@trim21/personal-pi-extensions 0.1.650 → 0.1.652

package/src/index.ts

@@ -0,0 +1,120 @@
+/**
+ * 本仓库的统一扩展入口：所有工具都在这里注册。
+ *
+ * 为什么是单一入口：pi 给每个扩展入口单独的模块图，模块级状态不跨入口共享。
+ * 工具集中在一处之后，同一入口内的模块（codemode 等）才能看到并直接调用
+ * 全部工具；`personalExtensions` 配置（`fileIo` / `fileIoByModel` /
+ * `disabledTools` / `enabledTools`）也才有唯一的求值点。
+ *
+ * 注册时机：pi 在每次会话启动（启动、/new、resume、fork、/reload）时重建扩展，
+ * 所以在 `session_start` 里注册即「每个会话按自己的模型判定一次」。模型在扩展
+ * 加载期读不到（`ctx.model` 只在事件里），这是注册放在 session_start 的原因。
+ *
+ * 模块划分：两套文件 IO 工具集（claude-code / opencode）由 `ToolUnit` 表描述，
+ * 其余工具模块暴露 `createXxx(pi)`；各模块的默认导出保留给「按路径单独加载」
+ * （手工 `-e`），本入口直接调用 createXxx，因此一个实例里只有一份模块状态。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createAftTools } from "./aft/index.js";
+import { createClaudeCodeFileTools } from "./claude-code/files.js";
+import { createGithubTools } from "./gh/index.js";
+import type { ToolBus } from "./lib/tool-bus.js";
+import { createToolRegistration } from "./lib/tool-registration.js";
+import { createToolServices } from "./lib/tool-services.js";
+import { TOOL_UNITS, type ToolUnitDeps } from "./lib/tool-units.js";
+import { resolveFileIoToolset } from "./lib/tools-config.js";
+import { createOpencodeFileTools } from "./opencode/files.js";
+import { createSpawnAgentTool } from "./spawn-agent.js";
+import { createTalkTools } from "./talk/index.js";
+import { createVisionTools } from "./vision-agent.js";
+import { createWebFetch } from "./web/fetch.js";
+import { createWebSearchTool } from "./web/search.js";
+
+/** 只做工具注册、以及自己那些与会话无关的钩子的模块。 */
+interface ToolModule {
+  register(bus: ToolBus): void;
+}
+
+export default function personalExtensions(pi: ExtensionAPI): void {
+  const registration = createToolRegistration(pi);
+  // 共享服务要在 registration 之后创建：LSP manager 的 session_start handler 得
+  // 排在「记录本会话模型」的 handler 之后。
+  const services = createToolServices(pi);
+
+  // 与文件工具集无关的模块（各自在 create 里注册自己的会话钩子与提示）。
+  const modules: { name: string; module: ToolModule }[] = [];
+  const addModule = (name: string, module: ToolModule | undefined): void => {
+    if (module) {
+      modules.push({ name, module });
+    }
+  };
+  addModule("github", createGithubTools());
+  addModule("vision", createVisionTools());
+  addModule("talk", createTalkTools(pi));
+  addModule("spawn-agent", createSpawnAgentTool());
+  addModule("web_search", createWebSearchTool());
+  addModule("web_fetch", createWebFetch(pi));
+  const aft = createAftTools(pi);
+
+  // 注册期的失败攒起来，在会话启动时一次性上报（那里才有 UI）。
+  const warnings: string[] = [];
+
+  /** 单个模块/单元注册失败不影响其余：记下失败，继续注册。 */
+  function runModule<T>(name: string, run: () => T): T | undefined {
+    try {
+      return run();
+    } catch (error) {
+      warnings.push(`${name}: ${error instanceof Error ? error.message : String(error)}`);
+      return undefined;
+    }
+  }
+
+  registration.onSessionStart(async (bus, ctx) => {
+    // 配置解析期的警告是稳定的，注册期的失败每个会话重新收集（避免跨会话重复上报）。
+    warnings.length = 0;
+    warnings.push(...registration.config.warnings);
+
+    // 文件工具集跟着本会话的模型走（会话内切换模型不重建扩展，因此不重判）。
+    const kind = resolveFileIoToolset(registration.config, ctx.model);
+    const fileToolset =
+      kind === "opencode"
+        ? createOpencodeFileTools(pi, {
+            policy: services.policy,
+            bus,
+            manager: services.manager,
+          })
+        : createClaudeCodeFileTools(pi, {
+            policy: services.policy,
+            bus,
+            manager: services.manager,
+          });
+    services.setLspEnabledHandler((service) => fileToolset.onLspEnabled(bus, service));
+    runModule(kind, () => fileToolset.restoreReads(ctx));
+
+    const deps: ToolUnitDeps = {
+      pi,
+      bus,
+      policy: services.policy,
+      runtime: services.runtime,
+      fileToolset,
+    };
+    for (const unit of TOOL_UNITS[kind]) {
+      runModule(unit.tools.join("/"), () => unit.register(deps));
+    }
+
+    // aft 的二进制探测、bridge 状态与工具注册绑在一起（找不到二进制就不注册）。
+    await runModule("aft", () => aft.registerForSession(bus, ctx));
+    for (const { name, module } of modules) {
+      runModule(name, () => module.register(bus));
+    }
+
+    for (const warning of warnings) {
+      ctx.ui.notify(warning, "warning");
+    }
+    for (const { field, pattern } of registration.unmatchedPatterns()) {
+      ctx.ui.notify(`personalExtensions.${field}: pattern "${pattern}" matches no tool`, "warning");
+    }
+  });
+}

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

