# 接入包（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 + 瘦蓝图 | 长周期/多业务线 |

## 决策记录

- 飞轮升格与 Gitea API 对接「分步实施」而非耦合：buff 读本地 `.git`（commit type/scope），与远程平台无关，可先做；Gitea API（CI 状态/PR review）随后
- 「完整分发」是陷阱，正确形态是分级菜单：新项目种全套，旧项目增量接入（复用 mcp_inject 的「命名空间隔离 + 合并不覆盖」语义，不动用户已有配置）
- 接入动作：现有 `apply_blueprint_buff` 升格为 `apply_onboarding_pack`，按档编排注入
- 语义层进料口隐患：决策/验收/踩坑仍需主动写（与饿死复盘笔记同源），须配「从 PR 标题/commit body/review 评论半自动提取」，不再单纯指望人自觉

## 复用的现有能力（~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 落实）

### 💭 接入包模板演进分发（MANAGED 块化）
- status: concept
- notes: 现状「文件存在即跳过、绝不覆盖」保护了用户定制，但代价是模板演进（如 2026-07-02 git-workflow 新增 Rules-Applied trailer 章节）无法触达存量项目，只能手工补（enterprise-system 已手工补过一次）。方案方向：给 git-workflow.md 引入 ONBOARDING_MANAGED 块（同 CLAUDE.md 的 BLUEPRINT_MANAGED 机制）——炼境管理区可原位升级、块外用户自由区永不触碰；lefthook.yml 因用户深度定制（monorepo filter 等）不适用块机制，改为版本注释+差异提示。

