文档目录

入门

方法论

判断一个设计好不好的九条原则和三条红线。

设计或改动 aiL 时按这些原则判断。每条后面有一个检验用的问题。

九条原则

1. 人的注意力是瓶颈

你只提出、决定、验收。会话、Client、worktree 都是实现细节:在一个 Desk 里看到全部需要自己处理的事,不用记哪件事在哪台电脑的哪个会话里。只在你要行动或用得上结果时打扰。

检验:这个设计让用户多记一件事、多看一个地方、多做一次操作了吗?

2. 双层:Router 判断,Worker 执行

Router 承接你的全部请求,只做选意图、选仓库、派发这样的轻判断。执行都在隔离上下文的 Worker 里。Worker 之间怎样往返,对 Router 透明。

检验:Router 为了这件事要读仓库的文件、要理解任务的内部吗?要,就交给 Worker。

3. 快慢路径:确定的交给代码

流转(下一步是谁、评审第几轮、何时结束、通知谁)、合入、归档、提交、记 Journal,都由引擎执行;模型只产出判断和内容。归属已定的往来直通:你对某个 Worker 的回答直接进它的队列,不经 Router。

检验:这一步的输出能由输入唯一确定吗?能,就写进引擎。

4. 拒绝多态:一个抽象,一套交互

一个抽象定义清楚一类实体和它的全部交互。同一抽象的实例可以取不同的参数,但所有实例对参数的解读相同。

检验:这次改动要写「除了 X」「仅当是 Y 时」吗?要,就先改抽象。

5. 上下文:隔离、关联、按需

Worker 启动在负责这件事的仓库里,一个上下文只做一件事。仓库之间只通过主仓的登记和稳定的 id 相连。常驻上下文(角色说明、Router 合同)只放每次都用得上的,其余给路径或命令,用到时再取。

检验:这段文字对读到它的每个 Agent 都有用吗?是每一轮都要用,还是给个路径就够?

6. 单一真源,状态与历史分开

一个事实只在一处维护:插件内容的真源是 Git 里的文件;任务与地图的真源是仓库里的任务记录;会话、运行、报告的真源是 Desk 的数据库。程序之间按字段交接,不从给人看的文字里解析状态。

检验:这个事实现在写在几个地方?改它要动几处?

7. 运行环境与上下文分离

上下文在 Git 里,能在任何一台电脑上重建。运行环境(二进制、Harness 与订阅、会话、数据库)可以整体替换。对 Harness 的依赖收口在 Worker 契约这一层窄接口上,它只用 ACP 公开的方法和事件。

检验:把运行环境搬到另一台电脑,除了安装和登录还要搬什么?Harness 升级一个版本,哪些地方会坏?

8. 异步,少触发轮次

派发立即返回,结果作为新消息送达,不等待、不轮询。能静默处理的不触发一轮,能合并的通知合并送达。运行中不插话:发给忙着的会话的消息排队。Worker 自己要等的事也一样:它报告多久后叫它,由引擎叫醒。

检验:这个改动让一次典型的运行多了几轮?

9. 用数据持续改进

运行中发生的事都记进运行流水,问题从统计和抽样里找。验证以终点为准:看模型实际收到了什么、用户实际看到了什么。

检验:这条改动引用了哪些运行作证据?

三条红线

  1. 一致抽象,零 work-around。 编排层看到的每个 Harness 会话都是同一个 Worker。不按 Harness 或实例名分支,不加特判、补丁标志位或临时绕行。各 Harness 之间的差别只有两个去处:写成 Harness 定义里的数据,或留在契约之外。某项能力装不进抽象时,先改抽象。
  2. Spec 驱动。 约定要变时先改 Spec,再改实现,同一次改动里同步。
  3. Prototype 先行。 关键的外部依赖先做最小原型,拿到实测结论再定正式方案。