# Daemon 模式与后台会话

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

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

## 概念

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

## Daemon 管理

### 启动 Daemon

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

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

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

# 指定权限模式（默认为 delegate 委托模式）
codebuddy daemon start --permission-mode default

# 传递其他标准参数（model、mcp-config 等会自动继承）
codebuddy daemon start --model claude-sonnet-4-20250514 --mcp-config ./mcp.json
```

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

> **默认委托模式**：Daemon 默认以委托（delegate）模式运行——主 agent 只负责协调调度，不直接修改代码。所有实现工作通过 subagent 完成。可通过 `--permission-mode` 切换为其他模式。

> **参数继承**：`daemon start` 时指定的标准 CLI 参数（`--model`、`--permission-mode`、`--mcp-config`、`--tools`、`--agent`、`--settings` 等）会自动继承到 daemon 子进程中。

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

### 查看状态

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

### 停止 / 重启

```bash
codebuddy daemon stop
codebuddy daemon restart
```

## 后台会话

### 启动后台任务

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

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

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

### 进程管理命令

```bash
# 列出所有活跃 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 文档](http-api.md) 中的 Workers & Daemon 章节。

### 示例

```bash
# 列出所有 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 文件内容：

```json
{
  "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 交互，不用每次都打开终端。

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

### CI/CD 自动化后端

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

```bash
# 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 环境。

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

### 后台批量任务

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

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

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

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

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

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

### IDE 扩展后端

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

## 与 --serve 的区别

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