跳到主要内容

FinClaw V1 Multi-Agent Execution Protocol

状态：Accepted Initial Protocol / V1 工程化期间多 Agent 协同的执行契约 日期：2026-05-16 项目：FinClaw 文档级别：项目级方法论协议 上游决策：v1-engineering-kickoff-decisions.md 配套协议：v1-task-packet-context-budget-schema.md、v1-handoff-anchor-template.md

1. Purpose​

V1 工程化是一个长周期、多轮次、跨 Agent 的协同过程。本文件定义在该过程中：

  • 多个 AI Coding Agent（Cursor / Codex / OOSO 等）如何并行执行而互不冲突；
  • 单个 Agent 在执行单个任务包闭环时如何保持在最佳工作区间；
  • 任务包之间如何通过 hand-off anchor 传递结论而不传递完整 context；
  • 治理库与工程仓库如何在多 Agent 同时改动时保持一致性。

本文件是元规范，约束所有后续 task packet 与工程 PR 的执行方式。

2. Effective Context vs Context Window​

2.1 关键概念校准​

概念含义
Context Window模型 API 接受的最大 token 数（GPT-5.5 ~256K、Kimi K2.6 ~200K）
Effective Context模型在该长度下保持高质量结构化输出的范围（通常是 Window 的 30-50%）
Sweet Spotcoding 场景的最佳工作区间（30K-80K input tokens）

2.2 经验阶梯​

输入 context 长度Agent 行为
< 5K约束过少；agent 容易跑偏
10K-30K理想；agent 表现稳定
30K-80K可工作；开始有 attention dilution
80K-150K质量明显下降；幻觉率上升；tool_use schema 漂移
> 150K模型不能可靠完成结构化输出任务

2.3 Agent 闭环 context 真实消耗结构​

单轮 agent 闭环 context 消耗 =
    system_prompt              (~5K)
  + skill/advisor 指令          (~5-15K)
  + 必读文档                    (~10-50K)
  + 工具调用结果累积            (5-50K，每次工具调用都进 context)
  + reasoning 中间产物          (3-20K)
  + 输出 budget                 (5-20K)
  ─────────────────────────
  ≈ 30K-150K

关键洞察：tool_use 累积是被低估的 context 消耗源。一个 coding agent 跑 10 次 Read + 5 次 Grep + 3 次 Shell，光工具调用结果就能塞 30K+ token。

3. Sweet Spot Targets​

V1 工程化期间的硬性目标：

Packet 类型Input Context TargetTotal Budget Target
设计文档撰写 sub-packet≤ 30K≤ 60K
工程实现 sub-packet≤ 40K≤ 80K
评测 / 测试 sub-packet≤ 35K≤ 60K
Skills 评审 / 自查 sub-packet≤ 25K≤ 50K
大型 refactor / migration≤ 50K≤ 100K

超过 target 时必须进一步切片为更小 sub-packet。

4. Hand-off Principle​

4.1 闭环间不传递完整 context​

每个 task packet / sub-packet 闭环完成时，必须产出符合 v1-handoff-anchor-template.md 的 hand-off anchor（≤ 5K tokens）。

下一个 Agent 启动时只载入：

新 Agent 输入 =
    system_prompt
  + 下一个 sub-packet 的 must_read 文档（按 section navigation 切片）
  + 上一个 sub-packet 的 hand-off anchor
  + 本 sub-packet 自己的指令

禁止：

  • 把前一个 agent 的完整对话历史作为输入；
  • 重复加载已经在 hand-off anchor 中固化的结论；
  • 让新 agent 「再读一遍」前一个 packet 已经读过的文档。

4.2 Anchor 是单向只读​

Hand-off anchor 一旦写入治理库，对后续 agent 只读。如发现 anchor 中的结论错误，不修改原 anchor，而是新建一个 hotfix sub-packet 显式修正。这保留决策痕迹，避免「沉默回滚」。

5. Multi-Agent Concurrency Rules​

5.1 文件所有权矩阵​

V1 工程仓库按 package 切分所有权，避免并发改同一文件：

Package主负责 Agent共享文件（需要协调）
agent/ (runtime + skills + advisors 编排)Agent Aagent/models.py（与 Agent B 协调）
tools/ (内置工具 + crypto data)Agent Bagent/models.py（与 Agent A 协调）
api/ (FastAPI + SSE 事件)Agent Capi/schemas.py（与 Agent D 协调）
web/ (前端)Agent Dapi/schemas.py（与 Agent C 协调）
skills/ (V1 7 个 Fin Skill 文件)Agent E—
evaluation/ (cases + runs + reports)Agent Ftests/（与所有 agent 协调）
config/ (provider 路由 + budget 配置)Agent G—

冲突解决规则：

  • 共享文件改动必须先在 hand-off anchor 中声明意图；
  • 同一文件同一行的并发修改由项目发起人裁决，不由 agent 间协商；
  • 任何跨 package 的接口变更（如新增 API endpoint）走 v1-api-contract-design.md 修订 PR，所有相关 agent 后续工作必须基于 PR 合并后版本。

5.2 Git Worktree 隔离​

每个并行 Agent 在独立 worktree 工作：

# 在新工程仓库 /Users/mlabs/Programs/CurvatureLabs/finclaw/ 下
git worktree add ../finclaw-agent-A feature/agent-runtime
git worktree add ../finclaw-agent-B feature/tools
git worktree add ../finclaw-agent-C feature/api
git worktree add ../finclaw-agent-D feature/web

每个 worktree 是独立 Cursor / Codex 工作目录。Agent 不需要意识到其他 worktree 的存在。

