Agent 写作规范

核心原则

这个站点的作者默认是 Codex agent。规范的目标是让不同 agent 在不同时间写出的章节仍然像同一个系统：结构一致、证据可靠、可构建、可发布。

单一事实来源

文件	用途	agent 是否直接编辑
data/versions.json	教程版本、准确源码提交与内容目录	是
markdown/*.md、data/*.json	默认/最新版正文与元数据	是
versions/<version>/markdown/、versions/<version>/data/	冻结历史教程	仅在明确维护该历史版时
src/content/docs/versions/	Starlight 编译输入	不直接编辑
public/versions/、dist/	构建时公开副本	不直接编辑

写作流程

1. 从 data/versions.json 选择目标版本并核对精确 Git revision。
2. 从该版本的 chapters file 找到目标章节，阅读其 sourceFiles。
3. 在该版本的 markdownDir 修改正文；不要拿另一版本的行号直接复用。
4. 必要时更新该版本的 source map 与 progress。
5. 运行 pnpm run validate:sources，核对 revision、路径与行范围。
6. 运行 pnpm run build 生成所有版本页面。

章节结构

每个完成章节必须以 H1 开头，并且前两节必须存在：

# <章节标题>

## 0. 本章学习目标

## 1. 一句话讲明白

推荐继续使用这些章节：

• 2. 它在 OpenCode agent 中的位置
• 3. 生活类比
• 4. Java 开发者类比
• 5. 最小源码路径
• 后续源码深挖章节
• 最后一节复盘

证据要求

• 代码行为必须来自真实源码阅读。
• 关键判断要带文件路径，最好带行号。
• 不确定时写“不确定”或“需要继续验证”，不要补剧情。
• 类比只能辅助理解，不能替代源码事实。
• 每章必须明确自己的源码版本；历史版保持冻结，最新版路径、函数名和行号必须在对应 checkout 中验证。

风格要求

• 面向中文读者写作。
• 假设读者是 Java 开发者，正在学习 TypeScript agent 项目。
• 先给架构位置，再讲具体实现。
• 避免为了漂亮而牺牲准确性。
• Markdown 保持框架无关，不在 markdown/*.md 使用 Starlight-only 组件。

质量门禁

提交前至少运行：

pnpm run build

两个版本源码工作区存在时必须运行：

pnpm run validate:sources

构建成功代表：

• 章节 JSON 基本 schema 合法；
• 每个版本的完成章节有对应 Markdown；
• 完成章节包含最低限度标题结构；
• Starlight 内容能编译成静态 HTML；
• 搜索索引能随站点一起生成。