agent-bot
1409e02187
- AGENTS.md/PROJECT.md rewritten to three-layer model (hard/default/advice); remote authority = Gitea native protection, coding flow zero-agentctl - delete .cursor/rules/agentctl-mandatory.mdc; cursor hooks downgraded to advisory - CURRENT/FEATURE-MATRIX become read-only snapshots; task state = Issue/PR - CI: add tracked secrets scan to required go-vet job - closeout record with V19/V20/V23/V26 evidence - local pre-commit/reference-transaction hook files removed from main worktree
4.2 KiB
4.2 KiB
Agent 工作手册
生效模型：Gitea 原生门禁（2026-09-29 U2 治理交接起生效；交接记录与旧模型见 .doc/ops/2026-09-29-u2-governance-closeout.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 凭证指引 从本机查找；缺失只记录路径与缺字段，不向用户索要值。 - 破坏性操作（强推、硬重置共享分支、删库、批量删远端引用）须用户明确授权。
- 共享环境边界：dev/test/main 运行实例、共享 DB、部署与发布操作只从 PROJECT 指定的运行入口执行且须明确授权；
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）；提交围绕可解释、可验证、可回退的逻辑变更；实现与回归测试可同批。
- 验证：改什么测什么，按 验证契约 与影响范围选择；PR 必需 CI 由 Gitea 判定（短测存量失败见 issue #2，报告不阻断）。纯文档改动只做差异/链接/一致性检查。
- Bug 与异常分析：用户报告问题时，先还原事实与根因、排查同类与关联问题、形成可审方案，再按问题类别回归（原例 + 同类变体 + 正常行为）；不以让单一句子/数据/路径通过为解决依据。分析默认不含实施授权。
- 文档：进 .doc taxonomy，命名
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 确认。工具缺失不阻断会话。 - 按症状/机制检索 问题台账 与 经验库 一次，重要命中再展开；无命中不建表。
agentctl（Development-Manager）保留为可选维护工具，仅用于部署、发布、恢复等受信执行场景；普通编码流程对它零依赖，其故障不是编码任务的待办。- 对用户简洁中文，指向证据文件；需要决策时一次 1–2 个关键问题。
变更与登记
本文件与 PROJECT 由 PR 变更并经审核合入后生效；历史治理模型（agentctl 租约、docs apply、候选集成、收口盘点）已由 2026-09-29 交接退役，旧规范文档保留为历史参考，冲突时以本文件为准。