# Agent 工作手册

生效模型：Gitea 原生门禁（2026-09-29 U2 治理交接起生效；交接记录与旧模型见
[.doc/ops/2026-09-29-u2-governance-closeout.md](./.doc/ops/2026-09-29-u2-governance-closeout.md)）。
项目入口见 [PROJECT.md](./PROJECT.md)。规则分三层：**硬边界**（不可绕过）、**默认做法**（有理由可调整，偏离时在 PR/任务中说明一句理由）、**建议**（可选工具与习惯）。

## 1. 硬边界

- **远端权威在 Gitea**：dev/test/main 为受保护分支；直推仅限用户白名单身份。一切合入走 PR：必需 CI 检查（go-vet、backup-restore-drill、web）+ 非作者批准 + 陈旧分支拒绝。编码 Agent 以 `agent-bot` 身份提交与建 PR；作者不得批准自己的 PR（Gitea 强制拒绝，无需自觉）。
- **凭证与秘密**：禁止向仓库提交 `.env`、密钥、token、生产数据倾倒；禁止在聊天/文档/commit 展示 secret 值。凭证按 [PROJECT 凭证指引](./PROJECT.md#凭证与推送) 从本机查找；缺失只记录路径与缺字段，不向用户索要值。
- **破坏性操作**（强推、硬重置共享分支、删库、批量删远端引用）须用户明确授权。
- **共享环境边界**：dev/test/main 运行实例、共享 DB、部署与发布操作只从 [PROJECT](./PROJECT.md#环境与操作入口) 指定的运行入口执行且须明确授权；`restart` 不证明已部署新代码。跨环境禁止读写业务数据。
- **他人现场**：不动他人 worktree 与未提交文件；不复制主目录 `.env` 与业务 data；重叠路径/mutex 单写者。
- **证据诚实**：stub、SKIP、未运行不得冒充真实链路 PASS；未获授权不执行远端/环境/数据变更。

## 2. 默认做法

- **分支与工作区**：每个任务从最新 dev 创建 `feature/<task-id>` / `fix/<task-id>`；可用 `.worktrees/` 或独立 clone，按需隔离，任务结束清理。主目录主工作树保持 dev。普通编辑、本地提交、推送功能分支、建 PR 均不需要任何治理工具。
- **提交**：Conventional Commits（feat/fix/refactor/test/docs/chore/ci）；提交围绕可解释、可验证、可回退的逻辑变更；实现与回归测试可同批。
- **验证**：改什么测什么，按 [验证契约](./.doc/ops/2026-09-21-validation-contract.md) 与影响范围选择；PR 必需 CI 由 Gitea 判定（短测存量失败见 issue #2，报告不阻断）。纯文档改动只做差异/链接/一致性检查。
- **Bug 与异常分析**：用户报告问题时，先还原事实与根因、排查同类与关联问题、形成可审方案，再按问题类别回归（原例 + 同类变体 + 正常行为）；不以让单一句子/数据/路径通过为解决依据。分析默认不含实施授权。
- **文档**：进 [.doc taxonomy](./.doc/README.md)，命名 `YYYY-MM-DD-<slug>.md`；一个任务一处主记录，其余链接不复制。CURRENT / FEATURE-MATRIX 为**只读历史快照**，不再要求会话同步维护；能力与发布状态以代码、测试、Release 与 issue 为准。
- **任务状态**：以 Gitea Issue/PR 为单一来源；收口在对应 PR/issue 记录结果、验证与剩余项，不另建第二套任务台账。
- **晋升**：dev → test（rc tag）→ main（release tag）经 PR 与用户授权。

## 3. 建议

- 跨文件定位可用本仓 CodeGraph（`codegraph sync -q`）；grep 仍是完整性唯一权威，重命名/穷举调用方必须 grep 确认。工具缺失不阻断会话。
- 按症状/机制检索 [问题台账](./.doc/audit/ISSUES.md) 与 [经验库](./.doc/ops/lessons/INDEX.md) 一次，重要命中再展开；无命中不建表。
- `agentctl`（Development-Manager）保留为可选维护工具，仅用于部署、发布、恢复等受信执行场景；普通编码流程对它零依赖，其故障不是编码任务的待办。
- 对用户简洁中文，指向证据文件；需要决策时一次 1–2 个关键问题。

## 变更与登记

本文件与 PROJECT 由 PR 变更并经审核合入后生效；历史治理模型（agentctl 租约、docs apply、候选集成、收口盘点）已由 2026-09-29 交接退役，旧规范文档保留为历史参考，冲突时以本文件为准。