帮你快速理解、总结文档立即下载
文档中心>WorkBuddy Enterprise>CodeBuddy>CodeBuddy Code>参考文档>Prewarm 预热进程

Prewarm 预热进程

最近更新时间：2026-08-26 17:59:31
我的收藏

本页目录：

说明：
适用：@tencent-ai/codebuddy-code（cbc / codebuddy）
预热进程让 cbc 先把冷启动跑完并挂起（加载 bundle → 容器初始化 → 认证 →产品配置 → MCP 发现），之后通过本地 IPC 唤醒时只需绑定工作目录即可立即服务。适合需要"秒级拉起会话"的场景（如 serve/acp 网关、会话池、调度器预拉起）。
收益：本机实测单次会话的启动等待从约 3.7s 降至 ~1ms。
说明：
默认关闭。仅在显式传 --prewarm 时启用，不影响任何现有用法。

快速上手

1. 启动一个预热进程（待命）

cbc --prewarm --prewarm-id pool1
进程会跑完冷启动，然后在本地 IPC 端点挂起待命（不绑定工作目录）：
macOS / Linux：unix socket /tmp/codebuddy-prewarm-pool1.sock（权限 0600，仅当前用户；
落盘目录可用 env CODEBUDDY_CODE_PREWARM_SOCKET_PATH 覆盖）
Windows：named pipe \\\\.\\pipe\\codebuddy-prewarm-pool1
--prewarm-id 可省略，默认用进程 PID 作为标识。

2. 查看 / 唤醒（轻量管理命令 cbc-prewarm）

cbc-prewarm 是一个纯 Node 零依赖的轻量命令，不加载主程序 bundle，毫秒级返回。
# 列出当前机器上发现的预热进程
cbc-prewarm list

# 探活
cbc-prewarm ping pool1

# 查询状态（idle / activating / active）
cbc-prewarm status pool1

# 唤醒：绑定到目标工作目录并开始服务
cbc-prewarm activate pool1 --cwd /path/to/project -- --serve
activate 的 -- 之后的参数会透传给被唤醒的进程（等价于正常 cbc <args>）。唤醒后该进程 chdir 到 --cwd、按透传参数进入对应模式（如 --serve / --acp），并主动关闭 IPC socket（一次性唤醒，之后通过它自己的服务端口对外）。
--cwd 可选：省略时预热进程保持冷启动时的工作目录（不 chdir、不广播 cwd 变更），适用于调用方无需切换目录、只想复用已预热容器的场景。需要绑定到特定项目目录时才传 --cwd。
模式不受限：透传参数可以是任意正常 cbc 参数，--serve、--acp 等常驻模式都原样生效，预热进程对模式没有任何限制或改写。需要常驻服务就传 --serve / --acp；不传常驻模式标志时走一次性命令路径，执行完即退出（headless 且无 TTY）。

外部程序集成（IPC 协议）

若想在自己的程序里唤醒预热进程，直接连本地 socket / pipe 发一行 JSON（NDJSON，每行一条），读一行 JSON 响应。

地址约定

macOS/Linux : <dir>/codebuddy-prewarm-<id>.sock   （<dir> 默认 /tmp）
Windows     : \\\\.\\pipe\\codebuddy-prewarm-<id>
unix socket 落盘目录默认 /tmp，可通过 env CODEBUDDY_CODE_PREWARM_SOCKET_PATH 覆盖（如 /tmp 被 noexec / 只读挂载，或需放进受控目录时）。进程侧与客户端侧读取同一 env 保持同构。Windows named pipe 命名空间无目录概念，不受该 env 影响。

消息

// 探活
{ "cmd": "ping" }
// → { "ok": true, "cmd": "ping", "status": "idle", "pid": 12345 }

// 查询状态
{ "cmd": "status" }
// → { "ok": true, "status": "idle"|"activating"|"active", "cwd": "...", "endpoint": "..." }

// 唤醒（cwd 可选——省略则保持冷启动 cwd；args 为透传给 cbc 的参数）
{ "cmd": "activate", "cwd": "/path/to/project", "args": ["--serve"], "sessionId": "可选" }
// → { "ok": true, "cmd": "activate", "status": "activating", "cwd": "..." }

