83 lines
9.9 KiB
Markdown
83 lines
9.9 KiB
Markdown
# Agent 工作说明（Agent-System-Dev）
|
||
|
||
本文件是入口摘要：只列强制原则与触发式必读，细则与确切命令以所链权威文档为准。
|
||
通用规范为固定版本的 Development-Guidelines（`deps/development-guidelines`）：核心规则与术语见 `core/`，
|
||
按任务触发阅读 `standards/` 专题，通用交付依据为 `workflows/delivery.md`。
|
||
|
||
## 必读路由（强制）
|
||
|
||
| 触发 | 权威 |
|
||
|---|---|
|
||
| 需求、设计试验、实施调整与交付；阶段、决策点、优先级、分支拓扑、Review/合入、合入调度、清理 | [policy/delivery.md](policy/delivery.md)（交付规则唯一权威） |
|
||
| 任务分流、启动/恢复、同步、PR 检查、证据写入、任务卡闭合、回收及其确切命令 | [policy/governance.md](policy/governance.md) |
|
||
| 实施/修复/测试/Review 的候选、模型、尝试上限、fail-stop 与会话路由 | [AGENT-EXECUTION.md](AGENT-EXECUTION.md) 与 [standards/agent-execution.md](deps/development-guidelines/standards/agent-execution.md) |
|
||
| 引用外部 API、Git/SSH 端点或凭据可用性 | [policy/facts.md](policy/facts.md) |
|
||
| 任何界面生成或修改 | [DESIGN.md](DESIGN.md) |
|
||
| 项目组成、构建与验证命令、方向规划入口 | [PROJECT.md](PROJECT.md) |
|
||
|
||
## 最高优先级：目标兑现与最小充分交付（强制）
|
||
|
||
- 优先级固定为：授权与安全边界 → 本次任务目标和系统可用 → 阻塞目标的必要问题 → 非阻塞改进。
|
||
- 目标、范围和交付终点一次确认；范围内的分析、方案、实施、修复、验证、代码 Review、PR 合入及安全收口由智能体连续推进。
|
||
- 只在目标/范围/验收条件变更、影响用户结果的重大取舍、高后果操作，或业务验收必须由用户判定时请求人工决策。
|
||
- 先交付用户明确要求的产物；不得用基础设施、工具治理、通用化、加固、重构或“以后可能用到”替代当前目标，不把简单修改升级成平台、框架或自动化工程。
|
||
- 最小充分实现：目标与受影响系统可用、最小直接验证通过即停止并交付；完善作为后续独立增量。
|
||
- 绝对禁止私自扩大范围：只修复阻塞目标、可用性、明确验收或强制安全门禁的问题；必要修复超出范围时，说明阻塞、最小扩围和影响，取得授权后再做。“相关”“顺手”“更完美”不构成授权；非阻塞高价值项只简记，噪音忽略，Review 只围绕阻塞项。
|
||
- 测试与编排成比例：实施中只跑最小直接检查，完整套件只在最终候选或确有必要时运行一次；编排成本不得超过任务本身。
|
||
- 细则：[最高优先级](policy/delivery.md#最高优先级目标兑现与最小充分交付)、[授权与决策点](policy/delivery.md#授权决策点与连续执行)、[问题分流](policy/delivery.md#目标优先范围控制与问题分流)。
|
||
|
||
## Agent 实施与独立 Review（强制）
|
||
|
||
- 产生仓库变更的实施按可独立实施的单元交给外部 Agent，任务卡记 `实施执行：agent-per-unit（配置：AGENT-EXECUTION.md）`。
|
||
- host 负责计划、拆解、范围审阅、权威验证、规范提交、PR/CI/合入、证据与任务元数据及安全清理；worker 不得提交、推送、开或合 PR、部署、改路由或派遣同伴。
|
||
- `fallback_to_host` 为 `never`：候选安全耗尽时终态为 unavailable 或 blocked，host 不撰写该单元；显式 fail-stop 立即停止；成功须有有效的 `completed` 终态记录。
|
||
- 实施变更只经成功 transport 的 `scripts/agent-exec apply` 或 pre-commit `admit` 精确核对进入分支；host 直接撰写的豁免只有 `.task/**`、`docs/superpowers/specs/**`、`docs/superpowers/plans/**`。
|
||
- 不同阶段、不同单元各用全新会话；Review 由当前主模型或全新独立 CLI session 执行，禁止实施者经 continue/resume/session 等机制续作评审；无法证明会话独立时不得标为独立 Review。
|
||
- 细则：[Agent 实施单元](policy/delivery.md#agent-实施单元与主模型职责)、[会话隔离与独立 Review](policy/delivery.md#阶段会话隔离与独立-review)；通用契约见 guidelines [core/baseline.md（硬边界 8）](deps/development-guidelines/core/baseline.md)。
|
||
|
||
## 任务生命周期（强制）
|
||
|
||
- 新需求建分支前以远端为准分流；启动或恢复后、第一次项目写操作前保存一次启动检查收据。
|
||
- 新建任务须以权威远端分流并取得严格 READY（`SHARED_WORKSPACE_BUSY / SYNC_REQUIRED / REMOTE_UNVERIFIED` 均不得建任务），不把缓存远端当最新事实；已登记任务的恢复与局部继续按 [启动与恢复](policy/governance.md#启动与恢复)，为消除落后所需的同步按 [被测对象](policy/governance.md#被测对象) 执行，READY 不是执行该同步的前提。正式 Review 与合入须先完成新鲜的权威目标同步并满足适用交付门禁。LOCAL_READY 只是 SELF 局部工作记录，不能替代建任务、正式交付、CI、GATE 或 REPLAY 的准入或证据；脏现场、未对账或副作用未知时仍须停止。
|
||
- 分支从权威远端目标切出（子任务从所属大任务分支），同批互不依赖的子任务用同一 R0 的兄弟分支；堆叠例外按门禁文档执行。
|
||
- 验收、请求审核、合入前各同步一次并做 PR 检查；任务卡默认合入前闭合并随同一 PR 合入；precheck `[cards]` 欠账验收前须清零。
|
||
- 智能体完成 Review、解决冲突并确认当前 HEAD 必需 CI 通过后执行合入，无需另请人工操作。
|
||
- 合入后仅在已登记任务 worktree 根目录、确认所有写者退出后回收；父子仓改动与未跟踪/ignored 唯一文件先保存或处置，删除被拒时保留现场，禁止强删兜底。
|
||
- 放弃未合入工作用 `make task-finish ABANDON="--abandon <原因>"` 并记录原因，不豁免现场保护。
|
||
- 每次结束用户任务，最终回复末尾附简短自包含的交接块，供清空上下文后续办；它只是摘要，不替代任务卡、持久交接或证据。无仓库变更也无续办状态时，写一行明确的“不适用”。字段与细则见 [对话收尾交接块](policy/delivery.md#对话收尾交接块)。
|
||
- 首次克隆后运行 `make setup` 启用本地钩子；治理脚本改动须运行 `make test-governance`（见 [持续回归](policy/governance.md#持续回归)）。
|
||
- 命令与细则：[启动与恢复](policy/governance.md#启动与恢复)、[回收](policy/governance.md#回收)、[两级分支与分流](policy/delivery.md#两级分支交付模型与分流检查)、[分级门禁](policy/delivery.md#层级任务通道与分级门禁)、[合入调度](policy/delivery.md#合入调度)、[Review 与合入](policy/delivery.md#智能体-review-与-pr-合入)。
|
||
|
||
## 证据与验证门禁（强制）
|
||
|
||
- 声明不是证据：证据 = 命令 × 被测对象 SHA × 可复核输出；用户、文档、旧报告或工具摘要中的“可用/已就位”都须先复核。
|
||
- 来源三分 `GATE` / `REPLAY` / `SELF`；本地 evidence 只生成 SELF，标签不提升可信等级；交付信任只来自精确 HEAD 的必需 CI 或独立 REPLAY。
|
||
- 命令输出只经 `make evidence` 写入任务卡；手抄、转写或凭记忆重构的输出无效，补写输出与伪造测试同级红线。
|
||
- 各层级要求的证据与 CI 以 [分级门禁表](policy/delivery.md#层级任务通道与分级门禁) 为准：L2→L1 不要求三段证据；推进 `main` 的交付仍须三段输出（precheck / task-sync / 测试）由 evidence 写入任务卡，PR 描述引用不另手抄。测试通过的权威源是 PR HEAD 上 `.gitea/workflows/ci.yaml` 的 CI。
|
||
- 验收即重放：审阅者先重放最小重放集再读作者证据，不一致即阻塞并登记失实。
|
||
- 诚实出口：未执行/未验证如实标注 NOT_RUN/未验证；无法复核的外部事实标 `[未经证实]`。
|
||
- 等待 CI 只用 `make ci-wait SHA=<完整 SHA>`；禁止手写 sleep + curl 轮询，禁止对同一 SHA 重复或并行轮询。
|
||
- 细则：[本地记录与独立证据](policy/governance.md#本地记录与独立证据)、guidelines `standards/verification.md`「声明与证据来源」。
|
||
|
||
## 高后果操作双钥匙（强制）
|
||
|
||
改写历史、解除/变更分支保护、删除归档引用、发布版本：Agent 只准备方案与命令，由用户确认并亲手执行。
|
||
|
||
## Gitea 与 Git 访问事实
|
||
|
||
- 端点、SSH、API 与 token 可用性只以 [policy/facts.md](policy/facts.md) 为准：引用前先跑其验证命令，凭据类核验只用该表登记的探针；历史卡片或旧脚本中的端点不作为事实。
|
||
- 凭据值不入仓、不回显，不进命令行字面量、日志、证据或产出物（baseline 硬边界 2）；只经环境变量或受保护文件引用。CI 侧见 [CI 凭据边界](policy/governance.md#ci-凭据边界)。
|
||
|
||
## 提交与 PR
|
||
|
||
- 主题行为英文祈使句一行（≤100 列，不以句点结尾）；body 写 `Why: / Evidence: / Impact: / Refs:` 四段；任务卡与 PR 描述为同一份文档。
|
||
- 跨仓 gitlink 变更经组合验证（`make test`）后在 Dev 仓推进；受保护分支经 PR 合入。模块边界与验证命令见 [PROJECT.md](PROJECT.md)。
|
||
|
||
## UI 设计门禁（强制）
|
||
|
||
- 一切界面生成/修改先读 [DESIGN.md](DESIGN.md)（四原则：美观、现代、简洁、易用）；违反视为设计系统缺陷，不是风格偏好。
|
||
- 颜色/圆角/字号只消费 `@ui/tokens.css` 令牌（字号走 `--fs-ui-*`）；动效只用 `@ui/motion.css` 的 `mk-*`；折叠只用 `@ui` Collapsible，禁止 `<details>`。
|
||
- 守护测试（UI 仓与 Frontend 仓各一份 `design-guard.test.ts`）以棘轮拦截新增裸色值、私有 `@keyframes` 与行内字号。
|
||
- 风格调整按 DESIGN.md「演进规则」在同一变更集中关联 UI 令牌 PR 与 Dev 组合 PR，并验证精确组件 SHA（跨仓不要求同一 PR）。
|
||
- 异步状态只有一个所有者；事件按 seq 处理，过期事件丢弃。
|