# Agent 工作手册（通用）

> 本文件与具体业务仓库无关，可整文件复用到其他项目。  
> **本仓库差异化约定见 [PROJECT.md](./PROJECT.md)。**

---

## 1. 目的与适用范围

- 适用于在本仓库工作的所有编码 Agent（Cursor、Claude Code、Codex、Kimi、Antigravity 等）。
- **聊天记录易失**；Git 与活文档区才是可协作、可审计的真相来源。
- 任何任务、调研、审计、修复、运维操作均须同步落盘，禁止「只改代码 / 只留在对话」。

---

## 2. 启动协议（Session Bootstrap）

每次会话开始，按顺序阅读：

1. **本文件** `AGENTS.md`
2. **[PROJECT.md](./PROJECT.md)**（本仓库地图与约定）
3. **[`.doc/README.md`](./.doc/README.md)**（文档 taxonomy）
4. **[`.doc/ops/CURRENT.md`](./.doc/ops/CURRENT.md)**（焦点、并行认领、集成槽位）
5. **[`.doc/status/FEATURE-MATRIX.md`](./.doc/status/FEATURE-MATRIX.md)**（模块完成度）
6. 相关 **short-term** / **handoff** / **audit** / **remediation**
7. 发布/审计类任务：[`remediation/gap-matrix.md`](./.doc/remediation/gap-matrix.md)

**未读完不得开始改代码**（紧急热修除外，事后必须在 24h 内补文档）。

---

## 3. 文档同步红线（强制）

| 时机 | 必须动作 |
|------|----------|
| 任务开始 | 在 `short-term/` 或 `long-term/` 新建或更新条目（复制 templates） |
| 认领 | 在 CURRENT「并行认领」表登记 owner / branch / mutex |
| 合 dev + 容器测 | 占用 CURRENT「集成槽位」；他人排队 |
| 里程碑 | 更新任务文 `status`、FEATURE-MATRIX、CURRENT |
| 调研/审计 | 写入 `audit/` 或 `ops/research/` |
| 整改方案 | 写入 `remediation/` |
| 验收 | 写 test-report（路径见 PROJECT），回链 checklist |
| 会话结束/切换 Agent | 按 [session-close-checklist](./.doc/ops/templates/session-close-checklist.md) |
| 提交 | 文档变更与代码同批或紧随 `docs(...)` 提交 |

**状态字段**：`planned | in_progress | blocked | done | cancelled`

**current vs historical**：完成项标 `done` 并移入 `archive/`；不删除证据。

---

## 4. 文档 taxonomy

默认路径：`.doc/`（详见 [`.doc/README.md`](./.doc/README.md)）

```text
.doc/
  README.md           # 总地图
  status/             # FEATURE-MATRIX（模块完成度 SSOT）
  audit/              # 问题发现与分析
  remediation/        # 整改方案；gap-matrix（发布 blocker）
  archive/            # 历史（只增不删）
  ops/                # 活协作：CURRENT、short-term、handoffs…
  system-design/      # 模块架构深读
  adr/ | backlog/ | test-reports/ | test-fixtures/
```

**红线**：禁止在 `.doc/` 根或 `docs/` 随意新建项目文档；新文档必须落入 taxonomy。

**命名**：`YYYY-MM-DD-<slug>.md`

---

## 5. 文档类型与何时使用

| 类型 | 路径 | 模板 |
|------|------|------|
| 问题/分析 | `audit/` | [audit-note.md](./.doc/ops/templates/audit-note.md) |
| 整改方案 | `remediation/` | [remediation-plan.md](./.doc/ops/templates/remediation-plan.md) |
| 短期任务 | `ops/short-term/` | [short-term-task.md](./.doc/ops/templates/short-term-task.md) |
| 长期 backlog | `ops/long-term/` | [long-term-task.md](./.doc/ops/templates/long-term-task.md) |
| Checklist | `ops/checklists/` | [checklist.md](./.doc/ops/templates/checklist.md) |
| 交接 | `ops/handoffs/` | [handoff.md](./.doc/ops/templates/handoff.md) |
| 调研 | `ops/research/` | [research-note.md](./.doc/ops/templates/research-note.md) |
| 模块完成度 | `status/FEATURE-MATRIX.md` | [feature-matrix-row.md](./.doc/ops/templates/feature-matrix-row.md) |
| 验收报告 | `.doc/test-reports/` | 见 test-reports-standard |
| 历史 | `archive/**` | 关闭后迁入 |

