@trim21/personal-pi-extensions 0.1.691 → 0.1.694

package/README.md

@@ -93,6 +93,8 @@
     // 工具可用性规则：条目是工具名模式，或 { tools, models }
     "disabledTools": ["talk-*", { "tools": ["web_*"], "models": ["gpt-*"] }],
     "enabledTools": [{ "tools": ["web_search"], "models": ["glm-*"] }],
+    // 只进 codemode、不交给模型的工具（须声明结构化输出才会生效）
+    "codemodeOnlyTools": [{ "tools": ["read-github-*"], "models": ["deepseek-*"] }],
   },
 }
 ```
@@ -101,6 +103,12 @@
 条目只在当前模型命中时参与判定。未配置该 section 时用 `fileIo: "claude-code"` 且不
 禁用任何工具。
 
+`codemodeOnlyTools` 把工具从模型可见列表移进 `codemode`：命中它、未被禁用、且声明了
+`structuredSchema` 的工具只登记在工具总线上、不交给 pi，模型只能在 codemode 脚本里用
+`call(...)` 调用它（`codemode` 的工具描述里仍有它的参数与返回类型声明）。没有结构化输出
+的工具进不了 codemode，因此会被忽略、保持直接可用，并在会话启动时给出一条 warning——
+想真正移除工具用 `disabledTools`。
+
 **判定时机是每个会话启动**：pi 在启动 / `/new` / `resume` / `/fork` / `/reload` 时重建
 扩展，注册就发生在 `session_start` 里（模型在扩展加载期读不到），因此新会话按自己的
 模型重新判定；**同一会话内 `/model` 切换不会改变工具集合**，换模型请开新会话。

package/package.json

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

package/src/codemode/tool.ts

@@ -7,6 +7,8 @@
  *
  * 可调用集合：总线上实际注册的、**声明了 `structuredSchema`** 的工具，执行时再与 active
  * 列表求交——pi 自己的 `defaultTools` / `--tools` / 子代理白名单的排除因此同样生效。
+ * codemode-only 工具（`codemodeOnlyTools` 命中且声明了 schema，因而没有交给 pi 注册）不在
+ * active 列表里是常态，直接进集合、不求交。
  *
  * wasm 在注册这个工具时编译一次（`createCodemodeSandbox`），worker 复用编译结果。
  */
@@ -36,11 +38,15 @@ export const CODEMODE_TOOL_NAME = "codemode";
  *
  * 脚本拿到的返回值必须有确定的形状——只给文本的工具在脚本里既没法当数据用（得解析文本），
  * 也没有返回类型能写进声明。用「有没有结构化输出」当门槛，这条规则自己会维持一致：不给工具
- * 加 schema 就不进集合，不需要维护一份会随工具增减而漂移的黑名单。因此下列工具天然不在集合
- * 里，理由各自成立：`codemode` 自身与 `spawn-agent`（没有 schema）、文件读写工具（脚本用
- * `fs.read` / `fs.write`，不重复一套为 LLM 上下文设计的行号/锚点语义）、搜索工具（脚本用
- * `call("Bash", { command })` 跑 `rg`，退出码可用、能拼管道）、`lsp-rename`（写工具）以及
- * talk / 会话工具（会把执行时间交给外部输入）。
+ * 加 schema 就不进集合，不需要维护一份会随工具增减而漂移的黑名单。
+ *
+ * active 求交只作用于直接工具；命中了 `codemodeOnlyTools` 的工具（声明了 schema、因而没有
+ * 交给 pi 注册）不在 active 列表里是常态，直接进集合。
+ *
+ * 下列工具天然不在集合里，理由各自成立：`codemode` 自身与 `spawn-agent`（没有 schema）、
+ * 文件读写工具（脚本用 `fs.read` / `fs.write`，不重复一套为 LLM 上下文设计的行号/锚点
+ * 语义）、搜索工具（脚本用 `call("Bash", { command })` 跑 `rg`，退出码可用、能拼管道）、
+ * `lsp-rename`（写工具）以及 talk / 会话工具（会把执行时间交给外部输入）。
  */
 /** 估计 token 用的字符数（与 pi 一致）。 */
 const CHARS_PER_TOKEN = 4;
@@ -82,7 +88,10 @@ function collectTools(bus: ToolBus, allowed: Set<string> | undefined): CallableT
   return bus
     .list()
     .filter((definition) => definition.structuredSchema !== undefined)
-    .filter((definition) => allowed === undefined || allowed.has(definition.name))
+    .filter(
+      (definition) =>
+        definition.codemodeOnly === true || allowed === undefined || allowed.has(definition.name),
+    )
     .map((definition) => ({
       name: definition.name,
       description: definition.description,
@@ -99,6 +108,8 @@ function buildDescription(tools: readonly CallableTool[]): string {
     "  and a failing tool rejects with a `CallFailedError` you can catch.",
     "- Only what the script passes to `text(value)` / `console.log(...)` and its `return` value enter",
     "  this conversation; nested calls and their results stay out of it.",
+    "- Pass only necessary content to `text(value)`: print the content the next step needs, not whole",
+    "  tool results or data you will not use.",
     "- `store.set(key, value)`, `store.get(key)` and `store.list()` are a small key/value store that",
     "  persists across codemode calls in this session; `store.set(key, undefined)` removes a key.",
     "- The sandbox has no file system, network, timers or Node APIs: calling tools is its only",
@@ -263,6 +274,7 @@ export function createCodemodeTools(pi: ExtensionAPI): CodemodeTools {
         promptSnippet: "codemode: run JavaScript that calls tools in parallel",
         promptGuidelines: [
           "Use codemode to batch or chain several tool calls, or to filter large tool output down to what matters, instead of issuing many individual tool calls.",
+          "Keep codemode output minimal: pass only the content the next step needs to `text(value)`, not whole tool results or data you will not use.",
         ],
         parameters: Type.Object({
           code: Type.String({

package/src/index.ts

@@ -126,6 +126,9 @@ export default function personalExtensions(pi: ExtensionAPI): void {
       codemode.register(bus, { policy: services.policy, reads: fileToolset.reads }),
     );
 
+    // 注册期的可诊断问题（例如 codemode-only 命中但没有结构化输出的工具）与其它警告一起上报。
+    warnings.push(...registration.diagnostics());
+
     for (const warning of warnings) {
       ctx.ui.notify(warning, "warning");
     }

package/src/lib/tool-bus.ts

@@ -3,7 +3,9 @@
  * （按名执行，不必绕回模型）。
  *
  * - `register`：按配置过滤（被禁用时跳过并返回 false）后交给 `pi.registerTool`，
- *   并保留通过的定义供 `list` / `get` 查询。
+ *   并保留通过的定义供 `list` / `get` 查询。命中 codemode-only 且声明了
+ *   `structuredSchema` 的工具只保留在总线上、不交给 pi（标 `codemodeOnly: true`）；
+ *   命中但没有 schema 的工具照常注册，并在 `diagnostics` 里留一条说明。
  * - `executeTool`：先用工具自身的参数 schema 校验参数，再调用定义的 `execute`；
  *   参数校验失败与工具抛出的异常都归一化成错误结果返回，不向调用方抛异常。
  *
@@ -85,9 +87,10 @@ export interface ExecuteToolOptions {
   toolCallId?: string;
 }
 
-/** 注册后的定义：多出的 `structuredSchema` 供 codemode 渲染脚本侧返回类型。 */
+/** 注册后的定义：多出的 `structuredSchema` 供 codemode 渲染脚本侧返回类型，`codemodeOnly` 标出未交给 pi 的只读脚本工具。 */
 export type RegisteredToolDefinition = ToolDefinition<TSchema, unknown, unknown> & {
   structuredSchema?: TSchema;
+  codemodeOnly?: boolean;
 };
 
 export interface ToolBus {
@@ -99,6 +102,8 @@ export interface ToolBus {
   list(): readonly RegisteredToolDefinition[];
   /** 所有尝试注册过的工具名（含被禁用而跳过的），用于校验配置里的模式是否有效。 */
   declaredNames(): readonly string[];
+  /** 注册期发现的可诊断问题（去重），由调用方在能提示用户时上报。 */
+  diagnostics(): readonly string[];
   get(name: string): RegisteredToolDefinition | undefined;
   /** 按名执行一个已注册工具；任何失败都以 `isError` 结果返回，不抛异常。 */
   executeTool(
@@ -111,6 +116,8 @@ export interface ToolBus {
 export interface ToolBusOptions {
   /** 返回 true 表示该工具被禁用、不注册。 */
   isDisabled?: (name: string) => boolean;
+  /** 返回 true 表示该工具应只进 codemode（是否真的如此还要看它有没有声明 `structuredSchema`）。 */
+  isCodemodeOnly?: (name: string) => boolean;
 }
 
 function errorResult(text: string): ToolExecutionResult {
@@ -180,6 +187,7 @@ function checkStructuredResult(
 export function createToolBus(pi: ExtensionAPI, options: ToolBusOptions = {}): ToolBus {
   const registered = new Map<string, RegisteredToolDefinition>();
   const declared = new Set<string>();
+  const diagnostics = new Set<string>();
   let callCounter = 0;
 
   return {
@@ -188,6 +196,22 @@ export function createToolBus(pi: ExtensionAPI, options: ToolBusOptions = {}): T
       if (options.isDisabled?.(definition.name) === true) {
         return false;
       }
+      if (options.isCodemodeOnly?.(definition.name) === true) {
+        // schema 门控：进不了 codemode 的工具照常直接注册，只留一条可诊断的说明，
+        // 避免配置把工具从模型面前静默移除（见 openspec design.md）。
+        if ((definition as { structuredSchema?: unknown }).structuredSchema === undefined) {
+          diagnostics.add(
+            `personalExtensions.codemodeOnlyTools: tool "${definition.name}" declares no structuredSchema; it stays directly available.`,
+          );
+        } else {
+          const codemodeStored = {
+            ...(definition as unknown as RegisteredToolDefinition),
+            codemodeOnly: true,
+          };
+          registered.set(codemodeStored.name, codemodeStored);
+          return true;
+        }
+      }
       const stored = definition as unknown as RegisteredToolDefinition;
       pi.registerTool(stored);
       registered.set(stored.name, stored);
@@ -202,6 +226,10 @@ export function createToolBus(pi: ExtensionAPI, options: ToolBusOptions = {}): T
       return [...declared];
     },
 
+    diagnostics() {
+      return [...diagnostics];
+    },
+
     get(name) {
       return registered.get(name);
     },

package/src/lib/tool-registration.ts

@@ -41,6 +41,8 @@ export interface ToolRegistration {
   onSessionStart(register: (bus: ToolBus, ctx: ExtensionContext) => void | Promise<void>): void;
   /** 哪些配置模式没命中过任何工具（在注册完成后调用）。 */
   unmatchedPatterns(): UnmatchedPattern[];
+  /** 注册期发现的可诊断问题（去重），与 unmatchedPatterns 一样在注册完成后上报。 */
+  diagnostics(): readonly string[];
 }
 
 /**
@@ -62,6 +64,7 @@ export function createToolRegistration(pi: ExtensionAPI, settingsPath?: string):
     // 每次注册都按当前模型重新判定：工具在 session_start 里注册，模型由下面
     // 的 handler 更新，二者在同一个会话内保持一致。
     isDisabled: (name) => resolveToolAvailability(config, model).isDisabled(name),
+    isCodemodeOnly: (name) => resolveToolAvailability(config, model).isCodemodeOnly(name),
   });
 
   pi.on("session_start", (_event, ctx) => {
@@ -79,5 +82,8 @@ export function createToolRegistration(pi: ExtensionAPI, settingsPath?: string):
     unmatchedPatterns() {
       return resolveToolAvailability(config, model).unmatchedPatterns(bus.declaredNames());
     },
+    diagnostics() {
+      return bus.diagnostics();
+    },
   };
 }

package/src/lib/tools-config.ts

@@ -7,7 +7,8 @@
  *     "fileIo": "claude-code",
  *     "fileIoByModel": [{ "models": ["glm-*"], "fileIo": "opencode" }],
  *     "disabledTools": ["talk-*", { "tools": ["web_*"], "models": ["gpt-*"] }],
- *     "enabledTools": [{ "tools": ["web_search"], "models": ["glm-*"] }]
+ *     "enabledTools": [{ "tools": ["web_search"], "models": ["glm-*"] }],
+ *     "codemodeOnlyTools": [{ "tools": ["read-github-*"], "models": ["glm-*"] }]
  *   }
  * }
  * ```
