@trim21/personal-pi-extensions 0.0.299 → 0.0.301

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.299",
+  "version": "0.0.301",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -88,6 +88,8 @@
     "@cortexkit/aft-bridge": "0.51.0",
     "@vscode/tree-sitter-wasm": "^0.3.1",
     "jsonc-parser": "^3.3.1",
+    "vscode-jsonrpc": "^9.0.1",
+    "vscode-languageserver-types": "^3.18.0",
     "web-tree-sitter": "^0.26.12"
   },
   "optionalDependencies": {

package/src/aft/ast-edit.ts

@@ -35,7 +35,7 @@ export interface PreviewExtract {
   truncated: boolean;
 }
 
-/** AFT preview diff 条目：`include_diff_content` 时带 before/after，>512KB 只带 truncated。 */
+/** AFT preview diff 条目：preview 模式下默认带 before/after，>512KB 只带 truncated。 */
 const previewDiffSchema = Type.Object({
   before: Type.Optional(Type.String()),
   after: Type.Optional(Type.String()),
@@ -232,12 +232,11 @@ export function registerAstEditTool(pi: ExtensionAPI, ctx: AftToolContext): void
       const rawArgs = buildWireArgs(params, filePath);
 
       // 第一步：preview（不写盘）拿所有变动文件的 before/after，供写保护审批。
-      const { response } = await callAftTool(
-        bridgeFor(ctx),
-        "edit",
-        { ...rawArgs, preview: true, include_diff_content: true },
-        extCtx,
-      );
+      // preview 必须经 options 传入（bridge 会放到 tool_call 消息顶层），
+      // 放进 arguments 会被 AFT 忽略并真的写盘。
+      const { response } = await callAftTool(bridgeFor(ctx), "edit", rawArgs, extCtx, {
+        preview: true,
+      });
       const { files: previewFiles, truncated } = extractPreviewFiles(response);
       if (truncated) {
         throw new Error("ast_edit: file too large for preview (over 512KB)");

package/src/aft/bridge.ts

@@ -7,8 +7,6 @@
  * aft-bridge 锁一致就不会走到最后的网络下载。
  */
 
-import { createRequire } from "node:module";
-
 import {
   type AftProjectTransport,
   type AftTransportPool,
@@ -22,16 +20,6 @@ import {
 } from "@cortexkit/aft-bridge";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-/** aft-bridge 包自身版本，作为二进制版本匹配基准。 */
-const BRIDGE_VERSION: string = (() => {
-  try {
-    const req = createRequire(import.meta.url);
-    return (req("@cortexkit/aft-bridge/package.json") as { version?: string }).version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-})();
-
 /** Pi 会话 ID：Rust 侧用它做 session 作用域（undo/checkpoint），感知工具可留空。 */
 export function resolveSessionId(extCtx: ExtensionContext): string | undefined {
   const manager = (extCtx as unknown as { sessionManager?: { getSessionId?: () => string } })
@@ -40,9 +28,14 @@ export function resolveSessionId(extCtx: ExtensionContext): string | undefined {
   return typeof id === "string" && id.length > 0 ? id : undefined;
 }
 
-/** 解析 aft 二进制；失败时抛出（调用方决定是否降级不注册工具）。 */
+/**
+ * 解析 aft 二进制；失败时抛出（调用方决定是否降级不注册工具）。
+ * 不带版本参数：findBinary 内部用 @cortexkit/aft-bridge 自身版本作为匹配基准，
+ * 与 npm 平台包（@cortexkit/aft-<platform>）精确对齐，避免手动读 package.json
+ * （其 exports 不暴露 ./package.json）。
+ */
 export async function resolveAftBinary(): Promise<string> {
-  const path = await findBinary(BRIDGE_VERSION);
+  const path = await findBinary();
   if (!path) {
     throw new Error(
       "AFT binary not found. Install via npm platform package (@cortexkit/aft-<platform>), cargo install agent-file-tools, or place `aft` on PATH.",
@@ -64,7 +57,7 @@ export async function createAftPool(cwd: string): Promise<AftPool> {
   const pool = await createAftTransportPool({
     harness: "pi",
     binaryPath,
-    poolOptions: { minVersion: BRIDGE_VERSION },
+    poolOptions: {},
     configOverrides: {
       storage_dir: resolveCortexKitStorageRoot(),
       cortexkit_user_config_path: paths.userConfigPath,
@@ -85,7 +78,7 @@ export async function callAftTool(
   command: string,
   rawArgs: Record<string, unknown>,
   extCtx: ExtensionContext,
-  options?: BridgeRequestOptions,
+  options?: BridgeRequestOptions & { preview?: boolean },
   softCodes?: ReadonlySet<string>,
 ): Promise<{ text: string; response: Record<string, unknown> }> {
   const timeoutMs = timeoutForCommand(command);

package/src/claude-code/files.ts

@@ -14,6 +14,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import { createLspService, initLsp, type LspService } from "../lib/lsp/lsp.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import {
   type ClaudeCodeState,
@@ -211,7 +212,11 @@ function requireCurrentRead(
   }
 }
 
-export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): void {
+export function registerFileTools(
+  pi: ExtensionAPI,
+  state: ClaudeCodeState,
+  service: LspService,
+): void {
   pi.registerTool({
     name: "Read",
     label: "Read",
@@ -305,6 +310,10 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
       const snapshot = snapshotOf(buffer);
       const key = await readStateKey(filePath);
       state.reads.set(key, snapshot);
+      // LSP warm-up 是后台任务，失败不影响读取
+      void service.touchFile(filePath, ctx.cwd).catch(() => {
+        // 后台 warm-up 失败不影响读取
+      });
       return {
         content: [{ type: "text", text: formatted.text }],
         details: { reads: { [key]: snapshot } },
@@ -348,118 +357,127 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
           replaceAll: params.replace_all,
         },
       });
-      return withFileMutationQueue(filePath, async () => {
-        const oldString = params.old_string;
-        const newString = params.new_string;
-        if (oldString === newString) {
-          throw new Error("No changes to make: old_string and new_string are exactly the same.");
-        }
-        // 空 old_string：创建新文件或填充空文件（不需要先 Read，对齐 Claude Code）
-        if (oldString === "") {
-          let exists = true;
-          try {
-            const value = await stat(filePath);
-            if (value.isFile()) {
-              const content = await readFile(filePath, "utf8");
-              if (content.trim() !== "") {
-                throw new Error("Cannot create new file - file already exists.");
+      const [message, details] = await withFileMutationQueue<[string, FileToolDetails]>(
+        filePath,
+        async () => {
+          const oldString = params.old_string;
+          const newString = params.new_string;
+          if (oldString === newString) {
+            throw new Error("No changes to make: old_string and new_string are exactly the same.");
+          }
+          // 空 old_string：创建新文件或填充空文件（不需要先 Read，对齐 Claude Code）
+          if (oldString === "") {
+            let exists = true;
+            try {
+              const value = await stat(filePath);
+              if (value.isFile()) {
+                const content = await readFile(filePath, "utf8");
+                if (content.trim() !== "") {
+                  throw new Error("Cannot create new file - file already exists.");
+                }
+              }
+            } catch (error) {
+              if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                exists = false;
+              } else {
+                throw error;
               }
             }
+            if (!exists) await mkdir(dirname(filePath), { recursive: true });
+            await writeFile(filePath, newString, "utf8");
+            const snapshot = snapshotOf(newString);
+            const key = await readStateKey(filePath);
+            state.reads.set(key, snapshot);
+            return [
+              `The file ${filePath} has been updated successfully.`,
+              { reads: { [key]: snapshot } },
+            ];
+          }
+          const replaceAll = params.replace_all ?? false;
+          // 防止 OOM 的大文件检查（对齐 Claude Code）
+          try {
+            const { size } = await stat(filePath);
+            if (size > MAX_EDIT_FILE_SIZE) {
+              throw new Error(
+                `File is too large to edit (${formatFileSize(size)}). Maximum editable file size is ${formatFileSize(MAX_EDIT_FILE_SIZE)}.`,
+              );
+            }
           } catch (error) {
-            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-              exists = false;
-            } else {
+            if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
               throw error;
             }
           }
-          if (!exists) await mkdir(dirname(filePath), { recursive: true });
-          await writeFile(filePath, newString, "utf8");
-          const snapshot = snapshotOf(newString);
-          const key = await readStateKey(filePath);
-          state.reads.set(key, snapshot);
-          return {
-            content: [
-              { type: "text", text: `The file ${filePath} has been updated successfully.` },
-            ],
-            details: { reads: { [key]: snapshot } } satisfies FileToolDetails,
-          };
-        }
-        const replaceAll = params.replace_all ?? false;
-        // 防止 OOM 的大文件检查（对齐 Claude Code）
-        try {
-          const { size } = await stat(filePath);
-          if (size > MAX_EDIT_FILE_SIZE) {
+          let content: Buffer;
+          try {
+            content = await readFile(filePath);
+          } catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+              const suggestion = await didYouMean(filePath, ctx.cwd);
+              throw new Error(
+                `File does not exist. Note: your current working directory is ${ctx.cwd}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`,
+                { cause: error },
+              );
+            }
+            throw error;
+          }
+          if (extname(filePath).toLowerCase() === ".ipynb") {
             throw new Error(
-              `File is too large to edit (${formatFileSize(size)}). Maximum editable file size is ${formatFileSize(MAX_EDIT_FILE_SIZE)}.`,
+              "File is a Jupyter Notebook. Use the NotebookEditTool to edit this file.",
             );
           }
-        } catch (error) {
-          if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
-            throw error;
+          const key = await readStateKey(filePath);
+          requireCurrentRead(state, key, filePath, content);
+          await access(filePath, constants.R_OK | constants.W_OK);
+          throwIfAborted(signal);
+          const original = content.toString("utf8");
+
+          // CRLF 规范化后匹配（old_string 不需要带 \r），写回时恢复原行尾
+          const crlfCount = (original.match(/\r\n/g) ?? []).length;
+          const lfCount = (original.match(/(?<!\r)\n/g) ?? []).length;
+          const lineEnding = crlfCount > lfCount ? "\r\n" : "\n";
+          const normalized = original.replaceAll("\r\n", "\n");
+          const actualOldString = findActualString(normalized, oldString) ?? oldString;
+          const matches = normalized.split(actualOldString).length - 1;
+          if (matches === 0) {
+            throw new Error(`String to replace not found in file.\nString: ${oldString}`);
           }
-        }
-        let content: Buffer;
-        try {
-          content = await readFile(filePath);
-        } catch (error) {
-          if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-            const suggestion = await didYouMean(filePath, ctx.cwd);
+          if (!replaceAll && matches > 1) {
             throw new Error(
-              `File does not exist. Note: your current working directory is ${ctx.cwd}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`,
-              { cause: error },
+              `Found ${matches} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.\nString: ${oldString}`,
             );
           }
-          throw error;
-        }
-        if (extname(filePath).toLowerCase() === ".ipynb") {
-          throw new Error(
-            "File is a Jupyter Notebook. Use the NotebookEditTool to edit this file.",
-          );
-        }
-        const key = await readStateKey(filePath);
-        requireCurrentRead(state, key, filePath, content);
-        await access(filePath, constants.R_OK | constants.W_OK);
-        throwIfAborted(signal);
-        const original = content.toString("utf8");
+          const actualNewString = preserveQuoteStyle(oldString, actualOldString, newString);
+          // split/join 与函数替换：replacement 含 $ 时不会触发 $& 等特殊语义
+          const updated = replaceAll
+            ? normalized.split(actualOldString).join(actualNewString)
+            : normalized.replace(actualOldString, () => actualNewString);
+          const restored = lineEnding === "\r\n" ? updated.replaceAll("\n", "\r\n") : updated;
+          await writeFile(filePath, restored, "utf8");
+          const snapshot = snapshotOf(restored);
+          state.reads.set(key, snapshot);
+          const diff = generateDiffString(original, restored);
+          const text = replaceAll
+            ? `The file ${filePath} has been updated. All occurrences were successfully replaced.`
+            : `The file ${filePath} has been updated successfully.`;
+          return [
+            text,
+            {
+              diff: diff.diff,
+              patch: generateUnifiedPatch(filePath, original, restored),
+              firstChangedLine: diff.firstChangedLine,
+              reads: { [key]: snapshot },
+            },
+          ];
+        },
+      );
 
-        // CRLF 规范化后匹配（old_string 不需要带 \r），写回时恢复原行尾
-        const crlfCount = (original.match(/\r\n/g) ?? []).length;
-        const lfCount = (original.match(/(?<!\r)\n/g) ?? []).length;
-        const lineEnding = crlfCount > lfCount ? "\r\n" : "\n";
-        const normalized = original.replaceAll("\r\n", "\n");
-        const actualOldString = findActualString(normalized, oldString) ?? oldString;
-        const matches = normalized.split(actualOldString).length - 1;
-        if (matches === 0) {
-          throw new Error(`String to replace not found in file.\nString: ${oldString}`);
-        }
-        if (!replaceAll && matches > 1) {
-          throw new Error(
-            `Found ${matches} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.\nString: ${oldString}`,
-          );
-        }
-        const actualNewString = preserveQuoteStyle(oldString, actualOldString, newString);
-        // split/join 与函数替换：replacement 含 $ 时不会触发 $& 等特殊语义
-        const updated = replaceAll
-          ? normalized.split(actualOldString).join(actualNewString)
-          : normalized.replace(actualOldString, () => actualNewString);
-        const restored = lineEnding === "\r\n" ? updated.replaceAll("\n", "\r\n") : updated;
-        await writeFile(filePath, restored, "utf8");
-        const snapshot = snapshotOf(restored);
-        state.reads.set(key, snapshot);
-        const diff = generateDiffString(original, restored);
-        const text = replaceAll
-          ? `The file ${filePath} has been updated. All occurrences were successfully replaced.`
-          : `The file ${filePath} has been updated successfully.`;
-        return {
-          content: [{ type: "text", text }],
-          details: {
-            diff: diff.diff,
-            patch: generateUnifiedPatch(filePath, original, restored),
-            firstChangedLine: diff.firstChangedLine,
-            reads: { [key]: snapshot },
-          } satisfies FileToolDetails,
-        };
-      });
+      throwIfAborted(signal);
+      // 写后等待文档诊断，ERROR 级错误追加到输出让模型可见
+      const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd);
+      const text = diagnosticText
+        ? `${message}\n\nLSP errors detected in this file, please fix:\n${diagnosticText}`
+        : message;
+      return { content: [{ type: "text" as const, text }], details };
     },
   });
 
@@ -490,44 +508,55 @@ export function registerFileTools(pi: ExtensionAPI, state: ClaudeCodeState): voi
         absolutePath: filePath,
         change: { oldText: "", newText: params.content },
       });
-      return withFileMutationQueue(filePath, async () => {
-        let original: string | undefined;
-        let key: string | undefined;
-        try {
-          const value = await stat(filePath);
-          if (value.isFile()) {
-            const content = await readFile(filePath);
-            key = await readStateKey(filePath);
-            requireCurrentRead(state, key, filePath, content);
-            original = content.toString("utf8");
-          }
-        } catch (error) {
-          if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
-            throw error;
+      const [message, details] = await withFileMutationQueue<[string, FileToolDetails]>(
+        filePath,
+        async () => {
+          let original: string | undefined;
+          let key: string | undefined;
+          try {
+            const value = await stat(filePath);
+            if (value.isFile()) {
+              const content = await readFile(filePath);
+              key = await readStateKey(filePath);
+              requireCurrentRead(state, key, filePath, content);
+              original = content.toString("utf8");
+            }
+          } catch (error) {
+            if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+              throw error;
+            }
           }
-        }
-        throwIfAborted(signal);
-        await mkdir(dirname(filePath), { recursive: true });
-        await writeFile(filePath, params.content, "utf8");
-        const snapshot = snapshotOf(params.content);
-        // 新建文件：writeFile 之后 realpath 才能解析；覆盖写则复用上面的 key
-        const resolvedKey = key ?? (await readStateKey(filePath));
-        state.reads.set(resolvedKey, snapshot);
-        const diff = generateDiffString(original ?? "", params.content);
-        const text =
-          original === undefined
-            ? `File created successfully at: ${filePath}`
-            : `The file ${filePath} has been updated successfully.`;
-        return {
-          content: [{ type: "text", text }],
-          details: {
-            diff: diff.diff,
-            patch: generateUnifiedPatch(filePath, original ?? "", params.content),
-            firstChangedLine: diff.firstChangedLine,
-            reads: { [resolvedKey]: snapshot },
-          } satisfies FileToolDetails,
-        };
-      });
+          throwIfAborted(signal);
+          await mkdir(dirname(filePath), { recursive: true });
+          await writeFile(filePath, params.content, "utf8");
+          const snapshot = snapshotOf(params.content);
+          // 新建文件：writeFile 之后 realpath 才能解析；覆盖写则复用上面的 key
+          const resolvedKey = key ?? (await readStateKey(filePath));
+          state.reads.set(resolvedKey, snapshot);
+          const diff = generateDiffString(original ?? "", params.content);
+          const text =
+            original === undefined
+              ? `File created successfully at: ${filePath}`
+              : `The file ${filePath} has been updated successfully.`;
+          return [
+            text,
+            {
+              diff: diff.diff,
+              patch: generateUnifiedPatch(filePath, original ?? "", params.content),
+              firstChangedLine: diff.firstChangedLine,
+              reads: { [resolvedKey]: snapshot },
+            },
+          ];
+        },
+      );
+
+      throwIfAborted(signal);
+      // 写后等待文档诊断，ERROR 级错误追加到输出让模型可见
+      const diagnosticText = await service.lspDiagnosticsForFile(filePath, ctx.cwd);
+      const text = diagnosticText
+        ? `${message}\n\nLSP errors detected in this file, please fix:\n${diagnosticText}`
+        : message;
+      return { content: [{ type: "text" as const, text }], details };
     },
   });
 }
@@ -562,6 +591,8 @@ function restoreFileReads(
  * 与主进程 index.ts 聚合加载时的行为一致。
  */
 export default function claudeCodeFileTools(pi: ExtensionAPI): void {
+  const service = createLspService();
+  initLsp(pi, service);
   const state = createClaudeCodeState();
 
   // 扩展实例在进程启动 / /reload / /new / /resume / /fork 时重建，内存里的
@@ -579,5 +610,5 @@ export default function claudeCodeFileTools(pi: ExtensionAPI): void {
     restoreFileReads(state, ctx.sessionManager);
   });
 
-  registerFileTools(pi, state);
+  registerFileTools(pi, state, service);
 }

package/src/lib/lsp/adapter.ts

@@ -0,0 +1,41 @@
+/**
+ * LSP 服务器插件契约：每个语言服务器一个 adapter class，向管理器提供统一接口。
+ *
+ * - findRoot 返回 undefined 表示该文件不应启用此服务器（目录外 / 无项目标记）；
+ * - spawn 返回 undefined 表示服务器不可用（二进制未安装）。
+ */
+
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { dirname, join } from "node:path";
+
+import { exists, walkUp } from "./bin.js";
+
+export interface LspServerHandle {
+  process: ChildProcessWithoutNullStreams;
+  initialization?: Record<string, unknown>;
+}
+
+export interface LspServerAdapter {
+  readonly id: string;
+  /** 关联的文件扩展名（含点，小写）；空数组表示匹配所有文件。 */
+  readonly extensions: readonly string[];
+  findRoot(file: string, cwd: string): Promise<string | undefined>;
+  spawn(root: string, cwd: string): Promise<LspServerHandle | undefined>;
+}
+
+/**
+ * 从文件所在目录向上（到 cwd）找项目标记文件；找不到时返回 cwd（opencode 的
+ * NearestRoot 宽松语义，保证项目内文件至少有一个 root）。
+ */
+export function nearestRoot(
+  markers: readonly string[],
+  file: string,
+  cwd: string,
+): Promise<string> {
+  for (const dir of walkUp(dirname(file), cwd)) {
+    for (const marker of markers) {
+      if (exists(join(dir, marker))) return Promise.resolve(dir);
+    }
+  }
+  return Promise.resolve(cwd);
+}

package/src/lib/lsp/adapters/clangd.ts

@@ -0,0 +1,26 @@
+/**
+ * C/C++ LSP 服务器（clangd，随 LLVM/clang 工具链安装，走 PATH）。
+ */
+
+import { type LspServerAdapter, type LspServerHandle, nearestRoot } from "../adapter.js";
+import { which } from "../bin.js";
+import { spawnProcess } from "../launch.js";
+
+const PROJECT_MARKERS = ["compile_commands.json", "compile_flags.txt", ".clangd"];
+
+export class ClangdAdapter implements LspServerAdapter {
+  readonly id = "clangd";
+  readonly extensions = [".c", ".cpp", ".cc", ".cxx", ".c++", ".h", ".hpp", ".hh", ".hxx", ".h++"];
+
+  findRoot(file: string, cwd: string): Promise<string> {
+    return nearestRoot(PROJECT_MARKERS, file, cwd);
+  }
+
+  spawn(root: string): Promise<LspServerHandle | undefined> {
+    const bin = which("clangd");
+    if (!bin) return Promise.resolve(undefined);
+    return Promise.resolve({
+      process: spawnProcess(bin, ["--background-index", "--clang-tidy"], { cwd: root }),
+    });
+  }
+}

package/src/lib/lsp/adapters/index.ts

@@ -0,0 +1,11 @@
+import { ClangdAdapter } from "./clangd.js";
+import { PyrightAdapter } from "./pyright.js";
+import { RuffAdapter } from "./ruff.js";
+import { TypescriptAdapter } from "./typescript.js";
+
+export type { LspServerAdapter, LspServerHandle } from "../adapter.js";
+
+/** 组装启用的服务器列表（新增语言：实现 adapter 后在这里注册）。 */
+export function createAdapters() {
+  return [new TypescriptAdapter(), new PyrightAdapter(), new RuffAdapter(), new ClangdAdapter()];
+}

package/src/lib/lsp/adapters/pyright.ts

@@ -0,0 +1,50 @@
+/**
+ * Python 类型检查 LSP 服务器（pyright-langserver）。
+ * pythonPath 优先取 VIRTUAL_ENV，其次项目 .venv / venv 里的解释器。
+ */
+
+import { join } from "node:path";
+
+import { type LspServerAdapter, nearestRoot } from "../adapter.js";
+import { exists, findBinaryInWorkspace, which } from "../bin.js";
+import { spawnProcess } from "../launch.js";
+
+const PROJECT_MARKERS = [
+  "pyproject.toml",
+  "setup.py",
+  "setup.cfg",
+  "requirements.txt",
+  "Pipfile",
+  "pyrightconfig.json",
+];
+
+export class PyrightAdapter implements LspServerAdapter {
+  readonly id = "pyright";
+  readonly extensions = [".py", ".pyi"];
+
+  findRoot(file: string, cwd: string): Promise<string> {
+    return nearestRoot(PROJECT_MARKERS, file, cwd);
+  }
+
+  async spawn(root: string, cwd: string) {
+    const bin =
+      (await findBinaryInWorkspace("pyright-langserver", root, cwd)) ?? which("pyright-langserver");
+    if (!bin) return;
+
+    const initialization: Record<string, string> = {};
+    const venvs = [process.env.VIRTUAL_ENV, join(root, ".venv"), join(root, "venv")];
+    for (const venv of venvs) {
+      if (!venv) continue;
+      const python = join(venv, process.platform === "win32" ? "Scripts" : "bin", "python");
+      if (exists(python)) {
+        initialization.pythonPath = python;
+        break;
+      }
+    }
+
+    return {
+      process: spawnProcess(bin, ["--stdio"], { cwd: root }),
+      initialization,
+    };
+  }
+}

package/src/lib/lsp/adapters/ruff.ts

@@ -0,0 +1,27 @@
+/**
+ * Python lint LSP 服务器（ruff 内置的 `ruff server`）。
+ * 二进制优先项目 .venv / venv，其次 PATH。
+ */
+
+import { type LspServerAdapter, nearestRoot } from "../adapter.js";
+import { findBinaryInWorkspace, which } from "../bin.js";
+import { spawnProcess } from "../launch.js";
+
+const PROJECT_MARKERS = ["pyproject.toml", "ruff.toml", ".ruff.toml"];
+
+export class RuffAdapter implements LspServerAdapter {
+  readonly id = "ruff";
+  readonly extensions = [".py", ".pyi"];
+
+  findRoot(file: string, cwd: string): Promise<string> {
+    return nearestRoot(PROJECT_MARKERS, file, cwd);
+  }
+
+  async spawn(root: string, cwd: string) {
+    const bin = (await findBinaryInWorkspace("ruff", root, cwd)) ?? which("ruff");
+    if (!bin) return;
+    return {
+      process: spawnProcess(bin, ["server"], { cwd: root }),
+    };
+  }
+}