@trim21/personal-pi-extensions 0.1.690 → 0.1.691

package/src/gh/tools/list-releases.ts

@@ -4,10 +4,9 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
+  resolveRepoTarget,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { renderReleaseList } from "../render.js";
@@ -27,10 +26,9 @@ export function addListReleasesTool(gh: GhClient, bus: ToolBus) {
       }),
       structuredSchema: ghReleaseListPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
-        const { repo, limit } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const items = await gh.reads.listReleases(owner, repoName, limit, signal);
+        const { limit } = params;
+        const { owner, name } = await resolveRepoTarget(params.repo, signal, ctx.cwd, params);
+        const items = await gh.reads.listReleases(owner, name, limit, signal);
         const releases = parseWithSchema(Type.Array(ghReleaseSummarySchema), items);
         // REST 没有 isLatest：按列表顺序取第一个非 draft / prerelease 的条目
         const latestIndex = releases.findIndex(
@@ -40,8 +38,7 @@ export function addListReleasesTool(gh: GhClient, bus: ToolBus) {
           releases.map((release, index) => ({ ...release, latest: index === latestIndex })),
         );
         const result = toToolResult(text, params);
-        result.details.pendant = subtitlePendant(params);
-        return withStructuredResult(result, { text, releases });
+        return withStructuredResult(withPendant(result, params), { text, releases });
       },
     }),
   );

package/src/gh/tools/list-workflow-runs.ts

@@ -4,10 +4,9 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
+  resolveRepoTarget,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { renderRunList } from "../render.js";
@@ -31,15 +30,13 @@ export function addListWorkflowRunsTool(gh: GhClient, bus: ToolBus) {
       }),
       structuredSchema: ghRunListPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
-        const { repo, limit, status, workflow } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const items = await gh.reads.listRuns(owner, repoName, { workflow, status, limit }, signal);
+        const { limit, status, workflow } = params;
+        const { owner, name } = await resolveRepoTarget(params.repo, signal, ctx.cwd, params);
+        const items = await gh.reads.listRuns(owner, name, { workflow, status, limit }, signal);
         const runs = parseWithSchema(Type.Array(ghRunSummarySchema), items);
         const text = renderRunList(runs);
         const result = toToolResult(text, params);
-        result.details.pendant = subtitlePendant(params);
-        return withStructuredResult(result, { text, runs });
+        return withStructuredResult(withPendant(result, params), { text, runs });
       },
     }),
   );

package/src/gh/tools/read-ci-logs.ts

@@ -9,12 +9,12 @@ import { dirname, join } from "node:path";
 
 import { Type } from "typebox";
 
-import type { RunJob } from "../../lib/github.js";
+import { isNotFound, type RunJob } from "../../lib/github.js";
 import { createSeqState } from "../../lib/seq-state.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
+  resolveRepoTarget,
   splitRepo,
   structuredFailure,
   type StructuredFailureResult,
@@ -299,19 +299,6 @@ export function stepLineSpans(log: string, apiSteps: readonly StepRef[]): Map<nu
   return spans;
 }
 
