@trim21/personal-pi-extensions 0.1.684 → 0.1.685

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

@@ -1,29 +1,65 @@
 import { Type } from "typebox";
 
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, ghExec, subtitlePendant, toToolResult } from "../base.js";
+import { parseWithSchema } from "../../lib/parse-with-schema.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import {
+  type GhClient,
+  ghExec,
+  subtitlePendant,
+  toToolResult,
+  withStructuredResult,
+} from "../base.js";
+import { renderRepoView } from "../render.js";
+import { ghRepoPayloadSchema, ghRepoViewSchema } from "../schemas.js";
+
+/** 我们向 gh 要的仓库字段，与渲染和载荷一一对应。 */
+const REPO_FIELDS = [
+  "name",
+  "nameWithOwner",
+  "description",
+  "url",
+  "homepageUrl",
+  "visibility",
+  "isPrivate",
+  "isFork",
+  "isArchived",
+  "stargazerCount",
+  "forkCount",
+  "primaryLanguage",
+  "defaultBranchRef",
+  "licenseInfo",
+  "issues",
+  "pullRequests",
+  "pushedAt",
+  "createdAt",
+  "updatedAt",
+].join(",");
 
 export function addReadRepoTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "read-github-repo",
-    label: "GitHub Repo",
-    description: "Get repository information.",
-    promptSnippet: "Read GitHub repo info",
-    parameters: Type.Object({
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+  bus.register(
+    defineStructuredTool({
+      name: "read-github-repo",
+      label: "GitHub Repo",
+      description: "Get repository information.",
+      promptSnippet: "Read GitHub repo info",
+      parameters: Type.Object({
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      structuredSchema: ghRepoPayloadSchema,
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        const { repo } = params;
+        const args = ["repo", "view"];
+        if (repo) {
+          args.push(repo);
+        }
+        args.push("--json", REPO_FIELDS);
+        const stdout = await ghExec(args, { cwd: ctx.cwd, signal, input: params });
+        const view = parseWithSchema(ghRepoViewSchema, JSON.parse(stdout));
+        const text = renderRepoView(view);
+        const result = toToolResult(text, params);
+        result.details.pendant = subtitlePendant(params);
+        return withStructuredResult(result, { text, repo: view });
+      },
     }),
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      const { repo } = params;
-      const args = ["repo", "view"];
-      if (repo) {
-        args.push(repo);
-      }
-      const result = toToolResult(
-        await ghExec(args, { cwd: ctx.cwd, signal, input: params }),
-        params,
-      );
-      result.details.pendant = subtitlePendant(params);
-      return result;
-    },
-  });
+  );
 }

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

@@ -1,46 +1,62 @@
 import { Type } from "typebox";
 
 import { runGh } from "../../lib/gh-process.js";
-import type { ToolBus } from "../../lib/tool-bus.js";
-import { type GhClient, repoArgs, subtitlePendant } from "../base.js";
+import { parseWithSchema } from "../../lib/parse-with-schema.js";
+import { defineStructuredTool, type ToolBus } from "../../lib/tool-bus.js";
+import { type GhClient, ghExec, repoArgs, subtitlePendant } from "../base.js";
+import { ghRunPayloadSchema, ghRunSummarySchema } from "../schemas.js";
+
+/** 收尾时查运行状态要的字段（`gh run watch` 自己没有 `--json`）。 */
+const RUN_FIELDS =
+  "databaseId,displayTitle,status,conclusion,workflowName,headBranch,event,createdAt,updatedAt,startedAt,url";
 
 export function addWatchRunTool(_gh: GhClient, bus: ToolBus) {
-  bus.register({
-    name: "watch-github-run",
-    label: "Watch GitHub Workflow Run",
-    description:
-      "Watch a GitHub Actions workflow run until it completes. " +
-      "Blocks until the run finishes and shows the final status.",
-    promptSnippet: "Watch and wait for a GitHub Actions run to complete",
-    parameters: Type.Object({
-      run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),
-      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+  bus.register(
+    defineStructuredTool({
+      name: "watch-github-run",
+      label: "Watch GitHub Workflow Run",
+      description:
+        "Watch a GitHub Actions workflow run until it completes. " +
+        "Blocks until the run finishes and shows the final status.",
+      promptSnippet: "Watch and wait for a GitHub Actions run to complete",
+      parameters: Type.Object({
+        run_id: Type.Union([Type.Number(), Type.String()], { description: "Workflow run ID" }),
+        repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      }),
+      structuredSchema: ghRunPayloadSchema,
+      async execute(_id, params, signal, onUpdate, ctx) {
+        const { run_id, repo } = params;
+
+        const pendant = subtitlePendant(params, "run_id");
+        onUpdate?.({
+          content: [{ type: "text", text: `Watching workflow run ${run_id}...` }],
+          details: {},
+        });
+
+        const result = await runGh(["run", "watch", String(run_id), ...repoArgs(repo)], {
+          cwd: ctx.cwd,
+          signal,
+          timeout: 600_000,
+        });
+
+        if (result.code !== 0) {
+          throw new Error(`gh run watch failed: ${result.stderr || `exit code ${result.code}`}`);
+        }
+
+        const text = `## Workflow Run ${run_id} Completed\n\n${result.stdout}`;
+        // 监控的是状态变化，结论要另外查一次（watch 的文本里只有过程）
+        const stdout = await ghExec(
+          ["run", "view", String(run_id), ...repoArgs(repo), "--json", RUN_FIELDS],
+          { cwd: ctx.cwd, signal, input: params },
+        );
+        const run = parseWithSchema(ghRunSummarySchema, JSON.parse(stdout));
+
+        return {
+          content: [{ type: "text" as const, text }],
+          details: { exitCode: 0, input: params, ...(pendant && { pendant }) },
+          structuredResult: { ok: true as const, value: { text, run } },
+        };
+      },
     }),
-    async execute(_id, params, signal, onUpdate, ctx) {
-      const { run_id, repo } = params;
-
-      const pendant = subtitlePendant(params, "run_id");
-      onUpdate?.({
-        content: [{ type: "text", text: `Watching workflow run ${run_id}...` }],
-        details: {},
-      });
-
-      const result = await runGh(["run", "watch", String(run_id), ...repoArgs(repo)], {
-        cwd: ctx.cwd,
-        signal,
-        timeout: 600_000,
-      });
-
-      if (result.code !== 0) {
-        throw new Error(`gh run watch failed: ${result.stderr || `exit code ${result.code}`}`);
-      }
-
-      return {
-        content: [
-          { type: "text", text: `## Workflow Run ${run_id} Completed\n\n${result.stdout}` },
-        ],
-        details: { exitCode: 0, input: params, ...(pendant && { pendant }) },
-      };
-    },
-  });
+  );
 }

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,76 @@ function normalize(raw: SearchItem): SearchHit {
   };
 }
 