---

## 6. 多 Agent 协作

### 6.1 并行认领（编码阶段）

任务开始前在 CURRENT「并行认领」表登记：

| 字段 | 说明 |
|------|------|
| owner | 工具 + 标识 |
| task | short-term 文件名 |
| branch | `feature/*` 或 `fix/*` |
| worktree | 路径或 `-` |
| mutex | 模块名（见 FEATURE-MATRIX） |
| status | `in_progress` / `blocked` / `done` |

**同一 mutex 同时仅一个 `in_progress`**。冲突 → 写 handoff blocker，禁止覆盖他人未合并改动。

### 6.2 分支与 Worktree（策略 A：一律从 dev 开分支）

> **禁止**在 `dev` / `test` / `main` 三大主干上直接 `git commit`（含代码、配置、文档）。  
> `dev` 仅作合入点；`test`/`main` 仅作环境晋升合入，禁止开发。

**任务开始（先于改码）：**

1. 更新本地 `dev`：`git checkout dev && git pull`（若已配置远端）
2. 从 `dev` 创建分支：`feature/<slug>`（新能力）或 `fix/<slug>`（缺陷）；slug 与 short-term 任务名对齐
3. 多 Agent 并行：用 `./scripts/agent-worktree.sh create feature/<slug>`（worktree 内编码）
4. 单 Agent：可在主仓 `git checkout -b feature/<slug>`，**不得**留在 `dev` 上改码提交

**合回 dev（占集成槽位，见 §6.3）：**

```bash
git checkout dev
git merge --no-ff feature/<slug> -m "merge: feature/<slug>"
# 冒烟通过后
git branch -d feature/<slug>   # 或 agent-worktree.sh remove
```

| 允许 | 禁止 |
|------|------|
| 在 `feature/*` / `fix/*` 上 commit | 在 `dev` / `test` / `main` 上 commit |
| worktree 内 `go test -short ./...` | worktree 内 `env-service.sh * start/stop/restart` |
| 占槽后在主仓 merge 入 `dev` | 多人直推同一 `dev` 工作区抢改 |
| 连主仓已起服务 `:8080` | 各 worktree 各起 docker |

脚本：`./scripts/agent-worktree.sh create|list|remove`

### 6.3 集成槽位（合入 dev + 容器验证）

> **编码与 worktree 单测可并行；合入 dev + 共享容器验证必须串行。**

Agent A 占槽 merge + 冒烟期间，Agent B **不得** merge dev 或动共享 docker；B 可继续 worktree 编码，并写入 queue 等待。

CURRENT「集成槽位」：`holder` | `phase`（idle/merging/smoke/e2e）| `since` | `scope` | `queue`

**释放**：冒烟 PASS（或 FAIL+handoff）+ 文档同步 + holder=idle。长 E2E 优先 smoke 释放，E2E 结果后补报告。

**默认冒烟（holder 在主仓执行）**：

```bash
go vet ./...
go test -short ./...
./scripts/env-service.sh dev rebuild
curl -sf http://127.0.0.1:8080/health
```

### 6.4 共享文档

`CURRENT.md` / `FEATURE-MATRIX.md` 由认领方或合并者更新；冲突时保留双方认领行再收敛。

### 6.5 协作纪律

- **单一焦点**：CURRENT 只列 1–3 个焦点
- **不覆盖**：发现冲突先 handoff/blocker
- **交接优先**：口头转述不可代替 handoff 文件

### 6.6 Herdr 角色、自动审批与备援

