Prewarm 预热进程使用说明 ​

适用：@tencent-ai/codebuddy-code（cbc / codebuddy）

预热进程让 cbc 先把冷启动跑完并挂起（加载 bundle → 容器初始化 → 认证 → 产品配置 → MCP 发现），之后通过本地 IPC 唤醒时只需绑定工作目录即可立即服务。 适合需要"秒级拉起会话"的场景（如 serve/acp 网关、会话池、调度器预拉起）。

收益：本机实测单次会话的启动等待从约 3.7s 降至 ~1ms。

默认关闭。仅在显式传 --prewarm 时启用，不影响任何现有用法。

快速上手 ​

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

bash
cbc --prewarm --prewarm-id pool1

进程会跑完冷启动，然后在本地 IPC 端点挂起待命（不绑定工作目录）：

  • macOS / Linux：unix socket /tmp/codebuddy-prewarm-pool1.sock（权限 0600，仅当前用户）
  • Windows：named pipe \\.\pipe\codebuddy-prewarm-pool1

--prewarm-id 可省略，默认用进程 PID 作为标识。

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

cbc-prewarm 是一个纯 Node 零依赖的轻量命令，不加载主程序 bundle，毫秒级返回。

bash
# 列出当前机器上发现的预热进程
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 : /tmp/codebuddy-prewarm-<id>.sock
Windows     : \\.\pipe\codebuddy-prewarm-<id>

消息 ​

jsonc
// 探活
{ "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": "..." }

activate 只允许成功一次；重复 activate 返回 { ok: false, error: "already activated" }。

Node.js 示例 ​

js
const net = require('net');

function prewarmAddr(id) {
  return process.platform === 'win32'
    ? `\\\\.\\pipe\\codebuddy-prewarm-${id}`
    : `/tmp/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: '...' }

行为与约束 ​

  • 一进程一会话：每个预热进程一生只绑定一次工作目录（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。

相关 ​