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 与蓝图分工）

git 是「过去时 + 量化」（做了什么），蓝图是「将来时 + 语义」（为什么这么做 + 怎样算做完），AGENTS.md 是「静态约定」（项目是什么 + 怎么动它）。

• 状态/进度交给 git 推断：模块 status/progress 不再手动声明，由炼境读 commit 活动推断 + 人确认（消除双写负担）
• 蓝图只留 git 给不了的：决策记录(WHY)、验收契约、踩坑根因、架构全景
• 蓝图分级：小项目可不要蓝图（AGENTS.md + 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、C→D 两条链可并行；C（飞轮地基）建议优先。

📋 A 模板分发引擎

• status: planned
• 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: planned
• 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）

📋 C L0 Conventional Commit 解析

• status: planned
• complexity: L
• 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: 新增 commit_metrics 表；buff watcher 的 check_project 用 last_commit..HEAD 取 message → 解析 type/scope/is_rework/is_ci_auto 写表；append_usage_snapshot 的 rework_count 改查 commit_metrics（is_rework=1 AND is_ci_auto=0）；首次接入限解析最近 N 条

📋 D 数据质量保护

• status: planned
• complexity: S
• depends: onboarding-pack（卡C）
• files: src-tauri/src/commands/commit_metrics.rs
• acceptance: CI 自修 commit（[DeepSeek-V3] 等标记）置 is_ci_auto=1 从返工率剔除；非 conventional commit 记 commit_type=null 单列不污染 fix 率；接入报告提示"种 lefthook 后数据才准"