+/**
+ * `gh issue list --json …` / `gh pr list --json …` 的响应形状。gh 走 GraphQL，字段是
+ * camelCase，`state` 是大写的 `OPEN` / `CLOSED` / `MERGED`，`comments` 是整个评论数组
+ * （不是计数）——所以浏览分支要在归一化这一步把它压成计数，才能和搜索分支（REST，
+ * 下划线命名、state 小写、comments 是数字）共用同一套 SearchHit、渲染与载荷。
+ */
+const ghListRecordSchema = Type.Object({
+  number: Type.Number(),
+  title: Type.String(),
+  state: Type.String(),
+  url: Type.String(),
+  labels: Type.Array(Type.Object({ name: Type.String() }, { additionalProperties: true })),
+  milestone: Type.Union([
+    Type.Object({ title: Type.String() }, { additionalProperties: true }),
+    Type.Null(),
+  ]),
+  assignees: Type.Array(Type.Object({ login: Type.String() }, { additionalProperties: true })),
+  author: Type.Union([
+    Type.Object({ login: Type.String() }, { additionalProperties: true }),
+    Type.Null(),
+  ]),
+  comments: Type.Array(Type.Unknown()),
+  createdAt: Type.String(),
+  updatedAt: Type.String(),
+  closedAt: Type.Union([Type.String(), Type.Null()]),
+  mergedAt: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+});
+
+/** 浏览分支要 gh 给的字段，与 `SearchHit` 的列一一对应（`comments` 只用来数个数）。 */
+export const GH_LIST_FIELDS = [
+  "number",
+  "title",
+  "state",
+  "url",
+  "labels",
+  "milestone",
+  "assignees",
+  "author",
+  "comments",
+  "createdAt",
+  "updatedAt",
+  "closedAt",
+  "mergedAt",
+].join(",");
+
+/** 把 `gh issue list --json` / `gh pr list --json` 的输出归一到 `SearchHit`（repo 由调用方给）。 */
+export function normalizeGhList(stdout: string, repo: string): SearchHit[] {
+  const items = parseWithSchema(Type.Array(ghListRecordSchema), JSON.parse(stdout));
+  return items.map((item) => {
+    const mergedAt = item.mergedAt ?? null;
+    return {
+      number: item.number,
+      // gh 给 MERGED 状态的 PR 与 OPEN/CLOSED 一样是 state 字段，merged 语义与搜索分支对齐
+      state: mergedAt ? "merged" : (item.state.toLowerCase() as SearchHit["state"]),
+      title: item.title,
+      url: item.url,
+      repo,
+      author: item.author?.login ?? "",
+      labels: item.labels.map((label) => label.name),
+      milestone: item.milestone?.title ?? "",
+      assignees: item.assignees.map((assignee) => assignee.login),
+      comments: item.comments.length,
+      createdAt: toDate(item.createdAt),
+      updatedAt: toDate(item.updatedAt),
+      closedAt: toDate(item.closedAt),
+      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.

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 },
+);