注意：说明：
注意：适用：@tencent-ai/codebuddy-code（cbc / codebuddy）
收益：本机实测单次会话的启动等待从约 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