一个主动型 Coding Agent
是怎么被设计出来的

先想一个失败的场景。你给 agent 开放了一个 20 人的仓库。它很勤快：每条新 Issue 都评论，每个 PR 都总结，每天早上一份进展日报。技术上它全部做对了——但一个月后，团队把它关掉了。

为什么？因为一个能替整个团队做事的 agent，也能消耗整个团队的注意力。它发一条消息的成本不是 token，而是 20 个人各花 30 秒读它、判断它、决定要不要回它。当它说得比做得多，它就从资产变成了负债。

这句话听起来像口号，但它是可执行的判据：项目里每一个消息、通知、问题、设置项、面板元素、甚至一段文档，都要单独结算它的注意力成本。给不出超过成本的价值，就删掉。下面所有设计，都是这条公理的推论。

推论 A：对 agent 行为的五条约束

推论 B：对设计的四条约束

推论 C：责任在运维者身上

Agent 用的是团队每天都能看到的账号（GitHub 用户、飞书机器人）。它说的每句话都算在你头上，所以 docs/000 把责任写成四条操作纪律：从小处开始（短名单 + 只观察）、为更少噪音调参（提示词更短更严，而不是加更多消息去解释噪音）、不用它制造数量（批量 PR 和广播比不做更糟）、为它说的话负责（读它代你发的内容，错了去改提示词）。

整个系统只有一条主流水线。先用"公司前台"的类比记住它，再看精确定义：

为什么非得这么绕？三个设计上的"不得不"

领域模型只有五个核心概念（Source、Thread、Eval、Mandate、Subscription）和六个支撑概念（Trigger、Ticket、Assignment、Channel、Policy、Correlation）。判断某个需求该落在哪，只需要问一句：它更像哪个概念的属性？如果都不像，那它大概应该写成提示词。

核心概念与它们守住的事

"人"为什么不是领域概念

模型里没有 Principal，也没有 Membership，更不把飞书的 ou_… 映射到 GitHub 的 login。原因很实际：

• 一个人的身份，在 Trigger 里只是 Source 给的 actor 元数据；
• 允许名单是 某个 Source 的 Policy 的一部分，用的是那个 Source 自己的身份体系；
• "飞书的张三就是 GitHub 的 zhangsan" 这种跨源映射，是 提示词文本（一个 identities skill），agent 需要时读一下。

这样做的收益是：新增一个 Source 时，不需要设计一套身份对齐机制；代价是跨源识别靠自然语言，但那是团队的领域知识，本来就该由人写下来。

聚合边界：一次事务能改什么

这是整个项目最精妙、也最容易读错的部分。一条消息进入系统后，只有两种命运：

路径 B 为什么必须存在

如果每条消息都走 Eval，那么"再补一句说明"也要重新审批一次。这既慢又蠢：授权已经给过了，范围没变。所以设计成——订阅关系把后续消息直接送进工单，由执行器决定要不要做。代价是执行器可能越界，因此加了两道约束：

• 工单仍受自己的 Mandate 限制，范围外的事必须 交回（orchestrator_trigger_handback），交回后它才变成 Eval 的候选；
• 主 Session 收到 follow-up 通知，但在执行器拥有这条消息期间，它只能"停"，不能"接"。

强度（Strength）：只有两档，但判据很细

explicit 和 inferred 的区别不是礼貌程度，而是能不能绕过研判。explicit 请求由主 Session 直接路由（它已经是"人明确要求"）；inferred 候选必须走完整研判，并且在非 auto 模式下根本不接单。

接受模式：把"能不能自己开工"变成一个开关

准入表：三个格子，覆盖"谁 × 有没有 @ 我"

每个 Source 的 Policy 里有一张准入表。行是接收范围（飞书：每个配置的群、其他 @ 到的群、私信；GitHub：新 Issue、新 PR、评论、默认分支 CI），每行最多三个格子：

"没 @ 消息"的两个格子，只在 Source 能收到该范围全部消息时才开放（飞书群设成"全部消息"、GitHub 打开 receive-all 开关）。CI 结果没有发送者，所以它那一行只有最后一个格子。机器人不使用这些格子，它们走 bot 名单。

亲手试一次闸门

下面这个交互模型直接照搬 src/policy.ts 里 gate() 的判定顺序。改几个条件，看结论怎么变——尤其注意"名单内的人 + 没 @"和"名单外的人 + @"在同一个 Thread 上会得到不同结果。

Mandate：授权一旦发出就是常量

