dev-manager-tauri/.blueprint/modules/onboarding-pack.md

# 接入包（Onboarding Pack）

炼境向被管理项目一键分发的标准化接入套件，让任意新旧项目成为「飞轮合格公民」。
统一以自建 Gitea 为 git 数据底座，缝合 git 规范、AI 约定、蓝图语义、炼境登记四层。

## 双层架构

- **自建 Gitea**：统一 git 数据底座（稳定、自主、CI + review 自控）
- **炼境**：底座之上的「项目飞轮控制台」——读 git 数据做跨项目飞轮聚合、分发接入包、维护蓝图语义层

> 决策（2026-06-19）：全面统一自建 Gitea，弃用 GitHub。数据主权 = 飞轮燃料自主可控，契合「管理越多→数据越多→飞轮越强」愿景。详见 memory [[project_gitea_unified_architecture]]。

## 蓝图重新定位（git 与蓝图分工）

> 完整定义见 `.blueprint/CONVENTIONS.md` §「蓝图定位（意图层）」。

核心分工：git 记录「做了什么」，蓝图只保留 git 给不了的三类信息（结构关系图 / 意图与验收标准 / 未来规划）。状态/进度/涉及文件从 git 信号推断，蓝图不手动双写。

## 接入包分档（底座统一，上层按需）

| 档 | 内容 | 适用 |
|----|------|------|
| **基线**（所有项目） | Gitea 建仓/迁移 + origin=Gitea + lefthook(强制 conventional) + AGENTS.md + git-workflow.md + 炼境登记 + buff 解析 commit | 全部新旧项目 |
| **增配**（复杂项目） | + Gitea Actions CI + DeepSeek review + 瘦蓝图 | 长周期/多业务线 |

## 决策记录

- **放弃 WSL 路径项目支持（2026-07-04 用户裁决）**：被管理项目只保留 Windows 路径（win_path），不再登记/支持 WSL UNC（\\wsl.localhost\...）路径项目。DB 中 2 条 WSL 残留登记已清（均为已有 win 路径登记的重复项，零飞轮数据损失）。**新代码不再写 WSL 路径分支**；存量 WSL 分支（18 文件 111 处）不主动拆除，触碰相关文件时顺手清理。边界：wsl-proxy / v2rayn-import 是独立代理功能，不在此决策范围
- 飞轮升格与 Gitea API 对接「分步实施」而非耦合：buff 读本地 `.git`（commit type/scope），与远程平台无关，可先做；Gitea API（CI 状态/PR review）随后
- 「完整分发」是陷阱，正确形态是分级菜单：新项目种全套，旧项目增量接入（复用 mcp_inject 的「命名空间隔离 + 合并不覆盖」语义，不动用户已有配置）
- 接入动作：现有 `apply_blueprint_buff` 升格为 `apply_onboarding_pack`，按档编排注入
- 语义层进料口隐患：决策/验收/踩坑仍需主动写（与饿死复盘笔记同源），须配「从 PR 标题/commit body/review 评论半自动提取」，不再单纯指望人自觉
- **分发文件三档升级语义（2026-07-15 择升环评估）**：① 版本化块文件（AGENTS/git-workflow）→ MANAGED 块原位升级；② 炼境全托管文件（envoy.md/blueprint-gate.cjs，用户不定制）→ 内容不一致即覆盖；③ 用户可定制文件（lefthook.yml）→ 绝不覆盖，但 verify_onboarding 须能检测落后。此前 ②③ 混用「存在即跳过」导致回流修正推不到存量项目
- **本地定制严禁写进 MANAGED 块内（2026-07-15 实调反噬实锤）**：炼境自身曾把「分支策略表 / Agent 按钮清单 / 降级约定 / 启动协议第 4 条」写在托管块内，v1.6.0/1.11.0 块升级时全部被原位覆盖抹掉（托管块的设计行为）。已恢复至块外「炼境自身约定」区。规则：托管块只放分发内容，项目定制一律块外；改块内容只能改炼境模板源头再分发
- **回流触发不自动化（2026-07-15 多角度辩证）**：否决子项目侧 hook 自动触发 /envoy——自动化触发拆掉人肉过滤层，诱导低价值回传污染通道，伤「择」换「环」转速。回流频率问题用炼境侧可观测性解（「沉默项目」诊断信号，见 B4 卡），人留在过滤环里。校验类需求优先放统计消费端（炼境 ingest）而非分发 hook（R12 边界单点 + 零分发成本 + 可回溯）

