@trim21/personal-pi-extensions 0.1.684 → 0.1.687

package/src/lib/github-reads.ts

@@ -0,0 +1,405 @@
+/**
+ * gh 工具的 REST 读取层：把「按 owner/repo/编号取数据」这一件事集中在这里，让工具文件
+ * 只关心渲染与载荷（与 `createGithubSearch` / `createGithubChecks` 并列）。
+ *
+ * 与 `gh … --json` 的差别：字段名是 GitHub REST 的（`html_url` / `closed_at` / `user.login`），
+ * 工具因此直接把响应原物给模型与结构化载荷，不再有 GraphQL 形状的中间层。
+ *
+ * 认证、代理与 401 重试都由 `createGithubApi` 承担（同一个缓存 client）；二进制下载走
+ * `rawFetch`，因为 octokit 会把响应体按 JSON 解析。
+ */
+
+import { createWriteStream } from "node:fs";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+import type { Octokit } from "octokit";
+
+import { createGithubApi, type GithubClientOptions } from "./github.js";
+
+/** `actions.listWorkflowRuns*` 的 `status` 取值（octokit 是字面量联合，工具参数是 string）。 */
+type WorkflowRunParams = NonNullable<
+  Parameters<Octokit["rest"]["actions"]["listWorkflowRunsForRepo"]>[0]
+>;
+type WorkflowRunStatus = NonNullable<WorkflowRunParams["status"]>;
+
+/** 列表类查询的公共过滤条件；与工具的 `ListFilters` 一一对应。 */
+export interface ListQuery {
+  state?: string;
+  label?: string;
+  author?: string;
+  assignee?: string;
+  milestone?: string;
+  limit?: number;
+}
+
+export interface GithubReads {
+  issue(owner: string, repo: string, number: number, signal?: AbortSignal): Promise<unknown>;
+  pull(owner: string, repo: string, number: number, signal?: AbortSignal): Promise<unknown>;
+  issueComments(
+    owner: string,
+    repo: string,
+    number: number,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  pullReviewComments(
+    owner: string,
+    repo: string,
+    number: number,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  pullReviews(
+    owner: string,
+    repo: string,
+    number: number,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  listIssues(
+    owner: string,
+    repo: string,
+    query: ListQuery,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  listPulls(
+    owner: string,
+    repo: string,
+    query: ListQuery,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  pullDiff(owner: string, repo: string, number: number, signal?: AbortSignal): Promise<string>;
+  listReleases(
+    owner: string,
+    repo: string,
+    limit: number | undefined,
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  /** `tag` 缺省时取 latest release（与 `gh release view` 的缺省一致）。 */
+  release(
+    owner: string,
+    repo: string,
+    tag: string | undefined,
+    signal?: AbortSignal,
+  ): Promise<unknown>;
+  listRuns(
+    owner: string,
+    repo: string,
+    query: { workflow?: string; status?: string; limit?: number },
+    signal?: AbortSignal,
+  ): Promise<unknown[]>;
+  run(owner: string, repo: string, runId: number, signal?: AbortSignal): Promise<unknown>;
+  repository(owner: string, repo: string, signal?: AbortSignal): Promise<unknown>;
+  /** job 的原始日志文本（GitHub 只有按 job id 取日志的端点）。 */
+  jobLogs(owner: string, repo: string, jobId: number, signal?: AbortSignal): Promise<string>;
+  /** 下载一个 release 资产到 `destPath`（流式，不整体驻留内存）。 */
+  downloadAssetTo(
+    owner: string,
+    repo: string,
+    assetId: number,
+    destPath: string,
+    signal?: AbortSignal,
+  ): Promise<void>;
+  /** 下载仓库源码归档（`gh release download --archive` 的对应物）。 */
+  downloadArchiveTo(
+    owner: string,
+    repo: string,
+    format: "zip" | "tar.gz",
+    ref: string | undefined,
+    destPath: string,
+    signal?: AbortSignal,
+  ): Promise<void>;
+}
+
+/** REST 列表查询把工具的 state 过滤映射成 `state` 参数（issue/PR 的值集合相同）。 */
+function stateParam(state: string | undefined): "open" | "closed" | "all" | undefined {
+  if (state === undefined || state === "all") {
+    return state === "all" ? "all" : undefined;
+  }
+  if (state === "open" || state === "closed") {
+    return state;
+  }
+  // merged 只对搜索路径有意义（列表端点没有这个状态），列表侧按 all 处理
+  if (state === "merged") {
+    return "all";
+  }
+  throw new Error(`invalid state: ${state} (expected open, closed, all)`);
+}
+
+/** `@me` 是 gh CLI 的简写，REST 列表端点不认识；按字面量转发（用户明确不做展开）。 */
+function listParams(query: ListQuery): {
+  state?: "open" | "closed" | "all";
+  labels?: string;
+  assignee?: string;
+  creator?: string;
+  milestone?: string;
+} {
+  const state = stateParam(query.state);
+  return {
+    ...(state !== undefined && { state }),
+    ...(query.label !== undefined && { labels: query.label }),
+    ...(query.assignee !== undefined && { assignee: query.assignee }),
+    ...(query.author !== undefined && { creator: query.author }),
+    ...(query.milestone !== undefined && { milestone: query.milestone }),
+  };
+}
+
+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 };
+}
+
+/** 把 octokit 的类型化 data 当外部 JSON 交出去：调用方用 schema 校验自己读的字段。 */
+function asJson(value: unknown): unknown {
+  return value;
+}
+
+export function createGithubReads(options: GithubClientOptions = {}): GithubReads {
+  const api = createGithubApi(options);
+
+  return {
+    async issue(owner, repo, number, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.issues.get({ owner, repo, issue_number: number, ...octokitRequest(signal) }),
+      );
+      return asJson(data);
+    },
+
+    async pull(owner, repo, number, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.pulls.get({ owner, repo, pull_number: number, ...octokitRequest(signal) }),
+      );
+      return asJson(data);
+    },
+
+    async issueComments(owner, repo, number, signal) {
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.issues.listComments, {
+          owner,
+          repo,
+          issue_number: number,
+          per_page: 100,
+          ...octokitRequest(signal),
+        }),
+      );
+      return data.map((item) => asJson(item));
+    },
+
+    async pullReviewComments(owner, repo, number, signal) {
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.pulls.listReviewComments, {
+          owner,
+          repo,
+          pull_number: number,
+          per_page: 100,
+          ...octokitRequest(signal),
+        }),
+      );
+      return data.map((item) => asJson(item));
+    },
+
+    async pullReviews(owner, repo, number, signal) {
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.pulls.listReviews, {
+          owner,
+          repo,
+          pull_number: number,
+          per_page: 100,
+          ...octokitRequest(signal),
+        }),
+      );
+      return data.map((item) => asJson(item));
+    },
+
+    async listIssues(owner, repo, query, signal) {
+      const limit = limitOf(query.limit, 30);
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.issues.listForRepo, {
+          owner,
+          repo,
+          per_page: limit,
+          ...listParams(query),
+          ...octokitRequest(signal),
+        }),
+      );
+      // 列表端点混着 PR（REST 的 issues 列表包含 PR），与 gh issue list 一致地过滤掉
+      const issues = data.filter((item) => !("pull_request" in item));
+      return issues.slice(0, limit).map((item) => asJson(item));
+    },
+
+    async listPulls(owner, repo, query, signal) {
+      const limit = limitOf(query.limit, 30);
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.pulls.list, {
+          owner,
+          repo,
+          per_page: limit,
+          ...listParams(query),
+          ...octokitRequest(signal),
+        }),
+      );
+      return data.slice(0, limit).map((item) => asJson(item));
+    },
+
+    async pullDiff(owner, repo, number, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.pulls.get({
+          owner,
+          repo,
+          pull_number: number,
+          mediaType: { format: "diff" },
+          ...octokitRequest(signal),
+        }),
+      );
+      // diff 媒体类型下 data 是原始 diff 文本；octokit 的类型仍按 JSON 声明，所以这里
+      // 显式断言而不是把对象 stringify（[object Object] 会静默毁掉 diff）
+      return data as unknown as string;
+    },
+
+    async listReleases(owner, repo, limit, signal) {
+      const data = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.repos.listReleases, {
+          owner,
+          repo,
+          per_page: limitOf(limit, 10),
+          ...octokitRequest(signal),
+        }),
+      );
+      return data.map((item) => asJson(item));
+    },
+
+    async release(owner, repo, tag, signal) {
+      const { data } = await api.call((octokit) =>
+        tag === undefined
+          ? octokit.rest.repos.getLatestRelease({ owner, repo, ...octokitRequest(signal) })
+          : octokit.rest.repos.getReleaseByTag({ owner, repo, tag, ...octokitRequest(signal) }),
+      );
+      return asJson(data);
+    },
+
+    async listRuns(owner, repo, query, signal) {
+      const limit = limitOf(query.limit, 20);
+      let workflowId: number | undefined;
+      if (query.workflow !== undefined) {
+        const workflows = await api.call((octokit) =>
+          octokit.paginate(octokit.rest.actions.listRepoWorkflows, {
+            owner,
+            repo,
+            per_page: 100,
+            ...octokitRequest(signal),
+          }),
+        );
+        const wanted = query.workflow.toLowerCase();
+        const match = workflows.find(
+          (workflow) =>
+            workflow.name.toLowerCase() === wanted ||
+            workflow.path.toLowerCase() === wanted ||
+            workflow.path.toLowerCase().endsWith(`/${wanted}`),
+        );
+        if (match === undefined) {
+          const names = workflows.map((workflow) => workflow.name).join(", ");
+          throw new Error(`workflow "${query.workflow}" not found (available: ${names})`);
+        }
+        workflowId = match.id;
+      }
+      const data = await api.call(async (octokit) => {
+        const params = {
+          owner,
+          repo,
+          per_page: limit,
+          // REST 的 status 同时接受运行状态与结论（success / failure / in_progress …）；
+          // octokit 把取值声明成字面量联合，这里按它的类型断言（非法取值由 API 报 422）
+          ...(query.status !== undefined && { status: query.status as WorkflowRunStatus }),
+          ...octokitRequest(signal),
+        };
+        return workflowId === undefined
+          ? octokit.paginate(octokit.rest.actions.listWorkflowRunsForRepo, params)
+          : octokit.paginate(octokit.rest.actions.listWorkflowRuns, {
+              ...params,
+              workflow_id: workflowId,
+            });
+      });
+      return data.slice(0, limit).map((item) => asJson(item));
+    },
+
+    async run(owner, repo, runId, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.actions.getWorkflowRun({
+          owner,
+          repo,
+          run_id: runId,
+          ...octokitRequest(signal),
+        }),
+      );
+      return asJson(data);
+    },
+
+    async repository(owner, repo, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.repos.get({ owner, repo, ...octokitRequest(signal) }),
+      );
+      return asJson(data);
+    },
+
+    async jobLogs(owner, repo, jobId, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.actions.downloadJobLogsForWorkflowRun({
+          owner,
+          repo,
+          job_id: jobId,
+          ...octokitRequest(signal),
+        }),
+      );
+      // 日志端点的响应体是文本；octokit 的类型是 `unknown`（按响应内容而定），这里断言
+      return data as string;
+    },
+
+    async downloadAssetTo(owner, repo, assetId, destPath, signal) {
+      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);
+    },
+
+    async downloadArchiveTo(owner, repo, format, ref, destPath, signal) {
+      const kind = format === "zip" ? "zipball" : "tarball";
+      const suffix = ref === undefined ? "" : `/${ref}`;
+      const response = await api.rawFetch(
+        `https://api.github.com/repos/${owner}/${repo}/${kind}${suffix}`,
+        { ...(signal && { signal }) },
+      );
+      await ensureOk(response);
+      await streamToFile(response, destPath);
+    },
+  };
+}
+
+/** 把响应体流式写入文件；响应没有 body（空资产）时写空文件。 */
+async function streamToFile(response: Response, destPath: string): Promise<void> {
+  const body = response.body;
+  if (body === null) {
+    await pipeline(Readable.from([]), createWriteStream(destPath));
+    return;
+  }
+  await pipeline(Readable.fromWeb(body), createWriteStream(destPath));
+}

