@trim21/personal-pi-extensions 0.1.684 → 0.1.685

package/README.md

@@ -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` 与写类工具共用同一套保护：写前要求「已读且读后

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.684",
+  "version": "0.1.685",
   "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

@@ -20,10 +20,13 @@ import {
   type CommitStatus,
   createGithubChecks,
   createGithubSearch,
+  GH_LIST_FIELDS,
   type GithubChecksClient,
   type GithubClientOptions,
   type GithubSearch,
+  normalizeGhList,
   renderHits,
+  type SearchHit,
 } from "../lib/github.js";
 import { parseWithSchema } from "../lib/parse-with-schema.js";
 import { type ToolPendant } from "../lib/pendant.js";
@@ -356,25 +359,32 @@ export function listGithubArgs(kind: "issue" | "pr", params: ListFilters): strin
   return args;
 }
 
-export async function listGithub(
+/**
+ * 浏览分支（`gh issue list` / `gh pr list`，不带 keywords）：直接要 `--json`，再归一到与
+ * 搜索分支同一套 `SearchHit`。repo 缺省时先解析当前仓库——文本要据此决定是否带 repo 列，
+ * 载荷里也必须有值。
+ */
+export async function browseList(
   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 args = [...listGithubArgs(kind, params), "--json", GH_LIST_FIELDS];
+  const stdout = await ghExec(args, ctx);
+  return { repo, hits: normalizeGhList(stdout, 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);
 }
 
 /**

package/src/gh/render.ts

@@ -0,0 +1,259 @@
+/**
+ * 文本类 gh 工具改走 `--json` 之后的渲染器：同一份 JSON 既渲染成给模型看的文本，也原样
+ * 进结构化载荷。文本格式是我们自己的（不再是 gh 的表格），因此这些函数要稳定、好读，
+ * 且只依赖 schema 里声明过的字段。
+ */
+
+import { dateOnly } from "../lib/github.js";
+
+/** 一行一个 release：`tag  标记  发布日期  标题`。 */
+export function renderReleaseList(
+  releases: {
+    tagName: string;
+    name?: string;
+    isLatest?: boolean;
+    isPrerelease?: boolean;
+    isDraft?: boolean;
+    publishedAt?: string | null;
+  }[],
+): string {
+  if (releases.length === 0) {
+    return "(no releases)";
+  }
+  return releases
+    .map((release) => {
+      const flags = [
+        release.isLatest ? "latest" : "",
+        release.isPrerelease ? "prerelease" : "",
+        release.isDraft ? "draft" : "",
+      ].filter(Boolean);
+      return [
+        release.tagName,
+        flags.join(","),
+        dateOnly(release.publishedAt),
+        release.name ?? "",
+      ].join("\t");
+    })
+    .join("\n");
+}
+
+/** 一行一个运行：`id  状态  结论  工作流  分支  事件  创建时间  链接`。 */
+export function renderRunList(
+  runs: {
+    databaseId: number;
+    status?: string;
+    conclusion?: string | null;
+    workflowName?: string;
+    headBranch?: string;
+    event?: string;
+    createdAt?: string;
+    url?: string;
+  }[],
+): string {
+  if (runs.length === 0) {
+    return "(no workflow runs)";
+  }
+  return runs
+    .map((run) =>
+      [
+        String(run.databaseId),
+        run.status ?? "",
+        run.conclusion ?? "",
+        run.workflowName ?? "",
+        run.headBranch ?? "",
+        run.event ?? "",
+        dateOnly(run.createdAt),
+        run.url ?? "",
+      ].join("\t"),
+    )
+    .join("\n");
+}
+
+/** 仓库概览：标题行 + 一行事实 + 一行链接 + 一行日期/许可。 */
+export function renderRepoView(repo: {
+  nameWithOwner?: string;
+  description?: string;
+  url?: string;
+  visibility?: string;
+  primaryLanguage?: { name: string } | null;
+  defaultBranchRef?: { name: string } | null;
+  stargazerCount?: number;
+  forkCount?: number;
+  issues?: { totalCount: number } | null;
+  pullRequests?: { totalCount: number } | null;
+  licenseInfo?: { name: string } | null;
+  pushedAt?: string;
+  createdAt?: string;
+}): string {
+  const facts = [
+    repo.visibility?.toLowerCase(),
+    repo.primaryLanguage?.name,
+    repo.defaultBranchRef && `default branch ${repo.defaultBranchRef.name}`,
+    repo.stargazerCount !== undefined && `stars ${repo.stargazerCount}`,
+    repo.forkCount !== undefined && `forks ${repo.forkCount}`,
+    repo.issues && `open issues ${repo.issues.totalCount}`,
+    repo.pullRequests && `open PRs ${repo.pullRequests.totalCount}`,
+  ].filter(Boolean);
+  return [
+    [repo.nameWithOwner, repo.description].filter(Boolean).join(" — "),
+    facts.join(" · "),
+    repo.url ?? "",
+    [
+      repo.pushedAt && `pushed ${dateOnly(repo.pushedAt)}`,
+      repo.createdAt && `created ${dateOnly(repo.createdAt)}`,
+      repo.licenseInfo?.name,
+    ]
+      .filter(Boolean)
+      .join(" · "),
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/** release 详情：标题、事实、资产清单、正文。 */
+export function renderReleaseView(release: {
+  tagName?: string;
+  name?: string;
+  url?: string;
+  isLatest?: boolean;
+  isPrerelease?: boolean;
+  isDraft?: boolean;
+  publishedAt?: string | null;
+  createdAt?: string;
+  author?: { login?: string } | null;
+  assets?: { name?: string; size?: number; downloadCount?: number }[];
+  body?: string;
+}): string {
+  const flags = [
+    release.isLatest && "latest",
+    release.isPrerelease && "prerelease",
+    release.isDraft && "draft",
+  ]
+    .filter(Boolean)
+    .join(",");
+  const assets = release.assets ?? [];
+  const lines = [
+    [release.tagName, release.name].filter(Boolean).join(" — "),
+    [
+      `published ${dateOnly(release.publishedAt ?? release.createdAt)}`,
+      flags,
+      release.author?.login && `by ${release.author.login}`,
+      release.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.downloadCount ?? 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 };
+}

package/src/gh/schemas.ts

@@ -228,3 +228,216 @@ export const checksVerdictSchema = Type.Object({
     }),
   ),
 });
+
+// ── 文本类工具改成 --json 之后的载荷 ─────────────────────────────────────────
+//
+// 这批工具的文本由我们自己从 JSON 渲染，因此载荷是 gh 的 JSON（字段名就是 gh 的）加一个
+// `text`（与工具输出一致）。与上面十个透传工具一样，gh 的 JSON 允许额外字段。
+
+/** `list-github-issues` / `list-github-prs` 的一行：浏览与搜索两条分支归一后的记录。 */
+export const ghHitSchema = Type.Object(
+  {
+    number: Type.Number(),
+    state: Type.Union([Type.Literal("open"), Type.Literal("closed"), Type.Literal("merged")]),
+    title: Type.String(),
+    url: Type.String(),
+    repo: Type.String({ description: "OWNER/REPO；浏览分支取参数或当前仓库" }),
+    author: Type.String(),
+    labels: Type.Array(Type.String()),
+    milestone: Type.String(),
+    assignees: Type.Array(Type.String()),
+    comments: Type.Number({ description: "评论数（浏览分支是评论数组的长度）" }),
+    createdAt: Type.String({ description: "YYYY-MM-DD" }),
+    updatedAt: Type.String({ description: "YYYY-MM-DD" }),
+    closedAt: Type.String(),
+    mergedAt: Type.String(),
+  },
+  { additionalProperties: false },
+);
+
+export const ghHitListPayloadSchema = Type.Object(
+  {
+    text: Type.String({ description: "与工具输出一致的行列表（可能被行数/字节预算截断）" }),
+    items: Type.Array(ghHitSchema, { description: "全部命中，不受文本截断影响" }),
+  },
+  { additionalProperties: false },
+);
+
+/** `gh release list --json` 的一行。 */
+export const ghReleaseSummarySchema = Type.Object(
+  {
+    tagName: Type.String(),
+    name: Type.Optional(Type.String()),
+    isLatest: Type.Optional(Type.Boolean()),
+    isPrerelease: Type.Optional(Type.Boolean()),
+    isDraft: Type.Optional(Type.Boolean()),
+    publishedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    createdAt: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+export const ghReleaseListPayloadSchema = Type.Object(
+  {
+    text: Type.String(),
+    releases: Type.Array(ghReleaseSummarySchema),
+  },
+  { additionalProperties: false },
+);
+
+/** `gh run list` / `gh run view --json` 的共同字段。 */
+export const ghRunSummarySchema = Type.Object(
+  {
+    databaseId: Type.Number(),
+    displayTitle: Type.Optional(Type.String()),
+    status: Type.Optional(Type.String()),
+    conclusion: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    workflowName: Type.Optional(Type.String()),
+    headBranch: Type.Optional(Type.String()),
+    event: Type.Optional(Type.String()),
+    createdAt: Type.Optional(Type.String()),
+    updatedAt: Type.Optional(Type.String()),
+    startedAt: Type.Optional(Type.String()),
+    url: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+export const ghRunListPayloadSchema = Type.Object(
+  {
+    text: Type.String(),
+    runs: Type.Array(ghRunSummarySchema),
+  },
+  { additionalProperties: false },
+);
+
+/** `watch-github-run`：文本是 `gh run watch` 的输出，载荷是收尾时查到的运行状态。 */
+export const ghRunPayloadSchema = Type.Object(
+  {
+    text: Type.String(),
+    run: ghRunSummarySchema,
+  },
+  { additionalProperties: false },
+);
+
+/** `gh repo view --json` 里我们渲染与脚本可能用到的字段。 */
+export const ghRepoViewSchema = Type.Object(
+  {
+    name: Type.Optional(Type.String()),
+    nameWithOwner: Type.Optional(Type.String()),
+    description: Type.Optional(Type.String()),
+    url: Type.Optional(Type.String()),
+    homepageUrl: Type.Optional(Type.String()),
+    visibility: Type.Optional(Type.String()),
+    isPrivate: Type.Optional(Type.Boolean()),
+    isFork: Type.Optional(Type.Boolean()),
+    isArchived: Type.Optional(Type.Boolean()),
+    stargazerCount: Type.Optional(Type.Number()),
+    forkCount: Type.Optional(Type.Number()),
+    primaryLanguage: Type.Optional(
+      Type.Union([
+        Type.Object({ name: Type.String() }, { additionalProperties: true }),
+        Type.Null(),
+      ]),
+    ),
+    defaultBranchRef: Type.Optional(
+      Type.Union([
+        Type.Object({ name: Type.String() }, { additionalProperties: true }),
+        Type.Null(),
+      ]),
+    ),
+    licenseInfo: Type.Optional(
+      Type.Union([
+        Type.Object({ name: Type.String() }, { additionalProperties: true }),
+        Type.Null(),
+      ]),
+    ),
+    issues: Type.Optional(
+      Type.Union([
+        Type.Object({ totalCount: Type.Number() }, { additionalProperties: true }),
+        Type.Null(),
+      ]),
+    ),
+    pullRequests: Type.Optional(
+      Type.Union([
+        Type.Object({ totalCount: Type.Number() }, { additionalProperties: true }),
+        Type.Null(),
+      ]),
+    ),
+    pushedAt: Type.Optional(Type.String()),
+    createdAt: Type.Optional(Type.String()),
+    updatedAt: Type.Optional(Type.String()),
+  },
+  { additionalProperties: true },
+);
+
+export const ghRepoPayloadSchema = Type.Object(
+  {
+    text: Type.String(),
+    repo: ghRepoViewSchema,
+  },
+  { additionalProperties: false },
+);
+
+/** `gh release view --json` 里我们渲染与脚本可能用到的字段。 */
+export const ghReleaseViewSchema = Type.Object(
+  {
+    tagName: Type.Optional(Type.String()),
+    name: Type.Optional(Type.String()),
+    body: Type.Optional(Type.String()),
+    url: Type.Optional(Type.String()),
+    isDraft: Type.Optional(Type.Boolean()),
+    isPrerelease: Type.Optional(Type.Boolean()),
+    createdAt: Type.Optional(Type.String()),
+    publishedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    targetCommitish: Type.Optional(Type.String()),
+    author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+    assets: Type.Optional(
+      Type.Array(
+        Type.Object(
+          {
+            name: Type.Optional(Type.String()),
+            size: Type.Optional(Type.Number()),
+            downloadCount: Type.Optional(Type.Number()),
+            contentType: Type.Optional(Type.String()),
+            state: Type.Optional(Type.String()),
+            url: Type.Optional(Type.String()),
+          },
+          { additionalProperties: true },
+        ),
+      ),
+    ),
+  },
+  { additionalProperties: true },
+);
+
+export const ghReleaseViewPayloadSchema = Type.Object(
+  {
+    text: Type.String(),
+    release: ghReleaseViewSchema,
+  },
+  { additionalProperties: false },
+);
+
+/** `read-github-pr-diff`：文本是原始 diff，载荷是从它解析出的变更统计。 */
+export const ghDiffPayloadSchema = Type.Object(
+  {
+    text: Type.String(),
+    files: Type.Array(
+      Type.Object(
+        {
+          path: Type.String(),
+          additions: Type.Number(),
+          deletions: Type.Number(),
+          /** diff 里的旧路径，重命名/复制时与 `path` 不同。 */
+          oldPath: Type.Optional(Type.String()),
+        },
+        { additionalProperties: false },
+      ),
+    ),
+    additions: Type.Number(),
+    deletions: Type.Number(),
+    changedFiles: Type.Number(),
+  },
+  { additionalProperties: false },
+);