feat(integrations): 微信要先扫码配对，改成 iLink 扫码登录 + 长轮询

上一版按"webhook + URL 里带令牌"自己编了一套，用户当场指出微信必须先扫码配对。
现在照腾讯 iLink Bot 协议自己做客户端：取二维码 → 手机扫码确认 → 存加密登录态 →
后端长轮询收消息 → 用 context_token 回话。独立实现，不依赖 DSH 的运行环境。

后端
- wechat_ilink.py：get_bot_qrcode / get_qrcode_status / getupdates / sendmessage，
  bot_token 用 Fernet（密钥由 JWT_SECRET 派生）加密入库，日志与接口都不回明文
- wechat_intake.py：一句话 → 任务或知识草稿，前缀识别、#标签、首行标题
- wechat_bot.py：每条通道一个轮询任务，启动时按 status='active' 恢复；
  message_id 去重；errcode -14 转 expired 让用户重新扫
- api/integrations.py 重写成扫码三接口 + 停用/断开/最近消息
- 迁移 0013（登录态列）、0014（轮询入口按 app.bot_channel 主键的 RLS 口子）

Web
- 接入页改成扫码流程：页面里画出二维码、每 2 秒问一次状态、连上显示微信用户与最近消息

验证
- pytest 149 passed（新增 test_wechat_bot 9 例）
- ruff check / ruff format --check 干净；tsc 0；vite build ✓
- web/e2e/integrations.mjs 7 项 ALL PASS（拿的是微信真二维码）

教训：接入第三方协议先去已有实现里找协议，别从直觉倒推。

2.Design/API.md

@@ -699,78 +699,69 @@ Query：
 
 ## 6.5 外部接入（微信 clawbot）
 
-微信里那个机器人把消息 POST 到本服务，消息就变成任务或知识草稿。
-**这一组接口不带登录态**：机器人不会登我们的账号，它只照着配置好的地址发。
+微信里那个机器人连上本服务之后，发一句话就变成任务或知识草稿。
+走的是腾讯 iLink Bot 协议：**扫码登录 → 后端长轮询收消息 → 用 context_token 回复**。
+所以这一组里只有「扫码」是免登录的（机器人自己不带我们的令牌），其余都要工作区 admin 以上。
 
-### 6.5.1 建通道（工作区 admin 以上）
+### 6.5.1 扫码与通道（工作区 admin 以上）
 
 | 方法 | 路径 | 说明 |
 |---|---|---|
-| GET | `/workspaces/{ws}/integrations` | 列出这个工作区的通道 |
-| POST | `/workspaces/{ws}/integrations` | `{"name":"微信"}`，**响应里带一次性令牌** |
-| PATCH | `/workspaces/{ws}/integrations/{id}` | `{"name"?}`、`{"status":"active"｜"disabled"}` |
-| POST | `/workspaces/{ws}/integrations/{id}/rotate` | 换令牌，旧地址立刻失效 |
-| DELETE | `/workspaces/{ws}/integrations/{id}` | 删通道（历史消息级联删掉） |
-| GET | `/workspaces/{ws}/integrations/{id}/messages?limit=20` | 最近的收信记录 |
+| GET | `/workspaces/{ws}/integrations` | 列出通道（含 `status`、`connected`、`polling`、`last_seen_at`、`last_error`） |
+| POST | `/workspaces/{ws}/integrations/wechat/qr` | 取一张二维码，返回 `{channel_id, qrcode_id, payload, image, expires_in}` |
+| GET | `/workspaces/{ws}/integrations/wechat/qr/{qrcode_id}` | 问扫码结果：`waiting`／`scaned`／`confirmed`／`expired` |
+| PATCH | `/workspaces/{ws}/integrations/{id}` | `{"status":"active"｜"disabled"}`，停用就停轮询 |
+| DELETE | `/workspaces/{ws}/integrations/{id}?confirm=true` | 断开：清掉登录态与游标，回到 `pending` |
+| GET | `/workspaces/{ws}/integrations/{id}/messages?limit=5` | 最近收到的消息与它变成了什么 |
 
-创建响应：
+取二维码的响应（`image` 是可以直接塞进 `<img>` 的 data URL，本地渲染，不是图片地址）：
 
 ```json
 {
-  "code": 0, "message": "ok",
-  "data": {
-    "channel": { "id": "…", "kind": "wechat_clawbot", "name": "微信", "status": "active",
-                 "last_seen_at": null, "created_at": "2026-11-05T14:02:11Z" },
-    "token": "lS7…(43 字符)",
-    "webhook_url": "https://example.com/api/v1/integrations/clawbot/lS7…"
-  }
+  "channel_id": "4f0a…",
+  "qrcode_id": "30c97db83291e779217cbe20c5373e91",
+  "payload": "https://liteapp.weixin.qq.com/q/7GiQu1?qrcode=30c97…&bot_type=3",
+  "image": "data:image/svg+xml;base64,PD94bWw…",
+  "expires_in": 300
 }
 ```
 