@@ -14,11 +14,11 @@ 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 { ToolBus } from "../tool-bus.js";
 import type { InspectLocation } from "./client.js";
 import type { LspService } from "./lsp.js";
 import { type LspPosition, symbolCandidates } from "./rename.js";
@@ -255,8 +255,8 @@ async function probeSymbolCandidates(options: {
   return first.output;
 }
 
-export function registerLspInspectTools(pi: ExtensionAPI, service: LspService): void {
-  pi.registerTool({
+export function registerLspInspectTools(bus: ToolBus, service: LspService): void {
+  bus.register({
     name: "lsp-find-definition",
     label: "Lsp Find Definition",
     description:
@@ -299,7 +299,7 @@ export function registerLspInspectTools(pi: ExtensionAPI, service: LspService):
     },
   });
 
-  pi.registerTool({
+  bus.register({
     name: "lsp-find-reference",
     label: "Lsp Find Reference",
     description:
@@ -342,7 +342,7 @@ export function registerLspInspectTools(pi: ExtensionAPI, service: LspService):
     },
   });
 
-  pi.registerTool({
+  bus.register({
     name: "lsp-inspect",
     label: "Lsp Inspect",
     description:

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

@@ -14,16 +14,13 @@ import { readFileSync } from "node:fs";
 import { readFile, stat, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
-import {
-  type ExtensionAPI,
-  generateDiffString,
-  withFileMutationQueue,
-} from "@earendil-works/pi-coding-agent";
+import { generateDiffString, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 import { resolvePathArg } from "../path.js";
 import type { ToolPendant } from "../pendant.ts";
 import type { RequestPolicy } from "../request-policy.js";
+import type { ToolBus } from "../tool-bus.js";
 import { guardWriteAccess } from "../write-guard.js";
 import { RenameNotPossibleError } from "./client.js";
 import type { LspService } from "./lsp.js";
@@ -51,11 +48,11 @@ const LSP_RENAME_PROMPT = readFileSync(
 ).trim();
 
 export function registerLspRenameTool(
-  pi: ExtensionAPI,
+  bus: ToolBus,
   service: LspService,
   options: LspRenameOptions,
 ): void {
-  pi.registerTool({
+  bus.register({
     name: "lsp-rename",
     label: "Lsp Rename",
     description: "Rename a code symbol and update all references across the workspace via LSP",

package/src/lib/tool-bus.ts

@@ -0,0 +1,126 @@
+/**
+ * 工具总线：本仓库全部工具的唯一注册通道，也是同入口模块（codemode 等）直接调用
+ * 工具的通道。
+ *
+ * - `register`：按配置过滤（被禁用时跳过并返回 false）后交给 `pi.registerTool`，
+ *   并保留通过的定义供 `list` / `get` 查询。
+ * - `executeTool`：先用工具自身的参数 schema 校验参数，再调用定义的 `execute`；
+ *   参数校验失败与工具抛出的异常都归一化成错误结果返回，不向调用方抛异常。
+ *
+ * 状态由闭包持有（工厂 + 闭包），不使用模块级可变状态。
+ */
+
+import type { AgentToolResult, AgentToolUpdateCallback } from "@earendil-works/pi-agent-core";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
+
+import { parseWithSchema } from "./parse-with-schema.js";
+
+/** 一次工具执行的结果：`isError` 标出失败（工具不存在、参数不合法、工具抛错）。 */
+export type ToolExecutionResult = AgentToolResult<unknown> & { isError: boolean };
+
+export interface ExecuteToolOptions {
+  /** 工具 `execute` 需要的宿主上下文：调用方把自己拿到的那个 ctx 传进来。 */
+  ctx: ExtensionContext;
+  signal?: AbortSignal;
+  onUpdate?: AgentToolUpdateCallback<unknown>;
+  /** 日志与临时文件命名用的调用 id；缺省由总线生成。 */
+  toolCallId?: string;
+}
+
+export interface ToolBus {
+  /** 注册一个工具；被配置禁用时跳过并返回 false。 */
+  register<TParams extends TSchema, TDetails>(
+    definition: ToolDefinition<TParams, TDetails, unknown>,
+  ): boolean;
+  /** 本次实际注册的工具定义。 */
+  list(): readonly ToolDefinition[];
+  /** 所有尝试注册过的工具名（含被禁用而跳过的），用于校验配置里的模式是否有效。 */
+  declaredNames(): readonly string[];
+  get(name: string): ToolDefinition | undefined;
+  /** 按名执行一个已注册工具；任何失败都以 `isError` 结果返回，不抛异常。 */
+  executeTool(
+    name: string,
+    args: unknown,
+    options: ExecuteToolOptions,
+  ): Promise<ToolExecutionResult>;
+}
+
+export interface ToolBusOptions {
+  /** 返回 true 表示该工具被禁用、不注册。 */
+  isDisabled?: (name: string) => boolean;
+}
+
+type AnyToolDefinition = ToolDefinition<TSchema, unknown, unknown>;
+
+function errorResult(text: string): ToolExecutionResult {
+  return { content: [{ type: "text", text }], details: { error: text }, isError: true };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function createToolBus(pi: ExtensionAPI, options: ToolBusOptions = {}): ToolBus {
+  const registered = new Map<string, AnyToolDefinition>();
+  const declared = new Set<string>();
+  let callCounter = 0;
+
+  return {
+    register(definition) {
+      declared.add(definition.name);
+      if (options.isDisabled?.(definition.name) === true) {
+        return false;
+      }
+      const stored = definition as unknown as AnyToolDefinition;
+      pi.registerTool(stored);
+      registered.set(stored.name, stored);
+      return true;
+    },
+
+    list() {
+      return [...registered.values()];
+    },
+
+    declaredNames() {
+      return [...declared];
+    },
+
+    get(name) {
+      return registered.get(name);
+    },
+
+    async executeTool(name, args, options) {
+      const definition = registered.get(name);
+      if (!definition) {
+        return errorResult(`Tool "${name}" is not available.`);
+      }
+
+      const toolCallId = options.toolCallId ?? `tool-bus-${++callCounter}`;
+      let params: Static<TSchema>;
+      try {
+        const prepared = definition.prepareArguments ? definition.prepareArguments(args) : args;
+        params = parseWithSchema(definition.parameters, prepared);
+      } catch (error) {
+        return errorResult(`Invalid arguments for tool "${name}": ${errorMessage(error)}`);
+      }
+
+      try {
+        const result = await definition.execute(
+          toolCallId,
+          params,
+          options.signal,
+          options.onUpdate,
+          options.ctx,
+        );
+        return { ...result, isError: false };
+      } catch (error) {
+        return errorResult(`Tool "${name}" failed: ${errorMessage(error)}`);
+      }
+    },
+  };
+}

package/src/lib/tool-registration.ts

@@ -0,0 +1,83 @@
+/**
+ * 工具注册上下文：把「配置 + 当前会话模型 → 总线 → 注册」这条链路收在一处。
+ *
+ * 约定：模块里的 registerXxx(bus, ...) 只收发工具的总线，需要宿主 API（pi.exec、
+ * pi.on、runtime.setup 等）时把 `pi` 作为后续参数显式传入；扩展入口/默认导出
+ * 用本文件的 createToolRegistration 把「当前会话模型」接上，并在 session_start
+ * 里调用这些 registerXxx。
+ *
+ * 为什么总线要先建、注册要晚于 `session_start`：
+ * - 禁用规则可以带 `models`，只有在 `session_start` 才能拿到本会话的模型，
+ *   因此注册发生在 `session_start` 里（总线在加载期先建好，过滤在注册时求值）。
+ * - LSP manager 在加载期创建、并在它自己的 `session_start` handler 里启用服务器
+ *   后回调注册 lsp 工具，所以它必须在加载期就能拿到同一个总线；模型由本文件
+ *   注册的 handler 更新，且它排在所有注册 handler 之前。
+ *
+ * 注册即启用：`pi.registerTool` 后工具默认进入 active 列表（pi 的 `defaultActive`
+ * 语义），本文件不碰 active 列表——工具可见性完全由「注册与否」决定，禁用工具就是
+ * 不注册。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { createToolBus, type ToolBus } from "./tool-bus.js";
+import {
+  type ModelIdentity,
+  readToolsConfig,
+  resolveToolAvailability,
+  type ToolsConfig,
+  type UnmatchedPattern,
+} from "./tools-config.js";
+
+export interface ToolRegistration {
+  /** 与同入口其他模块共享的总线。 */
+  readonly bus: ToolBus;
+  /** 本次配置解析结果（含解析期警告）。 */
+  readonly config: ToolsConfig;
+  /**
+   * 在每次会话启动时注册工具；注册时总线的过滤已按本会话模型生效。回调拿到
+   * 本会话的 ctx（reads 记账恢复等需要 sessionManager）。
+   */
+  onSessionStart(register: (bus: ToolBus, ctx: ExtensionContext) => void | Promise<void>): void;
+  /** 哪些配置模式没命中过任何工具（在注册完成后调用）。 */
+  unmatchedPatterns(): UnmatchedPattern[];
+}
+
+/**
+ * 独立入口（按路径加载的模块、或只有一组工具的入口）的注册接线：
+ * 每次会话启动时用本会话模型建好的总线注册工具。
+ */
+export function registerToolsOnSessionStart(
+  pi: ExtensionAPI,
+  register: (bus: ToolBus, ctx: ExtensionContext) => void | Promise<void>,
+): void {
+  createToolRegistration(pi).onSessionStart(register);
+}
+
+export function createToolRegistration(pi: ExtensionAPI, settingsPath?: string): ToolRegistration {
+  const config = readToolsConfig(settingsPath);
+  let model: ModelIdentity | undefined;
+
+  const bus = createToolBus(pi, {
+    // 每次注册都按当前模型重新判定：工具在 session_start 里注册，模型由下面
+    // 的 handler 更新，二者在同一个会话内保持一致。
+    isDisabled: (name) => resolveToolAvailability(config, model).isDisabled(name),
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    model = ctx.model;
+  });
+
+  return {
+    bus,
+    config,
+    onSessionStart(register) {
+      pi.on("session_start", async (_event, ctx) => {
+        await register(bus, ctx);
+      });
+    },
+    unmatchedPatterns() {
+      return resolveToolAvailability(config, model).unmatchedPatterns(bus.declaredNames());
+    },
+  };
+}

package/src/lib/tool-services.ts

@@ -0,0 +1,65 @@
+/**
+ * 共享工具服务：同一个扩展实例里的所有工具共用一份请求策略、bwrap runtime 与
+ * LSP manager。
+ *
+ * 为什么必须共享：两套文件 IO 工具集各自创建 LSP manager 会重复注册 `/lsp-*`
+ * 命令（命令名冲突）；各自创建 bwrap runtime 会重复注册 `/bwrap*` 命令。因此
+ * 由入口创建一份、注入给选中的工具集。
+ *
+ * LSP 专属工具（lsp-rename / inspect 族）由「当前会话选中的工具集」注册，
+ * 通过 `setLspEnabledHandler` 交给本模块——manager 在 session_start 之后才
+ * 触发该回调，那时入口已完成工具集选择。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { BwrapConfig } from "../bwrap/core.js";
+import { type BwrapRuntime, createBwrapRuntime } from "../bwrap/runtime.js";
+import {
+  createLspManager,
+  type LspManager,
+  type LspService,
+  type LspServiceOptions,
+} from "./lsp/lsp.js";
+import { createRequestPolicy, type RequestPolicy } from "./request-policy.js";
+
+export interface ToolServices {
+  policy: RequestPolicy;
+  runtime: BwrapRuntime;
+  manager: LspManager;
+  /** 由入口在选出本会话的工具集后设置。 */
+  setLspEnabledHandler(handler: ((service: LspService) => void) | undefined): void;
+}
+
+export interface ToolServicesOptions extends LspServiceOptions {
+  /** 固定沙箱配置（子代理用）；不传则跟随用户配置与 /bwrap-* 命令。 */
+  sandbox?: BwrapConfig;
+}
+
+export function createToolServices(pi: ExtensionAPI, options?: ToolServicesOptions): ToolServices {
+  const policy = createRequestPolicy(pi.events);
+  const runtime = createBwrapRuntime(policy, options?.sandbox);
+  // 注册 /bwrap* 命令、沙箱系统提示与 session 生命周期钩子；固定沙箱
+  // （子代理）不注册命令，见 BwrapRuntime.setup。
+  runtime.setup(pi);
+
+  let delegate: ((service: LspService) => void) | undefined;
+  const manager = createLspManager(
+    pi,
+    {
+      onEnabled: (_pi, service) => {
+        delegate?.(service);
+      },
+    },
+    options,
+  );
+
+  return {
+    policy,
+    runtime,
+    manager,
+    setLspEnabledHandler(handler) {
+      delegate = handler;
+    },
+  };
+}

package/src/lib/tool-units.ts

@@ -0,0 +1,102 @@
+/**
+ * 工具单元表：本仓库工具按「一套文件 IO 工具集 + 若干单元」组织，主入口与
+ * spawn-agent 的子代理共用同一张表，因此两处的工具实现、参数与审批完全一致。
+ *
+ * - 主入口按配置选中的工具集注册全部单元（`fileIo` / `fileIoByModel`）。
+ * - 子代理按 frontmatter 声明的工具名注册覆盖到的单元；可见性再由
+ *   `createAgentSession({ tools })` 的白名单收敛。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { BwrapRuntime } from "../bwrap/runtime.js";
+import type { FileToolset } from "../claude-code/files.js";
+import { registerSearchTools } from "../claude-code/search.js";
+import { registerSessionTools } from "../claude-code/session-tools.js";
+import { registerShellTools } from "../claude-code/shell.js";
+import { registerBashTool } from "../opencode/bash.js";
+import type { OpencodeFileToolset } from "../opencode/files.js";
+import { registerGlobTool } from "../opencode/glob.js";
+import { registerGrepTool } from "../opencode/grep.js";
+import { registerQuestionTool } from "../opencode/question.js";
+import { registerTodoTool } from "../opencode/todo.js";
+import type { RequestPolicy } from "./request-policy.js";
+import type { ToolBus } from "./tool-bus.js";
+import type { FileIoToolset } from "./tools-config.js";
+
+export interface ToolUnitDeps {
+  pi: ExtensionAPI;
+  bus: ToolBus;
+  policy: RequestPolicy;
+  runtime: BwrapRuntime;
+  /** 选中工具集的文件工具（Read/Edit/Write 或 read/edit/write）。 */
+  fileToolset: FileToolset | OpencodeFileToolset;
+}
+
+export interface ToolUnit {
+  /** 该单元提供的工具名，用于子代理按声明挑选单元。 */
+  tools: readonly string[];
+  register(deps: ToolUnitDeps): void;
+}
+
+export const TOOL_UNITS: Record<FileIoToolset, readonly ToolUnit[]> = {
+  "claude-code": [
+    {
+      tools: ["Read", "Edit", "Write"],
+      register: ({ bus, fileToolset }) => fileToolset.register(bus),
+    },
+    {
+      tools: ["Glob", "Grep"],
+      register: ({ bus, pi }) => registerSearchTools(bus, pi),
+    },
+    {
+      tools: ["Bash"],
+      register: ({ bus, pi, runtime }) => registerShellTools(bus, pi, runtime),
+    },
+    {
+      tools: ["TodoWrite", "AskUserQuestion"],
+      register: ({ bus, pi }) => registerSessionTools(bus, pi),
+    },
+  ],
+  opencode: [
+    {
+      tools: ["read", "edit", "write"],
+      register: ({ bus, fileToolset }) => fileToolset.register(bus),
+    },
+    {
+      tools: ["glob", "grep"],
+      register: ({ bus }) => {
+        registerGlobTool(bus);
+        registerGrepTool(bus);
+      },
+    },
+    {
+      tools: ["bash"],
+      register: ({ bus, pi, runtime }) => registerBashTool(bus, pi, runtime),
+    },
+    {
+      tools: ["todowrite", "question"],
+      register: ({ bus }) => {
+        registerTodoTool(bus);
+        registerQuestionTool(bus);
+      },
+    },
+  ],
+};
+
+/** 子代理声明的工具名对应哪一套文件 IO 工具集：出现哪一套的名字就用哪一套。 */
+export function toolsetsForToolNames(toolNames: readonly string[]): FileIoToolset | undefined {
+  const declared = new Set(toolNames);
+  for (const kind of ["claude-code", "opencode"] as const) {
+    if (TOOL_UNITS[kind].some((unit) => unit.tools.some((name) => declared.has(name)))) {
+      return kind;
+    }
+  }
+  return undefined;
+}
+
+/** 挑出覆盖到声明工具名的单元。 */
+export function unitsForToolNames(kind: FileIoToolset, toolNames: readonly string[]): ToolUnit[] {
+  const declared = new Set(toolNames);
+  return TOOL_UNITS[kind].filter((unit) => unit.tools.some((name) => declared.has(name)));
+}