Mandate 记录五件事：策略版本、范围、强度、命中的规则、发送者在该 Source 的身份 + 接收方式（basis）。它不可变，全生命周期里只有三种操作能改变它：

恢复前校验（revalidation）查什么

此外，Source 必须仍然监听原来的 Thread——但不需要仍然接收该 Thread 的全部消息。这两件事被刻意分开了：监听是"能不能恢复"，收全量是"能不能产生新候选"。

策略版本：为什么要一个 hash

policyVersion 把三样东西哈希在一起：规则、接受模式、各 Source 的 Policy 部分（含 bot 名单）。它带来三个能力：

1. 每个 Mandate 记得自己是在哪个版本下被批准的——审计时能回答"当时允许这么做吗"。
2. 版本一变，运行中的 Eval 全部丢弃、Trigger 重新排队（旧判断不能用于新规则）。
3. 系统能算出哪些活工单受影响（policyEffects：它依赖的规则被改了/被关了、请求人不再有资格、主动接单被关闭），只通知这些，其余不发噪音。

工单从 open 走到 ended。但它没有一张 status 字段让你随时改——阶段是从事实推导出来的：有没有未送达的 Input、有没有待回答的问题、最新报告说了什么、Assignment 处于什么状态。代码在 src/core/stage.ts，只有 20 行。

这样做的好处很直接：不会出现"状态字段说是执行中，但其实早就在等人"的漂移。只要事实对，标签一定对。

七个阶段（从上往下读，第一条命中即胜出）

关键语义：person 阶段意味着没有人类输入就无法继续。而一条新的人类消息会把 blocked / failed 的工单放回执行器，于是它掉到下一个命中的阶段（通常是 working）。

亲手判定一次

执行器：一个工单 = 一个 Session + 一个目录

每个工单拿到一个名为 worker-<ticket id> 的 DSH Session，和一个以工单短名命名的目录（默认在 <stateDir>/work 下）。它使用 dsh-superagent-worker preset：不带"问人 / 展示 / 改 profile"这类交互工具，并且前台 shell 命令 5 秒后自动转后台。

最后这点很容易被忽略，但它其实是"注意力"公理在工程上的投影：如果一条 pnpm build 卡住 3 分钟，那么这 3 分钟里人的新消息进不来，判断就延迟了。转后台之后，worker 可以在下一步就收到新消息。

结束条件：PR 关闭，不是"我干完了"

理由：PR 的合并/关闭是外部世界的既成事实，比 agent 的自我评价可靠。而且关闭之后工单保留订阅，人再评论一句就能在同一个 Mandate 下唤醒它——不用重新审批。

还有几个边界：正在恢复 / 重试 / 已恢复的工作没做完时，关闭不会结束工单；执行器接手了一条人的跟帖但还没给出非 progress 的报告或结束 turn 时，也会等。合并或关闭的最终结果会给聊天渠道发一条通知（GitHub 自己在 PR 上已经显示了，所以不重复）。

失败与恢复：先存后做

整个系统有一条铁律：决定之后要做的事，先存下来，再去做。派工、投递 Input、转发报告、发消息，都是先写一条 effect 记录，提交后再执行。所以进程在任何时刻崩溃，重启都能接着做。

行为的大部分不是代码，是文本。所以这个项目把"提示词"当成一等配置来管理：可编辑、可覆盖、有版本、可比对差异、升级不丢。

团队真正要写的，只有三段

此外还能加 team skills（比如一个 identities skill 说明"飞书的谁对应 GitHub 的谁"），以及覆盖每一个内置片段。工具描述、通知文案、卡片格式不能改——它们留在代码里，因为改了会破坏契约。

系统提示词是怎么拼起来的

顺序不是随手排的。Policy 放最后，因为它在每次模型请求时都会重新生成——放最后，策略一变，前面的文本完全不受影响，缓存和审查都简单。

冲突时谁赢：五层优先

角色分离：主 Session 不写实现计划

两个角色的边界被写死在提示词和工具集里：

为什么路由备注要限 30 词？因为一旦允许主 Session 写实现计划，它就会开始猜；而猜出来的计划会被执行器当成需求，最后没人知道需求是谁提的。prompts/shared.md 里那句"worker 从原始来源和既有策略推导需求，而不是从路由者添加的指令"就是这个意思。

版本的三个不变量

1. 每次保存产生一个不可变版本，含完整配置、修订号、前驱、时间戳、来源（面板或工具）。恢复旧版或默认值同样产生一个新版本。
2. 保存要声明它基于哪个修订。冲突的保存被拒绝，但不会丢你的草稿。
3. Session 每次模型请求都读最新版本，同一个 turn 的后续步骤也是。保存不会重启、取消或唤醒 Session；宿主会记录每个 Session 用过哪些修订，执行器可以回看自己工作时的版本。

