@snack-kit/porygon 0.1.0

package/README.md

@@ -0,0 +1,490 @@
+# Porygon
+
+统一的 LLM Agent CLI 编程接口框架。通过 Facade + Adapter 模式，将 Claude Code、OpenCode 等 CLI 工具封装为一致的 TypeScript API。
+
+## 安装
+
+```bash
+npm add @snack-kit/porygon
+```
+
+**前置条件**：需要安装至少一个 CLI 后端：
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude` 命令)
+- [OpenCode](https://github.com/opencode-ai/opencode) (`opencode` 命令)
+
+## 快速上手
+
+```ts
+import { createPorygon } from "@snack-kit/porygon";
+
+const porygon = createPorygon();
+
+// 简单调用：发送 prompt，返回最终文本
+const answer = await porygon.run({ prompt: "什么是闭包？" });
+console.log(answer);
+
+// 释放资源
+await porygon.dispose();
+```
+
+## API 速查
+
+### `createPorygon(config?): Porygon`
+
+工厂函数，创建 Porygon 实例。
+
+```ts
+const porygon = createPorygon({
+  defaultBackend: "claude",           // "claude" | "opencode"
+  backends: {
+    claude: {
+      model: "sonnet",
+      appendSystemPrompt: "用中文回答",
+      cwd: "/path/to/project",
+      proxy: { url: "http://127.0.0.1:7897" },
+    },
+  },
+  defaults: {
+    timeoutMs: 300_000,
+    maxTurns: 50,
+    appendSystemPrompt: "请简洁回答",
+  },
+  proxy: { url: "http://proxy:8080", noProxy: "localhost" },
+});
+```
+
+**PorygonConfig 字段：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `defaultBackend` | `string` | 默认后端名称 |
+| `backends` | `Record<string, BackendConfig>` | 各后端独立配置 |
+| `defaults` | `{ appendSystemPrompt?, timeoutMs?, maxTurns? }` | 全局默认参数 |
+| `proxy` | `{ url: string, noProxy?: string }` | 全局代理（后端级 proxy 优先） |
+
+**BackendConfig 字段：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `model` | `string` | 模型名称 |
+| `appendSystemPrompt` | `string` | 追加系统提示词 |
+| `proxy` | `ProxyConfig` | 后端专属代理 |
+| `cwd` | `string` | 工作目录 |
+
+---
+
+### `porygon.run(request): Promise<string>`
+
+发送 prompt，等待完成，返回最终结果文本。适合简单的一次性调用。
+
+```ts
+const result = await porygon.run({
+  prompt: "写一个 HTTP 服务器",
+  backend: "claude",
+  model: "opus",
+});
+```
+
+---
+
+### `porygon.query(request): AsyncGenerator<AgentMessage>`
+
+流式查询，逐条 yield `AgentMessage`。适合需要实时输出或监控工具调用的场景。
+
+```ts
+for await (const msg of porygon.query({ prompt: "解释快速排序" })) {
+  switch (msg.type) {
+    case "system":
+      console.log("模型:", msg.model);
+      break;
+    case "stream_chunk":
+      process.stdout.write(msg.text); // 实时输出
+      break;
+    case "assistant":
+      console.log("完整回复:", msg.text);
+      break;
+    case "tool_use":
+      console.log("工具调用:", msg.toolName, msg.input);
+      break;
+    case "result":
+      console.log("完成", { cost: msg.costUsd, tokens: msg.inputTokens });
+      break;
+    case "error":
+      console.error("错误:", msg.message);
+      break;
+  }
+}
+```
+
+---
+
+### PromptRequest（请求参数）
+
+`run()` 和 `query()` 共用同一参数类型：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `prompt` | `string` | 是 | 提示词 |
+| `backend` | `string` | 否 | 后端名称（默认取 config.defaultBackend） |
+| `model` | `string` | 否 | 模型名称 |
+| `resume` | `string` | 否 | 恢复会话的 session ID |
+| `systemPrompt` | `string` | 否 | 系统提示词（替换模式，设置后 appendSystemPrompt 失效） |
+| `appendSystemPrompt` | `string` | 否 | 系统提示词（追加模式，与 config 中的追加内容合并） |
+| `allowedTools` | `string[]` | 否 | 允许的工具白名单 |
+| `disallowedTools` | `string[]` | 否 | 禁用的工具黑名单 |
+| `maxTurns` | `number` | 否 | 最大对话轮次 |
+| `timeoutMs` | `number` | 否 | 超时毫秒数 |
+| `cwd` | `string` | 否 | 工作目录 |
+| `envVars` | `Record<string, string>` | 否 | 注入子进程的环境变量 |
+| `mcpServers` | `Record<string, McpServerConfig>` | 否 | MCP 服务器配置 |
+| `backendOptions` | `Record<string, unknown>` | 否 | 透传给后端的额外选项 |
+
+**McpServerConfig：**
+
+```ts
+interface McpServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+}
+```
+
+---
+
+### AgentMessage（消息类型）
+
+`porygon.query()` 返回的 `AgentMessage` 是一个联合类型。所有消息均包含 `timestamp: number`，可选 `sessionId?: string` 和 `raw?: unknown`（后端原始数据）。
+
+| type | 接口 | 关键字段 |
+|------|------|----------|
+| `"system"` | `AgentSystemMessage` | `model?`, `tools?`, `cwd?` |
+| `"assistant"` | `AgentAssistantMessage` | `text` |
+| `"tool_use"` | `AgentToolUseMessage` | `toolName`, `input`, `output?` |
+| `"stream_chunk"` | `AgentStreamChunkMessage` | `text` |
+| `"result"` | `AgentResultMessage` | `text`, `durationMs?`, `costUsd?`, `inputTokens?`, `outputTokens?` |
+| `"error"` | `AgentErrorMessage` | `message`, `code?` |
+
+---
+
+### `porygon.use(direction, fn): () => void`
+
+注册拦截器，返回取消注册函数。
+
+**direction**: `"input"` | `"output"`
+
+**InterceptorFn 签名：**
+
+```ts
+type InterceptorFn = (
+  text: string,
+  context: InterceptorContext
+) => string | boolean | undefined | Promise<string | boolean | undefined>;
+```
+
+- 返回 `string`：替换文本
+- 返回 `false`：拒绝消息（抛出 `InterceptorRejectedError`）
+- 返回 `true` / `undefined`：不修改，传递原始文本
+
+**InterceptorContext：**
+
+```ts
+interface InterceptorContext {
+  direction: "input" | "output";
+  backend: string;
+  sessionId?: string;
+  messageType?: string;  // 仅 output 方向
+}
+```
+
+**示例：**
+
+```ts
+// 输入拦截：追加指令
+const unuse = porygon.use("input", (text) => text + "\n请用 Markdown 格式回答");
+
+// 输出拦截：过滤敏感信息
+porygon.use("output", (text) => text.replace(/sk-[a-zA-Z0-9]{48}/g, "[REDACTED]"));
+
+// 拒绝过长输入
+porygon.use("input", (text) => { if (text.length > 10000) return false; });
+
+// 取消注册
+unuse();
+```
+
+---
+
+### 防护拦截器
+
+内置的 prompt 注入防护工具函数。
+
+#### `createInputGuard(options?): InterceptorFn`
+
+检测并阻止常见 prompt 注入攻击（内置 13 条中英文模式）。
+
+```ts
+import { createInputGuard } from "@snack-kit/porygon";
+
+// 使用内置规则
+porygon.use("input", createInputGuard());
+
+// 自定义配置
+porygon.use("input", createInputGuard({
+  blockedPatterns: [/我是管理员/, /sudo mode/i],
+  action: "reject",       // "reject"（拒绝）| "redact"（替换为 [REDACTED]）
+  backends: ["claude"],    // 仅对指定后端生效
+  customCheck: (text) => text.includes("bypass"),
+}));
+```
+
+#### `createOutputGuard(options?): InterceptorFn`
+
+检测输出中的敏感关键词泄露。
+
+```ts
+import { createOutputGuard } from "@snack-kit/porygon";
+
+porygon.use("output", createOutputGuard({
+  sensitiveKeywords: ["内部API密钥", "sk-xxxx"],
+  action: "redact",
+}));
+```
+
+**GuardOptions：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `blockedPatterns` | `RegExp[]` | 额外阻止模式（输入侧） |
+| `sensitiveKeywords` | `string[]` | 敏感关键词列表（输出侧） |
+| `action` | `"reject"` \| `"redact"` | 触发时的处理动作，输入默认 reject，输出默认 redact |
+| `customCheck` | `(text, context) => boolean` | 自定义判定函数 |
+| `backends` | `string[]` | 仅对指定后端生效 |
+
+---
+
+### `porygon.healthCheck()`
+
+对所有已注册后端进行健康检查（并行执行）。
+
+```ts
+const health = await porygon.healthCheck();
+// {
+//   claude: { available: true, compatibility: { version: "1.2.0", supported: true, warnings: [] } },
+//   opencode: { available: false, compatibility: null, error: "..." }
+// }
+```
+
+---
+
+### `porygon.listSessions(backend?, options?): Promise<SessionInfo[]>`
+
+列出指定后端的历史会话。
+
+```ts
+const sessions = await porygon.listSessions("claude", { limit: 10 });
+// SessionInfo: { sessionId, backend, summary?, lastModified, cwd?, metadata? }
+```
+
+---
+
+### `porygon.abort(backend, sessionId): void`
+
+中止正在运行的查询。
+
+---
+
+### `porygon.settings(backend, newSettings?): Promise<Record<string, unknown>>`
+
+读取或更新后端设置。
+
+```ts
+const settings = await porygon.settings("claude");
+await porygon.settings("claude", { model: "opus" });
+```
+
+---
+
+### `porygon.listModels(backend?): Promise<ModelInfo[]>`
+
+获取后端可用模型列表。
+
+```ts
+const models = await porygon.listModels("claude");
+// ModelInfo: { id: string, name?: string, provider?: string }
+```
+
+---
+
+### `porygon.getCapabilities(backend?): AdapterCapabilities`
+
+获取后端能力声明。
+
+```ts
+const caps = porygon.getCapabilities("claude");
+// {
+//   features: Set<"streaming" | "session-resume" | "system-prompt" | "tool-restriction" | "mcp" | ...>,
+//   outputFormats: string[],
+//   testedVersionRange: string,
+// }
+```
+
+---
+
+### `porygon.dispose(): Promise<void>`
+
+终止所有进程、中止所有查询、清空缓存。使用完毕后必须调用。
+
+---
+
+## 错误处理
+
+所有错误继承自 `PorygonError`，包含 `code` 字段：
+
+```ts
+import { PorygonError, AdapterNotFoundError } from "@snack-kit/porygon";
+
+try {
+  await porygon.run({ prompt: "hi", backend: "nonexistent" });
+} catch (err) {
+  if (err instanceof AdapterNotFoundError) {
+    console.log(err.code); // "ADAPTER_NOT_FOUND"
+  }
+}
+```
+
+| 错误类 | code | 场景 |
+|--------|------|------|
+| `AdapterNotFoundError` | `ADAPTER_NOT_FOUND` | 后端未注册 |
+| `AdapterNotAvailableError` | `ADAPTER_NOT_AVAILABLE` | CLI 不可用 |
+| `AdapterIncompatibleError` | `ADAPTER_INCOMPATIBLE` | 版本不兼容 |
+| `SessionNotFoundError` | `SESSION_NOT_FOUND` | 会话不存在 |
+| `InterceptorRejectedError` | `INTERCEPTOR_REJECTED` | 拦截器拒绝 |
+| `AgentExecutionError` | `AGENT_EXECUTION_ERROR` | 执行异常 |
+| `AgentTimeoutError` | `AGENT_TIMEOUT` | 超时 |
+| `ConfigValidationError` | `CONFIG_VALIDATION_ERROR` | 配置校验失败 |
+
+## 事件
+
+Porygon 继承自 EventEmitter：
+
+```ts
+porygon.on("health:degraded", (backend: string, warning: string) => {
+  console.warn(`${backend} 降级: ${warning}`);
+});
+```
+
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| `health:degraded` | `(backend, warning)` | 后端版本不兼容时触发 |
+
+## 完整导出列表
+
+```ts
+// 核心
+export { Porygon, createPorygon } from "@snack-kit/porygon";
+
+// 类型
+export type {
+  PorygonConfig, BackendConfig, ProxyConfig,
+  PromptRequest, McpServerConfig,
+  AgentMessage, AgentSystemMessage, AgentAssistantMessage,
+  AgentToolUseMessage, AgentStreamChunkMessage, AgentResultMessage, AgentErrorMessage,
+  AdapterCapabilities, CompatibilityResult, SessionInfo, SessionListOptions, ModelInfo,
+  InterceptorFn, InterceptorDirection, InterceptorContext,
+  GuardOptions, GuardAction,
+  PorygonEvents, IAgentAdapter,
+} from "@snack-kit/porygon";
+
+// 错误
+export {
+  PorygonError, AdapterNotFoundError, AdapterNotAvailableError,
+  AdapterIncompatibleError, SessionNotFoundError, InterceptorRejectedError,
+  AgentExecutionError, AgentTimeoutError, ConfigValidationError,
+} from "@snack-kit/porygon";
+
+// 防护拦截器
+export { createInputGuard, createOutputGuard } from "@snack-kit/porygon";
+
+// 适配器（自定义扩展用）
+export { AbstractAgentAdapter, ClaudeAdapter, OpenCodeAdapter } from "@snack-kit/porygon";
+```
+
+## 典型使用模式
+
+### 带防护的流式调用
+
+```ts
+import { createPorygon, createInputGuard, createOutputGuard } from "@snack-kit/porygon";
+
+const porygon = createPorygon({
+  defaultBackend: "claude",
+  backends: {
+    claude: { model: "sonnet", appendSystemPrompt: "用中文回答" },
+  },
+});
+
+porygon.use("input", createInputGuard());
+porygon.use("output", createOutputGuard({ sensitiveKeywords: ["SECRET"] }));
+
+for await (const msg of porygon.query({ prompt: "解释 async/await" })) {
+  if (msg.type === "stream_chunk") process.stdout.write(msg.text);
+  if (msg.type === "result") console.log("\n完成", msg.costUsd);
+}
+
+await porygon.dispose();
+```
+
+### 恢复会话
+
+```ts
+const sessions = await porygon.listSessions("claude", { limit: 1 });
+if (sessions.length > 0) {
+  const answer = await porygon.run({
+    prompt: "继续上次的工作",
+    resume: sessions[0].sessionId,
+  });
+}
+```
+
+### 注入环境变量与 MCP 服务器
+
+```ts
+const answer = await porygon.run({
+  prompt: "查找相关文档后回答",
+  envVars: { CLAUDE_CODE_OAUTH_TOKEN: "token-xxx" },
+  mcpServers: {
+    "context7": { command: "npx", args: ["-y", "@context7/mcp"] },
+  },
+});
+```
+
+### 健康检查后选择可用后端
+
+```ts
+const health = await porygon.healthCheck();
+const backend = health.claude?.available ? "claude" : "opencode";
+const answer = await porygon.run({ prompt: "hello", backend });
+```
+
+## 架构
+
+```
+Porygon (Facade)
+├── InterceptorManager     # 输入/输出拦截器流水线
+├── ProcessManager         # 子进程生命周期管理
+├── SessionManager         # 会话缓存与委托
+└── Adapters
+    ├── ClaudeAdapter      # claude -p --output-format stream-json
+    └── OpenCodeAdapter    # opencode serve + REST API + SSE
+```
+
+## 开发
+
+```bash
+npm install
+npm build       # 构建
+npm test        # 运行测试
+npm dev         # watch 模式构建
+npm playground  # 启动 Playground（http://localhost:3000）
+```