@trim21/personal-pi-extensions 0.1.684 → 0.1.687

package/README.md

@@ -16,7 +16,7 @@
 | [写保护（内置）](#写保护内置)             | 写工具内置：限制文件写入在 workspace 内，外部写入需审批                                       |
 | [LSP（内置）](#lsp内置)                   | 文件工具内置 LSP 诊断 + `lsp-rename`/`lsp-inspect`/`lsp-find-definition`/`lsp-find-reference` |
 | [aft](#aft)                               | AFT 只读代码感知：`aft_outline`/`aft_zoom`/`aft_callgraph`/`aft_search`                       |
-| [gh-readonly](#gh-readonly)               | GitHub 只读工具集（issue / PR / CI / release），基于 `gh` CLI                                 |
+| [gh-readonly](#gh-readonly)               | GitHub 只读工具集（issue / PR / CI / release），数据走 octokit REST                           |
 | [spawn-agent](#spawn-agent)               | 把任务委派给独立上下文窗口的子代理                                                            |
 | [system-prompt](#system-prompt)           | 完全替换 pi 默认 system prompt                                                                |
 | [vision-agent](#vision-agent)             | 视觉代理：主模型不支持视觉时提供 `describe_image`，调用视觉模型识别图片                       |
@@ -36,12 +36,14 @@
 - **嵌套调用经工具总线**：`call("Bash", { command })` 最终执行的是 `Bash` 工具自己的
   `execute`，所以工具的审批照常生效（Bash 沙箱外执行会弹自己的提权确认）。codemode
   不额外加确认层：脚本里连发十次调用就是十次工具自己的审批（需要审批的那些）。
-- **可调用集合** = 总线上实际注册的工具减去排除名单，执行时再与当前 active 列表求交，
-  所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` / `--tools`、子代理的工具
-  白名单都同样约束脚本。排除名单：`codemode` 自身与 `spawn-agent`；两套文件工具集的
-  读写工具（`Read`/`Edit`/`Write` 与 `read`/`edit`/`write`）；两套工具集的搜索工具
-  （`Grep`/`Glob` 与 `grep`/`glob`）——脚本搜文件用 `call("Bash", { command: "rg …" })`，
-  走同一个沙箱、拿得到退出码，还能拼管道，而那两个工具是给模型看结果的。
+- **可调用集合 = 声明了结构化输出的工具**（有 `structuredSchema` 的才进），执行时再与当前
+  active 列表求交，所以 `personalExtensions.disabledTools`、pi 的 `defaultTools` /
+  `--tools`、子代理的工具白名单都同样约束脚本。脚本拿到的返回值必须有确定的形状，因此没给
+  结构化结果的工具不进集合——这条规则自己维持一致，不需要维护一份会漂移的黑名单。由此天然
+  不在集合里的：`codemode` 自身与 `spawn-agent`、文件读写工具（脚本用 `fs.read` /
+  `fs.write`）、搜索工具（脚本用 `call("Bash", { command: "rg …" })`，走同一个沙箱、拿得到
+  退出码，还能拼管道）、`lsp-rename`（写工具）以及 talk / 会话工具（会把执行时间交给外部
+  输入）。
 - **文件读写只有 `fs` 一条路**：`fs.read(path)` 返回文件全文的原始 UTF-8 文本（不加行号、
   不截断、不设大小上限，只有内容不是合法 UTF-8 时报错），`fs.write(path, content)` 整体写入并自动创建
   父目录，相对路径相对当前 cwd。`fs.write` 与写类工具共用同一套保护：写前要求「已读且读后
@@ -459,7 +461,7 @@ pi -e ./src/aft/index.ts
 
 ## gh-readonly
 
-GitHub 只读工具集，基于系统 [`gh`](https://cli.github.com/) CLI（关键词搜索与 checks 查询走 octokit REST）。`gh` 不在 PATH 时整组不注册并在 session_start 报错；Windows 禁用。
+GitHub 只读工具集。取数走 octokit REST（`src/lib/github-reads.ts`）；只有「当前仓库」解析（`gh repo view`）与 token 获取（`gh auth token`）还用系统 [`gh`](https://cli.github.com/)，因此 `gh` 不在 PATH 时整组不注册并在 session_start 报错；Windows 禁用。
 
 - **Issue / PR**：`read-github-issue`、`list-github-issues`、`read-github-issue-comments`、`read-github-pr`、`list-github-prs`、`read-github-pr-diff`、`read-github-pr-status`、`read-github-pr-comments`
 - **CI**：`read-github-ci-logs`、`list-github-workflow-runs`、`get-github-workflow-jobs`、`wait-github-pr-checks`、`wait-github-commit-checks`、`watch-github-run`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.684",
+  "version": "0.1.687",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/codemode/declarations.ts

@@ -12,7 +12,8 @@ interface ToolLike {
   name: string;
   description?: string;
   parameters?: unknown;
-  structuredSchema?: unknown;
+  /** 只有声明了它的工具才可调用（见 `tool.ts` 的准入条件），因此这里是必需的。 */
+  structuredSchema: unknown;
 }
 
 type JsonSchema = Record<string, unknown>;
@@ -88,8 +89,7 @@ function renderType(schema: unknown, indent: string): string {
 function renderOverload(tool: ToolLike): string {
   const summary = tool.description?.split("\n", 1)[0]?.trim();
   const doc = summary ? `/** ${summary} */\n` : "";
-  const output =
-    tool.structuredSchema === undefined ? "string" : renderType(tool.structuredSchema, "");
+  const output = renderType(tool.structuredSchema, "");
   return `${doc}declare function call(name: ${JSON.stringify(tool.name)}, args: ${renderType(tool.parameters, "")}): Promise<${output}>;`;
 }
 

package/src/codemode/tool.ts

@@ -5,7 +5,7 @@
  * 自己的确认层），以及 `fs.read` / `fs.write` 两个文件原语（同样由主线程执行，与文件工具
  * 共用写审批与已读记账，见 fs.ts）。
  *
- * 可调用集合：总线上实际注册的工具减去 `EXCLUDED_TOOL_NAMES`，执行时再与 active
+ * 可调用集合：总线上实际注册的、**声明了 `structuredSchema`** 的工具，执行时再与 active
  * 列表求交——pi 自己的 `defaultTools` / `--tools` / 子代理白名单的排除因此同样生效。
  *
  * wasm 在注册这个工具时编译一次（`createCodemodeSandbox`），worker 复用编译结果。
@@ -32,30 +32,16 @@ import { CODEMODE_SOURCE_GRAMMAR, DEFAULT_OUTPUT_TOKENS, parseCodemodeSource } f
 export const CODEMODE_TOOL_NAME = "codemode";
 
 /**
- * 不暴露给脚本的工具：
- * - codemode 自身（防递归）；
- * - spawn-agent：它启动一个新的隔离会话，成本与运行时长都不适合放进脚本编排；
- * - 两套文件工具集的读写工具：脚本用 `fs.read` / `fs.write`（原文、不截断、按路径整体
- *   写入），不重复给一套为 LLM 上下文设计的行号/锚点语义；
- * - 两套工具集的搜索工具：脚本用 `call("Bash", { command })` 跑 `rg` / `grep` 更顺手——
- *   退出码可用、能拼管道，而这两个工具是给模型看结果的（相对路径、分组渲染、分页尾巴），
- *   声明块（尤其 Grep 的参数表与三选一输出）也白占 codemode 的描述篇幅。
+ * 准入条件：工具**声明了 `structuredSchema`** 才进 codemode。
+ *
+ * 脚本拿到的返回值必须有确定的形状——只给文本的工具在脚本里既没法当数据用（得解析文本），
+ * 也没有返回类型能写进声明。用「有没有结构化输出」当门槛，这条规则自己会维持一致：不给工具
+ * 加 schema 就不进集合，不需要维护一份会随工具增减而漂移的黑名单。因此下列工具天然不在集合
+ * 里，理由各自成立：`codemode` 自身与 `spawn-agent`（没有 schema）、文件读写工具（脚本用
+ * `fs.read` / `fs.write`，不重复一套为 LLM 上下文设计的行号/锚点语义）、搜索工具（脚本用
+ * `call("Bash", { command })` 跑 `rg`，退出码可用、能拼管道）、`lsp-rename`（写工具）以及
+ * talk / 会话工具（会把执行时间交给外部输入）。
  */
-const EXCLUDED_TOOL_NAMES: ReadonlySet<string> = new Set([
-  CODEMODE_TOOL_NAME,
-  "spawn-agent",
-  "Read",
-  "Edit",
-  "Write",
-  "read",
-  "edit",
-  "write",
-  "Grep",
-  "Glob",
-  "grep",
-  "glob",
-]);
-
 /** 估计 token 用的字符数（与 pi 一致）。 */
 const CHARS_PER_TOKEN = 4;
 
@@ -78,7 +64,8 @@ interface CallableTool {
   name: string;
   description?: string;
   parameters?: unknown;
-  structuredSchema?: unknown;
+  /** 准入条件：进集合的工具一定带着它（见上面的注释）。 */
+  structuredSchema: unknown;
 }
 
 /** 只在 pi 有 active 工具概念时才求交（子代理、`--tools` 等场景）。 */
@@ -94,7 +81,7 @@ function allowedToolNames(pi: ExtensionAPI): Set<string> | undefined {
 function collectTools(bus: ToolBus, allowed: Set<string> | undefined): CallableTool[] {
   return bus
     .list()
-    .filter((definition) => !EXCLUDED_TOOL_NAMES.has(definition.name))
+    .filter((definition) => definition.structuredSchema !== undefined)
     .filter((definition) => allowed === undefined || allowed.has(definition.name))
     .map((definition) => ({
       name: definition.name,

package/src/gh/base.ts

@@ -23,8 +23,11 @@ import {
   type GithubChecksClient,
   type GithubClientOptions,
   type GithubSearch,
+  normalizeRestList,
   renderHits,
+  type SearchHit,
 } from "../lib/github.js";
+import { createGithubReads, type GithubReads } from "../lib/github-reads.js";
 import { parseWithSchema } from "../lib/parse-with-schema.js";
 import { type ToolPendant } from "../lib/pendant.js";
 import { type StructuredResult } from "../lib/tool-bus.js";
@@ -140,24 +143,6 @@ export async function ghExec(
   return result.stdout;
 }
 
-export 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.
- */
-export 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. */
 export function splitRepo(nameWithOwner: string): { owner: string; repo: string } {
   const slash = nameWithOwner.indexOf("/");
@@ -323,58 +308,42 @@ export interface ListFilters {
 }
 
 /**
- * Build the `gh` argv for browsing issues/PRs (no keyword search).
- *
- * Keyword searches no longer go through the `gh` CLI — the octokit-based client
- * in `../lib/github.ts` handles them with state values (`all`, and `merged` for
- * PRs) that `gh search` cannot express. Browse calls keep `gh issue list` /
- * `gh pr list` semantics: `state` is passed through verbatim, since `gh issue
- * list` accepts open/closed/all and `gh pr list` additionally accepts merged.
+ * 浏览分支（不带 keywords）：走 octokit 的 REST 列表端点，再归一到与搜索分支同一套
+ * `SearchHit`。repo 缺省时先解析当前仓库——文本要据此决定是否带 repo 列，载荷里也必须有值。
  */
-export function listGithubArgs(kind: "issue" | "pr", params: ListFilters): string[] {
-  const { repo, state, label, author, assignee, milestone, limit } = params;
-
-  const args = [kind, "list", ...repoArgs(repo)];
-  if (state) {
-    args.push("--state", state);
-  }
-  if (label) {
-    args.push("--label", label);
-  }
-  if (author) {
-    args.push("--author", author);
-  }
-  if (assignee) {
-    args.push("--assignee", assignee);
-  }
-  if (milestone) {
-    args.push("--milestone", milestone);
-  }
-  if (limit) {
-    args.push("--limit", String(limit));
-  }
-  return args;
-}
-
-export async function listGithub(
+export async function browseList(
+  gh: GhClient,
   kind: "issue" | "pr",
   params: ListFilters,
   ctx: { cwd?: string; signal?: AbortSignal; input?: unknown },
-): Promise<string> {
-  return ghExec(listGithubArgs(kind, params), ctx);
+): Promise<{ repo: string; hits: SearchHit[] }> {
+  const repo = params.repo ?? (await resolveRepo(undefined, ctx.signal, ctx.cwd, ctx.input));
+  const { owner, repo: repoName } = splitRepo(repo);
+  const query = {
+    state: params.state,
+    label: params.label,
+    author: params.author,
+    assignee: params.assignee,
+    milestone: params.milestone,
+    limit: params.limit,
+  };
+  const items =
+    kind === "issue"
+      ? await gh.reads.listIssues(owner, repoName, query, ctx.signal)
+      : await gh.reads.listPulls(owner, repoName, query, ctx.signal);
+  return { repo, hits: normalizeRestList(items, repo) };
 }
 
-/** Run a keyword search through the octokit client and render the rows. */
-export async function searchList(
+/** 行列表的文本：两条分支共用一套 TSV 渲染；空结果是成功结果。 */
+export function renderHitList(
   kind: "issue" | "pr",
-  params: ListFilters,
-  githubSearch: GithubSearch,
-): Promise<string> {
-  const hits = await githubSearch.search(kind, params);
+  hits: SearchHit[],
+  options: { repo?: string; fields?: string },
+): string {
   if (hits.length === 0) {
     return `(no matching ${kind === "issue" ? "issues" : "pull requests"})`;
   }
-  return renderHits(hits, { repo: params.repo, fields: params.fields });
+  return renderHits(hits, options);
 }
 
 /**
@@ -390,6 +359,8 @@ export class GhClient {
   readonly fetch: typeof globalThis.fetch;
   readonly search: GithubSearch;
   readonly checks: GithubChecksClient;
+  /** REST 读取层：gh 工具的取数都走它（不再 spawn `gh` 取数据）。 */
+  readonly reads: GithubReads;
 
   constructor(
     fetchImpl: typeof globalThis.fetch = egress.fetch,
@@ -398,12 +369,31 @@ export class GhClient {
     this.fetch = fetchImpl;
     this.search = createGithubSearch({ fetch: fetchImpl, ...options });
     this.checks = createGithubChecks({ fetch: fetchImpl, ...options });
+    this.reads = createGithubReads({ fetch: fetchImpl, ...options });
   }
 }
 
 // ── checks watch (pure rendering + poll loop) ────────────────────────────────
 
 const CHECKS_POLL_INTERVAL_MS = 30_000;
+/** `watch-github-run` 的轮询间隔与上限。 */
+const RUN_WATCH_INTERVAL_MS = 30_000;
+const RUN_WATCH_DEADLINE_MS = 600_000;
+
+/** 运行快照：只声明我们渲染与载荷用到的字段，其余由 REST 原样带过。 */
+const runSnapshotSchema = Type.Object({
+  id: Type.Number(),
+  name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  display_title: Type.Optional(Type.String()),
+  status: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  conclusion: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  head_branch: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  event: Type.Optional(Type.String()),
+  created_at: Type.Optional(Type.String()),
+  updated_at: Type.Optional(Type.String()),
+  run_started_at: Type.Optional(Type.String()),
+  html_url: Type.Optional(Type.String()),
+});
 const CHECKS_WATCH_DEADLINE_MS = 600_000;
 
 export type CheckBucket = "pass" | "skipped" | "fail" | "pending";
@@ -644,6 +634,81 @@ export async function pollPrChecks(options: PollPrChecksOptions): Promise<Checks
   }
 }
 
+/** One polled workflow run: the REST fields the watch loop reports and renders. */
+export interface RunSnapshot {
+  id: number;
+  name?: string | null;
+  display_title?: string;
+  status?: string | null;
+  conclusion?: string | null;
+  head_branch?: string | null;
+  event?: string;
+  created_at?: string;
+  updated_at?: string;
+  run_started_at?: string;
+  html_url?: string;
+}
+
+/** 一行运行状态：`工作流 · 事件 · 分支 — 状态`（附耗时与链接）。 */
+export function renderRunStatus(run: RunSnapshot, elapsedMs?: number): string {
+  const state = run.conclusion ?? run.status ?? "unknown";
+  const facts = [run.name, run.event, run.head_branch].filter(Boolean).join(" · ");
+  const elapsed = elapsedMs === undefined ? "" : ` (${Math.round(elapsedMs / 1000)}s)`;
+  return `${facts} — ${state}${elapsed}${run.html_url === undefined ? "" : `\n${run.html_url}`}`;
+}
+
+export interface WatchRunOptions {
+  owner: string;
+  repo: string;
+  runId: number;
+  reads: GithubReads;
+  /** Owned by the caller; the poll loop observes it but never aborts it. */
+  signal: AbortSignal;
+  /** Test overrides. */
+  intervalMs?: number;
+  deadlineMs?: number;
+  onUpdate?: (msg: ToolResult) => void;
+}
+
+export interface RunWatchResult {
+  outcome: "completed" | "timeout";
+  run: RunSnapshot;
+  elapsedMs: number;
+}
+
+/**
+ * 轮询 `getWorkflowRun` 直到运行结束（`gh run watch` 的替代）：固定间隔轮询，每轮通过
+ * onUpdate 报一次当前状态，超过上限以 timeout 结束（不挂住）。
+ */
+export async function watchRun(options: WatchRunOptions): Promise<RunWatchResult> {
+  const { owner, repo, runId, reads, signal, onUpdate } = options;
+  const intervalMs = options.intervalMs ?? RUN_WATCH_INTERVAL_MS;
+  const deadlineMs = options.deadlineMs ?? RUN_WATCH_DEADLINE_MS;
+
+  const watchStart = Date.now();
+  for (;;) {
+    signal.throwIfAborted();
+    const run = parseWithSchema(runSnapshotSchema, await reads.run(owner, repo, runId, signal));
+    const elapsedMs = Date.now() - watchStart;
+    onUpdate?.({
+      content: [
+        {
+          type: "text",
+          text: `Watching workflow run ${runId}...\n${renderRunStatus(run, elapsedMs)}`,
+        },
+      ],
+      details: {},
+    });
+    if (run.status === "completed") {
+      return { outcome: "completed", run, elapsedMs };
+    }
+    if (elapsedMs >= deadlineMs) {
+      return { outcome: "timeout", run, elapsedMs };
+    }
+    await sleepInterruptibly(intervalMs, signal);
+  }
+}
+
 /** Job conclusions that count as "did not succeed" for CI result reporting. */
 const FAILED_JOB_CONCLUSIONS = new Set([
   "failure",

package/src/gh/render.ts

@@ -0,0 +1,259 @@
+/**
+ * 文本类 gh 工具改走 `--json` 之后的渲染器：同一份 JSON 既渲染成给模型看的文本，也原样
+ * 进结构化载荷。文本格式是我们自己的（不再是 gh 的表格），因此这些函数要稳定、好读，
+ * 且只依赖 schema 里声明过的字段。
+ */
+
+import { dateOnly } from "../lib/github.js";
+
+/**
+ * 一行一个 release：`tag  标记  发布日期  标题`。
+ *
+ * 标记有 `latest`（该仓库最新发布）/ `prerelease` / `draft`；REST 没有「isLatest」字段
+ * （那是 gh 按列表顺序算的），所以由调用方按第一个非 draft/prerelease 的条目传进来。
+ */
+export function renderReleaseList(
+  releases: {
+    tag_name: string;
+    name?: string | null;
+    latest?: boolean;
+    prerelease?: boolean;
+    draft?: boolean;
+    published_at?: string | null;
+  }[],
+): string {
+  if (releases.length === 0) {
+    return "(no releases)";
+  }
+  return releases
+    .map((release) => {
+      const flags = [
+        release.latest ? "latest" : "",
+        release.prerelease ? "prerelease" : "",
+        release.draft ? "draft" : "",
+      ].filter(Boolean);
+      return [
+        release.tag_name,
+        flags.join(","),
+        dateOnly(release.published_at),
+        release.name ?? "",
+      ].join("\t");
+    })
+    .join("\n");
+}
+
+/** 一行一个运行：`id  状态  结论  工作流  分支  事件  创建时间  链接`。 */
+export function renderRunList(
+  runs: {
+    id: number;
+    status?: string | null;
+    conclusion?: string | null;
+    name?: string | null;
+    head_branch?: string | null;
+    event?: string;
+    created_at?: string;
+    html_url?: string;
+  }[],
+): string {
+  if (runs.length === 0) {
+    return "(no workflow runs)";
+  }
+  return runs
+    .map((run) =>
+      [
+        String(run.id),
+        run.status ?? "",
+        run.conclusion ?? "",
+        run.name ?? "",
+        run.head_branch ?? "",
+        run.event ?? "",
+        dateOnly(run.created_at),
+        run.html_url ?? "",
+      ].join("\t"),
+    )
+    .join("\n");
+}
+
+/** 仓库概览：标题行 + 一行事实 + 一行链接 + 一行日期/许可。 */
+export function renderRepoView(repo: {
+  full_name?: string;
+  description?: string | null;
+  html_url?: string;
+  visibility?: string;
+  language?: string | null;
+  default_branch?: string;
+  stargazers_count?: number;
+  forks_count?: number;
+  open_issues_count?: number;
+  license?: { name?: string } | null;
+  pushed_at?: string;
+  created_at?: string;
+}): string {
+  const facts = [
+    repo.visibility?.toLowerCase(),
+    repo.language,
+    repo.default_branch && `default branch ${repo.default_branch}`,
+    repo.stargazers_count !== undefined && `stars ${repo.stargazers_count}`,
+    repo.forks_count !== undefined && `forks ${repo.forks_count}`,
+    repo.open_issues_count !== undefined && `open issues ${repo.open_issues_count}`,
+  ].filter(Boolean);
+  return [
+    [repo.full_name, repo.description].filter(Boolean).join(" — "),
+    facts.join(" · "),
+    repo.html_url ?? "",
+    [
+      repo.pushed_at && `pushed ${dateOnly(repo.pushed_at)}`,
+      repo.created_at && `created ${dateOnly(repo.created_at)}`,
+      repo.license?.name,
+    ]
+      .filter(Boolean)
+      .join(" · "),
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/** release 详情：标题、事实、资产清单、正文。 */
+export function renderReleaseView(release: {
+  tag_name?: string;
+  name?: string | null;
+  html_url?: string;
+  /** 由调用方按「列表里第一个非 draft / prerelease」推断（REST 没有这个字段）。 */
+  latest?: boolean;
+  prerelease?: boolean;
+  draft?: boolean;
+  published_at?: string | null;
+  created_at?: string;
+  author?: { login?: string } | null;
+  assets?: { name?: string; size?: number; download_count?: number }[];
+  body?: string | null;
+}): string {
+  const flags = [release.prerelease && "prerelease", release.draft && "draft"]
+    .filter(Boolean)
+    .join(",");
+  const assets = release.assets ?? [];
+  const lines = [
+    [release.tag_name, release.name].filter(Boolean).join(" — "),
+    [
+      `published ${dateOnly(release.published_at ?? release.created_at)}`,
+      flags,
+      release.author?.login && `by ${release.author.login}`,
+      release.html_url,
+    ]
+      .filter(Boolean)
+      .join(" · "),
+  ];
+  if (assets.length > 0) {
+    lines.push(`assets (${assets.length}):`);
+    for (const asset of assets) {
+      lines.push(
+        `- ${asset.name ?? ""} ${asset.size ?? 0} bytes, ${asset.download_count ?? 0} downloads`,
+      );
+    }
+  }
+  const body = release.body?.trim() ?? "";
+  if (body !== "") {
+    lines.push("", body);
+  }
+  return lines.join("\n");
+}
+
+export interface DiffFileStat {
+  path: string;
+  additions: number;
+  deletions: number;
+  oldPath?: string;
+}
+
+export interface DiffStats {
+  files: DiffFileStat[];
+  additions: number;
+  deletions: number;
+  changedFiles: number;
+}
+
+/** diff 里的路径：去掉 `a/` / `b/` 前缀与 git 给带空格路径加的双引号；`/dev/null` 给空串。 */
+function stripDiffPrefix(raw: string): string {
+  const trimmed = raw.trimEnd();
+  if (trimmed === "/dev/null") {
+    return "";
+  }
+  return trimmed
+    .replace(/^[ab]\//, "")
+    .replace(/^"/, "")
+    .replace(/"$/, "");
+}
+
+/** `diff --git a/x b/y` 的两个路径（路径带空格时 git 会加双引号）。 */
+function parseDiffHeader(rest: string): { oldPath: string; newPath: string } | undefined {
+  const match = /^(?:"a\/(.+)"|a\/(\S+)) (?:"b\/(.+)"|b\/(\S+))$/.exec(rest.trim());
+  if (!match) {
+    return undefined;
+  }
+  // 两组可选路径各有一个未参与匹配的捕获组（运行期是 undefined，类型上是 string），用 `||`
+  return { oldPath: match[1] || match[2], newPath: match[3] || match[4] };
+}
+
+/**
+ * 从 unified diff 文本里解析变更统计。
+ *
+ * `gh pr diff` 没有 `--json`，因此载荷只能从这里来。解析的边界都是 diff 的结构标记
+ * （`diff --git` / `---` / `+++` / `@@`），不依赖具体语言或文件内容：二进制文件与纯
+ * 模式变更（没有 `---` / `+++`）按 0 行变更计，路径取自 `diff --git` 头。
+ */
+export function parseDiffStats(diff: string): DiffStats {
+  const files: DiffFileStat[] = [];
+  let current: DiffFileStat | undefined;
+  /** `--- ` 给出的旧路径，等 `+++ ` 到了再决定它是不是重命名。 */
+  let oldPathFromHunk = "";
+  let inHunk = false;
+
+  for (const line of diff.split("\n")) {
+    if (line.startsWith("diff --git ")) {
+      if (current) {
+        files.push(current);
+      }
+      const header = parseDiffHeader(line.slice("diff --git ".length));
+      current = { path: header?.newPath ?? "", additions: 0, deletions: 0 };
+      oldPathFromHunk = header?.oldPath ?? "";
+      inHunk = false;
+      continue;
+    }
+    if (current === undefined) {
+      continue;
+    }
+    if (line.startsWith("--- ")) {
+      oldPathFromHunk = stripDiffPrefix(line.slice(4));
+      continue;
+    }
+    if (line.startsWith("+++ ")) {
+      const newPath = stripDiffPrefix(line.slice(4));
+      // 删除的文件新路径是 /dev/null，此时用旧路径当 path
+      current.path = newPath === "" ? oldPathFromHunk : newPath;
+      if (oldPathFromHunk !== "" && oldPathFromHunk !== current.path) {
+        current.oldPath = oldPathFromHunk;
+      }
+      continue;
+    }
+    if (line.startsWith("@@")) {
+      inHunk = true;
+      continue;
+    }
+    if (!inHunk) {
+      // 文件头（index / mode / rename / Binary files …）不算变更行
+      continue;
+    }
+    if (line.startsWith("+")) {
+      current.additions += 1;
+    } else if (line.startsWith("-")) {
+      current.deletions += 1;
+    }
+  }
+  if (current) {
+    files.push(current);
+  }
+
+  const additions = files.reduce((sum, file) => sum + file.additions, 0);
+  const deletions = files.reduce((sum, file) => sum + file.deletions, 0);
+  return { files, additions, deletions, changedFiles: files.length };
+}