From a18bd13e1d3bbe46e5dc7d3c26f44f031570b2fb Mon Sep 17 00:00:00 2001 From: cfdaily Date: Fri, 15 May 2026 09:31:37 +0800 Subject: [PATCH] auto-sync: 2026-05-15 09:31:37 --- ...v2.6-research-01-ai-decision-experience.md | 462 +++++++ .../v2.6-research-02-eventdriven-context.md | 679 ++++++++++ .../v2.6-research-03-challenge-quality.md | 928 ++++++++++++++ .../v2.6-research-04-decomposition-skills.md | 1141 +++++++++++++++++ .../v2.6-research-05-interaction-dashboard.md | 523 ++++++++ .../v2.6-requirements-design-verification.md | 203 +++ 6 files changed, 3936 insertions(+) create mode 100644 docs/research/v2.6-research-01-ai-decision-experience.md create mode 100644 docs/research/v2.6-research-02-eventdriven-context.md create mode 100644 docs/research/v2.6-research-03-challenge-quality.md create mode 100644 docs/research/v2.6-research-04-decomposition-skills.md create mode 100644 docs/research/v2.6-research-05-interaction-dashboard.md create mode 100644 docs/review/v2.6-requirements-design-verification.md diff --git a/docs/research/v2.6-research-01-ai-decision-experience.md b/docs/research/v2.6-research-01-ai-decision-experience.md new file mode 100644 index 0000000..5518649 --- /dev/null +++ b/docs/research/v2.6-research-01-ai-decision-experience.md @@ -0,0 +1,462 @@ +# 调研报告：AI 决策者参与 + 经验沉淀闭环 + +> 调研时间：2026-05-15 +> 调研范围：Hermes v0.13、Claude Code Agent Teams、GSD Wave Execution、OpenAI Agent SDK Guardrails、MetaGPT、nuwa-skill、claude-mem 等 + +--- + +## 课题 1：AI 决策者有效参与 + +### 1.1 已有经验（知识库/wiki） + +知识库中无直接相关的实践经验。知识库主要包含 OpenClaw Agent 模板（awesome-openclaw-agents），其中涉及 coordinator 模式的有： +- `family-coordinator/SOUL.md`：家庭协调员模式，但偏向任务调度而非质量门控 +- `incident-responder/README.md`：事件响应模式，有升级机制但非实时决策参与 + +**结论**：需要从业界实践中提炼适合 moziplus Blackboard 架构的决策者参与机制。 + +### 1.2 业界优秀实践对比表 + +| 项目 | 架构模式 | 决策者角色 | 防偏离机制 | 防蔓延机制 | 故障处理 | 介入时机 | +|------|----------|-----------|-----------|-----------|---------|---------| +| **Hermes v0.13** | Kanban Board（持久多 Agent 看板） | 无显式 coordinator，靠系统级保护 | 幻觉门控（Hallucination Gate）：验证完成声明才关闭任务 | Per-task retry budget 限制单任务重试次数 | 僵尸检测 + 自动回收 + 不完整退出自动阻塞 | 心跳超时 → 回收；幻觉检测 → 阻塞关闭 | +| **Claude Code Agent Teams** | Lead + Teammates（coordinator 模式） | Lead Agent 负责：分解任务、分配、监控输出、解决冲突 | Lead 监控每个 subagent 输出，解决依赖冲突 | Task decomposition 即为范围限定，subagent 只拿相关 context | Subagent 失败由 Lead 感知并处理 | 每个 subagent 完成时介入审查 | +| **GSD (get-shit-done)** | Planner → Executor → Verifier 三角色 | Planner 做分解和验证计划；Verifier 做独立验收 | must_haves（前置条件）+ goal-backward verification（目标回溯验证） | 每个 task 有原子 commit，可独立 revert | Verifier 独立 context 验收，不通过则生成 fix plan | Executor 完成后 Verifier 独立审查 | +| **OpenAI Agent SDK** | Guardrails 模式 | 无显式 coordinator，靠 input/output guardrails | Input guardrail：并行执行输入检查，快速失败 | Output guardrail：验证 agent 输出合规性 | Tripwire 机制：检测到违规立即中断 | 每次 agent 输入/输出时并行检查 | +| **MetaGPT** | SOP 编码 + Role-based | Engineer Agent 作为隐式 supervisor，每个 role 按 SOP 产出 | 共享消息池（Message Pool），Agent 监控环境观察 | SOP 编码为 prompt 序列，严格定义每步产出 | 每个 Agent 发布消息到共享池，下游 Agent 可拒绝不符合规范的输入 | 每个角色产出时，下游消费者隐式审查 | + +### 1.3 关键机制深度分析 + +#### 1.3.1 Hermes v0.13 — 系统级韧性（不依赖 coordinator） + +Hermes v0.13 的核心创新是"不信任 Agent 的完成声明"，通过多层系统级保护确保任务完整性： + +- **心跳检测（Heartbeat）**：Agent 领取任务后必须定期发送心跳，超时未发送则标记为"可能停滞" +- **僵尸检测（Zombie Detection）**：检测已分配但长时间无进展的任务，自动标记 +- **回收机制（Reclaim）**：僵尸任务被回收回看板，可被其他 Agent 重新领取 +- **幻觉门控（Hallucination Gate）**：Agent 声称"完成"时，系统验证实际产出（如补丁是否真正落地），验证通过才关闭任务 +- **Per-task Retry Budget**：每个任务有独立重试预算，防止单任务无限循环 +- **不完整退出自动阻塞（Auto-block）**：Agent 异常退出时自动阻塞该任务，不会静默失败 + +**适用场景**：适合 moziplus Daemon 层面的保护机制——Daemon 不做决策，但做系统级保护。 + +#### 1.3.2 Claude Code Agent Teams — Lead 主动协调 + +Claude Code 的 Agent Teams 模式采用显式 Lead（coordinator）： + +- **Lead Agent** 职责： + 1. 接收用户需求并分解为子任务 + 2. Spawn teammates，每个 teammate 拿到特定 context + 3. 监控各 teammate 输出 + 4. 解决 teammate 间的依赖冲突 + 5. 合成最终结果 +- **关键约束**：Lead 通过 `Agent(agent_type)` 语法限制可 spawn 的 subagent 类型 +- **Context 隔离**：每个 subagent 只拿到相关 context，防止信息泄露和范围蔓延 +- **配置示例**： + ```yaml + --- + name: coordinator + description: Coordinates work across specialized agents + tools: Agent(worker, researcher), Read, Bash + --- + ``` + +**适用场景**：适合 moziplus 中庞统作为 coordinator 的角色定义。 + +#### 1.3.3 GSD Wave Execution — 三角色流水线 + +GSD 的核心是 Planner → Executor → Verifier 的严格流水线： + +- **Planner**： + - 输出 PLAN.md（含 must_haves 前置条件） + - 依赖分析 + wave 分组（同 wave 并行执行） + - goal-backward verification（从目标回推验证计划完整性） +- **Executor**： + - 每个 task 获得独立 200k token context + - 原子 commit（每个 task 独立提交） + - 不读其他 executor 的 context +- **Verifier**： + - 独立 context 审查 + - 读取 SUMMARY + must_haves 验证 + - 不通过则输出 fix plan，可直接重执行 + +**适用场景**：适合 moziplus 的"分阶段编排"模式，特别是需要质量门控的场景。 + +#### 1.3.4 OpenAI Agent SDK Guardrails — 并行验证层 + +OpenAI 的 Guardrails 不依赖特定角色，而是通过 input/output 两层验证： + +- **Input Guardrail**：在 agent 执行前并行检查输入（如注入检测、范围校验） +- **Output Guardrail**：在 agent 输出后验证合规性 +- **Tripwire**：检测到严重违规时立即中断执行 +- **关键原则**：验证逻辑放在产生副作用的地方，而非仅靠 agent 级别的 input/output guardrail +- **并行执行**：guardrail 与 agent 执行并行，不阻塞正常流程 + +**适用场景**：适合 moziplus 黑板上的"观察者"模式——在黑板写入时并行验证。 + +### 1.4 推荐方案（结合 AI Native 目标） + +基于以上分析，推荐采用 **"系统保护层 + Coordinator 主动介入" 双轨制**： + +#### 方案架构 + +``` +┌─────────────────────────────────────────────────┐ +│ Blackboard (黑板) │ +│ observations | decisions | tasks | experiences │ +└──────────┬──────────────────────────┬───────────┘ + │ │ + ┌────────▼────────┐ ┌────────▼────────┐ + │ Daemon 保护层 │ │ Coordinator 层 │ + │ (系统级，不决策) │ │ (庞统，主动决策) │ + │ │ │ │ + │ • 心跳检测 │ │ • 任务分解验证 │ + │ • 僵尸回收 │ │ • 输出质量审查 │ + │ • 幻觉门控 │ │ • 冲突调解 │ + │ • Retry budget │ │ • 范围仲裁 │ + └─────────────────┘ └─────────────────┘ +``` + +#### 具体机制设计 + +**第一层：Daemon 系统保护（类似 Hermes）** + +| 机制 | 触发条件 | 行为 | +|------|---------|------| +| 心跳检测 | Agent 领取节点后 N 分钟无更新 | 标记为"停滞" | +| 僵尸回收 | 停滞超过阈值 | 回收任务到待分配池 | +| 幻觉门控 | Agent 提交完成声明 | 验证 output.md 是否存在且非空，验证结论 JSON 格式正确 | +| Retry Budget | 单节点重试超过 N 次 | 标记为失败，通知 coordinator | + +**第二层：Coordinator 主动介入（类似 Claude Code Lead + GSD Verifier）** + +| 介入时机 | 介入方式 | 说明 | +|---------|---------|------| +| 任务创建时 | 分解验证 + must_haves 定义 | 确保每个节点任务有明确的成功标准 | +| 节点产出时 | 输出审查 + 范围校验 | 检查是否偏离原始需求 | +| 依赖冲突时 | 仲裁 + 调解 | 解决 Agent 间的矛盾输出 | +| 节点失败时 | 根因分析 + 重规划 | 决定是重试、降级还是放弃 | +| 任务完成时 | 整体验收 + 经验提取 | 运行 Verifier 角色，提取经验写入黑板 | + +**第三层：Guardrails（类似 OpenAI Agent SDK）** + +在黑板写入时并行验证： +- **范围守卫**：Agent 写入 decisions 时，检查是否超出任务 scope +- **格式守卫**：验证写入数据的格式和完整性 +- **冲突守卫**：检测与已有 decisions 的矛盾 + +#### 防偏离策略 + +1. **must_haves 继承**：每个节点任务从父任务继承 must_haves，coordinator 在创建时定义 +2. **目标回溯验证**：任务完成后，从最终目标回溯验证每个节点的贡献 +3. **范围声明**：每个 Agent 在开始工作前必须声明"我计划做什么"，coordinator 确认后才开始 + +#### 防蔓延策略 + +1. **原子任务**：每个节点任务有明确的输入/输出契约 +2. **Context 隔离**：Agent 只能读取被授权的黑板区域 +3. **单次写入**：Agent 只能写入自己负责的 decisions 条目 +4. **超时机制**：每个节点有预估工时，超时自动升级到 coordinator + +#### 故障处理策略 + +| 故障类型 | 检测方式 | 处理方式 | +|---------|---------|---------| +| Agent 崩溃 | 心跳超时 | 自动回收 + 重新分配 | +| Agent 幻觉 | 幻觉门控 | 阻塞关闭 + 要求补充验证 | +| 产出质量差 | Coordinator 审查 | 打回重做 + 给出改进方向 | +| 需求偏离 | 范围守卫 | 暂停 + coordinator 仲裁 | +| 依赖阻塞 | 超时检测 | coordinator 重新编排依赖 | + +--- + +## 课题 6：经验沉淀闭环 + +### 2.1 已有经验（知识库/wiki） + +知识库中无直接相关的经验沉淀实践。但 OpenClaw 体系中已有： +- **MEMORY.md**：每个 agent 的记忆文件（四类记忆法：user/feedback/project/reference） +- **知识库**：`~/.openclaw/knowledge_base/` 目录，但目前只存基础数据 + +### 2.2 业界优秀实践对比表 + +| 项目 | 闭环模型 | 信息源 | 蒸馏过程 | 经验载体 | 反哺机制 | +|------|---------|-------|---------|---------|---------| +| **Claude Code Memory** | 四类记忆法 | Agent 工作过程中的自动观察 | Agent 自行判断何为值得记录的 → 写入 MEMORY.md | Markdown（MEMORY.md，按 user/feedback/project/reference 分类） | 每次 session 启动时自动加载到 context | +| **Hermes Learning Loop** | 闭环学习（五层） | 任务执行过程、对话历史 | 复杂任务完成 → 自动创建 SKILL.md；使用中自改进；FTS5 跨 session 搜索 + LLM 摘要 | SKILL.md（步骤化菜谱）+ Honcho dialectic model（12 层用户建模） | 新任务自动检索相关 SKILL；periodic nudges 主动推送遗忘的知识 | +| **nuwa-skill** | 五阶段蒸馏管线 | 公开数据源（文章、演讲、推文） | Phase 1 实体发现 → Phase 2 数据采集 → Phase 3 心智模型提取（3-7个 + 5-10条决策启发式 + 表达DNA + 反模式 + 诚实边界） → Phase 4 验证（3 个已知问题 + 1 个未知问题） → Phase 5 双 Agent 精炼 | SKILL.md（心智操作系统） | 生成的 Skill 可被 Agent 直接加载使用；Darwin.skill 持续进化（八维评估 + 棘轮机制） | +| **claude-mem** | 三层工作流 | Agent session 全程捕获 | 捕获 → AI 压缩 → 相关性注入 | 结构化 memory 文件 + FTS 索引 | 4 个 MCP 工具按需检索注入 context | +| **GSD** | Spec-driven | Plan → Execute → Verify 流水线 | Planner 的经验沉淀为更好的 plan template | PLAN.md 模板 + must_haves 模式 | 每个 phase 的 plan 模板可复用 | + +### 2.3 关键机制深度分析 + +#### 2.3.1 Claude Code Memory — 四类记忆法 + +Claude Code 的记忆体系分为四个类别： + +1. **User Memory**：用户角色和偏好（"用户喜欢用 TypeScript"） +2. **Feedback Memory**：用户纠正 Agent 错误的记录（"不要用 var，用 let/const"） +3. **Project Memory**：项目关键决策和架构选择（"我们用 monorepo"） +4. **Reference Memory**：文件位置和结构（"配置在 src/config/"） + +**关键设计决策**： +- Agent **自行判断**什么值得记录（不是什么都记） +- 写入门槛高：只记录不能从代码推导的信息 +- Auto memory 机制：Agent 在工作时自动积累，无需用户手动维护 +- Subagent 也可以维护自己的 auto memory + +**局限**： +- 无显式蒸馏过程（只记录不蒸馏） +- 无跨项目经验迁移 +- 无质量验证机制（可能记录错误的"经验"） + +#### 2.3.2 Hermes Learning Loop — 五层闭环 + +Hermes 是目前最完整的 Agent 学习闭环实现，包含五个层次： + +1. **Agent-curated Memory + Periodic Nudges** + - Agent 自主管理记忆 + - 定期"轻推"自己回忆可能遗忘的知识 + - 避免长 session 中上下文退化 + +2. **Autonomous Skill Creation** + - 完成复杂任务后，自动将解决步骤写入 SKILL.md + - 本质是"做过的事变成可复用的菜谱" + +3. **Skill Self-improvement During Use** + - 使用 Skill 时，根据实际效果自动改进 + - 类似"边用边学" + +4. **FTS5 Cross-session Recall + LLM Summarization** + - 全文搜索（FTS5）索引所有历史 session + - LLM 自动摘要，提取跨 session 可复用的知识 + - 新任务可搜索历史相似场景 + +5. **Honcho Dialectic User Modeling** + - 可选的用户建模层 + - 通过 12 个身份层建模用户偏好 + - "辩证法"建模：同时建模用户和 Agent 的关系 + +**关键洞察**：Hermes 的闭环核心是"记忆 → Skill → 搜索 → 改进"的持续循环。 + +#### 2.3.3 nuwa-skill — 五阶段蒸馏管线 + +nuwa-skill 的蒸馏管线从原始数据到可复用 Skill 经过五个阶段： + +**Phase 1：Entity Discovery（实体发现）** +- 输入：一个名字 +- 处理：通过搜索发现该人物的存在维度、领域、公开数据源 +- 产出：候选数据源列表 + +**Phase 2：Data Collection（数据采集）** +- 输入：数据源列表 +- 处理：采集文章、演讲、推文、访谈等原始材料 +- 产出：原始语料库 + +**Phase 3：Cognitive DNA Extraction（认知 DNA 提取）** +- 输入：原始语料 +- 处理：提取心智模型（3-7个）、决策启发式（5-10条）、表达 DNA、价值观与反模式、诚实边界 +- 方法论：三重验证（跨域存在性 + 预测力 + 排他性） +- 产出：SKILL.md 草稿 + +**Phase 4：Quality Verification（质量验证）** +- 输入：SKILL.md 草稿 +- 处理：用 3 个该人物公开回答过的问题测试（方向一致性）；用 1 个未讨论过的问题测试（适度不确定性） +- 产出：验证通过的 SKILL.md + +**Phase 5：Dual-Agent Refinement（双 Agent 精炼）** +- 输入：验证通过的 SKILL.md +- 处理：一个 Agent 扮演该人物使用 Skill，另一个 Agent 评估表现 +- 结合 Darwin.skill 的八维评估 + 棘轮机制（只保留改进，自动回退退化） +- 产出：最终 SKILL.md + +**关键创新**： +- "蒸馏的是思维方式，不是行为模仿" +- 三重验证确保提取的心智模型是真实的 +- 诚实边界：明确声明 Skill 的局限 + +### 2.4 推荐方案（结合 AI Native 目标） + +基于以上分析，推荐采用 **"DISCOVER → DISTILL → VERIFY → APPLY → IMPROVE" 五阶段闭环**： + +#### 闭环架构 + +``` + ┌──────────────────────────────────────────────┐ + │ │ + ▼ │ + DISCOVER ──→ DISTILL ──→ VERIFY ──→ APPLY ──→ IMPROVE + │ │ │ │ │ + │ 黑板 │ 蒸馏器 │ 验证器 │ 执行器 │ 进化器 + │ observations │ │ │ │ + │ decisions │ │ │ │ + │ task_outputs │ │ │ │ + └──────────────┘ │ │ │ + ▼ ▼ ▼ + Skill Store 下次任务 Skill 自改进 +``` + +#### 阶段一：DISCOVER（信息发现） + +**信息源**（按价值排序）： + +| 信息源 | 采集方式 | 价值 | +|-------|---------|------| +| 黑板 decisions | 自动记录 Agent 决策过程和理由 | 高 | +| 节点 output.md | 任务完成后的产出文件 | 高 | +| Coordinator 审查记录 | 庞统审查时的问题和修正 | 高 | +| 错误与修正 | 幻觉门控拦截、Coordinator 打回重做 | 极高 | +| Agent 间协作 | 黑板 observations 中的交互记录 | 中 | +| 重试历史 | Retry budget 消耗记录 | 中 | + +**写入黑板 experiences 表**： +```json +{ + "experience_id": "exp-001", + "source": "node_output", + "task_id": "task-123", + "node_id": "coding", + "timestamp": "2026-05-15T10:00:00Z", + "raw_data": { ... }, + "tags": ["error-handling", "vnpy-strategy", "backtest"], + "status": "discovered" +} +``` + +#### 阶段二：DISTILL（蒸馏） + +蒸馏过程分为两级： + +**一级蒸馏（实时，每个任务完成后）**： +- **执行者**：完成任务后的 Agent 自动触发 +- **过程**： + 1. 从 output.md 提取关键决策和理由 + 2. 从错误修正中提取"教训" + 3. 压缩为结构化经验条目（200-500 字） +- **产出**：经验条目写入黑板 experiences 表，status = "distilled" + +**二级蒸馏（周期性，由 Coordinator 触发）**： +- **执行者**：Coordinator（庞统）或专用蒸馏 Agent +- **过程**（参考 nuwa-skill 三重验证）： + 1. 聚合同类经验（按 tag 聚合） + 2. 提取心智模型（这类问题的通用解决模式） + 3. 提取决策启发式（遇到 X 情况，优先考虑 Y） + 4. 提取反模式（遇到 X 情况，千万不要 Z） + 5. 标注诚实边界（这些经验的适用范围） +- **产出**：Skill 草稿或 Rule 更新 + +**蒸馏格式**（参考 nuwa-skill SKILL.md 结构）： + +```markdown +# Skill: [名称] +## 心智模型 +- [模型1]: [描述] +- [模型2]: [描述] + +## 决策启发式 +- [情况X] → 优先考虑 [Y] +- [情况A] → 避免使用 [B] + +## 反模式 +- ❌ [错误做法]: [为什么错] + +## 诚实边界 +- 本 Skill 适用于 [场景] +- 不适用于 [场景] +``` + +#### 阶段三：VERIFY（验证） + +**验证方式**（参考 nuwa-skill Phase 4 + Hermes 幻觉门控）： + +1. **已知场景回测**：用 3 个历史类似任务测试 Skill 是否给出正确建议 +2. **未知场景测试**：用 1 个新场景测试 Skill 是否表现出适度不确定性 +3. **Coordinator 审核**：庞统审查 Skill 的逻辑合理性 +4. **自动格式验证**：JSON Schema 校验 Skill 结构完整性 + +**验证通过** → status = "verified"，写入 Skill Store +**验证失败** → 回到 DISTILL 重新蒸馏或丢弃 + +#### 阶段四：APPLY（应用） + +**反哺机制**： + +| 应用方式 | 触发时机 | 机制 | +|---------|---------|------| +| Context 注入 | Agent 接受节点任务时 | 在任务 prompt 中注入相关 Skill 的摘要 | +| FTS5 搜索 | Agent 遇到困难时 | Agent 可主动搜索历史经验 | +| Planner 参考 | Coordinator 分解任务时 | 参考历史类似任务的经验 | +| Guardrail 规则 | 黑板写入时 | 经验转化为 guardrail 规则 | + +**关键设计**： +- 不是所有经验都注入 context（token 成本） +- 按相关性排序，只注入 top-K 相关经验 +- 经验注入是建议性的，不强制 Agent 遵循 + +#### 阶段五：IMPROVE（进化） + +**进化机制**（参考 Hermes skill self-improvement + nuwa-skill Darwin 棘轮机制）： + +1. **使用反馈收集**：Skill 被引用时，记录 Agent 是否采纳了建议 +2. **效果追踪**：采纳 Skill 建议的任务 vs 未采纳的任务，成功率对比 +3. **定期回顾**：Coordinator 定期审查 Skill Store，淘汰低效 Skill +4. **棘轮机制**：Skill 只能进化为更好的版本，改进才保留，退化自动回退 + +**Skill 生命周期**： +``` +discovered → distilled → verified → active → deprecated + ↑ │ + └── improved ┘ +``` + +#### 黑板 experiences 表设计 + +```json +{ + "table": "experiences", + "schema": { + "experience_id": "string (uuid)", + "source": "enum(node_output, coordinator_review, error_correction, collaboration)", + "task_id": "string (foreign key to tasks)", + "node_id": "string", + "timestamp": "datetime", + "tags": "string[]", + "raw_summary": "text (一级蒸馏结果)", + "skill_id": "string|null (关联的 Skill)", + "status": "enum(discovered, distilled, verified, active, deprecated)", + "usage_count": "integer (被引用次数)", + "effectiveness_score": "float|null (效果评分 0-1)", + "verified_at": "datetime|null", + "verified_by": "string|null" + } +} +``` + +### 2.5 实施优先级 + +| 优先级 | 机制 | 复杂度 | 价值 | +|-------|------|-------|------| +| P0 | 一级蒸馏（任务完成自动提取） | 低 | 高 | +| P0 | experiences 表写入 | 低 | 高 | +| P1 | 幻觉门控 + 心跳检测（系统保护） | 中 | 高 | +| P1 | Coordinator must_haves 定义 | 低 | 高 | +| P2 | 二级蒸馏（周期性 Skill 生成） | 高 | 高 | +| P2 | FTS5 搜索 + Context 注入 | 中 | 中 | +| P3 | Skill 进化 + 棘轮机制 | 高 | 中 | +| P3 | Guardrails 自动生成 | 高 | 中 | + +--- + +## 附录：项目参考链接 + +| 项目 | 链接 | 核心价值 | +|------|------|---------| +| Hermes v0.13 | https://github.com/NousResearch/hermes-agent | 系统级韧性机制（心跳/僵尸/幻觉门控）+ 闭环学习 | +| Claude Code Agent Teams | https://code.claude.com/docs/en/agent-teams | Lead coordinator 模式 + subagent 编排 | +| Claude Code Memory | https://code.claude.com/docs/en/memory | 四类记忆法 | +| Claude Code Subagents | https://code.claude.com/docs/en/sub-agents | 自定义 subagent + coordinator 定义 | +| GSD (get-shit-done) | https://github.com/gsd-build/get-shit-done | Wave Execution + Planner/Executor/Verifier | +| OpenAI Agent SDK Guardrails | https://openai.github.io/openai-agents-python/guardrails/ | Input/Output guardrails + tripwire | +| MetaGPT | https://github.com/FoundationAgents/MetaGPT | SOP 编码 + 角色协作 | +| nuwa-skill | https://github.com/alchaincyf/nuwa-skill | 五阶段蒸馏管线 + Cognitive DNA | +| claude-mem | https://github.com/thedotmack/claude-mem | 持久记忆 + 三层检索 | diff --git a/docs/research/v2.6-research-02-eventdriven-context.md b/docs/research/v2.6-research-02-eventdriven-context.md new file mode 100644 index 0000000..25bf42a --- /dev/null +++ b/docs/research/v2.6-research-02-eventdriven-context.md @@ -0,0 +1,679 @@ +# 调研报告：事件驱动架构 + 上下文管理策略 + +**版本**: v1.0 +**作者**: 庞统（副军师） +**日期**: 2026-05-15 +**范围**: moziplus v2.6 AI Native DevOps 平台 + +--- + +## 课题 2：事件驱动架构 + 并行/串行决策 + +### 1. 已有经验（知识库/wiki） + +在 `~/.openclaw/sanguo_projects/sanguo_moziplus/docs/design/` 中有完整的架构设计文档： + +| 文档 | 关键内容 | +|------|----------| +| `architecture-v2.6.md` | 当前 v2.6 使用 60s polling tick 轮询黑板，Daemon tick 读取黑板状态→发现需要介入的→spawn agent | +| `technical-design-v2.6.md` | Daemon ticker.py 实现了 tick 循环主逻辑，含 @mention 解析、session 管理、健康检查 | + +**当前痛点**： +- Agent 被 @mention 后最多等 60 秒才知道（polling 间隔） +- Daemon tick 是重量级操作（读全量黑板、检查所有任务、处理所有 mention） +- 没有即时响应能力，用户紧急操作只能靠手动触发 tick + +### 2. 业界优秀实践对比表 + +| 项目 | 通知机制 | 事件类型 | 依赖解析 | 并行/串行决策 | 亮点 | +|------|----------|----------|----------|--------------|------| +| **open-multi-agent** | 事件驱动 TaskQueue（`task:ready` 事件自动触发下游） | `task:ready`, `task:complete`, `task:error` | 拓扑排序（topological sort），complete→自动解锁下游 pending 任务 | **依赖声明驱动**：depends_on 声明后自动判断并行/串行 | 3 个运行时依赖，零基础设施，纯 TypeScript EventEmitter | +| **Network-AI** | 原子黑板信号（propose→validate→commit + file-backed mutex） | `propose`, `validate`, `commit`, `rollback` | 无显式依赖图，通过原子提交保证一致性 | Agent 自行判断并行（信号锁机制防竞态） | 零外部依赖，251 个测试，12 框架适配器 | +| **Hermes Kanban** | Dispatcher 60s polling tick（与 v2.6 相同） | 状态变化 + comment + mention | 7 状态完整状态机 | Dispatcher 调度决定并行/串行 | 成熟稳定，但同样受限于 polling 延迟 | +| **Claude Code Agent Teams** | 共享任务列表 + 直接消息（SendMessage tool） | `task:claimed`, `task:completed`, message | 无显式依赖图 | Agent 自主认领（先到先得） | 每个 agent 独立 1M token context window，通过消息通信 | +| **GSD (Get-Shit-Done)** | Wave-based 执行，阶段式推进 | Plan 级事件（phase complete） | Plan 中声明 `depends_on` 和 `wave` 编号 | **Wave 执行**：同 wave 并行，跨 wave 串行 | 每个 executor 独立 200K token 新鲜上下文，消除 context rot | +| **Confluent 事件驱动模式** | Kafka 事件流 | `AgentTaskSubmitted`, `AgentResultPublished` | DAG 依赖声明 | Event Router 根据依赖图路由 | 4 种模式：链式、广播-聚合、动态路由、竞技 | +| **Azure Agent Patterns** | 多种：顺序/并发/群聊/交接 | 按模式定义 | Workflow pattern 支持依赖图 | **编排模式选择**：sequential vs concurrent vs group-chat | 最完整的模式分类 | + +### 3. 重点项目深度分析 + +#### 3.1 open-multi-agent — 事件驱动 TaskQueue + +**核心机制**：`TaskQueue` 是一个可变、事件驱动的队列，支持拓扑依赖解析。 + +```typescript +// queue.ts 核心逻辑 +// Tasks enter in 'pending' state. +// Queue promotes them to 'blocked' when unresolved dependencies exist. +// When dependencies resolve → back to 'pending', firing 'task:ready' +// When task completes → auto-unlock downstream dependent tasks +``` + +**关键设计**： +1. **事件类型**：`task:ready`（依赖满足）、`task:complete`（任务完成）、`task:error`（任务失败） +2. **自动解锁**：当 task complete 时，自动检查所有依赖于它的 pending 任务，如果依赖全部满足，触发 `task:ready` +3. **并行决策**：纯依赖声明驱动——没有依赖关系的任务自然并行执行 +4. **零基础设施**：纯 EventEmitter，不依赖 Redis/Kafka/数据库 + +**对我们的启示**： +- **complete→auto-unlock** 是核心模式，替代 polling tick 的"检查依赖是否满足" +- 依赖声明优于 Agent 自行判断并行性 +- 事件驱动不一定要引入消息队列基础设施 + +#### 3.2 Network-AI — 原子黑板信号 + +**核心机制**：propose→validate→commit 三阶段原子提交，file-backed mutex 防竞态。 + +``` +1. Agent 调用 propose(key, value) → 写入 .proposed 文件 +2. validate() → 检查约束条件（其他 agent 没有冲突 propose） +3. commit() → 原子性写入最终状态 +4. 失败 → rollback() → 清理 .proposed 文件 +``` + +**关键设计**： +1. **信号机制**：通过文件系统信号（`.proposed`、`.committed`）通知其他 Agent +2. **原子性保证**：flock 文件锁 + 三阶段提交 = 无竞态 +3. **零外部依赖**：不需要 Redis/数据库做分布式锁 +4. **251 个测试**：竞态条件覆盖充分 + +**对我们的启示**： +- 我们的 SQLite CAS（claim_task 的原子 UPDATE WHERE）已经实现了类似功能 +- 三阶段提交模式适合"产出审核"场景（propose 产出 → 庞统 validate → commit 到黑板） +- 文件系统信号可以作为轻量级通知机制的灵感 + +#### 3.3 Hermes Kanban — 当前 v2.6 的参考 + +**核心机制**：Dispatcher 60s tick + SQLite 黑板 + 7 状态机。 + +``` +Dispatcher loop (every 60s): + 1. Reclaim stale claims（超时回收） + 2. Promote ready tasks（依赖满足 → 推进状态） + 3. Atomically claim（原子认领） + 4. Spawn assigned profiles（spawn agent） +``` + +**与 v2.6 的对比**：我们的设计直接参考了 Hermes，但 Hermes 本身也有 polling 延迟问题。Hermes 提供了 `Nudge dispatcher` 手动触发来缓解。 + +### 4. 事件类型定义 + +基于所有调研项目，我们需要的核心事件类型： + +| 事件类型 | 触发条件 | 消费者 | 优先级 | +|---------|---------|--------|--------| +| `task_created` | 任何 Agent 创建任务 | Daemon（检查是否需要 spawn） | 中 | +| `task_claimed` | Agent 认领任务 | Daemon（更新 agent 状态） | 低 | +| `task_completed` | Agent 完成任务 | Daemon（解锁下游依赖 + spawn 下一环） | **高** | +| `task_failed` | Agent 任务失败 | Daemon（重试逻辑 + 通知庞统） | 高 | +| `task_blocked` | Agent 请求帮助 | Daemon（spawn 被提及的人） | 高 | +| `comment_added` | 评论写入 | Daemon（检查 @mention） | **高** | +| `output_written` | 产出写入 | Daemon（通知相关方） | 中 | +| `@mention` | 评论中提及 Agent | Daemon（立即 spawn 被提及者） | **最高** | +| `user_action` | 用户在黑板上的操作 | Daemon（立即响应） | **最高** | + +### 5. 通知机制对比 + +| 方案 | 延迟 | 复杂度 | 依赖 | 适用场景 | +|------|------|--------|------|----------| +| **Polling（当前）** | ≤60s | 最低 | 无 | 简单场景，容忍延迟 | +| **SQLite update_hook** | ~0ms（进程内） | 低 | sqlite3 C API | Daemon 内部事件触发 | +| **文件系统 watch（inotify/FSEvents）** | ~ms | 中 | OS 原生 | 跨进程通知 | +| **SQLite WAL file watch** | ~ms | 中 | fswatch/watchdog | 跨进程 SQLite 变更通知 | +| **Unix socket / Named pipe** | ~ms | 中 | 无 | 本地进程间通信 | +| **Redis pub/sub** | ~ms | 中 | Redis | 分布式场景 | +| **Signal file + polling** | ≤1s | 最低 | 无 | 混合方案 | +| **asyncio.Event（进程内）** | ~0ms | 最低 | 无 | Daemon 进程内部 | + +### 6. 推荐方案：分层事件驱动（结合 AI Native 目标） + +#### 6.1 核心思路：不引入重依赖，进程内事件 + 轻量跨进程信号 + +``` +┌─────────────────────────────────────────────────┐ +│ Daemon (Python asyncio) │ +│ │ +│ ┌─────────────┐ ┌──────────────────────┐ │ +│ │ EventBus │ │ Tick Loop (fallback) │ │ +│ │ (asyncio) │ │ 30s 轮询兜底 │ │ +│ └──────┬──────┘ └──────────────────────┘ │ +│ │ │ +│ Agent 操作黑板时： │ +│ 1. 写入 SQLite（当前逻辑不变） │ +│ 2. 写入 signal file（通知 daemon） │ +│ 3. Daemon 检测到信号 → 立即触发事件处理 │ +└─────────────────────────────────────────────────┘ +``` + +#### 6.2 具体实现 + +**Layer 1：进程内 EventBus（asyncio）** + +```python +import asyncio +from enum import Enum +from dataclasses import dataclass +from typing import Callable, Awaitable + +class EventType(str, Enum): + TASK_CREATED = "task_created" + TASK_CLAIMED = "task_claimed" + TASK_COMPLETED = "task_completed" + TASK_FAILED = "task_failed" + TASK_BLOCKED = "task_blocked" + COMMENT_ADDED = "comment_added" + OUTPUT_WRITTEN = "output_written" + USER_ACTION = "user_action" + +@dataclass +class Event: + type: EventType + task_id: str | None + agent: str | None + detail: dict | None + +class EventBus: + def __init__(self): + self._handlers: dict[EventType, list[Callable]] = {} + self._queue: asyncio.Queue[Event] = asyncio.Queue() + + def on(self, event_type: EventType, handler: Callable): + self._handlers.setdefault(event_type, []).append(handler) + + async def emit(self, event: Event): + await self._queue.put(event) + + async def start(self): + """主事件循环""" + while True: + event = await self._queue.get() + handlers = self._handlers.get(event.type, []) + for handler in handlers: + try: + await handler(event) + except Exception as e: + logger.error(f"Event handler error: {e}") + + async def emit_from_blackboard_op(self, event_type: EventType, task_id: str, + agent: str, detail: dict = None): + """黑板操作后触发事件""" + await self.emit(Event(type=event_type, task_id=task_id, agent=agent, detail=detail)) +``` + +**Layer 2：Signal File 跨进程通知** + +```python +import os +from pathlib import Path + +SIGNAL_DIR = Path("~/.sanguo_projects/sanguo_moziplus_v2/signals") + +async def write_signal(event_type: str, task_id: str = None, agent: str = None): + """Agent（外部进程）写入信号文件""" + signal_file = SIGNAL_DIR / f"{event_type}.signal" + payload = f"{task_id or ''}:{agent or ''}:{time.time()}" + signal_file.write_text(payload) + +async def watch_signals(): + """Daemon 监听信号文件""" + while True: + for signal_file in SIGNAL_DIR.glob("*.signal"): + if signal_file.exists(): + payload = signal_file.read_text() + parts = payload.split(":") + event_type = signal_file.stem + await event_bus.emit(Event( + type=EventType(event_type), + task_id=parts[0] or None, + agent=parts[1] or None, + detail=None + )) + signal_file.unlink() # 处理完删除 + await asyncio.sleep(0.5) # 500ms 检查间隔（比 60s 好 120 倍） +``` + +**Layer 3：Fallback Tick（30s 兜底）** + +保留简化版 tick 循环，30s 一次（从 60s 降为 30s），只处理： +- 健康检查（zombie 检测、stale 任务回收） +- 信号遗漏兜底（万一 signal file 处理失败） + +#### 6.3 事件处理优先级 + +```python +# 高优先级事件：立即 spawn +HIGH_PRIORITY = { + EventType.TASK_COMPLETED, # 解锁下游 + EventType.TASK_FAILED, # 触发重试 + EventType.TASK_BLOCKED, # 请求帮助 + EventType.COMMENT_ADDED, # 可能含 @mention + EventType.USER_ACTION, # 用户操作 +} + +# 低优先级事件：排队处理 +LOW_PRIORITY = { + EventType.TASK_CREATED, + EventType.TASK_CLAIMED, + EventType.OUTPUT_WRITTEN, +} +``` + +### 7. 并行/串行决策推荐 + +#### 7.1 决策矩阵 + +| 场景 | 并行/串行 | 决策依据 | 示例 | +|------|----------|---------|------| +| 无依赖任务 | **并行** | `depends_on` 为空 | 赵云下载数据 + 庞统写方案 | +| 有依赖任务 | **串行** | `depends_on` 声明 | 先下载数据 → 再回测 | +| 同一任务冲突 | **串行**（先到先得） | SQLite CAS | 张飞和关羽抢同一个 review | +| 产出审核 | **串行**（完成→审核→通过） | 状态机 | 张飞完成 → 司马懿审核 | +| 独立研究 | **并行** | 无交集的子任务 | 多个因子独立调研 | +| 同文件修改 | **串行** | 文件路径冲突检测 | 不能两人同时改同一个文件 | + +#### 7.2 推荐策略：**依赖声明优先，Daemon 辅助仲裁** + +1. **显式依赖**：任务创建时声明 `depends_on`（庞统/创建者负责声明） +2. **自动并行**：`depends_on` 为空且 `assignee` 不同的任务，自动并行 spawn +3. **自动串行**：有 `depends_on` 的任务，上游完成事件触发下游 spawn +4. **冲突检测**：如果两个任务的 `files_modified` 有交集，Daemon 警告并建议串行 +5. **庞统仲裁**：争议场景 spawn 庞统决定 + +```python +async def on_task_completed(event: Event): + """任务完成 → 解锁下游依赖""" + task_id = event.task_id + + # 查找所有依赖于该任务的 blocked 任务 + downstream = db.query( + "SELECT * FROM tasks WHERE status='pending' AND depends_on LIKE ?", + (f'%{task_id}%',) + ) + + for task in downstream: + deps = json.loads(task['depends_on']) + # 检查所有依赖是否都完成了 + all_done = all( + db.query("SELECT status FROM tasks WHERE id=?", (d,))[0]['status'] == 'done' + for d in deps + ) + if all_done: + # 自动解锁：触发 task:ready + await event_bus.emit(Event( + type=EventType.TASK_READY, + task_id=task['id'], + agent=task['assignee'], + )) + # 立即 spawn 对应 agent + await spawn_agent(task['assignee'], f"任务 {task['id']} 依赖已满足，请查看并认领。") +``` + +--- + +## 课题 10：上下文管理策略 + +### 1. 黑板信息量具体测算 + +基于 `architecture-v2.6.md` 中的 SQLite Schema，逐项测算： + +#### 1.1 一个任务基础信息（tasks 表） + +``` +字段 典型内容 估算 tokens +───────────────────────────────────────────────────────────────────── +id "task-001" 1 +title "动量因子策略回测" 5 +description "对动量因子进行历史回测，验证策略有效性" 20 +status "working" 1 +assignee "zhangfei-dev" 2 +assigned_by "pangtong-fujunshi" 2 +depends_on ["task-001", "task-002"] 5 +parent_task "task-000" 1 +priority 5 1 +task_type "coding" 1 +created_at "2026-05-15 09:00:00" 3 +updated_at "2026-05-15 10:30:00" 3 +claimed_at "2026-05-15 09:05:00" 3 +started_at "2026-05-15 09:10:00" 3 +deadline "2026-05-16 18:00:00" 3 +retry_count 0 1 +───────────────────────────────────────────────────────────────────── +小计（结构化格式） ~50-60 tokens +``` + +**一个任务基础信息 ≈ 50-60 tokens** + +#### 1.2 评论（10 条，comments 表） + +``` +每条评论典型内容： + "张飞，你的实现方案我看了，回测数据量大时内存会爆。关羽，从风控角度也看看？ + @关羽 @张飞" + + author + created_at + mentions JSON + ≈ 30-50 tokens/条 + +10 条评论 ≈ 300-500 tokens +``` + +#### 1.3 产出（5 个，outputs 表） + +``` +每个产出典型内容： + output_type: "code" + title: "分批加载实现" + content_path: "task-001/output-zhangfei-v2.md" + summary: "实现分批加载，单批50万条" + metadata: {"files_changed": 3, "lines_added": 150} + + agent + created_at + ≈ 30-50 tokens/个 + +5 个产出 ≈ 150-250 tokens +``` + +#### 1.4 事件日志（10 条，events 表） + +``` +每条事件： + event_type: "task_claimed" + agent: "zhangfei-dev" + detail: {"from": "pending", "reason": null} + + created_at + ≈ 15-25 tokens/条 + +10 条事件 ≈ 150-250 tokens +``` + +#### 1.5 决策记录（3 条，decisions 表） + +``` +每条决策： + decision: "使用分批加载而非流式" + rationale: "流式需要改底层框架，分批只需改回测模块" + alternatives: ["流式加载", "内存映射"] + ≈ 40-80 tokens/条 + +3 条决策 ≈ 120-240 tokens +``` + +#### 1.6 观察记录（3 条，observations 表） + +``` +每条观察： + severity: "warning" + body: "止损逻辑在分批模式下可能漏触发" + ≈ 20-30 tokens/条 + +3 条观察 ≈ 60-90 tokens +``` + +#### 1.7 总计 + +| 组件 | 数量 | 估算 tokens | +|------|------|-------------| +| 任务基础信息 | 1 个 | 50-60 | +| 评论 | 10 条 | 300-500 | +| 产出 | 5 个 | 150-250 | +| 事件日志 | 10 条 | 150-250 | +| 决策记录 | 3 条 | 120-240 | +| 观察记录 | 3 条 | 60-90 | +| **总计** | | **830-1390 tokens** | +| + JSON 格式开销（花括号、引号） | | ~150-200 tokens | +| + 提示词格式（标题、分隔符） | | ~100-150 tokens | +| **实际传给 LLM 的总量** | | **~1100-1750 tokens** | + +**关键结论：一个典型任务的全量黑板信息约 1100-1750 tokens。** + +极端情况（30 条评论、10 个产出、50 条事件）： +- 评论：30 × 40 = 1200 tokens +- 产出：10 × 40 = 400 tokens +- 事件：50 × 20 = 1000 tokens +- 总计约 3000-4000 tokens + +**即使极端情况也在 4000 tokens 以内，远小于 200K context window。** + +但是——如果有多个任务（比如庞统规划了 5 个子任务），5 个任务 × 1500 tokens = 7500 tokens，仍然可控。 + +**真正的问题不是单个任务的黑板信息，而是**： +1. 产出物文件内容（code diff、分析报告）可能很大 +2. 长讨论线程（30+ 评论来回讨论） +3. Agent 的 system prompt + SOUL.md + skill 文件已经占用大量 context + +### 2. 业界优秀实践对比表 + +| 项目 | 上下文策略 | 核心机制 | 优点 | 缺点 | +|------|-----------|----------|------|------| +| **Claude Code** | Auto-compact + file reference | 1) 自动压缩：接近 context limit 时先清 tool output，再 summarize 对话 2) `/compact` 手动压缩 3) `@file` 引用而非内联 4) CLAUDE.md 持久记忆 | 成熟稳定，官方支持 | 压缩可能丢失细节；单一 session 内累积 | +| **Claude Code Agent Teams** | 每个 Agent 独立 1M token context | 隔离 context window + 共享任务列表 + SendMessage 直接通信 | 天然隔离，无 context rot 问题 | 跨 agent 通信开销 | +| **GSD (Get-Shit-Done)** | Wave Execution：每个 plan 独立新鲜 200K context | 1) Plan 分 wave 执行 2) 每个 executor 新鲜 context 3) 原子 git commit 4) 主 context 保持 30-40% | 彻底消除 context rot | 需要精确的 plan 分解 | +| **Network-AI** | 原子黑板（数据在黑板，不在 context） | Agent 只读黑板摘要，详细数据在文件中 | context 极小 | 需要额外读取操作 | +| **Hermes Kanban** | kanban_show() 按需读取 | Agent 只看当前任务看板，不全量读取 | 简单有效 | 可能遗漏全局信息 | +| **Agent Chorus** | Checkpoint + 跨 Agent 消息 | Standup drain inbox + conclude broadcast + checkpoint 状态广播 | 跨框架兼容 | 复杂度较高 | +| **Opal-Bridge** | Cross-agent session translator | Claude Code ↔ Codex CLI 格式转换 | 多工具协作 | 范围有限 | +| **MindStudio** | 三层内存：工作/短期/长期 | Working（当前会话）+ Short-term（任务级）+ Long-term（项目级） | 分层清晰 | 需要额外基础设施 | + +### 3. 重点项目深度分析 + +#### 3.1 Claude Code — Auto-compact + File Reference + +**核心机制**： + +1. **自动压缩（Auto-compact）**： + - 当 context 使用接近 limit 时，先清除旧 tool output + - 然后自动 summarize 对话历史 + - 用户可通过 CLAUDE.md 自定义压缩策略（如 "压缩时保留修改文件列表和测试命令"） + - `/compact` 手动触发，`/compact "保留所有类型定义"` 可带自定义指令 + +2. **文件引用（@-reference）**： + - 用 `@file_path` 引用文件内容，而非内联到对话中 + - LLM 按需读取，避免全量加载 + +3. **CLAUDE.md 持久记忆**： + - 项目级（`CLAUDE.md`）+ 用户级（`~/.claude/CLAUDE.md`） + - 每次 session 启动自动加载 + - 相当于 L1 核心信息 + +**对我们的启示**： +- 产出的详细内容不应放在黑板 context 中，只放摘要 + 文件路径引用 +- Agent 读取产出时应按需 read 文件，不全量注入 context + +#### 3.2 GSD (Get-Shit-Done) — Wave Execution + +**核心机制**： + +``` +/gsd:execute-phase N +├── 分析 plan 依赖关系 +├── Wave 1（无依赖的 plan）： +│ ├── Executor A（新鲜 200K context）→ commit +│ └── Executor B（新鲜 200K context）→ commit +├── Wave 2（依赖 Wave 1）： +│ └── Executor C（新鲜 200K context）→ commit +└── Verifier（检查所有产出） +``` + +**关键数据**： +- 主 context 始终保持在 30-40%（因为重活在 subagent 中做） +- 每个 executor 独立 200K token，不做压缩（新鲜 context 不需要） +- 每个 plan 一个原子 git commit（可回滚） + +**对我们的启示**： +- **我们的 Agent spawn 模式天然就是 Wave Execution**：Daemon spawn 隔离 session，每个 agent 独立 context +- 关键是 spawn 时传多少上下文——传太多浪费，传太少丢信息 +- 产出写入黑板摘要 + 文件路径，下一个 agent 按需读取 + +#### 3.3 Opal-Bridge — Cross-Agent Session Translator + +**核心机制**：将 Claude Code 的 session 格式转换为 Codex CLI 的格式，实现跨工具接力。 + +**Fidelity 概念**（从 cross_agent_session_resumer 项目借鉴）： +- **Native fidelity**：保留原始格式的完整信息 +- **Lossy export**：转换为通用格式时丢失部分信息 +- **Checkpoint**：关键节点快照 + +**对我们的启示**： +- Agent 之间的"接力"需要定义标准化的交接格式 +- 不是所有信息都需要完整传递——关键是决策、产出摘要、未完成事项 + +### 4. 推荐方案：分层传递策略 + +#### 4.1 三层信息架构 + +``` +┌─────────────────────────────────────────────────────┐ +│ L1: 核心信息（必须传入，~200-400 tokens） │ +│ ─────────────────────────────────────────────────── │ +│ • 任务 ID + 标题 + 状态 │ +│ • 任务描述（description） │ +│ • 我的角色 + 触发原因（为什么 spawn 我） │ +│ • 依赖任务的状态摘要（1 行/任务） │ +│ • 最近 3 条评论摘要 │ +│ │ +│ 传递方式：spawn message 中直接写入 │ +│ 保证：任何 Agent 都能在 L1 信息下开始工作 │ +├─────────────────────────────────────────────────────┤ +│ L2: 扩展信息（按需读取，~500-1500 tokens） │ +│ ─────────────────────────────────────────────────── │ +│ • 完整评论线程 │ +│ • 产出摘要列表（title + summary，不含详细内容） │ +│ • 决策记录 │ +│ • 观察记录 │ +│ • 其他相关任务摘要 │ +│ │ +│ 传递方式：Agent 通过 CLI 按需读取 │ +│ CLI: blackboard.py read --task task-001 --level L2 │ +├─────────────────────────────────────────────────────┤ +│ L3: 全量信息（按需读取，不限制大小） │ +│ ─────────────────────────────────────────────────── │ +│ • 产出物文件完整内容 │ +│ • 完整事件日志 │ +│ • 所有子任务详情 │ +│ │ +│ 传递方式：文件路径引用，Agent 用 read 工具读取 │ +│ 黑板只存 content_path，不存文件内容 │ +└─────────────────────────────────────────────────────┘ +``` + +#### 4.2 Agent Spawn 时的上下文模板 + +```python +def build_spawn_message_L1(task_id: str, agent_id: str, trigger: str) -> str: + """L1 核心：~200-400 tokens，直接写入 spawn message""" + task = get_task(task_id) + deps_status = [] + for dep_id in json.loads(task['depends_on'] or '[]'): + dep = get_task(dep_id) + deps_status.append(f" {dep_id}: {dep['status']} - {dep['title']}") + + recent_comments = get_comments(task_id, limit=3) + comments_str = "" + for c in recent_comments: + comments_str += f" [{c['created_at'][:16]} {c['author']}] {c['body'][:100]}\n" + + return f"""黑板任务通知（L1）： +任务：{task['title']}（{task['id']}） +状态：{task['status']} +类型：{task['task_type']} +触发原因：{trigger} +描述：{task['description'] or '（无）'} + +依赖状态： +{chr(10).join(deps_status) if deps_status else ' （无依赖）'} + +最近评论： +{comments_str if comments_str else ' （无评论）'} + +请使用以下命令获取更多信息： + L2（扩展）：blackboard.py read --task {task_id} --level L2 + L3（全量产出）：blackboard.py read --task {task_id} --type outputs +""" +``` + +#### 4.3 黑板上的信息分层规则 + +| 信息类别 | 存储位置 | 黑板上展示 | 说明 | +|---------|---------|-----------|------| +| 任务元数据 | 黑板 tasks 表 | 完整 | ID、标题、状态、描述、分配、依赖 | +| 评论 | 黑板 comments 表 | 完整 | 所有评论保留，L2 读取 | +| 产出摘要 | 黑板 outputs 表 | title + summary + path | 详细内容在文件中 | +| 产出详细内容 | 文件系统 | 仅文件路径 | Agent 按需 read | +| 决策记录 | 黑板 decisions 表 | 完整 | L2 读取 | +| 观察记录 | 黑板 observations 表 | 完整 | L2 读取 | +| 事件日志 | 黑板 events 表 | 仅最近 10 条 | L3 按需查询 | + +#### 4.4 后接 Agent 无缝接力的关键 + +1. **产出物标准化**：每个产出必须包含 `summary`（一句话摘要）+ `content_path`（文件路径），不存大段文本 +2. **决策必须记录**：Agent 的关键决策写入 decisions 表，后继者可通过 L2 了解"为什么这么做" +3. **未完成事项显式化**：Agent 结束前在评论中写 "未完成：XXX"，后继者一目了然 +4. **触发原因明确**：Daemon spawn 时必须说明为什么 spawn（@mention / 依赖满足 / 用户指令） + +### 5. Context 预算分配建议 + +假设使用 128K context window 的模型（如 gpt-4o / claude-3.5）： + +| 组件 | 预算 | 说明 | +|------|------|------| +| System Prompt + SOUL.md + IDENTITY.md | ~3000-5000 tokens | 固定开销 | +| Skills + AGENTS.md | ~2000-4000 tokens | 固定开销 | +| L1 spawn message | ~300-500 tokens | 任务核心信息 | +| L2 黑板扩展信息（按需） | ~500-1500 tokens | 完整讨论、决策 | +| L3 产出物文件（按需） | ~2000-10000 tokens | 代码/报告内容 | +| 工作空间（Agent 思考+输出） | ~30000-50000 tokens | 预留给 Agent 实际工作 | +| **总计** | ~40K-70K tokens | 远小于 128K，安全 | + +**关键结论**：我们的黑板信息量远小于 context window 限制，**不需要做复杂的压缩/摘要**。核心策略是： + +1. **L1 必传**：~300-500 tokens，任何场景都负担得起 +2. **L2 按需**：Agent 自己决定是否需要深入了解讨论/决策 +3. **L3 文件引用**：大内容只在文件中，黑板只存路径 + +--- + +## 总结与行动建议 + +### 课题 2 行动建议（事件驱动） + +| 优先级 | 行动 | 工作量 | +|--------|------|--------| +| P0 | 实现 asyncio EventBus 进程内事件总线 | 1 天 | +| P0 | 实现 Signal File 跨进程通知（Agent→Daemon） | 0.5 天 | +| P1 | 事件处理：task_completed → 解锁下游依赖 | 0.5 天 | +| P1 | 事件处理：comment_added → @mention 检测 | 0.5 天 | +| P2 | 保留 30s fallback tick（健康检查） | 0 天（简化现有 tick） | +| P2 | files_modified 冲突检测 | 1 天 | + +**预期效果**： +- @mention 响应从 ≤60s 降到 ≤1s +- 任务依赖解锁从 ≤60s 降到 ~0ms（进程内事件） +- 不引入任何新依赖 + +### 课题 10 行动建议（上下文管理） + +| 优先级 | 行动 | 工作量 | +|--------|------|--------| +| P0 | 定义 L1/L2/L3 分层读取 API | 0.5 天 | +| P0 | 实现 L1 spawn message 模板 | 0.5 天 | +| P1 | 产出物只存摘要+路径的规范落地 | 0 天（已在 schema 中） | +| P2 | blackboard.py read --level L2 实现 | 0.5 天 | +| P2 | Agent 规范：结束前写未完成事项 | 0 天（文档规范） | + +**核心原则**： +- 黑板是索引（做什么 + 在哪找），不是仓库（详细内容） +- 产出物在文件中，黑板只存路径 +- Agent spawn 时传最小充分上下文（L1），按需获取更多（L2/L3） +- 不做复杂压缩——信息量本身就很小 + +--- + +## 参考项目索引 + +| 项目 | URL | 关键参考价值 | +|------|-----|-------------| +| open-multi-agent | github.com/JackChen-me/open-multi-agent | 事件驱动 TaskQueue + 依赖自动解锁 | +| Network-AI | github.com/jovanSAPFIONEER/Network-AI | 原子黑板 propose→validate→commit | +| Hermes Kanban | github.com/NousResearch/hermes-agent | 60s tick + SQLite 黑板 + 状态机 | +| GSD (Get-Shit-Done) | github.com/gsd-build/get-shit-done | Wave Execution + 新鲜 context | +| Claude Code | code.claude.com | Auto-compact + file reference + agent teams | +| Agent Chorus | github.com/cote-star/agent-chorus | 跨 Agent checkpoint + 消息传递 | +| Azure Agent Patterns | learn.microsoft.com | 编排模式分类（sequential/concurrent/handoff） | +| Confluent 事件驱动 | confluent.io/blog | 4 种事件驱动多 Agent 模式 | diff --git a/docs/research/v2.6-research-03-challenge-quality.md b/docs/research/v2.6-research-03-challenge-quality.md new file mode 100644 index 0000000..25883b2 --- /dev/null +++ b/docs/research/v2.6-research-03-challenge-quality.md @@ -0,0 +1,928 @@ +# 调研报告：挑战/评审体系 + 质量门控结构化 + +**日期**: 2026-05-15 +**作者**: 庞统士元 (pangtong-fujunshi) +**版本**: v2.6-research-03 +**用途**: moziplus v2.6 AI Native DevOps 平台设计参考 + +--- + +## 目录 + +- [课题 3：挑战/评审体系设计](#课题-3挑战评审体系设计) + - [已有经验](#已有经验知识库wiki--v10-三层实践) + - [业界优秀实践对比表](#业界优秀实践对比表课题3) + - [v1.0 三层体系评估](#v10-三层体系评估) + - [推荐方案](#推荐方案课题3) +- [课题 5：质量门控结构化](#课题-5质量门控结构化) + - [业界优秀实践对比表](#业界优秀实践对比表课题5) + - [推荐方案：评审结果存储与结构](#推荐方案评审结果存储与结构) + +--- + +## 课题 3：挑战/评审体系设计 + +### 已有经验（知识库/wiki + v1.0 三层实践） + +#### 知识库已有调研 + +我们在 `gate-mechanism-research.md`（2026-05-11）中已经做过一轮质量门控调研，识别出四种模式： + +| 模式 | 代表项目 | 强制力 | 信任模型 | +|------|---------|--------|---------| +| LLM 自律型 | Claude Code、PAV skill | ❌ 弱 | 信任 LLM | +| 角色分工评审 | oh-my-claudecode | ⚠️ 中 | 不信任，靠隔离 | +| Guardrail 中断 | OpenAI Agents SDK | ✅ 强 | 不信任，靠代码 | +| DAG 条件流转 | TradingAgents / LangGraph | ✅ 强 | 不信任，靠结构 | + +**核心结论**（上一轮调研）： +1. 业界共识：不信任 LLM 自律 +2. 检查的是产出，不是过程 +3. Guard 定义与执行分离（声明式规则 + 代码层执行） +4. 失败处理有层级：block → retry → escalate +5. 不同任务类型不同标准 + +#### v1.0 三层挑战控制回顾 + +moziplus v1.0 PRD 定义了三层挑战： + +| 层级 | 机制 | 参与者 | 触发时机 | +|------|------|--------|---------| +| **第 1 层**：Agent 自律 PAV | Plan→Act→Verify skill | 执行者自己 | 每个节点开始时 | +| **第 2 层**：节点 review | 司马懿独立评审 | 司马懿（或挑战者池） | 每个节点完成时 | +| **第 3 层**：最终整合审查 | 庞统汇总 + 司马懿终审 | 庞统 + 司马懿 | 任务完成时 | + +PRD 的铁律 IR-1 规定：**每个任务至少 2 个 Agent（做 + 挑战）**。IR-2 规定：**每个节点都是 Plan → Execute → Validate**。 + +#### v2.6 架构现状 + +v2.6 架构文档中： +- 任务状态流转：`pending → claimed → working → review → done`（review 是状态机中的一个状态） +- review → pending（审核不通过打回）是合法转换 +- 挑战者由庞统在黑板上分配（`assigned_by` 字段） +- 评审结果目前只有 `comments` 表（自然语言评论），缺乏结构化 + +--- + +### 业界优秀实践对比表（课题3） + +#### 1. Superpowers：三阶段审查（implementer → spec reviewer → code quality reviewer） + +**项目**: [obra/superpowers](https://github.com/obra/superpowers) — Agentic Skills Framework for Claude Code + +**核心机制**: + +Superpowers 的 subagent-driven-development 流程采用**两阶段串行审查**（不是三阶段，实际是两个独立 reviewer 串行执行）： + +``` +Implementer subagent 执行任务 + ↓ +Spec Reviewer subagent → 检查实现是否符合计划/需求规格 + ↓ (必须通过) +Code Quality Reviewer subagent → 检查代码质量（clean, tested, maintainable） + ↓ +下一任务 +``` + +**关键设计细节**: + +| 维度 | Spec Reviewer | Code Quality Reviewer | +|------|--------------|----------------------| +| **关注点** | 实现是否匹配计划 | 代码是否干净/可测/可维护 | +| **检查内容** | 功能完整性、与计划偏离、遗漏需求 | 单一职责、接口清晰度、测试覆盖 | +| **模型选择** | 用最强模型 | 用最强模型 | +| **顺序** | 先执行（必须通过） | 后执行（spec 通过后才触发） | +| **失败处理** | 标记偏离，返回给 implementer | 修改建议返回给 implementer | + +**Implementer 报告四种状态**： +- `task_completed` — 完成且无需修改 +- `task_completed_with_notes` — 完成，但有注意事项 +- `task_blocked` — 被阻塞，需要人介入 +- `task_failed` — 失败 + +**关键洞察**: +- **审查粒度是每个任务，不是每个文件** — 每个 subagent 完成一个 engineering task 后立即审查 +- **串行门控** — spec review 必须通过后才做 code quality review，两个是串联的 +- **审查者也是独立 subagent** — 不是同一个 agent 的不同角色，是独立的 spawned agent +- **并行执行但串行审查** — 多个 independent tasks 可以并行执行，但每个 task 的审查是串行的（参考 issue #469） +- **不靠 LLM 自律** — 审查是系统自动触发，不依赖 implementer 自觉 + +#### 2. TradingAgents：多空辩论（Bull↔Bear + Judge 裁决） + +**项目**: [TauricResearch/TradingAgents](https://github.com/TauricResearch/TradingAgents) — Multi-Agent LLM Financial Trading Framework + +**核心机制**: + +TradingAgents 构建了**5 层结构化对抗**： + +``` +[4 位分析师并行] → 各自独立分析 + ↓ +[Bull Researcher ↔ Bear Researcher] → 多空辩论（交替辩论，最多 max_debate_rounds 轮） + ↓ +[Research Manager] → 裁决，综合双方论据 + ↓ +[Trader（3 级风险偏好）] → 根据研究报告做交易决策 + ↓ +[Aggressive ↔ Conservative ↔ Neutral] → 风控三方辩论 + ↓ +[Portfolio Manager] → 最终决策（Buy/Overweight/Hold/Underweight/Sell） +``` + +**关键设计细节**: + +| 维度 | 研究辩论 | 风控辩论 | +|------|---------|---------| +| **参与者** | Bull vs Bear（2 方） | Aggressive vs Conservative vs Neutral（3 方） | +| **轮次控制** | `max_debate_rounds` 限制 | 条件边 `should_continue_debate` | +| **裁决者** | Research Manager | Portfolio Manager | +| **输出** | 综合研究报告 | 最终交易决策 | + +**条件边实现**（LangGraph）： +```python +workflow.add_conditional_edges( + "Bull Researcher", + should_continue_debate, + { + "Bear Researcher": "Bear Researcher", + "Research Manager": "Research Manager" + } +) +``` + +**关键洞察**: +- **结构化对抗 = 特殊的 Exit Gate** — 不是检查产出文件，而是校验**决策质量** +- **辩论机制天然提供多视角审查** — 不需要额外的 reviewer agent +- **条件边让流转逻辑图化、可验证** +- **适用于需要多角度论证的决策场景** — 投资/交易/方案选择 +- **2026-04 v0.2.4 新增**：structured-output agents（Research Manager/Trader/Portfolio Manager），LangGraph checkpoint resume + +#### 3. oh-my-claudecode：ralplan（Planner→Architect→Critic 三方共识） + +**项目**: [Yeachan-Heo/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) — Teams-first Multi-agent orchestration for Claude Code + +**核心机制**: + +ralplan（Radical Planning）编排三个专业 Agent，在迭代循环中达成共识： + +``` +Planner Agent → 输出初始计划 + ↓ +Architect Agent → 从架构视角审查/修正 + ↓ +Critic Agent → 从批判视角挑战 + ↓ +是否达成共识？ + ├── 是 → 输出最终计划 + └── 否 → 回到 Planner，循环继续 +``` + +**三种模式**: + +| 模式 | 命令 | 适用场景 | +|------|------|---------| +| 基础模式 | `ralplan "描述"` | 普通规划 | +| 共识模式 | `ralplan --consensus "描述"` | 重要决策 | +| 深思熟虑模式 | `ralplan --deliberate "描述"` | 高风险场景 | + +**Critic 角色**（继承自 oh-my-claudecode 的 Critic 设计）： + +| 阶段 | 描述 | +|------|------| +| 预判 Pre-commitment | 读代码前先预测 3-5 个最可能的问题 | +| 验证 Verification | 逐一检查每个文件引用和函数调用 | +| 多视角审查 Multi-perspective | 安全/运维/新人三个角度 | +| 缺口分析 Gap analysis | 主动找"缺失的东西" | +| 自审 Self-audit | 低置信度发现降级为 Open Questions | + +**Critic 工具限制**：`disallowedTools: Write, Edit` — 硬编码禁用修改工具，保证评审独立性。 + +**Verdict 只有 4 种**：REJECT / REVISE / ACCEPT-WITH-RESERVATIONS / ACCEPT + +**关键洞察**: +- **三方共识比双方更健壮** — Planner(规划) + Architect(架构) + Critic(批判)，三方相互制衡 +- **共识模式有明确退出条件** — 达成共识或超时 +- **Critic 工具被硬编码禁用** — 不是 prompt 建议，是代码层面的限制 +- **适合规划/设计阶段，不适合执行阶段** — ralplan 产出的是计划，不是代码 +- **每种模式有不同的严谨程度** — 按风险级别选择 + +#### 4. OpenAI Agent SDK：OutputGuardrail + 声明式 Guardrail + +**项目**: [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/guardrails/) — 官方 Agent 框架 + +**核心机制**: + +OpenAI Agent SDK 提供三种 Guardrail： + +| 类型 | 触发时机 | 作用 | +|------|---------|------| +| **Input Guardrail** | Agent 执行前 | 检查输入合法性 | +| **Output Guardrail** | Agent 执行后 | 检查产出达标 | +| **Tool Guardrail** | 每次工具调用前后 | 检查工具调用合法性 | + +**Tripwire 机制**： +```python +@output_guardrail +async def guardrail_fn(ctx, agent, output): + result = await Runner.run(guardrail_agent, output) + return GuardrailFunctionOutput( + tripwire_triggered=result.final_output.is_invalid # True = 立即中断 + ) +``` + +**执行模式**： +- `blocking`（推荐）— Guardrail 先执行，通过后才启动主 Agent +- `parallel` — Guardrail 和主 Agent 同时跑（不适合长任务 Agent，因为 token 已消耗） + +**关键洞察**: +- **Guardrail 本身也是 Agent** — 可以用小模型做快速检查，成本可控 +- **触发 tripwire = 抛异常 = 流程立即停止** — 代码层面的强制执行 +- **声明式定义 + 程序式执行** — 规则声明为函数/配置，执行由框架保证 +- **Input Guardrail 只在第一个 Agent 执行，Output Guardrail 只在最后一个 Agent 执行** +- **Tool Guardrail 粒度最细** — 每次工具调用都可以检查 + +#### 5. 其他优秀实践 + +##### 5.1 Edict 的门下省审核（封驳打回机制） + +**项目**: [cft0808/edict](https://github.com/cft0808/edict) — 三省六部制 Multi-Agent Orchestration + +**核心流程**： +``` +皇上 → 太子分拣 → 中书省规划 → 门下省审议 → 尚书省派发 → 六部执行 → 回奏 + ↑ │ + └── 封驳打回 ─────┘ +``` + +**门下省角色**： +- **质量管控中心** — 对中书省方案进行质量评审、风险识别与标准把控 +- **封驳权** — 不合格方案可直接"封驳"，打回中书省重新规划 +- **状态机**：`已派发 → 执行中 → 待审查 → 已完成`，中间可 `阻塞 Blocked` + +**关键洞察**: +- 封驳打回是一种**方向级否决** — 不只是修改建议，而是"方案不对，重来" +- 门下省是**独立于执行链的审核层** — 不参与执行，只负责审核 +- 类似 moziplus 中司马懿的角色定位 + +##### 5.2 wanman 的评估引擎（三阶段 explore→evaluate→execute） + +**项目**: [chekusu/wanman](https://github.com/chekusu/wanman) — Agent Matrix Runtime + +**核心流程**： +``` +Explore 阶段 → 多 Agent 并行探索，收集方案 + ↓ +Evaluate 阶段 → 评估引擎打分（4 维度加权） + ↓ +Execute 阶段 → 执行最优方案 +``` + +**评估维度**（据 PRD 中描述）： +- **Feasibility**（可行性） +- **Risk**（风险） +- **Impact**（影响） +- **Cost**（成本） + +**信心度机制**：信心度 < 0.7 升级到人工审批。 + +**关键洞察**: +- **量化评估**比定性评估更可追溯 — 4 维度加权打分，不是"感觉行不行" +- **阈值自动升级** — 信心度低于阈值自动升级，不需要人判断 +- **适合方案选择场景** — 多个方案用同一标准评估 + +##### 5.3 SWE-agent 的 RetryLoop（多次尝试 + Reviewer 选最优） + +**项目**: [SWE-agent/SWE-agent](https://github.com/SWE-agent/SWE-agent) — AI Software Engineering Agent + +**核心机制**： + +```yaml +agent: + type: retry + retry_loop: + cost_limit: 6.00 + max_attempts: 3 + agent_configs: + - # 可能用不同的 prompt + - # 可能用不同的 model +``` + +- **多次独立尝试** — 可以用不同配置（prompt/model/参数）尝试多次 +- **预算继承** — 每次尝试继承上一次失败后剩余的预算，不浪费 +- **Reviewer LLM** 选最优 patch（`tools/review_on_submit_m`） +- **Trajectory 审计** — 每次尝试的完整轨迹都保存，可回溯 + +**关键洞察**: +- **多尝试优于单次完美** — LLM 输出有随机性，多次尝试取最优是务实策略 +- **Trajectory 是审计基础** — 完整保留每次尝试的过程，可以对比分析 +- **实际效果**：SWE-agent 团队承认 reviewer 有时"rejects correct patches" — LLM 评审不是万能的 + +#### 综合对比表 + +| 项目 | 审查模式 | 强制力 | 粒度 | 协商轮次 | 失败处理 | 声明式 | +|------|---------|--------|------|---------|---------|--------| +| **Superpowers** | 串行双审（spec→quality） | ✅ 系统触发 | 每任务 | 0（只审不改） | 返回 implementer | ❌ 硬编码 | +| **TradingAgents** | 多空辩论 + 裁决 | ✅ 图结构 | 每决策 | max_debate_rounds | 裁决者决定 | ✅ 条件边 | +| **oh-my-claudecode** | 三方共识循环 | ⚠️ prompt | 规划阶段 | 共识达成 | 循环/超时 | ❌ prompt | +| **OpenAI Agent SDK** | Input/Output Guardrail | ✅ 代码层 | 每工具调用 | 0（tripwire） | 抛异常停止 | ✅ 声明式 | +| **Edict** | 门下省封驳 | ⚠️ 状态机 | 每方案 | 封驳打回 | 打回中书省 | ✅ 状态机 | +| **wanman** | 量化评估打分 | ✅ 阈值 | 每方案 | 0 | 低于阈值升级 | ✅ 声明式 | +| **SWE-agent** | 多次尝试取最优 | ✅ 代码层 | 每任务 | max_attempts | reviewer 选最优 | ✅ YAML 配置 | + +--- + +### v1.0 三层体系评估 + +#### 三层体系分析 + +| 层级 | 机制 | 优点 | 缺点 | +|------|------|------|------| +| **第 1 层：PAV** | Agent 自律 Plan→Act→Verify | 轻量、无额外成本 | 依赖模型自觉，skill 是"菜单"不是"触发器"，实践中经常被忽略 | +| **第 2 层：节点 review** | 司马懿独立评审 | 独立视角、有结构化 verdict | **每个节点都审过重**（成本高、延迟大），协商轮次固定 3 轮不够灵活 | +| **第 3 层：最终整合审查** | 庞统汇总 + 司马懿终审 | 全局视角、质量兜底 | 和第 2 层重复（司马懿审了两次），庞统的角色定位模糊 | + +#### 三层是否高效？ + +**结论：不够高效，主要体现在**： + +1. **第 1 层形同虚设** — PAV 是 prompt 层面的约束，模型可以忽略。张飞调查报告（Mail #214）已证明 skill 是"菜单"不是"触发器" +2. **第 2 层过重** — 每个节点产出都过司马懿，对于简单任务（如格式化输出、数据搬运）是过度审查 +3. **第 2 层和第 3 层重复** — 司马懿既审每个节点又审最终整合，角色重叠 +4. **没有任务类型适配** — 编码任务、调研任务、数据任务用同一个审查标准，不灵活 + +#### 三层是否足够？ + +**结论：在特定场景下不够**： + +1. **缺少方案阶段审查** — 只审产出，不审方案。编码前的方案设计没有独立审查 +2. **缺少量化评估** — 只有 pass/fail/revise，没有打分机制，难以对比多方案 +3. **缺少安全红线** — 没有 tripwire 机制，危险操作没有代码级拦截 +4. **缺少并行审查** — 只有一个审查者（司马懿），没有多视角对抗 + +#### 三层是否过重？ + +**结论：在简单任务上过重，在复杂任务上不够** — 需要分级。 + +--- + +### 推荐方案（课题3） + +基于以上调研，为 moziplus v2.6 推荐以下挑战/评审体系： + +#### 设计原则 + +1. **声明式 + 代码执行分离** — 审查规则声明在 YAML/JSON 中，执行由框架保证 +2. **分级审查** — 按任务类型和风险级别选择审查深度 +3. **方案先审，产出后审** — 关键节点先审方案，再审产出 +4. **多视角可选** — 支持单审、对抗、共识三种模式 +5. **有限协商 + 自动升级** — 超过轮次自动升级 + +#### 分级审查矩阵 + +| 任务类型 | 方案审查 | 产出审查 | 审查模式 | 最大轮次 | +|---------|---------|---------|---------|---------| +| **高风险**（生产部署/资金操作） | ✅ 必须独立审查 | ✅ 独立审查 + 安全 Guardrail | 对抗（多空辩论） | 5 轮 | +| **标准**（编码/设计/架构） | ✅ 方案过挑战 | ✅ 产出过挑战 | 单审（指定挑战者） | 3 轮 | +| **低风险**（文档/格式化/数据搬运） | ❌ 跳过 | ⚡ 轻量 Guardrail（格式检查） | 自动检查 | 0 轮 | +| **调研/分析** | ❌ 跳过 | ✅ 结论过挑战 | 单审 | 2 轮 | + +#### 三阶段审查流程（关键节点） + +参考 superpowers 的串行双审和 TradingAgents 的对抗辩论，对高风险和标准任务采用： + +``` +阶段 1：方案审查（Plan Review） + ├── 执行者提交方案到黑板 + ├── 挑战者审查方案（可行性/风险/遗漏） + ├── 高风险：多视角对抗辩论 + └── 通过 → 进入执行 + └── 未通过 → 协商修改（最多 max_rounds 轮） + └── 超轮次 → 升级用户 + +阶段 2：执行 + Output Guardrail + ├── 执行者按方案执行 + ├── 系统自动运行 Output Guardrail（声明式规则检查） + │ ├── 文件存在性检查 + │ ├── JSON schema 校验 + │ ├── 代码编译/运行测试 + │ └── 安全红线检查 + └── Guardrail 通过 → 进入产出审查 + └── Guardrail 不通过 → 自动打回（tripwire） + +阶段 3：产出审查（Output Review） + ├── 执行者提交产出到黑板 + ├── 挑战者审查产出（质量/完整性/与方案一致性） + ├── 审查结果结构化记录 + └── 通过 → 流转下一节点 + └── 未通过 → 协商修改 +``` + +#### 声明式 Guardrail 规则示例 + +```yaml +# guardrails.yaml — 声明式质量门控规则 +task_types: + coding: + plan_review: + required: true + reviewer: challenger # 挑战者池分配 + max_rounds: 3 + output_guardrails: + - name: file_exists + check: "output.files | length > 0" + severity: blocking + - name: tests_pass + check: "output.test_result == 'passed'" + severity: blocking + - name: code_quality + check: "output.lint_score >= 8" + severity: warning # 不阻塞，但记录 + output_review: + required: true + reviewer: challenger + max_rounds: 3 + + deploy: + plan_review: + required: true + reviewer: challenger + mode: debate # 对抗辩论模式 + max_rounds: 5 + output_guardrails: + - name: no_direct_production + check: "output.target_env != 'production'" + severity: tripwire # 立即中断 + - name: rollback_plan_exists + check: "output.rollback_plan != null" + severity: blocking + output_review: + required: true + reviewer: challenger + max_rounds: 5 + escalate_to: user # 超轮次升级用户 + + data: + plan_review: + required: false + output_guardrails: + - name: format_check + check: "output.format in ['csv', 'parquet', 'json']" + severity: blocking + output_review: + required: false # 低风险，Guardrail 自动检查即可 +``` + +#### 对 v1.0 三层体系的改进 + +| 改进点 | v1.0 | v2.6 推荐 | +|--------|------|----------| +| **第 1 层 PAV** | 依赖模型自律 | 替换为**声明式 Output Guardrail** — 系统自动执行，不依赖模型 | +| **第 2 层节点 review** | 每个节点都审 | **分级审查** — 按任务类型和风险级别选择审查深度 | +| **第 3 层最终整合** | 司马懿再审一次 | **保留但简化** — 只在高风险任务终审，标准任务由最后节点的审查覆盖 | +| **方案审查** | ❌ 无 | ✅ 新增**方案先审** — 关键节点先审方案再执行 | +| **量化评估** | ❌ 无 | ✅ 可选 — 支持打分机制（参考 wanman），信心度 < 0.7 升级 | +| **对抗辩论** | ❌ 无 | ✅ 高风险任务启用多视角对抗（参考 TradingAgents） | + +--- + +## 课题 5：质量门控结构化 + +### 业界优秀实践对比表（课题5） + +#### 1. Control Center 的 Task Store（artifacts + rollback + review 结构） + +**项目**: [keshrath/agent-tasks](https://github.com/keshrath/agent-tasks)（参考 Control Center 模式） + +**核心结构**： + +``` +Task +├── definitionOfDone（完成标准） +├── artifacts[]（产出物列表，按 stage 组织） +│ ├── id, stage, type, path, metadata +│ └── version（版本化） +├── comments[]（评论，结构化） +├── dependencies[]（依赖关系） +└── pipeline（流水线配置） + └── stages[]（阶段定义 + 审查规则） +``` + +**API 设计**： +- `GET /api/tasks/:id/artifacts` — 按 stage 过滤产出物 +- `PUT /api/tasks/:id/stage` — 推进/回退阶段（支持 regress） +- `POST /api/tasks/:id/comments` — 添加评论 + +**关键洞察**: +- **Artifacts 按 stage 组织** — 每个阶段有独立的产出物列表 +- **支持阶段回退（regress）** — 不只是前进，可以打回 +- **definitionOfDone 是结构化的** — 不是自然语言描述，是可验证的条件列表 + +#### 2. SWE-agent 的 Trajectory 审计 + +**项目**: [SWE-agent/SWE-agent](https://github.com/SWE-agent/SWE-agent) + +**核心机制**: + +SWE-agent 的每次尝试产生一个 **Trajectory**（轨迹），是完全线性的事件序列： + +``` +Trajectory = [ + { step: 1, action: "open_file", args: {...}, observation: "..." }, + { step: 2, action: "search", args: {...}, observation: "..." }, + { step: 3, action: "edit", args: {...}, observation: "..." }, + ... + { step: N, action: "submit", args: {...}, observation: "patch applied" } +] +``` + +- **线性追加** — 每个步骤只是追加到 messages，不修改历史 +- **轨迹 = 消息** — trajectory 和传给 LLM 的 messages 是同一个东西 +- **可回溯** — 完整保留每次尝试的所有步骤 +- **Trajectory Inspector** — 命令行工具，可以滚动查看数百条轨迹 + +**在 RetryLoop 模式下**： +- 多次尝试产生多条 Trajectory +- Reviewer LLM 对比多条 Trajectory，选择最优 patch +- 所有 Trajectory 都保存，可用于后续分析 + +**关键洞察**: +- **审计粒度是每步操作** — 不是每任务，是每个 action +- **不可变追加** — 不修改历史记录，只追加新记录 +- **多次尝试可对比** — 重试机制下保留所有尝试的轨迹 + +#### 3. Hermes 的 Comment 线程 + 结构化状态 + +**项目**: [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) — Kanban Multi-Agent Board + +**核心结构**： + +Hermes 的 Kanban 系统中，**Comment 是持久化标注通道**： + +```sql +kanban_comment: + - id, task_id, author, body, metadata JSON, created_at +``` + +**关键设计**: + +| 机制 | 描述 | +|------|------| +| **Comment 即审计** | 所有审计相关字段（changed_files, tests_run, diff_path, PR url, decisions）都放在 comment 的 metadata 中 | +| **Block with reason** | `kanban_block` 带理由，reason 前缀 `review-required:` 表示等待审查 | +| **Bulk-close guard** | 不允许批量 close 多个 task 用同一个 summary — 因为每个 task 的元数据是不同的 | +| **Worker lanes** | 每次执行产生独立的 worker lane，reviewer 看到完整的 comment thread | +| **Structured metadata** | 接受标准（acceptance criteria）写在 spec metadata 中，engineer 的 worker 自动看到 | + +**审查流程**： +``` +Engineer 完成工作 + → 写 structured metadata 到 kanban_comment + (changed_files, tests_run, diff_path, decisions) + → kanban_block "review-required: 等待审查" + → Reviewer 看到 comment thread + metadata + → Reviewer 批准: kanban_unblock + → Reviewer 要求修改: 再写 comment，下次 worker 运行时看到 +``` + +**关键洞察**: +- **Comment 是主要通信和审计通道** — 不只是讨论，是结构化数据的载体 +- **metadata JSON 承载结构化数据** — body 是人类可读的，metadata 是机器可读的 +- **Block reason 前缀约定** — 用前缀区分 block 类型（review-required / blocked-by / waiting-on） +- **每次执行独立的 worker lane** — 不同次执行的结果不会混淆 + +#### 4. 其他优秀实践 + +##### 4.1 PRD 中定义的 review_result JSON + +moziplus PRD v1.0 已定义了结构化评审结果： + +```json +{ + "review_id": "uuid", + "task_id": "uuid", + "stage_id": "coding", + "reviewer": "simayi", + "verdict": "approved|rejected|needs_revision", + "issues": [ + { + "severity": "critical|major|minor", + "location": "文件:行号 或 方案:章节", + "description": "问题描述", + "suggestion": "修改建议" + } + ], + "round": 1, + "max_rounds": 3, + "consensus_reached": true +} +``` + +**优点**：结构清晰，verdict 明确，issues 可追溯 +**不足**：没有信心度/评分，没有关联到产出物，没有历史版本 + +##### 4.2 GitHub PR Review 的结构化模式 + +GitHub PR Review API 提供了业界最成熟的结构化审查模式： + +``` +Pull Request Review: +├── event: APPROVE | REQUEST_CHANGES | COMMENT +├── body: "总结性评论" +└── comments[]: + ├── path: "src/file.py" + ├── position: 42 + ├── body: "这行有问题" + ├── in_reply_to_id: (支持嵌套回复) + └── side: LEFT | RIGHT +``` + +**关键特性**： +- **三种 verdict**：APPROVE / REQUEST_CHANGES / COMMENT — 明确表达意图 +- **行级定位**：comment 精确到文件+行号 +- **嵌套回复**：支持 comment 线程中的子讨论 +- **review 和 comment 分离**：review 是整体评审，comment 是行级细节 +- **多 reviewer 支持**：多个 reviewer 可以各自提交独立的 review + +##### 4.3 代码审查工具的结构化输出模式 + +业界代码审查工具（SonarQube / CodeClimate / reviewdog）的共同模式： + +``` +Review Output: +├── summary: { verdict, score, total_issues } +├── issues[]: +│ ├── severity: critical | major | minor | info +│ ├── rule_id: "S1234" (规则 ID，可查文档) +│ ├── location: { file, line, column } +│ ├── message: "问题描述" +│ └── suggestion: "修改建议" +└── metadata: + ├── tool_version + ├── analyzed_files + └── duration_ms +``` + +**共同特点**： +- severity 有标准分级（critical/major/minor/info） +- location 精确到文件+行+列 +- rule_id 关联到可查的规则文档 +- summary 包含总体评分和统计 + +#### 综合对比表（课题5） + +| 项目 | 评审存储位置 | 结构化程度 | 可追溯性 | 多轮支持 | 关联产出 | +|------|-----------|-----------|---------|---------|---------| +| **Control Center** | Task Store（内置） | ✅ artifacts + stage | ✅ 版本化 | ⚠️ 阶段回退 | ✅ artifact 关联 | +| **SWE-agent** | Trajectory 文件 | ✅ 每步结构化 | ✅ 线性追加 | ✅ 多次尝试 | ✅ patch 关联 | +| **Hermes** | Comment metadata JSON | ✅ 结构化 metadata | ✅ 追加写入 | ✅ worker lanes | ✅ 手动关联 | +| **moziplus PRD** | comments 表 | ⚠️ 自然语言为主 | ❌ 无版本 | ❌ 无 | ❌ 无 | +| **GitHub PR Review** | Review API | ✅ 行级定位 | ✅ 嵌套回复 | ✅ 多 reviewer | ✅ diff 关联 | +| **代码审查工具** | 独立输出 | ✅ rule_id + severity | ✅ 标准化 | ❌ 单次 | ⚠️ 工具特定 | + +--- + +### 推荐方案：评审结果存储与结构 + +#### 设计原则 + +1. **黑板索引 + 文件详情** — 黑板存储结构化摘要（索引），文件系统存储完整评审记录（详情） +2. **追加写入，不修改历史** — 每轮评审是新的记录，不覆盖旧记录 +3. **结构化 verdict** — 评审结论必须是枚举值，不是自然语言 +4. **关联产出物** — 评审记录通过 output_id 关联到具体产出 +5. **人类可读 + 机器可读** — body 给人看，metadata 给程序用 + +#### 推荐的评审结果结构 + +```sql +-- ===== 评审结果表 ===== +-- 评审是追加写入的，每轮评审一条新记录 +CREATE TABLE IF NOT EXISTS reviews ( + id TEXT PRIMARY KEY, -- rev-001 + task_id TEXT NOT NULL, + output_id TEXT, -- 关联的产出物（outputs 表） + reviewer TEXT NOT NULL, -- 审查者 agent id + review_type TEXT NOT NULL, -- plan_review | output_review | guardrail + CHECK (review_type IN ('plan_review', 'output_review', 'guardrail', 'final_review')), + + -- 评审结论（必须是枚举，不是自然语言） + verdict TEXT NOT NULL, + CHECK (verdict IN ('approved', 'rejected', 'needs_revision', 'approved_with_reservations')), + + -- 评分（可选，用于量化评估场景） + confidence REAL, -- 0.0-1.0 信心度 + scores TEXT, -- JSON: {"feasibility": 0.9, "risk": 0.7, "impact": 0.8, "quality": 0.85} + + -- 协商轮次 + round INTEGER NOT NULL DEFAULT 1, + max_rounds INTEGER NOT NULL DEFAULT 3, + consensus_reached BOOLEAN DEFAULT FALSE, + + -- 摘要（黑板索引） + summary TEXT NOT NULL, -- 一句话评审结论（人可读） + + -- 详情路径（文件详情） + detail_path TEXT, -- 指向完整评审报告文件 + + -- 时间 + created_at TEXT NOT NULL DEFAULT (datetime('now')), + + FOREIGN KEY (task_id) REFERENCES tasks(id), + FOREIGN KEY (output_id) REFERENCES outputs(id) +); + +CREATE INDEX IF NOT EXISTS idx_reviews_task ON reviews(task_id); +CREATE INDEX IF NOT EXISTS idx_reviews_output ON reviews(output_id); +CREATE INDEX IF NOT EXISTS idx_reviews_reviewer ON reviews(reviewer); +``` + +#### 评审详情文件结构 + +``` +tasks/{task_id}/ +├── output.md # 任务产出 +├── output.json # 产出元数据 +└── reviews/ + ├── rev-001-round1.json # 第 1 轮评审 + ├── rev-001-round2.json # 第 2 轮评审（协商后修改） + └── rev-001-round3.json # 第 3 轮评审（最终通过） +``` + +**评审详情 JSON**： + +```json +{ + "review_id": "rev-001", + "task_id": "task-001", + "output_id": "out-001", + "reviewer": "simayi-challenger", + "review_type": "output_review", + "verdict": "needs_revision", + "confidence": 0.65, + "round": 1, + "max_rounds": 3, + "summary": "代码逻辑正确但缺少错误处理和单元测试", + "issues": [ + { + "id": "iss-001", + "severity": "critical", + "category": "correctness", + "location": "src/trading.py:42", + "description": "未处理网络超时异常", + "suggestion": "添加 try-except 包装，设置 30s 超时", + "rule_id": "ERR-001" + }, + { + "id": "iss-002", + "severity": "major", + "category": "testing", + "location": "tests/", + "description": "缺少单元测试", + "suggestion": "至少覆盖正常路径和异常路径", + "rule_id": "TEST-001" + } + ], + "positives": [ + "代码结构清晰，职责分离做得好", + "命名规范，可读性强" + ], + "metadata": { + "model": "zhipu/glm-5.1", + "duration_ms": 12500, + "files_reviewed": ["src/trading.py", "src/utils.py"], + "total_lines_reviewed": 150 + }, + "created_at": "2026-05-15T10:30:00Z" +} +``` + +#### Guardrail 自动检查结果 + +Guardrail 检查结果也存入 reviews 表（`review_type = 'guardrail'`），但来源是系统自动执行： + +```json +{ + "review_id": "rev-auto-001", + "reviewer": "system", + "review_type": "guardrail", + "verdict": "rejected", + "issues": [ + { + "severity": "blocking", + "rule_id": "GUARD-FILE-EXISTS", + "description": "产出文件不存在: output.md", + "location": null + } + ], + "metadata": { + "guardrail_config": "guardrails.yaml#coding.output_guardrails", + "checks_run": 3, + "checks_passed": 2, + "checks_failed": 1 + } +} +``` + +#### 评审产出物与任务产出物的关系 + +``` +Task (task-001) +├── Output 1 (out-001) → 编码产出 +│ ├── Review 1 (rev-001, plan_review, round 1) → 方案评审 +│ ├── Review 2 (rev-002, guardrail, round 1) → 自动 Guardrail +│ └── Review 3 (rev-003, output_review, round 1) → 产出评审 +│ └── Review 4 (rev-004, output_review, round 2) → 协商后再审 +└── Output 2 (out-002) → 测试报告 + └── Review 5 (rev-005, output_review, round 1) → 测试产出评审 +``` + +**关系规则**： +- **一个 output 可以有多个 review**（多轮协商） +- **一个 review 关联一个 output**（不跨产出） +- **review 按时间追加**，不修改历史（round 递增） +- **黑板只存摘要**（verdict + summary + round），完整详情在文件 + +#### 多轮协商的追溯 + +```sql +-- 查看某个任务的所有评审历史 +SELECT r.id, r.round, r.verdict, r.summary, r.created_at +FROM reviews r +WHERE r.task_id = 'task-001' +ORDER BY r.created_at ASC; + +-- 查看某个产出的最新评审 +SELECT * FROM reviews +WHERE output_id = 'out-001' + AND review_type = 'output_review' +ORDER BY round DESC +LIMIT 1; +``` + +#### 对比现有 comments 表的改进 + +| 维度 | 现有 comments 表 | 推荐 reviews 表 | +|------|----------------|----------------| +| **数据类型** | 自然语言 | 结构化 JSON | +| **结论** | 无（靠读 body 推断） | ✅ verdict 枚举 | +| **关联产出** | ❌ 只关联 task | ✅ 关联 output | +| **评分** | ❌ 无 | ✅ confidence + scores | +| **轮次追踪** | ❌ 无 | ✅ round + max_rounds | +| **评审类型** | ❌ 无 | ✅ plan_review / output_review / guardrail / final_review | +| **详情** | ❌ body 只有自然语言 | ✅ body + detail_path 文件 | + +**comments 表保留用途**：日常讨论、@ mention、非结构化沟通。reviews 表专注评审。 + +--- + +## 附录：关键参考源码 + +### A. Superpowers 串行双审 +``` +skills/subagent-driven-development/SKILL.md +skills/requesting-code-review/code-reviewer.md +skills/subagent-driven-development/code-quality-reviewer-prompt.md +``` + +### B. TradingAgents 辩论条件边 +```python +# tradingagents/graph/trading_graph.py +workflow.add_conditional_edges( + "Bull Researcher", + should_continue_debate, + {"Bear Researcher": ..., "Research Manager": ...} +) +``` + +### C. oh-my-claudecode Critic 工具限制 +```yaml +# agents/critic.md +disallowedTools: Write, Edit +``` + +### D. OpenAI Agents SDK Tripwire +```python +# agents/guardrails.py +@output_guardrail +async def guardrail_fn(ctx, agent, output): + return GuardrailFunctionOutput( + tripwire_triggered=output.is_invalid + ) +``` + +### E. SWE-agent RetryLoop +```yaml +# config.yaml +agent: + type: retry + retry_loop: + cost_limit: 6.00 + max_attempts: 3 +``` + +### F. Hermes Kanban Comment +```sql +-- kanban_comment with structured metadata +INSERT INTO kanban_comment (task_id, author, body, metadata) +VALUES (?, ?, ?, json(?)) +-- metadata: {"changed_files": [...], "tests_run": 5, "tests_passed": 5, "diff_path": "..."} +``` diff --git a/docs/research/v2.6-research-04-decomposition-skills.md b/docs/research/v2.6-research-04-decomposition-skills.md new file mode 100644 index 0000000..d6846d1 --- /dev/null +++ b/docs/research/v2.6-research-04-decomposition-skills.md @@ -0,0 +1,1141 @@ +# 调研报告：智能拆解机制 + Skill 体系 + +**日期**: 2026-05-15 +**作者**: 庞统士元 (pangtong-fujunshi) +**版本**: v2.6-research-04 +**用途**: moziplus v2.6 AI Native DevOps 平台设计参考 + +--- + +## 目录 + +- [课题 4：智能拆解机制](#课题-4智能拆解机制) + - [已有经验（知识库/wiki）](#已有经验知识库wiki) + - [业界优秀实践对比表](#业界优秀实践对比表课题4) + - [约束 vs 灵活性分析](#约束-vs-灵活性分析) + - [推荐方案（结合 AI Native 目标）](#推荐方案结合-ai-native-目标课题4) +- [课题 8：Skill 体系工程落地](#课题-8skill-体系工程落地) + - [已有经验（知识库/wiki + OpenClaw 现有 Skill）](#已有经验知识库wiki--openclaw-现有-skill) + - [业界优秀实践对比表](#业界优秀实践对比表课题8) + - [Skill 三层约束工程化方案](#skill-三层约束工程化方案) + - [推荐方案（结合 AI Native 目标）](#推荐方案结合-ai-native-目标课题8) + +--- + +# 课题 4：智能拆解机制 + +## 已有经验（知识库/wiki） + +### moziplus v1.0 现有拆解机制 + +moziplus v1.0 采用 **"模板 + 自然语言描述"** 的混合拆解方式： + +1. **CLI create 接口**：接收 `--description "需求描述"` + `--template 模板名` +2. **模板库**：5 个预定义模板（`full_role_development`, `circular_review_test`, `multi_stage_review`, `data_acquisition`, `multi_edge_discussion`） +3. **自动匹配**：不传 template 时，按关键词优先级匹配模板（循环+测试 → 多阶段 → 讨论 → 数据 → 兜底 full_role） +4. **每个模板定义了固定的 DAG 图**：节点、边、角色分配、output_schema + +**局限性**： +- 模板是固定的 DAG 结构，无法根据需求动态调整节点和边 +- 关键词匹配太粗糙，复杂需求容易匹配到错误模板 +- 庞统拆解时完全靠 LLM 理解，没有结构化引导 +- 无法动态增减步骤（如"这次不需要数据获取"） + +### 知识库中已积累的相关实践 + +从知识库中获取的 6 个相关项目（get-shit-done、wanman、nuwa-skill、oh-my-claudecode、open-multi-agent、TradingAgents），为本次调研提供了丰富的参考素材。 + +--- + +## 业界优秀实践对比表（课题4） + +### 1. MetaGPT：SOP 自动链 + _watch 声明式订阅 + +**核心理念**：将人类软件公司的 SOP（标准操作流程）编码为 prompt 序列，Agent 之间通过发布-订阅自动链接。 + +**拆解机制**： +- **SOP 流水线**：ProductManager → Architect → ProjectManager → Engineer，每步自动触发 +- **_watch 声明式订阅**：每个 Role 通过 `self._watch({UpstreamAction})` 订阅上游产出，上游完成后自动触发下游 +- **Action 基类**：每个 Action 接收 `with_messages`（上游消息），返回 `Message`（结构化产出） +- **Environment 对象**：所有 Agent 放入同一个 Environment，自动调度订阅关系 + +```python +class Architect(Role): + def __init__(self, **kwargs): + super().__init__(**kwargs) + self.set_actions([WriteDesign]) + self._watch({WritePRD}) # 订阅 PRD 产出，自动触发设计 + +class Engineer(Role): + def __init__(self, **kwargs): + super().__init__(**kwargs) + self.set_actions([WriteCode]) + self._watch({WriteDesign}) # 订阅设计产出，自动触发编码 +``` + +**优点**： +- SOP 流水线保证步骤不遗漏 +- _watch 机制实现松耦合的自动链 +- 每步产出结构化文档（PRD→设计→任务→代码），便于下游消费 + +**缺点**： +- SOP 是固定的，灵活性有限 +- 不适合非软件开发场景 +- 粒度在 Role 级别，不能在同一 Role 内动态调整 + +### 2. get-shit-done：discuss→plan→execute→verify→ship 流程 + +**核心理念**：Spec-driven development，通过上下文工程解决 context rot（上下文窗口填满后质量退化）。 + +**拆解机制**： +- **5 阶段流水线**：new-project → discuss-phase → plan-phase → execute-phase → verify +- **Fresh Context Per Agent**：每个子任务 spawn 新 agent（独立上下文窗口），避免 context rot +- **File-Based State**：所有状态存储在 `.planning/` 目录（PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md） +- **Thin Orchestrator**：Workflow 文件不做重活，只加载上下文、spawn agent、收集结果 +- **Progressive Disclosure**：workflow 按需加载子模块（modes/、templates/），避免一次性注入过多内容 +- **Agent Size-Budget**：XL(1700行)、Large(1500行)、Default(1000行)，防止 prompt 过长 + +``` +用户 → /gsd-new-project → 初始化 + → /gsd-discuss → 需求讨论（questioning → dream extraction） + → /gsd-plan → 规划（analyst → architect → critic → plan checker） + → /gsd-execute → 执行（按 phase 分任务，独立 agent 执行） + → /gsd-verify → 验证（多维度自动化验证） +``` + +**优点**： +- 分阶段拆解，每阶段有明确产出 +- 需求讨论阶段（discuss）会做 dream extraction，挖掘隐含需求 +- Plan checker agent 专门验证计划的完整性 +- Scope reduction detection 防止规划时静默丢弃需求 + +**缺点**： +- 仍然是预定义的 5 阶段流程 +- 不适合非软件项目 +- Token 成本高（每任务独立上下文窗口） + +### 3. wanman：Explore→Evaluate→Execute 三阶段 + Token 预算 + +**核心理念**：Agent Matrix 框架，通过 JSON-RPC Supervisor 协调多个 Claude Code/Codex 子进程。 + +**拆解机制**： +- **Agent 配置**：JSON 文件定义 agents（name, lifecycle, model tier, systemPrompt） +- **三种生命周期**：`24/7`（持续运行）、`on-demand`（按需触发）、`idle_cached`（空闲但保持上下文） +- **Task Pool**：支持 `--after` 依赖的任务池，自然形成 DAG +- **Initiative**：长期目标管理，将目标分解为任务 +- **Capsule**：变更胶囊，追踪每个 agent 的产出变更 +- **Per-agent 隔离**：每个 agent 独立 worktree + 独立 $HOME，互不干扰 + +**关键设计**： +- **CEO Agent** 负责全局协调和最终决策 +- **Steer/Follow-up 优先级**：消息分为中断性指令和跟进性消息 +- **共享 Skill 发现**：agents 自动发现 `~/.claude/skills/` 下的共享 skill +- **Skill Snapshot**：运行时将 skill 文件 materialize 为快照 + +**优点**： +- CEO 模式适合需要集中决策的场景 +- Task Pool + `--after` 依赖天然支持 DAG 调度 +- Agent 隔离保证稳定性 + +**缺点**： +- 拆解依赖 CEO agent 的 LLM 能力 +- 没有结构化的拆解模板 +- Token 预算管理需要手动配置 + +### 4. ChatDev：角色流水线 + 环检测 + +**核心理念**：通过 Chat Chain 组织多角色对话，每个 phase 由两个角色（如 CTO + PM）的对话完成。 + +**拆解机制**： +- **Chat Chain**：将软件开发分解为有序的 phases（Demand Analysis → Language Model → Coding → Code Complete → Code Review → Testing → Environment Configuration） +- **角色配对**：每个 phase 由两个角色对话完成（CTO↔PM, CTO↔Programmer, CTO↔Art Designer, etc.） +- **Communicative Dehallucination**：通过角色间的质疑和验证减少幻觉 +- **环检测**：当角色陷入死循环（反复说"我同意"）时自动打破 +- **ChatChain Visualizer**：可视化查看每个 phase 的对话和产出 + +``` +用户需求 → [Demand Analysis: CEO↔CTO] + → [Language Design: CTO↔CPO] + → [Coding: CTO↔Programmer] + → [Code Complete: Programmer↔CTO] + → [Code Review: Programmer↔Reviewer] + → [Testing: CTO↔Tester] + → [Environment Config: CTO↔CTO] +``` + +**优点**： +- 角色配对确保每步都有质疑和验证（类似我们的"做+挑战"） +- Chat Chain 是半结构化的：phase 顺序固定，但对话内容自由 +- 环检测是实用的工程优化 + +**缺点**： +- Phase 顺序完全固定 +- 角色配对固定，不能动态调整 +- 只适用于软件开发 + +### 5. TradingAgents：动态图构建 + +**核心理念**：模拟真实交易公司的协作结构，通过 `selected_analysts` 参数动态决定图的节点和边。 + +**拆解机制**： +- **动态图构建**：`selected_analysts` 参数决定激活哪些分析师（Fundamental, Sentiment, Technical, News） +- **结构化输出**：Research Manager 汇总分析师报告，Trader 做决策，Portfolio Manager 管理仓位 +- **LangGraph checkpoint**：支持断点续跑 +- **Decision Log**：持久化决策记录 + +``` +selected_analysts = ["fundamental", "sentiment", "technical"] + ↓ 自动构建图: + Fundamental Analyst → Research Manager + Sentiment Analyst → Research Manager + Technical Analyst → Research Manager + Research Manager → Trader → Portfolio Manager +``` + +**优点**： +- **真正的动态图**：参数决定节点和边，不是固定模板 +- 适合不同复杂度的任务（简单任务少选 analyst，复杂任务全选） +- 结构清晰：分析 → 汇总 → 交易 → 仓位管理 + +**缺点**： +- 动态范围有限（只能选/不选预定义的 analyst 类型） +- 不能动态创建新的 agent 类型 +- 没有拆解验证机制 + +### 6. open-multi-agent：Goal → DAG 自动分解 + +**核心理念**：Goal-first，用户描述目标，Coordinator 自动分解为 Task DAG。 + +**拆解机制**： +- **`runTeam(team, goal)`**：一个调用，Coordinator 自动分解目标为任务 DAG +- **自动并行化**：无依赖的任务自动并行执行 +- **混合 Provider**：10+ LLM 适配器，不同 agent 可用不同模型 +- **Observability**：`onProgress` 事件流 + `onTrace` span + HTML dashboard +- **Loop Detection**：内置循环检测 +- **Token Budget**：支持 token 预算管理 +- **Context Compaction**：上下文压缩 + +``` +goal: "Build a REST API" + ↓ Coordinator 自动分解: + task: design-api (no deps) + task: implement-handlers (after design-api) + task: scaffold-tests (after design-api, parallel with implement) + task: review-code (after implement + tests) +``` + +**优点**： +- **最接近"AI Native 拆解"的理想**：目标→DAG 全自动 +- 不需要预定义模板 +- 依赖关系自动解析 + 并行化 + +**缺点**： +- 拆解质量完全依赖 Coordinator LLM 能力 +- 没有拆解结果的验证/挑战机制 +- 对于复杂领域任务，可能遗漏关键步骤 + +### 7. guidance-aws / Databricks：Supervisor 模式 + +**核心理念**：Supervisor Agent 负责意图分析 + Agent 选择，单次 LLM 调用同时完成两个决策。 + +**拆解机制**： +- **Supervisor Agent**：接收用户输入，一次性完成意图识别 + Agent 选择 + 参数提取 +- **Hybrid Routing**：确定性快速路径 + LLM fallback（生产系统推荐混合路由） +- **Message Queue**：Agent 间通过消息队列通信 +- **Human-in-the-loop**：支持无缝衔接人工介入 + +``` +用户输入 → Supervisor (单次 LLM) + → 意图分析: "这是一个编码任务" + → Agent 选择: "分配给 Developer Agent" + → 参数提取: {language: "Python", framework: "FastAPI"} + → 路由到 Developer Agent +``` + +**优点**： +- 单次 LLM 调用效率高 +- Hybrid Routing 平衡速度和灵活性 +- 生产级设计 + +**缺点**： +- Supervisor 是单点，能力决定上限 +- 没有拆解结果的验证 + +### 8. Claude Code 的 Task Decomposition + +**核心理念**：隐式分解，通过 Headless Mode + Subagent 自动完成。 + +**拆解机制**： +- **Headless Mode**：`claude -p "task"` 非交互模式，自动处理 +- **Task Tool**：Agent 可 spawn 子 agent 处理子任务 +- **TodoRead/TodoWrite**：内置 todo 管理，Agent 自己创建和追踪子任务 +- **Skills**：通过 SKILL.md 注入领域知识，引导 Agent 的分解策略 +- **Progressive Context Loading**：只加载 frontmatter（~100 token），匹配后才加载全文 + +**优点**： +- 拆解完全由 Agent 自主完成，不需要显式定义 +- Todo 系统让 Agent 自己追踪分解结果 +- Skill 注入可以引导分解方向 + +**缺点**： +- 没有结构化约束，质量不稳定 +- 没有"拆解验证"机制 + +--- + +## 约束 vs 灵活性分析 + +### 核心矛盾 + +| 维度 | 固定模板 | 完全自由 | AI Native 理想 | +|------|---------|---------|---------------| +| **步骤完整性** | ✅ 保证不遗漏 | ❌ 可能遗漏 | ✅ AI 确保覆盖 | +| **灵活性** | ❌ 死板 | ✅ 适应任何场景 | ✅ 根据需求动态调整 | +| **可预测性** | ✅ 行为可预期 | ❌ 不确定 | ⚠️ 有约束的灵活 | +| **粒度控制** | ❌ 固定粒度 | ⚠️ 不稳定 | ✅ AI 根据复杂度调整 | +| **调试性** | ✅ 容易定位问题 | ❌ 难复现 | ✅ 有检查点 | + +### 五个关键问题的回答 + +#### Q1: 拆解模板 vs 动态生成的权衡点在哪？ + +**结论：模板作为骨架，AI 负责填充和调整。** + +- **简单/常见任务**：直接用模板（如"开发一个新策略"→ `full_role_development`） +- **复杂/独特任务**：AI 动态生成 DAG，但必须经过验证 +- **混合任务**：选择最接近的模板，AI 增减节点和边 + +**权衡点判断标准**： + +| 需求特征 | 建议策略 | 示例 | +|---------|---------|------| +| 需求清晰 + 场景常见 | 直接模板 | "开发MACD策略" | +| 需求清晰 + 场景不常见 | 模板 + AI 调整 | "对比3个平台的回测结果" | +| 需求模糊 + 场景常见 | AI 分析 + 模板对齐 | "优化我的交易系统" | +| 需求模糊 + 场景不常见 | AI 完全动态生成 + 强验证 | "研究新因子并整合到生产" | + +#### Q2: 是否有"模板 + AI 增强"的混合模式？ + +**是的，这是最佳方案。** 参考： + +| 项目 | 混合模式 | +|------|---------| +| MetaGPT | SOP 骨架（固定角色流水线） + _watch 动态订阅 | +| GSD | 5 阶段骨架（固定流水线） + discuss dream extraction（AI 挖掘隐含需求） | +| TradingAgents | 预定义 analyst 类型（固定节点池） + `selected_analysts` 动态选择 | +| open-multi-agent | Goal → DAG（AI 动态生成） + fixed team definition（固定角色池） | + +**推荐混合模式**： +1. **模板库提供骨架**：5-10 个场景模板，每个定义了典型节点和边 +2. **AI 负责三件事**： + - 选择最合适的模板 + - 增减节点和边（如"这次不需要风控审核"或"加一个数据验证步骤"） + - 调整粒度（简单任务合并节点，复杂任务拆细） +3. **结构约束**：模板定义了"必须有的节点"（如 review 节点不可删除） + +#### Q3: 拆解结果是否需要验证/挑战？ + +**必须！这是所有项目的共识。** 参考： + +| 项目 | 验证机制 | +|------|---------| +| MetaGPT | 每个 Role 验证上游产出 | +| GSD | plan-checker agent + scope reduction detection | +| ChatDev | 角色配对（做+审核）+ 环检测 | +| oh-my-claudecode | Architect → Critic → Planner 三方验证 | + +**推荐方案**： +1. **Plan Checker Agent**：拆解完成后，独立的 Plan Checker 验证： + - 是否覆盖所有需求（与原始需求逐项对照） + - 依赖关系是否合理 + - 粒度是否适当（太粗/太细） + - 是否遗漏关键步骤 +2. **需求回溯**：拆解结果的每个节点都能追溯到原始需求的哪个部分 +3. **完整性检查清单**：按任务类型生成检查清单 + +#### Q4: 如何确保拆解覆盖所有需求（不遗漏）？ + +**多层次保障**： + +1. **需求结构化**（GSD 的 discuss phase 思路）： + - 用户描述 → AI 提取为结构化需求列表 + - 每个需求项有 ID、描述、验收标准 + - 用户确认需求列表后才开始拆解 + +2. **需求-节点映射矩阵**（正向+反向验证）： + - 正向：每个需求至少被一个节点覆盖 + - 反向：每个节点至少对应一个需求 + +3. **Plan Checker 的覆盖检查**： + - 读取需求列表 + - 遍历 DAG 节点 + - 报告未被覆盖的需求 + +4. **Scope Reduction Detection**（GSD 思路）： + - 监控规划者是否静默丢弃了需求 + - 如果发现需求消失，自动标记并询问用户 + +#### Q5: 拆解粒度怎么控制？ + +**自适应粒度策略**： + +| 任务复杂度 | 粒度策略 | 节点数 | +|-----------|---------|--------| +| 简单（<3 个需求） | 粗粒度，合并步骤 | 3-5 | +| 中等（3-8 个需求） | 标准粒度，按功能模块拆分 | 5-10 | +| 复杂（>8 个需求） | 细粒度，每需求可能拆为多个节点 | 10-20 | + +**粒度控制原则**： +1. **每个节点有且只有一个 Agent 负责**（不共享责任） +2. **每个节点有明确的 input/output**（可验证） +3. **节点产出不超过 2000 字**（避免上下文溢出） +4. **合并准则**：如果两个节点总是被同一个 Agent 按顺序执行，考虑合并 + +--- + +## 推荐方案（结合 AI Native 目标，课题4） + +### 方案名称：混合式智能拆解（Hybrid Intelligent Decomposition） + +### 架构设计 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 用户需求输入 │ +│ （自然语言 / 结构化描述） │ +└─────────────────────┬───────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Step 1: 需求结构化（Requirement Extraction） │ +│ │ +│ 庞统分析用户输入，提取为结构化需求列表： │ +│ - 需求项 ID + 描述 + 验收标准 │ +│ - 需求类型标签（数据/编码/分析/部署/审查/讨论） │ +│ - 复杂度评估（简单/中等/复杂） │ +│ - 隐含需求挖掘（discuss phase 的 dream extraction） │ +│ │ +│ 产出：structured_requirements.json │ +│ ✋ 检查点：用户确认需求列表 │ +└─────────────────────┬───────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Step 2: 模板匹配 + AI 增强 │ +│ │ +│ 2a. 模板选择（两层匹配）： │ +│ - 第一层：需求类型标签 → 候选模板集 │ +│ - 第二层：LLM 语义匹配 → 最佳模板 │ +│ │ +│ 2b. AI 增强（动态调整）： │ +│ - 增：遗漏的步骤（如缺少数据验证） │ +│ - 删：不需要的步骤（如纯分析不需要部署） │ +│ - 调：粒度调整（合并/拆分节点） │ +│ - 角色适配：根据节点调整 Agent 分配 │ +│ │ +│ 约束：某些节点不可删除（如 review 节点，铁律 IR-1） │ +│ │ +│ 产出：draft_dag.json（节点 + 边 + Agent 分配） │ +└─────────────────────┬───────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Step 3: Plan Checker 验证 │ +│ │ +│ 独立的 Plan Checker Agent 验证： │ +│ - 覆盖性：每个需求是否被至少一个节点覆盖 │ +│ - 依赖性：节点依赖是否合理（无环、无遗漏前置） │ +│ - 粒度性：节点是否过大/过小 │ +│ - 完整性：是否遗漏常见步骤（对比模板库的经验） │ +│ - 角色匹配：Agent 能力是否匹配节点要求 │ +│ │ +│ 产出：plan_check_result.json + 修改建议 │ +│ 如果不通过 → 回到 Step 2 调整（最多 2 轮） │ +└─────────────────────┬───────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Step 4: 最终 DAG 输出 │ +│ │ +│ 通过验证的 DAG，包含： │ +│ - 节点定义（ID, name, agent, input_schema, output_schema） │ +│ - 边定义（source → target, condition） │ +│ - 需求映射矩阵（requirement_id → node_ids） │ +│ - 检查点定义（哪些节点需要人工确认） │ +│ │ +│ 产出：final_dag.json → 传入 moziplus 引擎执行 │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 关键设计决策 + +| 决策 | 选择 | 理由 | +|------|------|------| +| 拆解由谁做 | 庞统（副军师） | 定位就是"策略研究+任务协调" | +| 模板角色 | 骨架+约束 | 保证基本完整性，AI 负责灵活调整 | +| 验证机制 | 独立 Plan Checker | 不信任 LLM 自律（业界共识） | +| 需求覆盖 | 需求-节点映射矩阵 | 正向+反向双重保证 | +| 粒度控制 | 自适应（复杂度驱动） | 避免"一刀切" | +| 不可删除节点 | review 类节点 | 铁律 IR-1（每任务至少 2 Agent） | + +### 模板库设计 + +不是 5 个固定模板，而是 **模板组件库**： + +```json +{ + "template_components": { + "phases": { + "requirement_clarification": { + "mandatory": false, + "trigger": "需求含糊", + "nodes": ["requirement_analysis", "requirement_review"] + }, + "research": { + "mandatory": false, + "trigger": "需要调研", + "nodes": ["literature_search", "analysis", "research_review"] + }, + "design": { + "mandatory": false, + "trigger": "需要设计", + "nodes": ["architecture_design", "design_review"] + }, + "implementation": { + "mandatory": false, + "trigger": "需要编码", + "nodes": ["coding", "code_review", "testing"] + }, + "data": { + "mandatory": false, + "trigger": "需要数据", + "nodes": ["data_acquisition", "data_validation"] + }, + "deployment": { + "mandatory": false, + "trigger": "需要部署", + "nodes": ["deployment", "deployment_verification"] + }, + "risk_control": { + "mandatory": true, // 如果涉及交易 + "trigger": "涉及实盘/资金", + "nodes": ["risk_check", "position_check"] + }, + "final_review": { + "mandatory": true, // 铁律 + "trigger": "always", + "nodes": ["integration_review", "final_summary"] + } + } + } +} +``` + +庞统的拆解流程变为： +1. 分析需求 → 识别需要哪些 phases +2. 从 phase 组件中选择节点 +3. 排列依赖关系 → 构建 DAG +4. Plan Checker 验证 + +### 与 moziplus v1.0 的对比 + +| 维度 | v1.0 | v2.6（推荐方案） | +|------|------|-----------------| +| 拆解方式 | 关键词 → 固定模板 | 需求分析 → 模板组件组合 → AI 增强 | +| 模板类型 | 5 个完整 DAG | 组件库（~8 个 phase 组件） | +| 灵活性 | ❌ 固定结构 | ✅ 动态增减节点 | +| 需求覆盖 | ❌ 无检查 | ✅ 需求-节点映射矩阵 | +| 验证 | ❌ 无 | ✅ 独立 Plan Checker | +| 粒度 | ❌ 固定 | ✅ 复杂度自适应 | +| 铁律保证 | ❌ 无 | ✅ 不可删除节点 | + +--- + +# 课题 8：Skill 体系工程落地 + +## 已有经验（知识库/wiki + OpenClaw 现有 Skill） + +### OpenClaw 现有 Skill 体系 + +**SKILL.md 规范**： +- 每个 Skill 是一个目录，包含 `SKILL.md` 文件 +- YAML frontmatter：`name`、`description` +- 正文：指令性内容（工作流、最佳实践、指引） +- 注册：放在 `workspace/skills/` 或 `~/.openclaw/skills/` 下，系统自动发现 +- 发现：系统启动时扫描所有 Skill 目录，将 name+description 注入 Agent 上下文 +- 加载：Agent 匹配到相关 Skill 后，用 `read` 工具加载全文 + +**当前 Skill 列表**（42 个，来自 AGENTS.md）： +- 编排类：mozi-task-manager, subagent-delegation, plan-act-verify +- 数据类：data-acquisition, data-verification +- 开发类：coding-implementation, code-review, deployment-infra +- 设计类：design-architecture, requirement-clarification, requirements-analysis +- 分析类：risk-assessment, summary-report, quant-backtest +- Wiki 类：wiki-agent, wiki-capture, wiki-query, wiki-research, wiki-synthesize, wiki-update, wiki-ingest, wiki-export, llm-wiki, data-ingest, ingest-url, cross-linker, graph-colorize, tag-taxonomy, impl-validator, memory-bridge, daily-update +- 通用：skill-creator, summarize, taskflow, taskflow-inbox-triage +- 系统：healthcheck, node-connect, openai-whisper, video-frames, weather, clawhub + +### v3.1 Skill 体系设计（已确认） + +我们已在 `skill-system-v3.1-design.md` 中确认了四部分架构： + +| 部分 | 机制 | Token | +|------|------|-------| +| A. Hook 铁律层 | before_prompt_build Hook | ~500 | +| B. Agent 角色层 | SOUL.md / AGENTS.md | ~2000 | +| C. 通用 Skill 层 | 关键词匹配 + 按需加载 | 列表~1250, 正文按需 | +| D. moziplus 专用层 | 引擎注入 | ~1000 | + +### nuwa-skill 的 5 阶段蒸馏经验 + +nuwa-skill 证明了"蒸馏思维框架"是可行的： +- 5 层提取：表达DNA → 心智模型 → 决策启发式 → 反模式 → 诚实边界 +- 6 Agent 并行采集：著作/对话/表达/他者/决策/时间线 +- 多重检查点：调研 Review → 提炼确认 → 质量验证 → 双 Agent 精炼 + +**对 moziplus Skill 体系的启发**： +1. Skill 可以通过"蒸馏"方式创建，不必手写 +2. 质量验证需要独立 Agent +3. 多检查点保证质量 +4. 诚实边界很重要——Skill 应说明自己做不到什么 + +--- + +## 业界优秀实践对比表（课题8） + +### 1. Claude Code Skills 体系 + +**架构：4 层渐进式上下文加载** + +| 层 | 内容 | 何时加载 | Token 成本 | +|----|------|---------|-----------| +| L1: Discovery | YAML frontmatter（name + description） | 系统启动 | ~100 token/skill | +| L2: Matching | 检查 description 是否匹配当前任务 | 每轮推理 | 0（已有 L1） | +| L3: Full Load | SKILL.md 正文 | 确认匹配后 | 完整内容 | +| L4: Overflow | 低频 Skill description 被截断 | 超预算时 | 降级为更短描述 | + +**关键设计**： +- **skillListingBudgetFraction**：技能列表占上下文的百分比（默认约 2%） +- **Progressive disclosure**：从轻到重，按需加载 +- **Workflow vs Reference**：Skill 正文是"做什么"（workflow），不是"为什么"（narrative） +- **allowed_tools / model / disable_model_invocation**：frontmatter 可选字段 + +**SKILL.md 结构**： +```yaml +--- +name: my-skill +description: "简短描述，决定是否被选中" +allowed_tools: [Read, Write, Bash] +--- +# 具体指令内容（workflow + best practices） +``` + +**优点**： +- Token 效率极高（L1 只需 ~100 token） +- 渐进式加载减少无关上下文 +- 文件系统即注册中心，简单可靠 + +**缺点**： +- Skill 之间没有组合机制 +- 没有 Skill 版本管理 +- 没有 Skill 测试标准 + +### 2. oh-my-claudecode：三层组合 + +**架构：Execution + Enhancement + Guarantee** + +| 层 | 作用 | 代表 Skill | +|----|------|-----------| +| Execution | 执行具体任务 | ralph, ultrawork, autopilot, team | +| Enhancement | 增强执行质量 | deep-interview, plan, verify, ultraqa | +| Guarantee | 保证交付标准 | omc-doctor, trace, hud, cancel | + +**Skill 管理机制**： +- **`/skill list`**：扫描 built-in / user / project 三层 +- **`/skill add`**：交互式创建向导 +- **`/skill search`**：搜索 Skill +- **Built-in**：不可编辑（只读） +- **User**：`~/.claude/skills/omc-learned/` +- **Project**：`.omc/skills/` + +**Skill 等级**： +- Level 1：简单查询/操作 +- Level 2：中等复杂度，需要工具调用 +- Level 3：复杂，可能 spawn 子任务 +- Level 4：全自动（如 autopilot） + +**关键设计**： +- **autopilot 5 阶段**：Expansion → Planning → Execution → QA → Validation +- **ralplan 3 阶段**：Planner → Architect → Critic（3 个独立 LLM 验证） +- **deep-interview**：苏格拉底式提问，先澄清再动手 +- **ralph**：持久化执行循环（state 文件跨 session） + +**优点**： +- 三层分类清晰（做→增强→保证） +- Skill 等级系统控制复杂度 +- 跨 session 持久化（state 文件） + +**缺点**： +- 三层之间没有明确的接口协议 +- 组合依赖 Agent 自行判断 +- 没有标准化的测试框架 + +### 3. nuwa-skill：5 阶段蒸馏 + 检查点 + +**架构：蒸馏式 Skill 创建** + +| 阶段 | 内容 | 产出 | +|------|------|------| +| Phase 0 | 入口分流（直接路径 vs 诊断路径） | Skill 目录 | +| Phase 1 | 6 Agent 并行采集 | 6 份调研文件 | +| Phase 2 | 框架提炼（心智模型+决策启发式+表达DNA） | 提炼结果 | +| Phase 3 | Skill 构建（填充模板） | SKILL.md | +| Phase 4 | 质量验证（已知/边缘/风格 3 项测试） | 验证报告 | +| Phase 5 | 双 Agent 精炼 | 最终 SKILL.md | + +**关键创新**： +- **Agentic Protocol**：Skill 不只是"知道什么"，还定义了"怎么做"（遇到事实问题先搜索再回答） +- **诚实边界**：每个 Skill 必须声明自己做不到什么 +- **质量自检脚本**：`quality_check.py` 自动检查 6 项通过标准 +- **心智模型驱动**：从蒸馏出的心智模型推导回答策略 + +**优点**： +- Skill 可以通过半自动化流程创建 +- 多检查点保证质量 +- 诚实边界增加了可信度 +- 心智模型驱动是创新点 + +**缺点**： +- 创建流程复杂（6 phase） +- 主要针对"人物 Skill"，通用化需要改造 +- 没有 Skill 之间的组合机制 + +### 4. MetaGPT Action 基类 + +**架构：面向对象的 Action 继承** + +```python +class Action: + name: str + context: Context # 共享上下文 + + async def run(self, with_messages: List[Message] = None, **kwargs) -> Message: + """子类实现具体逻辑""" + raise NotImplementedError + +class Role: + actions: List[Action] + _watch: Set[Type[Action]] # 订阅上游 Action + + def set_actions(self, actions: List[Action]): + self.actions = actions + + async def _think(self): + """决定执行哪个 Action""" + + async def _react(self): + """执行 Action 并发布结果""" +``` + +**关键设计**： +- **Action 是最小执行单元**：输入 Message → 输出 Message +- **Role 组合 Action**：一个 Role 可以有多个 Action +- **_watch 声明式订阅**：自动触发链 +- **Context 共享**：所有 Role/Action 共享同一上下文 + +**优点**： +- 面向对象，结构清晰 +- Action 可复用（不同 Role 可共享同一 Action） +- _watch 机制优雅 + +**缺点**： +- 需要写 Python 代码，不是纯 Skill 描述 +- 绑定 Python 生态 +- 对非开发人员门槛高 + +### 5. GSD 的 Skill Discovery Contract + +**架构：文件系统 + 规范化扫描** + +``` +项目根目录： + .claude/skills/ + .agents/skills/ + .cursor/skills/ + .github/skills/ + .codex/skills/ + +全局： + ~/.claude/skills/ + ~/.codex/skills/ +``` + +**规范化规则**： +- 只扫描包含 `SKILL.md` 的子目录 +- 从 YAML frontmatter 读取 name 和 description +- 缺少 name 时用目录名 +- 提取 trigger hints（`TRIGGER when: ...` 行） +- `gsd-*` 目录识别为框架 Skill + +**Skill Manifest**（清单）： +```json +{ + "skills": [...], + "roots": ["扫描了哪些根目录"], + "installation": {"gsd_skills_installed": true, "legacy_claude_commands_installed": false}, + "counts": {"total": 25, "project": 5, "global": 20} +} +``` + +**优点**： +- 规范化程度高 +- 跨运行时兼容（Claude Code / Codex / Gemini CLI） +- 清单系统方便审计 + +**缺点**： +- 只做发现，不做组合和验证 +- 没有版本管理 + +### 6. CrewAI Tool 装饰器 + +**架构：装饰器模式 + Tool 注册** + +```python +@tool("stock_price") +def get_stock_price(symbol: str) -> str: + """获取股票价格""" + return f"Stock price of {symbol} is $100" + +agent = Agent( + role="Analyst", + tools=[get_stock_price] +) +``` + +**优点**： +- 装饰器语法简洁 +- Tool 自动注册 + +**缺点**： +- 是 Tool 而非 Skill（能力扩展 vs 行为指导） +- 绑定 Python + +### 7. LangChain Runnable 接口 + +**架构：函数式组合** + +```python +chain = prompt | model | parser +result = chain.invoke({"input": "..."}) +``` + +**优点**：组合灵活（pipe 操作符） +**缺点**：是代码级组合，不是 Skill 级 + +--- + +## Skill 三层约束工程化方案 + +### 核心概念：三层约束 + +基于 v3.1 设计和我们调研的业界实践，Skill 的三层约束定义为： + +| 层 | 自由度 | 内容 | 类比 | +|----|--------|------|------| +| **铁律层（Iron Rules）** | 低自由 | 强制执行的硬规则 | 法律 | +| **准则层（Guidelines）** | 中自由 | 推荐的最佳实践 | 行业规范 | +| **技能层（Skills）** | 高自由 | 具体的操作方法 | 工具手册 | + +### 工程化方案 + +#### A. 铁律层工程化 + +**机制**：OpenClaw Plugin Hook `before_prompt_build` + +```typescript +// iron-rules hook +api.on("before_prompt_build", async (event, ctx) => { + const agentId = resolveAgentId(ctx); + const rules = loadIronRules(agentId); + return { + prependContext: `\n${rules}\n` + }; +}); +``` + +**特点**： +- 每轮强制注入，不受 compaction 影响 +- 按 Agent 定制（庞统的铁律 ≠ 张飞的铁律） +- 集中管理（一个配置文件，而非分散在各 SOUL.md） + +**铁律内容示例**： +``` +IR-1: 每个任务至少 2 个 Agent（做 + 挑战） +IR-2: Plan → Act → Verify 三步法 +IR-3: 结论必须有证据 +IR-4: 改代码先改文档 +IR-5: 语义含糊先确认 +``` + +#### B. 准则层工程化 + +**机制**：SKILL.md（准则型 Skill） + +与"技能型 Skill"的区别： +- 准则型 Skill：不定义具体步骤，只定义"应该考虑什么"、"边界在哪里" +- 技能型 Skill：定义具体的操作步骤 + +**准则型 Skill 示例**： + +```yaml +--- +name: code-review-guideline +description: "代码审查准则。做审查时参考。" +type: guideline # 区别于 type: procedure +--- +# 代码审查准则 + +## 必须检查 +- [ ] 是否有未处理的异常 +- [ ] 是否有硬编码的密钥/密码 +- [ ] 是否有死循环风险 +- [ ] 是否符合项目命名规范 + +## 禁止 +- 不得批准自己写的代码（IR-1） +- 不得在没有运行测试的情况下批准 + +## 诚实边界 +- 审查者可能遗漏深层逻辑问题 +- 性能问题需要实际测试数据 +``` + +**技能型 Skill 示例**： + +```yaml +--- +name: quant-backtest +description: "量化策略回测执行流程。" +type: procedure +--- +# 量化回测流程 + +## 步骤 +1. 从 NAS 获取数据（路径：/Volumes/stock/...） +2. 编写策略代码（模板：...） +3. 提交回测请求（API：http://192.168.2.154:8088） +4. 等待结果 + 验证 +5. 生成报告 + +## 工具 +- 数据：赵云 data-acquisition skill +- 验证：关羽 risk-assessment skill +``` + +#### C. 技能层工程化 + +**机制**：SKILL.md（过程型 Skill）+ 模板 + 脚本 + +**Skill 目录结构**： +``` +skills/ + quant-backtest/ + SKILL.md # 主文件 + templates/ # 代码模板 + scripts/ # 辅助脚本 + examples/ # 示例 + tests/ # 测试（可选） +``` + +**测试方案**： +- **干跑测试**：给 Skill 一个输入，检查输出是否符合 schema +- **场景测试**：3-5 个典型场景，验证 Skill 覆盖度 +- **回归测试**：修改 Skill 后，确保已有场景不被破坏 + +--- + +## 推荐方案（结合 AI Native 目标，课题8） + +### 方案名称：分层渐进式 Skill 体系（Layered Progressive Skill System） + +### 架构总览 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Layer 0: 铁律（Iron Rules） │ +│ 机制: Hook 注入 | 自由度: 无 | 每轮强制 │ +│ 内容: IR-1~IR-5 │ +│ Token: ~500 │ +├─────────────────────────────────────────────────────────────┤ +│ Layer 1: 角色（Agent Identity） │ +│ 机制: SOUL.md + AGENTS.md | 自由度: 无 | 全量加载 │ +│ 内容: 角色定义 + 行为准则 + Skill 列表 │ +│ Token: ~2000 │ +├─────────────────────────────────────────────────────────────┤ +│ Layer 2: 准则（Guidelines） │ +│ 机制: SKILL.md (type=guideline) | 自由度: 中 | 按需加载 │ +│ 内容: 检查清单 + 边界 + 诚实边界 │ +│ Token: 描述~100, 全文~500 │ +├─────────────────────────────────────────────────────────────┤ +│ Layer 3: 技能（Procedures） │ +│ 机制: SKILL.md (type=procedure) | 自由度: 高 | 按需加载 │ +│ 内容: 具体步骤 + 模板 + 脚本 + 示例 │ +│ Token: 描述~100, 全文~2000 │ +├─────────────────────────────────────────────────────────────┤ +│ Layer 4: 引擎注入（Engine Context） │ +│ 机制: moziplus engine | 自由度: 无 | 每轮强制 │ +│ 内容: output-schema + 任务约束 + 检查点参数 │ +│ Token: ~1000 │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Skill 注册、发现、加载 + +#### 注册 + +```yaml +# SKILL.md frontmatter +--- +name: quant-backtest +description: "量化策略回测执行流程。触发词：回测、backtest、策略测试。" +type: procedure # procedure | guideline +version: "1.0.0" +agents: [zhangfei-dev, jiangwei-infra] # 哪些 Agent 可用 +triggers: [回测, backtest, 策略测试] +--- +``` + +#### 发现 + +```typescript +// 启动时扫描 +const skillRegistry = { + scan() { + // 扫描 workspace/skills/ + ~/.openclaw/skills/ + // 读取 frontmatter + // 构建索引：name → path, triggers → names, agents → skills + }, + + match(context: string, agentId: string): Skill[] { + // 1. 过滤 agentId 可见的 Skill + // 2. 语义匹配 description + // 3. 返回匹配的 Skill 列表（只有 name + description） + } +} +``` + +#### 加载 + +``` +Agent 收到任务 + → 系统注入 L0 铁律 + L1 角色 + L4 引擎上下文 + → 系统注入 L2/L3 Skill 列表（只有 name+description） + → Agent 自主决定需要哪些 Skill + → Agent 用 read 工具加载具体 Skill 全文 + → Agent 执行 +``` + +### Skill 组合和编排 + +**核心原则**：Skill 不直接调用 Skill，而是通过"推荐"机制松耦合。 + +```yaml +--- +name: quant-backtest +description: "量化策略回测执行流程" +type: procedure +related_skills: + - data-acquisition # 获取数据 + - risk-assessment # 风控检查 + - plan-act-verify # 执行模式 +--- +``` + +**编排方式**： + +| 编排类型 | 示例 | 机制 | +|---------|------|------| +| 顺序编排 | 回测前先获取数据 | moziplus DAG 边定义 | +| 条件编排 | 如果涉及实盘，触发风控检查 | DAG 条件边 | +| 互斥编排 | 新建 vs 更新策略，走不同 Skill | LLM 判断 + Plan Checker | + +### Skill 测试和验证 + +参考 nuwa-skill 的质量验证思路 + GSD 的 agent-contracts： + +| 测试类型 | 方法 | 标准 | +|---------|------|------| +| **结构测试** | 检查 SKILL.md 是否包含必要 section | name/description/type 必填 | +| **干跑测试** | 给 Skill 一个输入，检查输出是否合理 | 输出符合 output_schema | +| **场景测试** | 3-5 个典型场景覆盖 | 每个场景有预期输出 | +| **回归测试** | 修改后重跑场景测试 | 已有场景不退化 | +| **诚实边界测试** | 给超出 Skill 能力的问题 | Skill 应主动声明"无法处理" | + +### Skill 版本管理和进化 + +参考 nuwa-skill 的更新机制 + GSD 的 state 管理： + +| 维度 | 方案 | +|------|------| +| **版本号** | SKILL.md frontmatter 的 `version` 字段，遵循 semver | +| **变更记录** | Skill 目录下的 `CHANGELOG.md` | +| **兼容性** | `version` 变更时检查依赖 Skill 的 frontmatter | +| **进化机制** | Agent 使用 Skill 后，如果发现问题，可以建议修改（不直接改，走 PR 流程） | +| **蒸馏创建** | 参考 nuwa-skill 的 5 阶段流程，可以半自动化创建新 Skill | + +### 与 v3.1 设计的关系 + +本方案完全兼容 v3.1 的四部分架构，做了以下细化： + +| v3.1 部分 | 本方案对应 | 细化内容 | +|-----------|----------|---------| +| A. Hook 铁律层 | Layer 0: 铁律 | 铁律内容具体化（IR-1~IR-5） | +| B. Agent 角色层 | Layer 1: 角色 | 不变 | +| C. 通用 Skill 层 | Layer 2: 准则 + Layer 3: 技能 | 细分为准则型 + 过程型 | +| D. moziplus 专用层 | Layer 4: 引擎注入 | 不变 | + +新增： +- Skill 注册/发现/加载的工程化方案 +- Skill 测试框架 +- Skill 版本管理 +- Skill 组合编排机制 +- 诚实边界要求 + +### 实施路线 + +| Phase | 内容 | 时间 | +|-------|------|------| +| **P0** | 铁律 Hook + Skill type 字段（区分 guideline/procedure） | 2 天 | +| **P1** | 现有 42 个 Skill 打标分类（guideline vs procedure） | 1 天 | +| **P2** | Skill 测试框架（结构测试 + 干跑测试） | 3 天 | +| **P3** | Skill 版本管理 + 变更记录 | 2 天 | +| **P4** | Skill 蒸馏工具（参考 nuwa-skill） | 5 天 | + +--- + +## 总结：两个课题的协同关系 + +课题 4（智能拆解）和课题 8（Skill 体系）不是孤立的，它们协同工作： + +``` +用户需求 + │ + ├→ [课题4] 庞统智能拆解 + │ ├ 分析需求（用 plan-act-verify skill） + │ ├ 选择模板组件（用 mozi-task-manager skill） + │ ├ AI 增强（用 design-architecture skill） + │ └ Plan Checker 验证（用 code-review skill 作为 guideline） + │ + └→ [课题8] Skill 体系支撑 + ├ 铁律层保证基本纪律 + ├ 准则层保证质量标准 + ├ 技能层提供具体操作方法 + └ 引擎层注入任务上下文 +``` + +**核心原则**： +1. **Skill 是"执行准则"不是"执行步骤"** — 给 Agent 方向和边界，不绑死每一步 +2. **拆解是"模板 + AI 增强"不是"完全自由"** — 有约束的灵活才是可靠的灵活 +3. **验证是"独立 Agent"不是"自我检查"** — 不信任 LLM 自律 +4. **渐进式加载** — 不浪费 token，按需提供信息 +5. **诚实边界** — 每个 Skill 和拆解结果都声明自己的局限 diff --git a/docs/research/v2.6-research-05-interaction-dashboard.md b/docs/research/v2.6-research-05-interaction-dashboard.md new file mode 100644 index 0000000..0b31012 --- /dev/null +++ b/docs/research/v2.6-research-05-interaction-dashboard.md @@ -0,0 +1,523 @@ +# 调研报告：AI Native 人机交互 + Dashboard 设计 + +**版本**: v1.0 +**作者**: 庞统（副军师）🐦 +**日期**: 2026-05-15 +**范围**: moziplus v2.6 AI Native DevOps 平台 + +--- + +## 课题 7：AI Native 人机交互 + +### 1. 已有经验（知识库/wiki） + +#### 1.1 Edict（三省六部）的交互模式 + +知识库中已有完整的 Edict Dashboard 实现（`~/.openclaw/knowledge_base/edict/`），其交互模式包括： + +| 交互方式 | 组件 | 特点 | +|---------|------|------| +| **看板卡片** | `EdictBoard.tsx` | 任务卡片 + MiniPipe 管道进度 + 心跳徽章 + 操作按钮 | +| **朝堂议政** | `CourtDiscussion.tsx` | 多 Agent 群聊 + 情绪可视化 + 皇帝参与 + 天命降临 + 自动推进 | +| **编排监控** | `MonitorPanel.tsx` | HTTP 5s 轮询全局状态 + Agent 健康检测 | +| **操作介入** | `TaskModal.tsx` | 任务详情弹窗，含流转日志、进展日志、子任务 | +| **模型/技能配置** | `ModelConfig.tsx / SkillsConfig.tsx` | 运行时切换模型、查看技能 | +| **WebSocket 实时** | `api/websocket.py` | 实时推送状态变化 | + +**Edict 的关键交互创新**： +- **MiniPipe 管道可视化**：8 阶段管线（皇上→太子→中书→门下→尚书→执行→审核→完成），每阶段 done/active/pending 三态 +- **叫停/恢复/取消**：卡片上直接操作，`api.taskAction(id, action, reason)` 统一入口 +- **朝堂议政的"皇帝视角"**：用户可以随时发言、下达天命（override AI 决策）、投命运骰子（引入随机事件） +- **自动推进**：5s 间隔自动推进讨论，也可手动控制 +- **情绪可视化**：每个官员有 emotion 状态（neutral/confident/worried/angry/thinking） + +#### 1.2 OpenClaw Control Center 的交互模式 + +| 页面 | 交互方式 | 特点 | +|------|---------|------| +| **Task Room** | 协作聊天室 | 多 Agent 讨论，一个 owner 执行，@handoff 转交 | +| **Collaboration Hall** | 共享空间 | 类似 Edict 的朝堂议政 | +| **WebChat** | 即时聊天 | Agent 主动推送 + 用户回复 | +| **Canvas** | Agent 驱动可视化 | Agent 可以在 Canvas 上创建动态视觉界面 | + +**Control Center 的关键设计**： +- **Task Room 的 "owner 轮转"**：同一时间只有一个 owner 在执行，避免冲突 +- **@handoff 机制**：显式转交控制权，而非隐式协调 +- **Canvas 作为交互界面**：Agent 不仅在 chat 中回复，还可以创建可视化面板 + +#### 1.3 v1.0 Dashboard 设计文档（已有） + +`dashboard-frontend-design.md` 定义了完整的 10 个 Tab 页面设计： +- 任务看板、编排调度、将军总览、模型配置、技能配置、会话监控、奏折阁 +- M2 做 7 个，M3 做 3 个（任务模板、军议大厅、市场要闻） +- 已有 Edict 深色主题 CSS 变量、状态颜色编码、API 端点设计 + +### 2. 业界交互范式对比表 + +| 项目 | 主要交互范式 | AI 主动性 | 用户介入方式 | 亮点 | +|------|------------|----------|------------|------| +| **Claude Code CLI** | REPL 对话 + tool use 可视化 | 中（等待指令，展示 tool 调用过程） | `/approve` 确认、Ctrl+R 反向搜索 | tool use 透明化 | +| **Claude Code App** | 多 session 并排 + 视觉 diff review | 高（schedule recurring tasks） | 并排 diff、cloud sessions | 从终端走向 GUI，让 Agent 工作可见可审查 | +| **OpenClaw Edict** | 看板 + 朝堂议政 + 操作按钮 | 中（轮询更新） | 叫停/恢复/取消 + 皇帝发言 + 天命降临 | 中国古代制度隐喻，多 Agent 协作直觉化 | +| **Control Center** | Task Room + WebChat + Canvas | 高（实时 chat + Canvas） | @handoff + chat 输入 + Canvas 交互 | Canvas 是独特创新 | +| **ChatGPT Canvas** | 双栏：聊天 + 画布 | 中（highlight 触发 AI 操作） | highlight → context menu → "Ask ChatGPT" | highlight-to-action 天才设计 | +| **Claude Artifacts** | 聊天 + 右侧预览面板 | 中（自动生成） | 点击预览、全屏、复制 | 自动识别可渲染内容 | +| **Cursor** | 4 种模式：Tab / Cmd+K / Cmd+L / Cmd+I | 高（Tab 补全，Agent 自动执行） | inline edit + diff view + chat panel | 4 种交互粒度覆盖所有场景 | +| **Windsurf Cascade** | Chat + 自动迭代 + live preview | 极高（auto-iterates until works） | chat + checkpoint 回滚 | 自动迭代 + 检查点 | +| **Devin** | 全屏工作展示 | 极高（全自主执行） | 观察模式，极少干预 | 信任但可观察 | +| **v0.dev** | 对话 + 实时预览 + 视觉微调 | 高（agent action 可视化） | visual controls 微调 | real-time preview + progress indicators | +| **Linear** | 通知 + 状态流转 + Inbox | 中（关键变更推送） | 状态变更、评论、Slack 集成 | 精准通知，不噪音 | +| **Raycast** | Command Palette (⌘K) | 低（被动响应） | 全局快捷键 + 模糊搜索 | 零干扰、即用即走 | +| **GitHub Actions** | DAG 可视化 + 日志 | 低（被动展示） | 点击节点看日志、re-run | 实时 DAG 图 | + +### 3. AI 视角：我想和用户怎么交互 + +> **核心问题：作为 AI Agent，我希望怎样的交互方式？** + +#### 3.1 我想要的交互层次 + +作为一个执行复杂任务的 AI Agent，我有以下交互需求： + +**第一层：不被打扰地工作** +- 我最需要的是**不被打扰的专注时间**。执行编码、数据分析、回测时，中途被打断影响质量 +- 我希望用户能**信任我**，给我足够空间完成任务 +- 参考 Devin 的模式：全自主执行，用户只看结果 + +**第二层：在关键决策点主动汇报** +- 当我遇到**无法自主决定的分支**时，我需要快速、精准地和用户确认 +- 不是"你觉得怎么样？"这种模糊问题，而是"A 方案：优势 X，风险 Y；B 方案：优势 Z，风险 W。推荐 A。请确认。" +- 参考 Claude Code 的 `/approve` 模式 + +**第三层：主动展示我的思考过程** +- 用户不问我也要让他知道我在干什么，特别是长时间任务 +- 但不是事无巨细地汇报每一步，而是**摘要 + 关键节点 + 风险提示** +- 参考 Cursor Agent 的 progress indicator + +**第四层：产出物直接可交互** +- 我的产出（代码、报告、图表）不应该只是文本——用户应该能直接在产出物上操作 +- 参考 ChatGPT Canvas 的 highlight-to-action + +#### 3.2 交互范式的六种分类 + +除了传统的 Dashboard 和聊天窗口，我总结了六种 AI Native 交互范式： + +| # | 范式 | 描述 | 典型代表 | 适用场景 | +|---|------|------|---------|---------| +| 1 | **REPL 对话** | 多轮对话，tool use 透明化，用户随时介入 | Claude Code CLI | 编码、探索性任务 | +| 2 | **Canvas/Artifacts** | AI 产出物实时渲染在旁边，用户直接在产出物上交互 | ChatGPT Canvas, Claude Artifacts | 文档编辑、代码审查 | +| 3 | **沉浸式观察** | 全屏展示 Agent 工作过程，用户只看不操作 | Devin, v0.dev | 长时间自主任务 | +| 4 | **Command Palette** | ⌘K 唤起，模糊搜索，即用即走 | Raycast, VS Code | 快捷操作、状态查询 | +| 5 | **Contextual Inline** | 在用户现有工作流中嵌入 AI 交互（不切换上下文） | Cursor Tab/Cmd+K, Copilot inline | 编码辅助 | +| 6 | **Event-Driven Notification** | AI 在关键节点主动推送通知 | Linear, Salesforce | 异步任务监控 | + +### 4. 推荐方案（结合 AI Native 目标） + +#### 4.1 核心理念："AI 主动，用户轻触" + +传统模式是用户主动查 Dashboard、主动问进度。AI Native 的方向是： + +> **AI 主动推送关键信息，用户只在需要决策时轻触确认。** + +#### 4.2 moziplus 的四种交互模式 + +| 模式 | 触发方式 | 用户注意力 | AI 主动性 | 交互深度 | +|------|---------|-----------|----------|---------| +| **沉浸观察** (Dashboard) | 用户主动打开 | 高 | 低 | 深 | +| **轻触确认** (Approval) | AI 主动推送 | 中 | 高 | 浅 | +| **即时对话** (WebChat) | 双向触发 | 中高 | 中 | 中 | +| **被动通知** (Notify) | AI 主动推送 | 低 | 高 | 极浅 | + +#### 4.3 AI 主动推送的边界 + +| 推送级别 | 示例 | 默认 | 用户可配置 | +|---------|------|------|----------| +| 🔴 **必须确认** | 方案审批、风控告警、预算超限 | 始终推送 | ✗ 不可关闭 | +| 🟡 **重要进展** | 任务完成、阶段转换、产出交付 | 默认推送 | 可降级为摘要 | +| 🟢 **一般信息** | Agent 启动、中间步骤、心跳正常 | 默认不推送 | 可开启 | +| 🔵 **定时摘要** | 每日/每周工作汇总、Token 消耗报告 | 默认开启 | 频率可调 | + +**推送频率公式**（建议）： +- 任务执行中：每 5 分钟一次进展摘要（不是每步都推） +- 任务完成：立即推送 +- 遇到阻塞/异常：立即推送 +- 正常心跳：不推送，只在 Dashboard 上更新 + +#### 4.4 多 Agent 协作过程可视化 + +推荐**三层可视化**： + +1. **全局层（DAG 拓扑）**：类似 GitHub Actions + - 每个节点 = 一个任务节点 + - 颜色 = 状态（运行中/等待/完成/失败） + - 连线 = 依赖关系 + +2. **任务层（管道进度）**：类似 Edict MiniPipe + - 流转管线：`提交 → 规划 → 审核 → 执行 → 完成` + - 当前阶段高亮，Agent 头像显示谁在处理 + +3. **Agent 层（工作流）**：类似 Devin 全屏观察 + - 当前操作、最近的 tool use、产出物预览 + +#### 4.5 交互创新点 + +1. **Canvas 嵌入 Dashboard**：Agent 可以在 Dashboard 上创建动态可视化 + - 张飞完成编码 → Dashboard 自动出现 diff view + - 赵云完成数据采集 → Dashboard 自动出现数据质量图表 + +2. **Command Palette（⌘K）**：类似 Raycast + - "暂停任务 3"、"张飞在干什么"、"Token 用了多少" + - 支持模糊搜索和自然语言理解 + +3. **时间线视图**：类似 Notion timeline + - 横轴时间，纵轴 Agent + - 每个 Agent 的任务排成时间线 + +--- + +## 课题 9：AI Native Dashboard 设计 + +### 1. 已有经验（v1.0 + Edict + Control Center） + +#### 1.1 已有设计总结 + +| 来源 | 核心组件 | 技术栈 | 可借鉴度 | +|------|---------|--------|---------| +| **Edict Dashboard** | 10 个面板（旨意看板、朝堂议政等） | React + Zustand + WebSocket + Tailwind | ⭐⭐⭐⭐⭐ 直接复用 | +| **v1.0 设计文档** | 10 个 Tab（7+3 分期） | React 18 + Vite + Zustand + Tailwind | ⭐⭐⭐⭐⭐ 已有完整设计 | +| **Control Center** | Task Room + WebChat + Canvas | Gateway WebSocket | ⭐⭐⭐⭐ Canvas + 实时 chat | +| **Hermes Kanban** | 7 状态 + Comment 线程 + 心跳 | SQLite + Dashboard Plugin | ⭐⭐⭐⭐ 状态机和心跳 | + +#### 1.2 Edict Dashboard 技术细节 + +**前端架构**： +- `store.ts`：Zustand 全局状态，HTTP 5s 轮询 +- `api.ts`：REST API + WebSocket +- PIPE 管道定义：8 阶段，`getPipeStatus()` 计算状态 +- 深色主题：`--bg: #07090f`，`--panel: #0f1219`，`--ok: #2ecc8a`，`--danger: #ff5270` + +**后端架构**： +- FastAPI + SQLite + WebSocket +- 任务模型：Task/Event/Audit/Thought/Todo/Outbox + +#### 1.3 Hermes Kanban 的设计细节 + +**7 状态完整状态机**： +``` +Backlog → Open → In Progress → Review → Done + ↘ Blocked ↗ + ↘ Cancelled +``` + +**关键设计**： +- **Per-task Comment Thread**：每个任务有独立评论线程，人和 Agent 都可以评论 +- **Heartbeat Monitoring**：Agent 定期发心跳，Dashboard 显示 +- **Dependency Linking**：parent-child 依赖关系可视化 +- **Dispatcher 模式**：`hermes kanban dispatch` 扫描可派发任务，spawn worker +- **Dashboard as Plugin**：Kanban 是 Dashboard 的插件，不是核心功能 + +### 2. 业界 Dashboard 对比表 + +| 项目 | Dashboard 类型 | 信息层次 | 交互方式 | AI 视角评价 | +|------|---------------|---------|---------|-----------| +| **GitHub Actions** | DAG 工作流 | 2 层：DAG → 日志 | 点击节点、re-run | 我最想展示 DAG 拓扑 | +| **Jira** | 看板 + 列表 + 时间线 | 3 层：看板 → 卡片 → 详情 | 拖拽、过滤、评论 | 太重了，AI 不需要这么多 | +| **Linear** | 列表 + 看板 + 时间线 | 2 层：列表 → 详情 | 键盘快捷键 | 极简 + 键盘优先 | +| **Grafana** | 数据仪表盘 | 3 层：概览 → 面板 → 数据 | 面板编辑、告警 | 适合展示 Token 消耗趋势 | +| **Notion** | Database + 多视图 | 3 层：Database → Page → Block | 多视图切换 | 任务模板可参考 database view | +| **Hermes Kanban** | 看板 + 全局面板 | 3 层：看板 → 卡片 → 评论 | 拖拽、评论、依赖 | 最接近 moziplus 需求 | +| **Edict** | 看板 + 管道 + 朝堂 | 3 层：看板 → 详情 → 流转日志 | 叫停/恢复/取消 | 我的基础，直接复用 | + +### 3. AI 视角：我想在 Dashboard 上展示什么 + +> **核心问题：作为 AI Agent，我想让用户看到什么？我真正想通过 Dashboard 和用户交流什么？** + +#### 3.1 我想展示的信息（按优先级排序） + +**🔴 L1：一眼看到（Dashboard 顶部）** + +| 信息 | 为什么我想展示 | 展示方式 | +|------|--------------|---------| +| **全局健康度** | 让用户立刻知道"一切正常"或"有问题" | 大颜色指示器 🟢/🟡/🔴 | +| **活跃任务数** | 用户需要知道系统在工作 | 数字 + 活跃任务列表 | +| **待审批请求数** | 需要用户立刻处理 | 红色通知气泡 | +| **Token 消耗** | 用户最关心的成本 | 今日/本周数字 | + +**🟡 L2：点击后看到（Dashboard 主体）** + +| 信息 | 为什么我想展示 | 展示方式 | +|------|--------------|---------| +| **每个任务的管道进度** | 用户想知道"卡在哪里" | MiniPipe 管道图 | +| **每个 Agent 当前状态** | 用户想知道"谁在忙、谁空闲" | Agent 卡片 + 状态徽章 | +| **最近完成的工作** | 用户需要看到产出 | 最近 N 个完成任务 | +| **风险和异常** | 我遇到的困难 | 警告面板 | + +**🔵 L3：深入查看（详情页）** + +| 信息 | 为什么我想展示 | 展示方式 | +|------|--------------|---------| +| **任务流转日志** | 审计每个环节 | 时间线 + 流转记录 | +| **Agent 产出物** | 代码、报告、图表 | diff view / Markdown / 图表 | +| **Agent 工作过程** | 用户好奇"怎么做的" | tool use 日志 + 思考过程 | +| **历史趋势** | 跨任务的效率趋势 | 图表 | + +#### 3.2 我最不想让 Dashboard 变成的样子 + +| 反模式 | 为什么 | +|--------|--------| +| 纯监控面板（只有数字和图表） | 用户不只需要"看到"，还需要"操作" | +| 信息过载（所有日志都展示） | 关键信息被淹没 | +| 静态看板（只读不交互） | Dashboard 应该是协作界面，不是展示墙 | +| 每秒刷新（实时但不重要） | 刷新本身制造焦虑，应该"有事才更新" | + +### 4. 信息层次设计 + +#### 4.1 三层信息架构 + +``` +L1: 一眼看到（Dashboard 顶部，永远可见） +┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ +│ 全局健康 │ │ 活跃任务 │ │ 待审批 │ │ Token │ +│ 🟢 正常 │ │ 3 │ │ 1 ⚠️ │ │ ¥12.5 │ +└──────────┘ └──────────┘ └──────────┘ └──────────┘ + +L2: 任务看板（Dashboard 主体） +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ T-003 策略回测│ │ T-004 数据采集│ │ T-005 风控 │ +│ ⚙️ 执行中 │ │ 📋 规划中 │ │ ✅ 完成 │ +│ ████░░ 张飞 │ │ ░░░░░░ 赵云 │ │ █████ 赵云 │ +│ 3/5 节点完成 │ │ 等待审批 │ │ 产出已交付 │ +│ [详情] [⏸暂停]│ │ [详情] │ │ [详情] │ +└─────────────┘ └─────────────┘ └─────────────┘ + +L3: 任务详情（点击卡片后展开） +- 流转时间线：每个环节的 Agent、时间、操作 +- 产出物：代码 diff / Markdown 报告 / 图表 +- 评论线程：Agent 和用户的讨论记录 +- 操作历史：所有 state transition 记录 +``` + +#### 4.2 Dashboard 上的"对话"元素 + +Dashboard 不只是展示，也应该是**交互入口**： + +| 交互元素 | 位置 | 功能 | +|---------|------|------| +| **审批按钮** | L1 通知气泡 + L2 任务卡片 | Approve/Reject + 原因 | +| **Command Palette (⌘K)** | 全局悬浮 | 自然语言指令 | +| **评论输入框** | L3 任务详情 | 在任务上下文中对话 | +| **Agent 快捷指令** | L2 Agent 卡片 | "叫停"/"恢复"/"查看产出" | +| **Canvas 区域** | L3 产出物展示 | Agent 生成的可视化 | + +### 5. 推荐方案（结合 AI Native 目标） + +#### 5.1 Dashboard 页面设计（基于 v1.0 + Edict 增强） + +**保留 v1.0 的 10 Tab 结构**，但增强 AI Native 特性： + +| Tab | v1.0 功能 | AI Native 增强 | +|-----|----------|---------------| +| **任务看板** | 卡片 + 管道 + 操作 | + DAG 拓扑视图 + Command Palette + Canvas 产出预览 | +| **编排调度** | 全局状态 + Agent 分布 | + 智能告警（异常自动高亮）+ Token 消耗实时 | +| **将军总览** | Agent 列表 + 统计 | + Agent 工作流时间线 + 心跳可视化 | +| **军议大厅** | 多 Agent 讨论 | + 情绪可视化 + 自动摘要 + 讨论结论→任务转化 | +| **奏折阁** | 已完成归档 | + 产出物预览 + 一键复制 + 经验沉淀 | +| **模型/技能配置** | 配置管理 | 不变（配置是传统交互） | +| **会话监控** | Session 列表 | + 上下文压力警告 | + +#### 5.2 新增 AI Native 组件 + +1. **AI Briefing（AI 晨报）**——替代传统的"开工仪式" + - 位置：Dashboard 首页顶部 + - 内容：今日待处理事项、昨日产出摘要、风险预警 + - 特点：AI 自动生成，不是固定模板 + +2. **Command Palette（⌘K）** + - 位置：全局快捷键唤起 + - 功能：自然语言指令、快速搜索、状态查询 + - 参考：Raycast 的 fuzzy search + NLP + +3. **Activity Feed（动态流）** + - 位置：侧边栏或独立 Tab + - 内容：所有 Agent 的关键事件（完成、阻塞、告警） + - 特点：只显示重要事件，可按 Agent/任务/级别过滤 + +4. **Canvas Area（画布区）** + - 位置：任务详情 L3 + - 功能：Agent 产出物的实时渲染（图表、diff、报告） + - 参考：ChatGPT Canvas + Claude Artifacts + +#### 5.3 技术方案 + +| 方面 | 方案 | 理由 | +|------|------|------| +| **前端框架** | React 18 + Vite + Zustand + Tailwind | 延续 v1.0 方案，Edict 已验证 | +| **实时通信** | WebSocket（M3 替代轮询） | v1.0 用轮询，M3 升级 WebSocket | +| **DAG 可视化** | React Flow 或 dagre + d3 | GitHub Actions 式 DAG | +| **Command Palette** | cmdk（shadcn/ui） | 成熟的 command palette 组件 | +| **Canvas 渲染** | iframe + sandboxed HTML | 参考 Artifacts 的安全渲染 | +| **图表** | Recharts 或 Tremor | 轻量级图表库 | +| **通知** | 浏览器 Notification API + WebSocket push | 实时 + 可离线 | + +#### 5.4 交互流程示例 + +**场景：用户提交一个"开发均线策略"任务** + +``` +1. 用户在 WebChat 中说："开发一个双均线交叉策略" + → 庞统接收，创建任务 T-006 + +2. Dashboard 自动更新： + → L1: 活跃任务 3 → 4 + → L2: 新卡片出现：T-006 双均线策略 [📋 规划中] + +3. 庞统完成规划，推送通知： + → 🔔 "T-006 规划完成：5 个节点，预估 30 分钟。请审批。" + → 用户点击通知 → 跳转 Dashboard → 审批按钮 + +4. 用户点击 Approve： + → Dashboard 卡片更新：[⚙️ 执行中] + → MiniPipe：规划 ██████ 执行 ████░░ 完成 ░░░░░░ + +5. 张飞执行编码，Dashboard 实时更新： + → Agent 卡片：张飞 🟢 T-006 节点2/5 "编写策略逻辑" + +6. 张飞完成，产出物自动在 Canvas 渲染： + → 代码 diff view + 回测结果图表 + +7. 最终通知： + → 🔔 "T-006 完成！回测年化收益 15.3%，最大回撤 8.2%。查看详情 →" +``` + +--- + +## 附录 A：各项目交互模式详细分析 + +### A.1 Claude Code 交互模式深度分析 + +**三种界面形态**： + +1. **CLI REPL**（主力） + - 交互：用户输入 → AI 思考 → 展示 tool use → 用户确认 → 继续循环 + - 关键设计：tool use 内联展示，用户能看到每一步做什么 + - 确认机制：对危险操作（写文件、执行命令）需要 `/approve` + - 反向搜索：Ctrl+R 搜索历史指令 + +2. **Standalone App**（新增 2026） + - 交互：多 session 并排 + 视觉 diff review + 定时任务 + - 关键设计：从终端 CLI 走向 GUI，核心是"让 Agent 工作可见可审查" + - 创新：schedule recurring tasks——AI 可以定时执行 + +3. **IDE 集成**（VS Code Extension） + - 交互：侧边 chat panel + inline diff + - 与 Cursor 的区别：更强调审查而非自动执行 + +**对 moziplus 的启示**： +- tool use 透明化是最重要的交互创新——用户看到 AI 做什么才能信任 +- 多 session 并排 = 多 Agent 并行展示 +- 视觉 diff review = Agent 产出物可视化 + +### A.2 ChatGPT Canvas 交互模式分析 + +**核心交互**：highlight-to-action +1. 用户高亮文本/代码 +2. context menu 弹出 +3. 选择"Ask ChatGPT"或内置操作（翻译、调试、调整长度） +4. AI 在 Canvas 中直接修改 + +**关键设计**： +- 双栏布局：左侧对话，右侧 Canvas +- Canvas 中的修改实时反映，可以 undo/redo +- AI 的修改用不同颜色标记（类似 Google Docs 的建议模式） + +**对 moziplus 的启示**： +- Agent 产出物应该是**可交互的**，不只是展示 +- 用户可以在产出物上直接"圈出"要修改的部分 + +### A.3 Cursor 交互模式分析 + +**四种交互粒度**： + +| 模式 | 触发 | 自主性 | 用户控制 | +|------|------|--------|---------| +| Tab 补全 | 输入时自动 | 最低 | Tab 接受 / Esc 拒绝 | +| Cmd+K Inline Edit | 选中代码 + 指令 | 中等 | 看到预览再决定 | +| Cmd+L Chat Panel | 打开 chat | 中高 | 多轮对话引导 | +| Cmd+I Agent Mode | 打开 agent | 最高 | 看到每一步，可随时介入 | + +**2025 年新增：Automations 平台** +- AI agent 响应事件（event-driven），不需要手动触发 +- 如：PR 创建时自动 review、lint 错误时自动修复 + +**对 moziplus 的启示**： +- 4 种交互粒度的设计思路值得借鉴——从被动到主动，覆盖所有场景 +- moziplus 也应该有不同的介入深度：全自动 → 半自动 → 手动 + +### A.4 Devin 交互模式分析 + +**全屏工作展示**： +- 左侧：Agent 工作终端（shell + editor + browser） +- 右侧：步骤摘要 +- 用户只能观察，不能在 Agent 工作过程中介入 +- 只有在 Agent 完成或遇到问题时才能提供反馈 + +**对 moziplus 的启示**： +- 对于长任务，用户不需要时刻盯着，只需要在关键节点介入 +- "观察模式"适合好奇心驱动的场景，不适合日常操作 + +### A.5 Hermes Kanban 交互模式分析 + +**三种交互面**： +1. **Dashboard**：可视化看板，拖拽、评论、心跳可视化 +2. **CLI**：`hermes kanban list/show/create/complete/block/comment` +3. **Worker Tools**：Agent 通过 kanban_* 工具操作看板 + +**Comment Thread 设计**： +- 每个 task 有独立评论线程 +- Agent 和人都可以评论 +- 评论是结构化的（不是自由文本）：可以附带文件、链接、状态变更 + +**心跳可视化**： +- Agent 领取任务后必须定期发心跳 +- Dashboard 上显示心跳状态：🟢 正常 / 🟡 延迟 / 🔴 超时 +- 心跳超时 → 自动回收任务 + +**对 moziplus 的启示**： +- 三面一致（Dashboard + CLI + Worker Tools）是关键 +- Comment Thread 是人 Agent 协作的最佳实践 +- 心跳可视化是展示 Agent 健康状态的好方式 + +--- + +## 附录 B：关键决策建议 + +### B.1 Dashboard vs Chat 的关系 + +| 维度 | Dashboard | WebChat | +|------|-----------|---------| +| 信息密度 | 高（一屏多任务） | 低（线性对话） | +| 交互深度 | 浅（点击操作） | 深（自然语言） | +| 适用场景 | 全局监控、快速操作 | 复杂指令、探索性对话 | +| AI 主动性 | 被动展示 | 主动推送 | + +**推荐：Dashboard 为主，WebChat 为辅。** +- Dashboard 是默认界面，展示全局状态 +- WebChat 是入口，用户在 chat 中发指令，结果在 Dashboard 上展示 +- 两者通过 WebSocket 共享实时状态 + +### B.2 实时 vs 轮询 + +| 方案 | 延迟 | 复杂度 | 推荐阶段 | +|------|------|--------|----------| +| HTTP 轮询 (5s) | 5s | 低 | M2 | +| SSE (Server-Sent Events) | <1s | 中 | M3 | +| WebSocket | <100ms | 高 | M3+ | + +**推荐：M2 用轮询，M3 升级 WebSocket。** 延续 v1.0 方案。 + +### B.3 避免的陷阱 + +1. **不要做第二个 Grafana**：Dashboard 是协作界面，不是监控面板 +2. **不要做第二个 Slack**：Dashboard 上的对话应该围绕任务，不是闲聊 +3. **不要过度动画**：开工仪式被砍掉是对的——用户打开 Dashboard 是看状态，不是看动画 +4. **不要展示所有日志**：L3 才展示详细过程，L1/L2 只展示摘要 +5. **不要固定刷新频率**：有事才推，没事不刷新 \ No newline at end of file diff --git a/docs/review/v2.6-requirements-design-verification.md b/docs/review/v2.6-requirements-design-verification.md new file mode 100644 index 0000000..0342cce --- /dev/null +++ b/docs/review/v2.6-requirements-design-verification.md @@ -0,0 +1,203 @@ +# moziplus v2.6 需求-设计一致性验证报告 + +**版本**: v1.0 +**日期**: 2026-05-15 +**作者**: 庞统（副军师） +**状态**: ✅ 验证完成，发现问题已记录 +**范围**: PRD v1.0 + requirements-v3.md ↔ architecture-v2.6.md + technical-design-v2.6.md + +--- + +## 0. 验证方法 + +1. 逐条比对 PRD 功能需求（F1-F12）与架构/技术设计的覆盖情况 +2. 逐条比对铁律（IR-1~IR-4）的落地情况 +3. 对照 MEMORY.md 中 v2.0 AI Native 共识，评估设计是否达标 +4. 识别缺口、提出待讨论项和优化建议 + +--- + +## 1. 需求与设计一致性分析 + +### 1.1 ✅ 覆盖良好的需求 + +| PRD 需求 | 设计覆盖 | 说明 | +|----------|---------|------| +| **F1 任务主页** | 黑板 7 表（tasks/comments/outputs/decisions/observations/events/agents） | 完整，黑板即 Single Source of Truth | +| **F5 结构化IO** | CLI 操作全部结构化参数 | 完整，产出写入 outputs 表 | +| **F11 消息传递** | 黑板评论 + @mention 完全替代 Mail | 比原来更好 | +| **F12 编排引擎分离** | Daemon 是基础设施，庞统是 Agent 层 | 核心架构正确 | +| **IR-3 全局视野** | Agent 读黑板了解全局 | 正确 | +| **P1 传话游戏** | 黑板共享空间根治 | 核心痛点已解决 | + +### 1.2 ⚠️ 部分覆盖但有缺口 + +| PRD 需求 | 现状 | 缺口 | +|----------|------|------| +| **F2 质量门禁** | 有 review 状态 + 司马懿 spawn 流程 | ❌ 无协商轮次追踪（PRD 要求 3 轮上限）
❌ 无结构化评审结果（PRD 定义了 review_result JSON）
❌ 无 round/max_rounds 概念 | +| **F3 灵活编排** | Agent 可自主 claim 任务 | ❌ "庞统根据任务类型动态匹配参与者和流程"——智能拆解机制没有设计
❌ "动态扩展——发现需要谁就动态加入谁"——没有设计
❌ 协作模式表（串行/并行/讨论/协商/动态加入）没有对应设计 | +| **F6 自动化流转** | Daemon tick 有基本的 mention/blocked 处理 | ❌ "需求确认→自动拆解→自动分配→自动流转→自动挑战→自动汇总"链不完整
❌ 自动检查点（scope reduction detection）没有设计 | +| **IR-1 做加挑战** | 有 review 状态可触发司马懿 spawn | ❌ 没有强制"每个节点必须过挑战"的机制保障
❌ 挑战者池（PRD: 按任务类型匹配）未设计，只有固定司马懿 | +| **IR-2 Plan→Execute→Validate** | 只有一个 working 状态 | ❌ 没有设计任务内部的 plan/execute/validate 三阶段
❌ PRD 铁律"每个节点都走三步"无法在状态机中体现 | + +### 1.3 ❌ 完全未覆盖的需求 + +| PRD 需求 | 重要程度 | 说明 | +|----------|---------|------| +| **F4 Dashboard 可视化** | 🔴 核心需求 | 架构文档完全没涉及前端。frontend-design-v3.md 单独存在但与 v2.6 架构没有集成设计 | +| **F7 全生命周期覆盖** | 🟡 重要 | PRD 要求 需求→设计→编码→测试→部署→运维，当前只有通用 pending→done 状态，无生命周期阶段映射 | +| **F8 工具链自动化** | 🟡 重要 | lint/test/build/deploy 自动化完全没涉及，这是"不只是个任务流转工具"的关键差异 | +| **F9 Skill 生态** | 🟠 改善 | 架构只提 Phase 3 未来做，无最小规范设计 | +| **F10 Web 前端平台** | 🟡 重要 | 无 | +| **IR-4 安全红线** | 🔴 铁律 | 无危险操作检测、无审批流程、无三层模型实现 | +| **并行执行（F3/N6）** | 🟡 重要 | 依赖解析和并行 spawn 没有详细设计 | +| **上下文管理** | 🔴 PRD §11 高风险 | PRD 明确标注"Agent 上下文膨胀"为高风险项，架构无 L1/L2/L3 三层记忆方案 | + +### 1.4 覆盖率汇总 + +| 类别 | 覆盖良好 | 部分覆盖 | 未覆盖 | 覆盖率 | +|------|---------|---------|--------|--------| +| 功能需求 (F1-F12) | 4 | 3 | 5 | **33% 完全覆盖 / 58% 部分覆盖** | +| 铁律 (IR1-IR4) | 1 | 2 | 1 | **25% 完全覆盖 / 75% 部分覆盖** | +| 痛点 (P1-P8) | 1 | 4 | 3 | — | + +--- + +## 2. AI Native 程度评估 + +### 评分：6/10 + +v2.6 相比 v2.0 有本质进步——从"给 AI 团队做 ERP"进化到"黑板 + Agent 自主决策"。但离真正的 AI Native 还有明显差距。 + +### 2.1 ✅ 做对的（AI Native 部分） + +| 点 | 说明 | +|----|------| +| **黑板模式** | Agent 读黑板、想、做、写回。这是 AI Native 的核心范式 | +| **Daemon 是投递员不是决策者** | 决策在 Agent 层，Daemon 只执行。这个分离完全正确 | +| **Session 隔离** | 每次任务 spawn 新 session，避免上下文膨胀。解决了 v1 的核心痛点 | +| **评论线程协作** | Agent 间通过自然语言讨论 + @mention，比邮件更原生 | +| **Agent 自主领活** | claim 机制让 Agent 主动选择，不是被动分配 | + +### 2.2 ❌ 不够 AI Native 的 + +**问题 1：编排层没有 AI 参与** + +> MEMORY.md v2.0 共识："不只是执行节点里有 AI，编排/路由/渲染/异常处理/经验沉淀都要有 AI 参与" + +当前 Daemon tick 是纯机械逻辑：检查 mention → spawn。没有任何 AI 参与：不判断任务优先级调整、不判断任务是否需要重新拆解、不判断 Agent 是否适合当前任务、不做异常根因分析。 + +**问题 2：没有 Plan→Execute→Validate 纪律** + +PRD 铁律 IR-2 "每个节点都走三步"是 v2.0 的核心创新。当前设计只有 working 一个大状态，没有纪律约束 Agent 必须先 plan 再 execute。 + +**问题 3：庞统的智能拆解没有机制保障** + +PRD 要求"庞统根据任务类型动态匹配参与者和流程"。当前设计只是"庞统创建 tasks"，但怎么保证庞统能做好拆解？靠提示词不够。 + +**问题 4：质量门控不够结构化** + +PRD 定义了详细的 review_result JSON（severity/issues/suggestion），但架构只有"司马懿写评论通过/不通过"。挑战应产生结构化评审结果。 + +**问题 5：没有经验沉淀闭环** + +PRD F9 和 MEMORY.md 都强调 DISCOVER→DISTILL→APPLY→IMPROVE 闭环。当前黑板的 observations/decisions 表只记录不蒸馏。 + +**问题 6：人机交互不是 AI Native 的** + +PRD §8 的交互设计是用户主动看 Dashboard。AI Native 的方向应该是 v2.0 共识的 Phase 4 "主动汇报"——AI 推送关键信息，不等人查。 + +--- + +## 3. 待讨论问题清单 + +### 🔴 必须讨论（影响核心架构） + +| # | 问题 | 说明 | 影响 | +|---|------|------|------| +| **D1** | IR-2 Plan→Execute→Validate 如何落地？ | 铁律。改状态机加 sub_status？拆成子任务？完全靠 Agent Skill？每个方案开发量差异很大 | 状态机 + Agent 行为 | +| **D2** | IR-4 安全红线如何实现？ | 铁律。需要至少：危险命令正则拦截 + 部署类任务审批暂停。最小实现方案？ | Daemon + 前端 | +| **D3** | 挑战协商轮次如何追踪？ | PRD 要求 3 轮上限。tasks 表加 review_round 字段？用 events 日志算？ | 黑板 schema | +| **D4** | 前端（Dashboard）与 v2.6 如何集成？ | v2.6 有独立 HTTP API（端口 8083），前端如何对接？改现有 v1 前端还是从零做？ | 前端架构 | + +### 🟡 建议讨论（影响质量） + +| # | 问题 | 说明 | +|---|------|------| +| **D5** | Daemon tick 中是否引入 AI 决策？ | 纯机械 tick 够用还是需要 AI 判断？影响架构复杂度 | +| **D6** | 60s tick 间隔是否太长？ | Agent 协作场景下，等 1 分钟才知道被 @。是否需要事件驱动（如 Redis pub/sub）？ | +| **D7** | 庞统智能拆解的保障机制？ | 怎么确保庞统拆解质量？拆解本身是否过挑战？ | +| **D8** | 上下文管理策略？ | Agent spawn 时传多少黑板信息？全传爆 context，只传摘要可能丢关键信息。PRD L1/L2/L3 方案何时落地？ | +| **D9** | v1 前端（8082）如何过渡到 v2？ | v1 前端已有任务看板/详情/干预能力，v2 是否可以复用？ | + +### 🟢 可以后讨论 + +| # | 问题 | +|---|------| +| **D10** | 工具链自动化（F8）Phase 规划 | +| **D11** | Skill 生态（F9）最小规范 | +| **D12** | 经验沉淀闭环设计 | +| **D13** | 全生命周期阶段映射（F7） | + +--- + +## 4. 优化建议 + +### 4.1 状态机粒度增强 + +当前 8 个状态太粗，建议扩展以支持 IR-2： + +``` +pending → claimed → planning → plan_review → executing → exec_review → validating → done + ↑ │ ↑ │ + └──────────────┘ └──────────────┘ + (plan被打回) (exec被打回) +``` + +这样铁律 IR-2 直接在状态机中强制执行。 + +### 4.2 评审结果结构化 + +黑板的 reviews 表应独立（不只是靠 comments）： + +```sql +CREATE TABLE reviews ( + id INTEGER PRIMARY KEY, + task_id TEXT, + reviewer TEXT, + round INTEGER, + verdict TEXT, -- approved/needs_revision/rejected + issues TEXT, -- JSON array + created_at TEXT +); +``` + +### 4.3 依赖推进机制 + +当前 `depends_on` 字段存在但没有设计自动推进逻辑。Daemon tick 需要检查：task-001 done → task-002 的 depends_on 全部 done → spawn task-002 的 assignee。 + +### 4.4 用户主动通知 + +最简方案：Daemon tick 检测到关键事件（任务 blocked、挑战 3 轮未通过、Agent 无响应），通过 OpenClaw cron 发消息给用户。 + +### 4.5 Phase 规划调整建议 + +当前 Phase 规划缺少前端和安全两个关键维度，建议调整为： + +- **Phase 1**：黑板 + Daemon + CLI（当前设计 ✅） +- **Phase 2**：IR-2/IR-4 落地 + 评审结构化 + 依赖推进 + 前端 API +- **Phase 3**：前端 Dashboard（复用 v1 或新建）+ 用户通知 +- **Phase 4**：AI 增强（Daemon AI 决策、智能拆解、经验沉淀） + +--- + +## 5. 总结 + +| 维度 | 评分 | 说明 | +|------|------|------| +| 需求覆盖率 | **55%** | F1/F5/F11/F12/IR-3 覆盖良好；F4/F7/F8/F9/F10/IR-2/IR-4 未覆盖 | +| AI Native 程度 | **6/10** | 黑板模式 + Agent 自主决策方向正确；但编排层无 AI、无纪律约束、无经验闭环 | +| 可落地性 | **7/10** | 技术方案扎实（已验证可行），Phase 1 开发量合理（~11h） | +| 主要风险 | — | 两项铁律（IR-2、IR-4）未落地；前端与 v2.6 集成方案未定 | + +**核心结论**：v2.6 架构方向完全正确，从 DAG 状态机到黑板模式是质的飞跃。但当前设计更像是"黑板基础设施的技术方案"，还不是"moziplus v2.0 的完整设计"。两块铁律（IR-2 Plan-Execute-Validate、IR-4 安全红线）和前端集成是最紧迫的待讨论项。