Files

T

weichenandCursor 14f75df1ac refactor: remove Control Center from this repository

Progress tracking now lives in a separate project. Drop the server,
docs, and module-boundary entries without restoring engineering-dashboard.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-09-19 03:40:00 +00:00

10 KiB

Raw Blame History

Agent 工作手册（通用）

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

1. 目的与适用范围

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

2. 启动协议（Session Bootstrap）

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

本文件 AGENTS.md
PROJECT.md（本仓库地图与约定）
.doc/README.md（文档 taxonomy）
.doc/ops/CURRENT.md（焦点、并行认领、集成槽位）
.doc/status/FEATURE-MATRIX.md（模块完成度）
相关 short-term / handoff / audit / remediation
发布/审计类任务：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
提交	文档变更与代码同批或紧随 `docs(...)` 提交

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

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

4. 文档 taxonomy

默认路径：.doc/（详见 .doc/README.md）

.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
整改方案	`remediation/`	remediation-plan.md
短期任务	`ops/short-term/`	short-term-task.md
长期 backlog	`ops/long-term/`	long-term-task.md
Checklist	`ops/checklists/`	checklist.md
交接	`ops/handoffs/`	handoff.md
调研	`ops/research/`	research-note.md
模块完成度	`status/FEATURE-MATRIX.md`	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 仅作环境晋升合入，禁止开发。

任务开始（先于改码）：

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

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

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 在主仓执行）：

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 为准。
Herdr 实例统一通过 scripts/herdr-agent-start.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. 文档生命周期

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

会话结束：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 与远端推送（自主，禁止索要）

查找顺序

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

禁止

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

缺失时

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

10. 安全与合规红线

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

11. 计划 / 实现 / 验证

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

12. 沟通

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

13. 工具入口（薄转发）

工具	入口
Cursor	`.cursor/rules/*` + 本文件
Claude Code	CLAUDE.md
Codex	CODEX.md
Gemini	GEMINI.md
Antigravity	ANTIGRAVITY.md
Kimi	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。

10 KiB Raw Blame History Unescape Escape