1k-monitor-pr-ci

PR の CI とレビューを監視

プルリクエストの CI チェックとレビューコメントを監視します。CI の失敗を自動修正し、インラインレビューコメントに対応し、レビュアーに返信してスレッドを解決します。

一度だけ実行する、コンテキストをあまり使わない PR ステータスの要約には、次を使用します。

yarn agent:check --profile ci --pr <PR_NUMBER>

監視の自動化には、安定した機械可読の仕様を優先してください。

yarn agent:check --profile ci --pr <PR_NUMBER> --json-file /tmp/agent-check.json

ターミナルのテキストを解析する代わりに、/tmp/agent-check.json を読み取ります。レポートには schemaVersion: 1、トップレベルの status／exitCode／failureReasons と、 安定した構造のネストされたオブジェクト remote.pr、remote.checks、remote.review が含まれます。

モニターを開始せずに特定のレビュースレッドに返信して解決するには、次を使用します。

yarn agent:review-thread --pr <PR_NUMBER> --list
yarn agent:review-thread --pr <PR_NUMBER> --thread <THREAD_ID> --reply-file <FILE>

--list または remote.review.threads.unresolvedItems[].id から GraphQL スレッド ID を使用してください。数値のインデックスは --dry-run での検証にのみ使用します。

ユーザーがポーリング、自動修正、またはレビュースレッドの一括処理を希望する場合にのみ、この監視ワークフローを使用してください。

使用方法

/1k-monitor-pr-ci https://github.com/OneKeyHQ/app-monorepo/pull/10717 3m
/1k-monitor-pr-ci 10717 5m
/1k-monitor-pr-ci https://github.com/OneKeyHQ/app-monorepo/pull/10717
/1k-monitor-pr-ci 10717
/1k-monitor-pr-ci

入力

$ARGUMENTS — スペースで区切られた 2 つの部分：

1. PR 識別子（現在のブランチに PR がない場合は必須）：PR 番号、GitHub PR URL
2. ポーリング間隔（省略可、既定値は 6m）：例：30s、1m、2m、3分钟、5min、6m

$ARGUMENTS が空の場合は、現在のブランチから PR を自動検出し、既定の間隔 6m を使用します。

ステップ 0：初期設定

1. 引数を解析する：$ARGUMENTS を PR 識別子とポーリング間隔に分割します。

   • PR 識別子：数値、または https://github.com/{owner}/{repo}/pull/{number} のような URL
   • ポーリング間隔：時間パターン（数字＋時間単位）に一致する任意のトークンを指定します。認識する単位：s／sec／秒、m／min／分钟／分。既定値：6m
   • $ARGUMENTS が空の場合、現在のブランチから PR を検出します：

     gh pr list --head "$(git branch --show-current)" --json number --jq '.[0].number'
     

   • PR が見つからず、引数も指定されていない場合は、ユーザーに PR リンクを尋ねます。

2. owner/repo を特定する：

   • GitHub の完全な URL が指定されている場合は、そこから owner と repo を抽出します。
   • それ以外の場合は、ローカルリポジトリから検出します：

     gh repo view --json owner,name --jq '"\(.owner.login)/\(.name)"'
     

3. 確認して開始する（以降の質問は不要）：

   Monitoring PR #10717 (OneKeyHQ/app-monorepo)
   Polling interval: 3m
   Starting...
   

ステップ 1：ポーリングループ

各反復（[Check N/30]）：

1a. agent-check JSON を取得する — 毎回必ず実行

唯一の読み取り手段として agent:check を使用します。CI チェック、PR メタデータ、 インラインコメント、GraphQL のレビュースレッド状態を取得し、安定した schemaVersion: 1 の JSON レポートを書き出します。

AGENT_CHECK_JSON="$(mktemp -t agent-check.XXXXXX.json)"
yarn agent:check --profile ci --pr <PR_NUMBER> --json-file "$AGENT_CHECK_JSON" || true