@@ -15,6 +16,9 @@
  * 工具名与模型名都用 minimatch 通配模式匹配；模型名同时试 `model.id` 与
  * `provider/model` 两种写法。带 `models` 的条目只在当前模型命中时才参与判定。
  * 非法字段/条目被忽略并产出警告，不影响其余配置生效。
+ *
+ * `codemodeOnlyTools` 只表示曝光方式：命中它的工具由总线决定是否按 codemode-only
+ * 注册（还要看工具有没有声明 `structuredSchema`，见 `tool-bus.ts`）。
  */
 
 import { readFileSync } from "node:fs";
@@ -45,7 +49,7 @@ const toolRuleSchema = Type.Object({
 
 export type FileIoToolset = "claude-code" | "opencode";
 
-export type ToolRuleField = "disabledTools" | "enabledTools";
+export type ToolRuleField = "disabledTools" | "enabledTools" | "codemodeOnlyTools";
 
 export interface FileIoByModelEntry {
   models: readonly string[];
@@ -65,6 +69,8 @@ export interface ToolsConfig {
   fileIoByModel: readonly FileIoByModelEntry[];
   disabledTools: readonly ToolPatternRule[];
   enabledTools: readonly ToolPatternRule[];
+  /** 命中且声明了 `structuredSchema` 的工具只进 codemode、不交给 pi。 */
+  codemodeOnlyTools: readonly ToolPatternRule[];
   /** 解析阶段发现的问题，由调用方在能提示用户时上报。 */
   warnings: readonly string[];
 }
@@ -82,6 +88,8 @@ export interface UnmatchedPattern {
 export interface ToolAvailability {
   /** 该工具名是否被禁用（命中 disabledTools 且未命中 enabledTools）。 */
   isDisabled(name: string): boolean;
+  /** 该工具名是否命中 codemodeOnlyTools（是否真的按 codemode-only 注册还要看它有没有结构化输出）。 */
+  isCodemodeOnly(name: string): boolean;
   /** 哪些模式没匹配到任何工具（含被规则禁用的工具）。 */
   unmatchedPatterns(declaredNames: readonly string[]): UnmatchedPattern[];
 }
@@ -165,6 +173,7 @@ export function parseToolsConfig(section: unknown, source = "personalExtensions"
       fileIoByModel: [],
       disabledTools: [],
       enabledTools: [],
+      codemodeOnlyTools: [],
       warnings,
     };
   }
@@ -175,6 +184,7 @@ export function parseToolsConfig(section: unknown, source = "personalExtensions"
       fileIoByModel: [],
       disabledTools: [],
       enabledTools: [],
+      codemodeOnlyTools: [],
       warnings,
     };
   }
@@ -184,6 +194,11 @@ export function parseToolsConfig(section: unknown, source = "personalExtensions"
     fileIoByModel: parseFileIoByModel(section.fileIoByModel, `${source}.fileIoByModel`, warnings),
     disabledTools: parseToolRules(section.disabledTools, `${source}.disabledTools`, warnings),
     enabledTools: parseToolRules(section.enabledTools, `${source}.enabledTools`, warnings),
+    codemodeOnlyTools: parseToolRules(
+      section.codemodeOnlyTools,
+      `${source}.codemodeOnlyTools`,
+      warnings,
+    ),
     warnings,
   };
 }
@@ -258,9 +273,13 @@ export function resolveToolAvailability(
       return config.enabledTools.every((rule) => !ruleMatches(rule, name, model));
     },
 
+    isCodemodeOnly(name) {
+      return config.codemodeOnlyTools.some((rule) => ruleMatches(rule, name, model));
+    },
+
     unmatchedPatterns(declaredNames) {
       const unmatched: UnmatchedPattern[] = [];
-      for (const field of ["disabledTools", "enabledTools"] as const) {
+      for (const field of ["disabledTools", "enabledTools", "codemodeOnlyTools"] as const) {
         for (const rule of config[field]) {
           for (const pattern of rule.tools) {
             if (declaredNames.every((name) => !matchesPattern(pattern, name))) {