@snack-kit/porygon 0.1.0 → 0.3.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";
@@ -113,7 +128,13 @@ interface AgentErrorMessage extends BaseAgentMessage {
  * 适配器能力声明
  */
 interface AdapterCapabilities {
-    features: Set<"streaming" | "session-resume" | "system-prompt" | "tool-restriction" | "mcp" | "subagents" | "worktree" | "budget-limit" | "serve-mode">;
+    features: Set<"streaming" | "session-resume" | "system-prompt" | "tool-restriction" | "mcp" | "subagents" | "worktree" | "budget-limit" | "serve-mode" | "interactive-session">;
+    /**
+     * 流式输出模式：
+     * - '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,48 @@ interface InterceptorContext {
  */
 type InterceptorFn = (text: string, context: InterceptorContext) => string | boolean | undefined | Promise<string | boolean | undefined>;
 
+/**
+ * 便捷的多轮对话封装。
+ *
+ * 底层仍是 per-turn spawn + --resume，但对调用方透明：
+ * ```ts
+ * const session = porygon.session({ systemPrompt: '...' });
+ * for await (const msg of session.send('Hello')) { ... }
+ * for await (const msg of session.send('继续')) { ... }  // 自动 resume
+ * session.close();
+ * ```
+ */
+declare class InteractiveSession {
+    readonly initialSessionId: string;
+    private resolvedSessionId?;
+    private adapter;
+    private baseRequest;
+    private firstSent;
+    private closed;
+    constructor(initialSessionId: string, adapter: IAgentAdapter, baseRequest: Omit<PromptRequest, "prompt">);
+    /** 当前生效的 sessionId（首次 send 后反映 CLI 返回的真实 ID） */
+    get sessionId(): string;
+    /** 会话是否仍然活跃 */
+    get isActive(): boolean;
+    /**
+     * 发送一条消息，返回流式响应。
+     * 首次调用使用 initialSessionId，后续自动附加 resume。
+     */
+    send(prompt: string): AsyncGenerator<AgentMessage>;
+    /** 关闭会话（仅清理内部状态，无进程需要释放） */
+    close(): void;
+}
+
+/**
+ * 健康检查结果（扁平化结构）
+ */
+interface HealthCheckResult {
+    available: boolean;
+    version?: string;
+    supported?: boolean;
+    warnings?: string[];
+    error?: string;
+}
 /**
  * Porygon 事件类型定义
  */
@@ -237,6 +302,11 @@ declare class Porygon extends EventEmitter {
      * @returns 最终结果文本
      */
     run(request: PromptRequest): Promise<string>;
+    /**
+     * 创建交互式多轮对话会话。
+     * 自动管理 sessionId 和 resume，对调用方透明。
+     */
+    session(options?: Omit<PromptRequest, "prompt">): InteractiveSession;
     /**
      * 注册拦截器
      * @param direction 拦截方向
@@ -255,13 +325,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 +358,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 合并后的请求
@@ -414,6 +495,8 @@ interface SpawnOptions {
     cwd?: string;
     env?: Record<string, string>;
     timeoutMs?: number;
+    /** 写入 stdin 后自动关闭的数据 */
+    stdinData?: string;
 }
 /**
  * 进程执行结果
@@ -588,6 +671,8 @@ declare abstract class AbstractAgentAdapter implements IAgentAdapter {
  */
 declare class ClaudeAdapter extends AbstractAgentAdapter {
     readonly backend = "claude";
+    /** CLI 命令名或路径 */
+    private get cliCommand();
     /**
      * 检查 Claude CLI 是否可用
      */
@@ -635,6 +720,11 @@ declare class ClaudeAdapter extends AbstractAgentAdapter {
      * @param noProxy 不走代理的地址列表
      */
     private applyProxyEnv;
+    /**
+     * 构建通过 stdin 传递给 Claude CLI 的数据。
+     * 使用 stdin 而非 CLI 参数传递 prompt，避免超长参数导致的 403 错误。
+     */
+    private buildStdinData;
     private buildArgs;
 }
 
@@ -646,11 +736,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 +809,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, 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 };