@snack-kit/porygon 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -15,7 +15,15 @@ interface BackendConfig {
     appendSystemPrompt?: string;
     proxy?: ProxyConfig;
     cwd?: string;
-    /** 透传给 CLI 的后端特定选项 */
+    /** 远程服务地址（OpenCode serve 模式） */
+    serverUrl?: string;
+    /** API Key 认证 */
+    apiKey?: string;
+    /** 是否为交互模式，false 时 Claude 会添加 --dangerously-skip-permissions */
+    interactive?: boolean;
+    /** CLI 可执行文件路径（如 Claude CLI 的自定义安装路径） */
+    cliPath?: string;
+    /** 透传给 CLI 的后端特定选项（向后兼容，推荐使用上方的显式字段） */
     options?: Record<string, unknown>;
 }
 /**
@@ -84,6 +92,13 @@ interface AgentSystemMessage extends BaseAgentMessage {
 interface AgentAssistantMessage extends BaseAgentMessage {
     type: "assistant";
     text: string;
+    /**
+     * 标记此消息为一个 turn 的完整文本汇总。
+     * 当为 true 时，text 内容与之前发出的 stream_chunk 消息完全重复，
+     * 调用方如果已通过 stream_chunk 累加文本，应忽略此消息的 text 以避免重复。
+     * run() 和拦截器仍会使用此消息。
+     */
+    turnComplete?: boolean;
 }
 interface AgentToolUseMessage extends BaseAgentMessage {
     type: "tool_use";
@@ -114,6 +129,12 @@ interface AgentErrorMessage extends BaseAgentMessage {
  */
 interface AdapterCapabilities {
     features: Set<"streaming" | "session-resume" | "system-prompt" | "tool-restriction" | "mcp" | "subagents" | "worktree" | "budget-limit" | "serve-mode">;
+    /**
+     * 流式输出模式：
+     * - 'delta': 后端原生产生增量 stream_chunk 事件（如 OpenCode）
+     * - 'chunked': 适配器将完整 assistant 消息拆分为 stream_chunk + assistant（如 Claude）
+     */
+    streamingMode: "delta" | "chunked";
     outputFormats: string[];
     testedVersionRange: string;
 }
@@ -159,6 +180,8 @@ interface IAgentAdapter {
     /** 获取可用模型列表 */
     listModels(): Promise<ModelInfo[]>;
     abort(sessionId: string): void;
+    /** 删除会话及其资源（可选实现） */
+    deleteSession?(sessionId: string): Promise<void>;
     dispose(): Promise<void>;
 }
 /**
@@ -186,6 +209,16 @@ interface InterceptorContext {
  */
 type InterceptorFn = (text: string, context: InterceptorContext) => string | boolean | undefined | Promise<string | boolean | undefined>;
 
+/**
+ * 健康检查结果（扁平化结构）
+ */
+interface HealthCheckResult {
+    available: boolean;
+    version?: string;
+    supported?: boolean;
+    warnings?: string[];
+    error?: string;
+}
 /**
  * Porygon 事件类型定义
  */
@@ -255,13 +288,15 @@ declare class Porygon extends EventEmitter {
      */
     listModels(backend?: string): Promise<ModelInfo[]>;
     /**
-     * 对所有已注册后端进行健康检查
+     * 检查单个后端的健康状态
+     * @param backend 后端名称
      */
-    healthCheck(): Promise<Record<string, {
-        available: boolean;
-        compatibility: CompatibilityResult | null;
-        error?: string;
-    }>>;
+    checkBackend(backend: string): Promise<HealthCheckResult>;
+    /**
+     * 对所有已注册后端进行健康检查。
+     * 返回扁平化结构，包含 version/supported/warnings 等字段。
+     */
+    healthCheck(): Promise<Record<string, HealthCheckResult>>;
     /**
      * 读取或更新后端设置
      * @param backend 后端名称
@@ -286,7 +321,16 @@ declare class Porygon extends EventEmitter {
      */
     dispose(): Promise<void>;
     /**
-     * 合并请求参数与配置默认值
+     * 合并请求参数与配置默认值。
+     *
+     * 合并策略：
+     * - model: request > backendConfig > 不设置（后端使用自身默认值）
+     * - timeoutMs: request > defaults
+     * - maxTurns: request > defaults
+     * - cwd: request > backendConfig
+     * - appendSystemPrompt: **追加模式** — defaults + backendConfig + request 三层拼接（换行分隔）
+     *   但如果 request.systemPrompt 已设置（替换模式），则忽略所有 appendSystemPrompt
+     *
      * @param request 原始请求
      * @param backend 后端名称
      * @returns 合并后的请求
@@ -588,6 +632,8 @@ declare abstract class AbstractAgentAdapter implements IAgentAdapter {
  */
 declare class ClaudeAdapter extends AbstractAgentAdapter {
     readonly backend = "claude";
+    /** CLI 命令名或路径 */
+    private get cliCommand();
     /**
      * 检查 Claude CLI 是否可用
      */
@@ -646,11 +692,18 @@ declare class OpenCodeAdapter extends AbstractAgentAdapter {
     readonly backend = "opencode";
     private apiClient;
     private servePort;
+    /** 远程服务器 URL（提供时跳过自启 serve） */
+    private remoteServerUrl?;
+    /** API Key（用于 Basic Auth） */
+    private apiKey?;
     /**
      * @param processManager 进程管理器实例
-     * @param servePort 可选的 serve 服务端口
+     * @param config 可选的后端配置
+     *   - serverUrl: 远程 OpenCode 服务地址，提供时跳过自启 serve
+     *   - apiKey: API Key，用于 Basic Auth 认证
+     *   - options.servePort: 本地 serve 端口（仅自启模式）
      */
-    constructor(processManager: ProcessManager, servePort?: number);
+    constructor(processManager: ProcessManager, config?: BackendConfig);
     /**
      * 检查 opencode 命令是否可用
      */
@@ -712,4 +765,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 IAgentAdapter, 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, ClaudeAdapter, type CompatibilityResult, ConfigValidationError, type GuardAction, type GuardOptions, type HealthCheckResult, type IAgentAdapter, 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

@@ -88,6 +88,10 @@ var BackendConfigSchema = z.object({
   appendSystemPrompt: z.string().optional(),
   proxy: ProxyConfigSchema.optional(),
   cwd: z.string().optional(),
+  serverUrl: z.string().optional(),
+  apiKey: z.string().optional(),
+  interactive: z.boolean().optional(),
+  cliPath: z.string().optional(),
   options: z.record(z.string(), z.unknown()).optional()
 });
 var PorygonConfigSchema = z.object({
@@ -780,15 +784,16 @@ function isResultEvent(event) {
 // src/adapters/claude/message-mapper.ts
 function mapClaudeEvent(event, sessionId) {
   const timestamp = Date.now();
-  const baseFields = { timestamp, sessionId, raw: event };
+  const resolvedSessionId = event.session_id ?? sessionId;
+  const baseFields = { timestamp, sessionId: resolvedSessionId, raw: event };
   if (isSystemEvent(event)) {
-    return {
+    return [{
       ...baseFields,
       type: "system",
       model: event.model,
       tools: event.tools,
       cwd: event.cwd
-    };
+    }];
   }
   if (isAssistantEvent(event)) {
     const content = event.message.content;
@@ -797,16 +802,16 @@ function mapClaudeEvent(event, sessionId) {
   if (isStreamEvent(event)) {
     const delta = event.event.delta;
     if (delta?.type === "text_delta" && delta.text) {
-      return {
+      return [{
         ...baseFields,
         type: "stream_chunk",
         text: delta.text
-      };
+      }];
     }
-    return null;
+    return [];
   }
   if (isResultEvent(event)) {
-    return {
+    return [{
       ...baseFields,
       type: "result",
       text: event.result,
@@ -814,38 +819,52 @@ function mapClaudeEvent(event, sessionId) {
       durationMs: event.duration_ms,
       inputTokens: event.input_tokens,
       outputTokens: event.output_tokens
-    };
+    }];
   }
-  return null;
+  return [];
 }
 function mapAssistantContent(blocks, baseFields) {
-  if (!blocks || blocks.length === 0) return null;
+  if (!blocks || blocks.length === 0) return [];
+  const messages = [];
   const textParts = [];
-  let firstToolUse = null;
   for (const block of blocks) {
     if (block.type === "text" && block.text) {
       textParts.push(block.text);
-    }
-    if (block.type === "tool_use" && !firstToolUse) {
-      firstToolUse = { name: block.name, input: block.input };
+      messages.push({
+        ...baseFields,
+        type: "stream_chunk",
+        text: block.text
+      });
     }
   }
   if (textParts.length > 0) {
-    return {
+    messages.push({
       ...baseFields,
       type: "assistant",
-      text: textParts.join("\n")
-    };
+      text: textParts.join("\n"),
+      turnComplete: true
+    });
   }
-  if (firstToolUse) {
-    return {
-      ...baseFields,
-      type: "tool_use",
-      toolName: firstToolUse.name,
-      input: firstToolUse.input
-    };
+  for (const block of blocks) {
+    if (block.type === "tool_use") {
+      messages.push({
+        ...baseFields,
+        type: "tool_use",
+        toolName: block.name,
+        input: block.input
+      });
+    }
+    if (block.type === "tool_result") {
+      messages.push({
+        ...baseFields,
+        type: "tool_use",
+        toolName: block.tool_use_id,
+        input: {},
+        output: block.content
+      });
+    }
   }
-  return null;
+  return messages;
 }
 
 // src/adapters/claude/index.ts
@@ -857,6 +876,10 @@ var CLAUDE_MODELS = [
 ];
 var ClaudeAdapter = class extends AbstractAgentAdapter {
   backend = "claude";
+  /** CLI 命令名或路径 */
+  get cliCommand() {
+    return this.config?.cliPath ?? "claude";
+  }
   /**
    * 检查 Claude CLI 是否可用
    */
@@ -865,7 +888,7 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
       const proc = new EphemeralProcess();
       const result = await proc.execute({
         command: "which",
-        args: ["claude"]
+        args: [this.cliCommand]
       });
       return result.exitCode === 0;
     } catch {
@@ -878,7 +901,7 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
   async getVersion() {
     const proc = new EphemeralProcess();
     const result = await proc.execute({
-      command: "claude",
+      command: this.cliCommand,
       args: ["--version"]
     });
     if (result.exitCode !== 0) {
@@ -905,6 +928,7 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
         "subagents",
         "worktree"
       ]),
+      streamingMode: "chunked",
       outputFormats: ["text", "json", "stream-json"],
       testedVersionRange: ">=1.0.0"
     };
@@ -936,13 +960,13 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
         }
       }
       const streamOptions = {
-        command: "claude",
+        command: this.cliCommand,
         args,
         ...cwd ? { cwd } : {},
         env: cleanEnv,
         timeoutMs: request.timeoutMs
       };
-      const cmdStr = ["claude", ...args.map((a) => /[\s"']/.test(a) ? JSON.stringify(a) : a)].join(" ");
+      const cmdStr = [this.cliCommand, ...args.map((a) => /[\s"']/.test(a) ? JSON.stringify(a) : a)].join(" ");
       const debugCmd = cwd ? `cd ${JSON.stringify(cwd)} && ${cmdStr}` : cmdStr;
       yield {
         type: "system",
@@ -963,8 +987,8 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
         } catch {
           continue;
         }
-        const message = mapClaudeEvent(parsed, sessionId);
-        if (message) {
+        const messages = mapClaudeEvent(parsed, sessionId);
+        for (const message of messages) {
           yield message;
         }
       }
@@ -984,7 +1008,7 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
       args.push("--limit", String(options.limit));
     }
     const result = await proc.execute({
-      command: "claude",
+      command: this.cliCommand,
       args,
       cwd: options?.cwd
     });
@@ -1108,6 +1132,11 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
     if (request.maxTurns !== void 0) {
       args.push("--max-turns", String(request.maxTurns));
     }
+    const interactive = this.config?.interactive;
+    const skipPerms = interactive === false || request.backendOptions?.dangerouslySkipPermissions || this.config?.options?.dangerouslySkipPermissions;
+    if (skipPerms) {
+      args.push("--dangerously-skip-permissions");
+    }
     if (request.mcpServers) {
       for (const [name, config] of Object.entries(request.mcpServers)) {
         const serverSpec = {
@@ -1144,11 +1173,14 @@ var OpenCodeApiError = class extends Error {
 var DEFAULT_TIMEOUT_MS = 3e4;
 var OpenCodeApiClient = class {
   baseUrl;
+  apiKey;
   /**
    * @param baseUrl opencode serve 服务的基础 URL，例如 http://localhost:39393
+   * @param apiKey 可选的 API Key，用于 Basic Auth 认证（username: opencode, password: apiKey）
    */
-  constructor(baseUrl) {
+  constructor(baseUrl, apiKey) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
   }
   /**
    * 创建新会话
@@ -1206,7 +1238,8 @@ var OpenCodeApiClient = class {
       method: "GET",
       headers: {
         Accept: "text/event-stream",
-        "Cache-Control": "no-cache"
+        "Cache-Control": "no-cache",
+        ...this.buildAuthHeaders()
       },
       signal: abortSignal
     });
@@ -1257,6 +1290,7 @@ var OpenCodeApiClient = class {
       const timer = setTimeout(() => controller.abort(), 5e3);
       const response = await fetch(`${this.baseUrl}/api/sessions`, {
         method: "GET",
+        headers: this.buildAuthHeaders(),
         signal: controller.signal
       });
       clearTimeout(timer);
@@ -1294,6 +1328,17 @@ var OpenCodeApiClient = class {
    * @param init fetch 请求选项
    * @returns 解析后的 JSON 响应
    */
+  /**
+   * 构建包含认证信息的请求 headers
+   */
+  buildAuthHeaders() {
+    const headers = {};
+    if (this.apiKey) {
+      const credentials = Buffer.from(`opencode:${this.apiKey}`).toString("base64");
+      headers["Authorization"] = `Basic ${credentials}`;
+    }
+    return headers;
+  }
   async request(path, init) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
@@ -1302,6 +1347,7 @@ var OpenCodeApiClient = class {
         ...init,
         headers: {
           "Content-Type": "application/json",
+          ...this.buildAuthHeaders(),
           ...init.headers
         },
         signal: controller.signal
@@ -1395,18 +1441,36 @@ var OpenCodeAdapter = class extends AbstractAgentAdapter {
   backend = "opencode";
   apiClient = null;
   servePort;
+  /** 远程服务器 URL（提供时跳过自启 serve） */
+  remoteServerUrl;
+  /** API Key（用于 Basic Auth） */
+  apiKey;
   /**
    * @param processManager 进程管理器实例
-   * @param servePort 可选的 serve 服务端口
+   * @param config 可选的后端配置
+   *   - serverUrl: 远程 OpenCode 服务地址，提供时跳过自启 serve
+   *   - apiKey: API Key，用于 Basic Auth 认证
+   *   - options.servePort: 本地 serve 端口（仅自启模式）
    */
-  constructor(processManager, servePort) {
-    super(processManager);
-    this.servePort = servePort ?? DEFAULT_SERVE_PORT;
+  constructor(processManager, config) {
+    super(processManager, config);
+    const opts = config?.options ?? {};
+    this.remoteServerUrl = config?.serverUrl ?? opts.serverUrl;
+    this.apiKey = config?.apiKey ?? opts.apiKey;
+    this.servePort = opts.servePort ?? DEFAULT_SERVE_PORT;
   }
   /**
    * 检查 opencode 命令是否可用
    */
   async isAvailable() {
+    if (this.remoteServerUrl) {
+      try {
+        const client = new OpenCodeApiClient(this.remoteServerUrl, this.apiKey);
+        return await client.healthCheck();
+      } catch {
+        return false;
+      }
+    }
     try {
       const proc = new EphemeralProcess();
       const result = await proc.execute({
@@ -1445,6 +1509,7 @@ var OpenCodeAdapter = class extends AbstractAgentAdapter {
         "system-prompt",
         "serve-mode"
       ]),
+      streamingMode: "delta",
       outputFormats: ["text"],
       testedVersionRange: TESTED_VERSION_RANGE
     };
@@ -1582,8 +1647,20 @@ var OpenCodeAdapter = class extends AbstractAgentAdapter {
       const healthy = await this.apiClient.healthCheck();
       if (healthy) return this.apiClient;
     }
+    if (this.remoteServerUrl) {
+      const client2 = new OpenCodeApiClient(this.remoteServerUrl, this.apiKey);
+      const healthy = await client2.healthCheck();
+      if (!healthy) {
+        throw new Error(
+          `\u65E0\u6CD5\u8FDE\u63A5\u8FDC\u7A0B OpenCode \u670D\u52A1: ${this.remoteServerUrl}`
+        );
+      }
+      this.apiClient = client2;
+      return client2;
+    }
     const client = new OpenCodeApiClient(
-      `http://localhost:${this.servePort}`
+      `http://localhost:${this.servePort}`,
+      this.apiKey
     );
     const alreadyRunning = await client.healthCheck();
     if (alreadyRunning) {
@@ -1661,7 +1738,12 @@ var Porygon = class extends EventEmitter2 {
     };
     const claudeAdapter = new ClaudeAdapter(this.processManager, mergedClaudeConfig);
     this.registerAdapter(claudeAdapter);
-    const opencodeAdapter = new OpenCodeAdapter(this.processManager);
+    const opencodeConfig = this.config.backends?.["opencode"];
+    const mergedOpencodeConfig = {
+      ...opencodeConfig,
+      proxy: opencodeConfig?.proxy ?? this.config.proxy
+    };
+    const opencodeAdapter = new OpenCodeAdapter(this.processManager, mergedOpencodeConfig);
     this.registerAdapter(opencodeAdapter);
   }
   /**
@@ -1753,29 +1835,45 @@ var Porygon = class extends EventEmitter2 {
     return this.getAdapter(backend).listModels();
   }
   /**
-   * 对所有已注册后端进行健康检查
+   * 检查单个后端的健康状态
+   * @param backend 后端名称
    */
-  async healthCheck() {
-    const entries = Array.from(this.adapters.entries());
-    const checks = entries.map(async ([name, adapter]) => {
-      try {
-        const available = await adapter.isAvailable();
-        let compatibility = null;
-        if (available) {
-          compatibility = await adapter.checkCompatibility();
-          if (!compatibility.supported) {
-            this.emit(
-              "health:degraded",
-              name,
-              compatibility.warnings.join("; ")
-            );
-          }
-        }
-        return [name, { available, compatibility }];
-      } catch (err) {
-        const errorMsg = err instanceof Error ? err.message : String(err);
-        return [name, { available: false, compatibility: null, error: errorMsg }];
+  async checkBackend(backend) {
+    const adapter = this.getAdapter(backend);
+    try {
+      const available = await adapter.isAvailable();
+      if (!available) {
+        return { available: false };
+      }
+      const compat = await adapter.checkCompatibility();
+      const result = {
+        available: true,
+        version: compat.version,
+        supported: compat.supported
+      };
+      if (compat.warnings.length > 0) {
+        result.warnings = compat.warnings;
+      }
+      if (!compat.supported) {
+        this.emit("health:degraded", backend, compat.warnings.join("; "));
       }
+      return result;
+    } catch (err) {
+      return {
+        available: false,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  /**
+   * 对所有已注册后端进行健康检查。
+   * 返回扁平化结构，包含 version/supported/warnings 等字段。
+   */
+  async healthCheck() {
+    const entries = Array.from(this.adapters.keys());
+    const checks = entries.map(async (name) => {
+      const result = await this.checkBackend(name);
+      return [name, result];
     });
     const settled = await Promise.allSettled(checks);
     const results = {};
@@ -1831,7 +1929,16 @@ var Porygon = class extends EventEmitter2 {
     this.sessionManager.clearCache();
   }
   /**
-   * 合并请求参数与配置默认值
+   * 合并请求参数与配置默认值。
+   *
+   * 合并策略：
+   * - model: request > backendConfig > 不设置（后端使用自身默认值）
+   * - timeoutMs: request > defaults
+   * - maxTurns: request > defaults
+   * - cwd: request > backendConfig
+   * - appendSystemPrompt: **追加模式** — defaults + backendConfig + request 三层拼接（换行分隔）
+   *   但如果 request.systemPrompt 已设置（替换模式），则忽略所有 appendSystemPrompt
+   *
    * @param request 原始请求
    * @param backend 后端名称
    * @returns 合并后的请求