# AI 随行手册

> 一个文件，向 AI 模型讲清如何编写远地虚拟机的客户程序。下载它，交给你的模型，模型就会从本手册所讲的同一套规则起步。

面向远地虚拟机编写的代码，很多会由模型起草。一个从没见过远地虚拟机的模型，会写出一个看似合理的客户程序（guest）：使用 `std`，在每个循环里分配内存，顺手用上原子计数器，信任它的证明者提示（advice），还提交一个 `usize`。**AI 随行手册**是一个 Markdown 文件，预先载入防止这些错误所需的一切：客户程序是什么、硬性规则、SDK 完整的公开接口及其确切签名、可以照抄的模式、各种错误及其修复方法，以及一份审查清单。

[下载随行手册](https://apogee.gweb3networks.com/docs/apogee-ai-companion.md)
复制到剪贴板
[以纯文本打开](https://apogee.gweb3networks.com/docs/apogee-ai-companion.md)

## 如何使用

- **在对话中**：在描述你想构建的东西之前，先附上这个文件，或者把它作为第一条消息粘贴进去。
- **在编程智能体中**：把它保存到项目根目录，使用你的工具按惯例读取的文件名，例如 `AGENTS.md` 或 `CLAUDE.md`，或者把它加入该工具的项目规则。智能体随后会在每次会话开始时读取它。
- **用于审查**：让模型对照文件第 8 节的审查清单，逐行检查一个客户程序。

这个文件用 **MUST** 和 **MUST NOT** 来陈述规则，每条旁边都附有理由，因为对于明确且有解释的约束，模型遵循得比需要自行推断的惯例更可靠。

## 包含的内容

| 章节 | 内容 |
| --- | --- |
| 0. 给模型的指示 | 把规则当作硬性约束；绝不调用未列出的 API；证明不是零知识的 |
| 1. 客户程序是什么 | 目标、单个 hart、证明陈述的内容、程序身份、三个内存区域 |
| 2. 硬性规则 | 23 条规则：程序形态、32 位的 `usize` 和指针、bump 分配器、栈、对齐、原子操作、不存在的外部世界、证明者提示、公开值的限制、指令集、浮点数、溢出检查、成本 |
| 3. 布局与构建 | crate 模板、客户程序工作空间、构建命令、宿主机（host）优先的库拆分 |
| 4. 客户程序 SDK | 每个公开函数及其确切签名、运行时事实与内存布局、委托的运算，以及 vendored crate |
| 5. 模式 | 对照哈希检查证明者提示；Merkle 查询与状态转换；缓冲区复用；结构化的证明者提示；为会增长的输出使用摘要 |
| 6. 宿主机一侧 | 在模拟器中运行、性能分析、导出映像、证明与验证、高度与同时处理中的分片 |
| 7. 错误与修复 | 客户程序会遇到的每一种退出状态、致命错误和拒绝，以及各自的原因和修复方法 |
| 8. 审查清单 | 在给出客户程序代码之前要做的十一项检查 |
| 9. 基本事实 | 指令集、证明系统、安全级别、各项限制和实测结果 |

## 它着重强调的规则

随行手册重申了本手册的规则，其中有三条值得特别指出，因为模型最常在这些地方出错：

- **指针和 `usize` 是 32 位。** 主要在 64 位代码上训练的模型，会不假思索地序列化 `usize`。于是客户程序和宿主机得出的字节就不一致了。
- **堆从不释放内存。** 惯用的 Rust 写法随意分配内存，因为真正的分配器会把内存还回来。在这里，每一次分配在剩余的运行期间都是永久的，所以随行手册要求处处复用缓冲区、处处使用 `with_capacity`。
- **原子操作能编译，但不属于新的客户程序代码。** 支持它们是为了兼容现有的库。在单个 hart 上它们不同步任何东西，还会给证明增加一个电路族。

## 给直接阅读本文档的智能体

- [`/llms.txt`](/llms.txt) 以 Markdown 形式索引本站的每一页，供浏览网页的模型使用。
- [`/docs/llms-full.txt`](https://apogee.gweb3networks.com/docs/llms-full.txt) 是合成一个文件的全部英文文档，规范也包括在内。
- 每一页都有一个 **以 Markdown 查看** 链接和一个 **复制为 Markdown** 按钮，位于标题下方和右侧栏中。

英文是本文档的标准语言，随行手册在所有语言版本中都以英文发布：英文是模型遵循得最可靠的语言，也是规范的写作语言。