@trim21/personal-pi-extensions 0.1.685 → 0.1.688

package/src/gh/schemas.ts

@@ -5,9 +5,8 @@
  * `structuredResult.value`。因此 schema 必须**允许额外字段**（GitHub 的 JSON 只多不少，
  * 多出来的字段不该让工具失败），只对工具本身已经依赖的字段设 required。
  *
- * 字段名取自 GitHub 的两种传输：`gh ... view --json`（GraphQL，actor 叫 `author` /
- * `user`）与 REST（`/pulls/:n/comments` 等，用了 `diff_hunk` / `submitted_at` 这类
- * 下划线命名）。评论与评审条目因此放宽成两者的并集。
+ * 字段名是 GitHub REST 的命名（`html_url` / `created_at` / `user.login`）：gh 工具的取数
+ * 全部走 octokit 之后不再有 `gh ... --json` 的 GraphQL 形状。
  */
 
 import { Type } from "typebox";
@@ -33,29 +32,27 @@ export const ghMilestoneSchema = Type.Object({
   dueOn: Type.Optional(Type.Union([Type.String(), Type.Null()])),
 });
 
-/** 评论条目：GraphQL 的 `author`/`createdAt` 与 REST 的 `user`/`diff_hunk` 并集。 */
+/** 评论条目：REST 的 issue/PR 评论与行内评审评论共用（`diff_hunk` 只有后者有）。 */
 export const ghCommentSchema = Type.Object({
-  id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
-  body: Type.Optional(Type.String()),
-  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  id: Type.Optional(Type.Number()),
+  body: Type.Optional(Type.Union([Type.String(), Type.Null()])),
   user: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
   path: Type.Optional(Type.String()),
   line: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
   diff_hunk: Type.Optional(Type.String()),
-  createdAt: Type.Optional(Type.String()),
-  url: Type.Optional(Type.String()),
+  created_at: Type.Optional(Type.String()),
+  updated_at: Type.Optional(Type.String()),
+  html_url: Type.Optional(Type.String()),
 });
 
-/** 评审条目：GraphQL 的 `reviews` 与 REST 的 `/pulls/:n/reviews` 并集。 */
+/** 评审条目：REST 的 `/pulls/:n/reviews`。 */
 export const ghReviewSchema = Type.Object({
-  id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
-  body: Type.Optional(Type.String()),
-  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  id: Type.Optional(Type.Number()),
+  body: Type.Optional(Type.Union([Type.String(), Type.Null()])),
   user: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
   state: Type.Optional(Type.String()),
-  createdAt: Type.Optional(Type.String()),
-  submitted_at: Type.Optional(Type.String()),
-  url: Type.Optional(Type.String()),
+  submitted_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  html_url: Type.Optional(Type.String()),
 });
 
 /** 待评审人：可能是用户（login）也可能是团队（slug）。 */
