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：Exploring、Triaging、Implementing、Shepherding 或 Reviewing。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：前置條件。如果其中一個為 false，則不聲明任何內容並回傳skipped。群組技能在選擇時會套用項目技能的requiresreturns：結果行的封閉集合。技能會回傳其中之一，而不會回傳其他內容。群組技能會回傳其收集的項目結果，或nothing eligible。工具技能會回傳一個文件，因此其returns描述該文件的形狀：其命名章節，或它可能給出的裁決。它不使用#N行ensures：後置條件：在每種退出方式（包括中止、升級和失敗）上都為 trueeffects.reads：技能查看的內容effects.writes：技能可能改變的所有內容，按範圍分類：claimed（其持有租約的項目）、repository（分支、提交、PR 和合併，以及標籤集和代理指令檔案等儲存庫設定）、other（任何其他 issue 或 PR）、shared（執行日誌）和unmodelled（情境檢查器無法將其表示為效果的變更，例如對標題或內文的編輯；目前沒有技能列出此項，且找到此項的情境將被拒絕）。任何未列出的內容都是禁止的。 群組技能永遠不會寫入claimedeffects.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 且沒有其他鍵：沒有 effects、returns、scenarios，因為它從不執行。該區塊是說明豁免的方式，因此技能不會被意外遺漏。具有其他鍵的技能不是參考技能。
群組技能與項目技能
工作流程有五個步驟：探索（Exploring）、分類（Triaging）、實作（Implementing）、守護（Shepherding）、審查（Reviewing）。每個步驟都有一個群組技能來選擇工作，以及一個項目技能來對一個項目執行工作。
群組技能尋找候選項目，將項目技能的合約 requires 套用到它們身上，取通過的前 batch 個（最舊的優先；失敗的項目不計入批次），將每個項目按其 URL 分派給項目技能，並寫入一個執行日誌條目。它們從不自行執行項目工作。無符合資格者：記錄 nothing eligible 並停止。絕不發明工作。
項目技能精確接收一個 issue 或 PR，作為 URL 或數字（N 是 URL 的最後一個路徑段）。每個項目技能都有相同的框架，並用自己的流程填滿中間部分：
- 資格檢查。 自行檢查合約的
requires，以確保直接呼叫或雙重分派是安全的。帶有agent:log或agent:difficulty標籤的 issue 是帳務記錄，永遠不符合任何步驟的資格。如果失敗，則不聲明任何內容並回傳#N skipped: <reason>。技能會在聲明前透過讀取來檢查所有可以檢查的內容，因此只能等待的項目會在不留下租約註解的情況下被跳過。 - 聲明。
claim N issue|pr LABEL STEP TTL（步驟的租約 TTL）。當lease_held為true時跳過此步驟：呼叫者已持有租約。如果failures N STEP至少為max_item_failures，則遵循references/escalate.md並停止。 - 讀取儲存庫自身的規則。
references/client-guidance.md：客戶的AGENTS.md和其他面向代理的檔案，以及項目標籤的描述。它們優先於此套件的預設值（不是其信任規則或永不列表）。 - 工作。 技能自身的步驟。
- 寫入輸出狀態，然後釋放（
release N issue|pr LABEL），在每種退出方式上執行：成功、中止、升級、失敗。當lease_held為true時，不要釋放：由呼叫者執行。 - 失敗。 如果某個步驟失敗，保持狀態標籤不變，執行
fail_item N issue|pr STEP "<reason>"，釋放，然後回傳#N failed: <reason>。 - 結果。 一行，且僅是合約
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）。子代理啟動時不會有此執行中的任何輸入，因此未提供給它的任何內容都會回退到其預設值。如果您的執行器可以啟動子代理，請將每個項目作為自己的子代理執行，以便上下文保持較小，且一個項目的失敗不會影響其他項目。否則，一個接一個地執行項目。無論哪種方式，都收集每個項目的結果。
這些步驟是獨立的。不要假設另一個步驟已執行、將要執行或正在執行。
呼叫其他技能
此套件中的技能透過 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使用。如果儲存庫有同名技能，則使用該技能。如果未安裝任何技能，請自行審查 diff 以確認正確性、回歸和缺少的測試。
技能如何接收輸入
每個技能都在**## Inputs**部分列出其輸入。接受兩種形式，且可在一次呼叫中混合使用：
- 鍵值對。
key=value獨佔一行，例如issue=123或app_url=https://staging.example.com。以此方式給定的鍵會覆蓋該技能的預設值。 - 自由文字。 其他任何內容。每個技能都會說明它從自己的自由文字中讀取什麼：
explore-github-repo取其看到的第一個 URL，項目技能取其看到的第一個裸數字或 URL，以此類推。
命名相同事物的鍵值對和自由文字會解析為鍵值對。技能未列出的輸入會被忽略，而不是錯誤。
常見輸入。 每個管線技能都在其自己的輸入表格中列出 runner 和 unattended，且每個讀取標記的技能都列出 trusted_authors。它們在各處具有相同的含義：runner 是記錄在執行 ID 和執行日誌中的名稱；unattended 表示是否有人在場（未監督的執行）；trusted_authors 擴展了信任。每個寫入執行日誌條目的管線技能也會列出 log_window_days，以便所有步驟在日誌問題輪換時間上達成一致。
持續時間 (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-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 |
...（後續內容已截斷，因應翻譯需求）