给 Agent 看的子系统文档,该怎么写?拆解 Magpie 和 DeepSeek Harness

Nexmoe 2026年10月14日

子系统文档只回答一个问题:改这块代码之前,必须知道什么?

Magpie 和 DeepSeek Harness(下称 DSH)都有 docs/subsystems 目录。思路相通,做法不同。Magpie 一页讲一块功能怎么跑,靠评审守;DSH 把流程和类型拆成地图与字典,靠脚本守。

本文先总讲子系统文档是什么、怎么管,再分讲两个项目各自的做法和特别之处。

材料固定在 Magpie 提交 f074996、DSH 提交 d743267。

一、子系统文档是什么

补上中间那层

README 讲怎么用,架构文档讲整体,注释讲函数。中间缺一层:一块功能横跨几个包,它管什么、不管什么、出错谁兜底,不属于任何一个文件。

人靠记忆和交接补这一层。Agent 补不上。没写进仓库的,它只能猜。

举个例子。Magpie 有些订阅从内置实现迁到了社区插件。迁移后报了个 bug,改哪边?看代码很难判断。provider-plugins.md 写了答案:

先确定归属,再决定修复位置。影响已迁移订阅的 bug,通常要改社区插件。只改内置实现,已迁移的用户收不到修复。

子系统文档装的就是这种事:代码里看不出,改之前必须知道。

一般长什么样

两个项目的做法有几处相同:

  • 按功能切,不按目录切。 一个子系统可以横跨多个包。
  • 一个子系统一页。 目录下放一个 README 做索引。
  • 页里写边界和契约,不抄实现细节。写到源码,只链文件和符号。
  • 一个事实只写一处。 别处链接过去。

落到仓库里,大致是这样:

AGENTS.md                   ← 入口:改之前先读哪页
docs/
└── subsystems/
    ├── README.md           ← 索引
    ├── gateway-routing.md  ← 一个子系统一页
    └── ……

分歧在一页装多少。可以把流程、约束、失败行为都装进一页,也可以把流程抽到架构文档,页里只留类型。Magpie 选前者,DSH 选后者。

二、子系统文档怎么管

文档写出来不难,难在一直对。管理要回答五个问题:

  1. 入口。 Agent 从哪知道要读?通常是根 AGENTS.md 里的一条指令。
  2. 规则写在哪。 写什么、何时改、怎么审,要有个地方定下来。可以集中在子系统 README,也可以分散到各份规范。
  3. 写什么。 每页必须有哪些内容。有没有模板,结构靠什么固定。
  4. 什么时候更新。 触发条件是什么。常见做法是:契约或类型变了,同一个 PR 改文档。
  5. 谁来守。 两条路:评审,或者脚本。

第五个问题最关键。评审能判断语义,但会漏;脚本不会漏,但只能查机械的东西,比如链接、配对、类型。

两条路有同一个盲区:检查守得住写下的,守不住没写的。 新加的契约没写进文档,脚本发现不了,只能靠评审。

Magpie 全靠评审,DSH 能写成脚本的都写成了脚本。下面分开看。

三、Magpie:一页讲清一块功能

11 份文档

Magpie 是本地网关,把各家编程 Agent 接到模型和订阅上。docs/subsystems 有 11 份文档加一个 README,约 2800 行。

子系统管什么
gateway-routing本地 LLM 端点:选上游、翻译协议、失败了换下一个
gateway-middleware插件里的 JavaScript,在网关里改写请求和回复
gateway-sessions把各 Agent 的原生会话和网关用量合成一个视图
providers-accounts三类上游:API provider、订阅账号、插件账号
provider-plugins订阅留在内置还是迁到插件,归属决定谁来处理
claude-subscription-bridge后续对话怎样找回上一轮的 Claude Code 进程
agent-wiring改写各家 Agent 的配置,接到本地网关
library把说明、MCP、skills、hooks 写进各 Agent 的配置文件
plugin-runtime内置插件的注册、启停和释放
gui-shell托盘、面板、窗口和 magpie web
sync-backup设置打包加密,经 WebDAV、S3 或 GitHub 同步

放在仓库里是这样:

AGENTS.md                     ← 入口
LESSONS.md                    ← 错题本,后面讲
docs/
├── code-standards.md
└── subsystems/
    ├── README.md             ← 索引,也是全部规则
    ├── gateway-middleware.md
    ├── gateway-routing.md
    └── ……(共 11 份)

一页长什么样

看 gateway-middleware.md,53 行。中间件是插件里的一段 JavaScript,在网关里改写请求和回复。

先看骨架:

