cc-node-bridge

cc-node 引擎的多客户端桥接平台：一个主项目 + 两个子项目（Web + VS Code）。

引擎（claude-code-node）运行在独立子进程（cc-node --stdio），桥接层统一管理会话/认证/限流/崩溃重启， 面向图形编程客户端（Web / VS Code）通过 JSON-RPC 2.0 接入。

职责边界：Telegram 编程入口不再由本桥接层负责，改由 cc-node 直接模式（--with-notify）承担。 cc-node-bridge 专注 Web / VS Code 等编程客户端的接入。

架构

┌────────────────────────────────────────────────┐
│  客户端层                                       │
│  Web UI · VS Code 扩展 · 手机 App               │
└──────────────────────┬─────────────────────────┘
                       │ JSON-RPC 2.0
        ┌──────────────┼──────────────┐
        │  WS          │  HTTP+SSE    │
┌───────▼────────┐┌────▼─────────┐
│ 桥接核心        ││              │
│ engine-pool    ││              │
│ 会话路由/认证    ││              │
└───────┬────────┘└──────────────┘
        │  stdio JSON-RPC（每会话一个子进程）
┌───────▼──────────────────────────────────┐
│  claude-code-node 引擎（cc-node --stdio）  │
└──────────────────────────────────────────┘

快速开始

# 1. 启动桥接（WebSocket，端口 8787）
node bin/cc-bridge.js --transport ws --port 8787

# 2. 带认证
node bin/cc-bridge.js --transport ws --port 8787 --token my-secret

# 3. Web 模式（HTTP+SSE + 演示页，浏览器直接对话）
node bin/cc-bridge.js --transport http --port 8788 --static clients/web/src/static

CLI 选项

| 参数 | 说明 | 默认 | |------|------|------| | --transport | ws / http（可组合） | ws | | --port | 监听端口 | 8787 | | --host | 监听地址 | 0.0.0.0 | | --token | 认证 token（逗号分隔多个；空 = 不鉴权） | 空 | | --maxSessions | 并发引擎子进程上限 | 10 | | --engine-* | 透传给 cc-node 引擎的启动参数（见下表） | — |

引擎参数透传（--engine-* → cc-node 启动开关，spawn 时原样追加）：

| bridge 开关 | 引擎参数 | 说明 | |------|------|------| | --engine-model NAME | --model | 模型名 | | --engine-api-base URL | --api-base | API 地址 | | --engine-api-key KEY | --api-key | API Key | | --engine-system-prompt TEXT | --system-prompt | 系统提示词 | | --engine-cwd PATH | --cwd | 引擎工作目录 | | --engine-max-turns N | --max-turns | 最大工具循环轮数 | | --engine-max-messages N | --max-messages | 历史折叠条数阈值 | | --engine-max-output-tokens N | --max-output-tokens | 单次输出上限覆盖 | | --engine-small-model | --small-model | 小模型兼容标记 | | --engine-no-stream | --no-stream | 禁用流式输出 | | --engine-verbose | --verbose | 引擎调试日志 |

运行时切换 LLM 源：客户端可随时发 config/set（apiBase/apiKey/model）切换，无需重启 bridge；config/get 读取当前源。引擎随新版 cc-node 自动匹配（依赖 ^2.x）。

环境变量：CC_BRIDGE_ENGINE（引擎命令）、CC_BRIDGE_TOKEN。

里程碑

| 阶段 | 内容 | 状态 | |------|------|:---:| | P0 | 立项 / 协议文档 / 目录结构 | ✅ | | P1 | cc-node --stdio 引擎入口（测试 13/13） | ✅ | | P2 | 桥接核心：engine-pool + 会话路由 + 认证 + WS（测试 11/11） | ✅ | | P3 | HTTP/SSE 传输 + Web 演示页（测试 13/13） | ✅ | | P4 | ~~Telegram 聊天适配~~（已移除，改由 cc-node 直接模式承担） | 🗑️ | | P5 | 加固 / 压测 / npm 发布 | ⏳ |

子项目

| 子项目 | 目录 | 状态 | |--------|------|------| | Web 前端 | clients/web/ | ✅ 演示页可用（流式对话 / 模式切换 / 设置） | | VS Code 扩展 | clients/vscode/ | ✅ 内嵌引擎模式可用（Plan/Code 双模式） |

测试

# P1 引擎 stdio 协议（模拟客户端全流程）
node scripts/test-stdio.mjs

# P2 桥接核心（认证/并发隔离/崩溃重启，WS 双客户端）
node scripts/test-bridge-ws.mjs

# P3 HTTP/SSE（认证/流式/工具回传/静态页）
node scripts/test-http-sse.mjs

真实对话测试需模型端点：CC_TEST_API_BASE / CC_TEST_MODEL / CC_TEST_API_KEY （本地 Ollama 免 key；云端需 key）。引擎路径：ENGINE_PATH。

文档

| 文档 | 说明 | |------|------| | docs/stdio-protocol.md | 引擎 stdio 协议（JSON-RPC 2.0 over NDJSON） | | docs/usage.md | 桥接层使用指南（传输/认证/客户端配置） | | docs/client-guide.md | 客户端接入指南（WS/HTTP 示例代码） | | docs/bridge-plan.md | 架构计划书 |

License

MIT