-/** Text of `stepNumber` in its raw log, or null when the step never ran. */
-export function extractStepFromLog(
-  log: string,
-  stepNumber: number,
-  apiSteps: readonly { number: number; name: string }[],
-): string | null {
-  const span = stepLineSpans(log, apiSteps).get(stepNumber);
-  if (span === undefined) {
-    return null;
-  }
-  return log.split("\n").slice(span.start, span.end).join("\n").trimEnd();
-}
-
 /** One step of a job, indexed into the job's raw log file. */
 export interface CiLogsStepIndex {
   number: number;
@@ -374,8 +361,11 @@ async function ciLogs(gh: GhClient, call: ToolCall<JobIdParams>): Promise<CiLogs
   const jobId = toPositiveId(job_id, "job_id");
 
   const pendant = subtitlePendant(params, "job_id");
-  const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-  const { owner, repo: name } = splitRepo(effectiveRepo);
+  const {
+    fullName: effectiveRepo,
+    owner,
+    name,
+  } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
 
   const failure = (text: string): StructuredFailureResult => ({
     content: [{ type: "text", text }],
@@ -387,8 +377,7 @@ async function ciLogs(gh: GhClient, call: ToolCall<JobIdParams>): Promise<CiLogs
   try {
     target = await gh.checks.job(owner, name, jobId, signal);
   } catch (error) {
-    const status = (error as { status?: number }).status;
-    if (status !== 404) {
+    if (!isNotFound(error)) {
       throw error;
     }
     return failure(

package/src/gh/tools/read-issue-comments.ts

@@ -1,13 +1,7 @@
 import { Type } from "typebox";
 
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
-import {
-  type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
-  toStructuredJsonResult,
-} from "../base.js";
+import { type GhClient, resolveRepoTarget, toStructuredJsonResult, withPendant } from "../base.js";
 import { issueCommentsSchema } from "../schemas.js";
 
 export function addReadIssueCommentsTool(gh: GhClient, bus: ToolBus) {
@@ -24,16 +18,14 @@ export function addReadIssueCommentsTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: issueCommentsSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const comments = await gh.reads.issueComments(owner, repoName, Number(number), signal);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
+        const comments = await gh.reads.issueComments(owner, name, Number(number), signal);
         const result = toStructuredJsonResult(
           JSON.stringify({ comments }, null, 2),
           params,
           issueCommentsSchema,
         );
-        result.details.pendant = subtitlePendant(params, "number");
-        return result;
+        return withPendant(result, params, "number");
       },
     }),
   );

package/src/gh/tools/read-issue.ts

@@ -1,13 +1,7 @@
 import { Type } from "typebox";
 
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
-import {
-  type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
-  toStructuredJsonResult,
-} from "../base.js";
+import { type GhClient, resolveRepoTarget, toStructuredJsonResult, withPendant } from "../base.js";
 import { issueViewSchema } from "../schemas.js";
 
 export function addReadIssueTool(gh: GhClient, bus: ToolBus) {
@@ -24,16 +18,14 @@ export function addReadIssueTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: issueViewSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const data = await gh.reads.issue(owner, repoName, Number(number), signal);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
+        const data = await gh.reads.issue(owner, name, Number(number), signal);
         const result = toStructuredJsonResult(
           JSON.stringify(data, null, 2),
           params,
           issueViewSchema,
         );
-        result.details.pendant = subtitlePendant(params, "number");
-        return result;
+        return withPendant(result, params, "number");
       },
     }),
   );

package/src/gh/tools/read-pr-comments.ts

@@ -1,13 +1,7 @@
 import { Type } from "typebox";
 
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
-import {
-  type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
-  toStructuredJsonResult,
-} from "../base.js";
+import { type GhClient, resolveRepoTarget, toStructuredJsonResult, withPendant } from "../base.js";
 import { prCommentsSchema } from "../schemas.js";
 
 export function addReadPrCommentsTool(gh: GhClient, bus: ToolBus) {
@@ -31,18 +25,17 @@ export function addReadPrCommentsTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: prCommentsSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo, reviews } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
         const pullNumber = Number(number);
 
         // reviews=true 给行内评审评论 + 评审摘要；缺省给 PR 上的普通（issue）评论
         const payload = reviews
           ? {
-              reviews: await gh.reads.pullReviews(owner, repoName, pullNumber, signal),
-              comments: await gh.reads.pullReviewComments(owner, repoName, pullNumber, signal),
+              reviews: await gh.reads.pullReviews(owner, name, pullNumber, signal),
+              comments: await gh.reads.pullReviewComments(owner, name, pullNumber, signal),
             }
           : {
-              comments: await gh.reads.issueComments(owner, repoName, pullNumber, signal),
+              comments: await gh.reads.issueComments(owner, name, pullNumber, signal),
             };
 
         const result = toStructuredJsonResult(
@@ -50,8 +43,7 @@ export function addReadPrCommentsTool(gh: GhClient, bus: ToolBus) {
           params,
           prCommentsSchema,
         );
-        result.details.pendant = subtitlePendant(params, "number");
-        return result;
+        return withPendant(result, params, "number");
       },
     }),
   );