5.3 同步点（Sync Points）​

频率动作
每个 sub-packet 完成Hand-off anchor 写入治理库 + worktree 当前分支 push 到 origin
每个 milestone 完成所有 worktree rebase 到 main，跑全量测试
每天结束（如果当天有多 agent 活动）项目发起人主导一次「集成 checkpoint」：把所有 feature 分支合并到 integration 分支，跑 smoke test

5.4 Context 隔离​

  • 禁止：Agent A 把自己的对话历史粘贴给 Agent B（这会导致 Agent B 上下文爆炸 + 受 A 的偏见污染）；
  • 允许：Agent A 把自己的 hand-off anchor 路径告诉 Agent B（Agent B 自行选择性加载）；
  • 必须：跨 agent 共享的所有结论必须落盘到治理库（不在临时聊天中）。

6. Parallel Execution Topology​

6.1 阶段性并行度建议​

阶段并行度模式
阶段 0：方法论补强1 Agent单 Agent 顺序执行（当前正在做）
阶段 1：核心架构设计1 Agenttech-stack / data-persistence / api-contract 必须串行
阶段 2：辅助设计文档3-4 AgentUI / observability / memory / cost 可并行
阶段 3：新工程仓库骨架1 Agent骨架建立必须单线
阶段 4：V1 工程实现4-5 Agent按 §5.1 文件所有权矩阵并行
阶段 5：评测 / Skills 自查与阶段 4 并行F + 自查 agent 独立运行
阶段 6：aifinlab Root Skills 分析与阶段 3-5 完全并行Codex 独立异步执行

6.2 不可并行的场景​

  • 决策性变更（决策记录、execution plan 修订）：单 Agent + 项目发起人确认；
  • 跨 package 接口变更：先单 Agent 改 API contract，合并后其他 Agent 才能基于新版本工作；
  • 数据模型重构：单 Agent，所有依赖此模型的工作暂停。

7. Quality Gates​

7.1 单个 sub-packet 完成的 quality gate​

Gate验证
Context budget 未超Agent 自报：input + 累积 tool_use + output 总计 ≤ packet 声明的 total_budget
Acceptance criteria 全通过按 packet 内 acceptance_criteria 逐条验证
Hand-off anchor 已产出治理库新增 anchor 文档，符合模板
未污染共享文件git diff 限定在文件所有权矩阵内
测试通过工程仓库 sub-packet 跑测试通过

任一 gate 失败 → packet 状态 partial 或 blocked，不进入 done。

7.2 集成 checkpoint quality gate​

Gate验证
全量测试通过pytest + lint + type check
跨 agent 接口一致API contract 检查通过
无未声明的共享文件冲突git merge 无 conflict
决策记录更新本次集成涉及的决策已回写治理库

8. Failure Modes and Recovery​

8.1 Sub-packet 执行失败​

失败模式恢复路径
Context budget 超限（agent 报错或质量下降）立即停止；切片为更小 sub-packet；重启
Tool_use schema 漂移（输出不符合 schema）检查 prompt 长度；如 > 80K 立即切片；如 < 30K 可能是 prompt 设计问题
未通过 acceptance criteria不强制 done；写入 partial anchor，下一个 sub-packet 处理遗留项
跨 agent 冲突立即停止所有相关 agent；项目发起人裁决；裁决结果写入治理库

8.2 Hand-off anchor 缺失​

如果某个 sub-packet 完成但未产出 hand-off anchor：

  • 下游 agent 不启动；
  • 项目发起人或后续 agent 负责补写 anchor（根据 sub-packet 实际产出反向归纳）；
  • 在治理库 risk log 中记录该次违规。

8.3 决策漂移​

如果发现某个 sub-packet 实际产出与 v1-engineering-kickoff-decisions.md 决议冲突：

  • 该 sub-packet 立即标记 blocked；
  • 升级到项目发起人；
  • 决策修订（如确认）后才解除 block。

9. Tool / Skill Recommendations​

V1 工程化期间推荐使用的 AI Coding 辅助技能：

Skill路径用途
writing-plans~/.claude/skills/writing-plans/写多步骤实施计划
to-issues~/.claude/skills/to-issues/计划拆 issue / sub-packet
codex plan~/.codex/skills/plan/战略规划
codex code-review~/.codex/skills/code-review/sub-packet 完成时自查
codex autopilot~/.codex/skills/autopilot/长周期自治循环
using-git-worktrees~/.claude/skills/using-git-worktrees/worktree 隔离
cursor frontend-design~/.cursor/skills/frontend-design/UI / web 实现

10. Anti-Patterns​

V1 工程化期间禁止的做法：

反模式为什么禁止
单个 Agent 单次会话试图完成整个 packet（含 10+ sub-packet）Context 必然超限
让 agent 「快速浏览整个工程仓库」再开始工作浪费 effective context 在无关文件
把上一个 agent 的对话历史粘贴给下一个 agentContext 污染 + 偏见传递
跨 agent 直接聊天（A 让 B 做什么）没有治理库证据，违反 §5.4
Sub-packet 完成但跳过 hand-off anchor后续 agent 必然重复劳动
把方法论协议本身当 must_read 加到每个 packet协议是元规范，agent 不需要每次读

11. Open Items​

  • Token 估算工具（自动统计治理库文档 token 数）尚未实现；当前估算手工进行；
  • 工程仓库的 worktree 自动化脚本（一键开 4 个 worktree）尚未起草；
  • Sub-packet 失败重试的指数退避策略尚未量化。

12. References​