@@ -75,58 +72,57 @@ export const checkBucketSchema = Type.Union([
 
 // ── 各工具的输出 ─────────────────────────────────────────────────────────────
 
-/** `read-github-issue`：`gh issue view --json` 的输出。 */
+/** `read-github-issue`：`issues.get` 的响应（REST 字段名，未读字段不在这里出现也不影响校验）。 */
 export const issueViewSchema = Type.Object({
   number: Type.Number(),
   title: Type.String(),
   state: Type.String(),
-  body: Type.Optional(Type.String()),
-  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
-  createdAt: Type.Optional(Type.String()),
-  updatedAt: Type.Optional(Type.String()),
-  closedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-  url: Type.Optional(Type.String()),
+  body: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  user: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  created_at: Type.Optional(Type.String()),
+  updated_at: Type.Optional(Type.String()),
+  closed_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  html_url: Type.Optional(Type.String()),
   labels: Type.Optional(Type.Array(ghLabelSchema)),
-  assignees: Type.Optional(Type.Array(ghActorSchema)),
-  comments: Type.Optional(Type.Array(ghCommentSchema)),
+  assignees: Type.Optional(Type.Union([Type.Array(ghActorSchema), Type.Null()])),
+  /** REST 这里给的是评论**数量**（`gh issue view --json comments` 给的是数组）。 */
+  comments: Type.Optional(Type.Number()),
   milestone: Type.Optional(Type.Union([ghMilestoneSchema, Type.Null()])),
 });
 
-/** `read-github-pr`：`gh pr view --json` 的输出，比 issue 多出合并与 diff 统计。 */
+/** `read-github-pr`：`pulls.get` 的响应，比 issue 多出合并信息与 diff 统计。 */
 export const prViewSchema = Type.Object({
   number: Type.Number(),
   title: Type.String(),
   state: Type.String(),
-  body: Type.Optional(Type.String()),
-  author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
-  createdAt: Type.Optional(Type.String()),
-  updatedAt: Type.Optional(Type.String()),
-  closedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-  mergedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-  mergedBy: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
-  headRefName: Type.Optional(Type.String()),
-  baseRefName: Type.Optional(Type.String()),
-  url: Type.Optional(Type.String()),
+  body: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  user: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  created_at: Type.Optional(Type.String()),
+  updated_at: Type.Optional(Type.String()),
+  closed_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  merged_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  merged: Type.Optional(Type.Boolean()),
+  merged_by: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
+  head: Type.Optional(Type.Object({ ref: Type.Optional(Type.String()) })),
+  base: Type.Optional(Type.Object({ ref: Type.Optional(Type.String()) })),
+  html_url: Type.Optional(Type.String()),
   additions: Type.Optional(Type.Number()),
   deletions: Type.Optional(Type.Number()),
-  changedFiles: Type.Optional(Type.Number()),
+  changed_files: Type.Optional(Type.Number()),
   labels: Type.Optional(Type.Array(ghLabelSchema)),
-  assignees: Type.Optional(Type.Array(ghActorSchema)),
-  reviewRequests: Type.Optional(Type.Array(ghReviewRequestSchema)),
-  reviews: Type.Optional(Type.Array(ghReviewSchema)),
-  comments: Type.Optional(Type.Array(ghCommentSchema)),
+  assignees: Type.Optional(Type.Union([Type.Array(ghActorSchema), Type.Null()])),
+  requested_reviewers: Type.Optional(Type.Union([Type.Array(ghReviewRequestSchema), Type.Null()])),
   milestone: Type.Optional(Type.Union([ghMilestoneSchema, Type.Null()])),
 });
 
-/** `read-github-issue-comments`：`gh issue view --json comments`。 */
+/**
+ * 两个评论工具共用：`issues.listComments` 或 `pulls.listReviewComments` 的数组。
+ * `reviews: true`（只对 PR）时额外带 `pulls.listReviews` 的结果。
+ */
 export const issueCommentsSchema = Type.Object({
-  comments: Type.Array(ghCommentSchema),
+  comments: Type.Array(ghCommentSchema, { description: "该 issue / PR 的评论（分页取全）" }),
 });
 
-/**
- * `read-github-pr-comments`：默认模式是 `gh pr view --json comments`（只有 comments），
- * `reviews: true` 时走 REST 同时给出 reviews 与行内评论。两个字段都可选。
- */
 export const prCommentsSchema = Type.Object({
   comments: Type.Optional(Type.Array(ghCommentSchema)),
   reviews: Type.Optional(Type.Array(ghReviewSchema)),
@@ -263,16 +259,15 @@ export const ghHitListPayloadSchema = Type.Object(
   { additionalProperties: false },
 );
 
-/** `gh release list --json` 的一行。 */
+/** `repos.listReleases` 的一行（REST 字段名）。 */
 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()),
+    tag_name: Type.String(),
+    name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    draft: Type.Optional(Type.Boolean()),
+    prerelease: Type.Optional(Type.Boolean()),
+    published_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    created_at: Type.Optional(Type.String()),
   },
   { additionalProperties: true },
 );
@@ -285,20 +280,20 @@ export const ghReleaseListPayloadSchema = Type.Object(
   { additionalProperties: false },
 );
 
-/** `gh run list` / `gh run view --json` 的共同字段。 */
+/** `actions.listWorkflowRuns*` / `getWorkflowRun` 的共同字段（REST 字段名）。 */
 export const ghRunSummarySchema = Type.Object(
   {
-    databaseId: Type.Number(),
-    displayTitle: Type.Optional(Type.String()),
-    status: Type.Optional(Type.String()),
+    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()])),
-    workflowName: Type.Optional(Type.String()),
-    headBranch: Type.Optional(Type.String()),
+    head_branch: Type.Optional(Type.Union([Type.String(), Type.Null()])),
     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()),
+    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()),
   },
   { additionalProperties: true },
 );
@@ -311,7 +306,7 @@ export const ghRunListPayloadSchema = Type.Object(
   { additionalProperties: false },
 );
 
