@trim21/personal-pi-extensions 0.1.683 → 0.1.685

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

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

@@ -18,8 +18,9 @@ import { Type } from "typebox";
 import type { Hover } from "vscode-languageserver-types";
 
 import { resolvePathArg } from "../path.js";
-import type { ToolBus } from "../tool-bus.js";
+import { defineStructuredTool, type ToolBus } from "../tool-bus.js";
 import type { InspectLocation } from "./client.js";
+import { lspHoverStructuredSchema, lspLocationsStructuredSchema } from "./inspect-schemas.js";
 import type { LspService } from "./lsp.js";
 import { type LspPosition, symbolCandidates } from "./rename.js";
 
@@ -29,12 +30,31 @@ const MAX_ENTRIES_PER_FILE = 10;
 const MAX_FILES_LISTED = 30;
 const MAX_SNIPPET_LENGTH = 200;
 
-/** 一次探测的产出：text 是消歧分组键，subtitle 供 pendant 摘要。 */
-interface InspectOutput {
+/** 渲染产出：text 也是消歧分组键。 */
+interface RenderedOutput {
   text: string;
   subtitle: string;
 }
 
+/**
+ * 一次探测的产出：渲染文本 + 结构化结果里除 `text` 之外的字段（选中哪一组，就取那一组的
+ * payload）。泛型让每个工具自己决定载荷。
+ */
+interface InspectOutput<TPayload> extends RenderedOutput {
+  payload: TPayload;
+}
+
+/** 位置载荷：服务层归一化后的绝对路径 + 1-based 行列号。 */
+function toLocationPayload(
+  locations: readonly InspectLocation[],
+): { path: string; line: number; character: number }[] {
+  return locations.map((location) => ({
+    path: location.path,
+    line: location.line + 1,
+    character: location.character + 1,
+  }));
+}
+
 function loadPrompt(fileName: string): string {
   return readFileSync(fileURLToPath(new URL(fileName, import.meta.url)), "utf8").trim();
 }
@@ -113,7 +133,7 @@ function toCoordinates(location: InspectLocation): string {
 async function formatDefinitionLocations(
   locations: InspectLocation[],
   cache: Map<string, string[]>,
-): Promise<InspectOutput> {
+): Promise<RenderedOutput> {
   if (locations.length === 0) {
     return { text: "No definition found for this symbol.", subtitle: "0 definition(s)" };
   }
@@ -131,7 +151,7 @@ async function formatDefinitionLocations(
 async function formatReferenceLocations(
   locations: InspectLocation[],
   cache: Map<string, string[]>,
-): Promise<InspectOutput> {
+): Promise<RenderedOutput> {
   if (locations.length === 0) {
     return { text: "No references found for this symbol.", subtitle: "0 reference(s)" };
   }
@@ -198,15 +218,15 @@ function formatHoverContents(contents: Hover["contents"]): string {
  * 行内同名候选逐个探测：输出一致即同一符号的多次出现；不一致报歧义并列出
  * 各候选的 1-based 列号（与 lsp-rename 的消歧行为一致）。
  */
-async function probeSymbolCandidates(options: {
+async function probeSymbolCandidates<TPayload>(options: {
   content: string;
   filePath: string;
   line: number;
   symbol: string;
   character?: number;
   signal?: AbortSignal;
-  probe: (position: LspPosition) => Promise<InspectOutput>;
-}): Promise<InspectOutput> {
+  probe: (position: LspPosition) => Promise<InspectOutput<TPayload>>;
+}): Promise<InspectOutput<TPayload>> {
   const candidates = symbolCandidates(
     options.content,
     options.line - 1,
@@ -218,12 +238,12 @@ async function probeSymbolCandidates(options: {
       `Symbol "${options.symbol}" not found on line ${options.line} of ${options.filePath}. Read the file again and locate the symbol.`,
     );
   }
-  const outputs: InspectOutput[] = [];
+  const outputs: InspectOutput<TPayload>[] = [];
   for (const candidate of candidates) {
     options.signal?.throwIfAborted();
     outputs.push(await options.probe(candidate));
   }
-  const groups = new Map<string, { output: InspectOutput; candidates: LspPosition[] }>();
+  const groups = new Map<string, { output: InspectOutput<TPayload>; candidates: LspPosition[] }>();
   for (const [index, candidate] of candidates.entries()) {
     const output = outputs.at(index);
     if (!output) {
@@ -256,137 +276,168 @@ async function probeSymbolCandidates(options: {
 }
 
 export function registerLspInspectTools(bus: ToolBus, service: LspService): void {
-  bus.register({
-    name: "lsp-find-definition",
-    label: "Lsp Find Definition",
-    description:
-      "Find where a code symbol is defined via LSP. Returns 1-based path:line:col locations with source line snippets.",
-    promptSnippet: "Find symbol definitions via LSP",
-    promptGuidelines: [FIND_DEFINITION_PROMPT],
-    parameters: POSITION_SCHEMA,
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      signal?.throwIfAborted();
-      const { path: filePath, content } = await readSymbolFile(ctx.cwd, params.file_path);
-      const cache = new Map<string, string[]>();
-      const output = await probeSymbolCandidates({
-        content,
-        filePath,
-        line: params.line,
-        symbol: params.symbol,
-        character: params.character,
-        signal,
-        probe: async (position) => {
-          const result = await service.inspect({
-            file: filePath,
-            cwd: ctx.cwd,
-            line: position.line,
-            character: position.character,
-            query: "definition",
-            options: { signal },
-          });
-          return formatDefinitionLocations(result.locations, cache);
-        },
-      });
-      return {
-        content: [{ type: "text" as const, text: output.text }],
-        details: {
-          pendant: {
-            title: "lsp-find-definition",
-            subtitle: `${params.symbol} · ${output.subtitle}`,
+  bus.register(
+    defineStructuredTool({
+      name: "lsp-find-definition",
+      label: "Lsp Find Definition",
+      description:
+        "Find where a code symbol is defined via LSP. Returns 1-based path:line:col locations with source line snippets.",
+      promptSnippet: "Find symbol definitions via LSP",
+      promptGuidelines: [FIND_DEFINITION_PROMPT],
+      parameters: POSITION_SCHEMA,
+      structuredSchema: lspLocationsStructuredSchema,
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        signal?.throwIfAborted();
+        const { path: filePath, content } = await readSymbolFile(ctx.cwd, params.file_path);
+        const cache = new Map<string, string[]>();
+        const output = await probeSymbolCandidates({
+          content,
+          filePath,
+          line: params.line,
+          symbol: params.symbol,
+          character: params.character,
+          signal,
+          probe: async (position) => {
+            const result = await service.inspect({
+              file: filePath,
+              cwd: ctx.cwd,
+              line: position.line,
+              character: position.character,
+              query: "definition",
+              options: { signal },
+            });
+            const rendered = await formatDefinitionLocations(result.locations, cache);
+            return {
+              ...rendered,
+              payload: {
+                serverID: result.serverID,
+                locations: toLocationPayload(result.locations),
+              },
+            };
           },
-        },
-      };
-    },
-  });
+        });
+        return {
+          content: [{ type: "text" as const, text: output.text }],
+          details: {
+            pendant: {
+              title: "lsp-find-definition",
+              subtitle: `${params.symbol} · ${output.subtitle}`,
+            },
+          },
+          structuredResult: { ok: true as const, value: { text: output.text, ...output.payload } },
+        };
+      },
+    }),
+  );
 
-  bus.register({
-    name: "lsp-find-reference",
-    label: "Lsp Find Reference",
-    description:
-      "Find all references to a code symbol across the workspace via LSP (includes the declaration). Grouped by file with 1-based line:col and source snippets.",
-    promptSnippet: "Find symbol references via LSP",
-    promptGuidelines: [FIND_REFERENCE_PROMPT],
-    parameters: POSITION_SCHEMA,
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      signal?.throwIfAborted();
-      const { path: filePath, content } = await readSymbolFile(ctx.cwd, params.file_path);
-      const cache = new Map<string, string[]>();
-      const output = await probeSymbolCandidates({
-        content,
-        filePath,
-        line: params.line,
-        symbol: params.symbol,
-        character: params.character,
-        signal,
-        probe: async (position) => {
-          const result = await service.inspect({
-            file: filePath,
-            cwd: ctx.cwd,
-            line: position.line,
-            character: position.character,
-            query: "references",
-            options: { signal },
-          });
-          return formatReferenceLocations(result.locations, cache);
-        },
-      });
-      return {
-        content: [{ type: "text" as const, text: output.text }],
-        details: {
-          pendant: {
-            title: "lsp-find-reference",
-            subtitle: `${params.symbol} · ${output.subtitle}`,
+  bus.register(
+    defineStructuredTool({
+      name: "lsp-find-reference",
+      label: "Lsp Find Reference",
+      description:
+        "Find all references to a code symbol across the workspace via LSP (includes the declaration). Grouped by file with 1-based line:col and source snippets.",
+      promptSnippet: "Find symbol references via LSP",
+      promptGuidelines: [FIND_REFERENCE_PROMPT],
+      parameters: POSITION_SCHEMA,
+      structuredSchema: lspLocationsStructuredSchema,
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        signal?.throwIfAborted();
+        const { path: filePath, content } = await readSymbolFile(ctx.cwd, params.file_path);
+        const cache = new Map<string, string[]>();
+        const output = await probeSymbolCandidates({
+          content,
+          filePath,
+          line: params.line,
+          symbol: params.symbol,
+          character: params.character,
+          signal,
+          probe: async (position) => {
+            const result = await service.inspect({
+              file: filePath,
+              cwd: ctx.cwd,
+              line: position.line,
+              character: position.character,
+              query: "references",
+              options: { signal },
+            });
+            const rendered = await formatReferenceLocations(result.locations, cache);
+            return {
+              ...rendered,
+              // 文本为上下文做了截断（每文件 10 条、最多 30 个文件），载荷给全部位置
+              payload: {
+                serverID: result.serverID,
+                locations: toLocationPayload(result.locations),
+              },
+            };
           },
-        },
-      };
-    },
-  });
+        });
+        return {
+          content: [{ type: "text" as const, text: output.text }],
+          details: {
+            pendant: {
+              title: "lsp-find-reference",
+              subtitle: `${params.symbol} · ${output.subtitle}`,
+            },
+          },
+          structuredResult: { ok: true as const, value: { text: output.text, ...output.payload } },
+        };
+      },
+    }),
+  );
 
-  bus.register({
-    name: "lsp-inspect",
-    label: "Lsp Inspect",
-    description:
-      "Get hover information (type signature, documentation) for a code symbol via LSP. Content is passed through from the language server.",
-    promptSnippet: "Get hover info for a symbol via LSP",
-    promptGuidelines: [INSPECT_PROMPT],
-    parameters: POSITION_SCHEMA,
-    async execute(_id, params, signal, _onUpdate, ctx) {
-      signal?.throwIfAborted();
-      const { path: filePath, content } = await readSymbolFile(ctx.cwd, params.file_path);
-      const output = await probeSymbolCandidates({
-        content,
-        filePath,
-        line: params.line,
-        symbol: params.symbol,
-        character: params.character,
-        signal,
-        probe: async (position) => {
-          const result = await service.inspect({
-            file: filePath,
-            cwd: ctx.cwd,
-            line: position.line,
-            character: position.character,
-            query: "hover",
-            options: { signal },
-          });
-          if (result.hover === null) {
+  bus.register(
+    defineStructuredTool({
+      name: "lsp-inspect",
+      label: "Lsp Inspect",
+      description:
+        "Get hover information (type signature, documentation) for a code symbol via LSP. Content is passed through from the language server.",
+      promptSnippet: "Get hover info for a symbol via LSP",
+      promptGuidelines: [INSPECT_PROMPT],
+      parameters: POSITION_SCHEMA,
+      structuredSchema: lspHoverStructuredSchema,
+      async execute(_id, params, signal, _onUpdate, ctx) {
+        signal?.throwIfAborted();
+        const { path: filePath, content } = await readSymbolFile(ctx.cwd, params.file_path);
+        const output = await probeSymbolCandidates({
+          content,
+          filePath,
+          line: params.line,
+          symbol: params.symbol,
+          character: params.character,
+          signal,
+          probe: async (position) => {
+            const result = await service.inspect({
+              file: filePath,
+              cwd: ctx.cwd,
+              line: position.line,
+              character: position.character,
+              query: "hover",
+              options: { signal },
+            });
+            // hover 的内容是服务器给的异构结构（string / MarkedString / MarkupContent），
+            // 渲染成文本给它；载荷里只另带是谁回答的
+            if (result.hover === null) {
+              return {
+                text: `No hover information for '${params.symbol}' at line ${params.line} of ${filePath}.`,
+                subtitle: "no hover info",
+                payload: { serverID: result.serverID },
+              };
+            }
             return {
-              text: `No hover information for '${params.symbol}' at line ${params.line} of ${filePath}.`,
-              subtitle: "no hover info",
+              text: formatHoverContents(result.hover.contents),
+              subtitle: "hover",
+              payload: { serverID: result.serverID },
             };
-          }
-          return {
-            text: formatHoverContents(result.hover.contents),
-            subtitle: "hover",
-          };
-        },
-      });
-      return {
-        content: [{ type: "text" as const, text: output.text }],
-        details: {
-          pendant: { title: "lsp-inspect", subtitle: `${params.symbol} · ${output.subtitle}` },
-        },
-      };
-    },
-  });
+          },
+        });
+        return {
+          content: [{ type: "text" as const, text: output.text }],
+          details: {
+            pendant: { title: "lsp-inspect", subtitle: `${params.symbol} · ${output.subtitle}` },
+          },
+          structuredResult: { ok: true as const, value: { text: output.text, ...output.payload } },
+        };
+      },
+    }),
+  );
 }