-> 令牌只在这里出现一次。库里存的是 `sha256(令牌)`，页面刷新之后连管理员也看不到；
-> 丢了就 `rotate` 重新生成。
+扫码成功那一次（`status == "confirmed"`）除了回 `status`，还带 `channel`：登录态已加密存进
+`bot_channel.bot_token_enc`（Fernet，密钥由 `JWT_SECRET` 派生），**不会回给任何接口**，轮询任务同时被拉起。
 
-### 6.5.2 收消息（clawbot → 本服务）
+`status` 的四个值：`pending`（还没连）、`active`（连上了、正在收）、`disabled`（管理员停用）、
+`expired`（登录态失效，需要重新扫码）。`polling` 说明后台任务此刻是否在跑。
 
-| 方法 | 路径 | 说明 |
-|---|---|---|
-| GET | `/integrations/clawbot/{token}?echostr=xxx` | 地址校验：有 `echostr` 就原样回纯文本 |
-| POST | `/integrations/clawbot/{token}` | 收一条消息，回 `{"reply": "...", "action": "...", "duplicate": false}` |
+### 6.5.2 消息怎么变成事项（不分接口，轮询里做）
 
-请求体**宽松解析**（不同机器人的壳子不一样），按顺序找第一个非空字符串：
+给机器人发的话这样理解：
 
-- 正文：`text` / `content` / `msg` / `message` / `query` / `body` / `data`（嵌套对象也会往里找 `text`、`content`、`body`、`message`）
-- 消息 id：`msg_id` / `message_id` / `msgid` / `id` / `uuid` / `event_id`
-- 发送者：`from` / `sender` / `from_user` / `user` / `uid` / `sender_id`
-
-正文的写法：
-
-| 开头 | 结果 |
+| 开头 | 落成什么 |
 |---|---|
-| 直接说 | 任务（`status=inbox`） |
-| `任务：` / `待办：` / `todo:` | 任务 |
-| `知识：` / `笔记：` / `note:` / `kb:` | 知识草稿（`doc_type=note`、`status_hint=draft`） |
-| `?` / `帮助` / `help` / `用法` | 只回一段用法说明，不建事项 |
+| `任务：`／`待办：`／`todo:` 或不带前缀 | 任务（`status = "inbox"`） |
+| `知识：`／`笔记：`／`note:`／`kb:` | 知识草稿（`status = "draft"`，`doc_type = "note"`） |
+| `帮助`／`?`／`help` | 只回一段用法，不建任何东西 |
 
-首行是标题（截到 180 字），其余行是正文；标题与正文里的 `#标签` 会被摘出来挂到事项上
-（纯数字的 `#123` 不算标签，避免把编号当成标签）。
+正文第一行当标题（超过 180 字截断），其余当正文；`#标签` 会被摘出来加到事项上（纯数字的不算标签）。
+建完之后会用 `context_token` 在微信里回一句，附上链接（`PUBLIC_BASE_URL` 或 CORS 里的第一个来源）。
+同一条消息（按 `message_id`）重复推送只会落一次，重推直接跳过。
 
-**幂等**：带 `msg_id` 的请求重复到达只处理一次，第二次直接回上次的 `reply` 且 `duplicate: true`
-——微信会重推，重推不能变成两条任务。
+图片／文件／视频目前只在 `bot_message.raw` 里留痕，正文不搬；语音如果服务端给了转写就用转写文本。
 
 ### 6.5.3 错误码
 
-| code | HTTP | 场景 |
+| 场景 | code | HTTP |
 |---|---|---|
-| 9002 | 404 | 令牌不存在或已被换掉；对外一律"通道不存在"，不区分工作区 |
-| 9003 | 403 | 通道被停用（`status=disabled`） |
+| 取二维码 / 问状态时微信返回错误 | `9002` | 404 |
+| 通道不存在、或不属于这个工作区 | `9002` | 404 |
+| 登录态失效（微信 errcode `-14`） | —（通道转 `expired`，接口正常返回） | 200 |
 
-### 6.5.4 租户隔离
+### 6.5.4 表与隔离
+
+`bot_channel`（通道、登录态、游标）与 `bot_message`（收到的消息留痕）都挂 `workspace_id`，
+走标准 RLS。轮询任务从 `channel_id` 起步、此刻还没有工作区上下文，所以迁移 `0014`
+额外给了一条 `app.bot_channel` 的按主键口子（permissive 策略，与原隔离策略 OR）。
 
-`bot_channel` / `bot_message` 都带 `workspace_id NOT NULL` + RLS。收消息时还不知道它属于哪个
-工作区，所以 `bot_channel` 的策略额外允许 `token_hash = current_setting('app.bot_token_hash')`：
-请求先把 `app.bot_token_hash` 设成本次令牌的哈希，策略只放行命中那一行，其余行照旧看不见。
-读到通道之后再 `bind_tenant()` 进这个工作区的上下文，任务是按**通道创建者**记账的。
 
 ## 7. 安卓发布与升级 `/app`