package/src/gh/tools/read-pr-diff.ts

@@ -3,10 +3,9 @@ import { Type } from "typebox";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
+  resolveRepoTarget,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { parseDiffStats } from "../render.js";
@@ -26,13 +25,14 @@ export function addReadPrDiffTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: ghDiffPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const diff = await gh.reads.pullDiff(owner, repoName, Number(number), signal);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
+        const diff = await gh.reads.pullDiff(owner, name, Number(number), signal);
         const result = toToolResult(diff, params);
-        result.details.pendant = subtitlePendant(params, "number");
         // 文本是原始 diff（没有 JSON 形式），载荷从同一份 diff 解析出变更统计
-        return withStructuredResult(result, { text: diff, ...parseDiffStats(diff) });
+        return withStructuredResult(withPendant(result, params, "number"), {
+          text: diff,
+          ...parseDiffStats(diff),
+        });
       },
     }),
   );

package/src/gh/tools/read-pr-status.ts

@@ -4,8 +4,7 @@ import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   mergeChecks,
-  resolveRepo,
-  splitRepo,
+  resolveRepoTarget,
   type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
@@ -32,8 +31,11 @@ export async function prStatus(
   const { number, repo } = params;
   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);
+  const {
+    fullName: effectiveRepo,
+    owner,
+    name,
+  } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
 
   const pollSignal = signal ?? new AbortController().signal;
   const headSha = await gh.checks.pullHead(owner, name, pullNumber, pollSignal);

package/src/gh/tools/read-pr.ts

@@ -1,13 +1,7 @@
 import { Type } from "typebox";
 
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
-import {
-  type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
-  toStructuredJsonResult,
-} from "../base.js";
+import { type GhClient, resolveRepoTarget, toStructuredJsonResult, withPendant } from "../base.js";
 import { prViewSchema } from "../schemas.js";
 
 export function addReadPrTool(gh: GhClient, bus: ToolBus) {
@@ -24,12 +18,10 @@ export function addReadPrTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: prViewSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { number, repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const data = await gh.reads.pull(owner, repoName, Number(number), signal);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
+        const data = await gh.reads.pull(owner, name, Number(number), signal);
         const result = toStructuredJsonResult(JSON.stringify(data, null, 2), params, prViewSchema);
-        result.details.pendant = subtitlePendant(params, "number");
-        return result;
+        return withPendant(result, params, "number");
       },
     }),
   );

package/src/gh/tools/read-release.ts

@@ -4,10 +4,9 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
+  resolveRepoTarget,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { renderReleaseView } from "../render.js";
@@ -28,14 +27,12 @@ export function addReadReleaseTool(gh: GhClient, bus: ToolBus) {
       structuredSchema: ghReleaseViewPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
         const { tag, repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const data = await gh.reads.release(owner, repoName, tag, signal);
+        const { owner, name } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
+        const data = await gh.reads.release(owner, name, tag, signal);
         const view = parseWithSchema(ghReleaseViewSchema, data);
         const text = renderReleaseView(view);
         const result = toToolResult(text, params);
-        result.details.pendant = subtitlePendant(params, "tag");
-        return withStructuredResult(result, { text, release: view });
+        return withStructuredResult(withPendant(result, params, "tag"), { text, release: view });
       },
     }),
   );

package/src/gh/tools/read-repo.ts

@@ -4,10 +4,9 @@ import { parseWithSchema } from "../../lib/parse-with-schema.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
-  subtitlePendant,
+  resolveRepoTarget,
   toToolResult,
+  withPendant,
   withStructuredResult,
 } from "../base.js";
 import { renderRepoView } from "../render.js";
@@ -25,15 +24,12 @@ export function addReadRepoTool(gh: GhClient, bus: ToolBus) {
       }),
       structuredSchema: ghRepoPayloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
