14 KiB
炼境 — 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 / TS 规范 / 需求对齐协议）见下方 ONBOARDING_MANAGED 块——单一事实来源，勿在此复抄。
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 路由层 + SSE 协议（agent 调用炼境的入口）
src-tauri/src/mcp_tools.rs MCP 工具 schema + dispatch + 实现（工具清单以 tools_list_result 为准）
src-tauri/src/mcp_webhook.rs Gitea webhook 处理（push/PR 事件写入飞轮）
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/ 炼境接入包模板草案（设计层）
关键约定
- 新增 Tauri command → 必须同步更新
src/lib/commands.ts，否则前端无法调用 - SQLite 新增表或字段 → 必须在
db.rs的migrate()里补 migration 语句，否则旧版本升级后启动报错 - 修改接入包模板（
resources/onboarding/）→ 检查docs/templates/agents-meta-rules.md是否需要同步
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/内容一致吗？
项目蓝图
本项目使用 .blueprint/ 目录维护项目全景架构图，驱动需求讨论和任务管理。
本节适用于任何 AI 编程工具（Claude / Qwen / Cursor / Copilot 等）。
对话开始时必须执行
- 读取
.blueprint/manifest.yaml了解项目全景和当前状态 - 读取
.blueprint/CONVENTIONS.md了解完整工作流规则
需求讨论 → 蓝图同步规则
| 用户说的 | AI 应做的 |
|---|---|
| "我想加个 XX 功能" | 确认需求后：manifest 新增模块（status: concept），创建 .blueprint/modules/<id>.md |
| "XX 功能需要 A、B、C" | 在模块文件中拆分为任务卡 |
| "这个方案确定了" | 模块 status → planned，补充任务卡 files/acceptance |
| "开始做 XX" | 模块 status → in_progress |
| 没提蓝图但在讨论功能 | 主动提议更新蓝图 |
复杂度决策（讨论新功能 / 拆解需求时）
| complexity | 执行流程 |
|---|---|
| S / M | 直接拆任务卡，确保每张卡有 files + acceptance + complexity → 标记 📋 |
| L（复杂系统设计） | 先做架构设计（Claude 用 /architect 技能，其他工具按 CONVENTIONS「复杂功能分析流程」章节执行）输出设计文档，用户确认后拆成 S/M 任务卡 |
L 级任务禁止直接写代码，必须先经过 架构设计 → 任务拆解 流程。
任务执行两阶段提交
- 开始写代码前：任务卡前缀改为 🔵，status → in_progress
- 完成验收后：任务卡前缀改为 ✅，status → done，更新 manifest
updated日期
完整规则（迭代管理、阻塞处理、复盘笔记等）详见 .blueprint/CONVENTIONS.md。
⚠️ 本块由炼境版本化托管，升级时整块原位覆盖——项目定制请写到块外，块内手改必丢（2026-07-15 炼境自身实锤丢失 5 段定制后新增本警示）。
核心开发约束
包管理
- pnpm 唯一：禁止 npm / yarn / npx / bun
- lock 文件只有
pnpm-lock.yaml，不生成其他
代码规范
- TypeScript 优先，避免
any - 函数/变量 camelCase；组件 PascalCase
- 异步统一
async/await，不用裸 Promise 链 - 错误处理明确
try/catch，不吞异常 - 优先编辑现有文件，避免创建不必要的新文件
- Playwright 版本固定：
package.json里的playwright锁死版本号，去掉^； 另建test:install脚本显式安装浏览器（playwright install --with-deps）， 升级时有意识操作，避免 pnpm install 静默触发 ~200MB 的浏览器重下
需求对齐协议
开始写代码前，先判断改动类型：
Bug Fix（当前行为与预期的意外偏差） → 建任务卡，直接执行，无需等确认词。
Feature / 行为变更（新增能力或主动改变已有行为） → 必须先输出确认卡，等用户说「确认」再动手：
- S 级（单文件、行为对外无变化，任务卡 complexity=S）：输出三行轻量卡
改哪：<文件或模块> 改什么：<一句话> 验收：<agent_verify 路径> - M / L 级：输出完整任务卡（含
files+acceptance+complexity），等确认
边界模糊时：保守判断，按 Feature 处理，走完整确认卡。
提交时：feat: 提交须在 commit message 末尾加 Feature-Confirmed: true trailer（lefthook commit-msg 强制检查）。这是确认卡已输出的机器层存证。
⚠️ Session 结束汇总补录 ≠ 确认卡替代——补录仅适用于漂移检测触发后用户主动选择补录的场景，不得作为「先做再补」的通道。
Git 工作流
见 docs/ai-context/git-workflow.md（分支策略 + Conventional Commits + Rules-Applied trailer + PR 规范）。
commit 必须符合 Conventional Commits（lefthook 强制），炼境据此采集飞轮数据。
agent 按钮与验证路径
功能的本体是代码层的能力；UI 按钮是它给人的投影，agent 按钮是给 agent 的投影 （可发现 + 可调用 + 有边界的能力声明）。开发任何功能时遵守：
-
边界单点实现：业务校验只写在能力本体层（API/command），UI 只呈现不复制逻辑—— 否则人与 agent 的验证路径会分裂
-
载体就近选择（本项目的 agent 按钮是什么，按项目类型对号入座）：
项目类型 agent 按钮载体 Web 服务 HTTP API 本身（前端按钮与 curl 调同一 endpoint，天然双投影） CLI/脚本 命令与 npm scripts 桌面应用 测试直接调用 command 函数 UI 呈现层 Playwright 驱动真界面（最后手段，仅关键路径） -
完成的定义：功能实现后，由 agent 沿投影路径真实走通一次（起服务 → 调接口 → 断言行为），再交人做 UI 终验——不许绕过功能手改产物冒充验证
-
侦察 → 驻军：agent 走通的关键路径，顺手固化为一条测试（桌面应用用 cargo test；Web 项目纯逻辑层用 vitest）； 一次性验收不固化（少而稳 > 多而脆）
-
acceptance 可执行化：
/splitter生成任务卡时，acceptance字段必须是可执行验证路径， 格式：[载体] 调用/运行什么(参数) → 断言什么。- 正例：
[Tauri command] apply_onboarding_pack(project_id) → written≥1，文件在磁盘存在 - 正例：
[HTTP API] POST /api/users → 201，body.id 非空 - 反例：
功能正常可用（模糊，agent 无法自验）
分层原则：凡含 UI 操作路径的 acceptance，必须拆成两段：
agent_verify:— 机器可断言（HTTP 状态码、数据库记录、函数返回值）；stop hook / CI 只验此段human_verify:— 需人眼判断（视觉效果、拖拽手势、30 秒浏览器终验） 纯 API / 命令行任务可省略human_verify:；UI 拖拽 / 动画 / 视觉类必须拆，否则 stop hook 无法收敛。
- 正例：
-
自验报告纪律：交人终验前的反馈必须含「没验什么」一节（未覆盖的路径、依赖的 假设、不确定的地方）；自修过程中改了断言/验收标准必须显式声明理由（改功能让测试过是 常规，改测试让功能过需报备）；agent 自验对 acceptance，人终验对意图——acceptance 可能继承需求理解偏差，两把尺子不可合一
多 AI CLI 协作
本项目可由多个 AI CLI 协同。交接时把结果总结成 3 条传给下一个：
1. 已完成：<改了哪些文件 + 核心决策>
2. 待验证：<需要确认的地方>
3. 约束继承：<影响后续的关键限制>
炼境自身约定（块外区——托管块升级不会触碰本节）
⚠️ 教训（2026-07-15）：本地定制严禁写进 MANAGED 块内——块会被版本升级原位覆盖。 本节内容曾因写在块内被 v1.6.0 升级抹掉，现恢复至块外。
炼境自身的分支策略
块内 git-workflow 是分发给子项目的通用策略；炼境自身按下表执行。
| 任务复杂度 | 分支策略 |
|---|---|
| S（简单增删改） | 直接 push master，不开分支 |
| M（中等逻辑） | 开 feat/<blueprint-module-id> 分支，完成后 PR → master |
| L（复杂系统） | 开 feat/<blueprint-module-id> 分支，必须走 PR + CI 验证 |
分支命名：直接对应蓝图模块 ID，如 feat/manage-multi-view；同名旧分支已存在时加卡号后缀（如 feat/onboarding-pack-u1）。
为什么 M/L 要开分支：
- PR body 是 agent 自验报告的归宿，飞轮从中采集结构化数据（PR 事件比 push 事件包含更多意图信息）
- feat/* 分支触发 PR CI，是 agent 自验链条的最后一环（本地 typecheck → PR CI → 人终验）
- 炼境推荐子项目走 PR 工作流，自身也应遵守同一套规范
分工原则
人定目标 → agent 执行 → agent 自验（走 agent 按钮）→ 人终验。
人只保留两件事：需求澄清（目标定义权） 和 目标验收（终验权）。
完整体系设计见 docs/ai-context/agent-button-system.md。
炼境自己的 Agent 按钮清单
| 能力 | 调用方式 | 通过标准 |
|---|---|---|
| TypeScript 类型检查 | pnpm typecheck |
无输出，exit 0 |
| Rust 单元测试 | cargo test（src-tauri/ 目录） |
无 FAILED |
| MCP 工具调用 | 见 src-tauri/src/mcp_tools.rs 工具列表 |
返回 JSON，无 error 字段 |
| 蓝图状态读取 | 读 .blueprint/manifest.yaml |
文件可解析，字段完整 |
| 蓝图状态更新 | 编辑 .blueprint/modules/<id>.md |
文件写入成功，格式合法 |
自验失败降级约定
- 失败 2 次内：自行修正，继续自验
- 失败 3 次：停止执行，输出以下内容后等待人工介入：
- 失败原因（具体报错或不通过的断言）
- 已尝试的修正路径
- 需要人决策的具体问题