agent:check の終了コードがゼロ以外でも、それだけを理由にコマンドの失敗と判断しないでください。 監視の用途では、ゼロ以外の終了コードは、保留中の CI、失敗した CI、未解決のレビュースレッド、下書き PR、マージを妨げる状態、 またはレビュー情報の切り捨てなど、対応が必要な状態が JSON に含まれていることを示します。

JSON レポートから次のフィールドを読み取ります。

• status、exitCode、failureReasons
• remote.pr.{number,url,state,reviewDecision,mergeStateStatus,isDraft}
• remote.checks.counts、remote.checks.failed、remote.checks.pending、remote.checks.gateFailed
• remote.review.threads.{unresolved,activeUnresolved,dataComplete,unresolvedItems}
• remote.review.changesRequestedBy

フォールバック：agent:check を利用できない場合、またはサポートされていない schemaVersion が返された場合は、同じ 4 つのシグナルについて gh のクエリを直接使用します。スレッド ID と解決状態の取得には GraphQL が引き続き必要です。GraphQL が失敗した場合は、インラインコメントに対して REST API にフォールバックします。

gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
  --jq '.[] | {id: .id, body: .body, path: .path, line: .original_line, user: .user.login, in_reply_to_id: .in_reply_to_id, created_at: .created_at}'

注：REST フォールバックではコメントの取得と返信はできますが、スレッドは解決できません（GitHub では GraphQL 経由でのみサポートされています）。REST フォールバックを使用する場合は、解決の手順（ステップ 3d）を省略し、スレッドを手動で解決する必要があることを警告として記録してください。

未解決のスレッド（isResolved: false）のみを対象にします。最後のコメントが現在の gh ユーザーによるもののスレッド（すでに返信済み）はスキップします。

1b. ステータスの概要を表示する

[Check 3/30]

CI Status:
| Check            | Status  | Duration |
|------------------|---------|----------|
| lint (24.x)      | pass    | 5m34s    |
| unittest (24.x)  | pending | -        |

Unresolved threads: 3
- src/views/Example.tsx:42 (@reviewer): "Consider using useCallback here"
- src/utils/format.ts:15 (@reviewer): "This should handle null case"
- src/components/Card.tsx:88 (@reviewer): "Typo in variable name"

1c. 次のアクションを決定する

アクションを選択する前に、agent:check の JSON を次の3つに分類します。

• 通常の失敗チェック：remote.checks.failed
• ゲートの失敗：remote.checks.gateFailed
• 保留中のチェック：remote.checks.pending

release-ready-merge-gate が失敗している場合は、自動修正する CI の失敗ではなく、想定されるマージブロッカーとして扱います。

CI ステータス	未解決のスレッド	アクション
通常の失敗チェック	-	CI の失敗を自動修正する（ステップ 2）
ゲートの失敗	スレッドあり	スレッドに対応する（ステップ 3）。その後、release-ready がないためブロックされていると報告する
ゲートの失敗	スレッドなし	待機を終了し、release-ready がないためブロックされていると報告する
保留中のチェックあり	スレッドあり	スレッドに対応する（ステップ 3）。CI の完了を引き続き待つ
保留中のチェックあり	スレッドなし	待機して再確認する
すべて成功	スレッドあり	スレッドに対応する（ステップ 3）
すべて成功	スレッドなし	完了（ステップ 4）

ステップ 2：CI の失敗を自動修正する

失敗したチェックごとに、次の手順を実行します。

1. 最新のポーリング結果から、対応が必要な失敗チェックを特定します。

   • 以前のイテレーションの古い出力ではなく、現在のイテレーションの remote.checks.failed の出力を使用します。
   • 失敗したチェックの name と link を保持します。
   • 再実行すると、先のエラーを修正した後、同じチェック内で別の失敗が明らかになることがあります。たとえば、lint (24.x) は最初にフォーマットで失敗し、その後、パッケージバージョンの整合性で再び失敗する場合があります。プッシュ後に同じチェック名で再度失敗した場合は、新たなステップ 2 の項目として扱い、通常の失敗チェックがなくなるまで修正を続けます。