-        const { repo } = params;
-        const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
-        const data = await gh.reads.repository(owner, repoName, signal);
+        const { owner, name } = await resolveRepoTarget(params.repo, signal, ctx.cwd, params);
+        const data = await gh.reads.repository(owner, name, signal);
         const view = parseWithSchema(ghRepoViewSchema, data);
         const text = renderRepoView(view);
         const result = toToolResult(text, params);
-        result.details.pendant = subtitlePendant(params);
-        return withStructuredResult(result, { text, repo: view });
+        return withStructuredResult(withPendant(result, params), { text, repo: view });
       },
     }),
   );

package/src/gh/tools/wait-commit-checks.ts

@@ -3,8 +3,7 @@ import { Type } from "typebox";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
+  resolveRepoTarget,
   type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
@@ -33,8 +32,7 @@ async function waitCommitChecks(
     details: {},
   });
 
-  const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-  const { owner, repo: repoName } = splitRepo(effectiveRepo);
+  const { owner, name: repoName } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
 
   const pollSignal = signal ?? new AbortController().signal;
   const sha = await gh.checks.headSha(owner, repoName, String(commit), pollSignal);

package/src/gh/tools/wait-pr-checks.ts

@@ -4,8 +4,7 @@ import { Value } from "typebox/value";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  resolveRepo,
-  splitRepo,
+  resolveRepoTarget,
   type StructuredResultOf,
   subtitlePendant,
   type ToolCall,
@@ -36,8 +35,7 @@ async function waitPrChecks(
     details: {},
   });
 