# Gateway middleware
(一段定位:是什么,为什么跑在网关进程里)
## Responsibilities and sources of truth   ← 职责表,每行对到源码
## Runtime path                            ← 四步运行路径
## Constraints and failure behavior        ← 限时、失败放行、重载
## Verification                            ← 能直接跑的测试命令

逐节看。

先划边界:中间件跑在网关进程里,不在 Bun 插件宿主里。理由是它要处理每个请求、每个流式事件。

再列职责,对应到源码:

部分负责源码
Discovery识别哪些插件是中间件internal/plugin/middleware.go
Load and run编译、运行时池、限时、计数internal/middleware
Gateway只在 Agent 发来的请求上执行internal/gateway/middleware.go

然后是运行路径,有个坑:只有 Agent 发来的请求经过中间件。Magpie 自己发的请求,比如生成标题、路由分类、搜索和识图替身,中间件看不到。

最后是失败行为。onRequest、onResponse 限时 250 毫秒,onEvent 50 毫秒,加载 1 秒。钩子抛错、返回非法值或超时,请求原样放行。

验证一节直接给命令,复制就能跑:

go test -tags nogui ./internal/middleware
go test -tags nogui -run TestMiddlewareThroughGateway ./internal/gateway
go test -tags nogui -bench Event ./internal/middleware

读完 53 行,改中间件前该知道的都知道了。

流程、约束、失败行为都在这一页。这是 Magpie 的写法:一页自足。

怎么管:README 就是规则手册

入口在根 AGENTS.md 第一节:

修改有文档的子系统之前,先读它的设计参考,并核对链接的源码。准备或评审 PR 时,遵守同一页的文档更新、语义变化描述和评审规则。

它只领路。规则全在 docs/subsystems/README.md,44 行,前半索引,后半规则。docs/code-standards.md 也不重写,同样指过去。读完这一页,就知道怎么写、何时改、怎么审。

# Subsystem design references
| Subsystem | Reference |             ← 11 行索引
## Maintain a reference               ← 写什么、何时改
## Describe a PR's semantic changes   ← PR 怎么写
## Review a change                    ← 评审四步

写什么。 每页写职责与边界、权威来源、运行路径、状态转换、约束和验证命令,相关时写失败与兼容行为。没有模板。6 份用了同样的四节:职责与权威来源、运行路径、约束与失败行为、验证。另 5 份小节名各异,gateway-sessions.md 没有验证一节。

何时改。 看契约。职责、接口、状态、路径、兼容或失败行为变了,同一个 PR 改文档。纯重构不用改。

怎么审。 PR 写清每个受影响子系统的触发条件、改前、改后,附文档、代码和测试证据。

README 自己举了例子:改插件接管逻辑的 PR,要说明哪种迁移状态和账号条件会触发,接管前后分别由哪段实现处理请求,哪个测试覆盖这次切换。

评审分四步查:

  1. 找出受影响的子系统和真实路径,包括走插件还是内置。
  2. 对照代码,核对 PR 说的前后行为。
  3. 查文档是否更新,源码链接是否有效。
  4. 查测试是否覆盖,没跑的检查如实报。

兜底一句:只改文档证明不了实现,行为变了仍要测试或运行证据。

特别之处一:没有任何检查

没有脚本、CI 或 hook 查文档,测试只跑格式、静态检查和单测。全靠人。

人会漏。我让 Agent 解析了 11 份文档的 475 条本地链接,1 条失效:sync-backup.md 指向根目录的 webdav_cli.go,文件其实在 internal/cli/。

特别之处二:错题本

Magpie 有一份 LESSONS.md,记最近合并的改动错在哪、哪条规则本可以拦住。

它和子系统文档并列。AGENTS.md 要求改代码前读 LESSONS,改子系统前读对应文档。子系统文档写现在什么样,LESSONS 写最近错在哪。反复出现的教训升进 docs/code-standards.md。

错题本里有一例直接关于子系统文档。gateway-routing.md 曾写:网关不查 Host 头,解析到 127.0.0.1 的网页会被当成同源。这是 DNS 重绑定漏洞。文档写得一清二楚,漏洞却一直留着,直到评审时有人复现才修。由此多了一条规则:

文档点名的安全缺口,是一个没关闭的 bug,不是一段描述。写下这种句子时,在同一个提交里开 issue。

文档写得越准,越像问题已经解决。

Magpie 没有 ADR(架构决策记录)。提案在 issue 和 PR 里,子系统文档只写已实现的状态。

四、DSH:地图和字典分开写

66 个子系统

DSH 是全插件化的 Agent 框架,建在 Cordis 上。Cordis 是插件框架,插件靠它提供的服务和事件协作。

