diff --git a/docs/design/architecture-v2.md b/docs/design/architecture-v2.md index 753a530..1e4240a 100644 --- a/docs/design/architecture-v2.md +++ b/docs/design/architecture-v2.md @@ -2211,18 +2211,144 @@ Agent 执行过程中的关键决策点用 severity=audit 记录: - 发现了什么 audit 级别不通知庞统,只记录在文件系统供事后审查。 -#### 3.12.11 Agent 调度方式(v2.5 确认) +#### 3.12.11 Agent 调度方式(v2.6 终版确认) -**实验结论**(2026-05-14 spawn 实验): -- `sessions_spawn` 只能 spawn 自己的 sub-agent,不能指定 guanyu-dev 等其他 agentId -- 因此 spawn 用于庞统内部的复杂分析,不能替代调度将军 +**实验结论**(2026-05-14 两轮 spawn 实验): +- `sessions_spawn` 配置 `allowAgents: ["*"]` 后可以指定其他 agentId +- 跨 Agent spawn 读写文件、结论回传、cleanup:delete 全部正常 +- **spawn 是 v2.0 调度将军的首选方式** -**v2.0 双模式调度**: +**Gateway 配置**(已应用): +```json +// ~/.openclaw/openclaw.json → agents.list[id=pangtong-fujunshi] +{ "subagents": { "allowAgents": ["*"] } } +``` -| 方式 | 用途 | 特点 | -|------|------|------| -| `openclaw agent --agent xxx` | 调度将军执行步骤 | 一次性 CLI,执行完进程结束 | -| `sessions_spawn` (cleanup:delete) | 庞统内部复杂分析 | 子 session 完成后自动清理 + 结论回传 | +**v2.0 调度方式(按优先级排序)**: + +| 优先级 | 方式 | 用途 | 特点 | +|--------|------|------|------| +| **首选** | `sessions_spawn(agentId="xxx", cleanup="delete")` | 调度将军执行步骤 | 不走 Gateway、并行、自动清理、结论回传 | +| Fallback | `openclaw agent --agent xxx --local --json` | spawn 不可用时 | `--local` 本地运行,自动 fallback | +| 内部 | `sessions_spawn()` (无 agentId) | 庞统内部复杂分析 | 子 session 继承上下文 | + +**spawn 的关键优势**(vs `openclaw agent` CLI): +- 不依赖 Gateway(Gateway 挂了也能调度) +- 庞统可以通过 `subagents list` 实时监控子 session 状态 +- 完成后自动回传结果,不需要轮询 +- 支持嵌套调度(`maxSpawnDepth: 2`) +- 支持并行(`maxConcurrent: 8`) + +#### 3.12.12 庞统上下文管理(v2.6 新增) + +> **核心问题**:庞统在一个 session 里处理多个任务时,上下文会膨胀。如果“每次唤醒全新视角”, +> 之前的推理过程丢失,决策质量下降。如果保留全部上下文,token 爆炸。 +> **必须找到平衡**。 + +**调研来源**: +- **get-shit-done**:Wave Execution——每个 plan 用独立新鲜上下文,避免 context rot +- **Claude Code**:session linked by parent_session_id + auxiliary-LLM compression +- **学术:Episodic Memory**(arXiv:2502.06975):episodic memory 是长期 Agent 的缺失拼图 +- **学术:Memory as Action**(arXiv:2509.25250):自主上下文策展 + +**方案:三层上下文架构** + +``` +┌───────────────────────────────────────────┐ +│ L1: 永久记忆(跨任务保留) │ +│ MEMORY.md + 经验库 + Skill 体系 │ +│ 每次启动自动注入,不受上下文窗口限制 │ +└───────────────────────────────────────────┘ + +┌───────────────────────────────────────────┐ +│ L2: 任务工作记忆(单任务内保留) │ +│ decisions.jsonl + moments.jsonl + status.json │ +│ 存文件系统,庞统被唤醒时 read 获取 │ +│ → 这就是“上下文恢复协议”的实质 │ +└───────────────────────────────────────────┘ + +┌───────────────────────────────────────────┐ +│ L3: 推理上下文(每次唤醒重建) │ +│ 当前推理过程,对话历史中的近期部分 │ +│ 通过 OpenClaw compaction 自动管理 │ +└───────────────────────────────────────────┘ +``` + +**具体机制**: + +1. **庞统被唤醒时**: + - read `status.json`(当前全局状态) + - read `decisions.jsonl`(之前做过的决策及理由) + - read `moments.jsonl`(最近 10 条事件) + - 这三步重建 L2 工作记忆 + +2. **庞统做决策时**: + - 关键决策写入 `decisions.jsonl`(不只在对话历史里) + - 格式:`{decision, reason, alternatives_rejected, timestamp}` + - 下次被唤醒时能看到自己之前为什么做这个决策 + +3. **防止“忘了”的兜底**: + - 每个 observation 写入时,daemon 同时记录到 `moments.jsonl` + - 庞统被唤醒时看到的 moments 包含所有 Agent 的 observation 摘要 + - 即使庞统“忘了”对话中的推理,通过文件系统能找回来 + +4. **并行步骤完成后的识别**: + - 两个并行步骤都完成后,daemon 生成一个“并行步骤关联分析” + - 检查两个步骤的 observation 是否有关联 + - 如果有关联,写入 moments 并通知庞统 + - 庞统不需要“记住”并行步骤的关系——文件系统替他记着 + +**与之前“全新视角”方案的区别**: +- 之前:每次唤醒清空一切,只看 status.json +- 现在:每次唤醒有 L1(永久)+ L2(文件系统工作记忆)+ L3(对话上下文) +- L2 是关键创新——决策理由和 observation 摘要存在文件里,不依赖对话历史 + +#### 3.12.13 防降级机制(v2.6 新增) + +> **核心问题**:调度策略本身如何防止在执行过程中逐渐妥协? +> 庞统如何保证不为了“完成任务”而降级目标? + +**四个防降级机制**: + +**机制 1:反合理化表(Anti-Rationalization Table)** + +来源:Agent Skills 生命周期实践 + +写入 orchestration-strategy Skill 的 L3(反模式)层: + +``` +庞统自检清单——每个调度决策前必须过: +❌ “这个步骤简化一下” → 问:PRD 目标是否被覆盖? +❌ “时间不够跳过验证” → 没有验证的产出不算完成 +❌ “这个Agent做不到就算了” → 换 Agent 或拆步骤 +❌ “先用简单方案后续优化” → v2.0 就是完整实现 +❌ “用户应该不在意” → 你的判断 ≠ 用户需求 +``` + +**机制 2:目标锚定(Goal Anchoring)** + +每个任务的原始 goal 和 PRD 需求写入 `context.json`,不可修改。 +庞统每次做调度决策时必须对照 goal: +- 决策是否更接近 goal? +- 如果偏离 goal,必须升级到用户,不能自行降级 + +**机制 3:范围缩减检测(Scope Reduction Detection)** + +来源:get-shit-done 实践 + +planner.py 在 Phase 2 生成计划时,每个步骤必须标注覆盖哪些需求。 +daemon 在执行完所有步骤后,反向检查:每个需求是否被至少一个步骤覆盖。 +如果有遗漏,不允许进入 Phase 4,必须 replan。 + +**机制 4:验证前不完成(Verification-Before-Completion)** + +来源:superpowers 实践 + +Agent 声称完成时,validator.py 检查: +1. 产出物文件存在且非空 +2. 产出物与 end_state 描述匹配(AI 语义检查) +3. 没有未处理的 blocking observation +任何一项不通过,步骤状态不变为 completed。 ---