lanrtop/dev-manager-tauri
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
lanrtop 2026-06-29 16:38:45 +09:00
parent ecb5620abb
commit 0552180e45
15 changed files with 588 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
.blueprint/CONVENTIONS.md
View File

@ -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 更快定位）
---

18
.blueprint/manifest.yaml
View File

@ -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

104
.blueprint/modules/agent-infrastructure.md Normal file
View File

@ -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

6
.blueprint/modules/onboarding-pack.md
View File

@ -12,11 +12,9 @@
## 蓝图重新定位（git 与蓝图分工）
git 是「过去时 + 量化」（做了什么），蓝图是「将来时 + 语义」（为什么这么做 + 怎样算做完），AGENTS.md 是「静态约定」（项目是什么 + 怎么动它）。
> 完整定义见 `.blueprint/CONVENTIONS.md` §「蓝图定位（意图层）」。
- **状态/进度交给 git 推断**：模块 status/progress 不再手动声明，由炼境读 commit 活动推断 + 人确认（消除双写负担）
- **蓝图只留 git 给不了的**：决策记录(WHY)、验收契约、踩坑根因、架构全景
- 蓝图分级：小项目可不要蓝图（AGENTS.md + git 足够）；长周期/多业务线项目才长出「瘦蓝图」
核心分工：git 记录「做了什么」，蓝图只保留 git 给不了的三类信息（结构关系图 / 意图与验收标准 / 未来规划）。状态/进度/涉及文件从 git 信号推断，蓝图不手动双写。
## 接入包分档（底座统一，上层按需）

4
.claude/rules/db-schema.md Normal file
View File

@ -0,0 +1,4 @@
---
globs: src-tauri/src/db.rs
---
修改 `db.rs` 新增表或字段时，确认已在 `migrate()` 函数中补充对应 migration 语句；缺失会导致旧版本用户升级后启动报错（对应蓝图 R05 规则）。

4
.claude/rules/onboarding-sync.md Normal file
View File

@ -0,0 +1,4 @@
---
globs: src-tauri/resources/onboarding/**
---
修改接入包模板时，检查 `docs/templates/agents-meta-rules.md` 是否需要同步更新——两者描述同一套元规则，必须保持一致（单一事实来源：tmpl 是分发实体，docs/templates/ 是设计草案）。

4
.claude/rules/tauri-contract.md Normal file
View File

@ -0,0 +1,4 @@
---
globs: src-tauri/src/commands/**
---
新增或修改 Tauri command 时，检查 `src/lib/commands.ts` 是否有对应前端封装；缺失则补写，否则前端无法调用（对应蓝图 R01 规则）。

111
AGENTS.md Normal file
View File

@ -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/` 内容一致吗？

10
CLAUDE.md
View File

@ -18,8 +18,12 @@ 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 + 模块详情 + 任务卡）
docs/ 部署和更新指南
.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` 流程。

41
docs/ai-context/project-brief.md Normal file
View File

@ -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/ 目录下运行）
```

36
docs/ai-context/project-context.yaml Normal file
View File

@ -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"

81
docs/templates/agents-meta-rules.md vendored Normal file
View File

@ -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` 的契约路径还准确吗？

44
docs/templates/project-brief.md.tmpl vendored Normal file
View File

@ -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
```

35
docs/templates/project-context.yaml.tmpl vendored Normal file
View File

@ -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"

59
src-tauri/resources/onboarding/AGENTS.md.tmpl
View File

@ -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` 的契约路径还准确吗？