auto-sync: 2026-05-15 09:31:37
This commit is contained in:
cfdaily
@@ -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 | 持久记忆 + 三层检索 |
|
||||
@@ -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 模式 |
|
||||
@@ -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:
|
||||
- <config 1> # 可能用不同的 prompt
|
||||
- <config 2> # 可能用不同的 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": "..."}
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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. **不要固定刷新频率**：有事才推，没事不刷新
|
||||
@@ -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 轮上限）<br>❌ 无结构化评审结果（PRD 定义了 review_result JSON）<br>❌ 无 round/max_rounds 概念 |
|
||||
| **F3 灵活编排** | Agent 可自主 claim 任务 | ❌ "庞统根据任务类型动态匹配参与者和流程"——智能拆解机制没有设计<br>❌ "动态扩展——发现需要谁就动态加入谁"——没有设计<br>❌ 协作模式表（串行/并行/讨论/协商/动态加入）没有对应设计 |
|
||||
| **F6 自动化流转** | Daemon tick 有基本的 mention/blocked 处理 | ❌ "需求确认→自动拆解→自动分配→自动流转→自动挑战→自动汇总"链不完整<br>❌ 自动检查点（scope reduction detection）没有设计 |
|
||||
| **IR-1 做加挑战** | 有 review 状态可触发司马懿 spawn | ❌ 没有强制"每个节点必须过挑战"的机制保障<br>❌ 挑战者池（PRD: 按任务类型匹配）未设计，只有固定司马懿 |
|
||||
| **IR-2 Plan→Execute→Validate** | 只有一个 working 状态 | ❌ 没有设计任务内部的 plan/execute/validate 三阶段<br>❌ 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 安全红线）和前端集成是最紧迫的待讨论项。
|
||||
Reference in New Issue
Block a user