Agent-System-Dev/AGENTS.md

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

本仓开发遵循 Development-Guidelines（见 deps/development-guidelines，gitlink 固定版本）： 核心规则与术语见其 core/，按任务触发阅读 standards/ 专题；通用交付依据为 workflows/delivery.md。 本项目的需求、设计试验、实施调整及交付必读 policy/delivery.md（交付规则唯一权威）： 目标、范围和交付终点一次确认；范围内的分析、方案、实施、修复、验证、代码 Review、PR 合入及安全收口由智能体连续推进。 只在目标/范围/验收条件变更、存在会影响用户结果的重大取舍、触及高后果操作，或业务验收必须由用户判定时请求人工决策。 智能体解决冲突并确认当前 HEAD 的 CI 通过后执行合入，无需另请人工操作。本文件是入口摘要，细则以所链文档为准。

立即生效的最高优先级（强制）

• 先交付用户产物：在既有授权与强制安全边界内，先交付用户明确要求的产物；不得用基础设施、工具治理、通用化、加固、重构或“以后可能用到”替代当前目标，禁止把简单 Markdown、配置或说明修改擅自升级成平台、框架、自动化系统或大规模工程。
• 最小充分实现：目标可用、系统可用并通过最小直接验证后立即停止并交付；体验、结构、性能与治理完善作为后续独立增量，不得拖延当前结果。
• 只修阻塞项：只修复直接阻塞目标、可用性、明确验收条件或强制安全门禁的问题；高价值非阻塞项只简记，低影响噪音直接忽略；Review/迭代只围绕阻塞项，阻塞项闭合即结束。
• 测试与风险成比例：实施中只跑最小直接检查；完整/长耗时套件仅在最终候选、规范明确要求或影响面确有必要时运行一次，禁止每个小文档、配置或 adapter 修改后重复全量测试。
• 编排成本不得超过任务本身：按 AGENT-EXECUTION.md 的候选和尝试上限调度，不限制单次 CLI 的推理时长、工具次数、规划方式或首次写文件时间；除非用户明确要求或有证据证明直接阻塞，不新增嵌套控制器、额外 worktree、复杂收据体系或新架构；执行路由不能成为推迟用户产物的理由。细则见 最高优先级。

任务目标与范围（强制）

• 优先级固定为：授权与安全边界 → 本次任务目标和系统可用 → 阻塞目标的必要问题 → 非阻塞改进。完成标准是已批准验收条件成立且受影响系统保持可用，不是清零所有附近问题。
• 绝对禁止私自扩大范围：影响目标的问题只在既有授权内作最小充分修复；必要修复超出范围时，说明阻塞、最小扩围和影响，取得授权后再做。“相关”“顺手”“更完美”不构成扩围授权。
• 新发现按影响分流：阻塞验收、导致不可用/明确回归、违反安全边界或必需门禁失败的必须处理；其余不阻塞交付，只有明确影响和后续价值的才记录。先实现端到端可用的最小闭环，非阻塞 Review 意见不阻止交付（见 问题分流）。

实施执行路由（强制）