- 本仓库 Herdr 角色、任务泳道、额度保护和备援顺序以 [Herdr Agent roster](./.doc/ops/2026-09-13-herdr-agent-roster.md) 为准。
- Herdr 实例统一通过 [`scripts/herdr-agent-start.sh`](./scripts/herdr-agent-start.sh) 启动；自动派发使用 [`scripts/herdr-agent-dispatch.sh`](./scripts/herdr-agent-dispatch.sh)。
- 自动审批只消除客户端逐条确认，不扩大任务授权；分支、worktree、mutex、集成槽和破坏性操作红线继续生效。
- 自动接管仅允许发生在未开始写入且明确的额度、认证、客户端或启动失败。`timeout` / `unknown` 不证明任务未执行，必须停止重复投递并先检查 pane 与 handoff。
- 名称 `context_pi` / “Herdr PI”专指协作终端内的 PI CLI；产品容器中的执行器统一称“产品 PI Agent Runner”，两者禁止混称或互相代替验收。
- 未进入 roster 的新模型（包括尚未接入的 Devin）默认 `standby`，通过一次只读任务和一次隔离 worktree 写任务验证后再进入路由。

---

## 7. 文档生命周期

```text
audit（问题）→ remediation（方案）→ ops/short-term（任务）
  → test-reports（验收）→ archive/（关闭证据）
```

会话结束：[session-close-checklist.md](./.doc/ops/templates/session-close-checklist.md)

---

## 8. Git 与提交

- 遵循 **Conventional Commits**：`feat` / `fix` / `refactor` / `test` / `docs` / `chore` / `ci`
- **原子提交**：一个逻辑变更一批；提交发生在 `feature/*` 或 `fix/*` 上，不在三大主干
- **合回 dev**：占集成槽位后 `merge --no-ff`（见 §6.2、§6.3）
- **晋升**：`dev` → `test`（rc tag）→ `main`（release tag）；仅在规划的环境合并时动 `test`/`main`
- **用户未要求**：不擅自 push
- **用户已要求 push/同步远端**：必须自主完成
- **禁止**：在 `dev`/`test`/`main` 上直接开发 commit；在 `git config` 写入 token；硬重置/强推/删库仅在用户明确授权时

---

## 9. Secrets 与远端推送（自主，禁止索要）

### 查找顺序

1. `${HOME}/.secrets/`（如 `gitea`）
2. **PROJECT.md** 与 **push 脚本**（`scripts/git-push-dev.sh`）

### 禁止

- 向用户索要 token
- 在聊天/文档/commit 中展示 secret
- 把 token 写入仓库或 `.env` 并提交

### 缺失时

在 ops/handoff 记 blocker（路径 + 缺字段）；**仍不索要 secret 内容**。

---

## 10. 安全与合规红线

- 不提交 `.env`、密钥、凭证、生产数据倾倒
- 破坏性命令仅在用户明确授权时
- XSS/注入等修复优先于功能扩展

---

## 11. 计划 / 实现 / 验证

1. **大改动**：先 short-term 范围；范围外记 long-term
2. **实现**：按 PROJECT 测试命令验证
3. **完成定义**：checklist 勾选须有证据链接

---

## 12. 沟通

- 对用户：**简洁、中文**
- 指向文件路径，不复述长篇规则
- 需要决策时 **一次只问 1–2 个关键问题**

---

## 13. 工具入口（薄转发）

| 工具 | 入口 |
|------|------|
| Cursor | `.cursor/rules/*` + 本文件 |
| Claude Code | [CLAUDE.md](./CLAUDE.md) |
| Codex | [CODEX.md](./CODEX.md) |
| Gemini | [GEMINI.md](./GEMINI.md) |
| Antigravity | [ANTIGRAVITY.md](./ANTIGRAVITY.md) |
| Kimi | [KIMI.md](./KIMI.md) |

均转发至本文件启动链。

---

## 14. 模板索引

| 类型 | 路径 |
|------|------|
| 短期任务 | `.doc/ops/templates/short-term-task.md` |
| 长期任务 | `.doc/ops/templates/long-term-task.md` |
| Checklist | `.doc/ops/templates/checklist.md` |
| 交接 | `.doc/ops/templates/handoff.md` |
| 调研 | `.doc/ops/templates/research-note.md` |
| 审计笔记 | `.doc/ops/templates/audit-note.md` |
| 整改方案 | `.doc/ops/templates/remediation-plan.md` |
| 完成度行 | `.doc/ops/templates/feature-matrix-row.md` |
| 会话结束 | `.doc/ops/templates/session-close-checklist.md` |

---

**本仓库差异化约定见 [PROJECT.md](./PROJECT.md)。**