docs/subsystems 大得多。66 个子系统,每个有英文页、中文页和一份配对记录,加 README 共 201 个文件,平铺一层。

AGENTS.md                    ← 入口:改 packages/ 前读 architecture.md
docs/
├── AGENTS.md                ← 文档规范,分层表在这
├── architecture.md          ← 地图
├── architecture.zh.md
├── architecture.i18n.yaml
└── subsystems/
    ├── README.md            ← 目录,不放规则
    ├── README.zh.md
    ├── README.i18n.yaml
    ├── session.md           ← 字典的一页
    ├── session.zh.md        ← 中文版
    ├── session.i18n.yaml    ← 配对记录
    ├── tools.md
    └── ……(三件一组,共 201 个文件)

一页长什么样

没有统一模板,骨架固定:标题、语言切换、一段定位,多数接一行 Source: 指向源码;中间按类型分组;59 页以一段自动生成的 Cordis API 收尾,夹在生成标记间,不许手改。

看 session.md。开头两句划清边界:

Session 是一条只追加的类型化事件日志,是 Agent 全部交互历史的唯一事实来源。LLM 的消息历史从日志推导出来,从不单独存储。日志怎样持久化,归兄弟页 persistence.md。

再看标题,几乎每个都是类型名:

# Sessions
English | [中文](session.zh.md)
(定位段)
Source: packages/core/session/src/types.ts
## `SessionEventMap` — the event vocabulary
## `SessionEvent<T>` — one log entry
## Surface types
## `Session` public API
## Why a turn ended: `TurnEndReasonMap`
## Durability contract
……
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
## Cordis API
### `ctx.sessionController` — `SessionController`
### `ctx.sessions` — `SessionStore`
……

一轮怎么跑,这页不展开,那是地图的事。

类型块有标记。这段原样摘自 session.md:

```ts type-equiv
/** A user-role specialization of the shared message representation. */
interface UserMessage extends MessageBase {
  readonly role: 'user'
}
```

type-equiv 表示这段必须和源码里的定义一致,脚本会去比。类的公开接口用 ts public-api 标记。

页里没有流程。流程在另一份文档里,见下一节。

特别之处一:地图和字典

文档规范里有张分层表,写明分工:

  • architecture.md 讲组合:核心包、主循环、接缝、扩展点。不放类型,类型归子系统页;不放理由,理由归 Agent Notes。
  • 子系统页讲类型、语义和生成的服务接口。不写行为叙事,那归 architecture.md。

地图告诉你请求经过哪几站,字典告诉你每站的数据结构。

子系统目录的 README 也这么说:这里补充 architecture.md,那边讲跨子系统的行为,这边讲单个子系统的词汇和接线。

拿一次工具调用看。architecture.md 的轮次流程图,节选:

turn/start
  claim next-step input plus one queued message
  assemble prompt sections + tool schemas
  -> agent/pre-step
     step/start
     agent/request -> prepareCall
     stream the bound prepared call -> llm/stream
     tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*
     step/end
  -> agent/turn-stopping
turn/end

工具调用只占其中一行。

地图只交代三件事:它在一轮对话的哪个位置;哪些是写进会话日志的持久事件;哪些是插件能插进来的扩展点,监听者必须调 next() 往下传。更细的,给链接。

字典 tools.md 把同一次调用拆开:pre-execute 后有一层只能收紧的守卫;execute 后由 projectContent 把结果转成模型看的内容;post-execute 后还可能有工具自带的 finalizeContent。ToolDefinition、ToolExecution、ToolExecutionResult 的定义原样贴在页上。

想知道工具调用在哪一步,看地图那一行。想写新守卫、查某个字段何时填上,翻字典。两边不互相复述。

链接方向也一样。architecture.md 指向子系统页 13 条,反向只有 3 条。地图领路,字典讲站内。

地图要短,字典要全

architecture.md 有字数预算。规范的目标是 2400 个英文词,脚本上限 2410,超了 CI 失败。调研时它 165 行、2403 词,只剩 7 词余量。子系统页没有上限,session.md 一页 1337 行。

地图短才能读完,字典全才能查到。规范原话的意思是:别给穷尽型参考文档设全局上限,要看查一次得扫多少无关内容。

地图也会动。根 AGENTS.md 规定:新行为挂到已写明的扩展点上,不改主循环;真改 agent-loop,就同时更新 architecture.md。

怎么管:规则散在几份规范里

入口在根 AGENTS.md 第三行:改 packages/ 前先读 architecture.md,写文档按 docs/AGENTS.md 来。先进地图,再由地图链到字典。