升级时不丢团队文本：每个覆盖记录自己基于哪一版内置文本。默认值变了，面板给它标上 Default updated（默认内容已更新），并排显示新旧差异，让团队选"保留我的"还是"用新默认"。没有覆盖的部分自动跟随新默认。

打开面板，只回答三个问题，而且是有顺序的：

六个 tab，与概念一一对应

七条原则（挑三条最容易被违反的说）

还有一条很实用的：标签说"等谁、要什么"，不说内部状态码。所以是"待验收 / 待回答 / 输入未送达"，而不是 READY_REVIEW / ATTENTION / DELIVERY_FAILED。这条规则让"看不懂这个页面"从设计问题变成了实现 bug。

这个系统天生是异步的：来源在轮询、模型在思考、shell 在跑、消息在重试。最容易出的 bug 是"两个地方同时改同一个状态"。它的解法不是加锁，而是结构上只留一个写者。

Runtime 与 Engine：组合根 vs 规则中心

Runtime（src/app/runtime.ts）是组合根，不含任何领域规则。它做的事：锁住状态目录 → 打开 Store → 构造每个组件 → 注册路由 → 跑 setup → 装 hook → 恢复被打断的 Assignment → 启动 pass 循环。构造失败就把 Store 关掉、把锁放开。

Engine（src/core/engine.ts）是规则的唯一入口。所有方法都是同步的，每条命令在一个事务里改完它的聚合；evaluateDue 为它改动的每个 Eval 或工单单独开事务。外部工作由 port 在事务内入队，提交后才执行。

五个 Part，一条单向依赖链

命名约定也统一了语义：请求用祈使句（stopTicket、bindThread，可能被拒绝），执行器回报的事实用过去式（assignmentStarted、deliveryFailed，不会被拒绝）。读方法名就知道这是"命令"还是"事实"。

Effects：把"要做的事"变成数据

六种副作用，各自有并发和退避策略。每个 kind/key 只有一行：重复入队同一个 key 会替换载荷并立即到期，但不改变队列顺序。

抛 Later 表示"延后但不算失败"（比如没有空闲 worker slot）——这是把"暂时做不了"和"做错了"分开的关键。relay 和 notice 保序：一条失败会挡住同类的后续。

一个状态一个写者

持久化：一个文件，九张表

<stateDir>/orchestrator.sqlite，只有 Store 打开它。Runtime 在打开前先拿目录锁，防止第二个进程迁移或写同一份状态。

生成列加索引的意义：一次 pass 只读"还有活的工作"，不会随历史增长而变慢。代价是旧记录永不删除，所以 trigger / disposition / decision、结束的工单、outbox 收据会无界增长——这是文档里明说的已知问题。

依赖规则：靠目录纪律保证架构

• src/core 不 import 任何外部模块（除了 Node 的哈希），也不做 I/O。所以领域规则可以内存里跑测试。
• src/sources 不 import src/app。来源是插件，不能反向依赖应用。
• 面板只从宿主侧 import 类型，加上几个纯值模块。
• 每个类只收到一个命名了它所用能力的窄接口（ExecutorHost、AssessorHost……），Runtime 只在这样的接口后面传自己。

看一个设计好不好，不要看它加了什么，要看它拒绝了什么、以及拒绝的理由能不能复用。docs/001-domain.md 专门留了一张"被拒绝的概念"表——这在项目文档里很少见，也是这份材料最适合拿来学设计判断的部分。

挑三条展开：如果当年选错会怎样

① 在 Subscription 上做准入检查

很自然的想法：既然每条消息都送到工单，那就在送之前查一遍"这个人有没有资格"。看起来更安全，实际会撕裂一个已经很脆弱的东西——上下文与授权是两件不同的事。

一条 CI 失败报告、一条同事的"我复现了"、一条 bot 的依赖升级提示，都应该让执行器看到（这是上下文），但它们都不该产生新权力（这是授权）。如果入口处统一检查，你要么把 CI 挡在外面（执行器瞎了），要么放它进来并赋予它某种强度（越权）。分开之后：扇出全部放行、授权仍然由 Mandate 兜底——一句话解决了。

② 策略变更时取消运行中的工单

直觉上"规则变了，正在做的事当然要停"。但停下来的代价是半成品：一个改了一半的分支、一个开着但没人管的 PR、一个已经 push 但没跑完 CI 的提交。这些半成品最终都要人收拾，比让它做完更贵。