2. 失敗したチェックの link から RUN_ID を導き出します。

   • リンクの例：
     • https://github.com/{owner}/{repo}/actions/runs/<RUN_ID>/job/<JOB_ID>
     • https://github.com/{owner}/{repo}/runs/<RUN_ID>
   • URL から <RUN_ID> を抽出し、ログを取得するときにその実行を正確に指定します。

3. 失敗ログを取得します：

   gh run view <RUN_ID> --log-failed 2>&1 | tail -100
   

4. 失敗を分析し、原因を特定します。

5. 修正可能（lint エラー、型エラー、今回の変更によるテスト失敗）：

   • コードを修正します
   • コミットします：fix: resolve CI <check-name> failure
   • PR ブランチにプッシュします
   • 30 秒待ってから、ステップ 1 に戻ります

6. 無関係または既存の可能性がある（リポジトリ全体のパッケージ／バージョン整合性の失敗、PR で変更していないファイルの失敗、または PR より前から発生しているように見える問題）：

   • origin/x と照らし合わせて簡単に確認するか、失敗条件が PR の差分外にもすでに存在するかを調べます。
   • 同じ失敗がベースブランチにもすでに存在する場合は、PR の作業で修正したかのように扱わず、既存のブロッカーとして報告します。
   • この PR でブロッカーも修正するか、無関係な問題として残すかをユーザーに確認します。

7. 修正不可能（インフラの問題、不安定なテスト、またはユーザーがここでは修正しないことを希望する無関係な失敗）：

   • 失敗の詳細をユーザーに報告します
   • 再実行、スキップ、手動修正などの対応を提案します
   • どのように進めるかをユーザーに確認します

ステップ 3：レビューのスレッドに対応する

未解決のスレッドごとに、次の手順を実行します。

3a. コメントを分類する

コメント本文と関連するコードのコンテキストを読み、次のように分類します。

• コード修正が必要 — ファイルの変更が必要 → 自動修正
• 質問 — 説明だけが必要で、コード変更は不要 → 自動返信
• 同意できない／修正しない — 返信する前に必ずユーザーに確認します。同意できない意見を自動で解決してはいけません。

スレッドごとに、これから行う対応を1行で記録し、その後すぐに修正を進めます。ユーザーの確認を待ってはいけません。ただし、同意できない／修正しないケースでは処理を一時停止します。

3b. コードを修正する

コード修正が必要なスレッドごとに、次の手順を実行します。

1. 指定されたパスと行のファイルを読みます
2. Edit ツールを使って修正します
3. 簡単に確認できる場合は、修正によって lint や型チェックに問題が生じないことを確認します

3c. コメントに返信する

REST API を使って、行った対応を説明する返信をします。

gh api --method POST \
  repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_database_id}/replies \
  -f body='Fixed: [concise explanation of the change]'

質問の場合（コード変更が不要な場合）：

gh api --method POST \
  repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_database_id}/replies \
  -f body='[answer to the question]'

返信は簡潔にします。何を変更し、なぜ変更したかを説明します。

3d. スレッドを解決する

返信後、GraphQL 経由でスレッドを解決します:

gh api graphql -f query='
mutation($threadId: ID!) {
  resolveReviewThread(input: {threadId: $threadId}) {
    thread {
      isResolved
    }
  }
}' -f threadId="THREAD_NODE_ID"

Note: スレッドの解決には GraphQL が必要です — 同等の REST API はありません。ステップ 1b で REST にフォールバックした場合は、このステップをスキップして次の警告をログに記録してください: 「スレッドの解決をスキップしました（GraphQL を利用できません）。手動で解決してください。」

3e. コミットとプッシュ

このイテレーションですべてのスレッドに対応した後:

1. 変更されたファイルをステージング: git add <specific files>
2. 説明的なメッセージでコミット:

   git commit -m "fix: address PR review feedback
   
   - [list each fix made]"
   

3. プッシュ: git push

3f. 再レビューを依頼する

修正をプッシュした後、コメントを残したレビュアーに再レビューを依頼します:

1. コメントを残したレビュアーを取得する（ステップ 1b のスレッドデータ、author.login フィールドから収集）

