dev-manager-tauri/.blueprint/modules/flywheel-intelligence.md

飞轮智能成长

炼境通过管理项目产生的多维数据反哺自身，形成可自我进化的成长闭环。 核心愿景：让炼境像一把可成长神器，执行数据越积越多，自身越来越好用。

背景

现有飞轮仅覆盖一个维度：usage.json 指标 → 梦核分析 → CONVENTIONS 建议。 复盘笔记、任务时长、返工率等执行质量数据已在采集，但没有进入任何反哺路径——数据在"睡觉"。

本模块分三个阶段逐步打通数据→改善的完整闭环。

方向修订（2026-06-19）

阶段一/二依赖「AI 主动写结构化复盘笔记」作为执行质量数据源。实测发现该进料口几乎枯竭：70 条笔记仅炼境自身 4 条结构化，外部项目存量为旧格式，rework_count/avg_rounds_M 长期为 0/null。

根本转向：执行质量数据从「AI 主动上报」改为「炼境从 git 被动自吸」——解析 conventional commit 的 type（fix=返工）/scope（=模块）自动计算，客户端无关、工作流无关。新增 L0 解析层（见任务卡）作为阶段三预测层的数据地基。详见 memory project_gitea_unified_architecture 及 onboarding-pack / gitea-integration 模块。

阶段触发条件

• 阶段二启动条件：阶段一上线后，梦核输出中稳定出现"高频陷阱摘要"板块，且跨项目复盘笔记数量 ≥ 20 条
• 阶段三启动条件（已修订）：L0 解析层上线后，conventional commit 执行质量数据稳定覆盖 ≥ 10 个项目（不再依赖复盘笔记积累时长，见上「方向修订」）

---

任务卡

✅ 阶段一：复盘笔记接入梦核飞轮

• status: done
• complexity: M
• files: src-tauri/src/commands/blueprint_feedback.rs, src/components/blueprint/FlywheelPanel.tsx
• acceptance: 梦核 prompt 构建时聚合所有项目的 project_notes；Opus 输出新增"高频陷阱摘要"板块，列出跨项目重复出现的踩坑模式；本地验证：有复盘笔记的项目数据能正确注入 prompt

阶段一详细设计：

• 梦核 prompt 模板增加输入段：通过 MCP 读取各项目 project_notes，按"任务类型 × 是否返工"分组
• Opus 输出格式新增板块：

  ### 高频陷阱（跨项目复盘笔记聚合）
  - <任务类型>：<踩坑描述>，出现 N 次（项目：A、B、C）
  

• 修改点：梦核 prompt 构建逻辑（Rust 侧）

---

✅ 独立项目自动创建产品组

• status: done
• complexity: S
• files: src-tauri/src/commands/groups.rs, src-tauri/src/commands/buff.rs
• acceptance: 对未加入任何产品组的蓝图项目，apply_blueprint_buff 时自动创建 "{name} (独立项目)" 产品组并注入 MCP，使 append_project_note 在该项目的 Claude 会话中可用

---

✅ 复盘笔记覆盖率可见性

• status: done
• complexity: M
• files: src-tauri/src/commands/mentor.rs, src/lib/commands.ts, src/components/mentor/MentorPanel.tsx
• acceptance: 项目导师面板显示"已完成 M/L 任务数 / 复盘笔记数 / 缺口"三格统计；缺口 > 0 时显示琥珀色警告提示；mentor_markdown 同步写入覆盖率表格和补写提醒，让 Claude 每次打开报告时自动感知

---

✅ 补测试：飞轮存量函数安全网

• status: done
• complexity: M
• depends: flywheel-intelligence（阶段二启动前完成，保障数据关键路径）
• files: src-tauri/src/commands/blueprint.rs
• acceptance: collect_flywheel_notes 有测试覆盖 win_path 匹配、wsl_path 匹配、项目不存在三种情况；get_flywheel_stats 有测试覆盖正常快照解析、空项目列表、iteration 跳变检测；所有新测试用依赖注入 + in-memory DB；cargo test 全绿

背景：阶段一实现时因无测试导致"查错表"bug 上线，靠人工 review 才发现。补测试后同类静默失败 bug 可在写代码时立即暴露。

---

✅ MCP Server 支持 SSE 传输

• status: done
• complexity: M
• files: src-tauri/src/mcp_server.rs
• acceptance: GET /mcp/group/:group_id 返回 text/event-stream，按 MCP SSE 传输规范完成握手；Claude Code 会话启动时 append_project_note 等工具可在工具列表中原生出现；Windows 本地测试通过（curl -N GET 端点可见 SSE 事件流）

背景：Claude Code MCP 客户端用 GET 发起 SSE 握手，炼境目前只接受 POST，导致 405 → MCP 永久失效。加 GET/SSE 端点后，所有项目原生 MCP 打通，复盘笔记可直接通过 append_project_note 写入，飞轮数据链完整，无需任何绕路脚本。

---

✅ 阶段二：usage.json 扩展采集维度

• status: done
• complexity: M
• depends: flywheel-intelligence（阶段一完成后启动）
• files: src-tauri/src/commands/blueprint.rs
• acceptance: usage.json 快照新增 complexity_dist、rework_count、avg_rounds_M 字段；字段值从复盘笔记解析填充；梦核分析可输出"M 级任务实际轮数 vs 预估"对比

阶段二详细设计：

"tasks": {
  ...现有字段...,
  "complexity_dist": { "S": 12, "M": 8, "L": 0 },
  "rework_count": 3,
  "avg_rounds_M": 2.4
}

