@snack-kit/porygon 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,715 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * 代理配置
+ */
+interface ProxyConfig {
+    url: string;
+    noProxy?: string;
+}
+/**
+ * 后端配置
+ */
+interface BackendConfig {
+    model?: string;
+    appendSystemPrompt?: string;
+    proxy?: ProxyConfig;
+    cwd?: string;
+    /** 透传给 CLI 的后端特定选项 */
+    options?: Record<string, unknown>;
+}
+/**
+ * Porygon 全局配置
+ */
+interface PorygonConfig {
+    defaultBackend?: string;
+    backends?: Record<string, BackendConfig>;
+    defaults?: {
+        appendSystemPrompt?: string;
+        timeoutMs?: number;
+        maxTurns?: number;
+    };
+    proxy?: ProxyConfig;
+}
+
+/**
+ * MCP 服务器配置
+ */
+interface McpServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+}
+/**
+ * 用户传递给 query()/run() 的请求参数
+ */
+interface PromptRequest {
+    prompt: string;
+    backend?: string;
+    /** 恢复会话的 session ID */
+    resume?: string;
+    /** 系统提示词（替换模式） */
+    systemPrompt?: string;
+    /** 系统提示词（追加模式） */
+    appendSystemPrompt?: string;
+    model?: string;
+    timeoutMs?: number;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    mcpServers?: Record<string, McpServerConfig>;
+    maxTurns?: number;
+    cwd?: string;
+    /** 透传给后端的额外选项 */
+    backendOptions?: Record<string, unknown>;
+    /** 注入到子进程的额外环境变量（如 CLAUDE_CODE_OAUTH_TOKEN、代理变量等） */
+    envVars?: Record<string, string>;
+}
+/**
+ * 统一输出消息联合类型
+ */
+type AgentMessage = AgentSystemMessage | AgentAssistantMessage | AgentToolUseMessage | AgentStreamChunkMessage | AgentResultMessage | AgentErrorMessage;
+interface BaseAgentMessage {
+    timestamp: number;
+    sessionId?: string;
+    /** 后端原始数据 */
+    raw?: unknown;
+}
+interface AgentSystemMessage extends BaseAgentMessage {
+    type: "system";
+    model?: string;
+    tools?: string[];
+    cwd?: string;
+}
+interface AgentAssistantMessage extends BaseAgentMessage {
+    type: "assistant";
+    text: string;
+}
+interface AgentToolUseMessage extends BaseAgentMessage {
+    type: "tool_use";
+    toolName: string;
+    input: Record<string, unknown>;
+    output?: string;
+}
+interface AgentStreamChunkMessage extends BaseAgentMessage {
+    type: "stream_chunk";
+    text: string;
+}
+interface AgentResultMessage extends BaseAgentMessage {
+    type: "result";
+    text: string;
+    durationMs?: number;
+    costUsd?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+interface AgentErrorMessage extends BaseAgentMessage {
+    type: "error";
+    message: string;
+    code?: string;
+}
+
+/**
+ * 适配器能力声明
+ */
+interface AdapterCapabilities {
+    features: Set<"streaming" | "session-resume" | "system-prompt" | "tool-restriction" | "mcp" | "subagents" | "worktree" | "budget-limit" | "serve-mode">;
+    outputFormats: string[];
+    testedVersionRange: string;
+}
+/**
+ * 兼容性检查结果
+ */
+interface CompatibilityResult {
+    version: string;
+    supported: boolean;
+    warnings: string[];
+}
+/**
+ * 会话信息
+ */
+interface SessionInfo {
+    sessionId: string;
+    backend: string;
+    summary?: string;
+    lastModified: number;
+    cwd?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 会话列表查询选项
+ */
+interface SessionListOptions {
+    limit?: number;
+    cwd?: string;
+}
+/**
+ * Agent 适配器接口
+ */
+interface IAgentAdapter {
+    readonly backend: string;
+    isAvailable(): Promise<boolean>;
+    getVersion(): Promise<string>;
+    getCapabilities(): AdapterCapabilities;
+    checkCompatibility(): Promise<CompatibilityResult>;
+    query(request: PromptRequest): AsyncGenerator<AgentMessage>;
+    listSessions(options?: SessionListOptions): Promise<SessionInfo[]>;
+    getSettings(): Promise<Record<string, unknown>>;
+    updateSettings(settings: Record<string, unknown>): Promise<void>;
+    /** 获取可用模型列表 */
+    listModels(): Promise<ModelInfo[]>;
+    abort(sessionId: string): void;
+    dispose(): Promise<void>;
+}
+/**
+ * 模型信息
+ */
+interface ModelInfo {
+    id: string;
+    name?: string;
+    provider?: string;
+}
+
+type InterceptorDirection = "input" | "output";
+interface InterceptorContext {
+    direction: InterceptorDirection;
+    backend: string;
+    sessionId?: string;
+    /** 仅输出方向可用 */
+    messageType?: string;
+}
+/**
+ * 拦截器函数签名
+ * - 返回 string: 替换文本，传递给下一个拦截器
+ * - 返回 false: 拒绝消息，抛出 InterceptorRejectedError
+ * - 返回 true/undefined: 不修改，传递原始文本给下一个拦截器
+ */
+type InterceptorFn = (text: string, context: InterceptorContext) => string | boolean | undefined | Promise<string | boolean | undefined>;
+
+/**
+ * Porygon 事件类型定义
+ */
+interface PorygonEvents {
+    "session:created": (info: SessionInfo) => void;
+    "session:resumed": (info: SessionInfo) => void;
+    "process:spawn": (backend: string, pid: number) => void;
+    "process:exit": (backend: string, code: number | null) => void;
+    "process:error": (backend: string, error: Error) => void;
+    "process:restart": (backend: string, attempt: number) => void;
+    "interceptor:rejected": (direction: string, reason: string) => void;
+    "health:degraded": (backend: string, warning: string) => void;
+}
+/**
+ * Porygon 主门面类，提供统一的 LLM 后端交互接口。
+ * 管理适配器注册、拦截器流水线、进程生命周期和会话管理。
+ */
+declare class Porygon extends EventEmitter {
+    private config;
+    private adapters;
+    private interceptors;
+    private processManager;
+    private sessionManager;
+    constructor(config?: Partial<PorygonConfig>);
+    /**
+     * 注册内置适配器
+     */
+    private registerBuiltinAdapters;
+    /**
+     * 注册自定义适配器
+     * @param adapter 适配器实例
+     */
+    registerAdapter(adapter: IAgentAdapter): void;
+    /**
+     * 获取指定后端的适配器
+     * @param backend 后端名称，默认使用配置中的 defaultBackend
+     */
+    private getAdapter;
+    /**
+     * 流式查询，返回 AgentMessage 异步生成器。
+     * 作为与 LLM 后端交互的主要入口。
+     * @param request 提示请求参数
+     * @yields AgentMessage 消息流
+     */
+    query(request: PromptRequest): AsyncGenerator<AgentMessage>;
+    /**
+     * 简单运行模式，收集所有消息并返回最终结果文本
+     * @param request 提示请求参数
+     * @returns 最终结果文本
+     */
+    run(request: PromptRequest): Promise<string>;
+    /**
+     * 注册拦截器
+     * @param direction 拦截方向
+     * @param fn 拦截器函数
+     * @returns 取消注册的函数
+     */
+    use(direction: InterceptorDirection, fn: InterceptorFn): () => void;
+    /**
+     * 获取后端能力声明
+     * @param backend 后端名称
+     */
+    getCapabilities(backend?: string): AdapterCapabilities;
+    /**
+     * 获取指定后端的可用模型列表
+     * @param backend 后端名称
+     */
+    listModels(backend?: string): Promise<ModelInfo[]>;
+    /**
+     * 对所有已注册后端进行健康检查
+     */
+    healthCheck(): Promise<Record<string, {
+        available: boolean;
+        compatibility: CompatibilityResult | null;
+        error?: string;
+    }>>;
+    /**
+     * 读取或更新后端设置
+     * @param backend 后端名称
+     * @param newSettings 要更新的设置项（可选）
+     * @returns 当前设置
+     */
+    settings(backend: string, newSettings?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * 列出指定后端的会话
+     * @param backend 后端名称
+     * @param options 查询选项
+     */
+    listSessions(backend?: string, options?: SessionListOptions): Promise<SessionInfo[]>;
+    /**
+     * 中止正在运行的查询
+     * @param backend 后端名称
+     * @param sessionId 会话 ID
+     */
+    abort(backend: string, sessionId: string): void;
+    /**
+     * 释放所有资源
+     */
+    dispose(): Promise<void>;
+    /**
+     * 合并请求参数与配置默认值
+     * @param request 原始请求
+     * @param backend 后端名称
+     * @returns 合并后的请求
+     */
+    private mergeRequest;
+}
+/**
+ * 创建 Porygon 实例的工厂函数
+ * @param config 可选的配置参数
+ * @returns Porygon 实例
+ */
+declare function createPorygon(config?: Partial<PorygonConfig>): Porygon;
+
+/**
+ * Porygon 基础错误类
+ */
+declare class PorygonError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+declare class AdapterNotFoundError extends PorygonError {
+    constructor(backend: string, options?: ErrorOptions);
+}
+declare class AdapterNotAvailableError extends PorygonError {
+    constructor(backend: string, options?: ErrorOptions);
+}
+declare class AdapterIncompatibleError extends PorygonError {
+    constructor(backend: string, version: string, options?: ErrorOptions);
+}
+declare class SessionNotFoundError extends PorygonError {
+    constructor(sessionId: string, options?: ErrorOptions);
+}
+declare class InterceptorRejectedError extends PorygonError {
+    constructor(reason: string, options?: ErrorOptions);
+}
+declare class AgentExecutionError extends PorygonError {
+    constructor(message: string, options?: ErrorOptions);
+}
+declare class AgentTimeoutError extends PorygonError {
+    constructor(timeoutMs: number, options?: ErrorOptions);
+}
+declare class ConfigValidationError extends PorygonError {
+    constructor(message: string, options?: ErrorOptions);
+}
+
+/**
+ * 防护拦截器触发时的处理动作
+ */
+type GuardAction = "reject" | "redact";
+/**
+ * 防护拦截器配置选项
+ */
+interface GuardOptions {
+    /**
+     * 输入侧：阻止用户通过 prompt 注入攻击套取系统提示词或绕过规则。
+     * 匹配到任一模式时触发防护。
+     * @example [/忽略.*指令/, /重复.*系统提示/, /ignore.*instructions/i]
+     */
+    blockedPatterns?: RegExp[];
+    /**
+     * 输出侧：防止模型在回复中泄露系统提示词内容。
+     * 提供需要保护的关键词列表，若输出中包含这些关键词则触发防护。
+     * @example ["内部密钥", "SECRET_TOKEN"]
+     */
+    sensitiveKeywords?: string[];
+    /**
+     * 触发防护时的处理动作：
+     * - "reject": 拒绝消息，抛出 InterceptorRejectedError（默认）
+     * - "redact": 替换匹配内容为 [REDACTED]，允许消息继续传递
+     */
+    action?: GuardAction;
+    /**
+     * 自定义判定函数，在内置规则之后执行。
+     * 返回 true 表示触发防护，返回 false 或 undefined 表示放行。
+     */
+    customCheck?: (text: string, context: InterceptorContext) => boolean | undefined;
+    /**
+     * 仅对指定后端生效，不设则对所有后端生效
+     */
+    backends?: string[];
+}
+/**
+ * 创建输入防护拦截器。
+ * 检测并阻止常见的 prompt 注入攻击，防止用户套取系统提示词或绕过规则。
+ *
+ * @param options 防护配置选项
+ * @returns 可注册到 `porygon.use("input", ...)` 的拦截器函数
+ *
+ * @example
+ * ```ts
+ * // 使用内置规则
+ * porygon.use("input", createInputGuard());
+ *
+ * // 自定义阻止模式
+ * porygon.use("input", createInputGuard({
+ *   blockedPatterns: [/我是管理员/, /sudo mode/i],
+ *   action: "reject",
+ * }));
+ * ```
+ */
+declare function createInputGuard(options?: GuardOptions): InterceptorFn;
+/**
+ * 创建输出防护拦截器。
+ * 检测模型输出中是否包含敏感关键词，防止系统提示词内容泄露。
+ *
+ * @param options 防护配置选项
+ * @returns 可注册到 `porygon.use("output", ...)` 的拦截器函数
+ *
+ * @example
+ * ```ts
+ * porygon.use("output", createOutputGuard({
+ *   sensitiveKeywords: ["内部API密钥", "sk-xxxx"],
+ *   action: "redact",
+ * }));
+ * ```
+ */
+declare function createOutputGuard(options?: GuardOptions): InterceptorFn;
+
+/**
+ * 进程启动选项
+ */
+interface SpawnOptions {
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+}
+/**
+ * 进程执行结果
+ */
+interface ProcessResult {
+    exitCode: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * 持久进程选项
+ */
+interface PersistentProcessOptions {
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    maxRestarts: number;
+    restartIntervalMs: number;
+    healthCheckIntervalMs: number;
+    healthCheckFn?: () => Promise<boolean>;
+}
+
+/**
+ * EphemeralProcess：一次性进程执行，支持流式输出。
+ * 适用于 `claude -p` 和 `opencode run` 等短生命周期调用场景。
+ */
+declare class EphemeralProcess {
+    private childProcess;
+    private aborted;
+    /**
+     * 执行命令并收集输出。支持 AbortController 进行取消操作。
+     * @param options 进程启动选项
+     * @param abortSignal 可选的中止信号
+     * @returns 进程执行结果
+     */
+    execute(options: SpawnOptions, abortSignal?: AbortSignal): Promise<ProcessResult>;
+    /**
+     * 以流式方式执行命令，逐行输出 stdout 内容。
+     * @param options 进程启动选项
+     * @param abortSignal 可选的中止信号
+     */
+    executeStreaming(options: SpawnOptions, abortSignal?: AbortSignal): AsyncGenerator<string>;
+    /** 获取底层子进程的 PID */
+    get pid(): number | undefined;
+    /** 终止进程：先发送 SIGTERM，超时后发送 SIGKILL */
+    terminate(): void;
+}
+/**
+ * PersistentProcess：长期运行的服务进程，支持自动重启。
+ * 适用于 `opencode serve` 等持久化服务场景。
+ */
+declare class PersistentProcess extends EventEmitter {
+    private process;
+    private restartCount;
+    private stopped;
+    private healthCheckTimer;
+    private readonly options;
+    constructor(options: PersistentProcessOptions);
+    /** 启动持久进程 */
+    start(): Promise<void>;
+    /** 处理进程崩溃，按指数退避策略重启 */
+    private handleCrash;
+    /** 停止健康检查定时器 */
+    private stopHealthCheck;
+    /** 停止持久进程 */
+    stop(): Promise<void>;
+    /** 获取底层子进程的 PID */
+    get pid(): number | undefined;
+    /** 当前进程是否正在运行 */
+    get isRunning(): boolean;
+}
+
+/**
+ * ProcessManager：统一管理所有子进程。
+ * 注册退出钩子，确保主进程退出时清理所有子进程。
+ */
+declare class ProcessManager {
+    private readonly ephemeral;
+    private readonly persistent;
+    /** 全局静态标记，确保信号处理器只注册一次 */
+    private static cleanupRegistered;
+    /** 所有活跃的 ProcessManager 实例（弱引用避免阻止 GC） */
+    private static readonly instances;
+    constructor();
+    /** 注册进程退出清理钩子（仅清理资源，不劫持宿主退出行为） */
+    private static registerCleanup;
+    /**
+     * 创建一次性进程实例并注册到管理器
+     * @param sessionId 会话标识
+     * @returns 一次性进程实例
+     */
+    createEphemeral(sessionId: string): EphemeralProcess;
+    /**
+     * 从管理器中移除一次性进程
+     * @param sessionId 会话标识
+     */
+    removeEphemeral(sessionId: string): void;
+    /**
+     * 启动或获取持久进程
+     * @param backend 后端标识
+     * @param options 持久进程选项
+     * @returns 持久进程实例
+     */
+    startPersistent(backend: string, options: PersistentProcessOptions): Promise<PersistentProcess>;
+    /**
+     * 获取指定后端的持久进程
+     * @param backend 后端标识
+     */
+    getPersistent(backend: string): PersistentProcess | undefined;
+    /**
+     * 获取指定会话的一次性进程
+     * @param sessionId 会话标识
+     */
+    getEphemeral(sessionId: string): EphemeralProcess | undefined;
+    /** 异步终止所有托管进程 */
+    terminateAll(): Promise<void>;
+    /** 同步终止所有托管进程（用于 exit 钩子） */
+    private terminateAllSync;
+    /**
+     * 销毁实例，从全局实例列表中移除
+     */
+    destroy(): void;
+}
+
+/**
+ * Agent 适配器抽象基类，实现 IAgentAdapter 接口的公共逻辑。
+ * 子类需实现所有 abstract 方法以完成具体后端的适配。
+ */
+declare abstract class AbstractAgentAdapter implements IAgentAdapter {
+    abstract readonly backend: string;
+    /** 活跃的 AbortController 映射，按 sessionId 索引 */
+    protected readonly abortControllers: Map<string, AbortController>;
+    protected readonly processManager: ProcessManager;
+    protected readonly config?: BackendConfig;
+    constructor(processManager: ProcessManager, config?: BackendConfig);
+    /**
+     * 默认兼容性检查：获取当前版本并与 testedVersionRange 进行比较
+     */
+    checkCompatibility(): Promise<CompatibilityResult>;
+    /**
+     * 中止指定会话的执行
+     * @param sessionId 会话标识
+     */
+    abort(sessionId: string): void;
+    /**
+     * 创建并注册 AbortController
+     * @param sessionId 会话标识
+     * @returns AbortController 实例
+     */
+    protected createAbortController(sessionId: string): AbortController;
+    /**
+     * 清理指定会话的 AbortController
+     * @param sessionId 会话标识
+     */
+    protected removeAbortController(sessionId: string): void;
+    abstract isAvailable(): Promise<boolean>;
+    abstract getVersion(): Promise<string>;
+    abstract getCapabilities(): AdapterCapabilities;
+    abstract query(request: PromptRequest): AsyncGenerator<AgentMessage>;
+    abstract listSessions(options?: SessionListOptions): Promise<SessionInfo[]>;
+    abstract listModels(): Promise<ModelInfo[]>;
+    abstract getSettings(): Promise<Record<string, unknown>>;
+    abstract updateSettings(settings: Record<string, unknown>): Promise<void>;
+    abstract dispose(): Promise<void>;
+}
+
+/**
+ * Claude Code CLI 适配器。
+ * 通过 `claude -p --output-format stream-json` 命令与 Claude Code 交互。
+ */
+declare class ClaudeAdapter extends AbstractAgentAdapter {
+    readonly backend = "claude";
+    /**
+     * 检查 Claude CLI 是否可用
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * 获取 Claude CLI 版本号
+     */
+    getVersion(): Promise<string>;
+    /**
+     * 获取 Claude 适配器能力声明
+     */
+    getCapabilities(): AdapterCapabilities;
+    /**
+     * 向 Claude 发送提示并以流式方式接收响应
+     * @param request 提示请求参数
+     */
+    query(request: PromptRequest): AsyncGenerator<AgentMessage>;
+    /**
+     * 列出 Claude 会话
+     * @param options 查询选项
+     */
+    listSessions(options?: SessionListOptions): Promise<SessionInfo[]>;
+    /**
+     * 获取 Claude 可用模型列表。
+     * Claude CLI 支持使用简短别名（sonnet/opus/haiku）自动选择当前最新版本。
+     */
+    listModels(): Promise<ModelInfo[]>;
+    /**
+     * 读取 Claude 设置
+     */
+    getSettings(): Promise<Record<string, unknown>>;
+    /**
+     * 更新 Claude 设置（读取-合并-写入）
+     * @param settings 要合并的设置项
+     */
+    updateSettings(settings: Record<string, unknown>): Promise<void>;
+    /**
+     * 释放适配器资源
+     */
+    dispose(): Promise<void>;
+    /**
+     * 将代理配置注入到环境变量中
+     * @param env 环境变量对象
+     * @param proxyUrl 代理地址
+     * @param noProxy 不走代理的地址列表
+     */
+    private applyProxyEnv;
+    private buildArgs;
+}
+
+/**
+ * OpenCode 适配器。
+ * 通过 `opencode serve` 启动 HTTP 服务，使用 REST API + SSE 进行交互。
+ */
+declare class OpenCodeAdapter extends AbstractAgentAdapter {
+    readonly backend = "opencode";
+    private apiClient;
+    private servePort;
+    /**
+     * @param processManager 进程管理器实例
+     * @param servePort 可选的 serve 服务端口
+     */
+    constructor(processManager: ProcessManager, servePort?: number);
+    /**
+     * 检查 opencode 命令是否可用
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * 获取 opencode 版本号
+     */
+    getVersion(): Promise<string>;
+    /**
+     * 获取适配器能力声明
+     */
+    getCapabilities(): AdapterCapabilities;
+    /**
+     * 执行查询：启动 serve 进程（如未启动），创建/恢复会话，发送消息并流式返回结果
+     * @param request 请求参数
+     * @yields AgentMessage 统一消息流
+     */
+    query(request: PromptRequest): AsyncGenerator<AgentMessage>;
+    /**
+     * 列出历史会话
+     * @param options 查询选项
+     */
+    listSessions(options?: SessionListOptions): Promise<SessionInfo[]>;
+    /**
+     * 获取 OpenCode 可用模型列表（通过 `opencode models` 命令）
+     */
+    listModels(): Promise<ModelInfo[]>;
+    /**
+     * 读取 opencode 配置文件
+     */
+    getSettings(): Promise<Record<string, unknown>>;
+    /**
+     * 更新 opencode 配置文件（读取-合并-写入）
+     * @param settings 要合并的配置项
+     */
+    updateSettings(settings: Record<string, unknown>): Promise<void>;
+    /**
+     * 释放资源：停止 serve 进程，中止所有活跃流
+     */
+    dispose(): Promise<void>;
+    /**
+     * 确保 opencode serve 进程已启动并可用
+     * @returns 可用的 API 客户端
+     */
+    private ensureServeRunning;
+    /**
+     * 轮询等待 serve 服务可达
+     * @param client API 客户端
+     */
+    private waitForServeReady;
+    /**
+     * 延迟指定毫秒
+     * @param ms 毫秒数
+     */
+    private delay;
+    /**
+     * 获取 opencode 配置文件路径
+     */
+    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 };