@trim21/personal-pi-extensions 0.1.489 → 0.1.490

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.489",
+  "version": "0.1.490",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/claude-code/files.ts

@@ -15,6 +15,7 @@ import {
 import { Type } from "typebox";
 
 import { appendLspDiagnosticText } from "../lib/lsp/diagnostic.js";
+import { registerLspInspectTools } from "../lib/lsp/inspect-tool.js";
 import { type LspService, registerLsp } from "../lib/lsp/lsp.js";
 import { registerLspRenameTool } from "../lib/lsp/rename-tool.js";
 import { formatSubtitlePath } from "../lib/path.js";
@@ -689,6 +690,8 @@ export function registerFileTools(
       return reads;
     },
   });
+  // 只读符号查询工具（find-definition / find-reference / inspect）与 opencode 共享。
+  registerLspInspectTools(pi, service);
 }
 
 /** 会更新 reads state 并随 details 持久化快照的工具名。 */

package/src/lib/lsp/client.ts

@@ -20,7 +20,13 @@ import {
   StreamMessageReader,
   StreamMessageWriter,
 } from "vscode-jsonrpc/node";
-import type { Diagnostic as VSCodeDiagnostic, WorkspaceEdit } from "vscode-languageserver-types";
+import type {
+  Diagnostic as VSCodeDiagnostic,
+  Hover,
+  Location as LspLocation,
+  LocationLink,
+  WorkspaceEdit,
+} from "vscode-languageserver-types";
 
 import type { LspServerHandle } from "./adapter.js";
 import { LANGUAGE_EXTENSIONS } from "./language.js";
@@ -72,6 +78,20 @@ const LSP_CONTENT_MODIFIED = -32801;
  */
 export class RenameNotPossibleError extends Error {}
 
