gh-issues

gh-issues

用於 issue 自動化轉為 PR。優先使用 gh CLI；僅在高階命令缺少所需欄位時，才降級回退使用 gh api。

Arguments

• 位置參數 owner/repo：可選；若未指定則從 git remote get-url origin 推導。
• --label <label>：篩選標籤。
• --limit <n>：預設 10。
• --milestone <title>：篩選里程碑。
• --assignee <login|@me>：篩選被指派者。
• --state open|closed|all：預設 open。
• --fork <owner/repo>：將分支推送到 fork，對原始 repository 建立 PR。
• --watch：持續輪詢 issue 與 review。
• --interval <minutes>：預設 5 分鐘。
• --dry-run：僅列出項目，不執行操作。
• --yes：不進行人工確認。
• --reviews-only：跳過 issue 修復；僅處理 PR review。
• --cron：啟動後立即退出；隱含 --yes。
• --model <id>：若支援，傳遞給 Worker 的模型 ID。
• --notify-channel <id>：可選的最終通知目標頻道。

Phase 1: resolve repo

git remote get-url origin
if [ -z "${GH_TOKEN:-}" ]; then
  CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/openclaw.json}"
  GH_TOKEN=$(jq -r '.skills.entries["gh-issues"].apiKey // empty' "$CONFIG_PATH" 2>/dev/null || true)
  if [ -n "$GH_TOKEN" ]; then export GH_TOKEN; fi
fi
gh auth status
gh repo view OWNER/REPO --json nameWithOwner,defaultBranchRef

若 gh auth status 執行失敗且缺乏 GH_TOKEN，請停止執行並要求提供 GitHub 認證資訊／設定。

推導出的變數：

• SOURCE_REPO：Issue 所在的原始 Repository。
• PUSH_REPO：若有設定 fork 則為 fork Repository，否則為原始 Repository。
• BASE_BRANCH：原始 Repository 的預設分支（除非使用者另有指定）。
• PUSH_REMOTE：Fork 模式下為 fork，否則為 origin。

若工作區（worktree）有未提交的變更（dirty）即停止執行，除非使用者確認 Worker 應忽略未提交的變更。

在 Fork 模式下，未經確認或在 --dry-run 期間，請勿修改 Remote 設定。

僅驗證認證與讀取權限：

gh auth token >/dev/null || test -n "${GH_TOKEN:-}"
gh repo view "$PUSH_REPO" --json nameWithOwner
git ls-remote --exit-code origin HEAD

Phase 2: fetch issues

建立篩選條件並擷取 issue：

gh issue list --repo "$SOURCE_REPO" --state open --limit 10 --json number,title,labels,url,body,assignees,milestone

根據請求加入 --label、--milestone、--assignee、--state、--limit 等參數。gh issue list 本身已自動排除 PR。

若未找到任何 issue：回報無符合項目。若指定 --dry-run：顯示精簡清單後停止。

Phase 3: avoid duplicate work

針對每個候選 issue：

gh pr list --repo "$SOURCE_REPO" --search "$SOURCE_REPO#<n>" --state open --json number,url,title,headRefName
gh pr list --repo "$SOURCE_REPO" --head "fix/issue-<n>" --state open --json number,url
gh api "repos/$PUSH_REPO/branches/fix/issue-<n>" >/dev/null

若已存在開啟中的 PR、現有分支或本機已被佔用（claim），則跳過該候選 issue。

佔用（claim）紀錄檔案：

${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/gh-issues-<owner>-<repo>.json

過期超過 2 小時的佔用紀錄將自動失效。
寫入前請確保上層目錄已建立。

Phase 4: confirm

除非指定 --yes 或 --cron，否則提示使用者選擇：

• all
• 以逗號分隔的 issue 編號
• cancel

確認之後，在 Fork 模式下，需先設定好推送的 Remote 再將工作交給 Agent：

gh auth setup-git
git remote get-url fork || git remote add fork "https://github.com/$PUSH_REPO.git"
git remote set-url fork "https://github.com/$PUSH_REPO.git"
git ls-remote --exit-code fork HEAD

Phase 5: spawn workers

最多啟動 8 個背景 Worker。在使用 --cron 時勿等待 Worker 執行完畢。

每次啟動 Worker 前，針對 SOURCE_REPO#<n> 寫入包含當前 ISO 時間戳記的佔用紀錄。Worker 回報 PR 或失敗後，移除或更新該紀錄。這能在分支或 PR 建立前，防止 watch/cron 模式產生重複重疊的任務。

Worker 的提示詞（Prompt）必須包含：

• Issue URL、標題、內文、標籤。
• SOURCE_REPO、PUSH_REPO、BASE_BRANCH、PUSH_REMOTE 及 Fork 模式狀態。
• 目標分支 fix/issue-<n>。
• 必要的證明與 PR 內文要求。
• 通知路由。

Worker 操作指南：

使用 gh 與 git，請勿憑空推測。
從 BASE_BRANCH 切換／建立 fix/issue-<n> 分支。
實作最小化修復。
執行相關測試。
使用 Conventional Commits 規範進行 commit。
推送到 PUSH_REMOTE。
針對 SOURCE_REPO 的 BASE_BRANCH 發起 PR。
PR 內文需包含：解決的問題 + 變更原因 + 使用者影響 + 測試／證明 + 顯式的 Fixes SOURCE_REPO#<n>。
回報 PR URL 或失敗原因。
若有提供路由，請透過 openclaw message send 傳送完成／失敗通知。

若支援，請使用 coding-agent 的啟動規則。

Phase 6: collect

透過 process 或任務註冊表輪詢 Worker 狀態。回報內容包含：

• Issue 編號 + 標題。
• 狀態：已建立 PR、已跳過、失敗、逾時。
• PR URL 或失敗原因。

僅在最終摘要時將精簡結果發送到通知頻道。

Reviews-only / watch reviews

尋找開啟中的 PR：

gh pr list --repo "$SOURCE_REPO" --state open --json number,title,url,headRefName,reviewDecision \
  --jq '[.[] | select(.headRefName | startswith("fix/issue-"))]'

擷取 Review 討論串／留言：

gh pr view <n> --repo "$SOURCE_REPO" --json url,headRefName,comments,reviews
gh api "repos/$SOURCE_REPO/pulls/<n>/comments"
gh api "repos/$SOURCE_REPO/issues/<n>/comments"

除非使用者明確指定 PR 編號，否則僅處理此工作流程建立的 fix/issue-* PR。按 PR 分組待處理的留言。忽略讚美、純狀態更新、重複及已處理的留言。針對每個選定／符合範圍的 PR 啟動一個 Worker，遵循相同的背景執行規則。

Review Worker 操作指南：

切換到 PR 分支。
閱讀所有需處理的 Review 留言。
進行最小化的修補變更。
執行相關測試。
正常 commit 並推送；除非明確指示，否則不要使用 force-push。
針對已處理的留言進行回覆，包含修復說明與 commit/檔案參照。
回報已處理／已跳過之留言與相關證明。

Watch mode

迴圈流程：

1. 擷取 issue。
2. 啟動符合條件的 Issue Worker。
3. 處理需要修復的 PR Review 留言。
4. 依據 --interval 休眠。
5. 當使用者指示停止時終止。

保持累計摘要簡短精簡。