package/src/lib/github.ts

@@ -186,6 +186,11 @@ export function renderHits(hits: SearchHit[], options: { repo?: string; fields?:
 }
 
 function toDate(iso: string | null | undefined): string {
+  return dateOnly(iso);
+}
+
+/** ISO 时间戳取日期部分（`2026-10-03`）；缺省或 null 给空串。 */
+export function dateOnly(iso: string | null | undefined): string {
   return iso ? iso.slice(0, 10) : "";
 }
 
@@ -217,6 +222,53 @@ function normalize(raw: SearchItem): SearchHit {
   };
 }
 
+/**
+ * REST 列表端点（`issues.listForRepo` / `pulls.list`）的条目形状。与搜索 API 的条目差别：
+ * repo 不在条目里（由调用方给），PR 的合并信息在 `merged_at`/`merged`。
+ */
+const restListItemSchema = Type.Object({
+  number: Type.Number(),
+  state: Type.String(),
+  title: Type.String(),
+  html_url: Type.String(),
+  user: Type.Union([Type.Object({ login: Type.String() }), Type.Null()]),
+  labels: Type.Array(Type.Object({ name: Type.Optional(Type.String()) })),
+  milestone: Type.Union([Type.Object({ title: Type.Optional(Type.String()) }), Type.Null()]),
+  assignees: Type.Union([Type.Array(Type.Object({ login: Type.String() })), Type.Null()]),
+  comments: Type.Optional(Type.Number()),
+  created_at: Type.String(),
+  updated_at: Type.String(),
+  closed_at: Type.Union([Type.String(), Type.Null()]),
+  merged_at: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+});
+
+/**
+ * 把 REST 列表条目归一到 `SearchHit`，与搜索分支共用一套渲染与载荷。`repo` 由调用方给
+ * （REST 列表端点的条目里没有仓库信息）。
+ */
+export function normalizeRestList(items: unknown, repo: string): SearchHit[] {
+  return parseWithSchema(Type.Array(restListItemSchema), items).map((item) => {
+    const mergedAt = item.merged_at ?? null;
+    return {
+      number: item.number,
+      // 已合并的 PR 在 REST 里也是 `closed`，merged 语义与搜索分支一致地由 merged_at 推断
+      state: mergedAt === null ? (item.state === "open" ? "open" : "closed") : "merged",
+      title: item.title,
+      url: item.html_url,
+      repo,
+      author: item.user?.login ?? "",
+      labels: item.labels.map((label) => label.name ?? ""),
+      milestone: item.milestone?.title ?? "",
+      assignees: (item.assignees ?? []).map((assignee) => assignee.login),
+      comments: item.comments ?? 0,
+      createdAt: toDate(item.created_at),
+      updatedAt: toDate(item.updated_at),
+      closedAt: toDate(item.closed_at),
+      mergedAt: toDate(mergedAt),
+    };
+  });
+}
+
 /**
  * Error thrown when the GitHub search API rejects the request. Carries the
  * original toolcall params so the model can see the exact input.
@@ -246,9 +298,14 @@ function describeHttpError(status: number | undefined): string {
   return `GitHub API error${status === undefined ? "" : ` (HTTP ${status})`}`;
 }
 
-interface GithubApi {
+export interface GithubApi {
   /** Run an octokit request; retries once with a fresh token on 401. */
   call<T>(fn: (octokit: Octokit) => Promise<T>): Promise<T>;