-  const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
-  const { owner, repo: repoName } = splitRepo(effectiveRepo);
+  const { owner, name: repoName } = await resolveRepoTarget(repo, signal, ctx.cwd, params);
 
   const pull = Value.Parse(
     pullHeadSchema,

package/src/gh/tools/watch-run.ts

@@ -4,8 +4,7 @@ import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
   renderRunStatus,
-  resolveRepo,
-  splitRepo,
+  resolveRepoTarget,
   subtitlePendant,
   type ToolResult,
   watchRun,
@@ -38,8 +37,12 @@ export function addWatchRunTool(gh: GhClient, bus: ToolBus) {
 
         // 轮询循环要求非空 signal（与两个 wait 工具一致：没有就自建一个）
         const pollSignal = signal ?? new AbortController().signal;
-        const effectiveRepo = await resolveRepo(repo, pollSignal, ctx.cwd, params);
-        const { owner, repo: repoName } = splitRepo(effectiveRepo);
+        const { owner, name: repoName } = await resolveRepoTarget(
+          repo,
+          pollSignal,
+          ctx.cwd,
+          params,
+        );
         const outcome = await watchRun({
           owner,
           repo: repoName,

package/src/lib/abort.ts

@@ -0,0 +1,10 @@
+/**
+ * 把调用方的取消信号与一个本地超时合并成单个 AbortSignal。
+ *
+ * 调用方可能不传 signal（例如 agent 空闲时的 `ctx.signal`），那时仍然要有超时兜底，
+ * 所以本地 `AbortSignal.timeout` 始终生效，两者都触发时以先到者为准。
+ */
+export function withTimeoutSignal(signal: AbortSignal | undefined, ms: number): AbortSignal {
+  const timeout = AbortSignal.timeout(ms);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}

package/src/lib/bash-tool.ts

@@ -0,0 +1,48 @@
+/**
+ * claude-code 与 opencode 两套 Bash 工具共用的部分：超时上下限、结构化结果 schema、
+ * 以及截断后从落盘文件读回完整输出。
+ *
+ * 只放两边逐字相同的部分。两套工具的截断提示文案、失败判定与 details 是刻意的差异，
+ * 留在各自的工具里，不在这里统一。
+ */
+
+import { readFile } from "node:fs/promises";
+
+import type { TruncationResult } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export const BASH_DEFAULT_TIMEOUT_MS = 120_000;
+export const BASH_MAX_TIMEOUT_MS = 7_200_000;
+
+/**
+ * `Bash` 的结构化结果：只有退出码与完整输出——命令非零退出不是失败，所以载荷里没有成败
+ * 标志，脚本直接读 `exitCode` 分支；超时/中止时 `exitCode` 为 `null`（原因在模型侧文本里）。
+ */
+export const bashStructuredSchema = Type.Object({
+  exitCode: Type.Union([Type.Number(), Type.Null()], {
+    description: "Exit code of the command; null when it was killed (timeout or abort)",
+  }),
+  output: Type.String({
+    description:
+      "Complete output of the command (stdout and stderr merged). Never truncated, never mixed with tool-added notices.",
+  }),
+});
+
+/**
+ * 载荷里的输出：文本被截断时读回落盘的完整输出（读不到就退回那份截断文本），
+ * 因此脚本拿到的永远是命令真正输出的内容。
+ */
+export async function spilledOutput(
+  output: string,
+  truncation: TruncationResult,
+  spillPath: string | undefined,
+): Promise<string> {
+  if (spillPath === undefined || !truncation.truncated) {
+    return output;
+  }
+  try {
+    return await readFile(spillPath, "utf8");
+  } catch {
+    return output;
+  }
+}

package/src/lib/github-reads.ts

@@ -15,7 +15,7 @@ import { pipeline } from "node:stream/promises";
 
 import type { Octokit } from "octokit";
 
-import { createGithubApi, type GithubClientOptions } from "./github.js";
+import { type GithubApi } from "./github.js";
 
 /** `actions.listWorkflowRuns*` 的 `status` 取值（octokit 是字面量联合，工具参数是 string）。 */
 type WorkflowRunParams = NonNullable<
@@ -146,23 +146,6 @@ function limitOf(limit: number | undefined, fallback: number): number {
   return Math.min(Math.max(limit ?? fallback, 1), 100);
 }
 
-/** 响应体不是 2xx 时抛错（状态、URL 与 GitHub 的 message 都在里面）。 */
-async function ensureOk(response: Response): Promise<Response> {
-  if (response.ok) {
-    return response;
-  }
-  let detail: string | undefined;
-  try {
-    const body = await response.text();
-    detail = (JSON.parse(body) as { message?: string }).message ?? body.slice(0, 200);
-  } catch {
-    detail = undefined;
-  }
-  throw new Error(
-    `GitHub API error (HTTP ${response.status}) at ${response.url}${detail === undefined || detail === "" ? "" : `: ${detail}`}`,
-  );
-}
-
 function octokitRequest(signal: AbortSignal | undefined): { signal?: AbortSignal } {
   return signal === undefined ? {} : { signal };
 }
@@ -172,9 +155,7 @@ function asJson(value: unknown): unknown {
   return value;
 }
 
-export function createGithubReads(options: GithubClientOptions = {}): GithubReads {
-  const api = createGithubApi(options);
-
+export function createGithubReads(api: GithubApi): GithubReads {
   return {
     async issue(owner, repo, number, signal) {
       const { data } = await api.call((octokit) =>
@@ -373,11 +354,11 @@ export function createGithubReads(options: GithubClientOptions = {}): GithubRead
     },
 
     async downloadAssetTo(owner, repo, assetId, destPath, signal) {
+      // rawFetch 非 2xx 直接抛 GithubApiError；这里只需流式落盘
       const response = await api.rawFetch(
         `https://api.github.com/repos/${owner}/${repo}/releases/assets/${assetId}`,
         { headers: { accept: "application/octet-stream" }, ...(signal && { signal }) },
       );
-      await ensureOk(response);
       await streamToFile(response, destPath);
     },
 
@@ -388,7 +369,6 @@ export function createGithubReads(options: GithubClientOptions = {}): GithubRead
         `https://api.github.com/repos/${owner}/${repo}/${kind}${suffix}`,
         { ...(signal && { signal }) },
       );
-      await ensureOk(response);
       await streamToFile(response, destPath);
     },
   };