docs: API 接口清单（从 OpenAPI schema 生成）

58 个接口，按 auth/crawler/creator/data/monitor/settings 分组，逐条列出方法、路径、
是否需要登录、说明、参数（含类型/必填/默认）、请求体 schema；附录展开请求体的字段。

**生成的，不是手写的** —— 手写的接口文档从改代码那天起就开始腐烂，而且烂得无声无息。
`docs/gen_api_doc.py` 只读 app 对象，不连库不起服务。

两处值得说的：

* 鉴权**不能从 schema 里读** —— require_auth 是普通依赖不是 security scheme，不会进
  OpenAPI 的 security 字段。所以那份「哪些路径免登录」的名单是照着 include_router
  核的，而且 auth 那一组不能一刀切（/me 和 /password 各自另有保护）。
* 生成完**顺手验一遍表格**：参数类型里的 `integer | null` 到处是，一个没转义的竖线
  就会把整张表切歪，而 markdown 不报错、只是安静地多一格。验过这个检查确实会拦。

接口的响应没有结构可列 —— 它们返回普通 dict，没声明 response_model。

docs/api.md

@@ -0,0 +1,257 @@
+# API 接口清单
+
+从 FastAPI 自己的 OpenAPI schema 生成的，**不是手写的** ——
+手写的接口文档从改代码那天起就开始腐烂，而且烂得无声无息。
+
+重新生成：
+
+```bash
+./.venv/Scripts/python.exe docs/gen_api_doc.py
+```
+
+## 通用约定
+
+| | |
+|---|---|
+| 前缀 | 所有接口都在 `/api` 下（WebSocket 是 `/api/ws/...`）|
+| 鉴权 | **Cookie 优先，Bearer 次之**：`token_from_request()` 先读会话 Cookie，读不到再读 `Authorization: Bearer <token>`。浏览器用 Cookie，脚本用 Bearer |
+| 会话怎么来 | `POST /api/auth/login`（密码），响应种下会话 Cookie；有效期由服务端 `resolve_session()` 判定 |
+| 错误形状 | FastAPI 默认的 `{"detail": "..."}`；401 是登录失效 |
+| **没有 `/docs`** | 特意关掉的：`/docs`、`/redoc`、`/openapi.json` 默认**不需要登录**，等于把整份接口地图连同「Try it out」一起送出去。要看交互式的，得挂在鉴权后面 |
+| WebSocket | `GET /api/ws/logs`（升级为 ws）—— 实时日志流。**不在这里的清单里**：OpenAPI 描述不了 WebSocket。它自己用 `require_ws_auth` 校验会话 Cookie |
+
+## 目录
+
+- [认证](#认证)（4 个）
+- [采集](#采集)（4 个）
+- [运营（博主账号）](#运营（博主账号）)（8 个）
+- [数据](#数据)（4 个）
+- [监控](#监控)（36 个）
+- [设置](#设置)（2 个）
+
+## 认证
+
+这一组**没有**统一挂 `require_auth`（登录不能要求先登录），所以逐个标。
+
+| 方法 | 路径 | 登录 | 说明 | 参数 | 请求体 |
+|---|---|:--:|---|---|---|
+| `POST` | `/api/auth/login` | — | Login |  | LoginPayload |
+| `POST` | `/api/auth/logout` | — | Logout |  |  |
+| `GET` | `/api/auth/me` | ✓ | Identity probe. The SPA treats a 401 here as "show the login page". |  |  |
+| `POST` | `/api/auth/password` | ✓ | Change the password and log every device out. |  | ChangePasswordPayload |
+
+## 采集
+
+| 方法 | 路径 | 登录 | 说明 | 参数 | 请求体 |
+|---|---|:--:|---|---|---|
+| `GET` | `/api/crawler/logs` | ✓ | Get recent logs | `limit`(query integer 可选=100) |  |
+| `POST` | `/api/crawler/start` | ✓ | Start crawler task. |  | CrawlerStartRequest |
+| `GET` | `/api/crawler/status` | ✓ | Get crawler status |  |  |
+| `POST` | `/api/crawler/stop` | ✓ | Stop crawler task |  |  |
+
+## 运营（博主账号）
+
+| 方法 | 路径 | 登录 | 说明 | 参数 | 请求体 |
+|---|---|:--:|---|---|---|
+| `GET` | `/api/creator/accounts` | ✓ | 账号列表。**不含 cookie**，只给 ``has_cookie``。 |  |  |
+| `DELETE` | `/api/creator/accounts/{account_id}` | ✓ | Delete Account | `account_id`(path integer 必填) |  |
+| `GET` | `/api/creator/accounts/{account_id}` | ✓ | Get Account Detail | `account_id`(path integer 必填) |  |
+| `POST` | `/api/creator/accounts/{account_id}/check` | ✓ | 重测登录态与数据权限。 | `account_id`(path integer 必填) |  |
+| `POST` | `/api/creator/accounts/{account_id}/sync` | ✓ | 拉取作品数据。 | `account_id`(path integer 必填)<br>`days`(query integer 可选=90) |  |
+| `DELETE` | `/api/creator/login` | ✓ | Cancel Login |  |  |
+| `GET` | `/api/creator/login` | ✓ | 轮询扫码结果；一旦成功就把账号落库并返回它。 |  |  |
+| `POST` | `/api/creator/login` | ✓ | Start Login |  |  |
+
+## 数据
+
+| 方法 | 路径 | 登录 | 说明 | 参数 | 请求体 |
+|---|---|:--:|---|---|---|
+| `GET` | `/api/data/download/{file_path}` | ✓ | Download file | `file_path`(path string 必填) |  |
+| `GET` | `/api/data/files` | ✓ | Get data file list | `platform`(query string \| null 可选)<br>`file_type`(query string \| null 可选) |  |
+| `GET` | `/api/data/files/{file_path}` | ✓ | Get file content or preview | `file_path`(path string 必填)<br>`preview`(query boolean 可选=True)<br>`limit`(query integer 可选=100) |  |
+| `GET` | `/api/data/stats` | ✓ | Get data statistics |  |  |
+
+## 监控
+
+| 方法 | 路径 | 登录 | 说明 | 参数 | 请求体 |
+|---|---|:--:|---|---|---|
+| `GET` | `/api/monitor/comment-notes` | ✓ | Works that have comments, newest first, with counts. | `task_id`(query integer \| null 可选)<br>`platform`(query string \| null 可选) |  |
+| `GET` | `/api/monitor/comments` | ✓ | Comments, each carrying the work it belongs to. | `task_id`(query integer \| null 可选)<br>`note_id`(query string \| null 可选)<br>`group_by`(query string \| null 可选)<br>`limit`(query integer 可选=200)<br>`platform`(query string \| null 可选) |  |
+| `DELETE` | `/api/monitor/cookie` | ✓ | Clear Cookie Endpoint | `platform`(query string 可选='xhs') |  |
+| `GET` | `/api/monitor/cookie` | ✓ | Cookie health only -- deliberately never returns the cookie value. | `platform`(query string 可选='xhs') |  |
+| `POST` | `/api/monitor/cookie` | ✓ | Set Cookie Endpoint | `platform`(query string 可选='xhs') | CookiePayload |
+| `GET` | `/api/monitor/covers/{note_id}` | ✓ | 作品封面，从本地缓存读。 | `note_id`(path string 必填) |  |
+| `PUT` | `/api/monitor/creators/{creator_hash}` | ✓ | 给博主起个备注（界面上的「备注」）。 | `creator_hash`(path string 必填)<br>`platform`(query string 可选='xhs') | CreatorAliasPayload |
+| `GET` | `/api/monitor/events` | ✓ | List Events | `task_id`(query integer \| null 可选)<br>`type`(query string \| null 可选)<br>`since_id`(query integer \| null 可选)<br>`limit`(query integer 可选=200)<br>`platform`(query string \| null 可选) |  |
+| `POST` | `/api/monitor/events/read` | ✓ | Mark Events Read | `task_id`(query integer \| null 可选) |  |
+| `GET` | `/api/monitor/export` | ✓ | Download collected data as CSV or Excel. | `kind`(query string 必填)<br>`task_id`(query integer[] \| null 可选)<br>`note_id`(query string \| null 可选)<br>`start_date`(query string \| null 可选)<br>`end_date`(query string \| null 可选)<br>`days`(query integer 可选=7)<br>`format`(query string 可选='csv')<br>`platform`(query string \| null 可选) |  |
+| `DELETE` | `/api/monitor/login/qr` | ✓ | Drop our tab and stop polling. |  |  |
+| `GET` | `/api/monitor/login/qr` | ✓ | Poll the live session: waiting -> success / expired / error. |  |  |
+| `POST` | `/api/monitor/login/qr` | ✓ | Open the login page in the CDP browser and return its QR code. | `platform`(query string 可选='xhs') |  |
+| `GET` | `/api/monitor/login/state` | ✓ | Ask the browser itself whether it is signed in. | `force`(query boolean 可选=False) |  |
+| `GET` | `/api/monitor/notes` | ✓ | List Notes | `task_id`(query integer \| null 可选)<br>`only_new`(query boolean 可选=False)<br>`limit`(query integer 可选=200)<br>`platform`(query string \| null 可选)<br>`tag_id`(query integer[] \| null 可选) |  |
+| `PUT` | `/api/monitor/notes/{note_id}` | ✓ | 给**作品**起个备注。 | `note_id`(path string 必填)<br>`platform`(query string 可选='xhs') | NoteAliasPayload |
+| `GET` | `/api/monitor/notes/{note_id}/series` | ✓ | Metric time series for a single note. | `note_id`(path string 必填)<br>`task_id`(query integer \| null 可选) |  |
+| `PUT` | `/api/monitor/notes/{note_id}/tags` | ✓ | 把一条作品的标签**整体替换**成这一组（空列表 = 全摘掉）。 | `note_id`(path string 必填)<br>`platform`(query string 可选='xhs') | NoteTagsPayload |
+| `GET` | `/api/monitor/overview` | ✓ | Headline numbers for the dashboard tiles, scoped to one platform. | `platform`(query string \| null 可选) |  |
+| `GET` | `/api/monitor/report` | ✓ | Daily new-content counts and interaction deltas for the selected tasks. | `task_id`(query integer[] \| null 可选)<br>`start_date`(query string \| null 可选)<br>`end_date`(query string \| null 可选)<br>`days`(query integer 可选=7)<br>`platform`(query string \| null 可选) |  |
+| `GET` | `/api/monitor/tags` | ✓ | 标签词表 + 各自被用在多少条作品上（删之前能看清代价）。 |  |  |
+| `POST` | `/api/monitor/tags` | ✓ | Create Tag |  | TagPayload |
+| `DELETE` | `/api/monitor/tags/{tag_id}` | ✓ | 删标签，连同它在所有作品上的贴纸。 | `tag_id`(path integer 必填) |  |
+| `PUT` | `/api/monitor/tags/{tag_id}` | ✓ | Update Tag | `tag_id`(path integer 必填) | TagPayload |
+| `GET` | `/api/monitor/tasks` | ✓ | List Tasks | `platform`(query string \| null 可选) |  |
+| `POST` | `/api/monitor/tasks` | ✓ | Create Task |  | MonitorTaskCreate |
+| `DELETE` | `/api/monitor/tasks/{task_id}` | ✓ | Delete Task | `task_id`(path integer 必填) |  |
+| `PATCH` | `/api/monitor/tasks/{task_id}` | ✓ | Update Task | `task_id`(path integer 必填) | MonitorTaskUpdate |
+| `POST` | `/api/monitor/tasks/{task_id}/run` | ✓ | Queue a run immediately and return; the crawl itself takes minutes. | `task_id`(path integer 必填) |  |
+| `GET` | `/api/monitor/tasks/{task_id}/runs` | ✓ | List Runs | `task_id`(path integer 必填)<br>`limit`(query integer 可选=50) |  |
+| `GET` | `/api/monitor/upstream` | ✓ | 最近一次上游检查的结果。 |  |  |
+| `POST` | `/api/monitor/upstream/check` | ✓ | 立刻检查一次上游仓库，并把结果写回缓存。 |  |  |
+| `DELETE` | `/api/monitor/webhook` | ✓ | Clear Webhook |  |  |
+| `GET` | `/api/monitor/webhook` | ✓ | Get Webhook |  |  |
+| `POST` | `/api/monitor/webhook` | ✓ | Set Webhook |  | WebhookPayload |
+| `POST` | `/api/monitor/webhook/test` | ✓ | Send a test message so the user can verify the robot works before relying on it. |  | WebhookTestPayload |
+
+## 设置
+
+| 方法 | 路径 | 登录 | 说明 | 参数 | 请求体 |
+|---|---|:--:|---|---|---|
+| `GET` | `/api/settings` | ✓ | Settings for one platform, plus the system-wide ones. | `platform`(query string 可选='xhs') |  |
+| `PUT` | `/api/settings` | ✓ | Partial update: only the keys present in the body are written. | `platform`(query string 可选='xhs') | SettingsUpdatePayload |
+
+## 请求体结构
+
+### ChangePasswordPayload
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `current` | string | ✓ |  |  |
+| `new` | string | ✓ |  |  |
+
+### CookiePayload
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `cookie` | string | ✓ |  |  |
+
+### CrawlerStartRequest
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `platform` | PlatformEnum | ✓ |  |  |
+| `login_type` | LoginTypeEnum |  | 'qrcode' |  |
+| `crawler_type` | CrawlerTypeEnum |  | 'search' |  |
+| `keywords` | string |  | '' |  |
+| `specified_ids` | string |  | '' |  |
+| `creator_ids` | string |  | '' |  |
+| `start_page` | integer |  | 1 |  |
+| `enable_comments` | boolean |  | True |  |
+| `enable_sub_comments` | boolean |  | False |  |
+| `enable_media` | boolean |  | False |  |
+| `save_option` | SaveDataOptionEnum |  | 'jsonl' |  |
+| `cookies` | string |  | '' |  |
+| `headless` | boolean |  | False |  |
+| `max_notes_count` | integer \| null |  |  |  |
+| `max_comments_count` | integer \| null |  |  |  |
+| `save_data_path` | string \| null |  |  |  |
+| `enable_cdp_mode` | boolean \| null |  |  |  |
+| `inject_all_cookies` | boolean \| null |  |  |  |
+| `save_login_state` | boolean \| null |  |  |  |
+| `cookies_file` | string \| null |  |  |  |
+| `max_concurrency_num` | integer \| null |  |  |  |
+| `crawler_max_sleep_sec` | integer \| null |  |  |  |
+| `enable_ip_proxy` | boolean \| null |  |  |  |
+| `ip_proxy_pool_count` | integer \| null |  |  |  |
+| `ip_proxy_provider_name` | string \| null |  |  |  |
+| `static_proxy_url` | string \| null |  |  |  |
+
+### CreatorAliasPayload
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `alias` | string |  | '' |  |
+
+### LoginPayload
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `password` | string | ✓ |  |  |
+
+### MonitorTaskCreate
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `name` | string | ✓ |  |  |
+| `platform` | string |  | 'xhs' |  |
+| `mode` | string | ✓ |  |  |
+| `interval_minutes` | integer \| null |  |  |  |
+| `schedule_mode` | string |  | 'interval' |  |
+| `schedule_hours` | integer[] |  |  |  |
+| `schedule_days` | integer[] |  |  |  |
+| `schedule_minute` | integer |  | 0 |  |
+| `max_notes_count` | integer \| null |  |  |  |
+| `enable_comments` | boolean |  | True |  |
+| `max_comments_count` | integer \| null |  |  |  |
+| `run_timeout_seconds` | integer |  | 3600 |  |
+| `enabled` | boolean |  | True |  |
+| `notify_enabled` | boolean |  | False |  |
+| `notify_failures` | boolean |  | True |  |
+| `targets` | string[] | ✓ |  |  |
+
+### MonitorTaskUpdate
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `name` | string \| null |  |  |  |
+| `enabled` | boolean \| null |  |  |  |
+| `interval_minutes` | integer \| null |  |  |  |
+| `schedule_mode` | string \| null |  |  |  |
+| `schedule_hours` | integer[] \| null |  |  |  |
+| `schedule_days` | integer[] \| null |  |  |  |
+| `schedule_minute` | integer \| null |  |  |  |
+| `max_notes_count` | integer \| null |  |  |  |
+| `enable_comments` | boolean \| null |  |  |  |
+| `max_comments_count` | integer \| null |  |  |  |
+| `run_timeout_seconds` | integer \| null |  |  |  |
+| `notify_enabled` | boolean \| null |  |  |  |
+| `notify_failures` | boolean \| null |  |  |  |
+| `targets` | string[] \| null |  |  |  |
+
+### NoteAliasPayload
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `alias` | string |  | '' |  |
+
+### NoteTagsPayload
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `tag_ids` | integer[] |  |  |  |
+
+### SettingsUpdatePayload
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+
+### TagPayload
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `name` | string | ✓ |  |  |
+| `color` | string |  | '' |  |
+
+### WebhookPayload
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `url` | string |  | '' | 企业微信机器人 Webhook 地址，留空表示停用 |
+
+### WebhookTestPayload
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|:--:|---|---|
+| `url` | string \| null |  |  | 不传则使用已保存的地址 |
+
+> **响应没有结构可列。** 这些接口返回的是普通 dict，没有声明 `response_model`，所以 OpenAPI 里没有响应的 shape。要看响应就调一次，或者读对应的 `service.py`。
+

docs/gen_api_doc.py

@@ -0,0 +1,275 @@
+# -*- coding: utf-8 -*-
+"""从 FastAPI 自己的 OpenAPI schema 生成 docs/api.md。
+
+**为什么是生成的而不是手写的**：手写的接口文档，从改代码的那天起就开始腐烂，而且烂得
+无声无息 —— 读者还会以为它是对的。这份每次跑一遍就是最新的。
+
+    ./.venv/Scripts/python.exe docs/gen_api_doc.py      # Windows
+    python docs/gen_api_doc.py                          # 服务器/容器里
+
+注意这个脚本**只读** app 对象，不连数据库、不起服务。
+"""
+
+import pathlib
+import re
+import sys
+
+# 让脚本能从仓库根目录跑起来（它自己不在根目录）。
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
+
+from api.main import app  # noqa: E402
+
+OUTPUT = pathlib.Path(__file__).resolve().parent / "api.md"
+
+# **不能从 schema 里读出鉴权** —— `require_auth` 是个普通依赖，不是 security scheme，
+# 所以它不会出现在 OpenAPI 的 security 字段里。这份名单是照 api/routers/ 里实际写的
+# `dependencies=[Depends(require_auth)]` 核出来的：
+#
+#   * auth 那一组整体**不加** require_auth（登录本身就不能要求先登录），但组里
+#     /me 和 /password 各自另有保护 —— 所以不能按「组」一刀切。
+#   * 其它五个 router 都在 include_router 上统一挂了 require_auth。
+PUBLIC_PATHS = {
+    "/api/auth/login",   # 登录本身
+    "/api/auth/logout",  # 清了 cookie 就完事，没有会话也能调
+}
+
+TAG_TITLES = {
+    "auth": "认证",
+    "crawler": "采集",
+    "creator": "运营（博主账号）",
+    "data": "数据",
+    "monitor": "监控",
+    "settings": "设置",
+}
+
+TAG_ORDER = ["auth", "crawler", "creator", "data", "monitor", "settings"]
+
+JSON_METHODS = {"post", "put", "patch"}
+
+BACKSLASH = chr(92)
+PIPE = "|"
+
+
+def first_paragraph(text: str) -> str:
+    """文档字符串的第一段 —— 整篇塞进去会把接口清单淹掉。"""
+    text = (text or "").strip()
+    if not text:
+        return ""
+    return text.split("\n\n")[0].strip()
+
+
+def describe_schema(schema: dict, spec: dict) -> str:
+    """把一个 schema 说成人话：引用就展开名字，数组说成「数组」。"""
+    if not schema:
+        return ""
+    if "$ref" in schema:
+        return schema["$ref"].rsplit("/", 1)[-1]
+    kind = schema.get("type", "")
+    if kind == "array":
+        inner = describe_schema(schema.get("items", {}), spec)
+        return f"{inner}[]"
+    if kind == "object":
+        props = schema.get("properties") or {}
+        return "{" + ", ".join(props.keys()) + "}" if props else "object"
+    if schema.get("anyOf") or schema.get("allOf"):
+        variants = schema.get("anyOf") or schema.get("allOf")
+        return " | ".join(filter(None, (describe_schema(v, spec) for v in variants)))
+    return kind or "?"
+
+
+def param_cell(params: list, spec: dict) -> str:
+    if not params:
+        return ""
+    parts = []
+    for param in params:
+        name = param["name"]
+        where = param["in"]
+        kind = describe_schema(param.get("schema", {}), spec)
+        required = "必填" if param.get("required") else "可选"
+        default = param.get("schema", {}).get("default")
+        suffix = f"={default!r}" if default is not None else ""
+        # 查询参数是前端最常搞错的地方，标出来。
+        parts.append(f"`{name}`({where} {kind} {required}{suffix})")
+    return "<br>".join(parts).replace("|", "\\|")
+
+
+def body_cell(op: dict, spec: dict) -> str:
+    body = op.get("requestBody")
+    if not body:
+        return ""
+    content = body.get("content", {})
+    schema = content.get("application/json", {}).get("schema", {})
+    # anyOf 会拼出 `integer | null` 这种，竖线不转义就会把这行切成两格。
+    return describe_schema(schema, spec).replace("|", "\\|")
+
+
+def render() -> str:
+    spec = app.openapi()
+    paths = spec["paths"]
+
+    by_tag: dict[str, list] = {}
+    for path, operations in paths.items():
+        for method, op in operations.items():
+            if method not in ("get", "post", "put", "patch", "delete"):
+                continue
+            tag = (op.get("tags") or ["其他"])[0]
+            by_tag.setdefault(tag, []).append((path, method, op))
+
+    lines: list[str] = []
+    lines.append("# API 接口清单")
+    lines.append("")
+    lines.append("从 FastAPI 自己的 OpenAPI schema 生成的，**不是手写的** ——")
+    lines.append("手写的接口文档从改代码那天起就开始腐烂，而且烂得无声无息。")
+    lines.append("")
+    lines.append("重新生成：")
+    lines.append("")
+    lines.append("```bash")
+    lines.append("./.venv/Scripts/python.exe docs/gen_api_doc.py")
+    lines.append("```")
+    lines.append("")
+    lines.append("## 通用约定")
+    lines.append("")
+    lines.append("| | |")
+    lines.append("|---|---|")
+    lines.append("| 前缀 | 所有接口都在 `/api` 下（WebSocket 是 `/api/ws/...`）|")
+    lines.append(
+        "| 鉴权 | **Cookie 优先，Bearer 次之**：`token_from_request()` 先读会话 Cookie，"
+        "读不到再读 `Authorization: Bearer <token>`。浏览器用 Cookie，脚本用 Bearer |"
+    )
+    lines.append(
+        "| 会话怎么来 | `POST /api/auth/login`（密码），响应种下会话 Cookie；"
+        "有效期由服务端 `resolve_session()` 判定 |"
+    )
+    lines.append("| 错误形状 | FastAPI 默认的 `{\"detail\": \"...\"}`；401 是登录失效 |")
+    lines.append(
+        "| **没有 `/docs`** | 特意关掉的：`/docs`、`/redoc`、`/openapi.json` 默认"
+        "**不需要登录**，等于把整份接口地图连同「Try it out」一起送出去。要看交互式的，"
+        "得挂在鉴权后面 |"
+    )
+    lines.append(
+        "| WebSocket | `GET /api/ws/logs`（升级为 ws）—— 实时日志流。**不在这里的清单里**："
+        "OpenAPI 描述不了 WebSocket。它自己用 `require_ws_auth` 校验会话 Cookie |"
+    )
+    lines.append("")
+    lines.append("## 目录")
+    lines.append("")
+    for tag in TAG_ORDER:
+        if tag in by_tag:
+            title = TAG_TITLES.get(tag, tag)
+            lines.append(f"- [{title}](#{title})（{len(by_tag[tag])} 个）")
+    lines.append("")
+
+    for tag in TAG_ORDER:
+        if tag not in by_tag:
+            continue
+        title = TAG_TITLES.get(tag, tag)
+        lines.append(f"## {title}")
+        lines.append("")
+        if tag == "auth":
+            lines.append(
+                "这一组**没有**统一挂 `require_auth`（登录不能要求先登录），所以逐个标。"
+            )
+            lines.append("")
+        lines.append("| 方法 | 路径 | 登录 | 说明 | 参数 | 请求体 |")
+        lines.append("|---|---|:--:|---|---|---|")
+        for path, method, op in sorted(by_tag[tag], key=lambda item: (item[0], item[1])):
+            summary = first_paragraph(op.get("description") or op.get("summary") or "")
+            # 表格单元格里的换行/竖线会把表格撑破。
+            summary = summary.replace("\n", " ").replace("|", "\\|")
+            params = [p for p in op.get("parameters", []) if p["in"] != "header"]
+            lines.append(
+                "| `{}` | `{}` | {} | {} | {} | {} |".format(
+                    method.upper(),
+                    path,
+                    "—" if path in PUBLIC_PATHS else "✓",
+                    summary,
+                    param_cell(params, spec),
+                    body_cell(op, spec),
+                )
+            )
+        lines.append("")
+
+    # ---- 附录：请求体长什么样 ------------------------------------------------
+    #
+    # 上面那些接口的「请求体」列只写了 schema 的名字，不写字段的话等于没说。
+    used = set()
+    for operations in paths.values():
+        for method, op in operations.items():
+            if method in JSON_METHODS:
+                body = op.get("requestBody")
+                if body:
+                    name = describe_schema(
+                        body.get("content", {}).get("application/json", {}).get("schema", {}),
+                        spec,
+                    )
+                    if name:
+                        used.add(name)
+
+    schemas = spec.get("components", {}).get("schemas", {})
+    if used:
+        lines.append("## 请求体结构")
+        lines.append("")
+        for name in sorted(used):
+            schema = schemas.get(name)
+            if not schema:
+                continue
+            lines.append(f"### {name}")
+            lines.append("")
+            lines.append("| 字段 | 类型 | 必填 | 默认 | 说明 |")
+            lines.append("|---|---|:--:|---|---|")
+            required = set(schema.get("required") or [])
+            for field, prop in (schema.get("properties") or {}).items():
+                kind = describe_schema(prop, spec).replace("|", "\\|")
+                default = prop.get("default")
+                desc = (prop.get("description") or "").replace("\n", " ").replace("|", "\\|")
+                lines.append(
+                    "| `{}` | {} | {} | {} | {} |".format(
+                        field,
+                        kind,
+                        "✓" if field in required else "",
+                        "" if default is None else repr(default),
+                        desc,
+                    )
+                )
+            lines.append("")
+
+        lines.append(
+            "> **响应没有结构可列。** 这些接口返回的是普通 dict，没有声明 "
+            "`response_model`，所以 OpenAPI 里没有响应的 shape。要看响应就调一次，"
+            "或者读对应的 `service.py`。"
+        )
+        lines.append("")
+
+    return "\n".join(lines) + "\n"
+
+
+def check_tables(text: str) -> None:
+    """生成完顺手验一遍表格。
+
+    一个没转义的竖线就能把整张表切歪 —— 而 markdown 不会报错，它只是安静地多出一格。
+    参数类型里的 `integer | null` 到处都是，所以这不是假想的风险。
+    """
+    escaped = BACKSLASH + PIPE
+    sentinel = "\x00"
+    expected = {2, 5, 6}  # 约定表 2、请求体表 5、接口表 6
+    bad = []
+
+    for number, line in enumerate(text.splitlines(), 1):
+        if not line.lstrip().startswith(PIPE):
+            continue
+        cells = line.strip().replace(escaped, sentinel).split(PIPE)[1:-1]
+        if len(cells) not in expected:
+            bad.append((number, len(cells), line[:70]))
+
+    if bad:
+        for number, count, snippet in bad[:5]:
+            print(f"  第 {number} 行有 {count} 格（预期 {sorted(expected)}）: {snippet}")
+        raise SystemExit("生成的表格结构不对，先修转义")
+
+
+if __name__ == "__main__":
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    text = render()
+    check_tables(text)
+    OUTPUT.write_text(text, encoding="utf-8")
+    print(f"写出 {OUTPUT}（{len(text.splitlines())} 行）")