子系统 README 只是目录:一段定位,一张每个子系统一行的表,再加类型块的写法。规则按一事一处,放在各自该在的地方:

规则写在哪
文档随每次代码改动更新根 AGENTS.md
子系统页写类型和语义,不写行为叙事docs/AGENTS.md 分层表
类型放子系统页,理由放 Agent Notesdocs/AGENTS.md 放置规则
改了类型,同一次改动更新页面docs/AGENTS.md
中英文成对更新docs/AGENTS.md、i18n 规范
每个包组 README 链到一个子系统页packages/AGENTS.md
参考文档不设字数上限,按好查来拆dsh-doc Skill

Magpie 的规则好找,DSH 的好维护。规则多了,挤在一页里会和别的规范打架。

写什么。 只要类型、语义和生成的服务接口。也没有模板,但类型块有固定标记,生成区有固定边界,结构由脚本卡住。

何时改。 看类型。改了已写进文档的类型,同一次改动更新对应页,中英文一起改。

特别之处二:脚本守文档

这是两个项目差别最大的地方。和子系统页相关的检查有五道:

  • 链接。 本地目标文件必须存在,#锚点 必须对上标题,中英文都扫。Magpie 那条失效链接,在这里会被拦下。
  • 类型比对。 每个 type-equiv 块和源码比,对不上就失败。字典不会悄悄过期,靠的是这道。
  • 翻译配对。 英文页和中文页的内容哈希、结构签名必须对上,见下一节。
  • 生成区。 文末的 Cordis API 必须和重新生成的一致。手改或忘了生成都会被发现。
  • 归属。 每个包组 README 至少链到一个子系统页。只查这一个方向,有 9 页没有包组链过来,不算违规。

检查分快慢两档。本地快检二十多项,含链接、配对、类型比对;完整检查再加归属和生成区。PR 的 CI 跑完整一套,只跳过文档代码的类型检查。本地漏跑的,合并前会补上。

脚本也有盲区。页里有没有混进行为叙事,内容放得对不对,靠评审。规范自己承认:类型比对抓得到贴错的类型,抓不到没写进文档的新类型。

特别之处三:中英双语

每页都有中文版和一份配对记录。session.i18n.yaml 开头是这样:

# Bilingual-pair consistency record for session.md (docs/i18n/README.md): per heading
# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
/sessions:
  en: 28fb7eb8f758fdf0
  zh: a36d6f03e331ad86
/sessions/sessioneventmap-the-event-vocabulary:
  en: 541354f6468e117d
  zh: 2d7a665bad828a02

每个标题一条,记中英两边的哈希,代码块和生成区不算。改完任一边,重新记录:

pnpm run verify-translation-pairing --write docs/subsystems/session.md

两边权威相等,标题层级、表格行列、代码块都要一一对应。英文改了、中文没跟上,配对检查就失败。architecture.md 也是这样三件一组。

这是 DSH 页数翻三倍的原因,也是它非靠脚本不可的原因。66 对页面,人工核不过来。

五、两种做法的代价

MagpieDSH
一页写什么一块功能怎么跑一组类型是什么
流程写在哪子系统页本身architecture.md
理由写在哪LESSONS;提案在 issue/PRAgent Notes
规则写在哪子系统 README几份规范和 Skill
更新时机契约变了,同一 PR类型变了,同一次改动
自动检查无链接、类型、配对、生成区、归属
主要风险链接和事实悄悄过期新类型和语义漏写

Magpie 直接。 一页 53 行,边界、限时、失败方式全有。代价是全靠人,链接坏了没人知道。

DSH 难过期。 类型不对、链接断了、中文没跟上,CI 都拦。代价是要跳着读:流程看地图,类型看字典,理由看 Agent Notes。

六、怎么起步

分两步。

先照 Magpie 写:

  1. 写个 README,列出子系统和各自职责,说明可以横跨多个包。
  2. 定下每页必写:职责与边界、权威来源、运行路径、失败行为、验证命令。Magpie 的四节可以直接抄。
  3. 在 AGENTS.md 写两条:改子系统前先读文档;契约变了,同一个 PR 更新。
  4. 定评审步骤:PR 写清前后行为,评审核对代码、链接和测试。
  5. 文档里写到的安全缺口,当场开 issue。

人守不住了,再学 DSH:

  1. 先加链接检查。成本最低,见效最快。
  2. 贴的类型多了,加类型比对,把文档绑到源码上。
  3. 子系统页开始混进流程,就把流程抽到架构文档里,一边做地图,一边做字典。

写什么,学 Magpie;怎么守,学 DSH。