Skip to content

Latest commit

 

History

History
516 lines (357 loc) · 49 KB

protocol.md

File metadata and controls

516 lines (357 loc) · 49 KB

共同协议(Common Protocol)

本文件是多 agent 协作的共同底座,全员必须完整遵守。 角色专属操作手册:architect.md / conductor.md / implementer.md / reviewer.md(项目实例中以部署路径为准)。 历史教训:anti-patterns.md。本协议源自项目 A 的协作规范 v1.5 及其实践演化。

每轮开工先确认工作区(§4),再执行角色手册。形态 C 或 Multica 托管任务必读 本地 worktree 工作流;托管任务先记录本轮起点,再做任何 Git 写操作。旧部署中的 A/B 标签不能覆盖实际拓扑与宿主分配。

1. 角色分工

角色 承担者 职责 专属权力
Owner 人类 方向决策;产品、界面、体验这类主观判断;花钱的事;读里程碑交付报告,裁决其中留给 Owner 的事项(§6.2、§7) 最终决策权;信道触发权(零内容搬运)。部署了 Conductor 时主要与它对话
Architect 设计能力最强的 agent 设计文档与 ADR;按里程碑批量出任务卡;裁决提案与阻塞;退回定性;里程碑收官评估;签发 Owner 交付报告 契约制定权、裁决权
Conductor(指挥,可选) 守流程可靠、说话清楚的 agent;能读懂代码的可开初审档(§1.3) Owner 的主要对话入口:听取意图、向各角色派工、用大白话汇报进展;派卡;卡级门禁(§2.3)并把通过的卡合入里程碑集成分支;初审档另做逐卡初审(不阻塞的改进意见与具体肯定);跨卡观察;backlog 状态;挂账;跟进没人接的事项;维护待 Owner 裁决清单;汇编交付报告的事实部分 派卡权、门禁退回权、集成分支合入权;初审档另有不带强制力的建议权;无契约权、裁决权、主干合入权
Implementer 执行细致的 agent 领卡后细化完成判据、实现、自检、交付;上报提案、阻塞与发现 红区以外的实现自主权(§6.1);无合入主干权
Reviewer(可选) 严谨的 agent,最好与 Implementer 异源 里程碑验收:卡全部集成后把整体实际跑起来;对抗档与取证档的卡逐卡验收;验收过的集成分支由它合入主干 验收权、主干合入权;无契约修改权

分工原则:做成什么、不能碰什么由 Architect 定;怎么做由 Implementer 定;交付齐不齐、门禁绿不绿、现在该谁动由 Conductor 盯(初审档还会提出改进意见,但不决定合不合);合起来能不能用由 Reviewer 实测后定。

内容链路与控制链路分开。内容链路是「设计 → 任务卡 → 实现 → 验收」,每一环都在转述或兑现设计意图;控制链路是「谁在做哪张卡、卡到了哪一步、下一步该谁动」。Conductor 只走控制链路:它不写卡面、不解释设计、不转述裁决。它把 Owner 的需求与反馈派给 Architect 时附原话,自己的理解另起一段并标明——原话在,就不构成有损中继。它做的卡级门禁也属于控制链路——对着清单核对、复跑命令、比对输出,结论不掺评价(§2.3)。初审档的 Conductor 可以对内容发表意见,但意见不带强制力、不改卡面、不转述设计:放开"说",不放开"判"。理由:设计与实现之间夹一个能力较弱的转述者,它就成了有损中继——出卡侧缺陷(anti-patterns.md「出卡侧」)连最强的模型都会犯,换人转述只会更多。消息直达当事方,Conductor 读全部消息,但不做中转站。

Architect 按需唤起,不常驻每张卡。它的工作集中在两头:里程碑开始时批量出卡,里程碑结束时收官评估;中间只在有事找它时出场(裁决、高风险卡的判据确认、退回定性,见 §2)。常规卡从派卡到合入可以全程不经过 Architect。理由:逐卡读代码审核在强执行者身上拦下的问题少于它消耗的往返。能机械判定的部分交给卡级门禁逐卡查,需要判断的部分集中到里程碑末——Reviewer 把整体跑起来,Architect 看结构并给每个问题归类(§7)。

可选角色的回落:

未部署 它的工作归谁
Conductor 派卡与记账归 Architect;卡级门禁与集成归 Reviewer
Reviewer 里程碑验收、逐卡验收与主干合入归 Architect(独立性收益不成立,其余照做)
两者都没有 全部归 Architect——本框架的双 agent 原形

部署了哪些角色在信道存档中声明。

Owner 不搬运内容:agent 之间的沟通全部走信道(§3),Owner 只用固定短语触发(如"看信道")。部署了 Conductor 时,Owner 主要和 Conductor 对话:控制类的事(先做什么、暂停、叫谁动)由它直接办;内容类的事(新需求、设计意见、主观反馈)由它带着原话派给 Architect;需要触发某个 agent 时,由它唤起或告诉 Owner 去触发谁(conductor.md §1)。Owner 也可以直接找任何角色,Conductor 不是关卡。留给 Owner 的事项按 §6.2 判定:阻塞当前工作的直接找 Owner;不阻塞的进待 Owner 裁决清单,随里程碑交付报告一并呈上(§7)。

1.1 代行与交接(限额 / 中断时)

agent 会因限额、上下文耗尽或模型切换而中断。没有代行协议,协作要么停摆、要么即兴处理,后者留下的是权责不清的半途卡。

谁可以代行:

中断方 代行者(按优先级)
Architect ① 另一个具备 Architect 能力的 agent(§1.2);② Reviewer(已部署时);③ 都没有 → 不代行,在途卡停在当前状态等原任回归
Reviewer Architect
Conductor Reviewer 或 Architect,谁在场谁接;控制链路与卡级门禁不需要特别授权

绝不由 Implementer 代行裁决、门禁或验收——自己裁自己、查自己、验自己的活,这几个环节的价值归零。Conductor 也不代行裁决与验收——它没有契约权,让控制链路顶替内容链路,正是 §1 要避免的有损中继。

代行期的权力边界:

权力 代行者 说明
裁决 L1 / 修订卡面 ✅ 即时生效且长期有效,不因原任回归而重审
出卡、派卡、按需审核 ✅
卡级门禁、合入集成分支 ✅
里程碑验收、收官评估 ✅
合入主干 视情况 见下方「主干合入需要两方都在」
push / 远程操作 ❌ 仍按项目既有的 Owner 授权规则,代行不放宽

主干合入需要两方都在(部署了 Reviewer 时):里程碑合入主干的前提是 Reviewer 的里程碑验收与 Architect 的收官归类(§7.1)——两件事由两个 agent 各做一件。代行期一个 agent 兼了两件时:

  • 卡照常做、照常过门禁、照常合入集成分支,开发不受影响;
  • 主干等:缺席方回归后补做它那一环,通过再合入;
  • Owner 明确授权「直接合」时可例外,授权写入信道。

为什么裁决算数、主干等一等:裁决是在途决策,停工中的实现方等不起,事后重审的代价是整条依赖链;主干是 Owner 看得到的基线,它等得起。卡都落在集成分支上,所以主干等待不阻塞任何一张卡。

交接对账:原任回归时,代行者在信道发一条交接消息,列全代行期的裁决编号、合入集成分支的卡、未闭合的 L1 与提案。原任据此接手,不重读全部历史。

半途卡不换手:正处在裁决 / 返工循环中的卡,由代行者主持到该卡合入集成分支,原任接回全局卡序与新卡。判据是证据链在谁手上——换手要求新任重读全部原始证据,收益为负。

1.2 角色的模型来源要记入存档

各角色可能由同一个模型的不同实例承担。同源实例的盲区是相关的——它们会在同一个地方一起看不见,而流程照跑、成本照付。部署时把各方的模型来源记入信道存档(SKILL.md 部署流程第 1 步),并按下表调整预期:

组合 后果
Reviewer 与开发两方异源 验收价值最高:测试路径、环境假设都与开发侧正交
Reviewer 与开发侧同源 验收仍有效——价值来自上下文独立和「真的跑起来」,与同源无关;重心放在实测,不靠读代码找 bug
Architect 与 Implementer 同源 出卡与实现的盲区相关;出卡自查(architect.md §1.3)要做实,验收要真跑
Conductor 的来源 不影响独立性——它不做内容决定;选型看守流程的可靠度与成本。开初审档时,与 Implementer 异源更有价值,同源的初审容易和实现方看不见同一处

两个 agent 异源且都具 Architect 能力时,互为对方的代行者(§1.1)——Architect 中断时协作不必停摆。

1.3 档位(执行者与 Conductor)

本协议正文按标准档写:假定 Implementer 是能独立读懂代码库、会主动核实事实的强模型,因此卡面薄、黄区先做后裁、交付报告精简。

Implementer 换成能力较弱或容易偏离的模型时,部署配置里把档位记为保守档,与该 Implementer 相关的环节叠加 保守档附录:黄区并入红区、Architect 写全完成判据、逐卡审核、体量预算、完整交付报告。档位按 Implementer 逐个登记,同一项目可以两档并存;改档由 Architect 在信道说明理由。

Conductor 也分两档,记入部署配置:

档 适用 做什么
基础档 只能可靠跑命令、比对输出的模型 对话与派工、派卡、门禁、记账、汇编——conductor.md 除 §4 外全部
初审档 能读懂代码、说得出具体理由的模型 基础档全部,外加逐卡初审与跨卡观察(conductor.md §4)

初审意见与门禁结论分开发、分开记:门禁结论只认清单(§2.3),初审意见不影响合入,实现方逐条回应"现在改 / 挂账 / 不采纳"(implementer.md §6.1)。Conductor 每个里程碑统计一次采纳率;连续偏低时 Architect 可以把它降回基础档。改档由 Architect 在信道说明理由。

档位只调节「补偿执行者能力」的那部分规则。协调类(单一事实源、确定 SHA、工作区安全、署名)、独立性类(实现者不裁决自己的卡、裁决与合入分属两方)、防加码类(§2.1 止损、§2.2 强度分档)与执行者强弱无关,两档都一样。

2. 任务生命周期

设计文档 / ADR → Architect 按里程碑批量出任务卡(目标 + 完成判据 + 本卡约束)
  → Conductor 按依赖顺序派卡
  → Implementer 领卡 → 细化完成判据 → 实现 → 自检 → 交付
       ↺ 黄区:提案并继续(L1-提案);红区:停在该点等裁决(L1-停)
  → Conductor 卡级门禁(§2.3):通过 → 合入里程碑集成分支;不过 → 退回 Implementer
       〔对抗档 / 取证档:合入前加一道 Reviewer 逐卡验收〕
  → 里程碑的卡全部集成 → Reviewer 里程碑验收(把整体实际跑起来)→ 问题清单交 Architect
  → Architect 收官评估与归类 ⇄ 补卡自迭代 → Reviewer 合入主干 → Owner 交付报告(§7)

三层检查各管一件事,不重叠:

层 何时 谁 回答的问题 靠什么
卡级门禁 每张卡交付时 Conductor 交付齐不齐、门禁绿不绿、判据有没有证据、改动面越没越线 清单、命令输出;结论不做判断(初审档另附不阻塞的初审意见)
里程碑验收 卡全部集成后 Reviewer 合起来到底能不能用、目标达没达成 冷启动的实际运行
收官评估 验收之后 Architect 结构偏没偏、每个问题该谁处理 设计判断

这样分的代价:常规卡在集成前没有人独立地把它跑起来试——门禁复跑的是实现方自己写的检查。"判据细化得太松""单看没问题、合起来不能用"这类问题要到里程碑验收才暴露,返工面更大。所以里程碑要切小,对抗档与取证档的卡不走这条捷径。

常规卡不经过 Architect。出现下列情况才唤起它(Conductor 负责发现并指给它):

