@trim21/personal-pi-extensions 0.0.303 → 0.0.305

package/package.json

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

package/src/aft/ast-edit.ts

@@ -16,9 +16,10 @@ import { Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { requireAbsolutePath } from "../claude-code/common.js";
+import { type ToolPendant } from "../lib/pendant.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import { callAftTool } from "./bridge.js";
-import { type AftToolContext, bridgeFor } from "./tools.js";
+import { type AftToolContext, bridgeFor, buildPendantMarkdown } from "./tools.js";
 
 // ── 纯函数（可测） ──────────────────────────────────────────────────────────
 
@@ -256,9 +257,20 @@ export function registerAstEditTool(pi: ExtensionAPI, ctx: AftToolContext): void
 
       // 第三步：AFT 原子写盘（备份 + 格式化 + undo），结果由 Rust 格式化返回。
       const { text } = await callAftTool(bridgeFor(ctx), "edit", rawArgs, extCtx);
+      const files = previewFiles.map((f) => f.file || filePath);
       return {
         content: [{ type: "text", text }],
-        details: { input: params, files: previewFiles.map((f) => f.file || filePath) },
+        details: {
+          files,
+          pendant: {
+            markdown: buildPendantMarkdown({
+              title: "ast_edit",
+              input: params,
+              output: text,
+            }),
+            expanded: true,
+          } satisfies ToolPendant,
+        },
       };
     },
   });

package/src/aft/imports.ts

