<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/vercel-labs/zerolang) · [上游 README](https://github.com/vercel-labs/zerolang/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# Zerolang

**面向智能体的编程语言。**

Zerolang 是一种实验性的图原生（graph-native）编程语言，语义图（semantic graph）即程序数据库。人类提出期望的结果。智能体查询图、提交经校验的编辑，并证明结果。

> **安全警告**
>
> Zerolang 处于实验阶段。可能会有破坏性变更、粗糙之处和安全问题。请在隔离的工作区中运行，不要针对生产系统或敏感数据使用。

## 从需求开始

预期的工作流就是一次普通对话：

```text
build hello world for zerolang
```

智能体应使用编译器，而不是根据源代码文本猜测：

```sh
zero init
zero patch --op 'addMain' --op 'addCheckWrite fn="main" text="hello from zero\n"'
zero run
```

结果仍可作为文本投影（projection）进行审查：

```zero
pub fn main(world: World) -> Void raises {
    check world.out.write("hello from zero\n")
}
```

该 `.0` 文件是 `zero.graph` 的投影。人类可以阅读、审查它，并偶尔进行编辑。智能体通常应继续使用 `zero query` 和 `zero patch`。

## 程序数据库

传统的智能体编码循环将文本视为单一事实来源：

```mermaid
flowchart LR
    A[agent writes text] --> B[check]
    B --> C[format]
    C --> D[build]
    D --> E[inspect failures]
    E --> A
```

Zerolang 让智能体更贴近编译器：

```mermaid
flowchart LR
    A[agent queries graph] --> B[agent submits checked patch]
    B --> C{compiler accepts?}
    C -- invalid or stale --> A
    C -- valid --> D[agent runs task validation]
    D --> E[human reviews projection when useful]
```

图为智能体提供显式句柄：符号、节点 ID、图哈希（graph hash）、类型、效应（effects）、所有权事实、能力、导入、调用边和目标事实。编辑可以针对语义结构而非行范围。陈旧的图哈希、意外的字段值、无效的形状和类型错误会在写入存储之前失败。

## 目前已有的内容

- `zero.graph` 是图优先包的经校验编译器输入。
- `.0` 文件是人类可读的投影，而非智能体常规的编写界面。
- `zero patch` 应用经校验的图编辑，并拒绝陈旧或无效的变更。
- `zero query`、`zero inspect`、`zero check`、`zero test` 和 `zero run` 通过面向智能体的命令暴露编译器事实。
- `zero import` 和 `zero export` 明确投影边界，避免人类文本编辑与图悄然偏离。

## 安装

安装编译器：

```sh
curl -fsSL https://zerolang.ai/install.sh | bash
export PATH="$HOME/.zero/bin:$PATH"
zero --version
```

安装智能体引导技能：

```sh
npx skills add vercel-labs/zerolang
```

编译器为智能体打包了版本匹配的技能：

```sh
zero skills
zero skills get agent
zero skills get graph
zero skills get language
zero skills get stdlib
```

## 日常流程

对于大多数包级工作：

```sh
zero query
zero patch --op help
zero patch --op 'addMain'
zero check
zero test
zero run -- <args>
```

默认输入为当前目录。仅在你需要明确指定时使用 `.`。

当人类需要审查投影文本时：

```sh
zero export
zero verify-projection
```

当人类有意编辑投影时：

```sh
zero import
zero check
```

## 运行时目标

图优先（graph-first）模型应在不放松运行时目标的前提下减少智能体的猜测：

- Token 高效检查
- 低内存占用
- 快速启动与构建
- 低运行时延迟
- 显式能力（capabilities）
- 小巧、无依赖的产物

## 开发 Zerolang

构建本地编译器：

```sh
pnpm install
make -C native/zero-c
bin/zero --version
```

有用的检查：

```sh
pnpm run docs:build
pnpm run conformance
pnpm run native:test
pnpm run command-contracts
```

本地迭代：

```sh
pnpm run conformance:local -- --list
pnpm run conformance:local -- --shard 1/4
pnpm run command-contracts:local
```

文档请见 [zerolang.ai](https://zerolang.ai).