@trim21/personal-pi-extensions 0.1.547 → 0.1.550

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.547",
+  "version": "0.1.550",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -108,6 +108,7 @@
     "minimatch": "^10.2.6",
     "octokit": "^5.0.5",
     "turndown": "^7.2.0",
+    "undici": "^7.29.0",
     "vscode-jsonrpc": "^9.0.1",
     "vscode-languageserver-types": "^3.18.0",
     "web-tree-sitter": "^0.27.0"

package/src/gh-readonly.ts

@@ -14,7 +14,7 @@
  *   - read-github-pr-comments: Get PR comments
  *   - read-github-ci-logs: Get CI workflow run logs
  *   - read-github-workflow-runs: List workflow runs
- *   - read-github-workflow-jobs: Get workflow run jobs
+ *   - get-github-workflow-jobs: Get workflow run jobs
  *   - read-github-repo: Get repo info
  *   - list-github-releases: List releases
  *   - read-github-release: Get release details
@@ -27,6 +27,11 @@
  *
  * Or for project-local:
  *   cp gh-readonly.ts .pi/extensions/
+ *
+ * Proxy (for the gh CLI and for the octokit-backed search/checks requests):
+ *   ~/.pi/agent/gh.json: { "proxy": "http://127.0.0.1:7890", "noProxy": "localhost" }
+ *   HTTPS_PROXY / HTTP_PROXY / ALL_PROXY and NO_PROXY are used instead for the
+ *   fields the config file leaves out. The config is read once per process.
  */
 
 import { spawn } from "node:child_process";
