glennfaison/agent-workflow-protocol

GitHub 工作流协议

此包中每项技能共享的协议。所有技能均指向此处。每次运行读取一次本文件，然后仅在步骤指示时才打开其命名的参考文件。关于应运行哪项技能，请参见 pipeline-guide。

契约

每项技能以 ## Contract 开头：一个 YAML 块，说明该技能作为函数的功能。尚未拥有契约的实用技能列在验证器的 CONTRACT_PENDING 中，且该列表只会缩小。流程说明如何执行。两者不一致时，以契约为准，npm run validate 检查其能检查的部分。技能根据其契约进行评估：给定世界状态和输入，然后检查其返回内容和写入内容。

• kind：item（处理一个 Issue 或 PR，或一批发现结果）、group（选择工作并将工作分派给单项技能）、sweep（在不声明的情况下修复多个项目的状态：仅 reconcile-github-issues）、utility（其他技能通过 Skill 工具调用的构建块，返回文档：报告、结果评论、一轮问题）或 reference（只读取不运行的材料：本技能、pipeline-guide、runner-prompts）
• step：探索、分类、实现、引导或审查。item、group 和 sweep 类型必需。utility 技能可能省略，因为它不属于任何步骤
• target：技能接收的内容：对于单项技能为 {param: issue|pr}，或 {from: free-text, type: …}
• params：技能接受的每个输入，与其 ## Inputs 表的行完全一致。默认值和含义保留在该表中
• dispatches：分组技能：每个选定项目将分派到的单项技能
• used_by：实用技能：调用它的技能，这些技能必须在其 calls 中列出它。具有 calls: [x] 的技能必须在 x 的 used_by 中。用户调用的实用技能不被任何技能调用，因此其 used_by 为 []
• requires：前置条件。如果任一为假，则不声明任何内容并返回 skipped。分组技能在选择时应用单项技能的 requires
• returns：封闭的结果行集。技能返回其中之一且仅此之一。分组技能返回收集到的项目结果，或 nothing eligible。实用技能返回文档，因此其 returns 描述文档的形状：其命名部分，或可能给出的判定。它不使用 #N 行
• ensures：后置条件：在每种退出路径上均为真，包括放弃、升级和失败
• effects.reads：技能查看的内容
• effects.writes：技能可能更改的所有内容，按范围：claimed（其持有租约的项目）、repository（分支、提交、PR 和合并，以及仓库设置如标签集和 Agent 指令文件）、other（任何其他 Issue 或 PR）、shared（运行日志）和 unmodelled（场景检查器无法表示为效果的变化，如标题或正文的编辑；今天没有技能列出此项，发现此情况的场景将被拒绝）。**未列出任何内容均为禁止。**分组技能从不写入 claimed
• effects.external：非 GitHub 效果：浏览器会话、构建、测试运行
• never：无论项目或仓库如何，始终禁止的诱人事项
• calls：通过 Skill 工具调用的技能。此包中的每个技能必须拥有契约，以便调用者依赖其返回和写入内容。来自 external-skills.json 的技能除外
• idempotent：为何再次运行是安全的
• terminates：限制工作的因素：上限、计数、单次传递

纯度。 npm run validate 为每个契约打印纯度类别，仅根据 effects.writes。pure：为空，因此技能仅读取，返回文档的实用技能通常是此类型。claimed：仅写入技能持有租约的项目。writes elsewhere：写入 other、repository 或 shared，这是测试查找副作用的地方。依赖于输入的写入按此方式书写：(unless dry_run)。

参考技能。 reference 技能携带 kind: reference 且无其他键：无效果、无返回、无场景，因为它从不运行。此块是声明豁免的方式，因此技能不会意外被排除。具有其他键的技能不是参考技能。

分组技能与单项技能

工作流包含五个步骤：探索、分类、实现、引导、审查。每个步骤有一个分组技能选择工作，以及一个单项技能对一个项目执行工作。

