laily/.pouch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ad6695245b237efebfd6ffe2b6d482e58fd75d71
.pouch/skills/ack/templates/project.template.md
T
laily ad6695245b feat(ack): bind test env to deployer and add regression mode 
ACK 0.19.0 hands test-environment deploys to the deployer skill,
documents bug-fix as a first-class scenario, and adds
docs/ack/regression.yaml harvest plus a /ack regression run.
2026-08-25 14:41:05 +08:00

7.5 KiB
Raw Blame History

<项目名> Agent 协作协议（项目覆盖层）

本项目基于 ACK Skill v<ack_version>。通用规范由 /ack 从 Skill 自身的 references/ 读取；本文件只保存项目差异。

本文件是「项目覆盖层」，文件名可配置。 默认放 docs/ack/project.md， 不占用 AGENTS.md，避免与团队已有的 AGENTS.md 约定冲突。 若希望 Agent 自动加载，可由项目维护者自行在 AGENTS.md 中引用本文件；ACK 不会自动修改 AGENTS.md、CLAUDE.md 或其它 Agent 指令文件。 无论叫什么，都在 tasks.yaml 的 project.overlayFile 记录实际路径。 docs/ack/ 只保存本项目的 project.md、tasks.yaml、knowledge.yaml、默认关闭的 delivery.yaml 与空的 regression.yaml， 不复制或链接 Skill。

项目概览

  • 项目：<project_name>
  • 技术栈：<tech_stack>
  • 运行命令：<run_command>
  • Base URL：<base_url>
  • 任务板：docs/ack/tasks.yaml
  • 项目知识：docs/ack/knowledge.yaml
  • 交付契约：docs/ack/delivery.yaml（默认关闭）
  • 回归目录：docs/ack/regression.yaml
  • 覆盖层文件：<overlay_file_path>（默认 docs/ack/project.md）

通用规范（由 ACK Skill 按需读取）

  • 开始需求：references/kickoff.md
  • 角色、权限、状态机与完成定义：references/roles-and-permissions.md
  • 模型档位与升级规则：references/model-routing.md
  • 闭环流程与 worktree 对齐：references/closed-loop.md
  • 验收信号与三轮策略：references/optimization-method.md
  • 派发 prompt 模板：references/prompt-templates.md
  • Orca 编排命令（可选）：references/orca-adapter.md
  • 验证后交付与配置维护（可选）：references/delivery.md
  • 回归目录与运行（可选）：references/regression.md

Worker 路由

机器可校验的模型、reasoning effort、权限模式、默认 profile、允许 worktree 和启动 receipt 全部以 docs/ack/tasks.yaml 的 project.orchestration 与顶层 workerReceipts 为准。本文件不保存可执行 worker 命令。

默认 profile：

角色 profile ID 档位
Developer codex-dev-standard standard
Test codex-test-standard standard
Developer 升级 codex-dev-strong strong

项目如改用 Cursor 或 Grok，应修改结构化 profile、allowlist 和 defaults，再运行任务板 校验；不能在这里粘贴 orca --command、Agent CLI 参数或自由 shell。 每次自动派发必须先审阅 launcher plan，再把其中的 launchFingerprint 作为 --expected-launch-fingerprint 启动 fresh worker。receiptHash 只作审计 checksum， 不授权自动复用旧终端；只有同轮空闲、身份匹配且历史消息可信清理后才可复用。

路径权限（项目覆盖层，必须填实际路径）

路径 Coordinator Test Developer 说明
<spec_paths> R/W Read-only Read-only 产品规格、API 文档、计划（PM 拥有）
<integration_test_paths> Read-only R/W Read-only 浏览器/API 回归（Test 拥有）
<test_records_path> Read-only R/W Read-only 复测记录
<source_paths> Read-only Read-only R/W 应用源码
<unit_test_paths> Read-only Read-only R/W 单元测试
<shared_config_templates> Read-only Read-only R/W 可提交配置模板
<local_config_paths> Read-only Read-only Read-only 本地私有配置
tasks.yaml R/W Read-only Read-only 只有 Coordinator 写
knowledge.yaml R/W Read-only Read-only 只有 Coordinator 写；Developer/Test 通过回报提名或验证
regression.yaml R/W Read-only Read-only 只有 Coordinator 写；Test 通过 regressionCandidates 提名
delivery.yaml 仅显式维护时 R/W Read-only Read-only 项目交付能力，不是执行授权