@@ -39,6 +44,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { createGhProxy } from "./lib/gh-proxy.js";
 import {
   type ActionJob,
   type CheckRun,
@@ -48,10 +54,17 @@ import {
   type GithubChecksClient,
   type GithubSearch,
   renderHits,
+  type RunJob,
 } from "./lib/github.js";
 import { type ToolPendant } from "./lib/pendant.js";
 import { createSeqState } from "./lib/seq-state.js";
 
+/**
+ * 代理配置（~/.pi/agent/gh.json，回退到 HTTP(S)_PROXY 环境变量）在本模块内共享：
+ * `gh` 子进程与 octokit 请求都从这里取，配置只在首次使用时读一次。
+ */
+const ghProxy = createGhProxy();
+
 interface GhResult {
   stdout: string;
   stderr: string;
@@ -82,16 +95,25 @@ export function isGhAvailable(): boolean {
   return false;
 }
 
-export function runGh(
+export async function runGh(
   args: string[],
-  ctx: { cwd?: string; signal?: AbortSignal; timeout?: number },
+  ctx: {
+    cwd?: string;
+    signal?: AbortSignal;
+    timeout?: number;
+    /** 追加到子进程环境变量（覆盖进程环境与代理配置），供测试或调用方定制。 */
+    env?: NodeJS.ProcessEnv;
+  },
 ): Promise<GhResult> {
+  const proxyEnv = await ghProxy.env();
+
   return new Promise((resolve) => {
     const proc = spawn("gh", args, {
       cwd: ctx.cwd,
       shell: false,
       stdio: ["ignore", "pipe", "pipe"],
-      env: { ...process.env, GH_PAGER: "cat" },
+      // gh 是 Go 程序，只认环境变量形式的代理配置；ctx.env 最后合并，调用方可覆盖。
+      env: { ...process.env, ...proxyEnv, ...ctx.env, GH_PAGER: "cat" },
     });
 
     let stdout = "";
@@ -244,6 +266,20 @@ function repoArgs(repo?: string): string[] {
   return repo ? ["--repo", repo] : [];
 }
 
+/**
+ * `gh api` for a JSON-array endpoint, following pagination. The REST API pages
+ * these lists at 30 items by default, so a single page silently drops the rest;
+ * `--slurp` is required because `--paginate` alone prints the pages back to back
+ * (not valid JSON), and the page arrays are flattened back into one list.
+ */
+async function ghApiList(
+  path: string,
+  ctx: { cwd?: string; signal?: AbortSignal; input?: unknown },
+): Promise<unknown[]> {
+  const out = await ghExec(["api", "--paginate", "--slurp", path], ctx);
+  return Value.Parse(Type.Array(Type.Array(Type.Unknown())), JSON.parse(out)).flat();
+}
+
 /** Split `OWNER/REPO`; throws when the name doesn't have exactly one slash. */
 function splitRepo(nameWithOwner: string): { owner: string; repo: string } {
   const slash = nameWithOwner.indexOf("/");
@@ -253,30 +289,19 @@ function splitRepo(nameWithOwner: string): { owner: string; repo: string } {
   return { owner: nameWithOwner.slice(0, slash), repo: nameWithOwner.slice(slash + 1) };
 }
 
+/** Parse a positive integer toolcall parameter (run/job ids are numbers or numeric strings). */
+function toPositiveId(value: number | string, name: string): number {
+  const id = typeof value === "number" ? value : Number(value);
+  if (!Number.isSafeInteger(id) || id <= 0) {
+    throw new Error(`invalid ${name}: ${String(value)} (expected a positive integer)`);
+  }
+  return id;
+}
+
 // ── runtime validation schemas for JSON.parse results ───────────────────────
 
 const repoViewSchema = Type.Object({ nameWithOwner: Type.String() });
 
-const stepSchema = Type.Object({
-  name: Type.String(),
-  number: Type.Number(),
-  status: Type.String(),
-  conclusion: Type.Union([Type.String(), Type.Null()]),
-});
-
-const jobRunSchema = Type.Object({
-  id: Type.Number(),
-  run_id: Type.Number(),
-  run_url: Type.String(),
-  name: Type.String(),
-  status: Type.String(),
-  conclusion: Type.Union([Type.String(), Type.Null()]),
-  html_url: Type.Optional(Type.String()),
-  steps: Type.Array(stepSchema),
-});
-
-const jobsResponseSchema = Type.Object({ jobs: Type.Array(jobRunSchema) });
-
 const prHeadSchema = Type.Object({ headRefOid: Type.String() });
 
 function truncate(
@@ -396,13 +421,6 @@ async function searchList(
 
 // ── CI helpers ───────────────────────────────────────────────────────────────
 
-export interface StepInfo {
-  name: string;
-  number: number;
-  status: string;
-  conclusion: string | null;
-}
-
 // 模块级串行状态：同一资源（如 CI 日志）的请求排队执行，配合函数内部的
 // 缓存检查避免重复网络请求。闭包状态不与其他扩展共享，key 无需全局前缀。
 const seq = createSeqState();
@@ -431,7 +449,7 @@ export function jobLogPath(repo: string, runId: string, jobId: number): string {
 }
 
 async function getJobLog(
-  job: CiLogsJob,
+  job: RunJob,
   signal: AbortSignal | undefined,
   cwd: string | undefined,
   input?: unknown,
@@ -529,115 +547,197 @@ export interface StepSpan {
   end: number;
 }
 
+/** The part of a step the log index needs. `RunJobStep` satisfies it. */
+export interface StepRef {
+  number: number;
+  name: string;
+  conclusion?: string | null;
+  started_at?: string | null;
+}
+
+/** A `##[group]Run …` / `##[group]Post Run …` line: the header of one executed step. */
+interface StepHeader {
+  /** 0-based index of the `##[group]` line. */
+  line: number;
+  /** Header text with the `Run ` / `Post Run ` prefix stripped. */
+  action: string;
+  /** Runner timestamp on that line (epoch ms), null when unparsable. */
+  timestamp: number | null;
+}
+
+/** Runner timestamp every log line starts with: `2026-08-05T16:36:08.1842645Z `. */
+const LOG_TIMESTAMP_RE = /^\uFEFF?(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z) /;
+const HEADER_PREFIX_RE = /^(Run |Post Run )/;
+
 /**
- * Locate a job's steps in its raw log by matching step names to "Run " groups.
- *
- * Each top-level step emits a `##[group]Run <name>` / `##[group]Post Run <name>`
- * marker at depth 1. Composite actions emit their internal steps as *additional*
- * depth-1 groups *after* the composite's own `##[endgroup]` (e.g. the internal
- * `Run actions/setup-python@…` groups inside `Run pypa/cibuildwheel@…`), so the
- * log's "Run " groups are NOT one-per-step.
- *
- * To handle that we treat a group as an *anchor* only when its action name
- * (after stripping the "Run "/"Post Run " prefix) matches a top-level API step
- * name. Composite-action internals match no API step and are absorbed into the
- * span of the enclosing step instead of truncating it.
- *
- * Step 1 ("Set up job") maps to everything before the first anchor group.
- * Steps with an anchor map to the span from their anchor to the next anchor.
- * Explicitly named steps that lack a "Run " prefix (e.g. a step named
- * "Setup node" running actions/setup-node) are located between the previous
- * and next anchor's groups.
- * Steps that were skipped and never executed get no span.
+ * The runner writes a step's header within ~1.6s of the step's API `started_at`
+ * (the API truncates its timestamps to whole seconds), so a header inside this
+ * window is evidence of the step it belongs to.
  */
-export function stepLineSpans(
-  log: string,
-  apiSteps: { number: number; name: string }[],
-): Map<number, StepSpan> {
-  const lines = log.split("\n");
-  const spans = new Map<number, StepSpan>();
+const HEADER_WINDOW_MS = 5_000;
+/** An exact name match proves the header belongs to that step. */
+const NAME_MATCH_SCORE = 4;
+/** Weight of a header inside the step's start window. */
+const TIME_MATCH_SCORE = 2;
+
+function headerTimestamp(line: string): number | null {
+  const match = LOG_TIMESTAMP_RE.exec(line);
+  if (match === null) return null;
+  const ms = Date.parse(match[1]);
+  return Number.isNaN(ms) ? null : ms;
+}
 
-  // Collect depth-1 "Run "/"Post Run " groups in log order.
-  const groups: { line: number; action: string }[] = [];
+/** Collect the depth-1 `Run ` / `Post Run ` headers, in log order. */
+function stepHeaders(lines: string[]): StepHeader[] {
+  const headers: StepHeader[] = [];
   let depth = 0;
   for (const [i, line] of lines.entries()) {
     if (line.includes("##[endgroup]")) {
       if (depth > 0) depth--;
       continue;
     }
-    if (line.includes("##[group]")) {
-      depth++;
-      if (depth === 1) {
-        const m = /##\[group\](.*)/.exec(line);
-        const name = m ? m[1].trim() : "";
-        if (name.startsWith("Run ") || name.startsWith("Post Run ")) {
-          groups.push({ line: i, action: name.replace(/^(Run |Post Run )/, "").trim() });
-        }
-      }
+    if (!line.includes("##[group]")) continue;
+    depth++;
+    if (depth !== 1) continue;
+    const name = /##\[group\](.*)/.exec(line)?.[1].trim() ?? "";
+    if (HEADER_PREFIX_RE.test(name)) {
+      headers.push({
+        line: i,
+        action: name.replace(HEADER_PREFIX_RE, "").trim(),
+        timestamp: headerTimestamp(line),
+      });
     }
   }
+  return headers;
+}
 
-  // API steps that produce a "Run "/"Post Run " log group, in step order.
-  const runSteps = apiSteps
-    .filter((s) => /^(Run |Post Run )/.test(s.name))
-    .map((s) => ({ number: s.number, action: s.name.replace(/^(Run |Post Run )/, "").trim() }))
-    .toSorted((a, b) => a.number - b.number);
-
-  // Greedily assign each run step the first unclaimed group whose action name
-  // matches (log order). Leftover groups are composite-action internals.
-  const used = new Set<number>();
-  const stepToGroup = new Map<number, number>(); // api step number -> group index
-  for (const rs of runSteps) {
-    const gi = groups.findIndex((g, idx) => !used.has(idx) && g.action === rs.action);
-    if (gi !== -1) {
-      used.add(gi);
-      stepToGroup.set(rs.number, gi);
+/** How well a step explains a header — 0 means "no evidence, don't guess". */
+function headerScore(step: StepRef, header: StepHeader): number {
+  let score = 0;
+  const named = step.name.replace(HEADER_PREFIX_RE, "").trim();
+  if (HEADER_PREFIX_RE.test(step.name) && named === header.action) {
+    score += NAME_MATCH_SCORE;
+  }
+  const started = step.started_at == null ? NaN : Date.parse(step.started_at);
+  if (!Number.isNaN(started) && header.timestamp !== null) {
+    const delta = header.timestamp - started;
+    if (delta >= 0 && delta <= HEADER_WINDOW_MS) {
+      score += TIME_MATCH_SCORE * (1 - delta / HEADER_WINDOW_MS);
     }
   }
+  return score;
+}
 
-  // Anchor sequence in log order.
-  const anchors = [...stepToGroup]
-    .map(([stepNum, gi]) => ({ stepNum, line: groups[gi].line }))
-    .toSorted((a, b) => a.line - b.line);
-
-  for (const s of apiSteps) {
-    let start: number;
-    let end: number;
-
-    if (s.number === 1) {
-      // Step 1 ("Set up job"): everything before the first "Run " group.
-      start = 0;
-      end = groups[0]?.line ?? lines.length;
-    } else {
-      const anchorIdx = anchors.findIndex((a) => a.stepNum === s.number);
-      if (anchorIdx === -1) {
-        // Non-anchor step (explicitly named, e.g. "Setup node"): its group sits
-        // in the gap between the previous and next anchors' groups. Take the
-        // first unclaimed group in that span.
-        const prevAnchor = anchors.reduce<{ stepNum: number; line: number } | undefined>(
-          (acc, a) => (a.stepNum < s.number ? a : acc),
-          undefined,
-        );
-        const nextAnchor = anchors.find((a) => a.stepNum > s.number);
-        const gapStart = prevAnchor ? prevAnchor.line + 1 : 0;
-        const gapEnd = nextAnchor ? nextAnchor.line : lines.length;
+/**
+ * Align steps with headers: an order-preserving best-scoring matching, where
+ * either side may be left unmatched. Only pairs with real evidence are matched,
+ * so a step whose block cannot be identified gets no span instead of a guess.
+ *
+ * Name evidence disappears as soon as the workflow names a step with `name:`
+ * (the API name is then the custom one, while the log header carries the action
+ * or command), which is why the timestamps matter too. Headers belonging to a
+ * composite action's *internal* steps carry no evidence for any API step, so
+ * they stay unmatched and are absorbed into the enclosing step's span.
+ */
+function alignStepsToHeaders(
+  steps: readonly StepRef[],
+  headers: StepHeader[],
+): Map<number, number> {
+  const n = steps.length;
+  const m = headers.length;
+  // Equal-scoring alignments are decided in favour of the earlier step: a step
+  // whose output the runner never logged (post steps, "Complete job") comes last
+  // in step order, so a header claimed by both belongs to the earlier one. A
+  // step that ran always emits its header before the next step starts, which
+  // leaves several steps competing for one header whenever the API timestamps
+  // (whole seconds) collapse them into the same second.
+  const TIE_BREAK = 1e-6;
+  const scores = steps.map((step, i) =>
+    headers.map((header) => {
+      const score = headerScore(step, header);
+      return score > 0 ? score + TIE_BREAK * (n - i) : 0;
+    }),
+  );
+  // best[i][j]: score of aligning the first i steps with the first j headers.
+  const best: number[][] = Array.from({ length: n + 1 }, () =>
+    Array.from({ length: m + 1 }, () => 0),
+  );
+  const paired: boolean[][] = Array.from({ length: n + 1 }, () =>
+    Array.from({ length: m + 1 }, () => false),
+  );
 
-        const gi = groups.findIndex(
-          (g, idx) => !used.has(idx) && g.line >= gapStart && g.line < gapEnd,
-        );
-        if (gi === -1) continue; // step never ran → no block in the log
-        start = groups[gi].line;
-        end = gapEnd;
+  for (let i = 1; i <= n; i++) {
+    for (let j = 1; j <= m; j++) {
+      const pairing = scores[i - 1][j - 1];
+      const withPairing = pairing > 0 ? best[i - 1][j - 1] + pairing : -Infinity;
+      if (withPairing >= best[i - 1][j] && withPairing >= best[i][j - 1]) {
+        best[i][j] = withPairing;
+        paired[i][j] = true;
       } else {
-        // Direct anchor hit: span from this anchor to the next one.
-        start = anchors[anchorIdx].line;
-        end = anchorIdx + 1 < anchors.length ? anchors[anchorIdx + 1].line : lines.length;
+        best[i][j] = Math.max(best[i - 1][j], best[i][j - 1]);
       }
     }
+  }
+
+  const assignment = new Map<number, number>(); // step number -> header index
+  for (let i = n, j = m; i > 0 && j > 0;) {
+    if (paired[i][j]) {
+      assignment.set(steps[i - 1].number, j - 1);
+      i--;
+      j--;
+    } else if (best[i - 1][j] >= best[i][j - 1]) {
+      i--;
+    } else {
+      j--;
+    }
+  }
+  return assignment;
+}
+
+/** Exclusive end index with trailing blank lines dropped, so a span slices to real text. */
+function trimTrailingBlankLines(lines: string[], start: number, end: number): number {
+  while (end > start && (lines[end - 1] ?? "").trim() === "") end--;
+  return end;
+}
+
+/**
+ * Locate a job's steps in its raw log: each executed step emits a depth-1
+ * `##[group]Run <x>` / `##[group]Post Run <x>` header, and its block runs from
+ * that header up to the next executed step's header. Everything in between —
+ * the action's own `::group::` output, a composite action's internal step
+ * headers — belongs to the enclosing step.
+ *
+ * "Set up job" emits no header: it owns the runner preamble before the first
+ * header. Steps with no header of their own (skipped steps, post steps the
+ * runner never logged, "Complete job") get no span.
+ */
+export function stepLineSpans(log: string, apiSteps: readonly StepRef[]): Map<number, StepSpan> {
+  const lines = log.split("\n");
+  const headers = stepHeaders(lines);
+  const spans = new Map<number, StepSpan>();
+
+  // "Set up job" is the runner's own preamble and never takes part in matching:
+  // its start window overlaps the first real step's header.
+  const preamble = apiSteps.find((s) => s.number === 1 && s.name === "Set up job");
+  if (preamble !== undefined) {
+    const end = trimTrailingBlankLines(lines, 0, headers[0]?.line ?? lines.length);
+    spans.set(preamble.number, { start: 0, end });
+  }
+
+  // A skipped step never started, so it emitted no header — and its name often
+  // repeats another step's ("Clear build" twice, "Post Run <action>" next to
+  // its "Run <action>"), which would let it steal that step's block.
+  const assignment = alignStepsToHeaders(
+    apiSteps.filter((s) => s !== preamble && s.conclusion !== "skipped"),
+    headers,
+  );
+  const placed = [...assignment]
+    .map(([number, headerIndex]) => ({ number, line: headers[headerIndex].line }))
+    .toSorted((a, b) => a.line - b.line);
 
-    // Drop trailing blank lines so the span slices to the step's own text.
-    while (end > start && lines[end - 1].trim() === "") end--;
-    spans.set(s.number, { start, end });
+  for (const [index, step] of placed.entries()) {
+    const end = trimTrailingBlankLines(lines, step.line, placed[index + 1]?.line ?? lines.length);
+    spans.set(step.number, { start: step.line, end });
   }
 
   return spans;
@@ -647,7 +747,7 @@ export function stepLineSpans(
 export function extractStepFromLog(
   log: string,
   stepNumber: number,
-  apiSteps: { number: number; name: string }[],
+  apiSteps: readonly { number: number; name: string }[],
 ): string | null {
   const span = stepLineSpans(log, apiSteps).get(stepNumber);
   if (span === undefined) return null;
@@ -656,17 +756,6 @@ export function extractStepFromLog(
 
 // ── ci-logs rendering (pure, testable) ──────────────────────────────────────
 
-export interface CiLogsJob {
-  id: number;
-  run_id: number;
-  /** Canonical `api.github.com/repos/<owner>/<repo>/actions/runs/<id>`. */
-  run_url: string;
-  name: string;
-  status: string;
-  conclusion: string | null;
-  steps: StepInfo[];
-}
-
 export interface CiLogsResult {
   content: { type: "text"; text: string }[];
   details: Record<string, unknown>;
@@ -699,7 +788,7 @@ export interface CiLogsJobIndex {
  * range. The step content itself is not returned — the model reads it out of
  * the file.
  */
-export function jobLogIndex(job: CiLogsJob, rawLog: string): CiLogsJobIndex {
+export function jobLogIndex(job: RunJob, rawLog: string): CiLogsJobIndex {
   const spans = stepLineSpans(rawLog, job.steps);
   return {
     name: job.name,
@@ -739,6 +828,10 @@ export interface MergedCheck {
   readonly link: string | null;
   /** Triggering workflow event (push, pull_request, ...); null when unknown. */
   readonly event: string | null;
+  /** Actions run id behind this check, for `get-github-workflow-jobs`; null when unknown. */
+  readonly runId: number | null;
+  /** Actions job id behind this check, for `read-github-ci-logs`; null when unknown. */
+  readonly jobId: number | null;
 }
 
 function statusBucket(state: string): CheckBucket {
@@ -791,6 +884,8 @@ export function mergeChecks(
       startedAt: null,
       link: status.targetUrl,
       event: null,
+      runId: null,
+      jobId: null,
     })),
     ...checkRuns.map((run) => ({
       name: run.name,
@@ -798,6 +893,8 @@ export function mergeChecks(
       startedAt: run.startedAt,
       link: run.url,
       event: run.event,
+      runId: run.runId,
+      jobId: run.jobId,
     })),
   ];
 }
@@ -1064,8 +1161,20 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     return;
   }
 
-  const githubSearch = createGithubSearch();
-  const githubChecks = createGithubChecks();
+  pi.on("session_start", async (_event, ctx) => {
+    // 代理配置读不出来（JSON 语法错、字段类型错、proxy 不是 http(s) URL）时只告警，
+    // 工具按直连继续工作——配置写错不该让整套 GitHub 工具不可用。
+    const { error } = await ghProxy.load();
+    if (!error) return;
+    try {
+      ctx.ui.notify(`gh proxy config ignored: ${error}`, "warning");
+    } catch {
+      // 读取期间 session 可能已被替换，失效的 ctx 直接忽略
+    }
+  });
+
+  const githubSearch = createGithubSearch({ fetch: ghProxy.fetch });
+  const githubChecks = createGithubChecks({ fetch: ghProxy.fetch });
 
   /**
    * Shared wait core of `wait-github-pr-checks` and
@@ -1303,28 +1412,41 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     name: "read-github-pr-status",
     label: "GitHub PR Status",
     description:
-      "Get the current status checks and CI results for a GitHub pull request. Returns the current snapshot immediately; pending checks are reported as-is, not waited on. Use wait-github-pr-checks to block until checks finish.",
+      "Get the current checks of a pull request's head commit as JSON {pr, repo, head_sha, checks:[{name, bucket, event, run_id, job_id, url}]}. `bucket` is pass / fail / pending / skipped; Actions checks carry the `run_id` and `job_id` behind them (null for other CI), which is what read-github-ci-logs and get-github-workflow-jobs take. Returns the snapshot immediately without waiting — use wait-github-pr-checks to block until the checks finish.",
     promptSnippet: "Read GitHub PR status checks",
     parameters: Type.Object({
       number: Type.Union([Type.Number(), Type.String()], { description: "PR number" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO (defaults to current repo)" })),
     }),
     async execute(_id, params, signal, _onUpdate, ctx) {
       const { number, repo } = params;
-      const args = ["pr", "checks", String(number), ...repoArgs(repo)];
+      const pullNumber = toPositiveId(number, "number");
+      const pendant = subtitlePendant(params, "number");
+      const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+      const { owner, repo: name } = splitRepo(effectiveRepo);
 
-      // `gh pr checks` exit codes: 0 = all passed, 1 = some failed, 8 = some
-      // pending. All three are valid states — return the current snapshot
-      // as-is without waiting. `wait-github-pr-checks` is the blocking variant.
-      const result = await runGh(args, { cwd: ctx.cwd, signal });
+      // 与 wait 工具同一条读取路径（octokit），只是这里不轮询：pending 的 check
+      // 原样返回，等结果走 wait-github-pr-checks。
+      const pollSignal = signal ?? new AbortController().signal;
+      const headSha = await githubChecks.pullHead(owner, name, pullNumber, pollSignal);
+      const [statuses, checkRuns] = await Promise.all([
+        githubChecks.statuses(owner, name, headSha, pollSignal),
+        githubChecks.checkRuns(owner, name, headSha, pollSignal),
+      ]);
+      const checks = mergeChecks(statuses, checkRuns).map((check) => ({
+        name: check.name,
+        bucket: check.bucket,
+        event: check.event,
+        run_id: check.runId,
+        job_id: check.jobId,
+        url: check.link,
+      }));
 
-      if (result.code !== 0 && result.code !== 1 && result.code !== 8) {
-        // Anything else is a real error (cancelled, auth, network, ...)
-        throw new GhError(args, result, params);
-      }
-      const toolResult = toToolResult(result.stdout, params);
-      toolResult.details.pendant = subtitlePendant(params, "number");
-      return toolResult;
+      const payload = { pr: pullNumber, repo: effectiveRepo, head_sha: headSha, checks };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
+        details: { ...payload, input: params, ...(pendant && { pendant }) },
+      };
     },
   });
 
@@ -1351,22 +1473,19 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       if (reviews) {
         const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
 
-        const [comments, reviewsOut] = await Promise.all([
-          ghExec(["api", `/repos/${effectiveRepo}/pulls/${String(number)}/comments`], {
+        const [reviewComments, reviewSummaries] = await Promise.all([
+          ghApiList(`/repos/${effectiveRepo}/pulls/${String(number)}/comments`, {
             cwd: ctx.cwd,
             signal,
             input: params,
           }),
-          ghExec(["api", `/repos/${effectiveRepo}/pulls/${String(number)}/reviews`], {
+          ghApiList(`/repos/${effectiveRepo}/pulls/${String(number)}/reviews`, {
             cwd: ctx.cwd,
             signal,
             input: params,
           }),
         ]);
 
-        const reviewComments = Value.Parse(Type.Array(Type.Unknown()), JSON.parse(comments));
-        const reviewSummaries = Value.Parse(Type.Array(Type.Unknown()), JSON.parse(reviewsOut));
-
         out = JSON.stringify(
           {
             reviews: reviewSummaries,
@@ -1453,39 +1572,39 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     name: "read-github-ci-logs",
     label: "GitHub CI Logs",
     description:
-      "Download one GitHub Actions job's CI log and index its steps. Returns JSON {name, id, status, conclusion, log_file, steps:[{number, name, conclusion, start_line?, end_line?}]}: `log_file` is the job's complete raw log on disk (runner timestamps and ANSI kept, exactly as GitHub delivers it) and each step carries the 1-based inclusive line range of its block inside that file. Read the content out of the file yourself (read/grep with offset/limit) — it is not echoed back. Get `job` names/ids from read-github-workflow-jobs." +
+      "Download one GitHub Actions job's CI log by job ID and index its steps. Returns JSON {name, id, status, conclusion, log_file, steps:[{number, name, conclusion, start_line?, end_line?}]}: `log_file` is the job's complete raw log on disk (runner timestamps and ANSI kept, exactly as GitHub delivers it) and each step carries the 1-based inclusive line range of its block inside that file. Read the content out of the file yourself (read/grep with offset/limit) — it is not echoed back. Get the job IDs from get-github-workflow-jobs, then call this once per job you need." +
       " Note: queued jobs have no logs yet; use watch-github-run to wait for completion.",
     promptSnippet: "Read GitHub CI logs",
     parameters: Type.Object({
-      run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),
+      job_id: Type.Union([Type.Number(), Type.String()], {
+        description: "Job ID, from get-github-workflow-jobs.",
+      }),
       repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
-      job: Type.String({ description: "Job name or job ID, from read-github-workflow-jobs." }),
     }),
     async execute(_id, params, signal, onUpdate, ctx) {
-      const { run_id, repo, job } = params;
-      const runId = String(run_id);
+      const { job_id, repo } = params;
+      const jobId = toPositiveId(job_id, "job_id");
 
-      const pendant = subtitlePendant(params, "run_id");
+      const pendant = subtitlePendant(params, "job_id");
       const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-      const jobsOut = await ghExec(["api", `/repos/${effectiveRepo}/actions/runs/${run_id}/jobs`], {
-        cwd: ctx.cwd,
-        signal,
-        input: params,
-      });
-      const { jobs } = Value.Parse(jobsResponseSchema, JSON.parse(jobsOut));
+      const { owner, repo: name } = splitRepo(effectiveRepo);
 
       const failure = (text: string): CiLogsResult => ({
         content: [{ type: "text", text }],
         details: { input: params, ...(pendant && { pendant }) },
       });
 
-      const isNumeric = /^\d+$/.test(job);
-      const target = jobs.find((j) => (isNumeric ? String(j.id) : j.name) === job);
-      if (target === undefined) {
+      let target: RunJob;
+      try {
+        target = await githubChecks.job(owner, name, jobId, signal);
+      } catch (error) {
+        const status = (error as { status?: number }).status;
+        if (status !== 404) throw error;
         return failure(
-          `Job "${job}" not found in run ${runId}. Available: ${jobs.map((j) => `${j.name} (id: ${j.id})`).join(", ")}`,
+          `Job ${jobId} not found in ${effectiveRepo} — job IDs come from \`get-github-workflow-jobs\`.`,
         );
       }
+
       if (target.status === "queued") {
         return failure(
           `Job "${target.name}" is still queued — no logs available yet. Use \`watch-github-run\` to wait for it to start, then retry.`,
@@ -1507,28 +1626,24 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     },
   });
 
-  // ── read-github-workflow-jobs ──────────────────────────────────────────────
+  // ── get-github-workflow-jobs ──────────────────────────────────────────────
   pi.registerTool({
-    name: "read-github-workflow-jobs",
+    name: "get-github-workflow-jobs",
     label: "GitHub Workflow Jobs",
     description:
-      "Get structured job data (name, status, conclusion, job ID) for a workflow run. Useful before reading CI logs to identify which job to inspect.",
-    promptSnippet: "Read GitHub workflow run jobs",
+      "Get every job of a workflow run as JSON {total_count, jobs:[{id, run_id, run_url, name, status, conclusion, html_url, steps:[{name, number, status, conclusion, started_at}]}]}. Paginated server-side, so runs with more than 30 jobs return all of them. Use the `id` with read-github-ci-logs after read-github-pr-status / wait-github-commit-checks did not already give you a job id.",
+    promptSnippet: "Get GitHub workflow run jobs",
     parameters: Type.Object({
       run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),
       repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
     }),
     async execute(_id, params, signal, _onUpdate, ctx) {
       const { run_id, repo } = params;
+      const runId = toPositiveId(run_id, "run_id");
       const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-      const result = toToolResult(
-        await ghExec(["api", `/repos/${effectiveRepo}/actions/runs/${run_id}/jobs`], {
-          cwd: ctx.cwd,
-          signal,
-          input: params,
-        }),
-        params,
-      );
+      const { owner, repo: name } = splitRepo(effectiveRepo);
+      const jobs = await githubChecks.runJobs(owner, name, runId, signal);
+      const result = toToolResult(JSON.stringify({ total_count: jobs.length, jobs }), params);
       result.details.pendant = subtitlePendant(params, "run_id");
       return result;
     },

package/src/lib/gh-proxy.ts

@@ -0,0 +1,192 @@
+/**
+ * gh-readonly 的代理配置与请求层。
+ *
+ * 配置来源（配置文件优先，未写的字段回退到环境变量）：
+ *   - ~/.pi/agent/gh.json: { "proxy": "http://127.0.0.1:7890", "noProxy": "localhost,.corp" }
+ *   - HTTPS_PROXY / HTTP_PROXY / ALL_PROXY（小写变体同样接受）、NO_PROXY
+ *
+ * 两条出口共用同一份配置：
+ *   - gh CLI 子进程：env() 给出要注入子进程的 HTTP(S)_PROXY / NO_PROXY 等变量
+ *   - octokit 请求：fetch 是挂了代理 dispatcher 的 fetch；未配置代理时就是全局 fetch
+ */
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { Type } from "typebox";
+import { EnvHttpProxyAgent } from "undici";
+
+import { parseWithSchema } from "./parse-with-schema.js";
+
+const ghConfigSchema = Type.Object({
+  proxy: Type.Optional(Type.String()),
+  noProxy: Type.Optional(Type.String()),
+});
+
+export interface GhProxySettings {
+  /** 代理 URL（http/https）；undefined 表示不使用代理。 */
+  proxy?: string;
+  /** 不走代理的 host 列表（逗号分隔），语义同 NO_PROXY。 */
+  noProxy?: string;
+}
+
+export function ghProxyConfigPath(): string {
+  return join(homedir(), ".pi", "agent", "gh.json");
+}
+
+/** 解析 gh.json 的内容；字段类型不符时抛出带字段路径的错误。 */
+export function parseGhProxyConfig(value: unknown): GhProxySettings {
+  const parsed = parseWithSchema(ghConfigSchema, value);
+  const proxy = parsed.proxy?.trim();
+  const noProxy = parsed.noProxy?.trim();
+  return { ...(proxy && { proxy }), ...(noProxy && { noProxy }) };
+}
+
+const PROXY_ENV_NAMES = [
+  "HTTPS_PROXY",
+  "https_proxy",
+  "HTTP_PROXY",
+  "http_proxy",
+  "ALL_PROXY",
+  "all_proxy",
+];
+
+const NO_PROXY_ENV_NAMES = ["NO_PROXY", "no_proxy"];
+
+function firstEnv(names: readonly string[], env: NodeJS.ProcessEnv): string | undefined {
+  for (const name of names) {
+    const value = env[name]?.trim();
+    if (value) return value;
+  }
+  return undefined;
+}
+
+/** 代理必须是 http(s) URL：undici 的 ProxyAgent 只支持 HTTP CONNECT 代理。 */
+function normalizeProxy(value: string | undefined): { proxy?: string; error?: string } {
+  if (!value) return {};
+  let protocol: string;
+  try {
+    protocol = new URL(value).protocol;
+  } catch {
+    return { error: `invalid proxy URL: ${value}` };
+  }
+  if (protocol !== "http:" && protocol !== "https:") {
+    return { error: `unsupported proxy protocol: ${value} (expected http:// or https://)` };
+  }
+  return { proxy: value };
+}
+
+export interface GhProxyLoad {
+  /** 生效的代理设置（配置文件与环境变量合并后的结果）。 */
+  settings: GhProxySettings;
+  /** 配置读取/解析失败的原因；未失败时为 undefined。 */
+  error?: string;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** 读配置文件；文件不存在视为未配置，其它失败只记录不抛出。 */
+async function readConfigFile(configPath: string): Promise<GhProxyLoad> {
+  let raw: string;
+  try {
+    raw = await readFile(configPath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { settings: {} };
+    return { settings: {}, error: `${configPath}: ${describeError(error)}` };
+  }
+  try {
+    return { settings: parseGhProxyConfig(JSON.parse(raw)) };
+  } catch (error) {
+    return { settings: {}, error: `${configPath}: ${describeError(error)}` };
+  }
+}
+
+async function resolveSettings(configPath: string, env: NodeJS.ProcessEnv): Promise<GhProxyLoad> {
+  const file = await readConfigFile(configPath);
+  const normalized = normalizeProxy(file.settings.proxy ?? firstEnv(PROXY_ENV_NAMES, env));
+  const noProxy = file.settings.noProxy ?? firstEnv(NO_PROXY_ENV_NAMES, env);
+  return {
+    settings: { ...(normalized.proxy && { proxy: normalized.proxy }), ...(noProxy && { noProxy }) },
+    error: file.error ?? normalized.error,
+  };
+}
+
+/** 要注入 gh 子进程的代理环境变量；未配置代理时为空对象（子进程继承父进程环境）。 */
+export function proxyEnvVars(settings: GhProxySettings): NodeJS.ProcessEnv {
+  const { proxy, noProxy } = settings;
+  if (!proxy) return {};
+  return {
+    // gh 是 Go 程序，https 目标只认 HTTPS_PROXY；统一填全部变量，避免用户只设了
+    // HTTP_PROXY 时 https 请求直连。小写变体给 curl 系的子进程用。
+    HTTP_PROXY: proxy,
+    HTTPS_PROXY: proxy,
+    ALL_PROXY: proxy,
+    http_proxy: proxy,
+    https_proxy: proxy,
+    all_proxy: proxy,
+    ...(noProxy && { NO_PROXY: noProxy, no_proxy: noProxy }),
+  };
+}
+
+/**
+ * 挂着代理 dispatcher 的 fetch，供 octokit 的 `request.fetch` 使用。
+ *
+ * octokit v5 丢弃了 node-fetch 时代的 `agent` 选项（@octokit/request 的选项里没有
+ * 这个字段，也没有任何地方把它转交给 fetch），只接受自定义 fetch —— octokit
+ * README 的 Proxy Servers 一节就是挂 undici 的代理 dispatcher。NO_PROXY 匹配由
+ * EnvHttpProxyAgent 负责；未配置代理时原样返回全局 fetch，默认路径行为不变。
+ */
+function createFetch(settings: GhProxySettings): typeof globalThis.fetch {
+  const { proxy, noProxy } = settings;
+  if (!proxy) return globalThis.fetch;
+  // undici 包与 Node 全局 fetch 各带一份 Dispatcher 类型声明（@types/node 走
+  // undici-types），结构一致但 compose 重载对不上，这里只做类型层面的转换。
+  const dispatcher = new EnvHttpProxyAgent({
+    httpProxy: proxy,
+    httpsProxy: proxy,
+    ...(noProxy && { noProxy }),
+  }) as unknown as NonNullable<RequestInit["dispatcher"]>;
+  return (input, init) => globalThis.fetch(input, { ...init, dispatcher });
+}
+
+export interface GhProxy {
+  /** 读取配置（首个调用触发读盘，之后返回同一个缓存结果，失败不抛出）。 */
+  load(): Promise<GhProxyLoad>;
+  /** 要注入 gh 子进程的代理环境变量；未配置代理时为空对象。 */
+  env(): Promise<NodeJS.ProcessEnv>;
+  /** 走代理的 fetch；未配置代理时就是全局 fetch。 */
+  readonly fetch: typeof globalThis.fetch;
+}
+
+/**
+ * 创建代理配置读取器。配置只在首次使用时读一次并缓存；`load` 与 `fetch` 共用这次
+ * 读取，因此运行期不会出现两者看到不同配置的情况。
+ */
+export function createGhProxy(
+  configPath: string = ghProxyConfigPath(),
+  env: NodeJS.ProcessEnv = process.env,
+): GhProxy {
+  let loading: Promise<GhProxyLoad> | undefined;
+  let proxied: typeof globalThis.fetch | undefined;
+
+  function load(): Promise<GhProxyLoad> {
+    loading ??= resolveSettings(configPath, env);
+    return loading;
+  }
+
+  return {
+    load,
+    env: async () => {
+      const { settings } = await load();
+      return proxyEnvVars(settings);
+    },
+    fetch: async (input, init) => {
+      const { settings } = await load();
+      proxied ??= createFetch(settings);
+      return proxied(input, init);
+    },
+  };
+}

package/src/lib/github.ts

@@ -248,17 +248,29 @@ export interface GithubApi {
   call<T>(fn: (octokit: Octokit) => Promise<T>): Promise<T>;
 }
 
+export interface GithubClientOptions {
+  /**
+   * Custom fetch for octokit's `request.fetch` hook — octokit v5 drops the old
+   * `agent` option, so a proxy has to arrive as a fetch implementation with a
+   * proxy dispatcher attached. Defaults to the global fetch.
+   */
+  fetch?: typeof globalThis.fetch;
+}
+
 /**
  * Create a shared octokit accessor. The client (and its auth token) is cached
  * in the returned closure, so repeated calls reuse the same client without
  * module-level state. A stale cached token can produce 401s; the cache is
  * dropped and the request retried once in that case.
  */
-export function createGithubApi(): GithubApi {
+export function createGithubApi(options: GithubClientOptions = {}): GithubApi {
   let client: Octokit | undefined;
 
   async function getClient(): Promise<Octokit> {
-    client ??= new Octokit({ auth: await ghAuthToken() });
+    client ??= new Octokit({
+      auth: await ghAuthToken(),
+      ...(options.fetch && { request: { fetch: options.fetch } }),
+    });
     return client;
   }
 
@@ -287,8 +299,8 @@ export interface GithubSearch {
 /**
  * Create a search client backed by a cached octokit instance.
  */
-export function createGithubSearch(): GithubSearch {
-  const api = createGithubApi();
+export function createGithubSearch(options: GithubClientOptions = {}): GithubSearch {
+  const api = createGithubApi(options);
 
   return {
     async search(kind, params) {
@@ -334,6 +346,10 @@ export interface CheckRun {
   readonly url: string | null;
   /** Triggering workflow event (push, pull_request, ...); null when unknown. */
   readonly event: string | null;
+  /** Actions workflow run id parsed from `details_url`; null for non-Actions checks. */
+  readonly runId: number | null;
+  /** Actions job id parsed from `details_url`; null when the check is run- not job-level. */
+  readonly jobId: number | null;
 }
 
 /** One Actions job flattened with its workflow run metadata. */
@@ -347,6 +363,32 @@ export interface ActionJob {
   readonly jobUrl?: string;
 }
 
+/** One step of a workflow run job, as the REST API reports it. */
+export interface RunJobStep {
+  readonly name: string;
+  readonly number: number;
+  readonly status: string;
+  readonly conclusion: string | null;
+  /** ISO-8601 UTC, second precision; null/absent for steps that never started. */
+  readonly started_at?: string | null;
+}
+
+/**
+ * One job of a workflow run. Field names mirror the REST API because the CI log
+ * index consumes them as they arrive: `run_url`/`run_id` locate the job's raw
+ * log file, `steps` give the step list to align against that log.
+ */
+export interface RunJob {
+  readonly id: number;
+  readonly run_id: number;
+  readonly run_url: string;
+  readonly name: string;
+  readonly status: string;
+  readonly conclusion: string | null;
+  readonly html_url: string | null;
+  readonly steps: readonly RunJobStep[];
+}
+
 export interface GithubChecksClient {
   statuses(
     owner: string,
@@ -367,6 +409,21 @@ export interface GithubChecksClient {
     headSha: string,
     signal: AbortSignal,
   ): Promise<readonly ActionJob[]>;
+  /**
+   * Every job of one workflow run, steps included. The endpoint pages at 30
+   * items by default, which used to hide the jobs past the first page from the
+   * CI-log tools; `paginate` follows the Link header so all pages arrive.
+   */
+  runJobs(
+    owner: string,
+    repo: string,
+    runId: number,
+    signal: AbortSignal | undefined,
+  ): Promise<readonly RunJob[]>;
+  /** One job by id, steps included (`run_url`/`run_id` identify its run). */
+  job(owner: string, repo: string, jobId: number, signal: AbortSignal | undefined): Promise<RunJob>;
+  /** Head commit SHA of a PR — the commit whose checks are reported. */
+  pullHead(owner: string, repo: string, pullNumber: number, signal: AbortSignal): Promise<string>;
   /** Resolve a SHA, branch name, or tag name to the commit's full SHA. */
   headSha(owner: string, repo: string, ref: string, signal: AbortSignal): Promise<string>;
 }
@@ -378,13 +435,46 @@ export interface GithubChecksClient {
  * GitHub Apps) — so external CI is visible to the caller.
  */
 const ACTIONS_RUN_URL_RE = /\/actions\/runs\/(\d+)/;
-export function createGithubChecks(): GithubChecksClient {
-  const api = createGithubApi();
+/** Job-level check runs point at `.../actions/runs/<run>/job/<job>`. */
+const ACTIONS_JOB_URL_RE = /\/actions\/runs\/\d+\/job\/(\d+)/;
+
+/** One REST job object (list and single-job endpoints share the schema). */
+type ApiJob = Awaited<ReturnType<Octokit["rest"]["actions"]["getJobForWorkflowRun"]>>["data"];
+
+function toRunJob(job: ApiJob): RunJob {
+  return {
+    id: job.id,
+    run_id: job.run_id,
+    run_url: job.run_url,
+    name: job.name,
+    status: job.status,
+    conclusion: job.conclusion,
+    html_url: job.html_url ?? null,
+    steps: (job.steps ?? []).map((step) => ({
+      name: step.name,
+      number: step.number,
+      status: step.status,
+      conclusion: step.conclusion,
+      started_at: step.started_at ?? null,
+    })),
+  };
+}
+
+export function createGithubChecks(options: GithubClientOptions = {}): GithubChecksClient {
+  const api = createGithubApi(options);
 
   return {
     async statuses(owner, repo, ref, signal) {
       const { data } = await api.call((octokit) =>
-        octokit.rest.repos.getCombinedStatusForRef({ owner, repo, ref, request: { signal } }),
+        octokit.rest.repos.getCombinedStatusForRef({
+          owner,
+          repo,
+          ref,
+          // The statuses array is paginated and defaults to 30 per page; a
+          // commit carrying more than 100 statuses is not a real scenario.
+          per_page: 100,
+          request: { signal },
+        }),
       );
       return data.statuses.map((status) => ({
         context: status.context,
@@ -414,8 +504,8 @@ export function createGithubChecks(): GithubChecksClient {
       );
       const events = new Map<string, string>();
       if (runIds.size > 0) {
-        const { data } = await api.call((octokit) =>
-          octokit.rest.actions.listWorkflowRunsForRepo({
+        const commitRuns = await api.call((octokit) =>
+          octokit.paginate(octokit.rest.actions.listWorkflowRunsForRepo, {
             owner,
             repo,
             head_sha: ref,
@@ -423,24 +513,34 @@ export function createGithubChecks(): GithubChecksClient {
             request: { signal },
           }),
         );
-        for (const run of data.workflow_runs) {
+        for (const run of commitRuns) {
           const id = String(run.id);
           if (runIds.has(id)) events.set(id, run.event);
         }
       }
-      return runs.map((run) => ({
-        name: run.name,
-        status: run.status,
-        conclusion: run.conclusion,
-        startedAt: run.started_at,
-        url: run.html_url ?? run.details_url ?? null,
-        event: events.get(ACTIONS_RUN_URL_RE.exec(run.details_url ?? "")?.[1] ?? "") ?? null,
-      }));
+      return runs.map((run) => {
+        const detailsUrl = run.details_url ?? "";
+        const runId = ACTIONS_RUN_URL_RE.exec(detailsUrl)?.[1];
+        const jobId = ACTIONS_JOB_URL_RE.exec(detailsUrl)?.[1];
+        return {
+          name: run.name,
+          status: run.status,
+          conclusion: run.conclusion,
+          startedAt: run.started_at,
+          url: run.html_url ?? run.details_url ?? null,
+          event: events.get(runId ?? "") ?? null,
+          runId: runId === undefined ? null : Number(runId),
+          jobId: jobId === undefined ? null : Number(jobId),
+        };
+      });
     },
 
     async actionJobs(owner, repo, headSha, signal) {
-      const { data } = await api.call((octokit) =>
-        octokit.rest.actions.listWorkflowRunsForRepo({
+      // Both levels are paginated: a commit can carry several workflow runs
+      // (push and pull_request), and a single run can have more jobs than one
+      // page — a missing page would silently drop failed jobs from the report.
+      const runs = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.actions.listWorkflowRunsForRepo, {
           owner,
           repo,
           head_sha: headSha,
@@ -449,9 +549,9 @@ export function createGithubChecks(): GithubChecksClient {
         }),
       );
       const jobs: ActionJob[] = [];
-      for (const run of data.workflow_runs) {
-        const { data: jobsData } = await api.call((octokit) =>
-          octokit.rest.actions.listJobsForWorkflowRun({
+      for (const run of runs) {
+        const runJobs = await api.call((octokit) =>
+          octokit.paginate(octokit.rest.actions.listJobsForWorkflowRun, {
             owner,
             repo,
             run_id: run.id,
@@ -459,7 +559,7 @@ export function createGithubChecks(): GithubChecksClient {
             request: { signal },
           }),
         );
-        for (const job of jobsData.jobs) {
+        for (const job of runJobs) {
           jobs.push({
             runId: run.id,
             runName: run.name ?? "",
@@ -474,6 +574,38 @@ export function createGithubChecks(): GithubChecksClient {
       return jobs;
     },
 
+    async runJobs(owner, repo, runId, signal) {
+      const jobs = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.actions.listJobsForWorkflowRun, {
+          owner,
+          repo,
+          run_id: runId,
+          per_page: 100,
+          request: { signal },
+        }),
+      );
+      return jobs.map((job) => toRunJob(job));
+    },
+
+    async job(owner, repo, jobId, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.actions.getJobForWorkflowRun({
+          owner,
+          repo,
+          job_id: jobId,
+          request: { signal },
+        }),
+      );
+      return toRunJob(data);
+    },
+
+    async pullHead(owner, repo, pullNumber, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.pulls.get({ owner, repo, pull_number: pullNumber, request: { signal } }),
+      );
+      return data.head.sha;
+    },
+
     async headSha(owner, repo, ref, signal) {
       const { data } = await api.call((octokit) =>
         octokit.rest.repos.getCommit({ owner, repo, ref, request: { signal } }),

package/src/skills/github-ci-logs/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: github-ci-logs
+description: Use when 排查某个仓库的 CI 失败、要拿到具体 job 的日志 —— 从 repo + PR number / commit sha / branch name / tag 一路定位到 job 日志：read-github-pr-status 或 wait-github-commit-checks 找出失败的 check 及其 run_id/job_id，get-github-workflow-jobs 列某个 run 的全部 job，read-github-ci-logs 按 job_id 把原始日志落盘并按 step 行号读取。全程走工具，不需要手工跑 gh CLI。
+---
+
+# 从 PR / commit 定位到 CI 日志
+
+## 核心原则
+
+- **id 是唯一可靠的坐标**：日志工具只收 `job_id`，不接受 job 名称。名称 → id 必须先经过 check 列表或 job 列表工具。
+- **不手工调 gh**：check / job / PR 数据都由工具封装好了 ，自己拼 `gh api` 只会重复劳动、还可能踩分页坑（jobs 端点默认一页 30 条）。
+- **一次调用一个 job**：多个失败 job 就多次调用，逐个取。
+- **日志内容不进上下文**：`read-github-ci-logs` 只返回索引（落盘路径 + 每个 step 的行号区间），内容自己用 Read 读区间、Grep 搜错误。
+
+## 入口选择
+
+| 手里有什么                    | 第一步                                                            | 拿到什么                                                                           |
+| ----------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| PR number                     | `read-github-pr-status { number, repo? }`                         | 该 PR head commit 的 checks 快照：`bucket` / `event` / `run_id` / `job_id` / `url` |
+| commit sha / branch / tag     | `wait-github-commit-checks { commit, repo?, event? }`             | 已失败时立即返回；报告失败 job 的行带 `#<jobId>`                                   |
+| 只有 repo（不知道是哪个 run） | `list-github-workflow-runs { repo?, workflow?, status?, limit? }` | run 列表（含 run id）                                                              |
+| 只有 run_id                   | `get-github-workflow-jobs { run_id, repo? }`                      | 该 run 的全部 job：`id` / `name` / `status` / `conclusion` / `html_url` / `steps`  |
+
+`repo` 都可省略，缺省用当前目录解析。
+
+## 主流程
+
+1. 用上表挑一个入口，拿到 checks 或 jobs 列表。
+2. 找失败项：`bucket == "fail"`（PR 快照）或报告里 `(failure)` / `(timed_out)` / `(cancelled)` 的行。
+3. 有 `job_id` 就直接进第 4 步。只有 `run_id`、或者想看看同一个 run 里还有哪些 job，就先 `get-github-workflow-jobs { run_id }`，按 `name` / `status` 挑出目标 job 的 `id`。
+4. `read-github-ci-logs { job_id, repo? }` → JSON 索引：
+
+   ```json
+   {
+     "name": "lint",
+     "id": 92374541920,
+     "status": "completed",
+     "conclusion": "failure",
+     "log_file": "/home/me/.cache/pi/github/ci-logs/a/b/42/92374541920.log",
+     "steps": [
+       {
+         "number": 6,
+         "name": "Run npx prettier --check ./",
+         "conclusion": "failure",
+         "start_line": 120,
+         "end_line": 148
+       }
+     ]
+   }
+   ```
+
+5. 读日志：优先读失败 step 的 `[start_line, end_line]`；要检索关键词（`##[error]`、`error:`、报错文件名）就在 `log_file` 上 Grep。`steps` 里没有行号的 step 是跳过或没产生日志的。
+6. 还有别的失败 job → 回到第 4 步（用各自 job id）。
+
+## 输出与边界
+
+- `read-github-pr-status`：**立即返回快照，不轮询**。字段：`checks[].{name,bucket,event,run_id,job_id,url}`，非 Actions 的 check（Azure DevOps 等）`run_id`/`job_id` 为 null —— 这类没有 GitHub 侧 job 日志可读。
+- `wait-github-commit-checks`：用于「没有 PR、只有 sha/branch/tag」的入口。它等的是 checks 全部结束，但**已经失败的 check 会让它第一轮就返回**；失败报告里的 Actions job 行带 `#jobId`。要更快返回可传 `fail_fast: true`；只想看某个事件的 check 用 `event`（如 `push`）。
+- `get-github-workflow-jobs`：SDK 分页，一个 run 有 72 个 job 也会全部返回（旧版只返回前 30 个，第 31 个之后既列不出也选不中）。
+- `read-github-ci-logs`：job 还在 `queued` 时不出日志，提示用 `watch-github-run` 等它开始；日志原样落盘到 `~/.cache/pi/github/ci-logs/<owner>/<repo>/<run_id>/<job_id>.log`（保留 runner 时间戳与 ANSI），同一 job 重复调用命中缓存，不重复下载。
+- 工具**不做**日志截断、清洗或回显；拿到的是文件路径 + 行号，正文自己读。
+
+## 与相邻工具的分工
+
+- `read-github-pr-status`（快照即返）vs `wait-github-pr-checks`（阻塞轮询到检查结束）：前者用来定位，后者用来等结果。
+- `watch-github-run`：已知 run_id、要等这个 run 跑完时用。
+- `list-github-workflow-runs`：run 列表走 `gh run list`，适合「某个 workflow 最近一次跑得怎么样」这类不需要 PR 上下文的场景。
+
+## 反例
+
+- 用 job 名称去调 `read-github-ci-logs` —— 它只认 id，名称先经 `get-github-workflow-jobs` 转成 id。
+- 为了拿日志去 Bash 跑 `gh api /repos/.../actions/runs/<id>/jobs` —— 直接用 `get-github-workflow-jobs`，分页与 id 提取已经处理好。
+- 把整份日志读进上下文 —— 先用索引里的行号区间，或对 `log_file` 做 Grep。