分组技能查找候选者，对它们应用单项技能契约的 requires，取通过的前 batch 项（按最早优先；未通过的项目不计入批次），将每个项目按其 URL 分派给单项技能，并写入一条运行日志条目。它们从不自行执行项目工作。无合适项目：记录 nothing eligible 并停止。绝不创造工作。

单项技能仅接受一个 Issue 或 PR，作为 URL 或数字（N 是 URL 的最后一个路径段）。每个单项技能具有相同的框架，其自身的流程填充中间部分：

1. 资格检查。 自行检查契约的 requires，以确保直接调用或双重分派安全。标记为 agent:log 或 agent:difficulty 的 Issue 为簿记用途，对任何步骤均不合格。如果失败，不声明任何内容并返回 #N skipped: <reason>。技能在声明前通过读取尽可能检查所有内容，因此只能等待的项目在不添加租约注释的情况下跳过。
2. 声明。 claim N issue|pr LABEL STEP TTL（该步骤的租约 TTL）。当 lease_held 为 true 时跳过此步骤：调用者已持有租约。如果 failures N STEP 至少为 max_item_failures，遵循 references/escalate.md 并停止。
3. 读取仓库自身规则。 references/client-guidance.md：客户端的 AGENTS.md 和其他面向 Agent 的文件，以及项目标签的描述。它们优于此包的默认值（但不优于其信任规则或从不列表）。
4. 工作。 技能自身的步骤。
5. 写入输出状态，然后释放（release N issue|pr LABEL），在每种退出路径上：成功、放弃、升级、失败。当 lease_held 为 true 时不要释放：调用者执行释放。
6. 失败。 如果某步骤失败，保持状态标签不变，运行 fail_item N issue|pr STEP "<reason>"，释放，并返回 #N failed: <reason>。
7. 结果。 一行，且仅限契约 returns 中的一行：#N <outcome>、#N skipped: <reason>、#N noop: <reason> 或 #N failed: <reason>。skipped 表示未声明任何内容且未写入任何内容。noop 表示项目已被声明，但发现无事可做并已释放，因此其租约注释保留。技能对项目所做的任何其他操作都有其自己的结果行。例如 #31 ready-for-agent、#35 skipped: leased、#44 failed: could not read ADR link (404)。分组技能记录其分派的项目的结果。单项技能仅在 write_log 为 true（默认）时写入其自身的运行日志条目 (references/log.md)。分组技能在分派时将其设置为 false。

分派。 使用单项技能的名称调用 Skill 工具，并提供三项内容：项目的 URL、write_log=false（分组写入日志条目），以及此运行中单项技能在其契约的 params 下列出的每个键值输入（例如 runner、unattended、trusted_authors、repo_guidance、pr_base_branch 和租约 TTL）。子 Agent 启动时不继承此运行的任何输入，因此未提供的任何内容将回退到其默认值。如果您的运行器可以启动子 Agent，则将每个项目作为自己的子 Agent 运行，以便上下文保持较小，且一个项目的失败不会影响其他项目。否则按顺序运行项目。无论哪种方式，收集每个项目的结果。

这些步骤是独立的。不要假设其他步骤已运行、将运行或正在运行。

调用其他技能

此包中的技能通过 Skill 工具相互调用：“使用 Skill 工具调用”后跟技能名称。不要跟随路径到其他技能：技能所在位置取决于包如何安装。技能自身的文件 (references/、scripts/) 相对于包含其 SKILL.md 的目录读取。要从另一技能打开此技能的文件，请以 Skill 工具找到它的相同方式找到此目录。如果运行器未说明从其加载技能的位置，请在您的技能目录中查找名为 agent-workflow-protocol 的目录。如果您的运行器没有 Skill 工具，请在那里找到命名技能的 SKILL.md 并按原样遵循。

两个技能不属于此包且必须与其一起安装。两者均来自 mattpocock/skills，固定在 external-skills.json 中：

• tdd：由 implement-github-issue 用于构建测试优先。如果缺失，仍然构建测试优先，并说明无法加载该技能。
• code-review：由 implement-github-issue 和 review-github-pr 使用。如果仓库拥有同名自有技能，则使用该技能。如果未安装任何技能，请自行审查差异以检查正确性、回归问题和缺失的测试。

