185 lines
18 KiB
Markdown
185 lines
18 KiB
Markdown
# Agent 工作说明（Agent-System-Dev）
|
||
|
||
本仓开发遵循 Development-Guidelines（见 `deps/development-guidelines`，gitlink 固定版本）：
|
||
核心规则与术语见其 `core/`，按任务触发阅读 `standards/` 专题；通用交付依据为 `workflows/delivery.md`。
|
||
本项目的需求、设计试验、实施调整及交付**必读 [policy/delivery.md](policy/delivery.md)**：
|
||
目标、范围和交付终点一次确认；范围内的分析、方案、实施、修复、验证、代码 Review、
|
||
PR 合入及安全收口由智能体连续推进。只在目标/范围/验收条件变更、存在会影响用户结果的
|
||
重大取舍、触及高后果操作，或业务验收必须由用户判定时请求人工决策。智能体解决冲突并确认
|
||
当前 HEAD 的 CI 通过后执行合入，无需另请人工操作。具体决策点、版本及授权条件见
|
||
policy/delivery.md。
|
||
|
||
## 立即生效的最高优先级（强制）
|
||
|
||
- 在既有授权与强制安全边界内，**先交付用户明确要求的产物**。不得用基础设施、工具治理、
|
||
通用化、加固、重构或“以后可能用到”替代当前目标；尤其禁止把简单 Markdown、配置或说明
|
||
修改擅自升级成平台、框架、自动化系统或大规模工程。
|
||
- 采用最小充分实现：先让目标可用、系统可用并通过最小直接验证，然后立即停止并交付；体验、
|
||
结构、性能与治理完善必须作为后续独立增量，不得拖延当前结果。
|
||
- 只修复直接阻塞目标、可用性、明确验收条件或强制安全门禁的问题。高价值非阻塞项只简记，
|
||
低影响噪音直接忽略；Review/迭代循环只围绕阻塞项，阻塞项闭合即结束。
|
||
- 测试与风险成比例：实施中只跑最小直接检查；完整/长耗时套件仅在最终候选、规范明确要求或
|
||
实际影响面确有必要时运行一次。禁止在每个小文档、配置或 adapter 修改后重复全量测试。
|
||
- 编排成本不得超过任务本身。实施、修复与测试按 AGENT-EXECUTION.md 的候选和尝试上限调度；
|
||
不限制单次 CLI 的推理时长、工具次数、规划方式或首次写文件时间。除非用户明确要求或已有证据
|
||
证明是当前目标的直接阻塞，否则不得新增嵌套控制器、额外 worktree、复杂收据体系或新架构。
|
||
执行路由是手段，不能成为推迟用户产物的理由。
|
||
|
||
## 任务目标与范围（强制）
|
||
|
||
- 执行优先级固定为：授权与安全边界 → 本次任务目标和系统可用 → 阻塞目标的必要问题 →
|
||
非阻塞改进。完成标准是已批准验收条件成立且受影响系统保持可用，不是把所有附近问题一并清零。
|
||
- 绝对禁止私自扩大范围。影响目标的问题仅在既有授权内作最小充分修复；必要修复超出范围时，说明
|
||
阻塞、最小扩围和影响，取得授权后再做。“相关”、“顺手”或“更完美”不构成扩围授权。
|
||
- 新发现按对当前目标的影响分流：阻塞验收、导致不可用/明确回归、违反安全边界或必需门禁失败的问题必须
|
||
处理；其余不阻塞交付。只有具备明确影响和后续价值的非阻塞问题才记录，不为低影响噪音制造新任务。
|
||
- 先实现端到端可用和可验证的最小闭环，再将体验、结构、性能及治理优化作为独立增量迭代；非阻塞 Review
|
||
意见不得阻止当前目标交付。
|
||
|
||
## 实施执行路由（强制）
|
||
|
||
- 实施、修复、测试与审阅调度**必读根目录 [AGENT-EXECUTION.md](AGENT-EXECUTION.md)**（唯一项目执行路由配置）。通用工程 Agent 契约（agent-per-unit 隔离执行、会话独立、JSON 终态收据、无 host 隐式代写、受控 transport/admission 准入）遵循 Development-Guidelines [core/baseline.md（硬边界 8）](deps/development-guidelines/core/baseline.md) 与 [standards/agent-execution.md](deps/development-guidelines/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` 终态记录（schema 写在 worker 提示词中）；缺失或无效即 fail closed。
|
||
三者都安全耗尽后，才允许一次全新的 Codex CLI 紧急尝试。Codex 平时只用于规划、方案设计、实施计划
|
||
或独立 Review，不进入这三个正常角色。`fallback_to_host` 为 `never`。安全耗尽不发出
|
||
host-fallback-authorized，终态为 unavailable 或 blocked，不授权 host 撰写该单元。旧值
|
||
`all-unavailable` 仍可解析，同样不产生 host 撰写授权。
|
||
- 显式 fail-stop 立即停止，不重试、不换候选、不启动紧急尝试：`failed-unknown`、`scope-expansion`、
|
||
`blocked`、`cancelled`、无效配置、未对账 Git 状态与安全失败。总超时，以及 stdin/stdout/stderr
|
||
都没有活动的空闲超时，归入 `failed-unknown`。
|
||
- 一次尝试只在显式终态失败、进程退出、总超时或上述空闲超时时结束。CLI 可在目标、范围与安全边界内
|
||
自主检查、计划、测试并迭代。
|
||
- 实施变更只经成功 transport 由 `scripts/agent_exec.py apply` 集成，或由 pre-commit `admit` 按精确内容
|
||
做本地完整性核对。本地 HMAC 历史与该钩子只是本地完整性/篡改证据（SELF），不是 GATE、可信身份，
|
||
也不防同一主机 OS 用户；本地记录缺失或无效仍拒绝，交付信任只来自精确 HEAD 的 CI 或独立 REPLAY。
|
||
host 直接管理的豁免只有 `.task/**`、`docs/superpowers/specs/**` 与
|
||
`docs/superpowers/plans/**`。host 不直接撰写实施单元。细则见
|
||
[policy/delivery.md](policy/delivery.md) 与 [policy/governance.md](policy/governance.md)。
|
||
不削弱 goal-first、严格范围、先可用、独立 Review、证据、平台准入与高后果双钥匙规则。
|
||
|
||
### 阶段与会话隔离（强制）
|
||
|
||
- 需求分析、方案、设计、计划、实施、测试、Review 与验收默认各启动一个全新会话；不同阶段、
|
||
不同实施单元不得复用同一 CLI 会话、conversation、thread 或 session。
|
||
- Review 必须由当前主模型执行，或交给**全新且独立**的 CLI session。绝对禁止实施者使用原 session
|
||
通过 `continue`、`resume`、conversation ID、session ID/路径或等价机制继续充当评审者。
|
||
- 独立评审只接收固定的目标/需求、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` 检查目标仓库中是否有接纳中的大任务集成分支（`branch_kind=initiative` 且 `accepting_requirements=true`）。三态分流：`JOIN`（建立对应大任务的子任务 `make task-start KIND=child INITIATIVE=feature/<initiative> NAME=feature/<initiative>-<slug>`）、`NEW`（建立普通任务或新的大任务 `make task-start [KIND=initiative] NAME=feature/<slug>`）、`DECISION_REQUIRED`（存在多个候选或改变范围/优先级，由人工决策）。
|
||
- 任务启动或恢复后，**第一次项目写操作前**通过
|
||
`RECEIPT=/tmp/<本次唯一名称>.json CMD="make precheck" make evidence` 运行一次启动检查并保存
|
||
完整脱敏收据（不要求已有任务卡）；按输出完成必读。`SHARED_WORKSPACE_BUSY / SYNC_REQUIRED /
|
||
REMOTE_UNVERIFIED` 均不得进入写入流程；失败后排除原因再启动，不把缓存远端当最新事实。
|
||
- 新任务运行 `make task-start NAME=feature/<slug> PRECHECK_RECEIPT=/tmp/<本次唯一名称>.json`，
|
||
建立独立 worktree 与任务卡并导入首次收据。恢复已有登记任务在原 worktree 用
|
||
`make task-resume PRECHECK_RECEIPT=/tmp/<本次唯一名称>.json` 验证并原样导入收据。
|
||
默认 delivery 要求严格 READY；局部恢复接口、启用条件与旧收据处理见 [开发门禁](policy/governance.md#启动与恢复)。任务中途不重复启动检查。
|
||
- **分支层级**：任务分支一律从权威 `origin/main` 切（`task-start` 已强制）；同批互不依赖的
|
||
子任务用同一 R0 的兄弟分支。确有顺序依赖需从父 feature 分支切子分支时（collaboration.md
|
||
允许的堆叠例外）：启动命令增加 `PARENT=feature/<父slug> PARENT_PR=<父PR链接>`，
|
||
任务卡记录主干 R0、父分支及其 SHA、父 PR；子分支命名 `<type>/<父slug>-<子题>`，
|
||
不嵌 SHA；合入顺序固定父→子；父合入后子分支须 `make task-sync` 并入最新 main 并把 PR
|
||
base 改回 main，方可声明可合入（分支保护要求 head 含 origin/main，未同步必被拦）。
|
||
- **验收、请求审核、合入前**各运行一次 `make task-sync`；完成声明的 precheck、task-sync、
|
||
测试三段输出由 `make evidence` 写入任务卡（见「证据与验证门禁」），不手抄。
|
||
- **多个分支交付 / CI 调度**：先读 [合入调度](policy/merge-queue.md)，核对采纳状态、协调者、
|
||
记录及当前窗口。新模式尚未启用时保留既有同步节点；启用后最终同步至合入核验共用窗口，
|
||
同基线 `task-sync` 只核验，固定后检查用源码外 RECEIPT 保存（见 [证据流程](policy/governance.md#候选固定前后)）。
|
||
- 合入后核对所有写者退出；能从当前会话、进程、锁与工作区状态证明时，智能体在
|
||
**已登记任务 worktree 根目录**运行
|
||
`TASK_WRITERS_STOPPED=1 make task-finish`。父子仓改动、未跟踪/ignored 唯一文件先保存或显式处置；删除被拒时
|
||
保留现场并按原因处理，禁止强删兜底；无法证明写者已退出时才请 owner 确认。放弃未合入工作用
|
||
`make task-finish ABANDON="--abandon <原因>"` 并记录原因；放弃不豁免现场保护。
|
||
- **任务卡闭合（防欠账）**：分支合入 main 后，其任务卡须回填"已完成"+主记录 PR 链接并
|
||
归档至 `.task/archive/`。`task-finish` 回收后按提示运行 `make task-close`，不借回收修改
|
||
共享主检出或推送另一任务。主检出 pull/merge 的 post-merge 钩子仅提示待办，不自动写入或推送。
|
||
`make task-close` 会提交、推送并可能创建 PR，标准闭合属于已授权交付的收口；仍须核对只包含本任务卡，否则停止扩围。闭合在主检出运行→建
|
||
`feature/card-close-*` 分支+PR，任务分支内加 `FOLD=--fold` 随当前 PR 合入。
|
||
precheck 的 `[cards]` 行报告欠账，验收前应清零；闭合 PR 同样由智能体按
|
||
policy/delivery.md 完成 Review、冲突处置及当前 HEAD 的 CI 核验后合入。
|
||
|
||
## 证据与验证门禁（强制）
|
||
|
||
原则：**「声明已就位」≠「能力已就位」**。任何来源（用户输入、方案、报告、他人或自己的
|
||
叙述）的结果声明都不是证据；证据 = 命令 × 被测对象 SHA × 可复核输出，三者齐备才算事实。
|
||
规范依据：guidelines `standards/verification.md`「声明与证据来源」（draft.10）。
|
||
|
||
- **来源三分**：产出物（任务卡、PR、报告、review 结论）中的通过类断言须标注来源——
|
||
`GATE`（可核验身份及固定对象的 CI/受信执行器）/ `REPLAY`（独立审阅者的重跑记录）/
|
||
`SELF`（作者或本地工具记录，含 precheck）。工具写入、摘要和来源标签不提升可信等级。
|
||
合入与验收须核验 GATE 的运行链接/身份及 SHA，或 REPLAY 的独立审阅者、命令和对象；
|
||
本地 evidence 只生成 SELF，不能靠 `SRC` 自行升级；与重验不一致时以重验为准。
|
||
- **证据由工具写入**：命令输出进入任务卡/PR 一律经 `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 合入。
|
||
- **高后果操作双钥匙**：改写历史、解除/变更分支保护、删除归档引用、发布版本——Agent 只准备
|
||
方案与命令，由用户确认并亲手执行；Agent 不得自行实施（baseline 硬边界 1 的授权范围要求）。
|
||
- 模块边界、公开契约与隔离档位见 `policy/modules/`（如有）与 PROJECT.md。
|
||
- 验证命令见 PROJECT.md「验证」节；完成声明的三段输出按「证据与验证门禁」节由
|
||
`make evidence` 写入任务卡，不手抄。
|
||
- 首次克隆本仓后运行 `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`，两行键值 `URL_PREFIX=…` 与
|
||
`ACCESS_TOKEN=<40 位 hex>`；取值 `grep ACCESS_TOKEN ~/.secrets/gitea | cut -d= -f2-`，
|
||
用作 `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。
|