+/**
+ * 服务器不支持某 LSP 方法（MethodNotFound）。与传输失败区分，供服务层跳过
+ * 该服务器尝试下一个，而不是把整个操作当作失败。
+ */
+export class LspMethodNotSupportedError extends Error {
+  readonly serverID: string;
+  readonly method: string;
+  constructor(serverID: string, method: string) {
+    super(`LSP server "${serverID}" does not support ${method}`);
+    this.serverID = serverID;
+    this.method = method;
+  }
+}
+
 /**
  * rename edit 未覆盖 references 看到的全部文件：服务器索引可能仍在后台加载。
  * 抛出时发生在写盘之前，整个 rename 无副作用，可稍后重试。
@@ -148,6 +168,48 @@ export interface RenameSymbolResult {
   placeholder?: string;
 }
 
+/** definition / references / hover 请求的输入（line / character 为 0-based LSP position）。 */
+export interface InspectPositionRequest {
+  path: string;
+  line: number;
+  character: number;
+}
+
+/** definition / references 归一化后的位置（0-based；1-based 格式化由工具层负责）。 */
+export interface InspectLocation {
+  path: string;
+  line: number;
+  character: number;
+}
+
+type DefinitionResult = LspLocation | LspLocation[] | LocationLink | LocationLink[] | null;
+
+/** Location / LocationLink → path + 0-based 坐标；非 file: URI 是服务器的意外行为，跳过。 */
+function toInspectLocations(result: DefinitionResult): InspectLocation[] {
+  if (result === null) return [];
+  const items = Array.isArray(result) ? result : [result];
+  const locations: InspectLocation[] = [];
+  for (const item of items) {
+    if ("targetUri" in item) {
+      if (!item.targetUri.startsWith("file:")) continue;
+      const range = item.targetSelectionRange ?? item.targetRange;
+      locations.push({
+        path: normalize(fileURLToPath(item.targetUri)),
+        line: range.start.line,
+        character: range.start.character,
+      });
+    } else {
+      if (!item.uri.startsWith("file:")) continue;
+      locations.push({
+        path: normalize(fileURLToPath(item.uri)),
+        line: item.range.start.line,
+        character: item.range.start.character,
+      });
+    }
+  }
+  return locations;
+}
+
 export class InitializeError extends Error {
   readonly serverID: string;
   constructor(serverID: string, cause: unknown) {
@@ -241,6 +303,21 @@ export interface LspClient {
    * 位置不在符号上 / 服务器不支持 rename 时抛 RenameNotPossibleError。
    */
   renameSymbol(request: RenameSymbolRequest): Promise<RenameSymbolResult>;
+  /**
+   * textDocument/definition：归一化后的定义位置列表（Location / LocationLink
+   * 统一转 path + 0-based 坐标；无结果返回空数组）。
+   */
+  definition(request: InspectPositionRequest): Promise<InspectLocation[]>;
+  /**
+   * textDocument/references：归一化后的引用位置列表（是否含声明处由服务器
+   * 按 includeDeclaration 决定，此处固定包含，对齐 rename 覆盖校验口径）。
+   */
+  references(request: InspectPositionRequest): Promise<InspectLocation[]>;
+  /**
+   * textDocument/hover：服务器返回的 contents 原样透传，不做内容归一化；
+   * 服务器无信息时返回 null（合法应答，非错误）。
+   */
+  hover(request: InspectPositionRequest): Promise<Hover | null>;
   shutdown(): Promise<void>;
 }
 
@@ -922,6 +999,31 @@ export async function create(input: CreateInput): Promise<LspClient> {
     return 0;
   };
 
+  // ── 只读符号查询（definition / references / hover）──────────────────────────
+
+  /** 请求前先同步磁盘内容（didOpen/didChange），保证服务器基于最新文本应答。 */
+  const preparePositionRequest = async (request: InspectPositionRequest) => {
+    const resolvedPath = normalize(
+      isAbsolute(request.path) ? request.path : resolve(input.directory, request.path),
+    );
+    await openDocument({ path: resolvedPath });
+    return {
+      uri: pathToFileURL(resolvedPath).href,
+      position: { line: request.line, character: request.character },
+    };
+  };
+
+  const sendInspectRequest = async <T>(method: string, message: object): Promise<T> => {
+    try {
+      return await retryOnContentModified(() => connection.sendRequest<T>(method, message));
+    } catch (error) {
+      if (error instanceof ResponseError && error.code === LSP_METHOD_NOT_FOUND) {
+        throw new LspMethodNotSupportedError(input.serverID, method);
+      }
+      throw error;
+    }
+  };
+
   return {
     root: input.root,
     get serverID() {
@@ -1101,6 +1203,31 @@ export async function create(input: CreateInput): Promise<LspClient> {
         current = toPaths(await referencesRequest());
       }
     },
+    async definition(request: InspectPositionRequest): Promise<InspectLocation[]> {
+      const { uri, position } = await preparePositionRequest(request);
+      return toInspectLocations(
+        await sendInspectRequest<DefinitionResult>("textDocument/definition", {
+          textDocument: { uri },
+          position,
+        }),
+      );
+    },
+    async references(request: InspectPositionRequest): Promise<InspectLocation[]> {
+      const { uri, position } = await preparePositionRequest(request);
+      const locations = await sendInspectRequest<LspLocation[] | null>("textDocument/references", {
+        textDocument: { uri },
+        position,
+        context: { includeDeclaration: true },
+      });
+      return toInspectLocations(locations);
+    },
+    async hover(request: InspectPositionRequest): Promise<Hover | null> {
+      const { uri, position } = await preparePositionRequest(request);
+      return await sendInspectRequest<Hover | null>("textDocument/hover", {
+        textDocument: { uri },
+        position,
+      });
+    },
     get diagnostics() {
       const result = new Map<string, Diagnostic[]>();
       for (const key of new Set([...pushDiagnostics.keys(), ...pullDiagnostics.keys()])) {

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

@@ -0,0 +1,376 @@
+/**
+ * 只读 LSP 符号查询工具，由 claude-code / opencode 两个工具集共享注册：
+ *
+ * - lsp-find-definition：textDocument/definition → 定义位置列表
+ * - lsp-find-reference：textDocument/references（含声明处）→ 按文件分组
+ * - lsp-inspect：textDocument/hover → hover 内容原样透传
+ *
+ * 三个工具共用 lsp-rename 的定位与消歧语义（file_path + line + symbol，
+ * character 消歧）：按词边界枚举行内候选逐个探测，格式化输出一致即视为
+ * 同一符号的多次出现，不一致报歧义并列出候选列号。
+ */
+
+import { readFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Hover } from "vscode-languageserver-types";
+
+import { resolvePathArg } from "../path.js";
+import type { InspectLocation } from "./client.js";
+import type { LspService } from "./lsp.js";
+import { type LspPosition, symbolCandidates } from "./rename.js";
+
+/** references 输出上限：每文件最多列出的行片段数。 */
+const MAX_ENTRIES_PER_FILE = 10;
+/** references 输出上限：最多列出片段的文件数，超出部分按计数汇总。 */
+const MAX_FILES_LISTED = 30;
+const MAX_SNIPPET_LENGTH = 200;
+
+/** 一次探测的产出：text 是消歧分组键，subtitle 供 pendant 摘要。 */
+interface InspectOutput {
+  text: string;
+  subtitle: string;
+}
+
+function loadPrompt(fileName: string): string {
+  return readFileSync(fileURLToPath(new URL(fileName, import.meta.url)), "utf8").trim();
+}
+
+const FIND_DEFINITION_PROMPT = loadPrompt("lsp-find-definition.md");
+const FIND_REFERENCE_PROMPT = loadPrompt("lsp-find-reference.md");
+const INSPECT_PROMPT = loadPrompt("lsp-inspect.md");
+
+const POSITION_SCHEMA = Type.Object(
+  {
+    file_path: Type.String({
+      description:
+        "A file containing the symbol (absolute path, or relative / ~/ path resolved against the session cwd)",
+    }),
+    line: Type.Integer({
+      minimum: 1,
+      description:
+        "1-based line number where the symbol appears (any occurrence works, not only the definition)",
+    }),
+    symbol: Type.String({
+      minLength: 1,
+      description: "The symbol's name exactly as it appears on that line",
+    }),
+    character: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        description:
+          "1-based character offset of the symbol on that line. Only needed when the tool reports an ambiguity error on this line",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+async function readSymbolFile(
+  cwd: string,
+  filePathArg: string,
+): Promise<{ path: string; content: string }> {
+  const filePath = resolvePathArg(cwd, filePathArg);
+  try {
+    await stat(filePath);
+    const content = await readFile(filePath, "utf8");
+    return { path: filePath, content };
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      throw new Error(`File does not exist: ${filePath}`, { cause: error });
+    }
+    throw error;
+  }
+}
+
+/** 目标行内容片段（跨文件缓存；读取失败静默跳过片段，坐标仍然输出）。 */
+async function lineSnippet(
+  path: string,
+  line: number,
+  cache: Map<string, string[]>,
+): Promise<string> {
+  let lines = cache.get(path);
+  if (lines === undefined) {
+    try {
+      const content = await readFile(path, "utf8");
+      lines = content.split("\n");
+    } catch {
+      return "";
+    }
+    cache.set(path, lines);
+  }
+  const text = (lines[line] ?? "").replace(/\r$/, "");
+  return text.length > MAX_SNIPPET_LENGTH ? `${text.slice(0, MAX_SNIPPET_LENGTH)}…` : text;
+}
+
+function toCoordinates(location: InspectLocation): string {
+  return `${location.path}:${location.line + 1}:${location.character + 1}`;
+}
+
+async function formatDefinitionLocations(
+  locations: InspectLocation[],
+  cache: Map<string, string[]>,
+): Promise<InspectOutput> {
+  if (locations.length === 0) {
+    return { text: "No definition found for this symbol.", subtitle: "0 definition(s)" };
+  }
+  const lines = [`Found ${locations.length} definition(s):`];
+  for (const location of locations) {
+    const snippet = await lineSnippet(location.path, location.line, cache);
+    lines.push(`- ${toCoordinates(location)}${snippet === "" ? "" : `\n  ${snippet}`}`);
+  }
+  return {
+    text: lines.join("\n"),
+    subtitle: `${locations.length} definition(s)`,
+  };
+}
+
+async function formatReferenceLocations(
+  locations: InspectLocation[],
+  cache: Map<string, string[]>,
+): Promise<InspectOutput> {
+  if (locations.length === 0) {
+    return { text: "No references found for this symbol.", subtitle: "0 reference(s)" };
+  }
+  const byPath = new Map<string, InspectLocation[]>();
+  for (const location of locations) {
+    const existing = byPath.get(location.path);
+    if (existing) existing.push(location);
+    else byPath.set(location.path, [location]);
+  }
+  const paths = [...byPath.keys()];
+  const sections = [`Found ${locations.length} reference(s) in ${paths.length} file(s):`];
+  for (const path of paths.slice(0, MAX_FILES_LISTED)) {
+    const entries = byPath.get(path);
+    if (!entries) continue;
+    const shown = entries.slice(0, MAX_ENTRIES_PER_FILE);
+    sections.push(`### ${path} (${entries.length})`);
+    for (const entry of shown) {
+      const snippet = await lineSnippet(path, entry.line, cache);
+      sections.push(
+        `- ${entry.line + 1}:${entry.character + 1}${snippet === "" ? "" : `: ${snippet}`}`,
+      );
+    }
+    if (entries.length > shown.length) {
+      sections.push(`(+${entries.length - shown.length} more in this file)`);
+    }
+  }
+  const omitted = paths.slice(MAX_FILES_LISTED);
+  if (omitted.length > 0) {
+    const omittedCount = omitted.reduce((sum, path) => sum + (byPath.get(path)?.length ?? 0), 0);
+    sections.push(`(+${omittedCount} reference(s) in ${omitted.length} more file(s) not shown)`);
+  }
+  return {
+    text: sections.join("\n"),
+    subtitle: `${locations.length} reference(s) in ${paths.length} file(s)`,
+  };
+}
+
+type MarkedString = string | { language: string; value: string };
+
+function formatMarkedString(marked: MarkedString): string {
+  return typeof marked === "string" ? marked : `\`\`\`${marked.language}\n${marked.value}\n\`\`\``;
+}
+
+/** hover contents 原样透传：仅做结构格式化（MarkedString → code fence），不改写内容。 */
+function formatHoverContents(contents: Hover["contents"]): string {
+  if (typeof contents === "string") return contents;
+  if (Array.isArray(contents)) {
+    return contents.map((marked) => formatMarkedString(marked)).join("\n\n");
+  }
+  if ("language" in contents) return formatMarkedString(contents);
+  return contents.value;
+}
+
+/**
+ * 行内同名候选逐个探测：输出一致即同一符号的多次出现；不一致报歧义并列出
+ * 各候选的 1-based 列号（与 lsp-rename 的消歧行为一致）。
+ */
+async function probeSymbolCandidates(options: {
+  content: string;
+  filePath: string;
+  line: number;
+  symbol: string;
+  character?: number;
+  signal?: AbortSignal;
+  probe: (position: LspPosition) => Promise<InspectOutput>;
+}): Promise<InspectOutput> {
+  const candidates = symbolCandidates(
+    options.content,
+    options.line - 1,
+    options.symbol,
+    options.character === undefined ? undefined : options.character - 1,
+  );
+  if (candidates.length === 0) {
+    throw new Error(
+      `Symbol "${options.symbol}" not found on line ${options.line} of ${options.filePath}. Read the file again and locate the symbol.`,
+    );
+  }
+  const outputs: InspectOutput[] = [];
+  for (const candidate of candidates) {
+    options.signal?.throwIfAborted();
+    outputs.push(await options.probe(candidate));
+  }
+  const groups = new Map<string, { output: InspectOutput; candidates: LspPosition[] }>();
+  for (const [index, candidate] of candidates.entries()) {
+    const output = outputs[index];
+    if (!output) continue;
+    const group = groups.get(output.text);
+    if (group) group.candidates.push(candidate);
+    else groups.set(output.text, { output, candidates: [candidate] });
+  }
+  if (groups.size > 1) {
+    const listing = [...groups.values()]
+      .map((group) =>
+        group.candidates
+          .map((candidate) => `- line ${candidate.line + 1}, column ${candidate.character + 1}`)
+          .join("\n"),
+      )
+      .join("\n");
+    throw new Error(
+      `Ambiguous symbol on line ${options.line} of ${options.filePath}: several distinct symbols share the name "${options.symbol}". Retry with 'character' (1-based) to pick one:\n${listing}`,
+    );
+  }
+  const first = [...groups.values()][0];
+  if (!first) throw new Error("LSP inspect returned no result");
+  return first.output;
+}
+
+export function registerLspInspectTools(pi: ExtensionAPI, service: LspService): void {
+  pi.registerTool({
+    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}`,
+          },
+        },
+      };
+    },
+  });
+
+  pi.registerTool({
+    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}`,
+          },
+        },
+      };
+    },
+  });
+
+  pi.registerTool({
+    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) {
+            return {
+              text: `No hover information for '${params.symbol}' at line ${params.line} of ${filePath}.`,
+              subtitle: "no hover info",
+            };
+          }
+          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}` },
+        },
+      };
+    },
+  });
+}

package/src/lib/lsp/lsp-find-definition.md

@@ -0,0 +1,8 @@
+## LSP Find Definition
+
+Find where a code symbol is defined and update nothing — read-only lookup via LSP.
+
+- Locate the symbol with `file_path` + `line` (1-based) + `symbol` (the symbol's name exactly as it appears on that line). Any occurrence works — it does not have to be the definition.
+- The tool computes the column itself; do not pass `character` unless asked to disambiguate.
+- When several distinct symbols share the same name on that line, the tool refuses to guess: it reports an ambiguity error listing the candidate columns. Re-run with `character` (1-based) to pick one.
+- Returns every definition site as `path:line:col` (1-based) with a source line snippet — imports, re-exports and overloads are resolved by the language server, unlike text search.

package/src/lib/lsp/lsp-find-reference.md

@@ -0,0 +1,8 @@
+## LSP Find Reference
+
+Find every reference to a code symbol across the workspace — read-only lookup via LSP.
+
+- Locate the symbol with `file_path` + `line` (1-based) + `symbol` (the symbol's name exactly as it appears on that line). Any occurrence works — it does not have to be the definition.
+- The tool computes the column itself; do not pass `character` unless asked to disambiguate.
+- When several distinct symbols share the same name on that line, the tool refuses to guess: it reports an ambiguity error listing the candidate columns. Re-run with `character` (1-based) to pick one.
+- Results are grouped by file with 1-based `line:col` and source snippets; the declaration site is included. Run it before `lsp-rename` to preview the blast radius.

package/src/lib/lsp/lsp-inspect.md

@@ -0,0 +1,8 @@
+## LSP Inspect
+
+Read a code symbol's hover information (type signature, documentation) without opening the file — read-only via LSP.
+
+- Locate the symbol with `file_path` + `line` (1-based) + `symbol` (the symbol's name exactly as it appears on that line). Any occurrence works — it does not have to be the definition.
+- The tool computes the column itself; do not pass `character` unless asked to disambiguate.
+- When several distinct symbols share the same name on that line, the tool refuses to guess: it reports an ambiguity error listing the candidate columns. Re-run with `character` (1-based) to pick one.
+- The hover content is passed through from the language server as-is.

package/src/lib/lsp/lsp.ts

@@ -25,7 +25,7 @@ import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding
 import { minimatch } from "minimatch";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
-import type { WorkspaceEdit } from "vscode-languageserver-types";
+import type { Hover, WorkspaceEdit } from "vscode-languageserver-types";
 
 import { type LspServerAdapter } from "./adapter.js";
 import {
@@ -33,6 +33,8 @@ import {
   type CreateInput,
   type Diagnostic,
   type Info as LspClient,
+  type InspectLocation,
+  LspMethodNotSupportedError,
   RenameNotPossibleError,
   WATCH_KIND_CHANGE,
   WATCH_KIND_CREATE,
@@ -242,6 +244,16 @@ interface LspState {
 /** 渲染 LSP status 文本的回调（传入 undefined 表示清除）。 */
 export type StatusRenderer = (text: string | undefined) => void;
 
+export type LspInspectQuery = "definition" | "references" | "hover";
+
+/**
+ * 返回类型与 query 泛型关联：query 为 "hover" 时返回 hover 内容，否则返回
+ * 位置列表。实现内部用 cast 建立关联（TS 无法验证分支与泛型的对应关系）。
+ */
+export type LspInspectResult<Q extends LspInspectQuery = LspInspectQuery> = Q extends "hover"
+  ? { serverID: string; query: "hover"; hover: Hover | null }
+  : { serverID: string; query: "definition" | "references"; locations: InspectLocation[] };
+
 export interface LspRequestOptions {
   notify?: ExtensionUIContext["notify"];
   /** 中止时提前结束诊断等待（已中止时直接跳过诊断）。 */
@@ -288,6 +300,19 @@ export interface LspService {
     newName: string;
     options?: LspRequestOptions;
   }): Promise<{ serverID: string; edit: WorkspaceEdit; placeholder?: string }>;
+  /**
+   * 只读符号查询（definition / references / hover）：只面向 kind 为 "language"
+   * 的服务器，按配置顺序取第一个成功结果；服务器不支持该方法（MethodNotFound）
+   * 时跳过并尝试下一个，全部不支持时抛聚合错误。line / character 为 0-based。
+   */
+  inspect<Q extends LspInspectQuery>(request: {
+    file: string;
+    cwd: string;
+    line: number;
+    character: number;
+    query: Q;
+    options?: LspRequestOptions;
+  }): Promise<LspInspectResult<Q>>;
   shutdownAll(): Promise<void>;
   /** 停止全部服务器并禁用 LSP：之后工具调用不再 spawn，直到 start/reload。 */
   stop(): Promise<void>;
@@ -690,6 +715,56 @@ export function createLspService(
       : new Error(`LSP rename failed on all servers — ${detail}`);
   }
 
+  /** 只读符号查询：与 rename 同款多服务器策略，但 MethodNotFound 是"跳过"而非失败。 */
+  async function inspect<Q extends LspInspectQuery>(request: {
+    file: string;
+    cwd: string;
+    line: number;
+    character: number;
+    query: Q;
+    options?: LspRequestOptions;
+  }): Promise<LspInspectResult<Q>> {
+    const clients = await getClients(
+      request.file,
+      request.cwd,
+      request.options?.notify,
+      (adapter) => adapter.kind !== "linter",
+    );
+    if (clients.length === 0) {
+      throw new Error(
+        `no LSP language server available for ${request.file} (check lsp.json servers and kind)`,
+      );
+    }
+    const failures: { serverID: string; error: unknown }[] = [];
+    for (const client of clients) {
+      const position = { path: request.file, line: request.line, character: request.character };
+      try {
+        if (request.query === "hover") {
+          const hover = await client.hover(position);
+          return { serverID: client.serverID, query: "hover", hover } as LspInspectResult<Q>;
+        }
+        const locations =
+          request.query === "definition"
+            ? await client.definition(position)
+            : await client.references(position);
+        return {
+          serverID: client.serverID,
+          query: request.query,
+          locations,
+        } as LspInspectResult<Q>;
+      } catch (error) {
+        failures.push({ serverID: client.serverID, error });
+      }
+    }
+    const allNotSupported = failures.every((f) => f.error instanceof LspMethodNotSupportedError);
+    const detail = failures
+      .map((f) => `${f.serverID}: ${f.error instanceof Error ? f.error.message : String(f.error)}`)
+      .join("; ");
+    throw allNotSupported
+      ? new LspMethodNotSupportedError("all configured servers", `textDocument/${request.query}`)
+      : new Error(`LSP inspect failed on all servers — ${detail}`);
+  }
+
   /** 关闭全部 client 并清空缓存；closing 置 true 让 in-flight spawn 自行退出。 */
   async function closeAll(): Promise<void> {
     state.closing = true;
@@ -752,6 +827,7 @@ export function createLspService(
     diagnostics,
     lspDiagnosticsForFile,
     rename,
+    inspect,
     shutdownAll,
     stop,
     start,

package/src/opencode/files.ts

@@ -30,6 +30,7 @@ import {
 import { Type } from "typebox";
 
 import { appendLspDiagnosticText } from "../lib/lsp/diagnostic.js";
+import { registerLspInspectTools } from "../lib/lsp/inspect-tool.js";
 import { type LspService, registerLsp } from "../lib/lsp/lsp.js";
 import { registerLspRenameTool } from "../lib/lsp/rename-tool.js";
 import { formatSubtitlePath } from "../lib/path.js";
@@ -700,6 +701,8 @@ export function registerFileTools(pi: ExtensionAPI, service: LspService): void {
   // 工具壳与 claude-code 共享（lib/lsp/rename-tool.ts）；opencode 不跟踪
   // read-before-write 状态，不传 recordReads hook。
   registerLspRenameTool(pi, service);
+  // 只读符号查询工具（find-definition / find-reference / inspect）与 claude-code 共享。
+  registerLspInspectTools(pi, service);
 }
 
 /** 独立入口：创建 LSP service（闭包共享给三个工具）并注册。 */

package/src/spawn-agent.ts

@@ -89,8 +89,8 @@ const SETTINGS_PATH = join(getAgentDir(), "settings.json");
  * implementation file (they share a read-snapshot state); the `tools`
  * allowlist still exposes only the declared subset. The opencode file tools
  * (read/edit/write) likewise share opencode/files.ts (they share the LSP
- * service instance); that file also registers the shared `lsp-rename` tool,
- * which stays hidden unless a subagent declares it.
+ * service instance); that file also registers the shared `lsp-rename` and
+ * LSP inspect tools, which stay hidden unless a subagent declares them.
  */
 const TOOL_EXTENSION_OVERRIDES: Record<string, string> = {
   read: "opencode/files.ts",