weichen/Agent-System-Dev
1
0
Fork 0
Code Issues 1 Pull Requests 6 Actions 4 Packages Projects Releases Wiki Activity
Files
39d69e681b1668dbca3f31fe86d2a8ae17b47c80
Agent-System-Dev/AGENTS.md
T
weichen 4629b871db Connect delivery windows and recovery to the repository rules 
Why: agents need consistent entrypoints and recording defaults to avoid retrying synchronization and CI outside the final delivery window.

Evidence: SELF generated-task-card red-green regression and governance suite recorded through make evidence; pending shared record created as Issue #518.

Impact: rules, task template and capability matrix stay explicit about pending activation, default strict startup, manual coordination and unchanged CI triggers.

Refs: U4; policy/merge-queue.md; .task/feature-merge-queue-policy-draft.md
2026-10-13 08:21:46 +00:00

9.8 KiB
Raw Blame History

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

本仓开发遵循 Development-Guidelines（见 deps/development-guidelines，gitlink 固定版本）： 核心规则与术语见其 core/，按任务触发阅读 standards/ 专题；通用交付依据为 workflows/delivery.md。 本项目的需求、设计试验、实施调整及交付必读 policy/delivery.md： 需求、方案、实施与验收默认逐阶段人工评审，阶段内迭代、按影响回退；代码 Review 与 PR 合入由智能体负责，解决冲突且当前 HEAD 的 CI 通过后执行合入，无需另请人工操作。 具体评审、版本及授权条件见 policy/delivery.md；其他阶段仅在用户明确授权范围内连续推进。

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 处理，过期事件丢弃。

任务启动门禁（强制）

  • 任务启动或恢复后，第一次项目写操作前通过 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；局部恢复接口、启用条件与旧收据处理见 开发门禁。任务中途不重复启动检查。
  • 分支层级：任务分支一律从权威 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 调度：先读 合入调度，核对采纳状态、协调者、 记录及当前窗口。新模式尚未启用时保留既有同步节点；启用后最终同步至合入核验共用窗口， 同基线 task-sync 只核验，固定后检查用源码外 RECEIPT 保存（见 证据流程）。
  • 合入后由工作区 owner 确认所有写者退出，在已登记任务 worktree 根目录运行 TASK_WRITERS_STOPPED=1 make task-finish。父子仓改动、未跟踪/ignored 唯一文件先保存或显式处置；删除被拒时 保留现场并按原因处理，禁止强删兜底。放弃未合入工作用 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。
Reference in New Issue View Git Blame Copy Permalink