docs(userguide): 增加 Daemon RPC 接口章节

记录 bat.sock JSON-RPC 2.0 控制面：统一 envelope（ok/status/data/error/request_id）、
方法命名空间与实现状态（daemon.*/resource.*/task.* 已实现，catalog/patch/unityfs
及 task.cancel/logs 返回 700003）、异步任务模型（resource.sync/verify 返回 task_id、
task.status/list 轮询）和调用示例。

对应 issue #1（协议文档）。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

USERGUIDE.md

@@ -220,3 +220,74 @@ HTTPS_PROXY=http://user:pass@127.0.0.1:7890 bat --auto-discover --daemon
 | `BAT-ERR-900001` | internal | 否 | 未归类的内部错误 |
 
 新增错误码在 `core/src/error_code.rs` 的码表登记后，同步更新本表。
+
+---
+
+## 6. Daemon RPC 接口
+
+`bat --daemon` 在后台状态目录下创建 `bat.sock`（Unix socket），提供**换行分隔的 JSON-RPC 2.0** 控制面。CLI 的 `status`/`stop`/`logs`/`reload`/`refresh` 优先走它；Go 服务层也应通过这个进程边界调用，而非 FFI。
+
+### 传输与 envelope
+
+- 请求：一行 JSON-RPC 2.0，`{"jsonrpc":"2.0","id":<n>,"method":"<ns>.<action>","params":{…}}`。
+- 响应：JSON-RPC 2.0，应用层负载统一装入 `result` 的 envelope：
+
+  ```json
+  {"jsonrpc":"2.0","id":1,"result":{
+    "ok": true,
+    "status": "ok",
+    "data": { … },
+    "request_id": "req-<pid>-<seq>"
+  }}
+  ```
+
+  - `ok`：应用层成功与否。失败时 `ok=false`、`status="error"`、`error` 为 §5 的 `ApiError` 结构（含 `BAT-ERR` 码）。
+  - `status`：`ok` | `accepted`（长任务已入队） | `error`。
+  - `request_id`：进程内唯一请求 ID。
+  - 请求解析失败（畸形 JSON）走 JSON-RPC 顶层 `error`（如 `-32700`），不进 envelope。
+
+### 方法命名空间
+
+方法采用 `<namespace>.<action>`。`bat.*` 为兼容别名（解析为 `daemon.*`）。
+
+| 方法 | 状态 | 说明 |
+|---|---|---|
+| `daemon.status` | ✅ | 后台状态快照 |
+| `daemon.logs` | ✅ | 日志尾部（`params.tail`，默认 200） |
+| `daemon.stop` | ✅ | 请求停止（`accepted`） |
+| `daemon.reload` | ✅ | 请求重新发现并强制刷新（`accepted`） |
+| `daemon.refresh` | ✅ | 请求刷新检查（`params.force`，`accepted`） |
+| `resource.state` | ✅ | 资源发布根 + 版本状态 + 上次同步结果 |
+| `resource.sync` | ✅ | 触发同步任务（`params.force`），返回 `task_id` |
+| `resource.verify` | ✅ | 触发校验任务（dry-run + audit），返回 `task_id` |
+| `task.status` | ✅ | 查询任务（`params.task_id`） |
+| `task.list` | ✅ | 列出全部任务（最新在前） |
+| `catalog.*` / `patch.*` / `unityfs.*` / `task.cancel` / `task.logs` | ⏳ | 已规划，返回 `BAT-ERR-700003`（not implemented） |
+| 未知方法 | — | `BAT-ERR-700001`（unknown method） |
+
+### 任务模型
+
+`resource.sync` / `resource.verify` 是**异步任务**：入队即返回 `{ "task_id": "task-<pid>-<seq>", "kind": "resource.sync" }`（`status: "accepted"`），实际执行由后台任务 worker 串行完成，通过 `task.status` / `task.list` 轮询。任务记录：
+
+```json
+{ "id": "task-1234-1", "kind": "resource.sync",
+  "status": "queued|running|succeeded|failed",
+  "stage": "download", "message": "…",
+  "created_at": …, "updated_at": …, "started_at": …, "finished_at": …,
+  "error": { … }, "result": { … } }
+```
+
+- 与后台 watch 循环的定时同步通过进程内锁互斥（任务等待而非失败）。
+- 任务目前**仅存内存**，随 daemon 生死；持久化（重启后仍可查）为后续工作。
+
+### 示例
+
+```bash
+# 触发同步任务并取回 task_id（socat 演示）
+printf '{"jsonrpc":"2.0","id":1,"method":"resource.sync","params":{"force":true}}\n' \
+  | socat - UNIX-CONNECT:/tmp/bat-pid/bat.sock
+
+# 轮询任务
+printf '{"jsonrpc":"2.0","id":2,"method":"task.status","params":{"task_id":"task-1234-1"}}\n' \
+  | socat - UNIX-CONNECT:/tmp/bat-pid/bat.sock
+```