触发 Architect 做什么
对抗档或取证档的卡,Implementer 交出了完成判据细化 确认判据后才开工(architect.md §4.1)
L1-提案 认可或否决;交付前没答复的随交付进入按需审核
L1-停 即时裁决,对方停在该点等
交付报告里标了「需 Architect 过目」的条目 按需审核,只看被标出的条目(architect.md §4.2)
门禁或逐卡验收的退回有争议;Conductor 拿不准某处算不算越线 定性(architect.md §5)
Reviewer 交来里程碑验收的问题清单 收官评估与归类(architect.md §6)

任务卡是唯一事实源:派活提示词与派卡消息只指向卡面路径,不复制内容。卡面写「做成什么」和「不能碰什么」,不写「怎么做」(architect.md §1.2)。运行相关的机械信息(分支、task_base、运行 ID、消息命名空间、集成分支)不进卡面,由派卡消息承载——批量出卡时这些信息还不存在。

完成判据分两层:Architect 在卡面给出少量有区分力的判据,回答「什么算做成」;Implementer 领卡后在卡面旁的细化文件(<卡 ID>.checks.md)里补全可执行的细化(具体输入、命令、预期)。细化单独成文件,是为了让卡面始终只有 Architect 一个写入者——同一个文件两方各改一半,裁决修订卡面时就会撞车。卡级门禁复跑的是细化;里程碑验收以卡面目标与 Architect 的判据为准,细化只是参考——细化比目标弱,在里程碑验收时照样过不了。

2.1 审核与验收的止损

打回/退回循环没有自然终点:每一轮都能挑出东西,而挑出东西不等于值得挑。"再看一眼总没坏处"是这个环节最主要的失效方式。 本节同样约束里程碑收官的自迭代(§7)。

  • 一次给全:审方一次性给出全部问题,不挤牙膏;
  • 只退回有依据的:指得到卡面目标 / 完成判据 / 约束某一条,或是可复现的缺陷 / 主干回归(§6.3)。写法偏好、命名风格、"我会写得更好"一律作为建议附上,不构成退回项;
  • 轮次封顶:门禁退回同一项连续 2 轮不过、逐卡验收退回 ≤2 轮仍不过,都交 Architect 定性(返工、改卡或接管重写);Architect 与 Reviewer 对定性有分歧才提交 Owner。收官自迭代 ≤2 轮,剩余问题如实写进交付报告;
  • 三个越线信号,出现任一条立即放行或升级:
    1. 本轮问题里,多数是上一轮返工产生的——已经在自己制造工作;
    2. 问题开始集中在表述、命名、体例——有依据的问题已经审干净了;
    3. 一张卡累计的门禁、验收与按需审核耗时超过它的实现耗时——投入产出已经倒挂。

审方与被审方都有义务喊停,不是只有被审方能喊。

2.2 验收强度分档

强度由"这段代码面对谁"决定,不由"它有多重要"决定。 出卡时在卡面标一档,backlog 同步。

档 适用 威胁模型 验收动作
常规 只处理项目自己产生的输入:工程基座、内部 schema、状态机、计算逻辑、内部工具、CI 写错了 跑通门禁 + 正反例测试 + 目标与 DoD 实测达成
对抗 处理外部或不可信输入:用户上传、第三方 API 响应、网络数据、渲染进用户界面的内容、安全边界本身 被攻击 常规全部,外加恶意输入矩阵、边界绕过、失败关闭证明

多数项目里对抗档只占少数几张卡,出卡时就要点名是哪几张,不要留给验收时临场判断。对抗档的卡过了卡级门禁之后,先由 Reviewer 逐卡验收再合入集成分支——它面对的是攻击者,等不到里程碑末。常规档的卡不做逐卡验收。

判据是一个具体问题:谁会攻击这段代码? 一个只有团队自己会改的内部文档检查脚本,答案是"没人"——给它设计"有人故意插入诱饵内容骗过检查"这类反例,是在虚构一个不存在的对手。反过来,处理用户上传文件的解析器答案是"任何拿到上传口的人",恶意输入矩阵一条都不能省。

给常规档做对抗验收不是"稳一点"。 它挤占的是真正需要对抗验收的那几张卡的预算,而且会让常规卡的体量翻倍——被审方为了通过而堆防御代码,审方为了发现问题而构造更刁钻的场景,双方都在加码,没有终点。

改档由 Architect 在信道说明理由并更新 backlog,Implementer 与 Reviewer 不自行升降。

取证档(正交于上面两档,不是第三个强度)

上面两档问的是「谁会攻击这段代码」。当卡要修的缺陷根因未知时,还要问第二个问题:「根因是不是已经由证据闭合?」 答案为否时,这张卡的产出是证据,不是修复——它与常规/对抗档正交,两者都可能同时叠加取证档。取证档的卡同样由 Reviewer 逐卡验收:证据闭没闭合需要判断,卡级门禁判不了。

项 取证档的差异
完成判据 不是「缺陷已修复」,而是「根因已由证据闭合,且证据形态满足卡面列举的 N 项」
交付物 诊断代码 + 原始证据;诊断代码可以是一次性的(测试态、取证后删除)
硬边界 证据闭合前禁止进入生产修复,包括「顺手改一下」
分阶段 证据若需多轮才拿得到(必须跑特定平台、特定负载、远程环境),按阶段冻结:每阶段独立 checkpoint,上一阶段证据不闭合不进下一阶段

为什么值得单列一档:跨平台、并发、环境相关的缺陷几乎都是这个形态,而它们最贵。跳过取证直接修,写出来的是**「在错误根因假设下恰好让测试变绿」的修复**——门禁不会告诉你这件事,它只会变绿。

出卡时若根因写的是推断而非实测,卡面必须明说这是推断,并把「实测根因与推断不符即 L1-停」写进卡面约束;否则实现方会把推断当契约照着实现。

2.3 卡级门禁

每张卡交付后、合入集成分支前,Conductor 对着下面这张封闭清单逐项核对。清单以内的不过就退回;清单以外的意见不进退回项——初审档写进初审意见(conductor.md §4),基础档不提。