-/** `watch-github-run`：文本是 `gh run watch` 的输出，载荷是收尾时查到的运行状态。 */
+/** `watch-github-run`：文本是轮询进度与完成报告，载荷是收尾时查到的运行状态。 */
 export const ghRunPayloadSchema = Type.Object(
   {
     text: Type.String(),
@@ -320,88 +315,57 @@ export const ghRunPayloadSchema = Type.Object(
   { additionalProperties: false },
 );
 
-/** `gh repo view --json` 里我们渲染与脚本可能用到的字段。 */
+/** `repos.get` 里我们渲染与脚本可能用到的字段（REST 字段名）。 */
 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()),
+    full_name: Type.Optional(Type.String()),
+    description: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    html_url: Type.Optional(Type.String()),
+    homepage: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    private: Type.Optional(Type.Boolean()),
+    fork: Type.Optional(Type.Boolean()),
+    archived: Type.Optional(Type.Boolean()),
     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(),
-      ]),
+    language: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    default_branch: Type.Optional(Type.String()),
+    stargazers_count: Type.Optional(Type.Number()),
+    forks_count: Type.Optional(Type.Number()),
+    open_issues_count: Type.Optional(Type.Number()),
+    license: Type.Optional(
+      Type.Union([Type.Object({ name: Type.Optional(Type.String()) }), 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()),
+    pushed_at: Type.Optional(Type.String()),
+    created_at: Type.Optional(Type.String()),
+    updated_at: Type.Optional(Type.String()),
   },
   { additionalProperties: true },
 );
 
-export const ghRepoPayloadSchema = Type.Object(
-  {
-    text: Type.String(),
-    repo: ghRepoViewSchema,
-  },
-  { additionalProperties: false },
-);
-
-/** `gh release view --json` 里我们渲染与脚本可能用到的字段。 */
+/** `repos.getReleaseByTag` / `getLatestRelease` 里我们渲染与脚本可能用到的字段。 */
 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()),
