多人 / 多 Agent 对齐协议
回答：多人 / 多 Agent 在生态内协同推进时，怎么确保认知、设计、计划、实施层面对齐而不漂移。
1. 对齐的三层颗粒
| 层 | 记号 | 内容 | 主要 artifact |
|---|---|---|---|
| 战略 / 定义层 | L | 生态愿景、项目定位、产品定义 | ecosystem/ projects/<id>/strategy/ projects/<id>/product/ |
| 设计 / 计划层 | D | 系统设计、roadmap、里程碑 | projects/<id>/design/、projects/<id>/execution/ 中人读版本计划 |
| 执行 / 协同层 | S | 任务包、接力锚点、Controller state | 见对应工程仓（不在本仓库） |
（记号 L / D / S 仅用于本协议「分层颗粒」；勿与 CM（Commons 方法论资产）缩写混用。）
本仓库只承载 L + D。S 层（task-packet / handoff-anchor / Controller state）在各项目工程仓内，本仓库只提供模板（../commons/templates/）、方法论（../commons/frameworks/）和只读索引（项目内 execution/<version>/execution-artifact-index.md）。
2. Task Packet 最小字段契约
完整定义（生命周期 / 字段语义 / 验证规则）由 commons/frameworks/task-packet/ 承载。本节列出所有 Task Packet 必须包含的最小字段：
| 字段 | 类型 | 说明 |
|---|---|---|
packet_id | string | 全局唯一，含项目前缀，如 finclaw.v1.tp-014 |
version | semver | 包本身的版本，便于重派发 |
parent | string|null | 上游 packet（如有），用于追溯依赖链 |
inputs | list | 必读源（含 path + 可选 anchor + 可选 commit_sha） |
acceptance | list | 验收点（每个含 check 描述 + command 可选） |
outputs | list | 期望产出物（路径 / 类型 / 写入位置） |
context_budget | object | max_tokens + 关键源 token 上限 + 上下文窗口建议 |
owner_agent_role | string | 适配的 Agent 角色（如 architect / implementer / reviewer） |
state | enum | draft / ready / in-progress / blocked / done / archived |
evidence_pointer | string | trial / audit 完成后回填的证据路径（指向工程仓 / execution/<version>/） |
3. Handoff Anchor 最小字段契约
完整定义见 commons/templates/handoff-anchor/。最小字段：
| 字段 | 类型 | 说明 |
|---|---|---|
anchor_id | string | 全局唯一，如 finclaw.v1.ha-007 |
phase | string | 接力发生时所处的阶段 / 里程碑 |
from_role / to_role | string / string | 谁交接给谁（Controller / 实施 Agent / 审计 Agent / 人） |
summary | string | ≤ 200 字：当前状态、下一步、风险 |
decisions | list | 本接力点拍板的关键决策 + 依据 |
open_questions | list | 待解决问题 + 推荐解 |
links | list | 相关 task-packet / commit / ADR / evidence |
created_at | ISO-8601 | 时间戳 |
closed_by | string|null | 谁关闭、何时关闭 |
4. Controller State 最小字段契约
每个项目 / 每个 controller 维持一份 state；本仓库不持有 state 本体，只规定其最小形状。详细模板见 commons/templates/controller-state/。最小字段：
| 字段 | 类型 | 说明 |
|---|---|---|
controller_id | string | 项目 + 版本 + 实例标识 |
phase | enum | intake / design / execute / trial / audit / blocked / done |
active_packets | list | 当前 in-progress / blocked 的 packet_id |
pending_anchors | list | 待消费的 handoff_anchor |
last_checkpoint | object | commit_sha + path + ts（可重放） |
inbox | list | 待处理的 escalation / question / proposal |
next_action | string | 一句话写明 controller 下一步 |
health | enum | green / yellow / red + 简述 |
5. Agent 范式适配
本仓库不绑定单一 Agent 框架，但协议必须能映射到主流范式的关键回写点，否则 Agent 在循环 / 任务包 / 工作流中产生的事实就回不来。
给人类读者的一句导言：若你不维护 Agent infra，不必深入每个范式细节。本节价值在于——无论下游用 harness、任务包还是 Ralph 类循环，都必须把 stop / 迭代边界 / 验证 / 接力映射回本文 §2-§4 的 task-packet / handoff-anchor / controller-state 字段；否则会出现「Agent 跑完了、仓库里没证据」的漂移。
5.0 Invariants
无论采用哪种 Agent 范式，以下 4 个 hook 都必须能回写到本协议的 artifact：
- stop hook：正常完成、主动停止、异常中断、等待外部解锁时，必须把 stop 原因写入
controller-state.health或相关 handoff-anchor。 - iteration boundary hook：每轮循环 / 每个 step / 每个 packet 边界，必须有可追溯的当前状态，至少能定位 active packet、下一步和阻塞项。
- verification hook：验收命令、人工审计、构建结果或检查结论必须写入
evidence_pointer或 handoff-anchor links，不能只留在对话上下文。 - handoff hook：跨 Agent、跨角色、跨会话、跨仓继续时，必须产出 handoff-anchor 或等价的本地落盘接力记录。
5.1 主流范式的回写点对应
详细 per-paradigm 文档位于 ../commons/frameworks/agent-paradigms/；本表保留稳定的 4-hook 对齐规则。
| 范式 | 关键回写点 | 本协议对应 |
|---|---|---|
| harness 模式（含工作流编排） | stop / iteration 边界、step 之间 | 每个 iteration 末写一份 handoff-anchor；harness 正常结束 controller-state.phase=done；若异常终止或等待外部解锁则 phase=blocked 并在 health 中标注原因 |
| task-packet 模式（本生态 FinClaw V1 实践） | 每个 packet 完成时 | 写 packet 完成 evidence，更新 controller-state.active_packets，必要时产 handoff-anchor |
| ReAct / planner→executor→reviewer pipeline | plan/action/observation 或 plan/execute/review 每轮结束 | iteration boundary 写当前 plan + action 结果；verification hook 写 reviewer 结论；stop hook 写最终状态；handoff hook 写下一角色输入与 open questions |
| Ralph Loop（自指循环） | 每轮 verification + 下一轮 prompt 之间 | verification 结论写入 evidence；下一轮 prompt 调用前 controller-state 必须刷新 |
| Ralph Wiggum（plugin 化简版） | plugin handler 之间 | 同上，最小要求是把 stop 原因写入 controller-state.health |
5.2 设计上预留位置
../commons/frameworks/ 下的 Agent 范式文档按以下文件名组织：
frameworks/agent-paradigms/harness.mdframeworks/agent-paradigms/task-packet.mdframeworks/agent-paradigms/react-pipeline.mdframeworks/agent-paradigms/ralph-loop.mdframeworks/agent-paradigms/ralph-wiggum.md
每个文件回答相同 5 个问题：何时触发 stop / 每轮 iteration 写什么 / 怎么 verification / 怎么 handoff / 多 Agent 协同时谁拿锁。
6. 多 Agent 协同模式
不绑定单一项目的多 Agent 协同模式集合由 ../commons/frameworks/multi-agent-coordination/ 承载。
7. 个人域 Agent 与团队域 Agent 的边界
个人域 Agent 只读取完成当前任务所需的公开治理入口、项目事实源、派生 Agent 包和明确授权的本地工程证据；不得默认读取团队私有沟通、个人密钥、未授权客户材料或未发布的商业过程记录。
团队域流通的信息应以治理库中的事实源、proposal、ADR、handoff-anchor 或项目 execution index 为交接面。个人域 Agent 若发现需要团队判断的事项，应沉淀为 proposal、checkpoint 或明确的 open question，而不是把对话上下文当成团队事实源。
接力点：
- 从个人域到团队域：提交最小可审计 artifact，包含 source refs、变更范围、验证证据和未决问题；
- 从团队域到个人域：给出明确入口文件、允许读取的证据范围和当前任务边界；
- 跨域禁止项：不得把未授权个人材料、凭据、客户敏感信息或只存在于即时对话中的判断写成生态事实。