docs(patrol): admin API cron paths, restart endpoint, API key users, CardKit v2

docs/explanation/security-model.md

@@ -42,7 +42,9 @@ HotPlex Gateway 的安全模型遵循两条核心原则：
 
 ### Layer 2：Authentication（认证）
 
-- **API Key**：Gateway 级别的访问控制
+- **API Key**：Gateway 级别的访问控制。支持两种解析模式：
+  - **默认模式**：所有有效 Key 映射到 `api_user`（单用户场景）
+  - **企业模式**（APIKeyResolver）：通过数据库映射将 Key 关联到具体用户身份，实现多用户 Session 隔离。支持 `MapResolver`（配置文件）和 `DBResolver`（SQLite）两种实现
 - **JWT**：Session 级别的身份验证，携带 `user_id`、`bot_id`、`scopes`
 
 ### Layer 3：Input Validation（输入验证）

docs/reference/admin-api.md

@@ -49,8 +49,8 @@ admin:
 | `stats:read` | - | - | 🟢 Read | - | - | - | `GET /admin/stats`<br>`GET /admin/metrics` |
 | `config:read` | - | - | - | 🟢 Read | - | - | `POST /admin/config/validate` |
 | `config:write` | - | - | - | 🟠 Write | - | - | `POST /admin/config/rollback` |
-| `admin:read` | - | - | - | - | 🟢 Read | 🟢 Read | `GET /admin/logs`<br>`GET /admin/debug/...`<br>`GET /admin/bots`<br>`GET /api/cron/jobs` |
-| `admin:write` | - | - | - | - | - | 🟠 Write | `POST/PATCH/DELETE /api/cron/jobs`<br>`POST /api/cron/jobs/{id}/run` |
+| `admin:read` | - | - | - | - | 🟢 Read | 🟢 Read | `GET /admin/logs`<br>`GET /admin/debug/...`<br>`GET /admin/bots`<br>`GET /admin/cron/jobs`<br>`GET /admin/api-keys` |
+| `admin:write` | - | - | - | - | - | 🟠 Write | `POST/PATCH/DELETE /admin/cron/jobs`<br>`POST /admin/cron/jobs/{id}/run`<br>`POST/PATCH/DELETE /admin/api-keys`<br>`POST /admin/restart` |
 
 > 💡 **图例**：🟢 **Read** (只读查询) | 🟠 **Write** (状态变更/操作) | 🔴 **Delete** (物理删除)
 
@@ -152,13 +152,13 @@ curl -X POST -H "Authorization: Bearer $TOKEN" \
 
 | 方法 | 路径 | Scope | 说明 |
 |------|------|-------|------|
-| GET | `/api/cron/jobs` | `admin:read` | 列出所有任务 |
-| GET | `/api/cron/jobs/{id}` | `admin:read` | 获取单个任务 |
-| POST | `/api/cron/jobs` | `admin:write` | 创建任务 |
-| PATCH | `/api/cron/jobs/{id}` | `admin:write` | 更新任务 |
-| DELETE | `/api/cron/jobs/{id}` | `admin:write` | 删除任务 |
-| POST | `/api/cron/jobs/{id}/run` | `admin:write` | 手动触发执行 |
-| GET | `/api/cron/jobs/{id}/runs` | `admin:read` | 执行历史 |
+| GET | `/admin/cron/jobs` | `admin:read` | 列出所有任务 |
+| GET | `/admin/cron/jobs/{id}` | `admin:read` | 获取单个任务 |
+| POST | `/admin/cron/jobs` | `admin:write` | 创建任务 |
+| PATCH | `/admin/cron/jobs/{id}` | `admin:write` | 更新任务 |
+| DELETE | `/admin/cron/jobs/{id}` | `admin:write` | 删除任务 |
+| POST | `/admin/cron/jobs/{id}/run` | `admin:write` | 手动触发执行 |
+| GET | `/admin/cron/jobs/{id}/runs` | `admin:read` | 执行历史 |
 
 Cron 未启用时返回 `503 Service Unavailable`。
 