# 检查 怎么判
1 交付完整 交付报告三节齐全(implementer.md §5);delivery_sha 可达且包含 task_base;C / 托管任务 guard check 通过
2 判据有落点 卡面每条完成判据,在细化文件里都有对应的检查,且交付报告给了通过的证据
3 复跑一致 在合并态(集成分支最新 + 交付)全量跑项目门禁命令表;逐条重跑细化里可执行的检查(已经落成自动化测试、被门禁命令表覆盖的,核对测试存在且通过即可,不单独重跑)。结果与交付报告一致,留命令与输出
4 改动面 task_base..delivery_sha 的改动里:没有删减既有测试;没有碰卡面明令禁止的路径;依赖清单、CI/workflow 文件有变化的都有对应提案
5 挂起事项清零 所有提案都有答复;「需 Architect 过目」的条目都有答复;对抗档 / 取证档的卡已有 Reviewer 逐卡验收通过
  • 通过 → 合入里程碑集成分支,更新 backlog,派下一张;
  • 不过 → 退回 Implementer,写明清单第几项、跑的命令、实际输出。不写"建议怎么改";
  • 合并冲突 → 退回 Implementer 同步基线后重新交付。Conductor 不解冲突——解冲突是在改代码;
  • 拿不准某处改动算不算越线(第 4 项里机械判不了的)→ 不判,指给 Architect。

门禁结论不掺判断:不因实现好坏、细化够不够严、代码结构而退回,不做探索性测试。这些分别属于里程碑验收与收官评估。门禁的价值在于它便宜、每张卡都做、结论不靠口味;一旦掺进判断,退回就失去了依据。

初审(初审档):与门禁同时做、同一条消息发出,但另起一节。每卡最多三条意见,类型为疑似缺陷 / 改进 / 存疑(标明该谁判),外加至多两句具体的肯定。初审意见不阻塞合入:门禁通过就合;实现方选择"现在改"的,以一次追加交付处理,不算退回轮次。这样分,门禁仍然便宜可靠,而每张卡又多了一双读过代码的眼睛——Reviewer 不做 code review,Architect 只在收官时看结构,逐卡读代码的空档由初审补上。

3. 信道协议

形态 A/B 默认通过项目仓库内的单文件信道异步通信(默认 docs/collab/channel.md)。本节的单文件追加、全局编号规则适用于串行发言。

形态 C 使用独立消息文件(默认 docs/collab/messages/<task>/<run-id>/<seq>.md),部署配置中登记发送分支,按确定 SHA 读取;用唯一消息 ID、in_reply_to、ack 表达引用与已读,不使用共享 index 或全局 #N。旧 channel.md 保留为历史归档。具体收发步骤与模板见 本地 worktree 工作流。平台消息入口可作通知,不会自动替代文件交付。

3.1 基本纪律

  • 只追加:消息永不修改、永不删除。

  • 写入方式:追加自己的消息一律用仅追加写入(如 cat >> <信道文件> <<'EOF' ... EOF,或等价的"文件末尾插入"),不用需要整篇读入重写、或对全文做模糊匹配的工具动这份文件——文件随协作推进越来越长,整篇重写/模糊匹配在长文件上容易匹配错位或误伤历史消息,物理上保证"只追加"落到实处,而不只是口头纪律。

  • 写入点只能由工作区文件本身决定,不能用任何 git 视角。形态 A 下"自己的消息不 add"(§3.3)使暂存版与 HEAD 版永远短于工作区文件——照它们判断末尾,就会把消息写到别人未暂存消息的前面。git diff HEAD -- <信道文件> 只用于读增量,绝不用于定位写入点。

  • 写入后自验(强制):上面两条是禁令,禁令依赖执行者记得;这三条是当场能发现的断言,追加完立刻跑,任一条不过就地修正:

    tail -3 <信道文件>                              # 你的消息必须在物理末尾
    grep -c '^### \[#<N>\]' <信道文件>               # 必须为 1(标题前缀按项目实例调整)
    git diff -- <信道文件> | grep -c '^-[^-]'       # 必须为 0:没动过任何历史内容
  • 万一写错位置:已写入的消息保持原地不动。重排违反只追加;重发会制造重复编号,那比错位更糟——编号唯一性是引用的基础,而物理顺序错了还能靠编号还原。正确处置是在下一条消息的元信息里注明「注:#N 物理位置早于 #M,按编号读」。只有内容不完整或被截断才需要重发,且必须用新编号,正文说明它是哪一条的完整重发。

  • 编号:消息编号 #N 全局严格递增,回复引用编号(如"就 #12 的 L1")。

  • 元协议豁免:信道消息豁免任务卡的范围限制;形态 C 仅允许在本方消息命名空间新增文件,不能借此改他人消息或部署配置。

  • 单一事实源:信道里不复述卡面/文档内容,只给路径与结论。

3.2 消息格式(多方寻址)

## #N | <发件人> → <收件人> | <日期> | <主题>
> 抄送:<角色,无则写"无"> | 已读至:#M | 下一步:@<角色>
  • 收件人唯一——是这条消息要求动作的那一方;需要知情但不需要动作的一律写进抄送。
  • 已读至:#M:声明本方已读到的最高编号。多方场景下这是唯一可靠的已读水位线(见 3.3)。
  • 下一步:@<角色>:明确下一个该动的人。Owner 读最后一条消息即知道该触发谁,不必回溯全流程。
  • 消息类型:派卡 / 技术问答 / 完成判据细化(待确认)/ L1-提案 / L1-停 / 裁决 / 交付报告 / 门禁结论 / 按需审核结论 / 逐卡验收结论 / 退回 / 定性 / 里程碑验收(台账与问题清单)/ 收官评估 / 收口通知 / 形态探测。

3.3 已读机制(先按工作区形态分流)

