Caveman Code 终极指南:Daemon 守护模式与双SDK远程结对编程,从本地到 GPU 集群的完整实践
Caveman Code 终极指南:Daemon 守护模式与双SDK远程结对编程,从本地到 GPU 集群的完整实践
Caveman Code 是一款面向终端的开源 AI 编程 Agent,实测 token 消耗仅为 Codex CLI 的 1/1.93。除了命令行模式,它还内置了 Daemon 守护模式(caveman serve)与双 SDK(进程内嵌入 SDK + 远程 HTTP SDK),让你可以把 Agent 升级为常驻的 Agent 服务,支持 SSH 断线不丢会话、多客户端实时结对编程,还能一键把任务派发到远程 GPU 机器。
下面这份指南带你从零搭好 Caveman Code Agent 服务,覆盖守护进程部署、安全配置、Worker 远程托管,以及两种 SDK 的选型与对接。
架构速览:谁在守护,谁在连接?
Caveman Code 的守护模式采用经典的 C/S 架构:caveman serve 启动一个无头 HTTP 守护进程,TUI 终端客户端、未来的桌面端/移动端都作为客户端挂载(attach)到上面。
- HTTP 负责控制面:创建会话、列出会话、终止会话
- WebSocket 负责数据面:流式 token、低延迟工具事件
- SQLite 持久化全部会话,文件位于
~/.cave/serve/sessions.db
官方架构示意(来自 docs/reference/daemon.md):
┌─────────────────────────────┐ ┌─────────────────────┐
│ cave TUI (client) │ ──HTTP─▶│ caveman serve │
│ caveman attach <session-id>│ ◀──WS── │ ├─ session store │
└─────────────────────────────┘ │ │ (SQLite) │
│ ├─ session loop │
┌─────────────────────────────┐ │ ├─ tool runtime │
│ cave-desktop (client) │ ──HTTP─▶│ └─ MCP clients │
└─────────────────────────────┘ └─────────────────────┘
守护模式一键上手:3 条命令跑起来
启动 Caveman Code Agent 服务只需三步:
caveman serve --port 39245 # 启动 Daemon 守护进程
caveman attach --host localhost:39245 # 挂载 TUI 客户端
caveman list # 列出所有会话
💡 默认绑定
127.0.0.1(仅本机可访问),这是刻意的安全设计。
守护进程的核心源码位于 serve.ts,HTTP 服务端与会话存储分别在 server.ts 和 store.ts。想深入了解协议细节,可以读一下 docs/reference/daemon.md。
图:Caveman Code 终端界面 —— 守护模式下,token 与工具调用事件通过 WebSocket 实时流式推送到客户端
远程访问与安全防护配置清单
守护模式默认只监听本机。如果需要远程访问,按官方推荐做以下配置(摘自 docs/reference/daemon.md):
| 配置项 | 推荐做法 |
|---|---|
| 绑定地址 | 使用 --host 0.0.0.0 对外开放 |
| 认证 | 非回环绑定必须提供 --token,WebSocket 连接同样使用 bearer 认证 |
| TLS | 交给反向代理处理:Caddy、nginx 或 cloudflared tunnel |
一句话总结:token 是底线,TLS 是代理的事。
Worker 远程托管:把任务派给 GPU 集群
这是 Daemon 模式最实用的进阶玩法:把算力强的远程机器(比如 GPU 工作站)注册为 Worker,本地终端瞬间释放。
第一步,在远程机器上启动 Worker:
caveman worker start --bind 0.0.0.0:39246 --token <secret>
第二步,在本地注册:
caveman worker add gpu-rig http://gpu-rig:39246 --token <secret>
第三步,给任何提示词加 & 前缀,任务就会派发到 Worker 执行:
& refactor packages/agent/src/checkpoints to use the new index format
本地终端立刻空闲,Worker 在后台跑会话。完成后随时重连:
caveman list
caveman attach <session-id>
⚠️ 注意:Worker 模式要求本地与远程之间具备 SSH 级别的信任,且守护模式尚不支持 Windows(官方计划 2026 Q3 预览)。
多客户端结对编程:一个会话,多台设备
Daemon 支持多个客户端挂载同一会话,所有编辑与输出实时流式同步到每一个客户端。官方文档明确推荐两个场景:
- 结对编程:两人各自 TUI 挂载同一会话,实时看到彼此的 Agent 进展
- 长会话常驻:笔记本 TUI 挂着一个会话,桌面客户端同时 tail 它
配合会话树导航,你可以随时回退到历史节点分叉尝试,而不影响另一端的进度。
图:会话树视图 —— 多客户端连接时,每个客户端都可以独立导航同一个会话的历史分支
双 SDK 详解:嵌入式 vs 远程式
Caveman Code 提供两套 SDK,对应两种集成形态:
1️⃣ 嵌入式 SDK:@juliusbrussee/caveman-code
SDK 直接包含在主包 caveman 中,无需单独安装。它通过 createAgentSession() 在同一 Node.js 进程内创建 Agent 会话,提供类型安全的 prompt()、steer()、事件订阅等完整 API。
适合:构建自定义 UI(Web/桌面/移动)、把 Agent 能力嵌入现有应用、自动化流水线。
const { session } = await createAgentSession();
session.subscribe((event) => {
if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
process.stdout.write(event.assistantMessageEvent.delta);
}
});
await session.prompt("What files are in the current directory?");
完整示例从最简到全控制在 examples/sdk/ 目录下,推荐从 01-minimal.ts 读起。
2️⃣ 远程 SDK:@juliusbrussee/caveman-sdk
这是一个轻量 TypeScript 客户端,对接 caveman serve 守护进程的 OpenAPI 3.1 规范(规范文件见 openapi.yaml):
npm install @juliusbrussee/caveman-sdk
import { CaveClient } from "@juliusbrussee/caveman-sdk";
const client = new CaveClient({ host: "localhost:39245" });
const session = await client.sessions.create({ model: "claude-sonnet-4" });
await session.prompt("explain this codebase");
for await (const ev of session.events()) {
console.log(ev);
}
核心实现见 client.ts 与 protocol.ts。
3️⃣ 跨语言集成?用 RPC 模式
如果你不用 TypeScript(Python、Go 等),或想要进程隔离,可以走 JSON-over-stdin/stdout 的 RPC 协议:
pi --mode rpc --no-session
RPC 模式以严格 JSONL 帧格式通信,命令走 stdin、事件流走 stdout,完整协议(prompt、steer、fork、compact 等 30+ 命令)见 docs/rpc.md。
选型速查表
| 维度 | 嵌入式 SDK | 远程 SDK | RPC 模式 |
|---|---|---|---|
| 部署形态 | 同一 Node.js 进程 | 连接 caveman serve 守护进程 |
子进程 + JSONL |
| 类型安全 | ✅ | ✅ | ❌(手动解析) |
| 跨语言 | ❌ | 部分(需 TS) | ✅ |
| 进程隔离 | ❌ | ✅ | ✅ |
| 典型场景 | 自定义 UI/流水线 | 多端连接 Agent 服务 | 语言无关客户端 |
SSH 断线也能续:守护模式的杀手锏
守护模式会话持久化在 SQLite,天然抗断线:
ssh box
caveman serve &
caveman attach <id>
# —— SSH 掉线 ——
ssh box
caveman attach <id> # 精确从断点继续
正在执行中的工具调用会完整跑完,重新 attach 时自动重放错过的全部事件。
常见问题速答
Q:守护模式是默认开启的吗?
不是。Daemon 是 opt-in 设计,绝大多数用户直接运行 caveman 即可,需要服务端能力时才 caveman serve。
Q:如何优雅停止守护进程?
caveman serve stop
caveman serve --pid-file ~/.cave/serve.pid stop
前台模式直接 Ctrl+C 即可,活跃会话会自动检查点到磁盘。
Q:还能给 Agent 加外部工具吗?
能。Caveman Code 是一等公民的 MCP 客户端,也支持把自己作为 MCP Server(caveman mcp-server)暴露给 Claude Desktop、Codex 等其他 Agent,详见 docs/reference/mcp.md。
延伸阅读
- 守护模式官方文档:docs/reference/daemon.md
- Daemon 源码:packages/coding-agent/src/core/daemon/
- CLI 命令入口:serve.ts、attach.ts、worker.ts
- 嵌入式 SDK 文档:docs/sdk.md
- RPC 协议文档:docs/rpc.md
- 远程 SDK 包:packages/sdk/
📌 项目说明:本仓库当前处于 Frozen 状态(仍可用),活跃开发已迁移至 JuliusBrussee/caveman(caveman wrap)。如需最新特性,请关注上游仓库。
按这份指南走下来,你已经掌握了 Caveman Code Agent 服务的全部核心能力:守护模式部署 → 远程访问安全配置 → Worker GPU 托管 → 多端结对 → 双 SDK 选型。从单机脚本到 GPU 集群,Caveman Code 都能以 1/1.93 的 token 成本,稳定跑通你的自动化编程流水线。

