@trim21/personal-pi-extensions 0.1.548 → 0.1.551

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.548",
+  "version": "0.1.551",
   "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,31 +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()]),
-  started_at: Type.Optional(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(
@@ -397,15 +421,6 @@ async function searchList(
 
 // ── CI helpers ───────────────────────────────────────────────────────────────
 
-export interface StepInfo {
-  name: string;
-  number: number;
-  status: string;
-  conclusion: string | null;
-  /** ISO-8601 UTC, second precision. Null for steps that never started. */
-  started_at?: string | null;
-}
-
 // 模块级串行状态：同一资源（如 CI 日志）的请求排队执行，配合函数内部的
 // 缓存检查避免重复网络请求。闭包状态不与其他扩展共享，key 无需全局前缀。
 const seq = createSeqState();
@@ -434,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,
@@ -532,7 +547,7 @@ export interface StepSpan {
   end: number;
 }
 
-/** The part of a step the log index needs. `StepInfo` satisfies it. */
+/** The part of a step the log index needs. `RunJobStep` satisfies it. */
 export interface StepRef {
   number: number;
   name: string;
@@ -624,7 +639,10 @@ function headerScore(step: StepRef, header: StepHeader): number {
  * 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: StepRef[], headers: StepHeader[]): Map<number, number> {
+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
@@ -693,7 +711,7 @@ function trimTrailingBlankLines(lines: string[], start: number, end: number): nu
  * 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: StepRef[]): Map<number, StepSpan> {
+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>();
@@ -729,7 +747,7 @@ export function stepLineSpans(log: string, apiSteps: StepRef[]): Map<number, Ste
 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;
@@ -738,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>;
@@ -781,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,
@@ -821,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 {
@@ -873,6 +884,8 @@ export function mergeChecks(
       startedAt: null,
       link: status.targetUrl,
       event: null,
+      runId: null,
+      jobId: null,
     })),
     ...checkRuns.map((run) => ({
       name: run.name,
@@ -880,6 +893,8 @@ export function mergeChecks(
       startedAt: run.startedAt,
       link: run.url,
       event: run.event,
+      runId: run.runId,
+      jobId: run.jobId,
     })),
   ];
 }
@@ -1146,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
@@ -1385,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 }) },
+      };
     },
   });
 
@@ -1433,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,
@@ -1535,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.`,
@@ -1589,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,196 @@
+/**
+ * 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：NO_PROXY 匹配、CONNECT 隧道都交给 undici 的
+ * EnvHttpProxyAgent，octokit 侧只认自定义 fetch（v5 丢掉了 node-fetch 时代的
+ * `agent` 选项，@octokit/request 的选项里没有这个字段，也没有任何地方把它转交给
+ * fetch），所以代理只能从 fetch 挂进去。
+ */
+function createProxyDispatcher(
+  proxy: string,
+  noProxy: string | undefined,
+): NonNullable<RequestInit["dispatcher"]> {
+  // undici 包与 Node 全局 fetch 各带一份 Dispatcher 类型声明（@types/node 走
+  // undici-types），结构一致但 compose 重载对不上，这里只做类型层面的转换。
+  return new EnvHttpProxyAgent({
+    httpProxy: proxy,
+    httpsProxy: proxy,
+    ...(noProxy && { noProxy }),
+  }) as unknown as NonNullable<RequestInit["dispatcher"]>;
+}
+
+export interface GhProxy {
+  /** 读取配置（首个调用触发读盘，之后返回同一个缓存结果，失败不抛出）。 */
+  load(): Promise<GhProxyLoad>;
+  /** 要注入 gh 子进程的代理环境变量；未配置代理时为空对象。 */
+  env(): Promise<NodeJS.ProcessEnv>;
+  /** 走代理的 fetch；未配置代理时就是全局 fetch。 */
+  readonly fetch: typeof globalThis.fetch;
+}
+
+/**
+ * 创建代理配置读取器。配置只在首次使用时读一次并缓存；`load` 与 `fetch` 共用这次
+ * 读取，因此运行期不会出现两者看到不同配置的情况。
+ *
+ * 缓存的是 dispatcher（连接池复用），**不是** `globalThis.fetch` 本身：每次调用都
+ * 取当前的全局 fetch，否则首个请求之后替换 `globalThis.fetch`（插桩、测试替身）
+ * 就不再生效。
+ */
+export function createGhProxy(
+  configPath: string = ghProxyConfigPath(),
+  env: NodeJS.ProcessEnv = process.env,
+): GhProxy {
+  let loading: Promise<GhProxyLoad> | undefined;
+  let dispatcher: NonNullable<RequestInit["dispatcher"]> | 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();
+      const { proxy, noProxy } = settings;
+      if (!proxy) return globalThis.fetch(input, init);
+      dispatcher ??= createProxyDispatcher(proxy, noProxy);
+      return globalThis.fetch(input, { ...init, dispatcher });
+    },
+  };
+}

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。