以下 staging 回执只适用于形态 A 的同一 index。形态 B 在已提交消息中显式写 已读至;形态 C 用 ack 列出实际读过的消息 ID。不同 worktree 的 git add 不会通知对方。

  • 两方:git add <信道文件> = 已读回执——只 add 含对方消息的状态,自己写的消息不 add(留给对方 add 作回执);回复对方之前先 add 对方消息。
  • 三方及以上:git add 是单一全局状态,表达不了"谁读了"——主收件人一 add,抄送方的未读增量就从 git diff 里消失了。故:
    • git add 语义收窄为主收件人的已读回执,只有 → 指向的那一方 add;
    • 抄送方不 add,且读增量必须用 git diff HEAD -- <信道文件>(而非 git diff——后者看不到已被主收件人 staged 的消息);
    • 真正的已读水位线是元信息行里的 已读至:#M,每方发言时如实声明,不依赖 git staging 状态。
  • 提交时 git commit 也必须带 pathspec——git add <路径> 精确暂存还不够:不带 pathspec 的 git commit 提交的是整个 index,而形态 A 下 index 里往往有对方 add 的信道回执(上面这条协议要求的动作),于是你的一次文档提交会把别人的已读状态连带提交进去。写成 git commit <明确路径…>,或提交前跑一次 git diff --cached --stat 确认 index 只含你要提交的文件。
    • 误提交时先确认工作区与运行起点。非托管形态 A 只有在确认无他人现场、且该提交未交付时才考虑回退重提;托管任务追加更正,不得套用 reset --soft HEAD~1 改写起点。仅取消暂存的 git restore --staged <路径> 不移动 HEAD,与历史回退不同。
  • 例外:合入收口时合入者可将信道记录一并 commit。

4. 工作区形态(A/B/C)与宿主约束

工作区拓扑与宿主管理是两件事。部署配置分别记录形态 A/B/C和管理者 manual / multica;同一项目可同时存在共享源目录与多个任务 worktree,按实际参与者安排分流。

集成分两级,每级只有一个集成人:卡级集成人把过了门禁的卡合入里程碑集成分支(默认 milestone/<里程碑>,从主干拉出),默认是 Conductor;主干集成人把验收过的集成分支合入主干,默认是 Reviewer。未部署时的回落见 §1。后续卡的 task_base 取集成分支上的确定 SHA,不取主干。下文"集成人"按所在层级取对应角色。

里程碑进行中,文档类提交也走集成分支:Architect 修订卡面与设计文档、Reviewer 的验收台账、交付报告,各自在本方分支提交并给出 SHA,由卡级集成人合入集成分支。纯文档改动不过门禁,集成人只核对改动面确实只有文档。这样主干在里程碑期间保持上一次验收过的状态,读卡面一律按消息给出的 SHA,不按"主干上的最新版"。

形态 A:共享本地工作区

两个 agent 读写同一个本地目录。未提交的变更互相可见;信道消息写入文件即送达。

  • 切分支 / merge / checkout / reset 之前,必须确认其他方无未提交现场(信道询问或 Owner 确认)——这类操作会摧毁对方工作区状态,是 A 形态第一铁律。
  • push 只按 Owner 明确要求执行(收口时按项目惯例)。
  • 消息交付无需 commit;各自的消息随各自的下一次正常提交入库(Architect 随文档提交,Implementer 随任务分支提交,merge 汇流)。

形态 B:分离工作区

各自 clone,一切经 commit + push 可见。

  • 信道消息必须 commit + push 后才算送达;读前 fetch,用远端的确定 SHA 读取。更新当前分支时显式选择保留本轮起点的方式,不用可能隐式 rebase 的裸 git pull。
  • 交付 = push 任务分支 + push 信道消息;领卡前先拉取主干最新。
  • 无"对方现场"问题,但远端分支是唯一事实,本地状态不作数。

形态 C:本地并行 worktree

  • 各自 toplevel / git-dir 不同,git-common-dir 相同。工作文件、index、HEAD 独立;对象库和普通分支引用共享。别人的提交可直接按 SHA 读,未提交文件和 staging 回执不可见,不需要为了本地交付 push。
  • 每个运行只写自己的 worktree 与分支。共享引用意味着不能强移、删除他人的分支,也不能用 git -C <源目录> 修改源工作区来绕过本方约束。
  • 并行卡分配独立分支与消息命名空间,范围在卡面列明,基线与依赖在派卡消息列明。已授权依赖可按确定 SHA 合并进自己的任务分支;这是基线同步,不是合入主干,后者仍归集成人。
  • 交付包含 task_base、run_start、delivery_sha 和本地验证证据。审核与验收都固定到交付 SHA;集成人串行集成,不以移动中的分支名代替已验收提交。
  • 配置、消息、验收与收口操作见 本地 worktree 工作流。

Multica 托管任务(叠加在实际拓扑上)

  • 使用平台已分配的目录、分支和 HEAD 状态,不按模板重新建分支、切 main、重建 worktree。每轮在任何 Git 写操作前执行 guard start,冻结 run_start;它不是任务最初的 task_base。
  • 交付 HEAD 必须包含本轮起点:git merge-base --is-ancestor <run_start> HEAD 必须成功。默认追加提交;不 amend 起点或更早提交、不 rebase 掉起点、不 reset 到其历史之外。平台的 baseline/checkpoint 提交即使说明不符合署名规范也保留原样。
  • start 同一运行只能捕获一次,上下文恢复与重复检查使用原 run_id。真正的新一轮使用新的运行 ID,不能为了让检查通过更换 ID 或覆盖记录。
  • 分支交付、平台记录成功、主干集成是不同状态。平台记录成功前不清理任务分支/worktree;托管资源由平台回收。失败时保留起点、交付 SHA 与现场,按参考文档诊断。

集成与验收用的工作区(形态 A 下二选一,记入信道存档)

门禁要在合并态复跑、合入集成分支;验收要实测、最后合入主干——在共享工作区里这会和 Implementer 正在做的下一张卡互相污染。两种解法,Conductor 与 Reviewer 各自选定:

  • A-共享:各方同目录。交接铁律——开始门禁或验收前确认交付现场已 commit 到任务分支,切分支与合入期间其他方不动工作区。零额外设施,靠纪律约束;卡多时会频繁打断实现方。
  • A-独立:用独立 worktree 或 clone 做门禁与验收,不碰共享工作区。它与其他方之间的通信须分别按 C 或 B 交付,不能继续使用共享 index 回执。推荐,门禁每张卡都要切到合并态。注意:worktree 里的 .git 是文件而非目录,挂载、拷贝进沙箱时须保留它引用的 Git 元数据可达性。