+  /**
+   * 用同一个 token 直接 fetch（二进制资产、源码归档这类要走原始响应体、不能经 octokit
+   * 的 JSON 解析的请求）。重定向自动跟随，401 同样丢缓存重试一次。
+   */
+  rawFetch(url: string, init?: RequestInit): Promise<Response>;
 }
 
 export interface GithubClientOptions {
@@ -268,17 +325,41 @@ export interface GithubClientOptions {
  * module-level state. A stale cached token can produce 401s; the cache is
  * dropped and the request retried once in that case.
  */
-function createGithubApi(options: GithubClientOptions = {}): GithubApi {
+export function createGithubApi(options: GithubClientOptions = {}): GithubApi {
   let client: Octokit | undefined;
+  // token 单独缓存：rawFetch（二进制/归档下载）不走 octokit，但同样不该每次 spawn
+  // `gh auth token`。401 时两个缓存一起丢。
+  let token: string | undefined;
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const tokenProvider = options.token ?? ghAuthToken;
+
+  async function getToken(): Promise<string> {
+    token ??= await tokenProvider();
+    return token;
+  }
 
   async function getClient(): Promise<Octokit> {
     client ??= new Octokit({
-      auth: await (options.token ?? ghAuthToken)(),
+      auth: await getToken(),
       ...(options.fetch && { request: { fetch: options.fetch } }),
     });
     return client;
   }
 
+  async function rawFetchOnce(url: string, init: RequestInit = {}): Promise<Response> {
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${await getToken()}`);
+    headers.set("accept", "application/vnd.github+json");
+    headers.set("x-github-api-version", "2022-11-28");
+    const response = await fetchImpl(url, { ...init, headers });
+    if (response.status === 401) {
+      // 缓存的 token 可能已过期：丢缓存后由调用方重试一次
+      token = undefined;
+      client = undefined;
+    }
+    return response;
+  }
+
   return {
     async call(fn) {
       for (let attempt = 0; ; attempt += 1) {
@@ -287,6 +368,7 @@ function createGithubApi(options: GithubClientOptions = {}): GithubApi {
         } catch (error) {
           const status = (error as { status?: number }).status;
           if (status === 401 && attempt === 0 && client) {
+            token = undefined;
             client = undefined;
             continue;
           }
@@ -294,6 +376,16 @@ function createGithubApi(options: GithubClientOptions = {}): GithubApi {
         }
       }
     },
+
+    async rawFetch(url, init) {
+      for (let attempt = 0; ; attempt += 1) {
+        const response = await rawFetchOnce(url, init);
+        if (response.status !== 401 || attempt > 0) {
+          return response;
+        }
+        await response.body?.cancel();
+      }
+    },
   };
 }
 

package/src/lib/lsp/inspect-schemas.ts

@@ -0,0 +1,44 @@
+/**
+ * 三个只读 LSP 查询工具（`lsp-find-definition` / `lsp-find-reference` / `lsp-inspect`）的
+ * 结构化结果 schema。
+ *
+ * 载荷只有我们自己归一化过的数据（`service.inspect` 的产出），没有外部引擎字段，因此这里
+ * 不学 AFT 那样全线可选：字段都在，类型确定。位置的行列号是 **1-based**（与工具文本、
+ * 与这三个工具自己的 `line` / `character` 参数一致），脚本拿到就能直接回喂给另一次查询。
+ *
+ * `locations` 给的是查询到的**全部**位置：文本会为了模型上下文对引用列表做截断
+ * （每文件 10 条、最多 30 个文件），载荷不跟着截——它是给程序用的数据，截断是渲染的事。
+ */
+
+import { Type } from "typebox";
+
+/** 一个位置：绝对路径 + 1-based 行列号（与工具文本里的 `path:line:col` 同源）。 */
+export const lspLocationSchema = Type.Object(
+  {
+    path: Type.String({ description: "文件的绝对路径" }),
+    line: Type.Integer({ minimum: 1, description: "1-based 行号" }),
+    character: Type.Integer({ minimum: 1, description: "1-based 列号" }),
+  },
+  { additionalProperties: false },
+);
+
+/** 回答这次查询的语言服务器 id，以及查询到的全部位置。 */
+export const lspLocationsStructuredSchema = Type.Object(
+  {
+    text: Type.String({ description: "与工具输出一致的渲染文本（引用列表可能被截断）" }),
+    serverID: Type.String({ description: "回答这次查询的语言服务器 id" }),
+    locations: Type.Array(lspLocationSchema, {
+      description: "查询到的全部位置，1-based 行列号，顺序与文本一致",
+    }),
+  },
+  { additionalProperties: false },
+);
+
+/** hover 的内容是服务器给的异构结构，渲染成文本后原样给出。 */
+export const lspHoverStructuredSchema = Type.Object(
+  {
+    text: Type.String({ description: "与工具输出一致的 hover 文本（服务器返回的内容）" }),
+    serverID: Type.String({ description: "回答这次查询的语言服务器 id" }),
+  },
+  { additionalProperties: false },
+);