dev-manager-tauri/AGENTS.md

炼境 — AI Agent 上下文

本文件遵循 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/ 内容一致吗？