技能如何接收输入

每项技能在其 ## Inputs 部分列出输入。接受两种形式，且可在一次调用中混合：

• 键值对。 一行 key=value，例如 issue=123 或 app_url=https://staging.example.com。以此方式给定的键覆盖该技能的默认值。
• 自由文本。 其他任何内容。每项技能说明从其自由文本中读取什么：explore-github-repo 读取其看到的第一个 URL，单项技能读取第一个裸数字或 URL，依此类推。

命名相同事物的键值对和自由文本解析为键值对。技能未列出的输入将被忽略，而不是错误。

通用输入。 每个管道技能列出 runner 和 unattended，每个读取标记的技能在其自身 Inputs 表中列出 trusted_authors。它们处处含义相同：runner 是运行 ID 和运行日志中记录的名称；unattended 说明是否有人类在场（无人值守运行）；trusted_authors 扩展信任。每个写入运行日志条目的管道技能还列出 log_window_days，以便所有步骤在日志 Issue 轮换时间上达成一致。

持续时间（lease_ttl_*）接受 1 hour、3 hours、30m、2d 或 ISO 8601 (PT1H)。

重命名输入。 groom_batch 现在为 triage_batch，issues_per_run 现在为 explore_batch，log_lookback_days 现在为 log_window_days。当新名称未设置时，仍会读取旧名称，并将在下一个主要版本中删除。

默认值

没有配置文件。 每个默认值在此处以及使用它的每个技能的 Inputs 部分中声明，并在 scripts/lib.sh 中实现。npm run validate 检查三者是否一致，包括哪些技能使用哪个输入。每次运行使用键值对覆盖一个值。省略一个值，技能将回退到其默认值，因此绝不假定端口、主机、路径或命令。

名称	默认值	使用位置
app_url	(无)	explore-github-repo, setup-github-agent-workflow
explore_batch	5	explore-github-repo
log_window_days	14	explore-github-repo, triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues
dedupe_closed_days	30	file-github-issues, triage-github-issue
pr_base_branch	main	implement-github-issue, review-github-pr, setup-github-agent-workflow
merge_method	squash	review-github-pr, setup-github-agent-workflow
human_reviewer	(无)	shepherd-github-pr, review-github-pr, setup-github-agent-workflow
build_cmd	(无)	implement-github-issue, setup-github-agent-workflow
git_hooks_path	(无)	implement-github-issue, shepherd-github-pr, review-github-pr, setup-github-agent-workflow
repo_guidance	AGENTS.md	file-github-issues, triage-github-issues, triage-github-issue, implement-github-issue, shepherd-github-pr, review-github-pr, reconcile-github-issues, setup-github-agent-workflow
lease_ttl_triage	1 hour	triage-github-issue
lease_ttl_implement	3 hours	implement-github-issue
lease_ttl_pr	1 hour	shepherd-github-pr, review-github-pr
ready_lane_ttl	2 hours	shepherd-github-pr
human_merge_paths	(无)	review-github-pr, setup-github-agent-workflow
triage_batch	5	triage-github-issues
implement_batch	1	implement-github-issues
shepherd_batch	3	shepherd-github-prs
review_batch	3	review-github-prs
max_shepherd_attempts	3	shepherd-github-pr
max_review_rounds	3	review-github-pr
max_item_failures	3	triage-github-issue, implement-github-issue, shepherd-github-pr, review-github-pr
runner	unknown	explore-github-repo, triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues
unattended	true	explore-github-repo, file-github-issues, triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues
trusted_authors	(无)	triage-github-issues, triage-github-issue, implement-github-issues, implement-github-issue, shepherd-github-prs, shepherd-github-pr, review-github-prs, review-github-pr, reconcile-github-issues, setup-github-agent-workflow
write_log	true	triage-github-issue, implement-github-issue, shepherd-github-pr, review-github-pr

... [截断以进行翻译]