## 复用的现有能力（~60% 地基已具备）

| 能力 | 现状 |
|------|------|
| `.claude/settings.json` 注入 | ✅ `mcp_inject`（命名空间隔离 + 合并不覆盖 + JSON 校验） |
| 生成接入 prompt / 扫描项目 | ✅ `generate_blueprint_prompt`（已读 AGENTS.md + monorepo 感知） |
| git 轮询 → 状态同步 | 🟡 `buff`（仅匹配文件路径，需补 conventional 解析，见 flywheel-intelligence L0） |
| CONVENTIONS 规则同步 | ✅ `sync_blueprint_rules` |
| 项目模板 | ✅ `templates` |
| CI workflow 生成 | 🟡 `cicd.rs`（仅 GitHub，需改造 Gitea Actions，见 gitea-integration） |

## 风险

- 旧项目存量 git 数据脏（无 scope、非 conventional）→ 数据质量是光谱，需「采用规范后切起算」或标不可信
- 跨项目聚合可比性：不同项目 scope 粒度/复杂度标准不同，fix 率直接相加会误导梦核
- 模板自身维护成本：AGENTS.md/lefthook/git-workflow.md 模板要随最佳实践演进

## 设计（architect 2026-06-19）

基线档范围：模板分发 + 炼境登记 + L0 commit 解析，**全部本地、不依赖 Gitea API**（Gitea 建仓/Actions/webhook 属 gitea-integration 档2）。

关键决策：
- **新建 `apply_onboarding_pack`**（不扩展 buff）：buff=挂 git 观测，onboarding_pack=完整接入，分层清晰
- **模板"存在则跳过 + 报告"**：markdown/yaml 不强行整文件合并，绝不覆盖用户已有（复用 mcp_inject 的路径解析 + 不存在才写）
- **L0 commit 解析挂在现有 buff watcher**：`last_commit..HEAD` 取 message → parse_conventional → 写新表 `commit_metrics`；与文件路径匹配两条路径并行互不干扰
- **rework_count 来源**从枯竭的 `parse_notes_metrics` 换成查 `commit_metrics`（fix 且非 CI 自修）；`avg_rounds_M` 基线暂为 null（需 PR 边界，留档2）
- **scope 原样聚合**，module 映射后置

新增：`commands/onboarding.rs`、`commands/commit_metrics.rs`、`resources/onboarding/*.tmpl`、`commit_metrics` 表
修改：`buff.rs`(check_project 加解析)、`blueprint.rs`(append_usage_snapshot)、`db.rs`、`lib.rs`、前端入口

## 任务卡

> 已过 /architect + /splitter。A→B、C1→C2 两条链可并行，D 依赖 C1+B；**C1（飞轮地基）建议优先开工**。

### ✅ A 模板分发引擎
- status: done
- complexity: M
- files: src-tauri/src/commands/onboarding.rs, src-tauri/resources/onboarding/{AGENTS.md,lefthook.yml,git-workflow.md}.tmpl
- acceptance: include_str! 内嵌 3 个标准模板（蓝本取自 enterprise-system）；分发时文件不存在→写入、已存在→跳过并在报告标注，绝不覆盖；复用 mcp_inject 的路径解析（含 WSL）；返回每个模板的 written/skipped/failed

### ✅ B apply_onboarding_pack 编排 + 前端入口
- status: done
- complexity: M
- depends: onboarding-pack（卡A）
- files: src-tauri/src/commands/onboarding.rs, src-tauri/src/lib.rs, src/lib/commands.ts, src/components/dashboard/ProjectCard.tsx
- acceptance: apply_onboarding_pack(project_path, project_id) 组合「模板分发 + apply_blueprint_buff」返回 OnboardingReport；看板卡片有"接入包"入口，展示分发报告（written/skipped/failed）

