a5cb30734d
- risk.rs 新增 Tauri command get_high_risk_scopes（薄包装）+ lib.rs 注册 - commands.ts 封装 HighRiskScope 类型与调用（R01） - FlywheelPanel 新增「返工热区」块：跨项目返工率降序， 分级配色与 classify_risk 阈值一致（≥35% 红 / ≥15% 琥珀） - 蓝图：P3-A~E 五卡全部 done，附 L 级复盘笔记，模块 progress 98 Rules-Applied: R01,R13
212 lines
17 KiB
Markdown
212 lines
17 KiB
Markdown
# 飞轮智能成长
|
||
|
||
炼境通过管理项目产生的多维数据反哺自身，形成可自我进化的成长闭环。
|
||
核心愿景：让炼境像一把可成长神器，执行数据越积越多，自身越来越好用。
|
||
|
||
## 背景
|
||
|
||
现有飞轮仅覆盖一个维度：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 预估"对比
|
||
|
||
阶段二详细设计：
|
||
```json
|
||
"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: done
|
||
- 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 置信度自动进化（阶段三）的真实数据前提。
|
||
> 完成记录（2026-07-02）：smart-commit 技能加 trailer 步骤；commit_metrics 新增 rules_applied 列（migration）+ parse_rules_applied + rule_hit_stats 聚合；梦核 prompt 新增「规则命中×返工交叉」数据段与【规则置信度】分析任务；5 个单元测试（测试抓到一个 ? 提前返回 bug）。数据将随日常 commit 自然积累。
|
||
|
||
### ✅ 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 编译进二进制）。
|
||
|
||
### 阶段三：执行质量预测层（已过 /architect + /splitter，2026-07-04）
|
||
|
||
> 触发条件已达标：commit_metrics 覆盖 17 项目 / 735 commit（459 conventional）。
|
||
> 设计裁决：规则置信度闭环 + 风险预警本期做；时长分布（无任务时间戳）与模式库推荐（笔记进料枯竭）缓做。
|
||
> 预测消费端 = MCP 工具 `predict_task_risk`（agent 开工前查询），梦核数据段为辅——预测给干活的 agent 用，不是给看板前的人看。
|
||
> **P0 侦察发现**：R1 trailer 管道是死链——git log 用 `%s` 只取 subject，Rules-Applied trailer 在 body 里永远读不到（炼境自身 11 条带 trailer 的 commit，DB rules_applied 全空）；单测喂全文所以全绿。P3-A 修复。
|
||
|
||
### ✅ P3-A. trailer 链路修复 + UPSERT 回填
|
||
- status: done
|
||
- done_note: 2026-07-04 完成。GIT_LOG_FMT 加 %(trailers:key=Rules-Applied,valueonly)（git 原生 trailer 解析，保持单行记录）；record_commit_entry + upsert_metrics（ON CONFLICT 仅回填 NULL，绝不覆盖）；buff.rs get_new_commits 委托 commit_metrics::read_git_log（消灭重复 FMT + 顺手清理该函数 WSL 分支）；ingest_full_git_history 改走 record_commit_entry（消灭第三处重复 INSERT）。测试：真 git 仓库 e2e trailer 提取回归 + UPSERT 四态语义，82 测试全绿。存量回填待新 build 重启后跑全量导入终验
|
||
- complexity: M
|
||
- files: src-tauri/src/commands/commit_metrics.rs, src-tauri/src/commands/buff.rs
|
||
- acceptance: "[cargo test] read_git_log 用 %(trailers:key=Rules-Applied,valueonly) 提取 trailer，record_commit 改 UPSERT（仅补 rules_applied IS NULL 的行，不覆盖已有值）单测覆盖；[Tauri command] 对炼境自身重跑 ingest_full_git_history → commit_metrics 中 rules_applied 非空行 ≥10，rule_hit_stats 返回非空"
|
||
- notes: buff.rs 与 commit_metrics.rs 两处重复的 FMT 常量统一为 commit_metrics::read_git_log 单一来源；git 原生 trailer 解析保持单行一条记录，避免 %B 多行解析
|
||
|
||
### ✅ P3-B. commit_files 采集（增量 + 全量）
|
||
- status: done
|
||
- done_note: 2026-07-04 完成。commit_files(sha,path 联合主键 + path 索引) migration 到位；read_git_log 加 --name-only，单次 git 调用同时取指标与文件（parse_git_log_output 纯函数解析 header/文件行混排）；record_commit_entry 落库文件（INSERT OR IGNORE 幂等），buff 增量与 ingest 全量两条链路自动覆盖。83 测试全绿（真仓库 e2e 含文件断言）
|
||
- complexity: M
|
||
- depends: flywheel-intelligence（卡 P3-A，共用 read_git_log 改造）
|
||
- files: src-tauri/src/commands/commit_metrics.rs, src-tauri/src/commands/buff.rs, src-tauri/src/db.rs
|
||
- acceptance: "[cargo test] 新表 commit_files(sha,path 联合主键) migration 到位（R05），git log --name-only 解析纯函数单测覆盖多 commit 多文件；[Tauri command] ingest_full_git_history 对炼境自身重跑 → commit_files 行数 >0 且重跑幂等（行数不变）"
|
||
|
||
### ✅ P3-C. risk.rs 风险画像 + predict_task_risk MCP 工具
|
||
- status: done
|
||
- done_note: 2026-07-04 完成。commands/risk.rs：scope 级（前缀匹配子 scope）+ 文件级（commit_files JOIN）返工率聚合，classify_risk 阈值 ≥0.35 high / ≥0.15 medium；样本 <5 或 conventional 率 <0.5（脏历史）→ confidence=low 并附 notes；CI 自修剔除。MCP 工具 schema+dispatch+清单断言。7 个单测（高返工 scope/小样本/脏历史/热点文件/CI 剔除/入参校验/阈值），90 全绿。MCP 实调待新 build 重启后终验
|
||
- complexity: M
|
||
- depends: flywheel-intelligence（卡 P3-B）
|
||
- files: src-tauri/src/commands/risk.rs, src-tauri/src/commands/mod.rs, src-tauri/src/mcp_tools.rs
|
||
- acceptance: "[MCP tool] predict_task_risk(project_id, scope 或 files) → JSON 含 risk_level/rework_rate/sample_size/confidence/hot_files，无 error 字段；sample_size<5 时 confidence=low；[cargo test] 风险聚合纯函数（conn 注入 + in-memory DB）覆盖高返工 scope、小样本、脏历史（conventional 率低标不可信）三种输入；tools_list_result 含 predict_task_risk 断言"
|
||
|
||
### ✅ P3-D. 梦核 prompt 高风险 scope 数据段
|
||
- status: done
|
||
- done_note: 2026-07-04 完成。risk.rs 新增 high_risk_scopes（样本 ≥5 且有非 CI 返工，返工率降序，项目名从 project_profiles 解析缺失回退 id）；generate_muhe_prompt 注入「跨项目高风险 scope」表格段（含分析指引：反复返工 scope=结构性脆弱点→固化环节输出预防性规范）；顺手把 rule_hits 段的 pool() 改 try_pool()（原实现测试环境必 panic，generate_muhe_prompt 因此不可测）；prompt 构建测试 + 聚合排序过滤测试，92 全绿
|
||
- complexity: S
|
||
- depends: flywheel-intelligence（卡 P3-C）
|
||
- files: src-tauri/src/commands/blueprint.rs
|
||
- acceptance: "[cargo test] 梦核 prompt 构建函数单测断言输出含「跨项目高风险 scope」数据段（返工率 top scope + 项目分布）；规则置信度段在 P3-A 数据流入后自然激活（注入点 blueprint.rs rule_hit_stats 已存在）"
|
||
|
||
### ✅ P3-E. FlywheelPanel 风险展示 + commands.ts 同步（可选收尾）
|
||
- status: done
|
||
- done_note: 2026-07-04 完成。实现形态微调：Git 执行质量表已有 TOP scope 列（F2 遗产），故新增独立「返工热区」块展示 get_high_risk_scopes（跨项目返工率降序，分级配色与 classify_risk 阈值一致 ≥35% 红 / ≥15% 琥珀）；Tauri command get_high_risk_scopes 薄包装 + lib.rs 注册 + commands.ts 封装（R01）。pnpm typecheck exit 0，cargo test 92 全绿
|
||
- complexity: S
|
||
- depends: flywheel-intelligence（卡 P3-C）
|
||
- files: src/lib/commands.ts, src/components/insight/FlywheelPanel.tsx, src-tauri/src/commands/risk.rs, src-tauri/src/lib.rs
|
||
- acceptance: "[pnpm typecheck] exit 0；FlywheelPanel 新增跨项目返工热区展示（get_high_risk_scopes 封装同步，R01）"
|
||
|
||
## 复盘笔记
|
||
|
||
【复盘】阶段三执行质量预测层 P3-A~E（2026-07-04）
|
||
任务类型: 后端数据管道 + MCP工具 + 前端展示
|
||
复杂度: L（architect+splitter 拆为 2M+1M+1S+1S，单会话连续执行）
|
||
实际轮数: 1轮（预估 1 轮）
|
||
是否返工: 否
|
||
有效策略: architect 阶段先查数据库实况而非只读设计文档——由此发现 R1 trailer 管道死链（%s 只取 subject，单测喂全文全绿而生产喂 subject 永空），这个 P0 若不修，阶段三核心闭环（规则置信度）建在死数据上；「单元绿、集成死」用真 git 仓库 e2e 测试驻军；UPSERT 只回填 NULL 不覆盖，让回填天然幂等；三处重复的 git log 取数统一为单一入口（read_git_log），--name-only 让指标与文件单次进程同取
|
||
顺手修的旧债: generate_muhe_prompt 用 pool() 导致测试环境必 panic（不可测），改 try_pool() 走占位文案
|
||
遗留: 存量数据回填与 predict_task_risk MCP 实调，待新 build 发布重启后终验（跑一次「全量导入」即回填 trailer + 文件）
|
||
auto_applied_rules: R01, R05, R06, R07, R13
|
||
rule_effectiveness: R06=有效（conn 注入使 risk.rs 7 测试全部 in-memory 可行）, R07=有效（e2e git 仓库回归测试抓住的正是集成层缺口）, R13=有效（acceptance 可执行格式让五张卡零歧义）, R01=有效（commands.ts 同步时确认 HighRiskScope 类型单一来源）, R05=有效（commit_files migration 随手写进 migrate()）
|
||
|
||
## 决策记录
|
||
|
||
- 三阶段串行而非并行：数据积累需要时间，阶段二依赖阶段一跑出足够复盘笔记，阶段三依赖阶段二的字段扩展；提前建设无数据支撑的预测层是无效投入
|
||
- 蓝图管理而非单独文档：三阶段是对炼境自身的迭代开发，bluepint 的 depends 字段天然表达阶段间的触发关系，可视化面板也能直接展示当前在哪个阶段
|
||
- 不存 CONVENTIONS 全文历史到 DB：Git 已有版本记录，效果对比通过 usage.json 的 conventions_version 分组已足够
|