形态 B 下各方各自 clone,天然无此问题。

形态确定方式

  1. 读取宿主本轮分配与项目部署配置;旧标签与实际不符时由配置维护者修订,其他角色报告差异并保留现场,不能靠切分支或 reset 把现场改成文档声称的样子。
  2. 各方执行 git rev-parse --path-format=absolute --show-toplevel --git-dir --git-common-dir(已部署 guard 时也可用 inspect),比对规范化路径与所在机器:同机同 toplevel/index 是 A;同机不同 toplevel、相同 common-dir 是 C;独立对象库的 clone 是 B。不同机器上的同名路径不代表共享仓库。
  3. 拓扑确定后验证消息通路:A 读未提交标记;B 从已 push 的确定 SHA 读;C 从另一任务分支的确定 SHA 读独立消息。读不到未提交消息不能据此判 B,也不自动授权 push。
  4. 将拓扑证据、管理者、消息分支、集成人与主干入口记录在部署配置中。无法确认的参与者按未知处理,先只读核查,不操作其工作区。

5. 实施反馈分级(L1 / L2 / L3)

实施中主动报告发现是任务的一部分,不是可选动作。

级别 定义 Implementer 的动作
L1-停 要做的事落在红区(§6.1),或卡面目标按写无法达成且没有一个可回退的做法 停在该点,信道上报 Architect,附首选方案;卡内不受影响的部分继续做
L1-提案 要做的事落在黄区(§6.1):超出纯实现决策,但做错了回退只影响本卡 信道发提案(选了什么、为什么、怎么回退),按首选方案继续做,相关改动单独成 commit;被否决则回退
L2 缺陷发现 设计/文档的错误、隐患、遗漏场景,不阻塞当前卡 继续实现,随交付报告提出;若会让当前实现方向性做错,升级为 L1
L3 改进建议 更优的库、更简的实现、体验或工程化改进 在卡面范围内且属绿区的直接采用;超出的只作建议

统一反馈格式(每条独立成项):

[L1-停/L1-提案/L2/L3] 现象:<撞上了什么,一句话>
影响:<影响哪个文档/模块/后续任务>
证据:<报错原文/官方文档链接/复现步骤>
方案:<L1 必填你的首选方案,提案另写回退方式;L2/L3 可空>

为什么提案不停工:源项目里五次 L1 停工的实现侧首选方案与最终裁决 5/5 一致——裁决零信息增量,等待却是实打实的。提案把顺序倒过来:先按首选方案走,Architect 保留否决权。代价是偶尔要回退一段,所以提案只用于回退成本封在本卡内的事。

提案的收口:Architect 在交付前答复的,按答复执行;到交付仍没答复的,Implementer 在交付报告里列为「未答复提案」并标「需 Architect 过目」,该卡合入前必须有答复。提案不会因为没人看而自动生效。

Architect 对应义务:L2/L3 每一条都要有归宿(采纳→改文档/开卡/挂账;否决→给理由)。归宿可以攒到里程碑收官时统一定(§7),由 Conductor 先挂账到 backlog 可见位置;会影响在途卡的 L2 不能攒。

裁决改了目标、判据或约束时,直接修订卡面并在裁决消息里点名改了哪一处;Reviewer 按最终卡面验收。

6. 决策权分层

一件事由谁定,看两个问题:做错了回退要动到谁,以及有没有客观依据能判对错。

6.1 实现期三区(Implementer 侧)

背景:早期 L1 一律停工,而五次停工的实现侧首选方案与最终裁决 5/5 一致。先是把"必然配套"下放成绿区,再把绿区从枚举改成"红区以外都是";现在在两者之间加一层黄区,把"需要第二双眼睛但等不起"的事改成先做后裁。

区 判据 动作
绿区 为达成卡面目标所做的实现决策,回退只动本卡自己的代码 直接做;值得知道的在交付报告披露
黄区 超出纯实现决策,但回退仍封在本卡内,不影响已验收产物、其它在途卡和用户 L1-提案,继续做(§5)
红区 回退会外溢到本卡之外,或本身不可逆,或属于 Owner 裁决域(§6.2) L1-停,等裁决

绿区举例:代码结构、模块内拆分、算法与数据结构、内部命名、错误处理方式;测试的组织与写法、fixture、纯测试/类型工具类 devDependencies;达成目标必需的配套改动,包括卡面没列到的相邻文件、已授权依赖引发的 lockfile 变更;卡面「上下文指针」里的参考做法——那是参考不是指令,有更好的做法可以换。

黄区举例:新增运行时依赖;调整本卡新引入、尚无其它已验收产物消费的接口形状;CI/workflow 结构调整;卡面与仓库实际不符时择一种解释往下做;为达成目标必须顺带做的、卡面没写的相邻小功能。

红区(穷举,一律停):

  • 安全边界(进程执行、文件系统范围、网络访问、鉴权);
  • 删减既有测试覆盖;
  • 修改已验收的跨批产物,或已被其它产物消费的公共契约(DTO、schema 语义、包导出面、设计文档定下的跨模块接口);
  • 与 ADR 或既有裁决冲突;
  • 卡面「本卡特有约束」明令禁止的内容;
  • 取证档证据闭合前改生产代码(§2.2);
  • 落在 Owner 裁决域的事(§6.2)。

拿不准在哪一区,就问回退成本:假设这个决定是错的,撤掉它要改哪些东西?只改本卡分支上的东西是黄区,提案后继续;要动主干、别人的卡或已经给到用户的东西是红区。不要因为拿不准就停——那是把协议退回一律停工。

绿区的义务是披露,不是申请:交付报告列出值得知道的决策——偏离了卡面参考做法、碰了卡面没列的文件、新增 devDependency、有明显取舍的设计选择——每项一句理由。常规实现细节不必报。

最严重的违规没有变:发现了更好的契约、或要越过红区,而直接改了。这类发现的价值在于进入裁决流程,不在于绕过流程的"好心"。

6.2 哪些事留给 Owner 裁决

默认是不留。 实施、验收、收官过程中发现的问题,只要有客观依据且修法清楚,就由 agent 自己改完,Owner 在交付报告里看到的是已经修好的结果(§7)。留给 Owner 的只有下面这些:

