lanrtop/dev-manager-tauri
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
feat/onboarding-pack
dev-manager-tauri/.blueprint/modules/onboarding-pack.md
lanrtop 428bb02a90
All checks were successful
Push & PR Check / check (push) Successful in 46s
Details
Push & PR Check / check (pull_request) Successful in 46s
Details
chore(blueprint): T2 验收完成 — git-workflow 分支策略升级
2026-07-04 10:24:18 +09:00

15 KiB
Raw Permalink Blame History

接入包（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 落实）

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

🔵 agent 按钮体系分发（B1/B2 已完成，B3/B4 待做）

  • status: in_progress
  • progress: 2026-07-03 B1 done——CONVENTIONS 1.10.0 加 R12（边界单点实现）+ R13（M/L 验收路径须真实走通，含载体就近选择表）；B2 done——AGENTS.md.tmpl v1.1.0 管理块含「agent 按钮与验证路径」章节（双投影/边界单点/载体表/完成的定义/侦察→驻军）。剩 B3（提示词升级，M，单独一轮）、B4（健康诊断遵守度，后置）
  • 版本化闭环要求（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,后置) 健康诊断加体系遵守度检查。移植体验=零新增动作，接入流程不变。

复盘笔记

【复盘】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 自省） 遗留: MCP 工具实调需炼境升级重启后终验（运行实例是旧 build）；WSL UNC 路径下 lefthook install 的 current_dir 行为未实测，失败会如实进 failed 态不会误报 auto_applied_rules: R01, R06, R07, R13 rule_effectiveness: R01=有效（commands.ts 同步时暴露类型层旧债）, R06=有效（conn 注入使全链集成测试可行）, R07=有效（6 条新测试）, R13=有效（集成测试即真实走通的验收路径）