From 0552180e4597a6b92912a6278e7ce83b9b2ce1a0 Mon Sep 17 00:00:00 2001 From: lanrtop Date: Mon, 29 Jun 2026 16:38:45 +0900 Subject: [PATCH] =?UTF-8?q?docs(blueprint):=20agent=20=E5=8F=8B=E5=A5=BD?= =?UTF-8?q?=E5=9F=BA=E7=A1=80=E8=AE=BE=E6=96=BD=E6=96=B9=E6=A1=88=20+=20?= =?UTF-8?q?=E7=82=BC=E5=A2=83=E8=87=AA=E8=BA=AB=E6=8E=A5=E5=85=A5=E5=8C=85?= =?UTF-8?q?=20+=20=E8=93=9D=E5=9B=BE=E8=A7=84=E8=8C=83=20v1.8.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CONVENTIONS.md v1.8.0：蓝图定位为意图层，files 字段变可选，status/progress 从 git 推断 - 新增 agent-infrastructure 模块（concept）：接入包 v2，扫描→确认→生成三件套 - AGENTS.md.tmpl 注入四支柱 + T1-T4 防腐元规则 - 炼境自身接入自己的包：AGENTS.md + docs/ai-context/ + .claude/rules/ - docs/templates/ 三件套模板：agents-meta-rules / project-brief / project-context --- .blueprint/CONVENTIONS.md | 47 +++++--- .blueprint/manifest.yaml | 18 ++- .blueprint/modules/agent-infrastructure.md | 104 ++++++++++++++++ .blueprint/modules/onboarding-pack.md | 6 +- .claude/rules/db-schema.md | 4 + .claude/rules/onboarding-sync.md | 4 + .claude/rules/tauri-contract.md | 4 + AGENTS.md | 111 ++++++++++++++++++ CLAUDE.md | 22 ++-- docs/ai-context/project-brief.md | 41 +++++++ docs/ai-context/project-context.yaml | 36 ++++++ docs/templates/agents-meta-rules.md | 81 +++++++++++++ docs/templates/project-brief.md.tmpl | 44 +++++++ docs/templates/project-context.yaml.tmpl | 35 ++++++ src-tauri/resources/onboarding/AGENTS.md.tmpl | 59 ++++++++++ 15 files changed, 588 insertions(+), 28 deletions(-) create mode 100644 .blueprint/modules/agent-infrastructure.md create mode 100644 .claude/rules/db-schema.md create mode 100644 .claude/rules/onboarding-sync.md create mode 100644 .claude/rules/tauri-contract.md create mode 100644 AGENTS.md create mode 100644 docs/ai-context/project-brief.md create mode 100644 docs/ai-context/project-context.yaml create mode 100644 docs/templates/agents-meta-rules.md create mode 100644 docs/templates/project-brief.md.tmpl create mode 100644 docs/templates/project-context.yaml.tmpl diff --git a/.blueprint/CONVENTIONS.md b/.blueprint/CONVENTIONS.md index cd2fc78..0253e1e 100644 --- a/.blueprint/CONVENTIONS.md +++ b/.blueprint/CONVENTIONS.md @@ -1,6 +1,6 @@ --- -version: 1.7.0 -updated: 2026-05-06 +version: 1.8.0 +updated: 2026-06-29 source: dev-manager-tauri --- @@ -22,6 +22,26 @@ source: dev-manager-tauri └── .md ← 每个模块的详情 + 任务卡 ``` +## 蓝图定位（意图层） + +蓝图只记录 git 永远无法自动产生的三类信息： + +| 类型 | 内容 | 为什么 git 做不到 | +|------|------|----------------| +| **结构** | 模块列表 + 关系图（dependency/related） | git 只知道文件，不知道模块意图和边界 | +| **意图** | 为什么做 + 验收标准 + 复杂度 + 复盘笔记 | commit 记录"做了什么"，不记录"为什么" | +| **规划** | concept / planned 方向 | 还没有代码，git 里什么都没有 | + +**不属于蓝图的**（交给 git 信号，蓝图不手动维护）： +- 任务状态（in_progress / done）→ 从 branch / commit 推断 +- 涉及文件（files）→ 从 git diff 读取，蓝图里为可选提示 +- 进度数字（progress）→ 从任务卡完成比例自动算 +- 更新时间（updated）→ 从 git log 读取 + +> 蓝图是项目的"架构意图层"，不是任务追踪系统。任务追踪的职责交还给 git。 + +--- + ## 何时更新蓝图 | 事件 | 操作 | @@ -69,7 +89,7 @@ modules/.md 中的每个二级标题（`###`）是一张任务卡： ### 📋 任务标题 - status: todo - complexity: M -- files: src/path/to/file.tsx, src-tauri/src/commands/xxx.rs +- files: src/path/to/file.tsx（可选，规划时填预期路径；实际文件由 git diff 追踪，无需回填） - depends: other-module-id - acceptance: 简要描述完成标准 - blocked_reason: （仅 status: blocked 时填写）执行受阻的具体原因 @@ -79,8 +99,6 @@ modules/.md 中的每个二级标题（`###`）是一张任务卡： 详细说明（可选）。 ``` -> **files 回填规则**：任务卡的 `files` 在规划时填入预期路径。实现完成后，若实际文件与规划有出入（合并、拆分、重命名），须在标记 ✅ done 之前将 `files` 更新为实际路径——这保证下次续接或派发时上下文准确。 - ### 状态前缀 | 前缀 | status | 含义 | @@ -95,9 +113,10 @@ modules/.md 中的每个二级标题（`###`）是一张任务卡： 任务卡同时满足以下条件时标记为 📋： 1. status 为 `todo` -2. 有明确的 `files`（涉及哪些文件） -3. 有明确的 `acceptance`（验收标准） -4. complexity 为 `S` 或 `M` +2. 有明确的 `acceptance`（验收标准） +3. complexity 为 `S` 或 `M` + +`files` 为可选提示字段，有则帮助 agent 更快定位，无则从 git diff 推断，不作派发门槛。 不满足条件的 todo 任务保持无前缀，说明还需补充信息。 @@ -130,8 +149,8 @@ updated: YYYY-MM-DD - id: kebab-case-id # 唯一标识，同时是 modules/ 下的文件名 name: 显示名称 area: frontend # 所属领域 ID - status: done # done / in_progress / planned / concept - progress: 100 # 0~100，done 自动视为 100 + status: done # planned/concept 手动设；in_progress/done 优先从 git 信号推断，人工确认 + progress: 100 # 由任务卡完成比例自动算，无需手填；App 根据 done 卡比例渲染 position: [x, y] # React Flow 画布坐标（可选） ``` @@ -247,7 +266,7 @@ Claude 在每次对话中应遵循以下流程： |----------|--------------| | "我想加个 XX 功能" | 确认需求后：manifest 加模块 (status: concept)，创建 modules/.md | | "XX 功能需要 A、B、C 三步" | 在模块文件中拆分为 3 张任务卡 | -| "这个方案确定了" | 模块 status → planned，补充任务卡的 files/acceptance | +| "这个方案确定了" | 模块 status → planned，补充任务卡的 acceptance（files 可选，有则更准确） | | "开始做 XX" | 模块 status → in_progress | | "为什么选这个方案" | 记录到模块的 `## 决策记录` | @@ -402,7 +421,7 @@ rule_effectiveness: R10=未验证（任务开始前未触发，事后归因） } ``` -- `dispatched` = 当前满足📋可派发条件的任务数（有 files + acceptance + complexity S/M） +- `dispatched` = 当前满足📋可派发条件的任务数（有 acceptance + complexity S/M；files 可选） - 节流：同一 UTC 日期只写一条，避免多次打开导致数据膨胀 - 文件存于项目本地，不上传服务器 @@ -529,17 +548,17 @@ rule_effectiveness: R10=未验证（任务开始前未触发，事后归因） 2. 按以下原则拆解： - **粒度**：每张卡 complexity 必须是 S 或 M，不允许 L - **依赖顺序**：数据层 → 后端命令 → 前端封装 → UI 组件 - - **可派发标准**：每张卡必须有 `files` + `acceptance` + `complexity` + - **可派发标准**：每张卡必须有 `acceptance` + `complexity`；`files` 建议填入预期路径，有则更准确 3. 将任务卡追加到 `modules/.md` 4. 更新 `manifest.yaml`：status → `planned`，更新 `updated` 日期 5. 输出拆解摘要（卡名、complexity、执行顺序） ### 质量检查 -- [ ] 每张卡有 `files` - [ ] 每张卡有 `acceptance` - [ ] complexity 全部是 S 或 M - [ ] 有依赖的卡填了 `depends` - [ ] 任务卡按执行顺序排列 +- [ ] `files` 尽量填入（建议项，有则帮助 agent 更快定位） --- diff --git a/.blueprint/manifest.yaml b/.blueprint/manifest.yaml index 845a108..f254b75 100644 --- a/.blueprint/manifest.yaml +++ b/.blueprint/manifest.yaml @@ -6,7 +6,7 @@ description: > 成为每个项目的贴身导师。炼境本身亦被纳入其中， 形成可自我进化的开发智能闭环。 iteration: 1 -updated: 2026-06-19 +updated: 2026-06-29 @@ -378,6 +378,13 @@ modules: progress: 0 position: [3500, 150] + - id: agent-infrastructure + name: Agent 友好基础设施生成 + area: backend + status: concept + progress: 0 + position: [3750, 0] + edges: # 前端依赖 - from: workspace-mgmt @@ -601,6 +608,15 @@ edges: - from: onboarding-pack to: gitea-integration type: dependency + - from: onboarding-pack + to: agent-infrastructure + type: dependency + - from: devtools-scan + to: agent-infrastructure + type: dependency + - from: project-env-scan + to: agent-infrastructure + type: dependency - from: gitea-integration to: flywheel-intelligence type: related diff --git a/.blueprint/modules/agent-infrastructure.md b/.blueprint/modules/agent-infrastructure.md new file mode 100644 index 0000000..ef12ffd --- /dev/null +++ b/.blueprint/modules/agent-infrastructure.md @@ -0,0 +1,104 @@ +# Agent 友好基础设施生成 + +接入包 v2 的核心扩展：从"分发固定模板"升级为"根据技术栈定制生成 Agent 友好基础设施"。 +炼境扫描项目技术栈 → 用户确认 → 生成三件套（元规则 + 契约映射 + 工具派生格式）。 + +## 定位 + +现有接入包（v1）解决了"让项目被炼境感知"的问题。 +本模块解决"让 agent 在项目里真正高效工作"的问题。 + +两者的关系： +- v1 是注册入炼境飞轮的门票 +- v2 是项目内部 agent 工作环境的基础设施 + +## 生成的三件套 + +| 产物 | 用途 | 单一来源 | +|------|------|---------| +| `AGENTS.md`（元规则段落） | 跨工具通用的防腐约定 | 炼境统一版本，接入时写入 | +| `docs/ai-context/project-context.yaml` | 技术栈特定的契约路径映射 | 炼境扫描后生成，技术栈变更时重新生成 | +| `.claude/rules/doc-freshness.md` | Claude Code 的路径注入派生版 | 从 AGENTS.md 元规则自动派生 | + +## 接入流程（扫描 → 确认 → 生成） + +``` +① 炼境扫描 + package.json / Cargo.toml / go.mod / Dockerfile + → 识别框架、ORM、API 层、monorepo 结构 + +② 展示给用户确认（不跳过此步） + "检测到：React 19 + Drizzle（drizzle/schema.ts）+ Hono（src/routes/） + 是否正确？" + +③ 用户确认或手动修正 + +④ 定制化生成三件套 +``` + +## 技术栈 → 契约路径映射规则 + +炼境内置识别表（示例，可扩展）： + +| 识别条件 | 契约类型 | 默认路径 | +|---------|---------|---------| +| `prisma` in dependencies | 数据库 schema | `prisma/schema.prisma` | +| `drizzle-orm` in dependencies | 数据库 schema | `drizzle/schema.ts` | +| `hono` / `express` | API 接口 | `src/routes/**` | +| `openapi` / `swagger` | API 接口 | `openapi.yaml` | +| Rust + `axum` | API 接口 | `src/routes/` | +| pnpm workspace | 共享类型 | `packages/types/**` | + +## 腐化监控（接入后持续运行） + +炼境定期读取 git log，对比文档文件 vs 代码文件的最后修改时间： + +| 风险级别 | 判断条件 | +|---------|---------| +| 🟢 正常 | 文档与代码同步更新 | +| 🟡 注意 | 核心代码改了，文档 14 天未动 | +| 🔴 高风险 | 外部契约类文件改了，AGENTS.md 30 天未动 | + +技术栈变更感知：`package.json` / `Cargo.toml` 变化时主动提示"建议重新运行接入包生成"。 + +## 设计原则 + +- 元规则不含具体路径（技术栈无关），`project-context.yaml` 含路径（技术栈特定） +- 炼境生成，不要求用户手动维护多份格式 +- 修复腐化永远是本地 agent 的事，炼境只检测和提醒 + +## 决策记录 + +- 元规则选用四支柱 + T1-T4 触发类型的双层结构：四支柱给 agent 判断"这个项目 ok 吗"，T1-T4 给 agent 判断"这次改动需要更新什么" +- project-context.yaml 选 YAML 而非写进 AGENTS.md：技术栈映射是易变信息，独立文件符合防腐铁律（不写死进常驻文档） +- 确认步骤不可跳过：项目可能正在迁移技术栈，扫描结果不一定是当前权威状态 + +## 参考验证 + +2026-06-29 用 enterprise-system 做模拟验证： +- 技术栈识别准确（React + Drizzle + Hono + PostgreSQL） +- 最近 git log 有 "chore(db): 彻底移除 Prisma，全面统一 Drizzle"，完美复现 T3 工具链变更场景 +- project-context.yaml 不存在，验证了它需要炼境主动生成 +- .claude/rules/ 已有 6 个路径注入规则，验证了派生格式的可行性 + +## 任务卡 + +> 本模块为 L 级，需先走 /architect 设计再拆分。以下为 concept 阶段的方向记录。 + +### 💭 技术栈扫描与确认 UI +- status: concept + +### 💭 project-context.yaml 生成器 +- status: concept + +### 💭 AGENTS.md 元规则段落注入 +- status: concept + +### 💭 .claude/rules/ 派生生成 +- status: concept + +### 💭 腐化风险看板（文档新鲜度评分） +- status: concept + +### 💭 技术栈变更感知与重新生成提示 +- status: concept diff --git a/.blueprint/modules/onboarding-pack.md b/.blueprint/modules/onboarding-pack.md index 25abdc2..0f9a9ed 100644 --- a/.blueprint/modules/onboarding-pack.md +++ b/.blueprint/modules/onboarding-pack.md @@ -12,11 +12,9 @@ ## 蓝图重新定位（git 与蓝图分工） -git 是「过去时 + 量化」（做了什么），蓝图是「将来时 + 语义」（为什么这么做 + 怎样算做完），AGENTS.md 是「静态约定」（项目是什么 + 怎么动它）。 +> 完整定义见 `.blueprint/CONVENTIONS.md` §「蓝图定位（意图层）」。 -- **状态/进度交给 git 推断**：模块 status/progress 不再手动声明，由炼境读 commit 活动推断 + 人确认（消除双写负担） -- **蓝图只留 git 给不了的**：决策记录(WHY)、验收契约、踩坑根因、架构全景 -- 蓝图分级：小项目可不要蓝图（AGENTS.md + git 足够）；长周期/多业务线项目才长出「瘦蓝图」 +核心分工：git 记录「做了什么」，蓝图只保留 git 给不了的三类信息（结构关系图 / 意图与验收标准 / 未来规划）。状态/进度/涉及文件从 git 信号推断，蓝图不手动双写。 ## 接入包分档（底座统一，上层按需） diff --git a/.claude/rules/db-schema.md b/.claude/rules/db-schema.md new file mode 100644 index 0000000..ed70aea --- /dev/null +++ b/.claude/rules/db-schema.md @@ -0,0 +1,4 @@ +--- +globs: src-tauri/src/db.rs +--- +修改 `db.rs` 新增表或字段时，确认已在 `migrate()` 函数中补充对应 migration 语句；缺失会导致旧版本用户升级后启动报错（对应蓝图 R05 规则）。 diff --git a/.claude/rules/onboarding-sync.md b/.claude/rules/onboarding-sync.md new file mode 100644 index 0000000..aba7f1d --- /dev/null +++ b/.claude/rules/onboarding-sync.md @@ -0,0 +1,4 @@ +--- +globs: src-tauri/resources/onboarding/** +--- +修改接入包模板时，检查 `docs/templates/agents-meta-rules.md` 是否需要同步更新——两者描述同一套元规则，必须保持一致（单一事实来源：tmpl 是分发实体，docs/templates/ 是设计草案）。 diff --git a/.claude/rules/tauri-contract.md b/.claude/rules/tauri-contract.md new file mode 100644 index 0000000..0955d8a --- /dev/null +++ b/.claude/rules/tauri-contract.md @@ -0,0 +1,4 @@ +--- +globs: src-tauri/src/commands/** +--- +新增或修改 Tauri command 时，检查 `src/lib/commands.ts` 是否有对应前端封装；缺失则补写，否则前端无法调用（对应蓝图 R01 规则）。 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5130f17 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,111 @@ +# 炼境 — AI Agent 上下文 + +> 本文件遵循 [AGENTS.md 开放规范](https://agents.md/)，供 Claude Code、Qwen Code、Cursor、Copilot 等 AI 工具读取。 + +## 项目定位 + +Git 多空间开发管理器，同时也是**项目 Agent 化改造引擎**。 +以蓝图为神经系统，以 Claude 为智能层，感知所管理项目的功能运转、质量状态与成长方向。 +炼境本身亦被纳入其中，形成可自我进化的开发智能闭环。 + +## 技术栈 + +- 前端：React 19 + TypeScript + TailwindCSS + React Query + Zustand + React Flow +- 后端：Rust + Tauri v2 + SQLite（rusqlite + r2d2） +- MCP Server：内嵌于 Tauri 进程（HTTP），供 Claude Code 调用炼境数据 +- 包管理：pnpm（禁止 npm/yarn/npx/bun） + +## 核心开发约束 + +**包管理**：pnpm 唯一，禁止 npm / yarn / npx / bun。 + +**TypeScript**：优先 TypeScript，避免 `any`；函数/变量 camelCase，组件 PascalCase；async/await，不用裸 Promise 链；try/catch 不吞异常。 + +**Rust 业务函数**：禁止在函数内部调用 `pool().get()`，连接由调用方传入（依赖注入，便于 in-memory DB 测试）。Tauri command 层负责获取连接并调用（薄包装，无需测试）。 + +## 架构速查 + +``` +src/lib/commands.ts 所有 Tauri command 的前端封装（唯一调用入口） +src-tauri/src/commands/ Rust 后端实现（每功能一个 .rs 文件） +src-tauri/src/db.rs SQLite 建表 + migration 逻辑 +src-tauri/src/mcp_server.rs 内嵌 MCP Server（agent 调用炼境的入口） +src-tauri/src/mcp_inject.rs MCP 配置注入（写入被管理项目的 .claude/settings.json） +src-tauri/resources/onboarding/ 接入包分发模板（AGENTS.md/lefthook/git-workflow） +.blueprint/ 项目蓝图（manifest + 模块详情 + 任务卡） +docs/ai-context/ AI 上下文文档（速查卡、契约映射） +docs/templates/ 炼境接入包模板草案（设计层） +``` + +## 关键约定 + +1. **新增 Tauri command → 必须同步更新 `src/lib/commands.ts`**，否则前端无法调用 +2. **SQLite 新增表或字段 → 必须在 `db.rs` 的 `migrate()` 里补 migration 语句**，否则旧版本升级后启动报错 +3. **修改接入包模板（`resources/onboarding/`）→ 检查 `docs/templates/agents-meta-rules.md` 是否需要同步** + +## 多 AI CLI 协作 + +本项目可由多个 AI CLI 协同。交接时附上： + +``` +已完成：<修改了哪些文件 + 核心决策> +待验证：<需要对方确认的地方> +约束继承：<影响后续工作的关键限制> +``` + +--- + +## Agent 友好工程四支柱 + +修改代码前，确认这个项目满足四支柱： + +**可导航**：凭文件名/目录名可在 30 秒内定位某功能的代码。通用能力有独立家，不寄生在业务模块下。 + +**可推理**：公共类型只在一处定义。改一个接口，类型检查能报出所有受影响处。 + +**可验证**：typecheck / lint / test 各有一条命令真能跑。关键路径有冒烟测试。 + +**可记忆**：规则按场景注入（不是一份巨型文档）。决策只写"为什么"，代码自己回答"是什么"。 + +--- + +## 文档防腐元规则 + +做任何改动时，判断它属于哪类变更： + +### T1 外部契约变更（最高优先级） +其他代码、服务、或 agent 依赖的定义——Tauri command 接口、MCP 接口、数据库 schema、共享类型。 +→ 查 `docs/ai-context/project-context.yaml` 找到对应文档，检查并同步更新。 + +### T2 架构边界变更 +模块划分、目录结构、依赖方向、命令分组变化。 +→ 检查本文件架构速查和 `docs/ai-context/project-brief.md` 是否需要同步。 + +### T3 工具链变更 +引入或替换库、Tauri 版本升级、Rust 依赖变更。 +→ 更新本文件技术栈声明；更新 `docs/ai-context/project-context.yaml`。 + +### T4 常驻上下文过期 +本文件（AGENTS.md）或 `docs/ai-context/project-brief.md` 描述的现实已经改变。 +→ 立即更新。这两份文档常驻 agent 上下文，过期危害最大。 + +### 不触发检查 +内部重构、性能优化、bug fix（外部行为不变）、测试文件、UI 样式调整。 + +--- + +## 文档防腐铁律 + +- 文档只写稳定的：为什么、铁律、意图、架构决策。 +- 易变的（端口、表名、命令清单）交给工具自省，不写死进常驻文档。 +- 单一事实来源：两处说同一事时，删掉派生的那处。 +- 两份文档打架时，信代码，不信文档。 + +--- + +## 定期防腐自查 + +- [ ] 技术栈声明还和 `package.json` / `Cargo.toml` 一致吗？ +- [ ] `project-brief.md` 最近 30 天有没有随架构改动更新？ +- [ ] `src/lib/commands.ts` 的封装覆盖了所有 `src-tauri/src/commands/` 下的 command 吗？ +- [ ] 接入包模板（`resources/onboarding/`）和 `docs/templates/` 内容一致吗？ diff --git a/CLAUDE.md b/CLAUDE.md index 2f46f87..9bde7af 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,13 +13,17 @@ Git 多空间开发管理器，Tauri v2 + React + TypeScript + Rust。 ## 目录结构 ``` -src/ 前端源码 -src/components/ React 组件（按功能分目录） -src/lib/commands.ts Tauri command 调用封装 -src-tauri/src/ Rust 后端 -src-tauri/src/commands/ Tauri command 实现 -.blueprint/ 项目蓝图（manifest + 模块详情 + 任务卡） -docs/ 部署和更新指南 +src/ 前端源码 +src/components/ React 组件（按功能分目录） +src/lib/commands.ts Tauri command 调用封装 +src-tauri/src/ Rust 后端 +src-tauri/src/commands/ Tauri command 实现 +src-tauri/resources/onboarding/ 接入包分发模板（AGENTS.md、git-workflow、lefthook） +.blueprint/ 项目蓝图（manifest + 模块详情 + 任务卡） +.claude/rules/ 路径注入规则（tauri-contract / db-schema / onboarding-sync） +AGENTS.md 跨工具 AI 上下文（四支柱 + 元规则，单一来源） +docs/ai-context/ AI 速查文档（project-brief.md、project-context.yaml） +docs/templates/ 炼境接入包模板草案（agents-meta-rules 等） ``` ## 命令执行规则 @@ -59,7 +63,7 @@ docs/ 部署和更新指南 |----------|--------------| | "我想加个 XX 功能" | 确认需求后：manifest 新增模块（status: concept），创建 `.blueprint/modules/.md` | | "XX 功能需要 A、B、C" | 在模块文件中拆分为任务卡 | -| "这个方案确定了" | 模块 status → planned，补充任务卡 files/acceptance | +| "这个方案确定了" | 模块 status → planned，补充任务卡 acceptance（files 可选） | | "开始做 XX" | 模块 status → in_progress | | 没提蓝图但在讨论功能 | 主动提议更新蓝图 | @@ -67,7 +71,7 @@ docs/ 部署和更新指南 | complexity | 执行流程 | |-----------|---------| -| S / M | 直接拆任务卡，确保每张卡有 `files` + `acceptance` + `complexity` → 标记 📋 | +| S / M | 直接拆任务卡，确保每张卡有 `acceptance` + `complexity` → 标记 📋（`files` 可选） | | L（复杂系统设计） | 先 `/architect` 输出设计文档，用户确认后 `/splitter` 拆成 S/M 任务卡 | > L 级任务禁止直接写代码，必须先经过 `/architect` → `/splitter` 流程。 diff --git a/docs/ai-context/project-brief.md b/docs/ai-context/project-brief.md new file mode 100644 index 0000000..2c61753 --- /dev/null +++ b/docs/ai-context/project-brief.md @@ -0,0 +1,41 @@ +# 炼境 — 速查卡 + +**定位**：Git 多空间开发管理器 + 项目 Agent 化改造引擎。Tauri v2 桌面 App，管理多个开发项目，为每个项目注入 Agent 友好基础设施，形成智能成长飞轮。 + +## 技术栈 + +| 层 | 技术 | +|----|------| +| 前端 | React 19 + TypeScript + TailwindCSS + React Query + Zustand + React Flow | +| 后端 | Rust + Tauri v2 | +| 数据 | SQLite（rusqlite + r2d2） | +| MCP | 内嵌 HTTP Server（供 Claude Code 调用） | +| 包管理 | pnpm | + +## 关键约定（改代码前必看） + +1. **Tauri command ↔ 前端封装**：新增 command 必须同步更新 `src/lib/commands.ts` +2. **DB 变更必须有 migration**：在 `src-tauri/src/db.rs` 的 `migrate()` 里补语句，否则旧版本升级报错 +3. **Rust 业务函数依赖注入**：禁止内部 `pool().get()`，连接由调用方传入 +4. **接入包模板 = 分发给被管理项目的规则**：改 `resources/onboarding/` 务必同步 `docs/templates/` + +## 目录速查 + +``` +src/lib/commands.ts 前后端契约（唯一前端入口） +src-tauri/src/commands/ Rust 后端实现（一功能一文件） +src-tauri/src/db.rs 数据库 schema + migration +src-tauri/src/mcp_server.rs MCP Server（agent 调用炼境的入口） +src-tauri/resources/onboarding/ 接入包分发模板 +.blueprint/ 项目蓝图 +docs/ai-context/ AI 上下文文档（本文件、契约映射） +docs/templates/ 接入包模板草案（设计层） +``` + +## 验收命令 + +```bash +pnpm typecheck # TypeScript 类型检查 +pnpm tauri dev # 启动开发环境 +cargo test # Rust 单元测试（src-tauri/ 目录下运行） +``` diff --git a/docs/ai-context/project-context.yaml b/docs/ai-context/project-context.yaml new file mode 100644 index 0000000..4088f68 --- /dev/null +++ b/docs/ai-context/project-context.yaml @@ -0,0 +1,36 @@ +# 炼境契约路径映射 +# 炼境自身版本，手工维护（等 agent-infrastructure 模块完成后由炼境自动生成） +# 供 AGENTS.md 元规则 T1 查询：「哪个文件是这个项目的契约？」 + +contracts: + - label: Tauri command 接口（前后端契约） + paths: + - "src-tauri/src/commands/**/*.rs" + - "src/lib/commands.ts" + doc: "新增 command 时两端必须同步；src/lib/commands.ts 是唯一前端调用入口" + + - label: 数据库 schema + paths: + - "src-tauri/src/db.rs" + doc: "SQLite 表结构变更必须在 migrate() 函数中补 migration 语句" + + - label: MCP Server 接口 + paths: + - "src-tauri/src/mcp_server.rs" + - "src-tauri/src/mcp_inject.rs" + doc: "MCP 接口变更影响 Claude Code 对炼境的调用，接口路由和参数需同步" + + - label: 接入包分发模板 + paths: + - "src-tauri/resources/onboarding/**" + doc: "模板变更需同步检查 docs/templates/agents-meta-rules.md（设计层来源）" + + +architecture_docs: + - "AGENTS.md" + - "CLAUDE.md" + - ".blueprint/manifest.yaml" + +agent_docs: + - "AGENTS.md" + - "docs/ai-context/project-brief.md" diff --git a/docs/templates/agents-meta-rules.md b/docs/templates/agents-meta-rules.md new file mode 100644 index 0000000..cbea47b --- /dev/null +++ b/docs/templates/agents-meta-rules.md @@ -0,0 +1,81 @@ +--- +version: 1.0.0 +updated: 2026-06-29 +usage: 炼境接入包分发时写入被管理项目 AGENTS.md 的元规则标准内容 +--- + +# Agent 友好工程元规则 + +> 本节由炼境接入包分发，规则技术栈无关，适用于所有项目和所有 AI 工具。 +> 项目特定的路径映射见 `docs/ai-context/project-context.yaml`。 + +--- + +## Agent 友好工程四支柱 + +修改代码前，确认这个项目满足四支柱： + +**可导航**：凭文件名/目录名可在 30 秒内定位某功能的代码。通用能力有独立家，不寄生在业务模块下。 + +**可推理**：公共类型只在一处定义。改一个接口，类型检查能报出所有受影响处。 + +**可验证**：typecheck / lint / test 各有一条命令真能跑。关键路径有冒烟测试。 + +**可记忆**：规则按场景注入（不是一份巨型文档）。决策只写"为什么"，代码自己回答"是什么"。 + +--- + +## 文档防腐元规则 + +做任何改动时，判断它属于哪类变更： + +### T1 外部契约变更（最高优先级） +其他代码、服务、或 agent 依赖的定义——接口、共享类型、数据结构、配置键名、环境变量名。 +→ 查 `docs/ai-context/project-context.yaml` 找到记录该契约的文档，检查并同步更新。 + +### T2 架构边界变更 +模块划分、目录结构、依赖方向、包边界调整。 +→ 检查架构文档是否需要同步。 + +### T3 工具链变更 +引入或替换库、框架、构建工具。 +→ 更新 AGENTS.md 技术栈声明；通知炼境重新扫描并更新 `project-context.yaml`。 + +### T4 常驻上下文过期 +AGENTS.md 或 `docs/ai-context/project-brief.md` 描述的现实已经改变。 +→ 立即更新。这两份文档常驻 agent 上下文，过期危害最大。 + +### 不触发检查 +内部重构、性能优化、bug fix（外部行为不变）、测试文件、临时脚本。 + +--- + +## 文档防腐铁律 + +- 文档只写稳定的：为什么、铁律、意图、架构决策。 +- 易变的（端口、路由、表名、命令清单）交给工具自省，不写死进常驻文档。写死 = 定时炸弹。 +- 单一事实来源：两处说同一事时，删掉派生的那处。 +- 两份文档打架时，信代码，不信文档。 + +--- + +## 跨 AI 工具交接模板 + +完成一段工作并交接给下一个 agent 时，附上： + +``` +已完成：<修改了哪些文件 + 核心决策> +待验证：<需要对方确认的地方> +约束继承：<影响对方工作的关键限制> +``` + +--- + +## 定期防腐自查 + +每隔一阵或大改后，对照以下清单： + +- [ ] AGENTS.md 里的技术栈声明还和代码一致吗？ +- [ ] `project-brief.md` 最近 30 天有没有随架构改动更新？ +- [ ] 有没有两份文档说同一件事且打架？ +- [ ] `project-context.yaml` 的契约路径还准确吗？ diff --git a/docs/templates/project-brief.md.tmpl b/docs/templates/project-brief.md.tmpl new file mode 100644 index 0000000..39e86df --- /dev/null +++ b/docs/templates/project-brief.md.tmpl @@ -0,0 +1,44 @@ +# — 速查卡 + +> 由炼境接入包生成。请补全 TODO 段落后提交到仓库。 +> 目标：新 agent 30 秒内能定向，不超过 300 字。 + +**定位**： + +## 技术栈 + +| 层 | 技术 | +|----|------| + + +## 关键约定（改代码前必看） + + + +## 目录速查 + +``` + +``` + +## 验收命令 + +```bash +# TODO: 填入项目的一键验证命令 +# pnpm typecheck # 类型检查 +# pnpm test # 测试 +# pnpm lint # lint +``` diff --git a/docs/templates/project-context.yaml.tmpl b/docs/templates/project-context.yaml.tmpl new file mode 100644 index 0000000..6ed1fd3 --- /dev/null +++ b/docs/templates/project-context.yaml.tmpl @@ -0,0 +1,35 @@ +# 项目契约路径映射 +# 由炼境接入包根据技术栈扫描生成，用户确认后写入 +# 供 AGENTS.md 元规则 T1 查询：「哪个文件是这个项目的外部契约？」 +# 技术栈变更后重新运行接入包生成 + +# contracts 由炼境扫描技术栈后自动填入，也可手动补充。 +# 常见示例（取消注释并按实际修改）： +contracts: + # - label: 数据库 schema（Drizzle） + # paths: ["drizzle/schema.ts"] + # doc: "schema 变更需同步更新数据库文档" + # + # - label: 数据库 schema（Prisma） + # paths: ["prisma/schema.prisma"] + # doc: "schema 变更需同步更新数据库文档" + # + # - label: API 接口（Hono / Express） + # paths: ["src/routes/**"] + # doc: "接口变更需同步更新 API 文档或 openapi.yaml" + # + # - label: 共享类型 + # paths: ["packages/types/**", "src/types/**"] + # doc: "类型只在此处定义，禁止手抄到其他模块" + # + # - label: 环境变量声明 + # paths: [".env.example"] + # doc: "新增环境变量必须在 .env.example 中同步声明" + +architecture_docs: + - "AGENTS.md" + # - "ARCHITECTURE.md" + +agent_docs: + - "AGENTS.md" + - "docs/ai-context/project-brief.md" diff --git a/src-tauri/resources/onboarding/AGENTS.md.tmpl b/src-tauri/resources/onboarding/AGENTS.md.tmpl index 999e0cd..cf6d9c8 100644 --- a/src-tauri/resources/onboarding/AGENTS.md.tmpl +++ b/src-tauri/resources/onboarding/AGENTS.md.tmpl @@ -42,3 +42,62 @@ ## 关键文档索引 + +--- + +## Agent 友好工程四支柱 + +修改代码前，确认这个项目满足四支柱： + +**可导航**：凭文件名/目录名可在 30 秒内定位某功能的代码。通用能力有独立家，不寄生在业务模块下。 + +**可推理**：公共类型只在一处定义。改一个接口，类型检查能报出所有受影响处。 + +**可验证**：typecheck / lint / test 各有一条命令真能跑。关键路径有冒烟测试。 + +**可记忆**：规则按场景注入（不是一份巨型文档）。决策只写"为什么"，代码自己回答"是什么"。 + +--- + +## 文档防腐元规则 + +做任何改动时，判断它属于哪类变更： + +### T1 外部契约变更（最高优先级） +其他代码、服务、或 agent 依赖的定义——接口、共享类型、数据结构、配置键名、环境变量名。 +→ 查 `docs/ai-context/project-context.yaml`（若存在）找到记录该契约的文档，检查并同步更新。 + +### T2 架构边界变更 +模块划分、目录结构、依赖方向、包边界调整。 +→ 检查架构文档是否需要同步。 + +### T3 工具链变更 +引入或替换库、框架、构建工具。 +→ 更新本文件（AGENTS.md）技术栈声明；通知炼境重新扫描并更新 `project-context.yaml`。 + +### T4 常驻上下文过期 +本文件（AGENTS.md）或 `docs/ai-context/project-brief.md` 描述的现实已经改变。 +→ 立即更新。这两份文档常驻 agent 上下文，过期危害最大。 + +### 不触发检查 +内部重构、性能优化、bug fix（外部行为不变）、测试文件、临时脚本。 + +--- + +## 文档防腐铁律 + +- 文档只写稳定的：为什么、铁律、意图、架构决策。 +- 易变的（端口、路由、表名、命令清单）交给工具自省，不写死进常驻文档。写死 = 定时炸弹。 +- 单一事实来源：两处说同一事时，删掉派生的那处。 +- 两份文档打架时，信代码，不信文档。 + +--- + +## 定期防腐自查 + +每隔一阵或大改后，对照以下清单： + +- [ ] AGENTS.md 里的技术栈声明还和代码一致吗？ +- [ ] `docs/ai-context/project-brief.md` 最近 30 天有没有随架构改动更新？ +- [ ] 有没有两份文档说同一件事且打架？ +- [ ] `docs/ai-context/project-context.yaml` 的契约路径还准确吗？