### ✅ C1 commit_metrics 表 + Conventional 解析器
- status: done
- complexity: M
- files: src-tauri/src/commands/commit_metrics.rs, src-tauri/src/db.rs
- acceptance: 新增 commit_metrics 表（sha PK / project_id / commit_type / scope / is_rework / is_ci_auto / committed_at / parsed_at）；`parse_conventional(message)` 解析 type/scope，type=fix→is_rework，`[DeepSeek-V3]`/`[R1]` 等标记→is_ci_auto，非 conventional→commit_type=null 单列；提供聚合查询 `rework_count(project_id)`；解析逻辑纯函数可单测（覆盖 feat/fix/带scope/无scope/CI自修/非规范 六种输入）

### ✅ C2 挂接 buff watcher + 飞轮快照
- status: done
- complexity: M
- depends: onboarding-pack（卡 C1）
- files: src-tauri/src/commands/buff.rs, src-tauri/src/commands/blueprint.rs
- acceptance: check_project 用 `last_commit..HEAD` 取 commit message（git log，复用现有 WSL 路径处理）→ 调 C1 解析写 commit_metrics；首次接入（last_commit 空）限解析最近 N 条；append_usage_snapshot 的 rework_count 改查 commit_metrics（is_rework=1 AND is_ci_auto=0）取代 parse_notes_metrics

### ✅ D 数据可信度提示
- status: done
- complexity: S
- depends: onboarding-pack（卡 C1、卡 B）
- files: src-tauri/src/commands/onboarding.rs, src-tauri/src/commands/commit_metrics.rs
- acceptance: OnboardingReport 与飞轮展示标注该项目 commit 规范化比例（conventional / 总数）；比例低时提示"种 lefthook 后数据才准"，避免脏数据被误读为可信（CI 过滤 / 非规范单列已在 C1 落实）

### ✅ T1. 接入包模板版本化（ONBOARDED_MANAGED 块机制）【体系分发前置】
- status: done
- done_note: 2026-07-03 dispatch_versioned 三态落地（written/updated/appended + 同版本 skipped），块外用户内容保护有测试兜底；AGENTS/git-workflow 模板入 ONBOARDING_MANAGED v1.1.0 块，lefthook 保持存在即跳过。**实测（用户走 UI，R13）**：enterprise-system 与 noteapp 重跑接入包均 appended×2 + lefthook skipped，磁盘验证两项目 ONBOARDING v1.1.0 + BLUEPRINT v1.10.0 双块到位。发现并修复：前端分发报告只认旧三态，appended 误显 ✗（c4a6600，R12 反例实证）。已知一次性迁移成本：enterprise-system 块外存在项目定制版「核心开发约束」与块内通用版共存，去重留给该项目自己的会话
- complexity: M
- files: src-tauri/src/commands/onboarding.rs, src-tauri/resources/onboarding/git-workflow.md.tmpl, src-tauri/resources/onboarding/AGENTS.md.tmpl
- acceptance: git-workflow 与 AGENTS.md 模板的炼境管理内容包进 ONBOARDING_MANAGED 标记块（带 version）；分发逻辑三态：文件不存在→写全新；存在且有标记→原位更新块（复用 blueprint.rs 的 upsert_managed_block 模式，可提取公共函数）；存在无标记→末尾追加块；块外用户内容永不触碰；lefthook.yml 保持"存在即跳过"（用户深度定制不适用块机制）；单元测试覆盖三态 + 用户区保护；对 enterprise-system 重跑接入包实测存量升级

> 背景：模板演进无法触达存量项目是版本化闭环的最大缺口（trailer 章节曾手工补）。