@@ -189,6 +189,34 @@ Bot 状态查询、配置管理和 Agent 配置文件操作端点。
 
 **PUT /admin/bots/{name}/config/{file}`** — 写入指定 Agent 配置文件（如 `SOUL.md`、`AGENTS.md`、`USER.md`）。请求体为文件内容，Content-Type 为 `text/plain`。
 
+### 网关重启
+
+| 方法 | 路径 | Scope | 说明 |
+|------|------|-------|------|
+| POST | `/admin/restart` | `admin:write` | 触发网关重启 |
+
+**POST /admin/restart** — 异步触发网关重启。Gateway 在 500ms 延迟后执行重启，立即返回 `{ "status": "restarting" }`。使用 `restart helper`（独立 PGID）确保安全隔离。未配置 restart handler 时返回 `503`。
+
+### API Key 用户管理
+
+管理 API Key 到用户身份的映射，用于企业级多用户 Session 隔离。需要数据库支持（SQLite），未配置 DB resolver 时返回 `501 Not Implemented`。
+
+| 方法 | 路径 | Scope | 说明 |
+|------|------|-------|------|
+| GET | `/admin/api-keys` | `admin:read` | 列出所有 API Key 映射 |
+| POST | `/admin/api-keys` | `admin:write` | 创建 API Key 映射 |
+| GET | `/admin/api-keys/{id}` | `admin:read` | 获取单个映射详情 |
+| PATCH | `/admin/api-keys/{id}` | `admin:write` | 更新映射 |
+| DELETE | `/admin/api-keys/{id}` | `admin:write` | 删除映射 |
+
+**POST /admin/api-keys** — 创建 API Key → UserID 映射。JSON body 含 `user_id`（必填，最长 128 字符）和 `description`（可选，最长 512 字符）。API Key 由系统自动生成（32 字节随机 hex）。返回 `201 Created`。
+
+**GET /admin/api-keys** — 返回所有映射列表，`api_key` 字段自动脱敏（仅显示前 8 + 后 4 位）。
+
+**PATCH /admin/api-keys/{id}`** — 更新指定映射的 `user_id` 和 `description`。
+
+**DELETE /admin/api-keys/{id}`** — 物理删除映射，同时清除缓存的 resolver 条目。
+
 ## Gateway API 端点
 
 Gateway API（`/api/sessions`）监听在网关主端口（`8888`），面向客户端 SDK 和 WebSocket 连接，使用 API Key 或 JWT 认证（非 Bearer Token）。
@@ -205,13 +233,13 @@ Gateway API（`/api/sessions`）监听在网关主端口（`8888`），面向客
 
 所有 Gateway API 端点启用 CORS（`Access-Control-Allow-Origin: *`），支持 `GET`、`POST`、`DELETE`、`OPTIONS` 方法。
 
-**POST /api/cron/jobs** — JSON body 含 `name`、`schedule`（cron:/every:/at: 前缀）、`message`、`bot_id`、`owner_id`、`enabled`。返回 `201 Created`。
+**POST /admin/cron/jobs** — JSON body 含 `name`、`schedule`（cron:/every:/at: 前缀）、`message`、`bot_id`、`owner_id`、`enabled`。返回 `201 Created`。
 
-**PATCH /api/cron/jobs/{id}** — 部分更新，JSON body。返回 `204 No Content`。
+**PATCH /admin/cron/jobs/{id}** — 部分更新，JSON body。返回 `204 No Content`。
 
-**POST /api/cron/jobs/{id}/run** — 手动触发（异步），返回 `202 Accepted`。
+**POST /admin/cron/jobs/{id}/run** — 手动触发（异步），返回 `202 Accepted`。
 
-**GET /api/cron/jobs/{id}/runs** — 查询执行历史。
+**GET /admin/cron/jobs/{id}/runs** — 查询执行历史。
 
 ## 错误响应格式
 
@@ -255,5 +283,5 @@ curl -H "Authorization: Bearer $TOKEN" \
 
 # 触发 Cron 任务
 curl -X POST -H "Authorization: Bearer $TOKEN" \
-  http://localhost:9999/api/cron/jobs/daily-health/run
+  http://localhost:9999/admin/cron/jobs/daily-health/run
 ```

docs/tutorials/feishu-integration.md

@@ -243,9 +243,9 @@ HOTPLEX_MESSAGING_TTS_MAX_CHARS=150
 <details>
 <summary>交互与指示器</summary>
 
-**权限交互**：Bot 发送确认卡片时，用户直接回复文本「允许」或「拒绝」即可，无需点击按钮。
+**权限交互**：Bot 发送确认卡片时，用户直接回复文本「允许」或「拒绝」即可。
 
-**Typing 指示器**：Bot 收到消息后自动添加 👀 emoji reaction，回复完成后自动移除。
+**选项交互**：当 Bot 发送多选项问题（如 AskUserQuestion）时，卡片包含可点击的复制按钮。点击按钮自动复制选项文本到剪贴板，粘贴发送即可响应。也可直接手动输入选项文本或自定义答案。
 
 这些行为为内置默认，无需额外配置。