From 2ed548556ca18955f1bbbf160a8e7260c44cb2f1 Mon Sep 17 00:00:00 2001 From: lanrtop Date: Fri, 19 Jun 2026 11:39:11 +0900 Subject: [PATCH] =?UTF-8?q?docs(blueprint):=20=E5=9B=BA=E5=8C=96=E7=BB=9F?= =?UTF-8?q?=E4=B8=80=20Gitea=20=E5=8F=8C=E5=B1=82=E6=9E=B6=E6=9E=84=20+=20?= =?UTF-8?q?=E6=8E=A5=E5=85=A5=E5=8C=85=20architect=20=E8=AE=BE=E8=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 战略转向统一自建 Gitea、冻结 GitHub；新增 onboarding-pack（两档接入包 + 基线 architect 设计 4 卡）与 gitea-integration（风筝线模型 + webhook）；flywheel 转向 git 自吸 + 新增 L0 commit 解析层 --- .blueprint/manifest.yaml | 38 ++++++++- .blueprint/modules/flywheel-intelligence.md | 19 ++++- .blueprint/modules/gitea-integration.md | 55 ++++++++++++ .blueprint/modules/github-auth.md | 4 +- .blueprint/modules/github-publish.md | 2 + .blueprint/modules/onboarding-pack.md | 94 +++++++++++++++++++++ 6 files changed, 207 insertions(+), 5 deletions(-) create mode 100644 .blueprint/modules/gitea-integration.md create mode 100644 .blueprint/modules/onboarding-pack.md diff --git a/.blueprint/manifest.yaml b/.blueprint/manifest.yaml index b8b207f..3cd0fc1 100644 --- a/.blueprint/manifest.yaml +++ b/.blueprint/manifest.yaml @@ -6,7 +6,7 @@ description: > 成为每个项目的贴身导师。炼境本身亦被纳入其中， 形成可自我进化的开发智能闭环。 iteration: 1 -updated: 2026-04-19 +updated: 2026-06-19 @@ -106,14 +106,14 @@ modules: - id: github-auth name: GitHub OAuth area: backend - status: done + status: deprecated progress: 100 position: [250, 350] - id: github-publish name: GitHub 发布 area: backend - status: done + status: deprecated progress: 100 position: [500, 350] @@ -363,6 +363,21 @@ modules: progress: 100 position: [3250, -150] + # ── 统一 Gitea 接入包（2026-06-19 战略转向）────── + - id: onboarding-pack + name: 接入包 + area: backend + status: concept + progress: 0 + position: [3500, 0] + + - id: gitea-integration + name: Gitea 集成 + area: backend + status: concept + progress: 0 + position: [3500, 150] + edges: # 前端依赖 - from: workspace-mgmt @@ -572,3 +587,20 @@ edges: - from: cloud-products to: cloud-db-instances type: dependency + + # 接入包（统一 Gitea 双层架构） + - from: blueprint-buff + to: onboarding-pack + type: dependency + - from: mcp-config-inject + to: onboarding-pack + type: dependency + - from: blueprint-onboarding + to: onboarding-pack + type: dependency + - from: onboarding-pack + to: gitea-integration + type: dependency + - from: gitea-integration + to: flywheel-intelligence + type: related diff --git a/.blueprint/modules/flywheel-intelligence.md b/.blueprint/modules/flywheel-intelligence.md index 23f8b02..433a6d0 100644 --- a/.blueprint/modules/flywheel-intelligence.md +++ b/.blueprint/modules/flywheel-intelligence.md @@ -10,10 +10,16 @@ 本模块分三个阶段逐步打通数据→改善的完整闭环。 +## 方向修订（2026-06-19） + +阶段一/二依赖「AI 主动写结构化复盘笔记」作为执行质量数据源。实测发现该进料口几乎枯竭：70 条笔记仅炼境自身 4 条结构化，外部项目存量为旧格式，`rework_count`/`avg_rounds_M` 长期为 0/null。 + +**根本转向**：执行质量数据从「AI 主动上报」改为「炼境从 git 被动自吸」——解析 conventional commit 的 type（fix=返工）/scope（=模块）自动计算，客户端无关、工作流无关。新增 **L0 解析层**（见任务卡）作为阶段三预测层的数据地基。详见 memory [[project_gitea_unified_architecture]] 及 onboarding-pack / gitea-integration 模块。 + ## 阶段触发条件 - **阶段二启动条件**：阶段一上线后，梦核输出中稳定出现"高频陷阱摘要"板块，且跨项目复盘笔记数量 ≥ 20 条 -- **阶段三启动条件**：阶段二运行 ≥ 3 个月，accumulated 数据覆盖 ≥ 15 个项目，usage.json 携带 rework_count 和 avg_rounds 字段 +- **阶段三启动条件（已修订）**：L0 解析层上线后，conventional commit 执行质量数据稳定覆盖 ≥ 10 个项目（不再依赖复盘笔记积累时长，见上「方向修订」） --- @@ -93,6 +99,17 @@ --- +### 📋 L0：Conventional Commit 执行质量解析层（数据地基，先于阶段三） +- status: concept +- complexity: L +- depends: onboarding-pack（项目须先种 lefthook + conventional 规范） +- files: src-tauri/src/commands/buff.rs, src-tauri/src/commands/blueprint.rs +- acceptance: 炼境后端从本地 git 解析 conventional commit —— type=fix 计返工、scope 映射模块、commit 数≈轮数；自动填充 usage.json 的 rework_count/avg_rounds_M/complexity_dist，取代「从复盘笔记解析」的枯竭路径；CI 自修 commit（如 `[DeepSeek-V3]`）须从返工率剔除；squash merge 项目须降级处理 + +> 背景：实测复盘笔记进料口枯竭（70 条仅 4 条结构化）。改由 git 自吸，客户端无关、工作流无关，是阶段三预测层的真实数据基础。 + +--- + ### 阶段三：执行质量预测层 - status: todo - complexity: L diff --git a/.blueprint/modules/gitea-integration.md b/.blueprint/modules/gitea-integration.md new file mode 100644 index 0000000..1306413 --- /dev/null +++ b/.blueprint/modules/gitea-integration.md @@ -0,0 +1,55 @@ +# Gitea 集成 + +对接已有的自建 Gitea 实例，作为所有被管理项目的统一 git 后端。接入包「增配档」的核心。 + +## 风筝线模型（炼境与 Gitea 的关系） + +🪁 **风筝 = Gitea 本体**（git 存储 + CI 执行）：独立部署、独立运行，炼境**不托管其进程、不背运维**。 +🧵 **线 = 炼境的掌控**（控制面）：炼境是**唯一持线人**——Gitea 连接/token 统一存炼境，建仓/关联/迁移/配置 lefthook&CI 的操控全经炼境，子项目对 Gitea 的动作都从它手里过。 +👀 **关注风筝的动态 = 观测面**（飞轮燃料）：炼境持续感知每个子项目 ↔ Gitea 的连接动态（push 的 commit type/scope、PR、CI 三阶段、review、停滞项目）。 + +> 「线」≠ 松散 API 对接：炼境是**主动掌控者**而非被动客户端。风筝越多 → 线越多 → 动态越丰富 → 飞轮越强（契合核心愿景）。 + +## 其他边界 + +- 替代炼境现有 GitHub 能力：`github-auth` / `github-publish` 已冻结，`cicd.rs` 的 GitHub Actions 生成改造为 Gitea Actions +- 炼境自身仓库也迁 Gitea（发布产物仍走 OSS updater 不变） + +## 参考实现 + +`enterprise-system` 已趟通完整链路，属「照搬」而非「从零探索」： +- Gitea origin（`git.yljt.info`）+ Gitee 镜像（备份） +- lefthook 强制 conventional commit + typecheck（pre-commit） +- Gitea Actions 三阶段 CI：静态检查 → 测试（DeepSeek-V3 自修）→ PR code review（DeepSeek） +- Gitea Actions 语法兼容 GitHub Actions，迁移成本低 + +> 详见 `E:/code-project/enterprise-system/docs/ai-context/git-workflow.md` 与 `AGENTS.md`。 + +## 任务卡（concept，待 /architect） + +### 💭 Gitea API 对接（握线基础） +- status: concept +- complexity: L +- acceptance: TBD —— 建仓/关联、推送、读 CI 状态、读 PR review 结果 + +### 💭 观测面：Gitea webhook 接入（持线人感知动态） +- status: concept +- complexity: L +- files: src-tauri/src/mcp_server.rs（内嵌 HTTP server 加 webhook 端点）, src-tauri/src/commands/blueprint.rs +- acceptance: TBD —— 复用炼境内嵌 HTTP server 新增 Gitea webhook 接收端点；实时接住各子项目 push/PR/CI/review 事件 → 解析 conventional commit（对接 flywheel-intelligence 的 L0 解析层）→ 写飞轮快照 + 刷新连接动态；webhook 不可达时降级为定时轮询 Gitea API + +### 💭 Gitea Actions workflow 生成 +- status: concept +- complexity: M +- files: src-tauri/src/commands/cicd.rs（改造） +- acceptance: TBD —— 生成 Gitea Actions 三阶段 CI 模板（语法兼容 GitHub Actions） + +### 💭 DeepSeek CI review 集成（可选插件） +- status: concept +- complexity: L +- acceptance: TBD —— 静态检查 + 测试自修 + PR review；作为复杂项目可选增配，不进基线档 + +### 💭 旧项目 GitHub → Gitea 迁移 +- status: concept +- complexity: M +- acceptance: TBD —— remote 切换 + 推送，安全增量，不丢历史 diff --git a/.blueprint/modules/github-auth.md b/.blueprint/modules/github-auth.md index 60deedb..8c1bbbc 100644 --- a/.blueprint/modules/github-auth.md +++ b/.blueprint/modules/github-auth.md @@ -1,10 +1,12 @@ --- id: github-auth name: GitHub OAuth -status: done +status: deprecated progress: 100 --- +> ❄️ **已冻结（2026-06-19）**：全面统一自建 Gitea，弃用 GitHub。功能保留不删，但不再演进；新接入走 onboarding-pack / gitea-integration 模块。 + ## 概述 GitHub OAuth Device Flow 认证，获取 token 后支持 API 操作和 Git 推送。 diff --git a/.blueprint/modules/github-publish.md b/.blueprint/modules/github-publish.md index 5fa152e..1ea1df5 100644 --- a/.blueprint/modules/github-publish.md +++ b/.blueprint/modules/github-publish.md @@ -1,5 +1,7 @@ # GitHub 发布 +> ❄️ **已冻结（2026-06-19）**：全面统一自建 Gitea，弃用 GitHub。功能保留不删，不再演进；项目发布走 Gitea（见 gitea-integration 模块）。 + 在炼境内通过 GitHub OAuth 直接将本地项目推送到远程仓库，支持新建仓库或关联已有仓库，完成发布后自动回填 remote URL。 ## 决策记录 diff --git a/.blueprint/modules/onboarding-pack.md b/.blueprint/modules/onboarding-pack.md new file mode 100644 index 0000000..b48d31e --- /dev/null +++ b/.blueprint/modules/onboarding-pack.md @@ -0,0 +1,94 @@ +# 接入包（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 后数据才准"