类别 判据 例子
产品方向与范围 会改变"这个产品做什么、给谁用、先做什么" 增删功能、调整里程碑目标、砍掉或推迟某个需求、改变默认行为的产品含义
主观体验 好坏取决于口味,文档里没有可判定的标准 界面布局与视觉、交互手感、文案语气、用户可见的命名
已批准的契约 要改设计文档或 ADR 里 Owner 认可过的契约或决策 公共 API 形状、数据模型语义、更换技术选型
代价落在 Owner 身上的取舍 几个方案都成立,区别在于谁付什么代价 性能换成本、工期换完整度、兼容旧数据还是迁移
花钱、对外、不可逆 产生费用,或动到仓库以外的世界 付费服务、对外发布、删除用户数据、项目惯例之外的 push
僵局 Architect 与 Reviewer 对定性的分歧两轮未解 —

不属于 Owner 裁决域、应当自己迭代掉的:

  • 有依据的缺陷——指得到目标、判据、契约某一条,或可复现的崩溃、回归;
  • 设计文档里的事实性错误且只有一种正确改法(文档写的 API 不存在、两处互相矛盾而其中一处明显是笔误)——Architect 直接改,报告里披露;
  • 修法只有一条合理路线的优化——明显的重复、明显的性能问题、缺失的错误处理;
  • 文档里已经给了标准的体验问题——设计稿有标注、规范有条目,照做即可,不因为"是界面"就上交。

拿不准时的两个检验:

  1. 两个合理的 Owner 会不会选得不一样? 会 → 留给 Owner;不会 → 自己做;
  2. Owner 看到改完的结果,会说"本该如此"还是"谁让你改的"? 前者自己做,后者留给 Owner。

留给 Owner 的事怎么留:

  • 阻塞当前工作的直接找 Owner,不在信道空转;其余进待 Owner 裁决清单(Conductor 维护),随里程碑交付报告一并呈上;
  • 每一项写成可以直接拍板的选择题:现状、可选方案、各自代价、Architect 的推荐。不交开放式问题;
  • 主观体验类附可看的东西:截图、录屏、可运行的入口;
  • 等待期间不停工:按 Architect 推荐的方案或最容易回退的方案先做,并在清单里注明"已按 X 先行,改主意的回退成本是 Y"。只有先行方案本身不可逆时才真的等。

谁来判定:实施期由发现者提出、Architect 判定是否属于本节;收官期由 Architect 在评估时逐项归类(§7)。Conductor 只记账,不判定。

6.3 退回与打回的依据

环节 谁 有效依据 无效依据
门禁退回 Conductor §2.3 清单某一项不过,附命令与输出 清单以外的任何意见——初审档写进初审意见,不作退回项
初审意见(不是退回) Conductor(初审档) 不需要依据才能提,但每条要说出影响或好处;疑似缺陷给复现或推理链 不阻塞合入;实现方可以不采纳,写一句理由即可
逐卡验收退回(对抗档 / 取证档) Reviewer 卡面目标 / 完成判据实测未达成;恶意输入矩阵某条失守;证据未闭合。每条附复现 写法偏好、代码风格、"我会写得更好";卡面没要求的功能——只能作建议
里程碑验收的问题 Reviewer 里程碑或卡面目标实测未达成;集成后的回归;可复现的崩溃、数据损坏、安全问题。每条附复现 同上。主观体验单列为"Owner 候选",不混进问题清单
按需审核打回 Architect 被标出的条目不认可(否决提案、自主决策与设计意图冲突);实现违背契约 卡面没写而现在才想要的——那是改卡,先修订卡面并声明是新增要求
  • 门禁退回与逐卡验收退回直达 Implementer,不经 Architect 转手:前者是清单与命令输出,后者有依据有复现,都不需要谁再判一次。Implementer 认为退回不成立时提出异议,由 Architect 定性;
  • 里程碑验收的问题清单交 Architect,不直接发 Implementer:这不是多转一道手——此时每个问题都要先定"自己修、交 Owner、还是不修"(§7.1),那是 Architect 的归类;一个里程碑只走一次,一次给全;
  • Reviewer 无契约修改权:发现卡面本身有问题(目标不对、判据与目标冲突、遗漏关键场景)→ 标明是卡面问题交 Architect,不自行要求改实现;
  • 返工后只复查退回项与受影响面;
  • 建议随结论附上,不阻塞:由 Conductor 挂账,Architect 在收官评估时决定去向;
  • 验收强度随卡面档位(§2.2):常规档不做恶意输入矩阵。

7. 里程碑收官与 Owner 交付

Owner 拿到的不是一串单卡通知,而是一份里程碑交付报告。报告送到 Owner 手上时,能自己修的都应该已经修完——报告里剩下的问题,要么属于 Owner 裁决域(§6.2),要么是权衡后决定不修并写明了理由。

7.1 里程碑验收、收官评估与自迭代

触发:里程碑内的卡全部合入集成分支,Conductor 通知 Reviewer。

  1. Reviewer 做里程碑验收(reviewer.md §1–§3):在集成分支上把整体实际跑起来——门禁复跑、里程碑目标与各卡目标逐条实测、各卡存疑点、主干既有路径回归冒烟。产出验收台账与问题清单,一次给全,交 Architect;

  2. Architect 做收官评估:目标达成情况以验收台账为证据,自己再实际跑一遍关键路径;整体结构有没有偏离设计;本里程碑挂账的 L2/L3、建议逐条过一遍。架构层面的把关集中在这一步;

  3. 逐项归类(判据见 §6.2):

    归类 处理
    自迭代 有依据、修法清楚 → 出补卡,走正常流程(门禁 → 集成分支)
    留给 Owner 属于 §6.2 裁决域 → 进待 Owner 裁决清单,写成选择题
    不处理 价值低于成本,或属于后续里程碑 → 写明理由,挂账到 backlog
  4. 补卡集成后,Reviewer 只复验补卡涉及面,Architect 只复评这部分。自迭代 ≤2 轮;出现 §2.1 越线信号立即停,剩余问题如实列进报告的「遗留缺陷」;

  5. 写交付报告(§7.2),合入集成分支;

  6. 合入主干:Reviewer 把含报告的集成分支合入主干,然后通知 Owner。遗留问题里若还有未修的崩溃、数据损坏、安全问题,或主干既有行为的回归,不合主干——报告开头写明原因与报告所在的分支,由 Owner 决定。