// 唤醒并等待 ACP 业务就绪（opt-in；建议配合 --port 0）
{
  "cmd": "activate",
  "ackMode": "ready",
  "cwd": "/path/to/project",
  "args": ["--serve", "--port", "0"],
  "sessionId": "session-1"
}
// → ACP /api/v1/acp 初始化完成后才响应：
// {
//   "ok": true,
//   "cmd": "activate",
//   "status": "active",
//   "pid": 12345,
//   "sessionId": "session-1",
//   "cwd": "/path/to/project",
//   "endpoint": "http://127.0.0.1:54321/api/v1/acp"
// }
activate 只允许成功一次；重复 activate 返回 { ok: false, error: "already activated" }。
ackMode 默认省略，保持向后兼容的 immediate ACK：IPC server 收到请求即返回 status: "activating"，不代表 HTTP listener 或 ACP 路由已经可用。需要把 endpoint 直接交给下游客户端的宿主应显式传 "ackMode": "ready"：
子进程用 --port 0 让内核分配无竞争端口。
响应会延迟到 HTTP listener 已启动且 ACP /api/v1/acp 完成初始化。
ready 响应携带实际非零端口、pid 与原样回传的 sessionId，调用方应校验三者。
ready ACK 刷出后，预热 IPC 会关闭并清理；后续通信改走返回的 ACP endpoint。
调用方应使用覆盖完整冷启动的超时窗口；WorkBuddy 默认等待 180 秒。连接提前断开时
agent-cli 不会自行终止已经 ready 的 serve 进程；宿主仍应回收无法接管的进程。

Node.js 示例

const net = require('net');

function prewarmAddr(id) {
  if (process.platform === 'win32') {
    return `\\\\\\\\.\\\\pipe\\\\codebuddy-prewarm-${id}`;
  }
  const dir = (process.env.CODEBUDDY_CODE_PREWARM_SOCKET_PATH || '').trim() || '/tmp';
  return require('path').join(dir, `codebuddy-prewarm-${id}.sock`);
}

function activate(id, { cwd, args = [] }) {
  return new Promise((resolve, reject) => {
    const sock = net.connect(prewarmAddr(id), () => {
      sock.write(JSON.stringify({ cmd: 'activate', cwd, args }) + '\\n');
    });
    let buf = '';
    sock.on('data', d => {
      buf += d;
      const nl = buf.indexOf('\\n');
      if (nl >= 0) { sock.end(); resolve(JSON.parse(buf.slice(0, nl))); }
    });
    sock.on('error', reject);
  });
}

// 唤醒 pool1，绑定目标目录并以 serve 模式启动
const res = await activate('pool1', { cwd: '/Users/me/project-A', args: ['--serve'] });
console.log(res); // { ok: true, cmd: 'activate', status: 'activating', cwd: '...' }
上例展示默认 immediate ACK。若需要 ACP-ready 边界，把发送内容改为：
sock.write(JSON.stringify({
  cmd: 'activate',
  ackMode: 'ready',
  sessionId: 'session-1',
  cwd,
  args: ['--serve', '--port', '0'],
}) + '\\n');

行为与约束

一进程一会话：每个预热进程一生只绑定一次工作目录（activate 那一刻），用完即弃。需要服务多个目录时，预热多个进程（不同 --prewarm-id），各自独立、互不影响。
工作目录隔离：activate 后会 chdir 并广播 cwd 变更，文件监听自动重绑、项目级缓存（设置 / 记忆 / 技能 / 插件 / 产品配置）自动失效重扫，确保不会读到预热期临时目录的旧配置。
USER 级配置共享：~/.codebuddy/ 下的用户级设置 / 认证 / MCP 在所有预热进程间天然共享。
安全：unix socket 权限收紧为 0600（仅属主），防止同机其他用户连接劫持。
退出清理：优雅退出（SIGINT/SIGTERM）或 activate 完成后自动清理 socket；SIGKILL 残留的 socket 在下次同 id 启动时会被自动覆盖。

配置方式

预热相关参数只能通过 CLI flag 配置：--prewarm / --prewarm-id <id> / --prewarm-force。
此外可通过 env 覆盖 unix socket 落盘目录：
env
作用
默认
CODEBUDDY_CODE_PREWARM_SOCKET_PATH
自定义 unix socket 落盘目录（如 /dev/abc/，尾斜杠可有可无）。进程侧创建 + 客户端连接读取同一 env。仅 unix；Windows named pipe 不受影响
/tmp

相关

CLI 参数总表：cli-reference.md

中国站