Caveman Code 终极指南:Daemon 守护模式与双SDK远程结对编程,从本地到 GPU 集群的完整实践

原创2026-10-23 22:09:391,977 阅读

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 终端 Agent 界面,展示守护模式下流式输出与实时状态

图: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 它

配合会话树导航,你可以随时回退到历史节点分叉尝试,而不影响另一端的进度。

Caveman Code 会话树视图,展示多客户端共享的 Agent 对话历史与分支

图:会话树视图 —— 多客户端连接时,每个客户端都可以独立导航同一个会话的历史分支

双 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。

延伸阅读

📌 项目说明:本仓库当前处于 Frozen 状态(仍可用),活跃开发已迁移至 JuliusBrussee/caveman(caveman wrap)。如需最新特性,请关注上游仓库。

按这份指南走下来,你已经掌握了 Caveman Code Agent 服务的全部核心能力:守护模式部署 → 远程访问安全配置 → Worker GPU 托管 → 多端结对 → 双 SDK 选型。从单机脚本到 GPU 集群,Caveman Code 都能以 1/1.93 的 token 成本,稳定跑通你的自动化编程流水线。

登录后查看全文
caveman-code