所以系统只做两件事：把变更记录下来，把它作为一条 Input 投递给受影响的工单（告诉执行器"你依赖的规则变了/被关了/请求人不再有资格"）。执行器自己决定怎么收尾。撤销授权是"下一次"的事。

③ 从自由文本推断"在等人"

执行器写"我需要你确认一下用哪个方案"，看起来很明确，用正则或小模型就能识别——直到有人写"我不需要你确认了，直接合并"，或者"他之前问我，我已经回了"。

正确做法是让执行器通过结构化字段提问：一个 attention 对象，带一个问题、指向触发它的那条消息。这样"等待"变成一个可查询的事实，而不是一段需要解读的散文。凡是会影响状态机的判断，都不能来自自然语言解析。

docs/008-cookbook.md 用一个虚构的 webhook 队列把这件事讲完了。浓缩成一句：一个 Source 要负责四件事——翻译事件、定义接收与授权规则、提供回复与上下文、维护轮询循环。

先把映射定死（这一步错了，后面全要返工）

十一步清单

1. 把 Trigger / Thread / Actor / Channel / 接收范围映射到领域概念。
2. 写 SourceKind：schema（校验 + 默认值）、fields（自动生成设置表单）、health（声明健康条目）、必要时 facts。
3. 翻译事件成 Trigger：稳定 id、丢掉 agent 自己的消息、正确设置 human 和 addressed。
4. scope()：决定这个来源收什么。只允许依赖 meta 和配置，因为恢复校验会用存储的 meta 再调一次。
5. channel.send：每条消息只发一次（用 message.id 做幂等键），只在"永久不可能送达"时返回 gone。
6. threadContext：让研判能读到 Trigger 周围的会话（可选，但没有它研判就只看得到一句话）。
7. policy：allowed 名单 + 准入表的行；可选 bots、sync。
8. environment：给执行器注册变量（DSH_SUPERAGENT_<KIND>_…，不要放凭据）。
9. 插件入口 + 循环：等 ctx.ready、跟随开关、receive 之后才移动游标、逐条容错、上报 health、响应 abort。
10. 加构建入口、package.json 导出、cordis.patch.yml 的 insert（先 disabled）。
11. 照 tests/sources.spec.ts 写测试：真 Store + 假 CLI。

四个最容易做错的契约

这部分最值得学的不是命令，而是把 agent 当成一个有身份、有状态、有崩溃恢复的线上服务来对待。

四个隔离决定

setup 到底在检查什么

Setup 用与 worker shell 相同的方式探测 CLI，然后写出 worker 的运行环境：

• 命令 shim（<stateDir>/worker-bin，放在 PATH 最前面）：gh 指向 agent 的 CLI、lark-cli 指向 bot 的 CLI、被禁用的命令直接失败。shim 在运行目标前会先把自己所在目录从 PATH 里去掉。
• git 配置（<stateDir>/worker-gitconfig）：替换操作者的全局/系统 git 配置，把 agent 的 CLI 设为 github.com 的凭据助手，把 SSH 地址改写成 HTTPS，定义 LFS 过滤器，移除 GH_TOKEN / GITHUB_TOKEN。
• 这两个目录里出现不是它写的文件，setup 直接失败——防止有人在里面塞东西。

运维接口：退出码就是状态机

scripts/dsh-superagent start | status | restart 的退出码语义很克制：

于是每小时巡检可以写得非常短：0 保持沉默，2/3 只报告一次不要重启，只有 1 才重启（且 --respect-stop 会尊重"人主动停的"）。这套约定的价值在于——它把"要不要叫醒人"变成了一个确定性的判断，而不是靠巡检 agent 自己权衡。

升级与已知边界

• 升级前：等没有执行器在 turn 中 → 备份 orchestrator.sqlite → git pull && pnpm install && pnpm build → restart 并看 status。
• 被新版本迁移过的数据库，旧版本打不开——回滚必须用升级前的备份。
• 团队文本和覆盖片段会保留；没有覆盖的片段跟随新默认。升级后要检查标了 Default updated 的部分。
• 两个明确写在"开放问题"里的：信任边界（哪些 Trigger 字段可信）和部署隔离（把 agent 的 profile 钉在自己的 DSH 版本上）。

术语表（面板的 (?) 就是这个）

状态枚举

文件地图：从哪读起

五道自检题

先自己回答，再展开。答得出来，说明你真的读懂了这套设计，而不是记住了它的名词。