@@ -0,0 +1,125 @@
+/**
+ * aft_import —— language-aware import add / remove。
+ *
+ * 参数经 bridge.toolCall 以 agent 工具名 "import" 分派，Rust 侧 subc 翻译层
+ * 按 op 转成内部命令（add_import / remove_import）。
+ * 与 aft_refactor 相同：不支持 preview，写保护为路径级审批。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { type ToolPendant } from "../lib/pendant.js";
+import { guardWriteAccess } from "../lib/write-guard.js";
+import { callAftTool } from "./bridge.js";
+import { type AftToolContext, bridgeFor, buildPendantMarkdown, resolvePathArg } from "./tools.js";
+
+const IMPORT_OPS = ["add", "remove"] as const;
+const VALIDATE_LEVELS = ["syntax", "full"] as const;
+
+const ImportParams = Type.Object(
+  {
+    op: Type.Union(
+      IMPORT_OPS.map((op) => Type.Literal(op)),
+      { description: "import 操作" },
+    ),
+    path: Type.String({ description: "目标文件路径（绝对或相对项目根）" }),
+    module: Type.Optional(
+      Type.String({ description: "模块路径（add/remove 必填），如 'react'、'./utils'" }),
+    ),
+    names: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          "要添加的具名导入，用语言原生的具名导入写法，支持按名 `as` 别名，如 ['useState']、Solidity ['ERC20', 'IERC20 as IToken']",
+      }),
+    ),
+    default_import: Type.Optional(Type.String({ description: "默认导入名（仅 ES），如 'React'" })),
+    namespace: Type.Optional(
+      Type.String({
+        description:
+          "命名空间绑定：`import * as ns from 'mod'`（ES）、`* as N from \"./X.sol\"`（Solidity）",
+      }),
+    ),
+    alias: Type.Optional(
+      Type.String({ description: '整模块别名。Solidity：`import "./X.sol" as X`' }),
+    ),
+    modifiers: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          "语句级修饰符，按语言校验：Java/C# 'static'、C# 'global'/'unsafe'、Java/Kotlin/Scala 'wildcard'、Swift '@testable'",
+      }),
+    ),
+    import_kind: Type.Optional(
+      Type.String({
+        description:
+          "符号类导入：PHP 'function'/'const'、Swift 'struct'/'class'/'enum'、Scala 'given'",
+      }),
+    ),
+    remove_name: Type.Optional(
+      Type.String({ description: "要移除的具名导入；缺省移除整个 import" }),
+    ),
+    type_only: Type.Optional(Type.Boolean({ description: "仅类型导入（仅 TS）" })),
+    validate: Type.Optional(
+      Type.Union(
+        VALIDATE_LEVELS.map((level) => Type.Literal(level)),
+        {
+          description: "编辑后校验级别（默认 syntax）",
+        },
+      ),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export function registerImportTool(pi: ExtensionAPI, ctx: AftToolContext): void {
+  pi.registerTool({
+    name: "aft_import",
+    label: "aft_import",
+    description: [
+      "语言感知的 import 管理：add / remove。",
+      "支持 TS, JS, TSX, Python, Rust, Go, Solidity, Java, C#, PHP, Kotlin, Scala, Swift, Ruby, Lua, C, C++, Perl, Vue。",
+      "add：添加默认/具名/命名空间导入；remove：移除具名导入或整个 import。",
+      "import 排序整理交给 lint（如 import/order + --fix），本工具不负责。",
+    ].join("\n"),
+    promptSnippet: "Language-aware import add / remove",
+    parameters: ImportParams,
+    async execute(_id, params, _signal, _onUpdate, extCtx) {
+      if (params.module === undefined || params.module.trim() === "") {
+        throw new Error(`'module' is required for '${params.op}' op`);
+      }
+
+      const filePath = resolvePathArg(extCtx.cwd, params.path);
+      await guardWriteAccess(extCtx, { toolName: "aft_import", absolutePath: filePath });
+
+      const rawArgs: Record<string, unknown> = { op: params.op, path: filePath };
+      if (params.module !== undefined && params.module.trim() !== "") {
+        rawArgs.module = params.module;
+      }
+      if (params.names !== undefined) rawArgs.names = params.names;
+      if (params.default_import !== undefined) rawArgs.defaultImport = params.default_import;
+      if (params.namespace !== undefined) rawArgs.namespace = params.namespace;
+      if (params.alias !== undefined) rawArgs.alias = params.alias;
+      if (params.modifiers !== undefined) rawArgs.modifiers = params.modifiers;
+      if (params.import_kind !== undefined) rawArgs.importKind = params.import_kind;
+      if (params.remove_name !== undefined) rawArgs.removeName = params.remove_name;
+      if (params.type_only !== undefined) rawArgs.typeOnly = params.type_only;
+      if (params.validate !== undefined) rawArgs.validate = params.validate;
+
+      const { text } = await callAftTool(bridgeFor(ctx), "import", rawArgs, extCtx);
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          files: [filePath],
+          pendant: {
+            markdown: buildPendantMarkdown({
+              title: "aft_import",
+              input: params,
+              output: text,
+            }),
+            expanded: true,
+          } satisfies ToolPendant,
+        },
+      };
+    },
+  });
+}

package/src/aft/index.ts

@@ -1,12 +1,14 @@
 /**
  * AFT 扩展入口：感知工具（aft_outline / aft_zoom / aft_callgraph / aft_search）
- * + ast_edit（符号级编辑，套用本仓库写保护机制）。
+ * + ast_edit（符号级编辑，套用本仓库写保护机制）+ aft_refactor / aft_import
+ * （workspace-wide 重构与 import 管理，路径级写保护）。
  *
  * 感知工具只读，不触碰本仓库自己的 read/write/edit/bash 工具及其安全机制
  * （bwrap 沙箱、write-guard、reads 记账）。aft_search 仅当用户级
  * aft.jsonc 开启 semantic_search 时注册（本地语义索引需 ONNX 运行时，
  * 内网默认关闭）。ast_edit 是写工具：用 AFT 的 preview 计算 diff，落盘走
- * 本仓库的 write-guard + reads 记账 + 写管线。
+ * 本仓库的 write-guard + reads 记账 + 写管线。aft_refactor / aft_import 的
+ * Rust 命令不支持 preview，写保护退化为路径级审批。
  *
  * 二进制缺失或 pool 创建失败时降级：不注册任何工具并在 session 开始时报
  * 一次错，而不是让每个工具调用失败。
@@ -21,6 +23,8 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerAstEditTool } from "./ast-edit.js";
 import { type AftPool, createAftPool, shutdownAftPool } from "./bridge.js";
 import { loadAftConfig } from "./config.js";
+import { registerImportTool } from "./imports.js";
+import { registerRefactorTool } from "./refactor.js";
 import {
   registerCallgraphTool,
   registerOutlineTool,
@@ -52,6 +56,8 @@ export default async function aftReadTools(pi: ExtensionAPI): Promise<void> {
   registerZoomTool(pi, toolCtx);
   registerCallgraphTool(pi, toolCtx);
   registerAstEditTool(pi, toolCtx);
+  registerRefactorTool(pi, toolCtx);
+  registerImportTool(pi, toolCtx);
   if (cfg.semanticSearch) {
     registerSearchTool(pi, toolCtx);
   }

package/src/aft/refactor.ts

@@ -0,0 +1,144 @@
+/**
+ * aft_refactor —— workspace-wide refactoring（move / extract / inline）。
+ *
+ * 参数经 bridge.toolCall 以 agent 工具名 "refactor" 分派，Rust 侧 subc 翻译层
+ * 按 op 转成内部命令（move_symbol / extract_function / inline_symbol）。
+ * 与 ast_edit 不同，这些命令不支持 preview：写保护退化为路径级审批
+ * （workspace 内自动放行，外部路径经 write-guard 确认，无 diff 预览）。
+ */
+
+import { coerceOptionalInt } from "@cortexkit/aft-bridge";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { type ToolPendant } from "../lib/pendant.js";
+import { guardWriteAccess } from "../lib/write-guard.js";
+import { callAftTool } from "./bridge.js";
+import { type AftToolContext, bridgeFor, buildPendantMarkdown, resolvePathArg } from "./tools.js";
+
+const REFACTOR_OPS = ["move", "extract", "inline"] as const;
+
+function requireField(value: unknown, name: string, op: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`'${name}' is required for '${op}' op`);
+  }
+}
+
+const RefactorParams = Type.Object(
+  {
+    op: Type.Union(
+      REFACTOR_OPS.map((op) => Type.Literal(op)),
+      { description: "重构操作" },
+    ),
+    path: Type.String({
+      description: "源文件路径（绝对或相对项目根；move 为符号当前所在文件）",
+    }),
+    symbol: Type.Optional(Type.String({ description: "符号名（move / inline 必填）" })),
+    destination: Type.Optional(Type.String({ description: "目标文件（move 必填）" })),
+    scope: Type.Optional(Type.String({ description: "move 消歧作用域" })),
+    name: Type.Optional(Type.String({ description: "新函数名（extract 必填）" })),
+    start_line: Type.Optional(
+      Type.Union([Type.Number(), Type.String()], {
+        description: "extract 起始行（1 起，必填）",
+      }),
+    ),
+    end_line: Type.Optional(
+      Type.Union([Type.Number(), Type.String()], {
+        description: "extract 结束行（含，必填）",
+      }),
+    ),
+    call_site_line: Type.Optional(
+      Type.Union([Type.Number(), Type.String()], {
+        description: "inline 调用点行号（1 起，必填）",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export function registerRefactorTool(pi: ExtensionAPI, ctx: AftToolContext): void {
+  pi.registerTool({
+    name: "aft_refactor",
+    label: "aft_refactor",
+    description: [
+      "workspace-wide 重构：更新跨文件的 import 与引用。",
+      "move：把顶层符号（非嵌套函数/类方法）移到另一文件，全 workspace 重写 import；执行前自动创建 checkpoint。",
+      "extract：把行区间抽成新函数（TS/JS/TSX、Python）。",
+      "inline：把调用点替换为函数体。",
+      "move / rename 整个文件用 aft_move（OS 层操作，不更新引用）；移动代码符号用本工具 op=move。",
+    ].join("\n"),
+    promptSnippet: "Workspace-wide symbol move / function extraction / inlining",
+    parameters: RefactorParams,
+    async execute(_id, params, _signal, _onUpdate, extCtx) {
+      const startLine = coerceOptionalInt(
+        params.start_line,
+        "start_line",
+        1,
+        Number.MAX_SAFE_INTEGER,
+      );
+      const endLine = coerceOptionalInt(params.end_line, "end_line", 1, Number.MAX_SAFE_INTEGER);
+      const callSiteLine = coerceOptionalInt(
+        params.call_site_line,
+        "call_site_line",
+        1,
+        Number.MAX_SAFE_INTEGER,
+      );
+
+      if (params.op === "move") {
+        requireField(params.symbol, "symbol", "move");
+        requireField(params.destination, "destination", "move");
+      } else if (params.op === "extract") {
+        requireField(params.name, "name", "extract");
+        if (startLine === undefined) throw new Error("'start_line' is required for 'extract' op");
+        if (endLine === undefined) throw new Error("'end_line' is required for 'extract' op");
+      } else {
+        requireField(params.symbol, "symbol", "inline");
+        if (callSiteLine === undefined) {
+          throw new Error("'call_site_line' is required for 'inline' op");
+        }
+      }
+
+      const filePath = resolvePathArg(extCtx.cwd, params.path);
+      const destination =
+        params.destination === undefined || params.destination.trim() === ""
+          ? undefined
+          : resolvePathArg(extCtx.cwd, params.destination);
+
+      const targets = destination === undefined ? [filePath] : [filePath, destination];
+      for (const target of targets) {
+        await guardWriteAccess(extCtx, { toolName: "aft_refactor", absolutePath: target });
+      }
+
+      const rawArgs: Record<string, unknown> = { op: params.op, path: filePath };
+      if (params.symbol !== undefined && params.symbol.trim() !== "") {
+        rawArgs.symbol = params.symbol;
+      }
+      if (destination !== undefined) rawArgs.destination = destination;
+      if (params.scope !== undefined && params.scope.trim() !== "") {
+        rawArgs.scope = params.scope;
+      }
+      if (params.name !== undefined && params.name.trim() !== "") {
+        rawArgs.name = params.name;
+      }
+      if (startLine !== undefined) rawArgs.startLine = startLine;
+      if (endLine !== undefined) rawArgs.endLine = endLine;
+      if (callSiteLine !== undefined) rawArgs.callSiteLine = callSiteLine;
+
+      const { text } = await callAftTool(bridgeFor(ctx), "refactor", rawArgs, extCtx);
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          files: targets,
+          pendant: {
+            markdown: buildPendantMarkdown({
+              title: "aft_refactor",
+              input: params,
+              output: text,
+            }),
+            expanded: true,
+          } satisfies ToolPendant,
+        },
+      };
+    },
+  });
+}

package/src/aft/tools.ts

@@ -20,6 +20,7 @@ import {
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
+import { type ToolPendant } from "../lib/pendant.js";
 import { callAftTool, SEMANTIC_INDEX_WAIT_TIMEOUT_MS } from "./bridge.js";
 
 /** 解析 `~` 前缀与相对路径（相对 session cwd）。URL 与绝对路径原样返回。 */
@@ -40,6 +41,32 @@ export function bridgeFor(ctx: AftToolContext): AftProjectTransport {
   return ctx.pool.getBridge(ctx.cwd);
 }
 
+/** 人类视角的调用记录：input params + 与 LLM 相同的输出结果。 */
+export function buildPendantMarkdown(params: {
+  title: string;
+  input: unknown;
+  output: string;
+  truncated?: boolean;
+}): string {
+  const lines = [
+    `## ${params.title}`,
+    "",
+    "**Input**",
+    "",
+    "```json",
+    JSON.stringify(params.input, null, 2),
+    "```",
+    "",
+    "**Output**",
+    "",
+    params.output,
+  ];
+  if (params.truncated) {
+    lines.push("", "_输出已截断_");
+  }
+  return lines.join("\n").trim();
+}
+
 const OutlineParams = Type.Object(
   {
     target: Type.String({
@@ -88,9 +115,21 @@ export function registerOutlineTool(pi: ExtensionAPI, ctx: AftToolContext): void
       if (params.includeTests !== undefined) rawArgs.includeTests = params.includeTests;
 
       const { text, response } = await callAftTool(bridgeFor(ctx), "outline", rawArgs, extCtx);
+      const truncated = response.truncated === true;
       return {
         content: [{ type: "text", text }],
-        details: { input: params, truncated: response.truncated === true },
+        details: {
+          truncated,
+          pendant: {
+            markdown: buildPendantMarkdown({
+              title: "aft_outline",
+              input: params,
+              output: text,
+              truncated,
+            }),
+            expanded: true,
+          } satisfies ToolPendant,
+        },
       };
     },
   });
@@ -193,9 +232,21 @@ export function registerZoomTool(pi: ExtensionAPI, ctx: AftToolContext): void {
       if (coerceBoolean(params.callgraph)) rawArgs.callgraph = true;
 
       const { text, response } = await callAftTool(bridgeFor(ctx), "zoom", rawArgs, extCtx);
+      const truncated = response.truncated === true;
       return {
         content: [{ type: "text", text }],
-        details: { input: params, truncated: response.truncated === true },
+        details: {
+          truncated,
+          pendant: {
+            markdown: buildPendantMarkdown({
+              title: "aft_zoom",
+              input: params,
+              output: text,
+              truncated,
+            }),
+            expanded: true,
+          } satisfies ToolPendant,
+        },
       };
     },
   });
@@ -291,9 +342,21 @@ export function registerCallgraphTool(pi: ExtensionAPI, ctx: AftToolContext): vo
         formatCallgraphSections(params.op, response, PLAIN_CALLGRAPH_THEME, {
           includeUnresolved: coerceBoolean(params.includeUnresolved),
         }).join("\n");
+      const truncated = response.truncated === true;
       return {
         content: [{ type: "text", text: out }],
-        details: { input: params, truncated: response.truncated === true },
+        details: {
+          truncated,
+          pendant: {
+            markdown: buildPendantMarkdown({
+              title: "aft_callgraph",
+              input: params,
+              output: out,
+              truncated,
+            }),
+            expanded: true,
+          } satisfies ToolPendant,
+        },
       };
     },
   });