+    tag_name: Type.Optional(Type.String()),
+    name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    body: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    html_url: Type.Optional(Type.String()),
+    draft: Type.Optional(Type.Boolean()),
+    prerelease: Type.Optional(Type.Boolean()),
+    created_at: Type.Optional(Type.String()),
+    published_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+    target_commitish: Type.Optional(Type.String()),
     author: Type.Optional(Type.Union([ghActorSchema, Type.Null()])),
     assets: Type.Optional(
       Type.Array(
         Type.Object(
           {
+            id: Type.Optional(Type.Number()),
             name: Type.Optional(Type.String()),
             size: Type.Optional(Type.Number()),
-            downloadCount: Type.Optional(Type.Number()),
-            contentType: Type.Optional(Type.String()),
+            download_count: Type.Optional(Type.Number()),
+            content_type: Type.Optional(Type.String()),
             state: Type.Optional(Type.String()),
-            url: Type.Optional(Type.String()),
+            browser_download_url: Type.Optional(Type.String()),
           },
           { additionalProperties: true },
         ),
@@ -419,6 +383,15 @@ export const ghReleaseViewPayloadSchema = Type.Object(
   { additionalProperties: false },
 );
 
+/** `repos.get` 的载荷：文本 + REST 响应。 */
+export const ghRepoPayloadSchema = Type.Object(
+  {
+    text: Type.String(),
+    repo: ghRepoViewSchema,
+  },
+  { additionalProperties: false },
+);
+
 /** `read-github-pr-diff`：文本是原始 diff，载荷是从它解析出的变更统计。 */
 export const ghDiffPayloadSchema = Type.Object(
   {

package/src/gh/tools/download-release-assets.ts

@@ -1,6 +1,6 @@
 import { mkdir, readdir, stat } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, matchesGlob } from "node:path";
 
 import { Type } from "typebox";
 import { Value } from "typebox/value";
@@ -9,9 +9,6 @@ import { type ToolPendant } from "../../lib/pendant.js";
 import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
 import {
   type GhClient,
-  GhError,
-  ghExec,
-  repoArgs,
   resolveRepo,
   splitRepo,
   structuredFailure,
@@ -30,10 +27,10 @@ interface ReleaseDownloadParams {
   archive?: "zip" | "tar.gz";
 }
 
-/** `gh release view --json tagName,assets` 里本工具真正读取的字段。 */
+/** `repos.getReleaseByTag` / `getLatestRelease` 里本工具真正读取的字段。 */
 const releaseViewSchema = Type.Object({
-  tagName: Type.String(),
-  assets: Type.Array(Type.Object({ name: Type.String(), size: Type.Number() })),
+  tag_name: Type.String(),
+  assets: Type.Array(Type.Object({ id: Type.Number(), name: Type.String(), size: Type.Number() })),
 });
 
 /** One regular file in a release's download directory. */
@@ -56,7 +53,7 @@ export function releaseAssetDir(repo: string, tag: string): string {
   return join(homedir(), ".cache", "pi", "github", "releases", owner, name, safeTag);
 }
 
-/** Split the comma-separated `pattern` toolcall parameter into gh pattern values. */
+/** Split the comma-separated `pattern` toolcall parameter into glob values. */
 export function releasePatterns(pattern: string | undefined): string[] {
   if (pattern === undefined) {
     return [];
@@ -67,28 +64,19 @@ export function releasePatterns(pattern: string | undefined): string[] {
     .filter((value) => value !== "");
 }
 
-/**
- * The `gh release download` argv. `--skip-existing` is always on: the download
- * directory is a cache, and rewriting a file that is already there would pull
- * the ground out from under anything reading it.
- */
-export function releaseDownloadArgs(options: {
-  tag: string;
-  repo: string;
-  dir: string;
-  patterns: readonly string[];
-  archive?: "zip" | "tar.gz";
-}): string[] {
-  const { tag, repo, dir, patterns, archive } = options;
-  const args = ["release", "download", tag, ...repoArgs(repo)];
-  if (archive !== undefined) {
-    args.push("--archive", archive);
-  }
-  for (const pattern of patterns) {
-    args.push("--pattern", pattern);
+/** 资产名是否命中任意一个 glob（`*` / `?` / `[...]` 都支持；无 glob 时取全部资产）。 */
+export function matchAsset(name: string, patterns: readonly string[]): boolean {
+  return patterns.length === 0 || patterns.some((pattern) => matchesGlob(name, pattern));
+}
+
+/** 文件大小；不存在（或读不到）时给 undefined，用来判断是否已下载完整。 */
+async function fileSize(path: string): Promise<number | undefined> {
+  try {
+    const info = await stat(path);
+    return info.size;
+  } catch {
+    return undefined;
   }
-  args.push("--dir", dir, "--skip-existing");
-  return args;
 }
 
 /** Regular files directly inside `dir`, with their sizes, sorted by name. */
@@ -107,22 +95,15 @@ async function listReleaseFiles(dir: string): Promise<ReleaseFile[]> {
 }
 
 /**
- * `gh release download` answers this exact message when a `--pattern` matched no
- * asset. It is the only signal the CLI offers, so the enrichment below degrades
- * to gh's own error (still thrown) if the wording ever changes.
- */
-const GH_NO_ASSET_MATCH = "no assets match the file pattern";
-
-/**
- * `download-github-release-assets`: fetch a release's assets (or source archive)
- * into `releaseAssetDir` with the gh credentials, so private repositories work
- * and the shell sandbox's network limits do not apply.
+ * `download-github-release-assets`: 把一个 release 的资产（或源码归档）下载到
+ * `releaseAssetDir`，用 `gh auth token` 的凭据，因此私有仓库可用、也不受 shell 沙箱的网络
+ * 限制。
  *
- * The tag is resolved through `gh release view` before downloading: a tag that
- * does not exist and a pattern that matched nothing are different answers, and
- * the release's own asset names are what the model needs to fix the second one.
+ * 先解析 release（缺 tag 时取 latest）：tag 不存在与「glob 没匹配到资产」是两种不同的答案，
+ * 后者要把该 release 实际的可选资产名列出来，模型才知道下一步怎么改。
  */
 export async function downloadReleaseAssets(
+  gh: GhClient,
   call: ToolCall<ReleaseDownloadParams>,
 ): Promise<StructuredResultOf<typeof releaseDownloadSchema> | StructuredFailureResult> {
   const { params, ctx, signal } = call;
@@ -134,58 +115,55 @@ export async function downloadReleaseAssets(
   }
 
   const effectiveRepo = await resolveRepo(params.repo, signal, ctx.cwd, params);
+  const { owner, repo: repoName } = splitRepo(effectiveRepo);
   const view = Value.Parse(
     releaseViewSchema,
-    JSON.parse(
-      await ghExec(
-        [
-          "release",
-          "view",
-          ...(params.tag === undefined ? [] : [params.tag]),
-          ...repoArgs(effectiveRepo),
-          "--json",
-          "tagName,assets",
-        ],
-        { cwd: ctx.cwd, signal, input: params },
-      ),
-    ),
+    await gh.reads.release(owner, repoName, params.tag, signal),
   );
 
   const assetNames = view.assets.map((asset) => asset.name);
-  const dir = releaseAssetDir(effectiveRepo, view.tagName);
+  const dir = releaseAssetDir(effectiveRepo, view.tag_name);
   await mkdir(dir, { recursive: true });
-  try {
-    await ghExec(
-      releaseDownloadArgs({
-        tag: view.tagName,
-        repo: effectiveRepo,
-        dir,
-        patterns,
-        ...(params.archive !== undefined && { archive: params.archive }),
-      }),
-      { cwd: ctx.cwd, signal, input: params },
-    );
-  } catch (error) {
-    // gh names the fault but not the choices; the release's asset list turns a
-    // dead end into the next toolcall.
-    if (error instanceof GhError && error.stderr.includes(GH_NO_ASSET_MATCH)) {
+
+  if (params.archive === undefined) {
+    const selected = view.assets.filter((asset) => matchAsset(asset.name, patterns));
+    if (selected.length === 0 && patterns.length > 0) {
       throw new Error(
-        `no asset of ${effectiveRepo}@${view.tagName} matched ${JSON.stringify(patterns)}; the release has: ${assetNames.join(", ") || "(no assets)"}`,
-        { cause: error },
+        `no asset of ${effectiveRepo}@${view.tag_name} matched ${JSON.stringify(patterns)}; the release has: ${assetNames.join(", ") || "(no assets)"}`,
       );
     }
-    throw error;
+    for (const asset of selected) {
+      const destPath = join(dir, asset.name);
+      // 同名且大小一致视为已完成（缓存目录里的半截文件不该被当成结果）
+      const existing = await fileSize(destPath);
+      if (existing === asset.size) {
+        continue;
+      }
+      await gh.reads.downloadAssetTo(owner, repoName, asset.id, destPath, signal);
+    }
+  } else {
+    const extension = params.archive === "zip" ? "zip" : "tar.gz";
+    // 归档是仓库源码的 tarball / zipball，名字由我们定（gh 用的是 `<owner>-<repo>-<tag>`）
+    const destPath = join(dir, `${repoName}-${view.tag_name}.${extension}`);
+    await gh.reads.downloadArchiveTo(
+      owner,
+      repoName,
+      params.archive,
+      view.tag_name,
+      destPath,
+      signal,
+    );
   }
 
   const files = await listReleaseFiles(dir);
-  const payload = { repo: effectiveRepo, tag: view.tagName, dir, files };
+  const payload = { repo: effectiveRepo, tag: view.tag_name, dir, files };
   const pendant: ToolPendant | undefined = subtitlePendant(
-    { repo: effectiveRepo, tag: view.tagName },
+    { repo: effectiveRepo, tag: view.tag_name },
     "tag",
   );
 
   if (files.length === 0 && params.archive === undefined) {
-    const text = `Nothing to download from ${effectiveRepo}@${view.tagName}: the release has no assets (try archive for the source tarball)`;
+    const text = `Nothing to download from ${effectiveRepo}@${view.tag_name}: the release has no assets (try archive for the source tarball)`;
     return {
       content: [{ type: "text", text }],
       details: {
@@ -207,14 +185,14 @@ export async function downloadReleaseAssets(
   );
 }
 
-export function addDownloadReleaseAssetsTool(_gh: GhClient, bus: ToolBus) {
+export function addDownloadReleaseAssetsTool(gh: GhClient, bus: ToolBus) {
   bus.register(
     defineStructuredTool({
       name: "download-github-release-assets",
       label: "GitHub Release Download",
       description:
         "Download a GitHub release's assets (or its source archive) into " +
-        "~/.cache/pi/github/releases/<owner>/<repo>/<tag>/ using the gh CLI's credentials, " +
+        "~/.cache/pi/github/releases/<owner>/<repo>/<tag>/ using the GitHub credentials, " +
         "so private repositories and large binaries work where a plain HTTP fetch cannot. " +
         "Files already in that directory are kept, never re-fetched. The result is the JSON " +
         "summary {repo, tag, dir, files:[{name, path, bytes}]} listing everything now in the " +
@@ -239,7 +217,7 @@ export function addDownloadReleaseAssetsTool(_gh: GhClient, bus: ToolBus) {
       }),
       structuredSchema: releaseDownloadSchema,
       async execute(_id, params, signal, _onUpdate, ctx) {
-        return downloadReleaseAssets({ params, ctx, signal });
+        return downloadReleaseAssets(gh, { params, ctx, signal });
       },
     }),
   );

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

@@ -26,7 +26,7 @@ async function listIssues(
   const { params, ctx, signal } = call;
   const { repo, hits } = params.keywords
     ? { repo: params.repo, hits: await gh.search.search("issue", params) }
-    : await browseList("issue", params, { cwd: ctx.cwd, signal, input: params });
+    : await browseList(gh, "issue", params, { cwd: ctx.cwd, signal, input: params });
   const text = renderHitList("issue", hits, { repo, fields: params.fields });
   const result = toToolResult(text, params);
   result.details.pendant = subtitlePendant(params);
@@ -52,14 +52,18 @@ export function addListIssuesTool(gh: GhClient, bus: ToolBus) {
           }),
         ),
         label: Type.Optional(Type.String({ description: "Filter by label" })),
-        // `@me` 由 GitHub 的搜索 / 过滤 API 解析：不带 keywords 时 gh 自行展开（GraphQL 过滤分支）
-        // 或按字面量转发（搜索分支），带 keywords 时我们直接把 `assignee:@me` 交给搜索 API。
-        // 两条传输都支持，因此本仓库不要再实现一次展开。
+        // `@me` 只在关键词搜索分支可用：搜索 API 自己把它解析成当前登录用户。浏览分支走
+        // REST 列表端点，`@me` 按字面量转发，不会匹配到当前用户（本仓库不做展开）。
         author: Type.Optional(
-          Type.String({ description: "Filter by author ('@me' for yourself)" }),
+          Type.String({
+            description: "Filter by author ('@me' works with keywords; browse takes it literally)",
+          }),
         ),
         assignee: Type.Optional(
-          Type.String({ description: "Filter by assignee ('@me' for yourself)" }),
+          Type.String({
+            description:
+              "Filter by assignee ('@me' works with keywords; browse takes it literally)",
+          }),
         ),
         milestone: Type.Optional(Type.String({ description: "Filter by milestone" })),
         limit: Type.Optional(Type.Number({ description: "Max results (default 30, max 100)" })),

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

@@ -26,7 +26,7 @@ async function listPrs(
   const { params, ctx, signal } = call;
   const { repo, hits } = params.keywords
     ? { repo: params.repo, hits: await gh.search.search("pr", params) }
-    : await browseList("pr", params, { cwd: ctx.cwd, signal, input: params });
+    : await browseList(gh, "pr", params, { cwd: ctx.cwd, signal, input: params });
   const text = renderHitList("pr", hits, { repo, fields: params.fields });
   const result = toToolResult(text, params);
   result.details.pendant = subtitlePendant(params);
@@ -52,14 +52,18 @@ export function addListPrsTool(gh: GhClient, bus: ToolBus) {
           }),
         ),
         label: Type.Optional(Type.String({ description: "Filter by label" })),
-        // `@me` 由 GitHub 的搜索 / 过滤 API 解析：不带 keywords 时 gh 自行展开（GraphQL 过滤分支）
-        // 或按字面量转发（搜索分支），带 keywords 时我们直接把 `assignee:@me` 交给搜索 API。
-        // 两条传输都支持，因此本仓库不要再实现一次展开。
+        // `@me` 只在关键词搜索分支可用：搜索 API 自己把它解析成当前登录用户。浏览分支走
+        // REST 列表端点，`@me` 按字面量转发，不会匹配到当前用户（本仓库不做展开）。
         author: Type.Optional(
-          Type.String({ description: "Filter by author ('@me' for yourself)" }),
+          Type.String({
+            description: "Filter by author ('@me' works with keywords; browse takes it literally)",
+          }),
         ),
         assignee: Type.Optional(
-          Type.String({ description: "Filter by assignee ('@me' for yourself)" }),
+          Type.String({
+            description:
+              "Filter by assignee ('@me' works with keywords; browse takes it literally)",
+          }),
         ),
         milestone: Type.Optional(Type.String({ description: "Filter by milestone" })),
         limit: Type.Optional(Type.Number({ description: "Max results (default 30, max 100)" })),