### ✅ V1. 接入生效验收：lefthook 激活 + verify_onboarding 按钮
- status: done
- done_note: 2026-07-04 完成。apply_onboarding_pack 分发后自动 lefthook install（本地 node_modules/.bin 优先、PATH 兜底、CREATE_NO_WINDOW 静默），报告新增 hook 三态；verify_onboarding MCP 工具六项检查链（AGENTS/git-workflow 管理块版本自省对比、pre-commit 真挂 lefthook、origin host 命中已登记 Gitea 实例、.gitea/workflows 存在、近 30 天 commit_metrics 流入）；判定逻辑纯函数化 5 条单测 + in-memory DB 全链集成测试（空项目六项全 fail → 铺齐后六项全 pass）；前端 commands.ts 类型同步（顺修 TemplateResult 缺 updated/appended 旧债）+ BlueprintModal 显示 hook 激活行。MCP 实调待炼境升级重启后终验（当前运行实例是旧 build）
- complexity: M
- depends: onboarding-pack（卡 B、卡 T1）
- files: src-tauri/src/commands/onboarding.rs, src-tauri/src/mcp_tools.rs, src/lib/commands.ts
- acceptance: [Tauri command] apply_onboarding_pack(project_id) 分发 lefthook.yml 后检测并激活 hook——找到 lefthook 可执行（node_modules/.bin/ 或 PATH）→ 执行 lefthook install，OnboardingReport 新增 hook_activated 三态（activated / missing_binary / failed），missing_binary 时附安装提示；[MCP tool] verify_onboarding(project_id) → 返回检查链 JSON（模板管理块版本到位 / .git/hooks/pre-commit 含 lefthook / origin 指向 Gitea / CI workflow 文件存在 / commit_metrics 近 30 天有该项目数据），每项 pass|fail + detail，无 error 字段；[cargo test] 检查链判定逻辑纯函数化，覆盖 hook 已挂/未挂、origin 匹配/不匹配（R06/R07）
- notes: 背景（2026-07-04 侦察确认）——接入包写 lefthook.yml 后从不激活，文件在 hook 死 → conventional 不强制 → 飞轮数据脏；炼境自身未踩纯因手动装过。本卡补两件事：① 分发即激活；② "消费者角色"机器化验证（分发成功 ≠ 功能生效，对应 agent-button-system.md 消费者驱动验证）。产出直接供 B4 健康诊断遵守度消费。同日发现的姊妹雷：cicd.rs PR CI 模板 pnpm lint --if-present 必挂语法已修（dc501f7，回归断言驻军）

