docs(blueprint): agent 友好基础设施方案 + 炼境自身接入包 + 蓝图规范 v1.8.0

- 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
2026-06-29 16:38:45 +09:00 · 2026-06-29 16:38:45 +09:00 · 0552180e45
commit 0552180e45
parent ecb5620abb
15 changed files with 588 additions and 28 deletions
--- 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
    └── <module-id>.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/<id>.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/<id>.md 中的每个二级标题（`###`）是一张任务卡：
 详细说明（可选）。
 ```

-> **files 回填规则**：任务卡的 `files` 在规划时填入预期路径。实现完成后，若实际文件与规划有出入（合并、拆分、重命名），须在标记 ✅ done 之前将 `files` 更新为实际路径——这保证下次续接或派发时上下文准确。
-
 ### 状态前缀

 | 前缀 | status | 含义 |
@ -95,9 +113,10 @@ modules/<id>.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/<id>.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/<id>.md`
 4. 更新 `manifest.yaml`：status → `planned`，更新 `updated` 日期
 5. 输出拆解摘要（卡名、complexity、执行顺序）

 ### 质量检查
- [ ] 每张卡有 `files`
 - [ ] 每张卡有 `acceptance`
 - [ ] complexity 全部是 S 或 M
 - [ ] 有依赖的卡填了 `depends`
 - [ ] 任务卡按执行顺序排列
+- [ ] `files` 尽量填入（建议项，有则帮助 agent 更快定位）

 ---

--- 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
--- a/.blueprint/modules/agent-infrastructure.md
+++ 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
--- 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 信号推断，蓝图不手动双写。

 ## 接入包分档（底座统一，上层按需）

--- a/.claude/rules/db-schema.md
+++ b/.claude/rules/db-schema.md
@ -0,0 +1,4 @@
+---
+globs: src-tauri/src/db.rs
+---
+修改 `db.rs` 新增表或字段时，确认已在 `migrate()` 函数中补充对应 migration 语句；缺失会导致旧版本用户升级后启动报错（对应蓝图 R05 规则）。
--- a/.claude/rules/onboarding-sync.md
+++ b/.claude/rules/onboarding-sync.md
@ -0,0 +1,4 @@
+---
+globs: src-tauri/resources/onboarding/**
+---
+修改接入包模板时，检查 `docs/templates/agents-meta-rules.md` 是否需要同步更新——两者描述同一套元规则，必须保持一致（单一事实来源：tmpl 是分发实体，docs/templates/ 是设计草案）。
--- a/.claude/rules/tauri-contract.md
+++ b/.claude/rules/tauri-contract.md
@ -0,0 +1,4 @@
+---
+globs: src-tauri/src/commands/**
+---
+新增或修改 Tauri command 时，检查 `src/lib/commands.ts` 是否有对应前端封装；缺失则补写，否则前端无法调用（对应蓝图 R01 规则）。
--- a/AGENTS.md
+++ 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/` 内容一致吗？
--- 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/<id>.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` 流程。
--- a/docs/ai-context/project-brief.md
+++ 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/ 目录下运行）
+```
--- a/docs/ai-context/project-context.yaml
+++ 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"
--- a/docs/templates/agents-meta-rules.md
+++ 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` 的契约路径还准确吗？
--- a/docs/templates/project-brief.md.tmpl
+++ b/docs/templates/project-brief.md.tmpl
@ -0,0 +1,44 @@
+# <!-- 项目名 --> — 速查卡
+
+> 由炼境接入包生成。请补全 TODO 段落后提交到仓库。
+> 目标：新 agent 30 秒内能定向，不超过 300 字。
+
+**定位**：<!-- TODO: 一句话描述项目定位和核心功能 -->
+
+## 技术栈
+
+| 层 | 技术 |
+|----|------|
+<!-- TODO: 填入技术栈，例：
+| 前端 | React 19 + TypeScript |
+| 后端 | Node.js + Hono |
+| 数据 | PostgreSQL + Drizzle ORM |
+| 包管理 | pnpm |
+-->
+
+## 关键约定（改代码前必看）
+
+<!-- TODO: 列出 3-5 条最重要的开发约束，例：
+1. **类型单一来源**：跨模块共享类型只在 `packages/types/` 定义
+2. **ORM 唯一**：使用 Drizzle，禁止 Prisma
+3. **API 层禁止写统计逻辑**：一律用 SQL view
+-->
+
+## 目录速查
+
+```
+<!-- TODO: 列出关键目录及职责，例：
+src/routes/          API 路由
+src/types/           共享类型（单一来源）
+drizzle/schema.ts    数据库 schema
+-->
+```
+
+## 验收命令
+
+```bash
+# TODO: 填入项目的一键验证命令
+# pnpm typecheck    # 类型检查
+# pnpm test         # 测试
+# pnpm lint         # lint
+```
--- a/docs/templates/project-context.yaml.tmpl
+++ 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"
--- a/src-tauri/resources/onboarding/AGENTS.md.tmpl
+++ b/src-tauri/resources/onboarding/AGENTS.md.tmpl
@ -42,3 +42,62 @@
 ## 关键文档索引

 <!-- TODO: 列出 README / ARCHITECTURE.md / 其他关键文档及用途。 -->
+
+---
+
+## 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` 的契约路径还准确吗？