---
id: blueprint-flywheel
name: 飞轮数据层
status: done
progress: 100
---

## 概述
外环数据采集与聚合层。在各项目的 .blueprint/usage.json 中记录飞轮运转快照（任务完成率、阻塞密度、conventions 版本），炼境跨项目聚合后计算健康指标，并格式化为梦核分析提示词的输入数据。

代码只处理确定性的机械工作（采集、计算、格式化），判断交给 Claude（梦核）。

## 任务卡

### ✅ usage.json 埋点写入
- status: done
- complexity: M
- files: src-tauri/src/commands/blueprint.rs
- acceptance: get_blueprint command 执行后，向项目 .blueprint/usage.json 追加一条 snapshot；schema：{ project_name, at, conventions_version, iteration, modules: {total,done,in_progress,planned,concept,blocked,stalled:string[]}, tasks: {total,done,in_progress,blocked,todo,dispatched}, blocked_reasons: string[] }；iteration 从 manifest.yaml 顶层 iteration 字段读取，失败写 1；节流：同一 UTC 日期同一项目只追加一条；conventions_version 从 .blueprint/CONVENTIONS.md frontmatter 读取，失败写 "unknown"；usage.json 不存在时自动创建为 { "project_name": "...", "snapshots": [] }

### ✅ get_flywheel_stats command
- status: done
- complexity: M
- files: src-tauri/src/commands/blueprint.rs, src-tauri/src/lib.rs, src/lib/commands.ts
- depends: blueprint-reader
- acceptance: 接收项目路径数组（由前端从 store 传入，与 sync_blueprint_rules 同模式）；读取每个项目的 .blueprint/usage.json；按 conventions_version 分组，对每组计算 4 项指标：可派发率（dispatched/total tasks）、任务完成率（done/total tasks）、飞轮持续率（30天内有快照的项目比例）、阻塞密度（blocked/total tasks）；跨项目聚合 blocked_reasons TOP10；检测停转项目（60天无快照）和 AI文档休眠项目（90天无快照），均携带 last_active 日期；返回结构化 FlywheelStats

### ✅ get_flywheel_stats 支持迭代感知
- status: done
- complexity: M
- files: src-tauri/src/commands/blueprint.rs, src/lib/commands.ts
- acceptance: usage.json snapshot 写入 iteration（读 manifest.yaml 顶层字段，失败写 1）；BlueprintManifest struct 新增 iteration 字段；get_flywheel_stats 扫描每个项目所有快照，检测 iteration 跳变，返回 iteration_jumps: Vec<IterationJump>；同时收集最新快照中 modules.stalled 列表，返回 stalled_modules: Vec<String>（格式 "project/module_id"）；梦核 prompt 补充「迭代跳变项目」和「停滞模块」两段摘要；commands.ts 新增 IterationJump 接口，FlywheelStats 补两字段

### ✅ 梦核提示词生成 command
- status: done
- complexity: M
- files: src-tauri/src/commands/blueprint.rs, src-tauri/src/lib.rs, src/lib/commands.ts
- depends: blueprint-reader
- acceptance: generate_muhe_prompt command，接收 FlywheelStats（由前端先调 get_flywheel_stats 获取后传入）+ 读取 master CONVENTIONS.md 内容，生成完整梦核分析提示词字符串；提示词包含：聚合数据摘要、TOP blocked_reasons、CONVENTIONS 全文、固化/遗忘双任务指令；注意：本任务须在 get_flywheel_stats 实现后执行

### ✅ 飞轮健康面板
- status: done
- complexity: M
- files: src/components/dashboard/BlueprintModal.tsx, src/lib/commands.ts
- depends: blueprint-view
- acceptance: 蓝图弹窗新增「飞轮」侧边面板；展示：各 conventions 版本队列的指标对比表（可派发率 / 任务完成率 / 飞轮持续率 / 阻塞密度）、跨项目 blocked_reasons TOP10、飞轮停转项目（60–90天，仅展示未进入休眠列表的）、AI文档休眠项目（90天+，含归档按钮+二次确认弹窗）、迭代跳变项目（iteration 递增，展示完成率跳变，⚠️标注大幅下降）、停滞模块（in_progress 但无可推进任务，格式 project/module_id）；「生成梦核提示词」按钮调用 generate_muhe_prompt，展示结果供复制

## 决策记录

- 代码只做机械工作（采集、聚合、格式化），梦核判断完全交给 Claude，不写打分公式
- usage.json 存各项目本地，不上传服务器，符合炼境 document-driven 设计哲学
- 节流策略：同一天一条，避免频繁打开蓝图导致数据膨胀
- conventions_version 打标是版本对比的关键，是外环版本评估的基础
- 4项指标中「可派发率」衡量任务卡规划质量，「飞轮持续率」衡量外环是否在转，两者是最先导指标；任务完成率衡量整体执行进度，阻塞密度是系统性风险信号
- iteration 字段用于区分历史 done 和当前迭代 done，避免多次重构后完成率虚高；迭代跳变是正常信号（主动重构），梦核据此判断而非告警