### ✅ T2. git-workflow 模板：分支策略升级为复杂度感知
- complexity: M
- status: done
- done_note: 2026-07-04 完成。模板 ONBOARDING_MANAGED 升至 v1.3.0，分支策略改为复杂度感知（简单改动直推 main/master，功能性改动开 feat/<name> 分支+PR），PR MCP 示例 head 从 "dev" 改为 "feat/<name>"
- files: src-tauri/resources/onboarding/git-workflow.md.tmpl
- acceptance: [Tauri command] 对已接入项目重跑接入包 → git-workflow.md ONBOARDING_MANAGED 块升至 v1.3.0，内容含「简单改动直推 main/master，功能性改动开 feat/<name> 分支 + PR」策略；PR 创建 MCP 示例 head 字段从 "dev" 改为 "feat/<name>"；docs/templates/agents-meta-rules.md 不含分支策略无需同步
- notes: 当前模板强制 dev→main 双分支，假设了任意项目都维护常设 dev 分支，实为过度约束。复杂度感知策略（小改直推 main/master，功能性改动开 feat/* + PR）与炼境自身策略一致、与飞轮目标对齐（PR body 是意图层数据），且对单人小项目更友好——不必维护无意义的常设 dev 分支。「简单/功能性」由 agent 根据改动文件数/性质自判，无需外部蓝图标签

### ✅ agent 按钮体系分发（B1/B2/B3 已完成，B4 后置）
- status: done
- done_note: 2026-07-04 B3 完成——CONVENTIONS.md manifest.yaml 规范新增 agent_button_carrier 字段（tauri/http/cli/playwright 四值）+ 必填规则；splitter SKILL.md 优先从 manifest 读取载体（三级优先：manifest字段>architect声明>就近推断）；炼境自身 manifest.yaml 补上 `agent_button_carrier: tauri`；AGENTS.md.tmpl 项目概况 TODO 提示新增该字段填写指引。B4 健康诊断遵守度后置。
- progress: 2026-07-03 B1 done——CONVENTIONS 1.10.0 加 R12（边界单点实现）+ R13（M/L 验收路径须真实走通，含载体就近选择表）；B2 done——AGENTS.md.tmpl v1.1.0 管理块含「agent 按钮与验证路径」章节（双投影/边界单点/载体表/完成的定义/侦察→驻军）。B3 done 2026-07-04（见 done_note）
- 版本化闭环要求（2026-07-03 用户澄清，体系分发的灵魂）: 分发不是"发了就不管"——每类资产带版本分发 → 子项目按该版本实践产生经验（成功/失败）→ 经验自吸反哺炼境（trailer/failure_cases/复盘/返工率）→ 按版本分组对比效果 → 修订出新版 → 再分发。CONVENTIONS 是模范生（version+队列对比+梦核+同步，1.8→1.9 已跑通一整圈）；B 系列每类资产按此标准建闭环。**前置依赖提升**：「接入包模板演进分发（MANAGED 块化）」concept 卡——模板无版本机制是当前最大缺口，没有它体系 v2 到不了存量项目
- notes: 2026-07-03 概念探讨收束后的分发需求（体系详见 memory concept_dual_projection 与 mcp-server 模块 concept 卡）。用户全 agent 开发形态下，"给开发者立规范"="给 agent 注入规范"，可完全机器化。四条现成管道分发四类资产：① B1(S) CONVENTIONS 1.10.0 加 R12 边界单点实现 + R13 验收须真实走通验证路径 + 载体选择原则；② B2(S) 接入包 AGENTS.md 模板加 agent 按钮章节（三要素/载体谱系/侦察驻军）；③ B3(M) init/sync 提示词升级——建蓝图时声明项目按钮载体、acceptance 生成为可执行验证路径格式；④ B4(S,后置) 健康诊断加体系遵守度检查。移植体验=零新增动作，接入流程不变。

### ✅ U1. 全托管文件升级通道 + 批量重分发（择升环断点修复 ①）
- status: done
- done_note: 2026-07-15 完成（分支 feat/onboarding-pack-u1 → PR）。dispatch_fully_managed 三态（written/skipped/updated，CRLF 归一化防覆盖抖动），envoy.md/blueprint-gate.cjs 切换全托管并加「由炼境托管」声明头；verify_onboarding 新增第 7 项「lefthook 检查段齐全」——期望键集合从内嵌 TMPL_LEFTHOOK 自省提取（lefthook_command_keys 纯函数，注释行不算键），零硬编码；MCP apply_onboarding_pack 支持批量模式（project_id 字段缺失→全部已登记项目，空串仍按无效单项目报错），schema required 放宽为空并同步测试断言（契约放宽属验收要求，已声明）。cargo test 102 全过。**实调终验（2026-07-15 dev 实例，遗留已销）**：批量分发 25 项目 0 失败——存量项目 envoy/gate 全部 updated（全托管通道生效）、AGENTS 块多项目原位升 v1.6.0；ingest 全量重跑 19 项目清洗 0 条（存量本就干净，防线在位）；verify 抽查 enterprise-system 与炼境自身均 6/7，唯一 fail 恰是新增「lefthook 检查段」并准确列出各自缺失键（检测落后功能真实工作）。PR #4 已 merge。batch_apply.py/scan_onboarded.py 可清理（用户处置）
- complexity: M
- depends: onboarding-pack（卡 T1）
- files: src-tauri/src/commands/onboarding.rs, src-tauri/src/mcp_tools.rs, src-tauri/resources/onboarding/.claude/commands/envoy.md, src-tauri/resources/onboarding/.claude/hooks/blueprint-gate.cjs
- acceptance: [Tauri command] 对存量项目重跑 apply_onboarding_pack → envoy.md / blueprint-gate.cjs 与内嵌模板不一致时覆盖（action=updated），一致时 skipped，文件头含「由炼境托管，重跑接入包会覆盖」声明；[cargo test] dispatch_fully_managed 三态（不存在→written / 一致→skipped / 不一致→updated）；[MCP tool] verify_onboarding 的 lefthook 检查项从内嵌 TMPL_LEFTHOOK 自省提取 commands 键集合，项目 lefthook.yml 缺键 → fail + 列出缺失键（禁止硬编码具体检查项名，模板演进校验器零维护）；[MCP tool] apply_onboarding_pack 不传 project_id → 对所有已登记项目批量执行并返回逐项目摘要（复用 ingest_git_history 先例），验收通过后删除 batch_apply.py / scan_onboarded.py
- notes: dispatch_one「存在即跳过」使回流修正只能推到 AGENTS/git-workflow 两份版本化文档——envoy/gate 的 bug 修复永远到不了存量 12 项目，批量重分发靠临时 python 脚本硬扛（batch_apply.py 为实锤）。三档升级语义见决策记录。已知盲点（辩证承认）：首次覆盖时子项目文件尚无托管声明，存在一次性盲覆盖窗口——envoy/gate 分发仅一周、被定制概率极低，且 updated 会在报告显式出现，风险接受

### ✅ U3. Rules-Applied 真实性校验（ingest 层单点实现，择升环断点修复 ②）
- status: done
- done_note: 2026-07-15 完成。纯函数 extract_rule_ids（R+数字 token 边界识别，防 PR13/R2D2 误提取）+ filter_valid_rules（valid=None 不校验 fail-open）；校验接入全部 4 条写入链路（buff 增量 / webhook push / gitea 轮询 / 全量导入），规则集每项目每批次加载一次；sanitize_rules_applied 显式回溯清洗通道（UPSERT「不覆盖」约束原样保留，两者并行不悖）；IngestResult 新增 sanitized 字段（Rust/TS/MCP 输出/FlywheelPanel 四层同步）；record_commit 收窄为 #[cfg(test)]，生产链路只剩 validated 版防绕过。cargo test 98 全过（新增 5 测：token 边界/过滤/入库剔除/message 链路/清洗幂等+仅清洗指定项目），pnpm typecheck 干净
- complexity: S
- files: src-tauri/src/commands/commit_metrics.rs
- acceptance: [cargo test] trailer 解析校验纯函数——规则 ID 不存在于该项目 .blueprint/CONVENTIONS.md（如 R99）→ 从 rules_applied 剔除并可观测（日志或 invalid 计数），真实 ID 保留；项目无 CONVENTIONS.md → 不校验全保留；[MCP tool] ingest_git_history 重跑 → 「规则命中 × 返工」交叉统计不再含未知 ID（存量污染可回溯清洗）
- notes: 辩证翻转载体：原方案（子项目 commit-msg hook）违反 R12 边界单点——统计消费端在炼境，校验就该在炼境 ingest 层。收益：零分发成本覆盖全部项目、重跑即回溯清洗、cargo test 可测（炼境自身 agent 按钮载体）。commit-msg hook 即时反馈版降为可选增强（若做依赖 U1 通道，不在本卡）。上限诚实：只挡 typo/幻觉 ID，「真 ID 假触发」留给宁缺毋滥纪律

### ✅ B4. 健康诊断遵守度 + 回传覆盖率（吸收被否决的 U2，择升环断点修复 ③）
- status: done
- done_note: 2026-07-15 完成。onboarding.rs 新增 silent_projects(conn)（R06 注入）：近 30 天有 commit_metrics 但零使者回传的已登记项目，SQL 经 blueprint_buffs UUID→win_path→project_workspaces 双路径关联（复用 get_all_commit_health 身份解析形状），未登记项目不列入（无法跑 /envoy）；get_diagnostics 新增「使者回传覆盖率」段，沉默项目列名称+commit 数并提示跑 /envoy。cargo test 99 全过（新测覆盖：UUID 关联命名/普通笔记不算回传/未登记不列入/回传过期重新变沉默）
- complexity: S
- files: src-tauri/src/mcp_tools.rs, src-tauri/src/commands/onboarding.rs
- acceptance: [MCP tool] get_diagnostics（或 verify_onboarding 检查链）新增「沉默项目」信号：项目近 30 天 commit_metrics 有数据但使者回传（list_envoy_returns 同源数据）为 0 → 列出项目名 + commit 数，提示去该项目跑 /envoy；近 30 天有回传或无 commit 活动 → 不报
- notes: U2（子项目侧 Stop hook 自动触发 /envoy）经多角度辩证否决（2026-07-15）：自动化触发会拆掉人肉过滤层，诱导 agent 用 under_validation 噪声交差灌满回传通道——伤「择」换「环」转速，本末倒置。正解是炼境侧可观测性：让遗忘可被看见（信号驱动），人留在过滤环里决定是否回传。同时销掉原 B4 后置欠账（体系遵守度检查）

### ✅ V2. AGENTS 模板注入「同源同边界 + 操作复刻」设计原则（v3.1）
- status: done
- done_note: 2026-08-23 完成。四刀外科手术：节首总纲（本体+双投影/先本体后投影+原型豁免）、第1条追加复刻推论+三分定位启发式、human_verify 补否决理由记录一句、版本 1.6.1→1.7.0；炼境自身 AGENTS.md 块内同步、agents-meta-rules.md 新增同源同边界节；cargo test onboarding 13 全过。补遗（同日）：节尾收束语「本体先行，边界一次，操作同语——人指的问题 agent 走得到，人在意的点 agent 读得懂」+ 需求对称两时间尺度脚注（当下=同源结构直接保证；跨会话=否决理由落账→复盘笔记→梦核，机制通道挂 governance-feedback-loop 缺口①）。1.7.0 未曾分发故不再升号。分发待重建安装后批量 re-apply
- complexity: S
- files: src-tauri/resources/onboarding/AGENTS.md.tmpl, AGENTS.md, docs/templates/agents-meta-rules.md
- acceptance: agent_verify: [文件] AGENTS.md.tmpl「agent 按钮与验证路径」节含「同源同边界」「操作序列 agent 皆可复刻」「三分定位」表述，MANAGED 版本 1.6.1→1.7.0；炼境自身 AGENTS.md 块内同步；cargo test onboarding 通过
- notes: 2026-08-23 多角度辩证收敛（v3→v3.1 外科手术版）：真实增量仅三个半（先本体后投影时序/复刻+复现路径/三分定位启发式/飞轮转译轻写一句），其余为已有六条重述不重复注入；三分定位从"定律"降级"启发式"（crypto.randomUUID 环境层实锤：本体投影都没病，病在环境）；原型探索豁免时序约束；飞轮转译不承诺机制（采集通道挂 governance-feedback-loop 缺口①）

### ✅ F1. 托管模板指纹测试：改内容必须升版本（文档约束 → 机器校验）
- status: done
- done_note: 2026-10-03 完成。tests 新增 managed_template_fingerprints_track_versions + 「版本号 → 摘要」登记表 TEMPLATE_FINGERPRINTS 三项：resources/onboarding/** 全部资源（递归遍历，新增模板文件自动纳入）↔ BASE_ONBOARDING_PACK_VERSION；AGENTS / git-workflow 管理块 ↔ 块首 version。摘要前 CRLF→LF，段间 \0 分隔；Python 直接对 git index LF blob 独立复算三项摘要与 Windows CRLF 工作区结果一致。报错区分「内容变了版本没升」与「版本已升待更新指纹」，并给出可直接粘贴的新登记行。BASE 与模板 capability-packs.json 相等复用既有 check_capability_packs 断言（补可读报错）。自验：cargo test --locked onboarding 22 全过；envoy.md 改一字 → 仅 pack 项失败（其余 21 测仍全过，即旧测试抓不到该漏洞）；AGENTS 块内改一字 → pack + AGENTS 两项失败；均已还原（envoy.md sha256 前后一致）后全绿。侦察佐证：dbc1b06（2026-09-23）改了 git-workflow 管理块内容未升 1.7.0，文档规则在 07-06 之后仍被漏过。**合入前实证更新流程**：rebase 到并行合入的 PR #28（envoy/SKILL/AGENTS 模板改动，规范升 BASE 1.7.0、AGENTS 块 1.10.0）后测试按设计报「版本已升，更新指纹常量即可」并给出新登记行（git-workflow 未动不报），照报错更新登记表后 22 全过、全量 cargo test 267 过
- complexity: S
- files: src-tauri/src/commands/onboarding.rs, .claude/rules/onboarding-sync.md
- acceptance: agent_verify: [cargo test] `cd src-tauri && cargo test --locked onboarding` 全绿；临时改 resources/onboarding/.claude/commands/envoy.md 一个字 → 指纹测试失败且报错含「升 BASE_ONBOARDING_PACK_VERSION 与 capability-packs.json 版本，并更新指纹常量」，还原后通过；摘要前 CRLF→LF 归一化（工作区 autocrlf=CRLF 与 CI LF 同摘要）
- notes: 全托管文件（envoy.md / SKILL.md）按内容覆盖，但 verify 只看 capability-packs 版本（check_skill 仅子串检查）——只改内容忘升 BASE_ONBOARDING_PACK_VERSION 时 verify 永远 ready、无人重跑分发，子项目收不到更新。onboarding-sync.md 的升版规则此前只有文档约束（2026-07-06 块版本漏升实锤）。指纹表同时钉住 AGENTS / git-workflow 的 ONBOARDING_MANAGED 块版本（同类漏洞：块版本不升 → dispatch_versioned 全部 skipped）

## 复盘笔记

【复盘】U1 全托管文件升级通道 + 批量重分发（2026-07-15）
任务类型: 分发引擎 + MCP 工具 + 验收链扩展
复杂度: M
实际轮数: 1 轮实现 + 1 轮实调修复（预估 1 轮）
是否返工: 是（实调暴露空路径 bug，473cf7e 补修）
有效策略: 立卡前多角度辩证砍掉伪需求（U2 否决、U3 载体翻转），实现返工率显著低于直做；检查项从内嵌模板自省（lefthook_command_keys）延续 V1 范式，校验器零维护；dev 实例实调=真实终验路径，两小时内筛出两个纯靠单测到不了的坑（空路径写 cwd、托管块抹本地定制）
踩坑: ① 批量 SQL 只滤 NULL 没滤空串，空路径登记让接入包写进进程 cwd（src-tauri/ 被污染）——路径入口防护必须在能力本体层单点做，已驻军回归测试；② 本地定制写在 MANAGED 块内被版本升级原位抹掉（分支策略表/按钮清单/降级约定/启动协议第4条）——托管块的"设计行为"反噬使用侧违规，恢复至块外并入决策记录
遗留: 全托管首次覆盖的盲窗口已发生（5 个存量项目 envoy/gate 被覆盖，未逐一核对覆盖前有无定制——各项目 git 历史可兜底恢复）；「块内被手改检测」（升级前 diff 旧块 vs 旧版模板，不符则警告）为候选改进，暂不立卡
auto_applied_rules: R06, R07, R13
rule_effectiveness: R06=有效（conn 注入使 silent_projects/校验全链可单测）, R07=有效（净增 10 条测试含 2 条坑驱动回归）, R13=有效（实调走通即抓出两坑，验证"分发成功≠功能生效"）

【复盘】V1 接入生效验收（2026-07-04）
任务类型: 后端命令 + MCP工具 + 前端类型同步
复杂度: M
实际轮数: 1轮（预估 1 轮）
是否返工: 否
有效策略: 立卡前先侦察实锤（grep 确认 lefthook install 全仓库零调用、cicd.rs 模板同款 lint 语法雷），acceptance 直接写成可执行验证路径使实现无歧义；检查链判定与 IO/DB 分离（纯函数 + conn 注入），in-memory DB 全链集成测试把"空项目全 fail → 铺齐全 pass"变成回归资产；模板期望版本从内嵌模板自省（extract_managed_block）而非硬编码，模板升版验收逻辑零维护
顺手修的旧债: 前端 TemplateResult 类型缺 updated/appended 两态（T1 时只修了组件层样式映射，类型层漏了）；AGENTS.md/agent-button-system.md 写死"21 个工具"计数（防腐铁律违例，改为指向 tools_list_result 自省）
遗留: ~~WSL UNC 路径下 lefthook install 未实测~~（已销项：2026-07-04 用户裁决放弃 WSL 路径项目，见决策记录）
追记（2026-07-04 批量接入实战）: MCP 实调已终验——8 项目跑通 apply+verify，enterprise-system/autoforphone/炼境自身 6/6 全绿。踩坑：Windows PATH 兜底对 pnpm 全局 shim 失效（pnpm -g 装的是 lefthook.cmd，CreateProcess 裸名只解析 .exe）→ 兜底追加尝试 "lefthook.cmd" 修复；本轮 6 个项目由 agent 手动 lefthook install 补齐（与按钮同路径）
auto_applied_rules: R01, R06, R07, R13
rule_effectiveness: R01=有效（commands.ts 同步时暴露类型层旧债）, R06=有效（conn 注入使全链集成测试可行）, R07=有效（6 条新测试）, R13=有效（集成测试即真实走通的验收路径）