---
id: blueprint-buff
---

## 概述

炼境向被管理项目施加"蓝图 Buff"的能力层。Buff 注入后，git 提交自动触发任务状态同步（📋→🔵），炼境实时刷新蓝图视图。核心链路只依赖 git，与 AI 工具热插拔解耦，可批量复用到任意被管理项目。

## 决策记录

- 用 tokio 每5秒轮询 HEAD commit 而非写 git hook，原因：Windows 上 shell hook 执行依赖 Git Bash，路径复杂；轮询方式对项目零侵入且跨平台
- git commit 只自动标 🔵（进行中），不自动标 ✅（完成）；完成的语义需要验收，这是自动化的边界
- Buff 同步后顺手调用 `get_blueprint()`，内部触发 `append_usage_snapshot()`，使飞轮数据与实际开发进度对齐
- 使用文件路径匹配而非 commit message 解析，与 AI 工具/提交信息风格完全解耦
- **files 重叠只作兜底（2026-10-02，B1）**：本批提交已有卡被显式推进（新增 🔵/✅/🔴 标题行）则不推断，整批无推进才视为「agent 忘了加锁」。原因：两阶段锁下在做的卡落地时已非 📋，files 重叠只能碰到未开工卡，精度结构性偏低。曾评估「提交说明引用卡 ID」——正文自由文本 4 次命中 3 次误判（「阶段二 N3/N4/N5 待启动」），结构化 trailer 又与上条解耦决策冲突且兜不住忘加锁场景，故不采用；「可能相关」改记 DB 信号不改卡片（方案 C）留作残余噪声持续时的升级路径
- **剩余缺口与冻结（2026-10-04，MVP 收口 M2）**：manifest 曾记 86%，剩余 14% 起初判为未更新的进度数字；同日 B2 终验被否决（见 B2 卡），证明剩余是真实缺口——兜底推断的误标须按上条升级路径做方案 C（files 重叠改记 DB「可能相关」信号、不改卡片，L 级）。用户定：误标属噪声、不阻挡 MVP 四条能力，方案 C 冻结为扩展，模块保持 in_progress。

## 任务卡

### ✅ blueprint_buffs 数据表
- status: done
- complexity: S
- files: src-tauri/src/db.rs
- acceptance: blueprint_buffs 表 migration 执行成功，字段包含 project_path/project_id/applied_at/last_sync_at/last_commit/status

### ✅ Buff 生命周期 Rust 命令
- status: done
- complexity: M
- files: src-tauri/src/commands/buff.rs, src-tauri/src/commands/mod.rs, src-tauri/src/lib.rs
- depends: blueprint-buff
- acceptance: apply_blueprint_buff/remove_blueprint_buff/get_buff_status/list_buffed_projects 四个命令可正常调用，apply 时同步调用 sync_blueprint_rules 注入规则

### ✅ git watcher + 任务匹配写回 + 飞轮快照
- status: done
- complexity: M
- files: src-tauri/src/commands/buff.rs, src-tauri/Cargo.toml
- depends: blueprint-buff
- acceptance: git commit 后5秒内，files 字段命中的任务卡自动标记为 🔵 in_progress，调用 get_blueprint 追加飞轮快照，emit blueprint://changed 事件

### ✅ 前端 Buff 管理 UI
- status: done
- complexity: M
- files: src/lib/commands.ts, src/components/dashboard/BlueprintModal.tsx, src/components/dashboard/ProjectCard.tsx
- depends: blueprint-buff
- acceptance: ProjectCard 已施加 Buff 时显示紫色⚡徽章，BlueprintModal GovernancePanel 有施加/撤销按钮，施加后展示 init prompt 供复制

### ✅ 前端实时刷新
- status: done
- complexity: S
- files: src/components/dashboard/BlueprintModal.tsx
- depends: blueprint-buff
- acceptance: git commit 后已打开的蓝图视图自动重新加载，变更的任务卡显示"刚刚更新"标记并在3秒后淡出

### ✅ BlueprintView 跨项目切换
- status: done
- complexity: M
- files: src/components/dashboard/BlueprintModal.tsx, src/components/dashboard/ProjectCard.tsx
- depends: blueprint-buff
- acceptance: 任意项目 ProjectCard 可打开该项目自己的蓝图视图，传入 projectId 支持 Buff 管理，炼境自身蓝图入口不受影响

