Daemon 模式与后台会话

Daemon 模式让 CodeBuddy Code 以后台常驻服务的方式运行，不依赖终端窗口。启动后提供完整的 HTTP API 和 Web UI，随时接受请求。

核心价值：把 CLI 从"用完即走"变成"随时待命"。

概念

概念	说明
Worker	运行中的 CLI 进程，通过 PID 文件注册在 ~/.codebuddy/sessions/
Daemon	后台常驻的 HTTP 服务进程（--serve 模式），通过 daemon start 管理
后台会话 (bg)	通过 --bg 启动的非交互式任务，自动输出日志到文件

Daemon 管理

启动 Daemon

# 启动 daemon（后台运行，自动分配端口）
codebuddy daemon start

# 指定端口
codebuddy daemon start --port 8080

# 指定绑定地址（允许远程访问）
codebuddy daemon start --host 0.0.0.0

Daemon 启动后以 detached 进程运行，父进程立即退出。本地地址默认免密访问，非本地地址自动开启密码认证。

幂等启动：多次执行 daemon start 不会创建多个 daemon。如果已有 daemon 在运行，会直接返回现有 daemon 的信息。

查看状态

codebuddy daemon status
# {"status":"running","pid":12345,"endpoint":"http://127.0.0.1:51862","startedAt":1775498920401}

停止 / 重启

codebuddy daemon stop
codebuddy daemon restart

后台会话

启动后台任务

# 后台执行任务
codebuddy --bg "实现登录页面"

# 指定名称（便于查找）
codebuddy --bg --name feature-login "实现登录页面"

后台会话以 --print -y 模式运行（无 TUI + 跳过权限确认），stdout/stderr 重定向到 ~/.codebuddy/logs/{name}.log。

进程管理命令

# 列出所有活跃 Worker
codebuddy ps

# 查看后台会话日志
codebuddy logs feature-login

# 持续跟踪日志（类似 tail -f）
codebuddy logs feature-login -f

# 附加到后台会话
codebuddy attach feature-login

# 终止后台会话
codebuddy kill feature-login

HTTP API

所有 Worker 和 Daemon 管理能力通过 REST API 暴露，Web UI 的 Workers 页面基于这些 API 构建。

详见 HTTP API 文档 中的 Workers & Daemon 章节。

示例

# 列出所有 Worker
curl http://127.0.0.1:8080/api/v1/workers

# 启动 Daemon
curl -X POST http://127.0.0.1:8080/api/v1/daemon/start \
  -H "Content-Type: application/json" \
  -d '{"port": 9090}'

# 查看 Worker 日志（遥测日志）
curl "http://127.0.0.1:8080/api/v1/workers/12345/logs?type=telemetry&tail=100"

# 终止 Worker
curl -X DELETE http://127.0.0.1:8080/api/v1/workers/12345

Web UI

--serve 模式启动后，Web UI 提供三个管理页面：

• Workers — Worker 进程管理和 Daemon 控制
• Logs — 独立日志查看器，支持 Worker 选择、日志类型切换、关键词搜索
• Metrics — 系统资源监控和各 Worker 进程级指标

日志体系

日志 API 支持 4 种类型，按优先级自动选择：

类型	路径	内容	触发条件
telemetry	~/.codebuddy/logs/{date}/{workspace}.log	所有模块的 Info/Warn/Error	始终（默认优先）
process	~/.codebuddy/logs/{name}.log	进程 stdout/stderr	仅 bg/daemon
debug	~/.codebuddy/debug/{sessionId}.txt	详细调试信息	需 --debug
transcript	~/.codebuddy/projects/{id}/{sessionId}.jsonl	对话历史	始终

PID 文件注册表

每个 CLI 进程启动时在 ~/.codebuddy/sessions/ 注册 PID 文件：

~/.codebuddy/sessions/
├── 12345.json          # 本地进程（PID 作为文件名）
├── 67890.json          # 另一个本地进程
└── manual-abc123.json  # 手动添加的远程 Worker

PID 文件内容：

{
  "pid": 12345,
  "sessionId": "interactive-12345",
  "cwd": "/home/user/project",
  "startedAt": 1775498920401,
  "kind": "interactive",
  "url": "http://127.0.0.1:8080",
  "mode": "local",
  "version": "2.78.1",
  "hostname": "my-machine"
}

进程存活通过 kill -0 检测，手动远程 Worker 通过心跳超时检测（2 分钟）。

环境变量

变量	说明
CODEBUDDY_SESSION_KIND	Worker 类型（interactive / bg / daemon）
CODEBUDDY_SESSION_NAME	后台会话显示名称
CODEBUDDY_SESSION_LOG	后台会话日志路径
CODEBUDDY_GATEWAY_AUTH	认证模式（none / password）

使用场景

开发服务器常驻

日常开发时启动一次 daemon，之后通过浏览器或 API 随时与 AI 交互，不用每次都打开终端。

codebuddy daemon start --port 8080
# 浏览器打开 http://127.0.0.1:8080 即可使用
# 关闭终端后服务仍在运行

CI/CD 自动化后端

在 CI 流水线中启动 daemon 作为 Agent 服务，其他步骤通过 HTTP API 调用它执行代码审查、测试生成等任务。

# CI 启动
codebuddy daemon start --port 9090

# 其他 CI 步骤调用
curl -X POST http://127.0.0.1:9090/api/v1/runs \
  -H "Content-Type: application/json" \
  -d '{"prompt": "审查这个 PR 的代码变更"}'

多人共享 Agent

一台开发机上启动 daemon 绑定局域网地址，团队成员通过 Web UI 共同使用同一个 Agent 环境。

codebuddy daemon start --host 0.0.0.0 --port 8080
# 同事访问 http://192.168.1.100:8080

后台批量任务

用 --bg 同时启动多个后台会话处理不同任务，通过 ps/logs/kill 管理。

codebuddy --bg --name "refactor-auth" "重构认证模块"
codebuddy --bg --name "add-tests" "给 utils 目录补充单元测试"
codebuddy --bg --name "fix-types" "修复所有 TypeScript 类型错误"

# 查看进度
codebuddy ps
codebuddy logs refactor-auth

微信/企业微信机器人后端

daemon 常驻运行作为聊天机器人的后端服务，通过长连接接收消息。

codebuddy daemon start
# 配合远程控制功能连接微信/企业微信渠道

IDE 扩展后端

IDE 插件通过 ACP 协议连接到 daemon，提供 AI 编程辅助，避免每次打开 IDE 都重新启动 CLI 进程。

与 --serve 的区别

特性	--serve	daemon start
生命周期	跟随终端，关闭终端则退出	后台常驻，独立于终端
启动方式	前台运行	fork detached 子进程
管理方式	Ctrl+C 停止	daemon stop/status/restart
多次启动	每次创建新进程	幂等，只维护一个 daemon
典型用途	临时开发调试	长期运行的服务