命令（项目覆盖层）

Developer 白盒验证：

<unit_test_command>
<build_command>
<local_run_command>

Test 黑盒复测（服务启动以 deployer 绑定的 intents.testEnvironment 为准）：

<preflight_command>
<api_smoke_command>
<browser_regression_command>

知识项的 verification.ref 只能引用 knowledge.yaml.verificationRegistry 中已 审查的检查入口。Registry 只保存仓库内相对 path 和结构化 args，不保存或执行自由 shell 命令；新项目没有知识时保持空对象。Developer/Test 只能把 registry ID 交给 Skill 的 scripts/run_verification.py 执行，不直接拼接 path/args。检查脚本从项目 根 cwd 或 ACK_PROJECT_ROOT 定位资源，不能依赖自身文件路径。 ACK_PROJECT_ROOT 是 runner 固定的根目录 fd 路径；仅用于日志的原始路径位于 ACK_PROJECT_ROOT_DISPLAY。

项目状态校验由 /ack 使用 Skill 自带的 scripts/validate_tasks.py、 scripts/validate_knowledge.py、scripts/validate_delivery.py 和 scripts/validate_regression.py 执行。 构建、测试环境部署和版本发布的机器入口以 delivery.yaml 的 intents 为准； 测试环境由 ACK 内部调用 deployer。本文件不维护第二套交付命令。

硬规则（其余见 references/）

  • 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现（验证者 ≠ 实现者）。
  • 模型分层：Coordinator 用强模型且不亲自跑测试，Test/Developer 用中低模型，必要时升级（见 references/model-routing.md）。
  • 自动 worker 只能由 ACK 的 scripts/launch_worker.py 按结构化 profile 启动； 禁止直接拼 orca terminal create --command，禁止 command、extraArgs、env 等第二配置面。
  • v0.10 自动 launcher 只支持 read-only 和 workspace-write。full-access、 bypass、YOLO/force 与关闭 sandbox 均 fail closed；需要可信平台审批通道后再开放。
  • 复用仅限同轮空闲、身份匹配且历史消息可信清理的 worker；否则重新 plan/launch。
  • 整轮结束后回收只属于 verified 任务的终端；blocked/failed/leftover 终端保留且不设 TTL。
  • worker_done 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 verified。
  • 只有 Coordinator 写 tasks.yaml、knowledge.yaml 和 regression.yaml； Developer 与 Test 都只读，通过消息回报。
  • Coordinator 只派发按 scope 命中并显式写入 knowledgeRefs 的 active 知识； candidate 不派发，知识库不全量注入。
  • Developer 回报 knowledgeApplied 与 knowledgeCandidates，Test 回报 knowledgeChecks。关键约束应下沉为测试、lint、CI 或正式规范。
  • ACK 不自动修改 AGENTS.md、CLAUDE.md 或其它 Agent 指令文件。
  • delivery.yaml 默认关闭，只描述能力，不自动授权提交、推送、发布或部署。测试环境 绑定 deployer，发版写在 intents.release；用户明确要求重新部署测试环境或发布 版本时才执行对应 intent。常规交付仍在任务 verified 且本次 profile 得到确认后 运行。回归目录在 docs/ack/regression.yaml，由用户明确要求「回归」时运行。
  • 默认交付 profile 最多到 validation_ready 或 review_ready；stable 发布或 production 部署必须有 approval 步骤并再次获得明确批准。配置变更只影响下一次 run。
  • 每个任务最多派发 3 轮，仍不过标记 leftover 并继续下一个。
  • 不提交、推送、发布或部署，除非用户确认的 ACK 任务或 delivery profile 明确包含。
Reference in New Issue View Git Blame Copy Permalink