• 调度必读 AGENT-EXECUTION.md（唯一项目执行路由配置）；通用契约遵循 guidelines core/baseline.md（硬边界 8） 与 standards/agent-execution.md。产生仓库变更的实施按可独立实施的单元拆分，任务卡记 实施执行：agent-per-unit（配置：AGENT-EXECUTION.md）。
• 外部 Agent 在新进程/隔离工作区执行一个有界单元；host 负责计划、拆解、范围审阅、权威验证、规范提交、PR/CI/合入、证据与任务元数据及安全清理。Worker 不得提交、推送、开或合 PR、部署、改路由或派遣同伴。
• 实施、修复与测试的正常候选只有 Cursor、Antigravity（agy）和 PI，顺序以配置为准；每个候选对安全可恢复失败（unavailable，或外部无副作用已被机制证明的 failed-clean）最多 3 次全新尝试后才换候选。network=false/external_cost=false 只是声明；没有强制隔离或可信对账时，已启动的失败尝试记 failed-unknown。成功须从该 CLI 实际事件信封解出有效的 completed 终态记录，缺失或无效即 fail closed。
• 三者都安全耗尽后才允许一次全新的 Codex CLI 紧急尝试；Codex 平时只用于规划、方案设计、实施计划或独立 Review。fallback_to_host 为 never（旧值 all-unavailable 同样不授权）：安全耗尽不发出 host-fallback-authorized，终态为 unavailable 或 blocked，host 不撰写该单元。
• 显式 fail-stop 立即停止，不重试、不换候选、不启动紧急尝试：failed-unknown、scope-expansion、blocked、cancelled、无效配置、未对账 Git 状态与安全失败；总超时及 stdin/stdout/stderr 都无活动的空闲超时归入 failed-unknown。一次尝试只在显式终态失败、进程退出、总超时或空闲超时时结束，CLI 可在目标、范围与安全边界内自主检查、计划、测试并迭代。
• 实施变更只经成功 transport 由 scripts/agent-exec apply 集成，或由 pre-commit admit 按精确内容核对。本地 HMAC 历史与该钩子只是本地完整性/篡改证据（SELF），不是 GATE、可信身份，也不防同一主机 OS 用户；本地记录缺失或无效仍拒绝，交付信任只来自精确 HEAD 的 CI 或独立 REPLAY。host 直接管理的豁免只有 .task/**、docs/superpowers/specs/** 与 docs/superpowers/plans/**，host 不直接撰写实施单元。细则见 policy/delivery.md 与 policy/governance.md；不削弱 goal-first、严格范围、先可用、独立 Review、证据、平台准入与高后果双钥匙规则。

阶段与会话隔离（强制）

• 需求分析、方案、设计、计划、实施、测试、Review 与验收默认各启动一个全新会话；不同阶段、不同实施单元不得复用同一 CLI 会话、conversation、thread 或 session。
• Review 由当前主模型或全新且独立的 CLI session 执行；绝对禁止实施者通过 continue、resume、conversation/session ID、session 路径或等价机制继续充当评审者。
• 评审只接收固定的目标/需求、base/head、实际 diff、测试与证据，默认不转交实施聊天、思维过程、中间自评或原会话历史；确需补充时只提供可复核产物。
• 每阶段记录工具、模型、stage、attempt/session 身份及 fresh_session；工具不暴露 session ID 时标 not-observable，但仍须新进程并禁用恢复/续聊；无法证明会话独立时不得标为独立 Review（见 会话隔离）。

UI 设计门禁（强制）

• 本仓一切界面生成/修改先读根目录 DESIGN.md（四原则：美观、现代、简洁、易用）再动手；违反视为设计系统缺陷，不是风格偏好。
• 颜色/圆角/字号只消费 @ui/tokens.css 令牌（字号走 --fs-ui-* 标尺）；动效只用 @ui/motion.css 的 mk-* 工具类；折叠一律用 @ui Collapsible 原语，禁止 <details>。
• 守护测试（UI 仓与 Frontend 仓各一份 design-guard.test.ts）以棘轮拦截新增裸色值、私有 @keyframes 与行内字号；风格调整须在同一变更集中关联 UI 令牌 PR 与 Dev 的 DESIGN.md/gitlink 组合 PR，并验证精确组件 SHA（跨仓不要求两个文件出现在同一 PR）。
• 异步状态只有一个所有者。事件按 seq 处理，过期事件丢弃。

任务启动门禁（强制）

• 新需求分流：创建分支前以远端为准运行 make task-triage REQ='<需求>' TRIAGE_RECEIPT=<路径> 检查接纳中的大任务（branch_kind=initiative 且 accepting_requirements=true）；有候选时运行 make task-triage-decide TRIAGE_RECEIPT=<路径> VERDICT=JOIN|NEW … REASON='<理由>'；make task-start … TRIAGE_RECEIPT=<路径> 核验收据通过后才建分支。JOIN 建子任务（KIND=child INITIATIVE=feature/<initiative> NAME=feature/<initiative>-<slug>），NEW 建普通任务或新大任务（[KIND=initiative] NAME=feature/<slug>），DECISION_REQUIRED 为有候选时的待决策状态，改变范围/优先级的加入由人工决策。已登记在父卡 ## 子任务登记 的计划内 L2 子任务可免分流收据。
• 启动检查：启动或恢复后、第一次项目写操作前运行一次 RECEIPT=/tmp/<本次唯一名称>.json CMD="make precheck" make evidence 保存完整脱敏收据并按输出完成必读；make task-start 省略 PRECHECK_RECEIPT 时自动捕获，恢复在原 worktree 用 make task-resume PRECHECK_RECEIPT=<路径>。SHARED_WORKSPACE_BUSY / SYNC_REQUIRED / REMOTE_UNVERIFIED 均不得进入写入流程，失败后排除原因再启动，不把缓存远端当最新事实。默认要求严格 READY，任务中途不重复；局部恢复见 开发门禁。
• 分支层级：一律从权威 origin/main 切，同批互不依赖的子任务用同一 R0 的兄弟分支。确有顺序依赖的堆叠例外：加 PARENT=feature/<父slug> PARENT_PR=<父PR链接>，卡记主干 R0、父分支及 SHA、父 PR，命名 <type>/<父slug>-<子题> 不嵌 SHA，合入顺序父→子，父合入后子须 make task-sync 并把 PR base 改回 main 才可合入（见 policy/delivery.md 与 开发门禁）。
• 同步与 PR 门禁：验收、请求审核、合入前各运行一次 make task-sync 与 make task-pr-check（大任务收口用 FINAL=1）；三段完成证据由 make evidence 写入任务卡。层级、任务通道与分级门禁见 层级与分级门禁，多分支交付的最终窗口见 合入调度。
• 回收：合入后核对所有写者退出；能从当前会话、进程、锁与工作区状态证明时，智能体在已登记任务 worktree 根目录运行 TASK_WRITERS_STOPPED=1 make task-finish，无法证明时才请 owner 确认。父子仓改动、未跟踪/ignored 唯一文件先保存或显式处置；删除被拒时保留现场，禁止强删兜底。放弃未合入工作用 make task-finish ABANDON="--abandon <原因>" 并记录原因，不豁免现场保护。
• 任务卡闭合：默认在最终同步/合入前于任务 worktree 运行 make task-close SELF=1（卡改为“已完成（合入前闭合）”、写入本 PR 链接并归档，随同一 PR 合入；会提交并推送本分支，只处理本分支的卡）。post-merge 钩子仅提示。主检出 make task-close 或 FOLD=--fold 只用于已合入未闭合的遗留卡，须核对只含目标卡，其闭合 PR 同样经智能体 Review、冲突处置与当前 HEAD CI 后合入。precheck [cards] 欠账验收前须清零。

证据与验证门禁（强制）

• 声明不是证据：「声明已就位」≠「能力已就位」；任何来源的结果声明都不是证据，证据 = 命令 × 被测对象 SHA × 可复核输出（guidelines standards/verification.md「声明与证据来源」）。
• 来源三分：通过类断言标注 GATE（可核验身份及固定对象的 CI/受信执行器）/ REPLAY（独立审阅者的重跑记录）/ SELF（作者或本地工具记录，含 precheck）。工具写入、摘要和标签不提升可信等级，本地 evidence 只生成 SELF，不能靠 SRC 升级；合入与验收须核验 GATE 的运行链接/身份及 SHA，或 REPLAY 的审阅者、命令和对象，与重验不一致以重验为准。
• 证据由工具写入：命令输出只经 CMD="<命令>" make evidence 写入（卡内写摘要块，完整脱敏收据一次性存于仓外，见 开发门禁）；凭据只经环境或受保护文件引用。手抄、转写、凭记忆重构的输出无效，补写输出与伪造测试同级红线。
• 完成声明三段输出（precheck / task-sync / 测试）由 evidence 写入任务卡，PR 描述引用不另手抄；测试通过的权威源是 CI（.gitea/workflows/ci.yaml 在 PR HEAD 上 make test+make build），本地输出只是辅助线索。
• 验收即重放：请求审核后，审阅者先在评审环境重放最小重放集（关键门禁命令 + 变更直接相关检查）再读作者证据；不一致直接阻塞并登记为失实事件。
• 外部事实零信任：用户/文档/旧报告中的“可用/已就位”须先执行 policy/facts.md 对应验证命令或当场实测才能写入产出物，无法复核标 [未经证实]；登记项带 last_verified 与 TTL，precheck [facts] 报告过期项，make facts-verify 逐条重验。
• 诚实出口：未执行/未验证是合法状态，如实标注（NOT_RUN/未验证）优于补写。

提交与 PR

• 主题行：英文祈使句一行（≤100 列，不以句点结尾）；body 写 Why: / Evidence: / Impact: / Refs: 四段；任务卡与 PR 描述为同一份文档。
• 跨仓 gitlink 变更须经组合验证（make test）后在 Dev 仓推进；受保护分支经 PR 合入。
• 等待 CI 只用一条阻塞命令 make ci-wait SHA=<完整 SHA>（15 s 轮询、失败即停、默认 20 分钟超时）； 禁止手写 sleep + curl 轮询循环，禁止对同一 SHA 重复/并行轮询；等待期间去做其他独立工作。
• 高后果操作双钥匙：改写历史、解除/变更分支保护、删除归档引用、发布版本——Agent 只准备方案与命令，由用户确认并亲手执行；Agent 不得自行实施（baseline 硬边界 1 的授权范围要求）。
• 模块边界、公开契约与隔离档位见 policy/modules/（如有）与 PROJECT.md；验证命令见 PROJECT.md「验证」节。
• 首次克隆本仓后运行 make setup 启用本地 pre-commit 钩子。
• 治理脚本改动须运行 make test-governance（临时真实仓库覆盖正常、拒绝及异常路径，已纳入 make test）；证据、工作区和 CI 凭据边界细则见 policy/governance.md。

Gitea 与 Git 访问事实（2026-09-30 实测；登记表 policy/facts.md）

机器可核的登记表在 policy/facts.md（每条带验证命令、last_verified 与 TTL）； 引用任一事实前先跑其验证命令。以下为叙述版：

历史任务卡与旧脚本里的 git-panel.u1680832.nyat.app:30319 已失效（TLS 握手失败）， 见到一律按过期处理，不要再试。当前权威通道：

• Web / API（HTTPS）：https://git-home.u1680832.nyat.app:30319（Gitea 1.27.3， API 前缀 /api/v1；偶发 broken pipe / 超时，重试即可）。
• Git over SSH：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/<Repo>.git （.gitmodules 与各仓 origin 均为此格式）。
• API token：~/.secrets/gitea HOME/IMC 段各有 - URL_PREFIX=/- ACCESS_TOKEN=<40 hex>，本仓取 HOME 段(F2)： awk '/^HOME:/{h=1;next} /^IMC:/{h=0} h&&sub(/^- ACCESS_TOKEN=/,""){print;exit}' ~/.secrets/gitea，作 Authorization: token <值> 头。token 值不入仓、不回显、不进产出物(baseline 硬边界 2)。
• SSH key：~/.ssh/home_gitea（ED25519，公钥指纹 SHA256:GYXaOXIMeloQ1fKSfdJ/ndgPQzs/Ix7Hk62ekfkfQ20，Gitea 侧密钥名 GMKtec）； ~/.ssh/config 已有 git-ssh.u1680832.nyat.app 主机条目，克隆/推送直接可用。
• 任务卡闭合 PR（标准收口中运行 make task-close）经 API 建 PR 时以 GITEA_TOKEN 环境变量传入同上的 token。