@snack-kit/porygon 0.4.0 → 0.5.0

package/README.md

@@ -54,6 +54,7 @@ const porygon = createPorygon({
     timeoutMs: 300_000,
     maxTurns: 50,
     appendSystemPrompt: "请简洁回答",
+    disallowedTools: ["WebSearch"],  // 全局禁用的工具
   },
   proxy: { url: "http://proxy:8080", noProxy: "localhost" },
 });
@@ -65,7 +66,7 @@ const porygon = createPorygon({
 |------|------|------|
 | `defaultBackend` | `string` | 默认后端名称 |
 | `backends` | `Record<string, BackendConfig>` | 各后端独立配置 |
-| `defaults` | `{ appendSystemPrompt?, timeoutMs?, maxTurns? }` | 全局默认参数 |
+| `defaults` | `{ appendSystemPrompt?, timeoutMs?, maxTurns?, disallowedTools? }` | 全局默认参数 |
 | `proxy` | `{ url: string, noProxy?: string }` | 全局代理（后端级 proxy 优先） |
 
 **BackendConfig 字段：**
@@ -80,6 +81,7 @@ const porygon = createPorygon({
 | `appendSystemPrompt` | `string` | 追加系统提示词 |
 | `proxy` | `ProxyConfig` | 后端专属代理 |
 | `cwd` | `string` | 工作目录 |
+| `disallowedTools` | `string[]` | 禁止使用的工具黑名单（后端级） |
 | `options` | `Record<string, unknown>` | 透传给后端的额外选项（向后兼容，推荐使用上方的显式字段） |
 
 ---
@@ -157,8 +159,8 @@ system → stream_chunk* → assistant(turnComplete) → tool_use* → ... → r
 | `resume` | `string` | 否 | 恢复会话的 session ID |
 | `systemPrompt` | `string` | 否 | 系统提示词（替换模式，设置后 appendSystemPrompt 失效） |
 | `appendSystemPrompt` | `string` | 否 | 系统提示词（追加模式，与 config 中的追加内容合并） |
-| `allowedTools` | `string[]` | 否 | 允许的工具白名单 |
-| `disallowedTools` | `string[]` | 否 | 禁用的工具黑名单 |
+| `onlyTools` | `string[]` | 否 | 仅允许使用的工具白名单（内部通过 getTools() 差集转为黑名单，与 disallowedTools 互斥，优先级更高） |
+| `disallowedTools` | `string[]` | 否 | 禁止使用的工具黑名单 |
 | `maxTurns` | `number` | 否 | 最大对话轮次 |
 | `timeoutMs` | `number` | 否 | 超时毫秒数 |
 | `cwd` | `string` | 否 | 工作目录 |
@@ -174,6 +176,8 @@ system → stream_chunk* → assistant(turnComplete) → tool_use* → ... → r
 | `timeoutMs` | request > defaults |
 | `maxTurns` | request > defaults |
 | `cwd` | request > backendConfig |
+| `onlyTools` | 通过 getTools() 获取全量列表，差集计算转为 disallowedTools（设置后忽略 disallowedTools） |
+| `disallowedTools` | defaults + backendConfig + request 三层叠加去重 |
 | `appendSystemPrompt` | defaults + backendConfig + request 三层追加拼接（换行分隔）。若 `systemPrompt` 已设置则忽略全部 append |
 
 ---
@@ -193,16 +197,32 @@ system → stream_chunk* → assistant(turnComplete) → tool_use* → ... → r
 
 ---
 
-### `porygon.checkBackend(backend): Promise<HealthCheckResult>`
+### `porygon.checkBackend(backend, options?): Promise<HealthCheckResult>`
 
-检查单个后端的健康状态。
+检查单个后端的健康状态。支持两种模式：
+
+- **轻量检测**（默认）：仅检查 CLI 是否存在 + 版本兼容性
+- **深度检测**（`deep: true`）：额外向模型发送一条测试消息，验证 Token/模型/配额是否真正可用
 
 ```ts
+// 轻量检测：仅检查 CLI 存在性和版本
 const result = await porygon.checkBackend("claude");
 // { available: true, version: "1.2.0", supported: true }
-// { available: false, error: "command not found" }
+
+// 深度检测：真实调用模型验证可用性
+const deep = await porygon.checkBackend("claude", { deep: true, model: "haiku" });
+// { available: true, version: "1.2.0", supported: true, modelVerified: true }
+// { available: true, version: "1.2.0", supported: true, modelVerified: false, warnings: ["模型验证失败: ..."] }
 ```
 
+**CheckBackendOptions：**
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `deep` | `boolean` | `false` | 启用深度检测，向模型发送测试消息 |
+| `model` | `string?` | 后端默认 | 深度检测使用的模型 |
+| `timeoutMs` | `number` | `15000` | 深度检测超时（毫秒） |
+
 **HealthCheckResult：**
 
 | 字段 | 类型 | 说明 |
@@ -212,6 +232,7 @@ const result = await porygon.checkBackend("claude");
 | `supported` | `boolean?` | 版本是否在测试范围内 |
 | `warnings` | `string[]?` | 兼容性警告 |
 | `error` | `string?` | 错误信息 |
+| `modelVerified` | `boolean?` | 深度检测时模型是否真正响应 |
 
 ---
 
@@ -350,6 +371,23 @@ const models = await porygon.listModels("claude");
 
 ---
 
+### `porygon.getTools(force?): Promise<string[]>`
+
+获取当前可用的工具列表。首次调用通过发起最小化对话（`maxTurns: 1`）从 `system` 事件中提取，结果会被缓存，后续调用直接返回缓存。
+
+```ts
+const tools = await porygon.getTools();
+console.log(tools);
+// ["Bash", "Read", "Edit", "Write", "Glob", "Grep", "mcp__xxx__yyy", ...]
+
+// 强制刷新缓存
+const fresh = await porygon.getTools(true);
+```
+
+> 仅 Claude 后端支持此能力，其他后端返回空数组。
+
+---
+
 ### `porygon.getCapabilities(backend?): AdapterCapabilities`
 
 获取后端能力声明。
@@ -422,7 +460,7 @@ porygon.on("health:degraded", (backend: string, warning: string) => {
 ```ts
 // 核心
 export { Porygon, createPorygon } from "@snack-kit/porygon";
-export type { PorygonEvents, HealthCheckResult } from "@snack-kit/porygon";
+export type { PorygonEvents, HealthCheckResult, CheckBackendOptions } from "@snack-kit/porygon";
 
 // 类型
 export type {
@@ -446,6 +484,9 @@ export {
 // 防护拦截器
 export { createInputGuard, createOutputGuard } from "@snack-kit/porygon";
 
+// 交互式会话
+export { InteractiveSession } from "@snack-kit/porygon";
+
 // 适配器（自定义扩展用）
 export { AbstractAgentAdapter, ClaudeAdapter, OpenCodeAdapter } from "@snack-kit/porygon";
 ```
@@ -499,13 +540,51 @@ const answer = await porygon.run({
 });
 ```
 
+### 工具控制
+
+```ts
+// 查询所有可用工具
+const tools = await porygon.getTools();
+console.log(tools); // ["Bash", "Read", "Edit", ...]
+
+// 黑名单：禁用危险工具
+await porygon.run({
+  prompt: "分析代码",
+  disallowedTools: ["Bash", "Edit", "Write"],
+});
+
+// 白名单：只允许只读工具（内部自动转为黑名单，getTools 结果有缓存）
+await porygon.run({
+  prompt: "阅读代码并回答",
+  onlyTools: ["Read", "Grep", "Glob"],
+});
+
+// 配置级黑名单：全局 + 后端级 + 请求级三层叠加
+const porygon = createPorygon({
+  defaults: { disallowedTools: ["WebSearch"] },
+  backends: {
+    claude: {
+      interactive: false,
+      disallowedTools: ["Bash"],
+    },
+  },
+});
+// 此时 disallowedTools = ["WebSearch", "Bash"]，无需每次请求重复传入
+```
+
+---
+
 ### 健康检查后选择可用后端
 
 ```ts
-// 检查单个后端
+// 轻量检查：CLI 存在性 + 版本
 const result = await porygon.checkBackend("claude");
 if (!result.available) console.error(result.error);
 
+// 深度检查：验证模型真正可用（Token/配额/模型名）
+const deep = await porygon.checkBackend("claude", { deep: true, model: "haiku" });
+if (deep.modelVerified) console.log("模型验证通过");
+
 // 批量检查所有后端
 const health = await porygon.healthCheck();
 const backend = health.claude?.available ? "claude" : "opencode";
@@ -551,6 +630,27 @@ npm run playground  # 启动 Playground
 
 ## Changelog
 
+### v0.5.0
+
+#### 新特性
+
+- **`porygon.getTools(force?)`** — 获取当前可用的工具列表（包括内置工具和 MCP 插件工具）。首次调用通过最小化对话获取并缓存，后续直接返回缓存，传入 `force: true` 强制刷新
+- **`IAgentAdapter.getTools?(force?)`** — 适配器接口新增可选方法，支持缓存与强制刷新
+- **`onlyTools`（请求参数）** — 仅允许使用的工具白名单，内部通过 `getTools()` 获取全量列表后差集计算转为 `disallowedTools`，工具缓存避免重复对话开销
+- **配置级工具黑名单** — `BackendConfig` 和 `defaults` 新增 `disallowedTools` 字段，支持全局或后端级统一禁用工具，三层叠加去重
+- **`checkBackend(backend, options?)` 深度检测模式** — 新增第二个参数 `CheckBackendOptions`，传入 `{ deep: true }` 时在基础 CLI/版本检查通过后，向模型发送一条极短测试消息（`maxTurns: 1`），验证 Token、模型、配额是否真正可用
+- **`CheckBackendOptions`** — 新增选项类型，支持 `deep`（启用深度检测）、`model`（指定验证模型）、`timeoutMs`（深度检测超时，默认 15s）
+- **`HealthCheckResult.modelVerified`** — 新增字段，深度检测时标识模型是否真正响应
+
+#### 破坏性变更
+
+- **`PromptRequest.allowedTools` 移除** — Claude CLI 的 `--allowedTools` 实际语义为"免确认"而非"限制范围"，已移除避免误用。替代方案：`onlyTools`（白名单，自动转黑名单）或 `disallowedTools`（黑名单）
+- **`porygon.session()` 返回类型变更** — 从 `InteractiveSession` 改为 `Promise<InteractiveSession>`，调用方需 `await`
+
+#### Bug Fixes
+
+- **Claude adapter 类型定义**: 修复 `ClaudeResultEvent` 缺少 `total_cost_usd` 字段导致的 TS2322 类型错误
+
 ### v0.4.0
 
 #### Bug Fixes

package/dist/index.cjs

@@ -134,6 +134,7 @@ var BackendConfigSchema = import_zod.z.object({
   apiKey: import_zod.z.string().optional(),
   interactive: import_zod.z.boolean().optional(),
   cliPath: import_zod.z.string().optional(),
+  disallowedTools: import_zod.z.array(import_zod.z.string()).optional(),
   options: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
 });
 var PorygonConfigSchema = import_zod.z.object({
@@ -142,7 +143,8 @@ var PorygonConfigSchema = import_zod.z.object({
   defaults: import_zod.z.object({
     appendSystemPrompt: import_zod.z.string().optional(),
     timeoutMs: import_zod.z.number().positive().optional(),
-    maxTurns: import_zod.z.number().int().positive().optional()
+    maxTurns: import_zod.z.number().int().positive().optional(),
+    disallowedTools: import_zod.z.array(import_zod.z.string()).optional()
   }).optional(),
   proxy: ProxyConfigSchema.optional()
 });
@@ -925,6 +927,8 @@ var CLAUDE_MODELS = [
 ];
 var ClaudeAdapter = class extends AbstractAgentAdapter {
   backend = "claude";
+  /** 工具列表缓存 */
+  cachedTools = null;
   /** CLI 命令名或路径 */
   get cliCommand() {
     return this.config?.cliPath ?? "claude";
@@ -1049,6 +1053,40 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
       this.processManager.removeEphemeral(sessionId);
     }
   }
+  /**
+   * 获取当前可用的工具列表。
+   * 首次调用通过发起最小化对话从 system 事件中提取 tools 字段，结果会被缓存。
+   * @param force 是否强制刷新缓存
+   */
+  async getTools(force) {
+    if (!force && this.cachedTools) {
+      return this.cachedTools;
+    }
+    const DEFAULT_TIMEOUT_MS2 = 15e3;
+    let tools = [];
+    for await (const message of this.query({
+      prompt: "hi",
+      maxTurns: 1,
+      timeoutMs: DEFAULT_TIMEOUT_MS2
+    })) {
+      const raw = message.raw;
+      if (message.type === "system" && raw?.tools) {
+        const rawTools = raw.tools;
+        if (Array.isArray(rawTools)) {
+          tools = rawTools.map((t) => {
+            if (typeof t === "string") return t;
+            if (typeof t === "object" && t !== null && "name" in t) {
+              return String(t.name);
+            }
+            return String(t);
+          });
+          break;
+        }
+      }
+    }
+    this.cachedTools = tools;
+    return tools;
+  }
   /**
    * 列出 Claude 会话
    * @param options 查询选项
@@ -1177,11 +1215,6 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
     if (appendPrompt) {
       args.push("--append-system-prompt", appendPrompt);
     }
-    if (request.allowedTools && request.allowedTools.length > 0) {
-      for (const tool of request.allowedTools) {
-        args.push("--allowedTools", tool);
-      }
-    }
     if (request.disallowedTools && request.disallowedTools.length > 0) {
       for (const tool of request.disallowedTools) {
         args.push("--disallowedTools", tool);
@@ -1195,16 +1228,17 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
     if (skipPerms) {
       args.push("--dangerously-skip-permissions");
     }
-    if (request.mcpServers) {
+    if (request.mcpServers && Object.keys(request.mcpServers).length > 0) {
+      const mcpConfig = {};
       for (const [name, config] of Object.entries(request.mcpServers)) {
-        const serverSpec = {
+        mcpConfig[name] = {
           command: config.command,
           ...config.args ? { args: config.args } : {},
           ...config.env ? { env: config.env } : {},
           ...config.url ? { url: config.url } : {}
         };
-        args.push("--mcp-server", `${name}=${JSON.stringify(serverSpec)}`);
       }
+      args.push("--mcp-config", JSON.stringify({ mcpServers: mcpConfig }));
     }
     return args;
   }
@@ -1879,7 +1913,7 @@ var Porygon = class extends import_node_events2.EventEmitter {
   async *query(request) {
     const adapter = this.getAdapter(request.backend);
     const backendName = adapter.backend;
-    const mergedRequest = this.mergeRequest(request, backendName);
+    const mergedRequest = await this.mergeRequest(request, backendName);
     const processedPrompt = await this.interceptors.processInput(
       mergedRequest.prompt,
       { backend: backendName, sessionId: mergedRequest.resume }
@@ -1921,10 +1955,10 @@ var Porygon = class extends import_node_events2.EventEmitter {
    * 创建交互式多轮对话会话。
    * 自动管理 sessionId 和 resume，对调用方透明。
    */
-  session(options) {
+  async session(options) {
     const backend = options?.backend ?? this.config.defaultBackend ?? "claude";
     const adapter = this.getAdapter(backend);
-    const merged = this.mergeRequest({ ...options, prompt: "" }, backend);
+    const merged = await this.mergeRequest({ ...options, prompt: "" }, backend);
     const { prompt: _, ...baseRequest } = merged;
     return new InteractiveSession(
       crypto.randomUUID(),
@@ -1932,6 +1966,16 @@ var Porygon = class extends import_node_events2.EventEmitter {
       baseRequest
     );
   }
+  /**
+   * 获取当前可用的工具列表。
+   * 首次调用通过发起最小化对话从 system 事件中提取工具清单，结果会被缓存。
+   * @param force 是否强制刷新缓存
+   */
+  async getTools(force) {
+    const adapter = this.getAdapter();
+    if (!adapter.getTools) return [];
+    return adapter.getTools(force);
+  }
   /**
    * 注册拦截器
    * @param direction 拦截方向
@@ -1958,8 +2002,9 @@ var Porygon = class extends import_node_events2.EventEmitter {
   /**
    * 检查单个后端的健康状态
    * @param backend 后端名称
+   * @param options 检测选项。传入 `{ deep: true }` 时会向模型发送一条测试消息验证可用性。
    */
-  async checkBackend(backend) {
+  async checkBackend(backend, options) {
     const adapter = this.getAdapter(backend);
     try {
       const available = await adapter.isAvailable();
@@ -1978,6 +2023,25 @@ var Porygon = class extends import_node_events2.EventEmitter {
       if (!compat.supported) {
         this.emit("health:degraded", backend, compat.warnings.join("; "));
       }
+      if (options?.deep) {
+        try {
+          const response = await this.run({
+            prompt: "Reply with exactly: ok",
+            backend,
+            model: options.model,
+            systemPrompt: "You are a health check probe. Reply with exactly one word: ok",
+            timeoutMs: options.timeoutMs ?? 15e3,
+            maxTurns: 1
+          });
+          result.modelVerified = typeof response === "string" && response.length > 0;
+        } catch (err) {
+          result.modelVerified = false;
+          result.warnings = [
+            ...result.warnings || [],
+            `\u6A21\u578B\u9A8C\u8BC1\u5931\u8D25: ${err instanceof Error ? err.message : String(err)}`
+          ];
+        }
+      }
       return result;
     } catch (err) {
       return {
@@ -2057,6 +2121,8 @@ var Porygon = class extends import_node_events2.EventEmitter {
    * - timeoutMs: request > defaults
    * - maxTurns: request > defaults
    * - cwd: request > backendConfig
+   * - disallowedTools: defaults + backendConfig + request 三层叠加去重
+   * - onlyTools: 通过 getTools() 获取全量列表，差集计算转为 disallowedTools（与 disallowedTools 互斥，onlyTools 优先）
    * - appendSystemPrompt: **追加模式** — defaults + backendConfig + request 三层拼接（换行分隔）
    *   但如果 request.systemPrompt 已设置（替换模式），则忽略所有 appendSystemPrompt
    *
@@ -2064,7 +2130,7 @@ var Porygon = class extends import_node_events2.EventEmitter {
    * @param backend 后端名称
    * @returns 合并后的请求
    */
-  mergeRequest(request, backend) {
+  async mergeRequest(request, backend) {
     const backendConfig = this.config.backends?.[backend];
     const defaults = this.config.defaults;
     const appendParts = [];
@@ -2077,12 +2143,28 @@ var Porygon = class extends import_node_events2.EventEmitter {
     if (request.appendSystemPrompt) {
       appendParts.push(request.appendSystemPrompt);
     }
+    let mergedDisallowedTools;
+    if (request.onlyTools) {
+      const adapter = this.getAdapter(backend);
+      const allTools = adapter.getTools ? await adapter.getTools() : [];
+      const allowSet = new Set(request.onlyTools);
+      const disallowed = allTools.filter((t) => !allowSet.has(t));
+      mergedDisallowedTools = disallowed.length > 0 ? disallowed : void 0;
+    } else {
+      const disallowParts = [
+        ...defaults?.disallowedTools ?? [],
+        ...backendConfig?.disallowedTools ?? [],
+        ...request.disallowedTools ?? []
+      ];
+      mergedDisallowedTools = disallowParts.length > 0 ? [...new Set(disallowParts)] : void 0;
+    }
     return {
       ...request,
       model: request.model ?? backendConfig?.model,
       timeoutMs: request.timeoutMs ?? defaults?.timeoutMs,
       maxTurns: request.maxTurns ?? defaults?.maxTurns,
       cwd: request.cwd ?? backendConfig?.cwd,
+      disallowedTools: mergedDisallowedTools,
       appendSystemPrompt: request.systemPrompt ? void 0 : appendParts.length > 0 ? appendParts.join("\n") : void 0
     };
   }