@snack-kit/porygon 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -23,6 +23,8 @@ interface BackendConfig {
     interactive?: boolean;
     /** CLI 可执行文件路径（如 Claude CLI 的自定义安装路径） */
     cliPath?: string;
+    /** 禁止使用的工具黑名单（后端级） */
+    disallowedTools?: string[];
     /** 透传给 CLI 的后端特定选项（向后兼容，推荐使用上方的显式字段） */
     options?: Record<string, unknown>;
 }
@@ -36,6 +38,8 @@ interface PorygonConfig {
         appendSystemPrompt?: string;
         timeoutMs?: number;
         maxTurns?: number;
+        /** 禁止使用的工具黑名单（全局默认） */
+        disallowedTools?: string[];
     };
     proxy?: ProxyConfig;
 }
@@ -63,7 +67,13 @@ interface PromptRequest {
     appendSystemPrompt?: string;
     model?: string;
     timeoutMs?: number;
-    allowedTools?: string[];
+    /**
+     * 仅允许使用的工具白名单。
+     * 运行时通过 getTools() 获取全量工具列表，差集计算后转为 disallowedTools 传递给 CLI。
+     * 与 disallowedTools 互斥，同时设置时 onlyTools 优先。
+     */
+    onlyTools?: string[];
+    /** 禁止使用的工具黑名单 */
     disallowedTools?: string[];
     mcpServers?: Record<string, McpServerConfig>;
     maxTurns?: number;
@@ -180,6 +190,8 @@ interface IAgentAdapter {
     /** 获取可用模型列表 */
     listModels(): Promise<ModelInfo[]>;
     abort(sessionId: string): void;
+    /** 获取当前可用的工具列表（可选实现，支持缓存） */
+    getTools?(force?: boolean): Promise<string[]>;
     /** 删除会话及其资源（可选实现） */
     deleteSession?(sessionId: string): Promise<void>;
     dispose(): Promise<void>;
@@ -250,6 +262,23 @@ interface HealthCheckResult {
     supported?: boolean;
     warnings?: string[];
     error?: string;
+    /** deep 模式下，模型是否真正响应 */
+    modelVerified?: boolean;
+}
+/**
+ * checkBackend 的选项
+ */
+interface CheckBackendOptions {
+    /**
+     * 启用深度检测：在基础 CLI/版本检查通过后，向模型发送一条极短测试消息，
+     * 验证 Token/模型/配额是否真正可用。
+     * 默认 false（仅做 CLI 存在性 + 版本检查）。
+     */
+    deep?: boolean;
+    /** deep 模式下使用的模型（可选，不传则用后端默认模型） */
+    model?: string;
+    /** deep 模式超时（毫秒），默认 15000 */
+    timeoutMs?: number;
 }
 /**
  * Porygon 事件类型定义
@@ -306,7 +335,13 @@ declare class Porygon extends EventEmitter {
      * 创建交互式多轮对话会话。
      * 自动管理 sessionId 和 resume，对调用方透明。
      */
-    session(options?: Omit<PromptRequest, "prompt">): InteractiveSession;
+    session(options?: Omit<PromptRequest, "prompt">): Promise<InteractiveSession>;
+    /**
+     * 获取当前可用的工具列表。
+     * 首次调用通过发起最小化对话从 system 事件中提取工具清单，结果会被缓存。
+     * @param force 是否强制刷新缓存
+     */
+    getTools(force?: boolean): Promise<string[]>;
     /**
      * 注册拦截器
      * @param direction 拦截方向
@@ -327,8 +362,9 @@ declare class Porygon extends EventEmitter {
     /**
      * 检查单个后端的健康状态
      * @param backend 后端名称
+     * @param options 检测选项。传入 `{ deep: true }` 时会向模型发送一条测试消息验证可用性。
      */
-    checkBackend(backend: string): Promise<HealthCheckResult>;
+    checkBackend(backend: string, options?: CheckBackendOptions): Promise<HealthCheckResult>;
     /**
      * 对所有已注册后端进行健康检查。
      * 返回扁平化结构，包含 version/supported/warnings 等字段。
@@ -365,6 +401,8 @@ declare class Porygon extends 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
      *
@@ -671,6 +709,8 @@ declare abstract class AbstractAgentAdapter implements IAgentAdapter {
  */
 declare class ClaudeAdapter extends AbstractAgentAdapter {
     readonly backend = "claude";
+    /** 工具列表缓存 */
+    private cachedTools;
     /** CLI 命令名或路径 */
     private get cliCommand();
     /**
@@ -690,6 +730,12 @@ declare class ClaudeAdapter extends AbstractAgentAdapter {
      * @param request 提示请求参数
      */
     query(request: PromptRequest): AsyncGenerator<AgentMessage>;
+    /**
+     * 获取当前可用的工具列表。
+     * 首次调用通过发起最小化对话从 system 事件中提取 tools 字段，结果会被缓存。
+     * @param force 是否强制刷新缓存
+     */
+    getTools(force?: boolean): Promise<string[]>;
     /**
      * 列出 Claude 会话
      * @param options 查询选项
@@ -809,4 +855,4 @@ declare class OpenCodeAdapter extends AbstractAgentAdapter {
     private getConfigPath;
 }
 
-export { AbstractAgentAdapter, type AdapterCapabilities, AdapterIncompatibleError, AdapterNotAvailableError, AdapterNotFoundError, type AgentAssistantMessage, type AgentErrorMessage, AgentExecutionError, type AgentMessage, type AgentResultMessage, type AgentStreamChunkMessage, type AgentSystemMessage, AgentTimeoutError, type AgentToolUseMessage, type BackendConfig, ClaudeAdapter, type CompatibilityResult, ConfigValidationError, type GuardAction, type GuardOptions, type HealthCheckResult, type IAgentAdapter, InteractiveSession, type InterceptorContext, type InterceptorDirection, type InterceptorFn, InterceptorRejectedError, type McpServerConfig, type ModelInfo, OpenCodeAdapter, Porygon, type PorygonConfig, PorygonError, type PorygonEvents, type PromptRequest, type ProxyConfig, type SessionInfo, type SessionListOptions, SessionNotFoundError, createInputGuard, createOutputGuard, createPorygon };
+export { AbstractAgentAdapter, type AdapterCapabilities, AdapterIncompatibleError, AdapterNotAvailableError, AdapterNotFoundError, type AgentAssistantMessage, type AgentErrorMessage, AgentExecutionError, type AgentMessage, type AgentResultMessage, type AgentStreamChunkMessage, type AgentSystemMessage, AgentTimeoutError, type AgentToolUseMessage, type BackendConfig, type CheckBackendOptions, ClaudeAdapter, type CompatibilityResult, ConfigValidationError, type GuardAction, type GuardOptions, type HealthCheckResult, type IAgentAdapter, InteractiveSession, type InterceptorContext, type InterceptorDirection, type InterceptorFn, InterceptorRejectedError, type McpServerConfig, type ModelInfo, OpenCodeAdapter, Porygon, type PorygonConfig, PorygonError, type PorygonEvents, type PromptRequest, type ProxyConfig, type SessionInfo, type SessionListOptions, SessionNotFoundError, createInputGuard, createOutputGuard, createPorygon };

package/dist/index.d.ts

@@ -23,6 +23,8 @@ interface BackendConfig {
     interactive?: boolean;
     /** CLI 可执行文件路径（如 Claude CLI 的自定义安装路径） */
     cliPath?: string;
+    /** 禁止使用的工具黑名单（后端级） */
+    disallowedTools?: string[];
     /** 透传给 CLI 的后端特定选项（向后兼容，推荐使用上方的显式字段） */
     options?: Record<string, unknown>;
 }
@@ -36,6 +38,8 @@ interface PorygonConfig {
         appendSystemPrompt?: string;
         timeoutMs?: number;
         maxTurns?: number;
+        /** 禁止使用的工具黑名单（全局默认） */
+        disallowedTools?: string[];
     };
     proxy?: ProxyConfig;
 }
@@ -63,7 +67,13 @@ interface PromptRequest {
     appendSystemPrompt?: string;
     model?: string;
     timeoutMs?: number;
-    allowedTools?: string[];
+    /**
+     * 仅允许使用的工具白名单。
+     * 运行时通过 getTools() 获取全量工具列表，差集计算后转为 disallowedTools 传递给 CLI。
+     * 与 disallowedTools 互斥，同时设置时 onlyTools 优先。
+     */
+    onlyTools?: string[];
+    /** 禁止使用的工具黑名单 */
     disallowedTools?: string[];
     mcpServers?: Record<string, McpServerConfig>;
     maxTurns?: number;
@@ -180,6 +190,8 @@ interface IAgentAdapter {
     /** 获取可用模型列表 */
     listModels(): Promise<ModelInfo[]>;
     abort(sessionId: string): void;
+    /** 获取当前可用的工具列表（可选实现，支持缓存） */
+    getTools?(force?: boolean): Promise<string[]>;
     /** 删除会话及其资源（可选实现） */
     deleteSession?(sessionId: string): Promise<void>;
     dispose(): Promise<void>;
@@ -250,6 +262,23 @@ interface HealthCheckResult {
     supported?: boolean;
     warnings?: string[];
     error?: string;
+    /** deep 模式下，模型是否真正响应 */
+    modelVerified?: boolean;
+}
+/**
+ * checkBackend 的选项
+ */
+interface CheckBackendOptions {
+    /**
+     * 启用深度检测：在基础 CLI/版本检查通过后，向模型发送一条极短测试消息，
+     * 验证 Token/模型/配额是否真正可用。
+     * 默认 false（仅做 CLI 存在性 + 版本检查）。
+     */
+    deep?: boolean;
+    /** deep 模式下使用的模型（可选，不传则用后端默认模型） */
+    model?: string;
+    /** deep 模式超时（毫秒），默认 15000 */
+    timeoutMs?: number;
 }
 /**
  * Porygon 事件类型定义
@@ -306,7 +335,13 @@ declare class Porygon extends EventEmitter {
      * 创建交互式多轮对话会话。
      * 自动管理 sessionId 和 resume，对调用方透明。
      */
-    session(options?: Omit<PromptRequest, "prompt">): InteractiveSession;
+    session(options?: Omit<PromptRequest, "prompt">): Promise<InteractiveSession>;
+    /**
+     * 获取当前可用的工具列表。
+     * 首次调用通过发起最小化对话从 system 事件中提取工具清单，结果会被缓存。
+     * @param force 是否强制刷新缓存
+     */
+    getTools(force?: boolean): Promise<string[]>;
     /**
      * 注册拦截器
      * @param direction 拦截方向
@@ -327,8 +362,9 @@ declare class Porygon extends EventEmitter {
     /**
      * 检查单个后端的健康状态
      * @param backend 后端名称
+     * @param options 检测选项。传入 `{ deep: true }` 时会向模型发送一条测试消息验证可用性。
      */
-    checkBackend(backend: string): Promise<HealthCheckResult>;
+    checkBackend(backend: string, options?: CheckBackendOptions): Promise<HealthCheckResult>;
     /**
      * 对所有已注册后端进行健康检查。
      * 返回扁平化结构，包含 version/supported/warnings 等字段。
@@ -365,6 +401,8 @@ declare class Porygon extends 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
      *
@@ -671,6 +709,8 @@ declare abstract class AbstractAgentAdapter implements IAgentAdapter {
  */
 declare class ClaudeAdapter extends AbstractAgentAdapter {
     readonly backend = "claude";
+    /** 工具列表缓存 */
+    private cachedTools;
     /** CLI 命令名或路径 */
     private get cliCommand();
     /**
@@ -690,6 +730,12 @@ declare class ClaudeAdapter extends AbstractAgentAdapter {
      * @param request 提示请求参数
      */
     query(request: PromptRequest): AsyncGenerator<AgentMessage>;
+    /**
+     * 获取当前可用的工具列表。
+     * 首次调用通过发起最小化对话从 system 事件中提取 tools 字段，结果会被缓存。
+     * @param force 是否强制刷新缓存
+     */
+    getTools(force?: boolean): Promise<string[]>;
     /**
      * 列出 Claude 会话
      * @param options 查询选项
@@ -809,4 +855,4 @@ declare class OpenCodeAdapter extends AbstractAgentAdapter {
     private getConfigPath;
 }
 
-export { AbstractAgentAdapter, type AdapterCapabilities, AdapterIncompatibleError, AdapterNotAvailableError, AdapterNotFoundError, type AgentAssistantMessage, type AgentErrorMessage, AgentExecutionError, type AgentMessage, type AgentResultMessage, type AgentStreamChunkMessage, type AgentSystemMessage, AgentTimeoutError, type AgentToolUseMessage, type BackendConfig, ClaudeAdapter, type CompatibilityResult, ConfigValidationError, type GuardAction, type GuardOptions, type HealthCheckResult, type IAgentAdapter, InteractiveSession, type InterceptorContext, type InterceptorDirection, type InterceptorFn, InterceptorRejectedError, type McpServerConfig, type ModelInfo, OpenCodeAdapter, Porygon, type PorygonConfig, PorygonError, type PorygonEvents, type PromptRequest, type ProxyConfig, type SessionInfo, type SessionListOptions, SessionNotFoundError, createInputGuard, createOutputGuard, createPorygon };
+export { AbstractAgentAdapter, type AdapterCapabilities, AdapterIncompatibleError, AdapterNotAvailableError, AdapterNotFoundError, type AgentAssistantMessage, type AgentErrorMessage, AgentExecutionError, type AgentMessage, type AgentResultMessage, type AgentStreamChunkMessage, type AgentSystemMessage, AgentTimeoutError, type AgentToolUseMessage, type BackendConfig, type CheckBackendOptions, ClaudeAdapter, type CompatibilityResult, ConfigValidationError, type GuardAction, type GuardOptions, type HealthCheckResult, type IAgentAdapter, InteractiveSession, type InterceptorContext, type InterceptorDirection, type InterceptorFn, InterceptorRejectedError, type McpServerConfig, type ModelInfo, OpenCodeAdapter, Porygon, type PorygonConfig, PorygonError, type PorygonEvents, type PromptRequest, type ProxyConfig, type SessionInfo, type SessionListOptions, SessionNotFoundError, createInputGuard, createOutputGuard, createPorygon };

package/dist/index.js

@@ -92,6 +92,7 @@ var BackendConfigSchema = z.object({
   apiKey: z.string().optional(),
   interactive: z.boolean().optional(),
   cliPath: z.string().optional(),
+  disallowedTools: z.array(z.string()).optional(),
   options: z.record(z.string(), z.unknown()).optional()
 });
 var PorygonConfigSchema = z.object({
@@ -100,7 +101,8 @@ var PorygonConfigSchema = z.object({
   defaults: z.object({
     appendSystemPrompt: z.string().optional(),
     timeoutMs: z.number().positive().optional(),
-    maxTurns: z.number().int().positive().optional()
+    maxTurns: z.number().int().positive().optional(),
+    disallowedTools: z.array(z.string()).optional()
   }).optional(),
   proxy: ProxyConfigSchema.optional()
 });
@@ -883,6 +885,8 @@ var CLAUDE_MODELS = [
 ];
 var ClaudeAdapter = class extends AbstractAgentAdapter {
   backend = "claude";
+  /** 工具列表缓存 */
+  cachedTools = null;
   /** CLI 命令名或路径 */
   get cliCommand() {
     return this.config?.cliPath ?? "claude";
@@ -1007,6 +1011,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 查询选项
@@ -1135,11 +1173,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);
@@ -1153,16 +1186,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;
   }
@@ -1837,7 +1871,7 @@ var Porygon = class extends EventEmitter2 {
   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 }
@@ -1879,10 +1913,10 @@ var Porygon = class extends EventEmitter2 {
    * 创建交互式多轮对话会话。
    * 自动管理 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(),
@@ -1890,6 +1924,16 @@ var Porygon = class extends EventEmitter2 {
       baseRequest
     );
   }
+  /**
+   * 获取当前可用的工具列表。
+   * 首次调用通过发起最小化对话从 system 事件中提取工具清单，结果会被缓存。
+   * @param force 是否强制刷新缓存
+   */
+  async getTools(force) {
+    const adapter = this.getAdapter();
+    if (!adapter.getTools) return [];
+    return adapter.getTools(force);
+  }
   /**
    * 注册拦截器
    * @param direction 拦截方向
@@ -1916,8 +1960,9 @@ var Porygon = class extends EventEmitter2 {
   /**
    * 检查单个后端的健康状态
    * @param backend 后端名称
+   * @param options 检测选项。传入 `{ deep: true }` 时会向模型发送一条测试消息验证可用性。
    */
-  async checkBackend(backend) {
+  async checkBackend(backend, options) {
     const adapter = this.getAdapter(backend);
     try {
       const available = await adapter.isAvailable();
@@ -1936,6 +1981,25 @@ var Porygon = class extends EventEmitter2 {
       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 {
@@ -2015,6 +2079,8 @@ var Porygon = class extends EventEmitter2 {
    * - 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
    *
@@ -2022,7 +2088,7 @@ var Porygon = class extends EventEmitter2 {
    * @param backend 后端名称
    * @returns 合并后的请求
    */
-  mergeRequest(request, backend) {
+  async mergeRequest(request, backend) {
     const backendConfig = this.config.backends?.[backend];
     const defaults = this.config.defaults;
     const appendParts = [];
@@ -2035,12 +2101,28 @@ var Porygon = class extends EventEmitter2 {
     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
     };
   }