diff --git a/docs/design/topic6-experience-loop-proposal.md b/docs/design/topic6-experience-loop-proposal.md new file mode 100644 index 0000000..eb54bf6 --- /dev/null +++ b/docs/design/topic6-experience-loop-proposal.md @@ -0,0 +1,320 @@ +# 课题6:经验沉淀闭环设计方案 + +**版本**: v1.0 +**作者**: 庞统(副军师)🐦 +**日期**: 2026-05-15 +**评审**: 待司马懿评审 +**状态**: 待评审 + +--- + +## 1. 设计目标 + +moziplus 的 Agent 在工作中产出了大量经验(决策、错误修正、最佳实践),但当前没有机制沉淀这些经验,导致每次任务都在"重新发明轮子"。本课题设计一个闭环系统,让经验自动采集、蒸馏、验证、应用、进化。 + +## 2. 核心洞察 + +> **问题**:v1.0 运行两个月,张飞修了 7 次类似的 bug,赵云踩了 3 次相同的数据格式问题。每次都是"重新发现",没有变成组织记忆。 +> +> **根因**:经验只存在于 Agent 的 session 上下文中,session 结束就消失了。MEMORY.md 是手动维护的,不够系统化。 +> +> **优秀实践**: +> - **Claude Code Memory**:四类记忆法,但只记录不蒸馏 +> - **Hermes**:闭环学习(记忆→Skill→搜索→改进),最完整 +> - **nuwa-skill**:五阶段蒸馏管线,蒸馏的是思维方式不是行为模仿 +> - **GSD**:plan template 可复用,Spec-driven 经验 + +**结论**:需要 DISCOVER → DISTILL → VERIFY → APPLY → IMPROVE 五阶段闭环,但必须实用——不搞复杂的 AI 蒸馏管线,从最简单的开始。 + +## 3. 设计决策 + +### D6-1:经验的三种载体 + +> **参考实践**: +> - **Claude Code**:MEMORY.md(Markdown,按 user/feedback/project/reference 分类) +> - **Hermes**:SKILL.md(步骤化菜谱)+ FTS5 索引 +> - **nuwa-skill**:SKILL.md(心智操作系统:心智模型 + 决策启发式 + 反模式 + 诚实边界) +> - **共享意识研究**:Memory → Skills → Rules 三层压缩 + +经验不是一种东西,有三种形态,载体不同: + +| 载体 | 内容 | 格式 | 生命周期 | 例子 | +|------|------|------|---------|------| +| **Rule(规则)** | 确定性的操作规范 | guardrails.yaml / prompt_templates/ | 长期稳定 | "所有 output 必须通过 JSON Schema 校验" | +| **Skill(技能)** | 半确定性的操作方法 | SKILL.md(Markdown) | 中期演进 | "如何正确下载分钟线数据" | +| **Memory(记忆)** | 非确定性的经验片段 | experiences 表 / MEMORY.md | 短期,可蒸馏为 Skill/Rule | "vnpy 的 load_bar 方法在 Python 3.12 有兼容问题" | + +**进化方向**:Memory → Skill → Rule。频繁出现的 Memory 被蒸馏为 Skill,高频引用的 Skill 可固化到 prompt_templates(Rule)。 + +``` +Memory(发现)→ Skill(方法)→ Rule(铁律) + ↓ 蒸馏 ↓ 固化 ↓ 强制 +非确定性 半确定性 确定性 +短命 中等 长命 +``` + +### D6-2:DISCOVER(信息发现) + +> **参考实践**: +> - **Hermes**:Agent-curated Memory + 任务执行过程自动记录 +> - **GSD**:verify phase 的产出作为经验来源 + +**信息源**(按价值排序): + +| 信息源 | 采集方式 | 价值 | 难度 | +|-------|---------|------|------| +| 错误与修正 | Guardrail 拦截 + Retry 记录 + 审查打回 | ⭐⭐⭐⭐⭐ | 低 | +| 黑板 decisions | 自动记录 Agent 决策过程和理由 | ⭐⭐⭐⭐ | 低(已有) | +| 审查记录 | reviews 表的 findings + verdict | ⭐⭐⭐⭐ | 低(已有) | +| Agent observations | 黑板 observations(风险、协作、异常) | ⭐⭐⭐ | 低(已有) | +| 节点 output | 任务完成后的产出文件 | ⭐⭐⭐ | 低(已有) | +| 反驳记录 | ACCEPT/REJECT/PARTIAL 的理由 | ⭐⭐⭐ | 中(Phase 2) | + +**采集机制**:不新增采集逻辑。所有信息源都已在课题1-4的设计中存在(黑板 decisions、reviews 表、observations、Guardrail 记录)。DISCOVER 阶段只是**读取已有数据**。 + +### D6-3:DISTILL(蒸馏)——两级蒸馏 + +> **参考实践**: +> - **nuwa-skill**:五阶段蒸馏(发现→采集→提取→验证→精炼),蒸馏的是思维方式 +> - **Hermes**:复杂任务完成 → 自动创建 SKILL.md +> - **GSD**:plan template 复用 + +不做 nuwa-skill 那样复杂的 AI 蒸馏管线。**两级蒸馏,从简单开始**: + +#### 一级蒸馏(实时,每个任务完成后自动) + +**触发**:任务状态变为 completed 或 failed 时。 + +**执行者**:庞统(在创建下一个任务前,花 ~30s 蒸馏上一个任务的经验)。 + +**过程**: +1. 读黑板上该任务的所有 decisions、observations、reviews +2. 提取 1-3 条关键经验("什么有效""什么无效""下次注意什么") +3. 写入黑板 experiences 表 + +**产出格式**: +```json +{ + "experience_id": "exp-001", + "source": "task_completion", + "task_id": "task-006", + "tags": ["vnpy", "strategy-coding", "error-handling"], + "summary": "vnpy 的 load_bar() 在 Python 3.12 下需要显式指定 end=None,否则只返回最后一根 bar", + "category": "pitfall", + "confidence": 0.9 +} +``` + +**Token 成本**:~500 token/任务(读黑板数据 + 生成摘要)。 + +#### 二级蒸馏(周期性,按需触发) + +**触发条件**(满足任一): +- 同类 experience 累积 ≥ 5 条(按 tag 聚合) +- 庞统发现重复问题出现 3 次 +- 用户要求"把最近的经验整理一下" + +**执行者**:庞统(Subagent 模式,独立 session)。 + +**过程**: +1. 聚合同 tag 的所有 experiences +2. 提取模式:"遇到 X 情况,应该 Y"(决策启发式) +3. 提取反模式:"遇到 X 情况,千万不要 Z"(避坑指南) +4. 标注适用范围(诚实边界) +5. 生成 SKILL.md 草稿 + +**产出**:SKILL.md 写入 `skills/` 目录(L3 被动参考层)。 + +**蒸馏格式**(简化版 nuwa-skill): +```markdown +# Skill: vnpy 分钟线数据加载 + +## 决策启发式 +- 加载分钟线数据时,优先用 load_bar(end=None) 显式指定全量 +- 数据文件超过 1GB 时,用 chunksize 分批读取 + +## 反模式 +- ❌ 不指定 end 参数 → 只返回最后一根 bar +- ❌ 全量读取大文件 → 内存溢出 + +## 诚实边界 +- 仅适用于 vnpy 的数据加载 API +- 不覆盖数据清洗逻辑 +``` + +### D6-4:VERIFY(验证) + +> **参考实践**: +> - **nuwa-skill**:3 个已知问题测试 + 1 个未知问题测试 + 双 Agent 精炼 +> - **Hermes**:幻觉门控——验证产出是否真实存在 + +**一级蒸馏(Memory)的验证**:轻量级。 +- 庞统自己 review(confidence 打分) +- 不需要独立验证环节 + +**二级蒸馏(Skill)的验证**:标准验证。 + +| 验证步骤 | 方法 | 通过标准 | +|---------|------|---------| +| 格式验证 | JSON Schema / Markdown 结构检查 | 结构完整 | +| 内容验证 | 庞统 review | 逻辑合理,无幻觉 | +| 实用性验证 | 标记为 "draft",下次任务引用后根据效果升级 | 被引用 ≥ 2 次且采纳率 > 50% | + +**Skill 生命周期**: +``` +draft → active → deprecated + ↑ │ + └── improved +``` + +- draft → active:被引用 ≥ 2 次且采纳率 > 50% +- active → deprecated:30 天无引用 或 采纳率 < 20% +- active → improved:发现更好的做法时更新 + +### D6-5:APPLY(应用)——经验的反哺机制 + +> **参考实践**: +> - **Claude Code Memory**:每次 session 启动自动加载 +> - **Hermes**:FTS5 跨 session 搜索 + LLM 摘要 + periodic nudge +> - **课题4 D4-6**:L2 引擎注入 + L3 被动参考 + +经验的反哺走课题4定义的四层架构: + +| 载体 | 反哺方式 | 层次 | 机制 | +|------|---------|------|------| +| **Rule** | 写入 guardrails.yaml / prompt_templates/ | L2 引擎注入 | Daemon 自动执行 | +| **Skill** | 写入 skills/ 目录 | L3 被动参考 | Agent 按需加载 | +| **Memory** | 写入 experiences 表 | L2 引擎注入(相关 Memory) | Daemon 按任务 tag 注入 | + +**Memory 的注入逻辑**(Daemon build_bootstrap 时): +```python +def get_relevant_experiences(task_tags, limit=3): + """按任务 tag 检索相关经验,注入 bootstrap 消息""" + experiences = query_experiences(tags=task_tags, status="active", limit=limit) + if experiences: + return format_as_context(experiences) # "注意:之前遇到过类似问题..." + return None +``` + +**注入位置**:在 L2 bootstrap 消息末尾,作为"历史经验提醒": +``` +═══ 历史经验提醒 ═══ +[exp-003] vnpy 分钟线加载:需要显式指定 end=None +[exp-007] 回测报告:确保包含收益曲线和最大回撤 +``` + +**Token 成本**:每条经验 ~50 token,最多 3 条 = ~150 token。 + +### D6-6:IMPROVE(进化) + +> **参考实践**: +> - **Hermes**:Skill 使用时自动改进 +> - **nuwa-skill**:Darwin.skill 八维评估 + 棘轮机制(只进不退) + +**进化机制**: + +| 机制 | 触发 | 执行者 | +|------|------|--------| +| **使用追踪** | Agent 在 Handoff 中标注"参考了 exp-003" | 执行者 | +| **效果对比** | 月度统计:采纳经验 vs 未采纳的任务成功率 | 庞统 | +| **淘汰** | 30 天无引用 → 标记 deprecated | Daemon 定期清理 | +| **更新** | 发现经验过时 → 庞统更新内容 | 庞统 | + +**棘轮原则**:经验只能改进不能退化。如果更新后效果更差,回退到上一个版本。 + +### D6-7:experiences 表设计 + +```sql +CREATE TABLE experiences ( + experience_id TEXT PRIMARY KEY, + source TEXT NOT NULL, -- task_completion / error_correction / review_finding / manual + task_id TEXT, -- 来源任务(FK → tasks) + tags TEXT NOT NULL, -- JSON array: ["vnpy", "strategy-coding"] + summary TEXT NOT NULL, -- 经验摘要(200字以内) + category TEXT NOT NULL, -- pitfall / best_practice / pattern / anti_pattern + confidence REAL DEFAULT 0.8, -- 0-1 + status TEXT DEFAULT 'active', -- draft / active / deprecated + skill_id TEXT, -- 关联的 Skill(二级蒸馏后填入) + usage_count INTEGER DEFAULT 0, -- 被引用次数 + last_used_at TEXT, -- 最后引用时间 + created_at TEXT NOT NULL, + created_by TEXT NOT NULL, -- 庞统 / 用户 + updated_at TEXT, + deprecated_reason TEXT +); +``` + +**索引**: +- `idx_exp_tags`:tags(JSON)— 按标签检索 +- `idx_exp_status`:status — 按状态过滤 +- `idx_exp_category`:category — 按类型过滤 + +### D6-8:和课题4四层架构的关系 + +``` +L0 铁律 ──── 最稳定的 Rule(IR-1~IR-5) + ↑ 极少固化(需要用户确认) + +L2 引擎注入 ─ prompt_templates/ + 相关 Memory + ↑ 庞统手动更新模板 + ↑ Daemon 自动注入相关 experience + +L3 被动参考 ─ skills/ 目录(二级蒸馏产出) + ↑ Agent 按需加载 + +黑板 experiences 表 ─ 原始 Memory + ↑ 一级蒸馏写入 + ↑ Daemon 按任务 tag 检索注入 +``` + +**进化路径**: +``` +experiences 表(Memory) + ↓ 累积 ≥ 5 条同类 +skills/ 目录(Skill) + ↓ 引用 ≥ 2 次且采纳 > 50% +prompt_templates/(Rule/L2 注入) + ↓ 用户确认 +guardrails.yaml / IR 铁律(L0) +``` + +### D6-9:实施优先级 + +| 优先级 | 内容 | Phase | 理由 | +|--------|------|-------|------| +| P0 | experiences 表创建 | Phase 1 | 基础设施 | +| P0 | 一级蒸馏(庞统任务完成后自动提取) | Phase 1 | 最小闭环 | +| P1 | Memory 注入 build_bootstrap() | Phase 2 | 经验反哺 | +| P1 | 使用追踪(Handoff 标注引用) | Phase 2 | 效果度量 | +| P2 | 二级蒸馏(Skill 生成) | Phase 3 | 需要足够多的 Memory 积累 | +| P2 | Skill 生命周期管理 | Phase 3 | draft/active/deprecated | +| P3 | 效果对比 + 棘轮机制 | Phase 4 | 需要长期数据 | + +**最小闭环(Phase 1)**:experiences 表 + 一级蒸馏 + Dashboard 可查看 = 从 0 到 1。 + +--- + +## 4. 和现有设计的对齐检查 + +| 已有设计 | 课题6 补充 | 一致性 | +|---------|-----------|--------| +| §3.2 SQLite Schema | D6-7 experiences 表加入黑板的 6 张表 | ✅ 同一数据库 | +| §4.4 Agent Spawn 上下文 | D6-5 Memory 注入 build_bootstrap() | ✅ 在 L2 末尾追加 | +| §4.7 Guardrail 体系 | D6-1 Rule 载体 = guardrails.yaml | ✅ 经验固化的终点 | +| §5.1 Agent 工作流程 | D6-2 信息源 = 黑板已有数据 | ✅ 不新增采集逻辑 | +| §9.4 Review Protocol | D6-2 审查记录作为经验源 | ✅ reviews 表数据 | +| 课题4 D4-6 四层架构 | D6-8 经验载体与四层架构对齐 | ✅ Memory→Skill→Rule 路径清晰 | +| 课题4 D4-10 目录结构 | skills/ 目录承载二级蒸馏产出 | ✅ L3 被动参考层 | +| MEMORY.md | D6-1 Memory 载体包含但超越 MEMORY.md | ✅ 系统化的 experiences 表替代手动维护 | + +## 5. 遗留 TODO + +| # | 待解决事项 | 归属 | 说明 | +|---|----------|------|------| +| T6-1 | experiences 表 tags 索引实现(JSON 查询优化) | Phase 1 | SQLite JSON 函数或 FTS5 | +| T6-2 | 一级蒸馏 prompt 模板(庞统任务完成后如何提取经验) | Phase 1 | 写入 prompt_templates/planner.md | +| T6-3 | build_bootstrap() 经验注入逻辑 | Phase 2 | 按 tag 检索 + 格式化 | +| T6-4 | 二级蒸馏触发条件实现 | Phase 3 | tag 聚合计数器 | +| T6-5 | Skill draft → active 的自动化验证 | Phase 3 | 引用计数 + 采纳率统计 | +| T6-6 | 经验淘汰定时任务 | Phase 3 | 30 天无引用 → deprecated | +| T6-7 | 效果对比报表(Dashboard 展示) | Phase 4 | 采纳 vs 未采纳成功率 |