• rework_count 和 avg_rounds 从项目 project_notes 中解析"实际轮数"字段聚合

---

✅ L0：Conventional Commit 执行质量解析层（数据地基，先于阶段三）

• status: done（2026-06-19，实现见 onboarding-pack 卡 C1+C2）
• complexity: L
• depends: onboarding-pack（项目须先种 lefthook + conventional 规范）
• files: src-tauri/src/commands/commit_metrics.rs, src-tauri/src/commands/buff.rs, src-tauri/src/commands/blueprint.rs, src-tauri/src/db.rs
• acceptance: 炼境后端从本地 git 解析 conventional commit —— type=fix 计返工、scope 映射模块、commit 数≈轮数；自动填充 usage.json 的 rework_count/avg_rounds_M/complexity_dist，取代「从复盘笔记解析」的枯竭路径；CI 自修 commit（如 [DeepSeek-V3]）须从返工率剔除；squash merge 项目须降级处理

背景：实测复盘笔记进料口枯竭（70 条仅 4 条结构化）。改由 git 自吸，客户端无关、工作流无关，是阶段三预测层的真实数据基础。

---

✅ F1. Git 健康度后端——全量历史导入 + 跨项目聚合

• status: done
• complexity: M
• files: src-tauri/src/commands/commit_metrics.rs, src-tauri/src/lib.rs, src/lib/commands.ts
• acceptance: 新增 ingest_full_git_history(project_id, project_path) 命令（最多 500 条，INSERT OR IGNORE 幂等）；新增 get_project_commit_health(project_ids) 命令返回各项目 conventional_rate/rework_rate/top_scopes；单元测试覆盖 ingest 幂等性和 health 聚合

✅ F2. 飞轮面板——Git 健康度区块 + 全量导入按钮

• status: done
• complexity: M
• depends: F1
• files: src/lib/commands.ts, src/components/dashboard/BlueprintModal.tsx
• acceptance: FlywheelPanel 底部新增"Git 执行质量"卡片，表格展示各项目 commit 规范化率/返工率/TOP scope；"全量导入"按钮对所有已接入项目触发 ingest_full_git_history，显示 loading 和结果摘要；无类型错误

---

📋 R1. Rules-Applied commit trailer 被动自吸（规则有效性数据源）

• status: todo
• complexity: M
• depends: flywheel-intelligence（L0 已完成即可，不依赖阶段三）
• files: .claude/skills/commit（或 smart-commit 模板）, src-tauri/src/commands/commit_metrics.rs, src-tauri/src/db.rs, src-tauri/src/commands/blueprint.rs
• acceptance: ① /commit 技能在本次任务触发过规则时，commit message 末尾自动附 Rules-Applied: R01,R06 trailer；② commit_metrics 解析层提取该 trailer 存入新列（补 migration，R05）；③ get_flywheel_stats 聚合"规则命中 × 该 commit 是否 fix 返工"交叉统计注入梦核 prompt；④ 新增解析函数有单元测试（依赖注入 + in-memory DB），cargo test 全绿

背景：复盘笔记进料口枯竭（70 条仅 4 条结构化），rule_effectiveness 闭环是死链，R01-R10 的 confidence 全是人工拍的。本卡把规则有效性数据改为 git 被动自吸——与 L0 同构，是 CONVENTIONS 置信度自动进化（阶段三）的真实数据前提。

✅ R2. CONVENTIONS 规则边界字段 + R11 失败记录规则

• status: done
• complexity: S
• files: .blueprint/CONVENTIONS.md（即内嵌 master 源，blueprint.rs include_str! 引用）
• acceptance: 规则格式新增可选字段 boundaries（已知不适用条件）与 failure_cases（日期+条件+现象）；新增 R11——confidence ≥ 0.80 的规则自动执行后仍未阻止问题时，必须在该规则下追加 failure_case；版本号递增，治理面板分发

背景："失败定边界、经验细化为变体"是经验飞轮的因果自洽核心，当前规则库只有正向 scope，无反例结构。 完成记录（2026-07-02）：CONVENTIONS 升 v1.9.0，新增 boundaries/failure_cases 字段说明 + R11 + abandoned 模块状态定义；向其他项目的分发随下次发版生效（CONVENTIONS 编译进二进制）。

阶段三：执行质量预测层

• status: todo
• complexity: L
• depends: flywheel-intelligence（阶段二完成且数据积累达标后启动）
• files: TBD（需 /architect 后确定）
• acceptance: TBD

阶段三方向（待 /architect 设计）：

• 任务完成时长分布（为 S/M/L 定义时间基准）
• 高风险任务预警（特定文件组合 → 历史高返工率）
• 跨项目模式库推荐
• 自动推荐规则置信度更新：梦核读取复盘笔记中的 auto_applied_rules + rule_effectiveness 字段，输出 CONVENTIONS 规则库的 confidence/evidence_count 更新建议；新增规则提案（从高频踩坑模式自动归纳）

⚠️ 阶段三为 L 级复杂度，到时须先走 /architect → /splitter 流程，禁止直接写代码。

决策记录

• 三阶段串行而非并行：数据积累需要时间，阶段二依赖阶段一跑出足够复盘笔记，阶段三依赖阶段二的字段扩展；提前建设无数据支撑的预测层是无效投入
• 蓝图管理而非单独文档：三阶段是对炼境自身的迭代开发，bluepint 的 depends 字段天然表达阶段间的触发关系，可视化面板也能直接展示当前在哪个阶段
• 不存 CONVENTIONS 全文历史到 DB：Git 已有版本记录，效果对比通过 usage.json 的 conventions_version 分组已足够