### ✅ B1 — files 重叠推断降为兜底（同批已有显式推进则不推断）
- status: done
- human_verify: "2026-10-02 终验通过：PR #27 合并后主仓库快进到 9da19ce，运行中的炼境（tauri dev）自动重编译生效；buff 处理该批提交（含改动 mcp_server.rs 的 4a37438，旧算法会把 P7/A4 标 🔵），blueprint_buffs.last_commit=9da19ce，主仓库 .blueprint/modules 无任何卡片状态变化。enterprise 侧本次未拉取 main（工作区有他人在制品），未覆盖子项目。"
- complexity: M
- files: src-tauri/src/commands/buff.rs, src-tauri/src/commands/blueprint.rs
- acceptance: "agent_verify: [cargo test] ①批内蓝图 diff 含 +### 🔵/✅ → 不标且内容不变；②无显式推进 + 精确路径命中 → 标 🔵；③仅反向后缀不命中；④lib.rs 不命中 mylib.rs；⑤尾逗号空项不命中；⑥「、」分隔可拆；⑦last_commit 非 HEAD 祖先 → 跳过。[回放脚本] master 历史 50 → ≤5，53af8c3/239d9fd/79853b7 对 P6/P7/P8/A4 零命中。human_verify: 重装炼境后合并下一个 PR，主仓库工作区不再出现无关卡被标 🔵"
- 起因：2026-10-02 合并 PR #24/#25/#26 后 P6/P7/P8（agent-client-parity）与 A4（architecture-evolution）未开工却被标 🔵，仅因与 P1/P3/P9 共用 files；enterprise-system 2026-07-22 回传同类问题（第二例，governance-feedback-loop 挂触发条件满足）
- 回放（master 240 个 first-parent 提交）：现有算法命中 50 次——明确误判 30、存疑 17、明确正确 3；热点为 mcp_tools.rs/onboarding.rs/commands.ts 等共享文件
- 根因：两阶段锁下真正在做的卡提交落地时已是 🔵/✅，files 重叠只能碰到仍为 📋 的卡——选择偏差使精度结构性偏低，非调匹配规则可解
- 实现（2026-10-02，分支 feat/blueprint-buff）：infer_task_marks 收口三道闸——last_commit 非 head 祖先跳过（git 出错记日志）、本批 .blueprint/modules patch 新增 🔵/✅/🔴 标题行（非原样搬移）跳过、余下才走 files 匹配；同一批次全程用轮询读到的 HEAD sha。匹配：parse_task_files（, 、 ， 分隔，丢空项）+ file_matches（精确或 / 边界后缀，去反向后缀）。蓝图同步提示词改为「核实仅共用文件的 🔵 可降回 📋 并写明原因」。边界分析补 🔴、head 口径、git 异常日志三处。
- verification: "2026-10-02：cargo test 256 passed / 0 failed；buff 9 条新测试（精确命中、非 📋 不动、反向后缀不命中、/ 边界、尾逗号空项、「、」分隔与 A4 实例、🔵/✅/🔴 推进判定、搬移不算推进、临时 git 仓库端到端：同批显式推进不推断 / 无推进兜底标 🔵 / checkout 非祖先跳过 / 首次接入兜底）。回放 master 240 个 first-parent 提交：命中 50 → 5，79 个批次因显式推进整批抑制，53af8c3/239d9fd/79853b7 对 P6/P7/P8/A4 零命中。"
- known_limits: "仍是启发式：不更新蓝图的 PR（如 Codex PR）碰共享文件仍可能误标；一次 pull 多个合并时，一个 PR 的显式推进会屏蔽另一个 PR 的兜底；只看已提交的蓝图改动，主仓库里只提交代码、🔵 锁留在工作区时仍会推断；files 项带反引号（4/311）或括号注释（21/311）永不命中（原有行为，未改）；WSL 路径项目上新增 git 辅助不分支，失败即不推断。"

### ✅ B2 — 跟进维护既有蓝图内容也算归属已显式
- status: done
- complexity: S
- files: src-tauri/src/commands/buff.rs
- acceptance: "agent_verify: [cargo test buff] ⑧ 批内只改写已推进卡的既有行（无标题变化）+ 共用文件改动 → 0 张被标；⑨ 批内纯追加新 📋 卡 + 共用文件改动 → 兜底仍标 🔵（P8 与新卡）；edits_existing_lines：hunk 内 `-` 行算、文件头 `---`/`--- /dev/null` 不算。[变异] 去掉 B2 条件后 ⑧ 失败（left 1, right 0）。human_verify: 主仓库快进到含本卡的提交后，下一次只补记已完成卡的 PR 合并，工作区无卡片被标 🔵"
- 起因：2026-10-03 05:49 主仓库快进到 19b9388（PR #31：只补记 ✅ P7 的 known_limits，无标题变化），35 秒后 P6/P8（onboarding.rs）与 A4（mcp_server.rs）再次被误标 🔵——B1 把「跟进已完成卡」判为无推进。B1 known_limits 预言的残余噪声第一次出现。
- 实现：infer_task_marks 增加第二个显式归属条件 edits_existing_lines——本批 .blueprint/modules patch 在 hunk 内有 `-` 行（删改既有内容）即视为 agent 在跟进维护，不推断；纯追加（新立 📋 卡、新模块）仍走兜底，保留「立卡即实现、忘了加锁」的捕获。
- verification: "2026-10-03：cargo test 284 passed / 0 failed / 5 ignored；buff 10 passed（新增 edits_existing_lines 单测与端到端 ⑧⑨）；变异验证见 acceptance。回放 master 260 个 first-parent 批次：B1 下无推进 172 批，B2 新增抑制 27 批，其中含代码改动的 6 批：19b9388（本次误标）、8f3be6b、0d4c2ad、cbc1d46、23de433、0552180，其余为只改蓝图的 docs/chore 提交（本就不会命中代码卡）；纯追加立卡的 9881b56、9c2064e、4f5cf43 保持兜底。"
- known_limits: "同批若只改写了无关 📋 卡的文字同时改代码且忘了加锁，B2 会少标（漏信号，不误标）。下次再出现误标时按 B1 决策记录升级到方案 C（files 重叠改记 DB「可能相关」信号，不改卡片，L 级）。"
- human_verify: "2026-10-04 否决：主仓库 12:45 快进到 ef09ef2（只改 docs/tasks/2026-10-03-coordination.md，无蓝图改动）后约 1 分钟，buff 把 intent-catalog 未开工的 📋 IC10（files 含该文件）标为 🔵——无显式推进、files 共用即兜底命中，属 B1 known_limits「不更新蓝图的提交碰共享文件仍可能误标」。B1/B2 两道闸已生效但不足以消除此类误标。"
- 终验: 2026-10-04 否决：只改共用文档、不动蓝图的提交仍会把无关 📋 卡误标 🔵（实例 IC10）