2. 再レビューを依頼:

   gh pr edit <PR_NUMBER> --add-reviewer <reviewer1>,<reviewer2>
   

   または、--add-reviewer が再レビューをトリガーしない場合は API 経由で:

   gh api --method POST \
     repos/{owner}/{repo}/pulls/{pr_number}/requested_reviewers \
     -f 'reviewers[]=reviewer1' -f 'reviewers[]=reviewer2'
   

3. ステップ 1 に戻る（CI の再実行を待つ）

ステップ 3g: リリース準備完了ゲートのブロッカーを報告する

唯一残っている失敗チェックが release-ready-merge-gate である場合は、ポーリングループを停止して次を報告します:

CI is complete, but merge is blocked by the release-ready gate.

Blocking check:
- release-ready-merge-gate: expected failure until the PR gets the `release-ready` label

Action:
- Add the `release-ready` label to the PR, then run the monitor again if needed

次のことはしないでください:

• このチェックを自動修正しようとすること
• これを不安定なインフラとして扱うこと
• これが自然に通過するのを待ち続けること

ステップ 4: 最終レポート

すべての通常の CI チェックが通過し、未解決のスレッドが残っていない場合:

All normal CI checks passed. All review threads resolved.

CI:
| Check            | Status | Duration |
|------------------|--------|----------|
| lint (24.x)      | pass   | 5m34s    |
| unittest (24.x)  | pass   | 4m42s    |

Review threads: 5 resolved, 0 remaining
PR: <URL>
Status: Ready for re-review / Ready to merge

release-ready-merge-gate が依然として失敗している場合は、この最終レポートを使用しないでください。代わりにステップ 3g のブロック状態レポートを使用してください。

ポーリングのルール

• チェック間のデフォルトは 6 分（ユーザーはステップ 0 でカスタマイズ可能）
• 修正＋プッシュ後は 30 秒、CI の再起動を許可するため
• 最大 30 イテレーション、その後ユーザーに続行または停止を尋ねる
• 常に [Check N/30] を表示する

重要な注意事項

• CI の失敗: 確認せずに自動修正
• 最初の CI エラーを修正した後、再実行で後から別の通常の失敗チェックが明らかになった場合でも停止しないでください。すべての通常の CI チェックが通過するまで、新しい失敗チェックの結果ごとにステップ 2 を続けてください。
• レビューコメント: 確認せずに自動修正 — 実行しようとしている内容の簡単な概要を表示し、すぐに続行します
• Disagree/Won't fix: 返信または解決する前に必ずユーザーに尋ねてください — これがユーザー入力が必要な唯一のケースです
• 強制プッシュやコミットの amend は決して行わないでください
• 各修正ラウンドは新しいコミットです
• 可能な場合は複数の CI 失敗を 1 つのコミットで修正してください
• チェックを自動的に再実行しないでください（ユーザーが gh run rerun を要求した場合のみ）
• コミットメッセージに「Co-Authored-By」や「Generated with」を含めないでください
• イテレーション間で重複作業を避けるため、対応済みのスレッドを追跡してください

エラー処理

• 非ブロッキングエラー: 個々のステップ（スレッドの解決、コメントへの返信、再レビューの依頼）が失敗した場合は、警告をログに記録し、次のスレッド/ステップに進んでください。単一のスレッドの失敗でループ全体を中止しないでください。
• GraphQL を利用できない: コメントの取得には REST API にフォールバックしてください。解決ステップをスキップし、警告をログに記録します。
• 返信に失敗: スレッドのパス/行とともに警告をログに記録し、次のスレッドに進んでください。コードの修正は引き続きコミットされます。
• 解決に失敗: 警告をログに記録し、続行します。スレッドは開いたままですが、修正はプッシュされています。
• 再レビューの依頼に失敗: 警告をログに記録し、続行します。レビュアーは依然としてプッシュ通知を確認できます。
• ブロッキングエラー: 次の場合はループを中止してください:
  • gh CLI が認証されていない
  • PR が存在しない
  • PR がすでにクローズまたはマージされている（各イテレーションで gh pr view <PR_NUMBER> --json state --jq '.state' を確認 — CLOSED または MERGED の場合は、停止してユーザーに通知してください）