<!-- 项目名 --> — AI Agent 上下文

> 本文件遵循 [AGENTS.md 开放规范](https://agents.md/)，供 Claude Code、Qwen Code、Cursor、Copilot 等 AI 工具读取。
> 由炼境接入包分发。请按项目实际补全下方 TODO 段落。
> `ONBOARDING_MANAGED` 标记块由炼境版本化管理（重跑接入包可原位升级），块外内容永不触碰。

## 项目概况

<!-- TODO: 一句话描述项目 + 技术栈。例：pnpm monorepo，React 19 + TypeScript 前端 + Hono API。 -->
<!-- TODO: 在 .blueprint/manifest.yaml 顶层补 agent_button_carrier（tauri/http/cli/playwright），
          splitter 生成任务卡时直接从此字段继承验证载体。参考 .blueprint/CONVENTIONS.md §manifest.yaml规范。 -->

## 架构与模块

<!-- TODO: 列出主要目录/模块及职责，帮助 AI 快速定位「改哪里」。 -->

## 关键文档索引

<!-- TODO: 列出 README / ARCHITECTURE.md / 其他关键文档及用途。 -->

<!-- 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 强制），炼境据此采集飞轮数据。

## agent 按钮与验证路径

功能的本体是代码层的能力；UI 按钮是它给人的投影，**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 走通的关键路径，顺手固化为一条测试（桌面应用用 cargo test；Web 项目纯逻辑层用 vitest）；
   一次性验收不固化（少而稳 > 多而脆）
5. **acceptance 可执行化**：`/splitter` 生成任务卡时，`acceptance` 字段必须是可执行验证路径，
   格式：`[载体] 调用/运行什么(参数) → 断言什么`。
   - 正例：`[Tauri command] apply_onboarding_pack(project_id) → written≥1，文件在磁盘存在`
   - 正例：`[HTTP API] POST /api/users → 201，body.id 非空`
   - 反例：`功能正常可用`（模糊，agent 无法自验）

## 多 AI CLI 协作

本项目可由多个 AI CLI 协同。交接时把结果总结成 3 条传给下一个：

```
1. 已完成：<改了哪些文件 + 核心决策>
2. 待验证：<需要确认的地方>
3. 约束继承：<影响后续的关键限制>
```
<!-- ONBOARDING_MANAGED_END -->

---

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