@@ -354,9 +417,21 @@ export function registerSearchTool(pi: ExtensionAPI, ctx: AftToolContext): void
         transportTimeoutMs: SEMANTIC_INDEX_WAIT_TIMEOUT_MS + 60_000,
         keepBridgeOnTimeout: true,
       });
+      const truncated = response.truncated === true;
       return {
         content: [{ type: "text", text }],
-        details: { input: params, truncated: response.truncated === true },
+        details: {
+          truncated,
+          pendant: {
+            markdown: buildPendantMarkdown({
+              title: "aft_search",
+              input: params,
+              output: text,
+              truncated,
+            }),
+            expanded: true,
+          } satisfies ToolPendant,
+        },
       };
     },
   });

package/src/lib/write-guard.ts

@@ -108,7 +108,11 @@ export interface WriteGuardOptions {
   toolName: string;
   /** The resolved absolute target path (caller has already parsed its args). */
   absolutePath: string;
-  change: PendingChange;
+  /**
+   * 待审批的变更内容；缺省时（如 aft_refactor/aft_import 无 preview diff）
+   * 审批对话框不展示 diff 预览，仅按路径审批。
+   */
+  change?: PendingChange;
 }
 
 /**
@@ -137,7 +141,7 @@ export async function guardWriteAccess(
   }
 
   while (true) {
-    const diffPreview = await buildDiffPreview(absolutePath, opts.change);
+    const diffPreview = opts.change ? await buildDiffPreview(absolutePath, opts.change) : undefined;
     const title =
       `Model requests write access outside workspace:\n\n` +
       `  Tool:  ${opts.toolName}\n` +