247 lines
11 KiB
Markdown
247 lines
11 KiB
Markdown
# 炼境 — 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 路由层 + 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/ 炼境接入包模板草案（设计层）
|
||
```
|
||
|
||
## 关键约定
|
||
|
||
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/` 内容一致吗？
|
||
|
||
<!-- BLUEPRINT_MANAGED_START version="1.10.0" -->
|
||
## 项目蓝图
|
||
|
||
本项目使用 `.blueprint/` 目录维护项目全景架构图，驱动需求讨论和任务管理。
|
||
本节适用于任何 AI 编程工具（Claude / Qwen / Cursor / Copilot 等）。
|
||
|
||
### 对话开始时必须执行
|
||
|
||
1. 读取 `.blueprint/manifest.yaml` 了解项目全景和当前状态
|
||
2. 读取 `.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`。
|
||
<!-- BLUEPRINT_MANAGED_END -->
|
||
|
||
<!-- ONBOARDING_MANAGED_START version="1.2.0" -->
|
||
## 核心开发约束
|
||
|
||
### 包管理
|
||
- **pnpm 唯一**：禁止 npm / yarn / npx / bun
|
||
- lock 文件只有 `pnpm-lock.yaml`，不生成其他
|
||
|
||
### 代码规范
|
||
- TypeScript 优先，避免 `any`
|
||
- 函数/变量 camelCase；组件 PascalCase
|
||
- 异步统一 `async/await`，不用裸 Promise 链
|
||
- 错误处理明确 `try/catch`，不吞异常
|
||
- 优先编辑现有文件，避免创建不必要的新文件
|
||
|
||
## Git 工作流
|
||
|
||
见 `docs/ai-context/git-workflow.md`（Conventional Commits + Rules-Applied trailer + PR 规范）。
|
||
**commit 必须符合 Conventional Commits**（lefthook 强制），炼境据此采集飞轮数据。
|
||
|
||
### 炼境自身的分支策略
|
||
|
||
> `git-workflow.md` 是分发给被管理子项目的接入包模板（dev→main 双分支）。
|
||
> 炼境自身使用以下策略，不套用子项目模板。
|
||
|
||
| 任务复杂度 | 分支策略 |
|
||
|-----------|---------|
|
||
| S（简单增删改） | 直接 push `master`，不开分支 |
|
||
| M（中等逻辑） | 开 `feat/<blueprint-module-id>` 分支，完成后 PR → `master` |
|
||
| L（复杂系统） | 开 `feat/<blueprint-module-id>` 分支，必须走 PR + CI 验证 |
|
||
|
||
**分支命名**：直接对应蓝图模块 ID，如 `feat/manage-multi-view`、`feat/flywheel-intelligence`。
|
||
|
||
**为什么 M/L 要开分支**：
|
||
- PR body 是 agent 自验报告的归宿，飞轮从中采集结构化数据（PR 事件比 push 事件包含更多意图信息）
|
||
- feat/* 分支触发 PR CI，是 agent 自验链条的最后一环（本地 typecheck → PR CI → 人终验）
|
||
- 炼境推荐子项目走 PR 工作流，自身也应遵守同一套规范
|
||
|
||
## agent 按钮与验证路径
|
||
|
||
> 完整体系设计见 `docs/ai-context/agent-button-system.md`。
|
||
|
||
**分工原则**：人定目标 → agent 执行 → agent 自验（走 agent 按钮）→ 人终验。
|
||
人只保留两件事：**需求澄清（目标定义权）** 和 **目标验收（终验权）**。
|
||
|
||
开发任何功能时遵守：
|
||
|
||
1. **边界单点实现**：业务校验只写在能力本体层（API/command），UI 只呈现不复制逻辑——
|
||
否则人与 agent 的验证路径会分裂
|
||
2. **载体就近选择**（本项目的 agent 按钮是什么，按项目类型对号入座）：
|
||
| 项目类型 | agent 按钮载体 |
|
||
|---------|---------------|
|
||
| Web 服务 | HTTP API 本身（前端按钮与 curl 调同一 endpoint，天然双投影） |
|
||
| CLI/脚本 | 命令与 npm scripts |
|
||
| 桌面应用 | 测试直接调用 command 函数 |
|
||
| UI 呈现层 | Playwright 驱动真界面（最后手段，仅关键路径） |
|
||
3. **完成的定义**：功能实现后，由 agent 沿投影路径真实走通一次（起服务 → 调接口 →
|
||
断言行为），再交人做 UI 终验——不许绕过功能手改产物冒充验证
|
||
4. **侦察 → 驻军**：agent 走通的关键路径，顺手固化为一条测试（vitest / cargo test）；
|
||
一次性验收不固化（少而稳 > 多而脆）
|
||
5. **acceptance 可执行化**：`/splitter` 生成任务卡时，`acceptance` 字段必须是可执行验证路径，
|
||
格式：`[载体] 调用/运行什么(参数) → 断言什么`。
|
||
- 正例：`[Tauri command] apply_onboarding_pack(project_id) → written≥1，文件在磁盘存在`
|
||
- 正例：`[HTTP API] POST /api/users → 201，body.id 非空`
|
||
- 反例：`功能正常可用`（模糊，agent 无法自验）
|
||
|
||
### 炼境自己的 Agent 按钮清单
|
||
|
||
| 能力 | 调用方式 | 通过标准 |
|
||
|------|---------|---------|
|
||
| TypeScript 类型检查 | `pnpm typecheck` | 无输出，exit 0 |
|
||
| 前端单元测试 | `pnpm test` | exit 0，无 FAILED |
|
||
| Rust 单元测试 | `cargo test`（src-tauri/ 目录） | 无 FAILED |
|
||
| MCP 工具调用 | 见 `src-tauri/src/mcp_tools.rs` 工具列表 | 返回 JSON，无 error 字段 |
|
||
| 蓝图状态读取 | 读 `.blueprint/manifest.yaml` | 文件可解析，字段完整 |
|
||
| 蓝图状态更新 | 编辑 `.blueprint/modules/<id>.md` | 文件写入成功，格式合法 |
|
||
|
||
### 自验失败降级约定
|
||
|
||
- **失败 2 次内**：自行修正，继续自验
|
||
- **失败 3 次**：停止执行，输出以下内容后等待人工介入：
|
||
1. 失败原因（具体报错或不通过的断言）
|
||
2. 已尝试的修正路径
|
||
3. 需要人决策的具体问题
|
||
|
||
## 多 AI CLI 协作
|
||
|
||
本项目可由多个 AI CLI 协同。交接时把结果总结成 3 条传给下一个：
|
||
|
||
```
|
||
1. 已完成：<改了哪些文件 + 核心决策>
|
||
2. 待验证：<需要确认的地方>
|
||
3. 约束继承：<影响后续的关键限制>
|
||
```
|
||
<!-- ONBOARDING_MANAGED_END -->
|