@snack-kit/porygon 0.1.0 → 0.2.0

package/README.md

@@ -39,10 +39,16 @@ const porygon = createPorygon({
   backends: {
     claude: {
       model: "sonnet",
+      interactive: false,             // false = --dangerously-skip-permissions
+      cliPath: "/usr/local/bin/claude", // 自定义 CLI 路径
       appendSystemPrompt: "用中文回答",
       cwd: "/path/to/project",
       proxy: { url: "http://127.0.0.1:7897" },
     },
+    opencode: {
+      serverUrl: "http://localhost:39393",
+      apiKey: "sk-xxx",
+    },
   },
   defaults: {
     timeoutMs: 300_000,
@@ -67,9 +73,14 @@ const porygon = createPorygon({
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `model` | `string` | 模型名称 |
+| `interactive` | `boolean` | 是否交互模式，`false` 时 Claude 添加 `--dangerously-skip-permissions` |
+| `cliPath` | `string` | CLI 可执行文件路径（如 Claude CLI 的自定义安装路径） |
+| `serverUrl` | `string` | 远程服务地址（OpenCode serve 模式） |
+| `apiKey` | `string` | API Key 认证 |
 | `appendSystemPrompt` | `string` | 追加系统提示词 |
 | `proxy` | `ProxyConfig` | 后端专属代理 |
 | `cwd` | `string` | 工作目录 |
+| `options` | `Record<string, unknown>` | 透传给后端的额外选项（向后兼容，推荐使用上方的显式字段） |
 
 ---
 
@@ -98,13 +109,18 @@ for await (const msg of porygon.query({ prompt: "解释快速排序" })) {
       console.log("模型:", msg.model);
       break;
     case "stream_chunk":
-      process.stdout.write(msg.text); // 实时输出
+      process.stdout.write(msg.text); // 增量文本，实时输出
       break;
     case "assistant":
-      console.log("完整回复:", msg.text);
+      // turnComplete=true: 与前面 stream_chunk 内容重复，流式消费者应跳过
+      // turnComplete=false/undefined: 独立文本（如 run() 模式），需要处理
+      if (!msg.turnComplete) {
+        console.log("回复:", msg.text);
+      }
       break;
     case "tool_use":
       console.log("工具调用:", msg.toolName, msg.input);
+      if (msg.output) console.log("工具结果:", msg.output);
       break;
     case "result":
       console.log("完成", { cost: msg.costUsd, tokens: msg.inputTokens });
@@ -116,6 +132,17 @@ for await (const msg of porygon.query({ prompt: "解释快速排序" })) {
 }
 ```
 
+**消息流顺序**（两个后端统一）：
+
+```
+system → stream_chunk* → assistant(turnComplete) → tool_use* → ... → result
+```
+
+- `stream_chunk` — 增量文本片段，用于实时展示
+- `assistant` — 单个 turn 的完整文本汇总。`turnComplete: true` 表示内容与 `stream_chunk` 重复
+- `tool_use` — 工具调用；若带 `output` 字段则为工具执行结果
+- `result` — 最终结果，包含完整文本和用量统计
+
 ---
 
 ### PromptRequest（请求参数）
@@ -139,16 +166,15 @@ for await (const msg of porygon.query({ prompt: "解释快速排序" })) {
 | `mcpServers` | `Record<string, McpServerConfig>` | 否 | MCP 服务器配置 |
 | `backendOptions` | `Record<string, unknown>` | 否 | 透传给后端的额外选项 |
 
-**McpServerConfig：**
+**配置合并策略**（`mergeRequest`）：
 
-```ts
-interface McpServerConfig {
-  command: string;
-  args?: string[];
-  env?: Record<string, string>;
-  url?: string;
-}
-```
+| 字段 | 策略 |
+|------|------|
+| `model` | request > backendConfig > 不设置 |
+| `timeoutMs` | request > defaults |
+| `maxTurns` | request > defaults |
+| `cwd` | request > backendConfig |
+| `appendSystemPrompt` | defaults + backendConfig + request 三层追加拼接（换行分隔）。若 `systemPrompt` 已设置则忽略全部 append |
 
 ---
 
@@ -159,7 +185,7 @@ interface McpServerConfig {
 | type | 接口 | 关键字段 |
 |------|------|----------|
 | `"system"` | `AgentSystemMessage` | `model?`, `tools?`, `cwd?` |
-| `"assistant"` | `AgentAssistantMessage` | `text` |
+| `"assistant"` | `AgentAssistantMessage` | `text`, `turnComplete?` |
 | `"tool_use"` | `AgentToolUseMessage` | `toolName`, `input`, `output?` |
 | `"stream_chunk"` | `AgentStreamChunkMessage` | `text` |
 | `"result"` | `AgentResultMessage` | `text`, `durationMs?`, `costUsd?`, `inputTokens?`, `outputTokens?` |
@@ -167,6 +193,39 @@ interface McpServerConfig {
 
 ---
 
+### `porygon.checkBackend(backend): Promise<HealthCheckResult>`
+
+检查单个后端的健康状态。
+
+```ts
+const result = await porygon.checkBackend("claude");
+// { available: true, version: "1.2.0", supported: true }
+// { available: false, error: "command not found" }
+```
+
+**HealthCheckResult：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `available` | `boolean` | 后端是否可用 |
+| `version` | `string?` | CLI 版本号 |
+| `supported` | `boolean?` | 版本是否在测试范围内 |
+| `warnings` | `string[]?` | 兼容性警告 |
+| `error` | `string?` | 错误信息 |
+
+---
+
+### `porygon.healthCheck(): Promise<Record<string, HealthCheckResult>>`
+
+对所有已注册后端进行健康检查（并行执行）。
+
+```ts
+const health = await porygon.healthCheck();
+// { claude: { available: true, version: "1.2.0", supported: true }, opencode: { available: false, error: "..." } }
+```
+
+---
+
 ### `porygon.use(direction, fn): () => void`
 
 注册拦截器，返回取消注册函数。
@@ -186,17 +245,6 @@ type InterceptorFn = (
 - 返回 `false`：拒绝消息（抛出 `InterceptorRejectedError`）
 - 返回 `true` / `undefined`：不修改，传递原始文本
 
-**InterceptorContext：**
-
-```ts
-interface InterceptorContext {
-  direction: "input" | "output";
-  backend: string;
-  sessionId?: string;
-  messageType?: string;  // 仅 output 方向
-}
-```
-
 **示例：**
 
 ```ts
@@ -263,20 +311,6 @@ porygon.use("output", createOutputGuard({
 
 ---
 
-### `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[]>`
 
 列出指定后端的历史会话。
@@ -324,11 +358,16 @@ const models = await porygon.listModels("claude");
 const caps = porygon.getCapabilities("claude");
 // {
 //   features: Set<"streaming" | "session-resume" | "system-prompt" | "tool-restriction" | "mcp" | ...>,
+//   streamingMode: "delta" | "chunked",
 //   outputFormats: string[],
 //   testedVersionRange: string,
 // }
 ```
 
+**`streamingMode`：**
+- `"delta"` — 后端原生产生增量 `stream_chunk` 事件（OpenCode）
+- `"chunked"` — 适配器将完整 assistant 拆分为 `stream_chunk` + `assistant`（Claude）
+
 ---
 
 ### `porygon.dispose(): Promise<void>`
@@ -383,6 +422,7 @@ porygon.on("health:degraded", (backend: string, warning: string) => {
 ```ts
 // 核心
 export { Porygon, createPorygon } from "@snack-kit/porygon";
+export type { PorygonEvents, HealthCheckResult } from "@snack-kit/porygon";
 
 // 类型
 export type {
@@ -393,7 +433,7 @@ export type {
   AdapterCapabilities, CompatibilityResult, SessionInfo, SessionListOptions, ModelInfo,
   InterceptorFn, InterceptorDirection, InterceptorContext,
   GuardOptions, GuardAction,
-  PorygonEvents, IAgentAdapter,
+  IAgentAdapter,
 } from "@snack-kit/porygon";
 
 // 错误
@@ -420,7 +460,7 @@ import { createPorygon, createInputGuard, createOutputGuard } from "@snack-kit/p
 const porygon = createPorygon({
   defaultBackend: "claude",
   backends: {
-    claude: { model: "sonnet", appendSystemPrompt: "用中文回答" },
+    claude: { model: "sonnet", interactive: false },
   },
 });
 
@@ -462,6 +502,11 @@ const answer = await porygon.run({
 ### 健康检查后选择可用后端
 
 ```ts
+// 检查单个后端
+const result = await porygon.checkBackend("claude");
+if (!result.available) console.error(result.error);
+
+// 批量检查所有后端
 const health = await porygon.healthCheck();
 const backend = health.claude?.available ? "claude" : "opencode";
 const answer = await porygon.run({ prompt: "hello", backend });
@@ -479,12 +524,70 @@ Porygon (Facade)
     └── OpenCodeAdapter    # opencode serve + REST API + SSE
 ```
 
+**适配器能力对比：**
+
+| 能力 | Claude | OpenCode |
+|------|--------|----------|
+| streaming | `chunked` | `delta` |
+| session-resume | ✓ | ✓ |
+| system-prompt | ✓ | ✓ |
+| tool-restriction | ✓ | - |
+| mcp | ✓ | - |
+| subagents | ✓ | - |
+| worktree | ✓ | - |
+| serve-mode | - | ✓ |
+
 ## 开发
 
 ```bash
 npm install
-npm build       # 构建
-npm test        # 运行测试
-npm dev         # watch 模式构建
-npm playground  # 启动 Playground（http://localhost:3000）
+npm run build       # 构建（ESM + CJS + DTS）
+npm test            # 运行测试
+npm run dev         # watch 模式构建
+npm run playground  # 启动 Playground
 ```
+
+---
+
+## Changelog
+
+### v0.2.0
+
+#### 新特性
+
+- **`checkBackend(backend)`** — 新增单后端健康检查方法，无需检查全部后端
+- **`HealthCheckResult`** — 健康检查返回扁平化结构 `{ available, version?, supported?, warnings?, error? }`
+- **`BackendConfig.cliPath`** — Claude CLI 自定义路径，有类型提示
+- **`BackendConfig.interactive`** — 布尔值控制是否跳过权限确认
+- **`BackendConfig.serverUrl`** — OpenCode 远程服务地址（顶级字段）
+- **`BackendConfig.apiKey`** — API Key 认证（顶级字段）
+- **`AgentAssistantMessage.turnComplete`** — 标记 assistant 消息为 turn 完整文本汇总，流式消费者可据此跳过重复文本
+- **`AdapterCapabilities.streamingMode`** — 声明后端的流式模式（`"delta"` 或 `"chunked"`）
+- **`IAgentAdapter.deleteSession?`** — 可选的会话删除方法（接口已定义，适配器待实现）
+- **`tool_result` 映射** — Claude 的 `tool_result` 内容块现在映射为带 `output` 字段的 `tool_use` 消息
+- **`session_id` 自动提取** — Claude 原始事件中的 `session_id` 自动映射到 `AgentMessage.sessionId`
+- **CJS 输出** — 同时构建 ESM 和 CJS 格式，支持 Electron 等 CJS 环境
+
+#### 破坏性变更
+
+- **`mapClaudeEvent()` 返回类型变更** — 从 `AgentMessage | null` 改为 `AgentMessage[]`（仅影响直接调用 mapper 的代码）
+- **Claude 消息流变更** — `assistant` 事件拆分为 `stream_chunk[]` + `assistant(turnComplete: true)`。之前同时累加 `assistant` 和 `stream_chunk` 文本的代码需要调整：只累加 `stream_chunk`，或检查 `turnComplete` 标记
+- **`healthCheck()` 返回类型变更** — 从 `{ available, compatibility: CompatibilityResult | null, error? }` 改为 `HealthCheckResult`（`{ available, version?, supported?, warnings?, error? }`），移除嵌套的 `compatibility` 字段
+- **`AdapterCapabilities` 新增必填字段** — `streamingMode: "delta" | "chunked"` 为必填，自定义适配器需添加
+
+#### 改进
+
+- `mergeRequest()` 添加详细 JSDoc 注释说明配置合并策略
+- `mapAssistantContent()` 支持多内容块拆分，不再丢失 tool_use 块
+
+### v0.1.0 — 初始版本
+
+- 基础 Facade + Adapter 架构
+- Claude Code CLI 适配器（`claude -p --output-format stream-json`）
+- OpenCode 适配器（`opencode serve` + REST API + SSE）
+- 输入/输出拦截器流水线
+- 防护拦截器（prompt 注入检测、敏感信息过滤）
+- 进程生命周期管理（EphemeralProcess / PersistentProcess）
+- 会话管理与恢复
+- Zod 配置校验
+- ESM 输出