收官期间不停工:里程碑验收与收官评估进行时,Implementer 可以开工下一个里程碑的卡——Conductor 从当前集成分支被验收的那个 SHA 拉出下一个里程碑的集成分支。本里程碑的补卡优先于新卡;补卡合入后,由 Conductor 把它们同步进下一个里程碑的集成分支。上一个里程碑最终没有合入主干时,后续里程碑照此继续,不回退到主干重来。

里程碑要切小:常规卡在集成分支上累积到里程碑验收才被实测,里程碑越大,问题暴露得越晚、牵连越广。一个里程碑以一次验收能跑完为度。

7.2 交付报告

Architect 签发,Conductor 汇编事实部分。 事实(做了哪些卡、各自怎么实现、验收证据、提交范围)来自各卡交付报告与验收台账,汇编不需要判断;效果评估、缺陷、建议与待裁决事项需要判断,由 Architect 写。未部署 Conductor 时全部由 Architect 写。模板见 templates/owner-report.md,报告落在仓库内(默认 docs/collab/reports/<里程碑>.md)。

节 内容 谁写
结论 里程碑目标达成情况;需要 Owner 做的事有几件 Architect
做了什么 对照里程碑目标列出交付内容,Owner 能感知的变化放前面 Conductor
怎么实现的 关键设计与取舍、偏离原设计的地方及原因 Conductor 汇编,Architect 补取舍
效果如何 实测证据:跑了什么、结果是什么、怎么亲自体验 Conductor 汇编自验收台账,Architect 下评估结论
过程中自己修掉的问题 收官自迭代修了什么,让 Owner 知道发生过 Architect
遗留缺陷 已知而未修的问题、影响范围、为什么没修、建议怎么处理 Architect
后续建议 接下来该做什么,按优先级 Architect
需要你裁决 待 Owner 裁决清单全文,每项是选择题并带推荐 Architect

报告的纪律:

  • 写给没跟过程的人看:用平常的话说清楚,不复述协作流程,内部代号只保留卡号;
  • 缺陷不藏:遗留缺陷如实写,包括自迭代两轮没修好的;没验证过的不写成已验证;
  • 「需要你裁决」里不该出现有依据且修法清楚的问题——出现了说明自迭代没做完,回去做;
  • 单卡合入不向 Owner 汇报;里程碑中途找 Owner 的只有阻塞性的裁决事项。

Owner 就裁决项给出决定后,由 Architect 转成卡或文档修订,进入下一轮正常流程。

8. 通用工程规约(默认值,部署时按项目覆盖)

代码风格、类型严格度、错误处理方式这类规范属于项目自身(贡献指南、lint 配置),不在本协议里规定。这里只留多 agent 协作才需要的几条:

项 规约
提交 Conventional Commits(feat/fix/docs/refactor/test/chore + 描述);尾注执行者身份,格式见 §8.1——多 agent 同仓提交,审计必需
分支 手工创建时默认 task/<ID>-短描述;宿主已分配时沿用实际分支;并行任务不得共享可写分支,同一执行者的顺序批量卡可共用分支
依赖 新增运行时依赖走 L1-提案(保守档为 L1-停);提案里枚举官方 companion 闭包(types、插件、CLI、配套包)并核查各新增包的 peerDependencies;交付报告列实际新增依赖全表
生成物 可由固定命令重现;生成物 lint 豁免必须按具体文件路径显式列名(禁通配目录、禁行内豁免注释)
门禁命令表 【部署时填写:类型检查 / lint / 测试 / 格式化 / 生成物重现校验的完整命令】
示例(项目 A):pnpm typecheck && pnpm lint && pnpm test;cargo test && cargo clippy -- -D warnings && cargo fmt --check;bindings 重生成后 shasum -a 256 比对零漂移

8.1 提交署名(谁提交谁署自己那条)

多个 agent 往同一个仓库提交,git log 的 author 字段通常是同一个人类账号——署名是唯一能区分"这段代码出自谁"的凭据,不是装饰。等到需要追责或复盘"这个决定当时是谁做的"时,它是仅有的线索。

格式:commit 消息末尾加 git trailer,一行一条:

Co-Authored-By: <角色>-<模型标识>

角色名与模型标识在部署时一并确定并记入信道存档(与 §1.2 的模型来源同一件事)。模型标识用该 agent 在本项目里的固定代号,不用版本号——版本会变,而署名是历史记录,变了就对不上从前的提交。形如:

Co-Authored-By: Architect-<模型代号>
Co-Authored-By: Conductor-<模型代号>
Co-Authored-By: Implementer-<模型代号>
Co-Authored-By: Reviewer-<模型代号>

Implementer 与 Reviewer 同源时代号相同、角色前缀不同,这正是要区分的两件事:同一个模型在两个角色下的产出,责任归属不同。

规则:

  • 署名要求作用于本方新建提交。已存在的宿主 baseline/checkpoint 和本轮起点按原样继承,不得仅为规范提交说明或尾注而 amend;
  • 谁提交谁署自己那条,不代签他人——代签让审计链失真,而审计链失真的时刻,恰好是你最需要它的时刻;
  • 一次提交若确实是多方共同产出(如 Architect 接管重写时在 Implementer 的分支上续改),由提交者列全参与方,并在提交描述里说清各自改了什么——列全不等于代签,前提是这次提交真的包含对方的产出;
  • 合入的 merge commit 由合入者署自己一条即可;被合入的各 commit 里已有各自署名,不必重复;
  • 代行期(§1.1)照常署代行者本人的角色,不署被代行者——事后要能一眼看出哪些裁决和提交出自代行期;
  • 需要 GitHub 识别为 co-author 时补邮箱(Co-Authored-By: Name <email>);纯内部审计可省。