Agent-System-Dev/AGENTS.md

Agent 工作说明（Agent-System-Dev）

本文件是入口摘要：只列强制原则与触发式必读，细则与确切命令以所链权威文档为准。 通用规范为固定版本的 Development-Guidelines（deps/development-guidelines）：核心规则与术语见 core/， 按任务触发阅读 standards/ 专题，通用交付依据为 workflows/delivery.md。

必读路由（强制）

触发	权威
需求、设计试验、实施调整与交付；阶段、决策点、优先级、分支拓扑、Review/合入、合入调度、清理	policy/delivery.md（交付规则唯一权威）
任务分流、启动/恢复、同步、PR 检查、证据写入、任务卡闭合、回收及其确切命令	policy/governance.md
实施/修复/测试/Review 的候选、模型、尝试上限、fail-stop 与会话路由	AGENT-EXECUTION.md 与 standards/agent-execution.md
引用外部 API、Git/SSH 端点或凭据可用性	policy/facts.md
任何界面生成或修改	DESIGN.md
项目组成、构建与验证命令、方向规划入口	PROJECT.md

最高优先级：目标兑现与最小充分交付（强制）

• 优先级固定为：授权与安全边界 → 本次任务目标和系统可用 → 阻塞目标的必要问题 → 非阻塞改进。
• 目标、范围和交付终点一次确认；范围内的分析、方案、实施、修复、验证、代码 Review、PR 合入及安全收口由智能体连续推进。
• 只在目标/范围/验收条件变更、影响用户结果的重大取舍、高后果操作，或业务验收必须由用户判定时请求人工决策。
• 先交付用户明确要求的产物；不得用基础设施、工具治理、通用化、加固、重构或“以后可能用到”替代当前目标，不把简单修改升级成平台、框架或自动化工程。
• 最小充分实现：目标与受影响系统可用、最小直接验证通过即停止并交付；完善作为后续独立增量。
• 绝对禁止私自扩大范围：只修复阻塞目标、可用性、明确验收或强制安全门禁的问题；必要修复超出范围时，说明阻塞、最小扩围和影响，取得授权后再做。“相关”“顺手”“更完美”不构成授权；非阻塞高价值项只简记，噪音忽略，Review 只围绕阻塞项。
• 测试与编排成比例：实施中只跑最小直接检查，完整套件只在最终候选或确有必要时运行一次；编排成本不得超过任务本身。
• 细则：最高优先级、授权与决策点、问题分流。

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 实施单元、会话隔离与独立 Review；通用契约见 guidelines core/baseline.md（硬边界 8）。

任务生命周期（强制）

• 新需求建分支前以远端为准分流；启动或恢复后、第一次项目写操作前保存一次启动检查收据。
• 新建任务须以权威远端分流并取得严格 READY（SHARED_WORKSPACE_BUSY / SYNC_REQUIRED / REMOTE_UNVERIFIED 均不得建任务），不把缓存远端当最新事实；已登记任务的恢复与局部继续按 启动与恢复，为消除落后所需的同步按 被测对象 执行，READY 不是执行该同步的前提。正式 Review 与合入须先完成新鲜的权威目标同步并满足适用交付门禁。LOCAL_READY 只是 SELF 局部工作记录，不能替代建任务、正式交付、CI、GATE 或 REPLAY 的准入或证据；脏现场、未对账或副作用未知时仍须停止。
• 分支从权威远端目标切出（子任务从所属大任务分支），同批互不依赖的子任务用同一 R0 的兄弟分支；堆叠例外按门禁文档执行。
• 验收、请求审核、合入前各同步一次并做 PR 检查；任务卡默认合入前闭合并随同一 PR 合入；precheck [cards] 欠账验收前须清零。
• 智能体完成 Review、解决冲突并确认当前 HEAD 必需 CI 通过后执行合入，无需另请人工操作。
• 合入后仅在已登记任务 worktree 根目录、确认所有写者退出后回收；父子仓改动与未跟踪/ignored 唯一文件先保存或处置，删除被拒时保留现场，禁止强删兜底。
• 放弃未合入工作用 make task-finish ABANDON="--abandon <原因>" 并记录原因，不豁免现场保护。
• 首次克隆后运行 make setup 启用本地钩子；治理脚本改动须运行 make test-governance（见 持续回归）。
• 命令与细则：启动与恢复、回收、两级分支与分流、分级门禁、合入调度、Review 与合入。

证据与验证门禁（强制）

• 声明不是证据：证据 = 命令 × 被测对象 SHA × 可复核输出；用户、文档、旧报告或工具摘要中的“可用/已就位”都须先复核。
• 来源三分 GATE / REPLAY / SELF；本地 evidence 只生成 SELF，标签不提升可信等级；交付信任只来自精确 HEAD 的必需 CI 或独立 REPLAY。
• 命令输出只经 make evidence 写入任务卡；手抄、转写或凭记忆重构的输出无效，补写输出与伪造测试同级红线。
• 各层级要求的证据与 CI 以 分级门禁表 为准：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 重复或并行轮询。
• 细则：本地记录与独立证据、guidelines standards/verification.md「声明与证据来源」。

高后果操作双钥匙（强制）

改写历史、解除/变更分支保护、删除归档引用、发布版本：Agent 只准备方案与命令，由用户确认并亲手执行。

Gitea 与 Git 访问事实

• 端点、SSH、API 与 token 可用性只以 policy/facts.md 为准：引用前先跑其验证命令，凭据类核验只用该表登记的探针；历史卡片或旧脚本中的端点不作为事实。
• 凭据值不入仓、不回显，不进命令行字面量、日志、证据或产出物（baseline 硬边界 2）；只经环境变量或受保护文件引用。CI 侧见 CI 凭据边界。

提交与 PR

• 主题行为英文祈使句一行（≤100 列，不以句点结尾）；body 写 Why: / Evidence: / Impact: / Refs: 四段；任务卡与 PR 描述为同一份文档。
• 跨仓 gitlink 变更经组合验证（make test）后在 Dev 仓推进；受保护分支经 PR 合入。模块边界与验证命令见 PROJECT.md。

UI 设计门禁（强制）

• 一切界面生成/修改先读 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 处理，过期事件丢弃。