diff --git a/CLAUDE.md b/CLAUDE.md
index 55b8b3920..f1a14766a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -343,6 +343,29 @@ Loopback requests bypass daemon token auth. Non-loopback requests require `X-ACE
 
 The frontend has pure helpers under [web/src/lib/](web/src/lib) with Node-based tests. Prefer adding data-shaping logic there rather than embedding it directly in components.
 
+### 消息通道(QQ / 微信 / 飞书 / 钉钉 / Telegram / Discord / LINE,openspec add-desktop-im-channels)
+
+用户文档 [docs/channels.md](docs/channels.md),接口 [docs/daemon-api.md](docs/daemon-api.md) 第 19 节。分三层,方向只能向下:`src/adapters/im/<平台>/` 是平台传输层(QQ 官方机器人 v2 网关、微信 iLink 长轮询、飞书长连接、钉钉 Stream、Telegram 长轮询、Discord 网关、LINE webhook),不认识会话;`src/host/channels/core/` 是核心(存储、访问与配对、命令、出站投影、会话路由、平台运行时、宿主);`src/apps/daemon/im_channels.cpp` 装配(worker.cpp 已接近 1000 行上限,装配与 `/rc` 共用的 `rc_session_catalog` 都拆在外面)。WhatsApp(`src/host/channels/*.cpp` 其余文件)不经过这套核心。
+
+- **平台清单只有一张表** `core/platforms.cpp`(`PlatformSpec`:凭据字段与是否密钥 / 可手填、账号字段、群成员身份是否按群隔离、换机器人是否清空机主与授权、机主绑定方式 Scan / Link / Code)。运行时、宿主、Web 接口、快照的 `credentials_public`(非密钥原样、密钥只给尾号)都按这张表走;认识各平台传输层类型的只有 `core/platform_adapters.cpp`(创建传输层、联网校验凭据、扫码流程),测试改地址走 `HostEndpoints`。加平台 = 加一行描述 + 一个 adapters 分支 + `Address::valid` 放行平台名。
+- **机主绑定三种**:QQ / 微信扫码时带出扫码人;Telegram 用 `/start <码>` 链接;飞书、钉钉、Discord、LINE 在连上之后由 `owner-link` 发 6 位一次性绑定码(`AccessControl::issue_owner_pin`,10 分钟、一次有效、码存在期间错 10 次作废),私聊发送这串数字即成为机主,这条消息不进会话。
+- **新代码过 R15 所有权检查(CI `check_ownership --strict --final`):** 不写裸 `std::thread`,线程用 `JoiningThread(&Class::method, this)`;存起来的回调捕获 `lifetime_.ref(*this)`,`LifetimeToken` 声明为最后一个成员、析构函数体先 `stop()`;同步回调用具名捕获,不要 `[&]` / `[this]`。未跟踪的新文件不在 lint 范围里,本地要用临时索引把它们加进去再跑。
+- **锁:** `PlatformRuntime` 的 `ops_mu_` 串行化开关 / 改凭据 / 接管 / 停止,`process_mu_` 让入站处理与断开互斥,`mu_` 只护状态字段;调 `transport->stop()` 时不能持 `mu_`(传输线程的 `on_status` 要拿它)。传输层在自己的锁外回调 `on_status`,快照在本对象锁外读 `transport->status()`,两边不会互锁。
+- **只给本机:** 路由用 `is_trusted_local_client_address`,远程 Web 代理转发进来的 `127.0.0.2` 也是 403;`WebServer::broadcast_local_event` 只推给 `WsConnState::trusted_local` 的连接 —— `channels_bind` 带扫码二维码内容。凭据只回尾号,二维码内容与密钥不写日志。
+- **会话列表 `channel_bound:{platform}`** 由 `sessions_for_workspace` 统一标注,侧栏显示与 `/rc` 相同的电脑图标;`/rc` 的换绑动画等专属行为仍只看 `remote_control_bound`,别把两者合并。
+- **连接后由工作线程为已有绑定恢复出站投影**(`Conversations::restore`),否则重启后在 Desktop 里输入的回复不会发到 IM。QQ 换 AppID 时清空机主与授权名单(用户 openid 按机器人隔离),并丢弃旧机器人下的绑定。
+- **QQ:** 全进程单调 `msg_seq`;被动回复额度按入站 msg_id 记账,被拒先降级主动消息,再被拒才暂存(只在内存,下一条入站时先补发);Markdown 被拒后改纯文本且不再尝试;超过直传上限的文件改发文字说明。扫码协议见 `qq_bind.hpp` 文件头(腾讯 connector 无开源许可,只参照协议)。
+- **Telegram:** update offset 存 `state.json` 游标,重启不重复处理;409 分 webhook(等用户在页面确认移除)与另一个轮询方(60 秒后重试)两种。
+- **Telegram 在 getMe 成功后就置已连接**,不要改回等第一次长轮询返回 —— 没有新消息时真实平台要等满 25 秒,设置页会一直停在“连接中”。
+- **设置页只给简要状态,细节写日志**(2026-10-05 验收反馈,仿 WorkBuddy「远程通道」):两列卡片、单色聊天图标、「连接 / 取消连接」按钮;没有凭据或没有机主时「连接」打开三步向导(创建机器人 → 连接 → 绑定机主),配好的直接连。失败原因、隐私模式、暂存待补发、绑定与收发计数由 `core/state_log.cpp` 在每次 `publish_state` 比较前后快照写进 daemon 日志(`[channels/<平台>]` 前缀,凭据尾号也不写);入站判定原因(`AccessResult::reason`)、IM 命令、QQ 扫码各阶段与发送回退在各自位置记日志。前端 `channelsSettings.test.js` 有守卫断言页面不渲染这些细节,别加回页面。`ChannelHost::publish_all` 也走 `publish_state`,否则绑定变化不进日志。
+- **微信(iLink)**:凭据全部来自扫码(`weixin_login`,二维码编码 `qrcode_img_content` 而不是 32 位令牌),设置页不能手填,校验只查齐全不联网。轮询游标与每个联系人的 `context_token` 存在 store 的 `values`(`weixin_cursor` / `weixin_context_tokens`,换机器人随 `clear_transport_state` 清掉);主动发送(Desktop 里输入的回复)也要带 context_token。-14 = 登录失效 → Failed 且停止重试,设置页点「连接」直接回到扫码。只有私聊。CDN 媒体 AES-128-ECB,上传结果在响应头 `x-encrypted-param`(`im::HttpResponse::headers` 键已小写)。
+- **钉钉 Stream**:校验 = 取 access token + 试注册一次 Stream(票据丢弃),能分出凭据错 / 应用未发布或没开 Stream 模式。每条入站要 ACK;回复优先用消息带来的 sessionWebhook,过期后走机器人 OpenAPI(要检查 errcode,HTTP 200 也可能失败)。同一应用每条消息只投给随机一个连接,靠核心的按账号文件锁保证只有一个 ACECode 在连。
+- **飞书长连接**:protobuf 帧(`feishu_frame`),每个事件帧都要 ACK,分片按 sum/seq 重组;飞书要求长连接**在线时**才能保存「使用长连接接收事件」,所以机器人未发布 / 未就绪只在 `extra.bot_warning` 里提示、不判校验失败,连接步骤的清单告诉用户回后台保存订阅、加 `im.message.receive_v1` 并发布。`domain`=lark 走 open.larksuite.com,测试经 `HostEndpoints::feishu_base` 覆盖。握手失败的响应头(`Handshake-Status` 等)`WebSocketClient` 拿不到,403 / 连接数超限目前按可重试处理。飞书、钉钉都按集群模式把事件随机分给同一应用的某个连接,同一应用接在别的工具上会被分走消息。
+- **LINE**:唯一要公网回调的平台。回调端口是 `core/line_webhook_server`(独立 Crow 应用,只监听 127.0.0.1,只有 webhook / health / media 三条路由,**绝不复用 daemon 主端口** —— 本机请求在主端口免 token,经隧道进来的也是本机地址);端口第一次由系统分配后存 cursor `line_listen_port` 沿用。公网地址留空 → 起 cloudflared 快速隧道(找不到时 `extra.cloudflared_missing`,设置页提示 winget 安装),每次连接用 PUT 重新登记 webhook;控制台的 Use webhook 只能手动开,没开时停在 Retrying(`extra.webhook_active=false`,设置页给出该做什么)。回复令牌 50 秒内免费用 reply,否则 push(计月额度,额度用完暂存到下一条消息再补发);机器人不能发文件,图片走回调端口的临时链接。
+- **Discord**:校验时 `/applications/@me` 报 Message Content Intent 关着就直接拒绝保存(否则网关 4014);保存时带回 `bot_id` / `application_id`(设置页邀请链接用)。优先 Resume,Identify 每 24 小时有上限,计数经 `on_identify_ledger` 存两个 cursor 跨重启保留;4004 / 4010–4014 停止重试。服务器频道与线程算群,@ 或回复机器人才处理;不 ping @everyone。
+- **Telegram 群隐私模式开启时 @机器人 的消息照常送达**(BotFather 默认即开启,正好符合“群里只处理 @”);关闭后机器人收到群里全部消息,仍只处理 @ 它的。早期 spec 把这条写反了,已更正。
+- 回归:`tests/daemon/im_channels_e2e_test.cpp`(生产装配 + 真实 SessionRegistry / 脚本化模型 + 真实传输层对假平台,覆盖验收清单里不依赖真实账号的部分)、`tests/im/`、`tests/network/websocket_client_test.cpp`、`tests/platform/aes_gcm_test.cpp`、`tests/channels/core/`(核心用内存版 SessionClient 与假传输层,宿主测试含两个宿主争同一把锁;`state_log_test.cpp` 守着日志内容与“不写凭据”)、`tests/web/channels_handler_test.cpp`、`web_server_smoke_test.cpp` 的 `ChannelRoutesRejectNonLocalClients` 等三条,前端 `channelsSettings.test.js` 与 `desktopNotify.test.js`。各平台假服务在 `tests/test_support/im/fake_*_server.hpp`(端到端测试只在用到的用例里创建微信 / 飞书 / 钉钉 / Discord / LINE 假服务,传输层参数经 `ImChannelDeps::tune_services` 调整),所有测试都不连真实平台。
+
 ## Desktop Shell
 
 The desktop shell runs a webview against workspace-local daemon processes. It does not change daemon internals; each daemon still serves one current working directory. Workspace switching currently uses whole-page navigation so browser origin follows the active loopback port.
@@ -581,6 +604,10 @@ SidePanel 折叠 UI:`ChatView` 把 `SidePanel` 包到 `<div class="ace-side-pane
 
 **栅格图片不要做成 `@路径` 引用。** 2026-09-04 / 09-20 两次改动让 Desktop 的本地文件全部「只给路径」,连截图也先落 `~/.acecode/composer-files/<uuid>/` 再插 `@路径`;结果输入框和对话记录只剩文件名,服务端又拒收图片引用(`save_attachment_reference`: `image attachments require snapshot data`),模型得先 `bash` 再 `show_image` 才看得到图。现在:`composerFileIntake` 把栅格图(`composerImagePresentation.js::isRasterImageMimeType`,不含 SVG)的 File 直接交给 `onMediaFiles` 上传;原生 `materialize_context_items` 对 ≤25 MiB 的栅格图带回字节(超限 / 读失败退回路径,添加不报错),前端经 `nativePickedFileToFile` 还原成带来源路径标记的 File;普通文件与文件夹仍是 `@路径`。对话记录里 `Message.jsx` 的用户气泡把图片部件交给上方 `AttachmentStrip` 渲染缩略图,不进正文的文件名按钮分支(与输入框的图片条对称;只有图片时不画空气泡)。回归:`composerFileIntake.test.js` 的栅格图一组、`composerMessageRendering.test.js`、`tests/desktop/context_items_test.cpp::RasterImagesCarrySnapshotBytes`。
 
+### Web UI: 输入框光标与 Slate 选区同步
+
+用户反馈:光标在行首,中文却打在行末,切换会话后恢复。Chrome 下输入法在 DOM 光标处合成,Slate 却在 compositionend 把文字插到 `editor.selection`;而 Slate 只在节流的 selectionchange 里把 DOM 光标写回选区,并在它认为「拖拽中 / 正在写选区 / 合成中」时整段跳过 —— 拖拽标记残留(dragstart 后没等到 dragend/drop)就会让选区永久过期,直到输入框重新挂载。`RichComposer` 因此在 `compositionstart` 与普通 `keydown` 消费选区前调 `adoptDomSelection`(判定在 `lib/composerDomSelection.js`),Slate 还有未渲染的改动时不采纳:`editor.onChange` 包装置位、`<ComposerRenderSentinel>`(与 Editable 同一次提交的 layout effect)清除,否则会用旧 DOM 撤销刚做的程序化选区。回归:`composerDomSelection.test.js`、`richComposerKeyboard.test.js` 的采纳用例。
+
 ### 其它反馈修复备忘(fix-feedback-0924)
 
 - **429 硬配额**:message 明确说额度 / 余额用完(`quota exhausted`、`exceeded your current quota`、余额不足…)也按硬配额,不再重试;按分钟的配额与普通限流仍重试(`retry_policy.cpp::is_hard_quota_message`)。
diff --git a/CMakeLists.txt b/CMakeLists.txt
index ef4936cce..e0e553fa7 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -145,6 +145,15 @@ if(WIN32)
     endif()
 endif()
 
+# QQ / Telegram 通道直接调用 libcurl 的 WebSocket 接口(curl_ws_send / curl_ws_recv),
+# vcpkg.json 为此请求了 curl[websockets];缺这个特性时在配置期就失败,别等到运行期。
+find_package(CURL CONFIG REQUIRED COMPONENTS WSS)
+if(NOT WIN32)
+    # QQ 扫码配置要做 AES-256-GCM 解密:Windows 用 BCrypt,其它平台用 libcrypto
+    # (vcpkg 在这些平台上本来就把 OpenSSL 编成 curl 的 TLS 后端)。
+    find_package(OpenSSL REQUIRED)
+endif()
+
 # cpp-mcp: only build the library, skip examples and tests
 set(MCP_BUILD_TESTS OFF CACHE BOOL "" FORCE)
 set(BUILD_MCP_EXAMPLES OFF CACHE BOOL "" FORCE)
diff --git a/assets/desktop_pet/DESIGN.md b/assets/desktop_pet/DESIGN.md
new file mode 100644
index 000000000..40a9c4da3
--- /dev/null
+++ b/assets/desktop_pet/DESIGN.md
@@ -0,0 +1,127 @@
+---
+name: ACECode 像素办公室
+description: 桌面宠物资源的局部视觉规则
+colors:
+  office-paper: "#fff9e9"
+  office-ink: "#27324f"
+  office-line: "#a8a6a4"
+  office-selected: "#dce7f6"
+  scene-outline: "#2b2737"
+typography:
+  body:
+    fontFamily: '"Pixelify Sans", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans SC", system-ui, sans-serif'
+    fontSize: "12px"
+    lineHeight: 1.4
+  label:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "PingFang SC", "Segoe UI", sans-serif'
+    fontSize: "12px"
+    lineHeight: 1.3
+  label-compact:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "PingFang SC", "Segoe UI", sans-serif'
+    fontSize: "11px"
+    lineHeight: 1.3
+rounded:
+  control: "4px"
+  bubble: "6px"
+spacing:
+  control-group: "4px"
+components:
+  control:
+    backgroundColor: "{colors.office-paper}"
+    textColor: "{colors.office-ink}"
+    typography: "{typography.label}"
+    rounded: "{rounded.control}"
+    padding: "5px 7px"
+  control-selected:
+    backgroundColor: "{colors.office-selected}"
+    textColor: "{colors.office-ink}"
+    rounded: "{rounded.control}"
+---
+
+# Design System: ACECode 像素办公室
+
+## Overview
+
+**Creative North Star: "保留原作的像素办公室"**
+
+本规范仅用于桌面宠物资源。视觉权威是已指定的原作；当前实现证据是 [agent_office_pet.html](agent_office_pet.html)。等距房间、家具、角色和透明外缘延续原作，新增会话控件保持紧凑。此处不定义 ACECode 全局品牌或通用页面风格。
+
+**Key Characteristics:**
+
+- 房间是主体，顶部控制条承担会话切换与跟随。
+- 场景用像素轮廓和分面明暗，操作文字优先保证中文辨认。
+- 同一会话保持稳定布局和角色外观；动画表达真实状态变化。
+
+## Colors
+
+房间保留原有多套地面、墙面和家具调色板；交互层使用独立的浅纸色与深墨色。
+
+### Primary
+
+选中控件使用 `office-selected`，通过整面底色和四边边框共同区分状态。
+
+### Neutral
+
+`office-paper` 用于控件、通知、工具图标底和成员列表；`office-ink` 用于操作文字与工具图标；`office-line` 用于控件及成员列表边界。`scene-outline` 保留给像素精灵轮廓。
+
+**The 分层配色 Rule.** 房间材质色服务于像素物件，操作层的状态色服务于真实交互；两者不互相推断业务状态。
+
+## Typography
+
+场景气泡继承 `body` 的内嵌 Pixelify Sans 与中文回退字体。顶部控件使用 `label`，窄窗口使用 `label-compact`；成员列表使用系统正文。这里没有展示标题字阶。
+
+会话标题保持单行省略，完整工作区和会话名保留在提示与可访问名称中。气泡有宽度上限和省略处理；缩放房间时不应按比例无限缩小操作文字。
+
+## Layout
+
+画布基准为 (344 × 252)，房间整体向下为控制条留出空间。场景随窗口等比缩放，控制条固定在场景顶部，保持一行；窄于 (400px) 时收紧字号与间距，窄于 (250px) 时继续压缩控件内边距。
+
+房间有经典、横排、纵排、L 形、工作岛五套模板，均保留主 agent 和七个子 agent 工位、家具区及机器人路线。布局和配色由会话种子决定。
+
+**The 稳定房间 Rule.** 同一会话的状态刷新不重新随机布置家具或改换角色外观。
+
+控制条的紧凑组间距仅适用于这一小型桌面窗口。展开成员列表限高并独立滚动，不压缩或重排房间。
+
+## Elevation & Depth
+
+家具与墙体通过等距分面、统一轮廓和遮挡顺序形成深度；透明区域保留桌面背景。操作条主要依靠底色和细边框区分层级。
+
+原作气泡带短距离像素投影，属于该场景的既有物件语言；不将此投影扩展为普通按钮、列表或 ACECode 其他页面的阴影规则。
+
+## Shapes
+
+场景以离散像素、等距长方体和精灵轮廓构成。操作控件采用小圆角与完整细边框，气泡保留尾角。工具图标使用与聊天界面共源的 SVG，不用文字字符代替。
+
+整数倍缩放保持清晰像素；非整数倍先做整数倍像素放大，再缩至窗口尺寸，维持像素宽窄的稳定。
+
+## Components
+
+### 会话控件
+
+浅纸色紧凑按钮，选中时整面变色。悬停改变底色，键盘焦点有独立轮廓；跟随开关用方形选中标记，并同步 `aria-checked`。
+
+### 场景状态
+
+角色动作、气泡和工具图标共同呈现状态。忙碌期间气泡常驻，一行「图标 动作 · 细节」：动作用短的现在进行时动词，细节用系统界面字体（路径、命令、英文推理在像素字体里难以辨认），放不下时从开头裁掉，保留最新的字和文件名；正在输出的气泡带闪烁光标。等待授权、等待回答、失败、停止均有明确文案；工具图标只在执行或准备工具时显示。上下文文件堆属于相应工位，依据当前上下文使用率呈现。
+
+### 交接
+
+成员加入、完成和 agent 间消息用走路与信封表达：信封带两格残影的抛物线和黄色标签（任务 / 回报 / 消息 / 新任务），落地时收件人头顶冒「!」。走路沿 2 单位网格寻路、不穿家具。
+
+### 溢出成员
+
+超过可见工位时显示 `+N`，展开后列出成员名称和当前状态。列表随快照更新；已离开的成员移除。列表仍展开时，失效焦点回到溢出入口；溢出消失时关闭列表。
+
+## Do's and Don'ts
+
+### Do:
+
+- **Do** 保留原作家具、透明房间、等距像素构形与稳定会话布局。
+- **Do** 让控制条、提示和成员列表保持可读，并把状态变化绑定到真实快照。
+- **Do** 为会话按钮和跟随开关保留焦点及可访问状态；减少动态效果偏好下不走路，但保留交接信封（它承载信息）。
+
+### Don't:
+
+- **Don't** 把局部宠物界面改造成卡片仪表盘或给透明场景铺满页面底色。
+- **Don't** 用装饰性忙碌动画冒充执行、完成、失败或上下文数据。
+- **Don't** 将这份局部规范中的小字号、紧凑间距和像素投影推广为全站默认样式。
diff --git a/assets/desktop_pet/OFL.txt b/assets/desktop_pet/OFL.txt
new file mode 100644
index 000000000..cc97f4546
--- /dev/null
+++ b/assets/desktop_pet/OFL.txt
@@ -0,0 +1,93 @@
+Copyright 2021 The Pixelify Sans Project Authors (https://github.com/eifetx/Pixelify-Sans)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/assets/desktop_pet/agent_office_pet.html b/assets/desktop_pet/agent_office_pet.html
new file mode 100644
index 000000000..8a53c910d
--- /dev/null
+++ b/assets/desktop_pet/agent_office_pet.html
@@ -0,0 +1,1541 @@
+<!doctype html>
+<!-- ACECode 桌面宠物：像素 AI 办公室。源自 agent-office 导出包，由 acecode-desktop 嵌入后
+     用 NavigateToString 加载，窗口透明、置顶、不抢焦点。像素字体 Pixelify Sans 采用 SIL OFL 1.1，见同目录 OFL.txt。 -->
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>ACECode 像素办公室</title>
+<style>
+@font-face{font-family:"Pixelify Sans";font-style:normal;font-weight:400 700;font-display:swap;src:url(data:font/woff2;base64,d09GMgABAAAAAC7wABQAAAAAkdgAAC59AAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGoFjG8YqHIU6P0hWQVKCSD9NVkFSMwZgP1NUQVRYAIRqL0QRCArmXNB5C4NgADDLGAE2AiQDhzIEIAWFDgeGNgwHG7eDB+8Quh2M+F/dDUYG6sBmZZodiGHjALxmLyj+/78lcDJEiluK6vw93S6daDKnZupSQrTVSmpWRMlJB+rCHJ74NLtEfaNVGAeXYDaadXfpSmV4+aO2Pz91yimzU7eSTkHJz3VfSyx++m8bcFcMQIGBG3Vw0F23XQWGpzBdvnJ3lDotPBB7X8yDzVvOHzAfpnkmDoOiNbYIcKeHiO1Czp/nt/nnvvdAoqxmRg3eQ2T6jMJaKRgFNjxqOKNYO13qIsNVltuvdL8SMOJg2/48KC/IEk886ALQkPO0iL7f77Pn3K8W2BEqs0auXAeKKE+mImSEjbBhGeGAywPa+7+pWvhgAUmABSyQSMgOXZjEmdLLdW6HbVYy7+31WmpNmKJNTFumCkQJorSr8BNnnLjGihonatWo0m87AgKwcAN4g/fz/VT3VY6iL8EwMsxZBr89wNmQozm0/r860yW1HB2Qc0i5Eg0rycf+/xetr/fiKx+MRdxo6oZxOVKBUt4Olqkrj71YWydrglnDS2eITP+cHl7pHlXHIxpPYPx5XC4fl4/D4cfl5G4a1pWpWdqDJQ6gLCnL0zte/VNFvjP5gZKP+Jli/SfBonsXjd0hCGABEo5HK8MT+SXiIMuTwWAB3mJJyHhD6Z3BvfMuNdan2YeBceHDP7Y06Y7eNXgpHVUUQvY6pNbM2qP112ixM3J4K4B4shdpPbZTWOmINdQKDAzi8eOvph1Aj6Mw/IBdli5gIrtb03kCJjhNM7/rBKdQwjD0zF+2fzOUoDshYgy0/vVw2p/+u4RG6+2+IwR7hODG+XljObZ5fvy/tNz9PdRTVVUrYlQ2RuXjvZfl+9EeOy6Xlx8RCSKNNEbbbRGdViGnL1vGWZoa1xhPGCMcVQg340sPEFwDADcAiwDsIcKSIUoUHz4wyARTACAEPOGwAYgGACPAhtcEAuBJgQ2AM6i11xr3lbtAhBCxMkgFh3MB81bfXtyg93Cf+RwOwQAIAAggLG812KlEACgIuv3B5ygwfjZbLFfrHWaYlk0c16N+EEY8ldAvSJkDCAIZMgACwBOlALZ3H1sCoqNH+3gQIQCA02kAEAx++GwdD9IQp8DveFzKgkedqIa+/ADwVgONg00C4UFQS0MK1UsEEAJuZu2Dl4sAuA4AQQYRABAO1CQtANUeBDrKjrIBNheljsaeUQX1ijACU+/s3/Jbqfjah4yx0OD1qHQ2AiLUKQegb4nBqFuSnEeLk22FaGhbGKFV46GcLMBCmqpTKUapitVEpcSAPA5yFn7XnI3vTWlwb/NlF+XWi+LusjiQ3wZe/gfAe3DW3ogfNY7obv+ng+CaqgsyIQFMWW+ft2112J0qwAOV5CEOBtweyZ/tcxF0Z6hugM9FeBcPzctUi0X0BLBw0JFI8BZeAKpZ5OzJAe2D+20Nm0SIJn65b+ritEXw0J29GEY6GnSPNNkKh9ziKfyKuLUenT4PuHe63f0rRRBewgFnV0aaEfimU2ETMnX/XZcIS7Lrmzx4cJlk1ATzv2Y7zxGBIOf5Buaxm6skOk2CkL+yJL6oAEvTzRcqU/BR35YSLABlAHIBxAOIAOAFtzS8TqMDvIwNXZGEYbHdxIA4bPyQmCW0AOAlPNd99TfCcGCTYfBgYxzIBoLi9WF8IC+/4M7Fq04m29vwJdXLE+fTpS1nszr1S35Nykape4JFVCMPDlD9mzv9UR0AABSLkVDHn9u+z/hdO1Xa6UaNfaVt9mb1jtS70h7Gr8UMvyqdxFTcLXpKlF98Ui/pR+9cLvLUplT7hAnHqde0/fFMXeR1k7xBH0hygbzN6HgVAmScxzu9v8xHG6np1iBbo+buZe+f7zgVo2H7LkQhCRnbyl84YSBH27bZ3v8txIN9f4qSGp9XuQTR8EAJGco3LURQ+r3N95WzSienXiGjWvockyve/Q5okqpAQnWHF2Xhqv9laIYkQnj4BIREvHgLEChIMKkQMiSKQrxk2XLkyldAQ6tQkWLlKunoVbGwsrFr1KZDt+l6zTDLbHPMtco6u+2x14AbAHwGAOA7AEwaBBHh4hLhEcAJiRDExHAePBA8ecJ58ULw5s1DoEAcQYLwBQvGISVFCBECFy0aLkYMjuGGI8jI4OTkOEgkAQpFTEGBL148vmTJWFJkcqGmxpIlCwagySqrPBIj1WUZZSwkHxgNMFoIFYKnGEJlbSGmNvYseWrostRqgBiBMGAxA2MBiw1uxgFjh7tG19N4LdjawNMN3HSIzQJuriuwympc61yu3fZyNeByHXEU1w0Q7uTiMCQEiYywqpOLD+T6FJweT1i5aELNmo0UsiakmmAys8Uw7dCZffy64Bod/FQjNBLQ0VEjUM4DqPLAyZ8InUY4o5GVOiNSFVqIZYQ6ko6FaaR6ERhRPRsH1BwxLjMd+uc48WmH9PkYIGMugOvlHRR7PvH4sx/2877ZK9rWVc7oZlWYX1Pm27yfbrHNb5tO72uJHBcH36fil7yJx3MKq9DD7X70KR2klODvNuH3uAttcHTeMB0e77Jq9OqbXbX8tx+W8p+LPxtF2HPfHpQR0LzH01jamOf/M0K8BLQkybLiWreWur3kHU9VevJl0V0nIwXh9QXAbxEgxpMQopGJSlOi+a5kkboqm3TK+VNuIY+RKpihBgaLbEM1Cq20ycFRdXc0/V3NEt2RhxGhfTgCvQFkaciygTaV65MvjV4qC50zhiwNZntGGleD3eRmGzqsbnf3PhLKsJsDJipopZGi3NkmBIBYCNazKgjKWQzZCfkiAd22Nx+MATDGlnYLjouWQhVLKANRsivSl1DlA2wBy/w2B8zXXjabXQzy8iIJ/QZ1e/Gnb42rO/FqEmN0J9qf4Ik/Suo9CkL5Dg0WaADS8E+qrmWcmhQq2SxRaMRyq47chlhWuY8jNe5bK6zE0uksuJuHZDdSKUVIFSalGovjXq+7ill/ajaKI1eW9DajfOyyOSwGwpyPg18IaNxwDgObZbocW5O1gXg797ZQpv1w+4LoYdXizZgBigLeukhQ9+9FZI46Wjnmaz4XW00ebruDDvEEVBZ9PN2+VaYrN4Hhkh+S715aw80mgXY8S7lF5knEu0uvRoin2nRNEpy50YPHggKsKXhNMa1GKA3xxpFeOBFCYH2oDLpY0oAZQ/RGVYclJb+yW3IYuWght1MIrk/jvgIXHNViTIHsDLnU163BC28FFgVJPpjqiplBJnkHslGYtyGzlhZJDgfDcDRs4nAYNSBJ+MiwEGIYDSYKMQzDoNy9Ecy9e1WX2KxuWVfsPuX/2sNeDQx1RDha3ZePAUA3CIO6oWPAABYIUXRFBhkor7aAW7ke1gyc1ArIy/zce8AGzW25E90ggVsEe73LNAALnrJpRpNFkjRSOLyKGAw9cO0gbUQkv3lq84VVElwPqDJ4aVZaLJHT3MknMcF3KYhCJ6+24lBQsLdsbye9E7K2ddukvwGuNuxMhWdzD6ZjUEJVy9n4He2ZfNv4i5PAbU+iaTIvLwCbXca143ZxXcPPtaxjgCMcjQBe//HpJpykcEnp3zzYag3toJsie+AsJCljcCNc6fN/FTtAMGvwZheDda5LZ86YB51X3LYlVSNEhHiWB7XFrVOzu2zDPFKCM3zAcUz26xRPc2qqko3zC0VRlIuhK+6uer7zsjBLR3lK5R1MUVR1E7kMh6bzTXxyoCGxlHUMcISjwxsmT3mDP8EVQEEfRJS7WSlNs37BlcnZHCvOOWfSyMNXnYZIbrCLVr6HE/IZz/D09zLLtndqcYrLhBwpqLMyS+wBVVbRCfWYTN16vmbsiboiTf6wRHNCXVI0xv2+pnDbeRyahB81kH4Gdx8YosZmGEm7aed3+QWg7VZzPSjtTQa7NoKMXhgBACHA4RQufbcxBsifczPLTgtM4n8+8qkKHggciCie/SuWCEF8uBGYAqMzGUZrAky+SXD5dCay01oIGhPA6c/bsYyWJkoACYSwBG67OcLy4rsxImwL8pMzLNIxT72fDt/txw1Pnzzu0V8P862rCy+zTNeDmzPNhkbnyTAu0nkvbOyKGNFVZDNMcQAJqqhARIeuy/IT+/EqooVNZuQBKiy4qwhmcng2qoB1JtTDGh8v/hhTYLQkYXAAbtzmZ9UEWDrqtxD6dYhQjgg2Z95vobXKE4qGQWofXwQAoAIAD6WP8O3KcHoIgwZCoAmSvEgV6znsJhtAK4EOx5Dy/T7msI4m3TZWLKMcZds0fOuXiSO5Fckix3w4LMuYx9yLY0pjzl3GkjQL/SAMfT8MeRAEnJsmpQEfuYQOBiSK6R6lrmBlOSynVulEZQy7odeREDISuxHaB3DO8K/kCpT5y89QkmYiLyRuNyAwJCpWSauzyif/Yk7CnP/Z8ri0mNsBAAABEEAAvPRvIAKuiKJdBAtgT+sDYB67a/QRpb8pj9sNzABGwzM5+zyEi6Qbnviq3wTAHzvsArARAKDXnQVACocgHAiABwJAAOziZWlHAAAcPsIo4ACwILQIMJsLRQ79KuzdsAo5Us4DYMA+4QEfyOdZlQGgIkXwQEk01XYDnAijWIu73uveDuEEzpGepH7SIGmINEKaJB1Yf4e4hXg6nQAphSSb7LTfGizqBrw98Cj1kQZEJo5qlfejE+1K8P+15320/c8fftpKAODDUOeHnoLfb/W8p0BU8FW/9KnvAQB6BBwuureHD+4K652zzW1vXHTePvtt9cBqu62y3RprPfPEUxtd+IC/ICSWlT3BX55f2CE7HPbKgK8/7t8710j+oP/a1TA9/i90wA0HvbDSBjfddcs9l33liqlOeemqH1z33DLLfeO1Szb70VLTnDZfnwU2YcMQOFhccAm4k3Dlxp8PX35EhokQKkyUcI9EUomlFCfRcOOkS5EqU5oMajnGGmW0McoUKVYiT7UGteoY1XvMoMV4TZp1MusSjXHCSUccc9xRCIAEBvFA4CzDsIiX2UpAUAAqUA76++QA5BwaLdcDUd85AG3ot/wJQCuA+ABwbQB4AaCfAABgsF5QHoMY16RNbdHQc7InceNuI74a7O10I3HA2AjfG1PXkPvd6HgA3GSxIqUl3gsiyNKQAIEE5oerAlY/MKMqosCL29Ew/08+EEjarWZaNWBUNOYPdosA1S6TMnMP+7rbaRgTIDboIry9iM64hW8av86hZZwAx7Kxznk05P00YJU5ryxRadJAJqxtG9IO8xdkmizj0jc7X+Um6QZnGgLmH2tdaWqsS9lzHoI2wPI/dpXuNaP6gggk1/SkBzE/syZOHRwT7AXJokeUgPYmgU7qYF8tJ6MMAo+sIQkriRwCTUkVAQx3Q4k3yUd2CSPSzd6jQyk5Lqns8amV2skQmCm0uz3NWsHQHKigmGAxRnxVzw7ZYZAz1EK2MnpY6rSAVcwS0anFsuRLZUgpRMqwI0LjDiGkV2p0IyargxtAj+ZoPIDlBAGp6sj3mlVbnVqb5faTb2cIE92dNwDVDR5WgpLrIESuhlmcCml+YY9EWSRiugESjVidwEEvjLHRcBeiQZRgaEn1YdjEDRImCSVyINA1IVwhdppdJhF/I0k1KQRANwGQKlfph+Ii+V+PkwqD/aOkW9OayKTQiWyoqnr3ouQyeNWwKuZV11lIvHCPjZRCYEuj3gkRGWB4rSSQ6eInocf6ZAVRCjCNKf9sSNEP7OWA9ZG8SW/Eap/PMokTRtPx6aYAcXqd2H7FGBXU+mS1fHFpLfIuwQAFl6EJuUIxjYSz0Qy+PWgYqcqq1c1Gi2oSZPnu9jPhiNqr3Fia6XL4wm8mfGOm4zqSoyijkOHl7emLSsdONNDXm5nPluqESqIAq2p4QkDfYywZg+IMAptR3i50ckbXpsGmWIKJuBL3U0PoCIedEbmdFRrWZ6JwmmgGp3EBAUWEnXDr6lWsS7BhM/Af6yytOH13NbHaFyVXoWVwUBXLYv58eU1Y688VL0UbE/QEzxZokf22Ks47yKsdVd2/A0iVTQRyeIsQs9iJSmS0YTHqpQnB+mipZt944FLyDGAmRgsY5Ml3YDNYgKeqp6nD562mT76tH3wHcpasDWCMW1W29OlMSpMmRyctXeMakLNqwUJDjrFDAIkw9j1ObLIttJQaMe86snEkXtGFA96E1bxabTy8Y1J80x838iQIraYhk48tYtNV0Goatrp6PIC9zmgoBGVvqguQquxjX0YQlDEmHRXON01iaszYz14+u5DgakqgeIpQysz4NYQBNz2DyIo/MlVzUH3n9iJ4tdBZTUmgcDRHqix81RnqJkKWMBeKGqSYcUVZae8yE4OIjehQxEpxtAcKtXWiohVXIbqVY+auX4wN/4kyatBGbluzQodLa3YZiTUc+ZDz256iqvfAJQIag8hHJeW9T9tYb0rOm2Fwr4gs10fa+5xI3GnY9wFbx56FFFXsmIW1N5IxwnB57sXNA6bkjUKkKrBYXQIfjuhq9z/ZNd21t8sziQBoEIAmjRXWF3sAegHGfzoJ+oiaQeRsZBOBzAgT01PXF0t6Ei/fHb0nRQWCVCQSF7mcmFBu8uK1cGbSjPfmVHrRdBWFXTZK4vPwTCWe/x9ubcCv+nYH75B7/tqAyLnIJQINS3rGx/zlwqcIACkyoVv+7WGp0KCS5pSRQuLR+Bo5zfSaND9fYLexS7JvT7Jke/nxHEsEoFkJQIoQvkbDLCoodXCdJXPm64pklSVkhHZdG+RJakl5VWsCHzKfUl+AIhhXr1tObqB+nvOeX5sxjf8QyjNW6q3MuA+9k8kI+EsrCaX1BSHUX7qRSFUEcvtzIYS35UO40dWwBgggSlXkiHcHFVoD4dFcuAZUy4tEdp739XBk+ORP4/1krQLWaE7VulMKNh2kxQAORzlr+/c6yJpRGgHiIuVomV7mTwV1uiOaZiAHNtRo3oGC/EOWbK99Ela+t91ClA/zx2MU8ANTrF7qccwHAogruhRDmRPAH8bb0wG5b+QHXFat1k75SM6BqB4tBinaZIgeZb5y7IL5FECeZa5f2q2tLbMQGRCiKWLYUUWWO6bDjRIVyGDG6AUzk3hyFondt79XcFMrI61lSpDhDUaN1F0PhS01w/xcEdZGpnOm5KibmN/yj1pAGjVxArBokid1DVeKZ7zrS9DfNSQxjyGmUOD5ZlXo0GgCFzhdnY6y49apLPG00x4/Iozq+GGs4yQekePLnVXEJbBDc6U9HDLNOae34Dwn0ev8Qwtl2QaCXZ/YrIndJZ+UUmOLYw/mUyjX3TrqzpsncpFS00gJMTm6lS819t7okUAiRogTep/KYL5C+OW1R0E7Wduy25Wo0WpbrIsFxx8D2o1xLGIzRuD9SM07fM/5/VjMm/dtjf6W4iTenPhYKn0EtZsHIgQAqLvD3lDqc0fe0u5thmr2r+LU/BR3GBnKkFSRnpkZvW0KinUjqC+CcWlqm6L2lFsfGTVy3v1S2rlWgPeYtY+dFCPJduJr9KVMz5WezJVMz/nMqlWZjsy5lafqknOzVl9Z7f0WNSjFK6vOgTjp+p7jlwbo5vYzSy8S/omVqnr9NEc0qeAnc2exHXmPCEBYOPVZJQgFBHOdwL3tku//LfTkIHSx7D6TbzOyCAnciakxSJVL/U/XLSKhvh251Hj9pPWMYs9jl2aDVqPZWKip7PPawg35JWs3mOK8wymaJqlEipJWqzpY3W9ecQ+VSM+toEgT6T2zM3vq6XEkCS9FIla9RutVlIJOIruL++i+om4yiVZQy/w5kyJMYe5TwKWtZU5t1Gp01CsKVm74a0OSZnLhFJ14B1YkzOu4rYkUOV8p2qipqTBV9ZmD7myHJCmL5vSynp7wy7lC5HoKXnGUDVZEF6pgOC9f9JKmzCB6gWrURnqJipeiwgx6mlWYJef66Z7iHl5rSQ8E2tnfgvSxfwTOwu2X5tjpvyK7YvLKpmOUFHnJ94RVAzedDKWSajbpnu63VdAK6tHfp4p7uf0UwQoLFMP38EpvSS9opOcOK316qEycSx22Ny4HP+5ZV0VuzWUFa/izv6xgi5QUBQdSZOMYSyVNhjyXy+PlJCRrg7zxkNHoj+/PSSBDHSP/g34ixjA0Y2WwCMm7pMfKhwSOrt09zcdd54/vZR9lrqwpnU7PDNomJTajxwv6mRI/h5Je1F8I+ng6mWtk2/PH+blz2pyg5SHyBDlJk1bvF+gEMozMxqx+L3dPDxwzHaO1138JOpNuQHdhYO8AnEntqWxKMIG/Q+iMX1NeNxg/75z80Z7yIahP83HjSd1R/QU9x59kr+5E1QUI3OiPn9DvFYCoDV/Qn/wkPPlAvURvEDzwdoxGXaFYr/SSQi7O66FrBlmlvEii0+rERUfS3WS1VKeHFSl6fZRehMo8jjPw9vmmYLwID/z0J9+mxp5eFWPSy+JlpHM6Q57YkXRCpMwIR1JVzMb9dQLM1cYBCxtsvv6BOn2DoolD7CYYJ4a1o8UqZus0G+KuPwNHQp6N6aR2k+ZM2iVrA1rdaujAjsDQCwLtEhBI7SZ63R+BZJcyVJGqOmNTKxrtV6SSpFz+vVxGkj+QqSAnGXlt5KqI4Ii+iJiJMZF9kdEt0hFk4WxK/iqOvyyVx2nH3E5zJynRf1irM9WxebxJ/e2nLNQA6cpz7U9Iy9YC7Lholzq9t14fwyifqJ50P/kOUuXqPcTYC+1GaK0n5Qfl8kNy8iBJ7khYv2597DRXtzQ39zR3Vz9/SUy9NXf/QFdX4w+yvDVWIIgQCIRCQagC5kQFUxRNkfpwPUklUfLgBK+IKrI/sZ+sCvOK9gqfeVIkPfn8wr2gdnZ4WGdYuGNzoVFuNBhvDUs/7oduwhbKDY2GsiOWLJ17Ul1ZA6w8RZLLGrl8M/8xQ9euBHe6rXzf9O7p+7+gE2na/XBz+MukN0hqyqD3mwtlWvdq3eltbXrBnIg9YTyhKzFJOcFVGXAtSs79osUBlQvPeC8YdaE6RicrGyxZZIXOXFoRnGHflwt/lO05Zjx20VRwxuN7wD5TnGRfU25u99TZs6wuqe5p6Jk2rasz6+j8lPNxI08Gcqbsw5ip/pN9jXGqEdSXaOv7LvcP5m9rHIvrFjvsjiV1Sxz/bjYuNMKBq+abZDiZZF5NhVMw47q+kply0Ut2nTFptpxIPjP1RrZCchDsfONdrV0ZiKyKlh5iMHhMmWQrfTVj2GYFhtaW6IDNZwzTxKB2w+4xsIIvI/1gzszFw1h+/E2KJPPfjf6wZCnFRD6Az3QnmUXGM2DgM7UrSxp6MfDjr/+14/C1vhbG3siQCbR8aigpl5sSqsJ4ws4RMXBb1I5bfozzbSVnS17sctVL2R3B0nt95cp8rwbbAQFw8V63o6mhn5g39IOFQ99aOnRQ29BPzd/9M7M1/oYvLAJJsap9DFiHAYGBgCDhzdbCg96aKuit0UFvzScpNYTQHGIhMiQyJBTCwFKRikhFpCJS0UxDIhkm54LU3h+sQkiugzgbnlt870+tQHOGw83ZfodGUoqBgIHAUAmcyMIfB3v/5mAf3h7sy4/ed+gOg8+SVV4JCNVwik1E1gRrGGehyMbIxsjGjRubO7jJDjLRjMIohM++6/SHP6d3c2iuOtJYX+8Kf17YLgAp/deEeGE0aHg9JBEJ9M5YV7DIGwGM5iyH7ghixTgGIrcaJdY4qLDJ0vooosUNHW4raid02SRpQuq5B+80u0FEbDhZLf/p8I99mi1J0SU3i7TQJrp85GR6RP36EsB9Kx+s9/3/D/xLgNxqAwFAEEB/GQIA6D8AIhEotEyjFavCmGur0y574WcFyNMgI1WottoWe+x3mevd4Wmf+WU45p00Vanlpqmi5ia0rv1d7EVDE+DSxS5pWRu70lk3azt2elf2bj8vVNaAQWEJvjAMRkMVtMEkWAgDcB3uw3MYhC/hb0wxCuMxE0dhIVZiPVpxIvbjVtyPV/AxvsYf8XfsyaaiFymomBjqorm0hg7RLRqkIfqDdoRw85VpruAm7uJpvJQP8n3+ToCzIDLJknKxyEzZIkflkXwn/2qucdqgi/WO/mpXrdQW2T3HfO2UjxleQqmbvcP7fI3v8uM+8Xf8cx/yv0NEfKTHyCiKqjBHa0yJ2bE2Dsad+DL+SCdPmZAl2ZK9uTxP5Yf8rVi9K7lstax21KX6rP7rq53UOV3TU3tDn+kn/evCkmyivejp6K3os+pqb5aWa5MO6WKfNdQMbMVtnvIj/hR/jX+q2DhdevVZZYM9Djrl0dsmchBDyDIBY4xPrUBFYbogL9AHFJsZRdgAvOp4wyn0WnAlVZdLToETxkHJST1hgV2GATAIrEZ6cDq4N7jbas8NhXDjltMETOxawytIQIu5RxrOeEM8DGmSLCnC5GmItio1KMACo7DPqocy1kOf8pxS+iUKnOn1p2ykhqoVNbKE4cGpJ722oKQ6S+89XVc034FshU6bIT7+KIhxz4VoA17sguCp6Hb6YrkypaAqswGwHw78JLZ4szA+TUBZlGSr5ao4LLg/G1ie18EMFwUpRYcVnxAfFGWIfZbjg9uDW6E1xGMOCSBL4NBZTrx6AZtAPIwZ/mksdFrsR31o8qoVe6OFNOc62FIOhGmhtnVxhxwlCLR4IBoltvH30IYeRC6EXdWkrhAf6lD4s/EQBeeZRzcR41neCmu2B6nI08/RsqpJDDiVs9jE1sZLwj70udSK54IrLTHHSC04Co2sPo9bjR6AX9TWJHFQhsNAHV67APpcqHnIWp52WrKAESZMHNLNdVMDCl+Y0owo1raGAawkoCc1c281S+TYYioczeCcqtpeE8r44N7gbqi3c0IfBgHAq7lzZ7Nppo2BjPve2a3D1xU2XN8pidXBjhFUsUV+niq5WKxZE0OlkDtgInYhcZ+rtyBrw90NbOwueXrXxI9XcDDhj52QLQzZxdEWXdajjXyqYV4eAhijzUwWr9bubRrCrKpAhcG0iESOERDIvMqQopUB6LJqm38WrzH3JqPlfnGBTD0xPx+AqBki2z79vDJOadwE6A15p7i4l1tSSdLmAiJP6U7atCycK5GzQK90mAxVfwkOF46LPAIvysaREejeYybl8hePXmChqYlgWcpO6gwz30yI9Se5pAnm6Y1RwNDFgZQ4cc6Tg5ainhDWlLMgJB3DiIaWATyzdkjdryZ0QQtega4a0dnNRyGPhkBYfjdN/BYwGIRsePraBwLwIAXZZtsLE1OnhM2LMNNYLGlRmdm2kSq/sItoANkmOiBS8kqcnLJEtI3JLrnH1q3idHUinAWDu3ZU8YlAC6J1OHAlHIWxodvAIMMzZM53C7OZ79PfmLFXSNXeEl6OQa1QNVE1Opg3mKv1rrKY6CV3zGGNO+WkEWBOKgb/AWLUvvGUVoILu2yQ5N4v5SrfCRpVVb4IEyRIaXIgHAbODga+BRhJzLE/vkTSLxxtJTDSDFde6ulSke5eVrzxntnWaG0DSKK1dAklUvCmLfua+EAKoqg7GgzoVSFr0xJzeeyiagAEWdsyl5ZSynDLqBnh1ni9wovE4mzaxqRaYSS4V+Ez/zGyWPvV3bMWLq/kokOFGZTWdYVHALQBuMsg6eDwoWEWmb92IApB0llppYYippm0j64JNH8IFQ0PMkhySXU8UKq3zBtZakJRhUD3FFI3Hto2AbuPmIdIuRoDcp7PQ55vODlBVbcA/y3xivMKy9qSDSqGq2WUCS9wjbvSHTNrc8tCJSCr49LLsgrt0WXb8GxbnU6AwV8G+xvv152X3I6Cj4sygdQvGP37Dnia8zicbnPDG1UpC76MiWvDJIh11YwLh+cUhfZjOGz0vdGuCxPQLKfvCHBNCl3M+JJ0vbWGhEMDdUEAcIfxC+c0MKLuhuqAIkotHPoDCw82O5GuPD2mLkXYRne+BW49x9su412jlFBpj8oUCzp6P8+AdC9/bztSAb/iTVUrWj2OKAfY4g2z+abDBzjKtjvklvUdV+IhlCAgayW4DlMzx6XSJ34k1+MBBQ1X7pJNliaMgVbw51q10ZIKkhzqxszLHULqOAfZ9I1rCC4qktoSXu6RBdhns7FndvQakN1mLQq52xsXMOrWnRKmN01SoX6rfhHbZrtB6nxqmRbqebRUPvO7dRbfk9H7sHFTBzxUv+2yQbGdkxsfRZ5c+yjm5P0h/h7AD81fVJo9/m7UyVtvvvXYe0/wUe/RIcJWktSuvp6HtdXrVZbfhL685EwWcq8v5MnJh5En1z6MPslRLRWnB4i+R2rx6itXyheff/HwiNHFoauV9f0IBpuyD+CTAGAIPQ+CbNCPYCeLZja9cF9v2N7IFQeUPFjB/2qXuFNd7g3hsJ3PDwFe1ydd07BgGBYGFG26VTrMx+Zej/bC1+UFLNSCp4skyUepqPjJj//xrx/89ZR9I33v7z/ech8lqlv3kcZgOKqdH2SHr31UA15J/8rBC8+/cPBKj7LDl/efAh+jj3MyLBxqJfDkKh2g0ZLpqx9GnSidDd3Jqg991sBUmT3ev/d7641UjL7b7hs+O2t1jEztQxAwYAMZ4PyuR7DQ743206PX9q+o/cqgO9mXj1flv/vN3Xu//tUvlkW/OL9d3/3NPokaHUYNb+ub6TLQ7DAGUmS0ZWB/y/a72ZT6qR7BLh+cX1x8//sX58S2X3zRJg+pOvY+MYKPfg6hl0d2KoeyX0urv9aVl5xhkCtb2JZmtdI+t9LlHiQLzwY/+fHf4/mk7//gX//4sfV+XYmdH83CN+VcsHizqi6h43EruYLLAnxVEf8ATp5FxOp8dHxilCD3K7VoIRvzXJjFeMxd1JzOhc7TZdWbN4VRabPJQC7CyDxGuoqxr8tLVFUEqcIozKynZ2gsiUueqBk35o5tvGaZ62jRYjWtJW//V3YtsEAaeNSpvqLA2Qye/GtDFsCf/gQwTimL4qO8ouj70QgV42Sytf5/5rqEuO7ZA6ueTO7dm9xScH54kJF0TOeKhxpW+XQY6fLrKnak5deV4H6dkbXdDocoGX93XE2/NqrRa3sKvjVb8hDH56jvIwQeqFMHS9IQyWSZa1aFCfM/H46jn786mQvhuIsU3X60f11laWi9gQ0DVex3MRRSuO71/Ue3kRe7BV90yoP0v/wlJ91QDrtEpD60ApP6P+mqNyqwbRWOKRnY/yELlc/0MBHD9HWvbsjmPzXBRLR2UfD164UUwt551u3rJjLrBxqGYrjh+m3L29Wda5qlKq0dAcw9TmWv17/aiFTseZ8ssHbmlrISqOor3ngjWG/WQrzvgQBJ+YlfFkxql/g9q5bLs76933+nNWH3qFI0mrkaN07J1w4FgbBu7LnJP53xQ6YUwSrs6pfXMTlfLc6dKKaO6qFTfCgT7iSpxdayb4dJwzl4SSIDRwXTAPs6Z2raLFTsOWGMumWPZBZFQ+lk6cY2C/auzRuFjhgaNjpfpOpB8VTmnLv24RVWqXoteNCtmZMJH0pW+Vm+qGv/4WjVHVHtF4pe8Eff4sbVFzWfrGKHUrTLLdMPDrXdx31hmWG42yu0/MqPRxvqLTy26oJ1sPY7n4eL2bxHfLmCZ882HEiP1/TlDPpr1vipHRdNseR8fp2SeTgAXcpmsdJp5BLq2lSrBK/58gF2CL3Mb2N2L7eM1LR+mMW37LpgNSqb31lVgX11mURDEUb+Zhf13ZW7ne4kd2KHy2fieGY9sGbeeUu2ZD11+7ZQYP/8yPaP4k17/rnnh6P4vazq1Wd8+4F35j1I/z0n/YMWLd7mV8t4WXrp02kQzheJMhiQD3TBhB2qg4r/3W/u/2+qFOJ1517K/UI+ZUBFXmz3cmfCXDZ5FNdoyQxkxmd8qRklA7Pa+Gn3B1lwb7OMLBqdPbhSLMeidJKnn3n68zGfoz3tefLL2m+8jG9GK+rR1Zpv3Fk43zwnhJwovu1oRk8o/4E0EZU1CXy3tWq7kOKlXqPTie3a6vi8WFZykXHErBB6NA/ntNiTo9V/nswKqlzMw+WhwPtdfjQjqTeDYfGTvB7Ob0//vWhN5prt4t/T2/Mx/3chsMPE2ArWq0QmNtw5rIAWIr/6eTcP3MBqBRXt5sHFvisPKvj9QNQ8m5yZsM1ysYVbvqCmjvN4a3qLi1uue1feLJg9RAXD+eMOeI5pmOSNlas3MU6szV+4rYqxviK3u7xYdgl1o8Rtq4jHLGg5w1MXLksufk7j4Q+jtwfYWqKlh7wxbF7LcowH3Ltkc7ZcQz7KF7MFde/pdOVh68ST1Uoki35U2LnhW0cXTFysKkpuLYs10UeSh2Pb2La32K1+0rjQV69Q5JfzS+YyN64EqVuYqTbpUj4+UKO5eBlNPSM6UzV1N5n5MJip1DAyvgPD3O5A5mbbpCJHBhp8PeatH0RmLtKmjVDvrPXZdE1DMWwv2iBgcYvUELmYfGbmjM2NwWw2INwW/oV3GVqWZ5+2cAsLCo+1S1BZgMW8/h2is0X0wx9etq++/DJllLpPPTsqzSn2lDvwo87sdRqKUtVlbh4Yr2TK34Pd0hjy8ddhvMDTuc+Lkena5r/vtNaKEUJfz7AMP4NRtDLsO3dsJU/QE3NJ5DtIc3u+X39YJ99ffkXJ5YBaQR+A1x8AgZTv4XjtIeXr4PjXAMAnq60K9obv2gKdL3eOOX4rAWDDAAAgsOnFFPFkJtzfQ1ktz+pv6xzGGk0KOfd2rNqSl/nsWYYQW0sJzvqdVm4aicaT+wBWuR3ObWQHrbp+2NWg8IaIbJ+KZb1ziBSwuoGJJmjNE/bP9tuWgbKcc5EJzyGxwFM/txpbEixFEi1igWgUZ4VF7BN34H1nxB32+7gJrEEAP8Zy1RuaGmQ2mIomctiV7ORdWfLxzlJav0Oc1jr3CMpDFi0+vY+wg59q1ol+rRReyaIYCQIOteP/mawmF9PN0/EkjuhZcz3JbWhgoYIsIxpFXbAxmCUY+2AlNsBwM2wHOP8CwACEUchPIlAYhb/giuDF7pH9/5DHcGQ/c/LV8CckgwAM0XJBI9ZriYtFoS38VCMuABwNnfsQvwT1YUSR9OHSPO4jxNjVx+JnQR9bFNODROIpHgYBCIR5kHMaYWHQpw8HCY5FpFcPoNbEzqgYo5FVFPnCaHVEhXIM580s2okuA5u1SUKVtzFoZfWt9mKR6eNvZUdq0sqMopFrLC0rB4adlckExeqN10auCMOsg129VmUYrU5W01SlVCySoqnpk5SmwaRs/JYjWQGNAjmSR0OV6h20zNoI6eQErfEUpJQsV4olVeIDU/+oW9oXqGxiwzDkUqaOkDE+VPlHBV4ysz4VOjScKg2aNKLmULcJc8kOFCTleTYapjxB5zFKn74hAGFuBYMbGuxjsN8i4SIYRfpGFMZNt90RLcZwMnfdc9+DjdO++bFMlB56xOyJxQ44KM4PVJutbffUMxbPJUqS8hTfSZVNMe71sxmv0SY5cjXJ862RmiNJtGwW9tWP9UK7Tl3BoUN+iL3aWY7y9k4wyWQTbTbFIcV+VKJUmbnKVZjaSk7bLO6b973TqsNCbOQCF12y3gbum981Nl/7n5S/AL/KQVz4jd/lIT4SICESITGSgMcVV2KBguxF2CrEFlfMJsTmJj1uuiNx2BFqfAI16qTJcNU1Rx1z3Am77XHeBSw8objmmKVfn3l61ZrhHJd4MNOKeCIy5CMnSQ0TbKl622TGC0689dFXP/0NMNAgg5U6jAWyNHk+vMQ7vMJrDB5k7m1lOhmutcfeZLCXFI1x6ThgVSjjEnDTLhPLZGqt2bZXj1TGjohj8ypu0wHmQB8yFsHBNBjCvm18U7ZTCg4iwmyT+yaFOjEFlR1x45kKr8NuSBiOtoKG6jpkZZb498SrbWATh4dKD9FsuhpszzgFffYE7rVQaGYuzME8tz7qaM+mIqHEYPzdZHLbs3ajrkO1hzJBlKPJ2xywtKnrJHL+EPMBAA==) format("woff2");}
+
+:root{--k:1.25;--font:"Pixelify Sans","PingFang SC","Hiragino Sans GB","Microsoft YaHei","Noto Sans SC",system-ui,sans-serif}
+*,*::before,*::after{box-sizing:border-box}
+html,body{margin:0;width:100%;height:100%;overflow:hidden;background:transparent}
+body{font:12px/1.4 var(--font);-webkit-font-smoothing:antialiased;-webkit-user-select:none;user-select:none}
+.scene{position:relative;width:100vw;height:100vh}
+.scene canvas{display:block;width:100%;height:100%;image-rendering:pixelated;image-rendering:crisp-edges;touch-action:none}
+.ov{position:absolute;inset:0;pointer-events:none;line-height:1.4}
+.scene canvas.up{position:absolute;inset:0;image-rendering:auto;pointer-events:none}
+.grip{position:absolute;left:calc(11 / 344 * 100%);top:calc(112 / 252 * 100%);width:16px;height:16px;cursor:nwse-resize;opacity:0;transition:opacity .15s;z-index:3}
+.scene:hover .grip{opacity:.95}
+.grip svg{display:block;width:100%;height:100%}
+.zoom-badge{position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);background:#27324f;color:#fff;font-weight:700;border-radius:6px;padding:2px 9px;font-size:13px;pointer-events:none;z-index:4}
+.bub{position:absolute;left:0;top:0;z-index:2;display:flex;align-items:center;gap:3px;max-width:min(64vw,calc(var(--k) * 150px));background:#fff;color:#1b2540;border:2px solid #27324f;border-radius:6px;padding:1px 6px 2px;font-size:max(10px,calc(var(--k) * 6.2px));font-weight:700;white-space:nowrap;box-shadow:2px 2px 0 rgba(20,24,40,.28)}
+.bub::after{content:"";position:absolute;left:var(--tail,50%);bottom:-6px;width:8px;height:8px;margin-left:-4px;background:inherit;border-right:2px solid #27324f;border-bottom:2px solid #27324f;transform:rotate(45deg)}
+.bub::before{content:"";position:absolute;left:var(--tail,50%);top:100%;width:2px;margin-left:-1px;height:var(--lead,0px);background:#27324f;opacity:.55}
+.bub.bot{background:#e6f4ff;transform:translate(-50%,calc(-100% - 7px))}
+.bub[hidden],.bub-detail[hidden]{display:none}
+.bub-label{flex:0 0 auto;max-width:calc(var(--k) * 96px);overflow:hidden;text-overflow:ellipsis}
+.bub-detail{flex:0 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;font:500 1em/1.3 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;color:#4d5875}
+.bub.compact .bub-detail{display:none}
+.bub.think{background:#f3f0ff}
+.bub.think .bub-detail{font-style:italic}
+.bub.type{background:#f2fbf4}
+.bub.type .bub-detail{color:#22324f}
+.bub.type .bub-detail::after{content:"\258d";margin-left:1px;color:#2f8f57;animation:office-caret 1s steps(1) infinite}
+.bub.wait{background:#eef4fb}
+.bub.alert{background:#fff1bf}
+.bub.bad{background:#ffe2dc}
+.bub.flash{background:#e6f7e9}
+.bub.picked{outline:2px solid #ffe14d;outline-offset:1px}
+@keyframes office-caret{50%{opacity:0}}
+.tag{position:absolute;transform:translate(-50%,calc(-100% - 8px));background:#ffe27a;color:#3a2a00;border:2px solid #27324f;border-radius:3px;font-size:max(10px,calc(var(--k) * 6px));font-weight:700;padding:0 4px;white-space:nowrap;z-index:3}
+
+:root{--office-paper:#fff9e9;--office-ink:#27324f;--office-line:#a8a6a4;--office-selected:#dce7f6}
+.office-controls{position:absolute;z-index:5;top:calc(var(--k)*2px);left:calc(var(--k)*4px);right:calc(var(--k)*4px);height:calc(var(--k)*26px);display:flex;align-items:center;gap:4px;font:12px/1.3 -apple-system,BlinkMacSystemFont,"PingFang SC","Segoe UI",sans-serif;color:var(--office-ink)}
+.office-tabs{display:flex;gap:3px;flex:1;min-width:0}
+.office-tab,.office-follow,.office-overflow{font:inherit;color:inherit;background:var(--office-paper);border:1px solid var(--office-line);border-radius:4px;cursor:pointer;min-width:0;padding:5px 7px;line-height:1.3}
+.office-tab{flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.office-tab[aria-selected="true"]{background:var(--office-selected);border-color:#526a91}
+.office-tab:hover,.office-follow:hover,.office-overflow:hover{background:#e6ecf5}
+.office-tab:focus-visible,.office-follow:focus-visible,.office-overflow:focus-visible{outline:2px solid #4378be;outline-offset:1px}
+.office-follow{flex:none;display:flex;align-items:center;gap:4px;white-space:nowrap}
+.office-follow::before{content:"";display:block;width:8px;height:8px;border:1px solid #65738b;border-radius:2px}
+.office-follow[aria-checked="true"]::before{background:#456b9c;border-color:#456b9c}
+.office-notice{position:absolute;left:50%;top:calc(var(--k)*30px);transform:translateX(-50%);max-width:90%;font:11px/1.5 -apple-system,BlinkMacSystemFont,"PingFang SC","Segoe UI",sans-serif;color:var(--office-ink);background:var(--office-paper);padding:2px 6px;border-radius:3px;z-index:4}
+.office-tool{flex:none;display:block;width:max(12px,calc(var(--k)*8px));height:max(12px,calc(var(--k)*8px))}
+.office-tool[hidden]{display:none}
+.office-overflow{position:absolute;right:calc(var(--k)*13px);bottom:calc(var(--k)*14px);z-index:4}
+.office-members{position:absolute;z-index:6;top:calc(var(--k)*30px);left:8px;right:8px;max-height:65%;overflow:auto;background:var(--office-paper);border:1px solid var(--office-line);border-radius:5px;padding:6px;scrollbar-color:#a8b6c9 var(--office-paper);scrollbar-width:thin}
+.office-members button{display:block;width:100%;background:transparent;border:0;color:var(--office-ink);text-align:left;padding:6px;cursor:pointer;font:12px/1.4 "Segoe UI",sans-serif}
+.office-members button:hover{background:var(--office-selected)}
+@media(max-width:400px){.office-controls{font-size:11px;gap:2px}.office-tab,.office-follow{padding:2px 3px}.office-tabs{gap:2px}.office-follow{gap:2px}.office-follow::before{width:6px;height:6px}}
+@media(max-width:250px){.office-tab,.office-follow{padding:0 1px;line-height:1}.office-follow::before{width:5px;height:5px}}
+@media(prefers-reduced-motion:reduce){.grip{transition:none}.bub.type .bub-detail::after{animation:none}}
+</style>
+</head>
+<body>
+<div class="scene" id="scene">
+  <div class="office-controls" aria-label="办公室切换">
+    <div class="office-tabs" id="officeTabs" role="tablist" aria-label="最近发消息的五个会话"></div>
+    <button class="office-follow" id="officeFollow" type="button" role="switch" aria-checked="true" title="跟随主窗口当前会话">跟随</button>
+  </div>
+  <div class="office-notice" id="officeNotice" role="status">正在连接会话</div>
+  <button class="office-overflow" id="officeOverflow" type="button" hidden></button>
+  <div class="office-members" id="officeMembers" hidden></div>
+  <canvas id="cv" width="344" height="252" aria-label="像素风 AI 办公室，Agent 们在工位上工作"></canvas>
+  <canvas id="up" class="up" hidden></canvas>
+  <div class="ov" id="ov"></div>
+  <div class="grip" id="grip" title="拖动调整大小，双击恢复默认大小"><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M2 7L7 2M2 11L11 2M2 15L15 2" stroke="#2b2737" stroke-width="3.4" stroke-linecap="square" fill="none"/><path d="M2 7L7 2M2 11L11 2M2 15L15 2" stroke="#ffffff" stroke-width="1.4" stroke-linecap="square" fill="none"/></svg></div>
+  <div class="zoom-badge" id="zoomBadge" hidden></div>
+</div>
+<script>
+/* AI Agent 像素办公室 —— 纯原生 JS，零依赖，可离线运行
+   ACECode 桌面宠物版：只保留场景画布与气泡层；草地不画（窗口在那里透明），
+   面板 / 按钮 / 花名册 / 事件日志全部去掉，交互改为拖动挪窗口 + 右键原生菜单。 */
+(() => {
+'use strict';
+/* =====================================================================
+   像素 AI 办公室 —— 资源复用思路
+   1. 一个图元 box()：所有家具、墙、机器人都是等距长方体拼出来的
+   2. 一个基色 → 三个面：mat(c) 自动算顶面/左面/右面明暗，换色只改一个值
+   3. 一个像素模板渲染器 pix() + 调色板：小人、图标、数字、信封全靠它
+   4. 小人 = 身体模板 × 调色板换色 × 水平翻转 × 动作补丁 × 配饰补丁
+   5. 一个描边后处理 outline()：所有精灵共用同一套像素描边
+   6. 一个精灵缓存 sprite(key)：同样外观只画一次，场景里无限实例化
+   7. 预制体：工位 = 椅子 + 人 + 桌 + 显示器；双人工位 = 工位 ×2（镜像）+ 隔板
+   ===================================================================== */
+
+/* ---------- 0. 工具 ---------- */
+const T = 8, RW = 88, RD = 72, WALL_H = 40;          // 1 格 = 8 单位，房间 11×9 格
+const VIEW = { w: 344, h: 252, ox: 156, oy: 86 };
+const INK = '#2b2737';                                // 统一描边色
+
+const mk = (w, h) => { const c = document.createElement('canvas'); c.width = w; c.height = h; return c; };
+const rng = s => () => { s |= 0; s = s + 0x6D2B79F5 | 0; let t = Math.imul(s ^ s >>> 15, 1 | s); t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t; return ((t ^ t >>> 14) >>> 0) / 4294967296; };
+const R = rng(20260927);
+const pick = a => a[(R() * a.length) | 0];
+const hash = n => { n = Math.imul(n ^ (n >>> 16), 0x45d9f3b); n = Math.imul(n ^ (n >>> 16), 0x45d9f3b); return ((n ^ (n >>> 16)) >>> 0) / 4294967296; };
+
+const toRGB = h => { const n = parseInt(h.slice(1), 16); return [n >> 16 & 255, n >> 8 & 255, n & 255]; };
+const toHex = a => '#' + a.map(v => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('');
+const mix = (a, b, t) => { const A = toRGB(a), B = toRGB(b); return toHex(A.map((v, i) => v + (B[i] - v) * t)); };
+const lite = (c, t) => mix(c, '#ffffff', t), dark = (c, t) => mix(c, '#000000', t);
+const mat = c => typeof c === 'object' ? c : { top: lite(c, .2), left: c, right: dark(c, .17) };
+
+/* ---------- 1. 等距光栅化：一个图元走天下 ---------- */
+const P = (o, x, y, z = 0) => [o.ox + 2 * (x - y), o.oy + x + y - z];
+
+function fillPoly(g, pts, color) {            // 自己扫描线填充，保证 2:1 像素阶梯清晰不糊
+  let y0 = Infinity, y1 = -Infinity;
+  for (const p of pts) { if (p[1] < y0) y0 = p[1]; if (p[1] > y1) y1 = p[1]; }
+  g.fillStyle = color;
+  for (let y = Math.floor(y0); y < Math.ceil(y1); y++) {
+    const cy = y + .5, xs = [];
+    for (let i = 0; i < pts.length; i++) {
+      const [ax, ay] = pts[i], [bx, by] = pts[(i + 1) % pts.length];
+      if ((ay <= cy && by > cy) || (by <= cy && ay > cy)) xs.push(ax + (cy - ay) * (bx - ax) / (by - ay));
+    }
+    xs.sort((a, b) => a - b);
+    for (let k = 0; k + 1 < xs.length; k += 2) {
+      const a = Math.round(xs[k]), b = Math.round(xs[k + 1]);
+      if (b > a) g.fillRect(a, y, b - a, 1);
+    }
+  }
+}
+function box(g, o, x, y, z, w, d, h, c) {
+  const m = mat(c);
+  if (h > 0) {
+    fillPoly(g, [P(o, x, y + d, z + h), P(o, x + w, y + d, z + h), P(o, x + w, y + d, z), P(o, x, y + d, z)], m.left);
+    fillPoly(g, [P(o, x + w, y, z + h), P(o, x + w, y + d, z + h), P(o, x + w, y + d, z), P(o, x + w, y, z)], m.right);
+  }
+  fillPoly(g, [P(o, x, y, z + h), P(o, x + w, y, z + h), P(o, x + w, y + d, z + h), P(o, x, y + d, z + h)], m.top);
+}
+const faceX = (g, o, x, y0, y1, z0, z1, c) => fillPoly(g, [P(o, x, y0, z1), P(o, x, y1, z1), P(o, x, y1, z0), P(o, x, y0, z0)], c);
+const faceY = (g, o, y, x0, x1, z0, z1, c) => fillPoly(g, [P(o, x0, y, z1), P(o, x1, y, z1), P(o, x1, y, z0), P(o, x0, y, z0)], c);
+const faceZ = (g, o, z, x0, y0, x1, y1, c) => fillPoly(g, [P(o, x0, y0, z), P(o, x1, y0, z), P(o, x1, y1, z), P(o, x0, y1, z)], c);
+function lineX(g, o, x, y0, y1, z, c) { g.fillStyle = c; for (let y = y0; y < y1; y++) { const [sx, sy] = P(o, x, y, z); g.fillRect(sx - 2, sy, 2, 1); } }
+function vline(g, o, x, y, z0, z1, c) { g.fillStyle = c; for (let z = z0; z < z1; z++) { const [sx, sy] = P(o, x, y, z); g.fillRect(sx - 1, sy, 1, 1); } }
+function lineY(g, o, y, x0, x1, z, c) { g.fillStyle = c; for (let x = x0; x < x1; x++) { const [sx, sy] = P(o, x, y, z); g.fillRect(sx, sy, 2, 1); } }
+
+/* ---------- 2. 描边 + 像素模板 + 精灵缓存 ---------- */
+function outline(cv, col = INK) {
+  const g = cv.getContext('2d'), W = cv.width, H = cv.height;
+  const im = g.getImageData(0, 0, W, H), d = im.data, a = new Uint8Array(W * H);
+  for (let i = 0; i < W * H; i++) a[i] = d[i * 4 + 3] > 0 ? 1 : 0;
+  const [r, gg, b] = toRGB(col);
+  for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
+    const i = y * W + x; if (a[i]) continue;
+    if ((x > 0 && a[i - 1]) || (x < W - 1 && a[i + 1]) || (y > 0 && a[i - W]) || (y < H - 1 && a[i + W])) {
+      const k = i * 4; d[k] = r; d[k + 1] = gg; d[k + 2] = b; d[k + 3] = 255;
+    }
+  }
+  g.putImageData(im, 0, 0);
+}
+function pix(rows, pal, flip = false, ol = true) {
+  const h = rows.length, w = rows[0].length, m = ol ? 1 : 0;
+  const cv = mk(w + 2 * m, h + 2 * m), g = cv.getContext('2d');
+  rows.forEach((row, y) => { for (let x = 0; x < w; x++) { const c = pal[row[x]]; if (!c) continue; g.fillStyle = c; g.fillRect((flip ? w - 1 - x : x) + m, y + m, 1, 1); } });
+  if (ol) outline(cv, pal.ink || INK);
+  return cv;
+}
+const patch = (rows, ps) => {
+  if (!ps) return rows; rows = rows.slice();
+  for (const [i, s] of ps) rows[i] = [...rows[i]].map((ch, k) => (s[k] && s[k] !== '_') ? s[k] : ch).join('');
+  return rows;
+};
+const SPR = new Map(); let blits = 0;
+const sprite = (key, build) => { let s = SPR.get(key); if (!s) { s = build(); SPR.set(key, s); } return s; };
+function isoSprite(key, [x0, y0, x1, y1, h], draw, ol = true) {
+  return sprite(key, () => {
+    const m = 2, sx0 = 2 * (x0 - y1), sx1 = 2 * (x1 - y0), sy0 = x0 + y0 - h, sy1 = x1 + y1;
+    const cv = mk(sx1 - sx0 + 2 * m, sy1 - sy0 + 2 * m), o = { ox: m - sx0, oy: m - sy0 };
+    draw(cv.getContext('2d'), o);
+    if (ol) outline(cv);
+    return { cv, ax: o.ox, ay: o.oy };
+  });
+}
+function blit(c, s, x, y, z = 0) {
+  const [sx, sy] = P(VIEW, x, y, z);
+  c.drawImage(s.cv, Math.round(sx - s.ax), Math.round(sy - s.ay)); blits++;
+}
+
+/* ---------- 3. 小人：1 套模板 × 调色板 × 翻转 × 补丁 ---------- */
+const BODY = {
+  front: [ // 面朝右下（看得见脸）
+    '....hhhhh...',
+    '..hhhhhhhhh.',
+    '.hhhhhhhllhh',
+    '.hhhhhhhhhhh',
+    '.hhhhhhshhsh',
+    '.hhhhsssssss',
+    '.Hhhssessses',
+    '.Hhhssessses',
+    '..Hhsbssssbs',
+    '...HSsssssS.',
+    '.....sss....',
+    '...cwwwwcc..',
+    '..ccccwwcccc',
+    '.ccccccccccc',
+    '.sCccccccccs',
+    '..CCCCCCCC..',
+    '..pppppppp..'],
+  back: [  // 背对镜头（面朝左上）
+    '...hhhhhh...',
+    '..hhhhhhhhh.',
+    '.hhhhllhhhhh',
+    '.hhhhhhhhhhh',
+    '.hhhhhhhhhhh',
+    '.hhhhhhhhhhh',
+    '.hhhhhhhhhhs',
+    '.HhhhhhhhhHs',
+    '..HHhhhhhHS.',
+    '...HHHHHH...',
+    '.....sss....',
+    '...cccccc...',
+    '..cccccccc..',
+    '.cccccccccc.',
+    '.sCccccccCs.',
+    '..CCCCCCCC..',
+    '..pppppppp..'],
+};
+const FRAMES = { // 动作 = 在同一模板上打几行补丁（_ 表示不变）
+  front: {
+    typeA: [[13, '_s__________'], [14, '_C__________']],
+    typeB: [[13, '___________s'], [14, '___________c']],
+    blink: [[6, '______s___s_']],
+  },
+  back: {
+    typeA: [[13, '_s__________'], [14, '_c__________']],
+    typeB: [[13, '__________s_'], [14, '__________C_']],
+  },
+};
+const ACC = { // 配饰 / 发型也是补丁
+  long:    { front: [[8, '.h__________'], [9, '.hh_________'], [10, '.hH_________'], [11, '.hH_________'], [12, '.H__________']],
+             back:  [[9, '.hhHHHHHHhh.'], [10, '..hhhhhhhh..'], [11, '..hHhhhhHh..']] },
+  tie:     { front: [[12, '______r_____'], [13, '______r_____']] },
+  glasses: { front: [[6, '_____g_ggg_g']], back: [[6, '__________g_']] },
+  headset: { front: [[1, '__aaaaaaaaa_'], [5, '__aA________'], [6, '__aA________'], [7, '__aA________'], [8, '____a_______'], [9, '____aa______']],
+             back:  [[1, '__aaaaaaaaa_'], [5, '_a_________a'], [6, '_a_________a']] },
+  cap:     { front: [[0, '....aaaaa...'], [1, '..aaaaaaaaa.'], [2, '.aaaaaaaaaaa'], [3, '________AAAA']],
+             back:  [[0, '...aaaaaa...'], [1, '..aaaaaaaaa.'], [2, '.aaaaaaaaaaa'], [3, '.aaaaaaaaaaa']] },
+
+  // ---- 扩充发型（10 种）：只改头发像素，发色跟着 h / H / l 走 ----
+  ponytail:  { front: [[2, 'a___________'], [3, 'h___________'], [4, 'h___________'], [5, 'h___________'], [6, 'H___________'], [7, 'h___________'], [8, 'Hh__________'], [9, '.H__________']],
+               back:  [[4, '_____aa_____'], [9, '_____hh_____'], [10, '_____hH_____'], [11, '_____hh_____'], [12, '_____H______']] },
+  twintails: { front: [[2, 'a___________'], [3, 'h___________'], [4, 'h___________'], [5, 'h___________'], [6, 'H___________'], [7, 'h___________'], [8, 'Hh__________'], [9, '.H_________a'], [10, '___________h'], [11, '__________hH']],
+               back:  [[3, 'a__________a'], [4, 'h___________'], [5, 'h___________'], [6, 'H___________'], [7, 'h___________'], [8, 'h__________h'], [9, 'H_________hh'], [10, '_h________hH'], [11, '_H__________']] },
+  bun:       { front: [[0, 'hlh.________'], [1, 'hhHa________'], [2, 'H___________']],
+               back:  [[1, '____HHHH____'], [2, '___HhllhH___'], [3, '___HhhhhH___'], [4, '____HHHH____'], [5, '_____aa_____']] },
+  spiky:     { front: [[0, '...h.h.h.h..'], [1, '.hhhhhhhlhhh'], [2, 'h___________'], [4, 'h___________']],
+               back:  [[0, '..h.h.h.h.h.'], [1, '.hhhhhhhhhhh'], [3, 'h___________'], [5, 'h___________']] },
+  bald:      { front: [[0, '....sssss...'], [1, '..Sssssssss.'], [2, '.Ssssssswsss'], [3, '.Sssssssssss'], [4, '.SsSssssssss'], [5, '.SsbSsssssss'], [6, '.SsS________'], [7, '.SSs________'], [8, '..Ss________'], [9, '...S________']],
+               back:  [[0, '...ssssss...'], [1, '..sssssssss.'], [2, '.sssswssssss'], [3, '.sssssssssss'], [4, '.sssssssssss'], [5, '.sssssssssss'], [6, '.Sssssssssss'], [7, '.SssssssssSs'], [8, '..SSsssssSS.'], [9, '...SSSSSS...']] },
+  bangs:     { front: [[4, '.hhhhhhhhhhh'], [5, '_____HhHhHhH']] },
+  bob:       { front: [[5, '___________h'], [6, 'hHhh_______h'], [7, 'hHhh_______h'], [8, 'hhhH_______H'], [9, '.HHH________']],
+               back:  [[6, 'hhhhhhhhhhhh'], [7, 'hHhhhhhhhhHh'], [8, 'hHHhhhhhhHHh'], [9, '.HHHHHHHHHH.']] },
+  afro:      { front: [[0, '..hhlhhhhh..'], [1, '.hhhhhhlhhhh'], [2, 'hhlhhhhhhhhh'], [3, 'hhhhhlhhhhhh'], [4, 'hh_l________'], [5, 'hhlh________'], [6, 'hHhh________'], [7, 'hhHh________'], [8, '.hHh________']],
+               back:  [[0, '..hhhlhhhh..'], [1, '.hhlhhhhhlhh'], [2, 'hhhhhhlhhhhh'], [3, 'hlhhhhhhhlhh'], [4, 'hhhhlhhhhhhh'], [5, 'hhhhhhhhlhhh'], [6, 'hhlhhhhhhhhs'], [7, 'hHhhhhlhhhHs'], [8, '.hHHhhhhhHS.']] },
+  mohawk:    { front: [[0, '...hhlhh....'], [1, '..HhhhhhHHH.'], [2, '.HHHhhhhHHHH'], [3, '.HHHHhhHHHHH'], [4, '.HHHHHHsHHsH'], [5, '.HHHH_______'], [6, '.HHH________'], [7, '.HHH________'], [8, '..HH________']],
+               back:  [[0, '...HHhhHH...'], [1, '..HHHhhHHHH.'], [2, '.HHHHhlHHHHH'], [3, '.HHHHhhHHHHH'], [4, '.HHHHhhHHHHH'], [5, '.HHHHhhHHHHH'], [6, '.HHHHhhHHHHs'], [7, '.HHHHhhHHHHs'], [8, '..HHHhhHHHS.']] },
+  braid:     { front: [[8, '_h__________'], [9, '_hH_________'], [10, '__Hh________'], [11, '__hH________'], [12, '__Hh________'], [13, '___a________']],
+               back:  [[9, '_____hH_____'], [10, '_____Hh_____'], [11, '_____hH_____'], [12, '_____Hh_____'], [13, '_____aa_____']] },
+
+  // ---- 扩充配饰（10 种）：帽子 / 头饰 / 脸部 / 胸前，颜色走 a / A（accColor）或固定色 ----
+  beanie:    { front: [[0, '....aawaa...'], [1, '..aaaaaaaaa.'], [2, '.aaaaaaaaaaa'], [3, '.AAAAAAAAAAA']],
+               back:  [[0, '...aawaaa...'], [1, '..aaaaaaaaa.'], [2, '.aaaaaaaaaaa'], [3, '.AAAAAAAAAAA']] },
+  headband:  { front: [[3, '.aaaaaaaaaaa']],
+               back:  [[3, '.aaaaaaaaaaa'], [4, 'a___________'], [5, 'A___________']] },
+  bow:       { front: [[0, 'aa.aa_______'], [1, 'aAAa________'], [2, '.a__________']],
+               back:  [[0, '...aa.aa....'], [1, '...aaAAaa...'], [2, '____a__a____']] },
+  shades:    { front: [[6, '____gkkgkkkk'], [7, '_____kk__kk_']], back: [[6, '__________g_']] },
+  mask:      { front: [[7, '____M_______'], [8, '____Mmmmmmmm'], [9, '____MmmmmmM_']], back: [[7, '__________M_']] },
+  beard:     { front: [[7, '____h_______'], [8, '____hhsssshh'], [9, '___HhhhhhhH_']], back: [[8, '__________h_']] },
+  mustache:  { front: [[8, '______HhhH__'], [9, '______H__H__']] },
+  bowtie:    { front: [[11, '____aaAaa___'], [12, '____a___a___']] },
+  badge:     { front: [[11, '____a___a___'], [12, '_____a_a____'], [13, '_____yYy____']], back: [[11, '____aaaa____']] },
+  scarf:     { front: [[10, '____aAaAa___'], [11, '___aaaaaaa__'], [12, '____A_______'], [13, '____a_______']],
+               back:  [[10, '____aAaAa___'], [11, '___aaaaaa___']] },
+};
+const luminance = c => { const [r, g, b] = toRGB(c); return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255; };
+function lookPal(L) {
+  return {
+    h: L.hair, H: dark(L.hair, .28), l: lite(L.hair, .35),
+    // 深肤色上默认眼色几乎看不见，换成更深的一档
+    s: L.skin, S: dark(L.skin, .13), b: mix(L.skin, '#ff6f6f', .35), e: luminance(L.skin) < .45 ? '#140d12' : '#2a2230',
+    c: L.shirt, C: dark(L.shirt, .22), w: '#ffffff', p: L.pants || '#3a3f52',
+    a: L.accColor || '#454b5e', A: L.accColor ? dark(L.accColor, .25) : '#ff8a5c',
+    r: '#d8423a', g: '#9aa3b8',
+    k: '#1d2130', m: '#f3f6fb', M: '#c5cdd9', y: '#ffd35c', Y: '#d9a92e',   // 墨镜片 / 口罩 / 工牌卡片
+  };
+}
+// 走路 = 坐姿模板下面再接三行腿脚;手臂沿用打字的两帧补丁当摆臂
+const LEGS = {
+  stand: ['...pp..pp...', '...pp..pp...', '..kkk..kkk..'],
+  walkA: ['..pp....pp..', '.pp......pp.', '.kk......kk.'],
+  walkB: ['...pp..pp...', '...pp..pp...', '..kkk..kkk..'],
+};
+const WALK_ARMS = { walkA: 'typeA', walkB: 'typeB' };
+function charSprite(L, pose, frame, flip) {
+  return sprite(`ch|${L.key}|${pose}|${frame}|${+flip}`, () => {
+    const legs = LEGS[frame];
+    let rows = patch(BODY[pose], FRAMES[pose][legs ? WALK_ARMS[frame] : frame]);
+    for (const k of L.acc) rows = patch(rows, ACC[k] && ACC[k][pose]);
+    if (legs) rows = rows.concat(legs);
+    const cv = pix(rows, lookPal(L), flip);
+    return { cv, ax: cv.width >> 1, ay: cv.height - 2 };
+  });
+}
+
+/* ---------- 4. 其他像素模板（图标 / 数字 / 信封 / 植物） ---------- */
+const MINI = {
+  q: ['.yyy.', 'y...y', '...y.', '..y..', '.....', '..y..'],
+  ex: ['y', 'y', 'y', 'y', '.', 'y'],
+  star: ['..y..', '.yyy.', 'yyyyy', '.yyy.', 'y...y'],
+  z: ['yyyy', '..y.', '.y..', 'yyyy'],
+  arrow: ['yyyyy', '.yyy.', '..y..'],
+  dot: ['yy', 'yy'],
+  glass: ['yyyyy', '.y.y.', '..y..', '.y.y.', 'yyyyy'],
+};
+const miniSpr = (n, c) => sprite(`mi|${n}|${c}`, () => ({ cv: pix(MINI[n], { y: c }) }));
+const DIGITS = {
+  0: ['###', '#.#', '#.#', '#.#', '###'], 1: ['.#.', '##.', '.#.', '.#.', '###'], 2: ['###', '..#', '###', '#..', '###'],
+  3: ['###', '..#', '.##', '..#', '###'], 4: ['#.#', '#.#', '###', '..#', '..#'], 5: ['###', '#..', '###', '..#', '###'],
+  6: ['###', '#..', '###', '#.#', '###'], 7: ['###', '..#', '..#', '.#.', '.#.'], 8: ['###', '#.#', '###', '#.#', '###'],
+  9: ['###', '#.#', '###', '..#', '###'], '+': ['...', '.#.', '###', '.#.', '...'],
+};
+const digitSpr = (ch, c) => sprite(`dg|${ch}|${c}`, () => ({ cv: pix(DIGITS[ch], { '#': c }) }));
+const ENV = ['wwwwwwwwwwwww', 'wWwwwwwwwwwWw', 'wwWwwwwwwwWww', 'wwwWwwwwwWwww', 'wwwwWwrwWwwww', 'wwwwwWrWwwwww', 'wwwwwwwwwwwww', 'wwwwwwwwwwwww'];
+const envSpr = () => sprite('env', () => ({ cv: pix(ENV, { w: '#fffdf4', W: '#cfc6b2', r: '#e5534b' }) }));
+const LEAF = [
+  '......l......', '..l...lG..l..', '..Gl.lGG.lG..', '...GllGGlG...', '.lGGgGGGgGGl.', 'lG..gGgGg..Gl',
+  '...lgGgGgl...', '..lG.gGg.Gl..', '.lG..gGg..Gl.', '.....gGg.....', '......g......'];
+const TREE = [
+  '.....lGGl.....', '...lGGgGGGl...', '..lGGgGGgGGl..', '.lGgGGlGGGgGl.', 'lGGGgGGGgGGGGl', 'GGgGGGlGGGGgGG',
+  'GGGGgGGGGgGGGG', '.GgGGGGgGGGgG.', '..GGgGGGGgGG..', '...GGGGgGGG...', '.....GGGG.....', '......tt......'];
+const ICON8 = {
+  plan:   { rows: ['..yyyy..', '.yywyyy.', '.ywyyyy.', '.yyyyyy.', '..yyyy..', '...gg...', '..gggg..', '...gg...'], pal: { y: '#ffd54a', w: '#fff7cf', g: '#9aa3b5' } },
+  code:   { rows: ['dddddddd', 'dkkkkkkd', 'dkgkkkkd', 'dkkgkkkd', 'dkgkwwkd', 'dkkkkkkd', 'dddddddd'], pal: { d: '#8ea3cf', k: '#1e2638', g: '#66e08f', w: '#ffffff' } },
+  review: { rows: ['.bbbb...', 'bwllwb..', 'blwwlb..', 'bwwwwb..', '.bbbb...', '....hh..', '.....hh.', '......hh'], pal: { b: '#5a6f9e', w: '#dff1ff', l: '#9fd4ff', h: '#b8773f' } },
+  test:   { rows: ['.......g', '......gg', '.....gg.', 'g...gg..', 'gg.gg...', '.ggg....', '..g.....'], pal: { g: '#45c46e' } },
+};
+
+/* ---------- 5. 家具预制体（全部由 box() 拼成） ---------- */
+const DESK_W = '#eceff4', DESK_WOOD = '#b8773f', MON = '#2f3341';
+const CH = { blue: '#3b6fe0', gray: '#5e6475', red: '#d9505e', green: '#4fb35a', orange: '#ef8a3a' };
+
+// 工位局部坐标：u = 朝向轴（人朝 +u 或 -u），v = 横向；axis 决定映射到世界 x 还是 y
+const sBox = (g, o, ax, u, v, z, du, dv, h, c) => ax === 'x' ? box(g, o, u, v, z, du, dv, h, c) : box(g, o, v, u, z, dv, du, h, c);
+const sLineU = (g, o, ax, v, u0, u1, z, c) => ax === 'x' ? lineY(g, o, v, u0, u1, z, c) : lineX(g, o, v, u0, u1, z, c);
+const sLineV = (g, o, ax, u, v0, v1, z, c) => ax === 'x' ? lineX(g, o, u, v0, v1, z, c) : lineY(g, o, u, v0, v1, z, c);
+const sFaceU = (g, o, ax, u, v0, v1, z0, z1, c) => ax === 'x' ? faceX(g, o, u, v0, v1, z0, z1, c) : faceY(g, o, u, v0, v1, z0, z1, c);
+
+function stationSprite(S, part) {  // 同款工位（朝向+配色相同）只渲染一次
+  const { axis: ax, s, desk, chair, mon } = S;
+  return isoSprite(`st|${ax}|${s}|${desk}|${chair}|${mon}|${part}`, [-11, -11, 11, 11, 18], (g, o) => {
+    const d0 = s > 0 ? 3 : -10, mu = s > 0 ? 7 : -8, ku = s > 0 ? 3 : -5;
+    const B = (...a) => sBox(g, o, ax, ...a);
+    const chairBack = () => B(s > 0 ? -3 : 2, -2, 4, 1, 4, 7, chair);
+    const chairBase = () => { B(-2, -2, 0, 4, 4, 1, '#4a4e60'); B(-1, -1, 1, 2, 2, 2, '#5d6275'); B(-2, -2, 3, 4, 4, 1, chair); };
+    const deskAll = () => {
+      B(d0, -6, 0, 7, 1, 6, dark(desk, .1));                 // 挡板
+      B(d0, 2, 0, 7, 4, 6, desk);                             // 抽屉柜
+      const dl = dark(desk, .3);
+      sLineU(g, o, ax, 6, d0 + 1, d0 + 6, 4, dl); sLineU(g, o, ax, 6, d0 + 1, d0 + 6, 2, dl);
+      B(d0, -6, 6, 7, 12, 2, desk);                           // 桌面
+    };
+    const keyboard = () => B(ku, -3, 8, 2, 4, 1, '#d3d8e2');
+    const monitor = () => { B(mu - 1, -3, 8, 3, 3, 1, mon); B(mu, -2, 9, 1, 1, 2, mon); B(mu, -5, 10, 1, 6, 6, mon); };
+    const mug = () => B(d0 + (s > 0 ? 1 : 5), 4, 8, 1, 1, 2, '#f5f5f5');
+    if (s > 0) { if (part === 'back') { chairBack(); chairBase(); } else { deskAll(); keyboard(); monitor(); mug(); } }
+    else { if (part === 'back') { deskAll(); monitor(); keyboard(); mug(); chairBase(); } else chairBack(); }
+  });
+}
+const dividerSpr = (ax, col) => isoSprite(`dv|${ax}|${col}`, [-7, -7, 7, 7, 15], (g, o) => sBox(g, o, ax, 0, -6, 0, 1, 12, 13, col));
+
+const SP = {
+  plant: () => isoSprite('plant', [-3, -3, 3, 3, 20], (g, o) => {
+    box(g, o, -2, -2, 0, 4, 4, 5, '#eee9df'); faceZ(g, o, 5, -1, -1, 1, 1, '#6b4a2e');
+    const lv = pix(LEAF, { l: '#8fd46a', G: '#4fa846', g: '#2f7d3a' }, false, false);
+    const [sx, sy] = P(o, 0, 0, 5); g.drawImage(lv, sx - (lv.width >> 1), sy - lv.height + 2);
+  }),
+  cooler: () => isoSprite('cooler', [-3, -3, 3, 3, 18], (g, o) => {
+    box(g, o, -2, -2, 0, 4, 4, 9, '#eef1f6');
+    const [sx, sy] = P(o, 2, 0, 7); g.fillStyle = '#e5534b'; g.fillRect(sx - 3, sy, 1, 1); g.fillStyle = '#3a8cf0'; g.fillRect(sx - 1, sy - 1, 1, 1);
+    box(g, o, -1, -1, 9, 2, 2, 6, '#86c8f5'); box(g, o, -1, -1, 15, 2, 2, 1, '#4a90d0');
+  }),
+  cabinet: () => isoSprite('cab', [0, 0, 5, 8, 15], (g, o) => {
+    box(g, o, 0, 0, 0, 5, 8, 14, '#d7dbe3');
+    const [sx, sy] = P(o, 5, 4, 14); g.fillStyle = '#9aa1b0'; g.fillRect(sx - 1, sy + 1, 1, 12);
+    g.fillStyle = '#6d7486'; g.fillRect(sx - 3, sy + 6, 1, 2); g.fillRect(sx + 1, sy + 6, 1, 2);
+  }),
+  shelf: () => isoSprite('shelf', [0, 0, 10, 5, 24], (g, o) => {
+    box(g, o, 0, 0, 0, 10, 5, 23, '#c98f55');
+    const BOOK = ['#e5534b', '#3a8cf0', '#f2c14e', '#45b36a', '#8e6bd8', '#f08a3c', '#2fb5b0'];
+    for (const z0 of [2, 9, 16]) {
+      faceY(g, o, 5, 1, 9, z0, z0 + 6, '#7a4f2c');
+      for (let x = 1; x < 9; x++) { const hh = 3 + ((hash(x * 31 + z0) * 3) | 0); faceY(g, o, 5, x, x + 1, z0, z0 + hh, BOOK[(x * 3 + z0) % BOOK.length]); }
+    }
+  }),
+  rack: () => isoSprite('rack', [0, 0, 6, 7, 29], (g, o) => {
+    box(g, o, 0, 0, 0, 6, 7, 28, '#3a4052');
+    faceY(g, o, 7, 1, 5, 2, 26, '#232838');
+    for (let z = 4; z < 26; z += 4) lineY(g, o, 7, 1, 5, z, '#4b5268');
+    for (let z = 6; z < 24; z += 3) lineX(g, o, 6, 2, 6, z, '#2c3140');
+  }),
+  counter: () => isoSprite('counter', [0, 0, 20, 5, 18], (g, o) => {
+    box(g, o, 0, 0, 0, 20, 5, 8, '#eef0f4');
+    for (let x = 5; x < 20; x += 5) { const [sx, sy] = P(o, x, 5, 7); g.fillStyle = '#b9c0cc'; g.fillRect(sx, sy + 1, 1, 6); }
+    box(g, o, 0, 0, 8, 20, 5, 1, DESK_WOOD);
+    box(g, o, 3, 1, 9, 4, 3, 6, '#3b3f4c'); faceY(g, o, 4, 4, 6, 11, 14, '#1f232e');
+    box(g, o, 9, 2, 9, 1, 1, 2, '#ffffff'); box(g, o, 11, 2, 9, 1, 1, 2, '#ffe0a3');
+  }),
+  table: () => isoSprite('table', [0, 0, 20, 6, 9], (g, o) => {
+    for (const [x, y] of [[0, 0], [19, 0], [0, 5], [19, 5]]) box(g, o, x, y, 0, 1, 1, 6, '#6d4a2c');
+    box(g, o, 0, 0, 6, 20, 6, 2, '#c0824a');
+    faceZ(g, o, 8, 3, 1, 6, 4, '#ffffff'); faceZ(g, o, 8, 12, 2, 15, 5, '#fff3c4');
+  }),
+  stool: () => isoSprite('stool', [-2, -2, 2, 2, 6], (g, o) => { box(g, o, -1, -1, 0, 2, 2, 4, '#6d4a2c'); box(g, o, -2, -2, 4, 4, 4, 1, '#e9774f'); }),
+  robot: dir => isoSprite(`bot|${dir}`, [-3, -3, 3, 3, 14], (g, o) => {
+    box(g, o, -2, -2, 0, 4, 4, 1, '#3b3f4c'); box(g, o, -2, -2, 1, 4, 4, 5, '#eef3f9');
+    lineX(g, o, 2, -2, 2, 3, '#4aa3ff'); lineY(g, o, 2, -2, 2, 3, '#4aa3ff');
+    box(g, o, -2, -2, 6, 4, 4, 4, '#d6e2f1');
+    box(g, o, 0, 0, 10, 1, 1, 2, '#8a93a8'); box(g, o, 0, 0, 12, 1, 1, 1, '#ff5a5a');
+    g.fillStyle = '#7ff3ff';
+    if (dir === '+x') { faceX(g, o, 2, -1, 1, 7, 9, '#223049'); g.fillStyle = '#7ff3ff'; g.fillRect(o.ox + 3, o.oy - 6, 1, 1); g.fillRect(o.ox + 5, o.oy - 7, 1, 1); }
+    if (dir === '+y') { faceY(g, o, 2, -1, 1, 7, 9, '#223049'); g.fillStyle = '#7ff3ff'; g.fillRect(o.ox - 4, o.oy - 6, 1, 1); g.fillRect(o.ox - 6, o.oy - 7, 1, 1); }
+  }),
+
+  // ---- 扩充物品：落地 16 种（墙面 4 种见 WALL_KINDS） ----
+  sofa: col => isoSprite(`sofa|${col}`, [0, 0, 16, 6, 10], (g, o) => {
+    box(g, o, 0, 0, 0, 16, 6, 3, dark(col, .18)); box(g, o, 0, 0, 3, 16, 2, 6, col);
+    box(g, o, 0, 2, 3, 2, 4, 3, dark(col, .06));
+    box(g, o, 2, 2, 3, 6, 4, 2, lite(col, .12)); box(g, o, 8, 2, 3, 6, 4, 2, lite(col, .12));
+    box(g, o, 14, 2, 3, 2, 4, 3, dark(col, .06));
+  }),
+  beanbag: col => isoSprite(`bean|${col}`, [0, 0, 5, 5, 7], (g, o) => { box(g, o, 0, 0, 0, 5, 5, 3, col); box(g, o, 1, 0, 3, 4, 4, 2, lite(col, .1)); box(g, o, 0, 0, 3, 2, 5, 3, dark(col, .08)); }),
+  lamp: () => isoSprite('lamp', [-1, -1, 2, 2, 20], (g, o) => {
+    box(g, o, 0, 0, 0, 2, 2, 1, '#3a3f52'); box(g, o, 0, 0, 1, 1, 1, 14, '#8a93a8'); box(g, o, -1, -1, 15, 3, 3, 4, '#ffe7a8');
+  }),
+  printer: () => isoSprite('printer', [0, 0, 6, 5, 12], (g, o) => {
+    box(g, o, 0, 0, 0, 6, 5, 6, '#c9ced8'); lineY(g, o, 5, 1, 5, 3, '#9aa1b0');
+    box(g, o, 0, 0, 6, 6, 5, 4, '#eef0f4'); faceY(g, o, 5, 1, 5, 7, 8, '#2b2737');
+    box(g, o, 1, 1, 10, 4, 3, 1, '#ffffff');
+    const [sx, sy] = P(o, 6, 1, 9); g.fillStyle = '#45c46e'; g.fillRect(sx - 1, sy, 1, 1);
+  }),
+  fridge: () => isoSprite('fridge', [0, 0, 5, 5, 16], (g, o) => {   // 复古薄荷色小冰箱，比打印机高一截
+    box(g, o, 0, 0, 0, 5, 5, 15, '#bfe3d6'); lineY(g, o, 5, 0, 5, 10, '#8cc2ae');
+    faceY(g, o, 5, 4, 5, 11, 14, '#e8e8e8'); faceY(g, o, 5, 4, 5, 5, 9, '#e8e8e8');
+    const [sx, sy] = P(o, 1, 5, 13); g.fillStyle = '#e5534b'; g.fillRect(sx, sy, 1, 1); g.fillStyle = '#f2c14e'; g.fillRect(sx + 2, sy + 1, 1, 1);
+  }),
+  vending: col => isoSprite(`vend|${col}`, [0, 0, 7, 6, 25], (g, o) => {
+    box(g, o, 0, 0, 0, 7, 6, 24, col); faceY(g, o, 6, 1, 5, 9, 21, '#bfe3ff');
+    const CAN = ['#e5534b', '#f2c14e', '#45b36a', '#3a8cf0', '#8e6bd8'];
+    for (const z of [10, 13, 16, 19]) for (let x = 1; x < 5; x++) faceY(g, o, 6, x, x + 1, z, z + 2, CAN[(x + z) % CAN.length]);
+    faceY(g, o, 6, 1, 5, 3, 6, '#2b2737'); faceX(g, o, 7, 2, 4, 12, 16, '#e8e8e8');
+  }),
+  lockers: col => isoSprite(`lock|${col}`, [0, 0, 12, 5, 21], (g, o) => {
+    box(g, o, 0, 0, 0, 12, 5, 20, col);
+    for (const x of [4, 8]) vline(g, o, x, 5, 1, 19, dark(col, .3));
+    for (const x0 of [0, 4, 8]) {
+      lineY(g, o, 5, x0 + 1, x0 + 3, 17, dark(col, .25)); lineY(g, o, 5, x0 + 1, x0 + 3, 16, dark(col, .25));
+      const [sx, sy] = P(o, x0 + 3, 5, 10); g.fillStyle = '#e8e8e8'; g.fillRect(sx - 1, sy, 1, 2);
+    }
+  }),
+  easel: () => isoSprite('easel', [0, 0, 12, 3, 19], (g, o) => {
+    box(g, o, 0, 1, 0, 1, 2, 7, '#9aa1b0'); box(g, o, 11, 1, 0, 1, 2, 7, '#9aa1b0');
+    box(g, o, 0, 1, 7, 12, 1, 11, '#c9ced8'); faceY(g, o, 2, 1, 11, 8, 17, '#fdfdf8');
+    lineY(g, o, 2, 2, 7, 15, '#3a8cf0'); lineY(g, o, 2, 2, 9, 12, '#e5534b'); lineY(g, o, 2, 3, 6, 10, '#45b36a');
+  }),
+  boxes: () => isoSprite('boxes', [0, 0, 9, 6, 8], (g, o) => {
+    box(g, o, 0, 0, 0, 5, 5, 4, '#c9975b'); faceZ(g, o, 4, 2, 0, 3, 5, '#ead3a6');
+    box(g, o, 1, 1, 4, 4, 4, 3, '#bf8750'); faceZ(g, o, 7, 2, 1, 3, 5, '#ead3a6');
+    box(g, o, 5, 1, 0, 4, 4, 3, '#d4a46a'); faceZ(g, o, 3, 5, 2, 9, 3, '#ead3a6');
+  }),
+  bins: () => isoSprite('bins', [0, 0, 7, 3, 6], (g, o) => {
+    box(g, o, 0, 0, 0, 3, 3, 5, '#6d7486'); faceZ(g, o, 5, 0, 0, 3, 3, '#3a3f52');
+    box(g, o, 4, 0, 0, 3, 3, 5, '#3f9a5c'); faceZ(g, o, 5, 4, 0, 7, 3, '#2a6e41');
+    const [sx, sy] = P(o, 5, 3, 3); g.fillStyle = '#d7f5e1'; g.fillRect(sx, sy, 2, 1);
+  }),
+  bigplant: () => isoSprite('bigplant', [-2, -2, 2, 2, 32], (g, o) => {   // 琴叶榕：木盆 + 树干 + 大树冠
+    box(g, o, -2, -2, 0, 4, 4, 6, '#c98f55'); faceZ(g, o, 6, -1, -1, 1, 1, '#6b4a2e');
+    box(g, o, 0, 0, 6, 1, 1, 8, '#7a5230');
+    const tr = pix(TREE, { l: '#8fd46a', G: '#4fa846', g: '#2f7d3a', t: '#6b4a2e' }, false, false);
+    const [sx, sy] = P(o, 0, 0, 12); g.drawImage(tr, sx - (tr.width >> 1), sy - tr.height + 3);
+  }),
+  cactus: () => isoSprite('cactus', [-1, -1, 2, 2, 12], (g, o) => {
+    box(g, o, -1, -1, 0, 3, 3, 3, '#e27d60'); box(g, o, 0, 0, 3, 1, 1, 7, '#4fa846');
+    box(g, o, -1, 0, 5, 1, 1, 3, '#4fa846'); box(g, o, 1, 0, 6, 1, 1, 2, '#4fa846');
+    const [sx, sy] = P(o, 0, 0, 10); g.fillStyle = '#ff9fbf'; g.fillRect(sx - 1, sy - 1, 2, 1);
+  }),
+  arcade: col => isoSprite(`arc|${col}`, [0, 0, 6, 8, 23], (g, o) => {
+    box(g, o, 0, 0, 0, 6, 6, 22, col); faceY(g, o, 6, 1, 5, 13, 19, '#141a2e');
+    faceY(g, o, 6, 2, 3, 15, 16, '#62f08e'); faceY(g, o, 6, 3, 4, 17, 18, '#ffcc4d');
+    box(g, o, 0, 6, 9, 6, 2, 2, dark(col, .25));
+    let [sx, sy] = P(o, 2, 7, 11); g.fillStyle = '#e5534b'; g.fillRect(sx, sy, 1, 1);
+    [sx, sy] = P(o, 4, 7, 11); g.fillStyle = '#f2c14e'; g.fillRect(sx, sy, 1, 1);
+    faceY(g, o, 6, 0, 6, 19, 22, '#ffcc4d');
+  }),
+  purifier: () => isoSprite('purif', [0, 0, 4, 4, 13], (g, o) => {
+    box(g, o, 0, 0, 0, 4, 4, 12, '#f4f6fa');
+    for (const z of [3, 5, 7]) lineY(g, o, 4, 1, 3, z, '#c9d0dc');
+    faceY(g, o, 4, 1, 3, 10, 11, '#5ab8ff');
+  }),
+  coatrack: col => isoSprite(`coat|${col}`, [-1, -1, 3, 2, 21], (g, o) => {
+    box(g, o, -1, -1, 0, 3, 3, 1, '#6d4a2c'); box(g, o, 0, 0, 1, 1, 1, 18, '#8b5a39');
+    box(g, o, -1, 0, 17, 3, 1, 1, '#8b5a39'); box(g, o, 1, 0, 9, 2, 1, 8, col);
+    box(g, o, -1, -1, 19, 2, 2, 1, '#3a3f52'); box(g, o, -1, -1, 18, 2, 2, 1, dark('#3a3f52', .2));
+  }),
+  coffeetable: () => isoSprite('ctable', [0, 0, 8, 5, 8], (g, o) => {
+    for (const [x, y] of [[0, 0], [7, 0], [0, 4], [7, 4]]) box(g, o, x, y, 0, 1, 1, 4, '#6d4a2c');
+    box(g, o, 0, 0, 4, 8, 5, 1, '#a86b3c'); box(g, o, 1, 1, 5, 3, 2, 1, '#3a8cf0'); box(g, o, 5, 2, 5, 1, 1, 2, '#ffffff');
+  }),
+};
+
+/* ---------- 6. 场景布局（纯数据） ---------- */
+const STN = {}, OBJ = [];
+function station(id, x, y, axis, s, o = {}) { return STN[id] = { id, x, y, axis, s, desk: o.desk || DESK_W, chair: o.chair || CH.blue, mon: MON, agent: null }; }
+const fp = (S, u0, u1) => S.axis === 'x'
+  ? { minX: S.x + u0, maxX: S.x + u1, minY: S.y - 6, maxY: S.y + 6 }
+  : { minX: S.x - 6, maxX: S.x + 6, minY: S.y + u0, maxY: S.y + u1 };
+function single(id, x, y, axis, s, o) {
+  const S = station(id, x, y, axis, s, o);
+  OBJ.push({ ...fp(S, s > 0 ? -3 : -10, s > 0 ? 10 : 3), h: 24, draw: c => drawStation(c, S) });
+}
+function pod(idA, idB, x, y, axis, oa, ob) {  // 双人对坐 = 工位 + 镜像工位 + 隔板
+  const A = station(idA, x, y, axis, 1, oa);
+  const B = station(idB, axis === 'x' ? x + 21 : x, axis === 'x' ? y : y + 21, axis, -1, ob);
+  const [dx, dy] = axis === 'x' ? [x + 10, y] : [x, y + 10];
+  OBJ.push({ ...fp(A, -3, 24), h: 24, draw: c => { drawStation(c, A); blit(c, dividerSpr(axis, '#86c46b'), dx, dy); drawStation(c, B); } });
+}
+function prop(get, x, y, w, d, h, extra) { OBJ.push({ minX: x, maxX: x + w, minY: y, maxY: y + d, h, draw: c => { blit(c, get(), x, y); extra && extra(c); } }); }
+function propC(get, x, y, h, z = 0) { OBJ.push({ minX: x - 2, maxX: x + 2, minY: y - 2, maxY: y + 2, h, draw: c => blit(c, get(), x, y, z) }); }
+
+// 布局随机：种子决定配色、靠墙物品、休息区、前排、角落和墙面装饰；
+// 9 个工位的位置、门、调度台、机器人巡逻路线不变，保证看得懂、不挡路
+const THEMES = [
+  { floor: ['#cfe4c6', '#c4ddbb'], slab: '#a9c6a3', wall: { top: '#fffaf0', left: '#f3e9d4', right: '#e4d6bb' }, base: '#b98a5c', rug: ['#c79a5e', '#ead6a8'] },
+  { floor: ['#e8dcc6', '#dfd0b6'], slab: '#c9b596', wall: { top: '#fbfbf7', left: '#e6ecf1', right: '#d3dbe3' }, base: '#8a6a4e', rug: ['#5f7fa8', '#a9c1dc'] },
+  { floor: ['#d7e1ea', '#cbd7e3'], slab: '#a7b6c6', wall: { top: '#fff9f2', left: '#f6e7dc', right: '#e8d4c6' }, base: '#9a7a62', rug: ['#b86a6a', '#e9c1b5'] },
+  { floor: ['#ecdce2', '#e2cfd7'], slab: '#c7aeb8', wall: { top: '#f7fbf8', left: '#e3efe8', right: '#cfe0d6' }, base: '#8d6f7d', rug: ['#6f9a7c', '#bcd9c4'] },
+];
+const SOFT_COLORS = ['#3a9d9a', '#d9a63e', '#e0735c', '#3b4f86', '#8e6bd8', '#6f9a7c'];
+const BODY_COLORS = ['#d94a4a', '#3a8cf0', '#45b36a', '#7c93b8', '#8a93a8', '#343a8a', '#e08a3a'];
+// 靠墙物品池：w × d 为占地（世界单位）；wt 权重；once 一间最多一个；side 也能靠左墙放
+const FURN = {
+  shelf:    { w: 10, d: 5, wt: 3, put: (x, y) => prop(SP.shelf, x, y, 10, 5, 24) },
+  rack:     { w: 6, d: 7, wt: 3, put: (x, y) => prop(SP.rack, x, y, 6, 7, 28, c => leds(c, x)) },
+  lockers:  { w: 12, d: 5, wt: 2, once: 1, put: (x, y, col) => prop(() => SP.lockers(col), x, y, 12, 5, 20) },
+  vending:  { w: 7, d: 6, wt: 2, once: 1, put: (x, y, col) => prop(() => SP.vending(col), x, y, 7, 6, 24) },
+  sofa:     { w: 16, d: 6, wt: 2, once: 1, put: (x, y, col) => prop(() => SP.sofa(col), x, y, 16, 6, 9) },
+  arcade:   { w: 6, d: 8, wt: 1, once: 1, put: (x, y, col) => prop(() => SP.arcade(col), x, y, 6, 8, 22) },
+  easel:    { w: 12, d: 3, wt: 1, once: 1, put: (x, y) => prop(SP.easel, x, y, 12, 3, 18) },
+  printer:  { w: 6, d: 5, wt: 2, once: 1, side: 1, put: (x, y) => prop(SP.printer, x, y, 6, 5, 11) },
+  fridge:   { w: 5, d: 5, wt: 1, once: 1, side: 1, put: (x, y) => prop(SP.fridge, x, y, 5, 5, 15) },
+  boxes:    { w: 9, d: 6, wt: 1, once: 1, side: 1, put: (x, y) => prop(SP.boxes, x, y, 9, 6, 7) },
+  bins:     { w: 7, d: 3, wt: 1, once: 1, side: 1, put: (x, y) => prop(SP.bins, x, y, 7, 3, 5) },
+  purifier: { w: 4, d: 4, wt: 1, once: 1, side: 1, put: (x, y) => prop(SP.purifier, x, y, 4, 4, 12) },
+  beanbag:  { w: 5, d: 5, wt: 1, side: 1, put: (x, y, col) => prop(() => SP.beanbag(col), x, y, 5, 5, 6) },
+  cabinet:  { w: 5, d: 8, wt: 2, side: 1, put: (x, y) => prop(SP.cabinet, x, y, 5, 8, 14) },
+  cooler:   { w: 4, d: 4, wt: 2, once: 1, side: 1, put: (x, y) => propC(SP.cooler, x + 2, y + 2, 16) },
+  plant:    { w: 4, d: 4, wt: 2, side: 1, put: (x, y) => propC(SP.plant, x + 2, y + 2, 20) },
+  bigplant: { w: 4, d: 4, wt: 2, side: 1, put: (x, y) => propC(SP.bigplant, x + 2, y + 2, 28) },
+  lamp:     { w: 4, d: 4, wt: 1, side: 1, put: (x, y) => propC(SP.lamp, x + 2, y + 2, 19) },
+  coatrack: { w: 4, d: 4, wt: 1, once: 1, side: 1, put: (x, y, col) => propC(() => SP.coatrack(col), x + 2, y + 2, 19) },
+  cactus:   { w: 4, d: 4, wt: 1, side: 1, put: (x, y) => propC(SP.cactus, x + 2, y + 2, 10) },
+};
+const BACK_POOL = Object.keys(FURN).filter(k => k !== 'cabinet');
+const LEFT_POOL = Object.keys(FURN).filter(k => FURN[k].side && FURN[k].w <= 9);
+// 墙面装饰：F(a, b, z0, z1, 颜色) 画在墙面上，a 为沿墙的起点
+const WALL_KINDS = {
+  clock: { w: 6, draw: (F, a) => {
+    F(a, a + 6, 21, 27, '#3a3f52'); F(a + 1, a + 5, 22, 26, '#ffffff');
+    const t = ((simNow / 3000) | 0) % 4;
+    F(a + 3, a + 4, 24, 26, '#2b2737');
+    if (t === 0) F(a + 3, a + 5, 24, 25, '#e5534b');
+    else if (t === 1) F(a + 3, a + 4, 23, 24, '#e5534b');
+    else if (t === 2) F(a + 1, a + 3, 24, 25, '#e5534b');
+    else F(a + 3, a + 4, 25, 26, '#e5534b');
+  } },
+  painting: { w: 9, draw: (F, a, d) => { F(a, a + 9, 14, 25, '#8a6a4a'); F(a + 1, a + 8, 15, 24, d.bg); F(a + 2, a + 5, 16, 21, d.c1); F(a + 4, a + 7, 18, 23, d.c2); } },
+  corkboard: { w: 10, draw: (F, a, d) => { F(a, a + 10, 13, 24, '#9c6f48'); F(a + 1, a + 9, 14, 23, '#d9a86b'); for (const [x, z, c] of d.notes) F(a + x, a + x + 2, z, z + 3, c); } },
+  dashboard: { w: 12, draw: (F, a) => {
+    F(a, a + 12, 15, 26, '#262b38'); F(a + 1, a + 11, 16, 25, '#141a2e');
+    const t = (simNow / 700) | 0;
+    for (let i = 0; i < 5; i++) { const h = 2 + ((hash(i * 7 + t) * 6) | 0); F(a + 2 + i * 2, a + 3 + i * 2, 17, 17 + h, i % 2 ? '#5ab8ff' : '#62f08e'); }
+  } },
+};
+let THEME = THEMES[0], WINDOWS = [], RUG = null, WALL_DECOR = [];
+function weightedKey(r, keys) {
+  let total = 0;
+  for (const k of keys) total += FURN[k].wt;
+  let v = r() * total;
+  for (const k of keys) { v -= FURN[k].wt; if (v < 0) return k; }
+  return keys[keys.length - 1];
+}
+function fillAlong(r, from, to, pool, used, size, place) {   // 沿墙从一头挑物品排下去，间距随机
+  let cur = from + ((r() * 3) | 0);
+  for (let guard = 0; guard < 24; guard++) {
+    const fits = pool.filter(k => cur + size(k) <= to && !(FURN[k].once && used.has(k)));
+    if (!fits.length) break;
+    const k = weightedKey(r, fits);
+    used.add(k);
+    place(k, cur);
+    cur += size(k) + 1 + ((r() * 4) | 0);
+  }
+}
+function freeSpans(from, to, wins) {   // 墙面上去掉窗户之后的空段
+  let spans = [[from, to]];
+  for (const w of wins) spans = spans.flatMap(([a, b]) => [[a, Math.min(b, w.a - 1)], [Math.max(a, w.b + 1), b]]).filter(([a, b]) => b - a >= 6);
+  return spans;
+}
+// 房间布局模板：调度台 + 7 个组员工位（比原来少一张桌子，腾出摆家具的空间）。
+// 每个模板自带机器人巡逻路线、左墙可用段和空地；随机时先挑模板，再往空地里摆家具。
+// 工位写法：['s', x, y, 朝向轴, 1 面向镜头 / -1 背对镜头] 单人位，['p', x, y, 轴] 双人对坐；第一项是调度台。
+const ROOMS = [
+  { name: '经典', stations: [['s', 14, 24, 'x', 1], ['p', 30, 22, 'x'], ['p', 30, 44, 'x'], ['p', 66, 14, 'y'], ['s', 80, 50, 'x', -1]],
+    robot: [[57, 33], [57, 56], [20, 56], [20, 33]], left: [32, 52],
+    zones: [[60, 40, 69, 57], [75, 12, 87, 34]], corners: [[3, 3], [84, 3], [4, 68], [86, 40], [86, 58]] },
+  { name: '横排', stations: [['s', 14, 40, 'x', 1], ['p', 34, 16, 'x'], ['p', 34, 40, 'x'], ['p', 68, 20, 'y'], ['s', 80, 54, 'x', -1]],
+    robot: [[27, 28], [60, 28], [60, 52], [27, 52]], left: [33, 50],
+    zones: [[77, 8, 87, 44]], corners: [[3, 3], [84, 3], [4, 68], [66, 55]] },
+  { name: '纵排', stations: [['s', 14, 24, 'x', 1], ['p', 36, 14, 'y'], ['p', 56, 14, 'y'], ['p', 30, 50, 'x'], ['s', 78, 24, 'y', 1]],
+    robot: [[26, 41], [46, 41], [46, 14], [46, 41], [67, 41], [67, 20], [67, 41]], left: [32, 52],
+    zones: [[70, 38, 87, 57]], corners: [[3, 3], [84, 3], [4, 68], [86, 12]] },
+  { name: 'L 形', stations: [['s', 46, 16, 'x', 1], ['p', 14, 24, 'y'], ['p', 34, 40, 'x'], ['p', 66, 16, 'y'], ['s', 80, 50, 'x', -1]],
+    robot: [[25, 52], [25, 28], [57, 28], [25, 28]], left: null,
+    zones: [[60, 42, 69, 57], [75, 10, 87, 40]], corners: [[3, 3], [84, 3], [4, 68], [86, 58]] },
+  { name: '工作岛', stations: [['s', 14, 24, 'x', 1], ['p', 34, 26, 'x'], ['p', 34, 38, 'x'], ['p', 70, 16, 'y'], ['s', 76, 52, 'x', -1]],
+    robot: [[27, 16], [61, 16], [61, 48], [27, 48]], left: [32, 52],
+    zones: [[78, 8, 87, 44], [31, 52, 58, 57]], corners: [[3, 3], [84, 3], [4, 68], [86, 58]] },
+];
+// 空地里的一组摆设：w × d 占地；once 与靠墙物品共用「一间最多一个」
+const VIGNETTES = [
+  { w: 8, d: 12, put: (x, y, p) => { prop(SP.coffeetable, x, y, 8, 5, 7); const c = p(SOFT_COLORS); prop(() => SP.beanbag(c), x + 1, y + 7, 5, 5, 6); } },
+  { w: 16, d: 12, once: 'sofa', put: (x, y, p) => { const c = p(SOFT_COLORS); prop(() => SP.sofa(c), x, y, 16, 6, 9); prop(SP.coffeetable, x + 4, y + 7, 8, 5, 7); } },
+  { w: 12, d: 4, put: (x, y) => { propC(SP.bigplant, x + 2, y + 2, 28); propC(SP.plant, x + 6, y + 2, 20); propC(SP.lamp, x + 10, y + 2, 19); } },
+  { w: 14, d: 8, once: 'arcade', put: (x, y, p) => { const c = p(BODY_COLORS); prop(() => SP.arcade(c), x, y, 6, 8, 22); prop(SP.bins, x + 7, y, 7, 3, 5); } },
+  { w: 12, d: 3, once: 'easel', put: (x, y) => prop(SP.easel, x, y, 12, 3, 18) },
+  { w: 9, d: 6, once: 'boxes', put: (x, y) => prop(SP.boxes, x, y, 9, 6, 7) },
+  { w: 4, d: 4, put: (x, y) => propC(SP.bigplant, x + 2, y + 2, 28) },
+  { w: 5, d: 5, put: (x, y, p) => { const c = p(SOFT_COLORS); prop(() => SP.beanbag(c), x, y, 5, 5, 6); } },
+];
+let ROOM = ROOMS[0];
+function fillZone(r, p, [x0, y0, x1, y1], used) {   // 沿空地的长边摆 1–3 组，最后一组之后可能留白
+  const alongX = (x1 - x0) >= (y1 - y0), end = alongX ? x1 : y1;
+  let cur = alongX ? x0 : y0;
+  for (let n = 0; n < 3; n++) {
+    const fits = VIGNETTES.filter(v => !(v.once && used.has(v.once)) &&
+      (alongX ? cur + v.w <= end && v.d <= y1 - y0 : cur + v.d <= end && v.w <= x1 - x0));
+    if (!fits.length || r() < .2 * n) break;
+    const v = p(fits);
+    if (v.once) used.add(v.once);
+    const x = alongX ? cur : x0 + ((r() * (x1 - x0 - v.w + 1)) | 0);
+    const y = alongX ? y0 + ((r() * (y1 - y0 - v.d + 1)) | 0) : cur;
+    v.put(x, y, p);
+    cur += (alongX ? v.w : v.d) + 1 + ((r() * 3) | 0);
+  }
+}
+function buildStations(room, chair) {
+  const ids = ['s1', 's2', 's3', 's4', 's5', 's6', 's7'];
+  let n = 0;
+  room.stations.forEach((st, i) => {
+    if (i === 0) single('s_conductor', st[1], st[2], st[3], st[4], { desk: DESK_WOOD, chair: CH.red });
+    else if (st[0] === 's') single(ids[n++], st[1], st[2], st[3], st[4], { chair: chair() });
+    else { const a = ids[n++], b = ids[n++]; pod(a, b, st[1], st[2], st[3], { chair: chair() }, { chair: chair() }); }
+  });
+}
+function placeRobot(room) {
+  robot.path = room.robot.map(pt => pt.slice());
+  [robot.x, robot.y] = robot.path[0];
+  robot.i = 1 % robot.path.length; robot.wait = 600; robot.moving = false;
+}
+function buildLayout(seed) {
+  const r = rng(seed), p = a => a[(r() * a.length) | 0];
+  for (const k of Object.keys(STN)) delete STN[k];
+  OBJ.length = 0;
+  THEME = p(THEMES);
+  const chair = () => p([CH.blue, CH.gray, CH.green, CH.orange, CH.blue]);
+  const colOf = k => (k === 'sofa' || k === 'beanbag' || k === 'coatrack') ? p(SOFT_COLORS) : p(BODY_COLORS);
+  ROOM = p(ROOMS);
+  buildStations(ROOM, chair);
+  placeRobot(ROOM);
+  const used = new Set();
+  // 后墙一排（x 6–82，深度不超过 8，碰不到后排工位）
+  fillAlong(r, 6, 82, BACK_POOL, used, k => FURN[k].w, (k, x) => FURN[k].put(x, 0, colOf(k)));
+  // 左墙一段（看板下方到门之前；有的模板这里被工位占了）
+  if (ROOM.left) fillAlong(r, ROOM.left[0], ROOM.left[1], LEFT_POOL, used, k => FURN[k].d, (k, y) => FURN[k].put(1, y, colOf(k)));
+  // 模板留出的空地：沙发茶几、绿植、街机、白板、纸箱……随机摆 1–3 组
+  for (const z of ROOM.zones) fillZone(r, p, z, used);
+  // 前排：会议桌和茶水台左右互换，地毯跟着会议桌，茶水台上随机摆件
+  const topper = p([SP.plant, SP.cactus, null]);
+  if (r() < .5) {
+    prop(SP.table, 28, 62, 20, 6, 8); RUG = [25, 59, 52, 72];
+    prop(SP.counter, 64, 63, 20, 5, 9, topper ? c => blit(c, topper(), 81, 65, 9) : null);
+    propC(SP.stool, 32, 70, 5); propC(SP.stool, 38, 70, 5); propC(SP.stool, 44, 70, 5);
+  } else {
+    prop(SP.counter, 24, 63, 20, 5, 9, topper ? c => blit(c, topper(), 41, 65, 9) : null);
+    prop(SP.table, 58, 62, 20, 6, 8); RUG = [55, 59, 82, 72];
+    propC(SP.stool, 62, 70, 5); propC(SP.stool, 68, 70, 5); propC(SP.stool, 74, 70, 5);
+  }
+  // 角落：绿植、大盆栽、落地灯、仙人掌，偶尔空着
+  for (const [x, y] of ROOM.corners) {
+    const k = p(['plant', 'plant', 'bigplant', 'lamp', 'cactus', null]);
+    if (k) FURN[k].put(x - (FURN[k].w >> 1), y - (FURN[k].d >> 1));
+  }
+  WINDOWS = p([
+    [{ p: 'y', a: 14, b: 28 }, { p: 'y', a: 34, b: 48 }, { p: 'x', a: 38, b: 48 }],
+    [{ p: 'y', a: 8, b: 22 }, { p: 'y', a: 28, b: 42 }],
+    [{ p: 'y', a: 20, b: 40 }, { p: 'x', a: 36, b: 50 }],
+    [{ p: 'y', a: 48, b: 62 }, { p: 'x', a: 38, b: 48 }],
+  ]);
+  // 墙面装饰：后墙空段里挑 1–2 个，左墙没窗户时再挂 1 个
+  WALL_DECOR = [];
+  const kinds = Object.keys(WALL_KINDS).sort(() => r() - .5);
+  const decorData = () => ({ bg: p(['#fdf6e3', '#e8f1f8', '#f3e8f2']), c1: p(BODY_COLORS), c2: p(SOFT_COLORS),
+    notes: [[1, 19, p(NOTE)], [4, 15, p(NOTE)], [7, 18, p(NOTE)]] });
+  let spans = freeSpans(3, 86, WINDOWS.filter(w => w.p === 'y'));
+  for (let n = 0, want = 1 + ((r() * 2) | 0); n < want && kinds.length; n++) {
+    const kind = kinds.pop(), w = WALL_KINDS[kind].w, fit = spans.filter(([a, b]) => b - a >= w);
+    if (!fit.length) continue;
+    const [a, b] = p(fit), at = a + ((r() * (b - a - w + 1)) | 0);
+    WALL_DECOR.push({ wall: 'y', kind, a: at, ...decorData() });
+    spans = spans.flatMap(([sa, sb]) => (sa === a && sb === b) ? [[sa, at - 1], [at + w + 1, sb]] : [[sa, sb]]).filter(([sa, sb]) => sb - sa >= 6);
+  }
+  if (!WINDOWS.some(w => w.p === 'x') && kinds.length) WALL_DECOR.push({ wall: 'x', kind: kinds.pop(), a: 38, ...decorData() });
+  BG = buildBG();
+  buildBlockMap();
+}
+function relayout(seed) {   // 运行中换布局：保留谁坐哪个工位
+  const seats = Object.values(STN).filter(s => s.agent).map(s => [s.id, s.agent]);
+  buildLayout(seed);
+  for (const [id, agent] of seats) if (STN[id]) STN[id].agent = agent;
+}
+
+/* ---------- 6b. 走路：2 单位一格的占地图 + 8 向 BFS，家具外扩 1 单位不贴边走 ---------- */
+const GRID = 2, GW = RW / GRID, GH = RD / GRID, DOOR = [2, 59];
+let BLOCK = new Uint8Array(GW * GH);
+function buildBlockMap() {
+  BLOCK = new Uint8Array(GW * GH);
+  for (const o of OBJ) {
+    for (let gy = Math.max(0, Math.floor((o.minY - 1) / GRID)); gy <= Math.min(GH - 1, Math.floor((o.maxY + 1 - .01) / GRID)); gy++)
+      for (let gx = Math.max(0, Math.floor((o.minX - 1) / GRID)); gx <= Math.min(GW - 1, Math.floor((o.maxX + 1 - .01) / GRID)); gx++) BLOCK[gy * GW + gx] = 1;
+  }
+}
+const cellOf = ([x, y]) => [Math.max(0, Math.min(GW - 1, Math.floor(x / GRID))), Math.max(0, Math.min(GH - 1, Math.floor(y / GRID)))];
+const cellPoint = i => [(i % GW) * GRID + GRID / 2, ((i / GW) | 0) * GRID + GRID / 2];
+function nearestFree(x, y) {   // 目标落在家具里时，取最近的空格
+  const [cx, cy] = cellOf([x, y]);
+  for (let r = 0; r < 10; r++) for (let dy = -r; dy <= r; dy++) for (let dx = -r; dx <= r; dx++) {
+    if (Math.max(Math.abs(dx), Math.abs(dy)) !== r) continue;
+    const gx = cx + dx, gy = cy + dy;
+    if (gx >= 0 && gy >= 0 && gx < GW && gy < GH && !BLOCK[gy * GW + gx]) return gy * GW + gx;
+  }
+  return cy * GW + cx;
+}
+function findPath(from, to) {
+  const s = nearestFree(...from), t = nearestFree(...to), prev = new Int32Array(GW * GH).fill(-1), queue = [s];
+  prev[s] = s;
+  for (let q = 0; q < queue.length && prev[t] < 0; q++) {
+    const i = queue[q], x = i % GW, y = (i / GW) | 0;
+    for (const [dx, dy] of [[1, 0], [-1, 0], [0, 1], [0, -1], [1, 1], [1, -1], [-1, 1], [-1, -1]]) {
+      const nx = x + dx, ny = y + dy, n = ny * GW + nx;
+      if (nx < 0 || ny < 0 || nx >= GW || ny >= GH || prev[n] >= 0 || BLOCK[n]) continue;
+      if (dx && dy && (BLOCK[y * GW + nx] || BLOCK[ny * GW + x])) continue;   // 不斜穿桌角
+      prev[n] = i; queue.push(n);
+    }
+  }
+  if (prev[t] < 0) return [from, to];
+  const cells = [];
+  for (let i = t; i !== s; i = prev[i]) cells.push(i);
+  cells.push(s); cells.reverse();
+  const pts = [from];   // 只留拐点
+  for (let k = 1; k < cells.length - 1; k++) {
+    const [ax, ay] = cellPoint(cells[k - 1]), [bx, by] = cellPoint(cells[k]), [cx, cy] = cellPoint(cells[k + 1]);
+    if (Math.sign(bx - ax) !== Math.sign(cx - bx) || Math.sign(by - ay) !== Math.sign(cy - by)) pts.push([bx, by]);
+  }
+  pts.push(cellPoint(t));
+  const [ex, ey] = cellOf(to);
+  if (!BLOCK[ey * GW + ex]) pts.push(to);   // 终点本身被家具占着时停在最近的空格
+  return pts;
+}
+// 工位局部坐标 u 轴：人朝 +u（s>0）或 -u，椅子在人身后；身后是过道，桌对面是来访者站的位置
+const seatSpot = (S, du) => { const u = S.s > 0 ? du : -du; return S.axis === 'x' ? [S.x + u, S.y] : [S.x, S.y + u]; };
+const seatBehind = S => seatSpot(S, -7), deskFront = S => seatSpot(S, 15);
+// stops: [{p:[x,y], wait, face, call}]，相邻两站之间各寻一次路
+function route(stops) {
+  const out = [{ p: stops[0].p }];
+  let last = stops[0].p;
+  for (const stop of stops.slice(1)) {
+    const legs = stop.direct ? [last, stop.p] : findPath(last, stop.p);
+    legs.slice(1).forEach((p, k) => out.push(k === legs.length - 2 ? { ...stop, p } : { p }));
+    last = legs[legs.length - 1];
+  }
+  return out;
+}
+
+/* ---------- 7. 角色与状态 ---------- */
+const ROLES = {
+  conductor: { name: '调度', stat: null, screen: 'doc' },
+  planner: { name: '规划', stat: 'plan', screen: 'doc' },
+  researcher: { name: '调研', stat: 'plan', screen: 'web' },
+  coder: { name: '编码', stat: 'code', screen: 'code' },
+  reviewer: { name: '审查', stat: 'review', screen: 'diff' },
+  tester: { name: '测试', stat: 'test', screen: 'test' },
+  designer: { name: '设计', stat: 'plan', screen: 'web' },
+  ops: { name: '运维', stat: 'test', screen: 'term' },
+};
+const STATS = { plan: '#ffd54a', code: '#66e08f', review: '#7cc4ff', test: '#ff9fbf' };
+const SCREEN = {
+  code: { bg: '#1c2536', ink: ['#7ee2a0', '#7cc4ff', '#ffb86b'] },
+  diff: { bg: '#1c2536', ink: ['#ff7b7b', '#7ee2a0'] },
+  test: { bg: '#143020', ink: ['#7ee2a0', '#c8f7d4'] },
+  web:  { bg: '#eef3ff', ink: ['#7a8db3', '#e46b9a', '#5a6c93'] },
+  doc:  { bg: '#fdfcf6', ink: ['#8a93a8', '#5b6aa6'] },
+  term: { bg: '#101521', ink: ['#9df29d'] },
+};
+const STATE_TXT = { idle:'待命', work:'工作中', think:'思考中', sleep:'zzz', done:'完成', error:'执行失败', stopped:'已停止', permission:'等待授权', question:'等待回答', retry:'正在重试', compact:'整理上下文' };
+
+let simNow = 0, paused = false, speed = 1, selected = null;
+let tokens = 0, shipped = 0;
+const AG = {}, envelopes = [], floats = [];
+const board = { todo: 0, doing: 0, done: 0 };
+let task = null;
+
+const $ = id => document.getElementById(id);
+const cv = $('cv'), ctx = cv.getContext('2d'), ov = $('ov');
+ctx.imageSmoothingEnabled = false;
+
+function mkEl(cls) { const e = document.createElement('div'); e.className = cls; e.hidden = true; ov.appendChild(e); return e; }
+
+const freeSeat = (prefer = '') => prefer && STN[prefer] && !STN[prefer].agent ? prefer
+  : Object.keys(STN).find(k => k !== 's_conductor' && !STN[k].agent);
+function addAgent(o) {
+  const seatId = o.seat && STN[o.seat] && !STN[o.seat].agent ? o.seat : freeSeat();
+  if (!seatId || AG[o.id]) return null;
+  const lk = o.look || randomLook();
+  const L = { hair: lk.hair, skin: lk.skin, shirt: lk.shirt, pants: lk.pants || '#3a3f52', acc: lk.acc || [], accColor: lk.accColor || '' };
+  L.key = [L.hair, L.skin, L.shirt, L.pants, L.acc.join('+'), L.accColor].join('|');
+  const a = { id: o.id, name: o.name || o.id, role: ROLES[o.role] ? o.role : 'coder', look: L, seat: seatId, recruit: !!o.recruit,
+    state: 'idle', stateAt: simNow, text: '', textUntil: 0, pingUntil: 0, hopUntil: 0, seed: (R() * 3000) | 0, hx: 0, hy: 0,
+    activityLabel: '', detail: '', icon: '', iconSvg: '', labelAt: simNow, walk: null, leaving: false, bubKey: '' };
+  STN[seatId].agent = a.id; AG[a.id] = a;
+  a.bub = mkEl('bub');
+  a.toolNode = document.createElement('img'); a.toolNode.className = 'office-tool'; a.toolNode.alt = ''; a.toolNode.hidden = true;
+  a.labelNode = document.createElement('span'); a.labelNode.className = 'bub-label';
+  a.detailNode = document.createElement('span'); a.detailNode.className = 'bub-detail';
+  a.bub.append(a.toolNode, a.labelNode, a.detailNode);
+  rosterAdd(a); updateHire();
+  return a;
+}
+// 随机外观池：前半段是原有的，后 10 个是扩充的
+const HAIR_COLORS = ['#231d1c', '#5b3b2b', '#b8683a', '#dcb24c', '#2c2a38', '#8b5a39', '#c94f7c', '#4a6fa5',
+  '#b9bcc6', '#f1dca0', '#8e2b3b', '#e0673a', '#5fc8a8', '#9b7fd6', '#5aa9e6', '#f29bb8', '#2f3f7a', '#2c8c8c'];
+const SKIN_TONES = ['#f7d5b5', '#eec7a3', '#d9a77f', '#b9825a', '#f9dcc0',
+  '#fbe5d6', '#f3cfb3', '#e8b894', '#e0ac7e', '#c68c62', '#a8714a', '#94603e', '#7d4f33', '#6b4430', '#5a3825'];
+const SHIRT_COLORS = ['#3aa56b', '#e0574c', '#4a8fdc', '#f2a444', '#7a62d8', '#2fb5b0', '#e36aa6',
+  '#f4d35e', '#2e3a59', '#8a9aa9', '#f2f2ec', '#3a3b45', '#a3d977', '#8e3b5f', '#c9975b', '#86c5f0', '#ff8f7a'];
+const ACC_COLORS = ['#e8544a', '#3a8cf0', '#45b36a',
+  '#f2c14e', '#8e6bd8', '#2fb5b0', '#f08a3c', '#e36aa6', '#3a3f52', '#f4f4f0', '#7a4a2a', '#9fd4ff', '#b8e986'];
+// 四个槽位各抽一个，互不打架；空字符串的权重就是「不戴」的概率
+const HAIR_STYLES = ['', '', 'long', 'ponytail', 'twintails', 'bun', 'spiky', 'bald', 'bangs', 'bob', 'afro', 'mohawk', 'braid'];
+const HEADWEAR = ['', '', '', 'cap', 'beanie', 'headband', 'bow', 'headset'];
+const FACEWEAR = ['', '', '', 'glasses', 'shades', 'mask', 'beard', 'mustache'];
+const CHESTWEAR = ['', '', 'tie', 'bowtie', 'badge', 'scarf'];
+const TALL_HAIR = new Set(['bun', 'spiky', 'afro', 'mohawk']);   // 帽子会把它们压扁
+function randomLook() {
+  const style = pick(HAIR_STYLES);
+  let head = pick(HEADWEAR);
+  if (TALL_HAIR.has(style) && (head === 'cap' || head === 'beanie')) head = '';
+  return {
+    hair: pick(HAIR_COLORS), skin: pick(SKIN_TONES), shirt: pick(SHIRT_COLORS),
+    acc: [style, head, pick(FACEWEAR), pick(CHESTWEAR)].filter(Boolean),
+    accColor: pick(ACC_COLORS),
+  };
+}
+function setState(id, state, text, ms) {
+  const a = AG[id]; if (!a) return;
+  if (a.state !== state) { a.state = state; a.stateAt = simNow; rosterUpd(a); }
+  if (text) say(id, text, ms);
+}
+function say(id, text, ms = 2600) { const a = AG[id]; if (!a) return; a.text = text; a.textUntil = simNow + ms; }
+function send(from, to, label = '') {
+  if (!AG[from] || !AG[to]) return;
+  const el = label ? mkEl('tag') : null; if (el) el.textContent = label;
+  AG[from].hopUntil = simNow + 450;
+  envelopes.push({ a: AG[from], b: AG[to], t0: simNow, dur: 1150, el });
+}
+function floatNum(a, n, col) { floats.push({ x: a.hx + 6, y: a.hy + 2, t0: simNow, s: '+' + n, col }); }
+
+/* ---------- 8. 绘制 ---------- */
+function drawStation(c, S) {
+  blit(c, stationSprite(S, 'back'), S.x, S.y);
+  if (S.s < 0) drawScreen(c, S);
+  drawAgent(c, S);
+  blit(c, stationSprite(S, 'front'), S.x, S.y);
+  const actor = S.agent && AG[S.agent];
+  if (actor && actor.contextKnown) {
+    const o = {ox:VIEW.ox+2*(S.x-S.y), oy:VIEW.oy+S.x+S.y};
+    const layers = Math.ceil(Math.max(0,Math.min(1,actor.contextRatio))*8);
+    for(let i=0;i<layers;i++) sBox(c,o,S.axis,S.s>0?4:-6,2,8+i,3,3,1,i===layers-1&&actor.contextRatio>=.85?'#e8786b':i%2?'#d7ddec':'#fff8e6');
+  }
+}
+// 工具类型 → 屏幕内容与动作：读类工具看屏幕（偶尔点头），写类工具敲键盘
+const SCREEN_BY_ICON = { TerminalReadWrite: 'term', Edit: 'code', Save: 'code', OpenFile: 'doc', Search: 'diff', BrowserGlobe: 'web', Eye: 'web', List: 'doc' };
+const READ_ICONS = new Set(['OpenFile', 'Search', 'BrowserGlobe', 'Eye', 'List', 'Embedding']);
+const typing = a => a.state === 'type' || (a.state === 'work' && !READ_ICONS.has(a.icon));
+function drawScreen(c, S) {           // 只有背对镜头的人，屏幕才朝向我们 → 动态画内容
+  const a = S.agent && AG[S.agent];
+  const o = { ox: VIEW.ox + 2 * (S.x - S.y), oy: VIEW.oy + S.x + S.y }, ax = S.axis, u = -7;
+  if (!a || a.walk) { sFaceU(c, o, ax, u, -4, 0, 11, 15, '#232a3d'); return; }
+  const sc = SCREEN[a.state === 'type' ? 'doc' : SCREEN_BY_ICON[a.icon] || ROLES[a.role].screen];
+  if (a.state !== 'work' && a.state !== 'type') {
+    sFaceU(c, o, ax, u, -4, 0, 11, 15, '#3f7ae0');
+    sLineV(c, o, ax, u, ax === 'x' ? -1 : -4, ax === 'x' ? 0 : -3, 14, '#9cc2ff');
+    return;
+  }
+  sFaceU(c, o, ax, u, -4, 0, 11, 15, sc.bg);
+  const tick = (simNow / 190) | 0;
+  [14, 12].forEach((z, i) => {
+    const len = 1 + ((hash(tick * 7 + i * 13 + S.x * 3) * 3.99) | 0);
+    const [v0, v1] = ax === 'x' ? [-len, 0] : [-4, -4 + len];
+    sLineV(c, o, ax, u, v0, v1, z, sc.ink[(tick + i) % sc.ink.length]);
+  });
+}
+function drawAgent(c, S) {
+  const a = S.agent && AG[S.agent]; if (!a || a.walk) return;
+  const pose = S.s > 0 ? 'front' : 'back', flip = S.axis === 'y';
+  let frame = 'idle', hop = 0;
+  if (typing(a)) frame = ((simNow / (a.state === 'type' ? 120 : 170)) | 0) % 2 ? 'typeA' : 'typeB';
+  else if (pose === 'front' && (simNow + a.seed) % 3300 < 140) frame = 'blink';
+  if (a.state === 'work' && !typing(a) && (simNow + a.seed) % 1400 < 220) hop = 1;   // 读东西时偶尔点头
+  if ((a.state === 'done' || simNow < a.hopUntil) && ((simNow / 140) | 0) % 4 < 2) hop = 2;
+  const spr = charSprite(a.look, pose, frame, flip);
+  const [sx, sy] = P(VIEW, S.x, S.y, 4);
+  c.drawImage(spr.cv, sx - spr.ax, sy - spr.ay - hop); blits++;
+  a.hx = sx; a.hy = sy - spr.ay - hop;
+}
+function drawWalker(c, a) {
+  const w = a.walk, d = w.dir;
+  const pose = d === '+x' || d === '+y' ? 'front' : 'back', flip = d === '+y' || d === '-y';
+  const step = ((simNow / 150) | 0) % 2;
+  const spr = charSprite(a.look, pose, w.moving ? (step ? 'walkA' : 'walkB') : 'stand', flip);
+  const [sx, sy] = P(VIEW, w.x, w.y, 0), bob = w.moving && step ? 1 : 0;
+  c.drawImage(spr.cv, Math.round(sx - spr.ax), Math.round(sy - spr.ay - bob)); blits++;
+  a.hx = Math.round(sx); a.hy = Math.round(sy - spr.ay - bob);
+}
+function leds(c, rx) {
+  const t = (simNow / 260) | 0;
+  for (let r = 0; r < 6; r++) for (let k = 0; k < 2; k++) {
+    if (hash(rx * 97 + r * 13 + k * 7 + t * 31) < .35) continue;
+    const [sx, sy] = P(VIEW, rx + 1 + k * 2, 7, 25 - r * 4);
+    c.fillStyle = hash(r * 5 + k + rx) > .82 ? '#ffc857' : (k ? '#5ab8ff' : '#62f08e');
+    c.fillRect(sx, sy, 2, 1);
+  }
+}
+
+// 背景（地板/墙/门）按当前主题画一次；草地不画，留给宠物窗口透明
+let BG = null;
+function buildBG() {
+  const cv = mk(VIEW.w, VIEW.h), g = cv.getContext('2d'), o = VIEW, t = THEME;
+  box(g, o, -3, -3, -4, RW + 3, RD + 3, 4, { top: t.slab, left: '#a3adba', right: '#8791a1' });
+  for (let tx = 0; tx < RW / T; tx++) for (let ty = 0; ty < RD / T; ty++)
+    faceZ(g, o, 0, tx * T + 1, ty * T + 1, tx * T + T, ty * T + T, (tx + ty) % 2 ? t.floor[0] : t.floor[1]);
+  if (RUG) { const [x0, y0, x1, y1] = RUG; faceZ(g, o, 0, x0, y0, x1, y1, t.rug[0]); faceZ(g, o, 0, x0 + 1, y0 + 1, x1 - 1, y1 - 1, t.rug[1]); }
+  box(g, o, -3, -3, 0, 3, RD + 3, WALL_H, t.wall);
+  box(g, o, 0, -3, 0, RW, 3, WALL_H, t.wall);
+  const bb = t.base;
+  box(g, o, 0, 0, 0, 1, 54, 3, bb); box(g, o, 0, 64, 0, 1, RD - 64, 3, bb); box(g, o, 0, 0, 0, RW, 1, 3, bb);
+  faceX(g, o, 0, 54, 64, 0, 25, '#7c4f2c'); faceX(g, o, 0, 55, 63, 0, 24, '#b07342');
+  faceX(g, o, 0, 56, 62, 14, 22, '#c4884f'); faceX(g, o, 0, 56, 62, 3, 12, '#c4884f');
+  const [kx, ky] = P(o, 0, 57, 12); g.fillStyle = '#ffd24a'; g.fillRect(kx - 1, ky, 2, 1);
+  return cv;
+}
+
+function hourNow() { const m = (simNow / 1000) * 5; return { day: 1 + Math.floor(m / 540), min: 540 + (m % 540) }; }
+function skyColor() { const h = hourNow().min / 60; return h < 14 ? '#8fd0ff' : h < 16 ? '#a6c9f2' : h < 17 ? '#ffcf8f' : '#f5a06b'; }
+const NOTE = ['#ffe36e', '#ff9fb6', '#9fd8ff', '#b8f09a'];
+function drawWalls(c) {
+  const o = VIEW, sky = skyColor();
+  for (const w of WINDOWS) {
+    const F = w.p === 'y' ? (a, b, z0, z1, col) => faceY(c, o, 0, a, b, z0, z1, col) : (a, b, z0, z1, col) => faceX(c, o, 0, a, b, z0, z1, col);
+    F(w.a - 1, w.b + 1, 11, 12, '#d9dde6');
+    F(w.a - 1, w.b + 1, 12, 31, '#fbfcff');
+    F(w.a, w.b, 13, 30, sky); F(w.a, w.b, 13, 19, lite(sky, .18));
+    F(w.a + 2, w.a + 3, 20, 28, lite(sky, .5)); F(w.a + 4, w.a + 5, 23, 29, lite(sky, .5));
+    const mid = (w.a + w.b) >> 1; F(mid, mid + 1, 13, 30, '#fbfcff');
+  }
+  // 看板墙：待办 / 进行 / 完成 —— 便签数量跟着任务走
+  faceX(c, o, 0, 7, 31, 11, 31, '#8a6a4a'); faceX(c, o, 0, 8, 30, 12, 30, '#fdfdf8');
+  const cols = [[23, 30, '#ef6b6b', board.todo], [16, 23, '#f2c14e', board.doing], [8, 16, '#58c07a', board.done]];
+  cols.forEach(([y0, y1, hc, n], ci) => {
+    faceX(c, o, 0, y0, y1, 27, 30, hc);
+    for (let k = 0; k < Math.min(6, n); k++) {
+      const r = k >> 1, ny = y0 + 1 + (k & 1) * 3, z1 = 26 - r * 5;
+      faceX(c, o, 0, ny, ny + 2, z1 - 3, z1, NOTE[(ci + k) % NOTE.length]);
+    }
+  });
+  c.fillStyle = '#c9c2b0';
+  for (const y of [16, 23]) { const [sx, sy] = P(o, 0, y, 27); c.fillRect(sx - 1, sy, 1, 15); }
+  for (const d of WALL_DECOR) {
+    const F = d.wall === 'y' ? (a, b, z0, z1, col) => faceY(c, o, 0, a, b, z0, z1, col) : (a, b, z0, z1, col) => faceX(c, o, 0, a, b, z0, z1, col);
+    WALL_KINDS[d.kind].draw(F, d.a, d);
+  }
+}
+
+// 机器人：场景里唯一会走动的角色（也是 box() 拼的）
+const BOT_LINES = ['休息一下', 'Beep!', '巡逻中'];
+const robot = { x: 20, y: 33, path: [[57, 33], [57, 56], [20, 56], [20, 33]], i: 0, wait: 900, dir: '+x', moving: false, text: '', textUntil: 0, hx: 0, hy: 0, bub: mkEl('bub bot') };
+const robotObj = { h: 14, minX: 0, maxX: 0, minY: 0, maxY: 0, draw: c => {
+  const bob = robot.moving && ((simNow / 150) | 0) % 2 ? 1 : 0;
+  blit(c, SP.robot(robot.dir), robot.x, robot.y, bob);
+  const [sx, sy] = P(VIEW, robot.x, robot.y, 14 + bob); robot.hx = sx; robot.hy = sy;
+} };
+function updRobot(dt) {
+  if (robot.wait > 0) { robot.wait -= dt; robot.moving = false; return; }
+  const [tx, ty] = robot.path[robot.i], dx = tx - robot.x, dy = ty - robot.y, dist = Math.hypot(dx, dy), sp = dt * 0.011;
+  robot.moving = true;
+  if (dist <= sp) {
+    robot.x = tx; robot.y = ty; robot.i = (robot.i + 1) % robot.path.length; robot.wait = 900 + R() * 1800;
+    // 有人在忙时机器人不闲聊，免得和真实状态气泡抢位置
+    if (R() < .4 && !Object.values(AG).some(a => a.state in BUBBLE_CLASS)) { robot.text = pick(BOT_LINES); robot.textUntil = simNow + 2200; }
+  } else {
+    robot.x += dx / dist * sp; robot.y += dy / dist * sp;
+    robot.dir = Math.abs(dx) > Math.abs(dy) ? (dx > 0 ? '+x' : '-x') : (dy > 0 ? '+y' : '-y');
+  }
+}
+
+// 走动的组员：进门领任务、回工位、交结果、出门；占用与机器人同样的深度排序
+const WALK_SPEED = 0.032;   // 世界单位 / 毫秒，穿过房间约 2–3 秒
+const walkers = new Set();
+function startWalk(a, path, done) {
+  const [x, y] = path[0].p;
+  a.walk = { path, i: 1, x, y, dir: a.walk ? a.walk.dir : '+x', moving: false, pause: 0, done,
+    obj: { h: 20, minX: 0, maxX: 0, minY: 0, maxY: 0, draw: c => a.walk && drawWalker(c, a) } };
+  walkers.add(a);
+}
+const faceDir = (fx, fy, tx, ty) => Math.abs(tx - fx) > Math.abs(ty - fy) ? (tx > fx ? '+x' : '-x') : (ty > fy ? '+y' : '-y');
+function updWalkers(dt) {
+  for (const a of [...walkers]) {
+    const w = a.walk;
+    if (!w) { walkers.delete(a); continue; }
+    if (w.pause > 0) { w.pause -= dt; w.moving = false; continue; }
+    if (w.i >= w.path.length) { walkers.delete(a); a.walk = null; w.done && w.done(); continue; }
+    const stop = w.path[w.i], [tx, ty] = stop.p, dx = tx - w.x, dy = ty - w.y, dist = Math.hypot(dx, dy), sp = dt * WALK_SPEED;
+    w.moving = true;
+    if (dist > .01) w.dir = faceDir(w.x, w.y, tx, ty);
+    if (dist <= sp) {
+      w.x = tx; w.y = ty; w.i++;
+      if (stop.face) w.dir = faceDir(w.x, w.y, ...stop.face);
+      if (stop.wait) { w.pause = stop.wait; w.moving = false; }
+      if (stop.call) stop.call();
+    } else { w.x += dx / dist * sp; w.y += dy / dist * sp; }
+  }
+}
+function walkerObjs() {
+  const out = [];
+  for (const a of walkers) {
+    const w = a.walk; if (!w) continue;
+    Object.assign(w.obj, { minX: w.x - 2, maxX: w.x + 2, minY: w.y - 2, maxY: w.y + 2 });
+    out.push(w.obj);
+  }
+  return out;
+}
+
+// 深度排序：按等距足迹做拓扑排序（只比较屏幕上重叠的对象）
+const sbb = o => [2 * (o.minX - o.maxY), 2 * (o.maxX - o.minY), o.minX + o.minY - o.h, o.maxX + o.maxY];
+function behind(a, b) {
+  const ab = a.maxX <= b.minX || a.maxY <= b.minY, ba = b.maxX <= a.minX || b.maxY <= a.minY;
+  if (ab !== ba) return ab;
+  return a.minX + a.maxX + a.minY + a.maxY < b.minX + b.maxX + b.minY + b.maxY;
+}
+function depthSort(list) {
+  const n = list.length, deps = list.map(() => []), bb = list.map(sbb);
+  for (let i = 0; i < n; i++) for (let j = i + 1; j < n; j++) {
+    const A = bb[i], B = bb[j];
+    if (!(A[0] < B[1] && B[0] < A[1] && A[2] < B[3] && B[2] < A[3])) continue;
+    if (behind(list[i], list[j])) deps[j].push(i); else deps[i].push(j);
+  }
+  const out = [], mark = new Uint8Array(n);
+  const visit = i => { if (mark[i]) return; mark[i] = 1; deps[i].forEach(visit); out.push(list[i]); };
+  list.map((_, i) => i).sort((i, j) => (list[i].maxX + list[i].maxY) - (list[j].maxX + list[j].maxY)).forEach(visit);
+  return out;
+}
+
+function drawOverlays(c) {
+  // 信封（agent 之间的消息）：带两格残影的抛物线，落地时收件人头顶冒「!」
+  const env = envSpr(), arc = t => Math.sin(Math.PI * t) * 26;
+  for (let i = envelopes.length - 1; i >= 0; i--) {
+    const e = envelopes[i], t = Math.min(1, (simNow - e.t0) / e.dur);
+    const at = u => [e.a.hx + (e.b.hx - e.a.hx) * u, e.a.hy + 4 + (e.b.hy - e.a.hy) * u - arc(u)];
+    c.globalAlpha = .35;
+    for (const lag of [.16, .08]) if (t > lag) { const [gx, gy] = at(t - lag); c.drawImage(env.cv, Math.round(gx - 7), Math.round(gy - 5)); }
+    c.globalAlpha = 1;
+    const [x, y] = at(t);
+    c.drawImage(env.cv, Math.round(x - 7), Math.round(y - 5)); blits++;
+    e.x = x; e.y = y - 5;
+    if (t >= 1) { e.b.pingUntil = simNow + 900; if (e.el) e.el.remove(); envelopes.splice(i, 1); }
+  }
+  // 头顶状态图标
+  const bobT = ((simNow / 260) | 0) % 2;
+  for (const a of Object.values(AG)) {
+    if (!a.hx) continue;
+    let n = null, col = '#ffe14d';
+    if (simNow < a.pingUntil) n = 'ex';
+    else if (a.state === 'question') n = 'q';
+    else if (a.state === 'error') { n = 'ex'; col = '#ff5a4f'; }
+    else if (a.state === 'done') n = 'star';
+    else if (a.state === 'sleep') { n = 'z'; col = '#cfe9ff'; }
+    else if (a.state === 'permission') n = 'ex';
+    else if (a.state === 'wait') { n = 'glass'; col = '#9fd4ff'; }
+    if (n) { const s = miniSpr(n, col); c.drawImage(s.cv, a.hx + 5, a.hy - 3 - bobT); if (a.state === 'sleep') { c.drawImage(s.cv,a.hx+10,a.hy-6-bobT);c.drawImage(s.cv,a.hx+15,a.hy-9-bobT); } blits++; }
+    else if (a.state === 'think' || a.state === 'compact' || a.state === 'retry') {   // 思考：三个点轮流跳
+      const lit = ((simNow / 280) | 0) % 3;
+      for (let k = 0; k < 3; k++) { const s = miniSpr('dot', k === lit ? '#ffffff' : '#b9c3dc'); c.drawImage(s.cv, a.hx + 5 + k * 4, a.hy - 2 - (k === lit ? 1 : 0)); }
+      blits++;
+    }
+    if (a.id === selected) { const s = miniSpr('arrow', '#ffe14d'); c.drawImage(s.cv, a.hx - 3, a.hy - 10 - bobT * 2); blits++; }
+  }
+  // 飘字 +N
+  for (let i = floats.length - 1; i >= 0; i--) {
+    const f = floats[i], t = (simNow - f.t0) / 900;
+    if (t >= 1) { floats.splice(i, 1); continue; }
+    [...f.s].forEach((ch, k) => { const s = digitSpr(ch, f.col); c.drawImage(s.cv, Math.round(f.x + k * 4), Math.round(f.y - t * 12)); blits++; });
+  }
+}
+// 状态气泡：忙碌期间常驻。一行「图标 动作 · 细节」，细节是正在写的最后几个字或调用的路径/命令。
+// 先放优先级高的（求助 > 主 agent > 正在输出 > 刚变化），撞上就往上叠，叠不下改成只显示动作。
+const BUBBLE_CLASS = { think: 'think', compact: 'think', retry: 'think', type: 'type', work: '', wait: 'wait',
+  permission: 'alert', question: 'alert', error: 'bad', stopped: 'bad', done: 'flash' };
+const ICON_STATES = new Set(['work', 'wait', 'permission', 'type']);
+function bubbleContent(a) {
+  if (a.text && simNow < a.textUntil) return { cls: 'flash', label: a.text, detail: '', icon: '', prio: 5 };
+  if (!(a.state in BUBBLE_CLASS)) return null;   // 待命、zzz 不说话
+  const alert = a.state === 'permission' || a.state === 'question' || a.state === 'error' || a.state === 'stopped';
+  return { cls: BUBBLE_CLASS[a.state], label: a.activityLabel || STATE_TXT[a.state] || '', detail: a.detail || '',
+    icon: ICON_STATES.has(a.state) ? a.iconSvg : '',
+    prio: alert ? 4 : a.role === 'conductor' ? 3 : a.state === 'type' ? 2 : simNow - a.labelAt < 4000 ? 1 : 0 };
+}
+// 气泡放不下时从开头裁：正在写的回复要看最新的字，路径要看文件名
+function fitDetailTail(node, text) {
+  if (!text || node.scrollWidth <= node.clientWidth + 1) return;
+  const chars = [...text.replace(/^…/, '')];
+  let lo = 1, hi = chars.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    node.textContent = '…' + chars.slice(mid).join('');
+    if (node.scrollWidth > node.clientWidth + 1) lo = mid + 1; else hi = mid;
+  }
+  node.textContent = '…' + chars.slice(lo).join('');
+}
+function renderBubble(a, c) {
+  const key = [c.cls, c.label, c.detail, c.icon, a.id === selected, innerWidth].join('\u0001');
+  if (key === a.bubKey) return;
+  a.bubKey = key;
+  a.bub.className = 'bub' + (c.cls ? ' ' + c.cls : '') + (a.id === selected ? ' picked' : '');
+  a.labelNode.textContent = c.label;
+  a.detailNode.textContent = c.detail; a.detailNode.hidden = !c.detail;
+  if (c.icon) {
+    if (a.iconFor !== c.icon) { a.iconFor = c.icon; a.toolNode.src = safeIcon(c.icon); }
+    a.toolNode.alt = a.tool || ''; a.toolNode.hidden = false;
+  } else a.toolNode.hidden = true;
+  a.bub.hidden = false; a.bub.style.left = '0px';   // 在左边缘量，免得被窗口右侧挤窄
+  fitDetailTail(a.detailNode, c.detail);
+  a.bubFullW = a.bub.offsetWidth; a.bubH = a.bub.offsetHeight;
+  a.bub.classList.add('compact'); a.bubCompactW = a.bub.offsetWidth; a.bub.classList.remove('compact');
+}
+function layoutBubbles(k) {
+  const W = innerWidth, minTop = k * 30, items = [];
+  for (const a of Object.values(AG)) {
+    const c = a.hx ? bubbleContent(a) : null;
+    if (!c) { if (!a.bub.hidden) { a.bub.hidden = true; a.bubKey = ''; } continue; }
+    renderBubble(a, c); items.push([c.prio, a]);
+  }
+  items.sort((x, y) => y[0] - x[0] || y[1].labelAt - x[1].labelAt);
+  const placed = [];
+  const hits = r => placed.some(p => r.left < p.right + 2 && p.left < r.right + 2 && r.top < p.bottom + 2 && p.top < r.bottom + 2);
+  // 候选位置：头顶居中 → 往左/右错开（尾巴仍指着头）→ 抬高一层/两层（用引线连回头顶）
+  const rectAt = (a, compact, lift, side) => {
+    const w = compact ? a.bubCompactW : a.bubFullW, h = a.bubH, cx = a.hx * k, tip = (a.hy - 1) * k - 7;
+    const want = side < 0 ? cx - w + 14 : side > 0 ? cx - 14 : cx - w / 2;
+    const left = Math.max(2, Math.min(W - w - 2, want)), top = Math.max(minTop, tip - h - lift * (h + 3));
+    return { left, top, right: left + w, bottom: top + h, compact, cx, lead: Math.max(0, tip - h - top) };
+  };
+  for (const [, a] of items) {
+    let best = null;
+    for (const compact of [false, true]) for (let lift = 0; lift < 3 && !best; lift++)
+      for (const side of [0, -1, 1]) { const r = rectAt(a, compact, lift, side); if (!hits(r)) { best = r; break; } }
+    best = best || rectAt(a, true, 0, 0);
+    placed.push(best);
+    a.bub.classList.toggle('compact', best.compact);
+    a.bub.style.left = best.left + 'px'; a.bub.style.top = best.top + 'px';
+    a.bub.style.setProperty('--tail', Math.max(8, Math.min(best.right - best.left - 8, best.cx - best.left)) + 'px');
+    a.bub.style.setProperty('--lead', best.lead + 'px');
+  }
+  // 原生窗口的形状区域也裁剪绘制：气泡（含尾巴和引线）范围变化时节流上报
+  const r3 = v => Math.round(v * 1000) / 1000, H = innerHeight;
+  const rects = placed.map(p => [r3(p.left / W), r3(p.top / H), r3(p.right / W), r3(Math.min(H, p.bottom + 8 + p.lead) / H)]);
+  if (!robot.bub.hidden) { const b = robot.bub.getBoundingClientRect(); rects.push([r3(b.left / W), r3(b.top / H), r3(b.right / W), r3((b.bottom + 8) / H)]); }
+  const key = JSON.stringify(rects);
+  if (key !== bubbleRegionKey && (simNow - bubbleRegionAt > 150 || rects.length !== bubbleRegions.length)) {
+    bubbleRegionKey = key; bubbleRegionAt = simNow; bubbleRegions = rects; reportOfficeRegions();
+  }
+}
+let bubbleRegions = [], bubbleRegionKey = '', bubbleRegionAt = -1e9;
+function placeDom() {
+  const k = cv.clientWidth / VIEW.w; if (!k) return;
+  const put = (el, x, y) => { el.style.left = (x * k) + 'px'; el.style.top = (y * k) + 'px'; };
+  layoutBubbles(k);
+  if (robot.text && simNow < robot.textUntil) { robot.bub.textContent = robot.text; robot.bub.hidden = false; put(robot.bub, robot.hx, robot.hy - 1); }
+  else robot.bub.hidden = true;
+  for (const e of envelopes) if (e.el && e.x !== undefined) { e.el.hidden = false; put(e.el, e.x, e.y); }
+}
+function render() {
+  blits = 0;
+  ctx.clearRect(0, 0, VIEW.w, VIEW.h);
+  ctx.drawImage(BG, 0, 0);
+  drawWalls(ctx);
+  robotObj.minX = robot.x - 2; robotObj.maxX = robot.x + 2; robotObj.minY = robot.y - 2; robotObj.maxY = robot.y + 2;
+  for (const o of depthSort(OBJ.concat(robotObj, walkerObjs()))) o.draw(ctx);
+  drawOverlays(ctx);
+  placeDom();
+}
+
+/* ---------- 9. 时间 & 主循环 ---------- */
+const waiters = [];
+const wait = ms => new Promise(r => waiters.push({ t: simNow + ms, r }));
+const FRAME_MS = 33;   // 常驻桌面：像素动画本来就是 150ms 级步进，约 30fps 足够，省 CPU/GPU
+let last = performance.now(), sinceDraw = FRAME_MS;
+function advance(dt) {
+  simNow += dt;
+  for (let i = waiters.length - 1; i >= 0; i--) if (waiters[i].t <= simNow) { const w = waiters[i]; waiters.splice(i, 1); w.r(); }
+  updRobot(dt);
+  updWalkers(dt);
+}
+function loop(ts) {
+  const dt = Math.min(64, ts - last); last = ts;
+  if (!paused) advance(dt * speed);
+  if ((sinceDraw += dt) >= FRAME_MS) { sinceDraw = 0; render(); presentUpscale(); notifyReady(); }
+  requestAnimationFrame(loop);
+}
+
+/* ---------- 10. 桌面宠物交互（原页面的面板 / 按钮 / 花名册都去掉了） ---------- */
+const post = msg => { try { if (window.chrome && chrome.webview) chrome.webview.postMessage(msg); } catch (e) { /* 普通浏览器里打开时没有宿主 */ } };
+let readySent = false;
+function notifyReady() { if (!readySent) { readySent = true; post('ready'); } }   // 第一帧画完再让原生把窗口挪进屏幕
+function renderTask() {}
+function rosterAdd() {}
+function rosterUpd() {}
+function updateHire() {}
+function log() {}
+function select(id) {
+  selected = id;
+  if (id) { const a = AG[id]; say(id, `${a.name} · ${a.activityLabel || STATE_TXT[a.state]}`, 3200); }
+}
+// 左键按住拖动 = 挪窗口（交给原生的标题栏拖动循环）；单击小人 = 头顶报状态；右键 = 原生菜单
+let press = null, dragged = false;
+cv.addEventListener('pointerdown', e => { if (e.button === 0) { press = { x: e.screenX, y: e.screenY }; dragged = false; } });
+cv.addEventListener('pointermove', e => {
+  if (!press || !(e.buttons & 1)) return;
+  if (Math.abs(e.screenX - press.x) + Math.abs(e.screenY - press.y) >= 4) { press = null; dragged = true; post('drag'); }
+});
+cv.addEventListener('pointerup', () => { press = null; });
+document.addEventListener('contextmenu', e => { e.preventDefault(); post('menu'); });
+cv.addEventListener('click', e => {
+  if (dragged) { dragged = false; return; }
+  const r = cv.getBoundingClientRect(), k = VIEW.w / r.width;
+  const x = (e.clientX - r.left) * k, y = (e.clientY - r.top) * k;
+  let best = null, bd = 1e9;
+  for (const a of Object.values(AG)) {
+    const dx = x - a.hx, dy = y - (a.hy + 8), d = dx * dx + dy * dy;
+    if (Math.abs(dx) < 9 && Math.abs(dy) < 12 && d < bd) { bd = d; best = a; }
+  }
+  select(best ? best.id : null);
+});
+// 窗口尺寸由原生按整数倍缩放给出，画布铺满窗口；--k = 每个场景像素对应多少 CSS 像素，气泡字号跟着它走
+function fit() {
+  const k = window.innerWidth / VIEW.w;
+  if (k > 0) document.documentElement.style.setProperty('--k', String(k));
+  syncUpscale();
+  reportOfficeRegions();
+}
+window.addEventListener('resize', fit);
+
+// ---- 用户缩放：滚轮 / 左上角把手交给原生改窗口大小，页面只负责把任意倍数画整齐 ----
+// 非整数倍（比如 2.3 倍）直接最近邻放大会一行 2 像素一行 3 像素；先按整数倍（向上取整）
+// 放大到离屏画布，再让浏览器平滑缩到窗口大小，像素宽窄一致，只在边缘有 1 像素过渡。
+const up = $('up'), upCtx = up ? up.getContext('2d') : null;
+let upN = 0;
+function syncUpscale() {
+  if (!up) return;
+  const K = cv.clientWidth * (window.devicePixelRatio || 1) / VIEW.w;
+  const n = !(K > 0) || Math.abs(K - Math.round(K)) < 0.02 ? 0 : Math.max(1, Math.ceil(K));
+  if (n === upN) return;
+  upN = n;
+  up.hidden = !n;
+  cv.style.opacity = n ? '0' : '';
+  if (n) { up.width = VIEW.w * n; up.height = VIEW.h * n; }
+}
+function presentUpscale() {
+  if (!upN) return;
+  upCtx.imageSmoothingEnabled = false;
+  upCtx.clearRect(0, 0, up.width, up.height);
+  upCtx.drawImage(cv, 0, 0, up.width, up.height);
+}
+const hostAttached = () => !!(window.chrome && chrome.webview);
+let wheelAcc = 0;
+cv.parentElement.addEventListener('wheel', e => {
+  if(e.target.closest('.office-controls,.office-members'))return;
+  if (!hostAttached()) return;   // 普通浏览器里打开时不拦滚动
+  e.preventDefault();
+  wheelAcc += e.deltaY * (e.deltaMode === 1 ? 33 : 1);
+  const r = cv.getBoundingClientRect();
+  const fx = ((e.clientX - r.left) / r.width).toFixed(3), fy = ((e.clientY - r.top) / r.height).toFixed(3);
+  while (Math.abs(wheelAcc) >= 100) {   // 鼠标滚轮一格 = 100；触控板的小增量攒够一格再发
+    const step = wheelAcc < 0 ? 1 : -1;
+    wheelAcc += step * 100;
+    post(`zoom ${step} ${fx} ${fy}`);
+  }
+}, { passive: false });
+const grip = $('grip');
+if (grip) {
+  grip.addEventListener('pointerdown', e => { if (e.button !== 0) return; e.preventDefault(); e.stopPropagation(); post('resize'); });
+  grip.addEventListener('dblclick', e => { e.preventDefault(); post('size-reset'); });
+}
+let badgeTimer = 0;
+function showBadge(text) {
+  const b = $('zoomBadge'); if (!b) return;
+  b.textContent = text; b.hidden = false;
+  clearTimeout(badgeTimer);
+  badgeTimer = setTimeout(() => { b.hidden = true; }, 900);
+}
+if (hostAttached()) chrome.webview.addEventListener('message', e => {
+  if (e.data && typeof e.data === 'object') {applyOfficeSnapshot(e.data);return;}
+  const m = String(e.data || '');
+  if (m.startsWith('size ')) showBadge(m.slice(5) + '%');
+});
+
+/* ---------- 11. 真实会话快照 ---------- */
+let officeSnapshot = {version:1,follow:true,connected:false,offices:[],agents:[],selected:null};
+let officeIdentity = '', liveReady = false;
+const seenTransfers = new Set();
+const TRANSFER_TAG = {NEW_TASK:'新任务', MESSAGE:'消息', FINAL_ANSWER:'回报'};
+const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+function action(value) {post(JSON.stringify(value));}
+function removeAgent(id) {
+  const a=AG[id];if(!a)return;
+  if(STN[a.seat]&&STN[a.seat].agent===id)STN[a.seat].agent=null;
+  a.walk=null;walkers.delete(a);
+  a.bub.remove();delete AG[id];
+  if(selected===id)selected=null;
+}
+function clearAgents() {
+  for(const id of Object.keys(AG))removeAgent(id);
+  for(const e of envelopes)e.el?.remove();
+  envelopes.length=0;floats.length=0;walkers.clear();
+}
+// 进出场：只在本办公室已经显示过一帧真实快照后才演（切换办公室、重连恢复都直接落座）
+const motionOK=()=>liveReady&&!reducedMotion.matches;
+const shortName=name=>{const s=[...String(name||'')];return s.length>8?s.slice(0,7).join('')+'…':s.join('');};
+function bossOf(item,visible) {
+  const parent=item.parentPath&&visible.find(x=>x.path===item.parentPath&&AG[x.id]&&!AG[x.id].leaving);
+  const boss=parent||visible.find(x=>x.root);
+  return boss&&AG[boss.id]&&boss.id!==item.id?AG[boss.id]:null;
+}
+const posOf=a=>a.walk?[a.walk.x,a.walk.y]:STN[a.seat]?[STN[a.seat].x,STN[a.seat].y]:DOOR;
+// 新成员：进门 → 到派活的人桌前领信封 → 绕到自己椅子后面 → 坐下
+function enterOffice(a,boss,from=DOOR) {
+  const S=STN[a.seat];
+  if(!S)return;
+  if(!motionOK()) {   // 减少动态效果：不走路，信封直接从派活的人飞到工位
+    if(boss&&liveReady){send(boss.id,a.id,'任务');say(boss.id,'派给 '+shortName(a.name),2200);}
+    return;
+  }
+  const stops=[{p:from}];
+  const B=boss&&!boss.walk&&STN[boss.seat];
+  if(B) stops.push({p:deskFront(B),wait:1000,face:[B.x,B.y],call:()=>{send(boss.id,a.id,'任务');say(boss.id,'交给你了',1500);}});
+  stops.push({p:seatBehind(S)},{p:[S.x,S.y],direct:true});
+  startWalk(a,route(stops),null);
+}
+// 离开：完成的人先到上级桌前交回报，再出门；失败/停止的人直接出门
+function leaveOffice(a,boss,report) {
+  const S=STN[a.seat];
+  if(S&&S.agent===a.id)S.agent=null;
+  a.leaving=true;
+  const from=posOf(a),stops=[{p:from}];
+  if(S&&!a.walk)stops.push({p:seatBehind(S),direct:true});
+  const B=report&&boss&&!boss.walk&&STN[boss.seat];
+  if(B) stops.push({p:deskFront(B),wait:1000,face:[B.x,B.y],call:()=>{send(a.id,boss.id,'回报');say(boss.id,'收到 '+shortName(a.name)+' 的结果',2600);}});
+  stops.push({p:DOOR});
+  startWalk(a,route(stops),()=>removeAgent(a.id));
+}
+// 正在往外走的人又接到任务：掉头回工位
+function returnToSeat(a,boss) {
+  const seat=freeSeat(a.seat);
+  if(!seat){removeAgent(a.id);return false;}
+  a.leaving=false;a.seat=seat;STN[seat].agent=a.id;
+  enterOffice(a,boss,posOf(a));
+  if(!motionOK()){a.walk=null;walkers.delete(a);}
+  return true;
+}
+function stableLook(seed) {
+  const rand=rng(seed), choose=items=>items[Math.floor(rand()*items.length)];
+  const style=choose(HAIR_STYLES);let head=choose(HEADWEAR);
+  if(TALL_HAIR.has(style)&&(head==='cap'||head==='beanie'))head='';
+  return {hair:choose(HAIR_COLORS),skin:choose(SKIN_TONES),shirt:choose(SHIRT_COLORS),pants:'#3a3f52',acc:[style,head,choose(FACEWEAR),choose(CHESTWEAR)].filter(Boolean),accColor:choose(ACC_COLORS)};
+}
+function safeIcon(svg) {
+  // Keep SVG in an image document: never inject bridge-provided markup into DOM.
+  return 'data:image/svg+xml;charset=utf-8,'+encodeURIComponent(String(svg).replace(/currentColor/g,'#27324f'));
+}
+function applyOfficeSnapshot(next) {
+  if(!next||next.version!==1||!Array.isArray(next.agents)||!Array.isArray(next.offices))return;
+  const identity=next.selected?.sessionId||'';
+  const changed=identity!==officeIdentity;
+  if(changed) {
+    clearAgents();officeIdentity=identity;liveReady=false;seenTransfers.clear();
+    $('officeMembers').hidden=true;reportOfficeRegions();
+    relayout(Number(next.seed)||1);
+  }
+  officeSnapshot=next;
+  const visible=next.agents.slice(0,8), ids=new Set(visible.map(a=>a.id)), completed=new Set(next.completed||[]);
+  for(const id of Object.keys(AG)) {
+    const a=AG[id];
+    if(ids.has(id)||a.leaving)continue;
+    const item={id,parentPath:a.parentPath||''}, boss=bossOf(item,visible), report=completed.has(id);
+    if(motionOK()) {a.state=report?'done':a.state;a.activityLabel=report?'已完成':a.activityLabel;a.detail='';leaveOffice(a,boss,report);}
+    else {
+      if(liveReady&&report&&boss){send(id,boss.id,'回报');say(boss.id,'收到 '+shortName(a.name)+' 的结果',2600);}
+      removeAgent(id);
+    }
+  }
+  for(const item of visible) {
+    let a=AG[item.id];
+    if(a&&a.leaving&&!returnToSeat(a,bossOf(item,visible)))a=null;
+    if(!a) {
+      a=addAgent({id:item.id,name:item.name,role:item.root?'conductor':'coder',seat:item.root?'s_conductor':undefined,
+        look:item.root?{hair:'#3b2a22',skin:'#f7d5b5',shirt:'#2d406e',pants:'#262b38',acc:['tie']}:stableLook(item.seed)});
+      if(!a)continue;
+      a.parentPath=item.parentPath||'';
+      if(liveReady&&!item.root)enterOffice(a,bossOf(item,visible));
+    }
+    const key=[item.state,item.label,item.tool].join('|');
+    if(key!==a.activityKey){a.activityKey=key;a.labelAt=simNow;}
+    a.name=item.name;a.contextKnown=item.contextKnown;a.contextRatio=item.contextRatio;a.parentPath=item.parentPath||'';
+    a.activityLabel=item.label;a.detail=item.detail||'';a.tool=item.tool;a.icon=item.icon||'';a.iconSvg=item.iconSvg||'';
+    if(liveReady&&item.compactId&&item.compactId!==a.compactId) {
+      robot.text='整理好旧文件了';robot.textUntil=simNow+2600;
+    }
+    a.compactId=item.compactId;
+    setState(a.id,item.state);
+    if(item.state==='compact'){robot.text='整理上下文';robot.textUntil=simNow+1600;}
+    for(const transfer of item.transfers||[]) {
+      const key=item.id+':'+transfer.seq;
+      if(seenTransfers.has(key))continue;
+      seenTransfers.add(key);
+      if(!liveReady)continue;
+      const from=visible.find(x=>x.id===transfer.sender_session_id||x.path===transfer.sender);
+      const to=visible.find(x=>x.path===transfer.recipient)||item;
+      if(!from||!to||from.id===to.id||!AG[from.id]||!AG[to.id])continue;
+      send(from.id,to.id,TRANSFER_TAG[transfer.type]||'消息');
+    }
+  }
+  while(seenTransfers.size>256)seenTransfers.delete(seenTransfers.values().next().value);
+  board.doing=next.agents.filter(a=>a.busy).length;
+  board.todo=next.agents.filter(a=>a.state==='permission'||a.state==='question').length;
+  board.done=next.agents.some(a=>a.root&&a.state==='sleep')?1:0;
+  tokens=next.agents.reduce((n,a)=>n+(a.contextTokens||0),0);
+  updateOfficeControls();syncOfficeMembers();liveReady=true;render();presentUpscale();
+}
+let controlsKey='';
+function updateOfficeControls() {
+  const s=officeSnapshot, tabs=$('officeTabs');
+  const key=JSON.stringify([s.offices,s.selected?.sessionId,s.follow,s.connected,s.complete,s.overflow]);
+  if(key===controlsKey)return;controlsKey=key;
+  tabs.replaceChildren();
+  s.offices.slice(0,5).forEach((office,index)=>{
+    const b=document.createElement('button');b.type='button';b.className='office-tab';b.setAttribute('role','tab');
+    b.textContent=office.title||String(index+1);b.title=[office.workspaceName,office.title].filter(Boolean).join(' / ');
+    b.setAttribute('aria-label',b.title);b.setAttribute('aria-selected',String(office.sessionId===s.selected?.sessionId));
+    b.addEventListener('click',()=>action({type:'select',session_id:office.sessionId,workspace_hash:office.workspaceHash}));
+    tabs.appendChild(b);
+  });
+  $('officeFollow').setAttribute('aria-checked',String(s.follow));
+  const notice=$('officeNotice');
+  notice.textContent=!s.connected?'连接已中断，正在重连':!s.selected?(s.complete===false?'正在读取最近会话':'发送消息后，会话会出现在这里'):s.complete===false?'正在读取最近会话':'';
+  notice.hidden=!notice.textContent;
+  const overflow=$('officeOverflow');overflow.hidden=!s.overflow;overflow.textContent='+'+s.overflow;
+  overflow.setAttribute('aria-label','查看其余 '+s.overflow+' 位成员');
+}
+$('officeFollow').addEventListener('click',()=>action({type:'follow',follow:!officeSnapshot.follow}));
+function reportOfficeRegions() {
+  const rects=[$('officeMembers'),$('officeNotice')].filter(node=>node&&!node.hidden).map(node=>node.getBoundingClientRect());
+  const rect=rects.length?[Math.min(...rects.map(r=>r.left))/innerWidth,Math.min(...rects.map(r=>r.top))/innerHeight,
+    Math.max(...rects.map(r=>r.right))/innerWidth,Math.max(...rects.map(r=>r.bottom))/innerHeight]:null;
+  action({type:'overlay',rect,bubbles:bubbleRegions});
+}
+function syncOfficeMembers() {
+  const list=$('officeMembers');
+  if(!officeSnapshot.overflow)list.hidden=true;
+  if(list.hidden){reportOfficeRegions();return;}
+  const focused=document.activeElement?.dataset.memberId;
+  list.replaceChildren();
+  for(const member of officeSnapshot.agents){const b=document.createElement('button');b.type='button';b.dataset.memberId=member.id;b.textContent=member.name+' · '+member.label;
+    b.addEventListener('click',()=>{action({type:'open',session_id:member.id,workspace_hash:officeSnapshot.selected?.workspaceHash||''});list.hidden=true;reportOfficeRegions();});list.appendChild(b);}
+  if(focused){const button=Array.from(list.children).find(b=>b.dataset.memberId===focused);(button||$('officeOverflow')).focus();}
+  reportOfficeRegions();
+}
+$('officeOverflow').addEventListener('click',()=>{
+  const list=$('officeMembers');list.hidden=!list.hidden;syncOfficeMembers();
+});
+document.addEventListener('keydown',e=>{if(e.key==='Escape'){$('officeMembers').hidden=true;reportOfficeRegions();}});
+cv.addEventListener('dblclick',()=>{if(selected)action({type:'open',session_id:selected,workspace_hash:officeSnapshot.selected?.workspaceHash||''});});
+// A stable empty room appears until the first real snapshot; no demo workers.
+buildLayout(1);
+window.AgentOffice={applySnapshot:applyOfficeSnapshot,get snapshot(){return officeSnapshot;},
+  get agents(){return Object.values(AG).map(a=>({id:a.id,name:a.name,state:a.state,contextRatio:a.contextRatio,look:a.look.key,seat:a.seat,
+    walking:!!a.walk,leaving:a.leaving,bubble:a.bub.hidden?'':a.bub.textContent,compact:a.bub.classList.contains('compact')}));},
+  get envelopes(){return envelopes.map(e=>({from:e.a.id,to:e.b.id,label:e.el?e.el.textContent:''}));},
+  get layoutSignature(){return JSON.stringify({theme:THEME,seats:Object.values(STN).map(s=>[s.id,s.x,s.y,s.axis,s.s])});},
+  // 测试用：按 32ms 步长推进模拟时间（走路、信封、等待）后重画一帧
+  advance(ms){for(let left=ms;left>0;left-=32)advance(Math.min(32,left));render();presentUpscale();},
+  layout:seed=>relayout(seed)};
+fit();
+requestAnimationFrame(t=>{last=t;requestAnimationFrame(loop);});
+
+})();
+
+</script>
+</body>
+</html>
diff --git a/assets/desktop_pet/surface.md b/assets/desktop_pet/surface.md
new file mode 100644
index 000000000..795e67192
--- /dev/null
+++ b/assets/desktop_pet/surface.md
@@ -0,0 +1,46 @@
+# 像素办公室界面约束
+
+模式：Operate。用途是在桌面像素场景中查看真实 agent 状态，并切换所观察的主会话。视觉规则见 [DESIGN.md](DESIGN.md)，场景实现见 [agent_office_pet.html](agent_office_pet.html)。
+
+## 视觉与首屏
+
+透明等距房间占据主体，顶部仅保留最近会话和跟随开关。原作家具、五套布局模板及像素角色保持；场景不扩展为管理页面。首次连接前显示空房间，连接或读取提示位于控制条下方。
+
+## 会话与成员
+
+- 最近列表跨工作区汇总，按用户最后发送消息的时间降序取五个主会话，排除已归档会话和子会话。
+- 跟随默认开启，观察主窗口当前会话；手动选择会话后关闭跟随。重新开启后回到主窗口当前会话。
+- 房间种子来自会话 ID；会话切换清理旧角色与瞬态效果，同一会话刷新保持布局和角色外观。
+- 房间显示一个主 agent 与最多七个子 agent；更多成员通过 `+N` 列表查看。列表展示完整当前成员集合及状态，展开期间持续更新。
+
+## 状态表达
+
+| 真实状态 | 场景表达 |
+| --- | --- |
+| 尚未开始执行 | 待命；没有演示角色补位 |
+| 推理 | 思考点轮流跳；气泡显示「思考中」或具体进度标题，以及推理最后几个词 |
+| 输出正文 | 打字动画；气泡显示「撰写回复」与最新几个字和光标，两次快照之间由 WebSocket token 实时补字 |
+| 调用工具 | 读类工具看屏幕点头、写类工具敲键盘；气泡显示与聊天共源的图标、动作和调用预览 |
+| 等成员回报 | 沙漏；气泡显示「等成员回报」 |
+| 等待授权、等待回答、重试 | 保留各自的明确状态文案 |
+| 主 agent 成功完成 | 留在主工位，显示 `zzz`；下一轮开始后恢复执行状态 |
+| 子 agent 加入 | 从门口走进，到派活的人桌前领「任务」信封，再回工位 |
+| 子 agent 成功完成 | 走到派活的人桌前递「回报」信封后出门；后续任务出现时再按真实成员恢复 |
+| 执行失败或停止 | 本轮保留失败或停止状态，不能表现为成功休息 |
+| 整理上下文 | 显示整理状态及机器人提示；文件堆随后跟随新上下文比例 |
+
+文件堆反映当前上下文使用量相对窗口容量的比例，不使用会话累计消耗量。容量未知时不绘制文件堆，不能把未知当作零用量。消息信封由真实成员变化或消息记录触发；减少动态效果偏好下不走路，信封仍然飞过（它表达谁和谁在交接，不是装饰）。
+
+状态气泡常驻于忙碌的 agent 头顶，按「求助 > 主 agent > 正在输出 > 刚变化」的优先级摆放：撞上就左右错开或抬高（引线连回头顶），再放不下只显示动作。有人忙时机器人不闲聊。
+
+## 桌面交互
+
+- 拖动场景移动窗口；单击角色查看名称和状态，双击打开对应会话。
+- 滚轮或把手调整窗口大小，把手双击恢复默认大小；控件和成员列表中的滚动不触发场景缩放。
+- 右键交给原生菜单。桌面窗口保持透明、置顶及不抢焦点约束；主动打开会话属于独立操作。
+- 成员列表独立滚动，点击成员打开会话并关闭列表，Escape 关闭列表；列表区域与原生命中区域保持同步。
+- 连接中断时保留最后快照并显示重连提示，不能继续伪造实时进展。
+
+## 依据与验证边界
+
+规则来自当前 HTML、`desktopOfficeState.js`、`desktopOfficeController.js` 与原生宠物窗口实现。本文只记录已实现行为与视觉约束，不作为原生窗口实测通过的证明；验收状态以该变更的任务和验证记录为准。
diff --git a/cmake/acecode_desktop.cmake b/cmake/acecode_desktop.cmake
index 3416eb372..7e3326e91 100644
--- a/cmake/acecode_desktop.cmake
+++ b/cmake/acecode_desktop.cmake
@@ -71,6 +71,10 @@ FetchContent_MakeAvailable(webview)
 # acecode_testable 把 agent/TUI/web assets 全部拖入桌面壳。
 if(APPLE)
     set(ACECODE_AGENT_BROWSER_HOST_SOURCE ${ACECODE_AGENT_BROWSER_HOST_MAC_SOURCE})
+    # The macOS office host is the only ARC translation unit in this target.
+    set(ACECODE_DESKTOP_PET_SOURCE ${ACECODE_DESKTOP_PET_MAC_SOURCE})
+    set_source_files_properties(${ACECODE_DESKTOP_PET_MAC_SOURCE}
+        PROPERTIES COMPILE_OPTIONS "-fobjc-arc")
 endif()
 
 set(ACECODE_DESKTOP_SOURCES
@@ -78,6 +82,7 @@ set(ACECODE_DESKTOP_SOURCES
     ${ACECODE_DESKTOP_MAIN_SOURCE}
     ${ACECODE_DESKTOP_SPLASH_SOURCE}
     ${ACECODE_DESKTOP_WEB_HOST_SOURCE}
+    ${ACECODE_DESKTOP_PET_SOURCE}
 )
 if(UNIX AND NOT APPLE)
     list(APPEND ACECODE_DESKTOP_SOURCES
@@ -129,10 +134,27 @@ endif()
 
 if(WIN32)
     target_link_libraries(acecode-desktop PRIVATE
-        ole32 shell32 user32 gdi32
+        ole32 shell32 user32 gdi32 dwmapi
     )
 endif()
 
+if(WIN32 OR APPLE)
+    set(ACECODE_DESKTOP_PET_PAGE "${CMAKE_SOURCE_DIR}/assets/desktop_pet/agent_office_pet.html")
+    set(ACECODE_DESKTOP_PET_PAGE_CPP "${CMAKE_BINARY_DIR}/generated/desktop_pet_page_embedded.cpp")
+    add_custom_command(
+        OUTPUT ${ACECODE_DESKTOP_PET_PAGE_CPP}
+        COMMAND ${CMAKE_COMMAND}
+            -DBIN2CPP_INPUT=${ACECODE_DESKTOP_PET_PAGE}
+            -DBIN2CPP_OUTPUT=${ACECODE_DESKTOP_PET_PAGE_CPP}
+            -DBIN2CPP_SYMBOL=desktop_pet_page
+            -P ${CMAKE_SOURCE_DIR}/cmake/acecode_bin2cpp.cmake
+        DEPENDS ${ACECODE_DESKTOP_PET_PAGE} ${CMAKE_SOURCE_DIR}/cmake/acecode_bin2cpp.cmake
+        COMMENT "Embedding the desktop agent office"
+        VERBATIM
+    )
+    target_sources(acecode-desktop PRIVATE ${ACECODE_DESKTOP_PET_PAGE_CPP})
+endif()
+
 if(UNIX AND NOT APPLE)
     set(ACECODE_LINUX_ICON "${CMAKE_SOURCE_DIR}/web/public/acecode-logo.png")
     # Refresh the adjacent window/tray artwork even when only the icon changes.
diff --git a/cmake/acecode_layer_libraries.cmake b/cmake/acecode_layer_libraries.cmake
index 5153f4bc9..be9e22746 100644
--- a/cmake/acecode_layer_libraries.cmake
+++ b/cmake/acecode_layer_libraries.cmake
@@ -69,9 +69,14 @@ elseif(WIN32)
     target_link_libraries(acecode_base_core PRIVATE
         bcrypt advapi32 ws2_32 ole32 shell32 user32 gdi32 msimg32 winmm)
 endif()
+if(NOT WIN32)
+    # platform/crypto 的 AES-256-GCM 在非 Windows 平台走 libcrypto。
+    target_link_libraries(acecode_base_core PRIVATE OpenSSL::Crypto)
+endif()
 
 acecode_add_layer_library(acecode_base_host base ${_base_host})
-target_link_libraries(acecode_base_host PUBLIC acecode_base_core cpr::cpr
+# network/websocket_client 直接使用 libcurl 的 WebSocket API。
+target_link_libraries(acecode_base_host PUBLIC acecode_base_core cpr::cpr CURL::libcurl
     PRIVATE unofficial::sqlite3::sqlite3)
 if(WIN32)
     target_link_libraries(acecode_base_host PRIVATE winhttp iphlpapi winpty_static)
@@ -164,7 +169,8 @@ set(ACECODE_DESKTOP_BINARY_ONLY_SOURCES
     ${ACECODE_DEEPIN_WINDOW_EFFECTS_SOURCE} ${ACECODE_DESKTOP_LINUX_SOURCE}
     ${ACECODE_AGENT_BROWSER_HOST_SOURCE} ${ACECODE_AGENT_BROWSER_HOST_MAC_SOURCE}
     ${ACECODE_DESKTOP_MAIN_SOURCE} ${ACECODE_DESKTOP_SPLASH_SOURCE}
-    ${ACECODE_DESKTOP_WEB_HOST_SOURCE})
+    ${ACECODE_DESKTOP_WEB_HOST_SOURCE} ${ACECODE_DESKTOP_PET_SOURCE}
+    ${ACECODE_DESKTOP_PET_MAC_SOURCE})
 acecode_collect_group_sources(_desktop apps/desktop)
 list(REMOVE_ITEM _desktop ${ACECODE_DESKTOP_BINARY_ONLY_SOURCES})
 acecode_add_layer_library(acecode_desktop_support apps ${_desktop})
diff --git a/cmake/acecode_source_paths.cmake b/cmake/acecode_source_paths.cmake
index cfb418163..95d7a1dfe 100644
--- a/cmake/acecode_source_paths.cmake
+++ b/cmake/acecode_source_paths.cmake
@@ -7,6 +7,8 @@ set(ACECODE_DEEPIN_WINDOW_EFFECTS_SOURCE "${CMAKE_SOURCE_DIR}/src/apps/desktop/d
 set(ACECODE_DESKTOP_MAIN_SOURCE "${CMAKE_SOURCE_DIR}/src/apps/desktop/main.cpp")
 set(ACECODE_DESKTOP_SPLASH_SOURCE "${CMAKE_SOURCE_DIR}/src/apps/desktop/splash_screen.cpp")
 set(ACECODE_DESKTOP_WEB_HOST_SOURCE "${CMAKE_SOURCE_DIR}/src/apps/desktop/web_host.cpp")
+set(ACECODE_DESKTOP_PET_SOURCE "${CMAKE_SOURCE_DIR}/src/apps/desktop/desktop_pet.cpp")
+set(ACECODE_DESKTOP_PET_MAC_SOURCE "${CMAKE_SOURCE_DIR}/src/apps/desktop/desktop_pet_mac.mm")
 set(ACECODE_DESKTOP_LINUX_SOURCE "${CMAKE_SOURCE_DIR}/src/apps/desktop/linux_desktop.cpp")
 set(ACECODE_AGENT_BROWSER_HOST_SOURCE "${CMAKE_SOURCE_DIR}/src/apps/desktop/agent_browser_host.cpp")
 set(ACECODE_AGENT_BROWSER_HOST_MAC_SOURCE "${CMAKE_SOURCE_DIR}/src/apps/desktop/agent_browser_host_mac.mm")
@@ -85,6 +87,8 @@ acecode_require_sources("shared target source paths"
     ${ACECODE_DESKTOP_MAIN_SOURCE}
     ${ACECODE_DESKTOP_SPLASH_SOURCE}
     ${ACECODE_DESKTOP_WEB_HOST_SOURCE}
+    ${ACECODE_DESKTOP_PET_SOURCE}
+    ${ACECODE_DESKTOP_PET_MAC_SOURCE}
     ${ACECODE_DESKTOP_LINUX_SOURCE}
     ${ACECODE_AGENT_BROWSER_HOST_SOURCE}
     ${ACECODE_AGENT_BROWSER_HOST_MAC_SOURCE}
diff --git a/design-prototypes/agent-office/DESIGN.md b/design-prototypes/agent-office/DESIGN.md
deleted file mode 100644
index 0904f1c84..000000000
--- a/design-prototypes/agent-office/DESIGN.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# 像素 AI 办公室视觉约定
-
-用户参考图是视觉权威：浅绿网格地砖、米白墙面、蓝色办公椅、彩色显示器、细深色像素轮廓。直接以代码构建此风格。
-
-场景占据首屏主区域。外壳像一张暖白的办公室管理台：低饱和苔绿导航、纸面按钮、轻量成员名册；避免管理卡片挤占像素场景。标题“好好工作事务所”，强调小团队共同工作的生活感。
-
-共享 2:1 等距投影；所有素材以整数像素绘制，最近邻缩放。人物使用同一模板及发型、肤色、衣服换色；桌椅、显示器、绿植、柜体共享资源定义。墙面、书架、咖啡角、会议桌、窗外树木组成完整房间。
-
-主交互：点击小人或成员名册查看状态；派发演示任务；暂停/继续及 1x/2x/4x；缩放；查看共享资源图鉴。窄屏保持场景完整，名册下移。键盘焦点清楚，减少动态偏好默认暂停。
diff --git a/design-prototypes/agent-office/PRODUCT.md b/design-prototypes/agent-office/PRODUCT.md
deleted file mode 100644
index dd3598669..000000000
--- a/design-prototypes/agent-office/PRODUCT.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# 像素 AI 办公室
-
-<!-- impeccable:product-schema 1 -->
-
-## Platform
-
-web
-
-## Users
-
-用户希望先体验 Agent Team 的可视化办公室，再决定正式集成。
-
-## Product Purpose
-
-用有工作动作的小人呈现 AI 团队分工，验证像素办公室效果。
-
-## Capabilities and Constraints
-
-用户确认独立演示页，先看效果；用代码绘制，最大化资源复用。所有任务与团队数据为本地模拟，不连接真实模型。实现选择为原生 HTML/CSS/Canvas，无外部资源依赖。
-
-## Brand Commitments
-
-以用户提供的等距像素办公室图片为视觉依据。
diff --git a/design-prototypes/agent-office/README.md b/design-prototypes/agent-office/README.md
deleted file mode 100644
index f193822ac..000000000
--- a/design-prototypes/agent-office/README.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# 好好工作事务所
-
-等距像素风 AI 办公室 demo。参考用户提供的办公室画面，全部使用 Canvas 代码绘制；团队与任务为本地模拟，没有真实模型请求。
-
-## 打开
-
-双击本目录的 **index.html**，使用 Chrome 或 Edge 打开即可。不需要安装依赖、启动服务器或联网。请保留同目录的 CSS 和四个 JS 文件。
-
-默认自动演示一个进行中的项目。开启系统“减少动态效果”时默认暂停，可手动点击“继续”。
-
-## 可以体验什么
-
-- 6 位伙伴分别负责规划、开发、设计、研究、审查和测试。
-- 点击小人或右侧成员按钮查看当前任务；成员按钮支持键盘操作。
-- 小人打字、眨眼，空闲时沿过道走去咖啡角，再回到工位。
-- 按依赖交接任务；整个项目完成后，“派发新任务”会启用。
-- 暂停/继续、1×/2×/4×、80%–140% 缩放、适应窗口。页面背景获得焦点时，空格也可暂停。
-- “素材图鉴”展示共享家具与人物；Escape 关闭图鉴。
-
-## 资源复用
-
-| 文件 | 唯一职责 |
-| --- | --- |
-| assets.js | 整数像素光栅、等距几何、家具工厂、人物模板、Atlas 缓存 |
-| simulation.js | 角色数据、通道移动、咖啡角占用、显式时间驱动的任务依赖 |
-| renderer.js | 缓存房间、家具实例布局、深度排序、人物与气泡合成、坐标命中 |
-| app.js | DOM 交互、动画调度、名册、详情与素材图鉴 |
-| office.css | 独立原型的响应式视觉系统 |
-
-- 地面重复使用 4 个配色图块；重复工位、椅子、隔板、绿植引用同一个缓存对象。
-- 人物共享同一套轮廓，通过发型、衣服、肤色和有限动作帧换色组合；头像与图鉴也取自同一 Atlas。
-- 墙壁、窗户、地板与光照只绘制一次到离屏 Canvas。家具实例只存位置与资源引用。
-- 最多 30 FPS 渲染，DOM 状态约每 220ms 更新一次；暂停、页面隐藏或打开图鉴时取消连续动画调度。
-- 缓存按资源类型、配色、动作和有限帧编号索引，不随运行时间无限增长。图鉴提供当前图块数和像素缓冲区估算，不包含浏览器自身开销。
-- **外部图片、字体、运行时依赖均为 0。** 源图不会作为背景贴图或资产被加载。
-
-新增一种家具：在 assets.js 的家具工厂中定义它，再向 renderer.js 的 furniture 数组添加实例。重复实例不需要重新绘制素材。修改角色外观只需修改 profiles 的配色与样式字段。
-
-将来接入真实 Agent Team 时，可保留 Atlas 和 Renderer，用真实事件驱动的状态适配器替换 Simulation；维持 actor 位置、action、任务进度和 status 的数据接口即可。本 demo 尚未接入 ACECode 正式界面。
-
-## 验证
-
-状态机使用 Node 内置测试，无额外测试依赖：
-
-~~~powershell
-node --test design-prototypes/agent-office/simulation.test.cjs
-~~~
-
-已验证：
-
-- 7 项状态机测试：暂停、倍速、无效时间、任务依赖、工位约束、咖啡往返、重复派发与完整完成。
-- Chromium 的 file 页面和本地 HTTP 页面；没有外部网络请求和页面脚本错误。
-- 鼠标/键盘成员选择、场景命中、缩放、图鉴及完成后的任务派发。
-- 暂停时模拟时间不变且没有连续绘制；隐藏页面和图鉴打开时不推进。
-- 320 / 390 / 768 / 1024 / 1440px 布局无横向溢出；桌面、手机和 150% DPI 截图检查。
-- 仓库 web 的 pnpm test、pnpm build，以及本次 OpenSpec 严格校验通过。
-
-设计记录位于 PRODUCT.md、DESIGN.md 和 surface.md；行为规范位于 openspec/changes/add-pixel-agent-office-demo。
diff --git a/design-prototypes/agent-office/app.js b/design-prototypes/agent-office/app.js
deleted file mode 100644
index 90e2f15e0..000000000
--- a/design-prototypes/agent-office/app.js
+++ /dev/null
@@ -1,103 +0,0 @@
-/* DOM is an adapter: simulation and artwork do not depend on this UI. */
-(function (O) {
-  'use strict';
-  const $=id=>document.getElementById(id);
-  const atlas=new O.Atlas(),sim=new O.Simulation(),renderer=new O.Renderer($('office'),atlas,sim);
-  const media=window.matchMedia('(prefers-reduced-motion: reduce)'); sim.paused=media.matches;
-  const events=new AbortController(),listen=(el,event,handler)=>el.addEventListener(event,handler,{signal:events.signal});
-  const rows=[]; let raf=null,lastTime=null,lastUi=0,eventSignature='',toastTimer=null;
-  const setText=(el,text)=>{text=String(text);if(el.textContent!==text)el.textContent=text;};
-  for(const a of sim.agents) {
-    const row=document.createElement('button'); row.type='button';row.className='agent-row';row.dataset.agent=a.index;
-    row.innerHTML='<canvas class="avatar" width="35" height="38" aria-hidden="true"></canvas><span><span class="agent-name"></span><span class="agent-role"></span></span><span class="agent-state"></span>';
-    row.querySelector('.agent-name').textContent=a.name;row.querySelector('.agent-role').textContent=a.role;
-    atlas.portrait(row.querySelector('canvas'),a.index);
-    listen(row,'click',()=>select(a.index));$('agent-list').append(row);rows.push(row);
-  }
-  function select(index) { sim.selected=index;updateUI();renderer.render(); }
-  function updateUI() {
-    setText($('clock'),sim.clock);setText($('day'),String(1+Math.floor(sim.time/(3*1440))).padStart(2,'0'));
-    let working=0;
-    for(const a of sim.agents) {
-      const row=rows[a.index],status=sim.status(a.index),state=row.querySelector('.agent-state');
-      row.setAttribute('aria-pressed',String(sim.selected===a.index));
-      row.setAttribute('aria-label',a.name+'，'+a.role+'，'+status.label);
-      setText(state,status.label);state.dataset.state=status.state;
-      if(a.action==='work')working++;
-    }
-    setText($('working-count'),working);setText($('resting-count'),(6-working)+' 位待命 / 休息');
-    const a=sim.agents[sim.selected],task=sim.tasks[sim.selected],status=sim.status(sim.selected),percent=Math.floor(task.elapsed/task.duration*100);
-    setText($('detail-name'),a.name);setText($('detail-role'),a.role);setText($('detail-id'),'AGENTS '+String(a.index+1).padStart(2,'0'));
-    setText($('detail-state'),status.label);
-    const description=task.elapsed>=task.duration?'已完成'+task.title+'。休息一下，准备迎接下一个好想法。':!sim.ready(a.index)?'等待'+task.deps.filter(i=>sim.tasks[i].elapsed<sim.tasks[i].duration).map(i=>sim.agents[i].name).join('、')+'交接，然后开始'+task.title+'。':task.text;
-    setText($('detail-task'),description);setText($('detail-percent'),percent+'%');$('detail-progress').style.width=percent+'%';
-    setText($('project-title'),sim.title);setText($('project-status'),sim.finished?'作品已完成':sim.paused?'协作已暂停':'团队正在协作');
-    setText($('task-count'),sim.doneCount+' / 6 项任务完成');
-    const total=Math.floor(sim.progress*100);$('project-percent').firstChild.textContent=total;$('project-fill').style.width=total+'%';
-    setText($('progress-caption'),sim.finished?'做得不错！可以派发下一个任务了。':'一步一步，把想法变成作品。');
-    setText($('scene-heading'),sim.paused?'把灵感暂停一下':sim.finished?'今天的好想法已完成':'灵感正在发生');
-    const dispatch=$('new-project');dispatch.disabled=sim.active;
-    dispatch.lastChild.textContent=sim.active?'任务进行中':'派发新任务';dispatch.title=sim.active?'当前项目完成后，可派发下一个演示任务':'开启下一个演示项目';
-    $('toggle-pause').setAttribute('aria-pressed',String(sim.paused));
-    $('toggle-pause').querySelector('use').setAttribute('href',sim.paused?'#i-play':'#i-pause');
-    setText($('toggle-pause').querySelector('span'),sim.paused?'继续':'暂停');$('pause-overlay').hidden=!sim.paused;
-    for(const button of document.querySelectorAll('[data-speed]')) button.setAttribute('aria-pressed',String(Number(button.dataset.speed)===sim.speed));
-    const signature=sim.events.map(e=>e.time+e.text).join('|');
-    if(signature!==eventSignature) {
-      eventSignature=signature;$('activity-list').replaceChildren();
-      for(const e of sim.events.slice(0,3)) { const li=document.createElement('li'),time=document.createElement('time'),text=document.createElement('span');time.textContent=e.time;text.textContent=e.text;li.append(time,text);$('activity-list').append(li); }
-    }
-    setText($('zoom-label'),Math.round(renderer.zoom*100)+'%');
-    $('zoom-out').disabled=renderer.zoom<=.8;$('zoom-in').disabled=renderer.zoom>=1.4;
-  }
-  function stop() { if(raf!==null) cancelAnimationFrame(raf);raf=null;lastTime=null; }
-  function canAnimate() {return !sim.paused&&!document.hidden&&!$('library').open;}
-  function start() { if(raf===null&&canAnimate()) {lastTime=null;raf=requestAnimationFrame(frame);} }
-  function frame(now) {
-    raf=null;if(!canAnimate()) {lastTime=null;return;}
-    if(lastTime===null)lastTime=now;
-    const dt=(now-lastTime)/1000;
-    if(dt>=1/30) {
-      sim.tick(Math.min(dt,.25));lastTime=now;renderer.render();
-      if(now-lastUi>220) {updateUI();lastUi=now;}
-    }
-    raf=requestAnimationFrame(frame);
-  }
-  function refresh() {updateUI();renderer.render();}
-  function togglePause() {sim.paused=!sim.paused;stop();refresh();start();}
-  function toast(message) {clearTimeout(toastTimer);setText($('toast'),message);$('toast').hidden=false;toastTimer=setTimeout(()=>{$('toast').hidden=true;},3200);}
-  function zoom(delta) {renderer.zoom=Math.round(Math.max(.8,Math.min(1.4,renderer.zoom+delta))*100)/100;refresh();}
-  listen($('toggle-pause'),'click',togglePause);
-  listen($('new-project'),'click',()=>{if(sim.startProject()) {refresh();toast('新任务已派发，看看大家怎么分工吧。');}});
-  for(const button of document.querySelectorAll('[data-speed]')) listen(button,'click',()=>{sim.speed=Number(button.dataset.speed);updateUI();});
-  listen($('zoom-in'),'click',()=>zoom(.1));listen($('zoom-out'),'click',()=>zoom(-.1));
-  listen($('zoom-reset'),'click',()=>{renderer.zoom=1;refresh();});
-  listen($('office'),'pointermove',e=>{const next=renderer.hit(e);$('office').style.cursor=next>=0?'pointer':'default';if(next!==renderer.hover){renderer.hover=next;renderer.render();}});
-  listen($('office'),'pointerleave',()=>{renderer.hover=-1;renderer.render();});
-  listen($('office'),'click',e=>{const hit=renderer.hit(e);if(hit>=0)select(hit);});
-  listen(document,'keydown',e=>{if(e.code==='Space'&&e.target===document.body&&!$('library').open){e.preventDefault();togglePause();}});
-  listen(document,'visibilitychange',()=>{stop();start();});
-  listen(window,'pagehide',stop);listen(window,'pageshow',start);
-  listen(media,'change',e=>{if(e.matches){sim.paused=true;stop();refresh();}});
-  const labels=[['tile','共享地砖'],['desk','标准工位'],['chair','办公椅'],['partition','工位隔板'],['bookcase','资料书架'],['cabinet','储物柜'],['plant','绿植'],['server','服务器'],['whiteboard','任务白板'],['sofa','休息沙发'],['table','咖啡小桌'],['coffee','咖啡台']];
-  let libraryBuilt=false;
-  function buildLibrary() {
-    if(libraryBuilt)return;libraryBuilt=true;
-    for(const [type,label] of labels) {
-      const item=document.createElement('div');item.className='asset-tile';
-      const preview=document.createElement('canvas');preview.width=110;preview.height=96;preview.setAttribute('aria-label',label);
-      const c=preview.getContext('2d');c.imageSmoothingEnabled=false;
-      if(type==='tile')atlas.draw(c,atlas.tile(0),55,27,1.8);
-      else {const s=atlas.get(type);c.drawImage(s.canvas,29,51,102,93,0,0,110,96);}
-      const caption=document.createElement('span');caption.textContent=label;item.append(preview,caption);$('asset-grid').append(item);
-    }
-    for(const a of sim.agents) {const item=document.createElement('div'),portrait=document.createElement('canvas');portrait.width=42;portrait.height=50;atlas.portrait(portrait,a.index);const label=document.createElement('span');label.textContent=a.name;item.append(portrait,label);$('portrait-grid').append(item);}
-  }
-  listen($('open-library'),'click',()=>{buildLibrary();const stats=atlas.stats();setText($('asset-stats'),stats.sprites+' 个缓存图块 · 约 '+stats.kib+' KiB 图块内存 · 0 张外部图片');$('library').showModal();stop();});
-  listen($('close-library'),'click',()=>{$('library').close();});
-  listen($('library'),'close',start);
-  listen($('library'),'click',e=>{if(e.target===$('library')){const r=$('library').getBoundingClientRect();if(e.clientX<r.left||e.clientX>r.right||e.clientY<r.top||e.clientY>r.bottom)$('library').close();}});
-  // A small, explicit seam for embedding, debugging and deterministic verification.
-  O.demo={simulation:sim,renderer,atlas,refresh,destroy(){stop();events.abort();clearTimeout(toastTimer);}};
-  refresh();start();
-})(globalThis.PixelOffice = globalThis.PixelOffice || {});
diff --git a/design-prototypes/agent-office/assets.js b/design-prototypes/agent-office/assets.js
deleted file mode 100644
index ba6f73de0..000000000
--- a/design-prototypes/agent-office/assets.js
+++ /dev/null
@@ -1,274 +0,0 @@
-/* Shared, code-drawn pixel atlas. No image files, fonts, network or libraries. */
-(function (O) {
-  'use strict';
-  const C = {
-    ink: '#41483f', edge: '#69715e', cream: '#f6f1df', wall: '#e8e5d4',
-    blue: '#548cb4', blueLight: '#75aed1', blueDark: '#3e6688',
-    wood: '#b78a56', woodLight: '#d2ad72', woodDark: '#8e6b49',
-    green: '#658c48', greenLight: '#91b75e', greenDark: '#3d6339',
-  };
-  function canvas(w, h) { const c = document.createElement('canvas'); c.width = w; c.height = h; return c; }
-  function rect(c, x, y, w, h, color) {
-    c.fillStyle = color; c.fillRect(Math.round(x), Math.round(y), Math.round(w), Math.round(h));
-  }
-  function line(c, x0, y0, x1, y1, color) {
-    x0 = Math.round(x0); y0 = Math.round(y0); x1 = Math.round(x1); y1 = Math.round(y1);
-    const dx = Math.abs(x1 - x0), sx = x0 < x1 ? 1 : -1;
-    const dy = -Math.abs(y1 - y0), sy = y0 < y1 ? 1 : -1;
-    let err = dx + dy;
-    c.fillStyle = color;
-    for (;;) {
-      c.fillRect(x0, y0, 1, 1);
-      if (x0 === x1 && y0 === y1) break;
-      const e2 = 2 * err;
-      if (e2 >= dy) { err += dy; x0 += sx; }
-      if (e2 <= dx) { err += dx; y0 += sy; }
-    }
-  }
-  function poly(c, points, fill, stroke) {
-    const p = points.map(([x, y]) => [Math.round(x), Math.round(y)]);
-    const lo = Math.min(...p.map(v => v[1])), hi = Math.max(...p.map(v => v[1]));
-    c.fillStyle = fill;
-    for (let y = lo; y <= hi; y++) {
-      const crosses = [];
-      for (let i = 0; i < p.length; i++) {
-        const a = p[i], b = p[(i + 1) % p.length];
-        if ((a[1] <= y && b[1] > y) || (b[1] <= y && a[1] > y)) {
-          crosses.push(a[0] + (y - a[1]) * (b[0] - a[0]) / (b[1] - a[1]));
-        }
-      }
-      crosses.sort((a, b) => a - b);
-      for (let i = 0; i + 1 < crosses.length; i += 2) {
-        c.fillRect(Math.ceil(crosses[i]), y, Math.floor(crosses[i + 1]) - Math.ceil(crosses[i]) + 1, 1);
-      }
-    }
-    if (stroke) p.forEach((v, i) => line(c, ...v, ...p[(i + 1) % p.length], stroke));
-  }
-  const iso = (x, y, z = 0) => [Math.round((x - y) * 24), Math.round((x + y) * 12 - z)];
-  function plane(c, x, y, w, d, z, color, stroke) {
-    poly(c, [iso(x, y, z), iso(x + w, y, z), iso(x + w, y + d, z), iso(x, y + d, z)], color, stroke);
-  }
-  function box(c, x, y, w, d, h, z, colors, stroke = C.ink) {
-    const a = iso(x, y, z), b = iso(x + w, y, z), e = iso(x + w, y + d, z), f = iso(x, y + d, z);
-    const at = iso(x, y, z + h), bt = iso(x + w, y, z + h), et = iso(x + w, y + d, z + h), ft = iso(x, y + d, z + h);
-    poly(c, [bt, et, e, b], colors[2], stroke);
-    poly(c, [ft, et, e, f], colors[1], stroke);
-    poly(c, [at, bt, et, ft], colors[0], stroke);
-  }
-  function panel(c, x, y, z, w, h, fill, stroke) {
-    poly(c, [iso(x, y, z), iso(x + w, y, z), iso(x + w, y, z + h), iso(x, y, z + h)], fill, stroke);
-  }
-  function shadow(c, w, d) { plane(c, -w / 2 + .13, -d / 2 + .16, w, d, 0, 'rgba(64,82,56,.16)'); }
-  const metal = ['#eff0e4', '#c1c5b7', '#d6d9cc'];
-  const wood = [C.woodLight, C.woodDark, C.wood];
-  function mug(c, x, y, z, color = '#f4e9cd') {
-    box(c, x, y, .14, .14, 5, z, [color, '#c6b693', color]);
-    const p = iso(x + .14, y + .03, z + 3);
-    rect(c, p[0], p[1], 3, 3, C.ink); rect(c, p[0], p[1], 2, 1, color);
-  }
-  function desk(c, variant) {
-    shadow(c, 1.8, 1.3);
-    for (const [x, y] of [[-.74,-.42],[.58,-.42],[-.74,.37],[.58,.37]]) {
-      box(c, x, y, .13, .13, 23, 0, metal);
-    }
-    box(c, .38, -.37, .32, .74, 15, 6, metal);
-    for (const z of [10,15,20]) panel(c, .42, .38, z, .25, 1, '#8d9686');
-    box(c, -.83, -.51, 1.66, 1.10, 4, 23, metal);
-    plane(c, -.74, -.44, 1.50, .94, 28, '#f9f8f0');
-    box(c, -.16, -.32, .32, .25, 2, 28, ['#7a837a','#5c635c','#68716b']);
-    box(c, -.03, -.27, .09, .09, 6, 29, metal);
-    box(c, -.36, -.36, .79, .12, 19, 34, ['#546369','#353f44','#4a5559']);
-    panel(c, -.30, -.231, 36, .66, 15, variant === 'warm' ? '#bb976a' : '#83b8c7');
-    panel(c, -.25, -.226, 38, .56, 10, variant === 'warm' ? '#e4be85' : '#b3d9d5');
-    for (let i = 0; i < 4; i++) panel(c, -.20, -.22, 39 + i * 2, .15 + (i % 3) * .09, 1, i % 2 ? '#579393' : '#eef4d7');
-    const p = iso(.30, -.22, 35); rect(c, p[0], p[1], 1, 1, '#b9d786');
-    box(c, -.21, .13, .69, .24, 1, 28, ['#9ba8a2','#88958e','#88958e']);
-    for (let i = 0; i < 5; i++) plane(c, -.17 + i * .12, .16, .06, .13, 30, '#e1e7d9');
-    plane(c, .60, .10, .18, .28, 28, '#b4c4b1');
-    box(c, .64, .16, .08, .12, 2, 28, metal);
-    mug(c, -.65, .18, 28, variant === 'warm' ? '#b48256' : '#98ad7d');
-  }
-  function chair(c) {
-    shadow(c, .70, .65);
-    const foot = iso(0, 0, 3);
-    for (const [x, y] of [[-10,4],[10,4],[0,-5]]) {
-      line(c, ...foot, x, y, '#535c53'); rect(c, x - 1, y, 3, 3, '#434a43');
-    }
-    box(c, -.06, -.05, .12, .12, 11, 3, ['#b4bbae','#7d857a','#8d9589']);
-    box(c, -.27, -.27, .55, .54, 4, 13, [C.blueLight,C.blueDark,C.blue]);
-    box(c, -.30, .25, .60, .11, 16, 18, [C.blueLight,C.blueDark,C.blue]);
-    line(c, -11, -17, -11, -10, '#606a60'); line(c, -11, -17, -5, -14, '#414c46');
-  }
-  function plant(c, small) {
-    shadow(c, .48, .48);
-    box(c, -.18, -.18, .36, .36, small ? 8 : 13, 0, ['#eae9d9','#b4b6a5','#d2d4c1']);
-    plane(c, -.13, -.13, .26, .26, small ? 9 : 14, '#6f6647');
-    const s = small ? .6 : 1;
-    c.save(); c.scale(s, s);
-    line(c, 0, -12, 0, -47, '#5f743a'); line(c, 1, -17, 1, -43, '#8a9c49');
-    for (const [x,y,flip] of [[-2,-25,1],[2,-34,-1],[-2,-40,1],[2,-46,-1],[-1,-33,1],[1,-25,-1]]) {
-      const p = [[x,y],[x+flip*12,y-12],[x+flip*9,y-16],[x+flip*3,y-12],[x,y-2]];
-      poly(c,p,C.greenDark); poly(c,p.map(([a,b])=>[a+flip,b-1]),C.green);
-      line(c,x,y-2,x+flip*8,y-12,C.greenLight);
-    }
-    poly(c,[[0,-40],[-4,-55],[0,-59],[4,-53],[2,-40]],C.greenDark);
-    line(c,0,-43,0,-56,C.greenLight); c.restore();
-  }
-  function bookcase(c) {
-    shadow(c, 1.18, .65);
-    box(c, -.58, -.28, 1.16, .57, 63, 0, ['#edeada','#b5b7a5','#c5c9b7']);
-    panel(c, -.50, .30, 5, 1.0, 52, '#888d7d', C.ink);
-    const books = ['#d0af63','#74969f','#a2654f','#718668','#e1d9b5','#667f9f'];
-    for (let row = 0; row < 3; row++) {
-      for (let i = 0; i < 6; i++) {
-        const z = 7 + row * 17, height = 11 + (i * 3 + row) % 5;
-        panel(c, -.45 + i * .152, .33, z, .12, height, books[(i + row * 2) % books.length], '#696c58');
-        panel(c, -.43 + i * .152, .335, z + 3, .07, 1, '#e4dfc9');
-      }
-      box(c, -.51, .18, 1.02, .20, 2, 5 + row * 17, metal);
-    }
-  }
-  function cabinet(c) {
-    shadow(c, 1.05, .64); box(c, -.52, -.32, 1.04, .64, 59, 0, metal);
-    panel(c, -.44, .33, 5, .87, 48, '#d0d3c4', '#858d7c');
-    const a = iso(0,.34,6), b=iso(0,.34,52); line(c,...a,...b,'#868d7d');
-    for(const x of [-.09,.09]) { const p=iso(x,.35,29); rect(c,p[0],p[1],1,7,'#6e786b'); }
-  }
-  function server(c) {
-    shadow(c, .9, .75); box(c,-.45,-.34,.9,.68,62,0,['#737f79','#45524e','#566560']);
-    for (let i=0;i<5;i++) {
-      panel(c,-.35,.35,5+i*11,.70,8,'#2f3f39','#879187');
-      panel(c,-.27,.36,8+i*11,.30,1,'#64766b');
-      const p=iso(.23,.36,10+i*11); rect(c,p[0],p[1],2,2,i===3?'#d6b468':'#a1bd74');
-    }
-  }
-  function whiteboard(c) {
-    for(const x of [-.75,.75]) { box(c,x,-.10,.09,.13,50,0,metal); box(c,x-.17,-.12,.42,.27,2,0,metal); }
-    box(c,-.92,-.14,1.85,.15,37,18,metal); panel(c,-.83,.02,22,1.67,30,'#f8f8ec','#a7af9b');
-    const colors=['#c49b63','#92aa76','#779eab','#c19b8b'];
-    for(let row=0;row<2;row++) for(let i=0;i<4;i++) panel(c,-.67+i*.36,.035,27+row*12,.23,7,colors[(i+row)%4]);
-    panel(c,-.65,.04,46,1.13,1,'#829172'); box(c,-.91,.02,1.87,.13,2,18,metal);
-  }
-  function sofa(c) {
-    shadow(c,1.90,.90);
-    for(const x of [-.8,.65]) box(c,x,-.20,.13,.13,7,0,wood);
-    box(c,-.94,-.32,1.88,.78,12,5,['#c99368','#966843','#ad7953']);
-    box(c,-.94,-.37,1.88,.20,25,12,['#dcaf80','#b4855e','#c39166']);
-    for(const x of [-.91,.68]) box(c,x,-.22,.24,.80,14,13,['#dca374','#ad7a52','#c59263']);
-    for(const x of [-.62,.06]) box(c,x,-.09,.61,.52,3,19,['#deb487','#bd946c','#c99c71']);
-    box(c,-.5,-.03,.31,.19,9,22,['#b2bf91','#88956e','#9eaa80']);
-  }
-  function table(c) {
-    shadow(c,1.15,.70);
-    for(const x of [-.43,.35]) for(const y of [-.19,.22]) box(c,x,y,.08,.08,13,0,wood);
-    box(c,-.60,-.34,1.2,.75,3,13,wood);
-    plane(c,-.34,-.20,.40,.34,17,'#e7e1c8','#87907a');
-    plane(c,-.31,-.17,.32,.25,18,'#9caf93'); mug(c,.21,.0,17);
-  }
-  function coffee(c) {
-    shadow(c,1.90,.78); box(c,-.95,-.36,1.90,.72,27,0,wood);
-    for(const x of [-.85,-.26,.33]) { panel(c,x,.37,3,.51,20,'#cba276','#846747'); const p=iso(x+.18,.38,20); rect(c,p[0],p[1],4,1,'#6d6248'); }
-    box(c,-1,-.39,2,.82,3,27,['#eee9d7','#c1bca9','#d9d5bf']);
-    box(c,-.67,-.20,.55,.45,18,30,['#888c7d','#4b5850','#616a60']);
-    panel(c,-.59,.26,35,.38,10,'#293d36'); panel(c,-.54,.27,42,.28,2,'#b8c7a5');
-    mug(c,-.46,.21,32); mug(c,.13,.10,30); mug(c,.43,.10,30,'#a4b087');
-    box(c,.68,-.17,.16,.16,7,30,['#d1ab73','#b08452','#c69c64']);
-  }
-  function partition(c) {
-    box(c,-.85,-.09,1.7,.18,31,0,['#acbf82','#8ea565','#9eb578']);
-    for(const x of [-.85,.8]) box(c,x,-.12,.06,.24,34,0,metal);
-    box(c,-.90,-.12,1.8,.23,2,34,metal);
-  }
-  function planter(c) {
-    box(c,-1.13,-.24,2.26,.48,15,0,['#edeedd','#bbbdaa','#d1d4bf']);
-    plane(c,-1.05,-.17,2.1,.34,16,'#77794e');
-    for(let i=0;i<9;i++) {
-      const p=iso(-.97+i*.23,0,19); rect(c,p[0]-3,p[1]-9,6,12,i%2?'#668349':'#7e9958');
-      rect(c,p[0]-1,p[1]-12,3,8,'#a0b976');
-    }
-  }
-  function rug(c) { plane(c,-1.2,-.9,2.4,1.8,.2,'#d2bea0','#a49679'); plane(c,-1.05,-.74,2.1,1.48,.4,'#c7b797','#b8a88a'); }
-  const furniture = { desk, chair, plant, bookcase, cabinet, server, whiteboard, sofa, table, coffee, partition, planter, rug };
-  const profiles = [
-    { id:'ce', name:'阿策', role:'团队协调', color:'#b28c57', dark:'#7e6244', hair:'#554936', lightHair:'#7a6748', skin:'#edc395', style:0 },
-    { id:'ma', name:'小码', role:'全栈开发', color:'#628ea8', dark:'#436378', hair:'#343e3c', lightHair:'#535c50', skin:'#e8bd8f', style:1 },
-    { id:'hui', name:'阿绘', role:'视觉设计', color:'#c48568', dark:'#945e48', hair:'#78543f', lightHair:'#9b7351', skin:'#f2cea2', style:2 },
-    { id:'xun', name:'小寻', role:'资料研究', color:'#a497b7', dark:'#756c87', hair:'#504637', lightHair:'#70624a', skin:'#e7bb87', style:3 },
-    { id:'shen', name:'阿审', role:'代码审查', color:'#84946b', dark:'#5a6d49', hair:'#4e493e', lightHair:'#77705c', skin:'#dba977', style:1 },
-    { id:'ce2', name:'小测', role:'质量测试', color:'#c1a157', dark:'#8a733e', hair:'#654c36', lightHair:'#96744c', skin:'#f1c89b', style:0 },
-  ];
-  // All six people share this silhouette. Palette/style/frame are the only variants.
-  function person(c, p, action, frame) {
-    const seated = action === 'work', walking = action === 'walk';
-    const bob = walking ? frame % 2 : 0;
-    const oy = seated ? -5 : -bob;
-    c.save(); c.translate(0,oy);
-    if (!seated) { rect(c,-8,0,18,3,'rgba(52,65,43,.16)'); }
-    const leg = walking ? [0,2,0,-2][frame%4] : 0;
-    rect(c,-6,-12,6,11+leg,'#374640'); rect(c,2,-12,6,11-leg,'#43534a');
-    rect(c,-7,-3+leg,8,4,C.ink); rect(c,2,-3-leg,9,4,C.ink);
-    if(seated) { rect(c,-6,-5,6,6,'#b7b3a0'); rect(c,1,-5,6,6,'#c6c0a6'); }
-    poly(c,[[-8,-26],[5,-27],[10,-23],[9,-11],[-7,-10],[-10,-20]],C.ink);
-    rect(c,-7,-25,13,14,p.color); rect(c,-7,-22,4,10,p.dark); rect(c,-2,-25,6,3,'#eee9d7');
-    rect(c,2,-23,3,10,p.color); rect(c,6,-21,3,7,p.dark);
-    if(action==='work') {
-      const k=frame%2; rect(c,6,-19-k,6,4,p.color); rect(c,10,-21-k,5,4,p.skin);
-      rect(c,-2,-16+k,9,3,p.color); rect(c,6,-18+k,5,3,p.skin);
-    } else if(action==='coffee') {
-      rect(c,6,-22,4,8,p.color); rect(c,8,-25,4,4,p.skin);
-      rect(c,10,-28,6,7,C.ink); rect(c,11,-27,5,5,'#e8e1c8'); rect(c,15,-26,3,3,'#cfc7ad');
-    } else {
-      rect(c,-10,-22,3,10,p.dark); rect(c,-10,-13+(walking?leg:0),3,4,p.skin);
-      rect(c,8,-21,3,9,p.color); rect(c,8,-12-(walking?leg:0),3,4,p.skin);
-    }
-    // Large expressive head, three-quarter view toward the desk.
-    poly(c,[[-9,-40],[-6,-44],[5,-44],[10,-39],[10,-29],[6,-25],[-5,-25],[-10,-30]],C.ink);
-    rect(c,-7,-39,15,11,p.skin); rect(c,-5,-29,11,3,p.skin);
-    rect(c,-8,-35,3,6,p.skin); rect(c,8,-34,3,4,p.skin);
-    rect(c,-7,-41,13,4,p.hair); rect(c,-9,-38,6,7,p.hair); rect(c,-7,-43,12,3,p.hair);
-    rect(c,-5,-42,8,2,p.lightHair); rect(c,-8,-37,3,9,p.hair);
-    rect(c,-4,-39,4,2,p.hair); rect(c,3,-40,5,3,p.hair);
-    if(p.style===1) { rect(c,-9,-40,5,3,p.hair); rect(c,-5,-45,8,3,p.hair); }
-    if(p.style===2) { rect(c,-12,-36,4,14,p.hair); rect(c,-11,-36,2,9,p.lightHair); rect(c,7,-39,3,6,p.hair); rect(c,-10,-29,3,2,p.color); }
-    if(p.style===3) { rect(c,-9,-44,16,4,p.dark); rect(c,-11,-40,22,3,p.color); rect(c,-4,-45,9,1,p.color); }
-    const blink = action==='idle' && frame===1;
-    rect(c,1,-35,2,blink?1:3,'#3e4136'); rect(c,6,-34,2,blink?1:3,'#3e4136');
-    rect(c,5,-28,3,1,'#b77959'); rect(c,8,-30,2,1,'#d8a278');
-    if(p.id==='shen') { line(c,-1,-36,4,-34,'#424e40'); line(c,5,-34,9,-33,'#424e40'); rect(c,-1,-35,5,4,'#414a3e'); rect(c,0,-34,3,2,'#b9c8af'); rect(c,6,-33,3,2,'#b9c8af'); }
-    c.restore();
-  }
-  class Atlas {
-    constructor() { this.cache = new Map(); }
-    get(type, variant='') {
-      const key=type+':'+variant;
-      if(this.cache.has(key)) return this.cache.get(key);
-      const bitmap=canvas(160,160), c=bitmap.getContext('2d'); c.imageSmoothingEnabled=false;
-      c.translate(80,132);
-      if(!furniture[type]) throw new Error('Unknown office asset: '+type);
-      furniture[type](c,variant);
-      const sprite={canvas:bitmap,ax:80,ay:132}; this.cache.set(key,sprite); return sprite;
-    }
-    person(index,action='idle',frame=0) {
-      const count=action==='walk'?4:2; frame=((frame%count)+count)%count;
-      const key='person:'+index+':'+action+':'+frame;
-      if(this.cache.has(key)) return this.cache.get(key);
-      const bitmap=canvas(48,64),c=bitmap.getContext('2d'); c.translate(22,54);
-      person(c,profiles[index],action,frame);
-      const sprite={canvas:bitmap,ax:22,ay:54}; this.cache.set(key,sprite); return sprite;
-    }
-    tile(index=0) {
-      const key='tile:'+index; if(this.cache.has(key)) return this.cache.get(key);
-      const bitmap=canvas(49,25),c=bitmap.getContext('2d');
-      const colors=['#c1cdb3','#c4cfb8','#bfccb2','#c7d1bb'];
-      poly(c,[[24,0],[48,12],[24,24],[0,12]],colors[index%4]);
-      line(c,0,12,24,0,'#d6dfcc'); line(c,24,0,48,12,'#d3ddc7');
-      line(c,0,12,24,24,'#aebfa2'); line(c,24,24,48,12,'#b0bfa4');
-      rect(c,15+(index%2)*8,13,1,1,'#b7c7a8');
-      const sprite={canvas:bitmap,ax:24,ay:0}; this.cache.set(key,sprite); return sprite;
-    }
-    draw(c,sprite,x,y,scale=1) { c.drawImage(sprite.canvas,Math.round(x-sprite.ax*scale),Math.round(y-sprite.ay*scale),sprite.canvas.width*scale,sprite.canvas.height*scale); }
-    portrait(target,index) { const c=target.getContext('2d'); c.imageSmoothingEnabled=false; c.clearRect(0,0,target.width,target.height); const s=this.person(index); c.drawImage(s.canvas,7,7,30,36,0,0,target.width,target.height); }
-    stats() { let bytes=0; for(const s of this.cache.values()) bytes+=s.canvas.width*s.canvas.height*4; return {sprites:this.cache.size,kib:Math.round(bytes/1024)}; }
-  }
-  O.Art={C,canvas,rect,line,poly,iso,plane,box,panel}; O.Atlas=Atlas; O.profiles=profiles;
-})(globalThis.PixelOffice = globalThis.PixelOffice || {});
diff --git a/design-prototypes/agent-office/index.html b/design-prototypes/agent-office/index.html
deleted file mode 100644
index 31629f9ba..000000000
--- a/design-prototypes/agent-office/index.html
+++ /dev/null
@@ -1,71 +0,0 @@
-<!doctype html>
-<html lang="zh-CN">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <meta name="theme-color" content="#f6f4eb">
-  <title>好好工作事务所 · 像素 AI 办公室</title>
-  <link rel="icon" href="data:,">
-  <link rel="stylesheet" href="office.css">
-  <script defer src="assets.js"></script>
-  <script defer src="simulation.js"></script>
-  <script defer src="renderer.js"></script>
-  <script defer src="app.js"></script>
-</head>
-<body>
-  <svg class="icon-definitions" aria-hidden="true"><defs>
-    <symbol id="i-office" viewBox="0 0 24 24"><path d="M4 21V7h9v14M13 11h7v10M1 21h22M7 10h3M7 14h3M7 18h3M16 14h1M16 18h1M6 7V3h5v4"/></symbol>
-    <symbol id="i-grid" viewBox="0 0 24 24"><path d="M3 3h7v7H3zM14 3h7v7h-7zM3 14h7v7H3zM14 14h7v7h-7z"/></symbol>
-    <symbol id="i-plus" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14"/></symbol>
-    <symbol id="i-minus" viewBox="0 0 24 24"><path d="M5 12h14"/></symbol>
-    <symbol id="i-clock" viewBox="0 0 24 24"><path d="M5 3h14v2h2v14h-2v2H5v-2H3V5h2zM12 7v6h4"/></symbol>
-    <symbol id="i-pause" viewBox="0 0 24 24"><path d="M7 5v14M16 5v14" stroke-width="4"/></symbol>
-    <symbol id="i-play" viewBox="0 0 24 24"><path d="m7 4 13 8-13 8z"/></symbol>
-    <symbol id="i-arrow" viewBox="0 0 24 24"><path d="M4 12h15M13 6l6 6-6 6"/></symbol>
-    <symbol id="i-close" viewBox="0 0 24 24"><path d="m6 6 12 12M6 18 18 6"/></symbol>
-    <symbol id="i-pointer" viewBox="0 0 24 24"><path d="M5 3v16l5-5 4 7 3-2-4-7h7z"/></symbol>
-    <symbol id="i-check" viewBox="0 0 24 24"><path d="m5 12 4 4L19 6"/></symbol>
-    <symbol id="i-coffee" viewBox="0 0 24 24"><path d="M4 8h12v10H4zM16 9h4v6h-4M2 21h17M7 2v3M12 2v3"/></symbol>
-    <symbol id="i-fit" viewBox="0 0 24 24"><path d="M8 3H3v5M16 3h5v5M21 16v5h-5M8 21H3v-5"/></symbol>
-  </defs></svg>
-  <div class="app-shell">
-    <header class="app-header">
-      <a class="brand" href="./index.html" aria-label="好好工作事务所首页">
-        <span class="brand-mark"><svg><use href="#i-office"/></svg></span>
-        <span><h1>好好工作事务所<span class="brand-period">.</span></h1><span class="brand-subtitle">A LITTLE OFFICE, BIG IDEAS</span></span>
-      </a>
-      <div class="header-right"><span class="online"><i></i>团队在线</span><span class="day">DAY <b id="day">01</b></span><span class="clock"><svg><use href="#i-clock"/></svg><time id="clock">09:41</time></span><button class="button library-button" id="open-library"><svg><use href="#i-grid"/></svg><span>素材图鉴</span></button></div>
-    </header>
-    <main>
-      <div class="workspace-header">
-        <div class="workspace-name"><span class="room-marker"></span><h2>办公室</h2><span class="workspace-slash">/</span><span class="workspace-subtitle">每个好想法，都有人在认真实现</span></div>
-        <div class="workspace-actions"><span class="demo-label">本地模拟 DEMO</span><button class="button primary" id="new-project"><svg><use href="#i-plus"/></svg>派发新任务</button></div>
-      </div>
-      <div class="workspace">
-        <section class="office-section" aria-label="像素办公室场景">
-          <div class="scene-heading"><div><span class="live-square"></span><strong id="scene-heading">灵感正在发生</strong><span class="scene-caption">WORKSPACE / 01</span></div><span class="scene-weather"><span class="pixel-sun" aria-hidden="true"></span>晴 · 适合一起做点什么</span></div>
-          <div class="stage" id="stage">
-            <canvas id="office" width="768" height="512" aria-label="六位 AI 成员的等距像素办公室。可通过右侧成员列表选择成员。">请使用支持 Canvas 的浏览器查看办公室。</canvas>
-            <div class="scene-note"><span class="note-dash"></span>小小的办公室，大大的可能。</div>
-            <div class="pause-overlay" id="pause-overlay" hidden><svg><use href="#i-pause"/></svg>办公室已暂停</div>
-          </div>
-          <div class="scene-toolbar"><span class="scene-hint"><svg><use href="#i-pointer"/></svg>点击小人，看看 TA 在忙什么</span><div class="view-controls"><button class="icon-button" id="zoom-out" aria-label="缩小场景"><svg><use href="#i-minus"/></svg></button><output id="zoom-label" aria-label="场景缩放">100%</output><button class="icon-button" id="zoom-in" aria-label="放大场景"><svg><use href="#i-plus"/></svg></button><span class="control-divider"></span><button class="icon-button" id="zoom-reset" aria-label="适应窗口"><svg><use href="#i-fit"/></svg></button></div></div>
-        </section>
-        <aside class="team-panel" aria-label="团队成员与动态">
-          <div class="panel-heading"><h2>今天的伙伴</h2><span class="count-label">6 位</span></div>
-          <div class="team-summary"><span><i class="status-dot"></i><span id="working-count">4</span> 位工作中</span><span id="resting-count">2 位准备中</span></div>
-          <div class="agent-list" id="agent-list"></div>
-          <section class="agent-detail" aria-label="选中成员详情"><div class="detail-heading"><span class="detail-label">正在关注</span><span id="detail-id">AGENTS 01</span></div><div class="detail-name"><strong id="detail-name">阿策</strong><span id="detail-role">团队协调</span><span id="detail-state" class="state-tag">构思中</span></div><p id="detail-task">把一个好想法拆成可执行的步骤。</p><div class="detail-meter"><span>当前任务</span><span id="detail-percent">0%</span></div><div class="meter"><span id="detail-progress"></span></div></section>
-          <section class="activity-section" aria-label="团队动态"><div class="activity-heading"><h3>办公室动态</h3><span class="activity-live">LIVE</span></div><ol class="activity-list" id="activity-list" aria-live="off"></ol></section>
-          <div class="team-footer"><svg><use href="#i-coffee"/></svg><span>好代码和好咖啡，都值得等待。</span></div>
-        </aside>
-      </div>
-      <section class="project-bar" aria-label="当前演示项目"><div class="project-info"><div class="project-heading"><span class="project-indicator"></span><h2 id="project-title">做一个有趣的 AI 工作台</h2><span class="project-kind">演示项目</span></div><div class="project-meta"><span id="project-status">团队正在协作</span><span class="meta-dot">·</span><span id="task-count">0 / 6 项任务完成</span></div></div><div class="project-progress"><div><span>项目进度</span><strong id="project-percent">0<span>%</span></strong></div><div class="meter project-meter"><span id="project-fill"></span></div><span class="progress-caption" id="progress-caption">一步一步，把想法变成作品。</span></div><div class="simulation-controls"><button class="button pause-button" id="toggle-pause" aria-pressed="false"><svg><use href="#i-pause"/></svg><span>暂停</span></button><div class="speed-control" role="group" aria-label="模拟速度"><button data-speed="1" aria-pressed="true">1×</button><button data-speed="2" aria-pressed="false">2×</button><button data-speed="4" aria-pressed="false">4×</button></div></div></section>
-    </main>
-    <footer class="app-footer"><span><span class="footer-pixel"></span>像素很小，想法很大。</span><span>6 位 AI 伙伴 · 本地模拟 · 无需联网</span></footer>
-  </div>
-  <dialog id="library" aria-labelledby="library-title"><div class="library-heading"><div><h2 id="library-title">办公室素材图鉴</h2><p>同一套积木，搭出整个办公室。</p></div><button class="icon-button" id="close-library" aria-label="关闭素材图鉴"><svg><use href="#i-close"/></svg></button></div><div class="library-content"><h3>家具与房间</h3><div class="asset-grid" id="asset-grid"></div><h3>一个人物模板，六位伙伴</h3><div class="portrait-grid" id="portrait-grid"></div><p class="library-footnote">家具重复使用同一缓存图块；人物通过发型、衣服换色和动作帧组合。场景、头像、图鉴共享素材，不加载任何图片。</p><output id="asset-stats"></output></div></dialog>
-  <div class="toast" id="toast" role="status" hidden></div>
-  <noscript><p class="noscript">请启用 JavaScript 来运行像素办公室。</p></noscript>
-</body>
-</html>
diff --git a/design-prototypes/agent-office/office.css b/design-prototypes/agent-office/office.css
deleted file mode 100644
index 4580d302b..000000000
--- a/design-prototypes/agent-office/office.css
+++ /dev/null
@@ -1,219 +0,0 @@
-:root {
-  color-scheme: light;
-  --paper: #f8f7f0; --paper-deep: #eeeee4; --ink: #344b3e; --muted: #5e6d55;
-  --line: #d9dfd1; --green: #4c6b48; --green-deep: #354f35; --green-soft: #e3eadb;
-  --scene: #e3e9dc; --white: #fffef9;
-  font-family: "Microsoft YaHei UI", "PingFang SC", "Noto Sans CJK SC", sans-serif;
-  font-size: 13px; color: var(--ink); background: #eeeee5;
-}
-* { box-sizing: border-box; }
-body { margin: 0; }
-button, a, input { -webkit-tap-highlight-color: transparent; }
-button { font: inherit; color: inherit; cursor: pointer; }
-button:disabled { cursor: default; opacity: .45; }
-a { color: inherit; text-decoration: none; }
-button, a { touch-action: manipulation; }
-button:focus-visible, a:focus-visible { outline: 2px solid var(--green); outline-offset: 4px; }
-::selection { color: var(--white); background: var(--green); }
-[hidden] { display: none !important; }
-svg { width: 18px; height: 18px; fill: none; stroke: currentColor; stroke-width: 1.7; stroke-linecap: square; stroke-linejoin: miter; flex-shrink: 0; }
-.icon-definitions { position: absolute; width: 0; height: 0; overflow: hidden; }
-.app-shell { max-width: 1600px; margin: 0 auto; padding: 0 38px; }
-.app-header { height: 100px; display: flex; justify-content: space-between; align-items: center; }
-.brand { display: flex; gap: 13px; align-items: center; }
-.brand-mark { background: var(--green); color: #f2efd6; width: 43px; height: 44px; display: grid; place-items: center; clip-path: polygon(4px 0,calc(100% - 4px) 0,calc(100% - 4px) 4px,100% 4px,100% calc(100% - 4px),calc(100% - 4px) calc(100% - 4px),calc(100% - 4px) 100%,4px 100%,4px calc(100% - 4px),0 calc(100% - 4px),0 4px,4px 4px); }
-.brand-mark svg { width: 29px; height: 29px; stroke-width: 1.5; }
-h1 { margin: 0 0 5px; font-size: 21px; font-weight: 700; letter-spacing: .035em; }
-.brand-period { color: #56694d; margin-left: 3px; }
-.brand-subtitle { font-size: 11px; letter-spacing: .19em; color: var(--muted); }
-.header-right { display: flex; align-items: center; gap: 24px; font-size: 12px; }
-.online { display: flex; align-items: center; gap: 7px; }
-.online i, .status-dot { background: #678652; width: 6px; height: 6px; display: inline-block; }
-.day { font-size: 11px; color: var(--muted); letter-spacing: .06em; }
-.day b { color: var(--ink); margin-left: 5px; font-size: 13px; }
-.clock { display: flex; gap: 7px; align-items: center; font-variant-numeric: tabular-nums; }
-.clock svg { width: 15px; height: 15px; }
-.button { display: inline-flex; align-items: center; justify-content: center; gap: 7px; min-height: 36px; padding: 7px 13px; border: 1px solid #cfd7c7; background: var(--paper); border-radius: 4px; transition: background 120ms; white-space: nowrap; }
-.button:hover:not(:disabled) { background: var(--green-soft); }
-.primary { background: var(--green); border-color: var(--green); color: var(--white); padding-inline: 15px; }
-.primary:hover:not(:disabled) { background: var(--green-deep); }
-main { background: var(--paper); border: 1px solid #cbd3c3; border-radius: 7px; overflow: hidden; }
-.workspace-header { min-height: 68px; padding: 15px 24px; display: flex; align-items: center; justify-content: space-between; gap: 14px; border-bottom: 1px solid var(--line); }
-.workspace-name { display: flex; align-items: center; gap: 12px; min-width: 0; }
-.room-marker { width: 11px; height: 12px; border: 2px solid var(--green); border-top-width: 4px; }
-h2 { font-size: 14px; margin: 0; font-weight: 700; }
-.workspace-slash { color: #56694d; margin: 0 2px; }
-.workspace-subtitle { font-size: 11px; color: var(--muted); }
-.workspace-actions { display: flex; align-items: center; gap: 15px; }
-.demo-label { color: #56694d; font-size: 11px; letter-spacing: .04em; }
-.workspace { display: grid; grid-template-columns: minmax(0,1fr) 270px; }
-.office-section { min-width: 0; background: var(--scene); display: flex; flex-direction: column; border-right: 1px solid var(--line); }
-.scene-heading { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 22px 25px 0; position: relative; z-index: 1; }
-.scene-heading > div { display: flex; align-items: center; gap: 7px; }
-.scene-heading strong { font-size: 12px; font-weight: 400; }
-.live-square { width: 5px; height: 5px; background: #80946f; }
-.scene-caption { font-size: 11px; color: #56694d; letter-spacing: .1em; margin-left: 6px; }
-.scene-weather { display: flex; gap: 7px; align-items: center; font-size: 11px; color: #56694d; }
-.pixel-sun { width: 9px; height: 9px; background: #bdad58; box-shadow: 0 -3px 0 -2px #a99643,0 3px 0 -2px #a99643,3px 0 0 -2px #a99643,-3px 0 0 -2px #a99643; }
-.stage { flex: 1; min-height: 465px; height: min(43vw,610px); position: relative; display: grid; place-items: center; overflow: hidden; }
-#office { position: absolute; inset: 0; min-width: 0; min-height: 0; display: block; width: 100%; height: 100%; object-fit: contain; image-rendering: pixelated; }
-.scene-note { position: absolute; bottom: 18px; left: 26px; font-size: 11px; color: #56694d; display: flex; align-items: center; gap: 8px; pointer-events: none; }
-.note-dash { width: 14px; height: 1px; background: #839577; }
-.pause-overlay { position: absolute; top: 18px; left: 50%; transform: translateX(-50%); display: flex; align-items: center; gap: 6px; background: var(--paper); border: 1px solid #b9c5af; border-radius: 3px; padding: 8px 12px; color: var(--green); font-size: 11px; }
-.pause-overlay svg { width: 13px; height: 13px; }
-.scene-toolbar { height: 48px; border-top: 1px solid #cfd8c6; display: flex; align-items: center; justify-content: space-between; gap: 8px; padding: 0 19px 0 25px; background: rgba(245,247,235,.48); }
-.scene-hint { color: #56694d; font-size: 11px; display: flex; align-items: center; gap: 7px; }
-.scene-hint svg { width: 13px; height: 13px; }
-.view-controls { display: flex; align-items: center; gap: 3px; }
-.icon-button { display: inline-grid; place-items: center; border: 0; background: transparent; width: 31px; height: 31px; border-radius: 3px; }
-.icon-button:hover:not(:disabled) { background: #d5dfca; }
-.icon-button svg { width: 16px; height: 16px; }
-#zoom-label { font-size: 11px; width: 37px; text-align: center; font-variant-numeric: tabular-nums; }
-.control-divider { width: 1px; height: 13px; background: #c3cdb9; margin: 0 5px; }
-.team-panel { padding: 23px 19px 0; display: flex; flex-direction: column; min-width: 0; }
-.panel-heading { display: flex; justify-content: space-between; align-items: center; }
-.count-label { font-size: 11px; color: var(--muted); }
-.team-summary { display: flex; flex-wrap: wrap; gap: 12px; font-size: 11px; color: var(--muted); margin-top: 10px; padding-bottom: 18px; border-bottom: 1px solid var(--line); }
-.team-summary > span:first-child { color: var(--green); }
-.team-summary .status-dot { width: 5px; height: 5px; margin-right: 5px; }
-.agent-list { padding: 11px 0 12px; display: grid; gap: 3px; }
-.agent-row { display: grid; grid-template-columns: 38px 1fr auto; width: 100%; gap: 9px; align-items: center; background: transparent; border: 1px solid transparent; padding: 5px 7px; border-radius: 4px; text-align: left; min-height: 49px; }
-.agent-row:hover { background: #eef0e4; }
-.agent-row[aria-pressed="true"] { background: #e8eddc; border-color: #ced9bd; }
-.avatar { width: 35px; height: 35px; background: #e3e7d8; border-radius: 4px; image-rendering: pixelated; }
-.agent-row:nth-child(2) .avatar { background: #dde7e9; }
-.agent-row:nth-child(3) .avatar { background: #f0e3d6; }
-.agent-row:nth-child(4) .avatar { background: #e6e0ed; }
-.agent-row:nth-child(5) .avatar { background: #e6e6dd; }
-.agent-row:nth-child(6) .avatar { background: #e9e5d4; }
-.agent-name { display: block; font-size: 12px; margin-bottom: 3px; }
-.agent-role { color: #56694d; display: block; font-size: 11px; }
-.agent-state { font-size: 11px; color: #56694d; display: flex; gap: 4px; align-items: center; }
-.agent-state::before { content: ''; width: 4px; height: 4px; background: currentColor; }
-.agent-state[data-state="waiting"],.agent-state[data-state="coffee"] { color: #56694d; }
-.agent-detail { padding: 14px 0 17px; border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); }
-.detail-heading { display: flex; justify-content: space-between; font-size: 11px; letter-spacing: .06em; color: var(--muted); }
-.detail-label { font-size: 11px; letter-spacing: 0; }
-.detail-name { display: flex; align-items: center; gap: 8px; margin-top: 11px; }
-.detail-name strong { font-size: 14px; }
-#detail-role { font-size: 11px; color: var(--muted); }
-.state-tag { margin-left: auto; font-size: 11px; padding: 3px 5px; background: #e7eadc; color: #56694d; border-radius: 2px; }
-#detail-task { font-size: 11px; line-height: 1.8; color: #56694d; min-height: 36px; margin: 9px 0 11px; }
-.detail-meter { display: flex; justify-content: space-between; font-size: 11px; color: var(--muted); margin-bottom: 7px; font-variant-numeric: tabular-nums; }
-.meter { height: 5px; background: #e2e6d9; overflow: hidden; }
-.meter > span { display: block; height: 100%; background: #829b66; width: 0; }
-.activity-section { padding-top: 17px; flex: 1; }
-.activity-heading { display: flex; align-items: center; justify-content: space-between; }
-h3 { font-size: 11px; margin: 0; font-weight: 400; }
-.activity-live { font-size: 11px; color: #56694d; letter-spacing: .08em; }
-.activity-list { padding: 0; margin: 11px 0; list-style: none; display: grid; gap: 10px; }
-.activity-list li { display: grid; grid-template-columns: 31px 1fr; gap: 7px; font-size: 11px; line-height: 1.7; }
-.activity-list time { color: #56694d; font-variant-numeric: tabular-nums; }
-.activity-list span { color: #56694d; }
-.team-footer { display: flex; align-items: center; justify-content: center; gap: 7px; color: #56694d; font-size: 11px; min-height: 45px; border-top: 1px solid var(--line); }
-.team-footer svg { width: 14px; height: 14px; }
-.project-bar { display: flex; align-items: center; justify-content: space-between; gap: 25px; padding: 22px 26px; border-top: 1px solid var(--line); background: #faf9f3; }
-.project-info { min-width: 0; }
-.project-heading { display: flex; align-items: center; gap: 9px; }
-.project-heading h2 { font-size: 13px; }
-.project-indicator { width: 10px; height: 10px; border: 2px solid #66854f; }
-.project-kind { font-size: 11px; color: #56694d; background: #edf0e4; padding: 3px 6px; border-radius: 3px; white-space: nowrap; }
-.project-meta { display: flex; gap: 8px; margin: 9px 0 0 19px; color: #56694d; font-size: 11px; }
-.meta-dot { color: #56694d; }
-.project-progress { width: clamp(140px,20vw,250px); }
-.project-progress > div:first-child { display: flex; justify-content: space-between; align-items: center; font-size: 11px; color: #56694d; margin-bottom: 6px; }
-.project-progress strong { color: var(--green); font-size: 18px; line-height: 20px; font-weight: 500; font-variant-numeric: tabular-nums; }
-.project-progress strong span { font-size: 11px; margin-left: 2px; }
-.project-meter { height: 7px; }
-.progress-caption { display: block; font-size: 11px; margin-top: 7px; color: #56694d; }
-.simulation-controls { display: flex; gap: 14px; align-items: center; }
-.pause-button { min-width: 74px; font-size: 11px; }
-.pause-button svg { width: 12px; height: 12px; }
-.speed-control { display: flex; border: 1px solid #d5dcca; border-radius: 4px; padding: 3px; }
-.speed-control button { background: transparent; border: 0; border-radius: 2px; width: 31px; height: 26px; font-size: 11px; }
-.speed-control button[aria-pressed="true"] { background: #e1e8d7; color: #405b34; }
-.speed-control button:hover { background: #ebeee3; }
-.app-footer { display: flex; justify-content: space-between; align-items: center; padding: 18px 2px 22px; font-size: 11px; color: #56694d; }
-.app-footer > span:first-child { display: flex; align-items: center; gap: 7px; }
-.footer-pixel { width: 6px; height: 6px; background: #8ea179; }
-dialog { padding: 0; width: min(660px,calc(100vw - 32px)); max-height: calc(100dvh - 48px); color: var(--ink); background: var(--paper); border: 1px solid #aab99b; border-radius: 7px; }
-dialog::backdrop { background: rgba(42,56,35,.45); }
-.library-heading { padding: 22px 24px; display: flex; justify-content: space-between; align-items: flex-start; border-bottom: 1px solid var(--line); }
-.library-heading h2 { font-size: 18px; }
-.library-heading p { color: var(--muted); font-size: 11px; margin: 8px 0 0; }
-.library-content { padding: 20px 24px 24px; }
-.library-content h3 { font-weight: 700; margin-bottom: 12px; }
-.asset-grid { display: grid; grid-template-columns: repeat(4,minmax(0,1fr)); gap: 1px; background: var(--line); border: 1px solid var(--line); margin-bottom: 25px; }
-.asset-tile { display: flex; flex-direction: column; align-items: center; padding: 4px 4px 10px; background: #f0f1e7; font-size: 11px; color: #56694d; }
-.asset-tile canvas { width: 100%; max-width: 110px; height: 92px; image-rendering: pixelated; object-fit: contain; }
-.portrait-grid { display: grid; grid-template-columns: repeat(6,minmax(0,1fr)); gap: 12px; text-align: center; font-size: 11px; }
-.portrait-grid canvas { display: block; width: 100%; height: auto; background: #e7eadc; image-rendering: pixelated; margin-bottom: 7px; }
-.library-footnote { font-size: 11px; color: var(--muted); line-height: 1.9; margin: 22px 0 12px; }
-#asset-stats { font-size: 11px; color: #56694d; }
-.toast { position: fixed; bottom: 25px; left: 50%; transform: translateX(-50%); background: #344c37; color: #56694d; padding: 12px 18px; border-radius: 4px; font-size: 12px; max-width: calc(100vw - 32px); z-index: 10; }
-.noscript { padding: 20px; text-align: center; }
-* { scrollbar-width: thin; scrollbar-color: #bbc7ad var(--paper); }
-@media (min-width: 1550px) { .stage { height: 625px; } }
-@media (max-width: 1150px) {
-  .app-shell { padding: 0 22px; } .header-right { gap: 15px; } .workspace { grid-template-columns: minmax(0,1fr) 242px; }
-  .team-panel { padding-inline: 14px; } .scene-caption,.scene-weather { display: none; } .stage { min-height: 460px; }
-  .project-bar { padding-inline: 20px; gap: 16px; } .simulation-controls { gap: 8px; } .project-kind { display: none; }
-}
-@media (max-width: 860px) {
-  .app-shell { padding: 0 16px; } .app-header { height: 84px; } h1 { font-size: 18px; } .brand-subtitle { font-size: 11px; }
-  .online,.day,.workspace-subtitle,.workspace-slash { display: none; } .workspace-header { padding: 13px 18px; min-height: 62px; }
-  .workspace { grid-template-columns: minmax(0,1fr); } .office-section { border-right: 0; } .stage { height: 65vw; min-height: 330px; }
-  .team-panel { padding: 20px; display: grid; grid-template-columns: 1fr 1fr; gap: 0 24px; border-top: 1px solid var(--line); }
-  .panel-heading,.team-summary { grid-column: 1; } .team-summary { padding-bottom: 10px; } .agent-list { grid-column: 1; grid-row: 3 / 5; }
-  .agent-detail { grid-column: 2; grid-row: 1 / 4; border-top: 0; padding-top: 0; align-self: start; }
-  .activity-section { grid-column: 2; grid-row: 4; padding-top: 4px; } .team-footer { grid-column: 1 / 3; }
-  .project-bar { flex-wrap: wrap; gap: 20px; } .project-info { flex: 1 1 50%; } .project-progress { flex: 1 1 30%; }
-  .simulation-controls { margin-left: auto; } .scene-weather { display: flex; } .app-footer > span:last-child { font-size: 11px; }
-}
-@media (max-width: 520px) {
-  .app-shell { padding: 0 10px; } .brand-mark { width: 35px; height: 36px; } .brand-mark svg { width: 24px; height: 24px; }
-  .brand { gap: 8px; } h1 { font-size: 16px; letter-spacing: 0; } .brand-subtitle { font-size: 11px; letter-spacing: .11em; }
-  .header-right { gap: 10px; } .clock { display: none; } .library-button { padding: 7px; min-height: 33px; font-size: 11px; }
-  .workspace-header { padding: 12px; } .workspace-actions { gap: 8px; } .demo-label { font-size: 11px; } .primary { font-size: 11px; padding-inline: 9px; min-height: 33px; }
-  .scene-heading { padding: 16px 14px 0; } .scene-heading strong { font-size: 11px; } .scene-weather { font-size: 11px; }
-  .stage { min-height: 280px; height: 76vw; } .scene-note { left: 15px; bottom: 12px; font-size: 11px; }
-  .scene-toolbar { padding: 0 8px 0 12px; } .scene-hint { font-size: 11px; gap: 4px; } .view-controls { gap: 0; }
-  .icon-button { width: 29px; height: 32px; } .control-divider { margin: 0 2px; } #zoom-label { width: 30px; font-size: 11px; }
-  .team-panel { padding: 18px 12px 0; gap: 0 13px; grid-template-columns: minmax(0,1.1fr) minmax(0,1fr); }
-  .team-summary { gap: 6px; font-size: 11px; } .agent-row { grid-template-columns: 29px 1fr auto; gap: 5px; padding: 5px 3px; }
-  .avatar { width: 28px; height: 32px; } .agent-name { font-size: 11px; } .agent-role { font-size: 11px; } .agent-state { font-size: 11px; }
-  .detail-name { flex-wrap: wrap; gap: 5px; } #detail-role { font-size: 11px; } .state-tag { margin-left: 0; } #detail-task { font-size: 11px; }
-  .detail-heading { font-size: 11px; } .detail-label { font-size: 11px; } .activity-list li { font-size: 11px; grid-template-columns: 27px 1fr; gap: 3px; }
-  .project-bar { padding: 18px 14px; gap: 16px; } .project-info { flex-basis: 100%; } .project-heading h2 { font-size: 12px; }
-  .project-progress { flex-basis: 40%; } .progress-caption { font-size: 11px; } .simulation-controls { gap: 6px; }
-  .pause-button { min-width: 58px; padding: 6px 8px; } .speed-control button { width: 26px; }
-  .app-footer { padding-block: 15px; font-size: 11px; } .app-footer > span:last-child { max-width: 155px; text-align: right; line-height: 1.6; }
-  .asset-grid { grid-template-columns: repeat(3,minmax(0,1fr)); } .portrait-grid { gap: 6px; } .library-content { padding: 16px; }
-}
-@media (prefers-reduced-motion: reduce) { *,*::before,*::after { transition: none !important; } }
-
-@media (max-width: 520px) {
-  .brand-subtitle { font-size: 10px; letter-spacing: 0; }
-  .demo-label { max-width: 65px; text-align: right; line-height: 1.4; }
-  .scene-weather { max-width: 110px; text-align: right; line-height: 1.5; }
-  .scene-hint { max-width: 170px; line-height: 1.5; }
-  .team-panel { display: block; padding: 18px 14px 0; }
-  .agent-list { grid-template-columns: repeat(2,minmax(0,1fr)); gap: 5px 9px; padding: 12px 0 16px; }
-  .agent-row { min-height: 58px; grid-template-columns: 30px 1fr; gap: 2px 6px; padding: 6px; }
-  .agent-row .avatar { grid-row: 1 / 3; }
-  .agent-state { grid-column: 2; margin-top: 3px; }
-  .agent-role { line-height: 1.5; }
-  .agent-name { font-size: 12px; }
-  .agent-detail { border-top: 1px solid var(--line); padding-top: 15px; }
-  .detail-name { gap: 9px; } .state-tag { margin-left: auto; }
-  #detail-task { min-height: 0; }
-  .activity-section { padding-top: 16px; }
-  .activity-list li { grid-template-columns: 37px 1fr; gap: 8px; }
-  .project-progress { flex: 1 1 100%; }
-  .simulation-controls { width: 100%; justify-content: flex-end; }
-  .app-footer { align-items: flex-start; gap: 12px; line-height: 1.6; }
-  .library-heading { padding: 18px 16px; }
-  .portrait-grid { grid-template-columns: repeat(3,minmax(0,1fr)); gap: 15px; }
-}
-
-@media (max-width: 370px) { .library-button span { display: none; } .brand-subtitle { font-size: 10px; } }
diff --git a/design-prototypes/agent-office/renderer.js b/design-prototypes/agent-office/renderer.js
deleted file mode 100644
index 2d9f98e47..000000000
--- a/design-prototypes/agent-office/renderer.js
+++ /dev/null
@@ -1,147 +0,0 @@
-/* Room caching and depth composition use the same atlas as all UI previews. */
-(function (O) {
-  'use strict';
-  const {C,canvas,rect,line,poly,iso,plane,box,panel}=O.Art;
-  const origin={x:340,y:155}, size={x:14,y:11};
-  const project=(x,y,z=0)=>{ const p=iso(x,y,z); return {x:origin.x+p[0],y:origin.y+p[1]}; };
-  function windowPanel(c,start,width,left=false) {
-    c.save(); if(left) c.scale(-1,1);
-    panel(c,start,-.015,36,width,47,'#aaa995','#808975');
-    panel(c,start+.08,.0,39,width-.16,43,'#f8f4e4');
-    panel(c,start+.16,.025,42,width-.32,37,'#a4ccda','#8bafba');
-    panel(c,start+.18,.03,44,width-.36,13,'#b9dce3');
-    for(let i=0;i<5;i++) {
-      const x=start+.19+i*(width-.4)/5,h=7+(i*7)%8;
-      panel(c,x,.035,43,(width-.4)/5+.01,h,i%2?'#91b9ad':'#a2c5b7');
-    }
-    for(let i=1;i<3;i++) panel(c,start+width*i/3-.025,.045,42,.075,37,'#f6f3e2','#b1c3bc');
-    panel(c,start+.16,.05,61,width-.32,2,'#d3e8e5');
-    box(c,start-.04,.04,width+.08,.18,3,35,['#f6f3e7','#cac9b5','#e0dfcc'],'#a5ad97');
-    c.restore();
-  }
-  function tinyTree(c,x,y,scale=1) {
-    c.save(); c.translate(x,y); c.scale(scale,scale);
-    rect(c,-2,0,4,14,'#91856a');
-    for(const [a,b,w,h,color] of [[-10,-13,20,17,'#9bab85'],[-14,-9,27,11,'#94a77b'],[-8,-17,17,11,'#b1bf96'],[-4,-20,10,8,'#b9c59e']]) rect(c,a,b,w,h,color);
-    rect(c,-10,-4,6,4,'#82986a'); c.restore();
-  }
-  function buildRoom(atlas) {
-    const result=canvas(768,512),c=result.getContext('2d'); c.imageSmoothingEnabled=false;
-    // Garden fragments and the offset foundation ground the cutaway room.
-    tinyTree(c,77,303,1.2); tinyTree(c,703,333,.9); tinyTree(c,664,378,.65);
-    for(const [x,y] of [[87,332],[663,408],[492,479],[160,393],[58,285]]) {
-      rect(c,x,y,2,3,'#b2bfa3'); rect(c,x+4,y-1,1,3,'#a8b798');
-    }
-    c.save(); c.translate(origin.x,origin.y);
-    poly(c,[iso(-.15,.0,-11),iso(14.5,.1,-11),iso(14.5,11.3,-11),iso(-.15,11.3,-11)],'rgba(91,107,73,.16)');
-    box(c,0,0,size.x,size.y,9,-9,['#c7d1b9','#a3ac94','#b2b9a2'],'#858f76');
-    for(let y=0;y<size.y;y++) for(let x=0;x<size.x;x++) { const p=iso(x,y); atlas.draw(c,atlas.tile((x*7+y*3)%4),p[0],p[1]); }
-    // Two walls, with low wooden skirting and a lighter top cap.
-    poly(c,[iso(0,0),iso(0,11),iso(0,11,99),iso(0,0,99)],'#e4e0cd','#8c927d');
-    poly(c,[iso(0,0),iso(14,0),iso(14,0,99),iso(0,0,99)],'#f0ecdc','#929781');
-    poly(c,[iso(0,0,99),iso(14,0,99),iso(14,-.18,103),iso(0,-.18,103),iso(-.18,0,103),iso(-.18,11,103),iso(0,11,99)],'#faf7e9','#afb29c');
-    poly(c,[iso(0,0,93),iso(0,11,93),iso(0,11,99),iso(0,0,99)],'#eeeada');
-    poly(c,[iso(0,0,92),iso(14,0,92),iso(14,0,99),iso(0,0,99)],'#fff9e7');
-    poly(c,[iso(.015,0,0),iso(.015,11,0),iso(.015,11,6),iso(.015,0,6)],'#b7996c','#a18c67');
-    panel(c,0,.01,0,14,6,'#c2a375','#a18c67');
-    windowPanel(c,1.0,2.6,true); windowPanel(c,4.8,2.6,true);
-    windowPanel(c,3.2,2.5); windowPanel(c,7.0,2.5);
-    // Warm notice board and a real-sized door occupy the remaining wall bays.
-    panel(c,10.25,.02,42,1.65,37,'#9e8055','#7e7557');
-    panel(c,10.33,.04,45,1.49,31,'#c8ac77');
-    for(const [x,z,color] of [[10.45,59,'#ece7cb'],[11.12,56,'#b3c39a'],[10.60,47,'#e2d29c']]) {
-      panel(c,x,.05,z,.48,10,color); const p=iso(x+.23,.06,z+9); rect(c,p[0],p[1],1,2,'#9c7354');
-    }
-    panel(c,12.5,.02,7,1.17,67,'#aa9473','#85836b');
-    panel(c,12.59,.035,8,.98,63,'#c1ab86');
-    panel(c,12.68,.05,35,.78,29,'#b8d3cc','#96b2a5');
-    const knob=iso(13.42,.06,30); rect(c,knob[0],knob[1],2,3,'#696f59');
-    // Pixel clock between the two rear windows.
-    const clock=iso(6.34,.04,80);
-    rect(c,clock[0]-8,clock[1]-7,16,15,'#81886e'); rect(c,clock[0]-6,clock[1]-9,12,19,'#81886e');
-    rect(c,clock[0]-6,clock[1]-6,12,13,'#f6f3dc'); rect(c,clock[0]-4,clock[1]-7,8,15,'#f6f3dc');
-    line(c,clock[0],clock[1],clock[0],clock[1]-5,'#535e4d'); line(c,clock[0],clock[1],clock[0]+4,clock[1]+2,'#535e4d');
-    const sign=iso(.7,.06,80);
-    rect(c,sign[0]-3,sign[1]-11,49,16,'#d9dbc0'); rect(c,sign[0]-2,sign[1]-10,47,14,'#687b56');
-    c.fillStyle='#f3efd6'; c.font='bold 7px sans-serif'; c.textAlign='left'; c.fillText('GOOD WORK',sign[0]+1,sign[1]);
-    // Sunlight is baked once, below furniture and characters.
-    poly(c,[iso(.15,2.0),iso(.15,4.2),iso(3.1,5.4),iso(3.1,3.2)],'rgba(255,247,204,.20)');
-    poly(c,[iso(3.5,.12),iso(5.5,.12),iso(7.4,2.1),iso(5.4,2.1)],'rgba(255,250,214,.19)');
-    c.restore(); return result;
-  }
-  class Renderer {
-    constructor(target,atlas,simulation) {
-      this.canvas=target; this.ctx=target.getContext('2d'); this.atlas=atlas; this.sim=simulation;
-      this.zoom=1; this.hover=-1; this.background=buildRoom(atlas); this.hits=[];
-      this.furniture=[
-        {type:'plant',x:.7,y:1.2}, {type:'bookcase',x:2.0,y:.65},
-        {type:'whiteboard',x:.65,y:5.25}, {type:'cabinet',x:.60,y:9.5},
-        {type:'coffee',x:10.8,y:.65}, {type:'server',x:13.15,y:1.35},
-        {type:'rug',x:2,y:8.9,depth:0}, {type:'sofa',x:1.25,y:7.5}, {type:'table',x:2.1,y:9.35},
-        {type:'plant',x:.65,y:10.35}, {type:'planter',x:11.8,y:10.0},
-        {type:'plant',x:13.1,y:4.4}, {type:'bookcase',x:13.25,y:6.3},
-        {type:'partition',x:4,y:6.05}, {type:'partition',x:7.2,y:6.05}, {type:'partition',x:10.4,y:6.05},
-      ];
-      for(const a of this.sim.agents) {
-        this.furniture.push({type:'desk',x:a.desk.x,y:a.desk.y,variant:a.index===2?'warm':''});
-        this.furniture.push({type:'chair',x:a.home.x,y:a.home.y,depth:a.home.x+a.home.y-.1});
-      }
-      for(const item of this.furniture) item.sprite=atlas.get(item.type,item.variant);
-    }
-    screen(x,y,z=0) { const p=project(x,y,z); return {x:384+(p.x-384)*this.zoom,y:280+(p.y-280)*this.zoom}; }
-    fromPointer(event) {
-      const r=this.canvas.getBoundingClientRect(),s=Math.min(r.width/768,r.height/512);
-      return {x:(event.clientX-r.left-(r.width-768*s)/2)/s,y:(event.clientY-r.top-(r.height-512*s)/2)/s};
-    }
-    hit(event) { const p=this.fromPointer(event); for(let i=this.hits.length-1;i>=0;i--) { const h=this.hits[i]; if(p.x>=h.x-17*this.zoom&&p.x<=h.x+18*this.zoom&&p.y>=h.y-52*this.zoom&&p.y<=h.y+7*this.zoom) return h.index; } return -1; }
-    bubble(c,x,y,text,color='#526a43') {
-      c.font='10px "Microsoft YaHei", sans-serif'; const width=Math.ceil(c.measureText(text).width)+16;
-      rect(c,x-width/2,y-19,width,17,'#839375'); rect(c,x-width/2-1,y-17,width+2,13,'#839375');
-      rect(c,x-width/2+1,y-18,width-2,15,'#fffdf1'); rect(c,x-width/2,y-16,width,11,'#fffdf1');
-      poly(c,[[x-3,y-2],[x+3,y-2],[x,y+2]],'#839375'); poly(c,[[x-2,y-3],[x+2,y-3],[x,y]],'#fffdf1');
-      c.fillStyle=color;c.textAlign='center';c.fillText(text,Math.round(x),Math.round(y-7));
-    }
-    render() {
-      const c=this.ctx,sim=this.sim,atlas=this.atlas;
-      c.imageSmoothingEnabled=false; c.clearRect(0,0,768,512); c.save();
-      c.translate(384,280);c.scale(this.zoom,this.zoom);c.translate(-384,-280);
-      c.drawImage(this.background,0,0);
-      const selected=sim.agents[sim.selected],sp=project(selected.x,selected.y);
-      c.save();c.translate(sp.x,sp.y+1);plane(c,-.47,-.43,.94,.86,0,'rgba(244,244,197,.4)','#829c61'); c.restore();
-      const items=this.furniture.map(item=>({...item,depth:item.depth===undefined?item.x+item.y:item.depth}));
-      for(const a of sim.agents) items.push({type:'person',x:a.x,y:a.y,agent:a,depth:a.x+a.y+.05});
-      items.sort((a,b)=>a.depth-b.depth);
-      this.hits=[];
-      for(const item of items) {
-        const p=project(item.x,item.y);
-        if(item.type==='person') {
-          const a=item.agent,frame=a.action==='walk'?Math.floor(sim.time*7+a.index)%4:a.action==='idle'?(Math.floor(sim.time+a.index*1.7)%6===0?1:0):Math.floor(sim.time*4+a.index)%2;
-          atlas.draw(c,atlas.person(a.index,a.action,frame),p.x,p.y);
-          this.hits.push({...this.screen(a.x,a.y),index:a.index});
-        } else atlas.draw(c,item.sprite,p.x,p.y);
-      }
-      // Name plates are a display layer; all hit tests target real actor positions.
-      for(const a of sim.agents) {
-        const p=project(a.x,a.y),active=a.index===sim.selected||a.index===this.hover;
-        c.font='8px "Microsoft YaHei", sans-serif'; c.textAlign='center';
-        const name=a.name,width=24;
-        rect(c,p.x-width/2,p.y+5,width,12,active?'#506947':'rgba(249,249,232,.90)');
-        c.fillStyle=active?'#fffce8':'#5c7050'; c.fillText(name,p.x,p.y+14);
-      }
-      for(const a of sim.agents) {
-        const selected=a.index===sim.selected;
-        const show=selected||(a.action==='work'&&Math.floor(sim.time/4+a.index)%3===0)||(a.action==='coffee');
-        if(!show)continue;
-        const p=project(a.x,a.y),status=sim.status(a.index);
-        const text=a.action==='coffee'?'补充一点灵感':status.label+(a.action==='work'?'...':'');
-        this.bubble(c,p.x+4,p.y-53,text,selected?'#46653c':'#677a58');
-      }
-      // Shared coffee corner: tiny steam frames animate without rebuilding furniture.
-      const coffee=project(10.55,.95,50),phase=Math.floor(sim.time*3)%3;
-      line(c,coffee.x,coffee.y-3-phase,coffee.x+1,coffee.y-7-phase,'#ecebd6');
-      if(sim.finished) { const p=project(7,4,82); this.bubble(c,p.x,p.y,'好想法，完成了！'); }
-      c.restore();
-    }
-  }
-  O.Renderer=Renderer;
-})(globalThis.PixelOffice = globalThis.PixelOffice || {});
diff --git a/design-prototypes/agent-office/simulation.js b/design-prototypes/agent-office/simulation.js
deleted file mode 100644
index e69fa72e8..000000000
--- a/design-prototypes/agent-office/simulation.js
+++ /dev/null
@@ -1,94 +0,0 @@
-/* Pure, deterministic simulation: explicit time in, structured team state out. */
-(function (O) {
-  'use strict';
-  const desks = [[4,3.5],[7.2,3.5],[10.4,3.5],[4,6.7],[7.2,6.7],[10.4,6.7]];
-  const definitions = [
-    { title:'拆解需求', doing:'规划中', text:'把好想法拆成可执行的小任务，安排大家的分工。', duration:18, deps:[] },
-    { title:'开发功能', doing:'开发中', text:'搭建工作台，编写交互逻辑，让每个小功能运转起来。', duration:48, deps:[0] },
-    { title:'设计界面', doing:'设计中', text:'打磨布局、颜色与像素细节，给好想法一个好看的样子。', duration:35, deps:[0] },
-    { title:'资料研究', doing:'研究中', text:'收集参考，梳理技术方案，把发现分享给伙伴。', duration:30, deps:[] },
-    { title:'代码审查', doing:'审查中', text:'和开发伙伴一起检查实现，找出可以做得更好的地方。', duration:23, deps:[1,2,3] },
-    { title:'质量验证', doing:'测试中', text:'验证关键交互和边界情况，确保作品可以放心交付。', duration:22, deps:[4] },
-  ];
-  const titles=['做一个有趣的 AI 工作台','为小团队设计一个灵感收集器','做一个会照顾番茄钟的助手','把今天的好想法变成小网站'];
-  const distance=(a,b)=>Math.hypot(a.x-b.x,a.y-b.y);
-  class Simulation {
-    constructor() {
-      this.time=0; this.speed=1; this.paused=false; this.projectNumber=0; this.selected=1; this.events=[];
-      this.agents=O.profiles.map((p,i)=>({ ...p,index:i,desk:{x:desks[i][0],y:desks[i][1]},home:{x:desks[i][0],y:desks[i][1]+.96},x:desks[i][0],y:desks[i][1]+.96,action:'idle',route:[],destination:'home',nextBreak:8+i*3,coffeeUntil:0 }));
-      this.startProject(true);
-    }
-    get active() { return this.tasks.some(t=>t.elapsed<t.duration); }
-    get progress() { return this.tasks.reduce((n,t)=>n+t.elapsed/t.duration,0)/this.tasks.length; }
-    get doneCount() { return this.tasks.filter(t=>t.elapsed>=t.duration).length; }
-    get clock() { const m=9*60+41+Math.floor(this.time/3); return String(Math.floor(m/60)%24).padStart(2,'0')+':'+String(m%60).padStart(2,'0'); }
-    log(text) { this.events.unshift({time:this.clock,text}); if(this.events.length>5) this.events.length=5; }
-    startProject(initial=false) {
-      if(!initial&&this.active) return false;
-      this.title=titles[this.projectNumber%titles.length]; this.projectNumber++;
-      this.tasks=definitions.map(d=>({...d,deps:[...d.deps],elapsed:0}));
-      if(initial) { this.tasks[0].elapsed=18; this.tasks[1].elapsed=8; this.tasks[2].elapsed=9; this.tasks[3].elapsed=19; }
-      this.finished=false;
-      this.log(initial?'阿策已拆解需求，伙伴们开始协作':'新任务已派发，阿策开始拆解需求');
-      if(initial) { this.log('小寻整理了第一批参考资料'); this.log('阿绘和小码开始并行设计、开发'); }
-      this.refreshActions(); return true;
-    }
-    ready(i) { const t=this.tasks[i]; return t.elapsed<t.duration&&t.deps.every(d=>this.tasks[d].elapsed>=this.tasks[d].duration); }
-    atHome(a) { return distance(a,a.home)<.02; }
-    coffeeRoute(a) {
-      const lane=a.desk.y+1.9;
-      return [{...a.home},{x:a.home.x,y:lane},{x:12.15,y:lane},{x:12.15,y:1.9},{x:10.8,y:1.9}];
-    }
-    goCoffee(a) { a.destination='coffee'; a.route=this.coffeeRoute(a).slice(1); a.action='walk'; }
-    goHome(a) { a.destination='home'; a.route=this.coffeeRoute(a).slice(0,-1).reverse(); a.action='walk'; }
-    move(a,dt) {
-      let remaining=dt*1.5;
-      while(a.route.length&&remaining>0) {
-        const target=a.route[0],d=distance(a,target);
-        if(d<=remaining) { a.x=target.x; a.y=target.y; remaining-=d; a.route.shift(); }
-        else { a.x+=(target.x-a.x)/d*remaining; a.y+=(target.y-a.y)/d*remaining; remaining=0; }
-      }
-      if(!a.route.length) {
-        if(a.destination==='coffee') { a.action='coffee'; a.coffeeUntil=this.time+5; }
-        else { a.action='idle'; a.nextBreak=this.time+14+a.index*2; }
-      }
-    }
-    refreshActions() {
-      for(const a of this.agents) if(!a.route.length&&this.atHome(a)) a.action=this.ready(a.index)?'work':'idle';
-    }
-    tick(dt) {
-      if(this.paused||!Number.isFinite(dt)||dt<=0) return;
-      // Substeps preserve dependency ordering even for a long caller-supplied step.
-      let remaining=dt*this.speed;
-      while(remaining>0) { const step=Math.min(.1,remaining); this.step(step); remaining-=step; }
-    }
-    step(dt) {
-      this.time+=dt;
-      for(const a of this.agents) {
-        const t=this.tasks[a.index];
-        if(a.route.length) { this.move(a,dt); continue; }
-        if(a.action==='coffee') {
-          if(this.ready(a.index)||this.time>=a.coffeeUntil) this.goHome(a);
-          continue;
-        }
-        if(this.atHome(a)&&this.ready(a.index)) {
-          a.action='work'; const before=t.elapsed; t.elapsed=Math.min(t.duration,t.elapsed+dt);
-          if(before<t.duration&&t.elapsed>=t.duration) { this.log(a.name+'完成了'+t.title); a.action='idle'; a.nextBreak=this.time+2+a.index; }
-        } else {
-          a.action='idle';
-          const coffeeBusy=this.agents.some(other=>other!==a&&other.destination==='coffee'&&(other.route.length||other.action==='coffee'));
-          if(this.time>=a.nextBreak&&!coffeeBusy) this.goCoffee(a);
-        }
-      }
-      if(!this.active&&!this.finished) { this.finished=true; this.log('作品完成！大家一起把想法变成了现实'); }
-    }
-    status(index) {
-      const a=this.agents[index],t=this.tasks[index];
-      if(a.action==='walk') return {label:a.destination==='home'?'回工位':'走动中',state:'walking'};
-      if(a.action==='coffee') return {label:'咖啡时间',state:'coffee'};
-      if(a.action==='work') return {label:t.doing,state:'working'};
-      return {label:t.elapsed>=t.duration?'已完成':'准备中',state:t.elapsed>=t.duration?'done':'waiting'};
-    }
-  }
-  O.Simulation=Simulation; O.desks=desks;
-})(globalThis.PixelOffice = globalThis.PixelOffice || {});
diff --git a/design-prototypes/agent-office/simulation.test.cjs b/design-prototypes/agent-office/simulation.test.cjs
deleted file mode 100644
index 83746032f..000000000
--- a/design-prototypes/agent-office/simulation.test.cjs
+++ /dev/null
@@ -1,78 +0,0 @@
-// Run from any directory: node --test simulation.test.cjs
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const path = require('node:path');
-const vm = require('node:vm');
-const context = vm.createContext({});
-for (const name of ['assets.js', 'simulation.js']) {
-  vm.runInContext(fs.readFileSync(path.join(__dirname, name), 'utf8'), context, { filename: name });
-}
-const { Simulation } = context.PixelOffice;
-const snapshot = sim => JSON.stringify({ time: sim.time, tasks: sim.tasks, agents: sim.agents, events: sim.events });
-
-test('paused time freezes tasks, actor motion and the event log', () => {
-  const sim = new Simulation(); sim.tick(10); sim.paused = true;
-  const before = snapshot(sim); sim.tick(120); assert.equal(snapshot(sim), before);
-  sim.paused = false; sim.tick(1); assert.ok(sim.time > 10);
-});
-
-test('speed scales explicit elapsed time exactly once', () => {
-  const normal = new Simulation(), fast = new Simulation(); fast.speed = 4;
-  normal.tick(4); fast.tick(1);
-  assert.ok(Math.abs(normal.time - fast.time) < 1e-8);
-  for (let i = 0; i < 6; i++) assert.ok(Math.abs(normal.tasks[i].elapsed - fast.tasks[i].elapsed) < 1e-8);
-});
-
-test('invalid time input cannot corrupt simulation state', () => {
-  const sim = new Simulation(), before = snapshot(sim);
-  for (const dt of [NaN, Infinity, -1, 0]) sim.tick(dt);
-  assert.equal(snapshot(sim), before);
-});
-
-test('dependent work starts only after handoff, and only at the desk', () => {
-  const sim = new Simulation();
-  for (let frame = 0; frame < 1600; frame++) {
-    const before = sim.tasks.map(t => t.elapsed); sim.tick(.1);
-    for (const actor of sim.agents) {
-      const t = sim.tasks[actor.index];
-      if (t.elapsed > before[actor.index]) {
-        assert.ok(t.deps.every(i => sim.tasks[i].elapsed === sim.tasks[i].duration));
-        assert.ok(Math.hypot(actor.x - actor.home.x, actor.y - actor.home.y) < .02);
-      }
-    }
-  }
-  assert.equal(sim.doneCount, 6); assert.equal(sim.progress, 1);
-});
-
-test('coffee breaks stay inside the office, reserve one spot, and return', () => {
-  const sim = new Simulation(); let sawWalk = false, sawCoffee = false, sawReturn = false;
-  for (let frame = 0; frame < 2200; frame++) {
-    sim.tick(.1);
-    const reserved = sim.agents.filter(a => a.destination === 'coffee' && (a.route.length || a.action === 'coffee'));
-    assert.ok(reserved.length <= 1);
-    for (const a of sim.agents) {
-      assert.ok(a.x >= 0 && a.x <= 14 && a.y >= 0 && a.y <= 11);
-      sawWalk ||= a.action === 'walk'; sawCoffee ||= a.action === 'coffee';
-      sawReturn ||= a.destination === 'home' && a.route.length > 0;
-    }
-  }
-  assert.ok(sawWalk && sawCoffee && sawReturn); assert.equal(sim.doneCount, 6);
-});
-
-test('duplicate dispatch is rejected, a finished project can start fresh', () => {
-  const sim = new Simulation(), before = snapshot(sim);
-  assert.equal(sim.startProject(), false); assert.equal(snapshot(sim), before);
-  sim.tick(240); assert.equal(sim.finished, true); assert.equal(sim.active, false);
-  assert.equal(sim.startProject(), true); assert.equal(sim.projectNumber, 2);
-  assert.equal(sim.progress, 0); assert.equal(sim.finished, false);
-  assert.equal(sim.startProject(), false); sim.tick(240);
-  assert.equal(sim.doneCount, 6); assert.equal(sim.finished, true);
-});
-
-test('a large explicit time step still resolves the entire dependency chain', () => {
-  const sim = new Simulation(); sim.tick(300);
-  assert.equal(sim.doneCount, 6);
-  assert.ok(sim.tasks.every(t => t.elapsed === t.duration));
-  assert.equal(sim.events.filter(e => e.text.includes('作品完成')).length, 1);
-});
diff --git a/design-prototypes/agent-office/surface.md b/design-prototypes/agent-office/surface.md
deleted file mode 100644
index 410cae655..000000000
--- a/design-prototypes/agent-office/surface.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# 办公室演示页
-
-模式：Experience。
-
-首先看到可活动的等距像素办公室，其次读取成员与当前项目。重点是角色的工作动作、任务状态变化和统一的像素材质。全页只保留有实际行为的控件。演示数据标识位于顶部。
diff --git a/docs/channels.md b/docs/channels.md
index abc7a1114..ddd885836 100644
--- a/docs/channels.md
+++ b/docs/channels.md
@@ -1,12 +1,269 @@
-# WhatsApp Channels
+# Messaging Channels
+
+ACECode can talk to you through instant-messaging apps. **QQ** (official bot, API
+v2), **WeChat** (Tencent iLink bot), **Feishu / Lark**, **DingTalk**, **Telegram**
+(Bot API), **Discord** and **LINE** (Messaging API) are built into the daemon and
+configured in **Settings > Integrations > Messaging channels** in Desktop or the
+local Web UI. **WhatsApp** is configured in a terminal; see [WhatsApp](#whatsapp).
+
+## Built-in Channels
+
+All seven channels are native C++: transports in `src/adapters/im/<platform>/`,
+routing, access and storage in `src/host/channels/core/`. The platform list,
+credential fields and identity rules live in one table
+(`src/host/channels/core/platforms.cpp`). Every platform except LINE connects
+outward from this computer (WebSocket or long polling), so no public address,
+webhook server or Node/Python runtime is needed. LINE only delivers to a public
+HTTPS address; see below. All HTTP and WebSocket traffic follows ACECode's proxy
+settings.
+
+### Setup
+
+The page shows the platforms as cards in two columns. Each card has one button:
+**Connect** while the platform is off, **Disconnect** while it is on. Both take
+effect immediately; there is no separate Save. A card shows only a one-line
+status (connecting, connected with the bot's name, reconnecting, failed, or held by
+another ACECode process) and any pending approval requests. Details such as
+failure reasons, group privacy mode, held QQ outputs, bindings and send counts are
+written to the daemon log (`<data dir>/logs/daemon-<date>.log`, lines tagged
+`[channels/<platform>]`) instead of the page. A failed card
+offers **Fix**, which reopens the connect step. A configured card offers
+**Manage** to change the bot or revoke the owner and approved contacts.
+
+**Connect** on a platform that has no credentials or no owner yet opens a
+three-step dialog: set up the bot, connect, and set the owner. When credentials
+and owner both exist, **Connect** connects right away without the dialog.
+
+**QQ.** The first step shows a QR code as soon as it opens; scan it with mobile
+QQ. ACECode requests a bind task from Tencent's bot binding service (the flow
+used by the official connector, with source `acecode`), shows the bind page as a
+QR code, refreshes expired codes automatically and gives up after ten minutes. On
+success the AppID and the AppSecret, decrypted locally with a one-time AES-256-GCM
+key, are saved and QQ is switched on. The person who scanned becomes the owner
+when the service reports them; otherwise the first person to message the bot
+privately within ten minutes becomes the owner, and after that window approving
+the first private request does. Cancelling or failing leaves the existing
+configuration unchanged.
+
+**Enter AppID / AppSecret manually** in the same step accepts the credentials of a
+bot from QQ Open Platform. They are verified by exchanging an access token before
+saving. Bots without personal verification can only be used by their
+administrator and can only join groups the administrator owns; the dialog says
+so when it finishes.
+
+**Telegram.** The first step explains how to create a bot with @BotFather; paste
+its token and it is verified with `getMe` before saving. The owner step creates a
+one-time `https://t.me/<bot>?start=<code>` link valid for ten minutes and shows it
+as a QR code. Whoever opens it and taps **Start** becomes the owner. Scan the QR
+code with the phone's camera app; Telegram's own scanner only links devices and
+cannot read it. On a computer where Telegram is signed in, click the link or use
+**Copy link** instead. With privacy mode on (the BotFather default) groups deliver
+only @mentions, replies to the bot and commands, which matches the mention-only
+group behavior; with it off the bot sees every group message but still handles
+only @mentions. If the bot has a webhook, polling is blocked; the connect step
+offers **Remove webhook and connect**, after explaining that the service
+currently receiving the webhook stops getting messages.
+
+**WeChat.** The first step shows a QR code from Tencent's iLink bot service;
+scan it with WeChat and confirm on the phone. The WeChat account that scanned
+becomes the owner automatically and is the only one who can talk to the bot;
+WeChat bots have private chats only. The bot token is saved locally. When the
+service reports the login has expired, the card shows a failure and the dialog
+asks you to scan again. Media goes through Tencent's CDN, encrypted with
+AES-128-ECB.
+
+**Feishu / Lark.** Create a custom app on the Feishu Open Platform
+(`open.feishu.cn/app`, or `open.larksuite.com/app` for Lark), add the Bot
+capability, grant `im:message`, `im:message:send_as_bot`,
+`im:message.p2p_msg:readonly`, `im:message.group_at_msg:readonly` and
+`im:resource`, then enter the App ID and App Secret (and pick Feishu or Lark).
+They are verified with a tenant access token before saving. ACECode then opens
+the long connection; only while it is online does Feishu let you save **Receive
+events through persistent connection** in **Events & Callbacks**, so the connect
+step lists what to finish there: save that mode, add the event
+`im.message.receive_v1` and publish a version that includes you.
+
+**DingTalk.** Create an internal app on the DingTalk Open Platform
+(`open-dev.dingtalk.com`), add the Robot capability with **Stream** message
+mode, grant the internal robot send-message permission, publish it, and enter the
+Client ID and Client Secret. They are verified with an access token. Replies go to
+the reply address carried by each incoming message while it is valid, and through
+the robot API afterwards, so replies typed in Desktop or sent after a restart are
+still delivered.
+
+**Discord.** Create an application in the Discord Developer Portal, copy the bot
+token from the **Bot** page and turn on **Message Content Intent** there. The
+token is verified with `/users/@me` and `/applications/@me`; the connect step then
+shows an invite link with the permissions the bot needs. Direct messages and
+@mentions (or replies to the bot) in server channels and threads are handled.
+
+**LINE.** Create an official account in LINE Official Account Manager, enable the
+Messaging API, then copy the **Channel ID** and **Channel secret** from LINE
+Developers; ACECode issues short-lived access tokens from them (a long-lived token
+can be pasted instead). In the console turn on **Use webhook** and turn off
+auto-reply and greeting messages. LINE can only deliver to a public HTTPS address,
+so the daemon starts a separate listener bound to `127.0.0.1` that serves only
+the webhook, a health check and outgoing media; every request is checked against
+the channel secret signature. Leave **Public address** empty to let ACECode start
+a Cloudflare quick tunnel (`cloudflared`, install with
+`winget install --id Cloudflare.cloudflared`) or enter your own HTTPS address that
+forwards to that listener. On every connect ACECode sets LINE's webhook URL to the
+current address. Never point a tunnel at the daemon's own port: local requests
+skip token checks there.
+
+**Feishu, DingTalk, Discord and LINE owners.** After connecting, the owner step
+shows a 6-digit code. Send exactly those digits to the bot in a private chat; the
+sender becomes the owner and the message is not passed to a session. Codes expire
+after ten minutes and work once; ten wrong guesses while a code is outstanding
+invalidate it.
+
+### Access
+
+Everyone is denied by default. Each platform has at most one owner.
+
+- An unknown private sender gets a pairing notice. The request appears on the
+  platform's card, Desktop shows a system notification when its window is not
+  focused, and the request expires after ten minutes. Approval applies from the
+  contact's next message. Approving a private user while there is no owner makes
+  them the owner.
+- A group must be approved first. In an approved group only messages that
+  @mention the bot are handled (on Telegram and Discord a reply to the bot also
+  counts), and each member is approved separately. QQ member identities are
+  scoped per group. On Discord each server channel or thread counts as a group;
+  WeChat has no groups.
+- Revoking access stops processing that contact immediately and aborts the
+  running turn of their sessions.
+- Switching to a different bot clears the owner and approvals on QQ, WeChat,
+  Feishu, DingTalk and LINE, because their user ids differ per bot or app; on
+  Telegram and Discord user ids are global and are kept.
+
+### Conversations And Commands
+
+Each private chat, and each member within a group, is bound to exactly one
+ACECode session. The first accepted message creates a no-workspace session with
+`default` permissions; it never inherits the daemon's dangerous or
+skip-confirmation mode. Bindings survive restarts. A session is bound to at most
+one chat: resuming it from another chat, even on the other platform, moves the
+binding and tells the previous chat. If a bound session was permanently deleted,
+the bot says so and suggests `/new` or `/sessions` instead of silently starting a
+new one.
+
+| Command | Effect |
+| --- | --- |
+| `/help` | Commands available to the sender |
+| `/status` | Platform, session, location, model, busy state, pending approvals and questions |
+| `/stop` | Stop the current turn |
+| `/new` | New session in the bound session's workspace, or a no-workspace session |
+| `/sessions`, `/sessions more`, `/sessions search <text>` | Numbered list of sessions to switch to |
+| `/resume <number or session id>` | Switch the binding; numbers refer to the latest list |
+| `/model [name]` | List saved models, or switch the bound session's model from the next turn |
+| `/approve <id>`, `/deny <id>` | Decide a permission request once |
+| `/aq ...` | Answer an AskUserQuestion, with the same syntax as `/rc` |
+
+Commands are never sent to the model. While a session is busy `/new` and
+`/resume` are refused; other commands run at once and plain messages queue as
+usual. The owner can switch to any normal, unarchived session, including other
+workspaces and no-workspace sessions. Other contacts only see sessions created
+from their own chat. Archived and subagent sessions are never listed. Text that
+starts with `/` is expanded as an opencode or skill command exactly like Web
+input. Plain text sent while a question is pending is handed to that question as
+an interjection.
+
+### Output And Media
+
+The assistant text of each turn and turn errors are sent; tool progress is not.
+Long text is split below each platform's limit. QQ merges one turn's text into as
+few messages as possible and uses Markdown with a plain-text fallback. Telegram
+converts Markdown to Telegram HTML and shows "typing" while the session is busy.
+Replies to input typed in Desktop are sent to the bound chat as well. Permission
+requests list `/approve` and `/deny` ids and questions use `/aq`; the first
+answer, from the chat or Desktop, wins and the other side is told it was handled.
+Send failures are counted per binding and written to the daemon log. A send
+whose outcome is unknown is never retried automatically.
+
+QQ passive replies quote the incoming message (private chats: 4 replies within 60
+minutes; groups: 5 within 5 minutes). Beyond that window ACECode sends an active
+message; if that is refused too, the output is held (up to 20 per chat, in memory)
+and delivered before the contact's next message is handled.
+
+Feishu sends Markdown as rich text (`post`) and falls back to plain text;
+DingTalk sends Markdown; Discord sends Markdown as is, below 2000 characters per
+message, never pinging @everyone; WeChat and LINE send plain text. LINE uses the
+free reply token while it is fresh and push messages otherwise; when the push
+quota is used up, outputs are held until the contact's next message, like QQ.
+
+Images and files up to 25 MiB, and within the platform download limit (20 MB on
+Telegram), are imported into the session's attachments. QQ voice messages use the
+platform's recognized text. Video, stickers and voice without text get a clear
+"not supported" reply. Images and files produced by the session are sent as
+native media: on Telegram images over 10 MB go as files and files over 50 MB are
+not sent; on QQ files over 20 MiB are replaced by a text notice. LINE bots
+cannot send files at all, so a text notice is sent instead; LINE images are served
+to LINE through the listener's media address.
+
+### Runtime And Storage
+
+Only the daemon hosts these channels: Desktop's shared daemon or a standalone
+`acecode daemon`. The TUI and headless modes never do. Whether channels stay
+online after Desktop quits follows **Settings > General > Continue running the
+background process after exiting ACECode**. Each platform account has its own OS
+file lock (`owner.lock`); a second process stays in standby, shows that the bot
+is held by another ACECode on the card (the owning PID goes to the log) and takes
+over after that process exits.
+
+Data lives under `<data dir>/channels/<platform>/` (`qq`, `weixin`, `feishu`,
+`dingtalk`, `telegram`, `discord`, `line`).
+`config.json` holds the on/off state, credentials, owner and approvals; it has
+owner-only permissions and is written only through the settings API. `state.json`
+holds bindings, the sessions created per chat, the last 4096 message receipts and
+the Telegram update offset and the WeChat polling cursor. A corrupt file blocks that platform with an error
+instead of being reset. Credentials and QR payloads are never logged; the API
+returns only their last four characters. The settings API and its WebSocket events
+accept direct local clients only (`docs/daemon-api.md`, section 19).
+
+### Limits
+
+QQ guild channels, Telegram webhooks, hosted bots, buttons, streamed message
+editing and voice replies are not supported. Feishu and DingTalk apps are set up
+by hand (their scan-to-create flows are not used). Cloudflare quick tunnels have
+no uptime guarantee and get a new address on every start; LINE may lose messages
+while its webhook URL switches. WeChat logins expire on Tencent's side and must
+be scanned again. Feishu and DingTalk hand each event to one random connection
+of the app, so running the same app in another ACECode, hermes or OpenClaw
+silently takes part of the messages; use one app per runner. LINE shows
+"connecting" until **Use webhook** is on in the console, and LINE file
+messages other than images become a text notice. Discord forum channels and
+Feishu card buttons are not handled. QQ "typing" is not sent because it
+may consume the passive reply budget. Held QQ outputs are lost if the daemon
+restarts; the session transcript still has them. Chunked QQ uploads are not
+implemented. So far the channels have been verified on Windows only.
+
+### Build And Local Tests
+
+```sh
+cmake --build <build-dir> --target acecode acecode_unit_tests
+acecode_unit_tests --gtest_filter='WebSocketClient*:AesGcm*:Im*:Qq*:Tg*:Telegram*:Channel*:ImChannelsEndToEnd*'
+pnpm --dir web test
+```
+
+The transports run end to end against local fake QQ (token, gateway WebSocket,
+messages, uploads, bind portal) and Telegram (Bot API, long polling, multipart)
+servers; the core uses an in-memory session client. `ImChannelsEndToEnd*` runs the daemon's
+production wiring with a real session registry and a scripted model against those fakes, covering
+owner binding, private and group chats, approvals, session switching, media and QQ resend. These
+tests never contact
+Tencent or Telegram. Real-account acceptance is tracked in the change's
+`verification.md`.
+
+## WhatsApp
 
-The first channel is a personal WhatsApp account linked by QR. C++ routing lives
+WhatsApp uses a personal account linked by QR. C++ routing lives
 in `src/host/channels`; a small, pinned Baileys/Node.js process handles WhatsApp device
 authentication and encryption. This is an unofficial WhatsApp Web integration,
 not the Business Cloud API. Account-based end-to-end validation requires pairing
 your own device. Never expose the account's auth directory or pairing QR.
 
-## Configuration
+### Configuration
 
 Run **`acecode channels`** in an interactive terminal. `acecode channels setup`
 is an explicit alias. This command only configures the account; it does not
@@ -66,7 +323,7 @@ already authorized by the wizard. Bot output IDs are persisted to avoid self-cha
 echo loops. Existing contacts remain authorized when the wizard is rerun; revoke
 unwanted contacts explicitly with `acecode channels revoke <jid>`.
 
-## Conversations And Controls
+### Conversations And Controls
 
 The first authorized message creates a regular **no-workspace session**, with
 `default` tool permissions. It does not inherit a local skip-confirmations mode,
@@ -124,7 +381,7 @@ message reference while it remains in the bounded bridge cache. Long text is
 split using the existing RC helper. Unsupported media and delivery failures do
 not terminate other conversations.
 
-## Runtime And Recovery
+### Runtime And Recovery
 
 Only the daemon worker hosts the gateway, using its existing SessionRegistry and
 LocalSessionClient. Starting `acecode daemon` connects configured channels.
@@ -166,7 +423,7 @@ No voice, scheduled/cross-channel delivery, other platforms, Matrix encryption,
 Yuanbao, Signal, BlueBubbles or Photon support is included in this phase. Existing
 `/rc` activation and bindings are unchanged.
 
-## Build And Local Tests
+### Build And Local Tests
 
 `acecode` builds stage the bridge next to the executable. `cmake --install build
 --config Release --prefix <package> --component whatsapp_channel` stages the
@@ -191,7 +448,7 @@ test loads Baileys and checks the disconnected protocol without contacting an
 account. These are not a substitute for scanning a QR and exchanging real
 messages from the intended account.
 
-## Real Account Acceptance
+### Real Account Acceptance
 
 After pairing, verify the following with the intended account before relying on
 unattended operation:
diff --git a/docs/daemon-api.md b/docs/daemon-api.md
index b916a3287..d3df6db23 100644
--- a/docs/daemon-api.md
+++ b/docs/daemon-api.md
@@ -138,6 +138,8 @@ Session list endpoints return arrays of objects shaped like:
   "swarm_mode": "off",
   "created_at": "2026-07-04T01:23:45Z",
   "updated_at": "2026-07-04T01:25:00Z",
+  "last_user_message_at": "2026-07-04T01:24:00Z",
+  "last_turn_outcome": "completed",
   "provider": "openai",
   "model": "gpt-4.1",
   "model_name": "work-gpt",
@@ -168,7 +170,11 @@ Session list endpoints return arrays of objects shaped like:
 ```
 
 Some fields are omitted when empty, especially `worktree`, `todos`, and token
-usage. For a managed-worktree session, top-level `cwd` intentionally remains
+usage. `remote_control_bound` is `true` only for the session bound by `/rc`.
+A session bound by an IM channel conversation (QQ / Telegram, section 19) also
+carries `"channel_bound": {"platform": "qq"}`; unbound sessions omit the field.
+The sidebar shows the same computer icon for either, but `/rc`-specific
+behavior keys only on `remote_control_bound`. For a managed-worktree session, top-level `cwd` intentionally remains
 the workspace/session-storage root. `worktree.path` is the active absolute
 working root used by file, Git, LSP, and path-reference surfaces.
 
@@ -272,6 +278,7 @@ update their transcript presentation.
 | GET | `/api/pinned-sessions/order` | read global cross-scope pin order |
 | PUT | `/api/pinned-sessions/order` | set global cross-scope pin order |
 | GET | `/api/sessions` | compatibility session list |
+| GET | `/api/desktop-office?session=<id>&workspace=<hash>` | recent five offices and selected root/agent runtime snapshot |
 | GET | `/api/session-search/sessions?q=...&limit=N&cursor=...&request_id=...` | incremental global session catalog page |
 | GET | `/api/session-search/user-messages?q=...&limit=N&request_id=...` | advance one bounded visible-user-message search batch |
 | POST | `/api/session-search/requests/:request_id/cancel` | cancel/pause an incremental global search |
@@ -442,6 +449,14 @@ update their transcript presentation.
 | POST | `/api/pty/:id/resize` | resize PTY |
 | POST | `/api/pty/:id/title` | set PTY title |
 | PUT | `/api/console/config` | write console shell config |
+| GET | `/api/channels` | IM channel snapshots (QQ, WeChat, Feishu, DingTalk, Telegram, Discord, LINE); local clients only |
+| POST | `/api/channels/:platform/enabled` | connect or disconnect a channel immediately |
+| PUT | `/api/channels/:platform/credentials` | validate, then save channel credentials |
+| POST / DELETE | `/api/channels/:platform/bind` | start or cancel scan-to-configure (QQ, WeChat) |
+| POST | `/api/channels/:platform/owner-link` | one-time owner link (Telegram) or 6-digit owner code (Feishu, DingTalk, Discord, LINE) |
+| POST | `/api/channels/telegram/remove-webhook` | remove a Telegram webhook after confirmation |
+| POST | `/api/channels/:platform/requests/:id/{approve,reject}` | decide a pairing request |
+| DELETE | `/api/channels/:platform/access/:principal` | revoke a contact or group |
 
 `POST /api/config/model-order` requires authentication and a complete permutation of
 the current model names returned by `GET /api/models`. Legacy profiles belonging
@@ -545,6 +560,32 @@ disabled, the write is silently ignored.
 
 ## 5. Workspaces and Sessions
 
+### `GET /api/desktop-office?session=<id>&workspace=<hash>`
+
+只读桌面办公室快照，使用通用鉴权/CORS，响应 `Cache-Control: no-store`。
+`session` 与 `workspace` 可省略；默认选最近办公室。选择子会话时返回它所属的根办公室。
+显式选择不存在或已归档会话返回 `404`，并在可用时附带当前 `offices`。
+
+```json
+{
+  "offices": [{"id":"root","workspace_hash":"abc123","title":"Review", "last_user_message_at":"2026-10-06T10:00:00Z"}],
+  "selected": {"id":"root","active":true,"status":"idle","last_turn_outcome":"completed","activity":{"known":true,"busy":false,"outcome":"completed","phase":"","tool":"","seq":42}},
+  "agents": [{"id":"root"}],
+  "complete": true,
+  "connected": true
+}
+```
+
+`offices` 最多五个：跨工作区按 `last_user_message_at` 降序，排除归档、子会话和没有真实用户输入的会话。打开会话、模型输出、隐藏提示及 agent 间消息不推进此时间；旧记录从 JSONL 逆向读取后缓存。目录或旧记录仍在加载时 `complete=false`，客户端可继续读取；空目录返回空数组及 `selected:null`。分叉继承保留消息的原始时间。
+
+`selected` 和 `agents` 只传身份、标题、所属工作区、真实状态和当前上下文用量等展示字段；不含输入草稿、原始工具参数、工具输出或历史正文（下文 `activity.detail` / `activity.text` 两个有界展示片段除外）。`agents` 包含根会话和当前 daemon 已装载的直属/网状子会话；网状子会话的 `parent_session_id` 是树根，`agent_path` 保留实际层级。已成功结束的子会话可仍出现在原始快照中，由桌宠投影立即离座。标题/摘要限 240 UTF-8 字节。
+
+运行中条目的 `activity` 来自事件分发器维护的紧凑状态，不依赖有限的重放缓冲：`known`、`busy`、`turn_id`、`outcome`、`phase`、`label`、`tool`、`detail`、`text`、`seq`、`compact_id`、`transfers`。待授权/待回答优先于工具和模型阶段；`outcome` 保留 `completed`/`aborted`/`error` 差别。`transfers` 最多保留 16 个带序号的 agent 间交接标识，不含消息内容。持久化 `last_turn_outcome` 使恢复后的完成主会话继续显示睡眠状态。
+
+流式正文会把 `phase` 置为 `responding`（默认「用于编程」模式下服务端不发该进度，由 token 事件推断），推理片段对应 `reasoning`，`text` 是本段正文或推理最后不超过 160 UTF-8 字节的尾巴，换阶段或开始工具调用即清空；`detail` 是正在运行工具的一行调用预览（`display_override`，为空时取 `command_preview`），最多 120 字节，工具结束清空。桌宠页面在两次快照之间直接用 WebSocket 的 `token` / `reasoning` 事件按 `seq` 叠加实时文字（约 150ms 节流），快照追上后以快照为准。
+
+`token_usage` 是最近请求上下文统计，配合 `context_window` 计算文件堆厚度；未知窗口不伪造比例。休眠会话可通过已有 model 端点补充窗口大小。该端点不会发起模型请求或改变会话运行状态。
+
 ### `GET /api/workspaces`
 
 Returns `Workspace[]`. The registry is scanned before listing. If no registry
@@ -5458,7 +5499,7 @@ discarded. The original history remains available.
 
 The daemon also hosts the optional WhatsApp channel runtime. Its control plane
 is a separate private loopback listener, not a route on this Web API. See
-[WhatsApp channels](channels.md) for standalone CLI configuration and management. The descriptor
+[WhatsApp channels](channels.md#whatsapp) for standalone CLI configuration and management. The descriptor
 `channels/whatsapp/owner.json` in the ACECode data directory contains protocol
 version 1, PID, port and an owner token. `POST /channels` requires the
 `X-ACECode-Channels-Token` header even on loopback and rejects browser Origin
@@ -5483,6 +5524,167 @@ from older binaries. Explicit CLI runtime commands never start
 a missing host. `acecode channels status` can read saved settings without one;
 its `host_running` field distinguishes offline configuration from a live owner.
 
+## 19. IM Channels (QQ, WeChat, Feishu, DingTalk, Telegram, Discord, LINE)
+
+`openspec add-desktop-im-channels`. The daemon hosts native channels for QQ
+(official bot, API v2 WebSocket gateway), WeChat (`weixin`, Tencent iLink bot,
+long polling), Feishu / Lark (`feishu`, long-connection WebSocket), DingTalk
+(`dingtalk`, Stream mode), Telegram (Bot API long polling), Discord (gateway
+WebSocket) and LINE (`line`, Messaging API webhooks through a dedicated local
+listener). Platform names in paths are exactly these keys. Each platform keeps
+its data under `<data_dir>/channels/<platform>/`: `config.json`
+(enabled flag, credentials, owner, approved contacts and groups; written only by
+these endpoints, owner-only permissions) and `state.json` (session bindings,
+sessions created per IM conversation, de-duplication receipts, Telegram update
+offset). A corrupt file blocks that platform with state `error`; it is never
+reset silently. WhatsApp (section 18) is unaffected and is not managed here.
+
+All routes accept only direct local clients. Requests forwarded by the remote
+Web proxy (source `127.0.0.2`) or from any other address return
+`403 {"error":"LOCAL_ONLY"}` even with a valid token. Errors use
+`{"error": CODE, "message": text}`: `400 CHANNEL_ERROR` or `BAD_REQUEST`
+(messages are user-facing Chinese text without credentials),
+`404 UNKNOWN_PLATFORM`, and `503 UNAVAILABLE` when the daemon has no channel host.
+Mutating routes return the full `GET /api/channels` snapshot unless noted.
+
+### `GET /api/channels`
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "telegram",
+      "configured": true,
+      "enabled": true,
+      "state": "connected",
+      "detail": "",
+      "retry_stopped": false,
+      "account": "123456",
+      "display_name": "@ace_bot",
+      "extra": {"username": "ace_bot", "privacy_mode": true, "link": "https://t.me/ace_bot"},
+      "credential_hint": "****wxyz",
+      "owner": "user:42",
+      "contacts": [
+        {"principal": "user:42", "kind": "user", "name": "Me", "owner": true, "approved_at_ms": 1790000000000}
+      ],
+      "pending": [
+        {"id": "a1b2c3d4", "kind": "user", "name": "Alice", "principal": "user:7",
+         "label": "Telegram 私聊", "expires_in_s": 512}
+      ],
+      "owner_window": false,
+      "bindings": [
+        {"key": "[\"telegram\",\"123456\",\"private\",\"42\"]", "label": "Telegram 私聊",
+         "chat": "42", "sender": "42", "session_id": "sid", "no_workspace": true,
+         "cwd": "...", "workspace_hash": "", "sent": 3, "failed": 0, "dropped": 0}
+      ]
+    }
+  ],
+  "binds": {"qq": {"platform": "qq", "phase": "idle"}, "weixin": {"platform": "weixin", "phase": "idle"}}
+}
+```
+
+- `state`: `unconfigured`, `disabled`, `connecting`, `connected`, `retrying`,
+  `failed` (`retry_stopped=true` after authentication failure, ban or another
+  fatal close; turning the switch on again reconnects), `standby` (another
+  ACECode process owns the account lock; `hosted_by_pid` names it, and this
+  process takes over after that owner exits), `stopped`, or `error` (corrupt
+  data files; `detail` gives the reason).
+- `credentials_public` lists the saved credential fields: non-secret values as
+  stored (AppID, Client ID, bot ids, Feishu `domain`, LINE `public_url`) and
+  secrets masked to their last four characters. `credential_hint` is the mask of
+  the platform's first secret field. QQ snapshots also carry `app_id`. QQ `extra`
+  reports `held` (outputs waiting for the contact's next message after the
+  passive and active reply windows were exhausted) and `markdown`.
+- Telegram `extra.webhook=true` means `getUpdates` is blocked by a configured
+  webhook; call `remove-webhook` after the user confirms.
+- Principals are `user:<id>`, `group:<id>`, and `member:<group>:<member>`
+  (only QQ scopes group member ids to the group). On WeChat only private chats
+  exist; on Discord a guild channel (or thread) is the "group".
+- The page shows only a one-line status. Failure reasons, privacy mode, held
+  outputs, bindings and send counts are written to the daemon log under
+  `[channels/<platform>]`.
+
+### `POST /api/channels/:platform/enabled`
+
+Body `{"enabled": true|false}`. The switch persists immediately and connects or
+disconnects without a separate save. Enabling an unconfigured platform returns
+`400`. Disabling keeps credentials, contacts and bindings.
+
+### `PUT /api/channels/:platform/credentials`
+
+Accepted fields per platform: QQ `app_id`, `app_secret`; Feishu `app_id`,
+`app_secret`, `domain` (`feishu` or `lark`); DingTalk `client_id`,
+`client_secret`, `robot_code`; Telegram `token`; Discord `token`; LINE
+`channel_id`, `channel_secret`, `access_token` (optional long-lived token),
+`public_url` (optional). WeChat has no manual credentials (scan only). Values
+are trimmed strings of at most 512 bytes; unknown fields are rejected. An empty
+or missing required field keeps the saved value (the page only knows the masked
+hint); an empty optional field such as `public_url` clears it. The merged
+credentials are validated online first (QQ access-token exchange, Feishu tenant
+token, DingTalk access token, Telegram `getMe`, Discord `/users/@me` plus
+`/applications/@me`, LINE token issue plus `/v2/bot/info`); failure returns
+`400` and saves nothing. Validation may add derived non-secret fields (Discord
+`bot_id` and `application_id`, LINE `bot_id`). On success the platform
+reconnects if it is on. Switching to a different bot account drops bindings of
+the old bot, and on platforms whose user ids are scoped per bot (QQ, WeChat,
+Feishu, DingTalk, LINE) also clears the owner and approved contacts.
+
+### `POST /api/channels/:platform/bind` and `DELETE /api/channels/:platform/bind`
+
+Scan-to-configure for `qq` and `weixin` (other platforms return `404`). Starts
+the flow and returns `{"platform":<p>,"phase":"starting"}`; a second start while
+any scan is running returns `400`. Progress is pushed as `channels_bind` events
+(below). `DELETE` cancels and returns the current bind state. Cancellation,
+failure and timeout leave the existing configuration untouched. On success the
+credentials are saved (QQ: AppID and the locally decrypted AppSecret; WeChat:
+bot token, bot id and API base), the scanning user becomes owner when the
+service reports them (WeChat always does; on QQ otherwise the first private
+sender within 10 minutes does), and the platform turns on.
+
+### `POST /api/channels/:platform/owner-link`
+
+Requires a connected bot and no owner yet. Telegram returns
+`{"link":"https://t.me/<bot>?start=<code>","expires_in_s":600}`; the first user
+who opens the link and sends `/start <code>` becomes owner. Feishu, DingTalk,
+Discord and LINE return `{"code":"123456","expires_in_s":600}`; the first user
+who sends exactly these six digits in a private chat with the bot becomes owner,
+and that message is not passed to a session. Codes are single-use; while a code
+is outstanding, ten wrong six-digit guesses in private chats invalidate all
+outstanding codes. QQ and WeChat return `400` (owners come from scanning).
+
+### `POST /api/channels/telegram/remove-webhook`
+
+Calls Telegram `deleteWebhook` and resumes polling. Only call it after the user
+confirms; it replaces whatever other service registered the webhook.
+
+### `POST /api/channels/:platform/requests/:id/approve|reject`
+
+Decides a pending pairing request (requests expire after 10 minutes; an
+expired or unknown id returns `400`). Approving a private user while the
+platform has no owner makes that user the owner. Approval applies from the
+contact's next message; the message that triggered the request is not replayed.
+
+### `DELETE /api/channels/:platform/access/:principal`
+
+The principal is percent-encoded in the path (for example
+`member%3AG1%3AM1`). Revoking removes it from the approved list (clearing the
+owner if it matches), drops its pending requests, and aborts the running turn
+of every session bound to it.
+
+### WebSocket events
+
+Channel events are sent only to WebSocket connections opened by direct local
+clients, using the envelope `{"type", "timestamp_ms", "payload"}` without a
+session id:
+
+| Type | Payload |
+|---|---|
+| `channels_state` | one platform snapshot, same shape as an item of `platforms` |
+| `channels_bind` | `{"platform":"qq"/"weixin", "phase", "qr_url"?, "refreshes"?, "error"?, "account"?, "owner_bound"?}`; phase is `starting`, `waiting`, `completed`, `failed`, `cancelled` or `timed_out` |
+| `channels_request` | `{"platform","id","kind","name","label"}` for a new pairing request; Desktop shows a system notification |
+
+`qr_url` is the QR code content for the phone; it is never logged.
+
 ## Session loading diagnostics
 
 - `POST /api/diagnostics/session-open` accepts `session_id`, nonnegative
diff --git a/docs/desktop-agent-office.md b/docs/desktop-agent-office.md
new file mode 100644
index 000000000..ba9d41ae6
--- /dev/null
+++ b/docs/desktop-agent-office.md
@@ -0,0 +1,28 @@
+# Agent 桌面办公室
+
+Windows 与 macOS Desktop 会显示一个透明的像素办公室。单会话有一个主角色 Maestro，多 agent 任务按真实子会话入座；无需启动额外模型，也没有演示任务循环。美术与拖动缩放来自原有 Claude 桌宠，旧的 `design-prototypes/agent-office` 事务所原型已移除。
+
+## 操作
+
+- 顶部显示跨工作区最近发过消息的五个主会话。顺序只看用户最后发送消息的时间，打开、切换和 agent 输出不会把会话顶到最前面。
+- “跟随”默认开启，办公室随主窗口当前会话切换。点击门牌会关闭跟随并固定办公室；再次打开跟随后恢复跟随。查看最近五个之外的当前会话不改变门牌排序。
+- 主 agent 成功完成后留在座位显示 `zzz`，下一轮自动醒来；成功完成的子 agent 立即离座，重新工作时以同样的外观返回。
+- 忙碌的 agent 头顶常驻状态气泡：「图标 动作 · 细节」。正在输出时显示「撰写回复」和最新的几个字（打字动画 + 光标），推理时显示思考点和推理尾巴，调用工具时显示动作（读取、运行命令、修改代码…）和调用预览（路径、命令）。默认「用于编程」模式下服务端不发正文进度，桌宠由 token 事件推断。气泡互相避让：先左右错开，再抬高并用引线连回头顶，放不下时只留动作。
+- 子 agent 出现时从门口走进来，先到派活的人桌前领「任务」信封再回工位；完成后走到派活的人桌前递「回报」信封（派活的人显示「收到…的结果」）再出门；失败或停止的成员直接出门。网状协作中 agent 间消息以带「消息 / 新任务 / 回报」标签的信封在工位间飞过。系统开启「减少动态效果」时不走路，交接信封仍然显示。
+- 等待授权、等待回答、重试、压缩、失败和取消有各自状态。超过七个子角色时点击 `+N` 查看成员并打开对应会话；列表随状态更新，Escape 收起。选中房间人物后双击可打开其会话。
+- 文件堆随当前上下文占用增长，压缩后依据实际新统计变薄。工具符号与聊天工具行共用 SVG 来源。
+- 拖动房间空地移动窗口；滚轮、右下角把手和右键菜单可缩放。窗口不抢主界面焦点，透明角落可穿透点击；尺寸按原实现保存。
+
+## 构建与数据流
+
+由当前工作区的 `scripts/dev_desktop.bat` 启动开发版。先构建 `web/`，再配置/构建 CMake Desktop，使内嵌主界面与桌宠资源保持一致。`ACECODE_DESKTOP_PET=0` 可对本次进程禁用桌宠；Linux 当前没有原生桌宠窗口实现。
+
+macOS 版（`src/apps/desktop/desktop_pet_mac.mm`，ARC 编译）用非激活 NSPanel + WKWebView 承载同一份页面：文档开始前注入 `window.chrome.webview` 垫片，页面代码不分平台；透明区域的点击穿透靠定时检测鼠标是否落在房间、控制条或页面上报的浮层里，再切换 `ignoresMouseEvents`；拖动与把手缩放由定时器跟随鼠标。默认 1.25 倍（约 430×315 点），设置存 `~/Library/Application Support/ACECode/desktop-pet/settings.json`。
+
+数据链为：会话元数据/事件分发器 → `GET /api/desktop-office` → App 级办公室控制器 → 原生 WebView 桥 → 像素场景。控制器复用现有引用计数 WS 订阅，事件触发刷新并以 3 秒轮询兜底；正在加载旧记录时短间隔继续读取。快速切换以请求代次和取消信号隔离迟到响应；页面卸载释放订阅和计时器，重载从原生缓存恢复当前选择与跟随状态。
+
+页面把成员列表、提示和状态气泡的矩形（节流后）上报给原生窗口：Windows 的窗口区域同时裁剪绘制，冒出墙顶的气泡必须并入区域才不会被切掉；macOS 用同一份矩形判断点击穿透。
+
+断线时明确显示正在重连，恢复后重取真实快照。错误和取消不会被当作成功睡眠。只同步小型展示字段，不通过动画触发或控制 agent 任务。
+
+视觉规则见 [桌宠设计](../assets/desktop_pet/DESIGN.md)，协议见 [daemon API](daemon-api.md)。验收命令及本次实测范围见 [交付记录](../openspec/changes/integrate-desktop-agent-office/verification.md)。
diff --git a/docs/help-source/group5.py b/docs/help-source/group5.py
index d0a0405db..7bb2bc59c 100644
--- a/docs/help-source/group5.py
+++ b/docs/help-source/group5.py
@@ -55,7 +55,15 @@
         '''<p>元素选择可以把目标位置作为上下文加入输入区，按 <kbd>Esc</kbd> 退出选择。添加控制台信息时，引用的是当时的快照，不会自动发送消息，也不会持续同步未来所有日志。</p><p>提交前检查附件或上下文项是否指向正确页面，可以移除无关项。动态页面、跨来源 iframe 和不同操作系统的原生实现存在能力差异；选不到时描述页面和元素位置，并以实际返回信息为准。</p><p>让智能体完成操作后，检查网页结果与必要的应用数据。浏览器动作成功只证明交互执行，不代表业务提交一定成功。连接能力状态可以在<strong>设置 &gt; 工具</strong>检查。</p>''')
 ], ["docs/agent-browser.md", "web/src/components/PreviewDetailsPanel.jsx", "web/src/components/SettingsPage.jsx"]),
 
-"channels": page("通过已经安装的渠道插件把一个 ACECode 会话连接到外部消息平台，或使用手动 Webhook 进行集成。", [
+"channels": page("在设置里直接连接 QQ 与 Telegram，或通过渠道插件、手动 Webhook 把 ACECode 会话接到其他消息平台。", [
+    section("im", "连接 QQ、微信、飞书、钉钉、Telegram、Discord 与 LINE",
+        '''<p>在 <strong>设置 &gt; 集成 &gt; 消息通道</strong> 中直接连接 QQ 官方机器人、微信、飞书、钉钉、Telegram、Discord 与 LINE，不需要安装插件或 Node.js；除 LINE 外都由本机主动连出，不需要公网地址，所有连接都跟随 ACECode 的代理设置。页面上每个平台一张卡片：点<strong>连接</strong>，还没配好的平台会弹出三步向导（创建机器人 → 连接 → 绑定机主），配好的直接连上；连上后按钮变成<strong>取消连接</strong>，点一下立即断开。卡片只显示简要状态和待批准请求，连接失败的原因、群隐私模式、收发计数等细节写在后台进程的日志里（数据目录下 <code>logs/daemon-日期.log</code>，带 <code>[channels/…]</code> 前缀）。</p>''',
+        table(["平台", "配置方式"], [["QQ", "点<strong>连接</strong>后向导直接显示二维码，用手机 QQ 扫码并确认，机器人会自动创建并配置，扫码人成为机主。也可以改为<strong>手动填写 AppID / AppSecret</strong>，保存前会先验证。未经个人认证的机器人只有管理员本人能使用，并且只能加入管理员担任群主的群。"], ["Telegram", "向导第一步说明如何在 @BotFather 创建机器人，粘贴 Token 后会先验证。连上后在“绑定机主”一步用手机相机扫码（Telegram 自带的扫码只能登录设备，扫不了这个），在 Telegram 里点<strong>开始</strong>即成为机主；电脑上登录了 Telegram 也可以直接点链接，或点<strong>复制链接</strong>。"], ["微信", "点<strong>连接</strong>后用微信扫码并在手机上确认，扫码的微信号自动成为机主，也是唯一能使用它的人。微信机器人只支持私聊；登录失效时卡片会提示，重新扫码即可。"], ["飞书", "在飞书开放平台创建企业自建应用、添加机器人能力并开通 im:message 等权限，填入 App ID 与 App Secret（可选飞书或 Lark）。连上之后回到开放平台，把订阅方式保存为<strong>使用长连接接收事件</strong>、添加<strong>接收消息 v2.0</strong>事件并发布版本（飞书要求长连接在线时才能保存）。"], ["钉钉", "在钉钉开放平台创建企业内部应用、添加机器人并选择 <strong>Stream 模式</strong>，开通机器人发送消息权限后发布，填入 Client ID 与 Client Secret。"], ["Discord", "在 Discord 开发者后台新建应用，在 Bot 页复制 Token 并打开 <strong>Message Content Intent</strong>，粘贴 Token 后用向导给出的邀请链接把机器人拉进服务器。私信与频道里 @机器人 都能用。"], ["LINE", "在 LINE Official Account Manager 建官方账号并启用 Messaging API，填入 Channel ID 与 Channel secret；在控制台打开 Use webhook、关闭自动回应。LINE 只能回调公网地址：公网地址留空时 ACECode 用 cloudflared 自动建立临时隧道（先用 <code>winget install --id Cloudflare.cloudflared</code> 安装），也可以填写自己的 HTTPS 地址。"]]),
+        '''<p>默认拒绝所有人。陌生人私聊只会收到配对提示，平台卡片上出现待批准请求（Desktop 窗口不在前台时弹出系统通知），请求 10 分钟后失效。群要先批准，群里只处理 @机器人 的消息，群成员也要单独批准。飞书、钉钉、Discord、LINE 连上后，向导会给出 6 位绑定码，私聊机器人发送这串数字即成为机主（10 分钟内有效，只能用一次）。飞书和钉钉会把每条消息随机交给同一应用的某一个连接，同一个应用不要再同时接到别的工具上，否则会悄悄分走一部分消息。在卡片的<strong>管理</strong>里可以更换机器人或撤销授权；撤销会立即停止处理对方的消息，并中止其会话正在进行的回合。</p>''',
+        table(["在聊天中发送", "作用"], [["<code>/help</code>", "列出可用命令。"], ["<code>/status</code>", "查看会话、位置、模型、是否忙碌和待处理事项。"], ["<code>/stop</code>", "停止当前回合。"], ["<code>/new</code>", "在当前会话所在的位置新建会话。"], ["<code>/sessions</code>、<code>/resume 编号</code>", "列出并切换会话；机主可以切到任意会话，其他人只能切换自己创建的会话。"], ["<code>/model 名称</code>", "从下一回合起切换模型。"], ["<code>/approve 编号</code>、<code>/deny 编号</code>、<code>/aq</code>", "处理权限请求与提问，与 Desktop 先答者生效。"]]),
+        '''<p>每个私聊（或群里的每位成员）绑定一个 ACECode 会话，第一条消息会自动新建无项目会话并使用默认权限。被绑定的会话在侧栏显示电脑图标；在 Desktop 里向它输入时，回复也会发到聊天。图片和文件会导入会话附件，QQ 语音使用平台识别出的文字。通道由后台进程托管：在“常规”中勾选“退出 ACECode 后继续运行后台进程”时，关闭 Desktop 后通道仍然在线。</p>''',
+        note("关于 QQ 回复额度", "QQ 对每条消息的被动回复有次数与时间限制。超出后 ACECode 改发主动消息；仍被拒绝时先暂存，等对方下一条消息时补发。暂存只在内存里，后台进程重启会丢失，但会话记录完整。")),
+
     section("configure", "准备并连接消息渠道",
         '''<p>先按渠道插件的说明安装它的可执行程序、完成平台认证并取得 manifest 文件。ACECode 使用 <code>remote_control.channels</code> 保存插件配置，使用 <code>remote_control.default_channel</code> 指定默认渠道。只输入消息平台名称不会自动安装插件。</p>''',
         code('{\n  "remote_control": {\n    "default_channel": "my-channel",\n    "channels": {\n      "my-channel": {\n        "manifest_path": "/absolute/path/to/channel-plugin.json",\n        "timeout_ms": 10000,\n        "settings": {}\n      }\n    }\n  }\n}', "JSON · 合并到主配置，路径与 settings 按插件说明填写"),
@@ -68,7 +76,7 @@
     section("manage", "查看状态、解绑与手动接入",
         code("/rc show\n/rc off", "在 ACECode 会话中查看状态与解除绑定"),
         '''<p>show 展示当前连接、入站与出站状态，内容可能包含认证信息，不要直接公开截图。off 解除当前绑定。daemon 托管模式会保存绑定会话并在后续启动时尝试恢复，单纯关闭桌面窗口不等于主动解绑。</p><p>手动集成使用 <code>/remote-control on</code> 启动本地入站服务，再通过 <code>/remote-control url &lt;webhook-url&gt;</code> 指定出站地址。入站使用 <code>POST /rc/send</code>、<code>X-ACECode-RC-Token</code> 请求头和 <code>{"text":"消息"}</code> 正文；按 show 的实际地址接入。</p><p>远程消息控制与<a href="web.html#remote">远程 Web</a>是两套入口，认证头与端口也不同。需要实现自己的渠道时，参见<a href="extension-development.html#channel">渠道插件协议</a>。</p>''')
-], ["src/base/config/config.hpp", "src/apps/tui/commands/remote_control_command.cpp", "src/host/remote_control/session_channel_binder.cpp", "docs/channel-plugin-protocol.md"]),
+], ["src/base/config/config.hpp", "src/apps/tui/commands/remote_control_command.cpp", "src/host/remote_control/session_channel_binder.cpp", "docs/channel-plugin-protocol.md", "docs/channels.md", "src/host/channels/core/host.cpp", "web/src/components/ChannelsSettings.jsx"]),
 
 "examples": page("用四个完整流程练习把目标、范围、执行和验证连在一起。示例提示可直接修改后使用。", [
     section("new-project", "新项目实战",
diff --git a/docs/help-source/sources.json b/docs/help-source/sources.json
index 1ef715afc..36ad79bdd 100644
--- a/docs/help-source/sources.json
+++ b/docs/help-source/sources.json
@@ -353,7 +353,10 @@
       "src/base/config/config.hpp",
       "src/apps/tui/commands/remote_control_command.cpp",
       "src/host/remote_control/session_channel_binder.cpp",
-      "docs/channel-plugin-protocol.md"
+      "docs/channel-plugin-protocol.md",
+      "docs/channels.md",
+      "src/host/channels/core/host.cpp",
+      "web/src/components/ChannelsSettings.jsx"
     ]
   },
   {
diff --git a/docs/help/assets/search-index.js b/docs/help/assets/search-index.js
index 9f99bdb4b..935994342 100644
--- a/docs/help/assets/search-index.js
+++ b/docs/help/assets/search-index.js
@@ -1069,8 +1069,16 @@ window.ACECODE_HELP_INDEX = [
     "group": "进阶使用",
     "title": "消息渠道与远程控制",
     "url": "channels.html",
-    "description": "通过已经安装的渠道插件把一个 ACECode 会话连接到外部消息平台，或使用手动 Webhook 进行集成。",
-    "text": "准备并连接消息渠道 先按渠道插件的说明安装它的可执行程序、完成平台认证并取得 manifest 文件。ACECode 使用 remote_control.channels 保存插件配置，使用 remote_control.default_channel 指定默认渠道。只输入消息平台名称不会自动安装插件。 JSON · 合并到主配置，路径与 settings 按插件说明填写 复制 { \"remote_control\": { \"default_channel\": \"my-channel\", \"channels\": { \"my-channel\": { \"manifest_path\": \"/absolute/path/to/channel-plugin.json\", \"timeout_ms\": 10000, \"settings\": {} } } } } 在要绑定的会话中提交 /rc ，它是 /remote-control 的别名，会激活默认渠道。确认返回已连接状态后，从消息平台发一条简单请求，检查是否进入目标会话并能收到回复。 AD-09 图片占位 渠道绑定与远程消息 此处补充实际界面截图 16 : 9 展示 /rc 返回的已连接状态和会话绑定标记，以及一条测试消息的往返；必须遮挡 Token、Webhook 密钥与私人聊天。 在渠道中切换会话 daemon 托管的已连接渠道可使用以下会话导航命令。这些控制命令由后台处理，不会作为普通问题交给当前模型。 在渠道发送 结果 /sessions 列出最近十个普通、未归档会话。 /sessions more 或 /sessions all 查看完整目录。 /sessions search 关键词 搜索最多五个匹配结果。 /sessions 2 选择最近一次列表中的第 2 个会话。 /session 和 /resume 是同一组渠道导航的别名。列表包含有工作区与无工作区的普通任务，不包含已归档任务和子代理。切换成功后以确认信息中的会话名称为准，再发送后续工作。 目标会话无法恢复时，原连接会保留。运行中的控制请求还在处理时，不要连续发送大量列表和切换命令。桌面前端可以收到切换提示，但渠道本身的会话选择不依赖桌面窗口保持打开。 查看状态、解绑与手动接入 在 ACECode 会话中查看状态与解除绑定 复制 /rc show /rc off show 展示当前连接、入站与出站状态，内容可能包含认证信息，不要直接公开截图。off 解除当前绑定。daemon 托管模式会保存绑定会话并在后续启动时尝试恢复，单纯关闭桌面窗口不等于主动解绑。 手动集成使用 /remote-control on 启动本地入站服务，再通过 /remote-control url <webhook-url> 指定出站地址。入站使用 POST /rc/send 、 X-ACECode-RC-Token 请求头和 {\"text\":\"消息\"} 正文；按 show 的实际地址接入。 远程消息控制与 远程 Web 是两套入口，认证头与端口也不同。需要实现自己的渠道时，参见 渠道插件协议 。"
+    "description": "在设置里直接连接 QQ 与 Telegram，或通过渠道插件、手动 Webhook 把 ACECode 会话接到其他消息平台。",
+    "text": "连接 QQ、微信、飞书、钉钉、Telegram、Discord 与 LINE 在 设置 > 集成 > 消息通道 中直接连接 QQ 官方机器人、微信、飞书、钉钉、Telegram、Discord 与 LINE，不需要安装插件或 Node.js；除 LINE 外都由本机主动连出，不需要公网地址，所有连接都跟随 ACECode 的代理设置。页面上每个平台一张卡片：点 连接 ，还没配好的平台会弹出三步向导（创建机器人 → 连接 → 绑定机主），配好的直接连上；连上后按钮变成 取消连接 ，点一下立即断开。卡片只显示简要状态和待批准请求，连接失败的原因、群隐私模式、收发计数等细节写在后台进程的日志里（数据目录下 logs/daemon-日期.log ，带 [channels/…] 前缀）。 平台 配置方式 QQ 点 连接 后向导直接显示二维码，用手机 QQ 扫码并确认，机器人会自动创建并配置，扫码人成为机主。也可以改为 手动填写 AppID / AppSecret ，保存前会先验证。未经个人认证的机器人只有管理员本人能使用，并且只能加入管理员担任群主的群。 Telegram 向导第一步说明如何在 @BotFather 创建机器人，粘贴 Token 后会先验证。连上后在“绑定机主”一步用手机相机扫码（Telegram 自带的扫码只能登录设备，扫不了这个），在 Telegram 里点 开始 即成为机主；电脑上登录了 Telegram 也可以直接点链接，或点 复制链接 。 微信 点 连接 后用微信扫码并在手机上确认，扫码的微信号自动成为机主，也是唯一能使用它的人。微信机器人只支持私聊；登录失效时卡片会提示，重新扫码即可。 飞书 在飞书开放平台创建企业自建应用、添加机器人能力并开通 im:message 等权限，填入 App ID 与 App Secret（可选飞书或 Lark）。连上之后回到开放平台，把订阅方式保存为 使用长连接接收事件 、添加 接收消息 v2.0 事件并发布版本（飞书要求长连接在线时才能保存）。 钉钉 在钉钉开放平台创建企业内部应用、添加机器人并选择 Stream 模式 ，开通机器人发送消息权限后发布，填入 Client ID 与 Client Secret。 Discord 在 Discord 开发者后台新建应用，在 Bot 页复制 Token 并打开 Message Content Intent ，粘贴 Token 后用向导给出的邀请链接把机器人拉进服务器。私信与频道里 @机器人 都能用。 LINE 在 LINE Official Account Manager 建官方账号并启用 Messaging API，填入 Channel ID 与 Channel secret；在控制台打开 Use webhook、关闭自动回应。LINE 只能回调公网地址：公网地址留空时 ACECode 用 cloudflared 自动建立临时隧道（先用 winget install --id Cloudflare.cloudflared 安装），也可以填写自己的 HTTPS 地址。 默认拒绝所有人。陌生人私聊只会收到配对提示，平台卡片上出现待批准请求（Desktop 窗口不在前台时弹出系统通知），请求 10 分钟后失效。群要先批准，群里只处理 @机器人 的消息，群成员也要单独批准。飞书、钉钉、Discord、LINE 连上后，向导会给出 6 位绑定码，私聊机器人发送这串数字即成为机主（10 分钟内有效，只能用一次）。飞书和钉钉会把每条消息随机交给同一应用的某一个连接，同一个应用不要再同时接到别的工具上，否则会悄悄分走一部分消息。在卡片的 管理 里可以更换机器人或撤销授权；撤销会立即停止处理对方的消息，并中止其会话正在进行的回合。 在聊天中发送 作用 /help 列出可用命令。 /status 查看会话、位置、模型、是否忙碌和待处理事项。 /stop 停止当前回合。 /new 在当前会话所在的位置新建会话。 /sessions 、 /resume 编号 列出并切换会话；机主可以切到任意会话，其他人只能切换自己创建的会话。 /model 名称 从下一回合起切换模型。 /approve 编号 、 /deny 编号 、 /aq 处理权限请求与提问，与 Desktop 先答者生效。 每个私聊（或群里的每位成员）绑定一个 ACECode 会话，第一条消息会自动新建无项目会话并使用默认权限。被绑定的会话在侧栏显示电脑图标；在 Desktop 里向它输入时，回复也会发到聊天。图片和文件会导入会话附件，QQ 语音使用平台识别出的文字。通道由后台进程托管：在“常规”中勾选“退出 ACECode 后继续运行后台进程”时，关闭 Desktop 后通道仍然在线。 关于 QQ 回复额度 QQ 对每条消息的被动回复有次数与时间限制。超出后 ACECode 改发主动消息；仍被拒绝时先暂存，等对方下一条消息时补发。暂存只在内存里，后台进程重启会丢失，但会话记录完整。 准备并连接消息渠道 先按渠道插件的说明安装它的可执行程序、完成平台认证并取得 manifest 文件。ACECode 使用 remote_control.channels 保存插件配置，使用 remote_control.default_channel 指定默认渠道。只输入消息平台名称不会自动安装插件。 JSON · 合并到主配置，路径与 settings 按插件说明填写 复制 { \"remote_control\": { \"default_channel\": \"my-channel\", \"channels\": { \"my-channel\": { \"manifest_path\": \"/absolute/path/to/channel-plugin.json\", \"timeout_ms\": 10000, \"settings\": {} } } } } 在要绑定的会话中提交 /rc ，它是 /remote-control 的别名，会激活默认渠道。确认返回已连接状态后，从消息平台发一条简单请求，检查是否进入目标会话并能收到回复。 AD-09 图片占位 渠道绑定与远程消息 此处补充实际界面截图 16 : 9 展示 /rc 返回的已连接状态和会话绑定标记，以及一条测试消息的往返；必须遮挡 Token、Webhook 密钥与私人聊天。 在渠道中切换会话 daemon 托管的已连接渠道可使用以下会话导航命令。这些控制命令由后台处理，不会作为普通问题交给当前模型。 在渠道发送 结果 /sessions 列出最近十个普通、未归档会话。 /sessions more 或 /sessions all 查看完整目录。 /sessions search 关键词 搜索最多五个匹配结果。 /sessions 2 选择最近一次列表中的第 2 个会话。 /session 和 /resume 是同一组渠道导航的别名。列表包含有工作区与无工作区的普通任务，不包含已归档任务和子代理。切换成功后以确认信息中的会话名称为准，再发送后续工作。 目标会话无法恢复时，原连接会保留。运行中的控制请求还在处理时，不要连续发送大量列表和切换命令。桌面前端可以收到切换提示，但渠道本身的会话选择不依赖桌面窗口保持打开。 查看状态、解绑与手动接入 在 ACECode 会话中查看状态与解除绑定 复制 /rc show /rc off show 展示当前连接、入站与出站状态，内容可能包含认证信息，不要直接公开截图。off 解除当前绑定。daemon 托管模式会保存绑定会话并在后续启动时尝试恢复，单纯关闭桌面窗口不等于主动解绑。 手动集成使用 /remote-control on 启动本地入站服务，再通过 /remote-control url <webhook-url> 指定出站地址。入站使用 POST /rc/send 、 X-ACECode-RC-Token 请求头和 {\"text\":\"消息\"} 正文；按 show 的实际地址接入。 远程消息控制与 远程 Web 是两套入口，认证头与端口也不同。需要实现自己的渠道时，参见 渠道插件协议 。"
+  },
+  {
+    "page": "消息渠道与远程控制",
+    "group": "进阶使用",
+    "title": "连接 QQ、微信、飞书、钉钉、Telegram、Discord 与 LINE",
+    "url": "channels.html#im",
+    "description": "连接 QQ、微信、飞书、钉钉、Telegram、Discord 与 LINE 在 设置 > 集成 > 消息通道 中直接连接 QQ 官方机器人、微信、飞书、钉钉、Telegram、Discord 与 LINE，不需要安装插件或 Node.js；除 LI",
+    "text": "连接 QQ、微信、飞书、钉钉、Telegram、Discord 与 LINE 在 设置 > 集成 > 消息通道 中直接连接 QQ 官方机器人、微信、飞书、钉钉、Telegram、Discord 与 LINE，不需要安装插件或 Node.js；除 LINE 外都由本机主动连出，不需要公网地址，所有连接都跟随 ACECode 的代理设置。页面上每个平台一张卡片：点 连接 ，还没配好的平台会弹出三步向导（创建机器人 → 连接 → 绑定机主），配好的直接连上；连上后按钮变成 取消连接 ，点一下立即断开。卡片只显示简要状态和待批准请求，连接失败的原因、群隐私模式、收发计数等细节写在后台进程的日志里（数据目录下 logs/daemon-日期.log ，带 [channels/…] 前缀）。 平台 配置方式 QQ 点 连接 后向导直接显示二维码，用手机 QQ 扫码并确认，机器人会自动创建并配置，扫码人成为机主。也可以改为 手动填写 AppID / AppSecret ，保存前会先验证。未经个人认证的机器人只有管理员本人能使用，并且只能加入管理员担任群主的群。 Telegram 向导第一步说明如何在 @BotFather 创建机器人，粘贴 Token 后会先验证。连上后在“绑定机主”一步用手机相机扫码（Telegram 自带的扫码只能登录设备，扫不了这个），在 Telegram 里点 开始 即成为机主；电脑上登录了 Telegram 也可以直接点链接，或点 复制链接 。 微信 点 连接 后用微信扫码并在手机上确认，扫码的微信号自动成为机主，也是唯一能使用它的人。微信机器人只支持私聊；登录失效时卡片会提示，重新扫码即可。 飞书 在飞书开放平台创建企业自建应用、添加机器人能力并开通 im:message 等权限，填入 App ID 与 App Secret（可选飞书或 Lark）。连上之后回到开放平台，把订阅方式保存为 使用长连接接收事件 、添加 接收消息 v2.0 事件并发布版本（飞书要求长连接在线时才能保存）。 钉钉 在钉钉开放平台创建企业内部应用、添加机器人并选择 Stream 模式 ，开通机器人发送消息权限后发布，填入 Client ID 与 Client Secret。 Discord 在 Discord 开发者后台新建应用，在 Bot 页复制 Token 并打开 Message Content Intent ，粘贴 Token 后用向导给出的邀请链接把机器人拉进服务器。私信与频道里 @机器人 都能用。 LINE 在 LINE Official Account Manager 建官方账号并启用 Messaging API，填入 Channel ID 与 Channel secret；在控制台打开 Use webhook、关闭自动回应。LINE 只能回调公网地址：公网地址留空时 ACECode 用 cloudflared 自动建立临时隧道（先用 winget install --id Cloudflare.cloudflared 安装），也可以填写自己的 HTTPS 地址。 默认拒绝所有人。陌生人私聊只会收到配对提示，平台卡片上出现待批准请求（Desktop 窗口不在前台时弹出系统通知），请求 10 分钟后失效。群要先批准，群里只处理 @机器人 的消息，群成员也要单独批准。飞书、钉钉、Discord、LINE 连上后，向导会给出 6 位绑定码，私聊机器人发送这串数字即成为机主（10 分钟内有效，只能用一次）。飞书和钉钉会把每条消息随机交给同一应用的某一个连接，同一个应用不要再同时接到别的工具上，否则会悄悄分走一部分消息。在卡片的 管理 里可以更换机器人或撤销授权；撤销会立即停止处理对方的消息，并中止其会话正在进行的回合。 在聊天中发送 作用 /help 列出可用命令。 /status 查看会话、位置、模型、是否忙碌和待处理事项。 /stop 停止当前回合。 /new 在当前会话所在的位置新建会话。 /sessions 、 /resume 编号 列出并切换会话；机主可以切到任意会话，其他人只能切换自己创建的会话。 /model 名称 从下一回合起切换模型。 /approve 编号 、 /deny 编号 、 /aq 处理权限请求与提问，与 Desktop 先答者生效。 每个私聊（或群里的每位成员）绑定一个 ACECode 会话，第一条消息会自动新建无项目会话并使用默认权限。被绑定的会话在侧栏显示电脑图标；在 Desktop 里向它输入时，回复也会发到聊天。图片和文件会导入会话附件，QQ 语音使用平台识别出的文字。通道由后台进程托管：在“常规”中勾选“退出 ACECode 后继续运行后台进程”时，关闭 Desktop 后通道仍然在线。 关于 QQ 回复额度 QQ 对每条消息的被动回复有次数与时间限制。超出后 ACECode 改发主动消息；仍被拒绝时先暂存，等对方下一条消息时补发。暂存只在内存里，后台进程重启会丢失，但会话记录完整。"
   },
   {
     "page": "消息渠道与远程控制",
diff --git a/docs/help/channels.html b/docs/help/channels.html
index 684e99965..8f24f8088 100644
--- a/docs/help/channels.html
+++ b/docs/help/channels.html
@@ -4,7 +4,7 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <meta name="color-scheme" content="dark light">
-  <meta name="description" content="通过已经安装的渠道插件把一个 ACECode 会话连接到外部消息平台，或使用手动 Webhook 进行集成。">
+  <meta name="description" content="在设置里直接连接 QQ 与 Telegram，或通过渠道插件、手动 Webhook 把 ACECode 会话接到其他消息平台。">
   <title>消息渠道与远程控制 · ACECode 文档</title>
   <link rel="icon" href="data:,">
   <link rel="stylesheet" href="assets/styles.css">
@@ -34,9 +34,15 @@
   <div class="document-layout">
     <main id="main-content" class="article" tabindex="-1">
       <div class="breadcrumb"><a href="index.html">文档</a><span aria-hidden="true">›</span><span>进阶使用</span></div>
-      <header class="article-header"><h1>消息渠道与远程控制</h1><p class="lead">通过已经安装的渠道插件把一个 ACECode 会话连接到外部消息平台，或使用手动 Webhook 进行集成。</p></header>
-      <details class="mobile-contents"><summary>本页内容<svg class="icon" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true"><path d="m8 5 7 7-7 7"/></svg></summary><ul><li><a href="#configure" data-toc-link>准备并连接消息渠道</a></li><li><a href="#sessions" data-toc-link>在渠道中切换会话</a></li><li><a href="#manage" data-toc-link>查看状态、解绑与手动接入</a></li></ul></details>
+      <header class="article-header"><h1>消息渠道与远程控制</h1><p class="lead">在设置里直接连接 QQ 与 Telegram，或通过渠道插件、手动 Webhook 把 ACECode 会话接到其他消息平台。</p></header>
+      <details class="mobile-contents"><summary>本页内容<svg class="icon" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true"><path d="m8 5 7 7-7 7"/></svg></summary><ul><li><a href="#im" data-toc-link>连接 QQ、微信、飞书、钉钉、Telegram、Discord 与 LINE</a></li><li><a href="#configure" data-toc-link>准备并连接消息渠道</a></li><li><a href="#sessions" data-toc-link>在渠道中切换会话</a></li><li><a href="#manage" data-toc-link>查看状态、解绑与手动接入</a></li></ul></details>
       
+<section aria-labelledby="im"><h2 id="im">连接 QQ、微信、飞书、钉钉、Telegram、Discord 与 LINE</h2><p>在 <strong>设置 &gt; 集成 &gt; 消息通道</strong> 中直接连接 QQ 官方机器人、微信、飞书、钉钉、Telegram、Discord 与 LINE，不需要安装插件或 Node.js；除 LINE 外都由本机主动连出，不需要公网地址，所有连接都跟随 ACECode 的代理设置。页面上每个平台一张卡片：点<strong>连接</strong>，还没配好的平台会弹出三步向导（创建机器人 → 连接 → 绑定机主），配好的直接连上；连上后按钮变成<strong>取消连接</strong>，点一下立即断开。卡片只显示简要状态和待批准请求，连接失败的原因、群隐私模式、收发计数等细节写在后台进程的日志里（数据目录下 <code>logs/daemon-日期.log</code>，带 <code>[channels/…]</code> 前缀）。</p>
+<div class="table-scroll"><table><thead><tr><th scope="col">平台</th><th scope="col">配置方式</th></tr></thead><tbody><tr><td>QQ</td><td>点<strong>连接</strong>后向导直接显示二维码，用手机 QQ 扫码并确认，机器人会自动创建并配置，扫码人成为机主。也可以改为<strong>手动填写 AppID / AppSecret</strong>，保存前会先验证。未经个人认证的机器人只有管理员本人能使用，并且只能加入管理员担任群主的群。</td></tr><tr><td>Telegram</td><td>向导第一步说明如何在 @BotFather 创建机器人，粘贴 Token 后会先验证。连上后在“绑定机主”一步用手机相机扫码（Telegram 自带的扫码只能登录设备，扫不了这个），在 Telegram 里点<strong>开始</strong>即成为机主；电脑上登录了 Telegram 也可以直接点链接，或点<strong>复制链接</strong>。</td></tr><tr><td>微信</td><td>点<strong>连接</strong>后用微信扫码并在手机上确认，扫码的微信号自动成为机主，也是唯一能使用它的人。微信机器人只支持私聊；登录失效时卡片会提示，重新扫码即可。</td></tr><tr><td>飞书</td><td>在飞书开放平台创建企业自建应用、添加机器人能力并开通 im:message 等权限，填入 App ID 与 App Secret（可选飞书或 Lark）。连上之后回到开放平台，把订阅方式保存为<strong>使用长连接接收事件</strong>、添加<strong>接收消息 v2.0</strong>事件并发布版本（飞书要求长连接在线时才能保存）。</td></tr><tr><td>钉钉</td><td>在钉钉开放平台创建企业内部应用、添加机器人并选择 <strong>Stream 模式</strong>，开通机器人发送消息权限后发布，填入 Client ID 与 Client Secret。</td></tr><tr><td>Discord</td><td>在 Discord 开发者后台新建应用，在 Bot 页复制 Token 并打开 <strong>Message Content Intent</strong>，粘贴 Token 后用向导给出的邀请链接把机器人拉进服务器。私信与频道里 @机器人 都能用。</td></tr><tr><td>LINE</td><td>在 LINE Official Account Manager 建官方账号并启用 Messaging API，填入 Channel ID 与 Channel secret；在控制台打开 Use webhook、关闭自动回应。LINE 只能回调公网地址：公网地址留空时 ACECode 用 cloudflared 自动建立临时隧道（先用 <code>winget install --id Cloudflare.cloudflared</code> 安装），也可以填写自己的 HTTPS 地址。</td></tr></tbody></table></div>
+<p>默认拒绝所有人。陌生人私聊只会收到配对提示，平台卡片上出现待批准请求（Desktop 窗口不在前台时弹出系统通知），请求 10 分钟后失效。群要先批准，群里只处理 @机器人 的消息，群成员也要单独批准。飞书、钉钉、Discord、LINE 连上后，向导会给出 6 位绑定码，私聊机器人发送这串数字即成为机主（10 分钟内有效，只能用一次）。飞书和钉钉会把每条消息随机交给同一应用的某一个连接，同一个应用不要再同时接到别的工具上，否则会悄悄分走一部分消息。在卡片的<strong>管理</strong>里可以更换机器人或撤销授权；撤销会立即停止处理对方的消息，并中止其会话正在进行的回合。</p>
+<div class="table-scroll"><table><thead><tr><th scope="col">在聊天中发送</th><th scope="col">作用</th></tr></thead><tbody><tr><td><code>/help</code></td><td>列出可用命令。</td></tr><tr><td><code>/status</code></td><td>查看会话、位置、模型、是否忙碌和待处理事项。</td></tr><tr><td><code>/stop</code></td><td>停止当前回合。</td></tr><tr><td><code>/new</code></td><td>在当前会话所在的位置新建会话。</td></tr><tr><td><code>/sessions</code>、<code>/resume 编号</code></td><td>列出并切换会话；机主可以切到任意会话，其他人只能切换自己创建的会话。</td></tr><tr><td><code>/model 名称</code></td><td>从下一回合起切换模型。</td></tr><tr><td><code>/approve 编号</code>、<code>/deny 编号</code>、<code>/aq</code></td><td>处理权限请求与提问，与 Desktop 先答者生效。</td></tr></tbody></table></div>
+<p>每个私聊（或群里的每位成员）绑定一个 ACECode 会话，第一条消息会自动新建无项目会话并使用默认权限。被绑定的会话在侧栏显示电脑图标；在 Desktop 里向它输入时，回复也会发到聊天。图片和文件会导入会话附件，QQ 语音使用平台识别出的文字。通道由后台进程托管：在“常规”中勾选“退出 ACECode 后继续运行后台进程”时，关闭 Desktop 后通道仍然在线。</p>
+<aside class="note"><strong>关于 QQ 回复额度</strong><p>QQ 对每条消息的被动回复有次数与时间限制。超出后 ACECode 改发主动消息；仍被拒绝时先暂存，等对方下一条消息时补发。暂存只在内存里，后台进程重启会丢失，但会话记录完整。</p></aside></section>
 <section aria-labelledby="configure"><h2 id="configure">准备并连接消息渠道</h2><p>先按渠道插件的说明安装它的可执行程序、完成平台认证并取得 manifest 文件。ACECode 使用 <code>remote_control.channels</code> 保存插件配置，使用 <code>remote_control.default_channel</code> 指定默认渠道。只输入消息平台名称不会自动安装插件。</p>
 <div class="code-block"><div class="code-heading"><span>JSON · 合并到主配置，路径与 settings 按插件说明填写</span><button class="copy-button js-only" type="button" aria-label="复制代码"><svg class="icon" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true"><path d="M8 8h12v13H8zM16 8V3H3v13h5"/></svg><span>复制</span></button></div><pre><code>{
   &quot;remote_control&quot;: {
@@ -61,7 +67,7 @@
       <nav class="page-navigation" aria-label="文章翻页"><a class="page-link previous" href="agent-browser.html"><span>上一篇</span><strong><svg class="icon" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true"><path d="M20 12H5m6-6-6 6 6 6"/></svg>Agent 浏览器</strong></a><a class="page-link next" href="examples.html"><span>下一篇</span><strong>实战示例<svg class="icon" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true"><path d="M4 12h15m-6-6 6 6-6 6"/></svg></strong></a></nav>
       <footer class="article-footer"><span>ACECode 帮助文档</span><a href="https://github.com/tmoonlight/acecode/issues" target="_blank" rel="noopener noreferrer">反馈文档问题</a></footer>
     </main>
-    <aside class="contents-rail" aria-label="本页内容"><div class="contents-sticky"><p class="contents-title">本页内容</p><nav aria-label="文章小节"><ul><li><a href="#configure" data-toc-link>准备并连接消息渠道</a></li><li><a href="#sessions" data-toc-link>在渠道中切换会话</a></li><li><a href="#manage" data-toc-link>查看状态、解绑与手动接入</a></li></ul></nav><div class="rail-note"><span>进阶使用</span><p>循着目录逐步了解 ACECode。</p><a href="quick-start.html">前往快速开始 →</a></div></div></aside>
+    <aside class="contents-rail" aria-label="本页内容"><div class="contents-sticky"><p class="contents-title">本页内容</p><nav aria-label="文章小节"><ul><li><a href="#im" data-toc-link>连接 QQ、微信、飞书、钉钉、Telegram、Discord 与 LINE</a></li><li><a href="#configure" data-toc-link>准备并连接消息渠道</a></li><li><a href="#sessions" data-toc-link>在渠道中切换会话</a></li><li><a href="#manage" data-toc-link>查看状态、解绑与手动接入</a></li></ul></nav><div class="rail-note"><span>进阶使用</span><p>循着目录逐步了解 ACECode。</p><a href="quick-start.html">前往快速开始 →</a></div></div></aside>
   </div>
   <dialog class="search-dialog" aria-labelledby="search-title">
     <div class="search-dialog-header"><svg class="icon " width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true"><circle cx="10.5" cy="10.5" r="5.5"/><path d="m15 15 4 4"/></svg><label class="sr-only" id="search-title" for="docs-search">搜索文档</label><input id="docs-search" type="search" placeholder="搜索文档、命令或操作…" autocomplete="off" spellcheck="false"><button class="search-close icon-button" type="button" aria-label="关闭搜索"><svg class="icon " width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true"><path d="m6 6 12 12M18 6 6 18"/></svg></button></div>
diff --git a/docs/images/agent-office/native-multi-complete.png b/docs/images/agent-office/native-multi-complete.png
new file mode 100644
index 000000000..e13f56c45
Binary files /dev/null and b/docs/images/agent-office/native-multi-complete.png differ
diff --git a/docs/images/agent-office/native-multi-working.png b/docs/images/agent-office/native-multi-working.png
new file mode 100644
index 000000000..88ed457e5
Binary files /dev/null and b/docs/images/agent-office/native-multi-working.png differ
diff --git a/openspec/changes/add-pixel-agent-office-demo/.openspec.yaml b/openspec/changes/add-chat-scroll-to-bottom/.openspec.yaml
similarity index 50%
rename from openspec/changes/add-pixel-agent-office-demo/.openspec.yaml
rename to openspec/changes/add-chat-scroll-to-bottom/.openspec.yaml
index 7f2ad572a..480ad4ded 100644
--- a/openspec/changes/add-pixel-agent-office-demo/.openspec.yaml
+++ b/openspec/changes/add-chat-scroll-to-bottom/.openspec.yaml
@@ -1,2 +1,2 @@
 schema: spec-driven
-created: 2026-09-27
+created: 2026-10-01
diff --git a/openspec/changes/add-chat-scroll-to-bottom/design.md b/openspec/changes/add-chat-scroll-to-bottom/design.md
new file mode 100644
index 000000000..ad97e159f
--- /dev/null
+++ b/openspec/changes/add-chat-scroll-to-bottom/design.md
@@ -0,0 +1,32 @@
+## Context
+
+ChatView 已有尾部跟随状态机、活动展开锚定、滚动与尺寸变化测量。现有自动跟随采用 80px 近底阈值。
+
+## Goals / Non-Goals
+
+目标：提供消息区底部中央的返回按钮，点击到达底部并恢复跟随，兼容窄窗口和主题。
+非目标：修改侧聊、文件预览或现有滚动条行为。
+
+## Decisions
+
+- 显示以真实滚动距离大于 2px 为准；滚动高度、视口高度的整数取整与缩放后的滚动位置叠加时，到底后的剩余距离可能超过 1px。使用独立的 2px 容差，不复用 80px 跟随阈值，以免距离底部仍有内容时缺失入口。
+- 接入现有合帧测量，以及内容、视口尺寸变化；短会话和到底时隐藏。
+- 每次受状态保护的程序滚动后立即刷新按钮显隐，保证浏览器已经到底、没有产生额外 scroll 事件时也能更新；普通滚动和尺寸变化仍复用现有合帧测量。
+- 新增 `jump_to_tail` 状态动作。点击取消活动展开锚定，复用受状态保护的尾部滚动调度，立即滚到底；无需额外动画。
+- 36px 圆形按钮使用真实 SVG、`bg-surface`、`text-fg`、`ace-shadow-lg` 和可见键盘焦点，悬浮在消息区而非滚动内容中。
+- 以消息栏自身为定位容器，距底至少 12px；存在审查浮层时使用已测量的 `changeDockBottomPadding` 上移。
+- 运行中复用 ChatView 的 `status === 'running'`（实时 busy 或已恢复的 running 状态），不另设计时器或推断文本。按钮只替换内部图标：三个 4px 圆点按从左到右的延迟依次上跳 3px，每轮各跳一次；空闲、完成、报错或确认中断后恢复箭头。
+- 三点继承按钮主题前景色，保持 18px 图标占位与 36px 点击区域。运行中提示为“运行中”，可访问名称保持“滚动到底部”，图案对辅助技术隐藏；到底时整个按钮照常隐藏。
+- 2026-10-05 用户反馈三点完全静止：Windows 的 `SPI_GETCLIENTAREAANIMATION` 为 false，当前客户端实际提供的样式在 `prefers-reduced-motion: reduce` 下使用 `animation:none`。本次覆盖静态三点的旧约定：作为运行状态提示，减少动态效果时仅将跳动幅度从 3px 降为 1.5px，不完全停掉，不更改系统设置。三点每个占据周期的三分之一，避免原版一半周期完全静止的间歇。
+- 动画验证除关键帧时间采样外，必须观察至少两个完整周期的真实时间变化，覆盖系统默认、no-preference 与 reduce；不得仅用手动设置 animation.currentTime 的结果宣称动画会自行运行。
+
+## Risks / Trade-offs
+
+- 查看历史内容期间的新消息不得强制回到底部；按钮只观察尺寸，点击才恢复跟随。
+- 现有工作区有其他未提交修改，文案目录更新必须保留它们。
+
+## Validation
+
+运行滚动定向测试、完整 `pnpm test`、`pnpm build`、OpenSpec 严格校验和差异检查；浏览器检查显示/隐藏、点击后跟随、尺寸变化、窄屏与阴影。
+
+2026-10-04 回归：Edge 在 150% 设备比例、90% 页面缩放及小数内容/视口高度下，真实 ChatView 到底后仍报告约 1.407px 的剩余距离；原 1px 判断使按钮持续显示，重复点击也不会消失。补充可重复执行的真实 ChatView 浏览器检查，覆盖缩放误差、手动返回、点击、流式增长和会话切换。
diff --git a/openspec/changes/add-chat-scroll-to-bottom/proposal.md b/openspec/changes/add-chat-scroll-to-bottom/proposal.md
new file mode 100644
index 000000000..aa0f43296
--- /dev/null
+++ b/openspec/changes/add-chat-scroll-to-bottom/proposal.md
@@ -0,0 +1,23 @@
+## Why
+
+用户查看较早的会话内容后，需要一个明确、随手可点的入口返回最新消息。
+
+## What Changes
+
+- 消息区未到底时，在底部中央显示圆形向下箭头悬浮按钮。
+- 点击后回到底部，解除活动展开锚定并恢复后续消息跟随。
+- 复用主题通用阴影，位置避开变更审查浮层，并提供中英文可访问名称。
+- 会话仍在运行时，将按钮内的箭头替换为从左到右依次跳动的三点；结束后恢复箭头，点击行为不变。
+
+## Capabilities
+
+### New Capabilities
+- `web-chat-scroll-to-bottom`: 会话消息区回到底部入口及其显示、定位、跟随行为。
+
+### Modified Capabilities
+
+无。
+
+## Impact
+
+涉及 Web/Desktop 共用的 ChatView、滚动状态机和静态文案目录；不修改后端协议。
diff --git a/openspec/changes/add-chat-scroll-to-bottom/specs/web-chat-scroll-to-bottom/spec.md b/openspec/changes/add-chat-scroll-to-bottom/specs/web-chat-scroll-to-bottom/spec.md
new file mode 100644
index 000000000..4fae06557
--- /dev/null
+++ b/openspec/changes/add-chat-scroll-to-bottom/specs/web-chat-scroll-to-bottom/spec.md
@@ -0,0 +1,58 @@
+## ADDED Requirements
+
+### Requirement: 按钮显示与定位
+会话消息区 SHALL 在距离底部大于 2px 时显示返回底部悬浮按钮，位于消息区底部中央，使用主题通用阴影并避开变更审查浮层。空闲时显示向下箭头，运行中显示三点。2px 容差独立于自动跟随的近底阈值，用于兼容浏览器缩放和滚动指标取整误差。
+
+#### Scenario: 查看历史内容
+- **WHEN** 用户向上滚动离开底部
+- **THEN** 按钮显示且不随消息内容滚出视口
+
+#### Scenario: 无需滚动
+- **WHEN** 消息不足一屏或消息区已经到底
+- **THEN** 按钮隐藏
+
+#### Scenario: 布局和内容变化
+- **WHEN** 内容高度或消息区尺寸变化
+- **THEN** 按钮按新的真实滚动位置刷新，不主动打断历史阅读
+
+#### Scenario: 缩放后的底部取整误差
+- **WHEN** 浏览器已经到达可滚动的最大位置，但取整后的剩余距离大于 1px 且不超过 2px
+- **THEN** 按钮隐藏，重复点击或继续下滚不会残留按钮
+
+### Requirement: 返回底部并恢复跟随
+按钮 SHALL 支持鼠标和键盘激活，提供中英文可访问名称，点击后解除历史阅读锚定并滚到最新内容。
+
+#### Scenario: 从历史返回
+- **WHEN** 用户激活按钮
+- **THEN** 消息区到达底部且按钮隐藏，后续内容继续跟随
+
+#### Scenario: 程序滚动没有额外滚动事件
+- **WHEN** 返回底部的程序滚动完成，且浏览器未再触发 scroll 事件
+- **THEN** 按钮仍按实际位置立即刷新显隐状态
+
+#### Scenario: 展开活动后返回
+- **WHEN** 用户展开活动并激活按钮
+- **THEN** 活动标题锚定解除，不阻碍返回底部
+
+### Requirement: 运行中的顺序三点指示
+按钮 SHALL 在当前会话仍在推理、输出或执行任务时以三个从左到右依次跳动的圆点替换箭头，复用会话运行状态。图标切换 MUST NOT 改变按钮的位置、尺寸、可访问动作名称或点击行为，也不得自动打断历史阅读。
+
+#### Scenario: 阅读历史期间开始运行
+- **WHEN** 按钮已显示且当前会话进入运行状态
+- **THEN** 箭头变为顺序跳动的三点，按钮仍可通过鼠标或键盘返回底部
+
+#### Scenario: 本轮结束
+- **WHEN** 会话完成、报错或确认中断且按钮仍显示
+- **THEN** 动画移除并恢复向下箭头，不改变用户滚动位置
+
+#### Scenario: 减少动态效果
+- **WHEN** 系统启用了减少动态效果且会话正在运行
+- **THEN** 三点仍按顺序轻微跳动作为运行提示，跳动幅度减小而不是完全静止，点击仍回到底部，应用不更改系统动态效果设置
+
+#### Scenario: 持续运行
+- **WHEN** 用户持续查看运行中的三点
+- **THEN** 三点随真实时间循环从左到右跳动，不需要鼠标移动或新消息触发，每轮不插入长时间全部静止的间歇
+
+#### Scenario: 切换会话
+- **WHEN** 用户从运行中的会话切换到空闲会话
+- **THEN** 按钮仅反映新会话的运行状态和滚动位置，不残留旧会话的三点
diff --git a/openspec/changes/add-chat-scroll-to-bottom/tasks.md b/openspec/changes/add-chat-scroll-to-bottom/tasks.md
new file mode 100644
index 000000000..00d799451
--- /dev/null
+++ b/openspec/changes/add-chat-scroll-to-bottom/tasks.md
@@ -0,0 +1,65 @@
+## 1. 实现
+
+- [x] 1.1 接入按钮显示测量、浮层定位、通用阴影和返回底部动作，更新中英文文案。
+- [x] 1.2 验证显隐边界与恢复跟随状态，完成浏览器交互及主题/窄屏检查。
+
+## 2. 验收
+
+- [x] 2.1 运行完整 Web 测试、构建、OpenSpec 严格校验与差异检查，记录结果。
+
+## 3. 到底后箭头残留回归（2026-10-04）
+
+- [x] 3.1 修正底部容差并同步程序滚动后的按钮显隐，补充边界测试。
+- [x] 3.2 添加并运行真实 ChatView 浏览器回归，确认旧代码复现、新代码通过，覆盖缩放、手动滚动、点击返回、流式跟随和短会话。
+- [x] 3.3 运行完整 Web 测试、构建、OpenSpec 严格校验与差异检查，记录本次验收结果。
+
+## 4. 运行中的三点指示
+
+- [x] 4.1 复用会话运行状态替换按钮图标，增加从左到右顺次跳动和减少动态效果样式。
+- [x] 4.2 增加并执行真实 ChatView 状态切换、动画次序、点击、会话切换与窄屏主题回归。
+- [x] 4.3 运行前端测试、构建、OpenSpec 严格校验与差异检查，记录结果及验证边界。
+
+## 5. 三点在系统减少动态效果下静止
+
+- [x] 5.1 核对 Windows 动态效果设置及当前 daemon 实际提供的 CSS，确认静止来自 reduce 分支关闭动画，而非旧包。
+- [x] 5.2 减少动态效果时保留低幅顺次跳动，调整周期避免长时间全部静止；新增真实时间采样回归，证明旧样式失败、新样式通过。
+- [x] 5.3 完成生产组件及构建样式验证、全量前端测试、构建与文档核对，保留先前图片粘贴及弹层关闭修复。
+
+## 验证记录（2026-10-05：三点真实时间静止回归）
+
+- Windows `SPI_GETCLIENTAREAANIMATION` 实测 false，Chromium 系统默认 `prefers-reduced-motion: reduce`。旧样式在真实时间 2.6 秒、84 帧内三点位移均为 0，animationName 为 none，新增回归先失败。
+- 新样式不更改系统设置；reduce 下保留 1.5px 轻微顺序跳动，普通模式 3px；延迟改为 0/400/800ms，周期 1.2 秒，各点依次跳动，不再有半个周期全静止的间歇。
+- 生产 ChatView 浏览器回归 27 项通过，覆盖系统默认、no-preference、reduce 三种情况下至少两轮真实时间动画。关键帧采样单独检查左右顺序；不再只靠暂停/跳转关键帧验证。
+- 当前 Desktop daemon 的 HTTP 页面与本次 web/dist 构建 SHA-256 相同；解析实际响应中的 style 后独立运行，系统默认下实测三点分别移动约 1.497/1.497/1.500px，普通模式约 3px，所有动画均 running。此检查没有修改用户页面或系统配置。
+- 先前图片粘贴与图标选择层回归重新执行 13/13 通过；完整前端测试退出码 0，构建成功（3133 模块、4500 个正则兼容检查）。OpenSpec strict 与本任务差异检查通过。
+- 结果位于会话临时目录 `dot-motion-before/`、`dot-motion-after/`、`context-paste-recheck/`；服务端产物验证脚本为同目录 `verify-served-dots.mjs`。当前客户端使用本工作树的 web/dist，F5 刷新后加载新资源；未强制刷新用户正在运行的页面，也未发布新版安装包。
+
+## 验证记录（2026-10-04：运行中的三点，历史稿）
+
+- 复用既有会话运行状态，只替换圆形按钮内的 18px 图案；三个圆点依次上跳，每个相隔 200ms，周期 1.2s，不改变点击、显隐及历史阅读逻辑。减少动态效果时显示静态三点。
+- 真实 ChatView 的 Windows Chromium 浏览器检查 24 项通过，无运行时异常。覆盖推理触发、逐点动画时间采样、按钮几何不变、完成/错误/中断恢复箭头、流式输出、鼠标和键盘返回、减少动态效果、缩放取整、窄屏暗色、REST busy 快照恢复以及会话切换。
+- 滚动、架构及活动展开锚定定向测试 28 项通过；`corepack pnpm test` 全量退出码 0；`corepack pnpm build` 通过（3132 模块，4500 个正则字面量兼容性检查通过）。
+- OpenSpec 严格校验及本任务相关差异检查通过。截图与浏览器结果位于当前会话临时目录的 `chat-tail-progress/`。
+- 测试只使用隔离 API fixture 和生产前端组件，未启动、重新打包或替换已安装 Desktop，未操作用户真实会话。
+
+## 验证记录（2026-10-04：到底后箭头残留）
+
+- 修复：独立的 2px 按钮显隐容差兼容滚动指标取整；每次受保护的程序滚动后立即更新显隐，不改变 80px 自动跟随阈值与历史阅读状态机。
+- `node src/lib/chatScrollFollow.test.js`、`chatScrollFollowArchitecture.test.js`、`activityExpansionAnchor.test.js`：26 项通过。
+- 新增 `web/scripts/test-chat-scroll-to-bottom.mjs`，可使用 `ACE_PLAYWRIGHT_MODULE` 与 `ACE_CHROMIUM_EXECUTABLE` 指定现有 Playwright/Edge，无需 daemon 或真实会话。
+- 浏览器旧代码对照：`node scripts/test-chat-scroll-to-bottom.mjs --baseline` 在“点击到达缩放后的最大滚动位置却仍显示按钮”处按预期失败，当时剩余距离约 1.148px；直接布局探测也复现过约 1.407px 的误差。
+- 浏览器新代码：同一脚本 12 项通过，无运行时错误。覆盖初始化、缩放取整、点击、真实鼠标滚轮、24px 显示、历史阅读、键盘返回、流式跟随、无 scroll 事件的程序滚动、窄屏暗色和短会话。窄屏用例在响应式布局稳定后重新建立历史阅读前置状态。
+- `pnpm test`：2983 个 `[pass]`，退出码 0。
+- `pnpm build`：通过，4498 个正则字面量兼容性扫描通过。
+- `openspec validate add-chat-scroll-to-bottom --strict`、`git diff --check`：通过；Impeccable detector 返回空问题列表。
+- 浏览器截图、测试和构建日志位于系统临时目录 `acecode-tail-visibility-20261004`。本次仅修改并验证当前检出的 Web 源码，未重新打包或替换已安装 Desktop。
+
+## 验证记录（2026-10-01）
+
+- `node src/lib/chatScrollFollow.test.js`、`chatScrollFollowArchitecture.test.js`、`activityExpansionAnchor.test.js`：24 项通过。
+- `pnpm test`：完整 Web 测试通过，日志含 2907 个 `[pass]` 结果。
+- `pnpm build`：通过，构建后的正则兼容性扫描通过。
+- `openspec validate add-chat-scroll-to-bottom --strict` 与本次涉及文件的 `git diff --check`：通过。
+- Impeccable detector：本次 ChatView 扫描无问题。
+- Edge 浏览器：加载真实 ChatView 及其样式，模拟 REST/流式事件，20 项交互检查通过，无运行时错误。覆盖底部隐藏、历史显现、24px 近底位置、流式阅读不抢滚动、点击后跟随、Enter/空格、亮暗主题、390px 窄窗口、英文名称、待办浮层避让、长短会话切换、视口尺寸变化和新会话首页。
+- 浏览器使用隔离的模拟会话；未重新打包或启动安装版 Desktop。临时验收文件位于系统临时目录 `acecode-jump-tail`。
diff --git a/openspec/changes/add-desktop-im-channels/.openspec.yaml b/openspec/changes/add-desktop-im-channels/.openspec.yaml
new file mode 100644
index 000000000..e3966d7a1
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-05
diff --git a/openspec/changes/add-desktop-im-channels/design.md b/openspec/changes/add-desktop-im-channels/design.md
new file mode 100644
index 000000000..551c73bc0
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/design.md
@@ -0,0 +1,248 @@
+## Context
+
+动机见 proposal.md，行为要求见 `specs/` 下的三个能力。与实现方案直接相关的现状如下。
+
+- **WhatsApp 通道**（`src/host/channels/`）：已在 master 上。`state.cpp` / `gateway.cpp` / `runtime.cpp` / `bridge.cpp` 多处写死了 WhatsApp，包括号码格式校验、会话键前缀、目录 `channels/whatsapp`、Baileys 桥。它由 daemon worker 托管（`worker.cpp` 构造 `channels::Runtime`），配置只能用终端向导，并且只在启动时读一次。本变更不改动这部分。
+- **可复用的现有能力**：
+  - 会话侧：`SessionClient`（create / resume / subscribe / send_input / respond_permission / respond_question / abort）、`SessionRegistry::switch_model`。
+  - `/rc` 远程控制：跨工作区会话目录 `build_rc_session_catalog` 与 `rc::resume_session_target_exact`；出站有界队列 `rc::RemoteControlHub`；提问桥 `rc::ChannelQuestionBridge`；事件分类 `rc::classify_session_event`；UTF-8 安全分段 `rc::chunk_rc_session_output`。
+  - 基础设施：跨进程 OS 文件锁 `channels::OwnerLock`；原子写 `atomic_write_file(path, content, /*restrict_permissions*/true)`；代理解析 `ProxyResolver::effective(url)`。
+- **Desktop**：只运行一个共享 daemon，服务所有工作区。“退出后保留后台服务”由 `DaemonPool::set_keep_alive_on_exit` 控制。
+- **侧栏图标**：侧栏的电脑图标来自会话列表里的 `remote_control_bound` 字段。它在 `server_helpers.cpp` 中按 `cfg.remote_control.bound_session_id` 计算，并会附带触发 `/rc` 专属的界面行为。
+- **依赖**：vcpkg 的 curl 是 8.19.0，当前启用的特性是 `core;non-http;ssl;sspi`，没有开 WebSocket；端口本身提供 `websockets` 特性，对应 `CURL_DISABLE_WEBSOCKETS`。仓库里没有 WebSocket 客户端库，也没有 AES-GCM 实现。
+- **参照实现**：
+  - Hermes：`gateway/platforms/qqbot`、`plugins/platforms/telegram`。
+  - WorkBuddy 5.6.2：解包 `app.asar`，读了 `main/server.js` 里的 `QQBindService`、`QQBotClient`、`QQBotApi`，以及腾讯官方的 `@tencent-connect/qqbot-connector` 1.1.0。该包没有开源许可，只参考协议，不复制代码。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 平台无关的通道核心与具体平台的传输层彻底分开：新增一个平台，只需实现传输接口并补一张设置卡片。
+- QQ 与 Telegram 全部用 C++ 原生实现，不需要 Node 或 Python。
+- 核心状态机（网关会话、回复预算、限速、格式转换、命令解析、访问控制）是不碰 IO 的纯逻辑，可以离线单测。
+- 本期只在 Windows 上做构建与实测；代码保持三平台可编译，CI 照常构建。
+
+**Non-Goals:**
+- 把 WhatsApp 迁到新核心。后续单独立变更，见 Migration Plan。
+- `/rc` 远程控制的任何改动。
+- Telegram 托管机器人（像 Hermes 那样运营一个管理机器人）、QQ 频道、语音合成、流式消息编辑、按钮交互。
+
+## Decisions
+
+### D1. 新核心与 WhatsApp 并存，不重构旧代码
+新核心放在 `src/host/channels/core/`，和现有的 `gateway.*` / `runtime.*` 等文件并列，互不调用。WhatsApp 的配置目录、归属锁、终端命令一律不动。
+- 备选：现在就把 WhatsApp 改到新核心上。否决的原因有三：用户要求“先不动”；它从未做过真实账号验收；一旦改坏，回归不可见。
+- 代价：短期内有两套相似的绑定和投影逻辑。新核心把 WhatsApp 网关里的出站投影模式（每个绑定一个 `RemoteControlHub` 加一个 `ChannelQuestionBridge`）抽成可复用组件，以后迁移 WhatsApp 时直接套用。
+
+### D2. 分层与模块位置
+
+| 位置 | 内容 |
+| --- | --- |
+| `src/base/network/websocket_client.*` | 基于 libcurl 的通用 WebSocket 客户端：`CURLOPT_CONNECT_ONLY=2` 加 `curl_ws_send` / `curl_ws_recv`。代理沿用 `ProxyResolver`，Windows 上沿用 NoRevoke。读操作带超时并可中止。限制单帧大小，处理 ping/pong 与 close 帧。 |
+| `src/base/platform/crypto/aes_gcm.*` | 只做 AES-256-GCM 解密。Windows 用 BCrypt，其他平台用 OpenSSL EVP。 |
+| `src/adapters/im/`（新模块） | 平台传输层，不了解 ACECode 会话。包括统一传输接口 `im/transport.hpp`、`im/qqbot/*`、`im/telegram/*`，以及公共的文本分段与 Markdown 处理。 |
+| `src/host/channels/core/` | 通道核心：宿主与生命周期、会话绑定路由、IM 内命令、访问与配对、配置与状态存储、出站投影。 |
+| `src/apps/web/routes/routes_channels.cpp` + `handlers/channels_handler.*` | REST 与 WS 事件，校验与 JSON 整形写成纯函数。 |
+| `src/apps/daemon/worker.cpp` | 装配，并在关闭序列里加一步。 |
+| `web/src/lib/channelsSettings.js` + `components/ChannelsSettings.jsx` | 设置页，逻辑写在纯函数里。 |
+
+- 新增 adapters 模块需要在 `src/layers.tsv` 增加一行：`src/adapters/im/`，模块名 `im`，rank 32。
+- 传输层只依赖 base，核心依赖 adapters/im、domain/session 与 host/remote_control，方向都向下。
+- `cmake/acecode_layer_libraries.cmake` 中，传输层归 `acecode_adapters`，核心归 `acecode_host`。
+- 备选：传输层也放进 `host/channels`，像 WhatsApp 的 bridge 那样。否决的原因：分层文档规定外部服务集成属于 adapters；放进 adapters 后，传输层不能引用会话，解耦由编译器保证。
+
+### D3. 传输接口
+`im::Transport` 是统一的传输接口：
+- **生命周期**：`start(callbacks)` / `stop()`，以及 `status()` 快照，状态取值为 `connecting` / `connected` / `retrying` / `failed`，附原因，并标明是否已停止重试。
+- **入站**：入站消息统一为 `im::Inbound`，字段包括：会话地址（平台、账号、聊天类型、聊天 ID、发言人 ID）、消息 ID、文字、是否 @、引用、附件描述（含语音识别文字）、平台原始的回复上下文。
+- **出站**：`send_text(address, text, reply_context)`、`send_file(address, path, name, mime, reply_context)`、`set_typing(address, on)`、`download(attachment) -> 本地临时文件`。
+- **能力声明**：每个平台声明 `max_text_units`、`batch_turn_output`、`supports_typing`、`max_upload_bytes` 等，核心据此决定分段与是否按回合合并。
+
+回复预算、限速、格式转换都由各传输层内部完成，核心不需要知道 QQ 的被动回复规则。
+
+### D4. 跨进程归属：每个平台账号一把锁
+- **锁文件**：`~/.acecode/channels/<platform>/owner.lock`，复用 `channels::OwnerLock`。
+- **取锁**：平台开关打开后才去取锁。取锁失败时，平台进入“由其他 ACECode 进程托管”状态，每 5 秒重试一次，持有者退出后自动接管。持有者把自己的 PID 写进 `owner.json`，供页面显示。
+- **释放**：关闭开关或进程退出时，先停传输层、退订会话，再释放锁。
+- **Telegram 的额外检测**：平台返回 409（另一个程序在轮询）时，也按“被占用”处理，这样可以覆盖 ACECode 以外的程序。
+- 备选：所有平台共用一把锁。否决的原因：QQ 和 Telegram 应当能分别由不同进程托管，单个平台故障也不应牵连另一个。
+
+### D5. 配置与状态存储
+每个平台一个目录：`~/.acecode/channels/qq/`、`~/.acecode/channels/telegram/`。
+
+| 文件 | 内容 | 写入时机 |
+| --- | --- | --- |
+| `config.json` | 开关、凭据、机主、已批准的联系人与群、平台选项 | 只在设置页的显式操作时写，私有权限原子写入 |
+| `state.json` | 会话绑定、每个 IM 会话创建过的会话列表、去重回执环（4096 条）、Telegram 的 update offset | 运行时写入 |
+| 内存，不落盘 | 配对请求（10 分钟过期）、机主绑定码、QQ 暂存待补发的输出 | — |
+
+- **文件损坏**：一律拒绝启动该平台，并在页面显示错误，不静默重置。这与 WhatsApp 的做法一致。
+- **会话地址键**：用结构化的 JSON 数组，例如 `["qq",app_id,"group",group_openid,member_openid]`、`["telegram",bot_id,"private",user_id]`。群成员地址里带上群 ID，因为 QQ 的群成员身份按群区分。
+- **接口返回**：只给出凭据的脱敏值（例如 `****abcd`）。日志与错误文本统一经过脱敏函数，Telegram 的 `bot<token>` URL 片段同样处理。
+
+### D6. 会话绑定与切换
+- **首条消息**：调用 `create_session(no_workspace=true, permission_mode="default", inherit_dangerous_mode=false)`，与 WhatsApp 一致。先写入绑定，再提交输入。
+- **`/new`**：读取当前绑定会话的工作区（cwd / workspace_hash），在同一位置新建；当前是无项目会话时，就新建无项目会话。
+- **`/sessions`、`/resume`**：
+  - 机主：复用 `build_rc_session_catalog`，覆盖活跃会话、已登记工作区和无项目会话，排除已归档会话与子代理会话；选中后用 `resume_session_target_exact` 恢复。
+  - 非机主：只能看到 `state.json` 中记录的“本 IM 会话创建过的会话”。
+  - 列表结果按 IM 会话保存快照，编号只对最近一次列表有效。
+- **忙碌判断**：用 `SessionInfo.busy`。会话忙碌时拒绝 `/new` 与 `/resume`，避免旧会话在后台无人看管地继续执行。
+- **绑定转移**：维护一张反向索引“会话 → IM 会话”。绑定转移时，先退订旧的出站投影，向原 IM 会话发提示，再建立新投影。所有操作都带代次号，旧代次的事件一律丢弃，做法同 `/rc` 的 binder。
+- **权限模式**：恢复已有会话时沿用该会话自己的权限模式（那是机主自己设置的），但同样不继承 daemon 进程级的危险标志。
+- **普通文本的技能展开**：复用 Web 输入的 `try_expand_skill_command`，按会话的工作区扫描技能，保证 IM 与 Web 的行为一致。
+
+### D7. 命令解析是纯逻辑
+新增 `channels/core/commands.*`：输入文本和发送者角色（机主或普通联系人），输出命令种类、参数，或“用法错误”。
+- `/sessions` 的 `more` / `search` 与编号选择，复用 `parse_rc_session_command` 的语义。
+- `/aq`、`/approve`、`/deny` 沿用 WhatsApp 网关已有的处理方式。
+- 系统回复文案集中放在 `channels/core/texts.*`，统一为中文，方便以后接入多语言。
+
+### D8. 出站投影
+- **事件分流**：每个绑定一个投影器，订阅会话事件。
+  - 助手文本：经 `classify_session_event` 判定后投递。
+  - 附件：来自 `output_attachments_from_content_parts`，以及 ToolEnd 事件里的 attachments。发送前必须重新解析，确认文件在该会话自己的附件目录内，与 WhatsApp 的做法一致。
+  - 权限请求、提问：同 WhatsApp 网关。
+- **订阅顺序**：先订阅，再读取待处理的请求快照，避免漏掉中间产生的请求。
+- **按回合合并**：平台声明了 `batch_turn_output`（QQ）时，同一回合的助手文本先缓存。遇到回合结束、需要发权限请求或提问、或者缓存超过上限，就合并成段发出。Telegram 收到即发，忙碌期间每 4.5 秒发一次“正在输入”。
+- **发送队列与失败统计**：发送经 `RemoteControlHub` 的有界 FIFO。失败计入该绑定的 `failed` / `dropped` 计数，在设置页显示；发送结果不确定时不重发。
+- **Desktop 输入同步**：在 Desktop 里向已绑定会话输入时，因为投影器订阅的是会话事件，回复会自然发到 IM，不需要额外处理。
+
+### D9. QQ 扫码绑定协议
+协议细节从 WorkBuddy 内置的官方 connector 中读取，并与 Hermes 交叉印证。
+- **申请任务**：`POST https://q.qq.com/lite/create_bind_task`，请求体 `{"key": base64(32 字节随机密钥)}`，返回 `{"retcode":0,"data":{"task_id":...}}`。
+- **二维码**：内容为 `https://q.qq.com/qqbot/openclaw/connect.html?task_id=<id>&source=acecode&_wv=2`。
+- **轮询**：每 2 秒 `POST https://q.qq.com/lite/poll_bind_result {"task_id":...}`，返回的 `status` 含义：0 无、1 进行中、2 完成、3 过期。完成时附带 `bot_appid` 与 `bot_encrypt_secret`。
+- **解密**：把 `bot_encrypt_secret` 做 base64 解码，按“前 12 字节 IV、末尾 16 字节认证标签、中间是密文”切分，用本地密钥做 AES-256-GCM 解密。
+- **过期**：重新申请任务，二维码随之刷新。整个流程 10 分钟超时。
+- **请求头**：带 `Accept: application/json`。缺少它时，q.qq.com 会返回反爬页面（见 Hermes 的注释）。还要带 `User-Agent: ACECode/<版本>`。
+- **机主**：若返回结果里有 `user_openid`（Hermes 会读这个字段），扫码人直接成为机主。若没有，扫码成功后 10 分钟内第一个私聊的人自动成为机主。对未认证的新机器人来说，只有管理员本人能私聊，所以这个人就是扫码人。之后的其他人一律走配对审批。
+- **在 daemon 中执行**：页面通过 REST 发起或取消扫码，二维码刷新与扫码结果通过 WS 推送。同一时间只允许一个扫码流程。
+- 备选：在前端调用这些接口。否决的原因：密钥和解密都应留在 daemon 中，浏览器也受跨域限制。
+
+### D10. QQ 网关与回复预算
+- **网关状态机**（纯逻辑）：
+  - 握手：Hello，然后 Identify 或 Resume。intents 只订阅 `1<<25`，即单聊与群聊，不含频道。
+  - 心跳：按 `heartbeat_interval` 的 80% 发送。
+  - 记录收到的 seq，Resume 时要用。
+  - 收到 op 7 时重连，op 9 时按可否恢复分别处理。
+- **关闭码**：按 WorkBuddy 已验证的表分类。
+  - 4004：刷新令牌后重连。
+  - 4006 / 4007 / 4009：重新 Identify。
+  - 4008：等 60 秒再连。
+  - 4900–4913：不可恢复会话，重新 Identify。
+  - 4914（仅沙箱或机器人不在线）、4915（已封禁）：停止重试。
+- **令牌**：在到期前 5 分钟刷新。
+- **回复预算**（纯逻辑，按入站 msg_id 记账）：私聊 60 分钟内最多 4 条，群聊 5 分钟内最多 5 条。超出后改发主动消息。主动消息也被拒绝时，暂存到该 IM 会话的待补发队列（最多 20 条），等下一条入站消息到来时先补发，再处理新消息。所有发送共用一个全进程单调递增的 `msg_seq`，避免 40054005（消息被去重）。
+- **发送失败按错误码分类**：若平台判定窗口已过，立即降级为主动消息，不依赖本地计时。这样即使官方文档里“60 分钟还是 5 分钟”的矛盾没有定论，行为也是对的。
+- **不发“正在输入”**：QQ 的“正在输入”（msg_type 6）可能占用被动回复的额度，本期不发，待真实验收后再评估。
+- **格式**：默认用 Markdown（msg_type 2）。失败时去掉标记，改用纯文本（msg_type 0）。单条文本上限按 4000 字符分段。
+- **媒体**：
+  - 入站：从 attachments 的 url 下载，上限 25 MiB；语音直接使用 `asr_refer_text`。
+  - 出站：先用单聊或群聊的 `/files` 上传，拿到 `file_info`，再以 msg_type 7 发送。本期用 base64 直传，超出直传上限时改为文字说明；分片上传留给后续。
+
+### D11. Telegram
+- **校验**：用 `getMe` 校验 token，同时读出 `username`，以及隐私模式状态 `can_read_all_group_messages`。
+- **长轮询**：`getUpdates`，参数 `timeout=25`（不少代理会在 30–60 秒后断开空闲连接），只订阅 message。每批处理完先持久化 offset，再确认下一批。
+- **409 冲突**：错误描述含 webhook 时，进入“已配置 webhook”状态；用户在页面确认后，才调用 `deleteWebhook`。其他 409 视为被另一个程序占用，每 60 秒重试一次。
+- **机主绑定链接**：`https://t.me/<username>?start=<一次性码>`，码为 24 位 URL 安全字符，10 分钟有效。识别到 `/start <码>` 后，立即把发送者设为机主。页面上把链接画成二维码。
+- **群里判定为 @ 的情况**：entities 或 caption_entities 中有指向本机器人的 `mention` 或 `text_mention`；`/cmd@本机器人`；`reply_to_message.from.id` 是本机器人。在话题群里，回复带上 `message_thread_id`。
+- **格式**：Markdown 转 Telegram HTML，这是纯函数。代码块转为 `<pre><code>`；行内代码、粗体、斜体、删除线、链接分别转成对应标签；标题转为粗体；列表转为符号行；所有文本转义 `& < >`。为避免把标签切断，先按段落把 Markdown 源文本切成 3500 个 UTF-16 单位以内的块，再逐块转换。平台返回 “can't parse entities” 时，改用纯文本重发。
+- **限速**（纯逻辑）：同一聊天至少间隔 1 秒，同一个群每分钟不超过 20 条。收到 429 时按 `retry_after` 等待后重发；429 表示平台明确拒绝了该消息，所以重发是安全的。
+- **媒体**：
+  - 入站：照片取不超过 20 MB 的最大尺寸，通过 `getFile` 加文件 URL 下载。
+  - 出站：用 cpr Multipart 调 `sendPhoto` / `sendDocument`；图片超过 10 MB 时改为按文件发送。
+
+### D12. Web 与 Desktop
+- **导航**：设置导航「集成」分组加入 `{key:'channels', label:'消息通道'}`。
+- **页面**（2026-10-05 验收反馈后改版，仿 WorkBuddy「远程通道」）：样式按 `acecode-frontend-style`。
+  - 两列平台卡片，每张只有单色图标（默认聊天图标，不用彩色品牌 logo）、名称、一句说明和一个按钮。没开时按钮是「连接」，开着时是「取消连接」，点击立即生效。
+  - 卡片上只显示一行简要状态：连接中、已连接（附机器人名）、连接中断正在重试、连接失败（附「处理」入口）、由其他进程托管。另外显示待批准请求，可以直接批准或拒绝。已配置的平台有「管理」入口，打开后可以更换机器人，或撤销机主与授权名单。
+  - 「连接」在没有凭据或没有机主时打开分步向导，凭据与机主都齐时直接连接。向导分三步：
+    1. 创建机器人：QQ 打开即获取二维码，可改为手动填写；Telegram 说明 BotFather 的步骤并粘贴 token。
+    2. 连接：自动开启，连上后自动进入下一步；失败时可以重试，webhook 阻塞时可以移除。
+    3. 绑定机主：Telegram 显示一次性链接与二维码，提示用手机相机扫；QQ 扫码时已带出机主，或提示私聊后批准请求。
+  - 页面顶部一句话提示 Desktop 退出与“退出 ACECode 后继续运行后台进程”的关系。WhatsApp 说明与已绑定会话列表不再放在页面上：侧栏电脑图标已能找到绑定会话。
+  - 备选：保留开关加整块细节（v1）。否决，因为用户验收时认为太复杂，要求“细节打印到日志里”。
+- **日志**：`core/state_log.cpp` 比较同一平台前后两份快照，在每次 `publish_state` 时把变化写进 daemon 日志。内容包括状态与原因、平台附加信息（隐私模式、webhook、暂存待补发）、凭据更新（只记“已更新”，不写尾号）、机主与机主窗口、授权名单、待批准请求、会话绑定与收发计数。另外几处也写日志：入站消息的判定原因（只记来源与长度，不记内容）、IM 命令、QQ 扫码各阶段（不记二维码内容）、QQ 被动回复降级、暂存与补发、超大文件改发说明、Telegram 限频与 HTML 回退。
+- **二维码**：用无依赖的 MIT 库 `qrcode-generator` 在前端生成内联 SVG。
+- **REST 接口**（只接受本机来源，非本机返回 403，做法同 `routes_pty`）：
+
+  | 方法与路径 | 用途 |
+  | --- | --- |
+  | `GET /api/channels` | 返回各平台快照 |
+  | `POST /api/channels/:platform/enabled` | 开关 |
+  | `PUT /api/channels/:platform/credentials` | 保存凭据，先校验再保存 |
+  | `POST` / `DELETE /api/channels/qq/bind` | 发起或取消扫码 |
+  | `POST /api/channels/telegram/owner-link` | 生成机主绑定链接 |
+  | `POST /api/channels/telegram/remove-webhook` | 显式移除 webhook |
+  | `POST /api/channels/:platform/requests/:id/{approve,reject}` | 审批配对请求 |
+  | `DELETE /api/channels/:platform/access/:id` | 撤销授权 |
+
+- **WS 事件**：`channels_state`（平台快照变化）、`channels_bind`（二维码刷新、成功、失败）、`channels_request`（新的配对请求，App 层监听后经 `desktopNotify` 弹系统通知）。
+- **侧栏**：会话列表新增字段 `channel_bound: {platform}`，值来自核心的“已绑定会话”快照。侧栏在 `remote_control_bound || channel_bound` 时显示同一个电脑图标，悬停提示写明来自哪个平台。`/rc` 的专属行为仍然只看 `remote_control_bound`。
+  - 备选：直接把通道绑定也写进 `remote_control_bound`。否决的原因：这会误触发 `/rc` 的会话选择提示和动画语义。
+- **接口文档**：同步到 `docs/daemon-api.md`。
+
+### D13. 依赖变更
+- **curl 开启 WebSocket**：在 `vcpkg.json` 中加入 `{"name":"curl","features":["websockets"]}`。cpr 链接的就是这份 curl，所有三元组都会以带 WebSocket 的 curl 重新构建。
+- **OpenSSL**：在非 Windows 平台上，把 OpenSSL::Crypto 显式链接给 AES-GCM 所在的库。
+- 备选：通过 FetchContent 引入 IXWebSocket 或 mbedTLS。否决的原因：curl 本身已经提供 WebSocket，代理与 TLS 行为能和现有 HTTP 请求完全一致；而且用户明确要求打开 curl 的特性。
+
+### D15. 更多平台:微信、飞书、钉钉、Discord、LINE(2026-10-06)
+用户要求参考 hermes-agent 再接五个平台。协议细节先由调研整理成规格(来源:hermes-agent 适配器、各平台官方 SDK 与文档),
+再按 QQ / Telegram 的分层实现:传输层在 `src/adapters/im/<平台>/`,核心不认识平台差异。
+- **平台描述表**:`core/platforms.{hpp,cpp}` 集中列出平台名、展示名、凭据字段(是否密钥、是否必填、是否由用户填写)、
+  账号字段、群成员身份是否按群隔离(只有 QQ)、用户 id 是否按机器人隔离(换机器人时清空名单)、机主绑定方式、
+  是否有扫码流程。运行时、宿主、Web 接口与日志都从这里取,不再写死 qq / telegram。
+  传输层的创建、凭据校验与扫码流程集中在 `core/platform_adapters.cpp`,这是唯一认识各平台类型的地方。
+- **接入方式**(全部由本机主动连出,LINE 除外):
+  - 微信:腾讯 iLink 接口,扫码登录拿到机器人令牌与扫码人(即机主),长轮询收消息,只有私聊;媒体经 CDN,
+    用 AES-128-ECB 加解密(新增 `platform/crypto/aes_ecb`、`digest`)。
+  - 飞书:先调长连接地址接口,再连 WebSocket;帧是 protobuf,手写编解码(`WebSocketClient` 新增 `send_binary`);
+    每个事件帧立即确认。飞书要求长连接在线时才能保存“使用长连接接收事件”,所以向导在连接一步之后列出回后台要做的事。
+  - 钉钉:Stream 模式,每次连接先申请一次性票据;回复优先走消息自带的会话回调地址,过期后改用机器人接口。
+  - Discord:网关 JSON 协议(不压缩),意图 GUILDS | GUILD_MESSAGES | DIRECT_MESSAGES | MESSAGE_CONTENT;
+    优先续连,保护每日登录额度;校验时取应用 id,向导给出邀请链接。
+  - LINE:只有回调。分层规则 R7 不允许 adapters 引入 Crow,所以回调服务的接口定义在 `im/line/line_webhook.hpp`,
+    Crow 实现在 `core/line_webhook_server.cpp`(channels 模块允许 Crow)。回调服务只监听 127.0.0.1、只开放回调 /
+    健康检查 / 媒体三个路径;公网转发绝不能指向 daemon 主端口(本机请求不验令牌,会把终端等接口暴露出去)。
+    公网地址由用户填写,留空时自动启动 cloudflared 临时隧道;每次连接都用接口更新 LINE 的回调地址。
+  - 备选:LINE 回调直接挂在 daemon 主服务上。否决,原因同上。
+- **机主绑定**:新增 6 位一次性绑定码(`AccessControl::issue_owner_pin`),机主私聊机器人发送即可,适用于没有深链接的
+  飞书、钉钉、Discord、LINE;10 分钟过期、只能用一次,有未过期绑定码时私聊里猜错 10 次作废全部绑定码。
+  `/api/channels/<平台>/owner-link` 对 Telegram 返回链接、对这四个平台返回绑定码。扫码绑定接口也改为
+  `/api/channels/<平台>/bind`(QQ、微信),快照里的扫码状态改为 `binds:{平台:状态}`。
+- **可选凭据字段**:设置页显式提交空串表示清除可选字段(如 LINE 公网地址改回自动隧道);校验只规整它认识的字段,
+  用户填的其它可选设置原样保留。
+- **起草方式**:五个平台的传输层由并行子代理按统一约定起草(`scratchpad/im_transport_contract.md`),每个文件用
+  “只编译不链接”的单文件检查自查,不碰共享构建目录;核心接线、设置页、文档由主会话完成并统一构建与测试。
+
+### D14. 测试策略
+- **纯逻辑单测**：网关状态机与关闭码分类、回复预算、限速器、Markdown 转 HTML、UTF-16 分段、命令解析、访问与配对（过期、机主规则）、配置与状态的校验和损坏拒绝、绑定转移与代次丢弃、AES-GCM（官方 connector 格式的已知向量）。按仓库惯例，测试注释用中文，写清触发场景和期望行为。
+- **本机假服务**：用 Crow 搭假的 QQ OpenAPI 加 WebSocket 网关，以及假的 Telegram Bot API，端到端跑传输层：断线恢复、限频、409、webhook、媒体。核心用内存版 `SessionClient`，覆盖首条消息、`/new`、`/resume`、权限请求先答者生效、撤销授权。
+- **前端**：`channelsSettings.js` 的 Node 测试，以及侧栏图标判定测试。
+- **Windows 实测与真实账号验收**：按任务清单逐项记录到 `verification.md`。
+
+## Risks / Trade-offs
+
+- **[腾讯绑定接口无公开文档，`source=acecode` 可能不被接受，接口也可能变动]** → 手动 AppID/AppSecret 始终可用。真实验收的第一项就是验证扫码；协议常量集中在一个文件里，便于修改。
+- **[QQ 被动回复规则的文档前后矛盾，主动消息可能被用户关闭]** → 失败时按错误码立即降级；暂存后在下一条消息时补发。暂存只在内存中，进程重启会丢失，但会话记录本身是完整的，页面会显示待补发条数。
+- **[curl 开启 websockets 会改变 vcpkg 依赖构建]** → CI 依赖缓存失效一次。Deepin 和旧 glibc 打包任务需要确认仍走 vcpkg 的 curl。
+- **[凭据泄露]** → 私有权限写入，接口只返回脱敏值，日志和错误统一脱敏，Telegram 的 URL 中 token 也要脱敏。设置接口只接受本机来源。
+- **[群里有人注入提示词，或非机主借机执行命令]** → 非机主只能在自己的无项目会话中操作。权限模式是 `default`，写操作必须审批，且审批只接受发起人本人或本地操作者，沿用 WhatsApp 的规则。非机主不能切到工作区会话。
+- **[未认证的 QQ 机器人只有管理员能用]** → 页面明确提示；需要给别人用时，引导用户去做个人认证。
+- **[Desktop 退出后通道断开]** → 页面提示与“退出后保留后台服务”的关系，不擅自修改该设置。
+- **[两套绑定逻辑并存（WhatsApp 旧网关与新核心）]** → 新核心的投影组件按“可承载 WhatsApp 传输”的标准设计，后续迁移时删除旧网关。
+
+## Migration Plan
+
+- 新装与升级时，所有新平台默认关闭，不迁移任何数据。WhatsApp 的目录与行为不变。
+- 回滚：关闭开关即可停止。旧版本二进制会忽略 `channels/qq`、`channels/telegram` 目录。
+- 后续把 WhatsApp 迁入新核心另起变更：为 WhatsApp 实现 `im::Transport`（Baileys 桥或 Cloud API），一次性导入旧的 `channels/whatsapp` 配置后删除旧网关。
+
+## Open Questions
+
+- QQ OpenAPI 域名：官方文档自 2026-08 起写的是 `api.bot.qq.com`，WorkBuddy 5.6.2 仍在用 `api.sgroup.qq.com` 与 `bots.qq.com`。默认采用文档域名，旧域名作为常量备选，真实验收时确认。
+- QQ 的“正在输入”是否占用被动回复额度，真实验收后再决定是否开启。
+- QQ 大文件的分片上传（Hermes `chunked_upload.py` 可作参考）在后续变更中实现。
diff --git a/openspec/changes/add-desktop-im-channels/proposal.md b/openspec/changes/add-desktop-im-channels/proposal.md
new file mode 100644
index 000000000..e398e9c3c
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/proposal.md
@@ -0,0 +1,88 @@
+## Why
+
+ACECode 的 daemon 已能托管 WhatsApp 通道，但配置只能靠终端向导，通道核心写死了 WhatsApp，而且每个联系人只能对应一个固定的无项目会话。用户希望在 Desktop 设置页里像 WorkBuddy 一样扫码接上 QQ、填 token 接上 Telegram，开关即用，并且能在 IM 里新建、切换会话，包括切到某个工作区的会话继续工作。
+
+2026-10-06 用户要求参考 hermes-agent,把飞书、钉钉、微信、Discord、LINE 也接进同一套通道核心,让国内外常用的 IM 都能远程使用 ACECode。
+
+## What Changes
+
+- 设置页「集成」分组新增「消息通道」:QQ、微信、飞书、钉钉、Telegram、Discord、LINE 以两列卡片排列,卡片用单色聊天图标。「连接」在还没配好时打开三步向导(配置机器人 → 连接 → 绑定机主),配好的直接连接;连上后按钮变成「取消连接」。卡片只显示一行简要状态与待批准请求,连接原因、隐私模式、收发计数等细节写进 daemon 日志(2026-10-05 验收反馈)。
+- 新增平台无关的通道核心：会话绑定、IM 内命令、访问控制与配对、出站投影、持久化、跨进程单实例归属。它和现有 WhatsApp 实现并存，WhatsApp 的代码、配置和终端向导都不改。
+- QQ 官方机器人，C++ 原生实现：
+  - 用手机 QQ 扫码完成配置，走腾讯 q.qq.com 的绑定任务协议，来源名 `acecode`；扫码失败时可以手动填 AppID/AppSecret。
+  - 本机直连 WebSocket 网关，不需要公网地址。
+  - 支持私聊和群里 @机器人。被动回复窗口用尽后降级为主动消息。
+  - 用 Markdown 发送；图片、文件双向；语音消息使用腾讯自带的识别文字。
+- Telegram Bot API，C++ 原生实现：
+  - 填 BotFather 给的 token，用长轮询收消息。
+  - 机主扫码或点一次性链接即自动绑定。
+  - 支持私聊和群里 @机器人。HTML 格式化，按平台长度分段并遵守限速；图片、文件双向。
+- 微信(腾讯 iLink 机器人接口),C++ 原生实现:
+  - 用微信扫码登录,扫码的微信号自动成为机主;长轮询收消息,只支持私聊。
+  - 文字与图片、文件双向;媒体经 CDN 用 AES-128-ECB 加解密。
+- 飞书 / Lark,C++ 原生实现:
+  - 填 App ID 与 App Secret(可选飞书或 Lark),本机直连长连接收事件,协议帧手写 protobuf 编解码。
+  - 私聊与群里 @机器人;Markdown 用富文本(post)发送,图片、文件双向。
+- 钉钉,C++ 原生实现:
+  - 填 Client ID 与 Client Secret,Stream 模式本机直连收消息。
+  - 回复优先走消息自带的会话回调地址,过期后改用机器人接口;私聊与群里 @机器人,图片、文件双向。
+- Discord,C++ 原生实现:
+  - 填 Bot Token,本机直连网关;私信与服务器频道里 @机器人,Markdown 原生,附件双向,显示“正在输入”。
+- LINE Messaging API,C++ 原生实现:
+  - 填 Channel ID 与 Channel secret 换取短期令牌。LINE 只支持公网回调:daemon 另起一个只监听本机的回调服务,
+    由用户填写的公网地址或自动启动的 Cloudflare 临时隧道转发进来,每次连接都自动更新 LINE 的回调地址。
+  - 私聊与群里 @机器人;回复令牌有效时用回复接口,否则推送;图片经回调服务的媒体地址发送,文件改发文字说明。
+- 机主绑定:QQ 与微信由扫码带出;Telegram 用一次性链接;飞书、钉钉、Discord、LINE 由机主私聊机器人发送设置页给出的 6 位一次性绑定码。
+- 会话模型：
+  - 每个 IM 会话（私聊联系人，或群里的某个发言人）同一时刻绑定一个 ACECode 会话；第一条消息自动建无项目会话。
+  - 提供命令 `/new` `/sessions` `/resume` `/model` `/status` `/stop` `/help` `/approve` `/deny` `/aq`。
+  - 机主可以切到任意会话，包括工作区会话；其他联系人只能在自己的通道会话之间切换。
+- 被绑定的会话在侧栏显示和 `/rc` 相同的电脑图标。在 Desktop 里往已绑定的会话输入时，回复照常同步到 IM。
+- 网络请求跟随 ACECode 的代理设置。通道相关接口只允许本机访问。
+- 依赖：
+  - vcpkg 为 curl 打开 `websockets` 特性。
+  - 新增 AES-256-GCM 解密：Windows 用 BCrypt，其他平台用 OpenSSL。
+  - 新增 AES-128-ECB、MD5 与 HMAC-SHA256(同样 BCrypt / OpenSSL);WebSocket 客户端支持发送二进制帧。
+  - 前端新增二维码渲染。
+- 非目标（本期不做）：
+  - WhatsApp 的任何改动，包括官方 Cloud API。
+  - 企业微信、飞书与钉钉的扫码建应用(本期手填凭据);LINE 的长期隧道或公网部署(本期只提供用户自填公网地址与临时隧道两种方式)。
+  - 语音转写或合成（QQ 自带的识别文字除外）。
+  - 按钮式交互、流式输出、Telegram 话题多会话。
+  - 定时任务推送到 IM、多账号。
+  - Linux/macOS 实机验证（本期只验 Windows）。
+
+## Capabilities
+
+### New Capabilities
+- `im-channels`: 平台无关的消息通道，包括设置页开关与状态、daemon 托管与跨进程归属、IM 会话与 ACECode 会话的绑定和切换、IM 内命令、访问控制与配对、出站投影、侧栏标识、代理与本机访问限制。
+- `qq-bot-channel`: QQ 官方机器人接入，包括扫码配置与手动兜底、WebSocket 网关、私聊与群 @、被动回复窗口与降级、Markdown、媒体与语音识别文字。
+- `telegram-channel`: Telegram Bot API 接入，包括 token 配置、机主绑定链接、长轮询、私聊与群 @、格式化分段限速、媒体收发。
+- `weixin-channel`: 微信 iLink 机器人接入,包括扫码登录与机主、长轮询、私聊、媒体加解密。
+- `feishu-channel`: 飞书 / Lark 接入,包括凭据校验、长连接帧协议与确认、私聊与群 @、富文本发送、媒体收发。
+- `dingtalk-channel`: 钉钉接入,包括凭据校验、Stream 连接与确认、私聊与群 @、会话回调与机器人接口两种回复、媒体收发。
+- `discord-channel`: Discord 接入,包括 token 校验与邀请链接、网关心跳与续连、私信与频道 @、分段与限速、附件。
+- `line-channel`: LINE 接入,包括凭据与短期令牌、本机回调服务与签名校验、公网地址与临时隧道、回复与推送、媒体。
+
+### Modified Capabilities
+（无。WhatsApp 与 `/rc` 的行为保持不变。）
+
+## Impact
+
+- C++ 代码：
+  - 新增 `src/host/channels/` 下的通用核心子目录。
+  - 新增 adapters 模块 `src/adapters/im/`，承载 QQ 与 Telegram 的传输层。
+  - 新增 `src/base/network/` WebSocket 客户端和 `src/base/platform/` AES-GCM 解密。
+  - 改动 `src/apps/daemon/worker.cpp` 的装配；`src/apps/web/` 增加 REST、WS 事件，并在会话列表里标记已绑定的会话。
+  - 同步更新 `src/layers.tsv`、`cmake/acecode_layer_libraries.cmake`。
+- 前端：设置导航、通道设置组件及其纯逻辑模块、侧栏图标判定、i18n 目录。
+- 依赖：`vcpkg.json` 增加 `curl[websockets]`（CI 依赖缓存会失效一次）；`web/package.json` 增加一个二维码库。
+- 数据:`~/.acecode/channels/<平台>/`(qq、weixin、feishu、dingtalk、telegram、discord、line),凭据以私有权限保存。
+- 外部服务：
+  - q.qq.com 的绑定接口没有公开文档，可能变动。
+  - QQ OpenAPI 与网关。
+  - api.telegram.org。
+  - ilinkai.weixin.qq.com(微信 iLink,接口无公开文档)、open.feishu.cn / open.larksuite.com、api.dingtalk.com / oapi.dingtalk.com、
+    discord.com、api.line.me 与 Cloudflare 临时隧道(trycloudflare.com,官方不保证可用性)。
+- 文档：`docs/channels.md`、`docs/daemon-api.md`、帮助站。
+- 测试：C++ 单测用本地假网关和假 Bot API 服务器；前端用 Node 测试；Windows 本机构建验证，加真实账号验收。
diff --git a/openspec/changes/add-desktop-im-channels/specs/dingtalk-channel/spec.md b/openspec/changes/add-desktop-im-channels/specs/dingtalk-channel/spec.md
new file mode 100644
index 000000000..dd3b6b1df
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/specs/dingtalk-channel/spec.md
@@ -0,0 +1,40 @@
+## Purpose
+
+通过钉钉企业内部应用机器人的 Stream 模式,把钉钉私聊和群里的 @ 消息接入 ACECode 的消息通道。用户填 Client ID 与 Client Secret,连接在本机运行,不需要公网地址。
+
+## ADDED Requirements
+
+### Requirement: 凭据配置与校验
+
+钉钉卡片的连接向导 SHALL 在第一步说明创建企业内部应用、添加机器人能力、选择 Stream 模式并发布的步骤,并接受 Client ID 与 Client Secret。保存前 SHALL 换取访问令牌进行校验:失败时 SHALL NOT 保存并提示原因。所有接口返回 SHALL 检查业务错误码,不能只看 HTTP 状态。
+
+#### Scenario: 凭据错误
+- **WHEN** 用户填入错误的 Client Secret 并继续
+- **THEN** 向导提示凭据无效,原有配置不变
+
+### Requirement: Stream 连接
+
+钉钉通道 SHALL 每次连接前申请一次性连接票据,再以 WebSocket 接收消息:
+- 每条机器人消息 SHALL 立即确认,再异步处理;系统 ping SHALL 原样回应;收到断开通知时 SHALL 确认后立即用新票据重连。
+- 同一条消息 SHALL 只处理一次(按推送 id 与消息 id 双重去重)。
+- 同一个应用同一时刻 SHALL 只被一个 ACECode 进程连接。
+
+#### Scenario: 服务端要求断开
+- **WHEN** 钉钉推送断开通知
+- **THEN** 通道确认后关闭连接,并立即用新票据重连,期间的消息不重复处理
+
+### Requirement: 私聊与群 @ 消息
+
+钉钉通道 SHALL 处理私聊消息与群里 @机器人 的消息,私聊以发送人的员工 id 标识,群以会话 id 标识。
+
+#### Scenario: 私聊问答
+- **WHEN** 已授权用户私聊机器人发送文字
+- **THEN** 文字进入该用户绑定的会话,回复发回该私聊
+
+### Requirement: 回复与媒体
+
+回复 SHALL 优先发到消息自带的会话回调地址(有效期内),过期或不存在时改用机器人接口按员工 id 或群会话 id 发送,因此在 Desktop 中输入的回复与重启后的回复同样能送达。文本以 Markdown 发送并按长度分段;群消息 SHALL 遵守每分钟条数限制,等待而不是乱序。图片与文件 SHALL 双向。
+
+#### Scenario: 会话回调过期
+- **WHEN** 距离对方最后一条消息已超过会话回调地址的有效期,用户在 Desktop 中向绑定的会话输入
+- **THEN** 回复经机器人接口发到对应的私聊或群
diff --git a/openspec/changes/add-desktop-im-channels/specs/discord-channel/spec.md b/openspec/changes/add-desktop-im-channels/specs/discord-channel/spec.md
new file mode 100644
index 000000000..4d2b425eb
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/specs/discord-channel/spec.md
@@ -0,0 +1,40 @@
+## Purpose
+
+通过 Discord Bot,把 Discord 私信和服务器频道里的 @ 消息接入 ACECode 的消息通道。用户粘贴 Bot Token,连接在本机以网关 WebSocket 运行,不需要公网地址。
+
+## ADDED Requirements
+
+### Requirement: Token 配置、校验与邀请
+
+Discord 卡片的连接向导 SHALL 说明在开发者后台创建应用、复制 Token 与打开 Message Content Intent 的步骤,并接受 Bot Token。保存前 SHALL 查询机器人与应用信息以校验 Token:失败时 SHALL NOT 保存并提示原因。校验成功后 SHALL 保存机器人 id 与应用 id,向导 SHALL 给出带发消息所需权限的邀请链接。
+
+#### Scenario: 有效 Token
+- **WHEN** 用户粘贴有效 Token 并继续
+- **THEN** 向导连接网关,并显示把机器人拉进服务器的邀请链接
+
+### Requirement: 网关连接
+
+Discord 通道 SHALL 以 JSON 网关协议连接(不压缩),订阅服务器消息、私信与消息内容:
+- SHALL 按网关下发的间隔(首次带随机抖动)发送心跳,未收到确认时视为失联并重连。
+- 断线后 SHALL 优先续连原会话,失败再重新登录,登录之间留出间隔,避免耗尽每日登录额度。
+- Token 无效、权限意图未开启等不可恢复的关闭原因 SHALL 停止重连,卡片提示连接失败,原因写入日志。
+
+#### Scenario: 未开启消息内容意图
+- **WHEN** 网关以未开启消息内容意图为由关闭连接
+- **THEN** 通道停止重连,日志写明需要在开发者后台打开 Message Content Intent
+
+### Requirement: 私信与频道 @ 消息
+
+Discord 通道 SHALL 处理私信,以及服务器频道(含子区)里 @机器人 或回复机器人的消息;SHALL 忽略机器人自己和其他机器人发出的消息,并从文字中去掉对机器人的 @。私信以对方用户 id 标识,频道以频道 id 标识。
+
+#### Scenario: 频道里 @机器人
+- **WHEN** 已批准频道里的已授权成员发送 “@机器人 帮我看看”
+- **THEN** 这段文字进入该成员在该频道的会话,回复发回原频道
+
+### Requirement: 发送、限速与附件
+
+回复 SHALL 以 Markdown 原样发送,按 2000 字符上限分段,第一段引用触发消息;发送时 SHALL 禁止 @everyone 与角色提醒。平台返回限流时 SHALL 按给出的等待时间后重发且不乱序。会话忙碌期间 SHALL 显示“正在输入”。附件 SHALL 双向:入站从 CDN 下载,出站以表单上传。
+
+#### Scenario: 平台限流
+- **WHEN** 发送被返回限流及等待时间
+- **THEN** 通道按给出的时间等待后重发,后续消息顺序不变
diff --git a/openspec/changes/add-desktop-im-channels/specs/feishu-channel/spec.md b/openspec/changes/add-desktop-im-channels/specs/feishu-channel/spec.md
new file mode 100644
index 000000000..aefe2f174
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/specs/feishu-channel/spec.md
@@ -0,0 +1,41 @@
+## Purpose
+
+通过飞书 / Lark 开放平台的自建应用机器人,把飞书私聊和群里的 @ 消息接入 ACECode 的消息通道。用户填 App ID 与 App Secret,连接在本机以长连接运行,不需要公网地址。
+
+## ADDED Requirements
+
+### Requirement: 凭据配置与校验
+
+飞书卡片的连接向导 SHALL 在第一步说明创建企业自建应用、添加机器人能力与开通权限的步骤,并接受 App ID、App Secret 与版本选择(飞书或 Lark)。保存前 SHALL 用这组凭据换取租户访问令牌进行校验:失败时 SHALL NOT 保存并在向导中提示原因;App Secret 保存后页面 SHALL 只显示尾号。
+
+#### Scenario: 凭据错误
+- **WHEN** 用户填入错误的 App Secret 并继续
+- **THEN** 向导提示凭据无效,原有配置不变
+
+### Requirement: 长连接接收
+
+飞书通道 SHALL 先调用长连接地址接口,再以 WebSocket 连接接收事件。具体规则:
+- 帧格式按飞书协议的 protobuf 编解码;SHALL 按服务端下发的间隔发送 ping,并合并分片事件。
+- 每个事件帧 SHALL 立即回确认,再异步处理;同一条消息 SHALL 只处理一次,超过 30 分钟的旧事件 SHALL 丢弃。
+- 断线后按服务端给出的重连参数与递增间隔重连;凭据被拒时 SHALL 停止重连,卡片提示连接失败,原因写入日志。
+- 连接成功后,向导 SHALL 提示用户回到开放平台把订阅方式保存为“使用长连接接收事件”、添加接收消息事件并发布版本(飞书要求长连接在线时才能保存)。
+
+#### Scenario: 事件确认
+- **WHEN** 飞书推送一条消息事件
+- **THEN** 通道立即回确认帧,飞书不再重投这条事件;消息进入对应会话
+
+### Requirement: 私聊与群 @ 消息
+
+飞书通道 SHALL 处理私聊消息,以及群里 @机器人 的消息;是否 @机器人 SHALL 以机器人自己的 open_id 判定,并去掉文字里的 @ 占位符。群与群成员按通用的访问控制分别审批。
+
+#### Scenario: 群里 @机器人
+- **WHEN** 已批准群中的已授权成员发送 “@机器人 帮我看看”
+- **THEN** 这段文字进入该成员在该群中的会话,回复发回原群
+
+### Requirement: 发送与媒体
+
+回复 SHALL 以富文本(post)中的 Markdown 段发送,代码块单独成段;富文本被拒时 SHALL 改用纯文本重发。触发本回合的消息存在时第一段 SHALL 作为对它的回复。图片与文件 SHALL 双向:入站经消息资源接口下载,出站先上传再发送。
+
+#### Scenario: 富文本被拒
+- **WHEN** 某段富文本被飞书拒绝
+- **THEN** 同一段内容以纯文本送达,不丢失
diff --git a/openspec/changes/add-desktop-im-channels/specs/im-channels/spec.md b/openspec/changes/add-desktop-im-channels/specs/im-channels/spec.md
new file mode 100644
index 000000000..59574a93c
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/specs/im-channels/spec.md
@@ -0,0 +1,249 @@
+## Purpose
+
+让用户在 Desktop 或独立 daemon 中，通过 QQ、微信、飞书、钉钉、Telegram、Discord、LINE 等即时通信平台与 ACECode 会话对话。在设置页一键连接，在 IM 里新建、切换会话，并处理审批与提问。
+
+## ADDED Requirements
+
+### Requirement: 设置页一键连接
+
+设置页「集成」分组 SHALL 提供「消息通道」页面，以两列卡片列出 QQ、微信、飞书、钉钉、Telegram、Discord 与 LINE，卡片图标使用单色图标（默认聊天图标）。卡片上的「连接」在平台尚未配置凭据或还没有机主时 SHALL 打开分步连接向导（创建或扫码配置机器人 → 连接 → 绑定机主）；凭据与机主都已具备时，点击后 SHALL 立即连接。平台开启后按钮 SHALL 变为「取消连接」，点击立即断开。连接与断开都不需要额外的保存操作。
+
+卡片 SHALL 只显示一行简要状态：连接中、已连接（附机器人名）、连接中断正在重试、连接失败、由其他 ACECode 进程托管。失败原因、群隐私模式、待补发数量、会话绑定与收发计数等细节 SHALL 写入 daemon 日志，不在页面展开；日志同样 SHALL NOT 包含凭据与扫码载荷。
+
+#### Scenario: 首次连接走向导
+- **WHEN** 用户在还没有配置的平台卡片上点击「连接」
+- **THEN** 弹出分步向导，依次完成机器人配置、连接与机主绑定，全程不需要点击保存；完成后卡片按钮变为「取消连接」
+
+#### Scenario: 已配置平台一键连接
+- **WHEN** 用户在凭据与机主都已具备的平台卡片上点击「连接」
+- **THEN** daemon 立即开始连接，卡片状态依次显示“连接中”“已连接”，不弹出向导
+
+#### Scenario: 取消连接立即断开
+- **WHEN** 用户点击已连接平台的「取消连接」
+- **THEN** daemon 立即断开该平台，之后该平台收到的消息不再处理；凭据、授权名单和会话绑定都保留
+
+#### Scenario: 临时故障自动重试
+- **WHEN** 已开启的平台因网络中断或平台临时错误而断开
+- **THEN** 卡片显示连接中断并正在重试，原因写入日志，daemon 按递增间隔自动重连；用户取消连接后停止重连
+
+#### Scenario: 鉴权失败停止重试
+- **WHEN** 平台明确拒绝凭据，或报告账号被封禁
+- **THEN** 卡片显示连接失败并提供「处理」入口，原因写入日志；daemon 停止自动重连，直到用户在向导中重试或更换凭据
+
+### Requirement: 连接状态跨重启保持
+
+每个平台的开启状态、凭据、授权名单与会话绑定 SHALL 持久保存。托管通道的 daemon 启动时 SHALL 自动连接所有已开启的平台。
+
+#### Scenario: 重启后自动连接
+- **WHEN** QQ 处于开启状态时 daemon 重启
+- **THEN** 新的 daemon 启动后自动连接 QQ，原有绑定继续有效
+
+### Requirement: 由 daemon 托管且单实例
+
+消息通道 SHALL 只由 daemon 进程托管，即 Desktop 的共享 daemon 或独立运行的 `acecode daemon`；TUI 与 headless 模式 SHALL NOT 托管通道。同一平台账号在任一时刻 SHALL 只被一个 ACECode 进程连接：其他进程处于待命状态，在页面上显示“由其他 ACECode 进程托管”，并在持有进程退出后接管。
+
+#### Scenario: 第二个进程待命
+- **WHEN** 两个 daemon 进程都开启了同一个 QQ 机器人
+- **THEN** 只有先取得归属的进程建立连接，同一条消息只被处理和回复一次；另一个进程的设置页显示由其他进程托管
+
+#### Scenario: 持有进程退出后接管
+- **WHEN** 持有连接的进程退出
+- **THEN** 待命进程在有限时间内接管连接，原有绑定继续有效
+
+#### Scenario: Desktop 退出与后台服务设置
+- **WHEN** 用户退出 Desktop
+- **THEN** 若“退出 ACECode 后继续运行后台进程”已勾选，通道继续在线；未勾选时，通道随 daemon 一起断开。消息通道页面 SHALL 提示这一依赖关系
+
+### Requirement: IM 会话与 ACECode 会话绑定
+
+每个 IM 会话（与某个联系人的私聊，或某个群里的某个发言人）在任一时刻 SHALL 绑定恰好一个 ACECode 会话。未绑定的 IM 会话发来第一条被接受的普通消息时，SHALL 新建一个无项目会话并绑定。该会话使用 `default` 权限模式，SHALL NOT 继承 daemon 进程级的危险或免确认设置。绑定 SHALL 跨重启保持。普通消息 SHALL 只提交给当前绑定的会话，不得广播到其他会话。
+
+#### Scenario: 首条消息建会话
+- **WHEN** 一个已授权的联系人第一次给机器人发普通消息
+- **THEN** 新建一个无项目会话并与该联系人绑定，这条消息作为用户输入提交给该会话
+
+#### Scenario: 重启后续接
+- **WHEN** daemon 重启后，同一联系人再次发消息
+- **THEN** 消息进入原绑定会话，此前的历史保留
+
+#### Scenario: 群内按发言人隔离
+- **WHEN** 同一个群里的两个已授权成员分别 @机器人
+- **THEN** 两人各自进入自己的会话，彼此的上下文不混合
+
+#### Scenario: 绑定的会话已被删除
+- **WHEN** 联系人发消息时，其绑定的会话已被永久删除
+- **THEN** 机器人回复明确提示，引导发送 `/new` 或 `/sessions`；不静默新建会话来顶替
+
+### Requirement: 一个会话只绑定一个 IM 会话
+
+一个 ACECode 会话在任一时刻 SHALL 最多被一个 IM 会话绑定。某个 IM 会话切到一个已被其他 IM 会话绑定的 ACECode 会话时，绑定 SHALL 转移过来：原 IM 会话收到“已转到其他通道”的提示后变为未绑定状态，此后该会话的输出只发往新的 IM 会话。
+
+#### Scenario: 跨平台转移绑定
+- **WHEN** 机主在 Telegram 用 `/resume` 选中一个当前绑定在 QQ 私聊上的会话
+- **THEN** 该会话改为绑定 Telegram，QQ 私聊收到转移提示，后续回复只发到 Telegram
+
+### Requirement: IM 内命令
+
+通道 SHALL 识别以下命令，并且 SHALL NOT 把它们作为对话内容提交给模型：
+- `/help`：列出发送者当前可用的命令。
+- `/status`：显示平台、绑定会话的标题、所在工作区（或“无项目”）、模型、是否忙碌，以及待处理的审批和提问编号。
+- `/stop`：中止绑定会话正在进行的回合。
+- `/new`：在当前绑定会话所在的位置新建会话并绑定。当前在某个工作区就建在该工作区，否则建无项目会话。
+- `/sessions`：列出可切换的会话并编号，支持 `more` 与 `search <关键词>`。
+- `/resume <编号或会话 ID>`：切换绑定。
+- `/model [名称]`：不带参数时列出已保存模型并标出当前模型；带名称时为绑定会话切换模型，从下一回合起生效。
+- `/approve <编号>`、`/deny <编号>`：一次性处理绑定会话的权限请求。
+- `/aq …`：回答提问，沿用现有远程控制的语法。
+
+会话忙碌时，`/help` `/status` `/stop` `/sessions` `/model` `/approve` `/deny` `/aq` SHALL 立即处理；`/new` 与 `/resume` SHALL 被拒绝并提示先 `/stop` 或等待完成；普通消息 SHALL 按现有输入队列排队。非命令文本提交给会话前，SHALL 像 Web 输入一样展开技能命令。通道的系统回复 SHALL 使用中文。
+
+#### Scenario: 忙碌时停止
+- **WHEN** 绑定会话正在执行，用户发送 `/stop`
+- **THEN** 当前回合立即中止，机器人回复已停止，`/stop` 不出现在会话记录里
+
+#### Scenario: 忙碌时切换被拒
+- **WHEN** 绑定会话正在执行，用户发送 `/new`
+- **THEN** 机器人拒绝并提示先 `/stop` 或等待完成，绑定保持不变
+
+#### Scenario: 新会话跟随当前位置
+- **WHEN** 联系人当前绑定在工作区 W 的会话上，发送 `/new`
+- **THEN** 在工作区 W 新建会话并绑定，后续消息在 W 中执行
+
+#### Scenario: 切换模型
+- **WHEN** 用户发送 `/model <已保存的模型名>`
+- **THEN** 绑定会话从下一回合起使用该模型；名称不存在时回复错误并列出可用模型
+
+#### Scenario: 状态命令不进对话
+- **WHEN** 用户发送 `/status`
+- **THEN** 机器人回复状态信息，会话记录与模型上下文都不变
+
+### Requirement: 机主与会话切换范围
+
+每个平台 SHALL 最多有一位机主。机主 SHALL 可以列出并切换到任意普通、未归档的会话，包括其他工作区的会话和无项目会话。机主以外的已授权联系人，SHALL 只能在通过自己这个 IM 会话创建的会话之间列出和切换；切到其他会话的请求 SHALL 被拒绝。已归档会话与子代理会话 SHALL NOT 出现在任何人的列表里。
+
+#### Scenario: 机主切到工作区会话
+- **WHEN** 机主发送 `/sessions` 后用 `/resume <编号>` 选中某个工作区会话
+- **THEN** 绑定切到该会话，未活跃时先恢复它，后续消息在该工作区中执行
+
+#### Scenario: 用绑定码成为机主
+- **WHEN** 还没有机主的飞书机器人连接成功后,用户在向导里拿到 6 位绑定码,并在飞书里私聊机器人发送这串数字
+- **THEN** 该用户成为机主,向导显示绑定完成;这条消息不进入任何会话
+
+#### Scenario: 普通联系人受限
+- **WHEN** 非机主联系人用 `/resume` 指定一个不是自己创建的会话
+- **THEN** 请求被拒绝，绑定不变；该联系人的 `/sessions` 只列出自己的通道会话
+
+### Requirement: 访问控制与配对
+
+通道 SHALL 默认拒绝所有未授权的发送者。
+
+私聊：
+- 未授权者私聊时 SHALL 只收到配对提示，消息不进入任何会话，设置页出现一条待批准请求，并弹出 Desktop 系统通知。
+- 待批准请求 SHALL 在 10 分钟后过期。
+- 机主在设置页批准或拒绝。批准后，对方从下一条消息开始生效，此前的消息不补处理。
+- 一个平台还没有机主时，第一个被批准（或在配置流程中被确认）的联系人 SHALL 成为机主。配置流程中的确认方式按平台不同：QQ 与微信由扫码带出扫码人（QQ 拿不到时，接下来 10 分钟内第一个私聊的人成为机主）；Telegram 用一次性链接；飞书、钉钉、Discord、LINE 由机主私聊机器人发送设置页给出的 6 位一次性绑定码。
+- 6 位绑定码 SHALL 在 10 分钟后过期、只能使用一次，发送绑定码的那条消息 SHALL NOT 进入会话；在有未过期绑定码时，私聊里连续猜错 10 次 SHALL 作废全部绑定码。
+
+群聊：
+- 群 SHALL 先被批准。
+- 在已批准的群里，只有已授权的成员 @机器人 时才处理消息；Telegram 中回复机器人的消息视同 @。
+- 未授权成员 @机器人 时，SHALL 产生一条待批准请求，并最多得到一次限频提示。
+- 未 @机器人 的群消息 SHALL 被忽略。
+
+撤销某联系人或群的授权后，SHALL 立即停止处理其消息，并中止其绑定会话正在进行的回合。
+
+#### Scenario: 陌生人私聊
+- **WHEN** 未授权用户私聊机器人
+- **THEN** 对方收到配对提示，消息不进入任何会话，设置页出现待批准请求并弹出系统通知
+
+#### Scenario: 批准后生效
+- **WHEN** 机主在设置页批准该请求
+- **THEN** 对方的下一条消息被正常处理，批准前那条消息不被补处理
+
+#### Scenario: 群里未 @
+- **WHEN** 已批准群中的已授权成员发消息但没有 @机器人
+- **THEN** 消息被忽略，不产生回复
+
+#### Scenario: 未批准的群
+- **WHEN** 机器人在一个未批准的群里被 @
+- **THEN** 消息不被处理，设置页出现该群的待批准请求
+
+#### Scenario: 撤销授权
+- **WHEN** 机主撤销某联系人的授权时，该联系人的会话正在执行
+- **THEN** 该回合被中止，此后该联系人的消息不再进入会话
+
+### Requirement: 输出投影到 IM
+
+绑定会话的输出 SHALL 按以下方式发往 IM：
+- 发送最终的助手文本，工具调用过程不发送。
+- 会话中产生的图片和文件，在平台大小限制内以原生媒体发送。
+- 权限请求以文本发送，附 `/approve <编号>` 与 `/deny <编号>`。
+- 提问按 `/aq` 语法呈现。
+- 回合出错时发送简短的错误说明。
+
+长文本 SHALL 按平台长度上限分段，且不截断 UTF-8 字符。同一个权限请求或提问在 Desktop 和 IM 之间先答者生效，另一端收到“已处理”的提示。在 Desktop 中向已绑定会话输入时，助手回复同样发往 IM。发送失败 SHALL 计入该绑定的失败计数并写入日志；发送结果不确定时 SHALL NOT 自动重发。
+
+#### Scenario: 最终答复
+- **WHEN** 一个回合完成，并产生了较长的助手文本
+- **THEN** IM 依序收到分段后的完整文本，中间的工具调用过程没有发送
+
+#### Scenario: 先答者生效
+- **WHEN** 权限请求已发到 IM，用户先在 Desktop 中批准
+- **THEN** IM 收到该请求已处理的提示；之后在 IM 发送 `/approve <编号>` 时，得到“已处理或不存在”的回复
+
+#### Scenario: Desktop 输入同步到 IM
+- **WHEN** 用户在 Desktop 中向一个已绑定的会话发送消息
+- **THEN** 助手的回复同时发到该会话绑定的 IM
+
+#### Scenario: 发送失败可见
+- **WHEN** 平台拒绝发送某条输出
+- **THEN** 该绑定的失败计数增加，日志记下这次失败，会话本身不受影响
+
+### Requirement: 入站媒体
+
+通道 SHALL 接受 IM 发来的图片和文件。单个文件不超过 25 MiB 且不超过平台下载上限时，SHALL 导入会话附件并随消息提交给会话；模型自身的多模态能力规则照常适用。不支持的消息类型（如视频、贴纸，以及没有识别文字的语音）SHALL 得到明确的“不支持”回复，并且 SHALL NOT 影响其他会话。
+
+#### Scenario: 发送图片
+- **WHEN** 已授权联系人发送一张图片并附带文字
+- **THEN** 图片作为附件出现在 Desktop 的会话记录中，文字与图片一起提交给会话
+
+#### Scenario: 不支持的类型
+- **WHEN** 联系人发送一段视频
+- **THEN** 机器人回复暂不支持该类型，会话不收到任何输入
+
+### Requirement: 侧栏标识
+
+在 Desktop 与 Web 的侧栏中，当前被 IM 会话绑定的 ACECode 会话 SHALL 显示与 `/rc` 绑定会话相同的电脑图标，无论它属于工作区还是无项目。绑定变化后，图标 SHALL 在侧栏的下一次刷新中随之移动，不需要重新加载页面。
+
+#### Scenario: 图标随切换移动
+- **WHEN** 机主在 IM 中用 `/resume` 把绑定从会话 A 切到会话 B
+- **THEN** 侧栏中 A 的电脑图标消失，B 显示该图标
+
+### Requirement: 代理、本机访问与凭据保护
+
+通道发出的所有 HTTP 和 WebSocket 连接 SHALL 遵循 ACECode 的网络代理设置。消息通道的 REST 与 WebSocket 接口 SHALL 只接受本机来源，非本机请求返回 403。
+
+凭据保护：
+- 平台凭据 SHALL 以仅当前用户可读的方式保存。
+- 读取配置时，SHALL 只返回脱敏的展示值（如尾号）。
+- 凭据和扫码载荷 SHALL NOT 出现在日志、错误信息或任何会话内容中。
+
+#### Scenario: 跟随手动代理
+- **WHEN** ACECode 设置了手动代理
+- **THEN** 通道对 QQ 和 Telegram 的 HTTP 请求与 WebSocket 连接都经由该代理
+
+#### Scenario: 远程访问被拒
+- **WHEN** 远程 Web 模式下，非本机客户端请求消息通道接口
+- **THEN** 请求返回 403，不泄露配置
+
+#### Scenario: 凭据不回显
+- **WHEN** 设置页读取 Telegram 配置
+- **THEN** 返回的是带尾号的脱敏值，而不是完整的 token
+
+### Requirement: WhatsApp 保持现状
+
+现有 WhatsApp 通道的行为、配置文件和终端命令 SHALL 保持不变。本期的消息通道页面 SHALL NOT 管理 WhatsApp。
+
+#### Scenario: WhatsApp 不受影响
+- **WHEN** 用户已通过终端向导配置并启用 WhatsApp，然后升级到包含本变更的版本
+- **THEN** daemon 启动后 WhatsApp 的连接、授权与会话行为与升级前一致
diff --git a/openspec/changes/add-desktop-im-channels/specs/line-channel/spec.md b/openspec/changes/add-desktop-im-channels/specs/line-channel/spec.md
new file mode 100644
index 000000000..29ccd1f21
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/specs/line-channel/spec.md
@@ -0,0 +1,37 @@
+## Purpose
+
+通过 LINE Messaging API,把 LINE 私聊和群里的 @ 消息接入 ACECode 的消息通道。LINE 只能把消息推送到公网 HTTPS 地址,所以 daemon 另起一个只监听本机的回调服务,经用户的公网地址或自动建立的 Cloudflare 临时隧道接收消息。
+
+## ADDED Requirements
+
+### Requirement: 凭据配置与校验
+
+LINE 卡片的连接向导 SHALL 说明建立官方账号、启用 Messaging API、打开 Use webhook 与关闭自动回应的步骤,并接受 Channel ID 与 Channel secret(可另填长期令牌代替)。保存前 SHALL 用它们换取短期访问令牌并查询机器人信息以校验:失败时 SHALL NOT 保存并提示原因。
+
+#### Scenario: 凭据错误
+- **WHEN** 用户填入错误的 Channel secret 并继续
+- **THEN** 向导提示凭据无效,原有配置不变
+
+### Requirement: 本机回调服务与签名校验
+
+LINE 通道 SHALL 使用独立的回调服务,只监听 127.0.0.1,只提供回调、健康检查与出站媒体三个路径;公网转发 SHALL NOT 指向 ACECode 自身的本机服务端口。回调请求 SHALL 先用 Channel secret 校验签名,不通过的请求一律拒绝;通过后 SHALL 立即返回成功,再交给通道线程处理,同一事件只处理一次。
+
+#### Scenario: 伪造的回调
+- **WHEN** 公网上有人向回调地址发送签名不对的请求
+- **THEN** 请求被拒绝,内容不进入任何会话
+
+### Requirement: 公网地址与临时隧道
+
+用户填写了公网地址时,SHALL 使用它;留空时 SHALL 自动启动 cloudflared 临时隧道指向回调服务,并在隧道就绪后取得公网地址。每次连接成功后 SHALL 通过接口把 LINE 的回调地址更新为当前公网地址。既没有公网地址又找不到 cloudflared 时,SHALL 停止重连,卡片提示连接失败,日志写明安装 cloudflared 或填写公网地址的办法。
+
+#### Scenario: 自动隧道
+- **WHEN** 用户没有填写公网地址,本机已安装 cloudflared,点击「连接」
+- **THEN** 通道启动临时隧道,把回调地址更新为隧道地址后显示已连接
+
+### Requirement: 私聊与群 @ 消息、回复与媒体
+
+LINE 通道 SHALL 处理私聊消息,以及群和多人聊天里 @机器人 的消息。回复令牌仍在有效期内时 SHALL 用回复接口,否则用推送接口;推送额度用尽时 SHALL 暂存输出,等对方下一条消息时用新的回复令牌补发。文本按 5000 字分段,Markdown 转为纯文本。入站图片与文件 SHALL 下载导入会话;出站图片经回调服务的媒体地址发送,文件 SHALL 改发文字说明(LINE 机器人不能发送文件)。私聊期间 SHALL 显示加载动画。
+
+#### Scenario: 回复令牌过期
+- **WHEN** 回合耗时超过回复令牌的有效期
+- **THEN** 答复改用推送接口送达
diff --git a/openspec/changes/add-desktop-im-channels/specs/qq-bot-channel/spec.md b/openspec/changes/add-desktop-im-channels/specs/qq-bot-channel/spec.md
new file mode 100644
index 000000000..17353290f
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/specs/qq-bot-channel/spec.md
@@ -0,0 +1,117 @@
+## Purpose
+
+通过 QQ 官方机器人（QQ 开放平台 API v2），把 QQ 私聊和群里的 @ 消息接入 ACECode 的消息通道。用户用手机 QQ 扫码即可完成配置，整个连接在本机运行，不需要公网地址。
+
+## ADDED Requirements
+
+### Requirement: 扫码配置
+
+QQ 的连接向导 SHALL 以扫码为默认方式，打开第一步即获取二维码：
+
+- **生成二维码**：在本地生成一次性密钥，向腾讯的机器人绑定服务申请绑定任务，再把绑定页面地址（来源名为 `acecode`）显示为二维码。
+- **自动刷新**：二维码过期后 SHALL 自动换新。
+- **超时与取消**：整个流程 SHALL 在 10 分钟后超时，用户也可以随时取消。
+- **扫码成功**：
+  - SHALL 在本地解密得到 AppSecret，并与 AppID 一起私有保存。
+  - SHALL 自动开启 QQ 通道并开始连接。
+  - 绑定服务返回了扫码人的身份时，SHALL 把扫码人设为机主。
+- **失败与取消**：SHALL NOT 改动已有配置。
+- **保密**：二维码内容与解密得到的密钥 SHALL NOT 写入日志，也 SHALL NOT 进入任何会话。
+
+#### Scenario: 扫码成功
+- **WHEN** 用户在 QQ 卡片上点击「连接」，并用手机 QQ 扫码确认
+- **THEN** 向导进入连接一步并显示连接中，随后显示已连接；卡片按钮变为「取消连接」
+
+#### Scenario: 二维码过期
+- **WHEN** 二维码在扫码前过期
+- **THEN** 向导自动换成新的二维码，流程继续
+
+#### Scenario: 取消扫码
+- **WHEN** 用户在扫码完成前点击取消
+- **THEN** 流程停止，已有的 QQ 配置与连接状态保持不变
+
+#### Scenario: 绑定服务不可用
+- **WHEN** 申请绑定任务失败
+- **THEN** 向导显示失败原因，并提供重新获取二维码与手动填写 AppID/AppSecret 的入口
+
+### Requirement: 手动配置兜底
+
+QQ 的连接向导 SHALL 允许改为手动填写 AppID 与 AppSecret。保存前 SHALL 先用这组凭据向平台换取访问令牌进行验证：验证失败时 SHALL NOT 保存，并在向导中显示原因；验证成功后保存，并进入连接一步。
+
+#### Scenario: 凭据错误
+- **WHEN** 用户填入错误的 AppSecret 并保存
+- **THEN** 向导提示凭据无效，原有配置不变
+
+### Requirement: 网关长连接
+
+QQ 通道 SHALL 由本机主动建立到 QQ 网关的 WebSocket 连接来接收消息，不依赖公网地址或回调服务器。
+
+- **保持连接**：SHALL 按网关下发的间隔发送心跳，并在访问令牌过期前刷新它。
+- **断线恢复**：短暂断线后 SHALL 优先恢复原会话，无法恢复时重新登录；重连间隔递增。
+- **限频**：收到网关限频时 SHALL 至少等待 60 秒再重连。
+- **不可恢复的错误**：收到凭据无效、机器人被封禁、机器人仅限沙箱或不在线等关闭原因时，SHALL 停止重连，卡片提示连接失败并提供「处理」入口，原因写入日志。
+- **去重**：同一条消息 SHALL 只处理一次。
+- **标识来源**：所有请求 SHALL 标识为 ACECode 客户端。
+
+#### Scenario: 网络短暂中断
+- **WHEN** 本机网络中断几秒后恢复
+- **THEN** 连接自动恢复，卡片短暂显示连接中断后回到已连接，期间送达的消息不被重复处理
+
+#### Scenario: 机器人被封禁
+- **WHEN** 网关以机器人被封禁为由关闭连接
+- **THEN** 卡片显示连接失败，原因写入日志，daemon 不再自动重连
+
+### Requirement: 私聊与群 @ 消息
+
+QQ 通道 SHALL 处理私聊消息，以及群里 @机器人 的消息，频道类消息 SHALL 忽略。群成员的身份按群区分，因此对群成员的授权 SHALL 按“群 + 成员”记录。连接向导完成时 SHALL 提示：未经个人认证的机器人只有管理员本人能使用，并且只能加入管理员担任群主的群。
+
+#### Scenario: 私聊
+- **WHEN** 已授权用户在 QQ 私聊中发送文字
+- **THEN** 文字进入该用户绑定的会话，回复发回该私聊
+
+#### Scenario: 群 @
+- **WHEN** 已授权成员在已批准的群里 @机器人 并提问
+- **THEN** 提问进入该成员在该群中的会话，回复发回该群
+
+### Requirement: 回复窗口与降级发送
+
+对每条收到的消息，QQ 通道 SHALL 优先发送带原消息引用的被动回复，并为每次发送使用严格递增的序号，以免被平台判为重复：
+
+- 私聊：60 分钟内最多 4 条。
+- 群聊：5 分钟内最多 5 条。
+
+超出时间窗口或条数后，SHALL 改发主动消息。主动消息也被拒绝时（对方或群主关闭了主动消息，或额度用完），未送达的输出 SHALL 暂存，在该 IM 会话下一次发来消息时作为被动回复补发，并附说明。同一回合的文字输出 SHALL 先合并，再按平台长度上限分段，以减少条数。QQ 上 SHALL NOT 发送“思考中”之类的过程提示。
+
+#### Scenario: 长任务超出窗口
+- **WHEN** 一个群聊回合运行超过 5 分钟才产生最终答复
+- **THEN** 答复以主动消息发到该群，内容完整
+
+#### Scenario: 主动消息被拒后补发
+- **WHEN** 私聊答复超出回复窗口，且对方关闭了主动消息
+- **THEN** 答复暂存；对方下一次发消息时，先收到补发的答复，再处理这条新消息
+
+#### Scenario: 多条输出不触发去重
+- **WHEN** 同一条消息的回复包含一段文字和一个文件
+- **THEN** 两条发送都成功，没有被平台判为重复消息
+
+### Requirement: 消息格式
+
+QQ 通道 SHALL 默认以 Markdown 格式发送文字。平台拒绝 Markdown 发送时，SHALL 去掉 Markdown 标记，改以纯文本重发同一段内容。
+
+#### Scenario: Markdown 被拒
+- **WHEN** 某个机器人不支持 Markdown，Markdown 发送失败
+- **THEN** 同一段内容以纯文本送达
+
+### Requirement: 媒体与语音
+
+- **收图片和文件**：QQ 通道 SHALL 下载用户发来的图片和文件，每个不超过 25 MiB，并导入会话附件。
+- **收语音**：SHALL 使用平台附带的语音识别文字作为输入，并标注它来自语音；没有识别文字时 SHALL 回复不支持。
+- **发图片和文件**：会话产生的图片和文件 SHALL 通过平台的富媒体上传接口发送，不依赖公网地址；超过本期支持的大小时 SHALL 改为文字说明。
+
+#### Scenario: 发送语音
+- **WHEN** 用户发送一段平台已识别出文字的语音
+- **THEN** 识别出的文字作为输入进入会话，并被标注为来自语音
+
+#### Scenario: 回传生成的文件
+- **WHEN** 会话在回合中生成了一份报告文件并作为附件输出
+- **THEN** 该文件以 QQ 文件消息发给用户
diff --git a/openspec/changes/add-desktop-im-channels/specs/telegram-channel/spec.md b/openspec/changes/add-desktop-im-channels/specs/telegram-channel/spec.md
new file mode 100644
index 000000000..f30336cb7
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/specs/telegram-channel/spec.md
@@ -0,0 +1,101 @@
+## Purpose
+
+通过 Telegram Bot API 把 Telegram 私聊和群组里的 @ 消息接入 ACECode 的消息通道。用户粘贴 BotFather 给的 token，再扫码或点一下链接完成机主绑定。整个连接在本机运行，不需要公网地址。
+
+## ADDED Requirements
+
+### Requirement: Token 配置与校验
+
+Telegram 的连接向导 SHALL 在第一步说明如何在 @BotFather 创建机器人，并接受用户粘贴的 token。保存前 SHALL 向平台查询机器人信息，以此校验 token：
+- 校验失败时 SHALL NOT 保存，并在向导中提示原因。
+- 校验成功后，卡片 SHALL 显示机器人的 @用户名；聊天链接与群隐私模式状态 SHALL 写入 daemon 日志。
+- 群隐私模式开启（BotFather 默认）时，群里只会送达 @机器人、回复机器人的消息与命令，正好满足“群里只处理 @ 消息”；日志 SHALL 写明这一点。隐私模式关闭时机器人能收到群里的全部消息，但仍只处理 @ 它的消息。
+- token 保存后，页面 SHALL 只显示脱敏值。
+
+#### Scenario: 有效 token
+- **WHEN** 用户在向导中粘贴有效 token 并继续
+- **THEN** 卡片显示机器人的 @用户名，token 只显示尾号；聊天链接与隐私模式状态写入日志
+
+#### Scenario: 无效 token
+- **WHEN** 用户粘贴已作废的 token
+- **THEN** 向导提示 token 无效，原有配置不变
+
+### Requirement: 机主绑定链接
+
+在平台还没有机主时，连接向导的「绑定机主」一步 SHALL 显示一个一次性的机主绑定链接，并同时以二维码形式显示；SHALL 说明要用手机相机扫码（Telegram 自带的扫码只能登录设备，扫不了这个），电脑上登录了 Telegram 时也可以直接点击或复制链接。打开链接会进入与机器人的对话并带上一次性绑定码。具体规则：
+- 绑定码有效期 10 分钟，SHALL 只能使用一次。
+- 用户经该链接开始对话后，SHALL 直接成为机主并获得授权，不需要再走配对审批。
+- 过期或已用过的绑定码 SHALL 按普通的未授权私聊处理。
+
+#### Scenario: 扫码成为机主
+- **WHEN** 用户用手机扫描绑定二维码，并在 Telegram 中点击开始
+- **THEN** 该用户成为机主，机器人回复绑定成功，向导显示绑定完成与机主信息
+
+#### Scenario: 绑定码过期
+- **WHEN** 用户在 10 分钟后才使用绑定链接
+- **THEN** 该用户只收到普通的配对提示，不会成为机主
+
+### Requirement: 长轮询接收
+
+Telegram 通道 SHALL 通过本机主动发起的长轮询接收消息，不依赖公网地址或 webhook。
+- 已处理更新的位置 SHALL 持久保存，重启后不重复处理同一条消息。
+- 平台报告该机器人已配置 webhook 时，SHALL 停止轮询，卡片提示需要处理，连接向导说明原因。只有在用户明确确认后，才可以移除该 webhook 并继续连接。
+- 平台报告另一个程序正在轮询同一 token 时，SHALL 把“机器人被其他程序占用”写入日志，并以较长间隔重试。
+
+#### Scenario: 重启后不重复处理
+- **WHEN** daemon 处理完一批消息后重启
+- **THEN** 已处理过的消息不会再次进入会话
+
+#### Scenario: 已配置 webhook
+- **WHEN** 用户连接一个仍配置着 webhook 的机器人
+- **THEN** 连接向导说明原因，并提供“移除 webhook 并连接”的选项；用户点击之前不做任何移除
+
+### Requirement: 私聊与群 @ 消息
+
+Telegram 通道 SHALL 处理私聊消息，以及群组、超级群组中满足以下任一条件的消息：
+- 文字或说明里 @机器人 用户名；
+- 带机器人名的命令；
+- 回复机器人的消息。
+
+频道帖子 SHALL 忽略。在带话题的群里，回复 SHALL 发回原话题。
+
+#### Scenario: 群里 @机器人
+- **WHEN** 已批准群中的已授权成员发送 “@机器人用户名 帮我看看这个”
+- **THEN** 这段文字进入该成员在该群中的会话，回复发回原群（以及原话题）
+
+#### Scenario: 回复机器人的消息
+- **WHEN** 已授权成员在群里直接回复机器人之前的一条消息
+- **THEN** 该回复按 @机器人 处理
+
+### Requirement: 格式、分段与限速
+
+Telegram 通道 SHALL 把 Markdown 转换为 Telegram 支持的 HTML 后发送。平台报告格式解析失败时，SHALL 以纯文本重发同一段内容。长文本 SHALL 按 Telegram 单条消息的长度上限分段。
+
+限速：
+- 同一聊天中相邻两条消息 SHALL 至少间隔 1 秒。
+- 同一个群每分钟 SHALL 不超过 20 条。
+- 平台返回限频时，SHALL 按平台给出的等待时间等待后重发。
+
+会话忙碌期间，SHALL 持续显示“正在输入”状态。
+
+#### Scenario: 格式解析失败
+- **WHEN** 某段答复转换后的 HTML 被平台拒绝
+- **THEN** 同一段内容以纯文本送达，不丢失
+
+#### Scenario: 平台限频
+- **WHEN** 平台对某次发送返回限频及等待时间
+- **THEN** 通道按给出的时间等待后重发这条消息，后续消息顺序不变
+
+### Requirement: 媒体收发
+
+- **接收**：Telegram 通道 SHALL 接收照片（取不超过限制的最大尺寸）和文件。单个不超过 20 MB 时，下载并导入会话附件；超出时 SHALL 回复超出限制。
+- **不支持的类型**：语音、音频、视频和贴纸 SHALL 回复暂不支持。
+- **发送**：会话产生的图片 SHALL 以图片发送，超过图片上限时改为文件发送；其他文件不超过 50 MB 时以文件发送，超出时改为文字说明。
+
+#### Scenario: 发送文件给机器人
+- **WHEN** 已授权用户发送一份 3 MB 的 PDF
+- **THEN** 文件作为附件进入该用户绑定的会话
+
+#### Scenario: 文件过大
+- **WHEN** 用户发送一份 30 MB 的文件
+- **THEN** 机器人回复文件超出 20 MB 限制，会话不收到任何输入
diff --git a/openspec/changes/add-desktop-im-channels/specs/weixin-channel/spec.md b/openspec/changes/add-desktop-im-channels/specs/weixin-channel/spec.md
new file mode 100644
index 000000000..9fbe533f0
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/specs/weixin-channel/spec.md
@@ -0,0 +1,46 @@
+## Purpose
+
+通过腾讯 iLink 机器人接口,把微信私聊接入 ACECode 的消息通道。用户用微信扫码登录,扫码的微信号就是机主;整个连接在本机运行,不需要公网地址。
+
+## ADDED Requirements
+
+### Requirement: 扫码登录
+
+微信卡片的连接向导 SHALL 以扫码为唯一配置方式:
+- 打开第一步即向 iLink 申请登录二维码并显示;二维码过期后 SHALL 自动换新,整个流程 10 分钟后超时,用户可随时取消。
+- 扫码确认后,SHALL 保存机器人令牌、机器人 id 与接口地址,并把扫码的微信号设为机主,随后自动开启微信通道。
+- 失败、超时或取消时 SHALL NOT 改动已有配置。
+- 二维码内容与机器人令牌 SHALL NOT 写入日志。
+
+#### Scenario: 扫码成功
+- **WHEN** 用户在微信卡片上点击「连接」,用微信扫码并在手机上确认
+- **THEN** 向导进入连接一步并显示已连接;扫码的微信号成为机主,卡片按钮变为「取消连接」
+
+#### Scenario: 二维码过期
+- **WHEN** 二维码在扫码前过期
+- **THEN** 向导自动换成新的二维码,流程继续
+
+### Requirement: 长轮询接收
+
+微信通道 SHALL 通过本机主动发起的长轮询接收消息。轮询游标 SHALL 持久保存,重启后不重复处理同一条消息。接口报告登录失效时,SHALL 停止重试,卡片提示连接失败并提供「处理」入口,原因(需要重新扫码)写入日志。
+
+#### Scenario: 登录失效
+- **WHEN** iLink 报告机器人会话已失效
+- **THEN** 通道停止轮询,卡片显示连接失败;用户重新扫码后恢复
+
+### Requirement: 私聊与回复
+
+微信通道 SHALL 只处理私聊消息。回复 SHALL 携带该联系人最近一次消息里的上下文令牌;Markdown SHALL 转成纯文本,并按 2000 字分段。会话忙碌期间 SHALL 尽量显示“正在输入”。
+
+#### Scenario: 私聊问答
+- **WHEN** 机主在微信里给机器人发送文字
+- **THEN** 文字进入绑定的会话,回复以纯文本发回同一个私聊
+
+### Requirement: 媒体收发
+
+- **接收**:图片与文件 SHALL 从 CDN 下载并按协议用 AES-128-ECB 解密后导入会话附件;超出大小限制时 SHALL 回复超出限制。
+- **发送**:会话产生的图片与文件 SHALL 加密后上传 CDN,再以图片或文件消息发送。
+
+#### Scenario: 发送图片给机器人
+- **WHEN** 机主发送一张图片
+- **THEN** 解密后的图片作为附件进入绑定的会话
diff --git a/openspec/changes/add-desktop-im-channels/tasks.md b/openspec/changes/add-desktop-im-channels/tasks.md
new file mode 100644
index 000000000..60018516d
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/tasks.md
@@ -0,0 +1,144 @@
+## 1. 基础设施
+
+- [x] 1.1 `vcpkg.json` 显式加入 `curl[websockets]`，重新配置后检查 `curl-config` 的 `supported_protocols`，确认含 WS/WSS。
+- [x] 1.2 `src/layers.tsv` 登记新模块 `src/adapters/im/`（`im`，adapters，rank 32），`cmake/acecode_layer_libraries.cmake` 写好新目录的归属。验证：`layer_lint`、`check_layer_libraries.py` 通过。
+- [x] 1.3 实现 `src/base/network/websocket_client.*`（libcurl connect-only 加 `curl_ws_*`）。要求：代理走 `ProxyResolver`；Windows 上 NoRevoke；读操作带超时、可中止；处理 ping/pong 与 close；单帧大小有上限。验证：用本机 Crow WebSocket 回显服务跑的 `WebSocketClient*` 单测通过，覆盖收发、关闭、超大帧拒绝、中止读取、断线报错。
+- [x] 1.4 实现 `src/base/platform/crypto/aes_gcm.*`（Windows BCrypt，其他平台 OpenSSL EVP）。验证：`AesGcm*` 单测通过，覆盖 NIST 测试向量、connector 格式（IV、密文、认证标签依次拼接）的样例、篡改后解密失败。
+
+## 2. 传输接口与公共工具（adapters/im）
+
+- [x] 2.1 定义 `im/transport.hpp`：统一的入站与出站类型、回复上下文、状态快照、平台能力声明。实现 `im/text_chunk.*`：按 UTF-8 安全切分，按 UTF-16 单位计数，优先在段落处切。验证：`ImTextChunk*` 单测覆盖中文、emoji、超长单行、空文本。
+- [x] 2.2 实现 Markdown 工具：转纯文本（供 QQ 回退用）、转 Telegram HTML。验证：`ImMarkdown*` 单测覆盖代码块、行内代码、粗体、斜体、删除线、链接、标题、列表、`& < >` 转义、未闭合标记。
+- [x] 2.3 实现凭据脱敏工具：生成带尾号的展示值，并清除 URL 和错误文本中的 `bot<token>`、AppSecret。验证：`ImRedact*` 单测通过。
+
+## 3. QQ 传输
+
+- [x] 3.1 实现扫码绑定流程：申请任务、2 秒一次轮询、解密、过期刷新、10 分钟超时、取消；读取返回结果中的 `user_openid`；请求头带 `Accept: application/json` 和 `User-Agent: ACECode/<版本>`；HTTP 层可注入。验证：`QqBind*` 单测用假响应覆盖成功、过期、取消、服务错误；捕获日志，确认其中没有密钥和二维码内容。
+- [x] 3.2 实现 QQ OpenAPI 客户端，包括：
+  - 令牌获取，并在到期前 5 分钟刷新；
+  - 获取网关地址；
+  - 单聊和群聊的文本、Markdown 发送；
+  - 用 `/files` 上传，再以 msg_type 7 发送媒体；
+  - 解析错误码。
+
+  验证：`QqApi*` 单测在本机假 HTTP 服务上通过。
+- [x] 3.3 实现网关状态机（纯逻辑，不碰 IO）：Hello / Identify / Resume、心跳间隔、seq 记录、op 7 与 op 9 的处理、关闭码分类（4004、4006/4007/4009、4008、4900–4913、4914、4915）。验证：`QqGatewayState*` 单测逐条覆盖。
+- [x] 3.4 实现回复预算与补发：私聊 60 分钟最多 4 条，群聊 5 分钟最多 5 条；全局递增 `msg_seq`；“窗口已过”的错误码立即降级为主动消息；主动消息被拒时暂存（上限 20 条），下一条入站消息到来时先补发。验证：`QqReplyBudget*` 单测通过。
+- [x] 3.5 组装 QQ 传输层：WebSocket、状态机、OpenAPI、回复预算、Markdown 失败回退、入站附件下载（25 MiB 上限）、语音使用识别文字、消息去重；只订阅单聊与群 @ 事件。验证：`QqTransport*` 端到端测试在 Crow 搭的假网关上通过，覆盖连接、收私聊与群 @、回复、断线后 Resume、4008 延迟重连、4915 停止重试。
+
+## 4. Telegram 传输
+
+- [x] 4.1 实现 Bot API 客户端：`getMe`、`getUpdates`、`sendMessage`（HTML 与纯文本）、`sendChatAction`、`getFile` 与文件下载、`sendPhoto` / `sendDocument`（multipart）、`deleteWebhook`；能区分 409 的 webhook 与被占用两种情况，并读出 429 的 `retry_after`。验证：`TelegramApi*` 单测在假 Bot API 上通过。
+- [x] 4.2 实现更新解析：区分私聊与群聊；判定是否 @ 本机器人（entities 与 caption_entities 中的 mention、text_mention、`/cmd@bot`，以及回复机器人的消息）；提取话题 ID、`/start <码>`、照片和文件描述，并识别不支持的类型。验证：`TelegramUpdate*` 单测通过。
+- [x] 4.3 实现限速器（纯逻辑）：同一聊天至少间隔 1 秒，同一个群每分钟最多 20 条，遇 429 按要求等待后重发且保持顺序。验证：`TelegramRateLimit*` 单测用假时钟通过。
+- [x] 4.4 组装 Telegram 传输层，包括：
+  - 长轮询，offset 持久化回调；
+  - webhook 与被占用两种状态；
+  - 忙碌期间每 4.5 秒发一次“正在输入”；
+  - HTML 失败回退纯文本；
+  - 分段；
+  - 照片与文件收发，带 20 MB / 50 MB / 10 MB 上限。
+
+  验证：`TelegramTransport*` 端到端测试在假 Bot API 上通过。
+
+## 5. 通道核心（host/channels/core）
+
+- [x] 5.1 实现每个平台的配置与状态存储：`config.json` 与 `state.json` 的结构校验、私有权限原子写、文件损坏时拒绝启动、脱敏快照、去重回执环、Telegram offset。验证：`ChannelStore*` 单测覆盖损坏拒绝、并发编辑、重启后读回。
+- [x] 5.2 实现访问控制与配对，包括：
+  - 默认拒绝；
+  - 待批准请求 10 分钟过期；
+  - 机主规则：第一个获批者成为机主；QQ 扫码返回的 openid 直接成为机主；扫码后 10 分钟内第一个私聊者成为机主；Telegram 的一次性 start 码；
+  - 群与群成员分别审批；
+  - 撤销授权。
+
+  验证：`ChannelAccess*` 单测通过。
+- [x] 5.3 实现命令解析与权限：`/help` `/status` `/stop` `/new` `/sessions [more|search]` `/resume` `/model` `/approve` `/deny` `/aq`；按机主或普通联系人决定可用命令；忙碌时拒绝 `/new` 与 `/resume`。验证：`ChannelCommands*` 单测通过。
+- [x] 5.4 实现会话绑定路由：
+  - 首条消息新建无项目会话（`default` 权限，不继承危险标志）；
+  - `/new` 跟随当前绑定会话的位置；
+  - 机主用会话目录选择，非机主只能看自己创建过的会话，编号快照只对最近一次列表有效；
+  - 跨 IM 会话转移绑定，旧代次的事件丢弃；
+  - 绑定的会话已删除时明确报错；
+  - 普通文本像 Web 输入一样展开技能命令。
+
+  验证：`ChannelRouter*` 单测用内存版 `SessionClient` 通过。
+- [x] 5.5 实现出站投影：每个绑定一个有界队列和一个提问桥；投递最终助手文本；按回合合并（供 QQ 用）；发送前重新校验附件路径；投影权限请求和提问，先答者生效，另一端收到已处理提示；统计失败与丢弃；Desktop 输入的回复同步发往 IM。验证：`ChannelOutbound*` 单测通过。
+- [x] 5.6 实现平台宿主生命周期：
+  - 开关即时连接与断开；
+  - 每平台一把归属锁，取锁失败进入待命，持有者退出后接管，`owner.json` 记录 PID；
+  - 临时故障递增退避重试，致命错误停止重试；
+  - 状态变化通知；
+  - 重启后自动连接已开启的平台；
+  - 统筹 QQ 扫码流程、Telegram 机主链接与移除 webhook。
+
+  验证：`ChannelHost*` 单测通过，其中包括两个宿主在临时目录里争用同一把锁。
+
+## 6. daemon 与 Web 接口
+
+- [x] 6.1 在 `worker.cpp` 装配通道宿主：接入 `SessionClient`、权限请求快照、会话 cwd、`switch_model`、会话目录、恢复会话、技能展开、WS 广播；关闭序列增加一步，先停止接收入站消息再释放。验证：`daemon_shutdown_sequence` 相关测试通过；daemon 在通道全部关闭时正常启动、正常退出。
+- [x] 6.2 实现 `routes_channels.cpp` 与 `handlers/channels_handler.*`：所有接口只接受本机来源；凭据先校验再保存；返回值脱敏；推送 `channels_state` / `channels_bind` / `channels_request` 三类 WS 事件；会话列表加 `channel_bound` 字段。验证：handler 单测通过；`web_server_smoke_test` 覆盖非本机请求返回 403、凭据脱敏、开关往返（使用假传输层）、`channel_bound` 标记。
+- [x] 6.3 更新 `docs/daemon-api.md` 的通道接口与事件说明，并检查与实现一致。
+
+## 7. 前端
+
+- [x] 7.1 新增 `qrcode-generator` 依赖。实现 `web/src/lib/channelsSettings.js`：快照规整、状态文案、按钮可用性、扫码流程状态、WS 事件合并。验证：Node 测试登记到 `runTests.js`，`pnpm test` 通过。
+- [x] 7.2 实现 `components/ChannelsSettings.jsx`，并把「消息通道」加入设置导航。样式按 `acecode-frontend-style`，包含：
+  - 两张平台卡片；
+  - 扫码与二维码，以及手动填写；
+  - Telegram 的 token 输入、机主二维码、隐私模式提示；
+  - 授权名单、待批准请求、已绑定会话；
+  - Desktop 后台服务提示，以及 WhatsApp 的说明。
+
+  新增中文文案先补 `i18n-en-overrides.mjs`，再执行 `pnpm i18n:catalog`。验证：`pnpm test`、`pnpm build` 通过。
+- [x] 7.3 实现以下两项：
+  - App 层监听 `channels_request`，经 `desktopNotify` 弹系统通知；
+  - 侧栏在 `channel_bound` 时显示 `/rc` 同款电脑图标，悬停提示来自哪个平台，`/rc` 的专属行为仍只看 `remote_control_bound`。
+
+  验证：侧栏图标判定与通知抑制的 Node 测试通过。
+
+## 8. 文档与验证
+
+- [x] 8.1 更新文档：`docs/channels.md` 增加 QQ 与 Telegram 章节（配置、命令、授权、限制）；同步帮助站对应页面；在 `CLAUDE.md` 记录实现要点。验证：文档与实际行为逐项核对一致。
+- [x] 8.2 在 Windows 构建 `acecode`、`acecode-desktop`、`acecode_unit_tests`；运行通道、远程控制、会话相关测试和前端测试；把结果记录到 `verification.md`。
+- [ ] 8.3 在 Windows 上和用户一起做真实账号验收，结果与限制逐项记入 `verification.md`。
+- [x] 8.5 按验收反馈简化设置页（design D12）：两列卡片，单色聊天图标，「连接 / 取消连接」按钮，未配好时走三步向导；页面只留简要状态与待批准请求，细节由 `core/state_log` 等写进 daemon 日志；更正 Telegram 群隐私模式的说明（开启时 @ 消息照常送达）。验证：`ChannelStateLog*`、`ChannelAccess*` 单测与前端 `channelsSettings.test.js`（含“页面不展示细节”的守卫）通过；通道相关套件、所有权与分层检查、`pnpm test`、`pnpm build` 通过。
+
+  QQ：
+  - `source=acecode` 扫码；
+  - 私聊；
+  - 群 @；
+  - 在 IM 中审批，以及与 Desktop 的先答者生效；
+  - 超出回复窗口后的降级与补发；
+  - 图片和文件双向；
+  - 语音识别文字。
+
+  Telegram：
+  - token 校验；
+  - 扫码绑定机主；
+  - 私聊；
+  - 群 @，以及隐私模式提示；
+  - 媒体收发。
+
+  通用：
+  - `/new` 与 `/sessions` + `/resume` 切到工作区会话；
+  - 非机主切换受限；
+  - 侧栏图标随绑定移动；
+  - 开关的即时性；
+  - Desktop 退出时，“退出后保留后台服务”开与关两种情况的表现；
+  - 现有 WhatsApp 不受影响。
+- [x] 8.4 运行 `openspec validate add-desktop-im-channels --strict` 与 `git diff --check`，确认都通过。
+
+## 9. 更多平台(微信、飞书、钉钉、Discord、LINE)
+
+- [x] 9.1 平台描述表 `core/platforms.*` 与 `core/platform_adapters.*`:运行时、宿主、Web 接口改为按描述表工作;扫码与机主接口改为按平台路由(`/api/channels/<平台>/bind`、`/owner-link`);可选凭据字段可清除。验证:通道相关套件全部通过。
+- [x] 9.2 6 位一次性绑定码与防猜测(`AccessControl::issue_owner_pin`)。验证:`ChannelAccess*` 单测。
+- [x] 9.3 新增 `platform/crypto/aes_ecb`、`digest`(MD5、HMAC-SHA256),`WebSocketClient::send_binary`。验证:`CryptoDigest*`、`CryptoAesEcb*` 标准向量单测。
+- [x] 9.4 微信传输层与扫码登录(`src/adapters/im/weixin/`)。验证:协议、登录、传输层单测在假 iLink 服务上通过。
+- [x] 9.5 飞书传输层(`src/adapters/im/feishu/`,含 protobuf 帧编解码)。验证:帧编解码字节向量、传输层单测在假服务上通过。
+- [x] 9.6 钉钉传输层(`src/adapters/im/dingtalk/`)。验证:Stream 帧、回复路由、传输层单测在假服务上通过。
+- [x] 9.7 Discord 传输层(`src/adapters/im/discord/`)。验证:网关状态机、传输层单测在假网关上通过。
+- [x] 9.8 LINE 传输层、本机回调服务与 cloudflared 隧道(`src/adapters/im/line/`、`core/line_webhook_server.*`)。验证:签名校验、回调服务、隧道状态与传输层单测通过。
+- [x] 9.9 核心接线:五个平台的传输层创建、凭据校验、微信扫码流程接入 `platform_adapters.cpp`;端到端测试覆盖每个平台的连接、私聊、机主绑定码。
+- [x] 9.10 设置页:七张卡片、按平台定义的三步向导(扫码 / 填写凭据 / 连接后清单 / 绑定码),i18n 目录。验证:`channelsSettings.test.js`、`pnpm test`、`pnpm build`。
+- [x] 9.11 文档:`docs/channels.md`、`docs/daemon-api.md`、帮助站、`CLAUDE.md` 更新为七个平台。
+- [x] 9.12 Windows 构建与全量相关测试、所有权与分层检查;结果记入 `verification.md`。
diff --git a/openspec/changes/add-desktop-im-channels/verification.md b/openspec/changes/add-desktop-im-channels/verification.md
new file mode 100644
index 000000000..94f3eaedb
--- /dev/null
+++ b/openspec/changes/add-desktop-im-channels/verification.md
@@ -0,0 +1,195 @@
+# Verification: add-desktop-im-channels
+
+Date: 2026-10-05. Main checkout `N:\Users\shao\acecode` on `master` (base `a67efe55`),
+Windows 11 Enterprise 22631, MSVC Release, Ninja build directory
+`N:\Users\shao\acecode-builds\im-channels` (`-DBUILD_TESTING=ON -DACECODE_BUILD_DESKTOP=ON`,
+vcpkg `x64-windows-static`, curl 8.19 with the `websockets` feature).
+
+## Automated checks (task 8.2)
+
+- Build: `acecode`, `acecode-desktop` and `acecode_unit_tests` built successfully. The build
+  reconfigured CMake and re-embedded the Web assets after `pnpm build`.
+- Layer guards: `check_layers.py --layout final --strict`, `check_file_size.py --strict` and
+  `check_ownership.py --strict --final` report 0 findings with the new untracked sources staged
+  into a temporary index; `scripts/refactor/check_layer_libraries.py --build-dir` passes.
+- Channel tests (transports, crypto, WebSocket, core, routes):
+  `WebSocketClient*:AesGcm*:Im*:Qq*:Tg*:Telegram*:ChannelStore*:ChannelAccess*:ChannelCommands*:ChannelRouter*:ChannelOutbound*:ChannelHostTest*`
+  — 197 tests, 3 shuffled repetitions, all passed. The core subset (64 tests) also passed 25
+  shuffled repetitions; one race in a test's own wait condition was found this way and fixed.
+- Web routes: `ChannelsHandler*`, `DaemonShutdownSequence*` and the complete `WebServer*` smoke
+  suite (286 tests, which now constructs a channel host in every fixture) passed, including
+  non-local rejection with a real `127.0.0.2` source address, credential masking, switch
+  round-trip with a fake transport and the `channel_bound` session-list field.
+- Full unit suite: 5765 tests from 836 suites in 496 s — 5756 passed, 0 failed, 9 skipped by design
+  (opt-in real WhatsApp bridge/npm, native toast smoke, real image-generation and RSS network
+  smokes, a local-only JSONL replay, and two POSIX-only tests). This run includes
+  `QqTransport.OversizedFileBecomesTextNotice`, added after the repetition runs above.
+- Frontend: `pnpm test` (3040 checks) and `pnpm build` passed; `pnpm i18n:catalog` regenerated the
+  source catalog from reviewed English overrides (no machine translation).
+- Daemon smoke: an isolated daemon (temporary `USERPROFILE`, `--run-dir`, `--port`) started with
+  both channels unconfigured, served `GET /api/channels`, created no channel files, and exited
+  cleanly through `acecode daemon stop` with no errors in its log. The settings page was checked
+  in the in-app browser with unconfigured and offline-seeded (configured but switched off)
+  Telegram data: cards, manual form, approvals, bound sessions and notes render in the open-group
+  style.
+
+End-to-end (`ImChannelsEndToEnd*`, 11 tests, 3 shuffled repetitions, all passed): the production
+wiring `make_im_channel_host` with a real `SessionRegistry`/`AgentLoop` (scripted model) and the real
+QQ and Telegram transports pointed at local fake platforms. Covered without real accounts:
+
+- Telegram: wrong token rejected and not saved; real token verified by `getMe`; owner bound by the
+  `/start` code from the owner link; private question answered in Telegram HTML; group needs approval
+  and only @mentions are handled (privacy mode reported); `/sessions` + `/resume` into a workspace
+  session and `/new` in that workspace; a non-owner cannot resume the owner's session; switching off
+  stops processing immediately and switching on resumes from the saved offset; an inbound photo is
+  downloaded into the session's attachments; a tool permission approved from Telegram, and a second
+  one approved first from Desktop (`/approve` afterwards reports it was already handled; the tool runs
+  once per request).
+- QQ: QR binding against the fake portal (AES-GCM secret, owner from `user_openid`, switch turned on,
+  gateway connected); private question answered as a passive reply with the original `msg_id`; voice
+  recognition text enters the session; group and group member need separate approval and the member's
+  @ question is answered in the group; an inbound image is downloaded with the bot token and imported;
+  output refused by both passive and active sends is held and resent with `(补发)` before the next
+  message is handled.
+
+Issues found and fixed through these runs:
+
+- Telegram reported "connected" only after the first `getUpdates` long poll returned; with no
+  incoming messages a real bot would stay on "connecting" for up to 25 seconds after the switch is
+  turned on. It is now connected as soon as `getMe` succeeds
+  (`TelegramTransport.ReportsConnectedBeforeFirstLongPollReturns`).
+- QQ files above the 20 MiB direct-upload limit were counted as failures without telling the
+  contact; they are now replaced by a text notice, as the design requires
+  (`QqTransport.OversizedFileBecomesTextNotice`).
+
+Channel-related suites after these fixes (`WebSocketClient*:AesGcm*:Im*:Qq*:Tg*:Telegram*:Channel*:
+ImChannelsEndToEnd*:DaemonShutdownSequence*:WebServerHttp.Channel*:WebServerHttp.SessionListMarks*:
+RemoteControl*:SessionChannelBinder*`, including the existing WhatsApp channel tests): 411 tests,
+407 passed, 4 skipped by design (opt-in real WhatsApp bridge/npm and image-generation network
+smokes), 0 failed.
+
+No test contacts Tencent or Telegram: transports run against local fake QQ (token, gateway
+WebSocket, messages, uploads, bind portal) and Telegram (Bot API, long polling, multipart)
+servers, and the QR bind flow uses a fixed key and an AES-GCM vector computed independently.
+
+## Real-account acceptance (task 8.3)
+
+Pending. It needs the operator's QQ and Telegram accounts on this Windows machine. The QQ QR flow
+talks to `q.qq.com` and creates or binds a real bot, so it is only run together with the user.
+Every item below except Desktop quit behavior already passes end to end against local fake
+platforms (see above); the real-account run confirms the platforms' actual behavior, in particular
+whether the QQ portal accepts `source=acecode`, real reply-window limits, and real media.
+Checklist (record result and any limitation per item):
+
+QQ (2026-10-05, same acceptance daemon; the user ran the QR flow on their own QQ account):
+- [x] `source=acecode` QR binding: Tencent's binding portal accepted the bind page with source
+      `acecode`; the scan created a bot, the secret was decrypted locally, QQ was
+      switched on and connected, and the owner was set. Markdown is available for this bot.
+- [x] private chat: "你好", "你是谁" and "你干嘛" from the owner were each answered in QQ; all three
+      messages carry QQ channel metadata in their bound no-workspace session.
+- [ ] group @mention
+- [ ] approval in IM, and first-answer-wins with Desktop
+- [ ] fallback after the passive reply window, held output and resend on the next message
+- [ ] images and files in both directions
+- [ ] voice recognition text
+
+Telegram (2026-10-05, isolated acceptance daemon on 127.0.0.1:28931, real bot created with
+@BotFather on the phone app):
+- [x] token validation: the BotFather token was verified by `getMe` and saved; the platform
+      connected and the page showed the bot's @username.
+- [x] owner binding by QR link: the owner scanned the QR with the phone camera, tapped Start and
+      became the owner. Finding: the page told the user to "scan with Telegram", but Telegram's
+      built-in scanner only links devices and cannot read the link, so the user could not scan it.
+      Fixed: the hint now says to use the phone camera, and the link next to the QR is clickable
+      (opened in the system browser from Desktop) with a **Copy link** button; docs/channels.md and
+      the help page say the same.
+- [x] private chat: "你好", "请问你今天好吗", "你是谁" and "请问你有啥功能" from the owner were each
+      answered in Telegram; all four messages carry Telegram channel metadata in their bound
+      no-workspace session. (An earlier note here quoted the QQ session by mistake; corrected after
+      checking each session's channel address.)
+- [ ] group @mention, privacy-mode hint
+- [ ] media in both directions
+
+General:
+- [ ] `/new` and `/sessions` + `/resume` into a workspace session
+- [ ] non-owner switching is restricted
+- [ ] sidebar icon follows the binding
+- [ ] connect / disconnect take effect immediately
+- [x] restart: after the acceptance daemon was stopped and started again, both platforms reconnected
+      on their own and both bindings were restored (`[channels/*] binding ...` lines in the log).
+- [ ] Desktop quit with "keep background process" on and off
+- [ ] existing WhatsApp behavior unchanged
+
+## Settings page redesign (acceptance feedback, 2026-10-05)
+
+During acceptance the user found the settings page too detailed and asked for WorkBuddy's layout:
+two columns of cards, a monochrome icon (default: chat), a **Connect** button that becomes
+**Disconnect** once connected, a step-by-step dialog after **Connect**, and details printed to the
+log instead of the page. Implemented as design D12 describes:
+
+- Cards show only a one-line status and pending approval requests; **Fix** reopens the connect
+  step after a failure, **Manage** changes the bot or revokes contacts.
+- **Connect** opens a three-step dialog (set up bot, connect, set owner) when credentials or the
+  owner are missing, and connects directly otherwise. The QQ step fetches the QR code on open;
+  the Telegram owner step explains to scan with the phone camera and offers the clickable link and
+  **Copy link**.
+- `src/host/channels/core/state_log.cpp` logs snapshot changes at every `publish_state`: state and
+  reason, platform extras (privacy mode, webhook, held outputs), owner and owner window, approved
+  contacts, pending requests, bindings and send counts. Credentials (even masked) and QR content are
+  never logged. Inbound decisions (with `AccessResult::reason`, no message text), IM commands, QQ
+  binding phases and send fallbacks are logged where they happen.
+- Corrected the Telegram spec: with group privacy mode on (the BotFather default) @mentions are
+  still delivered; checked against Telegram's documentation and BotFather's own description.
+
+Checks: `ChannelStateLog*` (6 new tests) and the extended `ChannelAccess.GroupNeedsApprovalThenMemberApprovalAndMention`;
+channel-related suites 413 passed, 4 skipped by design, 0 failed; ownership (`--strict --final`), layer
+and file-size checks report 0 findings with the new files staged; `pnpm test` 3044 passed,
+including the guard that the page renders none of the logged details; `pnpm build` passed. After
+the restart the daemon log showed the new lines, for example
+`[channels/telegram] group privacy mode on: groups deliver only @mentions, replies to the bot and commands`.
+
+## More platforms: WeChat, Feishu, DingTalk, Discord, LINE (2026-10-06)
+
+Automated checks on Windows (Ninja, `acecode-builds/im-channels`), all against local fake platforms:
+
+- Build: `acecode_unit_tests` and `acecode` built with the five new transports
+  (`src/adapters/im/{weixin,feishu,dingtalk,discord,line}/`) and `core/line_webhook_server`.
+- Channel and platform suites (`Channel*`, `ImChannelsEndToEnd`, `Qq*`, `Telegram*`, `Weixin*`,
+  `Feishu*`, `DingTalk*`, `Discord*`, `Line*`, `Im*`, `WebSocketClient`, `AesGcm`, `Crypto*`,
+  `ChannelsHandler`): 485 passed, 0 failed on the final build.
+- `ImChannelsEndToEnd`: 16 passed, including the five new ones that go through the production
+  wiring (`make_im_channel_host`, real `SessionRegistry` and scripted model):
+  WeChat scan login → owner from the scanner → private chat with the contact's `context_token`;
+  Feishu, DingTalk, Discord and LINE credentials validated → connected → 6-digit owner code →
+  private chat (Feishu replies to the message, DingTalk through the session webhook, Discord in the
+  DM channel, LINE with the free reply token and no push).
+- `pnpm test` 3048 passed (including LINE connect hints and WeChat re-scan when the login expired);
+  `pnpm build` passed; i18n catalog has no missing entries.
+- Ownership (`--strict --final`), layer and file-size checks: 0 findings with the new files staged.
+- `openspec validate add-desktop-im-channels --strict` passed; `git diff --check` reports no
+  whitespace errors.
+- Found while checking: the single-file compile checker used during drafting compiled its template
+  instead of the target, so earlier "compiles" were unverified; after fixing it a missing-brace bug
+  in `PlatformRuntime::set_credentials` showed up and was fixed before the build above.
+
+Not yet verified with real accounts (to do with the user): WeChat QR login and expiry; Feishu long
+connection, group @ delivery and post rendering; DingTalk Stream registration, @name stripping in
+group text and image rendering; Discord resume, DM opening and the 4014 message; LINE stateless
+tokens, Use webhook after an API URL change, quick-tunnel reachability, reply-token window,
+push quota and image fetching through the tunnel.
+
+## Known limits
+
+- Only Windows was built and run; macOS and Linux are expected to compile (OpenSSL EVP for
+  AES-GCM, `flock` owner lock) but were not built in this pass.
+- QQ guild channels, chunked uploads, typing status, Telegram webhooks and hosted bots are out of
+  scope; held QQ outputs live in memory only.
+- Feishu and DingTalk hand each event to one random connection of the app: the same app running in
+  another tool silently takes part of the messages. `WebSocketClient` exposes no handshake response
+  headers, so Feishu's 403 / connection-limit handshakes are retried. DingTalk has no WebSocket ping
+  of its own and reconnects after 120 s without frames.
+- LINE stays "connecting" until Use webhook is turned on by hand; it cannot send files (images go
+  through the listener's temporary links), and cloudflared is not tied to a kill-on-close job, so a
+  daemon crash can leave it running. Quick tunnels change address on every start.
+- Discord forum channels, Feishu card buttons and quoted-message text, and Discord rate-limit
+  pacing from response headers are not implemented.
diff --git a/openspec/changes/add-pixel-agent-office-demo/design.md b/openspec/changes/add-pixel-agent-office-demo/design.md
deleted file mode 100644
index 575829917..000000000
--- a/openspec/changes/add-pixel-agent-office-demo/design.md
+++ /dev/null
@@ -1,25 +0,0 @@
-## Context
-
-参考图确立浅绿地砖、奶油墙面、等距投影、深色像素轮廓和蓝色办公椅的视觉方向。用户确认先交付独立页面，双击 index.html 即可运行。
-
-## Goals / Non-Goals
-
-目标：代码绘图、素材复用、可交互、离线运行、低空闲开销、可供未来状态接入的清晰边界。
-非目标：生产集成、真实模型请求、远程资源下载、游戏经济系统。
-
-## Decisions
-
-- 原生 HTML/CSS 与顺序加载的普通 JS，共用 PixelOffice 命名空间，兼容 file 协议。
-- assets.js 负责整数坐标像素光栅、共享家具图集、人物模板换色和少量动画帧；实例只存配置和位置。
-- simulation.js 使用显式 dt 驱动状态与依赖任务；走路沿定义通道，团队成员数据不包含展示 DOM。
-- renderer.js 缓存房间背景，按地面深度排序家具和人物；同一资源同时用于场景、头像和图鉴。
-- app.js 是唯一交互适配层，负责选择、派发、缩放、暂停和速度。隐藏页面停止动画调度；暂停时只在交互后重绘。prefers-reduced-motion 默认暂停。
-- CSS 是该独立原型的局部视觉系统，不注入主应用；窄屏将成员面板移到场景下方。
-
-## Risks / Trade-offs
-
-程序绘制需要浏览器截图核对轮廓、遮挡和图块拼接。有限缓存避免每帧重复光栅化；Canvas 本身不能提供键盘节点，成员列表用原生按钮作为等价操作入口。
-
-## Validation
-
-离线 file 页面与本地 HTTP 页面；任务完成依赖、重复派发保护、暂停/恢复、倍速、选择、缩放；桌面及窄屏截图；浏览器错误与外部网络请求；严格 OpenSpec 校验。按仓库要求运行 web 测试和构建，分别报告基线失败。
diff --git a/openspec/changes/add-pixel-agent-office-demo/proposal.md b/openspec/changes/add-pixel-agent-office-demo/proposal.md
deleted file mode 100644
index 210c82d74..000000000
--- a/openspec/changes/add-pixel-agent-office-demo/proposal.md
+++ /dev/null
@@ -1,23 +0,0 @@
-## Why
-
-在接入真实 Agent Team 之前，先用独立可运行的像素办公室验证视觉与交互。用户提供了等距像素办公室参考图，并要求用代码绘制、最大化资源复用。
-
-## What Changes
-
-- 在 design-prototypes/agent-office 提供离线可打开的独立演示页。
-- 共享等距地砖、家具、人物模板和换色动画，表现六位成员的工作、走动与休息。
-- 支持成员选择、演示任务派发、暂停、速度切换与场景缩放。
-- 提供资源图鉴、源码结构与验证说明，方便未来接入真实团队状态。
-
-## Capabilities
-
-### New Capabilities
-- `pixel-agent-office-demo`: 独立像素办公室的渲染、模拟状态和交互演示。
-
-### Modified Capabilities
-
-无。
-
-## Impact
-
-只增加独立设计原型和本次 OpenSpec 文档，不改变生产 Web、C++、API 或依赖。演示任务和统计必须明确为模拟数据。
diff --git a/openspec/changes/add-pixel-agent-office-demo/specs/pixel-agent-office-demo/spec.md b/openspec/changes/add-pixel-agent-office-demo/specs/pixel-agent-office-demo/spec.md
deleted file mode 100644
index c5bcee1df..000000000
--- a/openspec/changes/add-pixel-agent-office-demo/specs/pixel-agent-office-demo/spec.md
+++ /dev/null
@@ -1,33 +0,0 @@
-## ADDED Requirements
-
-### Requirement: 独立代码绘制的办公室
-系统 SHALL 提供无需安装依赖、无需联网即可打开的独立页面，用程序化共享资源呈现等距像素房间、家具和六位团队成员。
-
-#### Scenario: 离线打开
-- **WHEN** 用户用浏览器打开 index.html
-- **THEN** 办公室完整呈现且不发起外部资源请求
-- **AND** 模拟数据标识可见
-
-### Requirement: 共享素材与受控渲染
-系统 SHALL 复用图块和人物模板，缓存静态房间与素材，并在暂停或页面隐藏时停止连续动画调度。
-
-#### Scenario: 资源复用
-- **WHEN** 场景、侧栏头像与图鉴显示相同成员或家具
-- **THEN** 它们使用同一资源定义与缓存
-
-#### Scenario: 暂停
-- **WHEN** 用户暂停演示
-- **THEN** 模拟时间、任务进度和人物动作保持不变
-- **AND** 选择和缩放仍可操作
-
-### Requirement: 可交互的团队模拟
-系统 SHALL 提供成员选择、任务派发、倍速和缩放，并以结构化状态呈现任务依赖和进度。
-
-#### Scenario: 派发任务
-- **WHEN** 用户派发新任务
-- **THEN** 成员按任务依赖推进工作并最终完成项目
-- **AND** 同一项目执行期间不能重复派发
-
-#### Scenario: 键盘与窄屏
-- **WHEN** 用户用键盘或窄屏浏览器访问
-- **THEN** 所有操作均有可聚焦的原生控件且页面无横向溢出
diff --git a/openspec/changes/add-pixel-agent-office-demo/tasks.md b/openspec/changes/add-pixel-agent-office-demo/tasks.md
deleted file mode 100644
index 6203e5f35..000000000
--- a/openspec/changes/add-pixel-agent-office-demo/tasks.md
+++ /dev/null
@@ -1,14 +0,0 @@
-## 1. 设计与资源
-
-- [x] 1.1 建立独立页面及已确认的产品、视觉记录。
-- [x] 1.2 实现共享像素绘图、家具图集和人物换色动画。
-
-## 2. 交互实现
-
-- [x] 2.1 实现显式时间驱动的团队模拟、任务依赖和重复派发保护。
-- [x] 2.2 实现场景深度排序、成员选择、暂停、倍速、缩放及资源图鉴。
-
-## 3. 验证与交付
-
-- [x] 3.1 完成离线/HTTP 浏览器交互和桌面/窄屏视觉验证。
-- [x] 3.2 完成项目检查、严格 OpenSpec 验证及运行/复用说明。
diff --git a/openspec/changes/enhance-desktop-agent-office-motion/.openspec.yaml b/openspec/changes/enhance-desktop-agent-office-motion/.openspec.yaml
new file mode 100644
index 000000000..aa32566bf
--- /dev/null
+++ b/openspec/changes/enhance-desktop-agent-office-motion/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-06
diff --git a/openspec/changes/enhance-desktop-agent-office-motion/design.md b/openspec/changes/enhance-desktop-agent-office-motion/design.md
new file mode 100644
index 000000000..b4c59f79b
--- /dev/null
+++ b/openspec/changes/enhance-desktop-agent-office-motion/design.md
@@ -0,0 +1,31 @@
+## Context
+
+见 proposal.md。前一变更 `integrate-desktop-agent-office` 已交付 Windows 办公室；本变更只增强表现层与平台覆盖。
+
+## Decisions
+
+### 1. 状态来源
+
+服务端 `SessionActivityState` 在分发器锁内折叠事件：token → `responding`，reasoning → `reasoning`，各自保留有界尾巴，换阶段或开始工具即清空；工具开始记录 `display_override`（为空取 `command_preview`）。这样快照在任意时刻都说得清「正在做什么」，打开办公室或断线重连后不依赖重放。实时性由 Web 控制器负责：token/reasoning 事件按会话写入叠加层，`seq` 大于快照才生效，快照追上即丢弃；连续正文在快照尾巴后拼接。不为每个 token 发 HTTP 请求。
+
+### 2. 文案
+
+动作动词与工具图标同表（`toolIcons.js`）；「适合日常工作」模式下的具体进度标题优先，引擎默认的笼统文案（等待模型响应、正在调用工具 X…）不进气泡。细节按半角宽度从开头裁剪，保留最新的字和文件名。
+
+### 3. 交接动画
+
+走路沿 2 单位网格 BFS（8 向、不斜穿桌角），家具占地外扩 1 单位；先到派活的人（`agent_path` 的上一级，找不到时是主 agent）桌前停顿并交接信封，再回工位或出门。离开中的成员又接到任务时掉头回座。只在本办公室已显示过真实快照后演，切换办公室和重连恢复直接落座。减少动态效果时不走路但保留信封。
+
+### 4. 原生窗口区域
+
+Windows `SetWindowRgn` 同时裁剪绘制，气泡冒出墙顶会被切掉，所以页面把气泡矩形（含尾巴与引线）节流上报，原生端与成员列表/提示一起并入区域。macOS 没有窗口区域，定时检测鼠标是否命中房间、控制条或这些矩形，切换 `ignoresMouseEvents`。命中判定与消息解析是纯函数，跨平台单测。
+
+### 5. macOS 宿主
+
+NSPanel（无边框、非激活、不可成为 key window、浮动层级、所有空间可见），WKWebView 关闭背景绘制并重载 `acceptsFirstMouse`。页面按 WebView2 接口编写，宿主在文档开始前注入同名垫片，消息经 `WKScriptMessageHandler` 回到 C++，宿主经 `evaluateJavaScript` 派发。拖动与把手缩放由 60Hz 定时器跟随鼠标。ObjC 回调只持有控制器 weak_ptr；关闭时移除脚本消息处理器（否则内容控制器强引用导致泄漏）。默认 1.25 倍逻辑尺寸，设置不写入 ACECode 数据目录。
+
+## Risks / Trade-offs
+
+- [macOS 未在本机编译] → 只用稳定的 AppKit/WebKit 公共接口与 ARC；需 macOS CI 或实机构建确认。
+- [气泡拥挤] → 优先级 + 错开/抬高/压缩三级避让；极端满员时仍可能重叠。
+- [流式尾巴进入快照] → 只保留 160 字节、换阶段清空，接口仍需鉴权，与聊天页可见内容一致。
diff --git a/openspec/changes/enhance-desktop-agent-office-motion/proposal.md b/openspec/changes/enhance-desktop-agent-office-motion/proposal.md
new file mode 100644
index 000000000..d399dcdcd
--- /dev/null
+++ b/openspec/changes/enhance-desktop-agent-office-motion/proposal.md
@@ -0,0 +1,26 @@
+## Why
+
+桌面 agent 办公室接入真实会话后，用户反馈三点：看不到代理之间交互的动画；代理飙字时看不到状态，气泡只出现一个图标、看不出在做什么；需要 macOS 支持。根因分别是：交接只有一个约 1 秒、9×6 像素的小信封，成员直接闪现/消失；默认「用于编程」模式下服务端不发正文进度，快照一直停在「等待模型」，WebSocket 的 token 事件又被控制器整体忽略，忙碌状态没有文字气泡；原生窗口只有 Windows 实现。
+
+## What Changes
+
+- 会话活动快照增加流式正文/推理尾巴（≤160 字节）与工具调用预览（≤120 字节），由 token 事件推断 `responding`。
+- 控制器用 WebSocket 的 token / reasoning 事件按 seq 叠加实时文字（约 150ms 节流），不增加快照请求。
+- 忙碌 agent 常驻状态气泡「图标 动作 · 细节」，按优先级避让；打字、阅读、思考、等成员各有动作。
+- 成员走进门、到派活的人桌前领「任务」信封、回工位；完成后走去递「回报」信封再出门；网状消息带标签信封。减少动态效果时不走路但保留信封。
+- 页面上报气泡矩形，Windows 窗口区域并入（避免被裁剪），macOS 用于点击穿透判定。
+- 新增 macOS 原生桌宠：非激活 NSPanel + WKWebView，注入 `chrome.webview` 垫片复用同一页面。
+
+## Capabilities
+
+### New Capabilities
+
+无。
+
+### Modified Capabilities
+
+- `desktop-agent-office`: 状态可读性、交接动画与 macOS 宿主（以新增要求记录，原变更尚未归档）。
+
+## Impact
+
+会话活动状态（domain）、办公室快照文档、Web 办公室状态/控制器与图标动词、桌宠页面、Windows 宿主窗口区域、新增 macOS 宿主与 CMake 登记。不改变 agent 调度、权限或模型请求。macOS 宿主未在本机编译验收，需在 macOS 构建与实机确认。
diff --git a/openspec/changes/enhance-desktop-agent-office-motion/specs/desktop-agent-office/spec.md b/openspec/changes/enhance-desktop-agent-office-motion/specs/desktop-agent-office/spec.md
new file mode 100644
index 000000000..345c4a7a2
--- /dev/null
+++ b/openspec/changes/enhance-desktop-agent-office-motion/specs/desktop-agent-office/spec.md
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: 忙碌状态可读
+
+办公室 SHALL 为忙碌的 agent 显示常驻状态气泡，内容包括动作和细节；正在输出正文时 SHALL 显示最新输出的文字并随输出更新，调用工具时 SHALL 显示动作、共源图标与调用预览。默认工作模式下没有正文进度事件时，系统 SHALL 由正文流推断输出状态。
+
+#### Scenario: 默认模式下输出正文
+- **WHEN** agent 在「用于编程」模式下开始输出正文
+- **THEN** 办公室显示该 agent 在打字，气泡为「撰写回复」及最新几个字，并在两次快照之间持续更新
+
+#### Scenario: 调用工具
+- **WHEN** agent 开始调用读取文件工具
+- **THEN** 气泡显示读取图标、「读取」和文件路径的末尾部分
+
+### Requirement: 交接可见
+
+成员加入、完成以及 agent 间消息 SHALL 以可见的交接动画表达：新成员 SHALL 从门口进入并在派活的 agent 处接收任务后入座；成功完成的成员 SHALL 先向派活的 agent 递交回报再离开；agent 间消息 SHALL 以带类型标签的信封在两者之间移动。减少动态效果偏好下 SHALL 省略走路但保留交接信封。
+
+#### Scenario: 星状派活与回报
+- **WHEN** 主 agent 派出子 agent，子 agent 随后成功完成
+- **THEN** 子 agent 走到主 agent 桌前领取「任务」信封后入座，完成后回到主 agent 桌前递交「回报」信封并离开，主 agent 显示收到结果
+
+### Requirement: macOS 桌面办公室
+
+macOS 桌面端 SHALL 提供与 Windows 相同页面与桥协议的透明置顶办公室窗口，不抢主窗口焦点，透明区域点击穿透，支持拖动、缩放、大小记忆、右键菜单与隐藏。
+
+#### Scenario: 透明区域点击
+- **WHEN** 用户点击办公室窗口中房间、控制条和浮层之外的透明区域
+- **THEN** 点击落到后面的窗口
diff --git a/openspec/changes/enhance-desktop-agent-office-motion/tasks.md b/openspec/changes/enhance-desktop-agent-office-motion/tasks.md
new file mode 100644
index 000000000..eb1595254
--- /dev/null
+++ b/openspec/changes/enhance-desktop-agent-office-motion/tasks.md
@@ -0,0 +1,19 @@
+## 1. 状态
+
+- [x] 1.1 活动快照增加正文/推理尾巴与工具调用预览，token 推断 responding；补中文场景单测。
+- [x] 1.2 控制器叠加 WebSocket token/reasoning 实时文字（节流、按 seq 让位快照）；状态投影增加动作动词、细节与上级路径；补单测与 i18n。
+
+## 2. 表现
+
+- [x] 2.1 常驻状态气泡（图标 动作 · 细节）、优先级避让、从开头裁剪；打字 / 阅读 / 思考点 / 沙漏动作。
+- [x] 2.2 走路寻路、领任务与交回报、网状消息标签信封、离开中途接新任务掉头；减少动态效果的降级。
+- [x] 2.3 页面上报气泡区域；Windows 窗口区域并入；命中判定与解析纯函数及单测。
+
+## 3. macOS
+
+- [x] 3.1 NSPanel + WKWebView 宿主、垫片桥、点击穿透、拖动/缩放/菜单、屏幕变化、生命周期；CMake 登记与页面嵌入。
+- [ ] 3.2 macOS 构建与实机验收（本机为 Windows，未执行）。
+
+## 4. 验收
+
+- [x] 4.1 C++ 定向单测、Web 全量测试与构建、浏览器自动化、Windows 原生运行。
diff --git a/openspec/changes/enhance-desktop-agent-office-motion/verification.md b/openspec/changes/enhance-desktop-agent-office-motion/verification.md
new file mode 100644
index 000000000..4edfc3eb5
--- /dev/null
+++ b/openspec/changes/enhance-desktop-agent-office-motion/verification.md
@@ -0,0 +1,15 @@
+# 验证记录
+
+验收日期：2026-10-06，Windows x64，工作区 `N:/Users/shao/acecode.worktrees/agent-office-live`，分支 `claude/agent-office-motion`（基于 master `1f95b89f`）。
+
+| 范围 | 结果 |
+| --- | --- |
+| C++ 定向 | `SessionActivityState.*`（含 3 条新增：默认模式流式正文、推理与正文分段、工具调用预览）、`DesktopPetLayout.*`（含浮层解析与命中判定 2 条新增）、`DesktopOfficeHttp.*`、`EventDispatcher*`、`RecentFixture.*`、`GlobalSessionCatalog.*` 全部通过。 |
+| C++ 全量 fast | `run_fast_tests.py --profile fast`：执行 5001、失败 0、跳过 9。 |
+| 构建 | Ninja/MSVC Release 构建 `acecode`、`acecode-desktop`、`acecode_unit_tests` 通过。构建目录 468 个缺少头文件依赖记录的目标文件已删除重编（初次构建 showIncludes 未记录依赖，改头文件后会链接到旧布局对象并在运行时崩溃）。 |
+| 静态 | 临时索引含新文件后，分层、所有权 `--strict --final`、行数、文档路径检查均 0 findings；`git diff --check` 通过；OpenSpec strict 通过。 |
+| Web | `pnpm test` 全部通过；`pnpm build` 通过；i18n 目录补 18 条英文。 |
+| 浏览器 | `web/scripts/test-desktop-office.mjs` 40 项通过、无页面错误与外部请求：常驻气泡、气泡区域上报、回报信封与致谢、出门、走进门领任务、网状消息信封、减少动态效果降级、原有切换/跟随/溢出/尺寸/断线检查。 |
+| Windows 原生 | 隔离用户目录 + 本机假模型（OpenAI 兼容流式，无真实模型调用）运行开发版 Desktop，经 WebView2 调试端口采样：主 agent 推理尾巴 → 撰写回复实时文字 → 派发任务、两名成员进门领「任务」信封入座 → 成员思考、流式回复 → 完成后递「回报」信封、主 agent「收到…的结果」→ zzz。窗口扩展样式保持 TOPMOST/NOACTIVATE/TOOLWINDOW；WindowFromPoint 确认气泡可点、透明角落穿透，注入的浮层矩形并入窗口区域、清除后恢复穿透。 |
+
+未执行：macOS 编译与实机验收（本机为 Windows；`desktop_pet_mac.mm` 仅经代码审查）；Linux 保持无桌宠。
diff --git a/openspec/changes/improve-archived-session-browser/.openspec.yaml b/openspec/changes/improve-archived-session-browser/.openspec.yaml
new file mode 100644
index 000000000..e8cda9e50
--- /dev/null
+++ b/openspec/changes/improve-archived-session-browser/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-10
diff --git a/openspec/changes/improve-archived-session-browser/design.md b/openspec/changes/improve-archived-session-browser/design.md
new file mode 100644
index 000000000..0a47980af
--- /dev/null
+++ b/openspec/changes/improve-archived-session-browser/design.md
@@ -0,0 +1,30 @@
+## Context
+
+`SectionArchived` loads a merged archive through `api.listAllArchivedSessions`, already including workspace hashes, names, paths, and no-workspace flags. `archivedSessions.js` provides workspace-qualified selection and removal helpers. Restore/delete operations already settle independently, preserve failures, notify the sidebar, and use the shared `Modal` for deletion. See `proposal.md` for the requested navigation improvements.
+
+## Goals / Non-Goals
+
+**Goals:** Keep one source of archive data and derive grouped, filtered results with testable pure helpers. Preserve endpoint routing, existing relative-time labels, and partial-failure behavior.
+
+**Non-Goals:** Changes to daemon APIs, full-text transcript search, session persistence, or the surrounding settings navigation.
+
+## Decisions
+
+- Derive workspace identity, search, sorting, and groups in `archivedSessions.js`. Use workspace hashes rather than names; separate no-workspace sessions and legacy local sessions. Shared display-title logic ensures search matches the row users see. Client-side filtering uses the already loaded archive and avoids additional requests.
+- 默认在各工作区内部按最近更新时间排序，可切换最早更新；缺少有效更新时间时回退到创建时间，无有效时间的会话始终放在组内末尾。工作区分组与筛选选项复用 `listAllArchivedSessions()` 返回的 `workspaces` 顺序，和侧边栏的 `/api/workspaces` 顺序一致，不受会话时间及搜索结果影响。筛选选项仍从完整归档列表生成，搜索不隐藏选项。
+- `groupArchivedSessions` 接收工作区标识顺序，先分组再分别排序组内会话。无工作区分组固定在前，与侧边栏任务区的位置一致；没有出现在工作区列表中的历史分组放在已知工作区之后，并按标识稳定排序。保留本地兼容回退、空组隐藏、同名工作区隔离以及批量操作行为，不新增请求或修改接口。
+- Derive batch targets from current visible results and prune selections hidden by changed filters. Keep matching selections through sorting. This avoids hidden destructive targets and stale selection on clearing a query.
+- Place the title/description and three batch buttons in a wrapping header, followed by a search field and two selects. Group sections show folder icons, names, counts, and divided session rows with the current per-row actions. Use settings theme tokens and existing icons, with no global stylesheet changes. Same-name options include a path or hash and group headers expose their path.
+- Retain existing batch and modal logic. Updating the list automatically updates counts and removes empty groups; the selected workspace remains available until the user changes it, even if its last session was removed.
+- Browser verification exposed the existing archive confirmation below the settings overlay (`z-[200]` versus `z-[300]`). Give this confirmation the existing settings-dialog layer `z-[310]` so mouse confirmation/cancellation remains available; keep the shared Modal default unchanged.
+
+## Risks / Trade-offs
+
+- [Filtering could accidentally retain hidden destructive targets] -> Use visible results for selected targets and test selection pruning, no matches, and combined filters.
+- [Shared settings CSS removes generic card borders] -> Use semantic list elements for group frames and marked composite controls for filter borders; inspect actual desktop, narrow, and dark renderings.
+- [New Chinese labels can fail localization gates] -> Add English overrides, regenerate the catalog, and review generated changes.
+- [Archives with many sessions remain fully loaded] -> This preserves the current loading contract; memoize local transformations without adding server pagination.
+
+## Migration Plan
+
+No data migration is needed. Ship the frontend bundle through the normal build. Reverting these frontend changes restores the previous archive presentation without altering stored sessions.
diff --git a/openspec/changes/improve-archived-session-browser/proposal.md b/openspec/changes/improve-archived-session-browser/proposal.md
new file mode 100644
index 000000000..7cdb9b622
--- /dev/null
+++ b/openspec/changes/improve-archived-session-browser/proposal.md
@@ -0,0 +1,25 @@
+## Why
+
+The archive settings page is a flat list with its batch actions below every session, making long archives difficult to navigate and manage. The requested layout puts search, sorting, workspace filtering, and batch actions above sessions grouped by workspace.
+
+## What Changes
+
+- Add a search field matching session titles, workspace names, and paths, plus newest/oldest update-time sorting and a workspace selector.
+- Group results by workspace identity, display each workspace name and matching session count, and keep sessions without a workspace in a separate group.
+- 工作区分组和筛选选项沿用侧边栏工作区顺序；最近／最早更新时间只决定各工作区内部的会话顺序。
+- Move select all, unarchive selected sessions, and delete selected sessions into the upper-right header; restrict selection and batch operations to current filtered results.
+- Retain single-session actions, localized relative timestamps, shared deletion confirmation, and partial-failure retry behavior.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `session-archive`: Add searchable, sortable workspace groups and header batch controls to the archive settings view.
+
+## Impact
+
+Frontend-only changes to `web/src/components/SettingsPage.jsx`, the archived-session helpers and tests, and localization overrides/catalog. Existing daemon APIs and dependencies remain sufficient. Verification covers filtering, group identity, selection boundaries, batch failures, responsive layout, and the complete web test/build gates.
diff --git a/openspec/changes/improve-archived-session-browser/specs/session-archive/spec.md b/openspec/changes/improve-archived-session-browser/specs/session-archive/spec.md
new file mode 100644
index 000000000..acfc3f45b
--- /dev/null
+++ b/openspec/changes/improve-archived-session-browser/specs/session-archive/spec.md
@@ -0,0 +1,63 @@
+## ADDED Requirements
+
+### Requirement: Archive browser filters and sorts workspace groups
+The archive settings view SHALL provide search, update-time sorting, and workspace selection above a list grouped by workspace identity. Each nonempty group SHALL show its workspace name and matching session count. Sessions without a workspace SHALL have a separate group.
+
+#### Scenario: Browse and sort groups
+- **WHEN** 用户打开已归档会话
+- **THEN** 工作区分组和工作区筛选选项 MUST 按侧边栏工作区顺序排列
+- **AND** 每个工作区内部的会话 MUST 默认按最近更新时间排列，缺失时回退到创建时间
+- **AND** 切换最早更新 MUST 只反转组内时间顺序，保持工作区分组顺序不变
+- **AND** 没有有效时间的会话 MUST 放在各自组内有时间的会话之后
+
+#### Scenario: Keep workspace order through filtering and archive changes
+- **WHEN** 用户搜索、切换工作区过滤条件，或取消归档／删除会话
+- **THEN** 剩余工作区分组 MUST 保持侧边栏中的相对顺序
+- **AND** 某个工作区最新或最早的会话变化 MUST NOT 改变工作区分组顺序
+- **AND** 没有匹配会话的工作区 MUST NOT 显示为空分组
+
+#### Scenario: Keep special and unlisted groups deterministic
+- **WHEN** 归档包含无工作区会话、本地兼容会话或未出现在工作区列表中的历史会话
+- **THEN** 无工作区分组 MUST 固定放在工作区之前，与侧边栏任务区位置一致
+- **AND** 未列出的工作区分组 MUST 放在已知工作区之后并按工作区标识稳定排序
+- **AND** 工作区顺序缺失时分组 MUST 仍不受组内会话时间排序方向影响
+
+#### Scenario: Combine search and workspace filtering
+- **WHEN** the user enters a search query and selects a workspace
+- **THEN** only that workspace's sessions matching the displayed title, workspace name, or path MUST be shown
+- **AND** search MUST ignore surrounding whitespace and letter case
+- **AND** group counts MUST reflect the matching results
+
+#### Scenario: Distinguish workspaces with the same name
+- **WHEN** two workspaces have the same display name
+- **THEN** they MUST remain independently filterable and grouped by identity
+- **AND** their paths or identifiers MUST be available to disambiguate them
+
+#### Scenario: Empty filtered results
+- **WHEN** search and workspace filters match no sessions
+- **THEN** the view MUST show a no-results message while keeping the filters accessible
+- **AND** no empty workspace groups MUST be rendered
+
+### Requirement: Archive batch actions appear in the header
+The archive view SHALL show select all/deselect all, unarchive selected sessions, and delete selected sessions in that order at the upper right above the filters and list. Controls SHALL wrap within narrow views without horizontal overflow.
+
+#### Scenario: Select only current results
+- **WHEN** the user selects all after applying filters
+- **THEN** only visible matching sessions MUST be selected
+- **AND** batch restore and deletion MUST act only on the current selection
+- **AND** changing filters MUST remove selections for sessions no longer visible
+- **AND** sorting MUST preserve selected sessions
+
+#### Scenario: No available selection
+- **WHEN** no current results are selected or an operation is running
+- **THEN** unavailable batch actions MUST be disabled
+
+#### Scenario: Partial operation failure
+- **WHEN** a batch restore or delete succeeds for some sessions and fails for others
+- **THEN** successful sessions MUST disappear and failed sessions MUST remain selected for retry
+- **AND** remaining groups and counts MUST update to match the list
+
+#### Scenario: Confirm deletion
+- **WHEN** the user deletes one session or the selected sessions
+- **THEN** the existing shared confirmation dialog MUST appear before permanent deletion
+- **AND** cancelling MUST leave the archive unchanged
diff --git a/openspec/changes/improve-archived-session-browser/tasks.md b/openspec/changes/improve-archived-session-browser/tasks.md
new file mode 100644
index 000000000..1f44e8ea4
--- /dev/null
+++ b/openspec/changes/improve-archived-session-browser/tasks.md
@@ -0,0 +1,23 @@
+## 1. Archive browsing logic
+
+- [x] 1.1 Add workspace grouping, combined search/workspace filtering, update-time sorting, and selection pruning helpers; verify unit coverage for duplicate names/IDs, no-workspace/local rows, invalid dates, empty results, and immutable input.
+
+## 2. Archive interface
+
+- [x] 2.1 Add the header batch controls, search/sort/workspace toolbar, and grouped counted rows; wire selection to visible results and retain single/batch operation behavior, verified with focused checks and browser interactions.
+- [x] 2.2 Add English overrides and regenerate the source catalog; verify localization audit and review generated changes.
+
+## 3. Integration verification
+
+- [x] 3.1 Run the complete web tests and production build, validate the OpenSpec change strictly, and inspect the final diff while preserving unrelated edits.
+- [x] 3.2 Verify desktop, narrow, and dark archive layouts and combined filters, visible-only selection, restore, delete confirmation/cancellation, and partial-failure retry against isolated mock sessions; capture a screenshot.
+
+Verification: `pnpm test` passed 2,174 cases; `pnpm build` and the regex compatibility gate passed; localization audit and strict OpenSpec validation passed. Headless Chromium exercised nine isolated mock sessions across three workspaces and no-workspace tasks, including ten restore/delete requests, injected partial failures, cancellation, scoped selection, locale switching, and 1600/760/430-pixel viewports with no page errors or horizontal content overflow. Screenshots were captured outside the repository. Browser QA also confirmed the scoped archive confirmation layer fix.
+
+## 4. 2026-10-05 工作区顺序修正
+
+- [x] 4.1 分组助手支持侧边栏工作区顺序，时间排序仅作用于组内；覆盖正反序、搜索、同名工作区、特殊分组及删除后的顺序稳定性。
+- [x] 4.2 归档页面复用接口返回的工作区顺序，分组和筛选选项保持一致。
+- [x] 4.3 执行定向回归、完整 Web 测试与生产构建、OpenSpec 严格验证和差异检查，并验证实际页面的排序交互。
+
+本次验证：归档助手 15 项、批量操作结构 3 项定向检查通过；`pnpm test` 全部通过（日志包含 3,024 条 `[pass]`）；`pnpm build` 与正则兼容性检查、`openspec validate improve-archived-session-browser --strict`、`git diff --check` 通过。Chromium 使用隔离 API 数据验证工作区分组与筛选顺序、组内正反时间排序、选择保留、组合筛选、取消归档后分组顺序以及修改工作区顺序后重新打开页面；1440px 和 430px 页面无横向溢出、无页面异常。没有重新构建或启动 Desktop。
diff --git a/openspec/changes/integrate-desktop-agent-office/.openspec.yaml b/openspec/changes/integrate-desktop-agent-office/.openspec.yaml
new file mode 100644
index 000000000..aa32566bf
--- /dev/null
+++ b/openspec/changes/integrate-desktop-agent-office/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-06
diff --git a/openspec/changes/integrate-desktop-agent-office/design.md b/openspec/changes/integrate-desktop-agent-office/design.md
new file mode 100644
index 000000000..a5c45ecd7
--- /dev/null
+++ b/openspec/changes/integrate-desktop-agent-office/design.md
@@ -0,0 +1,44 @@
+## Context
+
+动机见 proposal.md。主线已有持久化单会话、星状子任务和网状协作树；旧分支的桌宠由独立 WebView2 窗口及内嵌 Canvas 页面组成，保留 5 套布局、1 个核心位与 7 个组员位、家具与人物变化、鼠标拖动和缩放。原分支 5 个未提交文件是本次导入的权威版本。
+
+## Goals / Non-Goals
+
+**Goals:** 在现有 agent 生命周期之上增加只读可视化；无额外模型请求；后台工作和多会话切换可恢复；窗口异常不影响主界面。
+
+**Non-Goals:** 改造调度策略、从动画反推任务完成、重画美术、新增 macOS/Linux 原生桌宠、推送发布。
+
+## Decisions
+
+### 1. 唯一状态来源与数据流
+
+会话元数据保存最近真实用户消息时间，普通输出、打开会话、元数据修改不改变它。旧会话从持久化消息回填只读查询结果。全局目录提供最近五个未归档主会话，跨工作区按该字段排序；子会话保持归属父办公室。采用独立只读端点和现有全局目录，避免依赖侧栏的更新时间排序或全量历史加载。
+
+Web 应用级控制器读取最近列表及当前办公室快照，持有当前主会话及运行中子会话的引用计数订阅，用真实 WS 增量更新结构化状态。场景快照通过桌面桥送至 DesktopPet，宠物交互通过同一桥返回。主页面隐藏到托盘时继续更新；页面重载和 WS 重连重取快照。显示层不持有 agent 服务或控制权限。
+
+### 2. 选择与跟随
+
+默认跟随主窗口；点击五个会话中的门牌关闭跟随，固定选中。开启跟随后恢复当前主会话。最近名单仅在用户发送消息后更新；跟随查看名单以外会话时临时显示该房间，不改五个门牌的排序。无会话时呈现待命房间和可理解的空态，不启动模拟任务。
+
+### 3. 角色生命周期
+
+主会话始终映射固定核心角色 Maestro，收到真实完成结果后显示 zzz，下一回合醒来。等待审批/回答、压缩、重试、取消与失败独立表达。子 agent 以 session id 为身份，星状和网状统一归属根办公室，保留 agent_path 表达真实层级；成功完成立即离座，再次执行时以同外观返回。取消和失败不冒充完成。工位不足显示额外运行人数并允许进入对应会话查看，空位释放后补位。
+
+### 4. 图标、上下文与随机性
+
+工具名到图标映射为共用纯数据；聊天工具行、子任务和桌宠使用同一 SVG 定义。桥传受控图标数据而非执行脚本或任意 HTML。文件堆复用聊天 token 预算算法，以最近请求上下文用量/窗口大小计算；压缩成功后依实际新用量变薄，未知值不伪造百分比。每个会话的布局和角色外观由稳定身份种子决定。
+
+### 5. 原生与所有权
+
+导入窗口实现并补齐桥与缓存快照。GUI 线程拥有窗口/COM；回调仅持有 weak_ptr 或 lifetime 引用，销毁清理事件、计时器与窗口。控制栏与房间命中区域一起缩放，透明区域继续穿透；保留不抢焦点与已有自由缩放。Web 控制器可显式销毁并释放全部订阅、定时器和在途请求。
+
+## Risks / Trade-offs
+
+- [旧会话缺少最近用户时间] → 基于持久化可见用户消息查找并缓存，禁止用 updated_at 伪装。
+- [切换/重连时旧快照覆盖新状态] → 会话身份、控制器代次、事件序号校验；断线显示连接状态并从权威快照恢复。
+- [多工作区/子会话结束混淆] → 使用全局目录、实际父关系/agent_path 与真实回合结局，测试同名和跨会话情况。
+- [当前 master 有并行脏改动] → 独立 worktree 实施、导入范围审查、合并前保存并比对原工作区改动，仅提交本功能。
+
+## Migration Plan
+
+先记录原分支导入文件校验值，复制到本工作区并登记构建；新增规格、状态和测试；接线、验证 native 与 Web；最后将功能提交合回本地 master，并保留原分支和原工作区的其它改动。
diff --git a/openspec/changes/integrate-desktop-agent-office/proposal.md b/openspec/changes/integrate-desktop-agent-office/proposal.md
new file mode 100644
index 000000000..e8a73d86b
--- /dev/null
+++ b/openspec/changes/integrate-desktop-agent-office/proposal.md
@@ -0,0 +1,27 @@
+## Why
+
+Claude 会话已实现原生像素办公室桌宠，但尚未连接真实 agent。用户已确认以这套桌宠接入单 agent、星状及网状协作，并删除主线中不再需要的“好好工作事务所”独立原型。
+
+## What Changes
+
+- 完整引入原桌宠及未提交的随机布局、扩充家具和自由缩放改进。
+- 办公室常驻；按用户最近发送消息的时间提供最多五个主会话的切换入口。
+- 办公室提供默认开启的跟随开关；手动切换后固定，重新开启后跟随主窗口。
+- 主 agent 完成显示 zzz，收到新任务醒来；子 agent 完成即离座，再次工作时以相同身份及外观返回。
+- 真实工具活动、审批、提问、取消、失败、上下文和压缩状态驱动画面；工具图标与聊天界面共用来源。
+- 保存按会话稳定的随机布局，完整处理重连、切换、窗口关停和订阅回收。
+- 删除 design-prototypes/agent-office 的旧页面及相关过时说明。
+
+## Capabilities
+
+### New Capabilities
+
+- `desktop-agent-office`: 原生桌面办公室、最近五个会话、真实角色生命周期、工具与上下文可视化。
+
+### Modified Capabilities
+
+无；当前主规格目录没有同名能力。
+
+## Impact
+
+涉及原生 Desktop/WebView2、Web 应用级状态适配与图标、会话最近用户消息时间和只读查询、构建注册、相关测试与文档。沿用现有 agent 运行与权限机制。Windows 为当前原生实现，其它平台保持原有桌面行为。只合入本地 master 并提交，不推送或发布版本。
diff --git a/openspec/changes/integrate-desktop-agent-office/specs/desktop-agent-office/spec.md b/openspec/changes/integrate-desktop-agent-office/specs/desktop-agent-office/spec.md
new file mode 100644
index 000000000..e73c406de
--- /dev/null
+++ b/openspec/changes/integrate-desktop-agent-office/specs/desktop-agent-office/spec.md
@@ -0,0 +1,72 @@
+## Purpose
+
+将真实单 agent 与多 agent 会话呈现为常驻桌面的像素办公室，让用户在最近五个会话之间切换，并通过角色动作、工具图标和文件厚度观察执行、等待与上下文状态，同时保留原生桌宠交互和可靠恢复能力。
+
+## ADDED Requirements
+
+### Requirement: 常驻桌面办公室
+
+Windows 桌面端 SHALL 显示沿用现有像素美术的透明置顶办公室，保留拖动、自由缩放、大小记忆和透明区域穿透；没有任务时也保持可见。系统 SHALL 移除旧“好好工作事务所”独立原型。
+
+#### Scenario: 启动与空闲
+- **WHEN** 桌面端启动且没有运行任务
+- **THEN** 办公室可见并显示待命或睡眠状态，不发起演示任务或模型请求
+
+#### Scenario: 缩放与关闭
+- **WHEN** 用户缩放窗口、换 DPI 或退出应用
+- **THEN** 命中区域与画面一致、大小按逻辑尺寸恢复，退出释放窗口和事件资源
+
+### Requirement: 最近五个会话与跟随
+
+办公室 SHALL 提供跨工作区最近五个未归档主会话，严格按用户最后发送消息时间排序。子会话、后台输出与仅打开会话 SHALL NOT 改变该名单。办公室 SHALL 提供默认打开的跟随开关，手动选择办公室关闭跟随。
+
+#### Scenario: 消息排序
+- **WHEN** 第六个主会话收到用户新消息
+- **THEN** 该会话进入最近五个列表，最早发送消息的会话退出列表
+- **AND** 子 agent 的输出或主会话后续工具调用不挤占名额
+
+#### Scenario: 手动与跟随切换
+- **WHEN** 用户手动选择门牌后又切换主窗口会话
+- **THEN** 办公室保持手动选中会话
+- **AND** 用户打开跟随后显示主窗口当前会话；若其不在最近五个内，临时显示但不重排最近列表
+
+### Requirement: 真实角色状态
+
+办公室 SHALL 适用于单 agent、星状和网状协作；角色身份、动作和气泡来自真实会话状态。主 agent 成功完成 SHALL 保持在座并显示 zzz，新任务开始后醒来。子 agent 成功完成 SHALL 立即离座，后续任务再次入座时保持身份与外观。等待审批、提问、重试、取消、失败 SHALL 独立表达。
+
+#### Scenario: 单 agent 完成与唤醒
+- **WHEN** 单 agent 收到真实成功完成结果后开始下一回合
+- **THEN** 办公室依次显示 zzz 和工作状态，过程中没有模拟子角色
+
+#### Scenario: 多 agent 与再次执行
+- **WHEN** 星状或网状子 agent 完成、随后收到新任务
+- **THEN** 角色立即离座，再以相同外观进入所属根会话办公室
+- **AND** 等待审批或等待回答不触发成功退场或主角色睡眠
+
+#### Scenario: 工位溢出
+- **WHEN** 运行中的子 agent 数量超过七个组员工位
+- **THEN** 办公室显示额外人数并保留查看入口，空位释放后可见成员补位
+
+### Requirement: 工具与上下文表达一致
+
+桌宠与聊天工具行 SHALL 使用相同来源的工具图标。每位角色的桌面文件厚度 SHALL 反映真实当前上下文占用比例；压缩成功后根据新的用量变薄，未知用量不得显示伪造比例。
+
+#### Scenario: 工具调用
+- **WHEN** agent 开始一个内置工具调用
+- **THEN** 聊天与办公室显示一致的工具图标及当前活动
+
+#### Scenario: 上下文压缩
+- **WHEN** 上下文占用增长并发生一次成功压缩
+- **THEN** 文件堆随真实占用增加，并在压缩后的新用量到达时变薄
+
+### Requirement: 稳定外观与恢复
+
+同一会话的随机布局及同一角色的外观 SHALL 在切换、重连和重启后保持稳定。系统 SHALL 用权威快照恢复状态，拒绝过期响应，不重复播放已处理的消息交接动画；连接失败不得伪装成工作完成。
+
+#### Scenario: 切换与重连
+- **WHEN** 用户快速切换办公室且旧请求迟到，或连接断开后重连
+- **THEN** 当前办公室只应用对应会话的新快照与事件，角色、状态和文件堆可恢复，原来的订阅被正确释放
+
+#### Scenario: 随机会话布局
+- **WHEN** 同一会话重新打开，另一个会话首次打开
+- **THEN** 前者恢复相同布局，后者按独立稳定种子选取现有模板及家具
diff --git a/openspec/changes/integrate-desktop-agent-office/tasks.md b/openspec/changes/integrate-desktop-agent-office/tasks.md
new file mode 100644
index 000000000..c9359f825
--- /dev/null
+++ b/openspec/changes/integrate-desktop-agent-office/tasks.md
@@ -0,0 +1,24 @@
+## 1. 导入和清理
+
+- [x] 1.1 导入 Claude 桌宠的最新七个文件并登记构建，记录源文件校验值，验证分层与源文件检查。
+- [x] 1.2 删除旧事务所原型与过时变更记录，验证代码和文档没有运行入口引用。
+
+## 2. 真实会话数据
+
+- [x] 2.1 持久化最近真实用户消息时间并提供旧记录兼容，测试输出、打开、隐藏消息、恢复和分叉的排序语义。
+- [x] 2.2 提供跨工作区最近五个主会话及办公室快照，测试归档/子会话过滤、真实运行状态、上下文与无会话情况。
+- [x] 2.3 实现应用级办公室状态与订阅控制器，测试快速切换、跟随、重连、取消、失败、主角色睡眠和子角色完成/唤醒。
+
+## 3. 桌宠接线与表现
+
+- [x] 3.1 接通原生快照/交互桥并处理窗口生命周期，验证重载与关停不会遗留回调，保持拖动、缩放和透明命中。
+- [x] 3.2 实现最近五个门牌与默认开启的跟随开关，验证鼠标与键盘切换、长标题和最小缩放。
+- [x] 3.3 用真实单/多 agent 状态更新稳定角色、消息交接、溢出工位、zzz 和上下文文件堆，验证成功压缩后变薄及重连不重复动画。
+- [x] 3.4 共用工具图标来源，验证聊天、子任务和桌宠对同一工具显示一致图标。
+
+## 4. 验收和交付
+
+- [x] 4.1 完成相关 C++ 测试与 Windows Desktop/daemon 构建、Web pnpm test/build、OpenSpec 严格校验和 diff 检查，记录实际结果。
+- [x] 4.2 完成浏览器状态/交互自动化及 Windows 原生运行验证，记录截图、重连/切换和窗口缩放证据。
+- [x] 4.3 更新运行说明和 API 文档，按逐项要求审查最终差异，确认无模拟数据接入生产。
+- [x] 4.4 提交本功能并合入本地 master，验证提交归属及原工作区其它改动完整保留，不推送。
diff --git a/openspec/changes/integrate-desktop-agent-office/verification.md b/openspec/changes/integrate-desktop-agent-office/verification.md
new file mode 100644
index 000000000..1ff60f109
--- /dev/null
+++ b/openspec/changes/integrate-desktop-agent-office/verification.md
@@ -0,0 +1,57 @@
+# 验证记录
+
+## 导入基线
+
+源工作区：`N:/Users/shao/acecode/.claude/worktrees/acecode-folder-structure-fd3342`，HEAD `8f83c048`，含原分支五个未提交文件的当前内容；原工作区未修改。
+
+| 文件 | 源文件 SHA-256 |
+| --- | --- |
+| assets/desktop_pet/OFL.txt | 8ed5cd9e189e30dfdb0df2d5c2771556b50e9d502d899221328c3245caf8423c |
+| assets/desktop_pet/agent_office_pet.html | fcb7b2fc7cef7857c89dedf5cfc10e86a2df26c86d4ca503dbcc5e5f1f585830 |
+| src/apps/desktop/desktop_pet.cpp | 7d4b1567eb13ec3cd12ae0d173810f92ff21f663c843f62635a9b8e045409b67 |
+| src/apps/desktop/desktop_pet.hpp | d606978e20a99f2b9243ca351b6acacc1334b586bc15a94b32d69cd7d1d19c01 |
+| src/apps/desktop/desktop_pet_layout.cpp | 976a1d4ba4a3b0a5831b3473c82c1fa8db0a38d0e6b435d173d4d986722ccda3 |
+| src/apps/desktop/desktop_pet_layout.hpp | a9f2ddd85a2dc39579c5c7f908f923de57b2e7f0b45c1bc3a312659226f7f74a |
+| tests/desktop/desktop_pet_layout_test.cpp | 7141331b8342b4189452144a937f34b6799c1d348d7e56fd21b58ee33deefe57 |
+
+## 验收
+
+验收日期：2026-10-06，Windows x64，隔离工作区 `codex/agent-office-live`。
+
+| 范围 | 结果与证据 |
+| --- | --- |
+| C++ 编译 | 当前工作区 Ninja/MSVC 构建 `acecode`、`acecode-desktop`、`acecode_unit_tests` 通过。为避开 vcpkg 旧下载 URL 的 404，只读复用原桌宠工作区已验证且清单依赖相同的 vcpkg 安装树和 webview 源码；可执行文件全部由当前源码生成，未复制其它工作区程序。 |
+| C++ 测试 | 18 个 suite、193 项通过：新增桌宠布局、运行状态、最近消息、HTTP 快照测试，以及 EventDispatcher、全局会话目录/查询、恢复/回退/压缩、存储、回合结束/工具事件和注册表关停回归。 |
+| 静态与规格 | 分层检查（含 parent include 限制）0 findings，所有权 strict/final 0 findings，OpenSpec strict 通过，git diff --check 通过。 |
+| Web | `pnpm test` 全套通过；`pnpm build` 通过，4502 个正则字面量的兼容性扫描通过。 |
+| 浏览器 | `node web/scripts/test-desktop-office.mjs` 22 项通过，无页面错误/外部网络请求；覆盖无演示启动、最近五个控件、鼠标/键盘、完成离座/睡眠、稳定外观/布局、共源图标、溢出列表动态更新、172/344/860 宽度、断线/空态。 |
+| Windows 原生 | 用共享开发启动器及独立临时用户目录运行本次 Desktop，连接本机假 provider（没有真实模型调用）。原生 WebView2 的 12 项断言通过：重启恢复睡眠、主窗口跟随、真实星状主/子任务同时工作、成功子任务离座/主任务睡眠、上下文 1500/10000、手选关闭跟随/重开恢复、页面重载、滚轮放大/尺寸复位、办公室打开对应主会话。 |
+| 原生几何与生命周期 | Win32 命中检查确认透明角落落到后方窗口，控制条与房间落到桌宠；空态/断线提示和成员面板共同回传可见区域，避免被房间多边形裁掉；系统移动循环通过键盘移动使 x 从 1014 变为 981，测试后复原；窗口样式保留 TOPMOST/NOACTIVATE，RGBA 截图透明角落 alpha=0。最后一次内嵌资源构建后，另用 Win32 WindowFromPoint 验证断线提示实际落在原生命中区域；通过原生 quitApp 正常退出并确认本次进程结束。 |
+| 视觉审查 | 保留原作像素房间；独立 finish reviewer 初次仅发现展开成员列表滞后，修复及新增断言后复核 `resolved / ship`。唯一 detector 轮次中的最小 9px 功能文字已改为 11px，紧凑控制组重复间距经审查接受。 |
+
+原生运行截图来自真实 daemon/agent 生命周期（本机测试 provider）：
+
+![主 agent 和子 agent 同时工作](../../../docs/images/agent-office/native-multi-working.png)
+
+![子任务离座，主 agent 进入睡眠](../../../docs/images/agent-office/native-multi-complete.png)
+
+定向 C++ 回归命令：
+
+```text
+acecode_unit_tests --gtest_filter=DesktopPetLayout.*:SessionActivityState.*:RecentFixture.*:DesktopOfficeHttp.*:EventDispatcher.*:EventDispatcherWait.*:GlobalSessionCatalog.*:GlobalSessionCatalogIndex.*:GlobalSessionSearchService.*:SessionManagerResume.*:SessionManagerRewind.*:SessionManagerCompactReplace.*:SessionStorage.*:AgentLoopTurnTiming.*:AgentLoopTermination.*:AgentLoopToolLifecycleEvents.*:AgentLoopCompactEvents.*:SessionRegistryShutdown.*
+```
+
+浏览器脚本通过 `ACE_PLAYWRIGHT_MODULE` 使用已安装的 Playwright，`ACE_BROWSER_CHANNEL=msedge`；`ACE_OFFICE_CAPTURE_DIR` 可指定截图目录。原生验收对两个 WebView2 使用进程级 `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=0`，通过临时目录中的 DevToolsActivePort 连接；未修改用户全局环境或配置。
+
+运行边界：本次验证 Windows Desktop；macOS/Linux 本次仅保留无桌宠的空实现，没有宣称跨平台原生验收。源代码交付不会自动替换用户已安装的 Desktop。
+
+
+## 本地交付
+
+功能提交 `e80bccba355fd0b20dda3f42b2b0107d177cada0` 已从独立工作区 `codex/agent-office-live` 快进合入本地 `master`。
+
+合并前主工作区的 42 个已跟踪改动文件和 188 个未跟踪文件均保留：218 个文件逐字节 SHA-256 未变；12 个与功能重叠的文件先生成三方合并结果，再在每文件写入门下恢复用户改动。唯一需要手动合并的是通知测试文件，保留消息通道测试和本次原生桥测试。合并后这些原有改动仍未提交，Git index 无无关内容。
+
+主工作区在恢复上述改动后再次运行 `pnpm test`、`pnpm build` 和 `git diff --check` 均通过；办公室与通知桥定向 JS 测试通过。原 Claude 工作区七个导入文件的 SHA-256 与导入基线全部一致。旧事务所原型目录已从主工作区删除，验收创建的 Desktop/daemon/本机测试 provider 已退出。
+
+未执行 push、发布或安装替换。验收记录在后续文档提交中补齐，功能提交保持独立。
diff --git a/openspec/changes/integrate-recent-work-release-0-9-35/design.md b/openspec/changes/integrate-recent-work-release-0-9-35/design.md
new file mode 100644
index 000000000..eb076bd09
--- /dev/null
+++ b/openspec/changes/integrate-recent-work-release-0-9-35/design.md
@@ -0,0 +1,17 @@
+# 设计
+
+## 发布范围
+
+复用受保护 master 的集成与版本 PR。近期 worktree 按固定窗口与完成依据盘点；已经包含的提交及内容等价补丁不重复应用；源码和最终包分别验证。
+
+## 本机测试进程结果
+
+GTest 重复运行仅把最后一轮结果写入 XML，进程退出码反映所有轮次。运行器逐进程结合这两个信号：退出码 0 正常；退出码 1 且该进程 XML 记录断言失败时，继续现有失败与基线对照；其它非零退出必须阻断。超时使用的负数退出码保持在 JSON 中，避免同组成功进程通过 max 运算将其覆盖为 0。
+
+解析失败、缺失 XML 与已有基线失败维持原有判断。生产 MCP 连接与配置读写代码保持本次输入基线；首次失败与压力重复中的启动超时如实保留，最终全量结果另行验证。
+
+## 通道测试回调生命周期
+
+Linux CTest 在三个微信用例的断言全部通过后报告 double free。测试先声明传输对象、后声明记录器，导致记录器先析构，而传输对象析构中的 stop 仍会发送最终状态或排空消息。直接提取现有 Recorder 与生产 TransportCallbacks 类型构造停机回调最小复现，Linux ASan 报告 heap-use-after-free；仅调整声明顺序后通过。
+
+统一将微信、QQ、Telegram、飞书、Discord 测试中的 Recorder 放在传输对象之前，保证正常结束和 ASSERT 提前返回时，传输对象都先停机。钉钉和 LINE 已遵循此顺序。生产 PlatformRuntime 的回调经 LifetimeRef 进入宿主，析构体先调用 stop，断开时先停止传输对象，保持现有生产实现。
diff --git a/openspec/changes/integrate-recent-work-release-0-9-35/proposal.md b/openspec/changes/integrate-recent-work-release-0-9-35/proposal.md
new file mode 100644
index 000000000..0f05b1b0d
--- /dev/null
+++ b/openspec/changes/integrate-recent-work-release-0-9-35/proposal.md
@@ -0,0 +1,23 @@
+# v0.9.35 集成发布
+
+## 原因
+
+当前主线已有桌面 agent 办公室提交，以及已完成、尚未提交的消息通道和 Web 修复。按 acecode-release 流程统一提交、推送与发布，保证各平台包、更新清单和公开下载一致。
+
+## 范围
+
+- 固定最近 48 小时窗口：2026-10-04 17:50:03 至 2026-10-06 17:50:03，Asia/Taipei。
+- 审计全部 46 个 worktree；近期三个候选均已合入或其有效改动已在主线。九个 src 布局待迁移 ref 保留。
+- 纳入当前工作区 230 个源代码、测试、文档与配置文件；消息通道新增 QQ、Telegram、微信、飞书、钉钉、Discord、LINE。
+- 纳入桌面 agent 办公室动态、归档会话分组顺序、输入框 DOM 光标同步、侧栏取消置顶按钮及滚动回归。
+- 完成主线 PR、版本 PR，再从同步后的 master 发布唯一稳定版 v0.9.35。
+
+## 验收边界
+
+频道 QQ、Telegram 有真实账号绑定与私聊证据，其余五个平台只有本机模拟端到端验收；真实账号验收未完成的项目保持未勾选。桌面办公室 macOS 尚无本机验收；由发布 CI 验证编译，不能代替原生人工交互验收。
+
+种子资源、播种逻辑与测试相对 v0.9.34 没有变化，本次保留 seed revision 2026-10-04.1。
+
+## 测试汇总修复
+
+发布检查发现，GTest 重复执行时可能先失败后成功，XML 只保留最后一次，而进程仍以 1 退出；当前汇总器忽略这个差异。修复后，无法用该进程 XML 中的失败解释的非零退出必须阻断，包括超时和异常退出；已有基线失败的对照语义保持。负数退出码也必须在 JSON 中保留。
diff --git a/openspec/changes/integrate-recent-work-release-0-9-35/specs/local-test-runner/spec.md b/openspec/changes/integrate-recent-work-release-0-9-35/specs/local-test-runner/spec.md
new file mode 100644
index 000000000..25e6df9b1
--- /dev/null
+++ b/openspec/changes/integrate-recent-work-release-0-9-35/specs/local-test-runner/spec.md
@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: 测试进程退出与 XML 一致性
+本机测试运行器 MUST 校验每个子进程的退出状态，并在 XML 无法解释非零退出时阻断成功报告。
+
+#### Scenario: 重复测试最后一轮成功
+- **WHEN** GTest 重复执行的早期轮次失败、最后一轮 XML 全部通过，而进程退出码为 1
+- **THEN** 汇总运行必须失败，并记录对应子进程及退出码
+
+#### Scenario: 超时留下已有 XML
+- **WHEN** 子进程超时并以负数退出码记录，即使留下已有 XML 且其失败已在基线中
+- **THEN** 汇总运行必须失败，JSON 必须保留该负数退出码
+
+#### Scenario: 已有断言失败仍可与基线对照
+- **WHEN** 子进程以 1 退出且该进程 XML 的断言失败均为允许的已知基线失败
+- **THEN** 继续按照现有基线对照规则判定，不把普通断言失败重复归类为未知进程故障
+
+### Requirement: 异步回调测试依赖的析构顺序
+通道测试 MUST 使回调引用的记录器存活到传输对象停机完成，包含测试断言提前返回的路径。
+
+#### Scenario: 析构传输对象时仍有停机回调
+- **WHEN** 测试退出作用域，传输对象在析构过程中发送最终状态或排空入站消息
+- **THEN** 回调记录器必须仍然存活，且测试进程必须正常退出
diff --git a/openspec/changes/integrate-recent-work-release-0-9-35/tasks.md b/openspec/changes/integrate-recent-work-release-0-9-35/tasks.md
new file mode 100644
index 000000000..92d185f15
--- /dev/null
+++ b/openspec/changes/integrate-recent-work-release-0-9-35/tasks.md
@@ -0,0 +1,23 @@
+## 1. 范围与来源
+
+- [x] 1.1 固定 48 小时窗口，盘点 46 个 worktree、主线与远端，核对聊天结束状态和任务验收记录。
+- [x] 1.2 审查待提交文件并建立 SHA-256 基线；确认近期候选已经合入或内容等价，保留九个待迁移 ref。
+
+## 2. 集成验证与推送
+
+- [x] 2.1 Web 全量测试与生产构建通过；七项静态门禁在新增文件暂存后全部通过。
+- [x] 2.2 Windows 构建、全量单测执行和失败复核完成；浏览器回归与 OpenSpec 严格验证通过，间歇性失败明确记录。
+
+- [x] 2.3 修复测试汇总器漏报进程失败，覆盖重复测试末轮成功、超时和已有失败基线。
+
+- [x] 2.4 修正五组通道测试的回调记录器析构顺序，验证 ASan 最小复现与本机全量回归；Linux 全量复验纳入最终主线发布门禁。
+
+## 3. 后续发布门禁
+
+发布操作及最终结果随 GitHub Release 和本次发布审计附件记录，必须完成以下门禁：
+
+1. 集成 PR 将全部源码合入 master，确认来源提交已包含，master 与 origin/master 无分歧。
+2. 对新增 macOS 宿主及通道代码完成跨平台编译验证，再通过版本 PR 更新到 0.9.35。
+3. 从同步后的 master 创建 v0.9.35；同一提交的测试与全部平台打包成功。
+4. GitHub Release 包含 18 个用户下载包；六类更新 ZIP、两个 PKG 和全部手动下载包同步 aupdate，公开地址大小、哈希与 MIME 一致。
+5. 最终包的种子升级、包结构和 Git 状态验证完成，明确保留尚未执行的真实账号及原生人工验收范围。
diff --git a/openspec/changes/integrate-recent-work-release-0-9-35/verification.md b/openspec/changes/integrate-recent-work-release-0-9-35/verification.md
new file mode 100644
index 000000000..b2c167dc6
--- /dev/null
+++ b/openspec/changes/integrate-recent-work-release-0-9-35/verification.md
@@ -0,0 +1,43 @@
+# 发布验证记录
+
+审计时间：2026-10-06，Asia/Taipei。初始 master 为 93c934a4，origin/master 为 a67efe55，主线有 3 个未推送提交、230 个待提交文件。
+
+## Worktree 结论
+
+| 工作区 | 来源 HEAD | 结论与依据 |
+| --- | --- | --- |
+| acecode.worktrees/agent-office-live | 93c934a4a791e71bcf75d3f61aa69e00c45c0770 | 已包含在本地 master；工作区干净；两项办公室变更有 C++、Web、浏览器及 Windows 原生验证记录。 |
+| .claude/worktrees/cranky-jemison-14c349 | 6d45f1ce50adf419c41fa0ef91877b8122031401 | 代码与 UTF-8 测试文件已经相同；诊断文件包含后一候选的改进；共享文档和 Web smoke 测试的全部新增行在主线中。 |
+| .claude/worktrees/ecstatic-dirac-7e2088 | 8d64540dadd824825055aade4284f0320356955b | 诊断实现、头文件和测试逐文件相同；Web smoke 测试全部新增行在主线中。 |
+
+其余 42 个非主线 worktree 不在固定窗口内，没有按提交时间假定其完成。九个待迁移 ref 按 src 搬迁约定保留，不合并、不推进、不删除。旧工作区未提交改动保持原状。完整路径、分支、HEAD、状态、reflog 与原始 SHA-256 清单保存在本次发布审计附件中。
+
+## 已执行
+
+- pnpm test：退出码 0。
+- pnpm build：通过，4512 个正则字面量兼容性扫描通过。
+- 分层、文档路径、src/tests include、文件行数、所有权 strict/final、路径映射七项检查全部通过。首次未暂存时检查器不认识新增模块；暂存明确清单后消除全部缺失路径结果。
+- 桌面办公室浏览器回归：40 项通过，无页面错误、无外部网络请求。
+
+## 测试进程汇总修复
+
+首次 Windows 全量执行 6106 项，有 1 项 MCP 配置写入失败；MCP 套件单独复查 26 项通过。随后 20 次压力重复中，第 17 次在 5 秒启动等待处失败，最后一轮通过；进程退出 1，但旧运行器误报 OK。修复运行器以每进程退出状态和 XML 共同判断，保留超时负数退出码。新增三项报告行为回归，加上重构工具全套共 102 项测试通过；既有 MCP 业务源码未修改。所有原始日志保留，最终全量复查另行记录。
+
+## Windows 修复前复核
+
+- Release 构建 acecode、acecode-desktop、acecode_unit_tests 成功，CMake File API 的实际库归属与链接边界检查通过。
+- 全量清单 6107 项，执行 6106 项，9 项按设计跳过、1 项禁用。四分片复查的并行部分零失败；串行部分的 PointerOverlay 测试在显示产品浮层之前，被 Windows.UI.Core.CoreWindow 遮挡了测试底板，导致前置命中断言失败。
+- 随后用修复后的运行器复查 McpManagerAsync、ComputerUsePointerOverlay 及守护项，共 31 项通过，所有子进程退出码均为 0。MCP 写入异常在单独 26 项和本次 31 项复查中未复现；压力重复里的 5 秒启动超时保留为间歇性测试观察。没有将两次全量执行记为连续零失败。
+- 滚动浏览器 27 项通过；第一次冷启动在 Vite 关闭阶段退出，诊断副本与原脚本复跑均通过。
+
+## 后续发布门禁
+
+集成与版本 PR、跨平台 CI、最终包和公开下载验证尚待完成，最终结果随发布审计附件交付。
+
+## 通道夹具生命周期修复与最终本机结果
+
+首轮 Linux CTest 执行 6029 项，三个微信测试在断言通过后以 double free 退出。它们把 Recorder 声明在传输对象之后，退出作用域时记录器先释放，随后传输对象停机回调访问了已经销毁的记录器。用现有 Recorder、生产 TransportCallbacks 类型及停机回调契约构造 Linux 最小复现，GCC AddressSanitizer 检出 heap-use-after-free；调整声明顺序后退出码为 0。
+
+统一修正微信 12 处、Discord 14 处、飞书 10 处、QQ 10 处、Telegram 10 处声明顺序，共 56 处。钉钉和 LINE 已保持正确顺序。生产宿主回调使用 LifetimeRef，并在析构体内先停止传输对象，因此生产代码保持与三平台成功编译预检时完全相同。
+
+修复后 Windows Release 单测重新构建，全量清单 6107 项、执行 6106 项、9 项按设计跳过、1 项禁用；六个分片及串行进程全部退出 0，失败数 0，耗时 212.3 秒。所有权严格检查、OpenSpec 严格验证和差异检查通过。最终发布提交仍必须通过 Linux 全量 CTest 门禁。
diff --git a/scripts/refactor/run_fast_tests.py b/scripts/refactor/run_fast_tests.py
index 3b0018364..2d580ca85 100644
--- a/scripts/refactor/run_fast_tests.py
+++ b/scripts/refactor/run_fast_tests.py
@@ -278,6 +278,13 @@ def launch(label: str, index: int, filter_text: str, shard_env: dict | None = No
     missing = [job["label"] for job in jobs if not job["xml"]]
     actual = merge_results([Path(job["xml"]) for job in jobs if job["xml"]]) if jobs else \
         {"executed": [], "skipped": [], "failures": []}
+    # GTest repeat mode writes only the final iteration to XML, while the
+    # process keeps a failure exit from any earlier iteration. Crashes/timeouts
+    # can also leave a previous XML behind. Only ordinary assertion failures
+    # represented in this process's XML may use the known-baseline allowance.
+    unexpected_exits = [job for job in jobs if job["exit_code"] != 0 and
+                        (job["exit_code"] != 1 or not job["xml"] or
+                         not parse_xml(Path(job["xml"]))["failures"])]
     report = {
         "schema": 1,
         "tests": tests,
@@ -292,7 +299,7 @@ def launch(label: str, index: int, filter_text: str, shard_env: dict | None = No
         "jobs": jobs,
         "wall_seconds": wall,
         "shards_wall_seconds": shards_wall,
-        "run_exit_code": max([job["exit_code"] for job in jobs], default=0),
+        "run_exit_code": next((job["exit_code"] for job in jobs if job["exit_code"] != 0), 0),
         "binary": str(binary),
         "cwd": str(cwd),
         "iso_root": str(iso_root),
@@ -314,7 +321,8 @@ def launch(label: str, index: int, filter_text: str, shard_env: dict | None = No
         print(f"  {job['label']:>8}: exit={job['exit_code']} {job['seconds']}s")
     for row in actual["failures"]:
         print(f"  FAILED {row['name']}")
-    problems = []
+    problems = [f"{job['label']}: unexplained process exit {job['exit_code']}"
+                for job in unexpected_exits]
     if missing:
         problems.append(f"no XML from: {', '.join(missing)}")
     if comparison:
diff --git a/scripts/refactor/tests/test_run_fast_tests.py b/scripts/refactor/tests/test_run_fast_tests.py
index fb6712e23..2b0eb6062 100644
--- a/scripts/refactor/tests/test_run_fast_tests.py
+++ b/scripts/refactor/tests/test_run_fast_tests.py
@@ -2,10 +2,12 @@
 
 不启动真实的单测二进制;gtest 的 XML 用最小样例写到临时目录里解析。
 """
+import io
 import json
 import sys
 import tempfile
 import unittest
+from unittest import mock
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
@@ -125,5 +127,51 @@ def test_merge_dedupes_and_baseline_only_judges_executed_tests(self):
             json.dumps(diff)  # 报告必须能直接序列化进记录
 
 
+class ProcessExitTest(unittest.TestCase):
+    def run_fixture(self, exit_code, xml, baseline=False):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            binary = root / "fake-test-binary"
+            binary.touch()
+            output = root / "report.json"
+            argv = ["run_fast_tests.py", "--binary", str(binary), "--profile", "full",
+                    "--shards", "1", "--iso-root", str(root / "isolated"), "--output", str(output)]
+            if baseline:
+                prior = root / "baseline.json"
+                prior.write_text(json.dumps({"tests": ["Alpha.Fails"], "actual_results": {
+                    "executed": ["Alpha.Fails"], "skipped": [],
+                    "failures": [{"name": "Alpha.Fails", "message": "boom"}]}}), encoding="utf-8")
+                argv.extend(["--baseline", str(prior)])
+
+            def run_process(binary, args, env, cwd, log_path, timeout):
+                (log_path.parent / "results.xml").write_text(xml, encoding="utf-8")
+                return {"exit_code": exit_code, "seconds": 0, "log": str(log_path)}
+
+            listing = mock.Mock(stdout="Alpha.\n  Fails\n")
+            with mock.patch.object(sys, "argv", argv), \
+                    mock.patch.object(sys, "stdout", io.StringIO()), \
+                    mock.patch.object(rft.subprocess, "run", return_value=listing), \
+                    mock.patch.object(rft, "run_process", side_effect=run_process):
+                code = rft.main()
+            return code, json.loads(output.read_text(encoding="utf-8"))
+
+    def test_earlier_repeat_failure_cannot_be_hidden_by_final_passing_xml(self):
+        xml = GTEST_XML.format(suite="Alpha").replace('<failure message="boom"/>', '').replace('failures="1"', 'failures="0"')
+        code, report = self.run_fixture(1, xml)
+        self.assertEqual(1, code)
+        self.assertEqual([], report["actual_results"]["failures"])
+        self.assertEqual(1, report["run_exit_code"])
+
+    def test_timeout_preserves_negative_exit_even_with_previous_xml(self):
+        code, report = self.run_fixture(-1, GTEST_XML.format(suite="Alpha"), baseline=True)
+        self.assertEqual(1, code)
+        self.assertEqual(-1, report["run_exit_code"])
+
+    def test_known_assertion_failure_still_uses_baseline_policy(self):
+        code, report = self.run_fixture(1, GTEST_XML.format(suite="Alpha"), baseline=True)
+        self.assertEqual(0, code)
+        self.assertEqual([], report["comparison"]["failures_new"])
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/src/adapters/im/dingtalk/dingtalk_api.cpp b/src/adapters/im/dingtalk/dingtalk_api.cpp
new file mode 100644
index 000000000..4afea9a32
--- /dev/null
+++ b/src/adapters/im/dingtalk/dingtalk_api.cpp
@@ -0,0 +1,475 @@
+#include "dingtalk_api.hpp"
+
+#include "im/http.hpp"
+#include "im/redact.hpp"
+#include "utils/logger.hpp"
+
+#include <algorithm>
+
+namespace acecode::im::dingtalk {
+namespace {
+
+constexpr std::chrono::seconds kTokenRefreshMargin{300};
+
+std::string trim_slash(std::string base) {
+    while (!base.empty() && base.back() == '/') base.pop_back();
+    return base;
+}
+
+nlohmann::json parse_object(const std::string& body) {
+    try {
+        auto json = nlohmann::json::parse(body);
+        if (json.is_object()) return json;
+    } catch (...) {
+    }
+    return nlohmann::json::object();
+}
+
+std::string json_text(const nlohmann::json& value, const char* key) {
+    if (!value.is_object() || !value.contains(key)) return {};
+    const auto& field = value.at(key);
+    if (field.is_string()) return field.get<std::string>();
+    if (field.is_number_integer()) return std::to_string(field.get<std::int64_t>());
+    return {};
+}
+
+long long expire_seconds(const nlohmann::json& value, const char* key) {
+    if (!value.is_object() || !value.contains(key)) return 7200;
+    const auto& field = value.at(key);
+    if (field.is_number_integer()) return field.get<long long>();
+    if (field.is_string()) {
+        try {
+            return std::stoll(field.get<std::string>());
+        } catch (...) {
+        }
+    }
+    return 7200;
+}
+
+bool list_contains(const nlohmann::json& response, const char* key, const std::string& id) {
+    if (!response.contains(key) || !response[key].is_array()) return false;
+    for (const auto& item : response[key]) {
+        if (item.is_string() && item.get<std::string>() == id) return true;
+    }
+    return false;
+}
+
+std::vector<std::pair<std::string, std::string>> json_headers() {
+    return {{"Content-Type", "application/json"}, {"Accept", "application/json"}};
+}
+
+std::string log_detail(const ApiError& error) {
+    std::string text = "HTTP " + std::to_string(error.status);
+    if (!error.code.empty()) text += " code=" + error.code;
+    if (error.errcode != 0) text += " errcode=" + std::to_string(error.errcode);
+    if (!error.request_id.empty()) text += " requestid=" + error.request_id;
+    return text;
+}
+
+// Stream 注册的 ua 字段,格式沿用官方 SDK 的 name-sdk-lang/version。
+std::string stream_ua() {
+    const auto agent = user_agent();
+    const auto slash = agent.find('/');
+    return "acecode-stream-cpp/" + (slash == std::string::npos ? agent : agent.substr(slash + 1));
+}
+
+} // namespace
+
+Api::Api(ApiOptions options) : options_(std::move(options)) {}
+
+std::string Api::robot_code() const { return options_.robot_code.empty() ? options_.client_id : options_.robot_code; }
+
+std::vector<std::string> Api::secrets() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return {options_.client_secret, token_};
+}
+
+std::vector<std::string> Api::webhook_bases() const { return {options_.api_base, options_.oapi_base}; }
+
+std::string Api::fetch_token_locked(std::string* error) {
+    HttpRequest request;
+    request.method = "POST";
+    request.url = trim_slash(options_.api_base) + "/v1.0/oauth2/accessToken";
+    request.headers = json_headers();
+    request.body = nlohmann::json{{"appKey", options_.client_id}, {"appSecret", options_.client_secret}}.dump();
+    request.timeout = std::chrono::seconds(15);
+    request.use_proxy = options_.use_proxy;
+    const auto response = http_send(request);
+    const std::vector<std::string> secrets{options_.client_secret};
+    auth_failed_ = false;
+    last_token_status_ = response.status;
+    token_.clear();
+    if (response.status == 0) {
+        if (error) *error = redact_secrets(response.error.empty() ? "无法连接钉钉开放平台" : response.error, secrets);
+        return {};
+    }
+    const auto json = parse_object(response.body);
+    const auto token = json_text(json, "accessToken");
+    if (response.status >= 200 && response.status < 300 && !token.empty()) {
+        token_ = token;
+        const auto seconds = expire_seconds(json, "expireIn");
+        const auto margin = std::min<long long>(kTokenRefreshMargin.count(), std::max<long long>(seconds / 2, 1));
+        refresh_at_ = std::chrono::steady_clock::now() + std::chrono::seconds(std::max<long long>(seconds - margin, 1));
+        return token_;
+    }
+    const auto api_error = parse_api_error(response.status, response.body);
+    // 换令牌接口的 4xx 几乎都是凭据问题(invalidClientIdOrSecret / MissingappKey);429 与 5xx 是临时问题。
+    auth_failed_ = response.status >= 400 && response.status < 500 && response.status != 429;
+    LOG_WARN("[channels/dingtalk] access token request failed: " + log_detail(api_error));
+    if (error) {
+        *error = auth_failed_ ? std::string("Client ID 或 Client Secret 不正确")
+                              : redact_secrets("获取钉钉访问令牌失败:" + api_error.message, secrets);
+    }
+    return {};
+}
+
+std::string Api::access_token(std::string* error) {
+    std::lock_guard<std::mutex> lock(mu_);
+    if (!token_.empty() && std::chrono::steady_clock::now() < refresh_at_) return token_;
+    return fetch_token_locked(error);
+}
+
+void Api::invalidate_token() {
+    std::lock_guard<std::mutex> lock(mu_);
+    token_.clear();
+    refresh_at_ = {};
+}
+
+bool Api::last_token_auth_failed() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return auth_failed_;
+}
+
+StreamTicket Api::open_stream(std::chrono::milliseconds timeout) {
+    StreamTicket ticket;
+    HttpRequest request;
+    request.method = "POST";
+    request.url = trim_slash(options_.api_base) + "/v1.0/gateway/connections/open";
+    request.headers = json_headers();  // 不带 Accept 时平台默认回 XML
+    request.body = nlohmann::json{{"clientId", options_.client_id},
+                                  {"clientSecret", options_.client_secret},
+                                  {"subscriptions", nlohmann::json::array({{{"type", "CALLBACK"},
+                                                                            {"topic", kBotMessageTopic}}})},
+                                  {"ua", stream_ua()}}
+                       .dump();
+    request.timeout = timeout;
+    request.use_proxy = options_.use_proxy;
+    const auto response = http_send(request);
+    const std::vector<std::string> secrets{options_.client_secret};
+    if (response.status == 0) {
+        ticket.error.message = redact_secrets(response.error, secrets);
+        ticket.reason = describe_api_error(ticket.error);
+        return ticket;
+    }
+    if (response.status >= 200 && response.status < 300) {
+        const auto json = parse_object(response.body);
+        ticket.endpoint = json_text(json, "endpoint");
+        ticket.ticket = json_text(json, "ticket");
+        if (!ticket.endpoint.empty() && !ticket.ticket.empty()) {
+            ticket.ok = true;
+            return ticket;
+        }
+        ticket.error.status = response.status;
+        ticket.error.message = "missing endpoint or ticket";
+        ticket.reason = "钉钉 Stream 注册返回了无效的接入地址";
+        LOG_WARN("[channels/dingtalk] connections/open returned no endpoint/ticket");
+        return ticket;
+    }
+    ticket.error = parse_api_error(response.status, response.body);
+    ticket.error.message = redact_secrets(ticket.error.message, secrets);
+    LOG_WARN("[channels/dingtalk] connections/open failed: " + log_detail(ticket.error));
+    if (response.status == 401 || ticket.error.code == "authFailed" ||
+        ticket.error.code == "invalidClientIdOrSecret") {
+        ticket.auth_failed = true;
+        ticket.reason = "Client ID 或 Client Secret 无效,请在钉钉开发者后台核对后重新连接";
+    } else if (response.status >= 400 && response.status < 500 && response.status != 429) {
+        ticket.rejected = true;
+        ticket.reason = "钉钉拒绝建立 Stream 连接:请确认应用已发布、机器人已开启 Stream 模式,并检查服务器出口 IP 白名单";
+    } else {
+        ticket.reason = "钉钉 Stream 注册暂时失败(HTTP " + std::to_string(response.status) + "),稍后自动重试";
+    }
+    return ticket;
+}
+
+VerifyResult Api::verify() {
+    VerifyResult result;
+    result.client_id = options_.client_id;
+    result.robot_code = robot_code();
+    if (options_.client_id.empty() || options_.client_secret.empty()) {
+        result.auth_failed = true;
+        result.error = "请填写 Client ID 和 Client Secret";
+        return result;
+    }
+    std::string error;
+    std::string token;
+    bool auth_failed = false;
+    long status = 0;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        token_.clear();
+        token = fetch_token_locked(&error);
+        auth_failed = auth_failed_;
+        status = last_token_status_;
+    }
+    if (token.empty()) {
+        if (auth_failed) {
+            result.auth_failed = true;
+            result.error = "Client ID 或 Client Secret 不正确,请在钉钉开发者后台「凭证与基础信息」中核对";
+        } else if (status == 0) {
+            result.network = true;
+            result.error = "无法连接钉钉开放平台,请检查网络或代理设置";
+        } else {
+            result.error = error.empty() ? std::string("获取钉钉访问令牌失败") : error;
+        }
+        return result;
+    }
+    const auto ticket = open_stream(std::chrono::seconds(10));
+    if (ticket.ok) {
+        result.ok = true;
+        return result;
+    }
+    if (ticket.auth_failed) {
+        result.auth_failed = true;
+        result.error = "Client ID 或 Client Secret 不正确,请在钉钉开发者后台「凭证与基础信息」中核对";
+    } else if (ticket.rejected) {
+        result.rejected = true;
+        result.error = ticket.reason;
+    } else if (ticket.error.status == 0) {
+        result.network = true;
+        result.error = "无法连接钉钉开放平台,请检查网络或代理设置";
+    } else {
+        result.error = ticket.reason;
+    }
+    return result;
+}
+
+ApiResult Api::post_api(const std::string& path, const nlohmann::json& body, std::chrono::milliseconds timeout) {
+    ApiResult result;
+    for (int attempt = 0; attempt < 2; ++attempt) {
+        std::string error;
+        const auto token = access_token(&error);
+        if (token.empty()) {
+            result.error.message = error;
+            if (last_token_auth_failed()) {
+                result.error.status = 401;
+                result.error.code = "invalidClientIdOrSecret";
+            }
+            return result;
+        }
+        HttpRequest request;
+        request.method = "POST";
+        request.url = trim_slash(options_.api_base) + path;
+        request.headers = json_headers();
+        request.headers.emplace_back("x-acs-dingtalk-access-token", token);
+        request.body = body.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace);
+        request.timeout = timeout;
+        request.use_proxy = options_.use_proxy;
+        const auto response = http_send(request);
+        const std::vector<std::string> secrets{options_.client_secret, token};
+        if (response.status == 0) {
+            result.error = ApiError{};
+            result.error.message = redact_secrets(response.error, secrets);
+            return result;
+        }
+        ApiError error_body;
+        if (response.status >= 200 && response.status < 300 && !body_has_errcode(response.body, &error_body)) {
+            result.ok = true;
+            result.response = parse_object(response.body);
+            return result;
+        }
+        result.error = response.status >= 200 && response.status < 300 ? error_body
+                                                                          : parse_api_error(response.status, response.body);
+        result.error.message = redact_secrets(result.error.message, secrets);
+        if (is_token_error(result.error) && attempt == 0) {
+            invalidate_token();
+            continue;
+        }
+        LOG_WARN("[channels/dingtalk] " + path + " failed: " + log_detail(result.error));
+        return result;
+    }
+    return result;
+}
+
+ApiResult Api::send_webhook(const std::string& url, const nlohmann::json& body) {
+    ApiResult result;
+    if (!webhook_url_allowed(url, webhook_bases())) {
+        result.error.status = 400;
+        result.error.message = "会话回复地址不是钉钉域名,已拒绝";
+        LOG_WARN("[channels/dingtalk] refused a session webhook outside the DingTalk domains");
+        return result;
+    }
+    HttpRequest request;
+    request.method = "POST";
+    request.url = url;
+    request.headers = json_headers();
+    request.body = body.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace);
+    request.timeout = std::chrono::seconds(30);
+    request.use_proxy = options_.use_proxy;
+    const auto response = http_send(request);
+    // webhook 的 session 参数相当于 90 分钟内的回复凭据,不能出现在任何错误文本里。
+    const std::vector<std::string> secrets{options_.client_secret, url};
+    if (response.status == 0) {
+        result.error.message = redact_secrets(response.error, secrets);
+        return result;
+    }
+    ApiError error;
+    if (response.status >= 200 && response.status < 300) {
+        if (!body_has_errcode(response.body, &error)) {
+            result.ok = true;
+            result.response = parse_object(response.body);
+            return result;
+        }
+    } else {
+        error = parse_api_error(response.status, response.body);
+    }
+    error.message = redact_secrets(error.message, secrets);
+    result.error = error;
+    LOG_WARN("[channels/dingtalk] session webhook send failed: " + log_detail(error));
+    return result;
+}
+
+ApiResult Api::send_oto(const std::string& robot_code, const std::string& staff_id, const std::string& msg_key,
+                        const nlohmann::json& msg_param) {
+    const nlohmann::json body{{"robotCode", robot_code},
+                              {"userIds", nlohmann::json::array({staff_id})},
+                              {"msgKey", msg_key},
+                              {"msgParam", msg_param.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace)}};
+    auto result = post_api("/v1.0/robot/oToMessages/batchSend", body, std::chrono::seconds(30));
+    if (!result.ok) return result;
+    const auto& response = result.response;
+    result.ok = false;
+    result.error.status = 200;
+    if (list_contains(response, "flowControlledStaffIdList", staff_id)) {
+        result.error.code = "send.too.fast";
+        result.error.message = "发送频率过快";
+    } else if (list_contains(response, "invalidStaffIdList", staff_id)) {
+        result.error.code = "invalidStaffId";
+        result.error.message = "对方不在机器人的可见范围内,或不是本组织成员";
+    } else if (list_contains(response, "filteredStaffIdList", staff_id)) {
+        result.error.code = "filteredStaffId";
+        result.error.message = "钉钉过滤了这条消息(对方可能关闭了机器人消息)";
+    } else if (json_text(response, "processQueryKey").empty()) {
+        result.error.message = "钉钉没有确认这条消息";
+    } else {
+        result.ok = true;
+        result.error = ApiError{};
+        return result;
+    }
+    LOG_WARN("[channels/dingtalk] oToMessages/batchSend not delivered: " + result.error.code);
+    return result;
+}
+
+ApiResult Api::send_group(const std::string& robot_code, const std::string& conversation_id,
+                          const std::string& msg_key, const nlohmann::json& msg_param) {
+    const nlohmann::json body{{"robotCode", robot_code},
+                              {"openConversationId", conversation_id},
+                              {"msgKey", msg_key},
+                              {"msgParam", msg_param.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace)}};
+    auto result = post_api("/v1.0/robot/groupMessages/send", body, std::chrono::seconds(30));
+    if (result.ok && json_text(result.response, "processQueryKey").empty()) {
+        result.ok = false;
+        result.error.status = 200;
+        result.error.message = "钉钉没有确认这条消息";
+    }
+    return result;
+}
+
+ApiResult Api::upload_media(const std::string& type, const std::filesystem::path& path, const std::string& name,
+                            const std::string& mime_type) {
+    ApiResult result;
+    for (int attempt = 0; attempt < 2; ++attempt) {
+        std::string error;
+        const auto token = access_token(&error);
+        if (token.empty()) {
+            result.error.message = error;
+            return result;
+        }
+        HttpRequest request;
+        request.method = "POST";
+        // type 同时放查询参数与表单字段(python SDK 用表单字段,官方 connector 用查询参数)。
+        request.url = trim_slash(options_.oapi_base) + "/media/upload?access_token=" + url_encode(token) +
+                      "&type=" + url_encode(type);
+        HttpPart type_part;
+        type_part.name = "type";
+        type_part.value = type;
+        HttpPart media;
+        media.name = "media";
+        media.file = path;
+        media.filename = name;
+        media.content_type = mime_type.empty() ? std::string("application/octet-stream") : mime_type;
+        request.parts = {type_part, media};
+        request.timeout = std::chrono::seconds(120);
+        request.use_proxy = options_.use_proxy;
+        const auto response = http_send(request);
+        const std::vector<std::string> secrets{options_.client_secret, token};
+        if (response.status == 0) {
+            result.error = ApiError{};
+            result.error.message = redact_secrets(response.error, secrets);
+            return result;
+        }
+        ApiError api_error;
+        const bool http_ok = response.status >= 200 && response.status < 300;
+        if (http_ok && !body_has_errcode(response.body, &api_error)) {
+            result.response = parse_object(response.body);
+            if (!json_text(result.response, "media_id").empty()) {
+                result.ok = true;
+                result.error = ApiError{};
+                return result;
+            }
+            result.error = ApiError{};
+            result.error.status = response.status;
+            result.error.message = "钉钉上传结果缺少 media_id";
+            return result;
+        }
+        result.error = http_ok ? api_error : parse_api_error(response.status, response.body);
+        result.error.message = redact_secrets(result.error.message, secrets);
+        if (is_token_error(result.error) && attempt == 0) {
+            invalidate_token();
+            continue;
+        }
+        LOG_WARN("[channels/dingtalk] media/upload failed: " + log_detail(result.error));
+        return result;
+    }
+    return result;
+}
+
+std::string Api::download_url(const std::string& download_code, const std::string& robot_code, std::string* error) {
+    const auto result = post_api("/v1.0/robot/messageFiles/download",
+                                 {{"downloadCode", download_code}, {"robotCode", robot_code}}, std::chrono::seconds(30));
+    if (!result.ok) {
+        if (error) *error = "获取附件下载地址失败:" + describe_api_error(result.error);
+        return {};
+    }
+    const auto url = json_text(result.response, "downloadUrl");
+    if (url.empty() && error) *error = "钉钉没有返回附件下载地址";
+    return url;
+}
+
+bool Api::download(const std::string& download_code, const std::string& robot_code, const std::filesystem::path& dest,
+                   std::uint64_t max_bytes, std::string* error) {
+    const auto url = download_url(download_code, robot_code, error);
+    if (url.empty()) return false;
+    HttpRequest request;
+    request.url = url;  // 不带 Content-Type 与鉴权头:OSS 签名校验只认原始请求
+    request.timeout = std::chrono::seconds(120);
+    request.use_proxy = options_.use_proxy;
+    request.download_to = dest;
+    request.max_download_bytes = max_bytes;
+    const auto response = http_send(request);
+    if (response.too_large) {
+        if (error) *error = "附件超过大小限制";
+        return false;
+    }
+    if (response.status < 200 || response.status >= 300) {
+        std::error_code ec;
+        std::filesystem::remove(dest, ec);
+        if (error) {
+            *error = response.status == 0 ? "下载附件失败:" + redact_secrets(response.error, {url})
+                                          : "下载附件失败:HTTP " + std::to_string(response.status);
+        }
+        return false;
+    }
+    return true;
+}
+
+} // namespace acecode::im::dingtalk
diff --git a/src/adapters/im/dingtalk/dingtalk_api.hpp b/src/adapters/im/dingtalk/dingtalk_api.hpp
new file mode 100644
index 000000000..532f32741
--- /dev/null
+++ b/src/adapters/im/dingtalk/dingtalk_api.hpp
@@ -0,0 +1,113 @@
+#pragma once
+
+// 钉钉开放平台 HTTP 客户端:访问令牌、Stream 注册、会话 webhook / 机器人 OpenAPI 发消息、
+// 媒体上传、消息文件下载、凭据校验。
+// 线程安全:令牌刷新在锁内单飞(同一时刻只有一个换令牌请求),其余调用可并发。
+//
+// 两套接口的失败形态不同,都要检查:
+//   - 新版 api.dingtalk.com:HTTP 4xx + {"code","message","requestid"};
+//   - 旧版 oapi.dingtalk.com 与会话 webhook:HTTP 200 + {"errcode":非 0,"errmsg"}。
+
+#include "im/dingtalk/dingtalk_protocol.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <filesystem>
+#include <mutex>
+#include <string>
+#include <vector>
+
+namespace acecode::im::dingtalk {
+
+struct ApiOptions {
+    std::string client_id;      // Client ID(原 AppKey),不是密钥
+    std::string client_secret;  // Client Secret(原 AppSecret)
+    std::string robot_code;     // 机器人编码;空 = 与 client_id 相同(企业内部应用即如此)
+    std::string api_base = kApiBase;
+    std::string oapi_base = kOapiBase;
+    bool use_proxy = true;
+};
+
+struct ApiResult {
+    bool ok = false;
+    ApiError error;
+    nlohmann::json response = nlohmann::json::object();
+};
+
+// POST /v1.0/gateway/connections/open 的结果。ticket 一次性、90 秒有效。
+struct StreamTicket {
+    bool ok = false;
+    std::string endpoint;
+    std::string ticket;
+    ApiError error;
+    bool auth_failed = false;  // 401 authFailed:凭据无效,不会自己好
+    bool rejected = false;     // 其它 4xx:应用未发布 / 机器人未开 Stream 模式 / IP 白名单
+    std::string reason;        // 给用户看的中文原因(已脱敏)
+};
+
+// 保存凭据前的联网校验结果。
+struct VerifyResult {
+    bool ok = false;
+    bool auth_failed = false;  // Client ID / Client Secret 不对
+    bool rejected = false;     // 凭据对,但钉钉拒绝建立 Stream 连接(未发布、未开 Stream 模式等)
+    bool network = false;      // 网络不通
+    std::string error;         // 中文一句话,不含凭据
+    std::string client_id;
+    std::string robot_code;
+};
+
+class Api {
+public:
+    explicit Api(ApiOptions options);
+
+    // 有效令牌;到期前 5 分钟刷新。失败返回空串,error 为不含密钥的原因。
+    std::string access_token(std::string* error);
+    void invalidate_token();
+    // 最近一次换令牌失败是不是因为凭据被拒(而不是网络问题)。
+    bool last_token_auth_failed() const;
+
+    // Stream 注册:用 clientId/clientSecret 直接换 endpoint + ticket(不需要令牌)。
+    StreamTicket open_stream(std::chrono::milliseconds timeout);
+
+    // 校验凭据:先换令牌,再做一次 Stream 注册(ticket 丢弃,90 秒后自然失效)。
+    VerifyResult verify();
+
+    // 往会话 webhook 发一条消息(text / markdown)。URL 不在钉钉域名(或配置的接入地址)下时拒绝。
+    ApiResult send_webhook(const std::string& url, const nlohmann::json& body);
+    // 机器人单聊:POST /v1.0/robot/oToMessages/batchSend。成功 = 有 processQueryKey 且该用户
+    // 不在 invalid / flowControlled / filtered 名单里。msg_param 以 JSON 字符串形式发送。
+    ApiResult send_oto(const std::string& robot_code, const std::string& staff_id, const std::string& msg_key,
+                       const nlohmann::json& msg_param);
+    // 机器人群聊:POST /v1.0/robot/groupMessages/send。成功 = 有 processQueryKey。
+    ApiResult send_group(const std::string& robot_code, const std::string& conversation_id,
+                         const std::string& msg_key, const nlohmann::json& msg_param);
+    // POST oapi /media/upload(multipart,字段 type + media)。成功时 response 含 media_id。
+    ApiResult upload_media(const std::string& type, const std::filesystem::path& path, const std::string& name,
+                           const std::string& mime_type);
+    // downloadCode → 临时下载地址(messageFiles/download)。
+    std::string download_url(const std::string& download_code, const std::string& robot_code, std::string* error);
+    // 先换下载地址,再不带任何鉴权头和 Content-Type 地 GET(OSS 签名要求);超过 max_bytes 失败并删掉半截文件。
+    bool download(const std::string& download_code, const std::string& robot_code,
+                  const std::filesystem::path& dest, std::uint64_t max_bytes, std::string* error);
+
+    std::string robot_code() const;
+    // 需要从错误文本里抹掉的值:Client Secret 与当前令牌。
+    std::vector<std::string> secrets() const;
+    const ApiOptions& options() const { return options_; }
+
+private:
+    std::string fetch_token_locked(std::string* error);
+    ApiResult post_api(const std::string& path, const nlohmann::json& body, std::chrono::milliseconds timeout);
+    std::vector<std::string> webhook_bases() const;
+
+    ApiOptions options_;
+    mutable std::mutex mu_;
+    std::string token_;
+    std::chrono::steady_clock::time_point refresh_at_{};
+    bool auth_failed_ = false;
+    long last_token_status_ = 0;
+};
+
+} // namespace acecode::im::dingtalk
diff --git a/src/adapters/im/dingtalk/dingtalk_protocol.cpp b/src/adapters/im/dingtalk/dingtalk_protocol.cpp
new file mode 100644
index 000000000..d0d8c85c1
--- /dev/null
+++ b/src/adapters/im/dingtalk/dingtalk_protocol.cpp
@@ -0,0 +1,620 @@
+#include "dingtalk_protocol.hpp"
+
+#include <algorithm>
+#include <cctype>
+
+namespace acecode::im::dingtalk {
+namespace {
+
+constexpr int kMaxQuoteDepth = 3;
+
+std::string lower(std::string text) {
+    std::transform(text.begin(), text.end(), text.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return text;
+}
+
+bool contains_ci(const std::string& haystack, const std::string& needle) {
+    return lower(haystack).find(lower(needle)) != std::string::npos;
+}
+
+bool starts_with(std::string_view text, std::string_view prefix) {
+    return text.size() >= prefix.size() && text.compare(0, prefix.size(), prefix) == 0;
+}
+
+// 除 ASCII 空白外,钉钉 @ 提及后常见的 U+2005(四分之一 em 空格)、不换行空格与全角空格也算空白。
+std::size_t space_length(std::string_view text, std::size_t pos) {
+    const auto c = static_cast<unsigned char>(text[pos]);
+    if (c == ' ' || c == '\t' || c == '\r' || c == '\n' || c == '\f' || c == '\v') return 1;
+    if (starts_with(text.substr(pos), "\xC2\xA0")) return 2;
+    if (starts_with(text.substr(pos), "\xE2\x80\x85")) return 3;
+    if (starts_with(text.substr(pos), "\xE3\x80\x80")) return 3;
+    return 0;
+}
+
+bool ends_with_space(std::string_view text, std::size_t end) {
+    if (end == 0) return false;
+    const auto c = static_cast<unsigned char>(text[end - 1]);
+    if (c == ' ' || c == '\t' || c == '\r' || c == '\n' || c == '\f' || c == '\v') return true;
+    if (end >= 2 && text.substr(end - 2, 2) == "\xC2\xA0") return true;
+    if (end >= 3 && (text.substr(end - 3, 3) == "\xE2\x80\x85" || text.substr(end - 3, 3) == "\xE3\x80\x80"))
+        return true;
+    return false;
+}
+
+std::string trim(std::string_view text) {
+    std::size_t b = 0;
+    while (b < text.size()) {
+        const auto n = space_length(text, b);
+        if (!n) break;
+        b += n;
+    }
+    std::size_t e = text.size();
+    while (e > b) {
+        const auto c = static_cast<unsigned char>(text[e - 1]);
+        if (c == ' ' || c == '\t' || c == '\r' || c == '\n' || c == '\f' || c == '\v') {
+            --e;
+        } else if (e - b >= 2 && text.substr(e - 2, 2) == "\xC2\xA0") {
+            e -= 2;
+        } else if (e - b >= 3 &&
+                   (text.substr(e - 3, 3) == "\xE2\x80\x85" || text.substr(e - 3, 3) == "\xE3\x80\x80")) {
+            e -= 3;
+        } else {
+            break;
+        }
+    }
+    return std::string(text.substr(b, e - b));
+}
+
+// 字段值按“字符串或数字”读取;其它类型(含缺失)返回空串。
+std::string str(const nlohmann::json& value, const char* key) {
+    if (!value.is_object()) return {};
+    const auto it = value.find(key);
+    if (it == value.end()) return {};
+    if (it->is_string()) return it->get<std::string>();
+    if (it->is_number_integer()) return std::to_string(it->get<std::int64_t>());
+    if (it->is_number_unsigned()) return std::to_string(it->get<std::uint64_t>());
+    return {};
+}
+
+std::int64_t int_field(const nlohmann::json& value, const char* key) {
+    if (!value.is_object()) return 0;
+    const auto it = value.find(key);
+    if (it == value.end()) return 0;
+    if (it->is_number_integer()) return it->get<std::int64_t>();
+    if (it->is_number_unsigned()) return static_cast<std::int64_t>(it->get<std::uint64_t>());
+    if (it->is_number_float()) return static_cast<std::int64_t>(it->get<double>());
+    if (it->is_string()) {
+        try {
+            return std::stoll(it->get<std::string>());
+        } catch (...) {
+        }
+    }
+    return 0;
+}
+
+bool bool_field(const nlohmann::json& value, const char* key) {
+    if (!value.is_object()) return false;
+    const auto it = value.find(key);
+    if (it == value.end()) return false;
+    if (it->is_boolean()) return it->get<bool>();
+    if (it->is_string()) return lower(it->get<std::string>()) == "true";
+    if (it->is_number_integer()) return it->get<std::int64_t>() != 0;
+    return false;
+}
+
+// content 可能是对象,也可能是 JSON 编码的字符串;字符串解析失败时原样返回。
+nlohmann::json unwrap(const nlohmann::json& value) {
+    if (!value.is_string()) return value;
+    const auto& text = value.get_ref<const std::string&>();
+    const auto first = text.find_first_not_of(" \t\r\n");
+    if (first == std::string::npos || (text[first] != '{' && text[first] != '[')) return value;
+    try {
+        return nlohmann::json::parse(text);
+    } catch (...) {
+        return value;
+    }
+}
+
+nlohmann::json child(const nlohmann::json& value, const char* key) {
+    if (!value.is_object()) return nlohmann::json();
+    const auto it = value.find(key);
+    return it == value.end() ? nlohmann::json() : unwrap(*it);
+}
+
+// 地址里的 id:非空、不超过 128 字节、只有可打印 ASCII 且不含空白与引号。
+bool id_ok(const std::string& id) {
+    if (id.empty() || id.size() > 128) return false;
+    for (const char c : id) {
+        const auto u = static_cast<unsigned char>(c);
+        if (u <= 0x20 || u >= 0x7F || c == '"' || c == '\\') return false;
+    }
+    return true;
+}
+
+nlohmann::json rich_text_items(const nlohmann::json& data, const nlohmann::json& content) {
+    for (const auto& candidate : {child(content, "richText"), child(content, "richTextList"),
+                                  child(child(data, "richText"), "richTextList"), child(data, "richText")}) {
+        if (candidate.is_array()) return candidate;
+    }
+    return nlohmann::json::array();
+}
+
+std::string join_rich_text(const nlohmann::json& items) {
+    std::string out;
+    for (const auto& item : items) {
+        if (!item.is_object()) continue;
+        const auto type = lower(str(item, "type"));
+        if (!type.empty() && type != "text") continue;
+        const auto text = trim(str(item, "text"));
+        if (text.empty()) continue;
+        if (!out.empty()) out += "\n";
+        out += text;
+    }
+    return out;
+}
+
+Attachment make_attachment(AttachmentKind kind, const std::string& code, const std::string& name) {
+    Attachment attachment;
+    attachment.kind = kind;
+    attachment.remote_ref = code;
+    attachment.name = name;
+    return attachment;
+}
+
+std::string download_code(const nlohmann::json& content) {
+    auto code = str(content, "downloadCode");
+    if (code.empty()) code = str(content, "pictureDownloadCode");
+    return code;
+}
+
+// 富文本里的媒体项。语音项必须仍按语音处理(Hermes #38211)。
+void collect_rich_media(const nlohmann::json& items, std::vector<Attachment>& out) {
+    for (const auto& item : items) {
+        if (!item.is_object()) continue;
+        const auto code = download_code(item);
+        if (code.empty()) continue;
+        const auto type = lower(str(item, "type"));
+        if (type == "voice" || type == "audio") {
+            auto attachment = make_attachment(AttachmentKind::Voice, code, str(item, "fileName"));
+            attachment.transcript = trim(str(item, "recognition"));
+            out.push_back(std::move(attachment));
+        } else if (type == "video") {
+            out.push_back(make_attachment(AttachmentKind::Video, code, str(item, "fileName")));
+        } else if (type == "file") {
+            out.push_back(make_attachment(AttachmentKind::File, code, str(item, "fileName")));
+        } else {
+            out.push_back(make_attachment(AttachmentKind::Image, code, str(item, "fileName")));
+        }
+    }
+}
+
+std::string card_url(const nlohmann::json& content) {
+    for (const char* key : {"biz_custom_action_url", "url", "docUrl"}) {
+        const auto value = str(content, key);
+        if (!value.empty()) return value;
+    }
+    const auto inner = child(content, "content");
+    if (inner.is_string()) return trim(inner.get<std::string>());
+    for (const char* key : {"url", "docUrl"}) {
+        const auto value = str(inner, key);
+        if (!value.empty()) return value;
+    }
+    return {};
+}
+
+std::string document_line(const nlohmann::json& content) {
+    const auto title = trim(str(content, "title"));
+    const auto url = trim(card_url(content));
+    std::string line = "[文档]";
+    if (!title.empty()) line += " " + title;
+    if (!url.empty()) line += " " + url;
+    return title.empty() && url.empty() ? std::string{} : line;
+}
+
+std::string quote_of(const nlohmann::json& holder, int depth) {
+    if (!bool_field(holder, "isReplyMsg")) return {};
+    const auto replied = child(holder, "repliedMsg");
+    if (!replied.is_object()) return {};
+    auto type = str(replied, "msgType");
+    if (type.empty()) type = str(replied, "msgtype");
+    return extract_text(type, child(replied, "content"), depth + 1);
+}
+
+bool mentioned_bot(const nlohmann::json& data) {
+    const auto bot = str(data, "chatbotUserId");
+    const bool has_flag = data.contains("isInAtList");
+    const auto users = child(data, "atUsers");
+    bool in_users = false;
+    if (users.is_array() && !bot.empty()) {
+        for (const auto& user : users) in_users = in_users || str(user, "dingtalkId") == bot;
+    }
+    if (bool_field(data, "isInAtList") || in_users) return true;
+    // 两个字段都缺:企业内部机器人在群里本来只能收到 @ 它的消息。
+    return !has_flag && !users.is_array();
+}
+
+// 去掉群消息里对机器人自己的 @。只有 atUsers 里没有别人、且正文恰好只有一个
+// “位于开头或空白之后”的 @ 记号时才去掉,不碰邮箱、git@host 之类的文字。
+std::string strip_bot_mention(const std::string& text, const nlohmann::json& data) {
+    const auto bot = str(data, "chatbotUserId");
+    const auto users = child(data, "atUsers");
+    if (users.is_array()) {
+        for (const auto& user : users) {
+            const auto id = str(user, "dingtalkId");
+            if (!id.empty() && id != bot) return text;  // 还 @ 了别人:分不清哪个是机器人
+        }
+    }
+    std::vector<std::size_t> marks;
+    for (std::size_t i = 0; i < text.size(); ++i) {
+        if (text[i] == '@' && (i == 0 || ends_with_space(text, i))) marks.push_back(i);
+    }
+    if (marks.size() != 1) return text;
+    const auto begin = marks.front();
+    auto end = begin + 1;
+    while (end < text.size() && !space_length(text, end)) ++end;
+    if (end == begin + 1) return text;  // 孤立的 "@"
+    // 只去掉位于正文开头或末尾的 @(选人插入的提及几乎都在这两处),中间的 @ 文字原样保留。
+    const bool at_start = trim(std::string_view(text).substr(0, begin)).empty();
+    const bool at_end = trim(std::string_view(text).substr(end)).empty();
+    if (!at_start && !at_end) return text;
+    if (end < text.size()) end += space_length(text, end);
+    return text.substr(0, begin) + text.substr(end);
+}
+
+std::size_t utf8_length(std::string_view text, std::size_t pos) {
+    const auto lead = static_cast<unsigned char>(text[pos]);
+    std::size_t length = 1;
+    if (lead >= 0xF0 && lead <= 0xF4) length = 4;
+    else if (lead >= 0xE0) length = 3;
+    else if (lead >= 0xC2 && lead <= 0xDF) length = 2;
+    return pos + length > text.size() ? 1 : length;
+}
+
+bool numbered_line(std::string_view line) {
+    const auto stripped = trim(line);
+    std::size_t i = 0;
+    while (i < stripped.size() && std::isdigit(static_cast<unsigned char>(stripped[i]))) ++i;
+    return i > 0 && i + 1 < stripped.size() && stripped[i] == '.' &&
+           (stripped[i + 1] == ' ' || stripped[i + 1] == '\t');
+}
+
+std::size_t leading_spaces(std::string_view line) {
+    std::size_t i = 0;
+    while (i < line.size() && (line[i] == ' ' || line[i] == '\t')) ++i;
+    return i;
+}
+
+} // namespace
+
+bool is_encrypted_sender_id(const std::string& id) { return starts_with(id, "$:"); }
+
+std::string extract_text(const std::string& msgtype, const nlohmann::json& content, int depth) {
+    if (depth > kMaxQuoteDepth) return {};
+    const auto value = unwrap(content);
+    if (value.is_string()) return trim(value.get<std::string>());
+    if (!value.is_object()) return {};
+    const auto type = lower(msgtype);
+    for (const char* key : {"text", "content"}) {
+        const auto field = child(value, key);
+        if (field.is_string()) {
+            const auto text = trim(field.get<std::string>());
+            if (!text.empty()) return text;
+        } else if (field.is_object() && depth < kMaxQuoteDepth) {
+            const auto text = extract_text(type, field, depth + 1);
+            if (!text.empty()) return text;
+        }
+    }
+    const auto rich = rich_text_items(nlohmann::json::object(), value);
+    if (!rich.empty()) {
+        const auto text = join_rich_text(rich);
+        if (!text.empty()) return text;
+    }
+    if (type == "picture" || type == "image") return "[图片]";
+    if (type == "file") {
+        const auto name = trim(str(value, "fileName"));
+        return name.empty() ? "[文件]" : "[文件] " + name;
+    }
+    if (type == "audio" || type == "voice") {
+        const auto recognition = trim(str(value, "recognition"));
+        return recognition.empty() ? "[语音]" : recognition;
+    }
+    if (type == "video") return "[视频]";
+    if (type == "interactivecard" || type == "card") return document_line(value);
+    return trim(str(value, "title"));
+}
+
+std::optional<Inbound> parse_robot_message(const nlohmann::json& data, const std::string& client_id,
+                                           const std::string& fallback_id) {
+    if (!data.is_object()) return std::nullopt;
+    Inbound inbound;
+    inbound.message_id = str(data, "msgId");
+    if (inbound.message_id.empty()) inbound.message_id = fallback_id;
+    if (inbound.message_id.empty()) return std::nullopt;
+
+    const bool group = str(data, "conversationType") == "2";
+    const auto staff = str(data, "senderStaffId");
+    const auto user = staff.empty() ? str(data, "senderId") : staff;
+    auto& address = inbound.address;
+    address.platform = kPlatform;
+    address.account = client_id;
+    address.kind = group ? ChatKind::Group : ChatKind::Private;
+    address.chat = group ? str(data, "conversationId") : user;
+    address.sender = user;
+    if (!id_ok(address.account) || !id_ok(address.chat) || !id_ok(address.sender)) return std::nullopt;
+    inbound.mentioned = group ? mentioned_bot(data) : true;
+    inbound.sender_name = trim(str(data, "senderNick"));
+
+    const auto msgtype = lower(str(data, "msgtype"));
+    const auto content = child(data, "content");
+    std::string text;
+    if (msgtype == "richtext") {
+        const auto items = rich_text_items(data, content);
+        text = join_rich_text(items);
+        collect_rich_media(items, inbound.attachments);
+        inbound.quote_text = quote_of(content, 0);
+    } else if (msgtype == "picture" || msgtype == "image") {
+        const auto code = download_code(content);
+        if (!code.empty())
+            inbound.attachments.push_back(make_attachment(AttachmentKind::Image, code, str(content, "fileName")));
+    } else if (msgtype == "file") {
+        const auto code = download_code(content);
+        if (!code.empty()) {
+            auto attachment = make_attachment(AttachmentKind::File, code, str(content, "fileName"));
+            const auto size = int_field(content, "fileSize");
+            if (size > 0) attachment.size = static_cast<std::uint64_t>(size);
+            inbound.attachments.push_back(std::move(attachment));
+        }
+    } else if (msgtype == "audio" || msgtype == "voice") {
+        // 平台已经给了识别文字:不再附带音频重新转写(Hermes:重转写常把好结果覆盖成失败)。
+        auto attachment = make_attachment(AttachmentKind::Voice, download_code(content), {});
+        attachment.transcript = trim(str(content, "recognition"));
+        if (!attachment.remote_ref.empty() || !attachment.transcript.empty())
+            inbound.attachments.push_back(std::move(attachment));
+    } else if (msgtype == "video") {
+        const auto code = download_code(content);
+        if (!code.empty()) {
+            const auto ext = lower(str(content, "videoType"));
+            inbound.attachments.push_back(
+                make_attachment(AttachmentKind::Video, code, ext.empty() ? std::string{} : "video." + ext));
+        }
+    } else if (msgtype == "interactivecard" || msgtype == "card") {
+        text = document_line(content);
+    } else if (msgtype == "unknownmsgtype") {
+        // 机器人收不到的消息类型(平台只给一句提示):交给上层回复“暂不支持”。
+        inbound.attachments.push_back(make_attachment(AttachmentKind::Other, {}, {}));
+    } else {
+        // text / markdown / reply 以及未来的新类型:先看 text.content,再看 content。
+        const auto text_obj = child(data, "text");
+        text = trim(str(text_obj, "content"));
+        inbound.quote_text = quote_of(text_obj, 0);
+        if (text.empty()) text = extract_text(msgtype, content);
+        if (inbound.quote_text.empty()) inbound.quote_text = quote_of(content, 0);
+    }
+    if (group && !text.empty()) text = strip_bot_mention(text, data);
+    inbound.text = trim(text);
+    if (inbound.text.empty() && inbound.attachments.empty()) return std::nullopt;
+
+    nlohmann::json context{{"conversationType", group ? "2" : "1"},
+                           {"conversationId", str(data, "conversationId")},
+                           {"senderStaffId", staff},
+                           {"msgId", inbound.message_id}};
+    const auto webhook = str(data, "sessionWebhook");
+    if (!webhook.empty()) {
+        context["sessionWebhook"] = webhook;
+        context["sessionWebhookExpiredTime"] = int_field(data, "sessionWebhookExpiredTime");
+    }
+    const auto robot = str(data, "robotCode");
+    if (!robot.empty()) context["robotCode"] = robot;
+    inbound.reply_context = std::move(context);
+    return inbound;
+}
+
+ApiError parse_api_error(long status, const std::string& body) {
+    ApiError error;
+    error.status = status;
+    try {
+        const auto json = nlohmann::json::parse(body);
+        if (json.is_object()) {
+            error.code = str(json, "code");
+            error.errcode = static_cast<long>(int_field(json, "errcode"));
+            error.message = str(json, "message");
+            if (error.message.empty()) error.message = str(json, "errmsg");
+            for (const char* key : {"requestid", "requestId", "request_id"}) {
+                if (error.request_id.empty()) error.request_id = str(json, key);
+            }
+        }
+    } catch (...) {
+    }
+    if (error.message.empty()) {
+        if (!error.code.empty()) error.message = error.code;
+        else if (status > 0) error.message = "HTTP " + std::to_string(status);
+    }
+    return error;
+}
+
+bool body_has_errcode(const std::string& body, ApiError* error) {
+    try {
+        const auto json = nlohmann::json::parse(body);
+        if (!json.is_object() || !json.contains("errcode")) return false;
+        if (int_field(json, "errcode") == 0) return false;
+        if (error) *error = parse_api_error(200, body);
+        return true;
+    } catch (...) {
+        return false;
+    }
+}
+
+bool is_token_error(const ApiError& error) {
+    return error.code == "InvalidAuthentication" || error.status == 401 || error.errcode == 40014 ||
+           error.errcode == 42001;
+}
+
+Throttle throttle_kind(const ApiError& error) {
+    if (contains_ci(error.code, "QpsLimit")) return Throttle::Qps;
+    if (error.status == 429 || error.errcode == 130101 || error.errcode == 90018 || error.errcode == 90006)
+        return Throttle::Rate;
+    if (contains_ci(error.code, "send.too.fast") || contains_ci(error.code, "SendTooFast") ||
+        contains_ci(error.code, "Throttling"))
+        return Throttle::Rate;
+    if (contains_ci(error.message, "too fast") || error.message.find("频率过快") != std::string::npos ||
+        error.message.find("发送过快") != std::string::npos)
+        return Throttle::Rate;
+    return Throttle::None;
+}
+
+bool is_webhook_gone(const ApiError& error) {
+    if (error.errcode == 300001 || error.status == 404) return true;
+    return error.errcode != 0 && contains_ci(error.message, "session");
+}
+
+std::string describe_api_error(const ApiError& error) {
+    if (error.status == 0)
+        return error.message.empty() ? std::string("无法连接钉钉开放平台") : "无法连接钉钉开放平台:" + error.message;
+    const bool permission = contains_ci(error.code, "AccessTokenPermissionDenied") ||
+                            (contains_ci(error.code, "Forbidden.AccessDenied") && !contains_ci(error.code, "QpsLimit"));
+    if (permission)
+        return "应用缺少「企业内机器人发送消息」权限(qyapi_robot_sendmsg),请在钉钉开发者后台开通并重新发布";
+    if (contains_ci(error.code, "notAllow")) return "机器人未开通主动发送消息,请在钉钉开发者后台检查机器人配置";
+    if (error.errcode == 60020) return "本机出口 IP 不在钉钉应用的服务器 IP 白名单中";
+    if (contains_ci(error.code, "invalidClientIdOrSecret") || error.code == "authFailed" || error.errcode == 40096)
+        return "Client ID 或 Client Secret 不正确";
+    if (contains_ci(error.code, "robotCode") || error.message.find("机器人编码") != std::string::npos)
+        return "机器人编码错误:请确认机器人已添加到应用并重新发布";
+    if (throttle_kind(error) != Throttle::None) return "钉钉发送过于频繁,请稍后再试";
+    std::string text = "钉钉返回错误";
+    if (!error.message.empty()) text += ":" + error.message;
+    else if (error.status > 0) text += ":HTTP " + std::to_string(error.status);
+    return text;
+}
+
+bool webhook_url_allowed(const std::string& url, const std::vector<std::string>& extra_bases) {
+    for (const char c : url) {
+        if (static_cast<unsigned char>(c) <= 0x20 || c == '\\') return false;
+    }
+    const auto lowered = lower(url);
+    if (starts_with(lowered, "https://api.dingtalk.com/") || starts_with(lowered, "https://oapi.dingtalk.com/"))
+        return true;
+    for (auto base : extra_bases) {
+        while (!base.empty() && base.back() == '/') base.pop_back();
+        if (base.empty()) continue;
+        if (starts_with(lowered, lower(base) + "/")) return true;
+    }
+    return false;
+}
+
+std::string markdown_title(std::string_view markdown, const std::string& fallback) {
+    std::size_t pos = 0;
+    while (pos <= markdown.size()) {
+        auto end = markdown.find('\n', pos);
+        if (end == std::string_view::npos) end = markdown.size();
+        auto line = std::string(markdown.substr(pos, end - pos));
+        pos = end + 1;
+        std::size_t b = 0;
+        while (b < line.size() && std::string_view("#*>-+ \t`").find(line[b]) != std::string_view::npos) ++b;
+        std::string cleaned;
+        for (std::size_t i = b; i < line.size(); ++i) {
+            if (line[i] != '*' && line[i] != '`') cleaned.push_back(line[i]);
+        }
+        cleaned = trim(cleaned);
+        if (cleaned.empty()) {
+            if (end == markdown.size()) break;
+            continue;
+        }
+        std::size_t cut = 0, chars = 0;
+        while (cut < cleaned.size() && chars < kTitleChars) {
+            cut += utf8_length(cleaned, cut);
+            ++chars;
+        }
+        return trim(cleaned.substr(0, cut));
+    }
+    return fallback;
+}
+
+std::string normalize_markdown(std::string_view markdown) {
+    std::vector<std::string> lines;
+    std::size_t pos = 0;
+    while (true) {
+        const auto end = markdown.find('\n', pos);
+        if (end == std::string_view::npos) {
+            lines.emplace_back(markdown.substr(pos));
+            break;
+        }
+        lines.emplace_back(markdown.substr(pos, end - pos));
+        pos = end + 1;
+    }
+    std::string out;
+    bool in_fence = false;
+    std::size_t fence_indent = 0;
+    std::string previous;
+    bool first = true;
+    for (auto& line : lines) {
+        const auto indent = leading_spaces(line);
+        const bool fence = std::string_view(line).substr(indent).rfind("```", 0) == 0;
+        if (fence && !in_fence) {
+            in_fence = true;
+            fence_indent = indent;
+            line = line.substr(indent);
+        } else if (fence && in_fence) {
+            in_fence = false;
+            line = line.substr(std::min(indent, fence_indent));
+            fence_indent = 0;
+        } else if (in_fence) {
+            line = line.substr(std::min(indent, fence_indent));
+        } else if (numbered_line(line) && !first && !trim(previous).empty() && !numbered_line(previous)) {
+            out += "\n";
+        }
+        if (!first) out += "\n";
+        out += line;
+        previous = line;
+        first = false;
+    }
+    return out;
+}
+
+std::string file_extension(const std::string& name) {
+    const auto slash = name.find_last_of("/\\");
+    const auto base = slash == std::string::npos ? name : name.substr(slash + 1);
+    const auto dot = base.find_last_of('.');
+    if (dot == std::string::npos || dot == 0 || dot + 1 >= base.size()) return {};
+    return lower(base.substr(dot + 1));
+}
+
+bool is_image_file(const std::string& mime_type, const std::string& name) {
+    const auto mime = lower(mime_type);
+    if (mime == "image/png" || mime == "image/jpeg" || mime == "image/jpg" || mime == "image/gif" ||
+        mime == "image/bmp")
+        return true;
+    if (!mime.empty() && mime.rfind("image/", 0) != 0 && mime != "application/octet-stream") return false;
+    const auto ext = file_extension(name);
+    return ext == "png" || ext == "jpg" || ext == "jpeg" || ext == "gif" || ext == "bmp";
+}
+
+std::string upload_type_for(const std::string& mime_type, const std::string& name) {
+    if (is_image_file(mime_type, name)) return "image";
+    const auto mime = lower(mime_type);
+    const auto ext = file_extension(name);
+    if (mime == "audio/amr" || mime == "audio/mpeg" || mime == "audio/mp3" || mime == "audio/wav" ||
+        ext == "amr" || ext == "mp3" || ext == "wav")
+        return "voice";
+    return "file";
+}
+
+std::string url_encode(const std::string& value) {
+    static constexpr char kHex[] = "0123456789ABCDEF";
+    std::string out;
+    for (const char c : value) {
+        const auto u = static_cast<unsigned char>(c);
+        if ((u >= 'A' && u <= 'Z') || (u >= 'a' && u <= 'z') || (u >= '0' && u <= '9') || u == '-' ||
+            u == '_' || u == '.' || u == '~') {
+            out.push_back(c);
+        } else {
+            out.push_back('%');
+            out.push_back(kHex[u >> 4]);
+            out.push_back(kHex[u & 0x0F]);
+        }
+    }
+    return out;
+}
+
+} // namespace acecode::im::dingtalk
diff --git a/src/adapters/im/dingtalk/dingtalk_protocol.hpp b/src/adapters/im/dingtalk/dingtalk_protocol.hpp
new file mode 100644
index 000000000..a8d8140df
--- /dev/null
+++ b/src/adapters/im/dingtalk/dingtalk_protocol.hpp
@@ -0,0 +1,106 @@
+#pragma once
+
+// 钉钉企业内部应用机器人(Stream 模式)协议常量与纯解析逻辑,不做 IO。
+// 参照:open-dingtalk 官方 Stream SDK(python / node / go)、aliyun/dingtalk-sdk 的机器人 OpenAPI
+// 字段名、钉钉官方 openclaw connector,以及 Hermes 钉钉适配器的踩坑记录。
+
+#include "im/transport.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace acecode::im::dingtalk {
+
+inline constexpr const char* kPlatform = "dingtalk";
+// 新版 OpenAPI(令牌、Stream 注册、机器人发消息、文件下载)。
+inline constexpr const char* kApiBase = "https://api.dingtalk.com";
+// 旧版 OAPI(媒体上传、会话 webhook)。新版令牌在这里同样有效。
+inline constexpr const char* kOapiBase = "https://oapi.dingtalk.com";
+// 机器人收消息的回调主题。
+inline constexpr const char* kBotMessageTopic = "/v1.0/im/bot/messages/get";
+
+// 单条消息上限(按码点)。社区资料给出 4000 / 5000 / 20000 三种说法,取保守值。
+inline constexpr std::size_t kMaxTextChars = 3500;
+// Markdown 消息的 title 只用于通知栏与会话列表预览,截到 20 个字符。
+inline constexpr std::size_t kTitleChars = 20;
+inline constexpr const char* kDefaultTitle = "ACECode";
+
+// 消息里没有 senderStaffId(组织外用户)时,发言人用加密的 senderId,形如 "$:LWCP_v1:$…"。
+// 这种 id 不能用于机器人单聊 OpenAPI,只能经会话 webhook 回复。
+bool is_encrypted_sender_id(const std::string& id);
+
+// 把 Stream 推送的机器人消息(data 二次解析后的对象)转换为入站消息。
+//   - conversationType "1" = 单聊:chat = sender = senderStaffId(没有时用 senderId);
+//   - "2" = 群聊:chat = conversationId,sender = senderStaffId(没有时用 senderId);
+//   - message_id 取 msgId(重投时不变);缺失时用 fallback_id(Stream 帧头的 messageId);
+//   - 群聊 mentioned 看 isInAtList / atUsers 是否含机器人自己;两者都缺时视为点名
+//     (企业内部机器人在群里本来只能收到 @ 它的消息);
+//   - 文本、富文本、图片、文件、语音(带识别文字)、视频、文档卡片都转成文字或附件,
+//     附件的 remote_ref 是 downloadCode;无文字也无附件时返回 nullopt。
+// 地址字段只做长度与可打印字符检查,不调用 Address::valid()。
+std::optional<Inbound> parse_robot_message(const nlohmann::json& data, const std::string& client_id,
+                                           const std::string& fallback_id = {});
+
+// 从引用消息、富文本等任意形态的 content 里抽出可读文字(递归最多 3 层)。
+std::string extract_text(const std::string& msgtype, const nlohmann::json& content, int depth = 0);
+
+// 新版 OpenAPI 失败形如 HTTP 4xx + {"code","message","requestid"};
+// 旧版 OAPI 与会话 webhook 一律 HTTP 200 + {"errcode","errmsg"}。两种都解析到这里。
+struct ApiError {
+    long status = 0;          // HTTP 状态码;0 = 没拿到响应
+    std::string code;         // 新版 OpenAPI 的字符串错误码
+    long errcode = 0;         // OAPI / webhook 的数字错误码
+    std::string message;      // 平台给的原因(已去掉凭据前由调用方脱敏)
+    std::string request_id;   // 只写日志
+};
+
+// 解析失败响应;body 为空或不是 JSON 时用 HTTP 状态码兜底。
+ApiError parse_api_error(long status, const std::string& body);
+// HTTP 200 的响应体里是否带了非零 errcode(OAPI 与 webhook 的失败形态)。
+bool body_has_errcode(const std::string& body, ApiError* error);
+
+// 令牌失效(InvalidAuthentication / HTTP 401 / errcode 40014):清掉缓存令牌后重试一次。
+bool is_token_error(const ApiError& error);
+
+enum class Throttle {
+    None,
+    Qps,   // 接口 QPS 超限(code 含 QpsLimit):短暂等待后重试
+    Rate,  // 发送过快(send.too.fast / 130101 / 90018 / 90006 / HTTP 429):长等待后重试
+};
+Throttle throttle_kind(const ApiError& error);
+
+// 会话 webhook 已失效(errcode 300001 "session 不存在" 等),应改走 OpenAPI。
+bool is_webhook_gone(const ApiError& error);
+
+// 给用户看的一句中文原因(权限未开、IP 白名单、网络不通等给出处理办法);不含凭据,
+// 调用方仍要再经 redact_secrets。
+std::string describe_api_error(const ApiError& error);
+
+// 防 SSRF:只接受 https://api.dingtalk.com/ 或 https://oapi.dingtalk.com/ 开头的 webhook,
+// 以及 extra_bases 里列出的前缀(测试把 OpenAPI 地址换成本机假服务时使用)。
+bool webhook_url_allowed(const std::string& url, const std::vector<std::string>& extra_bases);
+
+// Markdown 消息的标题:第一行非空文字去掉 # * > - 等标记与首尾空白,截到 kTitleChars 个码点;
+// 为空时用 fallback。
+std::string markdown_title(std::string_view markdown, const std::string& fallback = kDefaultTitle);
+
+// 钉钉 Markdown 渲染器的两个怪癖(Hermes 实测):
+//   - 编号列表行的上一行是普通文字(非空、也不是编号行)时,中间要补一个空行,否则不渲染成列表;
+//   - 带缩进的 ``` 围栏不被识别,去掉围栏行(及其内容)前的公共缩进。
+std::string normalize_markdown(std::string_view markdown);
+
+// 媒体上传的 type:image / voice / file(视频也按 file 上传,与官方 connector 一致)。
+std::string upload_type_for(const std::string& mime_type, const std::string& name);
+bool is_image_file(const std::string& mime_type, const std::string& name);
+// 文件扩展名(小写、不带点);没有扩展名时为空。
+std::string file_extension(const std::string& name);
+
+// URL 查询参数编码(RFC 3986 非保留字符原样保留)。
+std::string url_encode(const std::string& value);
+
+} // namespace acecode::im::dingtalk
diff --git a/src/adapters/im/dingtalk/dingtalk_route.cpp b/src/adapters/im/dingtalk/dingtalk_route.cpp
new file mode 100644
index 000000000..87f3c4ff2
--- /dev/null
+++ b/src/adapters/im/dingtalk/dingtalk_route.cpp
@@ -0,0 +1,162 @@
+#include "dingtalk_route.hpp"
+
+#include <iterator>
+
+namespace acecode::im::dingtalk {
+namespace {
+
+std::string text(const nlohmann::json& value, const char* key) {
+    if (!value.is_object()) return {};
+    const auto it = value.find(key);
+    if (it == value.end()) return {};
+    if (it->is_string()) return it->get<std::string>();
+    if (it->is_number_integer()) return std::to_string(it->get<std::int64_t>());
+    return {};
+}
+
+std::int64_t number(const nlohmann::json& value, const char* key) {
+    if (!value.is_object()) return 0;
+    const auto it = value.find(key);
+    if (it == value.end()) return 0;
+    if (it->is_number_integer()) return it->get<std::int64_t>();
+    if (it->is_number_unsigned()) return static_cast<std::int64_t>(it->get<std::uint64_t>());
+    if (it->is_string()) {
+        try {
+            return std::stoll(it->get<std::string>());
+        } catch (...) {
+        }
+    }
+    return 0;
+}
+
+} // namespace
+
+Route route_from_context(const nlohmann::json& reply_context) {
+    Route route;
+    if (!reply_context.is_object()) return route;
+    route.webhook = text(reply_context, "sessionWebhook");
+    route.webhook_expires_ms = number(reply_context, "sessionWebhookExpiredTime");
+    route.conversation_id = text(reply_context, "conversationId");
+    route.group = text(reply_context, "conversationType") == "2";
+    route.staff_id = text(reply_context, "senderStaffId");
+    route.robot_code = text(reply_context, "robotCode");
+    route.msg_id = text(reply_context, "msgId");
+    return route;
+}
+
+bool webhook_usable(const Route& route, std::int64_t now_ms, std::int64_t margin_ms) {
+    return !route.webhook.empty() && route.webhook_expires_ms > 0 && now_ms + margin_ms < route.webhook_expires_ms;
+}
+
+RouteBook::RouteBook(std::size_t capacity, std::size_t dead_capacity)
+    : capacity_(capacity == 0 ? 1 : capacity), dead_capacity_(dead_capacity == 0 ? 1 : dead_capacity) {}
+
+void RouteBook::remember(const std::string& key, const Route& route) {
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto it = entries_.find(key);
+    if (it != entries_.end()) {
+        order_.erase(it->second.order);
+        entries_.erase(it);
+    }
+    order_.push_back(key);
+    entries_[key] = Entry{route, std::prev(order_.end())};
+    while (entries_.size() > capacity_) {
+        entries_.erase(order_.front());
+        order_.pop_front();
+    }
+}
+
+std::optional<Route> RouteBook::find(const std::string& key) const {
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto it = entries_.find(key);
+    if (it == entries_.end()) return std::nullopt;
+    return it->second.route;
+}
+
+Route RouteBook::resolve(const std::string& key, const nlohmann::json& reply_context, std::int64_t now_ms,
+                         std::int64_t margin_ms) const {
+    auto route = route_from_context(reply_context);
+    std::lock_guard<std::mutex> lock(mu_);
+    const bool context_ok = webhook_usable(route, now_ms, margin_ms) && !dead_.count(route.webhook);
+    if (!context_ok) {
+        route.webhook.clear();
+        route.webhook_expires_ms = 0;
+    }
+    const auto it = entries_.find(key);
+    if (it == entries_.end()) return route;
+    const auto& cached = it->second.route;
+    const bool cached_ok = webhook_usable(cached, now_ms, margin_ms) && !dead_.count(cached.webhook);
+    if (cached_ok && (!context_ok || cached.webhook_expires_ms > route.webhook_expires_ms)) {
+        route.webhook = cached.webhook;
+        route.webhook_expires_ms = cached.webhook_expires_ms;
+    }
+    if (route.staff_id.empty()) route.staff_id = cached.staff_id;
+    if (route.robot_code.empty()) route.robot_code = cached.robot_code;
+    if (route.conversation_id.empty()) route.conversation_id = cached.conversation_id;
+    if (route.msg_id.empty()) route.msg_id = cached.msg_id;
+    if (!reply_context.is_object() || !reply_context.contains("conversationType")) route.group = cached.group;
+    return route;
+}
+
+void RouteBook::mark_webhook_dead(const std::string& webhook) {
+    if (webhook.empty()) return;
+    std::lock_guard<std::mutex> lock(mu_);
+    if (!dead_.insert(webhook).second) return;
+    dead_order_.push_back(webhook);
+    while (dead_order_.size() > dead_capacity_) {
+        dead_.erase(dead_order_.front());
+        dead_order_.pop_front();
+    }
+}
+
+bool RouteBook::webhook_dead(const std::string& webhook) const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return dead_.count(webhook) > 0;
+}
+
+std::size_t RouteBook::size() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return entries_.size();
+}
+
+RateLimiter::Clock::time_point RateLimiter::reserve(const std::string& chat, Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    auto at = now;
+    const auto blocked = blocked_until_.find(chat);
+    if (blocked != blocked_until_.end() && blocked->second > at) at = blocked->second;
+    auto& sends = sends_[chat];
+    const auto per_window = limits_.per_window == 0 ? std::size_t{1} : limits_.per_window;
+    while (true) {
+        while (!sends.empty() && sends.front() + limits_.window <= at) sends.pop_front();
+        if (sends.size() < per_window) break;
+        at = sends.front() + limits_.window;
+    }
+    sends.push_back(at);
+    return at;
+}
+
+void RateLimiter::penalize(const std::string& chat, std::chrono::milliseconds wait, Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    auto& until = blocked_until_[chat];
+    const auto candidate = now + wait;
+    if (until < candidate) until = candidate;
+}
+
+bool DedupSet::seen(const std::string& key) {
+    std::lock_guard<std::mutex> lock(mu_);
+    if (keys_.count(key)) return true;
+    keys_.insert(key);
+    order_.push_back(key);
+    while (order_.size() > capacity_) {
+        keys_.erase(order_.front());
+        order_.pop_front();
+    }
+    return false;
+}
+
+bool DedupSet::contains(const std::string& key) const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return keys_.count(key) > 0;
+}
+
+} // namespace acecode::im::dingtalk
diff --git a/src/adapters/im/dingtalk/dingtalk_route.hpp b/src/adapters/im/dingtalk/dingtalk_route.hpp
new file mode 100644
index 000000000..0bfc12b80
--- /dev/null
+++ b/src/adapters/im/dingtalk/dingtalk_route.hpp
@@ -0,0 +1,113 @@
+#pragma once
+
+// 钉钉出站路由(纯逻辑,不做 IO):
+//   - Route:一次回复需要的平台信息(会话 webhook 及其到期时间、conversationId、staffId、robotCode);
+//   - RouteBook:按会话键记住最近一条入站消息带来的 Route(上限 500 条,超出淘汰最久未更新的),
+//     并记住已被平台判定失效的 webhook,避免从持久化的回复上下文里再次拿出来用;
+//   - RateLimiter:同一会话每 60 秒最多 20 条(钉钉机器人发送频率上限,超出会被封 10 分钟),
+//     平台报“发送过快”时按要求暂停该会话。调用方先 reserve 得到发送时刻,等到该时刻再发。
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <deque>
+#include <list>
+#include <map>
+#include <mutex>
+#include <optional>
+#include <set>
+#include <string>
+#include <unordered_map>
+
+namespace acecode::im::dingtalk {
+
+struct Route {
+    std::string webhook;
+    std::int64_t webhook_expires_ms = 0;  // 墙钟毫秒(sessionWebhookExpiredTime)
+    std::string conversation_id;
+    bool group = false;
+    std::string staff_id;
+    std::string robot_code;
+    std::string msg_id;
+};
+
+// 从入站消息的 reply_context 还原 Route;字段缺失时保持空值。
+Route route_from_context(const nlohmann::json& reply_context);
+
+// webhook 在 now_ms + margin_ms 之后仍然有效(提前 margin 视为过期,Hermes 用 5 分钟)。
+bool webhook_usable(const Route& route, std::int64_t now_ms, std::int64_t margin_ms);
+
+class RouteBook {
+public:
+    explicit RouteBook(std::size_t capacity = 500, std::size_t dead_capacity = 500);
+
+    // 记录某会话最新一条入站消息的 Route(覆盖旧值并刷新淘汰顺序)。
+    void remember(const std::string& key, const Route& route);
+    std::optional<Route> find(const std::string& key) const;
+
+    // 合并缓存与本次的回复上下文:webhook 取两者中仍可用且到期更晚的一个(已失效的跳过),
+    // staffId / robotCode / conversationId 缺失时互相补齐。
+    Route resolve(const std::string& key, const nlohmann::json& reply_context, std::int64_t now_ms,
+                  std::int64_t margin_ms) const;
+
+    // 平台说这个 webhook 已失效(session 不存在):以后不再使用。
+    void mark_webhook_dead(const std::string& webhook);
+    bool webhook_dead(const std::string& webhook) const;
+    std::size_t size() const;
+
+private:
+    struct Entry {
+        Route route;
+        std::list<std::string>::iterator order;
+    };
+
+    std::size_t capacity_;
+    std::size_t dead_capacity_;
+    mutable std::mutex mu_;
+    std::list<std::string> order_;  // 最近更新的在尾部
+    std::unordered_map<std::string, Entry> entries_;
+    std::set<std::string> dead_;
+    std::deque<std::string> dead_order_;
+};
+
+class RateLimiter {
+public:
+    using Clock = std::chrono::steady_clock;
+
+    struct Limits {
+        std::size_t per_window = 20;
+        std::chrono::milliseconds window{std::chrono::minutes(1)};
+    };
+
+    RateLimiter() = default;
+    explicit RateLimiter(Limits limits) : limits_(limits) {}
+
+    // 预约一条消息的发送时刻;返回值不早于 now。预约即占用名额。
+    Clock::time_point reserve(const std::string& chat, Clock::time_point now);
+    // 平台对该会话报“发送过快”:wait 之内不再预约到该会话。
+    void penalize(const std::string& chat, std::chrono::milliseconds wait, Clock::time_point now);
+
+private:
+    Limits limits_;
+    std::mutex mu_;
+    std::map<std::string, Clock::time_point> blocked_until_;
+    std::map<std::string, std::deque<Clock::time_point>> sends_;
+};
+
+// 有界去重集合:按插入顺序淘汰,超过 capacity 时丢最旧的。线程安全。
+class DedupSet {
+public:
+    explicit DedupSet(std::size_t capacity = 2000) : capacity_(capacity) {}
+    // 第一次见到返回 false 并记下;见过返回 true。
+    bool seen(const std::string& key);
+    bool contains(const std::string& key) const;
+
+private:
+    std::size_t capacity_;
+    mutable std::mutex mu_;
+    std::set<std::string> keys_;
+    std::deque<std::string> order_;
+};
+
+} // namespace acecode::im::dingtalk
diff --git a/src/adapters/im/dingtalk/dingtalk_stream.cpp b/src/adapters/im/dingtalk/dingtalk_stream.cpp
new file mode 100644
index 000000000..542e78935
--- /dev/null
+++ b/src/adapters/im/dingtalk/dingtalk_stream.cpp
@@ -0,0 +1,123 @@
+#include "dingtalk_stream.hpp"
+
+#include "im/dingtalk/dingtalk_protocol.hpp"
+
+#include <algorithm>
+#include <cctype>
+
+namespace acecode::im::dingtalk {
+namespace {
+
+std::string upper(std::string text) {
+    std::transform(text.begin(), text.end(), text.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::toupper(c)); });
+    return text;
+}
+
+std::string header_value(const nlohmann::json& headers, const char* key) {
+    if (!headers.is_object()) return {};
+    const auto it = headers.find(key);
+    if (it == headers.end()) return {};
+    if (it->is_string()) return it->get<std::string>();
+    if (it->is_number_integer()) return std::to_string(it->get<std::int64_t>());
+    if (it->is_number_unsigned()) return std::to_string(it->get<std::uint64_t>());
+    return {};
+}
+
+} // namespace
+
+std::optional<StreamFrame> parse_stream_frame(const std::string& text) {
+    nlohmann::json json;
+    try {
+        json = nlohmann::json::parse(text);
+    } catch (...) {
+        return std::nullopt;
+    }
+    if (!json.is_object()) return std::nullopt;
+    StreamFrame frame;
+    if (json.contains("type") && json["type"].is_string()) frame.type = upper(json["type"].get<std::string>());
+    if (frame.type.empty()) return std::nullopt;
+    if (json.contains("headers") && json["headers"].is_object()) frame.headers = json["headers"];
+    frame.topic = header_value(frame.headers, "topic");
+    frame.message_id = header_value(frame.headers, "messageId");
+    if (json.contains("data")) {
+        const auto& data = json["data"];
+        if (data.is_string()) frame.data = data.get<std::string>();
+        else if (!data.is_null()) frame.data = data.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace);
+    }
+    return frame;
+}
+
+std::string stream_reply(const std::string& message_id, int code, const std::string& message,
+                         const std::string& data) {
+    nlohmann::json reply{{"code", code},
+                         {"headers", {{"contentType", "application/json"}, {"messageId", message_id}}},
+                         {"message", message},
+                         {"data", data}};
+    return reply.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace);
+}
+
+StreamSession::StreamSession(std::chrono::milliseconds idle_timeout) : idle_timeout_(idle_timeout) {}
+
+void StreamSession::on_connected(Clock::time_point now) {
+    connected_at_ = now;
+    last_frame_ = now;
+    frames_ = 0;
+}
+
+StreamSession::Output StreamSession::on_frame(const std::string& text, Clock::time_point now,
+                                              bool accept_messages) {
+    Output out;
+    // 任何下行文本帧都说明连接仍然活着,包括无法解析的帧。
+    last_frame_ = now;
+    ++frames_;
+    const auto frame = parse_stream_frame(text);
+    if (!frame) {
+        out.invalid = true;
+        return out;
+    }
+    if (frame->type == "SYSTEM") {
+        out.system_topic = frame->topic.empty() ? std::string("(none)") : frame->topic;
+        // ping 必须把 data(含 opaque)原样回显;其它 SYSTEM 帧回执无害(python SDK 一律回 200)。
+        if (!frame->message_id.empty()) out.replies.push_back(stream_reply(frame->message_id, 200, "OK", frame->data));
+        if (frame->topic == "disconnect") out.disconnect = true;
+        return out;
+    }
+    if (frame->type == "CALLBACK") {
+        if (frame->topic != kBotMessageTopic) {
+            out.ignored_topic = frame->topic;
+            if (!frame->message_id.empty())
+                out.replies.push_back(stream_reply(frame->message_id, 404, "not implemented", ""));
+            return out;
+        }
+        if (!accept_messages) {
+            out.deferred = true;
+            return out;
+        }
+        if (!frame->message_id.empty())
+            out.replies.push_back(stream_reply(frame->message_id, 200, "OK", kCallbackAckData));
+        out.messages.push_back({frame->message_id, frame->data});
+        return out;
+    }
+    // EVENT 或未知类型:没有订阅,回 SUCCESS 让平台不再重投。
+    out.ignored_topic = frame->type + " " + frame->topic;
+    if (!frame->message_id.empty()) out.replies.push_back(stream_reply(frame->message_id, 200, "OK", kEventAckData));
+    return out;
+}
+
+bool StreamSession::idle_expired(Clock::time_point now) const {
+    if (idle_timeout_.count() <= 0) return false;
+    return now - last_frame_ >= idle_timeout_;
+}
+
+std::chrono::milliseconds stream_backoff(std::size_t attempt, std::chrono::milliseconds base,
+                                         std::chrono::milliseconds cap, std::chrono::milliseconds jitter) {
+    if (base.count() <= 0) base = std::chrono::milliseconds(1);
+    auto delay = base;
+    for (std::size_t i = 0; i < attempt && delay < cap; ++i) delay *= 2;
+    delay = std::min(delay, cap);
+    if (jitter.count() > 0) delay += jitter;
+    return std::min(delay, cap);
+}
+
+} // namespace acecode::im::dingtalk
diff --git a/src/adapters/im/dingtalk/dingtalk_stream.hpp b/src/adapters/im/dingtalk/dingtalk_stream.hpp
new file mode 100644
index 000000000..118698463
--- /dev/null
+++ b/src/adapters/im/dingtalk/dingtalk_stream.hpp
@@ -0,0 +1,86 @@
+#pragma once
+
+// 钉钉 Stream 长连接的帧编解码与会话状态(纯逻辑,不做 IO)。
+//
+// 下行帧:{"specVersion","type":"SYSTEM|EVENT|CALLBACK","headers":{topic,messageId,…},"data":"<JSON 字符串>"}。
+// 上行回执:{"code":200,"headers":{"contentType":"application/json","messageId":<原帧>},"message":"OK","data":"<字符串>"}。
+// 规则(官方 SDK 一致):
+//   - 机器人消息(CALLBACK /v1.0/im/bot/messages/get)先回执、后处理;不回执或回非 200 会被重投;
+//   - SYSTEM ping 必须回执,data 原样回显;
+//   - SYSTEM disconnect 先回执,再关连接并立即用新 ticket 重连(先关再回执会让平台重发断开指令);
+//   - 未订阅的 CALLBACK 主题回 404;EVENT(未订阅,仍到达时)回 SUCCESS 防止重投;
+//   - 头部字段的值可能是字符串也可能是数字,一律按“字符串或数字”读取。
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace acecode::im::dingtalk {
+
+struct StreamFrame {
+    std::string type;        // 大写:SYSTEM / EVENT / CALLBACK
+    std::string topic;
+    std::string message_id;  // headers.messageId;disconnect 帧可能没有
+    nlohmann::json headers = nlohmann::json::object();
+    std::string data;        // data 原文(本身是 JSON 字符串);缺失时为空
+};
+
+// 解析下行帧;不是 JSON 对象或缺 type 时返回 nullopt。
+std::optional<StreamFrame> parse_stream_frame(const std::string& text);
+
+// 构造上行回执帧。data 是要放进 "data" 字段的字符串(本身通常是 JSON 文本)。
+std::string stream_reply(const std::string& message_id, int code, const std::string& message,
+                         const std::string& data);
+
+// 机器人消息回执的 data(协议文档:该主题不消费回执内容)。
+inline constexpr const char* kCallbackAckData = "{\"response\":null}";
+inline constexpr const char* kEventAckData = "{\"status\":\"SUCCESS\",\"message\":\"success\"}";
+
+class StreamSession {
+public:
+    using Clock = std::chrono::steady_clock;
+
+    struct Message {
+        std::string message_id;  // 帧头 messageId(每次重投都不同)
+        std::string data;        // 机器人消息 JSON 文本(待二次解析)
+    };
+
+    struct Output {
+        std::vector<std::string> replies;  // 要立刻按顺序发出的回执帧
+        std::vector<Message> messages;     // 已回执的机器人消息
+        bool disconnect = false;           // 平台要求断开:发完回执后关闭并立即重连
+        bool deferred = false;             // 本地队列已满,机器人消息未回执(平台稍后重投)
+        bool invalid = false;              // 无法解析的帧(只记日志)
+        std::string system_topic;          // 收到的 SYSTEM 帧主题(日志用)
+        std::string ignored_topic;         // 未订阅的 CALLBACK / EVENT 主题(已回执,日志用)
+    };
+
+    // idle_timeout:连续这么久收不到任何帧就判定连接已失效;0 表示不检测。
+    explicit StreamSession(std::chrono::milliseconds idle_timeout = std::chrono::seconds(120));
+
+    // WebSocket 握手成功后调用。
+    void on_connected(Clock::time_point now);
+    // accept_messages=false 时机器人消息既不回执也不派发,让平台稍后重投(本地处理队列已满)。
+    Output on_frame(const std::string& text, Clock::time_point now, bool accept_messages = true);
+    // 到期检测:超过 idle_timeout 没收到任何帧时返回 true。
+    bool idle_expired(Clock::time_point now) const;
+
+    std::size_t frames() const { return frames_; }
+    Clock::time_point connected_at() const { return connected_at_; }
+
+private:
+    std::chrono::milliseconds idle_timeout_;
+    Clock::time_point connected_at_{};
+    Clock::time_point last_frame_{};
+    std::size_t frames_ = 0;
+};
+
+// 重连等待:min(base·2^attempt, cap),jitter 在 [0, jitter) 内由调用方给出。
+std::chrono::milliseconds stream_backoff(std::size_t attempt, std::chrono::milliseconds base,
+                                         std::chrono::milliseconds cap, std::chrono::milliseconds jitter);
+
+} // namespace acecode::im::dingtalk
diff --git a/src/adapters/im/dingtalk/dingtalk_transport.cpp b/src/adapters/im/dingtalk/dingtalk_transport.cpp
new file mode 100644
index 000000000..3f7ee0e24
--- /dev/null
+++ b/src/adapters/im/dingtalk/dingtalk_transport.cpp
@@ -0,0 +1,537 @@
+#include "dingtalk_transport.hpp"
+
+#include "im/redact.hpp"
+#include "im/text_chunk.hpp"
+#include "utils/logger.hpp"
+
+#include <algorithm>
+
+namespace acecode::im::dingtalk {
+namespace {
+
+constexpr std::chrono::seconds kAckTimeout{10};
+
+std::int64_t wall_now_ms() {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(
+               std::chrono::system_clock::now().time_since_epoch())
+        .count();
+}
+
+SendResult sent() { return {SendOutcome::Sent, {}}; }
+SendResult failed(const std::string& error) { return {SendOutcome::Failed, error}; }
+SendResult held(const std::string& error) { return {SendOutcome::Held, error}; }
+
+// OpenAPI 明确拒绝(4xx 或 200 但未送达)且不是限流:等对方下一条消息带来新 webhook 时补发。
+bool refused(const ApiError& error) {
+    return error.status >= 200 && error.status < 500 && throttle_kind(error) == Throttle::None;
+}
+
+std::string markdown_escape_label(const std::string& name) {
+    std::string out;
+    for (const char c : name) {
+        if (c == '[' || c == ']' || c == '(' || c == ')' || c == '\n' || c == '\r') continue;
+        out.push_back(c);
+    }
+    return out.empty() ? std::string("image") : out;
+}
+
+} // namespace
+
+DingTalkTransport::DingTalkTransport(DingTalkTransportOptions options)
+    : options_(std::move(options)),
+      api_(options_.api),
+      session_(options_.idle_timeout),
+      limiter_(options_.limits),
+      rng_(static_cast<std::minstd_rand::result_type>(Clock::now().time_since_epoch().count())) {
+    status_.account = options_.api.client_id;
+    status_.extra["robot_code"] = api_.robot_code();
+}
+
+DingTalkTransport::~DingTalkTransport() { stop(); }
+
+Capabilities DingTalkTransport::capabilities() const {
+    Capabilities caps;
+    caps.max_text_units = kMaxTextChars;
+    caps.count_utf16 = false;
+    // 每会话每分钟最多 20 条且没有编辑接口:同一回合的输出合并成尽量少的消息。
+    caps.batch_turn_output = true;
+    caps.supports_typing = false;
+    caps.max_upload_bytes = options_.max_upload_bytes;
+    caps.max_download_bytes = options_.max_download_bytes;
+    return caps;
+}
+
+void DingTalkTransport::start(TransportCallbacks callbacks) {
+    if (running_.exchange(true)) return;
+    callbacks_ = std::move(callbacks);
+    stopping_ = false;
+    reader_ = acecode::JoiningThread(&DingTalkTransport::run, this);
+    dispatcher_ = acecode::JoiningThread(&DingTalkTransport::dispatch_loop, this);
+}
+
+void DingTalkTransport::stop() {
+    if (!running_.exchange(false)) return;
+    {
+        // 置位与通知都在各自的锁内完成,等待方不会错过唤醒。
+        std::lock_guard<std::mutex> lock(wake_mu_);
+        stopping_ = true;
+    }
+    ws_.abort();
+    wake_.notify_all();
+    {
+        // 分发线程在 inbox_mu_ 下检查 stopping_;先拿一次这把锁再通知,避免它错过唤醒。
+        std::lock_guard<std::mutex> lock(inbox_mu_);
+    }
+    inbox_cv_.notify_all();
+    if (reader_.joinable()) reader_.join();
+    if (dispatcher_.joinable()) dispatcher_.join();
+    ws_.close();
+    {
+        std::lock_guard<std::mutex> lock(inbox_mu_);
+        inbox_.clear();  // 未处理的消息已回执;平台不会重投,只能丢弃并记日志
+    }
+    set_status(LinkState::Stopped, {});
+}
+
+TransportStatus DingTalkTransport::status() const {
+    std::lock_guard<std::mutex> lock(status_mu_);
+    auto copy = status_;
+    copy.extra["held"] = held_count();
+    return copy;
+}
+
+void DingTalkTransport::set_status(LinkState state, const std::string& detail, bool retry_stopped) {
+    TransportStatus snapshot;
+    {
+        std::lock_guard<std::mutex> lock(status_mu_);
+        const auto clean = redact_secrets(detail, {options_.api.client_secret});
+        if (status_.state == state && status_.detail == clean && status_.retry_stopped == retry_stopped) return;
+        status_.state = state;
+        status_.detail = clean;
+        status_.retry_stopped = retry_stopped;
+        snapshot = status_;
+    }
+    if (callbacks_.on_status) callbacks_.on_status(snapshot);
+}
+
+bool DingTalkTransport::wait_for(std::chrono::milliseconds duration) {
+    std::unique_lock<std::mutex> lock(wake_mu_);
+    wake_.wait_for(lock, duration, [this] { return stopping_.load(); });
+    return !stopping_;
+}
+
+bool DingTalkTransport::sleep_until(Clock::time_point at) {
+    const auto now = Clock::now();
+    if (at <= now) return true;
+    return wait_for(std::chrono::duration_cast<std::chrono::milliseconds>(at - now) + std::chrono::milliseconds(1));
+}
+
+std::chrono::milliseconds DingTalkTransport::next_backoff(std::size_t attempt) {
+    std::chrono::milliseconds jitter{0};
+    if (options_.jitter) jitter = std::chrono::milliseconds(static_cast<long long>(rng_() % 1000));
+    return stream_backoff(attempt, options_.backoff_base, options_.backoff_cap, jitter);
+}
+
+std::size_t DingTalkTransport::pending_count() {
+    std::lock_guard<std::mutex> lock(inbox_mu_);
+    return inbox_.size();
+}
+
+void DingTalkTransport::run() {
+    std::size_t attempt = 0;
+    while (!stopping_) {
+        set_status(attempt == 0 ? LinkState::Connecting : LinkState::Retrying,
+                   attempt == 0 ? "正在连接钉钉" : "正在重新连接钉钉");
+        bool immediate = false;
+        const auto ticket = api_.open_stream(options_.open_timeout);
+        if (!ticket.ok) {
+            if (ticket.auth_failed || ticket.rejected) {
+                // 凭据无效 / 应用未发布等不会自己好:停止重试,等用户处理后重新打开。
+                set_status(LinkState::Failed, ticket.reason, true);
+                break;
+            }
+            set_status(LinkState::Retrying, ticket.reason);
+        } else {
+            network::WebSocketConnectOptions ws_options;
+            // ticket 一次性有效;每次连接都重新注册,绝不复用。不带任何自定义头。
+            ws_options.url = ticket.endpoint + (ticket.endpoint.find('?') == std::string::npos ? "?" : "&") +
+                             "ticket=" + url_encode(ticket.ticket);
+            ws_options.connect_timeout = options_.open_timeout;
+            ws_options.use_proxy = options_.api.use_proxy;
+            std::string error;
+            if (!ws_.connect(ws_options, &error)) {
+                LOG_WARN("[channels/dingtalk] stream handshake failed: " +
+                         redact_secrets(error, {options_.api.client_secret, ticket.ticket}));
+                set_status(LinkState::Retrying, "无法连接钉钉 Stream 服务,稍后重试");
+            } else {
+                session_.on_connected(Clock::now());
+                LOG_INFO("[channels/dingtalk] stream connected");
+                set_status(LinkState::Connected, {});
+                std::string reason;
+                const auto end = read_loop(&reason);
+                ws_.close();
+                if (end == ReadEnd::Stopped || stopping_) break;
+                const bool got_frames = session_.frames() > 0;
+                const bool healthy = got_frames && Clock::now() - session_.connected_at() >= options_.healthy_after;
+                if (got_frames) attempt = 0;  // 新连接收到过帧:退避从头计数
+                immediate = healthy && (end == ReadEnd::Disconnect || end == ReadEnd::Closed);
+                set_status(LinkState::Retrying, reason);
+            }
+        }
+        if (stopping_) break;
+        if (immediate) continue;
+        const auto delay = next_backoff(attempt);
+        ++attempt;
+        if (!wait_for(delay)) break;
+    }
+    // 致命错误后保持 Failed 状态,线程退出前等 stop();stop() 负责收尾。
+    if (!stopping_) {
+        std::unique_lock<std::mutex> lock(wake_mu_);
+        wake_.wait(lock, [this] { return stopping_.load(); });
+    }
+}
+
+DingTalkTransport::ReadEnd DingTalkTransport::read_loop(std::string* reason) {
+    while (!stopping_) {
+        if (session_.idle_expired(Clock::now())) {
+            LOG_WARN("[channels/dingtalk] no stream frame for too long, reconnecting");
+            *reason = "钉钉连接长时间无响应,正在重连";
+            return ReadEnd::Idle;
+        }
+        network::WebSocketMessage message;
+        std::string error;
+        const auto received = ws_.receive(message, std::chrono::milliseconds(500), &error);
+        if (received == network::WebSocketRecv::Timeout) continue;
+        if (received == network::WebSocketRecv::Message) {
+            if (message.binary) continue;  // 应用层流量全是文本帧
+            const bool accept = pending_count() < options_.max_pending_inbound;
+            auto out = session_.on_frame(message.data, Clock::now(), accept);
+            // 先回执,再处理:回执只能发回送来该帧的这条连接。
+            for (const auto& reply : out.replies) {
+                std::string send_error;
+                if (!ws_.send_text(reply, kAckTimeout, &send_error))
+                    LOG_WARN("[channels/dingtalk] stream ack failed: " + send_error);
+            }
+            if (out.invalid)
+                LOG_WARN("[channels/dingtalk] ignored an unparsable stream frame (" +
+                         std::to_string(message.data.size()) + " bytes)");
+            if (!out.system_topic.empty() && out.system_topic != "ping")
+                LOG_INFO("[channels/dingtalk] stream system frame: " + out.system_topic);
+            if (!out.ignored_topic.empty())
+                LOG_INFO("[channels/dingtalk] ignored unsubscribed stream topic: " + out.ignored_topic);
+            if (out.deferred)
+                LOG_WARN("[channels/dingtalk] inbound queue full, leaving a robot message for redelivery");
+            bool queued = false;
+            for (auto& item : out.messages) {
+                if (!item.message_id.empty() && frames_seen_.seen(item.message_id)) {
+                    LOG_DEBUG("[channels/dingtalk] duplicate stream delivery skipped");
+                    continue;
+                }
+                std::lock_guard<std::mutex> lock(inbox_mu_);
+                inbox_.push_back({std::move(item.message_id), std::move(item.data)});
+                queued = true;
+            }
+            if (queued) inbox_cv_.notify_all();
+            if (out.disconnect) {
+                // 平台下线 / 负载切换的正常指令:回执已发,关闭后立即用新 ticket 重连。
+                LOG_INFO("[channels/dingtalk] server requested reconnect");
+                *reason = "钉钉要求重新连接";
+                return ReadEnd::Disconnect;
+            }
+            continue;
+        }
+        if (stopping_) break;
+        if (received == network::WebSocketRecv::Closed) {
+            LOG_INFO("[channels/dingtalk] stream closed by server (code " + std::to_string(ws_.close_code()) + ")");
+            *reason = "钉钉连接已断开,正在重连";
+            return ReadEnd::Closed;
+        }
+        LOG_WARN("[channels/dingtalk] stream receive failed: " + redact_secrets(error, {options_.api.client_secret}));
+        *reason = "钉钉连接出错,正在重连";
+        return ReadEnd::Error;
+    }
+    return ReadEnd::Stopped;
+}
+
+void DingTalkTransport::dispatch_loop() {
+    while (true) {
+        Pending pending;
+        {
+            std::unique_lock<std::mutex> lock(inbox_mu_);
+            inbox_cv_.wait(lock, [this] { return stopping_.load() || !inbox_.empty(); });
+            if (stopping_) break;
+            pending = std::move(inbox_.front());
+            inbox_.pop_front();
+        }
+        try {
+            handle_message(pending);
+        } catch (const std::exception& e) {
+            LOG_WARN(std::string("[channels/dingtalk] cannot handle robot message: ") + e.what());
+        }
+    }
+}
+
+void DingTalkTransport::handle_message(const Pending& pending) {
+    nlohmann::json data;
+    try {
+        data = nlohmann::json::parse(pending.data);
+    } catch (...) {
+        LOG_WARN("[channels/dingtalk] robot message payload is not JSON (" + std::to_string(pending.data.size()) +
+                 " bytes)");
+        return;
+    }
+    auto inbound = parse_robot_message(data, options_.api.client_id, pending.message_id);
+    if (!inbound) {
+        LOG_DEBUG("[channels/dingtalk] robot message without usable content skipped");
+        return;
+    }
+    // 重投的消息帧头 messageId 变了,msgId 不变:这里拦第二层。
+    if (messages_seen_.seen(inbound->message_id)) {
+        LOG_DEBUG("[channels/dingtalk] duplicate robot message skipped");
+        return;
+    }
+    routes_.remember(inbound->address.key(), route_from_context(inbound->reply_context));
+    // 先用这条新消息的 webhook 补发之前暂存的输出,再交给核心处理新消息,保证顺序。
+    if (has_held(inbound->address.key())) flush_held(inbound->address, inbound->reply_context);
+    if (callbacks_.on_inbound) callbacks_.on_inbound(std::move(*inbound));
+}
+
+std::shared_ptr<std::mutex> DingTalkTransport::chat_lock(const std::string& key) {
+    std::lock_guard<std::mutex> lock(locks_mu_);
+    auto& slot = chat_locks_[key];
+    if (!slot) slot = std::make_shared<std::mutex>();
+    return slot;
+}
+
+bool DingTalkTransport::has_held(const std::string& key) const {
+    std::lock_guard<std::mutex> lock(held_mu_);
+    const auto it = held_.find(key);
+    return it != held_.end() && !it->second.empty();
+}
+
+void DingTalkTransport::push_held(const std::string& key, std::vector<HeldItem> items) {
+    if (items.empty()) return;
+    std::lock_guard<std::mutex> lock(held_mu_);
+    auto& queue = held_[key];
+    for (auto& item : items) queue.push_back(std::move(item));
+}
+
+std::size_t DingTalkTransport::held_count() const {
+    std::lock_guard<std::mutex> lock(held_mu_);
+    std::size_t total = 0;
+    for (const auto& [key, queue] : held_) total += queue.size();
+    return total;
+}
+
+void DingTalkTransport::flush_held(const Address& to, const nlohmann::json& reply_context) {
+    const auto key = to.key();
+    const auto guard = chat_lock(key);
+    std::lock_guard<std::mutex> lock(*guard);
+    std::deque<HeldItem> items;
+    {
+        std::lock_guard<std::mutex> held_lock(held_mu_);
+        const auto it = held_.find(key);
+        if (it == held_.end()) return;
+        items.swap(it->second);
+        held_.erase(it);
+    }
+    LOG_INFO("[channels/dingtalk] resending " + std::to_string(items.size()) +
+             " held output(s) before the new message");
+    bool first = true;
+    while (!items.empty()) {
+        auto item = items.front();
+        if (first && !item.file) item.text = "(补发)" + item.text;
+        first = false;
+        const auto result = item.file ? send_file_locked(to, item, reply_context)
+                                      : deliver_markdown(to, item.text, reply_context);
+        if (result.outcome == SendOutcome::Held) {
+            if (item.file) {
+                // 文件只能走 OpenAPI;仍被拒时改发一句说明,不再无限暂存。
+                deliver_markdown(to, "文件「" + item.name + "」未能通过钉钉发送,请在 ACECode 中查看。", reply_context);
+                items.pop_front();
+                continue;
+            }
+            std::lock_guard<std::mutex> held_lock(held_mu_);
+            auto& queue = held_[key];
+            for (auto it = items.rbegin(); it != items.rend(); ++it) queue.push_front(*it);
+            return;
+        }
+        if (result.outcome == SendOutcome::Failed)
+            LOG_WARN("[channels/dingtalk] held output dropped after resend failed: " + result.error);
+        items.pop_front();
+    }
+}
+
+template <typename Send>
+ApiResult DingTalkTransport::throttled(const std::string& chat, Send&& send) {
+    ApiResult result;
+    auto rate_wait = options_.throttle_delay;
+    for (int attempt = 0; attempt <= options_.max_send_retries; ++attempt) {
+        if (!sleep_until(limiter_.reserve(chat, Clock::now()))) {
+            result = ApiResult{};
+            result.error.status = 0;
+            result.error.message = "钉钉通道已停止";
+            return result;
+        }
+        result = send();
+        if (result.ok) return result;
+        const auto kind = throttle_kind(result.error);
+        if (kind == Throttle::None) return result;
+        // 平台明确拒收了这条:等待后重发同一条是安全的;同一会话的发送由会话锁串行,不会乱序。
+        std::chrono::milliseconds wait = options_.qps_delay;
+        if (kind == Throttle::Rate) {
+            wait = rate_wait;
+            rate_wait = std::min(rate_wait * 2, options_.throttle_cap);
+        }
+        LOG_INFO("[channels/dingtalk] send throttled, retrying in " +
+                 std::to_string(std::chrono::duration_cast<std::chrono::seconds>(wait).count()) + "s");
+        limiter_.penalize(chat, wait, Clock::now());
+    }
+    return result;
+}
+
+std::string DingTalkTransport::staff_for(const Address& to, const Route& route) const {
+    if (!route.staff_id.empty()) return route.staff_id;
+    if (to.kind == ChatKind::Private && !is_encrypted_sender_id(to.chat)) return to.chat;
+    return {};
+}
+
+SendResult DingTalkTransport::deliver_openapi(const Address& to, const Route& route, const std::string& msg_key,
+                                              const nlohmann::json& msg_param) {
+    const auto robot = route.robot_code.empty() ? api_.robot_code() : route.robot_code;
+    ApiResult result;
+    if (to.kind == ChatKind::Group) {
+        result = throttled(to.chat, [&api = api_, &robot, &to, &msg_key, &msg_param] {
+            return api.send_group(robot, to.chat, msg_key, msg_param);
+        });
+    } else {
+        const auto staff = staff_for(to, route);
+        if (staff.empty()) {
+            LOG_INFO("[channels/dingtalk] no valid session webhook for an external user, holding output");
+            return held("对方不是本组织成员,会话回复地址已过期;对方下一条消息到来时补发");
+        }
+        result = throttled(to.chat, [&api = api_, &robot, &staff, &msg_key, &msg_param] {
+            return api.send_oto(robot, staff, msg_key, msg_param);
+        });
+    }
+    if (result.ok) return sent();
+    const auto reason = redact_secrets(describe_api_error(result.error), api_.secrets());
+    if (refused(result.error)) {
+        LOG_WARN("[channels/dingtalk] robot API refused the message, holding it until the next inbound message");
+        return held(reason);
+    }
+    return failed(reason);
+}
+
+SendResult DingTalkTransport::deliver_markdown(const Address& to, const std::string& markdown,
+                                               const nlohmann::json& reply_context) {
+    const auto title = markdown_title(markdown);
+    const auto route = routes_.resolve(to.key(), reply_context, wall_now_ms(), options_.webhook_margin.count());
+    if (!route.webhook.empty()) {
+        const nlohmann::json body{{"msgtype", "markdown"}, {"markdown", {{"title", title}, {"text", markdown}}}};
+        const auto result = throttled(to.chat, [&api = api_, &route, &body] { return api.send_webhook(route.webhook, body); });
+        if (result.ok) return sent();
+        if (!is_webhook_gone(result.error))
+            return failed(redact_secrets(describe_api_error(result.error), api_.secrets()));
+        LOG_INFO("[channels/dingtalk] session webhook expired, falling back to the robot API");
+        routes_.mark_webhook_dead(route.webhook);
+    }
+    return deliver_openapi(to, route, "sampleMarkdown", {{"title", title}, {"text", markdown}});
+}
+
+SendResult DingTalkTransport::send_text_locked(const Address& to, const std::string& text,
+                                               const nlohmann::json& reply_context) {
+    const auto key = to.key();
+    const auto chunks = chunk_text(normalize_markdown(text), kMaxTextChars, false);
+    for (std::size_t i = 0; i < chunks.size(); ++i) {
+        if (has_held(key)) {
+            // 该会话已有暂存:新输出排在后面,保证顺序。
+            std::vector<HeldItem> rest;
+            for (std::size_t j = i; j < chunks.size(); ++j) rest.push_back(HeldItem{false, chunks[j], {}, {}, {}});
+            push_held(key, std::move(rest));
+            return held({});
+        }
+        const auto result = deliver_markdown(to, chunks[i], reply_context);
+        if (result.outcome == SendOutcome::Failed) return result;
+        if (result.outcome == SendOutcome::Held) {
+            std::vector<HeldItem> rest;
+            for (std::size_t j = i; j < chunks.size(); ++j) rest.push_back(HeldItem{false, chunks[j], {}, {}, {}});
+            push_held(key, std::move(rest));
+            return result;
+        }
+    }
+    return sent();
+}
+
+SendResult DingTalkTransport::send_text(const Address& to, const std::string& text,
+                                        const nlohmann::json& reply_context) {
+    const auto guard = chat_lock(to.key());
+    std::lock_guard<std::mutex> lock(*guard);
+    return send_text_locked(to, text, reply_context);
+}
+
+SendResult DingTalkTransport::send_file_locked(const Address& to, const HeldItem& item,
+                                               const nlohmann::json& reply_context) {
+    std::error_code ec;
+    const auto size = std::filesystem::file_size(item.path, ec);
+    if (ec) return failed("文件不存在或不可读");
+    if (size > options_.max_upload_bytes) {
+        // 分片上传尚未实现:改发一条文字说明,对方至少知道有文件没发过去。
+        const auto limit_mib = std::to_string(options_.max_upload_bytes / (1024u * 1024u));
+        LOG_INFO("[channels/dingtalk] file of " + std::to_string(size) + " bytes is over the " + limit_mib +
+                 " MiB upload limit, sending a text notice instead");
+        return deliver_markdown(to, "文件「" + item.name + "」超过钉钉上传上限(" + limit_mib + " MiB),未发送;请在 ACECode 中查看。",
+                                reply_context);
+    }
+    if (is_image_file(item.mime_type, item.name)) {
+        // 图片以 mediaId 嵌进 Markdown:webhook 与 OpenAPI 都能发,也不额外消耗 OpenAPI 额度。
+        const auto uploaded = api_.upload_media("image", item.path, item.name, item.mime_type);
+        const auto media = uploaded.response.value("media_id", std::string{});
+        if (uploaded.ok && !media.empty())
+            return deliver_markdown(to, "![" + markdown_escape_label(item.name) + "](" + media + ")", reply_context);
+        LOG_WARN("[channels/dingtalk] image upload failed, retrying as a plain file");
+    }
+    const auto route = routes_.resolve(to.key(), reply_context, wall_now_ms(), options_.webhook_margin.count());
+    if (to.kind == ChatKind::Private && staff_for(to, route).empty()) {
+        // 组织外用户只能经 webhook 收文字。
+        return deliver_markdown(to, "文件「" + item.name + "」无法发送给组织外的钉钉用户,请在 ACECode 中查看。",
+                                reply_context);
+    }
+    const auto uploaded = api_.upload_media("file", item.path, item.name, item.mime_type);
+    const auto media = uploaded.response.value("media_id", std::string{});
+    if (!uploaded.ok || media.empty())
+        return failed("上传文件失败:" + redact_secrets(describe_api_error(uploaded.error), api_.secrets()));
+    const auto ext = file_extension(item.name);
+    return deliver_openapi(to, route, "sampleFile",
+                           {{"mediaId", media}, {"fileName", item.name}, {"fileType", ext.empty() ? "file" : ext}});
+}
+
+SendResult DingTalkTransport::send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                                        const std::string& mime_type, const nlohmann::json& reply_context) {
+    const auto key = to.key();
+    const auto guard = chat_lock(key);
+    std::lock_guard<std::mutex> lock(*guard);
+    HeldItem item{true, {}, path, name, mime_type};
+    if (has_held(key)) {
+        push_held(key, {item});
+        return held({});
+    }
+    auto result = send_file_locked(to, item, reply_context);
+    if (result.outcome == SendOutcome::Held) push_held(key, {item});
+    return result;
+}
+
+bool DingTalkTransport::download(const Attachment& attachment, const std::filesystem::path& dest,
+                                 std::string* error) {
+    if (attachment.remote_ref.empty()) {
+        if (error) *error = "附件缺少下载码";
+        return false;
+    }
+    if (attachment.size > options_.max_download_bytes) {
+        if (error) *error = "附件超过大小限制";
+        return false;
+    }
+    return api_.download(attachment.remote_ref, api_.robot_code(), dest, options_.max_download_bytes, error);
+}
+
+} // namespace acecode::im::dingtalk
diff --git a/src/adapters/im/dingtalk/dingtalk_transport.hpp b/src/adapters/im/dingtalk/dingtalk_transport.hpp
new file mode 100644
index 000000000..1fadc6269
--- /dev/null
+++ b/src/adapters/im/dingtalk/dingtalk_transport.hpp
@@ -0,0 +1,153 @@
+#pragma once
+
+// 钉钉机器人传输层:Stream 模式长连接收消息 + 会话 webhook / 机器人 OpenAPI 发消息。
+//
+// 线程:
+//   - reader_:唯一的 WebSocket 读者兼写者。Stream 注册 → 连接 → 收帧;机器人消息先回执再放进
+//     有界队列,绝不在读线程上处理(处理慢会让平台判定连接失效)。
+//   - dispatcher_:从队列取消息,按 msgId 去重、记住回复路由、补发暂存输出,再交给核心。
+//
+// 发送策略(按会话串行,不乱序):
+//   1. 会话 webhook 仍有效(到期前 5 分钟视为过期)→ POST Markdown;
+//   2. 否则走机器人 OpenAPI:群 → groupMessages/send;单聊且有 staffId → oToMessages/batchSend;
+//   3. 组织外用户(只有加密 senderId)且 webhook 已过期,或 OpenAPI 拒绝(权限未开等)→ 暂存,
+//      等该会话下一条消息带来新 webhook 时补发。webhook 报 session 不存在时记为失效并改走 OpenAPI。
+// 每个会话每分钟最多 20 条;平台报发送过快 / QPS 超限时等待后重发同一条。
+//
+// 同一应用只能有一条 Stream 连接在收消息(平台会把每条消息随机推给其中一条连接);
+// 进程间互斥由核心的通道宿主锁保证。
+
+#include "im/dingtalk/dingtalk_api.hpp"
+#include "im/dingtalk/dingtalk_route.hpp"
+#include "im/dingtalk/dingtalk_stream.hpp"
+#include "im/transport.hpp"
+#include "network/websocket_client.hpp"
+#include "utils/joining_thread.hpp"
+
+#include <atomic>
+#include <condition_variable>
+#include <deque>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <random>
+#include <vector>
+
+namespace acecode::im::dingtalk {
+
+struct DingTalkTransportOptions {
+    ApiOptions api;
+    // 重连等待:min(base·2^n + 抖动, cap);收到过帧的连接断开后从头计数。
+    std::chrono::milliseconds backoff_base{std::chrono::seconds(1)};
+    std::chrono::milliseconds backoff_cap{std::chrono::seconds(60)};
+    bool jitter = true;  // 0~1 秒随机抖动,避免多实例同时重连
+    // 连续这么久收不到任何帧(含平台的 SYSTEM ping)就重连;0 = 不检测。
+    std::chrono::milliseconds idle_timeout{std::chrono::seconds(120)};
+    // Stream 注册与 WebSocket 握手的超时。
+    std::chrono::milliseconds open_timeout{std::chrono::seconds(10)};
+    // 存活超过这么久的连接被平台要求断开 / 正常关闭后,立即重连而不退避。
+    std::chrono::milliseconds healthy_after{std::chrono::seconds(5)};
+    RateLimiter::Limits limits;
+    // 平台报“发送过快”后的首次等待,之后每次翻倍,最多到 throttle_cap(超限会被封 10 分钟)。
+    std::chrono::milliseconds throttle_delay{std::chrono::seconds(60)};
+    std::chrono::milliseconds throttle_cap{std::chrono::minutes(10)};
+    // 接口 QPS 超限(QpsLimit)时的等待(官方 connector 用 2 秒)。
+    std::chrono::milliseconds qps_delay{std::chrono::seconds(2)};
+    int max_send_retries = 5;
+    // webhook 到期前多久就不再使用。
+    std::chrono::milliseconds webhook_margin{std::chrono::minutes(5)};
+    std::uint64_t max_upload_bytes = 20u * 1024u * 1024u;
+    std::uint64_t max_download_bytes = 25u * 1024u * 1024u;
+    // 待处理入站消息上限;满了之后新消息不回执,让平台稍后重投。
+    std::size_t max_pending_inbound = 100;
+};
+
+class DingTalkTransport final : public Transport {
+public:
+    explicit DingTalkTransport(DingTalkTransportOptions options);
+    ~DingTalkTransport() override;
+
+    std::string platform() const override { return kPlatform; }
+    Capabilities capabilities() const override;
+    void start(TransportCallbacks callbacks) override;
+    void stop() override;
+    TransportStatus status() const override;
+    SendResult send_text(const Address& to, const std::string& text,
+                         const nlohmann::json& reply_context) override;
+    SendResult send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                         const std::string& mime_type, const nlohmann::json& reply_context) override;
+    bool download(const Attachment& attachment, const std::filesystem::path& dest,
+                  std::string* error) override;
+
+    std::size_t held_count() const;
+
+private:
+    using Clock = std::chrono::steady_clock;
+
+    struct HeldItem {
+        bool file = false;
+        std::string text;
+        std::filesystem::path path;
+        std::string name;
+        std::string mime_type;
+    };
+
+    struct Pending {
+        std::string message_id;
+        std::string data;
+    };
+
+    enum class ReadEnd { Stopped, Disconnect, Closed, Idle, Error };
+
+    void run();
+    ReadEnd read_loop(std::string* reason);
+    void dispatch_loop();
+    void handle_message(const Pending& pending);
+    bool wait_for(std::chrono::milliseconds duration);
+    bool sleep_until(Clock::time_point at);
+    void set_status(LinkState state, const std::string& detail, bool retry_stopped = false);
+    std::chrono::milliseconds next_backoff(std::size_t attempt);
+    std::size_t pending_count();
+
+    std::shared_ptr<std::mutex> chat_lock(const std::string& key);
+    bool has_held(const std::string& key) const;
+    void push_held(const std::string& key, std::vector<HeldItem> items);
+    void flush_held(const Address& to, const nlohmann::json& reply_context);
+
+    SendResult send_text_locked(const Address& to, const std::string& text, const nlohmann::json& reply_context);
+    SendResult send_file_locked(const Address& to, const HeldItem& item, const nlohmann::json& reply_context);
+    SendResult deliver_markdown(const Address& to, const std::string& markdown, const nlohmann::json& reply_context);
+    SendResult deliver_openapi(const Address& to, const Route& route, const std::string& msg_key,
+                               const nlohmann::json& msg_param);
+    std::string staff_for(const Address& to, const Route& route) const;
+    template <typename Send>
+    ApiResult throttled(const std::string& chat, Send&& send);
+
+    DingTalkTransportOptions options_;
+    Api api_;
+    StreamSession session_;
+    RouteBook routes_;
+    RateLimiter limiter_;
+    DedupSet frames_seen_;    // 帧头 messageId
+    DedupSet messages_seen_;  // 消息 msgId(重投时不变)
+    network::WebSocketClient ws_;
+    TransportCallbacks callbacks_;
+    std::minstd_rand rng_;    // 只在 reader_ 上使用
+    std::atomic<bool> running_{false};
+    std::atomic<bool> stopping_{false};
+    std::mutex wake_mu_;
+    std::condition_variable wake_;
+    mutable std::mutex status_mu_;
+    TransportStatus status_;
+    std::mutex inbox_mu_;
+    std::condition_variable inbox_cv_;
+    std::deque<Pending> inbox_;
+    mutable std::mutex held_mu_;
+    std::map<std::string, std::deque<HeldItem>> held_;
+    std::mutex locks_mu_;
+    std::map<std::string, std::shared_ptr<std::mutex>> chat_locks_;
+    acecode::JoiningThread reader_;
+    acecode::JoiningThread dispatcher_;
+};
+
+} // namespace acecode::im::dingtalk
diff --git a/src/adapters/im/discord/discord_api.cpp b/src/adapters/im/discord/discord_api.cpp
new file mode 100644
index 000000000..bbfab666a
--- /dev/null
+++ b/src/adapters/im/discord/discord_api.cpp
@@ -0,0 +1,350 @@
+#include "discord_api.hpp"
+
+#include "im/redact.hpp"
+#include "utils/logger.hpp"
+
+#include <algorithm>
+#include <cctype>
+#include <cmath>
+#include <random>
+
+namespace acecode::im::discord {
+namespace {
+
+std::string trim(const std::string& text) {
+    std::size_t b = 0, e = text.size();
+    while (b < e && std::isspace(static_cast<unsigned char>(text[b]))) ++b;
+    while (e > b && std::isspace(static_cast<unsigned char>(text[e - 1]))) --e;
+    return text.substr(b, e - b);
+}
+
+std::string path_segment(const std::string& value) {
+    static constexpr char kHex[] = "0123456789ABCDEF";
+    std::string out;
+    for (const char c : value) {
+        const auto u = static_cast<unsigned char>(c);
+        if ((u >= 'A' && u <= 'Z') || (u >= 'a' && u <= 'z') || (u >= '0' && u <= '9') || u == '-' || u == '_' ||
+            u == '.' || u == '~') {
+            out.push_back(c);
+        } else {
+            out.push_back('%');
+            out.push_back(kHex[u >> 4]);
+            out.push_back(kHex[u & 0x0F]);
+        }
+    }
+    return out;
+}
+
+// 发消息的幂等键:最多 25 个字符,这里用 19 位以内的随机数字。
+std::string make_nonce() {
+    std::random_device device;
+    const std::uint64_t value = (static_cast<std::uint64_t>(device()) << 32) ^ device();
+    return std::to_string(value % 1000000000000000000ULL);
+}
+
+std::string string_field(const nlohmann::json& value, const char* key) {
+    if (!value.is_object()) return {};
+    const auto it = value.find(key);
+    if (it == value.end()) return {};
+    if (it->is_string()) return it->get<std::string>();
+    if (it->is_number_integer()) return std::to_string(it->get<std::int64_t>());
+    return {};
+}
+
+} // namespace
+
+std::string normalize_token(std::string token) {
+    token = trim(token);
+    if (token.size() > 4 && (token.compare(0, 4, "Bot ") == 0 || token.compare(0, 4, "bot ") == 0))
+        token = trim(token.substr(4));
+    return token;
+}
+
+Api::Api(ApiOptions options, RateLimitPolicy policy) : options_(std::move(options)), policy_(policy) {
+    while (!options_.api_base.empty() && options_.api_base.back() == '/') options_.api_base.pop_back();
+    token_ = normalize_token(options_.token);
+}
+
+std::string Api::url(const std::string& path) const { return options_.api_base + path; }
+
+void Api::cancel() {
+    {
+        std::lock_guard<std::mutex> lock(rl_mu_);
+        cancelled_ = true;
+    }
+    rl_cv_.notify_all();
+}
+
+void Api::reset() {
+    std::lock_guard<std::mutex> lock(rl_mu_);
+    cancelled_ = false;
+}
+
+bool Api::wait_for_route(const std::string& route) {
+    std::unique_lock<std::mutex> lock(rl_mu_);
+    while (true) {
+        if (cancelled_) return false;
+        auto until = global_until_;
+        const auto it = route_until_.find(route);
+        if (it != route_until_.end()) until = (std::max)(until, it->second);
+        if (until <= Clock::now()) return true;
+        rl_cv_.wait_until(lock, until);
+    }
+}
+
+bool Api::sleep_for(std::chrono::milliseconds duration) {
+    std::unique_lock<std::mutex> lock(rl_mu_);
+    rl_cv_.wait_for(lock, duration, [&cancelled = cancelled_] { return cancelled.load(); });
+    return !cancelled_;
+}
+
+void Api::note_rate_limit(const std::string& route, std::chrono::milliseconds wait, bool global) {
+    std::lock_guard<std::mutex> lock(rl_mu_);
+    const auto now = Clock::now();
+    const auto until = now + wait;
+    if (global) {
+        global_until_ = (std::max)(global_until_, until);
+        return;
+    }
+    auto& slot = route_until_[route];
+    slot = (std::max)(slot, until);
+    if (route_until_.size() > 256) {
+        for (auto it = route_until_.begin(); it != route_until_.end();) {
+            if (it->second <= now) it = route_until_.erase(it);
+            else ++it;
+        }
+    }
+}
+
+ApiResult Api::perform(HttpRequest request, const std::string& route) {
+    ApiResult result;
+    const std::vector<std::string> secrets{token_, options_.token};
+    request.use_proxy = options_.use_proxy;
+    request.headers.emplace_back("Authorization", "Bot " + token_);
+    request.headers.emplace_back("User-Agent", discord_user_agent());
+    request.cancel = [&cancelled = cancelled_] { return cancelled.load(); };
+    for (int attempt = 0;; ++attempt) {
+        if (!wait_for_route(route)) {
+            result.cancelled = true;
+            result.error.message = "Request cancelled";
+            return result;
+        }
+        const auto response = http_send(request);
+        result.status = response.status;
+        if (response.cancelled || cancelled_) {
+            result.cancelled = true;
+            result.error = ApiError{};
+            result.error.message = "Request cancelled";
+            return result;
+        }
+        if (response.status == 0) {
+            result.error = ApiError{};
+            result.error.message = redact_secrets(response.error.empty() ? "HTTP request failed" : response.error, secrets);
+            return result;
+        }
+        if (response.status >= 200 && response.status < 300) {
+            result.ok = true;
+            result.error = ApiError{};
+            result.error.status = response.status;
+            if (!trim(response.body).empty()) {
+                try {
+                    result.body = nlohmann::json::parse(response.body);
+                } catch (...) {
+                    result.body = nlohmann::json::object();
+                }
+            }
+            return result;
+        }
+        result.error = parse_api_error(response.status, response.body);
+        result.error.message = redact_secrets(result.error.message, secrets);
+        result.error.detail = redact_secrets(result.error.detail, secrets);
+        if (response.status != 429 || attempt >= policy_.max_retries) return result;
+        // retry_after 是精确值(秒,小数);缺失时(例如 Cloudflare 的 HTML 页)按 1 秒处理。
+        const double seconds = result.error.retry_after > 0 ? result.error.retry_after : 1.0;
+        const auto wait = std::chrono::milliseconds(static_cast<long long>(std::ceil(seconds * 1000.0)));
+        if (wait > policy_.max_wait) {
+            LOG_WARN("[channels/discord] rate limited on " + route + " for " + std::to_string(wait.count()) +
+                     " ms, giving up on this request");
+            return result;
+        }
+        note_rate_limit(route, wait, result.error.global);
+        LOG_INFO("[channels/discord] rate limited on " + route + (result.error.global ? " (global)" : "") +
+                 ", retrying in " + std::to_string(wait.count()) + " ms");
+    }
+}
+
+ApiResult Api::get(const std::string& path, std::chrono::milliseconds timeout) {
+    HttpRequest request;
+    request.url = url(path);
+    request.timeout = timeout;
+    return perform(std::move(request), "GET " + path);
+}
+
+ApiResult Api::post(const std::string& path, const nlohmann::json& body, std::chrono::milliseconds timeout) {
+    HttpRequest request;
+    request.method = "POST";
+    request.url = url(path);
+    request.timeout = timeout;
+    if (!body.is_null()) {
+        request.headers.emplace_back("Content-Type", "application/json");
+        request.body = body.dump();
+    }
+    return perform(std::move(request), "POST " + path);
+}
+
+ApiResult Api::post_multipart(const std::string& path, std::vector<HttpPart> parts,
+                              std::chrono::milliseconds timeout) {
+    HttpRequest request;
+    request.method = "POST";
+    request.url = url(path);
+    request.timeout = timeout;
+    request.parts = std::move(parts);
+    return perform(std::move(request), "POST " + path);
+}
+
+ApiResult Api::current_user() { return get("/users/@me", std::chrono::seconds(15)); }
+
+ApiResult Api::current_application() { return get("/applications/@me", std::chrono::seconds(15)); }
+
+ApiResult Api::gateway_bot() { return get("/gateway/bot", std::chrono::seconds(15)); }
+
+ApiResult Api::open_dm(const std::string& user_id) {
+    return post("/users/@me/channels", nlohmann::json{{"recipient_id", user_id}}, std::chrono::seconds(20));
+}
+
+ApiResult Api::get_message(const std::string& channel_id, const std::string& message_id) {
+    return get("/channels/" + path_segment(channel_id) + "/messages/" + path_segment(message_id),
+               std::chrono::seconds(20));
+}
+
+ApiResult Api::trigger_typing(const std::string& channel_id) {
+    return post("/channels/" + path_segment(channel_id) + "/typing", nlohmann::json(), std::chrono::seconds(10));
+}
+
+ApiResult Api::send_with_nonce(const std::string& path, nlohmann::json body, bool multipart,
+                               const std::filesystem::path& file, const std::string& filename,
+                               const std::string& mime_type) {
+    body["nonce"] = make_nonce();
+    body["enforce_nonce"] = true;
+    ApiResult result;
+    for (int attempt = 0;; ++attempt) {
+        if (multipart) {
+            std::vector<HttpPart> parts;
+            HttpPart payload;
+            payload.name = "payload_json";
+            payload.value = body.dump();
+            payload.content_type = "application/json";
+            parts.push_back(std::move(payload));
+            HttpPart upload;
+            upload.name = "files[0]";
+            upload.file = file;
+            upload.filename = filename;
+            upload.content_type = mime_type.empty() ? "application/octet-stream" : mime_type;
+            parts.push_back(std::move(upload));
+            result = post_multipart(path, std::move(parts));
+        } else {
+            result = post(path, body);
+        }
+        if (result.ok || result.cancelled) return result;
+        const bool transient = result.status == 0 || result.status >= 500;
+        if (!transient || attempt >= policy_.max_send_retries) return result;
+        LOG_INFO("[channels/discord] send failed (" +
+                 (result.status == 0 ? std::string("network error") : "HTTP " + std::to_string(result.status)) +
+                 "), resending with the same nonce");
+        if (!sleep_for(policy_.send_retry_delay * (attempt + 1))) {
+            result.cancelled = true;
+            return result;
+        }
+    }
+}
+
+ApiResult Api::create_message(const std::string& channel_id, nlohmann::json body) {
+    return send_with_nonce("/channels/" + path_segment(channel_id) + "/messages", std::move(body), false, {}, {}, {});
+}
+
+ApiResult Api::create_message_with_file(const std::string& channel_id, nlohmann::json payload,
+                                        const std::filesystem::path& file, const std::string& filename,
+                                        const std::string& mime_type) {
+    return send_with_nonce("/channels/" + path_segment(channel_id) + "/messages", std::move(payload), true, file,
+                           filename, mime_type);
+}
+
+DownloadResult Api::download(const std::string& url, const std::filesystem::path& dest, std::uint64_t max_bytes) {
+    DownloadResult result;
+    HttpRequest request;
+    request.url = url;
+    request.timeout = std::chrono::minutes(2);
+    request.use_proxy = options_.use_proxy;
+    request.download_to = dest;
+    request.max_download_bytes = max_bytes;
+    request.cancel = [&cancelled = cancelled_] { return cancelled.load(); };
+    const auto response = http_send(request);
+    result.status = response.status;
+    result.too_large = response.too_large;
+    result.cancelled = response.cancelled;
+    if (!response.too_large && response.status >= 200 && response.status < 300 && !response.cancelled) {
+        result.ok = true;
+        return result;
+    }
+    std::error_code ec;
+    if (!response.too_large) std::filesystem::remove(dest, ec);
+    // curl 的错误文本可能带完整 URL(含签名),只保留主机名之前的部分不可靠,干脆只给类别。
+    result.error = response.too_large ? "Download exceeds limit"
+                   : response.status == 0 ? "network error"
+                                          : "HTTP " + std::to_string(response.status);
+    return result;
+}
+
+ValidationResult validate_credentials(const ApiOptions& options) {
+    ValidationResult result;
+    ApiOptions normalized = options;
+    normalized.token = normalize_token(options.token);
+    if (normalized.token.empty()) {
+        result.auth_failed = true;
+        result.error = "请填写 Discord Bot Token";
+        return result;
+    }
+    RateLimitPolicy policy;
+    policy.max_retries = 1;
+    policy.max_wait = std::chrono::seconds(10);
+    Api api(normalized, policy);
+    const auto me = api.current_user();
+    if (!me.ok) {
+        const auto& error = me.error;
+        if (me.status == 401 || error.code == 40001) {
+            result.auth_failed = true;
+            result.error = "Bot Token 无效或已被重置,请在 Discord 开发者后台的 Bot 页面重新生成并复制";
+        } else if (me.status == 403 && error.code != 0) {
+            result.auth_failed = true;
+            result.error = "Discord 拒绝了这个机器人账号:" + error.message;
+        } else if (me.status == 403) {
+            result.error = "请求被 Discord 拦截(HTTP 403),可能是当前网络出口被限制,请检查代理";
+        } else if (me.status == 0) {
+            result.error = error.message.empty() ? "无法连接 Discord,请检查网络或代理"
+                                                 : "无法连接 Discord,请检查网络或代理(" + error.message + ")";
+        } else {
+            result.error = describe_error(error);
+        }
+        return result;
+    }
+    result.profile.user_id = string_field(me.body, "id");
+    result.profile.username = string_field(me.body, "username");
+    if (result.profile.user_id.empty()) {
+        result.error = "Discord 返回的机器人信息无效";
+        return result;
+    }
+    const auto app = api.current_application();
+    if (app.ok) {
+        result.profile.application_id = string_field(app.body, "id");
+        result.profile.application_name = string_field(app.body, "name");
+        result.profile.message_content = message_content_intent(app.body);
+    } else {
+        LOG_WARN("[channels/discord] GET /applications/@me failed during validation (HTTP " +
+                 std::to_string(app.status) + "), intent state unknown");
+    }
+    result.profile.invite_url = invite_url(result.profile.application_id);
+    result.ok = true;
+    return result;
+}
+
+} // namespace acecode::im::discord
diff --git a/src/adapters/im/discord/discord_api.hpp b/src/adapters/im/discord/discord_api.hpp
new file mode 100644
index 000000000..c00cf151c
--- /dev/null
+++ b/src/adapters/im/discord/discord_api.hpp
@@ -0,0 +1,137 @@
+#pragma once
+
+// Discord REST 客户端(API v10)。所有请求带 "Authorization: Bot <token>" 与 DiscordBot 格式的
+// User-Agent;429 按响应体的 retry_after(秒,小数)等待后重发,global=true 时暂停全部请求,
+// 否则只暂停同一路由。等待可被 cancel() 打断(停机用)。线程安全。
+//
+// 响应头(X-RateLimit-*)目前拿不到(im::http_send 不返回响应头),所以只能在 429 之后等待,
+// 不能提前避让;对单个机器人足够。
+
+#include "im/discord/discord_protocol.hpp"
+#include "im/http.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <filesystem>
+#include <map>
+#include <mutex>
+#include <string>
+#include <vector>
+
+namespace acecode::im::discord {
+
+struct ApiOptions {
+    std::string token;               // 原始 bot token;带 "Bot " 前缀也接受
+    std::string api_base = kApiBase;
+    bool use_proxy = true;
+};
+
+struct RateLimitPolicy {
+    int max_retries = 4;  // 同一请求遇到 429 最多重发几次
+    // 平台要求的单次等待超过它就不等了,按限流失败返回(避免一条消息卡住几十分钟)。
+    std::chrono::milliseconds max_wait{std::chrono::minutes(5)};
+    // 网络错误或 5xx 时,发消息(带 nonce,不会重复)最多重发几次。
+    int max_send_retries = 2;
+    std::chrono::milliseconds send_retry_delay{std::chrono::seconds(1)};
+};
+
+struct ApiResult {
+    bool ok = false;
+    long status = 0;          // HTTP 状态码;0 = 没拿到响应
+    ApiError error;           // ok=false 时有效;文本已脱敏
+    nlohmann::json body;      // 成功时的响应 JSON;204 / 空响应为 null
+    bool cancelled = false;
+};
+
+struct DownloadResult {
+    bool ok = false;
+    long status = 0;
+    bool too_large = false;
+    bool cancelled = false;
+    std::string error;  // 传输层错误(英文,已脱敏;不含 URL 签名)
+};
+
+// 去掉首尾空白与可选的 "Bot " 前缀。
+std::string normalize_token(std::string token);
+
+class Api {
+public:
+    explicit Api(ApiOptions options, RateLimitPolicy policy = {});
+
+    const ApiOptions& options() const { return options_; }
+    // 规范化后的 token(网关 Identify / Resume 用)。
+    const std::string& token() const { return token_; }
+
+    ApiResult get(const std::string& path, std::chrono::milliseconds timeout = std::chrono::seconds(30));
+    ApiResult post(const std::string& path, const nlohmann::json& body,
+                   std::chrono::milliseconds timeout = std::chrono::seconds(30));
+    ApiResult post_multipart(const std::string& path, std::vector<HttpPart> parts,
+                             std::chrono::milliseconds timeout = std::chrono::minutes(5));
+
+    ApiResult current_user();         // GET /users/@me
+    ApiResult current_application();  // GET /applications/@me
+    ApiResult gateway_bot();          // GET /gateway/bot
+    ApiResult open_dm(const std::string& user_id);  // POST /users/@me/channels
+    ApiResult get_message(const std::string& channel_id, const std::string& message_id);
+    ApiResult trigger_typing(const std::string& channel_id);  // POST /channels/{id}/typing
+    // POST /channels/{id}/messages。自动加 nonce + enforce_nonce,网络错误或 5xx 时用同一 nonce
+    // 重发:请求其实已送达时平台返回原消息,不会出现重复。
+    ApiResult create_message(const std::string& channel_id, nlohmann::json body);
+    // 同上,multipart:payload_json + files[0]。
+    ApiResult create_message_with_file(const std::string& channel_id, nlohmann::json payload,
+                                       const std::filesystem::path& file, const std::string& filename,
+                                       const std::string& mime_type);
+    // 下载 CDN 附件。签名 URL 自带授权,不带 bot token。
+    DownloadResult download(const std::string& url, const std::filesystem::path& dest, std::uint64_t max_bytes);
+
+    // 打断限流等待与进行中的请求;之后的请求立即以 cancelled 返回,直到 reset()。
+    void cancel();
+    void reset();
+
+private:
+    using Clock = std::chrono::steady_clock;
+
+    ApiResult perform(HttpRequest request, const std::string& route);
+    ApiResult send_with_nonce(const std::string& path, nlohmann::json body, bool multipart,
+                              const std::filesystem::path& file, const std::string& filename,
+                              const std::string& mime_type);
+    bool wait_for_route(const std::string& route);
+    bool sleep_for(std::chrono::milliseconds duration);
+    void note_rate_limit(const std::string& route, std::chrono::milliseconds wait, bool global);
+    std::string url(const std::string& path) const;
+
+    ApiOptions options_;
+    RateLimitPolicy policy_;
+    std::string token_;
+    std::atomic<bool> cancelled_{false};
+    std::mutex rl_mu_;
+    std::condition_variable rl_cv_;
+    Clock::time_point global_until_{};
+    std::map<std::string, Clock::time_point> route_until_;
+};
+
+struct BotProfile {
+    std::string user_id;           // 机器人用户 id(= Address::account)
+    std::string username;
+    std::string application_id;    // 用于生成邀请链接;GET /applications/@me 失败时为空
+    std::string application_name;
+    IntentState message_content = IntentState::Unknown;
+    std::string invite_url;        // 由 application_id 生成;为空表示拿不到
+};
+
+struct ValidationResult {
+    bool ok = false;
+    bool auth_failed = false;  // token 无效 / 被平台拒绝:换 token 之前不要重试
+    std::string error;         // 一句话中文原因,不含 token
+    BotProfile profile;
+};
+
+// 联网校验 token:GET /users/@me 确认身份,GET /applications/@me 取应用 id 与 intent 开关。
+// 后者失败不影响成功(intent 状态为 Unknown)。
+ValidationResult validate_credentials(const ApiOptions& options);
+
+} // namespace acecode::im::discord
diff --git a/src/adapters/im/discord/discord_gateway.cpp b/src/adapters/im/discord/discord_gateway.cpp
new file mode 100644
index 000000000..979870d85
--- /dev/null
+++ b/src/adapters/im/discord/discord_gateway.cpp
@@ -0,0 +1,248 @@
+#include "discord_gateway.hpp"
+
+#include <algorithm>
+
+namespace acecode::im::discord {
+namespace {
+
+const char* os_name() {
+#if defined(_WIN32)
+    return "windows";
+#elif defined(__APPLE__)
+    return "macos";
+#else
+    return "linux";
+#endif
+}
+
+std::string string_field(const nlohmann::json& value, const char* key) {
+    if (!value.is_object()) return {};
+    const auto it = value.find(key);
+    if (it == value.end()) return {};
+    if (it->is_string()) return it->get<std::string>();
+    if (it->is_number_unsigned()) return std::to_string(it->get<std::uint64_t>());
+    if (it->is_number_integer()) return std::to_string(it->get<std::int64_t>());
+    return {};
+}
+
+} // namespace
+
+CloseDecision classify_close(int code) {
+    switch (code) {
+        case 4003: return {CloseAction::Identify, "Discord 网关会话已失效,正在重新登录"};
+        case 4004: return {CloseAction::Fatal, "Bot Token 无效或已被重置,请在 Discord 开发者后台重新复制并保存"};
+        case 4007: return {CloseAction::Identify, "Discord 网关消息序号无效,正在重新登录"};
+        case 4008: return {CloseAction::RateLimited, "触发 Discord 网关频控,稍后自动重连"};
+        case 4009: return {CloseAction::Identify, "Discord 网关会话超时,正在重新登录"};
+        case 4010: return {CloseAction::Fatal, "Discord 网关拒绝了分片参数(ACECode 内部错误)"};
+        case 4011: return {CloseAction::Fatal, "机器人加入的服务器过多(超过 2500 个),需要分片连接,暂不支持"};
+        case 4012: return {CloseAction::Fatal, "Discord 网关不接受当前 API 版本(ACECode 内部错误)"};
+        case 4013: return {CloseAction::Fatal, "Discord 网关拒绝了 intents 参数(ACECode 内部错误)"};
+        case 4014: return {CloseAction::Fatal, "需要在 Discord 开发者后台开启 Message Content Intent"};
+        default: break;
+    }
+    // 4000/4001/4002/4005、1006(没有关闭帧)以及服务端发来的其它 1xxx:都按普通断线恢复;
+    // 恢复不了时服务端会回 op 9,届时再重新登录。
+    return {CloseAction::Resume, "与 Discord 的连接已断开,正在恢复"};
+}
+
+void GatewaySession::on_connected(std::string token, Clock::time_point now, double jitter) {
+    token_ = std::move(token);
+    connected_ = true;
+    hello_ = false;
+    awaiting_ack_ = false;
+    ready_ = false;
+    jitter_ = jitter < 0.0 ? 0.0 : (jitter >= 1.0 ? 0.999 : jitter);
+    hello_deadline_ = now + hello_timeout_;
+    next_beat_ = now + interval_;
+}
+
+std::string GatewaySession::heartbeat_frame() const {
+    nlohmann::json frame{{"op", 1}};
+    frame["d"] = seq_ ? nlohmann::json(*seq_) : nlohmann::json(nullptr);
+    return frame.dump();
+}
+
+std::string GatewaySession::identify_frame() const {
+    return nlohmann::json{{"op", 2},
+                          {"d",
+                           {{"token", token_},
+                            {"intents", intents_},
+                            {"properties", {{"os", os_name()}, {"browser", "acecode"}, {"device", "acecode"}}}}}}
+        .dump();
+}
+
+std::string GatewaySession::resume_frame() const {
+    nlohmann::json frame{{"op", 6}};
+    frame["d"] = {{"token", token_}, {"session_id", session_id_}};
+    frame["d"]["seq"] = seq_ ? nlohmann::json(*seq_) : nlohmann::json(nullptr);
+    return frame.dump();
+}
+
+GatewaySession::Output GatewaySession::on_frame(const std::string& text, Clock::time_point now) {
+    Output out;
+    nlohmann::json payload;
+    try {
+        payload = nlohmann::json::parse(text);
+    } catch (...) {
+        return out;  // 无效帧忽略,连接本身由心跳兜底
+    }
+    if (!payload.is_object()) return out;
+    const auto op_it = payload.find("op");
+    if (op_it == payload.end() || !op_it->is_number_integer()) return out;
+    const int op = op_it->get<int>();
+    const auto d_it = payload.find("d");
+    const nlohmann::json d = d_it == payload.end() ? nlohmann::json(nullptr) : *d_it;
+
+    switch (op) {
+        case 10: {  // Hello
+            hello_ = true;
+            long long ms = 41250;
+            if (d.is_object() && d.contains("heartbeat_interval") && d["heartbeat_interval"].is_number())
+                ms = d["heartbeat_interval"].get<long long>();
+            interval_ = std::chrono::milliseconds((std::max)(1LL, ms));
+            next_beat_ = now + std::chrono::milliseconds(static_cast<long long>(static_cast<double>(interval_.count()) * jitter_));
+            awaiting_ack_ = false;
+            if (can_resume()) {
+                out.frames.push_back(resume_frame());
+            } else {
+                out.frames.push_back(identify_frame());
+                out.identified = true;
+            }
+            break;
+        }
+        case 0: {  // Dispatch
+            const auto s = payload.find("s");
+            if (s != payload.end() && s->is_number_integer()) seq_ = s->get<std::int64_t>();
+            const auto type = payload.contains("t") && payload["t"].is_string() ? payload["t"].get<std::string>()
+                                                                                : std::string{};
+            if (type == "READY") {
+                ReadyInfo info;
+                if (d.is_object()) {
+                    session_id_ = string_field(d, "session_id");
+                    resume_url_ = string_field(d, "resume_gateway_url");
+                    if (d.contains("user") && d["user"].is_object()) {
+                        info.bot_id = string_field(d["user"], "id");
+                        info.bot_name = string_field(d["user"], "username");
+                    }
+                    if (d.contains("application") && d["application"].is_object()) {
+                        const auto& app = d["application"];
+                        info.application_id = string_field(app, "id");
+                        if (app.contains("flags") && app["flags"].is_number_integer())
+                            info.application_flags = app["flags"].get<std::int64_t>();
+                    }
+                    if (d.contains("guilds") && d["guilds"].is_array()) info.guild_count = d["guilds"].size();
+                }
+                ready_ = true;
+                out.ready = true;
+                out.ready_info = std::move(info);
+            } else if (type == "RESUMED") {
+                ready_ = true;
+                out.ready = true;
+                out.resumed = true;
+            } else if (!type.empty()) {
+                out.dispatches.emplace_back(type, d);
+            }
+            break;
+        }
+        case 11:  // Heartbeat ACK
+            awaiting_ack_ = false;
+            break;
+        case 1:  // 服务端要求立即心跳;常规节奏不变
+            out.frames.push_back(heartbeat_frame());
+            break;
+        case 7:  // 服务端要求重连,会话可以恢复(可能在 Hello 之前到达)
+            out.reconnect = true;
+            break;
+        case 9:  // 会话失效;d=true 时仍可恢复
+            if (!(d.is_boolean() && d.get<bool>())) {
+                clear_session();
+                out.invalid_session = true;
+            }
+            out.reconnect = true;
+            break;
+        default:
+            break;
+    }
+    return out;
+}
+
+GatewaySession::Tick GatewaySession::on_tick(Clock::time_point now) {
+    Tick tick;
+    if (!connected_) return tick;
+    if (!hello_) {
+        tick.hello_timeout = now >= hello_deadline_;
+        return tick;
+    }
+    if (now < next_beat_) return tick;
+    if (awaiting_ack_) {
+        tick.zombie = true;
+        return tick;
+    }
+    tick.heartbeat = heartbeat_frame();
+    awaiting_ack_ = true;
+    next_beat_ = now + interval_;
+    return tick;
+}
+
+CloseDecision GatewaySession::on_closed(int code) {
+    connected_ = false;
+    hello_ = false;
+    ready_ = false;
+    awaiting_ack_ = false;
+    const auto decision = classify_close(code);
+    if (decision.action == CloseAction::Identify || decision.action == CloseAction::Fatal) clear_session();
+    return decision;
+}
+
+void GatewaySession::clear_session() {
+    session_id_.clear();
+    resume_url_.clear();
+    seq_.reset();
+}
+
+IdentifyBudget::IdentifyBudget(Limits limits, std::int64_t window_start_ms, std::int64_t count)
+    : limits_(limits), window_start_((std::max)(std::int64_t{0}, window_start_ms)),
+      count_((std::max)(std::int64_t{0}, count)) {}
+
+bool IdentifyBudget::window_active(std::int64_t now_ms) const {
+    return window_start_ > 0 && now_ms >= window_start_ && now_ms - window_start_ < limits_.window.count();
+}
+
+bool IdentifyBudget::daily_cap_reached(std::int64_t now_ms) const {
+    return window_active(now_ms) && count_ >= limits_.daily_cap;
+}
+
+std::int64_t IdentifyBudget::next_allowed_ms(std::int64_t now_ms) const {
+    std::int64_t at = now_ms;
+    if (last_identify_) {
+        at = (std::max)(at, *last_identify_ + static_cast<std::int64_t>(limits_.min_interval.count()));
+        if (failures_ > 0) {
+            // 5s → 10s → 20s …;指数封顶在 2^20,避免溢出。
+            const int shift = (std::min)(failures_ - 1, 20);
+            const auto backoff = (std::min)(static_cast<std::int64_t>(limits_.min_interval.count()) << shift,
+                                            static_cast<std::int64_t>(limits_.max_backoff.count()));
+            at = (std::max)(at, *last_identify_ + backoff);
+        }
+    }
+    at = (std::max)(at, blocked_until_);
+    if (daily_cap_reached(now_ms)) at = (std::max)(at, window_start_ + static_cast<std::int64_t>(limits_.window.count()));
+    return at;
+}
+
+void IdentifyBudget::record_identify(std::int64_t now_ms) {
+    if (!window_active(now_ms)) {
+        window_start_ = now_ms;
+        count_ = 0;
+    }
+    ++count_;
+    last_identify_ = now_ms;
+}
+
+void IdentifyBudget::record_ready() { failures_ = 0; }
+
+void IdentifyBudget::record_failure() { ++failures_; }
+
+void IdentifyBudget::block_until(std::int64_t until_ms) { blocked_until_ = (std::max)(blocked_until_, until_ms); }
+
+} // namespace acecode::im::discord
diff --git a/src/adapters/im/discord/discord_gateway.hpp b/src/adapters/im/discord/discord_gateway.hpp
new file mode 100644
index 000000000..7307494a7
--- /dev/null
+++ b/src/adapters/im/discord/discord_gateway.hpp
@@ -0,0 +1,154 @@
+#pragma once
+
+// Discord 网关会话状态机与登录(Identify)预算,纯逻辑,不做 IO。
+//
+// 协议:连接 → Hello(op 10)→ Identify(op 2)或 Resume(op 6)→ Dispatch(op 0:READY / RESUMED / 事件)。
+// 心跳:首次在 interval × jitter(jitter ∈ [0,1))后发送,之后每 interval 一次;下一次到期时上一拍
+// 还没收到 ACK(op 11)即判定连接假死,应以非 1000 关闭码断开并恢复会话。服务端发 op 1 时立即补一拍。
+// op 7:断开并恢复;op 9:d=true 可恢复,d=false 会话作废,等 1–5 秒后重新 Identify。
+//
+// 登录预算:Discord 每个机器人 24 小时最多 1000 次 Identify(Resume 不算),超出后会重置机器人
+// token。所以能 Resume 就 Resume,Identify 之间至少间隔 5 秒,连续失败指数退避(5s→10s→20s…
+// 封顶 5 分钟),24 小时内超过 900 次就暂停到窗口结束。
+
+#include "im/discord/discord_protocol.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace acecode::im::discord {
+
+enum class CloseAction {
+    Resume,       // 普通断线:带 session_id + seq 恢复
+    Identify,     // 会话已失效:重新登录
+    RateLimited,  // 网关频控(4008):至少等 60 秒再恢复
+    Fatal,        // token 无效、intent 未开等:停止重连,等用户处理
+};
+
+struct CloseDecision {
+    CloseAction action = CloseAction::Resume;
+    std::string reason;  // 给用户看的中文原因
+};
+
+CloseDecision classify_close(int code);
+
+struct ReadyInfo {
+    std::string bot_id;
+    std::string bot_name;
+    std::string application_id;
+    std::optional<std::int64_t> application_flags;
+    std::size_t guild_count = 0;
+};
+
+class GatewaySession {
+public:
+    using Clock = std::chrono::steady_clock;
+
+    struct Output {
+        std::vector<std::string> frames;  // 要发送的 JSON 文本帧
+        std::vector<std::pair<std::string, nlohmann::json>> dispatches;  // (事件类型, d),不含 READY/RESUMED
+        bool ready = false;            // 本帧让连接可用(READY 或 RESUMED)
+        bool resumed = false;          // 是 RESUMED
+        bool identified = false;       // 本帧发出了 Identify(调用方要记入登录预算)
+        bool reconnect = false;        // 需要断开重连(op 7 / op 9)
+        bool invalid_session = false;  // op 9 d=false:会话作废,以 1000 关闭,随机等 1–5 秒后重新 Identify
+        std::optional<ReadyInfo> ready_info;
+    };
+
+    struct Tick {
+        std::optional<std::string> heartbeat;  // 到期要发的心跳帧
+        bool zombie = false;         // 上一拍没等到 ACK:连接假死
+        bool hello_timeout = false;  // 连上后迟迟没收到 Hello
+    };
+
+    explicit GatewaySession(int intents = kIntents) : intents_(intents) {}
+
+    // WebSocket 握手成功后调用。token 为原始 bot token(不带 "Bot " 前缀);jitter ∈ [0,1)
+    // 决定首拍心跳的时刻。
+    void on_connected(std::string token, Clock::time_point now, double jitter);
+    Output on_frame(const std::string& text, Clock::time_point now);
+    Tick on_tick(Clock::time_point now);
+    // 连接关闭后调用,按关闭码决定下一次是恢复、重新登录还是停止。
+    CloseDecision on_closed(int code);
+    void clear_session();
+
+    void set_hello_timeout(std::chrono::milliseconds timeout) { hello_timeout_ = timeout; }
+
+    bool can_resume() const { return !session_id_.empty() && seq_.has_value(); }
+    const std::string& session_id() const { return session_id_; }
+    // READY 给出的恢复地址(基址,不含查询串);可能为空。
+    const std::string& resume_url() const { return resume_url_; }
+    std::optional<std::int64_t> last_seq() const { return seq_; }
+    std::chrono::milliseconds heartbeat_interval() const { return interval_; }
+    bool ready() const { return ready_; }
+    bool hello_received() const { return hello_; }
+
+    std::string identify_frame() const;
+    std::string resume_frame() const;
+    std::string heartbeat_frame() const;
+
+private:
+    int intents_;
+    std::string token_;
+    std::string session_id_;
+    std::string resume_url_;
+    std::optional<std::int64_t> seq_;
+    std::chrono::milliseconds interval_{std::chrono::seconds(41)};
+    std::chrono::milliseconds hello_timeout_{std::chrono::seconds(20)};
+    double jitter_ = 0.0;
+    Clock::time_point next_beat_{};
+    Clock::time_point hello_deadline_{};
+    bool connected_ = false;
+    bool hello_ = false;
+    bool awaiting_ack_ = false;
+    bool ready_ = false;
+};
+
+// 登录预算(纯逻辑)。时间一律用 Unix 毫秒,便于持久化 24 小时计数。
+class IdentifyBudget {
+public:
+    struct Limits {
+        std::chrono::milliseconds min_interval{std::chrono::seconds(5)};
+        std::chrono::milliseconds max_backoff{std::chrono::minutes(5)};
+        std::int64_t daily_cap = 900;  // Discord 硬上限 1000,留 100 次余量
+        std::chrono::milliseconds window{std::chrono::hours(24)};
+    };
+
+    IdentifyBudget() = default;
+    // window_start_ms / count 来自持久化(0 表示还没有记录)。
+    IdentifyBudget(Limits limits, std::int64_t window_start_ms, std::int64_t count);
+
+    // 最早允许 Identify 的时刻;<= now_ms 表示现在就可以。
+    std::int64_t next_allowed_ms(std::int64_t now_ms) const;
+    // 当前 24 小时窗口内已达上限。
+    bool daily_cap_reached(std::int64_t now_ms) const;
+    void record_identify(std::int64_t now_ms);
+    // Identify 之后收到 READY:清零连续失败计数。
+    void record_ready();
+    // Identify 之后没等到 READY 就断开 / op 9:连续失败计数 +1,下一次按指数退避。
+    void record_failure();
+    // GET /gateway/bot 的 session_start_limit.remaining == 0:在 until_ms 之前不登录。
+    void block_until(std::int64_t until_ms);
+
+    std::int64_t window_start_ms() const { return window_start_; }
+    std::int64_t count() const { return count_; }
+    int failures() const { return failures_; }
+
+private:
+    bool window_active(std::int64_t now_ms) const;
+
+    Limits limits_;
+    std::int64_t window_start_ = 0;
+    std::int64_t count_ = 0;
+    std::optional<std::int64_t> last_identify_;
+    int failures_ = 0;
+    std::int64_t blocked_until_ = 0;
+};
+
+} // namespace acecode::im::discord
diff --git a/src/adapters/im/discord/discord_protocol.cpp b/src/adapters/im/discord/discord_protocol.cpp
new file mode 100644
index 000000000..32aa0750b
--- /dev/null
+++ b/src/adapters/im/discord/discord_protocol.cpp
@@ -0,0 +1,518 @@
+#include "discord_protocol.hpp"
+
+#include "version.hpp"
+
+#include <algorithm>
+#include <cctype>
+#include <functional>
+#include <sstream>
+
+namespace acecode::im::discord {
+namespace {
+
+std::string trim(const std::string& text) {
+    std::size_t b = 0, e = text.size();
+    while (b < e && std::isspace(static_cast<unsigned char>(text[b]))) ++b;
+    while (e > b && std::isspace(static_cast<unsigned char>(text[e - 1]))) --e;
+    return text.substr(b, e - b);
+}
+
+std::string lower(std::string text) {
+    std::transform(text.begin(), text.end(), text.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return text;
+}
+
+bool starts_with(const std::string& text, const std::string& prefix) {
+    return text.size() >= prefix.size() && text.compare(0, prefix.size(), prefix) == 0;
+}
+
+// 雪花 id 在线上一律是字符串;测试或旧数据里偶尔是数字,一并接受。
+std::string string_field(const nlohmann::json& value, const char* key) {
+    if (!value.is_object()) return {};
+    const auto it = value.find(key);
+    if (it == value.end()) return {};
+    if (it->is_string()) return it->get<std::string>();
+    if (it->is_number_unsigned()) return std::to_string(it->get<std::uint64_t>());
+    if (it->is_number_integer()) return std::to_string(it->get<std::int64_t>());
+    return {};
+}
+
+std::int64_t int_field(const nlohmann::json& value, const char* key, std::int64_t fallback) {
+    if (!value.is_object()) return fallback;
+    const auto it = value.find(key);
+    if (it == value.end() || !it->is_number()) return fallback;
+    if (it->is_number_float()) return static_cast<std::int64_t>(it->get<double>());
+    return it->get<std::int64_t>();
+}
+
+bool bool_field(const nlohmann::json& value, const char* key) {
+    if (!value.is_object()) return false;
+    const auto it = value.find(key);
+    return it != value.end() && it->is_boolean() && it->get<bool>();
+}
+
+const nlohmann::json& object_field(const nlohmann::json& value, const char* key) {
+    static const nlohmann::json kNull;
+    if (!value.is_object()) return kNull;
+    const auto it = value.find(key);
+    return it == value.end() ? kNull : *it;
+}
+
+bool is_snowflake(const std::string& id) {
+    if (id.empty() || id.size() > 24) return false;
+    return std::all_of(id.begin(), id.end(), [](char c) { return c >= '0' && c <= '9'; });
+}
+
+// 展示名:服务器昵称 > 全局显示名 > 用户名。
+std::string display_name(const nlohmann::json& user, const nlohmann::json& member) {
+    auto nick = string_field(member, "nick");
+    if (!nick.empty()) return nick;
+    const auto& inner_member = object_field(user, "member");
+    nick = string_field(inner_member, "nick");
+    if (!nick.empty()) return nick;
+    auto global = string_field(user, "global_name");
+    if (!global.empty()) return global;
+    return string_field(user, "username");
+}
+
+struct MentionToken {
+    std::size_t begin = 0;
+    std::size_t end = 0;  // 不含
+    bool role = false;
+    std::string id;
+};
+
+// 扫描 <@id>、<@!id>(已废弃但仍会出现)与 <@&id>。
+std::vector<MentionToken> mention_tokens(const std::string& text) {
+    std::vector<MentionToken> out;
+    std::size_t i = 0;
+    while (i + 2 < text.size()) {
+        if (text[i] != '<' || text[i + 1] != '@') {
+            ++i;
+            continue;
+        }
+        std::size_t j = i + 2;
+        bool role = false;
+        if (text[j] == '!') ++j;
+        else if (text[j] == '&') {
+            role = true;
+            ++j;
+        }
+        const auto digits = j;
+        while (j < text.size() && text[j] >= '0' && text[j] <= '9') ++j;
+        if (j > digits && j < text.size() && text[j] == '>') {
+            out.push_back({i, j + 1, role, text.substr(digits, j - digits)});
+            i = j + 1;
+            continue;
+        }
+        ++i;
+    }
+    return out;
+}
+
+std::string mentioned_user_name(const nlohmann::json& mentions, const std::string& id) {
+    if (!mentions.is_array()) return {};
+    for (const auto& user : mentions) {
+        if (string_field(user, "id") == id) return display_name(user, nlohmann::json());
+    }
+    return {};
+}
+
+std::string mime_of(const std::string& content_type) {
+    auto mime = content_type;
+    const auto semi = mime.find(';');
+    if (semi != std::string::npos) mime.resize(semi);
+    return lower(trim(mime));
+}
+
+Attachment parse_attachment(const nlohmann::json& raw, bool voice_message) {
+    Attachment attachment;
+    attachment.name = string_field(raw, "filename");
+    attachment.mime_type = mime_of(string_field(raw, "content_type"));
+    attachment.remote_ref = string_field(raw, "url");
+    const auto size = int_field(raw, "size", 0);
+    if (size > 0) attachment.size = static_cast<std::uint64_t>(size);
+    const auto& mime = attachment.mime_type;
+    if (voice_message) attachment.kind = AttachmentKind::Voice;
+    else if (starts_with(mime, "image/")) attachment.kind = AttachmentKind::Image;
+    else if (starts_with(mime, "video/")) attachment.kind = AttachmentKind::Video;
+    else attachment.kind = AttachmentKind::File;
+    return attachment;
+}
+
+void append_attachments(const nlohmann::json& message, std::vector<Attachment>& out) {
+    const auto& list = object_field(message, "attachments");
+    if (!list.is_array()) return;
+    const bool voice = (int_field(message, "flags", 0) & kMessageFlagVoice) != 0;
+    for (const auto& raw : list) {
+        if (!raw.is_object()) continue;
+        auto attachment = parse_attachment(raw, voice);
+        if (!attachment.remote_ref.empty()) out.push_back(std::move(attachment));
+    }
+}
+
+void flatten_errors(const nlohmann::json& node, const std::string& path, std::vector<std::string>& out) {
+    if (!node.is_object()) return;
+    const auto errors = node.find("_errors");
+    if (errors != node.end() && errors->is_array()) {
+        for (const auto& item : *errors) {
+            const auto message = string_field(item, "message");
+            const auto code = string_field(item, "code");
+            std::string line = path.empty() ? std::string{} : path + ": ";
+            line += message.empty() ? code : message;
+            if (!message.empty() && !code.empty()) line += " (" + code + ")";
+            out.push_back(line);
+        }
+    }
+    for (auto it = node.begin(); it != node.end(); ++it) {
+        if (it.key() == "_errors") continue;
+        flatten_errors(it.value(), path.empty() ? it.key() : path + "." + it.key(), out);
+    }
+}
+
+bool contains_ci(const std::string& text, const std::string& needle) {
+    return lower(text).find(lower(needle)) != std::string::npos;
+}
+
+bool is_fence(const std::string& line) {
+    const auto t = trim(line);
+    return starts_with(t, "```") || starts_with(t, "~~~");
+}
+
+bool is_table_delimiter(const std::string& line) {
+    const auto t = trim(line);
+    if (t.empty() || t.find('-') == std::string::npos) return false;
+    if (t.find('|') == std::string::npos) return false;
+    return std::all_of(t.begin(), t.end(), [](char c) { return c == '|' || c == '-' || c == ':' || c == ' ' || c == '\t'; });
+}
+
+bool is_table_row(const std::string& line) {
+    const auto t = trim(line);
+    return !t.empty() && t.find('|') != std::string::npos;
+}
+
+} // namespace
+
+std::string discord_user_agent() {
+    return std::string("DiscordBot (") + kProjectUrl + ", " + ACECODE_VERSION + ")";
+}
+
+std::string invite_url(const std::string& application_id) {
+    if (!is_snowflake(application_id)) return {};
+    return "https://discord.com/oauth2/authorize?client_id=" + application_id +
+           "&scope=bot&permissions=" + std::to_string(kInvitePermissions) + "&integration_type=0";
+}
+
+std::string gateway_connect_url(const std::string& base) {
+    auto url = base;
+    const auto query = url.find('?');
+    if (query != std::string::npos) url.resize(query);
+    while (!url.empty() && url.back() == '/') url.pop_back();
+    if (url.empty()) return {};
+    return url + "/?v=10&encoding=json";
+}
+
+IntentState message_content_intent(const nlohmann::json& application) {
+    const auto& flags = object_field(application, "flags");
+    if (!flags.is_number_integer()) return IntentState::Unknown;
+    const auto value = flags.get<std::int64_t>();
+    return (value & (kAppFlagMessageContent | kAppFlagMessageContentLimited)) != 0 ? IntentState::Enabled
+                                                                                  : IntentState::Disabled;
+}
+
+ApiError parse_api_error(long status, const std::string& body) {
+    ApiError error;
+    error.status = status;
+    try {
+        const auto json = nlohmann::json::parse(body);
+        if (json.is_object()) {
+            error.code = static_cast<long>(int_field(json, "code", 0));
+            error.message = string_field(json, "message");
+            const auto& retry = object_field(json, "retry_after");
+            if (retry.is_number()) error.retry_after = (std::max)(0.0, retry.get<double>());
+            error.global = bool_field(json, "global");
+            std::vector<std::string> lines;
+            flatten_errors(object_field(json, "errors"), {}, lines);
+            for (const auto& line : lines) {
+                if (!error.detail.empty()) error.detail += "; ";
+                error.detail += line;
+            }
+        }
+    } catch (...) {
+    }
+    if (error.message.empty()) error.message = "HTTP " + std::to_string(status);
+    return error;
+}
+
+bool reference_rejected(const ApiError& error) {
+    if (error.code == 10008 || error.code == 160002) return true;
+    if (error.code != 50035) return false;
+    const auto text = error.message + " " + error.detail;
+    return contains_ci(text, "system message") || contains_ci(text, "message_reference") ||
+           contains_ci(text, "reply");
+}
+
+bool upload_too_large(const ApiError& error) { return error.status == 413 || error.code == 40005; }
+
+std::string describe_error(const ApiError& error) {
+    if (error.status == 0) {
+        return error.message.empty() || starts_with(error.message, "HTTP ") ? "无法连接 Discord"
+                                                                             : "无法连接 Discord:" + error.message;
+    }
+    if (error.status == 401 || error.code == 40001) return "Bot Token 无效或已被重置";
+    switch (error.code) {
+        case 10003: return "频道不存在,或机器人已无法访问该频道";
+        case 10008: return "要回复的消息已不存在";
+        case 10013: return "Discord 用户不存在";
+        case 20016:
+        case 20028: return "Discord 限流,请稍后再试";
+        case 40005: return "文件超过 Discord 上传上限";
+        case 40058: return "不能直接在论坛频道发消息,请在帖子里 @机器人";
+        case 50001: return "机器人无权访问该频道";
+        case 50006: return "不能发送空消息";
+        case 50007: return "无法私信该用户(对方关闭了私信,或与机器人没有共同的服务器)";
+        case 50008: return "不能在该类型的频道发消息";
+        case 50013: return "机器人缺少权限(需要发送消息、在子区发送消息、附加文件、读取消息历史)";
+        case 160005: return "子区已锁定,机器人无法发言";
+        case 50035: return "Discord 拒绝了消息内容:" + (error.detail.empty() ? error.message : error.detail);
+        default: break;
+    }
+    if (error.status == 413) return "文件超过 Discord 上传上限";
+    if (error.status == 429) return "Discord 限流,请稍后再试";
+    if (error.status == 403) return "请求被 Discord 拒绝(HTTP 403)";
+    if (error.status >= 500) return "Discord 服务暂时不可用(HTTP " + std::to_string(error.status) + ")";
+    return "Discord 请求失败:" + error.message;
+}
+
+std::string render_content(const std::string& content, const std::string& bot_id,
+                           const std::set<std::string>& bot_role_ids, const nlohmann::json& mentions,
+                           bool* mentioned) {
+    bool hit = false;
+    std::string out;
+    out.reserve(content.size());
+    std::size_t pos = 0;
+    for (const auto& token : mention_tokens(content)) {
+        out.append(content, pos, token.begin - pos);
+        pos = token.end;
+        const bool self = token.role ? bot_role_ids.count(token.id) > 0 : (!bot_id.empty() && token.id == bot_id);
+        if (self) {
+            hit = true;
+            // 去掉提及后不留双空格:"看看 <@BOT> 这个" → "看看 这个"。
+            if (!out.empty() && out.back() == ' ' && pos < content.size() && content[pos] == ' ') ++pos;
+            continue;
+        }
+        const auto name = token.role ? std::string{} : mentioned_user_name(mentions, token.id);
+        if (!name.empty()) out += "@" + name;
+        else out.append(content, token.begin, token.end - token.begin);
+    }
+    out.append(content, pos, std::string::npos);
+    if (mentioned) *mentioned = hit;
+    return trim(out);
+}
+
+ParsedMessage parse_message_create(const nlohmann::json& d, const std::string& bot_id,
+                                   const std::set<std::string>& bot_role_ids) {
+    ParsedMessage parsed;
+    if (!d.is_object()) {
+        parsed.drop_reason = "malformed payload";
+        return parsed;
+    }
+    const auto message_id = string_field(d, "id");
+    const auto channel_id = string_field(d, "channel_id");
+    const auto& author = object_field(d, "author");
+    const auto author_id = string_field(author, "id");
+    if (!is_snowflake(message_id) || !is_snowflake(channel_id) || !is_snowflake(author_id)) {
+        parsed.drop_reason = "missing message, channel or author id";
+        return parsed;
+    }
+    if (!bot_id.empty() && author_id == bot_id) {
+        parsed.drop_reason = "own message";
+        return parsed;
+    }
+    if (bool_field(author, "bot") || bool_field(author, "system") || !string_field(d, "webhook_id").empty()) {
+        parsed.drop_reason = "message from a bot, webhook or system account";
+        return parsed;
+    }
+    // 只接普通消息(0)与回复(19);置顶、加入、子区创建、子区首条(21)等系统类型一律忽略。
+    const auto type = int_field(d, "type", 0);
+    if (type != 0 && type != 19) {
+        parsed.drop_reason = "message type " + std::to_string(type) + " is not a user message";
+        return parsed;
+    }
+    const auto guild_id = string_field(d, "guild_id");
+    const auto channel_type = int_field(d, "channel_type", -1);
+    if (channel_type == 3) {
+        parsed.drop_reason = "group DM";
+        return parsed;
+    }
+    // channel_type 可能缺失(旧载荷):没有 guild_id 就是私聊。
+    const bool dm = channel_type == 1 || guild_id.empty();
+
+    Inbound inbound;
+    inbound.message_id = message_id;
+    inbound.address.platform = kPlatform;
+    inbound.address.account = bot_id;
+    inbound.address.sender = author_id;
+    inbound.address.kind = dm ? ChatKind::Private : ChatKind::Group;
+    inbound.address.chat = dm ? author_id : channel_id;
+
+    const auto& mentions = object_field(d, "mentions");
+    bool inline_mention = false;
+    auto content = string_field(d, "content");
+    // 转发的消息:外层正文为空时用快照里的正文,附件也一起带上。
+    std::vector<Attachment> attachments;
+    append_attachments(d, attachments);
+    const auto& snapshots = object_field(d, "message_snapshots");
+    if (snapshots.is_array()) {
+        for (const auto& snapshot : snapshots) {
+            const auto& inner = object_field(snapshot, "message");
+            if (!inner.is_object()) continue;
+            if (trim(content).empty()) content = string_field(inner, "content");
+            append_attachments(inner, attachments);
+        }
+    }
+    inbound.text = render_content(content, bot_id, bot_role_ids, mentions, &inline_mention);
+
+    bool mentioned = inline_mention;
+    if (!bot_id.empty() && mentions.is_array()) {
+        for (const auto& user : mentions) mentioned = mentioned || string_field(user, "id") == bot_id;
+    }
+    const auto& mention_roles = object_field(d, "mention_roles");
+    if (mention_roles.is_array()) {
+        for (const auto& role : mention_roles) {
+            if (role.is_string() && bot_role_ids.count(role.get<std::string>())) mentioned = true;
+        }
+    }
+    // 回复机器人的消息也算点名(用户关掉回复里的 @ 时 mentions 里没有机器人,要看被回复消息的作者)。
+    const auto& referenced = object_field(d, "referenced_message");
+    if (referenced.is_object()) {
+        const auto& ref_author = object_field(referenced, "author");
+        if (!bot_id.empty() && string_field(ref_author, "id") == bot_id) mentioned = true;
+        inbound.quote_text = render_content(string_field(referenced, "content"), bot_id, bot_role_ids,
+                                            object_field(referenced, "mentions"));
+        append_attachments(referenced, attachments);
+    }
+    inbound.mentioned = dm ? true : mentioned;
+    inbound.attachments = std::move(attachments);
+    if (inbound.text.empty() && inbound.attachments.empty()) {
+        parsed.drop_reason = inline_mention ? "bare mention without text" : "empty message";
+        return parsed;
+    }
+    inbound.sender_name = display_name(author, object_field(d, "member"));
+    inbound.reply_context = {{"message_id", message_id}, {"channel_id", channel_id}};
+    if (!guild_id.empty()) inbound.reply_context["guild_id"] = guild_id;
+    if (dm) {
+        parsed.dm_user = author_id;
+        parsed.dm_channel = channel_id;
+    }
+    parsed.inbound = std::move(inbound);
+    return parsed;
+}
+
+std::vector<std::string> bot_role_ids_in_guild(const nlohmann::json& guild, const std::string& bot_id) {
+    std::vector<std::string> out;
+    if (bot_id.empty()) return out;
+    const auto& roles = object_field(guild, "roles");
+    if (!roles.is_array()) return out;
+    for (const auto& role : roles) {
+        const auto& tags = object_field(role, "tags");
+        if (string_field(tags, "bot_id") == bot_id) {
+            const auto id = string_field(role, "id");
+            if (is_snowflake(id)) out.push_back(id);
+        }
+    }
+    return out;
+}
+
+std::string format_markdown(const std::string& markdown) {
+    std::vector<std::string> lines;
+    {
+        std::size_t start = 0;
+        while (true) {
+            const auto nl = markdown.find('\n', start);
+            if (nl == std::string::npos) {
+                lines.push_back(markdown.substr(start));
+                break;
+            }
+            lines.push_back(markdown.substr(start, nl - start));
+            start = nl + 1;
+        }
+    }
+    std::vector<std::string> out;
+    out.reserve(lines.size());
+    bool in_fence = false;
+    for (std::size_t i = 0; i < lines.size(); ++i) {
+        const auto& line = lines[i];
+        if (is_fence(line)) {
+            in_fence = !in_fence;
+            out.push_back(line);
+            continue;
+        }
+        if (in_fence) {
+            out.push_back(line);
+            continue;
+        }
+        // GFM 表格:表头行 + 分隔行(|---|:--:|),之后连续的含 '|' 行都属于表格。
+        if (is_table_row(line) && i + 1 < lines.size() && is_table_delimiter(lines[i + 1])) {
+            out.push_back("```");
+            std::size_t j = i;
+            while (j < lines.size() && is_table_row(lines[j]) && !is_fence(lines[j])) {
+                out.push_back(lines[j]);
+                ++j;
+            }
+            out.push_back("```");
+            i = j - 1;
+            continue;
+        }
+        // Discord 只渲染 #、##、### 三级标题,更深的标题会显示成带井号的原文。
+        const auto t = trim(line);
+        if (starts_with(t, "####")) {
+            std::size_t hashes = 0;
+            while (hashes < t.size() && t[hashes] == '#') ++hashes;
+            if (hashes <= 6 && hashes < t.size() && (t[hashes] == ' ' || t[hashes] == '\t')) {
+                const auto text = trim(t.substr(hashes));
+                out.push_back(text.empty() ? std::string{} : "**" + text + "**");
+                continue;
+            }
+        }
+        out.push_back(line);
+    }
+    std::string result;
+    for (std::size_t i = 0; i < out.size(); ++i) {
+        if (i) result.push_back('\n');
+        result += out[i];
+    }
+    return result;
+}
+
+std::string url_host(const std::string& url) {
+    const auto scheme = url.find("://");
+    if (scheme == std::string::npos) return {};
+    auto rest = url.substr(scheme + 3);
+    const auto end = rest.find_first_of("/?#");
+    if (end != std::string::npos) rest.resize(end);
+    const auto at = rest.rfind('@');
+    if (at != std::string::npos) rest = rest.substr(at + 1);
+    if (!rest.empty() && rest.front() == '[') {
+        const auto close = rest.find(']');
+        return close == std::string::npos ? std::string{} : lower(rest.substr(1, close - 1));
+    }
+    const auto colon = rest.find(':');
+    if (colon != std::string::npos) rest.resize(colon);
+    return lower(rest);
+}
+
+std::string attachment_id_from_url(const std::string& url) {
+    static const std::string kMarker = "/attachments/";
+    const auto pos = url.find(kMarker);
+    if (pos == std::string::npos) return {};
+    const auto channel_end = url.find('/', pos + kMarker.size());
+    if (channel_end == std::string::npos) return {};
+    const auto id_end = url.find('/', channel_end + 1);
+    if (id_end == std::string::npos) return {};
+    const auto id = url.substr(channel_end + 1, id_end - channel_end - 1);
+    return is_snowflake(id) ? id : std::string{};
+}
+
+} // namespace acecode::im::discord
diff --git a/src/adapters/im/discord/discord_protocol.hpp b/src/adapters/im/discord/discord_protocol.hpp
new file mode 100644
index 000000000..aad4a0218
--- /dev/null
+++ b/src/adapters/im/discord/discord_protocol.hpp
@@ -0,0 +1,109 @@
+#pragma once
+
+// Discord 机器人协议常量与纯解析逻辑(不做 IO)。
+// 参照:Discord 官方文档(discord-api-docs,2026-09)与 hermes-agent 的 Discord 适配器。
+//
+// 地址约定(与核心一致):
+//   - account = 机器人用户 id(READY.user.id,同 GET /users/@me 的 id);
+//   - 私聊:kind=Private,chat = sender = 对方用户 id;私聊频道 id 只放在 reply_context;
+//   - 服务器频道:kind=Group,chat = 频道 id(在子区里就是子区自己的频道 id),sender = 发言人 id。
+
+#include "im/transport.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <cstdint>
+#include <optional>
+#include <set>
+#include <string>
+#include <vector>
+
+namespace acecode::im::discord {
+
+inline constexpr const char* kPlatform = "discord";
+inline constexpr const char* kApiBase = "https://discord.com/api/v10";
+inline constexpr const char* kPortalUrl = "https://discord.com/developers/applications";
+inline constexpr const char* kProjectUrl = "https://github.com/tmoonlight/acecode";
+
+// GUILDS(1) | GUILD_MESSAGES(1<<9) | DIRECT_MESSAGES(1<<12) | MESSAGE_CONTENT(1<<15)
+inline constexpr int kIntents = 37377;
+
+// 单条消息上限 2000 字符,官方没说按什么单位计;按 UTF-16 单位(不小于码点数)切到 1990 最稳妥。
+inline constexpr std::size_t kMaxTextUnits = 1990;
+
+// 邀请链接里的机器人权限:查看频道(1<<10) + 发送消息(1<<11) + 附加文件(1<<15)
+// + 读取消息历史(1<<16) + 在子区发送消息(1<<38)。
+inline constexpr std::uint64_t kInvitePermissions = 274878008320ULL;
+
+// GET /applications/@me 的 flags:已批准(>=100 个服务器)/ 开发者后台开关(<100 个服务器)。
+inline constexpr std::int64_t kAppFlagMessageContent = std::int64_t{1} << 18;
+inline constexpr std::int64_t kAppFlagMessageContentLimited = std::int64_t{1} << 19;
+
+// 消息 flags:语音消息。
+inline constexpr std::int64_t kMessageFlagVoice = std::int64_t{1} << 13;
+
+// "DiscordBot (https://github.com/tmoonlight/acecode, <版本>)"。没有合法 UA 时 Cloudflare 可能拦截请求。
+std::string discord_user_agent();
+
+// 机器人邀请链接(scope=bot,权限见 kInvitePermissions);application_id 为空时返回空串。
+std::string invite_url(const std::string& application_id);
+
+// 网关地址 → 实际连接地址:去掉末尾 '/' 与已有查询串,再拼 "/?v=10&encoding=json"(不压缩)。
+std::string gateway_connect_url(const std::string& base);
+
+enum class IntentState { Unknown, Enabled, Disabled };
+
+// 由应用对象的 flags 判断 Message Content Intent 是否已开启;没有 flags 时为 Unknown。
+IntentState message_content_intent(const nlohmann::json& application);
+
+struct ApiError {
+    long status = 0;          // HTTP 状态码;0 = 没拿到响应
+    long code = 0;            // Discord JSON 错误码(10008、50035…)
+    std::string message;      // 平台原文(英文)
+    std::string detail;       // errors 里逐字段的原因,形如 "message_reference: Unknown message"
+    double retry_after = 0;   // 429:需要等待的秒数(小数)
+    bool global = false;      // 429:是否全局限流
+};
+
+// 解析失败响应 {"code","message","errors","retry_after","global"};无法解析时用 HTTP 状态码兜底。
+ApiError parse_api_error(long status, const std::string& body);
+
+// 回复定位被拒(被回复的消息不存在、是系统消息、没有读取历史权限):去掉 message_reference 重发即可。
+bool reference_rejected(const ApiError& error);
+// 文件过大(413 / 40005):改发文字说明。
+bool upload_too_large(const ApiError& error);
+// 给用户看的一句话中文原因(不含凭据)。
+std::string describe_error(const ApiError& error);
+
+struct ParsedMessage {
+    std::optional<Inbound> inbound;
+    std::string drop_reason;  // inbound 为空时的原因(英文,只写日志)
+    std::string dm_user;      // 私聊:对方用户 id 与私聊频道 id,供发送时复用
+    std::string dm_channel;
+};
+
+// 解析网关 MESSAGE_CREATE 的 d。bot_id 为机器人用户 id;bot_role_ids 为机器人的托管角色
+// (有人 @ 了机器人的角色也算点名)。过滤:自己、其他机器人、webhook、系统消息、群组私聊、
+// 非普通/回复类型、去掉 @ 后既没文字也没附件。
+ParsedMessage parse_message_create(const nlohmann::json& d, const std::string& bot_id,
+                                   const std::set<std::string>& bot_role_ids);
+
+// GUILD_CREATE 里属于本机器人的托管角色 id(roles[].tags.bot_id == bot_id)。
+std::vector<std::string> bot_role_ids_in_guild(const nlohmann::json& guild, const std::string& bot_id);
+
+// 处理正文里的提及:去掉 @机器人(<@id>、<@!id>)与机器人托管角色(<@&id>),其他用户的提及
+// 按 mentions[] 换成 "@名称";首尾去空白。mentioned 非空时写入是否出现了对机器人的提及。
+std::string render_content(const std::string& content, const std::string& bot_id,
+                           const std::set<std::string>& bot_role_ids, const nlohmann::json& mentions,
+                           bool* mentioned = nullptr);
+
+// Discord 原生支持大部分 Markdown;不支持的两处在这里处理:GFM 表格整体包进代码块(等宽显示),
+// 四级及以下标题改成粗体。代码块里的内容原样保留。
+std::string format_markdown(const std::string& markdown);
+
+// URL 的主机名(小写,不含端口与用户信息);解析不出时返回空串。
+std::string url_host(const std::string& url);
+// CDN 附件地址 .../attachments/<频道>/<附件 id>/<文件名> 里的附件 id;不是附件地址时返回空串。
+std::string attachment_id_from_url(const std::string& url);
+
+} // namespace acecode::im::discord
diff --git a/src/adapters/im/discord/discord_transport.cpp b/src/adapters/im/discord/discord_transport.cpp
new file mode 100644
index 000000000..e5884e11a
--- /dev/null
+++ b/src/adapters/im/discord/discord_transport.cpp
@@ -0,0 +1,713 @@
+#include "discord_transport.hpp"
+
+#include "im/redact.hpp"
+#include "im/text_chunk.hpp"
+#include "utils/logger.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <algorithm>
+#include <cctype>
+
+namespace acecode::im::discord {
+namespace {
+
+constexpr std::size_t kSeenLimit = 2000;
+constexpr std::size_t kOriginLimit = 2000;
+constexpr std::size_t kDmCacheLimit = 4096;
+
+std::string string_field(const nlohmann::json& value, const char* key) {
+    if (!value.is_object()) return {};
+    const auto it = value.find(key);
+    if (it == value.end()) return {};
+    if (it->is_string()) return it->get<std::string>();
+    if (it->is_number_unsigned()) return std::to_string(it->get<std::uint64_t>());
+    if (it->is_number_integer()) return std::to_string(it->get<std::int64_t>());
+    return {};
+}
+
+std::int64_t int_field(const nlohmann::json& value, const char* key, std::int64_t fallback) {
+    if (!value.is_object()) return fallback;
+    const auto it = value.find(key);
+    if (it == value.end() || !it->is_number()) return fallback;
+    if (it->is_number_float()) return static_cast<std::int64_t>(it->get<double>());
+    return it->get<std::int64_t>();
+}
+
+std::string lower(std::string text) {
+    std::transform(text.begin(), text.end(), text.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return text;
+}
+
+const char* action_name(CloseAction action) {
+    switch (action) {
+        case CloseAction::Resume: return "resume";
+        case CloseAction::Identify: return "identify";
+        case CloseAction::RateLimited: return "rate limited";
+        case CloseAction::Fatal: return "fatal";
+    }
+    return "resume";
+}
+
+nlohmann::json allowed_mentions(bool replied_user) {
+    // 只允许提及具体用户:LLM 输出或回显的 @everyone / @here / 角色提及一律不会响铃。
+    return {{"parse", nlohmann::json::array({"users"})}, {"replied_user", replied_user}};
+}
+
+// 回复定位:第一段带 message_reference(fail_if_not_exists=false,被回复消息已删时退化成普通消息)。
+// reply_context 里的频道与目标频道不一致时不带(跨频道回复不合法)。
+std::optional<std::string> reply_reference(const nlohmann::json& reply_context, const std::string& channel) {
+    const auto message_id = string_field(reply_context, "message_id");
+    if (message_id.empty()) return std::nullopt;
+    const auto context_channel = string_field(reply_context, "channel_id");
+    if (!context_channel.empty() && context_channel != channel) return std::nullopt;
+    return message_id;
+}
+
+std::string find_attachment_url(const nlohmann::json& message, const std::string& attachment_id) {
+    if (!message.is_object()) return {};
+    const auto attachments = message.find("attachments");
+    if (attachments != message.end() && attachments->is_array()) {
+        for (const auto& item : *attachments) {
+            if (string_field(item, "id") == attachment_id) return string_field(item, "url");
+        }
+    }
+    const auto referenced = message.find("referenced_message");
+    if (referenced != message.end()) {
+        auto url = find_attachment_url(*referenced, attachment_id);
+        if (!url.empty()) return url;
+    }
+    const auto snapshots = message.find("message_snapshots");
+    if (snapshots != message.end() && snapshots->is_array()) {
+        for (const auto& snapshot : *snapshots) {
+            if (!snapshot.is_object() || !snapshot.contains("message")) continue;
+            auto url = find_attachment_url(snapshot["message"], attachment_id);
+            if (!url.empty()) return url;
+        }
+    }
+    return {};
+}
+
+} // namespace
+
+DiscordTransport::DiscordTransport(DiscordTransportOptions options)
+    : options_(std::move(options)),
+      api_(options_.api, options_.rate_limit),
+      budget_(options_.identify_limits, options_.identify_window_start_ms, options_.identify_count),
+      rng_(std::random_device{}()) {}
+
+DiscordTransport::~DiscordTransport() { stop(); }
+
+Capabilities DiscordTransport::capabilities() const {
+    Capabilities caps;
+    caps.max_text_units = kMaxTextUnits;
+    caps.count_utf16 = true;
+    caps.batch_turn_output = false;
+    caps.supports_typing = true;
+    caps.max_upload_bytes = options_.max_upload_bytes;
+    caps.max_download_bytes = options_.max_download_bytes;
+    return caps;
+}
+
+void DiscordTransport::start(TransportCallbacks callbacks) {
+    if (running_.exchange(true)) return;
+    callbacks_ = std::move(callbacks);
+    {
+        std::lock_guard<std::mutex> lock(wake_mu_);
+        stopping_ = false;
+    }
+    api_.reset();
+    gateway_ = acecode::JoiningThread(&DiscordTransport::run, this);
+    typer_ = acecode::JoiningThread(&DiscordTransport::typing_loop, this);
+}
+
+void DiscordTransport::stop() {
+    if (!running_.exchange(false)) return;
+    {
+        std::lock_guard<std::mutex> lock(wake_mu_);
+        stopping_ = true;
+    }
+    api_.cancel();
+    ws_.abort();
+    wake_.notify_all();
+    if (gateway_.joinable()) gateway_.join();
+    if (typer_.joinable()) typer_.join();
+    // 主动停机用 1000 关闭:会话立即作废,机器人马上显示离线;下次启动重新 Identify。
+    ws_.close(1000, "shutdown");
+    session_.clear_session();
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        typing_.clear();
+    }
+    set_status(LinkState::Stopped, {});
+}
+
+TransportStatus DiscordTransport::status() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return status_;
+}
+
+std::string DiscordTransport::bot_user_id() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return bot_id_;
+}
+
+void DiscordTransport::set_status(LinkState state, const std::string& detail, bool retry_stopped) {
+    TransportStatus snapshot;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        const auto clean = redact_secrets(detail, {options_.api.token, api_.token()});
+        if (status_.state == state && status_.detail == clean && status_.retry_stopped == retry_stopped) return;
+        status_.state = state;
+        status_.detail = clean;
+        status_.retry_stopped = retry_stopped;
+        snapshot = status_;
+    }
+    if (callbacks_.on_status) callbacks_.on_status(snapshot);
+}
+
+bool DiscordTransport::wait_for(std::chrono::milliseconds duration) {
+    std::unique_lock<std::mutex> lock(wake_mu_);
+    wake_.wait_for(lock, duration, [this] { return stopping_.load(); });
+    return !stopping_;
+}
+
+std::int64_t DiscordTransport::wall_ms() const {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(
+               std::chrono::system_clock::now().time_since_epoch())
+        .count();
+}
+
+double DiscordTransport::random_jitter() { return std::uniform_real_distribution<double>(0.0, 1.0)(rng_); }
+
+std::chrono::milliseconds DiscordTransport::random_between(std::chrono::milliseconds low,
+                                                           std::chrono::milliseconds high) {
+    if (high <= low) return low;
+    return std::chrono::milliseconds(
+        std::uniform_int_distribution<long long>(low.count(), high.count())(rng_));
+}
+
+void DiscordTransport::run() {
+    std::size_t attempt = 0;
+    int resume_connect_failures = 0;
+    set_status(LinkState::Connecting, "正在连接 Discord");
+    while (!stopping_) {
+        ConnectionEnd end;
+        const bool fresh = !session_.can_resume();
+        std::string url;
+        if (fresh) {
+            // 登录预算:最小间隔、连续失败退避、24 小时上限、session_start_limit。
+            const auto now = wall_ms();
+            const auto allowed = budget_.next_allowed_ms(now);
+            if (allowed > now) {
+                const auto wait = std::chrono::milliseconds(allowed - now);
+                if (budget_.daily_cap_reached(now)) {
+                    LOG_WARN("[channels/discord] " + std::to_string(budget_.count()) +
+                             " identifies in the current 24h window, pausing for " +
+                             std::to_string(wait.count() / 60000) + " min to protect the token");
+                    set_status(LinkState::Retrying, "Discord 24 小时内登录次数接近上限,暂停自动连接,约 " +
+                                                        std::to_string(wait.count() / 60000 + 1) + " 分钟后恢复");
+                } else {
+                    LOG_INFO("[channels/discord] waiting " + std::to_string(wait.count()) + " ms before identifying");
+                }
+                if (!wait_for(wait)) break;
+                continue;
+            }
+            const auto gateway = api_.gateway_bot();
+            if (gateway.cancelled || stopping_) break;
+            if (!gateway.ok) {
+                if (gateway.status == 401 || gateway.error.code == 40001) {
+                    LOG_WARN("[channels/discord] token rejected by GET /gateway/bot (HTTP 401), stopping");
+                    set_status(LinkState::Failed,
+                               "Bot Token 无效或已被重置,请在 Discord 开发者后台重新复制并保存", true);
+                    break;
+                }
+                LOG_WARN("[channels/discord] GET /gateway/bot failed: HTTP " + std::to_string(gateway.status) +
+                         " " + gateway.error.message);
+                set_status(LinkState::Retrying, "无法获取 Discord 网关地址:" + describe_error(gateway.error));
+            } else {
+                url = string_field(gateway.body, "url");
+                const auto limit = gateway.body.is_object() && gateway.body.contains("session_start_limit")
+                                       ? gateway.body["session_start_limit"]
+                                       : nlohmann::json::object();
+                const auto remaining = int_field(limit, "remaining", -1);
+                const auto reset_after = int_field(limit, "reset_after", 0);
+                if (remaining == 0 && reset_after > 0) {
+                    budget_.block_until(now + reset_after);
+                    LOG_WARN("[channels/discord] session start limit exhausted, next identify in " +
+                             std::to_string(reset_after / 1000) + " s");
+                    set_status(LinkState::Retrying, "Discord 登录次数已用完,约 " +
+                                                        std::to_string(reset_after / 60000 + 1) + " 分钟后自动连接");
+                    continue;
+                }
+                if (url.empty()) set_status(LinkState::Retrying, "Discord 返回的网关地址无效");
+                else gateway_url_ = url;
+            }
+        } else {
+            url = session_.resume_url().empty() ? gateway_url_ : session_.resume_url();
+            if (url.empty()) {
+                session_.clear_session();
+                continue;
+            }
+        }
+        if (!url.empty()) {
+            network::WebSocketConnectOptions ws_options;
+            ws_options.url = gateway_connect_url(url);
+            ws_options.headers = {{"User-Agent", discord_user_agent()}};
+            ws_options.max_message_bytes = options_.max_message_bytes;
+            ws_options.use_proxy = options_.api.use_proxy;
+            std::string error;
+            if (!ws_.connect(ws_options, &error)) {
+                if (stopping_) break;
+                error = redact_secrets(error, {options_.api.token, api_.token()});
+                LOG_WARN("[channels/discord] gateway connect failed: " + error);
+                set_status(LinkState::Retrying, "无法连接 Discord 网关:" + error);
+                if (!fresh && ++resume_connect_failures >= 3) {
+                    LOG_INFO("[channels/discord] resume connect failed 3 times, falling back to identify");
+                    session_.clear_session();
+                    resume_connect_failures = 0;
+                }
+            } else {
+                resume_connect_failures = 0;
+                LOG_INFO(std::string("[channels/discord] gateway connected, ") +
+                         (fresh ? "identifying" : "resuming the previous session"));
+                end = serve_connection();
+            }
+        }
+        if (end.fatal || stopping_) break;
+        if (end.ready) attempt = 0;
+        const auto& backoff = options_.backoff;
+        auto delay = backoff.empty() ? std::chrono::milliseconds(1000)
+                                     : backoff[(std::min)(attempt, backoff.size() - 1)];
+        delay = (std::max)(delay, end.extra_delay);
+        ++attempt;
+        if (!wait_for(delay)) break;
+    }
+    // 致命错误后保持 Failed 状态,线程等到 stop() 再退出。
+    if (!stopping_) {
+        std::unique_lock<std::mutex> lock(wake_mu_);
+        wake_.wait(lock, [this] { return stopping_.load(); });
+    }
+}
+
+DiscordTransport::ConnectionEnd DiscordTransport::serve_connection() {
+    ConnectionEnd end;
+    bool identified = false;
+    const auto secrets = std::vector<std::string>{options_.api.token, api_.token()};
+    session_.set_hello_timeout(options_.hello_timeout);
+    session_.on_connected(api_.token(), Clock::now(), random_jitter());
+    while (!stopping_) {
+        const auto tick = session_.on_tick(Clock::now());
+        if (tick.hello_timeout || tick.zombie) {
+            LOG_WARN(tick.zombie ? "[channels/discord] heartbeat not acknowledged, reconnecting"
+                                 : "[channels/discord] no Hello from the gateway, reconnecting");
+            // 非 1000 关闭码:会话保留,可以 Resume。
+            ws_.close(4000, tick.zombie ? "heartbeat timeout" : "hello timeout");
+            session_.on_closed(4000);
+            if (identified && !end.ready) budget_.record_failure();
+            set_status(LinkState::Retrying, "Discord 网关没有响应,正在重连");
+            return end;
+        }
+        if (tick.heartbeat) ws_.send_text(*tick.heartbeat, std::chrono::seconds(10), nullptr);
+        network::WebSocketMessage message;
+        std::string error;
+        const auto received = ws_.receive(message, options_.receive_slice, &error);
+        if (received == network::WebSocketRecv::Timeout) continue;
+        if (received == network::WebSocketRecv::Message) {
+            if (message.binary) {
+                // 没有请求压缩,不应出现二进制帧;当作协议错误重连。
+                LOG_WARN("[channels/discord] unexpected binary gateway frame, reconnecting");
+                ws_.close(4000, "unexpected binary frame");
+                session_.on_closed(4000);
+                set_status(LinkState::Retrying, "Discord 网关数据异常,正在重连");
+                return end;
+            }
+            auto out = session_.on_frame(message.data, Clock::now());
+            for (const auto& frame : out.frames) ws_.send_text(frame, std::chrono::seconds(10), nullptr);
+            if (out.identified) {
+                identified = true;
+                budget_.record_identify(wall_ms());
+                LOG_INFO("[channels/discord] identify sent (" + std::to_string(budget_.count()) +
+                         " in the current 24h window)");
+                if (options_.on_identify_ledger) {
+                    try {
+                        options_.on_identify_ledger(budget_.window_start_ms(), budget_.count());
+                    } catch (const std::exception& e) {
+                        LOG_WARN(std::string("[channels/discord] persisting the identify ledger failed: ") + e.what());
+                    }
+                }
+            }
+            if (out.ready) {
+                end.ready = true;
+                if (!out.resumed) budget_.record_ready();
+                if (out.ready_info) on_ready(*out.ready_info);
+                LOG_INFO(out.resumed ? "[channels/discord] session resumed" : "[channels/discord] ready");
+                set_status(LinkState::Connected, {});
+            }
+            for (const auto& [type, d] : out.dispatches) handle_dispatch(type, d);
+            if (out.reconnect) {
+                if (out.invalid_session) {
+                    LOG_INFO("[channels/discord] session invalidated by the gateway (op 9), will identify again");
+                    if (identified && !end.ready) budget_.record_failure();
+                    // 会话已经作废,1000 关闭即可;等 1–5 秒再登录。
+                    ws_.close(1000, "invalid session");
+                    end.extra_delay = random_between(options_.invalid_session_delay_min,
+                                                     options_.invalid_session_delay_max);
+                    set_status(LinkState::Retrying, "Discord 会话已失效,正在重新登录");
+                } else {
+                    LOG_INFO("[channels/discord] gateway asked to reconnect, resuming");
+                    ws_.close(4000, "reconnect requested");
+                    set_status(LinkState::Retrying, "Discord 要求重新连接,正在恢复");
+                }
+                session_.on_closed(4000);
+                return end;
+            }
+            continue;
+        }
+        if (stopping_) break;
+        const int code = received == network::WebSocketRecv::Closed ? ws_.close_code() : 1006;
+        if (received == network::WebSocketRecv::Error)
+            LOG_WARN("[channels/discord] gateway receive error: " + redact_secrets(error, secrets));
+        const auto decision = session_.on_closed(code);
+        LOG_INFO("[channels/discord] gateway closed with code " + std::to_string(code) + " (" +
+                 action_name(decision.action) + ")");
+        if (identified && !end.ready) budget_.record_failure();
+        ws_.close(4000);
+        if (decision.action == CloseAction::Fatal) {
+            LOG_WARN("[channels/discord] gateway close code " + std::to_string(code) + " is fatal, not retrying");
+            set_status(LinkState::Failed, decision.reason, true);
+            end.fatal = true;
+        } else {
+            if (decision.action == CloseAction::RateLimited) end.extra_delay = options_.rate_limit_close_delay;
+            set_status(LinkState::Retrying, decision.reason);
+        }
+        return end;
+    }
+    // 停机:以 1000 关闭,会话作废。
+    ws_.close(1000, "shutdown");
+    session_.clear_session();
+    return end;
+}
+
+void DiscordTransport::on_ready(const ReadyInfo& info) {
+    std::lock_guard<std::mutex> lock(mu_);
+    if (!info.bot_id.empty()) bot_id_ = info.bot_id;
+    status_.account = bot_id_;
+    if (!info.bot_name.empty()) {
+        status_.display_name = info.bot_name;
+        status_.extra["username"] = info.bot_name;
+    }
+    if (!info.application_id.empty()) {
+        status_.extra["application_id"] = info.application_id;
+        status_.extra["invite_url"] = invite_url(info.application_id);
+    }
+    status_.extra["guilds"] = info.guild_count;
+    status_.extra["identifies_24h"] = budget_.count();
+    LOG_INFO("[channels/discord] bot " + bot_id_ + " is in " + std::to_string(info.guild_count) + " guild(s)");
+}
+
+bool DiscordTransport::seen_before(const std::string& message_id) {
+    std::lock_guard<std::mutex> lock(seen_mu_);
+    if (seen_.count(message_id)) return true;
+    seen_.insert(message_id);
+    seen_order_.push_back(message_id);
+    while (seen_order_.size() > kSeenLimit) {
+        seen_.erase(seen_order_.front());
+        seen_order_.pop_front();
+    }
+    return false;
+}
+
+void DiscordTransport::remember_attachments(const Inbound& inbound) {
+    if (inbound.attachments.empty()) return;
+    const auto channel = string_field(inbound.reply_context, "channel_id");
+    std::lock_guard<std::mutex> lock(mu_);
+    for (const auto& attachment : inbound.attachments) {
+        const auto id = attachment_id_from_url(attachment.remote_ref);
+        if (id.empty() || origins_.count(id)) continue;
+        origins_[id] = {channel, inbound.message_id};
+        origin_order_.push_back(id);
+    }
+    while (origin_order_.size() > kOriginLimit) {
+        origins_.erase(origin_order_.front());
+        origin_order_.pop_front();
+    }
+}
+
+void DiscordTransport::handle_dispatch(const std::string& type, const nlohmann::json& d) {
+    if (type == "GUILD_CREATE") {
+        // 学会机器人自己的托管角色:有人在补全里选了角色(<@&id>)也算 @机器人。
+        for (auto& id : bot_role_ids_in_guild(d, bot_user_id())) bot_roles_.insert(std::move(id));
+        return;
+    }
+    if (type != "MESSAGE_CREATE") return;
+    auto parsed = parse_message_create(d, bot_user_id(), bot_roles_);
+    if (!parsed.inbound) {
+        LOG_DEBUG("[channels/discord] inbound message dropped: " + parsed.drop_reason);
+        return;
+    }
+    // Resume 补发与“最多推送 N 次”的投递语义都会带来重复,按消息 id 去重。
+    if (seen_before(parsed.inbound->message_id)) {
+        LOG_DEBUG("[channels/discord] duplicate message " + parsed.inbound->message_id + " ignored");
+        return;
+    }
+    if (!parsed.dm_user.empty() && !parsed.dm_channel.empty()) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (dm_channels_.size() >= kDmCacheLimit) dm_channels_.clear();
+        dm_channels_[parsed.dm_user] = parsed.dm_channel;
+    }
+    remember_attachments(*parsed.inbound);
+    if (callbacks_.on_inbound) callbacks_.on_inbound(std::move(*parsed.inbound));
+}
+
+std::string DiscordTransport::resolve_channel(const Address& to, const nlohmann::json& reply_context,
+                                              std::string* error) {
+    if (to.kind == ChatKind::Group) {
+        if (to.chat.empty()) {
+            if (error) *error = "目标频道为空";
+            return {};
+        }
+        return to.chat;
+    }
+    if (to.chat.empty()) {
+        if (error) *error = "目标用户为空";
+        return {};
+    }
+    // 私聊:优先用触发本回合的那条私信所在的频道(reply_context 里没有 guild_id 才是私聊)。
+    const auto context_channel = string_field(reply_context, "channel_id");
+    if (!context_channel.empty() && string_field(reply_context, "guild_id").empty()) {
+        std::lock_guard<std::mutex> lock(mu_);
+        dm_channels_[to.chat] = context_channel;
+        return context_channel;
+    }
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        const auto it = dm_channels_.find(to.chat);
+        if (it != dm_channels_.end()) return it->second;
+    }
+    // 没有可用的私聊频道(Desktop 里输入的回复、给机主发绑定码):打开(或取回已有的)私聊频道。
+    const auto result = api_.open_dm(to.chat);
+    if (!result.ok) {
+        LOG_WARN("[channels/discord] open DM failed: HTTP " + std::to_string(result.status) + " code " +
+                 std::to_string(result.error.code));
+        if (error) *error = result.cancelled ? "Discord 通道已停止" : describe_error(result.error);
+        return {};
+    }
+    const auto channel = string_field(result.body, "id");
+    if (channel.empty()) {
+        if (error) *error = "Discord 没有返回私聊频道";
+        return {};
+    }
+    std::lock_guard<std::mutex> lock(mu_);
+    if (dm_channels_.size() >= kDmCacheLimit) dm_channels_.clear();
+    dm_channels_[to.chat] = channel;
+    return channel;
+}
+
+SendResult DiscordTransport::send_text(const Address& to, const std::string& text,
+                                       const nlohmann::json& reply_context) {
+    std::string error;
+    const auto chunks = chunk_text(format_markdown(text), kMaxTextUnits, true);
+    if (chunks.empty()) return {SendOutcome::Sent, {}};
+    const auto channel = resolve_channel(to, reply_context, &error);
+    if (channel.empty()) return {SendOutcome::Failed, error};
+    const auto reference = reply_reference(reply_context, channel);
+    std::lock_guard<std::mutex> lock(send_mu_);
+    bool first = true;
+    for (const auto& chunk : chunks) {
+        const bool with_reference = first && reference.has_value();
+        nlohmann::json body{{"content", chunk}, {"allowed_mentions", allowed_mentions(with_reference)}};
+        if (with_reference)
+            body["message_reference"] = {{"message_id", *reference}, {"fail_if_not_exists", false}};
+        auto result = api_.create_message(channel, body);
+        if (!result.ok && with_reference && reference_rejected(result.error)) {
+            LOG_INFO("[channels/discord] reply reference rejected (code " + std::to_string(result.error.code) +
+                     "), resending without it");
+            body.erase("message_reference");
+            body["allowed_mentions"] = allowed_mentions(false);
+            result = api_.create_message(channel, body);
+        }
+        if (!result.ok) {
+            if (result.cancelled) return {SendOutcome::Failed, "Discord 通道已停止"};
+            LOG_WARN("[channels/discord] send to channel " + channel + " failed: HTTP " +
+                     std::to_string(result.status) + " code " + std::to_string(result.error.code));
+            return {SendOutcome::Failed, describe_error(result.error)};
+        }
+        first = false;
+    }
+    return {SendOutcome::Sent, {}};
+}
+
+SendResult DiscordTransport::oversize_notice(const Address& to, const std::string& name,
+                                             const nlohmann::json& reply_context, bool local_limit) {
+    std::string limit;
+    if (local_limit) limit = "(" + std::to_string(options_.max_upload_bytes / (1024u * 1024u)) + " MiB)";
+    LOG_INFO("[channels/discord] file is over the upload limit, sending a text notice instead");
+    return send_text(to, "文件「" + name + "」超过 Discord 上传上限" + limit + ",未发送;请在 ACECode 中查看。",
+                     reply_context);
+}
+
+SendResult DiscordTransport::send_file(const Address& to, const std::filesystem::path& path,
+                                       const std::string& name, const std::string& mime_type,
+                                       const nlohmann::json& reply_context) {
+    std::error_code ec;
+    const auto size = std::filesystem::file_size(path, ec);
+    if (ec) return {SendOutcome::Failed, "文件不存在或不可读"};
+    const auto display = name.empty() ? path_to_utf8(path.filename()) : name;
+    if (size > options_.max_upload_bytes) return oversize_notice(to, display, reply_context, true);
+    std::string error;
+    const auto channel = resolve_channel(to, reply_context, &error);
+    if (channel.empty()) return {SendOutcome::Failed, error};
+    const auto reference = reply_reference(reply_context, channel);
+    // payload_json 里的 filename 决定对方看到的文件名;multipart 的文件名只能是 ASCII。
+    auto payload_for = [&display](const std::optional<std::string>& ref) {
+        const nlohmann::json attachment{{"id", 0}, {"filename", display}};
+        nlohmann::json payload{{"attachments", nlohmann::json::array({attachment})},
+                               {"allowed_mentions", allowed_mentions(ref.has_value())}};
+        if (ref) payload["message_reference"] = {{"message_id", *ref}, {"fail_if_not_exists", false}};
+        return payload;
+    };
+    ApiResult result;
+    {
+        std::lock_guard<std::mutex> lock(send_mu_);
+        result = api_.create_message_with_file(channel, payload_for(reference), path, display, mime_type);
+        if (!result.ok && reference && reference_rejected(result.error)) {
+            LOG_INFO("[channels/discord] reply reference rejected for an upload, resending without it");
+            result = api_.create_message_with_file(channel, payload_for(std::nullopt), path, display, mime_type);
+        }
+    }
+    if (!result.ok && upload_too_large(result.error)) return oversize_notice(to, display, reply_context, false);
+    if (!result.ok) {
+        if (result.cancelled) return {SendOutcome::Failed, "Discord 通道已停止"};
+        LOG_WARN("[channels/discord] upload to channel " + channel + " failed: HTTP " + std::to_string(result.status) +
+                 " code " + std::to_string(result.error.code));
+        return {SendOutcome::Failed, describe_error(result.error)};
+    }
+    // 已知坑:Discord 偶尔返回 200 但 attachments 为空,文件其实没发出去。
+    const auto attachments = result.body.is_object() && result.body.contains("attachments")
+                                 ? result.body["attachments"]
+                                 : nlohmann::json();
+    if (!attachments.is_array() || attachments.empty()) {
+        LOG_WARN("[channels/discord] upload to channel " + channel + " returned no attachments");
+        return {SendOutcome::Failed, "Discord 没有收到文件,请重试"};
+    }
+    return {SendOutcome::Sent, {}};
+}
+
+void DiscordTransport::set_typing(const Address& to, bool on) {
+    const auto key = to.key();
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (!on) {
+            typing_.erase(key);
+            return;
+        }
+        if (typing_.count(key)) return;
+        typing_[key] = {to, Clock::now()};
+    }
+    {
+        std::lock_guard<std::mutex> lock(wake_mu_);
+        typing_dirty_ = true;
+    }
+    wake_.notify_all();
+}
+
+void DiscordTransport::typing_loop() {
+    while (!stopping_) {
+        std::vector<Address> due;
+        const auto now = Clock::now();
+        auto next = now + options_.typing_interval;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            for (auto& [key, entry] : typing_) {
+                if (entry.due <= now) {
+                    due.push_back(entry.address);
+                    entry.due = now + options_.typing_interval;
+                }
+                next = (std::min)(next, entry.due);
+            }
+        }
+        for (const auto& address : due) {
+            if (stopping_) break;
+            std::string error;
+            const auto channel = resolve_channel(address, nlohmann::json::object(), &error);
+            ApiResult result;
+            if (!channel.empty()) result = api_.trigger_typing(channel);
+            if (!result.ok && !result.cancelled && !stopping_) {
+                // 429 已在 Api 里等待重发;其它错误(没权限、频道没了)不再继续刷输入状态。
+                LOG_DEBUG("[channels/discord] typing indicator stopped: HTTP " + std::to_string(result.status));
+                std::lock_guard<std::mutex> lock(mu_);
+                typing_.erase(address.key());
+            }
+        }
+        std::unique_lock<std::mutex> lock(wake_mu_);
+        wake_.wait_until(lock, next, [this] { return stopping_.load() || typing_dirty_.load(); });
+        typing_dirty_ = false;
+    }
+}
+
+bool DiscordTransport::host_allowed(const std::string& url) const {
+    if (options_.download_hosts.empty()) return true;
+    const auto host = url_host(url);
+    if (host.empty()) return false;
+    return std::any_of(options_.download_hosts.begin(), options_.download_hosts.end(),
+                       [&host](const std::string& allowed) { return lower(allowed) == host; });
+}
+
+std::string DiscordTransport::refresh_attachment_url(const std::string& url) {
+    const auto id = attachment_id_from_url(url);
+    if (id.empty()) return {};
+    AttachmentOrigin origin;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        const auto it = origins_.find(id);
+        if (it == origins_.end()) return {};
+        origin = it->second;
+    }
+    if (origin.channel_id.empty() || origin.message_id.empty()) return {};
+    const auto message = api_.get_message(origin.channel_id, origin.message_id);
+    if (!message.ok) return {};
+    return find_attachment_url(message.body, id);
+}
+
+bool DiscordTransport::download(const Attachment& attachment, const std::filesystem::path& dest,
+                                std::string* error) {
+    if (attachment.remote_ref.empty()) {
+        if (error) *error = "附件缺少下载地址";
+        return false;
+    }
+    if (attachment.size > options_.max_download_bytes) {
+        if (error) *error = "附件超过大小限制";
+        return false;
+    }
+    if (!host_allowed(attachment.remote_ref)) {
+        LOG_WARN("[channels/discord] refusing to download an attachment from host " + url_host(attachment.remote_ref));
+        if (error) *error = "附件地址不是 Discord 的 CDN,已拒绝下载";
+        return false;
+    }
+    auto result = api_.download(attachment.remote_ref, dest, options_.max_download_bytes);
+    if (!result.ok && !result.too_large && (result.status == 403 || result.status == 404)) {
+        // 签名地址过期:重新取一次消息,拿到新的签名地址再下载。
+        const auto fresh = refresh_attachment_url(attachment.remote_ref);
+        if (!fresh.empty() && host_allowed(fresh)) {
+            LOG_INFO("[channels/discord] attachment URL expired, downloading with a refreshed URL");
+            result = api_.download(fresh, dest, options_.max_download_bytes);
+        }
+    }
+    if (result.too_large) {
+        if (error) *error = "附件超过大小限制";
+        return false;
+    }
+    if (!result.ok) {
+        LOG_WARN("[channels/discord] attachment download failed: " + result.error);
+        if (error) {
+            *error = result.cancelled ? "Discord 通道已停止"
+                     : result.status == 0 ? "无法连接 Discord,附件下载失败"
+                                          : "下载附件失败:HTTP " + std::to_string(result.status);
+        }
+        return false;
+    }
+    return true;
+}
+
+} // namespace acecode::im::discord
diff --git a/src/adapters/im/discord/discord_transport.hpp b/src/adapters/im/discord/discord_transport.hpp
new file mode 100644
index 000000000..e248988ae
--- /dev/null
+++ b/src/adapters/im/discord/discord_transport.hpp
@@ -0,0 +1,148 @@
+#pragma once
+
+// Discord 机器人传输层:网关 WebSocket 收消息 + REST 发消息(只需出站 HTTPS / WSS)。
+//
+// 线程:
+//   - 网关线程:取网关地址、连接、心跳、Identify / Resume、解析 MESSAGE_CREATE 并回调 on_inbound;
+//     不做任何会阻塞心跳的 REST 调用。
+//   - 输入状态线程:set_typing(on) 期间每 typing_interval(默认 8 秒,指示器 10 秒过期)发一次
+//     POST /channels/{id}/typing。
+//   - 发送在调用方线程上进行,send_mu_ 串行化,保证同一传输层的消息按调用顺序送达;429 等待后重发。
+//
+// 登录预算:Identify 每 24 小时最多 1000 次(超出会被重置 token)。优先 Resume;Identify 前检查
+// IdentifyBudget 与 /gateway/bot 的 session_start_limit;24 小时计数通过 on_identify_ledger 交给
+// 调用方持久化,重启后由 identify_window_start_ms / identify_count 带回。
+
+#include "im/discord/discord_api.hpp"
+#include "im/discord/discord_gateway.hpp"
+#include "im/transport.hpp"
+#include "network/websocket_client.hpp"
+#include "utils/joining_thread.hpp"
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <deque>
+#include <functional>
+#include <map>
+#include <mutex>
+#include <optional>
+#include <random>
+#include <set>
+#include <string>
+#include <vector>
+
+namespace acecode::im::discord {
+
+struct DiscordTransportOptions {
+    ApiOptions api;
+    RateLimitPolicy rate_limit;
+    std::vector<std::chrono::milliseconds> backoff{
+        std::chrono::seconds(1), std::chrono::seconds(2), std::chrono::seconds(5),
+        std::chrono::seconds(10), std::chrono::seconds(30), std::chrono::seconds(60)};
+    std::chrono::milliseconds rate_limit_close_delay{std::chrono::seconds(60)};  // 网关 4008 之后
+    // op 9(d=false)之后随机等待 [min, max] 再重新 Identify。
+    std::chrono::milliseconds invalid_session_delay_min{std::chrono::seconds(1)};
+    std::chrono::milliseconds invalid_session_delay_max{std::chrono::seconds(5)};
+    std::chrono::milliseconds hello_timeout{std::chrono::seconds(20)};
+    std::chrono::milliseconds typing_interval{std::chrono::seconds(8)};
+    std::chrono::milliseconds receive_slice{250};  // 网关读超时,也是心跳检查的粒度
+    IdentifyBudget::Limits identify_limits;
+    // 持久化的 24 小时登录计数(Unix 毫秒 / 次数);0 表示没有记录。
+    std::int64_t identify_window_start_ms = 0;
+    std::int64_t identify_count = 0;
+    // 每次 Identify 后在网关线程上调用,交给调用方持久化;必须尽快返回。
+    std::function<void(std::int64_t window_start_ms, std::int64_t count)> on_identify_ledger;
+    // READY 与大服务器的 GUILD_CREATE 可达数 MB。
+    std::size_t max_message_bytes = 16u * 1024u * 1024u;
+    std::uint64_t max_upload_bytes = 20u * 1024u * 1024u;   // 官方默认单文件上限 20 MiB
+    std::uint64_t max_download_bytes = 25u * 1024u * 1024u;
+    // 只从这些主机下载附件(防止把请求引到别处);为空表示不检查(仅测试用)。
+    std::vector<std::string> download_hosts{"cdn.discordapp.com", "media.discordapp.net"};
+};
+
+class DiscordTransport final : public Transport {
+public:
+    explicit DiscordTransport(DiscordTransportOptions options);
+    ~DiscordTransport() override;
+
+    std::string platform() const override { return kPlatform; }
+    Capabilities capabilities() const override;
+    void start(TransportCallbacks callbacks) override;
+    void stop() override;
+    TransportStatus status() const override;
+    SendResult send_text(const Address& to, const std::string& text,
+                         const nlohmann::json& reply_context) override;
+    SendResult send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                         const std::string& mime_type, const nlohmann::json& reply_context) override;
+    void set_typing(const Address& to, bool on) override;
+    bool download(const Attachment& attachment, const std::filesystem::path& dest,
+                  std::string* error) override;
+
+    // READY 之后的机器人用户 id(= Address::account);连上之前为空。
+    std::string bot_user_id() const;
+
+private:
+    using Clock = std::chrono::steady_clock;
+
+    struct ConnectionEnd {
+        bool fatal = false;
+        bool ready = false;  // 本次连接收到过 READY / RESUMED
+        std::chrono::milliseconds extra_delay{0};
+    };
+    struct TypingEntry {
+        Address address;
+        Clock::time_point due;
+    };
+    struct AttachmentOrigin {
+        std::string channel_id;
+        std::string message_id;
+    };
+
+    void run();
+    ConnectionEnd serve_connection();
+    void typing_loop();
+    bool wait_for(std::chrono::milliseconds duration);
+    void set_status(LinkState state, const std::string& detail, bool retry_stopped = false);
+    void on_ready(const ReadyInfo& info);
+    void handle_dispatch(const std::string& type, const nlohmann::json& d);
+    bool seen_before(const std::string& message_id);
+    void remember_attachments(const Inbound& inbound);
+    std::string refresh_attachment_url(const std::string& url);
+    bool host_allowed(const std::string& url) const;
+    std::string resolve_channel(const Address& to, const nlohmann::json& reply_context, std::string* error);
+    SendResult oversize_notice(const Address& to, const std::string& name, const nlohmann::json& reply_context,
+                               bool local_limit);
+    std::int64_t wall_ms() const;
+    double random_jitter();
+    std::chrono::milliseconds random_between(std::chrono::milliseconds low, std::chrono::milliseconds high);
+
+    DiscordTransportOptions options_;
+    Api api_;
+    GatewaySession session_;    // 只在网关线程上访问(stop 在 join 之后)
+    IdentifyBudget budget_;     // 同上
+    std::string gateway_url_;   // 最近一次 /gateway/bot 给出的地址
+    std::set<std::string> bot_roles_;  // 机器人的托管角色;只在网关线程上访问
+    std::mt19937_64 rng_;              // 只在网关线程上访问
+    network::WebSocketClient ws_;
+    TransportCallbacks callbacks_;
+    acecode::JoiningThread gateway_, typer_;
+    std::atomic<bool> running_{false};
+    std::atomic<bool> stopping_{false};
+    std::atomic<bool> typing_dirty_{false};
+    std::mutex wake_mu_;
+    std::condition_variable wake_;
+    std::mutex send_mu_;  // 串行化发消息
+    mutable std::mutex mu_;  // status_、bot_id_、dm_channels_、typing_、origins_
+    TransportStatus status_;
+    std::string bot_id_;
+    std::map<std::string, std::string> dm_channels_;  // 用户 id → 私聊频道 id
+    std::map<std::string, TypingEntry> typing_;       // Address::key() → 条目
+    std::map<std::string, AttachmentOrigin> origins_;  // 附件 id → 所在消息(签名过期时重新取地址)
+    std::deque<std::string> origin_order_;
+    std::mutex seen_mu_;
+    std::set<std::string> seen_;
+    std::deque<std::string> seen_order_;
+};
+
+} // namespace acecode::im::discord
diff --git a/src/adapters/im/feishu/feishu_api.cpp b/src/adapters/im/feishu/feishu_api.cpp
new file mode 100644
index 000000000..005c46a81
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_api.cpp
@@ -0,0 +1,315 @@
+#include "im/feishu/feishu_api.hpp"
+
+#include "im/redact.hpp"
+
+#include <algorithm>
+#include <fstream>
+#include <iterator>
+
+namespace acecode::im::feishu {
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+std::string trim_slash(std::string base) {
+    while (!base.empty() && base.back() == '/') base.pop_back();
+    return base;
+}
+
+std::string path_segment(const std::string& value) {
+    static constexpr char kHex[] = "0123456789ABCDEF";
+    std::string out;
+    for (const char c : value) {
+        const auto u = static_cast<unsigned char>(c);
+        if ((u >= 'A' && u <= 'Z') || (u >= 'a' && u <= 'z') || (u >= '0' && u <= '9') || u == '-' || u == '_' ||
+            u == '.' || u == '~') {
+            out.push_back(c);
+        } else {
+            out.push_back('%');
+            out.push_back(kHex[u >> 4]);
+            out.push_back(kHex[u & 0x0F]);
+        }
+    }
+    return out;
+}
+
+std::function<bool()> cancel_check(const std::atomic<bool>* cancel) {
+    if (!cancel) return {};
+    return [cancel] { return cancel->load(); };
+}
+
+// 下载失败时响应体(JSON 错误)已经写进了目标文件:读回一小段用于解析错误码。
+std::string read_head(const std::filesystem::path& path, std::size_t limit) {
+    std::ifstream in(path, std::ios::binary);
+    if (!in) return {};
+    std::string data(limit, '\0');
+    in.read(data.data(), static_cast<std::streamsize>(limit));
+    data.resize(static_cast<std::size_t>(in.gcount()));
+    return data;
+}
+
+// 限流等待秒数与请求 id 只在响应头里(键已由 http_send 转成小写)。
+void attach_response_headers(ApiResult& result, const HttpResponse& response) {
+    const auto logid = response.headers.find("x-tt-logid");
+    if (logid != response.headers.end()) result.log_id = logid->second;
+    const auto reset = response.headers.find("x-ogw-ratelimit-reset");
+    if (reset != response.headers.end()) result.retry_after = parse_retry_after(reset->second);
+}
+
+} // namespace
+
+std::string feishu_user_agent() { return user_agent() + " source/acecode channel"; }
+
+Api::Api(ApiOptions options) : options_(std::move(options)) {}
+
+std::string Api::url(const std::string& path) const { return trim_slash(options_.base) + path; }
+
+std::string Api::redact(const std::string& text) const { return redact_secrets(text, {options_.app_secret}); }
+
+std::string Api::fetch_token_locked(std::string* error, const std::atomic<bool>* cancel) {
+    HttpRequest request;
+    request.method = "POST";
+    request.url = url("/open-apis/auth/v3/tenant_access_token/internal");
+    request.headers = {{"Content-Type", "application/json; charset=utf-8"}, {"User-Agent", feishu_user_agent()}};
+    request.body = dump_json({{"app_id", options_.app_id}, {"app_secret", options_.app_secret}});
+    request.timeout = std::chrono::seconds(15);
+    request.use_proxy = options_.use_proxy;
+    request.cancel = cancel_check(cancel);
+    const auto response = http_send(request);
+    auth_failed_ = false;
+    if (response.cancelled) {
+        if (error) *error = "已取消";
+        return {};
+    }
+    if (response.status == 0) {
+        if (error)
+            *error = redact("无法连接飞书开放平台" + (response.error.empty() ? std::string{} : ":" + response.error));
+        return {};
+    }
+    const auto result = parse_api_response(response.status, response.body);
+    const auto token = result.body.is_object() && result.body.contains("tenant_access_token") &&
+                               result.body["tenant_access_token"].is_string()
+                           ? result.body["tenant_access_token"].get<std::string>()
+                           : std::string{};
+    if (result.ok && !token.empty()) {
+        long long seconds = 7200;
+        if (result.body.contains("expire") && result.body["expire"].is_number_integer())
+            seconds = std::max<long long>(1, result.body["expire"].get<long long>());
+        // 官方 SDK 提前 10 分钟刷新;寿命本身很短时提前一半。
+        const auto margin = std::min<long long>(600, seconds / 2);
+        token_ = token;
+        refresh_at_ = Clock::now() + std::chrono::seconds(std::max<long long>(seconds - margin, 1));
+        return token_;
+    }
+    if (result.body.is_object() && result.body.contains("code") && result.code != 0 && !is_rate_limited(result) &&
+        response.status < 500 && !(result.code >= 50000 && result.code <= 59999)) {
+        // 这个接口返回非 0 code 即凭据有问题(无效、停用、选错飞书 / Lark)。
+        auth_failed_ = true;
+        if (error) *error = redact(describe_token_error(result.code, result.msg));
+        return {};
+    }
+    if (error) {
+        *error = response.status >= 500 || is_rate_limited(result)
+                     ? "飞书开放平台暂时不可用(HTTP " + std::to_string(response.status) + ")"
+                     : std::string("飞书返回了无效的令牌响应");
+    }
+    return {};
+}
+
+std::string Api::tenant_token(std::string* error, const std::atomic<bool>* cancel) {
+    std::lock_guard<std::mutex> lock(mu_);
+    if (!token_.empty() && Clock::now() < refresh_at_) return token_;
+    return fetch_token_locked(error, cancel);
+}
+
+void Api::invalidate_token() {
+    std::lock_guard<std::mutex> lock(mu_);
+    token_.clear();
+    refresh_at_ = {};
+}
+
+bool Api::last_token_auth_failed() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return auth_failed_;
+}
+
+ApiResult Api::call(const std::string& method, const std::string& path, const nlohmann::json& body,
+                    const std::atomic<bool>* cancel, std::chrono::milliseconds timeout) {
+    ApiResult result;
+    for (int attempt = 0; attempt < 2; ++attempt) {
+        std::string error;
+        const auto token = tenant_token(&error, cancel);
+        if (token.empty()) {
+            result = ApiResult{};
+            result.error = error;
+            result.auth_failed = last_token_auth_failed();
+            result.cancelled = cancel && cancel->load();
+            return result;
+        }
+        HttpRequest request;
+        request.method = method;
+        request.url = url(path);
+        request.headers = {{"Authorization", "Bearer " + token}, {"User-Agent", feishu_user_agent()}};
+        if (!body.is_null()) {
+            request.headers.emplace_back("Content-Type", "application/json; charset=utf-8");
+            request.body = dump_json(body);
+        }
+        request.timeout = timeout;
+        request.use_proxy = options_.use_proxy;
+        request.cancel = cancel_check(cancel);
+        const auto response = http_send(request);
+        result = parse_api_response(response.status, response.body);
+        result.cancelled = response.cancelled;
+        attach_response_headers(result, response);
+        if (response.status == 0) result.error = redact(response.error);
+        if (is_token_invalid(result.code) && attempt == 0) {
+            invalidate_token();
+            continue;
+        }
+        result.msg = redact(result.msg);
+        return result;
+    }
+    return result;
+}
+
+ApiResult Api::upload(const std::string& path, const std::vector<HttpPart>& parts) {
+    ApiResult result;
+    for (int attempt = 0; attempt < 2; ++attempt) {
+        std::string error;
+        const auto token = tenant_token(&error);
+        if (token.empty()) {
+            result = ApiResult{};
+            result.error = error;
+            result.auth_failed = last_token_auth_failed();
+            return result;
+        }
+        HttpRequest request;
+        request.method = "POST";
+        request.url = url(path);
+        request.headers = {{"Authorization", "Bearer " + token}, {"User-Agent", feishu_user_agent()}};
+        request.parts = parts;
+        request.timeout = std::chrono::minutes(5);
+        request.use_proxy = options_.use_proxy;
+        const auto response = http_send(request);
+        result = parse_api_response(response.status, response.body);
+        attach_response_headers(result, response);
+        if (response.status == 0) result.error = redact(response.error);
+        if (is_token_invalid(result.code) && attempt == 0) {
+            invalidate_token();
+            continue;
+        }
+        result.msg = redact(result.msg);
+        return result;
+    }
+    return result;
+}
+
+BotInfo Api::bot_info(std::string* error, const std::atomic<bool>* cancel) {
+    const auto result = call("GET", "/open-apis/bot/v3/info", nullptr, cancel, std::chrono::seconds(15));
+    if (!result.ok) {
+        if (error) *error = describe_error(result);
+        return {};
+    }
+    auto info = parse_bot_info(result.body);
+    if (!info.ok && error) *error = describe_activate_status(-1);
+    return info;
+}
+
+EndpointInfo Api::ws_endpoint(const std::atomic<bool>* cancel) {
+    HttpRequest request;
+    request.method = "POST";
+    request.url = url("/callback/ws/endpoint");
+    // 两个 SDK 都带 locale: zh,错误信息会以中文返回。
+    request.headers = {{"Content-Type", "application/json"}, {"locale", "zh"}, {"User-Agent", feishu_user_agent()}};
+    request.body = dump_json({{"AppID", options_.app_id}, {"AppSecret", options_.app_secret}});
+    request.timeout = std::chrono::seconds(15);
+    request.use_proxy = options_.use_proxy;
+    request.cancel = cancel_check(cancel);
+    const auto response = http_send(request);
+    if (response.status == 0) {
+        EndpointInfo info;
+        info.message = response.cancelled
+                           ? std::string("已取消")
+                           : redact("无法连接飞书开放平台" +
+                                    (response.error.empty() ? std::string{} : ":" + response.error));
+        return info;
+    }
+    auto info = parse_endpoint_response(response.status, response.body);
+    info.message = redact(info.message);
+    return info;
+}
+
+bool Api::download_resource(const ResourceRef& ref, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                            std::string* error) {
+    for (int attempt = 0; attempt < 2; ++attempt) {
+        std::string token_error;
+        const auto token = tenant_token(&token_error);
+        if (token.empty()) {
+            if (error) *error = "下载附件失败:" + token_error;
+            return false;
+        }
+        HttpRequest request;
+        request.url = url("/open-apis/im/v1/messages/" + path_segment(ref.message_id) + "/resources/" +
+                          path_segment(ref.key) + "?type=" + path_segment(ref.type));
+        request.headers = {{"Authorization", "Bearer " + token}, {"User-Agent", feishu_user_agent()}};
+        request.timeout = std::chrono::minutes(5);
+        request.use_proxy = options_.use_proxy;
+        request.download_to = dest;
+        request.max_download_bytes = max_bytes;
+        const auto response = http_send(request);
+        if (response.too_large) {
+            if (error) *error = "附件超过大小限制";
+            return false;
+        }
+        if (response.status >= 200 && response.status < 300) return true;
+        const auto body = read_head(dest, 64 * 1024);
+        std::error_code ec;
+        std::filesystem::remove(dest, ec);
+        if (response.status == 0) {
+            if (error)
+                *error = redact("下载附件失败:无法连接飞书开放平台" +
+                                (response.error.empty() ? std::string{} : ":" + response.error));
+            return false;
+        }
+        const auto result = parse_api_response(response.status, body);
+        if (is_token_invalid(result.code) && attempt == 0) {
+            invalidate_token();
+            continue;
+        }
+        if (error) *error = "下载附件失败:" + redact(describe_error(result));
+        return false;
+    }
+    if (error) *error = "下载附件失败:飞书访问凭证失效";
+    return false;
+}
+
+VerifyResult verify_credentials(const ApiOptions& options) {
+    VerifyResult result;
+    if (options.app_id.empty() || options.app_secret.empty()) {
+        result.auth_failed = true;
+        result.error = "请填写 App ID 和 App Secret";
+        return result;
+    }
+    Api api(options);
+    std::string error;
+    if (api.tenant_token(&error).empty()) {
+        result.auth_failed = api.last_token_auth_failed();
+        result.network_error = !result.auth_failed;
+        result.error = error.empty() ? std::string("凭据校验失败") : error;
+        return result;
+    }
+    result.ok = true;
+    const auto bot = api.bot_info(&error);
+    if (bot.ok) {
+        result.bot_open_id = bot.open_id;
+        result.bot_name = bot.name;
+        result.activate_status = bot.activate_status;
+        result.bot_ready = bot.ready();
+        if (!result.bot_ready) result.bot_warning = describe_activate_status(bot.activate_status);
+    } else {
+        result.bot_warning = error.empty() ? describe_activate_status(-1) : error;
+    }
+    return result;
+}
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_api.hpp b/src/adapters/im/feishu/feishu_api.hpp
new file mode 100644
index 000000000..409801303
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_api.hpp
@@ -0,0 +1,95 @@
+#pragma once
+
+// 飞书 / Lark OpenAPI 客户端:tenant_access_token 缓存、机器人信息、长连接地址、
+// 发消息 / 回复、图片与文件上传、消息资源下载。
+// 线程安全:令牌刷新在锁内串行(单飞),其余调用可以并发。
+// App Secret、令牌、长连接地址(带票据)都不会出现在返回的错误文本里。
+
+#include "im/feishu/feishu_protocol.hpp"
+#include "im/http.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <filesystem>
+#include <mutex>
+#include <string>
+#include <vector>
+
+namespace acecode::im::feishu {
+
+struct ApiOptions {
+    std::string app_id;
+    std::string app_secret;
+    std::string base = kFeishuBase;  // base_for_domain("feishu" / "lark")
+    bool use_proxy = true;
+};
+
+// 所有请求的 User-Agent:"ACECode/<版本> source/acecode channel"。末尾独立的 channel 标记
+// 照官方渠道 SDK 发送(hermes #50656 称缺它时长连接收不到群 @ 事件;未证实,但发送无害)。
+std::string feishu_user_agent();
+
+class Api {
+public:
+    explicit Api(ApiOptions options);
+
+    // 有效的 tenant_access_token;距到期不足 10 分钟(或剩余寿命一半)时刷新。
+    // 失败返回空串,error 为中文原因(不含密钥)。cancel 置位时尽快放弃。
+    std::string tenant_token(std::string* error, const std::atomic<bool>* cancel = nullptr);
+    void invalidate_token();
+    // 最近一次换令牌失败是否因为凭据被拒(这种错误不会自己好,不应继续重连)。
+    bool last_token_auth_failed() const;
+
+    // 带令牌的 JSON 调用(method 为 GET / POST;body 为 null 时不发请求体)。
+    // 令牌失效类错误码(99991661/3/4/5)自动换新令牌并重试一次。
+    ApiResult call(const std::string& method, const std::string& path, const nlohmann::json& body = nullptr,
+                   const std::atomic<bool>* cancel = nullptr,
+                   std::chrono::milliseconds timeout = std::chrono::seconds(30));
+    // multipart 上传(图片 / 文件),令牌处理同 call。
+    ApiResult upload(const std::string& path, const std::vector<HttpPart>& parts);
+
+    // GET /open-apis/bot/v3/info。失败时 error 为中文原因。
+    BotInfo bot_info(std::string* error, const std::atomic<bool>* cancel = nullptr);
+    // POST /callback/ws/endpoint(用 App ID / App Secret 鉴权,不用令牌)。
+    EndpointInfo ws_endpoint(const std::atomic<bool>* cancel = nullptr);
+
+    // GET /open-apis/im/v1/messages/{message_id}/resources/{key}?type=image|file 下载到 dest。
+    // 超过 max_bytes(0 = 不限)失败并删除半截文件;失败时 error 为中文原因。
+    bool download_resource(const ResourceRef& ref, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                           std::string* error);
+
+    const ApiOptions& options() const { return options_; }
+
+private:
+    std::string url(const std::string& path) const;
+    std::string fetch_token_locked(std::string* error, const std::atomic<bool>* cancel);
+    std::string redact(const std::string& text) const;
+
+    ApiOptions options_;
+    mutable std::mutex mu_;
+    std::string token_;
+    std::chrono::steady_clock::time_point refresh_at_{};
+    bool auth_failed_ = false;
+};
+
+// 保存凭据前的联网校验:换 tenant_access_token,再取机器人信息。
+struct VerifyResult {
+    bool ok = false;             // 凭据有效(换到了令牌)
+    bool auth_failed = false;    // 凭据被拒:App ID / App Secret 不对,或飞书 / Lark 选错
+    bool network_error = false;  // 网络不通或平台暂时不可用,无法判断凭据
+    std::string error;           // 失败时给用户看的中文原因(不含密钥)
+    std::string bot_open_id;     // 机器人自己的 open_id(非密钥)
+    std::string bot_name;        // 机器人名称(应用名)
+    int activate_status = -1;    // bot/v3/info 的 activate_status;-1 = 没取到
+    bool bot_ready = false;      // activate_status == 2
+    // 凭据有效但机器人还没就绪(未添加机器人能力 / 未发布版本 / 被停用)时的提示。
+    // 长连接本身不依赖它:飞书后台要求先有在线的长连接才能保存“使用长连接接收事件”,
+    // 而发布版本往往在那之后,所以这里只提示、不判失败。
+    std::string bot_warning;
+};
+
+VerifyResult verify_credentials(const ApiOptions& options);
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_frame.cpp b/src/adapters/im/feishu/feishu_frame.cpp
new file mode 100644
index 000000000..fa44ccf63
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_frame.cpp
@@ -0,0 +1,212 @@
+#include "im/feishu/feishu_frame.hpp"
+
+namespace acecode::im::feishu {
+namespace {
+
+constexpr int kWireVarint = 0;
+constexpr int kWire64 = 1;
+constexpr int kWireBytes = 2;
+constexpr int kWire32 = 5;
+
+void put_varint(std::string& out, std::uint64_t value) {
+    while (value >= 0x80) {
+        out.push_back(static_cast<char>((value & 0x7F) | 0x80));
+        value >>= 7;
+    }
+    out.push_back(static_cast<char>(value));
+}
+
+void put_tag(std::string& out, int field, int wire) {
+    put_varint(out, (static_cast<std::uint64_t>(field) << 3) | static_cast<std::uint64_t>(wire));
+}
+
+void put_bytes(std::string& out, int field, std::string_view value) {
+    put_tag(out, field, kWireBytes);
+    put_varint(out, value.size());
+    out.append(value.data(), value.size());
+}
+
+// int32 按 protobuf 规则先符号扩展到 64 位,负数因此是 10 字节 varint。
+std::uint64_t int32_wire(std::int32_t value) {
+    return static_cast<std::uint64_t>(static_cast<std::int64_t>(value));
+}
+
+class Reader {
+public:
+    explicit Reader(std::string_view data) : data_(data) {}
+
+    bool done() const { return pos_ >= data_.size(); }
+
+    bool varint(std::uint64_t* value) {
+        std::uint64_t result = 0;
+        for (int i = 0; i < 10; ++i) {
+            if (pos_ >= data_.size()) return false;
+            const auto byte = static_cast<std::uint8_t>(data_[pos_++]);
+            result |= static_cast<std::uint64_t>(byte & 0x7F) << (7 * i);
+            if ((byte & 0x80) == 0) {
+                *value = result;
+                return true;
+            }
+        }
+        return false;  // 超过 10 字节
+    }
+
+    bool bytes(std::string_view* value) {
+        std::uint64_t length = 0;
+        if (!varint(&length)) return false;
+        if (length > data_.size() - pos_) return false;
+        *value = data_.substr(pos_, static_cast<std::size_t>(length));
+        pos_ += static_cast<std::size_t>(length);
+        return true;
+    }
+
+    bool skip(int wire) {
+        switch (wire) {
+            case kWireVarint: {
+                std::uint64_t ignored = 0;
+                return varint(&ignored);
+            }
+            case kWire64:
+                if (data_.size() - pos_ < 8) return false;
+                pos_ += 8;
+                return true;
+            case kWireBytes: {
+                std::string_view ignored;
+                return bytes(&ignored);
+            }
+            case kWire32:
+                if (data_.size() - pos_ < 4) return false;
+                pos_ += 4;
+                return true;
+            default:
+                return false;  // group 或非法 wire type
+        }
+    }
+
+private:
+    std::string_view data_;
+    std::size_t pos_ = 0;
+};
+
+bool fail(std::string* error, const char* reason) {
+    if (error) *error = reason;
+    return false;
+}
+
+bool decode_header(std::string_view bytes, std::pair<std::string, std::string>* out) {
+    Reader reader(bytes);
+    while (!reader.done()) {
+        std::uint64_t tag = 0;
+        if (!reader.varint(&tag)) return false;
+        const auto field = tag >> 3;
+        const int wire = static_cast<int>(tag & 0x07);
+        if ((field == 1 || field == 2) && wire == kWireBytes) {
+            std::string_view value;
+            if (!reader.bytes(&value)) return false;
+            (field == 1 ? out->first : out->second) = std::string(value);
+        } else if (field == 0 || !reader.skip(wire)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+} // namespace
+
+std::string Frame::header(std::string_view key) const {
+    for (const auto& [name, value] : headers) {
+        if (name == key) return value;
+    }
+    return {};
+}
+
+bool Frame::has_header(std::string_view key) const {
+    for (const auto& item : headers) {
+        if (item.first == key) return true;
+    }
+    return false;
+}
+
+std::string encode_frame(const Frame& frame) {
+    std::string out;
+    put_tag(out, 1, kWireVarint);
+    put_varint(out, frame.seq_id);
+    put_tag(out, 2, kWireVarint);
+    put_varint(out, frame.log_id);
+    put_tag(out, 3, kWireVarint);
+    put_varint(out, int32_wire(frame.service));
+    put_tag(out, 4, kWireVarint);
+    put_varint(out, int32_wire(frame.method));
+    for (const auto& [key, value] : frame.headers) {
+        std::string header;
+        put_bytes(header, 1, key);
+        put_bytes(header, 2, value);
+        put_bytes(out, 5, header);
+    }
+    if (frame.payload_encoding) put_bytes(out, 6, *frame.payload_encoding);
+    if (frame.payload_type) put_bytes(out, 7, *frame.payload_type);
+    if (frame.payload) put_bytes(out, 8, *frame.payload);
+    if (frame.log_id_new) put_bytes(out, 9, *frame.log_id_new);
+    return out;
+}
+
+bool decode_frame(std::string_view bytes, Frame* out, std::string* error) {
+    Frame frame;
+    Reader reader(bytes);
+    while (!reader.done()) {
+        std::uint64_t tag = 0;
+        if (!reader.varint(&tag)) return fail(error, "truncated tag");
+        const auto field = tag >> 3;
+        const int wire = static_cast<int>(tag & 0x07);
+        if (field == 0) return fail(error, "invalid field number");
+        if (field >= 1 && field <= 4) {
+            if (wire != kWireVarint) return fail(error, "unexpected wire type for scalar field");
+            std::uint64_t value = 0;
+            if (!reader.varint(&value)) return fail(error, "truncated varint");
+            if (field == 1) frame.seq_id = value;
+            else if (field == 2) frame.log_id = value;
+            // int32 取低 32 位(负数的 10 字节编码也落在这里)。
+            else if (field == 3) frame.service = static_cast<std::int32_t>(static_cast<std::uint32_t>(value));
+            else frame.method = static_cast<std::int32_t>(static_cast<std::uint32_t>(value));
+            continue;
+        }
+        if (field >= 5 && field <= 9) {
+            if (wire != kWireBytes) return fail(error, "unexpected wire type for bytes field");
+            std::string_view value;
+            if (!reader.bytes(&value)) return fail(error, "truncated length-delimited field");
+            switch (field) {
+                case 5: {
+                    std::pair<std::string, std::string> header;
+                    if (!decode_header(value, &header)) return fail(error, "malformed header");
+                    frame.headers.push_back(std::move(header));
+                    break;
+                }
+                case 6: frame.payload_encoding = std::string(value); break;
+                case 7: frame.payload_type = std::string(value); break;
+                case 8: frame.payload = std::string(value); break;
+                default: frame.log_id_new = std::string(value); break;
+            }
+            continue;
+        }
+        if (!reader.skip(wire)) return fail(error, "cannot skip unknown field");
+    }
+    *out = std::move(frame);
+    return true;
+}
+
+Frame make_ping_frame(std::int32_t service) {
+    Frame frame;
+    frame.service = service;
+    frame.method = kMethodControl;
+    frame.headers.emplace_back("type", "ping");
+    return frame;
+}
+
+Frame make_ack_frame(const Frame& received, std::int64_t biz_rt_ms, const std::string& response_json) {
+    Frame ack = received;
+    ack.headers.emplace_back("biz_rt", std::to_string(biz_rt_ms < 0 ? 0 : biz_rt_ms));
+    ack.payload = response_json;
+    return ack;
+}
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_frame.hpp b/src/adapters/im/feishu/feishu_frame.hpp
new file mode 100644
index 000000000..4f08eae89
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_frame.hpp
@@ -0,0 +1,59 @@
+#pragma once
+
+// 飞书 / Lark 长连接的二进制帧(protobuf proto2,package pbbp2)手写编解码,纯逻辑。
+//
+//   message Header { required string key = 1; required string value = 2; }
+//   message Frame {
+//     required uint64 SeqID = 1;  required uint64 LogID = 2;
+//     required int32  service = 3; required int32 method = 4;   // 0 = CONTROL, 1 = DATA
+//     repeated Header headers = 5;
+//     optional string payload_encoding = 6; optional string payload_type = 7;
+//     optional bytes  payload = 8;          optional string LogIDNew = 9;
+//   }
+//
+// 编码:字段 1–4 即使为 0 也必须写出;可选字段只在“存在”时写出(存在但为空也写),
+// 这样回 ACK 时能原样回显服务端帧里出现过的字段。字段按编号升序,headers 保持顺序。
+// 解码:接受任意字段顺序与重复 header,跳过未知字段(wire type 0/1/2/5);
+// varint 最长 10 字节;group(wire type 3/4)与越界长度视为损坏。
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+namespace acecode::im::feishu {
+
+inline constexpr std::int32_t kMethodControl = 0;
+inline constexpr std::int32_t kMethodData = 1;
+
+struct Frame {
+    std::uint64_t seq_id = 0;
+    std::uint64_t log_id = 0;
+    std::int32_t service = 0;
+    std::int32_t method = 0;
+    std::vector<std::pair<std::string, std::string>> headers;  // 保持原始顺序
+    std::optional<std::string> payload_encoding;
+    std::optional<std::string> payload_type;
+    std::optional<std::string> payload;
+    std::optional<std::string> log_id_new;
+
+    // 第一个同名 header 的值;不存在时返回空串。
+    std::string header(std::string_view key) const;
+    bool has_header(std::string_view key) const;
+};
+
+std::string encode_frame(const Frame& frame);
+
+// 失败时返回 false,error 为英文原因(只用于日志)。
+bool decode_frame(std::string_view bytes, Frame* out, std::string* error);
+
+// 客户端心跳:Frame{SeqID:0, LogID:0, service, method:CONTROL, headers:[type=ping]},无 payload。
+Frame make_ping_frame(std::int32_t service);
+
+// 事件帧的 ACK:原样回显收到的帧(SeqID/LogID/service/method/payload_encoding/payload_type/
+// LogIDNew 与全部 header),末尾追加 biz_rt,payload 换成应答 JSON(如 {"code":200})。
+Frame make_ack_frame(const Frame& received, std::int64_t biz_rt_ms, const std::string& response_json);
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_gateway.cpp b/src/adapters/im/feishu/feishu_gateway.cpp
new file mode 100644
index 000000000..fdf78f2b5
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_gateway.cpp
@@ -0,0 +1,172 @@
+#include "im/feishu/feishu_gateway.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+namespace acecode::im::feishu {
+namespace {
+
+// 十进制非负整数;非法返回 -1。
+long long parse_count(const std::string& text) {
+    if (text.empty() || text.size() > 9) return -1;
+    long long value = 0;
+    for (const char c : text) {
+        if (c < '0' || c > '9') return -1;
+        value = value * 10 + (c - '0');
+    }
+    return value;
+}
+
+const char* kAckOk = R"({"code":200})";
+
+} // namespace
+
+void LinkSession::on_connected(std::int32_t service_id, Clock::time_point now) {
+    service_ = service_id;
+    connected_ = true;
+    next_ping_ = now;
+    last_receive_ = now;
+    pending_.clear();
+}
+
+void LinkSession::on_disconnected() {
+    connected_ = false;
+    pending_.clear();
+}
+
+std::chrono::milliseconds LinkSession::ping_interval() const {
+    return std::chrono::seconds(std::max(1, config_.ping_interval_s));
+}
+
+std::chrono::milliseconds LinkSession::read_timeout() const { return ping_interval() * 2 + limits_.read_grace; }
+
+void LinkSession::sweep(Clock::time_point now) {
+    for (auto it = pending_.begin(); it != pending_.end();) {
+        if (it->second.expires <= now) it = pending_.erase(it);
+        else ++it;
+    }
+}
+
+std::optional<std::string> LinkSession::reassemble(const std::string& id, std::size_t sum, std::size_t seq,
+                                                   std::string payload, Clock::time_point now,
+                                                   std::string* warning) {
+    auto found = pending_.find(id);
+    if (found == pending_.end()) {
+        if (!pending_.empty() && pending_.size() >= limits_.max_pending) {
+            // 丢掉最快过期的那组,给新消息腾位置。
+            auto oldest = std::min_element(pending_.begin(), pending_.end(), [](const auto& a, const auto& b) {
+                return a.second.expires < b.second.expires;
+            });
+            pending_.erase(oldest);
+            if (warning) *warning = "dropped an incomplete split message to bound the cache";
+        }
+        Pending fresh;
+        fresh.parts.resize(sum);
+        found = pending_.emplace(id, std::move(fresh)).first;
+    }
+    auto& entry = found->second;
+    if (entry.parts.size() != sum) {
+        pending_.erase(found);
+        if (warning) *warning = "split message part count changed";
+        return std::nullopt;
+    }
+    if (entry.parts[seq]) entry.bytes -= entry.parts[seq]->size();
+    entry.bytes += payload.size();
+    if (entry.bytes > limits_.max_total_bytes) {
+        pending_.erase(found);
+        if (warning) *warning = "split message exceeds the size limit";
+        return std::nullopt;
+    }
+    entry.parts[seq] = std::move(payload);
+    entry.expires = now + limits_.part_ttl;
+    for (const auto& part : entry.parts) {
+        if (!part) return std::nullopt;
+    }
+    std::string combined;
+    combined.reserve(entry.bytes);
+    for (const auto& part : entry.parts) combined += *part;
+    pending_.erase(found);
+    return combined;
+}
+
+LinkSession::Output LinkSession::on_message(const std::string& bytes, Clock::time_point now) {
+    Output out;
+    last_receive_ = now;
+    sweep(now);
+    Frame frame;
+    std::string error;
+    if (!decode_frame(bytes, &frame, &error)) {
+        out.warning = "undecodable frame: " + error;
+        return out;
+    }
+    const auto type = frame.header("type");
+    if (frame.method == kMethodControl) {
+        if (type == "pong" && frame.payload && !frame.payload->empty()) {
+            try {
+                out.config_updated = apply_client_config(nlohmann::json::parse(*frame.payload), &config_);
+            } catch (...) {
+                out.warning = "pong carried an invalid ClientConfig";
+            }
+        }
+        return out;  // 服务端 ping 不回应
+    }
+    if (frame.method != kMethodData || type != "event") return out;  // card 等:不回应
+
+    const auto sum_text = frame.header("sum");
+    const auto seq_text = frame.header("seq");
+    const long long sum = sum_text.empty() ? 1 : parse_count(sum_text);
+    const long long seq = seq_text.empty() ? 0 : parse_count(seq_text);
+    if (sum < 1 || seq < 0 || seq >= sum || static_cast<std::size_t>(sum) > limits_.max_parts) {
+        out.warning = "invalid split header sum=" + sum_text + " seq=" + seq_text;
+        return out;
+    }
+    std::string payload = frame.payload ? *frame.payload : std::string{};
+    if (sum > 1) {
+        auto combined = reassemble(frame.header("message_id"), static_cast<std::size_t>(sum),
+                                   static_cast<std::size_t>(seq), std::move(payload), now, &out.warning);
+        if (!combined) return out;  // 还没凑齐:非最后一片不回应
+        payload = std::move(*combined);
+    }
+    // 先 ACK 再处理:3 秒期限只覆盖 ACK,处理放到调用方。
+    out.frames.push_back(encode_frame(make_ack_frame(frame, 0, kAckOk)));
+    out.events.push_back(std::move(payload));
+    return out;
+}
+
+LinkSession::Tick LinkSession::on_tick(Clock::time_point now) {
+    Tick tick;
+    if (!connected_) return tick;
+    if (now - last_receive_ >= read_timeout()) {
+        tick.dead = true;
+        return tick;
+    }
+    if (now >= next_ping_) {
+        tick.ping = encode_frame(make_ping_frame(service_));
+        next_ping_ = now + ping_interval();
+    }
+    sweep(now);
+    return tick;
+}
+
+std::chrono::milliseconds reconnect_delay(const ClientConfig& config, bool server_config, std::size_t failures,
+                                          const std::vector<std::chrono::milliseconds>& backoff, double jitter) {
+    const auto ours = backoff.empty() ? std::chrono::milliseconds(1000)
+                                      : backoff[std::min(failures, backoff.size() - 1)];
+    if (!server_config) return ours;
+    std::chrono::milliseconds server{0};
+    if (failures == 0) {
+        const double fraction = std::clamp(jitter, 0.0, 1.0);
+        server = std::chrono::milliseconds(
+            static_cast<long long>(std::llround(fraction * static_cast<double>(config.reconnect_nonce_s) * 1000.0)));
+    } else {
+        server = std::chrono::seconds(config.reconnect_interval_s);
+    }
+    return std::max(ours, server);
+}
+
+bool reconnect_exhausted(const ClientConfig& config, bool server_config, std::size_t failures) {
+    return server_config && config.reconnect_count >= 0 &&
+           failures >= static_cast<std::size_t>(config.reconnect_count);
+}
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_gateway.hpp b/src/adapters/im/feishu/feishu_gateway.hpp
new file mode 100644
index 000000000..2dedcf2b7
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_gateway.hpp
@@ -0,0 +1,97 @@
+#pragma once
+
+// 飞书长连接会话状态机(纯逻辑,不做 IO)。
+// 输入:收到的二进制帧、时间推进;输出:要立刻发送的帧(事件 ACK、心跳)、重组好的事件
+// JSON、是否判定连接假死。另外提供重连等待时长的计算(服务端参数 + 本地退避)。
+//
+// 规则(官方 Go / Python SDK):
+//   - 连上后立刻发一次心跳,之后每 PingInterval 秒一次;
+//   - 任何帧都会刷新读超时;超过 2 × PingInterval + 5 秒没有收到任何帧即判定假死(NAT 断开、
+//     休眠唤醒后 read 会永远阻塞,而心跳写入照样“成功”);
+//   - CONTROL pong 若带 payload,是新的 ClientConfig,立即生效;服务端 ping 不回;
+//   - DATA type=event 每帧都 ACK {"code":200}(包括我们不处理的事件类型),拆包的只对
+//     凑齐最后一片的那一帧 ACK;type=card(旧版卡片回调)不回应直接丢弃。
+
+#include "im/feishu/feishu_frame.hpp"
+#include "im/feishu/feishu_protocol.hpp"
+
+#include <chrono>
+#include <cstdint>
+#include <map>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace acecode::im::feishu {
+
+class LinkSession {
+public:
+    using Clock = std::chrono::steady_clock;
+
+    struct Limits {
+        std::chrono::milliseconds read_grace{std::chrono::seconds(5)};  // 读超时 = 2 × 心跳间隔 + grace
+        std::chrono::milliseconds part_ttl{std::chrono::seconds(5)};    // 拆包缓存的存活时间(每片刷新)
+        std::size_t max_parts = 64;            // 单条消息最多拆成几片
+        std::size_t max_pending = 32;          // 同时在重组的消息数
+        std::size_t max_total_bytes = 16u * 1024u * 1024u;  // 单条消息重组后的上限
+    };
+
+    struct Output {
+        std::vector<std::string> frames;  // 立即发送的二进制帧(事件 ACK)
+        std::vector<std::string> events;  // 完整的事件 JSON,按到达顺序
+        bool config_updated = false;      // pong 带来了新的 ClientConfig
+        std::string warning;              // 帧损坏等,只写日志(英文,不含正文)
+    };
+
+    struct Tick {
+        std::optional<std::string> ping;  // 到期要发的心跳帧
+        bool dead = false;                // 超过读超时没有收到任何帧
+    };
+
+    LinkSession() = default;
+    explicit LinkSession(Limits limits) : limits_(limits) {}
+
+    void set_config(const ClientConfig& config) { config_ = config; }
+    const ClientConfig& config() const { return config_; }
+
+    // WebSocket 握手成功后调用:立即安排一次心跳,重置读超时与拆包缓存。
+    void on_connected(std::int32_t service_id, Clock::time_point now);
+    void on_disconnected();
+    Output on_message(const std::string& bytes, Clock::time_point now);
+    Tick on_tick(Clock::time_point now);
+
+    std::chrono::milliseconds ping_interval() const;
+    std::chrono::milliseconds read_timeout() const;
+    std::size_t pending_sets() const { return pending_.size(); }
+
+private:
+    struct Pending {
+        std::vector<std::optional<std::string>> parts;
+        std::size_t bytes = 0;
+        Clock::time_point expires{};
+    };
+
+    std::optional<std::string> reassemble(const std::string& id, std::size_t sum, std::size_t seq,
+                                          std::string payload, Clock::time_point now, std::string* warning);
+    void sweep(Clock::time_point now);
+
+    Limits limits_;
+    ClientConfig config_;
+    std::int32_t service_ = 0;
+    bool connected_ = false;
+    Clock::time_point next_ping_{};
+    Clock::time_point last_receive_{};
+    std::map<std::string, Pending> pending_;
+};
+
+// 下一次连接前的等待。failures = 自上次成功连接以来连续失败的次数(刚掉线、还没重试时为 0)。
+//   - 还没拿到过服务端参数(server_config=false):只用本地退避 backoff[failures];
+//   - 刚掉线(failures == 0):在 [0, ReconnectNonce] 秒里随机抖动(jitter ∈ [0,1)),与本地退避取大;
+//   - 之后每次:ReconnectInterval 秒,与本地退避取大(服务端参数优先,SDK 注释明确要求)。
+std::chrono::milliseconds reconnect_delay(const ClientConfig& config, bool server_config, std::size_t failures,
+                                          const std::vector<std::chrono::milliseconds>& backoff, double jitter);
+
+// ReconnectCount >= 0 时,连续失败达到该次数后停止重连(-1 = 无限)。
+bool reconnect_exhausted(const ClientConfig& config, bool server_config, std::size_t failures);
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_inbound.cpp b/src/adapters/im/feishu/feishu_inbound.cpp
new file mode 100644
index 000000000..7262f6a17
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_inbound.cpp
@@ -0,0 +1,457 @@
+#include "im/feishu/feishu_protocol.hpp"
+
+#include "im/feishu/feishu_text_util.hpp"
+
+#include <algorithm>
+#include <map>
+
+namespace acecode::im::feishu {
+
+using namespace detail;
+
+namespace {
+
+// ---------------------------------------------------------------- 文本清理
+
+bool is_self_mention(const Mention& mention, const BotIdentity& bot) {
+    if (mention.key == "@_all") return false;
+    if (!bot.open_id.empty() && !mention.open_id.empty()) return mention.open_id == bot.open_id;
+    if (!bot.name.empty() && !mention.name.empty()) return mention.name == bot.name;
+    return bot.open_id.empty() && mention.mentioned_type == "bot";
+}
+
+enum class TokenKind { Text, Self, Other, All };
+
+struct Token {
+    TokenKind kind = TokenKind::Text;
+    std::string text;
+};
+
+// 只由空白与句末标点组成(含全角)。空串返回 true。
+bool is_tail_only(std::string_view text) {
+    static const char* const kWide[] = {"\xE3\x80\x82", "\xEF\xBC\x8C", "\xEF\xBC\x81", "\xEF\xBC\x9F",
+                                        "\xEF\xBC\x9B", "\xEF\xBC\x9A", "\xE3\x80\x81", "\xE2\x80\xA6"};
+    std::size_t i = 0;
+    while (i < text.size()) {
+        const char c = text[i];
+        if (is_space(c) || c == '.' || c == ',' || c == '!' || c == '?' || c == ';' || c == ':') {
+            ++i;
+            continue;
+        }
+        bool matched = false;
+        for (const char* wide : kWide) {
+            if (text.compare(i, 3, wide) == 0) {
+                i += 3;
+                matched = true;
+                break;
+            }
+        }
+        if (!matched) return false;
+    }
+    return true;
+}
+
+void ltrim_in_place(std::string& text) {
+    std::size_t i = 0;
+    while (i < text.size() && is_space(text[i])) ++i;
+    text.erase(0, i);
+}
+
+void rtrim_in_place(std::string& text) {
+    while (!text.empty() && is_space(text.back())) text.pop_back();
+}
+
+// 开头去掉机器人 @ 之后,顺手去掉紧跟的逗号 / 冒号("@Bot, 帮我…")。
+void drop_leading_separator(std::string& text) {
+    ltrim_in_place(text);
+    for (const char* sep : {",", ":", "\xEF\xBC\x8C", "\xEF\xBC\x9A"}) {
+        if (starts_with(text, sep)) {
+            text.erase(0, std::char_traits<char>::length(sep));
+            ltrim_in_place(text);
+            return;
+        }
+    }
+}
+
+std::string normalize_lines(const std::string& text) {
+    std::string unified;
+    unified.reserve(text.size());
+    for (std::size_t i = 0; i < text.size(); ++i) {
+        if (text[i] == '\r') {
+            unified.push_back('\n');
+            if (i + 1 < text.size() && text[i + 1] == '\n') ++i;
+        } else {
+            unified.push_back(text[i]);
+        }
+    }
+    std::string out;
+    out.reserve(unified.size());
+    std::size_t start = 0;
+    while (start <= unified.size()) {
+        const auto end = unified.find('\n', start);
+        std::string line = unified.substr(start, end == std::string::npos ? std::string::npos : end - start);
+        while (!line.empty() && (line.back() == ' ' || line.back() == '\t')) line.pop_back();
+        out += line;
+        if (end == std::string::npos) break;
+        out.push_back('\n');
+        start = end + 1;
+    }
+    return trim(out);
+}
+
+// ---------------------------------------------------------------- 内容提取
+
+const nlohmann::json* resolve_post(const nlohmann::json& content, int depth = 0) {
+    if (depth > 4 || !content.is_object()) return nullptr;
+    if (content.contains("content") && content["content"].is_array()) return &content;
+    if (content.contains("post")) {
+        if (const auto* inner = resolve_post(content["post"], depth + 1)) return inner;
+    }
+    for (const char* locale : {"zh_cn", "en_us", "ja_jp"}) {
+        if (content.contains(locale)) {
+            if (const auto* inner = resolve_post(content[locale], depth + 1)) return inner;
+        }
+    }
+    for (const auto& item : content.items()) {
+        if (item.value().is_object() && item.value().contains("content") && item.value()["content"].is_array())
+            return &item.value();
+    }
+    return nullptr;
+}
+
+Attachment resource_attachment(AttachmentKind kind, const std::string& message_id, const std::string& key,
+                               const std::string& type, const std::string& name, const std::string& mime) {
+    Attachment attachment;
+    attachment.kind = kind;
+    attachment.name = name;
+    attachment.mime_type = mime;
+    attachment.remote_ref = make_resource_ref(message_id, key, type);
+    return attachment;
+}
+
+void render_post(const nlohmann::json& content, const std::string& message_id, ExtractedContent& out) {
+    const auto* post = resolve_post(content);
+    if (!post) {
+        out.text = "[富文本消息]";
+        return;
+    }
+    const auto title = trim(string_field(*post, "title"));
+    std::vector<std::string> lines;
+    for (const auto& row : (*post)["content"]) {
+        if (!row.is_array()) continue;
+        std::string line;
+        for (const auto& node : row) {
+            if (!node.is_object()) continue;
+            const auto tag = string_field(node, "tag");
+            const auto text = string_field(node, "text");
+            if (tag == "text") {
+                line += text;
+            } else if (tag == "a") {
+                const auto href = string_field(node, "href");
+                line += href.empty() ? text : "[" + (text.empty() ? href : text) + "](" + href + ")";
+            } else if (tag == "at") {
+                const auto user = string_field(node, "user_id");
+                if (starts_with(user, "@_")) {
+                    line += user;  // 占位符交给 clean_text 统一处理
+                } else {
+                    const auto name = string_field(node, "user_name");
+                    line += "@" + (name.empty() ? user : name);
+                }
+            } else if (tag == "img") {
+                const auto key = string_field(node, "image_key");
+                if (!key.empty())
+                    out.attachments.push_back(resource_attachment(AttachmentKind::Image, message_id, key, "image", {}, {}));
+            } else if (tag == "media") {
+                const auto key = string_field(node, "file_key");
+                if (!key.empty())
+                    out.attachments.push_back(resource_attachment(AttachmentKind::Video, message_id, key, "file",
+                                                                  string_field(node, "file_name"), {}));
+            } else if (tag == "emotion") {
+                line += "[" + string_field(node, "emoji_type") + "]";
+            } else if (tag == "hr") {
+                line += "---";
+            } else if (tag == "code_block") {
+                line += "```" + lower(string_field(node, "language")) + "\n" + text +
+                        (ends_with(text, "\n") ? "" : "\n") + "```";
+            } else {
+                line += text;  // md 及未知但带 text 的节点
+            }
+        }
+        if (!trim(line).empty()) lines.push_back(std::move(line));
+    }
+    std::string body;
+    for (std::size_t i = 0; i < lines.size(); ++i) {
+        if (i) body.push_back('\n');
+        body += lines[i];
+    }
+    if (title.empty()) out.text = body;
+    else out.text = body.empty() ? title : title + "\n" + body;
+}
+
+void collect_card_text(const nlohmann::json& value, std::vector<std::string>& out, int depth) {
+    if (depth > 32) return;
+    if (value.is_object()) {
+        // nlohmann 的对象按键名排序遍历;标题要排在正文前面,单独先取。
+        if (value.contains("title") && value["title"].is_string()) {
+            const auto title = trim(value["title"].get<std::string>());
+            if (!title.empty() && (out.empty() || out.back() != title)) out.push_back(title);
+        }
+        for (const auto& item : value.items()) {
+            const auto& key = item.key();
+            const auto& field = item.value();
+            if (key == "title" && field.is_string()) continue;
+            if ((key == "text" || key == "content") && field.is_string()) {
+                const auto text = trim(field.get<std::string>());
+                if (!text.empty() && (out.empty() || out.back() != text)) out.push_back(text);
+            } else if (field.is_structured()) {
+                collect_card_text(field, out, depth + 1);
+            }
+        }
+    } else if (value.is_array()) {
+        for (const auto& item : value) collect_card_text(item, out, depth + 1);
+    }
+}
+
+} // namespace
+
+std::vector<Mention> parse_mentions(const nlohmann::json& mentions) {
+    std::vector<Mention> out;
+    if (!mentions.is_array()) return out;
+    for (const auto& raw : mentions) {
+        if (!raw.is_object()) continue;
+        Mention mention;
+        mention.key = string_field(raw, "key");
+        mention.name = string_field(raw, "name");
+        mention.mentioned_type = string_field(raw, "mentioned_type");
+        if (raw.contains("id") && raw["id"].is_object()) {
+            mention.open_id = string_field(raw["id"], "open_id");
+            mention.user_id = string_field(raw["id"], "user_id");
+        } else if (raw.contains("id") && raw["id"].is_string()) {
+            // GET message 返回的 mentions:id 是字符串,类型在 id_type 里。
+            const auto type = string_field(raw, "id_type");
+            if (type == "open_id") mention.open_id = raw["id"].get<std::string>();
+            else if (type == "user_id") mention.user_id = raw["id"].get<std::string>();
+        }
+        out.push_back(std::move(mention));
+    }
+    return out;
+}
+
+bool mentions_bot(const std::vector<Mention>& mentions, const BotIdentity& bot) {
+    return std::any_of(mentions.begin(), mentions.end(),
+                       [&bot](const Mention& mention) { return is_self_mention(mention, bot); });
+}
+
+std::string clean_text(const std::string& raw, const std::vector<Mention>& mentions, const BotIdentity& bot) {
+    std::map<std::string, const Mention*> by_key;
+    for (const auto& mention : mentions) {
+        if (!mention.key.empty()) by_key.emplace(mention.key, &mention);
+    }
+    const auto self_label = [&bot](const Mention& mention) {
+        return "@" + (!bot.name.empty() ? bot.name : !mention.name.empty() ? mention.name : std::string("机器人"));
+    };
+
+    std::vector<Token> tokens;
+    const auto add_text = [&tokens](std::string_view piece) {
+        if (!tokens.empty() && tokens.back().kind == TokenKind::Text) tokens.back().text.append(piece);
+        else tokens.push_back({TokenKind::Text, std::string(piece)});
+    };
+    std::size_t i = 0;
+    while (i < raw.size()) {
+        if (raw.compare(i, 7, "@_user_") == 0 && i + 7 < raw.size() && is_digit(raw[i + 7])) {
+            std::size_t j = i + 7;
+            while (j < raw.size() && is_digit(raw[j])) ++j;
+            const auto found = by_key.find(raw.substr(i, j - i));
+            if (found == by_key.end()) {
+                add_text(" ");
+            } else if (is_self_mention(*found->second, bot)) {
+                tokens.push_back({TokenKind::Self, self_label(*found->second)});
+            } else {
+                const auto& m = *found->second;
+                tokens.push_back({TokenKind::Other,
+                                  "@" + (!m.name.empty() ? m.name : !m.open_id.empty() ? m.open_id : std::string("用户"))});
+            }
+            i = j;
+            continue;
+        }
+        if (raw.compare(i, 5, "@_all") == 0 && (i + 5 == raw.size() || !word_char(raw[i + 5]))) {
+            tokens.push_back({TokenKind::All, "@all"});
+            i += 5;
+            continue;
+        }
+        add_text(std::string_view(raw).substr(i, 1));
+        ++i;
+    }
+
+    // 开头的 @机器人(可以连着好几个)整体去掉。
+    bool stripped_lead = false;
+    while (!tokens.empty()) {
+        const auto& front = tokens.front();
+        if (front.kind == TokenKind::Self) {
+            stripped_lead = true;
+        } else if (!(front.kind == TokenKind::Text && trim(front.text).empty())) {
+            break;
+        }
+        tokens.erase(tokens.begin());
+    }
+    if (stripped_lead && !tokens.empty() && tokens.front().kind == TokenKind::Text)
+        drop_leading_separator(tokens.front().text);
+
+    // 结尾的 @机器人 只在其后只剩空白 / 句末标点时去掉;句中的保留("别再 @机器人 了")。
+    while (true) {
+        std::ptrdiff_t k = static_cast<std::ptrdiff_t>(tokens.size()) - 1;
+        while (k >= 0 && tokens[static_cast<std::size_t>(k)].kind == TokenKind::Text &&
+               is_tail_only(tokens[static_cast<std::size_t>(k)].text))
+            --k;
+        if (k < 0 || tokens[static_cast<std::size_t>(k)].kind != TokenKind::Self) break;
+        tokens.erase(tokens.begin() + k);
+        if (k > 0 && tokens[static_cast<std::size_t>(k - 1)].kind == TokenKind::Text)
+            rtrim_in_place(tokens[static_cast<std::size_t>(k - 1)].text);
+    }
+
+    std::string joined;
+    for (const auto& token : tokens) joined += token.text;
+    return normalize_lines(joined);
+}
+
+ExtractedContent extract_content(const std::string& message_type, const nlohmann::json& content,
+                                 const std::string& message_id) {
+    ExtractedContent out;
+    if (message_type == "text") {
+        out.text = string_field(content, "text");
+    } else if (message_type == "post") {
+        render_post(content, message_id, out);
+    } else if (message_type == "image") {
+        const auto key = string_field(content, "image_key");
+        if (!key.empty())
+            out.attachments.push_back(resource_attachment(AttachmentKind::Image, message_id, key, "image", {}, {}));
+    } else if (message_type == "file") {
+        const auto key = string_field(content, "file_key");
+        if (!key.empty())
+            out.attachments.push_back(resource_attachment(AttachmentKind::File, message_id, key, "file",
+                                                          string_field(content, "file_name"), {}));
+    } else if (message_type == "audio") {
+        const auto key = string_field(content, "file_key");
+        if (!key.empty())
+            out.attachments.push_back(
+                resource_attachment(AttachmentKind::Voice, message_id, key, "file", "voice.opus", "audio/opus"));
+    } else if (message_type == "media") {
+        const auto key = string_field(content, "file_key");
+        if (!key.empty())
+            out.attachments.push_back(resource_attachment(AttachmentKind::Video, message_id, key, "file",
+                                                          string_field(content, "file_name"), {}));
+    } else if (message_type == "sticker") {
+        out.text = "[表情]";
+    } else if (message_type == "folder") {
+        const auto name = string_field(content, "file_name");
+        out.text = "[文件夹" + (name.empty() ? std::string{} : ":" + name) + "](机器人无法下载文件夹)";
+    } else if (message_type == "interactive") {
+        std::vector<std::string> parts;
+        collect_card_text(content, parts, 0);
+        for (std::size_t i = 0; i < parts.size(); ++i) {
+            if (i) out.text.push_back('\n');
+            out.text += parts[i];
+        }
+        if (out.text.empty()) out.text = "[卡片消息]";
+    } else if (message_type == "share_chat") {
+        out.text = "[分享的群聊]";
+    } else if (message_type == "share_user") {
+        out.text = "[分享的名片]";
+    } else if (message_type == "merge_forward") {
+        out.text = "[合并转发的聊天记录]";
+    } else if (message_type == "location") {
+        const auto name = string_field(content, "name");
+        out.text = "[位置]" + (name.empty() ? std::string{} : " " + name);
+    } else if (message_type == "hongbao") {
+        out.text = "[红包]";
+    } else {
+        out.text = "[" + (message_type.empty() ? std::string("未知") : message_type) + " 消息]";
+    }
+    return out;
+}
+
+ParsedEvent parse_event(const std::string& payload, const BotIdentity& bot, const std::string& account,
+                        std::int64_t now_epoch_ms) {
+    ParsedEvent parsed;
+    nlohmann::json root;
+    try {
+        root = nlohmann::json::parse(payload);
+    } catch (...) {
+        parsed.disposition = EventDisposition::Invalid;
+        return parsed;
+    }
+    if (!root.is_object()) {
+        parsed.disposition = EventDisposition::Invalid;
+        return parsed;
+    }
+    const auto& header = object_field(root, "header");
+    parsed.event_type = string_field(header, "event_type");
+    // 1.0 事件(没有 schema 2.0)只有在用户额外订阅了旧版事件时才会出现,一律忽略。
+    if (string_field(root, "schema") != "2.0" || parsed.event_type != "im.message.receive_v1") return parsed;
+
+    const auto& event = object_field(root, "event");
+    const auto& sender = object_field(event, "sender");
+    const auto& message = object_field(event, "message");
+    parsed.message_id = string_field(message, "message_id");
+    const auto open_id = string_field(object_field(sender, "sender_id"), "open_id");
+    const auto sender_type = string_field(sender, "sender_type");
+    if (parsed.message_id.empty() || open_id.empty()) {
+        parsed.disposition = EventDisposition::Invalid;
+        return parsed;
+    }
+    if ((!sender_type.empty() && sender_type != "user") || (!bot.open_id.empty() && open_id == bot.open_id)) {
+        parsed.disposition = EventDisposition::FromBot;
+        return parsed;
+    }
+    const auto created = int_field(message, "create_time", 0);
+    if (created > 0 && now_epoch_ms - created > kStaleEventMs) {
+        parsed.disposition = EventDisposition::Stale;
+        return parsed;
+    }
+
+    const auto chat_type = string_field(message, "chat_type");
+    const auto chat_id = string_field(message, "chat_id");
+    Inbound inbound;
+    inbound.message_id = parsed.message_id;
+    inbound.address.platform = kPlatform;
+    inbound.address.account = account;
+    if (chat_type == "p2p") {
+        inbound.address.kind = ChatKind::Private;
+        inbound.address.chat = inbound.address.sender = open_id;
+    } else {
+        inbound.address.kind = ChatKind::Group;
+        inbound.address.chat = chat_id;
+        inbound.address.sender = open_id;
+    }
+    if (!inbound.address.valid()) {
+        parsed.disposition = EventDisposition::Invalid;
+        return parsed;
+    }
+
+    const auto mentions = parse_mentions(message.contains("mentions") ? message["mentions"] : nlohmann::json());
+    nlohmann::json content = nlohmann::json::object();
+    const auto raw_content = string_field(message, "content");
+    if (!raw_content.empty()) {
+        try {
+            content = nlohmann::json::parse(raw_content);
+        } catch (...) {
+            content = nlohmann::json::object();
+        }
+    }
+    auto extracted = extract_content(string_field(message, "message_type"), content, parsed.message_id);
+    inbound.text = clean_text(extracted.text, mentions, bot);
+    inbound.attachments = std::move(extracted.attachments);
+    inbound.mentioned = inbound.address.kind == ChatKind::Private || mentions_bot(mentions, bot);
+    if (inbound.text.empty() && inbound.attachments.empty()) {
+        parsed.disposition = EventDisposition::Empty;
+        return parsed;
+    }
+    inbound.reply_context = {{"message_id", parsed.message_id}, {"chat_id", chat_id}, {"chat_type", chat_type}};
+    const auto thread_id = string_field(message, "thread_id");
+    if (!thread_id.empty()) inbound.reply_context["thread_id"] = thread_id;
+    parsed.inbound = std::move(inbound);
+    parsed.disposition = EventDisposition::Message;
+    return parsed;
+}
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_outbound.cpp b/src/adapters/im/feishu/feishu_outbound.cpp
new file mode 100644
index 000000000..72abf048d
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_outbound.cpp
@@ -0,0 +1,193 @@
+#include "im/feishu/feishu_protocol.hpp"
+
+#include "im/feishu/feishu_text_util.hpp"
+#include "im/text_chunk.hpp"
+
+#include <algorithm>
+
+namespace acecode::im::feishu {
+
+using namespace detail;
+
+namespace {
+
+// ---------------------------------------------------------------- Markdown 判定
+
+bool line_is_heading(std::string_view line) {
+    std::size_t i = 0;
+    while (i < line.size() && line[i] == '#') ++i;
+    return i >= 1 && i <= 6 && i < line.size() && (line[i] == ' ' || line[i] == '\t');
+}
+
+std::string_view ltrim_view(std::string_view line) {
+    std::size_t i = 0;
+    while (i < line.size() && (line[i] == ' ' || line[i] == '\t')) ++i;
+    return line.substr(i);
+}
+
+bool line_is_list(std::string_view line) {
+    const auto rest = ltrim_view(line);
+    if (rest.size() >= 2 && (rest[0] == '-' || rest[0] == '*') && (rest[1] == ' ' || rest[1] == '\t')) return true;
+    std::size_t i = 0;
+    while (i < rest.size() && is_digit(rest[i])) ++i;
+    return i >= 1 && i + 1 < rest.size() && rest[i] == '.' && (rest[i + 1] == ' ' || rest[i + 1] == '\t');
+}
+
+bool line_is_rule(std::string_view line) {
+    const auto text = trim(line);
+    return text.size() >= 3 && text.find_first_not_of('-') == std::string::npos;
+}
+
+bool line_is_quote(std::string_view line) {
+    return !line.empty() && line[0] == '>' && (line.size() == 1 || line[1] == ' ' || line[1] == '\t');
+}
+
+bool line_is_table_separator(std::string_view line) {
+    if (line.size() < 2 || line[0] != '|') return false;
+    bool dash = false;
+    for (const char c : line) {
+        if (c == '-') dash = true;
+        else if (c != ':' && c != '|' && c != ' ' && c != '\t') return false;
+    }
+    return dash && trim(line).back() == '|';
+}
+
+// 同一行内成对出现的标记(如 **x**):开标记后的第一个字符不能还是标记字符,
+// 两个标记之间至少 min_inner 个字符。
+bool paired_inline(std::string_view line, std::string_view marker, std::size_t min_inner) {
+    std::size_t pos = 0;
+    while ((pos = line.find(marker, pos)) != std::string_view::npos) {
+        const auto inner = pos + marker.size();
+        if (inner < line.size() && line[inner] != marker[0] &&
+            line.find(marker, inner + min_inner) != std::string_view::npos)
+            return true;
+        pos = inner;
+    }
+    return false;
+}
+
+bool has_inline_markdown(std::string_view line) {
+    // `code`
+    for (std::size_t pos = line.find('`'); pos != std::string_view::npos; pos = line.find('`', pos + 1)) {
+        const auto end = line.find('`', pos + 1);
+        if (end != std::string_view::npos && end > pos + 1) return true;
+    }
+    if (paired_inline(line, "**", 2)) return true;   // **bold**(内部至少 2 个字符)
+    if (paired_inline(line, "~~", 2)) return true;   // ~~strike~~
+    {
+        const auto open = line.find("<u>");
+        if (open != std::string_view::npos && line.find("</u>", open + 4) != std::string_view::npos) return true;
+    }
+    // *italic*:单星号之间至少一个非星号字符
+    for (std::size_t pos = line.find('*'); pos != std::string_view::npos; pos = line.find('*', pos + 1)) {
+        std::size_t k = pos + 1;
+        while (k < line.size() && line[k] != '*') ++k;
+        if (k < line.size() && k > pos + 1) return true;
+    }
+    // [text](url)
+    for (std::size_t pos = line.find('['); pos != std::string_view::npos; pos = line.find('[', pos + 1)) {
+        const auto close = line.find("](", pos + 1);
+        if (close == std::string_view::npos || close == pos + 1) continue;
+        if (line.substr(pos + 1, close - pos - 1).find(']') != std::string_view::npos) continue;
+        const auto end = line.find(')', close + 2);
+        if (end != std::string_view::npos && end > close + 2) return true;
+    }
+    return false;
+}
+
+std::vector<std::string_view> split_lines_view(std::string_view text) {
+    std::vector<std::string_view> lines;
+    std::size_t start = 0;
+    while (start <= text.size()) {
+        const auto end = text.find('\n', start);
+        auto line = text.substr(start, end == std::string_view::npos ? std::string_view::npos : end - start);
+        if (!line.empty() && line.back() == '\r') line.remove_suffix(1);
+        lines.push_back(line);
+        if (end == std::string_view::npos) break;
+        start = end + 1;
+    }
+    return lines;
+}
+
+nlohmann::json md_row(const std::string& text) {
+    return nlohmann::json::array({nlohmann::json{{"tag", "md"}, {"text", text}}});
+}
+
+std::size_t content_bytes(const std::string& chunk, bool markdown) {
+    return dump_json(markdown ? build_post_content(chunk) : build_text_content(chunk)).size();
+}
+
+void split_into(const std::string& text, bool markdown, std::size_t max_chars, std::size_t max_bytes,
+                std::vector<std::string>& out) {
+    for (auto& chunk : chunk_text(text, max_chars, false)) {
+        if (max_chars > 64 && content_bytes(chunk, markdown) > max_bytes) {
+            split_into(chunk, markdown, max_chars / 2, max_bytes, out);
+        } else {
+            out.push_back(std::move(chunk));
+        }
+    }
+}
+
+} // namespace
+
+bool looks_like_markdown(std::string_view text) {
+    if (text.find("```") != std::string_view::npos) return true;
+    const auto lines = split_lines_view(text);
+    for (std::size_t i = 0; i < lines.size(); ++i) {
+        const auto line = lines[i];
+        if (line_is_heading(line) || line_is_list(line) || line_is_rule(line) || line_is_quote(line)) return true;
+        if (line.size() >= 2 && line[0] == '|' && trim(line).back() == '|' && i + 1 < lines.size() &&
+            line_is_table_separator(lines[i + 1]))
+            return true;
+        if (has_inline_markdown(line)) return true;
+    }
+    return false;
+}
+
+nlohmann::json build_post_content(const std::string& markdown) {
+    nlohmann::json rows = nlohmann::json::array();
+    if (markdown.find("```") == std::string::npos) {
+        rows.push_back(md_row(markdown));
+    } else {
+        std::vector<std::string> current;
+        bool in_code = false;
+        const auto flush = [&current, &rows] {
+            if (current.empty()) return;
+            std::string segment;
+            for (std::size_t i = 0; i < current.size(); ++i) {
+                if (i) segment.push_back('\n');
+                segment += current[i];
+            }
+            if (!trim(segment).empty()) rows.push_back(md_row(segment));
+            current.clear();
+        };
+        for (const auto line : split_lines_view(markdown)) {
+            const auto stripped = trim(line);
+            const bool fence = in_code ? stripped == "```"
+                                       : starts_with(stripped, "```") &&
+                                             stripped.find('`', 3) == std::string::npos;
+            if (fence) {
+                if (!in_code) flush();
+                current.emplace_back(line);
+                in_code = !in_code;
+                if (!in_code) flush();
+                continue;
+            }
+            current.emplace_back(line);
+        }
+        flush();
+        if (rows.empty()) rows.push_back(md_row(markdown));
+    }
+    return {{"zh_cn", {{"content", rows}}}};
+}
+
+nlohmann::json build_text_content(const std::string& text) { return {{"text", text}}; }
+
+std::vector<std::string> split_outbound(const std::string& text, bool markdown, std::size_t max_chars,
+                                        std::size_t max_bytes) {
+    std::vector<std::string> out;
+    split_into(text, markdown, max_chars, max_bytes, out);
+    return out;
+}
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_pacer.cpp b/src/adapters/im/feishu/feishu_pacer.cpp
new file mode 100644
index 000000000..3cdc84335
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_pacer.cpp
@@ -0,0 +1,41 @@
+#include "im/feishu/feishu_pacer.hpp"
+
+namespace acecode::im::feishu {
+namespace {
+
+// 记录太多接收方时清掉早已过期的条目,避免长期运行时无限增长。
+constexpr std::size_t kPruneThreshold = 1024;
+
+} // namespace
+
+void SendPacer::prune_locked(Clock::time_point now) {
+    if (next_allowed_.size() < kPruneThreshold) return;
+    for (auto it = next_allowed_.begin(); it != next_allowed_.end();) {
+        if (it->second <= now) it = next_allowed_.erase(it);
+        else ++it;
+    }
+}
+
+SendPacer::Clock::time_point SendPacer::reserve(const std::string& target, Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    prune_locked(now);
+    auto at = now;
+    const auto found = next_allowed_.find(target);
+    if (found != next_allowed_.end() && found->second > at) at = found->second;
+    next_allowed_[target] = at + gap_;
+    return at;
+}
+
+void SendPacer::penalize(const std::string& target, std::chrono::milliseconds wait, Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    auto& allowed = next_allowed_[target];
+    const auto until = now + wait;
+    if (allowed < until) allowed = until;
+}
+
+std::size_t SendPacer::tracked() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return next_allowed_.size();
+}
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_pacer.hpp b/src/adapters/im/feishu/feishu_pacer.hpp
new file mode 100644
index 000000000..aaededcf8
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_pacer.hpp
@@ -0,0 +1,34 @@
+#pragma once
+
+// 飞书发送节流(纯逻辑):同一接收方(群或用户)每秒最多 5 条,群内由所有机器人共享;
+// 这里按每个接收方相邻两条至少间隔 gap(默认 250 ms,即 ≤ 4 条/秒)预约发送时刻。
+// 被平台限流时 penalize,该接收方在等待期内不再预约。调用方先 reserve,睡到返回的时刻再发。
+
+#include <chrono>
+#include <map>
+#include <mutex>
+#include <string>
+
+namespace acecode::im::feishu {
+
+class SendPacer {
+public:
+    using Clock = std::chrono::steady_clock;
+
+    explicit SendPacer(std::chrono::milliseconds gap = std::chrono::milliseconds(250)) : gap_(gap) {}
+
+    // 预约一条消息的发送时刻;返回值不早于 now。预约即占用名额。
+    Clock::time_point reserve(const std::string& target, Clock::time_point now);
+    // 平台对该接收方限流:wait 之内不再预约到它。
+    void penalize(const std::string& target, std::chrono::milliseconds wait, Clock::time_point now);
+    std::size_t tracked() const;
+
+private:
+    void prune_locked(Clock::time_point now);
+
+    std::chrono::milliseconds gap_;
+    mutable std::mutex mu_;
+    std::map<std::string, Clock::time_point> next_allowed_;
+};
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_protocol.cpp b/src/adapters/im/feishu/feishu_protocol.cpp
new file mode 100644
index 000000000..58bb4a154
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_protocol.cpp
@@ -0,0 +1,397 @@
+#include "im/feishu/feishu_protocol.hpp"
+
+#include "im/feishu/feishu_text_util.hpp"
+
+#include <algorithm>
+#include <limits>
+
+namespace acecode::im::feishu {
+
+using namespace detail;
+
+namespace {
+
+int hex_value(char c) {
+    if (c >= '0' && c <= '9') return c - '0';
+    if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+    if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+    return -1;
+}
+
+std::string percent_decode(std::string_view text) {
+    std::string out;
+    out.reserve(text.size());
+    for (std::size_t i = 0; i < text.size(); ++i) {
+        if (text[i] == '%' && i + 2 < text.size()) {
+            const int hi = hex_value(text[i + 1]);
+            const int lo = hex_value(text[i + 2]);
+            if (hi >= 0 && lo >= 0) {
+                out.push_back(static_cast<char>(hi * 16 + lo));
+                i += 2;
+                continue;
+            }
+        }
+        out.push_back(text[i]);
+    }
+    return out;
+}
+
+std::string code_text(std::int64_t code) { return "(错误码 " + std::to_string(code) + ")"; }
+
+} // namespace
+
+std::string base_for_domain(const std::string& domain) {
+    const auto value = lower(trim(domain));
+    return value == kDomainLark || value == "larksuite" ? kLarkBase : kFeishuBase;
+}
+
+bool apply_client_config(const nlohmann::json& raw, ClientConfig* config) {
+    if (!raw.is_object() || !config) return false;
+    bool applied = false;
+    const auto read = [&raw](const char* key, std::int64_t* out) {
+        if (!raw.contains(key)) return false;
+        const auto& field = raw.at(key);
+        if (!field.is_number()) return false;
+        *out = field.is_number_float() ? static_cast<std::int64_t>(field.get<double>()) : field.get<std::int64_t>();
+        return true;
+    };
+    constexpr std::int64_t kMaxSeconds = 24 * 3600;
+    std::int64_t value = 0;
+    if (read("ReconnectCount", &value)) {
+        config->reconnect_count = static_cast<int>(std::clamp<std::int64_t>(value, -1, 1000000));
+        applied = true;
+    }
+    if (read("ReconnectInterval", &value) && value >= 0) {
+        config->reconnect_interval_s = static_cast<int>(std::min(value, kMaxSeconds));
+        applied = true;
+    }
+    if (read("ReconnectNonce", &value) && value >= 0) {
+        config->reconnect_nonce_s = static_cast<int>(std::min(value, kMaxSeconds));
+        applied = true;
+    }
+    if (read("PingInterval", &value) && value > 0) {
+        config->ping_interval_s = static_cast<int>(std::min(value, kMaxSeconds));
+        applied = true;
+    }
+    return applied;
+}
+
+std::string url_query_param(const std::string& url, const std::string& name) {
+    const auto question = url.find('?');
+    if (question == std::string::npos) return {};
+    auto query = std::string_view(url).substr(question + 1);
+    const auto hash = query.find('#');
+    if (hash != std::string_view::npos) query = query.substr(0, hash);
+    std::size_t start = 0;
+    while (start <= query.size()) {
+        const auto end = query.find('&', start);
+        const auto pair = query.substr(start, end == std::string_view::npos ? std::string_view::npos : end - start);
+        const auto eq = pair.find('=');
+        const auto key = percent_decode(pair.substr(0, eq));
+        if (key == name) return eq == std::string_view::npos ? std::string{} : percent_decode(pair.substr(eq + 1));
+        if (end == std::string_view::npos) break;
+        start = end + 1;
+    }
+    return {};
+}
+
+EndpointInfo parse_endpoint_response(long status, const std::string& body) {
+    EndpointInfo info;
+    info.status = status;
+    nlohmann::json json;
+    try {
+        json = nlohmann::json::parse(body);
+    } catch (...) {
+        json = nullptr;
+    }
+    const auto msg = json.is_object() ? string_field(json, "msg") : std::string{};
+    if (status != 200) {
+        info.message = "获取飞书长连接地址失败(HTTP " + std::to_string(status) + ")";
+        return info;
+    }
+    if (!json.is_object() || !json.contains("code")) {
+        info.message = "飞书长连接接口返回了无效的数据";
+        return info;
+    }
+    info.code = int_field(json, "code", -1);
+    if (info.code == 0) {
+        const auto& data = object_field(json, "data");
+        info.url = string_field(data, "URL");
+        if (data.contains("ClientConfig") && data["ClientConfig"].is_object()) info.client_config = data["ClientConfig"];
+        if (info.url.empty()) {
+            info.message = "飞书没有返回长连接地址";
+            return info;
+        }
+        info.device_id = url_query_param(info.url, "device_id");
+        const auto service = url_query_param(info.url, "service_id");
+        const auto parsed = int_field(nlohmann::json{{"v", service}}, "v", std::numeric_limits<std::int64_t>::min());
+        if (parsed < std::numeric_limits<std::int32_t>::min() || parsed > std::numeric_limits<std::int32_t>::max()) {
+            info.url.clear();
+            info.message = "飞书返回的长连接地址缺少 service_id";
+            return info;
+        }
+        info.service_id = static_cast<std::int32_t>(parsed);
+        info.ok = true;
+        return info;
+    }
+    if (info.code == 1 || info.code == 1000040343) {
+        info.message = "飞书长连接服务繁忙,稍后重试";
+        return info;
+    }
+    info.fatal = true;
+    if (info.code == 1000040345)
+        info.message = "App ID 或 App Secret 无效(也请确认选择的是飞书还是 Lark)";
+    else if (info.code == 1000040344)
+        info.message = "缺少 App ID 或 App Secret";
+    else
+        info.message = "飞书拒绝了长连接:" + (msg.empty() ? std::string("未知原因") : msg) + code_text(info.code);
+    return info;
+}
+
+HandshakeDecision classify_handshake(long http_status, int handshake_status, std::int64_t auth_errcode) {
+    HandshakeDecision decision;
+    if (handshake_status == 403) {
+        decision.fatal = true;
+        decision.message = "飞书拒绝了长连接(403),请确认应用为企业自建应用且凭据正确";
+    } else if (handshake_status == 514 && auth_errcode == 1000040350) {
+        decision.fatal = true;
+        decision.message = "该应用的长连接数已达上限,请关闭在其它地方运行的同一机器人";
+    } else {
+        decision.message = "无法建立飞书长连接" +
+                           (http_status > 0 ? "(HTTP " + std::to_string(http_status) + ")" : std::string{}) +
+                           ",稍后重试";
+    }
+    return decision;
+}
+
+ApiResult parse_api_response(long status, const std::string& body) {
+    ApiResult result;
+    result.status = status;
+    nlohmann::json json;
+    try {
+        json = nlohmann::json::parse(body);
+    } catch (...) {
+        json = nullptr;
+    }
+    if (json.is_object()) {
+        result.body = json;
+        result.code = int_field(json, "code", 0);
+        result.msg = string_field(json, "msg");
+        if (json.contains("data") && json["data"].is_object()) result.data = json["data"];
+    }
+    result.ok = status >= 200 && status < 300 && json.is_object() && result.code == 0;
+    return result;
+}
+
+bool is_token_invalid(std::int64_t code) {
+    return code == 99991661 || code == 99991663 || code == 99991664 || code == 99991665;
+}
+
+bool is_rate_limited(const ApiResult& result) {
+    const auto code = result.code;
+    return result.status == 429 || code == 99991400 || code == 99991402 || code == 11020 || code == 11021 ||
+           code == 230020;
+}
+
+std::chrono::seconds parse_retry_after(const std::string& value) {
+    const auto text = trim(value);
+    if (text.empty() || text.size() > 9) return std::chrono::seconds(0);
+    long long seconds = 0;
+    for (const char c : text) {
+        if (!is_digit(c)) return std::chrono::seconds(0);
+        seconds = seconds * 10 + (c - '0');
+    }
+    return std::chrono::seconds(std::min<long long>(seconds, 3600));
+}
+
+std::chrono::milliseconds rate_limit_wait(const ApiResult& result, std::chrono::milliseconds fallback) {
+    const auto requested = std::min<std::chrono::milliseconds>(result.retry_after, std::chrono::seconds(60));
+    return std::max(fallback, requested);
+}
+
+bool is_transient(const ApiResult& result) {
+    if (result.cancelled || result.auth_failed) return false;
+    if (result.status == 0 || result.status >= 500) return true;
+    return result.code >= 50000 && result.code <= 59999;
+}
+
+bool is_post_rejected(const ApiResult& result) {
+    if (result.ok) return false;
+    return result.code == 230001 ||
+           lower(result.msg).find("content format of the post type is incorrect") != std::string::npos;
+}
+
+bool is_reply_target_gone(std::int64_t code) { return code == 230011 || code == 231003; }
+
+std::string describe_error(const ApiResult& result) {
+    if (result.cancelled) return "已取消";
+    if (result.auth_failed) return result.error.empty() ? std::string("飞书凭据无效") : result.error;
+    if (result.status == 0) {
+        return "无法连接飞书开放平台" + (result.error.empty() ? std::string{} : ":" + result.error);
+    }
+    if (is_rate_limited(result)) return "发送过于频繁,被飞书限流";
+    if (is_token_invalid(result.code)) return "飞书访问凭证失效,请稍后重试";
+    switch (result.code) {
+        case 99991401: return "请求被应用的 IP 白名单拒绝,请在开发者后台「安全设置」中检查";
+        case 99991403: return "应用本月的 API 调用额度已用完";
+        case 99991662:
+        case 99991673: return "应用未启用或未安装到企业";
+        case 99991672:
+            return "应用缺少权限" + (result.msg.empty() ? std::string{} : ":" + result.msg) +
+                   "(添加权限后需重新发布版本)";
+        case 230002: return "机器人不在该群中";
+        case 230006:
+        case 234007: return "应用未开启机器人能力,请添加机器人能力并发布版本";
+        case 230011:
+        case 230110: return "消息已撤回或已删除";
+        case 231003: return "消息不存在";
+        case 230013: return "对方不在应用的可用范围内,请在开发者后台调整可用范围并发布版本";
+        case 230017: return "无权使用该文件(不是本机器人上传的)";
+        case 230018: return "该群禁止发言";
+        case 230022:
+        case 230028: return "消息内容未通过飞书的内容审核";
+        case 230025: return "消息内容过长";
+        case 230027:
+        case 230035: return "没有在该会话中发消息的权限";
+        case 230053: return "对方已停止接收机器人消息";
+        case 230055: return "文件类型与消息类型不匹配";
+        case 230099: return "卡片内容无效";
+        case 232009: return "该群已解散";
+        case 234003: return "附件与消息不匹配";
+        case 234004: return "机器人不在该会话中";
+        case 234006:
+        case 234037: return "文件超过飞书的大小限制";
+        case 234009: return "不支持外部群的附件";
+        case 234010: return "文件为空";
+        case 234011: return "不支持的文件格式";
+        case 234038: return "保密会话中的附件无法下载";
+        case 234039: return "图片分辨率过高";
+        case 234040: return "机器人无权查看该消息";
+        case 234043: return "合并转发或卡片里的附件无法下载";
+        default: break;
+    }
+    if (result.code != 0)
+        return "飞书返回错误:" + (result.msg.empty() ? std::string("未知原因") : result.msg) + code_text(result.code);
+    return "飞书返回 HTTP " + std::to_string(result.status);
+}
+
+std::string describe_token_error(std::int64_t code, const std::string& msg) {
+    switch (code) {
+        case 10014: return "App ID 不存在或应用已停用(也请确认选择的是飞书还是 Lark)";
+        case 10015: return "App Secret 不正确";
+        case 10003: return "App ID 或 App Secret 格式不对";
+        case 99991543: return "App ID 或 App Secret 不存在";
+        default: break;
+    }
+    return "凭据无效:" + (msg.empty() ? std::string("未知原因") : msg) + code_text(code);
+}
+
+BotInfo parse_bot_info(const nlohmann::json& body) {
+    BotInfo info;
+    if (!body.is_object() || int_field(body, "code", 0) != 0) return info;
+    const nlohmann::json* bot = nullptr;
+    if (body.contains("bot") && body["bot"].is_object()) bot = &body["bot"];
+    else if (object_field(body, "data").contains("bot") && body["data"]["bot"].is_object()) bot = &body["data"]["bot"];
+    if (!bot) return info;
+    info.open_id = string_field(*bot, "open_id");
+    info.name = string_field(*bot, "app_name");
+    info.activate_status = static_cast<int>(int_field(*bot, "activate_status", -1));
+    info.ok = !info.open_id.empty();
+    return info;
+}
+
+std::string describe_activate_status(int activate_status) {
+    switch (activate_status) {
+        case 2: return {};
+        case 0: return "机器人尚未安装到企业,请发布应用版本并等待管理员审核";
+        case 1: return "机器人已被企业管理员停用";
+        case 3:
+        case 4: return "应用已安装但尚未启用,请在开发者后台发布版本";
+        case 5:
+        case 6: return "应用授权已过期";
+        default: break;
+    }
+    return "未取到机器人信息:请在开发者后台添加机器人能力并发布版本";
+}
+
+std::string make_resource_ref(const std::string& message_id, const std::string& key, const std::string& type) {
+    return dump_json(nlohmann::json{{"message_id", message_id}, {"key", key}, {"type", type}});
+}
+
+std::optional<ResourceRef> parse_resource_ref(const std::string& remote_ref) {
+    try {
+        const auto json = nlohmann::json::parse(remote_ref);
+        ResourceRef ref;
+        ref.message_id = string_field(json, "message_id");
+        ref.key = string_field(json, "key");
+        ref.type = string_field(json, "type");
+        if (ref.message_id.empty() || ref.key.empty() || (ref.type != "image" && ref.type != "file"))
+            return std::nullopt;
+        return ref;
+    } catch (...) {
+        return std::nullopt;
+    }
+}
+
+std::string dump_json(const nlohmann::json& value) {
+    return value.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace);
+}
+
+SendTarget send_target(const Address& to, const nlohmann::json& reply_context) {
+    SendTarget target;
+    std::string chat_id;
+    if (reply_context.is_object()) {
+        target.reply_to = string_field(reply_context, "message_id");
+        chat_id = string_field(reply_context, "chat_id");
+        target.in_thread = !string_field(reply_context, "thread_id").empty();
+    }
+    if (!chat_id.empty()) {
+        target.receive_id_type = "chat_id";
+        target.receive_id = chat_id;
+    } else if (to.kind == ChatKind::Group) {
+        target.receive_id_type = "chat_id";
+        target.receive_id = to.chat;
+    } else {
+        target.receive_id_type = "open_id";
+        target.receive_id = to.chat;
+    }
+    if (target.reply_to.empty()) target.in_thread = false;
+    return target;
+}
+
+FileRoute route_file(const std::string& name, const std::string& mime_type, std::uint64_t size) {
+    const auto file = lower(name);
+    const auto mime = lower(mime_type);
+    const auto has_ext = [&file](std::initializer_list<const char*> exts) {
+        return std::any_of(exts.begin(), exts.end(), [&file](const char* ext) { return ends_with(file, ext); });
+    };
+    FileRoute route;
+    const bool image_ext = has_ext({".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp", ".ico", ".tif", ".tiff", ".heic"});
+    const bool image_mime = starts_with(mime, "image/") && mime != "image/svg+xml";
+    if ((image_ext || image_mime) && size > 0 && size <= kMaxImageBytes) {
+        route.image = true;
+        route.msg_type = "image";
+        return route;
+    }
+    route.msg_type = "file";
+    if (has_ext({".opus"}) || mime == "audio/opus") {
+        route.file_type = "opus";
+        route.msg_type = "audio";
+    } else if (has_ext({".mp4"}) || mime == "video/mp4") {
+        route.file_type = "mp4";
+        route.msg_type = "media";
+    } else if (has_ext({".pdf"})) {
+        route.file_type = "pdf";
+    } else if (has_ext({".doc", ".docx"})) {
+        route.file_type = "doc";
+    } else if (has_ext({".xls", ".xlsx"})) {
+        route.file_type = "xls";
+    } else if (has_ext({".ppt", ".pptx"})) {
+        route.file_type = "ppt";
+    } else {
+        route.file_type = "stream";
+    }
+    return route;
+}
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_protocol.hpp b/src/adapters/im/feishu/feishu_protocol.hpp
new file mode 100644
index 000000000..391499a4f
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_protocol.hpp
@@ -0,0 +1,242 @@
+#pragma once
+
+// 飞书 / Lark 机器人协议常量与纯逻辑(不做 IO):接入地址、长连接配置与握手分类、
+// OpenAPI 响应解析与错误分类、im.message.receive_v1 事件解析(@ 判定与文本清理)、
+// 出站 Markdown → post(md 节点)与分段、文件上传路由。
+// 协议细节见 add-desktop-im-channels 的飞书协议调研(长连接 pbbp2 帧、事件 2.0)。
+
+#include "im/transport.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace acecode::im::feishu {
+
+inline constexpr const char* kPlatform = "feishu";
+inline constexpr const char* kDomainFeishu = "feishu";
+inline constexpr const char* kDomainLark = "lark";
+inline constexpr const char* kFeishuBase = "https://open.feishu.cn";
+inline constexpr const char* kLarkBase = "https://open.larksuite.com";
+
+// "lark"(大小写不敏感)→ open.larksuite.com;其它一律 open.feishu.cn。
+// 飞书与 Lark 是两套独立的云,选错时换令牌会报 10014 / 1000040345。
+std::string base_for_domain(const std::string& domain);
+
+// 单条文本分段上限(字符,官方渠道 SDK 用 3500)与单条消息 content 序列化后的字节上限
+// (post 请求体上限 30 KB,留 2 KB 余量给外层 JSON 转义)。
+inline constexpr std::size_t kMaxTextChars = 3500;
+inline constexpr std::size_t kMaxContentBytes = 28u * 1024u;
+inline constexpr std::uint64_t kMaxImageBytes = 10u * 1024u * 1024u;
+inline constexpr std::uint64_t kMaxFileBytes = 30u * 1024u * 1024u;
+// 平台失败重投最长到 6 小时;创建时间超过 30 分钟的消息视为陈旧重放,直接丢弃。
+inline constexpr std::int64_t kStaleEventMs = 30LL * 60LL * 1000LL;
+
+// ---------------------------------------------------------------- 长连接
+
+// 服务端下发的长连接参数(单位秒),以服务端为准;本地默认值与官方 SDK 一致。
+struct ClientConfig {
+    int reconnect_count = -1;       // -1 = 无限重连
+    int reconnect_interval_s = 120;
+    int reconnect_nonce_s = 30;     // 首次重连前的随机抖动上限
+    int ping_interval_s = 120;
+};
+
+// 用 raw 里出现的字段覆盖 config(ReconnectCount / ReconnectInterval / ReconnectNonce /
+// PingInterval);负值的间隔与 0 的心跳间隔忽略。返回是否应用了至少一个字段。
+bool apply_client_config(const nlohmann::json& raw, ClientConfig* config);
+
+struct EndpointInfo {
+    bool ok = false;
+    bool fatal = false;        // 客户端错误(凭据无效等):不再重连
+    long status = 0;           // HTTP 状态码;0 = 没拿到响应
+    std::int64_t code = 0;
+    std::string message;       // 给用户看的中文原因;不含地址与密钥
+    std::string url;           // wss 地址,带票据,绝不能写日志
+    nlohmann::json client_config;  // 原始 ClientConfig;没有时为 null
+    std::string device_id;     // 连接 id,只用于日志
+    std::int32_t service_id = 0;
+};
+
+// 解析 POST /callback/ws/endpoint 的响应。HTTP 非 200、code 1 / 1000040343、地址为空
+// 都可重试;其它非 0 code 是客户端错误(致命)。
+EndpointInfo parse_endpoint_response(long status, const std::string& body);
+
+// 取 URL 查询参数(%XX 解码);不存在返回空串。
+std::string url_query_param(const std::string& url, const std::string& name);
+
+struct HandshakeDecision {
+    bool fatal = false;
+    std::string message;
+};
+
+// WebSocket 升级失败的分类。handshake_status / auth_errcode 来自响应头 Handshake-Status /
+// Handshake-Autherrcode(拿不到时传 0):403 → 致命;514 且 1000040350(连接数超限)→ 致命;
+// 其它一律可重试。
+HandshakeDecision classify_handshake(long http_status, int handshake_status, std::int64_t auth_errcode);
+
+// ---------------------------------------------------------------- OpenAPI
+
+struct ApiResult {
+    bool ok = false;
+    long status = 0;            // HTTP 状态码;0 = 没拿到响应
+    std::int64_t code = 0;      // 飞书业务错误码
+    std::string msg;            // 平台原文
+    std::string error;          // 传输层错误(status == 0 时),已脱敏
+    nlohmann::json body = nlohmann::json::object();
+    nlohmann::json data = nlohmann::json::object();  // body.data(没有时为空对象)
+    bool cancelled = false;
+    bool auth_failed = false;   // 换令牌时凭据被拒;error 为给用户看的原因
+    std::chrono::seconds retry_after{0};  // 限流响应头 x-ogw-ratelimit-reset(秒)
+    std::string log_id;         // 响应头 X-Tt-Logid,排障时飞书支持会要;只写日志
+};
+
+// 飞书的错误常带 HTTP 400/401/429 且仍有 JSON 体:一律解析响应体。ok = 2xx 且 code == 0。
+ApiResult parse_api_response(long status, const std::string& body);
+
+// 令牌失效类错误码(99991661 / 99991663 / 99991664 / 99991665):刷新令牌后重试一次。
+bool is_token_invalid(std::int64_t code);
+// 限流:HTTP 429,或 99991400 / 99991402 / 11020 / 11021 / 230020。
+bool is_rate_limited(const ApiResult& result);
+// 解析 x-ogw-ratelimit-reset(需要等待的秒数);非法或缺失返回 0,上限 1 小时。
+std::chrono::seconds parse_retry_after(const std::string& value);
+// 被限流后这次重发前的等待:本地退避与平台要求(封顶 60 秒)取大。
+std::chrono::milliseconds rate_limit_wait(const ApiResult& result, std::chrono::milliseconds fallback);
+// 值得原样重试的临时错误:网络错误、HTTP 5xx、code 落在 50000–59999。限流单独处理。
+bool is_transient(const ApiResult& result);
+// post 内容被拒(230001 或 msg 含 "content format of the post type is incorrect"):改发纯文本。
+bool is_post_rejected(const ApiResult& result);
+// 回复目标已撤回 / 不存在(230011 / 231003):改为直接发到会话。
+bool is_reply_target_gone(std::int64_t code);
+
+// 给用户看的一句话中文原因(不含凭据)。
+std::string describe_error(const ApiResult& result);
+// 换取 tenant_access_token 失败(code != 0)时给用户看的原因。
+std::string describe_token_error(std::int64_t code, const std::string& msg);
+
+struct BotInfo {
+    bool ok = false;
+    std::string open_id;    // 机器人自己的 open_id,只用于判定群里是否 @ 了机器人
+    std::string name;
+    int activate_status = -1;  // 2 = 已启用(唯一正常状态)
+    bool ready() const { return ok && activate_status == 2; }
+};
+
+// 解析 GET /open-apis/bot/v3/info(bot 在顶层,也兼容 data.bot)。
+BotInfo parse_bot_info(const nlohmann::json& body);
+// activate_status 不为 2 时给用户的提示。
+std::string describe_activate_status(int activate_status);
+
+// ---------------------------------------------------------------- 入站事件
+
+struct BotIdentity {
+    std::string open_id;
+    std::string name;
+};
+
+struct Mention {
+    std::string key;            // "@_user_1"
+    std::string open_id;
+    std::string user_id;
+    std::string name;
+    std::string mentioned_type; // "user" / "bot"
+};
+
+std::vector<Mention> parse_mentions(const nlohmann::json& mentions);
+
+// 是否点名了机器人。优先按 open_id 比对(权威);还没拿到机器人身份时退化为按名字、
+// 再退化为 mentioned_type == "bot"。@所有人 不算(与官方渠道 SDK 默认一致)。
+bool mentions_bot(const std::vector<Mention>& mentions, const BotIdentity& bot);
+
+// 把正文里的 @ 占位符换成可读文本:机器人自己的 @ 在开头 / 结尾处去掉、在中间保留为
+// "@名字";其他人 → "@名字";未知占位符 → 空格;@_all → "@all"。CRLF → LF,首尾空白去掉,
+// 每行行尾空白去掉;行内缩进保留(用户贴的代码不被破坏)。
+std::string clean_text(const std::string& raw, const std::vector<Mention>& mentions, const BotIdentity& bot);
+
+struct ExtractedContent {
+    std::string text;  // 仍含 @_user_N 占位符,交给 clean_text 处理
+    std::vector<Attachment> attachments;
+};
+
+// 按 message_type 从已解析的 content 里取文字与附件(post 的 img / media 节点也算附件)。
+ExtractedContent extract_content(const std::string& message_type, const nlohmann::json& content,
+                                 const std::string& message_id);
+
+// 附件下载定位:Attachment::remote_ref 存成 JSON {"message_id","key","type"},type 为 image / file。
+struct ResourceRef {
+    std::string message_id;
+    std::string key;
+    std::string type;
+};
+std::string make_resource_ref(const std::string& message_id, const std::string& key, const std::string& type);
+std::optional<ResourceRef> parse_resource_ref(const std::string& remote_ref);
+
+enum class EventDisposition {
+    Message,   // inbound 有值
+    Ignored,   // 不是 im.message.receive_v1(或 1.0 事件)
+    Stale,     // 创建时间超过 30 分钟(平台重投的旧消息)
+    FromBot,   // 机器人 / 应用发的,或机器人自己的回声
+    Empty,     // 去掉 @机器人 后既没有文字也没有附件
+    Invalid,   // JSON 损坏或缺关键字段
+};
+
+struct ParsedEvent {
+    EventDisposition disposition = EventDisposition::Ignored;
+    std::string event_type;
+    std::string message_id;      // 已解析出时填写(用于日志与去重)
+    std::optional<Inbound> inbound;
+};
+
+// 解析一个 type=event 帧的完整 payload。account = App ID;now_epoch_ms 用于陈旧判断。
+// 私聊:chat = sender = 对方 open_id;群聊:chat = chat_id,sender = 发言人 open_id。
+// reply_context = {message_id, chat_id, chat_type[, thread_id]}。
+ParsedEvent parse_event(const std::string& payload, const BotIdentity& bot, const std::string& account,
+                        std::int64_t now_epoch_ms);
+
+// ---------------------------------------------------------------- 出站
+
+// 是否按 Markdown 发送(整条消息判定一次,所有分段沿用,避免纯文字分段把 ** 原样露出)。
+// 规则对照 hermes 的 _MARKDOWN_HINT_RE:表格、标题、列表、分隔线、代码、粗/斜/删除线、
+// <u>、链接、引用。手写扫描,不用 std::regex。
+bool looks_like_markdown(std::string_view text);
+
+// post 内容 {"zh_cn":{"content":rows}}(不能再包一层 "post");每个 ``` 代码块单独占一行
+// md 节点,前后的正文各占一行 —— 飞书的 md 渲染器遇到大段内嵌代码块会吞掉后面的内容。
+nlohmann::json build_post_content(const std::string& markdown);
+nlohmann::json build_text_content(const std::string& text);
+
+// 序列化 JSON;非法 UTF-8 用替换字符兜底,绝不抛异常。
+std::string dump_json(const nlohmann::json& value);
+
+// 出站分段:先按字符上限切(代码块跨段时自动补闭合 / 重开围栏),再确保每段的 content
+// 序列化后不超过 max_bytes(超出就把该段按一半上限再切)。
+std::vector<std::string> split_outbound(const std::string& text, bool markdown,
+                                        std::size_t max_chars = kMaxTextChars,
+                                        std::size_t max_bytes = kMaxContentBytes);
+
+// 出站目标:有 reply_context.message_id 时首段走回复接口;有 chat_id 时一律按 chat_id 发
+// (私聊也有 chat_id);否则群 → chat_id = address.chat,私聊 → open_id = address.chat。
+struct SendTarget {
+    std::string receive_id_type;  // chat_id / open_id
+    std::string receive_id;
+    std::string reply_to;         // 触发本回合的消息 id(可空)
+    bool in_thread = false;       // 话题内:所有分段都走回复,留在同一话题
+};
+SendTarget send_target(const Address& to, const nlohmann::json& reply_context);
+
+// 文件上传路由。image = true 时走图片接口(≤ 10 MB 的常见图片),以 msg_type=image 发送;
+// 否则走文件接口:.opus → opus / audio,.mp4 → mp4 / media,pdf / doc / xls / ppt 各自
+// 类型 / file,其余 stream / file。上传类型必须与 msg_type 一致(否则 230055)。
+struct FileRoute {
+    bool image = false;
+    std::string file_type;
+    std::string msg_type;
+};
+FileRoute route_file(const std::string& name, const std::string& mime_type, std::uint64_t size);
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_text_util.hpp b/src/adapters/im/feishu/feishu_text_util.hpp
new file mode 100644
index 000000000..598e8f902
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_text_util.hpp
@@ -0,0 +1,85 @@
+#pragma once
+
+// 飞书协议实现内部共用的小工具(JSON 字段读取、字符串修剪),不对外暴露。
+
+#include <nlohmann/json.hpp>
+
+#include <algorithm>
+#include <cctype>
+#include <cstdint>
+#include <limits>
+#include <string>
+#include <string_view>
+
+namespace acecode::im::feishu::detail {
+
+inline std::string lower(std::string text) {
+    std::transform(text.begin(), text.end(), text.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return text;
+}
+
+inline bool is_space(char c) { return c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == '\f' || c == '\v'; }
+
+inline std::string trim(std::string_view text) {
+    std::size_t b = 0, e = text.size();
+    while (b < e && is_space(text[b])) ++b;
+    while (e > b && is_space(text[e - 1])) --e;
+    return std::string(text.substr(b, e - b));
+}
+
+inline bool starts_with(std::string_view text, std::string_view prefix) {
+    return text.size() >= prefix.size() && text.compare(0, prefix.size(), prefix) == 0;
+}
+
+inline bool ends_with(std::string_view text, std::string_view suffix) {
+    return text.size() >= suffix.size() && text.compare(text.size() - suffix.size(), suffix.size(), suffix) == 0;
+}
+
+inline bool is_digit(char c) { return c >= '0' && c <= '9'; }
+
+inline bool word_char(char c) { return std::isalnum(static_cast<unsigned char>(c)) != 0 || c == '_'; }
+
+inline std::string string_field(const nlohmann::json& value, const char* key) {
+    if (!value.is_object() || !value.contains(key)) return {};
+    const auto& field = value.at(key);
+    if (field.is_string()) return field.get<std::string>();
+    if (field.is_number_integer()) return std::to_string(field.get<std::int64_t>());
+    return {};
+}
+
+inline std::int64_t int_field(const nlohmann::json& value, const char* key, std::int64_t fallback) {
+    if (!value.is_object() || !value.contains(key)) return fallback;
+    const auto& field = value.at(key);
+    if (field.is_number_integer()) return field.get<std::int64_t>();
+    if (field.is_number_unsigned()) {
+        const auto raw = field.get<std::uint64_t>();
+        return raw > static_cast<std::uint64_t>(std::numeric_limits<std::int64_t>::max())
+                   ? fallback
+                   : static_cast<std::int64_t>(raw);
+    }
+    if (field.is_number_float()) return static_cast<std::int64_t>(field.get<double>());
+    if (field.is_string()) {
+        const auto text = trim(field.get<std::string>());
+        if (text.empty()) return fallback;
+        std::size_t i = text[0] == '-' ? 1 : 0;
+        if (i == text.size()) return fallback;
+        for (std::size_t k = i; k < text.size(); ++k) {
+            if (!is_digit(text[k])) return fallback;
+        }
+        try {
+            return std::stoll(text);
+        } catch (...) {
+            return fallback;
+        }
+    }
+    return fallback;
+}
+
+inline const nlohmann::json& object_field(const nlohmann::json& value, const char* key) {
+    static const nlohmann::json kEmpty = nlohmann::json::object();
+    if (!value.is_object() || !value.contains(key) || !value.at(key).is_object()) return kEmpty;
+    return value.at(key);
+}
+
+} // namespace acecode::im::feishu::detail
diff --git a/src/adapters/im/feishu/feishu_transport.cpp b/src/adapters/im/feishu/feishu_transport.cpp
new file mode 100644
index 000000000..fcdda6310
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_transport.cpp
@@ -0,0 +1,533 @@
+#include "im/feishu/feishu_transport.hpp"
+
+#include "im/markdown.hpp"
+#include "im/redact.hpp"
+#include "utils/logger.hpp"
+#include "utils/utf8_path.hpp"
+#include "utils/uuid.hpp"
+
+#include <algorithm>
+#include <thread>
+
+namespace acecode::im::feishu {
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+constexpr std::size_t kSeenLimit = 2048;
+constexpr auto kWriteTimeout = std::chrono::seconds(10);
+
+std::int64_t epoch_ms() {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(std::chrono::system_clock::now().time_since_epoch())
+        .count();
+}
+
+std::string ms_text(std::chrono::milliseconds value) { return std::to_string(value.count()) + "ms"; }
+
+// WebSocketClient 的错误文本形如 "... (HTTP 403)";取出状态码,没有则为 0。
+long http_status_in(const std::string& error) {
+    const auto pos = error.find("HTTP ");
+    if (pos == std::string::npos) return 0;
+    long status = 0;
+    for (std::size_t i = pos + 5; i < error.size() && error[i] >= '0' && error[i] <= '9' && status < 1000; ++i)
+        status = status * 10 + (error[i] - '0');
+    return status;
+}
+
+// 消息 id 来自核心保存的 reply_context,拼进路径前做百分号编码。
+std::string path_segment(const std::string& value) {
+    static constexpr char kHex[] = "0123456789ABCDEF";
+    std::string out;
+    for (const char c : value) {
+        const auto u = static_cast<unsigned char>(c);
+        if ((u >= 'A' && u <= 'Z') || (u >= 'a' && u <= 'z') || (u >= '0' && u <= '9') || u == '-' || u == '_' ||
+            u == '.' || u == '~') {
+            out.push_back(c);
+        } else {
+            out.push_back('%');
+            out.push_back(kHex[u >> 4]);
+            out.push_back(kHex[u & 0x0F]);
+        }
+    }
+    return out;
+}
+
+std::string result_brief(const ApiResult& result) {
+    return "HTTP " + std::to_string(result.status) + ", code " + std::to_string(result.code) +
+           (result.log_id.empty() ? std::string{} : ", logid " + result.log_id);
+}
+
+} // namespace
+
+FeishuTransport::FeishuTransport(FeishuTransportOptions options)
+    : options_(std::move(options)),
+      api_(options_.api),
+      pacer_(options_.send_gap),
+      session_(options_.link_limits) {
+    status_.account = options_.api.app_id;
+}
+
+FeishuTransport::~FeishuTransport() { stop(); }
+
+Capabilities FeishuTransport::capabilities() const {
+    Capabilities caps;
+    caps.max_text_units = kMaxTextChars;
+    caps.count_utf16 = false;
+    caps.batch_turn_output = false;
+    caps.supports_typing = false;
+    caps.max_upload_bytes = options_.max_upload_bytes;
+    caps.max_download_bytes = options_.max_download_bytes;
+    return caps;
+}
+
+void FeishuTransport::start(TransportCallbacks callbacks) {
+    if (running_.exchange(true)) return;
+    callbacks_ = std::move(callbacks);
+    stopping_ = false;
+    rng_.seed(std::random_device{}());
+    worker_ = acecode::JoiningThread(&FeishuTransport::run, this);
+}
+
+void FeishuTransport::stop() {
+    if (!running_.exchange(false)) return;
+    stopping_ = true;
+    wake_.notify_all();
+    // 不调用 ws_.abort():读循环最多 receive_poll 后看到停止标记,先发 close 帧再退出。
+    if (worker_.joinable()) worker_.join();
+    ws_.close();
+    set_status(LinkState::Stopped, {});
+}
+
+TransportStatus FeishuTransport::status() const {
+    std::lock_guard<std::mutex> lock(status_mu_);
+    return status_;
+}
+
+BotIdentity FeishuTransport::bot() const {
+    std::lock_guard<std::mutex> lock(bot_mu_);
+    return bot_;
+}
+
+void FeishuTransport::set_status(LinkState state, const std::string& detail, bool retry_stopped, bool force) {
+    TransportStatus snapshot;
+    {
+        std::lock_guard<std::mutex> lock(status_mu_);
+        const auto clean = redact_secrets(detail, {options_.api.app_secret});
+        if (!force && status_.state == state && status_.detail == clean && status_.retry_stopped == retry_stopped)
+            return;
+        status_.state = state;
+        status_.detail = clean;
+        status_.retry_stopped = retry_stopped;
+        snapshot = status_;
+    }
+    if (callbacks_.on_status) callbacks_.on_status(snapshot);
+}
+
+bool FeishuTransport::wait_for(std::chrono::milliseconds duration) {
+    std::unique_lock<std::mutex> lock(wake_mu_);
+    wake_.wait_for(lock, duration, [this] { return stopping_.load(); });
+    return !stopping_;
+}
+
+void FeishuTransport::run() {
+    std::size_t failures = 0;
+    bool first = true;
+    while (!stopping_) {
+        set_status(first ? LinkState::Connecting : LinkState::Retrying,
+                   first ? "正在连接飞书" : "正在重新连接飞书");
+        first = false;
+        const auto attempt = connect_and_serve();
+        if (stopping_ || attempt.outcome == Outcome::Stopped) break;
+        if (attempt.outcome == Outcome::Fatal) {
+            // 凭据无效、连接数超限等不会自己好:停止重试,等用户处理后重新打开。
+            LOG_WARN("[channels/feishu] connection failed permanently; retry stopped");
+            set_status(LinkState::Failed, attempt.message, true);
+            break;
+        }
+        if (attempt.outcome == Outcome::Dropped) failures = 0;
+        else ++failures;
+        if (reconnect_exhausted(session_.config(), server_config_, failures)) {
+            LOG_WARN("[channels/feishu] reconnect attempts exhausted (server ReconnectCount)");
+            set_status(LinkState::Failed, "多次重连飞书失败,已停止重试", true);
+            break;
+        }
+        set_status(LinkState::Retrying, attempt.message);
+        const double jitter = std::uniform_real_distribution<double>(0.0, 1.0)(rng_);
+        const auto delay = reconnect_delay(session_.config(), server_config_, failures, options_.backoff, jitter);
+        LOG_INFO("[channels/feishu] reconnecting in " + ms_text(delay));
+        if (!wait_for(delay)) break;
+    }
+    // 致命错误后保持 Failed 状态,等 stop() 收尾。
+    if (!stopping_) {
+        std::unique_lock<std::mutex> lock(wake_mu_);
+        wake_.wait(lock, [this] { return stopping_.load(); });
+    }
+}
+
+void FeishuTransport::refresh_bot() {
+    std::string error;
+    const auto info = api_.bot_info(&error, &stopping_);
+    bool ready = false;
+    int activate = -1;
+    std::string name;
+    {
+        std::lock_guard<std::mutex> lock(bot_mu_);
+        bot_checked_ = Clock::now();
+        if (info.ok) {
+            bot_.open_id = info.open_id;
+            bot_.name = info.name;
+            activate_status_ = info.activate_status;
+        }
+        ready = info.ok ? info.ready() : (!bot_.open_id.empty() && activate_status_ == 2);
+        activate = activate_status_;
+        name = bot_.name;
+    }
+    {
+        std::lock_guard<std::mutex> lock(status_mu_);
+        if (!name.empty()) status_.display_name = name;
+        status_.extra["bot_ready"] = ready;
+        status_.extra["activate_status"] = activate;
+        if (ready) {
+            status_.extra.erase("bot_warning");
+        } else {
+            status_.extra["bot_warning"] = info.ok ? describe_activate_status(info.activate_status)
+                                                   : (error.empty() ? describe_activate_status(-1) : error);
+        }
+    }
+    if (!ready)
+        LOG_WARN("[channels/feishu] bot identity unavailable or bot inactive (activate_status=" +
+                 std::to_string(activate) + "); group @ detection falls back to mention type");
+}
+
+FeishuTransport::Attempt FeishuTransport::connect_and_serve() {
+    std::string error;
+    if (api_.tenant_token(&error, &stopping_).empty()) {
+        if (stopping_) return {Outcome::Stopped, {}};
+        if (api_.last_token_auth_failed()) return {Outcome::Fatal, error};
+        LOG_WARN("[channels/feishu] tenant token unavailable");
+        return {Outcome::Failed, error};
+    }
+    // 每次连接都重新取机器人身份:应用迁移或重新发布后,旧的 open_id 会让群 @ 判定失效。
+    refresh_bot();
+    if (stopping_) return {Outcome::Stopped, {}};
+
+    const auto endpoint = api_.ws_endpoint(&stopping_);
+    if (stopping_) return {Outcome::Stopped, {}};
+    if (!endpoint.client_config.is_null()) {
+        auto config = session_.config();
+        if (apply_client_config(endpoint.client_config, &config)) {
+            session_.set_config(config);
+            server_config_ = true;
+        }
+    }
+    if (endpoint.fatal) {
+        LOG_WARN("[channels/feishu] endpoint rejected the app (code " + std::to_string(endpoint.code) + ")");
+        return {Outcome::Fatal, endpoint.message};
+    }
+    if (!endpoint.ok) {
+        LOG_WARN("[channels/feishu] endpoint unavailable (HTTP " + std::to_string(endpoint.status) + ", code " +
+                 std::to_string(endpoint.code) + ")");
+        return {Outcome::Failed, endpoint.message};
+    }
+
+    network::WebSocketConnectOptions ws_options;
+    ws_options.url = endpoint.url;  // 鉴权在 URL 查询参数里;不加任何额外请求头
+    ws_options.use_proxy = options_.api.use_proxy;
+    if (!ws_.connect(ws_options, &error)) {
+        const auto query = endpoint.url.find('?');
+        const auto secrets = std::vector<std::string>{
+            options_.api.app_secret, endpoint.url,
+            query == std::string::npos ? std::string{} : endpoint.url.substr(query + 1)};
+        LOG_WARN("[channels/feishu] long connection handshake failed: " + redact_secrets(error, secrets));
+        // 拿不到 Handshake-Status 响应头时一律按可重试处理(与 Go SDK 一致)。
+        const auto decision = classify_handshake(http_status_in(error), 0, 0);
+        return {decision.fatal ? Outcome::Fatal : Outcome::Failed, decision.message};
+    }
+    LOG_INFO("[channels/feishu] long connection established (device " + endpoint.device_id + ")");
+    session_.on_connected(endpoint.service_id, Clock::now());
+    set_status(LinkState::Connected, {});
+
+    Attempt attempt{Outcome::Dropped, "飞书长连接已断开,正在重连"};
+    serve_connection(attempt);
+    ws_.close(1000, "bye");  // close 帧很重要:否则平台会继续把消息投给这条已断开的连接
+    session_.on_disconnected();
+    if (stopping_) return {Outcome::Stopped, {}};
+    return attempt;
+}
+
+void FeishuTransport::serve_connection(Attempt& attempt) {
+    std::string error;
+    while (!stopping_) {
+        const auto now = Clock::now();
+        const auto tick = session_.on_tick(now);
+        if (tick.dead) {
+            LOG_WARN("[channels/feishu] no frame within the read timeout, reconnecting");
+            attempt.message = "飞书长连接无响应,正在重连";
+            return;
+        }
+        if (tick.ping && !ws_.send_binary(*tick.ping, kWriteTimeout, &error)) {
+            LOG_WARN("[channels/feishu] ping write failed, reconnecting");
+            return;
+        }
+        bool bot_ready = true;
+        bool bot_due = false;
+        {
+            std::lock_guard<std::mutex> lock(bot_mu_);
+            bot_ready = !bot_.open_id.empty() && activate_status_ == 2;
+            bot_due = now - bot_checked_ >= options_.bot_refresh_interval;
+        }
+        if (!bot_ready && bot_due) {
+            // 用户在后台发布版本后,机器人身份才可用;不重连也要能补上。
+            refresh_bot();
+            set_status(LinkState::Connected, {}, false, true);
+        }
+
+        network::WebSocketMessage message;
+        const auto received = ws_.receive(message, options_.receive_poll, &error);
+        if (received == network::WebSocketRecv::Timeout) continue;
+        if (received == network::WebSocketRecv::Message) {
+            if (!message.binary) {
+                LOG_WARN("[channels/feishu] ignored a non-binary frame");
+                continue;
+            }
+            auto out = session_.on_message(message.data, Clock::now());
+            if (!out.warning.empty()) LOG_WARN("[channels/feishu] " + out.warning);
+            if (out.config_updated)
+                LOG_INFO("[channels/feishu] server updated ClientConfig (ping " +
+                         std::to_string(session_.config().ping_interval_s) + "s)");
+            bool write_failed = false;
+            for (const auto& frame : out.frames) {
+                if (!ws_.send_binary(frame, kWriteTimeout, &error)) write_failed = true;
+            }
+            for (const auto& event : out.events) handle_event(event);
+            if (write_failed) {
+                LOG_WARN("[channels/feishu] ack write failed, reconnecting");
+                return;
+            }
+            continue;
+        }
+        if (stopping_) return;
+        const int code = received == network::WebSocketRecv::Closed ? ws_.close_code() : 1006;
+        LOG_INFO("[channels/feishu] long connection closed (code " + std::to_string(code) + ")");
+        return;
+    }
+}
+
+bool FeishuTransport::seen_before(const std::string& message_id) {
+    std::lock_guard<std::mutex> lock(seen_mu_);
+    if (seen_.count(message_id)) return true;
+    seen_.insert(message_id);
+    seen_order_.push_back(message_id);
+    while (seen_order_.size() > kSeenLimit) {
+        seen_.erase(seen_order_.front());
+        seen_order_.pop_front();
+    }
+    return false;
+}
+
+void FeishuTransport::handle_event(const std::string& payload) {
+    auto parsed = parse_event(payload, bot(), options_.api.app_id, epoch_ms());
+    switch (parsed.disposition) {
+        case EventDisposition::Message:
+            // 平台至少投递一次,重连或 ACK 超时后会重投;按消息 id 去重。
+            if (seen_before(parsed.message_id)) {
+                LOG_DEBUG("[channels/feishu] duplicate message " + parsed.message_id + " ignored");
+                return;
+            }
+            if (callbacks_.on_inbound) callbacks_.on_inbound(std::move(*parsed.inbound));
+            return;
+        case EventDisposition::Stale:
+            LOG_INFO("[channels/feishu] dropped stale message " + parsed.message_id + " (older than 30 minutes)");
+            return;
+        case EventDisposition::FromBot:
+            LOG_DEBUG("[channels/feishu] ignored a message sent by a bot");
+            return;
+        case EventDisposition::Empty:
+            LOG_DEBUG("[channels/feishu] ignored an empty message " + parsed.message_id);
+            return;
+        case EventDisposition::Invalid:
+            LOG_WARN("[channels/feishu] ignored a malformed event (" + parsed.event_type + ")");
+            return;
+        case EventDisposition::Ignored:
+            LOG_DEBUG("[channels/feishu] ignored event " + parsed.event_type);
+            return;
+    }
+}
+
+ApiResult FeishuTransport::with_retry(const std::string& pace_key, const std::function<ApiResult()>& attempt) {
+    std::size_t limited = 0;
+    std::size_t transient = 0;
+    while (true) {
+        if (!pace_key.empty()) {
+            const auto at = pacer_.reserve(pace_key, Clock::now());
+            const auto now = Clock::now();
+            if (at > now) std::this_thread::sleep_for(at - now);
+        }
+        auto result = attempt();
+        if (result.ok) return result;
+        if (is_rate_limited(result) && limited < options_.rate_limit_backoff.size()) {
+            // 限流表示平台没有收下这条消息,等待后重发是安全的;同一调用线程串行,顺序不乱。
+            const auto wait = rate_limit_wait(result, options_.rate_limit_backoff[limited++]);
+            LOG_INFO("[channels/feishu] rate limited (" + result_brief(result) + "), retrying in " + ms_text(wait));
+            if (pace_key.empty()) std::this_thread::sleep_for(wait);
+            else pacer_.penalize(pace_key, wait, Clock::now());
+            continue;
+        }
+        if (is_transient(result) && transient < options_.retry_backoff.size()) {
+            const auto wait = options_.retry_backoff[transient++];
+            LOG_INFO("[channels/feishu] request failed temporarily (" + result_brief(result) + "), retrying in " +
+                     ms_text(wait));
+            std::this_thread::sleep_for(wait);
+            continue;
+        }
+        return result;
+    }
+}
+
+ApiResult FeishuTransport::deliver(SendTarget& target, bool reply, const std::string& msg_type,
+                                   const nlohmann::json& content) {
+    const auto text = dump_json(content);
+    if (reply && !target.reply_to.empty()) {
+        // uuid 在重发之间保持不变:平台一小时内同一 uuid 只发一条,网络重试不会重复送达。
+        const nlohmann::json body{{"msg_type", msg_type}, {"content", text}, {"uuid", generate_uuid()}};
+        const auto path = "/open-apis/im/v1/messages/" + path_segment(target.reply_to) + "/reply";
+        auto result = with_retry(target.receive_id,
+                                 [&api = api_, &path, &body] { return api.call("POST", path, body); });
+        if (result.ok || !is_reply_target_gone(result.code)) return result;
+        LOG_INFO("[channels/feishu] reply target is gone (code " + std::to_string(result.code) +
+                 "), sending to the chat instead");
+        target.reply_to.clear();
+        target.in_thread = false;
+    }
+    const nlohmann::json body{{"receive_id", target.receive_id},
+                              {"msg_type", msg_type},
+                              {"content", text},
+                              {"uuid", generate_uuid()}};
+    const auto path = "/open-apis/im/v1/messages?receive_id_type=" + target.receive_id_type;
+    return with_retry(target.receive_id, [&api = api_, &path, &body] { return api.call("POST", path, body); });
+}
+
+SendResult FeishuTransport::send_text(const Address& to, const std::string& text,
+                                      const nlohmann::json& reply_context) {
+    // 整条消息只判定一次:否则不含标记的分段按纯文本发,与相邻分段格式不一致。
+    const bool markdown = looks_like_markdown(text);
+    auto target = send_target(to, reply_context);
+    bool first = true;
+    for (const auto& chunk : split_outbound(text, markdown)) {
+        const bool reply = !target.reply_to.empty() && (first || target.in_thread);
+        first = false;
+        auto result = deliver(target, reply, markdown ? "post" : "text",
+                              markdown ? build_post_content(chunk) : build_text_content(chunk));
+        if (!result.ok && markdown && is_post_rejected(result)) {
+            LOG_INFO("[channels/feishu] post rejected (code " + std::to_string(result.code) +
+                     "), resending the chunk as plain text");
+            result = deliver(target, reply && !target.reply_to.empty(), "text",
+                             build_text_content(markdown_to_plain(chunk)));
+        }
+        if (!result.ok) {
+            LOG_WARN("[channels/feishu] send failed (" + result_brief(result) + ")");
+            return {SendOutcome::Failed, describe_error(result)};
+        }
+    }
+    return {SendOutcome::Sent, {}};
+}
+
+ApiResult FeishuTransport::upload_file(const std::filesystem::path& path, const std::string& name,
+                                       const std::string& mime_type, const FileRoute& route, std::string* key) {
+    std::vector<HttpPart> parts;
+    std::string endpoint;
+    HttpPart file;
+    file.file = path;
+    file.filename = name;
+    file.content_type = mime_type.empty() ? "application/octet-stream" : mime_type;
+    if (route.image) {
+        endpoint = "/open-apis/im/v1/images";
+        parts.push_back(HttpPart{"image_type", "message"});
+        file.name = "image";
+    } else {
+        endpoint = "/open-apis/im/v1/files";
+        parts.push_back(HttpPart{"file_type", route.file_type});
+        parts.push_back(HttpPart{"file_name", name});  // 原名(UTF-8)放在字段里;文件部件的名字只能是 ASCII
+        file.name = "file";
+    }
+    parts.push_back(std::move(file));
+    auto result = with_retry({}, [&api = api_, &endpoint, &parts] { return api.upload(endpoint, parts); });
+    if (result.ok) {
+        const char* field = route.image ? "image_key" : "file_key";
+        if (result.data.contains(field) && result.data[field].is_string()) *key = result.data[field].get<std::string>();
+        if (key->empty()) {
+            result.ok = false;
+            result.code = -1;
+            result.msg = "上传结果缺少文件标识";
+        }
+    }
+    return result;
+}
+
+SendResult FeishuTransport::send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                                      const std::string& mime_type, const nlohmann::json& reply_context) {
+    std::error_code ec;
+    const auto size = std::filesystem::file_size(path, ec);
+    if (ec) return {SendOutcome::Failed, "文件不存在或不可读"};
+    if (size == 0) return {SendOutcome::Failed, "文件为空,未发送"};
+    const auto display = name.empty() ? path_to_utf8(path.filename()) : name;
+    auto route = route_file(display, mime_type, size);
+    if (!route.image && size > options_.max_upload_bytes) {
+        // 超过上传上限时改发一条文字说明,对方至少知道有文件没发过去。
+        const auto limit_mib = std::to_string(options_.max_upload_bytes / (1024u * 1024u));
+        LOG_INFO("[channels/feishu] file of " + std::to_string(size) + " bytes is over the " + limit_mib +
+                 " MiB upload limit, sending a text notice instead");
+        return send_text(to, "文件「" + display + "」超过飞书上传上限(" + limit_mib + " MiB),未发送;请在 ACECode 中查看。",
+                         reply_context);
+    }
+    const auto unrecoverable = [](const ApiResult& result) {
+        return result.auth_failed || is_transient(result) || is_rate_limited(result);
+    };
+    std::string key;
+    auto uploaded = upload_file(path, display, mime_type, route, &key);
+    if (!uploaded.ok && route.image && !unrecoverable(uploaded)) {
+        // 图片接口不认(格式、分辨率):改按普通文件发送。
+        LOG_INFO("[channels/feishu] image upload rejected (code " + std::to_string(uploaded.code) +
+                 "), sending as a file");
+        route = FileRoute{false, "stream", "file"};
+        uploaded = upload_file(path, display, mime_type, route, &key);
+    }
+    if (!uploaded.ok) {
+        LOG_WARN("[channels/feishu] upload failed (" + result_brief(uploaded) + ")");
+        return {SendOutcome::Failed, describe_error(uploaded)};
+    }
+    auto target = send_target(to, reply_context);
+    const auto content_for = [](const FileRoute& r, const std::string& k) {
+        return r.image ? nlohmann::json{{"image_key", k}} : nlohmann::json{{"file_key", k}};
+    };
+    auto result = deliver(target, !target.reply_to.empty(), route.msg_type, content_for(route, key));
+    if (!result.ok && (route.msg_type == "audio" || route.msg_type == "media") && !unrecoverable(result)) {
+        // 平台不认这段音视频(编码不符等):重新按普通文件上传发送。
+        LOG_INFO("[channels/feishu] " + route.msg_type + " message rejected (code " + std::to_string(result.code) +
+                 "), resending as a plain file");
+        route = FileRoute{false, "stream", "file"};
+        uploaded = upload_file(path, display, mime_type, route, &key);
+        if (!uploaded.ok) return {SendOutcome::Failed, describe_error(uploaded)};
+        result = deliver(target, !target.reply_to.empty(), route.msg_type, content_for(route, key));
+    }
+    if (!result.ok) {
+        LOG_WARN("[channels/feishu] file message failed (" + result_brief(result) + ")");
+        return {SendOutcome::Failed, describe_error(result)};
+    }
+    return {SendOutcome::Sent, {}};
+}
+
+bool FeishuTransport::download(const Attachment& attachment, const std::filesystem::path& dest, std::string* error) {
+    const auto ref = parse_resource_ref(attachment.remote_ref);
+    if (!ref) {
+        if (error) *error = "附件缺少下载信息";
+        return false;
+    }
+    if (attachment.size > options_.max_download_bytes) {
+        if (error) *error = "附件超过大小限制";
+        return false;
+    }
+    return api_.download_resource(*ref, dest, options_.max_download_bytes, error);
+}
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/feishu/feishu_transport.hpp b/src/adapters/im/feishu/feishu_transport.hpp
new file mode 100644
index 000000000..657884bfc
--- /dev/null
+++ b/src/adapters/im/feishu/feishu_transport.hpp
@@ -0,0 +1,119 @@
+#pragma once
+
+// 飞书 / Lark 传输层:官方长连接(WebSocket + protobuf 帧)收事件,OpenAPI 发消息。
+//
+// 收:连接前先换令牌、取机器人身份(判定群 @ 用),再请求长连接地址并拨号;每个事件帧
+// 先立即 ACK 再解析交给核心;按 message_id 去重,丢弃 30 分钟前的重投。心跳、读超时、
+// 拆包重组由 LinkSession 决定;掉线后按服务端的 ReconnectNonce / ReconnectInterval
+// 与本地退避重连(每次都重新请求地址,旧地址不复用);凭据无效、连接数超限等致命错误停止重连。
+// 停止时发送 close 帧 —— 否则飞书会把消息继续投给已断开的连接(集群模式下随机分发)。
+//
+// 发:整条消息判定一次是否 Markdown;是则以 post(md 节点,代码块单独成行)发送,被拒时该段
+// 改发纯文本;按 3500 字符 / 28 KB 分段;有触发消息时首段走回复接口(话题内每段都走回复,
+// 留在话题里),回复目标已撤回则改为直接发到会话;每个接收方 ≤ 4 条/秒,被限流按退避重发,
+// 网络错误与 5xx 重发时复用同一个 uuid(平台按 uuid 一小时内去重,不会重复送达)。
+
+#include "im/feishu/feishu_api.hpp"
+#include "im/feishu/feishu_gateway.hpp"
+#include "im/feishu/feishu_pacer.hpp"
+#include "im/transport.hpp"
+#include "network/websocket_client.hpp"
+#include "utils/joining_thread.hpp"
+
+#include <atomic>
+#include <condition_variable>
+#include <deque>
+#include <functional>
+#include <mutex>
+#include <random>
+#include <set>
+#include <vector>
+
+namespace acecode::im::feishu {
+
+struct FeishuTransportOptions {
+    ApiOptions api;
+    // 本地重连退避;拿到服务端 ClientConfig 后与服务端间隔取大。
+    std::vector<std::chrono::milliseconds> backoff{
+        std::chrono::seconds(1), std::chrono::seconds(2), std::chrono::seconds(5),
+        std::chrono::seconds(10), std::chrono::seconds(30), std::chrono::seconds(60)};
+    // 被限流(429 / 99991400 / 230020 …)后的等待,逐次递增,与平台响应头 x-ogw-ratelimit-reset
+    // 取大(封顶 60 秒);用完仍被限流则发送失败。
+    std::vector<std::chrono::milliseconds> rate_limit_backoff{
+        std::chrono::seconds(1), std::chrono::seconds(2), std::chrono::seconds(5),
+        std::chrono::seconds(10), std::chrono::seconds(30)};
+    // 网络错误 / 5xx 的重发等待。
+    std::vector<std::chrono::milliseconds> retry_backoff{std::chrono::milliseconds(500),
+                                                         std::chrono::milliseconds(1500)};
+    std::chrono::milliseconds send_gap{250};                 // 同一接收方相邻两条的最小间隔
+    std::chrono::milliseconds receive_poll{500};             // 读循环每次等待帧的时长
+    std::chrono::milliseconds bot_refresh_interval{std::chrono::minutes(5)};  // 机器人未就绪时的重查间隔
+    LinkSession::Limits link_limits;
+    std::uint64_t max_upload_bytes = kMaxFileBytes;
+    std::uint64_t max_download_bytes = 50u * 1024u * 1024u;
+};
+
+class FeishuTransport final : public Transport {
+public:
+    explicit FeishuTransport(FeishuTransportOptions options);
+    ~FeishuTransport() override;
+
+    std::string platform() const override { return kPlatform; }
+    Capabilities capabilities() const override;
+    void start(TransportCallbacks callbacks) override;
+    void stop() override;
+    TransportStatus status() const override;
+    SendResult send_text(const Address& to, const std::string& text,
+                         const nlohmann::json& reply_context) override;
+    SendResult send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                         const std::string& mime_type, const nlohmann::json& reply_context) override;
+    bool download(const Attachment& attachment, const std::filesystem::path& dest,
+                  std::string* error) override;
+
+    BotIdentity bot() const;
+
+private:
+    enum class Outcome { Failed, Dropped, Fatal, Stopped };
+    struct Attempt {
+        Outcome outcome = Outcome::Failed;
+        std::string message;
+    };
+
+    void run();
+    Attempt connect_and_serve();
+    void serve_connection(Attempt& attempt);
+    void handle_event(const std::string& payload);
+    void refresh_bot();
+    bool wait_for(std::chrono::milliseconds duration);
+    void set_status(LinkState state, const std::string& detail, bool retry_stopped = false, bool force = false);
+    bool seen_before(const std::string& message_id);
+    ApiResult with_retry(const std::string& pace_key, const std::function<ApiResult()>& attempt);
+    ApiResult deliver(SendTarget& target, bool reply, const std::string& msg_type, const nlohmann::json& content);
+    ApiResult upload_file(const std::filesystem::path& path, const std::string& name, const std::string& mime_type,
+                          const FileRoute& route, std::string* key);
+
+    FeishuTransportOptions options_;
+    Api api_;
+    SendPacer pacer_;
+    LinkSession session_;
+    network::WebSocketClient ws_;
+    TransportCallbacks callbacks_;
+    acecode::JoiningThread worker_;
+    std::atomic<bool> running_{false};
+    std::atomic<bool> stopping_{false};
+    bool server_config_ = false;  // 只在 worker 线程读写
+    std::mt19937 rng_;            // 只在 worker 线程使用(重连抖动)
+    std::mutex wake_mu_;
+    std::condition_variable wake_;
+    mutable std::mutex status_mu_;
+    TransportStatus status_;
+    mutable std::mutex bot_mu_;
+    BotIdentity bot_;
+    int activate_status_ = -1;
+    std::chrono::steady_clock::time_point bot_checked_{};
+    std::mutex seen_mu_;
+    std::set<std::string> seen_;
+    std::deque<std::string> seen_order_;
+};
+
+} // namespace acecode::im::feishu
diff --git a/src/adapters/im/http.cpp b/src/adapters/im/http.cpp
new file mode 100644
index 000000000..3d27f575f
--- /dev/null
+++ b/src/adapters/im/http.cpp
@@ -0,0 +1,162 @@
+#include "http.hpp"
+
+#include "im/redact.hpp"
+#include "network/proxy_resolver.hpp"
+#include "utils/utf8_path.hpp"
+#include "version.hpp"
+
+#include <cpr/cpr.h>
+
+#include <algorithm>
+#include <cctype>
+#include <fstream>
+#include <iterator>
+
+namespace acecode::im {
+namespace {
+
+// multipart 的文件名在 Windows 上会经 path::string() 转成 ANSI 代码页,遇到代码页
+// 表示不了的字符(emoji 等)直接抛异常;这里统一降为 ASCII,原名由调用方另行展示。
+std::string ascii_filename(const std::string& name) {
+    std::string out;
+    for (const char c : name) {
+        const auto u = static_cast<unsigned char>(c);
+        out.push_back(u >= 0x20 && u < 0x7F && c != '"' && c != '\\' && c != '/' ? c : '_');
+    }
+    const auto dot = out.find_last_of('.');
+    const auto stem = out.substr(0, dot == std::string::npos ? out.size() : dot);
+    if (stem.find_first_not_of('_') == std::string::npos)
+        out = "file" + (dot == std::string::npos ? std::string() : out.substr(dot));
+    return out;
+}
+
+std::string read_file(const std::filesystem::path& path) {
+    std::ifstream in(path, std::ios::binary);
+    if (!in) throw std::runtime_error("Cannot read upload file");
+    return std::string((std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>());
+}
+
+} // namespace
+
+std::string user_agent() { return std::string("ACECode/") + ACECODE_VERSION; }
+
+HttpResponse http_send(const HttpRequest& request) {
+    HttpResponse result;
+    cpr::Session session;
+    session.SetUrl(cpr::Url{request.url});
+    cpr::Header header;
+    for (const auto& [name, value] : request.headers) header[name] = value;
+    if (header.find("User-Agent") == header.end()) header["User-Agent"] = user_agent();
+    session.SetHeader(header);
+    session.SetTimeout(cpr::Timeout{request.timeout});
+    session.SetConnectTimeout(cpr::ConnectTimeout{std::min<std::chrono::milliseconds>(
+        request.timeout, std::chrono::seconds(15))});
+    if (request.use_proxy) {
+        auto options = network::proxy_options_for(request.url);
+        session.SetSslOptions(network::build_ssl_options(options));
+        session.SetProxies(std::move(options.proxies));
+        session.SetProxyAuth(std::move(options.auth));
+    } else {
+        session.SetProxies(cpr::Proxies{{"http", ""}, {"https", ""}});
+        session.SetSslOptions(cpr::Ssl(cpr::ssl::NoRevoke{true}));
+    }
+
+    if (request.cancel) {
+        session.SetProgressCallback(cpr::ProgressCallback{
+            [&cancel = request.cancel](cpr::cpr_pf_arg_t, cpr::cpr_pf_arg_t, cpr::cpr_pf_arg_t, cpr::cpr_pf_arg_t,
+                                       intptr_t) {
+                return !cancel();
+            }});
+    }
+
+    cpr::Response response;
+    try {
+        if (!request.download_to.empty()) {
+            std::ofstream out(request.download_to, std::ios::binary | std::ios::trunc);
+            if (!out) {
+                result.error = "Cannot create download file";
+                return result;
+            }
+            std::uint64_t written = 0;
+            bool too_large = false;
+            const auto limit = request.max_download_bytes;
+            response = session.Download(cpr::WriteCallback{[&written, &too_large, &out, limit](std::string_view data,
+                                                                                                intptr_t) {
+                written += data.size();
+                if (limit && written > limit) {
+                    too_large = true;
+                    return false;  // 中止传输
+                }
+                out.write(data.data(), static_cast<std::streamsize>(data.size()));
+                return static_cast<bool>(out);
+            }});
+            out.close();
+            if (too_large) {
+                std::error_code ec;
+                std::filesystem::remove(request.download_to, ec);
+                result.status = response.status_code;
+                result.too_large = true;
+                result.error = "Download exceeds limit";
+                return result;
+            }
+        } else if (!request.parts.empty()) {
+            cpr::Multipart multipart{};
+            std::vector<std::string> buffers;  // Buffer 只保存指针,数据要活到请求结束
+            buffers.reserve(request.parts.size());
+            for (const auto& part : request.parts) {
+                if (part.file.empty()) {
+                    multipart.parts.emplace_back(part.name, part.value, part.content_type);
+                    continue;
+                }
+                buffers.push_back(read_file(part.file));
+                const auto& data = buffers.back();
+                const auto name = ascii_filename(part.filename.empty() ? path_to_utf8(part.file.filename())
+                                                                       : part.filename);
+                multipart.parts.emplace_back(
+                    part.name, cpr::Buffer{data.begin(), data.end(), std::filesystem::path(name)},
+                    part.content_type);
+            }
+            session.SetMultipart(std::move(multipart));
+            response = session.Post();
+        } else if (request.method == "POST") {
+            session.SetBody(cpr::Body{request.body});
+            response = session.Post();
+        } else if (request.method == "PUT") {
+            session.SetBody(cpr::Body{request.body});
+            response = session.Put();
+        } else if (request.method == "PATCH") {
+            session.SetBody(cpr::Body{request.body});
+            response = session.Patch();
+        } else if (request.method == "DELETE") {
+            if (!request.body.empty()) session.SetBody(cpr::Body{request.body});
+            response = session.Delete();
+        } else {
+            response = session.Get();
+        }
+    } catch (const std::exception& e) {
+        result.error = redact_secrets(e.what());
+        return result;
+    }
+    if (request.cancel && request.cancel()) {
+        result.cancelled = true;
+        result.error = "Request cancelled";
+        return result;
+    }
+    if (response.error.code != cpr::ErrorCode::OK) {
+        result.error = redact_secrets(response.error.message.empty() ? "HTTP request failed"
+                                                                    : response.error.message);
+        result.status = response.status_code;
+        return result;
+    }
+    result.status = response.status_code;
+    result.body = std::move(response.text);
+    for (const auto& [name, value] : response.header) {
+        std::string key = name;
+        std::transform(key.begin(), key.end(), key.begin(),
+                       [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+        result.headers[key] = value;
+    }
+    return result;
+}
+
+} // namespace acecode::im
diff --git a/src/adapters/im/http.hpp b/src/adapters/im/http.hpp
new file mode 100644
index 000000000..aff948574
--- /dev/null
+++ b/src/adapters/im/http.hpp
@@ -0,0 +1,53 @@
+#pragma once
+
+// IM 传输层共用的 HTTP 调用(cpr)。代理与 TLS 选项与仓库其它 cpr 调用点同源
+// (ProxyResolver + NoRevoke);测试连本机假服务时可关闭代理。
+
+#include <chrono>
+#include <cstdint>
+#include <filesystem>
+#include <functional>
+#include <map>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace acecode::im {
+
+struct HttpPart {
+    std::string name;
+    std::string value;              // 普通字段的值
+    std::filesystem::path file;     // 非空时作为文件字段上传(整读进内存)
+    std::string filename;           // 文件字段对外显示的文件名
+    std::string content_type;
+};
+
+struct HttpRequest {
+    std::string method = "GET";     // GET / POST / PUT / PATCH / DELETE
+    std::string url;
+    std::vector<std::pair<std::string, std::string>> headers;
+    std::string body;               // 原始请求体(JSON)
+    std::vector<HttpPart> parts;    // 非空时按 multipart/form-data 发送
+    std::chrono::milliseconds timeout{std::chrono::seconds(30)};
+    bool use_proxy = true;
+    std::filesystem::path download_to;   // 非空时把响应体写入该文件
+    std::uint64_t max_download_bytes = 0;  // 0 = 不限
+    // 返回 true 时中止请求(长轮询停机用);libcurl 大约每秒检查一次。
+    std::function<bool()> cancel;
+};
+
+struct HttpResponse {
+    long status = 0;        // 0 = 没拿到 HTTP 响应(连接失败、超时、被取消)
+    std::string body;
+    std::map<std::string, std::string> headers;  // 响应头,键为小写(如微信 CDN 的 x-encrypted-param)
+    std::string error;      // 传输层错误;已脱敏
+    bool too_large = false; // 下载超过 max_download_bytes,文件已删除
+    bool cancelled = false; // 被 HttpRequest::cancel 中止
+};
+
+HttpResponse http_send(const HttpRequest& request);
+
+// "ACECode/<版本>",所有 IM 平台请求都带上,方便平台识别来源。
+std::string user_agent();
+
+} // namespace acecode::im
diff --git a/src/adapters/im/line/line_api.cpp b/src/adapters/im/line/line_api.cpp
new file mode 100644
index 000000000..7b7695e7e
--- /dev/null
+++ b/src/adapters/im/line/line_api.cpp
@@ -0,0 +1,448 @@
+#include "im/line/line_api.hpp"
+
+#include "im/line/line_protocol.hpp"
+#include "im/redact.hpp"
+#include "platform/crypto/secure_random.hpp"
+
+#include <algorithm>
+#include <thread>
+
+namespace acecode::im::line {
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+std::string trim_slash(std::string base) {
+    while (!base.empty() && base.back() == '/') base.pop_back();
+    return base;
+}
+
+std::string json_str(const nlohmann::json& object, const char* key) {
+    if (!object.is_object()) return {};
+    const auto it = object.find(key);
+    return it != object.end() && it->is_string() ? it->get<std::string>() : std::string{};
+}
+
+// 可取消的等待;返回 false 表示被取消。
+bool wait_cancellable(std::chrono::milliseconds duration, const CancelFn& cancel) {
+    const auto deadline = Clock::now() + duration;
+    while (Clock::now() < deadline) {
+        if (cancel && cancel()) return false;
+        const auto left = std::chrono::duration_cast<std::chrono::milliseconds>(deadline - Clock::now());
+        std::this_thread::sleep_for((std::min)(left, std::chrono::milliseconds(50)));
+    }
+    return !(cancel && cancel());
+}
+
+constexpr const char* kInvalidIdSecret = "Channel ID 或 Channel secret 无效,请在 LINE Developers Console 的 Basic settings 页核对";
+constexpr const char* kInvalidLongLived = "Channel access token 无效或已失效,请重新签发,或改用 Channel ID + Channel secret";
+
+} // namespace
+
+Api::Api(ApiOptions options) : options_(std::move(options)) {
+    options_.api_base = trim_slash(options_.api_base);
+    options_.data_api_base = trim_slash(options_.data_api_base);
+}
+
+std::vector<std::string> Api::secrets() const {
+    std::vector<std::string> out{options_.channel_secret, options_.access_token};
+    std::lock_guard<std::mutex> lock(mu_);
+    if (!token_.empty()) out.push_back(token_);
+    return out;
+}
+
+std::string Api::mint_locked(std::string* error, bool* auth_failed, const CancelFn& cancel) {
+    HttpRequest request;
+    request.method = "POST";
+    request.url = options_.api_base + "/oauth2/v3/token";
+    request.headers = {{"Content-Type", "application/x-www-form-urlencoded"}};
+    request.body = "grant_type=client_credentials&client_id=" + percent_encode(options_.channel_id) +
+                   "&client_secret=" + percent_encode(options_.channel_secret);
+    request.timeout = options_.timeout;
+    request.use_proxy = options_.use_proxy;
+    if (cancel) request.cancel = cancel;
+    const auto response = http_send(request);
+    const std::vector<std::string> secrets{options_.channel_secret, options_.access_token};
+    if (response.status == 0) {
+        if (error) {
+            *error = redact_secrets(response.error.empty() ? std::string("无法连接 LINE")
+                                                           : "无法连接 LINE:" + response.error,
+                                    secrets);
+        }
+        return {};
+    }
+    if (response.status == 400 || response.status == 401) {
+        // 换取令牌被拒只可能是 Channel ID / secret 不对(或频道被删除),不会自己好。
+        if (auth_failed) *auth_failed = true;
+        if (error) *error = kInvalidIdSecret;
+        return {};
+    }
+    if (response.status < 200 || response.status >= 300) {
+        if (error) *error = "LINE 令牌服务暂时不可用(HTTP " + std::to_string(response.status) + ")";
+        return {};
+    }
+    try {
+        const auto json = nlohmann::json::parse(response.body);
+        const auto token = json_str(json, "access_token");
+        if (!token.empty()) {
+            long long seconds = 900;
+            if (json.contains("expires_in") && json["expires_in"].is_number_integer())
+                seconds = json["expires_in"].get<long long>();
+            // 到期前 60 秒重换;有效期很短时至少留一半。
+            const long long margin = (std::min)(60LL, (std::max)(seconds / 2, 1LL));
+            token_ = token;
+            refresh_at_ = Clock::now() + std::chrono::seconds((std::max)(seconds - margin, 1LL));
+            return token_;
+        }
+    } catch (...) {
+    }
+    if (error) *error = "LINE 令牌服务返回了无效数据";
+    return {};
+}
+
+std::string Api::access_token(std::string* error, bool* auth_failed, const CancelFn& cancel) {
+    if (auth_failed) *auth_failed = false;
+    if (!options_.access_token.empty()) return options_.access_token;
+    std::lock_guard<std::mutex> lock(mu_);
+    if (!token_.empty() && Clock::now() < refresh_at_) return token_;
+    token_.clear();
+    if (options_.channel_id.empty() || options_.channel_secret.empty()) {
+        if (auth_failed) *auth_failed = true;
+        if (error) *error = "缺少 Channel ID 或 Channel secret";
+        return {};
+    }
+    return mint_locked(error, auth_failed, cancel);
+}
+
+void Api::invalidate_token() {
+    std::lock_guard<std::mutex> lock(mu_);
+    token_.clear();
+    refresh_at_ = {};
+}
+
+ApiResult Api::parse(const HttpResponse& response) const {
+    ApiResult result;
+    result.status = response.status;
+    result.cancelled = response.cancelled;
+    const auto hidden = secrets();
+    if (response.status == 0) {
+        result.message = redact_secrets(response.error.empty() ? std::string("无法连接 LINE")
+                                                               : "无法连接 LINE:" + response.error,
+                                        hidden);
+        return result;
+    }
+    result.ok = response.status >= 200 && response.status < 300;
+    if (!response.body.empty()) {
+        try {
+            auto json = nlohmann::json::parse(response.body);
+            if (json.is_object()) result.body = std::move(json);
+        } catch (...) {
+        }
+    }
+    std::string message = json_str(result.body, "message");
+    if (message.empty()) message = json_str(result.body, "error_description");
+    if (message.empty()) message = json_str(result.body, "error");
+    if (result.body.is_object() && result.body.contains("details") && result.body["details"].is_array() &&
+        !result.body["details"].empty()) {
+        const auto& detail = result.body["details"].front();
+        const auto text = json_str(detail, "message");
+        const auto property = json_str(detail, "property");
+        if (!text.empty()) message += " (" + (property.empty() ? text : property + ": " + text) + ")";
+    }
+    if (!result.ok && message.empty()) message = "LINE 请求失败(HTTP " + std::to_string(response.status) + ")";
+    result.message = redact_secrets(message, hidden);
+    return result;
+}
+
+ApiResult Api::call(const std::string& method, const std::string& base, const std::string& path,
+                    const std::string& body, const std::vector<std::pair<std::string, std::string>>& headers,
+                    const CancelFn& cancel) {
+    ApiResult result;
+    for (int attempt = 0; attempt < 2; ++attempt) {
+        std::string error;
+        bool auth_failed = false;
+        const auto token = access_token(&error, &auth_failed, cancel);
+        if (token.empty()) {
+            result = ApiResult{};
+            result.auth_failed = auth_failed;
+            result.message = error;
+            result.cancelled = cancel && cancel();
+            return result;
+        }
+        HttpRequest request;
+        request.method = method;
+        request.url = base + path;
+        request.headers = {{"Authorization", "Bearer " + token}};
+        if (method != "GET") request.headers.emplace_back("Content-Type", "application/json");
+        for (const auto& header : headers) request.headers.push_back(header);
+        request.body = body;
+        request.timeout = options_.timeout;
+        request.use_proxy = options_.use_proxy;
+        if (cancel) request.cancel = cancel;
+        result = parse(http_send(request));
+        if (result.status == 401) {
+            // 无状态令牌可能刚好过期或被平台提前作废:重换一次再试;长期令牌 401 就是失效了。
+            if (!uses_long_lived_token() && attempt == 0) {
+                invalidate_token();
+                continue;
+            }
+            result.auth_failed = true;
+            result.message = uses_long_lived_token() ? kInvalidLongLived : kInvalidIdSecret;
+        }
+        return result;
+    }
+    return result;
+}
+
+ApiResult Api::get(const std::string& path, const CancelFn& cancel) {
+    return call("GET", options_.api_base, path, {}, {}, cancel);
+}
+
+// 模型输出偶尔夹带非法 UTF-8;dump 默认会抛异常,这里替换成 U+FFFD,不让一次发送把线程打崩。
+static std::string dump_json(const nlohmann::json& body) {
+    return body.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace);
+}
+
+ApiResult Api::post(const std::string& path, const nlohmann::json& body,
+                    const std::vector<std::pair<std::string, std::string>>& headers, const CancelFn& cancel) {
+    return call("POST", options_.api_base, path, dump_json(body), headers, cancel);
+}
+
+ApiResult Api::put(const std::string& path, const nlohmann::json& body, const CancelFn& cancel) {
+    return call("PUT", options_.api_base, path, dump_json(body), {}, cancel);
+}
+
+ApiResult Api::bot_info(BotInfo* info, const CancelFn& cancel) {
+    auto result = get("/v2/bot/info", cancel);
+    if (result.ok && info) {
+        info->user_id = json_str(result.body, "userId");
+        info->basic_id = json_str(result.body, "basicId");
+        info->display_name = json_str(result.body, "displayName");
+        info->picture_url = json_str(result.body, "pictureUrl");
+        info->chat_mode = json_str(result.body, "chatMode");
+    }
+    return result;
+}
+
+ApiResult Api::webhook_info(WebhookInfo* info, const CancelFn& cancel) {
+    auto result = get("/v2/bot/channel/webhook/endpoint", cancel);
+    if (info) {
+        *info = WebhookInfo{};
+        if (result.ok) {
+            info->exists = true;
+            info->endpoint = json_str(result.body, "endpoint");
+            info->active = json_bool(result.body, "active");
+        }
+    }
+    return result;
+}
+
+ApiResult Api::set_webhook(const std::string& endpoint, const CancelFn& cancel) {
+    return put("/v2/bot/channel/webhook/endpoint", {{"endpoint", endpoint}}, cancel);
+}
+
+ApiResult Api::test_webhook(const std::string& endpoint, const CancelFn& cancel) {
+    return post("/v2/bot/channel/webhook/test", {{"endpoint", endpoint}}, {}, cancel);
+}
+
+ApiResult Api::reply(const std::string& reply_token, const nlohmann::json& messages) {
+    // 回复不能带 X-Line-Retry-Key(会被 400 拒绝)。
+    return post("/v2/bot/message/reply", {{"replyToken", reply_token}, {"messages", messages}});
+}
+
+ApiResult Api::push(const std::string& to, const nlohmann::json& messages, const std::string& retry_key) {
+    std::vector<std::pair<std::string, std::string>> headers;
+    if (!retry_key.empty()) headers.emplace_back("X-Line-Retry-Key", retry_key);
+    return post("/v2/bot/message/push", {{"to", to}, {"messages", messages}}, headers);
+}
+
+ApiResult Api::start_loading(const std::string& chat_id, int seconds) {
+    // 只接受 5 的倍数,范围 5..60。
+    seconds = (std::max)(5, (std::min)(60, seconds));
+    seconds -= seconds % 5;
+    return post("/v2/bot/chat/loading/start", {{"chatId", chat_id}, {"loadingSeconds", seconds}});
+}
+
+ApiResult Api::display_name(const std::string& chat_id, const std::string& user_id, std::string* name) {
+    std::string path;
+    if (!chat_id.empty() && chat_id[0] == 'C')
+        path = "/v2/bot/group/" + percent_encode(chat_id) + "/member/" + percent_encode(user_id);
+    else if (!chat_id.empty() && chat_id[0] == 'R')
+        path = "/v2/bot/room/" + percent_encode(chat_id) + "/member/" + percent_encode(user_id);
+    else
+        path = "/v2/bot/profile/" + percent_encode(user_id);
+    auto result = get(path);
+    if (result.ok && name) *name = json_str(result.body, "displayName");
+    return result;
+}
+
+ApiResult Api::quota(nlohmann::json* summary, const CancelFn& cancel) {
+    auto limit = get("/v2/bot/message/quota", cancel);
+    if (!limit.ok) return limit;
+    auto usage = get("/v2/bot/message/quota/consumption", cancel);
+    if (summary) {
+        *summary = nlohmann::json::object();
+        (*summary)["type"] = json_str(limit.body, "type");
+        if (limit.body.is_object() && limit.body.contains("value")) (*summary)["value"] = limit.body["value"];
+        if (usage.ok && usage.body.is_object() && usage.body.contains("totalUsage"))
+            (*summary)["used"] = usage.body["totalUsage"];
+    }
+    return usage.ok ? limit : usage;
+}
+
+bool Api::fetch_content(const std::string& url, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                        bool with_auth, HttpResponse* out, const CancelFn& cancel) {
+    HttpRequest request;
+    request.url = url;
+    if (with_auth) {
+        std::string error;
+        bool auth_failed = false;
+        const auto token = access_token(&error, &auth_failed, cancel);
+        if (token.empty()) {
+            out->status = 0;
+            out->error = error;
+            return false;
+        }
+        request.headers = {{"Authorization", "Bearer " + token}};
+    }
+    request.timeout = std::chrono::minutes(2);
+    request.use_proxy = options_.use_proxy;
+    request.download_to = dest;
+    request.max_download_bytes = max_bytes;
+    if (cancel) request.cancel = cancel;
+    *out = http_send(request);
+    return out->status >= 200 && out->status < 300 && out->status != 202 && !out->too_large;
+}
+
+bool Api::download_content(const std::string& message_id, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                           std::string* error, const CancelFn& cancel) {
+    const auto content = "/v2/bot/message/" + percent_encode(message_id) + "/content";
+    bool refreshed = false;
+    int waits = 0;
+    while (true) {
+        HttpResponse response;
+        if (fetch_content(options_.data_api_base + content, dest, max_bytes, true, &response, cancel)) return true;
+        std::error_code ec;
+        std::filesystem::remove(dest, ec);
+        if (response.too_large) {
+            if (error) *error = "附件超过大小限制";
+            return false;
+        }
+        if (response.status == 401 && !refreshed && !uses_long_lived_token()) {
+            refreshed = true;
+            invalidate_token();
+            continue;
+        }
+        if (response.status == 202) {
+            // 视频 / 音频转码中:按 /content/transcoding 的状态等待。
+            if (++waits > options_.transcoding_attempts) {
+                if (error) *error = "LINE 仍在处理该附件,请稍后重发";
+                return false;
+            }
+            const auto state = call("GET", options_.data_api_base, content + "/transcoding", {}, {}, cancel);
+            const auto status = json_str(state.body, "status");
+            if (status == "failed") {
+                if (error) *error = "LINE 无法处理该附件";
+                return false;
+            }
+            if (status != "succeeded" && !wait_cancellable(options_.transcoding_poll, cancel)) {
+                if (error) *error = "下载已取消";
+                return false;
+            }
+            continue;
+        }
+        if (error) {
+            if (response.status == 404) *error = "附件不存在或已过期";
+            else if (response.status == 410) *error = "对方已撤回该消息";
+            else if (response.status == 401) *error = uses_long_lived_token() ? kInvalidLongLived : kInvalidIdSecret;
+            else if (response.status == 0)
+                *error = redact_secrets("下载附件失败:" + (response.error.empty() ? std::string("无法连接 LINE")
+                                                                                : response.error),
+                                        secrets());
+            else *error = "下载附件失败:HTTP " + std::to_string(response.status);
+        }
+        return false;
+    }
+}
+
+bool Api::download_url(const std::string& url, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                       std::string* error, const CancelFn& cancel) {
+    if (url.rfind("https://", 0) != 0 && url.rfind("http://", 0) != 0) {
+        if (error) *error = "附件地址无效";
+        return false;
+    }
+    HttpResponse response;
+    if (fetch_content(url, dest, max_bytes, false, &response, cancel)) return true;
+    std::error_code ec;
+    std::filesystem::remove(dest, ec);
+    if (error) {
+        if (response.too_large) *error = "附件超过大小限制";
+        else if (response.status == 0) *error = redact_secrets("下载附件失败:" + response.error, secrets());
+        else *error = "下载附件失败:HTTP " + std::to_string(response.status);
+    }
+    return false;
+}
+
+std::string new_retry_key() {
+    auto bytes = platform::secure_random_bytes(16);
+    if (bytes.size() != 16) return {};
+    bytes[6] = static_cast<char>((static_cast<unsigned char>(bytes[6]) & 0x0Fu) | 0x40u);
+    bytes[8] = static_cast<char>((static_cast<unsigned char>(bytes[8]) & 0x3Fu) | 0x80u);
+    static constexpr char kHex[] = "0123456789abcdef";
+    std::string out;
+    for (std::size_t i = 0; i < bytes.size(); ++i) {
+        if (i == 4 || i == 6 || i == 8 || i == 10) out.push_back('-');
+        const auto u = static_cast<unsigned char>(bytes[i]);
+        out.push_back(kHex[u >> 4]);
+        out.push_back(kHex[u & 0x0F]);
+    }
+    return out;
+}
+
+Validation validate_credentials(const ApiOptions& options) {
+    Validation validation;
+    if (options.channel_secret.empty()) {
+        validation.error = "请填写 Channel secret(LINE Developers Console 的 Basic settings 页)";
+        return validation;
+    }
+    if (options.channel_id.empty() && options.access_token.empty()) {
+        validation.error = "请填写 Channel ID(LINE Developers Console 的 Basic settings 页)";
+        return validation;
+    }
+    if (!options.channel_id.empty() && !options.access_token.empty()) {
+        // 同时给了长期令牌:仍用 Channel ID + secret 换一次令牌,确认 secret 正确(回调签名要用它)。
+        auto minting = options;
+        minting.access_token.clear();
+        Api minter(minting);
+        std::string error;
+        bool auth_failed = false;
+        if (minter.access_token(&error, &auth_failed).empty()) {
+            validation.network_error = !auth_failed;
+            validation.error = auth_failed ? std::string(kInvalidIdSecret) : error;
+            return validation;
+        }
+    }
+    Api api(options);
+    BotInfo bot;
+    const auto result = api.bot_info(&bot);
+    if (!result.ok) {
+        if (result.auth_failed) {
+            validation.error = api.uses_long_lived_token() ? kInvalidLongLived : kInvalidIdSecret;
+        } else if (result.status == 0) {
+            validation.network_error = true;
+            validation.error = result.message.empty() ? std::string("无法连接 LINE") : result.message;
+        } else {
+            validation.error = "LINE 校验失败:" + result.message;
+        }
+        return validation;
+    }
+    if (bot.user_id.empty()) {
+        validation.error = "LINE 返回的机器人信息无效";
+        return validation;
+    }
+    validation.ok = true;
+    validation.bot = bot;
+    return validation;
+}
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/line/line_api.hpp b/src/adapters/im/line/line_api.hpp
new file mode 100644
index 000000000..0e76c9d93
--- /dev/null
+++ b/src/adapters/im/line/line_api.hpp
@@ -0,0 +1,133 @@
+#pragma once
+
+// LINE Messaging API 客户端:频道访问令牌、机器人信息、webhook 地址、回复 / 推送、
+// “正在输入”动画、用户名、配额、附件下载。所有 HTTP 走 im::http_send。
+//
+// 令牌:默认用 Channel ID + Channel secret 换取无状态令牌(15 分钟有效,到期前 60 秒或
+// 遇到 401 时重换,换取过程串行化);用户另外粘贴了长期令牌时直接用它(401 即凭据失效)。
+// 线程安全:可在多个线程同时调用。
+
+#include "im/http.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <filesystem>
+#include <functional>
+#include <mutex>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace acecode::im::line {
+
+inline constexpr const char* kApiBase = "https://api.line.me";
+inline constexpr const char* kDataApiBase = "https://api-data.line.me";
+
+struct ApiOptions {
+    std::string channel_id;
+    std::string channel_secret;
+    std::string access_token;  // 可选:长期令牌;非空时不再换取无状态令牌
+    std::string api_base = kApiBase;
+    std::string data_api_base = kDataApiBase;
+    bool use_proxy = true;
+    std::chrono::milliseconds timeout{std::chrono::seconds(15)};
+    // 内容转码(202)时轮询 /content/transcoding 的间隔与次数。
+    std::chrono::milliseconds transcoding_poll{std::chrono::seconds(2)};
+    int transcoding_attempts = 30;
+};
+
+struct ApiResult {
+    bool ok = false;           // HTTP 2xx
+    long status = 0;           // 0 = 没拿到 HTTP 响应
+    nlohmann::json body;       // 解析后的 JSON(没有或无效时为 null)
+    std::string message;       // 已脱敏的原因(LINE 的 message / error_description 或网络错误)
+    bool auth_failed = false;  // 凭据或令牌被拒(不会自己好)
+    bool cancelled = false;
+};
+
+struct BotInfo {
+    std::string user_id;       // 机器人 userId(Address::account)
+    std::string basic_id;      // @xxxx
+    std::string display_name;
+    std::string picture_url;
+    std::string chat_mode;     // chat / bot
+};
+
+struct WebhookInfo {
+    bool exists = false;       // false:还没设置过 webhook 地址(404)
+    std::string endpoint;
+    bool active = false;       // “Use webhook” 开关(只能在控制台改)
+};
+
+using CancelFn = std::function<bool()>;
+
+class Api {
+public:
+    explicit Api(ApiOptions options);
+
+    // 有效令牌;失败返回空串,error 为不含凭据的中文原因,auth_failed 表示凭据被拒。
+    std::string access_token(std::string* error, bool* auth_failed = nullptr, const CancelFn& cancel = {});
+    void invalidate_token();
+    bool uses_long_lived_token() const { return !options_.access_token.empty(); }
+
+    ApiResult get(const std::string& path, const CancelFn& cancel = {});
+    ApiResult post(const std::string& path, const nlohmann::json& body,
+                   const std::vector<std::pair<std::string, std::string>>& headers = {}, const CancelFn& cancel = {});
+    ApiResult put(const std::string& path, const nlohmann::json& body, const CancelFn& cancel = {});
+
+    ApiResult bot_info(BotInfo* info, const CancelFn& cancel = {});
+    ApiResult webhook_info(WebhookInfo* info, const CancelFn& cancel = {});
+    ApiResult set_webhook(const std::string& endpoint, const CancelFn& cancel = {});
+    ApiResult test_webhook(const std::string& endpoint, const CancelFn& cancel = {});
+    ApiResult reply(const std::string& reply_token, const nlohmann::json& messages);
+    // retry_key 用 new_retry_key() 生成;同一批消息重试时必须沿用同一个。
+    ApiResult push(const std::string& to, const nlohmann::json& messages, const std::string& retry_key);
+    ApiResult start_loading(const std::string& chat_id, int seconds);
+    // 私聊取用户资料,群 / 多人聊天取成员资料(只要显示名)。
+    ApiResult display_name(const std::string& chat_id, const std::string& user_id, std::string* name);
+    ApiResult quota(nlohmann::json* summary, const CancelFn& cancel = {});
+
+    // 下载消息内容(图片 / 视频 / 音频 / 文件);视频音频转码中(202)时等待转码完成。
+    // 超过 max_bytes 失败并删除半截文件。
+    bool download_content(const std::string& message_id, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                          std::string* error, const CancelFn& cancel = {});
+    // 外部内容(contentProvider.type = external)的地址:不带鉴权直接下载。
+    bool download_url(const std::string& url, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                      std::string* error, const CancelFn& cancel = {});
+
+    const ApiOptions& options() const { return options_; }
+    // 需要从日志与错误文本里抹掉的值(Channel secret、长期令牌、当前无状态令牌)。
+    std::vector<std::string> secrets() const;
+
+private:
+    ApiResult call(const std::string& method, const std::string& base, const std::string& path,
+                   const std::string& body, const std::vector<std::pair<std::string, std::string>>& headers,
+                   const CancelFn& cancel);
+    ApiResult parse(const HttpResponse& response) const;
+    std::string mint_locked(std::string* error, bool* auth_failed, const CancelFn& cancel);
+    bool fetch_content(const std::string& url, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                       bool with_auth, HttpResponse* out, const CancelFn& cancel);
+
+    ApiOptions options_;
+    mutable std::mutex mu_;
+    std::string token_;
+    std::chrono::steady_clock::time_point refresh_at_{};
+};
+
+// UUID v4(X-Line-Retry-Key);随机数失败时返回空串(调用方不带重试键发送,且不重试)。
+std::string new_retry_key();
+
+struct Validation {
+    bool ok = false;
+    bool network_error = false;  // 网络不通(区别于凭据无效)
+    std::string error;           // 中文、一句话、不含凭据
+    BotInfo bot;
+};
+
+// 保存凭据前的联网校验:Channel ID + secret 换取令牌(填了长期令牌时改用长期令牌),
+// 再读 /v2/bot/info。成功时给出机器人 userId、basicId 与名称。
+Validation validate_credentials(const ApiOptions& options);
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/line/line_media.cpp b/src/adapters/im/line/line_media.cpp
new file mode 100644
index 000000000..ea56441bb
--- /dev/null
+++ b/src/adapters/im/line/line_media.cpp
@@ -0,0 +1,72 @@
+#include "im/line/line_media.hpp"
+
+#include "im/line/line_protocol.hpp"
+#include "platform/crypto/secure_random.hpp"
+
+#include <cstring>
+
+namespace acecode::im::line {
+
+MediaRegistry::MediaRegistry(std::chrono::milliseconds ttl, std::size_t max_entries)
+    : ttl_(ttl), max_entries_(max_entries == 0 ? 1 : max_entries) {}
+
+void MediaRegistry::prune_locked(Clock::time_point now) {
+    for (auto it = entries_.begin(); it != entries_.end();) {
+        if (it->second.expires_at <= now) it = entries_.erase(it);
+        else ++it;
+    }
+    while (entries_.size() >= max_entries_) {
+        auto oldest = entries_.begin();
+        for (auto it = entries_.begin(); it != entries_.end(); ++it)
+            if (it->second.expires_at < oldest->second.expires_at) oldest = it;
+        entries_.erase(oldest);
+    }
+}
+
+std::string MediaRegistry::add(const std::filesystem::path& path, const std::string& name,
+                               const std::string& mime_type, Clock::time_point now) {
+    const auto token = platform::secure_random_token(32);
+    if (token.size() != 32) return {};
+    Entry entry;
+    entry.path = path;
+    entry.name = safe_file_name(name.empty() ? std::string("image") : name);
+    entry.mime_type = mime_type;
+    entry.expires_at = now + ttl_;
+    std::lock_guard<std::mutex> lock(mu_);
+    prune_locked(now);
+    const auto relative = token + "/" + entry.name;
+    entries_[token] = std::move(entry);
+    return relative;
+}
+
+std::optional<MediaRegistry::Entry> MediaRegistry::find(const std::string& token, const std::string& name,
+                                                        Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto it = entries_.find(token);
+    if (it == entries_.end()) return std::nullopt;
+    if (it->second.expires_at <= now) {
+        entries_.erase(it);
+        return std::nullopt;
+    }
+    if (it->second.name != name) return std::nullopt;
+    return it->second;
+}
+
+std::optional<MediaRegistry::Entry> MediaRegistry::find_path(const std::string& url_path, Clock::time_point now) {
+    const std::size_t prefix = std::strlen(kMediaRoutePrefix);
+    if (url_path.compare(0, prefix, kMediaRoutePrefix) != 0) return std::nullopt;
+    const auto rest = url_path.substr(prefix);
+    const auto slash = rest.find('/');
+    if (slash == std::string::npos || slash == 0 || slash + 1 >= rest.size()) return std::nullopt;
+    const auto token = rest.substr(0, slash);
+    const auto name = rest.substr(slash + 1);
+    if (name.find('/') != std::string::npos) return std::nullopt;
+    return find(token, name, now);
+}
+
+std::size_t MediaRegistry::size() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return entries_.size();
+}
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/line/line_media.hpp b/src/adapters/im/line/line_media.hpp
new file mode 100644
index 000000000..3c856a4e7
--- /dev/null
+++ b/src/adapters/im/line/line_media.hpp
@@ -0,0 +1,53 @@
+#pragma once
+
+// LINE 出站图片的临时公网链接登记表。LINE 机器人只能按公网 HTTPS 地址发图片,
+// 传输层把要发的文件登记在这里,经本机 webhook 端口的 /line/media/<令牌>/<文件名> 提供下载:
+//   - 令牌 32 个 URL 安全随机字符,链接默认 30 分钟后失效;
+//   - 只按令牌精确查找,文件名也必须一致;返回的永远是登记时的路径,URL 里的内容
+//     绝不参与拼接路径,不存在目录穿越;
+//   - 登记表有条数上限,超出时丢最旧的。
+
+#include <chrono>
+#include <cstddef>
+#include <filesystem>
+#include <map>
+#include <mutex>
+#include <optional>
+#include <string>
+
+namespace acecode::im::line {
+
+inline constexpr const char* kMediaRoutePrefix = "/line/media/";
+
+class MediaRegistry {
+public:
+    using Clock = std::chrono::steady_clock;
+
+    struct Entry {
+        std::filesystem::path path;
+        std::string name;       // URL 里的文件名(已清洗)
+        std::string mime_type;
+        Clock::time_point expires_at;
+    };
+
+    explicit MediaRegistry(std::chrono::milliseconds ttl = std::chrono::minutes(30), std::size_t max_entries = 256);
+
+    // 返回 "<令牌>/<文件名>"(拼在 <公网地址>/line/media/ 之后);随机数失败时返回空串。
+    std::string add(const std::filesystem::path& path, const std::string& name, const std::string& mime_type,
+                    Clock::time_point now = Clock::now());
+    // 令牌不存在、已过期或文件名不一致时返回 nullopt。
+    std::optional<Entry> find(const std::string& token, const std::string& name, Clock::time_point now = Clock::now());
+    // 解析 /line/media/<令牌>/<文件名> 并查找;路径格式不对返回 nullopt。
+    std::optional<Entry> find_path(const std::string& url_path, Clock::time_point now = Clock::now());
+    std::size_t size() const;
+
+private:
+    void prune_locked(Clock::time_point now);
+
+    std::chrono::milliseconds ttl_;
+    std::size_t max_entries_;
+    mutable std::mutex mu_;
+    std::map<std::string, Entry> entries_;
+};
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/line/line_outbound.cpp b/src/adapters/im/line/line_outbound.cpp
new file mode 100644
index 000000000..d216e1b05
--- /dev/null
+++ b/src/adapters/im/line/line_outbound.cpp
@@ -0,0 +1,363 @@
+// LineTransport 的发送部分:回复 / 推送选择、每次最多 5 条、推送额度用完时暂存补发、
+// 图片临时链接、文件改发说明、“正在输入”动画、附件下载。
+
+#include "im/line/line_transport.hpp"
+
+#include "im/redact.hpp"
+#include "im/text_chunk.hpp"
+#include "utils/logger.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <algorithm>
+#include <cstdio>
+
+namespace acecode::im::line {
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+constexpr std::size_t kUsedTokenLimit = 4096;
+
+std::int64_t now_wall_ms() {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(
+               std::chrono::system_clock::now().time_since_epoch())
+        .count();
+}
+
+std::string human_size(std::uint64_t bytes) {
+    char buffer[32];
+    if (bytes >= 1024u * 1024u)
+        std::snprintf(buffer, sizeof(buffer), "%.1f MB", static_cast<double>(bytes) / (1024.0 * 1024.0));
+    else if (bytes >= 1024u)
+        std::snprintf(buffer, sizeof(buffer), "%.1f KB", static_cast<double>(bytes) / 1024.0);
+    else
+        std::snprintf(buffer, sizeof(buffer), "%llu B", static_cast<unsigned long long>(bytes));
+    return buffer;
+}
+
+nlohmann::json messages_of(const std::vector<nlohmann::json>& all, std::size_t begin, std::size_t count) {
+    nlohmann::json out = nlohmann::json::array();
+    for (std::size_t i = begin; i < begin + count && i < all.size(); ++i) out.push_back(all[i]);
+    return out;
+}
+
+std::string push_error(const ApiResult& result) {
+    if (result.status == 0) return result.message.empty() ? "无法连接 LINE" : result.message;
+    if (result.status == 403) return "LINE 拒绝推送(当前方案或权限不允许):" + result.message;
+    if (result.status == 400) return "LINE 拒绝推送(对方可能已封锁官方账号或不在群里):" + result.message;
+    return "LINE 推送失败:" + result.message;
+}
+
+} // namespace
+
+SendResult LineTransport::send_text(const Address& to, const std::string& text, const nlohmann::json& reply_context) {
+    HeldItem item;
+    item.text = text;
+    std::lock_guard<std::mutex> lock(send_mu_);
+    return deliver_locked(to, {item}, reply_context, false);
+}
+
+SendResult LineTransport::send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                                    const std::string& mime_type, const nlohmann::json& reply_context) {
+    std::error_code ec;
+    const auto size = std::filesystem::file_size(path, ec);
+    if (ec) return {SendOutcome::Failed, "文件不存在或不可读"};
+    const auto display = name.empty() ? path_to_utf8(path.filename()) : name;
+    std::string notice;
+    if (!is_line_image(mime_type, display)) {
+        notice = "文件「" + display + "」(" + human_size(size) + ")已生成,但 LINE 机器人不能发送文件,请在 ACECode 中查看。";
+    } else if (size > options_.max_image_bytes) {
+        notice = "图片「" + display + "」超过 LINE 的 10 MB 上限,未发送;请在 ACECode 中查看。";
+    } else if (public_base().empty()) {
+        notice = "图片「" + display + "」暂时无法发送(LINE 回调地址尚未就绪),请在 ACECode 中查看。";
+    }
+    std::lock_guard<std::mutex> lock(send_mu_);
+    if (!notice.empty()) {
+        LOG_INFO("[channels/line] file of " + std::to_string(size) + " bytes cannot be sent as a LINE message, sending a notice");
+        HeldItem item;
+        item.plain = true;
+        item.text = notice;
+        return deliver_locked(to, {item}, reply_context, false);
+    }
+    HeldItem item;
+    item.file = true;
+    item.path = path;
+    item.name = display;
+    item.mime_type = mime_type.empty() ? "image/jpeg" : mime_type;
+    return deliver_locked(to, {item}, reply_context, false);
+}
+
+std::vector<LineTransport::Piece> LineTransport::build_pieces(const Address& to, const std::vector<HeldItem>& items,
+                                                              const nlohmann::json& reply_context, bool flushing) {
+    std::vector<Piece> pieces;
+    bool first_text = true;
+    std::string quote;
+    // 群里引用触发本回合的那条消息,方便大家看出在回答谁(引用令牌长期有效,可重复使用)。
+    if (!flushing && to.kind == ChatKind::Group && reply_context.is_object())
+        quote = json_string(reply_context, "quote_token");
+    for (const auto& item : items) {
+        if (item.file) {
+            const auto base = public_base();
+            const auto relative = base.empty() ? std::string{} : media_.add(item.path, item.name, item.mime_type);
+            if (relative.empty()) {
+                Piece piece;
+                piece.text = "图片「" + item.name + "」暂时无法发送(LINE 回调地址尚未就绪),请在 ACECode 中查看。";
+                piece.source.plain = true;
+                piece.source.text = piece.text;
+                piece.message = text_message(piece.text);
+                pieces.push_back(std::move(piece));
+                continue;
+            }
+            Piece piece;
+            piece.source = item;
+            piece.message = image_message(base + kMediaRoutePrefix + relative);
+            pieces.push_back(std::move(piece));
+            continue;
+        }
+        const auto chunks = item.plain ? chunk_text(item.text, kChunkUnits, true) : plain_text_chunks(item.text);
+        for (const auto& chunk : chunks) {
+            Piece piece;
+            piece.text = chunk;
+            piece.source.plain = true;
+            piece.source.text = chunk;
+            const auto shown = flushing && first_text ? "(补发)" + chunk : chunk;
+            piece.message = text_message(shown, first_text ? quote : std::string{});
+            first_text = false;
+            pieces.push_back(std::move(piece));
+        }
+    }
+    return pieces;
+}
+
+std::optional<ReplyToken> LineTransport::usable_reply_token_locked(const Address& to,
+                                                                   const nlohmann::json& reply_context) {
+    const auto now = now_wall_ms();
+    const auto from_context = reply_token_of(reply_context);
+    if (from_context && reply_token_fresh(*from_context, now) && !used_tokens_.count(from_context->token))
+        return from_context;
+    // 没有可用的上下文令牌(Desktop 里输入的回复、或令牌已用):用该会话最近一条消息的令牌。
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto it = latest_reply_.find(to.key());
+    if (it != latest_reply_.end() && reply_token_fresh(it->second, now) && !used_tokens_.count(it->second.token))
+        return it->second;
+    return std::nullopt;
+}
+
+void LineTransport::mark_token_used_locked(const std::string& token) {
+    if (!used_tokens_.insert(token).second) return;
+    used_order_.push_back(token);
+    while (used_order_.size() > kUsedTokenLimit) {
+        used_tokens_.erase(used_order_.front());
+        used_order_.pop_front();
+    }
+}
+
+void LineTransport::after_sent(const Address& to, const std::vector<Piece>& pieces, std::size_t begin,
+                               std::size_t count, const ApiResult& result) {
+    // 记下发出的消息 id,对方引用机器人的消息时能认出来。
+    if (result.body.is_object() && result.body.contains("sentMessages") && result.body["sentMessages"].is_array()) {
+        const auto& sent = result.body["sentMessages"];
+        for (std::size_t i = 0; i < sent.size() && i < count; ++i) {
+            const auto& piece = pieces[begin + i];
+            if (!sent[i].is_object() || piece.text.empty()) continue;
+            const auto id = json_string(sent[i], "id");
+            if (!id.empty()) remember_message(id, piece.text, true);
+        }
+    }
+    // 官方账号发出消息后“正在输入”动画会消失:仍在忙碌时稍后重显(见 typing_resume_delay)。
+    bool typing = false;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        const auto it = typing_.find(to.chat);
+        if (it != typing_.end()) {
+            it->second = Clock::now() + options_.typing_resume_delay;
+            typing = true;
+        }
+    }
+    if (typing) wake_typer();
+}
+
+SendResult LineTransport::deliver_locked(const Address& to, std::vector<HeldItem> items,
+                                         const nlohmann::json& reply_context, bool flushing) {
+    const auto key = to.key();
+    if (!flushing && held_size(key) > 0) {
+        // 已有暂存时新的输出排在后面,保证顺序。
+        hold(key, std::move(items));
+        return {SendOutcome::Held, {}};
+    }
+    const auto pieces = build_pieces(to, items, reply_context, flushing);
+    if (pieces.empty()) return {SendOutcome::Sent, {}};
+    std::vector<nlohmann::json> messages;
+    messages.reserve(pieces.size());
+    for (const auto& piece : pieces) messages.push_back(piece.message);
+
+    std::size_t index = 0;
+    if (const auto token = usable_reply_token_locked(to, reply_context)) {
+        const auto count = (std::min)(messages.size(), kMaxMessagesPerCall);
+        // 回复令牌只能用一次:无论结果如何都记为已用。
+        mark_token_used_locked(token->token);
+        ApiResult result;
+        for (std::size_t attempt = 0;; ++attempt) {
+            result = api_.reply(token->token, messages_of(messages, 0, count));
+            const bool rate_limited = result.status == 429 && !is_monthly_limit(result.status, result.message);
+            if (!rate_limited || attempt >= options_.send_retry.size() ||
+                !reply_token_fresh(*token, now_wall_ms()))
+                break;
+            if (!wait_for(options_.send_retry[attempt])) break;
+        }
+        if (result.ok) {
+            after_sent(to, pieces, 0, count, result);
+            index = count;
+        } else if (result.auth_failed) {
+            return {SendOutcome::Failed, result.message};
+        } else if (result.status >= 400 && result.status < 500) {
+            // 令牌失效或已用(400 Invalid reply token)等明确拒收:平台什么都没发,改用推送。
+            LOG_INFO("[channels/line] reply refused (HTTP " + std::to_string(result.status) + "), falling back to push");
+        } else {
+            // 超时 / 5xx:平台可能已经发出,不能重发。
+            LOG_WARN("[channels/line] reply failed with unknown outcome: " + result.message);
+            return {SendOutcome::Failed, "LINE 回复结果未知(网络或平台错误),未重发:" + result.message};
+        }
+    }
+
+    while (index < messages.size()) {
+        const auto count = (std::min)(messages.size() - index, kMaxMessagesPerCall);
+        // 同一批重试必须沿用同一个重试键,LINE 据此去重(重复返回 409)。
+        const auto retry_key = new_retry_key();
+        ApiResult result;
+        for (std::size_t attempt = 0;; ++attempt) {
+            result = api_.push(to.chat, messages_of(messages, index, count), retry_key);
+            if (result.ok || result.status == 409 || is_monthly_limit(result.status, result.message)) break;
+            const bool retryable = !result.auth_failed && !retry_key.empty() &&
+                                   (result.status == 429 || result.status >= 500 || result.status == 0);
+            if (!retryable || attempt >= options_.send_retry.size()) break;
+            LOG_INFO("[channels/line] push failed (HTTP " + std::to_string(result.status) + "), retrying with the same key");
+            if (!wait_for(options_.send_retry[attempt])) break;
+        }
+        if (result.ok || result.status == 409) {
+            quota_exhausted_ = false;
+            after_sent(to, pieces, index, count, result);
+            index += count;
+            continue;
+        }
+        if (is_monthly_limit(result.status, result.message)) {
+            quota_exhausted_ = true;
+            std::vector<HeldItem> rest;
+            for (std::size_t i = index; i < pieces.size(); ++i) rest.push_back(pieces[i].source);
+            const auto n = rest.size();
+            hold(key, std::move(rest));
+            LOG_WARN("[channels/line] monthly push quota exhausted, holding " + std::to_string(n) +
+                     " message(s) until the contact's next message");
+            return {SendOutcome::Held, "LINE 推送额度已用完,将在对方下一条消息时补发"};
+        }
+        LOG_WARN("[channels/line] push failed (HTTP " + std::to_string(result.status) + "): " + result.message);
+        return {SendOutcome::Failed, push_error(result)};
+    }
+    return {SendOutcome::Sent, {}};
+}
+
+void LineTransport::hold(const std::string& key, std::vector<HeldItem> items) {
+    std::lock_guard<std::mutex> lock(held_mu_);
+    auto& queue = held_[key];
+    for (auto& item : items) queue.push_back(std::move(item));
+    std::size_t dropped = 0;
+    while (queue.size() > kMaxHeldPerConversation) {
+        queue.pop_front();
+        ++dropped;
+    }
+    if (dropped) LOG_WARN("[channels/line] held queue full, dropped " + std::to_string(dropped) + " oldest output(s)");
+}
+
+std::deque<HeldItem> LineTransport::take_held(const std::string& key) {
+    std::lock_guard<std::mutex> lock(held_mu_);
+    const auto it = held_.find(key);
+    if (it == held_.end()) return {};
+    auto items = std::move(it->second);
+    held_.erase(it);
+    return items;
+}
+
+std::size_t LineTransport::held_size(const std::string& key) const {
+    std::lock_guard<std::mutex> lock(held_mu_);
+    const auto it = held_.find(key);
+    return it == held_.end() ? 0 : it->second.size();
+}
+
+void LineTransport::flush_held(const Address& address, const nlohmann::json& reply_context) {
+    std::lock_guard<std::mutex> lock(send_mu_);
+    auto held = take_held(address.key());
+    if (held.empty()) return;
+    LOG_INFO("[channels/line] resending " + std::to_string(held.size()) + " held output(s) before the new message");
+    deliver_locked(address, std::vector<HeldItem>(held.begin(), held.end()), reply_context, true);
+}
+
+void LineTransport::send_unidentified_notice(const std::string& reply_token) {
+    std::lock_guard<std::mutex> lock(send_mu_);
+    if (used_tokens_.count(reply_token)) return;
+    mark_token_used_locked(reply_token);
+    const auto result = api_.reply(
+        reply_token, nlohmann::json::array({text_message("无法识别发言人:电脑版 LINE 在群里不提供用户 ID,请用手机版 LINE 发送。")}));
+    if (!result.ok) LOG_DEBUG("[channels/line] unidentified-sender notice not sent (HTTP " + std::to_string(result.status) + ")");
+}
+
+void LineTransport::set_typing(const Address& to, bool on) {
+    // LINE 只允许对一对一聊天的用户显示动画(群 / 多人聊天会 400)。
+    if (to.kind != ChatKind::Private || !is_user_id(to.chat)) return;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (on) typing_.emplace(to.chat, Clock::now());
+        else typing_.erase(to.chat);
+    }
+    if (on) wake_typer();
+}
+
+void LineTransport::wake_typer() {
+    {
+        // 在锁内置位:输入线程检查条件与进入等待之间不会漏掉这次唤醒。
+        std::lock_guard<std::mutex> lock(wake_mu_);
+        typing_wake_ = true;
+    }
+    wake_.notify_all();
+}
+
+void LineTransport::typing_loop() {
+    while (!stopping_) {
+        std::vector<std::string> due;
+        auto next = Clock::now() + options_.typing_refresh;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            const auto now = Clock::now();
+            for (auto& [chat, at] : typing_) {
+                if (at <= now) {
+                    due.push_back(chat);
+                    at = now + options_.typing_refresh;
+                }
+                next = (std::min)(next, at);
+            }
+        }
+        for (const auto& chat : due) {
+            // 动画最长 60 秒;每 50 秒续一次,忙碌期间不会断。
+            const auto result = api_.start_loading(chat, 60);
+            if (!result.ok)
+                LOG_DEBUG("[channels/line] loading animation not shown (HTTP " + std::to_string(result.status) + ")");
+        }
+        std::unique_lock<std::mutex> lock(wake_mu_);
+        wake_.wait_until(lock, next, [this] { return stopping_.load() || typing_wake_.exchange(false); });
+    }
+}
+
+bool LineTransport::download(const Attachment& attachment, const std::filesystem::path& dest, std::string* error) {
+    if (attachment.remote_ref.empty()) {
+        if (error) *error = "该附件无法下载";
+        return false;
+    }
+    if (attachment.size > options_.max_download_bytes) {
+        if (error) *error = "附件超过大小限制";
+        return false;
+    }
+    if (attachment.remote_ref.rfind("https://", 0) == 0 || attachment.remote_ref.rfind("http://", 0) == 0)
+        return api_.download_url(attachment.remote_ref, dest, options_.max_download_bytes, error, cancel_fn());
+    return api_.download_content(attachment.remote_ref, dest, options_.max_download_bytes, error, cancel_fn());
+}
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/line/line_protocol.cpp b/src/adapters/im/line/line_protocol.cpp
new file mode 100644
index 000000000..904e5286b
--- /dev/null
+++ b/src/adapters/im/line/line_protocol.cpp
@@ -0,0 +1,452 @@
+#include "im/line/line_protocol.hpp"
+
+#include "im/markdown.hpp"
+#include "im/text_chunk.hpp"
+#include "platform/crypto/digest.hpp"
+#include "utils/base64.hpp"
+
+#include <algorithm>
+#include <cctype>
+#include <cstdio>
+
+namespace acecode::im::line {
+namespace {
+
+std::string str(const nlohmann::json& object, const char* key) {
+    if (!object.is_object()) return {};
+    const auto it = object.find(key);
+    if (it == object.end()) return {};
+    if (it->is_string()) return it->get<std::string>();
+    if (it->is_number_integer()) return std::to_string(it->get<std::int64_t>());
+    if (it->is_number_unsigned()) return std::to_string(it->get<std::uint64_t>());
+    return {};
+}
+
+std::int64_t int64_of(const nlohmann::json& object, const char* key) {
+    if (!object.is_object()) return 0;
+    const auto it = object.find(key);
+    if (it == object.end()) return 0;
+    if (it->is_number_integer()) return it->get<std::int64_t>();
+    if (it->is_number_unsigned()) return static_cast<std::int64_t>(it->get<std::uint64_t>());
+    if (it->is_number_float()) return static_cast<std::int64_t>(it->get<double>());
+    return 0;
+}
+
+bool bool_of(const nlohmann::json& object, const char* key) {
+    if (!object.is_object()) return false;
+    const auto it = object.find(key);
+    return it != object.end() && it->is_boolean() && it->get<bool>();
+}
+
+std::string trim(const std::string& text) {
+    const auto begin = text.find_first_not_of(" \t\r\n");
+    if (begin == std::string::npos) return {};
+    const auto end = text.find_last_not_of(" \t\r\n");
+    return text.substr(begin, end - begin + 1);
+}
+
+std::string lower(std::string text) {
+    std::transform(text.begin(), text.end(), text.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return text;
+}
+
+bool ends_with(const std::string& text, const std::string& suffix) {
+    return text.size() >= suffix.size() && text.compare(text.size() - suffix.size(), suffix.size(), suffix) == 0;
+}
+
+// UTF-8 序列长度与码点;非法字节按 1 字节、1 个 UTF-16 单位处理。
+std::size_t sequence_length(const std::string& utf8, std::size_t i, std::uint32_t* code_point) {
+    const auto c = static_cast<unsigned char>(utf8[i]);
+    std::size_t length = 1;
+    std::uint32_t value = c;
+    if (c >= 0xF0 && c <= 0xF4) {
+        length = 4;
+        value = c & 0x07u;
+    } else if (c >= 0xE0) {
+        length = 3;
+        value = c & 0x0Fu;
+    } else if (c >= 0xC2 && c < 0xE0) {
+        length = 2;
+        value = c & 0x1Fu;
+    }
+    if (length == 1 || i + length > utf8.size()) {
+        *code_point = c;
+        return 1;
+    }
+    for (std::size_t k = 1; k < length; ++k) {
+        const auto next = static_cast<unsigned char>(utf8[i + k]);
+        if ((next & 0xC0u) != 0x80u) {
+            *code_point = c;
+            return 1;
+        }
+        value = (value << 6) | (next & 0x3Fu);
+    }
+    *code_point = value;
+    return length;
+}
+
+EventKind kind_of(const std::string& type) {
+    if (type == "message") return EventKind::Message;
+    if (type == "follow") return EventKind::Follow;
+    if (type == "unfollow") return EventKind::Unfollow;
+    if (type == "join") return EventKind::Join;
+    if (type == "leave") return EventKind::Leave;
+    if (type == "unsend") return EventKind::Unsend;
+    if (type == "messageEdited") return EventKind::MessageEdited;
+    if (type == "postback") return EventKind::Postback;
+    return EventKind::Other;
+}
+
+Attachment content_attachment(const nlohmann::json& message, AttachmentKind kind, const std::string& extension,
+                              const std::string& mime) {
+    Attachment attachment;
+    attachment.kind = kind;
+    const auto id = str(message, "id");
+    attachment.name = id.empty() ? "line" + extension : id + extension;
+    attachment.mime_type = mime;
+    const auto provider = message.value("contentProvider", nlohmann::json::object());
+    if (str(provider, "type") == "external") {
+        // 外部内容不能经 LINE 内容接口下载,只能取对方给出的地址。
+        attachment.remote_ref = str(provider, "originalContentUrl");
+    } else {
+        attachment.remote_ref = id;
+    }
+    return attachment;
+}
+
+std::string location_text(const nlohmann::json& message) {
+    std::string text = "[位置]";
+    const auto title = str(message, "title");
+    const auto address = str(message, "address");
+    if (!title.empty()) text += " " + title;
+    if (!address.empty()) text += " " + address;
+    if (message.contains("latitude") && message.contains("longitude") && message["latitude"].is_number() &&
+        message["longitude"].is_number()) {
+        char buffer[96];
+        std::snprintf(buffer, sizeof(buffer), " (%.6f, %.6f)", message["latitude"].get<double>(),
+                      message["longitude"].get<double>());
+        text += buffer;
+    }
+    return text;
+}
+
+void parse_message(WebhookEvent& event, const nlohmann::json& message, const std::string& account,
+                   std::int64_t received_at_ms) {
+    event.message_id = str(message, "id");
+    event.quoted_message_id = str(message, "quotedMessageId");
+    const auto type = str(message, "type");
+
+    std::string text;
+    std::vector<Attachment> attachments;
+    if (type == "text") {
+        text = str(message, "text");
+        std::vector<std::pair<std::size_t, std::size_t>> strip;
+        const auto mention = message.value("mention", nlohmann::json::object());
+        const auto mentionees =
+            mention.is_object() ? mention.value("mentionees", nlohmann::json::array()) : nlohmann::json::array();
+        if (mentionees.is_array()) {
+            for (const auto& m : mentionees) {
+                if (!m.is_object() || str(m, "type") != "user") continue;  // @All 不算点名机器人
+                const bool self = bool_of(m, "isSelf") || (!account.empty() && str(m, "userId") == account);
+                if (!self) continue;
+                event.mentioned_self = true;
+                const auto index = int64_of(m, "index");
+                const auto length = int64_of(m, "length");
+                if (index >= 0 && length > 0)
+                    strip.emplace_back(static_cast<std::size_t>(index), static_cast<std::size_t>(length));
+            }
+        }
+        text = trim(remove_utf16_ranges(text, std::move(strip)));
+    } else if (type == "image") {
+        attachments.push_back(content_attachment(message, AttachmentKind::Image, ".jpg", "image/jpeg"));
+    } else if (type == "video") {
+        attachments.push_back(content_attachment(message, AttachmentKind::Video, ".mp4", "video/mp4"));
+    } else if (type == "audio") {
+        attachments.push_back(content_attachment(message, AttachmentKind::Voice, ".m4a", "audio/mp4"));
+    } else if (type == "file") {
+        Attachment attachment;
+        attachment.kind = AttachmentKind::File;
+        attachment.name = str(message, "fileName");
+        if (attachment.name.empty()) attachment.name = "file";
+        attachment.mime_type = "application/octet-stream";
+        const auto size = int64_of(message, "fileSize");
+        attachment.size = size > 0 ? static_cast<std::uint64_t>(size) : 0;
+        attachment.remote_ref = event.message_id;
+        attachments.push_back(std::move(attachment));
+    } else if (type == "sticker") {
+        Attachment attachment;
+        attachment.kind = AttachmentKind::Sticker;
+        attachment.name = "sticker";
+        attachments.push_back(std::move(attachment));
+    } else if (type == "location") {
+        text = location_text(message);
+    } else {
+        return;  // 未知类型:平台会无通知新增类型,一律忽略
+    }
+
+    if (event.chat_id.empty() || event.message_id.empty()) return;
+    if (event.source_type != "user" && event.user_id.empty()) {
+        event.unidentified_sender = true;
+        return;
+    }
+    if (text.empty() && attachments.empty()) return;
+
+    Inbound inbound;
+    inbound.address.platform = kPlatform;
+    inbound.address.account = account;
+    inbound.address.kind = event.source_type == "user" ? ChatKind::Private : ChatKind::Group;
+    inbound.address.chat = event.chat_id;
+    inbound.address.sender = event.user_id;
+    inbound.message_id = event.message_id;
+    inbound.text = std::move(text);
+    inbound.mentioned = inbound.address.kind == ChatKind::Private || event.mentioned_self;
+    if (inbound.address.kind == ChatKind::Private && inbound.text.rfind("/start ", 0) == 0) {
+        const auto code = trim(inbound.text.substr(7));
+        if (!code.empty() && code.find_first_of(" \t\r\n") == std::string::npos) inbound.start_code = code;
+    }
+    inbound.attachments = std::move(attachments);
+    if (!event.reply_token.empty() && !event.standby) {
+        ReplyToken token;
+        token.token = event.reply_token;
+        token.received_at_ms = received_at_ms;
+        token.event_ts_ms = event.timestamp_ms;
+        token.redelivery = event.redelivery;
+        token.quote_token = str(message, "quoteToken");
+        inbound.reply_context = make_reply_context(token, event.message_id);
+    } else {
+        inbound.reply_context = nlohmann::json{{"message_id", event.message_id}};
+        const auto quote = str(message, "quoteToken");
+        if (!quote.empty()) inbound.reply_context["quote_token"] = quote;
+    }
+    event.inbound = std::move(inbound);
+}
+
+WebhookEvent parse_event(const nlohmann::json& e, const std::string& account, std::int64_t received_at_ms) {
+    WebhookEvent event;
+    event.type = str(e, "type");
+    event.kind = kind_of(event.type);
+    event.event_id = str(e, "webhookEventId");
+    event.standby = str(e, "mode") == "standby";
+    event.redelivery = bool_of(e.value("deliveryContext", nlohmann::json::object()), "isRedelivery");
+    event.timestamp_ms = int64_of(e, "timestamp");
+    event.reply_token = str(e, "replyToken");
+    const auto source = e.value("source", nlohmann::json::object());
+    event.source_type = str(source, "type");
+    event.user_id = str(source, "userId");
+    if (event.source_type == "user") event.chat_id = event.user_id;
+    else if (event.source_type == "group") event.chat_id = str(source, "groupId");
+    else if (event.source_type == "room") event.chat_id = str(source, "roomId");
+    if (event.kind == EventKind::Message) {
+        const auto message = e.value("message", nlohmann::json::object());
+        if (message.is_object()) parse_message(event, message, account, received_at_ms);
+    } else if (event.kind == EventKind::Unsend) {
+        event.message_id = str(e.value("unsend", nlohmann::json::object()), "messageId");
+    }
+    return event;
+}
+
+} // namespace
+
+std::string json_string(const nlohmann::json& object, const char* key) { return str(object, key); }
+
+bool json_bool(const nlohmann::json& object, const char* key) { return bool_of(object, key); }
+
+std::string sign_body(std::string_view raw_body, const std::string& channel_secret) {
+    if (channel_secret.empty()) return {};
+    const auto digest = platform::hmac_sha256(channel_secret, std::string(raw_body));
+    if (digest.empty()) return {};
+    return base64_encode(digest);
+}
+
+bool verify_signature(std::string_view raw_body, std::string_view signature, const std::string& channel_secret) {
+    while (!signature.empty() && (signature.front() == ' ' || signature.front() == '\t')) signature.remove_prefix(1);
+    while (!signature.empty() && (signature.back() == ' ' || signature.back() == '\t' || signature.back() == '\r' ||
+                                  signature.back() == '\n'))
+        signature.remove_suffix(1);
+    if (signature.empty()) return false;
+    const auto expected = sign_body(raw_body, channel_secret);
+    if (expected.empty() || expected.size() != signature.size()) return false;
+    unsigned char diff = 0;
+    for (std::size_t i = 0; i < expected.size(); ++i)
+        diff |= static_cast<unsigned char>(expected[i] ^ signature[i]);
+    return diff == 0;
+}
+
+ParsedWebhook parse_webhook(std::string_view body, const std::string& account, std::int64_t received_at_ms) {
+    ParsedWebhook out;
+    nlohmann::json json;
+    try {
+        json = nlohmann::json::parse(body.begin(), body.end());
+    } catch (...) {
+        return out;
+    }
+    if (!json.is_object()) return out;
+    out.valid = true;
+    out.destination = str(json, "destination");
+    const auto events = json.find("events");
+    if (events == json.end() || !events->is_array()) return out;
+    for (const auto& e : *events) {
+        if (!e.is_object()) continue;
+        out.events.push_back(parse_event(e, account, received_at_ms));
+    }
+    return out;
+}
+
+std::size_t utf16_to_byte_offset(const std::string& utf8, std::size_t units) {
+    std::size_t i = 0;
+    std::size_t counted = 0;
+    while (i < utf8.size()) {
+        if (counted >= units) return i;
+        std::uint32_t code_point = 0;
+        const auto length = sequence_length(utf8, i, &code_point);
+        const std::size_t width = code_point >= 0x10000 ? 2 : 1;
+        if (counted + width > units) return i;  // 落在代理对中间:取该字符开头
+        counted += width;
+        i += length;
+    }
+    return utf8.size();
+}
+
+std::string remove_utf16_ranges(const std::string& utf8, std::vector<std::pair<std::size_t, std::size_t>> ranges) {
+    std::vector<std::pair<std::size_t, std::size_t>> bytes;
+    for (const auto& [offset, length] : ranges) {
+        if (length == 0) continue;
+        const auto begin = utf16_to_byte_offset(utf8, offset);
+        const auto end = utf16_to_byte_offset(utf8, offset + length);
+        if (end > begin) bytes.emplace_back(begin, end);
+    }
+    if (bytes.empty()) return utf8;
+    std::sort(bytes.begin(), bytes.end());
+    std::string out;
+    std::size_t cursor = 0;
+    for (const auto& [begin, end] : bytes) {
+        if (begin > cursor) out.append(utf8, cursor, begin - cursor);
+        cursor = (std::max)(cursor, end);
+    }
+    if (cursor < utf8.size()) out.append(utf8, cursor, std::string::npos);
+    return out;
+}
+
+std::optional<ReplyToken> reply_token_of(const nlohmann::json& reply_context) {
+    if (!reply_context.is_object()) return std::nullopt;
+    ReplyToken token;
+    token.token = str(reply_context, "reply_token");
+    if (token.token.empty()) return std::nullopt;
+    token.received_at_ms = int64_of(reply_context, "received_at_ms");
+    token.event_ts_ms = int64_of(reply_context, "event_ts_ms");
+    token.redelivery = bool_of(reply_context, "redelivery");
+    token.quote_token = str(reply_context, "quote_token");
+    return token;
+}
+
+nlohmann::json make_reply_context(const ReplyToken& token, const std::string& message_id) {
+    nlohmann::json context{{"reply_token", token.token},
+                           {"received_at_ms", token.received_at_ms},
+                           {"event_ts_ms", token.event_ts_ms}};
+    if (token.redelivery) context["redelivery"] = true;
+    if (!token.quote_token.empty()) context["quote_token"] = token.quote_token;
+    if (!message_id.empty()) context["message_id"] = message_id;
+    return context;
+}
+
+bool reply_token_fresh(const ReplyToken& token, std::int64_t now_ms) {
+    if (token.token.empty() || token.received_at_ms <= 0) return false;
+    if (now_ms >= token.received_at_ms + kReplyTokenWindowMs) return false;
+    // 重投事件的令牌在事件发生 20 分钟后一律失效,再留 1 分钟余量。
+    if (token.redelivery && (token.event_ts_ms <= 0 || now_ms >= token.event_ts_ms + kRedeliveredTokenLimitMs))
+        return false;
+    return true;
+}
+
+std::vector<std::string> plain_text_chunks(const std::string& markdown) {
+    return chunk_text(markdown_to_plain(markdown), kChunkUnits, true);
+}
+
+nlohmann::json text_message(const std::string& text, const std::string& quote_token) {
+    nlohmann::json message{{"type", "text"}, {"text", text}};
+    if (!quote_token.empty()) message["quoteToken"] = quote_token;
+    return message;
+}
+
+nlohmann::json image_message(const std::string& url) {
+    return {{"type", "image"}, {"originalContentUrl", url}, {"previewImageUrl", url}};
+}
+
+std::vector<std::vector<nlohmann::json>> batch_messages(const std::vector<nlohmann::json>& messages,
+                                                        std::size_t per_call) {
+    if (per_call == 0) per_call = kMaxMessagesPerCall;
+    std::vector<std::vector<nlohmann::json>> batches;
+    for (std::size_t i = 0; i < messages.size(); i += per_call) {
+        const auto end = (std::min)(messages.size(), i + per_call);
+        batches.emplace_back(messages.begin() + static_cast<std::ptrdiff_t>(i),
+                             messages.begin() + static_cast<std::ptrdiff_t>(end));
+    }
+    return batches;
+}
+
+bool is_monthly_limit(long status, const std::string& message) {
+    return status == 429 && lower(message).find("monthly limit") != std::string::npos;
+}
+
+bool is_invalid_reply_token(long status, const std::string& message) {
+    return status == 400 && lower(message).find("reply token") != std::string::npos;
+}
+
+std::string percent_encode(std::string_view value) {
+    static constexpr char kHex[] = "0123456789ABCDEF";
+    std::string out;
+    for (const char c : value) {
+        const auto u = static_cast<unsigned char>(c);
+        if ((u >= 'A' && u <= 'Z') || (u >= 'a' && u <= 'z') || (u >= '0' && u <= '9') || u == '-' || u == '_' ||
+            u == '.' || u == '~') {
+            out.push_back(c);
+        } else {
+            out.push_back('%');
+            out.push_back(kHex[u >> 4]);
+            out.push_back(kHex[u & 0x0F]);
+        }
+    }
+    return out;
+}
+
+std::string add_friend_url(const std::string& basic_id) {
+    if (basic_id.empty()) return {};
+    return "https://line.me/R/ti/p/" + percent_encode(basic_id);
+}
+
+std::string oa_message_url(const std::string& basic_id, const std::string& text) {
+    if (basic_id.empty()) return {};
+    return "https://line.me/R/oaMessage/" + percent_encode(basic_id) + "/?" + percent_encode(text);
+}
+
+bool is_user_id(const std::string& id) { return id.size() > 1 && id[0] == 'U'; }
+
+bool is_line_image(const std::string& mime_type, const std::string& name) {
+    const auto mime = lower(mime_type);
+    if (mime == "image/jpeg" || mime == "image/jpg" || mime == "image/png") return true;
+    if (!mime.empty() && mime != "application/octet-stream") return false;
+    const auto lname = lower(name);
+    return ends_with(lname, ".jpg") || ends_with(lname, ".jpeg") || ends_with(lname, ".png");
+}
+
+std::string safe_file_name(const std::string& name) {
+    std::string clean;
+    for (const char c : name) {
+        const auto u = static_cast<unsigned char>(c);
+        const bool ok = (u >= 'A' && u <= 'Z') || (u >= 'a' && u <= 'z') || (u >= '0' && u <= '9') || c == '.' ||
+                        c == '-' || c == '_';
+        clean.push_back(ok ? c : '_');
+    }
+    while (!clean.empty() && clean.front() == '.') clean.erase(clean.begin());
+    std::string extension;
+    const auto dot = clean.find_last_of('.');
+    if (dot != std::string::npos && dot > 0 && clean.size() - dot <= 8) extension = clean.substr(dot);
+    std::string stem = dot != std::string::npos && !extension.empty() ? clean.substr(0, dot) : clean;
+    if (stem.find_first_not_of('_') == std::string::npos) stem = "file";
+    const std::size_t limit = 64 - extension.size();
+    if (stem.size() > limit) stem.resize(limit);
+    return stem + extension;
+}
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/line/line_protocol.hpp b/src/adapters/im/line/line_protocol.hpp
new file mode 100644
index 000000000..2d41b07a4
--- /dev/null
+++ b/src/adapters/im/line/line_protocol.hpp
@@ -0,0 +1,131 @@
+#pragma once
+
+// LINE Messaging API 的纯逻辑部分(不做 IO):webhook 签名校验、webhook JSON 解析为
+// 入站消息、@机器人 识别与去除、回复令牌是否还能用、出站文字分段与每次调用的条数上限。
+//
+// 平台事实(见 LINE 官方文档,2026-10 核对):
+//   - 回调签名 X-Line-Signature = base64(HMAC-SHA256(Channel secret, 原始请求体));
+//   - 文字气泡上限 5000 个 UTF-16 单位,不渲染 Markdown;一次 reply / push 最多 5 条;
+//   - mention 的 index / length 按 UTF-16 单位计;
+//   - reply token 只能用一次,收到后 1 分钟内有效(这里按 50 秒算);重投的事件沿用原令牌,
+//     但事件发生 20 分钟后一律失效;
+//   - 群里电脑版 LINE 的发言不带 userId,无法识别发言人。
+
+#include "im/transport.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <cstddef>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+namespace acecode::im::line {
+
+inline constexpr const char* kPlatform = "line";
+inline constexpr std::size_t kMaxTextUnits = 5000;      // LINE 文字气泡上限(UTF-16 单位)
+inline constexpr std::size_t kChunkUnits = 4800;        // 分段长度,给“(补发)”等前缀留余量
+inline constexpr std::size_t kMaxMessagesPerCall = 5;   // 一次 reply / push 最多 5 个消息对象
+inline constexpr std::int64_t kReplyTokenWindowMs = 50 * 1000;
+inline constexpr std::int64_t kRedeliveredTokenLimitMs = 20 * 60 * 1000 - 60 * 1000;
+
+// ---- 签名 ----
+
+// 按 LINE 规则计算原始请求体的签名(base64)。channel_secret 为空或摘要失败时返回空串。
+std::string sign_body(std::string_view raw_body, const std::string& channel_secret);
+// 常量时间比较;签名为空、密钥为空或不一致都返回 false。header 两端空白会被忽略。
+bool verify_signature(std::string_view raw_body, std::string_view signature, const std::string& channel_secret);
+
+// ---- webhook 解析 ----
+
+enum class EventKind { Message, Follow, Unfollow, Join, Leave, Unsend, MessageEdited, Postback, Other };
+
+struct WebhookEvent {
+    EventKind kind = EventKind::Other;
+    std::string type;               // 原始 type
+    std::string event_id;           // webhookEventId(去重键,重投时不变)
+    bool standby = false;           // mode == "standby":不应发送任何消息
+    bool redelivery = false;
+    std::int64_t timestamp_ms = 0;  // 事件发生时间
+    std::string reply_token;
+    std::string source_type;        // user / group / room
+    std::string chat_id;            // 私聊 userId;群 groupId;多人聊天 roomId
+    std::string user_id;            // 发言人;群里可能为空(电脑版 LINE)
+    std::string message_id;
+    std::string quoted_message_id;  // 对方引用的消息 id(平台不提供内容)
+    bool mentioned_self = false;    // 文字里点名了本机器人
+    bool unidentified_sender = false;  // 群消息缺少 userId
+    std::optional<Inbound> inbound; // 可交给核心的消息事件
+};
+
+struct ParsedWebhook {
+    bool valid = false;             // false:不是 LINE webhook 的 JSON 结构
+    std::string destination;        // 机器人 userId
+    std::vector<WebhookEvent> events;
+};
+
+// account = 机器人 userId(Address::account,也用于 mention 的兜底判定);
+// received_at_ms = 本机收到 webhook 的墙钟时间,写进 reply_context 用来判断令牌是否过期。
+ParsedWebhook parse_webhook(std::string_view body, const std::string& account, std::int64_t received_at_ms);
+
+// 按 UTF-16 单位删除若干 [offset, offset + length) 区间;区间可无序、可重叠,越界部分截掉。
+std::string remove_utf16_ranges(const std::string& utf8, std::vector<std::pair<std::size_t, std::size_t>> ranges);
+// UTF-16 单位偏移对应的 UTF-8 字节偏移(落在代理对中间时取该字符开头);越界返回 utf8.size()。
+std::size_t utf16_to_byte_offset(const std::string& utf8, std::size_t units);
+
+// ---- 回复令牌 ----
+
+struct ReplyToken {
+    std::string token;
+    std::int64_t received_at_ms = 0;
+    std::int64_t event_ts_ms = 0;
+    bool redelivery = false;
+    std::string quote_token;
+};
+
+// 从 Inbound::reply_context 取出回复令牌;没有令牌时返回 nullopt。
+std::optional<ReplyToken> reply_token_of(const nlohmann::json& reply_context);
+nlohmann::json make_reply_context(const ReplyToken& token, const std::string& message_id);
+// 令牌是否还在可用窗口内(不判断是否已经用过)。
+bool reply_token_fresh(const ReplyToken& token, std::int64_t now_ms);
+
+// ---- 出站 ----
+
+// Markdown → 纯文本(链接保留为 “文字 (网址)”),再按 kChunkUnits 个 UTF-16 单位分段。
+std::vector<std::string> plain_text_chunks(const std::string& markdown);
+nlohmann::json text_message(const std::string& text, const std::string& quote_token = {});
+nlohmann::json image_message(const std::string& url);
+// 按每次调用最多 per_call 条分组。
+std::vector<std::vector<nlohmann::json>> batch_messages(const std::vector<nlohmann::json>& messages,
+                                                        std::size_t per_call = kMaxMessagesPerCall);
+
+// 429 里的 “You have reached your monthly limit.” 是推送额度用完,不是限频。
+bool is_monthly_limit(long status, const std::string& message);
+// 回复令牌已失效 / 已用过。
+bool is_invalid_reply_token(long status, const std::string& message);
+
+// ---- 杂项 ----
+
+// 宽松取值:对象缺失、字段缺失或类型不符时返回空串 / false,绝不抛异常
+// (平台会无通知地增改字段;线程里抛出的异常会直接终止进程)。数字 id 转成十进制字符串。
+std::string json_string(const nlohmann::json& object, const char* key);
+bool json_bool(const nlohmann::json& object, const char* key);
+
+// RFC 3986 非保留字符之外一律 %XX。
+std::string percent_encode(std::string_view value);
+// 加好友链接 https://line.me/R/ti/p/<编码后的 basicId>;basic_id 为空时返回空串。
+std::string add_friend_url(const std::string& basic_id);
+// 打开与官方账号的聊天并预填文字:https://line.me/R/oaMessage/<basicId>/?<文字>(都按 UTF-8 百分号编码)。
+// 机主绑定可用它生成二维码,例如预填 "/start 483920";私聊里 "/start <码>" 会解析进 Inbound::start_code。
+std::string oa_message_url(const std::string& basic_id, const std::string& text);
+// LINE 只能对用户 id(U 开头)显示“正在输入”动画。
+bool is_user_id(const std::string& id);
+// LINE 图片消息只接受 JPEG / PNG。
+bool is_line_image(const std::string& mime_type, const std::string& name);
+// 媒体链接里的文件名:只保留 [A-Za-z0-9._-],最长 64 字节,保留扩展名;结果不会以点开头。
+std::string safe_file_name(const std::string& name);
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/line/line_transport.cpp b/src/adapters/im/line/line_transport.cpp
new file mode 100644
index 000000000..538980e13
--- /dev/null
+++ b/src/adapters/im/line/line_transport.cpp
@@ -0,0 +1,770 @@
+#include "im/line/line_transport.hpp"
+
+#include "im/http.hpp"
+#include "im/redact.hpp"
+#include "platform/crypto/secure_random.hpp"
+#include "utils/logger.hpp"
+
+#include <algorithm>
+#include <fstream>
+#include <iterator>
+
+namespace acecode::im::line {
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+constexpr std::size_t kSeenLimit = 4096;
+constexpr std::size_t kRecentLimit = 512;
+constexpr std::size_t kNameCacheLimit = 512;
+constexpr auto kNameTtl = std::chrono::hours(1);
+
+constexpr const char* kUseWebhookOff =
+    "请在 LINE Developers Console 的 Messaging API 页开启 Use webhook,开启后自动连上";
+constexpr const char* kSetupHint =
+    "需在 LINE Developers Console → Messaging API 开启 Use webhook;并在 LINE Official Account Manager "
+    "关闭“自动回复”和“欢迎消息”,否则官方账号会同时自动应答";
+
+std::int64_t now_wall_ms() {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(
+               std::chrono::system_clock::now().time_since_epoch())
+        .count();
+}
+
+std::string trim_slash(std::string base) {
+    while (!base.empty() && base.back() == '/') base.pop_back();
+    return base;
+}
+
+ListenerReply plain_reply(int status, const std::string& body) {
+    ListenerReply reply;
+    reply.status = status;
+    reply.body = body;
+    reply.headers = {{"Cache-Control", "no-store"}};
+    return reply;
+}
+
+} // namespace
+
+LineTransport::LineTransport(LineTransportOptions options)
+    : options_(std::move(options)), api_(options_.api), tunnel_(options_.tunnel), media_(options_.media_ttl) {
+    options_.public_url = trim_slash(options_.public_url);
+    status_.extra["setup_hint"] = kSetupHint;
+    status_.extra["tunnel"] = tunnel_mode() ? "cloudflare" : "custom";
+}
+
+LineTransport::~LineTransport() { stop(); }
+
+Capabilities LineTransport::capabilities() const {
+    Capabilities caps;
+    caps.max_text_units = kChunkUnits;
+    caps.count_utf16 = true;
+    caps.batch_turn_output = true;  // 一个回合合并成一次回复,尽量用免费的回复令牌
+    caps.supports_typing = true;
+    caps.max_upload_bytes = options_.max_image_bytes;
+    caps.max_download_bytes = options_.max_download_bytes;
+    return caps;
+}
+
+void LineTransport::start(TransportCallbacks callbacks) {
+    if (running_.exchange(true)) return;
+    callbacks_ = std::move(callbacks);
+    stopping_ = false;
+    cancel_flag_->store(false);
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        instance_id_ = platform::secure_random_token(24);
+        if (instance_id_.empty()) instance_id_ = "line-" + std::to_string(now_wall_ms());
+    }
+    link_ = acecode::JoiningThread(&LineTransport::link_loop, this);
+    events_ = acecode::JoiningThread(&LineTransport::event_loop, this);
+    typer_ = acecode::JoiningThread(&LineTransport::typing_loop, this);
+}
+
+void LineTransport::stop() {
+    if (!running_.exchange(false)) return;
+    stopping_ = true;
+    cancel_flag_->store(true);
+    // 先进出一次各自的锁再通知:等待方要么还没检查条件(会看到 stopping_),要么已在等待,
+    // 不会丢失这次唤醒(事件线程的等待没有超时,丢了就永远停不下来)。
+    { std::lock_guard<std::mutex> lock(wake_mu_); }
+    wake_.notify_all();
+    { std::lock_guard<std::mutex> lock(queue_mu_); }
+    queue_cv_.notify_all();
+    if (link_.joinable()) link_.join();
+    // 回调端口停下后不会再进来新的请求;之后才能收尾事件线程。
+    if (options_.listener) options_.listener->stop();
+    listener_port_ = 0;
+    if (events_.joinable()) events_.join();
+    if (typer_.joinable()) typer_.join();
+    drop_tunnel();
+    {
+        std::lock_guard<std::mutex> lock(queue_mu_);
+        queue_.clear();
+    }
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        typing_.clear();
+        public_base_.clear();
+    }
+    set_status(LinkState::Stopped, {});
+}
+
+TransportStatus LineTransport::status() const {
+    TransportStatus copy;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        copy = status_;
+    }
+    copy.extra["held"] = held_count();
+    copy.extra["push_quota_exhausted"] = quota_exhausted_.load();
+    return copy;
+}
+
+std::size_t LineTransport::held_count() const {
+    std::lock_guard<std::mutex> lock(held_mu_);
+    std::size_t sum = 0;
+    for (const auto& entry : held_) sum += entry.second.size();
+    return sum;
+}
+
+std::uint16_t LineTransport::listen_port() const { return listener_port_.load(); }
+
+std::string LineTransport::public_base() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return public_base_;
+}
+
+std::string LineTransport::account() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return account_;
+}
+
+void LineTransport::set_status(LinkState state, const std::string& detail, bool retry_stopped) {
+    TransportStatus snapshot;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        const auto clean = redact_secrets(detail, {options_.api.channel_secret, options_.api.access_token});
+        if (status_.state == state && status_.detail == clean && status_.retry_stopped == retry_stopped) return;
+        status_.state = state;
+        status_.detail = clean;
+        status_.retry_stopped = retry_stopped;
+        snapshot = status_;
+    }
+    if (state == LinkState::Failed || state == LinkState::Retrying)
+        LOG_INFO(std::string("[channels/line] link ") + link_state_name(state) +
+                 (retry_stopped ? " (retry stopped)" : ""));
+    if (callbacks_.on_status) callbacks_.on_status(snapshot);
+}
+
+void LineTransport::drop_tunnel() {
+    // 隧道一停,旧的公网地址(含图片临时链接)就失效了;重新登记前不再对外给出它。
+    tunnel_.stop();
+    if (!tunnel_mode()) return;
+    std::lock_guard<std::mutex> lock(mu_);
+    public_base_.clear();
+}
+
+void LineTransport::set_extra(const std::string& key, nlohmann::json value) {
+    std::lock_guard<std::mutex> lock(mu_);
+    status_.extra[key] = std::move(value);
+}
+
+void LineTransport::progress(std::size_t attempt, const std::string& detail) {
+    set_status(attempt == 0 ? LinkState::Connecting : LinkState::Retrying, detail);
+}
+
+bool LineTransport::wait_for(std::chrono::milliseconds duration) {
+    std::unique_lock<std::mutex> lock(wake_mu_);
+    wake_.wait_for(lock, duration, [this] { return stopping_.load(); });
+    return !stopping_;
+}
+
+CancelFn LineTransport::cancel_fn() const {
+    return [flag = cancel_flag_] { return flag->load(); };
+}
+
+ListenerHandler LineTransport::listener_handler() {
+    return [ref = lifetime_.ref(*this)](const ListenerRequest& request) {
+        ListenerReply reply = plain_reply(503, "unavailable");
+        ref.with([&reply, &request](LineTransport& transport) { reply = transport.handle_request(request); });
+        return reply;
+    };
+}
+
+// ---------------------------------------------------------------- 连接与看守
+
+void LineTransport::link_loop() {
+    std::size_t attempt = 0;
+    set_status(LinkState::Connecting, "正在连接 LINE");
+    while (!stopping_) {
+        bool reached = false;
+        LinkStep step = LinkStep::Retry;
+        try {
+            step = connect_and_watch(attempt, &reached);
+        } catch (const std::exception& e) {
+            // 线程函数不能抛出异常(会终止进程):记日志后按普通临时错误重试。
+            LOG_ERROR(std::string("[channels/line] unexpected error while connecting: ") + e.what());
+            set_status(LinkState::Retrying, "连接 LINE 时出现内部错误,稍后重试");
+        }
+        if (step == LinkStep::Stopped || stopping_) break;
+        if (step == LinkStep::Fatal) {
+            // 致命错误不会自己好:不再保留公网隧道,等用户处理后重新打开。
+            drop_tunnel();
+            break;
+        }
+        if (reached) attempt = 0;
+        const auto& steps = options_.backoff;
+        const auto delay = steps.empty() ? std::chrono::milliseconds(1000) : steps[(std::min)(attempt, steps.size() - 1)];
+        ++attempt;
+        if (!wait_for(delay)) break;
+    }
+    if (!stopping_) {
+        std::unique_lock<std::mutex> lock(wake_mu_);
+        wake_.wait(lock, [this] { return stopping_.load(); });
+    }
+}
+
+LineTransport::LinkStep LineTransport::connect_and_watch(std::size_t attempt, bool* reached) {
+    const auto cancel = cancel_fn();
+    progress(attempt, attempt == 0 ? "正在连接 LINE" : "正在重新连接 LINE");
+
+    BotInfo bot;
+    const auto info = api_.bot_info(&bot, cancel);
+    if (stopping_ || info.cancelled) return LinkStep::Stopped;
+    if (!info.ok) {
+        if (info.auth_failed) {
+            set_status(LinkState::Failed, info.message, true);
+            return LinkStep::Fatal;
+        }
+        set_status(LinkState::Retrying, info.status == 0 ? info.message : "LINE 暂时不可用:" + info.message);
+        return LinkStep::Retry;
+    }
+    if (bot.user_id.empty()) {
+        set_status(LinkState::Retrying, "LINE 返回的机器人信息无效");
+        return LinkStep::Retry;
+    }
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        account_ = bot.user_id;
+        status_.account = bot.user_id;
+        status_.display_name = bot.display_name;
+        status_.extra["basic_id"] = bot.basic_id;
+        status_.extra["add_friend_url"] = add_friend_url(bot.basic_id);
+        status_.extra["chat_mode"] = bot.chat_mode;
+    }
+
+    LinkStep step = LinkStep::Retry;
+    if (!ensure_listener(&step)) return step;
+    std::string base;
+    if (!resolve_public_base(attempt, &base, &step)) return step;
+
+    if (options_.verify_public_url) {
+        progress(attempt, "正在检查公网地址能否访问本机");
+        if (!check_public(base, options_.public_check_timeout)) {
+            if (stopping_) return LinkStep::Stopped;
+            if (tunnel_mode()) {
+                drop_tunnel();  // 换一条隧道(新主机名)再试
+                set_status(LinkState::Retrying, "Cloudflare 隧道暂时无法从公网访问,正在重建");
+            } else {
+                set_status(LinkState::Retrying, "无法通过 " + base + " 访问本机 LINE 回调端口,请确认反向代理指向 http://127.0.0.1:" +
+                                                    std::to_string(listener_port_.load()));
+            }
+            return LinkStep::Retry;
+        }
+    }
+
+    const auto desired = base + kWebhookRoute;
+    WebhookInfo webhook;
+    if (!register_webhook(desired, &webhook, &step)) return step;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        public_base_ = base;
+        status_.extra["public_url"] = base;
+        status_.extra["webhook_url"] = desired;
+    }
+    log_quota();
+
+    while (!webhook.active) {
+        set_extra("webhook_active", false);
+        set_status(LinkState::Retrying, kUseWebhookOff);
+        if (!wait_for(options_.webhook_recheck)) return LinkStep::Stopped;
+        if (tunnel_mode() && !tunnel_.alive()) {
+            drop_tunnel();
+            return LinkStep::Retry;
+        }
+        const auto result = api_.webhook_info(&webhook, cancel);
+        if (stopping_) return LinkStep::Stopped;
+        if (result.auth_failed) {
+            set_status(LinkState::Failed, result.message, true);
+            return LinkStep::Fatal;
+        }
+        if (result.ok && webhook.endpoint != desired) {
+            LOG_WARN("[channels/line] webhook endpoint was changed elsewhere, registering it again");
+            api_.set_webhook(desired, cancel);
+        }
+    }
+    set_extra("webhook_active", true);
+    *reached = true;
+    LOG_INFO("[channels/line] connected, webhook " + desired);
+    set_status(LinkState::Connected, {});
+    return watch(base, desired);
+}
+
+bool LineTransport::ensure_listener(LinkStep* step) {
+    if (!options_.listener) {
+        set_status(LinkState::Failed, "LINE 回调端口组件缺失", true);
+        *step = LinkStep::Fatal;
+        return false;
+    }
+    if (listener_port_.load() != 0 && options_.listener->port() == listener_port_.load()) return true;
+    std::string error;
+    auto port = options_.listener->start(options_.listen_port, listener_handler(), &error);
+    if (port == 0 && options_.listen_port != 0 && tunnel_mode()) {
+        // 隧道模式下端口号无关紧要:指定端口被占用时退回系统分配。
+        LOG_WARN("[channels/line] listener port " + std::to_string(options_.listen_port) +
+                 " unavailable, falling back to an OS-assigned port");
+        port = options_.listener->start(0, listener_handler(), &error);
+    }
+    if (port == 0) {
+        set_status(LinkState::Retrying, "无法在本机 127.0.0.1:" + std::to_string(options_.listen_port) +
+                                            " 上接收 LINE 回调:" + error);
+        *step = LinkStep::Retry;
+        return false;
+    }
+    const auto previous = listener_port_.exchange(port);
+    if (previous != 0 && previous != port) drop_tunnel();  // 旧隧道指向旧端口
+    set_extra("listen_port", port);
+    LOG_INFO("[channels/line] webhook listener on 127.0.0.1:" + std::to_string(port));
+    if (port != options_.listen_port && options_.on_listen_port) options_.on_listen_port(port);
+    return true;
+}
+
+bool LineTransport::resolve_public_base(std::size_t attempt, std::string* base, LinkStep* step) {
+    if (!tunnel_mode()) {
+        *base = options_.public_url;
+        return true;
+    }
+    if (tunnel_.alive() && !tunnel_.public_url().empty()) {
+        *base = tunnel_.public_url();
+        return true;
+    }
+    drop_tunnel();
+    progress(attempt, "正在建立 Cloudflare 隧道");
+    TunnelFailure failure = TunnelFailure::None;
+    std::string error;
+    *base = tunnel_.start(listener_port_.load(), cancel_fn(), &failure, &error);
+    if (failure == TunnelFailure::Missing) {
+        set_extra("cloudflared_missing", true);  // 设置页据此提示安装,不必解析文字
+        set_status(LinkState::Failed, kCloudflaredInstallHint, true);
+        *step = LinkStep::Fatal;
+        return false;
+    }
+    if (failure == TunnelFailure::Cancelled || stopping_) {
+        *step = LinkStep::Stopped;
+        return false;
+    }
+    if (base->empty()) {
+        set_status(LinkState::Retrying, "Cloudflare 隧道启动失败:" + error);
+        *step = LinkStep::Retry;
+        return false;
+    }
+    return true;
+}
+
+bool LineTransport::check_public(const std::string& base, std::chrono::milliseconds timeout) {
+    std::string instance;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        instance = instance_id_;
+    }
+    const auto deadline = Clock::now() + timeout;
+    bool warned = false;
+    while (!stopping_) {
+        HttpRequest request;
+        request.url = base + kHealthRoute;
+        request.timeout = std::chrono::seconds(10);
+        request.use_proxy = options_.api.use_proxy;
+        request.cancel = cancel_fn();
+        const auto response = http_send(request);
+        if (response.status == 200 && response.body.find(instance) != std::string::npos) return true;
+        if (response.status == 200 && !warned) {
+            // 有应答但不是本进程的回调端口:公网地址指错了地方。
+            LOG_WARN("[channels/line] public URL answered, but not from this ACECode listener");
+            warned = true;
+        }
+        if (Clock::now() >= deadline) break;
+        if (!wait_for(options_.public_check_interval)) break;
+    }
+    LOG_WARN("[channels/line] public URL self-check failed");
+    return false;
+}
+
+bool LineTransport::register_webhook(const std::string& desired, WebhookInfo* info, LinkStep* step) {
+    const auto cancel = cancel_fn();
+    // 每次连上都重新登记一次(便宜且可靠:快速隧道每次重启主机名都会变,别人也可能在控制台改过)。
+    const auto put = api_.set_webhook(desired, cancel);
+    if (stopping_) {
+        *step = LinkStep::Stopped;
+        return false;
+    }
+    if (put.auth_failed) {
+        set_status(LinkState::Failed, put.message, true);
+        *step = LinkStep::Fatal;
+        return false;
+    }
+    if (!put.ok) {
+        if (put.status == 400 && !tunnel_mode()) {
+            set_status(LinkState::Failed, "LINE 不接受这个 webhook 地址(需要可从公网访问的 https 地址):" + put.message,
+                       true);
+            *step = LinkStep::Fatal;
+        } else {
+            set_status(LinkState::Retrying, "设置 LINE webhook 地址失败:" + put.message);
+            *step = LinkStep::Retry;
+        }
+        return false;
+    }
+    LOG_INFO("[channels/line] webhook endpoint registered (LINE may take up to a minute to switch)");
+    // 改地址不影响 “Use webhook” 开关(只能在控制台改),读出来决定是否算已连接。
+    const auto result = api_.webhook_info(info, cancel);
+    if (stopping_) {
+        *step = LinkStep::Stopped;
+        return false;
+    }
+    if (result.auth_failed) {
+        set_status(LinkState::Failed, result.message, true);
+        *step = LinkStep::Fatal;
+        return false;
+    }
+    if (!result.ok && result.status != 404) {
+        set_status(LinkState::Retrying, "读取 LINE webhook 设置失败:" + result.message);
+        *step = LinkStep::Retry;
+        return false;
+    }
+    // 404:LINE 侧缓存还没反映刚登记的地址(最多 1 分钟),按未开启处理,稍后复查。
+    if (!result.ok) info->active = false;
+    if (options_.test_webhook && desired != last_tested_endpoint_ && !run_webhook_test(desired, step)) return false;
+    return true;
+}
+
+bool LineTransport::run_webhook_test(const std::string& desired, LinkStep* step) {
+    // 测试接口每频道每小时只有 60 次,自己再限到每 10 分钟最多一次。
+    const auto now = Clock::now();
+    if (last_webhook_test_ != Clock::time_point{} && now - last_webhook_test_ < options_.webhook_test_interval)
+        return true;
+    last_webhook_test_ = now;
+    last_tested_endpoint_ = desired;
+    const auto result = api_.test_webhook(desired, cancel_fn());
+    if (stopping_) {
+        *step = LinkStep::Stopped;
+        return false;
+    }
+    if (!result.ok) {
+        LOG_WARN("[channels/line] webhook test call failed: " + result.message);
+        return true;
+    }
+    if (json_bool(result.body, "success")) {
+        LOG_INFO("[channels/line] LINE webhook test succeeded");
+        return true;
+    }
+    const auto reason = json_string(result.body, "reason");
+    const auto detail = json_string(result.body, "detail");
+    LOG_WARN("[channels/line] LINE webhook test failed: reason=" + reason + " detail=" +
+             redact_secrets(detail, {options_.api.channel_secret}));
+    if (reason == "ERROR_STATUS_CODE" && detail == "401") {
+        // LINE 的测试请求带签名,本机回 401 说明签名对不上:Channel secret 填错了。
+        set_status(LinkState::Failed, "Channel secret 与该频道不匹配,LINE 发来的消息无法通过签名校验", true);
+        *step = LinkStep::Fatal;
+        return false;
+    }
+    return true;
+}
+
+LineTransport::LinkStep LineTransport::watch(const std::string& base, const std::string& desired) {
+    const auto cancel = cancel_fn();
+    int tick = 0;
+    int self_failures = 0;
+    int not_ready = 0;
+    bool inactive = false;
+    while (true) {
+        if (!wait_for(options_.watch_interval)) return LinkStep::Stopped;
+        ++tick;
+        if (tunnel_mode()) {
+            if (!tunnel_.alive()) {
+                LOG_WARN("[channels/line] cloudflared exited, rebuilding the quick tunnel");
+                drop_tunnel();
+                set_status(LinkState::Retrying, "Cloudflare 隧道已退出,正在重建");
+                return LinkStep::Retry;
+            }
+            if (!tunnel_.ready()) {
+                // cloudflared 会自己重连边缘(主机名不变);长时间连不上才换一条隧道。
+                if (++not_ready >= 10) {
+                    drop_tunnel();
+                    set_status(LinkState::Retrying, "Cloudflare 隧道长时间断开,正在重建");
+                    return LinkStep::Retry;
+                }
+                set_status(LinkState::Retrying, "Cloudflare 隧道暂时断开,等待自动重连");
+                continue;
+            }
+            not_ready = 0;
+        }
+        const bool periodic = options_.self_check_every > 0 && tick % options_.self_check_every == 0;
+        if (periodic && options_.verify_public_url) {
+            if (!check_public(base, std::chrono::seconds(10))) {
+                if (stopping_) return LinkStep::Stopped;
+                if (++self_failures >= 3) {
+                    if (tunnel_mode()) drop_tunnel();
+                    set_status(LinkState::Retrying, "公网地址无法访问本机回调端口,正在重新连接");
+                    return LinkStep::Retry;
+                }
+            } else {
+                self_failures = 0;
+            }
+        }
+        if (periodic || inactive) {
+            WebhookInfo webhook;
+            const auto result = api_.webhook_info(&webhook, cancel);
+            if (stopping_) return LinkStep::Stopped;
+            if (result.auth_failed) {
+                set_status(LinkState::Failed, result.message, true);
+                return LinkStep::Fatal;
+            }
+            if (result.ok) {
+                if (webhook.endpoint != desired) {
+                    LOG_WARN("[channels/line] webhook endpoint was changed elsewhere, registering it again");
+                    api_.set_webhook(desired, cancel);
+                }
+                inactive = !webhook.active;
+                set_extra("webhook_active", webhook.active);
+                if (inactive) {
+                    set_status(LinkState::Retrying, kUseWebhookOff);
+                    continue;
+                }
+            }
+        }
+        set_status(LinkState::Connected, {});
+    }
+}
+
+void LineTransport::log_quota() {
+    nlohmann::json summary;
+    const auto result = api_.quota(&summary, cancel_fn());
+    if (!result.ok) return;
+    set_extra("push_quota", summary);
+    LOG_INFO("[channels/line] push quota: " + summary.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace));
+}
+
+// ---------------------------------------------------------------- 回调端口
+
+ListenerReply LineTransport::handle_request(const ListenerRequest& request) {
+    if (request.path == kWebhookRoute) {
+        if (request.method != "POST") return plain_reply(405, "method not allowed");
+        return accept_webhook(request.body, request.signature);
+    }
+    if (request.path == kHealthRoute) {
+        if (request.method != "GET" && request.method != "HEAD") return plain_reply(405, "method not allowed");
+        std::string instance;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            instance = instance_id_;
+        }
+        auto reply = plain_reply(200, nlohmann::json{{"status", "ok"}, {"platform", "line"}, {"instance", instance}}.dump());
+        reply.content_type = "application/json";
+        return reply;
+    }
+    if (request.path.rfind(kMediaRoutePrefix, 0) == 0) {
+        if (request.method != "GET" && request.method != "HEAD") return plain_reply(405, "method not allowed");
+        return serve_media(request.path, request.method == "HEAD");
+    }
+    return plain_reply(404, "not found");
+}
+
+ListenerReply LineTransport::accept_webhook(const std::string& body, const std::string& signature) {
+    if (body.size() > kMaxWebhookBodyBytes) return plain_reply(413, "payload too large");
+    // 签名必须在解析之前、按原始字节校验。
+    if (!verify_signature(body, signature, options_.api.channel_secret)) {
+        const auto count = ++rejected_signatures_;
+        if (count == 1 || count % 100 == 0)
+            LOG_WARN("[channels/line] rejected webhook with invalid signature (total " + std::to_string(count) + ")");
+        return plain_reply(401, "invalid signature");
+    }
+    {
+        std::lock_guard<std::mutex> lock(queue_mu_);
+        if (queue_.size() >= options_.max_queue) {
+            LOG_WARN("[channels/line] webhook queue full, asking LINE to redeliver later");
+            return plain_reply(503, "busy");
+        }
+        queue_.push_back({body, now_wall_ms()});
+    }
+    queue_cv_.notify_one();
+    return plain_reply(200, "OK");
+}
+
+ListenerReply LineTransport::serve_media(const std::string& path, bool head) {
+    const auto entry = media_.find_path(path);
+    if (!entry) return plain_reply(404, "not found");
+    std::error_code ec;
+    if (!std::filesystem::is_regular_file(entry->path, ec)) return plain_reply(404, "not found");
+    const auto size = std::filesystem::file_size(entry->path, ec);
+    if (ec || size > options_.max_image_bytes) return plain_reply(404, "not found");
+    ListenerReply reply = plain_reply(200, {});
+    reply.content_type = entry->mime_type.empty() ? "application/octet-stream" : entry->mime_type;
+    reply.headers.emplace_back("X-Content-Type-Options", "nosniff");
+    if (head) return reply;
+    std::ifstream in(entry->path, std::ios::binary);
+    reply.body.assign(std::istreambuf_iterator<char>(in), std::istreambuf_iterator<char>());
+    if (reply.body.size() != size) return plain_reply(404, "not found");
+    return reply;
+}
+
+// ---------------------------------------------------------------- 收消息
+
+void LineTransport::event_loop() {
+    while (true) {
+        QueuedWebhook item;
+        {
+            std::unique_lock<std::mutex> lock(queue_mu_);
+            queue_cv_.wait(lock, [this] { return stopping_.load() || !queue_.empty(); });
+            if (stopping_) return;
+            item = std::move(queue_.front());
+            queue_.pop_front();
+        }
+        try {
+            process_webhook(item);
+        } catch (const std::exception& e) {
+            LOG_WARN(std::string("[channels/line] failed to process webhook: ") + e.what());
+        }
+    }
+}
+
+void LineTransport::process_webhook(const QueuedWebhook& item) {
+    const auto bot = account();
+    auto parsed = parse_webhook(item.body, bot, item.received_at_ms);
+    if (!parsed.valid) {
+        LOG_WARN("[channels/line] ignored a signed webhook that is not valid JSON");
+        return;
+    }
+    if (!bot.empty() && !parsed.destination.empty() && parsed.destination != bot) {
+        LOG_WARN("[channels/line] ignored a webhook addressed to another bot");
+        return;
+    }
+    for (auto& event : parsed.events) {
+        if (stopping_) return;
+        handle_event(event);
+    }
+}
+
+bool LineTransport::seen_before(const std::string& key) {
+    std::lock_guard<std::mutex> lock(seen_mu_);
+    if (seen_.count(key)) return true;
+    seen_.insert(key);
+    seen_order_.push_back(key);
+    while (seen_order_.size() > kSeenLimit) {
+        seen_.erase(seen_order_.front());
+        seen_order_.pop_front();
+    }
+    return false;
+}
+
+void LineTransport::handle_event(WebhookEvent& event) {
+    if (!event.event_id.empty() && seen_before("e:" + event.event_id)) {
+        LOG_DEBUG("[channels/line] duplicate webhook event skipped");
+        return;
+    }
+    if (event.standby) {
+        LOG_INFO("[channels/line] standby event ignored (another module owns this chat)");
+        return;
+    }
+    switch (event.kind) {
+        case EventKind::Message:
+            break;
+        case EventKind::Follow:
+        case EventKind::Unfollow:
+        case EventKind::Join:
+        case EventKind::Leave:
+        case EventKind::Unsend:
+        case EventKind::MessageEdited:
+            LOG_INFO("[channels/line] " + event.type + " event (" + event.source_type + ")");
+            return;
+        default:
+            LOG_DEBUG("[channels/line] ignored event type " + event.type);
+            return;
+    }
+    if (!event.message_id.empty() && seen_before("m:" + event.message_id)) return;
+    if (event.redelivery) LOG_INFO("[channels/line] processing a redelivered message event");
+    if (!event.inbound) {
+        if (event.unidentified_sender) {
+            LOG_INFO("[channels/line] group message without userId (LINE desktop sender) ignored");
+            if (event.mentioned_self && !event.reply_token.empty()) send_unidentified_notice(event.reply_token);
+        }
+        return;
+    }
+    Inbound inbound = std::move(*event.inbound);
+    if (!event.quoted_message_id.empty()) {
+        // 平台不提供被引用消息的内容:从最近收发的消息里找;引用机器人的消息视同点名。
+        if (const auto quoted = recall_message(event.quoted_message_id)) {
+            inbound.quote_text = quoted->text;
+            if (quoted->from_bot) inbound.mentioned = true;
+        }
+    }
+    if (!inbound.text.empty()) remember_message(inbound.message_id, inbound.text, false);
+    if (options_.fetch_profiles) inbound.sender_name = sender_name(inbound.address);
+    note_reply_token(inbound.address, inbound.reply_context);
+    // 先用这条新消息的回复令牌补发之前暂存的输出,再交给核心处理新消息。
+    flush_held(inbound.address, inbound.reply_context);
+    if (callbacks_.on_inbound) callbacks_.on_inbound(std::move(inbound));
+}
+
+std::string LineTransport::sender_name(const Address& address) {
+    const auto key = address.chat + "|" + address.sender;
+    const auto now = Clock::now();
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        const auto it = names_.find(key);
+        if (it != names_.end() && now - it->second.second < kNameTtl) return it->second.first;
+    }
+    std::string name;
+    const auto result = api_.display_name(address.chat, address.sender, &name);
+    if (!result.ok) {
+        LOG_DEBUG("[channels/line] display name unavailable (HTTP " + std::to_string(result.status) + ")");
+        name.clear();
+    }
+    std::lock_guard<std::mutex> lock(mu_);
+    if (names_.size() >= kNameCacheLimit) names_.clear();
+    names_[key] = {name, now};
+    return name;
+}
+
+void LineTransport::remember_message(const std::string& id, const std::string& text, bool from_bot) {
+    if (id.empty()) return;
+    std::lock_guard<std::mutex> lock(mu_);
+    if (!recent_.count(id)) recent_order_.push_back(id);
+    auto& entry = recent_[id];
+    entry.text = text.size() > 4000 ? text.substr(0, 4000) : text;
+    entry.from_bot = from_bot;
+    while (recent_order_.size() > kRecentLimit) {
+        recent_.erase(recent_order_.front());
+        recent_order_.pop_front();
+    }
+}
+
+std::optional<LineTransport::RecentMessage> LineTransport::recall_message(const std::string& id) {
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto it = recent_.find(id);
+    if (it == recent_.end()) return std::nullopt;
+    return it->second;
+}
+
+void LineTransport::note_reply_token(const Address& address, const nlohmann::json& reply_context) {
+    const auto token = reply_token_of(reply_context);
+    if (!token) return;
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto now = now_wall_ms();
+    for (auto it = latest_reply_.begin(); it != latest_reply_.end();) {
+        if (!reply_token_fresh(it->second, now)) it = latest_reply_.erase(it);
+        else ++it;
+    }
+    latest_reply_[address.key()] = *token;
+}
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/line/line_transport.hpp b/src/adapters/im/line/line_transport.hpp
new file mode 100644
index 000000000..c93e2d98f
--- /dev/null
+++ b/src/adapters/im/line/line_transport.hpp
@@ -0,0 +1,230 @@
+#pragma once
+
+// LINE 传输层。LINE 机器人只能用 webhook 收消息,所以连接过程是:
+//   1. 用 Channel ID + secret 换令牌(或用长期令牌),读 /v2/bot/info 得到机器人 userId;
+//   2. 在 127.0.0.1 上开 LINE 专用回调端口(WebhookListener,Crow 实现由核心注入);
+//   3. 取得公网地址:用户自己的 HTTPS 地址,或启动 Cloudflare 快速隧道;
+//   4. 经公网地址访问 /line/health 自检,确认请求确实到达本机这个端口;
+//   5. 用 PUT /v2/bot/channel/webhook/endpoint 把 <公网地址>/line/webhook 登记给 LINE;
+//   6. “Use webhook” 开着才算已连接(这个开关只能在控制台手动打开)。
+// 之后持续看守:隧道进程退出或长时间断开就重建隧道并重新登记(快速隧道每次主机名都会变)。
+//
+// 收消息:回调线程只校验签名、入队并立即回 200(LINE 要求 2 秒内应答);
+// 解析、去重、补发暂存输出、交给核心都在传输层自己的事件线程里做。
+//
+// 发消息:回复令牌新鲜(50 秒内)且没用过时用 reply(免费),否则用 push(计入每月额度);
+// 一次最多 5 条;push 因每月额度用完被拒时暂存,等对方下一条消息到来时用它的回复令牌补发。
+// LINE 机器人不能发文件:图片经回调端口的临时链接发送,其它文件改发一条文字说明。
+
+#include "im/line/line_api.hpp"
+#include "im/line/line_media.hpp"
+#include "im/line/line_protocol.hpp"
+#include "im/line/line_tunnel.hpp"
+#include "im/line/line_webhook.hpp"
+#include "im/transport.hpp"
+#include "utils/joining_thread.hpp"
+#include "utils/lifetime_token.hpp"
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <deque>
+#include <filesystem>
+#include <functional>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <set>
+#include <string>
+#include <vector>
+
+namespace acecode::im::line {
+
+struct LineTransportOptions {
+    ApiOptions api;
+    // 必填:回调端口实现(channels::core::LineWebhookServer)。每个传输层实例独占一个。
+    std::shared_ptr<WebhookListener> listener;
+    // 用户自己的公网 HTTPS 地址(其反向代理 / 隧道指向 http://127.0.0.1:<listen_port>);
+    // 为空时自动启动 Cloudflare 快速隧道。
+    std::string public_url;
+    std::uint16_t listen_port = 0;  // 0 = 系统分配;填了自己的公网地址时应固定
+    // 实际监听端口与 listen_port 不同时回调(核心可持久化,下次沿用)。
+    std::function<void(std::uint16_t)> on_listen_port;
+    TunnelOptions tunnel;
+    bool verify_public_url = true;  // 登记前经公网地址访问 /line/health 自检
+    bool test_webhook = true;       // 地址变化后调用 LINE 的 webhook 测试接口(每 10 分钟最多一次)
+    bool fetch_profiles = true;     // 取发言人显示名(带缓存)
+    std::vector<std::chrono::milliseconds> backoff{
+        std::chrono::seconds(1), std::chrono::seconds(2), std::chrono::seconds(5),
+        std::chrono::seconds(10), std::chrono::seconds(30), std::chrono::seconds(60)};
+    std::chrono::milliseconds public_check_timeout{std::chrono::seconds(60)};
+    std::chrono::milliseconds public_check_interval{std::chrono::seconds(2)};
+    std::chrono::milliseconds watch_interval{std::chrono::seconds(30)};
+    int self_check_every = 10;      // 每 N 次看守做一次公网自检与 webhook 设置复查(约 5 分钟)
+    std::chrono::milliseconds webhook_recheck{std::chrono::seconds(60)};  // “Use webhook” 关着时的复查间隔
+    std::chrono::milliseconds webhook_test_interval{std::chrono::minutes(10)};
+    std::chrono::milliseconds typing_refresh{std::chrono::seconds(50)};
+    // 发出消息后动画会消失;仍在忙碌时隔这么久再重显。留出间隔是为了回合结束时
+    // (先发最后一条、再关闭“正在输入”)不会在最终答复之后又冒出一次动画。
+    std::chrono::milliseconds typing_resume_delay{std::chrono::seconds(2)};
+    std::vector<std::chrono::milliseconds> send_retry{
+        std::chrono::seconds(1), std::chrono::seconds(2), std::chrono::seconds(4)};
+    std::chrono::milliseconds media_ttl{std::chrono::minutes(30)};
+    std::uint64_t max_image_bytes = 10u * 1024u * 1024u;
+    std::uint64_t max_download_bytes = 25u * 1024u * 1024u;
+    std::size_t max_queue = 256;    // 待处理 webhook 上限;满了回 503(开启重投时 LINE 会重发)
+};
+
+// 推送被拒后暂存的输出。plain=true 表示 text 已是纯文本分段,补发时不再转换。
+struct HeldItem {
+    bool file = false;
+    bool plain = false;
+    std::string text;
+    std::filesystem::path path;
+    std::string name;
+    std::string mime_type;
+};
+
+class LineTransport final : public Transport {
+public:
+    static constexpr std::size_t kMaxHeldPerConversation = 20;
+
+    explicit LineTransport(LineTransportOptions options);
+    ~LineTransport() override;
+
+    std::string platform() const override { return kPlatform; }
+    Capabilities capabilities() const override;
+    void start(TransportCallbacks callbacks) override;
+    void stop() override;
+    TransportStatus status() const override;
+    SendResult send_text(const Address& to, const std::string& text,
+                         const nlohmann::json& reply_context) override;
+    SendResult send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                         const std::string& mime_type, const nlohmann::json& reply_context) override;
+    // 只对私聊有效(LINE 只允许对用户 id 显示动画);忙碌期间每 50 秒续一次,发出消息后立即重显。
+    void set_typing(const Address& to, bool on) override;
+    bool download(const Attachment& attachment, const std::filesystem::path& dest,
+                  std::string* error) override;
+
+    // 回调端口的请求分发(在回调端口的 HTTP 线程上调用;测试也可直接调用)。
+    ListenerReply handle_request(const ListenerRequest& request);
+    std::size_t held_count() const;
+    std::uint16_t listen_port() const;
+    std::string public_base() const;
+
+private:
+    enum class LinkStep { Stopped, Fatal, Retry };
+    struct QueuedWebhook {
+        std::string body;
+        std::int64_t received_at_ms = 0;
+    };
+    struct Piece {
+        nlohmann::json message;
+        HeldItem source;  // 推送被拒时据此暂存
+        std::string text;  // 文字消息的内容(引用识别用);图片为空
+    };
+    struct RecentMessage {
+        std::string text;
+        bool from_bot = false;
+    };
+
+    // ---- 连接与看守(line_transport.cpp) ----
+    void link_loop();
+    LinkStep connect_and_watch(std::size_t attempt, bool* reached);
+    bool ensure_listener(LinkStep* step);
+    bool resolve_public_base(std::size_t attempt, std::string* base, LinkStep* step);
+    bool check_public(const std::string& base, std::chrono::milliseconds timeout);
+    bool register_webhook(const std::string& desired, WebhookInfo* info, LinkStep* step);
+    bool run_webhook_test(const std::string& desired, LinkStep* step);
+    LinkStep watch(const std::string& base, const std::string& desired);
+    void log_quota();
+    void progress(std::size_t attempt, const std::string& detail);
+    void set_status(LinkState state, const std::string& detail, bool retry_stopped = false);
+    void set_extra(const std::string& key, nlohmann::json value);
+    void drop_tunnel();
+    bool wait_for(std::chrono::milliseconds duration);
+    CancelFn cancel_fn() const;
+    ListenerHandler listener_handler();
+    std::string account() const;
+    bool tunnel_mode() const { return options_.public_url.empty(); }
+
+    // ---- 收消息(line_transport.cpp) ----
+    ListenerReply accept_webhook(const std::string& body, const std::string& signature);
+    ListenerReply serve_media(const std::string& path, bool head);
+    void event_loop();
+    void process_webhook(const QueuedWebhook& item);
+    void handle_event(WebhookEvent& event);
+    bool seen_before(const std::string& key);
+    std::string sender_name(const Address& address);
+    void remember_message(const std::string& id, const std::string& text, bool from_bot);
+    std::optional<RecentMessage> recall_message(const std::string& id);
+    void note_reply_token(const Address& address, const nlohmann::json& reply_context);
+
+    // ---- 发消息(line_outbound.cpp) ----
+    SendResult deliver_locked(const Address& to, std::vector<HeldItem> items, const nlohmann::json& reply_context,
+                              bool flushing);
+    std::vector<Piece> build_pieces(const Address& to, const std::vector<HeldItem>& items,
+                                    const nlohmann::json& reply_context, bool flushing);
+    std::optional<ReplyToken> usable_reply_token_locked(const Address& to, const nlohmann::json& reply_context);
+    void mark_token_used_locked(const std::string& token);
+    void after_sent(const Address& to, const std::vector<Piece>& pieces, std::size_t begin, std::size_t count,
+                    const ApiResult& result);
+    void hold(const std::string& key, std::vector<HeldItem> items);
+    std::deque<HeldItem> take_held(const std::string& key);
+    std::size_t held_size(const std::string& key) const;
+    void flush_held(const Address& address, const nlohmann::json& reply_context);
+    void send_unidentified_notice(const std::string& reply_token);
+    void typing_loop();
+    void wake_typer();
+
+    LineTransportOptions options_;
+    Api api_;
+    CloudflareTunnel tunnel_;
+    MediaRegistry media_;
+    TransportCallbacks callbacks_;
+    std::shared_ptr<std::atomic<bool>> cancel_flag_ = std::make_shared<std::atomic<bool>>(false);
+    std::atomic<bool> running_{false};
+    std::atomic<bool> stopping_{false};
+    std::atomic<bool> typing_wake_{false};
+    std::atomic<bool> quota_exhausted_{false};
+    std::atomic<std::uint64_t> rejected_signatures_{0};
+    std::atomic<std::uint16_t> listener_port_{0};
+    std::chrono::steady_clock::time_point last_webhook_test_{};  // 只由连接线程读写
+    std::string last_tested_endpoint_;                           // 只由连接线程读写
+    acecode::JoiningThread link_, events_, typer_;
+    std::mutex wake_mu_;
+    std::condition_variable wake_;
+
+    mutable std::mutex mu_;  // 以下状态、身份、公网地址、缓存、正在输入
+    TransportStatus status_;
+    std::string account_;
+    std::string public_base_;
+    std::string instance_id_;
+    std::map<std::string, ReplyToken> latest_reply_;  // 会话键 → 最近一条入站消息的回复令牌
+    std::map<std::string, RecentMessage> recent_;
+    std::deque<std::string> recent_order_;
+    std::map<std::string, std::pair<std::string, std::chrono::steady_clock::time_point>> names_;
+    std::map<std::string, std::chrono::steady_clock::time_point> typing_;  // 用户 id → 下次续显时间
+
+    std::mutex queue_mu_;
+    std::condition_variable queue_cv_;
+    std::deque<QueuedWebhook> queue_;
+
+    std::mutex seen_mu_;
+    std::set<std::string> seen_;
+    std::deque<std::string> seen_order_;
+
+    std::mutex send_mu_;  // 串行化所有发送,保证同一会话的顺序;以下令牌记录也由它保护
+    std::set<std::string> used_tokens_;
+    std::deque<std::string> used_order_;
+
+    mutable std::mutex held_mu_;
+    std::map<std::string, std::deque<HeldItem>> held_;
+
+    // 最后声明:析构时先撤销,回调端口上还在执行的处理函数结束后才继续析构其它成员。
+    acecode::LifetimeToken lifetime_;
+};
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/line/line_tunnel.cpp b/src/adapters/im/line/line_tunnel.cpp
new file mode 100644
index 000000000..447d8e6fe
--- /dev/null
+++ b/src/adapters/im/line/line_tunnel.cpp
@@ -0,0 +1,291 @@
+#ifdef _WIN32
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+#include <winsock2.h>
+#include <ws2tcpip.h>
+#else
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <sys/socket.h>
+#include <unistd.h>
+#endif
+
+#include "im/line/line_tunnel.hpp"
+
+#include "im/http.hpp"
+#include "platform/process/piped_process.hpp"
+#include "platform/process/which.hpp"
+#include "utils/encoding.hpp"
+#include "utils/joining_thread.hpp"
+#include "utils/logger.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <algorithm>
+#include <filesystem>
+#include <thread>
+
+namespace acecode::im::line {
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+// 真实的 cloudflared 子进程:stdio 管道由 PipedProcess 管理(stderr 丢弃),
+// 读线程持续读空 stdout,避免子进程写满管道后卡住。
+class ChildTunnelProcess final : public TunnelProcess {
+public:
+    ~ChildTunnelProcess() override { stop(); }
+
+    bool start(const std::vector<std::string>& argv, std::string* error) {
+        platform::SpawnOptions spawn;
+        spawn.argv = argv;
+        if (!process_.start(spawn, error)) return false;
+        reader_ = acecode::JoiningThread(&ChildTunnelProcess::drain, this);
+        return true;
+    }
+
+    bool alive() override { return process_.started() && !process_.wait_exit(0); }
+
+    void stop() override {
+        if (!process_.started()) return;
+        // 先杀进程让读线程从阻塞读里返回,等它退出后再关句柄。
+        process_.kill_child();
+        if (reader_.joinable()) reader_.join();
+        process_.terminate();
+    }
+
+private:
+    void drain() {
+        char buffer[4096];
+        while (process_.read_stdout(buffer, sizeof(buffer)) > 0) {
+        }
+    }
+
+    platform::PipedProcess process_;
+    acecode::JoiningThread reader_;
+};
+
+std::unique_ptr<TunnelProcess> launch_child(const std::vector<std::string>& argv, std::string* error) {
+    auto process = std::make_unique<ChildTunnelProcess>();
+    if (!process->start(argv, error)) return nullptr;
+    return process;
+}
+
+HttpResponse metrics_get(std::uint16_t port, const std::string& path) {
+    HttpRequest request;
+    request.url = "http://127.0.0.1:" + std::to_string(port) + path;
+    request.timeout = std::chrono::seconds(3);
+    request.use_proxy = false;
+    return http_send(request);
+}
+
+bool wait_cancellable(std::chrono::milliseconds duration, const std::function<bool()>& cancel) {
+    const auto deadline = Clock::now() + duration;
+    while (Clock::now() < deadline) {
+        if (cancel && cancel()) return false;
+        const auto left = std::chrono::duration_cast<std::chrono::milliseconds>(deadline - Clock::now());
+        std::this_thread::sleep_for((std::min)(left, std::chrono::milliseconds(50)));
+    }
+    return !(cancel && cancel());
+}
+
+bool hostname_char(char c) {
+    return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '-' || c == '.' ||
+           c == ':';
+}
+
+} // namespace
+
+std::vector<std::string> cloudflared_install_candidates(const std::function<std::string(const char*)>& env) {
+    std::vector<std::string> out;
+    auto add = [&out](const std::string& base, const char* tail) {
+        if (!base.empty()) out.push_back(base + tail);
+    };
+    add(env("LOCALAPPDATA"), "\\Microsoft\\WinGet\\Links\\cloudflared.exe");
+    add(env("ProgramFiles(x86)"), "\\cloudflared\\cloudflared.exe");
+    add(env("ProgramFiles"), "\\cloudflared\\cloudflared.exe");
+    return out;
+}
+
+std::string locate_cloudflared() {
+    if (const auto found = platform::which("cloudflared")) return *found;
+#ifdef _WIN32
+    const auto env = [](const char* name) { return getenv_utf8(name); };
+    const std::vector<std::string> candidates = cloudflared_install_candidates(env);
+#else
+    const std::vector<std::string> candidates{"/opt/homebrew/bin/cloudflared", "/usr/local/bin/cloudflared",
+                                              "/usr/bin/cloudflared"};
+#endif
+    for (const auto& candidate : candidates) {
+        std::error_code ec;
+        if (std::filesystem::is_regular_file(path_from_utf8(candidate), ec)) return candidate;
+    }
+    return {};
+}
+
+std::vector<std::string> cloudflared_argv(const std::string& executable, std::uint16_t target_port,
+                                          std::uint16_t metrics_port, const TunnelOptions& options) {
+    std::vector<std::string> argv{executable, "tunnel", "--no-autoupdate"};
+    if (!options.config_path.empty()) {
+        argv.push_back("--config");
+        argv.push_back(options.config_path);
+    }
+    // 指标服务只能在 127.0.0.1(它带 /debug/pprof 与 /config,绝不能暴露)。
+    argv.push_back("--metrics");
+    argv.push_back("127.0.0.1:" + std::to_string(metrics_port));
+    if (!options.protocol.empty()) {
+        argv.push_back("--protocol");
+        argv.push_back(options.protocol);
+    }
+    if (!options.log_file.empty()) {
+        argv.push_back("--logfile");
+        argv.push_back(options.log_file);
+    }
+    // 用 127.0.0.1 而不是 localhost,避免解析成 ::1 而回调端口只监听 IPv4。
+    argv.push_back("--url");
+    argv.push_back("http://127.0.0.1:" + std::to_string(target_port));
+    return argv;
+}
+
+std::optional<std::string> parse_quicktunnel_hostname(const std::string& body) {
+    try {
+        const auto json = nlohmann::json::parse(body);
+        if (!json.is_object() || !json.contains("hostname") || !json["hostname"].is_string()) return std::nullopt;
+        const auto host = json["hostname"].get<std::string>();
+        if (host.empty() || host.size() > 253) return std::nullopt;
+        if (!std::all_of(host.begin(), host.end(), hostname_char)) return std::nullopt;
+        return host;
+    } catch (...) {
+        return std::nullopt;
+    }
+}
+
+std::uint16_t pick_free_loopback_port() {
+#ifdef _WIN32
+    WSADATA data;
+    if (::WSAStartup(MAKEWORD(2, 2), &data) != 0) return 0;
+    std::uint16_t port = 0;
+    const SOCKET s = ::socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
+    if (s != INVALID_SOCKET) {
+        sockaddr_in address{};
+        address.sin_family = AF_INET;
+        address.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+        address.sin_port = 0;
+        int length = sizeof(address);
+        if (::bind(s, reinterpret_cast<sockaddr*>(&address), sizeof(address)) == 0 &&
+            ::getsockname(s, reinterpret_cast<sockaddr*>(&address), &length) == 0)
+            port = ntohs(address.sin_port);
+        ::closesocket(s);
+    }
+    ::WSACleanup();
+    return port;
+#else
+    std::uint16_t port = 0;
+    const int s = ::socket(AF_INET, SOCK_STREAM, 0);
+    if (s >= 0) {
+        sockaddr_in address{};
+        address.sin_family = AF_INET;
+        address.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+        address.sin_port = 0;
+        socklen_t length = sizeof(address);
+        if (::bind(s, reinterpret_cast<sockaddr*>(&address), sizeof(address)) == 0 &&
+            ::getsockname(s, reinterpret_cast<sockaddr*>(&address), &length) == 0)
+            port = ntohs(address.sin_port);
+        ::close(s);
+    }
+    return port;
+#endif
+}
+
+CloudflareTunnel::CloudflareTunnel(TunnelOptions options) : options_(std::move(options)) {}
+
+CloudflareTunnel::~CloudflareTunnel() { stop(); }
+
+std::string CloudflareTunnel::executable() {
+    if (!options_.cloudflared_path.empty()) {
+        std::error_code ec;
+        return std::filesystem::is_regular_file(path_from_utf8(options_.cloudflared_path), ec)
+                   ? options_.cloudflared_path
+                   : std::string{};
+    }
+    return options_.locate ? options_.locate() : locate_cloudflared();
+}
+
+std::string CloudflareTunnel::start(std::uint16_t target_port, const std::function<bool()>& cancel,
+                                    TunnelFailure* failure, std::string* error) {
+    stop();
+    auto fail = [failure, error](TunnelFailure kind, const std::string& reason) {
+        if (failure) *failure = kind;
+        if (error) *error = reason;
+        return std::string{};
+    };
+    if (failure) *failure = TunnelFailure::None;
+    const auto exe = executable();
+    if (exe.empty()) return fail(TunnelFailure::Missing, kCloudflaredInstallHint);
+    metrics_port_ = options_.metrics_port ? options_.metrics_port : pick_free_loopback_port();
+    if (metrics_port_ == 0) return fail(TunnelFailure::Launch, "无法为 cloudflared 分配本机端口");
+
+    std::string launch_error;
+    const auto argv = cloudflared_argv(exe, target_port, metrics_port_, options_);
+    process_ = options_.launch ? options_.launch(argv, &launch_error) : launch_child(argv, &launch_error);
+    if (!process_) return fail(TunnelFailure::Launch, "无法启动 cloudflared:" + launch_error);
+    LOG_INFO("[channels/line] cloudflared started, metrics on 127.0.0.1:" + std::to_string(metrics_port_));
+
+    const auto deadline = Clock::now() + options_.ready_timeout;
+    std::string hostname;
+    while (true) {
+        if (cancel && cancel()) {
+            stop();
+            return fail(TunnelFailure::Cancelled, "已取消");
+        }
+        if (!process_->alive()) {
+            stop();
+            LOG_WARN("[channels/line] cloudflared exited before the quick tunnel was ready");
+            return fail(TunnelFailure::Exited,
+                        "cloudflared 已退出(可能连不上 Cloudflare,或 trycloudflare.com 暂时限流)");
+        }
+        if (hostname.empty()) {
+            const auto response = metrics_get(metrics_port_, "/quicktunnel");
+            if (response.status == 200) {
+                if (const auto host = parse_quicktunnel_hostname(response.body)) hostname = *host;
+            }
+        }
+        if (!hostname.empty() && metrics_get(metrics_port_, "/ready").status == 200) break;
+        if (Clock::now() >= deadline) {
+            stop();
+            LOG_WARN(std::string("[channels/line] cloudflared not ready in time (hostname ") +
+                     (hostname.empty() ? "missing" : "assigned") + ")");
+            return fail(TunnelFailure::Timeout, "等待 Cloudflare 隧道就绪超时");
+        }
+        if (!wait_cancellable(options_.poll_interval, cancel)) {
+            stop();
+            return fail(TunnelFailure::Cancelled, "已取消");
+        }
+    }
+    public_url_ = options_.url_scheme + "://" + hostname;
+    LOG_INFO("[channels/line] quick tunnel ready: " + public_url_);
+    return public_url_;
+}
+
+bool CloudflareTunnel::alive() { return process_ && process_->alive(); }
+
+bool CloudflareTunnel::ready() {
+    if (!process_ || metrics_port_ == 0) return false;
+    return metrics_get(metrics_port_, "/ready").status == 200;
+}
+
+void CloudflareTunnel::stop() {
+    if (process_) {
+        process_->stop();
+        process_.reset();
+        LOG_INFO("[channels/line] cloudflared stopped");
+    }
+    public_url_.clear();
+}
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/line/line_tunnel.hpp b/src/adapters/im/line/line_tunnel.hpp
new file mode 100644
index 000000000..9a8dceaf4
--- /dev/null
+++ b/src/adapters/im/line/line_tunnel.hpp
@@ -0,0 +1,96 @@
+#pragma once
+
+// Cloudflare 快速隧道(trycloudflare.com)管理:为本机 LINE 回调端口申请一个临时公网 HTTPS 地址。
+//
+//   cloudflared tunnel --no-autoupdate --metrics 127.0.0.1:<空闲端口> --url http://127.0.0.1:<回调端口>
+//
+// 公网主机名从 cloudflared 本机指标服务读取:GET /quicktunnel → {"hostname":"xxx.trycloudflare.com"}
+// (分配前为空串);GET /ready 返回 200 表示已与 Cloudflare 边缘建立连接。
+// 只探测已安装的 cloudflared(PATH 与 Windows 常见安装位置),绝不自动下载。
+// 隧道只指向 LINE 专用的回调端口,绝不指向 ACECode 主 Web 端口。
+//
+// 线程:CloudflareTunnel 不是线程安全的,只由传输层的连接线程使用;真实子进程的输出由
+// 内部 JoiningThread 持续读空,避免管道写满卡住子进程。
+
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace acecode::im::line {
+
+// 已启动的 cloudflared 子进程。测试注入假实现。
+class TunnelProcess {
+public:
+    virtual ~TunnelProcess() = default;
+    virtual bool alive() = 0;  // 进程是否还在运行
+    virtual void stop() = 0;   // 结束进程并回收;阻塞,可重复调用
+};
+
+using TunnelLauncher =
+    std::function<std::unique_ptr<TunnelProcess>(const std::vector<std::string>& argv, std::string* error)>;
+
+struct TunnelOptions {
+    std::string cloudflared_path;          // 用户指定的路径;为空时自动查找
+    std::function<std::string()> locate;   // 测试用:替换自动查找;返回空串表示没装
+    TunnelLauncher launch;                 // 测试用:替换真实子进程
+    std::uint16_t metrics_port = 0;        // 0 = 每次启动挑一个本机空闲端口
+    std::string protocol;                  // 空 = cloudflared 默认(quic);UDP 被封的网络可设 "http2"
+    std::string config_path;               // 可选:指定一个空配置文件,避免读到 ~/.cloudflared/config.yml
+    std::string log_file;                  // 可选:cloudflared 自己的日志文件(排查隧道问题用)
+    std::string url_scheme = "https";      // 测试用 http
+    std::chrono::milliseconds ready_timeout{std::chrono::seconds(45)};
+    std::chrono::milliseconds poll_interval{std::chrono::milliseconds(500)};
+};
+
+// 用户安装 cloudflared 的提示(状态文字里用)。
+inline constexpr const char* kCloudflaredInstallHint =
+    "未找到 cloudflared:请运行 winget install --id Cloudflare.cloudflared 安装后重新连接,或填写自己的公网 HTTPS 地址";
+
+// 查找顺序:PATH 上的 cloudflared,然后 Windows 常见安装位置。找不到返回空串。
+std::string locate_cloudflared();
+// 纯函数:Windows 常见安装位置(按优先级);env 取环境变量(UTF-8),没有时返回空串。
+std::vector<std::string> cloudflared_install_candidates(const std::function<std::string(const char*)>& env);
+
+std::vector<std::string> cloudflared_argv(const std::string& executable, std::uint16_t target_port,
+                                          std::uint16_t metrics_port, const TunnelOptions& options);
+
+// 解析 /quicktunnel 的应答;主机名为空或格式不对时返回 nullopt。
+std::optional<std::string> parse_quicktunnel_hostname(const std::string& body);
+
+// 在 127.0.0.1 上找一个当前空闲的 TCP 端口;失败返回 0。
+std::uint16_t pick_free_loopback_port();
+
+enum class TunnelFailure { None, Missing, Launch, Exited, Timeout, Cancelled };
+
+class CloudflareTunnel {
+public:
+    explicit CloudflareTunnel(TunnelOptions options);
+    ~CloudflareTunnel();
+    CloudflareTunnel(const CloudflareTunnel&) = delete;
+    CloudflareTunnel& operator=(const CloudflareTunnel&) = delete;
+
+    // 启动 cloudflared 指向 http://127.0.0.1:<target_port>,等到拿到主机名且 /ready 为 200。
+    // 成功返回公网地址(如 https://abc.trycloudflare.com);失败返回空串并给出原因。
+    std::string start(std::uint16_t target_port, const std::function<bool()>& cancel, TunnelFailure* failure,
+                      std::string* error);
+    bool running() const { return static_cast<bool>(process_); }
+    bool alive();
+    // 指标服务 /ready 是否为 200(进程还在但与边缘断开时为 false)。
+    bool ready();
+    void stop();
+    const std::string& public_url() const { return public_url_; }
+
+private:
+    std::string executable();
+
+    TunnelOptions options_;
+    std::unique_ptr<TunnelProcess> process_;
+    std::uint16_t metrics_port_ = 0;
+    std::string public_url_;
+};
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/line/line_webhook.hpp b/src/adapters/im/line/line_webhook.hpp
new file mode 100644
index 000000000..654de1f5a
--- /dev/null
+++ b/src/adapters/im/line/line_webhook.hpp
@@ -0,0 +1,59 @@
+#pragma once
+
+// LINE 回调接收端口的抽象接口。LINE 只能用 webhook 推送消息,ACECode 必须在本机开一个
+// HTTP 端口,再经 Cloudflare 隧道或用户自己的反向代理暴露到公网。
+//
+// 分层:adapters 不能依赖 Crow(R7),所以这里只定义接口;Crow 实现在
+// host/channels/core/line_webhook_server.{hpp,cpp}(channels::core::LineWebhookServer),
+// 由核心创建后经 LineTransportOptions::listener 交给传输层。
+//
+// 约定(实现必须遵守):
+//   - 只监听 127.0.0.1,绝不监听 0.0.0.0;不能是 ACECode 主 Web 端口(本机请求在那边免 token);
+//   - 只提供 POST /line/webhook、GET /line/health、GET /line/media/<令牌>/<文件名>,
+//     其余一律 404,不加任何 CORS 头;
+//   - 请求体原样交给处理函数(签名按原始字节计算,不能先解析再序列化);
+//   - 处理函数在 HTTP 线程上调用,必须很快返回(传输层只校验签名并入队)。
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace acecode::im::line {
+
+inline constexpr const char* kWebhookRoute = "/line/webhook";
+inline constexpr const char* kHealthRoute = "/line/health";
+// 超过 1 MiB 的请求体直接拒绝(LINE 的 webhook 远小于此)。
+inline constexpr std::size_t kMaxWebhookBodyBytes = 1024 * 1024;
+
+struct ListenerRequest {
+    std::string method;     // "GET" / "POST" / "HEAD"
+    std::string path;       // 不含查询串,未解码
+    std::string body;       // 原始字节
+    std::string signature;  // X-Line-Signature(头名大小写不敏感)
+};
+
+struct ListenerReply {
+    int status = 404;
+    std::string content_type = "text/plain; charset=utf-8";
+    std::string body;
+    std::vector<std::pair<std::string, std::string>> headers;
+};
+
+using ListenerHandler = std::function<ListenerReply(const ListenerRequest&)>;
+
+class WebhookListener {
+public:
+    virtual ~WebhookListener() = default;
+    // 在 127.0.0.1:port 上开始监听(port 为 0 时由系统分配)。成功返回实际端口;
+    // 失败返回 0 并写 error。已在运行时先停掉再重新监听。
+    virtual std::uint16_t start(std::uint16_t port, ListenerHandler handler, std::string* error) = 0;
+    // 阻塞到服务线程全部退出;返回后不再调用 handler,并释放它。可重复调用。
+    virtual void stop() = 0;
+    // 正在监听的端口;未运行时为 0。
+    virtual std::uint16_t port() const = 0;
+};
+
+} // namespace acecode::im::line
diff --git a/src/adapters/im/markdown.cpp b/src/adapters/im/markdown.cpp
new file mode 100644
index 000000000..331befa3b
--- /dev/null
+++ b/src/adapters/im/markdown.cpp
@@ -0,0 +1,347 @@
+#include "markdown.hpp"
+
+#include <cctype>
+#include <vector>
+
+namespace acecode::im {
+namespace {
+
+enum class BlockKind { Text, Blank, Code, Heading, Quote, Bullet, Ordered, Table, Rule };
+
+struct Block {
+    BlockKind kind = BlockKind::Text;
+    std::string text;               // 标题/列表/段落行的正文;代码块内容
+    std::string lang;               // 代码块语言
+    std::string marker;             // 有序列表编号或列表缩进
+    std::vector<std::string> lines; // 引用与表格的多行
+};
+
+bool is_alnum(char c) { return std::isalnum(static_cast<unsigned char>(c)) != 0; }
+
+std::string trim(std::string_view text) {
+    std::size_t b = 0, e = text.size();
+    while (b < e && (text[b] == ' ' || text[b] == '\t')) ++b;
+    while (e > b && (text[e - 1] == ' ' || text[e - 1] == '\t' || text[e - 1] == '\r')) --e;
+    return std::string(text.substr(b, e - b));
+}
+
+std::size_t leading_spaces(std::string_view line) {
+    std::size_t i = 0;
+    while (i < line.size() && line[i] == ' ') ++i;
+    return i;
+}
+
+bool fence_open(std::string_view line, std::string* lang) {
+    const auto indent = leading_spaces(line);
+    if (indent > 3 || line.substr(indent, 3) != "```") return false;
+    if (lang) {
+        *lang = trim(line.substr(indent + 3));
+        const auto space = lang->find(' ');
+        if (space != std::string::npos) lang->resize(space);
+    }
+    return true;
+}
+
+bool is_rule(std::string_view line) {
+    const auto text = trim(line);
+    if (text.size() < 3) return false;
+    const char c = text[0];
+    if (c != '-' && c != '*' && c != '_') return false;
+    std::size_t count = 0;
+    for (const char ch : text) {
+        if (ch == c) ++count;
+        else if (ch != ' ') return false;
+    }
+    return count >= 3;
+}
+
+std::vector<std::string> split_lines(std::string_view text) {
+    std::vector<std::string> lines;
+    std::size_t start = 0;
+    while (start <= text.size()) {
+        const auto end = text.find('\n', start);
+        std::string line(text.substr(start, end == std::string_view::npos ? std::string_view::npos : end - start));
+        if (!line.empty() && line.back() == '\r') line.pop_back();
+        lines.push_back(std::move(line));
+        if (end == std::string_view::npos) break;
+        start = end + 1;
+    }
+    return lines;
+}
+
+std::vector<Block> parse_blocks(std::string_view markdown) {
+    std::vector<Block> blocks;
+    const auto lines = split_lines(markdown);
+    for (std::size_t i = 0; i < lines.size(); ++i) {
+        const std::string& line = lines[i];
+        std::string lang;
+        if (fence_open(line, &lang)) {
+            Block block{BlockKind::Code};
+            block.lang = lang;
+            std::string content;
+            std::size_t j = i + 1;
+            for (; j < lines.size() && !fence_open(lines[j], nullptr); ++j) {
+                if (!content.empty() || j > i + 1) content += '\n';
+                content += lines[j];
+            }
+            block.text = content;
+            blocks.push_back(std::move(block));
+            i = j;  // 跳过闭合围栏;未闭合时吃到文末
+            continue;
+        }
+        const auto text = trim(line);
+        if (text.empty()) {
+            blocks.push_back(Block{BlockKind::Blank});
+            continue;
+        }
+        if (is_rule(line)) {
+            blocks.push_back(Block{BlockKind::Rule});
+            continue;
+        }
+        std::size_t hashes = 0;
+        while (hashes < text.size() && hashes < 7 && text[hashes] == '#') ++hashes;
+        if (hashes >= 1 && hashes <= 6 && hashes < text.size() && text[hashes] == ' ') {
+            Block block{BlockKind::Heading};
+            block.text = trim(std::string_view(text).substr(hashes + 1));
+            blocks.push_back(std::move(block));
+            continue;
+        }
+        if (text[0] == '>') {
+            Block block{BlockKind::Quote};
+            for (; i < lines.size(); ++i) {
+                const auto quoted = trim(lines[i]);
+                if (quoted.empty() || quoted[0] != '>') break;
+                std::string body = quoted.substr(1);
+                if (!body.empty() && body[0] == ' ') body.erase(0, 1);
+                block.lines.push_back(body);
+            }
+            --i;
+            blocks.push_back(std::move(block));
+            continue;
+        }
+        if (text[0] == '|') {
+            Block block{BlockKind::Table};
+            for (; i < lines.size(); ++i) {
+                const auto row = trim(lines[i]);
+                if (row.empty() || row[0] != '|') break;
+                block.lines.push_back(row);
+            }
+            --i;
+            blocks.push_back(std::move(block));
+            continue;
+        }
+        const auto indent = leading_spaces(line);
+        if ((text[0] == '-' || text[0] == '*' || text[0] == '+') && text.size() > 1 && text[1] == ' ') {
+            Block block{BlockKind::Bullet};
+            block.marker = std::string((indent / 2) * 2, ' ');
+            block.text = trim(std::string_view(text).substr(2));
+            blocks.push_back(std::move(block));
+            continue;
+        }
+        std::size_t digits = 0;
+        while (digits < text.size() && digits < 9 && std::isdigit(static_cast<unsigned char>(text[digits]))) ++digits;
+        if (digits > 0 && digits + 1 < text.size() && (text[digits] == '.' || text[digits] == ')') &&
+            text[digits + 1] == ' ') {
+            Block block{BlockKind::Ordered};
+            block.marker = std::string((indent / 2) * 2, ' ') + text.substr(0, digits) + ".";
+            block.text = trim(std::string_view(text).substr(digits + 2));
+            blocks.push_back(std::move(block));
+            continue;
+        }
+        Block block{BlockKind::Text};
+        block.text = std::string(line);
+        blocks.push_back(std::move(block));
+    }
+    return blocks;
+}
+
+bool safe_link(std::string_view url) {
+    for (const char* prefix : {"http://", "https://", "mailto:", "tg://"}) {
+        if (url.rfind(prefix, 0) == 0) return url.find_first_of(" \n\r\t") == std::string_view::npos;
+    }
+    return false;
+}
+
+// 行内渲染。html=false 时输出去标记的纯文本。depth 防止病态嵌套导致深递归。
+std::string render_inline(std::string_view s, bool html, int depth);
+
+// 在 s[from..] 中找与开头标记相同的闭合标记;要求内容非空且两端不是空格。
+std::size_t find_closing(std::string_view s, std::size_t from, std::string_view marker) {
+    std::size_t pos = from;
+    while (true) {
+        pos = s.find(marker, pos);
+        if (pos == std::string_view::npos) return pos;
+        if (pos > from && s[pos - 1] != ' ' && s[pos - 1] != '\\') return pos;
+        pos += 1;
+    }
+}
+
+std::string render_inline(std::string_view s, bool html, int depth) {
+    std::string out;
+    std::size_t i = 0;
+    auto emit_text = [&](char c) {
+        if (!html) {
+            out.push_back(c);
+            return;
+        }
+        if (c == '&') out += "&amp;";
+        else if (c == '<') out += "&lt;";
+        else if (c == '>') out += "&gt;";
+        else out.push_back(c);
+    };
+    while (i < s.size()) {
+        const char c = s[i];
+        // 反斜杠转义:\* \_ \` 等按字面输出
+        if (c == '\\' && i + 1 < s.size() && std::string_view("*_`~[]()#>|\\").find(s[i + 1]) != std::string_view::npos) {
+            emit_text(s[i + 1]);
+            i += 2;
+            continue;
+        }
+        if (c == '`') {
+            std::size_t ticks = 0;
+            while (i + ticks < s.size() && s[i + ticks] == '`') ++ticks;
+            const std::string marker(ticks, '`');
+            const auto close = s.find(marker, i + ticks);
+            if (close != std::string_view::npos) {
+                std::string code(s.substr(i + ticks, close - i - ticks));
+                if (code.size() >= 2 && code.front() == ' ' && code.back() == ' ') code = code.substr(1, code.size() - 2);
+                if (html) out += "<code>" + html_escape(code) + "</code>";
+                else out += code;
+                i = close + ticks;
+                continue;
+            }
+            for (std::size_t k = 0; k < ticks; ++k) emit_text('`');
+            i += ticks;
+            continue;
+        }
+        if (depth < 8 && c == '[') {
+            const auto close_text = s.find(']', i + 1);
+            if (close_text != std::string_view::npos && close_text + 1 < s.size() && s[close_text + 1] == '(') {
+                const auto close_url = s.find(')', close_text + 2);
+                if (close_url != std::string_view::npos) {
+                    const auto label = s.substr(i + 1, close_text - i - 1);
+                    const auto url = s.substr(close_text + 2, close_url - close_text - 2);
+                    if (!label.empty() && safe_link(url)) {
+                        if (html) {
+                            out += "<a href=\"" + html_escape(url, true) + "\">" +
+                                   render_inline(label, html, depth + 1) + "</a>";
+                        } else {
+                            const auto plain = render_inline(label, html, depth + 1);
+                            out += plain == url ? plain : plain + " (" + std::string(url) + ")";
+                        }
+                        i = close_url + 1;
+                        continue;
+                    }
+                }
+            }
+        }
+        if (depth < 8) {
+            struct Style { std::string_view marker; const char* tag; bool word_bound; };
+            static constexpr Style styles[] = {
+                {"**", "b", false}, {"__", "b", true}, {"~~", "s", false},
+                {"*", "i", false}, {"_", "i", true},
+            };
+            bool matched = false;
+            for (const auto& style : styles) {
+                if (s.substr(i, style.marker.size()) != style.marker) continue;
+                const auto start = i + style.marker.size();
+                if (start >= s.size() || s[start] == ' ') continue;
+                if (style.word_bound && i > 0 && is_alnum(s[i - 1])) continue;
+                // 单字符标记不能与双字符标记混淆(例如 ** 的第一个 *)
+                if (style.marker.size() == 1 && start < s.size() && s[start] == style.marker[0]) continue;
+                const auto close = find_closing(s, start, style.marker);
+                if (close == std::string_view::npos) continue;
+                const auto after = close + style.marker.size();
+                if (style.word_bound && after < s.size() && is_alnum(s[after])) continue;
+                const auto inner = render_inline(s.substr(start, close - start), html, depth + 1);
+                if (html) out += std::string("<") + style.tag + ">" + inner + "</" + style.tag + ">";
+                else out += inner;
+                i = after;
+                matched = true;
+                break;
+            }
+            if (matched) continue;
+        }
+        emit_text(c);
+        ++i;
+    }
+    return out;
+}
+
+std::string render(std::string_view markdown, bool html) {
+    std::string out;
+    bool first = true;
+    auto line = [&](const std::string& text) {
+        if (!first) out += '\n';
+        out += text;
+        first = false;
+    };
+    for (const auto& block : parse_blocks(markdown)) {
+        switch (block.kind) {
+            case BlockKind::Blank: line(""); break;
+            case BlockKind::Rule: line("——————"); break;
+            case BlockKind::Text: line(render_inline(block.text, html, 0)); break;
+            case BlockKind::Heading: {
+                const auto inner = render_inline(block.text, html, 0);
+                line(html ? "<b>" + inner + "</b>" : inner);
+                break;
+            }
+            case BlockKind::Bullet:
+                line(block.marker + "• " + render_inline(block.text, html, 0));
+                break;
+            case BlockKind::Ordered:
+                line(block.marker + " " + render_inline(block.text, html, 0));
+                break;
+            case BlockKind::Code:
+                if (html) {
+                    const std::string open = block.lang.empty()
+                        ? "<pre><code>"
+                        : "<pre><code class=\"language-" + html_escape(block.lang, true) + "\">";
+                    line(open + html_escape(block.text) + "</code></pre>");
+                } else {
+                    line(block.text);
+                }
+                break;
+            case BlockKind::Quote: {
+                std::string body;
+                for (std::size_t k = 0; k < block.lines.size(); ++k) {
+                    if (k) body += '\n';
+                    body += render_inline(block.lines[k], html, 0);
+                }
+                line(html ? "<blockquote>" + body + "</blockquote>" : body);
+                break;
+            }
+            case BlockKind::Table: {
+                std::string body;
+                for (std::size_t k = 0; k < block.lines.size(); ++k) {
+                    if (k) body += '\n';
+                    body += block.lines[k];
+                }
+                line(html ? "<pre>" + html_escape(body) + "</pre>" : body);
+                break;
+            }
+        }
+    }
+    return out;
+}
+
+} // namespace
+
+std::string html_escape(std::string_view text, bool attribute) {
+    std::string out;
+    out.reserve(text.size());
+    for (const char c : text) {
+        if (c == '&') out += "&amp;";
+        else if (c == '<') out += "&lt;";
+        else if (c == '>') out += "&gt;";
+        else if (attribute && c == '"') out += "&quot;";
+        else out.push_back(c);
+    }
+    return out;
+}
+
+std::string markdown_to_plain(std::string_view markdown) { return render(markdown, false); }
+
+std::string markdown_to_telegram_html(std::string_view markdown) { return render(markdown, true); }
+
+} // namespace acecode::im
diff --git a/src/adapters/im/markdown.hpp b/src/adapters/im/markdown.hpp
new file mode 100644
index 000000000..fa8ffcbe6
--- /dev/null
+++ b/src/adapters/im/markdown.hpp
@@ -0,0 +1,20 @@
+#pragma once
+
+// 助手回复(Markdown)在 IM 上的两种呈现:
+//   - markdown_to_plain:去掉标记的纯文本,用于 QQ Markdown 发送被拒时回退;
+//   - markdown_to_telegram_html:Telegram 支持的 HTML 子集(b/i/s/code/pre/a/blockquote),
+//     其余文本一律转义 & < >。标签只按配对结构输出,保证不会出现未闭合标签;
+//     无法识别的标记原样保留为文字。
+
+#include <string>
+#include <string_view>
+
+namespace acecode::im {
+
+std::string markdown_to_plain(std::string_view markdown);
+std::string markdown_to_telegram_html(std::string_view markdown);
+
+// HTML 文本转义(& < >);attribute=true 时额外转义双引号。
+std::string html_escape(std::string_view text, bool attribute = false);
+
+} // namespace acecode::im
diff --git a/src/adapters/im/qqbot/qq_api.cpp b/src/adapters/im/qqbot/qq_api.cpp
new file mode 100644
index 000000000..9fb93401c
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_api.cpp
@@ -0,0 +1,217 @@
+#include "qq_api.hpp"
+
+#include "im/http.hpp"
+#include "im/redact.hpp"
+
+#include <algorithm>
+#include <vector>
+
+namespace acecode::im::qqbot {
+namespace {
+
+std::string trim_slash(std::string base) {
+    while (!base.empty() && base.back() == '/') base.pop_back();
+    return base;
+}
+
+std::string path_segment(const std::string& value) {
+    static constexpr char kHex[] = "0123456789ABCDEF";
+    std::string out;
+    for (const char c : value) {
+        const auto u = static_cast<unsigned char>(c);
+        if ((u >= 'A' && u <= 'Z') || (u >= 'a' && u <= 'z') || (u >= '0' && u <= '9') ||
+            u == '-' || u == '_' || u == '.' || u == '~') {
+            out.push_back(c);
+        } else {
+            out.push_back('%');
+            out.push_back(kHex[u >> 4]);
+            out.push_back(kHex[u & 0x0F]);
+        }
+    }
+    return out;
+}
+
+std::string entity_base(const std::string& scope, const std::string& target) {
+    return (scope == "group" ? "/v2/groups/" : "/v2/users/") + path_segment(target);
+}
+
+long long expires_seconds(const nlohmann::json& value) {
+    if (value.is_number_integer()) return value.get<long long>();
+    if (value.is_string()) {
+        try {
+            return std::stoll(value.get<std::string>());
+        } catch (...) {
+        }
+    }
+    return 7200;
+}
+
+} // namespace
+
+Api::Api(ApiOptions options) : options_(std::move(options)) {}
+
+std::string Api::fetch_token_locked(std::string* error) {
+    HttpRequest request;
+    request.method = "POST";
+    request.url = options_.token_url;
+    request.headers = {{"Content-Type", "application/json"}};
+    request.body = nlohmann::json{{"appId", options_.app_id}, {"clientSecret", options_.app_secret}}.dump();
+    request.timeout = std::chrono::seconds(15);
+    request.use_proxy = options_.use_proxy;
+    const auto response = http_send(request);
+    const std::vector<std::string> secrets{options_.app_secret};
+    auth_failed_ = false;
+    if (response.status == 0) {
+        if (error) *error = redact_secrets(response.error.empty() ? "无法连接 QQ 开放平台" : response.error, secrets);
+        return {};
+    }
+    // 失败时平台仍可能返回 HTTP 200,以响应里有没有 access_token 为准。
+    try {
+        const auto json = nlohmann::json::parse(response.body);
+        if (json.is_object() && json.contains("access_token") && json["access_token"].is_string() &&
+            !json["access_token"].get<std::string>().empty()) {
+            token_ = json["access_token"].get<std::string>();
+            const auto seconds = expires_seconds(json.value("expires_in", nlohmann::json(7200)));
+            const auto margin = std::min<long long>(300, std::max<long long>(seconds / 2, 1));
+            refresh_at_ = std::chrono::steady_clock::now() + std::chrono::seconds(std::max<long long>(seconds - margin, 1));
+            return token_;
+        }
+        const auto api_error = parse_api_error(response.status, response.body);
+        auth_failed_ = response.status < 500;
+        if (error) *error = redact_secrets("凭据无效:" + api_error.message, secrets);
+    } catch (...) {
+        if (error) *error = "QQ 开放平台返回了无效的令牌响应";
+    }
+    return {};
+}
+
+std::string Api::access_token(std::string* error) {
+    std::lock_guard<std::mutex> lock(mu_);
+    if (!token_.empty() && std::chrono::steady_clock::now() < refresh_at_) return token_;
+    return fetch_token_locked(error);
+}
+
+bool Api::last_token_auth_failed() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return auth_failed_;
+}
+
+void Api::invalidate_token() {
+    std::lock_guard<std::mutex> lock(mu_);
+    token_.clear();
+    refresh_at_ = {};
+}
+
+bool Api::verify(std::string* error) {
+    std::lock_guard<std::mutex> lock(mu_);
+    token_.clear();
+    return !fetch_token_locked(error).empty();
+}
+
+std::string Api::gateway_url(std::string* error) {
+    for (int attempt = 0; attempt < 2; ++attempt) {
+        const auto token = access_token(error);
+        if (token.empty()) return {};
+        HttpRequest request;
+        request.url = trim_slash(options_.api_base) + "/gateway";
+        request.headers = {{"Authorization", "QQBot " + token}};
+        request.timeout = std::chrono::seconds(15);
+        request.use_proxy = options_.use_proxy;
+        const auto response = http_send(request);
+        if (response.status == 401 && attempt == 0) {
+            invalidate_token();
+            continue;
+        }
+        if (response.status != 200) {
+            if (error) *error = response.status == 0 ? response.error
+                                                     : "获取网关地址失败:" + parse_api_error(response.status, response.body).message;
+            return {};
+        }
+        try {
+            const auto json = nlohmann::json::parse(response.body);
+            const auto url = json.value("url", std::string{});
+            if (!url.empty()) return url;
+        } catch (...) {
+        }
+        if (error) *error = "QQ 网关地址无效";
+        return {};
+    }
+    if (error) *error = "QQ 鉴权失败";
+    return {};
+}
+
+ApiResult Api::post(const std::string& path, const nlohmann::json& body) {
+    ApiResult result;
+    for (int attempt = 0; attempt < 2; ++attempt) {
+        std::string error;
+        const auto token = access_token(&error);
+        if (token.empty()) {
+            result.error.message = error;
+            return result;
+        }
+        HttpRequest request;
+        request.method = "POST";
+        request.url = trim_slash(options_.api_base) + path;
+        request.headers = {{"Content-Type", "application/json"}, {"Authorization", "QQBot " + token}};
+        request.body = body.dump();
+        request.timeout = std::chrono::seconds(60);
+        request.use_proxy = options_.use_proxy;
+        const auto response = http_send(request);
+        if (response.status == 401 && attempt == 0) {
+            invalidate_token();
+            continue;
+        }
+        if (response.status >= 200 && response.status < 300) {
+            result.ok = true;
+            try {
+                result.response = nlohmann::json::parse(response.body);
+            } catch (...) {
+                result.response = nlohmann::json::object();
+            }
+            return result;
+        }
+        result.error = response.status == 0 ? ApiError{0, 0, response.error}
+                                            : parse_api_error(response.status, response.body);
+        result.error.message = redact_secrets(result.error.message, {options_.app_secret});
+        return result;
+    }
+    return result;
+}
+
+ApiResult Api::send_message(const std::string& scope, const std::string& target, const nlohmann::json& body) {
+    return post(entity_base(scope, target) + "/messages", body);
+}
+
+ApiResult Api::upload_file(const std::string& scope, const std::string& target, int file_type,
+                           const std::string& file_base64, const std::string& file_name) {
+    nlohmann::json body{{"file_type", file_type}, {"srv_send_msg", false}, {"file_data", file_base64}};
+    if (file_type == kFileTypeFile && !file_name.empty()) body["file_name"] = file_name;
+    return post(entity_base(scope, target) + "/files", body);
+}
+
+bool Api::download(const std::string& url, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                   std::string* error) {
+    std::string token_error;
+    const auto token = access_token(&token_error);
+    HttpRequest request;
+    request.url = normalize_attachment_url(url);
+    if (!token.empty()) request.headers = {{"Authorization", "QQBot " + token}};
+    request.timeout = std::chrono::seconds(60);
+    request.use_proxy = options_.use_proxy;
+    request.download_to = dest;
+    request.max_download_bytes = max_bytes;
+    const auto response = http_send(request);
+    if (response.too_large) {
+        if (error) *error = "附件超过大小限制";
+        return false;
+    }
+    if (response.status < 200 || response.status >= 300) {
+        std::error_code ec;
+        std::filesystem::remove(dest, ec);
+        if (error) *error = response.status == 0 ? response.error : "下载附件失败:HTTP " + std::to_string(response.status);
+        return false;
+    }
+    return true;
+}
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/qqbot/qq_api.hpp b/src/adapters/im/qqbot/qq_api.hpp
new file mode 100644
index 000000000..e0cc171f1
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_api.hpp
@@ -0,0 +1,65 @@
+#pragma once
+
+// QQ 开放平台 OpenAPI 客户端:访问令牌、网关地址、发消息、富媒体上传、附件下载。
+// 线程安全:令牌刷新串行化,发送可并发调用。
+
+#include "im/qqbot/qq_protocol.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <filesystem>
+#include <mutex>
+#include <string>
+
+namespace acecode::im::qqbot {
+
+struct ApiOptions {
+    std::string app_id;
+    std::string app_secret;
+    std::string api_base = kApiBase;
+    std::string token_url = kTokenUrl;
+    bool use_proxy = true;
+};
+
+struct ApiResult {
+    bool ok = false;
+    ApiError error;
+    nlohmann::json response = nlohmann::json::object();
+};
+
+class Api {
+public:
+    explicit Api(ApiOptions options);
+
+    // 返回有效令牌,到期前 5 分钟自动刷新。失败返回空串,error 为不含密钥的原因。
+    std::string access_token(std::string* error);
+    void invalidate_token();
+    // 最近一次换令牌失败是不是因为凭据被拒(而不是网络问题)。凭据被拒时不应继续重试。
+    bool last_token_auth_failed() const;
+    // 强制换取一次令牌,用于保存凭据前的校验。
+    bool verify(std::string* error);
+    // GET /gateway,返回 wss 地址。
+    std::string gateway_url(std::string* error);
+    // scope 为 "c2c" 或 "group";target 为对方 openid 或群 openid。
+    ApiResult send_message(const std::string& scope, const std::string& target, const nlohmann::json& body);
+    ApiResult upload_file(const std::string& scope, const std::string& target, int file_type,
+                          const std::string& file_base64, const std::string& file_name);
+    // 带鉴权头下载附件;超过 max_bytes 失败并删除半截文件。
+    bool download(const std::string& url, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                  std::string* error);
+    const ApiOptions& options() const { return options_; }
+
+private:
+    ApiResult post(const std::string& path, const nlohmann::json& body);
+    std::string fetch_token_locked(std::string* error);
+
+    ApiOptions options_;
+    mutable std::mutex mu_;
+    std::string token_;
+    std::chrono::steady_clock::time_point refresh_at_{};
+    bool auth_failed_ = false;
+};
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/qqbot/qq_bind.cpp b/src/adapters/im/qqbot/qq_bind.cpp
new file mode 100644
index 000000000..ee22f94f2
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_bind.cpp
@@ -0,0 +1,190 @@
+#include "qq_bind.hpp"
+
+#include "im/http.hpp"
+#include "platform/crypto/aes_gcm.hpp"
+#include "platform/crypto/secure_random.hpp"
+#include "utils/base64.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <thread>
+
+namespace acecode::im::qqbot {
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+std::string url_encode(const std::string& value) {
+    static constexpr char kHex[] = "0123456789ABCDEF";
+    std::string out;
+    for (const char c : value) {
+        const auto u = static_cast<unsigned char>(c);
+        if ((u >= 'A' && u <= 'Z') || (u >= 'a' && u <= 'z') || (u >= '0' && u <= '9') ||
+            u == '-' || u == '_' || u == '.' || u == '~') {
+            out.push_back(c);
+        } else {
+            out.push_back('%');
+            out.push_back(kHex[u >> 4]);
+            out.push_back(kHex[u & 0x0F]);
+        }
+    }
+    return out;
+}
+
+std::string trim_slash(std::string base) {
+    while (!base.empty() && base.back() == '/') base.pop_back();
+    return base;
+}
+
+// 等待 duration;期间每 100ms 检查一次取消。返回 false 表示被取消。
+bool wait_or_cancel(std::chrono::milliseconds duration, const std::atomic<bool>& cancelled) {
+    const auto until = Clock::now() + duration;
+    while (Clock::now() < until) {
+        if (cancelled) return false;
+        std::this_thread::sleep_for(std::min<std::chrono::milliseconds>(
+            std::chrono::milliseconds(100),
+            std::chrono::duration_cast<std::chrono::milliseconds>(until - Clock::now())));
+    }
+    return !cancelled;
+}
+
+struct PortalReply {
+    bool ok = false;
+    nlohmann::json data;
+    std::string error;
+};
+
+PortalReply post_portal(const BindOptions& options, const std::string& path, const nlohmann::json& body) {
+    HttpRequest request;
+    request.method = "POST";
+    request.url = trim_slash(options.portal_base) + path;
+    request.headers = {{"Content-Type", "application/json"}, {"Accept", "application/json"}};
+    request.body = body.dump();
+    request.timeout = options.request_timeout;
+    request.use_proxy = options.use_proxy;
+    const auto response = http_send(request);
+    PortalReply reply;
+    if (response.status == 0) {
+        reply.error = response.error.empty() ? "无法连接 QQ 开放平台" : response.error;
+        return reply;
+    }
+    if (response.status != 200) {
+        reply.error = "QQ 开放平台返回 HTTP " + std::to_string(response.status);
+        return reply;
+    }
+    try {
+        const auto json = nlohmann::json::parse(response.body);
+        if (!json.is_object() || json.value("retcode", -1) != 0) {
+            reply.error = json.is_object() ? json.value("msg", std::string("QQ 开放平台拒绝了请求"))
+                                           : std::string("QQ 开放平台返回了无效数据");
+            return reply;
+        }
+        reply.ok = true;
+        reply.data = json.contains("data") && json["data"].is_object() ? json["data"] : nlohmann::json::object();
+    } catch (...) {
+        reply.error = "QQ 开放平台返回了无效数据";
+    }
+    return reply;
+}
+
+std::string id_field(const nlohmann::json& data, const char* key) {
+    if (!data.contains(key)) return {};
+    const auto& field = data.at(key);
+    if (field.is_string()) return field.get<std::string>();
+    if (field.is_number_integer()) return std::to_string(field.get<std::int64_t>());
+    return {};
+}
+
+} // namespace
+
+std::string build_connect_url(const std::string& base, const std::string& task_id,
+                              const std::string& source) {
+    return trim_slash(base) + "/qqbot/openclaw/connect.html?task_id=" + url_encode(task_id) +
+           "&source=" + url_encode(source) + "&_wv=2";
+}
+
+bool decrypt_bind_secret(const std::string& encrypted_base64, const std::string& key_base64,
+                         std::string& secret, std::string* error) {
+    const auto key = base64_decode(key_base64);
+    const auto raw = base64_decode(encrypted_base64);
+    if (!key || !raw || raw->size() < 12 + 16) {
+        if (error) *error = "扫码返回的密钥格式无效";
+        return false;
+    }
+    const std::string iv = raw->substr(0, 12);
+    const std::string tag = raw->substr(raw->size() - 16);
+    const std::string ciphertext = raw->substr(12, raw->size() - 12 - 16);
+    std::string detail;
+    if (!platform::aes_256_gcm_decrypt(*key, iv, ciphertext, tag, secret, &detail)) {
+        if (error) *error = "扫码返回的密钥无法解密";
+        return false;
+    }
+    return true;
+}
+
+BindUpdate run_bind(const BindOptions& options, const std::atomic<bool>& cancelled,
+                    const BindProgress& progress) {
+    const auto deadline = Clock::now() + options.total_timeout;
+    BindUpdate update;
+    int refreshes = 0;
+    while (true) {
+        if (cancelled) return BindUpdate{BindPhase::Cancelled};
+        if (Clock::now() >= deadline) return BindUpdate{BindPhase::TimedOut};
+
+        const auto key_bytes = options.key_provider ? options.key_provider() : platform::secure_random_bytes(32);
+        if (key_bytes.size() != 32) {
+            update.phase = BindPhase::Failed;
+            update.error = "无法生成随机密钥";
+            return update;
+        }
+        const auto key = base64_encode(key_bytes);
+        const auto created = post_portal(options, "/lite/create_bind_task", {{"key", key}});
+        if (!created.ok) {
+            update.phase = BindPhase::Failed;
+            update.error = "申请绑定任务失败:" + created.error;
+            return update;
+        }
+        const auto task_id = id_field(created.data, "task_id");
+        if (task_id.empty()) {
+            update.phase = BindPhase::Failed;
+            update.error = "申请绑定任务失败:缺少 task_id";
+            return update;
+        }
+
+        BindUpdate waiting;
+        waiting.phase = BindPhase::WaitingScan;
+        waiting.qr_url = build_connect_url(options.connect_base, task_id, options.source);
+        waiting.refreshes = refreshes;
+        if (progress) progress(waiting);
+
+        bool expired = false;
+        while (!expired) {
+            if (!wait_or_cancel(options.poll_interval, cancelled)) return BindUpdate{BindPhase::Cancelled};
+            if (Clock::now() >= deadline) return BindUpdate{BindPhase::TimedOut};
+            // 轮询失败(网络抖动、平台临时错误)继续等,与官方 connector 的行为一致。
+            const auto polled = post_portal(options, "/lite/poll_bind_result", {{"task_id", task_id}});
+            if (!polled.ok) continue;
+            const int status = polled.data.value("status", 0);
+            if (status == 2) {
+                BindUpdate done;
+                done.app_id = id_field(polled.data, "bot_appid");
+                const auto encrypted = polled.data.value("bot_encrypt_secret", std::string{});
+                std::string error;
+                if (done.app_id.empty() || !decrypt_bind_secret(encrypted, key, done.app_secret, &error)) {
+                    done.phase = BindPhase::Failed;
+                    done.error = error.empty() ? "扫码结果缺少机器人信息" : error;
+                    done.app_secret.clear();
+                    return done;
+                }
+                done.phase = BindPhase::Completed;
+                done.user_openid = id_field(polled.data, "user_openid");
+                done.refreshes = refreshes;
+                return done;
+            }
+            if (status == 3) expired = true;
+        }
+        ++refreshes;
+    }
+}
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/qqbot/qq_bind.hpp b/src/adapters/im/qqbot/qq_bind.hpp
new file mode 100644
index 000000000..4a1c24207
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_bind.hpp
@@ -0,0 +1,60 @@
+#pragma once
+
+// QQ 机器人扫码配置(add-desktop-im-channels design D9)。
+//
+// 协议取自 WorkBuddy 5.6.2 内置的腾讯官方 @tencent-connect/qqbot-connector 1.1.0,
+// 并与 Hermes qqbot/onboard.py 交叉印证(该包无开源许可,只参照协议,未复制代码):
+//   1. POST {portal}/lite/create_bind_task {"key": base64(32 字节随机密钥)} → task_id
+//   2. 二维码内容:{portal}/qqbot/openclaw/connect.html?task_id=..&source=acecode&_wv=2
+//   3. 每 2 秒 POST {portal}/lite/poll_bind_result {"task_id"}:status 0 无 / 1 进行中 /
+//      2 完成(附 bot_appid、bot_encrypt_secret、可能有 user_openid)/ 3 过期(换新任务)
+//   4. bot_encrypt_secret = base64(IV 12 字节 | 密文 | 认证标签 16 字节),AES-256-GCM 解密
+// 二维码内容与解密后的密钥绝不写日志。
+
+#include "im/qqbot/qq_protocol.hpp"
+
+#include <atomic>
+#include <chrono>
+#include <functional>
+#include <string>
+
+namespace acecode::im::qqbot {
+
+enum class BindPhase { WaitingScan, Completed, Failed, Cancelled, TimedOut };
+
+struct BindUpdate {
+    BindPhase phase = BindPhase::WaitingScan;
+    std::string qr_url;       // WaitingScan:当前二维码内容
+    std::string error;        // Failed:原因,不含任何密钥
+    std::string app_id;       // Completed
+    std::string app_secret;   // Completed:只交给保存逻辑,不得展示或记录
+    std::string user_openid;  // Completed:扫码人在单聊里的 openid,接口没给时为空
+    int refreshes = 0;        // 二维码因过期刷新的次数
+};
+
+struct BindOptions {
+    std::string portal_base = kPortalBase;   // 申请与轮询接口所在的门户
+    std::string connect_base = kPortalBase;  // 二维码指向的门户(始终是正式门户)
+    std::string source = kBindSource;
+    bool use_proxy = true;
+    std::chrono::milliseconds poll_interval{std::chrono::seconds(2)};
+    std::chrono::milliseconds total_timeout{std::chrono::minutes(10)};
+    std::chrono::milliseconds request_timeout{std::chrono::seconds(10)};
+    // 测试注入点:返回 32 字节密钥;为空时使用密码学安全随机数。
+    std::function<std::string()> key_provider;
+};
+
+using BindProgress = std::function<void(const BindUpdate&)>;
+
+// 同步执行完整扫码流程,由调用方放到后台线程。每次显示或刷新二维码都会回调 progress;
+// 返回最终结果(Completed / Failed / Cancelled / TimedOut)。cancelled 置位后约 100ms 内返回。
+BindUpdate run_bind(const BindOptions& options, const std::atomic<bool>& cancelled,
+                    const BindProgress& progress);
+
+std::string build_connect_url(const std::string& base, const std::string& task_id,
+                              const std::string& source);
+
+bool decrypt_bind_secret(const std::string& encrypted_base64, const std::string& key_base64,
+                         std::string& secret, std::string* error);
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/qqbot/qq_gateway.cpp b/src/adapters/im/qqbot/qq_gateway.cpp
new file mode 100644
index 000000000..a516886a4
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_gateway.cpp
@@ -0,0 +1,124 @@
+#include "qq_gateway.hpp"
+
+#include <algorithm>
+
+namespace acecode::im::qqbot {
+
+void GatewaySession::on_connected(std::string token, Clock::time_point now) {
+    token_ = std::move(token);
+    hello_ = false;
+    awaiting_ack_ = false;
+    ready_ = false;
+    next_beat_ = now + interval_;
+}
+
+std::string GatewaySession::heartbeat_frame() const {
+    nlohmann::json frame{{"op", 1}};
+    frame["d"] = seq_ ? nlohmann::json(*seq_) : nlohmann::json(nullptr);
+    return frame.dump();
+}
+
+GatewaySession::Output GatewaySession::on_frame(const std::string& text, Clock::time_point now) {
+    Output out;
+    nlohmann::json payload;
+    try {
+        payload = nlohmann::json::parse(text);
+    } catch (...) {
+        return out;  // 无效帧直接忽略,连接本身由心跳兜底
+    }
+    if (!payload.is_object() || !payload.contains("op") || !payload["op"].is_number_integer()) return out;
+    const int op = payload["op"].get<int>();
+    const auto d = payload.contains("d") ? payload["d"] : nlohmann::json(nullptr);
+
+    switch (op) {
+        case 10: {  // Hello:按服务端间隔的 80% 发心跳,随后登录或恢复
+            hello_ = true;
+            long long ms = 30000;
+            if (d.is_object() && d.contains("heartbeat_interval") && d["heartbeat_interval"].is_number())
+                ms = d["heartbeat_interval"].get<long long>();
+            interval_ = std::chrono::milliseconds(std::max<long long>(1000, ms * 8 / 10));
+            next_beat_ = now + interval_;
+            nlohmann::json frame;
+            if (can_resume()) {
+                frame = {{"op", 6},
+                         {"d", {{"token", "QQBot " + token_}, {"session_id", session_id_}, {"seq", *seq_}}}};
+            } else {
+                frame = {{"op", 2},
+                         {"d",
+                          {{"token", "QQBot " + token_},
+                           {"intents", kIntents},
+                           {"shard", nlohmann::json::array({0, 1})},
+                           {"properties", {{"$os", "acecode"}, {"$browser", "acecode"}, {"$device", "acecode"}}}}}};
+            }
+            out.frames.push_back(frame.dump());
+            break;
+        }
+        case 0: {  // Dispatch
+            if (payload.contains("s") && payload["s"].is_number_integer()) seq_ = payload["s"].get<std::int64_t>();
+            const auto type = payload.value("t", std::string{});
+            if (type == "READY") {
+                if (d.is_object()) {
+                    session_id_ = d.value("session_id", std::string{});
+                    if (d.contains("user") && d["user"].is_object()) {
+                        const auto& user = d["user"];
+                        if (user.contains("id") && user["id"].is_string()) out.bot_id = user["id"].get<std::string>();
+                        out.bot_name = user.value("username", std::string{});
+                    }
+                }
+                ready_ = true;
+                out.ready = true;
+            } else if (type == "RESUMED") {
+                ready_ = true;
+                out.ready = true;
+            } else if (!type.empty()) {
+                out.dispatches.emplace_back(type, d);
+            }
+            break;
+        }
+        case 11:  // Heartbeat ACK
+            awaiting_ack_ = false;
+            break;
+        case 1:  // 服务端要求立即心跳
+            out.frames.push_back(heartbeat_frame());
+            break;
+        case 7:  // 服务端要求重连,会话可以恢复
+            out.reconnect = true;
+            break;
+        case 9:  // 会话失效;d=true 时仍可恢复
+            if (!(d.is_boolean() && d.get<bool>())) clear_session();
+            out.reconnect = true;
+            break;
+        default:
+            break;
+    }
+    return out;
+}
+
+GatewaySession::Tick GatewaySession::on_tick(Clock::time_point now) {
+    Tick tick;
+    if (!hello_ || now < next_beat_) return tick;
+    if (awaiting_ack_) {
+        tick.zombie = true;
+        return tick;
+    }
+    tick.heartbeat = heartbeat_frame();
+    awaiting_ack_ = true;
+    next_beat_ = now + interval_;
+    return tick;
+}
+
+CloseDecision GatewaySession::on_closed(int code) {
+    hello_ = false;
+    ready_ = false;
+    awaiting_ack_ = false;
+    const auto decision = classify_close(code);
+    if (decision.action == CloseAction::Identify) clear_session();
+    return decision;
+}
+
+void GatewaySession::clear_session() {
+    session_id_.clear();
+    seq_.reset();
+}
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/qqbot/qq_gateway.hpp b/src/adapters/im/qqbot/qq_gateway.hpp
new file mode 100644
index 000000000..c3447c5dc
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_gateway.hpp
@@ -0,0 +1,67 @@
+#pragma once
+
+// QQ 网关会话状态机(纯逻辑,不做 IO)。
+// 输入:收到的帧、时间推进、连接关闭码;输出:要发送的帧、派发的事件与连接指令。
+// 协议:Hello(op 10) → Identify(op 2) 或 Resume(op 6) → Dispatch(op 0: READY / RESUMED / 消息);
+// 心跳 op 1 / ACK op 11;服务端要求重连 op 7;会话失效 op 9(d=true 可恢复)。
+
+#include "im/qqbot/qq_protocol.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace acecode::im::qqbot {
+
+class GatewaySession {
+public:
+    using Clock = std::chrono::steady_clock;
+
+    struct Output {
+        std::vector<std::string> frames;  // 要发送的 JSON 文本帧
+        std::vector<std::pair<std::string, nlohmann::json>> dispatches;  // (事件类型, d)
+        bool ready = false;      // 本帧让连接可用(READY / RESUMED)
+        bool reconnect = false;  // 服务端要求重连(op 7 / op 9)
+        std::string bot_id;      // READY 里的机器人 id(可空)
+        std::string bot_name;    // READY 里的机器人名称(可空)
+    };
+
+    struct Tick {
+        std::optional<std::string> heartbeat;  // 到期要发的心跳帧
+        bool zombie = false;  // 上一次心跳一直没等到 ACK:连接已假死,应断开重连
+    };
+
+    // WebSocket 握手成功后调用;token 为不带前缀的访问令牌。
+    void on_connected(std::string token, Clock::time_point now);
+    Output on_frame(const std::string& text, Clock::time_point now);
+    Tick on_tick(Clock::time_point now);
+    // 连接关闭后调用,按关闭码决定下一次是恢复还是重新登录。
+    CloseDecision on_closed(int code);
+    // 平台明确要求重新登录(或凭据变化)时清掉会话。
+    void clear_session();
+
+    bool can_resume() const { return !session_id_.empty() && seq_.has_value(); }
+    const std::string& session_id() const { return session_id_; }
+    std::optional<std::int64_t> last_seq() const { return seq_; }
+    std::chrono::milliseconds heartbeat_interval() const { return interval_; }
+    bool ready() const { return ready_; }
+
+private:
+    std::string heartbeat_frame() const;
+
+    std::string token_;
+    std::string session_id_;
+    std::optional<std::int64_t> seq_;
+    std::chrono::milliseconds interval_{std::chrono::seconds(30)};
+    Clock::time_point next_beat_{};
+    bool hello_ = false;
+    bool awaiting_ack_ = false;
+    bool ready_ = false;
+};
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/qqbot/qq_protocol.cpp b/src/adapters/im/qqbot/qq_protocol.cpp
new file mode 100644
index 000000000..0c9171eec
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_protocol.cpp
@@ -0,0 +1,150 @@
+#include "qq_protocol.hpp"
+
+#include <algorithm>
+#include <cctype>
+
+namespace acecode::im::qqbot {
+namespace {
+
+std::string trim(const std::string& text) {
+    std::size_t b = 0, e = text.size();
+    while (b < e && std::isspace(static_cast<unsigned char>(text[b]))) ++b;
+    while (e > b && std::isspace(static_cast<unsigned char>(text[e - 1]))) --e;
+    return text.substr(b, e - b);
+}
+
+std::string lower(std::string text) {
+    std::transform(text.begin(), text.end(), text.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return text;
+}
+
+bool ends_with(const std::string& text, const std::string& suffix) {
+    return text.size() >= suffix.size() &&
+           text.compare(text.size() - suffix.size(), suffix.size(), suffix) == 0;
+}
+
+std::string string_field(const nlohmann::json& value, const char* key) {
+    if (!value.is_object() || !value.contains(key)) return {};
+    const auto& field = value.at(key);
+    if (field.is_string()) return field.get<std::string>();
+    if (field.is_number_integer()) return std::to_string(field.get<std::int64_t>());
+    return {};
+}
+
+Attachment parse_attachment(const nlohmann::json& raw) {
+    Attachment attachment;
+    const auto content_type = lower(string_field(raw, "content_type"));
+    attachment.name = string_field(raw, "filename");
+    attachment.mime_type = content_type;
+    attachment.remote_ref = normalize_attachment_url(string_field(raw, "url"));
+    if (raw.contains("size") && raw["size"].is_number_unsigned()) attachment.size = raw["size"].get<std::uint64_t>();
+    else if (raw.contains("size") && raw["size"].is_number_integer() && raw["size"].get<std::int64_t>() > 0)
+        attachment.size = static_cast<std::uint64_t>(raw["size"].get<std::int64_t>());
+    const auto name = lower(attachment.name);
+    const bool voice = content_type == "voice" || content_type.rfind("audio/", 0) == 0 ||
+                       ends_with(name, ".amr") || ends_with(name, ".silk") || ends_with(name, ".ogg") ||
+                       ends_with(name, ".wav") || ends_with(name, ".mp3");
+    if (voice) {
+        attachment.kind = AttachmentKind::Voice;
+        attachment.transcript = trim(string_field(raw, "asr_refer_text"));
+    } else if (content_type.rfind("image/", 0) == 0) {
+        attachment.kind = AttachmentKind::Image;
+    } else if (content_type.rfind("video/", 0) == 0) {
+        attachment.kind = AttachmentKind::Video;
+    } else {
+        attachment.kind = AttachmentKind::File;
+    }
+    return attachment;
+}
+
+} // namespace
+
+CloseDecision classify_close(int code) {
+    switch (code) {
+        case 4004: return {CloseAction::RefreshToken, "访问令牌失效,正在刷新"};
+        case 4006: return {CloseAction::Identify, "会话超时,正在重新登录"};
+        case 4007: return {CloseAction::Identify, "消息序号无效,正在重新登录"};
+        case 4008: return {CloseAction::RateLimited, "触发 QQ 网关频控,稍后重连"};
+        case 4009: return {CloseAction::Identify, "会话已失效,正在重新登录"};
+        case 4914: return {CloseAction::Fatal, "机器人已下线或仅限沙箱环境使用"};
+        case 4915: return {CloseAction::Fatal, "机器人已被封禁"};
+        default: break;
+    }
+    if (code >= 4900 && code <= 4913) return {CloseAction::Identify, "QQ 网关会话错误,正在重新登录"};
+    if (code >= 4001 && code <= 4003) return {CloseAction::Identify, "网关拒绝了请求,正在重新登录"};
+    return {CloseAction::Resume, "连接已断开,正在重连"};
+}
+
+std::optional<Inbound> parse_message_event(const std::string& type, const nlohmann::json& d,
+                                           const std::string& app_id, std::int64_t now_ms) {
+    if (!d.is_object()) return std::nullopt;
+    const bool c2c = type == "C2C_MESSAGE_CREATE";
+    const bool group_at = type == "GROUP_AT_MESSAGE_CREATE";
+    const bool group_all = type == "GROUP_MESSAGE_CREATE";
+    if (!c2c && !group_at && !group_all) return std::nullopt;
+
+    Inbound inbound;
+    inbound.message_id = string_field(d, "id");
+    if (inbound.message_id.empty()) return std::nullopt;
+    const auto author = d.contains("author") ? d.at("author") : nlohmann::json::object();
+    inbound.address.platform = "qq";
+    inbound.address.account = app_id;
+    if (c2c) {
+        inbound.address.kind = ChatKind::Private;
+        inbound.address.chat = inbound.address.sender = string_field(author, "user_openid");
+        inbound.mentioned = true;
+    } else {
+        inbound.address.kind = ChatKind::Group;
+        inbound.address.chat = string_field(d, "group_openid");
+        inbound.address.sender = string_field(author, "member_openid");
+        inbound.mentioned = group_at;
+    }
+    if (!inbound.address.valid()) return std::nullopt;
+    inbound.text = trim(string_field(d, "content"));
+    if (d.contains("attachments") && d["attachments"].is_array()) {
+        for (const auto& raw : d["attachments"]) {
+            if (raw.is_object()) inbound.attachments.push_back(parse_attachment(raw));
+        }
+    }
+    if (inbound.text.empty() && inbound.attachments.empty()) return std::nullopt;
+    inbound.reply_context = {{"msg_id", inbound.message_id},
+                             {"scope", c2c ? "c2c" : "group"},
+                             {"received_at_ms", now_ms}};
+    return inbound;
+}
+
+ApiError parse_api_error(long status, const std::string& body) {
+    ApiError error;
+    error.status = status;
+    try {
+        const auto json = nlohmann::json::parse(body);
+        if (json.is_object()) {
+            if (json.contains("code") && json["code"].is_number_integer()) error.code = json["code"].get<long>();
+            else if (json.contains("err_code") && json["err_code"].is_number_integer())
+                error.code = json["err_code"].get<long>();
+            error.message = json.value("message", std::string{});
+        }
+    } catch (...) {
+    }
+    if (error.message.empty()) error.message = "HTTP " + std::to_string(status);
+    return error;
+}
+
+int file_type_for(const std::string& mime_type, const std::string& name) {
+    const auto mime = lower(mime_type);
+    const auto file = lower(name);
+    if (mime.rfind("image/", 0) == 0) return kFileTypeImage;
+    for (const char* ext : {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp"}) {
+        if (ends_with(file, ext)) return kFileTypeImage;
+    }
+    if (mime == "video/mp4" || ends_with(file, ".mp4")) return kFileTypeVideo;
+    return kFileTypeFile;
+}
+
+std::string normalize_attachment_url(const std::string& url) {
+    if (url.rfind("//", 0) == 0) return "https:" + url;
+    return url;
+}
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/qqbot/qq_protocol.hpp b/src/adapters/im/qqbot/qq_protocol.hpp
new file mode 100644
index 000000000..18f933bde
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_protocol.hpp
@@ -0,0 +1,73 @@
+#pragma once
+
+// QQ 官方机器人(开放平台 API v2)协议常量与纯解析逻辑。
+// 参照:QQ 开放平台文档,以及 WorkBuddy 5.6.2 内置 QQ 插件与 Hermes qqbot 适配器
+// (add-desktop-im-channels design D9/D10)。
+
+#include "im/transport.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <cstdint>
+#include <optional>
+#include <string>
+
+namespace acecode::im::qqbot {
+
+// 2026-08 起官方文档统一使用 api.bot.qq.com;旧域名 api.sgroup.qq.com / bots.qq.com
+// (WorkBuddy 5.6.2 仍在用)同样可用,作为备选不默认启用。
+inline constexpr const char* kApiBase = "https://api.bot.qq.com";
+inline constexpr const char* kTokenUrl = "https://api.bot.qq.com/app/getAppAccessToken";
+inline constexpr const char* kPortalBase = "https://q.qq.com";
+inline constexpr const char* kBindSource = "acecode";
+
+// 只订阅单聊与群 @ 消息(GROUP_AND_C2C_EVENT);频道消息不接。
+inline constexpr int kIntents = 1 << 25;
+
+inline constexpr int kMsgTypeText = 0;
+inline constexpr int kMsgTypeMarkdown = 2;
+inline constexpr int kMsgTypeMedia = 7;
+
+inline constexpr int kFileTypeImage = 1;
+inline constexpr int kFileTypeVideo = 2;
+inline constexpr int kFileTypeFile = 4;
+
+// 单条文本上限(按字符);WorkBuddy 用 5000,Hermes 用 4000,取保守值。
+inline constexpr std::size_t kMaxTextChars = 4000;
+
+enum class CloseAction {
+    Resume,        // 普通断线:带 session 恢复
+    Identify,      // 会话已失效:重新登录
+    RefreshToken,  // 令牌失效:刷新令牌后恢复
+    RateLimited,   // 触发网关频控:至少等 60 秒
+    Fatal,         // 机器人被封禁 / 不在线 / 仅限沙箱:停止重连
+};
+
+struct CloseDecision {
+    CloseAction action = CloseAction::Resume;
+    std::string reason;  // 给用户看的中文原因
+};
+
+CloseDecision classify_close(int code);
+
+// 把网关派发事件(op 0)转换为入站消息。只处理单聊与群消息;
+// 其它事件、缺字段、空消息返回 nullopt。now_ms 记入回复上下文,用于被动回复窗口计时。
+std::optional<Inbound> parse_message_event(const std::string& type, const nlohmann::json& d,
+                                           const std::string& app_id, std::int64_t now_ms);
+
+struct ApiError {
+    long status = 0;
+    long code = 0;
+    std::string message;
+};
+
+// 解析 OpenAPI 失败响应({"code":..,"message":..});无法解析时用 HTTP 状态码兜底。
+ApiError parse_api_error(long status, const std::string& body);
+
+// 上传富媒体时的 file_type:图片 1、视频 2,其余一律按普通文件 4 发送。
+int file_type_for(const std::string& mime_type, const std::string& name);
+
+// 附件地址可能以 "//" 开头(省略协议),补成 https。
+std::string normalize_attachment_url(const std::string& url);
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/qqbot/qq_reply_budget.cpp b/src/adapters/im/qqbot/qq_reply_budget.cpp
new file mode 100644
index 000000000..db1cb2b88
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_reply_budget.cpp
@@ -0,0 +1,87 @@
+#include "qq_reply_budget.hpp"
+
+namespace acecode::im::qqbot {
+namespace {
+
+constexpr std::int64_t kPruneAfterMs = 2LL * 60 * 60 * 1000;  // 两小时后两种窗口都早已过期
+constexpr std::size_t kMaxEntries = 4096;
+
+} // namespace
+
+ReplyBudget::ReplyBudget(ReplyLimits limits) : limits_(limits) {}
+
+std::int64_t ReplyBudget::next_seq() {
+    std::lock_guard<std::mutex> lock(mu_);
+    return ++seq_;
+}
+
+void ReplyBudget::prune_locked(std::int64_t now_ms) {
+    if (entries_.size() < kMaxEntries / 2) return;
+    for (auto it = entries_.begin(); it != entries_.end();) {
+        if (now_ms - it->second.received_at_ms > kPruneAfterMs) it = entries_.erase(it);
+        else ++it;
+    }
+    while (entries_.size() >= kMaxEntries) entries_.erase(entries_.begin());
+}
+
+ReplyPlan ReplyBudget::plan(const nlohmann::json& reply_context, std::int64_t now_ms) {
+    std::lock_guard<std::mutex> lock(mu_);
+    ReplyPlan plan;
+    plan.msg_seq = ++seq_;
+    if (!reply_context.is_object()) return plan;
+    const auto msg_id = reply_context.value("msg_id", std::string{});
+    if (msg_id.empty()) return plan;
+    const bool group = reply_context.value("scope", std::string{}) == "group";
+    const auto received = reply_context.value("received_at_ms", now_ms);
+    const auto window = group ? limits_.group_window : limits_.c2c_window;
+    const int max = group ? limits_.group_max : limits_.c2c_max;
+    prune_locked(now_ms);
+    auto& entry = entries_[msg_id];
+    entry.received_at_ms = received;
+    if (entry.exhausted || entry.used >= max || now_ms - received >= window.count()) return plan;
+    ++entry.used;
+    plan.passive = true;
+    plan.msg_id = msg_id;
+    return plan;
+}
+
+void ReplyBudget::exhaust(const std::string& msg_id) {
+    std::lock_guard<std::mutex> lock(mu_);
+    entries_[msg_id].exhausted = true;
+}
+
+std::size_t HeldQueue::push(const std::string& conversation_key, HeldItem item) {
+    std::lock_guard<std::mutex> lock(mu_);
+    auto& queue = items_[conversation_key];
+    queue.push_back(std::move(item));
+    std::size_t dropped = 0;
+    while (queue.size() > kMaxPerConversation) {
+        queue.pop_front();
+        ++dropped;
+    }
+    return dropped;
+}
+
+std::deque<HeldItem> HeldQueue::take(const std::string& conversation_key) {
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto it = items_.find(conversation_key);
+    if (it == items_.end()) return {};
+    auto queue = std::move(it->second);
+    items_.erase(it);
+    return queue;
+}
+
+std::size_t HeldQueue::size(const std::string& conversation_key) const {
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto it = items_.find(conversation_key);
+    return it == items_.end() ? 0 : it->second.size();
+}
+
+std::size_t HeldQueue::total() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    std::size_t sum = 0;
+    for (const auto& item : items_) sum += item.second.size();
+    return sum;
+}
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/qqbot/qq_reply_budget.hpp b/src/adapters/im/qqbot/qq_reply_budget.hpp
new file mode 100644
index 000000000..9b6374fab
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_reply_budget.hpp
@@ -0,0 +1,81 @@
+#pragma once
+
+// QQ 被动回复额度与补发队列(纯逻辑,design D10)。
+//
+// 官方规则:对一条用户消息,私聊 60 分钟内最多回 4 条、群聊 5 分钟内最多回 5 条
+// (被动回复,带原消息 msg_id);超出后只能发主动消息,而主动消息可能被用户或群主关闭。
+// 所有发送共用一个全进程单调递增的 msg_seq —— 平台按 (msg_id, msg_seq) 去重,
+// 同一 msg_id 下重复的 msg_seq 会被判成重复消息(40054005)。
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <deque>
+#include <filesystem>
+#include <map>
+#include <mutex>
+#include <string>
+
+namespace acecode::im::qqbot {
+
+struct ReplyLimits {
+    std::chrono::milliseconds c2c_window{std::chrono::minutes(60)};
+    int c2c_max = 4;
+    std::chrono::milliseconds group_window{std::chrono::minutes(5)};
+    int group_max = 5;
+};
+
+struct ReplyPlan {
+    bool passive = false;   // true:带 msg_id 被动回复;false:主动消息
+    std::string msg_id;
+    std::int64_t msg_seq = 0;
+};
+
+class ReplyBudget {
+public:
+    explicit ReplyBudget(ReplyLimits limits = {});
+    // 为一次发送选择方式。被动回复会占用该消息的一次额度;额度用尽或窗口已过则改为主动。
+    ReplyPlan plan(const nlohmann::json& reply_context, std::int64_t now_ms);
+    // 平台拒绝了某条被动回复(窗口已过等):这条消息不再尝试被动回复。
+    void exhaust(const std::string& msg_id);
+    std::int64_t next_seq();
+
+private:
+    struct Entry {
+        int used = 0;
+        bool exhausted = false;
+        std::int64_t received_at_ms = 0;
+    };
+    void prune_locked(std::int64_t now_ms);
+
+    ReplyLimits limits_;
+    std::mutex mu_;
+    std::map<std::string, Entry> entries_;
+    std::int64_t seq_ = 0;
+};
+
+// 主动消息也被拒时暂存的输出,在对方下一条消息到来时作为被动回复补发。
+struct HeldItem {
+    bool file = false;
+    std::string text;                // 文本(Markdown)
+    std::filesystem::path path;      // 文件
+    std::string name;
+    std::string mime_type;
+};
+
+class HeldQueue {
+public:
+    static constexpr std::size_t kMaxPerConversation = 20;
+    // 超过上限时丢弃最旧的一条,返回被丢弃的条数。
+    std::size_t push(const std::string& conversation_key, HeldItem item);
+    std::deque<HeldItem> take(const std::string& conversation_key);
+    std::size_t size(const std::string& conversation_key) const;
+    std::size_t total() const;
+
+private:
+    mutable std::mutex mu_;
+    std::map<std::string, std::deque<HeldItem>> items_;
+};
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/qqbot/qq_transport.cpp b/src/adapters/im/qqbot/qq_transport.cpp
new file mode 100644
index 000000000..4e6514a8f
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_transport.cpp
@@ -0,0 +1,347 @@
+#include "qq_transport.hpp"
+
+#include "im/http.hpp"
+#include "im/markdown.hpp"
+#include "im/redact.hpp"
+#include "im/text_chunk.hpp"
+#include "utils/base64.hpp"
+#include "utils/logger.hpp"
+
+#include <algorithm>
+#include <cctype>
+#include <fstream>
+#include <iterator>
+
+namespace acecode::im::qqbot {
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+std::int64_t now_ms() {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(Clock::now().time_since_epoch()).count();
+}
+
+std::pair<std::string, std::string> scope_of(const Address& to) {
+    return {to.kind == ChatKind::Group ? "group" : "c2c", to.chat};
+}
+
+bool client_error(const ApiError& error) { return error.status >= 400 && error.status < 500; }
+
+bool markdown_rejected(const ApiError& error) {
+    if (!client_error(error)) return false;
+    std::string message = error.message;
+    std::transform(message.begin(), message.end(), message.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return message.find("markdown") != std::string::npos || message.find("msg_type") != std::string::npos;
+}
+
+constexpr std::size_t kSeenLimit = 1000;
+
+} // namespace
+
+QqTransport::QqTransport(QqTransportOptions options)
+    : options_(std::move(options)), api_(options_.api), budget_(options_.limits) {
+    markdown_ = options_.markdown;
+    status_.account = options_.api.app_id;
+}
+
+QqTransport::~QqTransport() { stop(); }
+
+Capabilities QqTransport::capabilities() const {
+    Capabilities caps;
+    caps.max_text_units = kMaxTextChars;
+    caps.count_utf16 = false;
+    caps.batch_turn_output = true;
+    caps.supports_typing = false;
+    caps.max_upload_bytes = options_.max_upload_bytes;
+    caps.max_download_bytes = options_.max_download_bytes;
+    return caps;
+}
+
+void QqTransport::start(TransportCallbacks callbacks) {
+    if (running_.exchange(true)) return;
+    callbacks_ = std::move(callbacks);
+    stopping_ = false;
+    worker_ = acecode::JoiningThread(&QqTransport::run, this);
+}
+
+void QqTransport::stop() {
+    if (!running_.exchange(false)) return;
+    stopping_ = true;
+    ws_.abort();
+    wake_.notify_all();
+    if (worker_.joinable()) worker_.join();
+    ws_.close();
+    set_status(LinkState::Stopped, {});
+}
+
+TransportStatus QqTransport::status() const {
+    std::lock_guard<std::mutex> lock(status_mu_);
+    auto copy = status_;
+    copy.extra["held"] = held_.total();
+    copy.extra["markdown"] = markdown_.load();
+    return copy;
+}
+
+void QqTransport::set_status(LinkState state, const std::string& detail, bool retry_stopped) {
+    TransportStatus snapshot;
+    {
+        std::lock_guard<std::mutex> lock(status_mu_);
+        if (status_.state == state && status_.detail == detail && status_.retry_stopped == retry_stopped) return;
+        status_.state = state;
+        status_.detail = redact_secrets(detail, {options_.api.app_secret});
+        status_.retry_stopped = retry_stopped;
+        snapshot = status_;
+    }
+    if (callbacks_.on_status) callbacks_.on_status(snapshot);
+}
+
+bool QqTransport::wait_for(std::chrono::milliseconds duration) {
+    std::unique_lock<std::mutex> lock(wake_mu_);
+    wake_.wait_for(lock, duration, [this] { return stopping_.load(); });
+    return !stopping_;
+}
+
+void QqTransport::run() {
+    std::size_t attempt = 0;
+    while (!stopping_) {
+        set_status(attempt == 0 ? LinkState::Connecting : LinkState::Retrying,
+                   attempt == 0 ? "正在连接 QQ" : "正在重新连接 QQ");
+        std::chrono::milliseconds extra_delay{0};
+        std::string error;
+        const auto token = api_.access_token(&error);
+        if (token.empty()) {
+            if (api_.last_token_auth_failed()) {
+                // 凭据被拒不会自己好:停止重试,等用户重新配置或重新打开开关。
+                set_status(LinkState::Failed, error, true);
+                break;
+            }
+            set_status(LinkState::Retrying, error);
+        } else {
+            const auto url = api_.gateway_url(&error);
+            network::WebSocketConnectOptions ws_options;
+            ws_options.url = url;
+            ws_options.headers = {{"User-Agent", user_agent()}};
+            ws_options.use_proxy = options_.api.use_proxy;
+            if (url.empty()) {
+                set_status(LinkState::Retrying, error);
+            } else if (!ws_.connect(ws_options, &error)) {
+                set_status(LinkState::Retrying, "无法连接 QQ 网关:" + error);
+            } else {
+                session_.on_connected(token, Clock::now());
+                bool fatal = false;
+                while (!stopping_) {
+                    const auto tick = session_.on_tick(Clock::now());
+                    if (tick.zombie) {
+                        ws_.close(4000, "heartbeat timeout");
+                        session_.on_closed(4000);
+                        break;
+                    }
+                    if (tick.heartbeat) ws_.send_text(*tick.heartbeat, std::chrono::seconds(10), nullptr);
+                    network::WebSocketMessage message;
+                    const auto received = ws_.receive(message, std::chrono::milliseconds(500), &error);
+                    if (received == network::WebSocketRecv::Timeout) continue;
+                    if (received == network::WebSocketRecv::Message) {
+                        auto out = session_.on_frame(message.data, Clock::now());
+                        for (const auto& frame : out.frames) ws_.send_text(frame, std::chrono::seconds(10), nullptr);
+                        if (out.ready) {
+                            attempt = 0;
+                            {
+                                std::lock_guard<std::mutex> lock(status_mu_);
+                                if (!out.bot_name.empty()) status_.display_name = out.bot_name;
+                            }
+                            set_status(LinkState::Connected, {});
+                        }
+                        for (const auto& [type, d] : out.dispatches) handle_dispatch(type, d);
+                        if (out.reconnect) {
+                            ws_.close(4000, "reconnect requested");
+                            break;
+                        }
+                        continue;
+                    }
+                    if (stopping_) break;
+                    const int code = received == network::WebSocketRecv::Closed ? ws_.close_code() : 1006;
+                    const auto decision = session_.on_closed(code);
+                    if (decision.action == CloseAction::Fatal) {
+                        set_status(LinkState::Failed, decision.reason, true);
+                        fatal = true;
+                    } else {
+                        if (decision.action == CloseAction::RefreshToken) api_.invalidate_token();
+                        if (decision.action == CloseAction::RateLimited) extra_delay = options_.rate_limit_delay;
+                        set_status(LinkState::Retrying, decision.reason);
+                    }
+                    break;
+                }
+                ws_.close();
+                if (fatal) break;
+            }
+        }
+        if (stopping_) break;
+        const auto& backoff = options_.backoff;
+        auto delay = backoff.empty() ? std::chrono::milliseconds(1000)
+                                     : backoff[(std::min)(attempt, backoff.size() - 1)];
+        delay = (std::max)(delay, extra_delay);
+        ++attempt;
+        if (!wait_for(delay)) break;
+    }
+    // 致命错误后保持 Failed 状态,线程退出;stop() 负责收尾。
+    if (!stopping_) {
+        std::unique_lock<std::mutex> lock(wake_mu_);
+        wake_.wait(lock, [this] { return stopping_.load(); });
+    }
+}
+
+bool QqTransport::seen_before(const std::string& message_id) {
+    std::lock_guard<std::mutex> lock(seen_mu_);
+    if (seen_.count(message_id)) return true;
+    seen_.insert(message_id);
+    seen_order_.push_back(message_id);
+    while (seen_order_.size() > kSeenLimit) {
+        seen_.erase(seen_order_.front());
+        seen_order_.pop_front();
+    }
+    return false;
+}
+
+void QqTransport::handle_dispatch(const std::string& type, const nlohmann::json& d) {
+    auto inbound = parse_message_event(type, d, options_.api.app_id, now_ms());
+    if (!inbound || seen_before(inbound->message_id)) return;
+    // 先用这条新消息的被动额度补发之前暂存的输出,再交给核心处理新消息。
+    auto held = held_.take(inbound->address.key());
+    if (!held.empty())
+        LOG_INFO("[channels/qq] resending " + std::to_string(held.size()) + " held output(s) before the new message");
+    bool first = true;
+    for (auto& item : held) {
+        if (first && !item.file) item.text = "(补发)" + item.text;
+        first = false;
+        deliver(inbound->address, item, inbound->reply_context, true);
+    }
+    if (callbacks_.on_inbound) callbacks_.on_inbound(std::move(*inbound));
+}
+
+ApiResult QqTransport::attempt_text(const std::string& scope, const std::string& target,
+                                    const std::string& text, const ReplyPlan& plan) {
+    auto body_for = [&](bool markdown, std::int64_t seq) {
+        nlohmann::json body = markdown
+            ? nlohmann::json{{"markdown", {{"content", text}}}, {"msg_type", kMsgTypeMarkdown}}
+            : nlohmann::json{{"content", markdown_to_plain(text)}, {"msg_type", kMsgTypeText}};
+        body["msg_seq"] = seq;
+        if (plan.passive) body["msg_id"] = plan.msg_id;
+        return body;
+    };
+    if (markdown_) {
+        auto result = api_.send_message(scope, target, body_for(true, plan.msg_seq));
+        if (result.ok || !markdown_rejected(result.error)) return result;
+        // 该机器人不支持 Markdown:之后一律发纯文本。
+        markdown_ = false;
+        LOG_WARN("[channels/qq] markdown rejected, falling back to plain text");
+    }
+    return api_.send_message(scope, target, body_for(false, budget_.next_seq()));
+}
+
+ApiResult QqTransport::attempt(const Address& to, const HeldItem& item, const ReplyPlan& plan) {
+    const auto [scope, target] = scope_of(to);
+    if (!item.file) return attempt_text(scope, target, item.text, plan);
+
+    ApiResult failure;
+    std::error_code ec;
+    const auto size = std::filesystem::file_size(item.path, ec);
+    if (ec || size > options_.max_upload_bytes) {
+        failure.error.message = ec ? "文件不存在或不可读" : "文件超过 QQ 上传上限";
+        return failure;
+    }
+    std::ifstream in(item.path, std::ios::binary);
+    const std::string bytes((std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>());
+    if (bytes.size() != size) {
+        failure.error.message = "读取文件失败";
+        return failure;
+    }
+    const auto uploaded = api_.upload_file(scope, target, file_type_for(item.mime_type, item.name),
+                                           base64_encode(bytes), item.name);
+    if (!uploaded.ok) return uploaded;
+    const auto info = uploaded.response.value("file_info", std::string{});
+    if (info.empty()) {
+        failure.error.message = "QQ 上传结果缺少 file_info";
+        return failure;
+    }
+    nlohmann::json body{{"content", ""}, {"msg_type", kMsgTypeMedia}, {"media", {{"file_info", info}}},
+                        {"msg_seq", plan.msg_seq}};
+    if (plan.passive) body["msg_id"] = plan.msg_id;
+    return api_.send_message(scope, target, body);
+}
+
+SendResult QqTransport::deliver(const Address& to, const HeldItem& item, const nlohmann::json& reply_context,
+                                bool flushing) {
+    const auto key = to.key();
+    if (!flushing && held_.size(key) > 0) {
+        held_.push(key, item);
+        return {SendOutcome::Held, {}};
+    }
+    auto plan = budget_.plan(reply_context, now_ms());
+    auto result = attempt(to, item, plan);
+    if (result.ok) return {SendOutcome::Sent, {}};
+    if (plan.passive && client_error(result.error)) {
+        // 被动回复被拒(窗口已过等):这条消息不再尝试被动,改发主动消息。
+        LOG_INFO("[channels/qq] passive reply refused (" + redact_secrets(result.error.message, {options_.api.app_secret}) +
+                 "), sending as an active message");
+        budget_.exhaust(plan.msg_id);
+        plan = ReplyPlan{false, {}, budget_.next_seq()};
+        result = attempt(to, item, plan);
+        if (result.ok) return {SendOutcome::Sent, {}};
+    }
+    if (!plan.passive && client_error(result.error)) {
+        held_.push(key, item);
+        LOG_WARN("[channels/qq] active message refused (" + redact_secrets(result.error.message, {options_.api.app_secret}) +
+                 "), held until the contact's next message");
+        return {SendOutcome::Held, result.error.message};
+    }
+    LOG_WARN("[channels/qq] send failed: " + redact_secrets(result.error.message, {options_.api.app_secret}));
+    return {SendOutcome::Failed, result.error.message.empty() ? "QQ 发送失败" : result.error.message};
+}
+
+SendResult QqTransport::send_text(const Address& to, const std::string& text,
+                                  const nlohmann::json& reply_context) {
+    SendResult overall{SendOutcome::Sent, {}};
+    for (const auto& chunk : chunk_text(text, kMaxTextChars, false)) {
+        HeldItem item;
+        item.text = chunk;
+        const auto result = deliver(to, item, reply_context, false);
+        if (result.outcome == SendOutcome::Failed) return result;
+        if (result.outcome == SendOutcome::Held) overall = result;
+    }
+    return overall;
+}
+
+SendResult QqTransport::send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                                  const std::string& mime_type, const nlohmann::json& reply_context) {
+    // 超过直传上限(分片上传尚未实现)时改发一条文字说明,对方至少知道有文件没发过去。
+    std::error_code ec;
+    const auto size = std::filesystem::file_size(path, ec);
+    if (!ec && size > options_.max_upload_bytes) {
+        const auto limit_mib = std::to_string(options_.max_upload_bytes / (1024u * 1024u));
+        LOG_INFO("[channels/qq] file of " + std::to_string(size) + " bytes is over the " + limit_mib +
+                 " MiB direct upload limit, sending a text notice instead");
+        return send_text(to, "文件「" + name + "」超过 QQ 直传上限(" + limit_mib + " MiB),未发送;请在 ACECode 中查看。",
+                         reply_context);
+    }
+    HeldItem item;
+    item.file = true;
+    item.path = path;
+    item.name = name;
+    item.mime_type = mime_type;
+    return deliver(to, item, reply_context, false);
+}
+
+bool QqTransport::download(const Attachment& attachment, const std::filesystem::path& dest, std::string* error) {
+    if (attachment.remote_ref.empty()) {
+        if (error) *error = "附件缺少下载地址";
+        return false;
+    }
+    if (attachment.size > options_.max_download_bytes) {
+        if (error) *error = "附件超过大小限制";
+        return false;
+    }
+    return api_.download(attachment.remote_ref, dest, options_.max_download_bytes, error);
+}
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/qqbot/qq_transport.hpp b/src/adapters/im/qqbot/qq_transport.hpp
new file mode 100644
index 000000000..1ae1e8e6c
--- /dev/null
+++ b/src/adapters/im/qqbot/qq_transport.hpp
@@ -0,0 +1,88 @@
+#pragma once
+
+// QQ 官方机器人传输层:本机 WebSocket 网关长连接 + OpenAPI 发送(design D10)。
+//
+// 发送策略:先用触发本回合的那条消息做被动回复;额度用尽、窗口已过或平台拒绝被动回复时
+// 改发主动消息;主动消息也被拒(对方/群主关闭、额度用完)时暂存,等该会话下一条消息到来时
+// 作为被动回复补发。某会话已有暂存时,新的输出直接排在暂存之后,保证顺序。
+
+#include "im/qqbot/qq_api.hpp"
+#include "im/qqbot/qq_gateway.hpp"
+#include "im/qqbot/qq_reply_budget.hpp"
+#include "im/transport.hpp"
+#include "network/websocket_client.hpp"
+#include "utils/joining_thread.hpp"
+
+#include <atomic>
+#include <condition_variable>
+#include <deque>
+#include <mutex>
+#include <set>
+#include <vector>
+
+namespace acecode::im::qqbot {
+
+struct QqTransportOptions {
+    ApiOptions api;
+    bool markdown = true;
+    ReplyLimits limits;
+    std::vector<std::chrono::milliseconds> backoff{
+        std::chrono::seconds(1), std::chrono::seconds(2), std::chrono::seconds(5),
+        std::chrono::seconds(10), std::chrono::seconds(30), std::chrono::seconds(60)};
+    std::chrono::milliseconds rate_limit_delay{std::chrono::seconds(60)};
+    std::uint64_t max_upload_bytes = 20u * 1024u * 1024u;
+    std::uint64_t max_download_bytes = 25u * 1024u * 1024u;
+};
+
+class QqTransport final : public Transport {
+public:
+    explicit QqTransport(QqTransportOptions options);
+    ~QqTransport() override;
+
+    std::string platform() const override { return "qq"; }
+    Capabilities capabilities() const override;
+    void start(TransportCallbacks callbacks) override;
+    void stop() override;
+    TransportStatus status() const override;
+    SendResult send_text(const Address& to, const std::string& text,
+                         const nlohmann::json& reply_context) override;
+    SendResult send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                         const std::string& mime_type, const nlohmann::json& reply_context) override;
+    bool download(const Attachment& attachment, const std::filesystem::path& dest,
+                  std::string* error) override;
+
+    std::size_t held_count() const { return held_.total(); }
+
+private:
+    void run();
+    bool wait_for(std::chrono::milliseconds duration);
+    void set_status(LinkState state, const std::string& detail, bool retry_stopped = false);
+    void handle_dispatch(const std::string& type, const nlohmann::json& d);
+    bool seen_before(const std::string& message_id);
+    SendResult deliver(const Address& to, const HeldItem& item, const nlohmann::json& reply_context,
+                       bool flushing);
+    ApiResult attempt(const Address& to, const HeldItem& item, const ReplyPlan& plan);
+    ApiResult attempt_text(const std::string& scope, const std::string& target, const std::string& text,
+                           const ReplyPlan& plan);
+
+    QqTransportOptions options_;
+    Api api_;
+    ReplyBudget budget_;
+    HeldQueue held_;
+    GatewaySession session_;
+    network::WebSocketClient ws_;
+    TransportCallbacks callbacks_;
+    acecode::JoiningThread worker_;
+    std::atomic<bool> running_{false};
+    std::atomic<bool> stopping_{false};
+    std::atomic<bool> markdown_{true};
+    std::mutex wake_mu_;
+    std::condition_variable wake_;
+    mutable std::mutex status_mu_;
+    TransportStatus status_;
+    std::mutex seen_mu_;
+    std::set<std::string> seen_;
+    std::deque<std::string> seen_order_;
+};
+
+} // namespace acecode::im::qqbot
diff --git a/src/adapters/im/redact.cpp b/src/adapters/im/redact.cpp
new file mode 100644
index 000000000..b336e320c
--- /dev/null
+++ b/src/adapters/im/redact.cpp
@@ -0,0 +1,61 @@
+#include "redact.hpp"
+
+#include <cctype>
+
+namespace acecode::im {
+namespace {
+
+bool token_char(char c) {
+    return std::isalnum(static_cast<unsigned char>(c)) != 0 || c == '_' || c == '-';
+}
+
+bool digit(char c) { return c >= '0' && c <= '9'; }
+
+// 把 <至少 5 位数字>:<至少 30 位 token 字符> 换成 ***。
+std::string redact_bot_tokens(const std::string& text) {
+    std::string out;
+    out.reserve(text.size());
+    std::size_t i = 0;
+    while (i < text.size()) {
+        if (digit(text[i]) && (i == 0 || !digit(text[i - 1]))) {
+            std::size_t j = i;
+            while (j < text.size() && digit(text[j])) ++j;
+            if (j - i >= 5 && j < text.size() && text[j] == ':') {
+                std::size_t k = j + 1;
+                while (k < text.size() && token_char(text[k])) ++k;
+                if (k - (j + 1) >= 30) {
+                    out += "***";
+                    i = k;
+                    continue;
+                }
+            }
+            out.append(text, i, j - i);
+            i = j;
+            continue;
+        }
+        out.push_back(text[i]);
+        ++i;
+    }
+    return out;
+}
+
+} // namespace
+
+std::string mask_secret(std::string_view secret) {
+    if (secret.size() < 8) return "****";
+    return "****" + std::string(secret.substr(secret.size() - 4));
+}
+
+std::string redact_secrets(std::string text, const std::vector<std::string>& secrets) {
+    for (const auto& secret : secrets) {
+        if (secret.size() < 6) continue;
+        std::size_t pos = 0;
+        while ((pos = text.find(secret, pos)) != std::string::npos) {
+            text.replace(pos, secret.size(), "***");
+            pos += 3;
+        }
+    }
+    return redact_bot_tokens(text);
+}
+
+} // namespace acecode::im
diff --git a/src/adapters/im/redact.hpp b/src/adapters/im/redact.hpp
new file mode 100644
index 000000000..cb44201c8
--- /dev/null
+++ b/src/adapters/im/redact.hpp
@@ -0,0 +1,21 @@
+#pragma once
+
+// 通道凭据脱敏。凭据(QQ AppSecret、Telegram bot token、扫码临时密钥)只允许以
+// 脱敏形式出现在接口返回、日志与错误文本里。
+
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace acecode::im {
+
+// 展示值:保留末 4 位,前面一律 "****";少于 8 个字符时整体显示为 "****"。
+std::string mask_secret(std::string_view secret);
+
+// 从任意文本中抹掉:
+//   - secrets 里列出的每个非空值(长度 >= 6 才处理,避免误伤普通词);
+//   - 形如 <数字>:<30+ 位 token 字符> 的 Telegram bot token(含 URL 里的 bot<token>)。
+// 被抹掉的部分替换为 "***"。手写扫描,不使用 std::regex。
+std::string redact_secrets(std::string text, const std::vector<std::string>& secrets = {});
+
+} // namespace acecode::im
diff --git a/src/adapters/im/telegram/tg_api.cpp b/src/adapters/im/telegram/tg_api.cpp
new file mode 100644
index 000000000..350d4c73c
--- /dev/null
+++ b/src/adapters/im/telegram/tg_api.cpp
@@ -0,0 +1,109 @@
+#include "tg_api.hpp"
+
+#include "im/redact.hpp"
+
+#include <algorithm>
+#include <cctype>
+#include <stdexcept>
+#include <vector>
+
+namespace acecode::im::telegram {
+namespace {
+
+std::string lower(std::string text) {
+    std::transform(text.begin(), text.end(), text.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return text;
+}
+
+} // namespace
+
+ConflictKind conflict_kind(const ApiResult& result) {
+    if (result.status != 409 && result.error_code != 409) return ConflictKind::None;
+    return lower(result.description).find("webhook") != std::string::npos ? ConflictKind::Webhook
+                                                                           : ConflictKind::OtherPoller;
+}
+
+Api::Api(ApiOptions options) : options_(std::move(options)) {
+    while (!options_.api_base.empty() && options_.api_base.back() == '/') options_.api_base.pop_back();
+}
+
+std::string Api::base() const { return options_.api_base + "/bot" + options_.token + "/"; }
+
+ApiResult Api::parse(const HttpResponse& response) const {
+    ApiResult result;
+    result.status = response.status;
+    result.cancelled = response.cancelled;
+    const std::vector<std::string> secrets{options_.token};
+    if (response.status == 0) {
+        result.description = redact_secrets(response.error.empty() ? "无法连接 Telegram" : response.error, secrets);
+        return result;
+    }
+    try {
+        const auto json = nlohmann::json::parse(response.body);
+        if (!json.is_object()) throw std::runtime_error("not an object");
+        result.ok = json.value("ok", false) && response.status >= 200 && response.status < 300;
+        if (json.contains("result")) result.result = json["result"];
+        result.error_code = json.value("error_code", 0);
+        result.description = redact_secrets(json.value("description", std::string{}), secrets);
+        if (json.contains("parameters") && json["parameters"].is_object())
+            result.retry_after = json["parameters"].value("retry_after", 0);
+    } catch (...) {
+        result.ok = false;
+        result.description = "Telegram 返回了无效数据(HTTP " + std::to_string(response.status) + ")";
+    }
+    if (!result.ok && result.description.empty())
+        result.description = "Telegram 请求失败(HTTP " + std::to_string(response.status) + ")";
+    return result;
+}
+
+ApiResult Api::call(const std::string& method, const nlohmann::json& params, std::chrono::milliseconds timeout,
+                    std::function<bool()> cancel) const {
+    HttpRequest request;
+    request.method = "POST";
+    request.url = base() + method;
+    request.headers = {{"Content-Type", "application/json"}};
+    request.body = params.is_null() ? "{}" : params.dump();
+    request.timeout = timeout;
+    request.use_proxy = options_.use_proxy;
+    request.cancel = std::move(cancel);
+    return parse(http_send(request));
+}
+
+ApiResult Api::call_multipart(const std::string& method, std::vector<HttpPart> parts,
+                              std::chrono::milliseconds timeout) const {
+    HttpRequest request;
+    request.method = "POST";
+    request.url = base() + method;
+    request.parts = std::move(parts);
+    request.timeout = timeout;
+    request.use_proxy = options_.use_proxy;
+    return parse(http_send(request));
+}
+
+bool Api::download(const std::string& file_path, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                   std::string* error) const {
+    HttpRequest request;
+    request.url = options_.api_base + "/file/bot" + options_.token + "/" + file_path;
+    request.timeout = std::chrono::minutes(2);
+    request.use_proxy = options_.use_proxy;
+    request.download_to = dest;
+    request.max_download_bytes = max_bytes;
+    const auto response = http_send(request);
+    if (response.too_large) {
+        if (error) *error = "文件超过 Telegram 下载上限";
+        return false;
+    }
+    if (response.status < 200 || response.status >= 300) {
+        std::error_code ec;
+        std::filesystem::remove(dest, ec);
+        if (error) {
+            *error = response.status == 0 ? redact_secrets(response.error, {options_.token})
+                                          : "下载文件失败:HTTP " + std::to_string(response.status);
+        }
+        return false;
+    }
+    return true;
+}
+
+} // namespace acecode::im::telegram
diff --git a/src/adapters/im/telegram/tg_api.hpp b/src/adapters/im/telegram/tg_api.hpp
new file mode 100644
index 000000000..74d06d209
--- /dev/null
+++ b/src/adapters/im/telegram/tg_api.hpp
@@ -0,0 +1,64 @@
+#pragma once
+
+// Telegram Bot API 客户端(design D11)。请求统一 POST JSON(文件走 multipart),
+// 响应按 {"ok","result","error_code","description","parameters.retry_after"} 解析。
+// token 出现在 URL 路径里,所有错误与日志文本都会脱敏。
+
+#include "im/http.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <filesystem>
+#include <functional>
+#include <string>
+#include <vector>
+
+namespace acecode::im::telegram {
+
+inline constexpr const char* kApiBase = "https://api.telegram.org";
+
+struct ApiOptions {
+    std::string token;
+    std::string api_base = kApiBase;
+    bool use_proxy = true;
+};
+
+struct ApiResult {
+    bool ok = false;
+    long status = 0;          // HTTP 状态码;0 = 没拿到响应
+    int error_code = 0;       // Bot API error_code
+    std::string description;  // 已脱敏
+    nlohmann::json result;
+    int retry_after = 0;      // 429 时平台要求等待的秒数
+    bool cancelled = false;
+};
+
+enum class ConflictKind { None, Webhook, OtherPoller };
+
+// 409 有两种:机器人配置了 webhook(getUpdates 不可用),或另一个程序正在轮询同一 token。
+ConflictKind conflict_kind(const ApiResult& result);
+
+class Api {
+public:
+    explicit Api(ApiOptions options);
+
+    ApiResult call(const std::string& method, const nlohmann::json& params,
+                   std::chrono::milliseconds timeout = std::chrono::seconds(30),
+                   std::function<bool()> cancel = {}) const;
+    ApiResult call_multipart(const std::string& method, std::vector<HttpPart> parts,
+                             std::chrono::milliseconds timeout = std::chrono::minutes(5)) const;
+    // 按 getFile 返回的 file_path 下载;超过 max_bytes 失败并删除半截文件。
+    bool download(const std::string& file_path, const std::filesystem::path& dest, std::uint64_t max_bytes,
+                  std::string* error) const;
+    const ApiOptions& options() const { return options_; }
+
+private:
+    std::string base() const;
+    ApiResult parse(const HttpResponse& response) const;
+
+    ApiOptions options_;
+};
+
+} // namespace acecode::im::telegram
diff --git a/src/adapters/im/telegram/tg_rate_limit.cpp b/src/adapters/im/telegram/tg_rate_limit.cpp
new file mode 100644
index 000000000..2b4f7d253
--- /dev/null
+++ b/src/adapters/im/telegram/tg_rate_limit.cpp
@@ -0,0 +1,30 @@
+#include "tg_rate_limit.hpp"
+
+namespace acecode::im::telegram {
+
+RateLimiter::Clock::time_point RateLimiter::reserve(const std::string& chat, bool group, Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    auto at = now;
+    const auto allowed = next_allowed_.find(chat);
+    if (allowed != next_allowed_.end() && allowed->second > at) at = allowed->second;
+    if (group) {
+        auto& sends = group_sends_[chat];
+        while (true) {
+            while (!sends.empty() && sends.front() + limits_.group_window <= at) sends.pop_front();
+            if (sends.size() < limits_.group_per_minute) break;
+            at = sends.front() + limits_.group_window;
+        }
+        sends.push_back(at);
+    }
+    next_allowed_[chat] = at + limits_.per_chat_gap;
+    return at;
+}
+
+void RateLimiter::penalize(const std::string& chat, std::chrono::seconds retry_after, Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    auto& allowed = next_allowed_[chat];
+    const auto until = now + retry_after;
+    if (allowed < until) allowed = until;
+}
+
+} // namespace acecode::im::telegram
diff --git a/src/adapters/im/telegram/tg_rate_limit.hpp b/src/adapters/im/telegram/tg_rate_limit.hpp
new file mode 100644
index 000000000..9265d9a31
--- /dev/null
+++ b/src/adapters/im/telegram/tg_rate_limit.hpp
@@ -0,0 +1,40 @@
+#pragma once
+
+// Telegram 发送限速(纯逻辑,design D11):同一聊天相邻两条至少间隔 1 秒;
+// 同一个群每 60 秒最多 20 条;平台返回 429 时按 retry_after 暂停该聊天。
+// 调用方先 reserve 得到发送时刻,睡到该时刻再发。
+
+#include <chrono>
+#include <deque>
+#include <map>
+#include <mutex>
+#include <string>
+
+namespace acecode::im::telegram {
+
+class RateLimiter {
+public:
+    using Clock = std::chrono::steady_clock;
+
+    struct Limits {
+        std::chrono::milliseconds per_chat_gap{std::chrono::seconds(1)};
+        std::size_t group_per_minute = 20;
+        std::chrono::milliseconds group_window{std::chrono::minutes(1)};
+    };
+
+    RateLimiter() = default;
+    explicit RateLimiter(Limits limits) : limits_(limits) {}
+
+    // 预约一条消息的发送时刻;返回值不早于 now。预约即占用名额。
+    Clock::time_point reserve(const std::string& chat, bool group, Clock::time_point now);
+    // 平台对该聊天返回 429:retry_after 之内不再预约到该聊天。
+    void penalize(const std::string& chat, std::chrono::seconds retry_after, Clock::time_point now);
+
+private:
+    Limits limits_;
+    std::mutex mu_;
+    std::map<std::string, Clock::time_point> next_allowed_;
+    std::map<std::string, std::deque<Clock::time_point>> group_sends_;
+};
+
+} // namespace acecode::im::telegram
diff --git a/src/adapters/im/telegram/tg_transport.cpp b/src/adapters/im/telegram/tg_transport.cpp
new file mode 100644
index 000000000..349d9f860
--- /dev/null
+++ b/src/adapters/im/telegram/tg_transport.cpp
@@ -0,0 +1,379 @@
+#include "tg_transport.hpp"
+
+#include "im/markdown.hpp"
+#include "im/redact.hpp"
+#include "im/text_chunk.hpp"
+#include "utils/logger.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <algorithm>
+#include <cctype>
+#include <thread>
+
+namespace acecode::im::telegram {
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+// Telegram 单条消息上限 4096(按 UTF-16 计、实体解析之后);Markdown 源文本转换后只会更短,
+// 留一些余量按 4000 切。
+constexpr std::size_t kChunkUnits = 4000;
+
+bool contains_ci(const std::string& text, const std::string& needle) {
+    std::string lower = text;
+    std::transform(lower.begin(), lower.end(), lower.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return lower.find(needle) != std::string::npos;
+}
+
+bool non_ascii(const std::string& text) {
+    return std::any_of(text.begin(), text.end(), [](char c) { return static_cast<unsigned char>(c) >= 0x80; });
+}
+
+bool is_image(const std::string& mime, const std::string& name) {
+    if (mime.rfind("image/", 0) == 0) return mime != "image/svg+xml";
+    std::string lower = name;
+    std::transform(lower.begin(), lower.end(), lower.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    for (const char* ext : {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"}) {
+        const std::string e(ext);
+        if (lower.size() >= e.size() && lower.compare(lower.size() - e.size(), e.size(), e) == 0) return true;
+    }
+    return false;
+}
+
+nlohmann::json chat_id_value(const std::string& chat) {
+    try {
+        std::size_t used = 0;
+        const auto value = std::stoll(chat, &used);
+        if (used == chat.size()) return value;
+    } catch (...) {
+    }
+    return chat;
+}
+
+} // namespace
+
+TelegramTransport::TelegramTransport(TelegramTransportOptions options)
+    : options_(std::move(options)), api_(options_.api), limiter_(options_.limits) {
+    offset_ = options_.initial_offset;
+}
+
+TelegramTransport::~TelegramTransport() { stop(); }
+
+Capabilities TelegramTransport::capabilities() const {
+    Capabilities caps;
+    caps.max_text_units = kChunkUnits;
+    caps.count_utf16 = true;
+    caps.batch_turn_output = false;
+    caps.supports_typing = true;
+    caps.max_upload_bytes = options_.max_upload_bytes;
+    caps.max_download_bytes = options_.max_download_bytes;
+    return caps;
+}
+
+void TelegramTransport::start(TransportCallbacks callbacks) {
+    if (running_.exchange(true)) return;
+    callbacks_ = std::move(callbacks);
+    stopping_ = false;
+    poller_ = acecode::JoiningThread(&TelegramTransport::poll_loop, this);
+    typer_ = acecode::JoiningThread(&TelegramTransport::typing_loop, this);
+}
+
+void TelegramTransport::stop() {
+    if (!running_.exchange(false)) return;
+    stopping_ = true;
+    wake_.notify_all();
+    if (poller_.joinable()) poller_.join();
+    if (typer_.joinable()) typer_.join();
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        typing_.clear();
+    }
+    set_status(LinkState::Stopped, {});
+}
+
+TransportStatus TelegramTransport::status() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return status_;
+}
+
+BotIdentity TelegramTransport::bot() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return bot_;
+}
+
+void TelegramTransport::set_status(LinkState state, const std::string& detail, bool retry_stopped) {
+    TransportStatus snapshot;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        const auto clean = redact_secrets(detail, {options_.api.token});
+        if (status_.state == state && status_.detail == clean && status_.retry_stopped == retry_stopped) return;
+        status_.state = state;
+        status_.detail = clean;
+        status_.retry_stopped = retry_stopped;
+        snapshot = status_;
+    }
+    if (callbacks_.on_status) callbacks_.on_status(snapshot);
+}
+
+bool TelegramTransport::wait_for(std::chrono::milliseconds duration) {
+    std::unique_lock<std::mutex> lock(wake_mu_);
+    wake_.wait_for(lock, duration, [this] { return stopping_.load() || webhook_cleared_.load(); });
+    return !stopping_;
+}
+
+void TelegramTransport::poll_loop() {
+    const auto cancel = [&stopping = stopping_] { return stopping.load(); };
+    std::size_t attempt = 0;
+    auto backoff = [&attempt, &steps = options_.backoff] {
+        const auto delay = steps.empty() ? std::chrono::milliseconds(1000) : steps[(std::min)(attempt, steps.size() - 1)];
+        ++attempt;
+        return delay;
+    };
+    bool identified = false;
+    set_status(LinkState::Connecting, "正在连接 Telegram");
+    while (!stopping_) {
+        if (!identified) {
+            const auto me = api_.call("getMe", nlohmann::json::object(), std::chrono::seconds(20), cancel);
+            if (me.cancelled || stopping_) break;
+            if (!me.ok) {
+                if (me.status == 401 || me.status == 404) {
+                    set_status(LinkState::Failed, "token 无效或已被吊销", true);
+                    break;
+                }
+                set_status(LinkState::Retrying, me.description);
+                if (!wait_for(backoff())) break;
+                continue;
+            }
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                const auto& r = me.result;
+                bot_.id = r.contains("id") ? (r["id"].is_number_integer() ? std::to_string(r["id"].get<std::int64_t>())
+                                                                           : r.value("id", std::string{}))
+                                           : std::string{};
+                bot_.username = r.value("username", std::string{});
+                status_.account = bot_.id;
+                status_.display_name = bot_.username.empty() ? std::string{} : "@" + bot_.username;
+                status_.extra["username"] = bot_.username;
+                status_.extra["privacy_mode"] = !r.value("can_read_all_group_messages", false);
+                status_.extra["link"] = bot_.username.empty() ? std::string{} : "https://t.me/" + bot_.username;
+            }
+            identified = true;
+            // getMe 成功已证明 token 与网络可用;不要等第一次长轮询返回(没有新消息时要等满
+            // poll_timeout)才显示已连接。之后的 409 / 网络错误会再把状态改掉。
+            set_status(LinkState::Connected, {});
+        }
+
+        nlohmann::json params{{"offset", offset_.load()},
+                              {"timeout", options_.poll_timeout.count()},
+                              {"allowed_updates", nlohmann::json::array({"message"})}};
+        const auto updates = api_.call("getUpdates", params, options_.poll_timeout + std::chrono::seconds(15), cancel);
+        if (updates.cancelled || stopping_) break;
+        if (updates.ok) {
+            attempt = 0;
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                status_.extra.erase("webhook");
+            }
+            set_status(LinkState::Connected, {});
+            std::int64_t next = offset_.load();
+            const auto me = bot();
+            if (updates.result.is_array()) {
+                for (const auto& update : updates.result) {
+                    auto parsed = parse_update(update, me, me.id);
+                    if (parsed.update_id >= next) next = parsed.update_id + 1;
+                    if (parsed.inbound && callbacks_.on_inbound) callbacks_.on_inbound(std::move(*parsed.inbound));
+                }
+            }
+            if (next != offset_.load()) {
+                offset_ = next;
+                if (options_.on_offset) options_.on_offset(next);
+            }
+            continue;
+        }
+        switch (conflict_kind(updates)) {
+            case ConflictKind::Webhook: {
+                {
+                    std::lock_guard<std::mutex> lock(mu_);
+                    status_.extra["webhook"] = true;
+                }
+                set_status(LinkState::Failed, "该机器人已配置 webhook,长轮询不可用;确认后可移除 webhook 并继续", true);
+                webhook_cleared_ = false;
+                std::unique_lock<std::mutex> lock(wake_mu_);
+                wake_.wait(lock, [this] { return stopping_.load() || webhook_cleared_.load(); });
+                webhook_cleared_ = false;
+                continue;
+            }
+            case ConflictKind::OtherPoller:
+                set_status(LinkState::Retrying, "机器人被其他程序占用(同一 token 正在别处长轮询)");
+                if (!wait_for(options_.conflict_retry)) return;
+                continue;
+            case ConflictKind::None:
+                break;
+        }
+        if (updates.status == 401 || updates.status == 404) {
+            set_status(LinkState::Failed, "token 无效或已被吊销", true);
+            break;
+        }
+        if (updates.status == 429 && updates.retry_after > 0) {
+            set_status(LinkState::Retrying, "Telegram 限频,稍后继续");
+            if (!wait_for(std::chrono::seconds(updates.retry_after))) break;
+            continue;
+        }
+        set_status(LinkState::Retrying, updates.description);
+        if (!wait_for(backoff())) break;
+    }
+    if (!stopping_) {
+        std::unique_lock<std::mutex> lock(wake_mu_);
+        wake_.wait(lock, [this] { return stopping_.load(); });
+    }
+}
+
+void TelegramTransport::typing_loop() {
+    while (!stopping_) {
+        std::vector<std::pair<std::string, std::string>> chats;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            chats.assign(typing_.begin(), typing_.end());
+        }
+        for (const auto& [chat, thread] : chats) {
+            nlohmann::json params{{"chat_id", chat_id_value(chat)}, {"action", "typing"}};
+            if (!thread.empty()) params["message_thread_id"] = chat_id_value(thread);
+            api_.call("sendChatAction", params, std::chrono::seconds(10));
+        }
+        std::unique_lock<std::mutex> lock(wake_mu_);
+        wake_.wait_for(lock, options_.typing_interval, [this] { return stopping_.load(); });
+    }
+}
+
+void TelegramTransport::set_typing(const Address& to, bool on) {
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (on) typing_.insert({to.chat, to.thread});
+        else typing_.erase({to.chat, to.thread});
+    }
+    if (on) wake_.notify_all();
+}
+
+ApiResult TelegramTransport::send_request(const Address& to, const std::string& method,
+                                          const nlohmann::json& params, const std::vector<HttpPart>& parts) {
+    const bool group = to.kind == ChatKind::Group;
+    ApiResult result;
+    for (int attempt = 0; attempt < 3; ++attempt) {
+        const auto at = limiter_.reserve(to.chat, group, Clock::now());
+        const auto now = Clock::now();
+        if (at > now) std::this_thread::sleep_for(at - now);
+        result = parts.empty() ? api_.call(method, params) : api_.call_multipart(method, parts);
+        if (result.status == 429 && result.retry_after > 0) {
+            // 429 表示平台明确拒收了这条消息,等待后重发是安全的;顺序由同一线程串行保证。
+            LOG_INFO("[channels/telegram] " + method + " rate limited, resending after " +
+                     std::to_string(result.retry_after) + "s");
+            limiter_.penalize(to.chat, std::chrono::seconds(result.retry_after), Clock::now());
+            continue;
+        }
+        return result;
+    }
+    return result;
+}
+
+SendResult TelegramTransport::send_text(const Address& to, const std::string& text,
+                                        const nlohmann::json& reply_context) {
+    bool first = true;
+    for (const auto& chunk : chunk_text(text, kChunkUnits, true)) {
+        nlohmann::json params{{"chat_id", chat_id_value(to.chat)},
+                              {"text", markdown_to_telegram_html(chunk)},
+                              {"parse_mode", "HTML"}};
+        if (!to.thread.empty()) params["message_thread_id"] = chat_id_value(to.thread);
+        if (first && reply_context.is_object() && reply_context.contains("message_id"))
+            params["reply_parameters"] = {{"message_id", reply_context["message_id"]},
+                                          {"allow_sending_without_reply", true}};
+        auto result = send_request(to, "sendMessage", params, {});
+        if (!result.ok && result.status == 400 && contains_ci(result.description, "parse")) {
+            // HTML 被拒(实体解析失败):同一段内容改用纯文本发送,不丢消息。
+            LOG_INFO("[channels/telegram] HTML rejected, resending the same chunk as plain text");
+            params.erase("parse_mode");
+            params["text"] = markdown_to_plain(chunk);
+            result = send_request(to, "sendMessage", params, {});
+        }
+        if (!result.ok) {
+            LOG_WARN("[channels/telegram] sendMessage failed: " + redact_secrets(result.description, {options_.api.token}));
+            return {SendOutcome::Failed, result.description};
+        }
+        first = false;
+    }
+    return {SendOutcome::Sent, {}};
+}
+
+SendResult TelegramTransport::send_file(const Address& to, const std::filesystem::path& path,
+                                        const std::string& name, const std::string& mime_type,
+                                        const nlohmann::json& reply_context) {
+    std::error_code ec;
+    const auto size = std::filesystem::file_size(path, ec);
+    if (ec) return {SendOutcome::Failed, "文件不存在或不可读"};
+    const bool photo = is_image(mime_type, name) && size <= options_.max_photo_bytes;
+    if (!photo && size > options_.max_upload_bytes) return {SendOutcome::Failed, "文件超过 Telegram 50 MB 上限"};
+    std::vector<HttpPart> parts;
+    parts.push_back(HttpPart{"chat_id", to.chat});
+    if (!to.thread.empty()) parts.push_back(HttpPart{"message_thread_id", to.thread});
+    if (reply_context.is_object() && reply_context.contains("message_id")) {
+        parts.push_back(HttpPart{"reply_parameters",
+                                 nlohmann::json{{"message_id", reply_context["message_id"]},
+                                                {"allow_sending_without_reply", true}}.dump()});
+    }
+    // multipart 文件名只能用 ASCII,原名带非 ASCII 字符时放进说明文字里展示。
+    if (non_ascii(name)) parts.push_back(HttpPart{"caption", name});
+    HttpPart file;
+    file.name = photo ? "photo" : "document";
+    file.file = path;
+    file.filename = name.empty() ? path_to_utf8(path.filename()) : name;
+    file.content_type = mime_type.empty() ? "application/octet-stream" : mime_type;
+    parts.push_back(std::move(file));
+    const auto result = send_request(to, photo ? "sendPhoto" : "sendDocument", nlohmann::json::object(), parts);
+    if (!result.ok) {
+        LOG_WARN(std::string("[channels/telegram] ") + (photo ? "sendPhoto" : "sendDocument") +
+                 " failed: " + redact_secrets(result.description, {options_.api.token}));
+        return {SendOutcome::Failed, result.description};
+    }
+    return {SendOutcome::Sent, {}};
+}
+
+bool TelegramTransport::download(const Attachment& attachment, const std::filesystem::path& dest,
+                                 std::string* error) {
+    if (attachment.remote_ref.empty()) {
+        if (error) *error = "附件缺少 file_id";
+        return false;
+    }
+    if (attachment.size > options_.max_download_bytes) {
+        if (error) *error = "文件超出 Telegram 20 MB 下载上限";
+        return false;
+    }
+    const auto info = api_.call("getFile", {{"file_id", attachment.remote_ref}}, std::chrono::seconds(20));
+    if (!info.ok) {
+        if (error) *error = info.description;
+        return false;
+    }
+    const auto file_path = info.result.value("file_path", std::string{});
+    if (file_path.empty()) {
+        if (error) *error = "文件超出 Telegram 20 MB 下载上限";
+        return false;
+    }
+    if (info.result.value("file_size", std::int64_t{0}) > static_cast<std::int64_t>(options_.max_download_bytes)) {
+        if (error) *error = "文件超出 Telegram 20 MB 下载上限";
+        return false;
+    }
+    return api_.download(file_path, dest, options_.max_download_bytes, error);
+}
+
+nlohmann::json TelegramTransport::action(const std::string& name, const nlohmann::json& args) {
+    (void)args;
+    if (name != "remove_webhook") throw std::runtime_error("Unsupported Telegram action: " + name);
+    const auto result = api_.call("deleteWebhook", {{"drop_pending_updates", false}}, std::chrono::seconds(20));
+    if (!result.ok) throw std::runtime_error("移除 webhook 失败:" + result.description);
+    LOG_INFO("[channels/telegram] webhook removed by user request");
+    webhook_cleared_ = true;
+    wake_.notify_all();
+    return {{"ok", true}};
+}
+
+} // namespace acecode::im::telegram
diff --git a/src/adapters/im/telegram/tg_transport.hpp b/src/adapters/im/telegram/tg_transport.hpp
new file mode 100644
index 000000000..97ff08abd
--- /dev/null
+++ b/src/adapters/im/telegram/tg_transport.hpp
@@ -0,0 +1,85 @@
+#pragma once
+
+// Telegram Bot API 传输层(design D11):长轮询收消息(只需出站 HTTPS),
+// Markdown → HTML 发送且失败回退纯文本,遵守限速,忙碌时持续“正在输入”。
+
+#include "im/telegram/tg_api.hpp"
+#include "im/telegram/tg_rate_limit.hpp"
+#include "im/telegram/tg_update.hpp"
+#include "im/transport.hpp"
+#include "utils/joining_thread.hpp"
+
+#include <atomic>
+#include <condition_variable>
+#include <functional>
+#include <mutex>
+#include <set>
+#include <vector>
+
+namespace acecode::im::telegram {
+
+struct TelegramTransportOptions {
+    ApiOptions api;
+    std::int64_t initial_offset = 0;
+    // 已处理到的下一个 update offset;调用方持久化,重启后从这里继续,避免重复处理。
+    std::function<void(std::int64_t)> on_offset;
+    std::chrono::seconds poll_timeout{25};
+    std::vector<std::chrono::milliseconds> backoff{
+        std::chrono::seconds(1), std::chrono::seconds(2), std::chrono::seconds(5),
+        std::chrono::seconds(10), std::chrono::seconds(30), std::chrono::seconds(60)};
+    std::chrono::milliseconds conflict_retry{std::chrono::seconds(60)};
+    std::chrono::milliseconds typing_interval{4500};
+    RateLimiter::Limits limits;
+    std::uint64_t max_upload_bytes = 50u * 1024u * 1024u;
+    std::uint64_t max_photo_bytes = 10u * 1024u * 1024u;
+    std::uint64_t max_download_bytes = 20u * 1024u * 1024u;
+};
+
+class TelegramTransport final : public Transport {
+public:
+    explicit TelegramTransport(TelegramTransportOptions options);
+    ~TelegramTransport() override;
+
+    std::string platform() const override { return "telegram"; }
+    Capabilities capabilities() const override;
+    void start(TransportCallbacks callbacks) override;
+    void stop() override;
+    TransportStatus status() const override;
+    SendResult send_text(const Address& to, const std::string& text,
+                         const nlohmann::json& reply_context) override;
+    SendResult send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                         const std::string& mime_type, const nlohmann::json& reply_context) override;
+    void set_typing(const Address& to, bool on) override;
+    bool download(const Attachment& attachment, const std::filesystem::path& dest,
+                  std::string* error) override;
+    // "remove_webhook":用户确认后移除机器人的 webhook,然后继续长轮询。
+    nlohmann::json action(const std::string& name, const nlohmann::json& args) override;
+
+    BotIdentity bot() const;
+
+private:
+    void poll_loop();
+    void typing_loop();
+    bool wait_for(std::chrono::milliseconds duration);
+    void set_status(LinkState state, const std::string& detail, bool retry_stopped = false);
+    ApiResult send_request(const Address& to, const std::string& method, const nlohmann::json& params,
+                           const std::vector<HttpPart>& parts);
+
+    TelegramTransportOptions options_;
+    Api api_;
+    RateLimiter limiter_;
+    TransportCallbacks callbacks_;
+    acecode::JoiningThread poller_, typer_;
+    std::atomic<bool> running_{false};
+    std::atomic<bool> stopping_{false};
+    std::atomic<bool> webhook_cleared_{false};
+    std::atomic<std::int64_t> offset_{0};
+    std::mutex wake_mu_;
+    std::condition_variable wake_;
+    mutable std::mutex mu_;  // status_、bot_、typing_
+    TransportStatus status_;
+    BotIdentity bot_;
+    std::set<std::pair<std::string, std::string>> typing_;  // (chat, thread)
+};
+
+} // namespace acecode::im::telegram
diff --git a/src/adapters/im/telegram/tg_update.cpp b/src/adapters/im/telegram/tg_update.cpp
new file mode 100644
index 000000000..266f7ad83
--- /dev/null
+++ b/src/adapters/im/telegram/tg_update.cpp
@@ -0,0 +1,205 @@
+#include "tg_update.hpp"
+
+#include <algorithm>
+#include <cctype>
+#include <utility>
+
+namespace acecode::im::telegram {
+namespace {
+
+std::size_t sequence_length(const std::string& text, std::size_t pos) {
+    const auto lead = static_cast<unsigned char>(text[pos]);
+    std::size_t length = 1;
+    if (lead >= 0xF0 && lead <= 0xF4) length = 4;
+    else if (lead >= 0xE0) length = 3;
+    else if (lead >= 0xC2 && lead <= 0xDF) length = 2;
+    return pos + length > text.size() ? 1 : length;
+}
+
+// UTF-16 单位位置 → UTF-8 字节位置。
+std::size_t byte_offset(const std::string& text, std::size_t units) {
+    std::size_t pos = 0, used = 0;
+    while (pos < text.size() && used < units) {
+        const auto length = sequence_length(text, pos);
+        used += length == 4 ? 2 : 1;
+        pos += length;
+    }
+    return pos;
+}
+
+std::string lower(std::string text) {
+    std::transform(text.begin(), text.end(), text.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return text;
+}
+
+std::string trim(const std::string& text) {
+    std::size_t b = 0, e = text.size();
+    while (b < e && std::isspace(static_cast<unsigned char>(text[b]))) ++b;
+    while (e > b && std::isspace(static_cast<unsigned char>(text[e - 1]))) --e;
+    return text.substr(b, e - b);
+}
+
+std::string id_string(const nlohmann::json& value) {
+    if (value.is_number_integer()) return std::to_string(value.get<std::int64_t>());
+    if (value.is_string()) return value.get<std::string>();
+    return {};
+}
+
+std::string display_name(const nlohmann::json& from) {
+    const auto username = from.value("username", std::string{});
+    if (!username.empty()) return "@" + username;
+    auto name = from.value("first_name", std::string{});
+    const auto last = from.value("last_name", std::string{});
+    if (!last.empty()) name += " " + last;
+    return name;
+}
+
+Attachment file_attachment(const nlohmann::json& file, AttachmentKind kind, const std::string& default_name,
+                           const std::string& default_mime) {
+    Attachment attachment;
+    attachment.kind = kind;
+    attachment.remote_ref = file.value("file_id", std::string{});
+    attachment.name = file.value("file_name", default_name);
+    attachment.mime_type = file.value("mime_type", default_mime);
+    if (file.contains("file_size") && file["file_size"].is_number_integer() && file["file_size"].get<std::int64_t>() > 0)
+        attachment.size = static_cast<std::uint64_t>(file["file_size"].get<std::int64_t>());
+    return attachment;
+}
+
+std::vector<Attachment> attachments_of(const nlohmann::json& message) {
+    constexpr std::uint64_t kPhotoLimit = 20u * 1024u * 1024u;
+    std::vector<Attachment> out;
+    if (message.contains("photo") && message["photo"].is_array() && !message["photo"].empty()) {
+        // 照片有多个尺寸,取不超过下载上限的最大一张。
+        const nlohmann::json* best = &message["photo"].back();
+        for (const auto& size : message["photo"]) {
+            const auto bytes = size.value("file_size", std::int64_t{0});
+            if (bytes > 0 && static_cast<std::uint64_t>(bytes) <= kPhotoLimit) best = &size;
+        }
+        out.push_back(file_attachment(*best, AttachmentKind::Image, "photo.jpg", "image/jpeg"));
+    }
+    if (message.contains("document") && message["document"].is_object()) {
+        auto attachment = file_attachment(message["document"], AttachmentKind::File, "document", "application/octet-stream");
+        if (attachment.mime_type.rfind("image/", 0) == 0) attachment.kind = AttachmentKind::Image;
+        out.push_back(std::move(attachment));
+    }
+    const std::pair<const char*, AttachmentKind> unsupported[] = {
+        {"voice", AttachmentKind::Voice}, {"audio", AttachmentKind::Voice}, {"video", AttachmentKind::Video},
+        {"video_note", AttachmentKind::Video}, {"animation", AttachmentKind::Video},
+        {"sticker", AttachmentKind::Sticker}};
+    for (const auto& [field, kind] : unsupported) {
+        if (message.contains(field) && message[field].is_object())
+            out.push_back(file_attachment(message[field], kind, field, ""));
+    }
+    return out;
+}
+
+struct Mention {
+    bool mentioned = false;
+    std::vector<std::pair<std::size_t, std::size_t>> strip;  // 要从正文删掉的 UTF-8 字节区间
+};
+
+Mention find_mention(const std::string& text, const nlohmann::json& entities, const BotIdentity& bot) {
+    Mention mention;
+    if (!entities.is_array()) return mention;
+    const auto handle = "@" + lower(bot.username);
+    for (const auto& entity : entities) {
+        if (!entity.is_object()) continue;
+        const auto type = entity.value("type", std::string{});
+        const auto offset = entity.value("offset", std::size_t{0});
+        const auto length = entity.value("length", std::size_t{0});
+        const auto begin = byte_offset(text, offset);
+        const auto end = byte_offset(text, offset + length);
+        const auto slice = text.substr(begin, end - begin);
+        if (type == "mention" && !bot.username.empty() && lower(slice) == handle) {
+            mention.mentioned = true;
+            mention.strip.emplace_back(begin, end);
+        } else if (type == "text_mention" && entity.contains("user") &&
+                   id_string(entity["user"].value("id", nlohmann::json())) == bot.id) {
+            mention.mentioned = true;
+        } else if (type == "bot_command" && !bot.username.empty()) {
+            const auto at = slice.find('@');
+            if (at != std::string::npos && lower(slice.substr(at)) == handle) {
+                mention.mentioned = true;
+                mention.strip.emplace_back(begin + at, end);  // "/status@bot" → "/status"
+            }
+        }
+    }
+    return mention;
+}
+
+std::string remove_ranges(std::string text, std::vector<std::pair<std::size_t, std::size_t>> ranges) {
+    std::sort(ranges.begin(), ranges.end(), [](const auto& a, const auto& b) { return a.first > b.first; });
+    for (const auto& [begin, end] : ranges) {
+        if (begin <= end && end <= text.size()) text.erase(begin, end - begin);
+    }
+    return text;
+}
+
+} // namespace
+
+std::string utf16_slice(const std::string& utf8, std::size_t offset, std::size_t length) {
+    const auto begin = byte_offset(utf8, offset);
+    const auto end = byte_offset(utf8, offset + length);
+    return utf8.substr(begin, end - begin);
+}
+
+ParsedUpdate parse_update(const nlohmann::json& update, const BotIdentity& bot, const std::string& account) {
+    ParsedUpdate parsed;
+    if (!update.is_object()) return parsed;
+    parsed.update_id = update.value("update_id", std::int64_t{-1});
+    if (!update.contains("message") || !update["message"].is_object()) return parsed;
+    const auto& message = update["message"];
+    if (!message.contains("chat") || !message.contains("from")) return parsed;
+    const auto& chat = message["chat"];
+    const auto& from = message["from"];
+    if (from.value("is_bot", false)) return parsed;  // 不处理其它机器人(包括自己)的消息
+    const auto chat_type = chat.value("type", std::string{});
+    if (chat_type != "private" && chat_type != "group" && chat_type != "supergroup") return parsed;
+
+    Inbound inbound;
+    inbound.address.platform = "telegram";
+    inbound.address.account = account;
+    inbound.address.kind = chat_type == "private" ? ChatKind::Private : ChatKind::Group;
+    inbound.address.chat = id_string(chat.value("id", nlohmann::json()));
+    inbound.address.sender = id_string(from.value("id", nlohmann::json()));
+    if (inbound.address.kind == ChatKind::Private) inbound.address.chat = inbound.address.sender;
+    if (message.value("is_topic_message", false) && message.contains("message_thread_id"))
+        inbound.address.thread = id_string(message["message_thread_id"]);
+    if (!inbound.address.valid()) return parsed;
+    inbound.message_id = id_string(message.value("message_id", nlohmann::json()));
+    if (inbound.message_id.empty()) return parsed;
+    inbound.sender_name = display_name(from);
+
+    const bool has_text = message.contains("text") && message["text"].is_string();
+    const std::string text = has_text ? message["text"].get<std::string>()
+                                      : message.value("caption", std::string{});
+    const auto entities = has_text ? message.value("entities", nlohmann::json::array())
+                                   : message.value("caption_entities", nlohmann::json::array());
+    const auto mention = find_mention(text, entities, bot);
+    bool reply_to_bot = false;
+    if (message.contains("reply_to_message") && message["reply_to_message"].is_object()) {
+        const auto& replied = message["reply_to_message"];
+        if (replied.contains("from") && id_string(replied["from"].value("id", nlohmann::json())) == bot.id)
+            reply_to_bot = true;
+        auto quote = replied.value("text", replied.value("caption", std::string{}));
+        if (quote.size() > 4000) quote.resize(4000);
+        inbound.quote_text = quote;
+    }
+    inbound.mentioned = inbound.address.kind == ChatKind::Private || mention.mentioned || reply_to_bot;
+    inbound.text = trim(remove_ranges(text, mention.strip));
+
+    if (inbound.address.kind == ChatKind::Private && inbound.text.rfind("/start", 0) == 0) {
+        const auto rest = trim(inbound.text.substr(6));
+        if (!rest.empty() && rest.find(' ') == std::string::npos) inbound.start_code = rest;
+    }
+    inbound.attachments = attachments_of(message);
+    if (inbound.text.empty() && inbound.attachments.empty()) return parsed;
+    inbound.reply_context = {{"message_id", message.value("message_id", std::int64_t{0})}};
+    if (!inbound.address.thread.empty()) inbound.reply_context["thread"] = inbound.address.thread;
+    parsed.inbound = std::move(inbound);
+    return parsed;
+}
+
+} // namespace acecode::im::telegram
diff --git a/src/adapters/im/telegram/tg_update.hpp b/src/adapters/im/telegram/tg_update.hpp
new file mode 100644
index 000000000..84e9ef0d7
--- /dev/null
+++ b/src/adapters/im/telegram/tg_update.hpp
@@ -0,0 +1,33 @@
+#pragma once
+
+// Telegram 更新解析(纯逻辑,design D11)。
+// 只处理 message 更新:私聊一律视为点名;群聊只有 @机器人、带机器人名的命令、
+// 回复机器人消息三种情况算点名。entity 的 offset/length 以 UTF-16 单位计,
+// 这里转换成 UTF-8 字节再切片。
+
+#include "im/transport.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <cstdint>
+#include <optional>
+#include <string>
+
+namespace acecode::im::telegram {
+
+struct BotIdentity {
+    std::string id;        // 机器人用户 id
+    std::string username;  // 不带 @
+};
+
+struct ParsedUpdate {
+    std::int64_t update_id = -1;
+    std::optional<Inbound> inbound;  // 非消息更新、频道帖子等为空
+};
+
+ParsedUpdate parse_update(const nlohmann::json& update, const BotIdentity& bot, const std::string& account);
+
+// 按 UTF-16 单位的 offset/length 从 UTF-8 文本中取子串;越界时截到末尾。
+std::string utf16_slice(const std::string& utf8, std::size_t offset, std::size_t length);
+
+} // namespace acecode::im::telegram
diff --git a/src/adapters/im/text_chunk.cpp b/src/adapters/im/text_chunk.cpp
new file mode 100644
index 000000000..2b77d25af
--- /dev/null
+++ b/src/adapters/im/text_chunk.cpp
@@ -0,0 +1,148 @@
+#include "text_chunk.hpp"
+
+#include <algorithm>
+
+namespace acecode::im {
+namespace {
+
+// 当前位置 UTF-8 序列的字节长度;非法字节按 1 处理,且不越过末尾。
+std::size_t sequence_length(std::string_view text, std::size_t pos) {
+    const auto lead = static_cast<unsigned char>(text[pos]);
+    std::size_t length = 1;
+    if (lead >= 0xF0 && lead <= 0xF4) length = 4;
+    else if (lead >= 0xE0) length = 3;
+    else if (lead >= 0xC2 && lead <= 0xDF) length = 2;
+    if (pos + length > text.size()) return 1;
+    for (std::size_t i = 1; i < length; ++i) {
+        if ((static_cast<unsigned char>(text[pos + i]) & 0xC0) != 0x80) return 1;
+    }
+    return length;
+}
+
+std::size_t units_of(std::size_t length, bool utf16) { return utf16 && length == 4 ? 2 : 1; }
+
+// 不超过 budget 个单位时能放下的最长前缀(字节数),落在字符边界上。
+std::size_t prefix_within(std::string_view text, std::size_t budget, bool utf16) {
+    std::size_t pos = 0, used = 0;
+    while (pos < text.size()) {
+        const auto length = sequence_length(text, pos);
+        const auto units = units_of(length, utf16);
+        if (used + units > budget) break;
+        used += units;
+        pos += length;
+    }
+    return pos;
+}
+
+bool is_fence_line(std::string_view line) {
+    std::size_t i = 0;
+    while (i < line.size() && i < 3 && line[i] == ' ') ++i;
+    return line.substr(i, 3) == "```";
+}
+
+// 扫描文本,返回末尾仍未闭合的围栏行(含语言标记);没有未闭合围栏则返回空。
+std::string open_fence_at_end(std::string_view text) {
+    std::string open;
+    std::size_t start = 0;
+    while (start <= text.size()) {
+        const auto end = text.find('\n', start);
+        const auto line = text.substr(start, end == std::string_view::npos ? std::string_view::npos : end - start);
+        if (is_fence_line(line)) {
+            if (open.empty()) {
+                open = std::string(line);
+                while (!open.empty() && (open.back() == '\r' || open.back() == ' ')) open.pop_back();
+            } else {
+                open.clear();
+            }
+        }
+        if (end == std::string_view::npos) break;
+        start = end + 1;
+    }
+    return open;
+}
+
+// 在 [min_pos, limit] 范围内从后往前找分隔符;返回分隔符起点,找不到返回 npos。
+std::size_t find_break(std::string_view text, std::size_t min_pos, std::size_t limit,
+                       std::string_view separator) {
+    if (limit < separator.size()) return std::string_view::npos;
+    auto pos = text.rfind(separator, limit - separator.size());
+    if (pos == std::string_view::npos || pos < min_pos) return std::string_view::npos;
+    return pos;
+}
+
+std::string_view trim_leading_breaks(std::string_view text) {
+    std::size_t i = 0;
+    while (i < text.size() && (text[i] == '\n' || text[i] == '\r' || text[i] == ' ')) ++i;
+    return text.substr(i);
+}
+
+bool blank(std::string_view text) {
+    return std::all_of(text.begin(), text.end(),
+                       [](char c) { return c == ' ' || c == '\n' || c == '\r' || c == '\t'; });
+}
+
+} // namespace
+
+std::size_t text_units(std::string_view utf8, bool utf16) {
+    std::size_t pos = 0, used = 0;
+    while (pos < utf8.size()) {
+        const auto length = sequence_length(utf8, pos);
+        used += units_of(length, utf16);
+        pos += length;
+    }
+    return used;
+}
+
+std::vector<std::string> chunk_text(std::string_view utf8, std::size_t max_units, bool utf16) {
+    std::vector<std::string> chunks;
+    max_units = std::max<std::size_t>(max_units, 16);
+    const bool has_fences = utf8.find("```") != std::string_view::npos;
+    // 有代码块时预留闭合围栏("\n```")的空间。
+    const std::size_t budget = has_fences ? max_units - 8 : max_units;
+
+    std::string current(utf8);
+    while (!blank(current)) {
+        if (text_units(current, utf16) <= max_units) {
+            chunks.push_back(current);
+            break;
+        }
+        const std::string_view view = current;
+        const std::size_t limit = prefix_within(view, budget, utf16);
+        const std::size_t min_pos = limit / 3;
+        std::size_t cut = std::string_view::npos;
+        std::size_t skip = 0;
+        for (const std::string_view separator : {std::string_view("\n\n"), std::string_view("\n"),
+                                                 std::string_view(" ")}) {
+            const auto pos = find_break(view, min_pos, limit, separator);
+            if (pos != std::string_view::npos && pos > 0) {
+                cut = pos;
+                skip = separator.size();
+                break;
+            }
+        }
+        if (cut == std::string_view::npos) {
+            cut = std::max<std::size_t>(limit, sequence_length(view, 0));
+            skip = 0;
+        }
+        std::string chunk = current.substr(0, cut);
+        std::string next = current.substr(cut + skip);
+        std::string reopen;
+        if (has_fences) {
+            const auto fence = open_fence_at_end(chunk);
+            if (!fence.empty()) {
+                chunk += "\n```";
+                reopen = fence + "\n";
+            }
+        }
+        if (!blank(chunk)) chunks.push_back(std::move(chunk));
+        // 重开围栏会把内容加长;极小上限下若这样会让剩余文本不再缩短,就放弃重开,保证循环收敛。
+        if (!reopen.empty() && reopen.size() + next.size() < current.size()) {
+            current = reopen + next;
+        } else {
+            current = std::string(trim_leading_breaks(next));
+        }
+    }
+    return chunks;
+}
+
+} // namespace acecode::im
diff --git a/src/adapters/im/text_chunk.hpp b/src/adapters/im/text_chunk.hpp
new file mode 100644
index 000000000..459c946c9
--- /dev/null
+++ b/src/adapters/im/text_chunk.hpp
@@ -0,0 +1,22 @@
+#pragma once
+
+// IM 出站文本分段。平台单条消息有长度上限(QQ 按字符,Telegram 按 UTF-16 单位),
+// 长回答要切成多条发送。规则:
+//   - 每段不超过 max_units;绝不切断 UTF-8 字符;
+//   - 优先在段落(空行)处切,其次换行,再次空格,最后才按字符硬切;
+//   - 切点落在 ``` 代码块里时,本段末尾补上闭合围栏,下一段开头重开同语言的围栏,
+//     保证每段都是完整可渲染的 Markdown。
+
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace acecode::im {
+
+// 文本长度:utf16=false 时按 Unicode 码点计,true 时按 UTF-16 单位计(增补平面字符算 2)。
+std::size_t text_units(std::string_view utf8, bool utf16);
+
+// 返回的每段都非空;输入为空(或只有空白)时返回空列表。max_units 小于 16 时按 16 处理。
+std::vector<std::string> chunk_text(std::string_view utf8, std::size_t max_units, bool utf16);
+
+} // namespace acecode::im
diff --git a/src/adapters/im/transport.cpp b/src/adapters/im/transport.cpp
new file mode 100644
index 000000000..e6e5adaa8
--- /dev/null
+++ b/src/adapters/im/transport.cpp
@@ -0,0 +1,73 @@
+#include "transport.hpp"
+
+#include <stdexcept>
+
+namespace acecode::im {
+namespace {
+
+bool simple_id(const std::string& value, std::size_t limit) {
+    if (value.empty() || value.size() > limit) return false;
+    for (const char c : value) {
+        // 钉钉的会话 id 是 base64(含 + / =),发送人 id 形如 $:LWCP_v1:$…;都不用于文件路径。
+        const bool ok = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
+                        c == '-' || c == '_' || c == '.' || c == ':' || c == '@' || c == '+' || c == '/' ||
+                        c == '=' || c == '$';
+        if (!ok) return false;
+    }
+    return true;
+}
+
+} // namespace
+
+std::string Address::key() const {
+    nlohmann::json key = nlohmann::json::array({platform, account,
+                                                kind == ChatKind::Group ? "group" : "private", chat});
+    if (kind == ChatKind::Group) key.push_back(sender);
+    return key.dump();
+}
+
+nlohmann::json Address::to_json() const {
+    nlohmann::json value{{"platform", platform},
+                         {"account", account},
+                         {"kind", kind == ChatKind::Group ? "group" : "private"},
+                         {"chat", chat},
+                         {"sender", sender}};
+    if (!thread.empty()) value["thread"] = thread;
+    return value;
+}
+
+Address Address::from_json(const nlohmann::json& value) {
+    Address address;
+    address.platform = value.at("platform").get<std::string>();
+    address.account = value.at("account").get<std::string>();
+    const auto kind = value.at("kind").get<std::string>();
+    if (kind != "group" && kind != "private") throw std::runtime_error("Invalid channel address kind");
+    address.kind = kind == "group" ? ChatKind::Group : ChatKind::Private;
+    address.chat = value.at("chat").get<std::string>();
+    address.sender = value.at("sender").get<std::string>();
+    address.thread = value.value("thread", std::string{});
+    return address;
+}
+
+bool Address::valid() const {
+    static const char* const kPlatforms[] = {"qq", "weixin", "feishu", "dingtalk", "telegram", "discord", "line"};
+    bool known = false;
+    for (const char* name : kPlatforms) known = known || platform == name;
+    if (!known) return false;
+    if (!simple_id(account, 128) || !simple_id(chat, 128) || !simple_id(sender, 128)) return false;
+    if (!thread.empty() && !simple_id(thread, 64)) return false;
+    return kind == ChatKind::Group || chat == sender;
+}
+
+const char* link_state_name(LinkState state) {
+    switch (state) {
+        case LinkState::Stopped: return "stopped";
+        case LinkState::Connecting: return "connecting";
+        case LinkState::Connected: return "connected";
+        case LinkState::Retrying: return "retrying";
+        case LinkState::Failed: return "failed";
+    }
+    return "stopped";
+}
+
+} // namespace acecode::im
diff --git a/src/adapters/im/transport.hpp b/src/adapters/im/transport.hpp
new file mode 100644
index 000000000..01262771e
--- /dev/null
+++ b/src/adapters/im/transport.hpp
@@ -0,0 +1,129 @@
+#pragma once
+
+// IM 平台传输层的统一接口(add-desktop-im-channels D3)。
+//
+// 传输层只负责“和某个 IM 平台说话”:连接、收消息、发文字/文件、下载附件。
+// 它不认识 ACECode 会话;会话绑定、命令、授权都在 host/channels/core。
+// 平台差异(QQ 被动回复额度、Telegram 限速与 HTML 格式)全部收在各自实现内部,
+// 核心只看 Capabilities 决定如何分段与是否按回合合并。
+
+#include <nlohmann/json.hpp>
+
+#include <cstdint>
+#include <filesystem>
+#include <functional>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+namespace acecode::im {
+
+enum class ChatKind { Private, Group };
+
+// 一个 IM 会话的位置。群聊按“群 + 发言人”区分(QQ 的群成员身份按群隔离)。
+struct Address {
+    std::string platform;  // "qq" / "telegram"
+    std::string account;   // QQ AppID / Telegram 机器人 id
+    ChatKind kind = ChatKind::Private;
+    std::string chat;      // 私聊:对方 id;群聊:群 id
+    std::string sender;    // 发言人 id(私聊时与 chat 相同)
+    std::string thread;    // Telegram 话题 id,仅用于回复定位,不参与会话键
+
+    // 结构化会话键(JSON 数组字符串),用于绑定、回执和授权记录。
+    std::string key() const;
+    nlohmann::json to_json() const;
+    static Address from_json(const nlohmann::json& value);
+    bool valid() const;
+};
+
+enum class AttachmentKind { Image, File, Voice, Video, Sticker, Other };
+
+struct Attachment {
+    AttachmentKind kind = AttachmentKind::Other;
+    std::string name;
+    std::string mime_type;
+    std::uint64_t size = 0;    // 0 = 平台没有给出
+    std::string remote_ref;    // QQ 附件 url / Telegram file_id
+    std::string transcript;    // 平台给出的语音识别文字(QQ asr_refer_text)
+};
+
+struct Inbound {
+    Address address;
+    std::string message_id;
+    std::string text;           // 已去掉 @机器人 的前缀
+    bool mentioned = false;     // 群聊里是否点名机器人;私聊恒为 true
+    std::string quote_text;     // 被引用消息的文字(可空)
+    std::string sender_name;    // 展示名(可空),只用于设置页的待批准请求
+    std::string start_code;     // Telegram `/start <码>` 的参数(机主绑定码)
+    std::vector<Attachment> attachments;
+    nlohmann::json reply_context = nlohmann::json::object();  // 平台私有的回复定位信息
+};
+
+enum class LinkState { Stopped, Connecting, Connected, Retrying, Failed };
+
+const char* link_state_name(LinkState state);
+
+struct TransportStatus {
+    LinkState state = LinkState::Stopped;
+    std::string detail;          // 给用户看的原因;绝不含凭据
+    bool retry_stopped = false;  // 致命错误后不再自动重试,等用户处理
+    std::string account;         // 平台账号 id(QQ AppID / Telegram 机器人 id)
+    std::string display_name;    // 机器人名称(可空)
+    nlohmann::json extra = nlohmann::json::object();  // 平台附加信息(用户名、隐私模式、webhook…)
+};
+
+struct Capabilities {
+    std::size_t max_text_units = 4000;   // 单条文本上限
+    bool count_utf16 = false;            // true:按 UTF-16 单位计数(Telegram)
+    bool batch_turn_output = false;      // true:同一回合的助手文本先合并再发(QQ)
+    bool supports_typing = false;
+    std::uint64_t max_upload_bytes = 0;
+    std::uint64_t max_download_bytes = 0;
+};
+
+enum class SendOutcome {
+    Sent,     // 平台确认送达
+    Held,     // 暂存,等对方下一条消息时补发(QQ 主动消息被拒)
+    Failed,   // 平台明确拒绝或参数无效;不会重发
+};
+
+struct SendResult {
+    SendOutcome outcome = SendOutcome::Failed;
+    std::string error;
+    bool ok() const { return outcome != SendOutcome::Failed; }
+};
+
+struct TransportCallbacks {
+    // 在传输层自己的线程上调用;实现必须尽快返回(核心只入队)。
+    std::function<void(Inbound)> on_inbound;
+    std::function<void(const TransportStatus&)> on_status;
+};
+
+class Transport {
+public:
+    virtual ~Transport() = default;
+    virtual std::string platform() const = 0;
+    virtual Capabilities capabilities() const = 0;
+    // 非阻塞:启动内部线程后立即返回。重复调用无副作用。
+    virtual void start(TransportCallbacks callbacks) = 0;
+    // 阻塞直到内部线程全部退出;之后不再回调。
+    virtual void stop() = 0;
+    virtual TransportStatus status() const = 0;
+    // text 为 Markdown;由实现按平台格式化。reply_context 来自触发本回合的入站消息。
+    virtual SendResult send_text(const Address& to, const std::string& text,
+                                 const nlohmann::json& reply_context) = 0;
+    virtual SendResult send_file(const Address& to, const std::filesystem::path& path,
+                                 const std::string& name, const std::string& mime_type,
+                                 const nlohmann::json& reply_context) = 0;
+    virtual void set_typing(const Address& to, bool on) { (void)to; (void)on; }
+    // 把入站附件下载到 dest(完整文件路径)。超出平台或本地上限时返回 false。
+    virtual bool download(const Attachment& attachment, const std::filesystem::path& dest,
+                          std::string* error) = 0;
+    // 平台专属操作(如 Telegram 的 remove_webhook)。未知操作抛 std::runtime_error。
+    virtual nlohmann::json action(const std::string& name, const nlohmann::json& args) {
+        (void)args;
+        throw std::runtime_error("Unsupported channel action: " + name);
+    }
+};
+
+} // namespace acecode::im
diff --git a/src/adapters/im/weixin/weixin_api.cpp b/src/adapters/im/weixin/weixin_api.cpp
new file mode 100644
index 000000000..e0bbb1993
--- /dev/null
+++ b/src/adapters/im/weixin/weixin_api.cpp
@@ -0,0 +1,191 @@
+#include "weixin_api.hpp"
+
+#include "im/redact.hpp"
+#include "platform/crypto/secure_random.hpp"
+
+
+#include <algorithm>
+#include <random>
+
+namespace acecode::im::weixin {
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+std::uint32_t random_uin() {
+    const auto bytes = platform::secure_random_bytes(4);
+    if (bytes.size() == 4) {
+        return (static_cast<std::uint32_t>(static_cast<unsigned char>(bytes[0])) << 24) |
+               (static_cast<std::uint32_t>(static_cast<unsigned char>(bytes[1])) << 16) |
+               (static_cast<std::uint32_t>(static_cast<unsigned char>(bytes[2])) << 8) |
+               static_cast<std::uint32_t>(static_cast<unsigned char>(bytes[3]));
+    }
+    // 这个值不是凭据(平台只要求它是随机数),系统随机源不可用时退回普通随机数即可。
+    std::random_device device;
+    return static_cast<std::uint32_t>(device());
+}
+
+ApiResult interpret(const HttpResponse& response, Clock::duration elapsed, std::chrono::milliseconds timeout,
+                    const std::vector<std::string>& secrets) {
+    ApiResult result;
+    result.status = response.status;
+    result.cancelled = response.cancelled;
+    if (response.cancelled) {
+        result.error = "请求已取消";
+        return result;
+    }
+    if (response.status == 0) {
+        const auto margin = std::chrono::milliseconds(1000);
+        result.timed_out = timeout > margin && elapsed >= timeout - margin;
+        const auto detail = redact_secrets(response.error, secrets);
+        result.error = detail.empty() ? std::string("无法连接微信服务器") : "无法连接微信服务器:" + detail;
+        return result;
+    }
+    const auto envelope = parse_envelope(response.body);
+    if (response.status < 200 || response.status >= 300) {
+        result.error = "微信服务器返回 HTTP " + std::to_string(response.status);
+        return result;
+    }
+    if (!envelope.parsed) {
+        result.error = "微信返回了无效数据";
+        return result;
+    }
+    result.ret = envelope.ret;
+    result.errcode = envelope.errcode;
+    result.errmsg = redact_secrets(envelope.errmsg, secrets);
+    if (envelope_failed(envelope)) {
+        result.session_expired = is_session_expired(envelope.ret, envelope.errcode, envelope.errmsg);
+        result.rate_limited = is_rate_limited(envelope.ret, envelope.errcode, envelope.errmsg);
+        if (result.session_expired) {
+            result.error = kSessionExpiredText;
+        } else if (result.rate_limited) {
+            result.error = "微信发送过于频繁,请稍后再试";
+        } else {
+            const int code = envelope.errcode != 0 ? envelope.errcode : envelope.ret;
+            result.error = "微信拒绝了请求(错误码 " + std::to_string(code) +
+                           (result.errmsg.empty() ? std::string{} : ":" + result.errmsg) + ")";
+        }
+        return result;
+    }
+    result.ok = true;
+    result.body = envelope.body;
+    return result;
+}
+
+std::vector<std::pair<std::string, std::string>> common_headers(const std::string& channel_version) {
+    return {{"iLink-App-Id", kAppId},
+            {"iLink-App-ClientVersion", std::to_string(client_version_number(channel_version))}};
+}
+
+} // namespace
+
+Api::Api(ApiOptions options) : options_(std::move(options)) {
+    if (options_.base_url.empty()) options_.base_url = kApiBase;
+    if (options_.cdn_base.empty()) options_.cdn_base = kCdnBase;
+    if (options_.channel_version.empty()) options_.channel_version = kChannelVersion;
+}
+
+std::vector<std::pair<std::string, std::string>> Api::headers() const {
+    auto headers = common_headers(options_.channel_version);
+    headers.emplace_back("Content-Type", "application/json");
+    headers.emplace_back("AuthorizationType", "ilink_bot_token");
+    headers.emplace_back("X-WECHAT-UIN", wechat_uin(random_uin()));
+    if (!options_.token.empty()) headers.emplace_back("Authorization", "Bearer " + options_.token);
+    return headers;
+}
+
+ApiResult Api::post(const std::string& endpoint, nlohmann::json body, std::chrono::milliseconds timeout,
+                    std::function<bool()> cancel) const {
+    if (!body.is_object()) body = nlohmann::json::object();
+    nlohmann::json base_info{{"channel_version", options_.channel_version}};
+    if (!options_.bot_agent.empty()) base_info["bot_agent"] = options_.bot_agent;
+    body["base_info"] = std::move(base_info);
+
+    HttpRequest request;
+    request.method = "POST";
+    request.url = join_url(options_.base_url, endpoint);
+    request.headers = headers();
+    request.body = body.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace);
+    request.timeout = timeout;
+    request.use_proxy = options_.use_proxy;
+    request.cancel = std::move(cancel);
+    const auto started = Clock::now();
+    const auto response = http_send(request);
+    return interpret(response, Clock::now() - started, timeout, {options_.token});
+}
+
+ApiResult get_unauthenticated(const std::string& url, const std::string& channel_version, bool use_proxy,
+                              std::chrono::milliseconds timeout, std::function<bool()> cancel) {
+    HttpRequest request;
+    request.url = url;
+    request.headers = common_headers(channel_version.empty() ? std::string(kChannelVersion) : channel_version);
+    request.timeout = timeout;
+    request.use_proxy = use_proxy;
+    request.cancel = std::move(cancel);
+    const auto started = Clock::now();
+    const auto response = http_send(request);
+    return interpret(response, Clock::now() - started, timeout, {});
+}
+
+// CDN 上传的结果只在响应头 x-encrypted-param 里(im::http_send 的响应头键已转小写)。
+CdnUploadResult cdn_upload(const std::string& url, const std::string& ciphertext, bool use_proxy,
+                           std::chrono::milliseconds timeout) {
+    CdnUploadResult result;
+    HttpRequest request;
+    request.method = "POST";
+    request.url = url;
+    request.headers = {{"Content-Type", "application/octet-stream"}};
+    request.body = ciphertext;
+    request.timeout = timeout;
+    request.use_proxy = use_proxy;
+    const auto response = http_send(request);
+    result.status = response.status;
+    if (response.status == 0) {
+        result.retryable = true;
+        result.error = response.error.empty() ? std::string("上传文件失败:无法连接微信文件服务器")
+                                              : "上传文件失败:" + response.error;
+        return result;
+    }
+    const auto header_value = [&response](const char* name) {
+        const auto it = response.headers.find(name);
+        return it == response.headers.end() ? std::string{} : it->second;
+    };
+    if (response.status != 200) {
+        result.retryable = response.status >= 500;
+        const auto detail = redact_secrets(header_value("x-error-message"));
+        result.error = "上传文件失败:HTTP " + std::to_string(response.status) +
+                       (detail.empty() ? std::string{} : "(" + detail + ")");
+        return result;
+    }
+    result.encrypted_param = header_value("x-encrypted-param");
+    if (result.encrypted_param.empty()) {
+        const auto detail = redact_secrets(header_value("x-error-message"));
+        result.error = detail.empty() ? std::string("上传文件失败:文件服务器没有返回文件标识")
+                                      : "上传文件失败:" + detail;
+        return result;
+    }
+    result.ok = true;
+    return result;
+}
+
+SessionCheck check_session(const ApiOptions& options, const std::string& user_id, std::chrono::milliseconds timeout) {
+    SessionCheck check;
+    if (options.token.empty()) {
+        check.state = SessionState::Expired;
+        check.error = "缺少微信登录凭据,请在设置页扫码登录";
+        return check;
+    }
+    const auto result = Api(options).post(kEpGetConfig, {{"ilink_user_id", user_id}}, timeout);
+    if (result.ok) {
+        check.state = SessionState::Valid;
+    } else if (result.session_expired) {
+        check.state = SessionState::Expired;
+        check.error = kSessionExpiredText;
+    } else {
+        check.state = SessionState::Unknown;
+        check.error = result.error;
+    }
+    return check;
+}
+
+} // namespace acecode::im::weixin
diff --git a/src/adapters/im/weixin/weixin_api.hpp b/src/adapters/im/weixin/weixin_api.hpp
new file mode 100644
index 000000000..c6f214312
--- /dev/null
+++ b/src/adapters/im/weixin/weixin_api.hpp
@@ -0,0 +1,90 @@
+#pragma once
+
+// 微信 iLink HTTP 客户端。
+//
+// 鉴权请求一律 POST JSON:请求头带 AuthorizationType / X-WECHAT-UIN(每次随机)/ iLink-App-Id /
+// iLink-App-ClientVersion / Authorization: Bearer <bot_token>,请求体顶层并入
+// base_info.channel_version。响应 Content-Type 是 application/octet-stream,一律按 JSON 解析;
+// 应用层错误是 HTTP 200 + ret/errcode 非 0(可能只有 errcode 没有 ret)。
+// bot_token 只出现在请求头里,所有错误文本都会脱敏。
+
+#include "im/http.hpp"
+#include "im/weixin/weixin_protocol.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <functional>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace acecode::im::weixin {
+
+struct ApiOptions {
+    std::string token;                 // bot_token(扫码登录得到)
+    std::string base_url = kApiBase;   // 扫码确认返回的 baseurl
+    std::string cdn_base = kCdnBase;   // 媒体 CDN
+    bool use_proxy = true;
+    std::string channel_version = kChannelVersion;
+    std::string bot_agent;             // 非空时随 base_info 上报(仅供平台观测,不参与鉴权)
+};
+
+struct ApiResult {
+    bool ok = false;
+    long status = 0;               // HTTP 状态码;0 = 没拿到响应
+    int ret = 0;
+    int errcode = 0;
+    std::string errmsg;            // 平台原文(已脱敏),只用于日志
+    std::string error;             // 给用户看的中文原因(已脱敏)
+    nlohmann::json body = nlohmann::json::object();
+    bool cancelled = false;
+    bool timed_out = false;        // 客户端等到超时(长轮询的正常现象)
+    bool session_expired = false;  // -14 等:机器人登录已失效
+    bool rate_limited = false;     // -2 限频
+};
+
+class Api {
+public:
+    explicit Api(ApiOptions options);
+
+    // endpoint 是相对路径(如 kEpGetUpdates);body 会被并入 base_info。
+    ApiResult post(const std::string& endpoint, nlohmann::json body, std::chrono::milliseconds timeout,
+                   std::function<bool()> cancel = {}) const;
+    const ApiOptions& options() const { return options_; }
+
+private:
+    std::vector<std::pair<std::string, std::string>> headers() const;
+
+    ApiOptions options_;
+};
+
+// 扫码相关的未鉴权 GET:只带 iLink-App-Id 与 iLink-App-ClientVersion。
+ApiResult get_unauthenticated(const std::string& url, const std::string& channel_version, bool use_proxy,
+                              std::chrono::milliseconds timeout, std::function<bool()> cancel = {});
+
+// 把加密后的媒体 POST 到 CDN(必须是 POST,PUT 会 404)。成功 = HTTP 200 且响应头带
+// x-encrypted-param(之后作为该文件的 encrypt_query_param 发出去)。
+struct CdnUploadResult {
+    bool ok = false;
+    bool retryable = false;        // 网络错误或 5xx;4xx 不重试
+    long status = 0;
+    std::string encrypted_param;
+    std::string error;             // 中文,已脱敏
+};
+
+CdnUploadResult cdn_upload(const std::string& url, const std::string& ciphertext, bool use_proxy,
+                           std::chrono::milliseconds timeout);
+
+// 可选的登录状态检查:以 getconfig 探测 bot_token 是否仍有效(不会消耗消息、不移动游标)。
+enum class SessionState { Valid, Expired, Unknown };
+
+struct SessionCheck {
+    SessionState state = SessionState::Unknown;
+    std::string error;  // 中文;Valid 时为空
+};
+
+SessionCheck check_session(const ApiOptions& options, const std::string& user_id,
+                           std::chrono::milliseconds timeout = std::chrono::seconds(10));
+
+} // namespace acecode::im::weixin
diff --git a/src/adapters/im/weixin/weixin_login.cpp b/src/adapters/im/weixin/weixin_login.cpp
new file mode 100644
index 000000000..891f273e1
--- /dev/null
+++ b/src/adapters/im/weixin/weixin_login.cpp
@@ -0,0 +1,153 @@
+#include "weixin_login.hpp"
+
+#include "im/weixin/weixin_api.hpp"
+#include "utils/logger.hpp"
+
+#include <thread>
+
+namespace acecode::im::weixin {
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+// 等待 duration;期间每 50ms 检查一次取消。返回 false 表示被取消。
+bool wait_or_cancel(std::chrono::milliseconds duration, const std::atomic<bool>& cancelled) {
+    const auto until = Clock::now() + duration;
+    while (Clock::now() < until) {
+        if (cancelled) return false;
+        std::this_thread::sleep_for((std::min<std::chrono::milliseconds>)(
+            std::chrono::milliseconds(50), std::chrono::duration_cast<std::chrono::milliseconds>(until - Clock::now())));
+    }
+    return !cancelled;
+}
+
+std::chrono::milliseconds bounded(std::chrono::milliseconds wanted, Clock::time_point deadline) {
+    const auto remaining = std::chrono::duration_cast<std::chrono::milliseconds>(deadline - Clock::now());
+    if (remaining < std::chrono::milliseconds(1000)) return std::chrono::milliseconds(1000);
+    return (std::min)(wanted, remaining);
+}
+
+std::string string_field(const nlohmann::json& body, const char* key) {
+    if (!body.is_object() || !body.contains(key) || !body[key].is_string()) return {};
+    return body[key].get<std::string>();
+}
+
+std::string normalized_base(const std::string& value, const std::string& fallback) {
+    std::string base = value;
+    while (!base.empty() && base.back() == '/') base.pop_back();
+    if (base.rfind("https://", 0) == 0 || base.rfind("http://", 0) == 0) return base;
+    return fallback;
+}
+
+LoginResult finish(LoginPhase phase, int refreshes, std::string error = {}) {
+    LoginResult result;
+    result.phase = phase;
+    result.refreshes = refreshes;
+    result.error = std::move(error);
+    return result;
+}
+
+} // namespace
+
+const char* login_phase_name(LoginPhase phase) {
+    switch (phase) {
+        case LoginPhase::WaitingScan: return "waiting";
+        case LoginPhase::Scanned: return "scanned";
+        case LoginPhase::Completed: return "completed";
+        case LoginPhase::Failed: return "failed";
+        case LoginPhase::Cancelled: return "cancelled";
+        case LoginPhase::TimedOut: return "timed_out";
+    }
+    return "failed";
+}
+
+LoginResult run_login(const LoginOptions& options, const std::atomic<bool>& cancelled,
+                      const LoginProgressFn& progress) {
+    const auto deadline = Clock::now() + options.total_timeout;
+    const std::function<bool()> cancel = [&cancelled] { return cancelled.load(); };
+    const auto api_base = normalized_base(options.api_base, kApiBase);
+    int refreshes = 0;
+    while (true) {
+        if (cancelled) return finish(LoginPhase::Cancelled, refreshes);
+        if (Clock::now() >= deadline) return finish(LoginPhase::TimedOut, refreshes);
+
+        // 二维码一律从默认地址申请(换码时也不沿用上一张的重定向地址)。
+        const auto qr = get_unauthenticated(join_url(api_base, kEpGetBotQr) + "?bot_type=" + kBotType,
+                                            options.channel_version, options.use_proxy,
+                                            bounded(options.qr_timeout, deadline), cancel);
+        if (cancelled) return finish(LoginPhase::Cancelled, refreshes);
+        if (!qr.ok) return finish(LoginPhase::Failed, refreshes, "获取微信二维码失败:" + qr.error);
+        const auto qrcode = string_field(qr.body, "qrcode");
+        if (qrcode.empty()) return finish(LoginPhase::Failed, refreshes, "获取微信二维码失败:返回内容缺少二维码");
+        const auto image = string_field(qr.body, "qrcode_img_content");
+        LoginProgress shown;
+        shown.phase = LoginPhase::WaitingScan;
+        shown.qr_url = image.empty() ? qrcode : image;
+        shown.refreshes = refreshes;
+        LOG_INFO("[channels/weixin] login QR issued (refreshes=" + std::to_string(refreshes) + ")");
+        if (progress) progress(shown);
+
+        auto poll_base = api_base;
+        bool scanned = false;
+        bool expired = false;
+        while (!expired) {
+            if (cancelled) return finish(LoginPhase::Cancelled, refreshes);
+            if (Clock::now() >= deadline) return finish(LoginPhase::TimedOut, refreshes);
+            const auto polled = get_unauthenticated(
+                join_url(poll_base, kEpGetQrStatus) + "?qrcode=" + url_encode(qrcode), options.channel_version,
+                options.use_proxy, bounded(options.status_timeout, deadline), cancel);
+            if (cancelled) return finish(LoginPhase::Cancelled, refreshes);
+            // 客户端超时、网络抖动、平台临时错误都按“继续等待”处理(与 hermes / 官方插件一致)。
+            const auto status = polled.ok ? string_field(polled.body, "status") : std::string("wait");
+            if (status == "scaned" || status == "scaned_but_redirect") {
+                if (status == "scaned_but_redirect") {
+                    const auto host = string_field(polled.body, "redirect_host");
+                    if (!host.empty()) {
+                        poll_base = options.redirect_scheme + "://" + host;
+                        LOG_INFO("[channels/weixin] login status polling switched to a redirected host");
+                    }
+                }
+                if (!scanned) {
+                    scanned = true;
+                    LOG_INFO("[channels/weixin] login QR scanned, waiting for confirmation");
+                    LoginProgress step = shown;
+                    step.phase = LoginPhase::Scanned;
+                    if (progress) progress(step);
+                }
+            } else if (status == "need_verifycode" || status == "verify_code_blocked") {
+                LOG_WARN("[channels/weixin] login requires a verification code, which is not supported");
+                return finish(LoginPhase::Failed, refreshes,
+                              "微信要求输入手机上显示的验证数字,ACECode 暂不支持这种确认方式,请稍后重新扫码");
+            } else if (status == "binded_redirect") {
+                LOG_WARN("[channels/weixin] login answered binded_redirect without credentials");
+                return finish(LoginPhase::Failed, refreshes, "微信提示该账号已连接过,但没有下发新的凭据,请稍后重新扫码");
+            } else if (status == "expired") {
+                ++refreshes;
+                if (refreshes > options.max_refreshes)
+                    return finish(LoginPhase::Failed, refreshes, "二维码多次过期,请重新开始扫码");
+                LOG_INFO("[channels/weixin] login QR expired, requesting a fresh one");
+                expired = true;
+                continue;
+            } else if (status == "confirmed") {
+                LoginResult done;
+                done.refreshes = refreshes;
+                done.bot_token = string_field(polled.body, "bot_token");
+                done.bot_id = id_string(polled.body.value("ilink_bot_id", nlohmann::json()));
+                done.user_id = id_string(polled.body.value("ilink_user_id", nlohmann::json()));
+                done.base_url = normalized_base(string_field(polled.body, "baseurl"), api_base);
+                if (done.bot_token.empty() || done.bot_id.empty() || !valid_id(done.bot_id)) {
+                    LOG_WARN("[channels/weixin] login confirmed without usable credentials");
+                    return finish(LoginPhase::Failed, refreshes, "扫码结果缺少机器人凭据,请重新扫码");
+                }
+                if (!done.user_id.empty() && !valid_id(done.user_id)) done.user_id.clear();
+                done.phase = LoginPhase::Completed;
+                LOG_INFO("[channels/weixin] login confirmed");
+                return done;
+            }
+            // wait 与未知状态:间隔后继续轮询。
+            if (!wait_or_cancel(options.poll_interval, cancelled)) return finish(LoginPhase::Cancelled, refreshes);
+        }
+    }
+}
+
+} // namespace acecode::im::weixin
diff --git a/src/adapters/im/weixin/weixin_login.hpp b/src/adapters/im/weixin/weixin_login.hpp
new file mode 100644
index 000000000..e087554b5
--- /dev/null
+++ b/src/adapters/im/weixin/weixin_login.hpp
@@ -0,0 +1,64 @@
+#pragma once
+
+// 微信 iLink 扫码登录(微信 ClawBot)。流程按 hermes-agent 验证过的 2.2.0 版本:
+//   1. GET {api}/ilink/bot/get_bot_qrcode?bot_type=3 → {qrcode, qrcode_img_content}
+//      二维码要编码 qrcode_img_content(liteapp 网址),不是 32 位的 qrcode 令牌。
+//   2. GET {base}/ilink/bot/get_qrcode_status?qrcode=<令牌>,服务端挂起约 30 秒:
+//      wait 继续等;scaned 已扫码待确认;scaned_but_redirect 换到 https://{redirect_host} 继续轮询
+//      同一个令牌;expired 换一张新二维码(从默认地址重新申请);confirmed 带回凭据。
+//      新版协议的 need_verifycode / verify_code_blocked / binded_redirect 不支持,直接失败并说明。
+//   3. confirmed:bot_token(之后所有请求的 Bearer)、ilink_bot_id(机器人账号)、baseurl
+//      (之后的接口地址)、ilink_user_id(扫码人,即机主)。
+// 二维码内容与 bot_token 绝不写日志。
+
+#include "im/weixin/weixin_protocol.hpp"
+
+#include <atomic>
+#include <chrono>
+#include <functional>
+#include <string>
+
+namespace acecode::im::weixin {
+
+enum class LoginPhase { WaitingScan, Scanned, Completed, Failed, Cancelled, TimedOut };
+
+// "waiting" / "scanned" / "completed" / "failed" / "cancelled" / "timed_out"
+const char* login_phase_name(LoginPhase phase);
+
+struct LoginProgress {
+    LoginPhase phase = LoginPhase::WaitingScan;  // WaitingScan:新二维码;Scanned:已扫码,等手机上确认
+    std::string qr_url;                           // 要渲染成二维码的内容(qrcode_img_content)
+    int refreshes = 0;                            // 因过期自动换码的次数
+};
+
+struct LoginResult {
+    LoginPhase phase = LoginPhase::Failed;  // Completed / Failed / Cancelled / TimedOut
+    std::string error;                      // Failed:中文原因,不含凭据
+    std::string bot_token;                  // Completed:只交给保存逻辑,不得展示或记录
+    std::string bot_id;                     // Completed:ilink_bot_id(Address::account)
+    std::string base_url;                   // Completed:之后使用的接口地址
+    std::string user_id;                    // Completed:扫码人的 ilink_user_id(可能为空)
+    int refreshes = 0;
+};
+
+struct LoginOptions {
+    std::string api_base = kApiBase;  // 申请二维码与默认轮询地址
+    bool use_proxy = true;
+    std::chrono::milliseconds poll_interval{std::chrono::seconds(1)};  // 每次状态应答后的间隔
+    std::chrono::milliseconds total_timeout{std::chrono::minutes(10)};
+    std::chrono::milliseconds qr_timeout{std::chrono::seconds(35)};
+    std::chrono::milliseconds status_timeout{std::chrono::seconds(35)};  // 状态长轮询的客户端超时
+    // 二维码过期后最多自动换几次(10 分钟内最多 6 张);超过则失败。
+    int max_refreshes = 5;
+    std::string redirect_scheme = "https";  // scaned_but_redirect 的新地址协议(测试用 http)
+    std::string channel_version = kChannelVersion;
+};
+
+using LoginProgressFn = std::function<void(const LoginProgress&)>;
+
+// 同步执行完整扫码流程,由调用方放到后台线程。显示或刷新二维码时回调一次 WaitingScan,
+// 首次扫码时回调一次 Scanned(qr_url 不变)。cancelled 置位后约 1 秒内返回 Cancelled。
+LoginResult run_login(const LoginOptions& options, const std::atomic<bool>& cancelled,
+                      const LoginProgressFn& progress);
+
+} // namespace acecode::im::weixin
diff --git a/src/adapters/im/weixin/weixin_media.cpp b/src/adapters/im/weixin/weixin_media.cpp
new file mode 100644
index 000000000..51dd87d83
--- /dev/null
+++ b/src/adapters/im/weixin/weixin_media.cpp
@@ -0,0 +1,197 @@
+#include "weixin_media.hpp"
+
+#include "im/http.hpp"
+#include "im/redact.hpp"
+#include "platform/crypto/aes_ecb.hpp"
+#include "platform/crypto/digest.hpp"
+#include "platform/crypto/secure_random.hpp"
+
+#include <fstream>
+#include <iterator>
+
+namespace acecode::im::weixin {
+namespace {
+
+std::string trim(const std::string& text) {
+    const auto begin = text.find_first_not_of(" \t\r\n");
+    if (begin == std::string::npos) return {};
+    const auto end = text.find_last_not_of(" \t\r\n");
+    return text.substr(begin, end - begin + 1);
+}
+
+void remove_quietly(const std::filesystem::path& path) {
+    std::error_code ec;
+    std::filesystem::remove(path, ec);
+}
+
+} // namespace
+
+std::string size_label(std::uint64_t bytes) {
+    constexpr std::uint64_t kMiB = 1024u * 1024u;
+    if (bytes >= kMiB) return std::to_string(bytes / kMiB) + " MB";
+    return std::to_string((bytes + 1023u) / 1024u) + " KB";
+}
+
+bool decrypt_media(const std::string& key, const std::string& ciphertext, std::string& plaintext,
+                   std::string* error) {
+    plaintext.clear();
+    if (key.size() != 16) {
+        if (error) *error = "附件密钥格式无法识别";
+        return false;
+    }
+    if (ciphertext.empty()) return true;
+    if (ciphertext.size() % 16 != 0) {
+        if (error) *error = "附件内容不完整,无法解密";
+        return false;
+    }
+    // ECB 的每个块独立:在末尾补一个“整块填充”的密文块,平台库按严格 PKCS#7 只会去掉这一块,
+    // 原文最后的填充留给下面的宽松规则处理(平台偶尔给出不规范的填充,不能因此丢文件)。
+    std::string pad_block;
+    if (!platform::aes_128_ecb_encrypt(key, std::string{}, pad_block, nullptr) || pad_block.size() != 16) {
+        if (error) *error = "附件解密失败";
+        return false;
+    }
+    std::string raw;
+    if (!platform::aes_128_ecb_decrypt(key, ciphertext + pad_block, raw, nullptr)) {
+        if (error) *error = "附件解密失败";
+        return false;
+    }
+    plaintext = strip_pkcs7_lenient(std::move(raw));
+    return true;
+}
+
+bool prepare_upload(const std::string& plaintext, PreparedUpload& out, std::string* error) {
+    out = PreparedUpload{};
+    const auto filekey = platform::secure_random_bytes(16);
+    out.aes_key = platform::secure_random_bytes(16);
+    const auto digest = platform::md5_digest(plaintext);
+    if (filekey.size() != 16 || out.aes_key.size() != 16 || digest.size() != 16) {
+        if (error) *error = "无法生成上传所需的随机密钥";
+        return false;
+    }
+    out.filekey = platform::to_hex(filekey);
+    out.md5_hex = platform::to_hex(digest);
+    out.raw_size = plaintext.size();
+    if (!platform::aes_128_ecb_encrypt(out.aes_key, plaintext, out.ciphertext, nullptr) ||
+        out.ciphertext.size() != platform::aes_128_ecb_padded_size(plaintext.size())) {
+        if (error) *error = "文件加密失败";
+        return false;
+    }
+    return true;
+}
+
+nlohmann::json upload_url_request(const PreparedUpload& upload, UploadMediaType type, const std::string& peer) {
+    return {{"filekey", upload.filekey},
+            {"media_type", static_cast<int>(type)},
+            {"to_user_id", peer},
+            {"rawsize", upload.raw_size},
+            {"rawfilemd5", upload.md5_hex},
+            {"filesize", upload.ciphertext.size()},
+            {"no_need_thumb", true},
+            {"aeskey", platform::to_hex(upload.aes_key)}};
+}
+
+std::string upload_target(const nlohmann::json& response, const std::string& cdn_base, const std::string& filekey) {
+    if (!response.is_object()) return {};
+    const auto full = response.contains("upload_full_url") && response["upload_full_url"].is_string()
+                          ? trim(response["upload_full_url"].get<std::string>())
+                          : std::string{};
+    if (!full.empty()) return full;
+    const auto param = response.contains("upload_param") && response["upload_param"].is_string()
+                           ? response["upload_param"].get<std::string>()
+                           : std::string{};
+    if (param.empty()) return {};
+    return cdn_upload_url(cdn_base, param, filekey);
+}
+
+std::chrono::milliseconds download_timeout(const std::string& kind) {
+    if (kind == "image") return std::chrono::seconds(30);
+    if (kind == "video") return std::chrono::seconds(120);
+    return std::chrono::seconds(60);
+}
+
+bool read_whole_file(const std::filesystem::path& path, std::uint64_t limit, std::string& data, std::string* error) {
+    data.clear();
+    std::error_code ec;
+    const auto size = std::filesystem::file_size(path, ec);
+    if (ec) {
+        if (error) *error = "文件不存在或不可读";
+        return false;
+    }
+    if (limit && size > limit) {
+        if (error) *error = "文件超过微信 " + size_label(limit) + " 上限";
+        return false;
+    }
+    std::ifstream in(path, std::ios::binary);
+    if (!in) {
+        if (error) *error = "文件不存在或不可读";
+        return false;
+    }
+    data.assign(std::istreambuf_iterator<char>(in), std::istreambuf_iterator<char>());
+    return true;
+}
+
+bool download_media(const ApiOptions& options, const MediaRef& ref, const std::filesystem::path& dest,
+                    std::uint64_t max_bytes, std::string* error) {
+    if (ref.key_invalid) {
+        if (error) *error = "附件密钥格式无法识别";
+        return false;
+    }
+    std::string url;
+    if (!ref.query_param.empty()) {
+        url = cdn_download_url(options.cdn_base, ref.query_param);
+    } else if (media_host_allowed(ref.full_url, options.cdn_base)) {
+        url = ref.full_url;
+    } else {
+        if (error) *error = "附件下载地址不是微信的域名,已拒绝";
+        return false;
+    }
+    auto temp = dest;
+    temp += ".wxdl";
+    HttpRequest request;
+    request.url = url;
+    request.timeout = download_timeout(ref.kind);
+    request.use_proxy = options.use_proxy;
+    request.download_to = temp;
+    // 密文比明文多出至多 16 字节的填充。
+    request.max_download_bytes = max_bytes ? max_bytes + (ref.aes_key.empty() ? 0 : 16) : 0;
+    const auto response = http_send(request);
+    if (response.too_large) {
+        remove_quietly(temp);
+        if (error) *error = "文件超过微信 " + size_label(max_bytes) + " 下载上限";
+        return false;
+    }
+    if (response.status < 200 || response.status >= 300) {
+        remove_quietly(temp);
+        if (error) {
+            *error = response.status == 0 ? (response.error.empty() ? std::string("下载微信文件失败:无法连接文件服务器")
+                                                                    : "下载微信文件失败:" + redact_secrets(response.error))
+                                          : "下载微信文件失败:HTTP " + std::to_string(response.status);
+        }
+        return false;
+    }
+    std::string data;
+    const bool read = read_whole_file(temp, 0, data, error);
+    remove_quietly(temp);
+    if (!read) return false;
+    std::string plaintext;
+    if (ref.aes_key.empty()) {
+        plaintext = std::move(data);
+    } else if (!decrypt_media(ref.aes_key, data, plaintext, error)) {
+        return false;
+    }
+    if (max_bytes && plaintext.size() > max_bytes) {
+        if (error) *error = "文件超过微信 " + size_label(max_bytes) + " 下载上限";
+        return false;
+    }
+    std::ofstream out(dest, std::ios::binary | std::ios::trunc);
+    if (!out || !out.write(plaintext.data(), static_cast<std::streamsize>(plaintext.size()))) {
+        out.close();
+        remove_quietly(dest);
+        if (error) *error = "无法保存下载的文件";
+        return false;
+    }
+    return true;
+}
+
+} // namespace acecode::im::weixin
diff --git a/src/adapters/im/weixin/weixin_media.hpp b/src/adapters/im/weixin/weixin_media.hpp
new file mode 100644
index 000000000..bb2f98160
--- /dev/null
+++ b/src/adapters/im/weixin/weixin_media.hpp
@@ -0,0 +1,57 @@
+#pragma once
+
+// 微信 iLink 媒体:CDN 上的文件内容一律 AES-128-ECB + PKCS#7 加密。
+//
+//   入站:按 encrypt_query_param(或白名单内的 full_url)下载密文 → 用消息里给的密钥解密;
+//         去填充采用宽松规则(填充不合法时原样保留,与 hermes / 官方插件一致)。
+//   出站:随机 16 字节密钥与 filekey → getuploadurl 拿上传参数 → POST 密文到 CDN →
+//         响应头 x-encrypted-param 作为该文件的 encrypt_query_param 发出。
+// 密钥、文件内容都不写日志。
+
+#include "im/weixin/weixin_api.hpp"
+#include "im/weixin/weixin_protocol.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <filesystem>
+#include <string>
+
+namespace acecode::im::weixin {
+
+// 解密 CDN 下载的密文。密文长度必须是 16 的倍数;空密文得到空明文。
+bool decrypt_media(const std::string& key, const std::string& ciphertext, std::string& plaintext,
+                   std::string* error);
+
+struct PreparedUpload {
+    std::string filekey;      // 32 个小写十六进制字符
+    std::string aes_key;      // 16 字节原始密钥
+    std::string md5_hex;      // 明文 MD5(小写十六进制)
+    std::uint64_t raw_size = 0;
+    std::string ciphertext;   // 长度 = PKCS#7 填充后的长度
+};
+
+// 生成一次性密钥与 filekey 并加密内容。
+bool prepare_upload(const std::string& plaintext, PreparedUpload& out, std::string* error);
+
+// getuploadurl 的请求体(base_info 由 Api 补上)。
+nlohmann::json upload_url_request(const PreparedUpload& upload, UploadMediaType type, const std::string& peer);
+// 从 getuploadurl 的响应确定上传地址:优先 upload_full_url,否则用 upload_param 拼 CDN 地址;
+// 两者都没有时返回空串。
+std::string upload_target(const nlohmann::json& response, const std::string& cdn_base, const std::string& filekey);
+
+// 各类媒体的下载超时(图片 30 秒,文件/语音 60 秒,视频 120 秒)。
+std::chrono::milliseconds download_timeout(const std::string& kind);
+
+// 下载并解密到 dest;明文超过 max_bytes 时失败并删除半截文件。error 为中文一句话。
+bool download_media(const ApiOptions& options, const MediaRef& ref, const std::filesystem::path& dest,
+                    std::uint64_t max_bytes, std::string* error);
+
+// 给用户看的大小:不足 1 MB 时按 KB 显示(如 "50 MB"、"512 KB")。
+std::string size_label(std::uint64_t bytes);
+
+// 整读文件;超过 limit 时失败(limit 为 0 表示不限)。
+bool read_whole_file(const std::filesystem::path& path, std::uint64_t limit, std::string& data, std::string* error);
+
+} // namespace acecode::im::weixin
diff --git a/src/adapters/im/weixin/weixin_protocol.cpp b/src/adapters/im/weixin/weixin_protocol.cpp
new file mode 100644
index 000000000..0164a5456
--- /dev/null
+++ b/src/adapters/im/weixin/weixin_protocol.cpp
@@ -0,0 +1,632 @@
+#include "weixin_protocol.hpp"
+
+#include "im/text_chunk.hpp"
+#include "platform/crypto/digest.hpp"
+#include "utils/base64.hpp"
+
+#include <algorithm>
+#include <cctype>
+#include <limits>
+
+namespace acecode::im::weixin {
+namespace {
+
+std::string lower(std::string text) {
+    std::transform(text.begin(), text.end(), text.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return text;
+}
+
+std::string trim(const std::string& text) {
+    std::size_t b = 0, e = text.size();
+    while (b < e && std::isspace(static_cast<unsigned char>(text[b]))) ++b;
+    while (e > b && std::isspace(static_cast<unsigned char>(text[e - 1]))) --e;
+    return text.substr(b, e - b);
+}
+
+bool ends_with(const std::string& text, const std::string& suffix) {
+    return text.size() >= suffix.size() && text.compare(text.size() - suffix.size(), suffix.size(), suffix) == 0;
+}
+
+std::string string_field(const nlohmann::json& object, const char* key) {
+    if (!object.is_object() || !object.contains(key) || !object[key].is_string()) return {};
+    return object[key].get<std::string>();
+}
+
+const nlohmann::json& object_field(const nlohmann::json& object, const char* key) {
+    static const nlohmann::json kEmpty = nlohmann::json::object();
+    if (!object.is_object() || !object.contains(key) || !object[key].is_object()) return kEmpty;
+    return object[key];
+}
+
+std::int64_t int64_field(const nlohmann::json& object, const char* key) {
+    if (!object.is_object() || !object.contains(key)) return 0;
+    const auto& value = object[key];
+    if (value.is_number_unsigned()) {
+        const auto v = value.get<std::uint64_t>();
+        return v > static_cast<std::uint64_t>((std::numeric_limits<std::int64_t>::max)())
+                   ? (std::numeric_limits<std::int64_t>::max)()
+                   : static_cast<std::int64_t>(v);
+    }
+    if (value.is_number_integer()) return value.get<std::int64_t>();
+    if (value.is_string()) {
+        try {
+            std::size_t used = 0;
+            const auto text = value.get<std::string>();
+            const auto v = std::stoll(text, &used);
+            return used == text.size() ? v : 0;
+        } catch (...) {
+            return 0;
+        }
+    }
+    return 0;
+}
+
+int int_field(const nlohmann::json& object, const char* key) {
+    const auto value = int64_field(object, key);
+    if (value > (std::numeric_limits<int>::max)()) return (std::numeric_limits<int>::max)();
+    if (value < (std::numeric_limits<int>::min)()) return (std::numeric_limits<int>::min)();
+    return static_cast<int>(value);
+}
+
+bool is_hex(const std::string& text) {
+    return std::all_of(text.begin(), text.end(), [](unsigned char c) { return std::isxdigit(c) != 0; });
+}
+
+bool is_media_type(int type) {
+    return type == kItemImage || type == kItemVoice || type == kItemFile || type == kItemVideo;
+}
+
+const char* media_label(int type) {
+    switch (type) {
+        case kItemImage: return "图片";
+        case kItemVoice: return "语音";
+        case kItemFile: return "文件";
+        case kItemVideo: return "视频";
+        default: return "媒体";
+    }
+}
+
+std::optional<std::string> image_key(const nlohmann::json& image_item, bool& invalid) {
+    // 图片优先用 image_item.aeskey(32 个十六进制字符),其次 media.aes_key。
+    const auto hex = string_field(image_item, "aeskey");
+    if (!hex.empty()) {
+        if (auto key = hex.size() == 32 ? hex_decode(hex) : std::nullopt) return key;
+        invalid = true;
+        return std::nullopt;
+    }
+    const auto encoded = string_field(object_field(image_item, "media"), "aes_key");
+    if (encoded.empty()) return std::string{};
+    if (auto key = parse_aes_key(encoded)) return key;
+    invalid = true;
+    return std::nullopt;
+}
+
+std::optional<std::string> media_key(const nlohmann::json& media, bool& invalid) {
+    const auto encoded = string_field(media, "aes_key");
+    if (encoded.empty()) return std::string{};
+    if (auto key = parse_aes_key(encoded)) return key;
+    invalid = true;
+    return std::nullopt;
+}
+
+// 一个媒体条目 → 附件;不是媒体条目时返回空。
+std::optional<Attachment> media_attachment(const nlohmann::json& item) {
+    const int type = int_field(item, "type");
+    if (!is_media_type(type)) return std::nullopt;
+    Attachment attachment;
+    MediaRef ref;
+    const nlohmann::json* body = nullptr;
+    std::optional<std::string> key;
+    switch (type) {
+        case kItemImage:
+            body = &object_field(item, "image_item");
+            key = image_key(*body, ref.key_invalid);
+            attachment.kind = AttachmentKind::Image;
+            attachment.name = "image.jpg";
+            attachment.mime_type = "image/jpeg";
+            ref.kind = "image";
+            break;
+        case kItemVoice:
+            body = &object_field(item, "voice_item");
+            key = media_key(object_field(*body, "media"), ref.key_invalid);
+            attachment.kind = AttachmentKind::Voice;
+            attachment.name = "voice.silk";
+            attachment.mime_type = "audio/silk";
+            attachment.transcript = trim(string_field(*body, "text"));
+            ref.kind = "voice";
+            break;
+        case kItemFile: {
+            body = &object_field(item, "file_item");
+            key = media_key(object_field(*body, "media"), ref.key_invalid);
+            const auto name = trim(string_field(*body, "file_name"));
+            attachment.name = name.empty() ? std::string("document.bin") : name;
+            attachment.mime_type = guess_mime(attachment.name);
+            attachment.kind = attachment.mime_type.rfind("image/", 0) == 0 && attachment.mime_type != "image/svg+xml"
+                                  ? AttachmentKind::Image
+                                  : AttachmentKind::File;
+            const auto size = int64_field(*body, "len");
+            if (size > 0) attachment.size = static_cast<std::uint64_t>(size);
+            ref.kind = "file";
+            break;
+        }
+        default:
+            body = &object_field(item, "video_item");
+            key = media_key(object_field(*body, "media"), ref.key_invalid);
+            attachment.kind = AttachmentKind::Video;
+            attachment.name = "video.mp4";
+            attachment.mime_type = "video/mp4";
+            ref.kind = "video";
+            break;
+    }
+    const auto& media = object_field(*body, "media");
+    ref.query_param = string_field(media, "encrypt_query_param");
+    ref.full_url = string_field(media, "full_url");
+    if (key) ref.aes_key = *key;
+    if (!ref.query_param.empty() || !ref.full_url.empty()) attachment.remote_ref = encode_media_ref(ref);
+    return attachment;
+}
+
+// 条目的文字(引用里的文字条目会递归取到它自己的正文)。
+std::string item_text(const nlohmann::json& item) {
+    if (int_field(item, "type") == kItemText) return string_field(object_field(item, "text_item"), "text");
+    if (int_field(item, "type") == kItemVoice) return trim(string_field(object_field(item, "voice_item"), "text"));
+    return {};
+}
+
+std::string quote_of(const nlohmann::json& ref_msg) {
+    const auto title = trim(string_field(ref_msg, "title"));
+    const auto& quoted = object_field(ref_msg, "message_item");
+    if (!quoted.empty()) {
+        const int type = int_field(quoted, "type");
+        if (is_media_type(type)) {
+            std::string label = std::string("[") + media_label(type) + "]";
+            if (type == kItemFile) {
+                const auto name = trim(string_field(object_field(quoted, "file_item"), "file_name"));
+                if (!name.empty()) label += " " + name;
+            }
+            return title.empty() ? label : label + " " + title;
+        }
+        const auto text = trim(item_text(quoted));
+        if (!title.empty() && !text.empty() && title != text) return title + " | " + text;
+        return text.empty() ? title : text;
+    }
+    return title;
+}
+
+struct Authority {
+    std::string scheme;
+    std::string host;  // 小写,不含端口
+    std::string port;  // 可空
+};
+
+std::optional<Authority> parse_authority(const std::string& url) {
+    const auto scheme_end = url.find("://");
+    if (scheme_end == std::string::npos) return std::nullopt;
+    Authority authority;
+    authority.scheme = lower(url.substr(0, scheme_end));
+    const auto rest = url.substr(scheme_end + 3);
+    const auto end = rest.find_first_of("/?#");
+    const auto hostport = rest.substr(0, end);
+    if (hostport.empty() || hostport.find('@') != std::string::npos) return std::nullopt;
+    const auto colon = hostport.rfind(':');
+    if (colon != std::string::npos && hostport.find(']') == std::string::npos) {
+        authority.host = lower(hostport.substr(0, colon));
+        authority.port = hostport.substr(colon + 1);
+    } else {
+        authority.host = lower(hostport);
+    }
+    if (authority.host.empty()) return std::nullopt;
+    return authority;
+}
+
+std::string json_text(const nlohmann::json& value) {
+    return value.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace);
+}
+
+} // namespace
+
+std::uint32_t client_version_number(const std::string& version) {
+    std::uint32_t parts[3] = {0, 0, 0};
+    std::size_t index = 0, pos = 0;
+    while (index < 3 && pos <= version.size()) {
+        const auto dot = version.find('.', pos);
+        const auto piece = version.substr(pos, dot == std::string::npos ? std::string::npos : dot - pos);
+        try {
+            parts[index] = static_cast<std::uint32_t>(std::stoul(piece)) & 0xFFu;
+        } catch (...) {
+            parts[index] = 0;
+        }
+        ++index;
+        if (dot == std::string::npos) break;
+        pos = dot + 1;
+    }
+    return (parts[0] << 16) | (parts[1] << 8) | parts[2];
+}
+
+std::string wechat_uin(std::uint32_t value) { return base64_encode(std::to_string(value)); }
+
+std::string join_url(const std::string& base, const std::string& path) {
+    std::string left = base;
+    while (!left.empty() && left.back() == '/') left.pop_back();
+    std::size_t start = 0;
+    while (start < path.size() && path[start] == '/') ++start;
+    return left + "/" + path.substr(start);
+}
+
+std::string url_encode(const std::string& value) {
+    static constexpr char kHex[] = "0123456789ABCDEF";
+    std::string out;
+    for (const char c : value) {
+        const auto u = static_cast<unsigned char>(c);
+        if ((u >= 'A' && u <= 'Z') || (u >= 'a' && u <= 'z') || (u >= '0' && u <= '9') || u == '-' || u == '_' ||
+            u == '.' || u == '~') {
+            out.push_back(c);
+        } else {
+            out.push_back('%');
+            out.push_back(kHex[u >> 4]);
+            out.push_back(kHex[u & 0x0F]);
+        }
+    }
+    return out;
+}
+
+Envelope parse_envelope(const std::string& body) {
+    Envelope envelope;
+    try {
+        auto json = nlohmann::json::parse(body);
+        if (!json.is_object()) return envelope;
+        envelope.parsed = true;
+        envelope.ret = int_field(json, "ret");
+        envelope.errcode = int_field(json, "errcode");
+        envelope.errmsg = string_field(json, "errmsg");
+        envelope.body = std::move(json);
+    } catch (...) {
+    }
+    return envelope;
+}
+
+bool envelope_failed(const Envelope& envelope) {
+    return !envelope.parsed || envelope.ret != 0 || envelope.errcode != 0;
+}
+
+bool is_session_expired(int ret, int errcode, const std::string& errmsg) {
+    if (ret == -14 || errcode == -14) return true;
+    return (ret == -2 || errcode == -2) && lower(trim(errmsg)) == "unknown error";
+}
+
+bool is_rate_limited(int ret, int errcode, const std::string& errmsg) {
+    if (ret != -2 && errcode != -2) return false;
+    if (is_session_expired(ret, errcode, errmsg)) return false;
+    const auto message = lower(errmsg);
+    return message.find("param") == std::string::npos && message.find("invalid") == std::string::npos;
+}
+
+std::string id_string(const nlohmann::json& value) {
+    if (value.is_number_unsigned()) return std::to_string(value.get<std::uint64_t>());
+    if (value.is_number_integer()) return std::to_string(value.get<std::int64_t>());
+    if (value.is_string()) return value.get<std::string>();
+    return {};
+}
+
+bool valid_id(const std::string& value) {
+    if (value.empty() || value.size() > 128) return false;
+    return std::all_of(value.begin(), value.end(), [](char c) {
+        return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '-' || c == '_' ||
+               c == '.' || c == ':' || c == '@';
+    });
+}
+
+std::string encode_media_ref(const MediaRef& ref) {
+    nlohmann::json value{{"v", 1}, {"t", ref.kind}};
+    if (!ref.query_param.empty()) value["q"] = ref.query_param;
+    if (!ref.full_url.empty()) value["u"] = ref.full_url;
+    if (!ref.aes_key.empty()) value["k"] = platform::to_hex(ref.aes_key);
+    if (ref.key_invalid) value["x"] = true;
+    return json_text(value);
+}
+
+std::optional<MediaRef> decode_media_ref(const std::string& text) {
+    try {
+        const auto value = nlohmann::json::parse(text);
+        if (!value.is_object() || value.value("v", 0) != 1) return std::nullopt;
+        MediaRef ref;
+        ref.kind = string_field(value, "t");
+        ref.query_param = string_field(value, "q");
+        ref.full_url = string_field(value, "u");
+        ref.key_invalid = value.value("x", false);
+        const auto hex = string_field(value, "k");
+        if (!hex.empty()) {
+            auto key = hex_decode(hex);
+            if (!key || key->size() != 16) return std::nullopt;
+            ref.aes_key = *key;
+        }
+        if (ref.query_param.empty() && ref.full_url.empty()) return std::nullopt;
+        return ref;
+    } catch (...) {
+        return std::nullopt;
+    }
+}
+
+std::optional<std::string> hex_decode(const std::string& hex) {
+    if (hex.size() % 2 != 0 || !is_hex(hex)) return std::nullopt;
+    const auto nibble = [](char c) {
+        if (c >= '0' && c <= '9') return c - '0';
+        if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+        return c - 'A' + 10;
+    };
+    std::string out;
+    out.reserve(hex.size() / 2);
+    for (std::size_t i = 0; i < hex.size(); i += 2)
+        out.push_back(static_cast<char>((nibble(hex[i]) << 4) | nibble(hex[i + 1])));
+    return out;
+}
+
+std::optional<std::string> parse_aes_key(const std::string& value) {
+    const auto decoded = base64_decode(trim(value));
+    if (!decoded) return std::nullopt;
+    if (decoded->size() == 16) return decoded;
+    if (decoded->size() == 32 && is_hex(*decoded)) return hex_decode(*decoded);
+    return std::nullopt;
+}
+
+std::string outbound_aes_key(const std::string& raw_key) { return base64_encode(platform::to_hex(raw_key)); }
+
+std::string strip_pkcs7_lenient(std::string data) {
+    if (data.empty()) return data;
+    const auto pad = static_cast<unsigned char>(data.back());
+    if (pad < 1 || pad > 16 || pad > data.size()) return data;
+    for (std::size_t i = data.size() - pad; i < data.size(); ++i)
+        if (static_cast<unsigned char>(data[i]) != pad) return data;
+    data.resize(data.size() - pad);
+    return data;
+}
+
+std::string guess_mime(const std::string& file_name) {
+    static const std::pair<const char*, const char*> kTypes[] = {
+        {".png", "image/png"}, {".jpg", "image/jpeg"}, {".jpeg", "image/jpeg"}, {".gif", "image/gif"},
+        {".webp", "image/webp"}, {".bmp", "image/bmp"}, {".svg", "image/svg+xml"},
+        {".pdf", "application/pdf"}, {".txt", "text/plain"}, {".md", "text/markdown"}, {".csv", "text/csv"},
+        {".json", "application/json"}, {".html", "text/html"}, {".htm", "text/html"},
+        {".zip", "application/zip"}, {".7z", "application/x-7z-compressed"}, {".rar", "application/vnd.rar"},
+        {".doc", "application/msword"},
+        {".docx", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"},
+        {".xls", "application/vnd.ms-excel"},
+        {".xlsx", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"},
+        {".ppt", "application/vnd.ms-powerpoint"},
+        {".pptx", "application/vnd.openxmlformats-officedocument.presentationml.presentation"},
+        {".mp4", "video/mp4"}, {".mov", "video/quicktime"}, {".mp3", "audio/mpeg"}, {".wav", "audio/wav"},
+        {".ogg", "audio/ogg"}, {".amr", "audio/amr"}, {".silk", "audio/silk"},
+    };
+    const auto name = lower(file_name);
+    for (const auto& [ext, mime] : kTypes)
+        if (ends_with(name, ext)) return mime;
+    return "application/octet-stream";
+}
+
+UploadMediaType upload_media_type(const std::string& mime_type, const std::string& file_name) {
+    const auto mime = mime_type.empty() || mime_type == "application/octet-stream" ? guess_mime(file_name)
+                                                                                   : lower(mime_type);
+    if (mime.rfind("image/", 0) == 0 && mime != "image/svg+xml") return UploadMediaType::Image;
+    if (mime.rfind("video/", 0) == 0) return UploadMediaType::Video;
+    return UploadMediaType::File;
+}
+
+std::string cdn_download_url(const std::string& cdn_base, const std::string& query_param) {
+    return join_url(cdn_base, "download") + "?encrypted_query_param=" + url_encode(query_param);
+}
+
+std::string cdn_upload_url(const std::string& cdn_base, const std::string& upload_param, const std::string& filekey) {
+    return join_url(cdn_base, "upload") + "?encrypted_query_param=" + url_encode(upload_param) +
+           "&filekey=" + url_encode(filekey);
+}
+
+bool media_host_allowed(const std::string& url, const std::string& cdn_base) {
+    static const char* kHosts[] = {"novac2c.cdn.weixin.qq.com", "ilinkai.weixin.qq.com", "wx.qlogo.cn",
+                                   "thirdwx.qlogo.cn",          "res.wx.qq.com",          "mmbiz.qpic.cn",
+                                   "mmbiz.qlogo.cn"};
+    const auto target = parse_authority(url);
+    if (!target || (target->scheme != "https" && target->scheme != "http")) return false;
+    for (const char* host : kHosts)
+        if (target->host == host) return true;
+    const auto cdn = parse_authority(cdn_base);
+    return cdn && cdn->scheme == target->scheme && cdn->host == target->host && cdn->port == target->port;
+}
+
+ParsedMessage parse_message(const nlohmann::json& message, const std::string& account) {
+    ParsedMessage parsed;
+    if (!message.is_object()) {
+        parsed.drop_reason = "not an object";
+        return parsed;
+    }
+    parsed.sender = string_field(message, "from_user_id");
+    parsed.message_id = id_string(message.value("message_id", nlohmann::json()));
+    if (parsed.message_id.empty()) parsed.message_id = string_field(message, "client_id");
+    if (parsed.message_id.empty() && message.contains("seq"))
+        parsed.message_id = "seq-" + id_string(message["seq"]);
+    parsed.context_token = string_field(message, "context_token");
+    parsed.create_time_ms = int64_field(message, "create_time_ms");
+    if (parsed.sender.empty()) {
+        parsed.drop_reason = "missing sender";
+        return parsed;
+    }
+    if (parsed.sender == account || int_field(message, "message_type") == kMessageTypeBot) {
+        parsed.drop_reason = "bot message";
+        return parsed;
+    }
+    if (!valid_id(parsed.sender)) {
+        parsed.drop_reason = "invalid sender id";
+        return parsed;
+    }
+    parsed.from_user = true;
+    if (parsed.message_id.empty()) {
+        parsed.drop_reason = "missing message id";
+        return parsed;
+    }
+
+    Inbound inbound;
+    inbound.address.platform = kPlatform;
+    inbound.address.account = account;
+    inbound.address.kind = ChatKind::Private;
+    inbound.address.chat = parsed.sender;
+    inbound.address.sender = parsed.sender;
+    inbound.message_id = parsed.message_id;
+    inbound.mentioned = true;
+
+    static const nlohmann::json kNoItems = nlohmann::json::array();
+    const auto& items = message.contains("item_list") && message["item_list"].is_array() ? message["item_list"]
+                                                                                       : kNoItems;
+    bool text_found = false;
+    std::vector<Attachment> quoted;
+    for (const auto& item : items) {
+        if (!item.is_object()) continue;
+        if (!text_found && int_field(item, "type") == kItemText) {
+            text_found = true;
+            inbound.text = trim(string_field(object_field(item, "text_item"), "text"));
+            const auto& ref = object_field(item, "ref_msg");
+            if (!ref.empty()) {
+                inbound.quote_text = quote_of(ref);
+                if (inbound.quote_text.size() > 4000) inbound.quote_text.resize(4000);
+            }
+        }
+        if (auto attachment = media_attachment(item)) inbound.attachments.push_back(std::move(*attachment));
+        const auto& ref_item = object_field(object_field(item, "ref_msg"), "message_item");
+        if (!ref_item.empty()) {
+            if (auto attachment = media_attachment(ref_item)) quoted.push_back(std::move(*attachment));
+        }
+    }
+    // 被引用的媒体排在本条消息自己的附件之后(“看看这张图”引用旧图片时也能拿到它)。
+    for (auto& attachment : quoted) inbound.attachments.push_back(std::move(attachment));
+    if (inbound.text.empty() && inbound.attachments.empty()) {
+        parsed.drop_reason = "no content";
+        return parsed;
+    }
+    inbound.reply_context = {{"message_id", parsed.message_id}};
+    parsed.inbound = std::move(inbound);
+    return parsed;
+}
+
+nlohmann::json text_item(const std::string& text) {
+    return {{"type", kItemText}, {"text_item", {{"text", text}}}};
+}
+
+nlohmann::json media_item(UploadMediaType type, const std::string& encrypt_query_param, const std::string& raw_key,
+                          std::uint64_t ciphertext_size, std::uint64_t plaintext_size, const std::string& md5_hex,
+                          const std::string& file_name) {
+    const nlohmann::json media{{"encrypt_query_param", encrypt_query_param},
+                               {"aes_key", outbound_aes_key(raw_key)},
+                               {"encrypt_type", 1}};
+    switch (type) {
+        case UploadMediaType::Image:
+            return {{"type", kItemImage}, {"image_item", {{"media", media}, {"mid_size", ciphertext_size}}}};
+        case UploadMediaType::Video:
+            return {{"type", kItemVideo},
+                    {"video_item", {{"media", media}, {"video_size", ciphertext_size}, {"play_length", 0},
+                                    {"video_md5", md5_hex}}}};
+        case UploadMediaType::File:
+        default:
+            return {{"type", kItemFile},
+                    {"file_item", {{"media", media}, {"file_name", file_name},
+                                   {"len", std::to_string(plaintext_size)}}}};
+    }
+}
+
+nlohmann::json build_send_body(const std::string& to, const std::string& client_id, const nlohmann::json& item,
+                               const std::string& context_token) {
+    nlohmann::json msg{{"from_user_id", ""},
+                       {"to_user_id", to},
+                       {"client_id", client_id},
+                       {"message_type", kMessageTypeBot},
+                       {"message_state", 2},
+                       {"item_list", nlohmann::json::array({item})}};
+    if (!context_token.empty()) msg["context_token"] = context_token;
+    return {{"msg", std::move(msg)}};
+}
+
+FragmentMerger::FragmentMerger(MergeLimits limits) : limits_(limits) {}
+
+std::vector<Inbound> FragmentMerger::push(Inbound inbound, Clock::time_point now) {
+    std::vector<Inbound> ready;
+    const auto key = inbound.address.sender;
+    const bool mergeable = inbound.attachments.empty() && !inbound.text.empty();
+    const bool long_fragment = mergeable && text_units(inbound.text, false) >= limits_.split_threshold;
+    auto it = pending_.find(key);
+    if (it != pending_.end()) {
+        if (!mergeable) {
+            ready.push_back(std::move(it->second.inbound));
+            pending_.erase(it);
+            ready.push_back(std::move(inbound));
+            return ready;
+        }
+        // 片段按到达顺序用换行拼接(与 hermes 一致);消息 id 与回复定位沿用第一段。
+        it->second.inbound.text += "\n" + inbound.text;
+        if (long_fragment) {
+            it->second.deadline = now + limits_.wait;
+            return ready;
+        }
+        ready.push_back(std::move(it->second.inbound));
+        pending_.erase(it);
+        return ready;
+    }
+    if (long_fragment) {
+        pending_.emplace(key, Pending{std::move(inbound), now + limits_.wait});
+        return ready;
+    }
+    ready.push_back(std::move(inbound));
+    return ready;
+}
+
+std::vector<Inbound> FragmentMerger::take_due(Clock::time_point now) {
+    std::vector<std::pair<Clock::time_point, std::string>> due;
+    for (const auto& [key, pending] : pending_)
+        if (pending.deadline <= now) due.emplace_back(pending.deadline, key);
+    std::sort(due.begin(), due.end());
+    std::vector<Inbound> ready;
+    for (const auto& entry : due) {
+        auto it = pending_.find(entry.second);
+        ready.push_back(std::move(it->second.inbound));
+        pending_.erase(it);
+    }
+    return ready;
+}
+
+std::vector<Inbound> FragmentMerger::take_all() {
+    return take_due(Clock::time_point::max());
+}
+
+InboundDeduper::InboundDeduper(std::size_t capacity, std::chrono::milliseconds content_window)
+    : capacity_(capacity == 0 ? 1 : capacity), window_(content_window) {}
+
+bool InboundDeduper::remember(const std::string& key) {
+    if (keys_.count(key)) return true;
+    keys_.insert(key);
+    order_.push_back(key);
+    while (order_.size() > capacity_) {
+        keys_.erase(order_.front());
+        order_.pop_front();
+    }
+    return false;
+}
+
+bool InboundDeduper::seen_id(const std::string& message_id) {
+    if (message_id.empty()) return false;
+    return remember("id:" + message_id);
+}
+
+bool InboundDeduper::seen_content(const std::string& sender, const std::string& text, std::int64_t create_time_ms,
+                                  Clock::time_point now) {
+    if (text.empty()) return false;  // 纯媒体消息不按内容去重,连发两张图都要收到
+    const auto digest = platform::to_hex(platform::md5_digest(text));
+    const auto key = "content:" + sender + ":" + digest;
+    if (create_time_ms > 0) return remember(key + ":" + std::to_string(create_time_ms));
+    for (auto it = recent_.begin(); it != recent_.end();) {
+        if (now - it->second > window_) it = recent_.erase(it);
+        else ++it;
+    }
+    const auto found = recent_.find(key);
+    const bool duplicate = found != recent_.end();
+    recent_[key] = now;
+    return duplicate;
+}
+
+} // namespace acecode::im::weixin
diff --git a/src/adapters/im/weixin/weixin_protocol.hpp b/src/adapters/im/weixin/weixin_protocol.hpp
new file mode 100644
index 000000000..9b7d4b26c
--- /dev/null
+++ b/src/adapters/im/weixin/weixin_protocol.hpp
@@ -0,0 +1,203 @@
+#pragma once
+
+// 微信 iLink 机器人(微信 ClawBot)协议的纯逻辑部分:不做 IO,便于单测。
+//
+// 协议要点(详见 openspec add-desktop-im-channels 的微信协议调研):
+//   - 扫码登录得到一个独立的机器人身份 xxx@im.bot(bot_token + ilink_bot_id),只有扫码的
+//     那个微信用户能和它私聊;没有群聊。
+//   - 收消息靠 POST ilink/bot/getupdates 长轮询,游标 get_updates_buf 原样回传、必须持久化。
+//   - 回复要带对方最近一条消息里的 context_token。
+//   - 应用层错误以 HTTP 200 + {"ret"/"errcode" 非 0} 返回,字段可能缺失(缺失按 0)。
+//   - 媒体走单独 CDN,内容用一次性 16 字节密钥做 AES-128-ECB + PKCS#7。
+// 版本按 hermes-agent 验证过的 2.2.0 声明(channel_version 与 iLink-App-ClientVersion 一致)。
+
+#include "im/transport.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <deque>
+#include <map>
+#include <optional>
+#include <set>
+#include <string>
+#include <vector>
+
+namespace acecode::im::weixin {
+
+inline constexpr const char* kPlatform = "weixin";
+inline constexpr const char* kApiBase = "https://ilinkai.weixin.qq.com";
+inline constexpr const char* kCdnBase = "https://novac2c.cdn.weixin.qq.com/c2c";
+inline constexpr const char* kChannelVersion = "2.2.0";
+inline constexpr const char* kAppId = "bot";
+inline constexpr const char* kBotType = "3";
+
+inline constexpr const char* kEpGetBotQr = "ilink/bot/get_bot_qrcode";
+inline constexpr const char* kEpGetQrStatus = "ilink/bot/get_qrcode_status";
+inline constexpr const char* kEpGetUpdates = "ilink/bot/getupdates";
+inline constexpr const char* kEpSendMessage = "ilink/bot/sendmessage";
+inline constexpr const char* kEpSendTyping = "ilink/bot/sendtyping";
+inline constexpr const char* kEpGetConfig = "ilink/bot/getconfig";
+inline constexpr const char* kEpGetUploadUrl = "ilink/bot/getuploadurl";
+
+// 消息条目类型(MessageItem.type)与消息来源(WeixinMessage.message_type)。
+inline constexpr int kItemText = 1;
+inline constexpr int kItemImage = 2;
+inline constexpr int kItemVoice = 3;
+inline constexpr int kItemFile = 4;
+inline constexpr int kItemVideo = 5;
+inline constexpr int kMessageTypeBot = 2;
+
+// 给用户看的“登录失效”说明;传输层状态与发送失败共用。
+inline constexpr const char* kSessionExpiredText = "微信登录已失效,请在设置页重新扫码";
+
+// "2.2.0" → ((2<<16)|(2<<8)|0) = 131584;无法解析的部分按 0。
+std::uint32_t client_version_number(const std::string& version);
+// X-WECHAT-UIN:随机 uint32 的十进制字符串再做 base64(不是真实 UIN,每次请求换一个)。
+std::string wechat_uin(std::uint32_t value);
+
+// base 与相对路径之间只保留一个 '/'。
+std::string join_url(const std::string& base, const std::string& path);
+// 除 [A-Za-z0-9-_.~] 外全部百分号编码(等同 Python quote(safe=''))。
+std::string url_encode(const std::string& value);
+
+// ---- 响应包络 ----
+
+struct Envelope {
+    bool parsed = false;   // 是 JSON 对象
+    int ret = 0;           // 缺失按 0
+    int errcode = 0;       // 缺失按 0
+    std::string errmsg;
+    nlohmann::json body = nlohmann::json::object();
+};
+
+Envelope parse_envelope(const std::string& body);
+bool envelope_failed(const Envelope& envelope);
+// -14,或 -2 且 errmsg 为 "unknown error"(hermes #17228):机器人 token 已失效。
+bool is_session_expired(int ret, int errcode, const std::string& errmsg);
+// -2 且不是上面的失效情况、也不是参数错误:平台限频。
+bool is_rate_limited(int ret, int errcode, const std::string& errmsg);
+
+// uint64 / int64 / 字符串形式的 id 一律转成十进制字符串;其它类型返回空串。
+std::string id_string(const nlohmann::json& value);
+// 平台 id(o9cq…@im.wechat、e06c…@im.bot)只允许常见字符,长度 1..128。
+bool valid_id(const std::string& value);
+
+// ---- 媒体 ----
+
+// 入站附件的下载信息,序列化后放进 Attachment::remote_ref。
+struct MediaRef {
+    std::string query_param;  // CDNMedia.encrypt_query_param
+    std::string full_url;     // CDNMedia.full_url
+    std::string aes_key;      // 16 字节原始密钥;空 = 明文
+    bool key_invalid = false; // 平台给了密钥但格式无法识别
+    std::string kind;         // image / voice / file / video
+};
+
+std::string encode_media_ref(const MediaRef& ref);
+std::optional<MediaRef> decode_media_ref(const std::string& text);
+
+std::optional<std::string> hex_decode(const std::string& hex);
+// CDNMedia.aes_key:base64 解码后 16 字节即原始密钥;32 个十六进制字符则再按十六进制解码。
+std::optional<std::string> parse_aes_key(const std::string& value);
+// 出站条目里的 aes_key = base64(32 个小写十六进制字符),不是 base64(原始 16 字节)——
+// 后者会让对方看到灰色方块(hermes 实测)。
+std::string outbound_aes_key(const std::string& raw_key);
+// 宽松去 PKCS#7:末字节 p 在 1..16 且末 p 字节都等于 p 才去掉,否则原样返回。
+std::string strip_pkcs7_lenient(std::string data);
+
+enum class UploadMediaType { Image = 1, Video = 2, File = 3 };
+
+std::string guess_mime(const std::string& file_name);
+// image/*(SVG 除外)→ 图片;video/* → 视频;其余(包括音频)一律按文件发送。
+UploadMediaType upload_media_type(const std::string& mime_type, const std::string& file_name);
+
+std::string cdn_download_url(const std::string& cdn_base, const std::string& query_param);
+std::string cdn_upload_url(const std::string& cdn_base, const std::string& upload_param,
+                           const std::string& filekey);
+// full_url 只允许微信自家域名(或配置的 CDN 地址),防止被诱导去请求任意内网地址。
+bool media_host_allowed(const std::string& url, const std::string& cdn_base);
+
+// ---- 入站解析 ----
+
+struct ParsedMessage {
+    std::optional<Inbound> inbound;  // 被丢弃时为空
+    std::string sender;              // from_user_id
+    std::string message_id;
+    std::string context_token;
+    std::int64_t create_time_ms = 0;
+    bool from_user = false;          // 真实用户发来的(不是机器人自己 / BOT 类型)
+    std::string drop_reason;         // 英文,只用于日志
+};
+
+// account = 机器人 id(ilink_bot_id)。私聊:chat = sender = from_user_id,mentioned = true。
+ParsedMessage parse_message(const nlohmann::json& message, const std::string& account);
+
+// ---- 出站 ----
+
+nlohmann::json text_item(const std::string& text);
+nlohmann::json media_item(UploadMediaType type, const std::string& encrypt_query_param,
+                          const std::string& raw_key, std::uint64_t ciphertext_size,
+                          std::uint64_t plaintext_size, const std::string& md5_hex,
+                          const std::string& file_name);
+// sendmessage 的请求体(base_info 由 Api 统一补上)。context_token 为空时不带该字段。
+nlohmann::json build_send_body(const std::string& to, const std::string& client_id,
+                               const nlohmann::json& item, const std::string& context_token);
+
+// ---- 入站整理 ----
+
+// iLink 会把超过约 2048 字的用户消息拆成几条依次投递。长片段(>= split_threshold 个字符)
+// 先暂存,等待 wait 内的后续片段;后续片段不长时立即合并交付,超时则原样交付。
+// 普通长度的消息不等待,零延迟。
+struct MergeLimits {
+    std::size_t split_threshold = 1800;  // 码点数;真实拆分点约 2048,留出余量
+    std::chrono::milliseconds wait{5000};
+};
+
+class FragmentMerger {
+public:
+    using Clock = std::chrono::steady_clock;
+    explicit FragmentMerger(MergeLimits limits = {});
+
+    // 新到一条消息,返回现在应交给上层的消息(保持同一发送人的先后顺序)。
+    std::vector<Inbound> push(Inbound inbound, Clock::time_point now);
+    // 等待已超时的暂存消息。
+    std::vector<Inbound> take_due(Clock::time_point now);
+    std::vector<Inbound> take_all();
+    bool empty() const { return pending_.empty(); }
+
+private:
+    struct Pending {
+        Inbound inbound;
+        Clock::time_point deadline;
+    };
+    MergeLimits limits_;
+    std::map<std::string, Pending> pending_;  // 键:发送人
+};
+
+// 入站去重:按消息 id;另外平台偶尔会换一个 message_id 重发同一条内容(hermes #16182),
+// 同一发送人、同一文字、同一发送时间(create_time_ms)的只处理一次。没有发送时间时,
+// 只在 content_window 内按文字去重(窗口很短,避免吞掉用户有意重复的“继续”)。
+class InboundDeduper {
+public:
+    using Clock = std::chrono::steady_clock;
+    explicit InboundDeduper(std::size_t capacity = 1000,
+                            std::chrono::milliseconds content_window = std::chrono::seconds(10));
+
+    // 返回 true 表示重复。message_id 为空时只做内容判定。
+    bool seen_id(const std::string& message_id);
+    bool seen_content(const std::string& sender, const std::string& text, std::int64_t create_time_ms,
+                      Clock::time_point now);
+
+private:
+    bool remember(const std::string& key);
+
+    std::size_t capacity_;
+    std::chrono::milliseconds window_;
+    std::set<std::string> keys_;
+    std::deque<std::string> order_;
+    std::map<std::string, Clock::time_point> recent_;  // 无发送时间的内容键 → 最近一次
+};
+
+} // namespace acecode::im::weixin
diff --git a/src/adapters/im/weixin/weixin_transport.cpp b/src/adapters/im/weixin/weixin_transport.cpp
new file mode 100644
index 000000000..6f1725c67
--- /dev/null
+++ b/src/adapters/im/weixin/weixin_transport.cpp
@@ -0,0 +1,504 @@
+#include "weixin_transport.hpp"
+
+#include "im/markdown.hpp"
+#include "im/redact.hpp"
+#include "im/text_chunk.hpp"
+#include "im/weixin/weixin_media.hpp"
+#include "platform/crypto/digest.hpp"
+#include "platform/crypto/secure_random.hpp"
+#include "utils/logger.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <algorithm>
+#include <cctype>
+
+namespace acecode::im::weixin {
+namespace {
+
+// hermes 代码里的单条上限(其文档里的 4000 已过时),按 Unicode 码点计。
+constexpr std::size_t kChunkUnits = 2000;
+constexpr std::chrono::seconds kSendTimeout{15};
+constexpr std::chrono::seconds kConfigTimeout{10};
+constexpr std::chrono::seconds kUploadTimeout{120};
+constexpr int kUploadAttempts = 3;
+
+bool blank(const std::string& text) {
+    return std::all_of(text.begin(), text.end(), [](unsigned char c) { return std::isspace(c) != 0; });
+}
+
+std::string new_client_id() {
+    static std::atomic<std::uint64_t> counter{0};
+    const auto random = platform::secure_random_bytes(16);
+    if (random.size() == 16) return "acecode-weixin-" + platform::to_hex(random);
+    // 只用于平台侧幂等去重,不是凭据;随机源不可用时用时间 + 计数保证唯一。
+    return "acecode-weixin-" +
+           std::to_string(std::chrono::system_clock::now().time_since_epoch().count()) + "-" +
+           std::to_string(++counter);
+}
+
+std::string describe(const ApiResult& result) {
+    return "status=" + std::to_string(result.status) + " ret=" + std::to_string(result.ret) +
+           " errcode=" + std::to_string(result.errcode) + (result.errmsg.empty() ? "" : " errmsg=" + result.errmsg);
+}
+
+} // namespace
+
+WeixinTransport::WeixinTransport(WeixinTransportOptions options)
+    : options_(std::move(options)), api_(options_.api), merger_(options_.merge) {
+    cursor_ = options_.initial_cursor;
+    for (const auto& [peer, token] : options_.initial_context_tokens)
+        if (valid_id(peer) && !token.empty()) tokens_[peer] = token;
+    status_.account = options_.bot_id;
+}
+
+WeixinTransport::~WeixinTransport() { stop(); }
+
+Capabilities WeixinTransport::capabilities() const {
+    Capabilities caps;
+    caps.max_text_units = kChunkUnits;
+    caps.count_utf16 = false;
+    // 微信没有消息编辑、发送有频率限制且分段之间要间隔:同一回合的输出合并后再发。
+    caps.batch_turn_output = true;
+    caps.supports_typing = true;
+    caps.max_upload_bytes = options_.max_upload_bytes;
+    caps.max_download_bytes = options_.max_download_bytes;
+    return caps;
+}
+
+void WeixinTransport::start(TransportCallbacks callbacks) {
+    if (running_.exchange(true)) return;
+    callbacks_ = std::move(callbacks);
+    stopping_ = false;
+    poller_ = acecode::JoiningThread(&WeixinTransport::poll_loop, this);
+    typer_ = acecode::JoiningThread(&WeixinTransport::typing_loop, this);
+    keeper_ = acecode::JoiningThread(&WeixinTransport::housekeeping_loop, this);
+}
+
+void WeixinTransport::stop() {
+    if (!running_.exchange(false)) return;
+    {
+        // 在锁内置位,等待中的线程不会错过唤醒。
+        std::lock_guard<std::mutex> lock(wake_mu_);
+        stopping_ = true;
+    }
+    wake_.notify_all();
+    {
+        std::lock_guard<std::mutex> lock(typing_mu_);
+        typing_dirty_ = true;
+    }
+    typing_cv_.notify_all();
+    if (poller_.joinable()) poller_.join();
+    if (keeper_.joinable()) keeper_.join();
+    if (typer_.joinable()) typer_.join();
+    {
+        std::lock_guard<std::mutex> lock(typing_mu_);
+        typing_.clear();
+        typing_stop_.clear();
+        typing_sent_.clear();
+    }
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        poll_active_ = false;
+    }
+    set_status(LinkState::Stopped, {});
+}
+
+TransportStatus WeixinTransport::status() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return status_;
+}
+
+std::string WeixinTransport::cursor() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return cursor_;
+}
+
+std::map<std::string, std::string> WeixinTransport::context_tokens() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return tokens_;
+}
+
+void WeixinTransport::set_status(LinkState state, const std::string& detail, bool retry_stopped) {
+    TransportStatus snapshot;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        const auto clean = redact_secrets(detail, {options_.api.token});
+        if (status_.state == state && status_.detail == clean && status_.retry_stopped == retry_stopped) return;
+        status_.state = state;
+        status_.detail = clean;
+        status_.retry_stopped = retry_stopped;
+        snapshot = status_;
+    }
+    if (callbacks_.on_status) callbacks_.on_status(snapshot);
+}
+
+bool WeixinTransport::wait_for(std::chrono::milliseconds duration) {
+    std::unique_lock<std::mutex> lock(wake_mu_);
+    wake_.wait_for(lock, duration, [this] { return stopping_.load(); });
+    return !stopping_;
+}
+
+void WeixinTransport::promote_if_polling() {
+    TransportStatus snapshot;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (!poll_active_ || Clock::now() - poll_started_ < options_.connect_grace) return;
+        if (status_.state != LinkState::Connecting && status_.state != LinkState::Retrying) return;
+        status_.state = LinkState::Connected;
+        status_.detail.clear();
+        status_.retry_stopped = false;
+        snapshot = status_;
+    }
+    if (callbacks_.on_status) callbacks_.on_status(snapshot);
+}
+
+void WeixinTransport::poll_loop() {
+    const std::function<bool()> cancel = [&stopping = stopping_] { return stopping.load(); };
+    std::size_t attempt = 0;
+    auto backoff = [&attempt, &steps = options_.backoff] {
+        const auto delay = steps.empty() ? std::chrono::milliseconds(1000) : steps[(std::min)(attempt, steps.size() - 1)];
+        ++attempt;
+        return delay;
+    };
+    set_status(LinkState::Connecting, "正在连接微信");
+    if (options_.api.token.empty() || options_.bot_id.empty()) {
+        set_status(LinkState::Failed, "缺少微信登录凭据,请在设置页扫码登录", true);
+    } else {
+        auto hold = options_.poll_timeout;
+        while (!stopping_) {
+            std::string cursor;
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                cursor = cursor_;
+                poll_active_ = true;
+                poll_started_ = Clock::now();
+            }
+            const auto result =
+                api_.post(kEpGetUpdates, {{"get_updates_buf", cursor}}, hold + options_.poll_margin, cancel);
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                poll_active_ = false;
+            }
+            if (result.cancelled || stopping_) break;
+            if (result.ok) {
+                attempt = 0;
+                set_status(LinkState::Connected, {});
+                const auto next_hold = result.body.value("longpolling_timeout_ms", std::int64_t{0});
+                if (next_hold > 0)
+                    hold = std::clamp(std::chrono::milliseconds(next_hold), std::chrono::milliseconds(100),
+                                      std::chrono::milliseconds(std::chrono::minutes(2)));
+                handle_batch(result.body);
+                continue;
+            }
+            // 客户端等到超时:当作空批次,游标不变,立即再轮询。
+            if (result.timed_out) continue;
+            if (result.session_expired) {
+                LOG_WARN("[channels/weixin] getupdates reports the bot session expired (" + describe(result) +
+                         "), waiting for a new QR login");
+                set_status(LinkState::Failed, kSessionExpiredText, true);
+                break;
+            }
+            LOG_WARN("[channels/weixin] getupdates failed (" + describe(result) + ")");
+            set_status(LinkState::Retrying, result.error);
+            if (!wait_for(backoff())) break;
+        }
+    }
+    if (!stopping_) {
+        std::unique_lock<std::mutex> lock(wake_mu_);
+        wake_.wait(lock, [this] { return stopping_.load(); });
+    }
+}
+
+void WeixinTransport::handle_batch(const nlohmann::json& body) {
+    if (body.contains("get_updates_buf") && body["get_updates_buf"].is_string()) {
+        const auto next = body["get_updates_buf"].get<std::string>();
+        bool changed = false;
+        if (!next.empty()) {
+            std::lock_guard<std::mutex> lock(mu_);
+            changed = next != cursor_;
+            cursor_ = next;
+        }
+        // 先持久化游标再处理消息:崩溃时宁可漏处理也不重复执行(重复由 id 去重兜底)。
+        if (changed && options_.on_cursor) options_.on_cursor(next);
+    }
+    if (!body.contains("msgs") || !body["msgs"].is_array()) return;
+    for (const auto& message : body["msgs"]) {
+        auto parsed = parse_message(message, options_.bot_id);
+        if (!parsed.from_user) {
+            LOG_DEBUG("[channels/weixin] inbound skipped: " + parsed.drop_reason);
+            continue;
+        }
+        bool duplicate = false;
+        {
+            std::lock_guard<std::mutex> lock(deliver_mu_);
+            duplicate = dedupe_.seen_id(parsed.message_id);
+        }
+        if (duplicate) {
+            LOG_DEBUG("[channels/weixin] duplicate inbound message ignored");
+            continue;
+        }
+        if (!parsed.context_token.empty()) remember_context_token(parsed.sender, parsed.context_token);
+        if (!parsed.inbound) {
+            LOG_DEBUG("[channels/weixin] inbound skipped: " + parsed.drop_reason);
+            continue;
+        }
+        std::lock_guard<std::mutex> lock(deliver_mu_);
+        const auto now = Clock::now();
+        if (dedupe_.seen_content(parsed.sender, parsed.inbound->text, parsed.create_time_ms, now)) {
+            LOG_INFO("[channels/weixin] inbound resent with a different message id, ignored");
+            continue;
+        }
+        deliver_locked(merger_.push(std::move(*parsed.inbound), now));
+    }
+}
+
+void WeixinTransport::deliver_locked(std::vector<Inbound> ready) {
+    for (auto& inbound : ready)
+        if (callbacks_.on_inbound) callbacks_.on_inbound(std::move(inbound));
+}
+
+void WeixinTransport::housekeeping_loop() {
+    while (true) {
+        {
+            std::unique_lock<std::mutex> lock(wake_mu_);
+            wake_.wait_for(lock, options_.housekeeping_tick, [this] { return stopping_.load(); });
+        }
+        const bool stopping = stopping_.load();
+        {
+            std::lock_guard<std::mutex> lock(deliver_mu_);
+            deliver_locked(stopping ? merger_.take_all() : merger_.take_due(Clock::now()));
+        }
+        if (stopping) break;
+        promote_if_polling();
+    }
+}
+
+std::string WeixinTransport::context_token_for(const std::string& peer) const {
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto it = tokens_.find(peer);
+    return it == tokens_.end() ? std::string{} : it->second;
+}
+
+void WeixinTransport::remember_context_token(const std::string& peer, const std::string& token) {
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        auto& slot = tokens_[peer];
+        if (slot == token) return;
+        slot = token;
+    }
+    if (options_.on_context_token) options_.on_context_token(peer, token);
+}
+
+void WeixinTransport::forget_context_token(const std::string& peer, const std::string& rejected) {
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        const auto it = tokens_.find(peer);
+        if (it == tokens_.end() || it->second != rejected) return;
+        tokens_.erase(it);
+    }
+    if (options_.on_context_token) options_.on_context_token(peer, std::string{});
+}
+
+ApiResult WeixinTransport::deliver_item(const std::string& peer, const nlohmann::json& item) {
+    const auto client_id = new_client_id();  // 同一段内容的重发沿用它,平台据此去重
+    auto token = context_token_for(peer);
+    ApiResult result;
+    for (int attempt = 0; attempt <= options_.send_retries; ++attempt) {
+        result = api_.post(kEpSendMessage, build_send_body(peer, client_id, item, token), kSendTimeout);
+        if (result.ok) return result;
+        if (result.session_expired && !token.empty()) {
+            // sendmessage 的 -14 也可能只是 context_token 过期;平台接受不带 token 的发送。
+            // 只删除被拒的那个 token:期间用户若又发来消息,就改用新 token 重发。
+            LOG_INFO("[channels/weixin] sendmessage rejected the cached context token, resending");
+            forget_context_token(peer, token);
+            token = context_token_for(peer);
+            continue;
+        }
+        if (result.session_expired) break;
+        std::chrono::milliseconds delay{0};
+        if (result.rate_limited) {
+            delay = options_.rate_limit_delay * (attempt + 1);
+        } else if (result.status == 0 || result.status >= 500) {
+            delay = options_.send_retry_delay * (attempt + 1);
+        } else {
+            break;  // 平台明确拒绝(参数、权限等),重发没有意义
+        }
+        if (attempt == options_.send_retries) break;
+        LOG_INFO("[channels/weixin] sendmessage will be resent (" + describe(result) + ")");
+        if (!wait_for(delay)) break;
+    }
+    LOG_WARN("[channels/weixin] sendmessage failed (" + describe(result) + ")");
+    return result;
+}
+
+SendResult WeixinTransport::send_text(const Address& to, const std::string& text, const nlohmann::json& reply_context) {
+    (void)reply_context;  // 回复定位只靠 context_token;它按对方用户缓存,总是最新的
+    const auto& peer = to.chat;
+    if (!valid_id(peer)) return {SendOutcome::Failed, "收件人无效"};
+    std::vector<std::string> chunks;
+    for (auto& chunk : chunk_text(markdown_to_plain(text), kChunkUnits, false))
+        if (!blank(chunk)) chunks.push_back(std::move(chunk));  // 绝不发送空白气泡
+    std::lock_guard<std::mutex> lock(send_mu_);
+    for (std::size_t i = 0; i < chunks.size(); ++i) {
+        if (i > 0 && !wait_for(options_.chunk_delay)) return {SendOutcome::Failed, "通道已关闭,剩余内容未发送"};
+        const auto result = deliver_item(peer, text_item(chunks[i]));
+        if (!result.ok) return {SendOutcome::Failed, result.error};
+    }
+    return {SendOutcome::Sent, {}};
+}
+
+SendResult WeixinTransport::send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                                      const std::string& mime_type, const nlohmann::json& reply_context) {
+    (void)reply_context;
+    const auto& peer = to.chat;
+    if (!valid_id(peer)) return {SendOutcome::Failed, "收件人无效"};
+    std::string data, error;
+    if (!read_whole_file(path, options_.max_upload_bytes, data, &error)) return {SendOutcome::Failed, error};
+    const auto display = name.empty() ? path_to_utf8(path.filename()) : name;
+    // 音频(包括 .silk)一律按文件发送:原生语音气泡在上游实现里也没有验证可用。
+    const auto type = upload_media_type(mime_type, display);
+    PreparedUpload upload;
+    if (!prepare_upload(data, upload, &error)) return {SendOutcome::Failed, error};
+    data.clear();
+    data.shrink_to_fit();
+
+    std::lock_guard<std::mutex> lock(send_mu_);
+    ApiResult target;
+    for (int attempt = 0; attempt < kUploadAttempts; ++attempt) {
+        target = api_.post(kEpGetUploadUrl, upload_url_request(upload, type, peer), kSendTimeout);
+        if (target.ok || !(target.status == 0 || target.status >= 500 || target.rate_limited)) break;
+        if (attempt + 1 < kUploadAttempts && !wait_for(options_.send_retry_delay * (attempt + 1))) break;
+    }
+    if (!target.ok) {
+        LOG_WARN("[channels/weixin] getuploadurl failed (" + describe(target) + ")");
+        return {SendOutcome::Failed, target.error};
+    }
+    const auto url = upload_target(target.body, options_.api.cdn_base, upload.filekey);
+    if (url.empty()) return {SendOutcome::Failed, "微信没有返回文件上传地址"};
+    CdnUploadResult uploaded;
+    for (int attempt = 0; attempt < kUploadAttempts; ++attempt) {
+        uploaded = cdn_upload(url, upload.ciphertext, options_.api.use_proxy, kUploadTimeout);
+        if (uploaded.ok || !uploaded.retryable) break;
+        if (attempt + 1 < kUploadAttempts && !wait_for(options_.send_retry_delay * (attempt + 1))) break;
+    }
+    if (!uploaded.ok) {
+        LOG_WARN("[channels/weixin] CDN upload failed (status=" + std::to_string(uploaded.status) + ")");
+        return {SendOutcome::Failed, uploaded.error};
+    }
+    const auto item = media_item(type, uploaded.encrypted_param, upload.aes_key, upload.ciphertext.size(),
+                                 upload.raw_size, upload.md5_hex, display);
+    const auto result = deliver_item(peer, item);
+    if (!result.ok) return {SendOutcome::Failed, result.error};
+    return {SendOutcome::Sent, {}};
+}
+
+bool WeixinTransport::download(const Attachment& attachment, const std::filesystem::path& dest, std::string* error) {
+    const auto ref = decode_media_ref(attachment.remote_ref);
+    if (!ref) {
+        if (error) *error = "附件缺少下载信息";
+        return false;
+    }
+    if (attachment.size > options_.max_download_bytes) {
+        if (error) *error = "文件超过微信 " + size_label(options_.max_download_bytes) + " 下载上限";
+        return false;
+    }
+    return download_media(options_.api, *ref, dest, options_.max_download_bytes, error);
+}
+
+std::string WeixinTransport::typing_ticket(const std::string& peer, bool allow_fetch) {
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        const auto it = tickets_.find(peer);
+        if (it != tickets_.end() && it->second.expires > Clock::now()) return it->second.value;
+    }
+    if (!allow_fetch) return {};
+    nlohmann::json body{{"ilink_user_id", peer}};
+    const auto token = context_token_for(peer);
+    if (!token.empty()) body["context_token"] = token;
+    const std::function<bool()> cancel = [&stopping = stopping_] { return stopping.load(); };
+    const auto result = api_.post(kEpGetConfig, body, kConfigTimeout, cancel);
+    const auto ticket = result.ok && result.body.contains("typing_ticket") && result.body["typing_ticket"].is_string()
+                            ? result.body["typing_ticket"].get<std::string>()
+                            : std::string{};
+    if (ticket.empty()) {
+        if (!result.cancelled) LOG_DEBUG("[channels/weixin] getconfig gave no typing ticket (" + describe(result) + ")");
+        return {};
+    }
+    std::lock_guard<std::mutex> lock(mu_);
+    tickets_[peer] = Ticket{ticket, Clock::now() + options_.typing_ticket_ttl};
+    return ticket;
+}
+
+void WeixinTransport::send_typing(const std::string& peer, int status, bool allow_fetch) {
+    const auto ticket = typing_ticket(peer, allow_fetch);
+    if (ticket.empty()) return;
+    const nlohmann::json body{{"ilink_user_id", peer}, {"typing_ticket", ticket}, {"status", status}};
+    // 停机时的取消不能被停机标志打断,只限制时间。
+    const auto result = allow_fetch
+                            ? api_.post(kEpSendTyping, body, kConfigTimeout,
+                                        [&stopping = stopping_] { return stopping.load(); })
+                            : api_.post(kEpSendTyping, body, std::chrono::seconds(3));
+    if (!result.ok && !result.cancelled) {
+        LOG_DEBUG("[channels/weixin] sendtyping failed (" + describe(result) + ")");
+        std::lock_guard<std::mutex> lock(mu_);
+        tickets_.erase(peer);  // 下次重新取 ticket
+    }
+}
+
+void WeixinTransport::typing_loop() {
+    while (!stopping_) {
+        std::vector<std::string> stops, due;
+        std::chrono::milliseconds wait = options_.typing_interval;
+        {
+            std::lock_guard<std::mutex> lock(typing_mu_);
+            stops.assign(typing_stop_.begin(), typing_stop_.end());
+            typing_stop_.clear();
+            const auto now = Clock::now();
+            for (const auto& peer : typing_) {
+                const auto it = typing_sent_.find(peer);
+                if (it == typing_sent_.end() || now - it->second >= options_.typing_interval) {
+                    due.push_back(peer);
+                    typing_sent_[peer] = now;
+                } else {
+                    const auto left = std::chrono::duration_cast<std::chrono::milliseconds>(
+                        it->second + options_.typing_interval - now);
+                    wait = (std::min)(wait, left);
+                }
+            }
+        }
+        for (const auto& peer : stops) send_typing(peer, 2, true);
+        for (const auto& peer : due) send_typing(peer, 1, true);
+        std::unique_lock<std::mutex> lock(typing_mu_);
+        typing_cv_.wait_for(lock, wait, [this] { return stopping_.load() || typing_dirty_; });
+        typing_dirty_ = false;
+    }
+    // 停机时对仍显示“正在输入”的用户补发取消(只用缓存的 ticket,不再请求 getconfig)。
+    std::set<std::string> pending;
+    {
+        std::lock_guard<std::mutex> lock(typing_mu_);
+        pending.insert(typing_.begin(), typing_.end());
+        pending.insert(typing_stop_.begin(), typing_stop_.end());
+    }
+    for (const auto& peer : pending) send_typing(peer, 2, false);
+}
+
+void WeixinTransport::set_typing(const Address& to, bool on) {
+    const auto& peer = to.chat;
+    if (!valid_id(peer)) return;
+    {
+        std::lock_guard<std::mutex> lock(typing_mu_);
+        if (on) {
+            if (typing_.insert(peer).second) {
+                typing_stop_.erase(peer);
+                typing_sent_.erase(peer);
+            }
+        } else if (typing_.erase(peer)) {
+            typing_stop_.insert(peer);
+            typing_sent_.erase(peer);
+        }
+        typing_dirty_ = true;
+    }
+    typing_cv_.notify_all();
+}
+
+} // namespace acecode::im::weixin
diff --git a/src/adapters/im/weixin/weixin_transport.hpp b/src/adapters/im/weixin/weixin_transport.hpp
new file mode 100644
index 000000000..47ff4ca91
--- /dev/null
+++ b/src/adapters/im/weixin/weixin_transport.hpp
@@ -0,0 +1,140 @@
+#pragma once
+
+// 微信 iLink(微信 ClawBot)传输层。
+//
+//   收:一个线程长轮询 getupdates;游标 get_updates_buf 一变化就先交给调用方持久化,再处理
+//       该批消息(至多一次;重复由 id 去重兜底)。-14 等“登录失效”→ Failed 且不再重试,
+//       等用户在设置页重新扫码。长消息被平台拆成几段时先合并再交给上层。
+//   发:Markdown 转纯文本,按 2000 字分段,每段之间间隔 1.5 秒;带上该用户最近的
+//       context_token(没有也照发);context_token 过期被拒时去掉它重发一次;限频时等待后重发,
+//       同一段重发沿用同一个 client_id(平台据此去重)。所有发送串行。
+//   正在输入:getconfig 取 typing_ticket(缓存 10 分钟),忙碌期间每 5 秒发一次,结束时必须
+//       发取消,否则对方一直显示“正在输入”。
+//   媒体:见 weixin_media.hpp。
+// 只有私聊:Address{platform "weixin", account = ilink_bot_id, chat = sender = 对方 ilink_user_id}。
+
+#include "im/transport.hpp"
+#include "im/weixin/weixin_api.hpp"
+#include "im/weixin/weixin_protocol.hpp"
+#include "utils/joining_thread.hpp"
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <functional>
+#include <map>
+#include <mutex>
+#include <set>
+#include <string>
+#include <vector>
+
+namespace acecode::im::weixin {
+
+struct WeixinTransportOptions {
+    ApiOptions api;               // token = bot_token;base_url = 登录返回的 baseurl
+    std::string bot_id;           // ilink_bot_id,作为 Address::account
+    std::string initial_cursor;   // 上次持久化的 get_updates_buf;空 = 从头开始
+    // 游标变化时回调(在处理该批消息之前),调用方持久化;丢失游标会让平台重放历史消息。
+    std::function<void(const std::string&)> on_cursor;
+    // 每个对方用户最近的 context_token。主动发送(Desktop 里输入的回复)也要用,调用方持久化;
+    // 回调里 token 为空表示该用户的 token 已失效、应删除。
+    std::map<std::string, std::string> initial_context_tokens;
+    std::function<void(const std::string& peer, const std::string& token)> on_context_token;
+
+    std::chrono::milliseconds poll_timeout{std::chrono::seconds(35)};  // 服务端挂起时长,之后以服务端给的为准
+    std::chrono::milliseconds poll_margin{std::chrono::seconds(10)};   // 客户端超时 = 挂起时长 + 余量
+    // 长轮询已挂起这么久仍没有报错,说明 token 被接受(无效 token 会立即得到 -14),即视为已连接;
+    // 不必等没有新消息时要挂满 35 秒的第一次轮询返回。
+    std::chrono::milliseconds connect_grace{std::chrono::seconds(3)};
+    std::vector<std::chrono::milliseconds> backoff{
+        std::chrono::seconds(1), std::chrono::seconds(2), std::chrono::seconds(5),
+        std::chrono::seconds(10), std::chrono::seconds(30), std::chrono::seconds(60)};
+    std::chrono::milliseconds chunk_delay{1500};       // 分段之间的间隔(hermes 实测值)
+    std::chrono::milliseconds send_retry_delay{1000};  // 网络错误 / 5xx:第 n 次重发前等 n 倍
+    std::chrono::milliseconds rate_limit_delay{3000};  // -2 限频:第 n 次重发前等 n 倍
+    int send_retries = 4;
+    std::chrono::milliseconds typing_interval{5000};
+    std::chrono::milliseconds typing_ticket_ttl{std::chrono::minutes(10)};
+    std::chrono::milliseconds housekeeping_tick{200};  // 合并片段到期检查与“已连接”判定的周期
+    MergeLimits merge;
+    std::uint64_t max_upload_bytes = 50u * 1024u * 1024u;
+    std::uint64_t max_download_bytes = 50u * 1024u * 1024u;
+};
+
+class WeixinTransport final : public Transport {
+public:
+    explicit WeixinTransport(WeixinTransportOptions options);
+    ~WeixinTransport() override;
+
+    std::string platform() const override { return kPlatform; }
+    Capabilities capabilities() const override;
+    void start(TransportCallbacks callbacks) override;
+    void stop() override;
+    TransportStatus status() const override;
+    SendResult send_text(const Address& to, const std::string& text,
+                         const nlohmann::json& reply_context) override;
+    SendResult send_file(const Address& to, const std::filesystem::path& path, const std::string& name,
+                         const std::string& mime_type, const nlohmann::json& reply_context) override;
+    void set_typing(const Address& to, bool on) override;
+    bool download(const Attachment& attachment, const std::filesystem::path& dest,
+                  std::string* error) override;
+
+    std::string cursor() const;
+    std::map<std::string, std::string> context_tokens() const;
+
+private:
+    using Clock = std::chrono::steady_clock;
+
+    struct Ticket {
+        std::string value;
+        Clock::time_point expires;
+    };
+
+    void poll_loop();
+    void typing_loop();
+    void housekeeping_loop();
+    bool wait_for(std::chrono::milliseconds duration);
+    void set_status(LinkState state, const std::string& detail, bool retry_stopped = false);
+    void promote_if_polling();
+    void handle_batch(const nlohmann::json& body);
+    void deliver_locked(std::vector<Inbound> ready);
+    ApiResult deliver_item(const std::string& peer, const nlohmann::json& item);
+    std::string context_token_for(const std::string& peer) const;
+    void remember_context_token(const std::string& peer, const std::string& token);
+    // 只有当前缓存的仍是 rejected 时才删除(期间收到的新 token 不受影响)。
+    void forget_context_token(const std::string& peer, const std::string& rejected);
+    std::string typing_ticket(const std::string& peer, bool allow_fetch);
+    void send_typing(const std::string& peer, int status, bool allow_fetch);
+
+    WeixinTransportOptions options_;
+    Api api_;
+    TransportCallbacks callbacks_;
+    acecode::JoiningThread poller_, typer_, keeper_;
+    std::atomic<bool> running_{false};
+    std::atomic<bool> stopping_{false};
+    std::mutex wake_mu_;
+    std::condition_variable wake_;
+
+    mutable std::mutex mu_;  // status_、cursor_、tokens_、tickets_、poll_*
+    TransportStatus status_;
+    std::string cursor_;
+    std::map<std::string, std::string> tokens_;
+    std::map<std::string, Ticket> tickets_;
+    bool poll_active_ = false;
+    Clock::time_point poll_started_{};
+
+    std::mutex deliver_mu_;  // 入站去重、片段合并与交付顺序
+    InboundDeduper dedupe_;
+    FragmentMerger merger_;
+
+    std::mutex typing_mu_;
+    std::condition_variable typing_cv_;
+    std::set<std::string> typing_;
+    std::set<std::string> typing_stop_;
+    std::map<std::string, Clock::time_point> typing_sent_;
+    bool typing_dirty_ = false;
+
+    std::mutex send_mu_;  // 出站串行(文字分段、媒体上传都不交错)
+};
+
+} // namespace acecode::im::weixin
diff --git a/src/apps/daemon/daemon_shutdown_sequence.cpp b/src/apps/daemon/daemon_shutdown_sequence.cpp
index ab68ea8aa..5c5b72b90 100644
--- a/src/apps/daemon/daemon_shutdown_sequence.cpp
+++ b/src/apps/daemon/daemon_shutdown_sequence.cpp
@@ -1,9 +1,9 @@
 #include "daemon_shutdown_sequence.hpp"
 #include <cstdio>
 namespace acecode::daemon {
-const std::array<DaemonShutdownStep, 14>& DaemonShutdownSequence::order() {
-    static const std::array<DaemonShutdownStep, 14> steps{{
-        DaemonShutdownStep::Channels, DaemonShutdownStep::RemoteWeb,
+const std::array<DaemonShutdownStep, 15>& DaemonShutdownSequence::order() {
+    static const std::array<DaemonShutdownStep, 15> steps{{
+        DaemonShutdownStep::Channels, DaemonShutdownStep::ImChannels, DaemonShutdownStep::RemoteWeb,
         DaemonShutdownStep::RemoteControl, DaemonShutdownStep::ConnectorWorkers,
         DaemonShutdownStep::Watchers, DaemonShutdownStep::LoopScheduler,
         DaemonShutdownStep::TaskSuggestions, DaemonShutdownStep::Sessions,
diff --git a/src/apps/daemon/daemon_shutdown_sequence.hpp b/src/apps/daemon/daemon_shutdown_sequence.hpp
index 026c527f8..3cef8e044 100644
--- a/src/apps/daemon/daemon_shutdown_sequence.hpp
+++ b/src/apps/daemon/daemon_shutdown_sequence.hpp
@@ -4,14 +4,14 @@
 
 namespace acecode::daemon {
 enum class DaemonShutdownStep {
-    Channels, RemoteWeb, RemoteControl, ConnectorWorkers, Watchers, LoopScheduler,
+    Channels, ImChannels, RemoteWeb, RemoteControl, ConnectorWorkers, Watchers, LoopScheduler,
     TaskSuggestions, Sessions, SpawnListener, Mcp, Lsp, ModelPool, Heartbeat, RuntimeFiles
 };
 class DaemonShutdownSequence {
 public:
     using Action = std::function<void(DaemonShutdownStep)>;
     void run(const Action& action) noexcept;
-    static const std::array<DaemonShutdownStep, 14>& order();
+    static const std::array<DaemonShutdownStep, 15>& order();
 private:
     bool ran_ = false;
 };
diff --git a/src/apps/daemon/im_channels.cpp b/src/apps/daemon/im_channels.cpp
new file mode 100644
index 000000000..587d60c17
--- /dev/null
+++ b/src/apps/daemon/im_channels.cpp
@@ -0,0 +1,83 @@
+#include "im_channels.hpp"
+
+#include "config/config.hpp"
+#include "platform/process/os_process.hpp"
+#include "remote_control/session_channel_binder.hpp"
+#include "session_host/session_registry.hpp"
+#include "skills/skill_command_expander.hpp"
+#include "utils/paths.hpp"
+#include "utils/utf8_path.hpp"
+#include "web/handlers/models_handler.hpp"
+#include "web/handlers/opencode_command_expander.hpp"
+
+#include <mutex>
+
+namespace acecode::daemon {
+
+std::filesystem::path im_channels_root() { return path_from_utf8(get_acecode_dir()) / "channels"; }
+
+std::unique_ptr<channels::core::ChannelHost> make_im_channel_host(ImChannelDeps deps) {
+    channels::core::HostServices services;
+    auto& conversation = services.conversation;
+    auto* registry = deps.registry;
+    auto* client = deps.client;
+    const auto* config = deps.config;
+    auto* config_mu = deps.config_mu;
+
+    conversation.sessions = client;
+    conversation.pending_permissions = [registry](const std::string& id) {
+        auto entry = registry->acquire(id);
+        return entry && entry->prompter ? entry->prompter->snapshot_pending_requests()
+                                        : std::vector<nlohmann::json>{};
+    };
+    conversation.session_cwd = [registry](const std::string& id) {
+        auto entry = registry->acquire(id);
+        return entry ? entry->cwd : std::string{};
+    };
+    conversation.catalog = std::move(deps.catalog);
+    conversation.resume_target = [client](const rc::RcSessionTarget& target) {
+        return rc::resume_session_target_exact(*client, target);
+    };
+    conversation.model_names = [config, config_mu] {
+        std::vector<std::string> names;
+        std::shared_lock<std::shared_mutex> lock(*config_mu);
+        for (const auto& model : config->saved_models) names.push_back(model.name);
+        return names;
+    };
+    conversation.switch_model = [config, config_mu, registry](const std::string& id, const std::string& name,
+                                                              std::string* error) {
+        std::optional<ModelProfile> profile;
+        {
+            std::shared_lock<std::shared_mutex> lock(*config_mu);
+            profile = web::find_model_by_name(*config, name);
+        }
+        if (!profile) {
+            if (error) *error = "没有名为 " + name + " 的模型";
+            return false;
+        }
+        return registry->switch_model(id, *profile, nullptr, error);
+    };
+    // 与 Web 输入相同的展开顺序:先 opencode 命令,再技能命令。
+    conversation.expand_skill = [config, config_mu, registry](const std::string& id, const std::string& text) {
+        if (auto entry = registry->acquire(id); entry && !entry->cwd.empty()) {
+            std::shared_lock<std::shared_mutex> lock(*config_mu);
+            auto command = web::try_expand_opencode_command(text, *config, entry->cwd);
+            if (command.expanded) return command.text;
+        }
+        if (auto skills = registry->skill_registry_snapshot(id)) {
+            auto skill = web::try_expand_skill_command(text, *skills);
+            if (skill.expanded) return skill.text;
+        }
+        return text;
+    };
+    services.broadcast = std::move(deps.broadcast);
+    services.current_pid = [] { return static_cast<std::int64_t>(current_pid()); };
+    services.endpoints = std::move(deps.endpoints);
+    services.bind = std::move(deps.bind);
+    services.weixin_login = std::move(deps.weixin_login);
+    if (deps.tune_services) deps.tune_services(services);
+    const auto root = deps.root.empty() ? im_channels_root() : deps.root;
+    return std::make_unique<channels::core::ChannelHost>(root, std::move(services));
+}
+
+} // namespace acecode::daemon
diff --git a/src/apps/daemon/im_channels.hpp b/src/apps/daemon/im_channels.hpp
new file mode 100644
index 000000000..07fd9860d
--- /dev/null
+++ b/src/apps/daemon/im_channels.hpp
@@ -0,0 +1,47 @@
+#pragma once
+
+// daemon 托管的消息通道(QQ、微信、飞书、钉钉、Telegram、Discord、LINE,openspec add-desktop-im-channels design D2 / D12):
+// 把 SessionRegistry、会话目录、模型切换、技能展开接到通道宿主上。
+// WS 推送经 broadcast 回调发出;宿主先于 WebServer 构造,调用方在 WebServer 建好后再接上。
+
+#include "channels/core/host.hpp"
+#include "remote_control/rc_session_navigation.hpp"
+
+#include <filesystem>
+#include <functional>
+#include <memory>
+#include <optional>
+#include <shared_mutex>
+#include <string>
+#include <vector>
+
+namespace acecode {
+struct AppConfig;
+class SessionClient;
+class SessionRegistry;
+} // namespace acecode
+
+namespace acecode::daemon {
+
+struct ImChannelDeps {
+    SessionRegistry* registry = nullptr;
+    SessionClient* client = nullptr;
+    const AppConfig* config = nullptr;  // 读 saved_models;持 config_mu 共享锁访问
+    std::shared_mutex* config_mu = nullptr;
+    std::function<std::vector<rc::RcSessionTarget>(const std::optional<std::string>&)> catalog;
+    channels::core::Broadcast broadcast;
+    // 以下只有端到端测试会改:平台接入地址、扫码门户与数据根目录(为空时用 im_channels_root())。
+    channels::core::HostEndpoints endpoints;
+    im::qqbot::BindOptions bind;
+    im::weixin::LoginOptions weixin_login;
+    std::filesystem::path root;
+    // 测试用:在宿主创建前调整服务(传输层参数、LINE 的隧道与回调端口等)。
+    std::function<void(channels::core::HostServices&)> tune_services;
+};
+
+// 通道数据根目录 <data_dir>/channels,与 WhatsApp 的 channels/whatsapp 并列。
+std::filesystem::path im_channels_root();
+
+std::unique_ptr<channels::core::ChannelHost> make_im_channel_host(ImChannelDeps deps);
+
+} // namespace acecode::daemon
diff --git a/src/apps/daemon/rc_session_catalog.cpp b/src/apps/daemon/rc_session_catalog.cpp
new file mode 100644
index 000000000..500f15d32
--- /dev/null
+++ b/src/apps/daemon/rc_session_catalog.cpp
@@ -0,0 +1,44 @@
+#include "rc_session_catalog.hpp"
+
+#include "session/global_session_catalog.hpp"
+#include "utils/logger.hpp"
+#include "workspace/workspace_registry.hpp"
+
+namespace acecode::daemon {
+
+std::vector<rc::RcSessionTarget> build_rc_session_catalog(const std::string& projects_dir,
+                                                          SessionClient& client,
+                                                          const std::optional<std::string>& query) {
+    GlobalSessionCatalogOptions options;
+    options.content_query = query;
+    options.content_limit_per_project = 100;
+    const auto catalog = build_global_session_catalog(projects_dir, client.list_sessions(), options);
+
+    std::vector<rc::RcSessionTarget> out;
+    out.reserve(catalog.entries.size());
+    for (const auto& entry : catalog.entries) {
+        const auto* active = entry.active ? &*entry.active : nullptr;
+        rc::RcSessionTarget target;
+        target.session_id = entry.meta.id;
+        target.workspace_hash = entry.workspace_hash;
+        target.cwd = active && !active->cwd.empty() ? active->cwd : entry.meta.cwd;
+        target.title = active && !active->title.empty() ? active->title : entry.meta.title;
+        target.summary = active && !active->summary.empty() ? active->summary : entry.meta.summary;
+        target.workspace_label = entry.meta.no_workspace
+            ? std::string{}
+            : (!entry.workspace_name.empty() ? entry.workspace_name : desktop::default_workspace_name(target.cwd));
+        target.updated_at = active && !active->updated_at.empty() ? active->updated_at : entry.meta.updated_at;
+        target.no_workspace = entry.meta.no_workspace;
+        target.active = active != nullptr;
+        target.content_match_score = entry.content_match ? entry.content_match->score : 0;
+        out.push_back(std::move(target));
+    }
+    for (const auto& error : catalog.errors) {
+        LOG_WARN("[remote-control] global session catalog " + error.stage + " failed for " + error.project_dir +
+                 ": " + error.message);
+    }
+    rc::sort_rc_session_targets(out, query.has_value());
+    return out;
+}
+
+} // namespace acecode::daemon
diff --git a/src/apps/daemon/rc_session_catalog.hpp b/src/apps/daemon/rc_session_catalog.hpp
new file mode 100644
index 000000000..7cd8da6e4
--- /dev/null
+++ b/src/apps/daemon/rc_session_catalog.hpp
@@ -0,0 +1,19 @@
+#pragma once
+
+// 跨工作区的会话目录:活跃会话 + 已登记工作区 + 无项目会话,排除归档与子代理会话。
+// /rc 远程控制与消息通道(QQ / Telegram)的 /sessions 共用这一份目录。
+
+#include "remote_control/rc_session_navigation.hpp"
+#include "session/session_client.hpp"
+
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace acecode::daemon {
+
+std::vector<rc::RcSessionTarget> build_rc_session_catalog(const std::string& projects_dir,
+                                                          SessionClient& client,
+                                                          const std::optional<std::string>& query);
+
+} // namespace acecode::daemon
diff --git a/src/apps/daemon/worker.cpp b/src/apps/daemon/worker.cpp
index 2cb74de6e..07afb0bbd 100644
--- a/src/apps/daemon/worker.cpp
+++ b/src/apps/daemon/worker.cpp
@@ -1,6 +1,8 @@
 #include "utils/abandonable_call.hpp"
 #include "worker.hpp"
 #include "daemon_shutdown_sequence.hpp"
+#include "im_channels.hpp"
+#include "rc_session_catalog.hpp"
 #include "platform/termination_signal.hpp"
 #include "ipc/runtime_files_guard.hpp"
 #include "utils/lifetime_token.hpp"
@@ -41,7 +43,6 @@
 #include "loop/loop_store.hpp"
 #include "loop/scheduled_task_tool.hpp"
 #include "session_host/local_session_client.hpp"
-#include "session/global_session_catalog.hpp"
 #include "session_host/session_registry.hpp"
 #include "session_host/thread_service.hpp"
 #include "session_host/task_suggestion_service.hpp"
@@ -111,49 +112,6 @@ namespace acecode::daemon {
 
 namespace {
 
-std::vector<acecode::rc::RcSessionTarget> build_rc_session_catalog(
-    const std::string& projects_dir,
-    acecode::SessionClient& client,
-    const std::optional<std::string>& query) {
-    acecode::GlobalSessionCatalogOptions options;
-    options.content_query = query;
-    options.content_limit_per_project = 100;
-    const auto catalog = acecode::build_global_session_catalog(
-        projects_dir, client.list_sessions(), options);
-
-    std::vector<acecode::rc::RcSessionTarget> out;
-    out.reserve(catalog.entries.size());
-    for (const auto& entry : catalog.entries) {
-        const auto* active = entry.active ? &*entry.active : nullptr;
-        acecode::rc::RcSessionTarget target;
-        target.session_id = entry.meta.id;
-        target.workspace_hash = entry.workspace_hash;
-        target.cwd = active && !active->cwd.empty() ? active->cwd : entry.meta.cwd;
-        target.title = active && !active->title.empty() ? active->title : entry.meta.title;
-        target.summary = active && !active->summary.empty() ? active->summary : entry.meta.summary;
-        target.workspace_label = entry.meta.no_workspace
-            ? std::string{}
-            : (!entry.workspace_name.empty()
-                ? entry.workspace_name
-                : acecode::desktop::default_workspace_name(target.cwd));
-        target.updated_at = active && !active->updated_at.empty()
-            ? active->updated_at
-            : entry.meta.updated_at;
-        target.no_workspace = entry.meta.no_workspace;
-        target.active = active != nullptr;
-        target.content_match_score = entry.content_match
-            ? entry.content_match->score
-            : 0;
-        out.push_back(std::move(target));
-    }
-    for (const auto& error : catalog.errors) {
-        LOG_WARN("[remote-control] global session catalog " + error.stage +
-                 " failed for " + error.project_dir + ": " + error.message);
-    }
-    acecode::rc::sort_rc_session_targets(out, query.has_value());
-    return out;
-}
-
 // Windows service control and owner-monitor requests share the process bridge.
 void request_terminate() {
     platform::TerminationSignal::request_process_termination();
@@ -559,6 +517,16 @@ int run_worker(const WorkerOptions& opts, const AppConfig& cfg) {
         return result;
     };
     acecode::channels::Runtime channel_runtime(std::move(channel_deps));
+    // 消息通道(QQ / Telegram):WS 推送等 WebServer 建好后再接上(宿主声明在 server 之前)。
+    auto im_broadcast = std::make_shared<acecode::channels::core::Broadcast>();
+    auto im_channels = make_im_channel_host(
+        {&registry, &client, &cfg_mut, &app_config_mu,
+         [projects_dir, &client](const std::optional<std::string>& query) {
+             return build_rc_session_catalog(projects_dir, client, query);
+         },
+         [im_broadcast](const std::string& type, const nlohmann::json& payload) {
+             if (*im_broadcast) (*im_broadcast)(type, payload);
+         }});
     subagent_deps->registry = &registry;
     subagent_deps->client   = &client;
     subagent_deps->config   = &cfg_mut;
@@ -698,8 +666,12 @@ int run_worker(const WorkerOptions& opts, const AppConfig& cfg) {
         }
     }
     web_deps.remote_web_proxy = &remote_web_proxy;
+    web_deps.channel_host = im_channels.get();
 
     acecode::web::WebServer server(std::move(web_deps));
+    *im_broadcast = [&server](const std::string& type, const nlohmann::json& payload) {
+        server.broadcast_local_event(type, payload);
+    };
     LifetimeToken server_lifetime;
     const auto server_ref = server_lifetime.ref(server);
 
@@ -785,6 +757,7 @@ int run_worker(const WorkerOptions& opts, const AppConfig& cfg) {
     const DaemonShutdownSequence::Action shutdown_step = [&](DaemonShutdownStep step) {
         switch (step) {
         case DaemonShutdownStep::Channels: channel_runtime.stop(); break;
+        case DaemonShutdownStep::ImChannels: im_channels->stop(); break;
         case DaemonShutdownStep::RemoteWeb: remote_web_proxy.stop(); break;
         case DaemonShutdownStep::RemoteControl:
             rc_binder.shutdown();
@@ -958,6 +931,7 @@ int run_worker(const WorkerOptions& opts, const AppConfig& cfg) {
     });
 
     channel_runtime.start();
+    im_channels->start();
     const int rc = server.run();
     LOG_INFO("[daemon] worker shutting down");
     if (opts.foreground) std::cerr << "[daemon] shutting down\n";
diff --git a/src/apps/desktop/desktop_pet.cpp b/src/apps/desktop/desktop_pet.cpp
new file mode 100644
index 000000000..b68981b5c
--- /dev/null
+++ b/src/apps/desktop/desktop_pet.cpp
@@ -0,0 +1,778 @@
+#include "desktop_pet.hpp"
+#include "web_host.hpp"
+
+#include "desktop_pet_layout.hpp"
+#include "platform/native_ui/strings.hpp"
+
+#include "utils/encoding.hpp"
+#include "utils/logger.hpp"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstddef>
+#include <cstdio>
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <string>
+#include <type_traits>
+
+#include <nlohmann/json.hpp>
+
+#ifdef _WIN32
+#  ifndef WIN32_LEAN_AND_MEAN
+#    define WIN32_LEAN_AND_MEAN
+#  endif
+#  ifndef NOMINMAX
+#    define NOMINMAX
+#  endif
+#  include <windows.h>
+#  include <dwmapi.h>
+#  include <wrl.h>
+#  include <WebView2.h>
+#  include <webview/webview.h>
+#  pragma comment(lib, "dwmapi.lib")
+
+namespace acecode {
+// cmake/acecode_desktop.cmake 用 acecode_bin2cpp.cmake 把
+// assets/desktop_pet/agent_office_pet.html 嵌进 exe。
+const unsigned char* desktop_pet_page_data();
+std::size_t desktop_pet_page_size();
+} // namespace acecode
+#endif
+
+namespace acecode::desktop {
+
+#ifdef _WIN32
+namespace {
+
+using Microsoft::WRL::Callback;
+using Microsoft::WRL::ComPtr;
+struct GdiDeleter { void operator()(HGDIOBJ value) const { if (value) ::DeleteObject(value); } };
+using UniqueRegion = std::unique_ptr<std::remove_pointer_t<HRGN>, GdiDeleter>;
+
+constexpr wchar_t kPetWindowClass[] = L"ACECodeDesktopPetWindow";
+constexpr UINT kMsgStartDrag = WM_APP + 0x41;
+constexpr UINT kMsgShowMenu = WM_APP + 0x42;
+constexpr UINT kMsgStartResize = WM_APP + 0x43;
+constexpr UINT_PTR kRevealTimer = 1;
+constexpr UINT_PTR kResizeTimer = 2;
+// 拖把手期间约 60Hz 轮询鼠标:不依赖鼠标捕获(按下时捕获在 WebView2 的子窗口手里)。
+constexpr UINT kResizePollMs = 15;
+constexpr double kZoomStep = 1.1;   // 滚轮一格 / 菜单一次
+// 页面第一帧画完会发 ready;万一没收到,导航完成后最多再等这么久也把窗口挪进来。
+constexpr UINT kRevealFallbackMs = 3000;
+constexpr UINT kMenuDock = 1;
+constexpr UINT kMenuHide = 2;
+constexpr UINT kMenuZoomIn = 3;
+constexpr UINT kMenuZoomOut = 4;
+constexpr UINT kMenuResetSize = 5;
+
+std::string hresult_text(HRESULT hr) {
+    char buffer[16];
+    std::snprintf(buffer, sizeof(buffer), "0x%08lX", static_cast<unsigned long>(hr));
+    return buffer;
+}
+
+bool desktop_pet_disabled_by_env() {
+    const char* value = std::getenv("ACECODE_DESKTOP_PET");
+    if (!value) return false;
+    const std::string text(value);
+    return text == "0" || text == "off" || text == "false" || text == "no";
+}
+
+bool chinese_ui() {
+    return native_locale().rfind("zh", 0) == 0;
+}
+
+HMONITOR primary_monitor() {
+    return ::MonitorFromPoint(POINT{0, 0}, MONITOR_DEFAULTTOPRIMARY);
+}
+
+DesktopPetRect work_area_of(HMONITOR monitor) {
+    MONITORINFO info{};
+    info.cbSize = sizeof(info);
+    if (!monitor || !::GetMonitorInfoW(monitor, &info)) {
+        RECT work{};
+        ::SystemParametersInfoW(SPI_GETWORKAREA, 0, &work, 0);
+        info.rcWork = work;
+    }
+    return {info.rcWork.left, info.rcWork.top,
+            info.rcWork.right - info.rcWork.left,
+            info.rcWork.bottom - info.rcWork.top};
+}
+
+int monitor_dpi(HMONITOR monitor) {
+    using GetDpiForMonitorFn = HRESULT(WINAPI*)(HMONITOR, int, UINT*, UINT*);
+    if (monitor) {
+        if (HMODULE shcore = ::LoadLibraryW(L"shcore.dll")) {
+            auto getter = reinterpret_cast<GetDpiForMonitorFn>(
+                reinterpret_cast<void*>(::GetProcAddress(shcore, "GetDpiForMonitor")));
+            UINT dpi_x = 0;
+            UINT dpi_y = 0;
+            const bool ok = getter && getter(monitor, 0, &dpi_x, &dpi_y) == S_OK;
+            ::FreeLibrary(shcore);
+            if (ok && dpi_y != 0) return static_cast<int>(dpi_y);
+        }
+    }
+    int dpi = 96;
+    if (HDC screen = ::GetDC(nullptr)) {
+        const int value = ::GetDeviceCaps(screen, LOGPIXELSY);
+        if (value > 0) dpi = value;
+        ::ReleaseDC(nullptr, screen);
+    }
+    return dpi;
+}
+
+std::filesystem::path pet_root_dir() {
+    wchar_t buffer[MAX_PATH] = {};
+    const DWORD length = ::GetEnvironmentVariableW(L"LOCALAPPDATA", buffer, MAX_PATH);
+    std::filesystem::path base;
+    if (length > 0 && length < MAX_PATH) {
+        base = buffer;
+    } else {
+        base = std::filesystem::temp_directory_path();
+    }
+    return base / L"ACECode" / L"desktop-pet";
+}
+
+std::filesystem::path pet_user_data_dir() {
+    return pet_root_dir() / L"webview2";
+}
+
+// 用户调过的大小(逻辑倍数,与 DPI 无关);0 表示没调过,用默认整数倍。
+double load_logical_scale() {
+    std::ifstream in(pet_root_dir() / L"settings.json");
+    if (!in) return 0.0;
+    const auto json = nlohmann::json::parse(in, nullptr, false);
+    if (json.is_discarded() || !json.is_object() || !json.contains("scale") || !json["scale"].is_number()) return 0.0;
+    const double scale = json["scale"].get<double>();
+    return std::isfinite(scale) && scale > 0.0 ? scale : 0.0;
+}
+
+void save_logical_scale(double scale) {
+    std::error_code ec;
+    std::filesystem::create_directories(pet_root_dir(), ec);
+    nlohmann::json json = nlohmann::json::object();
+    if (scale > 0.0) json["scale"] = std::round(scale * 1000.0) / 1000.0;
+    std::ofstream out(pet_root_dir() / L"settings.json", std::ios::trunc);
+    if (out) out << json.dump();
+}
+
+// 与 tao/winit 的透明窗口同一招:空区域的 blur-behind 让 DWM 按像素 alpha 合成
+// 这个窗口(区域为空所以不会真的模糊)。WebView2 背景设成全透明后,页面里
+// 没画东西的地方(原来的草地)就直接透出桌面。
+void enable_per_pixel_alpha(HWND hwnd) {
+    UniqueRegion empty(::CreateRectRgn(0, 0, -1, -1));
+    DWM_BLURBEHIND blur{};
+    blur.dwFlags = DWM_BB_ENABLE | DWM_BB_BLURREGION;
+    blur.fEnable = TRUE;
+    blur.hRgnBlur = empty.get();
+    const HRESULT hr = ::DwmEnableBlurBehindWindow(hwnd, &blur);
+    if (FAILED(hr)) {
+        LOG_WARN("[desktop-pet] DwmEnableBlurBehindWindow failed: " + hresult_text(hr));
+    }
+}
+
+// 窗口区域只留房间轮廓、控制条和页面浮层(成员列表 / 提示 / 状态气泡):
+// 透明角落既不绘制也不接收点击,点击会落到后面的窗口。区域同时裁剪绘制,
+// 所以冒出墙顶的气泡必须由页面上报,否则会被切掉。
+void apply_hit_region(HWND hwnd, double scale, const std::vector<DesktopPetOverlay>& overlays = {}) {
+    const auto polygon = desktop_pet_hit_polygon(scale);
+    std::vector<POINT> points;
+    points.reserve(polygon.size());
+    for (const auto& point : polygon) points.push_back(POINT{point.x, point.y});
+    UniqueRegion region(::CreatePolygonRgn(points.data(), static_cast<int>(points.size()), WINDING));
+    UniqueRegion toolbar(::CreateRectRgn(0, 0,
+        static_cast<int>(std::lround(kDesktopPetSceneWidth * scale)),
+        static_cast<int>(std::lround(kDesktopPetToolbarHeight * scale))));
+    if (region && toolbar) ::CombineRgn(region.get(), region.get(), toolbar.get(), RGN_OR);
+    RECT bounds{};
+    ::GetClientRect(hwnd, &bounds);
+    for (const auto& overlay : overlays) {
+        if (!region) break;
+        UniqueRegion popup(::CreateRectRgn(
+            static_cast<int>(overlay[0] * bounds.right), static_cast<int>(overlay[1] * bounds.bottom),
+            static_cast<int>(std::ceil(overlay[2] * bounds.right)), static_cast<int>(std::ceil(overlay[3] * bounds.bottom))));
+        if (popup) ::CombineRgn(region.get(), region.get(), popup.get(), RGN_OR);
+    }
+    // SetWindowRgn takes ownership only on success.
+    if (region && ::SetWindowRgn(hwnd, region.get(), TRUE)) (void)region.release();
+}
+
+} // namespace
+
+struct DesktopPet::Impl : std::enable_shared_from_this<DesktopPet::Impl> {
+    explicit Impl(WebHost& owner) : host(owner) {}
+    WebHost& host; // Required GUI host; DesktopPet is destroyed before this host.
+    nlohmann::json office_snapshot = {{"follow", true}};
+    bool page_ready = false;
+    std::vector<DesktopPetOverlay> hit_overlays;
+    HWND hwnd = nullptr;
+    webview::detail::mswebview2::loader loader;
+    ComPtr<ICoreWebView2Environment> environment;
+    ComPtr<ICoreWebView2Controller> controller;
+    ComPtr<ICoreWebView2> webview;
+    EventRegistrationToken message_token{};
+    EventRegistrationToken navigation_token{};
+    DesktopPetPlacement placement;
+    double logical_scale = 0.0;   // 用户调过的大小,0 = 默认
+    bool revealed = false;
+    bool user_moved = false;
+    bool closed = false;
+    bool resizing = false;
+    DesktopPetRect resize_start{};
+    POINT resize_cursor{};
+
+    ~Impl() { close(); }
+
+    void bind_bridge() {
+        const auto weak = weak_from_this();
+        host.bind("aceDesktop_updateOffice", [weak](const std::string& request) {
+            const auto self = weak.lock();
+            if (!self || self->closed || request.size() > 512 * 1024) return std::string("false");
+            try {
+                const auto args = nlohmann::json::parse(request);
+                if (!args.is_array() || args.size() != 1 || !args[0].is_string()) return std::string("false");
+                const auto value = nlohmann::json::parse(args[0].get<std::string>());
+                if (!value.is_object() || value.value("version", 0) != 1 ||
+                    !value.contains("agents") || !value["agents"].is_array() ||
+                    !value.contains("offices") || !value["offices"].is_array() || value["offices"].size() > 5) {
+                    return std::string("false");
+                }
+                self->office_snapshot = value;
+                self->publish_snapshot();
+                return std::string("true");
+            } catch (...) { return std::string("false"); }
+        });
+        host.bind("aceDesktop_getOfficeState", [weak](const std::string&) {
+            const auto self = weak.lock();
+            return self && !self->closed ? self->office_snapshot.dump() : std::string("{}");
+        });
+    }
+
+    void publish_snapshot() {
+        if (closed || !page_ready || !webview || !office_snapshot.contains("version")) return;
+        webview->PostWebMessageAsJson(utf8_to_wide(office_snapshot.dump()).c_str());
+    }
+
+    void office_action(const std::wstring& message) {
+        if (message.size() > 16384) return;
+        const auto value = nlohmann::json::parse(wide_to_utf8(message), nullptr, false);
+        if (!value.is_object()) return;
+        const auto type_field = value.find("type");
+        if (type_field == value.end() || !type_field->is_string()) return;
+        const auto type = type_field->get<std::string>();
+        if (type == "overlay") {
+            auto next = desktop_pet_overlays_from_message(value);
+            if (next == hit_overlays) return;
+            hit_overlays = std::move(next);
+            RECT bounds{};
+            ::GetClientRect(hwnd, &bounds);
+            apply_hit_region(hwnd, bounds.right / static_cast<double>(kDesktopPetSceneWidth), hit_overlays);
+            return;
+        }
+        if (type != "select" && type != "follow" && type != "open") return;
+        host.eval("window.dispatchEvent(new CustomEvent('ace-desktop-office-action',{detail:" +
+                  value.dump() + "}));");
+    }
+
+    bool start() {
+        const HMONITOR monitor = primary_monitor();
+        const DesktopPetRect work = work_area_of(monitor);
+        logical_scale = load_logical_scale();
+        placement = place_desktop_pet(work, monitor_dpi(monitor), logical_scale);
+
+        HINSTANCE instance = ::GetModuleHandleW(nullptr);
+        WNDCLASSEXW window_class{};
+        window_class.cbSize = sizeof(window_class);
+        window_class.hInstance = instance;
+        window_class.lpfnWndProc = &Impl::window_proc;
+        window_class.lpszClassName = kPetWindowClass;
+        window_class.hCursor = ::LoadCursorW(nullptr, MAKEINTRESOURCEW(32512)); // IDC_ARROW
+        // 纯黑在 per-pixel alpha 合成下就是全透明:WebView2 首帧之前窗口什么也不显示。
+        window_class.hbrBackground = static_cast<HBRUSH>(::GetStockObject(BLACK_BRUSH));
+        if (!::RegisterClassExW(&window_class) &&
+            ::GetLastError() != ERROR_CLASS_ALREADY_EXISTS) {
+            LOG_WARN("[desktop-pet] RegisterClassExW failed: " + std::to_string(::GetLastError()));
+            return false;
+        }
+
+        // 先放在工作区外面完成 WebView2 初始化与首帧,再挪进来(同 WebHost 的
+        // OffscreenUntilReady:父窗口可见时 WebView2 初始化更可靠,也不会闪出白底)。
+        hwnd = ::CreateWindowExW(
+            WS_EX_TOOLWINDOW | WS_EX_TOPMOST | WS_EX_NOACTIVATE,
+            kPetWindowClass,
+            L"ACECode Desktop Pet",
+            WS_POPUP,
+            work.x + work.width + 10000,
+            work.y + work.height + 10000,
+            placement.window.width,
+            placement.window.height,
+            nullptr,
+            nullptr,
+            instance,
+            this);
+        if (!hwnd) {
+            LOG_WARN("[desktop-pet] CreateWindowExW failed: " + std::to_string(::GetLastError()));
+            return false;
+        }
+        enable_per_pixel_alpha(hwnd);
+        apply_hit_region(hwnd, placement.scale);
+        ::ShowWindow(hwnd, SW_SHOWNOACTIVATE);
+        return create_environment();
+    }
+
+    bool create_environment() {
+        std::error_code ec;
+        const auto user_data = pet_user_data_dir();
+        std::filesystem::create_directories(user_data, ec);
+        if (ec) {
+            LOG_WARN("[desktop-pet] failed to create WebView2 profile directory: " + ec.message());
+            return false;
+        }
+        const auto weak = weak_from_this();
+        auto completed = Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
+            [weak](HRESULT result, ICoreWebView2Environment* value) -> HRESULT {
+                if (const auto self = weak.lock()) self->environment_ready(result, value);
+                return S_OK;
+            });
+        const HRESULT hr = loader.create_environment_with_options(
+            nullptr, user_data.wstring().c_str(), nullptr, completed.Get());
+        if (FAILED(hr)) {
+            LOG_WARN("[desktop-pet] failed to start WebView2 environment: " + hresult_text(hr));
+            return false;
+        }
+        return true;
+    }
+
+    void environment_ready(HRESULT result, ICoreWebView2Environment* value) {
+        if (closed) return;
+        if (FAILED(result) || !value) {
+            LOG_WARN("[desktop-pet] WebView2 environment failed: " + hresult_text(result));
+            close();
+            return;
+        }
+        environment = value;
+        const auto weak = weak_from_this();
+        const HRESULT hr = environment->CreateCoreWebView2Controller(
+            hwnd,
+            Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(
+                [weak](HRESULT created, ICoreWebView2Controller* controller_value) -> HRESULT {
+                    if (const auto self = weak.lock()) {
+                        self->controller_ready(created, controller_value);
+                    } else if (controller_value) {
+                        controller_value->Close();
+                    }
+                    return S_OK;
+                })
+                .Get());
+        if (FAILED(hr)) {
+            LOG_WARN("[desktop-pet] CreateCoreWebView2Controller failed: " + hresult_text(hr));
+            close();
+        }
+    }
+
+    void controller_ready(HRESULT result, ICoreWebView2Controller* value) {
+        if (closed) {
+            if (value) value->Close();
+            return;
+        }
+        if (FAILED(result) || !value) {
+            LOG_WARN("[desktop-pet] WebView2 controller failed: " + hresult_text(result));
+            close();
+            return;
+        }
+        controller = value;
+        ComPtr<ICoreWebView2Controller2> controller2;
+        if (SUCCEEDED(controller.As(&controller2))) {
+            // 全透明背景;进程级 WEBVIEW2_DEFAULT_BACKGROUND_COLOR(主窗口用的浅色)在这里被覆盖。
+            controller2->put_DefaultBackgroundColor(COREWEBVIEW2_COLOR{0, 0, 0, 0});
+        }
+        RECT bounds{};
+        ::GetClientRect(hwnd, &bounds);
+        controller->put_Bounds(bounds);
+        if (FAILED(controller->get_CoreWebView2(&webview)) || !webview) {
+            LOG_WARN("[desktop-pet] WebView2 core unavailable");
+            close();
+            return;
+        }
+        configure_settings();
+
+        const auto weak = weak_from_this();
+        webview->add_WebMessageReceived(
+            Callback<ICoreWebView2WebMessageReceivedEventHandler>(
+                [weak](ICoreWebView2*, ICoreWebView2WebMessageReceivedEventArgs* args) -> HRESULT {
+                    LPWSTR raw = nullptr;
+                    if (args && SUCCEEDED(args->TryGetWebMessageAsString(&raw)) && raw) {
+                        const std::wstring message(raw);
+                        ::CoTaskMemFree(raw);
+                        if (const auto self = weak.lock()) self->on_web_message(message);
+                    }
+                    return S_OK;
+                })
+                .Get(),
+            &message_token);
+        webview->add_NavigationCompleted(
+            Callback<ICoreWebView2NavigationCompletedEventHandler>(
+                [weak](ICoreWebView2*, ICoreWebView2NavigationCompletedEventArgs* args) -> HRESULT {
+                    BOOL success = FALSE;
+                    if (args) args->get_IsSuccess(&success);
+                    if (const auto self = weak.lock()) self->navigation_completed(success != FALSE);
+                    return S_OK;
+                })
+                .Get(),
+            &navigation_token);
+
+        const std::string page(reinterpret_cast<const char*>(acecode::desktop_pet_page_data()),
+                               acecode::desktop_pet_page_size());
+        const HRESULT hr = webview->NavigateToString(utf8_to_wide(page).c_str());
+        if (FAILED(hr)) {
+            LOG_WARN("[desktop-pet] NavigateToString failed: " + hresult_text(hr));
+            close();
+        }
+    }
+
+    void configure_settings() {
+        ComPtr<ICoreWebView2Settings> settings;
+        if (FAILED(webview->get_Settings(&settings)) || !settings) return;
+        settings->put_AreDefaultContextMenusEnabled(FALSE);
+        settings->put_AreDevToolsEnabled(FALSE);
+        settings->put_IsStatusBarEnabled(FALSE);
+        // Ctrl+滚轮缩放会打破整数倍像素对齐。
+        settings->put_IsZoomControlEnabled(FALSE);
+        ComPtr<ICoreWebView2Settings3> settings3;
+        if (SUCCEEDED(settings.As(&settings3))) {
+            settings3->put_AreBrowserAcceleratorKeysEnabled(FALSE);
+        }
+        ComPtr<ICoreWebView2Settings5> settings5;
+        if (SUCCEEDED(settings.As(&settings5))) settings5->put_IsPinchZoomEnabled(FALSE);
+        ComPtr<ICoreWebView2Settings6> settings6;
+        if (SUCCEEDED(settings.As(&settings6))) settings6->put_IsSwipeNavigationEnabled(FALSE);
+    }
+
+    void navigation_completed(bool success) {
+        if (closed || revealed) return;
+        if (!success) {
+            LOG_WARN("[desktop-pet] page navigation failed");
+            close();
+            return;
+        }
+        ::SetTimer(hwnd, kRevealTimer, kRevealFallbackMs, nullptr);
+    }
+
+    void on_web_message(const std::wstring& message) {
+        if (closed || !hwnd) return;
+        if (message == L"ready") {
+            page_ready = true;
+            reveal();
+            publish_snapshot();
+        } else if (!message.empty() && message.front() == L'{') {
+            office_action(message);
+        } else if (message == L"drag") {
+            // 回调里不直接进模态拖动循环,回到窗口过程再开始。
+            ::PostMessageW(hwnd, kMsgStartDrag, 0, 0);
+        } else if (message == L"menu") {
+            ::PostMessageW(hwnd, kMsgShowMenu, 0, 0);
+        } else if (message == L"resize") {
+            ::PostMessageW(hwnd, kMsgStartResize, 0, 0);
+        } else if (message == L"size-reset") {
+            reset_size();
+        } else if (message.rfind(L"zoom ", 0) == 0) {
+            int steps = 0;
+            double fx = 1.0, fy = 1.0;
+            if (::swscanf_s(message.c_str() + 5, L"%d %lf %lf", &steps, &fx, &fy) >= 1) zoom_by(steps, fx, fy);
+        }
+    }
+
+    void reveal() {
+        if (revealed || closed || !hwnd) return;
+        revealed = true;
+        ::KillTimer(hwnd, kRevealTimer);
+        apply_placement(placement);
+        LOG_INFO("[desktop-pet] shown at " + std::to_string(placement.window.x) + "," +
+                 std::to_string(placement.window.y) + " size " +
+                 std::to_string(placement.window.width) + "x" +
+                 std::to_string(placement.window.height) + " scale " +
+                 std::to_string(placement.scale));
+    }
+
+    void apply_placement(const DesktopPetPlacement& next) {
+        placement = next;
+        // 尺寸变了会同步收到 WM_SIZE,在那里更新 WebView2 边界和命中区域。
+        ::SetWindowPos(hwnd, HWND_TOPMOST, next.window.x, next.window.y,
+                       next.window.width, next.window.height,
+                       SWP_NOACTIVATE | SWP_SHOWWINDOW);
+    }
+
+    int window_dpi() const { return monitor_dpi(::MonitorFromWindow(hwnd, MONITOR_DEFAULTTOPRIMARY)); }
+    DesktopPetRect window_work_area() const { return work_area_of(::MonitorFromWindow(hwnd, MONITOR_DEFAULTTOPRIMARY)); }
+    DesktopPetRect window_rect() const {
+        RECT r{};
+        ::GetWindowRect(hwnd, &r);
+        return {r.left, r.top, r.right - r.left, r.bottom - r.top};
+    }
+
+    // 缩放后告诉页面当前是默认大小的百分之几,页面闪一下提示。
+    void notify_size(int dpi, const DesktopPetRect& work) {
+        if (!webview) return;
+        const double base = desktop_pet_scale(dpi, work.width, work.height);
+        const int percent = static_cast<int>(std::lround(placement.scale / base * 100.0));
+        webview->PostWebMessageAsString((L"size " + std::to_wstring(percent)).c_str());
+    }
+
+    void apply_scale(double device_scale, double fx, double fy) {
+        const int dpi = window_dpi();
+        const DesktopPetRect work = window_work_area();
+        const double scale = clamp_desktop_pet_scale(device_scale, dpi, work);
+        apply_placement(scale_desktop_pet(window_rect(), scale, fx, fy, work));
+        logical_scale = scale * 96.0 / dpi;
+        notify_size(dpi, work);
+    }
+
+    void zoom_by(int steps, double fx, double fy) {
+        if (!revealed || closed || steps == 0) return;
+        const double current = window_rect().width / static_cast<double>(kDesktopPetSceneWidth);
+        // 停在右下角时锚在右下角(缩放后还贴着角);拖动过之后以鼠标所在点为中心。
+        if (!user_moved) { fx = 1.0; fy = 1.0; }
+        apply_scale(current * std::pow(kZoomStep, steps), fx, fy);
+        save_logical_scale(logical_scale);
+    }
+
+    void start_resize() {
+        if (!revealed || closed || resizing) return;
+        resizing = true;
+        resize_start = window_rect();
+        ::GetCursorPos(&resize_cursor);
+        ::SetTimer(hwnd, kResizeTimer, kResizePollMs, nullptr);
+    }
+
+    void resize_tick() {
+        const int button = ::GetSystemMetrics(SM_SWAPBUTTON) ? VK_RBUTTON : VK_LBUTTON;
+        if (!(::GetAsyncKeyState(button) & 0x8000)) {
+            finish_resize();
+            return;
+        }
+        POINT cursor{};
+        ::GetCursorPos(&cursor);
+        // 把手在左上方:往左上拖变大、右下角不动;横竖两个方向取放大得多的那个。
+        const double by_x = resize_start.width - (cursor.x - resize_cursor.x);
+        const double by_y = (resize_start.height - (cursor.y - resize_cursor.y)) *
+                            kDesktopPetSceneWidth / static_cast<double>(kDesktopPetSceneHeight);
+        const int dpi = window_dpi();
+        const DesktopPetRect work = window_work_area();
+        const double scale = clamp_desktop_pet_scale(std::max(by_x, by_y) / kDesktopPetSceneWidth, dpi, work);
+        const auto next = scale_desktop_pet(resize_start, scale, 1.0, 1.0, work);
+        if (next.window.width == placement.window.width && next.window.x == placement.window.x &&
+            next.window.y == placement.window.y) return;
+        apply_placement(next);
+        logical_scale = scale * 96.0 / dpi;
+        notify_size(dpi, work);
+    }
+
+    void finish_resize() {
+        ::KillTimer(hwnd, kResizeTimer);
+        resizing = false;
+        save_logical_scale(logical_scale);
+    }
+
+    void reset_size() {
+        if (!revealed || closed) return;
+        logical_scale = 0.0;
+        save_logical_scale(0.0);
+        const int dpi = window_dpi();
+        const DesktopPetRect work = window_work_area();
+        if (!user_moved) dock_to_corner();
+        else apply_placement(scale_desktop_pet(window_rect(), desktop_pet_scale(dpi, work.width, work.height), 1.0, 1.0, work));
+        notify_size(dpi, work);
+    }
+
+    void dock_to_corner() {
+        const HMONITOR monitor = revealed
+            ? ::MonitorFromWindow(hwnd, MONITOR_DEFAULTTOPRIMARY)
+            : primary_monitor();
+        apply_placement(place_desktop_pet(work_area_of(monitor), monitor_dpi(monitor), logical_scale));
+    }
+
+    void start_drag() {
+        if (!hwnd) return;
+        // 与主窗口的 WebHost::start_window_drag 相同:放开 WebView2 子窗口的鼠标捕获,
+        // 交给系统的标题栏拖动循环,按钮松开时循环自己结束。
+        ::ReleaseCapture();
+        ::SendMessageW(hwnd, WM_NCLBUTTONDOWN, HTCAPTION, 0);
+    }
+
+    void show_menu() {
+        if (!hwnd) return;
+        HMENU menu = ::CreatePopupMenu();
+        if (!menu) return;
+        const bool zh = chinese_ui();
+        ::AppendMenuW(menu, MF_STRING, kMenuDock, zh ? L"回到右下角" : L"Move to corner");
+        ::AppendMenuW(menu, MF_SEPARATOR, 0, nullptr);
+        ::AppendMenuW(menu, MF_STRING, kMenuZoomIn, zh ? L"放大（也可以滚轮）" : L"Zoom in (or scroll)");
+        ::AppendMenuW(menu, MF_STRING, kMenuZoomOut, zh ? L"缩小" : L"Zoom out");
+        ::AppendMenuW(menu, MF_STRING, kMenuResetSize, zh ? L"恢复默认大小" : L"Reset size");
+        ::AppendMenuW(menu, MF_SEPARATOR, 0, nullptr);
+        ::AppendMenuW(menu, MF_STRING, kMenuHide, zh ? L"隐藏桌面宠物" : L"Hide desktop pet");
+        POINT cursor{};
+        ::GetCursorPos(&cursor);
+        // KB135788:弹菜单前把宿主设为前台,菜单后补一条消息,点空白处菜单才会消失。
+        ::SetForegroundWindow(hwnd);
+        const UINT command = static_cast<UINT>(::TrackPopupMenuEx(
+            menu, TPM_RETURNCMD | TPM_RIGHTBUTTON | TPM_NONOTIFY, cursor.x, cursor.y, hwnd, nullptr));
+        ::PostMessageW(hwnd, WM_NULL, 0, 0);
+        ::DestroyMenu(menu);
+        if (command == kMenuDock) {
+            user_moved = false;
+            dock_to_corner();
+        } else if (command == kMenuZoomIn) {
+            zoom_by(1, 0.5, 0.5);
+        } else if (command == kMenuZoomOut) {
+            zoom_by(-1, 0.5, 0.5);
+        } else if (command == kMenuResetSize) {
+            reset_size();
+        } else if (command == kMenuHide) {
+            LOG_INFO("[desktop-pet] hidden from context menu");
+            close();
+        }
+    }
+
+    void handle_dpi_changed(int dpi) {
+        const HMONITOR monitor = ::MonitorFromWindow(hwnd, MONITOR_DEFAULTTOPRIMARY);
+        const DesktopPetRect work = work_area_of(monitor);
+        if (!revealed) {
+            // 还在屏幕外:只换尺寸,位置等 reveal 时按主屏算。
+            const DesktopPetPlacement next = place_desktop_pet(work_area_of(primary_monitor()), dpi, logical_scale);
+            placement.scale = next.scale;
+            placement.window.width = next.window.width;
+            placement.window.height = next.window.height;
+            RECT current{};
+            ::GetWindowRect(hwnd, &current);
+            ::SetWindowPos(hwnd, nullptr, current.left, current.top, next.window.width,
+                           next.window.height, SWP_NOACTIVATE | SWP_NOZORDER);
+            return;
+        }
+        if (user_moved) {
+            RECT current{};
+            ::GetWindowRect(hwnd, &current);
+            apply_placement(resize_desktop_pet(
+                {current.left, current.top, current.right - current.left,
+                 current.bottom - current.top},
+                dpi, work, logical_scale));
+        } else {
+            apply_placement(place_desktop_pet(work, dpi, logical_scale));
+        }
+    }
+
+    LRESULT handle_message(UINT message, WPARAM wparam, LPARAM lparam) {
+        switch (message) {
+        case WM_MOUSEACTIVATE:
+            return MA_NOACTIVATE;
+        case WM_SIZE: {
+            RECT bounds{};
+            ::GetClientRect(hwnd, &bounds);
+            if (controller) controller->put_Bounds(bounds);
+            if (bounds.right > 0) apply_hit_region(hwnd, bounds.right / static_cast<double>(kDesktopPetSceneWidth), hit_overlays);
+            break;
+        }
+        case WM_MOVE:
+            if (controller) controller->NotifyParentWindowPositionChanged();
+            break;
+        case WM_EXITSIZEMOVE:
+            if (revealed) user_moved = true;
+            break;
+        case WM_DPICHANGED:
+            handle_dpi_changed(HIWORD(wparam));
+            return 0;
+        case WM_DISPLAYCHANGE:
+            if (revealed && !user_moved) dock_to_corner();
+            break;
+        case WM_SETTINGCHANGE:
+            if (wparam == SPI_SETWORKAREA && revealed && !user_moved) dock_to_corner();
+            break;
+        case WM_TIMER:
+            if (wparam == kResizeTimer) {
+                resize_tick();
+                return 0;
+            }
+            if (wparam == kRevealTimer) {
+                ::KillTimer(hwnd, kRevealTimer);
+                LOG_WARN("[desktop-pet] page ready signal missing; revealing after timeout");
+                reveal();
+                return 0;
+            }
+            break;
+        case kMsgStartDrag:
+            start_drag();
+            return 0;
+        case kMsgShowMenu:
+            show_menu();
+            return 0;
+        case kMsgStartResize:
+            start_resize();
+            return 0;
+        default:
+            break;
+        }
+        return ::DefWindowProcW(hwnd, message, wparam, lparam);
+    }
+
+    static LRESULT CALLBACK window_proc(HWND window, UINT message, WPARAM wparam, LPARAM lparam) {
+        if (message == WM_NCCREATE) {
+            const auto* create = reinterpret_cast<const CREATESTRUCTW*>(lparam);
+            auto* self = static_cast<Impl*>(create->lpCreateParams);
+            ::SetWindowLongPtrW(window, GWLP_USERDATA, reinterpret_cast<LONG_PTR>(self));
+            if (self) self->hwnd = window;
+        }
+        auto* self = reinterpret_cast<Impl*>(::GetWindowLongPtrW(window, GWLP_USERDATA));
+        if (!self || self->hwnd != window) return ::DefWindowProcW(window, message, wparam, lparam);
+        return self->handle_message(message, wparam, lparam);
+    }
+
+    void close() {
+        if (closed) return;
+        closed = true;
+        if (webview) {
+            webview->remove_WebMessageReceived(message_token);
+            webview->remove_NavigationCompleted(navigation_token);
+        }
+        if (controller) controller->Close();
+        webview.Reset();
+        controller.Reset();
+        environment.Reset();
+        if (hwnd) {
+            HWND window = hwnd;
+            hwnd = nullptr;
+            ::SetWindowLongPtrW(window, GWLP_USERDATA, 0);
+            ::DestroyWindow(window);
+        }
+    }
+};
+#endif
+
+DesktopPet::DesktopPet(WebHost& host) {
+#ifdef _WIN32
+    if (desktop_pet_disabled_by_env()) {
+        LOG_INFO("[desktop-pet] disabled by ACECODE_DESKTOP_PET");
+        return;
+    }
+    auto impl = std::make_shared<Impl>(host);
+    impl->bind_bridge();
+    if (impl->start()) {
+        impl_ = std::move(impl);
+    } else {
+        impl->close();
+    }
+#else
+    (void)host;
+#endif
+}
+
+DesktopPet::~DesktopPet() {
+#ifdef _WIN32
+    if (impl_) impl_->close();
+#endif
+}
+
+} // namespace acecode::desktop
diff --git a/src/apps/desktop/desktop_pet.hpp b/src/apps/desktop/desktop_pet.hpp
new file mode 100644
index 000000000..3a82f41ed
--- /dev/null
+++ b/src/apps/desktop/desktop_pet.hpp
@@ -0,0 +1,38 @@
+#pragma once
+
+// 桌面 agent 办公室:acecode-desktop 启动时在主屏右下角拉起一个透明、置顶、
+// 不抢焦点、不进任务栏的小窗口,里面是真实会话驱动的像素 AI 办公室
+// (assets/desktop_pet/agent_office_pet.html,构建期嵌进 exe)。
+// Web 应用经快照桥更新；GUI 线程拥有窗口和桥回调。
+//
+// 交互:左键拖动挪位置;单击小人头顶报状态;右键菜单「回到右下角 / 隐藏桌面宠物」
+// (隐藏只到本次退出)。环境变量 ACECODE_DESKTOP_PET=0 可整体关闭。
+//
+// Windows 实现在 desktop_pet.cpp(独立的 WebView2 环境,用户数据在
+// %LOCALAPPDATA%\ACECode\desktop-pet\webview2);macOS 实现在 desktop_pet_mac.mm
+// (非激活 NSPanel + WKWebView,设置在 ~/Library/Application Support/ACECode/desktop-pet)。
+// 两者都不进 ACECode 数据目录,以免被数据目录迁移当成持续写入的活文件;
+// Linux 构造即空操作。
+// 必须在 GUI 线程构造与析构;任何失败只记日志,不影响主窗口。
+
+#include <memory>
+
+namespace acecode::desktop {
+
+class WebHost;
+
+class DesktopPet {
+public:
+    explicit DesktopPet(WebHost& host);
+    ~DesktopPet();
+
+    DesktopPet(const DesktopPet&) = delete;
+    DesktopPet& operator=(const DesktopPet&) = delete;
+
+private:
+    struct Impl;
+    // DesktopPet owns the state; WebView callbacks briefly share it via weak locks.
+    std::shared_ptr<Impl> impl_;
+};
+
+} // namespace acecode::desktop
diff --git a/src/apps/desktop/desktop_pet_layout.cpp b/src/apps/desktop/desktop_pet_layout.cpp
new file mode 100644
index 000000000..951fe7373
--- /dev/null
+++ b/src/apps/desktop/desktop_pet_layout.cpp
@@ -0,0 +1,206 @@
+#include "desktop_pet_layout.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+#include <nlohmann/json.hpp>
+
+namespace acecode::desktop {
+namespace {
+
+constexpr int kBaseDpi = 96;
+constexpr int kEdgeMarginDip = 8;
+constexpr double kMinLogicalScale = 0.5;
+constexpr double kMaxWorkAreaFraction = 0.9;
+// 命中区域比房间轮廓外扩的场景像素数:盖住描边和轮廓线的取整误差。
+constexpr int kHitMargin = 3;
+
+// 与 agent_office_pet.html 里的场景常量一致:VIEW 原点 (156, 54),
+// 房间世界坐标 x∈[-3, 88]、y∈[-3, 72](含墙厚),地台底 z=-4,墙顶 z=40。
+constexpr int kViewOriginX = 156;
+constexpr int kViewOriginY = 54 + kDesktopPetToolbarHeight;
+constexpr int kRoomMinX = -3;
+constexpr int kRoomMaxX = 88;
+constexpr int kRoomMinY = -3;
+constexpr int kRoomMaxY = 72;
+constexpr int kRoomBottomZ = -4;
+constexpr int kWallTopZ = 40;
+
+int effective_dpi(int dpi) {
+    return dpi > 0 ? dpi : kBaseDpi;
+}
+
+// 等距投影,同页面里的 P():屏幕 x = ox + 2(x − y),屏幕 y = oy + x + y − z。
+DesktopPetPoint project(int x, int y, int z) {
+    return {kViewOriginX + 2 * (x - y), kViewOriginY + x + y - z};
+}
+
+DesktopPetRect sized_at(int x, int y, double scale) {
+    return {x, y,
+            static_cast<int>(std::lround(kDesktopPetSceneWidth * scale)),
+            static_cast<int>(std::lround(kDesktopPetSceneHeight * scale))};
+}
+
+int clamp_origin(int value, int size, int area_start, int area_size) {
+    const int max_value = area_start + area_size - size;
+    return std::max(area_start, std::min(value, max_value));
+}
+
+double scale_for(int dpi, const DesktopPetRect& work_area, double preferred_logical_scale) {
+    if (preferred_logical_scale > 0.0) {
+        return clamp_desktop_pet_scale(
+            preferred_logical_scale * effective_dpi(dpi) / kBaseDpi, dpi, work_area);
+    }
+    return desktop_pet_scale(dpi, work_area.width, work_area.height);
+}
+
+} // namespace
+
+int desktop_pet_scale(int dpi, int work_width, int work_height) {
+    // round(dpi / 96 × 1.25),整数运算避免浮点边界抖动。
+    int scale = std::max(1, (effective_dpi(dpi) * 125 + 4800) / 9600);
+    while (scale > 1 &&
+           (kDesktopPetSceneWidth * scale > work_width / 2 ||
+            kDesktopPetSceneHeight * scale > work_height / 2)) {
+        --scale;
+    }
+    return scale;
+}
+
+double clamp_desktop_pet_scale(double scale, int dpi, const DesktopPetRect& work_area) {
+    const double min_scale = kMinLogicalScale * effective_dpi(dpi) / kBaseDpi;
+    double max_scale = std::min(
+        work_area.width * kMaxWorkAreaFraction / kDesktopPetSceneWidth,
+        work_area.height * kMaxWorkAreaFraction / kDesktopPetSceneHeight);
+    if (!(max_scale > min_scale)) max_scale = min_scale;   // 工作区异常小时只保证下限
+    if (!std::isfinite(scale)) return min_scale;
+    return std::clamp(scale, min_scale, max_scale);
+}
+
+DesktopPetPlacement place_desktop_pet(const DesktopPetRect& work_area, int dpi,
+                                      double preferred_logical_scale) {
+    DesktopPetPlacement placement;
+    placement.scale = scale_for(dpi, work_area, preferred_logical_scale);
+    const int margin = (kEdgeMarginDip * effective_dpi(dpi) + kBaseDpi / 2) / kBaseDpi;
+    placement.window = sized_at(0, 0, placement.scale);
+    placement.window.x = clamp_origin(
+        work_area.x + work_area.width - placement.window.width - margin,
+        placement.window.width, work_area.x, work_area.width);
+    placement.window.y = clamp_origin(
+        work_area.y + work_area.height - placement.window.height - margin,
+        placement.window.height, work_area.y, work_area.height);
+    return placement;
+}
+
+DesktopPetPlacement resize_desktop_pet(const DesktopPetRect& current, int dpi,
+                                       const DesktopPetRect& work_area,
+                                       double preferred_logical_scale) {
+    DesktopPetPlacement placement;
+    placement.scale = scale_for(dpi, work_area, preferred_logical_scale);
+    placement.window = sized_at(current.x, current.y, placement.scale);
+    placement.window.x = clamp_origin(placement.window.x, placement.window.width,
+                                      work_area.x, work_area.width);
+    placement.window.y = clamp_origin(placement.window.y, placement.window.height,
+                                      work_area.y, work_area.height);
+    return placement;
+}
+
+DesktopPetPlacement scale_desktop_pet(const DesktopPetRect& current, double new_scale,
+                                      double anchor_fx, double anchor_fy,
+                                      const DesktopPetRect& work_area) {
+    anchor_fx = std::isfinite(anchor_fx) ? std::clamp(anchor_fx, 0.0, 1.0) : 1.0;
+    anchor_fy = std::isfinite(anchor_fy) ? std::clamp(anchor_fy, 0.0, 1.0) : 1.0;
+    const double anchor_x = current.x + anchor_fx * current.width;
+    const double anchor_y = current.y + anchor_fy * current.height;
+    DesktopPetPlacement placement;
+    placement.scale = new_scale;
+    placement.window = sized_at(0, 0, new_scale);
+    placement.window.x = clamp_origin(
+        static_cast<int>(std::lround(anchor_x - anchor_fx * placement.window.width)),
+        placement.window.width, work_area.x, work_area.width);
+    placement.window.y = clamp_origin(
+        static_cast<int>(std::lround(anchor_y - anchor_fy * placement.window.height)),
+        placement.window.height, work_area.y, work_area.height);
+    return placement;
+}
+
+std::vector<DesktopPetPoint> desktop_pet_hit_polygon(double scale) {
+    if (!(scale > 0.0)) scale = 1.0;
+    // 房间外包六边形,从左墙顶端起顺时针:左墙顶 → 墙角顶 → 后墙右顶 →
+    // 地台右角 → 地台前角 → 地台左角。每个点向外推 kHitMargin。
+    const DesktopPetPoint wall_left = project(kRoomMinX, kRoomMaxY, kWallTopZ);
+    const DesktopPetPoint wall_corner = project(kRoomMinX, kRoomMinY, kWallTopZ);
+    const DesktopPetPoint wall_right = project(kRoomMaxX, kRoomMinY, kWallTopZ);
+    const DesktopPetPoint floor_right = project(kRoomMaxX, kRoomMinY, kRoomBottomZ);
+    const DesktopPetPoint floor_front = project(kRoomMaxX, kRoomMaxY, kRoomBottomZ);
+    const DesktopPetPoint floor_left = project(kRoomMinX, kRoomMaxY, kRoomBottomZ);
+    const std::vector<DesktopPetPoint> outline = {
+        {wall_left.x - kHitMargin, wall_left.y - kHitMargin},
+        {wall_corner.x, wall_corner.y - kHitMargin},
+        {wall_right.x + kHitMargin, wall_right.y - kHitMargin},
+        {floor_right.x + kHitMargin, floor_right.y + kHitMargin},
+        {floor_front.x, floor_front.y + kHitMargin},
+        {floor_left.x - kHitMargin, floor_left.y + kHitMargin},
+    };
+    std::vector<DesktopPetPoint> polygon;
+    polygon.reserve(outline.size());
+    for (const auto& point : outline) {
+        polygon.push_back({
+            static_cast<int>(std::lround(std::clamp(point.x, 0, kDesktopPetSceneWidth) * scale)),
+            static_cast<int>(std::lround(std::clamp(point.y, 0, kDesktopPetSceneHeight) * scale)),
+        });
+    }
+    return polygon;
+}
+
+namespace {
+bool overlay_from_json(const nlohmann::json& value, DesktopPetOverlay& out) {
+    if (!value.is_array() || value.size() != 4) return false;
+    for (std::size_t i = 0; i < 4; ++i) {
+        if (!value[i].is_number()) return false;
+        const double coordinate = value[i].get<double>();
+        if (!std::isfinite(coordinate)) return false;
+        out[i] = std::clamp(coordinate, 0.0, 1.0);
+    }
+    return out[2] > out[0] && out[3] > out[1];
+}
+} // namespace
+
+std::vector<DesktopPetOverlay> desktop_pet_overlays_from_message(const nlohmann::json& message) {
+    std::vector<DesktopPetOverlay> overlays;
+    if (!message.is_object()) return overlays;
+    DesktopPetOverlay rect{};
+    if (const auto it = message.find("rect"); it != message.end() && overlay_from_json(*it, rect)) {
+        overlays.push_back(rect);
+    }
+    if (const auto it = message.find("bubbles"); it != message.end() && it->is_array()) {
+        for (const auto& item : *it) {
+            if (overlays.size() >= kDesktopPetMaxOverlays) break;
+            if (overlay_from_json(item, rect)) overlays.push_back(rect);
+        }
+    }
+    return overlays;
+}
+
+bool desktop_pet_hit_test(double scale, int width, int height,
+                          const std::vector<DesktopPetOverlay>& overlays, double x, double y) {
+    if (width <= 0 || height <= 0 || x < 0 || y < 0 || x >= width || y >= height) return false;
+    if (!(scale > 0.0)) scale = 1.0;
+    if (y < kDesktopPetToolbarHeight * scale) return true;
+    for (const auto& overlay : overlays) {
+        if (x >= overlay[0] * width && x < overlay[2] * width &&
+            y >= overlay[1] * height && y < overlay[3] * height) {
+            return true;
+        }
+    }
+    // 偶奇规则判断点是否在房间多边形里。
+    const auto polygon = desktop_pet_hit_polygon(scale);
+    bool inside = false;
+    for (std::size_t i = 0, j = polygon.size() - 1; i < polygon.size(); j = i++) {
+        const double xi = polygon[i].x, yi = polygon[i].y, xj = polygon[j].x, yj = polygon[j].y;
+        if ((yi > y) != (yj > y) && x < (xj - xi) * (y - yi) / (yj - yi) + xi) inside = !inside;
+    }
+    return inside;
+}
+
+} // namespace acecode::desktop
diff --git a/src/apps/desktop/desktop_pet_layout.hpp b/src/apps/desktop/desktop_pet_layout.hpp
new file mode 100644
index 000000000..501baad13
--- /dev/null
+++ b/src/apps/desktop/desktop_pet_layout.hpp
@@ -0,0 +1,82 @@
+#pragma once
+
+// 桌面宠物(像素办公室 demo)窗口的纯几何计算,不依赖任何平台 API,
+// 由 desktop_pet.cpp 的 Win32 宿主调用,单测在 tests/desktop/desktop_pet_layout_test.cpp。
+//
+// 场景是 assets/desktop_pet/agent_office_pet.html 里 344×220 的像素画布。
+// 缩放倍数 scale = 每个场景像素占多少设备像素:首次运行取整数倍(像素最整齐),
+// 用户用滚轮 / 把手缩放后可以是任意小数,页面负责把非整数倍画得均匀。
+// 画布里房间以外(原来的草地)是透明的,命中区域只取房间轮廓,
+// 透明角落的点击会落到后面的窗口上。
+
+#include <array>
+#include <vector>
+
+#include <nlohmann/json_fwd.hpp>
+
+namespace acecode::desktop {
+
+inline constexpr int kDesktopPetSceneWidth = 344;
+inline constexpr int kDesktopPetSceneHeight = 252;
+inline constexpr int kDesktopPetToolbarHeight = 32;
+
+struct DesktopPetRect {
+    int x = 0;
+    int y = 0;
+    int width = 0;
+    int height = 0;
+};
+
+struct DesktopPetPoint {
+    int x = 0;
+    int y = 0;
+};
+
+struct DesktopPetPlacement {
+    DesktopPetRect window;
+    double scale = 1.0;
+};
+
+// 首次运行的默认倍数(整数)。目标是逻辑宽度约 430px(dpi/96 × 1.25 四舍五入),
+// 至少 1;放不下时逐级缩小,保证窗口不超过工作区宽/高的一半。
+int desktop_pet_scale(int dpi, int work_width, int work_height);
+
+// 用户缩放的上下限:最小是逻辑 0.5 倍(172 逻辑像素宽),最大不超过工作区宽/高的 90%。
+// 非法输入(NaN、负数)按下限处理。
+double clamp_desktop_pet_scale(double scale, int dpi, const DesktopPetRect& work_area);
+
+// 把窗口贴在工作区(已扣除任务栏)右下角,留 8 个逻辑像素边距。
+// preferred_logical_scale > 0 表示用户调过大小(逻辑倍数,与 DPI 无关),否则用默认整数倍。
+DesktopPetPlacement place_desktop_pet(const DesktopPetRect& work_area, int dpi,
+                                      double preferred_logical_scale = 0.0);
+
+// 保持左上角不动、只按新 DPI 换尺寸;用户拖动过之后 DPI 变化走这条。
+DesktopPetPlacement resize_desktop_pet(const DesktopPetRect& current, int dpi,
+                                       const DesktopPetRect& work_area,
+                                       double preferred_logical_scale = 0.0);
+
+// 缩放到 new_scale(调用方先 clamp):窗口内相对位置 (anchor_fx, anchor_fy) 那一点
+// 在屏幕上保持不动,再把整个窗口夹回工作区。停靠右下角时锚点取 (1, 1)。
+DesktopPetPlacement scale_desktop_pet(const DesktopPetRect& current, double new_scale,
+                                      double anchor_fx, double anchor_fy,
+                                      const DesktopPetRect& work_area);
+
+// 房间轮廓(地台 + 两面墙的外包六边形)外扩少量边距,按 scale 换成窗口内设备像素坐标,
+// 顺时针,已夹在窗口范围内。
+std::vector<DesktopPetPoint> desktop_pet_hit_polygon(double scale);
+
+// 页面浮层(成员列表、提示、状态气泡)在窗口里的矩形,按窗口宽高的比例给出:
+// {left, top, right, bottom},均在 [0, 1]。
+using DesktopPetOverlay = std::array<double, 4>;
+inline constexpr std::size_t kDesktopPetMaxOverlays = 24;
+
+// 解析页面发来的 {"type":"overlay","rect":[...]|null,"bubbles":[[...],...]}:
+// 非数字 / 非有限值 / 空矩形整条丢弃,坐标夹到 [0, 1],最多保留 kDesktopPetMaxOverlays 个。
+std::vector<DesktopPetOverlay> desktop_pet_overlays_from_message(const nlohmann::json& message);
+
+// 窗口内一点 (x, y)(设备像素,左上为原点)是否落在桌宠上:房间轮廓、顶部控制条或任一浮层。
+// 透明区域返回 false,点击应穿透到后面的窗口。
+bool desktop_pet_hit_test(double scale, int width, int height,
+                          const std::vector<DesktopPetOverlay>& overlays, double x, double y);
+
+} // namespace acecode::desktop
diff --git a/src/apps/desktop/desktop_pet_mac.mm b/src/apps/desktop/desktop_pet_mac.mm
new file mode 100644
index 000000000..89ed3af38
--- /dev/null
+++ b/src/apps/desktop/desktop_pet_mac.mm
@@ -0,0 +1,754 @@
+// macOS 版桌面 agent 办公室:与 desktop_pet.cpp(Windows)共用同一份页面
+// (assets/desktop_pet/agent_office_pet.html,构建期嵌进可执行文件)、同一套桥协议
+// 和 desktop_pet_layout 的几何计算。
+//
+// 窗口是透明、置顶、不抢焦点的 NSPanel(非激活面板,不能成为 key window),
+// 里面放一个 WKWebView。页面按 WebView2 的 window.chrome.webview 写成,这里在
+// 文档开始前注入一个同名垫片:postMessage 转给 WKScriptMessageHandler,宿主经
+// window.__acePetDeliver 把消息派给页面的 message 监听器,页面代码无需区分平台。
+//
+// macOS 没有 SetWindowRgn:透明区域的点击穿透靠定时检测鼠标是否落在房间轮廓、
+// 控制条或页面上报的浮层里,再切换 ignoresMouseEvents。拖动 / 把手缩放同样由
+// 定时器跟随鼠标,不依赖 WebKit 把鼠标事件交还给窗口。
+//
+// 坐标:Cocoa 屏幕坐标原点在左下;desktop_pet_layout 按左上原点、设备像素计算。
+// 这里统一换成左上原点的「点」,并把 dpi 固定为 96(1 点 = 1 个逻辑像素,
+// Retina 的倍率由 WebKit 按 devicePixelRatio 处理)。
+//
+// 本文件用 ARC 编译(cmake/acecode_desktop.cmake 单独加 -fobjc-arc)。
+
+#include "desktop_pet.hpp"
+#include "web_host.hpp"
+
+#include "desktop_pet_layout.hpp"
+#include "platform/native_ui/strings.hpp"
+
+#include "utils/logger.hpp"
+
+#import <AppKit/AppKit.h>
+#import <WebKit/WebKit.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstddef>
+#include <cstdio>
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include <nlohmann/json.hpp>
+
+#if !__has_feature(objc_arc)
+#error "desktop_pet_mac.mm must be compiled with -fobjc-arc"
+#endif
+
+@class ACECodeDesktopPetBridge;
+@class ACECodeDesktopPetMenuTarget;
+
+namespace acecode {
+// cmake/acecode_desktop.cmake 用 acecode_bin2cpp.cmake 把页面嵌进可执行文件。
+const unsigned char* desktop_pet_page_data();
+std::size_t desktop_pet_page_size();
+} // namespace acecode
+
+namespace acecode::desktop {
+namespace {
+
+constexpr int kLogicalDpi = 96;
+constexpr double kDefaultLogicalScale = 1.25;   // 约 430×315 点,与 Windows 150% 下的逻辑大小相当
+constexpr double kZoomStep = 1.1;
+constexpr NSTimeInterval kHoverPollSeconds = 1.0 / 30.0;
+constexpr NSTimeInterval kGesturePollSeconds = 1.0 / 60.0;
+constexpr NSTimeInterval kRevealFallbackSeconds = 3.0;
+constexpr std::size_t kMaxSnapshotBytes = 512 * 1024;
+constexpr std::size_t kMaxActionBytes = 16384;
+
+enum MenuCommand : NSInteger { kMenuDock = 1, kMenuHide, kMenuZoomIn, kMenuZoomOut, kMenuResetSize };
+
+// 页面以 WebView2 的接口写成;这里在文档开始前补一个同名实现。
+constexpr const char* kBridgeShim = R"JS((() => {
+  const listeners = [];
+  const handler = window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.acePet;
+  if (!handler) return;
+  window.chrome = window.chrome || {};
+  window.chrome.webview = {
+    postMessage: value => handler.postMessage(typeof value === 'string' ? value : JSON.stringify(value)),
+    addEventListener: (type, listener) => { if (type === 'message') listeners.push(listener); },
+    removeEventListener: (type, listener) => { const i = listeners.indexOf(listener); if (i >= 0) listeners.splice(i, 1); },
+  };
+  window.__acePetDeliver = data => { for (const listener of listeners.slice()) { try { listener({ data }); } catch (e) {} } };
+})();)JS";
+
+bool desktop_pet_disabled_by_env() {
+    const char* value = std::getenv("ACECODE_DESKTOP_PET");
+    if (!value) return false;
+    const std::string text(value);
+    return text == "0" || text == "off" || text == "false" || text == "no";
+}
+
+bool chinese_ui() {
+    return native_locale().rfind("zh", 0) == 0;
+}
+
+NSString* ns_string(const std::string& value) {
+    NSString* text = [[NSString alloc] initWithBytes:value.data()
+                                              length:value.size()
+                                            encoding:NSUTF8StringEncoding];
+    return text ? text : @"";
+}
+
+// 不放进 ACECode 数据目录:数据目录迁移会把持续写入的文件当成活文件。
+std::filesystem::path pet_root_dir() {
+    NSArray<NSURL*>* urls = [[NSFileManager defaultManager]
+        URLsForDirectory:NSApplicationSupportDirectory inDomains:NSUserDomainMask];
+    NSURL* base = urls.firstObject;
+    const char* path = base ? base.fileSystemRepresentation : nullptr;
+    std::filesystem::path root = path ? std::filesystem::path(path)
+                                      : std::filesystem::temp_directory_path();
+    return root / "ACECode" / "desktop-pet";
+}
+
+double load_logical_scale() {
+    std::ifstream in(pet_root_dir() / "settings.json");
+    if (!in) return 0.0;
+    const auto json = nlohmann::json::parse(in, nullptr, false);
+    if (json.is_discarded() || !json.is_object() || !json.contains("scale") || !json["scale"].is_number()) return 0.0;
+    const double scale = json["scale"].get<double>();
+    return std::isfinite(scale) && scale > 0.0 ? scale : 0.0;
+}
+
+void save_logical_scale(double scale) {
+    std::error_code ec;
+    std::filesystem::create_directories(pet_root_dir(), ec);
+    nlohmann::json json = nlohmann::json::object();
+    if (scale > 0.0) json["scale"] = std::round(scale * 1000.0) / 1000.0;
+    std::ofstream out(pet_root_dir() / "settings.json", std::ios::trunc);
+    if (out) out << json.dump();
+}
+
+// 全局坐标翻转以主屏(菜单栏所在的屏)高度为准。
+CGFloat flip_height() {
+    NSScreen* primary = NSScreen.screens.firstObject;
+    return primary ? primary.frame.size.height : 0.0;
+}
+
+DesktopPetRect top_left_rect(NSRect rect) {
+    return {static_cast<int>(std::lround(rect.origin.x)),
+            static_cast<int>(std::lround(flip_height() - (rect.origin.y + rect.size.height))),
+            static_cast<int>(std::lround(rect.size.width)),
+            static_cast<int>(std::lround(rect.size.height))};
+}
+
+NSRect cocoa_rect(const DesktopPetRect& rect) {
+    return NSMakeRect(rect.x, flip_height() - (rect.y + rect.height), rect.width, rect.height);
+}
+
+} // namespace
+
+// GUI 线程上的全部状态;ObjC 回调只持有它的 weak_ptr。
+class PetController : public std::enable_shared_from_this<PetController> {
+public:
+    explicit PetController(WebHost& owner) : host_(owner) {}
+    virtual ~PetController() { close(); }
+
+    void bind_bridge();
+    bool start();
+    void close();
+
+    void on_web_message(const std::string& message);
+    void navigation_finished(bool success);
+    void web_process_terminated();
+    void poll_hover();
+    void poll_gesture();
+    void menu_command(NSInteger command);
+    void screens_changed();
+
+private:
+    void publish_snapshot();
+    void deliver(const nlohmann::json& value);
+    void office_action(const std::string& message);
+    void reveal();
+    void apply_placement(const DesktopPetPlacement& next);
+    DesktopPetRect window_rect() const;
+    DesktopPetRect work_area() const;
+    void notify_size();
+    void apply_scale(double scale, double fx, double fy);
+    void zoom_by(int steps, double fx, double fy);
+    void reset_size();
+    void dock_to_corner();
+    void begin_gesture(bool resize);
+    void end_gesture();
+    void show_menu();
+    void load_page();
+    double current_scale() const;
+
+    WebHost& host_;   // DesktopPet is destroyed before this host.
+    nlohmann::json office_snapshot_ = {{"follow", true}};
+    std::vector<DesktopPetOverlay> overlays_;
+    NSPanel* panel_ = nil;
+    WKWebView* webview_ = nil;
+    WKUserContentController* content_ = nil;
+    ACECodeDesktopPetBridge* bridge_ = nil;
+    ACECodeDesktopPetMenuTarget* menu_target_ = nil;
+    id screen_observer_ = nil;
+    NSTimer* hover_timer_ = nil;
+    NSTimer* gesture_timer_ = nil;
+    NSTimer* reveal_timer_ = nil;
+    double logical_scale_ = 0.0;   // 用户调过的大小,0 = 默认
+    bool page_ready_ = false;
+    bool revealed_ = false;
+    bool user_moved_ = false;
+    bool closed_ = false;
+    bool resizing_ = false;
+    bool dragging_ = false;
+    NSPoint gesture_mouse_ = NSZeroPoint;
+    DesktopPetRect gesture_start_{};
+};
+
+} // namespace acecode::desktop
+
+using acecode::desktop::PetController;
+
+// 非激活面板:点击不会把 ACECode 主窗口的键盘焦点抢走。
+@interface ACECodeDesktopPetPanel : NSPanel
+@end
+
+@implementation ACECodeDesktopPetPanel
+- (BOOL)canBecomeKeyWindow {
+    return NO;
+}
+- (BOOL)canBecomeMainWindow {
+    return NO;
+}
+@end
+
+// 面板不会成为 key window,第一下点击就要交给页面,而不是只用来激活窗口。
+@interface ACECodeDesktopPetWebView : WKWebView
+@end
+
+@implementation ACECodeDesktopPetWebView
+- (BOOL)acceptsFirstMouse:(NSEvent*)event {
+    (void)event;
+    return YES;
+}
+@end
+
+@interface ACECodeDesktopPetBridge : NSObject <WKScriptMessageHandler, WKNavigationDelegate>
+- (instancetype)initWithController:(const std::weak_ptr<PetController>&)controller;
+@end
+
+@implementation ACECodeDesktopPetBridge {
+    std::weak_ptr<PetController> _controller;
+}
+
+- (instancetype)initWithController:(const std::weak_ptr<PetController>&)controller {
+    if ((self = [super init])) _controller = controller;
+    return self;
+}
+
+- (void)userContentController:(WKUserContentController*)userContentController
+      didReceiveScriptMessage:(WKScriptMessage*)message {
+    (void)userContentController;
+    if (![message.body isKindOfClass:[NSString class]]) return;
+    const char* utf8 = [(NSString*)message.body UTF8String];
+    if (!utf8) return;
+    if (const auto controller = _controller.lock()) controller->on_web_message(utf8);
+}
+
+- (void)webView:(WKWebView*)webView didFinishNavigation:(WKNavigation*)navigation {
+    (void)webView;
+    (void)navigation;
+    if (const auto controller = _controller.lock()) controller->navigation_finished(true);
+}
+
+- (void)webView:(WKWebView*)webView didFailNavigation:(WKNavigation*)navigation withError:(NSError*)error {
+    (void)webView;
+    (void)navigation;
+    (void)error;
+    if (const auto controller = _controller.lock()) controller->navigation_finished(false);
+}
+
+- (void)webView:(WKWebView*)webView
+    didFailProvisionalNavigation:(WKNavigation*)navigation
+                       withError:(NSError*)error {
+    (void)webView;
+    (void)navigation;
+    (void)error;
+    if (const auto controller = _controller.lock()) controller->navigation_finished(false);
+}
+
+- (void)webViewWebContentProcessDidTerminate:(WKWebView*)webView {
+    (void)webView;
+    if (const auto controller = _controller.lock()) controller->web_process_terminated();
+}
+@end
+
+@interface ACECodeDesktopPetMenuTarget : NSObject
+- (instancetype)initWithController:(const std::weak_ptr<PetController>&)controller;
+- (void)choose:(NSMenuItem*)item;
+@end
+
+@implementation ACECodeDesktopPetMenuTarget {
+    std::weak_ptr<PetController> _controller;
+}
+
+- (instancetype)initWithController:(const std::weak_ptr<PetController>&)controller {
+    if ((self = [super init])) _controller = controller;
+    return self;
+}
+
+- (void)choose:(NSMenuItem*)item {
+    if (const auto controller = _controller.lock()) controller->menu_command(item.tag);
+}
+@end
+
+namespace acecode::desktop {
+
+void PetController::bind_bridge() {
+    const std::weak_ptr<PetController> weak = weak_from_this();
+    host_.bind("aceDesktop_updateOffice", [weak](const std::string& request) {
+        const auto self = weak.lock();
+        if (!self || self->closed_ || request.size() > kMaxSnapshotBytes) return std::string("false");
+        try {
+            const auto args = nlohmann::json::parse(request);
+            if (!args.is_array() || args.size() != 1 || !args[0].is_string()) return std::string("false");
+            const auto value = nlohmann::json::parse(args[0].get<std::string>());
+            if (!value.is_object() || value.value("version", 0) != 1 ||
+                !value.contains("agents") || !value["agents"].is_array() ||
+                !value.contains("offices") || !value["offices"].is_array() || value["offices"].size() > 5) {
+                return std::string("false");
+            }
+            self->office_snapshot_ = value;
+            self->publish_snapshot();
+            return std::string("true");
+        } catch (...) {
+            return std::string("false");
+        }
+    });
+    host_.bind("aceDesktop_getOfficeState", [weak](const std::string&) {
+        const auto self = weak.lock();
+        return self && !self->closed_ ? self->office_snapshot_.dump() : std::string("{}");
+    });
+}
+
+bool PetController::start() {
+    logical_scale_ = load_logical_scale();
+    const DesktopPetPlacement placement = place_desktop_pet(
+        work_area(), kLogicalDpi, logical_scale_ > 0.0 ? logical_scale_ : kDefaultLogicalScale);
+
+    panel_ = [[ACECodeDesktopPetPanel alloc]
+        initWithContentRect:cocoa_rect(placement.window)
+                  styleMask:NSWindowStyleMaskBorderless | NSWindowStyleMaskNonactivatingPanel
+                    backing:NSBackingStoreBuffered
+                      defer:NO];
+    if (!panel_) {
+        LOG_WARN("[desktop-pet] failed to create the macOS panel");
+        return false;
+    }
+    panel_.releasedWhenClosed = NO;
+    panel_.opaque = NO;
+    panel_.backgroundColor = NSColor.clearColor;
+    panel_.hasShadow = NO;
+    panel_.level = NSFloatingWindowLevel;
+    panel_.floatingPanel = YES;
+    panel_.hidesOnDeactivate = NO;
+    panel_.becomesKeyOnlyIfNeeded = YES;
+    panel_.movableByWindowBackground = NO;
+    panel_.acceptsMouseMovedEvents = YES;
+    panel_.ignoresMouseEvents = YES;   // 首帧之前完全透明,也不挡点击
+    panel_.alphaValue = 0.0;
+    panel_.collectionBehavior = NSWindowCollectionBehaviorCanJoinAllSpaces |
+                                NSWindowCollectionBehaviorFullScreenAuxiliary |
+                                NSWindowCollectionBehaviorStationary |
+                                NSWindowCollectionBehaviorIgnoresCycle;
+
+    const std::weak_ptr<PetController> weak = weak_from_this();
+    bridge_ = [[ACECodeDesktopPetBridge alloc] initWithController:weak];
+    menu_target_ = [[ACECodeDesktopPetMenuTarget alloc] initWithController:weak];
+
+    content_ = [[WKUserContentController alloc] init];
+    WKUserScript* shim = [[WKUserScript alloc] initWithSource:ns_string(kBridgeShim)
+                                                injectionTime:WKUserScriptInjectionTimeAtDocumentStart
+                                             forMainFrameOnly:YES];
+    [content_ addUserScript:shim];
+    [content_ addScriptMessageHandler:bridge_ name:@"acePet"];
+
+    WKWebViewConfiguration* configuration = [[WKWebViewConfiguration alloc] init];
+    configuration.userContentController = content_;
+    // 页面是嵌入的离线资源,不需要持久的网站数据。
+    configuration.websiteDataStore = [WKWebsiteDataStore nonPersistentDataStore];
+
+    const NSRect bounds = NSMakeRect(0, 0, placement.window.width, placement.window.height);
+    webview_ = [[ACECodeDesktopPetWebView alloc] initWithFrame:bounds configuration:configuration];
+    if (!webview_) {
+        LOG_WARN("[desktop-pet] failed to create the macOS WKWebView");
+        return false;
+    }
+    webview_.navigationDelegate = bridge_;
+    webview_.autoresizingMask = NSViewWidthSizable | NSViewHeightSizable;
+    webview_.allowsMagnification = NO;
+    webview_.allowsBackForwardNavigationGestures = NO;
+    // 透明背景:页面里没画东西的地方直接透出桌面。
+    [webview_ setValue:@NO forKey:@"drawsBackground"];
+    if (@available(macOS 12.0, *)) webview_.underPageBackgroundColor = NSColor.clearColor;
+    panel_.contentView = webview_;
+
+    screen_observer_ = [[NSNotificationCenter defaultCenter]
+        addObserverForName:NSApplicationDidChangeScreenParametersNotification
+                    object:nil
+                     queue:[NSOperationQueue mainQueue]
+                usingBlock:^(NSNotification* note) {
+                    (void)note;
+                    if (const auto self = weak.lock()) self->screens_changed();
+                }];
+
+    hover_timer_ = [NSTimer timerWithTimeInterval:kHoverPollSeconds
+                                          repeats:YES
+                                            block:^(NSTimer* timer) {
+                                                const auto self = weak.lock();
+                                                if (self) self->poll_hover();
+                                                else [timer invalidate];
+                                            }];
+    [[NSRunLoop mainRunLoop] addTimer:hover_timer_ forMode:NSRunLoopCommonModes];
+
+    // 透明地挂上屏幕,让 WebKit 按可见窗口渲染首帧;页面发 ready 后再显形。
+    [panel_ orderFrontRegardless];
+    load_page();
+    return true;
+}
+
+void PetController::load_page() {
+    const std::string page(reinterpret_cast<const char*>(acecode::desktop_pet_page_data()),
+                           acecode::desktop_pet_page_size());
+    [webview_ loadHTMLString:ns_string(page) baseURL:nil];
+}
+
+void PetController::navigation_finished(bool success) {
+    if (closed_ || revealed_) return;
+    if (!success) {
+        LOG_WARN("[desktop-pet] page navigation failed");
+        close();
+        return;
+    }
+    if (reveal_timer_) return;
+    const std::weak_ptr<PetController> weak = weak_from_this();
+    reveal_timer_ = [NSTimer scheduledTimerWithTimeInterval:kRevealFallbackSeconds
+                                                    repeats:NO
+                                                      block:^(NSTimer* timer) {
+                                                          (void)timer;
+                                                          const auto self = weak.lock();
+                                                          if (!self || self->revealed_) return;
+                                                          LOG_WARN("[desktop-pet] page ready signal missing; revealing after timeout");
+                                                          self->reveal();
+                                                      }];
+}
+
+void PetController::web_process_terminated() {
+    if (closed_) return;
+    // WebContent 进程被系统回收后页面是空白的:重新加载,ready 后重发快照。
+    LOG_WARN("[desktop-pet] web content process terminated; reloading");
+    page_ready_ = false;
+    load_page();
+}
+
+void PetController::reveal() {
+    if (revealed_ || closed_ || !panel_) return;
+    revealed_ = true;
+    [reveal_timer_ invalidate];
+    reveal_timer_ = nil;
+    panel_.alphaValue = 1.0;
+    [panel_ orderFrontRegardless];
+    const auto rect = window_rect();
+    LOG_INFO("[desktop-pet] shown at " + std::to_string(rect.x) + "," + std::to_string(rect.y) +
+             " size " + std::to_string(rect.width) + "x" + std::to_string(rect.height));
+}
+
+void PetController::deliver(const nlohmann::json& value) {
+    if (closed_ || !webview_) return;
+    const std::string script = "window.__acePetDeliver&&window.__acePetDeliver(" + value.dump() + ");";
+    [webview_ evaluateJavaScript:ns_string(script) completionHandler:nil];
+}
+
+void PetController::publish_snapshot() {
+    if (closed_ || !page_ready_ || !office_snapshot_.contains("version")) return;
+    deliver(office_snapshot_);
+}
+
+void PetController::on_web_message(const std::string& message) {
+    if (closed_ || !panel_) return;
+    if (message == "ready") {
+        page_ready_ = true;
+        reveal();
+        publish_snapshot();
+    } else if (!message.empty() && message.front() == '{') {
+        office_action(message);
+    } else if (message == "drag") {
+        begin_gesture(false);
+    } else if (message == "resize") {
+        begin_gesture(true);
+    } else if (message == "menu") {
+        // 回到下一轮事件循环再弹菜单,不在 WebKit 的回调里进入模态菜单循环。
+        const std::weak_ptr<PetController> weak = weak_from_this();
+        dispatch_async(dispatch_get_main_queue(), ^{
+            if (const auto self = weak.lock()) self->show_menu();
+        });
+    } else if (message == "size-reset") {
+        reset_size();
+    } else if (message.rfind("zoom ", 0) == 0) {
+        int steps = 0;
+        double fx = 1.0, fy = 1.0;
+        if (std::sscanf(message.c_str() + 5, "%d %lf %lf", &steps, &fx, &fy) >= 1) zoom_by(steps, fx, fy);
+    }
+}
+
+void PetController::office_action(const std::string& message) {
+    if (message.size() > kMaxActionBytes) return;
+    const auto value = nlohmann::json::parse(message, nullptr, false);
+    if (!value.is_object()) return;
+    const auto type_field = value.find("type");
+    if (type_field == value.end() || !type_field->is_string()) return;
+    const auto type = type_field->get<std::string>();
+    if (type == "overlay") {
+        overlays_ = desktop_pet_overlays_from_message(value);
+        return;
+    }
+    if (type != "select" && type != "follow" && type != "open") return;
+    host_.eval("window.dispatchEvent(new CustomEvent('ace-desktop-office-action',{detail:" +
+               value.dump() + "}));");
+}
+
+DesktopPetRect PetController::window_rect() const {
+    return panel_ ? top_left_rect(panel_.frame) : DesktopPetRect{};
+}
+
+DesktopPetRect PetController::work_area() const {
+    NSScreen* screen = panel_ && panel_.screen ? panel_.screen : NSScreen.mainScreen;
+    if (!screen) screen = NSScreen.screens.firstObject;
+    return screen ? top_left_rect(screen.visibleFrame) : DesktopPetRect{0, 0, 1440, 900};
+}
+
+double PetController::current_scale() const {
+    const auto rect = window_rect();
+    return rect.width > 0 ? rect.width / static_cast<double>(kDesktopPetSceneWidth) : 1.0;
+}
+
+void PetController::apply_placement(const DesktopPetPlacement& next) {
+    if (!panel_) return;
+    [panel_ setFrame:cocoa_rect(next.window) display:YES];
+}
+
+void PetController::notify_size() {
+    const double base = kDefaultLogicalScale;
+    const int percent = static_cast<int>(std::lround(current_scale() / base * 100.0));
+    deliver("size " + std::to_string(percent));
+}
+
+void PetController::apply_scale(double scale, double fx, double fy) {
+    const DesktopPetRect work = work_area();
+    const double clamped = clamp_desktop_pet_scale(scale, kLogicalDpi, work);
+    apply_placement(scale_desktop_pet(window_rect(), clamped, fx, fy, work));
+    logical_scale_ = clamped;
+    notify_size();
+}
+
+void PetController::zoom_by(int steps, double fx, double fy) {
+    if (!revealed_ || closed_ || steps == 0) return;
+    // 停在右下角时锚在右下角(缩放后还贴着角);拖动过之后以鼠标所在点为中心。
+    if (!user_moved_) { fx = 1.0; fy = 1.0; }
+    apply_scale(current_scale() * std::pow(kZoomStep, steps), fx, fy);
+    save_logical_scale(logical_scale_);
+}
+
+void PetController::reset_size() {
+    if (!revealed_ || closed_) return;
+    logical_scale_ = 0.0;
+    save_logical_scale(0.0);
+    if (!user_moved_) dock_to_corner();
+    else apply_placement(scale_desktop_pet(window_rect(), kDefaultLogicalScale, 1.0, 1.0, work_area()));
+    notify_size();
+}
+
+void PetController::dock_to_corner() {
+    apply_placement(place_desktop_pet(work_area(), kLogicalDpi,
+                                      logical_scale_ > 0.0 ? logical_scale_ : kDefaultLogicalScale));
+}
+
+void PetController::screens_changed() {
+    if (closed_ || !revealed_) return;
+    if (!user_moved_) {
+        dock_to_corner();
+        return;
+    }
+    // 拖到别处后换了显示器排列:只把窗口夹回当前工作区。
+    apply_placement(scale_desktop_pet(window_rect(), current_scale(), 0.0, 0.0, work_area()));
+}
+
+void PetController::begin_gesture(bool resize) {
+    if (!revealed_ || closed_ || dragging_ || resizing_) return;
+    dragging_ = !resize;
+    resizing_ = resize;
+    gesture_mouse_ = [NSEvent mouseLocation];
+    gesture_start_ = window_rect();
+    panel_.ignoresMouseEvents = NO;
+    const std::weak_ptr<PetController> weak = weak_from_this();
+    gesture_timer_ = [NSTimer timerWithTimeInterval:kGesturePollSeconds
+                                            repeats:YES
+                                              block:^(NSTimer* timer) {
+                                                  const auto self = weak.lock();
+                                                  if (self) self->poll_gesture();
+                                                  else [timer invalidate];
+                                              }];
+    [[NSRunLoop mainRunLoop] addTimer:gesture_timer_ forMode:NSRunLoopCommonModes];
+}
+
+void PetController::end_gesture() {
+    [gesture_timer_ invalidate];
+    gesture_timer_ = nil;
+    if (dragging_) user_moved_ = true;
+    if (resizing_) save_logical_scale(logical_scale_);
+    dragging_ = false;
+    resizing_ = false;
+}
+
+void PetController::poll_gesture() {
+    if (closed_ || (!dragging_ && !resizing_)) {
+        end_gesture();
+        return;
+    }
+    if (([NSEvent pressedMouseButtons] & 1) == 0) {
+        end_gesture();
+        return;
+    }
+    const NSPoint mouse = [NSEvent mouseLocation];
+    // 屏幕坐标 y 向上;换成左上原点后 y 方向取反。
+    const double dx = mouse.x - gesture_mouse_.x;
+    const double dy = gesture_mouse_.y - mouse.y;
+    if (dragging_) {
+        DesktopPetRect next = gesture_start_;
+        next.x += static_cast<int>(std::lround(dx));
+        next.y += static_cast<int>(std::lround(dy));
+        [panel_ setFrameOrigin:cocoa_rect(next).origin];
+        return;
+    }
+    // 把手在左上方:往左上拖变大、右下角不动;横竖两个方向取放大得多的那个。
+    const double by_x = gesture_start_.width - dx;
+    const double by_y = (gesture_start_.height - dy) * kDesktopPetSceneWidth /
+                        static_cast<double>(kDesktopPetSceneHeight);
+    const DesktopPetRect work = work_area();
+    const double scale = clamp_desktop_pet_scale(std::max(by_x, by_y) / kDesktopPetSceneWidth, kLogicalDpi, work);
+    const auto next = scale_desktop_pet(gesture_start_, scale, 1.0, 1.0, work);
+    const auto current = window_rect();
+    if (next.window.width == current.width && next.window.x == current.x && next.window.y == current.y) return;
+    apply_placement(next);
+    logical_scale_ = scale;
+    notify_size();
+}
+
+void PetController::poll_hover() {
+    if (closed_ || !panel_ || !revealed_) return;
+    if (dragging_ || resizing_) {
+        panel_.ignoresMouseEvents = NO;
+        return;
+    }
+    const NSPoint mouse = [NSEvent mouseLocation];
+    const NSRect frame = panel_.frame;
+    const double x = mouse.x - frame.origin.x;
+    const double y = frame.origin.y + frame.size.height - mouse.y;
+    const bool hit = desktop_pet_hit_test(current_scale(), static_cast<int>(frame.size.width),
+                                          static_cast<int>(frame.size.height), overlays_, x, y);
+    if (panel_.ignoresMouseEvents == hit) panel_.ignoresMouseEvents = !hit;
+}
+
+void PetController::show_menu() {
+    if (closed_ || !panel_) return;
+    const bool zh = chinese_ui();
+    NSMenu* menu = [[NSMenu alloc] initWithTitle:@""];
+    menu.autoenablesItems = NO;
+    ACECodeDesktopPetMenuTarget* target = menu_target_;
+    const auto add = [menu, target](NSString* title, NSInteger tag) {
+        NSMenuItem* item = [[NSMenuItem alloc] initWithTitle:title action:@selector(choose:) keyEquivalent:@""];
+        item.target = target;
+        item.tag = tag;
+        [menu addItem:item];
+    };
+    add(zh ? @"回到右下角" : @"Move to corner", kMenuDock);
+    [menu addItem:[NSMenuItem separatorItem]];
+    add(zh ? @"放大（也可以滚轮）" : @"Zoom in (or scroll)", kMenuZoomIn);
+    add(zh ? @"缩小" : @"Zoom out", kMenuZoomOut);
+    add(zh ? @"恢复默认大小" : @"Reset size", kMenuResetSize);
+    [menu addItem:[NSMenuItem separatorItem]];
+    add(zh ? @"隐藏桌面宠物" : @"Hide desktop pet", kMenuHide);
+    [menu popUpMenuPositioningItem:nil atLocation:[NSEvent mouseLocation] inView:nil];
+}
+
+void PetController::menu_command(NSInteger command) {
+    if (closed_) return;
+    switch (command) {
+    case kMenuDock:
+        user_moved_ = false;
+        dock_to_corner();
+        break;
+    case kMenuZoomIn: zoom_by(1, 0.5, 0.5); break;
+    case kMenuZoomOut: zoom_by(-1, 0.5, 0.5); break;
+    case kMenuResetSize: reset_size(); break;
+    case kMenuHide:
+        LOG_INFO("[desktop-pet] hidden from context menu");
+        close();
+        break;
+    default: break;
+    }
+}
+
+void PetController::close() {
+    if (closed_) return;
+    closed_ = true;
+    [hover_timer_ invalidate];
+    [gesture_timer_ invalidate];
+    [reveal_timer_ invalidate];
+    hover_timer_ = nil;
+    gesture_timer_ = nil;
+    reveal_timer_ = nil;
+    if (screen_observer_) [[NSNotificationCenter defaultCenter] removeObserver:screen_observer_];
+    screen_observer_ = nil;
+    // WKUserContentController 强引用消息处理器,不移除会连带页面一起泄漏。
+    [content_ removeScriptMessageHandlerForName:@"acePet"];
+    [content_ removeAllUserScripts];
+    webview_.navigationDelegate = nil;
+    [webview_ stopLoading];
+    [panel_ orderOut:nil];
+    [panel_ close];
+    webview_ = nil;
+    content_ = nil;
+    panel_ = nil;
+    bridge_ = nil;
+    menu_target_ = nil;
+}
+
+// DesktopPet 持有的实现:只是把控制器的所有权包起来。
+struct DesktopPet::Impl : PetController {
+    using PetController::PetController;
+};
+
+DesktopPet::DesktopPet(WebHost& host) {
+    if (desktop_pet_disabled_by_env()) {
+        LOG_INFO("[desktop-pet] disabled by ACECODE_DESKTOP_PET");
+        return;
+    }
+    auto impl = std::make_shared<Impl>(host);
+    impl->bind_bridge();
+    if (impl->start()) {
+        impl_ = std::move(impl);
+    } else {
+        impl->close();
+    }
+}
+
+DesktopPet::~DesktopPet() {
+    if (impl_) impl_->close();
+}
+
+} // namespace acecode::desktop
diff --git a/src/apps/desktop/main.cpp b/src/apps/desktop/main.cpp
index 7b8429a29..34969b08d 100644
--- a/src/apps/desktop/main.cpp
+++ b/src/apps/desktop/main.cpp
@@ -19,6 +19,7 @@
 #include "context_items.hpp"
 #include "platform/native_ui/context_picker.hpp"
 #include "desktop_about.hpp"
+#include "desktop_pet.hpp"
 #include "desktop_restart.hpp"
 #include "dpi_win.hpp"
 #include "edge_app_launcher.hpp"
@@ -2773,11 +2774,10 @@ int main(int argc, char** argv) {
         startup_timeline.snapshot_json() + ";\n");
     startup_navigation_started = true;
     host.navigate(url);
-    if (url == onboarding_url()) {
-        close_splash_once();
-    }
+    if (url == onboarding_url()) close_splash_once();
 
-    // 5. 阻塞主循环
+    // 5. GUI-owned office is destroyed before the WebHost.
+    DesktopPet desktop_pet(host);
     host.run();
 
     // 6. quit:写 last_active + stop_all
diff --git a/src/apps/web/handlers/channels_handler.cpp b/src/apps/web/handlers/channels_handler.cpp
new file mode 100644
index 000000000..c81ba83a7
--- /dev/null
+++ b/src/apps/web/handlers/channels_handler.cpp
@@ -0,0 +1,121 @@
+#include "channels_handler.hpp"
+
+#include "channels/core/platforms.hpp"
+
+#include <vector>
+
+namespace acecode::web {
+namespace {
+
+constexpr std::size_t kMaxCredentialBytes = 512;
+constexpr std::size_t kMaxPrincipalBytes = 300;
+
+std::string trim(const std::string& text) {
+    const auto begin = text.find_first_not_of(" \t\r\n");
+    if (begin == std::string::npos) return {};
+    const auto end = text.find_last_not_of(" \t\r\n");
+    return text.substr(begin, end - begin + 1);
+}
+
+int hex_digit(char c) {
+    if (c >= '0' && c <= '9') return c - '0';
+    if (c >= 'a' && c <= 'f') return c - 'a' + 10;
+    if (c >= 'A' && c <= 'F') return c - 'A' + 10;
+    return -1;
+}
+
+} // namespace
+
+bool is_channel_platform(const std::string& platform) {
+    return channels::core::find_platform_spec(platform) != nullptr;
+}
+
+bool parse_channel_enabled_request(const nlohmann::json& body, bool& enabled, std::string& error) {
+    if (!body.is_object() || !body.contains("enabled") || !body["enabled"].is_boolean()) {
+        error = "请求体需要 {\"enabled\": true 或 false}";
+        return false;
+    }
+    enabled = body["enabled"].get<bool>();
+    return true;
+}
+
+std::optional<nlohmann::json> parse_channel_credentials_request(const std::string& platform,
+                                                                 const nlohmann::json& body,
+                                                                 std::string& error) {
+    if (!body.is_object()) {
+        error = "请求体必须是 JSON 对象";
+        return std::nullopt;
+    }
+    const auto* spec = channels::core::find_platform_spec(platform);
+    if (!spec) {
+        error = "未知的消息通道平台";
+        return std::nullopt;
+    }
+    nlohmann::json credentials = nlohmann::json::object();
+    for (const auto& [key, value] : body.items()) {
+        bool known = false;
+        for (const auto& field : spec->fields) known = known || (field.user_input && field.key == key);
+        if (!known) {
+            error = "不支持的字段:" + key;
+            return std::nullopt;
+        }
+        if (!value.is_string()) {
+            error = "字段 " + key + " 必须是字符串";
+            return std::nullopt;
+        }
+        const auto text = trim(value.get<std::string>());
+        if (text.size() > kMaxCredentialBytes || text.find('\0') != std::string::npos) {
+            error = "字段 " + key + " 过长或包含非法字符";
+            return std::nullopt;
+        }
+        if (!text.empty()) {
+            credentials[key] = text;
+            continue;
+        }
+        // 可选字段允许显式提交空串表示清除;必填字段的空串表示沿用已保存的值,直接略过。
+        for (const auto& field : spec->fields)
+            if (field.key == key && !field.required) credentials[key] = "";
+    }
+    if (credentials.empty()) {
+        error = "请填写凭据";
+        return std::nullopt;
+    }
+    return credentials;
+}
+
+std::optional<std::string> decode_channel_principal(const std::string& raw) {
+    std::string out;
+    out.reserve(raw.size());
+    for (std::size_t i = 0; i < raw.size(); ++i) {
+        if (raw[i] == '%') {
+            if (i + 2 >= raw.size()) return std::nullopt;
+            const int hi = hex_digit(raw[i + 1]);
+            const int lo = hex_digit(raw[i + 2]);
+            if (hi < 0 || lo < 0) return std::nullopt;
+            out.push_back(static_cast<char>((hi << 4) | lo));
+            i += 2;
+        } else {
+            out.push_back(raw[i]);
+        }
+    }
+    if (out.empty() || out.size() > kMaxPrincipalBytes || out.find('\0') != std::string::npos) return std::nullopt;
+    const bool known_prefix =
+        out.rfind("user:", 0) == 0 || out.rfind("group:", 0) == 0 || out.rfind("member:", 0) == 0;
+    if (!known_prefix) return std::nullopt;
+    return out;
+}
+
+nlohmann::json channel_error_body(const std::string& code, const std::string& message) {
+    return {{"error", code}, {"message", message}};
+}
+
+void annotate_channel_bound(nlohmann::json& rows, const std::map<std::string, std::string>& bound) {
+    if (!rows.is_array() || bound.empty()) return;
+    for (auto& row : rows) {
+        if (!row.is_object() || !row.contains("id") || !row["id"].is_string()) continue;
+        const auto it = bound.find(row["id"].get<std::string>());
+        if (it != bound.end()) row["channel_bound"] = {{"platform", it->second}};
+    }
+}
+
+} // namespace acecode::web
diff --git a/src/apps/web/handlers/channels_handler.hpp b/src/apps/web/handlers/channels_handler.hpp
new file mode 100644
index 000000000..b74275222
--- /dev/null
+++ b/src/apps/web/handlers/channels_handler.hpp
@@ -0,0 +1,36 @@
+#pragma once
+
+// 消息通道(QQ / Telegram)REST 接口的纯函数部分:请求体校验、路径参数解码、
+// 错误体与会话列表的 channel_bound 标注。路由见 routes/routes_channels.cpp。
+
+#include <nlohmann/json.hpp>
+
+#include <map>
+#include <optional>
+#include <string>
+
+namespace acecode::web {
+
+bool is_channel_platform(const std::string& platform);
+
+// POST /api/channels/:platform/enabled  {"enabled": true|false}
+bool parse_channel_enabled_request(const nlohmann::json& body, bool& enabled, std::string& error);
+
+// PUT /api/channels/:platform/credentials
+// 只接受该平台已知的字段(QQ:app_id / app_secret;Telegram:token),值必须是字符串,
+// 去两端空白后不超过 512 字节。空字符串表示沿用已保存的值(设置页只拿得到尾号)。
+// 至少要有一个非空字段,否则报错。
+std::optional<nlohmann::json> parse_channel_credentials_request(const std::string& platform,
+                                                                 const nlohmann::json& body,
+                                                                 std::string& error);
+
+// DELETE /api/channels/:platform/access/:principal 的路径段:百分号解码后必须是
+// user: / group: / member: 前缀,不超过 300 字节。
+std::optional<std::string> decode_channel_principal(const std::string& raw);
+
+nlohmann::json channel_error_body(const std::string& code, const std::string& message);
+
+// 会话列表行:被 IM 会话绑定的会话加 channel_bound:{"platform": ...};其余行不加该字段。
+void annotate_channel_bound(nlohmann::json& rows, const std::map<std::string, std::string>& bound);
+
+} // namespace acecode::web
diff --git a/src/apps/web/routes/routes_channels.cpp b/src/apps/web/routes/routes_channels.cpp
new file mode 100644
index 000000000..1718cffbc
--- /dev/null
+++ b/src/apps/web/routes/routes_channels.cpp
@@ -0,0 +1,154 @@
+// routes_channels.cpp — 消息通道(QQ、微信、飞书、钉钉、Telegram、Discord、LINE;openspec add-desktop-im-channels design D12)
+//
+// 所有接口只接受本机直连(远程 Web 代理转发进来的 127.0.0.2 也拒绝,返回 403),
+// 并照常鉴权。凭据只回显尾号;扫码二维码内容只经本机 WS 推送,不写日志。
+#include "web/server_impl.hpp"
+#include "web/handlers/channels_handler.hpp"
+
+#include "channels/core/host.hpp"
+
+#include <chrono>
+#include <functional>
+#include <stdexcept>
+
+namespace acecode::web {
+using nlohmann::json;
+
+void WebServer::Impl::broadcast_local_event(const std::string& type, const json& payload) {
+    const auto now = std::chrono::duration_cast<std::chrono::milliseconds>(
+                         std::chrono::system_clock::now().time_since_epoch())
+                         .count();
+    const auto text = json{{"type", type}, {"timestamp_ms", now}, {"payload", payload}}.dump(
+        -1, ' ', false, json::error_handler_t::replace);
+    std::lock_guard<std::mutex> lk(ws_mu);
+    for (const auto& [conn, state] : ws_connections) {
+        if (!state || !state->trusted_local) continue;
+        try {
+            conn->send_text(text);
+        } catch (...) {
+        }
+    }
+}
+
+void WebServer::Impl::register_channels() {
+    const auto respond = [this](const crow::request& req, int status, const json& body) {
+        crow::response response(status);
+        response.add_header("Content-Type", "application/json");
+        response.add_header("Cache-Control", "no-store");
+        response.body = body.dump(-1, ' ', false, json::error_handler_t::replace);
+        return with_cors(req, std::move(response));
+    };
+    // 本机直连 + 鉴权 + 宿主可用;不满足时返回要回给客户端的响应。
+    const auto gate = [this, respond](const crow::request& req) -> std::optional<crow::response> {
+        if (!is_trusted_local_client_address(req.remote_ip_address)) {
+            log_unauthorized(req.url, req.remote_ip_address, "channels non-local");
+            return respond(req, 403, channel_error_body("LOCAL_ONLY", "消息通道只能在本机设置"));
+        }
+        if (auto rejected = require_auth(req)) return rejected;
+        if (!deps.channel_host) return respond(req, 503, channel_error_body("UNAVAILABLE", "消息通道不可用"));
+        return std::nullopt;
+    };
+    // 宿主操作失败时抛的异常转成响应:未知平台 404,其余 400(消息可直接展示,不含凭据)。
+    const auto run = [respond](const crow::request& req, const std::function<json()>& action) {
+        try {
+            return respond(req, 200, action());
+        } catch (const std::invalid_argument& e) {
+            return respond(req, 404, channel_error_body("UNKNOWN_PLATFORM", e.what()));
+        } catch (const std::exception& e) {
+            return respond(req, 400, channel_error_body("CHANNEL_ERROR", e.what()));
+        }
+    };
+    const auto parse_body = [](const crow::request& req) { return json::parse(req.body, nullptr, false); };
+
+    CROW_ROUTE(app, "/api/channels").methods(crow::HTTPMethod::Options)
+    ([this](const crow::request& req) { return cors_preflight(req); });
+    CROW_ROUTE(app, "/api/channels").methods(crow::HTTPMethod::GET)
+    ([this, gate, run](const crow::request& req) {
+        if (auto rejected = gate(req)) return std::move(*rejected);
+        return run(req, [this] { return deps.channel_host->snapshot(); });
+    });
+
+    CROW_ROUTE(app, "/api/channels/<string>/enabled").methods(crow::HTTPMethod::POST)
+    ([this, gate, run, respond, parse_body](const crow::request& req, const std::string& platform) {
+        if (auto rejected = gate(req)) return std::move(*rejected);
+        bool enabled = false;
+        std::string error;
+        if (!parse_channel_enabled_request(parse_body(req), enabled, error))
+            return respond(req, 400, channel_error_body("BAD_REQUEST", error));
+        return run(req, [this, &platform, enabled] {
+            deps.channel_host->platform(platform).set_enabled(enabled);
+            return deps.channel_host->snapshot();
+        });
+    });
+
+    CROW_ROUTE(app, "/api/channels/<string>/credentials").methods(crow::HTTPMethod::PUT)
+    ([this, gate, run, respond, parse_body](const crow::request& req, const std::string& platform) {
+        if (auto rejected = gate(req)) return std::move(*rejected);
+        if (!is_channel_platform(platform))
+            return respond(req, 404, channel_error_body("UNKNOWN_PLATFORM", "未知的消息通道平台"));
+        std::string error;
+        const auto credentials = parse_channel_credentials_request(platform, parse_body(req), error);
+        if (!credentials) return respond(req, 400, channel_error_body("BAD_REQUEST", error));
+        return run(req, [this, &platform, &credentials] {
+            deps.channel_host->platform(platform).set_credentials(*credentials);
+            return deps.channel_host->snapshot();
+        });
+    });
+
+    // 扫码绑定(QQ、微信);其他平台返回 404。
+    CROW_ROUTE(app, "/api/channels/<string>/bind").methods(crow::HTTPMethod::POST)
+    ([this, gate, run](const crow::request& req, const std::string& platform) {
+        if (auto rejected = gate(req)) return std::move(*rejected);
+        return run(req, [this, &platform] { return deps.channel_host->start_bind(platform); });
+    });
+    CROW_ROUTE(app, "/api/channels/<string>/bind").methods(crow::HTTPMethod::DELETE)
+    ([this, gate, run](const crow::request& req, const std::string& platform) {
+        if (auto rejected = gate(req)) return std::move(*rejected);
+        return run(req, [this, &platform] {
+            if (!deps.channel_host->has_platform(platform)) throw std::invalid_argument("未知的消息通道平台");
+            deps.channel_host->cancel_bind(platform);
+            return deps.channel_host->bind_state(platform);
+        });
+    });
+
+    // 机主绑定:Telegram 一次性链接,飞书 / 钉钉 / Discord / LINE 一次性 6 位绑定码。
+    CROW_ROUTE(app, "/api/channels/<string>/owner-link").methods(crow::HTTPMethod::POST)
+    ([this, gate, run](const crow::request& req, const std::string& platform) {
+        if (auto rejected = gate(req)) return std::move(*rejected);
+        return run(req, [this, &platform] { return deps.channel_host->owner_link(platform); });
+    });
+
+    CROW_ROUTE(app, "/api/channels/telegram/remove-webhook").methods(crow::HTTPMethod::POST)
+    ([this, gate, run](const crow::request& req) {
+        if (auto rejected = gate(req)) return std::move(*rejected);
+        return run(req, [this] {
+            deps.channel_host->platform("telegram").action("remove_webhook", json::object());
+            return deps.channel_host->snapshot();
+        });
+    });
+
+    CROW_ROUTE(app, "/api/channels/<string>/requests/<string>/<string>").methods(crow::HTTPMethod::POST)
+    ([this, gate, run, respond](const crow::request& req, const std::string& platform, const std::string& id,
+                                 const std::string& decision) {
+        if (auto rejected = gate(req)) return std::move(*rejected);
+        if (decision != "approve" && decision != "reject")
+            return respond(req, 404, channel_error_body("NOT_FOUND", "未知的操作"));
+        return run(req, [this, &platform, &id, &decision] {
+            deps.channel_host->platform(platform).approve(id, decision == "approve");
+            return deps.channel_host->snapshot();
+        });
+    });
+
+    CROW_ROUTE(app, "/api/channels/<string>/access/<string>").methods(crow::HTTPMethod::DELETE)
+    ([this, gate, run, respond](const crow::request& req, const std::string& platform, const std::string& raw) {
+        if (auto rejected = gate(req)) return std::move(*rejected);
+        const auto principal = decode_channel_principal(raw);
+        if (!principal) return respond(req, 400, channel_error_body("BAD_REQUEST", "授权身份格式不对"));
+        return run(req, [this, &platform, &principal] {
+            deps.channel_host->platform(platform).revoke(*principal);
+            return deps.channel_host->snapshot();
+        });
+    });
+}
+
+} // namespace acecode::web
diff --git a/src/apps/web/routes/routes_desktop_office.cpp b/src/apps/web/routes/routes_desktop_office.cpp
new file mode 100644
index 000000000..bc00f7ef3
--- /dev/null
+++ b/src/apps/web/routes/routes_desktop_office.cpp
@@ -0,0 +1,115 @@
+#include "web/server_impl.hpp"
+#include "session/session_recent_activity.hpp"
+
+namespace acecode::web {
+using nlohmann::json;
+namespace {
+json office_item(const json& source) {
+    json item = json::object();
+    for (const auto* key : {"id", "active", "status", "workspace_hash", "workspace_name",
+             "parent_session_id", "agent_path", "archived", "no_workspace", "title", "summary",
+             "last_user_message_at", "last_turn_outcome", "updated_at", "context_window", "token_usage"}) {
+        if (source.contains(key)) item[key] = source[key];
+    }
+    for (const auto* key : {"title", "summary"}) {
+        if (item.contains(key) && item[key].is_string())
+            item[key] = truncate_utf8_prefix(item[key].get_ref<const std::string&>(), 240);
+    }
+    return item;
+}
+} // namespace
+
+void WebServer::Impl::register_desktop_office() {
+    CROW_ROUTE(app, "/api/desktop-office").methods(crow::HTTPMethod::Options)
+    ([this](const crow::request& req) { return with_cors(req, crow::response(204)); });
+
+    CROW_ROUTE(app, "/api/desktop-office").methods(crow::HTTPMethod::GET)
+    ([this](const crow::request& req) {
+        if (auto rejected = require_auth(req)) return std::move(*rejected);
+        const auto respond = [&](int status, const json& body) {
+            crow::response response(status, body.dump());
+            response.add_header("Content-Type", "application/json");
+            response.add_header("Cache-Control", "no-store");
+            return with_cors(req, std::move(response));
+        };
+        const auto recent = global_session_search->recent_user_sessions(5);
+        json offices = json::array();
+        for (const auto& entry : recent.entries) {
+            auto item = entry.active ? session_info_to_json(*entry.active, &entry.meta)
+                                     : session_meta_to_json(entry.meta, entry.workspace_hash);
+            item["last_user_message_at"] = entry.meta.last_user_message_at;
+            item["last_turn_outcome"] = entry.meta.last_turn_outcome;
+            item["workspace_name"] = entry.workspace_name;
+            offices.push_back(office_item(item));
+        }
+        std::string selected = req.url_params.get("session") ? req.url_params.get("session") : "";
+        std::string workspace = req.url_params.get("workspace") ? req.url_params.get("workspace") : "";
+        if (selected.empty() && !offices.empty()) {
+            selected = offices.front().value("id", std::string{});
+            workspace = offices.front().value("workspace_hash", std::string{});
+        }
+        json result{{"offices", offices}, {"selected", nullptr}, {"agents", json::array()},
+                    {"complete", recent.progress.complete}, {"connected", true}};
+        if (selected.empty()) return respond(200, result);
+        const auto active = deps.session_client ? deps.session_client->list_sessions()
+                                                : std::vector<SessionInfo>{};
+        // A child selected in the main window belongs to its root's office.
+        for (const auto& session : active) {
+            if (session.id == selected && !session.parent_session_id.empty()) {
+                selected = session.parent_session_id;
+                workspace = session.workspace_hash;
+                break;
+            }
+        }
+        auto ws = resolve_session_workspace(selected, workspace);
+        // Global discovery also includes workspaces that have no visible sidebar
+        // registration. Their persisted cwd is still authoritative for storage.
+        for (const auto& entry : recent.entries) {
+            if (entry.meta.id != selected) continue;
+            acecode::desktop::WorkspaceMeta source;
+            source.hash = entry.meta.no_workspace ? std::string{} : entry.workspace_hash;
+            source.cwd = entry.meta.cwd;
+            source.name = entry.workspace_name;
+            ws = std::move(source);
+            break;
+        }
+        if (!ws) return respond(404, {{"error", "office session not found"}, {"offices", offices}});
+        auto meta = find_session_meta_for_workspace(*ws, selected);
+        if (!meta || meta->archived) {
+            return respond(404, {{"error", "office session unavailable"}, {"offices", offices}});
+        }
+        if (!meta->parent_session_id.empty()) {
+            selected = meta->parent_session_id;
+            meta = find_session_meta_for_workspace(*ws, selected);
+            if (!meta || meta->archived) return respond(404, {{"error", "office root unavailable"}});
+        }
+        if (meta->last_user_message_at.empty()) {
+            const auto old = read_session_recent_activity(SessionStorage::session_path(
+                SessionStorage::get_project_dir(meta->cwd), selected));
+            meta->last_user_message_at = old.last_user_message_at;
+            if (meta->last_turn_outcome.empty()) meta->last_turn_outcome = old.last_turn_outcome;
+        }
+        auto root = session_meta_to_json(*meta, ws->hash);
+        const auto decorate = [&](const json& source, const std::string& id) {
+            auto item = office_item(source);
+            if (deps.session_registry) {
+                if (const auto entry = deps.session_registry->acquire(id); entry && entry->loop) {
+                    item["activity"] = entry->loop->events().activity_snapshot();
+                }
+            }
+            return item;
+        };
+        for (const auto& session : active) {
+            if (session.id == selected) root = session_info_to_json(session, &*meta);
+        }
+        root = decorate(std::move(root), selected);
+        result["selected"] = root;
+        result["agents"].push_back(root);
+        for (const auto& child : active) {
+            if (child.parent_session_id != selected) continue;
+            result["agents"].push_back(decorate(session_info_to_json(child, nullptr), child.id));
+        }
+        return respond(200, result);
+    });
+}
+} // namespace acecode::web
diff --git a/src/apps/web/routes/routes_ws.cpp b/src/apps/web/routes/routes_ws.cpp
index bd67e3c9a..44f7daaf8 100644
--- a/src/apps/web/routes/routes_ws.cpp
+++ b/src/apps/web/routes/routes_ws.cpp
@@ -30,9 +30,11 @@ void WebServer::Impl::register_websocket() {
                 // Crow WS 的 onopen 不直接传 route 参数;走 hello-binding:
                 // 客户端 onopen 后立刻发 {type:"hello", payload:{session_id, since}},
                 // handle_ws_message 完成 SessionClient::subscribe 绑定。
+                const bool trusted_local = is_trusted_local_client_address(conn.get_remote_ip());
                 std::lock_guard<std::mutex> lk(ws_mu);
                 auto state = std::make_shared<WsConnState>();
                 state->connection = &conn;
+                state->trusted_local = trusted_local;
                 ws_connections.emplace(&conn, std::move(state));
                 LOG_INFO("[ws] connection opened");
             })
diff --git a/src/apps/web/server.cpp b/src/apps/web/server.cpp
index a1599a01e..aa92b4256 100644
--- a/src/apps/web/server.cpp
+++ b/src/apps/web/server.cpp
@@ -137,6 +137,7 @@ void WebServer::Impl::register_routes() {
     register_workspaces();
     register_pinned_sessions();
     register_sessions();
+    register_desktop_office();
     register_task_suggestions();
     register_models();
     register_image_generation();
@@ -161,6 +162,7 @@ void WebServer::Impl::register_routes() {
     register_hooks();
     register_feedback();
     register_pty();
+    register_channels();
     register_environment();
     register_websocket();
     register_static();
@@ -257,6 +259,11 @@ void WebServer::with_app_config_lock(const std::function<void()>& fn) const {
     fn();
 }
 
+void WebServer::broadcast_local_event(const std::string& type, const nlohmann::json& payload) {
+    if (!impl_) return;
+    impl_->broadcast_local_event(type, payload);
+}
+
 void WebServer::broadcast_remote_control_session_selected(
     const std::string& session_id,
     const std::string& workspace_hash,
diff --git a/src/apps/web/server.hpp b/src/apps/web/server.hpp
index f39feed61..a68793845 100644
--- a/src/apps/web/server.hpp
+++ b/src/apps/web/server.hpp
@@ -19,6 +19,8 @@
 #include "upgrade/upgrade.hpp"
 #include "session/opencode_import.hpp"
 
+#include <nlohmann/json.hpp>
+
 #include <atomic>
 #include <cstdint>
 #include <functional>
@@ -52,6 +54,10 @@ namespace acecode::desktop {
 class WorkspaceRegistry;
 } // namespace acecode::desktop
 
+namespace acecode::channels::core {
+class ChannelHost;
+} // namespace acecode::channels::core
+
 namespace acecode::web {
 
 class RemoteWebProxyController;
@@ -147,6 +153,9 @@ struct WebServerDeps {
     std::function<void()>      on_loops_changed;
     std::function<void()>      before_data_dir_copy;
     std::function<void()>      on_data_dir_copy_failure;
+    // 消息通道宿主(QQ / Telegram,add-desktop-im-channels)。null = /api/channels 返回 503,
+    // 会话列表不带 channel_bound。
+    acecode::channels::core::ChannelHost* channel_host = nullptr;
 };
 
 class WebServer {
@@ -187,6 +196,11 @@ class WebServer {
         const std::string& title,
         const std::string& updated_at);
 
+    // 只推给本机直连的 WS 连接(不含远程 Web 代理转发进来的连接):
+    // 消息通道的 channels_state / channels_bind / channels_request 带二维码与联系人信息。
+    // 线程安全。
+    void broadcast_local_event(const std::string& type, const nlohmann::json& payload);
+
 private:
     struct Impl;
     std::unique_ptr<Impl> impl_;
diff --git a/src/apps/web/server_helpers.cpp b/src/apps/web/server_helpers.cpp
index 0067109a3..ece7bad1c 100644
--- a/src/apps/web/server_helpers.cpp
+++ b/src/apps/web/server_helpers.cpp
@@ -7,6 +7,8 @@
 #include "session/session_load_metrics.hpp"
 #include "computer_use/runtime.hpp"
 #include "remote_control_session_event.hpp"
+#include "web/handlers/channels_handler.hpp"
+#include "channels/core/host.hpp"
 #include "session_status_routing.hpp"
 #include "config/saved_models_revision.hpp"
 #include "prompt/context_usage_breakdown.hpp"
@@ -860,6 +862,8 @@ json WebServer::Impl::session_info_to_json(const SessionInfo& s, const SessionMe
     o["model_name"]    = model_name;
     o["model_preset"]  = o["model_name"];
     o["context_window"] = s.context_window;
+    o["last_user_message_at"] = !s.last_user_message_at.empty() ? s.last_user_message_at : (m ? m->last_user_message_at : "");
+    o["last_turn_outcome"] = s.active ? s.last_turn_outcome : (m ? m->last_turn_outcome : "");
     o["deleted"]       = model_deleted;
     o["message_count"] = s.message_count > 0 ? s.message_count : (m ? m->message_count : 0);
     o["turn_count"]    = s.turn_count > 0 ? s.turn_count : (m ? m->turn_count : 0);
@@ -953,6 +957,8 @@ json WebServer::Impl::session_meta_to_json(const SessionMeta& m, const std::stri
     o["summary"]        = m.summary;
     o["created_at"]     = m.created_at;
     o["updated_at"]     = m.updated_at;
+    o["last_user_message_at"] = m.last_user_message_at;
+    o["last_turn_outcome"] = m.last_turn_outcome;
     o["provider"]       = model_deleted ? "" : m.provider;
     o["model"]          = model_deleted ? "" : m.model;
     o["model_name"]     = m.model_preset;
@@ -1276,6 +1282,9 @@ json WebServer::Impl::sessions_for_workspace(const acecode::desktop::WorkspaceMe
             !remote_control_session_id.empty() &&
             item.value("id", std::string{}) == remote_control_session_id;
     }
+    // 消息通道(QQ / Telegram)绑定的会话同样显示电脑图标;/rc 专属行为仍只看
+    // remote_control_bound(design D12)。
+    if (deps.channel_host) annotate_channel_bound(arr, deps.channel_host->bound_sessions());
     if (page_out) *page_out = page;
     return arr;
 }
diff --git a/src/apps/web/server_impl.hpp b/src/apps/web/server_impl.hpp
index 2f9408709..70f96948c 100644
--- a/src/apps/web/server_impl.hpp
+++ b/src/apps/web/server_impl.hpp
@@ -136,6 +136,8 @@ struct SideChatWorker {
 struct WsConnState {
     // Nullable borrowed connection; access only under Impl::ws_mu while registered.
     crow::websocket::connection* connection = nullptr;
+    // 本机直连(不含远程 Web 代理的 127.0.0.2);只有这类连接收消息通道事件。
+    bool trusted_local = false;
     std::string session_id;
     std::unordered_map<std::string, SessionClient::SubscriptionId> subscriptions;
     std::unordered_set<std::string> status_workspaces;
@@ -554,6 +556,7 @@ struct WebServer::Impl {
         const std::string& session_id,
         const std::string& workspace_hash_hint = {}) const;
     void broadcast_session_status(const nlohmann::json& payload);
+    void broadcast_local_event(const std::string& type, const nlohmann::json& payload);
     void broadcast_remote_control_session_selected(const std::string& session_id,
                                                    const std::string& workspace_hash,
                                                    const std::string& cwd,
@@ -620,6 +623,7 @@ struct WebServer::Impl {
     void register_workspaces();
     void register_pinned_sessions();
     void register_sessions();
+    void register_desktop_office();
     void register_task_suggestions();
     void register_models();
     void register_experts();
@@ -638,6 +642,7 @@ struct WebServer::Impl {
     void register_hooks();
     void register_feedback();
     void register_pty();
+    void register_channels();
     void register_environment();
     void register_websocket();
     void register_static();
diff --git a/src/base/network/websocket_client.cpp b/src/base/network/websocket_client.cpp
new file mode 100644
index 000000000..4f947d489
--- /dev/null
+++ b/src/base/network/websocket_client.cpp
@@ -0,0 +1,348 @@
+#include "websocket_client.hpp"
+
+#include "network/proxy_resolver.hpp"
+
+#include <curl/curl.h>
+
+#include <algorithm>
+#include <atomic>
+#include <mutex>
+#include <vector>
+
+#ifdef _WIN32
+#include <winsock2.h>
+#else
+#include <poll.h>
+#endif
+
+namespace acecode::network {
+namespace {
+
+constexpr std::chrono::milliseconds kWaitSlice{100};
+constexpr std::size_t kRecvChunk = 64 * 1024;
+
+std::string curl_error_text(CURLcode code, const char* detail) {
+    std::string text = curl_easy_strerror(code);
+    if (detail && *detail) text += std::string(": ") + detail;
+    return text;
+}
+
+// 等待 socket 可读或可写。超时返回 false;select/poll 自身出错时返回 true,
+// 让后续的 curl 调用报告真实错误,而不是在这里吞掉。
+bool wait_socket(curl_socket_t socket, bool for_write, std::chrono::milliseconds timeout) {
+    const auto ms = static_cast<long>(std::max<std::int64_t>(0, timeout.count()));
+#ifdef _WIN32
+    fd_set set;
+    FD_ZERO(&set);
+    FD_SET(socket, &set);
+    timeval tv{ms / 1000, (ms % 1000) * 1000};
+    const int ready = select(0, for_write ? nullptr : &set, for_write ? &set : nullptr,
+                             nullptr, &tv);
+#else
+    pollfd item{socket, static_cast<short>(for_write ? POLLOUT : POLLIN), 0};
+    const int ready = ::poll(&item, 1, static_cast<int>(ms));
+#endif
+    return ready != 0;
+}
+
+} // namespace
+
+struct WebSocketClient::Impl {
+    mutable std::mutex mu;  // 串行化对 easy handle 的所有调用
+    CURL* curl = nullptr;
+    curl_slist* headers = nullptr;
+    curl_socket_t socket = CURL_SOCKET_BAD;
+    std::size_t max_message_bytes = 4u * 1024u * 1024u;
+    std::atomic<bool> aborted{false};
+    std::atomic<bool> open{false};
+    int close_code = 0;
+    std::string close_reason;
+    // 正在重组的文本/二进制消息与 close 帧载荷。只在 receive 线程上访问。
+    std::string partial;
+    bool partial_binary = false;
+    std::string close_payload;
+
+    void release_locked() {
+        if (curl) curl_easy_cleanup(curl);
+        curl = nullptr;
+        if (headers) curl_slist_free_all(headers);
+        headers = nullptr;
+        socket = CURL_SOCKET_BAD;
+        open = false;
+        partial.clear();
+        close_payload.clear();
+    }
+
+    void record_close(const std::string& payload) {
+        if (payload.size() >= 2) {
+            close_code = (static_cast<unsigned char>(payload[0]) << 8) |
+                         static_cast<unsigned char>(payload[1]);
+            close_reason = payload.substr(2);
+        } else {
+            close_code = 1005;  // close 帧没有带状态码
+            close_reason.clear();
+        }
+    }
+};
+
+WebSocketClient::WebSocketClient() : impl_(std::make_unique<Impl>()) {}
+
+WebSocketClient::~WebSocketClient() {
+    std::lock_guard<std::mutex> lock(impl_->mu);
+    impl_->release_locked();
+}
+
+bool WebSocketClient::connect(const WebSocketConnectOptions& options, std::string* error) {
+    auto& s = *impl_;
+    std::lock_guard<std::mutex> lock(s.mu);
+    s.release_locked();
+    s.aborted = false;
+    s.close_code = 0;
+    s.close_reason.clear();
+    s.max_message_bytes = std::max<std::size_t>(1024, options.max_message_bytes);
+
+    s.curl = curl_easy_init();
+    if (!s.curl) {
+        if (error) *error = "curl_easy_init failed";
+        return false;
+    }
+    char detail[CURL_ERROR_SIZE] = {0};
+    curl_easy_setopt(s.curl, CURLOPT_ERRORBUFFER, detail);
+    curl_easy_setopt(s.curl, CURLOPT_URL, options.url.c_str());
+    curl_easy_setopt(s.curl, CURLOPT_CONNECT_ONLY, 2L);  // 2 = 完成 WebSocket Upgrade 后交还控制
+    curl_easy_setopt(s.curl, CURLOPT_NOSIGNAL, 1L);
+    curl_easy_setopt(s.curl, CURLOPT_CONNECTTIMEOUT_MS,
+                     static_cast<long>(options.connect_timeout.count()));
+    // 只约束握手阶段;握手完成后清零,后续收发由各自的超时控制。
+    curl_easy_setopt(s.curl, CURLOPT_TIMEOUT_MS, static_cast<long>(options.connect_timeout.count()));
+    curl_easy_setopt(s.curl, CURLOPT_SSL_OPTIONS, static_cast<long>(CURLSSLOPT_NO_REVOKE));
+
+    // 代理:与 cpr 调用点同源。直连时必须显式置空,否则 libcurl 会自行读取环境变量。
+    std::string proxy;
+    if (options.use_proxy) proxy = proxy_resolver().effective(websocket_proxy_lookup_url(options.url)).url;
+    curl_easy_setopt(s.curl, CURLOPT_PROXY, proxy.c_str());
+
+    for (const auto& [name, value] : options.headers) {
+        const auto line = name + ": " + value;
+        s.headers = curl_slist_append(s.headers, line.c_str());
+    }
+    if (s.headers) curl_easy_setopt(s.curl, CURLOPT_HTTPHEADER, s.headers);
+
+    const CURLcode rc = curl_easy_perform(s.curl);
+    if (rc != CURLE_OK) {
+        long status = 0;
+        curl_easy_getinfo(s.curl, CURLINFO_RESPONSE_CODE, &status);
+        if (error) {
+            *error = curl_error_text(rc, detail);
+            if (status > 0) *error += " (HTTP " + std::to_string(status) + ")";
+        }
+        s.release_locked();
+        return false;
+    }
+    curl_easy_setopt(s.curl, CURLOPT_ERRORBUFFER, nullptr);
+    curl_easy_setopt(s.curl, CURLOPT_TIMEOUT_MS, 0L);
+    // connect-only 模式下服务端拒绝升级(401/404/200…)时 perform 仍返回 OK,
+    // 必须确认拿到的是 101 Switching Protocols。
+    long status = 0;
+    curl_easy_getinfo(s.curl, CURLINFO_RESPONSE_CODE, &status);
+    if (status != 101) {
+        if (error) *error = "WebSocket upgrade rejected (HTTP " + std::to_string(status) + ")";
+        s.release_locked();
+        return false;
+    }
+    curl_socket_t socket = CURL_SOCKET_BAD;
+    if (curl_easy_getinfo(s.curl, CURLINFO_ACTIVESOCKET, &socket) != CURLE_OK ||
+        socket == CURL_SOCKET_BAD) {
+        if (error) *error = "WebSocket connected without an active socket";
+        s.release_locked();
+        return false;
+    }
+    s.socket = socket;
+    s.open = true;
+    return true;
+}
+
+bool WebSocketClient::send_text(const std::string& payload, std::chrono::milliseconds timeout,
+                                std::string* error) {
+    return send_frame(payload, timeout, error, false);
+}
+
+bool WebSocketClient::send_binary(const std::string& payload, std::chrono::milliseconds timeout,
+                                  std::string* error) {
+    return send_frame(payload, timeout, error, true);
+}
+
+bool WebSocketClient::send_frame(const std::string& payload, std::chrono::milliseconds timeout,
+                                 std::string* error, bool binary) {
+    auto& s = *impl_;
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    std::size_t offset = 0;
+    while (true) {
+        if (s.aborted) {
+            if (error) *error = "WebSocket aborted";
+            return false;
+        }
+        curl_socket_t socket = CURL_SOCKET_BAD;
+        {
+            std::lock_guard<std::mutex> lock(s.mu);
+            if (!s.curl || !s.open) {
+                if (error) *error = "WebSocket is not connected";
+                return false;
+            }
+            std::size_t sent = 0;
+            const CURLcode rc = curl_ws_send(s.curl, payload.data() + offset, payload.size() - offset,
+                                             &sent, 0, binary ? CURLWS_BINARY : CURLWS_TEXT);
+            offset += sent;
+            if (rc == CURLE_OK && offset >= payload.size()) return true;
+            if (rc != CURLE_OK && rc != CURLE_AGAIN) {
+                if (error) *error = curl_error_text(rc, nullptr);
+                s.open = false;
+                return false;
+            }
+            socket = s.socket;
+        }
+        const auto now = std::chrono::steady_clock::now();
+        if (now >= deadline) {
+            // 部分写出的帧无法撤回:连接已不可信,直接标记关闭。
+            std::lock_guard<std::mutex> lock(s.mu);
+            s.open = false;
+            if (error) *error = "WebSocket send timed out";
+            return false;
+        }
+        wait_socket(socket, true,
+                    (std::min)(kWaitSlice,
+                             std::chrono::duration_cast<std::chrono::milliseconds>(deadline - now)));
+    }
+}
+
+WebSocketRecv WebSocketClient::receive(WebSocketMessage& out, std::chrono::milliseconds timeout,
+                                       std::string* error) {
+    auto& s = *impl_;
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    std::vector<char> buffer(kRecvChunk);
+    while (true) {
+        if (s.aborted) {
+            if (error) *error = "WebSocket aborted";
+            return WebSocketRecv::Error;
+        }
+        curl_socket_t socket = CURL_SOCKET_BAD;
+        {
+            std::lock_guard<std::mutex> lock(s.mu);
+            if (!s.curl || !s.open) {
+                if (s.close_code != 0) return WebSocketRecv::Closed;
+                if (error) *error = "WebSocket is not connected";
+                return WebSocketRecv::Error;
+            }
+            std::size_t received = 0;
+            const curl_ws_frame* meta = nullptr;
+            const CURLcode rc = curl_ws_recv(s.curl, buffer.data(), buffer.size(), &received, &meta);
+            if (rc == CURLE_OK && meta) {
+                const int flags = meta->flags;
+                if (flags & CURLWS_CLOSE) {
+                    s.close_payload.append(buffer.data(), received);
+                    if (meta->bytesleft == 0) {
+                        s.record_close(s.close_payload);
+                        s.close_payload.clear();
+                        // 回一个 close 帧完成关闭握手;失败也无所谓,连接马上释放。
+                        std::size_t sent = 0;
+                        curl_ws_send(s.curl, "", 0, &sent, 0, CURLWS_CLOSE);
+                        s.release_locked();
+                        return WebSocketRecv::Closed;
+                    }
+                    continue;
+                }
+                if (flags & (CURLWS_PING | CURLWS_PONG)) continue;  // libcurl 已自动回 pong
+                if (flags & (CURLWS_TEXT | CURLWS_BINARY)) {
+                    if (s.partial.size() + received + static_cast<std::size_t>(meta->bytesleft) >
+                        s.max_message_bytes) {
+                        if (error) *error = "WebSocket message exceeds limit";
+                        s.close_code = 1009;
+                        s.close_reason = "message too big";
+                        std::size_t sent = 0;
+                        const char code[2] = {static_cast<char>(0x03), static_cast<char>(0xF1)};
+                        curl_ws_send(s.curl, code, sizeof(code), &sent, 0, CURLWS_CLOSE);
+                        s.release_locked();
+                        return WebSocketRecv::Error;
+                    }
+                    s.partial.append(buffer.data(), received);
+                    s.partial_binary = (flags & CURLWS_BINARY) != 0;
+                    if (meta->bytesleft == 0 && !(flags & CURLWS_CONT)) {
+                        out.binary = s.partial_binary;
+                        out.data = std::move(s.partial);
+                        s.partial.clear();
+                        return WebSocketRecv::Message;
+                    }
+                }
+                continue;
+            }
+            if (rc == CURLE_GOT_NOTHING || rc == CURLE_RECV_ERROR) {
+                // 对端没发 close 帧就断开了。
+                if (s.close_code == 0) {
+                    s.close_code = 1006;
+                    s.close_reason = curl_easy_strerror(rc);
+                }
+                s.release_locked();
+                return WebSocketRecv::Closed;
+            }
+            if (rc != CURLE_AGAIN) {
+                if (error) *error = curl_error_text(rc, nullptr);
+                s.release_locked();
+                return WebSocketRecv::Error;
+            }
+            socket = s.socket;
+        }
+        const auto now = std::chrono::steady_clock::now();
+        if (now >= deadline) return WebSocketRecv::Timeout;
+        wait_socket(socket, false,
+                    (std::min)(kWaitSlice,
+                             std::chrono::duration_cast<std::chrono::milliseconds>(deadline - now)));
+    }
+}
+
+void WebSocketClient::close(std::uint16_t code, const std::string& reason) {
+    auto& s = *impl_;
+    std::lock_guard<std::mutex> lock(s.mu);
+    if (s.curl && s.open) {
+        std::string payload;
+        payload.push_back(static_cast<char>((code >> 8) & 0xFF));
+        payload.push_back(static_cast<char>(code & 0xFF));
+        payload += reason.substr(0, 120);
+        std::size_t sent = 0;
+        curl_ws_send(s.curl, payload.data(), payload.size(), &sent, 0, CURLWS_CLOSE);
+    }
+    s.release_locked();
+}
+
+void WebSocketClient::abort() { impl_->aborted = true; }
+
+bool WebSocketClient::connected() const {
+    std::lock_guard<std::mutex> lock(impl_->mu);
+    return impl_->curl && impl_->open;
+}
+
+int WebSocketClient::close_code() const {
+    std::lock_guard<std::mutex> lock(impl_->mu);
+    return impl_->close_code;
+}
+
+std::string WebSocketClient::close_reason() const {
+    std::lock_guard<std::mutex> lock(impl_->mu);
+    return impl_->close_reason;
+}
+
+std::string websocket_proxy_lookup_url(const std::string& ws_url) {
+    auto lower_prefix = [&](const char* prefix) {
+        const std::string p(prefix);
+        if (ws_url.size() < p.size()) return false;
+        for (std::size_t i = 0; i < p.size(); ++i) {
+            const char c = ws_url[i];
+            if (static_cast<char>(c >= 'A' && c <= 'Z' ? c - 'A' + 'a' : c) != p[i]) return false;
+        }
+        return true;
+    };
+    if (lower_prefix("wss://")) return "https://" + ws_url.substr(6);
+    if (lower_prefix("ws://")) return "http://" + ws_url.substr(5);
+    return ws_url;
+}
+
+} // namespace acecode::network
diff --git a/src/base/network/websocket_client.hpp b/src/base/network/websocket_client.hpp
new file mode 100644
index 000000000..2926bb0fd
--- /dev/null
+++ b/src/base/network/websocket_client.hpp
@@ -0,0 +1,78 @@
+#pragma once
+
+// 基于 libcurl WebSocket API(connect-only + curl_ws_send / curl_ws_recv)的
+// 通用客户端,供 IM 通道(QQ 机器人网关)等长连接使用。
+//
+// 约定:
+//   - 代理沿用 ProxyResolver 的判定,直连时显式禁用 libcurl 自己的环境变量代理,
+//     与 cpr 调用点行为一致;TLS 保留 NoRevoke,证书校验交给 TLS 后端。
+//   - receive() 只返回重组好的完整消息;ping 由 libcurl 自动回 pong,控制帧不上抛。
+//   - 单条消息超过 max_message_bytes 视为协议错误,连接随即关闭。
+//   - 一个线程 receive、另一个线程 send_text 是允许的(内部串行化 curl 调用);
+//     abort() 可从任意线程调用,阻塞中的 receive/send 在 100ms 内返回。
+
+#include <chrono>
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace acecode::network {
+
+struct WebSocketMessage {
+    bool binary = false;
+    std::string data;
+};
+
+enum class WebSocketRecv {
+    Message,  // out 中是一条完整消息
+    Timeout,  // 超时前没有收到完整消息,连接仍然可用
+    Closed,   // 对端关闭(close 帧或断开);close_code()/close_reason() 可读
+    Error,    // 传输或协议错误;error 中是原因
+};
+
+struct WebSocketConnectOptions {
+    std::string url;  // ws:// 或 wss://
+    std::vector<std::pair<std::string, std::string>> headers;
+    std::chrono::milliseconds connect_timeout{std::chrono::seconds(20)};
+    std::size_t max_message_bytes = 4u * 1024u * 1024u;
+    bool use_proxy = true;
+};
+
+class WebSocketClient {
+public:
+    WebSocketClient();
+    ~WebSocketClient();
+    WebSocketClient(const WebSocketClient&) = delete;
+    WebSocketClient& operator=(const WebSocketClient&) = delete;
+
+    // 建立连接并完成 HTTP Upgrade。失败时 error 含 curl 错误与 HTTP 状态码。
+    bool connect(const WebSocketConnectOptions& options, std::string* error);
+    bool send_text(const std::string& payload, std::chrono::milliseconds timeout,
+                   std::string* error);
+    // 发送一条二进制消息(飞书长连接的 protobuf 帧)。语义同 send_text。
+    bool send_binary(const std::string& payload, std::chrono::milliseconds timeout,
+                     std::string* error);
+    WebSocketRecv receive(WebSocketMessage& out, std::chrono::milliseconds timeout,
+                          std::string* error);
+    // 尽力发送 close 帧后释放连接;重复调用无副作用。
+    void close(std::uint16_t code = 1000, const std::string& reason = {});
+    void abort();
+    bool connected() const;
+    // 对端 close 帧里的状态码;未收到 close 帧而断开时为 1006。
+    int close_code() const;
+    std::string close_reason() const;
+
+private:
+    bool send_frame(const std::string& payload, std::chrono::milliseconds timeout, std::string* error,
+                    bool binary);
+
+    struct Impl;
+    std::unique_ptr<Impl> impl_;
+};
+
+// ws:// → http://、wss:// → https://,用于代理选择与 NO_PROXY 匹配。
+std::string websocket_proxy_lookup_url(const std::string& ws_url);
+
+} // namespace acecode::network
diff --git a/src/base/platform/crypto/aes_ecb.cpp b/src/base/platform/crypto/aes_ecb.cpp
new file mode 100644
index 000000000..1ba258a94
--- /dev/null
+++ b/src/base/platform/crypto/aes_ecb.cpp
@@ -0,0 +1,110 @@
+#include "aes_ecb.hpp"
+
+#include <vector>
+
+#ifdef _WIN32
+#include <windows.h>
+#include <bcrypt.h>
+#else
+#include <openssl/evp.h>
+#endif
+
+namespace acecode::platform {
+namespace {
+
+bool fail(std::string* error, const char* message) {
+    if (error) *error = message;
+    return false;
+}
+
+#ifdef _WIN32
+// BCrypt 的 ECB 不做填充(不传 BCRYPT_BLOCK_PADDING),填充在外面按 PKCS#7 自己处理,
+// 两个平台的行为因此完全一致。
+bool run_native(const std::string& key, const std::string& input, bool encrypt, std::string& output,
+                std::string* error) {
+    BCRYPT_ALG_HANDLE alg = nullptr;
+    BCRYPT_KEY_HANDLE handle = nullptr;
+    const auto cleanup = [&alg, &handle] {
+        if (handle) BCryptDestroyKey(handle);
+        if (alg) BCryptCloseAlgorithmProvider(alg, 0);
+    };
+    if (BCryptOpenAlgorithmProvider(&alg, BCRYPT_AES_ALGORITHM, nullptr, 0) < 0) {
+        cleanup();
+        return fail(error, "AES provider unavailable");
+    }
+    if (BCryptSetProperty(alg, BCRYPT_CHAINING_MODE,
+                          reinterpret_cast<PUCHAR>(const_cast<wchar_t*>(BCRYPT_CHAIN_MODE_ECB)),
+                          sizeof(BCRYPT_CHAIN_MODE_ECB), 0) < 0) {
+        cleanup();
+        return fail(error, "AES-ECB mode unavailable");
+    }
+    if (BCryptGenerateSymmetricKey(alg, &handle, nullptr, 0,
+                                   reinterpret_cast<PUCHAR>(const_cast<char*>(key.data())),
+                                   static_cast<ULONG>(key.size()), 0) < 0) {
+        cleanup();
+        return fail(error, "Invalid AES key");
+    }
+    std::vector<unsigned char> out(input.empty() ? 1 : input.size());
+    ULONG written = 0;
+    auto* in = reinterpret_cast<PUCHAR>(const_cast<char*>(input.data()));
+    const auto size = static_cast<ULONG>(input.size());
+    const NTSTATUS status = encrypt
+        ? BCryptEncrypt(handle, in, size, nullptr, nullptr, 0, out.data(), size, &written, 0)
+        : BCryptDecrypt(handle, in, size, nullptr, nullptr, 0, out.data(), size, &written, 0);
+    cleanup();
+    if (status < 0) return fail(error, encrypt ? "AES-ECB encryption failed" : "AES-ECB decryption failed");
+    output.assign(reinterpret_cast<const char*>(out.data()), written);
+    return true;
+}
+#else
+bool run_native(const std::string& key, const std::string& input, bool encrypt, std::string& output,
+                std::string* error) {
+    EVP_CIPHER_CTX* ctx = EVP_CIPHER_CTX_new();
+    if (!ctx) return fail(error, "AES provider unavailable");
+    std::vector<unsigned char> out(input.size() + 16);
+    int len = 0;
+    int final_len = 0;
+    const auto* k = reinterpret_cast<const unsigned char*>(key.data());
+    const auto* in = reinterpret_cast<const unsigned char*>(input.data());
+    const bool ok = EVP_CipherInit_ex(ctx, EVP_aes_128_ecb(), nullptr, k, nullptr, encrypt ? 1 : 0) == 1 &&
+                    EVP_CIPHER_CTX_set_padding(ctx, 0) == 1 &&
+                    EVP_CipherUpdate(ctx, out.data(), &len, in, static_cast<int>(input.size())) == 1 &&
+                    EVP_CipherFinal_ex(ctx, out.data() + len, &final_len) == 1;
+    EVP_CIPHER_CTX_free(ctx);
+    if (!ok) return fail(error, encrypt ? "AES-ECB encryption failed" : "AES-ECB decryption failed");
+    output.assign(reinterpret_cast<const char*>(out.data()), static_cast<std::size_t>(len + final_len));
+    return true;
+}
+#endif
+
+} // namespace
+
+std::size_t aes_128_ecb_padded_size(std::size_t plaintext_size) { return (plaintext_size / 16 + 1) * 16; }
+
+bool aes_128_ecb_encrypt(const std::string& key, const std::string& plaintext, std::string& ciphertext,
+                         std::string* error) {
+    ciphertext.clear();
+    if (key.size() != 16) return fail(error, "AES-128 key must be 16 bytes");
+    std::string padded = plaintext;
+    const auto pad = static_cast<char>(16 - plaintext.size() % 16);
+    padded.append(static_cast<std::size_t>(pad), pad);
+    return run_native(key, padded, true, ciphertext, error);
+}
+
+bool aes_128_ecb_decrypt(const std::string& key, const std::string& ciphertext, std::string& plaintext,
+                         std::string* error) {
+    plaintext.clear();
+    if (key.size() != 16) return fail(error, "AES-128 key must be 16 bytes");
+    if (ciphertext.empty() || ciphertext.size() % 16 != 0) return fail(error, "AES-ECB ciphertext size is invalid");
+    std::string padded;
+    if (!run_native(key, ciphertext, false, padded, error)) return false;
+    const auto pad = static_cast<unsigned char>(padded.back());
+    if (pad == 0 || pad > 16 || pad > padded.size()) return fail(error, "AES-ECB padding is invalid");
+    for (std::size_t i = padded.size() - pad; i < padded.size(); ++i)
+        if (static_cast<unsigned char>(padded[i]) != pad) return fail(error, "AES-ECB padding is invalid");
+    padded.resize(padded.size() - pad);
+    plaintext = std::move(padded);
+    return true;
+}
+
+} // namespace acecode::platform
diff --git a/src/base/platform/crypto/aes_ecb.hpp b/src/base/platform/crypto/aes_ecb.hpp
new file mode 100644
index 000000000..df664a9e0
--- /dev/null
+++ b/src/base/platform/crypto/aes_ecb.hpp
@@ -0,0 +1,21 @@
+#pragma once
+
+// AES-128-ECB + PKCS#7 填充。Windows 走 BCrypt,其它平台走 OpenSSL libcrypto。
+// 用途:微信 iLink 机器人的媒体文件经 CDN 传输时,文件内容用一次性的 16 字节密钥加解密
+// (协议规定的算法;ECB 不适合一般场景,不要拿来做别的)。
+
+#include <string>
+
+namespace acecode::platform {
+
+// key 必须 16 字节。成功返回 true;error 只描述原因,绝不包含密钥或内容。
+bool aes_128_ecb_encrypt(const std::string& key, const std::string& plaintext, std::string& ciphertext,
+                         std::string* error);
+// 密文长度必须是 16 的倍数,填充不合法时返回 false。
+bool aes_128_ecb_decrypt(const std::string& key, const std::string& ciphertext, std::string& plaintext,
+                         std::string* error);
+
+// PKCS#7 填充后的长度(明文长度向上取整到 16 的倍数,正好整除时再加一块)。
+std::size_t aes_128_ecb_padded_size(std::size_t plaintext_size);
+
+} // namespace acecode::platform
diff --git a/src/base/platform/crypto/aes_gcm.cpp b/src/base/platform/crypto/aes_gcm.cpp
new file mode 100644
index 000000000..1001bf4b9
--- /dev/null
+++ b/src/base/platform/crypto/aes_gcm.cpp
@@ -0,0 +1,110 @@
+#include "aes_gcm.hpp"
+
+#include <vector>
+
+#ifdef _WIN32
+#include <windows.h>
+#include <bcrypt.h>
+#else
+#include <openssl/evp.h>
+#endif
+
+namespace acecode::platform {
+namespace {
+
+bool fail(std::string* error, const char* message) {
+    if (error) *error = message;
+    return false;
+}
+
+#ifdef _WIN32
+constexpr NTSTATUS kAuthTagMismatch = static_cast<NTSTATUS>(0xC000A002L);
+
+bool decrypt_native(const std::string& key, const std::string& iv, const std::string& ciphertext,
+                    const std::string& tag, std::string& plaintext, std::string* error) {
+    BCRYPT_ALG_HANDLE alg = nullptr;
+    BCRYPT_KEY_HANDLE handle = nullptr;
+    auto cleanup = [&] {
+        if (handle) BCryptDestroyKey(handle);
+        if (alg) BCryptCloseAlgorithmProvider(alg, 0);
+    };
+    if (BCryptOpenAlgorithmProvider(&alg, BCRYPT_AES_ALGORITHM, nullptr, 0) < 0) {
+        cleanup();
+        return fail(error, "AES provider unavailable");
+    }
+    if (BCryptSetProperty(alg, BCRYPT_CHAINING_MODE,
+                          reinterpret_cast<PUCHAR>(const_cast<wchar_t*>(BCRYPT_CHAIN_MODE_GCM)),
+                          sizeof(BCRYPT_CHAIN_MODE_GCM), 0) < 0) {
+        cleanup();
+        return fail(error, "AES-GCM mode unavailable");
+    }
+    if (BCryptGenerateSymmetricKey(alg, &handle, nullptr, 0,
+                                   reinterpret_cast<PUCHAR>(const_cast<char*>(key.data())),
+                                   static_cast<ULONG>(key.size()), 0) < 0) {
+        cleanup();
+        return fail(error, "Invalid AES key");
+    }
+    BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO info;
+    BCRYPT_INIT_AUTH_MODE_INFO(info);
+    info.pbNonce = reinterpret_cast<PUCHAR>(const_cast<char*>(iv.data()));
+    info.cbNonce = static_cast<ULONG>(iv.size());
+    info.pbTag = reinterpret_cast<PUCHAR>(const_cast<char*>(tag.data()));
+    info.cbTag = static_cast<ULONG>(tag.size());
+    std::vector<unsigned char> out(ciphertext.empty() ? 1 : ciphertext.size());
+    ULONG written = 0;
+    const NTSTATUS status = BCryptDecrypt(
+        handle, reinterpret_cast<PUCHAR>(const_cast<char*>(ciphertext.data())),
+        static_cast<ULONG>(ciphertext.size()), &info, nullptr, 0, out.data(),
+        static_cast<ULONG>(ciphertext.size()), &written, 0);
+    cleanup();
+    if (status == kAuthTagMismatch) return fail(error, "AES-GCM authentication failed");
+    if (status < 0) return fail(error, "AES-GCM decryption failed");
+    plaintext.assign(reinterpret_cast<const char*>(out.data()), written);
+    return true;
+}
+#else
+bool decrypt_native(const std::string& key, const std::string& iv, const std::string& ciphertext,
+                    const std::string& tag, std::string& plaintext, std::string* error) {
+    EVP_CIPHER_CTX* ctx = EVP_CIPHER_CTX_new();
+    if (!ctx) return fail(error, "AES provider unavailable");
+    std::vector<unsigned char> out(ciphertext.size() + 16);
+    int len = 0;
+    int final_len = 0;
+    const auto* k = reinterpret_cast<const unsigned char*>(key.data());
+    const auto* n = reinterpret_cast<const unsigned char*>(iv.data());
+    bool ok = EVP_DecryptInit_ex(ctx, EVP_aes_256_gcm(), nullptr, nullptr, nullptr) == 1 &&
+              EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, static_cast<int>(iv.size()), nullptr) == 1 &&
+              EVP_DecryptInit_ex(ctx, nullptr, nullptr, k, n) == 1 &&
+              EVP_DecryptUpdate(ctx, out.data(), &len,
+                                reinterpret_cast<const unsigned char*>(ciphertext.data()),
+                                static_cast<int>(ciphertext.size())) == 1 &&
+              EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, static_cast<int>(tag.size()),
+                                  const_cast<char*>(tag.data())) == 1;
+    if (!ok) {
+        EVP_CIPHER_CTX_free(ctx);
+        return fail(error, "AES-GCM decryption failed");
+    }
+    const bool authentic = EVP_DecryptFinal_ex(ctx, out.data() + len, &final_len) > 0;
+    EVP_CIPHER_CTX_free(ctx);
+    if (!authentic) return fail(error, "AES-GCM authentication failed");
+    plaintext.assign(reinterpret_cast<const char*>(out.data()), static_cast<std::size_t>(len + final_len));
+    return true;
+}
+#endif
+
+} // namespace
+
+bool aes_256_gcm_decrypt(const std::string& key, const std::string& iv,
+                         const std::string& ciphertext, const std::string& tag,
+                         std::string& plaintext, std::string* error) {
+    plaintext.clear();
+    if (key.size() != 32) return fail(error, "AES-256 key must be 32 bytes");
+    if (iv.size() != 12) return fail(error, "AES-GCM nonce must be 12 bytes");
+    if (tag.size() != 16) return fail(error, "AES-GCM tag must be 16 bytes");
+    std::string result;
+    if (!decrypt_native(key, iv, ciphertext, tag, result, error)) return false;
+    plaintext = std::move(result);
+    return true;
+}
+
+} // namespace acecode::platform
diff --git a/src/base/platform/crypto/aes_gcm.hpp b/src/base/platform/crypto/aes_gcm.hpp
new file mode 100644
index 000000000..70d8d5ed1
--- /dev/null
+++ b/src/base/platform/crypto/aes_gcm.hpp
@@ -0,0 +1,16 @@
+#pragma once
+
+// AES-256-GCM 解密(只解密,不加密)。Windows 走 BCrypt,其它平台走 OpenSSL libcrypto。
+// 用途:QQ 机器人扫码配置时,服务端用客户端临时生成的密钥加密 AppSecret 返回。
+
+#include <string>
+
+namespace acecode::platform {
+
+// key 必须 32 字节,iv 必须 12 字节,tag 必须 16 字节。认证失败(密文或标签被篡改、
+// 密钥不对)返回 false 且不输出明文;error 只描述原因,绝不包含密钥或明文。
+bool aes_256_gcm_decrypt(const std::string& key, const std::string& iv,
+                         const std::string& ciphertext, const std::string& tag,
+                         std::string& plaintext, std::string* error);
+
+} // namespace acecode::platform
diff --git a/src/base/platform/crypto/digest.cpp b/src/base/platform/crypto/digest.cpp
new file mode 100644
index 000000000..e4e22e8f7
--- /dev/null
+++ b/src/base/platform/crypto/digest.cpp
@@ -0,0 +1,87 @@
+#include "digest.hpp"
+
+#include <vector>
+
+#ifdef _WIN32
+#include <windows.h>
+#include <bcrypt.h>
+#else
+#include <openssl/evp.h>
+#include <openssl/hmac.h>
+#endif
+
+namespace acecode::platform {
+namespace {
+
+#ifdef _WIN32
+std::string bcrypt_hash(LPCWSTR algorithm, const std::string* key, const std::string& data) {
+    BCRYPT_ALG_HANDLE alg = nullptr;
+    BCRYPT_HASH_HANDLE hash = nullptr;
+    const auto cleanup = [&alg, &hash] {
+        if (hash) BCryptDestroyHash(hash);
+        if (alg) BCryptCloseAlgorithmProvider(alg, 0);
+    };
+    if (BCryptOpenAlgorithmProvider(&alg, algorithm, nullptr, key ? BCRYPT_ALG_HANDLE_HMAC_FLAG : 0) < 0) {
+        cleanup();
+        return {};
+    }
+    DWORD length = 0;
+    DWORD written = 0;
+    if (BCryptGetProperty(alg, BCRYPT_HASH_LENGTH, reinterpret_cast<PUCHAR>(&length), sizeof(length), &written, 0) <
+        0) {
+        cleanup();
+        return {};
+    }
+    auto* secret = key ? reinterpret_cast<PUCHAR>(const_cast<char*>(key->data())) : nullptr;
+    const auto secret_size = key ? static_cast<ULONG>(key->size()) : 0;
+    if (BCryptCreateHash(alg, &hash, nullptr, 0, secret, secret_size, 0) < 0 ||
+        BCryptHashData(hash, reinterpret_cast<PUCHAR>(const_cast<char*>(data.data())),
+                       static_cast<ULONG>(data.size()), 0) < 0) {
+        cleanup();
+        return {};
+    }
+    std::vector<unsigned char> out(length);
+    const bool ok = BCryptFinishHash(hash, out.data(), length, 0) >= 0;
+    cleanup();
+    return ok ? std::string(reinterpret_cast<const char*>(out.data()), out.size()) : std::string{};
+}
+#endif
+
+} // namespace
+
+std::string md5_digest(const std::string& data) {
+#ifdef _WIN32
+    return bcrypt_hash(BCRYPT_MD5_ALGORITHM, nullptr, data);
+#else
+    unsigned char out[EVP_MAX_MD_SIZE];
+    unsigned int length = 0;
+    if (EVP_Digest(data.data(), data.size(), out, &length, EVP_md5(), nullptr) != 1) return {};
+    return std::string(reinterpret_cast<const char*>(out), length);
+#endif
+}
+
+std::string hmac_sha256(const std::string& key, const std::string& data) {
+#ifdef _WIN32
+    return bcrypt_hash(BCRYPT_SHA256_ALGORITHM, &key, data);
+#else
+    unsigned char out[EVP_MAX_MD_SIZE];
+    unsigned int length = 0;
+    if (!HMAC(EVP_sha256(), key.data(), static_cast<int>(key.size()),
+              reinterpret_cast<const unsigned char*>(data.data()), data.size(), out, &length))
+        return {};
+    return std::string(reinterpret_cast<const char*>(out), length);
+#endif
+}
+
+std::string to_hex(const std::string& bytes) {
+    static const char kDigits[] = "0123456789abcdef";
+    std::string out;
+    out.reserve(bytes.size() * 2);
+    for (const unsigned char byte : bytes) {
+        out.push_back(kDigits[byte >> 4]);
+        out.push_back(kDigits[byte & 0x0f]);
+    }
+    return out;
+}
+
+} // namespace acecode::platform
diff --git a/src/base/platform/crypto/digest.hpp b/src/base/platform/crypto/digest.hpp
new file mode 100644
index 000000000..436ecb8c4
--- /dev/null
+++ b/src/base/platform/crypto/digest.hpp
@@ -0,0 +1,17 @@
+#pragma once
+
+// 摘要与消息认证码。Windows 走 BCrypt,其它平台走 OpenSSL libcrypto。
+// 用途:LINE 回调签名(HMAC-SHA256)、微信 iLink 媒体上传要求的原文件 MD5。
+
+#include <string>
+
+namespace acecode::platform {
+
+// 原始摘要字节(MD5 16 字节、HMAC-SHA256 32 字节);失败返回空串。
+std::string md5_digest(const std::string& data);
+std::string hmac_sha256(const std::string& key, const std::string& data);
+
+// 小写十六进制。
+std::string to_hex(const std::string& bytes);
+
+} // namespace acecode::platform
diff --git a/src/base/platform/crypto/secure_random.cpp b/src/base/platform/crypto/secure_random.cpp
new file mode 100644
index 000000000..5e8e39147
--- /dev/null
+++ b/src/base/platform/crypto/secure_random.cpp
@@ -0,0 +1,36 @@
+#include "secure_random.hpp"
+
+#ifdef _WIN32
+#include <windows.h>
+#include <bcrypt.h>
+#else
+#include <openssl/rand.h>
+#endif
+
+namespace acecode::platform {
+
+std::string secure_random_bytes(std::size_t count) {
+    std::string out(count, '\0');
+    if (count == 0) return out;
+#ifdef _WIN32
+    const NTSTATUS status = BCryptGenRandom(nullptr, reinterpret_cast<PUCHAR>(out.data()),
+                                            static_cast<ULONG>(count), BCRYPT_USE_SYSTEM_PREFERRED_RNG);
+    if (status < 0) return {};
+#else
+    if (RAND_bytes(reinterpret_cast<unsigned char*>(out.data()), static_cast<int>(count)) != 1) return {};
+#endif
+    return out;
+}
+
+std::string secure_random_token(std::size_t count) {
+    static constexpr char kAlphabet[] =
+        "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";  // 64 个字符
+    const auto bytes = secure_random_bytes(count);
+    if (bytes.size() != count) return {};
+    std::string token;
+    token.reserve(count);
+    for (const char b : bytes) token.push_back(kAlphabet[static_cast<unsigned char>(b) & 0x3F]);
+    return token;
+}
+
+} // namespace acecode::platform
diff --git a/src/base/platform/crypto/secure_random.hpp b/src/base/platform/crypto/secure_random.hpp
new file mode 100644
index 000000000..1ecfa9301
--- /dev/null
+++ b/src/base/platform/crypto/secure_random.hpp
@@ -0,0 +1,17 @@
+#pragma once
+
+// 密码学安全的随机字节:Windows BCryptGenRandom,其它平台 OpenSSL RAND_bytes。
+// 用于 QQ 扫码配置的一次性密钥、Telegram 机主绑定码等。
+
+#include <cstddef>
+#include <string>
+
+namespace acecode::platform {
+
+// 失败时返回空串(调用方必须当作错误处理,绝不能退化成弱随机)。
+std::string secure_random_bytes(std::size_t count);
+
+// count 个 URL 安全字符([A-Za-z0-9_-]),基于 secure_random_bytes。失败返回空串。
+std::string secure_random_token(std::size_t count);
+
+} // namespace acecode::platform
diff --git a/src/domain/session/event_dispatcher.cpp b/src/domain/session/event_dispatcher.cpp
index 1da610245..35f2105ea 100644
--- a/src/domain/session/event_dispatcher.cpp
+++ b/src/domain/session/event_dispatcher.cpp
@@ -87,6 +87,7 @@ std::uint64_t EventDispatcher::emit(SessionEventKind kind, nlohmann::json payloa
     {
         std::lock_guard<std::mutex> lk(mu_);
         evt.seq = ++seq_counter_;
+        activity_.apply(evt);
         if (options.buffered) {
             push_to_buffer(evt, options.coalesce_key);
         }
@@ -278,6 +279,11 @@ void EventDispatcher::unsubscribe_impl(SubscriptionId id, bool wait) {
     // Captured resources and queued payloads are released outside mu_.
 }
 
+nlohmann::json EventDispatcher::activity_snapshot() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return activity_.snapshot();
+}
+
 std::size_t EventDispatcher::listener_count() const {
     std::lock_guard<std::mutex> lk(mu_);
     const std::size_t observer_count =
diff --git a/src/domain/session/event_dispatcher.hpp b/src/domain/session/event_dispatcher.hpp
index 763389a01..3959764aa 100644
--- a/src/domain/session/event_dispatcher.hpp
+++ b/src/domain/session/event_dispatcher.hpp
@@ -25,6 +25,7 @@
 //   "实时新帧抢在历史旧帧之前送达、被客户端按 seq 误判为过期而丢弃" 的问题。
 
 #include "session_client.hpp"
+#include "session_activity_state.hpp"
 
 #include <atomic>
 #include <cstddef>
@@ -92,6 +93,9 @@ class EventDispatcher {
     // 测试用: 当前活跃 listener 数。
     std::size_t listener_count() const;
 
+    // Coherent presentation snapshot even when transient events are not replayed.
+    nlohmann::json activity_snapshot() const;
+
 private:
     struct BufferedEvent {
         SessionEvent event;
@@ -124,6 +128,7 @@ class EventDispatcher {
 
     std::atomic<std::uint64_t> seq_counter_{0};
     std::atomic<SubscriptionId> next_sub_id_{1};
+    SessionActivityState activity_; // Guarded by mu_, no callbacks or IO.
     std::size_t                buffer_capacity_;
     std::size_t                buffer_byte_capacity_;
     std::size_t                buffered_bytes_ = 0;
diff --git a/src/domain/session/global_session_catalog_meta.hpp b/src/domain/session/global_session_catalog_meta.hpp
index 9de994268..43db56f20 100644
--- a/src/domain/session/global_session_catalog_meta.hpp
+++ b/src/domain/session/global_session_catalog_meta.hpp
@@ -10,6 +10,8 @@ inline SessionMeta catalog_meta_from_active(const SessionInfo& active) {
     meta.cwd = active.cwd;
     meta.created_at = active.created_at;
     meta.updated_at = active.updated_at;
+    meta.last_user_message_at = active.last_user_message_at;
+    meta.last_turn_outcome = active.last_turn_outcome;
     meta.summary = active.summary;
     meta.provider = active.provider;
     meta.model = active.model;
diff --git a/src/domain/session/global_session_search.cpp b/src/domain/session/global_session_search.cpp
index a4c75c7de..c276578d6 100644
--- a/src/domain/session/global_session_search.cpp
+++ b/src/domain/session/global_session_search.cpp
@@ -1,6 +1,7 @@
 #include "global_session_search.hpp"
 
 #include "session_user_message_search.hpp"
+#include "session_recent_activity.hpp"
 #include "workspace/workspace_registry.hpp"
 #include "utils/utf8_path.hpp"
 
@@ -172,6 +173,12 @@ struct GlobalSessionSearchService::Impl {
         std::mutex run_mu;
     };
 
+    struct RecentCache {
+        SessionUserMessageFileSignature signature;
+        SessionRecentActivity activity;
+    };
+    std::mutex recent_mu;
+    std::unordered_map<std::string, RecentCache> recent_cache;
     GlobalSessionCatalogIndex index;
     std::mutex jobs_mu;
     std::unordered_map<std::string, std::shared_ptr<ContentJob>> jobs;
@@ -250,6 +257,56 @@ void GlobalSessionSearchService::stop() {
     impl_->index.stop();
 }
 
+GlobalSessionSearchPage GlobalSessionSearchService::recent_user_sessions(std::size_t limit) {
+    impl_->index.attach_request("desktop-agent-office");
+    auto snapshot = impl_->index.snapshot();
+    GlobalSessionSearchPage result;
+    result.progress = snapshot.progress;
+    result.errors = std::move(snapshot.catalog.errors);
+    const auto deadline = std::chrono::steady_clock::now() + std::chrono::milliseconds(100);
+    std::lock_guard<std::mutex> lock(impl_->recent_mu);
+    for (auto& entry : snapshot.catalog.entries) {
+        if (entry.meta.archived || !entry.meta.parent_session_id.empty()) continue;
+        if (entry.active && !entry.active->last_user_message_at.empty()) {
+            entry.meta.last_user_message_at = entry.active->last_user_message_at;
+            entry.meta.last_turn_outcome = entry.active->last_turn_outcome;
+        }
+        if (entry.meta.last_user_message_at.empty()) {
+            const auto path = SessionStorage::session_path(entry.project_dir, entry.meta.id);
+            const auto signature = session_user_message_file_signature(path);
+            auto cached = impl_->recent_cache.find(path);
+            if (cached == impl_->recent_cache.end() ||
+                cached->second.signature.mtime != signature.mtime ||
+                cached->second.signature.size != signature.size) {
+                if (std::chrono::steady_clock::now() >= deadline) {
+                    result.progress.complete = false;
+                    continue;
+                }
+                try {
+                    Impl::RecentCache value{signature, read_session_recent_activity(path)};
+                    cached = impl_->recent_cache.insert_or_assign(path, std::move(value)).first;
+                } catch (const std::exception& error) {
+                    result.errors.push_back({entry.project_dir, entry.workspace_hash,
+                                             "recent-user-message", error.what()});
+                    continue;
+                }
+            }
+            entry.meta.last_user_message_at = cached->second.activity.last_user_message_at;
+            if (entry.meta.last_turn_outcome.empty()) {
+                entry.meta.last_turn_outcome = cached->second.activity.last_turn_outcome;
+            }
+        }
+        if (!entry.meta.last_user_message_at.empty()) result.entries.push_back(std::move(entry));
+    }
+    std::sort(result.entries.begin(), result.entries.end(), [](const auto& a, const auto& b) {
+        if (a.meta.last_user_message_at != b.meta.last_user_message_at)
+            return a.meta.last_user_message_at > b.meta.last_user_message_at;
+        return a.meta.id < b.meta.id;
+    });
+    if (result.entries.size() > limit) result.entries.resize(limit);
+    return result;
+}
+
 GlobalSessionSearchPage GlobalSessionSearchService::search_sessions(
     const std::string& request_id,
     const std::string& query,
diff --git a/src/domain/session/global_session_search.hpp b/src/domain/session/global_session_search.hpp
index eba6adcfe..31b5150f9 100644
--- a/src/domain/session/global_session_search.hpp
+++ b/src/domain/session/global_session_search.hpp
@@ -53,6 +53,8 @@ class GlobalSessionSearchService {
         std::size_t limit,
         const std::string& cursor = {});
 
+    GlobalSessionSearchPage recent_user_sessions(std::size_t limit = 5);
+
     GlobalSessionContentSearchPage search_user_messages_batch(
         const std::string& request_id,
         const std::string& query,
diff --git a/src/domain/session/session_activity_state.cpp b/src/domain/session/session_activity_state.cpp
new file mode 100644
index 000000000..ee099ed51
--- /dev/null
+++ b/src/domain/session/session_activity_state.cpp
@@ -0,0 +1,150 @@
+#include "session_activity_state.hpp"
+#include "inter_agent_message.hpp"
+#include "utils/encoding.hpp"
+
+namespace acecode {
+namespace {
+// Enough for a speech bubble; the office shows only the last few words.
+constexpr std::size_t kStreamTailBytes = 160;
+
+std::string text(const nlohmann::json& value, const char* key) {
+    const auto it = value.find(key);
+    return it != value.end() && it->is_string()
+        ? truncate_utf8_prefix(it->get_ref<const std::string&>(), 240) : std::string{};
+}
+bool flag(const nlohmann::json& value, const char* key) {
+    const auto it = value.find(key);
+    return it != value.end() && it->is_boolean() && it->get<bool>();
+}
+std::string utf8_tail(const std::string& value, std::size_t max_bytes) {
+    if (value.size() <= max_bytes) return value;
+    std::size_t start = value.size() - max_bytes;
+    while (start < value.size() &&
+           (static_cast<unsigned char>(value[start]) & 0xC0) == 0x80) {
+        ++start;
+    }
+    return value.substr(start);
+}
+} // namespace
+
+void SessionActivityState::enter_phase(const std::string& phase) {
+    // Each model step starts a fresh bubble; a phase change ends the old text.
+    if (phase != phase_) stream_tail_.clear();
+    phase_ = phase;
+}
+
+void SessionActivityState::append_stream(const std::string& phase, const std::string& piece) {
+    if (phase_ != phase) {
+        enter_phase(phase);
+        if (phase == "responding") label_.clear();
+    }
+    if (tools_.empty()) tool_.clear();
+    stream_tail_ += piece;
+    // Trim in batches so a long reply costs O(piece) per token.
+    if (stream_tail_.size() > kStreamTailBytes * 2) {
+        stream_tail_ = utf8_tail(stream_tail_, kStreamTailBytes);
+    }
+}
+
+void SessionActivityState::apply(const SessionEvent& event) {
+    seq_ = event.seq;
+    const auto& p = event.payload;
+    if (!p.is_object()) return;
+    const auto finish = [&] {
+        const auto outcome = text(p, "outcome");
+        if (outcome.empty()) return;
+        busy_ = false;
+        known_ = true;
+        outcome_ = outcome;
+        phase_.clear(); label_.clear(); tool_.clear(); detail_.clear(); stream_tail_.clear();
+        tools_.clear(); permissions_.clear(); questions_.clear();
+    };
+    switch (event.kind) {
+    case SessionEventKind::BusyChanged:
+        busy_ = flag(p, "busy"); known_ = true;
+        if (busy_) {
+            outcome_.clear(); phase_ = "model_waiting";
+            label_.clear(); tool_.clear(); detail_.clear(); stream_tail_.clear();
+            tools_.clear(); permissions_.clear(); questions_.clear();
+            turn_id_ = text(p, "turn_id");
+        } else finish();
+        break;
+    case SessionEventKind::Done: finish(); break;
+    case SessionEventKind::AgentProgress:
+        enter_phase(text(p, "phase"));
+        label_ = text(p, "label");
+        tool_ = text(p, "tool");
+        break;
+    case SessionEventKind::Token:
+    case SessionEventKind::Reasoning: {
+        const auto it = p.find("text");
+        if (it == p.end() || !it->is_string()) break;
+        append_stream(event.kind == SessionEventKind::Token ? "responding" : "reasoning",
+                      it->get_ref<const std::string&>());
+        break;
+    }
+    case SessionEventKind::ToolStart: {
+        tool_ = text(p, "tool");
+        auto preview = text(p, "display_override");
+        if (preview.empty()) preview = text(p, "command_preview");
+        detail_ = truncate_utf8_prefix(preview, 120);
+        auto id = text(p, "tool_call_id");
+        if (id.empty()) id = tool_;
+        tools_[id] = {tool_, detail_};
+        stream_tail_.clear();
+        break;
+    }
+    case SessionEventKind::ToolEnd: {
+        auto id = text(p, "tool_call_id");
+        if (id.empty()) id = text(p, "tool");
+        tools_.erase(id);
+        if (tools_.empty()) {
+            tool_.clear();
+            detail_.clear();
+        } else {
+            tool_ = tools_.rbegin()->second.first;
+            detail_ = tools_.rbegin()->second.second;
+        }
+        break;
+    }
+    case SessionEventKind::PermissionRequest:
+        permissions_.insert(text(p, "request_id")); break;
+    case SessionEventKind::PermissionClosed:
+        permissions_.erase(text(p, "request_id")); break;
+    case SessionEventKind::QuestionRequest:
+        questions_.insert(text(p, "request_id")); break;
+    case SessionEventKind::QuestionClosed:
+        questions_.erase(text(p, "request_id")); break;
+    case SessionEventKind::Message: {
+        const auto metadata = p.find("metadata");
+        if (metadata == p.end() || !metadata->is_object()) break;
+        if (flag(*metadata, "compact_notice_complete")) {
+            compact_id_ = text(*metadata, "compact_notice_id");
+        }
+        const auto envelope = mesh::inter_agent_envelope_from_metadata(*metadata);
+        if (envelope) {
+            transfers_.push_back({{"seq", event.seq},
+                {"sender", envelope->sender}, {"recipient", envelope->recipient},
+                {"sender_session_id", envelope->sender_session_id},
+                {"type", mesh::inter_agent_message_type_name(envelope->type)}});
+            if (transfers_.size() > 16) transfers_.erase(transfers_.begin());
+        }
+        break;
+    }
+    default: break;
+    }
+}
+
+nlohmann::json SessionActivityState::snapshot() const {
+    auto phase = phase_;
+    if (!permissions_.empty()) phase = "permission_waiting";
+    else if (!questions_.empty()) phase = "question_waiting";
+    else if (!tools_.empty()) phase = "tool_running";
+    const bool streaming = phase == "responding" || phase == "reasoning";
+    return {{"seq", seq_}, {"known", known_}, {"busy", busy_},
+        {"turn_id", turn_id_}, {"outcome", outcome_}, {"phase", phase},
+        {"label", label_}, {"tool", tool_}, {"detail", detail_},
+        {"text", streaming ? utf8_tail(stream_tail_, kStreamTailBytes) : std::string{}},
+        {"compact_id", compact_id_}, {"transfers", transfers_}};
+}
+} // namespace acecode
diff --git a/src/domain/session/session_activity_state.hpp b/src/domain/session/session_activity_state.hpp
new file mode 100644
index 000000000..d0d94cef0
--- /dev/null
+++ b/src/domain/session/session_activity_state.hpp
@@ -0,0 +1,41 @@
+#pragma once
+
+#include "session_client.hpp"
+#include <map>
+#include <string>
+#include <unordered_set>
+#include <utility>
+
+namespace acecode {
+
+// Compact presentation state, updated under the owning dispatcher's mutex.
+// It keeps only short display fragments: the streaming tail of the current
+// model step (bounded) and each running tool's one-line call preview. No
+// transcript, arguments, tool output or service references are retained.
+class SessionActivityState {
+public:
+    void apply(const SessionEvent& event);
+    nlohmann::json snapshot() const;
+private:
+    void enter_phase(const std::string& phase);
+    void append_stream(const std::string& phase, const std::string& piece);
+
+    std::uint64_t seq_ = 0;
+    bool busy_ = false;
+    bool known_ = false;
+    std::string turn_id_;
+    std::string outcome_;
+    std::string phase_;
+    std::string label_;
+    std::string tool_;
+    std::string detail_;
+    std::string stream_tail_;
+    std::string compact_id_;
+    // tool_call_id -> (tool name, call preview)
+    std::map<std::string, std::pair<std::string, std::string>> tools_;
+    std::unordered_set<std::string> permissions_;
+    std::unordered_set<std::string> questions_;
+    nlohmann::json transfers_ = nlohmann::json::array();
+};
+
+} // namespace acecode
diff --git a/src/domain/session/session_client.hpp b/src/domain/session/session_client.hpp
index 85b36688a..70b1fb74e 100644
--- a/src/domain/session/session_client.hpp
+++ b/src/domain/session/session_client.hpp
@@ -281,6 +281,8 @@ struct SessionInfo {
     std::string worktree_path;
     std::string worktree_name;
     std::string worktree_branch;
+    std::string last_user_message_at;
+    std::string last_turn_outcome;
 };
 
 // ----- AskUserQuestion 回应(client→server) -----
diff --git a/src/domain/session/session_manager.cpp b/src/domain/session/session_manager.cpp
index 3fe456f84..43ea68f5b 100644
--- a/src/domain/session/session_manager.cpp
+++ b/src/domain/session/session_manager.cpp
@@ -1,4 +1,5 @@
 #include "session_manager.hpp"
+#include "session_recent_activity.hpp"
 #include "inter_agent_message.hpp"
 #include "session_history_page.hpp"
 #include "session_load_metrics.hpp"
@@ -241,6 +242,8 @@ void SessionManager::start_session(const std::string& cwd,
     message_count_ = 0;
     turn_count_ = 0;
     last_user_summary_.clear();
+    last_user_message_at_.clear();
+    last_turn_outcome_.clear();
     created_at_.clear();
     pending_title_.clear();
     title_source_.clear();
@@ -370,6 +373,7 @@ void SessionManager::on_message(const ChatMessage& msg) {
         }
     }
 
+    record_recent_activity_locked(msg);
     // Track last user message for summary
     if (is_visible_user_turn_message(msg)) {
         const std::string text = user_summary_source_text(msg);
@@ -616,6 +620,7 @@ std::vector<ChatMessage> SessionManager::resume_session(const std::string& sessi
     // Restore persisted display/model metadata when present. Resuming is not
     // conversation activity, so keep the persisted activity timestamp while
     // still rewriting repaired counters and compatibility fields below.
+    restore_recent_activity_locked(persisted_meta);
     std::optional<std::string> persisted_updated_at;
     if (fs::exists(meta_path_str_)) {
         auto meta = SessionStorage::read_meta(meta_path_str_);
@@ -911,6 +916,7 @@ std::string SessionManager::fork_active_session(const std::vector<ChatMessage>&
             log_user_message_index_error("rebuild after fork", session_id_, index_error);
         }
     }
+    restore_recent_activity_locked({});
     update_meta(SessionStorage::now_iso8601());
     if (goal_store_ && !previous_session_id.empty()) {
         std::string goal_error;
@@ -920,7 +926,6 @@ std::string SessionManager::fork_active_session(const std::vector<ChatMessage>&
     }
     return session_id_;
 }
-
 std::string SessionManager::fork_session_to_new_id(
     const std::vector<ChatMessage>& retained_prefix,
     const std::string& title,
@@ -1031,6 +1036,9 @@ std::string SessionManager::fork_session_to_new_id(
     meta.message_count   = count;
     meta.turn_count      = turn_count;
     meta.summary         = last_user_summary;
+    const auto recent = read_session_recent_activity(new_jsonl);
+    meta.last_user_message_at = recent.last_user_message_at;
+    meta.last_turn_outcome = recent.last_turn_outcome;
     meta.provider        = provider_name_;
     meta.model           = model_name_;
     meta.model_preset    = model_preset_;
@@ -1205,6 +1213,8 @@ bool SessionManager::update_meta(
         : (persisted.id.empty() ? created_at_ : persisted.updated_at);
     meta.message_count = message_count_;
     meta.turn_count = turn_count_;
+    meta.last_user_message_at = last_user_message_at_;
+    meta.last_turn_outcome = last_turn_outcome_;
     meta.summary = last_user_summary_;
     meta.provider = provider_name_;
     meta.model = model_name_;
@@ -1519,11 +1529,6 @@ std::string SessionManager::current_title_source() const {
     return title_source_;
 }
 
-std::string SessionManager::current_summary() const {
-    std::lock_guard<std::mutex> lk(mu_);
-    return last_user_summary_;
-}
-
 void SessionManager::set_input_draft(std::string draft, nlohmann::json composer_content) {
     std::lock_guard<std::mutex> lk(mu_);
     input_draft_ = std::move(draft);
@@ -1541,6 +1546,8 @@ void SessionManager::set_input_draft(std::string draft, nlohmann::json composer_
         meta.updated_at = meta.created_at;
         meta.message_count = message_count_;
         meta.turn_count = turn_count_;
+        meta.last_user_message_at = last_user_message_at_;
+        meta.last_turn_outcome = last_turn_outcome_;
         meta.summary = last_user_summary_;
         meta.provider = provider_name_;
         meta.model = model_name_;
diff --git a/src/domain/session/session_manager.hpp b/src/domain/session/session_manager.hpp
index 695bc24a5..15df2b15c 100644
--- a/src/domain/session/session_manager.hpp
+++ b/src/domain/session/session_manager.hpp
@@ -33,6 +33,8 @@ struct SessionDisplaySnapshot {
     WorktreeSessionInfo worktree;
     std::string swarm_mode;   // "" = off
     std::string agent_path;   // mesh child path; empty for roots
+    std::string last_user_message_at;
+    std::string last_turn_outcome;
 };
 
 class SessionManager {
@@ -275,6 +277,7 @@ class SessionManager {
     TokenUsage current_last_token_usage() const;
     TokenUsage current_session_token_usage() const;
     int current_turn_count() const;
+    void record_turn_outcome(const std::string& outcome);
 
     // Append one model-invisible diagnostic record to the active session's
     // trajectory sidecar. timestamp_ms <= 0 uses the current system clock.
@@ -290,6 +293,8 @@ class SessionManager {
     std::string current_trajectory_path() const;
 
 private:
+    void record_recent_activity_locked(const ChatMessage& msg);
+    void restore_recent_activity_locked(const SessionMeta& persisted_meta);
     void publish_display_snapshot_locked(); // mu_ held; display_mu_ is a leaf lock.
     bool ensure_created();  // Lazy creation of session files on first message
     // 追加一条不含可搜索用户文本的记录(检查点 / 净差异等),并同步推进用户消息
@@ -338,6 +343,8 @@ class SessionManager {
     int message_count_ = 0;
     int turn_count_ = 0;
     std::string last_user_summary_;
+    std::string last_user_message_at_;
+    std::string last_turn_outcome_;
     std::string created_at_;
     std::string pending_title_;
     std::string title_source_;
diff --git a/src/domain/session/session_manager_history.cpp b/src/domain/session/session_manager_history.cpp
index a7529f385..fcc00f0e4 100644
--- a/src/domain/session/session_manager_history.cpp
+++ b/src/domain/session/session_manager_history.cpp
@@ -1,4 +1,6 @@
 #include "session_manager.hpp"
+#include "session_recent_activity.hpp"
+#include "turn_timing.hpp"
 #include "session_history_page.hpp"
 #include "utils/logger.hpp"
 #include <filesystem>
@@ -6,15 +8,48 @@
 namespace acecode {
 namespace fs = std::filesystem;
 
+void SessionManager::record_turn_outcome(const std::string& outcome) {
+    if (!is_valid_turn_timing_status(outcome)) return;
+    std::lock_guard<std::mutex> lock(mu_);
+    if (last_turn_outcome_ == outcome) return;
+    last_turn_outcome_ = outcome;
+    update_meta();
+}
+
+void SessionManager::record_recent_activity_locked(const ChatMessage& msg) {
+    if (is_recent_user_message(msg)) {
+        last_user_message_at_ = msg.timestamp.empty() ? SessionStorage::now_iso8601() : msg.timestamp;
+        last_turn_outcome_.clear();
+    } else if (is_turn_timing_message(msg)) {
+        last_turn_outcome_ = decode_turn_timing(msg.metadata.at("turn_timing"))->status;
+    }
+}
+
+void SessionManager::restore_recent_activity_locked(const SessionMeta& persisted_meta) {
+    last_user_message_at_ = persisted_meta.last_user_message_at;
+    last_turn_outcome_ = persisted_meta.last_turn_outcome;
+    if (last_user_message_at_.empty()) {
+        const auto recent = read_session_recent_activity(jsonl_path_);
+        last_user_message_at_ = recent.last_user_message_at;
+        if (last_turn_outcome_.empty()) last_turn_outcome_ = recent.last_turn_outcome;
+    }
+}
+
 void SessionManager::publish_display_snapshot_locked() {
     SessionDisplaySnapshot snapshot{
         pending_title_, title_source_, last_user_summary_, turn_count_,
         last_token_usage_, session_token_usage_, worktree_, swarm_mode_, agent_path_,
+        last_user_message_at_, last_turn_outcome_,
     };
     std::lock_guard<std::mutex> lock(display_mu_);
     display_snapshot_ = std::move(snapshot);
 }
 
+std::string SessionManager::current_summary() const {
+    std::lock_guard<std::mutex> lk(mu_);
+    return last_user_summary_;
+}
+
 SessionDisplaySnapshot SessionManager::display_snapshot() const {
     std::lock_guard<std::mutex> lock(display_mu_);
     return display_snapshot_;
diff --git a/src/domain/session/session_recent_activity.cpp b/src/domain/session/session_recent_activity.cpp
new file mode 100644
index 000000000..6a5796de3
--- /dev/null
+++ b/src/domain/session/session_recent_activity.cpp
@@ -0,0 +1,48 @@
+#include "session_recent_activity.hpp"
+#include "inter_agent_message.hpp"
+#include "jsonl_scanner.hpp"
+#include "session_serializer.hpp"
+#include "session_user_message_search.hpp"
+#include "turn_timing.hpp"
+
+namespace acecode {
+namespace {
+bool consume(const ChatMessage& message, SessionRecentActivity& result) {
+    if (result.last_turn_outcome.empty() && is_turn_timing_message(message)) {
+        result.last_turn_outcome = decode_turn_timing(message.metadata.at("turn_timing"))->status;
+    }
+    if (!is_recent_user_message(message)) return false;
+    result.last_user_message_at = message.timestamp;
+    return true;
+}
+} // namespace
+
+bool is_recent_user_message(const ChatMessage& message) {
+    const auto tool = message.metadata.is_object() ? message.metadata.find("source_tool") : message.metadata.end();
+    const bool tool_injected = tool != message.metadata.end() && tool->is_string() && !tool->get_ref<const std::string&>().empty();
+    return !tool_injected && is_searchable_visible_user_message(message) && !mesh::is_inter_agent_message(message);
+}
+
+SessionRecentActivity recent_activity_from_messages(const std::vector<ChatMessage>& messages) {
+    SessionRecentActivity result;
+    for (auto it = messages.rbegin(); it != messages.rend(); ++it) {
+        if (consume(*it, result)) break;
+    }
+    return result;
+}
+
+SessionRecentActivity read_session_recent_activity(const std::string& jsonl_path) {
+    SessionRecentActivity result;
+    SessionFileReader reader(jsonl_path);
+    if (!reader.valid()) return result;
+    JsonlScanner scanner(reader, true);
+    while (const auto record = scanner.next()) {
+        try {
+            if (consume(deserialize_message(record->text), result)) break;
+        } catch (const nlohmann::json::exception&) {
+            // A damaged line is not a message or a completion signal.
+        }
+    }
+    return result;
+}
+} // namespace acecode
diff --git a/src/domain/session/session_recent_activity.hpp b/src/domain/session/session_recent_activity.hpp
new file mode 100644
index 000000000..c042738c1
--- /dev/null
+++ b/src/domain/session/session_recent_activity.hpp
@@ -0,0 +1,22 @@
+#pragma once
+
+#include "llm/llm_provider.hpp"
+#include <string>
+#include <vector>
+
+namespace acecode {
+
+struct SessionRecentActivity {
+    std::string last_user_message_at;
+    std::string last_turn_outcome;
+};
+
+// Visible human input only; internal mesh messages and compact summaries do not
+// make a conversation recent. Reuses the existing persisted message flags.
+bool is_recent_user_message(const ChatMessage& message);
+SessionRecentActivity recent_activity_from_messages(const std::vector<ChatMessage>& messages);
+// Reads backwards using the existing bounded JSONL scanner. Does not rewrite
+// old metadata or load an entire long transcript into memory.
+SessionRecentActivity read_session_recent_activity(const std::string& jsonl_path);
+
+} // namespace acecode
diff --git a/src/domain/session/session_storage.cpp b/src/domain/session/session_storage.cpp
index 201e56583..62ba97eeb 100644
--- a/src/domain/session/session_storage.cpp
+++ b/src/domain/session/session_storage.cpp
@@ -296,6 +296,8 @@ bool SessionStorage::write_meta(const std::string& meta_path, const SessionMeta&
     j["cwd"] = meta.cwd;
     j["created_at"] = meta.created_at;
     j["updated_at"] = meta.updated_at;
+    if (!meta.last_user_message_at.empty()) j["last_user_message_at"] = meta.last_user_message_at;
+    if (!meta.last_turn_outcome.empty()) j["last_turn_outcome"] = meta.last_turn_outcome;
     j["message_count"] = meta.message_count;
     j["summary"] = meta.summary;
     j["provider"] = meta.provider;
@@ -424,6 +426,8 @@ SessionMeta SessionStorage::read_meta(const std::string& meta_path) {
         meta.pre_plan_permission_mode = normalize_pre_plan_permission_mode_name(
             j.value("pre_plan_permission_mode", std::string{}));
         meta.turn_count      = (std::max)(0, j.value("turn_count", 0));
+        meta.last_user_message_at = j.value("last_user_message_at", std::string{});
+        meta.last_turn_outcome = j.value("last_turn_outcome", std::string{});
         if (j.contains("last_token_usage")) {
             meta.last_token_usage = token_usage_from_json(j["last_token_usage"]);
         }
diff --git a/src/domain/session/session_storage.hpp b/src/domain/session/session_storage.hpp
index 86e50c474..dfb9aa5d1 100644
--- a/src/domain/session/session_storage.hpp
+++ b/src/domain/session/session_storage.hpp
@@ -120,6 +120,8 @@ struct SessionMeta {
     // parent_session_id 恒为树根会话 id(界面归属、冒泡与级联删除都按它走),
     // 真实父子关系由路径表达。根会话与非网状会话为空,序列化省略。
     std::string agent_path;
+    std::string last_user_message_at; // ISO 8601; human input, not background activity.
+    std::string last_turn_outcome; // completed | aborted | error; empty = unknown/pending.
 };
 
 class SessionStorage {
diff --git a/src/engine/agent/turn/turn_finalizer.cpp b/src/engine/agent/turn/turn_finalizer.cpp
index aae4c5ed8..1b0064b21 100644
--- a/src/engine/agent/turn/turn_finalizer.cpp
+++ b/src/engine/agent/turn/turn_finalizer.cpp
@@ -165,7 +165,10 @@ void TurnFinalizer::step(Step selected, Frame& frame) {
     case Step::RecordOutcome: outcome_.record(status); break;
     case Step::ClearBusy: busy_ = false; break;
     case Step::BusyEvent: events_.emit(SessionEventKind::BusyChanged, frame.idle); break;
-    case Step::Done: events_.emit(SessionEventKind::Done, frame.done); break;
+    case Step::Done:
+        if (session_manager_) session_manager_->record_turn_outcome(status);
+        events_.emit(SessionEventKind::Done, frame.done);
+        break;
     case Step::AfterNormal: after_normal(*frame.turn); break;
     case Step::ContinueHook: continue_goal(); break;
     }
diff --git a/src/host/channels/core/access.cpp b/src/host/channels/core/access.cpp
new file mode 100644
index 000000000..2c768fc55
--- /dev/null
+++ b/src/host/channels/core/access.cpp
@@ -0,0 +1,218 @@
+#include "access.hpp"
+
+#include "channels/core/platforms.hpp"
+#include "platform/crypto/secure_random.hpp"
+
+#include <cstdint>
+
+namespace acecode::channels::core {
+namespace {
+
+constexpr std::size_t kPinDigits = 6;
+
+// 私聊文字是不是一串 6 位数字(两端空白不算);是就当作绑定码候选。
+std::string pin_candidate(const std::string& text) {
+    const auto begin = text.find_first_not_of(" \t\r\n");
+    if (begin == std::string::npos) return {};
+    const auto end = text.find_last_not_of(" \t\r\n");
+    const auto trimmed = text.substr(begin, end - begin + 1);
+    if (trimmed.size() != kPinDigits) return {};
+    for (const char c : trimmed)
+        if (c < '0' || c > '9') return {};
+    return trimmed;
+}
+
+bool is_pin(const std::string& code) { return code.size() == kPinDigits && !pin_candidate(code).empty(); }
+
+} // namespace
+
+std::string principal_for(const im::Address& address) {
+    const auto* spec = find_platform_spec(address.platform);
+    if (address.kind == im::ChatKind::Group && spec && spec->group_scoped_members)
+        return "member:" + address.chat + ":" + address.sender;
+    return "user:" + address.sender;
+}
+
+std::string group_principal(const im::Address& address) { return "group:" + address.chat; }
+
+std::string principal_kind(const std::string& principal) {
+    if (principal.rfind("group:", 0) == 0) return "group";
+    if (principal.rfind("member:", 0) == 0) return "member";
+    return "user";
+}
+
+void AccessControl::prune_locked(Clock::time_point now) {
+    for (auto it = requests_.begin(); it != requests_.end();) {
+        if (it->second.expires <= now) it = requests_.erase(it);
+        else ++it;
+    }
+    for (auto it = owner_codes_.begin(); it != owner_codes_.end();) {
+        if (it->second <= now) it = owner_codes_.erase(it);
+        else ++it;
+    }
+}
+
+bool AccessControl::has_pending_locked(const std::string& principal, Clock::time_point now) const {
+    for (const auto& [id, request] : requests_)
+        if (request.principal == principal && request.expires > now) return true;
+    return false;
+}
+
+std::optional<PendingRequest> AccessControl::create_locked(const std::string& principal, const im::Inbound& inbound,
+                                                           Clock::time_point now) {
+    if (has_pending_locked(principal, now) || requests_.size() >= kMaxPending) return std::nullopt;
+    PendingRequest request;
+    do {
+        request.id = platform::secure_random_token(8);
+    } while (!request.id.empty() && requests_.count(request.id));
+    if (request.id.empty()) return std::nullopt;
+    request.principal = principal;
+    request.kind = principal_kind(principal);
+    request.name = request.kind == "group" ? std::string{} : inbound.sender_name;
+    request.address = inbound.address;
+    request.expires = now + kRequestTtl;
+    requests_[request.id] = request;
+    return request;
+}
+
+AccessResult AccessControl::evaluate(const PlatformConfig& config, const im::Inbound& inbound,
+                                     Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    prune_locked(now);
+    AccessResult result;
+    result.principal = principal_for(inbound.address);
+    result.owner = !config.owner.empty() && config.owner == result.principal;
+
+    if (inbound.address.kind == im::ChatKind::Private) {
+        if (config.has_access(result.principal)) {
+            result.decision = AccessDecision::Allow;
+            result.reason = "authorized";
+            return result;
+        }
+        if (config.owner.empty()) {
+            const bool by_link = !inbound.start_code.empty();
+            const auto candidate = by_link ? inbound.start_code : pin_candidate(inbound.text);
+            const auto code = candidate.empty() ? owner_codes_.end() : owner_codes_.find(candidate);
+            if (code != owner_codes_.end()) {
+                owner_codes_.erase(code);  // 一次性
+                result.claimed_owner = result.owner = true;
+                result.decision = AccessDecision::Allow;
+                result.consumed = true;
+                result.reason = by_link ? "owner link accepted, sender is now the owner"
+                                        : "owner code accepted, sender is now the owner";
+                return result;
+            }
+            if (!by_link && !candidate.empty()) {
+                bool pins_active = false;
+                for (const auto& [value, expires] : owner_codes_) pins_active = pins_active || is_pin(value);
+                if (pins_active && ++pin_failures_ >= kMaxPinFailures) {
+                    for (auto it = owner_codes_.begin(); it != owner_codes_.end();) {
+                        if (is_pin(it->first)) it = owner_codes_.erase(it);
+                        else ++it;
+                    }
+                    pin_failures_ = 0;
+                }
+            }
+            if (owner_window_until_ > now) {
+                owner_window_until_ = {};
+                result.claimed_owner = result.owner = true;
+                result.decision = AccessDecision::Allow;
+                result.reason = "first private chat in the owner window, sender is now the owner";
+                return result;
+            }
+        }
+        result.created = create_locked(result.principal, inbound, now);
+        result.decision = result.created ? AccessDecision::NotifyPending : AccessDecision::Ignore;
+        result.reason = result.created ? "not authorized, approval requested"
+                                       : "not authorized, a request is already pending";
+        return result;
+    }
+
+    // 群聊:未点名一律忽略;群本身要先批准;然后发言人要被授权。
+    if (!inbound.mentioned) {
+        result.reason = "group message without @mention, ignored";
+        return result;
+    }
+    const auto group = group_principal(inbound.address);
+    if (!config.has_access(group)) {
+        result.created = create_locked(group, inbound, now);  // 不在群里回复,只在设置页出现请求
+        result.reason = result.created ? "group not approved, approval requested"
+                                       : "group not approved, a request is already pending";
+        return result;
+    }
+    if (config.has_access(result.principal)) {
+        result.decision = AccessDecision::Allow;
+        result.reason = "authorized";
+        return result;
+    }
+    result.created = create_locked(result.principal, inbound, now);
+    result.decision = result.created ? AccessDecision::NotifyPending : AccessDecision::Ignore;
+    result.reason = result.created ? "group member not authorized, approval requested"
+                                   : "group member not authorized, a request is already pending";
+    return result;
+}
+
+std::vector<PendingRequest> AccessControl::pending(Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    prune_locked(now);
+    std::vector<PendingRequest> out;
+    for (const auto& [id, request] : requests_) out.push_back(request);
+    return out;
+}
+
+std::optional<PendingRequest> AccessControl::take(const std::string& id, Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    prune_locked(now);
+    const auto it = requests_.find(id);
+    if (it == requests_.end()) return std::nullopt;
+    auto request = it->second;
+    requests_.erase(it);
+    return request;
+}
+
+void AccessControl::drop_principal(const std::string& principal) {
+    std::lock_guard<std::mutex> lock(mu_);
+    for (auto it = requests_.begin(); it != requests_.end();) {
+        if (it->second.principal == principal) it = requests_.erase(it);
+        else ++it;
+    }
+}
+
+std::string AccessControl::issue_owner_pin(Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    prune_locked(now);
+    for (int attempt = 0; attempt < 8; ++attempt) {
+        const auto random = platform::secure_random_bytes(4);
+        if (random.size() != 4) return {};
+        std::uint32_t value = 0;
+        for (const unsigned char byte : random) value = (value << 8) | byte;
+        std::string code = std::to_string(value % 1000000u);
+        code.insert(0, kPinDigits - code.size(), '0');
+        if (owner_codes_.count(code)) continue;
+        owner_codes_[code] = now + kOwnerTtl;
+        pin_failures_ = 0;
+        return code;
+    }
+    return {};
+}
+
+std::string AccessControl::issue_owner_code(Clock::time_point now) {
+    const auto code = platform::secure_random_token(24);
+    if (code.empty()) return {};
+    std::lock_guard<std::mutex> lock(mu_);
+    prune_locked(now);
+    owner_codes_[code] = now + kOwnerTtl;
+    return code;
+}
+
+void AccessControl::open_owner_window(Clock::time_point now) {
+    std::lock_guard<std::mutex> lock(mu_);
+    owner_window_until_ = now + kOwnerTtl;
+}
+
+bool AccessControl::owner_window_open(Clock::time_point now) const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return owner_window_until_ > now;
+}
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/access.hpp b/src/host/channels/core/access.hpp
new file mode 100644
index 000000000..745a6a0d1
--- /dev/null
+++ b/src/host/channels/core/access.hpp
@@ -0,0 +1,92 @@
+#pragma once
+
+// 消息通道的访问控制与配对(im-channels spec「访问控制与配对」)。
+//
+// 身份(principal):
+//   user:<id>            私聊联系人;用户 id 在平台内唯一的(Telegram、Discord 等),群里同一个人也用它
+//   group:<id>           群
+//   member:<群>:<成员>   群成员身份按群隔离的平台(QQ 的群成员 openid 与私聊 openid 不同)
+// 规则:默认拒绝;未授权私聊只得到配对提示并生成待批准请求(10 分钟过期);
+// 群要先批准、且只处理 @机器人 的消息;平台还没有机主时,第一个经扫码 / 一次性链接 /
+// 6 位绑定码 / 扫码后窗口确认的私聊联系人成为机主。
+
+#include "channels/core/store.hpp"
+#include "im/transport.hpp"
+
+#include <chrono>
+#include <map>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace acecode::channels::core {
+
+std::string principal_for(const im::Address& address);
+std::string group_principal(const im::Address& address);
+std::string principal_kind(const std::string& principal);  // "user" / "group" / "member"
+
+struct PendingRequest {
+    std::string id;         // 设置页审批用的短 id
+    std::string principal;
+    std::string kind;       // user / group / member
+    std::string name;       // 展示名(可空)
+    im::Address address;
+    std::chrono::steady_clock::time_point expires;
+};
+
+enum class AccessDecision {
+    Allow,          // 交给会话处理
+    Ignore,         // 静默忽略
+    NotifyPending,  // 回复一次配对提示
+};
+
+struct AccessResult {
+    AccessDecision decision = AccessDecision::Ignore;
+    std::string principal;
+    bool owner = false;          // 发送者是机主
+    bool claimed_owner = false;  // 这条消息让发送者成为机主,调用方需要持久化
+    std::optional<PendingRequest> created;  // 新建的待批准请求,调用方需要通知设置页
+    std::string reason;  // 判定原因,只用于日志(设置页不展示这些细节)
+    bool consumed = false;  // 这条消息只是绑定码(Telegram /start 或 6 位数字),不交给会话
+};
+
+class AccessControl {
+public:
+    using Clock = std::chrono::steady_clock;
+    static constexpr std::chrono::minutes kRequestTtl{10};
+    static constexpr std::chrono::minutes kOwnerTtl{10};
+    static constexpr std::size_t kMaxPending = 64;
+
+    AccessResult evaluate(const PlatformConfig& config, const im::Inbound& inbound, Clock::time_point now);
+
+    std::vector<PendingRequest> pending(Clock::time_point now);
+    // 审批时取走请求;已过期或不存在返回空。
+    std::optional<PendingRequest> take(const std::string& id, Clock::time_point now);
+    void drop_principal(const std::string& principal);
+
+    static constexpr int kMaxPinFailures = 10;
+
+    // Telegram 机主绑定链接里的一次性码,10 分钟有效。生成失败返回空串。
+    std::string issue_owner_code(Clock::time_point now);
+    // 6 位数字绑定码,机主私聊机器人发送它即成为机主;10 分钟有效、只能用一次。
+    // 有未过期的绑定码时,私聊里猜错 kMaxPinFailures 次就作废全部绑定码(防暴力猜测)。
+    std::string issue_owner_pin(Clock::time_point now);
+    // QQ 扫码成功但接口没给扫码人时:接下来 10 分钟内第一个私聊的人成为机主。
+    void open_owner_window(Clock::time_point now);
+    bool owner_window_open(Clock::time_point now) const;
+
+private:
+    std::optional<PendingRequest> create_locked(const std::string& principal, const im::Inbound& inbound,
+                                                Clock::time_point now);
+    bool has_pending_locked(const std::string& principal, Clock::time_point now) const;
+    void prune_locked(Clock::time_point now);
+
+    mutable std::mutex mu_;
+    std::map<std::string, PendingRequest> requests_;
+    std::map<std::string, Clock::time_point> owner_codes_;
+    int pin_failures_ = 0;
+    Clock::time_point owner_window_until_{};
+};
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/commands.cpp b/src/host/channels/core/commands.cpp
new file mode 100644
index 000000000..4f8fab464
--- /dev/null
+++ b/src/host/channels/core/commands.cpp
@@ -0,0 +1,134 @@
+#include "commands.hpp"
+
+#include <algorithm>
+#include <cctype>
+
+namespace acecode::channels::core {
+namespace {
+
+std::string trim(const std::string& text) {
+    std::size_t b = 0, e = text.size();
+    while (b < e && std::isspace(static_cast<unsigned char>(text[b]))) ++b;
+    while (e > b && std::isspace(static_cast<unsigned char>(text[e - 1]))) --e;
+    return text.substr(b, e - b);
+}
+
+std::string lower(std::string text) {
+    std::transform(text.begin(), text.end(), text.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    return text;
+}
+
+} // namespace
+
+Command parse_command(const std::string& raw) {
+    Command command;
+    const auto text = trim(raw);
+    if (text.empty() || text[0] != '/') return command;
+    const auto space = text.find_first_of(" \t\r\n");
+    const auto name = lower(text.substr(0, space));
+    command.argument = space == std::string::npos ? std::string{} : trim(text.substr(space));
+    if (name == "/help" || name == "/start") command.kind = CommandKind::Help;
+    else if (name == "/status") command.kind = CommandKind::Status;
+    else if (name == "/stop") command.kind = CommandKind::Stop;
+    else if (name == "/new") command.kind = CommandKind::New;
+    else if (name == "/sessions" || name == "/session") command.kind = CommandKind::Sessions;
+    else if (name == "/resume") command.kind = CommandKind::Resume;
+    else if (name == "/model" || name == "/models") command.kind = CommandKind::Model;
+    else if (name == "/approve") command.kind = CommandKind::Approve;
+    else if (name == "/deny") command.kind = CommandKind::Deny;
+    else if (name == "/aq") command.kind = CommandKind::Question;
+    else return Command{};
+
+    if (command.kind == CommandKind::Resume && command.argument.empty())
+        command.error = "用法:/resume <编号或会话 ID>。先发 /sessions 查看可切换的会话。";
+    if ((command.kind == CommandKind::Approve || command.kind == CommandKind::Deny) &&
+        (command.argument.empty() || command.argument.find(' ') != std::string::npos))
+        command.error = "用法:/approve <编号> 或 /deny <编号>。";
+    if (command.kind == CommandKind::Sessions && !command.argument.empty()) {
+        const auto lowered = lower(command.argument);
+        if (lowered != "more" && lowered != "all" && lowered.rfind("search ", 0) != 0)
+            command.error = "用法:/sessions、/sessions more 或 /sessions search <关键词>。";
+    }
+    return command;
+}
+
+bool runs_while_busy(CommandKind kind) { return kind != CommandKind::New && kind != CommandKind::Resume; }
+
+namespace texts {
+
+std::string help(bool owner) {
+    std::string text =
+        "可用命令:\n"
+        "/status 查看当前会话、模型和待处理事项\n"
+        "/stop 停止当前回合\n"
+        "/new 新建会话\n"
+        "/sessions 列出可切换的会话(more 查看更多,search <关键词> 搜索)\n"
+        "/resume <编号或会话 ID> 切换到某个会话\n"
+        "/model [名称] 查看或切换模型\n"
+        "/approve <编号>、/deny <编号> 处理权限请求\n"
+        "/aq 回答提问\n"
+        "其它文字会直接发给当前会话。";
+    if (!owner) text += "\n(你只能在自己创建的会话之间切换。)";
+    return text;
+}
+
+std::string pairing_notice() {
+    return "你还没有被授权使用这个 ACECode 机器人。已向机主发送请求,机主在 ACECode 设置页批准后,"
+           "请重新发送消息。请求 10 分钟后失效。";
+}
+
+std::string owner_bound() { return "已绑定为机主。现在可以直接发消息给 ACECode 了,发送 /help 查看命令。"; }
+
+std::string busy_reject() { return "当前会话正在执行,请先 /stop 或等它完成再切换会话。"; }
+
+std::string unsupported_media(const std::string& kind) { return "暂不支持" + kind + "消息,请发送文字、图片或文件。"; }
+
+std::string session_missing() {
+    return "无法打开当前绑定的会话(可能已被删除)。发送 /new 新建会话,或 /sessions 选择其它会话。";
+}
+
+std::string no_binding() { return "当前还没有会话。直接发消息即可开始,或发送 /sessions 选择已有会话。"; }
+
+std::string resume_denied() { return "只能切换到你自己通过这里创建的会话。发送 /sessions 查看可切换的会话。"; }
+
+std::string bound_elsewhere(const std::string& where) {
+    return "当前会话已转到" + where + "。之后的回复会发到那里;在这里继续发消息会开一个新会话。";
+}
+
+std::string transferred_here(const std::string& title) { return "已切换到会话:" + title; }
+
+std::string new_session(const std::string& location) { return "已新建会话(" + location + ")。"; }
+
+std::string stop_requested() { return "已请求停止当前回合。"; }
+
+std::string permission_prompt(const std::string& request_id, const std::string& tool, const std::string& args) {
+    return "需要你确认一个操作:" + tool + "\n" + args + "\n回复 /approve " + request_id + " 允许(仅这一次),或 /deny " +
+           request_id + " 拒绝。";
+}
+
+std::string permission_closed(const std::string& request_id, const std::string& choice) {
+    return "权限请求 " + request_id + " 已处理(" + choice + ")。";
+}
+
+std::string permission_unknown() { return "该权限请求已处理或不存在。"; }
+
+std::string permission_submitted(const std::string& request_id, bool approved) {
+    return std::string(approved ? "已允许" : "已拒绝") + "权限请求 " + request_id + "。";
+}
+
+std::string turn_failed(const std::string& reason) { return "处理失败:" + reason; }
+
+std::string input_rejected() { return "会话没有接受这条消息,请稍后重试。"; }
+
+std::string model_switched(const std::string& name) { return "已切换模型为 " + name + ",从下一回合起生效。"; }
+
+std::string model_unknown(const std::string& name, const std::vector<std::string>& names) {
+    std::string text = "没有名为 " + name + " 的模型。可用模型:";
+    for (const auto& item : names) text += "\n" + item;
+    return text;
+}
+
+} // namespace texts
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/commands.hpp b/src/host/channels/core/commands.hpp
new file mode 100644
index 000000000..adc264ecb
--- /dev/null
+++ b/src/host/channels/core/commands.hpp
@@ -0,0 +1,49 @@
+#pragma once
+
+// IM 内命令解析(纯逻辑)与中文提示文案(im-channels spec「IM 内命令」)。
+// 识别的命令不会作为对话内容提交给模型;不认识的 /xxx 照普通文本处理(可能是技能命令)。
+
+#include <string>
+#include <vector>
+
+namespace acecode::channels::core {
+
+enum class CommandKind { None, Help, Status, Stop, New, Sessions, Resume, Model, Approve, Deny, Question };
+
+struct Command {
+    CommandKind kind = CommandKind::None;
+    std::string argument;  // 去掉命令名后的参数(已去两端空白)
+    std::string error;     // 非空 = 用法错误,直接回复给用户
+};
+
+Command parse_command(const std::string& text);
+
+// 会话忙碌时能否立即执行;/new 与 /resume 需要先 /stop 或等待完成。
+bool runs_while_busy(CommandKind kind);
+
+namespace texts {
+
+std::string help(bool owner);
+std::string pairing_notice();
+std::string owner_bound();
+std::string busy_reject();
+std::string unsupported_media(const std::string& kind);
+std::string session_missing();
+std::string no_binding();
+std::string resume_denied();
+std::string bound_elsewhere(const std::string& where);
+std::string transferred_here(const std::string& title);
+std::string new_session(const std::string& location);
+std::string stop_requested();
+std::string permission_prompt(const std::string& request_id, const std::string& tool, const std::string& args);
+std::string permission_closed(const std::string& request_id, const std::string& choice);
+std::string permission_unknown();
+std::string permission_submitted(const std::string& request_id, bool approved);
+std::string turn_failed(const std::string& reason);
+std::string input_rejected();
+std::string model_switched(const std::string& name);
+std::string model_unknown(const std::string& name, const std::vector<std::string>& names);
+
+} // namespace texts
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/conversations.cpp b/src/host/channels/core/conversations.cpp
new file mode 100644
index 000000000..4a49e4f7d
--- /dev/null
+++ b/src/host/channels/core/conversations.cpp
@@ -0,0 +1,586 @@
+#include "conversations.hpp"
+
+#include "channels/core/platforms.hpp"
+#include "platform/crypto/secure_random.hpp"
+#include "session/attachment_store.hpp"
+#include "session/output_attachments.hpp"
+#include "session/session_storage.hpp"
+#include "utils/logger.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <algorithm>
+#include <cctype>
+#include <fstream>
+#include <iterator>
+#include <stdexcept>
+
+namespace acecode::channels::core {
+namespace {
+
+struct SessionMissing : std::runtime_error {
+    SessionMissing() : std::runtime_error("session missing") {}
+};
+
+bool all_digits(const std::string& text) {
+    return !text.empty() && std::all_of(text.begin(), text.end(), [](char c) { return c >= '0' && c <= '9'; });
+}
+
+std::string location_label(const BindingRecord& record) {
+    if (record.no_workspace || record.cwd.empty()) return "无项目";
+    return path_to_utf8(path_from_utf8(record.cwd).filename());
+}
+
+std::string media_kind_label(im::AttachmentKind kind) {
+    switch (kind) {
+        case im::AttachmentKind::Voice: return "语音";
+        case im::AttachmentKind::Video: return "视频";
+        case im::AttachmentKind::Sticker: return "贴纸";
+        default: return "此类";
+    }
+}
+
+std::string read_file(const std::filesystem::path& path) {
+    std::ifstream in(path, std::ios::binary);
+    return std::string((std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>());
+}
+
+const char* command_name(CommandKind kind) {
+    switch (kind) {
+        case CommandKind::Help: return "/help";
+        case CommandKind::Status: return "/status";
+        case CommandKind::Stop: return "/stop";
+        case CommandKind::New: return "/new";
+        case CommandKind::Sessions: return "/sessions";
+        case CommandKind::Resume: return "/resume";
+        case CommandKind::Model: return "/model";
+        case CommandKind::Approve: return "/approve";
+        case CommandKind::Deny: return "/deny";
+        case CommandKind::Question: return "/aq";
+        case CommandKind::None: break;
+    }
+    return "(text)";
+}
+
+} // namespace
+
+Conversations::Conversations(std::string platform, ChannelStore& store, AccessControl& access,
+                             std::shared_ptr<TransportSlot> transport, ConversationDeps deps)
+    : platform_(std::move(platform)), store_(store), access_(access), transport_(std::move(transport)),
+      deps_(std::move(deps)) {}
+
+Conversations::~Conversations() { shutdown(); }
+
+std::string Conversations::label_for(const im::Address& address) {
+    std::string label = platform_label(address.platform);
+    label += address.kind == im::ChatKind::Group ? " 群聊" : " 私聊";
+    return label;
+}
+
+void Conversations::reply(const im::Inbound& inbound, const std::string& text) {
+    if (auto projection = projection_for(inbound.address.key())) {
+        projection->say(text, inbound.reply_context);
+        return;
+    }
+    const auto transport = transport_->get();
+    if (!transport) return;
+    const auto result = transport->send_text(inbound.address, text, inbound.reply_context);
+    if (!result.ok()) LOG_WARN("[channels/" + platform_ + "] reply failed: " + result.error);
+}
+
+std::shared_ptr<Projection> Conversations::projection_for(const std::string& key) const {
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto it = projections_.find(key);
+    return it == projections_.end() ? nullptr : it->second;
+}
+
+HandleOutcome Conversations::handle(const im::Inbound& inbound) {
+    HandleOutcome outcome;
+    const auto config = store_.config();
+    const auto access = access_.evaluate(config, inbound, AccessControl::Clock::now());
+    outcome.pending_created = access.created;
+    {
+        // 只记来源、长度和判定原因,不记消息内容。
+        const auto line = "[channels/" + platform_ + "] inbound " + label_for(inbound.address) + " chat " +
+                          inbound.address.chat + " from " + access.principal + " (" +
+                          std::to_string(inbound.text.size()) + " bytes, " +
+                          std::to_string(inbound.attachments.size()) + " attachment(s)): " + access.reason;
+        if (access.created || access.claimed_owner) LOG_INFO(line);
+        else LOG_DEBUG(line);
+    }
+    if (access.claimed_owner) {
+        store_.update_config([&access, &inbound](PlatformConfig& c) {
+            c.owner = access.principal;
+            if (!c.has_access(access.principal))
+                c.access.push_back({access.principal, inbound.sender_name, now_wall_ms()});
+        });
+        outcome.owner_claimed = true;
+        reply(inbound, texts::owner_bound());
+        if (access.consumed) return outcome;  // 绑定码(/start <码> 或 6 位数字)本身不交给会话
+    }
+    if (access.decision == AccessDecision::NotifyPending) {
+        reply(inbound, texts::pairing_notice());
+        return outcome;
+    }
+    if (access.decision != AccessDecision::Allow) return outcome;
+
+    const auto key = inbound.address.key();
+    if (store_.has_receipt(key, inbound.message_id)) return outcome;
+    // 先记回执再处理:崩溃时宁可让对方重发,也不重复执行工具。
+    store_.remember_receipt(key, inbound.message_id);
+    try {
+        dispatch(inbound, access.owner);
+    } catch (const SessionMissing&) {
+        reply(inbound, texts::session_missing());
+    } catch (const std::exception& e) {
+        store_.forget_receipt(key, inbound.message_id);
+        reply(inbound, texts::turn_failed(e.what()));
+    }
+    return outcome;
+}
+
+void Conversations::dispatch(const im::Inbound& inbound, bool owner) {
+    const auto command = parse_command(inbound.text);
+    if (!command.error.empty()) {
+        reply(inbound, command.error);
+        return;
+    }
+    if (command.kind != CommandKind::None) {
+        LOG_INFO("[channels/" + platform_ + "] command " + command_name(command.kind) + " in " +
+                 label_for(inbound.address) + " chat " + inbound.address.chat);
+    }
+    switch (command.kind) {
+        case CommandKind::Help: reply(inbound, texts::help(owner)); return;
+        case CommandKind::Sessions: list_sessions(inbound, owner, command.argument); return;
+        case CommandKind::Resume: resume(inbound, owner, command.argument); return;
+        case CommandKind::New: new_session(inbound); return;
+        case CommandKind::None: submit(inbound); return;
+        default: handle_bound_command(inbound, command); return;
+    }
+}
+
+std::optional<SessionInfo> Conversations::session_info(const std::string& session_id) const {
+    for (auto& info : deps_.sessions->list_sessions())
+        if (info.id == session_id) return info;
+    return std::nullopt;
+}
+
+void Conversations::handle_bound_command(const im::Inbound& inbound, const Command& command) {
+    const auto record = store_.binding(inbound.address.key());
+    if (!record) {
+        reply(inbound, texts::no_binding());
+        return;
+    }
+    const auto projection = ensure_projection(*record);
+    const auto& id = record->session_id;
+    switch (command.kind) {
+        case CommandKind::Stop:
+            deps_.sessions->abort(id);
+            reply(inbound, texts::stop_requested());
+            return;
+        case CommandKind::Status: {
+            const auto info = session_info(id);
+            std::string text = "平台:" + platform_label(platform_) + "\n会话:" +
+                               (info && !info->title.empty() ? info->title : id) + "\n位置:" +
+                               location_label(*record) + "\n模型:" +
+                               (info && !info->model_name.empty() ? info->model_name : std::string("默认")) +
+                               "\n状态:" + (info && info->busy ? "执行中" : "空闲");
+            const auto permissions = projection->pending_permission_ids();
+            for (const auto& request : permissions) text += "\n待确认权限:" + request;
+            for (const auto& line : projection->pending_question_texts()) text += "\n" + line;
+            reply(inbound, text);
+            return;
+        }
+        case CommandKind::Model: {
+            const auto names = deps_.model_names ? deps_.model_names() : std::vector<std::string>{};
+            if (command.argument.empty()) {
+                const auto info = session_info(id);
+                std::string text = "可用模型(* 为当前):";
+                for (const auto& name : names)
+                    text += "\n" + std::string(info && info->model_name == name ? "* " : "  ") + name;
+                reply(inbound, text);
+                return;
+            }
+            if (std::find(names.begin(), names.end(), command.argument) == names.end()) {
+                reply(inbound, texts::model_unknown(command.argument, names));
+                return;
+            }
+            std::string error;
+            if (!deps_.switch_model || !deps_.switch_model(id, command.argument, &error)) {
+                reply(inbound, texts::turn_failed(error.empty() ? "切换模型失败" : error));
+                return;
+            }
+            reply(inbound, texts::model_switched(command.argument));
+            return;
+        }
+        case CommandKind::Approve:
+        case CommandKind::Deny: {
+            if (!projection->take_permission(command.argument)) {
+                reply(inbound, texts::permission_unknown());
+                return;
+            }
+            const bool approve = command.kind == CommandKind::Approve;
+            deps_.sessions->respond_permission(
+                id, {command.argument, approve ? PermissionDecisionChoice::Allow : PermissionDecisionChoice::Deny});
+            reply(inbound, texts::permission_submitted(command.argument, approve));
+            return;
+        }
+        case CommandKind::Question: {
+            const auto action = projection->with_questions(
+                [&inbound](rc::ChannelQuestionBridge& questions) { return questions.handle_input(inbound.text); });
+            projection->emit_question_action(action);
+            if (!action.submission) return;
+            // respond_question 可能同步触发 QuestionClosed,必须在问题状态机锁外调用。
+            const auto status = deps_.sessions->respond_question(id, action.submission->request_id,
+                                                                 action.submission->response);
+            projection->emit_question_action(
+                projection->with_questions([&action, status](rc::ChannelQuestionBridge& questions) {
+                    return questions.complete_submission(action.submission->request_id, status);
+                }));
+            return;
+        }
+        default:
+            return;
+    }
+}
+
+std::vector<rc::RcSessionTarget> Conversations::visible_sessions(const std::string& key, bool owner,
+                                                                   const std::optional<std::string>& query) const {
+    auto targets = deps_.catalog ? deps_.catalog(query) : std::vector<rc::RcSessionTarget>{};
+    if (owner) return targets;
+    const auto created = store_.created_sessions(key);
+    targets.erase(std::remove_if(targets.begin(), targets.end(),
+                                 [&](const rc::RcSessionTarget& target) {
+                                     return std::find(created.begin(), created.end(), target.session_id) ==
+                                            created.end();
+                                 }),
+                  targets.end());
+    return targets;
+}
+
+void Conversations::list_sessions(const im::Inbound& inbound, bool owner, const std::string& argument) {
+    std::optional<std::string> query;
+    std::size_t limit = rc::kRcSessionRecentLimit;
+    std::string lowered = argument;
+    std::transform(lowered.begin(), lowered.end(), lowered.begin(),
+                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+    if (lowered.rfind("search ", 0) == 0) {
+        query = argument.substr(7);
+        limit = rc::kRcSessionSearchLimit;
+    } else if (lowered == "more" || lowered == "all") {
+        limit = 50;
+    }
+    auto targets = visible_sessions(inbound.address.key(), owner, query);
+    if (targets.size() > limit) targets.resize(limit);
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        snapshots_[inbound.address.key()] = targets;
+    }
+    if (targets.empty()) {
+        reply(inbound, owner ? "没有可切换的会话。" : "你还没有通过这里创建过会话。");
+        return;
+    }
+    reply(inbound, rc::format_rc_session_listing(targets, "可切换的会话(发送 /resume <编号> 切换):"));
+}
+
+void Conversations::resume(const im::Inbound& inbound, bool owner, const std::string& argument) {
+    const auto key = inbound.address.key();
+    const auto current = store_.binding(key);
+    if (current) {
+        const auto info = session_info(current->session_id);
+        if (info && info->busy) {
+            reply(inbound, texts::busy_reject());
+            return;
+        }
+    }
+    std::optional<rc::RcSessionTarget> target;
+    if (all_digits(argument) && argument.size() <= 6) {
+        std::vector<rc::RcSessionTarget> snapshot;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            const auto it = snapshots_.find(key);
+            if (it != snapshots_.end()) snapshot = it->second;
+        }
+        if (snapshot.empty()) {
+            snapshot = visible_sessions(key, owner, std::nullopt);
+            if (snapshot.size() > rc::kRcSessionRecentLimit) snapshot.resize(rc::kRcSessionRecentLimit);
+        }
+        target = rc::select_rc_session_snapshot(snapshot, std::stoul(argument));
+    } else {
+        for (const auto& candidate : visible_sessions(key, true, std::nullopt))
+            if (candidate.session_id == argument) target = candidate;
+    }
+    if (!target) {
+        reply(inbound, "没有找到这个会话。先发送 /sessions 查看可切换的会话。");
+        return;
+    }
+    if (!owner) {
+        const auto created = store_.created_sessions(key);
+        if (std::find(created.begin(), created.end(), target->session_id) == created.end()) {
+            reply(inbound, texts::resume_denied());
+            return;
+        }
+    }
+    if (current && current->session_id == target->session_id) {
+        reply(inbound, "已经在这个会话里了。");
+        return;
+    }
+    if (!deps_.resume_target || !deps_.resume_target(*target)) {
+        reply(inbound, texts::session_missing());
+        return;
+    }
+    BindingRecord record;
+    record.address = inbound.address;
+    record.session_id = target->session_id;
+    record.cwd = target->cwd;
+    record.workspace_hash = target->workspace_hash;
+    record.no_workspace = target->no_workspace;
+    record.updated_at_ms = now_wall_ms();
+    switch_binding(record);
+    reply(inbound, texts::transferred_here(target->title.empty() ? target->session_id : target->title));
+}
+
+BindingRecord Conversations::create_binding(const im::Address& address, const std::optional<BindingRecord>& near) {
+    SessionOptions options;
+    options.permission_mode = "default";
+    options.inherit_dangerous_mode = false;
+    if (near && !near->no_workspace) {
+        options.cwd = near->cwd;
+        options.workspace_hash = near->workspace_hash;
+    } else {
+        options.no_workspace = true;
+    }
+    const auto id = deps_.sessions->create_session(options);
+    if (id.empty()) throw std::runtime_error("无法创建会话");
+    BindingRecord record;
+    record.address = address;
+    record.session_id = id;
+    record.cwd = deps_.session_cwd ? deps_.session_cwd(id) : std::string{};
+    record.no_workspace = options.no_workspace;
+    record.workspace_hash = options.no_workspace ? std::string{} : options.workspace_hash;
+    record.updated_at_ms = now_wall_ms();
+    store_.remember_created(address.key(), id);
+    return record;
+}
+
+void Conversations::new_session(const im::Inbound& inbound) {
+    const auto current = store_.binding(inbound.address.key());
+    if (current) {
+        const auto info = session_info(current->session_id);
+        if (info && info->busy) {
+            reply(inbound, texts::busy_reject());
+            return;
+        }
+    }
+    const auto record = create_binding(inbound.address, current);
+    switch_binding(record);
+    reply(inbound, texts::new_session(location_label(record)));
+}
+
+std::shared_ptr<Projection> Conversations::ensure_projection(const BindingRecord& record) {
+    const auto key = record.address.key();
+    if (auto existing = projection_for(key); existing && existing->record().session_id == record.session_id)
+        return existing;
+    rc::RcSessionTarget target;
+    target.session_id = record.session_id;
+    target.cwd = record.cwd;
+    target.workspace_hash = record.workspace_hash;
+    target.no_workspace = record.no_workspace;
+    if (!deps_.resume_target || !deps_.resume_target(target)) throw SessionMissing();
+    auto projection = std::make_shared<Projection>(
+        record, ProjectionDeps{deps_.sessions, transport_, deps_.pending_permissions});
+    projection->start();
+    std::shared_ptr<Projection> previous;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        previous = std::move(projections_[key]);
+        projections_[key] = projection;
+    }
+    if (previous) previous->stop();
+    return projection;
+}
+
+void Conversations::switch_binding(const BindingRecord& record) {
+    const auto key = record.address.key();
+    if (deps_.release_session) deps_.release_session(record.session_id, key, label_for(record.address));
+    store_.put_binding(record);
+    ensure_projection(record);
+    if (deps_.on_bindings_changed) deps_.on_bindings_changed();
+}
+
+bool Conversations::release_session(const std::string& session_id, const std::string& except_key,
+                                    const std::string& taker_label) {
+    bool released = false;
+    for (const auto& record : store_.bindings()) {
+        const auto key = record.address.key();
+        if (record.session_id != session_id || key == except_key) continue;
+        std::shared_ptr<Projection> projection;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            const auto it = projections_.find(key);
+            if (it != projections_.end()) {
+                projection = it->second;
+                projections_.erase(it);
+            }
+        }
+        const auto notice = texts::bound_elsewhere(taker_label);
+        if (projection) {
+            projection->say(notice, nlohmann::json::object());
+            projection->stop();
+        } else if (const auto transport = transport_->get()) {
+            transport->send_text(record.address, notice, nlohmann::json::object());
+        }
+        store_.erase_binding(key);
+        released = true;
+    }
+    return released;
+}
+
+void Conversations::submit(const im::Inbound& inbound) {
+    const auto key = inbound.address.key();
+    auto record = store_.binding(key);
+    if (!record) {
+        record = create_binding(inbound.address, std::nullopt);
+        store_.put_binding(*record);
+        if (deps_.on_bindings_changed) deps_.on_bindings_changed();
+    }
+    const auto projection = ensure_projection(*record);
+    const auto& session_id = record->session_id;
+
+    std::string text = inbound.text;
+    std::vector<im::Attachment> files;
+    for (const auto& attachment : inbound.attachments) {
+        if (attachment.kind == im::AttachmentKind::Voice && !attachment.transcript.empty()) {
+            text += (text.empty() ? "" : "\n") + std::string("[语音转写] ") + attachment.transcript;
+        } else if (attachment.kind == im::AttachmentKind::Image || attachment.kind == im::AttachmentKind::File) {
+            files.push_back(attachment);
+        } else {
+            reply(inbound, texts::unsupported_media(media_kind_label(attachment.kind)));
+        }
+    }
+    if (text.empty() && files.empty()) return;
+    if (!inbound.quote_text.empty())
+        text = "[引用的消息]\n" + inbound.quote_text + "\n[引用结束]\n" + text;
+
+    nlohmann::json channel{{"platform", platform_},
+                           {"address", inbound.address.to_json()},
+                           {"message_id", inbound.message_id},
+                           {"reply_context", inbound.reply_context}};
+    if (!inbound.sender_name.empty()) channel["sender_name"] = inbound.sender_name;
+
+    // 提问挂起时的普通文字视为插话,同一回合紧跟在工具结果后交给模型。
+    if (files.empty() && !text.empty()) {
+        const auto request_id = projection->with_questions(
+            [](rc::ChannelQuestionBridge& questions) { return questions.begin_interjection(); });
+        if (request_id) {
+            UserInput interjection;
+            interjection.text = text;
+            interjection.metadata["channel"] = channel;
+            const auto result = deps_.sessions->interject_question(session_id, *request_id, interjection);
+            const auto outcome = result.accepted() ? QuestionResponseStatus::Accepted : QuestionResponseStatus::Closed;
+            projection->emit_question_action(
+                projection->with_questions([&request_id, outcome](rc::ChannelQuestionBridge& questions) {
+                    return questions.complete_submission(*request_id, outcome);
+                }));
+            if (result.accepted()) return;
+        }
+    }
+
+    UserInput input;
+    input.text = deps_.expand_skill && !text.empty() && text[0] == '/' ? deps_.expand_skill(session_id, text) : text;
+    input.display_text = inbound.text.empty() ? text : inbound.text;
+    input.metadata["channel"] = channel;
+    if (!files.empty()) {
+        const auto transport = transport_->get();
+        if (!transport) throw std::runtime_error("通道未连接");
+        if (!input.text.empty()) input.content_parts.push_back({{"type", "text"}, {"text", input.text}});
+        nlohmann::json saved = nlohmann::json::array();
+        std::filesystem::create_directories(deps_.media_dir);
+        for (const auto& file : files) {
+            const auto temp = deps_.media_dir / ("in-" + platform::secure_random_token(16));
+            std::string error;
+            if (!transport->download(file, temp, &error)) {
+                std::error_code ec;
+                std::filesystem::remove(temp, ec);
+                reply(inbound, texts::turn_failed(error));
+                continue;
+            }
+            const auto bytes = read_file(temp);
+            std::error_code ec;
+            std::filesystem::remove(temp, ec);
+            const auto name = file.name.empty() ? std::string(file.kind == im::AttachmentKind::Image ? "image.jpg" : "file")
+                                                : file.name;
+            const auto stored = save_attachment(SessionStorage::get_project_dir(record->cwd), session_id, name,
+                                                file.mime_type, bytes, &error);
+            if (!stored) {
+                reply(inbound, texts::turn_failed(error));
+                continue;
+            }
+            input.content_parts.push_back(attachment_content_part(*stored));
+            saved.push_back(attachment_to_json(*stored));
+        }
+        if (!saved.empty()) input.metadata["attachments"] = saved;
+        if (saved.empty() && text.empty()) return;
+    }
+    if (input.empty()) return;
+    if (!deps_.sessions->send_input(session_id, input)) reply(inbound, texts::input_rejected());
+}
+
+void Conversations::restore() {
+    for (const auto& record : store_.bindings()) {
+        if (!transport_->get()) return;
+        try {
+            ensure_projection(record);
+        } catch (const SessionMissing&) {
+        } catch (const std::exception& e) {
+            LOG_WARN("[channels/" + platform_ + "] restore binding failed: " + e.what());
+        }
+    }
+}
+
+void Conversations::shutdown() {
+    std::map<std::string, std::shared_ptr<Projection>> projections;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        projections.swap(projections_);
+        snapshots_.clear();
+    }
+    for (auto& [key, projection] : projections) projection->stop();
+}
+
+void Conversations::abort_principal(const std::string& principal) {
+    for (const auto& record : store_.bindings()) {
+        const bool match = principal_for(record.address) == principal ||
+                           (principal_kind(principal) == "group" && group_principal(record.address) == principal);
+        if (match) deps_.sessions->abort(record.session_id);
+    }
+}
+
+nlohmann::json Conversations::bindings_json() const {
+    nlohmann::json out = nlohmann::json::array();
+    for (const auto& record : store_.bindings()) {
+        nlohmann::json item{{"key", record.address.key()},
+                            {"label", label_for(record.address)},
+                            {"chat", record.address.chat},
+                            {"sender", record.address.sender},
+                            {"session_id", record.session_id},
+                            {"no_workspace", record.no_workspace},
+                            {"cwd", record.cwd},
+                            {"workspace_hash", record.workspace_hash}};
+        if (const auto projection = projection_for(record.address.key())) {
+            const auto stats = projection->stats();
+            item["sent"] = stats.outbound_sent;
+            item["failed"] = stats.outbound_failed;
+            item["dropped"] = stats.outbound_dropped;
+        }
+        out.push_back(std::move(item));
+    }
+    return out;
+}
+
+std::vector<std::string> Conversations::bound_session_ids() const {
+    std::vector<std::string> ids;
+    for (const auto& record : store_.bindings()) ids.push_back(record.session_id);
+    return ids;
+}
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/conversations.hpp b/src/host/channels/core/conversations.hpp
new file mode 100644
index 000000000..c0f2eb0fa
--- /dev/null
+++ b/src/host/channels/core/conversations.hpp
@@ -0,0 +1,98 @@
+#pragma once
+
+// 一个平台的会话路由(im-channels spec「IM 会话与 ACECode 会话绑定」「IM 内命令」
+// 「机主与会话切换范围」,design D6):
+//   - 每个 IM 会话同一时刻绑定一个 ACECode 会话;第一条普通消息新建无项目会话
+//     (default 权限,不继承 daemon 的危险标志);绑定持久化,重启后续接。
+//   - /new 在当前位置新建;/sessions + /resume 切换(机主可选任意会话,其他人只能选
+//     自己创建过的会话);会话忙碌时拒绝切换。
+//   - 一个 ACECode 会话只绑定一个 IM 会话:被别处接管时通知原 IM 会话并解除绑定。
+// handle() 只在该平台的工作线程上串行调用;查询接口可从任意线程调用。
+
+#include "channels/core/access.hpp"
+#include "channels/core/commands.hpp"
+#include "channels/core/projection.hpp"
+#include "channels/core/store.hpp"
+#include "remote_control/rc_session_navigation.hpp"
+#include "session/session_client.hpp"
+
+#include <filesystem>
+#include <functional>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace acecode::channels::core {
+
+struct ConversationDeps {
+    SessionClient* sessions = nullptr;
+    std::function<std::vector<nlohmann::json>(const std::string&)> pending_permissions;
+    std::function<std::string(const std::string&)> session_cwd;
+    std::function<std::vector<rc::RcSessionTarget>(const std::optional<std::string>&)> catalog;
+    std::function<bool(const rc::RcSessionTarget&)> resume_target;
+    std::function<std::vector<std::string>()> model_names;
+    std::function<bool(const std::string&, const std::string&, std::string*)> switch_model;
+    // 普通文本提交前做技能命令展开(与 Web 输入一致);返回展开后的文本。
+    std::function<std::string(const std::string& session_id, const std::string& text)> expand_skill;
+    // 某会话即将被 taker 接管:host 让所有平台释放它(跨平台转移绑定)。
+    std::function<void(const std::string& session_id, const std::string& taker_key,
+                       const std::string& taker_label)> release_session;
+    std::function<void()> on_bindings_changed;
+    std::filesystem::path media_dir;  // 入站附件的临时下载目录
+};
+
+struct HandleOutcome {
+    std::optional<PendingRequest> pending_created;
+    bool owner_claimed = false;
+};
+
+class Conversations {
+public:
+    Conversations(std::string platform, ChannelStore& store, AccessControl& access,
+                  std::shared_ptr<TransportSlot> transport, ConversationDeps deps);
+    ~Conversations();
+
+    HandleOutcome handle(const im::Inbound& inbound);
+    // 连接后为已有绑定恢复出站投影,使 Desktop 里的输入也能把回复发到 IM;
+    // 会话已被删除的绑定保留,等对方下一条消息时提示。与 handle() 在同一线程串行调用。
+    void restore();
+    // 若本平台有 IM 会话(除 except_key 外)绑定着该会话:通知它、解除绑定。
+    bool release_session(const std::string& session_id, const std::string& except_key,
+                         const std::string& taker_label);
+    void shutdown();
+    // 撤销授权:中止该身份所有绑定会话正在进行的回合。
+    void abort_principal(const std::string& principal);
+    nlohmann::json bindings_json() const;
+    std::vector<std::string> bound_session_ids() const;
+    static std::string label_for(const im::Address& address);
+
+private:
+    void dispatch(const im::Inbound& inbound, bool owner);
+    void reply(const im::Inbound& inbound, const std::string& text);
+    void submit(const im::Inbound& inbound);
+    void handle_bound_command(const im::Inbound& inbound, const Command& command);
+    void list_sessions(const im::Inbound& inbound, bool owner, const std::string& argument);
+    void resume(const im::Inbound& inbound, bool owner, const std::string& argument);
+    void new_session(const im::Inbound& inbound);
+    BindingRecord create_binding(const im::Address& address, const std::optional<BindingRecord>& near);
+    std::shared_ptr<Projection> ensure_projection(const BindingRecord& record);
+    std::shared_ptr<Projection> projection_for(const std::string& key) const;
+    void switch_binding(const BindingRecord& record);
+    std::optional<SessionInfo> session_info(const std::string& session_id) const;
+    std::vector<rc::RcSessionTarget> visible_sessions(const std::string& key, bool owner,
+                                                      const std::optional<std::string>& query) const;
+
+    std::string platform_;
+    ChannelStore& store_;
+    AccessControl& access_;
+    std::shared_ptr<TransportSlot> transport_;
+    ConversationDeps deps_;
+    mutable std::mutex mu_;
+    std::map<std::string, std::shared_ptr<Projection>> projections_;
+    std::map<std::string, std::vector<rc::RcSessionTarget>> snapshots_;
+};
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/host.cpp b/src/host/channels/core/host.cpp
new file mode 100644
index 000000000..ebed15574
--- /dev/null
+++ b/src/host/channels/core/host.cpp
@@ -0,0 +1,230 @@
+#include "host.hpp"
+
+#include "utils/logger.hpp"
+
+#include <stdexcept>
+
+namespace acecode::channels::core {
+
+ChannelHost::ChannelHost(std::filesystem::path root, HostServices services)
+    : root_(std::move(root)), services_(std::move(services)) {
+    for (const auto& name : platform_names()) {
+        RuntimeServices runtime;
+        runtime.conversation = services_.conversation;
+        runtime.conversation.media_dir.clear();  // 由运行时放到 <root>/<platform>/media
+        const auto ref = lifetime_.ref(*this);
+        runtime.conversation.release_session = [ref](const std::string& session_id, const std::string& taker_key,
+                                                     const std::string& label) {
+            ref.with([&session_id, &taker_key, &label](ChannelHost& host) {
+                host.release_across(session_id, taker_key, label);
+            });
+        };
+        runtime.conversation.on_bindings_changed = [ref] { ref.with([](ChannelHost& host) { host.publish_all(); }); };
+        if (services_.make_transport) {
+            runtime.make_transport = services_.make_transport;
+        } else {
+            runtime.make_transport = [ref](const std::string& platform, const PlatformConfig& config,
+                                           ChannelStore& store) {
+                std::shared_ptr<im::Transport> transport;
+                ref.with([&transport, &platform, &config, &store](ChannelHost& host) {
+                    transport = make_platform_transport(platform, config, store, host.services_);
+                });
+                return transport;
+            };
+        }
+        if (services_.validate_credentials) {
+            runtime.validate_credentials = services_.validate_credentials;
+        } else {
+            runtime.validate_credentials = [ref](const std::string& platform, const nlohmann::json& credentials,
+                                                 std::string* error) {
+                nlohmann::json result;
+                ref.with([&result, &platform, &credentials, error](ChannelHost& host) {
+                    result = validate_platform_credentials(platform, credentials, host.services_, error);
+                });
+                return result;
+            };
+        }
+        runtime.broadcast = services_.broadcast;
+        runtime.current_pid = services_.current_pid;
+        runtime.standby_retry = services_.standby_retry;
+        runtimes_[name] = std::make_unique<PlatformRuntime>(name, root_ / name, std::move(runtime));
+    }
+}
+
+ChannelHost::~ChannelHost() { stop(); }
+
+void ChannelHost::start() {
+    for (const auto& name : platform_names()) runtimes_.at(name)->start();
+}
+
+void ChannelHost::stop() {
+    acecode::JoiningThread thread;
+    {
+        std::lock_guard<std::mutex> lock(bind_mu_);
+        if (bind_cancel_) bind_cancel_->store(true);
+        thread = std::move(bind_thread_);
+    }
+    if (thread.joinable()) thread.join();
+    for (const auto& name : platform_names()) runtimes_.at(name)->stop();
+}
+
+bool ChannelHost::has_platform(const std::string& name) const { return runtimes_.count(name) > 0; }
+
+PlatformRuntime& ChannelHost::platform(const std::string& name) {
+    const auto it = runtimes_.find(name);
+    if (it == runtimes_.end()) throw std::invalid_argument("未知的消息通道平台");
+    return *it->second;
+}
+
+nlohmann::json ChannelHost::snapshot() const {
+    nlohmann::json platforms = nlohmann::json::array();
+    nlohmann::json binds = nlohmann::json::object();
+    for (const auto& spec : platform_specs()) {
+        platforms.push_back(runtimes_.at(spec.name)->snapshot());
+        if (spec.scan_bind) binds[spec.name] = bind_state(spec.name);
+    }
+    return {{"platforms", platforms}, {"binds", binds}};
+}
+
+void ChannelHost::publish_all() {
+    for (const auto& name : platform_names()) runtimes_.at(name)->publish_state();
+}
+
+void ChannelHost::publish_bind(const nlohmann::json& state) {
+    if (services_.broadcast) services_.broadcast("channels_bind", state);
+}
+
+nlohmann::json ChannelHost::start_bind(const std::string& platform) {
+    const auto* spec = find_platform_spec(platform);
+    auto runner = spec && spec->scan_bind ? make_bind_runner(platform, services_) : BindRunner{};
+    if (!runner) throw std::invalid_argument("该平台不支持扫码绑定");
+    nlohmann::json state;
+    {
+        std::lock_guard<std::mutex> lock(bind_mu_);
+        if (bind_running_) throw std::runtime_error("已有扫码流程在进行,请先完成或取消");
+        if (bind_thread_.joinable()) bind_thread_.join();  // 上一次已结束的流程
+        bind_running_ = true;
+        auto cancelled = std::make_shared<std::atomic<bool>>(false);
+        bind_cancel_ = cancelled;
+        bind_state_ = {{"platform", platform}, {"phase", "starting"}};
+        state = bind_state_;
+        bind_thread_ = acecode::JoiningThread([ref = lifetime_.ref(*this), platform, runner, cancelled] {
+            ref.with([&platform, &runner, &cancelled](ChannelHost& host) {
+                host.run_bind_flow(platform, runner, cancelled);
+            });
+        });
+    }
+    LOG_INFO("[channels/" + platform + "] QR binding started");
+    publish_bind(state);
+    return state;
+}
+
+// 在扫码线程上运行;runner 在返回前同步回调 progress。
+void ChannelHost::run_bind_flow(const std::string& platform, const BindRunner& runner,
+                                const std::shared_ptr<std::atomic<bool>>& cancelled) {
+    const auto outcome = runner(
+        *cancelled, [&mu = bind_mu_, &state = bind_state_, &broadcast = services_.broadcast, &platform,
+                     cancelled](const BindProgress& update) {
+            if (cancelled->load()) return;
+            // 二维码内容不写日志(spec:扫码载荷保密),只记进度。
+            LOG_INFO(update.refreshes > 0 ? "[channels/" + platform + "] QR code expired and was refreshed (" +
+                                                std::to_string(update.refreshes) + ")"
+                                          : "[channels/" + platform + "] QR code ready, waiting for the scan");
+            nlohmann::json waiting{{"platform", platform},
+                                   {"phase", "waiting"},
+                                   {"qr_url", update.qr_url},
+                                   {"refreshes", update.refreshes}};
+            {
+                std::lock_guard<std::mutex> lock(mu);
+                state = waiting;
+            }
+            if (broadcast) broadcast("channels_bind", waiting);
+        });
+    finish_bind(platform, outcome, cancelled);
+}
+
+void ChannelHost::finish_bind(const std::string& platform, const BindOutcome& outcome,
+                              const std::shared_ptr<std::atomic<bool>>& cancelled) {
+    nlohmann::json state{{"platform", platform}, {"phase", outcome.phase}};
+    if (outcome.phase == "completed" && cancelled->load()) {
+        state["phase"] = "cancelled";  // 取消与完成同时发生:按取消处理,不改配置
+    } else if (outcome.phase == "completed") {
+        try {
+            auto& runtime = this->platform(platform);
+            runtime.set_credentials(outcome.credentials, false);
+            if (!outcome.owner.empty()) runtime.set_owner(outcome.owner, outcome.owner_name);
+            else if (runtime.owner().empty()) runtime.open_owner_window();
+            runtime.set_enabled(true);
+            state["account"] = outcome.account;
+            state["owner_bound"] = !outcome.owner.empty();
+        } catch (const std::exception& e) {
+            state = {{"platform", platform}, {"phase", "failed"}, {"error", std::string("保存配置失败:") + e.what()}};
+        }
+    } else if (outcome.phase == "failed") {
+        state["error"] = outcome.error.empty() ? std::string("扫码绑定失败") : outcome.error;
+    } else if (outcome.phase == "timed_out") {
+        state["error"] = "扫码超时,请重新发起";
+    }
+    const auto phase = state.value("phase", std::string{});
+    if (phase == "completed") {
+        LOG_INFO("[channels/" + platform + "] QR binding completed, account " + outcome.account +
+                 (state.value("owner_bound", false) ? ", the scanner is the owner" : ", owner window opened"));
+    } else if (phase == "cancelled") {
+        LOG_INFO("[channels/" + platform + "] QR binding cancelled, configuration unchanged");
+    } else {
+        LOG_WARN("[channels/" + platform + "] QR binding " + phase + ": " + state.value("error", std::string{}));
+    }
+    {
+        std::lock_guard<std::mutex> lock(bind_mu_);
+        bind_state_ = state;
+        bind_running_ = false;
+    }
+    publish_bind(state);
+}
+
+void ChannelHost::cancel_bind(const std::string& platform) {
+    std::lock_guard<std::mutex> lock(bind_mu_);
+    if (bind_cancel_ && bind_state_.value("platform", std::string{}) == platform) bind_cancel_->store(true);
+}
+
+nlohmann::json ChannelHost::bind_state(const std::string& platform) const {
+    std::lock_guard<std::mutex> lock(bind_mu_);
+    if (bind_state_.value("platform", std::string{}) == platform) return bind_state_;
+    return {{"platform", platform}, {"phase", "idle"}};
+}
+
+nlohmann::json ChannelHost::owner_link(const std::string& name) {
+    const auto* spec = find_platform_spec(name);
+    if (!spec) throw std::invalid_argument("未知的消息通道平台");
+    auto& runtime = platform(name);
+    const auto status = runtime.transport_status();
+    const auto ttl = std::chrono::duration_cast<std::chrono::seconds>(AccessControl::kOwnerTtl).count();
+    if (spec->owner_binding == OwnerBinding::Link) {
+        const auto username =
+            status.extra.is_object() ? status.extra.value("username", std::string{}) : std::string{};
+        if (status.state != im::LinkState::Connected || username.empty())
+            throw std::runtime_error(spec->label + " 尚未连接,连接成功后才能生成机主绑定链接");
+        const auto code = runtime.issue_owner_code();
+        return {{"link", "https://t.me/" + username + "?start=" + code}, {"expires_in_s", ttl}};
+    }
+    if (spec->owner_binding == OwnerBinding::Code) {
+        if (status.state != im::LinkState::Connected)
+            throw std::runtime_error(spec->label + " 尚未连接,连接成功后才能生成绑定码");
+        return {{"code", runtime.issue_owner_pin()}, {"expires_in_s", ttl}};
+    }
+    throw std::runtime_error(spec->label + " 在扫码时自动设定机主");
+}
+
+std::map<std::string, std::string> ChannelHost::bound_sessions() const {
+    std::map<std::string, std::string> out;
+    for (const auto& name : platform_names())
+        for (const auto& id : runtimes_.at(name)->bound_session_ids()) out[id] = name;
+    return out;
+}
+
+void ChannelHost::release_across(const std::string& session_id, const std::string& taker_key,
+                                 const std::string& label) {
+    for (const auto& name : platform_names()) runtimes_.at(name)->release_session(session_id, taker_key, label);
+}
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/host.hpp b/src/host/channels/core/host.hpp
new file mode 100644
index 000000000..f1769ec70
--- /dev/null
+++ b/src/host/channels/core/host.hpp
@@ -0,0 +1,78 @@
+#pragma once
+
+// 消息通道宿主(design D4 / D9 / D12):在 daemon 里托管各平台运行时(清单见 platforms.hpp),
+// 承接设置页的全部操作,运行扫码绑定流程(QQ、微信),并负责跨平台的会话绑定转移。
+// 每个平台的数据在 <root>/<platform>/ 下(root 通常是 ~/.acecode/channels)。
+
+#include "channels/core/host_services.hpp"
+#include "channels/core/platform_adapters.hpp"
+#include "channels/core/platforms.hpp"
+#include "utils/joining_thread.hpp"
+#include "utils/lifetime_token.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <atomic>
+#include <filesystem>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <vector>
+
+namespace acecode::channels::core {
+
+class ChannelHost {
+public:
+    ChannelHost(std::filesystem::path root, HostServices services);
+    ~ChannelHost();
+    ChannelHost(const ChannelHost&) = delete;
+    ChannelHost& operator=(const ChannelHost&) = delete;
+
+    void start();
+    void stop();
+
+    // {"platforms":[平台快照...], "binds":{"qq":{扫码状态}, "weixin":{...}}}
+    nlohmann::json snapshot() const;
+    bool has_platform(const std::string& name) const;
+    // 未知平台抛 std::invalid_argument。
+    PlatformRuntime& platform(const std::string& name);
+
+    // 扫码绑定(QQ、微信):同一时间只允许一个流程(重复发起抛 std::runtime_error,
+    // 不支持扫码的平台抛 std::invalid_argument);二维码刷新与结果经 broadcast("channels_bind")
+    // 推送,同时可用 bind_state() 查询。成功后保存凭据、设定机主(拿不到扫码人时打开 10 分钟窗口)
+    // 并开启该平台。
+    nlohmann::json start_bind(const std::string& platform);
+    void cancel_bind(const std::string& platform);
+    nlohmann::json bind_state(const std::string& platform) const;
+
+    // 机主绑定:Telegram 返回一次性链接 {"link","expires_in_s"};飞书、钉钉、Discord、LINE 返回
+    // 6 位绑定码 {"code","expires_in_s"},机主私聊机器人发送它即可。需要已连接且尚无机主。
+    nlohmann::json owner_link(const std::string& platform);
+
+    // 会话 id → 平台名;会话列表的 channel_bound 字段用它。
+    std::map<std::string, std::string> bound_sessions() const;
+
+private:
+    void release_across(const std::string& session_id, const std::string& taker_key, const std::string& label);
+    void publish_all();
+    void publish_bind(const nlohmann::json& state);
+    void run_bind_flow(const std::string& platform, const BindRunner& runner,
+                       const std::shared_ptr<std::atomic<bool>>& cancelled);
+    void finish_bind(const std::string& platform, const BindOutcome& outcome,
+                     const std::shared_ptr<std::atomic<bool>>& cancelled);
+
+    std::filesystem::path root_;
+    HostServices services_;
+    std::map<std::string, std::unique_ptr<PlatformRuntime>> runtimes_;
+
+    mutable std::mutex bind_mu_;
+    nlohmann::json bind_state_ = {{"phase", "idle"}};  // 最近一次扫码流程的状态(带 platform)
+    std::shared_ptr<std::atomic<bool>> bind_cancel_;
+    acecode::JoiningThread bind_thread_;
+    bool bind_running_ = false;
+    // 平台运行时与扫码线程经它回调宿主;最后声明,析构时最先撤销(此时 stop() 已停掉它们)。
+    LifetimeToken lifetime_;
+};
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/host_services.hpp b/src/host/channels/core/host_services.hpp
new file mode 100644
index 000000000..2732c845a
--- /dev/null
+++ b/src/host/channels/core/host_services.hpp
@@ -0,0 +1,65 @@
+#pragma once
+
+// 消息通道宿主的外部依赖:各平台的接入地址(测试指向本机假服务)、扫码流程参数、
+// 以及测试用的传输层参数调整钩子。真实运行时 daemon 只填会话依赖与广播。
+
+#include "channels/core/platform_runtime.hpp"
+#include "im/dingtalk/dingtalk_transport.hpp"
+#include "im/discord/discord_transport.hpp"
+#include "im/feishu/feishu_transport.hpp"
+#include "im/line/line_transport.hpp"
+#include "im/qqbot/qq_bind.hpp"
+#include "im/qqbot/qq_transport.hpp"
+#include "im/telegram/tg_transport.hpp"
+#include "im/weixin/weixin_login.hpp"
+#include "im/weixin/weixin_transport.hpp"
+
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <string>
+
+namespace acecode::channels::core {
+
+// 真实平台的接入地址;测试指向本机假服务。
+struct HostEndpoints {
+    std::string qq_api_base = im::qqbot::kApiBase;
+    std::string qq_token_url = im::qqbot::kTokenUrl;
+    std::string telegram_api_base = im::telegram::kApiBase;
+    // 微信:扫码登录用 weixin_api_base;登录后使用登录结果里的 base_url(为空时退回它)。
+    std::string weixin_api_base = im::weixin::kApiBase;
+    std::string weixin_cdn_base = im::weixin::kCdnBase;
+    std::string dingtalk_api_base = im::dingtalk::kApiBase;
+    std::string dingtalk_oapi_base = im::dingtalk::kOapiBase;
+    std::string discord_api_base = im::discord::kApiBase;
+    std::string feishu_base;  // 非空时覆盖按 domain(飞书 / Lark)选出的地址
+    std::string line_api_base = im::line::kApiBase;
+    std::string line_data_api_base = im::line::kDataApiBase;
+    bool use_proxy = true;
+};
+
+struct HostServices {
+    // 会话依赖;其中 release_session / on_bindings_changed / media_dir 由宿主填写。
+    ConversationDeps conversation;
+    Broadcast broadcast;
+    std::function<std::int64_t()> current_pid;
+    std::chrono::milliseconds standby_retry{std::chrono::seconds(5)};
+    HostEndpoints endpoints;
+    im::qqbot::BindOptions bind;
+    // 微信扫码登录参数;api_base / use_proxy 以 endpoints 为准。
+    im::weixin::LoginOptions weixin_login;
+    // 为空时按 endpoints 创建真实传输层 / 联网校验凭据。
+    TransportFactory make_transport;
+    CredentialValidator validate_credentials;
+    // 测试用:调整默认传输层的重试间隔等参数。
+    std::function<void(im::qqbot::QqTransportOptions&)> tune_qq;
+    std::function<void(im::telegram::TelegramTransportOptions&)> tune_telegram;
+    std::function<void(im::weixin::WeixinTransportOptions&)> tune_weixin;
+    std::function<void(im::dingtalk::DingTalkTransportOptions&)> tune_dingtalk;
+    std::function<void(im::discord::DiscordTransportOptions&)> tune_discord;
+    std::function<void(im::feishu::FeishuTransportOptions&)> tune_feishu;
+    // LINE 测试还要在这里换掉 cloudflared(tunnel.locate / launch)等。
+    std::function<void(im::line::LineTransportOptions&)> tune_line;
+};
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/line_webhook_server.cpp b/src/host/channels/core/line_webhook_server.cpp
new file mode 100644
index 000000000..5be142aed
--- /dev/null
+++ b/src/host/channels/core/line_webhook_server.cpp
@@ -0,0 +1,158 @@
+#include "channels/core/line_webhook_server.hpp"
+
+#include "utils/joining_thread.hpp"
+#include "utils/logger.hpp"
+
+#include <crow.h>
+
+#include <atomic>
+#include <chrono>
+#include <mutex>
+#include <string>
+
+namespace acecode::channels::core {
+namespace {
+
+// 路由与 LineWebhookServer 共享的处理函数槽。路由只捕获它的 shared_ptr,不捕获服务对象本身;
+// stop() 在服务线程全部退出后清空它。
+struct HandlerSlot {
+    std::mutex mu;
+    im::line::ListenerHandler handler;
+};
+
+crow::response dispatch(HandlerSlot& slot, const char* method, std::string path, const crow::request& req) {
+    im::line::ListenerHandler handler;
+    {
+        std::lock_guard<std::mutex> lock(slot.mu);
+        handler = slot.handler;
+    }
+    if (!handler) return crow::response(503);
+    im::line::ListenerRequest request;
+    request.method = method;
+    request.path = std::move(path);
+    request.body = req.body;  // 原始字节;签名按它计算
+    request.signature = req.get_header_value("X-Line-Signature");
+    im::line::ListenerReply reply;
+    try {
+        reply = handler(request);
+    } catch (const std::exception& e) {
+        LOG_WARN(std::string("[channels/line] webhook handler failed: ") + e.what());
+        reply = im::line::ListenerReply{};
+        reply.status = 500;
+        reply.body = "error";
+    }
+    crow::response res(reply.status);
+    res.set_header("Content-Type", reply.content_type);
+    for (const auto& [name, value] : reply.headers) res.set_header(name, value);
+    res.body = std::move(reply.body);
+    return res;
+}
+
+// exited 指向 Impl 的成员;Impl 在 join 服务线程之前不会销毁。
+void run_app(crow::SimpleApp* app, std::atomic<bool>* exited) {
+    try {
+        app->run();
+    } catch (const std::exception& e) {
+        LOG_WARN(std::string("[channels/line] webhook listener stopped: ") + e.what());
+    } catch (...) {
+        LOG_WARN("[channels/line] webhook listener stopped unexpectedly");
+    }
+    exited->store(true);
+}
+
+} // namespace
+
+struct LineWebhookServer::Impl {
+    std::mutex ops_mu;  // 串行化 start / stop
+    std::unique_ptr<crow::SimpleApp> app;
+    acecode::JoiningThread server;
+    std::shared_ptr<HandlerSlot> slot;
+    std::atomic<bool> exited{false};
+    std::atomic<std::uint16_t> port{0};
+
+    void stop_locked() {
+        if (app) app->stop();
+        if (server.joinable()) server.join();
+        if (slot) {
+            std::lock_guard<std::mutex> lock(slot->mu);
+            slot->handler = nullptr;
+        }
+        slot.reset();
+        app.reset();
+        port = 0;
+    }
+};
+
+LineWebhookServer::LineWebhookServer() : impl_(std::make_unique<Impl>()) {}
+
+LineWebhookServer::~LineWebhookServer() { stop(); }
+
+std::uint16_t LineWebhookServer::start(std::uint16_t port, im::line::ListenerHandler handler, std::string* error) {
+    std::lock_guard<std::mutex> lock(impl_->ops_mu);
+    impl_->stop_locked();
+    if (!handler) {
+        if (error) *error = "缺少回调处理函数";
+        return 0;
+    }
+    auto slot = std::make_shared<HandlerSlot>();
+    slot->handler = std::move(handler);
+    auto app = std::make_unique<crow::SimpleApp>();
+
+    CROW_ROUTE((*app), "/line/webhook").methods(crow::HTTPMethod::Post)([slot](const crow::request& req) {
+        return dispatch(*slot, "POST", im::line::kWebhookRoute, req);
+    });
+    CROW_ROUTE((*app), "/line/health").methods(crow::HTTPMethod::Get)([slot](const crow::request& req) {
+        return dispatch(*slot, "GET", im::line::kHealthRoute, req);
+    });
+    CROW_ROUTE((*app), "/line/media/<string>/<string>")
+        .methods(crow::HTTPMethod::Get)([slot](const crow::request& req, const std::string& token,
+                                               const std::string& name) {
+            return dispatch(*slot, "GET", std::string("/line/media/") + token + "/" + name, req);
+        });
+    CROW_CATCHALL_ROUTE((*app))([] { return crow::response(404); });
+
+    // 只监听回环地址;两个工作线程(LINE 会并发取图片与预览);signal_clear 避免 Crow 接管进程的 Ctrl+C / SIGTERM。
+    app->bindaddr("127.0.0.1").port(port).concurrency(3).signal_clear();
+    impl_->exited = false;
+    auto* raw = app.get();
+    impl_->server = acecode::JoiningThread(&run_app, raw, &impl_->exited);
+    const auto waited = raw->wait_for_server_start(std::chrono::seconds(5));
+    std::uint16_t bound = 0;
+    if (waited == std::cv_status::no_timeout && !impl_->exited.load() && raw->is_bound()) {
+        try {
+            bound = raw->port();
+        } catch (...) {
+            bound = 0;
+        }
+    }
+    if (bound == 0 || (port != 0 && bound != port)) {
+        raw->stop();
+        if (impl_->server.joinable()) impl_->server.join();
+        {
+            std::lock_guard<std::mutex> slot_lock(slot->mu);
+            slot->handler = nullptr;
+        }
+        if (error) {
+            *error = port != 0 ? "端口 " + std::to_string(port) + " 已被占用或无法监听" : std::string("无法监听本机端口");
+        }
+        LOG_WARN("[channels/line] webhook listener failed to start on 127.0.0.1:" + std::to_string(port));
+        return 0;
+    }
+    impl_->app = std::move(app);
+    impl_->slot = std::move(slot);
+    impl_->port = bound;
+    return bound;
+}
+
+void LineWebhookServer::stop() {
+    std::lock_guard<std::mutex> lock(impl_->ops_mu);
+    impl_->stop_locked();
+}
+
+std::uint16_t LineWebhookServer::port() const {
+    // 服务线程意外退出(端口被系统收回等)时视为未运行,传输层会重新监听。
+    if (impl_->exited.load()) return 0;
+    return impl_->port.load();
+}
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/line_webhook_server.hpp b/src/host/channels/core/line_webhook_server.hpp
new file mode 100644
index 000000000..b25e21876
--- /dev/null
+++ b/src/host/channels/core/line_webhook_server.hpp
@@ -0,0 +1,36 @@
+#pragma once
+
+// LINE 回调端口的 Crow 实现(im::line::WebhookListener)。
+//
+// 只监听 127.0.0.1(Cloudflare 隧道或用户的反向代理在本机转发进来),只注册三条路由:
+//   POST /line/webhook          → 原始请求体 + X-Line-Signature 交给传输层(校验签名、入队、立即回 200)
+//   GET  /line/health           → 公网自检
+//   GET  /line/media/<令牌>/<名> → 出站图片的临时链接
+// 其余一律 404,不加 CORS 头。它是独立的 Crow 应用,绝不复用 ACECode 主 Web 端口
+// (本机请求在主端口免 token,经隧道进来的请求也是本机地址)。
+//
+// 一个传输层实例独占一个 LineWebhookServer;stop() 之后可以再次 start()。
+
+#include "im/line/line_webhook.hpp"
+
+#include <memory>
+
+namespace acecode::channels::core {
+
+class LineWebhookServer final : public im::line::WebhookListener {
+public:
+    LineWebhookServer();
+    ~LineWebhookServer() override;
+    LineWebhookServer(const LineWebhookServer&) = delete;
+    LineWebhookServer& operator=(const LineWebhookServer&) = delete;
+
+    std::uint16_t start(std::uint16_t port, im::line::ListenerHandler handler, std::string* error) override;
+    void stop() override;
+    std::uint16_t port() const override;
+
+private:
+    struct Impl;
+    std::unique_ptr<Impl> impl_;
+};
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/platform_adapters.cpp b/src/host/channels/core/platform_adapters.cpp
new file mode 100644
index 000000000..3813d7da3
--- /dev/null
+++ b/src/host/channels/core/platform_adapters.cpp
@@ -0,0 +1,447 @@
+#include "channels/core/platform_adapters.hpp"
+
+#include "im/dingtalk/dingtalk_api.hpp"
+#include "channels/core/line_webhook_server.hpp"
+#include "im/discord/discord_api.hpp"
+#include "im/feishu/feishu_api.hpp"
+#include "im/line/line_api.hpp"
+#include "im/qqbot/qq_api.hpp"
+#include "im/telegram/tg_api.hpp"
+#include "im/weixin/weixin_api.hpp"
+#include "utils/logger.hpp"
+
+#include <mutex>
+
+namespace acecode::channels::core {
+namespace {
+
+std::string trimmed(const nlohmann::json& credentials, const char* key) {
+    if (!credentials.is_object() || !credentials.contains(key) || !credentials[key].is_string()) return {};
+    const auto value = credentials[key].get<std::string>();
+    const auto begin = value.find_first_not_of(" \t\r\n");
+    if (begin == std::string::npos) return {};
+    const auto end = value.find_last_not_of(" \t\r\n");
+    return value.substr(begin, end - begin + 1);
+}
+
+const char* qq_bind_phase(im::qqbot::BindPhase phase) {
+    switch (phase) {
+        case im::qqbot::BindPhase::WaitingScan: return "waiting";
+        case im::qqbot::BindPhase::Completed: return "completed";
+        case im::qqbot::BindPhase::Failed: return "failed";
+        case im::qqbot::BindPhase::Cancelled: return "cancelled";
+        case im::qqbot::BindPhase::TimedOut: return "timed_out";
+    }
+    return "failed";
+}
+
+std::shared_ptr<im::Transport> make_qq(const PlatformConfig& config, const HostServices& services) {
+    const auto& endpoints = services.endpoints;
+    im::qqbot::QqTransportOptions options;
+    options.api.app_id = trimmed(config.credentials, "app_id");
+    options.api.app_secret = trimmed(config.credentials, "app_secret");
+    options.api.api_base = endpoints.qq_api_base;
+    options.api.token_url = endpoints.qq_token_url;
+    options.api.use_proxy = endpoints.use_proxy;
+    if (services.tune_qq) services.tune_qq(options);
+    return std::make_shared<im::qqbot::QqTransport>(std::move(options));
+}
+
+std::shared_ptr<im::Transport> make_telegram(const PlatformConfig& config, ChannelStore& store,
+                                             const HostServices& services) {
+    im::telegram::TelegramTransportOptions options;
+    options.api.token = trimmed(config.credentials, "token");
+    options.api.api_base = services.endpoints.telegram_api_base;
+    options.api.use_proxy = services.endpoints.use_proxy;
+    options.initial_offset = store.cursor("telegram_offset");
+    options.on_offset = [&store](std::int64_t offset) {
+        try {
+            store.set_cursor("telegram_offset", offset);
+        } catch (const std::exception& e) {
+            LOG_WARN(std::string("[channels/telegram] save offset failed: ") + e.what());
+        }
+    };
+    if (services.tune_telegram) services.tune_telegram(options);
+    return std::make_shared<im::telegram::TelegramTransport>(std::move(options));
+}
+
+// 微信的轮询游标与每个联系人的 context_token 都存在通道的 values 里;换机器人时随账号状态一起清掉。
+constexpr const char* kWeixinCursor = "weixin_cursor";
+constexpr const char* kWeixinContextTokens = "weixin_context_tokens";
+
+std::shared_ptr<im::Transport> make_weixin(const PlatformConfig& config, ChannelStore& store,
+                                           const HostServices& services) {
+    const auto& endpoints = services.endpoints;
+    im::weixin::WeixinTransportOptions options;
+    options.api.token = trimmed(config.credentials, "bot_token");
+    options.api.base_url = trimmed(config.credentials, "base_url");
+    if (options.api.base_url.empty()) options.api.base_url = endpoints.weixin_api_base;
+    options.api.cdn_base = endpoints.weixin_cdn_base;
+    options.api.use_proxy = endpoints.use_proxy;
+    options.bot_id = trimmed(config.credentials, "bot_id");
+
+    const auto cursor = store.value(kWeixinCursor);
+    if (cursor.is_string()) options.initial_cursor = cursor.get<std::string>();
+    const auto tokens = store.value(kWeixinContextTokens);
+    if (tokens.is_object()) {
+        for (const auto& [peer, token] : tokens.items())
+            if (token.is_string()) options.initial_context_tokens[peer] = token.get<std::string>();
+    }
+    options.on_cursor = [&store](const std::string& value) {
+        try {
+            store.set_value(kWeixinCursor, value.empty() ? nlohmann::json() : nlohmann::json(value));
+        } catch (const std::exception& e) {
+            LOG_WARN(std::string("[channels/weixin] save cursor failed: ") + e.what());
+        }
+    };
+    // 读改写整个对象,多个发送 / 轮询线程同时回调时要串行。
+    auto tokens_mu = std::make_shared<std::mutex>();
+    options.on_context_token = [&store, tokens_mu](const std::string& peer, const std::string& token) {
+        try {
+            std::lock_guard<std::mutex> lock(*tokens_mu);
+            auto all = store.value(kWeixinContextTokens);
+            if (!all.is_object()) all = nlohmann::json::object();
+            if (token.empty()) all.erase(peer);
+            else all[peer] = token;
+            store.set_value(kWeixinContextTokens, all.empty() ? nlohmann::json() : all);
+        } catch (const std::exception& e) {
+            LOG_WARN(std::string("[channels/weixin] save context token failed: ") + e.what());
+        }
+    };
+    if (services.tune_weixin) services.tune_weixin(options);
+    return std::make_shared<im::weixin::WeixinTransport>(std::move(options));
+}
+
+im::dingtalk::ApiOptions dingtalk_api_options(const nlohmann::json& credentials, const HostServices& services) {
+    im::dingtalk::ApiOptions options;
+    options.client_id = trimmed(credentials, "client_id");
+    options.client_secret = trimmed(credentials, "client_secret");
+    options.robot_code = trimmed(credentials, "robot_code");
+    options.api_base = services.endpoints.dingtalk_api_base;
+    options.oapi_base = services.endpoints.dingtalk_oapi_base;
+    options.use_proxy = services.endpoints.use_proxy;
+    return options;
+}
+
+std::shared_ptr<im::Transport> make_dingtalk(const PlatformConfig& config, const HostServices& services) {
+    im::dingtalk::DingTalkTransportOptions options;
+    options.api = dingtalk_api_options(config.credentials, services);
+    if (services.tune_dingtalk) services.tune_dingtalk(options);
+    return std::make_shared<im::dingtalk::DingTalkTransport>(std::move(options));
+}
+
+im::feishu::ApiOptions feishu_api_options(const nlohmann::json& credentials, const HostServices& services) {
+    im::feishu::ApiOptions options;
+    options.app_id = trimmed(credentials, "app_id");
+    options.app_secret = trimmed(credentials, "app_secret");
+    options.base = services.endpoints.feishu_base.empty() ? im::feishu::base_for_domain(trimmed(credentials, "domain"))
+                                                          : services.endpoints.feishu_base;
+    options.use_proxy = services.endpoints.use_proxy;
+    return options;
+}
+
+std::shared_ptr<im::Transport> make_feishu(const PlatformConfig& config, const HostServices& services) {
+    im::feishu::FeishuTransportOptions options;
+    options.api = feishu_api_options(config.credentials, services);
+    if (services.tune_feishu) services.tune_feishu(options);
+    return std::make_shared<im::feishu::FeishuTransport>(std::move(options));
+}
+
+im::line::ApiOptions line_api_options(const nlohmann::json& credentials, const HostServices& services) {
+    im::line::ApiOptions options;
+    options.channel_id = trimmed(credentials, "channel_id");
+    options.channel_secret = trimmed(credentials, "channel_secret");
+    options.access_token = trimmed(credentials, "access_token");
+    options.api_base = services.endpoints.line_api_base;
+    options.data_api_base = services.endpoints.line_data_api_base;
+    options.use_proxy = services.endpoints.use_proxy;
+    return options;
+}
+
+// LINE 回调端口:第一次由系统分配,之后沿用(用户自己的反向代理指向它)。
+constexpr const char* kLineListenPort = "line_listen_port";
+
+std::shared_ptr<im::Transport> make_line(const PlatformConfig& config, ChannelStore& store,
+                                         const HostServices& services) {
+    im::line::LineTransportOptions options;
+    options.api = line_api_options(config.credentials, services);
+    options.public_url = trimmed(config.credentials, "public_url");
+    const auto port = store.cursor(kLineListenPort);
+    if (port > 0 && port <= 65535) options.listen_port = static_cast<std::uint16_t>(port);
+    options.on_listen_port = [&store](std::uint16_t value) {
+        try {
+            store.set_cursor(kLineListenPort, value);
+        } catch (const std::exception& e) {
+            LOG_WARN(std::string("[channels/line] save listen port failed: ") + e.what());
+        }
+    };
+    // 独立的 Crow 应用,只监听 127.0.0.1,绝不复用 daemon 的主 Web 端口。
+    options.listener = std::make_shared<LineWebhookServer>();
+    if (services.tune_line) services.tune_line(options);
+    return std::make_shared<im::line::LineTransport>(std::move(options));
+}
+
+// Discord 的 24 小时登录计数要跨重启保留(超额会被平台重置 token)。
+constexpr const char* kDiscordIdentifyWindow = "discord_identify_window_ms";
+constexpr const char* kDiscordIdentifyCount = "discord_identify_count";
+
+std::shared_ptr<im::Transport> make_discord(const PlatformConfig& config, ChannelStore& store,
+                                            const HostServices& services) {
+    im::discord::DiscordTransportOptions options;
+    options.api.token = trimmed(config.credentials, "token");
+    options.api.api_base = services.endpoints.discord_api_base;
+    options.api.use_proxy = services.endpoints.use_proxy;
+    options.identify_window_start_ms = store.cursor(kDiscordIdentifyWindow);
+    options.identify_count = store.cursor(kDiscordIdentifyCount);
+    options.on_identify_ledger = [&store](std::int64_t window_start_ms, std::int64_t count) {
+        try {
+            store.set_cursor(kDiscordIdentifyWindow, window_start_ms);
+            store.set_cursor(kDiscordIdentifyCount, count);
+        } catch (const std::exception& e) {
+            LOG_WARN(std::string("[channels/discord] save identify ledger failed: ") + e.what());
+        }
+    };
+    if (services.tune_discord) services.tune_discord(options);
+    return std::make_shared<im::discord::DiscordTransport>(std::move(options));
+}
+
+nlohmann::json validate_qq(const nlohmann::json& credentials, const HostServices& services, std::string* error) {
+    im::qqbot::ApiOptions options;
+    options.app_id = trimmed(credentials, "app_id");
+    options.app_secret = trimmed(credentials, "app_secret");
+    if (options.app_id.empty() || options.app_secret.empty()) {
+        if (error) *error = "请填写 AppID 和 AppSecret";
+        return nullptr;
+    }
+    options.api_base = services.endpoints.qq_api_base;
+    options.token_url = services.endpoints.qq_token_url;
+    options.use_proxy = services.endpoints.use_proxy;
+    im::qqbot::Api api(options);
+    std::string reason;
+    if (!api.verify(&reason)) {
+        if (error) *error = reason.empty() ? std::string("凭据无效") : reason;
+        return nullptr;
+    }
+    return {{"app_id", options.app_id}, {"app_secret", options.app_secret}};
+}
+
+nlohmann::json validate_telegram(const nlohmann::json& credentials, const HostServices& services,
+                                 std::string* error) {
+    const auto token = trimmed(credentials, "token");
+    if (token.find(':') == std::string::npos) {
+        if (error) *error = "Token 格式不对,应形如 123456:ABC-DEF…(在 @BotFather 中获取)";
+        return nullptr;
+    }
+    im::telegram::ApiOptions options;
+    options.token = token;
+    options.api_base = services.endpoints.telegram_api_base;
+    options.use_proxy = services.endpoints.use_proxy;
+    const auto result = im::telegram::Api(options).call("getMe", nlohmann::json::object(), std::chrono::seconds(15));
+    if (!result.ok) {
+        if (error) {
+            if (result.status == 401 || result.status == 404 || result.error_code == 401)
+                *error = "Token 无效,请在 @BotFather 中确认后重试";
+            else if (result.status == 0)
+                *error = "无法连接 Telegram" + (result.description.empty() ? std::string{} : ":" + result.description);
+            else
+                *error = result.description.empty() ? std::string("Token 校验失败") : result.description;
+        }
+        return nullptr;
+    }
+    return {{"token", token}};
+}
+
+// 微信凭据只来自扫码登录;这里只检查齐全,不联网(登录失效由传输层报告)。
+nlohmann::json validate_weixin(const nlohmann::json& credentials, std::string* error) {
+    const auto token = trimmed(credentials, "bot_token");
+    const auto bot_id = trimmed(credentials, "bot_id");
+    if (token.empty() || bot_id.empty()) {
+        if (error) *error = "请在设置页扫码登录微信";
+        return nullptr;
+    }
+    nlohmann::json saved{{"bot_token", token}, {"bot_id", bot_id}};
+    const auto base_url = trimmed(credentials, "base_url");
+    if (!base_url.empty()) saved["base_url"] = base_url;
+    return saved;
+}
+
+// 取一次 access token 并试注册一次 Stream 连接(票据随即丢弃),能区分凭据错误与应用未发布等。
+nlohmann::json validate_dingtalk(const nlohmann::json& credentials, const HostServices& services,
+                                 std::string* error) {
+    auto options = dingtalk_api_options(credentials, services);
+    if (options.client_id.empty() || options.client_secret.empty()) {
+        if (error) *error = "请填写 Client ID 和 Client Secret";
+        return nullptr;
+    }
+    const auto result = im::dingtalk::Api(options).verify();
+    if (!result.ok) {
+        if (error) *error = result.error.empty() ? std::string("凭据校验失败") : result.error;
+        return nullptr;
+    }
+    nlohmann::json saved{{"client_id", options.client_id}, {"client_secret", options.client_secret}};
+    if (!options.robot_code.empty()) saved["robot_code"] = options.robot_code;
+    return saved;
+}
+
+// 换 tenant 令牌并读机器人信息。机器人未就绪(还没发布版本)不算失败:飞书要求长连接在线
+// 才能保存订阅方式,发布往往在连上之后,连接步骤的清单会提示。
+nlohmann::json validate_feishu(const nlohmann::json& credentials, const HostServices& services,
+                               std::string* error) {
+    const auto options = feishu_api_options(credentials, services);
+    if (options.app_id.empty() || options.app_secret.empty()) {
+        if (error) *error = "请填写 App ID 和 App Secret";
+        return nullptr;
+    }
+    const auto result = im::feishu::verify_credentials(options);
+    if (!result.ok) {
+        if (error) *error = result.error.empty() ? std::string("凭据校验失败") : result.error;
+        return nullptr;
+    }
+    nlohmann::json saved{{"app_id", options.app_id}, {"app_secret", options.app_secret}};
+    const auto domain = trimmed(credentials, "domain");
+    if (!domain.empty()) saved["domain"] = domain;
+    return saved;
+}
+
+nlohmann::json validate_line(const nlohmann::json& credentials, const HostServices& services, std::string* error) {
+    const auto options = line_api_options(credentials, services);
+    if (options.channel_id.empty() || options.channel_secret.empty()) {
+        if (error) *error = "请填写 Channel ID 和 Channel secret";
+        return nullptr;
+    }
+    const auto public_url = trimmed(credentials, "public_url");
+    if (!public_url.empty() && public_url.rfind("https://", 0) != 0) {
+        if (error) *error = "公网地址必须以 https:// 开头(LINE 只回调 HTTPS)";
+        return nullptr;
+    }
+    const auto result = im::line::validate_credentials(options);
+    if (!result.ok) {
+        if (error) *error = result.error.empty() ? std::string("凭据校验失败") : result.error;
+        return nullptr;
+    }
+    nlohmann::json saved{{"channel_id", options.channel_id},
+                         {"channel_secret", options.channel_secret},
+                         {"bot_id", result.bot.user_id}};
+    if (!options.access_token.empty()) saved["access_token"] = options.access_token;
+    if (!public_url.empty()) saved["public_url"] = public_url;
+    return saved;
+}
+
+nlohmann::json validate_discord(const nlohmann::json& credentials, const HostServices& services,
+                                std::string* error) {
+    im::discord::ApiOptions options;
+    options.token = trimmed(credentials, "token");
+    if (options.token.rfind("Bot ", 0) == 0) options.token = options.token.substr(4);
+    if (options.token.empty()) {
+        if (error) *error = "请填写 Bot Token";
+        return nullptr;
+    }
+    options.api_base = services.endpoints.discord_api_base;
+    options.use_proxy = services.endpoints.use_proxy;
+    const auto result = im::discord::validate_credentials(options);
+    if (!result.ok) {
+        if (error) *error = result.error.empty() ? std::string("Token 校验失败") : result.error;
+        return nullptr;
+    }
+    // 关着 Message Content Intent 时网关会以 4014 拒绝连接,保存前就说清楚。
+    if (result.profile.message_content == im::discord::IntentState::Disabled) {
+        if (error) *error = "请先在 Discord 开发者后台的 Bot 页打开 Message Content Intent,保存后再连接";
+        return nullptr;
+    }
+    nlohmann::json saved{{"token", options.token}, {"bot_id", result.profile.user_id}};
+    if (!result.profile.application_id.empty()) saved["application_id"] = result.profile.application_id;
+    return saved;
+}
+
+const char* weixin_bind_phase(im::weixin::LoginPhase phase) {
+    switch (phase) {
+        case im::weixin::LoginPhase::WaitingScan:
+        case im::weixin::LoginPhase::Scanned: return "waiting";
+        case im::weixin::LoginPhase::Completed: return "completed";
+        case im::weixin::LoginPhase::Failed: return "failed";
+        case im::weixin::LoginPhase::Cancelled: return "cancelled";
+        case im::weixin::LoginPhase::TimedOut: return "timed_out";
+    }
+    return "failed";
+}
+
+BindRunner weixin_bind_runner(const HostServices& services) {
+    auto options = services.weixin_login;
+    options.api_base = services.endpoints.weixin_api_base;
+    options.use_proxy = services.endpoints.use_proxy;
+    return [options](const std::atomic<bool>& cancelled, const std::function<void(const BindProgress&)>& progress) {
+        const auto result = im::weixin::run_login(options, cancelled,
+                                                  [&progress](const im::weixin::LoginProgress& update) {
+            BindProgress step;
+            step.qr_url = update.qr_url;
+            step.refreshes = update.refreshes;
+            progress(step);
+        });
+        BindOutcome outcome;
+        outcome.phase = weixin_bind_phase(result.phase);
+        outcome.error = result.error;
+        if (result.phase == im::weixin::LoginPhase::Completed) {
+            outcome.credentials = {{"bot_token", result.bot_token}, {"bot_id", result.bot_id}};
+            if (!result.base_url.empty()) outcome.credentials["base_url"] = result.base_url;
+            outcome.account = result.bot_id;
+            if (!result.user_id.empty()) outcome.owner = "user:" + result.user_id;
+        }
+        return outcome;
+    };
+}
+
+BindRunner qq_bind_runner(const HostServices& services) {
+    return [options = services.bind](const std::atomic<bool>& cancelled,
+                                     const std::function<void(const BindProgress&)>& progress) {
+        const auto result = im::qqbot::run_bind(options, cancelled, [&progress](const im::qqbot::BindUpdate& update) {
+            BindProgress step;
+            step.qr_url = update.qr_url;
+            step.refreshes = update.refreshes;
+            progress(step);
+        });
+        BindOutcome outcome;
+        outcome.phase = qq_bind_phase(result.phase);
+        outcome.error = result.error;
+        if (result.phase == im::qqbot::BindPhase::Completed) {
+            outcome.credentials = {{"app_id", result.app_id}, {"app_secret", result.app_secret}};
+            outcome.account = result.app_id;
+            if (!result.user_openid.empty()) outcome.owner = "user:" + result.user_openid;
+        }
+        return outcome;
+    };
+}
+
+} // namespace
+
+std::shared_ptr<im::Transport> make_platform_transport(const std::string& platform, const PlatformConfig& config,
+                                                       ChannelStore& store, const HostServices& services) {
+    if (platform == "qq") return make_qq(config, services);
+    if (platform == "weixin") return make_weixin(config, store, services);
+    if (platform == "feishu") return make_feishu(config, services);
+    if (platform == "dingtalk") return make_dingtalk(config, services);
+    if (platform == "telegram") return make_telegram(config, store, services);
+    if (platform == "discord") return make_discord(config, store, services);
+    if (platform == "line") return make_line(config, store, services);
+    return nullptr;
+}
+
+nlohmann::json validate_platform_credentials(const std::string& platform, const nlohmann::json& credentials,
+                                             const HostServices& services, std::string* error) {
+    if (platform == "qq") return validate_qq(credentials, services, error);
+    if (platform == "weixin") return validate_weixin(credentials, error);
+    if (platform == "feishu") return validate_feishu(credentials, services, error);
+    if (platform == "dingtalk") return validate_dingtalk(credentials, services, error);
+    if (platform == "telegram") return validate_telegram(credentials, services, error);
+    if (platform == "discord") return validate_discord(credentials, services, error);
+    if (platform == "line") return validate_line(credentials, services, error);
+    if (error) *error = "未知的消息通道平台";
+    return nullptr;
+}
+
+BindRunner make_bind_runner(const std::string& platform, const HostServices& services) {
+    if (platform == "qq") return qq_bind_runner(services);
+    if (platform == "weixin") return weixin_bind_runner(services);
+    return {};
+}
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/platform_adapters.hpp b/src/host/channels/core/platform_adapters.hpp
new file mode 100644
index 000000000..5393cc2d9
--- /dev/null
+++ b/src/host/channels/core/platform_adapters.hpp
@@ -0,0 +1,46 @@
+#pragma once
+
+// 按平台名创建传输层、联网校验凭据、运行扫码绑定。平台清单与凭据字段见 platforms.hpp;
+// 这里是唯一需要认识各平台传输层类型的地方。
+
+#include "channels/core/host_services.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <atomic>
+#include <functional>
+#include <memory>
+#include <string>
+
+namespace acecode::channels::core {
+
+// 未知平台返回 nullptr。
+std::shared_ptr<im::Transport> make_platform_transport(const std::string& platform, const PlatformConfig& config,
+                                                       ChannelStore& store, const HostServices& services);
+
+// 成功返回要保存的凭据(去空白,可能补上机器人 id 等派生字段);失败返回 null 并写 error(不含凭据)。
+nlohmann::json validate_platform_credentials(const std::string& platform, const nlohmann::json& credentials,
+                                             const HostServices& services, std::string* error);
+
+// 扫码绑定(QQ、微信):进度里只有二维码内容与刷新次数;结果给出要保存的凭据与扫码人。
+struct BindProgress {
+    std::string qr_url;
+    int refreshes = 0;
+};
+
+struct BindOutcome {
+    std::string phase = "failed";  // completed / failed / cancelled / timed_out
+    nlohmann::json credentials = nlohmann::json::object();
+    std::string owner;        // 扫码人的 principal;空 = 平台没给出
+    std::string owner_name;
+    std::string account;      // 机器人账号 id,只用于日志与界面
+    std::string error;        // 失败原因(不含凭据)
+};
+
+using BindRunner = std::function<BindOutcome(const std::atomic<bool>& cancelled,
+                                             const std::function<void(const BindProgress&)>& progress)>;
+
+// 没有扫码流程的平台返回空函数。
+BindRunner make_bind_runner(const std::string& platform, const HostServices& services);
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/platform_runtime.cpp b/src/host/channels/core/platform_runtime.cpp
new file mode 100644
index 000000000..f8e214193
--- /dev/null
+++ b/src/host/channels/core/platform_runtime.cpp
@@ -0,0 +1,517 @@
+#include "platform_runtime.hpp"
+
+#include "channels/core/platforms.hpp"
+#include "channels/core/state_log.hpp"
+#include "channels/owner_lock.hpp"
+#include "im/redact.hpp"
+#include "utils/atomic_file.hpp"
+#include "utils/logger.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <algorithm>
+#include <fstream>
+#include <stdexcept>
+
+namespace acecode::channels::core {
+namespace {
+
+std::int64_t read_holder_pid(const std::filesystem::path& directory) {
+    try {
+        std::ifstream in(directory / "owner.json", std::ios::binary);
+        if (!in) return 0;
+        const auto json = nlohmann::json::parse(in);
+        return json.value("pid", std::int64_t{0});
+    } catch (...) {
+        return 0;
+    }
+}
+
+} // namespace
+
+struct PlatformRuntime::LockHandle {
+    OwnerLock lock;
+};
+
+PlatformRuntime::PlatformRuntime(std::string platform, std::filesystem::path directory, RuntimeServices services)
+    : platform_(std::move(platform)), directory_(std::move(directory)), services_(std::move(services)),
+      store_(directory_) {
+    auto deps = services_.conversation;
+    if (deps.media_dir.empty()) deps.media_dir = directory_ / "media";
+    conversations_ = std::make_unique<Conversations>(platform_, store_, access_, slot_, std::move(deps));
+}
+
+PlatformRuntime::~PlatformRuntime() { stop(); }
+
+bool PlatformRuntime::configured(const PlatformConfig& config) const {
+    const auto* spec = find_platform_spec(platform_);
+    return spec && credentials_complete(*spec, config.credentials);
+}
+
+// 绑定地址里的账号(平台描述表定义取哪个凭据字段;Telegram 取 token 冒号前一段)。
+std::string PlatformRuntime::account_of(const PlatformConfig& config) const {
+    const auto* spec = find_platform_spec(platform_);
+    return spec ? core::account_of(*spec, config.credentials) : std::string{};
+}
+
+void PlatformRuntime::forget_account_locked(const std::string& account) {
+    for (const auto& record : store_.bindings())
+        if (record.address.account == account) store_.erase_binding(record.address.key());
+    store_.clear_transport_state();  // 游标、上下文令牌都属于旧机器人
+    const auto* spec = find_platform_spec(platform_);
+    if (spec && spec->principals_scoped_to_account) {
+        store_.update_config([](PlatformConfig& config) {
+            config.owner.clear();
+            config.access.clear();
+        });
+    }
+}
+
+void PlatformRuntime::ensure_loaded() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    if (!running_) throw std::runtime_error("消息通道尚未启动");
+    if (!load_error_.empty()) throw std::runtime_error(load_error_);
+}
+
+void PlatformRuntime::start() {
+    {
+        std::lock_guard<std::mutex> ops(ops_mu_);
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            if (running_) return;
+            running_ = true;
+            load_error_.clear();
+        }
+        stopping_ = false;
+        try {
+            store_.load();
+        } catch (const std::exception& e) {
+            std::lock_guard<std::mutex> lock(mu_);
+            load_error_ = e.what();
+            LOG_ERROR("[channels/" + platform_ + "] " + load_error_);
+        }
+        worker_ = acecode::JoiningThread(&PlatformRuntime::worker_loop, this);
+        bool load_failed;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            load_failed = !load_error_.empty();
+        }
+        const auto config = store_.config();
+        if (!load_failed && config.enabled && configured(config)) {
+            try {
+                connect_locked();
+            } catch (const std::exception& e) {
+                LOG_ERROR("[channels/" + platform_ + "] connect failed: " + e.what());
+            }
+        }
+    }
+    publish_state();
+}
+
+void PlatformRuntime::stop() {
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (!running_) return;
+    }
+    stopping_ = true;
+    queue_cv_.notify_all();
+    if (worker_.joinable()) worker_.join();
+    std::lock_guard<std::mutex> ops(ops_mu_);
+    disconnect_locked();
+    std::lock_guard<std::mutex> lock(mu_);
+    running_ = false;
+}
+
+void PlatformRuntime::connect_locked() {
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (transport_) return;
+    }
+    if (!owns_lock_) {
+        std::error_code ec;
+        std::filesystem::create_directories(directory_, ec);
+        if (!lock_) lock_ = std::make_unique<LockHandle>();
+        if (!lock_->lock.acquire(directory_ / "owner.lock")) {
+            std::lock_guard<std::mutex> lock(mu_);
+            standby_ = true;
+            holder_pid_ = read_holder_pid(directory_);
+            return;
+        }
+        owns_lock_ = true;
+        const std::int64_t pid = services_.current_pid ? services_.current_pid() : 0;
+        atomic_write_file(path_to_utf8(directory_ / "owner.json"), nlohmann::json{{"pid", pid}}.dump(), true);
+    }
+    const auto config = store_.config();
+    auto transport = services_.make_transport ? services_.make_transport(platform_, config, store_) : nullptr;
+    if (!transport) throw std::runtime_error("无法创建通道连接");
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        standby_ = false;
+        holder_pid_ = 0;
+        transport_ = transport;
+    }
+    slot_->set(transport);
+    std::weak_ptr<im::Transport> weak = transport;
+    im::TransportCallbacks callbacks;
+    callbacks.on_inbound = [ref = lifetime_.ref(*this)](im::Inbound inbound) {
+        ref.with([&inbound](PlatformRuntime& runtime) { runtime.on_inbound(std::move(inbound)); });
+    };
+    callbacks.on_status = [ref = lifetime_.ref(*this), weak](const im::TransportStatus&) {
+        ref.with([&weak](PlatformRuntime& runtime) { runtime.on_transport_status(weak); });
+    };
+    transport->start(std::move(callbacks));
+    {
+        std::lock_guard<std::mutex> lock(queue_mu_);
+        restore_pending_ = true;
+    }
+    queue_cv_.notify_all();
+}
+
+void PlatformRuntime::on_transport_status(const std::weak_ptr<im::Transport>& source) {
+    {
+        const auto current = source.lock();
+        std::lock_guard<std::mutex> lock(mu_);
+        if (!current || current != transport_) return;
+    }
+    publish_state();
+}
+
+void PlatformRuntime::disconnect_locked() {
+    std::shared_ptr<im::Transport> transport;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        transport = std::move(transport_);
+        transport_.reset();
+        standby_ = false;
+        holder_pid_ = 0;
+    }
+    slot_->set(nullptr);
+    if (transport) transport->stop();  // 不持 mu_:传输层线程的回调需要它
+    {
+        std::lock_guard<std::mutex> lock(queue_mu_);
+        queue_.clear();
+        restore_pending_ = false;
+    }
+    {
+        std::lock_guard<std::mutex> process(process_mu_);
+        conversations_->shutdown();
+    }
+    if (owns_lock_) {
+        std::error_code ec;
+        std::filesystem::remove(directory_ / "owner.json", ec);
+        lock_->lock.release();
+        owns_lock_ = false;
+    }
+}
+
+void PlatformRuntime::on_inbound(im::Inbound inbound) {
+    {
+        std::lock_guard<std::mutex> lock(queue_mu_);
+        if (queue_.size() >= kMaxQueue) {
+            LOG_WARN("[channels/" + platform_ + "] inbound queue full, dropping message");
+            return;
+        }
+        queue_.push_back(std::move(inbound));
+    }
+    queue_cv_.notify_all();
+}
+
+void PlatformRuntime::worker_loop() {
+    while (true) {
+        std::unique_lock<std::mutex> lock(queue_mu_);
+        queue_cv_.wait_for(lock, services_.standby_retry,
+                           [this] { return stopping_.load() || !queue_.empty() || restore_pending_; });
+        if (stopping_) break;
+        if (restore_pending_) {
+            restore_pending_ = false;
+            lock.unlock();
+            std::lock_guard<std::mutex> process(process_mu_);
+            if (slot_->get()) conversations_->restore();
+            continue;
+        }
+        if (queue_.empty()) {
+            lock.unlock();
+            try_takeover();
+            continue;
+        }
+        auto inbound = std::move(queue_.front());
+        queue_.pop_front();
+        lock.unlock();
+        HandleOutcome outcome;
+        {
+            std::lock_guard<std::mutex> process(process_mu_);
+            if (!slot_->get()) continue;  // 处理前已被关闭
+            try {
+                outcome = conversations_->handle(inbound);
+            } catch (const std::exception& e) {
+                LOG_ERROR("[channels/" + platform_ + "] inbound failed: " + e.what());
+                continue;
+            }
+        }
+        if (outcome.pending_created && services_.broadcast) {
+            const auto& request = *outcome.pending_created;
+            services_.broadcast("channels_request", {{"platform", platform_},
+                                                     {"id", request.id},
+                                                     {"kind", request.kind},
+                                                     {"name", request.name},
+                                                     {"label", Conversations::label_for(request.address)}});
+        }
+        if (outcome.pending_created || outcome.owner_claimed) publish_state();
+    }
+}
+
+// 待命时由工作线程空闲轮询:持有者退出后接管连接。
+void PlatformRuntime::try_takeover() {
+    std::unique_lock<std::mutex> ops(ops_mu_, std::try_to_lock);
+    if (!ops) return;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (!standby_) return;
+    }
+    if (!store_.config().enabled) return;
+    bool connected = false;
+    try {
+        connect_locked();
+        std::lock_guard<std::mutex> lock(mu_);
+        connected = transport_ != nullptr;
+    } catch (const std::exception& e) {
+        LOG_ERROR("[channels/" + platform_ + "] takeover failed: " + e.what());
+    }
+    ops.unlock();
+    if (connected) publish_state();
+}
+
+void PlatformRuntime::set_enabled(bool enabled) {
+    {
+        std::lock_guard<std::mutex> ops(ops_mu_);
+        ensure_loaded();
+        if (enabled) {
+            if (!configured(store_.config())) throw std::runtime_error("请先完成配置");
+            store_.update_config([](PlatformConfig& config) { config.enabled = true; });
+            // 鉴权失败等致命错误后已停止重试:再次打开开关即重新连接。
+            const auto current = slot_->get();
+            if (current && current->status().retry_stopped) disconnect_locked();
+            connect_locked();
+        } else {
+            store_.update_config([](PlatformConfig& config) { config.enabled = false; });
+            disconnect_locked();
+        }
+    }
+    publish_state();
+}
+
+void PlatformRuntime::set_credentials(const nlohmann::json& credentials, bool validate) {
+    {
+        std::lock_guard<std::mutex> ops(ops_mu_);
+        ensure_loaded();
+        const auto previous = store_.config();
+        nlohmann::json merged = previous.credentials.is_object() ? previous.credentials : nlohmann::json::object();
+        if (credentials.is_object()) {
+            const auto* spec = find_platform_spec(platform_);
+            for (const auto& [key, value] : credentials.items()) {
+                if (!value.is_string()) continue;
+                if (!value.get<std::string>().empty()) {
+                    merged[key] = value;
+                    continue;
+                }
+                // 空串:可选字段表示清除(如 LINE 的公网地址改回自动隧道),必填字段沿用已保存的值。
+                if (!spec) continue;
+                for (const auto& field : spec->fields)
+                    if (field.key == key && !field.required) merged.erase(key);
+            }
+        }
+        nlohmann::json normalized = merged;
+        if (validate) {
+            std::string error;
+            normalized = services_.validate_credentials
+                ? services_.validate_credentials(platform_, merged, &error)
+                : nlohmann::json(nullptr);
+            if (!normalized.is_object()) throw std::runtime_error(error.empty() ? "凭据校验失败" : error);
+            // 校验只规整它认识的字段;用户填写的其它可选设置(飞书域名、LINE 公网地址…)原样保留。
+            if (const auto* spec = find_platform_spec(platform_)) {
+                for (const auto& field : spec->fields)
+                    if (field.user_input && !normalized.contains(field.key) && merged.contains(field.key))
+                        normalized[field.key] = merged[field.key];
+            }
+        }
+        PlatformConfig next = previous;
+        next.credentials = normalized;
+        if (!configured(next)) throw std::runtime_error("凭据不完整");
+        disconnect_locked();
+        store_.update_config([&normalized](PlatformConfig& config) { config.credentials = normalized; });
+        const auto old_account = account_of(previous);
+        if (!old_account.empty() && old_account != account_of(next)) forget_account_locked(old_account);
+        if (store_.config().enabled) connect_locked();  // 按开关状态用新凭据连接
+    }
+    publish_state();
+}
+
+void PlatformRuntime::approve(const std::string& request_id, bool approve) {
+    ensure_loaded();
+    const auto request = access_.take(request_id, AccessControl::Clock::now());
+    if (!request) throw std::runtime_error("该请求已过期或不存在");
+    if (approve) {
+        store_.update_config([&request](PlatformConfig& config) {
+            if (!config.has_access(request->principal))
+                config.access.push_back({request->principal, request->name, now_wall_ms()});
+            if (request->kind == "user" && config.owner.empty()) config.owner = request->principal;
+        });
+    }
+    publish_state();
+}
+
+void PlatformRuntime::revoke(const std::string& principal) {
+    ensure_loaded();
+    store_.update_config([&principal](PlatformConfig& config) {
+        config.access.erase(std::remove_if(config.access.begin(), config.access.end(),
+                                           [&principal](const AccessEntry& entry) { return entry.principal == principal; }),
+                            config.access.end());
+        if (config.owner == principal) config.owner.clear();
+    });
+    access_.drop_principal(principal);
+    conversations_->abort_principal(principal);
+    publish_state();
+}
+
+std::string PlatformRuntime::issue_owner_code() {
+    ensure_loaded();
+    if (!store_.config().owner.empty())
+        throw std::runtime_error("已经有机主了;如需更换,先在授权名单里移除当前机主");
+    const auto code = access_.issue_owner_code(AccessControl::Clock::now());
+    if (code.empty()) throw std::runtime_error("无法生成绑定码");
+    return code;
+}
+
+std::string PlatformRuntime::issue_owner_pin() {
+    ensure_loaded();
+    if (!store_.config().owner.empty())
+        throw std::runtime_error("已经有机主了;如需更换,先在授权名单里移除当前机主");
+    const auto code = access_.issue_owner_pin(AccessControl::Clock::now());
+    if (code.empty()) throw std::runtime_error("无法生成绑定码");
+    return code;
+}
+
+void PlatformRuntime::open_owner_window() {
+    access_.open_owner_window(AccessControl::Clock::now());
+    publish_state();
+}
+
+void PlatformRuntime::set_owner(const std::string& principal, const std::string& name) {
+    ensure_loaded();
+    store_.update_config([&principal, &name](PlatformConfig& config) {
+        config.owner = principal;
+        if (!config.has_access(principal)) config.access.push_back({principal, name, now_wall_ms()});
+    });
+    publish_state();
+}
+
+nlohmann::json PlatformRuntime::action(const std::string& name, const nlohmann::json& args) {
+    const auto transport = slot_->get();
+    if (!transport) throw std::runtime_error("通道未连接");
+    auto result = transport->action(name, args);
+    publish_state();
+    return result;
+}
+
+im::TransportStatus PlatformRuntime::transport_status() const {
+    const auto transport = slot_->get();
+    return transport ? transport->status() : im::TransportStatus{};
+}
+
+bool PlatformRuntime::release_session(const std::string& session_id, const std::string& except_key,
+                                      const std::string& label) {
+    return conversations_->release_session(session_id, except_key, label);
+}
+
+std::vector<std::string> PlatformRuntime::bound_session_ids() const { return conversations_->bound_session_ids(); }
+
+void PlatformRuntime::publish_state() {
+    nlohmann::json state;
+    {
+        // 快照在 log_mu_ 下取:并发的两次发布按先后比较,日志不会把状态写倒。
+        // 调用方不持 mu_ 与传输层的锁,这里再取 mu_ 不会互锁。
+        std::lock_guard<std::mutex> lock(log_mu_);
+        state = snapshot();
+        for (const auto& line : describe_state_changes(logged_state_, state))
+            Logger::instance().log(line.level, __FILE__, __LINE__, "[channels/" + platform_ + "] " + line.text);
+        logged_state_ = state;
+    }
+    if (services_.broadcast) services_.broadcast("channels_state", state);
+}
+
+nlohmann::json PlatformRuntime::snapshot() const {
+    const auto config = store_.config();
+    const bool ready = configured(config);
+    nlohmann::json out{{"platform", platform_}, {"configured", ready}, {"enabled", config.enabled}};
+    std::shared_ptr<im::Transport> transport;
+    std::string load_error;
+    bool standby;
+    std::int64_t holder_pid;
+    {
+        std::lock_guard<std::mutex> lock(mu_);
+        transport = transport_;
+        load_error = load_error_;
+        standby = standby_;
+        holder_pid = holder_pid_;
+    }
+    // 传输层在自己的锁外回调 on_status,这里在本对象锁外读取它的状态,不会互锁。
+    const auto status = transport ? transport->status() : im::TransportStatus{};
+    std::string state;
+    if (!load_error.empty()) state = "error";
+    else if (!config.enabled) state = ready ? "disabled" : "unconfigured";
+    else if (standby) state = "standby";
+    else if (!transport) state = ready ? "stopped" : "unconfigured";
+    else if (status.state == im::LinkState::Stopped) state = "connecting";
+    else state = im::link_state_name(status.state);
+    out["state"] = state;
+    out["detail"] = load_error.empty() ? status.detail : load_error;
+    out["retry_stopped"] = status.retry_stopped;
+    out["account"] = status.account;
+    out["display_name"] = status.display_name;
+    out["extra"] = status.extra.is_object() ? status.extra : nlohmann::json::object();
+    if (standby && holder_pid > 0) out["hosted_by_pid"] = holder_pid;
+    // 凭据:非密钥字段原样给出(AppID、机器人 id 等),密钥只给尾号;credential_hint 是第一个密钥的尾号。
+    nlohmann::json public_fields = nlohmann::json::object();
+    if (const auto* spec = find_platform_spec(platform_)) {
+        for (const auto& field : spec->fields) {
+            const auto value = config.credentials.is_object() ? config.credentials.value(field.key, std::string{})
+                                                              : std::string{};
+            if (value.empty()) continue;
+            if (!field.secret) {
+                public_fields[field.key] = value;
+                continue;
+            }
+            const auto masked = im::mask_secret(value);
+            public_fields[field.key] = masked;
+            if (!out.contains("credential_hint")) out["credential_hint"] = masked;
+        }
+    }
+    out["credentials_public"] = public_fields;
+    if (platform_ == "qq") out["app_id"] = config.credentials.value("app_id", std::string{});
+    nlohmann::json contacts = nlohmann::json::array();
+    for (const auto& entry : config.access) {
+        contacts.push_back({{"principal", entry.principal},
+                            {"kind", principal_kind(entry.principal)},
+                            {"name", entry.name},
+                            {"owner", entry.principal == config.owner},
+                            {"approved_at_ms", entry.approved_at_ms}});
+    }
+    out["contacts"] = contacts;
+    out["owner"] = config.owner.empty() ? nlohmann::json(nullptr) : nlohmann::json(config.owner);
+    nlohmann::json pending = nlohmann::json::array();
+    const auto now = AccessControl::Clock::now();
+    for (const auto& request : access_.pending(now)) {
+        pending.push_back(
+            {{"id", request.id},
+             {"kind", request.kind},
+             {"name", request.name},
+             {"principal", request.principal},
+             {"label", Conversations::label_for(request.address)},
+             {"expires_in_s", std::chrono::duration_cast<std::chrono::seconds>(request.expires - now).count()}});
+    }
+    out["pending"] = pending;
+    out["owner_window"] = access_.owner_window_open(now);
+    out["bindings"] = conversations_->bindings_json();
+    return out;
+}
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/platform_runtime.hpp b/src/host/channels/core/platform_runtime.hpp
new file mode 100644
index 000000000..d4eae07ab
--- /dev/null
+++ b/src/host/channels/core/platform_runtime.hpp
@@ -0,0 +1,134 @@
+#pragma once
+
+// 单个平台(QQ / Telegram)的运行时(design D4):
+//   - 开关即连:enable 时取该平台账号的跨进程归属锁,取到就连接传输层;
+//     取不到进入待命,每隔 standby_retry 重试,持有者退出后接管;disable 立即断开并释放锁。
+//   - 入站消息进有界队列,由本平台的工作线程串行交给 Conversations 处理。
+//   - 状态变化、新的待批准请求通过 broadcast 推给设置页。
+
+#include "channels/core/access.hpp"
+#include "channels/core/conversations.hpp"
+#include "channels/core/projection.hpp"
+#include "channels/core/store.hpp"
+#include "im/transport.hpp"
+#include "utils/joining_thread.hpp"
+#include "utils/lifetime_token.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <deque>
+#include <filesystem>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <vector>
+
+namespace acecode::channels::core {
+
+using TransportFactory =
+    std::function<std::shared_ptr<im::Transport>(const std::string& platform, const PlatformConfig&, ChannelStore&)>;
+// 校验凭据(联网);成功返回规范化后的凭据,失败返回 null 并写 error。
+using CredentialValidator =
+    std::function<nlohmann::json(const std::string& platform, const nlohmann::json& credentials, std::string* error)>;
+using Broadcast = std::function<void(const std::string& type, const nlohmann::json& payload)>;
+
+struct RuntimeServices {
+    ConversationDeps conversation;
+    TransportFactory make_transport;
+    CredentialValidator validate_credentials;
+    Broadcast broadcast;
+    std::function<std::int64_t()> current_pid;
+    std::chrono::milliseconds standby_retry{std::chrono::seconds(5)};
+};
+
+class PlatformRuntime {
+public:
+    static constexpr std::size_t kMaxQueue = 256;
+
+    PlatformRuntime(std::string platform, std::filesystem::path directory, RuntimeServices services);
+    ~PlatformRuntime();
+    PlatformRuntime(const PlatformRuntime&) = delete;
+    PlatformRuntime& operator=(const PlatformRuntime&) = delete;
+
+    // 读盘;已开启的平台自动连接。
+    void start();
+    // 断开并停止所有线程,保留配置。
+    void stop();
+
+    const std::string& platform() const { return platform_; }
+    nlohmann::json snapshot() const;
+    std::string owner() const { return store_.config().owner; }
+
+    // 以下操作失败时抛 std::runtime_error(消息可直接展示,不含凭据)。
+    void set_enabled(bool enabled);
+    // 缺失或为空的字段沿用已保存的值;validate 时先联网校验,失败不保存。
+    // 换成另一个机器人账号时,丢弃旧账号下的会话绑定;QQ 的用户 openid 按机器人隔离,
+    // 机主与授权名单也一并清空。
+    void set_credentials(const nlohmann::json& credentials, bool validate = true);
+    void approve(const std::string& request_id, bool approve);
+    void revoke(const std::string& principal);
+    std::string issue_owner_code();
+    std::string issue_owner_pin();  // 6 位绑定码;已有机主时抛异常
+    void open_owner_window();
+    void set_owner(const std::string& principal, const std::string& name);
+    nlohmann::json action(const std::string& name, const nlohmann::json& args);
+    im::TransportStatus transport_status() const;
+
+    bool release_session(const std::string& session_id, const std::string& except_key, const std::string& label);
+    std::vector<std::string> bound_session_ids() const;
+
+    // 推送当前快照给设置页,并把与上次相比的变化写进日志(state_log.hpp)。
+    void publish_state();
+
+private:
+    // 以下两个只在持有 ops_mu_ 时调用。
+    void connect_locked();
+    void disconnect_locked();
+    void worker_loop();
+    void try_takeover();
+    void on_inbound(im::Inbound inbound);
+    // 传输层状态变化;source 已不是当前连接(被替换的旧连接)时忽略。
+    void on_transport_status(const std::weak_ptr<im::Transport>& source);
+    bool configured(const PlatformConfig& config) const;
+    std::string account_of(const PlatformConfig& config) const;
+    void forget_account_locked(const std::string& account);
+    void ensure_loaded() const;
+
+    std::string platform_;
+    std::filesystem::path directory_;
+    RuntimeServices services_;
+    ChannelStore store_;
+    mutable AccessControl access_;
+    std::shared_ptr<TransportSlot> slot_ = std::make_shared<TransportSlot>();
+    std::unique_ptr<Conversations> conversations_;
+
+    std::mutex ops_mu_;      // 串行化开关 / 改凭据 / 接管 / 停止
+    std::mutex process_mu_;  // 入站处理与断开互斥:断开后不再处理排队消息
+    mutable std::mutex mu_;  // 状态字段
+    std::string load_error_;
+    bool running_ = false;
+    bool owns_lock_ = false;
+    bool standby_ = false;
+    std::int64_t holder_pid_ = 0;
+    std::shared_ptr<im::Transport> transport_;
+    struct LockHandle;
+    std::unique_ptr<LockHandle> lock_;
+
+    std::mutex queue_mu_;
+    std::condition_variable queue_cv_;
+    std::deque<im::Inbound> queue_;
+    bool restore_pending_ = false;  // 连接后由工作线程为已有绑定恢复出站投影
+    std::atomic<bool> stopping_{false};
+    std::mutex log_mu_;            // 取快照与比较日志在它下面串行,日志行按状态变化的先后写
+    nlohmann::json logged_state_;  // 上次写进日志的快照
+    acecode::JoiningThread worker_;
+    // 传输层回调经它进入本对象;最后声明,析构时最先撤销(此时 stop() 已停掉传输层)。
+    LifetimeToken lifetime_;
+};
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/platforms.cpp b/src/host/channels/core/platforms.cpp
new file mode 100644
index 000000000..dadfac3a7
--- /dev/null
+++ b/src/host/channels/core/platforms.cpp
@@ -0,0 +1,123 @@
+#include "channels/core/platforms.hpp"
+
+namespace acecode::channels::core {
+namespace {
+
+std::vector<PlatformSpec> build_specs() {
+    std::vector<PlatformSpec> specs;
+
+    PlatformSpec qq;
+    qq.name = "qq";
+    qq.label = "QQ";
+    qq.fields = {{"app_id"}, {"app_secret", true}};
+    qq.account_field = "app_id";
+    qq.group_scoped_members = true;          // 群成员 openid 按群隔离
+    qq.principals_scoped_to_account = true;  // 用户 openid 按机器人隔离
+    qq.owner_binding = OwnerBinding::Scan;
+    qq.scan_bind = true;
+    specs.push_back(qq);
+
+    // 微信(iLink 机器人):凭据全部来自扫码登录,设置页不能手填。
+    PlatformSpec weixin;
+    weixin.name = "weixin";
+    weixin.label = "微信";
+    weixin.fields = {{"bot_token", true, true, false},
+                     {"bot_id", false, true, false},
+                     {"base_url", false, false, false}};
+    weixin.account_field = "bot_id";
+    weixin.principals_scoped_to_account = true;
+    weixin.owner_binding = OwnerBinding::Scan;
+    weixin.scan_bind = true;
+    specs.push_back(weixin);
+
+    PlatformSpec feishu;
+    feishu.name = "feishu";
+    feishu.label = "飞书";
+    feishu.fields = {{"app_id"}, {"app_secret", true}, {"domain", false, false}};
+    feishu.account_field = "app_id";
+    feishu.principals_scoped_to_account = true;  // open_id 按应用隔离
+    specs.push_back(feishu);
+
+    PlatformSpec dingtalk;
+    dingtalk.name = "dingtalk";
+    dingtalk.label = "钉钉";
+    dingtalk.fields = {{"client_id"}, {"client_secret", true}, {"robot_code", false, false}};
+    dingtalk.account_field = "client_id";
+    dingtalk.principals_scoped_to_account = true;
+    specs.push_back(dingtalk);
+
+    PlatformSpec telegram;
+    telegram.name = "telegram";
+    telegram.label = "Telegram";
+    telegram.fields = {{"token", true}};
+    telegram.owner_binding = OwnerBinding::Link;  // 账号 id 是 token 冒号前一段
+    specs.push_back(telegram);
+
+    PlatformSpec discord;
+    discord.name = "discord";
+    discord.label = "Discord";
+    // bot_id 与 application_id 由校验得出;设置页用 application_id 拼邀请链接。
+    discord.fields = {{"token", true}, {"bot_id", false, false, false}, {"application_id", false, false, false}};
+    discord.account_field = "bot_id";  // 用户 id 全局唯一,换机器人不清名单
+    specs.push_back(discord);
+
+    PlatformSpec line;
+    line.name = "line";
+    line.label = "LINE";
+    // Channel ID + Channel secret 换短期令牌;长期令牌是可选的替代。public_url 为空时自动起
+    // Cloudflare 临时隧道。
+    line.fields = {{"channel_id"},
+                   {"channel_secret", true},
+                   {"access_token", true, false},
+                   {"bot_id", false, false, false},
+                   {"public_url", false, false}};
+    line.account_field = "bot_id";
+    line.principals_scoped_to_account = true;  // userId 按 Provider 隔离
+    specs.push_back(line);
+
+    return specs;
+}
+
+} // namespace
+
+const std::vector<PlatformSpec>& platform_specs() {
+    static const std::vector<PlatformSpec> specs = build_specs();
+    return specs;
+}
+
+const PlatformSpec* find_platform_spec(const std::string& name) {
+    for (const auto& spec : platform_specs())
+        if (spec.name == name) return &spec;
+    return nullptr;
+}
+
+std::vector<std::string> platform_names() {
+    std::vector<std::string> names;
+    for (const auto& spec : platform_specs()) names.push_back(spec.name);
+    return names;
+}
+
+std::string platform_label(const std::string& name) {
+    const auto* spec = find_platform_spec(name);
+    return spec ? spec->label : name;
+}
+
+bool credentials_complete(const PlatformSpec& spec, const nlohmann::json& credentials) {
+    if (!credentials.is_object()) return false;
+    for (const auto& field : spec.fields) {
+        if (!field.required) continue;
+        const auto it = credentials.find(field.key);
+        if (it == credentials.end() || !it->is_string() || it->get<std::string>().empty()) return false;
+    }
+    return true;
+}
+
+std::string account_of(const PlatformSpec& spec, const nlohmann::json& credentials) {
+    if (!credentials.is_object()) return {};
+    if (!spec.account_field.empty()) return credentials.value(spec.account_field, std::string{});
+    const auto token = credentials.value("token", std::string{});
+    const auto colon = token.find(':');
+    return colon == std::string::npos ? std::string{} : token.substr(0, colon);
+}
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/platforms.hpp b/src/host/channels/core/platforms.hpp
new file mode 100644
index 000000000..5ee9cff99
--- /dev/null
+++ b/src/host/channels/core/platforms.hpp
@@ -0,0 +1,51 @@
+#pragma once
+
+// 消息通道支持的平台清单。核心、宿主与 Web 接口都从这里取平台名、凭据字段与身份规则,
+// 不再各自写死。平台的连接方式(传输层)在 platform_adapters.cpp 里按名字创建。
+
+#include <nlohmann/json.hpp>
+
+#include <string>
+#include <vector>
+
+namespace acecode::channels::core {
+
+// 机主怎么产生:
+//   Scan  扫码绑定时平台给出扫码人(QQ、微信);拿不到时退回“10 分钟内第一个私聊的人”
+//   Link  一次性深链接(Telegram https://t.me/<机器人>?start=<码>)
+//   Code  一次性 6 位绑定码,机主私聊机器人发送这串数字(飞书、钉钉、Discord、LINE)
+// 三种方式之外,平台还没有机主时批准第一个私聊请求,对方也会成为机主。
+enum class OwnerBinding { Scan, Link, Code };
+
+struct CredentialField {
+    std::string key;
+    bool secret = false;      // 快照只回尾号,日志一律不写
+    bool required = true;     // 缺少时视为未配置
+    bool user_input = true;   // 设置页可以提交;false = 由校验或扫码得出(机器人 id 等)
+};
+
+struct PlatformSpec {
+    std::string name;   // 平台名:数据目录名、接口路径段、Address::platform
+    std::string label;  // 展示名:IM 里的提示文字与日志
+    std::vector<CredentialField> fields;
+    // 绑定地址里的账号 id(Address::account)所在的凭据字段;为空时按 token 冒号前一段推出(Telegram)。
+    std::string account_field;
+    bool group_scoped_members = false;          // 群成员身份按群隔离(QQ 的群成员 openid)
+    bool principals_scoped_to_account = false;  // 用户 id 按机器人隔离:换机器人时清空机主与授权名单
+    OwnerBinding owner_binding = OwnerBinding::Code;
+    bool scan_bind = false;                     // 有扫码绑定流程(QQ、微信)
+};
+
+const std::vector<PlatformSpec>& platform_specs();
+// 未知平台返回 nullptr。
+const PlatformSpec* find_platform_spec(const std::string& name);
+std::vector<std::string> platform_names();
+// 展示名;未知平台原样返回。
+std::string platform_label(const std::string& name);
+
+// 已保存凭据里必填字段是否都有非空字符串值。
+bool credentials_complete(const PlatformSpec& spec, const nlohmann::json& credentials);
+// 绑定地址里的账号 id;凭据不全时可能为空。
+std::string account_of(const PlatformSpec& spec, const nlohmann::json& credentials);
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/projection.cpp b/src/host/channels/core/projection.cpp
new file mode 100644
index 000000000..315d663ee
--- /dev/null
+++ b/src/host/channels/core/projection.cpp
@@ -0,0 +1,304 @@
+#include "projection.hpp"
+
+#include "channels/core/commands.hpp"
+#include "remote_control/rc_session_navigation.hpp"
+#include "remote_control/session_channel_binder.hpp"
+#include "session/attachment_store.hpp"
+#include "session/output_attachments.hpp"
+#include "session/session_storage.hpp"
+#include "utils/logger.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <filesystem>
+
+namespace acecode::channels::core {
+namespace {
+
+constexpr std::size_t kMaxClosedPermissions = 256;
+
+// path 必须在 root 之下(规范化后逐段比较,Windows 不区分大小写)。
+bool path_inside(const std::filesystem::path& path, const std::filesystem::path& root) {
+    std::error_code ec;
+    const auto resolved = std::filesystem::weakly_canonical(path, ec);
+    if (ec) return false;
+    const auto base = std::filesystem::weakly_canonical(root, ec);
+    if (ec || resolved == base) return false;
+    auto p = resolved.begin();
+    for (auto r = base.begin(); r != base.end(); ++r, ++p) {
+        if (p == resolved.end()) return false;
+#ifdef _WIN32
+        if (_wcsicmp(p->c_str(), r->c_str()) != 0) return false;
+#else
+        if (*p != *r) return false;
+#endif
+    }
+    return true;
+}
+
+// 把出站消息交给当前传输层。附件必须按 id 重新解析,并确认文件仍在该会话自己的
+// 附件目录里 —— 绝不信任模型给出的路径。
+class ImSender final : public rc::OutboundSender {
+public:
+    ImSender(im::Address address, std::string session_id, std::string cwd, std::shared_ptr<TransportSlot> slot)
+        : address_(std::move(address)), session_id_(std::move(session_id)), cwd_(std::move(cwd)),
+          slot_(std::move(slot)) {}
+
+    bool send(const rc::OutboundMessage& msg, std::string* error) override {
+        const auto transport = slot_->get();
+        if (!transport) {
+            if (error) *error = "通道未连接";
+            return false;
+        }
+        nlohmann::json context = nlohmann::json::object();
+        if (!msg.in_reply_to.empty()) {
+            try {
+                context = nlohmann::json::parse(msg.in_reply_to);
+            } catch (...) {
+            }
+        }
+        im::SendResult result;
+        if (msg.type == "file" && msg.attachment.is_object()) {
+            const auto id = msg.attachment.value("id", std::string{});
+            const auto project = SessionStorage::get_project_dir(cwd_);
+            std::string load_error;
+            const auto record = load_attachment(project, session_id_, id, &load_error);
+            if (!record) {
+                if (error) *error = load_error.empty() ? "附件不存在" : load_error;
+                return false;
+            }
+            const auto root = path_from_utf8(project) / "attachments" / session_id_;
+            if (!path_inside(path_from_utf8(record->path), root)) {
+                if (error) *error = "附件不在会话附件目录内";
+                return false;
+            }
+            result = transport->send_file(address_, path_from_utf8(record->path), record->name, record->mime_type,
+                                          context);
+        } else {
+            result = transport->send_text(address_, msg.text, context);
+        }
+        if (!result.ok()) {
+            if (error) *error = result.error;
+            return false;
+        }
+        return true;
+    }
+
+private:
+    im::Address address_;
+    std::string session_id_, cwd_;
+    std::shared_ptr<TransportSlot> slot_;
+};
+
+} // namespace
+
+std::shared_ptr<im::Transport> TransportSlot::get() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return transport_;
+}
+
+void TransportSlot::set(std::shared_ptr<im::Transport> transport) {
+    std::lock_guard<std::mutex> lock(mu_);
+    transport_ = std::move(transport);
+}
+
+Projection::Projection(BindingRecord record, ProjectionDeps deps)
+    : record_(std::move(record)), deps_(std::move(deps)) {}
+
+Projection::~Projection() { stop(); }
+
+void Projection::start() {
+    {
+        std::lock_guard<std::recursive_mutex> lock(mu_);
+        if (started_) return;
+        started_ = true;
+    }
+    hub_.enable("channel-internal", record_.session_id,
+                std::make_shared<ImSender>(record_.address, record_.session_id, record_.cwd, deps_.transport));
+    std::weak_ptr<Projection> weak = shared_from_this();
+    // 先订阅再读快照,避免两者之间产生的请求被漏掉。
+    subscription_ = deps_.sessions->subscribe(record_.session_id, [weak](const SessionEvent& event) {
+        if (auto self = weak.lock()) self->on_event(event);
+    });
+    if (auto pending = deps_.sessions->snapshot_pending_questions(record_.session_id)) {
+        std::lock_guard<std::recursive_mutex> lock(mu_);
+        emit_question_action(questions_.merge_snapshot(std::move(*pending)));
+    }
+    if (deps_.pending_permissions) {
+        const auto pending = deps_.pending_permissions(record_.session_id);
+        std::lock_guard<std::recursive_mutex> lock(mu_);
+        for (const auto& request : pending) permission_locked(request);
+    }
+}
+
+void Projection::stop() {
+    SessionClient::SubscriptionId subscription = 0;
+    {
+        std::lock_guard<std::recursive_mutex> lock(mu_);
+        if (!started_ || closed_) return;
+        flush_locked();
+        closed_ = true;
+        subscription = subscription_;
+        subscription_ = 0;
+    }
+    if (subscription) deps_.sessions->unsubscribe(record_.session_id, subscription);
+    set_typing(false);
+    hub_.clear_inbound_route();
+    hub_.disable();
+}
+
+void Projection::set_typing(bool on) {
+    const auto transport = deps_.transport->get();
+    if (transport && transport->capabilities().supports_typing) transport->set_typing(record_.address, on);
+}
+
+void Projection::enqueue_text_locked(const std::string& text, const nlohmann::json& reply_context) {
+    if (closed_ || text.empty()) return;
+    rc::OutboundMessage message;
+    message.type = "assistant_message";
+    message.text = text;
+    message.in_reply_to = reply_context.is_object() && !reply_context.empty() ? reply_context.dump() : std::string{};
+    hub_.notify_outbound(std::move(message));
+}
+
+void Projection::flush_locked() {
+    if (batch_.empty()) return;
+    auto text = std::move(batch_);
+    batch_.clear();
+    enqueue_text_locked(text, reply_context_);
+}
+
+void Projection::say(const std::string& text, const nlohmann::json& reply_context) {
+    std::lock_guard<std::recursive_mutex> lock(mu_);
+    flush_locked();
+    enqueue_text_locked(text, reply_context);
+}
+
+void Projection::emit_question_action(const rc::ChannelQuestionAction& action) {
+    std::lock_guard<std::recursive_mutex> lock(mu_);
+    if (action.outbound_texts.empty()) return;
+    flush_locked();
+    for (const auto& text : action.outbound_texts) enqueue_text_locked(text, reply_context_);
+}
+
+void Projection::permission_locked(const nlohmann::json& request) {
+    const auto id = request.value("request_id", std::string{});
+    if (id.empty() || closed_permissions_.count(id) || permissions_.count(id)) return;
+    permissions_[id] = request;
+    flush_locked();
+    const auto args = rc::chunk_rc_session_output(request.value("args", nlohmann::json::object()).dump(), 1500);
+    enqueue_text_locked(texts::permission_prompt(id, request.value("tool", std::string{}), args.empty() ? "" : args.front()),
+                        reply_context_);
+}
+
+bool Projection::take_permission(const std::string& request_id) {
+    std::lock_guard<std::recursive_mutex> lock(mu_);
+    return permissions_.erase(request_id) > 0;
+}
+
+std::vector<std::string> Projection::pending_permission_ids() const {
+    std::lock_guard<std::recursive_mutex> lock(mu_);
+    std::vector<std::string> ids;
+    for (const auto& [id, request] : permissions_) ids.push_back(id);
+    return ids;
+}
+
+std::vector<std::string> Projection::pending_question_texts() {
+    std::lock_guard<std::recursive_mutex> lock(mu_);
+    return questions_.announce_current().outbound_texts;
+}
+
+void Projection::on_event(const SessionEvent& event) {
+    std::lock_guard<std::recursive_mutex> lock(mu_);
+    if (closed_ || !event.payload.is_object()) return;
+    try {
+        const auto& p = event.payload;
+        const auto transport = deps_.transport->get();
+        const bool batch = transport && transport->capabilities().batch_turn_output;
+        switch (event.kind) {
+            case SessionEventKind::Message:
+                if (p.value("role", std::string{}) == "user") {
+                    flush_locked();
+                    reply_context_ = nlohmann::json::object();
+                    const auto meta = p.value("metadata", nlohmann::json::object());
+                    if (meta.is_object() && meta.contains("channel") && meta["channel"].is_object())
+                        reply_context_ = meta["channel"].value("reply_context", nlohmann::json::object());
+                    sent_attachments_.clear();
+                    return;
+                }
+                break;
+            case SessionEventKind::BusyChanged:
+                if (p.value("busy", false)) {
+                    set_typing(true);
+                } else {
+                    flush_locked();
+                    set_typing(false);
+                }
+                return;
+            case SessionEventKind::Done:
+                flush_locked();
+                set_typing(false);
+                return;
+            case SessionEventKind::QuestionRequest: {
+                auto request = rc::ChannelQuestionBridge::request_from_event(
+                    p, event.seq, rc::ChannelQuestionBridge::Clock::now());
+                if (request) emit_question_action(questions_.add_request(std::move(*request)));
+                return;
+            }
+            case SessionEventKind::QuestionClosed:
+                emit_question_action(questions_.close_request(p.value("request_id", std::string{}),
+                                                              p.value("reason", std::string("closed"))));
+                return;
+            case SessionEventKind::PermissionRequest:
+                permission_locked(p);
+                return;
+            case SessionEventKind::PermissionClosed: {
+                const auto id = p.value("request_id", std::string{});
+                if (permissions_.erase(id)) {
+                    flush_locked();
+                    enqueue_text_locked(texts::permission_closed(id, p.value("choice", std::string("closed"))),
+                                        reply_context_);
+                }
+                closed_permissions_.insert(id);
+                closed_order_.push_back(id);
+                if (closed_order_.size() > kMaxClosedPermissions) {
+                    closed_permissions_.erase(closed_order_.front());
+                    closed_order_.erase(closed_order_.begin());
+                }
+                return;
+            }
+            default:
+                break;
+        }
+        const auto output = rc::classify_session_event(event.kind, p);
+        if (output.kind == rc::OutboundEventAction::Kind::AssistantText && !output.text.empty()) {
+            if (batch) {
+                if (!batch_.empty()) batch_ += "\n\n";
+                batch_ += output.text;
+                if (batch_.size() > 32 * 1024) flush_locked();
+            } else {
+                enqueue_text_locked(output.text, reply_context_);
+            }
+        }
+        nlohmann::json files = nlohmann::json::array();
+        if (event.kind == SessionEventKind::Message && p.value("role", std::string{}) == "assistant")
+            files = output_attachments_from_content_parts(p.value("content_parts", nlohmann::json::array()));
+        if (event.kind == SessionEventKind::ToolEnd) files = p.value("attachments", nlohmann::json::array());
+        if (files.is_array() && !files.empty()) {
+            flush_locked();
+            for (const auto& file : files) {
+                if (!file.is_object()) continue;
+                const auto id = file.value("id", std::string{});
+                if (id.empty() || !sent_attachments_.insert(id).second) continue;
+                rc::OutboundMessage message;
+                message.type = "file";
+                message.attachment = file;
+                message.in_reply_to = reply_context_.empty() ? std::string{} : reply_context_.dump();
+                hub_.notify_outbound(std::move(message));
+            }
+        }
+    } catch (const std::exception& e) {
+        LOG_WARN(std::string("[channels] cannot project session event: ") + e.what());
+    }
+}
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/projection.hpp b/src/host/channels/core/projection.hpp
new file mode 100644
index 000000000..94fb5fdf7
--- /dev/null
+++ b/src/host/channels/core/projection.hpp
@@ -0,0 +1,99 @@
+#pragma once
+
+// 一个绑定的出站投影(design D8):订阅绑定会话的事件,把最终助手文本、会话产生的
+// 附件、权限请求、提问发到对应 IM 会话;发送经 RemoteControlHub 的有界 FIFO 串行执行,
+// 失败/丢弃计数供设置页显示。
+//
+// - 平台声明 batch_turn_output(QQ)时,同一回合的助手文本先缓存,回合结束或要发权限
+//   请求/提问/文件时合并发出,以节省被动回复额度。
+// - 回复引用:用户消息若来自 IM(metadata.channel.reply_context),本回合输出就引用它;
+//   Desktop 里输入的消息没有引用(QQ 上表现为主动消息)。
+// - 平台支持“正在输入”时,会话忙碌期间保持该状态。
+
+#include "channels/core/store.hpp"
+#include "im/transport.hpp"
+#include "remote_control/channel_question_bridge.hpp"
+#include "remote_control/remote_control_hub.hpp"
+#include "session/session_client.hpp"
+
+#include <functional>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <set>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace acecode::channels::core {
+
+// 线程安全地持有当前传输层;开关、改凭据时整体替换。
+class TransportSlot {
+public:
+    std::shared_ptr<im::Transport> get() const;
+    void set(std::shared_ptr<im::Transport> transport);
+
+private:
+    mutable std::mutex mu_;
+    std::shared_ptr<im::Transport> transport_;
+};
+
+struct ProjectionDeps {
+    SessionClient* sessions = nullptr;
+    std::shared_ptr<TransportSlot> transport;
+    std::function<std::vector<nlohmann::json>(const std::string&)> pending_permissions;
+};
+
+class Projection : public std::enable_shared_from_this<Projection> {
+public:
+    Projection(BindingRecord record, ProjectionDeps deps);
+    ~Projection();
+    Projection(const Projection&) = delete;
+    Projection& operator=(const Projection&) = delete;
+
+    void start();
+    // 退订并排空发送队列;之后不再发送任何东西。
+    void stop();
+
+    const BindingRecord& record() const { return record_; }
+    // 命令回复等:按 reply_context 引用触发它的消息,走同一个有序队列。
+    void say(const std::string& text, const nlohmann::json& reply_context);
+    // 一次性取走权限请求;不存在或已关闭返回 false。
+    bool take_permission(const std::string& request_id);
+    std::vector<std::string> pending_permission_ids() const;
+    std::vector<std::string> pending_question_texts();
+
+    // AskUserQuestion 的 /aq 与插话处理需要在锁内驱动问题状态机。
+    template <typename Fn>
+    auto with_questions(Fn&& fn) -> decltype(fn(std::declval<rc::ChannelQuestionBridge&>())) {
+        std::lock_guard<std::recursive_mutex> lock(mu_);
+        return fn(questions_);
+    }
+    void emit_question_action(const rc::ChannelQuestionAction& action);
+
+    rc::RemoteControlStats stats() const { return hub_.stats(); }
+
+private:
+    void on_event(const SessionEvent& event);
+    void enqueue_text_locked(const std::string& text, const nlohmann::json& reply_context);
+    void flush_locked();
+    void permission_locked(const nlohmann::json& request);
+    void set_typing(bool on);
+
+    BindingRecord record_;
+    ProjectionDeps deps_;
+    rc::RemoteControlHub hub_;
+    rc::ChannelQuestionBridge questions_;
+    SessionClient::SubscriptionId subscription_ = 0;
+    mutable std::recursive_mutex mu_;
+    bool started_ = false;
+    bool closed_ = false;
+    nlohmann::json reply_context_ = nlohmann::json::object();
+    std::string batch_;
+    std::map<std::string, nlohmann::json> permissions_;
+    std::set<std::string> closed_permissions_;
+    std::vector<std::string> closed_order_;
+    std::set<std::string> sent_attachments_;
+};
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/state_log.cpp b/src/host/channels/core/state_log.cpp
new file mode 100644
index 000000000..f1468d1a2
--- /dev/null
+++ b/src/host/channels/core/state_log.cpp
@@ -0,0 +1,222 @@
+#include "channels/core/state_log.hpp"
+
+#include <cstdint>
+#include <map>
+
+namespace acecode::channels::core {
+namespace {
+
+const nlohmann::json& field(const nlohmann::json& object, const char* key) {
+    static const nlohmann::json kNull;
+    if (!object.is_object()) return kNull;
+    const auto it = object.find(key);
+    return it == object.end() ? kNull : *it;
+}
+
+std::string text_of(const nlohmann::json& object, const char* key) {
+    const auto& value = field(object, key);
+    return value.is_string() ? value.get<std::string>() : std::string{};
+}
+
+std::int64_t number_of(const nlohmann::json& object, const char* key) {
+    const auto& value = field(object, key);
+    return value.is_number_integer() ? value.get<std::int64_t>() : 0;
+}
+
+bool flag_of(const nlohmann::json& object, const char* key) {
+    const auto& value = field(object, key);
+    return value.is_boolean() && value.get<bool>();
+}
+
+std::string dump(const nlohmann::json& value) {
+    return value.dump(-1, ' ', false, nlohmann::json::error_handler_t::replace);
+}
+
+std::map<std::string, nlohmann::json> index_by(const nlohmann::json& list, const char* key) {
+    std::map<std::string, nlohmann::json> out;
+    if (!list.is_array()) return out;
+    for (const auto& item : list) {
+        const auto id = text_of(item, key);
+        if (!id.empty()) out[id] = item;
+    }
+    return out;
+}
+
+// 状态 + 机器人名 + 托管进程 + 原因,例如 "connected @ace_bot"、"failed (retry stopped): token 无效"。
+std::string state_text(const nlohmann::json& snapshot) {
+    std::string text = text_of(snapshot, "state");
+    if (text.empty()) text = "unknown";
+    if (flag_of(snapshot, "retry_stopped")) text += " (retry stopped)";
+    const auto name = text_of(snapshot, "display_name");
+    if (!name.empty()) text += " " + name;
+    const auto pid = number_of(snapshot, "hosted_by_pid");
+    if (pid > 0) text += " (held by pid " + std::to_string(pid) + ")";
+    const auto detail = text_of(snapshot, "detail");
+    if (!detail.empty()) text += ": " + detail;
+    return text;
+}
+
+LogLevel state_level(const nlohmann::json& snapshot) {
+    const auto state = text_of(snapshot, "state");
+    return state == "failed" || state == "retrying" || state == "error" ? LogLevel::Warn : LogLevel::Info;
+}
+
+std::string who(const std::string& principal, const std::string& name) {
+    return name.empty() ? principal : principal + " (" + name + ")";
+}
+
+std::string owner_text(const nlohmann::json& snapshot) {
+    const auto owner = text_of(snapshot, "owner");
+    if (owner.empty()) return "none";
+    const auto& contacts = field(snapshot, "contacts");
+    if (contacts.is_array())
+        for (const auto& contact : contacts)
+            if (text_of(contact, "principal") == owner) return who(owner, text_of(contact, "name"));
+    return owner;
+}
+
+std::string binding_text(const nlohmann::json& binding) {
+    std::string text = text_of(binding, "label");
+    const auto chat = text_of(binding, "chat");
+    if (!chat.empty()) text += " chat " + chat;
+    const auto sender = text_of(binding, "sender");
+    if (!sender.empty() && sender != chat) text += " sender " + sender;
+    return text;
+}
+
+std::string binding_target(const nlohmann::json& binding) {
+    std::string text = "session " + text_of(binding, "session_id");
+    const auto cwd = text_of(binding, "cwd");
+    const auto& no_workspace = field(binding, "no_workspace");
+    if (no_workspace.is_boolean() && !no_workspace.get<bool>() && !cwd.empty()) text += " in " + cwd;
+    else text += " (no workspace)";
+    return text;
+}
+
+std::string counts_text(const nlohmann::json& binding) {
+    return "sent " + std::to_string(number_of(binding, "sent")) + ", failed " +
+           std::to_string(number_of(binding, "failed")) + ", dropped " + std::to_string(number_of(binding, "dropped"));
+}
+
+void describe_extra(const nlohmann::json& before, const nlohmann::json& after, bool first,
+                    std::vector<StateLogLine>& lines) {
+    const auto& extra_before = field(before, "extra");
+    const auto& extra_after = field(after, "extra");
+    const bool has_after = extra_after.is_object() && !extra_after.empty();
+    if (first ? !has_after : extra_before == extra_after) return;
+    lines.push_back({LogLevel::Info, "status " + (extra_after.is_object() ? dump(extra_after) : std::string("{}"))});
+    const auto& privacy_before = field(extra_before, "privacy_mode");
+    const auto& privacy_after = field(extra_after, "privacy_mode");
+    if (privacy_after.is_boolean() && privacy_after != privacy_before) {
+        lines.push_back({LogLevel::Info, privacy_after.get<bool>()
+            ? "group privacy mode on: groups deliver only @mentions, replies to the bot and commands"
+            : "group privacy mode off: the bot receives every group message but only handles @mentions"});
+    }
+    if (flag_of(extra_after, "webhook") && !flag_of(extra_before, "webhook")) {
+        lines.push_back({LogLevel::Warn,
+                         "a webhook is set for this bot; long polling stays blocked until it is removed in the connect dialog"});
+    }
+    const auto held = number_of(extra_after, "held");
+    if (held != number_of(extra_before, "held") && held > 0) {
+        lines.push_back({LogLevel::Warn, std::to_string(held) +
+                         " output(s) held after QQ refused them; they are resent before the contact's next message"});
+    }
+}
+
+void describe_access(const nlohmann::json& before, const nlohmann::json& after, bool first,
+                     std::vector<StateLogLine>& lines) {
+    const bool configured = flag_of(after, "configured");
+    if (first ? configured : text_of(before, "owner") != text_of(after, "owner"))
+        lines.push_back({LogLevel::Info, "owner " + owner_text(after)});
+    if (flag_of(after, "owner_window") != flag_of(before, "owner_window")) {
+        lines.push_back({LogLevel::Info, flag_of(after, "owner_window")
+            ? "owner window open: the first private chat within 10 minutes becomes the owner"
+            : "owner window closed"});
+    }
+    const auto contacts_before = index_by(field(before, "contacts"), "principal");
+    const auto contacts_after = index_by(field(after, "contacts"), "principal");
+    for (const auto& [principal, contact] : contacts_after) {
+        if (contacts_before.count(principal)) continue;
+        lines.push_back({LogLevel::Info, (first ? "authorized " : "access granted: ") +
+                                             who(principal, text_of(contact, "name"))});
+    }
+    for (const auto& [principal, contact] : contacts_before) {
+        if (contacts_after.count(principal)) continue;
+        lines.push_back({LogLevel::Info, "access removed: " + who(principal, text_of(contact, "name"))});
+    }
+    const auto pending_before = index_by(field(before, "pending"), "id");
+    const auto pending_after = index_by(field(after, "pending"), "id");
+    for (const auto& [id, request] : pending_after) {
+        if (pending_before.count(id)) continue;
+        lines.push_back({LogLevel::Info, "request " + id + " pending: " + text_of(request, "kind") + " " +
+                                             who(text_of(request, "principal"), text_of(request, "name")) + " via " +
+                                             text_of(request, "label") + ", expires in " +
+                                             std::to_string(number_of(request, "expires_in_s")) + "s"});
+    }
+    for (const auto& [id, request] : pending_before) {
+        if (pending_after.count(id)) continue;
+        lines.push_back({LogLevel::Info, "request " + id + " closed (approved, rejected or expired): " +
+                                             who(text_of(request, "principal"), text_of(request, "name"))});
+    }
+}
+
+void describe_bindings(const nlohmann::json& before, const nlohmann::json& after, bool first,
+                       std::vector<StateLogLine>& lines) {
+    const auto bindings_before = index_by(field(before, "bindings"), "key");
+    const auto bindings_after = index_by(field(after, "bindings"), "key");
+    for (const auto& [key, binding] : bindings_after) {
+        const auto old = bindings_before.find(key);
+        if (old == bindings_before.end()) {
+            lines.push_back({LogLevel::Info, "binding " + binding_text(binding) + " -> " + binding_target(binding) +
+                                                 (first ? " (" + counts_text(binding) + ")" : std::string{})});
+            continue;
+        }
+        if (text_of(old->second, "session_id") != text_of(binding, "session_id"))
+            lines.push_back({LogLevel::Info, "binding " + binding_text(binding) + " -> " + binding_target(binding)});
+        const auto sent = number_of(binding, "sent") - number_of(old->second, "sent");
+        const auto failed = number_of(binding, "failed") - number_of(old->second, "failed");
+        const auto dropped = number_of(binding, "dropped") - number_of(old->second, "dropped");
+        if (failed > 0)
+            lines.push_back({LogLevel::Warn, "delivery to " + binding_text(binding) + " failed (" + counts_text(binding) + ")"});
+        if (dropped > 0)
+            lines.push_back({LogLevel::Warn, std::to_string(dropped) + " output(s) to " + binding_text(binding) +
+                                                 " dropped (" + counts_text(binding) + ")"});
+        if (sent > 0)
+            lines.push_back({LogLevel::Dbg, "delivered " + std::to_string(sent) + " to " + binding_text(binding) + " (" +
+                                                counts_text(binding) + ")"});
+    }
+    for (const auto& [key, binding] : bindings_before) {
+        if (bindings_after.count(key)) continue;
+        lines.push_back({LogLevel::Info, "binding removed: " + binding_text(binding) + " (was " +
+                                             binding_target(binding) + ")"});
+    }
+}
+
+} // namespace
+
+std::vector<StateLogLine> describe_state_changes(const nlohmann::json& previous, const nlohmann::json& next) {
+    // 首次发布时 previous 不是对象,下面的取值一律得到空值,相当于和空快照比较。
+    std::vector<StateLogLine> lines;
+    const bool first = !previous.is_object();
+    const auto after_state = state_text(next);
+    if (first) {
+        lines.push_back({state_level(next), "state " + after_state});
+    } else {
+        const auto before_state = state_text(previous);
+        if (before_state != after_state)
+            lines.push_back({state_level(next), "state " + before_state + " -> " + after_state});
+        if (text_of(previous, "credential_hint") != text_of(next, "credential_hint") ||
+            text_of(previous, "app_id") != text_of(next, "app_id") ||
+            field(previous, "credentials_public") != field(next, "credentials_public")) {
+            const auto app_id = text_of(next, "app_id");
+            lines.push_back({LogLevel::Info, app_id.empty() ? std::string("credentials updated")
+                                                             : "credentials updated (AppID " + app_id + ")"});
+        }
+    }
+    describe_extra(previous, next, first, lines);
+    describe_access(previous, next, first, lines);
+    describe_bindings(previous, next, first, lines);
+    return lines;
+}
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/state_log.hpp b/src/host/channels/core/state_log.hpp
new file mode 100644
index 000000000..ddf79c718
--- /dev/null
+++ b/src/host/channels/core/state_log.hpp
@@ -0,0 +1,27 @@
+#pragma once
+
+// 消息通道状态日志(openspec add-desktop-im-channels,2026-10-05 验收反馈):设置页只显示
+// 简要状态,细节——连接状态与原因、平台附加信息(隐私模式、webhook、暂存待补发)、机主、
+// 授权名单、待批准请求、会话绑定与收发计数——在平台快照变化时写进 daemon 日志。
+// 只用快照里本就可以展示的字段;凭据(包括脱敏尾号)与二维码内容一律不写。
+
+#include "utils/logger.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <string>
+#include <vector>
+
+namespace acecode::channels::core {
+
+struct StateLogLine {
+    LogLevel level = LogLevel::Info;
+    std::string text;
+};
+
+// 比较同一平台前后两份快照(PlatformRuntime::snapshot 的结构),返回要写的日志行,
+// 不含 "[channels/<平台>] " 前缀。previous 不是对象时视为首次发布,输出当前状态的摘要;
+// 两份内容相同时返回空。
+std::vector<StateLogLine> describe_state_changes(const nlohmann::json& previous, const nlohmann::json& next);
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/store.cpp b/src/host/channels/core/store.cpp
new file mode 100644
index 000000000..33c586061
--- /dev/null
+++ b/src/host/channels/core/store.cpp
@@ -0,0 +1,333 @@
+#include "store.hpp"
+
+#include "utils/atomic_file.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <algorithm>
+#include <chrono>
+#include <fstream>
+#include <stdexcept>
+
+namespace acecode::channels::core {
+namespace {
+
+constexpr std::uintmax_t kMaxFileBytes = 4 * 1024 * 1024;
+constexpr std::size_t kMaxBindings = 2048;
+constexpr std::size_t kMaxAccess = 1024;
+
+bool safe_text(const std::string& value, std::size_t limit) {
+    return value.size() <= limit && value.find('\0') == std::string::npos;
+}
+
+bool session_id_ok(const std::string& id) {
+    return !id.empty() && id.size() <= 128 && std::all_of(id.begin(), id.end(), [](char c) {
+        return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '-' || c == '_';
+    });
+}
+
+bool principal_ok(const std::string& principal) {
+    return !principal.empty() && safe_text(principal, 300) &&
+           (principal.rfind("user:", 0) == 0 || principal.rfind("group:", 0) == 0 ||
+            principal.rfind("member:", 0) == 0);
+}
+
+nlohmann::json empty_state() {
+    return {{"version", 1}, {"bindings", nlohmann::json::object()}, {"created", nlohmann::json::object()},
+            {"receipts", nlohmann::json::array()}, {"cursors", nlohmann::json::object()},
+            {"values", nlohmann::json::object()}};
+}
+
+nlohmann::json read_json_file(const std::filesystem::path& path) {
+    std::error_code ec;
+    if (std::filesystem::file_size(path, ec) > kMaxFileBytes || ec)
+        throw std::runtime_error("通道数据文件过大或不可读:" + path_to_utf8(path.filename()));
+    std::ifstream in(path, std::ios::binary);
+    if (!in) throw std::runtime_error("无法读取通道数据文件:" + path_to_utf8(path.filename()));
+    try {
+        return nlohmann::json::parse(in);
+    } catch (const std::exception&) {
+        throw std::runtime_error("通道数据文件已损坏:" + path_to_utf8(path.filename()));
+    }
+}
+
+BindingRecord binding_from_json(const nlohmann::json& value) {
+    BindingRecord record;
+    record.address = im::Address::from_json(value.at("address"));
+    record.session_id = value.at("session_id").get<std::string>();
+    record.cwd = value.value("cwd", std::string{});
+    record.workspace_hash = value.value("workspace_hash", std::string{});
+    record.no_workspace = value.value("no_workspace", true);
+    record.updated_at_ms = value.value("updated_at_ms", std::int64_t{0});
+    return record;
+}
+
+nlohmann::json binding_to_json(const BindingRecord& record) {
+    return {{"address", record.address.to_json()},
+            {"session_id", record.session_id},
+            {"cwd", record.cwd},
+            {"workspace_hash", record.workspace_hash},
+            {"no_workspace", record.no_workspace},
+            {"updated_at_ms", record.updated_at_ms}};
+}
+
+void validate_state(const nlohmann::json& state) {
+    if (!state.is_object() || state.value("version", 0) != 1 || !state["bindings"].is_object() ||
+        !state["created"].is_object() || !state["receipts"].is_array() || !state["cursors"].is_object())
+        throw std::runtime_error("通道状态文件结构无效");
+    if (state["bindings"].size() > kMaxBindings || state["receipts"].size() > ChannelStore::kMaxReceipts)
+        throw std::runtime_error("通道状态文件超出上限");
+    for (const auto& [key, value] : state["bindings"].items()) {
+        const auto record = binding_from_json(value);
+        if (!record.address.valid() || record.address.key() != key || !session_id_ok(record.session_id) ||
+            !safe_text(record.cwd, 4096) || !safe_text(record.workspace_hash, 128))
+            throw std::runtime_error("通道状态文件里的会话绑定无效");
+    }
+    for (const auto& [key, value] : state["created"].items()) {
+        if (!value.is_array() || value.size() > ChannelStore::kMaxCreatedPerConversation || !safe_text(key, 1024))
+            throw std::runtime_error("通道状态文件里的会话记录无效");
+        for (const auto& id : value)
+            if (!id.is_string() || !session_id_ok(id.get<std::string>())) throw std::runtime_error("通道状态文件里的会话记录无效");
+    }
+    for (const auto& receipt : state["receipts"])
+        if (!receipt.is_string() || receipt.get<std::string>().size() > 2048) throw std::runtime_error("通道回执记录无效");
+    for (const auto& [key, value] : state["cursors"].items())
+        if (!value.is_number_integer() || !safe_text(key, 64)) throw std::runtime_error("通道游标记录无效");
+    if (state.contains("values")) {
+        if (!state["values"].is_object()) throw std::runtime_error("通道状态文件结构无效");
+        for (const auto& [key, value] : state["values"].items()) {
+            (void)value;
+            if (!safe_text(key, 64)) throw std::runtime_error("通道状态记录无效");
+        }
+        if (state["values"].dump().size() > ChannelStore::kMaxValueBytes) throw std::runtime_error("通道状态文件超出上限");
+    }
+}
+
+std::string receipt_key(const std::string& address_key, const std::string& message_id) {
+    if (message_id.empty() || message_id.size() > 256) throw std::runtime_error("Invalid channel message id");
+    return address_key + "|" + message_id;
+}
+
+} // namespace
+
+std::int64_t now_wall_ms() {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(
+               std::chrono::system_clock::now().time_since_epoch())
+        .count();
+}
+
+bool PlatformConfig::has_access(const std::string& principal) const { return find_access(principal) != nullptr; }
+
+const AccessEntry* PlatformConfig::find_access(const std::string& principal) const {
+    for (const auto& entry : access)
+        if (entry.principal == principal) return &entry;
+    return nullptr;
+}
+
+nlohmann::json config_to_json(const PlatformConfig& config) {
+    nlohmann::json access = nlohmann::json::array();
+    for (const auto& entry : config.access)
+        access.push_back({{"principal", entry.principal}, {"name", entry.name}, {"approved_at_ms", entry.approved_at_ms}});
+    return {{"version", 1},
+            {"enabled", config.enabled},
+            {"credentials", config.credentials},
+            {"owner", config.owner},
+            {"access", access}};
+}
+
+PlatformConfig config_from_json(const nlohmann::json& value) {
+    if (!value.is_object() || value.value("version", 0) != 1 || !value.contains("enabled") ||
+        !value["enabled"].is_boolean())
+        throw std::runtime_error("通道配置文件结构无效");
+    PlatformConfig config;
+    config.enabled = value["enabled"].get<bool>();
+    config.credentials = value.value("credentials", nlohmann::json::object());
+    if (!config.credentials.is_object()) throw std::runtime_error("通道凭据格式无效");
+    for (const auto& [key, field] : config.credentials.items())
+        if (!field.is_string() || !safe_text(field.get<std::string>(), 512) || !safe_text(key, 64))
+            throw std::runtime_error("通道凭据格式无效");
+    config.owner = value.value("owner", std::string{});
+    if (!config.owner.empty() && !principal_ok(config.owner)) throw std::runtime_error("通道机主记录无效");
+    const auto access = value.value("access", nlohmann::json::array());
+    if (!access.is_array() || access.size() > kMaxAccess) throw std::runtime_error("通道授权名单无效");
+    for (const auto& item : access) {
+        AccessEntry entry;
+        entry.principal = item.at("principal").get<std::string>();
+        entry.name = item.value("name", std::string{});
+        entry.approved_at_ms = item.value("approved_at_ms", std::int64_t{0});
+        if (!principal_ok(entry.principal) || !safe_text(entry.name, 200)) throw std::runtime_error("通道授权名单无效");
+        config.access.push_back(std::move(entry));
+    }
+    return config;
+}
+
+ChannelStore::ChannelStore(std::filesystem::path directory)
+    : directory_(std::move(directory)), state_(empty_state()) {}
+
+void ChannelStore::load() {
+    PlatformConfig config;
+    nlohmann::json state = empty_state();
+    const auto config_path = directory_ / "config.json";
+    const auto state_path = directory_ / "state.json";
+    std::error_code ec;
+    if (std::filesystem::exists(config_path, ec)) {
+        try {
+            config = config_from_json(read_json_file(config_path));
+        } catch (const nlohmann::json::exception&) {
+            throw std::runtime_error("通道配置文件已损坏");
+        }
+    }
+    if (std::filesystem::exists(state_path, ec)) {
+        state = read_json_file(state_path);
+        try {
+            validate_state(state);
+        } catch (const nlohmann::json::exception&) {
+            throw std::runtime_error("通道状态文件已损坏");
+        }
+        if (!state.contains("values")) state["values"] = nlohmann::json::object();  // 早期版本没有这一项
+    }
+    std::lock_guard<std::mutex> lock(mu_);
+    config_ = std::move(config);
+    state_ = std::move(state);
+}
+
+PlatformConfig ChannelStore::config() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return config_;
+}
+
+void ChannelStore::update_config(const std::function<void(PlatformConfig&)>& edit) {
+    std::lock_guard<std::mutex> lock(mu_);
+    auto next = config_;
+    edit(next);
+    const auto json = config_to_json(next);
+    config_from_json(json);  // 写盘前按读盘规则再校验一遍
+    std::filesystem::create_directories(directory_);
+    if (!atomic_write_file(path_to_utf8(directory_ / "config.json"), json.dump(2) + "\n", true))
+        throw std::runtime_error("无法保存通道配置");
+    config_ = std::move(next);
+}
+
+void ChannelStore::write_state_locked(nlohmann::json next) {
+    validate_state(next);
+    std::filesystem::create_directories(directory_);
+    if (!atomic_write_file(path_to_utf8(directory_ / "state.json"), next.dump(2) + "\n", true))
+        throw std::runtime_error("无法保存通道状态");
+    state_ = std::move(next);
+}
+
+std::optional<BindingRecord> ChannelStore::binding(const std::string& address_key) const {
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto& bindings = state_["bindings"];
+    const auto it = bindings.find(address_key);
+    if (it == bindings.end()) return std::nullopt;
+    return binding_from_json(*it);
+}
+
+std::vector<BindingRecord> ChannelStore::bindings() const {
+    std::lock_guard<std::mutex> lock(mu_);
+    std::vector<BindingRecord> out;
+    for (const auto& [key, value] : state_["bindings"].items()) out.push_back(binding_from_json(value));
+    return out;
+}
+
+void ChannelStore::put_binding(const BindingRecord& record) {
+    std::lock_guard<std::mutex> lock(mu_);
+    auto next = state_;
+    next["bindings"][record.address.key()] = binding_to_json(record);
+    write_state_locked(std::move(next));
+}
+
+void ChannelStore::erase_binding(const std::string& address_key) {
+    std::lock_guard<std::mutex> lock(mu_);
+    if (!state_["bindings"].contains(address_key)) return;
+    auto next = state_;
+    next["bindings"].erase(address_key);
+    write_state_locked(std::move(next));
+}
+
+std::vector<std::string> ChannelStore::created_sessions(const std::string& address_key) const {
+    std::lock_guard<std::mutex> lock(mu_);
+    std::vector<std::string> out;
+    const auto it = state_["created"].find(address_key);
+    if (it != state_["created"].end())
+        for (const auto& id : *it) out.push_back(id.get<std::string>());
+    return out;
+}
+
+void ChannelStore::remember_created(const std::string& address_key, const std::string& session_id) {
+    std::lock_guard<std::mutex> lock(mu_);
+    auto next = state_;
+    auto& list = next["created"][address_key];
+    if (!list.is_array()) list = nlohmann::json::array();
+    for (const auto& id : list)
+        if (id == session_id) return;
+    list.push_back(session_id);
+    while (list.size() > kMaxCreatedPerConversation) list.erase(list.begin());
+    write_state_locked(std::move(next));
+}
+
+bool ChannelStore::has_receipt(const std::string& address_key, const std::string& message_id) const {
+    const auto key = receipt_key(address_key, message_id);
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto& receipts = state_["receipts"];
+    return std::find(receipts.begin(), receipts.end(), key) != receipts.end();
+}
+
+void ChannelStore::remember_receipt(const std::string& address_key, const std::string& message_id) {
+    const auto key = receipt_key(address_key, message_id);
+    std::lock_guard<std::mutex> lock(mu_);
+    auto next = state_;
+    auto& receipts = next["receipts"];
+    if (std::find(receipts.begin(), receipts.end(), key) != receipts.end()) return;
+    receipts.push_back(key);
+    while (receipts.size() > kMaxReceipts) receipts.erase(receipts.begin());
+    write_state_locked(std::move(next));
+}
+
+void ChannelStore::forget_receipt(const std::string& address_key, const std::string& message_id) {
+    const auto key = receipt_key(address_key, message_id);
+    std::lock_guard<std::mutex> lock(mu_);
+    auto next = state_;
+    auto& receipts = next["receipts"];
+    receipts.erase(std::remove(receipts.begin(), receipts.end(), nlohmann::json(key)), receipts.end());
+    write_state_locked(std::move(next));
+}
+
+std::int64_t ChannelStore::cursor(const std::string& name) const {
+    std::lock_guard<std::mutex> lock(mu_);
+    return state_["cursors"].value(name, std::int64_t{0});
+}
+
+void ChannelStore::set_cursor(const std::string& name, std::int64_t value) {
+    std::lock_guard<std::mutex> lock(mu_);
+    auto next = state_;
+    next["cursors"][name] = value;
+    write_state_locked(std::move(next));
+}
+
+nlohmann::json ChannelStore::value(const std::string& name) const {
+    std::lock_guard<std::mutex> lock(mu_);
+    const auto& values = state_["values"];
+    const auto it = values.find(name);
+    return it == values.end() ? nlohmann::json(nullptr) : *it;
+}
+
+void ChannelStore::set_value(const std::string& name, const nlohmann::json& value) {
+    if (!safe_text(name, 64)) throw std::runtime_error("Invalid channel state name");
+    std::lock_guard<std::mutex> lock(mu_);
+    auto next = state_;
+    if (value.is_null()) next["values"].erase(name);
+    else next["values"][name] = value;
+    if (next["values"].dump().size() > kMaxValueBytes) throw std::runtime_error("通道状态超出上限");
+    write_state_locked(std::move(next));
+}
+
+void ChannelStore::clear_transport_state() {
+    std::lock_guard<std::mutex> lock(mu_);
+    auto next = state_;
+    next["cursors"] = nlohmann::json::object();
+    next["values"] = nlohmann::json::object();
+    write_state_locked(std::move(next));
+}
+
+} // namespace acecode::channels::core
diff --git a/src/host/channels/core/store.hpp b/src/host/channels/core/store.hpp
new file mode 100644
index 000000000..1ca34e98f
--- /dev/null
+++ b/src/host/channels/core/store.hpp
@@ -0,0 +1,94 @@
+#pragma once
+
+// 消息通道核心:每个平台一个目录(~/.acecode/channels/<platform>/,design D5)。
+//   config.json —— 开关、凭据、机主、授权名单;只在设置页显式操作时写,私有权限原子写入。
+//   state.json  —— 会话绑定、每个 IM 会话创建过的会话、去重回执、平台游标;运行时写入。
+// 文件结构不合法时 load() 抛异常:拒绝启动该平台并把原因显示在页面上,绝不静默重置。
+
+#include "im/transport.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <cstdint>
+#include <filesystem>
+#include <functional>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace acecode::channels::core {
+
+// 一个 IM 会话当前绑定的 ACECode 会话,以及重新打开它所需的身份。
+struct BindingRecord {
+    im::Address address;
+    std::string session_id;
+    std::string cwd;
+    std::string workspace_hash;
+    bool no_workspace = true;
+    std::int64_t updated_at_ms = 0;
+};
+
+struct AccessEntry {
+    std::string principal;  // "user:<id>" / "group:<id>" / "member:<群>:<成员>"
+    std::string name;
+    std::int64_t approved_at_ms = 0;
+};
+
+struct PlatformConfig {
+    bool enabled = false;
+    nlohmann::json credentials = nlohmann::json::object();
+    std::string owner;  // 机主的 principal;空 = 还没有机主
+    std::vector<AccessEntry> access;
+
+    bool has_access(const std::string& principal) const;
+    const AccessEntry* find_access(const std::string& principal) const;
+};
+
+class ChannelStore {
+public:
+    static constexpr std::size_t kMaxReceipts = 4096;
+    static constexpr std::size_t kMaxCreatedPerConversation = 200;
+
+    explicit ChannelStore(std::filesystem::path directory);
+
+    void load();
+    const std::filesystem::path& directory() const { return directory_; }
+
+    PlatformConfig config() const;
+    // 在锁内修改配置并原子写盘;写盘失败抛异常,内存保持原值。
+    void update_config(const std::function<void(PlatformConfig&)>& edit);
+
+    std::optional<BindingRecord> binding(const std::string& address_key) const;
+    std::vector<BindingRecord> bindings() const;
+    void put_binding(const BindingRecord& record);
+    void erase_binding(const std::string& address_key);
+    std::vector<std::string> created_sessions(const std::string& address_key) const;
+    void remember_created(const std::string& address_key, const std::string& session_id);
+    bool has_receipt(const std::string& address_key, const std::string& message_id) const;
+    void remember_receipt(const std::string& address_key, const std::string& message_id);
+    void forget_receipt(const std::string& address_key, const std::string& message_id);
+    std::int64_t cursor(const std::string& name) const;
+    void set_cursor(const std::string& name, std::int64_t value);
+    // 传输层的其它持久状态(微信的字符串游标、按联系人的上下文令牌等);不存在时返回 null。
+    static constexpr std::size_t kMaxValueBytes = 1024 * 1024;
+    nlohmann::json value(const std::string& name) const;
+    void set_value(const std::string& name, const nlohmann::json& value);
+    // 换成另一个机器人账号时:游标与其它持久状态都属于旧机器人,一并清空。
+    void clear_transport_state();
+
+private:
+    void write_state_locked(nlohmann::json next);
+
+    std::filesystem::path directory_;
+    mutable std::mutex mu_;
+    PlatformConfig config_;
+    nlohmann::json state_;
+};
+
+nlohmann::json config_to_json(const PlatformConfig& config);
+PlatformConfig config_from_json(const nlohmann::json& value);  // 不合法时抛异常
+
+std::int64_t now_wall_ms();
+
+} // namespace acecode::channels::core
diff --git a/src/host/session_host/session_registry.cpp b/src/host/session_host/session_registry.cpp
index 10baa9308..68479f006 100644
--- a/src/host/session_host/session_registry.cpp
+++ b/src/host/session_host/session_registry.cpp
@@ -2217,6 +2217,8 @@ std::vector<SessionInfo> SessionRegistry::list_active() const {
             info.title_source = display.title_source;
             info.summary = display.summary;
             info.turn_count = display.turn_count;
+            info.last_user_message_at = display.last_user_message_at;
+            info.last_turn_outcome = display.last_turn_outcome;
             info.last_token_usage = display.last_token_usage;
             info.session_token_usage = display.session_token_usage;
             const auto& worktree = display.worktree;
diff --git a/src/layers.tsv b/src/layers.tsv
index 2cddd8859..0fd468a9d 100644
--- a/src/layers.tsv
+++ b/src/layers.tsv
@@ -33,6 +33,7 @@ module	src/adapters/lsp/	lsp	adapters	28					D1 D2 D15
 module	src/adapters/pa/	pa	adapters	29					D1 D2 D15
 module	src/adapters/provider/	provider	adapters	30					D1 D2 D15
 module	src/adapters/tool/	tool	adapters	31					D1 D2 D15
+module	src/adapters/im/	im	adapters	32					add-desktop-im-channels: QQ / Telegram transports
 module	src/engine/tool_preamble/	tool_preamble	engine	40					D1 D2 D15
 module	src/engine/prompt/	prompt	engine	41					D1 D2 D15
 module	src/engine/agent/	agent	engine	42					D1 D2 D15
diff --git a/tests/channels/core/access_test.cpp b/tests/channels/core/access_test.cpp
new file mode 100644
index 000000000..b46f9ed65
--- /dev/null
+++ b/tests/channels/core/access_test.cpp
@@ -0,0 +1,217 @@
+#include <gtest/gtest.h>
+
+#include "channels/core/access.hpp"
+
+#include <chrono>
+
+// channels/core/access:默认拒绝、待批准请求、机主规则(一次性 start 码 / 扫码后窗口)、
+// 群与群成员分别审批。时间由调用方传入,用固定起点推进。
+
+namespace acecode::channels::core {
+namespace {
+
+using Clock = AccessControl::Clock;
+using std::chrono::minutes;
+using std::chrono::seconds;
+
+im::Inbound private_message(const std::string& user, const std::string& platform = "telegram") {
+    im::Inbound inbound;
+    inbound.address.platform = platform;
+    inbound.address.account = "100";
+    inbound.address.kind = im::ChatKind::Private;
+    inbound.address.chat = user;
+    inbound.address.sender = user;
+    inbound.message_id = "m";
+    inbound.text = "你好";
+    inbound.mentioned = true;
+    inbound.sender_name = "名字" + user;
+    return inbound;
+}
+
+im::Inbound group_message(const std::string& group, const std::string& member, bool mentioned,
+                          const std::string& platform = "telegram") {
+    auto inbound = private_message(member, platform);
+    inbound.address.kind = im::ChatKind::Group;
+    inbound.address.chat = group;
+    inbound.mentioned = mentioned;
+    return inbound;
+}
+
+// 场景:陌生人第一次私聊,随后又连发一条。
+// 期望:第一条得到配对提示并产生一条待批准请求(带展示名);
+// 同一个人在请求有效期内再发,不再提示、不产生重复请求。
+TEST(ChannelAccess, StrangerGetsOnePendingRequest) {
+    AccessControl access;
+    PlatformConfig config;
+    const auto t0 = Clock::now();
+    const auto first = access.evaluate(config, private_message("7"), t0);
+    EXPECT_EQ(first.decision, AccessDecision::NotifyPending);
+    ASSERT_TRUE(first.created.has_value());
+    EXPECT_EQ(first.created->principal, "user:7");
+    EXPECT_EQ(first.created->kind, "user");
+    EXPECT_EQ(first.created->name, "名字7");
+    const auto second = access.evaluate(config, private_message("7"), t0 + seconds(5));
+    EXPECT_EQ(second.decision, AccessDecision::Ignore);
+    EXPECT_FALSE(second.created.has_value());
+    EXPECT_EQ(access.pending(t0 + seconds(5)).size(), 1u);
+}
+
+// 场景:待批准请求放置 10 分钟以上没人处理。
+// 期望:9 分钟时还在;超过 10 分钟后从列表消失,审批该 id 失败;对方再发消息会产生新请求。
+TEST(ChannelAccess, PendingRequestsExpireAfterTenMinutes) {
+    AccessControl access;
+    PlatformConfig config;
+    const auto t0 = Clock::now();
+    const auto created = access.evaluate(config, private_message("7"), t0).created;
+    ASSERT_TRUE(created.has_value());
+    EXPECT_EQ(access.pending(t0 + minutes(9)).size(), 1u);
+    EXPECT_TRUE(access.pending(t0 + minutes(10) + seconds(1)).empty());
+    EXPECT_FALSE(access.take(created->id, t0 + minutes(11)).has_value());
+    const auto again = access.evaluate(config, private_message("7"), t0 + minutes(11));
+    EXPECT_EQ(again.decision, AccessDecision::NotifyPending);
+    EXPECT_TRUE(again.created.has_value());
+}
+
+// 场景:已在授权名单里的联系人私聊;其中一位是机主。
+// 期望:放行;只有机主那一位的 owner 标记为 true。
+TEST(ChannelAccess, ApprovedContactsAreAllowed) {
+    AccessControl access;
+    PlatformConfig config;
+    config.owner = "user:1";
+    config.access = {{"user:1", "", 0}, {"user:2", "", 0}};
+    const auto now = Clock::now();
+    const auto owner = access.evaluate(config, private_message("1"), now);
+    EXPECT_EQ(owner.decision, AccessDecision::Allow);
+    EXPECT_TRUE(owner.owner);
+    const auto contact = access.evaluate(config, private_message("2"), now);
+    EXPECT_EQ(contact.decision, AccessDecision::Allow);
+    EXPECT_FALSE(contact.owner);
+}
+
+// 场景:Telegram 机主绑定链接里的一次性码:正确使用一次、被第二个人重复使用、过期后使用。
+// 期望:第一次使用的人成为机主(claimed_owner);码用过即作废,第二个人只得到配对提示;
+// 过期的码同样无效。
+TEST(ChannelAccess, OwnerStartCodeIsSingleUseAndExpires) {
+    AccessControl access;
+    PlatformConfig config;
+    const auto t0 = Clock::now();
+    const auto code = access.issue_owner_code(t0);
+    ASSERT_EQ(code.size(), 24u);
+    auto claim = private_message("1");
+    claim.start_code = code;
+    const auto first = access.evaluate(config, claim, t0 + minutes(1));
+    EXPECT_EQ(first.decision, AccessDecision::Allow);
+    EXPECT_TRUE(first.claimed_owner);
+    EXPECT_TRUE(first.owner);
+
+    auto reuse = private_message("2");
+    reuse.start_code = code;
+    const auto second = access.evaluate(config, reuse, t0 + minutes(2));
+    EXPECT_FALSE(second.claimed_owner);
+    EXPECT_EQ(second.decision, AccessDecision::NotifyPending);
+
+    const auto late_code = access.issue_owner_code(t0);
+    auto late = private_message("3");
+    late.start_code = late_code;
+    const auto expired = access.evaluate(config, late, t0 + minutes(10) + seconds(1));
+    EXPECT_FALSE(expired.claimed_owner);
+}
+
+// 场景:QQ 扫码成功但绑定服务没给扫码人身份,打开 10 分钟的机主窗口。
+// 期望:窗口内第一个私聊的人成为机主,窗口随即关闭;第二个人走配对审批。
+TEST(ChannelAccess, OwnerWindowClaimsFirstPrivateSender) {
+    AccessControl access;
+    PlatformConfig config;
+    const auto t0 = Clock::now();
+    access.open_owner_window(t0);
+    EXPECT_TRUE(access.owner_window_open(t0 + minutes(1)));
+    const auto first = access.evaluate(config, private_message("OPENID1", "qq"), t0 + minutes(1));
+    EXPECT_TRUE(first.claimed_owner);
+    EXPECT_EQ(first.principal, "user:OPENID1");
+    EXPECT_FALSE(access.owner_window_open(t0 + minutes(1)));
+    const auto second = access.evaluate(config, private_message("OPENID2", "qq"), t0 + minutes(2));
+    EXPECT_FALSE(second.claimed_owner);
+    EXPECT_EQ(second.decision, AccessDecision::NotifyPending);
+}
+
+// 场景:平台已经有机主,此时窗口或绑定码仍在有效期内,陌生人私聊。
+// 期望:不会抢走机主身份,只产生待批准请求。
+TEST(ChannelAccess, ExistingOwnerIsNeverReplacedImplicitly) {
+    AccessControl access;
+    PlatformConfig config;
+    config.owner = "user:1";
+    config.access = {{"user:1", "", 0}};
+    const auto t0 = Clock::now();
+    access.open_owner_window(t0);
+    auto stranger = private_message("9");
+    stranger.start_code = access.issue_owner_code(t0);
+    const auto result = access.evaluate(config, stranger, t0 + seconds(1));
+    EXPECT_FALSE(result.claimed_owner);
+    EXPECT_FALSE(result.owner);
+    EXPECT_EQ(result.decision, AccessDecision::NotifyPending);
+}
+
+// 场景:群聊的完整审批顺序:未 @ 的消息、未批准的群里被 @、群批准后未授权成员被 @、
+// 成员被授权后再 @。
+// 期望:未 @ 直接忽略且不产生请求;未批准的群只在设置页产生群请求、不在群里回复;
+// 群批准后,未授权成员得到一次提示并产生成员请求;授权后放行。
+// 每一步的判定原因都写进日志(设置页不再展示),排查“群里为什么不回”时靠它。
+TEST(ChannelAccess, GroupNeedsApprovalThenMemberApprovalAndMention) {
+    AccessControl access;
+    PlatformConfig config;
+    const auto now = Clock::now();
+    const auto silent = access.evaluate(config, group_message("-100", "5", false), now);
+    EXPECT_EQ(silent.decision, AccessDecision::Ignore);
+    EXPECT_FALSE(silent.created.has_value());
+    EXPECT_EQ(silent.reason, "group message without @mention, ignored");
+
+    const auto unapproved = access.evaluate(config, group_message("-100", "5", true), now);
+    EXPECT_EQ(unapproved.decision, AccessDecision::Ignore);
+    ASSERT_TRUE(unapproved.created.has_value());
+    EXPECT_EQ(unapproved.created->principal, "group:-100");
+    EXPECT_EQ(unapproved.created->kind, "group");
+    EXPECT_EQ(unapproved.reason, "group not approved, approval requested");
+    EXPECT_EQ(access.evaluate(config, group_message("-100", "5", true), now).reason,
+              "group not approved, a request is already pending");
+
+    config.access.push_back({"group:-100", "", 0});
+    const auto member = access.evaluate(config, group_message("-100", "5", true), now);
+    EXPECT_EQ(member.decision, AccessDecision::NotifyPending);
+    ASSERT_TRUE(member.created.has_value());
+    EXPECT_EQ(member.created->principal, "user:5");
+    EXPECT_EQ(member.reason, "group member not authorized, approval requested");
+
+    config.access.push_back({"user:5", "", 0});
+    const auto allowed = access.evaluate(config, group_message("-100", "5", true), now);
+    EXPECT_EQ(allowed.decision, AccessDecision::Allow);
+    EXPECT_EQ(allowed.reason, "authorized");
+    EXPECT_EQ(access.evaluate(config, group_message("-100", "5", false), now).decision, AccessDecision::Ignore);
+}
+
+// 场景:QQ 群成员的 openid 按群隔离,与私聊 openid 不同;Telegram 用户 id 全局唯一。
+// 期望:QQ 群成员身份是 member:<群>:<成员>,Telegram 群成员仍是 user:<id>。
+TEST(ChannelAccess, QqGroupMembersArePerGroupPrincipals) {
+    EXPECT_EQ(principal_for(group_message("G1", "M1", true, "qq").address), "member:G1:M1");
+    EXPECT_EQ(principal_for(group_message("G2", "M1", true, "qq").address), "member:G2:M1");
+    EXPECT_EQ(principal_for(group_message("-100", "5", true, "telegram").address), "user:5");
+    EXPECT_EQ(principal_kind("member:G1:M1"), "member");
+    EXPECT_EQ(principal_kind("group:G1"), "group");
+    EXPECT_EQ(principal_kind("user:5"), "user");
+}
+
+// 场景:机主撤销某人的授权时,对方还有一条待批准请求。
+// 期望:drop_principal 把该身份的请求一并移除,其他人的请求保留。
+TEST(ChannelAccess, DropPrincipalRemovesItsRequests) {
+    AccessControl access;
+    PlatformConfig config;
+    const auto now = Clock::now();
+    access.evaluate(config, private_message("7"), now);
+    access.evaluate(config, private_message("8"), now);
+    access.drop_principal("user:7");
+    const auto pending = access.pending(now);
+    ASSERT_EQ(pending.size(), 1u);
+    EXPECT_EQ(pending[0].principal, "user:8");
+}
+
+} // namespace
+} // namespace acecode::channels::core
diff --git a/tests/channels/core/commands_test.cpp b/tests/channels/core/commands_test.cpp
new file mode 100644
index 000000000..e12cc559d
--- /dev/null
+++ b/tests/channels/core/commands_test.cpp
@@ -0,0 +1,75 @@
+#include <gtest/gtest.h>
+
+#include "channels/core/commands.hpp"
+
+// channels/core/commands:IM 内命令解析(纯逻辑)。识别的命令不进入对话;
+// 不认识的 /xxx 当作普通文本(可能是技能命令)。
+
+namespace acecode::channels::core {
+namespace {
+
+// 场景:用户发送各种已知命令,大小写混用、前后带空格、带参数。
+// 期望:识别为对应命令,参数去掉两端空白;/start 等同 /help,/session 与 /models 是别名。
+TEST(ChannelCommands, ParsesKnownCommands) {
+    EXPECT_EQ(parse_command("/help").kind, CommandKind::Help);
+    EXPECT_EQ(parse_command("/start").kind, CommandKind::Help);
+    EXPECT_EQ(parse_command("  /STATUS  ").kind, CommandKind::Status);
+    EXPECT_EQ(parse_command("/stop").kind, CommandKind::Stop);
+    EXPECT_EQ(parse_command("/new").kind, CommandKind::New);
+    EXPECT_EQ(parse_command("/session").kind, CommandKind::Sessions);
+    const auto search = parse_command("/sessions search  登录 bug ");
+    EXPECT_EQ(search.kind, CommandKind::Sessions);
+    EXPECT_EQ(search.argument, "search  登录 bug");
+    EXPECT_TRUE(search.error.empty());
+    EXPECT_EQ(parse_command("/sessions more").kind, CommandKind::Sessions);
+    const auto resume = parse_command("/resume 3");
+    EXPECT_EQ(resume.kind, CommandKind::Resume);
+    EXPECT_EQ(resume.argument, "3");
+    EXPECT_EQ(parse_command("/models").kind, CommandKind::Model);
+    EXPECT_EQ(parse_command("/model gpt-5").argument, "gpt-5");
+    EXPECT_EQ(parse_command("/approve abc").kind, CommandKind::Approve);
+    EXPECT_EQ(parse_command("/deny abc").kind, CommandKind::Deny);
+    EXPECT_EQ(parse_command("/aq 1 2").kind, CommandKind::Question);
+}
+
+// 场景:普通文字与不认识的斜杠命令(例如技能命令 /review)。
+// 期望:都不是通道命令,交给会话(技能命令随后按 Web 输入的规则展开)。
+TEST(ChannelCommands, UnknownSlashTextIsPlainInput) {
+    EXPECT_EQ(parse_command("你好").kind, CommandKind::None);
+    EXPECT_EQ(parse_command("/review 这个文件").kind, CommandKind::None);
+    EXPECT_EQ(parse_command("").kind, CommandKind::None);
+    EXPECT_EQ(parse_command("/statusbar").kind, CommandKind::None);
+}
+
+// 场景:命令缺参数或参数格式不对。
+// 期望:返回中文用法提示,由调用方直接回复给用户。
+TEST(ChannelCommands, ReportsUsageErrors) {
+    EXPECT_FALSE(parse_command("/resume").error.empty());
+    EXPECT_FALSE(parse_command("/approve").error.empty());
+    EXPECT_FALSE(parse_command("/deny a b").error.empty());
+    EXPECT_FALSE(parse_command("/sessions everything").error.empty());
+    EXPECT_TRUE(parse_command("/sessions all").error.empty());
+}
+
+// 场景:会话正在执行时收到各种命令。
+// 期望:只有 /new 与 /resume 需要等待或先 /stop,其余命令立即处理。
+TEST(ChannelCommands, OnlyNewAndResumeWaitForIdle) {
+    EXPECT_FALSE(runs_while_busy(CommandKind::New));
+    EXPECT_FALSE(runs_while_busy(CommandKind::Resume));
+    for (const auto kind : {CommandKind::Help, CommandKind::Status, CommandKind::Stop, CommandKind::Sessions,
+                            CommandKind::Model, CommandKind::Approve, CommandKind::Deny, CommandKind::Question})
+        EXPECT_TRUE(runs_while_busy(kind));
+}
+
+// 场景:机主与普通联系人分别发送 /help。
+// 期望:普通联系人的帮助额外说明只能切换自己创建的会话;权限提示附带 /approve 与 /deny 用法。
+TEST(ChannelCommands, HelpAndPromptsAreChinese) {
+    EXPECT_EQ(texts::help(true).find("只能在自己创建的会话"), std::string::npos);
+    EXPECT_NE(texts::help(false).find("只能在自己创建的会话"), std::string::npos);
+    const auto prompt = texts::permission_prompt("p1", "bash", "{\"command\":\"ls\"}");
+    EXPECT_NE(prompt.find("/approve p1"), std::string::npos);
+    EXPECT_NE(prompt.find("/deny p1"), std::string::npos);
+}
+
+} // namespace
+} // namespace acecode::channels::core
diff --git a/tests/channels/core/host_test.cpp b/tests/channels/core/host_test.cpp
new file mode 100644
index 000000000..12feff919
--- /dev/null
+++ b/tests/channels/core/host_test.cpp
@@ -0,0 +1,473 @@
+#include <gtest/gtest.h>
+
+#include "channels/core/host.hpp"
+#include "test_support/channels/core_fakes.hpp"
+#include "test_support/im/fake_qq_server.hpp"
+
+#include <filesystem>
+#include <fstream>
+#include <memory>
+
+// channels/core/host + platform_runtime:平台宿主的生命周期。传输层用假实现(由工厂注入),
+// QQ 扫码流程对接本机假门户;两个宿主在同一临时目录里争用归属锁。
+
+namespace acecode::channels::core {
+namespace {
+
+using test::FakeSessions;
+using test::FakeTransport;
+using test::message;
+using test::private_address;
+using test::wait_until;
+
+constexpr const char* kSecretB64 = "ZGVmZ2hpamtsbW5vOWrzEhyaIrNNBzyavxFHGfpv4JwMQcJAlM16v321wbiQ0njyP4fhqnk=";
+
+std::string fixed_key() {
+    std::string key;
+    for (int i = 0; i < 32; ++i) key.push_back(static_cast<char>(i));
+    return key;
+}
+
+class ChannelHostTest : public ::testing::Test {
+protected:
+    void SetUp() override {
+        home_dir = channels::test::temporary("host");
+        std::filesystem::create_directories(home_dir);
+        home = std::make_unique<channels::test::Home>(home_dir);
+        root = home_dir / "channels";
+    }
+    void TearDown() override {
+        home.reset();
+        std::error_code ec;
+        std::filesystem::remove_all(home_dir, ec);
+    }
+
+    HostServices services(std::int64_t pid = 1111) {
+        HostServices s;
+        s.conversation.sessions = &sessions;
+        s.conversation.pending_permissions = [](const std::string&) { return std::vector<nlohmann::json>{}; };
+        s.conversation.session_cwd = [this](const std::string& id) {
+            std::lock_guard<std::mutex> lock(sessions.mu);
+            return sessions.sessions[id].cwd;
+        };
+        s.conversation.catalog = [this](const std::optional<std::string>&) { return sessions.catalog(); };
+        s.conversation.resume_target = [this](const rc::RcSessionTarget& target) {
+            return sessions.resume_session(target.session_id, {});
+        };
+        s.broadcast = [this](const std::string& type, const nlohmann::json& payload) {
+            std::lock_guard<std::mutex> lock(mu);
+            events.emplace_back(type, payload);
+        };
+        s.current_pid = [pid] { return pid; };
+        s.standby_retry = std::chrono::milliseconds(30);
+        s.make_transport = [this](const std::string& platform, const PlatformConfig& config, ChannelStore&) {
+            auto transport = std::make_shared<FakeTransport>(platform);
+            transport->account = platform == "qq" ? config.credentials.value("app_id", std::string{}) : "100";
+            if (platform == "telegram") transport->extra = {{"username", "ace_bot"}};
+            std::lock_guard<std::mutex> lock(mu);
+            made.push_back(transport);
+            return transport;
+        };
+        s.validate_credentials = [this](const std::string&, const nlohmann::json& credentials, std::string* error) {
+            std::lock_guard<std::mutex> lock(mu);
+            validated.push_back(credentials);
+            if (reject_credentials) {
+                *error = "凭据无效";
+                return nlohmann::json(nullptr);
+            }
+            return credentials;
+        };
+        s.bind.portal_base = qq.base();
+        s.bind.connect_base = "https://q.qq.com";
+        s.bind.use_proxy = false;
+        s.bind.poll_interval = std::chrono::milliseconds(20);
+        s.bind.total_timeout = std::chrono::seconds(5);
+        s.bind.key_provider = fixed_key;
+        return s;
+    }
+
+    std::shared_ptr<FakeTransport> latest(const std::string& platform) {
+        std::lock_guard<std::mutex> lock(mu);
+        for (auto it = made.rbegin(); it != made.rend(); ++it)
+            if ((*it)->platform() == platform) return *it;
+        return nullptr;
+    }
+    std::size_t made_count() {
+        std::lock_guard<std::mutex> lock(mu);
+        return made.size();
+    }
+    std::vector<nlohmann::json> events_of(const std::string& type) {
+        std::lock_guard<std::mutex> lock(mu);
+        std::vector<nlohmann::json> out;
+        for (const auto& [name, payload] : events)
+            if (name == type) out.push_back(payload);
+        return out;
+    }
+    static nlohmann::json platform_of(const ChannelHost& host, const std::string& name) {
+        const auto snapshot = host.snapshot();  // 先存下来:range-for 不延长临时对象子对象的生命周期
+        for (const auto& item : snapshot["platforms"])
+            if (item.value("platform", "") == name) return item;
+        return nlohmann::json::object();
+    }
+    // 快照里可为 null 的字段(如 owner)按空串读。
+    static std::string text(const nlohmann::json& object, const char* key) {
+        return object.contains(key) && object[key].is_string() ? object[key].get<std::string>() : std::string{};
+    }
+    // Telegram 配好凭据、设机主 user:1 并打开开关。
+    void connect_telegram(ChannelHost& host) {
+        host.platform("telegram").set_credentials({{"token", "100:abcdefgh1234"}});
+        host.platform("telegram").set_owner("user:1", "机主");
+        host.platform("telegram").set_enabled(true);
+    }
+
+    std::filesystem::path home_dir, root;
+    std::unique_ptr<channels::test::Home> home;
+    FakeSessions sessions;
+    acecode::test::FakeQqServer qq;
+    std::mutex mu;
+    std::vector<std::pair<std::string, nlohmann::json>> events;
+    std::vector<std::shared_ptr<FakeTransport>> made;
+    std::vector<nlohmann::json> validated;
+    bool reject_credentials = false;
+};
+
+// 场景:新平台没有凭据时打开开关;保存凭据后打开、再关闭。
+// 期望:无凭据时拒绝打开;打开立即连接(无需保存),关闭立即断开并持久化开关状态;
+// 快照里的凭据只显示尾号;每次变化都推送 channels_state。
+TEST_F(ChannelHostTest, ToggleConnectsAndDisconnectsImmediately) {
+    ChannelHost host(root, services());
+    host.start();
+    EXPECT_EQ(platform_of(host, "telegram").value("state", ""), "unconfigured");
+    EXPECT_THROW(host.platform("telegram").set_enabled(true), std::runtime_error);
+
+    host.platform("telegram").set_credentials({{"token", "100:abcdefgh1234"}});
+    auto snapshot = platform_of(host, "telegram");
+    EXPECT_EQ(snapshot.value("state", ""), "disabled");
+    EXPECT_EQ(snapshot.value("credential_hint", ""), "****1234");
+    EXPECT_EQ(host.snapshot().dump().find("abcdefgh1234"), std::string::npos);
+
+    host.platform("telegram").set_enabled(true);
+    const auto transport = latest("telegram");
+    ASSERT_TRUE(transport);
+    EXPECT_EQ(transport->starts, 1);
+    EXPECT_EQ(platform_of(host, "telegram").value("state", ""), "connected");
+
+    host.platform("telegram").set_enabled(false);
+    EXPECT_EQ(transport->stops, 1);
+    EXPECT_EQ(platform_of(host, "telegram").value("state", ""), "disabled");
+    EXPECT_FALSE(events_of("channels_state").empty());
+    host.stop();
+
+    ChannelStore store(root / "telegram");
+    store.load();
+    EXPECT_FALSE(store.config().enabled);
+    EXPECT_EQ(store.config().credentials.value("token", ""), "100:abcdefgh1234");
+}
+
+// 场景:手动保存的凭据校验失败;已保存凭据后只改一个字段。
+// 期望:校验失败不保存并带原因;缺失的字段沿用已保存的值再校验。
+TEST_F(ChannelHostTest, CredentialsAreValidatedAndMerged) {
+    ChannelHost host(root, services());
+    host.start();
+    host.platform("qq").set_credentials({{"app_id", "A1"}, {"app_secret", "secret-1"}});
+    reject_credentials = true;
+    try {
+        host.platform("qq").set_credentials({{"app_secret", "wrong"}});
+        FAIL() << "校验失败应当抛异常";
+    } catch (const std::runtime_error& e) {
+        EXPECT_STREQ(e.what(), "凭据无效");
+    }
+    EXPECT_EQ(platform_of(host, "qq").value("credential_hint", ""), "****et-1");
+    reject_credentials = false;
+    host.platform("qq").set_credentials({{"app_secret", "secret-2"}});
+    {
+        std::lock_guard<std::mutex> lock(mu);
+        EXPECT_EQ(validated.back().value("app_id", ""), "A1");
+    }
+    EXPECT_EQ(platform_of(host, "qq").value("app_id", ""), "A1");
+    host.stop();
+}
+
+// 场景:传输层报告网络中断后进入重试,随后报告鉴权失败并停止重试。
+// 期望:页面状态依次为 retrying(附原因)与 failed(retry_stopped),并推送给页面。
+TEST_F(ChannelHostTest, TransportStatusIsPublished) {
+    ChannelHost host(root, services());
+    host.start();
+    connect_telegram(host);
+    const auto transport = latest("telegram");
+    transport->report(im::LinkState::Retrying, "网络中断");
+    auto snapshot = platform_of(host, "telegram");
+    EXPECT_EQ(snapshot.value("state", ""), "retrying");
+    EXPECT_EQ(snapshot.value("detail", ""), "网络中断");
+    bool pushed = false;
+    for (const auto& event : events_of("channels_state"))
+        if (event.value("state", "") == "retrying") pushed = true;
+    EXPECT_TRUE(pushed);
+    host.stop();
+}
+
+// 场景:平台明确拒绝凭据,传输层停止重试;用户再次打开开关。
+// 期望:页面显示 failed 与原因;再次打开开关会重建连接。
+TEST_F(ChannelHostTest, ReenablingAfterFatalErrorReconnects) {
+    ChannelHost host(root, services());
+    host.start();
+    connect_telegram(host);
+    latest("telegram")->report(im::LinkState::Failed, "Token 无效");
+    auto snapshot = platform_of(host, "telegram");
+    EXPECT_EQ(snapshot.value("state", ""), "failed");
+    EXPECT_EQ(snapshot.value("detail", ""), "Token 无效");
+    EXPECT_EQ(made_count(), 1u);
+    host.platform("telegram").set_enabled(true);
+    EXPECT_EQ(made_count(), 2u);
+    EXPECT_EQ(platform_of(host, "telegram").value("state", ""), "connected");
+    host.stop();
+}
+
+// 场景:两个 daemon 进程(这里是两个宿主)都开启了同一个 Telegram 机器人。
+// 期望:先取得归属锁的宿主连接;另一个进入待命并显示托管进程的 PID;
+// 持有者退出后,待命宿主在有限时间内接管连接。
+TEST_F(ChannelHostTest, SecondHostWaitsAndTakesOver) {
+    auto first = std::make_unique<ChannelHost>(root, services(1111));
+    first->start();
+    connect_telegram(*first);
+    ASSERT_EQ(platform_of(*first, "telegram").value("state", ""), "connected");
+
+    ChannelHost second(root, services(2222));
+    second.start();
+    auto waiting = platform_of(second, "telegram");
+    EXPECT_EQ(waiting.value("state", ""), "standby");
+    EXPECT_EQ(waiting.value("hosted_by_pid", 0), 1111);
+    EXPECT_EQ(made_count(), 1u);  // 待命期间不建立第二个连接
+
+    first->stop();
+    first.reset();
+    EXPECT_TRUE(wait_until([&] { return platform_of(second, "telegram").value("state", "") == "connected"; }));
+    EXPECT_EQ(made_count(), 2u);
+    second.stop();
+}
+
+// 场景:开启状态下 daemon 重启;重启前已有一个会话绑定。
+// 期望:新宿主启动后自动连接,绑定保留,并为绑定恢复出站投影(先恢复会话)。
+TEST_F(ChannelHostTest, RestartReconnectsAndRestoresBindings) {
+    std::string bound;
+    {
+        ChannelHost host(root, services());
+        host.start();
+        connect_telegram(host);
+        latest("telegram")->inject(message(private_address("1"), "你好", "m1"));
+        ASSERT_TRUE(wait_until([&] { return !sessions.input_log().empty(); }));
+        bound = sessions.input_log()[0].first;
+        host.stop();
+    }
+    sessions.resumed.clear();
+    ChannelHost host(root, services());
+    host.start();
+    EXPECT_EQ(platform_of(host, "telegram").value("state", ""), "connected");
+    EXPECT_EQ(host.bound_sessions().at(bound), "telegram");
+    EXPECT_TRUE(wait_until([&] {
+        std::lock_guard<std::mutex> lock(sessions.mu);
+        return std::find(sessions.resumed.begin(), sessions.resumed.end(), bound) != sessions.resumed.end();
+    }));
+    // 恢复会话之后才订阅事件:等订阅建立再模拟 Desktop 里产生的回复。
+    ASSERT_TRUE(wait_until([&] { return sessions.listener_count(bound) == 1; }));
+    sessions.assistant(bound, "Desktop 里输入后的回复");
+    EXPECT_TRUE(latest("telegram")->wait_said("Desktop 里输入后的回复"));
+    host.stop();
+}
+
+// 场景:Telegram 的 config.json 被写坏。
+// 期望:该平台显示 error 与原因,开关操作被拒绝;另一个平台不受影响。
+TEST_F(ChannelHostTest, CorruptConfigBlocksOnlyThatPlatform) {
+    std::filesystem::create_directories(root / "telegram");
+    std::ofstream(root / "telegram" / "config.json", std::ios::binary) << "{oops";
+    ChannelHost host(root, services());
+    host.start();
+    const auto broken = platform_of(host, "telegram");
+    EXPECT_EQ(broken.value("state", ""), "error");
+    EXPECT_NE(broken.value("detail", "").find("损坏"), std::string::npos);
+    EXPECT_THROW(host.platform("telegram").set_enabled(true), std::runtime_error);
+    EXPECT_EQ(platform_of(host, "qq").value("state", ""), "unconfigured");
+    host.stop();
+}
+
+// 场景:平台还没有机主,陌生人私聊;机主在设置页批准。
+// 期望:推送 channels_request 并在快照里列出请求;批准后对方进入授权名单并成为机主。
+TEST_F(ChannelHostTest, PendingRequestsAreBroadcastAndApproved) {
+    ChannelHost host(root, services());
+    host.start();
+    host.platform("telegram").set_credentials({{"token", "100:abcdefgh1234"}});
+    host.platform("telegram").set_enabled(true);
+    latest("telegram")->inject(message(private_address("9"), "你好", "m1"));
+    ASSERT_TRUE(wait_until([&] { return !events_of("channels_request").empty(); }));
+    const auto request = events_of("channels_request")[0];
+    EXPECT_EQ(request.value("kind", ""), "user");
+    const auto pending = platform_of(host, "telegram")["pending"];
+    ASSERT_EQ(pending.size(), 1u);
+    EXPECT_EQ(pending[0].value("label", ""), "Telegram 私聊");
+    EXPECT_THROW(host.platform("telegram").approve("no-such-id", true), std::runtime_error);
+    host.platform("telegram").approve(request.value("id", ""), true);
+    const auto snapshot = platform_of(host, "telegram");
+    EXPECT_EQ(text(snapshot, "owner"), "user:9");
+    EXPECT_TRUE(snapshot["pending"].empty());
+    ASSERT_EQ(snapshot["contacts"].size(), 1u);
+    EXPECT_TRUE(snapshot["contacts"][0].value("owner", false));
+    host.stop();
+}
+
+// 场景:机主撤销一位联系人的授权时,对方的会话正在执行,随后对方又发消息。
+// 期望:当前回合被中止;之后的消息只得到配对提示,不再进入会话。
+TEST_F(ChannelHostTest, RevokeAbortsAndStopsProcessing) {
+    ChannelHost host(root, services());
+    host.start();
+    connect_telegram(host);
+    const auto transport = latest("telegram");
+    transport->inject(message(private_address("2"), "申请", "m1"));
+    ASSERT_TRUE(wait_until([&] { return !events_of("channels_request").empty(); }));
+    host.platform("telegram").approve(events_of("channels_request")[0].value("id", ""), true);
+    EXPECT_EQ(text(platform_of(host, "telegram"), "owner"), "user:1");  // 已有机主,不会被替换
+    transport->inject(message(private_address("2"), "开始干活", "m2"));
+    ASSERT_TRUE(wait_until([&] { return sessions.input_log().size() == 1; }));
+    const auto id = sessions.input_log()[0].first;
+    host.platform("telegram").revoke("user:2");
+    EXPECT_EQ(sessions.abort_log(), std::vector<std::string>{id});
+    transport->inject(message(private_address("2"), "还能用吗", "m3"));
+    EXPECT_TRUE(wait_until([&] {
+        std::size_t notices = 0;
+        for (const auto& text : transport->texts())
+            if (text.find("还没有被授权") != std::string::npos) ++notices;
+        return notices == 2;
+    }));
+    EXPECT_EQ(sessions.input_log().size(), 1u);
+    host.stop();
+}
+
+// 场景:Telegram 未连接时生成机主链接;连接后生成链接,由某人点开发送 /start <码>。
+// 期望:未连接时报错;链接指向机器人用户名并带 24 位一次性码;对方成为机主并收到确认;
+// 已有机主后不能再生成链接。
+TEST_F(ChannelHostTest, TelegramOwnerLinkClaimsOwner) {
+    ChannelHost host(root, services());
+    host.start();
+    EXPECT_THROW(host.owner_link("telegram"), std::runtime_error);
+    host.platform("telegram").set_credentials({{"token", "100:abcdefgh1234"}});
+    host.platform("telegram").set_enabled(true);
+    const auto link = host.owner_link("telegram");
+    const std::string prefix = "https://t.me/ace_bot?start=";
+    const auto url = link.value("link", "");
+    ASSERT_EQ(url.rfind(prefix, 0), 0u) << url;
+    const auto code = url.substr(prefix.size());
+    EXPECT_EQ(code.size(), 24u);
+    EXPECT_EQ(link.value("expires_in_s", 0), 600);
+
+    auto start = message(private_address("5"), "/start " + code, "m1");
+    start.start_code = code;
+    latest("telegram")->inject(start);
+    ASSERT_TRUE(wait_until([&] { return text(platform_of(host, "telegram"), "owner") == "user:5"; }));
+    EXPECT_TRUE(latest("telegram")->wait_said("已绑定为机主"));
+    EXPECT_TRUE(sessions.input_log().empty());  // /start 本身不进会话
+    EXPECT_THROW(host.owner_link("telegram"), std::runtime_error);
+    host.stop();
+}
+
+// 场景:页面确认移除 Telegram webhook。
+// 期望:操作转交给当前传输层;未连接时报错。
+TEST_F(ChannelHostTest, PlatformActionsReachTheTransport) {
+    ChannelHost host(root, services());
+    host.start();
+    EXPECT_THROW(host.platform("telegram").action("remove_webhook", nlohmann::json::object()), std::runtime_error);
+    connect_telegram(host);
+    host.platform("telegram").action("remove_webhook", nlohmann::json::object());
+    EXPECT_EQ(latest("telegram")->actions, std::vector<std::string>{"remove_webhook"});
+    EXPECT_THROW(host.platform("wechat"), std::invalid_argument);
+    host.stop();
+}
+
+// 场景:用户点击“扫码连接”,用手机 QQ 扫码确认,绑定服务返回扫码人身份。
+// 期望:页面先收到二维码,完成后保存 AppID/AppSecret、扫码人成为机主、QQ 开关自动打开并连接;
+// 快照与推送里都不含 AppSecret。
+TEST_F(ChannelHostTest, QqScanBindSavesCredentialsAndConnects) {
+    int polls = 0;
+    qq.poll_bind_handler = [&](const nlohmann::json&) {
+        if (++polls < 2) return nlohmann::json{{"retcode", 0}, {"data", {{"status", 1}}}};
+        return nlohmann::json{{"retcode", 0},
+                              {"data", {{"status", 2}, {"bot_appid", 102030405},
+                                        {"bot_encrypt_secret", kSecretB64}, {"user_openid", "OWNER1"}}}};
+    };
+    ChannelHost host(root, services());
+    host.start();
+    EXPECT_EQ(host.start_bind("qq").value("phase", ""), "starting");
+    ASSERT_TRUE(wait_until([&] { return host.bind_state("qq").value("phase", "") == "completed"; }));
+    const auto snapshot = platform_of(host, "qq");
+    EXPECT_TRUE(snapshot.value("enabled", false));
+    EXPECT_EQ(snapshot.value("app_id", ""), "102030405");
+    EXPECT_EQ(text(snapshot, "owner"), "user:OWNER1");
+    EXPECT_EQ(snapshot.value("state", ""), "connected");
+    bool saw_qr = false;
+    for (const auto& event : events_of("channels_bind")) {
+        EXPECT_EQ(event.dump().find("qq-test-secret"), std::string::npos);
+        if (event.value("phase", "") == "waiting")
+            saw_qr = event.value("qr_url", "").find("source=acecode") != std::string::npos;
+    }
+    EXPECT_TRUE(saw_qr);
+    EXPECT_EQ(host.snapshot().dump().find("qq-test-secret"), std::string::npos);
+    host.stop();
+}
+
+// 场景:扫码流程进行中用户点了取消;以及流程进行中重复发起。
+// 期望:重复发起被拒绝;取消后状态为 cancelled,QQ 配置与开关保持原样。
+TEST_F(ChannelHostTest, QqScanCancelKeepsExistingConfig) {
+    qq.poll_bind_handler = [](const nlohmann::json&) { return nlohmann::json{{"retcode", 0}, {"data", {{"status", 1}}}}; };
+    ChannelHost host(root, services());
+    host.start();
+    host.start_bind("qq");
+    ASSERT_TRUE(wait_until([&] { return host.bind_state("qq").value("phase", "") == "waiting"; }));
+    EXPECT_THROW(host.start_bind("qq"), std::runtime_error);
+    host.cancel_bind("qq");
+    ASSERT_TRUE(wait_until([&] { return host.bind_state("qq").value("phase", "") == "cancelled"; }));
+    const auto snapshot = platform_of(host, "qq");
+    EXPECT_FALSE(snapshot.value("configured", true));
+    EXPECT_FALSE(snapshot.value("enabled", true));
+    host.stop();
+}
+
+// 场景:QQ 换成另一个机器人(AppID 变化);以及同一机器人重新保存凭据。
+// 期望:换机器人时清空机主与授权名单(QQ 的用户 openid 按机器人隔离);同一机器人保持不变。
+TEST_F(ChannelHostTest, ChangingQqBotClearsPerBotIdentities) {
+    ChannelHost host(root, services());
+    host.start();
+    auto& qq_runtime = host.platform("qq");
+    qq_runtime.set_credentials({{"app_id", "A1"}, {"app_secret", "secret-1"}});
+    qq_runtime.set_owner("user:OWNER1", "");
+    qq_runtime.set_credentials({{"app_id", "A1"}, {"app_secret", "secret-2"}});
+    EXPECT_EQ(text(platform_of(host, "qq"), "owner"), "user:OWNER1");
+    qq_runtime.set_credentials({{"app_id", "A2"}, {"app_secret", "secret-3"}});
+    const auto snapshot = platform_of(host, "qq");
+    EXPECT_TRUE(snapshot["owner"].is_null());
+    EXPECT_TRUE(snapshot["contacts"].empty());
+    host.stop();
+}
+
+// 场景:机主在 QQ 里 /resume 一个当前绑定在 Telegram 私聊上的会话。
+// 期望:绑定转到 QQ;Telegram 私聊收到转移提示;已绑定会话的归属变为 qq。
+TEST_F(ChannelHostTest, ResumeTransfersBindingAcrossPlatforms) {
+    ChannelHost host(root, services());
+    host.start();
+    connect_telegram(host);
+    host.platform("qq").set_credentials({{"app_id", "A1"}, {"app_secret", "secret-1"}});
+    host.platform("qq").set_owner("user:Q1", "机主");
+    host.platform("qq").set_enabled(true);
+    latest("telegram")->inject(message(private_address("1"), "你好", "m1"));
+    ASSERT_TRUE(wait_until([&] { return sessions.input_log().size() == 1; }));
+    const auto id = sessions.input_log()[0].first;
+    EXPECT_EQ(host.bound_sessions().at(id), "telegram");
+    latest("qq")->inject(message(private_address("Q1", "qq", "A1"), "/resume " + id, "q1"));
+    EXPECT_TRUE(latest("telegram")->wait_said("当前会话已转到QQ 私聊"));
+    EXPECT_TRUE(wait_until([&] {
+        const auto bound = host.bound_sessions();
+        return bound.count(id) && bound.at(id) == "qq";
+    }));
+    EXPECT_TRUE(latest("qq")->wait_said("已切换到会话"));
+    host.stop();
+}
+
+} // namespace
+} // namespace acecode::channels::core
diff --git a/tests/channels/core/line_webhook_server_test.cpp b/tests/channels/core/line_webhook_server_test.cpp
new file mode 100644
index 000000000..157cf4ca5
--- /dev/null
+++ b/tests/channels/core/line_webhook_server_test.cpp
@@ -0,0 +1,161 @@
+#include <gtest/gtest.h>
+
+#include "channels/core/line_webhook_server.hpp"
+#include "im/http.hpp"
+#include "im/line/line_tunnel.hpp"
+
+#include <atomic>
+#include <memory>
+#include <mutex>
+#include <vector>
+
+// channels/core/line_webhook_server:LINE 回调端口(Crow)。
+// 覆盖:只监听 127.0.0.1 的三条路由、原始请求体与签名头原样交给处理函数、其它路径 404、
+// 停止后释放处理函数并可再次启动、固定端口。
+
+namespace acecode::channels::core {
+namespace {
+
+using im::line::ListenerReply;
+using im::line::ListenerRequest;
+
+struct Recorder {
+    std::mutex mu;
+    std::vector<ListenerRequest> requests;
+
+    std::size_t count() {
+        std::lock_guard<std::mutex> lock(mu);
+        return requests.size();
+    }
+    ListenerRequest at(std::size_t i) {
+        std::lock_guard<std::mutex> lock(mu);
+        return requests.at(i);
+    }
+};
+
+im::line::ListenerHandler recording_handler(const std::shared_ptr<Recorder>& recorder) {
+    return [recorder](const ListenerRequest& request) {
+        {
+            std::lock_guard<std::mutex> lock(recorder->mu);
+            recorder->requests.push_back(request);
+        }
+        ListenerReply reply;
+        reply.status = 200;
+        reply.content_type = "application/json";
+        reply.body = R"({"path":")" + request.path + R"("})";
+        reply.headers = {{"Cache-Control", "no-store"}};
+        return reply;
+    };
+}
+
+im::HttpResponse send(const std::string& method, const std::string& url, const std::string& body = {},
+                      std::vector<std::pair<std::string, std::string>> headers = {}) {
+    im::HttpRequest request;
+    request.method = method;
+    request.url = url;
+    request.body = body;
+    request.headers = std::move(headers);
+    request.timeout = std::chrono::seconds(5);
+    request.use_proxy = false;
+    return im::http_send(request);
+}
+
+// 场景:启动回调端口,依次发 webhook(带签名头,请求体含中文与换行)、健康检查、媒体请求。
+// 期望:系统分配端口;处理函数拿到的方法、路径、原始请求体(逐字节一致)与签名头都正确;
+// 处理函数的状态码、类型与头原样返回。
+TEST(LineWebhookServer, ForwardsTheThreeRoutesVerbatim) {
+    auto recorder = std::make_shared<Recorder>();
+    LineWebhookServer server;
+    std::string error;
+    const auto port = server.start(0, recording_handler(recorder), &error);
+    ASSERT_NE(port, 0) << error;
+    EXPECT_EQ(server.port(), port);
+    const auto base = "http://127.0.0.1:" + std::to_string(port);
+
+    const std::string body = "{\"events\":[],\n\"text\":\"\xE4\xBD\xA0\xE5\xA5\xBD\"}";
+    auto response = send("POST", base + "/line/webhook", body, {{"x-line-signature", "SIG=="}});
+    EXPECT_EQ(response.status, 200);
+    EXPECT_EQ(response.body, R"({"path":"/line/webhook"})");
+    response = send("GET", base + "/line/health");
+    EXPECT_EQ(response.status, 200);
+    response = send("GET", base + "/line/media/tok123/a.png");
+    EXPECT_EQ(response.status, 200);
+
+    ASSERT_EQ(recorder->count(), 3u);
+    EXPECT_EQ(recorder->at(0).method, "POST");
+    EXPECT_EQ(recorder->at(0).path, "/line/webhook");
+    EXPECT_EQ(recorder->at(0).body, body);
+    EXPECT_EQ(recorder->at(0).signature, "SIG==");
+    EXPECT_EQ(recorder->at(1).path, "/line/health");
+    EXPECT_EQ(recorder->at(2).method, "GET");
+    EXPECT_EQ(recorder->at(2).path, "/line/media/tok123/a.png");
+    server.stop();
+}
+
+// 场景:请求不在白名单里的路径(API、主 Web 页面风格的路径、媒体多级路径),或用错方法。
+// 期望:404 / 405,处理函数一次都不会被调用 —— 经隧道暴露的端口不能多出任何入口。
+TEST(LineWebhookServer, EverythingElseIsRejected) {
+    auto recorder = std::make_shared<Recorder>();
+    LineWebhookServer server;
+    std::string error;
+    const auto port = server.start(0, recording_handler(recorder), &error);
+    ASSERT_NE(port, 0) << error;
+    const auto base = "http://127.0.0.1:" + std::to_string(port);
+    EXPECT_EQ(send("GET", base + "/").status, 404);
+    EXPECT_EQ(send("GET", base + "/api/sessions").status, 404);
+    EXPECT_EQ(send("POST", base + "/api/pty", "{}").status, 404);
+    EXPECT_EQ(send("GET", base + "/line/media/a/b/c").status, 404);
+    EXPECT_NE(send("GET", base + "/line/webhook").status, 200);
+    EXPECT_NE(send("POST", base + "/line/health", "{}").status, 200);
+    EXPECT_EQ(recorder->count(), 0u);
+}
+
+// 场景:停止回调端口后再请求;随后再次启动。
+// 期望:停止后端口不可达、port() 为 0、处理函数(及其捕获的对象)被释放;可以重新启动并正常工作。
+TEST(LineWebhookServer, StopReleasesHandlerAndAllowsRestart) {
+    auto recorder = std::make_shared<Recorder>();
+    auto sentinel = std::make_shared<int>(7);
+    std::weak_ptr<int> weak = sentinel;
+    LineWebhookServer server;
+    std::string error;
+    auto handler = recording_handler(recorder);
+    const auto port = server.start(
+        0,
+        [handler, sentinel](const ListenerRequest& request) { return handler(request); }, &error);
+    sentinel.reset();
+    ASSERT_NE(port, 0) << error;
+    EXPECT_FALSE(weak.expired());
+    server.stop();
+    EXPECT_EQ(server.port(), 0);
+    EXPECT_TRUE(weak.expired());
+    EXPECT_EQ(send("GET", "http://127.0.0.1:" + std::to_string(port) + "/line/health").status, 0);
+
+    const auto again = server.start(0, recording_handler(recorder), &error);
+    ASSERT_NE(again, 0) << error;
+    EXPECT_EQ(send("GET", "http://127.0.0.1:" + std::to_string(again) + "/line/health").status, 200);
+}
+
+// 场景:用户自己的反向代理指向固定端口,回调端口按该端口启动。
+// 期望:返回的就是指定端口,并能在其上收到请求。
+TEST(LineWebhookServer, HonorsFixedPort) {
+    const auto wanted = im::line::pick_free_loopback_port();
+    ASSERT_NE(wanted, 0);
+    auto recorder = std::make_shared<Recorder>();
+    LineWebhookServer server;
+    std::string error;
+    ASSERT_EQ(server.start(wanted, recording_handler(recorder), &error), wanted) << error;
+    EXPECT_EQ(send("GET", "http://127.0.0.1:" + std::to_string(wanted) + "/line/health").status, 200);
+}
+
+// 场景:缺少处理函数。
+// 期望:拒绝启动并给出原因,不会开出一个没人处理的端口。
+TEST(LineWebhookServer, RefusesToStartWithoutHandler) {
+    LineWebhookServer server;
+    std::string error;
+    EXPECT_EQ(server.start(0, {}, &error), 0);
+    EXPECT_FALSE(error.empty());
+    EXPECT_EQ(server.port(), 0);
+}
+
+} // namespace
+} // namespace acecode::channels::core
diff --git a/tests/channels/core/outbound_test.cpp b/tests/channels/core/outbound_test.cpp
new file mode 100644
index 000000000..fdbcc74e6
--- /dev/null
+++ b/tests/channels/core/outbound_test.cpp
@@ -0,0 +1,209 @@
+#include <gtest/gtest.h>
+
+#include "channels/core/projection.hpp"
+#include "session/attachment_store.hpp"
+#include "session/session_storage.hpp"
+#include "test_support/channels/core_fakes.hpp"
+
+#include <filesystem>
+#include <fstream>
+#include <memory>
+#include <thread>
+
+// channels/core/projection:一个绑定的出站投影。订阅会话事件,把助手文本、附件、
+// 权限请求与提问发到 IM;发送在 RemoteControlHub 的后台线程进行,断言前等待。
+
+namespace acecode::channels::core {
+namespace {
+
+using test::FakeSessions;
+using test::FakeTransport;
+using test::private_address;
+using test::wait_until;
+
+class ChannelOutbound : public ::testing::Test {
+protected:
+    void SetUp() override {
+        home_dir = channels::test::temporary("outbound");
+        std::filesystem::create_directories(home_dir);
+        home = std::make_unique<channels::test::Home>(home_dir);
+        sessions.add_session("s-1", cwd, "", true, "测试会话");
+    }
+    void TearDown() override {
+        if (projection) projection->stop();
+        projection.reset();
+        home.reset();
+        std::error_code ec;
+        std::filesystem::remove_all(home_dir, ec);
+    }
+    void start(im::Capabilities caps = {}) {
+        transport = std::make_shared<FakeTransport>("telegram", caps);
+        slot->set(transport);
+        BindingRecord record;
+        record.address = private_address("1");
+        record.session_id = "s-1";
+        record.cwd = cwd;
+        record.no_workspace = true;
+        projection = std::make_shared<Projection>(
+            record, ProjectionDeps{&sessions, slot, [this](const std::string&) { return pending; }});
+        projection->start();
+    }
+    void user(const nlohmann::json& metadata = nlohmann::json::object()) {
+        sessions.emit("s-1", SessionEventKind::Message, {{"role", "user"}, {"content", "问题"}, {"metadata", metadata}});
+    }
+
+    const std::string cwd = "C:/fake-no-workspace/s-1";
+    std::filesystem::path home_dir;
+    std::unique_ptr<channels::test::Home> home;
+    FakeSessions sessions;
+    std::shared_ptr<FakeTransport> transport;
+    std::shared_ptr<TransportSlot> slot = std::make_shared<TransportSlot>();
+    std::shared_ptr<Projection> projection;
+    std::vector<nlohmann::json> pending;
+};
+
+// 场景:一个回合里先有工具调用过程,最后是助手答复。
+// 期望:只发送助手文本,工具开始/进度不发送。
+TEST_F(ChannelOutbound, SendsAssistantTextButNotToolProgress) {
+    start();
+    user();
+    sessions.emit("s-1", SessionEventKind::ToolStart, {{"tool", "bash"}, {"args", {{"command", "ls"}}}});
+    sessions.emit("s-1", SessionEventKind::ToolUpdate, {{"tool", "bash"}, {"partial", "a.txt"}});
+    sessions.assistant("s-1", "最终答复");
+    ASSERT_TRUE(transport->wait_said("最终答复"));
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    EXPECT_EQ(transport->texts(), std::vector<std::string>{"最终答复"});
+}
+
+// 场景:平台声明按回合合并输出(QQ),一个回合内产生两段助手文本。
+// 期望:回合结束(忙碌变为空闲)前不发送;结束时合并成一条发出。
+TEST_F(ChannelOutbound, BatchesTurnOutputWhenPlatformAsks) {
+    im::Capabilities caps;
+    caps.batch_turn_output = true;
+    start(caps);
+    user();
+    sessions.assistant("s-1", "第一段");
+    sessions.assistant("s-1", "第二段");
+    std::this_thread::sleep_for(std::chrono::milliseconds(80));
+    EXPECT_EQ(transport->sent_count(), 0u);
+    sessions.emit("s-1", SessionEventKind::BusyChanged, {{"busy", false}});
+    ASSERT_TRUE(wait_until([&] { return transport->sent_count() == 1; }));
+    EXPECT_EQ(transport->texts()[0], "第一段\n\n第二段");
+}
+
+// 场景:用户消息来自 IM(带回复上下文),随后在 Desktop 里输入一条(不带通道信息)。
+// 期望:IM 那一回合的输出引用原消息;Desktop 输入那一回合的回复同样发到 IM,但不带引用。
+TEST_F(ChannelOutbound, ReplyContextFollowsTheTriggeringMessage) {
+    start();
+    user({{"channel", {{"platform", "telegram"}, {"reply_context", {{"msg_id", "m1"}}}}}});
+    sessions.assistant("s-1", "回复 IM");
+    ASSERT_TRUE(transport->wait_said("回复 IM"));
+    user();
+    sessions.assistant("s-1", "回复 Desktop");
+    ASSERT_TRUE(transport->wait_said("回复 Desktop"));
+    for (const auto& sent : transport->sent()) {
+        if (sent.text == "回复 IM") EXPECT_EQ(sent.context.value("msg_id", ""), "m1");
+        if (sent.text == "回复 Desktop") EXPECT_TRUE(sent.context.empty());
+    }
+}
+
+// 场景:投影启动前会话已有一个待确认的权限请求;之后又来一个请求并先在 Desktop 被处理。
+// 期望:启动时补发已有请求的提示;Desktop 处理后 IM 收到已处理提示,该编号不能再被 IM 取走。
+TEST_F(ChannelOutbound, PermissionPromptsAndFirstAnswerWins) {
+    pending = {{{"request_id", "p0"}, {"tool", "file_write"}, {"args", {{"path", "a.txt"}}}}};
+    start();
+    ASSERT_TRUE(transport->wait_said("/approve p0"));
+    sessions.emit("s-1", SessionEventKind::PermissionRequest, {{"request_id", "p1"}, {"tool", "bash"}});
+    ASSERT_TRUE(transport->wait_said("/approve p1"));
+    EXPECT_EQ(projection->pending_permission_ids(), (std::vector<std::string>{"p0", "p1"}));
+    sessions.emit("s-1", SessionEventKind::PermissionClosed, {{"request_id", "p1"}, {"choice", "allow"}});
+    EXPECT_TRUE(transport->wait_said("权限请求 p1 已处理"));
+    EXPECT_FALSE(projection->take_permission("p1"));
+    EXPECT_TRUE(projection->take_permission("p0"));
+    // 已关闭的请求重放不会再次提示
+    sessions.emit("s-1", SessionEventKind::PermissionRequest, {{"request_id", "p1"}, {"tool", "bash"}});
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    std::size_t prompts = 0;
+    for (const auto& text : transport->texts())
+        if (text.find("/approve p1") != std::string::npos) ++prompts;
+    EXPECT_EQ(prompts, 1u);
+}
+
+// 场景:会话发起 AskUserQuestion。
+// 期望:按 /aq 语法发到 IM。
+TEST_F(ChannelOutbound, QuestionsAreProjectedWithAqSyntax) {
+    start();
+    sessions.emit("s-1", SessionEventKind::QuestionRequest,
+                  {{"request_id", "q1"},
+                   {"questions",
+                    {{{"id", "target"},
+                      {"header", "部署"},
+                      {"text", "部署到哪?"},
+                      {"options", {{{"label", "测试"}}, {{"label", "正式"}}}}}}}});
+    EXPECT_TRUE(transport->wait_said("/aq"));
+    EXPECT_TRUE(transport->said("部署到哪?"));
+}
+
+// 场景:平台拒绝了一条输出,下一条正常。
+// 期望:失败计入统计,不重发;后续输出照常发送。
+TEST_F(ChannelOutbound, SendFailuresAreCountedNotRetried) {
+    start();
+    transport->fail_sends = 1;
+    sessions.assistant("s-1", "会失败");
+    ASSERT_TRUE(wait_until([&] { return projection->stats().outbound_failed == 1; }));
+    sessions.assistant("s-1", "会成功");
+    ASSERT_TRUE(transport->wait_said("会成功"));
+    EXPECT_FALSE(transport->said("会失败"));
+    EXPECT_EQ(projection->stats().outbound_failed, 1u);
+}
+
+// 场景:工具产出两个附件:一个在会话自己的附件目录里,一个是指向外部文件的引用;
+// 同一个附件在一个回合里出现两次。
+// 期望:前者以文件发送且只发一次;外部引用被拒绝并计入失败。
+TEST_F(ChannelOutbound, AttachmentsAreRevalidatedBeforeSending) {
+    start();
+    const auto project = SessionStorage::get_project_dir(cwd);
+    std::string error;
+    const auto stored = save_attachment(project, "s-1", "out.png", "image/png", "png-bytes", &error);
+    ASSERT_TRUE(stored.has_value()) << error;
+    const auto outside = home_dir / "outside.txt";
+    std::ofstream(outside, std::ios::binary) << "secret";
+    const auto reference =
+        save_attachment_reference(project, "s-1", "outside.txt", "text/plain", path_to_utf8(outside), &error);
+    ASSERT_TRUE(reference.has_value()) << error;
+    user();
+    sessions.emit("s-1", SessionEventKind::ToolEnd,
+                  {{"tool", "image_generate"},
+                   {"attachments", {{{"id", stored->id}}, {{"id", stored->id}}, {{"id", reference->id}}}}});
+    ASSERT_TRUE(wait_until([&] { return projection->stats().outbound_failed == 1; }));
+    ASSERT_TRUE(wait_until([&] { return transport->sent_count() == 1; }));
+    const auto sent = transport->sent();
+    EXPECT_EQ(sent[0].file, "out.png");
+}
+
+// 场景:平台支持“正在输入”,会话进入忙碌后又回到空闲。
+// 期望:忙碌时打开输入状态,空闲时关闭。
+TEST_F(ChannelOutbound, TypingFollowsBusyState) {
+    im::Capabilities caps;
+    caps.supports_typing = true;
+    start(caps);
+    sessions.emit("s-1", SessionEventKind::BusyChanged, {{"busy", true}});
+    sessions.emit("s-1", SessionEventKind::BusyChanged, {{"busy", false}});
+    ASSERT_GE(transport->typing.size(), 2u);
+    EXPECT_TRUE(transport->typing[0]);
+    EXPECT_FALSE(transport->typing.back());
+}
+
+// 场景:投影被停止(绑定转移或通道关闭)后,会话又产生输出。
+// 期望:已退订,不再发送任何东西。
+TEST_F(ChannelOutbound, StoppedProjectionSendsNothing) {
+    start();
+    projection->stop();
+    EXPECT_EQ(sessions.listener_count("s-1"), 0u);
+    sessions.assistant("s-1", "停止之后");
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+    EXPECT_EQ(transport->sent_count(), 0u);
+}
+
+} // namespace
+} // namespace acecode::channels::core
diff --git a/tests/channels/core/router_test.cpp b/tests/channels/core/router_test.cpp
new file mode 100644
index 000000000..9b9515bac
--- /dev/null
+++ b/tests/channels/core/router_test.cpp
@@ -0,0 +1,402 @@
+#include <gtest/gtest.h>
+
+#include "channels/core/conversations.hpp"
+#include "test_support/channels/core_fakes.hpp"
+
+#include <filesystem>
+#include <memory>
+
+// channels/core/conversations:IM 会话与 ACECode 会话的绑定路由。用内存版 SessionClient
+// 与假传输层驱动;回复经出站投影的后台线程发送,断言前等待。
+// 默认身份:Telegram 机器人 100,机主 user:1,已授权联系人 user:2,已批准群 -100。
+
+namespace acecode::channels::core {
+namespace {
+
+using test::FakeSessions;
+using test::FakeTransport;
+using test::group_address;
+using test::message;
+using test::private_address;
+using test::wait_until;
+
+class ChannelRouter : public ::testing::Test {
+protected:
+    void SetUp() override {
+        home_dir = channels::test::temporary("router");
+        std::filesystem::create_directories(home_dir);
+        home = std::make_unique<channels::test::Home>(home_dir);
+        transport = std::make_shared<FakeTransport>("telegram");
+        slot->set(transport);
+        open_store();
+        store->update_config([](PlatformConfig& config) {
+            config.enabled = true;
+            config.owner = "user:1";
+            config.access = {{"user:1", "", 0}, {"user:2", "", 0}, {"group:-100", "", 0}};
+        });
+        make_conversations();
+    }
+
+    void TearDown() override {
+        conversations.reset();
+        home.reset();
+        std::error_code ec;
+        std::filesystem::remove_all(home_dir, ec);
+    }
+
+    void open_store() {
+        store = std::make_unique<ChannelStore>(home_dir / "telegram");
+        store->load();
+    }
+
+    void make_conversations() {
+        ConversationDeps deps;
+        deps.sessions = &sessions;
+        deps.pending_permissions = [](const std::string&) { return std::vector<nlohmann::json>{}; };
+        deps.session_cwd = [this](const std::string& id) {
+            std::lock_guard<std::mutex> lock(sessions.mu);
+            return sessions.sessions[id].cwd;
+        };
+        deps.catalog = [this](const std::optional<std::string>& query) {
+            auto all = sessions.catalog();
+            if (!query) return all;
+            std::vector<rc::RcSessionTarget> hits;
+            for (const auto& target : all)
+                if (target.title.find(*query) != std::string::npos) hits.push_back(target);
+            return hits;
+        };
+        deps.resume_target = [this](const rc::RcSessionTarget& target) {
+            return sessions.resume_session(target.session_id, {});
+        };
+        deps.model_names = [] { return std::vector<std::string>{"fast", "smart"}; };
+        deps.switch_model = [this](const std::string& id, const std::string& name, std::string*) {
+            switched.emplace_back(id, name);
+            return true;
+        };
+        deps.expand_skill = [](const std::string&, const std::string& text) { return "[展开]" + text; };
+        deps.release_session = [this](const std::string& id, const std::string& key, const std::string& label) {
+            if (conversations) conversations->release_session(id, key, label);
+        };
+        deps.on_bindings_changed = [this] { ++binding_changes; };
+        deps.media_dir = home_dir / "media";
+        conversations = std::make_unique<Conversations>("telegram", *store, access, slot, deps);
+    }
+
+    // 模拟 daemon 重启:丢弃内存状态,重新读盘。
+    void restart() {
+        conversations.reset();
+        open_store();
+        make_conversations();
+    }
+
+    HandleOutcome send(const im::Inbound& inbound) { return conversations->handle(inbound); }
+    HandleOutcome send(const std::string& user, const std::string& text, const std::string& id) {
+        return send(message(private_address(user), text, id));
+    }
+    std::string bound(const std::string& user) {
+        const auto record = store->binding(private_address(user).key());
+        return record ? record->session_id : std::string{};
+    }
+
+    std::filesystem::path home_dir;
+    std::unique_ptr<channels::test::Home> home;
+    FakeSessions sessions;
+    std::shared_ptr<FakeTransport> transport;
+    std::shared_ptr<TransportSlot> slot = std::make_shared<TransportSlot>();
+    std::unique_ptr<ChannelStore> store;
+    AccessControl access;
+    std::unique_ptr<Conversations> conversations;
+    std::vector<std::pair<std::string, std::string>> switched;
+    int binding_changes = 0;
+};
+
+// 场景:已授权联系人第一次发普通消息。
+// 期望:新建无项目会话(default 权限、不继承 daemon 危险标志)并持久化绑定;
+// 消息作为用户输入提交,metadata.channel 带平台、地址与回复上下文。
+TEST_F(ChannelRouter, FirstMessageCreatesNoWorkspaceSession) {
+    send("1", "你好", "m1");
+    const auto created = sessions.created_log();
+    ASSERT_EQ(created.size(), 1u);
+    EXPECT_TRUE(created[0].second.no_workspace);
+    EXPECT_EQ(created[0].second.permission_mode, "default");
+    EXPECT_FALSE(created[0].second.inherit_dangerous_mode);
+    EXPECT_EQ(bound("1"), created[0].first);
+    const auto inputs = sessions.input_log();
+    ASSERT_EQ(inputs.size(), 1u);
+    EXPECT_EQ(inputs[0].first, created[0].first);
+    EXPECT_EQ(inputs[0].second.text, "你好");
+    const auto channel = inputs[0].second.metadata["channel"];
+    EXPECT_EQ(channel.value("platform", ""), "telegram");
+    EXPECT_EQ(channel["reply_context"].value("msg_id", ""), "m1");
+    EXPECT_GE(binding_changes, 1);
+}
+
+// 场景:daemon 重启后同一联系人再次发消息。
+// 期望:不新建会话,消息进入原绑定会话(先恢复该会话)。
+TEST_F(ChannelRouter, BindingSurvivesRestart) {
+    send("1", "第一条", "m1");
+    const auto id = bound("1");
+    restart();
+    send("1", "第二条", "m2");
+    EXPECT_EQ(sessions.created_log().size(), 1u);
+    const auto inputs = sessions.input_log();
+    ASSERT_EQ(inputs.size(), 2u);
+    EXPECT_EQ(inputs[1].first, id);
+    EXPECT_NE(std::find(sessions.resumed.begin(), sessions.resumed.end(), id), sessions.resumed.end());
+}
+
+// 场景:平台重复投递同一条消息(同一 message_id)。
+// 期望:只提交一次。
+TEST_F(ChannelRouter, DuplicateDeliveryIsIgnored) {
+    send("1", "你好", "m1");
+    send("1", "你好", "m1");
+    EXPECT_EQ(sessions.input_log().size(), 1u);
+}
+
+// 场景:同一个群里两个已授权成员分别 @机器人。
+// 期望:各自绑定独立的会话,上下文不混合。
+TEST_F(ChannelRouter, GroupMembersGetSeparateSessions) {
+    send(message(group_address("-100", "1"), "成员一", "g1"));
+    send(message(group_address("-100", "2"), "成员二", "g2"));
+    const auto inputs = sessions.input_log();
+    ASSERT_EQ(inputs.size(), 2u);
+    EXPECT_NE(inputs[0].first, inputs[1].first);
+}
+
+// 场景:绑定在工作区 W 的会话上时发送 /new。
+// 期望:在 W 新建会话(同 cwd 与 workspace_hash)并改绑,回复里带工作区名。
+TEST_F(ChannelRouter, NewSessionFollowsCurrentWorkspace) {
+    sessions.add_session("w-1", "C:/work/proj", "hash-w", false, "工作区会话");
+    send("1", "/resume w-1", "m1");
+    ASSERT_EQ(bound("1"), "w-1");
+    send("1", "/new", "m2");
+    const auto created = sessions.created_log();
+    ASSERT_EQ(created.size(), 1u);
+    EXPECT_FALSE(created[0].second.no_workspace);
+    EXPECT_EQ(created[0].second.cwd, "C:/work/proj");
+    EXPECT_EQ(created[0].second.workspace_hash, "hash-w");
+    EXPECT_EQ(bound("1"), created[0].first);
+    EXPECT_TRUE(transport->wait_said("已新建会话(proj)"));
+    EXPECT_TRUE(sessions.input_log().empty());  // 命令本身不进会话
+}
+
+// 场景:绑定会话正在执行时发送 /new、/resume,以及 /status。
+// 期望:/new 与 /resume 被拒绝且绑定不变;/status 立即回复并显示执行中。
+TEST_F(ChannelRouter, BusySessionRejectsSwitching) {
+    sessions.add_session("w-1", "C:/work/proj", "hash-w", false, "工作区会话");
+    send("1", "开始", "m1");
+    const auto id = bound("1");
+    sessions.set_busy(id, true);
+    send("1", "/new", "m2");
+    send("1", "/resume w-1", "m3");
+    EXPECT_EQ(sessions.created_log().size(), 1u);
+    EXPECT_EQ(bound("1"), id);
+    EXPECT_TRUE(transport->wait_said("请先 /stop"));
+    send("1", "/status", "m4");
+    EXPECT_TRUE(transport->wait_said("状态:执行中"));
+}
+
+// 场景:机主 /sessions 列出全部会话,然后目录里新增一个排在最前面的会话,再 /resume 1。
+// 期望:编号按最近一次列表的快照解析,选中的是列表里的第 1 项而不是新会话。
+TEST_F(ChannelRouter, ResumeIndexUsesLatestListingSnapshot) {
+    sessions.add_session("b-1", "C:/work/b", "hash-b", false, "会话 B");
+    sessions.add_session("c-1", "C:/work/c", "hash-c", false, "会话 C");
+    send("1", "/sessions", "m1");
+    EXPECT_TRUE(transport->wait_said("会话 B"));
+    sessions.add_session("a-1", "C:/work/a", "hash-a", false, "会话 A");
+    send("1", "/resume 1", "m2");
+    EXPECT_EQ(bound("1"), "b-1");
+    EXPECT_TRUE(transport->wait_said("已切换到会话:会话 B"));
+}
+
+// 场景:非机主联系人 /sessions 后尝试切到别人的会话,再切回自己创建的会话。
+// 期望:列表只含自己创建的会话;切别人的会话被拒绝且绑定不变。
+TEST_F(ChannelRouter, NonOwnerOnlySeesOwnSessions) {
+    sessions.add_session("w-1", "C:/work/proj", "hash-w", false, "别人的会话");
+    send("2", "你好", "m1");
+    const auto own = bound("2");
+    send("2", "/sessions", "m2");
+    EXPECT_TRUE(wait_until([&] { return transport->said("可切换的会话"); }));
+    EXPECT_FALSE(transport->said("别人的会话"));
+    send("2", "/resume w-1", "m3");
+    EXPECT_TRUE(transport->wait_said("只能切换到你自己"));
+    EXPECT_EQ(bound("2"), own);
+}
+
+// 场景:机主在群里用 /resume 选中一个当前绑定在自己私聊上的会话。
+// 期望:绑定转到群;私聊收到“已转到其他通道”的提示并解除绑定;
+// 此后该会话的输出只发到群里,私聊的旧投影已退订。
+TEST_F(ChannelRouter, ResumeTransfersBindingBetweenConversations) {
+    send("1", "私聊开始", "m1");
+    const auto id = bound("1");
+    send(message(group_address("-100", "1"), "/resume " + id, "g1"));
+    EXPECT_TRUE(bound("1").empty());
+    const auto group_binding = store->binding(group_address("-100", "1").key());
+    ASSERT_TRUE(group_binding.has_value());
+    EXPECT_EQ(group_binding->session_id, id);
+    EXPECT_TRUE(transport->wait_said("当前会话已转到Telegram 群聊"));
+    EXPECT_TRUE(wait_until([&] { return sessions.listener_count(id) == 1; }));
+    sessions.assistant(id, "只给群的回复");
+    ASSERT_TRUE(transport->wait_said("只给群的回复"));
+    for (const auto& sent : transport->sent()) {
+        if (sent.text == "只给群的回复") EXPECT_EQ(sent.to.kind, im::ChatKind::Group);
+    }
+}
+
+// 场景:绑定的会话已被永久删除,联系人在重启后继续发消息。
+// 期望:明确提示会话无法打开并引导 /new 或 /sessions;不静默新建会话顶替。
+TEST_F(ChannelRouter, DeletedSessionIsReportedNotReplaced) {
+    send("1", "你好", "m1");
+    const auto id = bound("1");
+    restart();
+    sessions.remove(id);
+    send("1", "还在吗", "m2");
+    EXPECT_TRUE(transport->wait_said("无法打开当前绑定的会话"));
+    EXPECT_EQ(sessions.created_log().size(), 1u);
+    EXPECT_EQ(bound("1"), id);
+}
+
+// 场景:普通文本以 / 开头但不是通道命令(技能命令)。
+// 期望:像 Web 输入一样展开后提交,显示文本保留原文。
+TEST_F(ChannelRouter, SkillCommandsAreExpandedLikeWebInput) {
+    send("1", "/review 这个文件", "m1");
+    const auto inputs = sessions.input_log();
+    ASSERT_EQ(inputs.size(), 1u);
+    EXPECT_EQ(inputs[0].second.text, "[展开]/review 这个文件");
+    EXPECT_EQ(inputs[0].second.display_text, "/review 这个文件");
+}
+
+// 场景:尚未绑定时 /status;绑定后 /stop。
+// 期望:命令不进入对话;未绑定时提示直接发消息开始;/stop 中止当前回合并确认。
+TEST_F(ChannelRouter, CommandsAreHandledOutsideTheConversation) {
+    send("1", "/status", "m1");
+    EXPECT_TRUE(transport->wait_said("当前还没有会话"));
+    send("1", "开始", "m2");
+    const auto id = bound("1");
+    send("1", "/stop", "m3");
+    EXPECT_EQ(sessions.abort_log(), std::vector<std::string>{id});
+    EXPECT_TRUE(transport->wait_said("已请求停止"));
+    EXPECT_EQ(sessions.input_log().size(), 1u);
+}
+
+// 场景:/model 不带参数、带已保存的模型名、带不存在的名字。
+// 期望:列出模型;切换绑定会话的模型;未知名字报错并列出可用模型。
+TEST_F(ChannelRouter, ModelCommandListsAndSwitches) {
+    send("1", "开始", "m1");
+    const auto id = bound("1");
+    send("1", "/model", "m2");
+    EXPECT_TRUE(transport->wait_said("可用模型"));
+    send("1", "/model smart", "m3");
+    ASSERT_EQ(switched.size(), 1u);
+    EXPECT_EQ(switched[0], std::make_pair(id, std::string("smart")));
+    EXPECT_TRUE(transport->wait_said("已切换模型为 smart"));
+    send("1", "/model nope", "m4");
+    EXPECT_TRUE(transport->wait_said("没有名为 nope 的模型"));
+    EXPECT_EQ(switched.size(), 1u);
+}
+
+// 场景:绑定会话发出权限请求,IM 里 /approve;随后另一个请求先在 Desktop 被处理。
+// 期望:IM 的批准提交给会话;同一编号再次 /approve 得到“已处理或不存在”;
+// Desktop 先处理的请求在 IM 里收到已处理提示,之后 /approve 同样无效。
+TEST_F(ChannelRouter, PermissionRequestsFirstAnswerWins) {
+    send("1", "开始", "m1");
+    const auto id = bound("1");
+    sessions.emit(id, SessionEventKind::PermissionRequest,
+                  {{"request_id", "p1"}, {"tool", "bash"}, {"args", {{"command", "ls"}}}});
+    ASSERT_TRUE(transport->wait_said("/approve p1"));
+    send("1", "/approve p1", "m2");
+    ASSERT_EQ(sessions.decisions.size(), 1u);
+    EXPECT_EQ(sessions.decisions[0].second.choice, PermissionDecisionChoice::Allow);
+    EXPECT_TRUE(transport->wait_said("已允许权限请求 p1"));
+    send("1", "/approve p1", "m3");
+    EXPECT_TRUE(transport->wait_said("该权限请求已处理或不存在"));
+
+    sessions.emit(id, SessionEventKind::PermissionRequest, {{"request_id", "p2"}, {"tool", "bash"}});
+    ASSERT_TRUE(transport->wait_said("/approve p2"));
+    sessions.emit(id, SessionEventKind::PermissionClosed, {{"request_id", "p2"}, {"choice", "allow"}});
+    EXPECT_TRUE(transport->wait_said("权限请求 p2 已处理"));
+    send("1", "/deny p2", "m4");
+    EXPECT_EQ(sessions.decisions.size(), 1u);
+}
+
+// 场景:会话在提问(AskUserQuestion)时,联系人没有用 /aq 而是直接发了文字。
+// 期望:作为插话交给当前提问,不作为新的普通输入排队。
+TEST_F(ChannelRouter, PlainTextDuringQuestionInterjects) {
+    send("1", "开始", "m1");
+    const auto id = bound("1");
+    sessions.emit(id, SessionEventKind::QuestionRequest,
+                  {{"request_id", "q1"},
+                   {"questions",
+                    {{{"id", "pick"},
+                      {"header", "选择"},
+                      {"text", "选哪个?"},
+                      {"options", {{{"label", "A"}}, {{"label", "B"}}}}}}}});
+    ASSERT_TRUE(transport->wait_said("/aq"));
+    send("1", "我想要 C", "m2");
+    ASSERT_EQ(sessions.interjections.size(), 1u);
+    EXPECT_EQ(sessions.interjections[0].request_id, "q1");
+    EXPECT_EQ(sessions.interjections[0].input.text, "我想要 C");
+    EXPECT_EQ(sessions.input_log().size(), 1u);
+}
+
+// 场景:联系人发来带识别文字的语音,以及一段视频。
+// 期望:语音按“[语音转写] …”提交;视频得到“暂不支持”的回复,会话不收到输入。
+TEST_F(ChannelRouter, VoiceTranscriptsAndUnsupportedMedia) {
+    auto voice = message(private_address("1"), "", "m1");
+    im::Attachment clip;
+    clip.kind = im::AttachmentKind::Voice;
+    clip.transcript = "明天开会";
+    voice.attachments.push_back(clip);
+    send(voice);
+    auto inputs = sessions.input_log();
+    ASSERT_EQ(inputs.size(), 1u);
+    EXPECT_EQ(inputs[0].second.text, "[语音转写] 明天开会");
+
+    auto video = message(private_address("1"), "", "m2");
+    im::Attachment movie;
+    movie.kind = im::AttachmentKind::Video;
+    video.attachments.push_back(movie);
+    send(video);
+    EXPECT_TRUE(transport->wait_said("暂不支持视频消息"));
+    EXPECT_EQ(sessions.input_log().size(), 1u);
+}
+
+// 场景:联系人发来一张图片并附带文字。
+// 期望:图片下载后导入会话附件,与文字一起提交(content_parts 含文字与图片,metadata 记录附件)。
+TEST_F(ChannelRouter, ImagesAreImportedAsSessionAttachments) {
+    auto photo = message(private_address("1"), "看看这张图", "m1");
+    im::Attachment image;
+    image.kind = im::AttachmentKind::Image;
+    image.name = "screen.png";
+    image.mime_type = "image/png";
+    image.remote_ref = "file-1";
+    photo.attachments.push_back(image);
+    send(photo);
+    const auto inputs = sessions.input_log();
+    ASSERT_EQ(inputs.size(), 1u);
+    EXPECT_EQ(inputs[0].second.content_parts.size(), 2u);
+    ASSERT_TRUE(inputs[0].second.metadata.contains("attachments"));
+    EXPECT_EQ(inputs[0].second.metadata["attachments"].size(), 1u);
+}
+
+// 场景:机主撤销某联系人的授权时,该联系人绑定的会话正在执行。
+// 期望:该会话的当前回合被中止。
+TEST_F(ChannelRouter, RevokingAccessAbortsTheirTurn) {
+    send("2", "开始", "m1");
+    const auto id = bound("2");
+    conversations->abort_principal("user:2");
+    EXPECT_EQ(sessions.abort_log(), std::vector<std::string>{id});
+}
+
+// 场景:陌生人私聊。
+// 期望:返回新建的待批准请求供设置页通知,对方收到配对提示,不建会话。
+TEST_F(ChannelRouter, StrangerGetsPairingNotice) {
+    const auto outcome = send("9", "你好", "m1");
+    ASSERT_TRUE(outcome.pending_created.has_value());
+    EXPECT_EQ(outcome.pending_created->principal, "user:9");
+    EXPECT_TRUE(transport->wait_said("还没有被授权"));
+    EXPECT_TRUE(sessions.created_log().empty());
+}
+
+} // namespace
+} // namespace acecode::channels::core
diff --git a/tests/channels/core/state_log_test.cpp b/tests/channels/core/state_log_test.cpp
new file mode 100644
index 000000000..fcc4c1324
--- /dev/null
+++ b/tests/channels/core/state_log_test.cpp
@@ -0,0 +1,198 @@
+#include <gtest/gtest.h>
+
+#include "channels/core/state_log.hpp"
+
+#include <algorithm>
+
+// channels/core/state_log:设置页只显示简要状态(2026-10-05 验收反馈),连接原因、隐私模式、
+// 暂存待补发、机主、授权名单、待批准请求、会话绑定与收发计数都在快照变化时写进日志。
+// 这里只测“前后两份快照 -> 日志行”的纯函数,不碰真实日志文件。
+
+namespace acecode::channels::core {
+namespace {
+
+nlohmann::json telegram_snapshot() {
+    return {
+        {"platform", "telegram"},
+        {"configured", true},
+        {"enabled", true},
+        {"state", "connected"},
+        {"detail", ""},
+        {"retry_stopped", false},
+        {"account", "100"},
+        {"display_name", "@ace_bot"},
+        {"credential_hint", "****wxyz"},
+        {"extra", {{"username", "ace_bot"}, {"privacy_mode", true}}},
+        {"owner", "user:42"},
+        {"owner_window", false},
+        {"contacts", nlohmann::json::array({{{"principal", "user:42"}, {"kind", "user"}, {"name", "我"}, {"owner", true}}})},
+        {"pending", nlohmann::json::array()},
+        {"bindings", nlohmann::json::array({{{"key", "k1"},
+                                             {"label", "Telegram 私聊"},
+                                             {"chat", "42"},
+                                             {"sender", "42"},
+                                             {"session_id", "s-1"},
+                                             {"no_workspace", false},
+                                             {"cwd", "C:/work/项目A"},
+                                             {"sent", 3},
+                                             {"failed", 1},
+                                             {"dropped", 0}}})},
+    };
+}
+
+const StateLogLine* find_line(const std::vector<StateLogLine>& lines, const std::string& text) {
+    const auto it = std::find_if(lines.begin(), lines.end(),
+                                 [&text](const StateLogLine& line) { return line.text == text; });
+    return it == lines.end() ? nullptr : &*it;
+}
+
+bool any_line_contains(const std::vector<StateLogLine>& lines, const std::string& needle) {
+    return std::any_of(lines.begin(), lines.end(),
+                       [&needle](const StateLogLine& line) { return line.text.find(needle) != std::string::npos; });
+}
+
+// 场景:daemon 启动后第一次发布 Telegram 快照(此前没有写过日志)。
+// 期望:写出当前状态的摘要——状态与机器人名、附加信息、隐私模式的含义、机主、授权名单、
+// 已有绑定及其收发计数;凭据尾号不出现在任何一行里。
+TEST(ChannelStateLog, FirstPublishSummarizesCurrentState) {
+    const auto lines = describe_state_changes(nullptr, telegram_snapshot());
+    EXPECT_NE(find_line(lines, "state connected @ace_bot"), nullptr);
+    EXPECT_TRUE(any_line_contains(lines, "status {"));
+    EXPECT_TRUE(any_line_contains(lines, "\"privacy_mode\":true"));
+    EXPECT_NE(find_line(lines, "group privacy mode on: groups deliver only @mentions, replies to the bot and commands"),
+              nullptr);
+    EXPECT_NE(find_line(lines, "owner user:42 (我)"), nullptr);
+    EXPECT_NE(find_line(lines, "authorized user:42 (我)"), nullptr);
+    EXPECT_NE(find_line(lines,
+                        "binding Telegram 私聊 chat 42 -> session s-1 in C:/work/项目A (sent 3, failed 1, dropped 0)"),
+              nullptr);
+    EXPECT_FALSE(any_line_contains(lines, "wxyz"));
+}
+
+// 场景:同一份快照被连续发布两次(例如别的平台的绑定变化触发 publish_all)。
+// 期望:第二次没有任何日志,避免每次推送都刷屏。
+TEST(ChannelStateLog, UnchangedSnapshotWritesNothing) {
+    const auto state = telegram_snapshot();
+    EXPECT_TRUE(describe_state_changes(state, state).empty());
+}
+
+// 场景:连接中断后重试,随后鉴权失败停止重试。
+// 期望:状态行写出前后状态与原因(设置页只显示“连接失败,详情见日志”),失败类状态用警告级别。
+TEST(ChannelStateLog, StateChangesCarryTheReason) {
+    const auto connected = telegram_snapshot();
+    auto retrying = connected;
+    retrying["state"] = "retrying";
+    retrying["detail"] = "网络中断";
+    auto lines = describe_state_changes(connected, retrying);
+    const auto* line = find_line(lines, "state connected @ace_bot -> retrying @ace_bot: 网络中断");
+    ASSERT_NE(line, nullptr);
+    EXPECT_EQ(line->level, LogLevel::Warn);
+
+    auto failed = retrying;
+    failed["state"] = "failed";
+    failed["retry_stopped"] = true;
+    failed["detail"] = "token 无效或已被吊销";
+    lines = describe_state_changes(retrying, failed);
+    EXPECT_NE(find_line(lines, "state retrying @ace_bot: 网络中断 -> failed (retry stopped) @ace_bot: token 无效或已被吊销"),
+              nullptr);
+
+    auto standby = connected;
+    standby["state"] = "standby";
+    standby["display_name"] = "";
+    standby["hosted_by_pid"] = 4321;
+    lines = describe_state_changes(connected, standby);
+    const auto* held = find_line(lines, "state connected @ace_bot -> standby (held by pid 4321)");
+    ASSERT_NE(held, nullptr);
+    EXPECT_EQ(held->level, LogLevel::Info);
+}
+
+// 场景:陌生人私聊产生待批准请求,机主批准后对方进入授权名单;之后撤销授权、机主被移除。
+// 期望:请求出现与关闭、授权加入与移除、机主变化各写一行,带身份与展示名。
+TEST(ChannelStateLog, AccessChangesAreLogged) {
+    const auto base = telegram_snapshot();
+    auto pending = base;
+    pending["pending"] = nlohmann::json::array(
+        {{{"id", "r1"}, {"kind", "user"}, {"name", "Alice"}, {"principal", "user:7"}, {"label", "Telegram 私聊"},
+          {"expires_in_s", 600}}});
+    auto lines = describe_state_changes(base, pending);
+    EXPECT_NE(find_line(lines, "request r1 pending: user user:7 (Alice) via Telegram 私聊, expires in 600s"), nullptr);
+
+    auto approved = base;
+    approved["contacts"].push_back({{"principal", "user:7"}, {"kind", "user"}, {"name", "Alice"}, {"owner", false}});
+    lines = describe_state_changes(pending, approved);
+    EXPECT_NE(find_line(lines, "request r1 closed (approved, rejected or expired): user:7 (Alice)"), nullptr);
+    EXPECT_NE(find_line(lines, "access granted: user:7 (Alice)"), nullptr);
+
+    auto revoked = approved;
+    revoked["owner"] = nullptr;
+    revoked["contacts"] = nlohmann::json::array({approved["contacts"][1]});
+    lines = describe_state_changes(approved, revoked);
+    EXPECT_NE(find_line(lines, "access removed: user:42 (我)"), nullptr);
+    EXPECT_NE(find_line(lines, "owner none"), nullptr);
+}
+
+// 场景:QQ 扫码后打开机主窗口;同一 IM 会话从会话 s-1 切到 s-2;投递失败、成功各一次;最后绑定被释放。
+// 期望:窗口开合、换绑、失败(警告)、成功(调试级别)、释放各一行。
+TEST(ChannelStateLog, OwnerWindowAndBindingChangesAreLogged) {
+    const auto base = telegram_snapshot();
+    auto window = base;
+    window["owner_window"] = true;
+    EXPECT_NE(find_line(describe_state_changes(base, window),
+                        "owner window open: the first private chat within 10 minutes becomes the owner"),
+              nullptr);
+
+    auto moved = base;
+    moved["bindings"][0]["session_id"] = "s-2";
+    moved["bindings"][0]["no_workspace"] = true;
+    moved["bindings"][0]["failed"] = 2;
+    moved["bindings"][0]["sent"] = 4;
+    const auto lines = describe_state_changes(base, moved);
+    EXPECT_NE(find_line(lines, "binding Telegram 私聊 chat 42 -> session s-2 (no workspace)"), nullptr);
+    const auto* failed = find_line(lines, "delivery to Telegram 私聊 chat 42 failed (sent 4, failed 2, dropped 0)");
+    ASSERT_NE(failed, nullptr);
+    EXPECT_EQ(failed->level, LogLevel::Warn);
+    const auto* sent = find_line(lines, "delivered 1 to Telegram 私聊 chat 42 (sent 4, failed 2, dropped 0)");
+    ASSERT_NE(sent, nullptr);
+    EXPECT_EQ(sent->level, LogLevel::Dbg);
+
+    auto released = base;
+    released["bindings"] = nlohmann::json::array();
+    EXPECT_NE(find_line(describe_state_changes(base, released),
+                        "binding removed: Telegram 私聊 chat 42 (was session s-1 in C:/work/项目A)"),
+              nullptr);
+}
+
+// 场景:更换 Telegram token;QQ 改了 AppID;QQ 有回复被平台拒收而暂存;Telegram 机器人被配置了 webhook。
+// 期望:凭据只记“已更新”(QQ 附 AppID,它不是密钥),不写任何凭据片段;暂存数量与 webhook 用警告级别说明后果。
+TEST(ChannelStateLog, CredentialsAndPlatformExtras) {
+    const auto base = telegram_snapshot();
+    auto rotated = base;
+    rotated["credential_hint"] = "****abcd";
+    auto lines = describe_state_changes(base, rotated);
+    EXPECT_NE(find_line(lines, "credentials updated"), nullptr);
+    EXPECT_FALSE(any_line_contains(lines, "abcd"));
+
+    nlohmann::json qq{{"platform", "qq"}, {"configured", true}, {"state", "connected"}, {"app_id", "1020"},
+                      {"credential_hint", "****9999"}, {"extra", {{"held", 0}}}};
+    auto qq_next = qq;
+    qq_next["app_id"] = "2030";
+    qq_next["extra"]["held"] = 2;
+    lines = describe_state_changes(qq, qq_next);
+    EXPECT_NE(find_line(lines, "credentials updated (AppID 2030)"), nullptr);
+    const auto* held =
+        find_line(lines, "2 output(s) held after QQ refused them; they are resent before the contact's next message");
+    ASSERT_NE(held, nullptr);
+    EXPECT_EQ(held->level, LogLevel::Warn);
+    EXPECT_FALSE(any_line_contains(lines, "9999"));
+
+    auto webhook = base;
+    webhook["extra"]["webhook"] = true;
+    const auto* blocked = find_line(describe_state_changes(base, webhook),
+                                    "a webhook is set for this bot; long polling stays blocked until it is removed in "
+                                    "the connect dialog");
+    ASSERT_NE(blocked, nullptr);
+    EXPECT_EQ(blocked->level, LogLevel::Warn);
+}
+
+} // namespace
+} // namespace acecode::channels::core
diff --git a/tests/channels/core/store_test.cpp b/tests/channels/core/store_test.cpp
new file mode 100644
index 000000000..d160b9b4b
--- /dev/null
+++ b/tests/channels/core/store_test.cpp
@@ -0,0 +1,216 @@
+#include <gtest/gtest.h>
+
+#include "channels/core/store.hpp"
+#include "test_support/channels/test_support.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <filesystem>
+#include <fstream>
+#include <thread>
+#include <vector>
+
+// channels/core/store:每个平台目录下的 config.json(开关、凭据、机主、授权名单)
+// 与 state.json(会话绑定、创建记录、去重回执、游标)。
+
+namespace acecode::channels::core {
+namespace {
+
+im::Address telegram_user(const std::string& id) {
+    im::Address address;
+    address.platform = "telegram";
+    address.account = "100";
+    address.kind = im::ChatKind::Private;
+    address.chat = id;
+    address.sender = id;
+    return address;
+}
+
+void write_text(const std::filesystem::path& path, const std::string& text) {
+    std::filesystem::create_directories(path.parent_path());
+    std::ofstream(path, std::ios::binary) << text;
+}
+
+// 场景:设置页保存了凭据与授权名单,运行时写入了绑定、创建记录、回执和游标,然后进程重启。
+// 期望:新的 ChannelStore 读盘后,所有字段与重启前一致。
+TEST(ChannelStore, RoundTripsConfigAndStateAcrossRestart) {
+    const auto dir = channels::test::temporary("store-roundtrip");
+    {
+        ChannelStore store(dir);
+        store.load();
+        store.update_config([](PlatformConfig& config) {
+            config.enabled = true;
+            config.credentials = {{"token", "100:secret-token"}};
+            config.owner = "user:1";
+            config.access.push_back({"user:1", "机主", 42});
+            config.access.push_back({"group:-1001", "", 43});
+        });
+        BindingRecord record;
+        record.address = telegram_user("1");
+        record.session_id = "s-1";
+        record.cwd = "C:/work/项目";
+        record.workspace_hash = "abc";
+        record.no_workspace = false;
+        record.updated_at_ms = 7;
+        store.put_binding(record);
+        store.remember_created(record.address.key(), "s-1");
+        store.remember_receipt(record.address.key(), "m-1");
+        store.set_cursor("telegram_offset", 99);
+    }
+    ChannelStore reloaded(dir);
+    reloaded.load();
+    const auto config = reloaded.config();
+    EXPECT_TRUE(config.enabled);
+    EXPECT_EQ(config.credentials.value("token", ""), "100:secret-token");
+    EXPECT_EQ(config.owner, "user:1");
+    ASSERT_EQ(config.access.size(), 2u);
+    EXPECT_EQ(config.access[0].name, "机主");
+    const auto key = telegram_user("1").key();
+    const auto binding = reloaded.binding(key);
+    ASSERT_TRUE(binding.has_value());
+    EXPECT_EQ(binding->session_id, "s-1");
+    EXPECT_EQ(binding->cwd, "C:/work/项目");
+    EXPECT_FALSE(binding->no_workspace);
+    EXPECT_EQ(reloaded.created_sessions(key), std::vector<std::string>{"s-1"});
+    EXPECT_TRUE(reloaded.has_receipt(key, "m-1"));
+    EXPECT_FALSE(reloaded.has_receipt(key, "m-2"));
+    EXPECT_EQ(reloaded.cursor("telegram_offset"), 99);
+    std::filesystem::remove_all(dir);
+}
+
+// 场景:config.json 被写坏(不是 JSON),或 state.json 里绑定的键与地址不一致。
+// 期望:load() 抛出带中文原因的异常,拒绝启动该平台,且不会把文件重置成空配置。
+TEST(ChannelStore, RejectsCorruptFilesWithoutResetting) {
+    const auto dir = channels::test::temporary("store-corrupt");
+    write_text(dir / "config.json", "{not json");
+    ChannelStore broken(dir);
+    try {
+        broken.load();
+        FAIL() << "损坏的配置应当被拒绝";
+    } catch (const std::runtime_error& e) {
+        EXPECT_NE(std::string(e.what()).find("损坏"), std::string::npos) << e.what();
+    }
+    {
+        std::ifstream in(dir / "config.json", std::ios::binary);
+        EXPECT_EQ(std::string((std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>()), "{not json");
+    }
+
+    const auto dir2 = channels::test::temporary("store-bad-binding");
+    nlohmann::json state{{"version", 1},
+                         {"bindings", {{"wrong-key", {{"address", telegram_user("1").to_json()}, {"session_id", "s-1"}}}}},
+                         {"created", nlohmann::json::object()},
+                         {"receipts", nlohmann::json::array()},
+                         {"cursors", nlohmann::json::object()}};
+    write_text(dir2 / "state.json", state.dump());
+    ChannelStore mismatched(dir2);
+    EXPECT_THROW(mismatched.load(), std::runtime_error);
+
+    write_text(dir2 / "state.json", R"({"version":2})");
+    ChannelStore wrong_version(dir2);
+    EXPECT_THROW(wrong_version.load(), std::runtime_error);
+    std::filesystem::remove_all(dir);
+    std::filesystem::remove_all(dir2);
+}
+
+// 场景:配置文件版本不对,或机主身份不是 user:/group:/member: 前缀。
+// 期望:都视为无效配置,load() 抛异常。
+TEST(ChannelStore, RejectsInvalidConfigStructure) {
+    const auto dir = channels::test::temporary("store-bad-config");
+    write_text(dir / "config.json", R"({"version":9,"enabled":true})");
+    ChannelStore bad_version(dir);
+    EXPECT_THROW(bad_version.load(), std::runtime_error);
+    write_text(dir / "config.json", R"({"version":1,"enabled":true,"owner":"admin"})");
+    ChannelStore bad_owner(dir);
+    EXPECT_THROW(bad_owner.load(), std::runtime_error);
+    write_text(dir / "config.json", R"({"version":1,"enabled":true,"credentials":{"token":5}})");
+    ChannelStore bad_credentials(dir);
+    EXPECT_THROW(bad_credentials.load(), std::runtime_error);
+    std::filesystem::remove_all(dir);
+}
+
+// 场景:目录里还没有任何文件(首次使用)。
+// 期望:load() 成功,平台处于关闭、无凭据、无机主的初始状态。
+TEST(ChannelStore, MissingFilesMeanFreshPlatform) {
+    const auto dir = channels::test::temporary("store-fresh");
+    ChannelStore store(dir);
+    store.load();
+    const auto config = store.config();
+    EXPECT_FALSE(config.enabled);
+    EXPECT_TRUE(config.credentials.empty());
+    EXPECT_TRUE(config.owner.empty());
+    EXPECT_TRUE(store.bindings().empty());
+    EXPECT_EQ(store.cursor("telegram_offset"), 0);
+}
+
+// 场景:设置页的多个操作(批准请求、撤销授权)在不同线程同时修改配置。
+// 期望:每次修改都基于最新配置串行进行,8 个线程各加 25 条授权后共 200 条,重读一致。
+TEST(ChannelStore, ConcurrentConfigEditsAreSerialized) {
+    const auto dir = channels::test::temporary("store-concurrent");
+    ChannelStore store(dir);
+    store.load();
+    std::vector<std::thread> threads;
+    for (int t = 0; t < 8; ++t) {
+        threads.emplace_back([&, t] {
+            for (int i = 0; i < 25; ++i) {
+                store.update_config([&](PlatformConfig& config) {
+                    config.access.push_back({"user:" + std::to_string(t * 100 + i), "", 0});
+                });
+            }
+        });
+    }
+    for (auto& thread : threads) thread.join();
+    EXPECT_EQ(store.config().access.size(), 200u);
+    ChannelStore reloaded(dir);
+    reloaded.load();
+    EXPECT_EQ(reloaded.config().access.size(), 200u);
+    std::filesystem::remove_all(dir);
+}
+
+// 场景:一个 IM 会话通过 /new 反复建会话,超过每个 IM 会话保留的上限(200)。
+// 期望:只保留最近 200 个,最早的被淘汰;重复登记同一个会话不产生重复项。
+TEST(ChannelStore, CreatedSessionListIsBounded) {
+    const auto dir = channels::test::temporary("store-created");
+    ChannelStore store(dir);
+    store.load();
+    const auto key = telegram_user("1").key();
+    for (int i = 0; i < 205; ++i) store.remember_created(key, "s-" + std::to_string(i));
+    store.remember_created(key, "s-204");
+    const auto created = store.created_sessions(key);
+    ASSERT_EQ(created.size(), ChannelStore::kMaxCreatedPerConversation);
+    EXPECT_EQ(created.front(), "s-5");
+    EXPECT_EQ(created.back(), "s-204");
+    std::filesystem::remove_all(dir);
+}
+
+// 场景:处理消息时先记回执,随后处理失败需要允许对方重发。
+// 期望:forget_receipt 后同一条消息不再被视为已处理;其它消息的回执不受影响。
+TEST(ChannelStore, ReceiptsCanBeForgottenAfterFailure) {
+    const auto dir = channels::test::temporary("store-receipts");
+    ChannelStore store(dir);
+    store.load();
+    const auto key = telegram_user("1").key();
+    store.remember_receipt(key, "m-1");
+    store.remember_receipt(key, "m-2");
+    store.forget_receipt(key, "m-1");
+    EXPECT_FALSE(store.has_receipt(key, "m-1"));
+    EXPECT_TRUE(store.has_receipt(key, "m-2"));
+    EXPECT_FALSE(store.has_receipt(telegram_user("2").key(), "m-2"));
+    std::filesystem::remove_all(dir);
+}
+
+#ifndef _WIN32
+// 场景:保存了含 token 的配置。
+// 期望:config.json 只有当前用户可读写(0600)。
+TEST(ChannelStore, ConfigFileIsPrivate) {
+    const auto dir = channels::test::temporary("store-private");
+    ChannelStore store(dir);
+    store.load();
+    store.update_config([](PlatformConfig& config) { config.credentials = {{"token", "100:secret"}}; });
+    const auto perms = std::filesystem::status(dir / "config.json").permissions();
+    using std::filesystem::perms;
+    EXPECT_EQ(perms & (perms::group_all | perms::others_all), perms::none);
+    std::filesystem::remove_all(dir);
+}
+#endif
+
+} // namespace
+} // namespace acecode::channels::core
diff --git a/tests/daemon/daemon_shutdown_sequence_test.cpp b/tests/daemon/daemon_shutdown_sequence_test.cpp
index 25d64460c..b1f6b2a14 100644
--- a/tests/daemon/daemon_shutdown_sequence_test.cpp
+++ b/tests/daemon/daemon_shutdown_sequence_test.cpp
@@ -53,6 +53,18 @@ TEST(DaemonShutdownSequence, StopsProducersAndSessionsBeforeTheirServices) {
     for (const auto& [step, count] : calls) { (void)step; EXPECT_EQ(count, 1); }
 }
 
+// 场景与期望：消息通道(QQ / Telegram)先停止接收入站消息并退订会话事件，再关闭会话；
+// 否则回合收尾时投影还会往已断开的平台发消息。
+TEST(DaemonShutdownSequence, ImChannelsStopBeforeSessions) {
+    bool channels_running = true;
+    DaemonShutdownSequence shutdown;
+    shutdown.run([&](DaemonShutdownStep step) {
+        if (step == DaemonShutdownStep::ImChannels) channels_running = false;
+        if (step == DaemonShutdownStep::Sessions) EXPECT_FALSE(channels_running);
+    });
+    EXPECT_FALSE(channels_running);
+}
+
 // 场景与期望：一个收尾步骤抛异常后，后续步骤仍执行且重复调用不重做，避免退出漏清理。
 TEST(DaemonShutdownSequence, ExceptionStillRunsLaterCleanupOnce) {
     int registry_shutdowns = 0;
diff --git a/tests/daemon/im_channels_e2e_test.cpp b/tests/daemon/im_channels_e2e_test.cpp
new file mode 100644
index 000000000..65563fea9
--- /dev/null
+++ b/tests/daemon/im_channels_e2e_test.cpp
@@ -0,0 +1,810 @@
+#include <gtest/gtest.h>
+
+#include "channels/core/line_webhook_server.hpp"
+#include "config/config.hpp"
+#include "daemon/im_channels.hpp"
+#include "daemon/rc_session_catalog.hpp"
+#include "permissions/permissions.hpp"
+#include "session_host/local_session_client.hpp"
+#include "session/session_storage.hpp"
+#include "session_host/session_registry.hpp"
+#include "test_support/agent/stub_provider.hpp"
+#include "test_support/im/fake_dingtalk_server.hpp"
+#include "test_support/im/fake_discord_server.hpp"
+#include "test_support/im/fake_feishu_server.hpp"
+#include "test_support/im/fake_line_server.hpp"
+#include "test_support/im/fake_qq_server.hpp"
+#include "test_support/im/fake_telegram_server.hpp"
+#include "test_support/im/fake_weixin_server.hpp"
+#include "tool/tool_executor.hpp"
+#include "utils/paths.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <cstdlib>
+#include <filesystem>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <random>
+#include <shared_mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+// 消息通道端到端:daemon 的生产装配(make_im_channel_host)+ 真实 SessionRegistry / AgentLoop
+// (脚本化模型)+ 真实各平台传输层,平台换成本机假服务。覆盖真实账号验收清单里
+// 不依赖真实账号的部分:凭据校验、机主绑定、私聊与群 @ 的完整往返、审批、切到工作区会话、
+// /new、非机主受限、开关即时性、图片入站、QQ 扫码、语音识别文字与超出回复窗口后的补发;
+// 微信扫码登录,飞书、钉钉、Discord、LINE 的 6 位绑定码与私聊往返。
+// 这五个平台的假服务只在用到的用例里创建(各自要起一个本机端口)。
+
+namespace acecode::daemon {
+namespace {
+
+namespace fs = std::filesystem;
+using nlohmann::json;
+using std::chrono::milliseconds;
+
+constexpr const char* kSecretB64 = "ZGVmZ2hpamtsbW5vOWrzEhyaIrNNBzyavxFHGfpv4JwMQcJAlM16v321wbiQ0njyP4fhqnk=";
+
+const char* home_key() {
+#ifdef _WIN32
+    return "USERPROFILE";
+#else
+    return "HOME";
+#endif
+}
+
+void set_env(const char* key, const std::string& value) {
+#ifdef _WIN32
+    _putenv_s(key, value.c_str());
+#else
+    if (value.empty()) unsetenv(key);
+    else setenv(key, value.c_str(), 1);
+#endif
+}
+
+bool wait_until(const std::function<bool()>& ready, milliseconds timeout = std::chrono::seconds(10)) {
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    while (std::chrono::steady_clock::now() < deadline) {
+        if (ready()) return true;
+        std::this_thread::sleep_for(milliseconds(20));
+    }
+    return ready();
+}
+
+std::string fixed_key() {
+    std::string key;
+    for (int i = 0; i < 32; ++i) key.push_back(static_cast<char>(i));
+    return key;
+}
+
+json telegram_message(std::int64_t chat, const std::string& chat_type, std::int64_t from, std::int64_t id,
+                      const std::string& text) {
+    return {{"message", {{"message_id", id},
+                         {"from", {{"id", from}, {"is_bot", false}, {"first_name", "U" + std::to_string(from)}}},
+                         {"chat", {{"id", chat}, {"type", chat_type}}},
+                         {"text", text}}}};
+}
+
+class ImChannelsEndToEnd : public testing::Test {
+protected:
+    void SetUp() override {
+        home = fs::temp_directory_path() / ("acecode_im_e2e_" + std::to_string(std::random_device{}()));
+        fs::create_directories(home / "ws");
+        workspace = path_to_utf8(home / "ws");
+        if (const char* previous = std::getenv(home_key())) {
+            previous_home = previous;
+            had_home = true;
+        }
+        set_env(home_key(), path_to_utf8(home));
+        previous_mode = override_run_mode_for_test(RunMode::User);
+        reset_data_dir_cache_for_test();
+
+        SessionRegistryDeps deps;
+        deps.provider_accessor = [p = provider] { return std::shared_ptr<LlmProvider>(p); };
+        deps.tools = &tools;
+        deps.cwd = workspace;
+        deps.template_permissions = &permissions;
+        deps.no_workspace_cache_root = path_to_utf8(home / "no-workspace");
+        deps.auto_title_generator = [](const std::string&) { return std::optional<std::string>{"title"}; };
+        registry = std::make_unique<SessionRegistry>(std::move(deps));
+        client = std::make_unique<LocalSessionClient>(*registry);
+    }
+
+    void TearDown() override {
+        if (host) host->stop();
+        host.reset();
+        client.reset();
+        if (registry) registry->shutdown_all();
+        registry.reset();
+        set_env(home_key(), had_home ? previous_home : std::string{});
+        override_run_mode_for_test(previous_mode);
+        reset_data_dir_cache_for_test();
+        std::error_code ec;
+        fs::remove_all(home, ec);
+    }
+
+    void start_host() {
+        ImChannelDeps deps;
+        deps.registry = registry.get();
+        deps.client = client.get();
+        deps.config = &config;
+        deps.config_mu = &config_mu;
+        const auto projects = path_to_utf8(path_from_utf8(get_acecode_dir()) / "projects");
+        deps.catalog = [this, projects](const std::optional<std::string>& query) {
+            return build_rc_session_catalog(projects, *client, query);
+        };
+        deps.broadcast = [this](const std::string& type, const json& payload) {
+            std::lock_guard<std::mutex> lock(events_mu);
+            events.emplace_back(type, payload);
+        };
+        deps.endpoints.telegram_api_base = telegram.base();
+        deps.endpoints.qq_api_base = qq.base();
+        deps.endpoints.qq_token_url = qq.base() + "/app/getAppAccessToken";
+        if (weixin) {
+            deps.endpoints.weixin_api_base = weixin->base();
+            deps.endpoints.weixin_cdn_base = weixin->cdn_base();
+            deps.weixin_login.poll_interval = milliseconds(20);
+            deps.weixin_login.total_timeout = std::chrono::seconds(5);
+            deps.weixin_login.redirect_scheme = "http";
+        }
+        if (dingtalk) {
+            deps.endpoints.dingtalk_api_base = dingtalk->base();
+            deps.endpoints.dingtalk_oapi_base = dingtalk->base();
+        }
+        if (discord) deps.endpoints.discord_api_base = discord->api_base();
+        if (feishu) {
+            deps.endpoints.feishu_base = feishu->base();
+            deps.tune_services = [](channels::core::HostServices& services) {
+                services.tune_feishu = [](im::feishu::FeishuTransportOptions& options) {
+                    options.backoff = {milliseconds(50)};
+                    options.receive_poll = milliseconds(50);
+                    options.send_gap = milliseconds(1);
+                };
+            };
+        }
+        if (line) {
+            deps.endpoints.line_api_base = line->base();
+            deps.endpoints.line_data_api_base = line->base();
+            // 自有公网地址模式:公网地址就是本机回调端口本身(真实环境里要求 https,
+            // 这里绕过保存前的校验直接改传输层参数),不启动 cloudflared。
+            deps.tune_services = [port = line_port](channels::core::HostServices& services) {
+                services.tune_line = [port](im::line::LineTransportOptions& options) {
+                    options.listen_port = port;
+                    options.public_url = "http://127.0.0.1:" + std::to_string(port);
+                    options.backoff = {milliseconds(50)};
+                    options.public_check_timeout = std::chrono::seconds(3);
+                    options.public_check_interval = milliseconds(50);
+                    options.webhook_recheck = milliseconds(100);
+                };
+            };
+        }
+        deps.endpoints.use_proxy = false;
+        deps.bind.portal_base = qq.base();
+        deps.bind.connect_base = "https://q.qq.com";
+        deps.bind.use_proxy = false;
+        deps.bind.poll_interval = milliseconds(20);
+        deps.bind.total_timeout = std::chrono::seconds(5);
+        deps.bind.key_provider = fixed_key;
+        deps.root = home / "channels";
+        host = make_im_channel_host(std::move(deps));
+        host->start();
+    }
+
+    json platform(const std::string& name) {
+        const auto snapshot = host->snapshot();
+        for (const auto& item : snapshot["platforms"])
+            if (item.value("platform", "") == name) return item;
+        return json::object();
+    }
+    static std::string text(const json& object, const char* key) {
+        return object.contains(key) && object[key].is_string() ? object[key].get<std::string>() : std::string{};
+    }
+    // 某个 IM 会话(chat + sender)当前绑定的会话 id。
+    std::string bound(const std::string& name, const std::string& chat, const std::string& sender) {
+        const auto snapshot = platform(name);  // 先存下来:range-for 不延长临时对象子对象的生命周期
+        for (const auto& binding : snapshot["bindings"])
+            if (binding.value("chat", "") == chat && binding.value("sender", "") == sender)
+                return binding.value("session_id", "");
+        return {};
+    }
+    std::vector<json> events_of(const std::string& type) {
+        std::lock_guard<std::mutex> lock(events_mu);
+        std::vector<json> out;
+        for (const auto& [name, payload] : events)
+            if (name == type) out.push_back(payload);
+        return out;
+    }
+    // Telegram 发到某个聊天的消息里是否有一条包含 needle。
+    bool telegram_sent(std::int64_t chat, const std::string& needle) {
+        for (const auto& call : telegram.calls_to("sendMessage")) {
+            if (call.body.value("chat_id", std::int64_t{0}) == chat &&
+                call.body.value("text", std::string{}).find(needle) != std::string::npos)
+                return true;
+        }
+        return false;
+    }
+    // 用户消息是否出现在模型收到的某次请求里(证明它进入了会话)。
+    bool model_saw(const std::string& needle) {
+        for (int i = 0; i < provider->turn_count(); ++i)
+            for (const auto& message : provider->messages_for_turn(i))
+                if (message.role == "user" && message.content.find(needle) != std::string::npos) return true;
+        return false;
+    }
+    void connect_telegram_as_owner() {
+        auto& runtime = host->platform("telegram");
+        runtime.set_credentials({{"token", telegram.token()}});
+        runtime.set_enabled(true);
+        ASSERT_TRUE(wait_until([&] { return platform("telegram").value("state", "") == "connected"; }));
+        const auto link = host->owner_link("telegram").value("link", std::string{});
+        const auto code = link.substr(link.find("start=") + 6);
+        telegram.push_update(telegram_message(42, "private", 42, 1, "/start " + code));
+        ASSERT_TRUE(wait_until([&] { return text(platform("telegram"), "owner") == "user:42"; }));
+    }
+
+    fs::path home;
+    std::string workspace;
+    ToolExecutor tools;
+    PermissionManager permissions;
+    AppConfig config;
+    std::shared_mutex config_mu;
+    std::shared_ptr<acecode_test::StubLlmProvider> provider = std::make_shared<acecode_test::StubLlmProvider>();
+    std::unique_ptr<SessionRegistry> registry;
+    std::unique_ptr<LocalSessionClient> client;
+    acecode::test::FakeTelegramServer telegram;
+    acecode::test::FakeQqServer qq;
+    std::unique_ptr<acecode::test::FakeWeixinServer> weixin;
+    std::unique_ptr<acecode::test::FakeDingTalkServer> dingtalk;
+    std::unique_ptr<acecode::test::FakeDiscordServer> discord;
+    std::unique_ptr<acecode::test::FakeFeishuServer> feishu;
+    std::unique_ptr<acecode::test::FakeLineServer> line;
+    std::uint16_t line_port = 0;
+    std::unique_ptr<channels::core::ChannelHost> host;
+    std::mutex events_mu;
+    std::vector<std::pair<std::string, json>> events;
+    std::string previous_home;
+    bool had_home = false;
+    RunMode previous_mode = RunMode::User;
+};
+
+// 场景:设置页填错 token 后改成正确的;用机主链接里的 /start 码绑定机主;机主私聊提问。
+// 期望:错误 token 不保存;正确 token 经 getMe 校验后连接;/start 发送者成为机主并收到确认;
+// 私聊消息新建无项目会话、进入模型,助手答复按 Telegram HTML 发回同一私聊。
+TEST_F(ImChannelsEndToEnd, TelegramValidatesTokenBindsOwnerAndChats) {
+    start_host();
+    EXPECT_THROW(host->platform("telegram").set_credentials({{"token", "999:wrong-token"}}), std::runtime_error);
+    EXPECT_FALSE(platform("telegram").value("configured", true));
+    connect_telegram_as_owner();
+    EXPECT_TRUE(wait_until([&] { return telegram_sent(42, "已绑定为机主"); }));
+
+    provider->push_text("**收到**,我是 ACECode");
+    telegram.push_update(telegram_message(42, "private", 42, 2, "你好"));
+    ASSERT_TRUE(wait_until([&] { return telegram_sent(42, "<b>收到</b>,我是 ACECode"); }));
+    EXPECT_TRUE(model_saw("你好"));
+    const auto session = bound("telegram", "42", "42");
+    ASSERT_FALSE(session.empty()) << platform("telegram").dump(2);
+    EXPECT_EQ(host->bound_sessions().at(session), "telegram");
+    for (const auto& info : client->list_sessions())
+        if (info.id == session) EXPECT_TRUE(info.no_workspace);
+}
+
+// 场景:机器人在一个未批准的群里被 @,机主在设置页批准该群后再次 @ 提问;群里不 @ 的消息。
+// 期望:未批准时只产生群的待批准请求、不回复;批准后 @ 的提问进入会话并在群里得到答复;
+// 不 @ 的消息被忽略。隐私模式(默认开启)反映在快照里。
+TEST_F(ImChannelsEndToEnd, TelegramGroupNeedsApprovalAndMention) {
+    start_host();
+    connect_telegram_as_owner();
+    EXPECT_TRUE(platform("telegram")["extra"].value("privacy_mode", false));
+    auto mention = telegram_message(-100, "group", 42, 10, "@AceTestBot 帮我看看");
+    mention["message"]["entities"] = json::array({{{"type", "mention"}, {"offset", 0}, {"length", 11}}});
+    telegram.push_update(mention);
+    ASSERT_TRUE(wait_until([&] { return !events_of("channels_request").empty(); }));
+    const auto request = events_of("channels_request").back();
+    EXPECT_EQ(request.value("kind", ""), "group");
+    host->platform("telegram").approve(request.value("id", ""), true);
+
+    telegram.push_update(telegram_message(-100, "group", 42, 11, "大家好"));  // 不 @,应忽略
+    provider->push_text("群里的答复");
+    mention["message"]["message_id"] = 12;
+    telegram.push_update(mention);
+    ASSERT_TRUE(wait_until([&] { return telegram_sent(-100, "群里的答复"); }));
+    EXPECT_FALSE(model_saw("大家好"));
+    EXPECT_FALSE(bound("telegram", "-100", "42").empty());
+}
+
+// 场景:机主先在私聊里开始,然后 /sessions 列出会话、/resume 切到一个工作区会话继续提问,
+// 再 /new。
+// 期望:切换后提问进入工作区会话并收到答复;/new 在同一工作区新建会话并改绑。
+TEST_F(ImChannelsEndToEnd, TelegramOwnerSwitchesIntoWorkspaceSessionAndNew) {
+    start_host();
+    connect_telegram_as_owner();
+    SessionOptions options;
+    options.cwd = workspace;
+    const auto workspace_session = client->create_session(options);
+    ASSERT_FALSE(workspace_session.empty());
+
+    telegram.push_update(telegram_message(42, "private", 42, 2, "/sessions"));
+    ASSERT_TRUE(wait_until([&] { return telegram_sent(42, "可切换的会话"); }));
+    telegram.push_update(telegram_message(42, "private", 42, 3, "/resume " + workspace_session));
+    ASSERT_TRUE(wait_until([&] { return bound("telegram", "42", "42") == workspace_session; }));
+    EXPECT_TRUE(wait_until([&] { return telegram_sent(42, "已切换到会话"); }));
+
+    provider->push_text("工作区里的答复");
+    telegram.push_update(telegram_message(42, "private", 42, 4, "看看工作区"));
+    ASSERT_TRUE(wait_until([&] { return telegram_sent(42, "工作区里的答复"); }));
+    EXPECT_TRUE(model_saw("看看工作区"));
+
+    telegram.push_update(telegram_message(42, "private", 42, 5, "/new"));
+    ASSERT_TRUE(wait_until([&] {
+        const auto id = bound("telegram", "42", "42");
+        return !id.empty() && id != workspace_session;
+    }));
+    const auto fresh = bound("telegram", "42", "42");
+    bool in_workspace = false;
+    for (const auto& info : client->list_sessions())
+        if (info.id == fresh) in_workspace = !info.no_workspace && path_from_utf8(info.cwd) == path_from_utf8(workspace);
+    EXPECT_TRUE(in_workspace);
+}
+
+// 场景:机主批准一位普通联系人;该联系人试图 /resume 机主的会话。
+// 期望:请求被拒绝且其绑定不变;对方仍可正常和自己的会话对话。
+TEST_F(ImChannelsEndToEnd, TelegramNonOwnerCannotResumeOthersSessions) {
+    start_host();
+    connect_telegram_as_owner();
+    provider->push_text("机主的答复");
+    telegram.push_update(telegram_message(42, "private", 42, 2, "机主的问题"));
+    ASSERT_TRUE(wait_until([&] { return telegram_sent(42, "机主的答复"); }));
+    const auto owner_session = bound("telegram", "42", "42");
+
+    telegram.push_update(telegram_message(7, "private", 7, 3, "你好"));
+    ASSERT_TRUE(wait_until([&] { return !events_of("channels_request").empty(); }));
+    EXPECT_TRUE(wait_until([&] { return telegram_sent(7, "还没有被授权"); }));
+    host->platform("telegram").approve(events_of("channels_request").back().value("id", ""), true);
+    EXPECT_EQ(text(platform("telegram"), "owner"), "user:42");  // 已有机主,不会被替换
+
+    provider->push_text("给联系人的答复");
+    telegram.push_update(telegram_message(7, "private", 7, 4, "我的问题"));
+    ASSERT_TRUE(wait_until([&] { return telegram_sent(7, "给联系人的答复"); }));
+    const auto contact_session = bound("telegram", "7", "7");
+    telegram.push_update(telegram_message(7, "private", 7, 5, "/resume " + owner_session));
+    EXPECT_TRUE(wait_until([&] { return telegram_sent(7, "只能切换到你自己"); }));
+    EXPECT_EQ(bound("telegram", "7", "7"), contact_session);
+    EXPECT_EQ(bound("telegram", "42", "42"), owner_session);
+}
+
+// 场景:关闭开关期间机主发来消息,随后重新打开开关。
+// 期望:关闭立即停止轮询,期间不处理任何消息;重新打开后从保存的位置继续,补处理那条消息。
+TEST_F(ImChannelsEndToEnd, TelegramSwitchTakesEffectImmediately) {
+    start_host();
+    connect_telegram_as_owner();
+    host->platform("telegram").set_enabled(false);
+    EXPECT_EQ(platform("telegram").value("state", ""), "disabled");
+    telegram.push_update(telegram_message(42, "private", 42, 2, "关着的时候发的"));
+    std::this_thread::sleep_for(milliseconds(800));
+    EXPECT_FALSE(model_saw("关着的时候发的"));
+
+    provider->push_text("恢复后的答复");
+    host->platform("telegram").set_enabled(true);
+    ASSERT_TRUE(wait_until([&] { return telegram_sent(42, "恢复后的答复"); }));
+    EXPECT_TRUE(model_saw("关着的时候发的"));
+}
+
+// 场景:机主发来一张带说明文字的图片。
+// 期望:图片经 getFile 下载并导入会话附件,说明文字与图片一起进入会话,答复发回私聊。
+TEST_F(ImChannelsEndToEnd, TelegramPhotoBecomesSessionAttachment) {
+    start_host();
+    connect_telegram_as_owner();
+    provider->push_text("看到图片了");
+    json photo = {{"message", {{"message_id", 20},
+                               {"from", {{"id", 42}, {"is_bot", false}, {"first_name", "Ann"}}},
+                               {"chat", {{"id", 42}, {"type", "private"}}},
+                               {"caption", "看看这张图"},
+                               {"photo", json::array({{{"file_id", "p1"}, {"file_unique_id", "u1"},
+                                                       {"width", 90}, {"height", 90}, {"file_size", 32}}})}}}};
+    telegram.push_update(photo);
+    ASSERT_TRUE(wait_until([&] { return telegram_sent(42, "看到图片了"); }));
+    EXPECT_FALSE(telegram.calls_to("download:documents/p1.bin").empty());
+    EXPECT_TRUE(model_saw("看看这张图"));
+    const auto session = bound("telegram", "42", "42");
+    std::string error;
+    bool has_attachment = false;
+    for (const auto& info : client->list_sessions()) {
+        if (info.id != session) continue;
+        const auto dir = path_from_utf8(SessionStorage::get_project_dir(info.cwd)) / "attachments" / session;
+        has_attachment = fs::exists(dir) && !fs::is_empty(dir);
+    }
+    EXPECT_TRUE(has_attachment);
+}
+
+// 场景:模型要调用一个需要确认的工具。第一次机主在 Telegram 里 /approve;第二次先在 Desktop
+// 里批准,之后机主再发 /approve。
+// 期望:IM 收到带编号的确认请求;IM 批准后工具执行、答复发回;Desktop 先批准时 IM 收到
+// “已处理”提示,随后的 /approve 得到“已处理或不存在”,工具不会因此多执行一次。
+TEST_F(ImChannelsEndToEnd, TelegramPermissionApprovalAndFirstAnswerWins) {
+    std::atomic<int> deploys{0};
+    ToolDef def;
+    def.name = "deploy_preview";
+    def.description = "deploy a preview build";
+    def.parameters = json({{"type", "object"}, {"properties", {{"target", {{"type", "string"}}}}}});
+    ASSERT_TRUE(tools.register_tool(ToolImpl{def, [&](const std::string&, const ToolContext&) {
+        ++deploys;
+        return ToolResult{"deployed", true};
+    }, false}));
+    start_host();
+    connect_telegram_as_owner();
+    // 从发到私聊的最后一条确认请求里取出编号。
+    auto latest_request_id = [&]() {
+        std::string id;
+        for (const auto& call : telegram.calls_to("sendMessage")) {
+            const auto body = call.body.value("text", std::string{});
+            const auto at = body.find("/approve ");
+            if (call.body.value("chat_id", std::int64_t{0}) != 42 || at == std::string::npos) continue;
+            const auto start = at + 9;
+            const auto end = body.find_first_of(" \n<", start);
+            id = body.substr(start, end == std::string::npos ? std::string::npos : end - start);
+        }
+        return id;
+    };
+
+    provider->push_tool_call("deploy_preview", json{{"target", "staging"}}.dump(), "call-1");
+    provider->push_text("第一次部署完成");
+    telegram.push_update(telegram_message(42, "private", 42, 2, "部署一下"));
+    ASSERT_TRUE(wait_until([&] { return !latest_request_id().empty(); }));
+    const auto first = latest_request_id();
+    telegram.push_update(telegram_message(42, "private", 42, 3, "/approve " + first));
+    ASSERT_TRUE(wait_until([&] { return telegram_sent(42, "第一次部署完成"); }));
+    EXPECT_EQ(deploys.load(), 1);
+    EXPECT_TRUE(telegram_sent(42, "已允许权限请求 " + first));
+
+    provider->push_tool_call("deploy_preview", json{{"target", "prod"}}.dump(), "call-2");
+    provider->push_text("第二次部署完成");
+    telegram.push_update(telegram_message(42, "private", 42, 4, "再部署一次"));
+    ASSERT_TRUE(wait_until([&] { const auto id = latest_request_id(); return !id.empty() && id != first; }));
+    const auto second = latest_request_id();
+    client->respond_permission(bound("telegram", "42", "42"), {second, PermissionDecisionChoice::Allow});
+    ASSERT_TRUE(wait_until([&] { return telegram_sent(42, "权限请求 " + second + " 已处理"); }));
+    ASSERT_TRUE(wait_until([&] { return telegram_sent(42, "第二次部署完成"); }));
+    telegram.push_update(telegram_message(42, "private", 42, 5, "/approve " + second));
+    EXPECT_TRUE(wait_until([&] { return telegram_sent(42, "该权限请求已处理或不存在"); }));
+    EXPECT_EQ(deploys.load(), 2);
+}
+
+// 场景:用手机 QQ 扫码(门户返回扫码人 openid),扫码人私聊提问,再发一段带识别文字的语音。
+// 期望:扫码完成后凭据保存、开关自动打开并连上网关,扫码人成为机主;提问进入会话,
+// 答复以被动回复(带原消息 msg_id)发回;语音以“[语音转写] …”进入会话。
+TEST_F(ImChannelsEndToEnd, QqScanConnectsAndChatsWithVoice) {
+    int polls = 0;
+    qq.poll_bind_handler = [&](const json&) {
+        if (++polls < 2) return json{{"retcode", 0}, {"data", {{"status", 1}}}};
+        return json{{"retcode", 0},
+                    {"data", {{"status", 2}, {"bot_appid", "102030405"}, {"bot_encrypt_secret", kSecretB64},
+                              {"user_openid", "OWNER1"}}}};
+    };
+    start_host();
+    host->start_bind("qq");
+    ASSERT_TRUE(wait_until([&] { return host->bind_state("qq").value("phase", "") == "completed"; }));
+    ASSERT_TRUE(wait_until([&] { return platform("qq").value("state", "") == "connected"; }));
+    EXPECT_EQ(text(platform("qq"), "owner"), "user:OWNER1");
+    EXPECT_EQ(text(platform("qq"), "app_id"), "102030405");
+
+    provider->push_text("你好呀,我在");
+    qq.push_c2c("M1", "OWNER1", "你好");
+    ASSERT_TRUE(wait_until([&] {
+        for (const auto& request : qq.requests_to("/v2/users/OWNER1/messages"))
+            if (request.body.value("msg_id", "") == "M1" && request.body.dump().find("我在") != std::string::npos)
+                return true;
+        return false;
+    }));
+    EXPECT_TRUE(model_saw("你好"));
+
+    provider->push_text("好的,记下了");
+    qq.push_c2c("M2", "OWNER1", "", json::array({{{"content_type", "voice"},
+                                                   {"url", "https://example.invalid/voice.silk"},
+                                                   {"asr_refer_text", "明天上午开会"}}}));
+    ASSERT_TRUE(wait_until([&] { return model_saw("[语音转写] 明天上午开会"); }));
+}
+
+// 场景:扫码绑定 QQ 后,机器人在一个未批准的群里被成员 @;机主在设置页先批准群,再批准该成员。
+// 期望:群与成员分别产生待批准请求(QQ 群成员身份是 member:<群>:<成员>,与机主的私聊身份不同);
+// 两者都批准后成员的 @ 提问进入会话,答复以被动回复发回该群。
+TEST_F(ImChannelsEndToEnd, QqGroupAndMemberNeedSeparateApproval) {
+    qq.poll_bind_handler = [](const json&) {
+        return json{{"retcode", 0},
+                    {"data", {{"status", 2}, {"bot_appid", "102030405"}, {"bot_encrypt_secret", kSecretB64},
+                              {"user_openid", "OWNER1"}}}};
+    };
+    start_host();
+    host->start_bind("qq");
+    ASSERT_TRUE(wait_until([&] { return platform("qq").value("state", "") == "connected"; }));
+
+    qq.push_group_at("G1", "G1", "MEMBER1", " 帮我看看日志");
+    ASSERT_TRUE(wait_until([&] { return events_of("channels_request").size() == 1; }));
+    EXPECT_EQ(events_of("channels_request")[0].value("kind", ""), "group");
+    host->platform("qq").approve(events_of("channels_request")[0].value("id", ""), true);
+
+    qq.push_group_at("G2", "G1", "MEMBER1", " 帮我看看日志");
+    ASSERT_TRUE(wait_until([&] { return events_of("channels_request").size() == 2; }));
+    EXPECT_EQ(events_of("channels_request")[1].value("kind", ""), "member");
+    host->platform("qq").approve(events_of("channels_request")[1].value("id", ""), true);
+    EXPECT_EQ(text(platform("qq"), "owner"), "user:OWNER1");
+
+    provider->push_text("日志看过了");
+    qq.push_group_at("G3", "G1", "MEMBER1", " 帮我看看日志");
+    ASSERT_TRUE(wait_until([&] {
+        for (const auto& request : qq.requests_to("/v2/groups/G1/messages"))
+            if (request.body.value("msg_id", "") == "G3" && request.body.dump().find("日志看过了") != std::string::npos)
+                return true;
+        return false;
+    }));
+    EXPECT_FALSE(bound("qq", "G1", "MEMBER1").empty());
+}
+
+// 场景:扫码人私聊发来一张图片。
+// 期望:图片按附件地址带 QQBot 令牌下载,导入会话附件,并与文字说明一起进入会话。
+TEST_F(ImChannelsEndToEnd, QqImageBecomesSessionAttachment) {
+    qq.poll_bind_handler = [](const json&) {
+        return json{{"retcode", 0},
+                    {"data", {{"status", 2}, {"bot_appid", "102030405"}, {"bot_encrypt_secret", kSecretB64},
+                              {"user_openid", "OWNER1"}}}};
+    };
+    start_host();
+    host->start_bind("qq");
+    ASSERT_TRUE(wait_until([&] { return platform("qq").value("state", "") == "connected"; }));
+
+    provider->push_text("图片收到了");
+    qq.push_c2c("M1", "OWNER1", "看看这张截图",
+                json::array({{{"content_type", "image/png"}, {"filename", "shot.png"},
+                              {"url", qq.base() + "/download/shot"}, {"size", 16}}}));
+    ASSERT_TRUE(wait_until([&] {
+        for (const auto& request : qq.requests_to("/v2/users/OWNER1/messages"))
+            if (request.body.dump().find("图片收到了") != std::string::npos) return true;
+        return false;
+    }));
+    const auto downloads = qq.requests_to("/download/shot");
+    ASSERT_EQ(downloads.size(), 1u);
+    EXPECT_EQ(downloads[0].authorization.rfind("QQBot ", 0), 0u);
+    EXPECT_TRUE(model_saw("看看这张截图"));
+    const auto session = bound("qq", "OWNER1", "OWNER1");
+    bool has_attachment = false;
+    for (const auto& info : client->list_sessions()) {
+        if (info.id != session) continue;
+        const auto dir = path_from_utf8(SessionStorage::get_project_dir(info.cwd)) / "attachments" / session;
+        has_attachment = fs::exists(dir) && !fs::is_empty(dir);
+    }
+    EXPECT_TRUE(has_attachment);
+}
+
+// 场景:QQ 被动与主动回复都被平台拒绝(超出回复窗口且主动消息被关),之后对方又发来一条消息。
+// 期望:那一回合的答复先暂存(快照显示 1 条待补发);下一条消息到达时先以“(补发)”补发,
+// 再处理新消息。
+TEST_F(ImChannelsEndToEnd, QqHeldOutputIsResentOnNextMessage) {
+    qq.poll_bind_handler = [](const json&) {
+        return json{{"retcode", 0},
+                    {"data", {{"status", 2}, {"bot_appid", "102030405"}, {"bot_encrypt_secret", kSecretB64},
+                              {"user_openid", "OWNER1"}}}};
+    };
+    std::atomic<bool> reject{false};
+    qq.message_handler = [&](const acecode::test::FakeQqServer::Request&) {
+        if (reject) return std::make_pair(403, json{{"code", 304}, {"message", "reply window closed"}});
+        return std::make_pair(200, json{{"id", "R"}});
+    };
+    start_host();
+    host->start_bind("qq");
+    ASSERT_TRUE(wait_until([&] { return platform("qq").value("state", "") == "connected"; }));
+
+    reject = true;
+    provider->push_text("迟到的答复");
+    qq.push_c2c("M1", "OWNER1", "第一个问题");
+    ASSERT_TRUE(wait_until([&] { return platform("qq")["extra"].value("held", 0) == 1; }));
+
+    reject = false;
+    provider->push_text("新的答复");
+    qq.push_c2c("M2", "OWNER1", "第二个问题");
+    ASSERT_TRUE(wait_until([&] {
+        bool resent = false, fresh = false;
+        for (const auto& request : qq.requests_to("/v2/users/OWNER1/messages")) {
+            const auto body = request.body.dump();
+            if (body.find("(补发)") != std::string::npos && body.find("迟到的答复") != std::string::npos) resent = true;
+            if (body.find("新的答复") != std::string::npos) fresh = true;
+        }
+        return resent && fresh;
+    }));
+    EXPECT_EQ(platform("qq")["extra"].value("held", -1), 0);
+}
+
+// 场景:设置页点「连接」开始微信扫码,用户扫码并在手机上确认;机主随后私聊提问。
+// 期望:扫码过程中快照给出二维码内容;确认后保存 bot_token / bot_id / baseurl、扫码人成为机主、
+// 自动启用并连接;私聊消息进入会话,答复用该用户的 context_token 发回(纯文本,不带 Markdown)。
+TEST_F(ImChannelsEndToEnd, WeixinScanLoginBindsOwnerAndChats) {
+    weixin = std::make_unique<acecode::test::FakeWeixinServer>();
+    std::atomic<int> polls{0};
+    weixin->qr_status_handler = [&](const acecode::test::FakeWeixinServer::Call&) {
+        if (++polls < 3) return json{{"ret", 0}, {"status", "wait"}};
+        return json{{"ret", 0},
+                    {"status", "confirmed"},
+                    {"bot_token", weixin->token()},
+                    {"ilink_bot_id", "e06c1ceea05e@im.bot"},
+                    {"baseurl", weixin->base()},
+                    {"ilink_user_id", "owner@im.wechat"}};
+    };
+    start_host();
+    host->start_bind("weixin");
+    ASSERT_TRUE(wait_until([&] {
+        return host->bind_state("weixin").value("qr_url", std::string{}).find("liteapp.weixin.qq.com") !=
+               std::string::npos;
+    })) << host->bind_state("weixin").dump();
+    ASSERT_TRUE(wait_until([&] { return platform("weixin").value("state", "") == "connected"; }))
+        << platform("weixin").dump(2);
+    EXPECT_EQ(text(platform("weixin"), "owner"), "user:owner@im.wechat");
+    EXPECT_EQ(platform("weixin").value("account", ""), "e06c1ceea05e@im.bot");
+
+    provider->push_text("**收到**,我是 ACECode");
+    weixin->push_text("owner@im.wechat", "你好", 7001, "ctx-owner");
+    ASSERT_TRUE(wait_until([&] {
+        for (const auto& call : weixin->calls_to("sendmessage")) {
+            const auto& msg = call.body["msg"];
+            if (msg.value("to_user_id", "") != "owner@im.wechat") continue;
+            const auto said = msg["item_list"][0]["text_item"].value("text", "");
+            if (said.find("收到,我是 ACECode") != std::string::npos && msg.value("context_token", "") == "ctx-owner")
+                return true;
+        }
+        return false;
+    }));
+    EXPECT_TRUE(model_saw("你好"));
+    EXPECT_FALSE(bound("weixin", "owner@im.wechat", "owner@im.wechat").empty());
+}
+
+// 场景:设置页填写钉钉 Client ID / Secret 并连接;向导给出 6 位绑定码,用户私聊机器人发送它,
+// 然后提问。期望:凭据经取 token 与试注册 Stream 校验后保存并连接;绑定码的发送者成为机主、
+// 收到确认且这条消息不进会话;提问进入会话,答复经该消息带来的会话 webhook 以 Markdown 发回。
+TEST_F(ImChannelsEndToEnd, DingTalkOwnerCodeBindsAndRepliesThroughWebhook) {
+    dingtalk = std::make_unique<acecode::test::FakeDingTalkServer>();
+    start_host();
+    auto& runtime = host->platform("dingtalk");
+    EXPECT_THROW(runtime.set_credentials({{"client_id", dingtalk->client_id}, {"client_secret", "wrong-secret-0"}}),
+                 std::runtime_error);
+    runtime.set_credentials({{"client_id", dingtalk->client_id}, {"client_secret", dingtalk->client_secret}});
+    runtime.set_enabled(true);
+    ASSERT_TRUE(wait_until([&] { return platform("dingtalk").value("state", "") == "connected"; }))
+        << platform("dingtalk").dump(2);
+    const auto code = host->owner_link("dingtalk").value("code", std::string{});
+    ASSERT_EQ(code.size(), 6u);
+
+    dingtalk->push_callback("H1", dingtalk->private_text("m1", "staff01", code));
+    ASSERT_TRUE(wait_until([&] { return text(platform("dingtalk"), "owner") == "user:staff01"; }));
+    const auto sent_through_webhook = [&](const std::string& needle) {
+        for (const auto& request : dingtalk->requests_to("/robot/sendBySession"))
+            if (request.body.dump().find(needle) != std::string::npos) return true;
+        return false;
+    };
+    EXPECT_TRUE(wait_until([&] { return sent_through_webhook("已绑定为机主"); }));
+    EXPECT_FALSE(model_saw(code));
+
+    provider->push_text("**收到**,我是 ACECode");
+    dingtalk->push_callback("H2", dingtalk->private_text("m2", "staff01", "你好"));
+    ASSERT_TRUE(wait_until([&] { return sent_through_webhook("**收到**,我是 ACECode"); }));
+    EXPECT_TRUE(model_saw("你好"));
+    EXPECT_TRUE(dingtalk->has_ack("H2"));
+}
+
+// 场景:设置页粘贴 Discord Bot Token 并连接;用户私信机器人发送绑定码,再私信提问。
+// 期望:token 经 /users/@me 校验后保存,并带回机器人 id 与应用 id(邀请链接要用);网关 Identify
+// 后连接;绑定码的发送者成为机主;提问进入会话,答复以 Markdown 原样发到该私信频道。
+TEST_F(ImChannelsEndToEnd, DiscordOwnerCodeBindsAndChatsInDm) {
+    discord = std::make_unique<acecode::test::FakeDiscordServer>();
+    start_host();
+    auto& runtime = host->platform("discord");
+    EXPECT_THROW(runtime.set_credentials({{"token", "not-a-valid-token"}}), std::runtime_error);
+    runtime.set_credentials({{"token", discord->token}});
+    const auto saved = platform("discord")["credentials_public"];
+    EXPECT_EQ(saved.value("bot_id", ""), discord->bot_id) << saved.dump();
+    EXPECT_EQ(saved.value("application_id", ""), discord->application_id);
+    runtime.set_enabled(true);
+    ASSERT_TRUE(wait_until([&] { return platform("discord").value("state", "") == "connected"; }))
+        << platform("discord").dump(2);
+    const auto code = host->owner_link("discord").value("code", std::string{});
+    ASSERT_EQ(code.size(), 6u);
+
+    const std::string user = "800000000000000042";
+    const auto dm = "/channels/" + acecode::test::FakeDiscordServer::dm_channel_for(user) + "/messages";
+    const auto sent_to_dm = [&](const std::string& needle) {
+        for (const auto& request : discord->requests_to("POST", dm))
+            if (request.body.value("content", std::string{}).find(needle) != std::string::npos) return true;
+        return false;
+    };
+    discord->push_dm("100000000000000001", user, code);
+    ASSERT_TRUE(wait_until([&] { return text(platform("discord"), "owner") == "user:" + user; }));
+    EXPECT_TRUE(wait_until([&] { return sent_to_dm("已绑定为机主"); }));
+
+    provider->push_text("**收到**,我是 ACECode");
+    discord->push_dm("100000000000000002", user, "你好");
+    ASSERT_TRUE(wait_until([&] { return sent_to_dm("**收到**,我是 ACECode"); }));
+    EXPECT_TRUE(model_saw("你好"));
+}
+
+// 场景:设置页填写飞书 App ID / Secret 并连接;用户私聊机器人发送绑定码,再提问。
+// 期望:凭据经 tenant 令牌与机器人信息校验后保存,长连接建立后连接;绑定码的发送者(open_id)
+// 成为机主并收到确认;提问进入会话,答复以回复原消息的方式发回;每个事件帧都被 ACK。
+TEST_F(ImChannelsEndToEnd, FeishuOwnerCodeBindsAndRepliesToMessage) {
+    feishu = std::make_unique<acecode::test::FakeFeishuServer>();
+    start_host();
+    auto& runtime = host->platform("feishu");
+    runtime.set_credentials({{"app_id", "cli_app"}, {"app_secret", "secret-value-123"}});
+    runtime.set_enabled(true);
+    ASSERT_TRUE(wait_until([&] { return platform("feishu").value("state", "") == "connected"; }))
+        << platform("feishu").dump(2);
+    const auto code = host->owner_link("feishu").value("code", std::string{});
+    ASSERT_EQ(code.size(), 6u);
+
+    const auto p2p = [](const std::string& id, const std::string& said) {
+        return acecode::test::FakeFeishuServer::message_event(id, "p2p", "oc_p2p", "ou_owner", "text",
+                                                              {{"text", said}});
+    };
+    const auto sent = [&](const std::string& needle) {
+        for (const auto& request : feishu->sends())
+            if (request.raw.find(needle) != std::string::npos || request.body.dump().find(needle) != std::string::npos)
+                return true;
+        return false;
+    };
+    feishu->push_event(p2p("om_1", code));
+    ASSERT_TRUE(wait_until([&] { return text(platform("feishu"), "owner") == "user:ou_owner"; }));
+    EXPECT_TRUE(wait_until([&] { return sent("已绑定为机主"); }));
+
+    provider->push_text("收到,我是 ACECode");
+    feishu->push_event(p2p("om_2", "你好"));
+    ASSERT_TRUE(wait_until([&] { return sent("收到,我是 ACECode"); }));
+    EXPECT_TRUE(model_saw("你好"));
+    EXPECT_FALSE(feishu->requests_to("/open-apis/im/v1/messages/om_2/reply").empty());
+    EXPECT_TRUE(wait_until([&] { return feishu->frames_of_type("event").size() >= 2; }));
+}
+
+// 场景:设置页填写 LINE Channel ID / secret 并连接(公网地址指向本机回调端口);用户私聊官方账号
+// 发送绑定码,再提问。期望:凭据经换令牌与机器人信息校验后保存并带回机器人 userId;回调地址
+// 登记给 LINE 后连接;带签名的 webhook 里绑定码的发送者成为机主;提问进入会话,答复用这条消息
+// 的回复令牌发回(免费的 reply,不用 push)。
+TEST_F(ImChannelsEndToEnd, LineOwnerCodeBindsAndRepliesWithReplyToken) {
+    using acecode::test::FakeLineServer;
+    line = std::make_unique<FakeLineServer>();
+    line_port = im::line::pick_free_loopback_port();
+    start_host();
+    auto& runtime = host->platform("line");
+    runtime.set_credentials({{"channel_id", FakeLineServer::kChannelId}, {"channel_secret", FakeLineServer::kSecret}});
+    EXPECT_EQ(platform("line")["credentials_public"].value("bot_id", ""), FakeLineServer::kBotId);
+    runtime.set_enabled(true);
+    ASSERT_TRUE(wait_until([&] { return platform("line").value("state", "") == "connected"; }))
+        << platform("line").dump(2);
+    EXPECT_EQ(line->endpoint(), "http://127.0.0.1:" + std::to_string(line_port) + "/line/webhook");
+    const auto code = host->owner_link("line").value("code", std::string{});
+    ASSERT_EQ(code.size(), 6u);
+
+    const std::string user = "U11111111111111111111111111111111";
+    const auto webhook = "http://127.0.0.1:" + std::to_string(line_port) + "/line/webhook";
+    const auto say = [&](const std::string& said, const std::string& id) {
+        const auto token = line->issue_reply_token();
+        const auto body = FakeLineServer::webhook_body(
+            {FakeLineServer::text_event(FakeLineServer::source("user", "", user), said, id, token, "ev-" + id)});
+        EXPECT_EQ(FakeLineServer::post_webhook(webhook, body).status, 200);
+    };
+    const auto replied = [&](const std::string& needle) {
+        for (const auto& call : line->calls_to("POST", "/v2/bot/message/reply"))
+            if (call.body.dump().find(needle) != std::string::npos) return true;
+        return false;
+    };
+    say(code, "m1");
+    ASSERT_TRUE(wait_until([&] { return text(platform("line"), "owner") == "user:" + user; }));
+    EXPECT_TRUE(wait_until([&] { return replied("已绑定为机主"); }));
+
+    provider->push_text("收到,我是 ACECode");
+    say("你好", "m2");
+    ASSERT_TRUE(wait_until([&] { return replied("收到,我是 ACECode"); }));
+    EXPECT_TRUE(model_saw("你好"));
+    EXPECT_TRUE(line->calls_to("POST", "/v2/bot/message/push").empty());
+}
+
+} // namespace
+} // namespace acecode::daemon
diff --git a/tests/desktop/desktop_pet_layout_test.cpp b/tests/desktop/desktop_pet_layout_test.cpp
new file mode 100644
index 000000000..f81a02e05
--- /dev/null
+++ b/tests/desktop/desktop_pet_layout_test.cpp
@@ -0,0 +1,258 @@
+// 桌面宠物(像素办公室 demo)窗口几何的纯逻辑测试(可移植)。
+//
+// Win32 透明窗口 + WebView2 只能在 Windows 实机看效果,但下面这些决定
+// 「窗口多大、贴在哪、哪里能点」的算术在这里锁住:
+//   1. 整数倍缩放随 DPI 取值(场景 344×252 像素,整数倍才不糊);
+//   2. 小屏幕上缩放逐级回退,窗口不超过工作区一半;
+//   3. 贴工作区右下角并留 8 个逻辑像素边距(工作区已扣任务栏,可能不从 0 开始);
+//   4. 用户拖动过之后 DPI 变化只换尺寸、不跳回角落,且不被推出屏幕;
+//   5. 命中区域是房间外包六边形:透明角落不接点击,房间内部都能点到;
+//   6. 用户缩放的上下限(逻辑 0.5 倍到工作区 90%);
+//   7. 用户调过的大小跨 DPI 按逻辑倍数换算;
+//   8. 滚轮 / 把手缩放时锚点不动,放不下时推回工作区;
+//   9. 小数倍缩放时命中区域按四舍五入换算;
+//  10. 页面上报的浮层(成员列表 / 提示 / 状态气泡)解析:坏数据整条丢弃、坐标夹紧、条数有上限;
+//  11. 点击命中判定(macOS 用它切换点击穿透):房间、控制条、浮层命中,透明角落穿透。
+
+#include <gtest/gtest.h>
+
+#include "desktop/desktop_pet_layout.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <cmath>
+#include <vector>
+
+using namespace acecode::desktop;
+
+namespace {
+
+// 射线法判断点是否在多边形内部,只给测试用。
+bool inside(const std::vector<DesktopPetPoint>& polygon, int x, int y) {
+    bool result = false;
+    for (std::size_t i = 0, j = polygon.size() - 1; i < polygon.size(); j = i++) {
+        const auto& a = polygon[i];
+        const auto& b = polygon[j];
+        if ((a.y > y) != (b.y > y)) {
+            const double cross = a.x + static_cast<double>(y - a.y) * (b.x - a.x) / (b.y - a.y);
+            if (x < cross) result = !result;
+        }
+    }
+    return result;
+}
+
+constexpr DesktopPetRect kFullHd{0, 0, 1920, 1040};
+
+} // namespace
+
+// 场景 1:常见 DPI 下的缩放倍数。
+// 触发:工作区足够大(1920×1040),DPI 取 96/120/144/168/192。
+// 期望:round(dpi/96 × 1.25) → 1/2/2/2/3。96 DPI 时 1.25 四舍五入为 1(344px 宽),
+// 192 DPI 时 2.5 进位为 3(逻辑宽度约 516px),都在「约 430 逻辑像素」附近。
+TEST(DesktopPetLayout, ScaleFollowsDpiWithIntegerSteps) {
+    EXPECT_EQ(desktop_pet_scale(96, 3840, 2160), 1);
+    EXPECT_EQ(desktop_pet_scale(120, 3840, 2160), 2);
+    EXPECT_EQ(desktop_pet_scale(144, 3840, 2160), 2);
+    EXPECT_EQ(desktop_pet_scale(168, 3840, 2160), 2);
+    EXPECT_EQ(desktop_pet_scale(192, 3840, 2160), 3);
+}
+
+// 场景 1b:拿不到 DPI(0 或负数)时按 96 处理,不能算出 0 倍窗口。
+TEST(DesktopPetLayout, InvalidDpiFallsBackToBase) {
+    EXPECT_EQ(desktop_pet_scale(0, 1920, 1040), 1);
+    EXPECT_EQ(desktop_pet_scale(-5, 1920, 1040), 1);
+}
+
+// 场景 2:小工作区上缩放回退。
+// 触发:192 DPI 本该取 3 倍(1032×756),但工作区只有 1366×728。
+// 期望:3 倍宽 1032 > 683(一半宽)→ 退到 2 倍(688 > 683 仍超)→ 1 倍。
+// 回退到 1 为止,再小也不会出现 0 倍。
+TEST(DesktopPetLayout, ScaleShrinksToFitHalfOfWorkArea) {
+    EXPECT_EQ(desktop_pet_scale(192, 1366, 728), 1);
+    EXPECT_EQ(desktop_pet_scale(192, 1600, 1080), 2);   // 688 ≤ 800、504 ≤ 450
+    EXPECT_EQ(desktop_pet_scale(192, 100, 100), 1);
+}
+
+// 场景 3:贴右下角。
+// 触发:96 DPI、工作区 1920×1040(底部 40px 是任务栏,已被扣掉)。
+// 期望:窗口 344×252,右边距与下边距都是 8px → x = 1920-344-8,y = 1040-252-8。
+TEST(DesktopPetLayout, PlacesAtBottomRightWithMargin) {
+    const auto placement = place_desktop_pet(kFullHd, 96);
+    EXPECT_EQ(placement.scale, 1);
+    EXPECT_EQ(placement.window.width, 344);
+    EXPECT_EQ(placement.window.height, 252);
+    EXPECT_EQ(placement.window.x, 1920 - 344 - 8);
+    EXPECT_EQ(placement.window.y, 1040 - 252 - 8);
+}
+
+// 场景 3b:工作区不从原点开始(任务栏在左侧/顶部,或副屏在主屏左边为负坐标)。
+// 触发:工作区 {-1920, 60, 1920, 1020},144 DPI(边距 8×1.5=12px,2 倍窗口 688×504)。
+// 期望:右下角按工作区自身的右/下边算,而不是按屏幕原点。
+TEST(DesktopPetLayout, PlacementRespectsOffsetWorkArea) {
+    const auto placement = place_desktop_pet({-1920, 60, 1920, 1020}, 144);
+    EXPECT_EQ(placement.scale, 2);
+    EXPECT_EQ(placement.window.x, -1920 + 1920 - 688 - 12);
+    EXPECT_EQ(placement.window.y, 60 + 1020 - 504 - 12);
+}
+
+// 场景 4:拖动过之后换 DPI(比如拖到另一块屏)。
+// 触发 a:1080p 工作区,左上角 (100, 120),新 DPI 144 → 2 倍 688×504,原位放得下。
+// 触发 b:4K 工作区 3840×2080,左上角 (3500, 1900),新 DPI 192 → 3 倍 1032×756。
+// 期望:左上角尽量不动;原位置放不下新尺寸时往回推,整个窗口留在工作区内
+// (x ≤ 3840-1032,y ≤ 2080-756),不会一半跑到屏幕外。
+TEST(DesktopPetLayout, ResizeKeepsOriginButStaysInsideWorkArea) {
+    const auto kept = resize_desktop_pet({100, 120, 344, 252}, 144, kFullHd);
+    EXPECT_EQ(kept.scale, 2);
+    EXPECT_EQ(kept.window.x, 100);
+    EXPECT_EQ(kept.window.y, 120);
+    EXPECT_EQ(kept.window.width, 688);
+
+    const auto pushed = resize_desktop_pet({3500, 1900, 344, 252}, 192, {0, 0, 3840, 2080});
+    EXPECT_EQ(pushed.scale, 3);
+    EXPECT_EQ(pushed.window.x, 3840 - 1032);
+    EXPECT_EQ(pushed.window.y, 2080 - 756);
+}
+
+// 场景 5:命中区域 = 房间外包六边形。
+// 触发:1 倍缩放下取多边形,再按 2 倍取一次。
+// 期望:
+//   - 6 个顶点、全部落在 344×252 画布内;
+//   - 画布四个透明角(原来的草地)都在多边形外 → 点击穿透到后面的窗口;
+//   - 房间地板中心、左墙门口、后墙窗户、最前面的柜台这些有内容的点都在多边形内;
+//   - 2 倍缩放的顶点恰好是 1 倍的两倍(窗口区域按设备像素给)。
+TEST(DesktopPetLayout, HitPolygonCoversRoomAndLeavesCornersOpen) {
+    const auto polygon = desktop_pet_hit_polygon(1);
+    ASSERT_EQ(polygon.size(), 6u);
+    for (const auto& point : polygon) {
+        EXPECT_GE(point.x, 0);
+        EXPECT_LE(point.x, kDesktopPetSceneWidth);
+        EXPECT_GE(point.y, 0);
+        EXPECT_LE(point.y, kDesktopPetSceneHeight);
+    }
+
+    EXPECT_FALSE(inside(polygon, 2, 2)) << "左上角是透明草地,不该接点击";
+    EXPECT_FALSE(inside(polygon, 340, 2)) << "右上角是透明草地";
+    EXPECT_FALSE(inside(polygon, 2, 248)) << "左下角是透明草地";
+    EXPECT_FALSE(inside(polygon, 340, 248)) << "右下角是透明草地";
+
+    EXPECT_TRUE(inside(polygon, 172, 162)) << "地板中间";
+    EXPECT_TRUE(inside(polygon, 30, 142)) << "左墙上的门";
+    EXPECT_TRUE(inside(polygon, 240, 92)) << "后墙的窗户";
+    EXPECT_TRUE(inside(polygon, 188, 237)) << "房间最前面的柜台";
+
+    const auto doubled = desktop_pet_hit_polygon(2);
+    ASSERT_EQ(doubled.size(), polygon.size());
+    for (std::size_t i = 0; i < polygon.size(); ++i) {
+        EXPECT_EQ(doubled[i].x, polygon[i].x * 2);
+        EXPECT_EQ(doubled[i].y, polygon[i].y * 2);
+    }
+}
+
+// 场景 6:缩放上下限。
+// 触发:96 DPI、1920×1040 工作区,分别请求 0.1 倍、10 倍、2.3 倍和 NaN。
+// 期望:下限 = 逻辑 0.5 倍(96 DPI 下就是 0.5);上限 = min(1920×0.9/344, 1040×0.9/252),
+// 这里高度先顶到(约 4.2545);中间值原样返回;NaN 当成下限,不能让窗口尺寸变成非法值。
+// 192 DPI 时下限跟着变成 1.0(仍是逻辑 0.5 倍,172 逻辑像素宽)。
+TEST(DesktopPetLayout, ClampKeepsScaleBetweenHalfAndNinetyPercent) {
+    EXPECT_DOUBLE_EQ(clamp_desktop_pet_scale(0.1, 96, kFullHd), 0.5);
+    EXPECT_NEAR(clamp_desktop_pet_scale(10.0, 96, kFullHd), 1040 * 0.9 / 252, 1e-9);
+    EXPECT_DOUBLE_EQ(clamp_desktop_pet_scale(2.3, 96, kFullHd), 2.3);
+    EXPECT_DOUBLE_EQ(clamp_desktop_pet_scale(std::nan(""), 96, kFullHd), 0.5);
+    EXPECT_DOUBLE_EQ(clamp_desktop_pet_scale(0.2, 192, {0, 0, 3840, 2080}), 1.0);
+}
+
+// 场景 7:用户调过大小(逻辑 1.25 倍)后在 144 DPI 下摆放。
+// 期望:设备倍数 = 1.25 × 144/96 = 1.875,窗口 645×473(472.5 四舍五入),
+// 仍贴右下角,边距 12px;请求超大时被夹到上限,高度正好是工作区的 90%(936)。
+TEST(DesktopPetLayout, PreferredLogicalScaleFollowsDpi) {
+    const auto placement = place_desktop_pet(kFullHd, 144, 1.25);
+    EXPECT_DOUBLE_EQ(placement.scale, 1.875);
+    EXPECT_EQ(placement.window.width, 645);
+    EXPECT_EQ(placement.window.height, 473);
+    EXPECT_EQ(placement.window.x, 1920 - 645 - 12);
+    EXPECT_EQ(placement.window.y, 1040 - 473 - 12);
+
+    const auto huge = place_desktop_pet(kFullHd, 96, 20.0);
+    EXPECT_EQ(huge.window.height, 936);
+    EXPECT_LE(huge.window.width, 1920);
+}
+
+// 场景 8:以锚点缩放。
+// 触发:窗口 {1000, 500, 344×252} 放大到 2 倍。
+// 期望:锚点 (1, 1)(停靠右下角时)→ 右下角 (1344, 720) 不动,新窗口左上角 (656, 280);
+// 锚点 (0.5, 0.5)(鼠标在正中滚轮)→ 中心 (1172, 610) 不动,左上角 (828, 390);
+// 锚点 (0, 0) 但右下方放不下 → 整个窗口推回工作区内,不会有一半跑出屏幕。
+TEST(DesktopPetLayout, ScaleAroundAnchorKeepsPointFixed) {
+    const DesktopPetRect current{1000, 500, 344, 252};
+    const auto corner = scale_desktop_pet(current, 2.0, 1.0, 1.0, kFullHd);
+    EXPECT_EQ(corner.window.width, 688);
+    EXPECT_EQ(corner.window.height, 504);
+    EXPECT_EQ(corner.window.x, 656);
+    EXPECT_EQ(corner.window.y, 248);
+
+    const auto center = scale_desktop_pet(current, 2.0, 0.5, 0.5, kFullHd);
+    EXPECT_EQ(center.window.x, 828);
+    EXPECT_EQ(center.window.y, 374);
+
+    const auto pushed = scale_desktop_pet({1500, 700, 344, 252}, 2.0, 0.0, 0.0, kFullHd);
+    EXPECT_EQ(pushed.window.x, 1920 - 688);
+    EXPECT_EQ(pushed.window.y, 1040 - 504);
+}
+
+// 场景 9:小数倍缩放(1.5 倍)时的命中区域。
+// 期望:每个顶点等于 1 倍顶点 × 1.5 后四舍五入,窗口区域和画面按同一比例对齐。
+TEST(DesktopPetLayout, HitPolygonSupportsFractionalScale) {
+    const auto base = desktop_pet_hit_polygon(1.0);
+    const auto scaled = desktop_pet_hit_polygon(1.5);
+    ASSERT_EQ(scaled.size(), base.size());
+    for (std::size_t i = 0; i < base.size(); ++i) {
+        EXPECT_EQ(scaled[i].x, static_cast<int>(std::lround(base[i].x * 1.5)));
+        EXPECT_EQ(scaled[i].y, static_cast<int>(std::lround(base[i].y * 1.5)));
+    }
+}
+
+// 场景:页面发来 overlay 消息,rect 是成员列表 / 提示的外包框,bubbles 是状态气泡列表,
+// 其中混着越界坐标、NaN 以外的非数字、宽度为 0 的矩形和超量条目。
+// 期望:越界坐标夹到 [0,1];非数字、空矩形整条丢弃;rect=null 时只取气泡;
+// 总数不超过 kDesktopPetMaxOverlays。
+// 回归:修复前原生端只认一个 rect,冒出墙顶的气泡被窗口区域裁掉、也点不到。
+TEST(DesktopPetLayout, OverlayMessageKeepsValidRectsOnly) {
+    const auto overlays = desktop_pet_overlays_from_message(nlohmann::json{
+        {"type", "overlay"},
+        {"rect", {0.1, 0.2, 0.5, 0.6}},
+        {"bubbles", nlohmann::json::array({
+            nlohmann::json::array({-0.2, 0.1, 0.3, 1.4}),
+            nlohmann::json::array({0.4, "x", 0.5, 0.6}),
+            nlohmann::json::array({0.4, 0.4, 0.4, 0.6}),
+            nlohmann::json::array({0.6, 0.1, 0.7})})}});
+    ASSERT_EQ(overlays.size(), 2u);
+    EXPECT_DOUBLE_EQ(overlays[1][0], 0.0) << "左边越界夹到 0";
+    EXPECT_DOUBLE_EQ(overlays[1][3], 1.0) << "下边越界夹到 1";
+
+    const auto bubbles_only = desktop_pet_overlays_from_message(nlohmann::json{
+        {"type", "overlay"}, {"rect", nullptr},
+        {"bubbles", nlohmann::json::array({nlohmann::json::array({0.2, 0.2, 0.3, 0.3})})}});
+    ASSERT_EQ(bubbles_only.size(), 1u);
+
+    nlohmann::json many = nlohmann::json::array();
+    for (int i = 0; i < 40; ++i) many.push_back({0.1, 0.1, 0.2, 0.2});
+    EXPECT_EQ(desktop_pet_overlays_from_message({{"bubbles", many}}).size(), kDesktopPetMaxOverlays);
+    EXPECT_TRUE(desktop_pet_overlays_from_message(nlohmann::json::array()).empty());
+}
+
+// 场景:1.25 倍(430×315)窗口,依次点:房间中央、顶部控制条、左上透明角落、
+// 左上角落里一个上报过的气泡、窗口外。
+// 期望:房间 / 控制条 / 气泡命中;没有浮层的透明角落与窗口外不命中(点击应穿透)。
+TEST(DesktopPetLayout, HitTestCoversRoomToolbarAndOverlays) {
+    const double scale = 1.25;
+    const int width = 430, height = 315;
+    const std::vector<DesktopPetOverlay> none;
+    EXPECT_TRUE(desktop_pet_hit_test(scale, width, height, none, 215, 200)) << "房间中央";
+    EXPECT_TRUE(desktop_pet_hit_test(scale, width, height, none, 400, 10)) << "顶部控制条";
+    EXPECT_FALSE(desktop_pet_hit_test(scale, width, height, none, 6, 60)) << "左上透明角落";
+    EXPECT_FALSE(desktop_pet_hit_test(scale, width, height, none, 6, 310)) << "左下透明角落";
+    const std::vector<DesktopPetOverlay> bubble{{0.0, 0.15, 0.1, 0.25}};
+    EXPECT_TRUE(desktop_pet_hit_test(scale, width, height, bubble, 6, 60)) << "角落里的气泡";
+    EXPECT_FALSE(desktop_pet_hit_test(scale, width, height, bubble, -1, 60)) << "窗口外";
+    EXPECT_FALSE(desktop_pet_hit_test(scale, width, height, bubble, 430, 60)) << "右边界外";
+}
diff --git a/tests/im/dingtalk_api_test.cpp b/tests/im/dingtalk_api_test.cpp
new file mode 100644
index 000000000..057e49d38
--- /dev/null
+++ b/tests/im/dingtalk_api_test.cpp
@@ -0,0 +1,202 @@
+#include <gtest/gtest.h>
+
+#include "im/dingtalk/dingtalk_api.hpp"
+#include "test_support/im/fake_dingtalk_server.hpp"
+
+#include <fstream>
+
+// im/dingtalk/dingtalk_api:钉钉 HTTP 客户端对本机假开放平台的端到端测试 —— 令牌缓存与失效重试、
+// 凭据校验的三种失败、两套错误形态、webhook 白名单、媒体上传与 OSS 下载。
+
+namespace acecode::im::dingtalk {
+namespace {
+
+ApiOptions local_options(test::FakeDingTalkServer& server) {
+    ApiOptions options;
+    options.client_id = server.client_id;
+    options.client_secret = server.client_secret;
+    options.api_base = server.base();
+    options.oapi_base = server.base();
+    options.use_proxy = false;
+    return options;
+}
+
+// 场景:连续两次调用群发接口,之后令牌在平台侧被作废,再调用一次。
+// 期望:前两次复用同一个令牌(只换一次);作废后第一次请求返回 InvalidAuthentication,
+// 客户端清掉缓存换新令牌并重试一次成功;令牌放在 x-acs-dingtalk-access-token 头里。
+TEST(DingTalkApi, CachesTokenAndRefreshesOnceWhenInvalid) {
+    test::FakeDingTalkServer server;
+    Api api(local_options(server));
+    EXPECT_TRUE(api.send_group("dingR", "cid1", "sampleText", {{"content", "a"}}).ok);
+    EXPECT_TRUE(api.send_group("dingR", "cid1", "sampleText", {{"content", "b"}}).ok);
+    EXPECT_EQ(server.token_calls(), 1);
+    server.revoke_token("tok-1");
+    const auto result = api.send_group("dingR", "cid1", "sampleText", {{"content", "c"}});
+    EXPECT_TRUE(result.ok) << result.error.message;
+    EXPECT_EQ(server.token_calls(), 2);
+    const auto sent = server.requests_to("/v1.0/robot/groupMessages/send");
+    ASSERT_EQ(sent.size(), 4u);
+    EXPECT_EQ(sent[2].token, "tok-1");
+    EXPECT_EQ(sent[3].token, "tok-2");
+    // msgParam 是 JSON 字符串而不是对象(平台要求二次编码)。
+    ASSERT_TRUE(sent[3].body["msgParam"].is_string());
+    EXPECT_EQ(nlohmann::json::parse(sent[3].body["msgParam"].get<std::string>())["content"], "c");
+    EXPECT_EQ(sent[3].body["openConversationId"], "cid1");
+}
+
+// 场景:用户填错了 Client Secret 后点“保存”。
+// 期望:校验失败且标记为凭据无效(不是网络问题);中文原因指向“凭证与基础信息”;不含密钥原文。
+TEST(DingTalkApi, VerifyReportsInvalidCredentials) {
+    test::FakeDingTalkServer server;
+    auto options = local_options(server);
+    options.client_secret = "wrong-secret-value-999";
+    const auto result = Api(options).verify();
+    EXPECT_FALSE(result.ok);
+    EXPECT_TRUE(result.auth_failed);
+    EXPECT_FALSE(result.network);
+    EXPECT_NE(result.error.find(u8"Client Secret"), std::string::npos);
+    EXPECT_EQ(result.error.find("wrong-secret-value-999"), std::string::npos);
+}
+
+// 场景:凭据正确、应用已发布,用户点“保存”。
+// 期望:校验成功,返回 Client ID 与默认机器人编码(与 Client ID 相同);做过一次 Stream 注册
+// 但不建立 WebSocket 连接(ticket 90 秒后自然失效)。
+TEST(DingTalkApi, VerifySucceedsWithoutOpeningAConnection) {
+    test::FakeDingTalkServer server;
+    const auto result = Api(local_options(server)).verify();
+    EXPECT_TRUE(result.ok) << result.error;
+    EXPECT_EQ(result.client_id, server.client_id);
+    EXPECT_EQ(result.robot_code, server.client_id);
+    EXPECT_EQ(server.issued_tickets().size(), 1u);
+    EXPECT_EQ(server.connections(), 0);
+    const auto open = server.requests_to("/v1.0/gateway/connections/open");
+    ASSERT_EQ(open.size(), 1u);
+    EXPECT_EQ(open[0].body["subscriptions"][0]["topic"], kBotMessageTopic);
+    EXPECT_EQ(open[0].body["subscriptions"][0]["type"], "CALLBACK");
+}
+
+// 场景:凭据正确,但应用未发布 / 机器人没开 Stream 模式,Stream 注册返回 400。
+// 期望:标记为 rejected(既不是凭据错误也不是网络问题),原因提示检查发布与 Stream 模式。
+TEST(DingTalkApi, VerifyReportsUnpublishedApp) {
+    test::FakeDingTalkServer server;
+    server.open_handler = [](const test::FakeDingTalkServer::Request&) {
+        return test::FakeDingTalkServer::Reply{400, {{"code", "invalidParameter"}, {"requestid", "R"},
+                                                      {"message", "robot not found"}}};
+    };
+    const auto result = Api(local_options(server)).verify();
+    EXPECT_FALSE(result.ok);
+    EXPECT_TRUE(result.rejected);
+    EXPECT_FALSE(result.auth_failed);
+    EXPECT_NE(result.error.find(u8"Stream 模式"), std::string::npos) << result.error;
+}
+
+// 场景:钉钉开放平台连不上(端口无人监听)。
+// 期望:标记为网络问题,而不是凭据无效。
+TEST(DingTalkApi, VerifyDistinguishesNetworkFailure) {
+    std::string dead_base;
+    {
+        test::FakeDingTalkServer server;
+        dead_base = server.base();
+    }
+    ApiOptions options;
+    options.client_id = "dingX";
+    options.client_secret = "secret-value-xyz";
+    options.api_base = dead_base;
+    options.oapi_base = dead_base;
+    options.use_proxy = false;
+    const auto result = Api(options).verify();
+    EXPECT_FALSE(result.ok);
+    EXPECT_TRUE(result.network);
+    EXPECT_FALSE(result.auth_failed);
+}
+
+// 场景:机器人单聊接口 HTTP 200 返回,但该用户在 invalidStaffIdList 里。
+// 期望:视为未送达(ok=false),原因说明对方不在可见范围;不会被当成成功吞掉。
+TEST(DingTalkApi, OtoListedUserIsNotDelivered) {
+    test::FakeDingTalkServer server;
+    server.oto_handler = [](const test::FakeDingTalkServer::Request&) {
+        return test::FakeDingTalkServer::Reply{200, {{"processQueryKey", "PQK"},
+                                                      {"invalidStaffIdList", {"staff01"}}}};
+    };
+    Api api(local_options(server));
+    const auto result = api.send_oto("dingR", "staff01", "sampleMarkdown", {{"title", "t"}, {"text", "x"}});
+    EXPECT_FALSE(result.ok);
+    EXPECT_NE(result.error.message.find(u8"可见范围"), std::string::npos);
+    const auto sent = server.requests_to("/v1.0/robot/oToMessages/batchSend");
+    ASSERT_EQ(sent.size(), 1u);
+    EXPECT_EQ(sent[0].body["userIds"], nlohmann::json::array({"staff01"}));
+}
+
+// 场景:会话 webhook 返回 HTTP 200 + errcode 300001;另有一个指向外部主机的 webhook。
+// 期望:HTTP 200 但 errcode 非 0 判为失败并识别为 webhook 失效(Hermes 只看状态码的 bug 不复现);
+// 外部主机的地址直接拒绝,不发出任何请求。
+TEST(DingTalkApi, WebhookChecksErrcodeAndAllowlist) {
+    test::FakeDingTalkServer server;
+    server.webhook_handler = [](const test::FakeDingTalkServer::Request&) {
+        return test::FakeDingTalkServer::Reply{200, {{"errcode", 300001}, {"errmsg", "session 不存在"}}};
+    };
+    Api api(local_options(server));
+    const nlohmann::json body{{"msgtype", "text"}, {"text", {{"content", "hi"}}}};
+    const auto gone = api.send_webhook(server.webhook("S9"), body);
+    EXPECT_FALSE(gone.ok);
+    EXPECT_TRUE(is_webhook_gone(gone.error));
+    EXPECT_EQ(gone.error.message.find("S9"), std::string::npos);
+
+    const auto foreign = api.send_webhook("https://evil.example.com/robot/sendBySession?session=x", body);
+    EXPECT_FALSE(foreign.ok);
+    EXPECT_EQ(server.requests_to("/robot/sendBySession").size(), 1u);
+}
+
+// 场景:上传一张图片作为媒体文件。
+// 期望:multipart 带 type 字段与 media 文件(文件名、内容原样),type 与令牌也放在查询参数里;
+// 返回带 @ 前缀的 media_id;令牌在 OAPI 上失效(errcode 40014)时换新令牌重试一次。
+TEST(DingTalkApi, UploadsMediaWithTypeFieldAndQuery) {
+    test::FakeDingTalkServer server;
+    std::atomic<int> uploads{0};
+    server.upload_handler = [&uploads](const test::FakeDingTalkServer::Request&) {
+        if (uploads++ == 0)
+            return test::FakeDingTalkServer::Reply{200, {{"errcode", 40014}, {"errmsg", "不合法的access_token"}}};
+        return test::FakeDingTalkServer::Reply{0, nullptr};
+    };
+    const auto file = std::filesystem::path(testing::TempDir()) / "acecode-dingtalk-shot.png";
+    { std::ofstream(file, std::ios::binary) << "PNGDATA"; }
+    Api api(local_options(server));
+    const auto result = api.upload_media("image", file, "shot.png", "image/png");
+    EXPECT_TRUE(result.ok) << result.error.message;
+    EXPECT_EQ(result.response.value("media_id", ""), "@media-1");
+    const auto requests = server.requests_to("/media/upload");
+    ASSERT_EQ(requests.size(), 2u);
+    EXPECT_EQ(requests[0].token, "tok-1");
+    EXPECT_EQ(requests[1].token, "tok-2");
+    EXPECT_EQ(requests[1].query, "image");
+    EXPECT_EQ(requests[1].body.value("type", ""), "image");
+    EXPECT_EQ(requests[1].file_name, "shot.png");
+    EXPECT_EQ(requests[1].file_body, "PNGDATA");
+    std::filesystem::remove(file);
+}
+
+// 场景:下载入站附件:先用 downloadCode 换下载地址,再 GET 该地址;另一个附件超过本地上限。
+// 期望:换地址时带 downloadCode 与 robotCode;GET 不带 Content-Type(否则 OSS 签名校验失败);
+// 超限时返回 false、中文原因,并删掉半截文件。
+TEST(DingTalkApi, DownloadsWithoutContentTypeAndHonoursLimit) {
+    test::FakeDingTalkServer server;
+    Api api(local_options(server));
+    const auto dest = std::filesystem::path(testing::TempDir()) / "acecode-dingtalk-dl.bin";
+    std::string error;
+    ASSERT_TRUE(api.download("code1", "dingR", dest, 1024, &error)) << error;
+    EXPECT_EQ(std::filesystem::file_size(dest), 16u);
+    const auto resolve = server.requests_to("/v1.0/robot/messageFiles/download");
+    ASSERT_EQ(resolve.size(), 1u);
+    EXPECT_EQ(resolve[0].body.value("downloadCode", ""), "code1");
+    EXPECT_EQ(resolve[0].body.value("robotCode", ""), "dingR");
+    const auto oss = server.requests_to("/oss/code1");
+    ASSERT_EQ(oss.size(), 1u);
+    EXPECT_TRUE(oss[0].content_type.empty());
+
+    EXPECT_FALSE(api.download("big", "dingR", dest, 100, &error));
+    EXPECT_NE(error.find(u8"超过"), std::string::npos);
+    EXPECT_FALSE(std::filesystem::exists(dest));
+}
+
+} // namespace
+} // namespace acecode::im::dingtalk
diff --git a/tests/im/dingtalk_protocol_test.cpp b/tests/im/dingtalk_protocol_test.cpp
new file mode 100644
index 000000000..40eced6f9
--- /dev/null
+++ b/tests/im/dingtalk_protocol_test.cpp
@@ -0,0 +1,355 @@
+#include <gtest/gtest.h>
+
+#include "im/dingtalk/dingtalk_protocol.hpp"
+
+// im/dingtalk/dingtalk_protocol:钉钉机器人消息解析、错误分类、webhook 白名单、
+// Markdown 标题与渲染怪癖修正。全部是纯函数,不碰网络。
+
+namespace acecode::im::dingtalk {
+namespace {
+
+constexpr const char* kClient = "dingCLIENT";
+
+nlohmann::json private_text(const std::string& text) {
+    return {{"msgId", "msgA"},
+            {"msgtype", "text"},
+            {"text", {{"content", text}}},
+            {"conversationType", "1"},
+            {"conversationId", "cidP+/x=="},
+            {"senderId", "$:LWCP_v1:$abc=="},
+            {"senderStaffId", "staff01"},
+            {"senderNick", "Ann"},
+            {"robotCode", kClient},
+            {"sessionWebhook", "https://oapi.dingtalk.com/robot/sendBySession?session=s1"},
+            {"sessionWebhookExpiredTime", 1700000000000LL}};
+}
+
+nlohmann::json group_text(const std::string& text) {
+    return {{"msgId", "msgG"},
+            {"msgtype", "text"},
+            {"text", {{"content", text}}},
+            {"conversationType", "2"},
+            {"conversationId", "cidGROUP+/=="},
+            {"senderId", "$:LWCP_v1:$bob"},
+            {"senderStaffId", "staff02"},
+            {"chatbotUserId", "$:LWCP_v1:$bot"},
+            {"isInAtList", true},
+            {"atUsers", nlohmann::json::array({{{"dingtalkId", "$:LWCP_v1:$bot"}}})}};
+}
+
+// 场景:组织内用户单聊机器人发一条文字。
+// 期望:私聊地址 chat = sender = senderStaffId,account = Client ID;恒视为点名;
+// 文本去掉首尾空白;回复上下文带 webhook、到期时间、会话类型与 msgId。
+TEST(DingTalkProtocol, ParsesPrivateTextWithStaffId) {
+    const auto inbound = parse_robot_message(private_text("  你好  "), kClient);
+    ASSERT_TRUE(inbound);
+    EXPECT_EQ(inbound->address.platform, "dingtalk");
+    EXPECT_EQ(inbound->address.account, kClient);
+    EXPECT_EQ(inbound->address.kind, ChatKind::Private);
+    EXPECT_EQ(inbound->address.chat, "staff01");
+    EXPECT_EQ(inbound->address.sender, "staff01");
+    EXPECT_TRUE(inbound->mentioned);
+    EXPECT_EQ(inbound->text, u8"你好");
+    EXPECT_EQ(inbound->message_id, "msgA");
+    EXPECT_EQ(inbound->sender_name, "Ann");
+    const auto& ctx = inbound->reply_context;
+    EXPECT_EQ(ctx.value("sessionWebhook", ""), "https://oapi.dingtalk.com/robot/sendBySession?session=s1");
+    EXPECT_EQ(ctx.value("sessionWebhookExpiredTime", 0LL), 1700000000000LL);
+    EXPECT_EQ(ctx.value("conversationType", ""), "1");
+    EXPECT_EQ(ctx.value("senderStaffId", ""), "staff01");
+    EXPECT_EQ(ctx.value("msgId", ""), "msgA");
+    EXPECT_EQ(ctx.value("robotCode", ""), kClient);
+}
+
+// 场景:组织外用户单聊(没有 senderStaffId),conversationType 以数字 1 发来。
+// 期望:回退用加密 senderId 作为 chat 与 sender;数字形式的会话类型也能识别为单聊。
+TEST(DingTalkProtocol, ExternalUserFallsBackToSenderId) {
+    auto data = private_text("hi");
+    data.erase("senderStaffId");
+    data["conversationType"] = 1;
+    const auto inbound = parse_robot_message(data, kClient);
+    ASSERT_TRUE(inbound);
+    EXPECT_EQ(inbound->address.chat, "$:LWCP_v1:$abc==");
+    EXPECT_TRUE(is_encrypted_sender_id(inbound->address.chat));
+    EXPECT_EQ(inbound->reply_context.value("senderStaffId", "x"), "");
+}
+
+// 场景:群里 @机器人 并在开头带着机器人的 @名字(atUsers 只有机器人自己)。
+// 期望:群地址 chat = conversationId、sender = staffId;mentioned=true;开头的 @名字被去掉。
+TEST(DingTalkProtocol, ParsesGroupMentionAndStripsBotName) {
+    const auto inbound = parse_robot_message(group_text("@ACE助手 /new 开始"), kClient);
+    ASSERT_TRUE(inbound);
+    EXPECT_EQ(inbound->address.kind, ChatKind::Group);
+    EXPECT_EQ(inbound->address.chat, "cidGROUP+/==");
+    EXPECT_EQ(inbound->address.sender, "staff02");
+    EXPECT_TRUE(inbound->mentioned);
+    EXPECT_EQ(inbound->text, "/new 开始");
+}
+
+// 场景:群消息里出现邮箱、git@host,或同时 @ 了别人。
+// 期望:邮箱与 git@host 原样保留(@ 前不是空白);atUsers 里有别人时不去掉任何 @(分不清哪个是机器人)。
+TEST(DingTalkProtocol, DoesNotStripEmailsOrAmbiguousMentions) {
+    auto email = parse_robot_message(group_text("发到 a@b.com 和 git@github.com"), kClient);
+    ASSERT_TRUE(email);
+    EXPECT_EQ(email->text, "发到 a@b.com 和 git@github.com");
+
+    auto data = group_text("@机器人 @张三 看看");
+    data["atUsers"].push_back({{"dingtalkId", "$:LWCP_v1:$zhang"}});
+    const auto both = parse_robot_message(data, kClient);
+    ASSERT_TRUE(both);
+    EXPECT_EQ(both->text, "@机器人 @张三 看看");
+}
+
+// 场景:@机器人 放在末尾;以及正文中间出现一个手打的 @文字(不是真正的提及)。
+// 期望:末尾的 @名字被去掉;中间的 @文字原样保留(只去掉开头或末尾的提及,避免误删正文)。
+TEST(DingTalkProtocol, StripsTrailingMentionButKeepsMiddleText) {
+    const auto trailing = parse_robot_message(group_text("帮我看看 @ACE助手"), kClient);
+    ASSERT_TRUE(trailing);
+    EXPECT_EQ(trailing->text, "帮我看看");
+    const auto middle = parse_robot_message(group_text("请转告 @老王 明天开会"), kClient);
+    ASSERT_TRUE(middle);
+    EXPECT_EQ(middle->text, "请转告 @老王 明天开会");
+}
+
+// 场景:群消息没有点名机器人(isInAtList=false,atUsers 不含机器人);以及两个字段都缺失。
+// 期望:前者 mentioned=false;后者视为点名(企业内部机器人在群里只收得到 @ 它的消息)。
+TEST(DingTalkProtocol, GroupMentionDetection) {
+    auto data = group_text("随便聊聊");
+    data["isInAtList"] = false;
+    data["atUsers"] = nlohmann::json::array();
+    const auto silent = parse_robot_message(data, kClient);
+    ASSERT_TRUE(silent);
+    EXPECT_FALSE(silent->mentioned);
+
+    data.erase("isInAtList");
+    data.erase("atUsers");
+    const auto missing = parse_robot_message(data, kClient);
+    ASSERT_TRUE(missing);
+    EXPECT_TRUE(missing->mentioned);
+}
+
+// 场景:富文本消息,文字与图片交错。
+// 期望:文字段按顺序用换行拼接;图片变成附件,remote_ref 为 downloadCode。
+TEST(DingTalkProtocol, RichTextJoinsTextAndCollectsPictures) {
+    auto data = private_text("");
+    data.erase("text");
+    data["msgtype"] = "richText";
+    data["content"] = {{"richText", nlohmann::json::array({{{"text", "示例图如下："}},
+                                                           {{"type", "picture"}, {"downloadCode", "DC1"},
+                                                            {"pictureDownloadCode", "P1"}},
+                                                           {{"text", "看完再说"}}})}};
+    const auto inbound = parse_robot_message(data, kClient);
+    ASSERT_TRUE(inbound);
+    EXPECT_EQ(inbound->text, "示例图如下：\n看完再说");
+    ASSERT_EQ(inbound->attachments.size(), 1u);
+    EXPECT_EQ(inbound->attachments[0].kind, AttachmentKind::Image);
+    EXPECT_EQ(inbound->attachments[0].remote_ref, "DC1");
+}
+
+// 场景:图片、文件、视频消息,其中文件消息的 content 以 JSON 字符串形式发来。
+// 期望:分别解析为图片 / 文件(带文件名)/ 视频附件;字符串形式的 content 也能读。
+TEST(DingTalkProtocol, MediaMessagesBecomeAttachments) {
+    auto picture = private_text("");
+    picture.erase("text");
+    picture["msgtype"] = "picture";
+    picture["content"] = {{"pictureDownloadCode", "P2"}, {"downloadCode", "DC2"}};
+    const auto image = parse_robot_message(picture, kClient);
+    ASSERT_TRUE(image);
+    ASSERT_EQ(image->attachments.size(), 1u);
+    EXPECT_EQ(image->attachments[0].kind, AttachmentKind::Image);
+    EXPECT_EQ(image->attachments[0].remote_ref, "DC2");
+    EXPECT_TRUE(image->text.empty());
+
+    auto file = private_text("");
+    file.erase("text");
+    file["msgtype"] = "file";
+    file["content"] = nlohmann::json{{"fileName", "报告.pdf"}, {"downloadCode", "DC3"}, {"spaceId", "1"}}.dump();
+    const auto doc = parse_robot_message(file, kClient);
+    ASSERT_TRUE(doc);
+    ASSERT_EQ(doc->attachments.size(), 1u);
+    EXPECT_EQ(doc->attachments[0].kind, AttachmentKind::File);
+    EXPECT_EQ(doc->attachments[0].name, "报告.pdf");
+
+    auto video = private_text("");
+    video.erase("text");
+    video["msgtype"] = "video";
+    video["content"] = {{"duration", "5"}, {"videoType", "mp4"}, {"downloadCode", "DC4"}};
+    const auto clip = parse_robot_message(video, kClient);
+    ASSERT_TRUE(clip);
+    EXPECT_EQ(clip->attachments.at(0).kind, AttachmentKind::Video);
+    EXPECT_EQ(clip->attachments.at(0).name, "video.mp4");
+}
+
+// 场景:语音消息带平台识别文字。
+// 期望:语音附件的 transcript 为识别文字(交给核心拼成“[语音转写]”),不当作需要重新转写的音频。
+TEST(DingTalkProtocol, AudioCarriesRecognitionText) {
+    auto audio = private_text("");
+    audio.erase("text");
+    audio["msgtype"] = "audio";
+    audio["content"] = {{"downloadCode", "DC5"}, {"recognition", " 明天开会 "}};
+    const auto inbound = parse_robot_message(audio, kClient);
+    ASSERT_TRUE(inbound);
+    ASSERT_EQ(inbound->attachments.size(), 1u);
+    EXPECT_EQ(inbound->attachments[0].kind, AttachmentKind::Voice);
+    EXPECT_EQ(inbound->attachments[0].transcript, u8"明天开会");
+}
+
+// 场景:分享文档卡片(interactiveCard)与机器人收不到的消息类型(unknownMsgType)。
+// 期望:文档卡片变成“[文档] 标题 链接”文字;未知类型变成一个 Other 附件,让核心回复“暂不支持”。
+TEST(DingTalkProtocol, CardsAndUnsupportedTypes) {
+    auto card = private_text("");
+    card.erase("text");
+    card["msgtype"] = "interactiveCard";
+    card["content"] = {{"title", "周报"}, {"biz_custom_action_url", "https://alidocs.dingtalk.com/i/x"}};
+    const auto doc = parse_robot_message(card, kClient);
+    ASSERT_TRUE(doc);
+    EXPECT_EQ(doc->text, "[文档] 周报 https://alidocs.dingtalk.com/i/x");
+
+    auto unknown = private_text("");
+    unknown.erase("text");
+    unknown["msgtype"] = "unknownMsgType";
+    unknown["content"] = {{"unknownMsgType", "用户发送了一条消息，机器人暂不支持接收。"}};
+    const auto other = parse_robot_message(unknown, kClient);
+    ASSERT_TRUE(other);
+    EXPECT_TRUE(other->text.empty());
+    ASSERT_EQ(other->attachments.size(), 1u);
+    EXPECT_EQ(other->attachments[0].kind, AttachmentKind::Other);
+}
+
+// 场景:引用回复(text.isReplyMsg + repliedMsg,被引用内容是 JSON 字符串)。
+// 期望:quote_text 为被引用消息的文字,正文不受影响。
+TEST(DingTalkProtocol, QuoteReplyIsExtracted) {
+    auto data = private_text("同意");
+    data["text"]["isReplyMsg"] = true;
+    data["text"]["repliedMsg"] = {{"msgType", "text"}, {"msgId", "old"},
+                                  {"content", nlohmann::json{{"text", "上线时间定在周五"}}.dump()}};
+    const auto inbound = parse_robot_message(data, kClient);
+    ASSERT_TRUE(inbound);
+    EXPECT_EQ(inbound->text, u8"同意");
+    EXPECT_EQ(inbound->quote_text, u8"上线时间定在周五");
+}
+
+// 场景:消息缺 msgId、或者既无文字也无附件、或者 data 不是对象。
+// 期望:缺 msgId 时用帧头 messageId 兜底;没有内容或格式不对返回 nullopt。
+TEST(DingTalkProtocol, MissingFieldsAreHandled) {
+    auto data = private_text("hi");
+    data.erase("msgId");
+    const auto fallback = parse_robot_message(data, kClient, "hdr-1");
+    ASSERT_TRUE(fallback);
+    EXPECT_EQ(fallback->message_id, "hdr-1");
+    EXPECT_FALSE(parse_robot_message(data, kClient));
+
+    EXPECT_FALSE(parse_robot_message(private_text("   "), kClient));
+    EXPECT_FALSE(parse_robot_message(nlohmann::json::array(), kClient));
+    auto no_sender = private_text("hi");
+    no_sender.erase("senderStaffId");
+    no_sender.erase("senderId");
+    EXPECT_FALSE(parse_robot_message(no_sender, kClient));
+}
+
+// 场景:新版 OpenAPI 的 4xx 错误与旧版 OAPI / webhook 的 HTTP 200 + errcode 两种失败形态。
+// 期望:两种都能解析出错误码与原因;HTTP 200 + errcode 0 不算失败。
+TEST(DingTalkProtocol, ParsesBothErrorShapes) {
+    const auto api = parse_api_error(400, R"({"code":"InvalidAuthentication","requestid":"R1","message":"不合法的access_token"})");
+    EXPECT_EQ(api.code, "InvalidAuthentication");
+    EXPECT_EQ(api.request_id, "R1");
+    EXPECT_TRUE(is_token_error(api));
+
+    ApiError oapi;
+    EXPECT_TRUE(body_has_errcode(R"({"errcode":300001,"errmsg":"session 不存在"})", &oapi));
+    EXPECT_EQ(oapi.errcode, 300001);
+    EXPECT_EQ(oapi.message, "session 不存在");
+    EXPECT_TRUE(is_webhook_gone(oapi));
+    EXPECT_FALSE(body_has_errcode(R"({"errcode":0,"errmsg":"ok"})", nullptr));
+    EXPECT_FALSE(body_has_errcode(R"({"processQueryKey":"k"})", nullptr));
+
+    const auto bare = parse_api_error(502, "<html>bad gateway</html>");
+    EXPECT_EQ(bare.message, "HTTP 502");
+}
+
+// 场景:各种限流与令牌失效的错误码。
+// 期望:QpsLimit 归为短等待;send.too.fast / 130101 / 429 归为长等待;40014 与 HTTP 401 是令牌失效。
+TEST(DingTalkProtocol, ClassifiesThrottleAndTokenErrors) {
+    ApiError qps;
+    qps.status = 403;
+    qps.code = "Forbidden.AccessDenied.QpsLimitForApi";
+    EXPECT_EQ(throttle_kind(qps), Throttle::Qps);
+    ApiError fast;
+    fast.status = 200;
+    fast.errcode = 130101;
+    EXPECT_EQ(throttle_kind(fast), Throttle::Rate);
+    ApiError too_many;
+    too_many.status = 429;
+    EXPECT_EQ(throttle_kind(too_many), Throttle::Rate);
+    ApiError normal;
+    normal.status = 400;
+    normal.code = "invalidParameter.msgParam.invalid";
+    EXPECT_EQ(throttle_kind(normal), Throttle::None);
+    ApiError oapi_token;
+    oapi_token.errcode = 40014;
+    EXPECT_TRUE(is_token_error(oapi_token));
+}
+
+// 场景:防 SSRF —— 回复用的 webhook 地址来自入站消息,可能被伪造。
+// 期望:只接受 https 的 api/oapi.dingtalk.com;拒绝 http、子域名伪装、@ 伪装与带空白的地址;
+// 配置的接入地址(测试里的本机假服务)作为额外前缀放行。
+TEST(DingTalkProtocol, WebhookAllowlistBlocksForeignHosts) {
+    EXPECT_TRUE(webhook_url_allowed("https://oapi.dingtalk.com/robot/sendBySession?session=x", {}));
+    EXPECT_TRUE(webhook_url_allowed("https://api.dingtalk.com/v1.0/robot/x", {}));
+    EXPECT_FALSE(webhook_url_allowed("http://oapi.dingtalk.com/robot/sendBySession", {}));
+    EXPECT_FALSE(webhook_url_allowed("https://oapi.dingtalk.com.evil.com/robot", {}));
+    EXPECT_FALSE(webhook_url_allowed("https://oapi.dingtalk.com@evil.com/robot", {}));
+    EXPECT_FALSE(webhook_url_allowed("https://oapi.dingtalk.com/a b", {}));
+    EXPECT_FALSE(webhook_url_allowed("http://127.0.0.1:9/robot", {}));
+    EXPECT_TRUE(webhook_url_allowed("http://127.0.0.1:9/robot", {"http://127.0.0.1:9/"}));
+    EXPECT_FALSE(webhook_url_allowed("http://127.0.0.1:99/robot", {"http://127.0.0.1:9"}));
+}
+
+// 场景:为 Markdown 消息生成通知栏标题。
+// 期望:取第一行非空文字,去掉 # * > - 与反引号,截到 20 个字符(按码点,不切坏中文);全空时用默认标题。
+TEST(DingTalkProtocol, MarkdownTitleUsesFirstLine) {
+    EXPECT_EQ(markdown_title("\n## **部署结果**\n正文"), u8"部署结果");
+    EXPECT_EQ(markdown_title("> - `make test` passed"), "make test passed");
+    EXPECT_EQ(markdown_title(u8"一二三四五六七八九十一二三四五六七八九十多出来的"), u8"一二三四五六七八九十一二三四五六七八九十");
+    EXPECT_EQ(markdown_title("  \n ** \n"), "ACECode");
+}
+
+// 场景:钉钉渲染器的两个怪癖(Hermes 实测):编号列表紧跟普通文字不渲染;缩进的代码围栏不识别。
+// 期望:编号列表前补一个空行(相邻编号行之间不补);缩进围栏及其内容去掉围栏的缩进;围栏内的编号行不动。
+TEST(DingTalkProtocol, NormalizesMarkdownQuirks) {
+    EXPECT_EQ(normalize_markdown("步骤如下:\n1. 安装\n2. 运行"), "步骤如下:\n\n1. 安装\n2. 运行");
+    EXPECT_EQ(normalize_markdown("- 项\n   ```bash\n   ls\n   ```\n"), "- 项\n```bash\nls\n```\n");
+    EXPECT_EQ(normalize_markdown("```\ncode\n1. not a list\n```"), "```\ncode\n1. not a list\n```");
+}
+
+// 场景:按文件名 / MIME 决定媒体上传类型。
+// 期望:常见图片为 image;amr/mp3/wav 为 voice;其余(含视频、PDF)为 file;扩展名小写且不带点。
+TEST(DingTalkProtocol, UploadTypeAndExtension) {
+    EXPECT_EQ(upload_type_for("image/png", "a.png"), "image");
+    EXPECT_EQ(upload_type_for("", "Shot.JPG"), "image");
+    EXPECT_EQ(upload_type_for("image/webp", "a.webp"), "file");
+    EXPECT_EQ(upload_type_for("audio/amr", "v.amr"), "voice");
+    EXPECT_EQ(upload_type_for("video/mp4", "clip.mp4"), "file");
+    EXPECT_EQ(upload_type_for("application/pdf", "a.pdf"), "file");
+    EXPECT_EQ(file_extension("报告.PDF"), "pdf");
+    EXPECT_EQ(file_extension("README"), "");
+    EXPECT_EQ(url_encode("a b+c/d"), "a%20b%2Bc%2Fd");
+}
+
+// 场景:把平台错误翻译给用户。
+// 期望:缺发消息权限、IP 白名单、网络不通都给出带处理办法的中文一句话。
+TEST(DingTalkProtocol, DescribesCommonErrors) {
+    ApiError permission;
+    permission.status = 403;
+    permission.code = "Forbidden.AccessDenied.AccessTokenPermissionDenied";
+    EXPECT_NE(describe_api_error(permission).find("qyapi_robot_sendmsg"), std::string::npos);
+    ApiError ip;
+    ip.status = 200;
+    ip.errcode = 60020;
+    EXPECT_NE(describe_api_error(ip).find(u8"白名单"), std::string::npos);
+    ApiError offline;
+    EXPECT_NE(describe_api_error(offline).find(u8"无法连接"), std::string::npos);
+}
+
+} // namespace
+} // namespace acecode::im::dingtalk
diff --git a/tests/im/dingtalk_route_test.cpp b/tests/im/dingtalk_route_test.cpp
new file mode 100644
index 000000000..6f96d1028
--- /dev/null
+++ b/tests/im/dingtalk_route_test.cpp
@@ -0,0 +1,134 @@
+#include <gtest/gtest.h>
+
+#include "im/dingtalk/dingtalk_route.hpp"
+
+// im/dingtalk/dingtalk_route:回复路由(会话 webhook 缓存与合并)、发送限速、有界去重。纯逻辑。
+
+namespace acecode::im::dingtalk {
+namespace {
+
+using Clock = RateLimiter::Clock;
+using std::chrono::milliseconds;
+using std::chrono::seconds;
+
+constexpr std::int64_t kMargin = 5 * 60 * 1000;
+
+nlohmann::json context(const std::string& webhook, std::int64_t expires, const std::string& staff = "staff01") {
+    return {{"sessionWebhook", webhook}, {"sessionWebhookExpiredTime", expires}, {"conversationType", "1"},
+            {"conversationId", "cid1"},  {"senderStaffId", staff},               {"robotCode", "dingR"},
+            {"msgId", "m1"}};
+}
+
+// 场景:从入站消息的回复上下文还原路由;到期时间以字符串形式保存(持久化后可能如此)。
+// 期望:各字段都能读出;群聊标记按 conversationType 判断。
+TEST(DingTalkRoute, RouteFromContextReadsAllFields) {
+    auto ctx = context("https://oapi.dingtalk.com/robot/sendBySession?session=a", 0);
+    ctx["sessionWebhookExpiredTime"] = "1700000000000";
+    ctx["conversationType"] = "2";
+    const auto route = route_from_context(ctx);
+    EXPECT_EQ(route.webhook_expires_ms, 1700000000000LL);
+    EXPECT_TRUE(route.group);
+    EXPECT_EQ(route.staff_id, "staff01");
+    EXPECT_EQ(route.robot_code, "dingR");
+    EXPECT_EQ(route.conversation_id, "cid1");
+    EXPECT_FALSE(route_from_context(nlohmann::json()).group);
+}
+
+// 场景:webhook 还有 10 分钟、4 分钟到期,以及没有到期时间。
+// 期望:提前 5 分钟视为过期 —— 10 分钟的可用,4 分钟的与没有到期时间的都不可用。
+TEST(DingTalkRoute, WebhookUsableHonoursMargin) {
+    const std::int64_t now = 1'000'000'000;
+    Route route;
+    route.webhook = "https://oapi.dingtalk.com/x";
+    route.webhook_expires_ms = now + 10 * 60 * 1000;
+    EXPECT_TRUE(webhook_usable(route, now, kMargin));
+    route.webhook_expires_ms = now + 4 * 60 * 1000;
+    EXPECT_FALSE(webhook_usable(route, now, kMargin));
+    route.webhook_expires_ms = 0;
+    EXPECT_FALSE(webhook_usable(route, now, kMargin));
+}
+
+// 场景:触发本回合的旧消息带着快过期的 webhook,而该会话最近一条消息(缓存)带着更新的 webhook;
+// 另一种情况是回复上下文为空(Desktop 里输入的回复)。
+// 期望:取到期更晚的那个 webhook;上下文为空时直接用缓存,并从缓存补齐 staffId / robotCode。
+TEST(DingTalkRoute, ResolvePrefersFresherWebhook) {
+    const std::int64_t now = 1'000'000'000;
+    RouteBook book;
+    auto fresh = route_from_context(context("https://oapi.dingtalk.com/new", now + 80 * 60 * 1000));
+    book.remember("k", fresh);
+    const auto merged = book.resolve("k", context("https://oapi.dingtalk.com/old", now + 30 * 60 * 1000), now, kMargin);
+    EXPECT_EQ(merged.webhook, "https://oapi.dingtalk.com/new");
+
+    const auto empty = book.resolve("k", nlohmann::json::object(), now, kMargin);
+    EXPECT_EQ(empty.webhook, "https://oapi.dingtalk.com/new");
+    EXPECT_EQ(empty.staff_id, "staff01");
+    EXPECT_EQ(empty.robot_code, "dingR");
+
+    const auto unknown = book.resolve("other", nlohmann::json::object(), now, kMargin);
+    EXPECT_TRUE(unknown.webhook.empty());
+}
+
+// 场景:平台对某个 webhook 报了 session 不存在,而重启后持久化的回复上下文里还带着它。
+// 期望:标记失效后 resolve 不再给出它(返回空 webhook,让调用方走 OpenAPI)。
+TEST(DingTalkRoute, DeadWebhookIsNeverReused) {
+    const std::int64_t now = 1'000'000'000;
+    RouteBook book;
+    const auto ctx = context("https://oapi.dingtalk.com/gone", now + 60 * 60 * 1000);
+    book.remember("k", route_from_context(ctx));
+    book.mark_webhook_dead("https://oapi.dingtalk.com/gone");
+    EXPECT_TRUE(book.webhook_dead("https://oapi.dingtalk.com/gone"));
+    const auto route = book.resolve("k", ctx, now, kMargin);
+    EXPECT_TRUE(route.webhook.empty());
+    EXPECT_EQ(route.staff_id, "staff01");
+}
+
+// 场景:缓存上限 2 条,依次记住 a、b,再更新 a,然后记住 c。
+// 期望:淘汰的是最久未更新的 b,而不是最早插入的 a。
+TEST(DingTalkRoute, RouteBookEvictsLeastRecentlyUpdated) {
+    RouteBook book(2);
+    Route route;
+    book.remember("a", route);
+    book.remember("b", route);
+    book.remember("a", route);
+    book.remember("c", route);
+    EXPECT_EQ(book.size(), 2u);
+    EXPECT_TRUE(book.find("a"));
+    EXPECT_FALSE(book.find("b"));
+    EXPECT_TRUE(book.find("c"));
+}
+
+// 场景:同一会话一分钟内发 21 条(钉钉上限每会话每分钟 20 条,超出会被封 10 分钟)。
+// 期望:前 20 条立即可发;第 21 条被排到第 1 条之后满 60 秒;其它会话不受影响。
+TEST(DingTalkRoute, RateLimiterKeepsTwentyPerMinutePerChat) {
+    RateLimiter limiter;
+    const auto t0 = Clock::now();
+    for (int i = 0; i < 20; ++i) EXPECT_EQ(limiter.reserve("cid", t0), t0);
+    EXPECT_EQ(limiter.reserve("cid", t0), t0 + seconds(60));
+    EXPECT_EQ(limiter.reserve("other", t0), t0);
+}
+
+// 场景:平台报“发送过快”,要求该会话暂停 30 秒。
+// 期望:30 秒内的预约都排到暂停结束之后;更短的二次惩罚不会把暂停提前。
+TEST(DingTalkRoute, RateLimiterPenaltyDelaysChat) {
+    RateLimiter limiter;
+    const auto t0 = Clock::now();
+    limiter.penalize("cid", seconds(30), t0);
+    limiter.penalize("cid", seconds(5), t0);
+    EXPECT_EQ(limiter.reserve("cid", t0 + seconds(1)), t0 + seconds(30));
+    EXPECT_EQ(limiter.reserve("cid", t0 + seconds(31)), t0 + seconds(31));
+}
+
+// 场景:去重集合容量 2,依次见到 x、y、x、z,再查 x。
+// 期望:重复的 x 被识别;超出容量后最早的 x 被淘汰,再次出现时视为新消息。
+TEST(DingTalkRoute, DedupSetIsBounded) {
+    DedupSet seen(2);
+    EXPECT_FALSE(seen.seen("x"));
+    EXPECT_FALSE(seen.seen("y"));
+    EXPECT_TRUE(seen.seen("x"));
+    EXPECT_FALSE(seen.seen("z"));
+    EXPECT_FALSE(seen.contains("x"));
+    EXPECT_TRUE(seen.contains("z"));
+}
+
+} // namespace
+} // namespace acecode::im::dingtalk
diff --git a/tests/im/dingtalk_send_test.cpp b/tests/im/dingtalk_send_test.cpp
new file mode 100644
index 000000000..b4b607839
--- /dev/null
+++ b/tests/im/dingtalk_send_test.cpp
@@ -0,0 +1,347 @@
+#include <gtest/gtest.h>
+
+#include "im/dingtalk/dingtalk_transport.hpp"
+#include "test_support/im/fake_dingtalk_server.hpp"
+
+#include <fstream>
+#include <functional>
+#include <mutex>
+#include <vector>
+
+// im/dingtalk/dingtalk_transport:钉钉传输层的发送端到端测试。覆盖会话 webhook 回复、
+// webhook 失效 / 过期后改走机器人 OpenAPI、Desktop 里输入的回复(没有回复上下文)、
+// 组织外用户与 OpenAPI 被拒时的暂存补发、限流等待重发、长文分段与文件 / 图片发送。
+
+namespace acecode::im::dingtalk {
+namespace {
+
+using Server = test::FakeDingTalkServer;
+
+DingTalkTransportOptions local_options(Server& server) {
+    DingTalkTransportOptions options;
+    options.api.client_id = server.client_id;
+    options.api.client_secret = server.client_secret;
+    options.api.api_base = server.base();
+    options.api.oapi_base = server.base();
+    options.api.use_proxy = false;
+    options.backoff_base = std::chrono::milliseconds(50);
+    options.backoff_cap = std::chrono::milliseconds(200);
+    options.jitter = false;
+    options.idle_timeout = std::chrono::milliseconds(0);
+    options.throttle_delay = std::chrono::milliseconds(100);
+    options.qps_delay = std::chrono::milliseconds(50);
+    return options;
+}
+
+struct Recorder {
+    std::mutex mu;
+    std::vector<Inbound> inbound;
+    std::function<void(const Inbound&)> hook;  // 在传输层分发线程上、记录之前调用
+    TransportCallbacks callbacks() {
+        TransportCallbacks cb;
+        cb.on_inbound = [this](Inbound in) {
+            if (hook) hook(in);
+            std::lock_guard<std::mutex> lock(mu);
+            inbound.push_back(std::move(in));
+        };
+        return cb;
+    }
+    std::size_t count() {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.size();
+    }
+    Inbound at(std::size_t i) {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.at(i);
+    }
+};
+
+// 启动传输层并等到假网关登记了连接。
+void start(DingTalkTransport& transport, Recorder& recorder, Server& server) {
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(Server::wait_until([&transport, &server] {
+        return transport.status().state == LinkState::Connected && server.connections() >= 1;
+    }));
+}
+
+// 推一条消息并等它到达上层,返回入站消息。
+Inbound receive(Server& server, Recorder& recorder, const std::string& header_id, const nlohmann::json& data) {
+    const auto before = recorder.count();
+    server.push_callback(header_id, data);
+    EXPECT_TRUE(Server::wait_until([&recorder, before] { return recorder.count() > before; }));
+    return recorder.at(recorder.count() - 1);
+}
+
+nlohmann::json msg_param(const Server::Request& request) {
+    return nlohmann::json::parse(request.body.value("msgParam", std::string("{}")));
+}
+
+// 场景:收到单聊消息后回复一段带编号列表的 Markdown。
+// 期望:经该消息的会话 webhook 以 markdown 发送,标题取第一行;编号列表前补了空行(钉钉渲染怪癖);
+// 不调用机器人 OpenAPI(不消耗月度额度)。
+TEST(DingTalkSend, RepliesThroughSessionWebhook) {
+    Server server;
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    start(transport, recorder, server);
+    const auto inbound = receive(server, recorder, "h1", server.private_text("m1", "staff01", "hi"));
+    const auto result = transport.send_text(inbound.address, u8"## 结果\n步骤:\n1. 构建\n2. 测试", inbound.reply_context);
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto sent = server.requests_to("/robot/sendBySession");
+    ASSERT_EQ(sent.size(), 1u);
+    EXPECT_EQ(sent[0].query, "S1");
+    EXPECT_EQ(sent[0].body.value("msgtype", ""), "markdown");
+    EXPECT_EQ(sent[0].body["markdown"].value("title", ""), u8"结果");
+    EXPECT_EQ(sent[0].body["markdown"].value("text", ""), u8"## 结果\n步骤:\n\n1. 构建\n2. 测试");
+    EXPECT_TRUE(server.requests_to("/v1.0/robot/oToMessages/batchSend").empty());
+}
+
+// 场景:会话 webhook 报 errcode 300001(session 不存在),随后再回复一条。
+// 期望:改走机器人单聊 OpenAPI(userIds=[staffId]、robotCode=Client ID、msgKey=sampleMarkdown、
+// msgParam 为 JSON 字符串)且发送成功;第二条不再尝试那个已失效的 webhook。
+TEST(DingTalkSend, FallsBackToRobotApiWhenWebhookIsGone) {
+    Server server;
+    server.webhook_handler = [](const Server::Request&) {
+        return Server::Reply{200, {{"errcode", 300001}, {"errmsg", "session 不存在"}}};
+    };
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    start(transport, recorder, server);
+    const auto inbound = receive(server, recorder, "h1", server.private_text("m1", "staff01", "hi"));
+    EXPECT_EQ(transport.send_text(inbound.address, "first", inbound.reply_context).outcome, SendOutcome::Sent);
+    EXPECT_EQ(transport.send_text(inbound.address, "second", inbound.reply_context).outcome, SendOutcome::Sent);
+    EXPECT_EQ(server.requests_to("/robot/sendBySession").size(), 1u);
+    const auto oto = server.requests_to("/v1.0/robot/oToMessages/batchSend");
+    ASSERT_EQ(oto.size(), 2u);
+    EXPECT_EQ(oto[0].body["userIds"], nlohmann::json::array({"staff01"}));
+    EXPECT_EQ(oto[0].body.value("robotCode", ""), server.client_id);
+    EXPECT_EQ(oto[0].body.value("msgKey", ""), "sampleMarkdown");
+    EXPECT_EQ(msg_param(oto[0]).value("text", ""), "first");
+    EXPECT_EQ(msg_param(oto[1]).value("text", ""), "second");
+}
+
+// 场景:触发回复的消息带的 webhook 只剩 2 分钟有效(长回合之后常见)。
+// 期望:提前 5 分钟视为过期,直接走 OpenAPI,不去撞一个可能在发送途中过期的 webhook。
+TEST(DingTalkSend, NearlyExpiredWebhookIsSkipped) {
+    Server server;
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    start(transport, recorder, server);
+    const auto data = server.private_text("m1", "staff01", "hi", "S1", Server::now_ms() + 2 * 60 * 1000);
+    const auto inbound = receive(server, recorder, "h1", data);
+    EXPECT_EQ(transport.send_text(inbound.address, "late", inbound.reply_context).outcome, SendOutcome::Sent);
+    EXPECT_TRUE(server.requests_to("/robot/sendBySession").empty());
+    EXPECT_EQ(server.requests_to("/v1.0/robot/oToMessages/batchSend").size(), 1u);
+}
+
+// 场景:重启后在 Desktop 里输入的回复 —— 没有回复上下文,也没有缓存的 webhook。
+// 期望:群会话走 groupMessages/send(openConversationId = conversationId);
+// 组织内单聊走 oToMessages/batchSend(userIds = 地址里的 staffId)。
+TEST(DingTalkSend, DesktopOutputWithoutContextUsesRobotApi) {
+    Server server;
+    DingTalkTransport transport(local_options(server));
+    Address group{"dingtalk", server.client_id, ChatKind::Group, "cidG+/==", "staff09", {}};
+    EXPECT_EQ(transport.send_text(group, "hello group", nlohmann::json::object()).outcome, SendOutcome::Sent);
+    const auto sent = server.requests_to("/v1.0/robot/groupMessages/send");
+    ASSERT_EQ(sent.size(), 1u);
+    EXPECT_EQ(sent[0].body.value("openConversationId", ""), "cidG+/==");
+    EXPECT_EQ(msg_param(sent[0]).value("text", ""), "hello group");
+
+    Address user{"dingtalk", server.client_id, ChatKind::Private, "staff05", "staff05", {}};
+    EXPECT_EQ(transport.send_text(user, "hello", nlohmann::json::object()).outcome, SendOutcome::Sent);
+    const auto oto = server.requests_to("/v1.0/robot/oToMessages/batchSend");
+    ASSERT_EQ(oto.size(), 1u);
+    EXPECT_EQ(oto[0].body["userIds"], nlohmann::json::array({"staff05"}));
+}
+
+// 场景:组织外用户(没有 staffId)发来消息,回复时 webhook 已过期;之后对方又发来一条。
+// 期望:第一次发送结果为“暂存”,不调用任何发送接口;新消息到来时先用它的新 webhook 补发
+// (带“补发”标记),然后才把新消息交给上层。
+TEST(DingTalkSend, ExternalUserOutputIsHeldUntilNextMessage) {
+    Server server;
+    Recorder recorder;
+    std::atomic<std::size_t> webhooks_before_second{0};
+    recorder.hook = [&server, &webhooks_before_second](const Inbound& in) {
+        if (in.message_id == "m2") webhooks_before_second = server.requests_to("/robot/sendBySession").size();
+    };
+    DingTalkTransport transport(local_options(server));
+    start(transport, recorder, server);
+    const auto first = receive(server, recorder, "h1",
+                               server.private_text("m1", "", "hi", "S1", Server::now_ms() - 1000));
+    EXPECT_EQ(first.address.chat, "$:LWCP_v1:$ext");
+    EXPECT_EQ(transport.send_text(first.address, "late answer", first.reply_context).outcome, SendOutcome::Held);
+    EXPECT_EQ(transport.held_count(), 1u);
+    EXPECT_TRUE(server.requests_to("/robot/sendBySession").empty());
+    EXPECT_TRUE(server.requests_to("/v1.0/robot/oToMessages/batchSend").empty());
+
+    receive(server, recorder, "h2", server.private_text("m2", "", "again", "S2"));
+    EXPECT_EQ(webhooks_before_second.load(), 1u);
+    const auto sent = server.requests_to("/robot/sendBySession");
+    ASSERT_EQ(sent.size(), 1u);
+    EXPECT_EQ(sent[0].query, "S2");
+    const auto text = sent[0].body["markdown"].value("text", "");
+    EXPECT_EQ(text.rfind(u8"(补发)", 0), 0u) << text;
+    EXPECT_NE(text.find("late answer"), std::string::npos);
+    EXPECT_EQ(transport.held_count(), 0u);
+}
+
+// 场景:应用没开通机器人发消息权限:webhook 已失效,OpenAPI 返回 403 AccessTokenPermissionDenied;
+// 之后用户再发一条消息(带新 webhook)。
+// 期望:发送结果为暂存,原因提示开通 qyapi_robot_sendmsg;新消息到来时经新 webhook 补发成功。
+TEST(DingTalkSend, RefusedRobotApiOutputIsHeldAndFlushed) {
+    Server server;
+    server.webhook_handler = [](const Server::Request& r) {
+        if (r.query == "S1") return Server::Reply{200, {{"errcode", 300001}, {"errmsg", "session 不存在"}}};
+        return Server::Reply{0, nullptr};
+    };
+    server.oto_handler = [](const Server::Request&) {
+        return Server::Reply{403, {{"code", "Forbidden.AccessDenied.AccessTokenPermissionDenied"},
+                                   {"message", "没有调用该接口的权限"}}};
+    };
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    start(transport, recorder, server);
+    const auto first = receive(server, recorder, "h1", server.private_text("m1", "staff01", "hi"));
+    const auto result = transport.send_text(first.address, "answer", first.reply_context);
+    EXPECT_EQ(result.outcome, SendOutcome::Held);
+    EXPECT_NE(result.error.find("qyapi_robot_sendmsg"), std::string::npos) << result.error;
+
+    receive(server, recorder, "h2", server.private_text("m2", "staff01", "again", "S2"));
+    const auto sent = server.requests_to("/robot/sendBySession");
+    ASSERT_EQ(sent.size(), 2u);
+    EXPECT_EQ(sent[1].query, "S2");
+    EXPECT_NE(sent[1].body["markdown"].value("text", "").find("answer"), std::string::npos);
+    EXPECT_EQ(transport.held_count(), 0u);
+}
+
+// 场景:webhook 第一次返回 errcode 130101(发送过快),第二次正常;群发接口第一次返回 QPS 超限。
+// 期望:等待后重发同一条内容并成功,不丢消息;两次请求内容完全相同;webhook 重发至少等了限流延迟。
+TEST(DingTalkSend, RetriesThrottledSendsWithoutLosingThem) {
+    Server server;
+    std::atomic<int> webhook_calls{0}, group_calls{0};
+    server.webhook_handler = [&webhook_calls](const Server::Request&) {
+        if (webhook_calls++ == 0) return Server::Reply{200, {{"errcode", 130101}, {"errmsg", "send too fast"}}};
+        return Server::Reply{0, nullptr};
+    };
+    server.group_handler = [&group_calls](const Server::Request&) {
+        if (group_calls++ == 0)
+            return Server::Reply{403, {{"code", "Forbidden.AccessDenied.QpsLimitForApi"}, {"message", "qps"}}};
+        return Server::Reply{0, nullptr};
+    };
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    start(transport, recorder, server);
+    const auto inbound = receive(server, recorder, "h1", server.private_text("m1", "staff01", "hi"));
+    const auto t0 = std::chrono::steady_clock::now();
+    EXPECT_EQ(transport.send_text(inbound.address, "once", inbound.reply_context).outcome, SendOutcome::Sent);
+    EXPECT_GE(std::chrono::steady_clock::now() - t0, std::chrono::milliseconds(100));
+    const auto sent = server.requests_to("/robot/sendBySession");
+    ASSERT_EQ(sent.size(), 2u);
+    EXPECT_EQ(sent[0].body, sent[1].body);
+
+    Address group{"dingtalk", server.client_id, ChatKind::Group, "cidG", "staff09", {}};
+    EXPECT_EQ(transport.send_text(group, "group once", nlohmann::json::object()).outcome, SendOutcome::Sent);
+    EXPECT_EQ(server.requests_to("/v1.0/robot/groupMessages/send").size(), 2u);
+}
+
+// 场景:回复一段约 6000 字的长文(三段,每段 2000 字)。
+// 期望:按段落切成多条依次发送,每条不超过 3500 个字符,顺序与原文一致。
+TEST(DingTalkSend, SplitsLongTextInOrder) {
+    Server server;
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    start(transport, recorder, server);
+    const auto inbound = receive(server, recorder, "h1", server.private_text("m1", "staff01", "hi"));
+    std::string text;
+    for (const char* mark : {u8"甲", u8"乙", u8"丙"}) {
+        if (!text.empty()) text += "\n\n";
+        for (int i = 0; i < 2000; ++i) text += mark;
+    }
+    EXPECT_EQ(transport.send_text(inbound.address, text, inbound.reply_context).outcome, SendOutcome::Sent);
+    const auto sent = server.requests_to("/robot/sendBySession");
+    ASSERT_GE(sent.size(), 2u);
+    std::string joined;
+    for (const auto& r : sent) {
+        const auto part = r.body["markdown"].value("text", "");
+        EXPECT_LE(part.size() / 3, kMaxTextChars);
+        joined += part;
+    }
+    EXPECT_LT(joined.find(u8"甲"), joined.find(u8"乙"));
+    EXPECT_LT(joined.find(u8"乙"), joined.find(u8"丙"));
+}
+
+// 场景:回传一张会话生成的 PNG 图片。
+// 期望:按 type=image 上传拿到 mediaId,再以 Markdown 图片嵌入经 webhook 发送(不消耗 OpenAPI 额度)。
+TEST(DingTalkSend, SendsImagesAsEmbeddedMarkdown) {
+    Server server;
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    start(transport, recorder, server);
+    const auto inbound = receive(server, recorder, "h1", server.private_text("m1", "staff01", "chart"));
+    const auto file = std::filesystem::path(testing::TempDir()) / "acecode-dingtalk-chart.png";
+    { std::ofstream(file, std::ios::binary) << "PNGDATA"; }
+    const auto result = transport.send_file(inbound.address, file, "chart.png", "image/png", inbound.reply_context);
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto uploads = server.requests_to("/media/upload");
+    ASSERT_EQ(uploads.size(), 1u);
+    EXPECT_EQ(uploads[0].query, "image");
+    const auto sent = server.requests_to("/robot/sendBySession");
+    ASSERT_EQ(sent.size(), 1u);
+    EXPECT_EQ(sent[0].body["markdown"].value("text", ""), "![chart.png](@media-1)");
+    std::filesystem::remove(file);
+}
+
+// 场景:在群里回传一个 PDF 报告。
+// 期望:按 type=file 上传,再经 groupMessages/send 以 sampleFile 发送(mediaId、原文件名、扩展名)。
+TEST(DingTalkSend, SendsDocumentsThroughRobotApi) {
+    Server server;
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    start(transport, recorder, server);
+    const auto inbound = receive(server, recorder, "h1", server.group_text("g1", "cidG", "staff02", "report"));
+    const auto file = std::filesystem::path(testing::TempDir()) / "acecode-dingtalk-report.pdf";
+    { std::ofstream(file, std::ios::binary) << "PDF-DATA"; }
+    const auto result =
+        transport.send_file(inbound.address, file, u8"周报.pdf", "application/pdf", inbound.reply_context);
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto uploads = server.requests_to("/media/upload");
+    ASSERT_EQ(uploads.size(), 1u);
+    EXPECT_EQ(uploads[0].query, "file");
+    const auto sent = server.requests_to("/v1.0/robot/groupMessages/send");
+    ASSERT_EQ(sent.size(), 1u);
+    EXPECT_EQ(sent[0].body.value("msgKey", ""), "sampleFile");
+    const auto param = msg_param(sent[0]);
+    EXPECT_EQ(param.value("mediaId", ""), "@media-1");
+    EXPECT_EQ(param.value("fileName", ""), u8"周报.pdf");
+    EXPECT_EQ(param.value("fileType", ""), "pdf");
+    std::filesystem::remove(file);
+}
+
+// 场景:文件超过上传上限(测试里调到 4 字节);以及要把文件发给组织外用户。
+// 期望:两种情况都不上传,改发一条带文件名的文字说明,发送结果为已发送。
+TEST(DingTalkSend, UndeliverableFilesBecomeTextNotices) {
+    Server server;
+    Recorder recorder;
+    auto options = local_options(server);
+    options.max_upload_bytes = 4;
+    DingTalkTransport transport(options);
+    start(transport, recorder, server);
+    const auto inbound = receive(server, recorder, "h1", server.private_text("m1", "staff01", "big"));
+    const auto file = std::filesystem::path(testing::TempDir()) / "acecode-dingtalk-big.pdf";
+    { std::ofstream(file, std::ios::binary) << "PDF-DATA"; }
+    EXPECT_EQ(transport.send_file(inbound.address, file, "big.pdf", "application/pdf", inbound.reply_context).outcome,
+              SendOutcome::Sent);
+    const auto external = receive(server, recorder, "h2", server.private_text("m2", "", "ext", "S2"));
+    std::filesystem::resize_file(file, 2);
+    EXPECT_EQ(transport.send_file(external.address, file, "small.pdf", "application/pdf", external.reply_context).outcome,
+              SendOutcome::Sent);
+    EXPECT_TRUE(server.requests_to("/media/upload").empty());
+    const auto sent = server.requests_to("/robot/sendBySession");
+    ASSERT_EQ(sent.size(), 2u);
+    EXPECT_NE(sent[0].body["markdown"].value("text", "").find("big.pdf"), std::string::npos);
+    EXPECT_NE(sent[1].body["markdown"].value("text", "").find(u8"组织外"), std::string::npos);
+    std::filesystem::remove(file);
+}
+
+} // namespace
+} // namespace acecode::im::dingtalk
diff --git a/tests/im/dingtalk_stream_test.cpp b/tests/im/dingtalk_stream_test.cpp
new file mode 100644
index 000000000..c27aa72d3
--- /dev/null
+++ b/tests/im/dingtalk_stream_test.cpp
@@ -0,0 +1,171 @@
+#include <gtest/gtest.h>
+
+#include "im/dingtalk/dingtalk_protocol.hpp"
+#include "im/dingtalk/dingtalk_stream.hpp"
+
+// im/dingtalk/dingtalk_stream:Stream 帧解析、回执构造、断开指令、空闲检测与重连退避。
+// 全部用假时间驱动,不碰网络。
+
+namespace acecode::im::dingtalk {
+namespace {
+
+using Clock = StreamSession::Clock;
+using std::chrono::milliseconds;
+
+nlohmann::json parse(const std::string& text) { return nlohmann::json::parse(text); }
+
+std::string callback_frame(const std::string& id, const std::string& topic, const nlohmann::json& data) {
+    return nlohmann::json{{"specVersion", "1.0"},
+                          {"type", "CALLBACK"},
+                          {"headers", {{"messageId", id}, {"topic", topic}, {"contentType", "application/json"},
+                                       {"time", "1690106592000"}}},
+                          {"data", data.dump()}}
+        .dump();
+}
+
+// 场景:帧头的值有的是字符串、有的是数字(协议文档示例里 time 是数字),data 是 JSON 字符串。
+// 期望:type 统一为大写;topic / messageId 照常读出;数字头部不导致解析失败;data 保留原文。
+TEST(DingTalkStream, ParsesFramesWithMixedHeaderTypes) {
+    const auto frame = parse_stream_frame(
+        R"({"specVersion":"1.0","type":"system","headers":{"topic":"ping","messageId":12345,"time":1690106592000},"data":"{\"opaque\":\"abc\"}"})");
+    ASSERT_TRUE(frame);
+    EXPECT_EQ(frame->type, "SYSTEM");
+    EXPECT_EQ(frame->topic, "ping");
+    EXPECT_EQ(frame->message_id, "12345");
+    EXPECT_EQ(frame->data, R"({"opaque":"abc"})");
+    EXPECT_FALSE(parse_stream_frame("not json"));
+    EXPECT_FALSE(parse_stream_frame(R"({"headers":{}})"));
+}
+
+// 场景:平台发来 SYSTEM ping(带 opaque)。
+// 期望:回一帧 code 200 的回执,messageId 相同,data 逐字回显(平台靠 opaque 对账);不派发任何消息。
+TEST(DingTalkStream, PingIsEchoedVerbatim) {
+    StreamSession session;
+    const auto t0 = Clock::now();
+    session.on_connected(t0);
+    const auto out = session.on_frame(
+        R"({"type":"SYSTEM","headers":{"topic":"ping","messageId":"p1","contentType":"application/json"},"data":"{\"opaque\":\"123-dsfs\"}"})",
+        t0);
+    ASSERT_EQ(out.replies.size(), 1u);
+    const auto reply = parse(out.replies[0]);
+    EXPECT_EQ(reply["code"], 200);
+    EXPECT_EQ(reply["headers"]["messageId"], "p1");
+    EXPECT_EQ(reply["headers"]["contentType"], "application/json");
+    EXPECT_EQ(reply["data"], R"({"opaque":"123-dsfs"})");
+    EXPECT_TRUE(out.messages.empty());
+    EXPECT_FALSE(out.disconnect);
+}
+
+// 场景:收到机器人消息回调。
+// 期望:先产生 code 200 的回执(data 为 {"response":null}),同时把消息交给上层;回执在派发之前构造好。
+TEST(DingTalkStream, RobotCallbackIsAcknowledgedAndDispatched) {
+    StreamSession session;
+    const auto t0 = Clock::now();
+    session.on_connected(t0);
+    const auto out = session.on_frame(callback_frame("h1", kBotMessageTopic, {{"msgId", "m1"}}), t0);
+    ASSERT_EQ(out.replies.size(), 1u);
+    const auto reply = parse(out.replies[0]);
+    EXPECT_EQ(reply["code"], 200);
+    EXPECT_EQ(reply["headers"]["messageId"], "h1");
+    EXPECT_EQ(reply["data"], kCallbackAckData);
+    ASSERT_EQ(out.messages.size(), 1u);
+    EXPECT_EQ(out.messages[0].message_id, "h1");
+    EXPECT_EQ(parse(out.messages[0].data)["msgId"], "m1");
+}
+
+// 场景:本地待处理队列已满时又来了一条机器人消息。
+// 期望:不回执、不派发(deferred=true),让平台约 60 秒后重投,而不是回执后丢掉。
+TEST(DingTalkStream, FullQueueLeavesCallbackUnacknowledged) {
+    StreamSession session;
+    const auto t0 = Clock::now();
+    session.on_connected(t0);
+    const auto out = session.on_frame(callback_frame("h2", kBotMessageTopic, {{"msgId", "m2"}}), t0, false);
+    EXPECT_TRUE(out.deferred);
+    EXPECT_TRUE(out.replies.empty());
+    EXPECT_TRUE(out.messages.empty());
+}
+
+// 场景:收到未订阅的回调主题,以及一个(未订阅却到达的)EVENT。
+// 期望:未知回调主题回 404;EVENT 回 SUCCESS 防止平台反复重投;两者都不派发。
+TEST(DingTalkStream, UnknownTopicsAreAnsweredButNotDispatched) {
+    StreamSession session;
+    const auto t0 = Clock::now();
+    session.on_connected(t0);
+    const auto unknown = session.on_frame(callback_frame("h3", "/v1.0/card/instances/callback", {}), t0);
+    ASSERT_EQ(unknown.replies.size(), 1u);
+    EXPECT_EQ(parse(unknown.replies[0])["code"], 404);
+    EXPECT_TRUE(unknown.messages.empty());
+    EXPECT_FALSE(unknown.ignored_topic.empty());
+
+    const auto event = session.on_frame(
+        R"({"type":"EVENT","headers":{"topic":"*","messageId":"e1","eventType":"user_add_org"},"data":"{}"})", t0);
+    ASSERT_EQ(event.replies.size(), 1u);
+    EXPECT_EQ(parse(event.replies[0])["data"], kEventAckData);
+    EXPECT_TRUE(event.messages.empty());
+}
+
+// 场景:平台发来 SYSTEM disconnect;一次带 messageId,一次不带(协议允许缺省)。
+// 期望:带 messageId 时先回执再要求断开;不带时不回执,只要求断开。
+TEST(DingTalkStream, DisconnectRequestsReconnect) {
+    StreamSession session;
+    const auto t0 = Clock::now();
+    session.on_connected(t0);
+    const auto with_id = session.on_frame(
+        R"({"type":"SYSTEM","headers":{"topic":"disconnect","messageId":"d1"},"data":"{\"reason\":\"connection is expired\"}"})",
+        t0);
+    EXPECT_TRUE(with_id.disconnect);
+    ASSERT_EQ(with_id.replies.size(), 1u);
+    EXPECT_EQ(parse(with_id.replies[0])["headers"]["messageId"], "d1");
+
+    const auto without_id =
+        session.on_frame(R"({"type":"SYSTEM","headers":{"topic":"disconnect"},"data":"{}"})", t0);
+    EXPECT_TRUE(without_id.disconnect);
+    EXPECT_TRUE(without_id.replies.empty());
+}
+
+// 场景:收到一帧无法解析的文本。
+// 期望:标记 invalid,不回执、不派发;它仍算作连接存活的证据(帧计数增加)。
+TEST(DingTalkStream, InvalidFrameIsReportedButKeepsLiveness) {
+    StreamSession session(milliseconds(1000));
+    const auto t0 = Clock::now();
+    session.on_connected(t0);
+    const auto out = session.on_frame("<<garbage>>", t0 + milliseconds(900));
+    EXPECT_TRUE(out.invalid);
+    EXPECT_TRUE(out.replies.empty());
+    EXPECT_EQ(session.frames(), 1u);
+    EXPECT_FALSE(session.idle_expired(t0 + milliseconds(1800)));
+}
+
+// 场景:空闲检测阈值 1 秒;连接后一直没有帧,然后收到一帧 ping。
+// 期望:未满 1 秒不判定失效;满 1 秒判定失效;收到帧后从该时刻重新计时;阈值为 0 时永不判定。
+TEST(DingTalkStream, IdleTimeoutTracksLastFrame) {
+    StreamSession session(milliseconds(1000));
+    const auto t0 = Clock::now();
+    session.on_connected(t0);
+    EXPECT_FALSE(session.idle_expired(t0 + milliseconds(999)));
+    EXPECT_TRUE(session.idle_expired(t0 + milliseconds(1000)));
+    session.on_frame(R"({"type":"SYSTEM","headers":{"topic":"ping","messageId":"p"},"data":"{}"})",
+                     t0 + milliseconds(1500));
+    EXPECT_FALSE(session.idle_expired(t0 + milliseconds(2000)));
+    EXPECT_TRUE(session.idle_expired(t0 + milliseconds(2500)));
+
+    StreamSession unlimited(milliseconds(0));
+    unlimited.on_connected(t0);
+    EXPECT_FALSE(unlimited.idle_expired(t0 + std::chrono::hours(5)));
+}
+
+// 场景:连续重连失败时的等待(基数 1 秒、上限 60 秒)。
+// 期望:1、2、4…秒翻倍,抖动叠加在上面,总等待不超过上限。
+TEST(DingTalkStream, BackoffDoublesUpToCap) {
+    const milliseconds base(1000), cap(60000), none(0);
+    EXPECT_EQ(stream_backoff(0, base, cap, none), milliseconds(1000));
+    EXPECT_EQ(stream_backoff(1, base, cap, none), milliseconds(2000));
+    EXPECT_EQ(stream_backoff(3, base, cap, none), milliseconds(8000));
+    EXPECT_EQ(stream_backoff(10, base, cap, none), milliseconds(60000));
+    EXPECT_EQ(stream_backoff(100, base, cap, none), milliseconds(60000));
+    EXPECT_EQ(stream_backoff(1, base, cap, milliseconds(500)), milliseconds(2500));
+    EXPECT_EQ(stream_backoff(10, base, cap, milliseconds(500)), milliseconds(60000));
+}
+
+} // namespace
+} // namespace acecode::im::dingtalk
diff --git a/tests/im/dingtalk_transport_test.cpp b/tests/im/dingtalk_transport_test.cpp
new file mode 100644
index 000000000..430cd1be6
--- /dev/null
+++ b/tests/im/dingtalk_transport_test.cpp
@@ -0,0 +1,329 @@
+#include <gtest/gtest.h>
+
+#include "im/dingtalk/dingtalk_transport.hpp"
+#include "test_support/im/fake_dingtalk_server.hpp"
+
+#include <condition_variable>
+#include <functional>
+#include <mutex>
+#include <vector>
+
+// im/dingtalk/dingtalk_transport:钉钉传输层的连接与收消息端到端测试。本机假开放平台提供
+// Stream 注册、一次性 ticket 的 WebSocket 网关与机器人回调推送;覆盖连接、先回执后处理、
+// 两层去重、ping 回显、断开指令立即重连、空闲重连、致命错误停止重试与附件下载。
+
+namespace acecode::im::dingtalk {
+namespace {
+
+using Server = test::FakeDingTalkServer;
+
+DingTalkTransportOptions local_options(Server& server) {
+    DingTalkTransportOptions options;
+    options.api.client_id = server.client_id;
+    options.api.client_secret = server.client_secret;
+    options.api.api_base = server.base();
+    options.api.oapi_base = server.base();
+    options.api.use_proxy = false;
+    options.backoff_base = std::chrono::milliseconds(50);
+    options.backoff_cap = std::chrono::milliseconds(200);
+    options.jitter = false;
+    options.idle_timeout = std::chrono::milliseconds(0);
+    options.healthy_after = std::chrono::milliseconds(0);
+    options.throttle_delay = std::chrono::milliseconds(100);
+    options.qps_delay = std::chrono::milliseconds(50);
+    return options;
+}
+
+struct Recorder {
+    std::mutex mu;
+    std::vector<Inbound> inbound;
+    std::vector<TransportStatus> statuses;
+    std::function<void(const Inbound&)> hook;  // 在传输层分发线程上、记录之前调用
+    TransportCallbacks callbacks() {
+        TransportCallbacks cb;
+        cb.on_inbound = [this](Inbound in) {
+            if (hook) hook(in);
+            std::lock_guard<std::mutex> lock(mu);
+            inbound.push_back(std::move(in));
+        };
+        cb.on_status = [this](const TransportStatus& s) {
+            std::lock_guard<std::mutex> lock(mu);
+            statuses.push_back(s);
+        };
+        return cb;
+    }
+    std::size_t inbound_count() {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.size();
+    }
+    Inbound inbound_at(std::size_t i) {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.at(i);
+    }
+};
+
+bool wait_connected(DingTalkTransport& transport) {
+    return Server::wait_until([&transport] { return transport.status().state == LinkState::Connected; });
+}
+
+// 已连接且假网关已登记第 connections 条连接(之后 push 一定落在这条连接上)。
+bool wait_ready(DingTalkTransport& transport, Server& server, int connections = 1) {
+    return wait_connected(transport) &&
+           Server::wait_until([&server, connections] { return server.connections() >= connections; });
+}
+
+// 场景:开启钉钉通道,Stream 注册拿到 ticket 后连上网关,平台推来一条单聊消息。
+// 期望:注册请求带 clientId 与机器人回调订阅;握手使用刚发的 ticket;状态变为已连接;
+// 入站消息地址为 Client ID + staffId;该帧以 code 200 回执;停止后状态为已停止。
+TEST(DingTalkTransport, ConnectsAndReceivesPrivateMessage) {
+    Server server;
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_ready(transport, server));
+    EXPECT_EQ(transport.status().account, server.client_id);
+    const auto open = server.requests_to("/v1.0/gateway/connections/open");
+    ASSERT_EQ(open.size(), 1u);
+    EXPECT_EQ(open[0].body.value("clientId", ""), server.client_id);
+    EXPECT_EQ(server.used_tickets(), std::vector<std::string>{"ticket-1"});
+
+    server.push_callback("h1", server.private_text("m1", "staff01", u8" 你好 "));
+    ASSERT_TRUE(Server::wait_until([&recorder] { return recorder.inbound_count() == 1; }));
+    const auto inbound = recorder.inbound_at(0);
+    EXPECT_EQ(inbound.address.platform, "dingtalk");
+    EXPECT_EQ(inbound.address.account, server.client_id);
+    EXPECT_EQ(inbound.address.chat, "staff01");
+    EXPECT_EQ(inbound.text, u8"你好");
+    EXPECT_EQ(inbound.reply_context.value("sessionWebhook", ""), server.webhook("S1"));
+    ASSERT_TRUE(Server::wait_until([&server] { return server.has_ack("h1"); }));
+    for (const auto& ack : server.acks()) {
+        if (ack["headers"].value("messageId", "") == "h1") EXPECT_EQ(ack.value("code", 0), 200);
+    }
+    transport.stop();
+    EXPECT_EQ(transport.status().state, LinkState::Stopped);
+}
+
+// 场景:上层处理一条消息很慢(处理函数阻塞);处理期间平台又发来 SYSTEM ping。
+// 期望:回执在处理完成之前就已送达平台(先回执后处理);ping 照样被及时回执 —— 读线程不被处理阻塞。
+// 回归:若在读线程上处理消息,慢处理会让平台收不到回执而重投,并因 ping 无回应判定连接失效。
+TEST(DingTalkTransport, AcknowledgesBeforeProcessingAndKeepsReading) {
+    Server server;
+    // 回调里用到的对象都声明在传输层之前,保证传输层先析构(先停线程)。
+    Recorder recorder;
+    std::mutex gate_mu;
+    std::condition_variable gate_cv;
+    bool release = false;
+    std::atomic<bool> acked_while_blocked{false};
+    DingTalkTransport transport(local_options(server));
+    recorder.hook = [&server, &gate_mu, &gate_cv, &release, &acked_while_blocked](const Inbound&) {
+        acked_while_blocked = Server::wait_until([&server] { return server.has_ack("h1"); });
+        std::unique_lock<std::mutex> lock(gate_mu);
+        gate_cv.wait_for(lock, std::chrono::seconds(5), [&release] { return release; });
+    };
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_ready(transport, server));
+    server.push_callback("h1", server.private_text("m1", "staff01", "slow"));
+    ASSERT_TRUE(Server::wait_until([&acked_while_blocked] { return acked_while_blocked.load(); }));
+    server.push_ping("p1", "op-1");
+    EXPECT_TRUE(Server::wait_until([&server] { return server.has_ack("p1"); }));
+    EXPECT_EQ(recorder.inbound_count(), 0u);  // 处理函数仍阻塞着
+    {
+        std::lock_guard<std::mutex> lock(gate_mu);
+        release = true;
+    }
+    gate_cv.notify_all();
+    EXPECT_TRUE(Server::wait_until([&recorder] { return recorder.inbound_count() == 1; }));
+    transport.stop();
+}
+
+// 场景:平台重投同一条消息(帧头 messageId 换新、msgId 不变),以及同一帧被重复推送。
+// 期望:每一帧都回执(否则平台会继续重投);上层只收到一次。
+TEST(DingTalkTransport, DeduplicatesRedeliveryOnBothIds) {
+    Server server;
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_ready(transport, server));
+    const auto data = server.private_text("m1", "staff01", "hi");
+    server.push_callback("h1", data);
+    server.push_callback("h2", data);
+    server.push_callback("h1", data);
+    server.push_callback("h3", server.private_text("m2", "staff01", "second"));
+    ASSERT_TRUE(Server::wait_until([&recorder] { return recorder.inbound_count() == 2; }));
+    ASSERT_TRUE(Server::wait_until([&server] { return server.has_ack("h2") && server.has_ack("h3"); }));
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    EXPECT_EQ(recorder.inbound_count(), 2u);
+    EXPECT_EQ(recorder.inbound_at(1).message_id, "m2");
+}
+
+// 场景:平台发来 SYSTEM ping,data 里带 opaque。
+// 期望:回执的 messageId 相同,data 逐字回显 opaque。
+TEST(DingTalkTransport, AnswersPingWithOpaqueEcho) {
+    Server server;
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_ready(transport, server));
+    server.push_ping("p9", "opaque-123");
+    ASSERT_TRUE(Server::wait_until([&server] { return server.has_ack("p9"); }));
+    for (const auto& ack : server.acks()) {
+        if (ack["headers"].value("messageId", "") != "p9") continue;
+        EXPECT_EQ(ack.value("code", 0), 200);
+        EXPECT_EQ(nlohmann::json::parse(ack.value("data", "{}")).value("opaque", ""), "opaque-123");
+    }
+}
+
+// 场景:平台发来 SYSTEM disconnect(负载切换)。退避基数故意设成 5 秒。
+// 期望:先回执,再关闭并立即(不等 5 秒退避)用新的 ticket 重新注册、重连,回到已连接。
+// 回归:ticket 一次性,复用旧 ticket 会握手失败。
+TEST(DingTalkTransport, DisconnectReconnectsImmediatelyWithFreshTicket) {
+    Server server;
+    auto options = local_options(server);
+    options.backoff_base = std::chrono::seconds(5);
+    options.backoff_cap = std::chrono::seconds(5);
+    Recorder recorder;
+    DingTalkTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_ready(transport, server));
+    server.push_disconnect("d1");
+    ASSERT_TRUE(Server::wait_until([&server] { return server.connections() == 2; }, std::chrono::seconds(2)));
+    EXPECT_TRUE(server.has_ack("d1"));
+    EXPECT_EQ(server.used_tickets(), (std::vector<std::string>{"ticket-1", "ticket-2"}));
+    ASSERT_TRUE(wait_connected(transport));
+    server.push_callback("h1", server.private_text("m1", "staff01", "after reconnect"));
+    EXPECT_TRUE(Server::wait_until([&recorder] { return recorder.inbound_count() == 1; }));
+}
+
+// 场景:网关直接关闭连接(网络抖动、服务端重启)。
+// 期望:按退避等待后重新注册并重连,回到已连接。
+TEST(DingTalkTransport, ReconnectsAfterServerClose) {
+    Server server;
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_ready(transport, server));
+    server.close_connection(1001);
+    ASSERT_TRUE(Server::wait_until([&server] { return server.connections() == 2; }));
+    EXPECT_TRUE(wait_connected(transport));
+    EXPECT_EQ(server.issued_tickets().size(), 2u);
+}
+
+// 场景:连接建立后平台一直不发任何帧(半开连接);空闲阈值设为 300 毫秒。
+// 期望:判定连接失效并主动重连。
+TEST(DingTalkTransport, ReplacesIdleConnection) {
+    Server server;
+    auto options = local_options(server);
+    options.idle_timeout = std::chrono::milliseconds(300);
+    Recorder recorder;
+    DingTalkTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_ready(transport, server));
+    EXPECT_TRUE(Server::wait_until([&server] { return server.connections() >= 2; }));
+}
+
+// 场景:Stream 注册第一次返回 500(平台临时故障),之后恢复。
+// 期望:状态先是重试中,随后自动连上;共注册两次。
+TEST(DingTalkTransport, RetriesTemporaryRegistrationFailure) {
+    Server server;
+    std::atomic<int> calls{0};
+    server.open_handler = [&calls](const Server::Request&) {
+        if (calls++ == 0) return Server::Reply{500, {{"code", "ServiceUnavailable"}, {"message", "busy"}}};
+        return Server::Reply{0, nullptr};
+    };
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_ready(transport, server));
+    EXPECT_EQ(server.requests_to("/v1.0/gateway/connections/open").size(), 2u);
+    bool retried = false;
+    {
+        std::lock_guard<std::mutex> lock(recorder.mu);
+        for (const auto& s : recorder.statuses) retried = retried || s.state == LinkState::Retrying;
+    }
+    EXPECT_TRUE(retried);
+}
+
+// 场景:Client Secret 错误,Stream 注册返回 401 authFailed。
+// 期望:状态变为失败且停止重试,不建立 WebSocket;原因提示核对凭据且不含密钥原文;之后不再注册。
+TEST(DingTalkTransport, InvalidCredentialsStopRetrying) {
+    Server server;
+    auto options = local_options(server);
+    options.api.client_secret = "wrong-secret-value-999";
+    Recorder recorder;
+    DingTalkTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(Server::wait_until([&transport] { return transport.status().state == LinkState::Failed; }));
+    const auto status = transport.status();
+    EXPECT_TRUE(status.retry_stopped);
+    EXPECT_NE(status.detail.find("Client Secret"), std::string::npos) << status.detail;
+    EXPECT_EQ(status.detail.find("wrong-secret-value-999"), std::string::npos);
+    std::this_thread::sleep_for(std::chrono::milliseconds(300));
+    EXPECT_EQ(server.connections(), 0);
+    EXPECT_EQ(server.requests_to("/v1.0/gateway/connections/open").size(), 1u);
+}
+
+// 场景:应用未发布或机器人未开 Stream 模式,Stream 注册返回 400。
+// 期望:失败并停止重试(用户在钉钉后台处理后重新打开开关即可),原因提到发布与 Stream 模式。
+TEST(DingTalkTransport, UnpublishedAppStopsRetrying) {
+    Server server;
+    server.open_handler = [](const Server::Request&) {
+        return Server::Reply{400, {{"code", "invalidParameter"}, {"message", "app not published"}}};
+    };
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(Server::wait_until([&transport] { return transport.status().state == LinkState::Failed; }));
+    EXPECT_TRUE(transport.status().retry_stopped);
+    EXPECT_NE(transport.status().detail.find(u8"Stream 模式"), std::string::npos);
+}
+
+// 场景:群里 @机器人 发消息,开头带着机器人的 @名字。
+// 期望:群地址按 conversationId + staffId;mentioned=true;@名字已去掉。
+TEST(DingTalkTransport, ReceivesGroupMention) {
+    Server server;
+    Recorder recorder;
+    DingTalkTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_ready(transport, server));
+    server.push_callback("h1", server.group_text("g1", "cidGROUP", "staff02", u8"@ACE /status"));
+    ASSERT_TRUE(Server::wait_until([&recorder] { return recorder.inbound_count() == 1; }));
+    const auto inbound = recorder.inbound_at(0);
+    EXPECT_EQ(inbound.address.kind, ChatKind::Group);
+    EXPECT_EQ(inbound.address.chat, "cidGROUP");
+    EXPECT_EQ(inbound.address.sender, "staff02");
+    EXPECT_TRUE(inbound.mentioned);
+    EXPECT_EQ(inbound.text, "/status");
+}
+
+// 场景:用户发来一张图片,核心下载它;另一张图片超过本地下载上限。
+// 期望:用 downloadCode 换地址后下载成功;超限时返回 false 并给出中文原因。
+TEST(DingTalkTransport, DownloadsPictureAttachment) {
+    Server server;
+    auto options = local_options(server);
+    options.max_download_bytes = 100;
+    Recorder recorder;
+    DingTalkTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_ready(transport, server));
+    auto data = server.private_text("m1", "staff01", "");
+    data.erase("text");
+    data["msgtype"] = "picture";
+    data["content"] = {{"downloadCode", "code1"}};
+    server.push_callback("h1", data);
+    ASSERT_TRUE(Server::wait_until([&recorder] { return recorder.inbound_count() == 1; }));
+    const auto inbound = recorder.inbound_at(0);
+    ASSERT_EQ(inbound.attachments.size(), 1u);
+    const auto dest = std::filesystem::path(testing::TempDir()) / "acecode-dingtalk-pic.bin";
+    std::string error;
+    ASSERT_TRUE(transport.download(inbound.attachments[0], dest, &error)) << error;
+    EXPECT_EQ(std::filesystem::file_size(dest), 16u);
+
+    auto big = inbound.attachments[0];
+    big.remote_ref = "big";
+    EXPECT_FALSE(transport.download(big, dest, &error));
+    EXPECT_NE(error.find(u8"超过"), std::string::npos);
+    std::filesystem::remove(dest);
+}
+
+} // namespace
+} // namespace acecode::im::dingtalk
diff --git a/tests/im/discord_api_test.cpp b/tests/im/discord_api_test.cpp
new file mode 100644
index 000000000..bd53cec1b
--- /dev/null
+++ b/tests/im/discord_api_test.cpp
@@ -0,0 +1,163 @@
+#include <gtest/gtest.h>
+
+#include "im/discord/discord_api.hpp"
+#include "test_support/im/fake_discord_server.hpp"
+
+#include <atomic>
+#include <future>
+
+// im/discord/discord_api:Discord REST 客户端与凭据校验(本机假 Discord,不连真实平台)。
+// 覆盖:鉴权头与 User-Agent、token 校验三种结果(成功 / token 无效 / 网络不通)、intent 开关、
+// 发消息的 nonce 幂等重发、429 等待重发、等待过长放弃、停机打断等待。
+
+namespace acecode::im::discord {
+namespace {
+
+ApiOptions local_options(const test::FakeDiscordServer& server) {
+    ApiOptions options;
+    options.token = server.token;
+    options.api_base = server.api_base();
+    options.use_proxy = false;
+    return options;
+}
+
+// 场景:用户在设置页填入正确的 bot token,保存前联网校验。
+// 期望:成功;给出机器人 id、用户名、应用 id、Message Content Intent 已开启,以及邀请链接;
+// 请求带 "Authorization: Bot <token>" 与 "DiscordBot (...)" 格式的 User-Agent。
+TEST(DiscordApi, ValidatesTokenAndReadsApplication) {
+    test::FakeDiscordServer server;
+    const auto result = validate_credentials(local_options(server));
+    ASSERT_TRUE(result.ok) << result.error;
+    EXPECT_EQ(result.profile.user_id, server.bot_id);
+    EXPECT_EQ(result.profile.username, "AceBot");
+    EXPECT_EQ(result.profile.application_id, server.application_id);
+    EXPECT_EQ(result.profile.application_name, "Ace App");
+    EXPECT_EQ(result.profile.message_content, IntentState::Enabled);
+    EXPECT_NE(result.profile.invite_url.find("client_id=" + server.application_id), std::string::npos);
+    const auto me = server.requests_to("GET", "/users/@me");
+    ASSERT_EQ(me.size(), 1u);
+    EXPECT_EQ(me[0].authorization, "Bot " + server.token);
+    EXPECT_EQ(me[0].user_agent.rfind("DiscordBot (", 0), 0u) << me[0].user_agent;
+}
+
+// 场景:用户从别处复制时带上了 "Bot " 前缀和首尾空白;应用没有开启 Message Content Intent。
+// 期望:前缀与空白被去掉后校验成功;intent 状态为“未开启”(设置向导据此提示去后台打开开关),
+// 但不影响校验通过。
+TEST(DiscordApi, AcceptsBotPrefixAndReportsDisabledIntent) {
+    test::FakeDiscordServer server;
+    server.application_flags = 0;
+    auto options = local_options(server);
+    options.token = "  Bot " + server.token + "  ";
+    const auto result = validate_credentials(options);
+    ASSERT_TRUE(result.ok) << result.error;
+    EXPECT_EQ(result.profile.message_content, IntentState::Disabled);
+}
+
+// 场景:token 错误(已重置或抄错),平台返回 401。
+// 期望:失败且标记为凭据无效(不要重试);原因是一句明确的中文;错误文本里没有 token。
+TEST(DiscordApi, RejectsInvalidTokenWithoutLeakingIt) {
+    test::FakeDiscordServer server;
+    auto options = local_options(server);
+    options.token = "OTk5OTk5.wrong.token-value-that-should-never-be-logged";
+    const auto result = validate_credentials(options);
+    EXPECT_FALSE(result.ok);
+    EXPECT_TRUE(result.auth_failed);
+    EXPECT_NE(result.error.find(u8"无效"), std::string::npos) << result.error;
+    EXPECT_EQ(result.error.find("token-value-that-should-never-be-logged"), std::string::npos);
+}
+
+// 场景:网络不通(连接被拒)。
+// 期望:失败但不标记为凭据无效(换网络后可以重试);原因说明无法连接 Discord。
+TEST(DiscordApi, DistinguishesNetworkFailureFromInvalidToken) {
+    ApiOptions options;
+    options.token = "OTk5OTk5.some.token";
+    options.api_base = "http://127.0.0.1:1/api/v10";
+    options.use_proxy = false;
+    const auto result = validate_credentials(options);
+    EXPECT_FALSE(result.ok);
+    EXPECT_FALSE(result.auth_failed);
+    EXPECT_NE(result.error.find(u8"无法连接"), std::string::npos) << result.error;
+}
+
+// 场景:发消息时平台先返回 502(请求可能其实已送达),第二次成功。
+// 期望:用同一个 nonce(且 enforce_nonce=true)重发,平台据此去重,不会出现两条相同消息。
+TEST(DiscordApi, CreateMessageRetriesTransientErrorsWithSameNonce) {
+    test::FakeDiscordServer server;
+    std::atomic<int> calls{0};
+    server.message_handler = [&calls](const test::FakeDiscordServer::Request&) {
+        if (calls++ == 0) return std::make_pair(502, nlohmann::json{{"message", "bad gateway"}});
+        return std::make_pair(0, nlohmann::json());
+    };
+    RateLimitPolicy policy;
+    policy.send_retry_delay = std::chrono::milliseconds(10);
+    Api api(local_options(server), policy);
+    const auto result = api.create_message("500000000000000001", {{"content", "hi"}});
+    ASSERT_TRUE(result.ok) << result.error.message;
+    const auto sent = server.requests_to("POST", "/channels/500000000000000001/messages");
+    ASSERT_EQ(sent.size(), 2u);
+    EXPECT_FALSE(sent[0].body.value("nonce", "").empty());
+    EXPECT_EQ(sent[0].body.value("nonce", ""), sent[1].body.value("nonce", "x"));
+    EXPECT_TRUE(sent[1].body.value("enforce_nonce", false));
+}
+
+// 场景:发消息遇到 429,响应体 retry_after=0.2(秒,小数)。
+// 期望:等待约 0.2 秒后原样重发并成功;总共两次请求。
+TEST(DiscordApi, WaitsRetryAfterOn429) {
+    test::FakeDiscordServer server;
+    std::atomic<int> calls{0};
+    server.message_handler = [&calls](const test::FakeDiscordServer::Request&) {
+        if (calls++ == 0)
+            return std::make_pair(429, nlohmann::json{{"message", "You are being rate limited."},
+                                                      {"retry_after", 0.2}, {"global", false}, {"code", 20028}});
+        return std::make_pair(0, nlohmann::json());
+    };
+    Api api(local_options(server));
+    const auto begin = std::chrono::steady_clock::now();
+    const auto result = api.create_message("500000000000000001", {{"content", "hi"}});
+    const auto elapsed = std::chrono::steady_clock::now() - begin;
+    ASSERT_TRUE(result.ok) << result.error.message;
+    EXPECT_EQ(calls.load(), 2);
+    EXPECT_GE(elapsed, std::chrono::milliseconds(150));
+}
+
+// 场景:429 要求等待 120 秒,超过允许的单次等待上限(测试里设为 1 秒)。
+// 期望:不等待、不重发,直接以 429 失败返回,调用方给用户“限流,稍后再试”。
+TEST(DiscordApi, GivesUpWhenRetryAfterExceedsLimit) {
+    test::FakeDiscordServer server;
+    server.message_handler = [](const test::FakeDiscordServer::Request&) {
+        return std::make_pair(429, nlohmann::json{{"message", "You are being rate limited."},
+                                                  {"retry_after", 120.0}, {"global", false}});
+    };
+    RateLimitPolicy policy;
+    policy.max_wait = std::chrono::seconds(1);
+    Api api(local_options(server), policy);
+    const auto result = api.create_message("500000000000000001", {{"content", "hi"}});
+    EXPECT_FALSE(result.ok);
+    EXPECT_EQ(result.status, 429);
+    EXPECT_EQ(server.requests_to("POST", "/channels/").size(), 1u);
+}
+
+// 场景:发消息正在等一个 30 秒的 429,此时通道被关闭(stop 调用 cancel)。
+// 期望:等待立即被打断,调用在 3 秒内以 cancelled 返回,不会把停机卡住。
+TEST(DiscordApi, CancelInterruptsRateLimitWait) {
+    test::FakeDiscordServer server;
+    server.message_handler = [](const test::FakeDiscordServer::Request&) {
+        return std::make_pair(429, nlohmann::json{{"message", "You are being rate limited."},
+                                                  {"retry_after", 30.0}, {"global", true}});
+    };
+    Api api(local_options(server));
+    auto pending = std::async(std::launch::async, [&api] {
+        return api.create_message("500000000000000001", {{"content", "hi"}});
+    });
+    ASSERT_TRUE(test::FakeDiscordServer::wait_until(
+        [&server] { return server.requests_to("POST", "/channels/").size() == 1; }));
+    std::this_thread::sleep_for(std::chrono::milliseconds(100));
+    api.cancel();
+    ASSERT_EQ(pending.wait_for(std::chrono::seconds(3)), std::future_status::ready);
+    const auto result = pending.get();
+    EXPECT_FALSE(result.ok);
+    EXPECT_TRUE(result.cancelled);
+}
+
+} // namespace
+} // namespace acecode::im::discord
diff --git a/tests/im/discord_gateway_test.cpp b/tests/im/discord_gateway_test.cpp
new file mode 100644
index 000000000..8c9efa2eb
--- /dev/null
+++ b/tests/im/discord_gateway_test.cpp
@@ -0,0 +1,266 @@
+#include <gtest/gtest.h>
+
+#include "im/discord/discord_gateway.hpp"
+
+// im/discord/discord_gateway:Discord 网关会话状态机与登录预算。全部用假时间驱动,不碰网络。
+
+namespace acecode::im::discord {
+namespace {
+
+using Clock = GatewaySession::Clock;
+using std::chrono::milliseconds;
+
+nlohmann::json parse(const std::string& text) { return nlohmann::json::parse(text); }
+
+std::string hello(int interval_ms) {
+    return nlohmann::json{{"op", 10}, {"d", {{"heartbeat_interval", interval_ms}}}}.dump();
+}
+
+std::string ready(int seq) {
+    return nlohmann::json{{"op", 0},
+                          {"t", "READY"},
+                          {"s", seq},
+                          {"d",
+                           {{"v", 10},
+                            {"user", {{"id", "900"}, {"username", "AceBot"}, {"bot", true}}},
+                            {"guilds", nlohmann::json::array({{{"id", "1"}, {"unavailable", true}},
+                                                              {{"id", "2"}, {"unavailable", true}}})},
+                            {"session_id", "S1"},
+                            {"resume_gateway_url", "wss://resume.discord.gg"},
+                            {"application", {{"id", "901"}, {"flags", 1 << 19}}}}}}
+        .dump();
+}
+
+// 场景:新连接收到 Hello(心跳间隔 40 秒),本次连接的抖动系数为 0.5。
+// 期望:立即回 Identify:token 是原始 token(不带 "Bot " 前缀)、intents=37377、properties 用新写法
+// (os/browser/device,不带 $);首拍心跳在 40×0.5=20 秒时,之前不发。
+TEST(DiscordGateway, HelloSendsIdentifyAndSchedulesJitteredFirstBeat) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("raw-token", t0, 0.5);
+    const auto out = session.on_frame(hello(40000), t0);
+    ASSERT_EQ(out.frames.size(), 1u);
+    EXPECT_TRUE(out.identified);
+    const auto identify = parse(out.frames[0]);
+    EXPECT_EQ(identify["op"], 2);
+    EXPECT_EQ(identify["d"]["token"], "raw-token");
+    EXPECT_EQ(identify["d"]["intents"], kIntents);
+    EXPECT_EQ(identify["d"]["intents"], 37377);
+    EXPECT_EQ(identify["d"]["properties"]["browser"], "acecode");
+    EXPECT_FALSE(identify["d"]["properties"].contains("$os"));
+    EXPECT_FALSE(identify["d"].contains("compress"));
+    EXPECT_EQ(session.heartbeat_interval(), milliseconds(40000));
+    EXPECT_FALSE(session.on_tick(t0 + milliseconds(19999)).heartbeat);
+    EXPECT_TRUE(session.on_tick(t0 + milliseconds(20000)).heartbeat);
+}
+
+// 场景:收到 READY,随后一条 MESSAGE_CREATE。
+// 期望:READY 让连接可用,记下 session_id、恢复地址、机器人 id/名、应用 id/flags、服务器数量;
+// 消息事件作为派发交给上层(READY 本身不派发);seq 跟着更新,可以恢复。
+TEST(DiscordGateway, ReadyRecordsSessionAndDispatchesEvents) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0, 0.0);
+    session.on_frame(hello(40000), t0);
+    const auto r = session.on_frame(ready(1), t0);
+    EXPECT_TRUE(r.ready);
+    EXPECT_FALSE(r.resumed);
+    EXPECT_TRUE(r.dispatches.empty());
+    ASSERT_TRUE(r.ready_info);
+    EXPECT_EQ(r.ready_info->bot_id, "900");
+    EXPECT_EQ(r.ready_info->bot_name, "AceBot");
+    EXPECT_EQ(r.ready_info->application_id, "901");
+    EXPECT_EQ(r.ready_info->application_flags, 1 << 19);
+    EXPECT_EQ(r.ready_info->guild_count, 2u);
+    EXPECT_EQ(session.session_id(), "S1");
+    EXPECT_EQ(session.resume_url(), "wss://resume.discord.gg");
+    const auto m = session.on_frame(
+        nlohmann::json{{"op", 0}, {"t", "MESSAGE_CREATE"}, {"s", 2}, {"d", {{"id", "M1"}}}}.dump(), t0);
+    ASSERT_EQ(m.dispatches.size(), 1u);
+    EXPECT_EQ(m.dispatches[0].first, "MESSAGE_CREATE");
+    EXPECT_EQ(session.last_seq(), 2);
+    EXPECT_TRUE(session.can_resume());
+}
+
+// 场景:首拍心跳发出后一直没有 ACK,又到了下一拍;另一种情况是收到 ACK 后照常继续。
+// 期望:心跳帧带最新 seq;没等到 ACK 就到期时判定假死(应以非 1000 关闭码断开并恢复);
+// 收到 op 11 后恢复正常节奏。还没收到任何 Dispatch 时心跳的 d 为 null。
+TEST(DiscordGateway, HeartbeatCarriesSequenceAndDetectsZombie) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0, 0.0);
+    session.on_frame(hello(10000), t0);
+    const auto first = session.on_tick(t0);
+    ASSERT_TRUE(first.heartbeat);
+    EXPECT_TRUE(parse(*first.heartbeat)["d"].is_null());
+    session.on_frame(R"({"op":11})", t0);
+    session.on_frame(ready(5), t0);
+    const auto beat = session.on_tick(t0 + milliseconds(10000));
+    ASSERT_TRUE(beat.heartbeat);
+    EXPECT_EQ(parse(*beat.heartbeat)["d"], 5);
+    EXPECT_TRUE(session.on_tick(t0 + milliseconds(20000)).zombie);
+    session.on_frame(R"({"op":11})", t0 + milliseconds(20000));
+    EXPECT_TRUE(session.on_tick(t0 + milliseconds(20001)).heartbeat);
+}
+
+// 场景:连上之后 20 秒(默认超时)还没收到 Hello。
+// 期望:on_tick 报告 hello_timeout,传输层据此断开重连;收到 Hello 前不发心跳。
+TEST(DiscordGateway, ReportsMissingHello) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0, 0.0);
+    EXPECT_FALSE(session.on_tick(t0 + milliseconds(19000)).hello_timeout);
+    const auto tick = session.on_tick(t0 + milliseconds(20000));
+    EXPECT_TRUE(tick.hello_timeout);
+    EXPECT_FALSE(tick.heartbeat);
+}
+
+// 场景:READY 之后普通断线(1006),重连后再次收到 Hello;以及恢复成功收到 RESUMED。
+// 期望:用 Resume(op 6)带 token、原 session_id 与最新 seq,不发 Identify(不消耗登录预算);
+// RESUMED 让连接可用且标记为恢复。
+TEST(DiscordGateway, ResumesAfterAbnormalClose) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0, 0.0);
+    session.on_frame(hello(40000), t0);
+    session.on_frame(ready(7), t0);
+    EXPECT_EQ(session.on_closed(1006).action, CloseAction::Resume);
+    EXPECT_TRUE(session.can_resume());
+    session.on_connected("tok", t0, 0.3);
+    const auto out = session.on_frame(hello(40000), t0);
+    ASSERT_EQ(out.frames.size(), 1u);
+    EXPECT_FALSE(out.identified);
+    const auto resume = parse(out.frames[0]);
+    EXPECT_EQ(resume["op"], 6);
+    EXPECT_EQ(resume["d"]["token"], "tok");
+    EXPECT_EQ(resume["d"]["session_id"], "S1");
+    EXPECT_EQ(resume["d"]["seq"], 7);
+    const auto resumed = session.on_frame(R"({"op":0,"t":"RESUMED","s":8,"d":null})", t0);
+    EXPECT_TRUE(resumed.ready);
+    EXPECT_TRUE(resumed.resumed);
+    EXPECT_FALSE(resumed.ready_info);
+}
+
+// 场景:服务端发 op 7(可能在 Hello 之前);发 op 1 要求立即心跳。
+// 期望:op 7 返回重连指令并保留会话(之后 Resume);op 1 立即回一帧心跳。
+TEST(DiscordGateway, ServerReconnectAndHeartbeatRequests) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0, 0.0);
+    const auto early = session.on_frame(R"({"op":7,"d":null})", t0);
+    EXPECT_TRUE(early.reconnect);
+    session.on_frame(hello(40000), t0);
+    session.on_frame(ready(2), t0);
+    const auto reconnect = session.on_frame(R"({"op":7,"d":null})", t0);
+    EXPECT_TRUE(reconnect.reconnect);
+    EXPECT_FALSE(reconnect.invalid_session);
+    EXPECT_TRUE(session.can_resume());
+    const auto beat = session.on_frame(R"({"op":1,"d":null})", t0);
+    ASSERT_EQ(beat.frames.size(), 1u);
+    EXPECT_EQ(parse(beat.frames[0])["op"], 1);
+    EXPECT_EQ(parse(beat.frames[0])["d"], 2);
+}
+
+// 场景:服务端发 op 9;d=true 表示还能恢复,d=false 表示会话作废(Resume 窗口过期也是这样)。
+// 期望:d=true 只要求重连、会话保留;d=false 清掉会话(含恢复地址),标记 invalid_session,
+// 下一次连接改发 Identify。
+TEST(DiscordGateway, InvalidSessionKeepsOrClearsSession) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0, 0.0);
+    session.on_frame(hello(40000), t0);
+    session.on_frame(ready(3), t0);
+    const auto resumable = session.on_frame(R"({"op":9,"d":true})", t0);
+    EXPECT_TRUE(resumable.reconnect);
+    EXPECT_FALSE(resumable.invalid_session);
+    EXPECT_TRUE(session.can_resume());
+    const auto dead = session.on_frame(R"({"op":9,"d":false})", t0);
+    EXPECT_TRUE(dead.reconnect);
+    EXPECT_TRUE(dead.invalid_session);
+    EXPECT_FALSE(session.can_resume());
+    EXPECT_TRUE(session.resume_url().empty());
+    session.on_connected("tok", t0, 0.0);
+    EXPECT_TRUE(session.on_frame(hello(40000), t0).identified);
+}
+
+// 场景:网关以各种关闭码断开。
+// 期望:4004(token 无效)与 4010–4014 是致命错误,不再重连,4014 的原因指向开启 Message Content
+// Intent;4003/4007/4009 要重新登录且清掉会话;4008 单独按频控处理;其余(1000/1001/1006/4000/
+// 4001/4002/4005 以及未知码)按普通断线恢复。
+TEST(DiscordGateway, ClassifiesCloseCodes) {
+    for (int code : {4004, 4010, 4011, 4012, 4013, 4014})
+        EXPECT_EQ(classify_close(code).action, CloseAction::Fatal) << code;
+    EXPECT_NE(classify_close(4014).reason.find("Message Content Intent"), std::string::npos);
+    EXPECT_NE(classify_close(4004).reason.find("Token"), std::string::npos);
+    for (int code : {4003, 4007, 4009})
+        EXPECT_EQ(classify_close(code).action, CloseAction::Identify) << code;
+    EXPECT_EQ(classify_close(4008).action, CloseAction::RateLimited);
+    for (int code : {1000, 1001, 1006, 4000, 4001, 4002, 4005, 4999})
+        EXPECT_EQ(classify_close(code).action, CloseAction::Resume) << code;
+
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0, 0.0);
+    session.on_frame(hello(40000), t0);
+    session.on_frame(ready(4), t0);
+    EXPECT_EQ(session.on_closed(4009).action, CloseAction::Identify);
+    EXPECT_FALSE(session.can_resume());
+}
+
+// 场景:两次 Identify 之间,以及新会话连续失败(Identify 后没等到 READY)。
+// 期望:两次 Identify 至少间隔 5 秒;失败后按 5s→10s→20s 指数退避,封顶 5 分钟;
+// 收到 READY 后清零,回到 5 秒最小间隔。
+TEST(DiscordGateway, IdentifyBudgetEnforcesIntervalAndBackoff) {
+    IdentifyBudget budget;
+    const std::int64_t t = 1'700'000'000'000;
+    EXPECT_EQ(budget.next_allowed_ms(t), t);
+    budget.record_identify(t);
+    EXPECT_EQ(budget.next_allowed_ms(t), t + 5000);
+    budget.record_failure();
+    EXPECT_EQ(budget.next_allowed_ms(t), t + 5000);
+    budget.record_failure();
+    EXPECT_EQ(budget.next_allowed_ms(t), t + 10000);
+    budget.record_failure();
+    EXPECT_EQ(budget.next_allowed_ms(t), t + 20000);
+    for (int i = 0; i < 20; ++i) budget.record_failure();
+    EXPECT_EQ(budget.next_allowed_ms(t), t + 5 * 60 * 1000);
+    budget.record_ready();
+    EXPECT_EQ(budget.next_allowed_ms(t), t + 5000);
+}
+
+// 场景:24 小时窗口内 Identify 次数达到上限(测试里上限设为 3;真实值 900,硬上限 1000,
+// 超出会被 Discord 重置 token)。
+// 期望:达到上限后暂停到窗口结束;窗口过后重新计数。
+TEST(DiscordGateway, IdentifyBudgetPausesAtDailyCap) {
+    IdentifyBudget::Limits limits;
+    limits.daily_cap = 3;
+    IdentifyBudget budget(limits, 0, 0);
+    const std::int64_t t = 1'700'000'000'000;
+    for (int i = 0; i < 3; ++i) budget.record_identify(t + i * 10000);
+    const auto now = t + 60000;
+    EXPECT_TRUE(budget.daily_cap_reached(now));
+    EXPECT_EQ(budget.next_allowed_ms(now), t + 24LL * 3600 * 1000);
+    const auto later = t + 24LL * 3600 * 1000 + 1;
+    EXPECT_FALSE(budget.daily_cap_reached(later));
+    budget.record_identify(later);
+    EXPECT_EQ(budget.count(), 1);
+    EXPECT_EQ(budget.window_start_ms(), later);
+}
+
+// 场景:进程重启,从持久化的计数恢复(窗口开始于 1 小时前,已用 900 次);
+// 另有 /gateway/bot 报告 session_start_limit.remaining=0,要求等 reset_after。
+// 期望:恢复的计数立即生效(暂停到窗口结束);block_until 的时刻同样被遵守。
+TEST(DiscordGateway, IdentifyBudgetHonoursPersistedCountAndStartLimit) {
+    const std::int64_t now = 1'700'000'000'000;
+    IdentifyBudget restored(IdentifyBudget::Limits{}, now - 3600 * 1000, 900);
+    EXPECT_TRUE(restored.daily_cap_reached(now));
+    EXPECT_EQ(restored.next_allowed_ms(now), now - 3600 * 1000 + 24LL * 3600 * 1000);
+
+    IdentifyBudget blocked;
+    blocked.block_until(now + 90000);
+    EXPECT_EQ(blocked.next_allowed_ms(now), now + 90000);
+    EXPECT_EQ(blocked.next_allowed_ms(now + 90000), now + 90000);
+}
+
+} // namespace
+} // namespace acecode::im::discord
diff --git a/tests/im/discord_protocol_test.cpp b/tests/im/discord_protocol_test.cpp
new file mode 100644
index 000000000..c2c9bb689
--- /dev/null
+++ b/tests/im/discord_protocol_test.cpp
@@ -0,0 +1,308 @@
+#include <gtest/gtest.h>
+
+#include "im/discord/discord_protocol.hpp"
+
+// im/discord/discord_protocol:MESSAGE_CREATE 解析(私信 / 服务器频道 / 点名 / 过滤)、提及处理、
+// 附件分类、错误响应解析与分类、邀请链接、Markdown 适配、URL 小工具。全部纯逻辑。
+
+namespace acecode::im::discord {
+namespace {
+
+const std::string kBot = "900000000000000001";
+const std::string kUser = "100000000000000007";
+const std::string kChannel = "500000000000000001";
+const std::string kGuild = "700000000000000001";
+
+nlohmann::json dm_message(const std::string& content) {
+    return {{"id", "600000000000000001"},
+            {"channel_id", "8" + kUser},
+            {"channel_type", 1},
+            {"type", 0},
+            {"author", {{"id", kUser}, {"username", "alice"}, {"global_name", "Alice"}}},
+            {"content", content},
+            {"mentions", nlohmann::json::array()},
+            {"attachments", nlohmann::json::array()}};
+}
+
+nlohmann::json guild_message(const std::string& content) {
+    return {{"id", "600000000000000002"},
+            {"channel_id", kChannel},
+            {"guild_id", kGuild},
+            {"channel_type", 0},
+            {"type", 0},
+            {"author", {{"id", kUser}, {"username", "bob"}, {"global_name", "Bob"}}},
+            {"member", {{"nick", "Bobby"}, {"roles", nlohmann::json::array()}}},
+            {"content", content},
+            {"mentions", nlohmann::json::array()},
+            {"mention_roles", nlohmann::json::array()},
+            {"attachments", nlohmann::json::array()}};
+}
+
+// 场景:用户私信机器人一句话(没有 guild_id,channel_type=1)。
+// 期望:私聊地址的 chat 与 sender 都是对方用户 id、account 是机器人 id;私聊恒为点名;
+// 回复上下文带消息 id 与私聊频道 id(没有 guild_id);同时给出“用户 → 私聊频道”供发送复用。
+TEST(DiscordProtocol, ParsesDirectMessage) {
+    const auto parsed = parse_message_create(dm_message("  你好  "), kBot, {});
+    ASSERT_TRUE(parsed.inbound) << parsed.drop_reason;
+    const auto& in = *parsed.inbound;
+    EXPECT_EQ(in.address.platform, "discord");
+    EXPECT_EQ(in.address.account, kBot);
+    EXPECT_EQ(in.address.kind, ChatKind::Private);
+    EXPECT_EQ(in.address.chat, kUser);
+    EXPECT_EQ(in.address.sender, kUser);
+    EXPECT_TRUE(in.mentioned);
+    EXPECT_EQ(in.text, u8"你好");
+    EXPECT_EQ(in.sender_name, "Alice");
+    EXPECT_EQ(in.reply_context.value("message_id", ""), "600000000000000001");
+    EXPECT_EQ(in.reply_context.value("channel_id", ""), "8" + kUser);
+    EXPECT_FALSE(in.reply_context.contains("guild_id"));
+    EXPECT_EQ(parsed.dm_user, kUser);
+    EXPECT_EQ(parsed.dm_channel, "8" + kUser);
+}
+
+// 场景:旧载荷没有 channel_type 字段,也没有 guild_id。
+// 期望:仍按私聊处理(以 guild_id 缺失为准)。
+TEST(DiscordProtocol, MissingChannelTypeFallsBackToGuildIdCheck) {
+    auto d = dm_message("hi");
+    d.erase("channel_type");
+    const auto parsed = parse_message_create(d, kBot, {});
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_EQ(parsed.inbound->address.kind, ChatKind::Private);
+}
+
+// 场景:服务器频道里 "<@机器人> 看看 <@!机器人> 这个 <@另一个人>",mentions 里有机器人与另一个人。
+// 期望:群地址的 chat 是频道 id、sender 是发言人;视为点名;正文去掉机器人的两种提及写法,
+// 不留双空格,其他人的提及换成 "@显示名";展示名优先用服务器昵称;回复上下文带 guild_id。
+TEST(DiscordProtocol, ParsesGuildMentionAndStripsBotTokens) {
+    auto d = guild_message("<@" + kBot + "> 看看 <@!" + kBot + "> 这个 <@200000000000000002>");
+    d["mentions"] = nlohmann::json::array(
+        {{{"id", kBot}, {"username", "AceBot"}, {"bot", true}},
+         {{"id", "200000000000000002"}, {"username", "carol"}, {"global_name", "Carol"}}});
+    const auto parsed = parse_message_create(d, kBot, {});
+    ASSERT_TRUE(parsed.inbound) << parsed.drop_reason;
+    const auto& in = *parsed.inbound;
+    EXPECT_EQ(in.address.kind, ChatKind::Group);
+    EXPECT_EQ(in.address.chat, kChannel);
+    EXPECT_EQ(in.address.sender, kUser);
+    EXPECT_TRUE(in.mentioned);
+    EXPECT_EQ(in.text, u8"看看 这个 @Carol");
+    EXPECT_EQ(in.sender_name, "Bobby");
+    EXPECT_EQ(in.reply_context.value("guild_id", ""), kGuild);
+    EXPECT_TRUE(parsed.dm_user.empty());
+}
+
+// 场景:手机端/转发的消息正文里有 <@机器人>,但 mentions 数组是空的。
+// 期望:只看正文也能认出点名(hermes 同样两处都查)。
+TEST(DiscordProtocol, InlineMentionWithoutMentionsArrayCounts) {
+    const auto parsed = parse_message_create(guild_message("<@" + kBot + "> ping"), kBot, {});
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_TRUE(parsed.inbound->mentioned);
+    EXPECT_EQ(parsed.inbound->text, "ping");
+}
+
+// 场景:服务器频道里一条没有点名机器人的普通消息。
+// 期望:照常解析,但 mentioned=false(由核心忽略,传输层不替核心做决定)。
+TEST(DiscordProtocol, GuildMessageWithoutMentionIsNotMentioned) {
+    const auto parsed = parse_message_create(guild_message("大家好"), kBot, {});
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_FALSE(parsed.inbound->mentioned);
+    EXPECT_EQ(parsed.inbound->text, u8"大家好");
+}
+
+// 场景:用户回复机器人的消息(type 19),并且关掉了回复里的 @(mentions 里没有机器人)。
+// 期望:看被回复消息的作者是机器人,算点名;被回复消息的正文作为 quote_text。
+TEST(DiscordProtocol, ReplyToBotCountsAsMention) {
+    auto d = guild_message("继续说");
+    d["type"] = 19;
+    d["message_reference"] = {{"message_id", "600000000000000000"}};
+    d["referenced_message"] = {{"id", "600000000000000000"},
+                               {"author", {{"id", kBot}, {"username", "AceBot"}, {"bot", true}}},
+                               {"content", "上一条回答"}};
+    const auto parsed = parse_message_create(d, kBot, {});
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_TRUE(parsed.inbound->mentioned);
+    EXPECT_EQ(parsed.inbound->quote_text, u8"上一条回答");
+}
+
+// 场景:用户在补全里选了机器人的托管角色,正文是 <@&角色 id>,mention_roles 里也有它。
+// 期望:已知机器人角色时算点名,角色提及从正文里去掉;mention_everyone 不算点名。
+TEST(DiscordProtocol, BotManagedRoleMentionCounts) {
+    const std::string role = "300000000000000003";
+    auto d = guild_message("<@&" + role + "> 帮忙");
+    d["mention_roles"] = nlohmann::json::array({role});
+    const auto parsed = parse_message_create(d, kBot, {role});
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_TRUE(parsed.inbound->mentioned);
+    EXPECT_EQ(parsed.inbound->text, u8"帮忙");
+
+    auto everyone = guild_message("@everyone 开会");
+    everyone["mention_everyone"] = true;
+    const auto plain = parse_message_create(everyone, kBot, {role});
+    ASSERT_TRUE(plain.inbound);
+    EXPECT_FALSE(plain.inbound->mentioned);
+}
+
+// 场景:GUILD_CREATE 的角色列表里有一个 tags.bot_id 等于机器人 id 的托管角色。
+// 期望:找出这个角色 id;其他角色不算。
+TEST(DiscordProtocol, FindsBotManagedRoleInGuildCreate) {
+    const nlohmann::json guild{{"id", kGuild},
+                               {"roles", nlohmann::json::array(
+                                             {{{"id", "300000000000000001"}, {"name", "everyone"}},
+                                              {{"id", "300000000000000003"}, {"tags", {{"bot_id", kBot}}}},
+                                              {{"id", "300000000000000004"}, {"tags", {{"bot_id", "1"}}}}})}};
+    const auto roles = bot_role_ids_in_guild(guild, kBot);
+    ASSERT_EQ(roles.size(), 1u);
+    EXPECT_EQ(roles[0], "300000000000000003");
+}
+
+// 场景:自己发出的消息回显、其他机器人、webhook、系统消息类型(置顶 6、子区首条 21)、群组私聊、
+// 只 @ 了机器人没有任何内容。
+// 期望:全部丢弃并给出原因(日志用);不会产生入站消息。
+TEST(DiscordProtocol, DropsSelfBotsSystemTypesAndBareMentions) {
+    auto self = guild_message("echo");
+    self["author"]["id"] = kBot;
+    auto bot = guild_message("hi");
+    bot["author"]["bot"] = true;
+    auto webhook = guild_message("hook");
+    webhook["webhook_id"] = "123456789012345678";
+    auto pin = guild_message("");
+    pin["type"] = 6;
+    auto starter = guild_message("thread starter");
+    starter["type"] = 21;
+    auto group_dm = dm_message("hi");
+    group_dm["channel_type"] = 3;
+    const auto bare = guild_message("<@" + kBot + ">");
+    for (const auto& d : {self, bot, webhook, pin, starter, group_dm, bare}) {
+        const auto parsed = parse_message_create(d, kBot, {});
+        EXPECT_FALSE(parsed.inbound) << d.dump();
+        EXPECT_FALSE(parsed.drop_reason.empty());
+    }
+}
+
+// 场景:消息带三个附件(带 charset 的文本、图片、视频),另一条是语音消息(flags 含 1<<13)。
+// 期望:mime 去掉参数并转小写;按前缀分为文件 / 图片 / 视频;语音消息的附件标为语音;
+// remote_ref 是 CDN 地址、size 原样带上;只有附件没有正文也算有效消息。
+TEST(DiscordProtocol, ClassifiesAttachments) {
+    auto d = dm_message("");
+    d["attachments"] = nlohmann::json::array(
+        {{{"id", "1"}, {"filename", "log.txt"}, {"size", 1234}, {"content_type", "Text/Plain; charset=utf-8"},
+          {"url", "https://cdn.discordapp.com/attachments/5/1/log.txt?ex=a&is=b&hm=c&"}},
+         {{"id", "2"}, {"filename", "a.png"}, {"size", 10}, {"content_type", "image/png"}, {"url", "https://cdn/x/a.png"}},
+         {{"id", "3"}, {"filename", "v.mp4"}, {"size", 10}, {"content_type", "video/mp4"}, {"url", "https://cdn/x/v.mp4"}}});
+    const auto parsed = parse_message_create(d, kBot, {});
+    ASSERT_TRUE(parsed.inbound);
+    const auto& list = parsed.inbound->attachments;
+    ASSERT_EQ(list.size(), 3u);
+    EXPECT_EQ(list[0].kind, AttachmentKind::File);
+    EXPECT_EQ(list[0].mime_type, "text/plain");
+    EXPECT_EQ(list[0].size, 1234u);
+    EXPECT_EQ(list[0].name, "log.txt");
+    EXPECT_EQ(list[0].remote_ref, "https://cdn.discordapp.com/attachments/5/1/log.txt?ex=a&is=b&hm=c&");
+    EXPECT_EQ(list[1].kind, AttachmentKind::Image);
+    EXPECT_EQ(list[2].kind, AttachmentKind::Video);
+
+    auto voice = dm_message("");
+    voice["flags"] = 1 << 13;
+    voice["attachments"] = nlohmann::json::array(
+        {{{"id", "4"}, {"filename", "voice-message.ogg"}, {"content_type", "audio/ogg"}, {"url", "https://cdn/v.ogg"}}});
+    const auto voiced = parse_message_create(voice, kBot, {});
+    ASSERT_TRUE(voiced.inbound);
+    EXPECT_EQ(voiced.inbound->attachments.at(0).kind, AttachmentKind::Voice);
+}
+
+// 场景:用户转发了一条带文件的消息:外层正文为空,内容在 message_snapshots[0].message 里。
+// 期望:用快照的正文作为 text,快照的附件也收进来。
+TEST(DiscordProtocol, UsesForwardedSnapshotContent) {
+    auto d = dm_message("");
+    d["message_snapshots"] = nlohmann::json::array(
+        {{{"message", {{"content", "转发的内容"},
+                       {"attachments", nlohmann::json::array({{{"id", "9"}, {"filename", "f.pdf"},
+                                                               {"content_type", "application/pdf"},
+                                                               {"url", "https://cdn/f.pdf"}}})}}}}});
+    const auto parsed = parse_message_create(d, kBot, {});
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_EQ(parsed.inbound->text, u8"转发的内容");
+    ASSERT_EQ(parsed.inbound->attachments.size(), 1u);
+    EXPECT_EQ(parsed.inbound->attachments[0].name, "f.pdf");
+}
+
+// 场景:发消息失败的几种响应体:回复定位字段校验失败(50035 嵌套 errors)、被回复消息不存在(10008)、
+// 没有读历史权限(160002)、缺权限(50013)、429 限流体、413 / 40005 文件过大、非 JSON 的 502。
+// 期望:50035 的 detail 带出字段路径与原因;前三种判定为“去掉回复定位重发即可”,50013 不是;
+// 429 读出小数秒 retry_after 与 global;过大判定正确;非 JSON 用 "HTTP 状态码" 兜底;
+// 给用户的中文原因能区分私信被拒与缺权限。
+TEST(DiscordProtocol, ParsesAndClassifiesApiErrors) {
+    const auto form = parse_api_error(
+        400, R"({"code":50035,"message":"Invalid Form Body","errors":{"message_reference":{"_errors":[{"code":"MESSAGE_REFERENCE_UNKNOWN_MESSAGE","message":"Unknown message"}]}}})");
+    EXPECT_EQ(form.code, 50035);
+    EXPECT_NE(form.detail.find("message_reference: Unknown message"), std::string::npos) << form.detail;
+    EXPECT_TRUE(reference_rejected(form));
+    EXPECT_TRUE(reference_rejected(parse_api_error(404, R"({"code":10008,"message":"Unknown Message"})")));
+    EXPECT_TRUE(reference_rejected(parse_api_error(403, R"({"code":160002,"message":"Cannot reply without permission to read message history"})")));
+    const auto perms = parse_api_error(403, R"({"code":50013,"message":"Missing Permissions"})");
+    EXPECT_FALSE(reference_rejected(perms));
+    EXPECT_NE(describe_error(perms).find(u8"权限"), std::string::npos);
+    EXPECT_NE(describe_error(parse_api_error(403, R"({"code":50007,"message":"Cannot send messages to this user"})")).find(u8"私信"),
+              std::string::npos);
+
+    const auto limited = parse_api_error(429, R"({"message":"You are being rate limited.","retry_after":64.57,"global":true,"code":20028})");
+    EXPECT_DOUBLE_EQ(limited.retry_after, 64.57);
+    EXPECT_TRUE(limited.global);
+
+    EXPECT_TRUE(upload_too_large(parse_api_error(413, "")));
+    EXPECT_TRUE(upload_too_large(parse_api_error(400, R"({"code":40005,"message":"Request entity too large"})")));
+    const auto html = parse_api_error(502, "<html>bad gateway</html>");
+    EXPECT_EQ(html.code, 0);
+    EXPECT_EQ(html.message, "HTTP 502");
+}
+
+// 场景:由应用 id 生成邀请链接;由 /applications/@me 的 flags 判断 Message Content Intent。
+// 期望:链接 scope=bot、权限值 274878008320(查看频道 + 发送消息 + 附加文件 + 读历史 + 子区发送);
+// 空 id 不生成链接;1<<18 或 1<<19 任一置位即已开启,都没有为未开启,没有 flags 为未知。
+TEST(DiscordProtocol, BuildsInviteUrlAndReadsIntentFlags) {
+    EXPECT_EQ(invite_url("900000000000000001"),
+              "https://discord.com/oauth2/authorize?client_id=900000000000000001&scope=bot"
+              "&permissions=274878008320&integration_type=0");
+    EXPECT_TRUE(invite_url("").empty());
+    EXPECT_EQ(message_content_intent({{"flags", 1 << 18}}), IntentState::Enabled);
+    EXPECT_EQ(message_content_intent({{"flags", (1 << 19) | 1}}), IntentState::Enabled);
+    EXPECT_EQ(message_content_intent({{"flags", 0}}), IntentState::Disabled);
+    EXPECT_EQ(message_content_intent(nlohmann::json::object()), IntentState::Unknown);
+}
+
+// 场景:/gateway/bot 给出的地址可能带或不带结尾斜杠,恢复地址同理。
+// 期望:统一拼成 "<地址>/?v=10&encoding=json"(不带 compress);原有查询串被替换。
+TEST(DiscordProtocol, BuildsGatewayConnectUrl) {
+    EXPECT_EQ(gateway_connect_url("wss://gateway.discord.gg"), "wss://gateway.discord.gg/?v=10&encoding=json");
+    EXPECT_EQ(gateway_connect_url("wss://gateway-us-east1-b.discord.gg/"),
+              "wss://gateway-us-east1-b.discord.gg/?v=10&encoding=json");
+    EXPECT_EQ(gateway_connect_url("wss://gateway.discord.gg/?v=9"), "wss://gateway.discord.gg/?v=10&encoding=json");
+    EXPECT_TRUE(gateway_connect_url("").empty());
+}
+
+// 场景:助手回复里有 GFM 表格、四级标题,以及代码块里长得像表格/标题的内容。
+// 期望:表格整体包进 ``` 代码块(Discord 不渲染表格);#### 标题改成粗体;代码块内原样保留;
+// 普通 ### 标题(Discord 支持)不动。
+TEST(DiscordProtocol, FormatsTablesAndDeepHeadings) {
+    const std::string input = "### 结果\n| 名称 | 值 |\n|---|---|\n| a | 1 |\n\n#### 细节\n```\n| x | y |\n|---|---|\n#### keep\n```";
+    const std::string expected = "### 结果\n```\n| 名称 | 值 |\n|---|---|\n| a | 1 |\n```\n\n**细节**\n```\n| x | y |\n|---|---|\n#### keep\n```";
+    EXPECT_EQ(format_markdown(input), expected);
+    EXPECT_EQ(format_markdown("普通 **文字** a|b"), "普通 **文字** a|b");
+}
+
+// 场景:取附件地址的主机名与附件 id;User-Agent 的格式。
+// 期望:主机名小写、去掉端口与用户信息;从 /attachments/<频道>/<附件>/ 取出附件 id;
+// UA 形如 "DiscordBot (<项目地址>, <版本>)"(Discord 要求的格式)。
+TEST(DiscordProtocol, UrlHelpersAndUserAgent) {
+    EXPECT_EQ(url_host("https://CDN.DiscordApp.com/attachments/1/2/a.txt?ex=1"), "cdn.discordapp.com");
+    EXPECT_EQ(url_host("http://user@127.0.0.1:8080/x"), "127.0.0.1");
+    EXPECT_EQ(url_host("not a url"), "");
+    EXPECT_EQ(attachment_id_from_url("https://cdn.discordapp.com/attachments/500/1290000000000000099/log.txt?ex=1"),
+              "1290000000000000099");
+    EXPECT_EQ(attachment_id_from_url("https://example.com/files/1/2"), "");
+    EXPECT_EQ(discord_user_agent().rfind("DiscordBot (https://github.com/tmoonlight/acecode, ", 0), 0u);
+    EXPECT_EQ(discord_user_agent().back(), ')');
+}
+
+} // namespace
+} // namespace acecode::im::discord
diff --git a/tests/im/discord_transport_test.cpp b/tests/im/discord_transport_test.cpp
new file mode 100644
index 000000000..f191a50ac
--- /dev/null
+++ b/tests/im/discord_transport_test.cpp
@@ -0,0 +1,564 @@
+#include <gtest/gtest.h>
+
+#include "im/discord/discord_transport.hpp"
+#include "test_support/im/fake_discord_server.hpp"
+
+#include <algorithm>
+#include <atomic>
+#include <fstream>
+#include <mutex>
+#include <thread>
+#include <vector>
+
+// im/discord/discord_transport:Discord 传输层端到端测试(本机假 Discord,不连真实平台)。
+// 覆盖:网关登录与状态、私信与服务器频道 @ / 回复机器人 / 过滤与去重、回复定位与分段、
+// 回复目标失效的回退、429 等待重发、无回复上下文时打开私聊频道、断线 Resume、op 7 / op 9、
+// Resume 被拒后重新登录、致命关闭码(4014)、token 无效、心跳假死、正在输入、文件收发、停机及时。
+
+namespace acecode::im::discord {
+namespace {
+
+using test::FakeDiscordServer;
+using std::chrono::milliseconds;
+
+const std::string kUser = "100000000000000007";
+const std::string kChannel = "500000000000000001";
+
+DiscordTransportOptions local_options(const FakeDiscordServer& server) {
+    DiscordTransportOptions options;
+    options.api.token = server.token;
+    options.api.api_base = server.api_base();
+    options.api.use_proxy = false;
+    options.rate_limit.send_retry_delay = milliseconds(10);
+    options.backoff = {milliseconds(50)};
+    options.rate_limit_close_delay = milliseconds(100);
+    options.invalid_session_delay_min = milliseconds(10);
+    options.invalid_session_delay_max = milliseconds(20);
+    options.typing_interval = milliseconds(100);
+    options.receive_slice = milliseconds(50);
+    options.identify_limits.min_interval = milliseconds(10);
+    options.download_hosts = {"127.0.0.1"};
+    return options;
+}
+
+struct Recorder {
+    std::mutex mu;
+    std::vector<Inbound> inbound;
+    TransportCallbacks callbacks() {
+        TransportCallbacks cb;
+        cb.on_inbound = [this](Inbound in) {
+            std::lock_guard<std::mutex> lock(mu);
+            inbound.push_back(std::move(in));
+        };
+        return cb;
+    }
+    std::size_t count() {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.size();
+    }
+    Inbound at(std::size_t i) {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.at(i);
+    }
+};
+
+bool wait_state(DiscordTransport& transport, LinkState state) {
+    return FakeDiscordServer::wait_until([&transport, state] { return transport.status().state == state; });
+}
+
+std::string dm_channel() { return FakeDiscordServer::dm_channel_for(kUser); }
+
+// 连上网关并收一条私信,返回这条入站消息(用于后续发送测试)。
+Inbound connect_and_receive_dm(FakeDiscordServer& server, DiscordTransport& transport, Recorder& recorder) {
+    transport.start(recorder.callbacks());
+    EXPECT_TRUE(wait_state(transport, LinkState::Connected));
+    server.push_dm("600000000000000001", kUser, "hello");
+    EXPECT_TRUE(FakeDiscordServer::wait_until([&recorder] { return recorder.count() >= 1; }));
+    return recorder.at(0);
+}
+
+Address dm_address(const FakeDiscordServer& server, const std::string& user) {
+    Address to;
+    to.platform = "discord";
+    to.account = server.bot_id;
+    to.kind = ChatKind::Private;
+    to.chat = to.sender = user;
+    return to;
+}
+
+bool contains_code(const std::vector<int>& codes, int code) {
+    return std::find(codes.begin(), codes.end(), code) != codes.end();
+}
+
+// 场景:开启 Discord 通道,网关握手(Hello → Identify → READY)后用户私信机器人。
+// 期望:状态变为已连接,account 是机器人用户 id、显示名是机器人用户名、附带邀请链接;
+// Identify 用原始 token 与 intents 37377;登录次数通过回调交给调用方持久化;
+// 入站私信的地址 chat = sender = 用户 id,视为点名,回复上下文带私聊频道 id;停止后状态为已停止。
+TEST(DiscordTransport, ConnectsIdentifiesAndReceivesDirectMessage) {
+    FakeDiscordServer server;
+    auto options = local_options(server);
+    std::atomic<std::int64_t> ledger{0};
+    options.on_identify_ledger = [&ledger](std::int64_t, std::int64_t count) { ledger = count; };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    const auto status = transport.status();
+    EXPECT_EQ(status.account, server.bot_id);
+    EXPECT_EQ(status.display_name, "AceBot");
+    EXPECT_NE(status.extra.value("invite_url", "").find("client_id=" + server.application_id), std::string::npos);
+    EXPECT_EQ(transport.bot_user_id(), server.bot_id);
+    const auto identifies = server.frames_with_op(2);
+    ASSERT_EQ(identifies.size(), 1u);
+    EXPECT_EQ(identifies[0]["d"]["token"], server.token);
+    EXPECT_EQ(identifies[0]["d"]["intents"], 37377);
+    EXPECT_EQ(ledger.load(), 1);
+    const auto gateway = server.requests_to("GET", "/gateway/bot");
+    ASSERT_EQ(gateway.size(), 1u);
+    EXPECT_EQ(gateway[0].authorization, "Bot " + server.token);
+
+    server.push_dm("600000000000000001", kUser, u8" 你好 ");
+    ASSERT_TRUE(FakeDiscordServer::wait_until([&recorder] { return recorder.count() == 1; }));
+    const auto in = recorder.at(0);
+    EXPECT_EQ(in.address.platform, "discord");
+    EXPECT_EQ(in.address.account, server.bot_id);
+    EXPECT_EQ(in.address.kind, ChatKind::Private);
+    EXPECT_EQ(in.address.chat, kUser);
+    EXPECT_EQ(in.address.sender, kUser);
+    EXPECT_TRUE(in.mentioned);
+    EXPECT_EQ(in.text, u8"你好");
+    EXPECT_EQ(in.sender_name, "Alice");
+    EXPECT_EQ(in.reply_context.value("channel_id", ""), dm_channel());
+    transport.stop();
+    EXPECT_EQ(transport.status().state, LinkState::Stopped);
+}
+
+// 场景:服务器频道里依次出现:@机器人 的消息、普通闲聊、回复机器人的消息、别的机器人发言、
+// 机器人自己消息的回显,以及第一条消息被重复推送(Resume 补发时常见)。
+// 期望:上层只收到三条:@ 的那条(点名、去掉提及)、闲聊(未点名,交给核心忽略)、回复机器人
+// (点名,带被回复内容);机器人消息、自己的回显和重复消息都不上报。
+TEST(DiscordTransport, GuildMentionsRepliesAndFilters) {
+    FakeDiscordServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    const auto bot = server.bot_id;
+    const nlohmann::json mention{{"mentions", nlohmann::json::array({{{"id", bot}, {"username", "AceBot"}, {"bot", true}}})}};
+    server.push_guild("600000000000000011", kChannel, kUser, "<@" + bot + u8"> 看看这个", mention);
+    server.push_guild("600000000000000012", kChannel, kUser, u8"随便聊聊");
+    server.push_guild("600000000000000013", kChannel, kUser, u8"继续",
+                      {{"type", 19},
+                       {"referenced_message",
+                        {{"id", "600000000000000010"}, {"author", {{"id", bot}, {"bot", true}}}, {"content", u8"之前的回答"}}}});
+    server.push_guild("600000000000000014", kChannel, "200000000000000009", u8"我是别的机器人",
+                      {{"author", {{"id", "200000000000000009"}, {"username", "other"}, {"bot", true}}}});
+    server.push_guild("600000000000000015", kChannel, bot, u8"自己发的",
+                      {{"author", {{"id", bot}, {"username", "AceBot"}, {"bot", true}}}});
+    server.push_guild("600000000000000011", kChannel, kUser, "<@" + bot + u8"> 看看这个", mention);
+    ASSERT_TRUE(FakeDiscordServer::wait_until([&recorder] { return recorder.count() == 3; }));
+    std::this_thread::sleep_for(milliseconds(200));
+    ASSERT_EQ(recorder.count(), 3u);
+    const auto first = recorder.at(0);
+    EXPECT_EQ(first.address.kind, ChatKind::Group);
+    EXPECT_EQ(first.address.chat, kChannel);
+    EXPECT_EQ(first.address.sender, kUser);
+    EXPECT_TRUE(first.mentioned);
+    EXPECT_EQ(first.text, u8"看看这个");
+    EXPECT_FALSE(recorder.at(1).mentioned);
+    const auto reply = recorder.at(2);
+    EXPECT_TRUE(reply.mentioned);
+    EXPECT_EQ(reply.quote_text, u8"之前的回答");
+}
+
+// 场景:收到私信后回复一段约 4500 字符、三个段落的长文本。
+// 期望:按段落切成三条(每条不超过 2000);只有第一条带 message_reference(fail_if_not_exists=false)
+// 指向触发消息;每条都带 allowed_mentions 且只允许提及用户(不会 @everyone / 角色);带 nonce 幂等键。
+TEST(DiscordTransport, RepliesWithReferenceAndSafeMentionsInChunks) {
+    FakeDiscordServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(local_options(server));
+    const auto in = connect_and_receive_dm(server, transport, recorder);
+    const auto text = std::string(1500, 'a') + "\n\n" + std::string(1500, 'b') + "\n\n" + std::string(1500, 'c');
+    const auto result = transport.send_text(in.address, text, in.reply_context);
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto sent = server.requests_to("POST", "/channels/" + dm_channel() + "/messages");
+    ASSERT_EQ(sent.size(), 3u);
+    ASSERT_TRUE(sent[0].body.contains("message_reference"));
+    EXPECT_EQ(sent[0].body["message_reference"].value("message_id", ""), in.message_id);
+    EXPECT_FALSE(sent[0].body["message_reference"].value("fail_if_not_exists", true));
+    EXPECT_FALSE(sent[1].body.contains("message_reference"));
+    EXPECT_FALSE(sent[2].body.contains("message_reference"));
+    for (const auto& request : sent) {
+        EXPECT_LE(request.body.value("content", "").size(), 2000u);
+        EXPECT_EQ(request.body["allowed_mentions"]["parse"], nlohmann::json::array({"users"}));
+        EXPECT_FALSE(request.body.value("nonce", "").empty());
+    }
+    EXPECT_EQ(sent[1].body.value("content", ""), std::string(1500, 'b'));
+}
+
+// 场景:被回复的那条消息已被删除,平台对带 message_reference 的请求返回 10008。
+// 期望:去掉回复定位后重发同一段内容并成功;平台共收到两次请求。
+TEST(DiscordTransport, ResendsWithoutReferenceWhenReplyTargetIsGone) {
+    FakeDiscordServer server;
+    server.message_handler = [](const FakeDiscordServer::Request& r) {
+        if (r.body.contains("message_reference"))
+            return std::make_pair(404, nlohmann::json{{"code", 10008}, {"message", "Unknown Message"}});
+        return std::make_pair(0, nlohmann::json());
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(local_options(server));
+    const auto in = connect_and_receive_dm(server, transport, recorder);
+    const auto result = transport.send_text(in.address, "reply", in.reply_context);
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto sent = server.requests_to("POST", "/channels/" + dm_channel() + "/messages");
+    ASSERT_EQ(sent.size(), 2u);
+    EXPECT_TRUE(sent[0].body.contains("message_reference"));
+    EXPECT_FALSE(sent[1].body.contains("message_reference"));
+    EXPECT_EQ(sent[1].body.value("content", ""), "reply");
+}
+
+// 场景:连续发两条消息,第一条先被 429(retry_after=0.1 秒)拒收。
+// 期望:等待后重发,两条都送达,且平台看到的顺序仍是“第一条、第二条”(不丢、不乱序)。
+TEST(DiscordTransport, WaitsAndResendsAfterRateLimitInOrder) {
+    FakeDiscordServer server;
+    std::atomic<int> calls{0};
+    server.message_handler = [&calls](const FakeDiscordServer::Request&) {
+        if (calls++ == 0)
+            return std::make_pair(429, nlohmann::json{{"message", "You are being rate limited."},
+                                                      {"retry_after", 0.1}, {"global", false}, {"code", 20028}});
+        return std::make_pair(0, nlohmann::json());
+    };
+    DiscordTransport transport(local_options(server));
+    const auto to = dm_address(server, kUser);
+    const nlohmann::json context{{"message_id", "600000000000000001"}, {"channel_id", dm_channel()}};
+    EXPECT_EQ(transport.send_text(to, u8"第一条", context).outcome, SendOutcome::Sent);
+    EXPECT_EQ(transport.send_text(to, u8"第二条", context).outcome, SendOutcome::Sent);
+    const auto sent = server.requests_to("POST", "/channels/" + dm_channel() + "/messages");
+    ASSERT_EQ(sent.size(), 3u);
+    EXPECT_EQ(sent[0].body.value("content", ""), u8"第一条");
+    EXPECT_EQ(sent[1].body.value("content", ""), u8"第一条");
+    EXPECT_EQ(sent[2].body.value("content", ""), u8"第二条");
+}
+
+// 场景:没有回复上下文的私聊发送(Desktop 里输入的回复、核心给机主发绑定码),且本进程还没收过
+// 这个用户的私信;连续发两条。
+// 期望:先 POST /users/@me/channels 打开私聊频道(只打开一次,之后复用),再往该频道发消息;
+// 不带 message_reference;网关没连上也能发(REST 与网关无关)。
+TEST(DiscordTransport, OpensDirectMessageChannelWithoutReplyContext) {
+    FakeDiscordServer server;
+    DiscordTransport transport(local_options(server));
+    const std::string user = "100000000000000042";
+    const auto to = dm_address(server, user);
+    EXPECT_EQ(transport.send_text(to, u8"绑定码:123456", nlohmann::json::object()).outcome, SendOutcome::Sent);
+    EXPECT_EQ(transport.send_text(to, u8"第二条", nlohmann::json::object()).outcome, SendOutcome::Sent);
+    const auto opens = server.requests_to("POST", "/users/@me/channels");
+    ASSERT_EQ(opens.size(), 1u);
+    EXPECT_EQ(opens[0].body.value("recipient_id", ""), user);
+    const auto sent = server.requests_to("POST", "/channels/" + FakeDiscordServer::dm_channel_for(user) + "/messages");
+    ASSERT_EQ(sent.size(), 2u);
+    EXPECT_FALSE(sent[0].body.contains("message_reference"));
+}
+
+// 场景:连接期间网关以 4000(未知错误,可恢复)断开。
+// 期望:重连到 READY 给出的恢复地址(/resume/),用 Resume 带原 session_id 与断开前最后的 seq,
+// 不重新 Identify(不消耗登录预算),最终回到已连接。
+TEST(DiscordTransport, ResumesAfterRecoverableClose) {
+    FakeDiscordServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(local_options(server));
+    connect_and_receive_dm(server, transport, recorder);
+    const auto seq_before = server.last_seq();
+    server.close_connection(4000, "unknown error");
+    ASSERT_TRUE(FakeDiscordServer::wait_until([&server] { return server.connections("resume") == 1; }));
+    ASSERT_TRUE(FakeDiscordServer::wait_until([&server, &transport] {
+        return !server.frames_with_op(6).empty() && transport.status().state == LinkState::Connected;
+    }));
+    const auto resume = server.frames_with_op(6).front();
+    EXPECT_EQ(resume["d"]["session_id"], "S1");
+    EXPECT_EQ(resume["d"]["seq"], seq_before);
+    EXPECT_EQ(resume["d"]["token"], server.token);
+    EXPECT_EQ(server.identify_count(), 1);
+}
+
+// 场景:网关发来 op 7(要求重连)。
+// 期望:客户端以非 1000 关闭码断开(1000 会让会话作废),连到恢复地址并 Resume,不重新登录。
+TEST(DiscordTransport, ServerReconnectRequestResumes) {
+    FakeDiscordServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    server.push({{"op", 7}, {"d", nullptr}});
+    ASSERT_TRUE(FakeDiscordServer::wait_until([&server] { return !server.frames_with_op(6).empty(); }));
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    EXPECT_EQ(server.connections("resume"), 1);
+    EXPECT_EQ(server.identify_count(), 1);
+    EXPECT_FALSE(contains_code(server.client_close_codes(), 1000));
+}
+
+// 场景:网关发来 op 9(d=false,会话作废)。
+// 期望:随机等待一小会儿后连回 /gateway/bot 给出的地址重新 Identify(第二次登录),回到已连接;
+// 不去恢复地址。
+TEST(DiscordTransport, InvalidSessionTriggersFreshIdentify) {
+    FakeDiscordServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    server.push({{"op", 9}, {"d", false}});
+    ASSERT_TRUE(FakeDiscordServer::wait_until([&server] { return server.identify_count() == 2; }));
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    EXPECT_EQ(server.connections("gateway"), 2);
+    EXPECT_EQ(server.connections("resume"), 0);
+}
+
+// 场景:断线后尝试 Resume,但会话已过期,网关回 op 9(d=false)。
+// 期望:放弃恢复,回到 /gateway/bot 的地址重新 Identify,最终回到已连接。
+TEST(DiscordTransport, RejectedResumeFallsBackToIdentify) {
+    FakeDiscordServer server;
+    server.resume_ok = false;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    server.close_connection(4000, "unknown error");
+    ASSERT_TRUE(FakeDiscordServer::wait_until([&server] { return server.identify_count() == 2; }));
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    EXPECT_EQ(server.connections("resume"), 1);
+    EXPECT_EQ(server.frames_with_op(6).size(), 1u);
+}
+
+// 场景:开发者后台没有开启 Message Content Intent,网关在 Identify 后以 4014 关闭。
+// 期望:状态变为失败并停止重试(不会反复登录消耗预算),原因提示去开启 Message Content Intent。
+TEST(DiscordTransport, DisallowedIntentIsFatal) {
+    FakeDiscordServer server;
+    server.identify_close_code = 4014;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Failed));
+    const auto status = transport.status();
+    EXPECT_TRUE(status.retry_stopped);
+    EXPECT_NE(status.detail.find("Message Content Intent"), std::string::npos) << status.detail;
+    std::this_thread::sleep_for(milliseconds(300));
+    EXPECT_EQ(server.connections("gateway"), 1);
+    EXPECT_EQ(server.identify_count(), 1);
+}
+
+// 场景:token 已被重置,GET /gateway/bot 返回 401。
+// 期望:不去连网关,状态直接变为失败且停止重试;状态文字里没有 token。
+TEST(DiscordTransport, InvalidTokenStopsBeforeConnecting) {
+    FakeDiscordServer server;
+    auto options = local_options(server);
+    options.api.token = "OTk5OTk5.wrong.token-that-must-not-appear";
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Failed));
+    const auto status = transport.status();
+    EXPECT_TRUE(status.retry_stopped);
+    EXPECT_EQ(status.detail.find("token-that-must-not-appear"), std::string::npos);
+    std::this_thread::sleep_for(milliseconds(200));
+    EXPECT_EQ(server.connections("gateway"), 0);
+    EXPECT_EQ(server.requests_to("GET", "/gateway/bot").size(), 1u);
+}
+
+// 场景:网关不再回心跳 ACK(连接假死;心跳间隔调成 150 毫秒)。
+// 期望:下一拍到期时客户端主动断开(不用 1000)并 Resume,不重新登录;恢复 ACK 后回到已连接。
+TEST(DiscordTransport, ZombieConnectionIsClosedAndResumed) {
+    FakeDiscordServer server;
+    server.heartbeat_interval_ms = 150;
+    server.ack_heartbeats = false;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(FakeDiscordServer::wait_until([&server] { return server.connections("resume") >= 1; }));
+    server.ack_heartbeats = true;
+    ASSERT_TRUE(FakeDiscordServer::wait_until([&server] { return !server.frames_with_op(6).empty(); }));
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    EXPECT_EQ(server.identify_count(), 1);
+    EXPECT_FALSE(contains_code(server.client_close_codes(), 1000));
+}
+
+// 场景:回合进行中打开“正在输入”,一段时间后关闭(测试里间隔调成 100 毫秒;真实为 8 秒,
+// 因为指示器 10 秒后自动消失)。
+// 期望:打开期间持续向私聊频道 POST /typing;关闭后不再发送。
+TEST(DiscordTransport, TypingIndicatorRepeatsUntilTurnedOff) {
+    FakeDiscordServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(local_options(server));
+    const auto in = connect_and_receive_dm(server, transport, recorder);
+    EXPECT_TRUE(transport.capabilities().supports_typing);
+    const auto path = "/channels/" + dm_channel() + "/typing";
+    transport.set_typing(in.address, true);
+    ASSERT_TRUE(FakeDiscordServer::wait_until([&server, &path] { return server.requests_to("POST", path).size() >= 3; }));
+    transport.set_typing(in.address, false);
+    std::this_thread::sleep_for(milliseconds(150));
+    const auto settled = server.requests_to("POST", path).size();
+    std::this_thread::sleep_for(milliseconds(350));
+    EXPECT_EQ(server.requests_to("POST", path).size(), settled);
+}
+
+// 场景:回传一个文件名含中文的文件,带回复上下文。
+// 期望:multipart 只有 payload_json 与 files[0] 两个字段;payload_json 的 attachments[0] 用原始
+// 文件名(对方看到的名字)、id 为 0,并带回复定位;文件内容原样上传;结果为已发送。
+TEST(DiscordTransport, SendsFileAsMultipartWithPayloadJson) {
+    FakeDiscordServer server;
+    DiscordTransport transport(local_options(server));
+    const auto to = dm_address(server, kUser);
+    const nlohmann::json context{{"message_id", "600000000000000001"}, {"channel_id", dm_channel()}};
+    const auto file = std::filesystem::path(testing::TempDir()) / "acecode-discord-report.pdf";
+    { std::ofstream(file, std::ios::binary) << "PDF-DATA"; }
+    const auto result = transport.send_file(to, file, u8"报告.pdf", "application/pdf", context);
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto sent = server.requests_to("POST", "/channels/" + dm_channel() + "/messages");
+    ASSERT_EQ(sent.size(), 1u);
+    EXPECT_EQ(sent[0].part_names, (std::vector<std::string>{"payload_json", "files[0]"}));
+    EXPECT_EQ(sent[0].body["attachments"][0].value("filename", ""), u8"报告.pdf");
+    EXPECT_EQ(sent[0].body["attachments"][0]["id"], 0);
+    EXPECT_EQ(sent[0].body["message_reference"].value("message_id", ""), "600000000000000001");
+    EXPECT_EQ(sent[0].file_body, "PDF-DATA");
+    std::filesystem::remove(file);
+}
+
+// 场景:上传请求返回 200,但消息里的 attachments 是空的(hermes 记录过的平台偶发问题)。
+// 期望:不当作成功,返回失败并提示没有收到文件。
+TEST(DiscordTransport, UploadWithoutAttachmentsInResponseFails) {
+    FakeDiscordServer server;
+    server.message_handler = [](const FakeDiscordServer::Request& r) {
+        if (!r.file_name.empty())
+            return std::make_pair(200, nlohmann::json{{"id", "990000000000000001"}, {"attachments", nlohmann::json::array()}});
+        return std::make_pair(0, nlohmann::json());
+    };
+    DiscordTransport transport(local_options(server));
+    const auto file = std::filesystem::path(testing::TempDir()) / "acecode-discord-empty.txt";
+    { std::ofstream(file, std::ios::binary) << "data"; }
+    const auto result = transport.send_file(dm_address(server, kUser), file, "a.txt", "text/plain", nlohmann::json::object());
+    EXPECT_EQ(result.outcome, SendOutcome::Failed);
+    EXPECT_NE(result.error.find(u8"没有收到文件"), std::string::npos) << result.error;
+    std::filesystem::remove(file);
+}
+
+// 场景:文件超过本地上传上限(测试里调到 4 字节);以及没超本地上限但平台返回 413 / 40005
+// (服务器的实际上限更低)。
+// 期望:两种情况都改发一条带文件名的文字说明,结果为已发送;前者根本不上传。
+TEST(DiscordTransport, OversizedFileBecomesTextNotice) {
+    FakeDiscordServer server;
+    std::atomic<int> uploads{0};
+    server.message_handler = [&uploads](const FakeDiscordServer::Request& r) {
+        if (!r.file_name.empty()) {
+            ++uploads;
+            return std::make_pair(413, nlohmann::json{{"code", 40005}, {"message", "Request entity too large"}});
+        }
+        return std::make_pair(0, nlohmann::json());
+    };
+    const auto file = std::filesystem::path(testing::TempDir()) / "acecode-discord-big.pdf";
+    { std::ofstream(file, std::ios::binary) << "PDF-DATA"; }
+    const auto to = dm_address(server, kUser);
+    {
+        auto options = local_options(server);
+        options.max_upload_bytes = 4;
+        DiscordTransport transport(options);
+        EXPECT_EQ(transport.send_file(to, file, "big.pdf", "application/pdf", {}).outcome, SendOutcome::Sent);
+        EXPECT_EQ(uploads.load(), 0);
+    }
+    {
+        DiscordTransport transport(local_options(server));
+        EXPECT_EQ(transport.send_file(to, file, "big.pdf", "application/pdf", {}).outcome, SendOutcome::Sent);
+        EXPECT_EQ(uploads.load(), 1);
+    }
+    const auto sent = server.requests_to("POST", "/channels/" + dm_channel() + "/messages");
+    std::size_t notices = 0;
+    for (const auto& r : sent)
+        if (r.file_name.empty() && r.body.value("content", "").find("big.pdf") != std::string::npos) ++notices;
+    EXPECT_EQ(notices, 2u);
+    std::filesystem::remove(file);
+}
+
+// 场景:下载入站附件(CDN 签名地址),以及一个超过下载上限的附件(测试里上限 1024 字节)。
+// 期望:前者下载成功、请求里不带 bot token(签名地址自带授权,token 不能发给 CDN);
+// 后者失败,原因是超过大小限制,不留下半截文件。
+TEST(DiscordTransport, DownloadsAttachmentWithoutBotToken) {
+    FakeDiscordServer server;
+    auto options = local_options(server);
+    options.max_download_bytes = 1024;
+    DiscordTransport transport(options);
+    Attachment small;
+    small.remote_ref = server.cdn_url(kChannel, "1290000000000000099", "notes.txt");
+    const auto dest = std::filesystem::path(testing::TempDir()) / "acecode-discord-notes.txt";
+    std::string error;
+    ASSERT_TRUE(transport.download(small, dest, &error)) << error;
+    EXPECT_EQ(std::filesystem::file_size(dest), 32u);
+    const auto cdn = server.requests_to("GET", "/cdn/attachments/");
+    ASSERT_EQ(cdn.size(), 1u);
+    EXPECT_TRUE(cdn[0].authorization.empty());
+    std::filesystem::remove(dest);
+
+    Attachment big;
+    big.remote_ref = server.cdn_url(kChannel, "1290000000000000098", "big.bin");
+    const auto big_dest = std::filesystem::path(testing::TempDir()) / "acecode-discord-big.bin";
+    EXPECT_FALSE(transport.download(big, big_dest, &error));
+    EXPECT_NE(error.find(u8"大小限制"), std::string::npos) << error;
+    EXPECT_FALSE(std::filesystem::exists(big_dest));
+}
+
+// 场景:附件地址不在 Discord CDN 的主机上(默认只允许 cdn.discordapp.com / media.discordapp.net)。
+// 期望:拒绝下载并说明原因,不发出任何请求。
+TEST(DiscordTransport, RejectsAttachmentHostsOutsideTheCdn) {
+    FakeDiscordServer server;
+    auto options = local_options(server);
+    options.download_hosts = {"cdn.discordapp.com", "media.discordapp.net"};
+    DiscordTransport transport(options);
+    Attachment attachment;
+    attachment.remote_ref = server.cdn_url(kChannel, "1290000000000000099", "notes.txt");
+    std::string error;
+    EXPECT_FALSE(transport.download(attachment, std::filesystem::path(testing::TempDir()) / "acecode-discord-x.txt", &error));
+    EXPECT_NE(error.find("CDN"), std::string::npos) << error;
+    EXPECT_TRUE(server.requests_to("GET", "/cdn/").empty());
+}
+
+// 场景:收到带附件的私信,但等到下载时签名地址已过期(CDN 返回 404)。
+// 期望:重新取一次这条消息拿到新的签名地址,再下载成功。
+TEST(DiscordTransport, RefreshesExpiredAttachmentUrl) {
+    FakeDiscordServer server;
+    const std::string attachment_id = "1290000000000000099";
+    server.expired_attachments = {attachment_id};
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    server.push_dm("600000000000000021", kUser, u8"看附件",
+                   nlohmann::json::array({{{"id", attachment_id}, {"filename", "notes.txt"}, {"size", 32},
+                                           {"content_type", "text/plain"},
+                                           {"url", server.cdn_url(dm_channel(), attachment_id, "notes.txt")}}}));
+    ASSERT_TRUE(FakeDiscordServer::wait_until([&recorder] { return recorder.count() == 1; }));
+    const auto in = recorder.at(0);
+    ASSERT_EQ(in.attachments.size(), 1u);
+    const auto dest = std::filesystem::path(testing::TempDir()) / "acecode-discord-refreshed.txt";
+    std::string error;
+    ASSERT_TRUE(transport.download(in.attachments[0], dest, &error)) << error;
+    EXPECT_EQ(server.requests_to("GET", "/channels/" + dm_channel() + "/messages/600000000000000021").size(), 1u);
+    EXPECT_EQ(server.requests_to("GET", "/cdn/attachments/").size(), 2u);
+    std::filesystem::remove(dest);
+}
+
+// 场景:/gateway/bot 一直返回 500,传输层处于 30 秒的重连退避中,此时关闭通道。
+// 期望:stop() 立即打断等待并返回(2 秒内),状态为已停止。
+TEST(DiscordTransport, StopIsPromptDuringBackoff) {
+    FakeDiscordServer server;
+    server.gateway_bot_status = 500;
+    auto options = local_options(server);
+    options.backoff = {std::chrono::seconds(30)};
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    DiscordTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Retrying));
+    const auto begin = std::chrono::steady_clock::now();
+    transport.stop();
+    EXPECT_LT(std::chrono::steady_clock::now() - begin, std::chrono::seconds(2));
+    EXPECT_EQ(transport.status().state, LinkState::Stopped);
+}
+
+} // namespace
+} // namespace acecode::im::discord
diff --git a/tests/im/feishu_api_test.cpp b/tests/im/feishu_api_test.cpp
new file mode 100644
index 000000000..a47c349f0
--- /dev/null
+++ b/tests/im/feishu_api_test.cpp
@@ -0,0 +1,216 @@
+#include <gtest/gtest.h>
+
+#include "im/feishu/feishu_api.hpp"
+#include "test_support/im/fake_feishu_server.hpp"
+
+#include <atomic>
+#include <filesystem>
+#include <fstream>
+
+// im/feishu/feishu_api:飞书 OpenAPI 客户端对本机假开放平台的端到端测试 ——
+// 令牌缓存与失效重取、凭据校验(成功 / 凭据错误 / 网络不通 / 机器人未就绪)、
+// 长连接地址请求、消息资源下载。
+
+namespace acecode::im::feishu {
+namespace {
+
+using test::FakeFeishuServer;
+
+ApiOptions local_options(const FakeFeishuServer& server) {
+    ApiOptions options;
+    options.app_id = "cli_app";
+    options.app_secret = "secret-value-123";
+    options.base = server.base();
+    options.use_proxy = false;
+    return options;
+}
+
+std::filesystem::path temp_file(const char* name) { return std::filesystem::path(testing::TempDir()) / name; }
+
+// 场景:连续两次调用需要令牌的接口。
+// 期望:只换一次令牌并复用缓存;请求带 "Bearer <令牌>" 与含独立 channel 标记的 User-Agent。
+TEST(FeishuApi, CachesTenantTokenAcrossCalls) {
+    FakeFeishuServer server;
+    Api api(local_options(server));
+    std::string error;
+    EXPECT_TRUE(api.bot_info(&error).ok) << error;
+    EXPECT_TRUE(api.bot_info(&error).ok) << error;
+    EXPECT_EQ(server.token_calls(), 1);
+    const auto info = server.requests_to("/open-apis/bot/v3/info");
+    ASSERT_EQ(info.size(), 2u);
+    EXPECT_EQ(info[1].authorization, "Bearer t-1");
+    EXPECT_NE(info[1].user_agent.find(" channel"), std::string::npos) << info[1].user_agent;
+    const auto token = server.requests_to("/open-apis/auth/v3/tenant_access_token/internal");
+    ASSERT_EQ(token.size(), 1u);
+    EXPECT_EQ(token[0].body.value("app_id", ""), "cli_app");
+    EXPECT_EQ(token[0].body.value("app_secret", ""), "secret-value-123");
+}
+
+// 场景:发消息时平台返回 99991663(令牌失效,例如被另一个客户端换了新令牌后旧的到期)。
+// 期望:丢弃缓存、换新令牌并用新令牌重试一次,最终成功;不把错误交给调用方。
+TEST(FeishuApi, RefreshesTokenOnInvalidTokenCode) {
+    FakeFeishuServer server;
+    std::atomic<int> calls{0};
+    server.message_handler = [&calls](const FakeFeishuServer::Request&) {
+        if (calls++ == 0)
+            return std::make_pair(400, nlohmann::json{{"code", 99991663}, {"msg", "Invalid access token"}});
+        return std::make_pair(200, nlohmann::json{{"code", 0}, {"data", {{"message_id", "om_ok"}}}});
+    };
+    Api api(local_options(server));
+    const auto result = api.call("POST", "/open-apis/im/v1/messages?receive_id_type=chat_id",
+                                 {{"receive_id", "oc_1"}, {"msg_type", "text"}, {"content", R"({"text":"hi"})"}});
+    EXPECT_TRUE(result.ok) << describe_error(result);
+    EXPECT_EQ(result.data.value("message_id", ""), "om_ok");
+    EXPECT_EQ(server.token_calls(), 2);
+    const auto sends = server.sends();
+    ASSERT_EQ(sends.size(), 2u);
+    EXPECT_EQ(sends[1].authorization, "Bearer t-2");
+    EXPECT_EQ(sends[1].query, "chat_id");
+}
+
+// 场景:发消息被限流,响应头带 x-ogw-ratelimit-reset 与 X-Tt-Logid。
+// 期望:ApiResult 判为限流,带出平台要求的等待秒数与请求 id(只用于日志排障)。
+TEST(FeishuApi, ReadsRateLimitHeaders) {
+    FakeFeishuServer server;
+    server.message_handler = [](const FakeFeishuServer::Request&) {
+        return std::make_pair(429, nlohmann::json{{"code", 99991400}, {"msg", "request trigger frequency limit"}});
+    };
+    server.message_headers = {{"x-ogw-ratelimit-reset", "2"}, {"X-Tt-Logid", "log-123"}};
+    Api api(local_options(server));
+    const auto result = api.call("POST", "/open-apis/im/v1/messages?receive_id_type=chat_id", {{"receive_id", "oc"}});
+    EXPECT_FALSE(result.ok);
+    EXPECT_TRUE(is_rate_limited(result));
+    EXPECT_EQ(result.retry_after, std::chrono::seconds(2));
+    EXPECT_EQ(result.log_id, "log-123");
+}
+
+// 场景:保存凭据前联网校验,凭据正确且机器人已发布启用。
+// 期望:ok,返回机器人 open_id 与名称,机器人就绪、没有提示。
+TEST(FeishuApi, VerifyReturnsBotIdentity) {
+    FakeFeishuServer server;
+    const auto result = verify_credentials(local_options(server));
+    EXPECT_TRUE(result.ok) << result.error;
+    EXPECT_FALSE(result.auth_failed);
+    EXPECT_EQ(result.bot_open_id, "ou_bot");
+    EXPECT_EQ(result.bot_name, "TestBot");
+    EXPECT_TRUE(result.bot_ready);
+    EXPECT_TRUE(result.bot_warning.empty());
+}
+
+// 场景:App Secret 填错,换令牌接口返回 HTTP 200 + code 10015。
+// 期望:判为凭据被拒(不是网络问题),给出“App Secret 不正确”,错误文本不含密钥。
+TEST(FeishuApi, VerifyReportsWrongSecret) {
+    FakeFeishuServer server;
+    server.token_handler = [](const FakeFeishuServer::Request&) {
+        return std::make_pair(200, nlohmann::json{{"code", 10015}, {"msg", "wrong app secret"}});
+    };
+    const auto result = verify_credentials(local_options(server));
+    EXPECT_FALSE(result.ok);
+    EXPECT_TRUE(result.auth_failed);
+    EXPECT_FALSE(result.network_error);
+    EXPECT_NE(result.error.find("App Secret"), std::string::npos) << result.error;
+    EXPECT_EQ(result.error.find("secret-value-123"), std::string::npos);
+}
+
+// 场景:网络不通(端口 1 上没有服务);以及没填 App Secret。
+// 期望:前者判为网络错误而非凭据错误;后者直接提示填写,不发请求。
+TEST(FeishuApi, VerifyDistinguishesNetworkFailure) {
+    ApiOptions options;
+    options.app_id = "cli_app";
+    options.app_secret = "secret-value-123";
+    options.base = "http://127.0.0.1:1";
+    options.use_proxy = false;
+    const auto result = verify_credentials(options);
+    EXPECT_FALSE(result.ok);
+    EXPECT_TRUE(result.network_error);
+    EXPECT_FALSE(result.auth_failed);
+    EXPECT_NE(result.error.find("无法连接"), std::string::npos) << result.error;
+
+    options.app_secret.clear();
+    const auto empty = verify_credentials(options);
+    EXPECT_TRUE(empty.auth_failed);
+    EXPECT_FALSE(empty.error.empty());
+}
+
+// 场景:凭据正确,但机器人还没就绪 —— 一次 activate_status=0(待安装),一次 bot/v3/info 直接报错
+// (未添加机器人能力 / 未发布版本)。
+// 期望:凭据仍判为有效(长连接不依赖它,飞书后台要先有在线长连接才能保存订阅方式),
+// 但 bot_ready=false 并给出中文提示。
+TEST(FeishuApi, VerifyWarnsWhenBotIsNotReady) {
+    FakeFeishuServer server;
+    std::atomic<int> calls{0};
+    server.bot_handler = [&calls](const FakeFeishuServer::Request&) {
+        if (calls++ == 0)
+            return std::make_pair(200, nlohmann::json{{"code", 0},
+                                                      {"bot", {{"activate_status", 0}, {"open_id", "ou_bot"}}}});
+        return std::make_pair(400, nlohmann::json{{"code", 230006}, {"msg", "bot ability is not activated"}});
+    };
+    const auto inactive = verify_credentials(local_options(server));
+    EXPECT_TRUE(inactive.ok);
+    EXPECT_FALSE(inactive.bot_ready);
+    EXPECT_EQ(inactive.activate_status, 0);
+    EXPECT_FALSE(inactive.bot_warning.empty());
+    const auto missing = verify_credentials(local_options(server));
+    EXPECT_TRUE(missing.ok);
+    EXPECT_FALSE(missing.bot_ready);
+    EXPECT_NE(missing.bot_warning.find("机器人能力"), std::string::npos) << missing.bot_warning;
+}
+
+// 场景:请求长连接地址;另一次平台以 1000040345 拒绝凭据。
+// 期望:请求体用 PascalCase 的 AppID / AppSecret,带 locale: zh 与 channel UA;解析出地址、
+// service_id、device_id。被拒时判为致命,原因不含密钥。
+TEST(FeishuApi, RequestsWebSocketEndpoint) {
+    FakeFeishuServer server;
+    Api api(local_options(server));
+    const auto info = api.ws_endpoint();
+    ASSERT_TRUE(info.ok) << info.message;
+    EXPECT_EQ(info.service_id, 1234);
+    EXPECT_EQ(info.device_id, "dev-7");
+    const auto requests = server.requests_to("/callback/ws/endpoint");
+    ASSERT_EQ(requests.size(), 1u);
+    EXPECT_EQ(requests[0].body.value("AppID", ""), "cli_app");
+    EXPECT_EQ(requests[0].body.value("AppSecret", ""), "secret-value-123");
+    EXPECT_EQ(requests[0].locale, "zh");
+    EXPECT_NE(requests[0].user_agent.find(" channel"), std::string::npos);
+    EXPECT_EQ(server.token_calls(), 0);  // 长连接不用 tenant_access_token
+
+    server.endpoint_handler = [](const FakeFeishuServer::Request&) {
+        return std::make_pair(200, nlohmann::json{{"code", 1000040345}, {"msg", "app_id or app_secret is invalid"},
+                                                  {"data", {{"URL", ""}}}});
+    };
+    const auto rejected = api.ws_endpoint();
+    EXPECT_TRUE(rejected.fatal);
+    EXPECT_EQ(rejected.message.find("secret-value-123"), std::string::npos);
+}
+
+// 场景:下载消息里的图片;下载超过本地上限的文件;下载合并转发里的附件(平台拒绝);
+// 下载时令牌恰好失效。
+// 期望:正常下载写出完整文件并带 type=image;超限失败、删除半截文件并提示“超过大小限制”;
+// 平台拒绝时给出中文原因;令牌失效时换新令牌重试一次后成功。
+TEST(FeishuApi, DownloadsMessageResources) {
+    FakeFeishuServer server;
+    Api api(local_options(server));
+    const auto dest = temp_file("acecode-feishu-download.bin");
+    std::string error;
+    ASSERT_TRUE(api.download_resource({"om_1", "img_k", "image"}, dest, 1024, &error)) << error;
+    EXPECT_EQ(std::filesystem::file_size(dest), 16u);
+    const auto first = server.requests_to("/open-apis/im/v1/messages/om_1/resources/img_k");
+    ASSERT_EQ(first.size(), 1u);
+    EXPECT_EQ(first[0].query, "image");
+
+    EXPECT_FALSE(api.download_resource({"om_1", "big", "file"}, dest, 1024, &error));
+    EXPECT_NE(error.find("超过"), std::string::npos) << error;
+    EXPECT_FALSE(std::filesystem::exists(dest));
+
+    EXPECT_FALSE(api.download_resource({"om_1", "gone", "file"}, dest, 1024, &error));
+    EXPECT_NE(error.find("合并转发"), std::string::npos) << error;
+    EXPECT_FALSE(std::filesystem::exists(dest));
+
+    const auto before = server.token_calls();
+    ASSERT_TRUE(api.download_resource({"om_1", "expired", "file"}, dest, 1024, &error)) << error;
+    EXPECT_EQ(server.token_calls(), before + 1);
+    std::filesystem::remove(dest);
+}
+
+} // namespace
+} // namespace acecode::im::feishu
diff --git a/tests/im/feishu_frame_test.cpp b/tests/im/feishu_frame_test.cpp
new file mode 100644
index 000000000..16f045793
--- /dev/null
+++ b/tests/im/feishu_frame_test.cpp
@@ -0,0 +1,159 @@
+#include <gtest/gtest.h>
+
+#include "im/feishu/feishu_frame.hpp"
+
+#include <initializer_list>
+
+// im/feishu/feishu_frame:飞书长连接 pbbp2 帧的手写 protobuf 编解码。
+// 期望字节全部由真实 protobuf 运行时按同一 schema 生成(service_id = 1234),
+// 与飞书协议调研文档 §5.3 的测试向量一致;编码必须逐字节相同。
+
+namespace acecode::im::feishu {
+namespace {
+
+// "08 00 10 …" → 原始字节。
+std::string hex(const char* text) {
+    std::string out;
+    int high = -1;
+    for (const char* p = text; *p; ++p) {
+        const char c = *p;
+        int value = -1;
+        if (c >= '0' && c <= '9') value = c - '0';
+        else if (c >= 'a' && c <= 'f') value = c - 'a' + 10;
+        if (value < 0) continue;
+        if (high < 0) {
+            high = value;
+        } else {
+            out.push_back(static_cast<char>(high * 16 + value));
+            high = -1;
+        }
+    }
+    return out;
+}
+
+std::string bytes(std::initializer_list<int> values) {
+    std::string out;
+    for (const int v : values) out.push_back(static_cast<char>(v));
+    return out;
+}
+
+const char* kPing = "08 00 10 00 18 d2 09 20 00 2a 0c 0a 04 74 79 70 65 12 04 70 69 6e 67";
+const char* kData =
+    "08 00 10 00 18 d2 09 20 01 2a 0d 0a 04 74 79 70 65 12 05 65 76 65 6e 74 2a 10 0a 0a 6d 65 73 73 61 67 65 5f "
+    "69 64 12 02 6d 31 2a 08 0a 03 73 75 6d 12 01 31 2a 08 0a 03 73 65 71 12 01 30 2a 0e 0a 08 74 72 61 63 65 5f 69 "
+    "64 12 02 74 31 42 10 7b 22 73 63 68 65 6d 61 22 3a 22 32 2e 30 22 7d";
+const char* kAck =
+    "08 00 10 00 18 d2 09 20 01 2a 0d 0a 04 74 79 70 65 12 05 65 76 65 6e 74 2a 10 0a 0a 6d 65 73 73 61 67 65 5f "
+    "69 64 12 02 6d 31 2a 08 0a 03 73 75 6d 12 01 31 2a 08 0a 03 73 65 71 12 01 30 2a 0e 0a 08 74 72 61 63 65 5f 69 "
+    "64 12 02 74 31 2a 0b 0a 06 62 69 7a 5f 72 74 12 01 33 42 0c 7b 22 63 6f 64 65 22 3a 32 30 30 7d";
+// SeqID=300, LogID=7000000000, payload_encoding 存在但为空, payload_type="json", payload="P", LogIDNew="L9"。
+const char* kFull =
+    "08 ac 02 10 80 8c ee 89 1a 18 d2 09 20 01 2a 0d 0a 04 74 79 70 65 12 05 65 76 65 6e 74 32 00 3a 04 6a 73 6f 6e "
+    "42 01 50 4a 02 4c 39";
+// service = -5:int32 负数按 64 位符号扩展,是 10 字节 varint。
+const char* kNegative = "08 01 10 02 18 fb ff ff ff ff ff ff ff ff 01 20 01";
+
+// 场景:客户端心跳帧(service_id 1234)。
+// 期望:与官方运行时的字节完全一致 —— 字段 1–4 即使为 0 也写出,只有一个 type=ping 头,没有 payload。
+TEST(FeishuFrame, EncodesPingExactly) {
+    EXPECT_EQ(encode_frame(make_ping_frame(1234)), hex(kPing));
+}
+
+// 场景:构造一个带 5 个头与 JSON payload 的 DATA 帧。
+// 期望:逐字节等于测试向量;header 保持插入顺序,可选字段 6/7/9 未设置时不写出。
+TEST(FeishuFrame, EncodesDataFrameExactly) {
+    Frame frame;
+    frame.service = 1234;
+    frame.method = kMethodData;
+    frame.headers = {{"type", "event"}, {"message_id", "m1"}, {"sum", "1"}, {"seq", "0"}, {"trace_id", "t1"}};
+    frame.payload = R"({"schema":"2.0"})";
+    EXPECT_EQ(encode_frame(frame), hex(kData));
+}
+
+// 场景:解码服务端事件帧,再按规则生成 ACK(业务耗时 3 ms)。
+// 期望:ACK 原样回显原帧的全部字段与头(顺序不变),末尾追加 biz_rt=3,payload 换成 {"code":200};
+// 逐字节等于测试向量。回归意义:ACK 字段漏回显会让平台认为没送达,15 秒后重投。
+TEST(FeishuFrame, AckEchoesReceivedFrameAndAppendsBizRt) {
+    Frame frame;
+    std::string error;
+    ASSERT_TRUE(decode_frame(hex(kData), &frame, &error)) << error;
+    EXPECT_EQ(frame.service, 1234);
+    EXPECT_EQ(frame.method, kMethodData);
+    EXPECT_EQ(frame.header("message_id"), "m1");
+    ASSERT_TRUE(frame.payload.has_value());
+    EXPECT_EQ(*frame.payload, R"({"schema":"2.0"})");
+    EXPECT_EQ(encode_frame(make_ack_frame(frame, 3, R"({"code":200})")), hex(kAck));
+}
+
+// 场景:服务端帧带了全部可选字段,其中 payload_encoding 存在但为空。
+// 期望:解码出全部字段(大数值 LogID 正确);重新编码与原字节完全一致 —— “存在但为空”的字段
+// 回 ACK 时也要回显(Go SDK 总是写出)。
+TEST(FeishuFrame, OptionalFieldPresenceRoundTrips) {
+    Frame frame;
+    ASSERT_TRUE(decode_frame(hex(kFull), &frame, nullptr));
+    EXPECT_EQ(frame.seq_id, 300u);
+    EXPECT_EQ(frame.log_id, 7000000000ull);
+    ASSERT_TRUE(frame.payload_encoding.has_value());
+    EXPECT_TRUE(frame.payload_encoding->empty());
+    EXPECT_EQ(frame.payload_type.value_or(""), "json");
+    EXPECT_EQ(frame.payload.value_or(""), "P");
+    EXPECT_EQ(frame.log_id_new.value_or(""), "L9");
+    EXPECT_EQ(encode_frame(frame), hex(kFull));
+}
+
+// 场景:service 为负数(协议里不会出现,但要按 protobuf 规则处理)。
+// 期望:编码为 10 字节 varint;解码回原值。
+TEST(FeishuFrame, NegativeInt32UsesTenByteVarint) {
+    Frame frame;
+    frame.seq_id = 1;
+    frame.log_id = 2;
+    frame.service = -5;
+    frame.method = kMethodData;
+    EXPECT_EQ(encode_frame(frame), hex(kNegative));
+    Frame decoded;
+    ASSERT_TRUE(decode_frame(hex(kNegative), &decoded, nullptr));
+    EXPECT_EQ(decoded.service, -5);
+}
+
+// 场景:字段乱序到达,夹带四种 wire type 的未知字段,header 里也有未知子字段,且有重复头。
+// 期望:全部跳过未知字段,已知字段正确解析;重复头按出现顺序保留。
+TEST(FeishuFrame, DecoderSkipsUnknownFieldsInAnyOrder) {
+    std::string data;
+    data += bytes({0x42, 0x02}) + "{}";                                    // payload 先到
+    data += bytes({0x78, 0x96, 0x01});                                    // 字段 15 varint
+    data += bytes({0x81, 0x01, 1, 2, 3, 4, 5, 6, 7, 8});                  // 字段 16 fixed64
+    data += bytes({0x8a, 0x01, 0x03}) + "abc";                            // 字段 17 length-delimited
+    data += bytes({0x95, 0x01, 1, 2, 3, 4});                              // 字段 18 fixed32
+    data += bytes({0x2a, 0x08, 0x0a, 0x01, 'k', 0x12, 0x01, 'v', 0x18, 0x05});  // header + 未知子字段
+    data += bytes({0x2a, 0x06, 0x0a, 0x01, 'k', 0x12, 0x01, 'w'});        // 重复的 k
+    data += bytes({0x20, 0x01, 0x18, 0xd2, 0x09});                        // method 在 service 之前
+    Frame frame;
+    std::string error;
+    ASSERT_TRUE(decode_frame(data, &frame, &error)) << error;
+    EXPECT_EQ(frame.service, 1234);
+    EXPECT_EQ(frame.method, kMethodData);
+    ASSERT_EQ(frame.headers.size(), 2u);
+    EXPECT_EQ(frame.headers[0].second, "v");
+    EXPECT_EQ(frame.headers[1].second, "w");
+    EXPECT_EQ(frame.header("k"), "v");
+    EXPECT_EQ(frame.payload.value_or(""), "{}");
+    EXPECT_FALSE(frame.payload_type.has_value());
+}
+
+// 场景:损坏的帧 —— 长度越界、varint 超过 10 字节、group wire type、已知字段的 wire type 不对、截断的 tag。
+// 期望:全部解码失败并给出原因,不越界读、不崩溃。
+TEST(FeishuFrame, DecoderRejectsMalformedInput) {
+    Frame frame;
+    std::string error;
+    EXPECT_FALSE(decode_frame(bytes({0x42, 0x10, 'a'}), &frame, &error));
+    EXPECT_FALSE(error.empty());
+    EXPECT_FALSE(decode_frame(bytes({0x08, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x01}),
+                              &frame, nullptr));
+    EXPECT_FALSE(decode_frame(bytes({0x7b, 0x00}), &frame, nullptr));        // 字段 15 group 起始
+    EXPECT_FALSE(decode_frame(bytes({0x1a, 0x01, 0x00}), &frame, nullptr));  // service 用了 length-delimited
+    EXPECT_FALSE(decode_frame(bytes({0x80}), &frame, nullptr));
+    EXPECT_TRUE(decode_frame(std::string(), &frame, nullptr));  // 空帧合法(全部取默认值)
+}
+
+} // namespace
+} // namespace acecode::im::feishu
diff --git a/tests/im/feishu_gateway_test.cpp b/tests/im/feishu_gateway_test.cpp
new file mode 100644
index 000000000..3af2402e8
--- /dev/null
+++ b/tests/im/feishu_gateway_test.cpp
@@ -0,0 +1,207 @@
+#include <gtest/gtest.h>
+
+#include "im/feishu/feishu_gateway.hpp"
+#include "im/feishu/feishu_pacer.hpp"
+
+// im/feishu/feishu_gateway:飞书长连接会话状态机(心跳、读超时、ACK、拆包重组、pong 配置)
+// 与重连等待计算;im/feishu/feishu_pacer:发送节流。全部用假时间驱动,不碰网络。
+
+namespace acecode::im::feishu {
+namespace {
+
+using Clock = LinkSession::Clock;
+using std::chrono::milliseconds;
+using std::chrono::seconds;
+
+Frame event_frame(const std::string& payload, const std::string& id = "f1", int sum = 1, int seq = 0) {
+    Frame frame;
+    frame.seq_id = 7;
+    frame.log_id = 9;
+    frame.service = 1234;
+    frame.method = kMethodData;
+    frame.headers = {{"type", "event"}, {"message_id", id}, {"sum", std::to_string(sum)},
+                     {"seq", std::to_string(seq)}, {"trace_id", "t"}, {"instance_id", "inst"}};
+    frame.payload = payload;
+    return frame;
+}
+
+Frame decode(const std::string& bytes) {
+    Frame frame;
+    EXPECT_TRUE(decode_frame(bytes, &frame, nullptr));
+    return frame;
+}
+
+LinkSession connected_session(Clock::time_point t0, int ping_seconds = 10) {
+    LinkSession session;
+    ClientConfig config;
+    config.ping_interval_s = ping_seconds;
+    session.set_config(config);
+    session.on_connected(1234, t0);
+    return session;
+}
+
+// 场景:连上长连接后时间推进(心跳间隔 10 秒),期间服务端一直有回应。
+// 期望:连上的第一个 tick 立即发心跳(service_id 正确),之后不到 10 秒不发,满 10 秒再发。
+TEST(FeishuGateway, PingsImmediatelyThenEveryInterval) {
+    const auto t0 = Clock::now();
+    auto session = connected_session(t0);
+    const auto first = session.on_tick(t0);
+    ASSERT_TRUE(first.ping.has_value());
+    EXPECT_EQ(*first.ping, encode_frame(make_ping_frame(1234)));
+    EXPECT_FALSE(session.on_tick(t0 + seconds(5)).ping.has_value());
+    session.on_message(encode_frame(Frame{}), t0 + seconds(6));  // 任意帧刷新读超时
+    EXPECT_TRUE(session.on_tick(t0 + seconds(10)).ping.has_value());
+}
+
+// 场景:NAT 断开后 read 永远阻塞,心跳写入照样“成功”,但服务端不再有任何帧到达。
+// 期望:超过 2 × 心跳间隔 + 5 秒(此处 25 秒)判定假死;期间收到任何帧都会重新计时。
+TEST(FeishuGateway, DetectsSilentConnectionAfterReadTimeout) {
+    const auto t0 = Clock::now();
+    auto session = connected_session(t0);
+    EXPECT_EQ(session.read_timeout(), milliseconds(25000));
+    EXPECT_FALSE(session.on_tick(t0 + seconds(24)).dead);
+    session.on_message(encode_frame(Frame{}), t0 + seconds(24));
+    EXPECT_FALSE(session.on_tick(t0 + seconds(40)).dead);
+    EXPECT_TRUE(session.on_tick(t0 + seconds(49)).dead);
+}
+
+// 场景:收到一个未拆包的事件帧。
+// 期望:立即产出一个 ACK —— 回显原帧(SeqID/LogID/service/全部头,含 instance_id),追加 biz_rt,
+// payload 为 {"code":200};同时把完整的事件 JSON 交给调用方。
+TEST(FeishuGateway, AcksEventFramesAndEmitsPayload) {
+    const auto t0 = Clock::now();
+    auto session = connected_session(t0);
+    const auto out = session.on_message(encode_frame(event_frame(R"({"schema":"2.0"})")), t0);
+    ASSERT_EQ(out.frames.size(), 1u);
+    ASSERT_EQ(out.events.size(), 1u);
+    EXPECT_EQ(out.events[0], R"({"schema":"2.0"})");
+    const auto ack = decode(out.frames[0]);
+    EXPECT_EQ(ack.seq_id, 7u);
+    EXPECT_EQ(ack.log_id, 9u);
+    EXPECT_EQ(ack.service, 1234);
+    EXPECT_EQ(ack.method, kMethodData);
+    EXPECT_EQ(ack.header("instance_id"), "inst");
+    EXPECT_EQ(ack.headers.back().first, "biz_rt");
+    EXPECT_EQ(ack.payload.value_or(""), R"({"code":200})");
+}
+
+// 场景:一个事件被拆成 3 片乱序到达(seq 2、0、1)。
+// 期望:前两片不回应、不产出事件;凑齐时按序号拼接出完整 JSON,只用凑齐的那一帧(seq=1)回 ACK。
+TEST(FeishuGateway, ReassemblesSplitPayloadsOutOfOrder) {
+    const auto t0 = Clock::now();
+    auto session = connected_session(t0);
+    EXPECT_TRUE(session.on_message(encode_frame(event_frame("C", "big", 3, 2)), t0).frames.empty());
+    EXPECT_TRUE(session.on_message(encode_frame(event_frame("A", "big", 3, 0)), t0).events.empty());
+    EXPECT_EQ(session.pending_sets(), 1u);
+    const auto out = session.on_message(encode_frame(event_frame("B", "big", 3, 1)), t0 + milliseconds(100));
+    ASSERT_EQ(out.events.size(), 1u);
+    EXPECT_EQ(out.events[0], "ABC");
+    ASSERT_EQ(out.frames.size(), 1u);
+    EXPECT_EQ(decode(out.frames[0]).header("seq"), "1");
+    EXPECT_EQ(session.pending_sets(), 0u);
+}
+
+// 场景:拆包的第二片在 6 秒后才到(缓存存活 5 秒,每片刷新)。
+// 期望:第一片已过期被丢弃,第二片单独凑不齐,不产出事件也不回 ACK(平台会整体重投)。
+TEST(FeishuGateway, ExpiresIncompleteSplitPayloads) {
+    const auto t0 = Clock::now();
+    auto session = connected_session(t0);
+    session.on_message(encode_frame(event_frame("A", "m", 2, 0)), t0);
+    const auto out = session.on_message(encode_frame(event_frame("B", "m", 2, 1)), t0 + seconds(6));
+    EXPECT_TRUE(out.events.empty());
+    EXPECT_TRUE(out.frames.empty());
+}
+
+// 场景:非法的拆包头(sum=0、seq 越界、sum 超过 64 片上限)。
+// 期望:丢弃并给出日志警告,不 ACK、不产出事件、不分配缓存。
+TEST(FeishuGateway, RejectsInvalidSplitHeaders) {
+    const auto t0 = Clock::now();
+    auto session = connected_session(t0);
+    for (const auto& frame : {event_frame("x", "a", 0, 0), event_frame("x", "b", 2, 2), event_frame("x", "c", 65, 0)}) {
+        const auto out = session.on_message(encode_frame(frame), t0);
+        EXPECT_TRUE(out.frames.empty());
+        EXPECT_TRUE(out.events.empty());
+        EXPECT_FALSE(out.warning.empty());
+    }
+    EXPECT_EQ(session.pending_sets(), 0u);
+}
+
+// 场景:服务端 pong 带来新的 ClientConfig(心跳改为 30 秒);另有服务端 ping、旧版 card 帧、损坏的帧。
+// 期望:pong 配置立即生效;服务端 ping 与 card 帧不回应;损坏的帧只产生警告。
+TEST(FeishuGateway, AppliesPongConfigAndIgnoresOtherFrames) {
+    const auto t0 = Clock::now();
+    auto session = connected_session(t0);
+    Frame pong;
+    pong.service = 1234;
+    pong.headers = {{"type", "pong"}};
+    pong.payload = R"({"PingInterval":30,"ReconnectInterval":60})";
+    const auto out = session.on_message(encode_frame(pong), t0);
+    EXPECT_TRUE(out.config_updated);
+    EXPECT_EQ(session.ping_interval(), milliseconds(30000));
+    EXPECT_EQ(session.config().reconnect_interval_s, 60);
+
+    Frame ping = make_ping_frame(1234);
+    EXPECT_TRUE(session.on_message(encode_frame(ping), t0).frames.empty());
+    auto card = event_frame("{}");
+    card.headers[0].second = "card";
+    const auto card_out = session.on_message(encode_frame(card), t0);
+    EXPECT_TRUE(card_out.frames.empty());
+    EXPECT_TRUE(card_out.events.empty());
+    EXPECT_FALSE(session.on_message(std::string("\x42\x10", 2), t0).warning.empty());
+}
+
+// 场景:断开后 tick。
+// 期望:不再发心跳也不判定假死(由重连流程接管)。
+TEST(FeishuGateway, DisconnectedSessionIsQuiet) {
+    const auto t0 = Clock::now();
+    auto session = connected_session(t0);
+    session.on_disconnected();
+    const auto tick = session.on_tick(t0 + seconds(100));
+    EXPECT_FALSE(tick.ping.has_value());
+    EXPECT_FALSE(tick.dead);
+}
+
+// 场景:各种重连时机 —— 还没拿到服务端参数、刚掉线(随机抖动)、连续失败(服务端间隔)、本地退避更大。
+// 期望:没有服务端参数时只用本地退避;刚掉线时为 jitter × ReconnectNonce;之后为 ReconnectInterval;
+// 与本地退避取大。
+TEST(FeishuGateway, ComputesReconnectDelay) {
+    ClientConfig config;  // nonce 30 s,interval 120 s
+    const std::vector<milliseconds> backoff{milliseconds(1000), milliseconds(5000), milliseconds(200000)};
+    EXPECT_EQ(reconnect_delay(config, false, 0, backoff, 0.9), milliseconds(1000));
+    EXPECT_EQ(reconnect_delay(config, false, 7, backoff, 0.9), milliseconds(200000));
+    EXPECT_EQ(reconnect_delay(config, true, 0, backoff, 0.5), milliseconds(15000));
+    EXPECT_EQ(reconnect_delay(config, true, 0, backoff, 0.0), milliseconds(1000));
+    EXPECT_EQ(reconnect_delay(config, true, 1, backoff, 0.5), milliseconds(120000));
+    EXPECT_EQ(reconnect_delay(config, true, 2, backoff, 0.5), milliseconds(200000));
+    config.reconnect_interval_s = 0;
+    config.reconnect_nonce_s = 0;
+    EXPECT_EQ(reconnect_delay(config, true, 1, {milliseconds(50)}, 0.5), milliseconds(50));
+}
+
+// 场景:服务端 ReconnectCount 为 -1(无限)、3,以及还没拿到服务端参数。
+// 期望:-1 与无服务端参数时永不停止;为 3 时连续失败 3 次后停止。
+TEST(FeishuGateway, StopsAfterServerReconnectCount) {
+    ClientConfig config;
+    EXPECT_FALSE(reconnect_exhausted(config, true, 1000));
+    config.reconnect_count = 3;
+    EXPECT_FALSE(reconnect_exhausted(config, true, 2));
+    EXPECT_TRUE(reconnect_exhausted(config, true, 3));
+    EXPECT_FALSE(reconnect_exhausted(config, false, 3));
+}
+
+// 场景:同一接收方连续发三条,另一接收方发一条;随后第一个接收方被平台限流 2 秒。
+// 期望:同一接收方相邻两条间隔 250 ms,不同接收方互不影响;限流期内的预约推迟到限流结束。
+TEST(FeishuGateway, PacerSpacesSendsPerTarget) {
+    SendPacer pacer(milliseconds(250));
+    const auto t0 = Clock::now();
+    EXPECT_EQ(pacer.reserve("oc_a", t0), t0);
+    EXPECT_EQ(pacer.reserve("oc_a", t0), t0 + milliseconds(250));
+    EXPECT_EQ(pacer.reserve("oc_a", t0), t0 + milliseconds(500));
+    EXPECT_EQ(pacer.reserve("oc_b", t0), t0);
+    pacer.penalize("oc_a", seconds(2), t0);
+    EXPECT_EQ(pacer.reserve("oc_a", t0), t0 + seconds(2));
+    EXPECT_EQ(pacer.tracked(), 2u);
+}
+
+} // namespace
+} // namespace acecode::im::feishu
diff --git a/tests/im/feishu_protocol_test.cpp b/tests/im/feishu_protocol_test.cpp
new file mode 100644
index 000000000..25f804555
--- /dev/null
+++ b/tests/im/feishu_protocol_test.cpp
@@ -0,0 +1,494 @@
+#include <gtest/gtest.h>
+
+#include "im/feishu/feishu_protocol.hpp"
+
+#include <chrono>
+
+// im/feishu/feishu_protocol:飞书协议纯逻辑 —— 接入地址、长连接地址响应与握手分类、
+// OpenAPI 错误分类、im.message.receive_v1 解析(@ 判定、文本清理、附件)、出站 Markdown 与分段。
+
+namespace acecode::im::feishu {
+namespace {
+
+std::int64_t now_ms() {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(
+               std::chrono::system_clock::now().time_since_epoch())
+        .count();
+}
+
+const BotIdentity kBot{"ou_bot", "TestBot"};
+
+nlohmann::json bot_mention(const std::string& key = "@_user_1") {
+    return {{"key", key}, {"id", {{"open_id", "ou_bot"}, {"union_id", "on_b"}}}, {"mentioned_type", "bot"},
+            {"name", "TestBot"}, {"tenant_key", "tk"}};
+}
+
+nlohmann::json user_mention(const std::string& key, const std::string& open_id, const std::string& name) {
+    return {{"key", key}, {"id", {{"open_id", open_id}}}, {"mentioned_type", "user"}, {"name", name}};
+}
+
+std::string event(const std::string& chat_type, const std::string& message_type, const nlohmann::json& content,
+                  const nlohmann::json& mentions = nullptr, std::int64_t create_time = 0,
+                  const std::string& sender_type = "user", const std::string& sender = "ou_user") {
+    nlohmann::json message{{"message_id", "om_1"},
+                           {"create_time", std::to_string(create_time ? create_time : now_ms())},
+                           {"chat_id", "oc_chat"},
+                           {"chat_type", chat_type},
+                           {"message_type", message_type},
+                           {"content", content.dump()}};
+    if (!mentions.is_null()) message["mentions"] = mentions;
+    return nlohmann::json{{"schema", "2.0"},
+                          {"header", {{"event_id", "e1"}, {"event_type", "im.message.receive_v1"}}},
+                          {"event", {{"sender", {{"sender_id", {{"open_id", sender}}}, {"sender_type", sender_type}}},
+                                     {"message", message}}}}
+        .dump();
+}
+
+Inbound parse_ok(const std::string& payload, const BotIdentity& bot = kBot) {
+    auto parsed = parse_event(payload, bot, "cli_app", now_ms());
+    EXPECT_EQ(parsed.disposition, EventDisposition::Message);
+    return parsed.inbound.value_or(Inbound{});
+}
+
+// 场景:用户选择“飞书”或“Lark”(含大小写与空白差异)。
+// 期望:lark → open.larksuite.com,其余(含空串)→ open.feishu.cn。
+TEST(FeishuProtocol, BaseForDomain) {
+    EXPECT_EQ(base_for_domain("lark"), kLarkBase);
+    EXPECT_EQ(base_for_domain(" LARK "), kLarkBase);
+    EXPECT_EQ(base_for_domain("feishu"), kFeishuBase);
+    EXPECT_EQ(base_for_domain(""), kFeishuBase);
+}
+
+// 场景:长连接地址接口成功返回 URL 与 ClientConfig。
+// 期望:取出 URL、device_id、service_id(int32),ClientConfig 原样保留以便应用。
+TEST(FeishuProtocol, ParsesEndpointSuccess) {
+    const auto body = nlohmann::json{
+        {"code", 0},
+        {"msg", "ok"},
+        {"data",
+         {{"URL", "wss://msg-frontier.feishu.cn/ws/v2?fpid=1&aid=2&device_id=7123&access_key=k&service_id="
+                  "33554678&ticket=t%2B1"},
+          {"ClientConfig", {{"ReconnectCount", -1}, {"ReconnectInterval", 120}, {"ReconnectNonce", 30},
+                            {"PingInterval", 90}}}}}};
+    const auto info = parse_endpoint_response(200, body.dump());
+    ASSERT_TRUE(info.ok) << info.message;
+    EXPECT_FALSE(info.fatal);
+    EXPECT_EQ(info.device_id, "7123");
+    EXPECT_EQ(info.service_id, 33554678);
+    EXPECT_EQ(url_query_param(info.url, "ticket"), "t+1");
+    ClientConfig config;
+    EXPECT_TRUE(apply_client_config(info.client_config, &config));
+    EXPECT_EQ(config.ping_interval_s, 90);
+}
+
+// 场景:长连接地址接口的各种失败 —— 原样抓包的凭据错误(HTTP 200 + code 1000040345)、
+// 服务繁忙(1、1000040343)、HTTP 500、code 0 但 URL 为空。
+// 期望:凭据错误是致命的,给出中文原因;其余都可重试。
+TEST(FeishuProtocol, ClassifiesEndpointFailures) {
+    const auto probe =
+        R"({"error":{"id":1000040345,"localizedMessage":{"locale":"zh","message":"app_id or app_secret is invalid"},"ErrX":null},"msg":"app_id or app_secret is invalid","data":{"URL":""},"code":1000040345})";
+    const auto bad = parse_endpoint_response(200, probe);
+    EXPECT_FALSE(bad.ok);
+    EXPECT_TRUE(bad.fatal);
+    EXPECT_NE(bad.message.find("App Secret"), std::string::npos) << bad.message;
+
+    for (const auto code : {1LL, 1000040343LL}) {
+        const auto busy = parse_endpoint_response(200, nlohmann::json{{"code", code}, {"msg", "busy"}}.dump());
+        EXPECT_FALSE(busy.ok);
+        EXPECT_FALSE(busy.fatal) << code;
+    }
+    EXPECT_FALSE(parse_endpoint_response(500, "oops").fatal);
+    const auto empty = parse_endpoint_response(200, R"({"code":0,"data":{"URL":""}})");
+    EXPECT_FALSE(empty.ok);
+    EXPECT_FALSE(empty.fatal);
+    const auto other = parse_endpoint_response(200, R"({"code":1000040344,"msg":"no credential"})");
+    EXPECT_TRUE(other.fatal);
+}
+
+// 场景:服务端只下发部分 ClientConfig 字段,或给出非法值(负的间隔、0 的心跳)。
+// 期望:只覆盖出现且合法的字段,其余保持默认。
+TEST(FeishuProtocol, ClientConfigOverridesOnlyValidFields) {
+    ClientConfig config;
+    EXPECT_TRUE(apply_client_config({{"PingInterval", 30}}, &config));
+    EXPECT_EQ(config.ping_interval_s, 30);
+    EXPECT_EQ(config.reconnect_interval_s, 120);
+    EXPECT_FALSE(apply_client_config({{"ReconnectInterval", -5}, {"PingInterval", 0}}, &config));
+    EXPECT_EQ(config.reconnect_interval_s, 120);
+    EXPECT_EQ(config.ping_interval_s, 30);
+    EXPECT_TRUE(apply_client_config({{"ReconnectCount", 3}, {"ReconnectNonce", 0}}, &config));
+    EXPECT_EQ(config.reconnect_count, 3);
+    EXPECT_EQ(config.reconnect_nonce_s, 0);
+}
+
+// 场景:WebSocket 升级失败时的 Handshake-Status / Handshake-Autherrcode 组合。
+// 期望:403 与 514+1000040350(连接数超限)致命;514 的其它错误码与拿不到头时都可重试。
+TEST(FeishuProtocol, ClassifiesHandshakeFailures) {
+    EXPECT_TRUE(classify_handshake(403, 403, 0).fatal);
+    EXPECT_TRUE(classify_handshake(400, 514, 1000040350).fatal);
+    EXPECT_FALSE(classify_handshake(400, 514, 123).fatal);
+    EXPECT_FALSE(classify_handshake(502, 0, 0).fatal);
+    EXPECT_FALSE(classify_handshake(0, 0, 0).message.empty());
+}
+
+// 场景:私聊里收到一条文本消息。
+// 期望:地址为私聊,chat = sender = 对方 open_id,account = App ID;私聊恒视为点名;
+// reply_context 带 message_id / chat_id / chat_type。
+TEST(FeishuProtocol, ParsesPrivateTextMessage) {
+    const auto inbound = parse_ok(event("p2p", "text", {{"text", "  你好\r\n世界  "}}));
+    EXPECT_EQ(inbound.address.platform, "feishu");
+    EXPECT_EQ(inbound.address.account, "cli_app");
+    EXPECT_EQ(inbound.address.kind, ChatKind::Private);
+    EXPECT_EQ(inbound.address.chat, "ou_user");
+    EXPECT_EQ(inbound.address.sender, "ou_user");
+    EXPECT_TRUE(inbound.mentioned);
+    EXPECT_EQ(inbound.text, "你好\n世界");
+    EXPECT_EQ(inbound.message_id, "om_1");
+    EXPECT_EQ(inbound.reply_context.value("message_id", ""), "om_1");
+    EXPECT_EQ(inbound.reply_context.value("chat_id", ""), "oc_chat");
+    EXPECT_EQ(inbound.reply_context.value("chat_type", ""), "p2p");
+}
+
+// 场景:群里 "@机器人 帮我看看"。
+// 期望:按 open_id 认出点名了机器人,mentioned = true;开头的 @ 去掉;地址为群 + 发言人。
+TEST(FeishuProtocol, GroupMentionOfBotIsDetectedAndStripped) {
+    const auto inbound =
+        parse_ok(event("group", "text", {{"text", "@_user_1 帮我看看"}}, nlohmann::json::array({bot_mention()})));
+    EXPECT_EQ(inbound.address.kind, ChatKind::Group);
+    EXPECT_EQ(inbound.address.chat, "oc_chat");
+    EXPECT_EQ(inbound.address.sender, "ou_user");
+    EXPECT_TRUE(inbound.mentioned);
+    EXPECT_EQ(inbound.text, "帮我看看");
+}
+
+// 场景:群消息只 @ 了别人,且机器人名字恰好与被 @ 的人相同(open_id 不同)。
+// 期望:open_id 不同就不算点名机器人(名字只是最后手段);被 @ 的人显示为 "@名字"。
+TEST(FeishuProtocol, MentionOfAnotherUserIsNotTheBot) {
+    const auto mentions = nlohmann::json::array({user_mention("@_user_1", "ou_tom", "TestBot")});
+    const auto inbound = parse_ok(event("group", "text", {{"text", "@_user_1 你好"}}, mentions));
+    EXPECT_FALSE(inbound.mentioned);
+    EXPECT_EQ(inbound.text, "@TestBot 你好");
+}
+
+// 场景:机器人的 @ 出现在句中、句尾(后跟全角问号)、以及 "@机器人, 帮忙" 这种带分隔符的开头。
+// 期望:句中保留为 "@机器人名",句尾去掉但保留标点,开头去掉并吃掉紧跟的逗号。
+TEST(FeishuProtocol, StripsBotMentionsOnlyAtEdges) {
+    const auto mentions = std::vector<Mention>{{"@_user_1", "ou_bot", "", "TestBot", "bot"}};
+    EXPECT_EQ(clean_text("别再 @_user_1 了", mentions, kBot), "别再 @TestBot 了");
+    EXPECT_EQ(clean_text("看一下 @_user_1\xEF\xBC\x9F", mentions, kBot), "看一下\xEF\xBC\x9F");
+    EXPECT_EQ(clean_text("@_user_1, 帮忙", mentions, kBot), "帮忙");
+    EXPECT_EQ(clean_text("@_user_1 @_user_1 两次", mentions, kBot), "两次");
+    // @_user_10 不能被当成 @_user_1 的前缀吃掉。
+    EXPECT_EQ(clean_text("@_user_10 hi", mentions, kBot), "hi");
+}
+
+// 场景:@所有人,以及 mentions 里查不到的占位符。
+// 期望:@所有人不算点名机器人(官方渠道 SDK 默认),文字里显示为 "@all";未知占位符换成空格。
+TEST(FeishuProtocol, AtAllAndUnknownPlaceholders) {
+    const auto inbound = parse_ok(
+        event("group", "text", {{"text", "@_all 开会"}}, nlohmann::json::array({{{"key", "@_all"}, {"name", "所有人"}}})));
+    EXPECT_FALSE(inbound.mentioned);
+    EXPECT_EQ(inbound.text, "@all 开会");
+    EXPECT_EQ(clean_text("a@_user_9b", {}, kBot), "a b");
+    EXPECT_EQ(clean_text("@_allx", {}, kBot), "@_allx");
+}
+
+// 场景:还没取到机器人身份(未发布版本时 bot/v3/info 不可用),群里 @ 了一个 mentioned_type=bot 的对象。
+// 期望:退化为按 mentioned_type 判定,仍算点名并去掉 @。
+TEST(FeishuProtocol, UnknownBotIdentityFallsBackToMentionType) {
+    const auto inbound = parse_ok(
+        event("group", "text", {{"text", "@_user_1 在吗"}}, nlohmann::json::array({bot_mention()})), BotIdentity{});
+    EXPECT_TRUE(inbound.mentioned);
+    EXPECT_EQ(inbound.text, "在吗");
+}
+
+// 场景:平台在重启后重投 31 分钟前的消息;另一条是 29 分钟前的。
+// 期望:超过 30 分钟的判为陈旧并丢弃,29 分钟的照常处理。
+TEST(FeishuProtocol, DropsStaleEvents) {
+    const auto stale = parse_event(event("p2p", "text", {{"text", "hi"}}, nullptr, now_ms() - 31 * 60 * 1000), kBot,
+                                   "cli_app", now_ms());
+    EXPECT_EQ(stale.disposition, EventDisposition::Stale);
+    EXPECT_EQ(stale.message_id, "om_1");
+    const auto fresh = parse_event(event("p2p", "text", {{"text", "hi"}}, nullptr, now_ms() - 29 * 60 * 1000), kBot,
+                                   "cli_app", now_ms());
+    EXPECT_EQ(fresh.disposition, EventDisposition::Message);
+}
+
+// 场景:机器人 / 应用发出的消息,以及机器人自己的回声;只有 "@机器人" 没有内容的消息。
+// 期望:前两者判为 FromBot,最后一个判为 Empty,都不交给核心。
+TEST(FeishuProtocol, IgnoresBotSendersAndBareMentions) {
+    EXPECT_EQ(parse_event(event("group", "text", {{"text", "hi"}}, nullptr, 0, "app"), kBot, "cli_app", now_ms())
+                  .disposition,
+              EventDisposition::FromBot);
+    EXPECT_EQ(parse_event(event("p2p", "text", {{"text", "hi"}}, nullptr, 0, "user", "ou_bot"), kBot, "cli_app",
+                          now_ms())
+                  .disposition,
+              EventDisposition::FromBot);
+    EXPECT_EQ(parse_event(event("group", "text", {{"text", "@_user_1"}}, nlohmann::json::array({bot_mention()})), kBot,
+                          "cli_app", now_ms())
+                  .disposition,
+              EventDisposition::Empty);
+}
+
+// 场景:其它事件类型、1.0 事件、损坏的 JSON。
+// 期望:前两者 Ignored(仍由传输层 ACK),损坏的 Invalid。
+TEST(FeishuProtocol, IgnoresOtherEvents) {
+    const auto reaction =
+        nlohmann::json{{"schema", "2.0"}, {"header", {{"event_type", "im.message.reaction.created_v1"}}}, {"event", {}}};
+    EXPECT_EQ(parse_event(reaction.dump(), kBot, "cli_app", now_ms()).disposition, EventDisposition::Ignored);
+    EXPECT_EQ(parse_event(R"({"type":"event_callback","uuid":"u","event":{}})", kBot, "cli_app", now_ms()).disposition,
+              EventDisposition::Ignored);
+    EXPECT_EQ(parse_event("{not json", kBot, "cli_app", now_ms()).disposition, EventDisposition::Invalid);
+}
+
+// 场景:post 富文本,含标题、普通文字、链接、@机器人、图片、代码块;同时测试外层包了 zh_cn 的形态。
+// 期望:文字按行拼接(@机器人 在开头被去掉),图片成为附件且下载定位指向这条消息、type=image;
+// 代码块还原成 ``` 围栏;两种形态结果一致。
+TEST(FeishuProtocol, ExtractsPostTextAndImages) {
+    const nlohmann::json post{
+        {"title", "周报"},
+        {"content",
+         nlohmann::json::array(
+             {nlohmann::json::array({{{"tag", "at"}, {"user_id", "@_user_1"}, {"user_name", ""}},
+                                     {{"tag", "text"}, {"text", " 看下"}},
+                                     {{"tag", "a"}, {"text", "文档"}, {"href", "https://a.b/c"}}}),
+              nlohmann::json::array({{{"tag", "img"}, {"image_key", "img_v3_1"}}}),
+              nlohmann::json::array({{{"tag", "code_block"}, {"language", "GO"}, {"text", "x := 1"}}})})}};
+    const auto mentions = nlohmann::json::array({bot_mention()});
+    for (const auto& content : {post, nlohmann::json{{"zh_cn", post}}}) {
+        const auto inbound = parse_ok(event("group", "post", content, mentions));
+        EXPECT_TRUE(inbound.mentioned);
+        EXPECT_EQ(inbound.text, "周报\n@TestBot 看下[文档](https://a.b/c)\n```go\nx := 1\n```");
+        ASSERT_EQ(inbound.attachments.size(), 1u);
+        EXPECT_EQ(inbound.attachments[0].kind, AttachmentKind::Image);
+        const auto ref = parse_resource_ref(inbound.attachments[0].remote_ref);
+        ASSERT_TRUE(ref.has_value());
+        EXPECT_EQ(ref->message_id, "om_1");
+        EXPECT_EQ(ref->key, "img_v3_1");
+        EXPECT_EQ(ref->type, "image");
+    }
+}
+
+// 场景:图片、文件、语音、视频、表情包、文件夹消息。
+// 期望:图片 / 文件 / 语音 / 视频成为对应种类的附件(文件保留原名,下载 type 分别为 image / file);
+// 表情包与文件夹无法下载,转成占位文字。
+TEST(FeishuProtocol, MediaMessagesBecomeAttachments) {
+    const auto image = extract_content("image", {{"image_key", "img_k"}}, "om_9");
+    ASSERT_EQ(image.attachments.size(), 1u);
+    EXPECT_EQ(image.attachments[0].kind, AttachmentKind::Image);
+    EXPECT_EQ(parse_resource_ref(image.attachments[0].remote_ref)->type, "image");
+
+    const auto file = extract_content("file", {{"file_key", "file_k"}, {"file_name", "报告.pdf"}}, "om_9");
+    ASSERT_EQ(file.attachments.size(), 1u);
+    EXPECT_EQ(file.attachments[0].kind, AttachmentKind::File);
+    EXPECT_EQ(file.attachments[0].name, "报告.pdf");
+    EXPECT_EQ(parse_resource_ref(file.attachments[0].remote_ref)->type, "file");
+
+    EXPECT_EQ(extract_content("audio", {{"file_key", "a"}, {"duration", 2000}}, "om_9").attachments.at(0).kind,
+              AttachmentKind::Voice);
+    EXPECT_EQ(extract_content("media", {{"file_key", "v"}, {"image_key", "c"}}, "om_9").attachments.at(0).kind,
+              AttachmentKind::Video);
+    const auto sticker = extract_content("sticker", {{"file_key", "s"}}, "om_9");
+    EXPECT_TRUE(sticker.attachments.empty());
+    EXPECT_FALSE(sticker.text.empty());
+    EXPECT_NE(extract_content("folder", {{"file_key", "f"}, {"file_name", "资料"}}, "om_9").text.find("资料"),
+              std::string::npos);
+}
+
+// 场景:卡片消息(interactive)的简化内容。
+// 期望:收集 title / text / content 字段的文字,按行拼接,去掉相邻重复。
+TEST(FeishuProtocol, FlattensInteractiveCards) {
+    const nlohmann::json card{
+        {"title", "审批"},
+        {"elements", nlohmann::json::array({nlohmann::json::array(
+                         {{{"tag", "text"}, {"text", "同意吗"}}, {{"tag", "text"}, {"text", "同意吗"}}})})}};
+    EXPECT_EQ(extract_content("interactive", card, "om_1").text, "审批\n同意吗");
+}
+
+// 场景:附件定位串被篡改或缺字段。
+// 期望:解析失败返回空,下载时给出中文原因而不是发出错误请求。
+TEST(FeishuProtocol, ResourceRefRejectsInvalidValues) {
+    EXPECT_TRUE(parse_resource_ref(make_resource_ref("om_1", "k", "file")).has_value());
+    EXPECT_FALSE(parse_resource_ref(make_resource_ref("om_1", "k", "video")).has_value());
+    EXPECT_FALSE(parse_resource_ref(make_resource_ref("", "k", "file")).has_value());
+    EXPECT_FALSE(parse_resource_ref("https://example.com/x").has_value());
+}
+
+// 场景:各种助手回复,判定是否按 Markdown 发送。
+// 期望:表格、标题、列表、分隔线、代码、粗体、删除线、下划线、斜体、链接、引用都判为 Markdown;
+// 普通句子、网址、"1.5 倍"、单个星号不判。
+TEST(FeishuProtocol, DetectsMarkdown) {
+    for (const char* text : {"| a | b |\n|---|---|\n| 1 | 2 |", "# 标题", "- 列表", "  * 列表", "1. 第一",
+                             "---", "```\ncode\n```", "用 `ls` 看", "这是 **重点** 内容", "~~删掉~~", "<u>下划线</u>",
+                             "*斜体*", "见 [文档](https://a.b)", "> 引用"}) {
+        EXPECT_TRUE(looks_like_markdown(text)) << text;
+    }
+    for (const char* text : {"你好,今天天气不错。", "https://example.com/a_b", "放大 1.5 倍", "3 * 4 = 12", "**",
+                             "#没有空格"}) {
+        EXPECT_FALSE(looks_like_markdown(text)) << text;
+    }
+}
+
+// 场景:带代码块的 Markdown 回复转成 post。
+// 期望:{"zh_cn":{"content":rows}}(没有外层 "post" 包装,否则 230001);代码块单独占一行 md 节点,
+// 前后正文各占一行;没有代码块时整段一个 md 节点。
+TEST(FeishuProtocol, BuildsPostWithIsolatedCodeBlocks) {
+    const auto post = build_post_content("说明\n```cpp\nint a;\n```\n结论");
+    ASSERT_TRUE(post.contains("zh_cn"));
+    EXPECT_FALSE(post.contains("post"));
+    const auto& rows = post["zh_cn"]["content"];
+    ASSERT_EQ(rows.size(), 3u);
+    EXPECT_EQ(rows[0][0]["tag"], "md");
+    EXPECT_EQ(rows[0][0]["text"], "说明");
+    EXPECT_EQ(rows[1][0]["text"], "```cpp\nint a;\n```");
+    EXPECT_EQ(rows[2][0]["text"], "结论");
+    const auto simple = build_post_content("**粗体**");
+    ASSERT_EQ(simple["zh_cn"]["content"].size(), 1u);
+    EXPECT_EQ(simple["zh_cn"]["content"][0][0]["text"], "**粗体**");
+    EXPECT_EQ(build_text_content("a\nb")["text"], "a\nb");
+}
+
+// 场景:超长回复与转义膨胀严重的回复(全是双引号:每个字符序列化后占 2 字节)。
+// 期望:每段不超过字符上限;每段 content 序列化后不超过字节上限;拼回去与原文一致。
+TEST(FeishuProtocol, SplitsByCharactersAndSerializedBytes) {
+    const std::string long_text(8000, 'x');
+    const auto chunks = split_outbound(long_text, false);
+    ASSERT_GE(chunks.size(), 3u);
+    for (const auto& chunk : chunks) EXPECT_LE(chunk.size(), kMaxTextChars);
+
+    const std::string quotes(3000, '"');
+    const auto pieces = split_outbound(quotes, false, 3500, 4096);
+    ASSERT_GE(pieces.size(), 2u);
+    std::string joined;
+    for (const auto& piece : pieces) {
+        EXPECT_LE(dump_json(build_text_content(piece)).size(), 4096u);
+        joined += piece;
+    }
+    EXPECT_EQ(joined, quotes);
+}
+
+// 场景:OpenAPI 的各种响应。
+// 期望:只有 2xx 且 code 0 才算成功;429 / 99991400 / 230020 为限流;网络错误、5xx 为临时错误;
+// 230001 或 "content format of the post type is incorrect" 为 post 被拒;令牌失效码与回复目标消失码可识别;
+// 错误描述为中文且不暴露内部字段。
+TEST(FeishuProtocol, ClassifiesApiResults) {
+    EXPECT_TRUE(parse_api_response(200, R"({"code":0,"msg":"success","data":{"message_id":"om"}})").ok);
+    EXPECT_EQ(parse_api_response(200, R"({"code":0,"data":{"message_id":"om"}})").data.value("message_id", ""), "om");
+    EXPECT_FALSE(parse_api_response(200, R"({"code":230013,"msg":"x"})").ok);
+    EXPECT_FALSE(parse_api_response(200, "not json").ok);
+
+    EXPECT_TRUE(is_rate_limited(parse_api_response(429, R"({"code":99991400})")));
+    EXPECT_TRUE(is_rate_limited(parse_api_response(400, R"({"code":230020})")));
+    EXPECT_TRUE(is_transient(parse_api_response(502, "")));
+    EXPECT_TRUE(is_transient(ApiResult{}));
+    EXPECT_FALSE(is_transient(parse_api_response(400, R"({"code":230013})")));
+    EXPECT_TRUE(is_post_rejected(parse_api_response(400, R"({"code":230001,"msg":"invalid param"})")));
+    EXPECT_TRUE(is_post_rejected(
+        parse_api_response(400, R"({"code":9,"msg":"The content format of the post type is incorrect"})")));
+    EXPECT_TRUE(is_token_invalid(99991663));
+    EXPECT_TRUE(is_token_invalid(99991661));
+    EXPECT_FALSE(is_token_invalid(230013));
+    EXPECT_TRUE(is_reply_target_gone(230011));
+    EXPECT_TRUE(is_reply_target_gone(231003));
+
+    EXPECT_NE(describe_error(parse_api_response(400, R"({"code":230013,"msg":"x"})")).find("可用范围"),
+              std::string::npos);
+    EXPECT_NE(describe_error(parse_api_response(400, R"({"code":99991672,"msg":"need im:message"})")).find(
+                  "im:message"),
+              std::string::npos);
+    EXPECT_NE(describe_error(parse_api_response(400, R"({"code":777,"msg":"boom"})")).find("777"), std::string::npos);
+    ApiResult network;
+    network.error = "Couldn't connect";
+    EXPECT_NE(describe_error(network).find("无法连接"), std::string::npos);
+}
+
+// 场景:限流响应头 x-ogw-ratelimit-reset 的各种取值,以及据此计算重发前的等待。
+// 期望:合法秒数原样取出(上限 1 小时),非法 / 缺失为 0;等待取本地退避与平台要求的较大者,
+// 平台要求封顶 60 秒(避免一条消息卡住整个会话太久)。
+TEST(FeishuProtocol, ComputesRateLimitWait) {
+    using std::chrono::milliseconds;
+    using std::chrono::seconds;
+    EXPECT_EQ(parse_retry_after(" 3 "), seconds(3));
+    EXPECT_EQ(parse_retry_after(""), seconds(0));
+    EXPECT_EQ(parse_retry_after("1.5"), seconds(0));
+    EXPECT_EQ(parse_retry_after("99999"), seconds(3600));
+    ApiResult limited;
+    limited.retry_after = seconds(5);
+    EXPECT_EQ(rate_limit_wait(limited, milliseconds(1000)), milliseconds(5000));
+    limited.retry_after = seconds(120);
+    EXPECT_EQ(rate_limit_wait(limited, milliseconds(1000)), milliseconds(60000));
+    limited.retry_after = seconds(0);
+    EXPECT_EQ(rate_limit_wait(limited, milliseconds(1000)), milliseconds(1000));
+}
+
+// 场景:换令牌接口返回的凭据错误码。
+// 期望:10014 提示确认飞书 / Lark;10015 提示 App Secret 不正确;其它带上平台原文与错误码。
+TEST(FeishuProtocol, DescribesTokenErrors) {
+    EXPECT_NE(describe_token_error(10014, "app id not exists").find("Lark"), std::string::npos);
+    EXPECT_NE(describe_token_error(10015, "wrong app secret").find("App Secret"), std::string::npos);
+    EXPECT_NE(describe_token_error(12345, "weird").find("12345"), std::string::npos);
+}
+
+// 场景:bot/v3/info 的三种形态 —— bot 在顶层、在 data 下、机器人未启用。
+// 期望:前两种都能取出 open_id 与名称;activate_status != 2 时 ready() 为 false 并有中文提示。
+TEST(FeishuProtocol, ParsesBotInfo) {
+    const auto top = parse_bot_info(
+        nlohmann::json::parse(R"({"code":0,"bot":{"activate_status":2,"app_name":"A","open_id":"ou_b"}})"));
+    EXPECT_TRUE(top.ready());
+    EXPECT_EQ(top.open_id, "ou_b");
+    EXPECT_EQ(top.name, "A");
+    const auto nested =
+        parse_bot_info(nlohmann::json::parse(R"({"code":0,"data":{"bot":{"activate_status":2,"open_id":"ou_c"}}})"));
+    EXPECT_EQ(nested.open_id, "ou_c");
+    const auto inactive =
+        parse_bot_info(nlohmann::json::parse(R"({"code":0,"bot":{"activate_status":0,"open_id":"ou_d"}})"));
+    EXPECT_TRUE(inactive.ok);
+    EXPECT_FALSE(inactive.ready());
+    EXPECT_FALSE(describe_activate_status(0).empty());
+    EXPECT_TRUE(describe_activate_status(2).empty());
+    EXPECT_FALSE(parse_bot_info(nlohmann::json::parse(R"({"code":99991672,"msg":"x"})")).ok);
+}
+
+// 场景:有回复上下文(群 / 私聊 / 话题)与没有回复上下文(Desktop 里输入的回复)时的出站目标。
+// 期望:有 chat_id 一律按 chat_id 发(私聊也有);没有时群按 chat_id = 群 id、私聊按 open_id = 对方 id;
+// 话题消息标记 in_thread;没有 message_id 时不回复。
+TEST(FeishuProtocol, SelectsSendTarget) {
+    Address group{"feishu", "cli_app", ChatKind::Group, "oc_g", "ou_u", ""};
+    Address dm{"feishu", "cli_app", ChatKind::Private, "ou_u", "ou_u", ""};
+    const auto with_context = send_target(dm, {{"message_id", "om_1"}, {"chat_id", "oc_p2p"}, {"chat_type", "p2p"}});
+    EXPECT_EQ(with_context.receive_id_type, "chat_id");
+    EXPECT_EQ(with_context.receive_id, "oc_p2p");
+    EXPECT_EQ(with_context.reply_to, "om_1");
+    EXPECT_FALSE(with_context.in_thread);
+    const auto plain_group = send_target(group, nlohmann::json::object());
+    EXPECT_EQ(plain_group.receive_id_type, "chat_id");
+    EXPECT_EQ(plain_group.receive_id, "oc_g");
+    EXPECT_TRUE(plain_group.reply_to.empty());
+    const auto plain_dm = send_target(dm, nullptr);
+    EXPECT_EQ(plain_dm.receive_id_type, "open_id");
+    EXPECT_EQ(plain_dm.receive_id, "ou_u");
+    EXPECT_TRUE(send_target(group, {{"message_id", "om_2"}, {"chat_id", "oc_g"}, {"thread_id", "omt_1"}}).in_thread);
+}
+
+// 场景:回传各种文件。
+// 期望:≤ 10 MB 的图片走图片接口;超过 10 MB 的图片按普通文件(stream);.opus → 语音,.mp4 → 视频,
+// pdf / Office 各自类型,其余 stream;上传类型与 msg_type 配套。
+TEST(FeishuProtocol, RoutesFilesForUpload) {
+    EXPECT_TRUE(route_file("a.png", "", 1000).image);
+    EXPECT_TRUE(route_file("photo", "image/jpeg", 1000).image);
+    const auto big = route_file("a.png", "image/png", 11u * 1024u * 1024u);
+    EXPECT_FALSE(big.image);
+    EXPECT_EQ(big.file_type, "stream");
+    EXPECT_EQ(big.msg_type, "file");
+    EXPECT_EQ(route_file("v.opus", "", 10).msg_type, "audio");
+    EXPECT_EQ(route_file("v.opus", "", 10).file_type, "opus");
+    EXPECT_EQ(route_file("m.MP4", "", 10).msg_type, "media");
+    EXPECT_EQ(route_file("r.pdf", "", 10).file_type, "pdf");
+    EXPECT_EQ(route_file("r.docx", "", 10).file_type, "doc");
+    EXPECT_EQ(route_file("r.xlsx", "", 10).file_type, "xls");
+    EXPECT_EQ(route_file("r.pptx", "", 10).file_type, "ppt");
+    EXPECT_EQ(route_file("r.zip", "", 10).file_type, "stream");
+    EXPECT_FALSE(route_file("vector.svg", "image/svg+xml", 10).image);
+}
+
+} // namespace
+} // namespace acecode::im::feishu
diff --git a/tests/im/feishu_transport_test.cpp b/tests/im/feishu_transport_test.cpp
new file mode 100644
index 000000000..21d0a370b
--- /dev/null
+++ b/tests/im/feishu_transport_test.cpp
@@ -0,0 +1,500 @@
+#include <gtest/gtest.h>
+
+#include "im/feishu/feishu_transport.hpp"
+#include "test_support/im/fake_feishu_server.hpp"
+
+#include <atomic>
+#include <filesystem>
+#include <fstream>
+#include <mutex>
+#include <vector>
+
+// im/feishu/feishu_transport:飞书传输层端到端测试。本机假开放平台提供令牌、机器人信息、
+// 长连接地址与二进制 WebSocket 长连接、发消息与上传下载接口;测试覆盖连接与心跳、事件 ACK、
+// 私聊 / 群 @ / 去重 / 陈旧丢弃 / 拆包、回复与分段、post → 纯文本回退、限流重发、
+// 回复目标消失、断线重连、致命错误停止重试、文件收发与 close 帧。
+
+namespace acecode::im::feishu {
+namespace {
+
+using std::chrono::milliseconds;
+using test::FakeFeishuServer;
+
+FeishuTransportOptions local_options(const FakeFeishuServer& server) {
+    FeishuTransportOptions options;
+    options.api.app_id = "cli_app";
+    options.api.app_secret = "secret-value-123";
+    options.api.base = server.base();
+    options.api.use_proxy = false;
+    options.backoff = {milliseconds(50)};
+    options.rate_limit_backoff = {milliseconds(50), milliseconds(50)};
+    options.retry_backoff = {milliseconds(20)};
+    options.send_gap = milliseconds(1);
+    options.receive_poll = milliseconds(50);
+    return options;
+}
+
+struct Recorder {
+    std::mutex mu;
+    std::vector<Inbound> inbound;
+    std::vector<TransportStatus> statuses;
+    TransportCallbacks callbacks() {
+        TransportCallbacks cb;
+        cb.on_inbound = [this](Inbound in) {
+            std::lock_guard<std::mutex> lock(mu);
+            inbound.push_back(std::move(in));
+        };
+        cb.on_status = [this](const TransportStatus& s) {
+            std::lock_guard<std::mutex> lock(mu);
+            statuses.push_back(s);
+        };
+        return cb;
+    }
+    std::size_t inbound_count() {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.size();
+    }
+    Inbound inbound_at(std::size_t i) {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.at(i);
+    }
+    std::vector<TransportStatus> all_statuses() {
+        std::lock_guard<std::mutex> lock(mu);
+        return statuses;
+    }
+};
+
+bool wait_connected(FeishuTransport& transport, FakeFeishuServer& server, int connections = 1) {
+    return FakeFeishuServer::wait_until([&] {
+        return transport.status().state == LinkState::Connected && server.connections() >= connections;
+    });
+}
+
+nlohmann::json p2p_text(const std::string& id, const std::string& text) {
+    return FakeFeishuServer::message_event(id, "p2p", "oc_p2p", "ou_user", "text", {{"text", text}});
+}
+
+nlohmann::json bot_mention() {
+    return nlohmann::json::array(
+        {{{"key", "@_user_1"}, {"id", {{"open_id", "ou_bot"}}}, {"mentioned_type", "bot"}, {"name", "TestBot"}}});
+}
+
+nlohmann::json content_of(const FakeFeishuServer::Request& request) {
+    return nlohmann::json::parse(request.body.value("content", std::string("{}")));
+}
+
+std::filesystem::path temp_file(const char* name, const std::string& data) {
+    const auto path = std::filesystem::path(testing::TempDir()) / name;
+    std::ofstream(path, std::ios::binary) << data;
+    return path;
+}
+
+// 场景:开启飞书通道,长连接建立后收到一条私聊文本。
+// 期望:先换令牌、取机器人信息,再用 AppID / AppSecret(PascalCase、locale: zh、带 channel 的 UA)
+// 请求长连接地址;连上即发心跳(带地址里的 service_id);状态为已连接并显示机器人名;事件帧被
+// 原样回显 ACK({"code":200}、带 biz_rt、instance_id 不变);入站消息地址、文本与回复上下文正确;
+// 状态里不出现长连接票据与密钥;停止后状态为已停止。
+TEST(FeishuTransport, ConnectsAcksAndDeliversPrivateMessage) {
+    FakeFeishuServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    FeishuTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport, server));
+    const auto status = transport.status();
+    EXPECT_EQ(status.display_name, "TestBot");
+    EXPECT_EQ(status.account, "cli_app");
+    EXPECT_EQ(status.extra.value("bot_ready", false), true);
+    EXPECT_EQ(transport.bot().open_id, "ou_bot");
+
+    const auto endpoint = server.requests_to("/callback/ws/endpoint");
+    ASSERT_EQ(endpoint.size(), 1u);
+    EXPECT_EQ(endpoint[0].body.value("AppID", ""), "cli_app");
+    EXPECT_EQ(endpoint[0].locale, "zh");
+    EXPECT_NE(endpoint[0].user_agent.find(" channel"), std::string::npos);
+
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return !server.frames_of_type("ping").empty(); }));
+    EXPECT_EQ(server.frames_of_type("ping")[0].service, 1234);
+    EXPECT_EQ(server.text_frames(), 0);
+
+    server.push_event(p2p_text("om_1", "你好"));
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return recorder.inbound_count() == 1; }));
+    const auto inbound = recorder.inbound_at(0);
+    EXPECT_EQ(inbound.address.kind, ChatKind::Private);
+    EXPECT_EQ(inbound.address.chat, "ou_user");
+    EXPECT_EQ(inbound.address.sender, "ou_user");
+    EXPECT_EQ(inbound.address.account, "cli_app");
+    EXPECT_TRUE(inbound.mentioned);
+    EXPECT_EQ(inbound.text, "你好");
+    EXPECT_EQ(inbound.reply_context.value("message_id", ""), "om_1");
+    EXPECT_EQ(inbound.reply_context.value("chat_id", ""), "oc_p2p");
+
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return server.frames_of_type("event").size() == 1; }));
+    const auto ack = server.frames_of_type("event")[0];
+    EXPECT_EQ(ack.method, kMethodData);
+    EXPECT_EQ(ack.header("instance_id"), "inst-1");
+    EXPECT_TRUE(ack.has_header("biz_rt"));
+    EXPECT_EQ(ack.payload.value_or(""), R"({"code":200})");
+
+    for (const auto& s : recorder.all_statuses()) {
+        EXPECT_EQ(s.detail.find("TICKET-SECRET"), std::string::npos);
+        EXPECT_EQ(s.detail.find("secret-value-123"), std::string::npos);
+    }
+    transport.stop();
+    EXPECT_EQ(transport.status().state, LinkState::Stopped);
+}
+
+// 场景:群里依次收到 —— @机器人 的消息、同一条消息的重投、不 @ 机器人的消息、2 小时前的旧消息。
+// 期望:@ 的消息 mentioned=true 且去掉了 @;重投只交给核心一次;不 @ 的消息 mentioned=false
+// (是否响应由核心决定);旧消息被丢弃。四个事件帧全部 ACK(包括重复与丢弃的),避免平台重投。
+TEST(FeishuTransport, GroupMentionsDedupeAndStaleEvents) {
+    FakeFeishuServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    FeishuTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport, server));
+    const auto mentioned = FakeFeishuServer::message_event("om_g1", "group", "oc_group", "ou_user", "text",
+                                                           {{"text", "@_user_1 看看日志"}}, bot_mention());
+    server.push_event(mentioned);
+    server.push_event(mentioned);
+    server.push_event(FakeFeishuServer::message_event("om_g2", "group", "oc_group", "ou_other", "text",
+                                                      {{"text", "大家好"}}));
+    const auto two_hours_ago = std::chrono::duration_cast<milliseconds>(
+                                   std::chrono::system_clock::now().time_since_epoch())
+                                   .count() -
+                               2 * 3600 * 1000;
+    server.push_event(FakeFeishuServer::message_event("om_old", "p2p", "oc_p2p", "ou_user", "text", {{"text", "旧"}},
+                                                      nullptr, two_hours_ago));
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return server.frames_of_type("event").size() == 4; }));
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return recorder.inbound_count() == 2; }));
+    std::this_thread::sleep_for(milliseconds(200));
+    EXPECT_EQ(recorder.inbound_count(), 2u);
+    const auto first = recorder.inbound_at(0);
+    EXPECT_EQ(first.address.kind, ChatKind::Group);
+    EXPECT_EQ(first.address.chat, "oc_group");
+    EXPECT_EQ(first.address.sender, "ou_user");
+    EXPECT_TRUE(first.mentioned);
+    EXPECT_EQ(first.text, "看看日志");
+    const auto second = recorder.inbound_at(1);
+    EXPECT_FALSE(second.mentioned);
+    EXPECT_EQ(second.address.sender, "ou_other");
+}
+
+// 场景:一个事件被服务端拆成 3 片推送。
+// 期望:重组成一条入站消息;只对凑齐的最后一片回 ACK(共 1 个)。
+TEST(FeishuTransport, ReassemblesSplitEvents) {
+    FakeFeishuServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    FeishuTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport, server));
+    server.push_event(p2p_text("om_split", std::string(300, 'x')), 3);
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return recorder.inbound_count() == 1; }));
+    EXPECT_EQ(recorder.inbound_at(0).text, std::string(300, 'x'));
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return server.frames_of_type("event").size() == 1; }));
+    std::this_thread::sleep_for(milliseconds(150));
+    EXPECT_EQ(server.frames_of_type("event").size(), 1u);
+}
+
+// 场景:对一条私聊消息回复一段超过单条上限的 Markdown。
+// 期望:整条按 post 发送;第一段走回复接口(回复触发消息),之后的分段按 chat_id 直接发到会话;
+// 每段 content 是 {"zh_cn":{"content":[[{"tag":"md",…}]]}};每次请求带 uuid。
+TEST(FeishuTransport, RepliesToTriggerThenCreatesLaterChunks) {
+    FakeFeishuServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    FeishuTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport, server));
+    server.push_event(p2p_text("om_1", "写个报告"));
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return recorder.inbound_count() == 1; }));
+    const auto inbound = recorder.inbound_at(0);
+
+    std::string text = "# 报告\n\n";
+    for (int i = 0; i < 80; ++i) text += "第 " + std::to_string(i) + " 段:" + std::string(60, 'x') + "\n\n";
+    const auto result = transport.send_text(inbound.address, text, inbound.reply_context);
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto sends = server.sends();
+    ASSERT_GE(sends.size(), 2u);
+    EXPECT_EQ(sends[0].path, "/open-apis/im/v1/messages/om_1/reply");
+    EXPECT_EQ(sends[0].body.value("msg_type", ""), "post");
+    EXPECT_FALSE(sends[0].body.value("uuid", "").empty());
+    const auto content = content_of(sends[0]);
+    EXPECT_EQ(content["zh_cn"]["content"][0][0]["tag"], "md");
+    EXPECT_NE(content["zh_cn"]["content"][0][0]["text"].get<std::string>().find("# 报告"), std::string::npos);
+    for (std::size_t i = 1; i < sends.size(); ++i) {
+        EXPECT_EQ(sends[i].path, "/open-apis/im/v1/messages");
+        EXPECT_EQ(sends[i].query, "chat_id");
+        EXPECT_EQ(sends[i].body.value("receive_id", ""), "oc_p2p");
+        EXPECT_EQ(sends[i].body.value("msg_type", ""), "post");
+    }
+    EXPECT_EQ(sends[0].authorization, "Bearer t-1");
+}
+
+// 场景:平台拒收 post(230001,"content format of the post type is incorrect")。
+// 期望:同一段改为纯文本(去掉 Markdown 标记)重发成功,结果为已发送;不重试同一个 post。
+TEST(FeishuTransport, FallsBackToPlainTextWhenPostIsRejected) {
+    FakeFeishuServer server;
+    server.message_handler = [](const FakeFeishuServer::Request& r) {
+        if (r.body.value("msg_type", "") == "post")
+            return std::make_pair(400, nlohmann::json{{"code", 230001},
+                                                      {"msg", "The content format of the post type is incorrect"}});
+        return std::make_pair(200, nlohmann::json{{"code", 0}, {"data", {{"message_id", "om_r"}}}});
+    };
+    FeishuTransport transport(local_options(server));
+    const Address dm{"feishu", "cli_app", ChatKind::Private, "ou_user", "ou_user", ""};
+    const auto result = transport.send_text(dm, "**粗体**", nlohmann::json::object());
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto sends = server.sends();
+    ASSERT_EQ(sends.size(), 2u);
+    EXPECT_EQ(sends[0].body.value("msg_type", ""), "post");
+    EXPECT_EQ(sends[1].body.value("msg_type", ""), "text");
+    EXPECT_EQ(content_of(sends[1]).value("text", ""), "粗体");
+}
+
+// 场景:Desktop 里输入的回复,没有回复上下文;分别发往群与私聊。
+// 期望:群按 receive_id_type=chat_id 发到群 id,私聊按 open_id 发到对方;普通文字用 text 类型。
+TEST(FeishuTransport, SendsToAddressWithoutReplyContext) {
+    FakeFeishuServer server;
+    FeishuTransport transport(local_options(server));
+    const Address group{"feishu", "cli_app", ChatKind::Group, "oc_group", "ou_user", ""};
+    const Address dm{"feishu", "cli_app", ChatKind::Private, "ou_user", "ou_user", ""};
+    EXPECT_EQ(transport.send_text(group, "hello", nlohmann::json::object()).outcome, SendOutcome::Sent);
+    EXPECT_EQ(transport.send_text(dm, "hi", nullptr).outcome, SendOutcome::Sent);
+    const auto sends = server.sends();
+    ASSERT_EQ(sends.size(), 2u);
+    EXPECT_EQ(sends[0].query, "chat_id");
+    EXPECT_EQ(sends[0].body.value("receive_id", ""), "oc_group");
+    EXPECT_EQ(sends[0].body.value("msg_type", ""), "text");
+    EXPECT_EQ(content_of(sends[0]).value("text", ""), "hello");
+    EXPECT_EQ(sends[1].query, "open_id");
+    EXPECT_EQ(sends[1].body.value("receive_id", ""), "ou_user");
+}
+
+// 场景:第一次发送被限流(HTTP 429 + 99991400),第二次成功。
+// 期望:等待后重发同一请求(uuid 不变,平台据此去重),结果为已发送;消息不丢。
+TEST(FeishuTransport, RetriesRateLimitedSendsWithSameUuid) {
+    FakeFeishuServer server;
+    std::atomic<int> calls{0};
+    server.message_handler = [&calls](const FakeFeishuServer::Request&) {
+        if (calls++ == 0)
+            return std::make_pair(429, nlohmann::json{{"code", 99991400}, {"msg", "request trigger frequency limit"}});
+        return std::make_pair(200, nlohmann::json{{"code", 0}, {"data", {{"message_id", "om_r"}}}});
+    };
+    FeishuTransport transport(local_options(server));
+    const Address group{"feishu", "cli_app", ChatKind::Group, "oc_group", "ou_user", ""};
+    EXPECT_EQ(transport.send_text(group, "排队的消息", nullptr).outcome, SendOutcome::Sent);
+    const auto sends = server.sends();
+    ASSERT_EQ(sends.size(), 2u);
+    EXPECT_EQ(sends[0].body.value("uuid", "a"), sends[1].body.value("uuid", "b"));
+}
+
+// 场景:要回复的那条消息已被撤回(230011)。
+// 期望:改为按 chat_id 直接发到会话,结果为已发送。
+TEST(FeishuTransport, FallsBackToCreateWhenReplyTargetIsGone) {
+    FakeFeishuServer server;
+    server.message_handler = [](const FakeFeishuServer::Request& r) {
+        if (r.path.find("/reply") != std::string::npos)
+            return std::make_pair(400, nlohmann::json{{"code", 230011}, {"msg", "message recalled"}});
+        return std::make_pair(200, nlohmann::json{{"code", 0}, {"data", {{"message_id", "om_r"}}}});
+    };
+    FeishuTransport transport(local_options(server));
+    const Address group{"feishu", "cli_app", ChatKind::Group, "oc_group", "ou_user", ""};
+    const auto result = transport.send_text(
+        group, "结果", {{"message_id", "om_x"}, {"chat_id", "oc_group"}, {"chat_type", "group"}});
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto sends = server.sends();
+    ASSERT_EQ(sends.size(), 2u);
+    EXPECT_EQ(sends[0].path, "/open-apis/im/v1/messages/om_x/reply");
+    EXPECT_EQ(sends[1].path, "/open-apis/im/v1/messages");
+    EXPECT_EQ(sends[1].body.value("receive_id", ""), "oc_group");
+}
+
+// 场景:平台明确拒绝(对方不在应用可用范围内,230013)。
+// 期望:不重试,结果为失败并给出中文原因。
+TEST(FeishuTransport, ReportsPermanentSendErrors) {
+    FakeFeishuServer server;
+    server.message_handler = [](const FakeFeishuServer::Request&) {
+        return std::make_pair(400, nlohmann::json{{"code", 230013}, {"msg", "Bot has NO availability to this user."}});
+    };
+    FeishuTransport transport(local_options(server));
+    const Address dm{"feishu", "cli_app", ChatKind::Private, "ou_user", "ou_user", ""};
+    const auto result = transport.send_text(dm, "hi", nullptr);
+    EXPECT_EQ(result.outcome, SendOutcome::Failed);
+    EXPECT_NE(result.error.find("可用范围"), std::string::npos) << result.error;
+    EXPECT_EQ(server.sends().size(), 1u);
+}
+
+// 场景:服务端主动关闭长连接。
+// 期望:重新请求长连接地址(旧地址不复用)并重连,回到已连接;新连接上的消息照常收到。
+TEST(FeishuTransport, ReconnectsWithFreshEndpointAfterServerClose) {
+    FakeFeishuServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    FeishuTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport, server));
+    server.close_connection(1000);
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return server.connections() == 2; }));
+    ASSERT_TRUE(wait_connected(transport, server, 2));
+    EXPECT_EQ(server.endpoint_calls(), 2);
+    server.push_event(p2p_text("om_after", "又连上了"));
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return recorder.inbound_count() == 1; }));
+}
+
+// 场景:长连接地址接口第一次 HTTP 500(平台繁忙),第二次正常。
+// 期望:按退避重试,最终连上;共请求两次地址。
+TEST(FeishuTransport, RetriesTransientEndpointFailures) {
+    FakeFeishuServer server;
+    std::atomic<int> calls{0};
+    server.endpoint_handler = [&calls, &server](const FakeFeishuServer::Request&) {
+        if (calls++ == 0) return std::make_pair(500, nlohmann::json{{"msg", "system busy"}});
+        return std::make_pair(200, nlohmann::json{{"code", 0},
+                                                  {"data", {{"URL", server.ws_url()},
+                                                            {"ClientConfig", server.client_config}}}});
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    FeishuTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport, server));
+    EXPECT_EQ(server.endpoint_calls(), 2);
+    bool retried = false;
+    for (const auto& s : recorder.all_statuses()) retried = retried || s.state == LinkState::Retrying;
+    EXPECT_TRUE(retried);
+}
+
+// 场景:长连接地址接口以 1000040345 拒绝(App ID / App Secret 无效,或选错了飞书 / Lark)。
+// 期望:状态为失败且停止重试,原因是中文且不含密钥;之后不再请求地址、不建立连接。
+TEST(FeishuTransport, EndpointCredentialErrorStopsRetrying) {
+    FakeFeishuServer server;
+    server.endpoint_handler = [](const FakeFeishuServer::Request&) {
+        return std::make_pair(200, nlohmann::json{{"code", 1000040345}, {"msg", "app_id or app_secret is invalid"},
+                                                  {"data", {{"URL", ""}}}});
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    FeishuTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return transport.status().state == LinkState::Failed; }));
+    const auto status = transport.status();
+    EXPECT_TRUE(status.retry_stopped);
+    EXPECT_NE(status.detail.find("App Secret"), std::string::npos) << status.detail;
+    EXPECT_EQ(status.detail.find("secret-value-123"), std::string::npos);
+    std::this_thread::sleep_for(milliseconds(300));
+    EXPECT_EQ(server.endpoint_calls(), 1);
+    EXPECT_EQ(server.connections(), 0);
+}
+
+// 场景:换令牌接口返回 10014(App ID 不存在,常见于把飞书应用配成了 Lark)。
+// 期望:不请求长连接地址,状态直接为失败且停止重试,提示确认飞书 / Lark。
+TEST(FeishuTransport, InvalidAppIdStopsRetrying) {
+    FakeFeishuServer server;
+    server.token_handler = [](const FakeFeishuServer::Request&) {
+        return std::make_pair(200, nlohmann::json{{"code", 10014}, {"msg", "app id not exists"}});
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    FeishuTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return transport.status().state == LinkState::Failed; }));
+    EXPECT_TRUE(transport.status().retry_stopped);
+    EXPECT_NE(transport.status().detail.find("Lark"), std::string::npos);
+    EXPECT_EQ(server.endpoint_calls(), 0);
+}
+
+// 场景:回传一张 PNG 与一个中文名的 PDF。
+// 期望:图片先走图片上传(image_type=message)再以 image 消息发送;PDF 走文件上传
+// (file_type=pdf,file_name 字段保留中文原名)再以 file 消息发送。
+TEST(FeishuTransport, SendsImagesAndFiles) {
+    FakeFeishuServer server;
+    FeishuTransport transport(local_options(server));
+    const Address dm{"feishu", "cli_app", ChatKind::Private, "ou_user", "ou_user", ""};
+    const auto png = temp_file("acecode-feishu-pic.png", "PNGDATA");
+    const auto pdf = temp_file("acecode-feishu-report.pdf", "PDFDATA");
+    EXPECT_EQ(transport.send_file(dm, png, "pic.png", "image/png", nullptr).outcome, SendOutcome::Sent);
+    EXPECT_EQ(transport.send_file(dm, pdf, "报告.pdf", "application/pdf", nullptr).outcome, SendOutcome::Sent);
+
+    const auto images = server.requests_to("/open-apis/im/v1/images");
+    ASSERT_EQ(images.size(), 1u);
+    EXPECT_NE(images[0].raw.find("image_type"), std::string::npos);
+    EXPECT_NE(images[0].raw.find("PNGDATA"), std::string::npos);
+    const auto files = server.requests_to("/open-apis/im/v1/files");
+    ASSERT_EQ(files.size(), 1u);
+    EXPECT_NE(files[0].raw.find("file_type"), std::string::npos);
+    EXPECT_NE(files[0].raw.find("报告.pdf"), std::string::npos);
+
+    const auto sends = server.sends();
+    ASSERT_EQ(sends.size(), 2u);
+    EXPECT_EQ(sends[0].body.value("msg_type", ""), "image");
+    EXPECT_EQ(content_of(sends[0]).value("image_key", ""), "img_v3_up");
+    EXPECT_EQ(sends[1].body.value("msg_type", ""), "file");
+    EXPECT_EQ(content_of(sends[1]).value("file_key", ""), "file_v3_up");
+    std::filesystem::remove(png);
+    std::filesystem::remove(pdf);
+}
+
+// 场景:要回传的文件超过上传上限(测试里把上限调到 4 字节),以及空文件。
+// 期望:超限时不上传,改发一条带文件名的文字说明;空文件直接失败并说明原因。
+TEST(FeishuTransport, OversizedFileBecomesTextNotice) {
+    FakeFeishuServer server;
+    auto options = local_options(server);
+    options.max_upload_bytes = 4;
+    FeishuTransport transport(options);
+    const Address dm{"feishu", "cli_app", ChatKind::Private, "ou_user", "ou_user", ""};
+    const auto big = temp_file("acecode-feishu-big.pdf", "PDF-DATA");
+    EXPECT_EQ(transport.send_file(dm, big, "big.pdf", "application/pdf", nullptr).outcome, SendOutcome::Sent);
+    EXPECT_TRUE(server.requests_to("/open-apis/im/v1/files").empty());
+    const auto sends = server.sends();
+    ASSERT_EQ(sends.size(), 1u);
+    EXPECT_NE(sends[0].body.dump().find("big.pdf"), std::string::npos);
+    const auto empty = temp_file("acecode-feishu-empty.txt", "");
+    EXPECT_EQ(transport.send_file(dm, empty, "empty.txt", "text/plain", nullptr).outcome, SendOutcome::Failed);
+    std::filesystem::remove(big);
+    std::filesystem::remove(empty);
+}
+
+// 场景:收到一条图片消息,核心随后下载附件;另有一个附件超过本地下载上限。
+// 期望:入站附件为图片;按“消息 id + image_key + type=image”下载成功;超限的直接失败并给出中文原因。
+TEST(FeishuTransport, DownloadsInboundAttachments) {
+    FakeFeishuServer server;
+    auto options = local_options(server);
+    options.max_download_bytes = 1024;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    FeishuTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport, server));
+    server.push_event(FakeFeishuServer::message_event("om_img", "p2p", "oc_p2p", "ou_user", "image",
+                                                      {{"image_key", "img_k"}}));
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return recorder.inbound_count() == 1; }));
+    const auto inbound = recorder.inbound_at(0);
+    ASSERT_EQ(inbound.attachments.size(), 1u);
+    EXPECT_EQ(inbound.attachments[0].kind, AttachmentKind::Image);
+    const auto dest = std::filesystem::path(testing::TempDir()) / "acecode-feishu-in.bin";
+    std::string error;
+    ASSERT_TRUE(transport.download(inbound.attachments[0], dest, &error)) << error;
+    EXPECT_EQ(std::filesystem::file_size(dest), 16u);
+    const auto downloads = server.requests_to("/open-apis/im/v1/messages/om_img/resources/img_k");
+    ASSERT_EQ(downloads.size(), 1u);
+    EXPECT_EQ(downloads[0].query, "image");
+
+    Attachment big = inbound.attachments[0];
+    big.remote_ref = make_resource_ref("om_img", "big", "file");
+    EXPECT_FALSE(transport.download(big, dest, &error));
+    EXPECT_NE(error.find("超过"), std::string::npos) << error;
+    Attachment broken;
+    broken.remote_ref = "not-a-ref";
+    EXPECT_FALSE(transport.download(broken, dest, &error));
+    std::filesystem::remove(dest);
+}
+
+// 场景:用户关闭通道。
+// 期望:stop() 返回前向服务端发出 close 帧(状态码 1000)。回归意义:不发 close 帧时飞书会把
+// 连接当作仍在线,继续把消息随机分给这条死连接,通道整段时间“收不到消息”(hermes #10202)。
+TEST(FeishuTransport, StopSendsCloseFrame) {
+    FakeFeishuServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    FeishuTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport, server));
+    transport.stop();
+    ASSERT_TRUE(FakeFeishuServer::wait_until([&] { return !server.close_codes().empty(); }));
+    EXPECT_EQ(server.close_codes()[0], 1000);
+}
+
+} // namespace
+} // namespace acecode::im::feishu
diff --git a/tests/im/line_api_test.cpp b/tests/im/line_api_test.cpp
new file mode 100644
index 000000000..1c23a0553
--- /dev/null
+++ b/tests/im/line_api_test.cpp
@@ -0,0 +1,211 @@
+#include <gtest/gtest.h>
+
+#include "im/line/line_api.hpp"
+#include "im/line/line_tunnel.hpp"
+#include "test_support/im/fake_line_server.hpp"
+
+#include <filesystem>
+#include <fstream>
+#include <iterator>
+#include <regex>
+
+// im/line/line_api:LINE API 客户端(本机假 LINE 服务)。
+// 覆盖:无状态令牌换取与缓存、401 后重换一次、凭据无效、长期令牌、联网校验三种结果、
+// webhook 地址未设置、附件下载(正常 / 超限 / 撤回 / 转码中)、重试键格式。
+
+namespace acecode::im::line {
+namespace {
+
+using test::FakeLineServer;
+
+ApiOptions local_options(const FakeLineServer& server) {
+    ApiOptions options;
+    options.channel_id = FakeLineServer::kChannelId;
+    options.channel_secret = FakeLineServer::kSecret;
+    options.api_base = server.base();
+    options.data_api_base = server.base();
+    options.use_proxy = false;
+    options.timeout = std::chrono::seconds(5);
+    options.transcoding_poll = std::chrono::milliseconds(20);
+    return options;
+}
+
+std::filesystem::path temp_file(const std::string& name) {
+    return std::filesystem::temp_directory_path() / ("acecode-line-api-" + name);
+}
+
+// 场景:连续两次调用接口。
+// 期望:第一次用 Channel ID + secret 换一个无状态令牌(表单字段正确),第二次直接复用缓存,
+// 不会每次都换令牌。
+TEST(LineApi, MintsStatelessTokenOnceAndCachesIt) {
+    FakeLineServer server;
+    Api api(local_options(server));
+    BotInfo bot;
+    ASSERT_TRUE(api.bot_info(&bot).ok);
+    EXPECT_EQ(bot.user_id, FakeLineServer::kBotId);
+    EXPECT_EQ(bot.basic_id, "@216ruabc");
+    EXPECT_EQ(bot.display_name, u8"ACE 测试机器人");
+    ASSERT_TRUE(api.bot_info(&bot).ok);
+    EXPECT_EQ(server.mint_count(), 1);
+    const auto mints = server.calls_to("POST", "/oauth2/v3/token");
+    ASSERT_EQ(mints.size(), 1u);
+    EXPECT_EQ(mints[0].body.value("grant_type", ""), "client_credentials");
+    EXPECT_EQ(mints[0].body.value("client_id", ""), FakeLineServer::kChannelId);
+    EXPECT_EQ(server.calls_to("GET", "/v2/bot/info")[0].authorization, "Bearer stateless-1");
+}
+
+// 场景:平台提前作废了缓存的无状态令牌,下一次调用收到 401。
+// 期望:自动重换一次令牌并重试成功,调用方看不到 401。
+TEST(LineApi, RemintsOnceAfter401) {
+    FakeLineServer server;
+    Api api(local_options(server));
+    BotInfo bot;
+    ASSERT_TRUE(api.bot_info(&bot).ok);
+    server.revoke_tokens();
+    const auto result = api.bot_info(&bot);
+    EXPECT_TRUE(result.ok);
+    EXPECT_EQ(server.mint_count(), 2);
+}
+
+// 场景:Channel secret 填错。
+// 期望:换令牌被 400 拒绝,结果标 auth_failed,给出中文原因且不含 secret。
+TEST(LineApi, InvalidChannelCredentialsAreAuthFailures) {
+    FakeLineServer server;
+    auto options = local_options(server);
+    options.channel_secret = "ffffffffffffffffffffffffffffffff";
+    Api api(options);
+    BotInfo bot;
+    const auto result = api.bot_info(&bot);
+    EXPECT_FALSE(result.ok);
+    EXPECT_TRUE(result.auth_failed);
+    EXPECT_NE(result.message.find("Channel ID 或 Channel secret 无效"), std::string::npos);
+    EXPECT_EQ(result.message.find(options.channel_secret), std::string::npos);
+}
+
+// 场景:用户粘贴了长期令牌;之后该令牌被重新签发(旧的失效)。
+// 期望:直接用长期令牌,不换取无状态令牌;失效后 401 即判凭据失效,不重试换令牌。
+TEST(LineApi, LongLivedTokenIsUsedDirectly) {
+    FakeLineServer server;
+    server.long_lived_token = "long-lived-token-abcdef";
+    auto options = local_options(server);
+    options.access_token = server.long_lived_token;
+    Api api(options);
+    BotInfo bot;
+    ASSERT_TRUE(api.bot_info(&bot).ok);
+    EXPECT_EQ(server.mint_count(), 0);
+    EXPECT_EQ(server.calls_to("GET", "/v2/bot/info")[0].authorization, "Bearer long-lived-token-abcdef");
+
+    Api stale([&options] {
+        auto copy = options;
+        copy.access_token = "revoked-token-123456";
+        return copy;
+    }());
+    const auto result = stale.bot_info(&bot);
+    EXPECT_TRUE(result.auth_failed);
+    EXPECT_NE(result.message.find("Channel access token"), std::string::npos);
+    EXPECT_EQ(server.mint_count(), 0);
+}
+
+// 场景:保存凭据前的联网校验:正确凭据、错误 secret、缺 secret、服务不可达。
+// 期望:正确时给出机器人 userId / basicId / 名称;错误时是明确的中文原因;
+// 网络不通时标 network_error(界面据此区分“凭据错”和“连不上”)。
+TEST(LineApi, ValidateCredentialsDistinguishesFailures) {
+    FakeLineServer server;
+    auto ok = validate_credentials(local_options(server));
+    ASSERT_TRUE(ok.ok) << ok.error;
+    EXPECT_EQ(ok.bot.user_id, FakeLineServer::kBotId);
+    EXPECT_EQ(ok.bot.basic_id, "@216ruabc");
+
+    auto wrong = local_options(server);
+    wrong.channel_secret = "ffffffffffffffffffffffffffffffff";
+    auto bad = validate_credentials(wrong);
+    EXPECT_FALSE(bad.ok);
+    EXPECT_FALSE(bad.network_error);
+    EXPECT_NE(bad.error.find("Channel secret"), std::string::npos);
+
+    auto missing = local_options(server);
+    missing.channel_secret.clear();
+    EXPECT_NE(validate_credentials(missing).error.find("Channel secret"), std::string::npos);
+
+    auto offline = local_options(server);
+    offline.api_base = "http://127.0.0.1:" + std::to_string(pick_free_loopback_port());
+    auto down = validate_credentials(offline);
+    EXPECT_FALSE(down.ok);
+    EXPECT_TRUE(down.network_error);
+}
+
+// 场景:长期令牌 + Channel ID + secret 同时填写,但 secret 不对。
+// 期望:仍用 Channel ID + secret 换一次令牌来验证 secret(回调签名要用它),校验失败。
+TEST(LineApi, ValidateChecksSecretEvenWithLongLivedToken) {
+    FakeLineServer server;
+    server.long_lived_token = "long-lived-token-abcdef";
+    auto options = local_options(server);
+    options.access_token = server.long_lived_token;
+    EXPECT_TRUE(validate_credentials(options).ok);
+    options.channel_secret = "ffffffffffffffffffffffffffffffff";
+    const auto result = validate_credentials(options);
+    EXPECT_FALSE(result.ok);
+    EXPECT_FALSE(result.network_error);
+}
+
+// 场景:频道从未设置过 webhook 地址;随后设置一个地址。
+// 期望:读取时 404 → exists=false;设置走 PUT,之后能读到地址与 “Use webhook” 状态。
+// 注:im::http_send 需要支持 PUT,否则 PUT 会被当成 GET 发出(本用例即为守卫)。
+TEST(LineApi, WebhookEndpointReadAndWrite) {
+    FakeLineServer server;
+    server.webhook_active = false;
+    Api api(local_options(server));
+    WebhookInfo info;
+    const auto first = api.webhook_info(&info);
+    EXPECT_EQ(first.status, 404);
+    EXPECT_FALSE(info.exists);
+    ASSERT_TRUE(api.set_webhook("https://abc.trycloudflare.com/line/webhook").ok);
+    ASSERT_EQ(server.calls_to("PUT", "/v2/bot/channel/webhook/endpoint").size(), 1u);
+    ASSERT_TRUE(api.webhook_info(&info).ok);
+    EXPECT_TRUE(info.exists);
+    EXPECT_EQ(info.endpoint, "https://abc.trycloudflare.com/line/webhook");
+    EXPECT_FALSE(info.active);
+}
+
+// 场景:下载图片内容;下载超过上限的内容;下载已被撤回的内容;下载仍在转码的视频。
+// 期望:正常内容写入文件;超限失败并删除半截文件;410 给出“已撤回”;202 时轮询转码状态后再下载成功。
+TEST(LineApi, DownloadsContentWithLimitsAndTranscoding) {
+    FakeLineServer server;
+    server.set_content("img1", std::string(64, 'p'));
+    server.set_content("big", std::string(4096, 'b'));
+    server.set_content("transcode-1", std::string(16, 'v'));
+    Api api(local_options(server));
+    const auto dest = temp_file("content.bin");
+    std::string error;
+    ASSERT_TRUE(api.download_content("img1", dest, 1024, &error)) << error;
+    {
+        std::ifstream in(dest, std::ios::binary);
+        const std::string bytes((std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>());
+        EXPECT_EQ(bytes, std::string(64, 'p'));
+    }
+    EXPECT_FALSE(api.download_content("big", dest, 1024, &error));
+    EXPECT_EQ(error, "附件超过大小限制");
+    EXPECT_FALSE(std::filesystem::exists(dest));
+
+    EXPECT_FALSE(api.download_content("gone", dest, 1024, &error));
+    EXPECT_EQ(error, "对方已撤回该消息");
+
+    ASSERT_TRUE(api.download_content("transcode-1", dest, 1024, &error)) << error;
+    EXPECT_EQ(server.calls_to("GET", "/v2/bot/message/transcode-1/content/transcoding").size(), 1u);
+    EXPECT_EQ(server.calls_to("GET", "/v2/bot/message/transcode-1/content").size(), 2u);
+    std::error_code ec;
+    std::filesystem::remove(dest, ec);
+}
+
+// 场景:生成推送重试键。
+// 期望:是小写 UUID v4 形式,每次不同。
+TEST(LineApi, RetryKeysAreUuidV4) {
+    const auto a = new_retry_key();
+    const auto b = new_retry_key();
+    EXPECT_TRUE(std::regex_match(a, std::regex("^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$")))
+        << a;
+    EXPECT_NE(a, b);
+}
+
+} // namespace
+} // namespace acecode::im::line
diff --git a/tests/im/line_protocol_test.cpp b/tests/im/line_protocol_test.cpp
new file mode 100644
index 000000000..9ab6e3bbc
--- /dev/null
+++ b/tests/im/line_protocol_test.cpp
@@ -0,0 +1,392 @@
+#include <gtest/gtest.h>
+
+#include "im/line/line_media.hpp"
+#include "im/line/line_protocol.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <string>
+
+// im/line/line_protocol 与 line_media:LINE 纯逻辑单测。
+// 覆盖:签名(官方示例)、webhook 解析(私聊 / 群 @ / @All / 电脑版无 userId / 各类附件 / 位置 / standby /
+// 重投 / 无效 JSON)、UTF-16 区间删除、回复令牌新鲜度、分段与每次 5 条、错误识别、链接与文件名、媒体登记表。
+
+namespace acecode::im::line {
+namespace {
+
+constexpr const char* kBot = "U0123456789abcdef0123456789abcdef";
+constexpr const char* kUser = "U11111111111111111111111111111111";
+constexpr const char* kSecret = "8c570fa6dd201bb328f1c1eac23a96d8";
+constexpr std::int64_t kNow = 1700000000000;
+
+std::string body_with(const nlohmann::json& event) {
+    return nlohmann::json{{"destination", kBot}, {"events", nlohmann::json::array({event})}}.dump();
+}
+
+nlohmann::json message_event(const nlohmann::json& source, const nlohmann::json& message) {
+    return {{"type", "message"}, {"mode", "active"}, {"timestamp", kNow - 1000},
+            {"source", source}, {"webhookEventId", "01FZ74A0TDDPYRVKNK77XKC3ZR"},
+            {"deliveryContext", {{"isRedelivery", false}}}, {"replyToken", "rt-1"}, {"message", message}};
+}
+
+// 场景:LINE 官方文档给出的签名示例(secret、请求体、期望签名)。
+// 期望:按原始字节计算的 base64(HMAC-SHA256) 与官方值一致,校验通过。
+TEST(LineProtocol, SignatureMatchesOfficialVector) {
+    const std::string body = R"({"destination":"U8e742f61d673b39c7fff3cecb7536ef0","events":[]})";
+    EXPECT_EQ(sign_body(body, kSecret), "GhRKmvmHys4Pi8DxkF4+EayaH0OqtJtaZxgTD9fMDLs=");
+    EXPECT_TRUE(verify_signature(body, "GhRKmvmHys4Pi8DxkF4+EayaH0OqtJtaZxgTD9fMDLs=", kSecret));
+    // 头值两端的空白不影响校验(代理有时会带上)。
+    EXPECT_TRUE(verify_signature(body, " GhRKmvmHys4Pi8DxkF4+EayaH0OqtJtaZxgTD9fMDLs=\r\n", kSecret));
+}
+
+// 场景:请求体被改动一个字节(如代理把 LF 换成 CRLF)、签名缺失、密钥不对或为空。
+// 期望:全部拒绝 —— 签名必须按原样字节、正确密钥计算。
+TEST(LineProtocol, SignatureRejectsTamperingAndMissingValues) {
+    const std::string body = R"({"destination":"U8e742f61d673b39c7fff3cecb7536ef0","events":[]})";
+    const auto good = sign_body(body, kSecret);
+    EXPECT_FALSE(verify_signature(body + "\n", good, kSecret));
+    EXPECT_FALSE(verify_signature(body, "", kSecret));
+    EXPECT_FALSE(verify_signature(body, good, "00000000000000000000000000000000"));
+    EXPECT_FALSE(verify_signature(body, good, ""));
+    EXPECT_FALSE(verify_signature(body, good.substr(0, good.size() - 1), kSecret));
+}
+
+// 场景:用户一对一发来一条文字。
+// 期望:私聊地址 chat = sender = userId,account = 机器人 id,视为点名;reply_context 带回复令牌、
+// 本机收到时间、事件时间、引用令牌与消息 id。
+TEST(LineProtocol, ParsesPrivateText) {
+    const auto body = body_with(message_event({{"type", "user"}, {"userId", kUser}},
+                                              {{"id", "100"}, {"type", "text"}, {"text", " 你好 "}, {"quoteToken", "qt"}}));
+    const auto parsed = parse_webhook(body, kBot, kNow);
+    ASSERT_TRUE(parsed.valid);
+    EXPECT_EQ(parsed.destination, kBot);
+    ASSERT_EQ(parsed.events.size(), 1u);
+    const auto& event = parsed.events[0];
+    EXPECT_EQ(event.kind, EventKind::Message);
+    EXPECT_EQ(event.event_id, "01FZ74A0TDDPYRVKNK77XKC3ZR");
+    ASSERT_TRUE(event.inbound.has_value());
+    const auto& in = *event.inbound;
+    EXPECT_EQ(in.address.platform, "line");
+    EXPECT_EQ(in.address.account, kBot);
+    EXPECT_EQ(in.address.kind, ChatKind::Private);
+    EXPECT_EQ(in.address.chat, kUser);
+    EXPECT_EQ(in.address.sender, kUser);
+    EXPECT_EQ(in.message_id, "100");
+    EXPECT_EQ(in.text, u8"你好");
+    EXPECT_TRUE(in.mentioned);
+    EXPECT_EQ(in.reply_context.value("reply_token", ""), "rt-1");
+    EXPECT_EQ(in.reply_context.value("received_at_ms", std::int64_t{0}), kNow);
+    EXPECT_EQ(in.reply_context.value("event_ts_ms", std::int64_t{0}), kNow - 1000);
+    EXPECT_EQ(in.reply_context.value("quote_token", ""), "qt");
+    EXPECT_EQ(in.reply_context.value("message_id", ""), "100");
+}
+
+// 场景:群里有人发 “😀@ACE 帮我看看”,mention 的 index/length 按 UTF-16 计(emoji 占 2 个单位)。
+// 期望:按 UTF-16 区间去掉 @ACE,不切坏 emoji;只因 isSelf 点名机器人才 mentioned;群地址 chat = groupId。
+// 回归:若按 UTF-8 字节切片,emoji 会被截成乱码、“@ACE” 残留一部分。
+TEST(LineProtocol, GroupSelfMentionIsStrippedByUtf16Offsets) {
+    const std::string text = u8"😀@ACE 帮我看看";
+    const nlohmann::json mention{{"mentionees", {{{"index", 2}, {"length", 4}, {"type", "user"},
+                                                  {"userId", kBot}, {"isSelf", true}}}}};
+    const auto body = body_with(message_event({{"type", "group"}, {"groupId", "Cgroup1"}, {"userId", kUser}},
+                                              {{"id", "101"}, {"type", "text"}, {"text", text},
+                                               {"quoteToken", "q"}, {"mention", mention}}));
+    const auto parsed = parse_webhook(body, kBot, kNow);
+    ASSERT_EQ(parsed.events.size(), 1u);
+    ASSERT_TRUE(parsed.events[0].inbound.has_value());
+    const auto& in = *parsed.events[0].inbound;
+    EXPECT_EQ(in.address.kind, ChatKind::Group);
+    EXPECT_EQ(in.address.chat, "Cgroup1");
+    EXPECT_EQ(in.address.sender, kUser);
+    EXPECT_TRUE(in.mentioned);
+    EXPECT_EQ(in.text, u8"😀 帮我看看");
+}
+
+// 场景:群消息只 @All,或点名了别人;另一条没有 isSelf 字段但 userId 等于机器人 id。
+// 期望:@All 与点名别人都不算点名机器人,文字原样保留;userId 兜底判定为点名。
+TEST(LineProtocol, MentionRulesForAllOthersAndFallback) {
+    const nlohmann::json all{{"mentionees", {{{"index", 0}, {"length", 4}, {"type", "all"}},
+                                             {{"index", 5}, {"length", 4}, {"type", "user"}, {"userId", kUser}}}}};
+    auto parsed = parse_webhook(body_with(message_event({{"type", "group"}, {"groupId", "Cg"}, {"userId", kUser}},
+                                                        {{"id", "1"}, {"type", "text"}, {"text", "@All @Bob hi"},
+                                                         {"quoteToken", "q"}, {"mention", all}})),
+                                kBot, kNow);
+    ASSERT_TRUE(parsed.events[0].inbound.has_value());
+    EXPECT_FALSE(parsed.events[0].inbound->mentioned);
+    EXPECT_EQ(parsed.events[0].inbound->text, "@All @Bob hi");
+
+    const nlohmann::json fallback{{"mentionees", {{{"index", 0}, {"length", 4}, {"type", "user"}, {"userId", kBot}}}}};
+    parsed = parse_webhook(body_with(message_event({{"type", "room"}, {"roomId", "Rroom"}, {"userId", kUser}},
+                                                   {{"id", "2"}, {"type", "text"}, {"text", "@ACE hi"},
+                                                    {"quoteToken", "q"}, {"mention", fallback}})),
+                           kBot, kNow);
+    ASSERT_TRUE(parsed.events[0].inbound.has_value());
+    EXPECT_TRUE(parsed.events[0].inbound->mentioned);
+    EXPECT_EQ(parsed.events[0].inbound->address.chat, "Rroom");
+    EXPECT_EQ(parsed.events[0].inbound->text, "hi");
+}
+
+// 场景:电脑版 LINE 用户在群里 @机器人,事件 source 没有 userId。
+// 期望:不生成入站消息(无法识别发言人,不能做成员授权),但标出 unidentified_sender 与 mentioned_self,
+// 传输层据此用免费回复令牌提示对方。
+TEST(LineProtocol, GroupMessageWithoutUserIdIsUnidentified) {
+    const nlohmann::json mention{{"mentionees", {{{"index", 0}, {"length", 4}, {"type", "user"}, {"isSelf", true}}}}};
+    const auto parsed = parse_webhook(body_with(message_event({{"type", "group"}, {"groupId", "Cg"}},
+                                                              {{"id", "3"}, {"type", "text"}, {"text", "@ACE hi"},
+                                                               {"quoteToken", "q"}, {"mention", mention}})),
+                                      kBot, kNow);
+    ASSERT_EQ(parsed.events.size(), 1u);
+    EXPECT_FALSE(parsed.events[0].inbound.has_value());
+    EXPECT_TRUE(parsed.events[0].unidentified_sender);
+    EXPECT_TRUE(parsed.events[0].mentioned_self);
+    EXPECT_EQ(parsed.events[0].reply_token, "rt-1");
+}
+
+// 场景:私聊依次发来图片、外部图片、视频、语音、文件、贴图、位置。
+// 期望:图片/视频/语音的 remote_ref 是消息 id(外部内容取原始地址),文件带文件名与大小,
+// 贴图是不可下载的 Sticker 附件,位置转成一行文字。
+TEST(LineProtocol, MapsMediaAndLocationMessages) {
+    const nlohmann::json src{{"type", "user"}, {"userId", kUser}};
+    auto first = [&src](const nlohmann::json& message) {
+        const auto parsed = parse_webhook(body_with(message_event(src, message)), kBot, kNow);
+        EXPECT_EQ(parsed.events.size(), 1u);
+        return parsed.events.at(0).inbound;
+    };
+    auto in = first({{"id", "200"}, {"type", "image"}, {"quoteToken", "q"}, {"contentProvider", {{"type", "line"}}}});
+    ASSERT_TRUE(in && in->attachments.size() == 1);
+    EXPECT_EQ(in->attachments[0].kind, AttachmentKind::Image);
+    EXPECT_EQ(in->attachments[0].remote_ref, "200");
+    EXPECT_EQ(in->attachments[0].mime_type, "image/jpeg");
+
+    in = first({{"id", "201"}, {"type", "image"}, {"quoteToken", "q"},
+                {"contentProvider", {{"type", "external"}, {"originalContentUrl", "https://cdn.example/a.jpg"}}}});
+    ASSERT_TRUE(in && in->attachments.size() == 1);
+    EXPECT_EQ(in->attachments[0].remote_ref, "https://cdn.example/a.jpg");
+
+    in = first({{"id", "202"}, {"type", "video"}, {"quoteToken", "q"}, {"duration", 1000},
+                {"contentProvider", {{"type", "line"}}}});
+    ASSERT_TRUE(in && in->attachments.size() == 1);
+    EXPECT_EQ(in->attachments[0].kind, AttachmentKind::Video);
+
+    in = first({{"id", "203"}, {"type", "audio"}, {"duration", 1000}, {"contentProvider", {{"type", "line"}}}});
+    ASSERT_TRUE(in && in->attachments.size() == 1);
+    EXPECT_EQ(in->attachments[0].kind, AttachmentKind::Voice);
+    EXPECT_EQ(in->attachments[0].name, "203.m4a");
+
+    in = first({{"id", "204"}, {"type", "file"}, {"fileName", u8"报告.pdf"}, {"fileSize", 2048}});
+    ASSERT_TRUE(in && in->attachments.size() == 1);
+    EXPECT_EQ(in->attachments[0].kind, AttachmentKind::File);
+    EXPECT_EQ(in->attachments[0].name, u8"报告.pdf");
+    EXPECT_EQ(in->attachments[0].size, 2048u);
+    EXPECT_EQ(in->attachments[0].remote_ref, "204");
+
+    in = first({{"id", "205"}, {"type", "sticker"}, {"packageId", "1"}, {"stickerId", "2"},
+                {"stickerResourceType", "STATIC"}, {"quoteToken", "q"}});
+    ASSERT_TRUE(in && in->attachments.size() == 1);
+    EXPECT_EQ(in->attachments[0].kind, AttachmentKind::Sticker);
+    EXPECT_TRUE(in->attachments[0].remote_ref.empty());
+
+    in = first({{"id", "206"}, {"type", "location"}, {"title", "Office"}, {"address", "Taipei"},
+                {"latitude", 25.033}, {"longitude", 121.5654}});
+    ASSERT_TRUE(in.has_value());
+    EXPECT_EQ(in->text, u8"[位置] Office Taipei (25.033000, 121.565400)");
+}
+
+// 场景:standby 模式的事件(另一个模块接管了聊天)、重投事件、空事件列表、无效 JSON、未知事件与消息类型。
+// 期望:standby 标记出来且 reply_context 不带令牌;重投标志进 reply_context;空列表与未知类型被容忍;
+// 无效 JSON 判为 invalid。
+TEST(LineProtocol, ToleratesStandbyRedeliveryAndUnknownShapes) {
+    auto standby = message_event({{"type", "user"}, {"userId", kUser}},
+                                 {{"id", "300"}, {"type", "text"}, {"text", "x"}, {"quoteToken", "q"}});
+    standby["mode"] = "standby";
+    standby.erase("replyToken");
+    auto parsed = parse_webhook(body_with(standby), kBot, kNow);
+    ASSERT_EQ(parsed.events.size(), 1u);
+    EXPECT_TRUE(parsed.events[0].standby);
+    ASSERT_TRUE(parsed.events[0].inbound.has_value());
+    EXPECT_FALSE(parsed.events[0].inbound->reply_context.contains("reply_token"));
+
+    auto redelivered = message_event({{"type", "user"}, {"userId", kUser}},
+                                     {{"id", "301"}, {"type", "text"}, {"text", "x"}, {"quoteToken", "q"}});
+    redelivered["deliveryContext"]["isRedelivery"] = true;
+    parsed = parse_webhook(body_with(redelivered), kBot, kNow);
+    ASSERT_TRUE(parsed.events[0].inbound.has_value());
+    EXPECT_TRUE(parsed.events[0].redelivery);
+    EXPECT_TRUE(parsed.events[0].inbound->reply_context.value("redelivery", false));
+
+    parsed = parse_webhook(R"({"destination":"U1","events":[]})", kBot, kNow);
+    EXPECT_TRUE(parsed.valid);
+    EXPECT_TRUE(parsed.events.empty());
+
+    parsed = parse_webhook("not json", kBot, kNow);
+    EXPECT_FALSE(parsed.valid);
+
+    parsed = parse_webhook(body_with({{"type", "brandNewEvent"}, {"webhookEventId", "E1"}}), kBot, kNow);
+    ASSERT_EQ(parsed.events.size(), 1u);
+    EXPECT_EQ(parsed.events[0].kind, EventKind::Other);
+    EXPECT_FALSE(parsed.events[0].inbound.has_value());
+
+    parsed = parse_webhook(body_with(message_event({{"type", "user"}, {"userId", kUser}},
+                                                   {{"id", "302"}, {"type", "hologram"}})),
+                           kBot, kNow);
+    EXPECT_FALSE(parsed.events[0].inbound.has_value());
+
+    parsed = parse_webhook(body_with({{"type", "unsend"}, {"webhookEventId", "E2"},
+                                      {"source", {{"type", "user"}, {"userId", kUser}}},
+                                      {"unsend", {{"messageId", "777"}}}}),
+                           kBot, kNow);
+    EXPECT_EQ(parsed.events[0].kind, EventKind::Unsend);
+    EXPECT_EQ(parsed.events[0].message_id, "777");
+}
+
+// 场景:删除多个 UTF-16 区间:重叠、无序、越界、长度为 0;以及代理对中间的偏移。
+// 期望:重叠部分只删一次,越界截到末尾,长度 0 忽略;偏移落在代理对中间时取该字符开头。
+TEST(LineProtocol, RemovesUtf16RangesSafely) {
+    EXPECT_EQ(remove_utf16_ranges("abcdef", {{4, 2}, {1, 2}, {2, 1}}), "ad");
+    EXPECT_EQ(remove_utf16_ranges("abc", {{2, 10}}), "ab");
+    EXPECT_EQ(remove_utf16_ranges("abc", {{1, 0}}), "abc");
+    const std::string emoji = u8"a😀b";
+    EXPECT_EQ(utf16_to_byte_offset(emoji, 1), 1u);
+    EXPECT_EQ(utf16_to_byte_offset(emoji, 2), 1u);  // 代理对中间
+    EXPECT_EQ(utf16_to_byte_offset(emoji, 3), 5u);
+    EXPECT_EQ(utf16_to_byte_offset(emoji, 99), emoji.size());
+}
+
+// 场景:回复令牌的几种时间状态。阈值:收到后 50 秒内可用(官方说 1 分钟,留 10 秒余量);
+// 重投事件在事件发生 20 分钟后一律失效(再留 1 分钟余量)。
+// 期望:新鲜可用;超过 50 秒、缺令牌、缺收到时间不可用;重投且事件已过 19 分钟以上不可用。
+TEST(LineProtocol, ReplyTokenFreshnessTable) {
+    ReplyToken token;
+    token.token = "rt";
+    token.received_at_ms = kNow;
+    token.event_ts_ms = kNow - 1000;
+    EXPECT_TRUE(reply_token_fresh(token, kNow + 10'000));
+    EXPECT_FALSE(reply_token_fresh(token, kNow + 50'000));
+    auto missing = token;
+    missing.token.clear();
+    EXPECT_FALSE(reply_token_fresh(missing, kNow));
+    auto no_time = token;
+    no_time.received_at_ms = 0;
+    EXPECT_FALSE(reply_token_fresh(no_time, kNow));
+    auto redelivered = token;
+    redelivered.redelivery = true;
+    EXPECT_TRUE(reply_token_fresh(redelivered, kNow + 1000));
+    redelivered.event_ts_ms = kNow - 19 * 60 * 1000 - 1;
+    EXPECT_FALSE(reply_token_fresh(redelivered, kNow + 1000));
+
+    const auto context = make_reply_context(token, "m1");
+    const auto back = reply_token_of(context);
+    ASSERT_TRUE(back.has_value());
+    EXPECT_EQ(back->token, "rt");
+    EXPECT_EQ(back->received_at_ms, kNow);
+    EXPECT_FALSE(reply_token_of(nlohmann::json::object()).has_value());
+}
+
+// 场景:助手回复是带链接与粗体的 Markdown,另有一段超长文字。
+// 期望:转成纯文本且链接保留为 “文字 (网址)”;长文按 4800 个 UTF-16 单位分段;12 条消息分成 5/5/2 三次调用。
+TEST(LineProtocol, ChunksPlainTextAndBatchesByFive) {
+    const auto chunks = plain_text_chunks("**重点**:见 [文档](https://example.com/doc)");
+    ASSERT_EQ(chunks.size(), 1u);
+    EXPECT_EQ(chunks[0], u8"重点:见 文档 (https://example.com/doc)");
+
+    const auto long_chunks = plain_text_chunks(std::string(10000, 'a'));
+    ASSERT_EQ(long_chunks.size(), 3u);
+    for (const auto& chunk : long_chunks) EXPECT_LE(chunk.size(), kChunkUnits);
+
+    std::vector<nlohmann::json> messages;
+    for (int i = 0; i < 12; ++i) messages.push_back(text_message(std::to_string(i)));
+    const auto batches = batch_messages(messages);
+    ASSERT_EQ(batches.size(), 3u);
+    EXPECT_EQ(batches[0].size(), 5u);
+    EXPECT_EQ(batches[1].size(), 5u);
+    EXPECT_EQ(batches[2].size(), 2u);
+    EXPECT_EQ(batches[2][1]["text"], "11");
+    EXPECT_EQ(text_message("x", "qt")["quoteToken"], "qt");
+    EXPECT_FALSE(text_message("x").contains("quoteToken"));
+}
+
+// 场景:LINE 返回的几种错误。
+// 期望:429 + “monthly limit” 是额度用完(暂存),普通 429 是限频;400 “Invalid reply token” 识别为令牌失效。
+TEST(LineProtocol, ClassifiesQuotaAndReplyTokenErrors) {
+    EXPECT_TRUE(is_monthly_limit(429, "You have reached your monthly limit."));
+    EXPECT_FALSE(is_monthly_limit(429, "The API rate limit has been exceeded. Try again later."));
+    EXPECT_FALSE(is_monthly_limit(400, "monthly limit"));
+    EXPECT_TRUE(is_invalid_reply_token(400, "Invalid reply token"));
+    EXPECT_FALSE(is_invalid_reply_token(400, "Failed to send messages"));
+}
+
+// 场景:机主用预填 “/start 483920” 的 oaMessage 链接私聊机器人;群里有人发同样的文字。
+// 期望:链接按 UTF-8 百分号编码;私聊解析出 start_code,群聊不解析。
+TEST(LineProtocol, StartCodeAndOaMessageLink) {
+    EXPECT_EQ(oa_message_url("@216ruabc", "/start 483920"),
+              "https://line.me/R/oaMessage/%40216ruabc/?%2Fstart%20483920");
+    auto parsed = parse_webhook(body_with(message_event({{"type", "user"}, {"userId", kUser}},
+                                                        {{"id", "400"}, {"type", "text"}, {"text", "/start 483920"},
+                                                         {"quoteToken", "q"}})),
+                                kBot, kNow);
+    ASSERT_TRUE(parsed.events[0].inbound.has_value());
+    EXPECT_EQ(parsed.events[0].inbound->start_code, "483920");
+    parsed = parse_webhook(body_with(message_event({{"type", "group"}, {"groupId", "Cg"}, {"userId", kUser}},
+                                                   {{"id", "401"}, {"type", "text"}, {"text", "/start 483920"},
+                                                    {"quoteToken", "q"}})),
+                           kBot, kNow);
+    ASSERT_TRUE(parsed.events[0].inbound.has_value());
+    EXPECT_TRUE(parsed.events[0].inbound->start_code.empty());
+}
+
+// 场景:生成加好友链接、判断可显示动画的 id、判断图片类型、清洗媒体文件名。
+// 期望:basicId 的 @ 被编码;只有 U 开头的 id 能显示动画;只认 JPEG/PNG;
+// 文件名只保留安全字符、不以点开头、不含路径分隔符,超长截断但保留扩展名。
+TEST(LineProtocol, LinksIdsImagesAndFileNames) {
+    EXPECT_EQ(add_friend_url("@216ruabc"), "https://line.me/R/ti/p/%40216ruabc");
+    EXPECT_EQ(add_friend_url(""), "");
+    EXPECT_TRUE(is_user_id(kUser));
+    EXPECT_FALSE(is_user_id("Cgroup"));
+    EXPECT_TRUE(is_line_image("image/png", "a"));
+    EXPECT_TRUE(is_line_image("", "photo.JPG"));
+    EXPECT_FALSE(is_line_image("image/gif", "a.gif"));
+    EXPECT_FALSE(is_line_image("application/pdf", "a.png"));
+    EXPECT_EQ(safe_file_name(u8"截图 1.png"), "_______1.png");
+    EXPECT_EQ(safe_file_name("../../etc/passwd"), "_.._etc_passwd");
+    EXPECT_EQ(safe_file_name("...."), "file");
+    const auto long_name = safe_file_name(std::string(100, 'x') + ".jpeg");
+    EXPECT_EQ(long_name.size(), 64u);
+    EXPECT_EQ(long_name.substr(long_name.size() - 5), ".jpeg");
+}
+
+// 场景:登记一张要发送的图片,再按 URL 路径查找;另有过期、文件名不符、路径格式不对、令牌不存在的请求。
+// 期望:只有令牌与文件名都对、且未过期才返回登记时的路径;URL 内容绝不参与路径拼接。
+TEST(LineMedia, RegistryFindsOnlyExactLiveEntries) {
+    using Clock = MediaRegistry::Clock;
+    MediaRegistry registry(std::chrono::minutes(30), 2);
+    const auto now = Clock::now();
+    const auto relative = registry.add("C:/data/a.png", "a.png", "image/png", now);
+    ASSERT_FALSE(relative.empty());
+    const auto slash = relative.find('/');
+    const auto token = relative.substr(0, slash);
+    EXPECT_EQ(token.size(), 32u);
+    EXPECT_EQ(relative.substr(slash + 1), "a.png");
+
+    const auto found = registry.find_path(std::string(kMediaRoutePrefix) + relative, now);
+    ASSERT_TRUE(found.has_value());
+    EXPECT_EQ(found->path, std::filesystem::path("C:/data/a.png"));
+    EXPECT_EQ(found->mime_type, "image/png");
+
+    EXPECT_FALSE(registry.find(token, "b.png", now).has_value());
+    EXPECT_FALSE(registry.find_path("/line/media/" + token + "/../a.png", now).has_value());
+    EXPECT_FALSE(registry.find_path("/line/media/" + token, now).has_value());
+    EXPECT_FALSE(registry.find_path("/other/" + relative, now).has_value());
+    EXPECT_FALSE(registry.find("nosuchtoken", "a.png", now).has_value());
+    EXPECT_FALSE(registry.find(token, "a.png", now + std::chrono::minutes(31)).has_value());
+    // 过期的条目在查找时被移除。
+    EXPECT_EQ(registry.size(), 0u);
+
+    // 超过条数上限时丢最旧的。
+    registry.add("1.png", "1.png", "image/png", now);
+    registry.add("2.png", "2.png", "image/png", now + std::chrono::seconds(1));
+    registry.add("3.png", "3.png", "image/png", now + std::chrono::seconds(2));
+    EXPECT_LE(registry.size(), 2u);
+}
+
+} // namespace
+} // namespace acecode::im::line
diff --git a/tests/im/line_transport_test.cpp b/tests/im/line_transport_test.cpp
new file mode 100644
index 000000000..87faed3ef
--- /dev/null
+++ b/tests/im/line_transport_test.cpp
@@ -0,0 +1,591 @@
+#include <gtest/gtest.h>
+
+#include "channels/core/line_webhook_server.hpp"
+#include "im/line/line_transport.hpp"
+#include "test_support/im/fake_line_server.hpp"
+
+#include <atomic>
+#include <filesystem>
+#include <fstream>
+#include <mutex>
+#include <thread>
+#include <vector>
+
+// im/line/line_transport:LINE 传输层端到端测试。
+// 真实组件:LineTransport + Crow 回调端口(channels::core::LineWebhookServer);
+// 假组件:本机假 LINE API、假 cloudflared。所有请求只在 127.0.0.1,不连真实平台。
+// 覆盖:自有公网地址 / 快速隧道两种模式的连接与 webhook 登记、签名校验、去重、私聊与群 @、
+// 回复与推送的选择、5 条一批、推送重试键、额度用完暂存补发、图片临时链接、文件说明、
+// 凭据无效停止重试、未安装 cloudflared、隧道退出重建、Use webhook 未开、正在输入、引用识别、及时停机。
+
+namespace acecode::im::line {
+namespace {
+
+using test::FakeCloudflared;
+using test::FakeLineServer;
+
+constexpr const char* kUser = "U11111111111111111111111111111111";
+constexpr const char* kGroup = "Cgroup0000000000000000000000000001";
+
+struct Recorder {
+    std::mutex mu;
+    std::vector<Inbound> inbound;
+    std::function<void()> on_each;  // 可选:收到入站消息时(在传输层线程上)调用
+
+    TransportCallbacks callbacks() {
+        TransportCallbacks cb;
+        cb.on_inbound = [this](Inbound in) {
+            if (on_each) on_each();
+            std::lock_guard<std::mutex> lock(mu);
+            inbound.push_back(std::move(in));
+        };
+        return cb;
+    }
+    std::size_t count() {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.size();
+    }
+    Inbound at(std::size_t i) {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.at(i);
+    }
+};
+
+struct Harness {
+    FakeLineServer server;
+    std::shared_ptr<channels::core::LineWebhookServer> listener = std::make_shared<channels::core::LineWebhookServer>();
+    std::uint16_t port = pick_free_loopback_port();
+
+    std::string base() const { return "http://127.0.0.1:" + std::to_string(port); }
+    std::string webhook_url() const { return base() + "/line/webhook"; }
+
+    // 自有公网地址模式:公网地址就是回调端口本身,公网自检与 LINE 的 webhook 测试都直达它。
+    LineTransportOptions options() const {
+        LineTransportOptions options;
+        options.api.channel_id = FakeLineServer::kChannelId;
+        options.api.channel_secret = FakeLineServer::kSecret;
+        options.api.api_base = server.base();
+        options.api.data_api_base = server.base();
+        options.api.use_proxy = false;
+        options.api.timeout = std::chrono::seconds(5);
+        options.listener = listener;
+        options.listen_port = port;
+        options.public_url = base() + "/";
+        options.backoff = {std::chrono::milliseconds(50)};
+        options.public_check_timeout = std::chrono::seconds(3);
+        options.public_check_interval = std::chrono::milliseconds(50);
+        options.watch_interval = std::chrono::hours(1);
+        options.webhook_recheck = std::chrono::milliseconds(100);
+        options.send_retry = {std::chrono::milliseconds(20), std::chrono::milliseconds(20)};
+        return options;
+    }
+};
+
+Address private_address() {
+    Address address;
+    address.platform = "line";
+    address.account = FakeLineServer::kBotId;
+    address.kind = ChatKind::Private;
+    address.chat = address.sender = kUser;
+    return address;
+}
+
+Address group_address() {
+    auto address = private_address();
+    address.kind = ChatKind::Group;
+    address.chat = kGroup;
+    return address;
+}
+
+bool wait_state(LineTransport& transport, LinkState state) {
+    return FakeLineServer::wait_until([&transport, state] { return transport.status().state == state; });
+}
+
+// 发一条私聊文字 webhook,返回回调端口的 HTTP 状态码。
+long post_private_text(Harness& h, const std::string& text, const std::string& message_id,
+                       const std::string& reply_token, const std::string& event_id) {
+    const auto body = FakeLineServer::webhook_body(
+        {FakeLineServer::text_event(FakeLineServer::source("user", "", kUser), text, message_id, reply_token, event_id)});
+    return FakeLineServer::post_webhook(h.webhook_url(), body).status;
+}
+
+// 场景:使用自己的公网地址(结尾带斜杠)开启 LINE。
+// 期望:换令牌 → 读机器人信息 → 开回调端口 → 公网自检 → PUT 登记 <公网地址>/line/webhook →
+// 调用 LINE 的 webhook 测试(假服务真的发来带签名的请求)→ 已连接;状态里有机器人 id、名称、加好友链接。
+TEST(LineTransport, ConnectsWithOwnPublicUrlAndRegistersWebhook) {
+    Harness h;
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(h.options());
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+    const auto status = transport.status();
+    EXPECT_EQ(status.account, FakeLineServer::kBotId);
+    EXPECT_EQ(status.display_name, u8"ACE 测试机器人");
+    EXPECT_EQ(status.extra.value("add_friend_url", ""), "https://line.me/R/ti/p/%40216ruabc");
+    EXPECT_EQ(status.extra.value("webhook_url", ""), h.webhook_url());
+    EXPECT_EQ(status.extra.value("listen_port", 0), h.port);
+    EXPECT_EQ(status.extra.value("tunnel", ""), "custom");
+    EXPECT_FALSE(status.extra.value("setup_hint", "").empty());
+    EXPECT_EQ(h.server.endpoint(), h.webhook_url());
+    EXPECT_EQ(h.server.calls_to("PUT", "/v2/bot/channel/webhook/endpoint").size(), 1u);
+    EXPECT_EQ(h.server.calls_to("POST", "/v2/bot/channel/webhook/test").size(), 1u);
+    EXPECT_EQ(h.server.mint_count(), 1);
+    EXPECT_EQ(recorder.count(), 0u);  // webhook 测试是空事件,不产生入站消息
+    const auto begin = std::chrono::steady_clock::now();
+    transport.stop();
+    EXPECT_LT(std::chrono::steady_clock::now() - begin, std::chrono::seconds(3));
+    EXPECT_EQ(transport.status().state, LinkState::Stopped);
+}
+
+// 场景:用户私聊发来一条文字;LINE 因网络原因重发同一事件;另有伪造签名与无签名的请求。
+// 期望:回调立即 200,入站消息只上报一次(按 webhookEventId 去重),带发言人显示名与回复令牌;
+// 签名不对或缺失一律 401 且不上报。
+TEST(LineTransport, ReceivesPrivateTextOnceAndRejectsBadSignatures) {
+    Harness h;
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(h.options());
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+    const auto token = h.server.issue_reply_token();
+    EXPECT_EQ(post_private_text(h, u8"你好", "m1", token, "ev1"), 200);
+    ASSERT_TRUE(FakeLineServer::wait_until([&recorder] { return recorder.count() == 1; }));
+    const auto in = recorder.at(0);
+    EXPECT_EQ(in.address.platform, "line");
+    EXPECT_EQ(in.address.account, FakeLineServer::kBotId);
+    EXPECT_EQ(in.address.chat, kUser);
+    EXPECT_EQ(in.address.sender, kUser);
+    EXPECT_EQ(in.text, u8"你好");
+    EXPECT_TRUE(in.mentioned);
+    EXPECT_EQ(in.sender_name, "Ann");
+    EXPECT_EQ(in.reply_context.value("reply_token", ""), token);
+
+    EXPECT_EQ(post_private_text(h, u8"你好", "m1", token, "ev1"), 200);  // 重投
+    const auto body = FakeLineServer::webhook_body(
+        {FakeLineServer::text_event(FakeLineServer::source("user", "", kUser), "evil", "m2", "", "ev2")});
+    EXPECT_EQ(FakeLineServer::post_webhook(h.webhook_url(), body, "ffffffffffffffffffffffffffffffff").status, 401);
+    EXPECT_EQ(FakeLineServer::post_webhook(h.webhook_url(), body, "").status, 401);
+    std::this_thread::sleep_for(std::chrono::milliseconds(300));
+    EXPECT_EQ(recorder.count(), 1u);
+}
+
+// 场景:群里一条 @机器人 的消息,一条普通闲聊。
+// 期望:两条都上报(是否回应由核心决定);前者 mentioned=true 且去掉了 @ 部分,后者 mentioned=false;
+// 群地址 chat = groupId、sender = 发言人。
+TEST(LineTransport, GroupMentionsAreDetected) {
+    Harness h;
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(h.options());
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+    const auto src = FakeLineServer::source("group", kGroup, kUser);
+    const nlohmann::json mention{{"mention", {{"mentionees", {{{"index", 0}, {"length", 4}, {"type", "user"},
+                                                               {"userId", FakeLineServer::kBotId}, {"isSelf", true}}}}}}};
+    const auto body = FakeLineServer::webhook_body(
+        {FakeLineServer::text_event(src, u8"@ACE 总结一下", "g1", h.server.issue_reply_token(), "eg1", mention),
+         FakeLineServer::text_event(src, u8"今天天气不错", "g2", h.server.issue_reply_token(), "eg2")});
+    EXPECT_EQ(FakeLineServer::post_webhook(h.webhook_url(), body).status, 200);
+    ASSERT_TRUE(FakeLineServer::wait_until([&recorder] { return recorder.count() == 2; }));
+    EXPECT_EQ(recorder.at(0).address.kind, ChatKind::Group);
+    EXPECT_EQ(recorder.at(0).address.chat, kGroup);
+    EXPECT_EQ(recorder.at(0).address.sender, kUser);
+    EXPECT_TRUE(recorder.at(0).mentioned);
+    EXPECT_EQ(recorder.at(0).text, u8"总结一下");
+    EXPECT_FALSE(recorder.at(1).mentioned);
+}
+
+// 场景:对一条新消息先回复一段 Markdown,再用同一上下文发第二段;之后对另一条消息发 7 段长回答。
+// 期望:第一段用回复令牌(免费,纯文本);令牌只能用一次,第二段改用推送并带重试键;
+// 7 段长回答:前 5 段一次回复,剩下 2 段一次推送。
+TEST(LineTransport, RepliesOnceThenPushesInBatchesOfFive) {
+    Harness h;
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(h.options());
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+    ASSERT_EQ(post_private_text(h, "q1", "m1", h.server.issue_reply_token(), "ev1"), 200);
+    ASSERT_TRUE(FakeLineServer::wait_until([&recorder] { return recorder.count() == 1; }));
+    const auto context = recorder.at(0).reply_context;
+
+    EXPECT_EQ(transport.send_text(private_address(), "**你好**", context).outcome, SendOutcome::Sent);
+    EXPECT_EQ(transport.send_text(private_address(), "second", context).outcome, SendOutcome::Sent);
+    const auto replies = h.server.calls_to("POST", "/v2/bot/message/reply");
+    ASSERT_EQ(replies.size(), 1u);
+    EXPECT_EQ(replies[0].body["messages"][0]["text"], u8"你好");
+    auto pushes = h.server.calls_to("POST", "/v2/bot/message/push");
+    ASSERT_EQ(pushes.size(), 1u);
+    EXPECT_EQ(pushes[0].body.value("to", ""), kUser);
+    EXPECT_EQ(pushes[0].body["messages"][0]["text"], "second");
+    EXPECT_FALSE(pushes[0].retry_key.empty());
+
+    ASSERT_EQ(post_private_text(h, "q2", "m2", h.server.issue_reply_token(), "ev2"), 200);
+    ASSERT_TRUE(FakeLineServer::wait_until([&recorder] { return recorder.count() == 2; }));
+    std::string long_text;
+    for (int i = 0; i < 7; ++i) long_text += (i ? "\n\n" : "") + std::string(4000, static_cast<char>('a' + i));
+    EXPECT_EQ(transport.send_text(private_address(), long_text, recorder.at(1).reply_context).outcome, SendOutcome::Sent);
+    const auto second_reply = h.server.calls_to("POST", "/v2/bot/message/reply");
+    ASSERT_EQ(second_reply.size(), 2u);
+    EXPECT_EQ(second_reply[1].body["messages"].size(), 5u);
+    pushes = h.server.calls_to("POST", "/v2/bot/message/push");
+    ASSERT_EQ(pushes.size(), 2u);
+    EXPECT_EQ(pushes[1].body["messages"].size(), 2u);
+    EXPECT_EQ(pushes[1].body["messages"][1]["text"].get<std::string>()[0], 'g');
+}
+
+// 场景:回复令牌已过期(2 分钟前收到),第一次推送遇到 500。
+// 期望:不尝试过期令牌,直接推送;5xx 后用同一个重试键重发(LINE 据此去重),最终成功。
+TEST(LineTransport, StaleTokenPushesAndRetriesWithSameKey) {
+    Harness h;
+    std::atomic<int> pushes{0};
+    h.server.override = [&pushes](const FakeLineServer::Call& call) -> std::optional<FakeLineServer::Reply> {
+        if (call.path != "/v2/bot/message/push" || ++pushes > 1) return std::nullopt;
+        return FakeLineServer::Reply{500, {{"message", "Internal error"}}, {}};
+    };
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(h.options());
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+    ReplyToken stale;
+    stale.token = h.server.issue_reply_token();
+    stale.received_at_ms = FakeLineServer::now_ms() - 120'000;
+    stale.event_ts_ms = stale.received_at_ms;
+    EXPECT_EQ(transport.send_text(private_address(), "late answer", make_reply_context(stale, "m9")).outcome,
+              SendOutcome::Sent);
+    EXPECT_TRUE(h.server.calls_to("POST", "/v2/bot/message/reply").empty());
+    const auto calls = h.server.calls_to("POST", "/v2/bot/message/push");
+    ASSERT_EQ(calls.size(), 2u);
+    EXPECT_FALSE(calls[0].retry_key.empty());
+    EXPECT_EQ(calls[0].retry_key, calls[1].retry_key);
+}
+
+// 场景:推送额度用完(429 “monthly limit”),期间有两段输出;随后对方又发来一条消息。
+// 期望:两段都暂存(第二段排在第一段后面),状态标出额度用完;新消息到来时先用它的回复令牌
+// 一次补发两段(第一段带“(补发)”),然后才把新消息交给核心。
+TEST(LineTransport, QuotaExhaustedOutputsAreHeldAndFlushedOnNextMessage) {
+    Harness h;
+    h.server.override = [](const FakeLineServer::Call& call) -> std::optional<FakeLineServer::Reply> {
+        if (call.path != "/v2/bot/message/push") return std::nullopt;
+        return FakeLineServer::Reply{429, {{"message", "You have reached your monthly limit."}}, {}};
+    };
+    std::atomic<std::size_t> replies_at_inbound{0};
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(h.options());
+    recorder.on_each = [&replies_at_inbound, &h] {
+        replies_at_inbound = h.server.calls_to("POST", "/v2/bot/message/reply").size();
+    };
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+
+    const auto first = transport.send_text(private_address(), u8"回答一", nlohmann::json::object());
+    EXPECT_EQ(first.outcome, SendOutcome::Held);
+    EXPECT_FALSE(first.error.empty());
+    EXPECT_EQ(transport.send_text(private_address(), u8"回答二", nlohmann::json::object()).outcome, SendOutcome::Held);
+    EXPECT_EQ(transport.held_count(), 2u);
+    EXPECT_TRUE(transport.status().extra.value("push_quota_exhausted", false));
+    EXPECT_EQ(h.server.calls_to("POST", "/v2/bot/message/push").size(), 1u);  // 第二段直接排队,不再撞墙
+
+    ASSERT_EQ(post_private_text(h, u8"在吗", "m5", h.server.issue_reply_token(), "ev5"), 200);
+    ASSERT_TRUE(FakeLineServer::wait_until([&recorder] { return recorder.count() == 1; }));
+    const auto replies = h.server.calls_to("POST", "/v2/bot/message/reply");
+    ASSERT_EQ(replies.size(), 1u);
+    EXPECT_EQ(replies_at_inbound.load(), 1u);  // 补发先于交给核心
+    ASSERT_EQ(replies[0].body["messages"].size(), 2u);
+    EXPECT_EQ(replies[0].body["messages"][0]["text"], u8"(补发)回答一");
+    EXPECT_EQ(replies[0].body["messages"][1]["text"], u8"回答二");
+    EXPECT_EQ(transport.held_count(), 0u);
+}
+
+// 场景:助手产出一张 PNG 截图和一个 PDF 报告。
+// 期望:图片作为 image 消息发出,地址是 <公网地址>/line/media/<令牌>/<文件名>,经回调端口能取回原文件;
+// PDF 改发一条说明(LINE 机器人不能发文件)。不存在的路径直接失败。
+TEST(LineTransport, SendsImagesViaMediaRouteAndNoticesForOtherFiles) {
+    Harness h;
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(h.options());
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+    const auto dir = std::filesystem::temp_directory_path() / "acecode-line-transport-test";
+    std::filesystem::create_directories(dir);
+    const auto png = dir / "shot.png";
+    const std::string bytes = "\x89PNG\r\n\x1a\nfake-image-bytes";
+    {
+        std::ofstream out(png, std::ios::binary);
+        out << bytes;
+    }
+    const auto pdf = dir / "report.pdf";
+    {
+        std::ofstream out(pdf, std::ios::binary);
+        out << "%PDF-1.4";
+    }
+    EXPECT_EQ(transport.send_file(private_address(), png, "shot.png", "image/png", nlohmann::json::object()).outcome,
+              SendOutcome::Sent);
+    auto pushes = h.server.calls_to("POST", "/v2/bot/message/push");
+    ASSERT_EQ(pushes.size(), 1u);
+    const auto message = pushes[0].body["messages"][0];
+    EXPECT_EQ(message["type"], "image");
+    const auto url = message.value("originalContentUrl", std::string{});
+    EXPECT_EQ(url.rfind(h.base() + "/line/media/", 0), 0u) << url;
+    EXPECT_EQ(message.value("previewImageUrl", ""), url);
+    const auto fetched = FakeLineServer::http_get(url);
+    EXPECT_EQ(fetched.status, 200);
+    EXPECT_EQ(fetched.body, bytes);
+    EXPECT_EQ(FakeLineServer::http_get(url + "x").status, 404);
+
+    EXPECT_EQ(transport.send_file(private_address(), pdf, "report.pdf", "application/pdf", nlohmann::json::object())
+                  .outcome,
+              SendOutcome::Sent);
+    pushes = h.server.calls_to("POST", "/v2/bot/message/push");
+    ASSERT_EQ(pushes.size(), 2u);
+    EXPECT_NE(pushes[1].body["messages"][0].value("text", "").find("不能发送文件"), std::string::npos);
+
+    EXPECT_EQ(transport.send_file(private_address(), dir / "missing.png", "missing.png", "image/png", {}).outcome,
+              SendOutcome::Failed);
+    std::error_code ec;
+    std::filesystem::remove_all(dir, ec);
+}
+
+// 场景:Channel secret 填错。
+// 期望:Failed 且停止重试,原因说明 Channel ID / secret 无效;不会反复换令牌。
+TEST(LineTransport, InvalidCredentialsStopRetrying) {
+    Harness h;
+    auto options = h.options();
+    options.api.channel_secret = "ffffffffffffffffffffffffffffffff";
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Failed));
+    const auto status = transport.status();
+    EXPECT_TRUE(status.retry_stopped);
+    EXPECT_NE(status.detail.find("Channel ID 或 Channel secret 无效"), std::string::npos);
+    EXPECT_EQ(status.detail.find(options.api.channel_secret), std::string::npos);
+    std::this_thread::sleep_for(std::chrono::milliseconds(300));
+    EXPECT_EQ(h.server.calls_to("POST", "/oauth2/v3/token").size(), 1u);
+}
+
+// 场景:没有填公网地址,电脑上也没装 cloudflared。
+// 期望:Failed 且停止重试,提示 winget 安装命令或填写自己的公网地址。
+TEST(LineTransport, MissingCloudflaredFailsWithInstallHint) {
+    Harness h;
+    auto options = h.options();
+    options.public_url.clear();
+    options.tunnel.locate = [] { return std::string{}; };
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Failed));
+    EXPECT_TRUE(transport.status().retry_stopped);
+    EXPECT_NE(transport.status().detail.find("winget install --id Cloudflare.cloudflared"), std::string::npos);
+    EXPECT_TRUE(h.server.endpoint().empty());
+}
+
+TunnelOptions fake_tunnel(const FakeCloudflared& fake) {
+    TunnelOptions tunnel;
+    tunnel.locate = [] { return std::string("C:/tools/cloudflared.exe"); };
+    tunnel.launch = fake.launcher();
+    tunnel.metrics_port = fake.metrics_port();
+    tunnel.url_scheme = "http";
+    tunnel.ready_timeout = std::chrono::seconds(5);
+    tunnel.poll_interval = std::chrono::milliseconds(20);
+    return tunnel;
+}
+
+// 场景:不填公网地址,用(假的)Cloudflare 快速隧道;随后 cloudflared 进程意外退出。
+// 期望:隧道指向回调端口(--url http://127.0.0.1:<端口>),经隧道地址自检后登记 webhook 并连上;
+// 进程退出后自动重启隧道并重新连上。
+TEST(LineTransport, QuickTunnelModeConnectsAndRestartsAfterExit) {
+    Harness h;
+    FakeCloudflared fake;
+    auto options = h.options();
+    options.public_url.clear();
+    options.listen_port = 0;
+    options.tunnel = fake_tunnel(fake);
+    options.watch_interval = std::chrono::milliseconds(100);
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+    const auto port = transport.listen_port();
+    ASSERT_NE(port, 0);
+    const auto local = "http://127.0.0.1:" + std::to_string(port);
+    EXPECT_EQ(h.server.endpoint(), local + "/line/webhook");
+    EXPECT_EQ(transport.status().extra.value("tunnel", ""), "cloudflare");
+    const auto argv = fake.last_argv();
+    EXPECT_NE(std::find(argv.begin(), argv.end(), local), argv.end());
+
+    fake.kill_current();
+    ASSERT_TRUE(FakeLineServer::wait_until([&fake] { return fake.launch_count() == 2; }));
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+    transport.stop();
+}
+
+// 场景:快速隧道每次重启主机名都会变(不做公网自检的配置下)。
+// 期望:重建隧道后把新地址重新登记给 LINE。
+TEST(LineTransport, NewTunnelHostnameIsRegisteredAgain) {
+    Harness h;
+    FakeCloudflared fake;
+    fake.state()->hostname_for = [](int launch, const std::string&) {
+        return "tunnel-" + std::to_string(launch) + ".test";
+    };
+    auto options = h.options();
+    options.public_url.clear();
+    options.listen_port = 0;
+    options.verify_public_url = false;
+    options.test_webhook = false;
+    options.tunnel = fake_tunnel(fake);
+    options.watch_interval = std::chrono::milliseconds(100);
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+    EXPECT_EQ(h.server.endpoint(), "http://tunnel-1.test/line/webhook");
+    fake.kill_current();
+    ASSERT_TRUE(FakeLineServer::wait_until(
+        [&h] { return h.server.endpoint() == "http://tunnel-2.test/line/webhook"; }));
+    EXPECT_EQ(h.server.calls_to("PUT", "/v2/bot/channel/webhook/endpoint").size(), 2u);
+}
+
+// 场景:“Use webhook” 开关在控制台没打开;过一会儿用户打开了它。
+// 期望:先处于重试中并提示去开 Use webhook(webhook 地址已登记好);开关打开后自动变为已连接。
+TEST(LineTransport, WaitsForUseWebhookSwitch) {
+    Harness h;
+    h.server.webhook_active = false;
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(h.options());
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(FakeLineServer::wait_until([&transport] {
+        const auto status = transport.status();
+        return status.state == LinkState::Retrying && status.detail.find("Use webhook") != std::string::npos;
+    }));
+    EXPECT_EQ(h.server.endpoint(), h.webhook_url());
+    h.server.webhook_active = true;
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    EXPECT_TRUE(transport.status().extra.value("webhook_active", false));
+}
+
+// 场景:核心在私聊与群聊里都打开“正在输入”。
+// 期望:私聊调用 loading/start(60 秒);群聊不调用(LINE 只允许一对一);关闭后不再续显。
+TEST(LineTransport, TypingUsesLoadingAnimationForPrivateChatsOnly) {
+    Harness h;
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(h.options());
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+    transport.set_typing(group_address(), true);
+    transport.set_typing(private_address(), true);
+    ASSERT_TRUE(FakeLineServer::wait_until(
+        [&h] { return !h.server.calls_to("POST", "/v2/bot/chat/loading/start").empty(); }));
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    const auto calls = h.server.calls_to("POST", "/v2/bot/chat/loading/start");
+    ASSERT_EQ(calls.size(), 1u);
+    EXPECT_EQ(calls[0].body.value("chatId", ""), kUser);
+    EXPECT_EQ(calls[0].body.value("loadingSeconds", 0), 60);
+    transport.set_typing(private_address(), false);
+    transport.set_typing(group_address(), false);
+}
+
+// 场景:群里机器人回答了一条消息;之后有人引用这条回答发言(没有 @);
+// 另有一位电脑版 LINE 用户(没有 userId)@了机器人。
+// 期望:引用机器人的消息视同点名,并带上被引用的文字;电脑版用户的消息不上报,
+// 但用免费回复令牌提示改用手机版。
+TEST(LineTransport, QuotedBotMessagesAndUnidentifiedSenders) {
+    Harness h;
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(h.options());
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected)) << transport.status().detail;
+    const auto src = FakeLineServer::source("group", kGroup, kUser);
+    const nlohmann::json mention{{"mention", {{"mentionees", {{{"index", 0}, {"length", 4}, {"type", "user"},
+                                                               {"isSelf", true}}}}}}};
+    auto body = FakeLineServer::webhook_body(
+        {FakeLineServer::text_event(src, u8"@ACE 几点了", "g1", h.server.issue_reply_token(), "eq1", mention)});
+    ASSERT_EQ(FakeLineServer::post_webhook(h.webhook_url(), body).status, 200);
+    ASSERT_TRUE(FakeLineServer::wait_until([&recorder] { return recorder.count() == 1; }));
+    ASSERT_EQ(transport.send_text(group_address(), u8"三点", recorder.at(0).reply_context).outcome, SendOutcome::Sent);
+    const auto reply = h.server.calls_to("POST", "/v2/bot/message/reply").at(0);
+    EXPECT_EQ(reply.body["messages"][0].value("quoteToken", ""), "q-g1");  // 群里引用提问的那条
+
+    const auto bot_message_id = std::string("9001");  // 假服务给第一条发出的消息分配的 id
+    body = FakeLineServer::webhook_body({FakeLineServer::text_event(
+        src, u8"为什么", "g2", h.server.issue_reply_token(), "eq2", {{"quotedMessageId", bot_message_id}})});
+    ASSERT_EQ(FakeLineServer::post_webhook(h.webhook_url(), body).status, 200);
+    ASSERT_TRUE(FakeLineServer::wait_until([&recorder] { return recorder.count() == 2; }));
+    EXPECT_TRUE(recorder.at(1).mentioned);
+    EXPECT_EQ(recorder.at(1).quote_text, u8"三点");
+
+    const auto desktop_token = h.server.issue_reply_token();
+    body = FakeLineServer::webhook_body({FakeLineServer::text_event(FakeLineServer::source("group", kGroup, ""),
+                                                                    u8"@ACE hi", "g3", desktop_token, "eq3", mention)});
+    ASSERT_EQ(FakeLineServer::post_webhook(h.webhook_url(), body).status, 200);
+    ASSERT_TRUE(FakeLineServer::wait_until(
+        [&h] { return h.server.calls_to("POST", "/v2/bot/message/reply").size() == 2; }));
+    const auto notice = h.server.calls_to("POST", "/v2/bot/message/reply").at(1);
+    EXPECT_EQ(notice.body.value("replyToken", ""), desktop_token);
+    EXPECT_NE(notice.body["messages"][0].value("text", "").find("手机版"), std::string::npos);
+    EXPECT_EQ(recorder.count(), 2u);
+}
+
+// 场景:收到一张图片后由核心下载;另有一个超过本地上限的文件。
+// 期望:按消息 id 从内容接口下载成功;超限的在下载前就拒绝。
+TEST(LineTransport, DownloadsAttachments) {
+    Harness h;
+    h.server.set_content("img7", "jpeg-bytes");
+    auto options = h.options();
+    options.max_download_bytes = 1024;
+    LineTransport transport(options);
+    Attachment image;
+    image.kind = AttachmentKind::Image;
+    image.remote_ref = "img7";
+    const auto dest = std::filesystem::temp_directory_path() / "acecode-line-download.bin";
+    std::string error;
+    ASSERT_TRUE(transport.download(image, dest, &error)) << error;
+    EXPECT_EQ(std::filesystem::file_size(dest), 10u);
+    Attachment big;
+    big.kind = AttachmentKind::File;
+    big.remote_ref = "img7";
+    big.size = 4096;
+    EXPECT_FALSE(transport.download(big, dest, &error));
+    EXPECT_EQ(error, "附件超过大小限制");
+    std::error_code ec;
+    std::filesystem::remove(dest, ec);
+}
+
+// 场景:回调端口收到超大请求体、未知路径、错误方法。
+// 期望:413 / 404 / 405,都不会进入解析。
+TEST(LineTransport, RouterRejectsOversizeUnknownAndWrongMethod) {
+    Harness h;
+    LineTransport transport(h.options());
+    ListenerRequest request;
+    request.method = "POST";
+    request.path = kWebhookRoute;
+    request.body = std::string(kMaxWebhookBodyBytes + 1, 'x');
+    EXPECT_EQ(transport.handle_request(request).status, 413);
+    request.path = "/api/sessions";
+    EXPECT_EQ(transport.handle_request(request).status, 404);
+    request.method = "GET";
+    request.path = kWebhookRoute;
+    EXPECT_EQ(transport.handle_request(request).status, 405);
+    request.path = kHealthRoute;
+    EXPECT_EQ(transport.handle_request(request).status, 200);
+}
+
+// 场景:隧道一直连不上边缘时用户关闭通道。
+// 期望:stop() 很快返回,之后状态为已停止。
+TEST(LineTransport, StopIsPromptWhileTunnelIsStarting) {
+    Harness h;
+    FakeCloudflared fake;
+    fake.state()->ready = false;
+    auto options = h.options();
+    options.public_url.clear();
+    options.tunnel = fake_tunnel(fake);
+    options.tunnel.ready_timeout = std::chrono::seconds(30);
+    Recorder recorder;  // 先于传输层声明:传输层析构(停机)时回调对象仍然有效
+    LineTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(FakeLineServer::wait_until([&fake] { return fake.launch_count() == 1; }));
+    const auto begin = std::chrono::steady_clock::now();
+    transport.stop();
+    EXPECT_LT(std::chrono::steady_clock::now() - begin, std::chrono::seconds(3));
+    EXPECT_EQ(transport.status().state, LinkState::Stopped);
+}
+
+} // namespace
+} // namespace acecode::im::line
diff --git a/tests/im/line_tunnel_test.cpp b/tests/im/line_tunnel_test.cpp
new file mode 100644
index 000000000..3ef06b6f1
--- /dev/null
+++ b/tests/im/line_tunnel_test.cpp
@@ -0,0 +1,194 @@
+#include <gtest/gtest.h>
+
+#include "im/line/line_tunnel.hpp"
+#include "test_support/im/fake_line_server.hpp"
+
+#include <algorithm>
+#include <atomic>
+#include <map>
+
+// im/line/line_tunnel:Cloudflare 快速隧道管理(假 cloudflared:指标服务 + 假子进程)。
+// 覆盖:命令行参数、/quicktunnel 解析、安装位置候选、启动并取得公网地址、未安装、
+// 进程提前退出、就绪超时、取消、空闲端口。不会启动真实 cloudflared,也不连 Cloudflare。
+
+namespace acecode::im::line {
+namespace {
+
+using test::FakeCloudflared;
+
+TunnelOptions fake_options(const FakeCloudflared& fake) {
+    TunnelOptions options;
+    options.locate = [] { return std::string("C:/tools/cloudflared.exe"); };
+    options.launch = fake.launcher();
+    options.metrics_port = fake.metrics_port();
+    options.url_scheme = "http";
+    options.ready_timeout = std::chrono::seconds(3);
+    options.poll_interval = std::chrono::milliseconds(20);
+    return options;
+}
+
+bool has_pair(const std::vector<std::string>& argv, const std::string& flag, const std::string& value) {
+    for (std::size_t i = 0; i + 1 < argv.size(); ++i)
+        if (argv[i] == flag && argv[i + 1] == value) return true;
+    return false;
+}
+
+// 场景:按选项拼 cloudflared 命令行(含可选的协议、配置文件、日志文件)。
+// 期望:关闭自动更新;指标服务只在 127.0.0.1;目标用 127.0.0.1 而不是 localhost(避免解析到 ::1);
+// 可选参数只在设置时出现。
+TEST(LineTunnel, BuildsCommandLine) {
+    TunnelOptions options;
+    auto argv = cloudflared_argv("cloudflared", 8123, 20241, options);
+    EXPECT_EQ(argv[0], "cloudflared");
+    EXPECT_EQ(argv[1], "tunnel");
+    EXPECT_NE(std::find(argv.begin(), argv.end(), "--no-autoupdate"), argv.end());
+    EXPECT_TRUE(has_pair(argv, "--metrics", "127.0.0.1:20241"));
+    EXPECT_TRUE(has_pair(argv, "--url", "http://127.0.0.1:8123"));
+    EXPECT_EQ(std::find(argv.begin(), argv.end(), "--protocol"), argv.end());
+
+    options.protocol = "http2";
+    options.config_path = "C:/data/empty.yml";
+    options.log_file = "C:/data/cloudflared.log";
+    argv = cloudflared_argv("cloudflared", 8123, 20241, options);
+    EXPECT_TRUE(has_pair(argv, "--protocol", "http2"));
+    EXPECT_TRUE(has_pair(argv, "--config", "C:/data/empty.yml"));
+    EXPECT_TRUE(has_pair(argv, "--logfile", "C:/data/cloudflared.log"));
+    EXPECT_EQ(argv.back(), "http://127.0.0.1:8123");
+}
+
+// 场景:指标服务 /quicktunnel 的几种应答。
+// 期望:只接受非空、只含主机名字符的值;未分配(空串)、带路径或注入字符、非 JSON 一律拒绝。
+TEST(LineTunnel, ParsesQuickTunnelHostname) {
+    EXPECT_EQ(parse_quicktunnel_hostname(R"({"hostname":"abc-def.trycloudflare.com"})").value_or(""),
+              "abc-def.trycloudflare.com");
+    EXPECT_FALSE(parse_quicktunnel_hostname(R"({"hostname":""})").has_value());
+    EXPECT_FALSE(parse_quicktunnel_hostname(R"({"hostname":"evil.com/path"})").has_value());
+    EXPECT_FALSE(parse_quicktunnel_hostname(R"({"hostname":"a b"})").has_value());
+    EXPECT_FALSE(parse_quicktunnel_hostname("OK\n").has_value());
+}
+
+// 场景:Windows 上 winget 便携版、MSI(x86 / x64 目录)的安装位置;某个环境变量缺失。
+// 期望:按 WinGet Links → Program Files (x86) → Program Files 的顺序给出候选;缺失的变量跳过。
+TEST(LineTunnel, InstallCandidatesFollowWindowsLayout) {
+    std::map<std::string, std::string> env{{"LOCALAPPDATA", "C:\\Users\\u\\AppData\\Local"},
+                                           {"ProgramFiles", "C:\\Program Files"}};
+    const auto candidates = cloudflared_install_candidates([&env](const char* name) {
+        const auto it = env.find(name);
+        return it == env.end() ? std::string{} : it->second;
+    });
+    ASSERT_EQ(candidates.size(), 2u);
+    EXPECT_EQ(candidates[0], "C:\\Users\\u\\AppData\\Local\\Microsoft\\WinGet\\Links\\cloudflared.exe");
+    EXPECT_EQ(candidates[1], "C:\\Program Files\\cloudflared\\cloudflared.exe");
+}
+
+// 场景:启动隧道,假 cloudflared 很快分配主机名并就绪。
+// 期望:返回 <scheme>://<主机名>;启动参数指向给定的回调端口;stop 后进程被结束、地址清空。
+TEST(LineTunnel, StartsAndReportsPublicUrl) {
+    FakeCloudflared fake;
+    CloudflareTunnel tunnel(fake_options(fake));
+    TunnelFailure failure = TunnelFailure::Cancelled;
+    std::string error;
+    const auto url = tunnel.start(9555, {}, &failure, &error);
+    EXPECT_EQ(url, "http://127.0.0.1:9555") << error;
+    EXPECT_EQ(failure, TunnelFailure::None);
+    EXPECT_TRUE(tunnel.alive());
+    EXPECT_TRUE(tunnel.ready());
+    EXPECT_TRUE(has_pair(fake.last_argv(), "--url", "http://127.0.0.1:9555"));
+    EXPECT_TRUE(has_pair(fake.last_argv(), "--metrics", "127.0.0.1:" + std::to_string(fake.metrics_port())));
+    tunnel.stop();
+    EXPECT_FALSE(tunnel.alive());
+    EXPECT_TRUE(tunnel.public_url().empty());
+}
+
+// 场景:电脑上没装 cloudflared。
+// 期望:失败类型为 Missing,原因里给出 winget 安装命令与“填写自己的公网地址”两条出路。
+TEST(LineTunnel, MissingCloudflaredGivesInstallHint) {
+    FakeCloudflared fake;
+    auto options = fake_options(fake);
+    options.locate = [] { return std::string{}; };
+    CloudflareTunnel tunnel(options);
+    TunnelFailure failure = TunnelFailure::None;
+    std::string error;
+    EXPECT_TRUE(tunnel.start(9555, {}, &failure, &error).empty());
+    EXPECT_EQ(failure, TunnelFailure::Missing);
+    EXPECT_NE(error.find("winget install --id Cloudflare.cloudflared"), std::string::npos);
+    EXPECT_NE(error.find("公网"), std::string::npos);
+    EXPECT_EQ(fake.launch_count(), 0u);
+}
+
+// 场景:cloudflared 启动后还没就绪就退出了(例如 trycloudflare.com 限流)。
+// 期望:不会一直等到超时,立即以 Exited 失败返回。
+TEST(LineTunnel, ProcessExitBeforeReadyFailsFast) {
+    FakeCloudflared fake;
+    fake.state()->hostname_for = [](int, const std::string&) { return std::string{}; };  // 一直拿不到主机名
+    auto options = fake_options(fake);
+    options.ready_timeout = std::chrono::seconds(30);
+    auto launch = options.launch;
+    options.launch = [launch](const std::vector<std::string>& argv, std::string* error) {
+        auto process = launch(argv, error);
+        process->stop();  // 立刻“退出”
+        return process;
+    };
+    CloudflareTunnel tunnel(options);
+    TunnelFailure failure = TunnelFailure::None;
+    std::string error;
+    const auto begin = std::chrono::steady_clock::now();
+    EXPECT_TRUE(tunnel.start(9555, {}, &failure, &error).empty());
+    EXPECT_EQ(failure, TunnelFailure::Exited);
+    EXPECT_LT(std::chrono::steady_clock::now() - begin, std::chrono::seconds(5));
+}
+
+// 场景:主机名已分配,但一直连不上 Cloudflare 边缘(/ready 503)。
+// 期望:等到 ready_timeout 后以 Timeout 失败,并结束子进程。
+TEST(LineTunnel, NeverReadyTimesOut) {
+    FakeCloudflared fake;
+    fake.state()->ready = false;
+    auto options = fake_options(fake);
+    options.ready_timeout = std::chrono::milliseconds(300);
+    CloudflareTunnel tunnel(options);
+    TunnelFailure failure = TunnelFailure::None;
+    std::string error;
+    EXPECT_TRUE(tunnel.start(9555, {}, &failure, &error).empty());
+    EXPECT_EQ(failure, TunnelFailure::Timeout);
+    EXPECT_FALSE(tunnel.alive());
+}
+
+// 场景:等待就绪期间用户关闭了通道(取消)。
+// 期望:很快以 Cancelled 返回并结束子进程。
+TEST(LineTunnel, CancelStopsWaiting) {
+    FakeCloudflared fake;
+    fake.state()->ready = false;
+    auto options = fake_options(fake);
+    options.ready_timeout = std::chrono::seconds(30);
+    CloudflareTunnel tunnel(options);
+    std::atomic<int> polls{0};
+    TunnelFailure failure = TunnelFailure::None;
+    std::string error;
+    const auto begin = std::chrono::steady_clock::now();
+    EXPECT_TRUE(tunnel.start(9555, [&polls] { return ++polls > 5; }, &failure, &error).empty());
+    EXPECT_EQ(failure, TunnelFailure::Cancelled);
+    EXPECT_FALSE(tunnel.alive());
+    EXPECT_LT(std::chrono::steady_clock::now() - begin, std::chrono::seconds(5));
+}
+
+// 场景:启动子进程本身失败。
+// 期望:以 Launch 失败,原因带上启动错误。
+TEST(LineTunnel, LaunchFailureIsReported) {
+    FakeCloudflared fake;
+    fake.state()->fail_launch = true;
+    CloudflareTunnel tunnel(fake_options(fake));
+    TunnelFailure failure = TunnelFailure::None;
+    std::string error;
+    EXPECT_TRUE(tunnel.start(9555, {}, &failure, &error).empty());
+    EXPECT_EQ(failure, TunnelFailure::Launch);
+    EXPECT_NE(error.find("fake launch failure"), std::string::npos);
+}
+
+// 场景:为 cloudflared 指标服务挑本机空闲端口。
+// 期望:返回非 0 端口。
+TEST(LineTunnel, PicksFreeLoopbackPort) {
+    EXPECT_NE(pick_free_loopback_port(), 0);
+}
+
+} // namespace
+} // namespace acecode::im::line
diff --git a/tests/im/markdown_test.cpp b/tests/im/markdown_test.cpp
new file mode 100644
index 000000000..25ac82123
--- /dev/null
+++ b/tests/im/markdown_test.cpp
@@ -0,0 +1,85 @@
+#include <gtest/gtest.h>
+
+#include "im/markdown.hpp"
+
+#include <string>
+
+// im/markdown:助手回复在 Telegram 上以 HTML 子集发送,在 QQ Markdown 被拒时退回纯文本。
+// 关键约束:Telegram 的 HTML 解析很严格,标签必须成对,文本里的 < > & 必须转义。
+
+namespace acecode::im {
+namespace {
+
+std::size_t count(const std::string& text, const std::string& needle) {
+    std::size_t n = 0, pos = 0;
+    while ((pos = text.find(needle, pos)) != std::string::npos) {
+        ++n;
+        pos += needle.size();
+    }
+    return n;
+}
+
+// 场景:代码块里含有 < > & 和看起来像 Markdown 的 **x**。
+// 期望:整体放进 <pre><code class="language-cpp">,内容只做转义、不做任何格式化。
+TEST(ImMarkdown, CodeBlockIsEscapedVerbatim) {
+    const auto html = markdown_to_telegram_html("```cpp\nif (a < b && **x**) {}\n```");
+    EXPECT_EQ(html, "<pre><code class=\"language-cpp\">if (a &lt; b &amp;&amp; **x**) {}</code></pre>");
+}
+
+// 场景:行内代码、粗体、斜体、删除线混排。
+// 期望:分别转成 code/b/i/s 标签,行内代码里的 < 被转义。
+TEST(ImMarkdown, InlineFormatting) {
+    EXPECT_EQ(markdown_to_telegram_html("use `a<b` and **bold** *it* ~~old~~"),
+              "use <code>a&lt;b</code> and <b>bold</b> <i>it</i> <s>old</s>");
+}
+
+// 场景:snake_case 标识符和 2 * 3 * 4 这样的算式里出现 _ 和 *。
+// 期望:不被误判成斜体,原样输出。
+TEST(ImMarkdown, IdentifiersAndArithmeticAreNotEmphasis) {
+    EXPECT_EQ(markdown_to_telegram_html("call my_long_function_name now"),
+              "call my_long_function_name now");
+    EXPECT_EQ(markdown_to_telegram_html("2 * 3 * 4"), "2 * 3 * 4");
+}
+
+// 场景:安全链接与 javascript: 链接。
+// 期望:http(s) 链接转成 <a href>;javascript: 链接不生成标签,按文字输出。
+TEST(ImMarkdown, OnlySafeLinksBecomeAnchors) {
+    EXPECT_EQ(markdown_to_telegram_html("see [docs](https://example.com/a?b=1&c=2)"),
+              "see <a href=\"https://example.com/a?b=1&amp;c=2\">docs</a>");
+    EXPECT_EQ(markdown_to_telegram_html("[x](javascript:alert(1))"), "[x](javascript:alert(1))");
+}
+
+// 场景:标题、无序列表、有序列表、引用、分隔线。
+// 期望:标题变粗体,列表变“• ”,有序编号保留,连续引用行合并进一个 blockquote。
+TEST(ImMarkdown, BlockElements) {
+    const auto html = markdown_to_telegram_html("# Title\n- one\n2. two\n> q1\n> q2\n---");
+    EXPECT_EQ(html, "<b>Title</b>\n• one\n2. two\n<blockquote>q1\nq2</blockquote>\n——————");
+}
+
+// 场景:未闭合的粗体标记、孤立的反引号、普通文本里的尖括号。
+// 期望:按字面输出并转义;生成的 HTML 里开闭标签数量一致。
+TEST(ImMarkdown, UnclosedMarkersStayLiteralAndTagsBalance) {
+    const auto html = markdown_to_telegram_html("**open and `tick <tag> & more");
+    EXPECT_EQ(html, "**open and `tick &lt;tag&gt; &amp; more");
+    const auto mixed = markdown_to_telegram_html("**a *b* c** and __d__ `e` ~~f~~");
+    EXPECT_EQ(count(mixed, "<b>"), count(mixed, "</b>"));
+    EXPECT_EQ(count(mixed, "<i>"), count(mixed, "</i>"));
+    EXPECT_EQ(count(mixed, "<s>"), count(mixed, "</s>"));
+}
+
+// 场景:表格。
+// 期望:整张表放进 <pre> 保持对齐,单元格里的 < 被转义。
+TEST(ImMarkdown, TablesBecomePreformatted) {
+    EXPECT_EQ(markdown_to_telegram_html("| a | b |\n|---|---|\n| 1 | <2 |"),
+              "<pre>| a | b |\n|---|---|\n| 1 | &lt;2 |</pre>");
+}
+
+// 场景:QQ Markdown 被拒后回退纯文本。
+// 期望:去掉粗体/代码围栏/标题标记,链接变成“文字 (地址)”,不做 HTML 转义。
+TEST(ImMarkdown, PlainFallbackStripsMarkers) {
+    EXPECT_EQ(markdown_to_plain("# 标题\n**粗体** 和 [链接](https://a.b)\n```\nx < y\n```"),
+              "标题\n粗体 和 链接 (https://a.b)\nx < y");
+}
+
+} // namespace
+} // namespace acecode::im
diff --git a/tests/im/qq_api_test.cpp b/tests/im/qq_api_test.cpp
new file mode 100644
index 000000000..ba9a589ef
--- /dev/null
+++ b/tests/im/qq_api_test.cpp
@@ -0,0 +1,140 @@
+#include <gtest/gtest.h>
+
+#include "im/qqbot/qq_api.hpp"
+#include "test_support/im/fake_qq_server.hpp"
+
+#include <fstream>
+
+// im/qqbot/qq_api:QQ OpenAPI 客户端,对着本机假开放平台跑。
+
+namespace acecode::im::qqbot {
+namespace {
+
+ApiOptions local_options(const test::FakeQqServer& server) {
+    ApiOptions options;
+    options.app_id = "APP";
+    options.app_secret = "secret-value-123";
+    options.api_base = server.base();
+    options.token_url = server.base() + "/app/getAppAccessToken";
+    options.use_proxy = false;
+    return options;
+}
+
+// 场景:连续两次取令牌。
+// 期望:第一次向平台换取,第二次直接复用缓存;请求体带 appId 与 clientSecret。
+TEST(QqApi, FetchesAndCachesAccessToken) {
+    test::FakeQqServer server;
+    nlohmann::json seen;
+    server.token_handler = [&](const nlohmann::json& body) {
+        seen = body;
+        return nlohmann::json{{"access_token", "tok-A"}, {"expires_in", "7200"}};
+    };
+    Api api(local_options(server));
+    std::string error;
+    EXPECT_EQ(api.access_token(&error), "tok-A") << error;
+    EXPECT_EQ(api.access_token(&error), "tok-A");
+    EXPECT_EQ(server.token_calls(), 1);
+    EXPECT_EQ(seen.value("appId", ""), "APP");
+    EXPECT_EQ(seen.value("clientSecret", ""), "secret-value-123");
+}
+
+// 场景:凭据错误时平台仍返回 HTTP 200,只是带 code=100007。
+// 期望:取令牌失败、标记为凭据被拒(调用方据此停止重试),错误信息里不含 AppSecret。
+TEST(QqApi, InvalidCredentialsAreReportedAsAuthFailure) {
+    test::FakeQqServer server;
+    server.token_handler = [](const nlohmann::json&) {
+        return nlohmann::json{{"code", 100007}, {"message", "appid invalid"}};
+    };
+    Api api(local_options(server));
+    std::string error;
+    EXPECT_TRUE(api.access_token(&error).empty());
+    EXPECT_TRUE(api.last_token_auth_failed());
+    EXPECT_NE(error.find("appid invalid"), std::string::npos) << error;
+    EXPECT_EQ(error.find("secret-value-123"), std::string::npos) << error;
+    EXPECT_FALSE(api.verify(&error));
+}
+
+// 场景:取网关地址,以及发一条单聊消息。
+// 期望:请求都带 "QQBot <令牌>" 鉴权头;网关地址原样返回;消息体原样送达。
+TEST(QqApi, GatewayAndSendUseBotAuthorization) {
+    test::FakeQqServer server;
+    Api api(local_options(server));
+    std::string error;
+    const auto url = api.gateway_url(&error);
+    EXPECT_NE(url.find("/websocket"), std::string::npos) << error;
+    const auto result = api.send_message("c2c", "U1", {{"content", "hi"}, {"msg_type", 0}});
+    EXPECT_TRUE(result.ok) << result.error.message;
+    const auto sent = server.requests_to("/v2/users/U1/messages");
+    ASSERT_EQ(sent.size(), 1u);
+    EXPECT_EQ(sent[0].authorization, "QQBot tok-1");
+    EXPECT_EQ(sent[0].body.value("content", ""), "hi");
+}
+
+// 场景:平台对第一次发送返回 401(令牌在本地缓存期内被吊销)。
+// 期望:客户端作废令牌、重新换取后重发一次,最终成功;令牌接口被调用两次。
+TEST(QqApi, RetriesOnceAfterUnauthorized) {
+    test::FakeQqServer server;
+    int calls = 0;
+    server.message_handler = [&](const test::FakeQqServer::Request&) {
+        ++calls;
+        if (calls == 1) return std::make_pair(401, nlohmann::json{{"message", "token expired"}});
+        return std::make_pair(200, nlohmann::json{{"id", "R"}});
+    };
+    Api api(local_options(server));
+    const auto result = api.send_message("group", "G1", {{"content", "x"}, {"msg_type", 0}});
+    EXPECT_TRUE(result.ok) << result.error.message;
+    EXPECT_EQ(server.token_calls(), 2);
+    const auto sent = server.requests_to("/v2/groups/G1/messages");
+    ASSERT_EQ(sent.size(), 2u);
+    EXPECT_EQ(sent[1].authorization, "QQBot tok-2");
+}
+
+// 场景:平台以 400 拒绝发送。
+// 期望:返回失败并带平台给的错误码与原因,不重试。
+TEST(QqApi, ClientErrorsAreReturnedWithoutRetry) {
+    test::FakeQqServer server;
+    server.message_handler = [](const test::FakeQqServer::Request&) {
+        return std::make_pair(400, nlohmann::json{{"code", 40034}, {"message", "msg_id expired"}});
+    };
+    Api api(local_options(server));
+    const auto result = api.send_message("c2c", "U1", {{"content", "x"}});
+    EXPECT_FALSE(result.ok);
+    EXPECT_EQ(result.error.status, 400);
+    EXPECT_EQ(result.error.code, 40034);
+    EXPECT_EQ(server.requests_to("/v2/users/U1/messages").size(), 1u);
+}
+
+// 场景:上传一个普通文件到群。
+// 期望:请求体包含 file_type=4、base64 数据、文件名,且不直接发送(srv_send_msg=false);返回 file_info。
+TEST(QqApi, UploadsFileAsBase64) {
+    test::FakeQqServer server;
+    Api api(local_options(server));
+    const auto result = api.upload_file("group", "G1", kFileTypeFile, "aGVsbG8=", "r.pdf");
+    ASSERT_TRUE(result.ok) << result.error.message;
+    EXPECT_EQ(result.response.value("file_info", ""), "INFO-1");
+    const auto uploads = server.requests_to("/v2/groups/G1/files");
+    ASSERT_EQ(uploads.size(), 1u);
+    EXPECT_EQ(uploads[0].body.value("file_type", 0), kFileTypeFile);
+    EXPECT_EQ(uploads[0].body.value("file_data", ""), "aGVsbG8=");
+    EXPECT_EQ(uploads[0].body.value("file_name", ""), "r.pdf");
+    EXPECT_FALSE(uploads[0].body.value("srv_send_msg", true));
+}
+
+// 场景:下载附件,一个在上限内,一个超过上限。
+// 期望:前者写入目标文件并带鉴权头;后者失败且不留下半截文件。
+TEST(QqApi, DownloadsWithAuthAndSizeLimit) {
+    test::FakeQqServer server;
+    Api api(local_options(server));
+    const auto dir = std::filesystem::path(testing::TempDir()) / "acecode-qq-api-download";
+    std::filesystem::create_directories(dir);
+    std::string error;
+    ASSERT_TRUE(api.download(server.base() + "/download/small", dir / "small.bin", 1024, &error)) << error;
+    EXPECT_EQ(std::filesystem::file_size(dir / "small.bin"), 16u);
+    EXPECT_EQ(server.requests_to("/download/small").at(0).authorization, "QQBot tok-1");
+    EXPECT_FALSE(api.download(server.base() + "/download/big", dir / "big.bin", 1024, &error));
+    EXPECT_FALSE(std::filesystem::exists(dir / "big.bin"));
+    std::filesystem::remove_all(dir);
+}
+
+} // namespace
+} // namespace acecode::im::qqbot
diff --git a/tests/im/qq_bind_test.cpp b/tests/im/qq_bind_test.cpp
new file mode 100644
index 000000000..32cabce79
--- /dev/null
+++ b/tests/im/qq_bind_test.cpp
@@ -0,0 +1,137 @@
+#include <gtest/gtest.h>
+
+#include "im/qqbot/qq_bind.hpp"
+#include "test_support/im/fake_qq_server.hpp"
+
+#include <thread>
+
+// im/qqbot/qq_bind:QQ 机器人扫码配置流程。用本机假门户代替 q.qq.com;
+// 加密向量用固定密钥(0x00..0x1f)与 IV,由 Python cryptography 预先算出。
+
+namespace acecode::im::qqbot {
+namespace {
+
+constexpr const char* kKeyB64 = "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=";
+constexpr const char* kSecretB64 = "ZGVmZ2hpamtsbW5vOWrzEhyaIrNNBzyavxFHGfpv4JwMQcJAlM16v321wbiQ0njyP4fhqnk=";
+
+std::string fixed_key() {
+    std::string key;
+    for (int i = 0; i < 32; ++i) key.push_back(static_cast<char>(i));
+    return key;
+}
+
+BindOptions local_options(const test::FakeQqServer& server) {
+    BindOptions options;
+    options.portal_base = server.base();
+    options.connect_base = "https://q.qq.com";
+    options.use_proxy = false;
+    options.poll_interval = std::chrono::milliseconds(20);
+    options.total_timeout = std::chrono::seconds(5);
+    options.key_provider = fixed_key;
+    return options;
+}
+
+// 场景:用户扫码,门户第一次轮询返回“进行中”,第二次返回完成并带加密密钥与扫码人。
+// 期望:先回调一次显示二维码(指向正式门户、来源 acecode);最终返回完成,
+// 解密出的 AppSecret 与预设明文一致;申请任务时上传的是本地生成的密钥。
+TEST(QqBind, CompletesAndDecryptsSecret) {
+    test::FakeQqServer server;
+    int polls = 0;
+    server.poll_bind_handler = [&](const nlohmann::json&) {
+        ++polls;
+        if (polls < 2) return nlohmann::json{{"retcode", 0}, {"data", {{"status", 1}}}};
+        return nlohmann::json{{"retcode", 0},
+                              {"data", {{"status", 2}, {"bot_appid", 102030405},
+                                        {"bot_encrypt_secret", kSecretB64}, {"user_openid", "OWNER1"}}}};
+    };
+    std::vector<BindUpdate> updates;
+    std::atomic<bool> cancelled{false};
+    const auto result = run_bind(local_options(server), cancelled,
+                                 [&](const BindUpdate& u) { updates.push_back(u); });
+    ASSERT_EQ(result.phase, BindPhase::Completed) << result.error;
+    EXPECT_EQ(result.app_id, "102030405");
+    EXPECT_EQ(result.app_secret, u8"qq-test-secret-中文-123");
+    EXPECT_EQ(result.user_openid, "OWNER1");
+    ASSERT_EQ(updates.size(), 1u);
+    EXPECT_EQ(updates[0].qr_url, "https://q.qq.com/qqbot/openclaw/connect.html?task_id=task-1&source=acecode&_wv=2");
+    const auto created = server.requests_to("/lite/create_bind_task");
+    ASSERT_EQ(created.size(), 1u);
+    EXPECT_EQ(created[0].body.value("key", ""), kKeyB64);
+}
+
+// 场景:第一张二维码过期(status 3),门户再给一个新任务。
+// 期望:自动换新任务,二维码回调两次且地址不同,最终完成且 refreshes = 1。
+TEST(QqBind, RefreshesExpiredQrCode) {
+    test::FakeQqServer server;
+    int created = 0;
+    server.create_bind_handler = [&](const nlohmann::json&) {
+        ++created;
+        return nlohmann::json{{"retcode", 0}, {"data", {{"task_id", "task-" + std::to_string(created)}}}};
+    };
+    server.poll_bind_handler = [&](const nlohmann::json& body) {
+        if (body.value("task_id", "") == "task-1") return nlohmann::json{{"retcode", 0}, {"data", {{"status", 3}}}};
+        return nlohmann::json{{"retcode", 0},
+                              {"data", {{"status", 2}, {"bot_appid", "APP"}, {"bot_encrypt_secret", kSecretB64}}}};
+    };
+    std::vector<std::string> urls;
+    std::atomic<bool> cancelled{false};
+    const auto result = run_bind(local_options(server), cancelled,
+                                 [&](const BindUpdate& u) { urls.push_back(u.qr_url); });
+    ASSERT_EQ(result.phase, BindPhase::Completed) << result.error;
+    EXPECT_EQ(result.refreshes, 1);
+    ASSERT_EQ(urls.size(), 2u);
+    EXPECT_NE(urls[0], urls[1]);
+    EXPECT_TRUE(result.user_openid.empty());
+}
+
+// 场景:二维码已显示,用户在扫码前点了取消。
+// 期望:流程很快返回 Cancelled,不产生任何凭据。
+TEST(QqBind, CancelStopsQuickly) {
+    test::FakeQqServer server;
+    std::atomic<bool> cancelled{false};
+    auto options = local_options(server);
+    options.poll_interval = std::chrono::seconds(10);
+    BindUpdate result;
+    std::thread runner([&] { result = run_bind(options, cancelled, {}); });
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return !server.requests_to("/lite/create_bind_task").empty(); }));
+    const auto start = std::chrono::steady_clock::now();
+    cancelled = true;
+    runner.join();
+    EXPECT_EQ(result.phase, BindPhase::Cancelled);
+    EXPECT_TRUE(result.app_secret.empty());
+    EXPECT_LT(std::chrono::steady_clock::now() - start, std::chrono::seconds(2));
+}
+
+// 场景:门户拒绝创建任务(retcode 非 0),以及一直没人扫码直到总超时。
+// 期望:前者返回 Failed 并带门户给的原因;后者返回 TimedOut。
+TEST(QqBind, ReportsPortalFailureAndTimeout) {
+    test::FakeQqServer server;
+    server.create_bind_handler = [](const nlohmann::json&) {
+        return nlohmann::json{{"retcode", 1001}, {"msg", "source not allowed"}};
+    };
+    std::atomic<bool> cancelled{false};
+    const auto failed = run_bind(local_options(server), cancelled, {});
+    EXPECT_EQ(failed.phase, BindPhase::Failed);
+    EXPECT_NE(failed.error.find("source not allowed"), std::string::npos) << failed.error;
+
+    test::FakeQqServer idle;
+    auto options = local_options(idle);
+    options.total_timeout = std::chrono::milliseconds(300);
+    EXPECT_EQ(run_bind(options, cancelled, {}).phase, BindPhase::TimedOut);
+}
+
+// 场景:扫码结果里的密文被篡改,或用错了密钥。
+// 期望:解密失败,不返回任何明文。
+TEST(QqBind, RejectsTamperedSecret) {
+    std::string secret, error;
+    EXPECT_TRUE(decrypt_bind_secret(kSecretB64, kKeyB64, secret, &error)) << error;
+    std::string tampered = kSecretB64;
+    tampered[20] = tampered[20] == 'A' ? 'B' : 'A';
+    secret.clear();
+    EXPECT_FALSE(decrypt_bind_secret(tampered, kKeyB64, secret, &error));
+    EXPECT_TRUE(secret.empty());
+    EXPECT_FALSE(decrypt_bind_secret("not base64!", kKeyB64, secret, &error));
+}
+
+} // namespace
+} // namespace acecode::im::qqbot
diff --git a/tests/im/qq_gateway_test.cpp b/tests/im/qq_gateway_test.cpp
new file mode 100644
index 000000000..007ed6a6d
--- /dev/null
+++ b/tests/im/qq_gateway_test.cpp
@@ -0,0 +1,131 @@
+#include <gtest/gtest.h>
+
+#include "im/qqbot/qq_gateway.hpp"
+
+// im/qqbot/qq_gateway:QQ 网关会话状态机。全部用假时间驱动,不碰网络。
+
+namespace acecode::im::qqbot {
+namespace {
+
+using Clock = GatewaySession::Clock;
+using std::chrono::milliseconds;
+
+nlohmann::json parse(const std::string& text) { return nlohmann::json::parse(text); }
+
+std::string hello(int interval_ms) {
+    return nlohmann::json{{"op", 10}, {"d", {{"heartbeat_interval", interval_ms}}}}.dump();
+}
+
+std::string ready(int seq) {
+    return nlohmann::json{{"op", 0}, {"t", "READY"}, {"s", seq},
+                          {"d", {{"session_id", "S1"}, {"user", {{"id", "B1"}, {"username", "Bot"}}}}}}
+        .dump();
+}
+
+// 场景:新连接收到 Hello(心跳间隔 10 秒)。
+// 期望:回 Identify,带 "QQBot <令牌>" 与只订阅单聊/群 @ 的 intents;心跳按 80% 即 8 秒发送。
+TEST(QqGateway, HelloTriggersIdentifyAndHeartbeatInterval) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0);
+    const auto out = session.on_frame(hello(10000), t0);
+    ASSERT_EQ(out.frames.size(), 1u);
+    const auto identify = parse(out.frames[0]);
+    EXPECT_EQ(identify["op"], 2);
+    EXPECT_EQ(identify["d"]["token"], "QQBot tok");
+    EXPECT_EQ(identify["d"]["intents"], kIntents);
+    EXPECT_EQ(session.heartbeat_interval(), milliseconds(8000));
+}
+
+// 场景:收到 READY 与之后的一条单聊消息事件。
+// 期望:READY 让连接可用并记下 session_id 与机器人名;消息事件作为派发交给上层;seq 跟着更新。
+TEST(QqGateway, ReadyAndDispatchUpdateSessionAndSequence) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0);
+    session.on_frame(hello(10000), t0);
+    const auto r = session.on_frame(ready(1), t0);
+    EXPECT_TRUE(r.ready);
+    EXPECT_EQ(r.bot_name, "Bot");
+    EXPECT_EQ(session.session_id(), "S1");
+    const auto m = session.on_frame(
+        nlohmann::json{{"op", 0}, {"t", "C2C_MESSAGE_CREATE"}, {"s", 2}, {"d", {{"id", "M1"}}}}.dump(), t0);
+    ASSERT_EQ(m.dispatches.size(), 1u);
+    EXPECT_EQ(m.dispatches[0].first, "C2C_MESSAGE_CREATE");
+    EXPECT_EQ(session.last_seq(), 2);
+}
+
+// 场景:心跳到期前、到期时、以及发出心跳后一直没收到 ACK 又到下一次到期。
+// 期望:到期前不发;到期发出带最新 seq 的心跳;没等到 ACK 再到期时判定连接假死;
+// 收到 ACK 后恢复正常心跳。
+TEST(QqGateway, HeartbeatScheduleAndZombieDetection) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0);
+    session.on_frame(hello(10000), t0);
+    session.on_frame(ready(5), t0);
+    EXPECT_FALSE(session.on_tick(t0 + milliseconds(7000)).heartbeat);
+    const auto beat = session.on_tick(t0 + milliseconds(8000));
+    ASSERT_TRUE(beat.heartbeat);
+    EXPECT_EQ(parse(*beat.heartbeat)["d"], 5);
+    EXPECT_TRUE(session.on_tick(t0 + milliseconds(16000)).zombie);
+    session.on_frame(R"({"op":11})", t0 + milliseconds(16000));
+    EXPECT_TRUE(session.on_tick(t0 + milliseconds(16001)).heartbeat);
+}
+
+// 场景:普通断线(1006)后重连,再次收到 Hello。
+// 期望:用 Resume(op 6)带上原 session_id 与 seq 恢复会话,而不是重新登录。
+TEST(QqGateway, ResumesAfterOrdinaryDisconnect) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0);
+    session.on_frame(hello(10000), t0);
+    session.on_frame(ready(7), t0);
+    EXPECT_EQ(session.on_closed(1006).action, CloseAction::Resume);
+    session.on_connected("tok2", t0);
+    const auto out = session.on_frame(hello(10000), t0);
+    ASSERT_EQ(out.frames.size(), 1u);
+    const auto resume = parse(out.frames[0]);
+    EXPECT_EQ(resume["op"], 6);
+    EXPECT_EQ(resume["d"]["session_id"], "S1");
+    EXPECT_EQ(resume["d"]["seq"], 7);
+    EXPECT_EQ(resume["d"]["token"], "QQBot tok2");
+}
+
+// 场景:因会话失效(4009)断开,或服务端发来 op 9(d=false)。
+// 期望:会话被清掉,下一次连接重新 Identify。
+TEST(QqGateway, InvalidSessionForcesFreshIdentify) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0);
+    session.on_frame(hello(10000), t0);
+    session.on_frame(ready(3), t0);
+    EXPECT_EQ(session.on_closed(4009).action, CloseAction::Identify);
+    EXPECT_FALSE(session.can_resume());
+
+    session.on_connected("tok", t0);
+    session.on_frame(hello(10000), t0);
+    session.on_frame(ready(4), t0);
+    const auto invalid = session.on_frame(R"({"op":9,"d":false})", t0);
+    EXPECT_TRUE(invalid.reconnect);
+    EXPECT_FALSE(session.can_resume());
+}
+
+// 场景:服务端发 op 7 要求重连;发 op 1 要求立即心跳。
+// 期望:op 7 返回重连指令且保留会话;op 1 立即回一帧心跳。
+TEST(QqGateway, ServerReconnectAndHeartbeatRequests) {
+    GatewaySession session;
+    const auto t0 = Clock::now();
+    session.on_connected("tok", t0);
+    session.on_frame(hello(10000), t0);
+    session.on_frame(ready(2), t0);
+    const auto reconnect = session.on_frame(R"({"op":7})", t0);
+    EXPECT_TRUE(reconnect.reconnect);
+    EXPECT_TRUE(session.can_resume());
+    const auto beat = session.on_frame(R"({"op":1})", t0);
+    ASSERT_EQ(beat.frames.size(), 1u);
+    EXPECT_EQ(parse(beat.frames[0])["op"], 1);
+}
+
+} // namespace
+} // namespace acecode::im::qqbot
diff --git a/tests/im/qq_protocol_test.cpp b/tests/im/qq_protocol_test.cpp
new file mode 100644
index 000000000..e1423709d
--- /dev/null
+++ b/tests/im/qq_protocol_test.cpp
@@ -0,0 +1,116 @@
+#include <gtest/gtest.h>
+
+#include "im/qqbot/qq_protocol.hpp"
+
+// im/qqbot/qq_protocol:网关关闭码分类、消息事件解析、OpenAPI 错误解析。
+
+namespace acecode::im::qqbot {
+namespace {
+
+// 场景:网关以各种关闭码断开。
+// 期望:令牌失效先刷新;会话类错误重新登录;频控单独处理;封禁、下线/仅沙箱为致命错误;
+// 其余普通断线按恢复会话处理。
+TEST(QqProtocol, ClassifiesGatewayCloseCodes) {
+    EXPECT_EQ(classify_close(4004).action, CloseAction::RefreshToken);
+    for (int code : {4006, 4007, 4009, 4900, 4913, 4001})
+        EXPECT_EQ(classify_close(code).action, CloseAction::Identify) << code;
+    EXPECT_EQ(classify_close(4008).action, CloseAction::RateLimited);
+    EXPECT_EQ(classify_close(4914).action, CloseAction::Fatal);
+    EXPECT_EQ(classify_close(4915).action, CloseAction::Fatal);
+    EXPECT_FALSE(classify_close(4915).reason.empty());
+    for (int code : {1000, 1001, 1006, 4000})
+        EXPECT_EQ(classify_close(code).action, CloseAction::Resume) << code;
+}
+
+// 场景:收到一条单聊消息,正文两端带空白。
+// 期望:地址为私聊(对方 openid 同时是 chat 与 sender),视为点名,正文去空白;
+// 回复上下文里记录 msg_id、scope=c2c 与接收时间。
+TEST(QqProtocol, ParsesC2CMessage) {
+    const auto inbound = parse_message_event(
+        "C2C_MESSAGE_CREATE",
+        {{"id", "M1"}, {"content", "  你好  "}, {"author", {{"user_openid", "U1"}}}}, "APP", 1234);
+    ASSERT_TRUE(inbound);
+    EXPECT_EQ(inbound->address.platform, "qq");
+    EXPECT_EQ(inbound->address.account, "APP");
+    EXPECT_EQ(inbound->address.kind, ChatKind::Private);
+    EXPECT_EQ(inbound->address.chat, "U1");
+    EXPECT_EQ(inbound->address.sender, "U1");
+    EXPECT_TRUE(inbound->mentioned);
+    EXPECT_EQ(inbound->text, u8"你好");
+    EXPECT_EQ(inbound->reply_context.value("msg_id", ""), "M1");
+    EXPECT_EQ(inbound->reply_context.value("scope", ""), "c2c");
+    EXPECT_EQ(inbound->reply_context.value("received_at_ms", 0), 1234);
+}
+
+// 场景:群里 @机器人 的消息,以及群主开启“接收全部消息”后推来的普通群消息。
+// 期望:前者按“群 + 成员”定位且视为点名;后者同样能解析,但标记为未点名(核心会忽略)。
+TEST(QqProtocol, ParsesGroupMessagesWithMentionFlag) {
+    const nlohmann::json d{{"id", "M2"}, {"content", " 帮我看看 "}, {"group_openid", "G1"},
+                           {"author", {{"member_openid", "MB1"}}}};
+    const auto at = parse_message_event("GROUP_AT_MESSAGE_CREATE", d, "APP", 0);
+    ASSERT_TRUE(at);
+    EXPECT_EQ(at->address.kind, ChatKind::Group);
+    EXPECT_EQ(at->address.chat, "G1");
+    EXPECT_EQ(at->address.sender, "MB1");
+    EXPECT_TRUE(at->mentioned);
+    EXPECT_EQ(at->reply_context.value("scope", ""), "group");
+    const auto all = parse_message_event("GROUP_MESSAGE_CREATE", d, "APP", 0);
+    ASSERT_TRUE(all);
+    EXPECT_FALSE(all->mentioned);
+}
+
+// 场景:消息带图片、带识别文字的语音、普通文件三种附件,地址以 // 开头。
+// 期望:类型分别识别为图片、语音、文件;语音保留识别文字;省略协议的 // 地址补成 https。
+TEST(QqProtocol, ParsesAttachmentsAndVoiceTranscript) {
+    const nlohmann::json d{
+        {"id", "M3"}, {"content", ""}, {"author", {{"user_openid", "U1"}}},
+        {"attachments", nlohmann::json::array({
+            {{"content_type", "image/png"}, {"filename", "a.png"}, {"url", "//cdn.example/a"}, {"size", 10}},
+            {{"content_type", "voice"}, {"filename", "v.amr"}, {"url", "https://cdn.example/v"},
+             {"asr_refer_text", " 明天开会 "}},
+            {{"content_type", "file"}, {"filename", "r.pdf"}, {"url", "http://cdn.example/r"}}})}};
+    const auto inbound = parse_message_event("C2C_MESSAGE_CREATE", d, "APP", 0);
+    ASSERT_TRUE(inbound);
+    ASSERT_EQ(inbound->attachments.size(), 3u);
+    EXPECT_EQ(inbound->attachments[0].kind, AttachmentKind::Image);
+    EXPECT_EQ(inbound->attachments[0].remote_ref, "https://cdn.example/a");
+    EXPECT_EQ(inbound->attachments[0].size, 10u);
+    EXPECT_EQ(inbound->attachments[1].kind, AttachmentKind::Voice);
+    EXPECT_EQ(inbound->attachments[1].transcript, u8"明天开会");
+    EXPECT_EQ(inbound->attachments[2].kind, AttachmentKind::File);
+    EXPECT_EQ(inbound->attachments[2].remote_ref, "http://cdn.example/r");
+}
+
+// 场景:频道消息、READY 之类的非消息事件、没有正文也没有附件的消息、缺少发送者的消息。
+// 期望:都不产生入站消息。
+TEST(QqProtocol, IgnoresUnsupportedOrEmptyEvents) {
+    const nlohmann::json ok{{"id", "M"}, {"content", "x"}, {"author", {{"user_openid", "U"}}}};
+    EXPECT_FALSE(parse_message_event("AT_MESSAGE_CREATE", ok, "APP", 0));
+    EXPECT_FALSE(parse_message_event("READY", ok, "APP", 0));
+    EXPECT_FALSE(parse_message_event("C2C_MESSAGE_CREATE",
+                                     {{"id", "M"}, {"content", "  "}, {"author", {{"user_openid", "U"}}}}, "APP", 0));
+    EXPECT_FALSE(parse_message_event("C2C_MESSAGE_CREATE", {{"id", "M"}, {"content", "x"}}, "APP", 0));
+}
+
+// 场景:OpenAPI 返回 {"code","message"} 错误体,或返回无法解析的内容。
+// 期望:读出错误码与原因;解析不了时用 HTTP 状态码兜底。
+TEST(QqProtocol, ParsesApiErrors) {
+    const auto error = parse_api_error(400, R"({"code":40034,"message":"msg_id expired"})");
+    EXPECT_EQ(error.status, 400);
+    EXPECT_EQ(error.code, 40034);
+    EXPECT_EQ(error.message, "msg_id expired");
+    EXPECT_EQ(parse_api_error(502, "<html>").message, "HTTP 502");
+}
+
+// 场景:按文件类型选择上传时的 file_type。
+// 期望:图片 1、mp4 视频 2,其余(含音频与文档)一律按普通文件 4。
+TEST(QqProtocol, MapsUploadFileTypes) {
+    EXPECT_EQ(file_type_for("image/png", "a.png"), kFileTypeImage);
+    EXPECT_EQ(file_type_for("", "photo.JPG"), kFileTypeImage);
+    EXPECT_EQ(file_type_for("video/mp4", "v.mp4"), kFileTypeVideo);
+    EXPECT_EQ(file_type_for("audio/mpeg", "a.mp3"), kFileTypeFile);
+    EXPECT_EQ(file_type_for("application/pdf", "r.pdf"), kFileTypeFile);
+}
+
+} // namespace
+} // namespace acecode::im::qqbot
diff --git a/tests/im/qq_reply_budget_test.cpp b/tests/im/qq_reply_budget_test.cpp
new file mode 100644
index 000000000..80b3036f2
--- /dev/null
+++ b/tests/im/qq_reply_budget_test.cpp
@@ -0,0 +1,100 @@
+#include <gtest/gtest.h>
+
+#include "im/qqbot/qq_reply_budget.hpp"
+
+// im/qqbot/qq_reply_budget:QQ 被动回复额度(私聊 60 分钟 4 条、群聊 5 分钟 5 条)、
+// 全局递增 msg_seq,以及主动消息被拒时的补发队列。
+
+namespace acecode::im::qqbot {
+namespace {
+
+nlohmann::json context(const std::string& id, const std::string& scope, std::int64_t at) {
+    return {{"msg_id", id}, {"scope", scope}, {"received_at_ms", at}};
+}
+
+constexpr std::int64_t kMinute = 60 * 1000;
+
+// 场景:同一条私聊消息连续回复 5 次。
+// 期望:前 4 次被动回复(带 msg_id),第 5 次改为主动消息。
+TEST(QqReplyBudget, PrivateChatAllowsFourPassiveReplies) {
+    ReplyBudget budget;
+    const auto ctx = context("M1", "c2c", 0);
+    for (int i = 0; i < 4; ++i) {
+        const auto plan = budget.plan(ctx, kMinute);
+        EXPECT_TRUE(plan.passive) << i;
+        EXPECT_EQ(plan.msg_id, "M1");
+    }
+    EXPECT_FALSE(budget.plan(ctx, kMinute).passive);
+}
+
+// 场景:私聊消息 61 分钟后才有回复;群消息 6 分钟后才有回复。
+// 期望:都已超出被动回复窗口,改为主动消息。
+TEST(QqReplyBudget, WindowExpiryForcesActiveMessage) {
+    ReplyBudget budget;
+    EXPECT_FALSE(budget.plan(context("M1", "c2c", 0), 61 * kMinute).passive);
+    EXPECT_TRUE(budget.plan(context("M2", "group", 0), 4 * kMinute).passive);
+    EXPECT_FALSE(budget.plan(context("M3", "group", 0), 6 * kMinute).passive);
+}
+
+// 场景:同一条群消息连续回复 6 次。
+// 期望:前 5 次被动,第 6 次主动。
+TEST(QqReplyBudget, GroupAllowsFivePassiveReplies) {
+    ReplyBudget budget;
+    const auto ctx = context("G1", "group", 0);
+    for (int i = 0; i < 5; ++i) EXPECT_TRUE(budget.plan(ctx, kMinute).passive) << i;
+    EXPECT_FALSE(budget.plan(ctx, kMinute).passive);
+}
+
+// 场景:平台拒绝了某条消息的被动回复(例如窗口其实已过);以及没有回复上下文的发送。
+// 期望:该消息此后不再尝试被动;没有上下文时直接主动。
+TEST(QqReplyBudget, ExhaustAndMissingContextUseActiveMessages) {
+    ReplyBudget budget;
+    const auto ctx = context("M1", "c2c", 0);
+    EXPECT_TRUE(budget.plan(ctx, kMinute).passive);
+    budget.exhaust("M1");
+    EXPECT_FALSE(budget.plan(ctx, kMinute).passive);
+    EXPECT_FALSE(budget.plan(nlohmann::json::object(), kMinute).passive);
+}
+
+// 场景:交替为不同消息安排发送,并单独申请序号。
+// 期望:msg_seq 全局严格递增,不会出现重复(平台按 msg_id + msg_seq 去重)。
+TEST(QqReplyBudget, SequenceIsGloballyIncreasing) {
+    ReplyBudget budget;
+    std::int64_t last = 0;
+    for (int i = 0; i < 10; ++i) {
+        const auto plan = budget.plan(context(i % 2 ? "A" : "B", "c2c", 0), kMinute);
+        EXPECT_GT(plan.msg_seq, last);
+        last = plan.msg_seq;
+        const auto seq = budget.next_seq();
+        EXPECT_GT(seq, last);
+        last = seq;
+    }
+}
+
+// 场景:主动消息被拒后为同一会话暂存 22 条输出,另一个会话暂存 1 条。
+// 期望:每个会话最多保留最新 20 条(丢弃最旧的 2 条),取出时保持原顺序且取后清空;
+// 不同会话互不影响。
+TEST(QqHeldQueue, KeepsNewestTwentyInOrderPerConversation) {
+    HeldQueue queue;
+    std::size_t dropped = 0;
+    for (int i = 0; i < 22; ++i) {
+        HeldItem item;
+        item.text = std::to_string(i);
+        dropped += queue.push("a", item);
+    }
+    HeldItem other;
+    other.text = "other";
+    queue.push("b", other);
+    EXPECT_EQ(dropped, 2u);
+    EXPECT_EQ(queue.size("a"), 20u);
+    EXPECT_EQ(queue.total(), 21u);
+    const auto items = queue.take("a");
+    ASSERT_EQ(items.size(), 20u);
+    EXPECT_EQ(items.front().text, "2");
+    EXPECT_EQ(items.back().text, "21");
+    EXPECT_EQ(queue.size("a"), 0u);
+    EXPECT_EQ(queue.size("b"), 1u);
+}
+
+} // namespace
+} // namespace acecode::im::qqbot
diff --git a/tests/im/qq_transport_test.cpp b/tests/im/qq_transport_test.cpp
new file mode 100644
index 000000000..3cbbdcc16
--- /dev/null
+++ b/tests/im/qq_transport_test.cpp
@@ -0,0 +1,295 @@
+#include <gtest/gtest.h>
+
+#include "im/qqbot/qq_transport.hpp"
+#include "test_support/im/fake_qq_server.hpp"
+
+#include <fstream>
+#include <mutex>
+#include <vector>
+
+// im/qqbot/qq_transport:QQ 传输层端到端测试。本机假开放平台提供令牌、/gateway、
+// WebSocket 网关与发消息接口;测试覆盖连接、收消息、被动/主动/暂存三级发送、
+// Markdown 回退、去重、致命关闭与凭据错误。
+
+namespace acecode::im::qqbot {
+namespace {
+
+QqTransportOptions local_options(const test::FakeQqServer& server) {
+    QqTransportOptions options;
+    options.api.app_id = "APP";
+    options.api.app_secret = "secret-value-123";
+    options.api.api_base = server.base();
+    options.api.token_url = server.base() + "/app/getAppAccessToken";
+    options.api.use_proxy = false;
+    options.backoff = {std::chrono::milliseconds(50)};
+    options.rate_limit_delay = std::chrono::milliseconds(100);
+    return options;
+}
+
+struct Recorder {
+    std::mutex mu;
+    std::vector<Inbound> inbound;
+    std::vector<TransportStatus> statuses;
+    TransportCallbacks callbacks() {
+        TransportCallbacks cb;
+        cb.on_inbound = [this](Inbound in) {
+            std::lock_guard<std::mutex> lock(mu);
+            inbound.push_back(std::move(in));
+        };
+        cb.on_status = [this](const TransportStatus& s) {
+            std::lock_guard<std::mutex> lock(mu);
+            statuses.push_back(s);
+        };
+        return cb;
+    }
+    std::size_t inbound_count() {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.size();
+    }
+    Inbound inbound_at(std::size_t i) {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.at(i);
+    }
+};
+
+bool wait_connected(QqTransport& transport) {
+    return test::FakeQqServer::wait_until([&] { return transport.status().state == LinkState::Connected; });
+}
+
+// 场景:开启 QQ 通道,网关握手后推来一条单聊消息,随后用它回复一段 Markdown。
+// 期望:状态变为已连接并显示机器人名;入站消息带正确地址与回复上下文;
+// 回复以 Markdown 被动回复送达(带 msg_id 与 msg_seq),结果为已发送。
+TEST(QqTransport, ConnectsReceivesAndRepliesPassively) {
+    test::FakeQqServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    QqTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport));
+    EXPECT_EQ(transport.status().display_name, "TestBot");
+    const auto identify = server.frames().front();
+    EXPECT_EQ(identify.value("op", 0), 2);
+    EXPECT_EQ(identify["d"]["token"], "QQBot tok-1");
+
+    server.push_c2c("M1", "U1", " 你好 ");
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return recorder.inbound_count() == 1; }));
+    const auto inbound = recorder.inbound_at(0);
+    EXPECT_EQ(inbound.text, u8"你好");
+    EXPECT_EQ(inbound.address.chat, "U1");
+
+    const auto result = transport.send_text(inbound.address, "**好的**", inbound.reply_context);
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto sent = server.requests_to("/v2/users/U1/messages");
+    ASSERT_EQ(sent.size(), 1u);
+    EXPECT_EQ(sent[0].body.value("msg_type", -1), kMsgTypeMarkdown);
+    EXPECT_EQ(sent[0].body["markdown"].value("content", ""), "**好的**");
+    EXPECT_EQ(sent[0].body.value("msg_id", ""), "M1");
+    EXPECT_GE(sent[0].body.value("msg_seq", 0), 1);
+    transport.stop();
+    EXPECT_EQ(transport.status().state, LinkState::Stopped);
+}
+
+// 场景:平台拒绝带 msg_id 的被动回复(例如窗口已过),但接受主动消息。
+// 期望:自动改发主动消息(不带 msg_id),结果为已发送;平台共收到两次请求。
+TEST(QqTransport, FallsBackToActiveMessageWhenPassiveIsRejected) {
+    test::FakeQqServer server;
+    server.message_handler = [](const test::FakeQqServer::Request& r) {
+        if (r.body.contains("msg_id"))
+            return std::make_pair(400, nlohmann::json{{"code", 40034}, {"message", "msg_id expired"}});
+        return std::make_pair(200, nlohmann::json{{"id", "R"}});
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    QqTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport));
+    server.push_c2c("M1", "U1", "hi");
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return recorder.inbound_count() == 1; }));
+    const auto inbound = recorder.inbound_at(0);
+    const auto result = transport.send_text(inbound.address, "reply", inbound.reply_context);
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto sent = server.requests_to("/v2/users/U1/messages");
+    ASSERT_EQ(sent.size(), 2u);
+    EXPECT_TRUE(sent[0].body.contains("msg_id"));
+    EXPECT_FALSE(sent[1].body.contains("msg_id"));
+}
+
+// 场景:被动与主动消息都被拒(对方关闭了主动消息);之后对方又发来一条新消息。
+// 期望:第一次发送结果为“暂存”;新消息到来时先用它的被动额度补发暂存内容(带“补发”标记与
+// 新的 msg_id),然后才把新消息交给上层。
+TEST(QqTransport, HoldsOutputAndFlushesOnNextInbound) {
+    test::FakeQqServer server;
+    std::atomic<bool> reject{true};
+    server.message_handler = [&](const test::FakeQqServer::Request&) {
+        if (reject) return std::make_pair(403, nlohmann::json{{"code", 304}, {"message", "proactive disabled"}});
+        return std::make_pair(200, nlohmann::json{{"id", "R"}});
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    QqTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport));
+    server.push_c2c("M1", "U1", "first");
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return recorder.inbound_count() == 1; }));
+    const auto first = recorder.inbound_at(0);
+    EXPECT_EQ(transport.send_text(first.address, "late answer", first.reply_context).outcome, SendOutcome::Held);
+    EXPECT_EQ(transport.held_count(), 1u);
+
+    reject = false;
+    const auto before = server.requests_to("/v2/users/U1/messages").size();
+    server.push_c2c("M2", "U1", "second");
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return recorder.inbound_count() == 2; }));
+    const auto sent = server.requests_to("/v2/users/U1/messages");
+    ASSERT_EQ(sent.size(), before + 1);
+    EXPECT_EQ(sent.back().body.value("msg_id", ""), "M2");
+    EXPECT_NE(sent.back().body["markdown"].value("content", "").find("late answer"), std::string::npos);
+    EXPECT_EQ(sent.back().body["markdown"].value("content", "").rfind(u8"(补发)", 0), 0u);
+    EXPECT_EQ(transport.held_count(), 0u);
+}
+
+// 场景:机器人不支持 Markdown,平台对 msg_type 2 返回带 markdown 字样的 400。
+// 期望:同一段内容改用纯文本(msg_type 0,去掉标记)重发成功;之后的发送直接用纯文本。
+TEST(QqTransport, FallsBackToPlainTextWhenMarkdownIsRejected) {
+    test::FakeQqServer server;
+    server.message_handler = [](const test::FakeQqServer::Request& r) {
+        if (r.body.value("msg_type", 0) == kMsgTypeMarkdown)
+            return std::make_pair(400, nlohmann::json{{"code", 11255}, {"message", "markdown not allowed"}});
+        return std::make_pair(200, nlohmann::json{{"id", "R"}});
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    QqTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport));
+    server.push_c2c("M1", "U1", "hi");
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return recorder.inbound_count() == 1; }));
+    const auto inbound = recorder.inbound_at(0);
+    EXPECT_EQ(transport.send_text(inbound.address, "**粗体**", inbound.reply_context).outcome, SendOutcome::Sent);
+    EXPECT_EQ(transport.send_text(inbound.address, "第二条", inbound.reply_context).outcome, SendOutcome::Sent);
+    const auto sent = server.requests_to("/v2/users/U1/messages");
+    ASSERT_EQ(sent.size(), 3u);
+    EXPECT_EQ(sent[1].body.value("msg_type", -1), kMsgTypeText);
+    EXPECT_EQ(sent[1].body.value("content", ""), u8"粗体");
+    EXPECT_EQ(sent[2].body.value("msg_type", -1), kMsgTypeText);
+}
+
+// 场景:网关重复推送同一条消息(重连补发时常见),以及推送一条群 @ 消息。
+// 期望:重复的消息只交给上层一次;群消息按“群 + 成员”定位。
+TEST(QqTransport, DeduplicatesMessagesAndParsesGroupMentions) {
+    test::FakeQqServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    QqTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport));
+    server.push_c2c("M1", "U1", "hi");
+    server.push_c2c("M1", "U1", "hi");
+    server.push_group_at("M2", "G1", "MB1", "看看");
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return recorder.inbound_count() == 2; }));
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    EXPECT_EQ(recorder.inbound_count(), 2u);
+    const auto group = recorder.inbound_at(1);
+    EXPECT_EQ(group.address.kind, ChatKind::Group);
+    EXPECT_EQ(group.address.chat, "G1");
+    EXPECT_EQ(group.address.sender, "MB1");
+}
+
+// 场景:连接期间网关以 4008(频控)断开。
+// 期望:等待频控延迟后自动重连,并用 Resume 恢复原会话,最终回到已连接。
+TEST(QqTransport, ReconnectsAndResumesAfterRateLimitClose) {
+    test::FakeQqServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    QqTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport));
+    server.close_connection(4008, "rate limited");
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return server.connections() == 2; }));
+    ASSERT_TRUE(wait_connected(transport));
+    bool resumed = false;
+    for (const auto& frame : server.frames()) resumed = resumed || frame.value("op", 0) == 6;
+    EXPECT_TRUE(resumed);
+}
+
+// 场景:网关以 4915(机器人被封禁)关闭连接。
+// 期望:状态变为失败、停止自动重试,原因为“机器人已被封禁”,之后不再重连。
+TEST(QqTransport, StopsRetryingAfterBan) {
+    test::FakeQqServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    QqTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport));
+    server.close_connection(4915, "banned");
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return transport.status().state == LinkState::Failed; }));
+    const auto status = transport.status();
+    EXPECT_TRUE(status.retry_stopped);
+    EXPECT_NE(status.detail.find(u8"封禁"), std::string::npos) << status.detail;
+    std::this_thread::sleep_for(std::chrono::milliseconds(300));
+    EXPECT_EQ(server.connections(), 1);
+}
+
+// 场景:AppSecret 错误,平台拒绝换令牌。
+// 期望:不去连网关,状态直接变为失败且停止重试;错误信息不含 AppSecret。
+TEST(QqTransport, InvalidCredentialsFailWithoutRetrying) {
+    test::FakeQqServer server;
+    server.token_handler = [](const nlohmann::json&) {
+        return nlohmann::json{{"code", 100016}, {"message", "invalid appsecret"}};
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    QqTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return transport.status().state == LinkState::Failed; }));
+    const auto status = transport.status();
+    EXPECT_TRUE(status.retry_stopped);
+    EXPECT_EQ(status.detail.find("secret-value-123"), std::string::npos);
+    EXPECT_EQ(server.connections(), 0);
+}
+
+// 场景:回传一个会话生成的文件。
+// 期望:先上传(base64、file_type=4、带文件名),再以 msg_type 7 带 file_info 发送。
+TEST(QqTransport, SendsFilesThroughRichMediaUpload) {
+    test::FakeQqServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    QqTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport));
+    server.push_c2c("M1", "U1", "send me the report");
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return recorder.inbound_count() == 1; }));
+    const auto inbound = recorder.inbound_at(0);
+    const auto file = std::filesystem::path(testing::TempDir()) / "acecode-qq-report.pdf";
+    { std::ofstream(file, std::ios::binary) << "PDF-DATA"; }
+    const auto result = transport.send_file(inbound.address, file, "report.pdf", "application/pdf",
+                                            inbound.reply_context);
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    const auto uploads = server.requests_to("/v2/users/U1/files");
+    ASSERT_EQ(uploads.size(), 1u);
+    EXPECT_EQ(uploads[0].body.value("file_type", 0), kFileTypeFile);
+    EXPECT_EQ(uploads[0].body.value("file_name", ""), "report.pdf");
+    const auto sent = server.requests_to("/v2/users/U1/messages");
+    ASSERT_EQ(sent.size(), 1u);
+    EXPECT_EQ(sent[0].body.value("msg_type", -1), kMsgTypeMedia);
+    EXPECT_EQ(sent[0].body["media"].value("file_info", ""), "INFO-1");
+    std::filesystem::remove(file);
+}
+
+// 场景:会话产出的文件超过 QQ 直传上限(测试里把上限调到 4 字节)。
+// 期望:不上传,改发一条带文件名的文字说明,发送结果为已发送。
+TEST(QqTransport, OversizedFileBecomesTextNotice) {
+    test::FakeQqServer server;
+    auto options = local_options(server);
+    options.max_upload_bytes = 4;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    QqTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_connected(transport));
+    server.push_c2c("M1", "U1", "send me the report");
+    ASSERT_TRUE(test::FakeQqServer::wait_until([&] { return recorder.inbound_count() == 1; }));
+    const auto inbound = recorder.inbound_at(0);
+    const auto file = std::filesystem::path(testing::TempDir()) / "acecode-qq-big.pdf";
+    { std::ofstream(file, std::ios::binary) << "PDF-DATA"; }
+    const auto result = transport.send_file(inbound.address, file, "big.pdf", "application/pdf",
+                                            inbound.reply_context);
+    EXPECT_EQ(result.outcome, SendOutcome::Sent) << result.error;
+    EXPECT_TRUE(server.requests_to("/v2/users/U1/files").empty());
+    const auto sent = server.requests_to("/v2/users/U1/messages");
+    ASSERT_EQ(sent.size(), 1u);
+    EXPECT_NE(sent[0].body.dump().find("big.pdf"), std::string::npos);
+    std::filesystem::remove(file);
+}
+
+} // namespace
+} // namespace acecode::im::qqbot
diff --git a/tests/im/redact_test.cpp b/tests/im/redact_test.cpp
new file mode 100644
index 000000000..40567ed54
--- /dev/null
+++ b/tests/im/redact_test.cpp
@@ -0,0 +1,35 @@
+#include <gtest/gtest.h>
+
+#include "im/redact.hpp"
+
+// im/redact:通道凭据只能以脱敏形式出现在接口返回、日志与错误文本里。
+
+namespace acecode::im {
+namespace {
+
+// 场景:设置页展示已保存的 AppSecret / token。
+// 期望:只露出末 4 位;过短的值整体隐藏。
+TEST(ImRedact, MaskKeepsOnlyLastFourCharacters) {
+    EXPECT_EQ(mask_secret("abcdefgh1234"), "****1234");
+    EXPECT_EQ(mask_secret("short"), "****");
+    EXPECT_EQ(mask_secret(""), "****");
+}
+
+// 场景:Telegram 请求失败的错误文本里带着完整 URL(token 在路径里)。
+// 期望:token 被替换成 ***,其余诊断信息保留。
+TEST(ImRedact, RemovesTelegramTokenFromUrls) {
+    const std::string error =
+        "GET https://api.telegram.org/bot123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw0/getMe failed";
+    EXPECT_EQ(redact_secrets(error), "GET https://api.telegram.org/bot***/getMe failed");
+}
+
+// 场景:错误文本中出现已知的 AppSecret;另有一个只有 3 位的“密钥”和普通的时间/端口文字。
+// 期望:已知密钥被抹掉;过短的值不处理;12345:short 这类文字不被误伤。
+TEST(ImRedact, RemovesListedSecretsWithoutFalsePositives) {
+    EXPECT_EQ(redact_secrets("secret=Zx9QpL0mN7 appears twice: Zx9QpL0mN7", {"Zx9QpL0mN7", "abc"}),
+              "secret=*** appears twice: ***");
+    EXPECT_EQ(redact_secrets("port 12345:short abc"), "port 12345:short abc");
+}
+
+} // namespace
+} // namespace acecode::im
diff --git a/tests/im/text_chunk_test.cpp b/tests/im/text_chunk_test.cpp
new file mode 100644
index 000000000..3ff77ae30
--- /dev/null
+++ b/tests/im/text_chunk_test.cpp
@@ -0,0 +1,110 @@
+#include <gtest/gtest.h>
+
+#include "im/text_chunk.hpp"
+
+#include <string>
+
+// im/text_chunk:IM 出站长文本分段。QQ 按字符计、Telegram 按 UTF-16 单位计,
+// 分段不能切断 UTF-8 字符,也不能把代码块切成没闭合的半截。
+
+namespace acecode::im {
+namespace {
+
+bool valid_utf8(const std::string& text) {
+    std::size_t i = 0;
+    while (i < text.size()) {
+        const auto c = static_cast<unsigned char>(text[i]);
+        std::size_t len = c < 0x80 ? 1 : c >= 0xF0 ? 4 : c >= 0xE0 ? 3 : c >= 0xC2 ? 2 : 0;
+        if (len == 0 || i + len > text.size()) return false;
+        for (std::size_t k = 1; k < len; ++k)
+            if ((static_cast<unsigned char>(text[i + k]) & 0xC0) != 0x80) return false;
+        i += len;
+    }
+    return true;
+}
+
+std::size_t count_fence_lines(const std::string& text) {
+    std::size_t count = 0, pos = 0;
+    while ((pos = text.find("```", pos)) != std::string::npos) {
+        if (pos == 0 || text[pos - 1] == '\n') ++count;
+        pos += 3;
+    }
+    return count;
+}
+
+// 场景:统计中文与 emoji 的长度。
+// 期望:按码点计时 emoji 算 1;按 UTF-16 计时增补平面的 emoji 算 2。
+TEST(ImTextChunk, CountsCodePointsAndUtf16Units) {
+    const std::string text = u8"你好😀";
+    EXPECT_EQ(text_units(text, false), 3u);
+    EXPECT_EQ(text_units(text, true), 4u);
+}
+
+// 场景:短文本、空文本、纯空白。
+// 期望:短文本原样一段;空文本与纯空白不产生任何分段(不会发出空消息)。
+TEST(ImTextChunk, ShortAndBlankInputs) {
+    EXPECT_EQ(chunk_text("hello", 100, false), std::vector<std::string>{"hello"});
+    EXPECT_TRUE(chunk_text("", 100, false).empty());
+    EXPECT_TRUE(chunk_text(" \n\n ", 100, false).empty());
+}
+
+// 场景:两段文字合起来超长,但每段单独都不超长。
+// 期望:在空行处切成两段,第二段开头不带多余空行。
+TEST(ImTextChunk, PrefersParagraphBoundary) {
+    const std::string first(60, 'a');
+    const std::string second(60, 'b');
+    const auto chunks = chunk_text(first + "\n\n" + second, 100, false);
+    ASSERT_EQ(chunks.size(), 2u);
+    EXPECT_EQ(chunks[0], first);
+    EXPECT_EQ(chunks[1], second);
+}
+
+// 场景:一整行 500 个汉字,没有任何换行或空格可以切。
+// 期望:按字符硬切;每段都是合法 UTF-8 且不超过上限;拼回去与原文完全一致。
+TEST(ImTextChunk, HardSplitsLongCjkLineOnCharacterBoundaries) {
+    std::string text;
+    for (int i = 0; i < 500; ++i) text += u8"汉";
+    const auto chunks = chunk_text(text, 120, false);
+    ASSERT_GT(chunks.size(), 1u);
+    std::string joined;
+    for (const auto& chunk : chunks) {
+        EXPECT_TRUE(valid_utf8(chunk));
+        EXPECT_LE(text_units(chunk, false), 120u);
+        joined += chunk;
+    }
+    EXPECT_EQ(joined, text);
+}
+
+// 场景:Telegram 按 UTF-16 计数,40 个 emoji(80 个单位)切成上限 16 的段。
+// 期望:每段不超过 16 个 UTF-16 单位,且不切断任何 emoji。
+TEST(ImTextChunk, RespectsUtf16LimitForEmoji) {
+    std::string text;
+    for (int i = 0; i < 40; ++i) text += u8"😀";
+    const auto chunks = chunk_text(text, 16, true);
+    std::string joined;
+    for (const auto& chunk : chunks) {
+        EXPECT_LE(text_units(chunk, true), 16u);
+        EXPECT_TRUE(valid_utf8(chunk));
+        joined += chunk;
+    }
+    EXPECT_EQ(joined, text);
+}
+
+// 场景:一个 python 代码块比单条上限长得多。
+// 期望:每段的 ``` 行数都是偶数(围栏成对);后续段以 ```python 重新开头,
+// 渲染时每段都是完整的代码块。
+TEST(ImTextChunk, KeepsCodeFencesBalancedAcrossChunks) {
+    std::string code = "```python\n";
+    for (int i = 0; i < 60; ++i) code += "print('line " + std::to_string(i) + "')\n";
+    code += "```\n";
+    const auto chunks = chunk_text("Intro text\n\n" + code + "\nDone.", 200, false);
+    ASSERT_GT(chunks.size(), 2u);
+    for (std::size_t i = 0; i < chunks.size(); ++i) {
+        EXPECT_EQ(count_fence_lines(chunks[i]) % 2, 0u) << "chunk " << i << ":\n" << chunks[i];
+        EXPECT_LE(text_units(chunks[i], false), 200u);
+    }
+    EXPECT_EQ(chunks[1].rfind("```python\n", 0), 0u) << chunks[1];
+}
+
+} // namespace
+} // namespace acecode::im
diff --git a/tests/im/tg_api_test.cpp b/tests/im/tg_api_test.cpp
new file mode 100644
index 000000000..bf85a5f1e
--- /dev/null
+++ b/tests/im/tg_api_test.cpp
@@ -0,0 +1,77 @@
+#include <gtest/gtest.h>
+
+#include "im/telegram/tg_api.hpp"
+#include "test_support/im/fake_telegram_server.hpp"
+
+// im/telegram/tg_api:Bot API 客户端,对着本机假 Bot API 跑。
+
+namespace acecode::im::telegram {
+namespace {
+
+ApiOptions local_options(const test::FakeTelegramServer& server) {
+    ApiOptions options;
+    options.token = server.token();
+    options.api_base = server.base();
+    options.use_proxy = false;
+    return options;
+}
+
+// 场景:用正确 token 调 getMe,以及用错误 token 调 getMe。
+// 期望:前者成功并拿到机器人信息;后者返回 401 失败,错误信息里不含 token。
+TEST(TelegramApi, CallsMethodsWithTokenInPath) {
+    test::FakeTelegramServer server;
+    Api api(local_options(server));
+    const auto me = api.call("getMe", nlohmann::json::object());
+    ASSERT_TRUE(me.ok) << me.description;
+    EXPECT_EQ(me.result.value("username", ""), "AceTestBot");
+    auto bad_options = local_options(server);
+    bad_options.token = "999999:WRONG-TOKEN-zyxwvutsrqponmlkjihgfedcba";
+    Api bad(bad_options);
+    const auto denied = bad.call("getMe", nlohmann::json::object());
+    EXPECT_FALSE(denied.ok);
+    EXPECT_EQ(denied.status, 401);
+    EXPECT_EQ(denied.description.find("WRONG-TOKEN"), std::string::npos);
+}
+
+// 场景:getUpdates 返回两种 409(配置了 webhook / 另一个程序在轮询),以及 429。
+// 期望:409 按描述区分成两类;429 读出 retry_after。
+TEST(TelegramApi, ClassifiesConflictsAndReadsRetryAfter) {
+    test::FakeTelegramServer server;
+    std::string mode = "webhook";
+    server.override = [&](const test::FakeTelegramServer::Call& call) -> nlohmann::json {
+        if (call.method != "getUpdates" && call.method != "sendMessage") return nullptr;
+        if (call.method == "sendMessage")
+            return {{"ok", false}, {"error_code", 429}, {"description", "Too Many Requests: retry after 3"},
+                    {"parameters", {{"retry_after", 3}}}};
+        if (mode == "webhook")
+            return {{"ok", false}, {"error_code", 409},
+                    {"description", "Conflict: can't use getUpdates method while webhook is active"}};
+        return {{"ok", false}, {"error_code", 409},
+                {"description", "Conflict: terminated by other getUpdates request"}};
+    };
+    Api api(local_options(server));
+    EXPECT_EQ(conflict_kind(api.call("getUpdates", {{"offset", 0}})), ConflictKind::Webhook);
+    mode = "other";
+    EXPECT_EQ(conflict_kind(api.call("getUpdates", {{"offset", 0}})), ConflictKind::OtherPoller);
+    const auto limited = api.call("sendMessage", {{"chat_id", 1}, {"text", "x"}});
+    EXPECT_EQ(limited.status, 429);
+    EXPECT_EQ(limited.retry_after, 3);
+    EXPECT_EQ(conflict_kind(limited), ConflictKind::None);
+}
+
+// 场景:连接一个没有服务的地址,错误文本里本会带出完整 URL(含 token)。
+// 期望:请求失败且错误信息不含 token。
+TEST(TelegramApi, TransportErrorsDoNotLeakToken) {
+    ApiOptions options;
+    options.token = "123456:SECRET-TOKEN-abcdefghijklmnopqrstuvwxyz";
+    options.api_base = "http://127.0.0.1:1";
+    options.use_proxy = false;
+    Api api(options);
+    const auto result = api.call("getMe", nlohmann::json::object(), std::chrono::seconds(2));
+    EXPECT_FALSE(result.ok);
+    EXPECT_EQ(result.status, 0);
+    EXPECT_EQ(result.description.find("SECRET-TOKEN"), std::string::npos) << result.description;
+}
+
+} // namespace
+} // namespace acecode::im::telegram
diff --git a/tests/im/tg_rate_limit_test.cpp b/tests/im/tg_rate_limit_test.cpp
new file mode 100644
index 000000000..e884a5546
--- /dev/null
+++ b/tests/im/tg_rate_limit_test.cpp
@@ -0,0 +1,48 @@
+#include <gtest/gtest.h>
+
+#include "im/telegram/tg_rate_limit.hpp"
+
+// im/telegram/tg_rate_limit:Telegram 限速(同一聊天 1 秒 1 条、群每分钟 20 条、429 暂停)。
+// 全部用假时间,不真正等待。
+
+namespace acecode::im::telegram {
+namespace {
+
+using Clock = RateLimiter::Clock;
+using std::chrono::milliseconds;
+using std::chrono::seconds;
+
+// 场景:同一个私聊在同一时刻连续申请三次发送。
+// 期望:三次发送时刻依次相隔 1 秒;另一个私聊不受影响,可以立即发送。
+TEST(TelegramRateLimit, SpacesMessagesPerChat) {
+    RateLimiter limiter;
+    const auto t0 = Clock::now();
+    EXPECT_EQ(limiter.reserve("a", false, t0), t0);
+    EXPECT_EQ(limiter.reserve("a", false, t0), t0 + seconds(1));
+    EXPECT_EQ(limiter.reserve("a", false, t0), t0 + seconds(2));
+    EXPECT_EQ(limiter.reserve("b", false, t0), t0);
+}
+
+// 场景:同一个群在 1 分钟内要发 21 条(相邻间隔设为 0 以单独验证每分钟上限)。
+// 期望:前 20 条都在第一分钟内;第 21 条被推迟到第一条发出后满 60 秒。
+TEST(TelegramRateLimit, LimitsGroupsToTwentyPerMinute) {
+    RateLimiter::Limits limits;
+    limits.per_chat_gap = milliseconds(0);
+    RateLimiter limiter(limits);
+    const auto t0 = Clock::now();
+    for (int i = 0; i < 20; ++i) EXPECT_EQ(limiter.reserve("g", true, t0), t0) << i;
+    EXPECT_EQ(limiter.reserve("g", true, t0), t0 + seconds(60));
+}
+
+// 场景:平台对某聊天返回 429,要求等待 5 秒。
+// 期望:该聊天下一次发送不早于 5 秒后;其它聊天不受影响。
+TEST(TelegramRateLimit, PenaltyDelaysOnlyThatChat) {
+    RateLimiter limiter;
+    const auto t0 = Clock::now();
+    limiter.penalize("a", seconds(5), t0);
+    EXPECT_EQ(limiter.reserve("a", false, t0), t0 + seconds(5));
+    EXPECT_EQ(limiter.reserve("b", false, t0), t0);
+}
+
+} // namespace
+} // namespace acecode::im::telegram
diff --git a/tests/im/tg_transport_test.cpp b/tests/im/tg_transport_test.cpp
new file mode 100644
index 000000000..8b5cb3688
--- /dev/null
+++ b/tests/im/tg_transport_test.cpp
@@ -0,0 +1,300 @@
+#include <gtest/gtest.h>
+
+#include "im/telegram/tg_transport.hpp"
+#include "test_support/im/fake_telegram_server.hpp"
+
+#include <atomic>
+#include <fstream>
+#include <mutex>
+#include <thread>
+#include <vector>
+
+// im/telegram/tg_transport:Telegram 传输层端到端测试(本机假 Bot API)。
+// 覆盖:身份与隐私模式、长轮询收消息与 offset 持久化、HTML 发送与纯文本回退、
+// 429 重试、webhook 冲突与用户确认移除、被占用、token 无效、正在输入、文件收发、及时停机。
+
+namespace acecode::im::telegram {
+namespace {
+
+TelegramTransportOptions local_options(const test::FakeTelegramServer& server) {
+    TelegramTransportOptions options;
+    options.api.token = server.token();
+    options.api.api_base = server.base();
+    options.api.use_proxy = false;
+    options.poll_timeout = std::chrono::seconds(1);
+    options.backoff = {std::chrono::milliseconds(50)};
+    options.conflict_retry = std::chrono::milliseconds(100);
+    options.typing_interval = std::chrono::milliseconds(100);
+    options.limits.per_chat_gap = std::chrono::milliseconds(10);
+    return options;
+}
+
+struct Recorder {
+    std::mutex mu;
+    std::vector<Inbound> inbound;
+    TransportCallbacks callbacks() {
+        TransportCallbacks cb;
+        cb.on_inbound = [this](Inbound in) {
+            std::lock_guard<std::mutex> lock(mu);
+            inbound.push_back(std::move(in));
+        };
+        return cb;
+    }
+    std::size_t count() {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.size();
+    }
+    Inbound at(std::size_t i) {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.at(i);
+    }
+};
+
+bool wait_state(TelegramTransport& transport, LinkState state) {
+    return test::FakeTelegramServer::wait_until([&] { return transport.status().state == state; });
+}
+
+// 场景:开启 Telegram,机器人隐私模式开着;随后用户私聊一条消息。
+// 期望:状态变为已连接,显示 @用户名、聊天链接与“隐私模式开启”;收到入站消息;
+// 处理后的 offset 通过回调交给调用方持久化(= update_id + 1)。
+TEST(TelegramTransport, ConnectsReceivesAndPersistsOffset) {
+    test::FakeTelegramServer server;
+    auto options = local_options(server);
+    std::atomic<std::int64_t> persisted{0};
+    options.on_offset = [&](std::int64_t value) { persisted = value; };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    TelegramTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    const auto status = transport.status();
+    EXPECT_EQ(status.display_name, "@AceTestBot");
+    EXPECT_EQ(status.extra.value("link", ""), "https://t.me/AceTestBot");
+    EXPECT_TRUE(status.extra.value("privacy_mode", false));
+    EXPECT_EQ(status.account, "8001");
+
+    server.push_private_text(42, "你好", 1);
+    ASSERT_TRUE(test::FakeTelegramServer::wait_until([&] { return recorder.count() == 1; }));
+    EXPECT_EQ(recorder.at(0).text, u8"你好");
+    EXPECT_EQ(recorder.at(0).address.account, "8001");
+    ASSERT_TRUE(test::FakeTelegramServer::wait_until([&] { return persisted.load() == 101; }));
+    transport.stop();
+}
+
+// 场景:重启时把持久化的 offset 交给传输层,服务端还留着旧消息。
+// 期望:从该 offset 开始轮询,旧消息不会再次交给上层。
+TEST(TelegramTransport, ResumesFromPersistedOffset) {
+    test::FakeTelegramServer server;
+    server.push_private_text(42, "old", 1);  // update_id 100
+    server.push_private_text(42, "new", 2);  // update_id 101
+    auto options = local_options(server);
+    options.initial_offset = 101;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    TelegramTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(test::FakeTelegramServer::wait_until([&] { return recorder.count() == 1; }));
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    EXPECT_EQ(recorder.count(), 1u);
+    EXPECT_EQ(recorder.at(0).text, "new");
+}
+
+// 场景:回复一段 Markdown;第二次发送时平台说 HTML 实体解析失败。
+// 期望:第一次以 HTML 发出并引用原消息;第二次同一内容改以纯文本重发成功。
+TEST(TelegramTransport, SendsHtmlAndFallsBackToPlainText) {
+    test::FakeTelegramServer server;
+    std::atomic<int> sends{0};
+    server.override = [&](const test::FakeTelegramServer::Call& call) -> nlohmann::json {
+        if (call.method != "sendMessage") return nullptr;
+        if (++sends == 2)
+            return {{"ok", false}, {"error_code", 400}, {"description", "Bad Request: can't parse entities"}};
+        return nullptr;
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    TelegramTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    Address to;
+    to.platform = "telegram";
+    to.account = "8001";
+    to.chat = to.sender = "42";
+    EXPECT_EQ(transport.send_text(to, "**粗体** <tag>", {{"message_id", 55}}).outcome, SendOutcome::Sent);
+    EXPECT_EQ(transport.send_text(to, "**第二条**", {{"message_id", 56}}).outcome, SendOutcome::Sent);
+    const auto calls = server.calls_to("sendMessage");
+    ASSERT_EQ(calls.size(), 3u);
+    EXPECT_EQ(calls[0].body.value("parse_mode", ""), "HTML");
+    EXPECT_EQ(calls[0].body.value("text", ""), u8"<b>粗体</b> &lt;tag&gt;");
+    EXPECT_EQ(calls[0].body["reply_parameters"].value("message_id", 0), 55);
+    EXPECT_FALSE(calls[2].body.contains("parse_mode"));
+    EXPECT_EQ(calls[2].body.value("text", ""), u8"第二条");
+}
+
+// 场景:平台对一次发送返回 429,要求等 1 秒。
+// 期望:传输层等待后重发同一条消息并成功。
+TEST(TelegramTransport, RetriesAfterRateLimit) {
+    test::FakeTelegramServer server;
+    std::atomic<int> sends{0};
+    server.override = [&](const test::FakeTelegramServer::Call& call) -> nlohmann::json {
+        if (call.method != "sendMessage" || ++sends > 1) return nullptr;
+        return {{"ok", false}, {"error_code", 429}, {"description", "Too Many Requests"}, {"parameters", {{"retry_after", 1}}}};
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    TelegramTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    Address to;
+    to.platform = "telegram";
+    to.account = "8001";
+    to.chat = to.sender = "42";
+    const auto start = std::chrono::steady_clock::now();
+    EXPECT_EQ(transport.send_text(to, "hello", {}).outcome, SendOutcome::Sent);
+    EXPECT_GE(std::chrono::steady_clock::now() - start, std::chrono::milliseconds(900));
+    EXPECT_EQ(server.calls_to("sendMessage").size(), 2u);
+}
+
+// 场景:机器人配置了 webhook,getUpdates 返回 409;用户在设置页确认“移除 webhook 并连接”。
+// 期望:先进入失败状态并标出 webhook;执行移除动作后调用 deleteWebhook,随后恢复轮询并连上。
+TEST(TelegramTransport, WebhookConflictWaitsForUserConfirmation) {
+    test::FakeTelegramServer server;
+    std::atomic<bool> webhook{true};
+    server.override = [&](const test::FakeTelegramServer::Call& call) -> nlohmann::json {
+        if (call.method == "deleteWebhook") {
+            webhook = false;
+            return nullptr;
+        }
+        if (call.method == "getUpdates" && webhook)
+            return {{"ok", false}, {"error_code", 409},
+                    {"description", "Conflict: can't use getUpdates method while webhook is active"}};
+        return nullptr;
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    TelegramTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Failed));
+    EXPECT_TRUE(transport.status().extra.value("webhook", false));
+    EXPECT_TRUE(server.calls_to("deleteWebhook").empty());
+    EXPECT_TRUE(transport.action("remove_webhook", nlohmann::json::object()).value("ok", false));
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    EXPECT_EQ(server.calls_to("deleteWebhook").size(), 1u);
+}
+
+// 场景:另一个程序正在用同一个 token 长轮询;以及 token 已被吊销。
+// 期望:前者显示“被其他程序占用”并稍后重试;后者直接失败、停止重试。
+TEST(TelegramTransport, ReportsOtherPollerAndInvalidToken) {
+    test::FakeTelegramServer server;
+    server.override = [&](const test::FakeTelegramServer::Call& call) -> nlohmann::json {
+        if (call.method != "getUpdates") return nullptr;
+        return {{"ok", false}, {"error_code", 409}, {"description", "Conflict: terminated by other getUpdates request"}};
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    TelegramTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Retrying));
+    EXPECT_NE(transport.status().detail.find(u8"占用"), std::string::npos);
+    transport.stop();
+
+    auto options = local_options(server);
+    options.api.token = "999999:WRONG-TOKEN-zyxwvutsrqponmlkjihgfedcba";
+    TelegramTransport bad(options);
+    bad.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(bad, LinkState::Failed));
+    EXPECT_TRUE(bad.status().retry_stopped);
+    EXPECT_EQ(bad.status().detail.find("WRONG-TOKEN"), std::string::npos);
+}
+
+// 场景:会话开始忙碌时打开“正在输入”,结束时关闭。
+// 期望:忙碌期间持续发送 sendChatAction(typing);关闭后不再发送。
+TEST(TelegramTransport, TypingIndicatorRepeatsWhileBusy) {
+    test::FakeTelegramServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    TelegramTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    Address to;
+    to.platform = "telegram";
+    to.account = "8001";
+    to.chat = to.sender = "42";
+    transport.set_typing(to, true);
+    ASSERT_TRUE(test::FakeTelegramServer::wait_until([&] { return server.calls_to("sendChatAction").size() >= 2; }));
+    transport.set_typing(to, false);
+    std::this_thread::sleep_for(std::chrono::milliseconds(150));
+    const auto after = server.calls_to("sendChatAction").size();
+    std::this_thread::sleep_for(std::chrono::milliseconds(300));
+    EXPECT_EQ(server.calls_to("sendChatAction").size(), after);
+    EXPECT_EQ(server.calls_to("sendChatAction").at(0).body.value("action", ""), "typing");
+}
+
+// 场景:回传一个中文文件名的文档和一张图片;再下载用户发来的文件,以及一个超大文件。
+// 期望:文档走 sendDocument,multipart 文件名降为 ASCII(全是非 ASCII 时用 file)、原名放进 caption;
+// 图片走 sendPhoto;
+// 下载经 getFile 拿到路径后成功;超出 20 MB 的文件被拒。
+TEST(TelegramTransport, SendsAndDownloadsFiles) {
+    test::FakeTelegramServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    TelegramTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    Address to;
+    to.platform = "telegram";
+    to.account = "8001";
+    to.chat = to.sender = "42";
+    const auto dir = std::filesystem::path(testing::TempDir()) / "acecode-tg-files";
+    std::filesystem::create_directories(dir);
+    { std::ofstream(dir / "r.pdf", std::ios::binary) << "PDF"; }
+    { std::ofstream(dir / "p.png", std::ios::binary) << "PNG"; }
+    EXPECT_EQ(transport.send_file(to, dir / "r.pdf", u8"报告.pdf", "application/pdf", {}).outcome, SendOutcome::Sent);
+    EXPECT_EQ(transport.send_file(to, dir / "p.png", "p.png", "image/png", {}).outcome, SendOutcome::Sent);
+    const auto docs = server.calls_to("sendDocument");
+    ASSERT_EQ(docs.size(), 1u);
+    EXPECT_EQ(docs[0].file_name, "file.pdf");
+    EXPECT_EQ(docs[0].body.value("caption", ""), u8"报告.pdf");
+    EXPECT_EQ(docs[0].file_body, "PDF");
+    EXPECT_EQ(server.calls_to("sendPhoto").size(), 1u);
+
+    Attachment attachment;
+    attachment.kind = AttachmentKind::File;
+    attachment.remote_ref = "f1";
+    std::string error;
+    ASSERT_TRUE(transport.download(attachment, dir / "in.bin", &error)) << error;
+    EXPECT_EQ(std::filesystem::file_size(dir / "in.bin"), 32u);
+    attachment.remote_ref = "too-big";
+    EXPECT_FALSE(transport.download(attachment, dir / "big.bin", &error));
+    std::filesystem::remove_all(dir);
+}
+
+// 场景:长轮询进行中(服务端挂起请求)时关闭通道。
+// 期望:stop 在 3 秒内返回,不必等长轮询超时。
+TEST(TelegramTransport, StopsPromptlyDuringLongPoll) {
+    test::FakeTelegramServer server;
+    auto options = local_options(server);
+    options.poll_timeout = std::chrono::seconds(25);
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    TelegramTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(test::FakeTelegramServer::wait_until([&] { return !server.calls_to("getUpdates").empty(); }));
+    const auto start = std::chrono::steady_clock::now();
+    transport.stop();
+    EXPECT_LT(std::chrono::steady_clock::now() - start, std::chrono::seconds(3));
+    EXPECT_EQ(transport.status().state, LinkState::Stopped);
+}
+
+// 场景:打开开关后一直没有新消息,第一次长轮询要挂到超时才返回(真实平台是 25 秒)。
+// 期望:getMe 成功后立即显示已连接,不必等第一次长轮询返回。
+// 回归:曾经要等第一次 getUpdates 返回才置已连接,设置页打开开关后长时间停在“连接中”。
+TEST(TelegramTransport, ReportsConnectedBeforeFirstLongPollReturns) {
+    test::FakeTelegramServer server;
+    std::atomic<bool> release{false};
+    server.override = [&](const test::FakeTelegramServer::Call& call) -> nlohmann::json {
+        if (call.method != "getUpdates") return nullptr;
+        for (int i = 0; i < 150 && !release; ++i) std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        return {{"ok", true}, {"result", nlohmann::json::array()}};
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    TelegramTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    EXPECT_TRUE(test::FakeTelegramServer::wait_until(
+        [&] { return transport.status().state == LinkState::Connected; }, std::chrono::milliseconds(1000)));
+    release = true;
+    transport.stop();
+}
+
+} // namespace
+} // namespace acecode::im::telegram
diff --git a/tests/im/tg_update_test.cpp b/tests/im/tg_update_test.cpp
new file mode 100644
index 000000000..de3ebfc81
--- /dev/null
+++ b/tests/im/tg_update_test.cpp
@@ -0,0 +1,147 @@
+#include <gtest/gtest.h>
+
+#include "im/telegram/tg_update.hpp"
+
+// im/telegram/tg_update:Telegram 更新解析。重点是群聊“是否点名机器人”的判定,
+// 以及 entity 偏移按 UTF-16 计、要换算成 UTF-8 字节的问题。
+
+namespace acecode::im::telegram {
+namespace {
+
+const BotIdentity kBot{"8001", "AceTestBot"};
+
+nlohmann::json message(nlohmann::json chat, nlohmann::json extra) {
+    nlohmann::json m{{"message_id", 55}, {"from", {{"id", 42}, {"is_bot", false}, {"first_name", "Ann"}}},
+                     {"chat", std::move(chat)}};
+    for (auto& [k, v] : extra.items()) m[k] = v;
+    return {{"update_id", 7}, {"message", m}};
+}
+
+nlohmann::json group_chat() { return {{"id", -1001}, {"type", "supergroup"}}; }
+
+// 场景:私聊里发 "/start abc123"(机主绑定链接带的码)。
+// 期望:视为点名,地址为私聊(chat 与 sender 都是对方 id),提取出绑定码,回复上下文带 message_id。
+TEST(TelegramUpdate, PrivateStartCarriesBindingCode) {
+    const auto parsed = parse_update(message({{"id", 42}, {"type", "private"}}, {{"text", "/start abc123"}}), kBot, "8001");
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_EQ(parsed.update_id, 7);
+    const auto& in = *parsed.inbound;
+    EXPECT_EQ(in.address.kind, ChatKind::Private);
+    EXPECT_EQ(in.address.chat, "42");
+    EXPECT_EQ(in.address.sender, "42");
+    EXPECT_TRUE(in.mentioned);
+    EXPECT_EQ(in.start_code, "abc123");
+    EXPECT_EQ(in.reply_context.value("message_id", 0), 55);
+}
+
+// 场景:群消息开头是 emoji(占 2 个 UTF-16 单位),后面 @AceTestBot。
+// 期望:按 UTF-16 偏移正确找到 mention 并判定为点名;正文里去掉 @机器人。
+TEST(TelegramUpdate, GroupMentionWithUtf16Offsets) {
+    const std::string text = u8"😀 @AceTestBot 帮我看看";
+    const auto parsed = parse_update(
+        message(group_chat(), {{"text", text},
+                               {"entities", nlohmann::json::array({{{"type", "mention"}, {"offset", 3}, {"length", 11}}})}}),
+        kBot, "8001");
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_TRUE(parsed.inbound->mentioned);
+    EXPECT_EQ(parsed.inbound->address.kind, ChatKind::Group);
+    EXPECT_EQ(parsed.inbound->address.chat, "-1001");
+    EXPECT_EQ(parsed.inbound->address.sender, "42");
+    EXPECT_EQ(parsed.inbound->text, u8"😀  帮我看看");
+}
+
+// 场景:群里发 "/status@AceTestBot";另一条 @ 的是别的机器人;第三条没有任何点名。
+// 期望:第一条算点名且命令变成 "/status";后两条都不算点名(核心会忽略)。
+TEST(TelegramUpdate, CommandsForThisBotCountOthersDoNot) {
+    const auto command = parse_update(
+        message(group_chat(), {{"text", "/status@AceTestBot"},
+                               {"entities", nlohmann::json::array({{{"type", "bot_command"}, {"offset", 0}, {"length", 18}}})}}),
+        kBot, "8001");
+    ASSERT_TRUE(command.inbound);
+    EXPECT_TRUE(command.inbound->mentioned);
+    EXPECT_EQ(command.inbound->text, "/status");
+    const auto other = parse_update(
+        message(group_chat(), {{"text", "@OtherBot hi"},
+                               {"entities", nlohmann::json::array({{{"type", "mention"}, {"offset", 0}, {"length", 9}}})}}),
+        kBot, "8001");
+    ASSERT_TRUE(other.inbound);
+    EXPECT_FALSE(other.inbound->mentioned);
+    const auto plain = parse_update(message(group_chat(), {{"text", "just chatting"}}), kBot, "8001");
+    ASSERT_TRUE(plain.inbound);
+    EXPECT_FALSE(plain.inbound->mentioned);
+}
+
+// 场景:群里直接回复机器人之前的一条消息,话题群里带 message_thread_id。
+// 期望:回复机器人算点名;记下被引用的文字与话题 id(话题只用于回复定位)。
+TEST(TelegramUpdate, ReplyToBotCountsAsMentionAndKeepsThread) {
+    const auto parsed = parse_update(
+        message(group_chat(), {{"text", "继续"},
+                               {"is_topic_message", true},
+                               {"message_thread_id", 9},
+                               {"reply_to_message", {{"message_id", 50}, {"from", {{"id", 8001}, {"is_bot", true}}},
+                                                     {"text", "上一条回答"}}}}),
+        kBot, "8001");
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_TRUE(parsed.inbound->mentioned);
+    EXPECT_EQ(parsed.inbound->address.thread, "9");
+    EXPECT_EQ(parsed.inbound->quote_text, u8"上一条回答");
+    EXPECT_EQ(parsed.inbound->reply_context.value("thread", ""), "9");
+}
+
+// 场景:带说明文字的照片(多个尺寸)、图片类型的文件、语音、贴纸。
+// 期望:照片取上限内最大的尺寸并用 caption 作正文;图片文件识别为图片;
+// 语音与贴纸标为对应类型(核心会回复“暂不支持”)。
+TEST(TelegramUpdate, ParsesMediaAttachments) {
+    const auto photo = parse_update(
+        message({{"id", 42}, {"type", "private"}},
+                {{"caption", "看这张"},
+                 {"photo", nlohmann::json::array({{{"file_id", "small"}, {"file_size", 100}},
+                                                  {{"file_id", "large"}, {"file_size", 2000}}})}}),
+        kBot, "8001");
+    ASSERT_TRUE(photo.inbound);
+    EXPECT_EQ(photo.inbound->text, u8"看这张");
+    ASSERT_EQ(photo.inbound->attachments.size(), 1u);
+    EXPECT_EQ(photo.inbound->attachments[0].kind, AttachmentKind::Image);
+    EXPECT_EQ(photo.inbound->attachments[0].remote_ref, "large");
+
+    const auto doc = parse_update(
+        message({{"id", 42}, {"type", "private"}},
+                {{"document", {{"file_id", "d1"}, {"file_name", "a.png"}, {"mime_type", "image/png"}, {"file_size", 10}}}}),
+        kBot, "8001");
+    ASSERT_TRUE(doc.inbound);
+    EXPECT_EQ(doc.inbound->attachments.at(0).kind, AttachmentKind::Image);
+    EXPECT_EQ(doc.inbound->attachments.at(0).name, "a.png");
+
+    const auto voice = parse_update(message({{"id", 42}, {"type", "private"}}, {{"voice", {{"file_id", "v1"}}}}), kBot, "8001");
+    ASSERT_TRUE(voice.inbound);
+    EXPECT_EQ(voice.inbound->attachments.at(0).kind, AttachmentKind::Voice);
+    const auto sticker = parse_update(message({{"id", 42}, {"type", "private"}}, {{"sticker", {{"file_id", "s1"}}}}), kBot, "8001");
+    ASSERT_TRUE(sticker.inbound);
+    EXPECT_EQ(sticker.inbound->attachments.at(0).kind, AttachmentKind::Sticker);
+}
+
+// 场景:频道帖子、其它机器人发的消息、非 message 更新。
+// 期望:都不产生入站消息,但 update_id 照常返回,用于推进 offset。
+TEST(TelegramUpdate, IgnoresChannelsBotsAndOtherUpdates) {
+    const auto channel = parse_update(message({{"id", -1009}, {"type", "channel"}}, {{"text", "post"}}), kBot, "8001");
+    EXPECT_FALSE(channel.inbound);
+    EXPECT_EQ(channel.update_id, 7);
+    auto from_bot = message({{"id", 42}, {"type", "private"}}, {{"text", "hi"}});
+    from_bot["message"]["from"]["is_bot"] = true;
+    EXPECT_FALSE(parse_update(from_bot, kBot, "8001").inbound);
+    const auto edited = parse_update({{"update_id", 8}, {"edited_message", {{"text", "x"}}}}, kBot, "8001");
+    EXPECT_FALSE(edited.inbound);
+    EXPECT_EQ(edited.update_id, 8);
+}
+
+// 场景:按 UTF-16 偏移切含 emoji 与中文的文本,包括越界的长度。
+// 期望:切出的子串与按字符直觉一致;越界时截到末尾,不切断字符。
+TEST(TelegramUpdate, Utf16SliceHandlesSurrogatePairs) {
+    const std::string text = u8"a😀中b";
+    EXPECT_EQ(utf16_slice(text, 1, 2), u8"😀");
+    EXPECT_EQ(utf16_slice(text, 3, 1), u8"中");
+    EXPECT_EQ(utf16_slice(text, 3, 100), u8"中b");
+}
+
+} // namespace
+} // namespace acecode::im::telegram
diff --git a/tests/im/transport_test.cpp b/tests/im/transport_test.cpp
new file mode 100644
index 000000000..3e2c03a1c
--- /dev/null
+++ b/tests/im/transport_test.cpp
@@ -0,0 +1,87 @@
+#include <gtest/gtest.h>
+
+#include "im/transport.hpp"
+
+// im/transport:IM 会话地址是会话绑定、去重回执和授权记录的主键。
+
+namespace acecode::im {
+namespace {
+
+Address private_chat() {
+    Address a;
+    a.platform = "telegram";
+    a.account = "8001";
+    a.kind = ChatKind::Private;
+    a.chat = "42";
+    a.sender = "42";
+    return a;
+}
+
+// 场景:同一个人分别在私聊、群 A、群 B 里发消息;群里还有另一个成员。
+// 期望:四个地址的会话键各不相同;话题 id 不参与会话键(同一人在群里不同话题仍是同一会话)。
+TEST(ImAddress, KeysSeparatePrivateGroupsAndSenders) {
+    const auto dm = private_chat();
+    auto group_a = dm;
+    group_a.kind = ChatKind::Group;
+    group_a.chat = "-1001";
+    auto group_b = group_a;
+    group_b.chat = "-1002";
+    auto other_member = group_a;
+    other_member.sender = "43";
+    EXPECT_NE(dm.key(), group_a.key());
+    EXPECT_NE(group_a.key(), group_b.key());
+    EXPECT_NE(group_a.key(), other_member.key());
+    auto with_thread = group_a;
+    with_thread.thread = "7";
+    EXPECT_EQ(group_a.key(), with_thread.key());
+}
+
+// 场景:地址写入 state.json 后再读回。
+// 期望:往返后字段与会话键完全一致;kind 非法时读取失败而不是默认成私聊。
+TEST(ImAddress, JsonRoundTripAndRejectsUnknownKind) {
+    auto group = private_chat();
+    group.kind = ChatKind::Group;
+    group.chat = "-1001";
+    group.thread = "9";
+    const auto restored = Address::from_json(group.to_json());
+    EXPECT_EQ(restored.key(), group.key());
+    EXPECT_EQ(restored.thread, "9");
+    auto bad = group.to_json();
+    bad["kind"] = "channel";
+    EXPECT_THROW(Address::from_json(bad), std::runtime_error);
+}
+
+// 场景:校验来自平台的地址。
+// 期望:私聊要求 chat 与 sender 相同;未知平台、空 id、含空格或换行的 id 一律无效;
+// 钉钉 base64 形式的会话 id(含 + / =)与 $:LWCP_v1:$ 形式的发送人 id、微信 …@im.wechat 有效。
+TEST(ImAddress, ValidationRejectsMalformedAddresses) {
+    EXPECT_TRUE(private_chat().valid());
+    auto mismatched = private_chat();
+    mismatched.sender = "43";
+    EXPECT_FALSE(mismatched.valid());
+    auto unknown = private_chat();
+    unknown.platform = "whatsapp";
+    EXPECT_FALSE(unknown.valid());
+    auto spaced = private_chat();
+    spaced.chat = spaced.sender = "a b";
+    EXPECT_FALSE(spaced.valid());
+    auto newline = private_chat();
+    newline.chat = newline.sender = "a\nb";
+    EXPECT_FALSE(newline.valid());
+    auto dingtalk = private_chat();
+    dingtalk.platform = "dingtalk";
+    dingtalk.kind = ChatKind::Group;
+    dingtalk.chat = "cidb4uF+pXo/FpKMw==";
+    dingtalk.sender = "$:LWCP_v1:$abcDEF";
+    EXPECT_TRUE(dingtalk.valid());
+    auto weixin = private_chat();
+    weixin.platform = "weixin";
+    weixin.chat = weixin.sender = "o9cq80wW@im.wechat";
+    EXPECT_TRUE(weixin.valid());
+    auto empty = private_chat();
+    empty.account.clear();
+    EXPECT_FALSE(empty.valid());
+}
+
+} // namespace
+} // namespace acecode::im
diff --git a/tests/im/weixin_login_test.cpp b/tests/im/weixin_login_test.cpp
new file mode 100644
index 000000000..031651e23
--- /dev/null
+++ b/tests/im/weixin_login_test.cpp
@@ -0,0 +1,211 @@
+#include <gtest/gtest.h>
+
+#include "im/weixin/weixin_login.hpp"
+#include "test_support/im/fake_weixin_server.hpp"
+
+#include <atomic>
+#include <mutex>
+#include <thread>
+#include <vector>
+
+// im/weixin/weixin_login:微信 ClawBot 扫码登录流程。用本机假 iLink 服务代替 ilinkai.weixin.qq.com;
+// 真实服务的状态查询会挂起约 30 秒,假服务立即应答,轮询间隔缩短到 20ms。
+
+namespace acecode::im::weixin {
+namespace {
+
+LoginOptions local_options(const test::FakeWeixinServer& server) {
+    LoginOptions options;
+    options.api_base = server.base();
+    options.use_proxy = false;
+    options.poll_interval = std::chrono::milliseconds(20);
+    options.total_timeout = std::chrono::seconds(5);
+    options.redirect_scheme = "http";
+    return options;
+}
+
+nlohmann::json confirmed(const std::string& base_url = "https://ilinkai.weixin.qq.com") {
+    return {{"ret", 0},
+            {"status", "confirmed"},
+            {"bot_token", "bot-token-SECRET-123456"},
+            {"ilink_bot_id", "e06c1ceea05e@im.bot"},
+            {"baseurl", base_url},
+            {"ilink_user_id", "o9cq800kum_owner@im.wechat"}};
+}
+
+struct ProgressLog {
+    std::mutex mu;
+    std::vector<LoginProgress> steps;
+    LoginProgressFn fn() {
+        return [this](const LoginProgress& step) {
+            std::lock_guard<std::mutex> lock(mu);
+            steps.push_back(step);
+        };
+    }
+};
+
+// 场景:用户扫码,状态依次为 wait → scaned → confirmed。
+// 期望:先回调一次二维码(内容是 qrcode_img_content 的 liteapp 网址,不是 32 位令牌),扫码后回调一次
+// Scanned;结果带回 bot_token、ilink_bot_id、baseurl 与扫码人;状态查询带上令牌,
+// 并只带 iLink-App-Id: bot 与 ClientVersion 131584 两个协议头(没有 Authorization)。
+TEST(WeixinLogin, CompletesAfterScanAndConfirm) {
+    test::FakeWeixinServer server;
+    std::atomic<int> polls{0};
+    server.qr_status_handler = [&](const test::FakeWeixinServer::Call&) {
+        const int n = ++polls;
+        if (n == 1) return nlohmann::json{{"ret", 0}, {"status", "wait"}};
+        if (n == 2) return nlohmann::json{{"ret", 0}, {"status", "scaned"}};
+        if (n == 3) return nlohmann::json{{"ret", 0}, {"status", "scaned"}};
+        return confirmed();
+    };
+    ProgressLog log;
+    std::atomic<bool> cancelled{false};
+    const auto result = run_login(local_options(server), cancelled, log.fn());
+    ASSERT_EQ(result.phase, LoginPhase::Completed) << result.error;
+    EXPECT_EQ(result.bot_token, "bot-token-SECRET-123456");
+    EXPECT_EQ(result.bot_id, "e06c1ceea05e@im.bot");
+    EXPECT_EQ(result.base_url, "https://ilinkai.weixin.qq.com");
+    EXPECT_EQ(result.user_id, "o9cq800kum_owner@im.wechat");
+    EXPECT_EQ(result.refreshes, 0);
+
+    ASSERT_EQ(log.steps.size(), 2u);
+    EXPECT_EQ(log.steps[0].phase, LoginPhase::WaitingScan);
+    EXPECT_EQ(log.steps[0].qr_url, "https://liteapp.weixin.qq.com/q/7GiQu1?qrcode=qr-1&bot_type=3");
+    EXPECT_EQ(log.steps[1].phase, LoginPhase::Scanned);
+    EXPECT_EQ(log.steps[1].qr_url, log.steps[0].qr_url);
+
+    const auto qr = server.calls_to("get_bot_qrcode");
+    ASSERT_EQ(qr.size(), 1u);
+    EXPECT_EQ(qr[0].method, "GET");
+    EXPECT_EQ(qr[0].query.at("bot_type"), "3");
+    const auto status = server.calls_to("get_qrcode_status");
+    ASSERT_FALSE(status.empty());
+    EXPECT_EQ(status[0].query.at("qrcode"), "qr-1");
+    EXPECT_EQ(status[0].headers.at("iLink-App-Id"), "bot");
+    EXPECT_EQ(status[0].headers.at("iLink-App-ClientVersion"), "131584");
+    EXPECT_EQ(status[0].headers.count("Authorization"), 0u);
+}
+
+// 场景:第一张二维码过期(expired),平台再发一张新的,用户扫第二张。
+// 期望:自动重新申请二维码并回调新地址(两次地址不同),之后用新令牌查询,最终完成且 refreshes = 1。
+TEST(WeixinLogin, RefreshesExpiredQrCode) {
+    test::FakeWeixinServer server;
+    server.qr_status_handler = [&](const test::FakeWeixinServer::Call& call) {
+        if (call.query.at("qrcode") == "qr-1") return nlohmann::json{{"ret", 0}, {"status", "expired"}};
+        return confirmed();
+    };
+    ProgressLog log;
+    std::atomic<bool> cancelled{false};
+    const auto result = run_login(local_options(server), cancelled, log.fn());
+    ASSERT_EQ(result.phase, LoginPhase::Completed) << result.error;
+    EXPECT_EQ(result.refreshes, 1);
+    ASSERT_EQ(log.steps.size(), 2u);
+    EXPECT_NE(log.steps[0].qr_url, log.steps[1].qr_url);
+    EXPECT_EQ(log.steps[1].refreshes, 1);
+    EXPECT_EQ(server.calls_to("get_bot_qrcode").size(), 2u);
+}
+
+// 场景:二维码一直过期(用户迟迟不扫),换码次数超过上限。
+// 期望:返回 Failed 并说明“多次过期”,不会无限换码。
+TEST(WeixinLogin, GivesUpAfterTooManyExpiredCodes) {
+    test::FakeWeixinServer server;
+    server.qr_status_handler = [](const test::FakeWeixinServer::Call&) {
+        return nlohmann::json{{"ret", 0}, {"status", "expired"}};
+    };
+    auto options = local_options(server);
+    options.max_refreshes = 2;
+    std::atomic<bool> cancelled{false};
+    const auto result = run_login(options, cancelled, {});
+    EXPECT_EQ(result.phase, LoginPhase::Failed);
+    EXPECT_NE(result.error.find(u8"多次过期"), std::string::npos) << result.error;
+    EXPECT_EQ(server.calls_to("get_bot_qrcode").size(), 3u);
+}
+
+// 场景:扫码后平台要求把轮询换到另一个机房(scaned_but_redirect + redirect_host)。
+// 期望:之后用同一个令牌到新地址轮询,在那里拿到确认;没有返回 baseurl 时沿用默认接口地址。
+TEST(WeixinLogin, FollowsRedirectHost) {
+    test::FakeWeixinServer primary;
+    test::FakeWeixinServer redirected;
+    primary.qr_status_handler = [&](const test::FakeWeixinServer::Call&) {
+        return nlohmann::json{{"ret", 0}, {"status", "scaned_but_redirect"}, {"redirect_host", redirected.host()}};
+    };
+    redirected.qr_status_handler = [](const test::FakeWeixinServer::Call&) {
+        auto done = confirmed();
+        done.erase("baseurl");
+        return done;
+    };
+    ProgressLog log;
+    std::atomic<bool> cancelled{false};
+    const auto result = run_login(local_options(primary), cancelled, log.fn());
+    ASSERT_EQ(result.phase, LoginPhase::Completed) << result.error;
+    EXPECT_EQ(result.base_url, primary.base());
+    EXPECT_EQ(primary.calls_to("get_qrcode_status").size(), 1u);
+    const auto moved = redirected.calls_to("get_qrcode_status");
+    ASSERT_FALSE(moved.empty());
+    EXPECT_EQ(moved[0].query.at("qrcode"), "qr-1");
+    ASSERT_EQ(log.steps.size(), 2u);
+    EXPECT_EQ(log.steps[1].phase, LoginPhase::Scanned);
+}
+
+// 场景:新版协议要求在电脑上输入手机显示的数字(need_verifycode),ACECode 不支持这一步。
+// 期望:不挂起等待,立即返回 Failed,原因用中文说明需要验证数字。
+TEST(WeixinLogin, VerificationCodeFailsWithClearMessage) {
+    test::FakeWeixinServer server;
+    server.qr_status_handler = [](const test::FakeWeixinServer::Call&) {
+        return nlohmann::json{{"ret", 0}, {"status", "need_verifycode"}};
+    };
+    std::atomic<bool> cancelled{false};
+    const auto result = run_login(local_options(server), cancelled, {});
+    EXPECT_EQ(result.phase, LoginPhase::Failed);
+    EXPECT_NE(result.error.find(u8"验证数字"), std::string::npos) << result.error;
+    EXPECT_TRUE(result.bot_token.empty());
+}
+
+// 场景:申请二维码时平台报错;以及确认结果里缺少机器人 id。
+// 期望:前者 Failed 并带平台原因;后者 Failed,且不返回任何凭据。
+TEST(WeixinLogin, ReportsQrFailureAndIncompleteConfirmation) {
+    test::FakeWeixinServer server;
+    server.qr_handler = [](const test::FakeWeixinServer::Call&) {
+        return nlohmann::json{{"ret", -1}, {"errmsg", "bot_type invalid"}};
+    };
+    std::atomic<bool> cancelled{false};
+    const auto failed = run_login(local_options(server), cancelled, {});
+    EXPECT_EQ(failed.phase, LoginPhase::Failed);
+    EXPECT_NE(failed.error.find("bot_type invalid"), std::string::npos) << failed.error;
+
+    test::FakeWeixinServer partial;
+    partial.qr_status_handler = [](const test::FakeWeixinServer::Call&) {
+        auto done = confirmed();
+        done.erase("ilink_bot_id");
+        return done;
+    };
+    const auto incomplete = run_login(local_options(partial), cancelled, {});
+    EXPECT_EQ(incomplete.phase, LoginPhase::Failed);
+    EXPECT_TRUE(incomplete.bot_token.empty());
+}
+
+// 场景:二维码已显示,用户点了取消;以及一直没人扫码直到总超时。
+// 期望:取消后很快返回 Cancelled;超时返回 TimedOut。均不产生凭据。
+TEST(WeixinLogin, CancelAndTimeout) {
+    test::FakeWeixinServer server;
+    std::atomic<bool> cancelled{false};
+    auto options = local_options(server);
+    options.poll_interval = std::chrono::seconds(10);
+    LoginResult result;
+    std::thread runner([&] { result = run_login(options, cancelled, {}); });
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return !server.calls_to("get_qrcode_status").empty(); }));
+    const auto start = std::chrono::steady_clock::now();
+    cancelled = true;
+    runner.join();
+    EXPECT_EQ(result.phase, LoginPhase::Cancelled);
+    EXPECT_TRUE(result.bot_token.empty());
+    EXPECT_LT(std::chrono::steady_clock::now() - start, std::chrono::seconds(2));
+
+    std::atomic<bool> idle{false};
+    auto quick = local_options(server);
+    quick.total_timeout = std::chrono::milliseconds(300);
+    EXPECT_EQ(run_login(quick, idle, {}).phase, LoginPhase::TimedOut);
+}
+
+} // namespace
+} // namespace acecode::im::weixin
diff --git a/tests/im/weixin_protocol_test.cpp b/tests/im/weixin_protocol_test.cpp
new file mode 100644
index 000000000..1191123ef
--- /dev/null
+++ b/tests/im/weixin_protocol_test.cpp
@@ -0,0 +1,357 @@
+#include <gtest/gtest.h>
+
+#include "im/weixin/weixin_media.hpp"
+#include "im/weixin/weixin_protocol.hpp"
+#include "platform/crypto/aes_ecb.hpp"
+
+// im/weixin/weixin_protocol + weixin_media 的纯逻辑:请求头取值、响应包络判定、入站解析、
+// 媒体密钥格式、出站条目、片段合并与去重。测试向量来自微信协议调研文档(hermes / 官方插件实测值)。
+
+namespace acecode::im::weixin {
+namespace {
+
+constexpr const char* kBot = "e06c1ceea05e@im.bot";
+constexpr const char* kUser = "o9cq800kum_owner@im.wechat";
+
+std::string bytes_0_to_15() {
+    std::string key;
+    for (int i = 0; i < 16; ++i) key.push_back(static_cast<char>(i));
+    return key;
+}
+
+nlohmann::json text_message(const std::string& text) {
+    return {{"seq", 429},
+            {"message_id", 7351234567890123456ULL},
+            {"from_user_id", kUser},
+            {"to_user_id", kBot},
+            {"create_time_ms", 1759712345678LL},
+            {"message_type", 1},
+            {"message_state", 2},
+            {"context_token", "AARzJWAFAAABAAAAAAAp2m3u7oE0x7V8Xw=="},
+            {"item_list", nlohmann::json::array({{{"type", 1}, {"text_item", {{"text", text}}}}})}};
+}
+
+Inbound make_inbound(const std::string& sender, const std::string& text, const std::string& id) {
+    Inbound inbound;
+    inbound.address.platform = "weixin";
+    inbound.address.account = kBot;
+    inbound.address.chat = inbound.address.sender = sender;
+    inbound.message_id = id;
+    inbound.text = text;
+    inbound.mentioned = true;
+    return inbound;
+}
+
+// 场景:按 hermes 的 2.2.0 版本声明协议版本,并为每个请求生成 X-WECHAT-UIN。
+// 期望:ClientVersion = (主<<16)|(次<<8)|修订(2.2.0 → 131584,2.4.9 → 132105);
+// X-WECHAT-UIN 是十进制数字字符串的 base64(文档示例 3141592653 → MzE0MTU5MjY1Mw==)。
+TEST(WeixinProtocol, ClientVersionAndUinHeader) {
+    EXPECT_EQ(client_version_number("2.2.0"), 131584u);
+    EXPECT_EQ(client_version_number("2.4.9"), 132105u);
+    EXPECT_EQ(client_version_number("garbage"), 0u);
+    EXPECT_EQ(wechat_uin(3141592653u), "MzE0MTU5MjY1Mw==");
+    EXPECT_EQ(join_url("https://a.example/", "/ilink/bot/getupdates"), "https://a.example/ilink/bot/getupdates");
+    EXPECT_EQ(url_encode("a b/c+d=e"), "a%20b%2Fc%2Bd%3De");
+}
+
+// 场景:平台的应用层错误以 HTTP 200 返回,且实测失效 token 的应答只有 errcode 没有 ret。
+// 期望:{"errcode":-14} 判为失败且是“登录失效”;-2 + "unknown error" 也是失效(hermes #17228);
+// -2 + "freq limit" 是限频;-2 + 参数错误既不是失效也不是限频;字段缺失按 0 视为成功;非 JSON 判失败。
+TEST(WeixinProtocol, EnvelopeDetectsHttp200Errors) {
+    const auto expired = parse_envelope(R"({"errcode":-14,"errmsg":"session timeout"})");
+    EXPECT_TRUE(envelope_failed(expired));
+    EXPECT_TRUE(is_session_expired(expired.ret, expired.errcode, expired.errmsg));
+
+    EXPECT_TRUE(is_session_expired(-2, 0, "Unknown Error "));
+    EXPECT_FALSE(is_rate_limited(-2, 0, "unknown error"));
+    EXPECT_TRUE(is_rate_limited(-2, 0, "freq limit"));
+    EXPECT_TRUE(is_rate_limited(0, -2, ""));
+    EXPECT_FALSE(is_rate_limited(-2, 0, "parameter error"));
+    EXPECT_FALSE(is_session_expired(-2, 0, "freq limit"));
+
+    const auto ok = parse_envelope(R"({"msgs":[],"get_updates_buf":"x"})");
+    EXPECT_FALSE(envelope_failed(ok));
+    EXPECT_EQ(ok.body.value("get_updates_buf", ""), "x");
+    EXPECT_TRUE(envelope_failed(parse_envelope("not json")));
+    EXPECT_TRUE(envelope_failed(parse_envelope(R"({"ret":-1})")));
+}
+
+// 场景:收到用户私聊的一条文字,message_id 是超过 2^53 的 uint64。
+// 期望:地址为 weixin / 机器人 id / 私聊 / chat = sender = 用户 id,私聊恒为点名;
+// message_id 原样转成十进制(不丢精度);context_token 与发送时间被取出;回复定位只带消息 id。
+TEST(WeixinProtocol, ParsesPrivateTextMessage) {
+    const auto parsed = parse_message(text_message(u8"  你好  "), kBot);
+    ASSERT_TRUE(parsed.inbound.has_value()) << parsed.drop_reason;
+    const auto& inbound = *parsed.inbound;
+    EXPECT_EQ(inbound.address.platform, "weixin");
+    EXPECT_EQ(inbound.address.account, kBot);
+    EXPECT_EQ(inbound.address.kind, ChatKind::Private);
+    EXPECT_EQ(inbound.address.chat, kUser);
+    EXPECT_EQ(inbound.address.sender, kUser);
+    EXPECT_TRUE(inbound.mentioned);
+    EXPECT_EQ(inbound.text, u8"你好");
+    EXPECT_EQ(inbound.message_id, "7351234567890123456");
+    EXPECT_EQ(inbound.reply_context.value("message_id", ""), "7351234567890123456");
+    EXPECT_FALSE(inbound.reply_context.contains("context_token"));
+    EXPECT_EQ(parsed.context_token, "AARzJWAFAAABAAAAAAAp2m3u7oE0x7V8Xw==");
+    EXPECT_EQ(parsed.create_time_ms, 1759712345678LL);
+    EXPECT_TRUE(parsed.from_user);
+}
+
+// 场景:机器人自己发出的消息、BOT 类型消息、没有发送人的消息、以及只有未知条目的空消息。
+// 期望:前三者不算用户消息(from_user = false);空消息虽不交给上层,但仍算用户消息,
+// 以便传输层记下它带来的最新 context_token。
+TEST(WeixinProtocol, DropsBotOwnAndEmptyMessages) {
+    auto own = text_message("x");
+    own["from_user_id"] = kBot;
+    EXPECT_FALSE(parse_message(own, kBot).from_user);
+
+    auto bot_type = text_message("x");
+    bot_type["message_type"] = 2;
+    EXPECT_FALSE(parse_message(bot_type, kBot).from_user);
+
+    auto anonymous = text_message("x");
+    anonymous.erase("from_user_id");
+    EXPECT_FALSE(parse_message(anonymous, kBot).from_user);
+
+    auto empty = text_message("x");
+    empty["item_list"] = nlohmann::json::array({{{"type", 11}}});
+    const auto parsed = parse_message(empty, kBot);
+    EXPECT_TRUE(parsed.from_user);
+    EXPECT_FALSE(parsed.inbound.has_value());
+    EXPECT_EQ(parsed.context_token, "AARzJWAFAAABAAAAAAAp2m3u7oE0x7V8Xw==");
+}
+
+// 场景:用户引用一条文字回复、引用一张图片提问、以及发来带平台转写文字的语音。
+// 期望:引用文字进 quote_text(标题与原文不同时用“ | ”连接);被引用的图片作为附件附上,
+// quote_text 标出“[图片]”;语音成为 Voice 附件,转写文字放在 transcript(由核心拼进正文)。
+TEST(WeixinProtocol, QuotesAndVoiceTranscript) {
+    auto quoted = text_message(u8"同意");
+    quoted["item_list"][0]["ref_msg"] = {{"title", u8"摘要"},
+                                         {"message_item", {{"type", 1}, {"text_item", {{"text", u8"原话"}}}}}};
+    auto parsed = parse_message(quoted, kBot);
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_EQ(parsed.inbound->quote_text, u8"摘要 | 原话");
+    EXPECT_TRUE(parsed.inbound->attachments.empty());
+
+    auto quoted_image = text_message(u8"这张图是什么");
+    quoted_image["item_list"][0]["ref_msg"] = {
+        {"message_item", {{"type", 2}, {"image_item", {{"aeskey", "00112233445566778899aabbccddeeff"},
+                                                       {"media", {{"encrypt_query_param", "Q1"}}}}}}}};
+    parsed = parse_message(quoted_image, kBot);
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_EQ(parsed.inbound->quote_text, u8"[图片]");
+    ASSERT_EQ(parsed.inbound->attachments.size(), 1u);
+    EXPECT_EQ(parsed.inbound->attachments[0].kind, AttachmentKind::Image);
+
+    auto voice = text_message("");
+    voice["item_list"] = nlohmann::json::array(
+        {{{"type", 3}, {"voice_item", {{"text", u8"明天开会"}, {"encode_type", 6},
+                                       {"media", {{"encrypt_query_param", "V1"}, {"aes_key", "ABEiM0RVZneImaq7zN3u/w=="}}}}}}});
+    parsed = parse_message(voice, kBot);
+    ASSERT_TRUE(parsed.inbound);
+    EXPECT_TRUE(parsed.inbound->text.empty());
+    ASSERT_EQ(parsed.inbound->attachments.size(), 1u);
+    EXPECT_EQ(parsed.inbound->attachments[0].kind, AttachmentKind::Voice);
+    EXPECT_EQ(parsed.inbound->attachments[0].transcript, u8"明天开会");
+}
+
+// 场景:收到图片(image_item.aeskey 十六进制密钥)、文件(media.aes_key 是“十六进制文本的 base64”)、
+// 视频(media.aes_key 是原始 16 字节的 base64)以及密钥格式坏掉的文件。
+// 期望:附件类型、文件名、MIME、大小(file_item.len 是十进制字符串)正确;remote_ref 能还原出
+// 下载参数与同一把 16 字节密钥;坏密钥被标记,下载时会明确报错而不是把密文当明文保存。
+TEST(WeixinProtocol, MediaAttachmentsCarryDownloadRef) {
+    auto message = text_message("");
+    message["item_list"] = nlohmann::json::array({
+        {{"type", 2}, {"image_item", {{"aeskey", "00112233445566778899aabbccddeeff"},
+                                      {"media", {{"encrypt_query_param", "IMG"}}}}}},
+        {{"type", 4}, {"file_item", {{"file_name", u8"报告.pdf"}, {"len", "12345"},
+                                     {"media", {{"encrypt_query_param", "FILE"},
+                                                {"aes_key", "MDAxMTIyMzM0NDU1NjY3Nzg4OTlhYWJiY2NkZGVlZmY="}}}}}},
+        {{"type", 5}, {"video_item", {{"media", {{"full_url", "https://novac2c.cdn.weixin.qq.com/c2c/download?x=1"},
+                                                 {"aes_key", "ABEiM0RVZneImaq7zN3u/w=="}}}}}},
+        {{"type", 4}, {"file_item", {{"file_name", "bad.bin"},
+                                     {"media", {{"encrypt_query_param", "BAD"}, {"aes_key", "AAAA"}}}}}},
+    });
+    const auto parsed = parse_message(message, kBot);
+    ASSERT_TRUE(parsed.inbound);
+    const auto& files = parsed.inbound->attachments;
+    ASSERT_EQ(files.size(), 4u);
+    const auto expected_key = *hex_decode("00112233445566778899aabbccddeeff");
+
+    EXPECT_EQ(files[0].kind, AttachmentKind::Image);
+    auto ref = decode_media_ref(files[0].remote_ref);
+    ASSERT_TRUE(ref);
+    EXPECT_EQ(ref->query_param, "IMG");
+    EXPECT_EQ(ref->aes_key, expected_key);
+    EXPECT_EQ(ref->kind, "image");
+
+    EXPECT_EQ(files[1].kind, AttachmentKind::File);
+    EXPECT_EQ(files[1].name, u8"报告.pdf");
+    EXPECT_EQ(files[1].mime_type, "application/pdf");
+    EXPECT_EQ(files[1].size, 12345u);
+    ref = decode_media_ref(files[1].remote_ref);
+    ASSERT_TRUE(ref);
+    EXPECT_EQ(ref->aes_key, expected_key);
+
+    EXPECT_EQ(files[2].kind, AttachmentKind::Video);
+    ref = decode_media_ref(files[2].remote_ref);
+    ASSERT_TRUE(ref);
+    EXPECT_TRUE(ref->query_param.empty());
+    EXPECT_EQ(ref->full_url, "https://novac2c.cdn.weixin.qq.com/c2c/download?x=1");
+    EXPECT_EQ(ref->aes_key, expected_key);
+
+    ref = decode_media_ref(files[3].remote_ref);
+    ASSERT_TRUE(ref);
+    EXPECT_TRUE(ref->key_invalid);
+}
+
+// 场景:平台下发的媒体密钥有两种编码,出站时还要按平台要求编码密钥。
+// 期望:base64(16 字节)与 base64(32 位十六进制文本)都还原成同一把密钥,其它长度拒绝;
+// 出站 aes_key = base64(小写十六进制文本)(文档示例 00..0f → MDAwMTAy…MGY=),
+// 用 base64(原始字节) 会让对方看到灰色方块。
+TEST(WeixinProtocol, AesKeyFormats) {
+    const auto expected = *hex_decode("00112233445566778899aabbccddeeff");
+    EXPECT_EQ(parse_aes_key("ABEiM0RVZneImaq7zN3u/w=="), expected);
+    EXPECT_EQ(parse_aes_key("MDAxMTIyMzM0NDU1NjY3Nzg4OTlhYWJiY2NkZGVlZmY="), expected);
+    EXPECT_FALSE(parse_aes_key("AAAA").has_value());
+    EXPECT_FALSE(parse_aes_key("!!").has_value());
+    EXPECT_EQ(outbound_aes_key(bytes_0_to_15()), "MDAwMTAyMDMwNDA1MDYwNzA4MDkwYTBiMGMwZDBlMGY=");
+}
+
+// 场景:解密 CDN 下载的媒体;平台偶尔给出填充不规范的密文。
+// 期望:FIPS-197 的 AES-128 标准向量能解出原文(末字节 0xff 不是合法填充,宽松规则下原样保留);
+// 正常加密的内容往返一致;长度不是 16 的倍数的密文报错;宽松去填充只去合法的填充。
+TEST(WeixinProtocol, DecryptsMediaWithLenientPadding) {
+    const auto key = bytes_0_to_15();
+    const auto ciphertext = *hex_decode("69c4e0d86a7b0430d8cdb78070b4c55a");
+    std::string plaintext, error;
+    ASSERT_TRUE(decrypt_media(key, ciphertext, plaintext, &error)) << error;
+    EXPECT_EQ(plaintext, *hex_decode("00112233445566778899aabbccddeeff"));
+
+    std::string encrypted;
+    ASSERT_TRUE(platform::aes_128_ecb_encrypt(key, u8"微信图片内容", encrypted, nullptr));
+    ASSERT_TRUE(decrypt_media(key, encrypted, plaintext, &error)) << error;
+    EXPECT_EQ(plaintext, u8"微信图片内容");
+
+    EXPECT_FALSE(decrypt_media(key, std::string(15, 'x'), plaintext, &error));
+    EXPECT_FALSE(error.empty());
+
+    EXPECT_EQ(strip_pkcs7_lenient(std::string("abc") + std::string(3, '\x03')), "abc");
+    EXPECT_EQ(strip_pkcs7_lenient(std::string("abc\x02\x03")), std::string("abc\x02\x03"));
+    EXPECT_EQ(strip_pkcs7_lenient(std::string("abc\x00", 4)), std::string("abc\x00", 4));
+}
+
+// 场景:回传文件时按 MIME 选择上传类型,并构造 sendmessage 请求体。
+// 期望:图片(SVG 除外)→ 1,视频 → 2,音频与其它 → 3(文件);文字消息 from_user_id 为空、
+// message_type 2、message_state 2,没有 context_token 时不带该字段;文件条目的 len 是十进制字符串。
+TEST(WeixinProtocol, UploadTypesAndMessageBodies) {
+    EXPECT_EQ(upload_media_type("image/png", "a.png"), UploadMediaType::Image);
+    EXPECT_EQ(upload_media_type("", "photo.JPG"), UploadMediaType::Image);
+    EXPECT_EQ(upload_media_type("image/svg+xml", "a.svg"), UploadMediaType::File);
+    EXPECT_EQ(upload_media_type("video/mp4", "a.mp4"), UploadMediaType::Video);
+    EXPECT_EQ(upload_media_type("audio/silk", "v.silk"), UploadMediaType::File);
+    EXPECT_EQ(upload_media_type("application/octet-stream", "r.pdf"), UploadMediaType::File);
+
+    const auto body = build_send_body(kUser, "cid-1", text_item(u8"回复"), "");
+    const auto& msg = body["msg"];
+    EXPECT_EQ(msg.value("from_user_id", "?"), "");
+    EXPECT_EQ(msg.value("to_user_id", ""), kUser);
+    EXPECT_EQ(msg.value("client_id", ""), "cid-1");
+    EXPECT_EQ(msg.value("message_type", 0), 2);
+    EXPECT_EQ(msg.value("message_state", 0), 2);
+    EXPECT_FALSE(msg.contains("context_token"));
+    EXPECT_EQ(msg["item_list"][0]["text_item"].value("text", ""), u8"回复");
+    EXPECT_EQ(build_send_body(kUser, "c", text_item("x"), "tok")["msg"].value("context_token", ""), "tok");
+
+    const auto file = media_item(UploadMediaType::File, "ENC", bytes_0_to_15(), 32, 20, "md5", "a.txt");
+    EXPECT_EQ(file.value("type", 0), 4);
+    EXPECT_EQ(file["file_item"].value("len", ""), "20");
+    EXPECT_EQ(file["file_item"]["media"].value("aes_key", ""), "MDAwMTAyMDMwNDA1MDYwNzA4MDkwYTBiMGMwZDBlMGY=");
+    EXPECT_EQ(file["file_item"]["media"].value("encrypt_type", 0), 1);
+    const auto image = media_item(UploadMediaType::Image, "ENC", bytes_0_to_15(), 48, 40, "md5", "a.png");
+    EXPECT_EQ(image.value("type", 0), 2);
+    EXPECT_EQ(image["image_item"].value("mid_size", 0), 48);
+}
+
+// 场景:拼 CDN 上传 / 下载地址;入站媒体只给了 full_url。
+// 期望:参数全部百分号编码;full_url 只接受微信自家域名或配置的 CDN 地址,
+// 拒绝其它主机、带用户名的地址与非 http(s) 协议(防止被诱导请求内网)。
+TEST(WeixinProtocol, CdnUrlsAndHostAllowlist) {
+    EXPECT_EQ(cdn_download_url("https://novac2c.cdn.weixin.qq.com/c2c", "a+b/c"),
+              "https://novac2c.cdn.weixin.qq.com/c2c/download?encrypted_query_param=a%2Bb%2Fc");
+    EXPECT_EQ(cdn_upload_url("https://novac2c.cdn.weixin.qq.com/c2c/", "p=1", "ab"),
+              "https://novac2c.cdn.weixin.qq.com/c2c/upload?encrypted_query_param=p%3D1&filekey=ab");
+    const std::string cdn = kCdnBase;
+    EXPECT_TRUE(media_host_allowed("https://novac2c.cdn.weixin.qq.com/c2c/download?x=1", cdn));
+    EXPECT_TRUE(media_host_allowed("https://MMBIZ.QPIC.CN/a.jpg", cdn));
+    EXPECT_FALSE(media_host_allowed("https://evil.example/a.jpg", cdn));
+    EXPECT_FALSE(media_host_allowed("https://evil@novac2c.cdn.weixin.qq.com/a", cdn));
+    EXPECT_FALSE(media_host_allowed("file:///etc/passwd", cdn));
+    EXPECT_FALSE(media_host_allowed("http://127.0.0.1:8080/c2c/x", cdn));
+    EXPECT_TRUE(media_host_allowed("http://127.0.0.1:8080/c2c/x", "http://127.0.0.1:8080/c2c"));
+    EXPECT_FALSE(media_host_allowed("http://127.0.0.1:9090/c2c/x", "http://127.0.0.1:8080/c2c"));
+}
+
+// 场景:用户粘贴一段约 2500 字的长文,平台把它拆成 1900 字 + 600 字两条依次投递。
+// 期望:第一段(达到 1800 字阈值)先暂存不交付;第二段到来时合并成一条交付,沿用第一段的消息 id;
+// 普通短消息不等待;长片段等不到后续时到期原样交付;暂存期间来了媒体消息则先交付暂存内容再交付媒体。
+TEST(WeixinProtocol, FragmentMergerJoinsSplitMessages) {
+    using Clock = FragmentMerger::Clock;
+    MergeLimits limits;
+    limits.split_threshold = 1800;
+    limits.wait = std::chrono::milliseconds(5000);
+    FragmentMerger merger(limits);
+    const auto t0 = Clock::now();
+    const std::string first(1900, 'a');
+
+    EXPECT_TRUE(merger.push(make_inbound(kUser, first, "m1"), t0).empty());
+    auto ready = merger.push(make_inbound(kUser, "tail", "m2"), t0 + std::chrono::milliseconds(300));
+    ASSERT_EQ(ready.size(), 1u);
+    EXPECT_EQ(ready[0].text, first + "\ntail");
+    EXPECT_EQ(ready[0].message_id, "m1");
+    EXPECT_TRUE(merger.empty());
+
+    ready = merger.push(make_inbound(kUser, "short", "m3"), t0);
+    ASSERT_EQ(ready.size(), 1u);
+    EXPECT_EQ(ready[0].text, "short");
+
+    EXPECT_TRUE(merger.push(make_inbound(kUser, first, "m4"), t0).empty());
+    EXPECT_TRUE(merger.take_due(t0 + std::chrono::milliseconds(4000)).empty());
+    ready = merger.take_due(t0 + std::chrono::milliseconds(5000));
+    ASSERT_EQ(ready.size(), 1u);
+    EXPECT_EQ(ready[0].message_id, "m4");
+
+    EXPECT_TRUE(merger.push(make_inbound(kUser, first, "m5"), t0).empty());
+    auto media = make_inbound(kUser, "", "m6");
+    media.attachments.push_back(Attachment{AttachmentKind::Image});
+    ready = merger.push(std::move(media), t0);
+    ASSERT_EQ(ready.size(), 2u);
+    EXPECT_EQ(ready[0].message_id, "m5");
+    EXPECT_EQ(ready[1].message_id, "m6");
+}
+
+// 场景:平台重复投递同一 message_id;又换了一个 message_id 重发同一内容(同一发送时间);
+// 用户隔了一会儿又发了一次同样的“继续”(发送时间不同)。
+// 期望:前两种只处理一次;第三种照常处理。没有发送时间时,只在 10 秒窗口内按内容去重。
+TEST(WeixinProtocol, DeduperDropsRepeats) {
+    using Clock = InboundDeduper::Clock;
+    InboundDeduper dedupe(1000, std::chrono::seconds(10));
+    const auto now = Clock::now();
+    EXPECT_FALSE(dedupe.seen_id("1"));
+    EXPECT_TRUE(dedupe.seen_id("1"));
+    EXPECT_FALSE(dedupe.seen_id(""));
+
+    EXPECT_FALSE(dedupe.seen_content(kUser, u8"继续", 1000, now));
+    EXPECT_TRUE(dedupe.seen_content(kUser, u8"继续", 1000, now));
+    EXPECT_FALSE(dedupe.seen_content(kUser, u8"继续", 2000, now));
+
+    EXPECT_FALSE(dedupe.seen_content(kUser, "x", 0, now));
+    EXPECT_TRUE(dedupe.seen_content(kUser, "x", 0, now + std::chrono::seconds(5)));
+    EXPECT_FALSE(dedupe.seen_content(kUser, "x", 0, now + std::chrono::seconds(30)));
+    EXPECT_FALSE(dedupe.seen_content(kUser, "", 0, now));
+    EXPECT_FALSE(dedupe.seen_content(kUser, "", 0, now));
+}
+
+} // namespace
+} // namespace acecode::im::weixin
diff --git a/tests/im/weixin_transport_test.cpp b/tests/im/weixin_transport_test.cpp
new file mode 100644
index 000000000..0b5740239
--- /dev/null
+++ b/tests/im/weixin_transport_test.cpp
@@ -0,0 +1,563 @@
+#include <gtest/gtest.h>
+
+#include "im/text_chunk.hpp"
+#include "im/weixin/weixin_media.hpp"
+#include "im/weixin/weixin_transport.hpp"
+#include "platform/crypto/aes_ecb.hpp"
+#include "platform/crypto/digest.hpp"
+#include "test_support/im/fake_weixin_server.hpp"
+#include "utils/base64.hpp"
+
+#include <algorithm>
+#include <atomic>
+#include <fstream>
+#include <map>
+#include <mutex>
+#include <set>
+#include <thread>
+#include <vector>
+
+// im/weixin/weixin_transport:微信 iLink 传输层端到端测试(本机假 iLink 服务与假 CDN)。
+// 覆盖:协议头与 base_info、长轮询收消息与游标持久化、从持久化游标继续、登录失效停止重试、
+// HTTP 200 错误后重试、去重、长消息合并、context_token 的使用与失效重发、限频重发、
+// 正在输入、文件上传与下载解密、及时停机、长轮询挂起时即显示已连接。
+
+namespace acecode::im::weixin {
+namespace {
+
+constexpr const char* kBot = "e06c1ceea05e@im.bot";
+constexpr const char* kUser = "o9cq800kum_owner@im.wechat";
+
+WeixinTransportOptions local_options(const test::FakeWeixinServer& server) {
+    WeixinTransportOptions options;
+    options.api.token = server.token();
+    options.api.base_url = server.base();
+    options.api.cdn_base = server.cdn_base();
+    options.api.use_proxy = false;
+    options.bot_id = kBot;
+    options.poll_timeout = std::chrono::milliseconds(300);
+    options.poll_margin = std::chrono::seconds(2);
+    options.connect_grace = std::chrono::milliseconds(200);
+    options.backoff = {std::chrono::milliseconds(50)};
+    options.chunk_delay = std::chrono::milliseconds(10);
+    options.send_retry_delay = std::chrono::milliseconds(20);
+    options.rate_limit_delay = std::chrono::milliseconds(50);
+    options.typing_interval = std::chrono::milliseconds(100);
+    options.housekeeping_tick = std::chrono::milliseconds(20);
+    options.merge.wait = std::chrono::milliseconds(1000);
+    return options;
+}
+
+struct Recorder {
+    std::mutex mu;
+    std::vector<Inbound> inbound;
+    std::vector<LinkState> states;
+    TransportCallbacks callbacks() {
+        TransportCallbacks cb;
+        cb.on_inbound = [this](Inbound in) {
+            std::lock_guard<std::mutex> lock(mu);
+            inbound.push_back(std::move(in));
+        };
+        cb.on_status = [this](const TransportStatus& status) {
+            std::lock_guard<std::mutex> lock(mu);
+            states.push_back(status.state);
+        };
+        return cb;
+    }
+    std::size_t count() {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.size();
+    }
+    Inbound at(std::size_t i) {
+        std::lock_guard<std::mutex> lock(mu);
+        return inbound.at(i);
+    }
+    bool saw(LinkState state) {
+        std::lock_guard<std::mutex> lock(mu);
+        return std::find(states.begin(), states.end(), state) != states.end();
+    }
+};
+
+Address user_address() {
+    Address to;
+    to.platform = "weixin";
+    to.account = kBot;
+    to.chat = to.sender = kUser;
+    return to;
+}
+
+bool wait_state(WeixinTransport& transport, LinkState state) {
+    return test::FakeWeixinServer::wait_until([&] { return transport.status().state == state; });
+}
+
+std::filesystem::path temp_dir(const char* name) {
+    const auto dir = std::filesystem::path(testing::TempDir()) / name;
+    std::filesystem::remove_all(dir);
+    std::filesystem::create_directories(dir);
+    return dir;
+}
+
+std::string read_file(const std::filesystem::path& path) {
+    std::ifstream in(path, std::ios::binary);
+    return std::string((std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>());
+}
+
+// 场景:开启微信通道后,用户私聊发来一条消息(message_id 是超过 2^53 的 uint64)。
+// 期望:状态变为已连接,账号为机器人 id;收到入站消息且 id 不丢精度;新游标与该用户的
+// context_token 都通过回调交给调用方持久化;getupdates 请求带齐协议头(Bearer token、
+// AuthorizationType、iLink-App-Id、ClientVersion 131584、每次随机的 X-WECHAT-UIN = base64(数字))
+// 与 base_info.channel_version = 2.2.0。
+TEST(WeixinTransport, ConnectsReceivesAndPersistsCursor) {
+    test::FakeWeixinServer server;
+    auto options = local_options(server);
+    std::mutex mu;
+    std::string persisted;
+    std::map<std::string, std::string> tokens;
+    options.on_cursor = [&](const std::string& cursor) {
+        std::lock_guard<std::mutex> lock(mu);
+        persisted = cursor;
+    };
+    options.on_context_token = [&](const std::string& peer, const std::string& token) {
+        std::lock_guard<std::mutex> lock(mu);
+        tokens[peer] = token;
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    EXPECT_EQ(transport.status().account, kBot);
+
+    server.push_text(kUser, u8"你好", 7351234567890123456ULL, "ctx-A");
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return recorder.count() == 1; }));
+    const auto inbound = recorder.at(0);
+    EXPECT_EQ(inbound.text, u8"你好");
+    EXPECT_EQ(inbound.message_id, "7351234567890123456");
+    EXPECT_EQ(inbound.address.platform, "weixin");
+    EXPECT_EQ(inbound.address.account, kBot);
+    EXPECT_EQ(inbound.address.chat, kUser);
+    EXPECT_TRUE(inbound.mentioned);
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] {
+        std::lock_guard<std::mutex> lock(mu);
+        return persisted == "cur-1" && tokens[kUser] == "ctx-A";
+    }));
+    EXPECT_EQ(transport.cursor(), "cur-1");
+
+    const auto polls = server.calls_to("getupdates");
+    ASSERT_FALSE(polls.empty());
+    const auto& headers = polls[0].headers;
+    EXPECT_EQ(headers.at("Authorization"), "Bearer " + server.token());
+    EXPECT_EQ(headers.at("AuthorizationType"), "ilink_bot_token");
+    EXPECT_EQ(headers.at("iLink-App-Id"), "bot");
+    EXPECT_EQ(headers.at("iLink-App-ClientVersion"), "131584");
+    const auto uin = base64_decode(headers.at("X-WECHAT-UIN"));
+    ASSERT_TRUE(uin.has_value());
+    EXPECT_FALSE(uin->empty());
+    EXPECT_EQ(uin->find_first_not_of("0123456789"), std::string::npos);
+    EXPECT_EQ(polls[0].body["base_info"].value("channel_version", ""), "2.2.0");
+    EXPECT_TRUE(polls[0].body.contains("get_updates_buf"));
+    transport.stop();
+}
+
+// 场景:重启时把持久化的游标交给传输层,服务端还留着之前处理过的消息。
+// 期望:第一次 getupdates 就带上该游标,旧消息不会再交给上层。
+TEST(WeixinTransport, ResumesFromPersistedCursor) {
+    test::FakeWeixinServer server;
+    server.push_text(kUser, "old", 1);  // seq 1
+    server.push_text(kUser, "new", 2);  // seq 2
+    auto options = local_options(server);
+    options.initial_cursor = "cur-1";
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return recorder.count() == 1; }));
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    EXPECT_EQ(recorder.count(), 1u);
+    EXPECT_EQ(recorder.at(0).text, "new");
+    EXPECT_EQ(server.calls_to("getupdates").at(0).body.value("get_updates_buf", ""), "cur-1");
+}
+
+// 场景:bot_token 已失效,平台对 getupdates 返回 HTTP 200 + {"errcode":-14,"errmsg":"session timeout"}。
+// 期望:状态 Failed 且停止重试,原因提示到设置页重新扫码,不含 token;之后不再继续轮询。
+TEST(WeixinTransport, SessionExpiredStopsRetrying) {
+    test::FakeWeixinServer server;
+    auto options = local_options(server);
+    options.api.token = "stale-token-ZYXWVUTSRQPONMLK";
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Failed));
+    const auto status = transport.status();
+    EXPECT_TRUE(status.retry_stopped);
+    EXPECT_EQ(status.detail, kSessionExpiredText);
+    EXPECT_EQ(status.detail.find("stale-token"), std::string::npos);
+    const auto polls = server.calls_to("getupdates").size();
+    std::this_thread::sleep_for(std::chrono::milliseconds(300));
+    EXPECT_EQ(server.calls_to("getupdates").size(), polls);
+    EXPECT_FALSE(recorder.saw(LinkState::Connected));
+}
+
+// 场景:平台第一次 getupdates 返回 HTTP 200 + {"ret":-1,"errmsg":"system busy"}(临时错误)。
+// 期望:进入重试状态并按退避重试,随后恢复为已连接并正常收到消息。
+TEST(WeixinTransport, RetriesAfterHttp200Error) {
+    test::FakeWeixinServer server;
+    std::atomic<int> polls{0};
+    server.override = [&](const test::FakeWeixinServer::Call& call) -> nlohmann::json {
+        if (call.endpoint == "getupdates" && ++polls == 1) return {{"ret", -1}, {"errmsg", "system busy"}};
+        return nullptr;
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return recorder.saw(LinkState::Retrying); }));
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    server.push_text(kUser, "hello", 10);
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return recorder.count() == 1; }));
+}
+
+// 场景:平台重复投递同一 message_id;又换了个 message_id 重发同一内容(发送时间相同,hermes #16182);
+// 之后用户发来一条新消息。
+// 期望:重复的两条都被忽略,只交付第一条与新消息。
+TEST(WeixinTransport, DedupesRepeatedMessages) {
+    test::FakeWeixinServer server;
+    auto first = test::FakeWeixinServer::text_message(kUser, u8"执行一下", 100);
+    first["create_time_ms"] = 5555;
+    auto resent = first;
+    resent["message_id"] = 101;
+    server.push_message(first);
+    server.push_message(first);
+    server.push_message(resent);
+    server.push_text(kUser, u8"新消息", 102);
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return recorder.count() == 2; }));
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+    ASSERT_EQ(recorder.count(), 2u);
+    EXPECT_EQ(recorder.at(0).message_id, "100");
+    EXPECT_EQ(recorder.at(1).text, u8"新消息");
+}
+
+// 场景:用户粘贴一段长文,平台按约 2048 字拆成 1900 字 + “尾巴”两条投递;另一段 1900 字的长文没有后续。
+// 期望:前者合并为一条交付(换行连接,消息 id 沿用第一段);后者等待期满后原样交付。
+TEST(WeixinTransport, MergesSplitLongMessage) {
+    test::FakeWeixinServer server;
+    std::string longer;
+    for (int i = 0; i < 1900; ++i) longer += u8"长";
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(wait_state(transport, LinkState::Connected));
+    server.push_text(kUser, longer, 1);
+    server.push_text(kUser, u8"尾巴", 2);
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return recorder.count() == 1; }));
+    EXPECT_EQ(recorder.at(0).text, longer + u8"\n尾巴");
+    EXPECT_EQ(recorder.at(0).message_id, "1");
+
+    server.push_text(kUser, longer, 3);
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return recorder.count() == 2; }));
+    EXPECT_EQ(recorder.at(1).message_id, "3");
+}
+
+// 场景:用户发来消息后,助手回复一段 Markdown,以及一段 4500 个汉字的长回答。
+// 期望:回复转成纯文本并带上该用户最新的 context_token、from_user_id 为空、message_type 2;
+// 长回答按 2000 字(码点)切成 3 段依次发送,内容拼起来与原文一致,每段 client_id 不同。
+TEST(WeixinTransport, SendsPlainTextWithContextTokenAndChunks) {
+    test::FakeWeixinServer server;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(local_options(server));
+    transport.start(recorder.callbacks());
+    server.push_text(kUser, "hi", 1, "ctx-B");
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return recorder.count() == 1; }));
+    const auto inbound = recorder.at(0);
+    EXPECT_EQ(transport.send_text(inbound.address, u8"**粗体** 文字", inbound.reply_context).outcome,
+              SendOutcome::Sent);
+    auto sends = server.calls_to("sendmessage");
+    ASSERT_EQ(sends.size(), 1u);
+    const auto& msg = sends[0].body["msg"];
+    EXPECT_EQ(msg.value("to_user_id", ""), kUser);
+    EXPECT_EQ(msg.value("from_user_id", "?"), "");
+    EXPECT_EQ(msg.value("context_token", ""), "ctx-B");
+    EXPECT_EQ(msg.value("message_type", 0), 2);
+    EXPECT_EQ(msg["item_list"][0]["text_item"].value("text", ""), u8"粗体 文字");
+    EXPECT_EQ(msg.value("client_id", "").rfind("acecode-weixin-", 0), 0u);
+    EXPECT_EQ(sends[0].body["base_info"].value("channel_version", ""), "2.2.0");
+
+    std::string longer;
+    for (int i = 0; i < 4500; ++i) longer += u8"字";
+    EXPECT_EQ(transport.send_text(user_address(), longer, {}).outcome, SendOutcome::Sent);
+    sends = server.calls_to("sendmessage");
+    ASSERT_EQ(sends.size(), 4u);
+    std::string joined;
+    std::set<std::string> ids;
+    for (std::size_t i = 1; i < sends.size(); ++i) {
+        const auto text = sends[i].body["msg"]["item_list"][0]["text_item"].value("text", "");
+        EXPECT_LE(text_units(text, false), 2000u);
+        joined += text;
+        ids.insert(sends[i].body["msg"].value("client_id", ""));
+    }
+    EXPECT_EQ(joined, longer);
+    EXPECT_EQ(ids.size(), 3u);
+}
+
+// 场景:在 Desktop 里输入回复(没有触发消息),传输层只有上次持久化的 context_token,
+// 而它已经过期,平台对带 token 的发送返回 -14。
+// 期望:去掉 token 用同一个 client_id 重发并成功;过期 token 被删除并通知调用方(token 为空)。
+TEST(WeixinTransport, RetriesWithoutStaleContextToken) {
+    test::FakeWeixinServer server;
+    server.override = [](const test::FakeWeixinServer::Call& call) -> nlohmann::json {
+        if (call.endpoint == "sendmessage" && call.body["msg"].contains("context_token"))
+            return {{"errcode", -14}, {"errmsg", "session timeout"}};
+        return nullptr;
+    };
+    auto options = local_options(server);
+    options.initial_context_tokens = {{kUser, "ctx-old"}};
+    std::mutex mu;
+    std::vector<std::pair<std::string, std::string>> updates;
+    options.on_context_token = [&](const std::string& peer, const std::string& token) {
+        std::lock_guard<std::mutex> lock(mu);
+        updates.emplace_back(peer, token);
+    };
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(options);
+    transport.start(recorder.callbacks());
+    EXPECT_EQ(transport.send_text(user_address(), "hello", nlohmann::json::object()).outcome, SendOutcome::Sent);
+    const auto sends = server.calls_to("sendmessage");
+    ASSERT_EQ(sends.size(), 2u);
+    EXPECT_EQ(sends[0].body["msg"].value("context_token", ""), "ctx-old");
+    EXPECT_FALSE(sends[1].body["msg"].contains("context_token"));
+    EXPECT_EQ(sends[0].body["msg"].value("client_id", ""), sends[1].body["msg"].value("client_id", ""));
+    EXPECT_EQ(transport.context_tokens().count(kUser), 0u);
+    std::lock_guard<std::mutex> lock(mu);
+    ASSERT_EQ(updates.size(), 1u);
+    EXPECT_EQ(updates[0], std::make_pair(std::string(kUser), std::string{}));
+}
+
+// 场景:平台对一次发送返回 -2 "freq limit"(限频);另一次返回参数错误。
+// 期望:限频时等待后用同一个 client_id 重发并成功,不丢消息;参数错误直接失败、不重发。
+TEST(WeixinTransport, RateLimitWaitsAndResends) {
+    test::FakeWeixinServer server;
+    std::atomic<int> sends{0};
+    std::atomic<bool> reject{false};
+    server.override = [&](const test::FakeWeixinServer::Call& call) -> nlohmann::json {
+        if (call.endpoint != "sendmessage") return nullptr;
+        if (reject) return {{"ret", -1}, {"errmsg", "param error"}};
+        if (++sends == 1) return {{"ret", -2}, {"errmsg", "freq limit"}};
+        return nullptr;
+    };
+    auto options = local_options(server);
+    options.rate_limit_delay = std::chrono::milliseconds(200);
+    WeixinTransport transport(options);
+    const auto start = std::chrono::steady_clock::now();
+    EXPECT_EQ(transport.send_text(user_address(), "hello", {}).outcome, SendOutcome::Sent);
+    EXPECT_GE(std::chrono::steady_clock::now() - start, std::chrono::milliseconds(180));
+    auto calls = server.calls_to("sendmessage");
+    ASSERT_EQ(calls.size(), 2u);
+    EXPECT_EQ(calls[0].body["msg"].value("client_id", ""), calls[1].body["msg"].value("client_id", ""));
+
+    reject = true;
+    const auto failed = transport.send_text(user_address(), "again", {});
+    EXPECT_EQ(failed.outcome, SendOutcome::Failed);
+    EXPECT_NE(failed.error.find(u8"错误码 -1"), std::string::npos) << failed.error;
+    EXPECT_EQ(server.calls_to("sendmessage").size(), 3u);
+}
+
+// 场景:会话开始忙碌时打开“正在输入”,结束时关闭。
+// 期望:先用 getconfig 取 typing_ticket(带上该用户的 context_token),忙碌期间反复发送 status 1;
+// 关闭时发送 status 2(否则对方一直显示“正在输入”),之后不再发送 status 1。
+TEST(WeixinTransport, TypingUsesTicketAndAlwaysCancels) {
+    test::FakeWeixinServer server;
+    auto options = local_options(server);
+    options.initial_context_tokens = {{kUser, "ctx-T"}};
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(options);
+    transport.start(recorder.callbacks());
+    const auto typing_with = [&](int status) {
+        std::size_t n = 0;
+        for (const auto& call : server.calls_to("sendtyping"))
+            if (call.body.value("status", 0) == status) ++n;
+        return n;
+    };
+    transport.set_typing(user_address(), true);
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return typing_with(1) >= 2; }));
+    const auto config = server.calls_to("getconfig");
+    ASSERT_EQ(config.size(), 1u);
+    EXPECT_EQ(config[0].body.value("ilink_user_id", ""), kUser);
+    EXPECT_EQ(config[0].body.value("context_token", ""), "ctx-T");
+    EXPECT_EQ(server.calls_to("sendtyping").at(0).body.value("typing_ticket", ""), "ticket-1");
+
+    transport.set_typing(user_address(), false);
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return typing_with(2) == 1; }));
+    const auto after = typing_with(1);
+    std::this_thread::sleep_for(std::chrono::milliseconds(300));
+    EXPECT_EQ(typing_with(1), after);
+    EXPECT_EQ(transport.capabilities().supports_typing, true);
+}
+
+// 场景:回传一份中文文件名的 PDF 与一张 PNG 图片。
+// 期望:getuploadurl 带上类型(文件 3 / 图片 1)、明文大小与 MD5、填充后大小、十六进制密钥与 filekey;
+// 密文 POST 到 CDN(地址由 upload_param 与 filekey 拼成),用该密钥能解回原文;
+// sendmessage 的条目用 CDN 响应头 x-encrypted-param,aes_key = base64(十六进制密钥),
+// 文件条目保留中文文件名、len 为十进制字符串,图片条目 mid_size = 密文大小。
+TEST(WeixinTransport, UploadsFilesThroughCdn) {
+    test::FakeWeixinServer server;
+    WeixinTransport transport(local_options(server));
+    const auto dir = temp_dir("acecode-weixin-upload");
+    const std::string pdf = u8"PDF-内容-0123456789";
+    { std::ofstream(dir / "r.pdf", std::ios::binary) << pdf; }
+    { std::ofstream(dir / "p.png", std::ios::binary) << std::string(40, 'P'); }
+
+    ASSERT_EQ(transport.send_file(user_address(), dir / "r.pdf", u8"报告.pdf", "application/pdf", {}).outcome,
+              SendOutcome::Sent);
+    const auto request = server.calls_to("getuploadurl").at(0).body;
+    EXPECT_EQ(request.value("media_type", 0), 3);
+    EXPECT_EQ(request.value("to_user_id", ""), kUser);
+    EXPECT_EQ(request.value("rawsize", 0u), pdf.size());
+    EXPECT_EQ(request.value("rawfilemd5", ""), platform::to_hex(platform::md5_digest(pdf)));
+    EXPECT_EQ(request.value("filesize", 0u), platform::aes_128_ecb_padded_size(pdf.size()));
+    EXPECT_TRUE(request.value("no_need_thumb", false));
+    const auto key_hex = request.value("aeskey", "");
+    ASSERT_EQ(key_hex.size(), 32u);
+    EXPECT_EQ(request.value("filekey", "").size(), 32u);
+
+    const auto upload = server.calls_to("cdn_upload").at(0);
+    EXPECT_EQ(upload.method, "POST");
+    EXPECT_EQ(upload.query.at("encrypted_query_param"), "up-1");
+    EXPECT_EQ(upload.query.at("filekey"), request.value("filekey", ""));
+    std::string plaintext, error;
+    ASSERT_TRUE(decrypt_media(*hex_decode(key_hex), upload.raw, plaintext, &error)) << error;
+    EXPECT_EQ(plaintext, pdf);
+
+    const auto item = server.calls_to("sendmessage").at(0).body["msg"]["item_list"][0];
+    EXPECT_EQ(item.value("type", 0), 4);
+    EXPECT_EQ(item["file_item"].value("file_name", ""), u8"报告.pdf");
+    EXPECT_EQ(item["file_item"].value("len", ""), std::to_string(pdf.size()));
+    EXPECT_EQ(item["file_item"]["media"].value("encrypt_query_param", ""), "enc-1");
+    EXPECT_EQ(item["file_item"]["media"].value("aes_key", ""), base64_encode(key_hex));
+
+    ASSERT_EQ(transport.send_file(user_address(), dir / "p.png", "p.png", "image/png", {}).outcome, SendOutcome::Sent);
+    EXPECT_EQ(server.calls_to("getuploadurl").at(1).body.value("media_type", 0), 1);
+    const auto image = server.calls_to("sendmessage").at(1).body["msg"]["item_list"][0];
+    EXPECT_EQ(image.value("type", 0), 2);
+    EXPECT_EQ(image["image_item"].value("mid_size", 0u), platform::aes_128_ecb_padded_size(40));
+    std::filesystem::remove_all(dir);
+}
+
+// 场景:CDN 上传先返回一次 500(临时故障);另一次返回 400(请求被拒);以及文件超过上传上限。
+// 期望:500 后重新上传并成功;400 不重试直接失败;超限文件在上传前就被拒绝,原因提示上限。
+TEST(WeixinTransport, CdnUploadRetriesOnlyTransientFailures) {
+    test::FakeWeixinServer server;
+    auto options = local_options(server);
+    options.max_upload_bytes = 1024;
+    WeixinTransport transport(options);
+    const auto dir = temp_dir("acecode-weixin-upload-retry");
+    { std::ofstream(dir / "a.txt", std::ios::binary) << "hello"; }
+    { std::ofstream(dir / "big.bin", std::ios::binary) << std::string(2048, 'b'); }
+
+    server.cdn_upload_failures = {500};
+    EXPECT_EQ(transport.send_file(user_address(), dir / "a.txt", "a.txt", "text/plain", {}).outcome, SendOutcome::Sent);
+    EXPECT_EQ(server.calls_to("cdn_upload").size(), 2u);
+
+    server.cdn_upload_failures = {400};
+    const auto rejected = transport.send_file(user_address(), dir / "a.txt", "a.txt", "text/plain", {});
+    EXPECT_EQ(rejected.outcome, SendOutcome::Failed);
+    EXPECT_EQ(server.calls_to("cdn_upload").size(), 3u);
+    EXPECT_EQ(server.calls_to("sendmessage").size(), 1u);
+
+    const auto big = transport.send_file(user_address(), dir / "big.bin", "big.bin", "", {});
+    EXPECT_EQ(big.outcome, SendOutcome::Failed);
+    EXPECT_NE(big.error.find(u8"上限"), std::string::npos) << big.error;
+    std::filesystem::remove_all(dir);
+}
+
+// 场景:用户发来一张图片(密钥在 image_item.aeskey,内容在 CDN 上加密);另有一个附件只给了
+// 指向陌生主机的 full_url,一个指向本 CDN 的 full_url,以及一个解密后超过下载上限的文件。
+// 期望:图片下载并解密成原文;陌生主机被拒绝(防 SSRF);本 CDN 的 full_url 可下载;超限文件失败并删除。
+TEST(WeixinTransport, DownloadsAndDecryptsMedia) {
+    test::FakeWeixinServer server;
+    std::string key;
+    for (int i = 0; i < 16; ++i) key.push_back(static_cast<char>(0xA0 + i));
+    const std::string content = u8"微信图片的原始字节 PNG...";
+    std::string encrypted;
+    ASSERT_TRUE(platform::aes_128_ecb_encrypt(key, content, encrypted, nullptr));
+    server.put_blob("Q-IMG", encrypted);
+    std::string big_encrypted;
+    ASSERT_TRUE(platform::aes_128_ecb_encrypt(key, std::string(4096, 'z'), big_encrypted, nullptr));
+    server.put_blob("Q-BIG", big_encrypted);
+
+    auto message = test::FakeWeixinServer::text_message(kUser, "", 50);
+    message["item_list"] = nlohmann::json::array(
+        {{{"type", 2}, {"image_item", {{"aeskey", platform::to_hex(key)}, {"media", {{"encrypt_query_param", "Q-IMG"}}}}}}});
+    server.push_message(message);
+    auto options = local_options(server);
+    options.max_download_bytes = 1024;
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return recorder.count() == 1; }));
+    const auto inbound = recorder.at(0);
+    ASSERT_EQ(inbound.attachments.size(), 1u);
+    EXPECT_EQ(inbound.attachments[0].kind, AttachmentKind::Image);
+
+    const auto dir = temp_dir("acecode-weixin-download");
+    std::string error;
+    ASSERT_TRUE(transport.download(inbound.attachments[0], dir / "img.jpg", &error)) << error;
+    EXPECT_EQ(read_file(dir / "img.jpg"), content);
+
+    Attachment foreign;
+    foreign.kind = AttachmentKind::File;
+    foreign.remote_ref = encode_media_ref(MediaRef{"", "http://evil.example/x", key, false, "file"});
+    EXPECT_FALSE(transport.download(foreign, dir / "evil.bin", &error));
+    EXPECT_NE(error.find(u8"域名"), std::string::npos) << error;
+
+    Attachment direct;
+    direct.kind = AttachmentKind::File;
+    direct.remote_ref = encode_media_ref(
+        MediaRef{"", server.cdn_base() + "/download?encrypted_query_param=Q-IMG", key, false, "file"});
+    ASSERT_TRUE(transport.download(direct, dir / "direct.bin", &error)) << error;
+    EXPECT_EQ(read_file(dir / "direct.bin"), content);
+
+    Attachment big;
+    big.kind = AttachmentKind::File;
+    big.remote_ref = encode_media_ref(MediaRef{"Q-BIG", "", key, false, "file"});
+    EXPECT_FALSE(transport.download(big, dir / "big.bin", &error));
+    EXPECT_NE(error.find(u8"上限"), std::string::npos) << error;
+    EXPECT_FALSE(std::filesystem::exists(dir / "big.bin"));
+    std::filesystem::remove_all(dir);
+}
+
+// 场景:长轮询进行中(服务端挂起请求)时关闭通道。
+// 期望:stop 在 3 秒内返回,不必等长轮询超时;之后状态为已停止。
+TEST(WeixinTransport, StopsPromptlyDuringLongPoll) {
+    test::FakeWeixinServer server;
+    server.max_hold = std::chrono::seconds(5);
+    auto options = local_options(server);
+    options.poll_timeout = std::chrono::seconds(5);
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(options);
+    transport.start(recorder.callbacks());
+    ASSERT_TRUE(test::FakeWeixinServer::wait_until([&] { return !server.calls_to("getupdates").empty(); }));
+    const auto start = std::chrono::steady_clock::now();
+    transport.stop();
+    EXPECT_LT(std::chrono::steady_clock::now() - start, std::chrono::seconds(3));
+    EXPECT_EQ(transport.status().state, LinkState::Stopped);
+}
+
+// 场景:开启通道后一直没有新消息,第一次长轮询要挂满(真实平台约 35 秒)才返回。
+// 期望:长轮询挂起超过 connect_grace 且没有报错(失效 token 会立即得到 -14)时就显示已连接。
+// 回归:Telegram 曾因等第一次长轮询返回才置已连接,设置页打开开关后长时间停在“连接中”。
+TEST(WeixinTransport, ReportsConnectedWhileFirstPollIsHeld) {
+    test::FakeWeixinServer server;
+    server.max_hold = std::chrono::seconds(4);
+    auto options = local_options(server);
+    options.poll_timeout = std::chrono::seconds(4);
+    Recorder recorder;  // 停机仍会回调:记录器必须晚于传输对象析构
+    WeixinTransport transport(options);
+    transport.start(recorder.callbacks());
+    EXPECT_TRUE(test::FakeWeixinServer::wait_until(
+        [&] { return transport.status().state == LinkState::Connected; }, std::chrono::milliseconds(1500)));
+    EXPECT_EQ(server.calls_to("getupdates").size(), 1u);
+    transport.stop();
+}
+
+} // namespace
+} // namespace acecode::im::weixin
diff --git a/tests/network/websocket_client_test.cpp b/tests/network/websocket_client_test.cpp
new file mode 100644
index 000000000..ba9ea9f4a
--- /dev/null
+++ b/tests/network/websocket_client_test.cpp
@@ -0,0 +1,199 @@
+#include <gtest/gtest.h>
+
+#include "network/websocket_client.hpp"
+#include "test_support/network/crow_test_server.hpp"
+
+#include <atomic>
+#include <chrono>
+#include <memory>
+#include <thread>
+
+// network/websocket_client 的本机端到端测试:用 Crow 起一个 WebSocket 服务,
+// 覆盖收发、对端关闭、超大消息、超时、中止等 QQ 网关会遇到的情形。
+// 测试一律关闭代理(use_proxy=false),避免本机系统代理影响 127.0.0.1 连接。
+
+namespace acecode::network {
+namespace {
+
+// 回显服务:普通文本原样返回;"close-4008" 让服务端以 4008 关闭;
+// "big:N" 让服务端回一条 N 字节的文本。
+struct EchoApp {
+    crow::SimpleApp app;
+    EchoApp() {
+        CROW_WEBSOCKET_ROUTE(app, "/ws")
+            .onmessage([](crow::websocket::connection& conn, const std::string& data, bool binary) {
+                if (data == "close-4008") {
+                    conn.close("rate limited", 4008);
+                    return;
+                }
+                if (data.rfind("big:", 0) == 0) {
+                    conn.send_text(std::string(std::stoul(data.substr(4)), 'x'));
+                    return;
+                }
+                if (binary) conn.send_binary(data);
+                else conn.send_text(data);
+            });
+    }
+};
+
+WebSocketConnectOptions local_options(const test::CrowTestServer& server) {
+    WebSocketConnectOptions options;
+    options.url = server.ws_base() + "/ws";
+    options.use_proxy = false;
+    options.connect_timeout = std::chrono::seconds(5);
+    return options;
+}
+
+// 场景:连上本机服务后发送一条含中文的文本。
+// 期望:收到逐字节相同的回显,连接保持可用。
+TEST(WebSocketClient, EchoesUtf8TextMessage) {
+    EchoApp echo;
+    test::CrowTestServer server(echo.app);
+    WebSocketClient client;
+    std::string error;
+    ASSERT_TRUE(client.connect(local_options(server), &error)) << error;
+    const std::string payload = u8"你好,WebSocket 🚀";
+    ASSERT_TRUE(client.send_text(payload, std::chrono::seconds(5), &error)) << error;
+    WebSocketMessage message;
+    ASSERT_EQ(client.receive(message, std::chrono::seconds(5), &error), WebSocketRecv::Message) << error;
+    EXPECT_FALSE(message.binary);
+    EXPECT_EQ(message.data, payload);
+    EXPECT_TRUE(client.connected());
+}
+
+// 场景:服务端回一条 200000 字节的消息,远大于单次 curl_ws_recv 的 64KB 缓冲。
+// 期望:客户端把多次读到的片段拼成一条完整消息返回。
+TEST(WebSocketClient, ReassemblesMessageLargerThanReceiveBuffer) {
+    EchoApp echo;
+    test::CrowTestServer server(echo.app);
+    WebSocketClient client;
+    std::string error;
+    ASSERT_TRUE(client.connect(local_options(server), &error)) << error;
+    ASSERT_TRUE(client.send_text("big:200000", std::chrono::seconds(5), &error)) << error;
+    WebSocketMessage message;
+    ASSERT_EQ(client.receive(message, std::chrono::seconds(10), &error), WebSocketRecv::Message) << error;
+    EXPECT_EQ(message.data.size(), 200000u);
+}
+
+// 场景:客户端把单条消息上限设为 2048 字节,服务端却发来 10000 字节。
+// 期望:receive 报错“超出上限”并主动关闭连接,而不是无限占用内存。
+TEST(WebSocketClient, RejectsMessageAboveConfiguredLimit) {
+    EchoApp echo;
+    test::CrowTestServer server(echo.app);
+    WebSocketClient client;
+    auto options = local_options(server);
+    options.max_message_bytes = 2048;
+    std::string error;
+    ASSERT_TRUE(client.connect(options, &error)) << error;
+    ASSERT_TRUE(client.send_text("big:10000", std::chrono::seconds(5), &error)) << error;
+    WebSocketMessage message;
+    EXPECT_EQ(client.receive(message, std::chrono::seconds(5), &error), WebSocketRecv::Error);
+    EXPECT_NE(error.find("exceeds limit"), std::string::npos) << error;
+    EXPECT_FALSE(client.connected());
+}
+
+// 场景:服务端用 4008(QQ 网关的限频关闭码)和原因文本关闭连接。
+// 期望:receive 返回 Closed,并能读到 4008 与原因,供上层决定退避策略。
+TEST(WebSocketClient, ReportsPeerCloseCodeAndReason) {
+    EchoApp echo;
+    test::CrowTestServer server(echo.app);
+    WebSocketClient client;
+    std::string error;
+    ASSERT_TRUE(client.connect(local_options(server), &error)) << error;
+    ASSERT_TRUE(client.send_text("close-4008", std::chrono::seconds(5), &error)) << error;
+    WebSocketMessage message;
+    ASSERT_EQ(client.receive(message, std::chrono::seconds(5), &error), WebSocketRecv::Closed) << error;
+    EXPECT_EQ(client.close_code(), 4008);
+    EXPECT_EQ(client.close_reason(), "rate limited");
+    EXPECT_FALSE(client.connected());
+}
+
+// 场景:连接空闲,receive 只等 200ms。
+// 期望:返回 Timeout 且连接仍然可用,之后照常收发。
+TEST(WebSocketClient, TimeoutKeepsConnectionUsable) {
+    EchoApp echo;
+    test::CrowTestServer server(echo.app);
+    WebSocketClient client;
+    std::string error;
+    ASSERT_TRUE(client.connect(local_options(server), &error)) << error;
+    WebSocketMessage message;
+    EXPECT_EQ(client.receive(message, std::chrono::milliseconds(200), &error), WebSocketRecv::Timeout);
+    EXPECT_TRUE(client.connected());
+    ASSERT_TRUE(client.send_text("after-timeout", std::chrono::seconds(5), &error)) << error;
+    ASSERT_EQ(client.receive(message, std::chrono::seconds(5), &error), WebSocketRecv::Message) << error;
+    EXPECT_EQ(message.data, "after-timeout");
+}
+
+// 场景:receive 以 10 秒超时阻塞时,另一个线程调用 abort()(对应停止通道)。
+// 期望:receive 在 2 秒内返回 Error,不会等满 10 秒。
+TEST(WebSocketClient, AbortWakesBlockedReceive) {
+    EchoApp echo;
+    test::CrowTestServer server(echo.app);
+    WebSocketClient client;
+    std::string error;
+    ASSERT_TRUE(client.connect(local_options(server), &error)) << error;
+    std::thread stopper([&] {
+        std::this_thread::sleep_for(std::chrono::milliseconds(200));
+        client.abort();
+    });
+    const auto start = std::chrono::steady_clock::now();
+    WebSocketMessage message;
+    EXPECT_EQ(client.receive(message, std::chrono::seconds(10), &error), WebSocketRecv::Error);
+    EXPECT_LT(std::chrono::steady_clock::now() - start, std::chrono::seconds(2));
+    stopper.join();
+}
+
+// 场景:连接建立后服务端进程直接停掉(对应网络断开或网关重启)。
+// 期望:receive 不会卡住也不会误报消息,而是报告连接已断开,状态变为未连接。
+TEST(WebSocketClient, ServerShutdownIsReportedAsDisconnect) {
+    auto echo = std::make_unique<EchoApp>();
+    auto server = std::make_unique<test::CrowTestServer>(echo->app);
+    WebSocketClient client;
+    std::string error;
+    ASSERT_TRUE(client.connect(local_options(*server), &error)) << error;
+    server.reset();
+    WebSocketMessage message;
+    const auto result = client.receive(message, std::chrono::seconds(5), &error);
+    EXPECT_TRUE(result == WebSocketRecv::Closed || result == WebSocketRecv::Error);
+    EXPECT_FALSE(client.connected());
+}
+
+// 场景:连接一个没有 WebSocket 路由的路径,以及一个没有服务监听的端口。
+// 期望:connect 返回 false 并给出非空错误,状态为未连接。
+TEST(WebSocketClient, ConnectFailuresAreReported) {
+    EchoApp echo;
+    test::CrowTestServer server(echo.app);
+    WebSocketClient client;
+    std::string error;
+    auto options = local_options(server);
+    options.url = server.ws_base() + "/missing";
+    EXPECT_FALSE(client.connect(options, &error));
+    EXPECT_FALSE(error.empty());
+    EXPECT_FALSE(client.connected());
+    error.clear();
+    options.url = "ws://127.0.0.1:1/ws";
+    options.connect_timeout = std::chrono::seconds(2);
+    EXPECT_FALSE(client.connect(options, &error));
+    EXPECT_FALSE(error.empty());
+}
+
+// 场景:未连接时调用 send_text。
+// 期望:直接返回 false 并说明未连接,不崩溃。
+TEST(WebSocketClient, SendWithoutConnectionFails) {
+    WebSocketClient client;
+    std::string error;
+    EXPECT_FALSE(client.send_text("x", std::chrono::milliseconds(100), &error));
+    EXPECT_NE(error.find("not connected"), std::string::npos) << error;
+}
+
+// 场景:代理选择需要把 ws/wss 地址换成 http/https 地址再查 NO_PROXY。
+// 期望:scheme 按大小写不敏感替换,其余部分原样保留;非 ws 地址不变。
+TEST(WebSocketClient, ProxyLookupUrlMapsWebSocketSchemes) {
+    EXPECT_EQ(websocket_proxy_lookup_url("wss://api.sgroup.qq.com/websocket"),
+              "https://api.sgroup.qq.com/websocket");
+    EXPECT_EQ(websocket_proxy_lookup_url("WS://127.0.0.1:9/x"), "http://127.0.0.1:9/x");
+    EXPECT_EQ(websocket_proxy_lookup_url("https://example.com"), "https://example.com");
+}
+
+} // namespace
+} // namespace acecode::network
diff --git a/tests/platform/aes_gcm_test.cpp b/tests/platform/aes_gcm_test.cpp
new file mode 100644
index 000000000..9e4454dda
--- /dev/null
+++ b/tests/platform/aes_gcm_test.cpp
@@ -0,0 +1,98 @@
+#include <gtest/gtest.h>
+
+#include "platform/crypto/aes_gcm.hpp"
+
+#include <string>
+
+// platform/crypto/aes_gcm:QQ 扫码配置用它解密服务端返回的 AppSecret。
+// 向量取自 GCM 规范(McGrew & Viega)Test Case 13/14/15,并用 Python
+// cryptography 库交叉核对过。
+
+namespace acecode::platform {
+namespace {
+
+std::string hex(const std::string& text) {
+    std::string out;
+    for (std::size_t i = 0; i + 1 < text.size(); i += 2)
+        out.push_back(static_cast<char>(std::stoi(text.substr(i, 2), nullptr, 16)));
+    return out;
+}
+
+// 场景:GCM 规范 Test Case 15(AES-256,64 字节明文,无附加数据)。
+// 期望:解密结果与规范给出的明文逐字节一致。
+TEST(AesGcm, DecryptsSpecificationTestCase15) {
+    const auto key = hex("feffe9928665731c6d6a8f9467308308feffe9928665731c6d6a8f9467308308");
+    const auto iv = hex("cafebabefacedbaddecaf888");
+    const auto ciphertext = hex(
+        "522dc1f099567d07f47f37a32a84427d643a8cdcbfe5c0c97598a2bd2555d1aa"
+        "8cb08e48590dbb3da7b08b1056828838c5f61e6393ba7a0abcc9f662898015ad");
+    const auto tag = hex("b094dac5d93471bdec1a502270e3cc6c");
+    const auto expected = hex(
+        "d9313225f88406e5a55909c5aff5269a86a7a9531534f7da2e4c303d8a318a72"
+        "1c3c0c95956809532fcf0e2449a6b525b16aedf5aa0de657ba637b391aafd255");
+    std::string plaintext, error;
+    ASSERT_TRUE(aes_256_gcm_decrypt(key, iv, ciphertext, tag, plaintext, &error)) << error;
+    EXPECT_EQ(plaintext, expected);
+}
+
+// 场景:Test Case 14(全零密钥与 IV,16 字节全零明文)与 Test Case 13(空明文,只有标签)。
+// 期望:前者解出 16 个零字节;后者解出空串且认证通过。
+TEST(AesGcm, DecryptsZeroKeyVectorsIncludingEmptyPlaintext) {
+    const std::string key(32, '\0');
+    const std::string iv(12, '\0');
+    std::string plaintext, error;
+    ASSERT_TRUE(aes_256_gcm_decrypt(key, iv, hex("cea7403d4d606b6e074ec5d3baf39d18"),
+                                    hex("d0d1c8a799996bf0265b98b5d48ab919"), plaintext, &error))
+        << error;
+    EXPECT_EQ(plaintext, std::string(16, '\0'));
+    ASSERT_TRUE(aes_256_gcm_decrypt(key, iv, "", hex("530f8afbc74536b9a963b4f1c4cb738b"),
+                                    plaintext, &error))
+        << error;
+    EXPECT_TRUE(plaintext.empty());
+}
+
+// 场景:密文被改动一个比特、或标签被改动、或换了一把密钥。
+// 期望:三种情况都认证失败,返回 false 且不输出任何明文。
+TEST(AesGcm, RejectsTamperedCiphertextTagOrWrongKey) {
+    const auto key = hex("feffe9928665731c6d6a8f9467308308feffe9928665731c6d6a8f9467308308");
+    const auto iv = hex("cafebabefacedbaddecaf888");
+    auto ciphertext = hex(
+        "522dc1f099567d07f47f37a32a84427d643a8cdcbfe5c0c97598a2bd2555d1aa"
+        "8cb08e48590dbb3da7b08b1056828838c5f61e6393ba7a0abcc9f662898015ad");
+    auto tag = hex("b094dac5d93471bdec1a502270e3cc6c");
+    std::string plaintext, error;
+
+    auto flipped = ciphertext;
+    flipped[5] = static_cast<char>(flipped[5] ^ 0x01);
+    EXPECT_FALSE(aes_256_gcm_decrypt(key, iv, flipped, tag, plaintext, &error));
+    EXPECT_TRUE(plaintext.empty());
+    EXPECT_NE(error.find("authentication"), std::string::npos) << error;
+
+    auto bad_tag = tag;
+    bad_tag[0] = static_cast<char>(bad_tag[0] ^ 0x80);
+    EXPECT_FALSE(aes_256_gcm_decrypt(key, iv, ciphertext, bad_tag, plaintext, &error));
+    EXPECT_TRUE(plaintext.empty());
+
+    auto wrong_key = key;
+    wrong_key[31] = static_cast<char>(wrong_key[31] ^ 0x01);
+    EXPECT_FALSE(aes_256_gcm_decrypt(wrong_key, iv, ciphertext, tag, plaintext, &error));
+    EXPECT_TRUE(plaintext.empty());
+}
+
+// 场景:调用方传入长度不对的密钥、nonce 或标签(例如 base64 解码出错)。
+// 期望:不调用底层加密库,直接返回 false 并说明哪一项长度不对。
+TEST(AesGcm, ValidatesKeyNonceAndTagLengths) {
+    std::string plaintext, error;
+    EXPECT_FALSE(aes_256_gcm_decrypt(std::string(16, 'k'), std::string(12, 'n'), "x",
+                                     std::string(16, 't'), plaintext, &error));
+    EXPECT_NE(error.find("32 bytes"), std::string::npos) << error;
+    EXPECT_FALSE(aes_256_gcm_decrypt(std::string(32, 'k'), std::string(16, 'n'), "x",
+                                     std::string(16, 't'), plaintext, &error));
+    EXPECT_NE(error.find("12 bytes"), std::string::npos) << error;
+    EXPECT_FALSE(aes_256_gcm_decrypt(std::string(32, 'k'), std::string(12, 'n'), "x",
+                                     std::string(8, 't'), plaintext, &error));
+    EXPECT_NE(error.find("16 bytes"), std::string::npos) << error;
+}
+
+} // namespace
+} // namespace acecode::platform
diff --git a/tests/platform/crypto_digest_test.cpp b/tests/platform/crypto_digest_test.cpp
new file mode 100644
index 000000000..2f9e89bb4
--- /dev/null
+++ b/tests/platform/crypto_digest_test.cpp
@@ -0,0 +1,73 @@
+#include <gtest/gtest.h>
+
+#include "platform/crypto/aes_ecb.hpp"
+#include "platform/crypto/digest.hpp"
+
+#include <string>
+
+// platform/crypto 的 MD5、HMAC-SHA256、AES-128-ECB:用公开标准向量校验(RFC 1321 / RFC 4231 /
+// NIST SP 800-38A),确保 Windows BCrypt 与其它平台 OpenSSL 两条实现给出同样的结果。
+
+namespace acecode::platform {
+namespace {
+
+std::string from_hex(const std::string& hex) {
+    std::string out;
+    for (std::size_t i = 0; i + 1 < hex.size(); i += 2) out.push_back(static_cast<char>(std::stoi(hex.substr(i, 2), nullptr, 16)));
+    return out;
+}
+
+// 场景:对空串与 "abc" 求 MD5(微信媒体上传要求附原文件 MD5)。
+// 期望:与 RFC 1321 附录的标准值一致。
+TEST(CryptoDigest, Md5MatchesRfcVectors) {
+    EXPECT_EQ(to_hex(md5_digest("")), "d41d8cd98f00b204e9800998ecf8427e");
+    EXPECT_EQ(to_hex(md5_digest("abc")), "900150983cd24fb0d6963f7d28e17f72");
+}
+
+// 场景:LINE 回调签名 = base64(HMAC-SHA256(channel secret, 原始请求体))。
+// 期望:RFC 4231 测试用例 2 与用例 6(密钥长于分组,要先摘要)都与标准值一致。
+TEST(CryptoDigest, HmacSha256MatchesRfc4231) {
+    EXPECT_EQ(to_hex(hmac_sha256("Jefe", "what do ya want for nothing?")),
+              "5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843");
+    EXPECT_EQ(to_hex(hmac_sha256(std::string(131, '\xaa'),
+                                 "Test Using Larger Than Block-Size Key - Hash Key First")),
+              "60e431591ee0b67f0d8a26aacbf5b77f8e0bc6213728c5140546040f0ee37f54");
+}
+
+// 场景:微信 CDN 的文件用 AES-128-ECB + PKCS#7 加密。
+// 期望:第一块密文与 NIST SP 800-38A F.1.1 一致;整块明文会多出一整块填充;解密还原原文。
+TEST(CryptoAesEcb, EncryptMatchesNistAndRoundTrips) {
+    const auto key = from_hex("2b7e151628aed2a6abf7158809cf4f3c");
+    const auto plain = from_hex("6bc1bee22e409f96e93d7e117393172a");
+    std::string cipher;
+    ASSERT_TRUE(aes_128_ecb_encrypt(key, plain, cipher, nullptr));
+    ASSERT_EQ(cipher.size(), 32u);
+    EXPECT_EQ(cipher.size(), aes_128_ecb_padded_size(plain.size()));
+    EXPECT_EQ(to_hex(cipher.substr(0, 16)), "3ad77bb40d7a3660a89ecaf32466ef97");
+    std::string back;
+    ASSERT_TRUE(aes_128_ecb_decrypt(key, cipher, back, nullptr));
+    EXPECT_EQ(back, plain);
+
+    std::string short_cipher;
+    ASSERT_TRUE(aes_128_ecb_encrypt(key, "hello", short_cipher, nullptr));
+    EXPECT_EQ(short_cipher.size(), 16u);
+    ASSERT_TRUE(aes_128_ecb_decrypt(key, short_cipher, back, nullptr));
+    EXPECT_EQ(back, "hello");
+}
+
+// 场景:密钥长度不对、密文长度不是 16 的倍数、用错密钥解出非法填充。
+// 期望:都返回 false 且给出原因,不输出明文。
+TEST(CryptoAesEcb, RejectsBadKeyLengthAndPadding) {
+    std::string out;
+    std::string error;
+    EXPECT_FALSE(aes_128_ecb_encrypt("short", "x", out, &error));
+    EXPECT_FALSE(error.empty());
+    EXPECT_FALSE(aes_128_ecb_decrypt(std::string(16, 'k'), "123", out, &error));
+    std::string cipher;
+    ASSERT_TRUE(aes_128_ecb_encrypt(std::string(16, 'k'), "payload", cipher, nullptr));
+    EXPECT_FALSE(aes_128_ecb_decrypt(std::string(16, 'x'), cipher, out, &error));
+    EXPECT_TRUE(out.empty());
+}
+
+} // namespace
+} // namespace acecode::platform
diff --git a/tests/session/session_activity_state_test.cpp b/tests/session/session_activity_state_test.cpp
new file mode 100644
index 000000000..d1810f4b4
--- /dev/null
+++ b/tests/session/session_activity_state_test.cpp
@@ -0,0 +1,151 @@
+// 覆盖 SessionActivityState(桌面像素办公室读取的会话活动快照)的状态折叠规则:
+//  1. 回合完成在事件环被挤掉后仍可读,新回合开始即唤醒;
+//  2. 等待授权 / 等待回答优先于其它活动,全部关闭后回到工具执行;
+//  3. 取消与失败不会被记成成功完成;
+//  4. 不缓冲的进度事件与压缩完成同样进入快照;
+//  5. 网状消息只保留身份、不保留正文,且有条数上限;
+//  6. 流式正文让快照进入「撰写回复」并只保留有限尾巴;
+//  7. 推理与正文各自成段,换阶段时旧尾巴清空;
+//  8. 工具调用带一行调用预览,工具结束后预览清空。
+#include <gtest/gtest.h>
+#include "session/event_dispatcher.hpp"
+#include "session/session_activity_state.hpp"
+
+using namespace acecode;
+using nlohmann::json;
+
+// 场景:事件环容量只有 1,回合完成后又来了 5 个 token 把 Done 挤出环。
+// 期望:快照仍报 outcome=completed / busy=false;下一回合 busy=true 后 outcome 清空。
+TEST(SessionActivityState, CompletionSurvivesReplayEvictionAndNewTurnWakes) {
+    EventDispatcher events(1);
+    events.emit(SessionEventKind::BusyChanged, {{"busy", true}, {"turn_id", "first"}});
+    events.emit(SessionEventKind::Done, {{"outcome", "completed"}});
+    for (int i = 0; i < 5; ++i) events.emit(SessionEventKind::Token, {{"text", "x"}});
+    EXPECT_EQ(events.activity_snapshot()["outcome"], "completed");
+    EXPECT_FALSE(events.activity_snapshot()["busy"].get<bool>());
+    events.emit(SessionEventKind::BusyChanged, {{"busy", true}, {"turn_id", "next"}});
+    EXPECT_EQ(events.activity_snapshot()["outcome"], "");
+    EXPECT_TRUE(events.activity_snapshot()["busy"].get<bool>());
+}
+
+// 场景:工具执行中先后来两个授权请求和一个提问,中间夹一条普通进度。
+// 期望:只要还有未关闭的授权就是 permission_waiting,其次 question_waiting,
+// 都关闭后回到 tool_running;工具结束后 tool 清空,输出正文不进快照。
+TEST(SessionActivityState, PendingInteractionsOutrankOtherActivityUntilAllClose) {
+    EventDispatcher events;
+    events.emit(SessionEventKind::BusyChanged, {{"busy", true}});
+    events.emit(SessionEventKind::ToolStart, {{"tool", "bash"}, {"tool_call_id", "t"}});
+    events.emit(SessionEventKind::PermissionRequest, {{"request_id", "one"}});
+    events.emit(SessionEventKind::PermissionRequest, {{"request_id", "two"}});
+    events.emit(SessionEventKind::AgentProgress, {{"phase", "thinking"}, {"label", "Thinking"}});
+    events.emit(SessionEventKind::PermissionClosed, {{"request_id", "one"}});
+    EXPECT_EQ(events.activity_snapshot()["phase"], "permission_waiting");
+    events.emit(SessionEventKind::QuestionRequest, {{"request_id", "q"}});
+    events.emit(SessionEventKind::PermissionClosed, {{"request_id", "two"}});
+    EXPECT_EQ(events.activity_snapshot()["phase"], "question_waiting");
+    events.emit(SessionEventKind::QuestionClosed, {{"request_id", "q"}});
+    EXPECT_EQ(events.activity_snapshot()["phase"], "tool_running");
+    events.emit(SessionEventKind::ToolEnd, {{"tool", "bash"}, {"tool_call_id", "t"}, {"output", "private output"}});
+    EXPECT_EQ(events.activity_snapshot()["tool"], "");
+    EXPECT_EQ(events.activity_snapshot().dump().find("private output"), std::string::npos);
+}
+
+// 场景:回合以 aborted / error 结束,或 busy=false 却没有 outcome。
+// 期望:outcome 原样保留为 aborted / error;没有 outcome 时保持空串,不能当成 completed。
+TEST(SessionActivityState, CancellationAndFailureAreNeverSuccessfulCompletion) {
+    for (const auto* outcome : {"aborted", "error"}) {
+        EventDispatcher events;
+        events.emit(SessionEventKind::BusyChanged, {{"busy", true}});
+        events.emit(SessionEventKind::BusyChanged, {{"busy", false}, {"outcome", outcome}});
+        EXPECT_EQ(events.activity_snapshot()["outcome"], outcome);
+    }
+    EventDispatcher events;
+    events.emit(SessionEventKind::BusyChanged, {{"busy", false}});
+    EXPECT_EQ(events.activity_snapshot()["outcome"], "");
+}
+
+// 场景:不进回放环的 compacting 进度,以及压缩通知先「未完成」后「完成」。
+// 期望:phase=compacting 可见;只有 compact_notice_complete=true 才记 compact_id。
+TEST(SessionActivityState, TransientProgressAndCompactionAreSnapshotState) {
+    EventDispatcher events;
+    EventDispatcher::EmitOptions transient;
+    transient.buffered = false;
+    events.emit(SessionEventKind::AgentProgress, {{"phase", "compacting"}}, transient);
+    EXPECT_EQ(events.activity_snapshot()["phase"], "compacting");
+    events.emit(SessionEventKind::Message, {{"metadata", {{"compact_notice_id", "c1"}, {"compact_notice_complete", false}}}});
+    EXPECT_EQ(events.activity_snapshot()["compact_id"], "");
+    events.emit(SessionEventKind::Message, {{"metadata", {{"compact_notice_id", "c1"}, {"compact_notice_complete", true}}}});
+    EXPECT_EQ(events.activity_snapshot()["compact_id"], "c1");
+}
+
+// 场景:连续 20 条网状 agent 间消息,正文是私有内容。
+// 期望:只保留最近 16 条的发送方 / 接收方身份,快照里找不到正文。
+TEST(SessionActivityState, MeshTransfersRetainIdentityWithoutPrivateBodyAndAreBounded) {
+    EventDispatcher events;
+    for (int i = 0; i < 20; ++i) events.emit(SessionEventKind::Message, {
+        {"content", "private content"},
+        {"metadata", {{"inter_agent", {{"type", "MESSAGE"}, {"sender", "/root/a"},
+            {"recipient", "/root/b"}, {"sender_session_id", "child-a"}}}}}});
+    const auto snapshot = events.activity_snapshot();
+    ASSERT_EQ(snapshot["transfers"].size(), 16u);
+    EXPECT_EQ(snapshot["transfers"].back()["sender_session_id"], "child-a");
+    EXPECT_EQ(snapshot.dump().find("private content"), std::string::npos);
+}
+
+// 场景:默认「用于编程」模式下模型开始输出正文 —— 这时服务端不会发 responding 进度,
+// 只有一串 token。共推 400 个「字」(1200 字节),远超气泡需要的长度。
+// 期望:快照 phase=responding,text 是最后 160 字节以内、以最后一个字结尾的合法 UTF-8;
+// 进度里遗留的「正在等待模型响应」不再当作当前文案。
+// 回归:修复前快照一直停在 model_waiting,办公室里正在飙字的 agent 只显示一个问号。
+TEST(SessionActivityState, StreamingReplyIsVisibleWithBoundedTail) {
+    EventDispatcher events;
+    events.emit(SessionEventKind::BusyChanged, {{"busy", true}});
+    events.emit(SessionEventKind::AgentProgress, {{"phase", "model_waiting"}, {"label", "正在等待模型响应"}});
+    for (int i = 0; i < 399; ++i) events.emit(SessionEventKind::Token, {{"text", "字"}});
+    events.emit(SessionEventKind::Token, {{"text", "尾"}});
+    const auto snapshot = events.activity_snapshot();
+    EXPECT_EQ(snapshot["phase"], "responding");
+    EXPECT_EQ(snapshot["label"], "");
+    const auto tail = snapshot["text"].get<std::string>();
+    EXPECT_LE(tail.size(), 160u);
+    EXPECT_GE(tail.size(), 150u);
+    EXPECT_EQ(tail.size() % 3, 0u) << "每个汉字 3 字节,截断点必须落在字符边界";
+    EXPECT_EQ(tail.substr(tail.size() - 3), "尾");
+}
+
+// 场景:先推理(reasoning 进度 + 推理片段),再开始输出正文。
+// 期望:推理阶段 text 是推理尾巴;转入正文后旧推理内容清空,只剩正文。
+TEST(SessionActivityState, ReasoningAndReplyAreSeparateBubbles) {
+    EventDispatcher events;
+    events.emit(SessionEventKind::BusyChanged, {{"busy", true}});
+    events.emit(SessionEventKind::AgentProgress, {{"phase", "reasoning"}, {"label", "正在推理"}});
+    events.emit(SessionEventKind::Reasoning, {{"text", "check config"}});
+    EXPECT_EQ(events.activity_snapshot()["phase"], "reasoning");
+    EXPECT_EQ(events.activity_snapshot()["text"], "check config");
+    events.emit(SessionEventKind::Token, {{"text", "好的"}});
+    EXPECT_EQ(events.activity_snapshot()["phase"], "responding");
+    EXPECT_EQ(events.activity_snapshot()["text"], "好的");
+}
+
+// 场景:正文写到一半开始调用工具,工具带调用预览(display_override);随后工具结束。
+// 期望:工具期间 phase=tool_running、detail=预览、text 为空(正文气泡结束);
+// 工具结束后 tool / detail 都清空;没有 display_override 时退回 command_preview。
+TEST(SessionActivityState, ToolCallCarriesOneLinePreviewUntilItEnds) {
+    EventDispatcher events;
+    events.emit(SessionEventKind::BusyChanged, {{"busy", true}});
+    events.emit(SessionEventKind::Token, {{"text", "我先看看"}});
+    events.emit(SessionEventKind::ToolStart, {{"tool", "file_read"}, {"tool_call_id", "a"},
+        {"display_override", "src/main.cpp"}, {"args", {{"path", "secret-arg"}}}});
+    auto snapshot = events.activity_snapshot();
+    EXPECT_EQ(snapshot["phase"], "tool_running");
+    EXPECT_EQ(snapshot["detail"], "src/main.cpp");
+    EXPECT_EQ(snapshot["text"], "");
+    EXPECT_EQ(snapshot.dump().find("secret-arg"), std::string::npos);
+    events.emit(SessionEventKind::ToolEnd, {{"tool", "file_read"}, {"tool_call_id", "a"}});
+    snapshot = events.activity_snapshot();
+    EXPECT_EQ(snapshot["tool"], "");
+    EXPECT_EQ(snapshot["detail"], "");
+    events.emit(SessionEventKind::ToolStart, {{"tool", "bash"}, {"tool_call_id", "b"},
+        {"display_override", ""}, {"command_preview", "npm test"}});
+    EXPECT_EQ(events.activity_snapshot()["detail"], "npm test");
+}
diff --git a/tests/session/session_recent_activity_test.cpp b/tests/session/session_recent_activity_test.cpp
new file mode 100644
index 000000000..8be4e11aa
--- /dev/null
+++ b/tests/session/session_recent_activity_test.cpp
@@ -0,0 +1,142 @@
+#include <gtest/gtest.h>
+#include "session/session_recent_activity.hpp"
+#include "session/session_manager.hpp"
+#include "session/session_storage.hpp"
+#include "session/global_session_search.hpp"
+#include "session/turn_timing.hpp"
+#include "utils/cwd_hash.hpp"
+#include "utils/uuid.hpp"
+#include "test_support/memory/memory_test_home.hpp"
+#include <chrono>
+#include <filesystem>
+#include <fstream>
+#include <thread>
+
+using namespace acecode;
+namespace fs = std::filesystem;
+namespace {
+class RecentFixture : public testing::Test {
+protected:
+    acecode_test::MemoryTestHome home{"office-recency"};
+    fs::path root = home.root() / "catalog";
+    void SetUp() override { fs::create_directories(root); }
+    void TearDown() override { std::error_code ec; fs::remove_all(root, ec); }
+};
+ChatMessage input(const char* time, const char* text = "hello") {
+    ChatMessage result; result.role = "user"; result.content = text;
+    result.timestamp = time; result.uuid = generate_uuid(); return result;
+}
+}
+
+TEST_F(RecentFixture, ReverseReadIgnoresBackgroundMessagesAndDamagedTail) {
+    const auto file = (root / "session.jsonl").string();
+    auto user = input("2026-10-06T09:10:00Z");
+    ASSERT_TRUE(SessionStorage::append_message(file, user));
+    auto internal = input("2026-10-06T09:11:00Z");
+    internal.metadata = {{"hidden_goal_context", true}};
+    ASSERT_TRUE(SessionStorage::append_message(file, internal));
+    auto mesh = input("2026-10-06T09:12:00Z");
+    mesh.metadata = {{"inter_agent", {{"type", "MESSAGE"}, {"sender", "/root/a"}, {"recipient", "/root"}}}};
+    ASSERT_TRUE(SessionStorage::append_message(file, mesh));
+    ASSERT_TRUE(SessionStorage::append_message(file, make_turn_timing_message(
+        {user.uuid, 1, 2, 1, "completed"}, "2026-10-06T09:13:00Z")));
+    std::ofstream(file, std::ios::app) << "{broken\n";
+    auto automatic = input("2026-10-06T09:14:00Z");
+    automatic.metadata = {{"source_tool", "tool_search"}};
+    ASSERT_TRUE(SessionStorage::append_message(file, automatic));
+    const auto recent = read_session_recent_activity(file);
+    EXPECT_EQ(recent.last_user_message_at, user.timestamp);
+    EXPECT_EQ(recent.last_turn_outcome, "completed");
+    auto next = input("2026-10-06T10:00:00Z");
+    ASSERT_TRUE(SessionStorage::append_message(file, next));
+    EXPECT_TRUE(read_session_recent_activity(file).last_turn_outcome.empty());
+}
+
+TEST_F(RecentFixture, ManagerPersistsOnlyHumanRecencyAndKeepsItOnResume) {
+    SessionManager manager;
+    manager.start_session(root.string(), "test", "test");
+    const auto user = input("2026-10-06T09:10:00Z");
+    manager.on_message(user);
+    const auto id = manager.current_session_id();
+    const auto directory = manager.current_project_dir();
+    const auto metaPath = SessionStorage::meta_path(directory, id);
+    auto reply = user; reply.role = "assistant"; reply.timestamp = "2026-10-06T10:00:00Z";
+    manager.on_message(reply);
+    manager.set_session_title("renamed");
+    EXPECT_EQ(SessionStorage::read_meta(metaPath).last_user_message_at, user.timestamp);
+    manager.on_message(make_turn_timing_message({user.uuid,1,2,1,"aborted"},reply.timestamp));
+    EXPECT_EQ(SessionStorage::read_meta(metaPath).last_turn_outcome, "aborted");
+    manager.resume_session(id);
+    EXPECT_EQ(manager.display_snapshot().last_user_message_at, user.timestamp);
+    EXPECT_EQ(manager.display_snapshot().last_turn_outcome, "aborted");
+    manager.on_message(input("2026-10-06T11:00:00Z"));
+    EXPECT_EQ(SessionStorage::read_meta(metaPath).last_user_message_at, "2026-10-06T11:00:00Z");
+    EXPECT_TRUE(SessionStorage::read_meta(metaPath).last_turn_outcome.empty());
+    manager.finalize();
+    std::error_code ec; fs::remove_all(directory, ec);
+}
+
+TEST_F(RecentFixture, GlobalFiveUseUserTimeAcrossProjectsAndExcludeChildrenAndArchive) {
+    for (int i = 0; i < 8; ++i) {
+        const auto directory = root / (i % 2 == 0 ? "project-a" : "project-b");
+        fs::create_directories(directory);
+        SessionMeta meta;
+        meta.id = "20261006-10000" + std::to_string(i) + "-abcd";
+        meta.cwd = directory.string(); meta.created_at = "2026-10-06T00:00:00Z";
+        meta.updated_at = "2026-10-06T23:00:0" + std::to_string(9-i) + "Z";
+        meta.last_user_message_at = "2026-10-06T10:00:0" + std::to_string(i) + "Z";
+        if (i == 7) meta.archived = true;
+        if (i == 6) meta.parent_session_id = "parent";
+        // One legacy entry must derive its real input time from JSONL.
+        const auto message = input(meta.last_user_message_at.c_str());
+        ASSERT_TRUE(SessionStorage::append_message(SessionStorage::session_path(directory.string(),meta.id),message));
+        if (i == 5) meta.last_user_message_at.clear();
+        ASSERT_TRUE(SessionStorage::write_meta(SessionStorage::meta_path(directory.string(),meta.id),meta));
+    }
+    GlobalSessionSearchService service(root.string());
+    service.start(); service.notify_startup_interaction();
+    GlobalSessionSearchPage result;
+    const auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds(5);
+    do {
+        result = service.recent_user_sessions();
+        if (result.progress.complete) break;
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    } while (std::chrono::steady_clock::now() < deadline);
+    service.stop();
+    ASSERT_TRUE(result.progress.complete);
+    ASSERT_EQ(result.entries.size(),5u);
+    EXPECT_EQ(result.entries.front().meta.id,"20261006-100005-abcd");
+    EXPECT_EQ(result.entries.back().meta.id,"20261006-100001-abcd");
+}
+
+TEST_F(RecentFixture, ForkUsesRetainedInputTimeWithoutPretendingItWasSentNow) {
+    SessionManager manager;
+    manager.start_session(root.string(), "test", "test");
+    const auto first = input("2026-10-06T09:10:00Z");
+    const auto second = input("2026-10-06T10:00:00Z");
+    manager.on_message(first); manager.on_message(second);
+    const auto source = manager.current_session_id();
+    const auto fork = manager.fork_session_to_new_id({first}, "branch", source, first.uuid);
+    ASSERT_FALSE(fork.empty());
+    const auto meta = SessionStorage::read_meta(SessionStorage::meta_path(manager.current_project_dir(), fork));
+    EXPECT_EQ(meta.last_user_message_at, first.timestamp);
+    EXPECT_EQ(manager.current_session_id(), source);
+    EXPECT_EQ(manager.display_snapshot().last_user_message_at, second.timestamp);
+    const auto active_fork = manager.fork_active_session({first});
+    ASSERT_FALSE(active_fork.empty());
+    EXPECT_EQ(manager.display_snapshot().last_user_message_at, first.timestamp);
+}
+
+TEST_F(RecentFixture, InternalTurnOutcomePersistsWithoutChangingHumanRecency) {
+    SessionManager manager;
+    manager.start_session(root.string(), "test", "test");
+    auto internal = input("2026-10-06T10:00:00Z");
+    internal.metadata = {{"inter_agent", {{"type", "MESSAGE"}, {"sender", "/root"}, {"recipient", "/root/a"}}}};
+    manager.on_message(internal);
+    manager.record_turn_outcome("completed");
+    EXPECT_TRUE(manager.display_snapshot().last_user_message_at.empty());
+    EXPECT_EQ(manager.display_snapshot().last_turn_outcome, "completed");
+    const auto id = manager.current_session_id();
+    manager.resume_session(id);
+    EXPECT_EQ(manager.display_snapshot().last_turn_outcome, "completed");
+}
diff --git a/tests/test_support/channels/core_fakes.hpp b/tests/test_support/channels/core_fakes.hpp
new file mode 100644
index 000000000..0e6bf779a
--- /dev/null
+++ b/tests/test_support/channels/core_fakes.hpp
@@ -0,0 +1,402 @@
+#pragma once
+
+// 通道核心(host/channels/core)单测共用的假对象:
+//   - FakeSessions:线程安全的内存版 SessionClient,可设置会话列表、忙碌、删除;
+//     send_input / respond_permission 等会像真实会话一样回推事件。
+//   - FakeTransport:可编排的假传输层,记录所有发送,可注入入站消息与状态变化。
+// 出站投影经 RemoteControlHub 的后台线程发送,断言前用 wait_until 等待。
+
+#include "channels/core/conversations.hpp"
+#include "im/transport.hpp"
+#include "session/ask_user_question_prompter.hpp"
+#include "session/session_client.hpp"
+#include "test_support/channels/test_support.hpp"
+#include "utils/utf8_path.hpp"
+
+#include <gtest/gtest.h>
+
+#include <chrono>
+#include <filesystem>
+#include <fstream>
+#include <functional>
+#include <map>
+#include <mutex>
+#include <set>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace acecode::channels::core::test {
+
+inline bool wait_until(const std::function<bool()>& ready,
+                       std::chrono::milliseconds timeout = std::chrono::seconds(5)) {
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    while (std::chrono::steady_clock::now() < deadline) {
+        if (ready()) return true;
+        std::this_thread::sleep_for(std::chrono::milliseconds(5));
+    }
+    return ready();
+}
+
+class FakeSessions : public SessionClient {
+public:
+    struct Interjection {
+        std::string session_id;
+        std::string request_id;
+        UserInput input;
+    };
+
+    std::string create_session(const SessionOptions& options) override {
+        std::lock_guard<std::mutex> lock(mu);
+        const auto id = "ch-" + std::to_string(++counter);
+        created.emplace_back(id, options);
+        SessionInfo info;
+        info.id = id;
+        info.no_workspace = options.no_workspace;
+        info.workspace_hash = options.workspace_hash;
+        info.cwd = options.no_workspace ? "C:/fake-no-workspace/" + id : options.cwd;
+        info.title = "会话 " + id;
+        info.active = true;
+        sessions[id] = info;
+        return id;
+    }
+    bool resume_session(const std::string& id, const SessionOptions&) override {
+        std::lock_guard<std::mutex> lock(mu);
+        resumed.push_back(id);
+        return sessions.count(id) > 0 && !deleted.count(id);
+    }
+    std::vector<SessionInfo> list_sessions() override {
+        std::lock_guard<std::mutex> lock(mu);
+        std::vector<SessionInfo> out;
+        for (const auto& [id, info] : sessions)
+            if (!deleted.count(id)) out.push_back(info);
+        return out;
+    }
+    void destroy_session(const std::string&) override {}
+    SubscriptionId subscribe(const std::string& id, EventListener listener, std::uint64_t) override {
+        std::lock_guard<std::mutex> lock(mu);
+        const auto sub = next_sub++;
+        listeners[id][sub] = std::move(listener);
+        return sub;
+    }
+    void unsubscribe(const std::string& id, SubscriptionId sub) override {
+        std::lock_guard<std::mutex> lock(mu);
+        listeners[id].erase(sub);
+    }
+    bool send_input(const std::string& id, const std::string& text) override {
+        UserInput input;
+        input.text = text;
+        return send_input(id, input);
+    }
+    bool send_input(const std::string& id, const UserInput& input) override {
+        {
+            std::lock_guard<std::mutex> lock(mu);
+            if (!accept_input || deleted.count(id) || !sessions.count(id)) return false;
+            inputs.emplace_back(id, input);
+        }
+        emit(id, SessionEventKind::Message,
+             {{"role", "user"}, {"content", input.text}, {"metadata", input.metadata}});
+        return true;
+    }
+    TurnSteerResult interject_question(const std::string& id, const std::string& request_id, const UserInput& input,
+                                       const std::string&) override {
+        bool ok;
+        {
+            std::lock_guard<std::mutex> lock(mu);
+            interjections.push_back({id, request_id, input});
+            ok = interject_ok;
+        }
+        if (!ok) return {TurnSteerStatus::NoPendingQuestion, {}, "no pending question"};
+        emit(id, SessionEventKind::QuestionClosed, {{"request_id", request_id}, {"reason", "interjected"}});
+        return {TurnSteerStatus::Accepted, "turn-1", {}};
+    }
+    BuiltinCommandResult execute_builtin_command(const std::string&, const BuiltinCommandRequest&) override {
+        return {};
+    }
+    void respond_permission(const std::string& id, const PermissionDecision& decision) override {
+        {
+            std::lock_guard<std::mutex> lock(mu);
+            decisions.emplace_back(id, decision);
+        }
+        emit(id, SessionEventKind::PermissionClosed,
+             {{"request_id", decision.request_id}, {"choice", to_string(decision.choice)}});
+    }
+    QuestionResponseStatus respond_question(const std::string& id, const std::string& request,
+                                            const AskUserQuestionResponse&) override {
+        {
+            std::lock_guard<std::mutex> lock(mu);
+            if (!answered.insert(request).second) return QuestionResponseStatus::Closed;
+        }
+        emit(id, SessionEventKind::QuestionClosed, {{"request_id", request}, {"reason", "answered"}});
+        return QuestionResponseStatus::Accepted;
+    }
+    std::optional<std::vector<PendingQuestionRequestSnapshot>> snapshot_pending_questions(
+        const std::string&) override {
+        return std::vector<PendingQuestionRequestSnapshot>{};
+    }
+    void abort(const std::string& id) override {
+        std::lock_guard<std::mutex> lock(mu);
+        aborts.push_back(id);
+    }
+
+    // ---- 测试操作 ----
+    void emit(const std::string& id, SessionEventKind kind, const nlohmann::json& payload) {
+        std::map<SubscriptionId, EventListener> copy;
+        std::uint64_t seq;
+        {
+            std::lock_guard<std::mutex> lock(mu);
+            copy = listeners[id];
+            seq = ++next_seq;
+        }
+        for (const auto& item : copy) item.second(SessionEvent{kind, seq, 0, payload});
+    }
+    void assistant(const std::string& id, const std::string& text) {
+        emit(id, SessionEventKind::Message, {{"role", "assistant"}, {"content", text}});
+    }
+    void add_session(const std::string& id, const std::string& cwd, const std::string& workspace_hash,
+                     bool no_workspace, const std::string& title) {
+        std::lock_guard<std::mutex> lock(mu);
+        SessionInfo info;
+        info.id = id;
+        info.cwd = cwd;
+        info.workspace_hash = workspace_hash;
+        info.no_workspace = no_workspace;
+        info.title = title;
+        sessions[id] = info;
+    }
+    void set_busy(const std::string& id, bool busy) {
+        std::lock_guard<std::mutex> lock(mu);
+        sessions[id].busy = busy;
+    }
+    void remove(const std::string& id) {
+        std::lock_guard<std::mutex> lock(mu);
+        deleted.insert(id);
+    }
+    std::size_t listener_count(const std::string& id) {
+        std::lock_guard<std::mutex> lock(mu);
+        return listeners[id].size();
+    }
+    std::vector<std::pair<std::string, UserInput>> input_log() {
+        std::lock_guard<std::mutex> lock(mu);
+        return inputs;
+    }
+    std::vector<std::pair<std::string, SessionOptions>> created_log() {
+        std::lock_guard<std::mutex> lock(mu);
+        return created;
+    }
+    std::vector<std::string> abort_log() {
+        std::lock_guard<std::mutex> lock(mu);
+        return aborts;
+    }
+
+    // 会话目录:与 build_rc_session_catalog 同形,按 id 排序。
+    std::vector<rc::RcSessionTarget> catalog() {
+        std::lock_guard<std::mutex> lock(mu);
+        std::vector<rc::RcSessionTarget> out;
+        for (const auto& [id, info] : sessions) {
+            if (deleted.count(id)) continue;
+            rc::RcSessionTarget target;
+            target.session_id = id;
+            target.cwd = info.cwd;
+            target.workspace_hash = info.workspace_hash;
+            target.no_workspace = info.no_workspace;
+            target.title = info.title;
+            out.push_back(target);
+        }
+        return out;
+    }
+
+    std::mutex mu;
+    int counter = 0;
+    bool accept_input = true;
+    bool interject_ok = true;
+    std::uint64_t next_sub = 1, next_seq = 0;
+    std::map<std::string, SessionInfo> sessions;
+    std::set<std::string> deleted, answered;
+    std::vector<std::pair<std::string, SessionOptions>> created;
+    std::vector<std::string> resumed, aborts;
+    std::vector<std::pair<std::string, UserInput>> inputs;
+    std::vector<Interjection> interjections;
+    std::vector<std::pair<std::string, PermissionDecision>> decisions;
+    std::map<std::string, std::map<SubscriptionId, EventListener>> listeners;
+};
+
+class FakeTransport : public im::Transport {
+public:
+    struct Sent {
+        im::Address to;
+        std::string text;
+        nlohmann::json context;
+        std::string file;  // send_file 时为文件名
+    };
+
+    explicit FakeTransport(std::string name = "telegram", im::Capabilities caps = {})
+        : name_(std::move(name)), caps_(caps) {}
+
+    std::string platform() const override { return name_; }
+    im::Capabilities capabilities() const override { return caps_; }
+    void start(im::TransportCallbacks callbacks) override {
+        im::TransportStatus snapshot;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            callbacks_ = std::move(callbacks);
+            ++starts;
+            status_.state = im::LinkState::Connected;
+            status_.account = account;
+            status_.extra = extra;
+            snapshot = status_;
+        }
+        notify(snapshot);
+    }
+    void stop() override {
+        std::lock_guard<std::mutex> lock(mu_);
+        callbacks_ = {};
+        ++stops;
+        status_.state = im::LinkState::Stopped;
+    }
+    im::TransportStatus status() const override {
+        std::lock_guard<std::mutex> lock(mu_);
+        return status_;
+    }
+    im::SendResult send_text(const im::Address& to, const std::string& text, const nlohmann::json& context) override {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (fail_sends > 0) {
+            --fail_sends;
+            return {im::SendOutcome::Failed, "平台拒绝"};
+        }
+        sent_.push_back({to, text, context, {}});
+        return {im::SendOutcome::Sent, {}};
+    }
+    im::SendResult send_file(const im::Address& to, const std::filesystem::path& path, const std::string& name,
+                             const std::string&, const nlohmann::json& context) override {
+        std::lock_guard<std::mutex> lock(mu_);
+        sent_.push_back({to, path_to_utf8(path), context, name});
+        return {im::SendOutcome::Sent, {}};
+    }
+    void set_typing(const im::Address&, bool on) override {
+        std::lock_guard<std::mutex> lock(mu_);
+        typing.push_back(on);
+    }
+    bool download(const im::Attachment&, const std::filesystem::path& dest, std::string* error) override {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (!download_ok) {
+            if (error) *error = "下载失败";
+            return false;
+        }
+        std::ofstream out(dest, std::ios::binary);
+        out << download_bytes;
+        return true;
+    }
+    nlohmann::json action(const std::string& name, const nlohmann::json&) override {
+        std::lock_guard<std::mutex> lock(mu_);
+        actions.push_back(name);
+        return {{"ok", true}};
+    }
+
+    // ---- 测试操作 ----
+    void inject(const im::Inbound& inbound) {
+        std::function<void(im::Inbound)> on_inbound;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            on_inbound = callbacks_.on_inbound;
+        }
+        if (on_inbound) on_inbound(inbound);
+    }
+    void report(im::LinkState state, const std::string& detail) {
+        im::TransportStatus snapshot;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            status_.state = state;
+            status_.detail = detail;
+            status_.retry_stopped = state == im::LinkState::Failed;  // 假定 Failed 都是致命错误
+            snapshot = status_;
+        }
+        notify(snapshot);
+    }
+    std::vector<Sent> sent() const {
+        std::lock_guard<std::mutex> lock(mu_);
+        return sent_;
+    }
+    std::vector<std::string> texts() const {
+        std::lock_guard<std::mutex> lock(mu_);
+        std::vector<std::string> out;
+        for (const auto& item : sent_)
+            if (item.file.empty()) out.push_back(item.text);
+        return out;
+    }
+    // 是否有一条发送包含 needle。
+    bool said(const std::string& needle) const {
+        for (const auto& text : texts())
+            if (text.find(needle) != std::string::npos) return true;
+        return false;
+    }
+    bool wait_said(const std::string& needle) const {
+        return wait_until([&] { return said(needle); });
+    }
+    std::size_t sent_count() const {
+        std::lock_guard<std::mutex> lock(mu_);
+        return sent_.size();
+    }
+
+    std::string account = "100";
+    nlohmann::json extra = nlohmann::json::object();
+    int fail_sends = 0;
+    bool download_ok = true;
+    std::string download_bytes = "image-bytes";
+    int starts = 0, stops = 0;
+    std::vector<bool> typing;
+    std::vector<std::string> actions;
+
+private:
+    void notify(const im::TransportStatus& status) {
+        std::function<void(const im::TransportStatus&)> on_status;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            on_status = callbacks_.on_status;
+        }
+        if (on_status) on_status(status);
+    }
+
+    std::string name_;
+    im::Capabilities caps_;
+    mutable std::mutex mu_;
+    im::TransportCallbacks callbacks_;
+    im::TransportStatus status_;
+    std::vector<Sent> sent_;
+};
+
+inline im::Address private_address(const std::string& user, const std::string& platform = "telegram",
+                                   const std::string& account = "100") {
+    im::Address address;
+    address.platform = platform;
+    address.account = account;
+    address.kind = im::ChatKind::Private;
+    address.chat = user;
+    address.sender = user;
+    return address;
+}
+
+inline im::Address group_address(const std::string& group, const std::string& member,
+                                 const std::string& platform = "telegram", const std::string& account = "100") {
+    im::Address address;
+    address.platform = platform;
+    address.account = account;
+    address.kind = im::ChatKind::Group;
+    address.chat = group;
+    address.sender = member;
+    return address;
+}
+
+inline im::Inbound message(const im::Address& address, const std::string& text, const std::string& id,
+                           bool mentioned = true) {
+    im::Inbound inbound;
+    inbound.address = address;
+    inbound.text = text;
+    inbound.message_id = id;
+    inbound.mentioned = address.kind == im::ChatKind::Private ? true : mentioned;
+    inbound.sender_name = "名字-" + address.sender;
+    inbound.reply_context = {{"msg_id", id}};
+    return inbound;
+}
+
+} // namespace acecode::channels::core::test
diff --git a/tests/test_support/im/fake_dingtalk_server.hpp b/tests/test_support/im/fake_dingtalk_server.hpp
new file mode 100644
index 000000000..a09e5af12
--- /dev/null
+++ b/tests/test_support/im/fake_dingtalk_server.hpp
@@ -0,0 +1,378 @@
+#pragma once
+
+// 测试用:本机假钉钉开放平台(只监听 127.0.0.1)。一个端口同时扮演三个角色:
+//   - api.dingtalk.com:/v1.0/oauth2/accessToken、/v1.0/gateway/connections/open、
+//     /v1.0/robot/oToMessages/batchSend、/v1.0/robot/groupMessages/send、/v1.0/robot/messageFiles/download;
+//   - oapi.dingtalk.com:/media/upload(multipart)、会话 webhook /robot/sendBySession?session=…;
+//   - Stream 网关:WebSocket /connect?ticket=…(ticket 一次性),以及 OSS 下载 /oss/<code>
+//     (带 Content-Type 头的请求一律 403,模拟签名校验失败)。
+// 各接口都可以注入应答,用于钉钉传输层与 API 客户端的端到端测试。
+
+#include "test_support/network/crow_test_server.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <set>
+#include <string>
+#include <thread>
+#include <utility>
+#include <vector>
+
+namespace acecode::test {
+
+class FakeDingTalkServer {
+public:
+    struct Request {
+        std::string path;
+        std::string token;           // x-acs-dingtalk-access-token 头或 access_token 查询参数
+        std::string query;           // 关心的查询参数(webhook 的 session、上传的 type)
+        std::string content_type;    // 请求的 Content-Type 头
+        nlohmann::json body;         // JSON 请求体;multipart 时为普通字段
+        std::string file_name;       // multipart 文件字段的文件名
+        std::string file_body;       // multipart 文件内容
+    };
+
+    using Reply = std::pair<int, nlohmann::json>;
+
+    std::string client_id = "dingTESTCLIENT";
+    std::string client_secret = "client-secret-value-123";
+
+    // 以下应答钩子可选;返回 status=0 表示走默认应答。
+    std::function<Reply(const Request&)> token_handler;
+    std::function<Reply(const Request&)> open_handler;
+    std::function<Reply(const Request&)> webhook_handler;
+    std::function<Reply(const Request&)> oto_handler;
+    std::function<Reply(const Request&)> group_handler;
+    std::function<Reply(const Request&)> upload_handler;
+    std::function<Reply(const Request&)> download_handler;
+
+    FakeDingTalkServer() {
+        CROW_ROUTE(app_, "/v1.0/oauth2/accessToken").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto request = make_request("/v1.0/oauth2/accessToken", req);
+            record(request);
+            int calls = 0;
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                calls = ++token_calls_;
+            }
+            if (auto custom = call(token_handler, request); custom.first) return json_response(custom);
+            if (request.body.value("appKey", "") != client_id || request.body.value("appSecret", "") != client_secret)
+                return json_response({400, {{"code", "invalidClientIdOrSecret"}, {"requestid", "R-T"},
+                                            {"message", "无效的clientId或者clientSecret"}}});
+            return json_response({200, {{"accessToken", "tok-" + std::to_string(calls)}, {"expireIn", 7200}}});
+        });
+        CROW_ROUTE(app_, "/v1.0/gateway/connections/open").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto request = make_request("/v1.0/gateway/connections/open", req);
+            record(request);
+            if (auto custom = call(open_handler, request); custom.first) return json_response(custom);
+            if (request.body.value("clientId", "") != client_id ||
+                request.body.value("clientSecret", "") != client_secret)
+                return json_response({401, {{"code", "authFailed"}, {"requestid", "R-O"}, {"message", "鉴权失败"}}});
+            std::string ticket;
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                ticket = "ticket-" + std::to_string(++ticket_seq_);
+                tickets_.insert(ticket);
+                issued_.push_back(ticket);
+            }
+            return json_response({200, {{"endpoint", "ws://127.0.0.1:" + std::to_string(port_) + "/connect"},
+                                        {"ticket", ticket}}});
+        });
+        CROW_ROUTE(app_, "/robot/sendBySession").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            auto request = make_request("/robot/sendBySession", req);
+            request.query = param(req, "session");
+            record(request);
+            if (auto custom = call(webhook_handler, request); custom.first) return json_response(custom);
+            return json_response({200, {{"errcode", 0}, {"errmsg", "ok"}}});
+        });
+        CROW_ROUTE(app_, "/v1.0/robot/oToMessages/batchSend").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto request = make_request("/v1.0/robot/oToMessages/batchSend", req);
+            record(request);
+            if (auto auth = check_token(request); auth.first) return json_response(auth);
+            if (auto custom = call(oto_handler, request); custom.first) return json_response(custom);
+            return json_response({200, {{"processQueryKey", "PQK-OTO"},
+                                        {"invalidStaffIdList", nlohmann::json::array()},
+                                        {"flowControlledStaffIdList", nlohmann::json::array()}}});
+        });
+        CROW_ROUTE(app_, "/v1.0/robot/groupMessages/send").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto request = make_request("/v1.0/robot/groupMessages/send", req);
+            record(request);
+            if (auto auth = check_token(request); auth.first) return json_response(auth);
+            if (auto custom = call(group_handler, request); custom.first) return json_response(custom);
+            return json_response({200, {{"processQueryKey", "PQK-GROUP"}}});
+        });
+        CROW_ROUTE(app_, "/v1.0/robot/messageFiles/download").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto request = make_request("/v1.0/robot/messageFiles/download", req);
+            record(request);
+            if (auto auth = check_token(request); auth.first) return json_response(auth);
+            if (auto custom = call(download_handler, request); custom.first) return json_response(custom);
+            return json_response({200, {{"downloadUrl", base() + "/oss/" + request.body.value("downloadCode", "")}}});
+        });
+        CROW_ROUTE(app_, "/oss/<string>")
+        ([this](const crow::request& req, const std::string& code) {
+            auto request = make_request("/oss/" + code, req);
+            record(request);
+            if (!request.content_type.empty()) return crow::response(403, "SignatureDoesNotMatch");
+            return crow::response(200, std::string(code == "big" ? 4096 : 16, 'z'));
+        });
+        CROW_ROUTE(app_, "/media/upload").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            auto request = make_request("/media/upload", req);
+            request.token = param(req, "access_token");
+            request.query = param(req, "type");
+            record(request);
+            if (auto custom = call(upload_handler, request); custom.first) return json_response(custom);
+            if (!valid_token(request.token))
+                return json_response({200, {{"errcode", 40014}, {"errmsg", "不合法的access_token"}}});
+            int seq = 0;
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                seq = ++media_seq_;
+            }
+            return json_response({200, {{"errcode", 0}, {"errmsg", "ok"}, {"type", request.query},
+                                        {"media_id", "@media-" + std::to_string(seq)}}});
+        });
+        CROW_WEBSOCKET_ROUTE(app_, "/connect")
+            .onaccept([this](const crow::request& req, void**) -> bool {
+                const auto ticket = param(req, "ticket");
+                std::lock_guard<std::mutex> lock(mu_);
+                used_.push_back(ticket);
+                // ticket 一次性:用过即作废,没发过的一律拒绝握手。
+                return tickets_.erase(ticket) > 0;
+            })
+            .onopen([this](crow::websocket::connection& conn) {
+                std::lock_guard<std::mutex> lock(mu_);
+                conn_ = &conn;
+                ++connections_;
+            })
+            .onclose([this](crow::websocket::connection& conn, const std::string&, std::uint16_t) {
+                std::lock_guard<std::mutex> lock(mu_);
+                if (conn_ == &conn) conn_ = nullptr;
+            })
+            .onmessage([this](crow::websocket::connection&, const std::string& data, bool) {
+                std::lock_guard<std::mutex> lock(mu_);
+                acks_.push_back(parse(data));
+            });
+        server_ = std::make_unique<CrowTestServer>(app_);
+        port_ = server_->port();
+    }
+
+    ~FakeDingTalkServer() { server_.reset(); }
+
+    std::string base() const { return "http://127.0.0.1:" + std::to_string(port_); }
+    std::string webhook(const std::string& session) const { return base() + "/robot/sendBySession?session=" + session; }
+
+    static std::int64_t now_ms() {
+        return std::chrono::duration_cast<std::chrono::milliseconds>(
+                   std::chrono::system_clock::now().time_since_epoch())
+            .count();
+    }
+
+    // 单聊消息的 data(staff 为空时模拟组织外用户:只有加密 senderId)。
+    nlohmann::json private_text(const std::string& msg_id, const std::string& staff, const std::string& text,
+                                const std::string& session = "S1", std::int64_t expires_ms = 0) const {
+        nlohmann::json data{{"msgId", msg_id},
+                            {"msgtype", "text"},
+                            {"text", {{"content", text}}},
+                            {"conversationType", "1"},
+                            {"conversationId", "cidPRIVATE"},
+                            {"senderId", "$:LWCP_v1:$" + (staff.empty() ? std::string("ext") : staff)},
+                            {"senderNick", "Ann"},
+                            {"chatbotUserId", "$:LWCP_v1:$bot"},
+                            {"robotCode", client_id},
+                            {"sessionWebhook", webhook(session)},
+                            {"sessionWebhookExpiredTime", expires_ms ? expires_ms : now_ms() + 90 * 60 * 1000},
+                            {"createAt", now_ms()}};
+        if (!staff.empty()) data["senderStaffId"] = staff;
+        return data;
+    }
+
+    nlohmann::json group_text(const std::string& msg_id, const std::string& cid, const std::string& staff,
+                              const std::string& text, bool at_bot = true) const {
+        return {{"msgId", msg_id},
+                {"msgtype", "text"},
+                {"text", {{"content", text}}},
+                {"conversationType", "2"},
+                {"conversationId", cid},
+                {"conversationTitle", "Team"},
+                {"senderId", "$:LWCP_v1:$" + staff},
+                {"senderStaffId", staff},
+                {"senderNick", "Bob"},
+                {"chatbotUserId", "$:LWCP_v1:$bot"},
+                {"isInAtList", at_bot},
+                {"atUsers", at_bot ? nlohmann::json::array({{{"dingtalkId", "$:LWCP_v1:$bot"}}})
+                                   : nlohmann::json::array()},
+                {"robotCode", client_id},
+                {"sessionWebhook", webhook("G-" + cid)},
+                {"sessionWebhookExpiredTime", now_ms() + 90 * 60 * 1000}};
+    }
+
+    // 推一条机器人消息回调;header_id 为帧头 messageId(重投时换新)。
+    void push_callback(const std::string& header_id, const nlohmann::json& data) {
+        push({{"specVersion", "1.0"},
+              {"type", "CALLBACK"},
+              {"headers", {{"appId", "app"}, {"connectionId", "c1"}, {"contentType", "application/json"},
+                           {"messageId", header_id}, {"time", "1690106592000"},
+                           {"topic", "/v1.0/im/bot/messages/get"}}},
+              {"data", data.dump()}});
+    }
+    void push_ping(const std::string& header_id, const std::string& opaque) {
+        push({{"specVersion", "1.0"},
+              {"type", "SYSTEM"},
+              {"headers", {{"contentType", "application/json"}, {"messageId", header_id}, {"topic", "ping"},
+                           {"time", 1690106592000LL}}},
+              {"data", nlohmann::json{{"opaque", opaque}}.dump()}});
+    }
+    void push_disconnect(const std::string& header_id) {
+        nlohmann::json headers{{"contentType", "application/json"}, {"topic", "disconnect"}};
+        if (!header_id.empty()) headers["messageId"] = header_id;
+        push({{"specVersion", "1.0"}, {"type", "SYSTEM"}, {"headers", headers},
+              {"data", R"({"reason": "connection is expired"})"}});
+    }
+    void push(const nlohmann::json& frame) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (conn_) conn_->send_text(frame.dump());
+    }
+    void close_connection(std::uint16_t code = 1000) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (conn_) conn_->close("bye", code);
+    }
+
+    std::vector<Request> requests() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return requests_;
+    }
+    std::vector<Request> requests_to(const std::string& path) {
+        std::vector<Request> out;
+        for (const auto& r : requests()) if (r.path == path) out.push_back(r);
+        return out;
+    }
+    std::vector<nlohmann::json> acks() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return acks_;
+    }
+    bool has_ack(const std::string& message_id) {
+        for (const auto& ack : acks()) {
+            if (ack.contains("headers") && ack["headers"].value("messageId", "") == message_id) return true;
+        }
+        return false;
+    }
+    int connections() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return connections_;
+    }
+    int token_calls() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return token_calls_;
+    }
+    std::vector<std::string> issued_tickets() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return issued_;
+    }
+    std::vector<std::string> used_tickets() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return used_;
+    }
+    // 令牌作废:之后这些令牌调用 OpenAPI 一律 InvalidAuthentication。
+    void revoke_token(const std::string& token) {
+        std::lock_guard<std::mutex> lock(mu_);
+        revoked_.insert(token);
+    }
+
+    static bool wait_until(const std::function<bool()>& predicate,
+                           std::chrono::milliseconds timeout = std::chrono::seconds(5)) {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (std::chrono::steady_clock::now() < deadline) {
+            if (predicate()) return true;
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        }
+        return predicate();
+    }
+
+private:
+    static nlohmann::json parse(const std::string& text) {
+        try {
+            return nlohmann::json::parse(text);
+        } catch (...) {
+            return nlohmann::json::object();
+        }
+    }
+    static std::string param(const crow::request& req, const char* name) {
+        const char* value = req.url_params.get(name);
+        return value ? std::string(value) : std::string{};
+    }
+    static crow::response json_response(const Reply& reply) {
+        crow::response res(reply.first, reply.second.dump());
+        res.set_header("Content-Type", "application/json");
+        return res;
+    }
+    static Reply call(const std::function<Reply(const Request&)>& handler, const Request& request) {
+        return handler ? handler(request) : Reply{0, nullptr};
+    }
+    static Request make_request(const std::string& path, const crow::request& req) {
+        Request request;
+        request.path = path;
+        request.token = req.get_header_value("x-acs-dingtalk-access-token");
+        request.content_type = req.get_header_value("Content-Type");
+        if (request.content_type.find("multipart/form-data") != std::string::npos) {
+            request.body = nlohmann::json::object();
+            crow::multipart::message message(req);
+            for (const auto& part : message.parts) {
+                const auto disposition = part.get_header_object("Content-Disposition");
+                const auto name = disposition.params.count("name") ? disposition.params.at("name") : std::string{};
+                if (disposition.params.count("filename")) {
+                    request.file_name = disposition.params.at("filename");
+                    request.file_body = part.body;
+                } else {
+                    request.body[name] = part.body;
+                }
+            }
+        } else {
+            request.body = req.body.empty() ? nlohmann::json::object() : parse(req.body);
+        }
+        return request;
+    }
+    bool valid_token(const std::string& token) {
+        std::lock_guard<std::mutex> lock(mu_);
+        return token.rfind("tok-", 0) == 0 && !revoked_.count(token);
+    }
+    Reply check_token(const Request& request) {
+        if (valid_token(request.token)) return {0, nullptr};
+        return {400, {{"code", "InvalidAuthentication"}, {"requestid", "R-A"}, {"message", "不合法的access_token"}}};
+    }
+    void record(const Request& request) {
+        std::lock_guard<std::mutex> lock(mu_);
+        requests_.push_back(request);
+    }
+
+    crow::SimpleApp app_;
+    std::unique_ptr<CrowTestServer> server_;
+    std::uint16_t port_ = 0;
+    std::mutex mu_;
+    crow::websocket::connection* conn_ = nullptr;
+    int connections_ = 0;
+    int token_calls_ = 0;
+    int ticket_seq_ = 0;
+    int media_seq_ = 0;
+    std::set<std::string> tickets_;
+    std::set<std::string> revoked_;
+    std::vector<std::string> issued_;
+    std::vector<std::string> used_;
+    std::vector<Request> requests_;
+    std::vector<nlohmann::json> acks_;
+};
+
+} // namespace acecode::test
diff --git a/tests/test_support/im/fake_discord_server.hpp b/tests/test_support/im/fake_discord_server.hpp
new file mode 100644
index 000000000..ed001abc1
--- /dev/null
+++ b/tests/test_support/im/fake_discord_server.hpp
@@ -0,0 +1,366 @@
+#pragma once
+
+// 测试用:本机假 Discord。REST 挂在 /api/v10 下(/users/@me、/applications/@me、/gateway/bot、
+// 打开私聊、发消息(JSON 与 multipart)、输入状态、取消息),CDN 挂在 /cdn/attachments/...,
+// 网关是两个 WebSocket 路由:/gateway/(首次登录)与 /resume/(READY 给出的恢复地址)。
+// 各环节可注入失败:关闭码、不回 ACK、Resume 被拒、发消息返回 429 / 10008 等。只监听 127.0.0.1。
+
+#include "test_support/network/crow_test_server.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <set>
+#include <string>
+#include <thread>
+#include <utility>
+#include <vector>
+
+namespace acecode::test {
+
+class FakeDiscordServer {
+public:
+    struct Request {
+        std::string method;
+        std::string path;           // 去掉 /api/v10 前缀;CDN 请求为 /cdn/...
+        std::string authorization;
+        std::string user_agent;
+        nlohmann::json body = nlohmann::json::object();  // JSON 请求体,或 multipart 的 payload_json
+        std::vector<std::string> part_names;              // multipart 字段名
+        std::string file_name;                            // multipart 文件字段的文件名
+        std::string file_body;                            // multipart 文件内容
+    };
+
+    struct Frame {
+        std::string route;  // "gateway" / "resume"
+        nlohmann::json payload;
+    };
+
+    // 形如真实 token(三段 base64url),只用于测试。
+    std::string token = "OTAwMDAwMDAwMDAwMDAwMDAx.GfakeX.test-token-abcdefghijklmnopqrstuvwxyz0123";
+    std::string bot_id = "900000000000000001";
+    std::string bot_name = "AceBot";
+    std::string application_id = "900000000000000001";
+    std::int64_t application_flags = std::int64_t{1} << 19;  // Message Content Intent(<100 个服务器的开关)
+    int heartbeat_interval_ms = 1000;
+    int gateway_bot_status = 200;           // /gateway/bot 的状态码(可模拟 401)
+    int session_start_remaining = 999;
+    std::atomic<bool> ack_heartbeats{true};
+    std::atomic<int> identify_close_code{0};  // 非 0:收到 Identify 后用这个关闭码断开
+    std::atomic<bool> resume_ok{true};        // false:收到 Resume 时回 op 9(d=false)
+    // 发消息接口的应答;返回 {0, ...} 表示用默认应答。
+    std::function<std::pair<int, nlohmann::json>(const Request&)> message_handler;
+    // 签名“已过期”的附件 id:CDN 对不带 fresh=1 的请求回 404。
+    std::set<std::string> expired_attachments;
+
+    FakeDiscordServer() {
+        CROW_ROUTE(app_, "/api/v10/users/@me")
+        ([this](const crow::request& req) {
+            const auto request = record_request(req, "GET", "/users/@me");
+            if (!authorized(request)) return unauthorized();
+            return json_response(200, {{"id", bot_id}, {"username", bot_name}, {"discriminator", "0"},
+                                       {"global_name", nullptr}, {"bot", true}});
+        });
+        CROW_ROUTE(app_, "/api/v10/applications/@me")
+        ([this](const crow::request& req) {
+            const auto request = record_request(req, "GET", "/applications/@me");
+            if (!authorized(request)) return unauthorized();
+            return json_response(200, {{"id", application_id}, {"name", "Ace App"}, {"bot_public", false},
+                                       {"flags", application_flags}});
+        });
+        CROW_ROUTE(app_, "/api/v10/gateway/bot")
+        ([this](const crow::request& req) {
+            const auto request = record_request(req, "GET", "/gateway/bot");
+            if (!authorized(request)) return unauthorized();
+            if (gateway_bot_status != 200)
+                return json_response(gateway_bot_status, {{"message", "gateway failed"}, {"code", 0}});
+            return json_response(200, {{"url", ws_url("/gateway")},
+                                       {"shards", 1},
+                                       {"session_start_limit",
+                                        {{"total", 1000}, {"remaining", session_start_remaining},
+                                         {"reset_after", 14400000}, {"max_concurrency", 1}}}});
+        });
+        CROW_ROUTE(app_, "/api/v10/users/@me/channels").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto request = record_request(req, "POST", "/users/@me/channels");
+            if (!authorized(request)) return unauthorized();
+            const auto recipient = request.body.value("recipient_id", std::string{});
+            return json_response(200, {{"id", dm_channel_for(recipient)}, {"type", 1},
+                                       {"recipients", nlohmann::json::array({{{"id", recipient}}})}});
+        });
+        CROW_ROUTE(app_, "/api/v10/channels/<string>/messages").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req, const std::string& channel) {
+            const auto request = record_request(req, "POST", "/channels/" + channel + "/messages");
+            if (!authorized(request)) return unauthorized();
+            if (message_handler) {
+                auto reply = message_handler(request);
+                if (reply.first != 0) return json_response(reply.first, reply.second);
+            }
+            nlohmann::json message{{"id", std::to_string(++message_seq_ + 990000000000000000LL)},
+                                   {"channel_id", channel},
+                                   {"content", request.body.value("content", std::string{})},
+                                   {"attachments", nlohmann::json::array()}};
+            if (!request.file_name.empty()) {
+                const auto& declared = request.body.contains("attachments") ? request.body["attachments"]
+                                                                            : nlohmann::json::array();
+                const auto filename = declared.is_array() && !declared.empty()
+                                          ? declared[0].value("filename", request.file_name)
+                                          : request.file_name;
+                message["attachments"].push_back({{"id", "991000000000000001"}, {"filename", filename},
+                                                  {"size", request.file_body.size()}});
+            }
+            return json_response(200, message);
+        });
+        CROW_ROUTE(app_, "/api/v10/channels/<string>/typing").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req, const std::string& channel) {
+            const auto request = record_request(req, "POST", "/channels/" + channel + "/typing");
+            if (!authorized(request)) return unauthorized();
+            return crow::response(204);
+        });
+        CROW_ROUTE(app_, "/api/v10/channels/<string>/messages/<string>")
+        ([this](const crow::request& req, const std::string& channel, const std::string& message) {
+            const auto request = record_request(req, "GET", "/channels/" + channel + "/messages/" + message);
+            if (!authorized(request)) return unauthorized();
+            nlohmann::json attachments = nlohmann::json::array();
+            std::lock_guard<std::mutex> lock(mu_);
+            for (const auto& id : expired_attachments)
+                attachments.push_back({{"id", id}, {"filename", "notes.txt"},
+                                       {"url", cdn_url(channel, id, "notes.txt", true)}});
+            return json_response(200, {{"id", message}, {"channel_id", channel}, {"attachments", attachments}});
+        });
+        CROW_ROUTE(app_, "/cdn/attachments/<string>/<string>/<string>")
+        ([this](const crow::request& req, const std::string& channel, const std::string& id,
+                const std::string& name) {
+            record_request(req, "GET", "/cdn/attachments/" + channel + "/" + id + "/" + name);
+            const bool fresh = req.url_params.get("fresh") != nullptr;
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                if (expired_attachments.count(id) && !fresh) return crow::response(404);
+            }
+            return crow::response(200, std::string(name == "big.bin" ? 4096 : 32, 'd'));
+        });
+        CROW_WEBSOCKET_ROUTE(app_, "/gateway/")
+            .onopen([this](crow::websocket::connection& conn) { opened(conn, "gateway"); })
+            .onclose([this](crow::websocket::connection& conn, const std::string&, std::uint16_t code) {
+                closed(conn, code);
+            })
+            .onmessage([this](crow::websocket::connection& conn, const std::string& data, bool) {
+                message(conn, "gateway", data);
+            });
+        CROW_WEBSOCKET_ROUTE(app_, "/resume/")
+            .onopen([this](crow::websocket::connection& conn) { opened(conn, "resume"); })
+            .onclose([this](crow::websocket::connection& conn, const std::string&, std::uint16_t code) {
+                closed(conn, code);
+            })
+            .onmessage([this](crow::websocket::connection& conn, const std::string& data, bool) {
+                message(conn, "resume", data);
+            });
+        server_ = std::make_unique<CrowTestServer>(app_);
+        port_ = server_->port();
+    }
+
+    ~FakeDiscordServer() { server_.reset(); }
+
+    std::string api_base() const { return server_->http_base() + "/api/v10"; }
+    std::string http_base() const { return server_->http_base(); }
+
+    // 假服务给某个用户分配的私聊频道 id(数字串,形如真实频道 id)。
+    static std::string dm_channel_for(const std::string& user_id) { return "8" + user_id; }
+
+    std::string cdn_url(const std::string& channel, const std::string& id, const std::string& name,
+                        bool fresh = false) const {
+        return server_->http_base() + "/cdn/attachments/" + channel + "/" + id + "/" + name +
+               (fresh ? "?fresh=1&ex=1&is=1&hm=sig" : "?ex=1&is=1&hm=sig");
+    }
+
+    // 推送一条 Dispatch(op 0),seq 自动递增。
+    void push_dispatch(const std::string& type, const nlohmann::json& d) {
+        push({{"op", 0}, {"t", type}, {"s", ++seq_}, {"d", d}});
+    }
+    // 私信:没有 guild_id,channel_type 1。
+    void push_dm(const std::string& id, const std::string& user_id, const std::string& content,
+                 nlohmann::json attachments = nlohmann::json::array()) {
+        push_dispatch("MESSAGE_CREATE",
+                      {{"id", id}, {"channel_id", dm_channel_for(user_id)}, {"channel_type", 1}, {"type", 0},
+                       {"author", {{"id", user_id}, {"username", "alice"}, {"global_name", "Alice"}}},
+                       {"content", content}, {"mentions", nlohmann::json::array()},
+                       {"mention_roles", nlohmann::json::array()}, {"attachments", attachments}});
+    }
+    // 服务器频道消息;extra 里的字段覆盖默认值(mentions、type、referenced_message、author…)。
+    void push_guild(const std::string& id, const std::string& channel, const std::string& user_id,
+                    const std::string& content, const nlohmann::json& extra = nlohmann::json::object()) {
+        nlohmann::json d{{"id", id}, {"channel_id", channel}, {"guild_id", "700000000000000001"},
+                         {"channel_type", 0}, {"type", 0},
+                         {"author", {{"id", user_id}, {"username", "bob"}, {"global_name", "Bob"}}},
+                         {"member", {{"nick", nullptr}, {"roles", nlohmann::json::array()}}},
+                         {"content", content}, {"mentions", nlohmann::json::array()},
+                         {"mention_roles", nlohmann::json::array()}, {"attachments", nlohmann::json::array()}};
+        for (auto it = extra.begin(); it != extra.end(); ++it) d[it.key()] = it.value();
+        push_dispatch("MESSAGE_CREATE", d);
+    }
+    void push(const nlohmann::json& frame) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (conn_) conn_->send_text(frame.dump());
+    }
+    void close_connection(std::uint16_t code, const std::string& reason) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (conn_) conn_->close(reason, code);
+    }
+
+    std::vector<Request> requests() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return requests_;
+    }
+    std::vector<Request> requests_to(const std::string& method, const std::string& path_prefix) {
+        std::vector<Request> out;
+        for (const auto& r : requests())
+            if (r.method == method && r.path.rfind(path_prefix, 0) == 0) out.push_back(r);
+        return out;
+    }
+    std::vector<Frame> frames() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return frames_;
+    }
+    std::vector<nlohmann::json> frames_with_op(int op) {
+        std::vector<nlohmann::json> out;
+        for (const auto& f : frames())
+            if (f.payload.value("op", -1) == op) out.push_back(f.payload);
+        return out;
+    }
+    int connections(const std::string& route) {
+        std::lock_guard<std::mutex> lock(mu_);
+        return route == "resume" ? resume_connections_ : gateway_connections_;
+    }
+    int identify_count() { return static_cast<int>(frames_with_op(2).size()); }
+    std::vector<int> client_close_codes() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return close_codes_;
+    }
+    std::int64_t last_seq() const { return seq_.load(); }
+
+    // 等待条件成立(最多 timeout);条件在锁外求值。
+    static bool wait_until(const std::function<bool()>& predicate,
+                           std::chrono::milliseconds timeout = std::chrono::seconds(5)) {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (std::chrono::steady_clock::now() < deadline) {
+            if (predicate()) return true;
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        }
+        return predicate();
+    }
+
+private:
+    static nlohmann::json parse(const std::string& text) {
+        try {
+            return text.empty() ? nlohmann::json::object() : nlohmann::json::parse(text);
+        } catch (...) {
+            return nlohmann::json::object();
+        }
+    }
+    static crow::response json_response(int status, const nlohmann::json& body) {
+        crow::response res(status, body.dump());
+        res.set_header("Content-Type", "application/json");
+        return res;
+    }
+    static crow::response unauthorized() { return json_response(401, {{"message", "401: Unauthorized"}, {"code", 0}}); }
+
+    bool authorized(const Request& request) const { return request.authorization == "Bot " + token; }
+
+    std::string ws_url(const std::string& path) const { return "ws://127.0.0.1:" + std::to_string(port_) + path; }
+
+    Request record_request(const crow::request& req, const std::string& method, const std::string& path) {
+        Request request;
+        request.method = method;
+        request.path = path;
+        request.authorization = req.get_header_value("Authorization");
+        request.user_agent = req.get_header_value("User-Agent");
+        const auto type = req.get_header_value("Content-Type");
+        if (type.find("multipart/form-data") != std::string::npos) {
+            crow::multipart::message message(req);
+            for (const auto& part : message.parts) {
+                const auto disposition = part.get_header_object("Content-Disposition");
+                const auto name = disposition.params.count("name") ? disposition.params.at("name") : std::string{};
+                request.part_names.push_back(name);
+                if (disposition.params.count("filename")) {
+                    request.file_name = disposition.params.at("filename");
+                    request.file_body = part.body;
+                } else if (name == "payload_json") {
+                    request.body = parse(part.body);
+                }
+            }
+        } else {
+            request.body = parse(req.body);
+        }
+        std::lock_guard<std::mutex> lock(mu_);
+        requests_.push_back(request);
+        return request;
+    }
+
+    void opened(crow::websocket::connection& conn, const std::string& route) {
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            conn_ = &conn;
+            if (route == "resume") ++resume_connections_;
+            else ++gateway_connections_;
+        }
+        conn.send_text(nlohmann::json{{"op", 10}, {"d", {{"heartbeat_interval", heartbeat_interval_ms}}}}.dump());
+    }
+
+    void closed(crow::websocket::connection& conn, std::uint16_t code) {
+        std::lock_guard<std::mutex> lock(mu_);
+        close_codes_.push_back(code);
+        if (conn_ == &conn) conn_ = nullptr;
+    }
+
+    void message(crow::websocket::connection& conn, const std::string& route, const std::string& data) {
+        const auto frame = parse(data);
+        const int op = frame.value("op", -1);
+        int sessions = 0;
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            frames_.push_back({route, frame});
+            if (op == 2) sessions = ++sessions_;
+        }
+        if (op == 1) {
+            if (ack_heartbeats) conn.send_text(R"({"op":11})");
+        } else if (op == 2) {
+            if (const int code = identify_close_code.load(); code != 0) {
+                conn.close("identify rejected", static_cast<std::uint16_t>(code));
+                return;
+            }
+            conn.send_text(nlohmann::json{
+                {"op", 0}, {"t", "READY"}, {"s", ++seq_},
+                {"d",
+                 {{"v", 10},
+                  {"user", {{"id", bot_id}, {"username", bot_name}, {"bot", true}}},
+                  {"guilds", nlohmann::json::array({{{"id", "700000000000000001"}, {"unavailable", true}}})},
+                  {"session_id", "S" + std::to_string(sessions)},
+                  {"resume_gateway_url", ws_url("/resume")},
+                  {"application", {{"id", application_id}, {"flags", application_flags}}}}}}.dump());
+        } else if (op == 6) {
+            if (resume_ok) conn.send_text(nlohmann::json{{"op", 0}, {"t", "RESUMED"}, {"s", ++seq_}, {"d", nullptr}}.dump());
+            else conn.send_text(R"({"op":9,"d":false})");
+        }
+    }
+
+    crow::SimpleApp app_;
+    std::unique_ptr<CrowTestServer> server_;
+    std::uint16_t port_ = 0;
+    std::mutex mu_;
+    crow::websocket::connection* conn_ = nullptr;
+    std::atomic<std::int64_t> seq_{0};
+    std::atomic<long long> message_seq_{0};
+    int sessions_ = 0;
+    int gateway_connections_ = 0;
+    int resume_connections_ = 0;
+    std::vector<int> close_codes_;
+    std::vector<Request> requests_;
+    std::vector<Frame> frames_;
+};
+
+} // namespace acecode::test
diff --git a/tests/test_support/im/fake_feishu_server.hpp b/tests/test_support/im/fake_feishu_server.hpp
new file mode 100644
index 000000000..61ece2815
--- /dev/null
+++ b/tests/test_support/im/fake_feishu_server.hpp
@@ -0,0 +1,356 @@
+#pragma once
+
+// 测试用:本机假飞书开放平台(只监听 127.0.0.1)。提供 tenant_access_token、bot/v3/info、
+// 长连接地址(/callback/ws/endpoint)、二进制 WebSocket 长连接(pbbp2 帧)、发消息 / 回复、
+// 图片与文件上传、消息资源下载,并允许测试注入失败,用于飞书传输层与 API 的端到端测试。
+
+#include "im/feishu/feishu_frame.hpp"
+#include "test_support/network/crow_test_server.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <utility>
+#include <vector>
+
+namespace acecode::test {
+
+class FakeFeishuServer {
+public:
+    struct Request {
+        std::string path;           // 不含查询串
+        std::string query;          // receive_id_type / type 查询参数
+        std::string authorization;
+        std::string user_agent;
+        std::string locale;
+        std::string content_type;
+        std::string raw;            // 原始请求体(multipart 时用来检查字段)
+        nlohmann::json body;        // JSON 请求体(解析失败为空对象)
+    };
+
+    // 应答钩子:返回 (HTTP 状态码, 响应体)。未设置时一律成功。钩子在服务端锁外调用。
+    std::function<std::pair<int, nlohmann::json>(const Request&)> message_handler;
+    std::function<std::pair<int, nlohmann::json>(const Request&)> token_handler;
+    std::function<std::pair<int, nlohmann::json>(const Request&)> endpoint_handler;
+    std::function<std::pair<int, nlohmann::json>(const Request&)> bot_handler;
+    std::function<std::pair<int, nlohmann::json>(const Request&)> upload_handler;
+
+    // 长连接参数:默认重连无抖动、无间隔(测试里由本地退避决定节奏)。
+    nlohmann::json client_config{{"ReconnectCount", -1}, {"ReconnectInterval", 0}, {"ReconnectNonce", 0},
+                                 {"PingInterval", 120}};
+    std::atomic<bool> respond_pings{true};
+    std::string pong_payload;  // 非空时随 pong 下发(新的 ClientConfig)
+    // 加到发消息类响应上的额外响应头(如 x-ogw-ratelimit-reset、X-Tt-Logid);请求开始前设置。
+    std::vector<std::pair<std::string, std::string>> message_headers;
+    std::int32_t service_id = 1234;
+
+    FakeFeishuServer() {
+        CROW_ROUTE(app_, "/open-apis/auth/v3/tenant_access_token/internal").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto request = record(req, "");
+            int calls = 0;
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                calls = ++token_calls_;
+            }
+            if (token_handler) return reply(token_handler(request));
+            return json_response(200, {{"code", 0}, {"msg", "ok"},
+                                       {"tenant_access_token", "t-" + std::to_string(calls)}, {"expire", 7200}});
+        });
+        CROW_ROUTE(app_, "/open-apis/bot/v3/info")
+        ([this](const crow::request& req) {
+            const auto request = record(req, "");
+            if (bot_handler) return reply(bot_handler(request));
+            return json_response(200, {{"code", 0}, {"msg", "ok"},
+                                       {"bot", {{"activate_status", 2}, {"app_name", "TestBot"},
+                                                {"open_id", "ou_bot"}, {"ip_white_list", nlohmann::json::array()}}}});
+        });
+        CROW_ROUTE(app_, "/callback/ws/endpoint").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto request = record(req, "");
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                ++endpoint_calls_;
+            }
+            if (endpoint_handler) return reply(endpoint_handler(request));
+            return json_response(200, {{"code", 0}, {"msg", "ok"},
+                                       {"data", {{"URL", ws_url()}, {"ClientConfig", client_config}}}});
+        });
+        CROW_ROUTE(app_, "/open-apis/im/v1/messages").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            return message(record(req, query_of(req, "receive_id_type")));
+        });
+        CROW_ROUTE(app_, "/open-apis/im/v1/messages/<string>/reply").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req, const std::string&) { return message(record(req, "")); });
+        CROW_ROUTE(app_, "/open-apis/im/v1/images").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto request = record(req, "");
+            if (upload_handler) return reply(upload_handler(request));
+            return json_response(200, {{"code", 0}, {"msg", "success"}, {"data", {{"image_key", "img_v3_up"}}}});
+        });
+        CROW_ROUTE(app_, "/open-apis/im/v1/files").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto request = record(req, "");
+            if (upload_handler) return reply(upload_handler(request));
+            return json_response(200, {{"code", 0}, {"msg", "success"}, {"data", {{"file_key", "file_v3_up"}}}});
+        });
+        CROW_ROUTE(app_, "/open-apis/im/v1/messages/<string>/resources/<string>")
+        ([this](const crow::request& req, const std::string&, const std::string& key) {
+            record(req, query_of(req, "type"));
+            if (key == "gone")
+                return json_response(400, {{"code", 234043}, {"msg", "unsupported message type"}});
+            if (key == "expired") {
+                std::lock_guard<std::mutex> lock(mu_);
+                if (!expired_once_) {
+                    expired_once_ = true;
+                    return json_response(400, {{"code", 99991663}, {"msg", "invalid access token"}});
+                }
+            }
+            crow::response res(200, std::string(key == "big" ? 4096 : 16, 'z'));
+            res.set_header("Content-Type", "image/png");
+            return res;
+        });
+        CROW_WEBSOCKET_ROUTE(app_, "/ws/v2")
+            .onopen([this](crow::websocket::connection& conn) {
+                std::lock_guard<std::mutex> lock(mu_);
+                conn_ = &conn;
+                ++connections_;
+            })
+            .onclose([this](crow::websocket::connection& conn, const std::string&, std::uint16_t code) {
+                std::lock_guard<std::mutex> lock(mu_);
+                if (conn_ == &conn) conn_ = nullptr;
+                close_codes_.push_back(code);
+            })
+            .onmessage([this](crow::websocket::connection& conn, const std::string& data, bool binary) {
+                im::feishu::Frame frame;
+                std::string error;
+                const bool ok = binary && im::feishu::decode_frame(data, &frame, &error);
+                {
+                    std::lock_guard<std::mutex> lock(mu_);
+                    if (!binary) ++text_frames_;
+                    if (ok) frames_.push_back(frame);
+                }
+                if (ok && frame.method == im::feishu::kMethodControl && frame.header("type") == "ping" &&
+                    respond_pings) {
+                    im::feishu::Frame pong = frame;
+                    pong.headers = {{"type", "pong"}};
+                    if (!pong_payload.empty()) pong.payload = pong_payload;
+                    conn.send_binary(im::feishu::encode_frame(pong));
+                }
+            });
+        server_ = std::make_unique<CrowTestServer>(app_);
+        port_ = server_->port();
+    }
+
+    ~FakeFeishuServer() { server_.reset(); }
+
+    std::string base() const { return server_->http_base(); }
+    // 长连接地址:票据放在查询参数里,测试用来确认它不会出现在日志与状态里。
+    std::string ws_url() const {
+        return "ws://127.0.0.1:" + std::to_string(port_) +
+               "/ws/v2?fpid=493&aid=552564&device_id=dev-7&access_key=AK-SECRET&service_id=" +
+               std::to_string(service_id) + "&ticket=TICKET-SECRET";
+    }
+
+    // ---- 推送事件
+
+    static nlohmann::json message_event(const std::string& message_id, const std::string& chat_type,
+                                        const std::string& chat_id, const std::string& sender_open_id,
+                                        const std::string& message_type, const nlohmann::json& content,
+                                        const nlohmann::json& mentions = nullptr, std::int64_t create_time_ms = 0) {
+        if (create_time_ms == 0) {
+            create_time_ms = std::chrono::duration_cast<std::chrono::milliseconds>(
+                                 std::chrono::system_clock::now().time_since_epoch())
+                                 .count();
+        }
+        nlohmann::json message{{"message_id", message_id},
+                               {"create_time", std::to_string(create_time_ms)},
+                               {"chat_id", chat_id},
+                               {"chat_type", chat_type},
+                               {"message_type", message_type},
+                               {"content", content.dump()}};
+        if (!mentions.is_null()) message["mentions"] = mentions;
+        return {{"schema", "2.0"},
+                {"header", {{"event_id", "ev-" + message_id}, {"event_type", "im.message.receive_v1"},
+                            {"create_time", std::to_string(create_time_ms)}, {"app_id", "cli_app"},
+                            {"tenant_key", "tk"}}},
+                {"event", {{"sender", {{"sender_id", {{"open_id", sender_open_id}, {"union_id", "on_x"}}},
+                                       {"sender_type", "user"}, {"tenant_key", "tk"}}},
+                           {"message", message}}}};
+    }
+
+    // 以一个或多个 DATA type=event 帧推送 payload;parts > 1 时按字节平均切开。
+    void push_event(const nlohmann::json& event, int parts = 1) {
+        const auto payload = event.dump();
+        const auto frame_id = "frame-" + std::to_string(++frame_seq_);
+        const auto size = payload.size();
+        for (int seq = 0; seq < parts; ++seq) {
+            const auto begin = size * static_cast<std::size_t>(seq) / static_cast<std::size_t>(parts);
+            const auto end = size * static_cast<std::size_t>(seq + 1) / static_cast<std::size_t>(parts);
+            im::feishu::Frame frame;
+            frame.seq_id = 0;
+            frame.log_id = 0;
+            frame.service = service_id;
+            frame.method = im::feishu::kMethodData;
+            frame.headers = {{"type", "event"},
+                             {"message_id", frame_id},
+                             {"sum", std::to_string(parts)},
+                             {"seq", std::to_string(seq)},
+                             {"trace_id", "trace-" + frame_id},
+                             {"instance_id", "inst-1"}};
+            frame.payload = payload.substr(begin, end - begin);
+            push_frame(frame);
+        }
+    }
+
+    void push_frame(const im::feishu::Frame& frame) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (conn_) conn_->send_binary(im::feishu::encode_frame(frame));
+    }
+
+    void close_connection(std::uint16_t code = 1000) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (conn_) conn_->close("server closing", code);
+    }
+
+    // ---- 观察
+
+    std::vector<Request> requests() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return requests_;
+    }
+    std::vector<Request> requests_to(const std::string& prefix) {
+        std::vector<Request> out;
+        for (const auto& r : requests()) {
+            if (r.path.rfind(prefix, 0) == 0) out.push_back(r);
+        }
+        return out;
+    }
+    // 发消息类请求(创建 + 回复),按到达顺序。
+    std::vector<Request> sends() {
+        std::vector<Request> out;
+        for (const auto& r : requests()) {
+            const bool reply = r.path.size() > 6 && r.path.compare(r.path.size() - 6, 6, "/reply") == 0;
+            if (r.path == "/open-apis/im/v1/messages" || reply) out.push_back(r);
+        }
+        return out;
+    }
+    std::vector<im::feishu::Frame> frames() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return frames_;
+    }
+    std::vector<im::feishu::Frame> frames_of_type(const std::string& type) {
+        std::vector<im::feishu::Frame> out;
+        for (const auto& frame : frames()) {
+            if (frame.header("type") == type) out.push_back(frame);
+        }
+        return out;
+    }
+    int token_calls() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return token_calls_;
+    }
+    int endpoint_calls() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return endpoint_calls_;
+    }
+    int connections() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return connections_;
+    }
+    int text_frames() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return text_frames_;
+    }
+    std::vector<std::uint16_t> close_codes() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return close_codes_;
+    }
+
+    // 等待条件成立(最多 timeout);条件在锁外求值。
+    static bool wait_until(const std::function<bool()>& predicate,
+                           std::chrono::milliseconds timeout = std::chrono::seconds(5)) {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (std::chrono::steady_clock::now() < deadline) {
+            if (predicate()) return true;
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        }
+        return predicate();
+    }
+
+private:
+    static nlohmann::json parse(const std::string& text) {
+        try {
+            const auto json = nlohmann::json::parse(text);
+            return json.is_object() ? json : nlohmann::json::object();
+        } catch (...) {
+            return nlohmann::json::object();
+        }
+    }
+    static std::string query_of(const crow::request& req, const char* key) {
+        const char* value = req.url_params.get(key);
+        return value ? std::string(value) : std::string{};
+    }
+    static crow::response json_response(int status, const nlohmann::json& body) {
+        crow::response res(status, body.dump());
+        res.set_header("Content-Type", "application/json");
+        return res;
+    }
+    static crow::response reply(const std::pair<int, nlohmann::json>& result) {
+        return json_response(result.first, result.second);
+    }
+    Request record(const crow::request& req, const std::string& query) {
+        Request request;
+        request.path = req.url;
+        request.query = query;
+        request.authorization = req.get_header_value("Authorization");
+        request.user_agent = req.get_header_value("User-Agent");
+        request.locale = req.get_header_value("locale");
+        request.content_type = req.get_header_value("Content-Type");
+        request.raw = req.body;
+        request.body = parse(req.body);
+        std::lock_guard<std::mutex> lock(mu_);
+        requests_.push_back(request);
+        return request;
+    }
+    crow::response message(const Request& request) {
+        crow::response res;
+        if (message_handler) {
+            res = reply(message_handler(request));
+        } else {
+            int count = 0;
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                count = ++sent_;
+            }
+            res = json_response(200, {{"code", 0}, {"msg", "success"},
+                                      {"data", {{"message_id", "om_sent_" + std::to_string(count)}}}});
+        }
+        for (const auto& [name, value] : message_headers) res.set_header(name, value);
+        return res;
+    }
+
+    crow::SimpleApp app_;
+    std::unique_ptr<CrowTestServer> server_;
+    std::uint16_t port_ = 0;
+    std::mutex mu_;
+    crow::websocket::connection* conn_ = nullptr;
+    std::atomic<int> frame_seq_{0};
+    int token_calls_ = 0;
+    int endpoint_calls_ = 0;
+    int connections_ = 0;
+    int text_frames_ = 0;
+    int sent_ = 0;
+    bool expired_once_ = false;
+    std::vector<Request> requests_;
+    std::vector<im::feishu::Frame> frames_;
+    std::vector<std::uint16_t> close_codes_;
+};
+
+} // namespace acecode::test
diff --git a/tests/test_support/im/fake_line_server.hpp b/tests/test_support/im/fake_line_server.hpp
new file mode 100644
index 000000000..abd1ada6e
--- /dev/null
+++ b/tests/test_support/im/fake_line_server.hpp
@@ -0,0 +1,433 @@
+#pragma once
+
+// 测试用:本机假 LINE Messaging API(api.line.me 与 api-data.line.me 共用一个地址)
+// 以及假 cloudflared(指标服务 /quicktunnel、/ready + 可注入的假子进程)。
+// 只监听 127.0.0.1,任何测试都不连真实平台。
+//
+// 假 LINE 服务覆盖:无状态令牌换取、/v2/bot/info、webhook 地址读写与测试(真的向登记地址
+// 发一个带签名的空事件请求)、回复(校验回复令牌只能用一次)、推送(记录重试键)、
+// 正在输入动画、配额、用户资料、消息内容下载(含 202 转码、410 撤回)。
+
+#include "im/http.hpp"
+#include "im/line/line_protocol.hpp"
+#include "im/line/line_tunnel.hpp"
+#include "test_support/network/crow_test_server.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <functional>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <set>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace acecode::test {
+
+class FakeLineServer {
+public:
+    struct Call {
+        std::string method;
+        std::string path;
+        nlohmann::json body;  // JSON 请求体;换令牌的表单字段也解析成对象
+        std::string authorization;
+        std::string retry_key;
+    };
+    struct Reply {
+        int status = 200;
+        nlohmann::json body = nlohmann::json::object();
+        std::optional<std::string> raw;  // 非空时按二进制原样返回(消息内容下载)
+    };
+
+    static constexpr const char* kChannelId = "1650000001";
+    // LINE 官方文档签名示例里的 secret。
+    static constexpr const char* kSecret = "8c570fa6dd201bb328f1c1eac23a96d8";
+    static constexpr const char* kBotId = "U0123456789abcdef0123456789abcdef";
+
+    FakeLineServer() {
+        CROW_CATCHALL_ROUTE(app_)([this](const crow::request& req) { return handle(req); });
+        server_ = std::make_unique<CrowTestServer>(app_);
+    }
+    ~FakeLineServer() { server_.reset(); }
+
+    std::string base() const { return server_->http_base(); }
+
+    // 可选:返回值非空时用它应答(在内置处理之前调用)。测试开始前设置。
+    std::function<std::optional<Reply>(const Call&)> override;
+
+    std::string long_lived_token;           // 非空时也接受它作为 Bearer
+    std::atomic<bool> webhook_active{true}; // “Use webhook” 开关
+    std::string test_signing_secret = kSecret;  // webhook 测试请求用的签名密钥
+    int token_expires_in = 900;
+
+    // 发一个回复令牌(模拟 LINE 随 webhook 下发)。
+    std::string issue_reply_token() {
+        std::lock_guard<std::mutex> lock(mu_);
+        const auto token = "rt-" + std::to_string(++next_reply_token_);
+        reply_tokens_.insert(token);
+        return token;
+    }
+    // 让当前所有已发放的无状态令牌失效(模拟平台提前作废)。
+    void revoke_tokens() {
+        std::lock_guard<std::mutex> lock(mu_);
+        tokens_.clear();
+    }
+    void set_content(const std::string& message_id, std::string bytes) {
+        std::lock_guard<std::mutex> lock(mu_);
+        content_[message_id] = std::move(bytes);
+    }
+    void set_endpoint(const std::string& endpoint) {
+        std::lock_guard<std::mutex> lock(mu_);
+        endpoint_ = endpoint;
+    }
+    std::string endpoint() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return endpoint_;
+    }
+    int mint_count() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return mints_;
+    }
+    std::vector<Call> calls() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return calls_;
+    }
+    std::vector<Call> calls_to(const std::string& method, const std::string& path) {
+        std::vector<Call> out;
+        for (const auto& call : calls())
+            if (call.method == method && call.path == path) out.push_back(call);
+        return out;
+    }
+
+    // ---- 构造 webhook ----
+
+    static nlohmann::json source(const std::string& type, const std::string& chat, const std::string& user) {
+        nlohmann::json value{{"type", type}};
+        if (type == "user") value["userId"] = user;
+        if (type == "group") value["groupId"] = chat;
+        if (type == "room") value["roomId"] = chat;
+        if (type != "user" && !user.empty()) value["userId"] = user;
+        return value;
+    }
+    static nlohmann::json text_event(const nlohmann::json& src, const std::string& text, const std::string& message_id,
+                                     const std::string& reply_token, const std::string& event_id,
+                                     const nlohmann::json& extra = nlohmann::json::object()) {
+        nlohmann::json message{{"id", message_id}, {"type", "text"}, {"text", text}, {"quoteToken", "q-" + message_id}};
+        for (auto it = extra.begin(); it != extra.end(); ++it) message[it.key()] = it.value();
+        nlohmann::json event{{"type", "message"},
+                             {"mode", "active"},
+                             {"timestamp", now_ms()},
+                             {"source", src},
+                             {"webhookEventId", event_id},
+                             {"deliveryContext", {{"isRedelivery", false}}},
+                             {"message", message}};
+        if (!reply_token.empty()) event["replyToken"] = reply_token;
+        return event;
+    }
+    static std::string webhook_body(const std::vector<nlohmann::json>& events, const std::string& destination = kBotId) {
+        return nlohmann::json{{"destination", destination}, {"events", events}}.dump();
+    }
+    // 向回调端口发一个带签名的 webhook;secret 为空时不带签名头。
+    static im::HttpResponse post_webhook(const std::string& url, const std::string& body,
+                                         const std::string& secret = kSecret) {
+        im::HttpRequest request;
+        request.method = "POST";
+        request.url = url;
+        request.headers = {{"Content-Type", "application/json; charset=utf-8"}};
+        if (!secret.empty()) request.headers.emplace_back("x-line-signature", im::line::sign_body(body, secret));
+        request.body = body;
+        request.timeout = std::chrono::seconds(10);
+        request.use_proxy = false;
+        return im::http_send(request);
+    }
+    static im::HttpResponse http_get(const std::string& url) {
+        im::HttpRequest request;
+        request.url = url;
+        request.timeout = std::chrono::seconds(10);
+        request.use_proxy = false;
+        return im::http_send(request);
+    }
+
+    static std::int64_t now_ms() {
+        return std::chrono::duration_cast<std::chrono::milliseconds>(
+                   std::chrono::system_clock::now().time_since_epoch())
+            .count();
+    }
+
+    static bool wait_until(const std::function<bool()>& predicate,
+                           std::chrono::milliseconds timeout = std::chrono::seconds(8)) {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (std::chrono::steady_clock::now() < deadline) {
+            if (predicate()) return true;
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        }
+        return predicate();
+    }
+
+private:
+    static crow::response reply(const Reply& r) {
+        if (r.raw) {
+            crow::response res(r.status, *r.raw);
+            res.set_header("Content-Type", "image/jpeg");
+            return res;
+        }
+        crow::response res(r.status, r.body.dump());
+        res.set_header("Content-Type", "application/json");
+        return res;
+    }
+    static Reply error(int status, const std::string& message) { return {status, {{"message", message}}, {}}; }
+
+    static nlohmann::json parse_form(const std::string& body) {
+        nlohmann::json out = nlohmann::json::object();
+        std::size_t start = 0;
+        while (start < body.size()) {
+            auto end = body.find('&', start);
+            if (end == std::string::npos) end = body.size();
+            const auto pair = body.substr(start, end - start);
+            const auto eq = pair.find('=');
+            if (eq != std::string::npos) out[pair.substr(0, eq)] = decode(pair.substr(eq + 1));
+            start = end + 1;
+        }
+        return out;
+    }
+    static std::string decode(const std::string& value) {
+        std::string out;
+        for (std::size_t i = 0; i < value.size(); ++i) {
+            if (value[i] == '%' && i + 2 < value.size()) {
+                out.push_back(static_cast<char>(std::stoi(value.substr(i + 1, 2), nullptr, 16)));
+                i += 2;
+            } else {
+                out.push_back(value[i] == '+' ? ' ' : value[i]);
+            }
+        }
+        return out;
+    }
+
+    bool authorized(const std::string& header) {
+        const std::string prefix = "Bearer ";
+        if (header.compare(0, prefix.size(), prefix) != 0) return false;
+        const auto token = header.substr(prefix.size());
+        std::lock_guard<std::mutex> lock(mu_);
+        return tokens_.count(token) > 0 || (!long_lived_token.empty() && token == long_lived_token);
+    }
+
+    nlohmann::json sent_messages(std::size_t count) {
+        nlohmann::json sent = nlohmann::json::array();
+        std::lock_guard<std::mutex> lock(mu_);
+        for (std::size_t i = 0; i < count; ++i) {
+            const auto id = std::to_string(9000 + ++next_message_);
+            sent.push_back({{"id", id}, {"quoteToken", "sq-" + id}});
+        }
+        return sent;
+    }
+
+    crow::response handle(const crow::request& req) {
+        Call call;
+        call.method = crow::method_name(req.method);
+        call.path = req.url.substr(0, req.url.find('?'));
+        call.authorization = req.get_header_value("Authorization");
+        call.retry_key = req.get_header_value("X-Line-Retry-Key");
+        if (call.path == "/oauth2/v3/token") {
+            call.body = parse_form(req.body);
+        } else {
+            try {
+                call.body = req.body.empty() ? nlohmann::json::object() : nlohmann::json::parse(req.body);
+            } catch (...) {
+                call.body = nlohmann::json::object();
+            }
+        }
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            calls_.push_back(call);
+        }
+        if (override) {
+            if (const auto custom = override(call)) return reply(*custom);
+        }
+        return reply(builtin(call));
+    }
+
+    Reply builtin(const Call& call) {
+        const auto& path = call.path;
+        if (path == "/oauth2/v3/token" && call.method == "POST") {
+            if (call.body.value("grant_type", "") != "client_credentials" ||
+                call.body.value("client_id", "") != kChannelId || call.body.value("client_secret", "") != kSecret)
+                return {400, {{"error", "invalid_client"}, {"error_description", "Invalid 'client_credentials'."}}};
+            std::lock_guard<std::mutex> lock(mu_);
+            const auto token = "stateless-" + std::to_string(++mints_);
+            tokens_.insert(token);
+            return {200, {{"token_type", "Bearer"}, {"access_token", token}, {"expires_in", token_expires_in}}};
+        }
+        if (!authorized(call.authorization)) return error(401, "Authentication failed. Confirm that the access token in the authorization header is valid.");
+        if (path == "/v2/bot/info") {
+            return {200, {{"userId", kBotId}, {"basicId", "@216ruabc"}, {"displayName", "ACE 测试机器人"},
+                          {"chatMode", "bot"}, {"markAsReadMode", "auto"}}};
+        }
+        if (path == "/v2/bot/channel/webhook/endpoint") {
+            std::lock_guard<std::mutex> lock(mu_);
+            if (call.method == "PUT") {
+                endpoint_ = call.body.value("endpoint", std::string{});
+                return {200, nlohmann::json::object()};
+            }
+            if (endpoint_.empty()) return error(404, "Webhook endpoint not found");
+            return {200, {{"endpoint", endpoint_}, {"active", webhook_active.load()}}};
+        }
+        if (path == "/v2/bot/channel/webhook/test") {
+            // 和 LINE 一样:向目标地址发一个带签名的空事件请求,把结果报回来。
+            const auto target = call.body.value("endpoint", endpoint());
+            const auto body = webhook_body({});
+            const auto response = post_webhook(target, body, test_signing_secret);
+            const bool ok = response.status == 200;
+            return {200, {{"success", ok}, {"timestamp", "2026-10-06T00:00:00Z"}, {"statusCode", response.status},
+                          {"reason", ok ? "OK" : (response.status == 0 ? "COULD_NOT_CONNECT" : "ERROR_STATUS_CODE")},
+                          {"detail", std::to_string(response.status)}}};
+        }
+        if (path == "/v2/bot/message/reply") {
+            const auto token = call.body.value("replyToken", std::string{});
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                if (!reply_tokens_.count(token) || used_reply_tokens_.count(token)) return error(400, "Invalid reply token");
+                used_reply_tokens_.insert(token);
+            }
+            return {200, {{"sentMessages", sent_messages(call.body["messages"].size())}}};
+        }
+        if (path == "/v2/bot/message/push") {
+            return {200, {{"sentMessages", sent_messages(call.body["messages"].size())}}};
+        }
+        if (path == "/v2/bot/chat/loading/start") return {202, nlohmann::json::object()};
+        if (path == "/v2/bot/message/quota") return {200, {{"type", "limited"}, {"value", 200}}};
+        if (path == "/v2/bot/message/quota/consumption") return {200, {{"totalUsage", 3}}};
+        if (path.rfind("/v2/bot/profile/", 0) == 0 || path.find("/member/") != std::string::npos)
+            return {200, {{"displayName", "Ann"}, {"userId", path.substr(path.rfind('/') + 1)}}};
+        const std::string content_prefix = "/v2/bot/message/";
+        if (path.rfind(content_prefix, 0) == 0) {
+            const auto rest = path.substr(content_prefix.size());
+            const auto slash = rest.find('/');
+            const auto id = rest.substr(0, slash);
+            const auto tail = slash == std::string::npos ? std::string{} : rest.substr(slash);
+            if (tail == "/content/transcoding") return {200, {{"status", "succeeded"}}};
+            if (tail == "/content") return content(id);
+        }
+        return error(404, "Not found");
+    }
+
+    Reply content(const std::string& id) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (id == "gone") return error(410, "The content is gone");
+        if (id.rfind("transcode", 0) == 0 && !transcoded_.count(id)) {
+            // 第一次请求:还在转码(202,无正文)。
+            transcoded_.insert(id);
+            Reply pending;
+            pending.status = 202;
+            pending.raw = std::string{};
+            return pending;
+        }
+        const auto it = content_.find(id);
+        if (it == content_.end()) return error(404, "not found");
+        Reply ok;
+        ok.raw = it->second;
+        return ok;
+    }
+
+    crow::SimpleApp app_;
+    std::unique_ptr<CrowTestServer> server_;
+    std::mutex mu_;
+    std::vector<Call> calls_;
+    std::set<std::string> tokens_;
+    std::set<std::string> reply_tokens_;
+    std::set<std::string> used_reply_tokens_;
+    std::set<std::string> transcoded_;
+    std::map<std::string, std::string> content_;
+    std::string endpoint_;
+    int mints_ = 0;
+    int next_reply_token_ = 0;
+    int next_message_ = 0;
+};
+
+// 假 cloudflared:指标服务 + 假子进程。launcher() 记录参数,按 --url 里的端口给出主机名
+// (127.0.0.1:<回调端口>,配合 url_scheme = "http" 让公网自检直达回调端口)。
+class FakeCloudflared {
+public:
+    struct State {
+        std::mutex mu;
+        std::vector<std::vector<std::string>> launches;
+        std::string hostname;
+        std::shared_ptr<std::atomic<bool>> current;  // 当前进程是否存活
+        std::atomic<bool> ready{true};
+        std::atomic<bool> fail_launch{false};
+        std::function<std::string(int launch, const std::string& target)> hostname_for;  // 可选
+    };
+
+    class Process final : public im::line::TunnelProcess {
+    public:
+        explicit Process(std::shared_ptr<std::atomic<bool>> alive) : alive_(std::move(alive)) {}
+        bool alive() override { return alive_->load(); }
+        void stop() override { alive_->store(false); }
+
+    private:
+        std::shared_ptr<std::atomic<bool>> alive_;
+    };
+
+    FakeCloudflared() {
+        CROW_ROUTE(app_, "/quicktunnel")([state = state_] {
+            std::lock_guard<std::mutex> lock(state->mu);
+            return crow::response(200, nlohmann::json{{"hostname", state->hostname}}.dump());
+        });
+        CROW_ROUTE(app_, "/ready")([state = state_] {
+            std::lock_guard<std::mutex> lock(state->mu);
+            const bool up = state->ready.load() && state->current && state->current->load();
+            return crow::response(up ? 200 : 503, nlohmann::json{{"status", up ? 200 : 503}}.dump());
+        });
+        server_ = std::make_unique<CrowTestServer>(app_);
+    }
+
+    std::uint16_t metrics_port() const { return server_->port(); }
+    std::shared_ptr<State> state() const { return state_; }
+
+    im::line::TunnelLauncher launcher() const {
+        return [state = state_](const std::vector<std::string>& argv, std::string* error)
+                   -> std::unique_ptr<im::line::TunnelProcess> {
+            if (state->fail_launch.load()) {
+                if (error) *error = "fake launch failure";
+                return nullptr;
+            }
+            std::string target;
+            for (std::size_t i = 0; i + 1 < argv.size(); ++i)
+                if (argv[i] == "--url") target = argv[i + 1];
+            const auto colon = target.rfind(':');
+            const auto port = colon == std::string::npos ? std::string{} : target.substr(colon + 1);
+            auto alive = std::make_shared<std::atomic<bool>>(true);
+            std::lock_guard<std::mutex> lock(state->mu);
+            state->launches.push_back(argv);
+            const int n = static_cast<int>(state->launches.size());
+            state->hostname = state->hostname_for ? state->hostname_for(n, port) : "127.0.0.1:" + port;
+            state->current = alive;
+            return std::make_unique<Process>(alive);
+        };
+    }
+
+    // 模拟 cloudflared 进程意外退出。
+    void kill_current() {
+        std::lock_guard<std::mutex> lock(state_->mu);
+        if (state_->current) state_->current->store(false);
+    }
+    std::size_t launch_count() {
+        std::lock_guard<std::mutex> lock(state_->mu);
+        return state_->launches.size();
+    }
+    std::vector<std::string> last_argv() {
+        std::lock_guard<std::mutex> lock(state_->mu);
+        return state_->launches.empty() ? std::vector<std::string>{} : state_->launches.back();
+    }
+
+private:
+    std::shared_ptr<State> state_ = std::make_shared<State>();
+    crow::SimpleApp app_;
+    std::unique_ptr<CrowTestServer> server_;
+};
+
+} // namespace acecode::test
diff --git a/tests/test_support/im/fake_qq_server.hpp b/tests/test_support/im/fake_qq_server.hpp
new file mode 100644
index 000000000..884b819e2
--- /dev/null
+++ b/tests/test_support/im/fake_qq_server.hpp
@@ -0,0 +1,243 @@
+#pragma once
+
+// 测试用:本机假 QQ 开放平台。提供令牌、/gateway、WebSocket 网关、发消息、上传、
+// 扫码绑定任务等接口,并允许测试注入失败,用于 QQ 传输层与扫码流程的端到端测试。
+
+#include "test_support/network/crow_test_server.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace acecode::test {
+
+class FakeQqServer {
+public:
+    struct Request {
+        std::string path;
+        std::string authorization;
+        nlohmann::json body;
+    };
+
+    // 发消息接口的应答:返回 HTTP 状态码与响应体;默认一律成功。
+    std::function<std::pair<int, nlohmann::json>(const Request&)> message_handler;
+    // 令牌接口的应答;默认返回 tok-N(每次递增)。
+    std::function<nlohmann::json(const nlohmann::json&)> token_handler;
+    // 绑定任务接口的应答;默认 create 返回 task-1,poll 返回 status 1。
+    std::function<nlohmann::json(const nlohmann::json&)> create_bind_handler;
+    std::function<nlohmann::json(const nlohmann::json&)> poll_bind_handler;
+    // 收到 Identify(op 2)后服务端要做的事;默认回 READY。返回 false 表示不回 READY。
+    std::function<bool(const nlohmann::json&)> on_identify;
+    int heartbeat_interval_ms = 1000;
+    int first_gateway_status = 200;  // 可模拟 /gateway 首次失败
+
+    FakeQqServer() {
+        CROW_ROUTE(app_, "/app/getAppAccessToken").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto body = parse(req.body);
+            nlohmann::json reply;
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                ++token_calls_;
+                reply = token_handler ? token_handler(body)
+                                      : nlohmann::json{{"access_token", "tok-" + std::to_string(token_calls_)},
+                                                       {"expires_in", "7200"}};
+            }
+            return json_response(200, reply);
+        });
+        CROW_ROUTE(app_, "/gateway")
+        ([this](const crow::request& req) {
+            record({"/gateway", req.get_header_value("Authorization"), nlohmann::json::object()});
+            std::lock_guard<std::mutex> lock(mu_);
+            if (first_gateway_status != 200) {
+                const int status = first_gateway_status;
+                first_gateway_status = 200;
+                return json_response(status, {{"code", status}, {"message", "gateway failed"}});
+            }
+            return json_response(200, {{"url", "ws://127.0.0.1:" + std::to_string(port_) + "/websocket"}});
+        });
+        CROW_ROUTE(app_, "/v2/users/<string>/messages").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req, const std::string& id) {
+            return message("/v2/users/" + id + "/messages", req);
+        });
+        CROW_ROUTE(app_, "/v2/groups/<string>/messages").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req, const std::string& id) {
+            return message("/v2/groups/" + id + "/messages", req);
+        });
+        CROW_ROUTE(app_, "/v2/users/<string>/files").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req, const std::string& id) {
+            record({"/v2/users/" + id + "/files", req.get_header_value("Authorization"), parse(req.body)});
+            return json_response(200, {{"file_uuid", "F1"}, {"file_info", "INFO-1"}, {"ttl", 3600}});
+        });
+        CROW_ROUTE(app_, "/v2/groups/<string>/files").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req, const std::string& id) {
+            record({"/v2/groups/" + id + "/files", req.get_header_value("Authorization"), parse(req.body)});
+            return json_response(200, {{"file_uuid", "F1"}, {"file_info", "INFO-1"}, {"ttl", 3600}});
+        });
+        CROW_ROUTE(app_, "/download/<string>")
+        ([this](const crow::request& req, const std::string& name) {
+            record({"/download/" + name, req.get_header_value("Authorization"), nlohmann::json::object()});
+            crow::response res(200, std::string(name == "big" ? 4096 : 16, 'z'));
+            return res;
+        });
+        CROW_ROUTE(app_, "/lite/create_bind_task").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto body = parse(req.body);
+            record({"/lite/create_bind_task", "", body});
+            std::lock_guard<std::mutex> lock(mu_);
+            return json_response(200, create_bind_handler ? create_bind_handler(body)
+                                                          : nlohmann::json{{"retcode", 0}, {"data", {{"task_id", "task-1"}}}});
+        });
+        CROW_ROUTE(app_, "/lite/poll_bind_result").methods(crow::HTTPMethod::Post)
+        ([this](const crow::request& req) {
+            const auto body = parse(req.body);
+            record({"/lite/poll_bind_result", "", body});
+            std::lock_guard<std::mutex> lock(mu_);
+            return json_response(200, poll_bind_handler ? poll_bind_handler(body)
+                                                        : nlohmann::json{{"retcode", 0}, {"data", {{"status", 1}}}});
+        });
+        CROW_WEBSOCKET_ROUTE(app_, "/websocket")
+            .onopen([this](crow::websocket::connection& conn) {
+                {
+                    std::lock_guard<std::mutex> lock(mu_);
+                    conn_ = &conn;
+                    ++connections_;
+                }
+                conn.send_text(nlohmann::json{{"op", 10}, {"d", {{"heartbeat_interval", heartbeat_interval_ms}}}}.dump());
+                cv_.notify_all();
+            })
+            .onclose([this](crow::websocket::connection& conn, const std::string&, std::uint16_t) {
+                std::lock_guard<std::mutex> lock(mu_);
+                if (conn_ == &conn) conn_ = nullptr;
+                cv_.notify_all();
+            })
+            .onmessage([this](crow::websocket::connection& conn, const std::string& data, bool) {
+                const auto frame = parse(data);
+                const int op = frame.value("op", -1);
+                {
+                    std::lock_guard<std::mutex> lock(mu_);
+                    frames_.push_back(frame);
+                }
+                cv_.notify_all();
+                if (op == 1) {
+                    conn.send_text(R"({"op":11})");
+                } else if (op == 2) {
+                    if (!on_identify || on_identify(frame)) {
+                        conn.send_text(nlohmann::json{{"op", 0}, {"t", "READY"}, {"s", ++seq_},
+                                                      {"d", {{"session_id", "S1"}, {"user", {{"id", "B1"}, {"username", "TestBot"}}}}}}.dump());
+                    }
+                } else if (op == 6) {
+                    conn.send_text(nlohmann::json{{"op", 0}, {"t", "RESUMED"}, {"s", ++seq_}, {"d", nullptr}}.dump());
+                }
+            });
+        server_ = std::make_unique<CrowTestServer>(app_);
+        port_ = server_->port();
+    }
+
+    ~FakeQqServer() { server_.reset(); }
+
+    std::string base() const { return server_->http_base(); }
+
+    // 向当前连接推送一条单聊消息事件。
+    void push_c2c(const std::string& id, const std::string& openid, const std::string& content,
+                  nlohmann::json attachments = nlohmann::json::array()) {
+        push({{"op", 0}, {"t", "C2C_MESSAGE_CREATE"}, {"s", ++seq_},
+              {"d", {{"id", id}, {"content", content}, {"author", {{"user_openid", openid}}},
+                     {"attachments", attachments}}}});
+    }
+    void push_group_at(const std::string& id, const std::string& group, const std::string& member,
+                       const std::string& content) {
+        push({{"op", 0}, {"t", "GROUP_AT_MESSAGE_CREATE"}, {"s", ++seq_},
+              {"d", {{"id", id}, {"content", content}, {"group_openid", group},
+                     {"author", {{"member_openid", member}}}}}});
+    }
+    void push(const nlohmann::json& frame) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (conn_) conn_->send_text(frame.dump());
+    }
+    void close_connection(std::uint16_t code, const std::string& reason) {
+        std::lock_guard<std::mutex> lock(mu_);
+        if (conn_) conn_->close(reason, code);
+    }
+
+    std::vector<Request> requests() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return requests_;
+    }
+    std::vector<Request> requests_to(const std::string& prefix) {
+        std::vector<Request> out;
+        for (const auto& r : requests()) if (r.path.rfind(prefix, 0) == 0) out.push_back(r);
+        return out;
+    }
+    std::vector<nlohmann::json> frames() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return frames_;
+    }
+    int token_calls() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return token_calls_;
+    }
+    int connections() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return connections_;
+    }
+
+    // 等待条件成立(最多 timeout);条件在锁外求值。
+    static bool wait_until(const std::function<bool()>& predicate,
+                           std::chrono::milliseconds timeout = std::chrono::seconds(5)) {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (std::chrono::steady_clock::now() < deadline) {
+            if (predicate()) return true;
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        }
+        return predicate();
+    }
+
+private:
+    static nlohmann::json parse(const std::string& text) {
+        try {
+            return nlohmann::json::parse(text);
+        } catch (...) {
+            return nlohmann::json::object();
+        }
+    }
+    static crow::response json_response(int status, const nlohmann::json& body) {
+        crow::response res(status, body.dump());
+        res.set_header("Content-Type", "application/json");
+        return res;
+    }
+    crow::response message(const std::string& path, const crow::request& req) {
+        Request request{path, req.get_header_value("Authorization"), parse(req.body)};
+        record(request);
+        std::pair<int, nlohmann::json> reply{200, {{"id", "R" + std::to_string(requests().size())}}};
+        if (message_handler) reply = message_handler(request);
+        return json_response(reply.first, reply.second);
+    }
+    void record(const Request& request) {
+        std::lock_guard<std::mutex> lock(mu_);
+        requests_.push_back(request);
+    }
+
+    crow::SimpleApp app_;
+    std::unique_ptr<CrowTestServer> server_;
+    std::uint16_t port_ = 0;
+    std::mutex mu_;
+    std::condition_variable cv_;
+    crow::websocket::connection* conn_ = nullptr;
+    std::atomic<int> seq_{0};
+    int token_calls_ = 0;
+    int connections_ = 0;
+    std::vector<Request> requests_;
+    std::vector<nlohmann::json> frames_;
+};
+
+} // namespace acecode::test
diff --git a/tests/test_support/im/fake_telegram_server.hpp b/tests/test_support/im/fake_telegram_server.hpp
new file mode 100644
index 000000000..3409ae48c
--- /dev/null
+++ b/tests/test_support/im/fake_telegram_server.hpp
@@ -0,0 +1,183 @@
+#pragma once
+
+// 测试用:本机假 Telegram Bot API(/bot<token>/<method> 与 /file/bot<token>/<dir>/<name>)。
+// getUpdates 支持长轮询等待;各接口可注入失败(409、429、HTML 解析失败等)。
+
+#include "test_support/network/crow_test_server.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <condition_variable>
+#include <deque>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace acecode::test {
+
+class FakeTelegramServer {
+public:
+    struct Call {
+        std::string method;
+        nlohmann::json body;                       // JSON 请求体
+        std::vector<std::string> part_names;       // multipart 字段名
+        std::string file_name;                     // multipart 文件字段的文件名
+        std::string file_body;                     // multipart 文件内容
+    };
+
+    explicit FakeTelegramServer(std::string token = "123456:TEST-TOKEN-abcdefghijklmnopqrstuvwxyz")
+        : token_(std::move(token)) {
+        CROW_ROUTE(app_, "/<string>/<string>").methods(crow::HTTPMethod::Post, crow::HTTPMethod::Get)
+        ([this](const crow::request& req, const std::string& bot, const std::string& method) {
+            if (bot != "bot" + token_) return reply(401, {{"ok", false}, {"error_code", 401}, {"description", "Unauthorized"}});
+            return handle(req, method);
+        });
+        CROW_ROUTE(app_, "/file/<string>/<string>/<string>")
+        ([this](const std::string& bot, const std::string& dir, const std::string& name) {
+            if (bot != "bot" + token_) return crow::response(401);
+            record({"download:" + dir + "/" + name, nlohmann::json::object(), {}, {}, {}});
+            return crow::response(200, std::string(name == "big.bin" ? 4096 : 32, 'd'));
+        });
+        server_ = std::make_unique<CrowTestServer>(app_);
+    }
+
+    ~FakeTelegramServer() {
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            closing_ = true;
+        }
+        cv_.notify_all();
+        server_.reset();
+    }
+
+    std::string base() const { return server_->http_base(); }
+    const std::string& token() const { return token_; }
+
+    // 可选:返回非空 json 表示用它作为该方法的应答(状态码取 error_code,默认 200)。
+    std::function<nlohmann::json(const Call&)> override;
+    bool can_read_all_group_messages = false;
+
+    void push_update(nlohmann::json update) {
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            update["update_id"] = next_update_id_++;
+            updates_.push_back(std::move(update));
+        }
+        cv_.notify_all();
+    }
+    void push_private_text(std::int64_t user_id, const std::string& text, std::int64_t message_id) {
+        push_update({{"message", {{"message_id", message_id},
+                                  {"from", {{"id", user_id}, {"is_bot", false}, {"first_name", "Ann"}}},
+                                  {"chat", {{"id", user_id}, {"type", "private"}}},
+                                  {"text", text}}}});
+    }
+
+    std::vector<Call> calls() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return calls_;
+    }
+    std::vector<Call> calls_to(const std::string& method) {
+        std::vector<Call> out;
+        for (const auto& c : calls()) if (c.method == method) out.push_back(c);
+        return out;
+    }
+
+    static bool wait_until(const std::function<bool()>& predicate,
+                           std::chrono::milliseconds timeout = std::chrono::seconds(5)) {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (std::chrono::steady_clock::now() < deadline) {
+            if (predicate()) return true;
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        }
+        return predicate();
+    }
+
+private:
+    static crow::response reply(int status, const nlohmann::json& body) {
+        crow::response res(status, body.dump());
+        res.set_header("Content-Type", "application/json");
+        return res;
+    }
+    static nlohmann::json ok(const nlohmann::json& result) { return {{"ok", true}, {"result", result}}; }
+
+    void record(const Call& call) {
+        std::lock_guard<std::mutex> lock(mu_);
+        calls_.push_back(call);
+    }
+
+    crow::response handle(const crow::request& req, const std::string& method) {
+        Call call;
+        call.method = method;
+        const auto type = req.get_header_value("Content-Type");
+        if (type.find("multipart/form-data") != std::string::npos) {
+            crow::multipart::message message(req);
+            for (const auto& part : message.parts) {
+                const auto disposition = part.get_header_object("Content-Disposition");
+                const auto name = disposition.params.count("name") ? disposition.params.at("name") : std::string{};
+                call.part_names.push_back(name);
+                if (disposition.params.count("filename")) {
+                    call.file_name = disposition.params.at("filename");
+                    call.file_body = part.body;
+                } else {
+                    call.body[name] = part.body;
+                }
+            }
+        } else {
+            try {
+                call.body = req.body.empty() ? nlohmann::json::object() : nlohmann::json::parse(req.body);
+            } catch (...) {
+                call.body = nlohmann::json::object();
+            }
+        }
+        if (method != "getUpdates") record(call);
+        if (override) {
+            const auto custom = override(call);
+            if (!custom.is_null()) return reply(custom.value("error_code", 200), custom);
+        }
+        if (method == "getMe") {
+            return reply(200, ok({{"id", 8001}, {"is_bot", true}, {"username", "AceTestBot"},
+                                  {"can_read_all_group_messages", can_read_all_group_messages}}));
+        }
+        if (method == "getUpdates") {
+            record(call);
+            const auto offset = call.body.value("offset", std::int64_t{0});
+            const auto timeout = std::min<int>(call.body.value("timeout", 0), 2);
+            std::unique_lock<std::mutex> lock(mu_);
+            auto pending = [&] {
+                for (const auto& u : updates_) if (u["update_id"].get<std::int64_t>() >= offset) return true;
+                return false;
+            };
+            cv_.wait_for(lock, std::chrono::seconds(timeout), [&] { return closing_ || pending(); });
+            nlohmann::json result = nlohmann::json::array();
+            for (const auto& u : updates_) if (u["update_id"].get<std::int64_t>() >= offset) result.push_back(u);
+            return reply(200, ok(result));
+        }
+        if (method == "sendMessage") {
+            return reply(200, ok({{"message_id", 900 + static_cast<int>(calls_to("sendMessage").size())}}));
+        }
+        if (method == "sendChatAction" || method == "deleteWebhook") return reply(200, ok(true));
+        if (method == "getFile") {
+            const auto id = call.body.value("file_id", std::string{});
+            if (id == "too-big") return reply(200, ok({{"file_id", id}, {"file_size", 30 * 1024 * 1024}}));
+            return reply(200, ok({{"file_id", id}, {"file_path", "documents/" + id + ".bin"}, {"file_size", 32}}));
+        }
+        if (method == "sendDocument" || method == "sendPhoto") return reply(200, ok({{"message_id", 950}}));
+        return reply(404, {{"ok", false}, {"error_code", 404}, {"description", "Not Found: method not found"}});
+    }
+
+    std::string token_;
+    crow::SimpleApp app_;
+    std::unique_ptr<CrowTestServer> server_;
+    std::mutex mu_;
+    std::condition_variable cv_;
+    bool closing_ = false;
+    std::int64_t next_update_id_ = 100;
+    std::deque<nlohmann::json> updates_;
+    std::vector<Call> calls_;
+};
+
+} // namespace acecode::test
diff --git a/tests/test_support/im/fake_weixin_server.hpp b/tests/test_support/im/fake_weixin_server.hpp
new file mode 100644
index 000000000..2a3c29f83
--- /dev/null
+++ b/tests/test_support/im/fake_weixin_server.hpp
@@ -0,0 +1,269 @@
+#pragma once
+
+// 测试用:本机假微信 iLink 服务。
+//   /ilink/bot/get_bot_qrcode、get_qrcode_status(扫码登录,未鉴权 GET)
+//   /ilink/bot/getupdates(长轮询,游标 "cur-<seq>")、sendmessage、sendtyping、getconfig、getuploadurl
+//   /c2c/upload(媒体 CDN 上传,响应头 x-encrypted-param)、/c2c/download(按 encrypted_query_param 取内容)
+// 鉴权接口要求 Authorization: Bearer <token>,否则与真实平台一样返回 HTTP 200 + {"errcode":-14}。
+// 响应 Content-Type 与真实平台一致是 application/octet-stream。
+
+#include "test_support/network/crow_test_server.hpp"
+
+#include <nlohmann/json.hpp>
+
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <deque>
+#include <functional>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace acecode::test {
+
+class FakeWeixinServer {
+public:
+    struct Call {
+        std::string endpoint;                       // getupdates / sendmessage / cdn_upload / get_bot_qrcode …
+        std::string method;                         // GET / POST
+        std::map<std::string, std::string> headers; // 关心的几个请求头
+        std::map<std::string, std::string> query;   // 关心的几个查询参数(已解码)
+        nlohmann::json body = nlohmann::json::object();
+        std::string raw;                            // 原始请求体(CDN 上传的密文)
+    };
+
+    explicit FakeWeixinServer(std::string token = "wx-bot-token-ABCDEFGHIJKLMNOPQRSTUV")
+        : token_(std::move(token)) {
+        CROW_ROUTE(app_, "/ilink/bot/<string>").methods(crow::HTTPMethod::Get, crow::HTTPMethod::Post)
+        ([this](const crow::request& req, const std::string& endpoint) { return handle_api(req, endpoint); });
+        CROW_ROUTE(app_, "/c2c/<string>").methods(crow::HTTPMethod::Get, crow::HTTPMethod::Post)
+        ([this](const crow::request& req, const std::string& endpoint) { return handle_cdn(req, endpoint); });
+        server_ = std::make_unique<CrowTestServer>(app_);
+    }
+
+    ~FakeWeixinServer() {
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            closing_ = true;
+        }
+        cv_.notify_all();
+        server_.reset();
+    }
+
+    std::string base() const { return server_->http_base(); }
+    std::string host() const { return "127.0.0.1:" + std::to_string(server_->port()); }
+    std::string cdn_base() const { return base() + "/c2c"; }
+    const std::string& token() const { return token_; }
+
+    // 可选:返回非 null 的 json 表示用它作为该接口的应答(HTTP 状态取 "_http",默认 200)。
+    std::function<nlohmann::json(const Call&)> override;
+    // 扫码:申请二维码与查询状态的应答;为空时用默认(qr-N / 一直 wait)。
+    std::function<nlohmann::json(const Call&)> qr_handler;
+    std::function<nlohmann::json(const Call&)> qr_status_handler;
+    // CDN 上传前几次返回的 HTTP 状态(用来模拟 5xx / 4xx);用完后正常应答。
+    std::deque<int> cdn_upload_failures;
+    std::chrono::milliseconds max_hold{300};  // getupdates 没有新消息时最多挂起多久
+    std::int64_t longpolling_timeout_ms = 300;
+
+    void push_message(nlohmann::json message) {
+        {
+            std::lock_guard<std::mutex> lock(mu_);
+            if (!message.contains("seq")) message["seq"] = ++next_seq_;
+            else next_seq_ = std::max<std::int64_t>(next_seq_, message["seq"].get<std::int64_t>());
+            messages_.push_back(std::move(message));
+        }
+        cv_.notify_all();
+    }
+
+    static nlohmann::json text_message(const std::string& from, const std::string& text, std::uint64_t message_id,
+                                       const std::string& context_token = "ctx-1") {
+        return {{"message_id", message_id},
+                {"from_user_id", from},
+                {"to_user_id", "e06c1ceea05e@im.bot"},
+                {"create_time_ms", static_cast<std::int64_t>(1759712345000) + static_cast<std::int64_t>(message_id % 100000)},
+                {"message_type", 1},
+                {"message_state", 2},
+                {"context_token", context_token},
+                {"item_list", nlohmann::json::array({{{"type", 1}, {"text_item", {{"text", text}}}}})}};
+    }
+
+    void push_text(const std::string& from, const std::string& text, std::uint64_t message_id,
+                   const std::string& context_token = "ctx-1") {
+        push_message(text_message(from, text, message_id, context_token));
+    }
+
+    // CDN 下载内容(按 encrypted_query_param 查找)。
+    void put_blob(const std::string& query_param, std::string bytes) {
+        std::lock_guard<std::mutex> lock(mu_);
+        blobs_[query_param] = std::move(bytes);
+    }
+
+    std::vector<Call> calls() {
+        std::lock_guard<std::mutex> lock(mu_);
+        return calls_;
+    }
+    std::vector<Call> calls_to(const std::string& endpoint) {
+        std::vector<Call> out;
+        for (const auto& call : calls())
+            if (call.endpoint == endpoint) out.push_back(call);
+        return out;
+    }
+
+    static bool wait_until(const std::function<bool()>& predicate,
+                           std::chrono::milliseconds timeout = std::chrono::seconds(5)) {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        while (std::chrono::steady_clock::now() < deadline) {
+            if (predicate()) return true;
+            std::this_thread::sleep_for(std::chrono::milliseconds(20));
+        }
+        return predicate();
+    }
+
+private:
+    static crow::response reply(int status, const nlohmann::json& body) {
+        crow::response res(status, body.dump());
+        res.set_header("Content-Type", "application/octet-stream");
+        return res;
+    }
+
+    static Call describe(const crow::request& req, const std::string& endpoint) {
+        Call call;
+        call.endpoint = endpoint;
+        call.method = req.method == crow::HTTPMethod::Post ? "POST" : "GET";
+        for (const char* name : {"Authorization", "AuthorizationType", "X-WECHAT-UIN", "iLink-App-Id",
+                                 "iLink-App-ClientVersion", "Content-Type"}) {
+            const auto value = req.get_header_value(name);
+            if (!value.empty()) call.headers[name] = value;
+        }
+        for (const char* name : {"qrcode", "bot_type", "encrypted_query_param", "filekey", "verify_code"}) {
+            if (const char* value = req.url_params.get(name)) call.query[name] = value;
+        }
+        call.raw = req.body;
+        if (call.method == "POST" && endpoint.rfind("cdn_", 0) != 0) {
+            try {
+                call.body = req.body.empty() ? nlohmann::json::object() : nlohmann::json::parse(req.body);
+            } catch (...) {
+                call.body = nlohmann::json::object();
+            }
+        }
+        return call;
+    }
+
+    void record(const Call& call) {
+        std::lock_guard<std::mutex> lock(mu_);
+        calls_.push_back(call);
+    }
+
+    crow::response handle_api(const crow::request& req, const std::string& endpoint) {
+        const auto call = describe(req, endpoint);
+        record(call);
+        // 测试注入的处理函数在锁外调用,它们可以再查询本服务的记录。
+        if (endpoint == "get_bot_qrcode") {
+            int count = 0;
+            {
+                std::lock_guard<std::mutex> lock(mu_);
+                count = ++qr_count_;
+            }
+            if (qr_handler) return reply(200, qr_handler(call));
+            const auto code = "qr-" + std::to_string(count);
+            return reply(200, {{"qrcode", code},
+                               {"qrcode_img_content",
+                                "https://liteapp.weixin.qq.com/q/7GiQu1?qrcode=" + code + "&bot_type=3"},
+                               {"ret", 0}});
+        }
+        if (endpoint == "get_qrcode_status") {
+            if (qr_status_handler) return reply(200, qr_status_handler(call));
+            return reply(200, {{"ret", 0}, {"status", "wait"}});
+        }
+        if (call.headers.count("Authorization") == 0 || call.headers.at("Authorization") != "Bearer " + token_)
+            return reply(200, {{"errcode", -14}, {"errmsg", "session timeout"}});
+        if (override) {
+            const auto custom = override(call);
+            if (!custom.is_null()) return reply(custom.value("_http", 200), custom);
+        }
+        if (endpoint == "getupdates") return get_updates(call);
+        if (endpoint == "sendmessage") return reply(200, {{"ret", 0}});
+        if (endpoint == "sendtyping") return reply(200, {{"ret", 0}, {"errmsg", ""}});
+        if (endpoint == "getconfig") return reply(200, {{"ret", 0}, {"errmsg", ""}, {"typing_ticket", "ticket-1"}});
+        if (endpoint == "getuploadurl") {
+            std::lock_guard<std::mutex> lock(mu_);
+            return reply(200, {{"ret", 0}, {"upload_param", "up-" + std::to_string(++upload_count_)},
+                               {"thumb_upload_param", ""}});
+        }
+        return reply(404, {{"ret", -1}, {"errmsg", "not found"}});
+    }
+
+    crow::response get_updates(const Call& call) {
+        const auto cursor = call.body.value("get_updates_buf", std::string{});
+        const std::int64_t after = cursor.rfind("cur-", 0) == 0 ? std::stoll(cursor.substr(4)) : 0;
+        std::unique_lock<std::mutex> lock(mu_);
+        auto pending = [this, after] {
+            for (const auto& m : messages_)
+                if (m["seq"].get<std::int64_t>() > after) return true;
+            return false;
+        };
+        cv_.wait_for(lock, max_hold, [this, &pending] { return closing_ || pending(); });
+        nlohmann::json msgs = nlohmann::json::array();
+        std::int64_t last = after;
+        for (const auto& m : messages_) {
+            const auto seq = m["seq"].get<std::int64_t>();
+            if (seq > after) {
+                msgs.push_back(m);
+                last = std::max(last, seq);
+            }
+        }
+        return reply(200, {{"ret", 0},
+                           {"msgs", msgs},
+                           {"get_updates_buf", last > 0 ? "cur-" + std::to_string(last) : cursor},
+                           {"longpolling_timeout_ms", longpolling_timeout_ms}});
+    }
+
+    crow::response handle_cdn(const crow::request& req, const std::string& name) {
+        auto call = describe(req, "cdn_" + name);
+        record(call);
+        std::lock_guard<std::mutex> lock(mu_);
+        if (name == "upload") {
+            if (req.method != crow::HTTPMethod::Post) return crow::response(404);
+            if (!cdn_upload_failures.empty()) {
+                const int status = cdn_upload_failures.front();
+                cdn_upload_failures.pop_front();
+                crow::response res(status);
+                res.set_header("x-error-message", "injected failure");
+                return res;
+            }
+            const auto param = "enc-" + std::to_string(++encrypted_count_);
+            blobs_[param] = req.body;
+            crow::response res(200);
+            res.set_header("x-encrypted-param", param);
+            return res;
+        }
+        if (name == "download") {
+            const auto it = blobs_.find(call.query["encrypted_query_param"]);
+            if (it == blobs_.end()) return crow::response(404);
+            crow::response res(200, it->second);
+            res.set_header("Content-Type", "application/octet-stream");
+            return res;
+        }
+        return crow::response(404);
+    }
+
+    std::string token_;
+    crow::SimpleApp app_;
+    std::unique_ptr<CrowTestServer> server_;
+    std::mutex mu_;
+    std::condition_variable cv_;
+    bool closing_ = false;
+    std::int64_t next_seq_ = 0;
+    int qr_count_ = 0;
+    int upload_count_ = 0;
+    int encrypted_count_ = 0;
+    std::deque<nlohmann::json> messages_;
+    std::map<std::string, std::string> blobs_;
+    std::vector<Call> calls_;
+};
+
+} // namespace acecode::test
diff --git a/tests/test_support/network/crow_test_server.hpp b/tests/test_support/network/crow_test_server.hpp
new file mode 100644
index 000000000..d2bbd1326
--- /dev/null
+++ b/tests/test_support/network/crow_test_server.hpp
@@ -0,0 +1,39 @@
+#pragma once
+
+// 测试用:在 127.0.0.1 的随机端口上运行一个 Crow 应用,析构时停止。
+// 用于 WebSocket 客户端、QQ 假网关、Telegram 假 Bot API 等本机端到端测试。
+
+#include <crow.h>
+
+#include <chrono>
+#include <cstdint>
+#include <future>
+#include <string>
+
+namespace acecode::test {
+
+class CrowTestServer {
+public:
+    explicit CrowTestServer(crow::SimpleApp& app) : app_(app) {
+        app_.loglevel(crow::LogLevel::Warning);
+        app_.bindaddr("127.0.0.1").port(0).concurrency(2).signal_clear();
+        future_ = app_.run_async();
+        app_.wait_for_server_start(std::chrono::seconds(5));
+    }
+    ~CrowTestServer() {
+        app_.stop();
+        if (future_.valid()) future_.wait();
+    }
+    CrowTestServer(const CrowTestServer&) = delete;
+    CrowTestServer& operator=(const CrowTestServer&) = delete;
+
+    std::uint16_t port() const { return app_.port(); }
+    std::string http_base() const { return "http://127.0.0.1:" + std::to_string(port()); }
+    std::string ws_base() const { return "ws://127.0.0.1:" + std::to_string(port()); }
+
+private:
+    crow::SimpleApp& app_;
+    std::future<void> future_;
+};
+
+} // namespace acecode::test
diff --git a/tests/web/channels_handler_test.cpp b/tests/web/channels_handler_test.cpp
new file mode 100644
index 000000000..f09387b03
--- /dev/null
+++ b/tests/web/channels_handler_test.cpp
@@ -0,0 +1,79 @@
+#include <gtest/gtest.h>
+
+#include "web/handlers/channels_handler.hpp"
+
+// web/handlers/channels_handler:消息通道 REST 接口的请求校验与会话列表标注(纯函数)。
+
+namespace acecode::web {
+namespace {
+
+using nlohmann::json;
+
+// 场景:开关请求体分别是正确的布尔值、字符串、缺字段、不是对象。
+// 期望:只有 {"enabled": bool} 被接受,其余返回中文错误。
+TEST(ChannelsHandler, EnabledRequestNeedsBoolean) {
+    bool enabled = false;
+    std::string error;
+    EXPECT_TRUE(parse_channel_enabled_request(json{{"enabled", true}}, enabled, error));
+    EXPECT_TRUE(enabled);
+    EXPECT_FALSE(parse_channel_enabled_request(json{{"enabled", "yes"}}, enabled, error));
+    EXPECT_FALSE(error.empty());
+    EXPECT_FALSE(parse_channel_enabled_request(json::object(), enabled, error));
+    EXPECT_FALSE(parse_channel_enabled_request(json::array(), enabled, error));
+}
+
+// 场景:QQ 手动填写凭据:两端带空白、只改其中一个字段、混入未知字段、全部为空。
+// 期望:去空白后返回;空字符串字段省略(沿用已保存的值);未知字段与全空都被拒绝。
+TEST(ChannelsHandler, QqCredentialsAreTrimmedAndRestricted) {
+    std::string error;
+    const auto both = parse_channel_credentials_request("qq", json{{"app_id", " 1020 "}, {"app_secret", "s3cret\n"}},
+                                                        error);
+    ASSERT_TRUE(both.has_value()) << error;
+    EXPECT_EQ(both->value("app_id", ""), "1020");
+    EXPECT_EQ(both->value("app_secret", ""), "s3cret");
+
+    const auto only_id = parse_channel_credentials_request("qq", json{{"app_id", "1020"}, {"app_secret", ""}}, error);
+    ASSERT_TRUE(only_id.has_value()) << error;
+    EXPECT_FALSE(only_id->contains("app_secret"));
+
+    EXPECT_FALSE(parse_channel_credentials_request("qq", json{{"token", "x"}}, error).has_value());
+    EXPECT_FALSE(parse_channel_credentials_request("qq", json{{"app_id", "  "}}, error).has_value());
+    EXPECT_FALSE(parse_channel_credentials_request("qq", json{{"app_id", 1020}}, error).has_value());
+}
+
+// 场景:Telegram token 过长,或请求体不是对象。
+// 期望:拒绝并给出原因。
+TEST(ChannelsHandler, TelegramTokenLengthIsLimited) {
+    std::string error;
+    EXPECT_TRUE(parse_channel_credentials_request("telegram", json{{"token", "100:abc"}}, error).has_value());
+    EXPECT_FALSE(
+        parse_channel_credentials_request("telegram", json{{"token", std::string(600, 'a')}}, error).has_value());
+    EXPECT_FALSE(parse_channel_credentials_request("telegram", json("100:abc"), error).has_value());
+}
+
+// 场景:撤销授权的路径参数:百分号编码的 QQ 群成员身份、未编码的用户身份、未知前缀、坏编码。
+// 期望:解码后符合 user:/group:/member: 前缀的才接受。
+TEST(ChannelsHandler, PrincipalPathSegmentIsDecodedAndValidated) {
+    EXPECT_EQ(decode_channel_principal("member%3AG1%3AM1").value_or(""), "member:G1:M1");
+    EXPECT_EQ(decode_channel_principal("user:123").value_or(""), "user:123");
+    EXPECT_EQ(decode_channel_principal("group%3A-100").value_or(""), "group:-100");
+    EXPECT_FALSE(decode_channel_principal("admin").has_value());
+    EXPECT_FALSE(decode_channel_principal("user%3").has_value());
+    EXPECT_FALSE(decode_channel_principal("user%3A%00x").has_value());
+    EXPECT_FALSE(decode_channel_principal("").has_value());
+}
+
+// 场景:会话列表三行,其中一行被 QQ 绑定。
+// 期望:只有那一行加 channel_bound:{platform:"qq"},其它行不加字段。
+TEST(ChannelsHandler, AnnotatesOnlyBoundSessions) {
+    json rows = json::array({{{"id", "a"}}, {{"id", "b"}}, {{"title", "无 id"}}});
+    annotate_channel_bound(rows, {{"b", "qq"}});
+    EXPECT_FALSE(rows[0].contains("channel_bound"));
+    EXPECT_EQ(rows[1]["channel_bound"].value("platform", ""), "qq");
+    EXPECT_FALSE(rows[2].contains("channel_bound"));
+    EXPECT_TRUE(is_channel_platform("telegram"));
+    EXPECT_FALSE(is_channel_platform("whatsapp"));  // WhatsApp 不归消息通道页面管理
+}
+
+} // namespace
+} // namespace acecode::web
diff --git a/tests/web/desktop_office_route_test.cpp b/tests/web/desktop_office_route_test.cpp
new file mode 100644
index 000000000..fb5628309
--- /dev/null
+++ b/tests/web/desktop_office_route_test.cpp
@@ -0,0 +1,155 @@
+#include <gtest/gtest.h>
+#include <cpr/cpr.h>
+#include "web/server.hpp"
+#include "desktop/daemon_supervisor.hpp"
+#include "workspace/workspace_registry.hpp"
+#include "session_host/local_session_client.hpp"
+#include "session_host/session_registry.hpp"
+#include "test_support/agent/stub_provider.hpp"
+#include "test_support/memory/memory_test_home.hpp"
+#include "utils/joining_thread.hpp"
+#include "utils/cwd_hash.hpp"
+#include "utils/paths.hpp"
+#include <chrono>
+#include <filesystem>
+#include <thread>
+
+using namespace acecode;
+using nlohmann::json;
+using namespace std::chrono_literals;
+namespace {
+class DesktopOfficeHttp : public testing::Test {
+protected:
+    acecode_test::MemoryTestHome home{"office-http"};
+    std::string cwd = home.workspace_cwd("main");
+    std::string projects = (home.root() / ".acecode" / "projects").string();
+    AppConfig cfg;
+    ToolExecutor tools;
+    desktop::WorkspaceRegistry workspaces;
+    std::unique_ptr<SessionRegistry> registry;
+    std::unique_ptr<LocalSessionClient> client;
+    std::unique_ptr<web::WebServer> server;
+    JoiningThread worker; // Joined before the server and its dependencies disappear.
+
+    void SetUp() override {
+        cfg.web.bind = "127.0.0.1";
+        cfg.web.port = desktop::pick_free_loopback_port();
+        workspaces.register_new(projects, cwd);
+        SessionRegistryDeps sessions;
+        sessions.cwd = cwd; sessions.tools = &tools;
+        // Shared with the registry's provider accessor for the fixture lifetime.
+        auto provider = std::make_shared<acecode_test::StubLlmProvider>();
+        provider->push_text("complete");
+        sessions.provider_accessor = [provider] { return provider; };
+        registry = std::make_unique<SessionRegistry>(std::move(sessions));
+        client = std::make_unique<LocalSessionClient>(*registry);
+        web::WebServerDeps deps;
+        deps.web_cfg = &cfg.web; deps.app_config = &cfg; deps.cwd = cwd;
+        deps.config_path = (home.root() / "config.json").string();
+        deps.sync_model_reasoning = false; deps.token = "office-fixture";
+        deps.projects_dir = projects; deps.workspace_registry = &workspaces;
+        deps.session_client = client.get(); deps.session_registry = registry.get();
+        server = std::make_unique<web::WebServer>(std::move(deps));
+        worker = JoiningThread([this] { server->run(); });
+        const auto deadline = std::chrono::steady_clock::now() + 3s;
+        while (std::chrono::steady_clock::now() < deadline) {
+            if (cpr::Get(cpr::Url{url("/api/health")}, cpr::Timeout{200}).status_code == 200) return;
+            std::this_thread::sleep_for(10ms);
+        }
+        FAIL() << "office HTTP server did not start";
+    }
+    void TearDown() override {
+        if (server) server->stop();
+        worker.join(); server.reset(); client.reset(); registry.reset();
+    }
+    std::string url(const std::string& path) const {
+        return "http://127.0.0.1:" + std::to_string(cfg.web.port) + path;
+    }
+    json snapshot(const std::string& id = {}) {
+        json result;
+        const auto deadline = std::chrono::steady_clock::now() + 3s;
+        do {
+            const auto response = cpr::Get(cpr::Url{url("/api/desktop-office")},
+                cpr::Parameters{{"session", id}}, cpr::Timeout{2000});
+            EXPECT_EQ(response.status_code, 200) << response.text;
+            if (response.status_code != 200) return {};
+            result = json::parse(response.text);
+            if (result.value("complete", false)) return result;
+            std::this_thread::sleep_for(10ms);
+        } while (std::chrono::steady_clock::now() < deadline);
+        ADD_FAILURE() << "office catalog did not settle";
+        return result;
+    }
+    std::string active(const std::string& parent = {}, bool no_workspace = false) {
+        SessionOptions opts;
+        opts.cwd = cwd; opts.parent_session_id = parent; opts.no_workspace = no_workspace;
+        if (!parent.empty()) opts.subagent_depth = 1;
+        const auto id = registry->create(opts);
+        auto entry = registry->acquire(id);
+        ChatMessage message; message.role = "user"; message.content = "test input";
+        message.timestamp = "2026-10-06T10:00:00Z";
+        entry->sm->on_message(message);
+        return id;
+    }
+};
+} // namespace
+
+TEST_F(DesktopOfficeHttp, EmptyAndAuthenticationAndMissingSession) {
+    const auto empty = snapshot();
+    ASSERT_TRUE(empty.contains("offices"));
+    EXPECT_TRUE(empty["offices"].empty());
+    EXPECT_TRUE(empty["selected"].is_null());
+    EXPECT_TRUE(empty["agents"].empty());
+    const auto denied = cpr::Get(cpr::Url{url("/api/desktop-office")},
+        cpr::Header{{"Origin", "https://untrusted.invalid"}});
+    EXPECT_NE(denied.status_code, 200);
+    const auto missing = cpr::Get(cpr::Url{url("/api/desktop-office?session=missing")});
+    EXPECT_EQ(missing.status_code, 404);
+    EXPECT_EQ(cpr::Options(cpr::Url{url("/api/desktop-office")}).status_code, 204);
+}
+
+TEST_F(DesktopOfficeHttp, SnapshotCarriesRealRuntimeAndRoutesMeshChildToRoot) {
+    const auto root = active();
+    const auto child = active(root);
+    auto entry = registry->acquire(root);
+    auto worker_entry = registry->acquire(child);
+    entry->loop->events().emit(SessionEventKind::BusyChanged, {{"busy", true}, {"turn_id", "root-turn"}});
+    worker_entry->loop->events().emit(SessionEventKind::BusyChanged, {{"busy", true}});
+    worker_entry->loop->events().emit(SessionEventKind::ToolStart, {{"tool", "file_read"}, {"tool_call_id", "read-1"}});
+    worker_entry->loop->events().emit(SessionEventKind::PermissionRequest, {{"request_id", "permission-1"}});
+    auto result = snapshot(child);
+    ASSERT_EQ(result["selected"]["id"], root);
+    ASSERT_EQ(result["offices"].size(), 1u);
+    ASSERT_EQ(result["agents"].size(), 2u);
+    EXPECT_EQ(result["agents"][1]["activity"]["phase"], "permission_waiting");
+    EXPECT_EQ(result["agents"][1]["activity"]["tool"], "file_read");
+    entry->loop->events().emit(SessionEventKind::Done, {{"outcome", "completed"}});
+    worker_entry->loop->events().emit(SessionEventKind::Done, {{"outcome", "aborted"}});
+    result = snapshot(root);
+    EXPECT_EQ(result["selected"]["activity"]["outcome"], "completed");
+    EXPECT_EQ(result["agents"][1]["activity"]["outcome"], "aborted");
+    EXPECT_FALSE(result["selected"].contains("input_draft"));
+    EXPECT_FALSE(result["selected"].contains("session_path"));
+}
+
+TEST_F(DesktopOfficeHttp, HiddenWorkspaceAndNoWorkspaceAreSelectable) {
+    const auto hidden_cwd = home.workspace_cwd("not-in-sidebar");
+    const auto directory = SessionStorage::get_project_dir(hidden_cwd);
+    std::filesystem::create_directories(directory);
+    SessionMeta meta;
+    meta.id = "20261006-110000-aabb"; meta.cwd = hidden_cwd; meta.title = "Hidden office";
+    meta.created_at = "2026-10-06T11:00:00Z"; meta.updated_at = meta.created_at;
+    meta.last_user_message_at = meta.created_at; meta.last_turn_outcome = "completed";
+    meta.last_token_usage.prompt_tokens = 1200; meta.last_token_usage.has_data = true;
+    ASSERT_TRUE(SessionStorage::write_meta(SessionStorage::meta_path(directory, meta.id), meta));
+    auto result = snapshot();
+    ASSERT_EQ(result["offices"].size(), 1u);
+    EXPECT_EQ(result["selected"]["id"], meta.id);
+    EXPECT_EQ(result["selected"]["token_usage"]["prompt_tokens"], 1200);
+    EXPECT_EQ(result["selected"]["last_turn_outcome"], "completed");
+    const auto unbound = active({}, true);
+    result = snapshot(unbound);
+    EXPECT_EQ(result["selected"]["id"], unbound);
+    EXPECT_EQ(result["selected"]["workspace_hash"], "");
+    EXPECT_TRUE(result["selected"]["no_workspace"].get<bool>());
+}
diff --git a/tests/web/web_server_smoke_test.cpp b/tests/web/web_server_smoke_test.cpp
index d55c532e8..a273c626e 100644
--- a/tests/web/web_server_smoke_test.cpp
+++ b/tests/web/web_server_smoke_test.cpp
@@ -77,6 +77,9 @@
 #include "utils/text_file_buffer.hpp"
 #include "utils/utf8_path.hpp"
 #include "web/handlers/fs_browser_handler.hpp"
+#include "web/handlers/channels_handler.hpp"
+#include "channels/core/host.hpp"
+#include "test_support/channels/core_fakes.hpp"
 #include "web/remote_web_proxy.hpp"
 #include "agent/event_payload/message_payload.hpp"
 #include "web/server.hpp"
@@ -497,6 +500,13 @@ struct WebServerFixture {
     std::unique_ptr<FakeRemoteWebProxyController> remote_web_proxy;
     std::unique_ptr<acecode::web::WebServer> server;
     std::unique_ptr<acecode::PtySessionRegistry> pty_registry;
+    // 消息通道宿主:每个夹具都接上(未 start 时不建线程、不读盘),通道用例里再 start。
+    // 传输层是假的,凭据校验对 token "bad:token" 失败。
+    std::shared_ptr<acecode::channels::core::Broadcast> channel_broadcast =
+        std::make_shared<acecode::channels::core::Broadcast>();
+    std::unique_ptr<acecode::channels::core::ChannelHost> channel_host;
+    std::mutex channel_mu;
+    std::vector<std::shared_ptr<acecode::channels::core::test::FakeTransport>> channel_transports;
 
     std::thread server_thread;
     int port = 0;
@@ -661,7 +671,41 @@ struct WebServerFixture {
             wdeps.pty_registry = pty_registry.get();
         }
 
+        {
+            acecode::channels::core::HostServices channel_services;
+            channel_services.conversation.sessions = client.get();
+            channel_services.conversation.session_cwd = [this](const std::string& id) {
+                auto entry = registry->acquire(id);
+                return entry ? entry->cwd : std::string{};
+            };
+            channel_services.broadcast = [broadcast = channel_broadcast](const std::string& type,
+                                                                         const json& payload) {
+                if (*broadcast) (*broadcast)(type, payload);
+            };
+            channel_services.make_transport = [this](const std::string& platform,
+                                                     const acecode::channels::core::PlatformConfig&,
+                                                     acecode::channels::core::ChannelStore&) {
+                auto transport = std::make_shared<acecode::channels::core::test::FakeTransport>(platform);
+                std::lock_guard<std::mutex> lock(channel_mu);
+                channel_transports.push_back(transport);
+                return transport;
+            };
+            channel_services.validate_credentials = [](const std::string&, const json& credentials,
+                                                       std::string* error) {
+                if (credentials.value("token", std::string{}) == "bad:token") {
+                    *error = "Token 无效";
+                    return json(nullptr);
+                }
+                return credentials;
+            };
+            channel_host = std::make_unique<acecode::channels::core::ChannelHost>(
+                tmp_dir / "channels", std::move(channel_services));
+            wdeps.channel_host = channel_host.get();
+        }
         server = std::make_unique<acecode::web::WebServer>(std::move(wdeps));
+        *channel_broadcast = [srv = server.get()](const std::string& type, const json& payload) {
+            srv->broadcast_local_event(type, payload);
+        };
         server_thread = std::thread([this] { server->run(); });
 
         // 等 server 监听就绪 — 用 cpr 探活到 /api/health 通为止,最多 3s
@@ -783,6 +827,7 @@ struct WebServerFixture {
               true) {}
 
     ~WebServerFixture() {
+        if (channel_host) channel_host->stop();
         if (server) server->stop();
         if (server_thread.joinable()) server_thread.join();
 
@@ -791,7 +836,9 @@ struct WebServerFixture {
         // while its project/checkpoint directories still exist; deleting the
         // fixture tree first races those terminal writes and can crash during
         // member destruction.
+        *channel_broadcast = nullptr;
         server.reset();
+        channel_host.reset();
         if (task_suggestions) task_suggestions->shutdown();
         task_suggestions.reset();
         client.reset();
@@ -2246,6 +2293,122 @@ TEST(WebServerHttp, SessionListMarksOnlyRemoteControlBoundSession) {
     }
 }
 
+// 场景:远程 Web 代理转发进来的请求(源地址 127.0.0.2)带着正确 token 访问消息通道接口。
+// 期望:返回 403,不泄露任何通道配置;本机直连照常 200。
+TEST(WebServerHttp, ChannelRoutesRejectNonLocalClients) {
+    WebServerFixture fx;
+    fx.channel_host->start();
+    const auto remote = cpr::Get(cpr::Url{fx.url("/api/channels")},
+                                 cpr::Header{{"X-ACECode-Token", "smoke-token"}},
+                                 cpr::Interface{"127.0.0.2"}, cpr::Timeout{3000});
+    if (remote.status_code == 0) GTEST_SKIP() << "本机不能以 127.0.0.2 为源地址发起连接: " << remote.error.message;
+    EXPECT_EQ(remote.status_code, 403) << remote.text;
+    EXPECT_EQ(json::parse(remote.text).value("error", ""), "LOCAL_ONLY");
+    EXPECT_EQ(remote.text.find("platforms"), std::string::npos);
+    const auto local = cpr::Get(cpr::Url{fx.url("/api/channels")});
+    ASSERT_EQ(local.status_code, 200) << local.text;
+    EXPECT_EQ(json::parse(local.text)["platforms"].size(), acecode::channels::core::platform_specs().size());
+}
+
+// 场景:设置页保存 Telegram token、打开再关闭开关;以及各种错误请求。
+// 期望:返回的快照只含 token 尾号;打开立即连接(假传输层被启动),关闭立即断开;
+// 校验失败的凭据不保存;非法请求体 400、未知平台 404。
+TEST(WebServerHttp, ChannelCredentialsAreMaskedAndToggleRoundTrips) {
+    WebServerFixture fx;
+    fx.channel_host->start();
+    const auto platform_of = [](const json& snapshot, const std::string& name) {
+        for (const auto& item : snapshot["platforms"])
+            if (item.value("platform", "") == name) return item;
+        return json(json::object());
+    };
+    const cpr::Header headers{{"Content-Type", "application/json"}};
+
+    const auto bad = cpr::Put(cpr::Url{fx.url("/api/channels/telegram/credentials")}, headers,
+                              cpr::Body{R"({"token":"bad:token"})"});
+    EXPECT_EQ(bad.status_code, 400) << bad.text;
+    EXPECT_EQ(json::parse(bad.text).value("message", ""), "Token 无效");
+
+    const auto saved = cpr::Put(cpr::Url{fx.url("/api/channels/telegram/credentials")}, headers,
+                                cpr::Body{R"({"token":"100:abcdefgh1234"})"});
+    ASSERT_EQ(saved.status_code, 200) << saved.text;
+    EXPECT_EQ(saved.text.find("abcdefgh1234"), std::string::npos);
+    EXPECT_EQ(platform_of(json::parse(saved.text), "telegram").value("credential_hint", ""), "****1234");
+    const auto listed = cpr::Get(cpr::Url{fx.url("/api/channels")});
+    ASSERT_EQ(listed.status_code, 200);
+    EXPECT_EQ(listed.text.find("abcdefgh1234"), std::string::npos);
+
+    const auto enabled = cpr::Post(cpr::Url{fx.url("/api/channels/telegram/enabled")}, headers,
+                                   cpr::Body{R"({"enabled":true})"});
+    ASSERT_EQ(enabled.status_code, 200) << enabled.text;
+    EXPECT_EQ(platform_of(json::parse(enabled.text), "telegram").value("state", ""), "connected");
+    std::shared_ptr<acecode::channels::core::test::FakeTransport> transport;
+    {
+        std::lock_guard<std::mutex> lock(fx.channel_mu);
+        ASSERT_EQ(fx.channel_transports.size(), 1u);
+        transport = fx.channel_transports[0];
+    }
+    EXPECT_EQ(transport->starts, 1);
+
+    const auto disabled = cpr::Post(cpr::Url{fx.url("/api/channels/telegram/enabled")}, headers,
+                                    cpr::Body{R"({"enabled":false})"});
+    ASSERT_EQ(disabled.status_code, 200) << disabled.text;
+    EXPECT_EQ(platform_of(json::parse(disabled.text), "telegram").value("state", ""), "disabled");
+    EXPECT_EQ(transport->stops, 1);
+
+    EXPECT_EQ(cpr::Post(cpr::Url{fx.url("/api/channels/telegram/enabled")}, headers,
+                        cpr::Body{R"({"enabled":"yes"})"}).status_code, 400);
+    EXPECT_EQ(cpr::Put(cpr::Url{fx.url("/api/channels/telegram/credentials")}, headers,
+                       cpr::Body{R"({"password":"x"})"}).status_code, 400);
+    EXPECT_EQ(cpr::Post(cpr::Url{fx.url("/api/channels/wechat/enabled")}, headers,
+                        cpr::Body{R"({"enabled":true})"}).status_code, 404);
+    EXPECT_EQ(cpr::Delete(cpr::Url{fx.url("/api/channels/telegram/access/admin")}).status_code, 400);
+}
+
+// 场景:机主在 Telegram 里发出第一条消息,通道为其新建并绑定一个无项目会话。
+// 期望:会话列表里只有这个会话带 channel_bound:{platform:"telegram"},其它会话不带该字段;
+// remote_control_bound 不受影响(/rc 专属行为只看它)。
+TEST(WebServerHttp, SessionListMarksChannelBoundSessions) {
+    WebServerFixture fx;
+    fx.channel_host->start();
+    const auto other = cpr::Post(cpr::Url{fx.url("/api/sessions")},
+                                 cpr::Header{{"Content-Type", "application/json"}}, cpr::Body{R"({})"});
+    ASSERT_EQ(other.status_code, 201) << other.text;
+    const auto other_id = json::parse(other.text).value("session_id", std::string{});
+    auto& telegram = fx.channel_host->platform("telegram");
+    telegram.set_credentials({{"token", "100:abcdefgh1234"}});
+    telegram.set_owner("user:1", "机主");
+    telegram.set_enabled(true);
+    std::shared_ptr<acecode::channels::core::test::FakeTransport> transport;
+    {
+        std::lock_guard<std::mutex> lock(fx.channel_mu);
+        ASSERT_FALSE(fx.channel_transports.empty());
+        transport = fx.channel_transports.back();
+    }
+    transport->inject(acecode::channels::core::test::message(
+        acecode::channels::core::test::private_address("1"), "你好", "m1"));
+    ASSERT_TRUE(acecode::channels::core::test::wait_until([&] { return !fx.channel_host->bound_sessions().empty(); }));
+    const auto bound_id = fx.channel_host->bound_sessions().begin()->first;
+
+    const auto listed = cpr::Get(cpr::Url{fx.url("/api/sessions")});
+    ASSERT_EQ(listed.status_code, 200) << listed.text;
+    bool saw_bound = false;
+    bool saw_other = false;
+    for (const auto& session : json::parse(listed.text)) {
+        const auto id = session.value("id", std::string{});
+        if (id == bound_id) {
+            saw_bound = true;
+            ASSERT_TRUE(session.contains("channel_bound")) << session.dump();
+            EXPECT_EQ(session["channel_bound"].value("platform", ""), "telegram");
+            EXPECT_FALSE(session.value("remote_control_bound", true));
+        } else if (id == other_id) {
+            saw_other = true;
+            EXPECT_FALSE(session.contains("channel_bound"));
+        }
+    }
+    EXPECT_TRUE(saw_bound);
+    EXPECT_TRUE(saw_other);
+}
+
 TEST(WebServerHttp, ExportSessionMarkdownUsesSuggestedAndUserSelectedFilename) {
     const auto export_dir = std::filesystem::temp_directory_path() /
                             ("acecode_session_export_success_" + std::to_string(std::random_device{}()));
diff --git a/vcpkg.json b/vcpkg.json
index baf01371d..5b018e1ca 100644
--- a/vcpkg.json
+++ b/vcpkg.json
@@ -3,6 +3,12 @@
   "version-semver": "0.9.34",
   "dependencies": [
     "cpr",
+    {
+      "name": "curl",
+      "features": [
+        "websockets"
+      ]
+    },
     "crow",
     "ftxui",
     "libzip",
diff --git a/web/package.json b/web/package.json
index 6eac105d9..b87ed69c4 100644
--- a/web/package.json
+++ b/web/package.json
@@ -44,14 +44,15 @@
     "micromark-util-symbol": "^2.0.1",
     "micromark-util-types": "^2.0.2",
     "pptx2html": "0.3.4",
+    "qrcode-generator": "2.0.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-i18next": "17.0.10",
     "react-joyride": "3.2.0",
+    "shiki": "4.3.1",
     "slate": "^0.126.0",
     "slate-history": "^0.113.1",
     "slate-react": "^0.126.0",
-    "shiki": "4.3.1",
     "x-data-spreadsheet": "^1.1.9",
     "xlsx": "^0.18.5"
   },
diff --git a/web/pnpm-lock.yaml b/web/pnpm-lock.yaml
index 4cb744261..55c270417 100644
--- a/web/pnpm-lock.yaml
+++ b/web/pnpm-lock.yaml
@@ -103,6 +103,9 @@ importers:
       pptx2html:
         specifier: 0.3.4
         version: 0.3.4
+      qrcode-generator:
+        specifier: 2.0.4
+        version: 2.0.4
       react:
         specifier: ^18.3.1
         version: 18.3.1
@@ -1873,6 +1876,9 @@ packages:
     resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==}
     engines: {node: '>=6'}
 
+  qrcode-generator@2.0.4:
+    resolution: {integrity: sha512-mZSiP6RnbHl4xL2Ap5HfkjLnmxfKcPWpWe/c+5XxCuetEenqmNFf1FH/ftXPCtFG5/TDobjsjz6sSNL0Sr8Z9g==}
+
   react-dom@18.3.1:
     resolution: {integrity: sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==}
     peerDependencies:
@@ -4057,6 +4063,8 @@ snapshots:
 
   punycode.js@2.3.1: {}
 
+  qrcode-generator@2.0.4: {}
+
   react-dom@18.3.1(react@18.3.1):
     dependencies:
       loose-envify: 1.4.0
diff --git a/web/scripts/i18n-en-overrides.mjs b/web/scripts/i18n-en-overrides.mjs
index 45d622a78..615d154e8 100644
--- a/web/scripts/i18n-en-overrides.mjs
+++ b/web/scripts/i18n-en-overrides.mjs
@@ -1,6 +1,30 @@
 // Human-reviewed product terminology and phrases where generic machine
 // translation is ambiguous without ACECode context.
 export const ENGLISH_SOURCE_OVERRIDES = Object.freeze({
+  '待命': 'Standing by',
+  '等待授权': 'Waiting for approval',
+  '等待回答': 'Waiting for an answer',
+  '整理上下文': 'Compacting context',
+  '正在重试': 'Retrying',
+  '思考中': 'Thinking',
+  '撰写回复': 'Writing reply',
+  '准备': 'Preparing to ',
+  '准备调用工具': 'Preparing a tool call',
+  '写入文件': 'Writing a file',
+  '修改代码': 'Editing code',
+  '搜索代码': 'Searching code',
+  '查阅网页': 'Browsing the web',
+  '协作': 'Collaborating',
+  '更新待办': 'Updating todos',
+  '收尾': 'Wrapping up',
+  '使用技能': 'Using a skill',
+  '调用 MCP': 'Calling MCP',
+  '派发任务': 'Dispatching a task',
+  '等成员回报': 'Waiting for members',
+  '发消息': 'Sending a message',
+  '追加任务': 'Adding a follow-up task',
+  '叫停成员': 'Stopping a member',
+  '查看成员': 'Checking members',
   '选择文件': 'Select file',
   '无法读取目录': 'Unable to read directory',
   '空目录': 'Empty directory',
@@ -1820,4 +1844,168 @@ export const ENGLISH_SOURCE_OVERRIDES = Object.freeze({
   "连接已断开，停止状态尚未确认": "Disconnected. The stop has not been confirmed",
   "正在等待当前任务停止": "Waiting for the current task to stop",
   "正在停止本轮任务…": "Stopping this turn…",
+  // 消息通道(openspec add-desktop-im-channels):设置 > 集成 > 消息通道、侧栏与配对请求通知
+  "请先填写凭据": "Fill in the credentials first",
+  "扫码连接二维码": "QR code for connecting",
+  "还差几步": "A few more steps",
+  "把机器人拉进你的服务器": "Add the bot to your server",
+  "复制失败,请手动选中复制": "Copy failed. Select the text and copy it manually",
+  "机主绑定二维码": "Owner binding QR code",
+  "绑定码": "Binding code",
+  "绑定码 10 分钟内有效,只能用一次;发送后这里会自动完成。": "The code is valid for 10 minutes and works once. This step completes by itself after you send it.",
+  "在 QQ、微信、飞书、钉钉、Telegram、Discord、LINE 里远程使用 ACECode。凭据只保存在这台电脑上;关闭 Desktop 后是否继续在线,取决于 设置 > 常规 里的“退出 ACECode 后继续运行后台进程”。": "Use ACECode remotely from QQ, WeChat, Feishu, DingTalk, Telegram, Discord and LINE. Credentials stay on this computer. Whether channels stay online after Desktop closes depends on \"Continue running the background process after exiting ACECode\" in Settings > General.",
+  "微信": "WeChat",
+  "飞书": "Feishu",
+  "钉钉": "DingTalk",
+  "在微信里私聊机器人下达指令,结果回到聊天窗口。": "Message the bot privately in WeChat to give instructions. Results come back to the chat.",
+  "在飞书私聊或群里 @机器人 下达指令,结果回到聊天窗口。": "Give instructions in a Feishu private chat or by @mentioning the bot in a group. Results come back to the chat.",
+  "在钉钉私聊或群里 @机器人 下达指令,结果回到聊天窗口。": "Give instructions in a DingTalk private chat or by @mentioning the bot in a group. Results come back to the chat.",
+  "私信机器人或在服务器频道里 @它 下达指令,结果回到频道。": "DM the bot or @mention it in a server channel to give instructions. Results come back to the channel.",
+  "在 LINE 私聊或群里 @机器人 下达指令,结果回到聊天窗口。": "Give instructions in a LINE private chat or by @mentioning the bot in a group. Results come back to the chat.",
+  "扫码登录": "Scan to sign in",
+  "用微信扫一扫并在手机上确认;扫码的微信号就是机主,也是唯一能使用它的人。": "Scan with WeChat and confirm on your phone. The WeChat account that scans becomes the owner and is the only one who can use the bot.",
+  "现在可以在微信里给机器人发消息了。微信机器人只支持私聊。": "You can now message the bot in WeChat. WeChat bots only support private chats.",
+  "创建应用": "Create app",
+  "打开飞书开放平台,创建「企业自建应用」,在「添加应用能力」里添加「机器人」。": "Open the Feishu Open Platform, create a custom app, and add the Bot capability under Add features.",
+  "在「权限管理」开通:im:message、im:message:send_as_bot、im:message.p2p_msg:readonly、im:message.group_at_msg:readonly、im:resource。": "Under Permissions, enable: im:message, im:message:send_as_bot, im:message.p2p_msg:readonly, im:message.group_at_msg:readonly, im:resource.",
+  "在「凭证与基础信息」复制 App ID 与 App Secret,填到下面。": "Copy the App ID and App Secret from Credentials & Basic Info and enter them below.",
+  "打开飞书开放平台": "Open Feishu Open Platform",
+  "App ID(cli_ 开头)": "App ID (starts with cli_)",
+  "版本": "Region",
+  "飞书(中国)": "Feishu (China)",
+  "Lark(海外)": "Lark (international)",
+  "回到飞书开放平台的「事件与回调」,订阅方式选「使用长连接接收事件」并保存(这里连上之后才能保存)。": "Back in the Feishu Open Platform, under Events & Callbacks choose \"Receive events through persistent connection\" and save (saving only works once this connection is up).",
+  "添加事件「接收消息 v2.0」(im.message.receive_v1)。": "Add the event \"Message received v2.0\" (im.message.receive_v1).",
+  "在「版本管理与发布」创建版本并发布,可用范围要包含你自己。": "Create and publish a version under Version Management & Release, with availability including yourself.",
+  "在飞书里搜索这个机器人,私聊它发送下面的 6 位数字。": "Find the bot in Feishu and send it the 6-digit code below in a private chat.",
+  "现在可以在飞书里私聊机器人了。把机器人拉进群后 @ 它,第一次需要在设置页批准。": "You can now message the bot privately in Feishu. Add it to a group and @mention it there; the first time needs approval in Settings.",
+  "打开钉钉开放平台,创建「企业内部应用」,在「应用能力」里添加「机器人」。": "Open the DingTalk Open Platform, create an internal app, and add the Robot capability.",
+  "机器人的消息接收模式选「Stream 模式」,在「权限管理」开通企业内机器人发送消息权限,然后发布应用。": "Set the robot's message mode to Stream, grant the internal robot send-message permission under Permissions, then publish the app.",
+  "在「凭证与基础信息」复制 Client ID 与 Client Secret,填到下面。": "Copy the Client ID and Client Secret from Credentials & Basic Info and enter them below.",
+  "打开钉钉开放平台": "Open DingTalk Open Platform",
+  "在钉钉里找到这个机器人,私聊它发送下面的 6 位数字。": "Find the robot in DingTalk and send it the 6-digit code below in a private chat.",
+  "现在可以在钉钉里私聊机器人了。把机器人拉进群后 @ 它,第一次需要在设置页批准。": "You can now message the robot privately in DingTalk. Add it to a group and @mention it there; the first time needs approval in Settings.",
+  "把机器人拉进群后 @ 它,第一次需要在设置页批准。": "Add the bot to a group and @mention it there; the first time needs approval in Settings.",
+  "打开 Discord 开发者后台,新建应用,在「Bot」页点「Reset Token」并复制。": "Open the Discord Developer Portal, create an application, and on the Bot page click Reset Token and copy it.",
+  "在同一页打开「Message Content Intent」。": "On the same page, turn on Message Content Intent.",
+  "把 Token 粘贴到下面;验证通过后用邀请链接把机器人拉进你的服务器。": "Paste the token below. Once it is verified, use the invite link to add the bot to your server.",
+  "打开 Discord 开发者后台": "Open the Discord Developer Portal",
+  "在 Discord 里私信这个机器人(需要和它在同一个服务器),发送下面的 6 位数字。": "DM the bot in Discord (you need to share a server with it) and send the 6-digit code below.",
+  "现在可以私信机器人,或在服务器频道里 @ 它。第一次在频道里使用需要在设置页批准。": "You can now DM the bot or @mention it in a server channel. Using it in a channel the first time needs approval in Settings.",
+  "创建频道": "Create channel",
+  "在 LINE Official Account Manager 建立官方账号,并在「设定 > Messaging API」启用 Messaging API。": "Create an official account in LINE Official Account Manager and enable the Messaging API under Settings > Messaging API.",
+  "在 LINE Developers 控制台的频道「Basic settings」复制 Channel ID 与 Channel secret,填到下面。": "Copy the Channel ID and Channel secret from the channel's Basic settings in the LINE Developers console and enter them below.",
+  "在「Messaging API」页打开 Use webhook;在官方账号的回应设定里关闭自动回应讯息与加入好友的欢迎讯息。": "Turn on Use webhook on the Messaging API page, and turn off auto-reply and greeting messages in the official account's response settings.",
+  "LINE 只能通过公网地址回调。公网地址留空时,ACECode 会用 cloudflared 自动建立临时隧道(先安装:winget install --id Cloudflare.cloudflared),每次连接都会自动更新 LINE 的回调地址。": "LINE can only deliver messages to a public address. If you leave the public address empty, ACECode opens a temporary cloudflared tunnel (install it first: winget install --id Cloudflare.cloudflared) and updates LINE's webhook URL on every connect.",
+  "打开 LINE Developers": "Open LINE Developers",
+  "打开 LINE Official Account Manager": "Open LINE Official Account Manager",
+  "公网地址": "Public address",
+  "公网地址(可选,留空则自动建立隧道)": "Public address (optional; leave empty for an automatic tunnel)",
+  "在 LINE 里把官方账号加为好友,私聊它发送下面的 6 位数字。": "Add the official account as a friend in LINE and send it the 6-digit code below.",
+  "现在可以在 LINE 里私聊机器人了。把机器人邀请进群后 @ 它,第一次需要在设置页批准。": "You can now message the bot privately in LINE. Invite it to a group and @mention it there; the first time needs approval in Settings.",
+  "微信机器人": "WeChat bot",
+  "机器人 {{p0}}": "Bot {{p0}}",
+  "{{p0}} 机器人": "{{p0}} bot",
+  "接下来 10 分钟内第一个私聊机器人的人成为机主,现在就用你的 {{p0}} 私聊它一句。": "The first person to message the bot privately in the next 10 minutes becomes the owner. Send it a message from your {{p0}} now.",
+  "用你的 {{p0}} 私聊机器人一句,下面会出现请求,批准后你就是机主。": "Send the bot a private message from your {{p0}}. A request appears below; approve it to become the owner.",
+  "用微信扫一扫,并在手机上确认": "Scan with WeChat and confirm on your phone",
+  "获取二维码失败,请重试": "Couldn't get a QR code. Try again",
+  "{{p0}}(留空则不修改)": "{{p0}} (leave empty to keep)",
+  "weixin wechat 微信 扫码 ilink 机器人 im channel 消息通道 连接 取消连接": "weixin wechat qr ilink bot im channel messaging connect disconnect",
+  "feishu lark 飞书 app id app secret 长连接 机器人 im channel 消息通道 连接 取消连接": "feishu lark app id app secret persistent connection bot im channel messaging connect disconnect",
+  "dingtalk 钉钉 stream client id client secret 机器人 im channel 消息通道 连接 取消连接": "dingtalk stream client id client secret robot im channel messaging connect disconnect",
+  "discord bot token 机器人 服务器 im channel 消息通道 连接 取消连接": "discord bot token server im channel messaging connect disconnect",
+  "line messaging api channel secret webhook cloudflared 机器人 im channel 消息通道 连接 取消连接": "line messaging api channel secret webhook cloudflared bot im channel messaging connect disconnect",
+  "处理": "Fix",
+  "管理": "Manage",
+  "{{p0}} 个请求待批准": "{{p0}} request(s) awaiting approval",
+  "使用已保存的机器人,或者换一个。": "Use the saved bot, or switch to another one.",
+  "更换": "Change",
+  "在 Telegram 里搜索 @BotFather(认准蓝色认证标记),发送 /newbot。": "In Telegram, search for @BotFather (look for the blue verified badge) and send /newbot.",
+  "按提示起名字,用户名要以 bot 结尾。": "Follow the prompts to name it. The username must end in bot.",
+  "把它回复的 Token 粘贴到下面。": "Paste the token it replies with below.",
+  "使用已保存的机器人": "Use the saved bot",
+  "验证并继续": "Verify and continue",
+  "使用已保存的机器人,或者重新扫码换一个。": "Use the saved bot, or scan again to switch to another one.",
+  "填写 QQ 开放平台里机器人的 AppID 与 AppSecret,保存前会先验证。": "Enter the bot's AppID and AppSecret from QQ Open Platform. They are verified before saving.",
+  "返回扫码": "Back to QR code",
+  "正在获取二维码…": "Getting a QR code…",
+  "扫码后会自动创建机器人并完成配置,扫码人成为机主。": "Scanning creates and configures the bot automatically. Whoever scans becomes the owner.",
+  "重新获取二维码": "Get a new QR code",
+  "移除 webhook 并连接": "Remove webhook and connect",
+  "机器人": "the bot",
+  "现在可以在 QQ 里私聊机器人了。把机器人拉进群后 @ 它,第一次需要在设置页批准。未经个人认证的机器人只能由你本人使用,也只能加入你担任群主的群。": "You can now message the bot privately in QQ. To use it in a group, add the bot and @mention it; the first time needs approval in Settings. A bot without personal verification can only be used by you and can only join groups you own.",
+  "连接完成": "All set",
+  "用手机相机扫码(Telegram 自带的扫码扫不了这个),在 Telegram 里点「开始」就成为机主。": "Scan it with your phone's camera (Telegram's own scanner can't read it), then tap Start in Telegram to become the owner.",
+  "电脑上登录了 Telegram 也可以直接点链接:": "If Telegram is signed in on this computer, you can also click the link:",
+  "链接 10 分钟内有效,只能用一次。": "The link is valid for 10 minutes and works once.",
+  "或者批准私聊请求,第一个被批准的人成为机主": "Or approve a private chat request. The first person approved becomes the owner",
+  "稍后再说": "Later",
+  "连接 {{p0}}": "Connect {{p0}}",
+  "管理 {{p0}}": "Manage {{p0}}",
+  "更换机器人": "Change bot",
+  "机主可以切换到任意会话;其他人只能在自己创建的会话之间切换。": "The owner can switch to any session; others can only switch between sessions they created.",
+  "还没有授权任何人。": "No one is approved yet.",
+  "QQ 机器人": "QQ bot",
+  "在 QQ 私聊或群里 @机器人 下达指令,结果回到聊天窗口。": "Give instructions in a QQ private chat or by @mentioning the bot in a group. Results come back to the chat.",
+  "在 Telegram 私聊或群里 @机器人 下达指令,结果回到聊天窗口。": "Give instructions in a Telegram private chat or by @mentioning the bot in a group. Results come back to the chat.",
+  "扫码创建机器人": "Scan to create bot",
+  "连接": "Connect",
+  "创建机器人": "Create bot",
+  "取消连接": "Disconnect",
+  "通道数据异常,详情见日志": "Channel data error. See the log for details",
+  "连接中…": "Connecting…",
+  "连接中断,正在自动重试": "Connection lost, retrying automatically",
+  "机器人设置了 webhook,需要处理": "The bot has a webhook set; action needed",
+  "连接失败,详情见日志": "Connection failed. See the log for details",
+  "已由另一个 ACECode 连接": "Connected by another ACECode",
+  "通道数据文件异常,详情见日志。": "The channel data file has a problem. See the log for details.",
+  "已连接 {{p0}}": "Connected {{p0}}",
+  "正在打开连接…": "Opening the connection…",
+  "这个机器人设置了 webhook,ACECode 收不到消息。移除后由 ACECode 接管,原来接收 webhook 的服务会停止收到消息。": "This bot has a webhook set, so ACECode can't receive messages. After it is removed, ACECode takes over and the service that received the webhook stops getting messages.",
+  "连接失败,原因已写入日志。确认凭据无误后重试,或回到上一步更换。": "Connection failed; the reason is in the log. Check the credentials and retry, or go back to change them.",
+  "连接中断,正在自动重试…": "Connection lost, retrying automatically…",
+  "这个机器人正由另一个 ACECode 连接,它退出后这里会自动接管。": "Another ACECode is connected to this bot. This one takes over automatically after it exits.",
+  "正在连接…": "Connecting…",
+  "机主:{{p0}}": "Owner: {{p0}}",
+  "二维码过期后已自动换新,请扫描新的二维码": "The QR code expired and was replaced. Scan the new one",
+  "用手机 QQ 扫一扫,按提示创建并授权机器人": "Scan with QQ on your phone and follow the prompts to create and authorize the bot",
+  "扫码成功,你已是机主": "Scanned. You are now the owner",
+  "扫码成功": "Scanned",
+  "获取二维码失败,可以重试,或改为手动填写": "Couldn't get a QR code. Retry, or enter the credentials manually",
+  "二维码已过期": "The QR code expired",
+  "qq bot 机器人 扫码 appid appsecret im channel 消息通道 连接 取消连接 owner approve revoke 机主 授权 审批 撤销": "qq bot qr appid appsecret im channel messaging connect disconnect owner approve revoke",
+  "telegram bot token botfather 机器人 机主 im channel 消息通道 连接 取消连接 owner approve revoke 授权 审批 撤销": "telegram bot token botfather owner im channel messaging connect disconnect approve revoke",
+  "{{p0}} 分钟后过期": "Expires in {{p0}} min",
+  "{{p0}} 配对请求": "{{p0}} pairing request",
+  "{{p0}}{{p1}}请求使用 ACECode,到设置 > 消息通道处理": "{{p0}}{{p1}} wants to use ACECode. Review it in Settings > Messaging channels",
+  "绑定机主": "Set owner",
+  "撤销 {{p0}} 的授权?": "Revoke access for {{p0}}?",
+  "撤销后立即停止处理其消息,并中止其会话正在进行的回合。": "Their messages stop being processed immediately, and any running turn in their sessions is stopped.",
+  "机主": "Owner",
+  "机主与授权名单": "Owner and approved contacts",
+  "批准": "Approve",
+  "群": "Group",
+  "群 {{p0}}": "Group {{p0}}",
+  "群 {{p0}} 的成员 {{p1}}": "Member {{p1}} of group {{p0}}",
+  "群成员": "Group member",
+  "复制链接": "Copy link",
+  "手动填写": "Enter manually",
+  "私聊": "Private chat",
+  "消息通道": "Messaging channels",
+  "消息通道只能在运行 ACECode 的这台电脑上设置": "Messaging channels can only be configured on the computer running ACECode",
+  "新联系人": "A new contact",
+  "一个群": "A group",
+  "已绑定到 {{p0}}": "Bound to {{p0}}",
+  "已保存 {{p0}},留空则不修改": "Saved {{p0}}. Leave blank to keep it",
+  "已拒绝 {{p0}}": "Declined {{p0}}",
+  "已连接 · {{p0}}": "Connected · {{p0}}",
+  "已批准 {{p0}}": "Approved {{p0}}",
+  "已取消扫码,原有配置未改动": "QR setup canceled. The existing configuration is unchanged",
+  "用户 {{p0}}": "User {{p0}}",
+  "重新扫码": "Scan again",
+  "重新生成": "Regenerate",
+  "没有找到 cloudflared。先运行 winget install --id Cloudflare.cloudflared 安装后重试,或回到上一步填写自己的公网地址。": "cloudflared was not found. Install it with winget install --id Cloudflare.cloudflared and try again, or go back and enter your own public address.",
+  "回调地址已登记。请在 LINE Developers 控制台的 Messaging API 页打开 Use webhook,打开后这里会自动变为已连接。": "The webhook URL is registered. Turn on Use webhook on the Messaging API page of the LINE Developers console; this changes to connected automatically once it is on.",
+  "请把你的公网地址转发到本机 http://127.0.0.1:{{p0}},连通后会自动继续。": "Forward your public address to http://127.0.0.1:{{p0}} on this computer. Setup continues automatically once it is reachable.",
 });
diff --git a/web/scripts/test-chat-scroll-to-bottom.mjs b/web/scripts/test-chat-scroll-to-bottom.mjs
index 88122496a..eac9e665c 100644
--- a/web/scripts/test-chat-scroll-to-bottom.mjs
+++ b/web/scripts/test-chat-scroll-to-bottom.mjs
@@ -130,6 +130,24 @@ try {
     await button.waitFor();
     await settle();
   };
+  // Observe the live animation clock, without pausing or seeking keyframes.
+  const observeDotMotion = () => dots.evaluateAll(async nodes => {
+    const samples = [];
+    const start = performance.now();
+    while (performance.now() - start < 2600) {
+      await new Promise(requestAnimationFrame);
+      samples.push(nodes.map(node => new DOMMatrixReadOnly(getComputedStyle(node).transform).m42));
+    }
+    return {
+      reduced: matchMedia('(prefers-reduced-motion: reduce)').matches,
+      names: nodes.map(node => getComputedStyle(node).animationName),
+      ranges: nodes.map((_, index) => {
+        const values = samples.map(sample => sample[index]);
+        return Math.max(...values) - Math.min(...values);
+      }),
+      frames: samples.length,
+    };
+  });
   await page.goto(`http://127.0.0.1:${server.httpServer.address().port}/scroll-fixture`);
   await page.locator('[data-chat-row="true"]').last().waitFor();
   await settle();
@@ -177,9 +195,16 @@ try {
   const runningBox = await button.boundingBox();
   check('running indicator preserves the button position and size',
     ['x', 'y', 'width', 'height'].every(key => Math.abs(idleBox[key] - runningBox[key]) < 1), { idleBox, runningBox });
+  for (const reducedMotion of [null, 'no-preference', 'reduce']) {
+    await page.emulateMedia({ reducedMotion });
+    const motion = await observeDotMotion();
+    check(`dots advance in real time with ${reducedMotion || 'system'} motion preference`,
+      motion.frames > 10 && motion.ranges.length === 3 && motion.ranges.every(range => range > 1), motion);
+  }
+  await page.emulateMedia({ reducedMotion: 'no-preference' });
   const animation = await dots.evaluateAll(nodes => ({
     delays: nodes.map(node => getComputedStyle(node).animationDelay),
-    samples: [100, 300, 500].map(time => nodes.map(node => {
+    samples: [200, 600, 1000].map(time => nodes.map(node => {
       const animation = node.getAnimations()[0];
       animation.pause();
       animation.currentTime = time;
@@ -187,7 +212,7 @@ try {
     })),
   }));
   check('dots hop one at a time from left to right',
-    animation.delays.join(',') === '0s,0.2s,0.4s'
+    animation.delays.join(',') === '0s,0.4s,0.8s'
     && animation.samples.every((sample, index) => sample.every((y, dot) => dot === index ? y < -2.9 : Math.abs(y) < .1)), animation);
   await dots.evaluateAll(nodes => nodes.forEach(node => node.getAnimations().forEach(animation => {
     animation.currentTime = 0;
@@ -199,11 +224,12 @@ try {
   }
   await page.emulateMedia({ reducedMotion: 'reduce' });
   await settle();
-  check('reduced motion keeps static dots and a usable button', await button.isEnabled()
-    && await dots.evaluateAll(nodes => nodes.length === 3 && nodes.every(node => getComputedStyle(node).animationName === 'none')));
+  const reducedMotion = await observeDotMotion();
+  check('reduced motion keeps gentle moving dots and a usable button', await button.isEnabled()
+    && reducedMotion.ranges.every(range => range > 1 && range <= 1.5), reducedMotion);
   await button.click();
   await settle();
-  await bottom('clicking static running dots returns to the bottom');
+  await bottom('clicking reduced-motion running dots returns to the bottom');
   await page.emulateMedia({ reducedMotion: 'no-preference' });
   await away();
   for (const type of ['done', 'error', 'turn_aborted']) {
diff --git a/web/scripts/test-desktop-office.mjs b/web/scripts/test-desktop-office.mjs
new file mode 100644
index 000000000..adbca1baa
--- /dev/null
+++ b/web/scripts/test-desktop-office.mjs
@@ -0,0 +1,120 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { toolIconSvg } from '../src/lib/toolIcons.js';
+const modulePath = process.env.ACE_PLAYWRIGHT_MODULE;
+const { chromium } = await import(modulePath ? pathToFileURL(path.resolve(modulePath)).href : 'playwright');
+const root = fileURLToPath(new URL('../../', import.meta.url));
+const output = process.env.ACE_OFFICE_CAPTURE_DIR || fs.mkdtempSync(path.join(os.tmpdir(),'ace-office-browser-'));
+fs.mkdirSync(output,{recursive:true});
+const browser = await chromium.launch({channel:process.env.ACE_BROWSER_CHANNEL || 'msedge',headless:true});
+const errors=[],external=[];
+const actor=(id,extra={})=>({id,root:id==='root',name:id==='root'?'Maestro':id,state:'work',label:'工作中',busy:true,seed:id.length*173,contextKnown:true,contextRatio:.7,contextTokens:7000,contextLimit:10000,transfers:[],...extra});
+const data=(extra={})=>({version:1,follow:true,connected:true,complete:true,seed:137,
+  selected:{sessionId:'root',workspaceHash:'project',title:'修复登录流程'},
+  offices:['修复登录流程','研究消息分发','整理设计文档','检查任务取消','验证桌面发布'].map((title,i)=>({sessionId:i?'root'+i:'root',workspaceHash:'project',title,workspaceName:'ACECode'})),
+  agents:[actor('root',{tool:'file_read',iconSvg:toolIconSvg('file_read')}),actor('代码审查',{state:'think',label:'思考中'}),actor('回归测试',{state:'permission',label:'等待授权'})],overflow:0,...extra});
+try {
+  const page=await browser.newPage({viewport:{width:688,height:504},deviceScaleFactor:1});
+  page.on('pageerror',e=>errors.push(e.message));page.on('request',r=>{if(/^https?:/.test(r.url()))external.push(r.url());});
+  await page.addInitScript(()=>{window.officeActions=[];window.chrome={webview:{postMessage:value=>officeActions.push(value),addEventListener:(type,listener)=>{window.hostMessage=listener;}}};});
+  await page.goto(pathToFileURL(path.join(root,'assets/desktop_pet/agent_office_pet.html')).href);
+  await page.waitForFunction(()=>!!window.AgentOffice&&window.officeActions.includes('ready'));
+  assert.equal(await page.evaluate(()=>AgentOffice.agents.length),0,'production starts without demo workers');
+  const apply=async snapshot=>{await page.evaluate(value=>window.hostMessage({data:value}),snapshot);await page.waitForTimeout(90);};
+  // 以模拟时间推进(走路、信封、等待),不依赖真实帧率;predicate 在页面里求值。
+  const advanceUntil=async(predicate,maxMs=20000)=>page.evaluate(({source,maxMs})=>{
+    const test=new Function('return ('+source+')');
+    for(let t=0;t<maxMs;t+=100){if(test())return true;AgentOffice.advance(100);}
+    return test();
+  },{source:predicate,maxMs});
+  const present=()=>page.evaluate(()=>AgentOffice.agents.filter(a=>!a.leaving).map(a=>a.id));
+  await apply(data());
+  assert.equal(await page.locator('.office-tab').count(),5);
+  assert.equal(await page.locator('#officeFollow').getAttribute('aria-checked'),'true');
+  assert.equal(await page.evaluate(()=>AgentOffice.agents.length),3);
+  const originalLayout=await page.evaluate(()=>AgentOffice.layoutSignature);
+  const look=await page.evaluate(()=>AgentOffice.agents.find(a=>a.id==='代码审查').look);
+  await page.locator('.office-tab').nth(1).click();
+  assert.ok(await page.evaluate(()=>officeActions.some(raw=>{try{return JSON.parse(raw).type==='select'&&JSON.parse(raw).session_id==='root1';}catch{return false;}})));
+  await page.locator('#officeFollow').click();
+  assert.ok(await page.evaluate(()=>officeActions.some(raw=>{try{return JSON.parse(raw).type==='follow'&&JSON.parse(raw).follow===false;}catch{return false;}})));
+  await page.locator('.office-tab').nth(2).focus();
+  await page.keyboard.press('Enter');
+  assert.ok(await page.evaluate(()=>officeActions.some(raw=>{try{const m=JSON.parse(raw);return m.type==='select'&&m.session_id==='root2';}catch{return false;}})));
+  await page.screenshot({path:path.join(output,'office-working-688.png')});
+  // Busy agents keep a persistent bubble: verb plus the call preview or the latest streamed words.
+  await apply(data({agents:[actor('root',{tool:'file_read',iconSvg:toolIconSvg('file_read'),label:'读取',detail:'src/auth/login.cpp'}),
+    actor('代码审查',{state:'type',label:'撰写回复',detail:'…并发登录会覆盖旧会话'}),actor('回归测试',{state:'permission',label:'等待授权',detail:'运行命令'})]}));
+  const bubbles=await page.evaluate(()=>Object.fromEntries(AgentOffice.agents.map(a=>[a.id,a.bubble])));
+  assert.match(bubbles.root,/读取.*src\/auth\/login\.cpp/);
+  assert.match(bubbles['代码审查'],/撰写回复.*覆盖旧会话/);
+  assert.match(bubbles['回归测试'],/等待授权/);
+  assert.ok(await page.locator('.bub.type .bub-detail').count()>=1,'streaming bubble keeps the typing caret style');
+  assert.ok(await page.evaluate(()=>officeActions.some(raw=>{try{const m=JSON.parse(raw);return m.type==='overlay'&&m.bubbles?.length>=3;}catch{return false;}})),'bubble regions reach the native window shape');
+  await page.screenshot({path:path.join(output,'office-bubbles-688.png')});
+  // Completed workers walk to their dispatcher, hand in a report envelope, then leave; the main agent sleeps.
+  await apply(data({agents:[actor('root',{state:'sleep',label:'zzz',busy:false,contextRatio:.15})],completed:['代码审查','回归测试']}));
+  assert.deepEqual(await present(),['root']);
+  assert.ok(await page.evaluate(()=>AgentOffice.agents.filter(a=>a.leaving).every(a=>a.walking&&a.state==='done')));
+  assert.ok(await advanceUntil("AgentOffice.envelopes.some(e=>e.label==='回报'&&e.to==='root')"),'report envelope flies to the dispatcher');
+  assert.ok(await advanceUntil("AgentOffice.agents.some(a=>a.id==='root'&&/收到.*的结果/.test(a.bubble))"),'dispatcher acknowledges the report');
+  assert.ok(await advanceUntil("AgentOffice.agents.length===1"),'workers leave through the door');
+  assert.deepEqual(await page.evaluate(()=>AgentOffice.agents.map(a=>a.state)),['sleep']);
+  await page.screenshot({path:path.join(output,'office-sleep-688.png')});
+  // A new worker walks in, receives a task envelope at the dispatcher's desk, then sits down.
+  await apply(data());
+  assert.ok(await page.evaluate(()=>AgentOffice.agents.filter(a=>!a.root&&a.id!=='root').every(a=>a.walking)),'new workers enter on foot');
+  assert.ok(await advanceUntil("AgentOffice.envelopes.some(e=>e.label==='任务'&&e.from==='root')"),'task envelope leaves the dispatcher');
+  assert.ok(await advanceUntil("AgentOffice.agents.every(a=>!a.walking)"),'workers reach their seats');
+  assert.equal(await page.evaluate(()=>AgentOffice.agents.find(a=>a.id==='代码审查').look),look);
+  assert.equal(await page.evaluate(()=>AgentOffice.layoutSignature),originalLayout);
+  const toolImage=await page.locator('.office-tool:not([hidden])').first().getAttribute('src');
+  assert.equal(decodeURIComponent(toolImage.split(',')[1]),toolIconSvg('file_read').replaceAll('currentColor','#27324f'));
+  // Over-capacity members remain reachable, and the host receives their hit box.
+  const many=[actor('root'),...Array.from({length:9},(_,i)=>actor('成员'+i))];
+  await apply(data({agents:many,overflow:2}));
+  assert.equal((await present()).length,8);
+  await page.locator('#officeOverflow').click();
+  assert.equal(await page.locator('#officeMembers button').count(),10);
+  assert.ok(await page.evaluate(()=>officeActions.some(raw=>{try{const m=JSON.parse(raw);return m.type==='overlay'&&m.rect?.[2]>m.rect?.[0];}catch{return false;}})));
+  await apply(data({agents:many.map((a,i)=>i===9?{...a,state:'permission',label:'等待授权'}:a),overflow:2}));
+  assert.match(await page.locator('#officeMembers button').last().textContent(),/等待授权/);
+  await page.locator('#officeMembers button').last().click();
+  assert.ok(await page.evaluate(()=>officeActions.some(raw=>{try{const m=JSON.parse(raw);return m.type==='open'&&m.session_id==='成员8';}catch{return false;}})));
+  await page.locator('#officeOverflow').click();
+  await apply(data({follow:false}));
+  await advanceUntil("AgentOffice.agents.every(a=>!a.walking)");
+  // Mesh messages between members fly as labelled envelopes.
+  await apply(data({agents:[actor('root'),actor('代码审查',{path:'/root/review'}),actor('回归测试',{path:'/root/test',
+    transfers:[{seq:77,sender:'/root/review',recipient:'/root/test',sender_session_id:'代码审查',type:'MESSAGE'}]})]}));
+  assert.ok(await page.evaluate(()=>AgentOffice.envelopes.some(e=>e.from==='代码审查'&&e.to==='回归测试'&&e.label==='消息')),'mesh message envelope');
+  // Reduced motion: no walking, but the task hand-off is still shown.
+  await page.emulateMedia({reducedMotion:'reduce'});
+  await apply(data({agents:[actor('root'),actor('代码审查',{path:'/root/review'}),actor('回归测试',{path:'/root/test'}),actor('文档')]}));
+  assert.equal(await page.evaluate(()=>AgentOffice.agents.find(a=>a.id==='文档').walking),false);
+  assert.ok(await page.evaluate(()=>AgentOffice.envelopes.some(e=>e.to==='文档'&&e.label==='任务')),'reduced motion keeps the hand-off');
+  await page.emulateMedia({reducedMotion:'no-preference'});
+  assert.equal(await page.locator('#officeMembers').isHidden(),true);
+  assert.ok(await page.evaluate(()=>officeActions.some(raw=>{try{const m=JSON.parse(raw);return m.type==='overlay'&&m.rect===null;}catch{return false;}})));
+
+  // The narrowest native scale keeps all five controls and the follow switch clickable.
+  for(const [width,height] of [[172,126],[344,252],[860,630]]) {
+    await page.setViewportSize({width,height});await page.waitForTimeout(90);
+    const bounds=await page.locator('.office-controls button').evaluateAll(buttons=>buttons.map(b=>{const r=b.getBoundingClientRect();return {x:r.x,y:r.y,right:r.right,bottom:r.bottom};}));
+    assert.equal(bounds.length,6);
+    assert.ok(bounds.every(r=>r.x>=0&&r.y>=0&&r.right<=width&&r.bottom<=32*width/344+1),JSON.stringify({width,bounds}));
+    await page.screenshot({path:path.join(output,`office-size-${width}.png`)});
+  }
+  await page.setViewportSize({width:688,height:504});
+  await apply(data({connected:false}));
+  assert.match(await page.locator('#officeNotice').textContent(),/连接已中断/);
+  assert.ok(await page.evaluate(()=>{const notices=officeActions.map(raw=>{try{return JSON.parse(raw);}catch{return {};}}).filter(m=>m.type==='overlay');return notices.at(-1)?.rect?.[3]>notices.at(-1)?.rect?.[1];}),'native region includes disconnected notice');
+  await apply(data({agents:[],offices:[],selected:null}));
+  assert.match(await page.locator('#officeNotice').textContent(),/发送消息后/);
+  assert.ok(await page.evaluate(()=>{const notices=officeActions.map(raw=>{try{return JSON.parse(raw);}catch{return {};}}).filter(m=>m.type==='overlay');return Array.isArray(notices.at(-1)?.rect);}), 'native region includes empty-state notice');
+  assert.deepEqual(errors,[]);assert.deepEqual(external,[]);
+  console.log(JSON.stringify({output,checks:40,errors,external},null,2));
+} finally {await browser.close();}
diff --git a/web/src/App.jsx b/web/src/App.jsx
index b1ef39bc5..43ddad069 100644
--- a/web/src/App.jsx
+++ b/web/src/App.jsx
@@ -1,3 +1,4 @@
+import { useDesktopOffice } from './lib/useDesktopOffice.js';
 // 顶层 App:鉴权 gate(401 → TokenPrompt)+ 主壳。
 //
 // 视觉对齐设计稿方向 C:顶部 41px TopBar + 270px Sidebar + 主区(单会话/4宫格/9宫格)
@@ -27,6 +28,8 @@ import {
 } from './lib/desktopNotificationMonitor.js';
 import {
   maybeNotify,
+  maybeNotifyChannelRequest,
+  buildChannelRequestPayload,
   noteHostWindowFocus,
   isHostWindowFocused,
   notificationBodyFromEvent,
@@ -58,6 +61,7 @@ import {
   SESSION_LIST_CHANGED_EVENT,
 } from './lib/sessionListEvents.js';
 import { normalizeRemoteControlSessionSelected } from './lib/remoteControlSessionNavigation.js';
+import { channelStateBindingSignature } from './lib/channelsSettings.js';
 import { beginSessionOpen } from './lib/sessionOpenDiagnostics.js';
 import { usePreference, mergeNextValue, readWithFallback } from './lib/usePreference.js';
 import { sessionWorkbench } from './lib/sessionWorkbench.js';
@@ -250,6 +254,7 @@ export function App() {
   );
 
   const [activeRef,    setActiveRef]    = useState(null);
+  useDesktopOffice(activeRef);
   const workbenchOwner = sessionWorkbench.ownerFor(activeRef);
   const [sessionTitleTarget, setSessionTitleTarget] = useState(null);
   const [sessionActionsTarget, setSessionActionsTarget] = useState(null);
@@ -1132,6 +1137,33 @@ export function App() {
     return () => connection.removeEventListener('message', handler);
   }, [authState, resumeAndOpenSession]);
 
+  // 消息通道(QQ / Telegram):新的配对请求在窗口失焦时弹系统通知,否则页面内提示;
+  // 某个平台绑定的会话集合变化时让侧栏立即刷新,电脑图标随之移动。
+  useEffect(() => {
+    if (authState !== 'ok') return undefined;
+    const bindingSignatures = new Map();
+    const handler = (event) => {
+      const message = event.detail || {};
+      if (message.type === 'channels_request') {
+        const request = message.payload || {};
+        if (!maybeNotifyChannelRequest(request, { cfg: healthRef.current?.notifications })) {
+          const payload = buildChannelRequestPayload(request);
+          toast({ kind: 'info', text: `${payload.title}:${payload.body}`, duration: 6000 });
+        }
+        return;
+      }
+      if (message.type !== 'channels_state') return;
+      const signature = channelStateBindingSignature(message.payload);
+      if (signature === null) return;
+      const platform = message.payload.platform;
+      if (bindingSignatures.get(platform) === signature) return;
+      bindingSignatures.set(platform, signature);
+      notifySessionListChanged({ reason: 'channel-binding-changed', noWorkspace: true });
+    };
+    connection.addEventListener('message', handler);
+    return () => connection.removeEventListener('message', handler);
+  }, [authState]);
+
   // 全局 Ctrl/Cmd+K 切换搜索面板。键位定义、判定与提示文案都收在
   // lib/searchPaletteShortcut.js,控制台(xterm)也按同一判定放行冒泡。
   useGlobalShortcut(
diff --git a/web/src/components/ActivityLine.jsx b/web/src/components/ActivityLine.jsx
index 6b6b81ba1..6ecc6f247 100644
--- a/web/src/components/ActivityLine.jsx
+++ b/web/src/components/ActivityLine.jsx
@@ -13,6 +13,7 @@ export function ActivityLine({
   icon = null,
   running = false,
   spinnerStatic = false,
+  preferIconWhileRunning = false,
   trailing = null,
   expandable = false,
   expanded = false,
@@ -37,7 +38,7 @@ export function ActivityLine({
         className="flex h-4 w-4 shrink-0 items-center justify-center"
         aria-hidden="true"
       >
-        {running ? (
+        {running && !preferIconWhileRunning ? (
           <span className={clsx('ace-spinner h-3 w-3', spinnerStatic && 'ace-spinner-static')} />
         ) : icon}
       </span>
diff --git a/web/src/components/ChannelsSettings.jsx b/web/src/components/ChannelsSettings.jsx
new file mode 100644
index 000000000..7723c61fc
--- /dev/null
+++ b/web/src/components/ChannelsSettings.jsx
@@ -0,0 +1,794 @@
+// 消息通道(设置 > 集成 > 消息通道,openspec add-desktop-im-channels / add-more-im-channels)。
+// 页面只有两列平台卡片:「连接」在还没配好时打开分步向导,配好的直接连接;连上后按钮变成
+// 「取消连接」。卡片只显示一行简要状态和待批准请求;连接原因、隐私模式、收发计数等细节由 daemon
+// 写进日志,不在页面展开(2026-10-05 验收反馈)。各平台向导的说明、字段与机主绑定方式在
+// lib/channelsSettings.js 的 platformSetup;状态变化经 WS(channels_*)实时合并。
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { api } from '../lib/api.js';
+import { connection } from '../lib/connection.js';
+import { clsx } from '../lib/format.js';
+import {
+  applyChannelsEvent,
+  bindView,
+  channelCardView,
+  channelCards,
+  channelErrorText,
+  connectNeedsWizard,
+  connectStepView,
+  contactRows,
+  credentialFields,
+  credentialPlaceholder,
+  credentialsPayload,
+  discordInviteUrl,
+  initialWizardStep,
+  normalizeBind,
+  normalizeChannelsSnapshot,
+  ownerStepView,
+  pendingRows,
+  platformSetup,
+  qrSvgModel,
+  savedBotSummary,
+} from '../lib/channelsSettings.js';
+import { copyTextToSystemClipboard } from '../lib/systemClipboard.js';
+import { Modal } from './Modal.jsx';
+import { VsIcon } from './Icon.jsx';
+import { toast } from './Toast.jsx';
+
+const inputClass = 'w-full h-8 px-2.5 text-[12px] rounded-md border border-border bg-surface-alt text-fg outline-none focus:border-accent transition disabled:opacity-50';
+const primaryButtonClass = 'px-3 py-1 text-[12px] bg-accent text-white rounded disabled:opacity-60 shrink-0';
+const secondaryButtonClass = 'px-3 py-1 text-[12px] rounded border border-border bg-surface hover:bg-surface-hi transition disabled:opacity-50 shrink-0';
+const dangerButtonClass = 'px-3 py-1 text-[12px] bg-danger text-white rounded disabled:opacity-60 shrink-0';
+const linkButtonClass = 'px-1 py-0.5 text-[11px] text-fg-mute hover:text-fg hover:underline disabled:opacity-50';
+const iconButtonClass = 'w-7 h-7 inline-flex items-center justify-center rounded text-fg-mute hover:text-fg hover:bg-surface-alt transition';
+
+const TONE_TEXT = { ok: 'text-ok', danger: 'text-danger', warn: 'text-warn', mute: 'text-fg-mute' };
+const TONE_DOT = {
+  ok: 'bg-ok shadow-[0_0_4px_var(--ace-ok)]',
+  danger: 'bg-danger shadow-[0_0_4px_var(--ace-danger)]',
+  warn: 'bg-warn shadow-[0_0_4px_var(--ace-warn)]',
+  mute: 'bg-fg-mute',
+};
+
+function StatusPill({ tone = 'mute', text }) {
+  return (
+    <span className={clsx('flex items-center gap-1.5 text-[12px] min-w-0', TONE_TEXT[tone] || TONE_TEXT.mute)}>
+      <span className={clsx('w-2 h-2 rounded-full shrink-0', TONE_DOT[tone] || TONE_DOT.mute)} />
+      <span className="truncate">{text}</span>
+    </span>
+  );
+}
+
+function PlatformIcon({ name, size = 18, box = 'h-9 w-9' }) {
+  return (
+    <span className={clsx('flex shrink-0 items-center justify-center rounded-md border border-border bg-surface-alt text-fg-2', box)}>
+      <VsIcon name={name} size={size} />
+    </span>
+  );
+}
+
+// 二维码在亮/暗主题下都保持白底黑块:反色二维码不是所有手机都能扫。
+function QrCode({ value, label }) {
+  const model = useMemo(() => qrSvgModel(value), [value]);
+  if (!model) return null;
+  return (
+    <div data-settings-surface="true" className="inline-flex shrink-0 rounded-md border border-border bg-white p-1">
+      <svg role="img" aria-label={label} viewBox={`0 0 ${model.size} ${model.size}`} width="168" height="168"
+        shapeRendering="crispEdges">
+        <path d={model.path} fill="black" />
+      </svg>
+    </div>
+  );
+}
+
+function QrPlaceholder() {
+  return (
+    <div className="flex h-[176px] w-[176px] shrink-0 items-center justify-center rounded-md bg-surface-alt">
+      <span className="ace-spinner" />
+    </div>
+  );
+}
+
+function PendingList({ requests, busy, onDecide }) {
+  return requests.map((request) => (
+    <div key={request.id} className="flex items-center justify-between gap-2 py-1.5">
+      <div className="min-w-0">
+        <div className="text-[12px] truncate">{request.title}</div>
+        <div className="text-[11px] text-fg-mute truncate">{request.subtitle}</div>
+      </div>
+      <div className="flex items-center gap-1.5 shrink-0">
+        <button type="button" className={primaryButtonClass} disabled={!!busy}
+          onClick={() => onDecide(request, true)}>批准</button>
+        <button type="button" className={secondaryButtonClass} disabled={!!busy}
+          onClick={() => onDecide(request, false)}>拒绝</button>
+      </div>
+    </div>
+  ));
+}
+
+function ChannelCard({ card, platform, busy, onConnect, onDisconnect, onFix, onManage, onDecide }) {
+  const view = channelCardView(platform, busy);
+  const pending = pendingRows(platform);
+  const connect = view.button.action === 'connect';
+  return (
+    <article data-channel-card={card.platform} className="flex min-w-0 flex-col rounded-lg border border-border bg-surface p-4">
+      <div className="flex items-center gap-3">
+        <PlatformIcon name={card.icon} />
+        <div className="min-w-0 flex-1 truncate text-[14px] font-semibold">{card.title}</div>
+        <button type="button" disabled={view.button.disabled}
+          className={connect ? primaryButtonClass : secondaryButtonClass}
+          onClick={connect ? onConnect : onDisconnect}>
+          {view.button.label}
+        </button>
+      </div>
+      <p className="mt-3 text-[12px] leading-5 text-fg-mute">{card.description}</p>
+      {(view.status || platform.configured) && (
+        <div className="mt-3 flex min-h-[22px] items-center justify-between gap-2">
+          {view.status ? <StatusPill tone={view.status.tone} text={view.status.text} /> : <span />}
+          <span className="flex items-center gap-1 shrink-0">
+            {view.status?.action === 'fix' && (
+              <button type="button" className={linkButtonClass} onClick={onFix}>处理</button>
+            )}
+            {platform.configured && (
+              <button type="button" className={linkButtonClass} onClick={onManage}>管理</button>
+            )}
+          </span>
+        </div>
+      )}
+      {pending.length > 0 && (
+        <div className="mt-3 border-t border-border pt-2">
+          <div className="text-[12px] font-medium text-warn">{`${pending.length} 个请求待批准`}</div>
+          <PendingList requests={pending} busy={busy} onDecide={onDecide} />
+        </div>
+      )}
+    </article>
+  );
+}
+
+function Stepper({ steps, current }) {
+  return (
+    <ol className="mb-5 flex items-center gap-2">
+      {steps.map((label, index) => {
+        const done = index < current;
+        const active = index === current;
+        return (
+          <li key={label} className={clsx('flex min-w-0 items-center gap-2', index < steps.length - 1 && 'flex-1')}
+            aria-current={active ? 'step' : undefined}>
+            <span className={clsx('flex h-6 w-6 shrink-0 items-center justify-center rounded-full border text-[12px]',
+              active ? 'border-accent bg-accent text-white' : done ? 'border-accent text-accent' : 'border-border text-fg-mute')}>
+              {done ? <VsIcon name="check" size={12} /> : index + 1}
+            </span>
+            <span className={clsx('truncate text-[12px]', active ? 'font-medium text-fg' : 'text-fg-mute')}>{label}</span>
+            {index < steps.length - 1 && <span className="h-px min-w-[12px] flex-1 bg-border" />}
+          </li>
+        );
+      })}
+    </ol>
+  );
+}
+
+function WizardFooter({ children }) {
+  return <div className="mt-5 flex items-center justify-end gap-2">{children}</div>;
+}
+
+function SavedBot({ title, desc, children }) {
+  return (
+    <div className="flex items-center justify-between gap-3 rounded-md bg-surface-alt px-3 py-2.5">
+      <div className="min-w-0">
+        <div className="text-[13px] truncate">{title}</div>
+        {desc && <div className="text-[11px] text-fg-mute truncate">{desc}</div>}
+      </div>
+      <div className="flex items-center gap-1 shrink-0">{children}</div>
+    </div>
+  );
+}
+
+function InlineError({ text }) {
+  return text ? <p className="mt-2 text-[12px] text-danger">{text}</p> : null;
+}
+
+function Instructions({ items }) {
+  if (!items?.length) return null;
+  return (
+    <ol className="list-decimal space-y-1 pl-5 text-[12px] leading-5 text-fg-2">
+      {items.map((item) => <li key={item}>{item}</li>)}
+    </ol>
+  );
+}
+
+function ExternalLinks({ links }) {
+  if (!links?.length) return null;
+  return (
+    <div className="mt-2 flex flex-wrap gap-x-3 gap-y-1">
+      {links.map((link) => (
+        <a key={link.href} href={link.href} target="_blank" rel="noreferrer"
+          className="text-[12px] text-accent hover:underline">{link.label}</a>
+      ))}
+    </div>
+  );
+}
+
+// 第一步(填写凭据):说明 + 字段;已经保存过的机器人默认显示摘要,点「更换」再填。
+function CredentialFields({ platformKey, platform, draft, setDraft, autoFocus }) {
+  return credentialFields(platformKey).map((field, index) => (
+    field.kind === 'select' ? (
+      <label key={field.key} className="mt-2 flex items-center gap-2 text-[12px]">
+        <span className="w-14 shrink-0 text-fg-mute">{field.label}</span>
+        <select className={inputClass} value={draft[field.key] ?? field.defaultValue ?? ''}
+          onChange={(e) => setDraft((d) => ({ ...d, [field.key]: e.target.value }))} aria-label={field.label}>
+          {field.options.map((option) => <option key={option.value} value={option.value}>{option.label}</option>)}
+        </select>
+      </label>
+    ) : (
+      <input key={field.key} className={clsx(inputClass, 'mt-2')} type={field.secret ? 'password' : 'text'}
+        value={draft[field.key] ?? ''} autoFocus={autoFocus && index === 0}
+        placeholder={credentialPlaceholder(platform, field)}
+        onChange={(e) => setDraft((d) => ({ ...d, [field.key]: e.target.value }))}
+        autoComplete={field.secret ? 'new-password' : 'off'} spellCheck={false} aria-label={field.label} />
+    )
+  ));
+}
+
+function FormCredentialsStep({ platformKey, platform, busy, run, change, onNext, onCancel }) {
+  const setup = platformSetup(platformKey);
+  const [editing, setEditing] = useState(change || !platform.configured);
+  const [draft, setDraft] = useState({});
+  const [error, setError] = useState('');
+  const saved = savedBotSummary(platformKey, platform);
+
+  const save = async () => {
+    const body = credentialsPayload(platformKey, draft);
+    if (!body) {
+      setError('请先填写凭据');
+      return;
+    }
+    setError('');
+    const ok = await run(`${platformKey}-credentials`, async () => {
+      const result = await api.setChannelCredentials(platformKey, body);
+      setDraft({});
+      return result;
+    }, setError);
+    if (ok) onNext();
+  };
+
+  if (!editing) {
+    return (
+      <>
+        <p className="mb-3 text-[12px] text-fg-mute">使用已保存的机器人,或者换一个。</p>
+        <SavedBot title={saved.title} desc={saved.desc}>
+          <button type="button" className={linkButtonClass} onClick={() => setEditing(true)}>更换</button>
+        </SavedBot>
+        <WizardFooter>
+          <button type="button" className={secondaryButtonClass} onClick={onCancel}>取消</button>
+          <button type="button" data-ace-dialog-primary="true" className={primaryButtonClass} onClick={onNext}>下一步</button>
+        </WizardFooter>
+      </>
+    );
+  }
+  return (
+    <>
+      <Instructions items={setup.credential.instructions} />
+      <ExternalLinks links={setup.credential.links} />
+      {setup.credential.note && <p className="mt-2 text-[11px] leading-5 text-fg-mute">{setup.credential.note}</p>}
+      <div className="mt-1">
+        <CredentialFields platformKey={platformKey} platform={platform} draft={draft} setDraft={setDraft} autoFocus />
+      </div>
+      <InlineError text={error} />
+      {platform.configured && !change && (
+        <button type="button" className={clsx(linkButtonClass, 'mt-2')} onClick={() => setEditing(false)}>
+          使用已保存的机器人
+        </button>
+      )}
+      <WizardFooter>
+        <button type="button" className={secondaryButtonClass} onClick={onCancel}>取消</button>
+        <button type="button" data-ace-dialog-primary="true" className={primaryButtonClass} disabled={!!busy} onClick={save}>
+          {busy === `${platformKey}-credentials` ? '验证中…' : '验证并继续'}
+        </button>
+      </WizardFooter>
+    </>
+  );
+}
+
+// 第一步(扫码):QQ 与微信。QQ 另有手动填写;已保存的机器人默认显示摘要。
+function ScanCredentialsStep({ platformKey, platform, bind, busy, run, change, onNext, onCancel }) {
+  const setup = platformSetup(platformKey);
+  const manualAvailable = setup.credential.fields.length > 0;
+  const [mode, setMode] = useState(change || !platform.configured ? 'scan' : 'saved');
+  const [draft, setDraft] = useState({});
+  const [error, setError] = useState('');
+  const view = bindView(bind, platformKey);
+  const startedRef = useRef(false);
+  const sawActiveRef = useRef(false);
+  const saved = savedBotSummary(platformKey, platform);
+
+  const startScan = useCallback(() => {
+    startedRef.current = true;
+    sawActiveRef.current = false;
+    run(`${platformKey}-bind`, () => api.startChannelBind(platformKey));
+  }, [platformKey, run]);
+
+  // 用户已经点了「连接」:进入扫码方式就直接获取二维码,不用再点一次。
+  useEffect(() => {
+    if (mode !== 'scan' || startedRef.current || view.active || busy) return;
+    startScan();
+  }, [mode, view.active, busy, startScan]);
+
+  // 只认这次发起的扫码:看到进行中之后再完成,才进入下一步(凭据已保存,通道已自动打开)。
+  useEffect(() => {
+    if (view.active) sawActiveRef.current = true;
+    if (mode === 'scan' && bind.phase === 'completed' && sawActiveRef.current) onNext();
+  }, [mode, view.active, bind.phase, onNext]);
+
+  const leaveScan = (next) => {
+    if (view.active) api.cancelChannelBind(platformKey).catch(() => {});
+    if (next !== 'scan') startedRef.current = false;
+    setMode(next);
+  };
+
+  const saveManual = async () => {
+    const body = credentialsPayload(platformKey, draft);
+    if (!body) {
+      setError('请先填写凭据');
+      return;
+    }
+    setError('');
+    const ok = await run(`${platformKey}-credentials`, async () => {
+      const result = await api.setChannelCredentials(platformKey, body);
+      setDraft({});
+      return result;
+    }, setError);
+    if (ok) onNext();
+  };
+
+  if (mode === 'saved') {
+    return (
+      <>
+        <p className="mb-3 text-[12px] text-fg-mute">使用已保存的机器人,或者重新扫码换一个。</p>
+        <SavedBot title={saved.title} desc={saved.desc}>
+          <button type="button" className={linkButtonClass} onClick={() => setMode('scan')}>重新扫码</button>
+          {manualAvailable && (
+            <button type="button" className={linkButtonClass} onClick={() => setMode('manual')}>手动填写</button>
+          )}
+        </SavedBot>
+        <WizardFooter>
+          <button type="button" className={secondaryButtonClass} onClick={onCancel}>取消</button>
+          <button type="button" data-ace-dialog-primary="true" className={primaryButtonClass} onClick={onNext}>下一步</button>
+        </WizardFooter>
+      </>
+    );
+  }
+  if (mode === 'manual') {
+    return (
+      <>
+        <p className="mb-1 text-[12px] text-fg-mute">{setup.credential.manualIntro}</p>
+        <CredentialFields platformKey={platformKey} platform={platform} draft={draft} setDraft={setDraft} autoFocus />
+        <InlineError text={error} />
+        <button type="button" className={clsx(linkButtonClass, 'mt-2')} onClick={() => setMode('scan')}>返回扫码</button>
+        <WizardFooter>
+          <button type="button" className={secondaryButtonClass} onClick={onCancel}>取消</button>
+          <button type="button" data-ace-dialog-primary="true" className={primaryButtonClass} disabled={!!busy}
+            onClick={saveManual}>
+            {busy === `${platformKey}-credentials` ? '验证中…' : '验证并继续'}
+          </button>
+        </WizardFooter>
+      </>
+    );
+  }
+  const retryable = ['failed', 'timed_out', 'cancelled'].includes(bind.phase) && !view.active;
+  return (
+    <>
+      <div className="flex items-center gap-4">
+        {view.showQr ? <QrCode value={bind.qrUrl} label="扫码连接二维码" /> : <QrPlaceholder />}
+        <div className="min-w-0 flex-1 text-[12px] leading-5">
+          <p className={clsx(TONE_TEXT[view.tone] || 'text-fg-2')}>{view.message || '正在获取二维码…'}</p>
+          <p className="mt-2 text-fg-mute">{setup.credential.scanHint}</p>
+          {retryable && (
+            <button type="button" className={clsx(secondaryButtonClass, 'mt-3')} disabled={!!busy} onClick={startScan}>
+              重新获取二维码
+            </button>
+          )}
+        </div>
+      </div>
+      <div className="mt-3 flex items-center gap-2">
+        {manualAvailable && (
+          <button type="button" className={linkButtonClass} onClick={() => leaveScan('manual')}>手动填写</button>
+        )}
+        {platform.configured && !change && (
+          <button type="button" className={linkButtonClass} onClick={() => leaveScan('saved')}>使用已保存的机器人</button>
+        )}
+      </div>
+      <WizardFooter>
+        <button type="button" className={secondaryButtonClass} onClick={onCancel}>取消</button>
+      </WizardFooter>
+    </>
+  );
+}
+
+function ConnectStep({ platformKey, platform, busy, run, onBack, onNext }) {
+  const view = connectStepView(platform);
+  const setup = platformSetup(platformKey);
+  const inviteUrl = platformKey === 'discord' ? discordInviteUrl(platform.credentialsPublic?.application_id) : '';
+  // 连上后还要回平台后台做事(飞书保存长连接、Discord 邀请进服务器)时停在这一步,让用户看完再下一步。
+  const checklist = setup.connectChecklist;
+  const holdAfterConnect = checklist.length > 0 || Boolean(inviteUrl);
+  const [error, setError] = useState('');
+  const enabledRef = useRef(false);
+  // 已经连着进来(从下一步退回)时不自动前进,否则「上一步」会被立刻弹回去。
+  const autoAdvanceRef = useRef(view.phase !== 'connected' && !holdAfterConnect);
+  const connect = useCallback(() => {
+    setError('');
+    run(`${platformKey}-toggle`, () => api.setChannelEnabled(platformKey, true), setError);
+  }, [platformKey, run]);
+
+  // 进入这一步就打开连接;扫码成功时 daemon 已经自动打开,不再重复。
+  useEffect(() => {
+    if (enabledRef.current || platform.enabled || busy) return;
+    enabledRef.current = true;
+    connect();
+  }, [platform.enabled, busy, connect]);
+
+  useEffect(() => {
+    if (view.phase === 'connected' && autoAdvanceRef.current) onNext();
+  }, [view.phase, onNext]);
+
+  const working = view.phase === 'idle' || view.phase === 'connecting';
+  return (
+    <>
+      <div className="flex items-start gap-3 rounded-md bg-surface-alt px-4 py-3">
+        {working
+          ? <span className="ace-spinner mt-0.5 shrink-0" />
+          : <span className={clsx('mt-1.5 h-2 w-2 shrink-0 rounded-full', TONE_DOT[view.tone] || TONE_DOT.mute)} />}
+        <p className={clsx('text-[12px] leading-5', TONE_TEXT[view.tone] || 'text-fg-2')}>{view.text}</p>
+      </div>
+      {view.phase === 'connected' && checklist.length > 0 && (
+        <div className="mt-4">
+          <div className="mb-1 text-[12px] font-medium">还差几步</div>
+          <Instructions items={checklist} />
+        </div>
+      )}
+      {inviteUrl && (
+        <div className="mt-4 text-[12px] leading-5">
+          <div className="mb-1 font-medium">把机器人拉进你的服务器</div>
+          <a href={inviteUrl} target="_blank" rel="noreferrer" className="break-all text-accent hover:underline">{inviteUrl}</a>
+        </div>
+      )}
+      <InlineError text={error} />
+      <WizardFooter>
+        <button type="button" className={secondaryButtonClass} onClick={onBack}>上一步</button>
+        {view.phase === 'webhook' && (
+          <button type="button" className={dangerButtonClass} disabled={!!busy}
+            onClick={() => run('tg-webhook', () => api.removeTelegramWebhook(), setError)}>
+            移除 webhook 并连接
+          </button>
+        )}
+        {view.phase === 'failed' && (
+          <button type="button" data-ace-dialog-primary="true" className={primaryButtonClass} disabled={!!busy}
+            onClick={connect}>重试</button>
+        )}
+        {view.phase === 'connected' && (
+          <button type="button" data-ace-dialog-primary="true" className={primaryButtonClass} onClick={onNext}>下一步</button>
+        )}
+      </WizardFooter>
+    </>
+  );
+}
+
+function OwnerStep({ platformKey, platform, busy, run, onDecide, onBack, onDone }) {
+  const view = ownerStepView(platform, platformKey);
+  const setup = platformSetup(platformKey);
+  const pending = pendingRows(platform).filter((request) => request.kind === 'user');
+  const [issued, setIssued] = useState(null);  // {link} 或 {code}
+  const [error, setError] = useState('');
+  const requestedRef = useRef(false);
+
+  const issue = useCallback(() => {
+    setError('');
+    run(`${platformKey}-owner-link`, async () => {
+      const result = await api.createChannelOwnerLink(platformKey);
+      setIssued({ link: result?.link || '', code: result?.code || '' });
+    }, setError);
+  }, [platformKey, run]);
+
+  useEffect(() => {
+    if ((view.mode !== 'link' && view.mode !== 'code') || requestedRef.current || busy) return;
+    requestedRef.current = true;
+    issue();
+  }, [view.mode, busy, issue]);
+
+  const copy = async (value) => {
+    const result = await copyTextToSystemClipboard(value);
+    toast(result?.ok ? { kind: 'ok', text: '已复制' } : { kind: 'err', text: '复制失败,请手动选中复制' });
+  };
+
+  if (view.done) {
+    return (
+      <>
+        <div className="flex flex-col items-center px-4 py-3 text-center">
+          <span className="flex h-10 w-10 items-center justify-center rounded-full bg-accent-bg text-accent">
+            <VsIcon name="check" size={18} />
+          </span>
+          <div className="mt-3 text-[14px] font-semibold">连接完成</div>
+          <p className="mt-1 text-[12px] text-fg-2">{view.text}</p>
+          <p className="mt-2 text-[12px] leading-5 text-fg-mute">{setup.doneHint}</p>
+        </div>
+        <WizardFooter>
+          <button type="button" data-ace-dialog-primary="true" className={primaryButtonClass} onClick={onDone}>完成</button>
+        </WizardFooter>
+      </>
+    );
+  }
+  const link = issued?.link || '';
+  const code = issued?.code || '';
+  return (
+    <>
+      {view.mode === 'link' && (
+        <div className="flex items-center gap-4">
+          {link ? <QrCode value={link} label="机主绑定二维码" /> : <QrPlaceholder />}
+          <div className="min-w-0 flex-1 text-[12px] leading-5">
+            <p>用手机相机扫码(Telegram 自带的扫码扫不了这个),在 Telegram 里点「开始」就成为机主。</p>
+            <p className="mt-2 text-fg-mute">电脑上登录了 Telegram 也可以直接点链接:</p>
+            {link && (
+              <a href={link} target="_blank" rel="noreferrer" className="break-all text-accent hover:underline">{link}</a>
+            )}
+            <div className="mt-2 flex flex-wrap gap-2">
+              <button type="button" className={secondaryButtonClass} disabled={!link} onClick={() => copy(link)}>复制链接</button>
+              <button type="button" className={secondaryButtonClass} disabled={!!busy} onClick={issue}>重新生成</button>
+            </div>
+            <p className="mt-2 text-[11px] text-fg-mute">链接 10 分钟内有效,只能用一次。</p>
+          </div>
+        </div>
+      )}
+      {view.mode === 'code' && (
+        <div className="rounded-md bg-surface-alt px-4 py-4 text-center">
+          <p className="text-[12px] leading-5 text-fg-2">{view.text}</p>
+          <div className="mt-3 font-mono text-[28px] tracking-[0.3em] text-fg" aria-label="绑定码">
+            {code || <span className="ace-spinner" />}
+          </div>
+          <div className="mt-3 flex justify-center gap-2">
+            <button type="button" className={secondaryButtonClass} disabled={!code} onClick={() => copy(code)}>复制</button>
+            <button type="button" className={secondaryButtonClass} disabled={!!busy} onClick={issue}>重新生成</button>
+          </div>
+          <p className="mt-2 text-[11px] text-fg-mute">绑定码 10 分钟内有效,只能用一次;发送后这里会自动完成。</p>
+        </div>
+      )}
+      {(view.mode === 'window' || view.mode === 'request') && (
+        <p className="rounded-md bg-surface-alt px-4 py-3 text-[12px] leading-5 text-fg-2">{view.text}</p>
+      )}
+      <InlineError text={error} />
+      {pending.length > 0 && (
+        <div className="mt-4">
+          <div className="text-[12px] font-medium">或者批准私聊请求,第一个被批准的人成为机主</div>
+          <PendingList requests={pending} busy={busy} onDecide={onDecide} />
+        </div>
+      )}
+      <WizardFooter>
+        <button type="button" className={secondaryButtonClass} onClick={onBack}>上一步</button>
+        <button type="button" className={secondaryButtonClass} onClick={onDone}>稍后再说</button>
+      </WizardFooter>
+    </>
+  );
+}
+
+function ConnectWizard({ platformKey, platform, bind, busy, run, onDecide, startAt, change, onClose }) {
+  const card = channelCards().find((item) => item.platform === platformKey);
+  const setup = platformSetup(platformKey);
+  const [step, setStep] = useState(startAt);
+  const titleId = `ace-channels-wizard-${platformKey}`;
+  const scanning = setup.credential.kind === 'scan' && bindView(bind, platformKey).active;
+  const close = () => {
+    if (scanning) api.cancelChannelBind(platformKey).catch(() => {});
+    onClose();
+  };
+  const toConnect = useCallback(() => setStep(1), []);
+  const toOwner = useCallback(() => setStep(2), []);
+
+  return (
+    <Modal onClose={close} width={540} labelledBy={titleId}>
+      <div className="p-5">
+        <div className="mb-4 flex items-center gap-3">
+          <PlatformIcon name={card.icon} size={16} box="h-8 w-8" />
+          <div id={titleId} className="flex-1 text-[15px] font-semibold">{`连接 ${card.title}`}</div>
+          <button type="button" className={iconButtonClass} aria-label="关闭" onClick={close}>
+            <VsIcon name="close" size={14} />
+          </button>
+        </div>
+        <Stepper steps={setup.steps} current={step} />
+        {step === 0 && setup.credential.kind === 'scan' && (
+          <ScanCredentialsStep platformKey={platformKey} platform={platform} bind={bind} busy={busy} run={run}
+            change={change} onNext={toConnect} onCancel={close} />
+        )}
+        {step === 0 && setup.credential.kind === 'form' && (
+          <FormCredentialsStep platformKey={platformKey} platform={platform} busy={busy} run={run} change={change}
+            onNext={toConnect} onCancel={close} />
+        )}
+        {step === 1 && (
+          <ConnectStep platformKey={platformKey} platform={platform} busy={busy} run={run}
+            onBack={() => setStep(0)} onNext={toOwner} />
+        )}
+        {step === 2 && (
+          <OwnerStep platformKey={platformKey} platform={platform} busy={busy} run={run} onDecide={onDecide}
+            onBack={() => setStep(1)} onDone={onClose} />
+        )}
+      </div>
+    </Modal>
+  );
+}
+
+function ManageDialog({ platformKey, platform, busy, onRevoke, onChangeBot, onClose }) {
+  const card = channelCards().find((item) => item.platform === platformKey);
+  const contacts = contactRows(platform);
+  const titleId = `ace-channels-manage-${platformKey}`;
+  const bot = savedBotSummary(platformKey, platform);
+  return (
+    <Modal onClose={onClose} width={480} labelledBy={titleId}>
+      <div className="p-5">
+        <div className="mb-4 flex items-center gap-3">
+          <PlatformIcon name={card.icon} size={16} box="h-8 w-8" />
+          <div id={titleId} className="flex-1 text-[15px] font-semibold">{`管理 ${card.title}`}</div>
+          <button type="button" className={iconButtonClass} aria-label="关闭" onClick={onClose}>
+            <VsIcon name="close" size={14} />
+          </button>
+        </div>
+        <div className="mb-1 text-[12px] font-semibold">机器人</div>
+        <SavedBot title={bot.title} desc={bot.desc}>
+          <button type="button" className={secondaryButtonClass} disabled={!!busy} onClick={onChangeBot}>更换机器人</button>
+        </SavedBot>
+        <div className="mt-4 mb-1 text-[12px] font-semibold">机主与授权名单</div>
+        <p className="mb-1 text-[11px] text-fg-mute">机主可以切换到任意会话;其他人只能在自己创建的会话之间切换。</p>
+        {contacts.length === 0 ? (
+          <p className="py-1.5 text-[12px] text-fg-mute">还没有授权任何人。</p>
+        ) : contacts.map((contact) => (
+          <div key={contact.principal} className="flex items-center justify-between gap-3 py-1.5">
+            <div className="min-w-0">
+              <div className="text-[12px] truncate">{contact.title}</div>
+              <div className="text-[11px] text-fg-mute truncate">
+                {[contact.kindLabel, contact.subtitle].filter(Boolean).join(' · ')}
+              </div>
+            </div>
+            <button type="button" className={clsx(linkButtonClass, 'text-danger')} disabled={!!busy}
+              onClick={() => onRevoke(contact)}>撤销</button>
+          </div>
+        ))}
+        <WizardFooter>
+          <button type="button" data-ace-dialog-primary="true" className={primaryButtonClass} onClick={onClose}>完成</button>
+        </WizardFooter>
+      </div>
+    </Modal>
+  );
+}
+
+export function ChannelsSettings() {
+  const [state, setState] = useState(() => normalizeChannelsSnapshot(null));
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+  const [busy, setBusy] = useState('');
+  const busyRef = useRef('');
+  const [wizard, setWizard] = useState(null);      // { platform, startAt, change }
+  const [managing, setManaging] = useState('');   // 平台名
+  const [revoking, setRevoking] = useState(null);  // { platform, contact }
+
+  const load = useCallback(async () => {
+    try {
+      setState(normalizeChannelsSnapshot(await api.getChannels()));
+      setError('');
+    } catch (e) {
+      setError(channelErrorText(e));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => { load(); }, [load]);
+
+  useEffect(() => {
+    const handler = (event) => setState((prev) => applyChannelsEvent(prev, event.detail || {}));
+    connection.addEventListener('message', handler);
+    return () => connection.removeEventListener('message', handler);
+  }, []);
+
+  // 执行一个操作:同一时间只允许一个;返回快照的接口直接刷新页面,其余靠 WS 推送。
+  // onError 给了就把错误交给调用方(向导里就地显示),否则弹提示。
+  const run = useCallback(async (key, action, onError) => {
+    if (busyRef.current) return false;
+    busyRef.current = key;
+    setBusy(key);
+    try {
+      const result = await action();
+      if (result && Array.isArray(result.platforms)) {
+        setState(normalizeChannelsSnapshot(result));
+      } else if (result?.platform && result.phase) {
+        // 扫码发起 / 取消
+        setState((prev) => ({ ...prev, binds: { ...prev.binds, [result.platform]: normalizeBind(result) } }));
+      }
+      return true;
+    } catch (e) {
+      const message = channelErrorText(e);
+      if (onError) onError(message);
+      else toast({ kind: 'err', text: message });
+      return false;
+    } finally {
+      busyRef.current = '';
+      setBusy('');
+    }
+  }, []);
+
+  const decide = useCallback((platformKey, request, approve) => run(`decide-${request.id}`, async () => {
+    const result = await api.decideChannelRequest(platformKey, request.id, approve);
+    toast({ kind: 'ok', text: approve ? `已批准 ${request.title}` : `已拒绝 ${request.title}` });
+    return result;
+  }), [run]);
+
+  const connect = (platformKey) => {
+    const platform = state.platforms[platformKey];
+    if (connectNeedsWizard(platform)) {
+      setWizard({ platform: platformKey, startAt: initialWizardStep(platform), change: false });
+      return;
+    }
+    run(`${platformKey}-toggle`, () => api.setChannelEnabled(platformKey, true));
+  };
+
+  return (
+    <>
+      <h2 className="text-xl font-bold mb-2">消息通道</h2>
+      <p className="text-[12px] text-fg-mute mb-5">
+        在 QQ、微信、飞书、钉钉、Telegram、Discord、LINE 里远程使用 ACECode。凭据只保存在这台电脑上;关闭 Desktop 后是否继续在线,取决于 设置 &gt; 常规 里的“退出 ACECode 后继续运行后台进程”。
+      </p>
+      {error && (
+        <div className="mb-3 px-3 py-2 rounded-md border border-danger bg-surface text-danger text-[12px] flex items-center justify-between gap-3">
+          <span>{error}</span>
+          <button type="button" className={linkButtonClass} onClick={() => { setLoading(true); load(); }}>重试</button>
+        </div>
+      )}
+      {loading ? (
+        <div className="px-3.5 py-8 text-[12px] text-fg-mute text-center">
+          <span className="ace-spinner mr-2" /> 加载中
+        </div>
+      ) : (
+        <div data-channel-cards="true" className="grid grid-cols-2 gap-3">
+          {channelCards().map((card) => (
+            <ChannelCard key={card.platform} card={card} platform={state.platforms[card.platform]} busy={busy}
+              onConnect={() => connect(card.platform)}
+              onDisconnect={() => run(`${card.platform}-toggle`, () => api.setChannelEnabled(card.platform, false))}
+              onFix={() => setWizard({ platform: card.platform, startAt: 1, change: false })}
+              onManage={() => setManaging(card.platform)}
+              onDecide={(request, approve) => decide(card.platform, request, approve)} />
+          ))}
+        </div>
+      )}
+      {wizard && (
+        <ConnectWizard platformKey={wizard.platform} platform={state.platforms[wizard.platform]}
+          bind={state.binds[wizard.platform] || normalizeBind({ platform: wizard.platform })}
+          busy={busy} run={run} startAt={wizard.startAt} change={wizard.change}
+          onDecide={(request, approve) => decide(wizard.platform, request, approve)}
+          onClose={() => setWizard(null)} />
+      )}
+      {managing && (
+        <ManageDialog platformKey={managing} platform={state.platforms[managing]} busy={busy}
+          onRevoke={(contact) => setRevoking({ platform: managing, contact })}
+          onChangeBot={() => {
+            setWizard({ platform: managing, startAt: 0, change: true });
+            setManaging('');
+          }}
+          onClose={() => setManaging('')} />
+      )}
+      {revoking && (
+        <Modal onClose={() => setRevoking(null)} width={420} labelledBy="ace-channels-revoke-title">
+          <div className="p-4">
+            <div id="ace-channels-revoke-title" className="text-[14px] font-semibold mb-2">
+              {`撤销 ${revoking.contact.title} 的授权?`}
+            </div>
+            <div className="text-[12px] text-fg-mute mb-4">撤销后立即停止处理其消息,并中止其会话正在进行的回合。</div>
+            <div className="flex justify-end gap-2">
+              <button type="button" className={secondaryButtonClass} onClick={() => setRevoking(null)}>取消</button>
+              <button type="button" data-ace-dialog-primary="true" className={dangerButtonClass} disabled={!!busy}
+                onClick={async () => {
+                  const ok = await run(`revoke-${revoking.contact.principal}`,
+                    () => api.revokeChannelAccess(revoking.platform, revoking.contact.principal));
+                  if (ok) setRevoking(null);
+                }}>撤销</button>
+            </div>
+          </div>
+        </Modal>
+      )}
+    </>
+  );
+}
diff --git a/web/src/components/Icon.jsx b/web/src/components/Icon.jsx
index ac5a23f48..bcb49d6af 100644
--- a/web/src/components/Icon.jsx
+++ b/web/src/components/Icon.jsx
@@ -1,4 +1,5 @@
 import { createElement } from 'react';
+import { toolIconName } from '../lib/toolIcons.js';
 import { fileTypeIconForPath } from '../lib/fileTypeIcons.js';
 import { ICON_VIEW_BOX, INTERFACE_ICONS, iconStrokeWidth } from '../lib/interfaceIcons.js';
 
@@ -218,7 +219,8 @@ export function FileTypeIcon({
   );
 }
 
-export function ToolSummaryIcon({ icon, ok, className = '' }) {
+export function ToolSummaryIcon({ icon, tool = '', ok, className = '' }) {
+  if (tool) return <VsIcon name={toolIconName(tool, icon)} size={14} className={className} />;
   if (!ok) return <VsIcon name="error" size={14} mono={false} className={className} />;
   const mapped = TOOL_ICON_MAP.get(icon) || (ICONS[icon] ? icon : 'ok');
   const statusIcon = mapped === 'ok' || mapped === 'warning' || mapped === 'error';
diff --git a/web/src/components/RichComposer.jsx b/web/src/components/RichComposer.jsx
index f08448645..9d6a71f39 100644
--- a/web/src/components/RichComposer.jsx
+++ b/web/src/components/RichComposer.jsx
@@ -3,6 +3,7 @@ import {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -20,6 +21,7 @@ import {
   Slate,
   useFocused,
   useSelected,
+  useSlate,
   withReact,
 } from 'slate-react';
 import {
@@ -65,6 +67,7 @@ import {
 import { filesFromTransfer, readComposerClipboardData } from '../lib/composerFileTransfer.js';
 import { isPasteBlockPart, shouldFoldPastedText } from '../lib/pastedText.js';
 import { composerSelectedTag, composerTagSelection } from '../lib/composerSelection.js';
+import { composerDomSelectionToAdopt } from '../lib/composerDomSelection.js';
 import { synchronizeComposerLeadingCommand } from '../lib/composerCommandSync.js';
 import {
   RICH_COMPOSER_CONTEXT_PASTE_ACTIONS,
@@ -255,6 +258,16 @@ function ComposerElement({ onPreviewAttachment, onRemoveAttachment, ...props })
   );
 }
 
+// Subscribes to every editor change like <Editable>, so its layout effect runs
+// in the same commit after Editable has written the new state into the DOM.
+function ComposerRenderSentinel({ onRendered }) {
+  useSlate();
+  useLayoutEffect(() => {
+    onRendered();
+  });
+  return null;
+}
+
 function currentPlainSelection(document, selection) {
   if (!selection) {
     const end = composerTextFromDocument(document).length;
@@ -563,10 +576,20 @@ function RichComposerShell({
       ? composerDocumentFromContent(externalContent, commands, attachments)
       : composerDocumentFromText(normalizedValue, commands, attachments);
   }
-  const editor = useMemo(
-    () => withComposerInlineTags(withHistory(withReact(createEditor()))),
-    [],
-  );
+  const renderPendingRef = useRef(false);
+  const editor = useMemo(() => {
+    const instance = withComposerInlineTags(withHistory(withReact(createEditor())));
+    const { onChange } = instance;
+    instance.onChange = (options) => {
+      // Cleared by ComposerRenderSentinel once React has rendered this change.
+      renderPendingRef.current = true;
+      onChange(options);
+    };
+    return instance;
+  }, []);
+  const markEditorRendered = useCallback(() => {
+    renderPendingRef.current = false;
+  }, []);
   const editableRef = useRef(null);
   const pointerSelectionRef = useRef(null);
   const seenAttachmentKeysRef = useRef(new Set(attachments.map((item, index) => composerAttachmentTag(item, index).attachmentKey)));
@@ -622,12 +645,43 @@ function RichComposerShell({
     clearCompositionSettleTimer();
   }, [clearCompositionSettleTimer]);
 
+  const publishSelection = useCallback((selection = editor.selection) => {
+    const next = {
+      ...currentPlainSelection(editor.children, selection),
+      collapsed: !selection || (Range.isCollapsed(selection) && !composerSelectedTag(editor)),
+    };
+    selectionRef.current = next;
+    onSelectionChange?.(next);
+  }, [editor, onSelectionChange]);
+
+  // Input must apply where the user sees the caret. Slate's own selectionchange
+  // sync can be left disabled (for example by a drag that never reported its
+  // end), so adopt the live DOM selection right before Slate consumes it.
+  const adoptDomSelection = useCallback(() => {
+    const range = composerDomSelectionToAdopt({
+      editor,
+      editableElement: editableRef.current,
+      renderPending: renderPendingRef.current,
+      toSlateRange: (domSelection) => ReactEditor.toSlateRange(editor, domSelection, {
+        exactMatch: false,
+        suppressThrow: true,
+      }),
+    });
+    if (!range) return false;
+    Transforms.select(editor, range);
+    publishSelection(range);
+    return true;
+  }, [editor, publishSelection]);
+
   const handleCompositionStart = useCallback((event) => {
     clearCompositionSettleTimer();
+    // Chrome composes at the DOM caret, but Slate commits event.data at
+    // editor.selection when the composition ends.
+    adoptDomSelection();
     compositionStateRef.current.active = true;
     compositionStateRef.current.settling = false;
     return onCompositionStart?.(event);
-  }, [clearCompositionSettleTimer, onCompositionStart]);
+  }, [adoptDomSelection, clearCompositionSettleTimer, onCompositionStart]);
 
   const handleCompositionEnd = useCallback((event) => {
     compositionStateRef.current.active = false;
@@ -645,15 +699,6 @@ function RichComposerShell({
     return handled;
   }, [clearCompositionSettleTimer, onCompositionEnd]);
 
-  const publishSelection = useCallback((selection = editor.selection) => {
-    const next = {
-      ...currentPlainSelection(editor.children, selection),
-      collapsed: !selection || (Range.isCollapsed(selection) && !composerSelectedTag(editor)),
-    };
-    selectionRef.current = next;
-    onSelectionChange?.(next);
-  }, [editor, onSelectionChange]);
-
   const capturePasteSelection = useCallback(() => {
     const editable = editableRef.current;
     const domSelection = window.getSelection?.();
@@ -1258,6 +1303,8 @@ function RichComposerShell({
       return true;
     }
 
+    // Deletes, tag navigation and parent shortcuts all read editor.selection.
+    adoptDomSelection();
     onKeyDown?.(event);
     if (event.defaultPrevented) return;
     if (disabled) {
@@ -1342,7 +1389,7 @@ function RichComposerShell({
     if (event.key === 'Delete' && deleteAdjacentTag(editor, 'forward')) {
       event.preventDefault();
     }
-  }, [disabled, editor, isComposingKeyEvent, onKeyDown, onSubmit, submitOnEnter]);
+  }, [adoptDomSelection, disabled, editor, isComposingKeyEvent, onKeyDown, onSubmit, submitOnEnter]);
 
   const requestClipboardTextFallback = useCallback((capturedSelection) => {
     const clipboard = window.navigator?.clipboard;
@@ -1578,6 +1625,7 @@ function RichComposerShell({
         onCompositionEnd={handleCompositionEnd}
         spellCheck
       />
+      <ComposerRenderSentinel onRendered={markEditorRendered} />
     </Slate>
   );
 }
diff --git a/web/src/components/SettingsPage.jsx b/web/src/components/SettingsPage.jsx
index 306e14661..6593ec49b 100644
--- a/web/src/components/SettingsPage.jsx
+++ b/web/src/components/SettingsPage.jsx
@@ -55,6 +55,7 @@ import { ComputerUseSettings } from './ComputerUseSettings.jsx';
 import { SummaryGenerationSettings } from './SummaryGenerationSettings.jsx';
 import { ToolRewriteSettings } from './ToolRewriteSettings.jsx';
 import { SecurityCenterSettings } from './SecurityCenterSettings.jsx';
+import { ChannelsSettings } from './ChannelsSettings.jsx';
 import { MemorySettings } from './MemorySettings.jsx';
 import { clsx, formatCount, relativeTime } from '../lib/format.js';
 import { lookupErrorMessage } from '../lib/errors.js';
@@ -446,6 +447,7 @@ export function SettingsPage({
           {activeNavKey === 'skills' && <SectionSkills />}
           {activeNavKey === 'mcp' && <SectionMCP />}
           {activeNavKey === 'connectors' && <SectionConnectors />}
+          {activeNavKey === 'channels' && <ChannelsSettings />}
           {activeNavKey === 'models' && (
             <SectionModel onModelProfileUpdated={onModelProfileUpdated} />
           )}
@@ -2767,9 +2769,9 @@ function SectionArchived() {
         }
         if (!cancelled) {
           setList(sessions);
-          setWorkspaces(groupArchivedSessions(sessions)
-            .map(({ key, name, path }) => ({ key, name, path }))
-            .sort((a, b) => a.name.localeCompare(b.name)));
+          setWorkspaces(groupArchivedSessions(sessions, {
+            workspaceOrder: (Array.isArray(result?.workspaces) ? result.workspaces : []).map((workspace) => workspace.hash),
+          }).map(({ key, name, path }) => ({ key, name, path })));
         }
       })
       .catch((e) => {
@@ -2782,8 +2784,11 @@ function SectionArchived() {
   }, []);
 
   const groups = useMemo(
-    () => groupArchivedSessions(list, { query: search, workspaceKey, sortOrder }),
-    [list, search, workspaceKey, sortOrder],
+    () => groupArchivedSessions(list, {
+      query: search, workspaceKey, sortOrder,
+      workspaceOrder: workspaces.map((workspace) => workspace.key),
+    }),
+    [list, search, workspaceKey, sortOrder, workspaces],
   );
   const visibleItems = useMemo(() => groups.flatMap((group) => group.items), [groups]);
   const workspaceOptions = useMemo(() => workspaces.map((workspace) => ({
diff --git a/web/src/components/Sidebar.jsx b/web/src/components/Sidebar.jsx
index c8c1e5ff9..1e7ac6687 100644
--- a/web/src/components/Sidebar.jsx
+++ b/web/src/components/Sidebar.jsx
@@ -27,6 +27,7 @@ import BrandLogo from './BrandLogo.jsx';
 import { api } from '../lib/api.js';
 import { sessionWorktreeFromSources } from '../lib/sessionJump.js';
 import { connection } from '../lib/connection.js';
+import { channelBoundLabel, channelBoundPlatform } from '../lib/channelsSettings.js';
 import { tr } from '../i18n/index.js';
 import {
   DESKTOP_CONTEXT_ACTION_EVENT,
@@ -802,6 +803,9 @@ function SessionRow({
   const title = sessionDisplayTitle(s, s.name || '');
   const sessionMarker = sidebarSessionMarker(s);
   const remoteControlBound = Boolean(s.remote_control_bound ?? s.remoteControlBound);
+  // 被 QQ / Telegram 会话绑定的会话显示同一个电脑图标;/rc 的专属行为(换绑动画等)仍只看
+  // remoteControlBound(openspec add-desktop-im-channels design D12)。
+  const channelPlatform = remoteControlBound ? '' : channelBoundPlatform(s);
   const hoverDetails = sessionHoverDetails(s);
   const hasHoverDetails = Boolean(hoverDetails);
   const hoverCardId = useId();
@@ -983,6 +987,7 @@ function SessionRow({
       data-desktop-session-title={title || undefined}
       data-desktop-session-archive="true"
       data-remote-control-bound={remoteControlBound ? 'true' : undefined}
+      data-channel-bound={channelPlatform || undefined}
       data-sidebar-pinned-key={pinned ? rowKey || undefined : undefined}
       data-sidebar-pinned-id={pinned ? s.id || undefined : undefined}
       data-sidebar-pinned-workspace={pinned ? pinScope || undefined : undefined}
@@ -1098,7 +1103,7 @@ function SessionRow({
           aria-describedby={hoverCardVisible ? hoverCardId : undefined}
           aria-label={remoteControlBound
             ? tr('remoteControl.connectedSessionAria', { title })
-            : title}
+            : channelPlatform ? `${title},${channelBoundLabel(channelPlatform)}` : title}
           className="ace-sidebar-session-title-button ace-sidebar-tree-content flex min-w-0 w-full items-center gap-1.5 px-0 py-[4.5px] bg-transparent text-left cursor-pointer"
         >
           {remoteControlBound && (
@@ -1109,6 +1114,12 @@ function SessionRow({
               data-remote-control-session-icon="true"
             />
           )}
+          {channelPlatform && (
+            <span className="inline-flex shrink-0" title={channelBoundLabel(channelPlatform)}
+              data-channel-session-icon={channelPlatform}>
+              <VsIcon name="computer" size={18} className="text-accent" />
+            </span>
+          )}
           <SidebarSessionTitle title={title} />
         </button>
       )}
@@ -1144,12 +1155,7 @@ function SessionRow({
               e.stopPropagation();
               onTogglePin?.(s, !pinned);
             }}
-            className={clsx(
-              'ace-session-pin-btn ace-sidebar-row-hover-action w-[18px] h-7 rounded items-center justify-center shrink-0 transition text-fg-mute hover:text-fg hover:bg-surface-hi',
-              pinned
-                ? 'flex'
-                : 'hidden group-hover:flex group-focus-within:flex',
-            )}
+            className="ace-session-pin-btn ace-sidebar-row-hover-action w-[18px] h-7 rounded items-center justify-center shrink-0 transition text-fg-mute hover:text-fg hover:bg-surface-hi hidden group-hover:flex group-focus-within:flex"
             title={pinned ? '取消置顶' : '置顶'}
             aria-label={pinned ? '取消置顶' : '置顶'}
           >
diff --git a/web/src/components/SubagentPanel.jsx b/web/src/components/SubagentPanel.jsx
index 111921ebf..35904fdb8 100644
--- a/web/src/components/SubagentPanel.jsx
+++ b/web/src/components/SubagentPanel.jsx
@@ -43,7 +43,7 @@ import {
   taskStatsParts,
   taskStatusLabel,
 } from '../lib/subagentTasks.js';
-import { VsIcon } from './Icon.jsx';
+import { ToolSummaryIcon, VsIcon } from './Icon.jsx';
 import { TranscriptItems } from './TranscriptItems.jsx';
 import { AttachmentTextLoaderContext } from './AttachmentTextLoaderContext.jsx';
 
@@ -88,6 +88,7 @@ function TaskCard({ task, nowMs, onAbort, onOpenTranscript }) {
       </div>
       {stats.length > 0 && (
         <div className="text-[11px] text-fg-mute truncate" title={stats.join(' · ')}>
+          {task.lastTool && <ToolSummaryIcon tool={task.lastTool} ok className="inline-flex align-middle mr-1" />}
           {stats.join(' · ')}
         </div>
       )}
diff --git a/web/src/components/ToolBlock.jsx b/web/src/components/ToolBlock.jsx
index f6272fcde..3dfc4861d 100644
--- a/web/src/components/ToolBlock.jsx
+++ b/web/src/components/ToolBlock.jsx
@@ -406,7 +406,7 @@ export const ToolBlock = memo(function ToolBlock({ entry, onReviewToggle, sessio
             : 'submit'}
         >
           <ActivityLine
-            icon={<ToolSummaryIcon icon={completedSummary.icon} ok={!askCancelled} className={askCancelled ? 'text-fg-mute' : 'text-ok'} />}
+            icon={<ToolSummaryIcon tool={tool} icon={completedSummary.icon} ok={!askCancelled} className={askCancelled ? 'text-fg-mute' : 'text-ok'} />}
             label={completedSummary.verb || title || tool || 'AskUserQuestion'}
             detail={completedSummary.object || ''}
             trailing={liveElapsed > 0 ? <span className="tabular-nums">{formatElapsed(liveElapsed)}</span> : null}
@@ -438,7 +438,7 @@ export const ToolBlock = memo(function ToolBlock({ entry, onReviewToggle, sessio
         className="ace-tool-activity min-w-0"
       >
         <ActivityLine
-          icon={<ToolSummaryIcon icon={completedSummary.icon} ok={ok} className={ok ? 'text-ok' : 'text-danger'} />}
+          icon={<ToolSummaryIcon tool={tool} icon={completedSummary.icon} ok={ok} className={ok ? 'text-ok' : 'text-danger'} />}
           label={completedSummary.verb || title || tool || '工具完成'}
           detail={bashCommand || completedSummary.object || ''}
           trailing={(
@@ -498,6 +498,8 @@ export const ToolBlock = memo(function ToolBlock({ entry, onReviewToggle, sessio
     >
       <ActivityLine
         running
+        preferIconWhileRunning
+        icon={<ToolSummaryIcon tool={tool} icon={genericSummary.icon} ok />}
         spinnerStatic={!liveProgress}
         label={genericSummary.verb || title || displayOverride || tool || '正在执行工具'}
         detail={bashCommand || genericSummary.object || ''}
diff --git a/web/src/i18n/sourceCatalog.generated.js b/web/src/i18n/sourceCatalog.generated.js
index 367ad002e..abeb8b32a 100644
--- a/web/src/i18n/sourceCatalog.generated.js
+++ b/web/src/i18n/sourceCatalog.generated.js
@@ -23,10 +23,12 @@ export const sourceCatalogs = {
     "s_01bf3b34f431074f": "此页面不符合 App Transport Security 的安全连接要求。",
     "s_01ca13e5a1ebdc8d": "勾选的条目固定显示在侧栏,其余条目收在「扩展」菜单里;拖动行可调整顺序。",
     "s_01e1429e4860a2d5": "每周代码变更总结",
+    "s_01ebb09c9bad848f": "飞书(中国)",
     "s_020754edb04dde8d": "macOS 系统通知权限",
     "s_0215ff0b3cce53f1": "反馈内容",
     "s_0220aafc260ee131": "启用 hooks 功能后,已配置的钩子会显示在此处",
     "s_025486bcb86499e3": "请选择摘要模型",
+    "s_027be81bc401b0cd": "连接失败,原因已写入日志。确认凭据无误后重试,或回到上一步更换。",
     "s_029d7b3375ad16aa": "写入规则文件",
     "s_02b411ce6d16f108": "动态上下文",
     "s_02bcdbc5a1453cb0": "复制相对路径",
@@ -45,8 +47,10 @@ export const sourceCatalogs = {
     "s_051836569928a9f9": "编辑",
     "s_054b73a972372bdb": "未找到可用终端",
     "s_05564f10bcba6ae8": "同一专家可属于多个 Tag",
+    "s_057dc352ed0a0a29": "更换机器人",
     "s_0580fcee37e02012": "删除失败：",
     "s_05a531a083e68807": "复制 {{p0}} 验证码 {{p1}}",
+    "s_05abefa30a624a8a": "派发任务",
     "s_05df17e0e401d645": "让 Agent 帮你重构、修 bug、加测试",
     "s_05efef8465e0c666": "git 响应超时(仓库可能很大)",
     "s_05fdf30411d98d32": "沙箱",
@@ -67,6 +71,7 @@ export const sourceCatalogs = {
     "s_07918dbd4c70b182": "缩小预览",
     "s_07a10608cd7a1e0c": "关闭后沙箱内命令无法联网(macOS / Linux 真隔离)",
     "s_07b0e6eadae125e1": "目标版本",
+    "s_07bc10c7295f8dae": "机主与授权名单",
     "s_07bf8b28ae3680e0": "专家组件类型",
     "s_07deea1ebeb8c9f8": "读取失败 (HTTP {{p0}})",
     "s_07ee23a0924d3d0b": "由于你中断了当前响应，队列已暂停",
@@ -82,6 +87,7 @@ export const sourceCatalogs = {
     "s_08af65aa6bfa1a95": "手写的规则文件只读展示,请直接编辑文件;解析失败的文件整体不生效。",
     "s_08ba7ec0955d1d28": "正在启动浏览器",
     "s_08d43bdc4dcb6253": "可更新",
+    "s_08e5a3f74d4c6894": "用手机 QQ 扫一扫,按提示创建并授权机器人",
     "s_08e9d9ef7d382947": "仅拦截写入",
     "s_08f10fb5ebba9e65": "使用深色背景，关闭后使用浅色背景",
     "s_0970eb5b921e82c5": "{{p0}} 行",
@@ -106,6 +112,7 @@ export const sourceCatalogs = {
     "s_0acd4d885ae0c69a": "源文件夹",
     "s_0ad947db2d9ee20a": "daemon 退出时运行被中断",
     "s_0ade55ea5a89bf7d": "写文件失败",
+    "s_0adea32a9fd1dcbe": "扫码成功,你已是机主",
     "s_0ae64c633fbe0f42": "检查过期依赖、安全风险和可控范围内的技术债。",
     "s_0ae7312510f4b495": "收起详情",
     "s_0af42a6e2915abaa": "删除记忆失败",
@@ -131,6 +138,7 @@ export const sourceCatalogs = {
     "s_0c8320ac03732e4c": "需要访问令牌",
     "s_0c869dac8a4aa550": "请输入 bash.exe 完整路径",
     "s_0cc2ca1cf8347d79": "任务完成通知已关闭",
+    "s_0ced3f40670a5ac1": "Lark(海外)",
     "s_0cf8b14f4651f4de": "上周",
     "s_0d0cbac2eee54113": "重命名",
     "s_0d0e1a86b3aa7877": "用户",
@@ -142,12 +150,14 @@ export const sourceCatalogs = {
     "s_0d94ad38844747ce": "切换失败:",
     "s_0d966a3d69ee069c": "关闭后所有命令直接在当前用户权限下执行,自动模式的未知命令改为逐条确认",
     "s_0de50760cb250e32": "移除模型 {{p0}}",
+    "s_0df737cb62bb5175": "群",
     "s_0e0163080d2e4ad4": "无法获取文件路径",
     "s_0e0c2d7597ef508d": "已缺失",
     "s_0e1a7040390fb03e": "新建项目",
     "s_0e700e0f522f37ff": "比较基线:{{p0}}(仅切换查看对象,不会 checkout)",
     "s_0e993148f8f5d3d2": "Grok 登录已失效，请重新连接",
     "s_0eab58baf452449c": "请输入完整的绝对路径,例如 C:\\Users 或 /home",
+    "s_0eb01c40432b05a9": "连接中断,正在自动重试",
     "s_0eca7afbf4f68601": "搜索技能名称或描述...",
     "s_0ecd009b61757eae": "创建独立 worktree，不包含未提交的修改。",
     "s_0f415f8b2bbbb37a": "读取运行记录失败：",
@@ -161,12 +171,14 @@ export const sourceCatalogs = {
     "s_10e80ac177155143": "消息不能为空",
     "s_111448a2e1a82306": "还有 {{p0}} 个字段",
     "s_11152b370ff3e7ca": "超高画质模型",
+    "s_1117493dfd5708d1": "在钉钉里找到这个机器人,私聊它发送下面的 6 位数字。",
     "s_1123245d1bed08b2": "规则",
     "s_11448fff91a477dc": "已生成",
     "s_1159250ae5748529": "无效的关闭窗口行为",
     "s_117b19fd23b61edb": "按命令前缀决定放行、询问或禁止。前缀按空格分词,git status|diff 表示第二个词可以是任一个。「放行(沙箱外)」会跳过沙箱,只给确实需要的命令;解释器、shell、rm、sudo 这类前缀不能放行。",
     "s_117c113c3b45cf89": "排队",
     "s_1198cb9da295145d": "新建会话默认使用此模式,当前会话会同步切换",
+    "s_11a4dc9fc810be2f": "机器人的消息接收模式选「Stream 模式」,在「权限管理」开通企业内机器人发送消息权限,然后发布应用。",
     "s_11a6ac8794688be8": "命中询问规则",
     "s_11b999fc4610de85": "联网",
     "s_11cb87897cfb7e7b": "{{p0}}能力",
@@ -186,6 +198,7 @@ export const sourceCatalogs = {
     "s_132411ba41da7354": "推理",
     "s_132a029e79ec9872": "与智能体共享",
     "s_13357fcd2d59d851": "命令前缀不能为空",
+    "s_13439ef69aeff4f2": "在「凭证与基础信息」复制 App ID 与 App Secret,填到下面。",
     "s_134a1a3e2b52b04f": "收起整个右侧面板",
     "s_134fdd6479c8036b": "发送 (Enter)",
     "s_13670a878cf6f01d": "ACECode 升级",
@@ -200,14 +213,17 @@ export const sourceCatalogs = {
     "s_13f6a415ac664be2": "从当前 Provider 探测真实模型列表",
     "s_140b07fe3f9f7d48": "需要下载",
     "s_1417bae3d17d6405": "收起图像",
+    "s_142cf02f83d4e7ab": "撰写回复",
     "s_14357c0d6ca270df": "请检查地址是否正确，然后重试。",
     "s_14381a6ef00a1253": "定时测试与问题修复",
+    "s_143dab9db74c3131": "连接完成",
     "s_145219e726b87790": "隐藏",
     "s_145eb48a326b5d27": "工具重写",
     "s_148d195e21b05db5": "配置",
     "s_14cbad1d857ee3e6": "连接已断开，停止状态尚未确认",
     "s_14d1e349b14010a9": "取消下载",
     "s_14e7acfc08afa9e9": "浏览器组件已停止",
+    "s_14ee02a96d9bca6d": "已连接 · {{p0}}",
     "s_150dd0cecdc803d0": "当前工作区",
     "s_150f3c28d9d036af": "已清除标题",
     "s_155c2f5d0a3b2394": "笔记本",
@@ -236,24 +252,32 @@ export const sourceCatalogs = {
     "s_1832990660bb60c2": "函数",
     "s_183b5f823fdb5522": "添加工作区失败:",
     "s_18435419f154847b": "命令前缀",
+    "s_1843acb8c6ea0f47": "私信机器人或在服务器频道里 @它 下达指令,结果回到频道。",
     "s_184568b57e5e6d3f": "正在生成测试图片…",
     "s_1847a84db6d5fc1a": "权限模式切换失败:",
     "s_18565a5455a0a875": "加载沙箱设置失败",
+    "s_18578640315b5b33": "更新待办",
     "s_1882a447d5f76d5f": "反馈内容不能超过 10000 字",
+    "s_188397c445996182": "已由另一个 ACECode 连接",
     "s_18850bf66a4ba4c6": "模型申请临时加宽沙盒权限",
+    "s_1903b018a3b98d7d": "{{p0}} 机器人",
     "s_19086bec77d5e5e5": "已自动兼容系统命名规则",
+    "s_190eedb7bfaa8609": "追加任务",
     "s_191041794ad98158": "(所有匹配)",
     "s_1910636fddbffe3e": "读取应用控件并操作鼠标和键盘",
     "s_19107d868966ff2c": "会话标题",
     "s_194b5dba3c63f537": "推理设置",
     "s_1964dafada0807b5": "Git 分支",
     "s_19af3dcd414d81df": "{{p0}} 个附件",
+    "s_19bf536853e2e78a": "协作",
     "s_19bfb1631d25a204": "正在保存主题…",
     "s_19cfa7d09d8dd287": "派遣中…",
     "s_1a0bf11a28779888": "选择后填入真实聊天框，不会自动发送",
     "s_1a16ea81ee6a29e4": "网站无法完成跳转，请稍后重试。",
+    "s_1a474c3207ed49f4": "待命",
     "s_1a4c6ebd7bbdbaa8": "还没有填写能力介绍。",
     "s_1a52bda1e037f2c3": "执行、编程或处理任务时使用",
+    "s_1a6c41c6ee173bab": "已绑定到 {{p0}}",
     "s_1a7224bf1e427ee4": "分叉失败:无 session_id",
     "s_1a7e48179574fffa": "收起变更摘要",
     "s_1a7eef17e199fa07": "收起命令详情",
@@ -265,6 +289,7 @@ export const sourceCatalogs = {
     "s_1ae7a34c1452785e": "Markdown 所见即所得编辑器",
     "s_1afed6a81a2512d2": "选择模型",
     "s_1b14bd33bab15a6d": "{{p0}} 继承全局",
+    "s_1b442420620b3bb4": "现在可以在飞书里私聊机器人了。把机器人拉进群后 @ 它,第一次需要在设置页批准。",
     "s_1b479e1420fb0342": "放行目录",
     "s_1b4bc8cfe06cb405": "标记为已读",
     "s_1b58f84ec946fe67": "职业 / 定位",
@@ -312,6 +337,7 @@ export const sourceCatalogs = {
     "s_1f4b8e02fe0eb7ab": "可选择多个模型，确认后一次性回填到新增模型表单。",
     "s_1f6c6927e129a5f5": "请升级并重启 ACECode daemon 后再试。",
     "s_1f79c9f362dc9d4b": "外观设置保存失败，已恢复上次配置：",
+    "s_1f9d55088d4f8ec0": "机主可以切换到任意会话;其他人只能在自己创建的会话之间切换。",
     "s_1fca6787d35baa53": "进入 Plan",
     "s_1fcd48a731ea363a": "原生选择器返回无效结果",
     "s_1fe3eb68a68b187d": "放行并记住",
@@ -334,6 +360,7 @@ export const sourceCatalogs = {
     "s_21482b7f3029698f": "设为主理人",
     "s_21493a0f78021d9b": "选择当前文件夹",
     "s_2156709a76aa43e6": "输入消息…",
+    "s_2157f1235d2a58ee": "群 {{p0}} 的成员 {{p1}}",
     "s_21a08761b9914419": "一行一条。~ 表示家目录,:workspace_roots 表示当前工作区根,:tmpdir 表示沙箱临时目录,其余必须是绝对路径。黑名单支持 **/.env 这类通配。",
     "s_21a9727afd60df42": "已开启蜂群模式（星型）",
     "s_21cab4f2e52fbfef": "未命名对话",
@@ -342,6 +369,7 @@ export const sourceCatalogs = {
     "s_2217610d8e605cdc": "打开全局 Skill 目录",
     "s_222c9c161b8907d6": "当前会话已多次压缩，建议在新会话中接续当前工作。",
     "s_222eac7780eaef4d": "模型配置已检查",
+    "s_225a51a3b48fddf4": "在 Discord 里私信这个机器人(需要和它在同一个服务器),发送下面的 6 位数字。",
     "s_227ea7277bfc00e9": "加载 MCP 失败:",
     "s_228d8b711ccf3ab3": "提交反馈",
     "s_228f61d57a0a4568": "已明确选择",
@@ -362,9 +390,11 @@ export const sourceCatalogs = {
     "s_23f176008ae4f3bd": "原生文件数据无效",
     "s_246e46c2a4189cb5": "重命名失败:",
     "s_248e8e2921bcc92c": "会话 conversation messages auto collapse fold expand tools",
+    "s_251dee09f7adbd2e": "请先填写凭据",
     "s_2529b19bc41c0e9e": "请求格式错误",
     "s_2539cf900d5b8d37": "正在安装更新",
     "s_255c8d56e8bb1295": "无匹配结果",
+    "s_2560c96f89c6fea0": "在 LINE Official Account Manager 建立官方账号,并在「设定 > Messaging API」启用 Messaging API。",
     "s_257bbcc44c839db4": "修改时间",
     "s_257c21aae4198b7e": "设置与再次查看",
     "s_25c76c88d05b627c": "原生文件系统桥接不可用",
@@ -374,18 +404,23 @@ export const sourceCatalogs = {
     "s_25ec0421b03bc4f3": "拖动调整右侧栏宽度",
     "s_261dba7261ed8c05": "描述不能为空",
     "s_2623156dcd71bf2d": "星号",
+    "s_264333fb5458a573": "准备调用工具",
     "s_2657124b1481b789": "项目提供",
     "s_267c4a7a86dd1849": "全部类型",
     "s_26ab0eee67e8c707": "已调用工具",
     "s_26c8aefe6fbfa744": "沙箱、文件与命令策略,以及每一次判定的审计记录。",
     "s_26da3cee0bb25151": "等待用户回复 AskUserQuestion",
     "s_26df939b25bc7b02": "排队消息内容",
+    "s_270dd2ebfcbec271": "在 LINE 里把官方账号加为好友,私聊它发送下面的 6 位数字。",
     "s_2719a8ea304b8cbf": "从",
     "s_2719f7ce2ace6db7": "无法打开 macOS 通知设置",
     "s_2721b6c32975b55d": "远程 Web 连接",
+    "s_27389885c97c4ab1": "钉钉",
+    "s_273f40d0251a8261": "打开钉钉开放平台",
     "s_2745ccb884fcf6ab": "意见反馈",
     "s_27586f180db1c812": "已重命名",
     "s_2812f6c1263c96a9": "已删除“{{p0}}”",
+    "s_281b0924bb9c5a16": "用微信扫一扫并在手机上确认;扫码的微信号就是机主,也是唯一能使用它的人。",
     "s_28200a87c40ced80": "导入并应用",
     "s_28321cb9b77f137c": "从这里分叉",
     "s_2834cf755087f50d": "摘要生成",
@@ -425,6 +460,7 @@ export const sourceCatalogs = {
     "s_2c7dfb7f0b25589e": "当前对话内容查找",
     "s_2c843e836a4d4422": "保存关闭窗口设置失败:",
     "s_2c8855fc8ab8f5fb": "未发现可用的非本机网络地址，请检查网卡连接。",
+    "s_2c8904ba4a192db8": "创建机器人",
     "s_2ca1a16a870f47d3": "未找到相关设置",
     "s_2cc0b5d70839d137": "Mermaid 源码",
     "s_2cd0f3be8738a86c": "取消",
@@ -478,6 +514,8 @@ export const sourceCatalogs = {
     "s_31ebdbfa17b81a02": "模型已保存",
     "s_32058ae99d61249c": "无法获取迁移进度：{{p0}}",
     "s_321e4914f68c1db0": "未知升级错误",
+    "s_3221a042ea3677a8": "重新生成",
+    "s_323bf944ea7c06e1": "在飞书私聊或群里 @机器人 下达指令,结果回到聊天窗口。",
     "s_3264ce720a9e420d": "主题正在下载，请稍候",
     "s_326d1d537e72f82d": "正在启动或停止反向代理",
     "s_327f00da9fc2ec36": "隐藏详情面板",
@@ -504,15 +542,18 @@ export const sourceCatalogs = {
     "s_34b3cac2a496d263": "模型目录",
     "s_34c3c3b2bd45600d": "展开全部 diff",
     "s_34f7336d39831fca": "全部关闭",
+    "s_350a7736d0d4cb03": "绑定机主",
     "s_3548b099890e187f": "模型用量明细",
     "s_3568d317c8161ad4": "这是一个内嵌浏览器。",
     "s_357211096f78cdb8": "设为默认",
     "s_3590fba381ad57f0": "选中文本操作",
     "s_35c52c32418a2678": "将删除全部 {{p0}} 条记录,无法恢复。需要留档请先导出。",
     "s_35cda8a7052dec20": "迁移失败",
+    "s_3615b021b8af5e82": "收尾",
     "s_3620d3d986f14584": "关闭模型弹窗",
     "s_3625f9fa2f9c629a": "拒绝执行命令",
     "s_364970d8168ca5fe": "发送中…",
+    "s_3687f953cfe85fb8": "取消连接",
     "s_369078855fa122f7": "只读工具调用",
     "s_36f33adaf0942634": "确认",
     "s_3703e47860f64a12": "文件不存在",
@@ -522,13 +563,16 @@ export const sourceCatalogs = {
     "s_375f5091e213f094": "路径都是 daemon 所在机器上的路径",
     "s_377e4422342c71f7": "问题反馈已上传",
     "s_3785cba81d184679": "当前工作区记忆",
+    "s_378eaca774bb9551": "扫码登录",
     "s_37979829426b0cdb": "工作区",
+    "s_37a41b2e983b06ee": "使用技能",
     "s_37c427d9f5dc817d": "默认模型已设为 ",
     "s_37d36b087f49c6d2": "选择专家组件",
     "s_37e4e42c314102da": "图像",
     "s_381117baedb79e1a": "选择 Provider 和模型后，只显示当前连接真正支持的配置。",
     "s_381796352dc0301d": "配置已保存但未能生效，请重试",
     "s_3819d5e4aa5dba68": "钢笔",
+    "s_38744132b501a1eb": "提问",
     "s_38c043e08502e710": "个性化",
     "s_38cd88ed8b3ddbf1": "复制完整输出",
     "s_38d456bbdb81317c": "按 Tag 筛选",
@@ -536,6 +580,7 @@ export const sourceCatalogs = {
     "s_390fd9bc7d9d7a2a": "审计中心",
     "s_392d0dceb45998d3": "极高",
     "s_39592d688f12a5a6": "已存在同名条目",
+    "s_3969d8203ae05775": "扫码连接二维码",
     "s_39932f24fe11a6ba": "文件",
     "s_39a9046f9c8c993d": "最近使用",
     "s_39b068ea492a4f9a": "模型能力标签无效",
@@ -577,10 +622,12 @@ export const sourceCatalogs = {
     "s_3db7b06b5f6de0e0": "工作目录",
     "s_3dcff5522afda275": "提示词缓存命中率",
     "s_3dd1245c155aba60": "模型配置不可用，已保留当前连接",
+    "s_3dd922527fba482d": "把机器人拉进群后 @ 它,第一次需要在设置页批准。",
     "s_3de42d7c68d442e5": "单次",
     "s_3df739dcd8a069eb": "最近会话记录",
     "s_3e04f83df97fa6f2": "最早更新",
     "s_3e48e68ed87a9add": "点击空白处或按 / 直接输入路径",
+    "s_3e6221be3922f850": "用微信扫一扫,并在手机上确认",
     "s_3e65bba57b173f30": "粘贴的文本太长，超出 /{{p0}} 的上限（{{p1}} 字节）。去掉命令可作为普通消息发送，或缩短内容",
     "s_3e7d75b94f3a1f26": "加载工具重写配置失败",
     "s_3ea0e6e41518ea24": "空目录",
@@ -632,6 +679,7 @@ export const sourceCatalogs = {
     "s_42e1b73173a3b1d4": "确认专家切换状态失败：{{p0}}",
     "s_432a6c3328243eee": "无法连接 xAI 设备授权服务",
     "s_4334aa1fdaa5a8c1": "已从会话中提炼、尚未整合进记忆的观察",
+    "s_433779053c77eea8": "机器人 {{p0}}",
     "s_434203a723b4614e": "已更新",
     "s_4342d572b0ee2718": "主会话仍可继续输入",
     "s_434c7efecbad5725": "请选择执行时间",
@@ -641,11 +689,13 @@ export const sourceCatalogs = {
     "s_4382c23e9e50479f": "Agent 已完成计划,请求批准后退出 Plan 模式。",
     "s_43911903e1cf7e63": "已复制预览内容",
     "s_43cad95bdcdcc30d": "升级失败",
+    "s_43ce458cae49a1ad": "思考中",
     "s_43d7d2b51d75fa42": "创建项目",
     "s_43db2741a745b179": "启用服务器",
     "s_43f3dc12a6077835": "正在启动…",
     "s_43f4a4d322d58a5b": "已编辑 {{p0}}",
     "s_43fc32e85fb21c53": "进行中的目标",
+    "s_43fcef33a825715a": "把 Token 粘贴到下面;验证通过后用邀请链接把机器人拉进你的服务器。",
     "s_43fd0fc1e9ae1edb": "名称冲突已处理",
     "s_4430768f253a5d6d": "开启工具重写，并对之后的模型请求生效",
     "s_443cb29217829285": "查看擅长领域后派遣到新任务，或维护自己的专家和专家团。",
@@ -681,6 +731,7 @@ export const sourceCatalogs = {
     "s_475ac58abf66032b": "读取根目录失败:{{p0}}",
     "s_476c022a773e1f82": "请关闭其他 ACECode 窗口后再迁移",
     "s_478211dd029aa604": "网站的安全证书无效或与当前地址不匹配。",
+    "s_47b50c43e14ca6ba": "扫码成功",
     "s_47c99fb0ddf2cffa": "{{p0}} – {{p1}} 累计使用了 {{p2}} 个 Token",
     "s_47f22728ee1600ed": "状态消息:",
     "s_481acc2c1413db38": "图像生成",
@@ -691,6 +742,7 @@ export const sourceCatalogs = {
     "s_4871613a44be8d7a": "默认打开文件和文件夹的位置",
     "s_487422ef0c4e25b6": "首页标题",
     "s_48807d75530c1b03": "找不到这条排队消息",
+    "s_4888c0a26e905c1f": "用户 {{p0}}",
     "s_48d75d4b7e92d9f2": "切换到项目",
     "s_48f78f1abeca0c47": "粘贴内容较大（{{p0}}），将分 {{p1}} 段上传",
     "s_490a88b8ae9d4a2e": "该模型已不存在,请刷新",
@@ -706,12 +758,14 @@ export const sourceCatalogs = {
     "s_4a6d8d490c54d438": "允许一次",
     "s_4a83accbad2c11e1": "开场白",
     "s_4a8d6841b4023edf": "确认导入",
+    "s_4aa95aa725909efe": "把机器人拉进你的服务器",
     "s_4ab32793197b28db": "所选模型已不可用，定时任务已停用",
     "s_4ac9db43b40c292d": "当前后台服务不支持电脑操控，请更新 ACECode 并重启后重试",
     "s_4ad732f1d78f6725": "后台进程状态",
     "s_4ad8aa6461e64127": "上一题 (Shift+Tab)",
     "s_4af8f4c6dd2e233e": "大脑",
     "s_4afad488b461b58f": "侧边聊天记录",
+    "s_4b19c2f91cd3f418": "消息通道只能在运行 ACECode 的这台电脑上设置",
     "s_4b427656a253ca1e": "请完全退出并重新启动 ACECode",
     "s_4b47dbae97ba938a": "提示词",
     "s_4b50c9fa24dcafa3": "未配置模型",
@@ -733,6 +787,7 @@ export const sourceCatalogs = {
     "s_4cc7b00050cb1c21": "行",
     "s_4cca8a4406aea952": "需要确认",
     "s_4ce87e7fe2b6e95d": "文件或文件夹",
+    "s_4ceae06adf5b9199": "撤销后立即停止处理其消息,并中止其会话正在进行的回合。",
     "s_4d0680f9efaef147": "未读",
     "s_4d2b19065afe4b07": "LSP 已开启:{{p0}}",
     "s_4d3f6a081ea86097": "彻底删除失败:",
@@ -755,7 +810,9 @@ export const sourceCatalogs = {
     "s_4ef515abfdb8690d": "安装包",
     "s_4f01af9093fc9e59": "无法连接到此网站",
     "s_4f021f59121c6827": "等待执行",
+    "s_4f1f6ea2b75de587": "消息通道",
     "s_4f2bf16cc26825e8": "取消自定义答案",
+    "s_4f3bac187963a04a": "管理 {{p0}}",
     "s_4f5b0e563a452c80": "刷新技能列表",
     "s_4f61317e9307ad3e": "访问被拒",
     "s_4fca07787f3ef1ec": "移除这个待发送附件？",
@@ -763,6 +820,7 @@ export const sourceCatalogs = {
     "s_4fe5ca6370a901ef": "ACECode 本地工具分类",
     "s_4fed9b0a87376127": "主题工坊",
     "s_5002a3c1c2822955": "原生与受管",
+    "s_500b6710a6f009cc": "在「版本管理与发布」创建版本并发布,可用范围要包含你自己。",
     "s_5019872ac7610542": "无法安全打开此网站",
     "s_5026a63b58cdf048": "执行中",
     "s_50563579e4119e75": "其它规则文件",
@@ -798,6 +856,7 @@ export const sourceCatalogs = {
     "s_52b06532811be3e4": "与另一条规则重复",
     "s_52b44d4d2c562541": "连接 xAI",
     "s_52d25a9e30ba94f1": "关于",
+    "s_52ebdbe6cf99a77c": "还没有授权任何人。",
     "s_52f79fed15ec2723": "当前模型",
     "s_52fb62f878dcdbef": "主题包校验失败，请重新下载",
     "s_5305d3b2b3f1648f": "爆米花",
@@ -828,9 +887,11 @@ export const sourceCatalogs = {
     "s_55db57105231bd95": "工作空间不可用",
     "s_55ef676879f7cca3": "diff 过大,请在终端查看",
     "s_561817f0252936a9": "放行",
+    "s_562834f547655a37": "搜索代码",
     "s_5653d97cdf569cb9": "系统防火墙、路由器或云安全组可能仍需放行代理端口。公网访问仍建议使用可信 VPN，并在上游配置 HTTPS。",
     "s_56627c94a9decee6": "最大输出 Token",
     "s_566e5f182a63185d": "正在压缩主题资源…",
+    "s_5670da45d1d6e526": "App ID(cli_ 开头)",
     "s_567146d66825e213": "开启自动换行",
     "s_56964754c2e1ab57": "反向代理已监听 {{p0}}:{{p1}}",
     "s_569af1a47dbdf053": "最新",
@@ -852,6 +913,7 @@ export const sourceCatalogs = {
     "s_57e4fcb2dad50b5c": "远程 Web 模式已开启",
     "s_57eb46dacc97defb": "在任务列表每一行右侧显示最近活动时间，关闭后仍可在悬停卡片里查看",
     "s_5804b9cca84304ff": "清空侧边聊天",
+    "s_58210afb340c2c5e": "链接 10 分钟内有效,只能用一次。",
     "s_5835048333dad1d6": "选择自定义答案",
     "s_584f28c1077647a9": "正在取消...",
     "s_5868e5f7632072d9": "拒绝 {{p0}}",
@@ -905,8 +967,10 @@ export const sourceCatalogs = {
     "s_5d7fd21f1e3ca6b4": "复制消息",
     "s_5d817dbb5da09259": "导入主题返回了无效结果，请刷新后重试",
     "s_5d937ed111134879": "模型能力",
+    "s_5ddcb16ab6fcb808": "查看成员",
     "s_5ddffd77ea7fedae": "正在加载已保存模型…",
     "s_5e56bec8550f499d": "请选择文件夹",
+    "s_5e78c941de4a98ed": "连接 {{p0}}",
     "s_5e80c1e561d45b11": "选择权限模式",
     "s_5e8e7af57abbcbcf": "删除中…",
     "s_5eaefa4a3950e8a3": "请选择新路径",
@@ -917,11 +981,14 @@ export const sourceCatalogs = {
     "s_5f53727059cdc69a": "输入你的答案",
     "s_5f5a4c5fb8ab71d6": "输入框当前不可用",
     "s_5f5b6195dfd24aa1": "等待交互内容同步",
+    "s_5f76b2bf82dd2c5d": "版本",
     "s_5f7780324a4b55f1": "会话续接建议",
     "s_5fba64a2b5976bd4": "上传失败，点击重试",
     "s_5fcad9600a50f834": "关闭右侧标签页",
     "s_5fe46d0c2faeacf7": "选择模型连接",
     "s_605a534da98e42ec": "Token 活动视图",
+    "s_60b83f21d9d5d703": "群 {{p0}}",
+    "s_610a30de692b91b0": "请把你的公网地址转发到本机 http://127.0.0.1:{{p0}},连通后会自动继续。",
     "s_610e4e820d6881ea": "彻底删除会话“{{p0}}”？此操作不可撤销。",
     "s_6135d4159e892541": "移除",
     "s_613de904cc604e3b": "{{p0}}本地工具 {{p1}}",
@@ -934,7 +1001,9 @@ export const sourceCatalogs = {
     "s_624b5799ebd036b0": "无工作区",
     "s_6258a2c6f9c89143": "复制全文",
     "s_62731d95bc805803": "正在导出…",
+    "s_6278c2f645ab3982": "公网地址",
     "s_629bb52ce0e5270f": "已将 {{p0}} 添加到聊天",
+    "s_62b72265c96e5e34": "正在重试",
     "s_62c850eabc4ba70e": "部分搜索数据加载失败：",
     "s_6309a3bb5ba4c714": "保存失败",
     "s_63448df0ea0c5be2": "插话中断",
@@ -950,7 +1019,9 @@ export const sourceCatalogs = {
     "s_641778357a5e8a41": "查看配置 Schema",
     "s_643a1b94e9498780": "已信任钩子",
     "s_6492494fbe805292": "描述灵感，生成专属主题",
+    "s_64ded447c5bdd6ea": "验证并继续",
     "s_64e9f3e72b149b27": "此页面意外退出，请重新加载。",
+    "s_64fd6a54381b531c": "获取二维码失败,请重试",
     "s_64fdd111ae7c2ead": "工作空间正在迁移，请等待完成并重启",
     "s_651ec477427c76eb": "添加能力或上下文",
     "s_65273e466af9881c": "来自后台任务:{{p0}}",
@@ -961,6 +1032,7 @@ export const sourceCatalogs = {
     "s_65b3f17534a8c0ab": "加载记忆失败",
     "s_663a5905150ea46d": "请检查系统代理设置后重新加载页面。",
     "s_664c216a6c75054f": "/expert-manager 帮我创建一个 XXX 专家，擅长 XXXXX。我的经验是：[请补充你的行业背景、相关经验]。",
+    "s_66687ec68c240db9": "在「Messaging API」页打开 Use webhook;在官方账号的回应设定里关闭自动回应讯息与加入好友的欢迎讯息。",
     "s_6679f618e868b532": "斜杠命令",
     "s_667b75d63a19b6b8": "上传失败:",
     "s_66809c2ae51ddf06": "移除 Tag {{p0}}",
@@ -1012,7 +1084,9 @@ export const sourceCatalogs = {
     "s_6aa3b1bd38fe141b": "名字不能为空",
     "s_6abdf8409678b516": "在右侧审查面板中查看",
     "s_6ad55eb177526999": "放大预览",
+    "s_6add2714c40f1d45": "私聊",
     "s_6ae40b532ea0f924": "已转至新会话继续。",
+    "s_6aecec7bb2ae1d74": "公网地址(可选,留空则自动建立隧道)",
     "s_6b01fce4dbeaeeb9": "更改",
     "s_6bbaf705e8c64c2b": "目录内容",
     "s_6bea77acefb364ac": "标准",
@@ -1029,6 +1103,7 @@ export const sourceCatalogs = {
     "s_6cec8d70466c7b55": "请在 Microsoft Store 的“库”中获取 ACECode 更新。",
     "s_6cf2531ab1119b67": "授权",
     "s_6d0b032bc4d31ea2": "复制标题",
+    "s_6d0d116c95898867": "机主",
     "s_6d330244eecae355": "连接 daemon 失败:",
     "s_6d3d916f1807a4d2": "继续添加 Tag",
     "s_6d5503cc0bd22117": "选择探测到的模型",
@@ -1043,6 +1118,7 @@ export const sourceCatalogs = {
     "s_6dc0d06dd58b2cb6": "内置默认禁止名单",
     "s_6dd39868b7d587c7": "当前后台服务不支持安全中心，请更新 ACECode 并重启后重试",
     "s_6e1ba4bf187327e9": "终端程序路径",
+    "s_6e382d9250f8dc10": "手动填写",
     "s_6e392a597af4abab": "memory summary model 记忆摘要模型",
     "s_6e55e0f207bfd2e0": "运行记录",
     "s_6e6aba42eba94da0": "正在与智能体共享",
@@ -1052,6 +1128,7 @@ export const sourceCatalogs = {
     "s_6f4b75ff28679ce4": "扁平列表",
     "s_6f5994e138557f90": "% 已用",
     "s_6f87682bc02532c6": "每个工作区可拥有独立的 Skill,仅在该工作区的会话中生效。",
+    "s_6f98bb98abfcd0c9": "打开飞书开放平台,创建「企业自建应用」,在「添加应用能力」里添加「机器人」。",
     "s_6f9c11640850a30c": "清空审计日志失败",
     "s_6fb9dd3555d1b3b0": "确认迁移",
     "s_6fc38ef3602fe789": "上下文",
@@ -1077,12 +1154,16 @@ export const sourceCatalogs = {
     "s_71dcce0699b98a09": "专家组件",
     "s_71dfe4a817b8801d": "请先登录 Copilot",
     "s_71e95b289aad1f6a": "已跳过",
+    "s_71ea09dd1e9905d5": "电脑上登录了 Telegram 也可以直接点链接:",
     "s_71f09042e226bdf9": "高画质模型",
     "s_71fa1b09e415447e": "把身份、擅长领域、开场白和运行时能力配置在同一个专家中。",
     "s_720182db8f88cf7d": "正在读取运行时能力…",
+    "s_722dd20ced9e6d55": "用你的 {{p0}} 私聊机器人一句,下面会出现请求,批准后你就是机主。",
     "s_725831ec12394243": "取消归档失败:",
+    "s_72ccb1274a093efb": "填写 QQ 开放平台里机器人的 AppID 与 AppSecret,保存前会先验证。",
     "s_72dde8dfef88d37d": "确认添加",
     "s_72ec61d7855c86a1": "请求超时（秒）",
+    "s_737c725c1321d260": "已保存 {{p0}},留空则不修改",
     "s_73952aa91a9366b5": "已切换至 ",
     "s_73ae35f541bc8124": "复制附件地址",
     "s_73b629753f6d5fe5": "已复制全部 diff",
@@ -1091,6 +1172,7 @@ export const sourceCatalogs = {
     "s_73e5df48000d6a22": "选择任务位置",
     "s_73fab2d02ab591cb": "模型检测失败{{p0}}：{{p1}}{{p2}}",
     "s_7409a608060f5804": "未指定",
+    "s_741a285fa14f8523": "整理上下文",
     "s_742025b1a0eccc8c": "类型无效",
     "s_743342489c23fe24": "刷新记忆列表",
     "s_744a61203be24c0b": "每 {{p0}} {{p1}}",
@@ -1129,6 +1211,7 @@ export const sourceCatalogs = {
     "s_76e350aa9b3cf01a": "正在读取默认位置…",
     "s_76ebf39ee090026f": "无人值守下不能批越权",
     "s_76f677430db630af": "仅 ACECode Desktop 支持内嵌浏览器",
+    "s_7715155115f58274": "返回扫码",
     "s_77322b7c285eb8bd": "主题已删除",
     "s_7734b5d136de7bdb": "自动重启失败:",
     "s_77423bdd32d35ce3": "编辑刚刚发出的内容",
@@ -1148,11 +1231,13 @@ export const sourceCatalogs = {
     "s_78e5c1be3c1a2347": "壶铃",
     "s_78ea07a31cd96f65": "从此版本开始记录新的 token 用量,历史会话不会回填",
     "s_79167440a990362e": "会话已导出:{{p0}}",
+    "s_79209170acff4896": "等待授权",
     "s_79383e9981843085": "读取 Web 核心信息",
     "s_7948c26c9630a0cc": "资深开发工程师",
     "s_79612d07708f27c8": "平台状态",
     "s_7967bb84220ae3d1": "该工作区没有技能;放到项目的 .acecode/skills 目录即可被发现",
     "s_797644874d78c30a": "剪贴板不可用",
+    "s_79ee5900e8dc266b": "{{p0}} 配对请求",
     "s_79f326be4409d51f": "项目",
     "s_7a0b79e584676550": "ACECode 全局项目目录",
     "s_7a437376c304672c": "在当前回合的下一次模型调用前加入这条消息",
@@ -1161,6 +1246,7 @@ export const sourceCatalogs = {
     "s_7a8a11ead50742a2": "添加",
     "s_7a9b22bb6b0a159e": "Grok Coding Plan 已退出",
     "s_7aa6d0ef5feb745c": "彻底删除",
+    "s_7ace720715576424": "绑定码",
     "s_7acf2ee49b4924ef": "位置：{{p0}}",
     "s_7ad6bbf3f8508928": "忽略建议",
     "s_7adc856731f31518": "尚未运行",
@@ -1168,6 +1254,7 @@ export const sourceCatalogs = {
     "s_7afb72a4b5b21193": "添加工作区",
     "s_7b00c3d69a0c48a5": "个模型",
     "s_7b10b3966368f243": "没有匹配的",
+    "s_7b113358cc1fe5fd": "新联系人",
     "s_7b1347c4ded0097a": "侧边聊天",
     "s_7b187349d641590c": "导出会话失败:",
     "s_7b1c1c5b441d279b": "请检查网站地址和网络连接，然后重试。",
@@ -1195,6 +1282,7 @@ export const sourceCatalogs = {
     "s_7d09ee28674f2d4b": "跳过原因:",
     "s_7d1070ff5c5b7bdf": "[粘贴的文本: {{p0}}]",
     "s_7d166479398a3bce": "正在提交插话…",
+    "s_7d20222788427d6b": "在「权限管理」开通:im:message、im:message:send_as_bot、im:message.p2p_msg:readonly、im:message.group_at_msg:readonly、im:resource。",
     "s_7d3a4b81e7018779": "会话历史已更新，请重试",
     "s_7d4ca7f48effd602": "大",
     "s_7d6667c86ebec2fa": "已达成目标",
@@ -1207,11 +1295,13 @@ export const sourceCatalogs = {
     "s_7df5c456c765e4c3": "禁用",
     "s_7e1df49bc3432fb2": "找不到该预设对应的 Provider 描述",
     "s_7e2ffe585c643f17": "准断网",
+    "s_7e4419d1de251094": "飞书",
     "s_7e8586f653066a9c": "删除模型预设",
     "s_7e963d9ae21a7ad5": "摘要模型",
     "s_7ea852a1f549b6ca": "请输入定时任务名称",
     "s_7ecf1cde648680d2": "已选",
     "s_7ecff345fb5ca29e": "Copilot 授权校验失败",
+    "s_7ed80e44eaf9c51c": "写入文件",
     "s_7edb086ee0d4c6c8": "任务完成通知已打开，但 macOS 系统权限已拒绝",
     "s_7ee8b2d0ae7ade97": "移除附件",
     "s_7efe433909425026": "自定义请求头格式不正确",
@@ -1222,6 +1312,7 @@ export const sourceCatalogs = {
     "s_7f64e6cc3a5dccc7": "调整后台任务面板宽度",
     "s_7f68ebad19ba6bcd": "检查更新",
     "s_7f6c661eb101f549": "连接 GitHub",
+    "s_7f92b2869303b795": "在微信里私聊机器人下达指令,结果回到聊天窗口。",
     "s_7fd7c6c1c60155c2": "没有可批注的选中文本",
     "s_7fe9cf36941a738f": "最大化预览面板",
     "s_80160e448f307c23": "仅显示预览",
@@ -1239,18 +1330,23 @@ export const sourceCatalogs = {
     "s_8143449ded6af56c": "展开项目",
     "s_81508b76150acb3d": "留空从 PATH 查找",
     "s_817af552ff22fdff": "加载失败:",
+    "s_81b430b696435180": "微信",
     "s_81c9f5ef56c3acfd": "summary title generation local model 摘要模型 会话标题",
     "s_81ee43758501ff89": "例如 128000",
     "s_81f19964ae735b1a": "高级功能",
     "s_81fd16a12933fe19": "编辑{{p0}}",
+    "s_8227ca04cabbb5e8": "现在可以在微信里给机器人发消息了。微信机器人只支持私聊。",
     "s_822fb37dba29381a": "选择文件",
     "s_82395d423099a07a": "已归档",
+    "s_823b4ba6e569146a": "在 LINE Developers 控制台的频道「Basic settings」复制 Channel ID 与 Channel secret,填到下面。",
     "s_825a80f75113a9d3": "提示词缓存命中：{{p0}} / {{p1}} 输入 token（{{p2}}%），缓存写入 {{p3}}",
+    "s_82601c48d5d64d71": "修改代码",
     "s_8268968d4a8759fc": "当前模型不支持只读旁路聊天，请切换模型后重试。",
     "s_82808f881bf7755f": "团队成员 · {{p0}} 人",
     "s_82a043c05e8a9446": "专家名称",
     "s_82c4aa13b7ca109e": "最大化",
     "s_82ec71d0714dc013": "正在连接 Windows WebView2。",
+    "s_8301f8304e5dd793": "获取二维码失败,可以重试,或改为手动填写",
     "s_836c3d5d6bc88f78": "写/执行操作前确认",
     "s_837415ff50de9e5c": "匹配:",
     "s_837acaec000d9f38": "已保存。{{p0}} 处疑似密钥已替换为 [REDACTED]，上面显示的是保存后的内容。",
@@ -1276,17 +1372,20 @@ export const sourceCatalogs = {
     "s_8526267fcc158a52": "显示更早的消息",
     "s_85501294b3c40740": "内容超过 50 万字符，直接编辑会明显卡顿；可复制出去修改后用剪贴板内容替换",
     "s_8569e005ca1f98f1": "已打开技能目录",
+    "s_856dba844b90b484": "打开 LINE Official Account Manager",
     "s_8585b2747da94d76": "页面重定向失败",
     "s_85c016964ce0bedf": "目录不存在",
     "s_85c5c1f5567b4d67": "批注",
     "s_85e2f5601c1a0258": "无人值守",
     "s_8609635074718e14": "已引用到聊天",
     "s_86353011351e5d0b": "opencode 会话导入失败:",
+    "s_8652e90f49cd7463": "调用 MCP",
     "s_86542c6b657c93ab": "会话:{{p0}}",
     "s_86624f5719c93e79": "显示更早的 {{p0}} 条消息",
     "s_867698fb7b0c730c": "项目名称",
     "s_867ea0e1328728d9": "错误:",
     "s_8696c49ac55b8c71": "超高",
+    "s_86a515d230592181": "扫码后会自动创建机器人并完成配置,扫码人成为机主。",
     "s_86a63f23a076b11e": "外观",
     "s_86a82374a35763d1": "{{p0}} 个问题待回答",
     "s_86a88f06d31bd3b6": "正在读取 macOS 系统通知权限",
@@ -1312,6 +1411,7 @@ export const sourceCatalogs = {
     "s_88d72ece7cf76737": "搜索结果",
     "s_8905355415cd0bd0": "没有可引用的选中文本",
     "s_89140d4ebd886f12": "插件已启用",
+    "s_891836aa11f5c4d9": "在 Telegram 私聊或群里 @机器人 下达指令,结果回到聊天窗口。",
     "s_89330587b799cc59": "暂时无法下载",
     "s_8949d6721460a7f8": "聊天输入区的模型选择器使用这里的预设。",
     "s_8968ac45a626bd2a": "会话菜单",
@@ -1323,6 +1423,7 @@ export const sourceCatalogs = {
     "s_8996cf52b5aacf6a": "归档失败:",
     "s_89c4766afc85125f": "连接失败",
     "s_89d3e8892ae8fd51": "更多专家",
+    "s_89db648162e7cea1": "连接中断,正在自动重试…",
     "s_89e0ebd9d750f2c1": "当前后台服务不支持图像生成，请更新 ACECode 并重启后重试",
     "s_8a32f1c8f96d5905": "沙箱后端不可用:{{p0}}",
     "s_8a687fb42860ccd0": "思考深度：{{p0}}",
@@ -1341,15 +1442,18 @@ export const sourceCatalogs = {
     "s_8b6ff498515bcc2f": "时间",
     "s_8b7cbd4cede975c1": "导入主题",
     "s_8bcc3e177f5f3b10": "不保存",
+    "s_8be0ea36a9bba286": "正在连接…",
     "s_8c1ae715559b78bd": "无法获取升级进度",
     "s_8c5c96ae7d403826": "已放行指定目录",
     "s_8c803ec4ccd237fb": "此网站暂时无法正确响应，请稍后重试。",
     "s_8ca30ef95071173d": "正在分叉到新会话",
     "s_8cb443ab83797881": "图表",
     "s_8cb45d256976500e": "静默允许",
+    "s_8cbe697b157364a5": "批准",
     "s_8cd177ccd9a3ce2a": "文件：{{p0}}",
     "s_8ce03a48ca299d89": "默认打开目标",
     "s_8cf0105d35ee8db8": "思考",
+    "s_8d0d535863719b97": "dingtalk 钉钉 stream client id client secret 机器人 im channel 消息通道 连接 取消连接",
     "s_8d2773df13e2ebed": "宫格里还没有会话",
     "s_8d2c69445d32a5b4": "当前不可用",
     "s_8d2e9a70cf226d91": "搜索已保存模型",
@@ -1375,11 +1479,14 @@ export const sourceCatalogs = {
     "s_8e6cd5a3fba2a97c": "后台运行设置失败:",
     "s_8e7847be62b68c2b": "上一级",
     "s_8e7aa97f7fda6bc8": "重置记忆失败",
+    "s_8e86f9b1d54f2c51": "复制链接",
     "s_8e94c67730c3984e": "尚未授权",
     "s_8eb6432c43427be3": "已知安全命令",
     "s_8ee6730e12551245": "配置写盘失败",
     "s_8effeb945cdcfbd8": "钩子代码",
+    "s_8f1094e99bf0e30a": "这个机器人设置了 webhook,ACECode 收不到消息。移除后由 ACECode 接管,原来接收 webhook 的服务会停止收到消息。",
     "s_8f407bb9c116f41d": "间隔数值",
+    "s_8f43a2aeaac85a91": "回到飞书开放平台的「事件与回调」,订阅方式选「使用长连接接收事件」并保存(这里连上之后才能保存)。",
     "s_8f46cb4df9c2e6ca": "仅支持 PNG、JPEG、GIF、WebP、BMP 或 ICO",
     "s_8f68def4890f0915": "最近使用的专家组件",
     "s_8f6f8d979c981ced": "已复制",
@@ -1396,13 +1503,16 @@ export const sourceCatalogs = {
     "s_90ccdf079052559f": "删除模型 {{p0}}",
     "s_90dae385f5c1bd68": "旁路聊天连接已中断，请重试。",
     "s_90fd1d973ec921f7": "电脑操控目前仅支持 Windows",
+    "s_9118ed423edf0b11": "在「凭证与基础信息」复制 Client ID 与 Client Secret,填到下面。",
     "s_912be01af6735ac1": "默认权限模式已设为 ",
+    "s_913216fda599e7d3": "{{p0}} 分钟后过期",
     "s_913cd56da217a9a2": "指针样式",
     "s_9147f07072527b70": "启用模型推理",
     "s_914b7a5f9d45d7b9": "粘贴的文本正在上传，完成后请再发送",
     "s_9154825fa11a80a2": "复用连接的 API 地址和 Key，图像模型在下方单独指定。",
     "s_915b988cbfed5442": "远程 Web 模式",
     "s_916a15661d20131c": "已暂停的目标",
+    "s_916afcd85322d732": "更换",
     "s_917b1c1f18d0276b": "保存中...",
     "s_92172b32227b0aae": "删除后无法恢复；记忆摘要之后也不会再自动生成这条记忆。",
     "s_926a50b98ece2667": "撤销",
@@ -1419,6 +1529,7 @@ export const sourceCatalogs = {
     "s_9344597efd4950cc": "执行失败",
     "s_9344fdfb51e2e192": "擅长领域",
     "s_935717bb48835029": "没有操作或等待下一项任务时使用",
+    "s_93828ba27fd646b2": "在钉钉私聊或群里 @机器人 下达指令,结果回到聊天窗口。",
     "s_93a8734cce300531": "搜索模型",
     "s_93ac0efe6818ad18": "引用已有专家，指定一位主理人；成员保留各自能力范围。",
     "s_93b93a43e96a3556": "目录名：",
@@ -1465,6 +1576,7 @@ export const sourceCatalogs = {
     "s_981a6df8cf54be60": "PNG 图片",
     "s_9833401820de5e2b": "受管 Provider 在这里完成登录，密钥和端点不会进入模型弹窗。",
     "s_9842842bc84fd474": "电脑操控支持 Windows 和 macOS 14 及以上版本",
+    "s_98532681701285de": "现在可以在 LINE 里私聊机器人了。把机器人邀请进群后 @ 它,第一次需要在设置页批准。",
     "s_985511d8c078002c": "正在回答…",
     "s_985575198233e251": "导出主题失败",
     "s_986c56322e8bb553": "请选择关闭窗口操作",
@@ -1472,13 +1584,17 @@ export const sourceCatalogs = {
     "s_9884e90a773101b9": "全局记忆",
     "s_988c12f1398e3d9d": "AI 执行的命令运行在隔离沙箱里,文件、命令、网络策略按下面的规则生效。",
     "s_98cbc356f0e61a08": "新增一个 Provider 配置后即可在这里管理。",
+    "s_98fc221b10e87c21": "创建应用",
     "s_991bb7cfe5a81550": "保存修改",
     "s_992b4416c9d23e96": "正在读取模型…",
     "s_9966d6b375133f89": "路径必须是绝对路径:{{p0}}",
+    "s_99731fe916c6b3bf": "现在可以在钉钉里私聊机器人了。把机器人拉进群后 @ 它,第一次需要在设置页批准。",
+    "s_99845832ed7f16f6": "稍后再说",
     "s_998568217a58f2fc": "无匹配的全局技能",
     "s_999bf43be3657ea3": "非交互嵌入默认放行",
     "s_99a4e1e59743908f": "扩展",
     "s_99aea2f9131ad6da": "技能",
+    "s_99b8595e331d53a0": "在 QQ 私聊或群里 @机器人 下达指令,结果回到聊天窗口。",
     "s_99c32108b160659e": "请选择不超过 16 MB 的完整主题 ZIP",
     "s_9a1537c4f4d32cef": "未知命令且沙箱不可用",
     "s_9a548610ec6b027f": "已复制代码",
@@ -1500,7 +1616,9 @@ export const sourceCatalogs = {
     "s_9d028438fbd04725": "请先填写 API 地址和 Key，或选择可用的模型连接",
     "s_9d0f70c4cee1d679": "本次会话放行",
     "s_9d1a1b1c006d85f0": "文件编码不受支持，只能只读预览",
+    "s_9d8692671d208b74": "群成员",
     "s_9d8fb8378821c838": "近 365 天内累计",
+    "s_9dbb88d5e18dcea1": "移除 webhook 并连接",
     "s_9dc0825fba5422e4": "加载中...",
     "s_9dc11d465f7d22c2": "迁移任务已不存在，请重新发起迁移",
     "s_9dcb7682ca6c6910": "{{p0}} 个 LSP",
@@ -1509,6 +1627,7 @@ export const sourceCatalogs = {
     "s_9e3fc11213b90ed0": "在资源管理器中显示",
     "s_9e4a69b0e32825ba": "选择任务范围",
     "s_9e66271fb2e5fc90": "技能与协作",
+    "s_9e6c825ec268ab7b": "把它回复的 Token 粘贴到下面。",
     "s_9e73b26eb0a378c9": "没有可读取的内容",
     "s_9e87fbcaed97c244": "升级已取消，当前安装未修改",
     "s_9e928f35eb8008a4": "暂时无法获取主题下载大小，请重试",
@@ -1531,9 +1650,11 @@ export const sourceCatalogs = {
     "s_9fc9368cc2c409a3": "暂无已配置插件",
     "s_9fd56f7aae1ca61d": "显示隐藏项目",
     "s_9fef8ee282a01ab9": "本地模型目录格式不完整，请更新 ACECode 或刷新目录。",
+    "s_9ff545329109ea65": "机主:{{p0}}",
     "s_a00235e8c624f16d": "扩展 / 专家组件",
     "s_a011d73ec679db1a": "启动升级失败:",
     "s_a071de661efe95fb": "删除这条记忆？",
+    "s_a0a0e5f6072c8213": "weixin wechat 微信 扫码 ilink 机器人 im channel 消息通道 连接 取消连接",
     "s_a0dd1a666530c173": "默认权限模式已更新,当前会话同步失败:",
     "s_a0f73bcccc33cb7b": "关闭预览面板会关闭当前预览区域的全部 {{p0}} 个标签页。是否继续？",
     "s_a1315bcfc62a19f8": "原生桥返回了无效结果",
@@ -1541,8 +1662,10 @@ export const sourceCatalogs = {
     "s_a153567fbff7a035": "工作空间依赖项",
     "s_a184d57717116620": "已有旁路提问正在回答，请稍候",
     "s_a1a9da9ee6ed0401": "未知原因",
+    "s_a1dfbbbaa9f2fef9": "机器人设置了 webhook,需要处理",
     "s_a203f86cf6a6a841": "MCP 服务器",
     "s_a22774c08bc9187e": "加入可写",
+    "s_a253535fd2df2437": "接下来 10 分钟内第一个私聊机器人的人成为机主,现在就用你的 {{p0}} 私聊它一句。",
     "s_a25f7afbdeabbf5b": "天平",
     "s_a26e8186b190f6a1": "已添加到会话",
     "s_a27718d789f9cd53": "请先连接 {{p0}}",
@@ -1558,18 +1681,22 @@ export const sourceCatalogs = {
     "s_a3030bf8f16dc63c": "保存",
     "s_a3446a9f995b97ae": "新路径不能位于当前工作空间内",
     "s_a37778f17c5f3ee5": "已取消",
+    "s_a379593b5b7590f0": "重新扫码",
     "s_a37fe6cce130db08": "允许多进程启动",
     "s_a383b3a7e26ba13e": "由 Microsoft Store 管理更新",
     "s_a398cdc4c87f6bb1": "当前 daemon 不支持外观配置持久化",
     "s_a3a33d4898a73327": "项目配置与全局配置叠加，同名服务器以项目配置为准。",
+    "s_a3c4db63188defb7": "在同一页打开「Message Content Intent」。",
     "s_a46b5607cf04e274": "请选择决策",
     "s_a48c70216c141e4a": "我们该在 {{p0}} 中做什么？",
     "s_a49f5287fc9ef2d0": "展开目录",
     "s_a4c3313deb180960": "三",
+    "s_a4d14414860b025b": "机器人",
     "s_a4dbd208ac604795": "迁移失败：{{p0}}",
     "s_a4e47879fbd494b2": "探测模型",
     "s_a500bd5efd41f72a": "当前问题",
     "s_a53a4e7bcadab26f": "取消目标",
+    "s_a5574109f0208e89": "连接",
     "s_a55e054ba8777aed": "我了解这些记忆会被永久删除，且无法撤销",
     "s_a567bdaa11367f26": "中",
     "s_a56e7d2220e99dc0": "运行中的会话正在使用该模型",
@@ -1579,6 +1706,7 @@ export const sourceCatalogs = {
     "s_a5c89f1001ff103d": "任务已终止：{{p0}}",
     "s_a60959c3478597ba": "导出 PNG 图片",
     "s_a621d610084a268b": "Windows WebView2 暂时无法启动，请重新启动 ACECode 后再试。",
+    "s_a627f4f2dbd7c83b": "feishu lark 飞书 app id app secret 长连接 机器人 im channel 消息通道 连接 取消连接",
     "s_a63280253f17d440": "会话",
     "s_a655bcaa91a25426": "取消派遣：{{p0}}",
     "s_a67fa4bcb68094b4": "没有符合筛选条件的专家组件",
@@ -1587,6 +1715,7 @@ export const sourceCatalogs = {
     "s_a6dfb80406396953": "当前平台不拦截读取,此清单不生效(仅 macOS / Linux)",
     "s_a6e1beaceb5bbafa": "暂无任务或项目",
     "s_a7310a28aa28faf4": "取消升级失败:",
+    "s_a73a5fef875e86b2": "没有找到 cloudflared。先运行 winget install --id Cloudflare.cloudflared 安装后重试,或回到上一步填写自己的公网地址。",
     "s_a74010990fc78e7d": "本地导入",
     "s_a76952e53abfc0d9": "刷新模型",
     "s_a77ecf353bbece4f": "升级失败:",
@@ -1611,6 +1740,7 @@ export const sourceCatalogs = {
     "s_a9a52fa6f6089c4d": "无法保存，请重新打开后再试",
     "s_a9c7ba0a90821f96": "退出连接",
     "s_a9f9acf6c0a4da5e": "已删除 {{p0}} 个会话",
+    "s_a9fe4ee81f686689": "连接失败,详情见日志",
     "s_aa06c367f0d85408": "更新中",
     "s_aa1b765fb519fa08": "认证失败:",
     "s_aa1e899dd35771b0": "橙色",
@@ -1629,6 +1759,7 @@ export const sourceCatalogs = {
     "s_ab48bf2aff24b769": "远程 Web 代理启动或停止超时",
     "s_ab61b9d1e06f9811": "新建终端(默认 shell)",
     "s_ab732547ef013de7": "允许后,这条命令将在沙盒内执行。",
+    "s_ab7a910f5dec5480": "还差几步",
     "s_ab9084a640fbb864": "全不选",
     "s_abb6edd1093c5cf2": "任务已终止",
     "s_abe29e9399d0301c": "加载更多失败",
@@ -1638,6 +1769,7 @@ export const sourceCatalogs = {
     "s_ac3f6e014eef361b": "切换开发者工具",
     "s_ac4901c4979510a2": "{{p0}}（不可用）",
     "s_ac6062580b3feb00": "后台任务建议",
+    "s_ac7246e3c8488218": "{{p0}} 个请求待批准",
     "s_ac7646d3e0e17e38": "待导入主题预览",
     "s_ac77953a1e064ed6": "发送失败",
     "s_ac8e7ffd9e3458ab": "本平台没有可用沙盒,未知命令需要确认",
@@ -1648,6 +1780,7 @@ export const sourceCatalogs = {
     "s_ad24308da105ecab": "无法连接 Grok 模型服务",
     "s_ad403ac8e643bda1": "主题已删除，部分缓存待清理",
     "s_ad4c46728555aeb6": "找不到此网站",
+    "s_ad5aaf33d6ce9b8a": "正在获取二维码…",
     "s_ae115efd1b2c2524": "任务已中止",
     "s_ae13d96782b88e57": "探索代码库",
     "s_ae30451fc65b75de": "没有匹配的 Provider",
@@ -1679,6 +1812,7 @@ export const sourceCatalogs = {
     "s_b0e60c5b81438dff": "主理人",
     "s_b0fda488e4430202": "文件过大，无法在详情中编辑",
     "s_b135c840f4ab004d": "请先选择工作空间",
+    "s_b1806dfd868502c0": "现在可以在 QQ 里私聊机器人了。把机器人拉进群后 @ 它,第一次需要在设置页批准。未经个人认证的机器人只能由你本人使用,也只能加入你担任群主的群。",
     "s_b193e624476c776d": "未能获取模型回复，请检查配置后重试",
     "s_b19b09a6ed90c4be": "{{p0}}当前生效头像",
     "s_b1a521adee6fcd78": "旁路聊天响应格式错误，请重试。",
@@ -1689,12 +1823,14 @@ export const sourceCatalogs = {
     "s_b2749206c4e01861": "旁路提问失败",
     "s_b2888f5f93782bb7": "加载会话失败:",
     "s_b28e2113fe3a14e6": "全部时间",
+    "s_b28f2b46e181e999": "打开 Discord 开发者后台,新建应用,在「Bot」页点「Reset Token」并复制。",
     "s_b291a71042529666": "包含 {{p0}} 条本地估算记录,总量可能与服务商账单不同",
     "s_b2d2f7bccbeeffa1": "正在确认…",
     "s_b31640e590dd972a": "有尚未保存的更改",
     "s_b33181ed8c62a396": "删除主题",
     "s_b3594eb35263f1eb": "批注 {{p0}}，原文已变化",
     "s_b387dca9c27793f0": "取消导出失败，请重试",
+    "s_b3bc6035b32575a6": "discord bot token 机器人 服务器 im channel 消息通道 连接 取消连接",
     "s_b3dd7d131a1959f4": "直接用自然语言交代任务，或输入 / 查看可用命令。发送后 ACECode 会在所选范围内工作。",
     "s_b40cae1f1f4446f0": "关闭窗口时您希望执行什么操作？退出应用将停止所有正在运行的任务和定时任务。",
     "s_b40f2c82dca202be": "当前后端不隔离网络。",
@@ -1729,6 +1865,7 @@ export const sourceCatalogs = {
     "s_b76fe0327e7aefc8": "取消置顶失败:",
     "s_b79ce792c1a1287a": "正在校验并安装…",
     "s_b7f4557b8b746a5e": "请输入完整的文件夹路径",
+    "s_b806e39b8e3c4403": "用手机相机扫码(Telegram 自带的扫码扫不了这个),在 Telegram 里点「开始」就成为机主。",
     "s_b817c99bb4f24dd5": "展开列表面板",
     "s_b8199c9199128706": "计划与任务",
     "s_b858b96d7e9a464e": "在文件树中定位",
@@ -1741,8 +1878,10 @@ export const sourceCatalogs = {
     "s_b91472f6f25b1041": "输入消息或 / 命令…",
     "s_b91b8a344a77fca6": "目录路径为空",
     "s_b9238eb0c9178901": "主题操作失败，请重试",
+    "s_b925ae46007cd1f0": "机主绑定二维码",
     "s_b92b399d2820c415": "清除已保存密钥",
     "s_b92d86f4f5570817": "关闭其他",
+    "s_b93afa1b4934b706": "查阅网页",
     "s_b967309734beff88": "记忆摘要",
     "s_b97ad406809572e1": "启用推理",
     "s_b97c0e55e836dee2": "所选摘要模型不可用，请重新选择模型",
@@ -1764,6 +1903,7 @@ export const sourceCatalogs = {
     "s_bad0ab59c33beb1d": "每天 {{p0}}",
     "s_baeb44eebe946b43": "只能包含字母、数字、下划线和连字符，最多 64 个字符",
     "s_bb3e66754a5e03e3": "Agent 请求执行以下操作:",
+    "s_bb6d995724f49a72": "管理",
     "s_bb7cc334f9434dab": "关闭后，本次填写的内容和能力选择不会保存。",
     "s_bb7ed30127ddfd49": "导出任务返回了无效结果，请重试",
     "s_bb7ef73495dd8a74": "结果",
@@ -1794,10 +1934,12 @@ export const sourceCatalogs = {
     "s_be235f67fed22f01": "取消归档",
     "s_be385b84994016d0": "浏览器组件意外停止，请重试加载此页面。",
     "s_be3e095ce6b95549": "名字以 ( 开头是系统保留",
+    "s_be7bbdf1213e0555": "QQ 机器人",
     "s_be98c07b13ac0281": "静态",
     "s_bee1bfab91f18284": "无人值守自动放行",
     "s_bf1617e297b85f92": "已从桌面工作区列表移除",
     "s_bf24e735d802644f": "一行一个；显示在卡片与详情中",
+    "s_bf2a78216b764bb1": "qq bot 机器人 扫码 appid appsecret im channel 消息通道 连接 取消连接 owner approve revoke 机主 授权 审批 撤销",
     "s_bf39e015be237ba0": "项目已创建，但返回的工作区信息不完整",
     "s_bf3a8846479b7fb7": "输入或粘贴绝对路径,回车跳转",
     "s_bf3e55705e1de1e8": "任务完成通知设置失败:",
@@ -1817,7 +1959,9 @@ export const sourceCatalogs = {
     "s_c02c246a6d181676": "无法读取粘贴的文本",
     "s_c02fdcf208b3e472": "删除规则",
     "s_c03b9deb55408bc4": "页面进程已停止",
+    "s_c043eb82f9332c31": "正在打开连接…",
     "s_c044ecbe7fe9c678": "仅显示主题色箭头",
+    "s_c051216ed509001e": "在 Telegram 里搜索 @BotFather(认准蓝色认证标记),发送 /newbot。",
     "s_c05f7cd6ed3587a2": "飞机",
     "s_c0866a5a020be7a3": "彻底删除会话",
     "s_c087c3d4b210ee82": "删除主题返回了无效结果，请刷新后重试",
@@ -1836,6 +1980,7 @@ export const sourceCatalogs = {
     "s_c27916570d04cf33": "当前工作区未在后台服务中登记",
     "s_c2a497830ef74215": "最新版本",
     "s_c2b732b196ccc7f3": "会话已彻底删除",
+    "s_c2b794434132af6e": "重新获取二维码",
     "s_c2e410cd40759fb5": "向 ACECode 描述任务，或输入 / 命令...",
     "s_c2f0625f0f3d2c18": "展开工具详情",
     "s_c304f59bf05cfa14": "桌面启动",
@@ -1846,8 +1991,10 @@ export const sourceCatalogs = {
     "s_c39d1e51a3941a89": "正在保存主题包…",
     "s_c3a73c5eecea42a3": "专家",
     "s_c3b8f744ed2c55bf": "JSON 格式错误:",
+    "s_c3e1b26c451e8221": "添加事件「接收消息 v2.0」(im.message.receive_v1)。",
     "s_c3e5589604083870": "暂无插件",
     "s_c3f989b790daab98": "后台服务暂不可用，请稍后重试",
+    "s_c43f153cb1be5ca5": "等成员回报",
     "s_c4ae8fa5a16b5a75": "跳过所有工具权限确认",
     "s_c4c5b649cbf25fbb": "记忆与上下文",
     "s_c52c7fbed621e8ff": "批注 {{p0}}",
@@ -1908,12 +2055,14 @@ export const sourceCatalogs = {
     "s_ca6343cddb75f289": "生成测试图片失败，请检查连接和模型名称",
     "s_ca66c2da6f5bf825": "了解更多",
     "s_ca74d439e7712aa5": "daemon 未运行，已错过且不会补跑",
+    "s_ca78ab9bac8e9f5b": "在飞书里搜索这个机器人,私聊它发送下面的 6 位数字。",
     "s_ca949d1eb3377a79": "ACE 标记",
     "s_cadd75ef8275de01": "已查看 {{p0}} 张图像",
     "s_caecb5d342cc889a": "恢复目标",
     "s_cafc8a4f6acda2cb": "Tag 可多选；同一专家会出现在每个已选 Tag 下",
     "s_cb2fcb9099668d50": "暂无回答",
     "s_cb31eb7a0c2aa250": "编辑模型 · {{p0}}",
+    "s_cb51a062db592988": "这个机器人正由另一个 ACECode 连接,它退出后这里会自动接管。",
     "s_cb5d682bac3d1a2d": "重置",
     "s_cb62ebd689ee8f20": "当前",
     "s_cb65690b6ee3a1d4": "无法获取 GitHub 验证码",
@@ -1921,13 +2070,17 @@ export const sourceCatalogs = {
     "s_cbb5a32c96c3cdee": "添加所选模型",
     "s_cbd7dc0ea6976fd0": "关闭窗口时",
     "s_cc0477362c195cf3": "暂无可复用的 OpenAI 兼容连接，请选择单独配置。",
+    "s_cc574bc5da5d9ac3": "绑定码 10 分钟内有效,只能用一次;发送后这里会自动完成。",
     "s_cc66c3f576fd5a49": "完全访问权限",
     "s_cc91b14c8a02a155": "将 {{p0}} 设为默认模型",
     "s_cce894450069ba5b": "未知来源",
     "s_cd0832ff9b505231": "主题包已交给浏览器下载",
+    "s_cd0ce16ee4fd90de": "复制失败,请手动选中复制",
+    "s_cd1db6a7d69cb947": "在 QQ、微信、飞书、钉钉、Telegram、Discord、LINE 里远程使用 ACECode。凭据只保存在这台电脑上;关闭 Desktop 后是否继续在线,取决于 设置 > 常规 里的“退出 ACECode 后继续运行后台进程”。",
     "s_cd32a8c1d823d060": "{{p0}} · 原文已变化",
     "s_cd3b78eb00f7cd12": "已配置的钩子将显示在此处",
     "s_cd62bee012d94183": "页面组件意外停止，请重新加载。",
+    "s_cd68324b409f9962": "LINE 只能通过公网地址回调。公网地址留空时,ACECode 会用 cloudflared 自动建立临时隧道(先安装:winget install --id Cloudflare.cloudflared),每次连接都会自动更新 LINE 的回调地址。",
     "s_cd7395dfd00b67f2": "只放行写入 {{p0}}",
     "s_cda33af428d74680": "命中沙箱内放行规则",
     "s_cdae8daae433af05": "原生选择器不可用",
@@ -1950,8 +2103,10 @@ export const sourceCatalogs = {
     "s_cf479a0f90887a09": "暂时无法获取主题信息，请检查网络后重试",
     "s_cf4880f621b9d7bd": "我的专家",
     "s_cf4b1ead545e9bfc": "通配符只能用在黑名单里:{{p0}}",
+    "s_cf5c7eb43df2410f": "一个群",
     "s_cf6506cb7fc47b9c": "粘贴的文本 · 待上传",
     "s_cf6783b5388c5684": "放行(沙箱内)",
+    "s_cf8ab6767bf0526f": "二维码过期后已自动换新,请扫描新的二维码",
     "s_cf911266fb127d62": "展开项目栏",
     "s_cf9430e214bde1a8": "当前目录无法创建 worktree",
     "s_cfbb88c4ba804b90": "哑铃",
@@ -1962,6 +2117,7 @@ export const sourceCatalogs = {
     "s_d04fcbda737fc0c6": "加载中",
     "s_d059018d896d6cde": "删除 {{p0}} 行",
     "s_d06e875dde456038": "还没有被拦截的路径",
+    "s_d0916de8c1b603bd": "已批准 {{p0}}",
     "s_d0ca08d604551151": "队列已暂停",
     "s_d0f680208ed8796c": "git 超时,点击重试",
     "s_d0fb5bbca8184bdd": "跳转到当前问题:{{p0}}",
@@ -1981,6 +2137,8 @@ export const sourceCatalogs = {
     "s_d2fc539871184000": "插话已提交，正在打断当前回合",
     "s_d3136b6fa93050df": "来自 {{p0}} 个会话",
     "s_d31c72ba37a59575": "暂无已归档会话",
+    "s_d321ee860efcbb5d": "使用已保存的机器人,或者换一个。",
+    "s_d33995ad669c80cf": "创建频道",
     "s_d33e249955c846e3": "正在安全停止升级，请稍候。",
     "s_d35ab580f555345e": "停止请求发送失败，连接恢复后请重试",
     "s_d381ac2d678d3f8e": "点击窗口右上角关闭按钮时执行的操作",
@@ -2004,6 +2162,7 @@ export const sourceCatalogs = {
     "s_d538a7ab8d9826bb": "启动导入失败",
     "s_d53d32f1a1211371": "自定义请求头 JSON",
     "s_d57bc0acdb5f23ab": "加载 diff 失败",
+    "s_d593d21fca298b8f": "微信机器人",
     "s_d5d126f6c79d9b11": "所有工作区",
     "s_d5d360963aa38a66": "打开会话失败:",
     "s_d5e75e3452a056c7": "插话提交失败:",
@@ -2021,6 +2180,7 @@ export const sourceCatalogs = {
     "s_d69766c856685234": "新手指引",
     "s_d6cd7e5f2a8a82cf": "这条记忆已不存在，请刷新列表",
     "s_d6d20f05ed0f96e0": "单次执行时间",
+    "s_d6e882143a3c3b83": "扫码创建机器人",
     "s_d6f766f2adf53227": "排队中",
     "s_d6feded758aed3eb": "取消升级",
     "s_d73e140df277dffe": "模型已更新",
@@ -2028,6 +2188,7 @@ export const sourceCatalogs = {
     "s_d74679ad02055214": "钩子操作失败:",
     "s_d74f204139fdd6ab": "搜索专家名称、Tag 或擅长领域",
     "s_d7503697e8e7850b": "重试主题工坊",
+    "s_d750c976bfff1be2": "打开飞书开放平台",
     "s_d77674f90811d7af": "配置范围",
     "s_d7875850553752e5": "切换专家失败：{{p0}}",
     "s_d7b2165028a50b95": "自动编辑和运行沙盒内命令,危险操作与越界请求需确认",
@@ -2048,6 +2209,7 @@ export const sourceCatalogs = {
     "s_d94f9bafff59c06b": "已启用钩子",
     "s_d954c8e3f3042985": "危险命令",
     "s_d9686d510cd34aff": "通知会静默进入通知中心",
+    "s_d9894ab44928d667": "按提示起名字,用户名要以 bot 结尾。",
     "s_d9b7af1d4322eb34": "折叠全部 diff",
     "s_d9c35f6c3c4deeaa": "(空目录)",
     "s_d9f02c7caa8a847d": "保存自定义指令失败:",
@@ -2074,9 +2236,11 @@ export const sourceCatalogs = {
     "s_db8630211fe3934a": "原生设置不可用",
     "s_db95142124934467": "音乐",
     "s_dbaa6ba5056580a7": "不在当前可选专家范围内",
+    "s_dbcac8ae7d65ae39": "二维码已过期",
     "s_dbcb25260e3df31a": "每一次命令执行、文件修改、沙箱拦截与规则变更的判定记录;最多保留 {{p0}} 条。",
     "s_dbd379b39f0d3537": "粉色",
     "s_dc2ba467fc7ac962": "描述",
+    "s_dc3cabe68bcc3046": "打开钉钉开放平台,创建「企业内部应用」,在「应用能力」里添加「机器人」。",
     "s_dc47f62bd3f882f0": "组建专家团",
     "s_dc4d662d071eea52": "创建于",
     "s_dc55764fa54e2a48": "MCP 配置范围",
@@ -2092,6 +2256,7 @@ export const sourceCatalogs = {
     "s_dd42f689b17393c2": "正在加载更早的消息…",
     "s_dd7a9008edbca109": "已取消 {{p0}} 个会话的归档，{{p1}} 个失败",
     "s_dda206707b809157": "连接已中断",
+    "s_ddcf6e77b0ee1000": "准备",
     "s_ddde08946298195d": "还原",
     "s_ddfe2c796c7eb71b": "手动添加",
     "s_de03ee139fe2fd9f": "已找到",
@@ -2103,6 +2268,7 @@ export const sourceCatalogs = {
     "s_de32e20193ad1042": "知道了",
     "s_de8184da1ef88d03": "已配置",
     "s_deb6051740064edd": "使用记忆",
+    "s_dec96df98f052d22": "打开 LINE Developers",
     "s_deeceedbed503b78": "每日代码健康巡检",
     "s_df359a6a54eab051": "通过配置和已启用的插件管理生命周期钩子。",
     "s_df3d58c7d84b85f2": "设置",
@@ -2118,13 +2284,17 @@ export const sourceCatalogs = {
     "s_e058a2b5c4f81526": "查看全文",
     "s_e05f7e88f89c5f88": "，下载完成后自动应用。",
     "s_e07802f10db9b6b8": "找到适合当前工作的专家",
+    "s_e0959e358684c224": "{{p0}}(留空则不修改)",
     "s_e09b1c37f79f440d": "放行(沙箱外)",
     "s_e0b05fd1040bf6ce": "删除主题失败，请重试",
     "s_e0b1051909eb179e": "任务与工作区",
     "s_e0b6ce5e09cd4386": "服务器配置",
     "s_e0c8243464aa770c": "0 / {{p0}} 步",
     "s_e0d995508b32cdbb": "{{p0}}% 已用",
+    "s_e0e9b9269cbd7678": "打开 Discord 开发者后台",
     "s_e0ec651f0dae7cf3": "引用",
+    "s_e0f62acd5d3cebdd": "通道数据异常,详情见日志",
+    "s_e0fecdf371158416": "已取消扫码,原有配置未改动",
     "s_e122303044304acc": "使用此名称保存",
     "s_e17df82098f51602": "已将控制台日志添加到聊天",
     "s_e19c3b9e266c69c9": "浏览器",
@@ -2139,6 +2309,7 @@ export const sourceCatalogs = {
     "s_e246195c1a39636e": "下一轮",
     "s_e2469247115761e9": "默认画质",
     "s_e26740162fbcb387": "将排队消息插入当前回合",
+    "s_e2780ee23078ea51": "{{p0}}{{p1}}请求使用 ACECode,到设置 > 消息通道处理",
     "s_e2a76ef1f12e147f": "终端",
     "s_e2f12da7faa68217": "已下载",
     "s_e2fda204edef967e": "JSON 必须是对象",
@@ -2194,12 +2365,14 @@ export const sourceCatalogs = {
     "s_e806fbbe8ec6e82d": "插件",
     "s_e833097b603cb745": "{{p0}} 个上下文",
     "s_e84e54a6b6dbbbb9": "读写都拒绝:{{p0}}",
+    "s_e8ac23cf743aa1f8": "或者批准私聊请求,第一个被批准的人成为机主",
     "s_e8dc871a7fdee23b": "总计",
     "s_e8e08b0f61dd4ddb": "正在取消…",
     "s_e90589613fe54246": "显示隐藏",
     "s_e948d90880bb3dba": "JSON 无效,无法切换",
     "s_e951cbd07b5633c1": "移除本地项目",
     "s_e95f2ba203c9af41": "请等待正在运行的任务完成后再迁移",
+    "s_e99a6717b6917534": "处理",
     "s_e99b5859dcf96dc4": "向上查看更早的问题",
     "s_e9a1310b7638d211": "下一轮派遣{{p0}}：{{p1}}",
     "s_e9b00d7f92151b2d": "派遣 {{p0}}",
@@ -2223,16 +2396,19 @@ export const sourceCatalogs = {
     "s_eb4c406398df4d73": "暂无工作区用量",
     "s_eb557068ab4833dd": "无法连接 Copilot 模型服务",
     "s_eb55f0980fa90bac": "等待你回答",
+    "s_eb92486a46895884": "现在可以私信机器人,或在服务器频道里 @ 它。第一次在频道里使用需要在设置页批准。",
     "s_eb93045599c0e25c": "进入 Plan 模式",
     "s_ebb240a1930e8bfb": "搜索图标",
     "s_ebb63196c7d3c318": "复制图片失败:",
     "s_ec7a11c7061bc164": "正在迁移工作空间…",
     "s_ec869826ec67f839": "Agent Browser 的部分浏览器数据未能复制，重启后可能需要重新登录",
     "s_ec9bbc8139d8bdd1": "专",
+    "s_ecdf5ea03d83b916": "line messaging api channel secret webhook cloudflared 机器人 im channel 消息通道 连接 取消连接",
     "s_ece45f7651c8c206": "Agent Browser 桌面桥不可用",
     "s_ed100f18801746c9": "命令规则已保存",
     "s_ed147f03761ab80e": "将元素添加到聊天",
     "s_ed150cce119ea114": "已记住 Git Bash 路径",
+    "s_ed16bd1db4b68498": "等待回答",
     "s_ed1790d489e671a9": "ACECode 本地工具继承全局",
     "s_ed21620162d871e5": "加载会话记录…",
     "s_ed2f18de3cdc1c5f": "关于 ACECode",
@@ -2241,12 +2417,15 @@ export const sourceCatalogs = {
     "s_eda73a5daf8f734f": "当前问题:{{p0}}",
     "s_edb18f09d0ff4c83": "编辑模型 {{p0}}",
     "s_edbd4f79f1b7919a": "... +{{p0}} 行已折叠",
+    "s_ede83cc65dad0522": "使用已保存的机器人,或者重新扫码换一个。",
     "s_edecf0ae6e5144f9": "发送",
     "s_ee00e57c07195431": "当前运行模式不支持自动重启，请完全退出后重新启动 ACECode",
     "s_ee1db622be4f2443": "关闭 {{p0}}",
+    "s_ee1e5738be96819a": "已连接 {{p0}}",
     "s_ee32f25f70508f9c": "清除搜索",
     "s_ee34c74d32e7548a": "最近创建",
     "s_ee529160390df1c4": "端点模式",
+    "s_ee9ebe523d4205f8": "连接中…",
     "s_eea1694c235b5ddf": "每天",
     "s_eeccc53745f048de": "查看{{p0}}“{{p1}}”",
     "s_eeef861b87676f3f": "地球",
@@ -2267,12 +2446,14 @@ export const sourceCatalogs = {
     "s_f00ef1be4493739b": "每次询问",
     "s_f0352e9758fbff2d": "禁止执行命令",
     "s_f035aab05364d2c5": "选择「{{p0}}」",
+    "s_f03b1d0aa80f24ea": "在 LINE 私聊或群里 @机器人 下达指令,结果回到聊天窗口。",
     "s_f04360cb3c9187dc": "{{p0}} 个文件有未保存的修改。是否保存后继续？",
     "s_f07ba1ef037a8e44": "已有定时任务",
     "s_f07bda17207c1e3e": "只读文件系统",
     "s_f0935665814a3f25": "复制连接失败：{{p0}}",
     "s_f098218a3032a625": "已拒绝",
     "s_f09e3585d4a4e27e": "模型连接",
+    "s_f0b4569c602a10a0": "使用已保存的机器人",
     "s_f121ab742cefcb8e": "需要关注",
     "s_f1929d7304960203": "已禁用钩子",
     "s_f1aa0173729f7228": "移除引用上下文",
@@ -2280,6 +2461,7 @@ export const sourceCatalogs = {
     "s_f1b112d6acd841b1": "学士帽",
     "s_f1bdeeb9fb4cab81": "主题资源校验失败，无法导出",
     "s_f1e0dfb858e7fcfe": "钩子拒绝",
+    "s_f21f25112af89630": "回调地址已登记。请在 LINE Developers 控制台的 Messaging API 页打开 Use webhook,打开后这里会自动变为已连接。",
     "s_f27627514a2cb542": "专家组件加载失败",
     "s_f28461bb49c85647": "已完成",
     "s_f2902ada282332d2": "未知命令,沙箱内执行",
@@ -2287,9 +2469,11 @@ export const sourceCatalogs = {
     "s_f2b4237b35f0b3b2": "查看会话",
     "s_f2bdc88464c51c2e": "显示 API Key",
     "s_f2d964d3dc5862d1": "超时:",
+    "s_f2df9f7ce435d9d6": "通道数据文件异常,详情见日志。",
     "s_f2f491398295b1b9": "莲花",
     "s_f323fc507d585565": "最小化到托盘",
     "s_f335420fcda22e54": "该文件格式暂不支持预览",
+    "s_f33c31866a8c335e": "已拒绝 {{p0}}",
     "s_f36f1a90b64f69e5": "Node.js 工具",
     "s_f37b8e7538b116da": "展开{{p0}}",
     "s_f39f410e0b493a67": "跳过指引",
@@ -2331,6 +2515,7 @@ export const sourceCatalogs = {
     "s_f628f6c3e43734b2": "清除筛选后查看全部可用组件。",
     "s_f69273dbbebfb3a1": "格式化",
     "s_f699d16db6c37a35": "当前平台不能真正断网:关闭网络访问时只注入离线环境(代理指向无效端口、ssh 桩),不走代理的程序仍能联网。",
+    "s_f6dba35520d09e76": "telegram bot token botfather 机器人 机主 im channel 消息通道 连接 取消连接 owner approve revoke 授权 审批 撤销",
     "s_f6dc1b1641600dd0": "正在导入…",
     "s_f70f928df89406a7": "立即升级",
     "s_f72684a97677d48a": "对话问题轨道",
@@ -2346,6 +2531,7 @@ export const sourceCatalogs = {
     "s_f8209b2310bc54a8": "打开快捷菜单",
     "s_f82c68c72b8f9aca": "下一题",
     "s_f84c7d6122a7753f": "用量记录",
+    "s_f8567a884d2336b5": "撤销 {{p0}} 的授权?",
     "s_f896a064e0be9e4e": "解析失败,整个文件未生效:{{p0}}",
     "s_f8b6ebf2a9e19bbd": "已复制图片",
     "s_f8c104adf2f77e87": "请填写专家名称",
@@ -2409,6 +2595,7 @@ export const sourceCatalogs = {
     "s_fcea4baf388f169a": "运行核心测试，定位并修复可可靠复现的问题。",
     "s_fcf8b4bff0df782d": "打开文件夹",
     "s_fcffc107c99acbba": "已注册工作区",
+    "s_fd351bc95e9337e4": "发消息",
     "s_fd4b9e3b6c685bae": "继续编辑",
     "s_fd5fd3c4567938c7": "询问",
     "s_fd6529f1e944f8c7": "与当前会话共享文件；有任务运行时会排队。",
@@ -2429,6 +2616,7 @@ export const sourceCatalogs = {
     "s_ff199a8f48c79fd8": "审计日志已导出",
     "s_ff20131bcd4725f2": "还没有规则。确认框里选「以后都允许」也会自动写到这里。",
     "s_ff509c9ba052a21c": "保存中…",
+    "s_ff62ea25d5d6b3a6": "叫停成员",
     "s_ff63d45ac706d173": "在新会话中继续",
     "s_ff857f2b6ac947ac": "最近整合",
     "s_ff8b0d734b03b1a4": "自定义模型",
@@ -2458,10 +2646,12 @@ export const sourceCatalogs = {
     "s_01bf3b34f431074f": "This page does not meet App Transport Security's secure connection requirements.",
     "s_01ca13e5a1ebdc8d": "Checked items stay pinned in the sidebar; the rest live in the Extensions menu. Drag a row to reorder.",
     "s_01e1429e4860a2d5": "Weekly code change summary",
+    "s_01ebb09c9bad848f": "Feishu (China)",
     "s_020754edb04dde8d": "macOS system notification permissions",
     "s_0215ff0b3cce53f1": "Feedback content",
     "s_0220aafc260ee131": "After enabling the hooks function, the configured hooks will be displayed here",
     "s_025486bcb86499e3": "Please select a summary model",
+    "s_027be81bc401b0cd": "Connection failed; the reason is in the log. Check the credentials and retry, or go back to change them.",
     "s_029d7b3375ad16aa": "Rule written to file",
     "s_02b411ce6d16f108": "Dynamic context",
     "s_02bcdbc5a1453cb0": "copy relative path",
@@ -2480,8 +2670,10 @@ export const sourceCatalogs = {
     "s_051836569928a9f9": "edit",
     "s_054b73a972372bdb": "No usable terminal found",
     "s_05564f10bcba6ae8": "The same expert can belong to multiple Tags",
+    "s_057dc352ed0a0a29": "Change bot",
     "s_0580fcee37e02012": "Delete failed:",
     "s_05a531a083e68807": "Copy {{p0}} verification code {{p1}}",
+    "s_05abefa30a624a8a": "Dispatching a task",
     "s_05df17e0e401d645": "Ask Agent to refactor, fix bugs, and add tests",
     "s_05efef8465e0c666": "git response timeout (the warehouse may be large)",
     "s_05fdf30411d98d32": "Sandbox",
@@ -2502,6 +2694,7 @@ export const sourceCatalogs = {
     "s_07918dbd4c70b182": "Zoom out preview",
     "s_07a10608cd7a1e0c": "When off, sandboxed commands cannot reach the network (fully enforced on macOS / Linux)",
     "s_07b0e6eadae125e1": "target version",
+    "s_07bc10c7295f8dae": "Owner and approved contacts",
     "s_07bf8b28ae3680e0": "Expert component type",
     "s_07deea1ebeb8c9f8": "Read failed (HTTP {{p0}})",
     "s_07ee23a0924d3d0b": "Queue paused because you interrupted the current response",
@@ -2517,6 +2710,7 @@ export const sourceCatalogs = {
     "s_08af65aa6bfa1a95": "Hand-written rules files are read-only here; edit the files directly. A file that fails to parse is ignored as a whole.",
     "s_08ba7ec0955d1d28": "Starting Browser",
     "s_08d43bdc4dcb6253": "Update available",
+    "s_08e5a3f74d4c6894": "Scan with QQ on your phone and follow the prompts to create and authorize the bot",
     "s_08e9d9ef7d382947": "writes only",
     "s_08f10fb5ebba9e65": "Use dark backgrounds; turn it off to use light backgrounds",
     "s_0970eb5b921e82c5": "{{p0}} line",
@@ -2541,6 +2735,7 @@ export const sourceCatalogs = {
     "s_0acd4d885ae0c69a": "Source folders",
     "s_0ad947db2d9ee20a": "Operation is interrupted when daemon exits",
     "s_0ade55ea5a89bf7d": "Failed to write file",
+    "s_0adea32a9fd1dcbe": "Scanned. You are now the owner",
     "s_0ae64c633fbe0f42": "Check for out-of-date dependencies, security risks, and manageable technical debt.",
     "s_0ae7312510f4b495": "Collapse details",
     "s_0af42a6e2915abaa": "Could not delete memory",
@@ -2566,6 +2761,7 @@ export const sourceCatalogs = {
     "s_0c8320ac03732e4c": "Access token required",
     "s_0c869dac8a4aa550": "Please enter the full path to bash.exe",
     "s_0cc2ca1cf8347d79": "Task completion notifications disabled",
+    "s_0ced3f40670a5ac1": "Lark (international)",
     "s_0cf8b14f4651f4de": "last week",
     "s_0d0cbac2eee54113": "Rename",
     "s_0d0e1a86b3aa7877": "User",
@@ -2577,12 +2773,14 @@ export const sourceCatalogs = {
     "s_0d94ad38844747ce": "Switch failed:",
     "s_0d966a3d69ee069c": "When off, every command runs with your user privileges and unknown commands in auto mode ask for confirmation one by one",
     "s_0de50760cb250e32": "Remove model {{p0}}",
+    "s_0df737cb62bb5175": "Group",
     "s_0e0163080d2e4ad4": "Unable to get file path",
     "s_0e0c2d7597ef508d": "Missing",
     "s_0e1a7040390fb03e": "New project",
     "s_0e700e0f522f37ff": "Comparison baseline:{{p0}}(only switches the viewing object, not checkout)",
     "s_0e993148f8f5d3d2": "The Grok sign-in is invalid. Connect again.",
     "s_0eab58baf452449c": "Enter a full absolute path, such as C:\\Users or /home",
+    "s_0eb01c40432b05a9": "Connection lost, retrying automatically",
     "s_0eca7afbf4f68601": "Search for skill name or description...",
     "s_0ecd009b61757eae": "Create a separate worktree. Uncommitted changes are not included.",
     "s_0f415f8b2bbbb37a": "Failed to read running records:",
@@ -2596,12 +2794,14 @@ export const sourceCatalogs = {
     "s_10e80ac177155143": "Message cannot be empty",
     "s_111448a2e1a82306": "There are {{p0}} fields",
     "s_11152b370ff3e7ca": "Ultra quality model",
+    "s_1117493dfd5708d1": "Find the robot in DingTalk and send it the 6-digit code below in a private chat.",
     "s_1123245d1bed08b2": "Rule",
     "s_11448fff91a477dc": "Created",
     "s_1159250ae5748529": "Invalid close-window behavior",
     "s_117b19fd23b61edb": "Allow, prompt or forbid commands by prefix. Prefixes are split on spaces; git status|diff means the second word may be either. \"Allow (outside sandbox)\" skips the sandbox, so reserve it for commands that truly need it; interpreters, shells, rm and sudo cannot be allowed.",
     "s_117c113c3b45cf89": "queue",
     "s_1198cb9da295145d": "New sessions use this mode by default, and the current session will be switched synchronously.",
+    "s_11a4dc9fc810be2f": "Set the robot's message mode to Stream, grant the internal robot send-message permission under Permissions, then publish the app.",
     "s_11a6ac8794688be8": "Matched a prompt rule",
     "s_11b999fc4610de85": "networking",
     "s_11cb87897cfb7e7b": "{{p0}} capability",
@@ -2621,6 +2821,7 @@ export const sourceCatalogs = {
     "s_132411ba41da7354": "reasoning",
     "s_132a029e79ec9872": "Share with agent",
     "s_13357fcd2d59d851": "The command prefix must not be empty",
+    "s_13439ef69aeff4f2": "Copy the App ID and App Secret from Credentials & Basic Info and enter them below.",
     "s_134a1a3e2b52b04f": "Collapse the entire right panel",
     "s_134fdd6479c8036b": "Send (Enter)",
     "s_13670a878cf6f01d": "ACECode upgrade",
@@ -2635,14 +2836,17 @@ export const sourceCatalogs = {
     "s_13f6a415ac664be2": "Detect the actual model list from this provider",
     "s_140b07fe3f9f7d48": "Download size:",
     "s_1417bae3d17d6405": "Collapse images",
+    "s_142cf02f83d4e7ab": "Writing reply",
     "s_14357c0d6ca270df": "Check that the address is correct, then try again.",
     "s_14381a6ef00a1253": "Regular testing and problem fixing",
+    "s_143dab9db74c3131": "All set",
     "s_145219e726b87790": "Hidden",
     "s_145eb48a326b5d27": "Tool rewrite",
     "s_148d195e21b05db5": "Configuration",
     "s_14cbad1d857ee3e6": "Disconnected. The stop has not been confirmed",
     "s_14d1e349b14010a9": "Cancel download",
     "s_14e7acfc08afa9e9": "Browser component stopped",
+    "s_14ee02a96d9bca6d": "Connected · {{p0}}",
     "s_150dd0cecdc803d0": "Current workspace",
     "s_150f3c28d9d036af": "Title cleared",
     "s_155c2f5d0a3b2394": "Notebook",
@@ -2671,24 +2875,32 @@ export const sourceCatalogs = {
     "s_1832990660bb60c2": "function",
     "s_183b5f823fdb5522": "Failed to add workspace:",
     "s_18435419f154847b": "Command prefix",
+    "s_1843acb8c6ea0f47": "DM the bot or @mention it in a server channel to give instructions. Results come back to the channel.",
     "s_184568b57e5e6d3f": "Generating test image…",
     "s_1847a84db6d5fc1a": "Permission mode switch failed:",
     "s_18565a5455a0a875": "Could not load sandbox settings",
+    "s_18578640315b5b33": "Updating todos",
     "s_1882a447d5f76d5f": "Feedback cannot exceed 10,000 characters",
+    "s_188397c445996182": "Connected by another ACECode",
     "s_18850bf66a4ba4c6": "The model requests temporary extra sandbox permissions",
+    "s_1903b018a3b98d7d": "{{p0}} bot",
     "s_19086bec77d5e5e5": "Automatically compatible with system naming rules",
+    "s_190eedb7bfaa8609": "Adding a follow-up task",
     "s_191041794ad98158": "(all matches)",
     "s_1910636fddbffe3e": "Read application controls and operate the mouse and keyboard",
     "s_19107d868966ff2c": "Session title",
     "s_194b5dba3c63f537": "Reasoning settings",
     "s_1964dafada0807b5": "Git branch",
     "s_19af3dcd414d81df": "{{p0}} attachments",
+    "s_19bf536853e2e78a": "Collaborating",
     "s_19bfb1631d25a204": "Saving theme…",
     "s_19cfa7d09d8dd287": "Dispatching…",
     "s_1a0bf11a28779888": "Fill in the real chat box after selection, it will not be sent automatically",
     "s_1a16ea81ee6a29e4": "The site could not complete the redirect. Try again later.",
+    "s_1a474c3207ed49f4": "Standing by",
     "s_1a4c6ebd7bbdbaa8": "No competency introduction has been filled in yet.",
     "s_1a52bda1e037f2c3": "Used while executing, coding, or handling a task",
+    "s_1a6c41c6ee173bab": "Bound to {{p0}}",
     "s_1a7224bf1e427ee4": "Fork failed: No session_id",
     "s_1a7e48179574fffa": "Collapse change summary",
     "s_1a7eef17e199fa07": "Collapse command details",
@@ -2700,6 +2912,7 @@ export const sourceCatalogs = {
     "s_1ae7a34c1452785e": "Markdown WYSIWYG editor",
     "s_1afed6a81a2512d2": "Select model",
     "s_1b14bd33bab15a6d": "Inherit global settings for {{p0}}",
+    "s_1b442420620b3bb4": "You can now message the bot privately in Feishu. Add it to a group and @mention it there; the first time needs approval in Settings.",
     "s_1b479e1420fb0342": "Directory allowed",
     "s_1b4bc8cfe06cb405": "Mark as read",
     "s_1b58f84ec946fe67": "Career/Position",
@@ -2747,6 +2960,7 @@ export const sourceCatalogs = {
     "s_1f4b8e02fe0eb7ab": "You can select multiple models and fill in the new model form at once after confirmation.",
     "s_1f6c6927e129a5f5": "Please upgrade and restart the ACECode daemon and try again.",
     "s_1f79c9f362dc9d4b": "Could not save appearance settings; restored the last saved settings:",
+    "s_1f9d55088d4f8ec0": "The owner can switch to any session; others can only switch between sessions they created.",
     "s_1fca6787d35baa53": "Enter Plan",
     "s_1fcd48a731ea363a": "Native selector returns invalid results",
     "s_1fe3eb68a68b187d": "Allowed and remembered",
@@ -2769,6 +2983,7 @@ export const sourceCatalogs = {
     "s_21482b7f3029698f": "Make lead",
     "s_21493a0f78021d9b": "Select current folder",
     "s_2156709a76aa43e6": "Enter message…",
+    "s_2157f1235d2a58ee": "Member {{p1}} of group {{p0}}",
     "s_21a08761b9914419": "One entry per line. ~ is the home directory,:workspace_roots the current workspace root,:tmpdir the sandbox temp directory; everything else must be an absolute path. The deny list accepts wildcards such as **/.env.",
     "s_21a9727afd60df42": "Swarm mode (Star) enabled",
     "s_21cab4f2e52fbfef": "Unnamed conversation",
@@ -2777,6 +2992,7 @@ export const sourceCatalogs = {
     "s_2217610d8e605cdc": "Open the global Skill Catalog",
     "s_222c9c161b8907d6": "This conversation has been compacted several times. Continue the current work in a new conversation.",
     "s_222eac7780eaef4d": "Model configuration checked",
+    "s_225a51a3b48fddf4": "DM the bot in Discord (you need to share a server with it) and send the 6-digit code below.",
     "s_227ea7277bfc00e9": "Failed to load MCP:",
     "s_228d8b711ccf3ab3": "Submit feedback",
     "s_228f61d57a0a4568": "Explicitly selected",
@@ -2797,9 +3013,11 @@ export const sourceCatalogs = {
     "s_23f176008ae4f3bd": "The native file data is invalid",
     "s_246e46c2a4189cb5": "Rename failed:",
     "s_248e8e2921bcc92c": "conversation messages auto collapse fold expand tools",
+    "s_251dee09f7adbd2e": "Fill in the credentials first",
     "s_2529b19bc41c0e9e": "Request format error",
     "s_2539cf900d5b8d37": "Installing updates",
     "s_255c8d56e8bb1295": "No matching results",
+    "s_2560c96f89c6fea0": "Create an official account in LINE Official Account Manager and enable the Messaging API under Settings > Messaging API.",
     "s_257bbcc44c839db4": "Modified",
     "s_257c21aae4198b7e": "Setup and review",
     "s_25c76c88d05b627c": "Native filesystem bridge unavailable",
@@ -2809,18 +3027,23 @@ export const sourceCatalogs = {
     "s_25ec0421b03bc4f3": "Drag to adjust the width of the right column",
     "s_261dba7261ed8c05": "Description cannot be empty",
     "s_2623156dcd71bf2d": "Asterisk",
+    "s_264333fb5458a573": "Preparing a tool call",
     "s_2657124b1481b789": "Provided by project",
     "s_267c4a7a86dd1849": "All types",
     "s_26ab0eee67e8c707": "Tool called",
     "s_26c8aefe6fbfa744": "Sandbox, file and command policies, plus an audit record of every decision.",
     "s_26da3cee0bb25151": "Wait for user to reply to AskUserQuestion",
     "s_26df939b25bc7b02": "Queued message",
+    "s_270dd2ebfcbec271": "Add the official account as a friend in LINE and send it the 6-digit code below.",
     "s_2719a8ea304b8cbf": "from",
     "s_2719f7ce2ace6db7": "Can't open macOS notification settings",
     "s_2721b6c32975b55d": "Remote Web connection",
+    "s_27389885c97c4ab1": "DingTalk",
+    "s_273f40d0251a8261": "Open DingTalk Open Platform",
     "s_2745ccb884fcf6ab": "Feedback",
     "s_27586f180db1c812": "renamed",
     "s_2812f6c1263c96a9": "Deleted “{{p0}}”",
+    "s_281b0924bb9c5a16": "Scan with WeChat and confirm on your phone. The WeChat account that scans becomes the owner and is the only one who can use the bot.",
     "s_28200a87c40ced80": "Import and apply",
     "s_28321cb9b77f137c": "Branch from here",
     "s_2834cf755087f50d": "Summary generation",
@@ -2860,6 +3083,7 @@ export const sourceCatalogs = {
     "s_2c7dfb7f0b25589e": "Search current conversation content",
     "s_2c843e836a4d4422": "Failed to save close-window settings:",
     "s_2c8855fc8ab8f5fb": "No usable non-local network address was found. Check your network adapter.",
+    "s_2c8904ba4a192db8": "Create bot",
     "s_2ca1a16a870f47d3": "No matching settings",
     "s_2cc0b5d70839d137": "Mermaid source",
     "s_2cd0f3be8738a86c": "Cancel",
@@ -2913,6 +3137,8 @@ export const sourceCatalogs = {
     "s_31ebdbfa17b81a02": "Model saved",
     "s_32058ae99d61249c": "Could not get migration progress: {{p0}}",
     "s_321e4914f68c1db0": "Unknown upgrade error",
+    "s_3221a042ea3677a8": "Regenerate",
+    "s_323bf944ea7c06e1": "Give instructions in a Feishu private chat or by @mentioning the bot in a group. Results come back to the chat.",
     "s_3264ce720a9e420d": "The theme is downloading. Please wait.",
     "s_326d1d537e72f82d": "Starting or stopping reverse proxy",
     "s_327f00da9fc2ec36": "Hide details panel",
@@ -2939,15 +3165,18 @@ export const sourceCatalogs = {
     "s_34b3cac2a496d263": "Model catalog",
     "s_34c3c3b2bd45600d": "Expand all diff",
     "s_34f7336d39831fca": "Close all",
+    "s_350a7736d0d4cb03": "Set owner",
     "s_3548b099890e187f": "Model usage details",
     "s_3568d317c8161ad4": "This is an embedded browser.",
     "s_357211096f78cdb8": "Set as default",
     "s_3590fba381ad57f0": "Selected text actions",
     "s_35c52c32418a2678": "All {{p0}} entries will be deleted and cannot be recovered. Export first if you need a copy.",
     "s_35cda8a7052dec20": "Migration failed",
+    "s_3615b021b8af5e82": "Wrapping up",
     "s_3620d3d986f14584": "Close model dialog",
     "s_3625f9fa2f9c629a": "Command denied",
     "s_364970d8168ca5fe": "Sending…",
+    "s_3687f953cfe85fb8": "Disconnect",
     "s_369078855fa122f7": "Read-only tool calls",
     "s_36f33adaf0942634": "Confirm",
     "s_3703e47860f64a12": "File does not exist",
@@ -2957,13 +3186,16 @@ export const sourceCatalogs = {
     "s_375f5091e213f094": "Paths are on the machine running the daemon",
     "s_377e4422342c71f7": "Problem feedback has been uploaded",
     "s_3785cba81d184679": "Current workspace memory",
+    "s_378eaca774bb9551": "Scan to sign in",
     "s_37979829426b0cdb": "Workspace",
+    "s_37a41b2e983b06ee": "Using a skill",
     "s_37c427d9f5dc817d": "The default model has been set to",
     "s_37d36b087f49c6d2": "Select expert component",
     "s_37e4e42c314102da": "image",
     "s_381117baedb79e1a": "After choosing a provider and model, only settings supported by that connection are shown.",
     "s_381796352dc0301d": "Settings were saved but could not be applied. Please try again",
     "s_3819d5e4aa5dba68": "Pen",
+    "s_38744132b501a1eb": "Question",
     "s_38c043e08502e710": "Personalization",
     "s_38cd88ed8b3ddbf1": "Copy full output",
     "s_38d456bbdb81317c": "Filter by Tag",
@@ -2971,6 +3203,7 @@ export const sourceCatalogs = {
     "s_390fd9bc7d9d7a2a": "Audit Center",
     "s_392d0dceb45998d3": "Extra high",
     "s_39592d688f12a5a6": "An entry with the same name already exists",
+    "s_3969d8203ae05775": "QR code for connecting",
     "s_39932f24fe11a6ba": "document",
     "s_39a9046f9c8c993d": "Recently used",
     "s_39b068ea492a4f9a": "Model capability label is invalid",
@@ -3012,10 +3245,12 @@ export const sourceCatalogs = {
     "s_3db7b06b5f6de0e0": "Working directory",
     "s_3dcff5522afda275": "Prompt cache hit rate",
     "s_3dd1245c155aba60": "The model configuration is unavailable; the current connection was retained",
+    "s_3dd922527fba482d": "Add the bot to a group and @mention it there; the first time needs approval in Settings.",
     "s_3de42d7c68d442e5": "Single",
     "s_3df739dcd8a069eb": "Recent conversation history",
     "s_3e04f83df97fa6f2": "Oldest updated",
     "s_3e48e68ed87a9add": "Click the empty area or press / to type a path",
+    "s_3e6221be3922f850": "Scan with WeChat and confirm on your phone",
     "s_3e65bba57b173f30": "The pasted text is too long for the /{{p0}} limit ({{p1}} bytes). Remove the command to send it as a normal message, or shorten it",
     "s_3e7d75b94f3a1f26": "Failed to load tool rewrite settings",
     "s_3ea0e6e41518ea24": "Empty directory",
@@ -3067,6 +3302,7 @@ export const sourceCatalogs = {
     "s_42e1b73173a3b1d4": "Could not confirm the expert switch status: {{p0}}",
     "s_432a6c3328243eee": "Could not reach the xAI device authorization service",
     "s_4334aa1fdaa5a8c1": "Observations extracted from sessions that have not been consolidated into memories yet",
+    "s_433779053c77eea8": "Bot {{p0}}",
     "s_434203a723b4614e": "updated",
     "s_4342d572b0ee2718": "The main session can still continue typing",
     "s_434c7efecbad5725": "Please select execution time",
@@ -3076,11 +3312,13 @@ export const sourceCatalogs = {
     "s_4382c23e9e50479f": "The Agent has completed the plan and exits Plan mode after requesting approval.",
     "s_43911903e1cf7e63": "Preview content copied",
     "s_43cad95bdcdcc30d": "Upgrade failed",
+    "s_43ce458cae49a1ad": "Thinking",
     "s_43d7d2b51d75fa42": "Create project",
     "s_43db2741a745b179": "Enable server",
     "s_43f3dc12a6077835": "Starting...",
     "s_43f4a4d322d58a5b": "Edited {{p0}}",
     "s_43fc32e85fb21c53": "Active goal",
+    "s_43fcef33a825715a": "Paste the token below. Once it is verified, use the invite link to add the bot to your server.",
     "s_43fd0fc1e9ae1edb": "Name conflict resolved",
     "s_4430768f253a5d6d": "Enable tool rewrite for subsequent model requests",
     "s_443cb29217829285": "Review specialties and dispatch to a new task, or manage your own experts and expert teams.",
@@ -3116,6 +3354,7 @@ export const sourceCatalogs = {
     "s_475ac58abf66032b": "Could not load the root folders: {{p0}}",
     "s_476c022a773e1f82": "Close other ACECode windows before migrating",
     "s_478211dd029aa604": "The site security certificate is invalid or does not match this address.",
+    "s_47b50c43e14ca6ba": "Scanned",
     "s_47c99fb0ddf2cffa": "{{p0}} – {{p1}}: {{p2}} tokens used in total",
     "s_47f22728ee1600ed": "Status message:",
     "s_481acc2c1413db38": "Image generation",
@@ -3126,6 +3365,7 @@ export const sourceCatalogs = {
     "s_4871613a44be8d7a": "Where to open files and folders by default",
     "s_487422ef0c4e25b6": "Home title",
     "s_48807d75530c1b03": "This queued message cannot be found",
+    "s_4888c0a26e905c1f": "User {{p0}}",
     "s_48d75d4b7e92d9f2": "Switch to project",
     "s_48f78f1abeca0c47": "The pasted content is large ({{p0}}) and will be uploaded in {{p1}} parts",
     "s_490a88b8ae9d4a2e": "This model no longer exists, please refresh",
@@ -3141,12 +3381,14 @@ export const sourceCatalogs = {
     "s_4a6d8d490c54d438": "allowed once",
     "s_4a83accbad2c11e1": "opening remarks",
     "s_4a8d6841b4023edf": "Confirm import",
+    "s_4aa95aa725909efe": "Add the bot to your server",
     "s_4ab32793197b28db": "The selected model is unavailable; the scheduled task was disabled",
     "s_4ac9db43b40c292d": "The current backend does not support Computer Use. Update ACECode, restart, and try again.",
     "s_4ad732f1d78f6725": "Background process",
     "s_4ad8aa6461e64127": "Previous (Shift+Tab)",
     "s_4af8f4c6dd2e233e": "Brain",
     "s_4afad488b461b58f": "Side chat history",
+    "s_4b19c2f91cd3f418": "Messaging channels can only be configured on the computer running ACECode",
     "s_4b427656a253ca1e": "Fully quit and restart ACECode",
     "s_4b47dbae97ba938a": "prompt word",
     "s_4b50c9fa24dcafa3": "No model configured",
@@ -3168,6 +3410,7 @@ export const sourceCatalogs = {
     "s_4cc7b00050cb1c21": "OK",
     "s_4cca8a4406aea952": "Confirmation required",
     "s_4ce87e7fe2b6e95d": "File or folder",
+    "s_4ceae06adf5b9199": "Their messages stop being processed immediately, and any running turn in their sessions is stopped.",
     "s_4d0680f9efaef147": "unread",
     "s_4d2b19065afe4b07": "LSP is on:{{p0}}",
     "s_4d3f6a081ea86097": "Complete deletion failed:",
@@ -3190,7 +3433,9 @@ export const sourceCatalogs = {
     "s_4ef515abfdb8690d": "Installation package",
     "s_4f01af9093fc9e59": "Cannot connect to this site",
     "s_4f021f59121c6827": "Waiting for execution",
+    "s_4f1f6ea2b75de587": "Messaging channels",
     "s_4f2bf16cc26825e8": "Unselect custom answer",
+    "s_4f3bac187963a04a": "Manage {{p0}}",
     "s_4f5b0e563a452c80": "Refresh skill list",
     "s_4f61317e9307ad3e": "Access denied",
     "s_4fca07787f3ef1ec": "Remove this pending attachment?",
@@ -3198,6 +3443,7 @@ export const sourceCatalogs = {
     "s_4fe5ca6370a901ef": "ACECode local tool categories",
     "s_4fed9b0a87376127": "Theme workshop",
     "s_5002a3c1c2822955": "Native and managed",
+    "s_500b6710a6f009cc": "Create and publish a version under Version Management & Release, with availability including yourself.",
     "s_5019872ac7610542": "Cannot open this site securely",
     "s_5026a63b58cdf048": "Executing",
     "s_50563579e4119e75": "Other rules files",
@@ -3233,6 +3479,7 @@ export const sourceCatalogs = {
     "s_52b06532811be3e4": "Duplicates another rule",
     "s_52b44d4d2c562541": "Connect xAI",
     "s_52d25a9e30ba94f1": "About",
+    "s_52ebdbe6cf99a77c": "No one is approved yet.",
     "s_52f79fed15ec2723": "Current model",
     "s_52fb62f878dcdbef": "Theme verification failed. Download it again.",
     "s_5305d3b2b3f1648f": "Popcorn",
@@ -3263,9 +3510,11 @@ export const sourceCatalogs = {
     "s_55db57105231bd95": "Workspace is unavailable",
     "s_55ef676879f7cca3": "The diff is too large, please check it in the terminal",
     "s_561817f0252936a9": "Allowed",
+    "s_562834f547655a37": "Searching code",
     "s_5653d97cdf569cb9": "Your system firewall, router, or cloud security group may still need to allow the proxy port. For public Internet access, continue to use a trusted VPN and configure HTTPS upstream.",
     "s_56627c94a9decee6": "Maximum output tokens",
     "s_566e5f182a63185d": "Compressing theme files…",
+    "s_5670da45d1d6e526": "App ID (starts with cli_)",
     "s_567146d66825e213": "Enable automatic line wrapping",
     "s_56964754c2e1ab57": "Reverse proxy listening on {{p0}}:{{p1}}",
     "s_569af1a47dbdf053": "up to date",
@@ -3287,6 +3536,7 @@ export const sourceCatalogs = {
     "s_57e4fcb2dad50b5c": "Remote Web mode enabled",
     "s_57eb46dacc97defb": "Show the last active time on the right of each task row; when off, it is still available in the hover card",
     "s_5804b9cca84304ff": "Clear side chat",
+    "s_58210afb340c2c5e": "The link is valid for 10 minutes and works once.",
     "s_5835048333dad1d6": "Select custom answer",
     "s_584f28c1077647a9": "Cancelling...",
     "s_5868e5f7632072d9": "Denied {{p0}}",
@@ -3340,8 +3590,10 @@ export const sourceCatalogs = {
     "s_5d7fd21f1e3ca6b4": "Copy message",
     "s_5d817dbb5da09259": "The theme import returned an invalid result. Refresh and try again",
     "s_5d937ed111134879": "Model capabilities",
+    "s_5ddcb16ab6fcb808": "Checking members",
     "s_5ddffd77ea7fedae": "Loading saved models…",
     "s_5e56bec8550f499d": "Choose a directory",
+    "s_5e78c941de4a98ed": "Connect {{p0}}",
     "s_5e80c1e561d45b11": "Select permission mode",
     "s_5e8e7af57abbcbcf": "Deleting…",
     "s_5eaefa4a3950e8a3": "Choose a new path",
@@ -3352,11 +3604,14 @@ export const sourceCatalogs = {
     "s_5f53727059cdc69a": "Enter your answer",
     "s_5f5a4c5fb8ab71d6": "The input box is currently unavailable",
     "s_5f5b6195dfd24aa1": "Waiting for interactive content to be synchronized",
+    "s_5f76b2bf82dd2c5d": "Region",
     "s_5f7780324a4b55f1": "Conversation continuation suggestion",
     "s_5fba64a2b5976bd4": "Upload failed, click to retry",
     "s_5fcad9600a50f834": "Close the tab on the right",
     "s_5fe46d0c2faeacf7": "Choose a model connection",
     "s_605a534da98e42ec": "Token activity view",
+    "s_60b83f21d9d5d703": "Group {{p0}}",
+    "s_610a30de692b91b0": "Forward your public address to http://127.0.0.1:{{p0}} on this computer. Setup continues automatically once it is reachable.",
     "s_610e4e820d6881ea": "Completely delete session \"{{p0}}\"? This action cannot be undone.",
     "s_6135d4159e892541": "Remove",
     "s_613de904cc604e3b": "{{p0}} local tool {{p1}}",
@@ -3369,7 +3624,9 @@ export const sourceCatalogs = {
     "s_624b5799ebd036b0": "No workspace",
     "s_6258a2c6f9c89143": "Copy all",
     "s_62731d95bc805803": "Exporting…",
+    "s_6278c2f645ab3982": "Public address",
     "s_629bb52ce0e5270f": "Added {{p0}} to chat",
+    "s_62b72265c96e5e34": "Retrying",
     "s_62c850eabc4ba70e": "Partial search data failed to load:",
     "s_6309a3bb5ba4c714": "Save failed",
     "s_63448df0ea0c5be2": "Interjection interrupted",
@@ -3385,7 +3642,9 @@ export const sourceCatalogs = {
     "s_641778357a5e8a41": "View configuration schema",
     "s_643a1b94e9498780": "Trusted hook",
     "s_6492494fbe805292": "Describe your idea, create your theme",
+    "s_64ded447c5bdd6ea": "Verify and continue",
     "s_64e9f3e72b149b27": "This page exited unexpectedly. Reload it.",
+    "s_64fd6a54381b531c": "Couldn't get a QR code. Try again",
     "s_64fdd111ae7c2ead": "Workspace migration is in progress. Wait for it to finish, then restart.",
     "s_651ec477427c76eb": "Add capability or context",
     "s_65273e466af9881c": "From background task:{{p0}}",
@@ -3396,6 +3655,7 @@ export const sourceCatalogs = {
     "s_65b3f17534a8c0ab": "Could not load memories",
     "s_663a5905150ea46d": "Check your system proxy settings, then reload the page.",
     "s_664c216a6c75054f": "/expert-manager Help me create an XXX expert specializing in XXXXX. My experience is: [add your industry background and relevant experience].",
+    "s_66687ec68c240db9": "Turn on Use webhook on the Messaging API page, and turn off auto-reply and greeting messages in the official account's response settings.",
     "s_6679f618e868b532": "slash command",
     "s_667b75d63a19b6b8": "Upload failed:",
     "s_66809c2ae51ddf06": "Remove Tag {{p0}}",
@@ -3447,7 +3707,9 @@ export const sourceCatalogs = {
     "s_6aa3b1bd38fe141b": "name cannot be empty",
     "s_6abdf8409678b516": "View in the review panel on the right",
     "s_6ad55eb177526999": "Zoom in preview",
+    "s_6add2714c40f1d45": "Private chat",
     "s_6ae40b532ea0f924": "Work has continued in a new conversation.",
+    "s_6aecec7bb2ae1d74": "Public address (optional; leave empty for an automatic tunnel)",
     "s_6b01fce4dbeaeeb9": "Change",
     "s_6bbaf705e8c64c2b": "Folder contents",
     "s_6bea77acefb364ac": "Standard",
@@ -3464,6 +3726,7 @@ export const sourceCatalogs = {
     "s_6cec8d70466c7b55": "Get ACECode updates from Library in Microsoft Store.",
     "s_6cf2531ab1119b67": "Authorize",
     "s_6d0b032bc4d31ea2": "Copy title",
+    "s_6d0d116c95898867": "Owner",
     "s_6d330244eecae355": "Failed to connect to daemon:",
     "s_6d3d916f1807a4d2": "Continue to add tags",
     "s_6d5503cc0bd22117": "Select detected model",
@@ -3478,6 +3741,7 @@ export const sourceCatalogs = {
     "s_6dc0d06dd58b2cb6": "Built-in default deny list",
     "s_6dd39868b7d587c7": "The current background service does not support the Security Center. Update ACECode, restart and try again",
     "s_6e1ba4bf187327e9": "Terminal program path",
+    "s_6e382d9250f8dc10": "Enter manually",
     "s_6e392a597af4abab": "memory summary model",
     "s_6e55e0f207bfd2e0": "Run history",
     "s_6e6aba42eba94da0": "Shared with agent",
@@ -3487,6 +3751,7 @@ export const sourceCatalogs = {
     "s_6f4b75ff28679ce4": "Flat list",
     "s_6f5994e138557f90": "% used",
     "s_6f87682bc02532c6": "Each workspace can have an independent Skill, which only takes effect in the session of that workspace.",
+    "s_6f98bb98abfcd0c9": "Open the Feishu Open Platform, create a custom app, and add the Bot capability under Add features.",
     "s_6f9c11640850a30c": "Could not clear the audit log",
     "s_6fb9dd3555d1b3b0": "Confirm migration",
     "s_6fc38ef3602fe789": "Context",
@@ -3512,12 +3777,16 @@ export const sourceCatalogs = {
     "s_71dcce0699b98a09": "Expert components",
     "s_71dfe4a817b8801d": "Please log in to Copilot first",
     "s_71e95b289aad1f6a": "skipped",
+    "s_71ea09dd1e9905d5": "If Telegram is signed in on this computer, you can also click the link:",
     "s_71f09042e226bdf9": "High quality model",
     "s_71fa1b09e415447e": "Configure the identity, areas of expertise, opening remarks, and runtime capabilities in the same expert.",
     "s_720182db8f88cf7d": "Reading runtime capabilities...",
+    "s_722dd20ced9e6d55": "Send the bot a private message from your {{p0}}. A request appears below; approve it to become the owner.",
     "s_725831ec12394243": "Unarchiving failed:",
+    "s_72ccb1274a093efb": "Enter the bot's AppID and AppSecret from QQ Open Platform. They are verified before saving.",
     "s_72dde8dfef88d37d": "Confirm to add",
     "s_72ec61d7855c86a1": "Request timeout (seconds)",
+    "s_737c725c1321d260": "Saved {{p0}}. Leave blank to keep it",
     "s_73952aa91a9366b5": "Switched to",
     "s_73ae35f541bc8124": "Copy attachment address",
     "s_73b629753f6d5fe5": "All diffs copied",
@@ -3526,6 +3795,7 @@ export const sourceCatalogs = {
     "s_73e5df48000d6a22": "Choose task location",
     "s_73fab2d02ab591cb": "Model test failed {{p0}}: {{p1}}{{p2}}",
     "s_7409a608060f5804": "not specified",
+    "s_741a285fa14f8523": "Compacting context",
     "s_742025b1a0eccc8c": "Invalid type",
     "s_743342489c23fe24": "Refresh memories",
     "s_744a61203be24c0b": "per {{p0}}{{p1}}",
@@ -3564,6 +3834,7 @@ export const sourceCatalogs = {
     "s_76e350aa9b3cf01a": "Reading default location...",
     "s_76ebf39ee090026f": "Escalation cannot be approved unattended",
     "s_76f677430db630af": "The embedded Browser is available only in ACECode Desktop",
+    "s_7715155115f58274": "Back to QR code",
     "s_77322b7c285eb8bd": "Theme deleted",
     "s_7734b5d136de7bdb": "Automatic restart failed:",
     "s_77423bdd32d35ce3": "Edit the message you just sent",
@@ -3583,11 +3854,13 @@ export const sourceCatalogs = {
     "s_78e5c1be3c1a2347": "Kettlebell",
     "s_78ea07a31cd96f65": "Starting from this version, new token usage will be recorded, and historical sessions will not be backfilled.",
     "s_79167440a990362e": "Session exported:{{p0}}",
+    "s_79209170acff4896": "Waiting for approval",
     "s_79383e9981843085": "Read web core information",
     "s_7948c26c9630a0cc": "Senior development engineer",
     "s_79612d07708f27c8": "Platform status",
     "s_7967bb84220ae3d1": "There are no skills in this workspace; they can be found by placing them in the project's.acecode/skills directory.",
     "s_797644874d78c30a": "Clipboard unavailable",
+    "s_79ee5900e8dc266b": "{{p0}} pairing request",
     "s_79f326be4409d51f": "Project",
     "s_7a0b79e584676550": "ACECode global project directory",
     "s_7a437376c304672c": "Add this message before the next model call in the current round",
@@ -3596,6 +3869,7 @@ export const sourceCatalogs = {
     "s_7a8a11ead50742a2": "Add to",
     "s_7a9b22bb6b0a159e": "Grok Coding Plan disconnected",
     "s_7aa6d0ef5feb745c": "Delete completely",
+    "s_7ace720715576424": "Binding code",
     "s_7acf2ee49b4924ef": "Location: {{p0}}",
     "s_7ad6bbf3f8508928": "Dismiss suggestion",
     "s_7adc856731f31518": "Not run yet",
@@ -3603,6 +3877,7 @@ export const sourceCatalogs = {
     "s_7afb72a4b5b21193": "Add workspace",
     "s_7b00c3d69a0c48a5": "models",
     "s_7b10b3966368f243": "no match",
+    "s_7b113358cc1fe5fd": "A new contact",
     "s_7b1347c4ded0097a": "Side chat",
     "s_7b187349d641590c": "Export session failed:",
     "s_7b1c1c5b441d279b": "Check the site address and your network connection, then try again.",
@@ -3630,6 +3905,7 @@ export const sourceCatalogs = {
     "s_7d09ee28674f2d4b": "Reason for skipping:",
     "s_7d1070ff5c5b7bdf": "[Pasted text: {{p0}}]",
     "s_7d166479398a3bce": "Submitting interjection…",
+    "s_7d20222788427d6b": "Under Permissions, enable: im:message, im:message:send_as_bot, im:message.p2p_msg:readonly, im:message.group_at_msg:readonly, im:resource.",
     "s_7d3a4b81e7018779": "Conversation history changed. Try again",
     "s_7d4ca7f48effd602": "big",
     "s_7d6667c86ebec2fa": "Goal completed",
@@ -3642,11 +3918,13 @@ export const sourceCatalogs = {
     "s_7df5c456c765e4c3": "Disable",
     "s_7e1df49bc3432fb2": "The provider definition for this profile was not found",
     "s_7e2ffe585c643f17": "best-effort offline",
+    "s_7e4419d1de251094": "Feishu",
     "s_7e8586f653066a9c": "Delete model profile",
     "s_7e963d9ae21a7ad5": "Summary model",
     "s_7ea852a1f549b6ca": "Enter a scheduled task name",
     "s_7ecf1cde648680d2": "Selected",
     "s_7ecff345fb5ca29e": "Copilot authorization verification failed",
+    "s_7ed80e44eaf9c51c": "Writing a file",
     "s_7edb086ee0d4c6c8": "Task completion notifications are enabled, but macOS permission was denied",
     "s_7ee8b2d0ae7ade97": "Remove attachment",
     "s_7efe433909425026": "Custom request headers are invalid",
@@ -3657,6 +3935,7 @@ export const sourceCatalogs = {
     "s_7f64e6cc3a5dccc7": "Resize background task panel",
     "s_7f68ebad19ba6bcd": "Check for updates",
     "s_7f6c661eb101f549": "Connect GitHub",
+    "s_7f92b2869303b795": "Message the bot privately in WeChat to give instructions. Results come back to the chat.",
     "s_7fd7c6c1c60155c2": "No selected text to annotate",
     "s_7fe9cf36941a738f": "Maximize preview panel",
     "s_80160e448f307c23": "Show preview only",
@@ -3674,18 +3953,23 @@ export const sourceCatalogs = {
     "s_8143449ded6af56c": "Expand project",
     "s_81508b76150acb3d": "Leave empty to search PATH",
     "s_817af552ff22fdff": "Loading failed:",
+    "s_81b430b696435180": "WeChat",
     "s_81c9f5ef56c3acfd": "summary title generation local model summary model session title",
     "s_81ee43758501ff89": "For example, 128000",
     "s_81f19964ae735b1a": "Advanced features",
     "s_81fd16a12933fe19": "Edit {{p0}}",
+    "s_8227ca04cabbb5e8": "You can now message the bot in WeChat. WeChat bots only support private chats.",
     "s_822fb37dba29381a": "Select file",
     "s_82395d423099a07a": "Archived",
+    "s_823b4ba6e569146a": "Copy the Channel ID and Channel secret from the channel's Basic settings in the LINE Developers console and enter them below.",
     "s_825a80f75113a9d3": "Prompt cache hits: {{p0}} of {{p1}} input tokens ({{p2}}%), {{p3}} written to cache",
+    "s_82601c48d5d64d71": "Editing code",
     "s_8268968d4a8759fc": "This model does not support tool-free side chat. Switch models and try again.",
     "s_82808f881bf7755f": "Team Members ·{{p0}} people",
     "s_82a043c05e8a9446": "Expert name",
     "s_82c4aa13b7ca109e": "maximize",
     "s_82ec71d0714dc013": "Connecting to Windows WebView2.",
+    "s_8301f8304e5dd793": "Couldn't get a QR code. Retry, or enter the credentials manually",
     "s_836c3d5d6bc88f78": "Confirm before writing/executing operations",
     "s_837415ff50de9e5c": "match:",
     "s_837acaec000d9f38": "Saved. {{p0}} suspected secret(s) were replaced with [REDACTED]; the saved content is shown above.",
@@ -3711,17 +3995,20 @@ export const sourceCatalogs = {
     "s_8526267fcc158a52": "Show earlier messages",
     "s_85501294b3c40740": "The content exceeds 500,000 characters and editing it here would be slow; copy it out, edit it, then replace it with the clipboard content",
     "s_8569e005ca1f98f1": "Skill catalog opened",
+    "s_856dba844b90b484": "Open LINE Official Account Manager",
     "s_8585b2747da94d76": "Page redirect failed",
     "s_85c016964ce0bedf": "Directory not found",
     "s_85c5c1f5567b4d67": "Annotate",
     "s_85e2f5601c1a0258": "Unattended",
     "s_8609635074718e14": "Referenced to chat",
     "s_86353011351e5d0b": "opencode session import failed:",
+    "s_8652e90f49cd7463": "Calling MCP",
     "s_86542c6b657c93ab": "Session: {{p0}}",
     "s_86624f5719c93e79": "Show {{p0}} earlier messages",
     "s_867698fb7b0c730c": "Project name",
     "s_867ea0e1328728d9": "mistake:",
     "s_8696c49ac55b8c71": "Ultra",
+    "s_86a515d230592181": "Scanning creates and configures the bot automatically. Whoever scans becomes the owner.",
     "s_86a63f23a076b11e": "Appearance",
     "s_86a82374a35763d1": "{{p0}} questions pending",
     "s_86a88f06d31bd3b6": "Reading macOS system notification permissions",
@@ -3747,6 +4034,7 @@ export const sourceCatalogs = {
     "s_88d72ece7cf76737": "Search results",
     "s_8905355415cd0bd0": "No selected text to quote",
     "s_89140d4ebd886f12": "Plugin enabled",
+    "s_891836aa11f5c4d9": "Give instructions in a Telegram private chat or by @mentioning the bot in a group. Results come back to the chat.",
     "s_89330587b799cc59": "Download unavailable",
     "s_8949d6721460a7f8": "The model picker in the chat composer uses these profiles.",
     "s_8968ac45a626bd2a": "session menu",
@@ -3758,6 +4046,7 @@ export const sourceCatalogs = {
     "s_8996cf52b5aacf6a": "Archiving failed:",
     "s_89c4766afc85125f": "Connection failed",
     "s_89d3e8892ae8fd51": "More experts",
+    "s_89db648162e7cea1": "Connection lost, retrying automatically…",
     "s_89e0ebd9d750f2c1": "The current backend does not support image generation. Update ACECode, restart, and try again.",
     "s_8a32f1c8f96d5905": "Sandbox backend unavailable: {{p0}}",
     "s_8a687fb42860ccd0": "Reasoning depth: {{p0}}",
@@ -3776,15 +4065,18 @@ export const sourceCatalogs = {
     "s_8b6ff498515bcc2f": "Timing",
     "s_8b7cbd4cede975c1": "Import theme",
     "s_8bcc3e177f5f3b10": "Don't save",
+    "s_8be0ea36a9bba286": "Connecting…",
     "s_8c1ae715559b78bd": "Unable to get upgrade progress",
     "s_8c5c96ae7d403826": "Allowed for the selected directory",
     "s_8c803ec4ccd237fb": "The site cannot respond correctly right now. Try again later.",
     "s_8ca30ef95071173d": "Forking to a new session",
     "s_8cb443ab83797881": "Chart",
     "s_8cb45d256976500e": "silently allow",
+    "s_8cbe697b157364a5": "Approve",
     "s_8cd177ccd9a3ce2a": "File: {{p0}}",
     "s_8ce03a48ca299d89": "Default open target",
     "s_8cf0105d35ee8db8": "think",
+    "s_8d0d535863719b97": "dingtalk stream client id client secret robot im channel messaging connect disconnect",
     "s_8d2773df13e2ebed": "There are no conversations yet in Gonggri",
     "s_8d2c69445d32a5b4": "Currently unavailable",
     "s_8d2e9a70cf226d91": "Search saved models",
@@ -3810,11 +4102,14 @@ export const sourceCatalogs = {
     "s_8e6cd5a3fba2a97c": "Background run setup failed:",
     "s_8e7847be62b68c2b": "Up one level",
     "s_8e7aa97f7fda6bc8": "Could not reset memory",
+    "s_8e86f9b1d54f2c51": "Copy link",
     "s_8e94c67730c3984e": "Not authorized yet",
     "s_8eb6432c43427be3": "Known safe command",
     "s_8ee6730e12551245": "Configuration disk writing failed",
     "s_8effeb945cdcfbd8": "Hook code",
+    "s_8f1094e99bf0e30a": "This bot has a webhook set, so ACECode can't receive messages. After it is removed, ACECode takes over and the service that received the webhook stops getting messages.",
     "s_8f407bb9c116f41d": "interval value",
+    "s_8f43a2aeaac85a91": "Back in the Feishu Open Platform, under Events & Callbacks choose \"Receive events through persistent connection\" and save (saving only works once this connection is up).",
     "s_8f46cb4df9c2e6ca": "Only PNG, JPEG, GIF, WebP, BMP, or ICO is supported",
     "s_8f68def4890f0915": "Recently used expert components",
     "s_8f6f8d979c981ced": "Copied",
@@ -3831,13 +4126,16 @@ export const sourceCatalogs = {
     "s_90ccdf079052559f": "Delete model {{p0}}",
     "s_90dae385f5c1bd68": "The side chat connection was interrupted. Try again.",
     "s_90fd1d973ec921f7": "Computer Use is currently available only on Windows",
+    "s_9118ed423edf0b11": "Copy the Client ID and Client Secret from Credentials & Basic Info and enter them below.",
     "s_912be01af6735ac1": "The default permission mode is set to",
+    "s_913216fda599e7d3": "Expires in {{p0}} min",
     "s_913cd56da217a9a2": "Pointer style",
     "s_9147f07072527b70": "Enable model reasoning",
     "s_914b7a5f9d45d7b9": "The pasted text is uploading; send again when it finishes",
     "s_9154825fa11a80a2": "Reuse the connection’s API URL and key. Choose image models separately below.",
     "s_915b988cbfed5442": "Remote Web mode",
     "s_916a15661d20131c": "Paused goal",
+    "s_916afcd85322d732": "Change",
     "s_917b1c1f18d0276b": "Saving...",
     "s_92172b32227b0aae": "This cannot be undone, and memory summarization will not recreate this memory.",
     "s_926a50b98ece2667": "Cancel",
@@ -3854,6 +4152,7 @@ export const sourceCatalogs = {
     "s_9344597efd4950cc": "Execution failed",
     "s_9344fdfb51e2e192": "Areas of expertise",
     "s_935717bb48835029": "Used while inactive or waiting for the next task",
+    "s_93828ba27fd646b2": "Give instructions in a DingTalk private chat or by @mentioning the bot in a group. Results come back to the chat.",
     "s_93a8734cce300531": "Search models",
     "s_93ac0efe6818ad18": "Citing existing experts, designate a leader; members retain their respective areas of competence.",
     "s_93b93a43e96a3556": "Directory name:",
@@ -3900,6 +4199,7 @@ export const sourceCatalogs = {
     "s_981a6df8cf54be60": "PNG image",
     "s_9833401820de5e2b": "Sign in to managed providers here. Their credentials and endpoints never enter the model dialog.",
     "s_9842842bc84fd474": "Computer Use supports Windows and macOS 14 or later",
+    "s_98532681701285de": "You can now message the bot privately in LINE. Invite it to a group and @mention it there; the first time needs approval in Settings.",
     "s_985511d8c078002c": "Answering…",
     "s_985575198233e251": "Theme export failed",
     "s_986c56322e8bb553": "Choose a close-window action",
@@ -3907,13 +4207,17 @@ export const sourceCatalogs = {
     "s_9884e90a773101b9": "Global memory",
     "s_988c12f1398e3d9d": "Commands run by the AI execute inside an isolated sandbox; file, command and network policies follow the rules below.",
     "s_98cbc356f0e61a08": "Add a provider configuration to manage it here.",
+    "s_98fc221b10e87c21": "Create app",
     "s_991bb7cfe5a81550": "Save changes",
     "s_992b4416c9d23e96": "Reading models…",
     "s_9966d6b375133f89": "Paths must be absolute: {{p0}}",
+    "s_99731fe916c6b3bf": "You can now message the robot privately in DingTalk. Add it to a group and @mention it there; the first time needs approval in Settings.",
+    "s_99845832ed7f16f6": "Later",
     "s_998568217a58f2fc": "No matching global skills",
     "s_999bf43be3657ea3": "Allowed by default in a non-interactive embedding",
     "s_99a4e1e59743908f": "Extensions",
     "s_99aea2f9131ad6da": "Skills",
+    "s_99b8595e331d53a0": "Give instructions in a QQ private chat or by @mentioning the bot in a group. Results come back to the chat.",
     "s_99c32108b160659e": "Choose a complete theme ZIP up to 16 MB",
     "s_9a1537c4f4d32cef": "Unknown command and the sandbox is unavailable",
     "s_9a548610ec6b027f": "Code copied",
@@ -3935,7 +4239,9 @@ export const sourceCatalogs = {
     "s_9d028438fbd04725": "Enter an API URL and key, or choose an available model connection",
     "s_9d0f70c4cee1d679": "Allowed for this session",
     "s_9d1a1b1c006d85f0": "Unsupported file encoding; read-only preview only",
+    "s_9d8692671d208b74": "Group member",
     "s_9d8fb8378821c838": "Cumulative within the last 365 days",
+    "s_9dbb88d5e18dcea1": "Remove webhook and connect",
     "s_9dc0825fba5422e4": "Loading...",
     "s_9dc11d465f7d22c2": "The migration task no longer exists. Start the migration again.",
     "s_9dcb7682ca6c6910": "{{p0}} LSPs",
@@ -3944,6 +4250,7 @@ export const sourceCatalogs = {
     "s_9e3fc11213b90ed0": "Show in explorer",
     "s_9e4a69b0e32825ba": "Select task scope",
     "s_9e66271fb2e5fc90": "Skills and collaboration",
+    "s_9e6c825ec268ab7b": "Paste the token it replies with below.",
     "s_9e73b26eb0a378c9": "Nothing to read",
     "s_9e87fbcaed97c244": "Update cancelled. The current installation was not changed",
     "s_9e928f35eb8008a4": "Could not load the download size. Try again.",
@@ -3966,9 +4273,11 @@ export const sourceCatalogs = {
     "s_9fc9368cc2c409a3": "No plugins configured",
     "s_9fd56f7aae1ca61d": "Show hidden items",
     "s_9fef8ee282a01ab9": "The local model catalog is incomplete. Update ACECode or refresh the catalog.",
+    "s_9ff545329109ea65": "Owner: {{p0}}",
     "s_a00235e8c624f16d": "Extension/expert components",
     "s_a011d73ec679db1a": "Failed to start upgrade:",
     "s_a071de661efe95fb": "Delete this memory?",
+    "s_a0a0e5f6072c8213": "weixin wechat qr ilink bot im channel messaging connect disconnect",
     "s_a0dd1a666530c173": "The default permission mode has been updated and the current session synchronization failed:",
     "s_a0f73bcccc33cb7b": "Closing the preview panel will close all {{p0}} tabs in the current preview area. Continue?",
     "s_a1315bcfc62a19f8": "Native bridge returned invalid results",
@@ -3976,8 +4285,10 @@ export const sourceCatalogs = {
     "s_a153567fbff7a035": "workspace dependencies",
     "s_a184d57717116620": "There is already a bypass question being answered, please wait.",
     "s_a1a9da9ee6ed0401": "unknown reason",
+    "s_a1dfbbbaa9f2fef9": "The bot has a webhook set; action needed",
     "s_a203f86cf6a6a841": "MCP servers",
     "s_a22774c08bc9187e": "Allow writes",
+    "s_a253535fd2df2437": "The first person to message the bot privately in the next 10 minutes becomes the owner. Send it a message from your {{p0}} now.",
     "s_a25f7afbdeabbf5b": "Scale",
     "s_a26e8186b190f6a1": "Added to session",
     "s_a27718d789f9cd53": "Connect {{p0}} first",
@@ -3993,18 +4304,22 @@ export const sourceCatalogs = {
     "s_a3030bf8f16dc63c": "Save",
     "s_a3446a9f995b97ae": "The new path cannot be inside the current workspace",
     "s_a37778f17c5f3ee5": "Cancelled",
+    "s_a379593b5b7590f0": "Scan again",
     "s_a37fe6cce130db08": "Allow multiple instances",
     "s_a383b3a7e26ba13e": "Updates managed by Microsoft Store",
     "s_a398cdc4c87f6bb1": "The current daemon does not support persistent appearance settings",
     "s_a3a33d4898a73327": "Project servers are combined with global servers. Project definitions override matching names.",
+    "s_a3c4db63188defb7": "On the same page, turn on Message Content Intent.",
     "s_a46b5607cf04e274": "Choose a decision",
     "s_a48c70216c141e4a": "What should we do in {{p0}}?",
     "s_a49f5287fc9ef2d0": "Expand directory",
     "s_a4c3313deb180960": "three",
+    "s_a4d14414860b025b": "the bot",
     "s_a4dbd208ac604795": "Migration failed: {{p0}}",
     "s_a4e47879fbd494b2": "Detect models",
     "s_a500bd5efd41f72a": "Current issues",
     "s_a53a4e7bcadab26f": "Cancel goal",
+    "s_a5574109f0208e89": "Connect",
     "s_a55e054ba8777aed": "I understand these memories will be permanently deleted and this cannot be undone",
     "s_a567bdaa11367f26": "Medium",
     "s_a56e7d2220e99dc0": "A running session is using this model",
@@ -4014,6 +4329,7 @@ export const sourceCatalogs = {
     "s_a5c89f1001ff103d": "Task terminated:{{p0}}",
     "s_a60959c3478597ba": "Export PNG image",
     "s_a621d610084a268b": "Windows WebView2 could not start. Restart ACECode and try again.",
+    "s_a627f4f2dbd7c83b": "feishu lark app id app secret persistent connection bot im channel messaging connect disconnect",
     "s_a63280253f17d440": "session",
     "s_a655bcaa91a25426": "Cancel dispatch: {{p0}}",
     "s_a67fa4bcb68094b4": "There are no expert components matching the filter criteria",
@@ -4022,6 +4338,7 @@ export const sourceCatalogs = {
     "s_a6dfb80406396953": "The current platform does not block reads, so this list has no effect (macOS / Linux only)",
     "s_a6e1beaceb5bbafa": "No tasks or projects yet",
     "s_a7310a28aa28faf4": "Failed to cancel update:",
+    "s_a73a5fef875e86b2": "cloudflared was not found. Install it with winget install --id Cloudflare.cloudflared and try again, or go back and enter your own public address.",
     "s_a74010990fc78e7d": "Import locally",
     "s_a76952e53abfc0d9": "Refresh model",
     "s_a77ecf353bbece4f": "Upgrade failed:",
@@ -4046,6 +4363,7 @@ export const sourceCatalogs = {
     "s_a9a52fa6f6089c4d": "Could not save. Reopen this form and try again.",
     "s_a9c7ba0a90821f96": "Disconnect",
     "s_a9f9acf6c0a4da5e": "{{p0}} conversations deleted",
+    "s_a9fe4ee81f686689": "Connection failed. See the log for details",
     "s_aa06c367f0d85408": "Updating",
     "s_aa1b765fb519fa08": "Authentication failed:",
     "s_aa1e899dd35771b0": "Orange",
@@ -4064,6 +4382,7 @@ export const sourceCatalogs = {
     "s_ab48bf2aff24b769": "Timed out while starting or stopping the remote Web proxy",
     "s_ab61b9d1e06f9811": "Create a new terminal (default shell)",
     "s_ab732547ef013de7": "If approved, this command will run inside the sandbox.",
+    "s_ab7a910f5dec5480": "A few more steps",
     "s_ab9084a640fbb864": "Deselect all",
     "s_abb6edd1093c5cf2": "Task terminated",
     "s_abe29e9399d0301c": "Failed to load more",
@@ -4073,6 +4392,7 @@ export const sourceCatalogs = {
     "s_ac3f6e014eef361b": "Toggle developer tools",
     "s_ac4901c4979510a2": "{{p0}} (unavailable)",
     "s_ac6062580b3feb00": "Suggested task",
+    "s_ac7246e3c8488218": "{{p0}} request(s) awaiting approval",
     "s_ac7646d3e0e17e38": "Theme import preview",
     "s_ac77953a1e064ed6": "Sending failed",
     "s_ac8e7ffd9e3458ab": "No sandbox is available; unknown commands require approval",
@@ -4083,6 +4403,7 @@ export const sourceCatalogs = {
     "s_ad24308da105ecab": "Could not reach the Grok model service",
     "s_ad403ac8e643bda1": "Theme deleted; some cached files still need cleanup",
     "s_ad4c46728555aeb6": "Site not found",
+    "s_ad5aaf33d6ce9b8a": "Getting a QR code…",
     "s_ae115efd1b2c2524": "Task aborted",
     "s_ae13d96782b88e57": "Explore the codebase",
     "s_ae30451fc65b75de": "No matching providers",
@@ -4114,6 +4435,7 @@ export const sourceCatalogs = {
     "s_b0e60c5b81438dff": "Lead",
     "s_b0fda488e4430202": "The file is too large to edit in details",
     "s_b135c840f4ab004d": "Please select a workspace first",
+    "s_b1806dfd868502c0": "You can now message the bot privately in QQ. To use it in a group, add the bot and @mention it; the first time needs approval in Settings. A bot without personal verification can only be used by you and can only join groups you own.",
     "s_b193e624476c776d": "Could not get a model reply. Check the settings and retry",
     "s_b19b09a6ed90c4be": "Effective {{p0}} avatar",
     "s_b1a521adee6fcd78": "The side chat response was invalid. Try again.",
@@ -4124,12 +4446,14 @@ export const sourceCatalogs = {
     "s_b2749206c4e01861": "Side chat failed",
     "s_b2888f5f93782bb7": "Failed to load session:",
     "s_b28e2113fe3a14e6": "All time",
+    "s_b28f2b46e181e999": "Open the Discord Developer Portal, create an application, and on the Bot page click Reset Token and copy it.",
     "s_b291a71042529666": "Contains {{p0}} local estimate records, the total may be different from the service provider bill",
     "s_b2d2f7bccbeeffa1": "Confirming…",
     "s_b31640e590dd972a": "There are unsaved changes",
     "s_b33181ed8c62a396": "Delete theme",
     "s_b3594eb35263f1eb": "Annotation {{p0}}, source text changed",
     "s_b387dca9c27793f0": "Could not cancel the export. Try again.",
+    "s_b3bc6035b32575a6": "discord bot token server im channel messaging connect disconnect",
     "s_b3dd7d131a1959f4": "Tell tasks directly in natural language, or enter / view available commands. After sending ACECode will work within the selected range.",
     "s_b40cae1f1f4446f0": "What should happen when you close the window? Exiting the app stops all running tasks and scheduled tasks.",
     "s_b40f2c82dca202be": "The current backend does not isolate the network.",
@@ -4164,6 +4488,7 @@ export const sourceCatalogs = {
     "s_b76fe0327e7aefc8": "Failed to unpin:",
     "s_b79ce792c1a1287a": "Verifying and installing…",
     "s_b7f4557b8b746a5e": "Enter an absolute directory path",
+    "s_b806e39b8e3c4403": "Scan it with your phone's camera (Telegram's own scanner can't read it), then tap Start in Telegram to become the owner.",
     "s_b817c99bb4f24dd5": "Expand list panel",
     "s_b8199c9199128706": "Planning and tasks",
     "s_b858b96d7e9a464e": "Locate in file tree",
@@ -4176,8 +4501,10 @@ export const sourceCatalogs = {
     "s_b91472f6f25b1041": "Enter message or /command…",
     "s_b91b8a344a77fca6": "Directory path is empty",
     "s_b9238eb0c9178901": "The theme action failed. Try again.",
+    "s_b925ae46007cd1f0": "Owner binding QR code",
     "s_b92b399d2820c415": "Clear saved key",
     "s_b92d86f4f5570817": "Close other",
+    "s_b93afa1b4934b706": "Browsing the web",
     "s_b967309734beff88": "Memory summarization",
     "s_b97ad406809572e1": "Enable reasoning",
     "s_b97c0e55e836dee2": "The selected summary model is unavailable. Please select another model",
@@ -4199,6 +4526,7 @@ export const sourceCatalogs = {
     "s_bad0ab59c33beb1d": "Every day {{p0}}",
     "s_baeb44eebe946b43": "Only letters, digits, underscores and hyphens, up to 64 characters",
     "s_bb3e66754a5e03e3": "The Agent requests the following actions:",
+    "s_bb6d995724f49a72": "Manage",
     "s_bb7cc334f9434dab": "After closing, the content and ability selection filled in this time will not be saved.",
     "s_bb7ed30127ddfd49": "The export returned an invalid result. Try again.",
     "s_bb7ef73495dd8a74": "Result",
@@ -4229,10 +4557,12 @@ export const sourceCatalogs = {
     "s_be235f67fed22f01": "Unarchive",
     "s_be385b84994016d0": "The browser component stopped unexpectedly. Try loading this page again.",
     "s_be3e095ce6b95549": "Names starting with ( are reserved by the system",
+    "s_be7bbdf1213e0555": "QQ bot",
     "s_be98c07b13ac0281": "static",
     "s_bee1bfab91f18284": "Auto-approved while unattended",
     "s_bf1617e297b85f92": "Removed from desktop workspace list",
     "s_bf24e735d802644f": "One per line; shown in cards and details",
+    "s_bf2a78216b764bb1": "qq bot qr appid appsecret im channel messaging connect disconnect owner approve revoke",
     "s_bf39e015be237ba0": "The project was created, but incomplete workspace information was returned",
     "s_bf3a8846479b7fb7": "Type or paste an absolute path, then press Enter",
     "s_bf3e55705e1de1e8": "Failed to update task completion notifications:",
@@ -4252,7 +4582,9 @@ export const sourceCatalogs = {
     "s_c02c246a6d181676": "Could not read the pasted text",
     "s_c02fdcf208b3e472": "Delete rule",
     "s_c03b9deb55408bc4": "Page process stopped",
+    "s_c043eb82f9332c31": "Opening the connection…",
     "s_c044ecbe7fe9c678": "Theme-colored arrow only",
+    "s_c051216ed509001e": "In Telegram, search for @BotFather (look for the blue verified badge) and send /newbot.",
     "s_c05f7cd6ed3587a2": "Plane",
     "s_c0866a5a020be7a3": "Delete conversation completely",
     "s_c087c3d4b210ee82": "Theme deletion returned an invalid result. Refresh and try again.",
@@ -4271,6 +4603,7 @@ export const sourceCatalogs = {
     "s_c27916570d04cf33": "The current workspace is not registered with the background service",
     "s_c2a497830ef74215": "latest version",
     "s_c2b732b196ccc7f3": "Conversation has been completely deleted",
+    "s_c2b794434132af6e": "Get a new QR code",
     "s_c2e410cd40759fb5": "Describe a task to ACECode, or type / for commands…",
     "s_c2f0625f0f3d2c18": "Expand tool details",
     "s_c304f59bf05cfa14": "Desktop startup",
@@ -4281,8 +4614,10 @@ export const sourceCatalogs = {
     "s_c39d1e51a3941a89": "Saving theme package…",
     "s_c3a73c5eecea42a3": "Expert",
     "s_c3b8f744ed2c55bf": "JSON format error:",
+    "s_c3e1b26c451e8221": "Add the event \"Message received v2.0\" (im.message.receive_v1).",
     "s_c3e5589604083870": "No plugins",
     "s_c3f989b790daab98": "The backend is temporarily unavailable. Try again later.",
+    "s_c43f153cb1be5ca5": "Waiting for members",
     "s_c4ae8fa5a16b5a75": "Skip all tool permission confirmations",
     "s_c4c5b649cbf25fbb": "Memory and context",
     "s_c52c7fbed621e8ff": "Annotation {{p0}}",
@@ -4343,12 +4678,14 @@ export const sourceCatalogs = {
     "s_ca6343cddb75f289": "Could not generate a test image. Check the connection and model name.",
     "s_ca66c2da6f5bf825": "learn more",
     "s_ca74d439e7712aa5": "The daemon is not running, it has been missed and will not be rerun.",
+    "s_ca78ab9bac8e9f5b": "Find the bot in Feishu and send it the 6-digit code below in a private chat.",
     "s_ca949d1eb3377a79": "ACE badge",
     "s_cadd75ef8275de01": "Viewed {{p0}} images",
     "s_caecb5d342cc889a": "Resume goal",
     "s_cafc8a4f6acda2cb": "Tags can be selected multiple times; the same expert will appear under each selected Tag",
     "s_cb2fcb9099668d50": "No answer yet",
     "s_cb31eb7a0c2aa250": "Edit model · {{p0}}",
+    "s_cb51a062db592988": "Another ACECode is connected to this bot. This one takes over automatically after it exits.",
     "s_cb5d682bac3d1a2d": "Reset",
     "s_cb62ebd689ee8f20": "current",
     "s_cb65690b6ee3a1d4": "Unable to get GitHub verification code",
@@ -4356,13 +4693,17 @@ export const sourceCatalogs = {
     "s_cbb5a32c96c3cdee": "Add selected model",
     "s_cbd7dc0ea6976fd0": "When closing the window",
     "s_cc0477362c195cf3": "No reusable OpenAI-compatible connections. Choose Configure separately.",
+    "s_cc574bc5da5d9ac3": "The code is valid for 10 minutes and works once. This step completes by itself after you send it.",
     "s_cc66c3f576fd5a49": "Full access",
     "s_cc91b14c8a02a155": "Set {{p0}} as the default model",
     "s_cce894450069ba5b": "unknown source",
     "s_cd0832ff9b505231": "Theme package sent to browser downloads",
+    "s_cd0ce16ee4fd90de": "Copy failed. Select the text and copy it manually",
+    "s_cd1db6a7d69cb947": "Use ACECode remotely from QQ, WeChat, Feishu, DingTalk, Telegram, Discord and LINE. Credentials stay on this computer. Whether channels stay online after Desktop closes depends on \"Continue running the background process after exiting ACECode\" in Settings > General.",
     "s_cd32a8c1d823d060": "{{p0}} · Source text changed",
     "s_cd3b78eb00f7cd12": "Configured hooks will appear here",
     "s_cd62bee012d94183": "The page component stopped unexpectedly. Reload it.",
+    "s_cd68324b409f9962": "LINE can only deliver messages to a public address. If you leave the public address empty, ACECode opens a temporary cloudflared tunnel (install it first: winget install --id Cloudflare.cloudflared) and updates LINE's webhook URL on every connect.",
     "s_cd7395dfd00b67f2": "Only allow writes to {{p0}}",
     "s_cda33af428d74680": "Matched a sandboxed allow rule",
     "s_cdae8daae433af05": "Native selector is not available",
@@ -4385,8 +4726,10 @@ export const sourceCatalogs = {
     "s_cf479a0f90887a09": "Could not load theme information. Check your connection and try again.",
     "s_cf4880f621b9d7bd": "my expert",
     "s_cf4b1ead545e9bfc": "Wildcards are only allowed in the deny list: {{p0}}",
+    "s_cf5c7eb43df2410f": "A group",
     "s_cf6506cb7fc47b9c": "Pasted text · Waiting to upload",
     "s_cf6783b5388c5684": "Allow (inside sandbox)",
+    "s_cf8ab6767bf0526f": "The QR code expired and was replaced. Scan the new one",
     "s_cf911266fb127d62": "Expand sidebar",
     "s_cf9430e214bde1a8": "A worktree cannot be created from this directory",
     "s_cfbb88c4ba804b90": "Dumbbell",
@@ -4397,6 +4740,7 @@ export const sourceCatalogs = {
     "s_d04fcbda737fc0c6": "Loading",
     "s_d059018d896d6cde": "Delete the {{p0}} line",
     "s_d06e875dde456038": "No blocked paths yet",
+    "s_d0916de8c1b603bd": "Approved {{p0}}",
     "s_d0ca08d604551151": "Queue paused",
     "s_d0f680208ed8796c": "git times out, click to try again",
     "s_d0fb5bbca8184bdd": "Jump to current question:{{p0}}",
@@ -4416,6 +4760,8 @@ export const sourceCatalogs = {
     "s_d2fc539871184000": "Interjection submitted; interrupting the active turn",
     "s_d3136b6fa93050df": "From {{p0}} session(s)",
     "s_d31c72ba37a59575": "No archived conversations yet",
+    "s_d321ee860efcbb5d": "Use the saved bot, or switch to another one.",
+    "s_d33995ad669c80cf": "Create channel",
     "s_d33e249955c846e3": "Stopping the update safely. Please wait.",
     "s_d35ab580f555345e": "Could not send the stop request. Try again after reconnecting",
     "s_d381ac2d678d3f8e": "What to do when the close button in the top-right corner is clicked",
@@ -4439,6 +4785,7 @@ export const sourceCatalogs = {
     "s_d538a7ab8d9826bb": "Failed to start import",
     "s_d53d32f1a1211371": "Custom request headers JSON",
     "s_d57bc0acdb5f23ab": "Loading diff failed",
+    "s_d593d21fca298b8f": "WeChat bot",
     "s_d5d126f6c79d9b11": "All workspaces",
     "s_d5d360963aa38a66": "Failed to open session:",
     "s_d5e75e3452a056c7": "Failed to submit interjection:",
@@ -4456,6 +4803,7 @@ export const sourceCatalogs = {
     "s_d69766c856685234": "Beginner's Guide",
     "s_d6cd7e5f2a8a82cf": "This memory no longer exists. Refresh the list.",
     "s_d6d20f05ed0f96e0": "Single execution time",
+    "s_d6e882143a3c3b83": "Scan to create bot",
     "s_d6f766f2adf53227": "Queuing",
     "s_d6feded758aed3eb": "Cancel update",
     "s_d73e140df277dffe": "Model updated",
@@ -4463,6 +4811,7 @@ export const sourceCatalogs = {
     "s_d74679ad02055214": "Hook operation failed:",
     "s_d74f204139fdd6ab": "Search for expert names, tags or areas of expertise",
     "s_d7503697e8e7850b": "Retry workshop",
+    "s_d750c976bfff1be2": "Open Feishu Open Platform",
     "s_d77674f90811d7af": "Configuration scope",
     "s_d7875850553752e5": "Failed to switch expert: {{p0}}",
     "s_d7b2165028a50b95": "Automatically edit and run sandboxed commands; confirm dangerous operations and requests outside the sandbox",
@@ -4483,6 +4832,7 @@ export const sourceCatalogs = {
     "s_d94f9bafff59c06b": "Hooks enabled",
     "s_d954c8e3f3042985": "Dangerous command",
     "s_d9686d510cd34aff": "Notifications will enter the notification center silently",
+    "s_d9894ab44928d667": "Follow the prompts to name it. The username must end in bot.",
     "s_d9b7af1d4322eb34": "Collapse all diff",
     "s_d9c35f6c3c4deeaa": "(empty directory)",
     "s_d9f02c7caa8a847d": "Failed to save custom directive:",
@@ -4509,9 +4859,11 @@ export const sourceCatalogs = {
     "s_db8630211fe3934a": "Native settings are not available",
     "s_db95142124934467": "Music",
     "s_dbaa6ba5056580a7": "Outside the currently selectable expert set",
+    "s_dbcac8ae7d65ae39": "The QR code expired",
     "s_dbcb25260e3df31a": "A decision record for every command run, file change, sandbox block and rule change; the newest {{p0}} entries are kept.",
     "s_dbd379b39f0d3537": "Pink",
     "s_dc2ba467fc7ac962": "Description",
+    "s_dc3cabe68bcc3046": "Open the DingTalk Open Platform, create an internal app, and add the Robot capability.",
     "s_dc47f62bd3f882f0": "Build expert team",
     "s_dc4d662d071eea52": "Created",
     "s_dc55764fa54e2a48": "MCP configuration scope",
@@ -4527,6 +4879,7 @@ export const sourceCatalogs = {
     "s_dd42f689b17393c2": "Loading earlier messages…",
     "s_dd7a9008edbca109": "Unarchived {{p0}} sessions; {{p1}} failed",
     "s_dda206707b809157": "Connection interrupted",
+    "s_ddcf6e77b0ee1000": "Preparing to",
     "s_ddde08946298195d": "reduction",
     "s_ddfe2c796c7eb71b": "Add manually",
     "s_de03ee139fe2fd9f": "Found",
@@ -4538,6 +4891,7 @@ export const sourceCatalogs = {
     "s_de32e20193ad1042": "Got it",
     "s_de8184da1ef88d03": "Configured",
     "s_deb6051740064edd": "Use memory",
+    "s_dec96df98f052d22": "Open LINE Developers",
     "s_deeceedbed503b78": "Daily code health inspection",
     "s_df359a6a54eab051": "Manage lifecycle hooks via configuration and enabled plugins.",
     "s_df3d58c7d84b85f2": "Settings",
@@ -4553,13 +4907,17 @@ export const sourceCatalogs = {
     "s_e058a2b5c4f81526": "View full text",
     "s_e05f7e88f89c5f88": ". The theme will be applied after download.",
     "s_e07802f10db9b6b8": "Find the right expert for your current job",
+    "s_e0959e358684c224": "{{p0}} (leave empty to keep)",
     "s_e09b1c37f79f440d": "Allow (outside sandbox)",
     "s_e0b05fd1040bf6ce": "Could not delete the theme. Try again.",
     "s_e0b1051909eb179e": "Tasks and workspaces",
     "s_e0b6ce5e09cd4386": "Server configuration",
     "s_e0c8243464aa770c": "0 /{{p0}} steps",
     "s_e0d995508b32cdbb": "{{p0}}% used",
+    "s_e0e9b9269cbd7678": "Open the Discord Developer Portal",
     "s_e0ec651f0dae7cf3": "Quote",
+    "s_e0f62acd5d3cebdd": "Channel data error. See the log for details",
+    "s_e0fecdf371158416": "QR setup canceled. The existing configuration is unchanged",
     "s_e122303044304acc": "Save with this name",
     "s_e17df82098f51602": "Added console logs to chat",
     "s_e19c3b9e266c69c9": "Browser",
@@ -4574,6 +4932,7 @@ export const sourceCatalogs = {
     "s_e246195c1a39636e": "next round",
     "s_e2469247115761e9": "Default quality",
     "s_e26740162fbcb387": "Interject queued message into the active turn",
+    "s_e2780ee23078ea51": "{{p0}}{{p1}} wants to use ACECode. Review it in Settings > Messaging channels",
     "s_e2a76ef1f12e147f": "Terminal",
     "s_e2f12da7faa68217": "Downloaded",
     "s_e2fda204edef967e": "JSON must be an object",
@@ -4629,12 +4988,14 @@ export const sourceCatalogs = {
     "s_e806fbbe8ec6e82d": "Plugins",
     "s_e833097b603cb745": "{{p0}} contexts",
     "s_e84e54a6b6dbbbb9": "Reads and writes are denied for: {{p0}}",
+    "s_e8ac23cf743aa1f8": "Or approve a private chat request. The first person approved becomes the owner",
     "s_e8dc871a7fdee23b": "total",
     "s_e8e08b0f61dd4ddb": "Cancelling…",
     "s_e90589613fe54246": "Show hidden",
     "s_e948d90880bb3dba": "JSON is invalid and cannot be switched",
     "s_e951cbd07b5633c1": "Remove local project",
     "s_e95f2ba203c9af41": "Wait for running tasks to finish before migrating.",
+    "s_e99a6717b6917534": "Fix",
     "s_e99b5859dcf96dc4": "Scroll up to see older questions",
     "s_e9a1310b7638d211": "Next round dispatch {{p0}}:{{p1}}",
     "s_e9b00d7f92151b2d": "Dispatch {{p0}}",
@@ -4658,16 +5019,19 @@ export const sourceCatalogs = {
     "s_eb4c406398df4d73": "No workspace usage yet",
     "s_eb557068ab4833dd": "Unable to connect to Copilot model service",
     "s_eb55f0980fa90bac": "waiting for your answer",
+    "s_eb92486a46895884": "You can now DM the bot or @mention it in a server channel. Using it in a channel the first time needs approval in Settings.",
     "s_eb93045599c0e25c": "Enter Plan mode",
     "s_ebb240a1930e8bfb": "Search icons",
     "s_ebb63196c7d3c318": "Failed to copy image:",
     "s_ec7a11c7061bc164": "Migrating workspace…",
     "s_ec869826ec67f839": "Some Agent Browser data could not be copied. You may need to sign in again after restarting.",
     "s_ec9bbc8139d8bdd1": "Specialize",
+    "s_ecdf5ea03d83b916": "line messaging api channel secret webhook cloudflared bot im channel messaging connect disconnect",
     "s_ece45f7651c8c206": "The Agent Browser Desktop bridge is unavailable",
     "s_ed100f18801746c9": "Command rules saved",
     "s_ed147f03761ab80e": "Add element to chat",
     "s_ed150cce119ea114": "Git Bash path memorized",
+    "s_ed16bd1db4b68498": "Waiting for an answer",
     "s_ed1790d489e671a9": "Inherit global ACECode local tools",
     "s_ed21620162d871e5": "Loading session records…",
     "s_ed2f18de3cdc1c5f": "About ACECode",
@@ -4676,12 +5040,15 @@ export const sourceCatalogs = {
     "s_eda73a5daf8f734f": "Current issue:{{p0}}",
     "s_edb18f09d0ff4c83": "Edit model {{p0}}",
     "s_edbd4f79f1b7919a": "... +{{p0}} lines collapsed",
+    "s_ede83cc65dad0522": "Use the saved bot, or scan again to switch to another one.",
     "s_edecf0ae6e5144f9": "send",
     "s_ee00e57c07195431": "The current running mode does not support automatic restart. Please exit completely and then restart ACECode.",
     "s_ee1db622be4f2443": "Close {{p0}}",
+    "s_ee1e5738be96819a": "Connected {{p0}}",
     "s_ee32f25f70508f9c": "Clear search",
     "s_ee34c74d32e7548a": "Recently created",
     "s_ee529160390df1c4": "Endpoint mode",
+    "s_ee9ebe523d4205f8": "Connecting…",
     "s_eea1694c235b5ddf": "every day",
     "s_eeccc53745f048de": "View {{p0}}\"{{p1}}\"",
     "s_eeef861b87676f3f": "Globe",
@@ -4702,12 +5069,14 @@ export const sourceCatalogs = {
     "s_f00ef1be4493739b": "Ask every time",
     "s_f0352e9758fbff2d": "Command forbidden",
     "s_f035aab05364d2c5": "Select \"{{p0}}\"",
+    "s_f03b1d0aa80f24ea": "Give instructions in a LINE private chat or by @mentioning the bot in a group. Results come back to the chat.",
     "s_f04360cb3c9187dc": "{{p0}} file(s) have unsaved changes. Save before continuing?",
     "s_f07ba1ef037a8e44": "Existing scheduled task",
     "s_f07bda17207c1e3e": "Read-only file system",
     "s_f0935665814a3f25": "Failed to copy connection: {{p0}}",
     "s_f098218a3032a625": "Rejected",
     "s_f09e3585d4a4e27e": "Model connections",
+    "s_f0b4569c602a10a0": "Use the saved bot",
     "s_f121ab742cefcb8e": "Needs attention",
     "s_f1929d7304960203": "Hook disabled",
     "s_f1aa0173729f7228": "Remove reference context",
@@ -4715,6 +5084,7 @@ export const sourceCatalogs = {
     "s_f1b112d6acd841b1": "Graduation cap",
     "s_f1bdeeb9fb4cab81": "Theme verification failed; the theme cannot be exported",
     "s_f1e0dfb858e7fcfe": "Denied by hook",
+    "s_f21f25112af89630": "The webhook URL is registered. Turn on Use webhook on the Messaging API page of the LINE Developers console; this changes to connected automatically once it is on.",
     "s_f27627514a2cb542": "Expert component failed to load",
     "s_f28461bb49c85647": "Completed",
     "s_f2902ada282332d2": "Unknown command, ran inside the sandbox",
@@ -4722,9 +5092,11 @@ export const sourceCatalogs = {
     "s_f2b4237b35f0b3b2": "View session",
     "s_f2bdc88464c51c2e": "Show API key",
     "s_f2d964d3dc5862d1": "time out:",
+    "s_f2df9f7ce435d9d6": "The channel data file has a problem. See the log for details.",
     "s_f2f491398295b1b9": "Lotus",
     "s_f323fc507d585565": "Minimize to tray",
     "s_f335420fcda22e54": "This file format does not currently support preview",
+    "s_f33c31866a8c335e": "Declined {{p0}}",
     "s_f36f1a90b64f69e5": "Node.js Tools",
     "s_f37b8e7538b116da": "Expand {{p0}}",
     "s_f39f410e0b493a67": "skip guide",
@@ -4766,6 +5138,7 @@ export const sourceCatalogs = {
     "s_f628f6c3e43734b2": "Clear filters to view all available components.",
     "s_f69273dbbebfb3a1": "format",
     "s_f699d16db6c37a35": "This platform cannot fully cut the network: turning network access off only injects an offline environment (proxy pointed at a dead port, ssh stubs); programs that ignore the proxy can still connect.",
+    "s_f6dba35520d09e76": "telegram bot token botfather owner im channel messaging connect disconnect approve revoke",
     "s_f6dc1b1641600dd0": "Importing…",
     "s_f70f928df89406a7": "Upgrade now",
     "s_f72684a97677d48a": "Conversation Question Track",
@@ -4781,6 +5154,7 @@ export const sourceCatalogs = {
     "s_f8209b2310bc54a8": "Open context menu",
     "s_f82c68c72b8f9aca": "Next question",
     "s_f84c7d6122a7753f": "Usage record",
+    "s_f8567a884d2336b5": "Revoke access for {{p0}}?",
     "s_f896a064e0be9e4e": "Parse failed, the whole file is ignored: {{p0}}",
     "s_f8b6ebf2a9e19bbd": "Image copied",
     "s_f8c104adf2f77e87": "Please fill in the name of the expert",
@@ -4844,6 +5218,7 @@ export const sourceCatalogs = {
     "s_fcea4baf388f169a": "Run core tests to locate and fix reliably reproducible issues.",
     "s_fcf8b4bff0df782d": "Open folder",
     "s_fcffc107c99acbba": "Registered workspaces",
+    "s_fd351bc95e9337e4": "Sending a message",
     "s_fd4b9e3b6c685bae": "Continue editing",
     "s_fd5fd3c4567938c7": "Ask",
     "s_fd6529f1e944f8c7": "Share files with this conversation. The task will queue while other work is running.",
@@ -4864,6 +5239,7 @@ export const sourceCatalogs = {
     "s_ff199a8f48c79fd8": "Audit log exported",
     "s_ff20131bcd4725f2": "No rules yet. Choosing \"Always allow\" in a confirmation dialog also writes here automatically.",
     "s_ff509c9ba052a21c": "Saving…",
+    "s_ff62ea25d5d6b3a6": "Stopping a member",
     "s_ff63d45ac706d173": "Continue in a new conversation",
     "s_ff857f2b6ac947ac": "Last consolidation",
     "s_ff8b0d734b03b1a4": "Custom models",
diff --git a/web/src/lib/api.js b/web/src/lib/api.js
index a25f97521..a01ada64f 100644
--- a/web/src/lib/api.js
+++ b/web/src/lib/api.js
@@ -616,6 +616,10 @@ export function createApi(base = null) {
       );
     },
     refreshModelCatalog: ()          => request('POST',   '/api/models/catalog/refresh', {}, base),
+    getDesktopOffice: ({sessionId = '', workspaceHash = ''} = {}, {signal} = {}) => {
+      const query = new URLSearchParams({session: sessionId, workspace: workspaceHash});
+      return request('GET', `/api/desktop-office?${query}`, undefined, base, {signal});
+    },
     getSessionModel:  (sid, workspaceHash = '') => {
       const qs = workspaceHash ? `?workspace=${encodeURIComponent(workspaceHash)}` : '';
       return request('GET', `/api/sessions/${encodeURIComponent(sid)}/model${qs}`, undefined, base);
@@ -709,6 +713,27 @@ export function createApi(base = null) {
     exportAudit: (query = '')        => request('GET', '/api/security/audit/export' + query, undefined, base),
     clearAudit: ()                   => request('DELETE', '/api/security/audit', undefined, base),
     setConnectors: (cfg)             => request('PUT',    '/api/config/connectors', cfg, base),
+    // 消息通道(Settings > 集成 > 消息通道,openspec add-desktop-im-channels)。只接受本机直连。
+    getChannels: ()                  => request('GET', '/api/channels', undefined, base),
+    setChannelEnabled: (platform, enabled) =>
+      request('POST', `/api/channels/${encodeURIComponent(platform)}/enabled`, { enabled }, base),
+    // 保存前联网校验(QQ 换取令牌 / Telegram getMe),给足时间。
+    setChannelCredentials: (platform, credentials) =>
+      request('PUT', `/api/channels/${encodeURIComponent(platform)}/credentials`, credentials, base,
+        { timeoutMs: 45000 }),
+    startChannelBind: (platform)     =>
+      request('POST', `/api/channels/${encodeURIComponent(platform)}/bind`, {}, base),
+    cancelChannelBind: (platform)    =>
+      request('DELETE', `/api/channels/${encodeURIComponent(platform)}/bind`, undefined, base),
+    createChannelOwnerLink: (platform) =>
+      request('POST', `/api/channels/${encodeURIComponent(platform)}/owner-link`, {}, base),
+    removeTelegramWebhook: ()        => request('POST', '/api/channels/telegram/remove-webhook', {}, base),
+    decideChannelRequest: (platform, id, approve) =>
+      request('POST', `/api/channels/${encodeURIComponent(platform)}/requests/${encodeURIComponent(id)}/`
+        + (approve ? 'approve' : 'reject'), {}, base),
+    revokeChannelAccess: (platform, principal) =>
+      request('DELETE', `/api/channels/${encodeURIComponent(platform)}/access/${encodeURIComponent(principal)}`,
+        undefined, base),
     getUpgradeConfig: ()             => request('GET',    '/api/config/upgrade', undefined, base),
     setUpgradeConfig: (cfg)          => request('PUT',    '/api/config/upgrade', cfg, base),
     getToolchainConfig: () => request('GET', '/api/config/toolchains', undefined, base),
diff --git a/web/src/lib/archivedSessions.js b/web/src/lib/archivedSessions.js
index 76db4121b..3e067a896 100644
--- a/web/src/lib/archivedSessions.js
+++ b/web/src/lib/archivedSessions.js
@@ -24,6 +24,7 @@ export function groupArchivedSessions(items, {
   query = '',
   workspaceKey = '',
   sortOrder = 'newest',
+  workspaceOrder = [],
 } = {}) {
   const search = String(query).trim().toLowerCase();
   const rows = (Array.isArray(items) ? items : [])
@@ -34,19 +35,29 @@ export function groupArchivedSessions(items, {
       return [sessionDisplayTitle(item, item?.name || ''), workspace.name, workspace.path]
         .some((value) => value.toLowerCase().includes(search));
     });
-  rows.sort((a, b) => {
-    if (a.time === null) return b.time === null ? 0 : 1;
-    if (b.time === null) return -1;
-    return sortOrder === 'oldest' ? a.time - b.time : b.time - a.time;
-  });
   const groups = new Map();
-  for (const { item, workspace } of rows) {
+  for (const row of rows) {
+    const { workspace } = row;
     if (!groups.has(workspace.key)) {
       groups.set(workspace.key, { ...workspace, items: [] });
     }
-    groups.get(workspace.key).items.push(item);
+    groups.get(workspace.key).items.push(row);
   }
-  return [...groups.values()];
+  const order = Array.isArray(workspaceOrder) ? workspaceOrder : [];
+  const ranks = new Map(order.map((key, index) => [key, index]));
+  // The sidebar places no-workspace tasks before workspace folders.
+  ranks.set('__no_workspace__', -1);
+  return [...groups.values()]
+    .sort((a, b) => (ranks.get(a.key) ?? order.length) - (ranks.get(b.key) ?? order.length)
+      || a.key.localeCompare(b.key))
+    .map((group) => ({
+      ...group,
+      items: group.items.sort((a, b) => {
+        if (a.time === null) return b.time === null ? 0 : 1;
+        if (b.time === null) return -1;
+        return sortOrder === 'oldest' ? a.time - b.time : b.time - a.time;
+      }).map(({ item }) => item),
+    }));
 }
 
 export function archivedSessionTarget(item = {}) {
diff --git a/web/src/lib/archivedSessions.test.js b/web/src/lib/archivedSessions.test.js
index c15ff00d9..d169391a4 100644
--- a/web/src/lib/archivedSessions.test.js
+++ b/web/src/lib/archivedSessions.test.js
@@ -110,12 +110,12 @@ const archive = [
 
 test('archive groups keep same-name workspaces and no-workspace tasks separate', () => {
   const groups = groupArchivedSessions(archive);
-  assert.deepEqual(groups.map(({ key }) => key), ['two', 'one', '__no_workspace__']);
+  assert.deepEqual(groups.map(({ key }) => key), ['__no_workspace__', 'one', 'two']);
   assert.deepEqual(groups[1].items.map(({ id }) => id), ['middle', 'same']);
   assert.deepEqual(groups.map(({ items }) => items.length), [1, 2, 1]);
-  assert.equal(groups[0].name, groups[1].name);
-  assert.notEqual(groups[0].path, groups[1].path);
-  assert.equal(groups[2].name, '无工作区');
+  assert.equal(groups[1].name, groups[2].name);
+  assert.notEqual(groups[1].path, groups[2].path);
+  assert.equal(groups[0].name, '无工作区');
 });
 
 test('archive workspace labels support paths, legacy local rows, and explicit no-workspace flags', () => {
@@ -127,7 +127,7 @@ test('archive workspace labels support paths, legacy local rows, and explicit no
     key: '__no_workspace__', name: '无工作区', path: '',
   });
   assert.deepEqual(groupArchivedSessions([{ id: 'local' }, { id: 'task', no_workspace: true }])
-    .map(({ key }) => key), ['__local__', '__no_workspace__']);
+    .map(({ key }) => key), ['__no_workspace__', '__local__']);
 });
 
 test('archive search combines trimmed case-insensitive titles, workspace names, paths, and workspace filter', () => {
@@ -155,13 +155,51 @@ test('archive sorting uses creation fallback, keeps undated rows last, and leave
   ]);
   const newest = groupArchivedSessions(items);
   const oldest = groupArchivedSessions(items, { sortOrder: 'oldest' });
-  assert.deepEqual(newest.map(({ key }) => key), ['two', 'one', '__no_workspace__']);
-  assert.deepEqual(oldest.map(({ key }) => key), ['one', '__no_workspace__', 'two']);
+  assert.deepEqual(newest.map(({ key }) => key), ['__no_workspace__', 'one', 'two']);
+  assert.deepEqual(oldest.map(({ key }) => key), ['__no_workspace__', 'one', 'two']);
   assert.deepEqual(newest[1].items.map(({ id }) => id), ['middle', 'fallback', 'same', 'unknown']);
-  assert.deepEqual(oldest[0].items.map(({ id }) => id), ['same', 'fallback', 'middle', 'unknown']);
+  assert.deepEqual(oldest[1].items.map(({ id }) => id), ['same', 'fallback', 'middle', 'unknown']);
   assert.equal(items[0].id, 'unknown');
 });
 
+test('sidebar workspace order is independent of session times and sort direction', () => {
+  for (const workspaceOrder of [Object.freeze(['one', 'two']), Object.freeze(['two', 'one'])]) {
+    for (const sortOrder of ['newest', 'oldest']) {
+      const groups = groupArchivedSessions([...archive].reverse(), { workspaceOrder, sortOrder });
+      assert.deepEqual(groups.map(({ key }) => key), ['__no_workspace__', ...workspaceOrder]);
+      assert.deepEqual(groups.find(({ key }) => key === 'one').items.map(({ id }) => id),
+        sortOrder === 'oldest' ? ['same', 'middle'] : ['middle', 'same']);
+    }
+  }
+});
+
+test('search and archive removal preserve workspace order without empty groups', () => {
+  const options = { workspaceOrder: ['two', 'empty', 'one'] };
+  assert.deepEqual(groupArchivedSessions(archive, { ...options, query: 'draft', sortOrder: 'oldest' })
+    .map(({ key }) => key), ['__no_workspace__', 'two', 'one']);
+  assert.deepEqual(groupArchivedSessions(archive, { ...options, query: 'project' })
+    .map(({ key }) => key), ['two', 'one']);
+  const remaining = removeArchivedSessionsByKey(archive, [archivedSessionKey(archive[2])]);
+  assert.deepEqual(groupArchivedSessions(remaining, options).map(({ key }) => key),
+    ['__no_workspace__', 'two', 'one']);
+  assert.deepEqual(groupArchivedSessions(remaining, { ...options, workspaceKey: 'one' })[0].items,
+    [archive[0]]);
+  assert.deepEqual(groupArchivedSessions(remaining, { ...options, workspaceKey: 'empty' }), []);
+});
+
+test('unlisted and local archive groups have stable order after listed workspaces', () => {
+  const items = [{ id: 'local', updated_at: '2030-01-01' }, ...archive];
+  for (const sortOrder of ['newest', 'oldest']) {
+    assert.deepEqual(groupArchivedSessions(items, { workspaceOrder: ['two'], sortOrder })
+      .map(({ key }) => key), ['__no_workspace__', 'two', '__local__', 'one']);
+    const reversed = [...items].reverse();
+    assert.deepEqual(groupArchivedSessions(reversed, { workspaceOrder: ['two'], sortOrder })
+      .map(({ key }) => key), ['__no_workspace__', 'two', '__local__', 'one']);
+    assert.deepEqual(groupArchivedSessions(reversed, { workspaceOrder: null, sortOrder })
+      .map(({ key }) => key), ['__no_workspace__', '__local__', 'one', 'two']);
+  }
+});
+
 test('filtered selection excludes hidden sessions and preserves visible selection through sorting and failures', () => {
   const selected = toggleAllArchivedSessionSelection(archive, new Set());
   const filtered = groupArchivedSessions(archive, { workspaceKey: 'one' }).flatMap(({ items }) => items);
diff --git a/web/src/lib/channelsSettings.js b/web/src/lib/channelsSettings.js
new file mode 100644
index 000000000..c8b261682
--- /dev/null
+++ b/web/src/lib/channelsSettings.js
@@ -0,0 +1,673 @@
+// 消息通道设置页(设置 > 集成 > 消息通道,openspec add-desktop-im-channels)的纯逻辑:
+// 快照规整、卡片(连接 / 取消连接 + 一行简要状态)、分步连接向导各步的视图、扫码流程视图、
+// WS 事件合并、二维码路径、会话列表的 channel_bound 判定。组件 components/ChannelsSettings.jsx
+// 只负责渲染与请求。页面刻意只给简要状态:原因、隐私模式、暂存待补发、收发计数等细节由 daemon
+// 写进日志(src/host/channels/core/state_log.cpp),不要再加回页面。
+import qrcode from 'qrcode-generator';
+
+// 与 daemon 的平台描述表(src/host/channels/core/platforms.cpp)同序。
+export const CHANNEL_PLATFORMS = ['qq', 'weixin', 'feishu', 'dingtalk', 'telegram', 'discord', 'line'];
+
+// 有扫码绑定流程的平台。
+export const SCAN_PLATFORMS = ['qq', 'weixin'];
+
+function text(value) {
+  return value == null ? '' : String(value);
+}
+
+function object(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function array(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function count(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+}
+
+// 平台短名(侧栏提示“已绑定到 …”、请求通知用)。写成函数:文案在调用时求值,跟随界面语言。
+export function channelPlatformTitle(platform) {
+  switch (platform) {
+    case 'qq': return 'QQ';
+    case 'weixin': return '微信';
+    case 'feishu': return '飞书';
+    case 'dingtalk': return '钉钉';
+    case 'telegram': return 'Telegram';
+    case 'discord': return 'Discord';
+    case 'line': return 'LINE';
+    default: return text(platform);
+  }
+}
+
+export function isChannelPlatform(platform) {
+  return CHANNEL_PLATFORMS.includes(platform);
+}
+
+export function emptyChannelPlatform(platform) {
+  return {
+    platform,
+    configured: false,
+    enabled: false,
+    state: 'unconfigured',
+    detail: '',
+    retryStopped: false,
+    account: '',
+    displayName: '',
+    extra: {},
+    credentialHint: '',
+    credentialsPublic: {},
+    appId: '',
+    owner: '',
+    ownerWindow: false,
+    hostedByPid: 0,
+    contacts: [],
+    pending: [],
+    bindings: [],
+  };
+}
+
+export function normalizeChannelPlatform(raw) {
+  const source = object(raw);
+  const platform = text(source.platform);
+  const base = emptyChannelPlatform(platform);
+  return {
+    ...base,
+    configured: source.configured === true,
+    enabled: source.enabled === true,
+    state: text(source.state) || base.state,
+    detail: text(source.detail),
+    retryStopped: source.retry_stopped === true,
+    account: text(source.account),
+    displayName: text(source.display_name),
+    extra: object(source.extra),
+    credentialHint: text(source.credential_hint),
+    credentialsPublic: object(source.credentials_public),
+    appId: text(source.app_id),
+    owner: text(source.owner),
+    ownerWindow: source.owner_window === true,
+    hostedByPid: count(source.hosted_by_pid),
+    contacts: array(source.contacts).map((item) => {
+      const contact = object(item);
+      return {
+        principal: text(contact.principal),
+        kind: text(contact.kind),
+        name: text(contact.name),
+        owner: contact.owner === true,
+      };
+    }).filter((contact) => contact.principal),
+    pending: array(source.pending).map((item) => {
+      const request = object(item);
+      return {
+        id: text(request.id),
+        kind: text(request.kind),
+        name: text(request.name),
+        principal: text(request.principal),
+        label: text(request.label),
+        expiresInS: count(request.expires_in_s),
+      };
+    }).filter((request) => request.id),
+    bindings: array(source.bindings).map((item) => {
+      const binding = object(item);
+      return {
+        key: text(binding.key),
+        label: text(binding.label),
+        chat: text(binding.chat),
+        sender: text(binding.sender),
+        sessionId: text(binding.session_id),
+        noWorkspace: binding.no_workspace !== false,
+        cwd: text(binding.cwd),
+        workspaceHash: text(binding.workspace_hash),
+        sent: count(binding.sent),
+        failed: count(binding.failed),
+        dropped: count(binding.dropped),
+      };
+    }).filter((binding) => binding.key && binding.sessionId),
+  };
+}
+
+// 扫码绑定流程的状态(QQ、微信)。
+export function normalizeBind(raw) {
+  const source = object(raw);
+  return {
+    platform: text(source.platform),
+    phase: text(source.phase) || 'idle',
+    qrUrl: text(source.qr_url),
+    refreshes: count(source.refreshes),
+    error: text(source.error),
+    account: text(source.account),
+    ownerBound: source.owner_bound === true,
+  };
+}
+
+export function normalizeChannelsSnapshot(raw) {
+  const source = object(raw);
+  const platforms = {};
+  for (const platform of CHANNEL_PLATFORMS) platforms[platform] = emptyChannelPlatform(platform);
+  for (const item of array(source.platforms)) {
+    const normalized = normalizeChannelPlatform(item);
+    if (isChannelPlatform(normalized.platform)) platforms[normalized.platform] = normalized;
+  }
+  const rawBinds = object(source.binds);
+  const binds = {};
+  for (const platform of SCAN_PLATFORMS) binds[platform] = normalizeBind({ platform, ...object(rawBinds[platform]) });
+  return { platforms, binds };
+}
+
+// WS 事件合并:channels_state 替换单个平台快照,channels_bind 更新该平台的扫码状态;
+// 无关事件原样返回同一个对象(调用方可据此跳过重渲染)。
+export function applyChannelsEvent(state, envelope) {
+  const message = object(envelope);
+  const payload = object(message.payload);
+  if (message.type === 'channels_state') {
+    const platform = normalizeChannelPlatform(payload);
+    if (!isChannelPlatform(platform.platform)) return state;
+    return { ...state, platforms: { ...state.platforms, [platform.platform]: platform } };
+  }
+  if (message.type === 'channels_bind' && SCAN_PLATFORMS.includes(payload.platform)) {
+    return { ...state, binds: { ...object(state.binds), [payload.platform]: normalizeBind(payload) } };
+  }
+  return state;
+}
+
+// 平台卡片的固定内容。图标统一用单色图标,默认是聊天图标(用户拍板:不用彩色品牌 logo)。
+// 写成函数:文案在渲染时求值,切换界面语言后跟着变。
+export function channelCards() {
+  const card = (platform, title, description) => ({ platform, title, icon: 'chat', description });
+  return [
+    card('qq', 'QQ 机器人', '在 QQ 私聊或群里 @机器人 下达指令,结果回到聊天窗口。'),
+    card('weixin', '微信', '在微信里私聊机器人下达指令,结果回到聊天窗口。'),
+    card('feishu', '飞书', '在飞书私聊或群里 @机器人 下达指令,结果回到聊天窗口。'),
+    card('dingtalk', '钉钉', '在钉钉私聊或群里 @机器人 下达指令,结果回到聊天窗口。'),
+    card('telegram', 'Telegram', '在 Telegram 私聊或群里 @机器人 下达指令,结果回到聊天窗口。'),
+    card('discord', 'Discord', '私信机器人或在服务器频道里 @它 下达指令,结果回到频道。'),
+    card('line', 'LINE', '在 LINE 私聊或群里 @机器人 下达指令,结果回到聊天窗口。'),
+  ];
+}
+
+const DISCORD_PERMISSIONS = '274878008320';  // 查看频道、发消息、读历史、附件、在子区发消息
+
+export function discordInviteUrl(applicationId) {
+  const id = text(applicationId);
+  return id ? `https://discord.com/oauth2/authorize?client_id=${id}&scope=bot&permissions=${DISCORD_PERMISSIONS}` : '';
+}
+
+// 每个平台的连接向导:三步的名称、第一步(扫码或填写凭据)的说明与字段、连上后要回平台后台
+// 完成的事、机主怎么产生(scan:QQ 扫码人 / scanner:微信扫码人 / link:Telegram 链接 /
+// code:6 位绑定码)、完成时的提示。
+export function platformSetup(platform) {
+  const field = (key, label, extra = {}) => ({ key, label, placeholder: label, secret: false, ...extra });
+  switch (platform) {
+    case 'qq':
+      return {
+        steps: ['扫码创建机器人', '连接', '绑定机主'],
+        credential: {
+          kind: 'scan',
+          scanHint: '扫码后会自动创建机器人并完成配置,扫码人成为机主。',
+          manualIntro: '填写 QQ 开放平台里机器人的 AppID 与 AppSecret,保存前会先验证。',
+          fields: [field('app_id', 'AppID'), field('app_secret', 'AppSecret', { secret: true })],
+        },
+        connectChecklist: [],
+        owner: 'scan',
+        doneHint: '现在可以在 QQ 里私聊机器人了。把机器人拉进群后 @ 它,第一次需要在设置页批准。未经个人认证的机器人只能由你本人使用,也只能加入你担任群主的群。',
+      };
+    case 'weixin':
+      return {
+        steps: ['扫码登录', '连接', '完成'],
+        credential: {
+          kind: 'scan',
+          scanHint: '用微信扫一扫并在手机上确认;扫码的微信号就是机主,也是唯一能使用它的人。',
+          manualIntro: '',
+          fields: [],
+        },
+        connectChecklist: [],
+        owner: 'scanner',
+        doneHint: '现在可以在微信里给机器人发消息了。微信机器人只支持私聊。',
+      };
+    case 'feishu':
+      return {
+        steps: ['创建应用', '连接', '绑定机主'],
+        credential: {
+          kind: 'form',
+          instructions: [
+            '打开飞书开放平台,创建「企业自建应用」,在「添加应用能力」里添加「机器人」。',
+            '在「权限管理」开通:im:message、im:message:send_as_bot、im:message.p2p_msg:readonly、im:message.group_at_msg:readonly、im:resource。',
+            '在「凭证与基础信息」复制 App ID 与 App Secret,填到下面。',
+          ],
+          links: [{ label: '打开飞书开放平台', href: 'https://open.feishu.cn/app' }],
+          fields: [
+            field('app_id', 'App ID', { placeholder: 'App ID(cli_ 开头)' }),
+            field('app_secret', 'App Secret', { secret: true }),
+            field('domain', '版本', {
+              kind: 'select',
+              options: [{ value: 'feishu', label: '飞书(中国)' }, { value: 'lark', label: 'Lark(海外)' }],
+              defaultValue: 'feishu',
+            }),
+          ],
+        },
+        connectChecklist: [
+          '回到飞书开放平台的「事件与回调」,订阅方式选「使用长连接接收事件」并保存(这里连上之后才能保存)。',
+          '添加事件「接收消息 v2.0」(im.message.receive_v1)。',
+          '在「版本管理与发布」创建版本并发布,可用范围要包含你自己。',
+        ],
+        owner: 'code',
+        ownerHint: '在飞书里搜索这个机器人,私聊它发送下面的 6 位数字。',
+        doneHint: '现在可以在飞书里私聊机器人了。把机器人拉进群后 @ 它,第一次需要在设置页批准。',
+      };
+    case 'dingtalk':
+      return {
+        steps: ['创建应用', '连接', '绑定机主'],
+        credential: {
+          kind: 'form',
+          instructions: [
+            '打开钉钉开放平台,创建「企业内部应用」,在「应用能力」里添加「机器人」。',
+            '机器人的消息接收模式选「Stream 模式」,在「权限管理」开通企业内机器人发送消息权限,然后发布应用。',
+            '在「凭证与基础信息」复制 Client ID 与 Client Secret,填到下面。',
+          ],
+          links: [{ label: '打开钉钉开放平台', href: 'https://open-dev.dingtalk.com/' }],
+          fields: [field('client_id', 'Client ID'), field('client_secret', 'Client Secret', { secret: true })],
+        },
+        connectChecklist: [],
+        owner: 'code',
+        ownerHint: '在钉钉里找到这个机器人,私聊它发送下面的 6 位数字。',
+        doneHint: '现在可以在钉钉里私聊机器人了。把机器人拉进群后 @ 它,第一次需要在设置页批准。',
+      };
+    case 'telegram':
+      return {
+        steps: ['创建机器人', '连接', '绑定机主'],
+        credential: {
+          kind: 'form',
+          instructions: [
+            '在 Telegram 里搜索 @BotFather(认准蓝色认证标记),发送 /newbot。',
+            '按提示起名字,用户名要以 bot 结尾。',
+            '把它回复的 Token 粘贴到下面。',
+          ],
+          links: [],
+          fields: [field('token', 'Bot Token', { secret: true })],
+        },
+        connectChecklist: [],
+        owner: 'link',
+        doneHint: '把机器人拉进群后 @ 它,第一次需要在设置页批准。',
+      };
+    case 'discord':
+      return {
+        steps: ['创建机器人', '连接', '绑定机主'],
+        credential: {
+          kind: 'form',
+          instructions: [
+            '打开 Discord 开发者后台,新建应用,在「Bot」页点「Reset Token」并复制。',
+            '在同一页打开「Message Content Intent」。',
+            '把 Token 粘贴到下面;验证通过后用邀请链接把机器人拉进你的服务器。',
+          ],
+          links: [{ label: '打开 Discord 开发者后台', href: 'https://discord.com/developers/applications' }],
+          fields: [field('token', 'Bot Token', { secret: true })],
+        },
+        connectChecklist: [],
+        owner: 'code',
+        ownerHint: '在 Discord 里私信这个机器人(需要和它在同一个服务器),发送下面的 6 位数字。',
+        doneHint: '现在可以私信机器人,或在服务器频道里 @ 它。第一次在频道里使用需要在设置页批准。',
+      };
+    case 'line':
+      return {
+        steps: ['创建频道', '连接', '绑定机主'],
+        credential: {
+          kind: 'form',
+          instructions: [
+            '在 LINE Official Account Manager 建立官方账号,并在「设定 > Messaging API」启用 Messaging API。',
+            '在 LINE Developers 控制台的频道「Basic settings」复制 Channel ID 与 Channel secret,填到下面。',
+            '在「Messaging API」页打开 Use webhook;在官方账号的回应设定里关闭自动回应讯息与加入好友的欢迎讯息。',
+          ],
+          note: 'LINE 只能通过公网地址回调。公网地址留空时,ACECode 会用 cloudflared 自动建立临时隧道(先安装:winget install --id Cloudflare.cloudflared),每次连接都会自动更新 LINE 的回调地址。',
+          links: [
+            { label: '打开 LINE Developers', href: 'https://developers.line.biz/console/' },
+            { label: '打开 LINE Official Account Manager', href: 'https://manager.line.biz/' },
+          ],
+          fields: [
+            field('channel_id', 'Channel ID'),
+            field('channel_secret', 'Channel secret', { secret: true }),
+            field('public_url', '公网地址', { placeholder: '公网地址(可选,留空则自动建立隧道)', clearable: true }),
+          ],
+        },
+        connectChecklist: [],
+        owner: 'code',
+        ownerHint: '在 LINE 里把官方账号加为好友,私聊它发送下面的 6 位数字。',
+        doneHint: '现在可以在 LINE 里私聊机器人了。把机器人邀请进群后 @ 它,第一次需要在设置页批准。',
+      };
+    default:
+      return {
+        steps: ['配置', '连接', '绑定机主'],
+        credential: { kind: 'form', instructions: [], links: [], fields: [] },
+        connectChecklist: [],
+        owner: 'code',
+        ownerHint: '',
+        doneHint: '',
+      };
+  }
+}
+
+export function wizardSteps(platform) {
+  return platformSetup(platform).steps;
+}
+
+// 已保存的机器人在向导与管理对话框里的一行摘要(只用非密钥字段与密钥尾号)。
+export function savedBotSummary(platformKey, platform) {
+  const item = platform || emptyChannelPlatform(platformKey);
+  const fields = object(item.credentialsPublic);
+  const value = (key) => text(fields[key]);
+  switch (platformKey) {
+    case 'qq':
+      return { title: `AppID ${item.appId || value('app_id') || '未知'}`, desc: `AppSecret ${item.credentialHint || '已保存'}` };
+    case 'weixin':
+      return { title: item.displayName || '微信机器人', desc: value('bot_id') ? `机器人 ${value('bot_id')}` : '' };
+    case 'feishu':
+      return { title: item.displayName || `App ID ${value('app_id')}`, desc: `App Secret ${value('app_secret') || '已保存'}` };
+    case 'dingtalk':
+      return { title: item.displayName || `Client ID ${value('client_id')}`, desc: `Client Secret ${value('client_secret') || '已保存'}` };
+    case 'line':
+      return { title: item.displayName || `Channel ${value('channel_id')}`, desc: `Channel secret ${value('channel_secret') || '已保存'}` };
+    default:
+      return { title: item.displayName || `${channelPlatformTitle(platformKey)} 机器人`, desc: `Token ${item.credentialHint || '已保存'}` };
+  }
+}
+
+// 卡片:按钮(连接 / 取消连接)与一行简要状态,tone 取 ok / warn / danger / mute。
+// 失败只说“详情见日志”,并给出 action:'fix' 让卡片显示「处理」入口(打开向导的连接步)。
+export function channelCardView(platform, busy = false) {
+  const item = platform || emptyChannelPlatform('');
+  const button = item.enabled
+    ? { action: 'disconnect', label: '取消连接', disabled: Boolean(busy) }
+    : { action: 'connect', label: '连接', disabled: Boolean(busy) || item.state === 'error' };
+  return { button, status: cardStatus(item) };
+}
+
+function cardStatus(item) {
+  if (item.state === 'error') return { tone: 'danger', text: '通道数据异常,详情见日志' };
+  if (!item.enabled) return null;
+  switch (item.state) {
+    case 'connected':
+      return { tone: 'ok', text: item.displayName ? `已连接 · ${item.displayName}` : '已连接' };
+    case 'connecting':
+      return { tone: 'warn', text: '连接中…' };
+    case 'retrying':
+      return { tone: 'warn', text: '连接中断,正在自动重试' };
+    case 'failed':
+      return telegramWebhookBlocked(item)
+        ? { tone: 'warn', text: '机器人设置了 webhook,需要处理', action: 'fix' }
+        : { tone: 'danger', text: '连接失败,详情见日志', action: 'fix' };
+    case 'standby':
+      return { tone: 'mute', text: '已由另一个 ACECode 连接' };
+    default:
+      return { tone: 'mute', text: '未连接' };
+  }
+}
+
+// 点「连接」:还没配好(没有凭据,或还没有机主)时打开分步向导,已经配好的直接连接。
+export function connectNeedsWizard(platform) {
+  const item = platform || emptyChannelPlatform('');
+  return !item.configured || !item.owner || scanLoginExpired(item);
+}
+
+// 微信的登录凭据会在腾讯侧失效:平台停止重试后只能重新扫码,重连旧凭据没有意义。
+function scanLoginExpired(item) {
+  return item.platform === 'weixin' && item.state === 'failed' && item.retryStopped;
+}
+
+// 向导从哪一步开始:没有凭据(或微信登录已失效)从第 1 步,有凭据从第 2 步(连接)。
+export function initialWizardStep(platform) {
+  if (!platform?.configured || scanLoginExpired(platform)) return 0;
+  return 1;
+}
+
+// 向导第 2 步(连接)的视图:phase 决定能做什么,text 是给用户看的一句话。
+export function connectStepView(platform) {
+  const item = platform || emptyChannelPlatform('');
+  if (item.state === 'error') return { phase: 'failed', tone: 'danger', text: '通道数据文件异常,详情见日志。' };
+  if (item.state === 'connected') {
+    return { phase: 'connected', tone: 'ok', text: item.displayName ? `已连接 ${item.displayName}` : '已连接' };
+  }
+  if (!item.enabled) return { phase: 'idle', tone: 'mute', text: '正在打开连接…' };
+  const lineHint = lineConnectHint(item);
+  if (lineHint) return lineHint;
+  switch (item.state) {
+    case 'failed':
+      if (telegramWebhookBlocked(item)) {
+        return {
+          phase: 'webhook',
+          tone: 'warn',
+          text: '这个机器人设置了 webhook,ACECode 收不到消息。移除后由 ACECode 接管,原来接收 webhook 的服务会停止收到消息。',
+        };
+      }
+      return { phase: 'failed', tone: 'danger', text: '连接失败,原因已写入日志。确认凭据无误后重试,或回到上一步更换。' };
+    case 'retrying':
+      return { phase: 'connecting', tone: 'warn', text: '连接中断,正在自动重试…' };
+    case 'standby':
+      return { phase: 'standby', tone: 'mute', text: '这个机器人正由另一个 ACECode 连接,它退出后这里会自动接管。' };
+    default:
+      return { phase: 'connecting', tone: 'mute', text: '正在连接…' };
+  }
+}
+
+// LINE 连接里只有用户能做的几步:装 cloudflared、在控制台打开 Use webhook、把自己的公网地址
+// 转发到本机回调端口。其余失败原因照常只写日志。
+function lineConnectHint(item) {
+  if (item.platform !== 'line') return null;
+  const extra = item.extra || {};
+  if (item.state === 'failed' && extra.cloudflared_missing === true) {
+    return {
+      phase: 'failed',
+      tone: 'danger',
+      text: '没有找到 cloudflared。先运行 winget install --id Cloudflare.cloudflared 安装后重试,或回到上一步填写自己的公网地址。',
+    };
+  }
+  if (item.state !== 'retrying') return null;
+  if (extra.webhook_active === false) {
+    return {
+      phase: 'connecting',
+      tone: 'warn',
+      text: '回调地址已登记。请在 LINE Developers 控制台的 Messaging API 页打开 Use webhook,打开后这里会自动变为已连接。',
+    };
+  }
+  const port = Number(extra.listen_port) || 0;
+  if (extra.tunnel === 'custom' && port > 0 && !text(extra.webhook_url)) {
+    return {
+      phase: 'connecting',
+      tone: 'warn',
+      text: `请把你的公网地址转发到本机 http://127.0.0.1:${port},连通后会自动继续。`,
+    };
+  }
+  return null;
+}
+
+export function ownerTitle(platform) {
+  const owner = text(platform?.owner);
+  if (!owner) return '';
+  const contact = array(platform?.contacts).find((item) => item.principal === owner);
+  return contact?.name || principalLabel(owner);
+}
+
+// 向导第 3 步(绑定机主)。Telegram 用一次性链接;飞书、钉钉、Discord、LINE 用 6 位绑定码;
+// QQ 扫码时通常已带出机主,没带出时靠 10 分钟窗口,窗口过了就批准对方的私聊请求
+// (批准第一个私聊请求即成为机主);微信的扫码人就是机主。
+export function ownerStepView(platform, platformKey) {
+  const item = platform || emptyChannelPlatform(platformKey);
+  if (item.owner) return { done: true, mode: 'done', text: `机主:${ownerTitle(item)}` };
+  const owner = platformSetup(platformKey).owner;
+  if (owner === 'link') return { done: false, mode: 'link', text: '' };
+  if (owner === 'code') return { done: false, mode: 'code', text: platformSetup(platformKey).ownerHint };
+  const title = channelPlatformTitle(platformKey);
+  if (item.ownerWindow) {
+    return { done: false, mode: 'window', text: `接下来 10 分钟内第一个私聊机器人的人成为机主,现在就用你的 ${title} 私聊它一句。` };
+  }
+  return { done: false, mode: 'request', text: `用你的 ${title} 私聊机器人一句,下面会出现请求,批准后你就是机主。` };
+}
+
+// 扫码流程视图(QQ、微信)。
+export function bindView(bind, platformKey = 'qq') {
+  const state = bind || normalizeBind(null);
+  const active = state.phase === 'starting' || state.phase === 'waiting';
+  switch (state.phase) {
+    case 'starting':
+      return { active, showQr: false, tone: 'mute', message: '正在获取二维码…' };
+    case 'waiting':
+      return {
+        active,
+        showQr: Boolean(state.qrUrl),
+        tone: 'mute',
+        message: state.refreshes > 0
+          ? '二维码过期后已自动换新,请扫描新的二维码'
+          : platformKey === 'weixin'
+            ? '用微信扫一扫,并在手机上确认'
+            : '用手机 QQ 扫一扫,按提示创建并授权机器人',
+      };
+    case 'completed':
+      return { active, showQr: false, tone: 'ok', message: state.ownerBound ? '扫码成功,你已是机主' : '扫码成功' };
+    case 'failed':
+      return {
+        active,
+        showQr: false,
+        tone: 'danger',
+        message: state.error || (platformKey === 'weixin' ? '获取二维码失败,请重试' : '获取二维码失败,可以重试,或改为手动填写'),
+      };
+    case 'cancelled':
+      return { active, showQr: false, tone: 'mute', message: '已取消扫码,原有配置未改动' };
+    case 'timed_out':
+      return { active, showQr: false, tone: 'danger', message: '二维码已过期' };
+    default:
+      return { active: false, showQr: false, tone: 'mute', message: '' };
+  }
+}
+
+export function principalLabel(principal) {
+  const value = text(principal);
+  if (value.startsWith('member:')) {
+    const rest = value.slice('member:'.length);
+    const split = rest.indexOf(':');
+    if (split > 0) return `群 ${rest.slice(0, split)} 的成员 ${rest.slice(split + 1)}`;
+  }
+  if (value.startsWith('group:')) return `群 ${value.slice('group:'.length)}`;
+  if (value.startsWith('user:')) return `用户 ${value.slice('user:'.length)}`;
+  return value;
+}
+
+export function principalKindLabel(kind) {
+  if (kind === 'group') return '群';
+  if (kind === 'member') return '群成员';
+  return '私聊';
+}
+
+export function contactRows(platform) {
+  return array(platform?.contacts).map((contact) => ({
+    ...contact,
+    title: contact.name || principalLabel(contact.principal),
+    subtitle: contact.name ? principalLabel(contact.principal) : '',
+    kindLabel: contact.owner ? '机主' : principalKindLabel(contact.kind),
+  }));
+}
+
+export function pendingRows(platform) {
+  return array(platform?.pending).map((request) => {
+    const minutes = Math.max(1, Math.ceil(request.expiresInS / 60));
+    return {
+      ...request,
+      title: request.name || principalLabel(request.principal),
+      subtitle: [principalKindLabel(request.kind), request.label, `${minutes} 分钟后过期`]
+        .filter(Boolean).join(' · '),
+    };
+  });
+}
+
+export function telegramWebhookBlocked(platform) {
+  return object(platform?.extra).webhook === true;
+}
+
+// 平台第一步要填写的字段(QQ 是扫码之外的手动填写)。
+export function credentialFields(platform) {
+  return platformSetup(platform).credential.fields;
+}
+
+// 保存凭据的请求体:去两端空白,空字段省略(表示沿用已保存的值);标了 clearable 的可选字段
+// 留空表示清除(如 LINE 公网地址改回自动隧道)。没有任何内容时返回 null。
+export function credentialsPayload(platform, draft) {
+  const source = object(draft);
+  const body = {};
+  let filled = false;
+  for (const field of credentialFields(platform)) {
+    const value = text(source[field.key] ?? field.defaultValue).trim();
+    if (value) {
+      body[field.key] = value;
+      if (field.kind !== 'select') filled = true;
+    } else if (field.clearable) {
+      body[field.key] = '';
+    }
+  }
+  return filled || Object.keys(body).some((key) => body[key] === '') ? body : null;
+}
+
+// 输入框占位:已保存的密钥给尾号并提示留空不改,已保存的普通字段给原值,否则给字段名。
+export function credentialPlaceholder(platform, field) {
+  const saved = text(object(platform?.credentialsPublic)[field.key]);
+  if (saved) return field.secret ? `已保存 ${saved},留空则不修改` : `${saved}(留空则不修改)`;
+  return field.placeholder || field.label;
+}
+
+// 二维码:返回带 4 格静区的边长与 SVG 路径(按行合并相邻深色模块)。
+export function qrSvgModel(content, errorCorrection = 'M') {
+  const value = text(content);
+  if (!value) return null;
+  const code = qrcode(0, errorCorrection);
+  code.addData(value);
+  code.make();
+  const modules = code.getModuleCount();
+  const quiet = 4;
+  const parts = [];
+  for (let row = 0; row < modules; row += 1) {
+    let col = 0;
+    while (col < modules) {
+      if (!code.isDark(row, col)) {
+        col += 1;
+        continue;
+      }
+      let end = col;
+      while (end < modules && code.isDark(row, end)) end += 1;
+      parts.push(`M${col + quiet} ${row + quiet}h${end - col}v1h-${end - col}z`);
+      col = end;
+    }
+  }
+  return { size: modules + quiet * 2, modules, path: parts.join('') };
+}
+
+// 会话列表:被 IM 会话绑定的会话带 channel_bound:{platform};返回平台名或空串。
+export function channelBoundPlatform(session) {
+  const bound = object(session?.channel_bound ?? session?.channelBound);
+  const platform = text(bound.platform);
+  return isChannelPlatform(platform) ? platform : '';
+}
+
+export function channelBoundLabel(platform) {
+  return platform ? `已绑定到 ${channelPlatformTitle(platform)}` : '';
+}
+
+// 所有平台绑定的会话 id 集合(排序后的字符串,便于比较是否变化)。
+export function channelBindingSignature(state) {
+  const ids = [];
+  for (const platform of CHANNEL_PLATFORMS) {
+    for (const binding of array(state?.platforms?.[platform]?.bindings)) ids.push(`${platform}:${binding.sessionId}`);
+  }
+  return ids.sort().join('|');
+}
+
+// 单个 channels_state 事件里的绑定签名;侧栏据此判断要不要立即刷新。
+export function channelStateBindingSignature(payload) {
+  const platform = normalizeChannelPlatform(payload);
+  if (!isChannelPlatform(platform.platform)) return null;
+  return platform.bindings.map((binding) => binding.sessionId).sort().join('|');
+}
+
+// 接口错误的展示文案:优先用后端给的中文 message(不含凭据);远程客户端统一提示本机设置。
+export function channelErrorText(error) {
+  const body = object(error?.body);
+  if (error?.code === 'LOCAL_ONLY' || body.error === 'LOCAL_ONLY') return '消息通道只能在运行 ACECode 的这台电脑上设置';
+  return text(body.message) || text(error?.message) || '操作失败';
+}
diff --git a/web/src/lib/channelsSettings.test.js b/web/src/lib/channelsSettings.test.js
new file mode 100644
index 000000000..054f69951
--- /dev/null
+++ b/web/src/lib/channelsSettings.test.js
@@ -0,0 +1,387 @@
+// lib/channelsSettings 单元测试:消息通道设置页的快照规整、卡片(连接 / 取消连接 + 简要状态)、
+// 分步连接向导各步的视图、扫码视图、WS 事件合并、二维码路径与侧栏 channel_bound 判定。
+
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import qrcode from 'qrcode-generator';
+import {
+  applyChannelsEvent,
+  channelBindingSignature,
+  channelBoundLabel,
+  channelBoundPlatform,
+  channelCardView,
+  channelCards,
+  channelErrorText,
+  channelStateBindingSignature,
+  connectNeedsWizard,
+  connectStepView,
+  contactRows,
+  credentialFields,
+  credentialPlaceholder,
+  credentialsPayload,
+  discordInviteUrl,
+  initialWizardStep,
+  normalizeChannelsSnapshot,
+  ownerStepView,
+  pendingRows,
+  principalLabel,
+  bindView,
+  platformSetup,
+  savedBotSummary,
+  qrSvgModel,
+  telegramWebhookBlocked,
+  wizardSteps,
+} from './channelsSettings.js';
+
+function run(name, fn) {
+  try {
+    fn();
+    console.log(`[pass] ${name}`);
+  } catch (error) {
+    console.error(`[fail] ${name}`);
+    throw error;
+  }
+}
+
+const TELEGRAM = {
+  platform: 'telegram',
+  configured: true,
+  enabled: true,
+  state: 'connected',
+  display_name: '@ace_bot',
+  credential_hint: '****wxyz',
+  extra: { username: 'ace_bot', privacy_mode: true },
+  owner: 'user:42',
+  contacts: [{ principal: 'user:42', kind: 'user', name: '我', owner: true }],
+  pending: [{ id: 'r1', kind: 'user', name: 'Alice', principal: 'user:7', label: 'Telegram 私聊', expires_in_s: 61 }],
+  bindings: [{
+    key: '["telegram","1","private","42"]',
+    label: 'Telegram 私聊',
+    session_id: 's-1',
+    no_workspace: false,
+    cwd: 'C:/work/项目A',
+    sent: 3,
+    failed: 1,
+    dropped: 0,
+  }],
+};
+
+// 场景:接口返回只有 Telegram 一个平台,QQ 缺失;字段是 snake_case。
+// 期望:两个平台都有默认快照;字段转成 camelCase,数组项缺 id 的被丢弃。
+run('normalizeChannelsSnapshot 补齐缺失平台并规整字段', () => {
+  const state = normalizeChannelsSnapshot({
+    platforms: [{ ...TELEGRAM, pending: [...TELEGRAM.pending, { name: '缺 id' }] }],
+    binds: { qq: { platform: 'qq', phase: 'waiting', qr_url: 'https://q.qq.com/x', refreshes: 2 } },
+  });
+  assert.equal(state.platforms.qq.state, 'unconfigured');
+  assert.equal(state.platforms.qq.configured, false);
+  assert.equal(state.platforms.telegram.displayName, '@ace_bot');
+  assert.equal(state.platforms.telegram.pending.length, 1);
+  assert.equal(state.platforms.telegram.bindings[0].sessionId, 's-1');
+  assert.equal(state.binds.qq.qrUrl, 'https://q.qq.com/x');
+  assert.equal(state.binds.qq.refreshes, 2);
+  assert.equal(state.binds.weixin.phase, 'idle');
+  assert.equal(state.platforms.discord.state, 'unconfigured');
+});
+
+// 场景:WS 推来 channels_state(替换单个平台)、channels_bind(扫码进度)与无关事件。
+// 期望:只改对应部分;无关事件返回同一个对象,组件可跳过重渲染。
+run('applyChannelsEvent 只合并消息通道事件', () => {
+  const state = normalizeChannelsSnapshot({ platforms: [TELEGRAM] });
+  const next = applyChannelsEvent(state, {
+    type: 'channels_state',
+    payload: { ...TELEGRAM, state: 'retrying', detail: '网络中断' },
+  });
+  assert.equal(next.platforms.telegram.state, 'retrying');
+  assert.equal(next.platforms.qq, state.platforms.qq);
+  const bind = applyChannelsEvent(next, { type: 'channels_bind', payload: { platform: 'qq', phase: 'failed', error: '门户不可用' } });
+  assert.equal(bind.binds.qq.phase, 'failed');
+  const weixin = applyChannelsEvent(bind, { type: 'channels_bind', payload: { platform: 'weixin', phase: 'waiting', qr_url: 'https://liteapp.weixin.qq.com/q/x' } });
+  assert.equal(weixin.binds.weixin.qrUrl, 'https://liteapp.weixin.qq.com/q/x');
+  assert.equal(weixin.binds.qq, bind.binds.qq);
+  assert.equal(applyChannelsEvent(weixin, { type: 'channels_bind', payload: { platform: 'telegram', phase: 'waiting' } }), weixin);
+  assert.equal(applyChannelsEvent(bind, { type: 'token', payload: {} }), bind);
+  assert.equal(applyChannelsEvent(bind, { type: 'channels_state', payload: { platform: 'whatsapp' } }), bind);
+});
+
+// 场景:设置页的平台卡片。
+// 期望:七个平台按国内(QQ、微信、飞书、钉钉)再海外(Telegram、Discord、LINE)排列;图标统一是
+// 单色聊天图标(用户拍板:不用彩色品牌 logo);向导都是三步,第一步按平台区分。
+run('channelCards 与向导步骤', () => {
+  assert.deepEqual(channelCards().map((card) => card.platform),
+    ['qq', 'weixin', 'feishu', 'dingtalk', 'telegram', 'discord', 'line']);
+  assert.ok(channelCards().every((card) => card.icon === 'chat'));
+  assert.deepEqual(wizardSteps('qq'), ['扫码创建机器人', '连接', '绑定机主']);
+  assert.deepEqual(wizardSteps('weixin'), ['扫码登录', '连接', '完成']);
+  assert.deepEqual(wizardSteps('telegram'), ['创建机器人', '连接', '绑定机主']);
+  assert.deepEqual(wizardSteps('line'), ['创建频道', '连接', '绑定机主']);
+});
+
+// 场景:各平台的接入方式。
+// 期望:QQ、微信扫码(只有 QQ 能改手填);飞书、钉钉、Discord、LINE 填凭据并用 6 位绑定码定机主;
+// Telegram 用一次性链接;飞书连上后还要回后台保存长连接订阅并发布版本,所以有连接后清单。
+run('platformSetup 区分接入方式与机主绑定', () => {
+  assert.equal(platformSetup('qq').credential.kind, 'scan');
+  assert.equal(platformSetup('qq').credential.fields.length, 2);
+  assert.equal(platformSetup('weixin').credential.kind, 'scan');
+  assert.equal(platformSetup('weixin').credential.fields.length, 0);
+  assert.equal(platformSetup('weixin').owner, 'scanner');
+  for (const platform of ['feishu', 'dingtalk', 'discord', 'line']) {
+    assert.equal(platformSetup(platform).credential.kind, 'form', platform);
+    assert.equal(platformSetup(platform).owner, 'code', platform);
+  }
+  assert.equal(platformSetup('telegram').owner, 'link');
+  assert.ok(platformSetup('feishu').connectChecklist.some((item) => item.includes('使用长连接接收事件')));
+  assert.deepEqual(credentialFields('dingtalk').map((field) => field.key), ['client_id', 'client_secret']);
+  assert.deepEqual(credentialFields('line').map((field) => field.key), ['channel_id', 'channel_secret', 'public_url']);
+});
+
+// 场景:Discord 校验通过后拿到 application id,向导要给出邀请链接;已保存机器人的摘要。
+// 期望:邀请链接带 bot 作用域与发消息所需权限;没有 id 时不给链接;摘要只用非密钥字段与尾号。
+run('discordInviteUrl 与已保存机器人摘要', () => {
+  assert.equal(discordInviteUrl('123'), 'https://discord.com/oauth2/authorize?client_id=123&scope=bot&permissions=274878008320');
+  assert.equal(discordInviteUrl(''), '');
+  assert.deepEqual(savedBotSummary('feishu', { credentialsPublic: { app_id: 'cli_1', app_secret: '****abcd' } }),
+    { title: 'App ID cli_1', desc: 'App Secret ****abcd' });
+  assert.deepEqual(savedBotSummary('discord', { displayName: 'AceBot', credentialHint: '****wxyz', credentialsPublic: {} }),
+    { title: 'AceBot', desc: 'Token ****wxyz' });
+});
+
+// 场景:卡片在各种状态下的按钮与状态行。
+// 期望:没开时按钮是「连接」且不显示状态;开着时按钮是「取消连接」;已连接显示机器人名;
+// 失败只说“详情见日志”并带「处理」入口(原因写进 daemon 日志,不在页面展开);webhook 单独提示;
+// 数据文件异常时「连接」不可点;请求进行中按钮一律禁用。
+run('channelCardView 按钮与简要状态', () => {
+  const state = normalizeChannelsSnapshot({ platforms: [TELEGRAM] }).platforms.telegram;
+  assert.deepEqual(channelCardView(state), {
+    button: { action: 'disconnect', label: '取消连接', disabled: false },
+    status: { tone: 'ok', text: '已连接 · @ace_bot' },
+  });
+  const off = { ...state, enabled: false, state: 'disabled' };
+  assert.deepEqual(channelCardView(off), { button: { action: 'connect', label: '连接', disabled: false }, status: null });
+  const failed = channelCardView({ ...state, state: 'failed', retryStopped: true, detail: 'token 无效' });
+  assert.deepEqual(failed.status, { tone: 'danger', text: '连接失败,详情见日志', action: 'fix' });
+  assert.equal(failed.status.text.includes('token'), false);
+  assert.equal(channelCardView({ ...state, state: 'failed', extra: { webhook: true } }).status.text,
+    '机器人设置了 webhook,需要处理');
+  assert.equal(channelCardView({ ...state, state: 'retrying', detail: '网络中断' }).status.text, '连接中断,正在自动重试');
+  assert.equal(channelCardView({ ...state, state: 'standby', hostedByPid: 4321 }).status.text, '已由另一个 ACECode 连接');
+  assert.equal(channelCardView({ ...off, state: 'error' }).button.disabled, true);
+  assert.equal(channelCardView(off, true).button.disabled, true);
+  assert.equal(channelCardView(state, true).button.disabled, true);
+});
+
+// 场景:点「连接」时平台的配置程度不同。
+// 期望:没有凭据或还没有机主 -> 打开向导(没有凭据从第 1 步,有凭据从第 2 步);
+// 凭据与机主都齐 -> 直接连接,不弹向导。
+run('connectNeedsWizard 与 initialWizardStep', () => {
+  const blank = normalizeChannelsSnapshot(null).platforms.telegram;
+  const configured = { ...blank, configured: true };
+  const ready = { ...configured, owner: 'user:42' };
+  assert.equal(connectNeedsWizard(blank), true);
+  assert.equal(connectNeedsWizard(configured), true);
+  assert.equal(connectNeedsWizard(ready), false);
+  assert.equal(initialWizardStep(blank), 0);
+  assert.equal(initialWizardStep(configured), 1);
+});
+
+// 场景:LINE 连接停在需要用户动手的几步:没装 cloudflared、控制台没开 Use webhook、
+// 自己的公网地址还没转发到本机回调端口;以及普通的重试。
+// 期望:前三种给出具体该做什么(含端口号);普通重试仍是通用文案;其它平台不受这些字段影响。
+run('LINE 连接步骤的可操作提示', () => {
+  const base = { ...normalizeChannelsSnapshot(null).platforms.line, configured: true, enabled: true };
+  const missing = connectStepView({ ...base, state: 'failed', extra: { cloudflared_missing: true } });
+  assert.equal(missing.phase, 'failed');
+  assert.ok(missing.text.includes('winget install --id Cloudflare.cloudflared'));
+  const webhookOff = connectStepView({ ...base, state: 'retrying', extra: { webhook_active: false } });
+  assert.equal(webhookOff.tone, 'warn');
+  assert.ok(webhookOff.text.includes('Use webhook'));
+  const custom = connectStepView({ ...base, state: 'retrying', extra: { tunnel: 'custom', listen_port: 41234 } });
+  assert.ok(custom.text.includes('http://127.0.0.1:41234'));
+  const plain = connectStepView({ ...base, state: 'retrying', extra: { tunnel: 'cloudflare' } });
+  assert.equal(plain.text, '连接中断,正在自动重试…');
+  const telegram = { ...normalizeChannelsSnapshot(null).platforms.telegram, configured: true, enabled: true };
+  assert.equal(connectStepView({ ...telegram, state: 'retrying', extra: { webhook_active: false } }).text,
+    '连接中断,正在自动重试…');
+});
+
+// 场景:微信登录在腾讯侧失效,传输层报失败并停止重试;另有一次普通的微信连接失败。
+// 期望:登录失效时点「连接」打开向导并从扫码(第 1 步)开始;普通失败仍直接重连;
+// 其他平台停止重试不受影响。
+run('微信登录失效时连接回到扫码', () => {
+  const weixin = normalizeChannelsSnapshot(null).platforms.weixin;
+  const ready = { ...weixin, configured: true, owner: 'user:o@im.wechat' };
+  const expired = { ...ready, state: 'failed', retryStopped: true };
+  assert.equal(connectNeedsWizard(expired), true);
+  assert.equal(initialWizardStep(expired), 0);
+  assert.equal(connectNeedsWizard({ ...ready, state: 'failed', retryStopped: false }), false);
+  const telegram = normalizeChannelsSnapshot(null).platforms.telegram;
+  const stopped = { ...telegram, configured: true, owner: 'user:42', state: 'failed', retryStopped: true };
+  assert.equal(connectNeedsWizard(stopped), false);
+});
+
+// 场景:向导第 2 步(连接)期间平台状态的变化。
+// 期望:还没打开 -> 正在打开;连接中 / 重试中 -> 继续等;已连接 -> 可进入下一步;
+// webhook 阻塞 -> 说明后果并允许移除;其他失败 -> 只说原因已写入日志,可重试;待命 -> 说明会自动接管。
+run('connectStepView 映射连接阶段', () => {
+  const base = { ...normalizeChannelsSnapshot(null).platforms.telegram, configured: true };
+  assert.equal(connectStepView(base).phase, 'idle');
+  assert.equal(connectStepView({ ...base, enabled: true, state: 'connecting' }).phase, 'connecting');
+  assert.equal(connectStepView({ ...base, enabled: true, state: 'retrying' }).phase, 'connecting');
+  assert.deepEqual(connectStepView({ ...base, enabled: true, state: 'connected', displayName: '@ace_bot' }),
+    { phase: 'connected', tone: 'ok', text: '已连接 @ace_bot' });
+  const webhook = connectStepView({ ...base, enabled: true, state: 'failed', extra: { webhook: true } });
+  assert.equal(webhook.phase, 'webhook');
+  assert.match(webhook.text, /原来接收 webhook 的服务会停止收到消息/);
+  const failed = connectStepView({ ...base, enabled: true, state: 'failed', detail: 'token 无效' });
+  assert.equal(failed.phase, 'failed');
+  assert.match(failed.text, /原因已写入日志/);
+  assert.equal(connectStepView({ ...base, enabled: true, state: 'standby' }).phase, 'standby');
+});
+
+// 场景:向导第 3 步(绑定机主)。
+// 期望:已有机主 -> 完成并显示机主名;Telegram 没有机主 -> 一次性链接;QQ 扫码后的 10 分钟窗口内 ->
+// 提示去私聊;窗口已过 -> 提示私聊后批准请求(批准第一个私聊请求即成为机主)。
+run('ownerStepView 按平台给出绑定方式', () => {
+  const telegram = normalizeChannelsSnapshot({ platforms: [TELEGRAM] }).platforms.telegram;
+  assert.deepEqual(ownerStepView(telegram, 'telegram'), { done: true, mode: 'done', text: '机主:我' });
+  assert.equal(ownerStepView({ ...telegram, owner: '' }, 'telegram').mode, 'link');
+  const qq = { ...normalizeChannelsSnapshot(null).platforms.qq, configured: true };
+  assert.equal(ownerStepView({ ...qq, ownerWindow: true }, 'qq').mode, 'window');
+  assert.equal(ownerStepView(qq, 'qq').mode, 'request');
+  assert.equal(ownerStepView({ ...qq, owner: 'user:9' }, 'qq').text, '机主:用户 9');
+  const discord = { ...normalizeChannelsSnapshot(null).platforms.discord, configured: true };
+  assert.equal(ownerStepView(discord, 'discord').mode, 'code');
+  assert.match(ownerStepView(discord, 'discord').text, /6 位数字/);
+});
+
+// 场景:扫码流程各阶段。
+// 期望:进行中阶段 active=true;等待阶段有二维码才显示;过期刷新后提示扫新码;
+// 完成时区分扫码人是否已成为机主;失败附原因并提示可改为手动填写。
+run('bindView 映射扫码阶段', () => {
+  assert.equal(bindView({ phase: 'starting' }).active, true);
+  const waiting = bindView({ phase: 'waiting', qrUrl: 'u', refreshes: 0 });
+  assert.equal(waiting.showQr, true);
+  assert.equal(waiting.message, '用手机 QQ 扫一扫,按提示创建并授权机器人');
+  assert.match(bindView({ phase: 'waiting', qrUrl: 'u', refreshes: 1 }).message, /自动换新/);
+  assert.equal(bindView({ phase: 'completed', ownerBound: true }).message, '扫码成功,你已是机主');
+  assert.equal(bindView({ phase: 'completed', ownerBound: false }).message, '扫码成功');
+  assert.match(bindView({ phase: 'failed', error: '' }).message, /手动填写/);
+  assert.equal(bindView({ phase: 'failed', error: '' }, 'weixin').message, '获取二维码失败,请重试');
+  assert.equal(bindView({ phase: 'waiting', qrUrl: 'u' }, 'weixin').message, '用微信扫一扫,并在手机上确认');
+  assert.equal(bindView({ phase: 'failed', error: '门户不可用' }).message, '门户不可用');
+  assert.equal(bindView({ phase: 'idle' }).active, false);
+});
+
+// 场景:授权名单与待批准请求的展示行。
+// 期望:身份转成中文标签;机主标“机主”;请求显示过期分钟数。
+run('列表行规整', () => {
+  const state = normalizeChannelsSnapshot({ platforms: [TELEGRAM] }).platforms.telegram;
+  assert.equal(principalLabel('member:G1:M1'), '群 G1 的成员 M1');
+  assert.equal(principalLabel('group:-100'), '群 -100');
+  assert.equal(principalLabel('user:7'), '用户 7');
+  assert.equal(contactRows(state)[0].kindLabel, '机主');
+  assert.equal(pendingRows(state)[0].subtitle, '私聊 · Telegram 私聊 · 2 分钟后过期');
+});
+
+// 场景:Telegram 机器人被配置了 webhook,或者没有。
+// 期望:只有 extra.webhook === true 才判定为被阻塞。
+run('telegramWebhookBlocked', () => {
+  assert.equal(telegramWebhookBlocked({ extra: { webhook: true } }), true);
+  assert.equal(telegramWebhookBlocked({ extra: {} }), false);
+});
+
+// 场景:有人把细节加回设置页(2026-10-05 用户验收反馈:设置界面太复杂,细节打印到日志)。
+// 期望:页面组件不渲染原因 / 隐私模式 / 暂存数 / 绑定计数这些细节;卡片两列;不用开关,用连接按钮。
+run('消息通道设置页保持简洁,细节只进日志', () => {
+  const page = readFileSync(new URL('../components/ChannelsSettings.jsx', import.meta.url), 'utf8');
+  assert.match(page, /grid grid-cols-2/);
+  assert.doesNotMatch(page, /platform\.detail|privacy_mode|\.held\b|bindingRows|binding\.stats/);
+  assert.doesNotMatch(page, /<Toggle\b/);
+});
+
+// 场景:手动填写凭据:两端带空白、只改一个字段、全空。
+// 期望:去空白后提交,空字段省略(沿用已保存的值),全空返回 null 不发请求。
+run('credentialsPayload 与占位文案', () => {
+  assert.deepEqual(credentialsPayload('qq', { app_id: ' 1020 ', app_secret: '' }), { app_id: '1020' });
+  assert.deepEqual(credentialsPayload('telegram', { token: ' 1:abc ' }), { token: '1:abc' });
+  assert.equal(credentialsPayload('telegram', { token: '  ' }), null);
+  // 飞书的版本选择默认飞书;只选了版本、没填任何凭据不算有内容。
+  assert.deepEqual(credentialsPayload('feishu', { app_id: 'cli_1', app_secret: 's' }),
+    { app_id: 'cli_1', app_secret: 's', domain: 'feishu' });
+  assert.equal(credentialsPayload('feishu', {}), null);
+  // LINE 公网地址留空表示清除(改回自动隧道),所以即使别的都没填也要提交。
+  assert.deepEqual(credentialsPayload('line', { public_url: ' ' }), { public_url: '' });
+  assert.deepEqual(credentialsPayload('line', { channel_id: '1', channel_secret: 's', public_url: 'https://x.example' }),
+    { channel_id: '1', channel_secret: 's', public_url: 'https://x.example' });
+  const token = credentialFields('telegram')[0];
+  assert.equal(credentialPlaceholder({ credentialsPublic: { token: '****wxyz' } }, token), '已保存 ****wxyz,留空则不修改');
+  assert.equal(credentialPlaceholder({ credentialsPublic: {} }, token), 'Bot Token');
+  const appId = credentialFields('feishu')[0];
+  assert.equal(credentialPlaceholder({ credentialsPublic: { app_id: 'cli_9' } }, appId), 'cli_9(留空则不修改)');
+});
+
+// 场景:把扫码链接画成二维码。
+// 期望:边长 = 模块数 + 两侧各 4 格静区;路径里的深色格数与库给出的深色模块数一致;空内容返回 null。
+run('qrSvgModel 生成带静区的二维码路径', () => {
+  const content = 'https://q.qq.com/qqbot/openclaw/connect.html?task_id=abc&source=acecode&_wv=2';
+  const model = qrSvgModel(content);
+  assert.equal(model.size, model.modules + 8);
+  const code = qrcode(0, 'M');
+  code.addData(content);
+  code.make();
+  let dark = 0;
+  for (let r = 0; r < code.getModuleCount(); r += 1)
+    for (let c = 0; c < code.getModuleCount(); c += 1) if (code.isDark(r, c)) dark += 1;
+  const covered = [...model.path.matchAll(/h(\d+)v1/g)].reduce((sum, match) => sum + Number(match[1]), 0);
+  assert.equal(covered, dark);
+  assert.equal(qrSvgModel(''), null);
+});
+
+// 场景:会话列表行带 channel_bound,或只有 /rc 绑定,或平台名未知。
+// 期望:只认 QQ / Telegram;悬停提示写明平台;/rc 绑定不影响这个判定。
+run('channelBoundPlatform 只认消息通道平台', () => {
+  assert.equal(channelBoundPlatform({ channel_bound: { platform: 'qq' } }), 'qq');
+  assert.equal(channelBoundPlatform({ channelBound: { platform: 'telegram' } }), 'telegram');
+  assert.equal(channelBoundPlatform({ remote_control_bound: true }), '');
+  assert.equal(channelBoundPlatform({ channel_bound: { platform: 'whatsapp' } }), '');
+  assert.equal(channelBoundLabel('qq'), '已绑定到 QQ');
+  assert.equal(channelBoundLabel(''), '');
+});
+
+// 场景:绑定从会话 A 移到会话 B,或只是发送计数变化。
+// 期望:签名只在绑定的会话集合变化时改变,侧栏据此决定是否立即刷新。
+run('绑定签名只随会话集合变化', () => {
+  const state = normalizeChannelsSnapshot({ platforms: [TELEGRAM] });
+  const moved = applyChannelsEvent(state, {
+    type: 'channels_state',
+    payload: { ...TELEGRAM, bindings: [{ ...TELEGRAM.bindings[0], session_id: 's-2' }] },
+  });
+  const counted = applyChannelsEvent(state, {
+    type: 'channels_state',
+    payload: { ...TELEGRAM, bindings: [{ ...TELEGRAM.bindings[0], sent: 9 }] },
+  });
+  assert.notEqual(channelBindingSignature(moved), channelBindingSignature(state));
+  assert.equal(channelBindingSignature(counted), channelBindingSignature(state));
+  assert.equal(channelStateBindingSignature(TELEGRAM), 's-1');
+  assert.equal(channelStateBindingSignature({ platform: 'whatsapp' }), null);
+});
+
+// 场景:接口返回带中文 message 的 400、远程客户端的 403、网络异常。
+// 期望:分别展示后端文案、本机设置提示、异常自身的消息。
+run('channelErrorText 选择展示文案', () => {
+  assert.equal(channelErrorText({ code: 'CHANNEL_ERROR', body: { error: 'CHANNEL_ERROR', message: 'Token 无效' } }), 'Token 无效');
+  assert.equal(channelErrorText({ code: 'LOCAL_ONLY', body: { error: 'LOCAL_ONLY' } }), '消息通道只能在运行 ACECode 的这台电脑上设置');
+  assert.equal(channelErrorText(new Error('Failed to fetch')), 'Failed to fetch');
+  assert.equal(channelErrorText(null), '操作失败');
+});
+
+// 场景:侧栏渲染被消息通道绑定的会话。
+// 期望:与 /rc 共用电脑图标并带平台提示;/rc 的换绑动画类名仍只由 remoteControlBound 决定。
+run('Sidebar 用 channelBoundPlatform 显示通道绑定图标', () => {
+  const sidebar = readFileSync(new URL('../components/Sidebar.jsx', import.meta.url), 'utf8');
+  assert.match(sidebar, /channelBoundPlatform\(s\)/);
+  assert.match(sidebar, /data-channel-session-icon=\{channelPlatform\}/);
+  assert.match(sidebar, /remoteControlBound && 'is-remote-control-bound'/);
+  assert.doesNotMatch(sidebar, /channelPlatform && 'is-remote-control-bound'/);
+});
diff --git a/web/src/lib/chatScrollFollowArchitecture.test.js b/web/src/lib/chatScrollFollowArchitecture.test.js
index c53decebb..b9ceefd36 100644
--- a/web/src/lib/chatScrollFollowArchitecture.test.js
+++ b/web/src/lib/chatScrollFollowArchitecture.test.js
@@ -101,10 +101,11 @@ run('tail button reuses session status without changing visibility or navigation
   assert.match(button, /: <VsIcon name="ArrowDown" size=\{18\} \/>/);
 });
 
-run('tail progress dots animate left to right and respect reduced motion', () => {
+run('tail progress dots keep a lower-amplitude live signal under reduced motion', () => {
   const styles = source('styles/globals.css');
   assert.match(styles, /\.ace-chat-tail-progress > span\s*\{[^}]*background: currentColor;[^}]*animation: ace-chat-tail-dot-hop 1\.2s ease-in-out infinite;/);
-  assert.match(styles, /\.ace-chat-tail-progress > span:nth-child\(2\)\s*\{ animation-delay: \.2s;/);
-  assert.match(styles, /\.ace-chat-tail-progress > span:nth-child\(3\)\s*\{ animation-delay: \.4s;/);
-  assert.match(styles, /@media \(prefers-reduced-motion: reduce\)\s*\{\s*\.ace-chat-tail-progress > span\s*\{ animation: none;/);
+  assert.match(styles, /\.ace-chat-tail-progress > span:nth-child\(2\)\s*\{ animation-delay: \.4s;/);
+  assert.match(styles, /\.ace-chat-tail-progress > span:nth-child\(3\)\s*\{ animation-delay: \.8s;/);
+  assert.match(styles, /\.ace-chat-tail-progress\s*\{ --ace-chat-tail-dot-lift: -1\.5px;/);
+  assert.doesNotMatch(styles, /\.ace-chat-tail-progress > span\s*\{ animation: none;/);
 });
diff --git a/web/src/lib/composerDomSelection.js b/web/src/lib/composerDomSelection.js
new file mode 100644
index 000000000..4c686e959
--- /dev/null
+++ b/web/src/lib/composerDomSelection.js
@@ -0,0 +1,51 @@
+import { Range } from 'slate';
+
+function containsNode(root, node) {
+  if (!root || !node) return false;
+  if (root === node) return true;
+  try {
+    return typeof root.contains === 'function' && root.contains(node);
+  } catch {
+    return false;
+  }
+}
+
+// Slate copies the browser caret into editor.selection only from its throttled
+// selectionchange listener, and skips that listener while it believes a drag,
+// a selection write or a composition is in progress. If one of those flags is
+// left behind, Slate keeps an old selection while the user sees the caret
+// elsewhere. Chrome compositions and Backspace/Delete then apply to the old
+// Slate selection, so IME text lands at the previous position (often the end).
+//
+// Returns the Slate range of the live DOM selection when it must replace
+// editor.selection before the editor consumes input, otherwise null.
+export function composerDomSelectionToAdopt({
+  editor,
+  editableElement,
+  toSlateRange,
+  renderPending = false,
+} = {}) {
+  if (!editor || !editableElement || typeof toSlateRange !== 'function') return null;
+  // Unrendered operations mean the DOM still shows the previous document or
+  // selection. Slate's own sync also waits; mapping now would undo the change.
+  if (renderPending || (editor.operations?.length || 0) > 0) return null;
+  const documentRef = editableElement.ownerDocument;
+  if (!documentRef || documentRef.activeElement !== editableElement) return null;
+  const domSelection = typeof documentRef.getSelection === 'function'
+    ? documentRef.getSelection()
+    : documentRef.defaultView?.getSelection?.();
+  if (!domSelection || !(domSelection.rangeCount > 0)) return null;
+  if (!containsNode(editableElement, domSelection.anchorNode)
+    || !containsNode(editableElement, domSelection.focusNode)) {
+    return null;
+  }
+  let range = null;
+  try {
+    range = toSlateRange(domSelection);
+  } catch {
+    return null;
+  }
+  if (!range?.anchor || !range?.focus) return null;
+  if (editor.selection && Range.equals(range, editor.selection)) return null;
+  return range;
+}
diff --git a/web/src/lib/composerDomSelection.test.js b/web/src/lib/composerDomSelection.test.js
new file mode 100644
index 000000000..9441a7212
--- /dev/null
+++ b/web/src/lib/composerDomSelection.test.js
@@ -0,0 +1,178 @@
+// 本文件覆盖「输入框把浏览器光标同步进 Slate 选区」这一修复(用户反馈:光标在行首,
+// 用中文输入法打的字却出现在行末,切换会话后恢复)。
+//
+// 根因:Slate 只在 selectionchange 里把 DOM 光标写回 editor.selection,并且在它认为
+// 「正在拖拽 / 正在写选区 / 正在合成」时整段跳过。拖拽标记一旦残留(dragstart 之后没有
+// dragend/drop),之后的点击、Home 等都不再更新 editor.selection;而 Chrome 的输入法
+// 合成结束时,Slate 是把文字插到 editor.selection(过期的行末),不是用户看到的光标处。
+// 修复:在 compositionstart / keydown 消费选区之前,用 composerDomSelectionToAdopt 判断
+// 是否需要采纳 DOM 选区。
+//
+// 场景:
+//   1. 回归:Slate 选区停在行末、DOM 光标在行首 → 返回行首的 Slate range
+//   2. 两边一致 → 不重复 select
+//   3. Slate 还有未渲染的改动(渲染中 / 操作未 flush)→ 不用旧 DOM 覆盖新选区
+//   4. 编辑器没有焦点、DOM 选区不在编辑器里、没有选区 → 不采纳
+//   5. DOM 选区映射失败(返回 null 或抛错)→ 不采纳
+//   6. editor.selection 为空时也采纳 DOM 光标
+//   7. 生产接线:compositionstart 先采纳 DOM 光标,再标记合成状态并调用父组件回调
+//   8. 生产接线:渲染哨兵与 editor.onChange 包装共同维护「未渲染」标记
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import vm from 'node:vm';
+import { parseSync, traverse } from '@babel/core';
+import { composerDomSelectionToAdopt } from './composerDomSelection.js';
+
+function run(name, fn) {
+  try {
+    fn();
+    console.log(`[pass] ${name}`);
+  } catch (error) {
+    console.error(`[fail] ${name}`);
+    throw error;
+  }
+}
+
+const point = (offset) => ({ path: [0, 0], offset });
+const caret = (offset) => ({ anchor: point(offset), focus: point(offset) });
+
+// 鸭子类型的假 DOM:editable 只认识自己和 inner 文本节点;document 的 activeElement /
+// getSelection 可按场景替换。
+function fixture({
+  editorSelection = caret(4),
+  domRange = caret(0),
+  focused = true,
+  selectionInside = true,
+  rangeCount = 1,
+  operations = [],
+  renderPending = false,
+} = {}) {
+  const inner = { nodeType: 3 };
+  const outside = { nodeType: 3 };
+  const editable = {
+    contains: (node) => node === editable || node === inner,
+  };
+  const node = selectionInside ? inner : outside;
+  const domSelection = { rangeCount, anchorNode: node, focusNode: node };
+  editable.ownerDocument = {
+    activeElement: focused ? editable : { tagName: 'BUTTON' },
+    getSelection: () => domSelection,
+  };
+  const calls = [];
+  return {
+    calls,
+    args: {
+      editor: { selection: editorSelection, operations },
+      editableElement: editable,
+      renderPending,
+      toSlateRange: (selection) => {
+        calls.push(selection);
+        return typeof domRange === 'function' ? domRange() : domRange;
+      },
+    },
+  };
+}
+
+// 场景 1(回归):用户先打了「帮我」,editor.selection 在行末 offset 4;之后点击 / Home
+// 把 DOM 光标移到行首,但 Slate 的同步被残留的拖拽标记跳过。
+// 期望:返回 DOM 光标对应的行首 range,调用方据此 select。
+// 修复前:输入法提交的文字插到行末,用户看到光标在行首、字却出现在末尾。
+run('stale Slate selection adopts the caret the user actually sees', () => {
+  const test = fixture();
+  assert.deepEqual(composerDomSelectionToAdopt(test.args), caret(0));
+  assert.equal(test.calls.length, 1, 'DOM 选区只映射一次');
+});
+
+// 场景 2:正常情况下 Slate 已同步,两边相同。
+// 期望:返回 null,不产生多余的 set_selection(否则每次按键都触发一次渲染)。
+run('an already synchronized selection is left untouched', () => {
+  const test = fixture({ editorSelection: caret(2), domRange: caret(2) });
+  assert.equal(composerDomSelectionToAdopt(test.args), null);
+});
+
+// 场景 3:程序刚 select 了新位置(例如方向键跨过标签),onChange 已发出但 React 还没把它
+// 写进 DOM(renderPending),或者操作还没 flush(operations 非空)。此时 DOM 仍是旧光标。
+// 期望:不采纳,也不去映射 DOM(NODE 映射表此时也是旧的)。
+// 若误采纳:刚做完的程序化选区会被旧 DOM 光标撤销。
+run('pending renders or unflushed operations keep the programmatic selection', () => {
+  for (const options of [{ renderPending: true }, { operations: [{ type: 'set_selection' }] }]) {
+    const test = fixture(options);
+    assert.equal(composerDomSelectionToAdopt(test.args), null);
+    assert.equal(test.calls.length, 0, '未渲染时不应读取 DOM 选区');
+  }
+});
+
+// 场景 4:焦点在别的控件(按钮、终端)、DOM 选区落在编辑器之外、或者根本没有选区。
+// 期望:全部返回 null —— 不能把别处的选区搬进输入框。
+run('selections outside a focused editor are ignored', () => {
+  for (const options of [{ focused: false }, { selectionInside: false }, { rangeCount: 0 }]) {
+    const test = fixture(options);
+    assert.equal(composerDomSelectionToAdopt(test.args), null, JSON.stringify(options));
+    assert.equal(test.calls.length, 0);
+  }
+  assert.equal(composerDomSelectionToAdopt({}), null, '缺少参数时安全返回');
+});
+
+// 场景 5:DOM 正在被 React 替换等情况下,toSlateRange 映射不出来(null)或直接抛错。
+// 期望:返回 null,保留 Slate 原选区,输入不会因为异常中断。
+run('unmappable DOM selections fall back to the existing Slate selection', () => {
+  assert.equal(composerDomSelectionToAdopt(fixture({ domRange: null }).args), null);
+  assert.equal(composerDomSelectionToAdopt(fixture({ domRange: () => { throw new Error('Cannot resolve a Slate point'); } }).args), null);
+});
+
+// 场景 6:Slate 选区为空(刚挂载、被 deselect)但编辑器已获得焦点且 DOM 有光标。
+// 期望:直接采纳 DOM 光标。
+run('a missing Slate selection adopts the DOM caret', () => {
+  const test = fixture({ editorSelection: null, domRange: caret(3) });
+  assert.deepEqual(composerDomSelectionToAdopt(test.args), caret(3));
+});
+
+const composerSource = fs.readFileSync(new URL('../components/RichComposer.jsx', import.meta.url), 'utf8');
+const ast = parseSync(composerSource, { configFile: false, babelrc: false, parserOpts: { plugins: ['jsx'] } });
+const callbacks = new Map();
+traverse(ast, {
+  VariableDeclarator({ node }) {
+    if (node.id.name === 'handleCompositionStart' || node.id.name === 'adoptDomSelection') {
+      const callback = node.init.arguments[0];
+      callbacks.set(node.id.name, composerSource.slice(callback.start, callback.end));
+    }
+  },
+});
+
+// 场景 7:生产代码的 handleCompositionStart。
+// 触发:compositionstart 到达(Slate 的 onCompositionStart 先调我们的回调,再决定是否删除
+// 选中片段)。
+// 期望:先采纳 DOM 光标,再置 active、清 settling,最后把父组件回调的返回值原样交还 Slate。
+// 修复前:没有采纳这一步,合成结束时文字落在过期的 editor.selection。
+run('composition start adopts the DOM caret before composition state and parent callbacks', () => {
+  assert.ok(callbacks.has('handleCompositionStart'), '缺少生产回调 handleCompositionStart');
+  const order = [];
+  const compositionStateRef = { current: { active: false, settling: true } };
+  const context = vm.createContext({
+    compositionStateRef,
+    clearCompositionSettleTimer: () => order.push('clear'),
+    adoptDomSelection: () => {
+      order.push(`adopt:${compositionStateRef.current.active}`);
+      return true;
+    },
+    onCompositionStart: () => {
+      order.push(`parent:${compositionStateRef.current.active}`);
+      return 'parent-result';
+    },
+  });
+  const handleCompositionStart = vm.runInContext(`(${callbacks.get('handleCompositionStart')})`, context);
+  assert.equal(handleCompositionStart({}), 'parent-result');
+  assert.deepEqual(order, ['clear', 'adopt:false', 'parent:true']);
+  assert.equal(compositionStateRef.current.settling, false);
+});
+
+// 场景 8:「未渲染」标记的两端都必须接上:editor.onChange 包装置位,与 Editable 同一次提交里
+// 的渲染哨兵清除;adoptDomSelection 把它传给判定函数。缺任一端,修复要么失效要么会用旧
+// DOM 覆盖新选区。
+run('render sentinel and onChange wrapper maintain the pending-render flag', () => {
+  assert.match(composerSource, /instance\.onChange = \(options\) => \{[\s\S]*?renderPendingRef\.current = true;[\s\S]*?onChange\(options\);/);
+  assert.match(composerSource, /spellCheck\s*\/>\s*<ComposerRenderSentinel onRendered=\{markEditorRendered\} \/>\s*<\/Slate>/);
+  assert.match(composerSource, /function ComposerRenderSentinel\(\{ onRendered \}\) \{\s*useSlate\(\);\s*useLayoutEffect\(\(\) => \{\s*onRendered\(\);/);
+  assert.match(callbacks.get('adoptDomSelection') || '', /renderPending: renderPendingRef\.current/);
+  assert.match(callbacks.get('adoptDomSelection') || '', /exactMatch: false/);
+});
diff --git a/web/src/lib/desktopNotify.js b/web/src/lib/desktopNotify.js
index defbeaae6..29c9ad195 100644
--- a/web/src/lib/desktopNotify.js
+++ b/web/src/lib/desktopNotify.js
@@ -5,17 +5,19 @@
 // 不存在 → 所有 notify 调用 no-op,这与 search palette 跨 workspace bridge 的
 // 降级模式一致。
 //
-// 唯一弹窗规则:
+// 弹窗规则:
 //   - master enabled 开启
-//   - 事件是主任务 completion
+//   - 事件是主任务 completion,或消息通道的新配对请求(channel)
 //   - 整个 ACECode 窗口失焦
 // permission / question 一律留在页面内处理;窗口只要有焦点,无论当前打开
-// 哪个会话、workspace 或页面都不发 native completion 通知。旧的 per-type
-// 和 suppress_when_focused 配置字段仅保留后端兼容,不再参与运行时判定。
+// 哪个会话、workspace 或页面都不发 native 通知(配对请求改由页面内 toast 提示)。
+// 旧的 per-type 和 suppress_when_focused 配置字段仅保留后端兼容,不再参与运行时判定。
 //
 // payload 构造抽到 buildNotificationPayload — 长文本截断 80 字 + 省略号,
 // 空文本回退到默认占位,纯函数,可测。
 
+import { channelPlatformTitle } from './channelsSettings.js';
+
 const NOTIFICATION_BODY_LIMIT = 80;
 
 // WebView2 / 壳内 focus 有时会短暂落到 native 标题栏,document.hasFocus()
@@ -122,12 +124,36 @@ export function shouldNotifySessionCompletion({
 
 export function shouldSuppress(payload, hasFocus, cfg) {
   if (!notificationsEnabled(cfg)) return true;
-  // payload.id 形如 "question-..." / "completion-...",取首段判类型。
+  // payload.id 形如 "question-..." / "completion-..." / "channel-...",取首段判类型。
   const type = String(payload?.id || '').split('-')[0];
-  if (type !== 'completion') return true;
+  if (type !== 'completion' && type !== 'channel') return true;
   return hasFocus === true;
 }
 
+// 消息通道(QQ、微信、飞书、钉钉、Telegram、Discord、LINE)的新配对请求(WS channels_request)。
+// 不关联会话,点击通知只把窗口拉到前台。
+export function buildChannelRequestPayload(request = {}) {
+  const platform = String(request.platform || '');
+  const title = `${channelPlatformTitle(platform)} 配对请求`;
+  const who = String(request.name || '').trim() || (request.kind === 'group' ? '一个群' : '新联系人');
+  const where = String(request.label || '').trim();
+  return {
+    id: `channel-${platform || 'unknown'}-${String(request.id || '')}-${Date.now()}`,
+    workspace_hash: '',
+    session_id: '',
+    title,
+    body: truncateForNotification(`${who}${where ? `(${where})` : ''}请求使用 ACECode,到设置 > 消息通道处理`),
+  };
+}
+
+export function maybeNotifyChannelRequest(request, { hasFocus, cfg } = {}) {
+  if (!bridgeAvailable()) return false;
+  const payload = buildChannelRequestPayload(request);
+  const focused = typeof hasFocus === 'boolean' ? hasFocus : isHostWindowFocused();
+  if (shouldSuppress(payload, focused, cfg)) return false;
+  return notify(payload);
+}
+
 function bridgeAvailable() {
   return typeof window !== 'undefined'
     && typeof window.aceDesktop_notify === 'function';
@@ -155,10 +181,10 @@ export function focusSession(workspaceHash, sessionId) {
     return false;
   }
   try {
-    window.aceDesktop_focusSession(JSON.stringify({
+    window.aceDesktop_focusSession({
       workspace_hash: workspaceHash || '',
       session_id: sessionId,
-    }));
+    });
     return true;
   } catch {
     return false;
diff --git a/web/src/lib/desktopNotify.test.js b/web/src/lib/desktopNotify.test.js
index d26f96be5..7d74b160a 100644
--- a/web/src/lib/desktopNotify.test.js
+++ b/web/src/lib/desktopNotify.test.js
@@ -14,6 +14,9 @@ import {
   shouldSuppress,
   truncateForNotification,
   maybeNotify,
+  focusSession,
+  maybeNotifyChannelRequest,
+  buildChannelRequestPayload,
   noteHostWindowFocus,
   isHostWindowFocused,
 } from './desktopNotify.js';
@@ -286,3 +289,51 @@ run('maybeNotify 桥可用 + 窗口聚焦 → 不投递完成通知', () => {
   assert.equal(called, 0);
   global.window = prev;
 });
+
+// 消息通道(QQ / Telegram)的新配对请求:窗口失焦时弹系统通知,聚焦时由页面内 toast 提示;
+// 总开关关闭时一律不弹。
+run('buildChannelRequestPayload 写明平台、来源与处理入口', () => {
+  const payload = buildChannelRequestPayload({ platform: 'qq', id: 'r1', kind: 'user', name: 'Alice', label: 'QQ 私聊' });
+  assert.equal(payload.title, 'QQ 配对请求');
+  assert.equal(payload.body, 'Alice(QQ 私聊)请求使用 ACECode,到设置 > 消息通道处理');
+  assert.equal(payload.session_id, '');
+  assert.ok(payload.id.startsWith('channel-qq-r1-'));
+  const group = buildChannelRequestPayload({ platform: 'telegram', id: 'r2', kind: 'group', name: '' });
+  assert.equal(group.title, 'Telegram 配对请求');
+  assert.ok(group.body.startsWith('一个群请求使用'));
+});
+
+run('shouldSuppress: 配对请求只在窗口失焦且总开关开启时弹', () => {
+  const payload = buildChannelRequestPayload({ platform: 'telegram', id: 'r1', name: 'Bob' });
+  assert.equal(shouldSuppress(payload, false, null), false);
+  assert.equal(shouldSuppress(payload, true, null), true);
+  assert.equal(shouldSuppress(payload, false, { enabled: false }), true);
+});
+
+run('maybeNotifyChannelRequest 失焦时经桥投递,聚焦时不投递', () => {
+  const prev = global.window;
+  const captured = [];
+  global.window = { aceDesktop_notify: (json) => { captured.push(JSON.parse(json)); } };
+  assert.equal(maybeNotifyChannelRequest({ platform: 'qq', id: 'r9', name: 'Carol' }, { hasFocus: false, cfg: null }), true);
+  assert.equal(maybeNotifyChannelRequest({ platform: 'qq', id: 'r9', name: 'Carol' }, { hasFocus: true, cfg: null }), false);
+  assert.equal(captured.length, 1);
+  assert.equal(captured[0].title, 'QQ 配对请求');
+  global.window = prev;
+});
+
+run('focusSession passes a structured native argument and supports no-workspace sessions', () => {
+  const previous = globalThis.window;
+  let request;
+  globalThis.window = {aceDesktop_focusSession: value => {request = value;}};
+  try {
+    assert.equal(focusSession('', 'office-root'), true);
+    // Native receives the JSON-encoded argument array, whose first item must
+    // be an object rather than a second, nested JSON string.
+    const nativeArgs = JSON.parse(JSON.stringify([request]));
+    assert.deepEqual(nativeArgs, [{workspace_hash:'', session_id:'office-root'}]);
+    assert.equal(focusSession('workspace', ''), false);
+  } finally {
+    if (previous === undefined) delete globalThis.window;
+    else globalThis.window = previous;
+  }
+});
diff --git a/web/src/lib/desktopOffice.test.js b/web/src/lib/desktopOffice.test.js
new file mode 100644
index 000000000..8ed976f29
--- /dev/null
+++ b/web/src/lib/desktopOffice.test.js
@@ -0,0 +1,197 @@
+import assert from 'node:assert/strict';
+import { recentOffices, officeActor, projectDesktopOffice, stableOfficeSeed, fitTail, speechTail } from './desktopOfficeState.js';
+import { createDesktopOfficeController, OFFICE_LIVE_PUBLISH_MS } from './desktopOfficeController.js';
+import { toolActivityVerb, toolIconName, toolIconSvg } from './toolIcons.js';
+import { interfaceIconSvg } from './interfaceIcons.js';
+
+function test(name, fn) {fn(); console.log(`[pass] desktop office: ${name}`);}
+async function check(name, fn) {await fn(); console.log(`[pass] desktop office: ${name}`);}
+const session = (id, overrides = {}) => ({id, active:true, last_user_message_at:'2026-10-06T10:00:00Z', ...overrides});
+const snapshot = (id, overrides = {}) => ({selected:session(id),offices:[session(id)],agents:[session(id)],complete:true,...overrides});
+
+test('recent five depend only on human send time across workspaces', () => {
+  const rows = Array.from({length:7}, (_,i) => session(String(i),{workspace_hash:`w${i%2}`,last_user_message_at:`2026-10-06T10:00:0${i}Z`,updated_at:`2026-10-06T20:00:0${9-i}Z`}));
+  rows.push(session('archived',{archived:true,last_user_message_at:'2099-01-01'}));
+  rows.push(session('child',{parent_session_id:'6',last_user_message_at:'2099-01-01'}));
+  rows.push(session('empty',{last_user_message_at:''}));
+  assert.deepEqual(recentOffices(rows).map(s=>s.id),['6','5','4','3','2']);
+});
+
+test('main sleeps on completion and wakes; workers leave on completion', () => {
+  assert.equal(officeActor(session('root',{last_turn_outcome:'completed'}),'root').state,'sleep');
+  assert.equal(officeActor(session('root',{busy:true,last_turn_outcome:'completed'}),'root').state,'think');
+  assert.equal(officeActor(session('child',{last_turn_outcome:'completed'}),'root').present,false);
+  assert.equal(officeActor(session('child',{busy:true,last_turn_outcome:'completed'}),'root').present,true);
+  assert.equal(officeActor(session('root'),'root').state,'idle');
+});
+
+test('waiting, retry, cancellation and errors are distinct', () => {
+  for(const [phase,expected] of [['permission_waiting','permission'],['question_waiting','question'],['compacting','compact'],['model_retry','retry']]) {
+    assert.equal(officeActor(session('root',{busy:true,activity:{phase}}),'root').state,expected);
+  }
+  assert.equal(officeActor(session('root',{last_turn_outcome:'aborted'}),'root').state,'stopped');
+  assert.equal(officeActor(session('root',{last_turn_outcome:'error'}),'root').state,'error');
+});
+
+test('failed mesh workers with internal input stay visible for the current root turn', () => {
+  const child=session('mesh',{last_user_message_at:'',updated_at:'2026-10-06T10:01:00Z',last_turn_outcome:'error'});
+  assert.equal(projectDesktopOffice(snapshot('root',{agents:[session('root'),child]})).agents.length,2);
+  const newer=session('root',{last_user_message_at:'2026-10-06T10:02:00Z'});
+  assert.equal(projectDesktopOffice({...snapshot('root'),selected:newer,agents:[newer,child]}).agents.length,1);
+});
+
+test('paper thickness follows current context rather than lifetime totals', () => {
+  const base=session('root',{context_window:1000,token_usage:{has_data:true,prompt_tokens:900},session_token_usage:{total_tokens:9000000}});
+  const full=officeActor(base,'root');
+  assert.equal(full.contextRatio,.9);
+  const compacted=officeActor({...base,token_usage:{has_data:true,prompt_tokens:150}},'root');
+  assert.equal(compacted.contextRatio,.15);
+  assert.equal(officeActor(session('root'),'root').contextKnown,false);
+});
+
+test('stable identity and nested mesh children belong to one office with overflow', () => {
+  const agents=[session('root'),...Array.from({length:9},(_,i)=>session(`child${i}`,{parent_session_id:'root',agent_path:`/root/a/child${i}`,busy:true}))];
+  const view=projectDesktopOffice(snapshot('root',{agents}));
+  assert.equal(view.agents.length,10);assert.equal(view.overflow,2);
+  assert.equal(view.agents[0].name,'Maestro');
+  assert.equal(stableOfficeSeed('root'),stableOfficeSeed('root'));
+  assert.notEqual(stableOfficeSeed('root'),stableOfficeSeed('another'));
+  assert.equal(view.agents.find(a=>a.id==='child0').seed,officeActor(agents[1],'root').seed);
+});
+
+test('tool SVG is exactly the shared chat icon source', () => {
+  for(const tool of ['file_read','file_write','file_edit','apply_patch','grep','glob','web_search','bash','spawn_subagent','agent_send_message','AskUserQuestion','TodoWrite','task_complete','vision_analyze','skill_view','mcp__server__tool','unknown']) {
+    const icon=toolIconName(tool);
+    assert.equal(toolIconSvg(tool),interfaceIconSvg(icon,14));
+    assert.match(toolIconSvg(tool),/^<svg/);
+  }
+  assert.equal(toolIconName('file_read'),'OpenFile');
+  assert.equal(toolIconName('mcp__server__tool'),'MCP');
+});
+
+// 正在输出正文:显示「撰写回复」与最新的几个字,Markdown 标点不进气泡。
+test('streaming reply types and shows only its latest words', () => {
+  const actor=officeActor(session('root',{busy:true,activity:{phase:'responding',text:'第一段\n\n## 小标题\n**最后**几个字是这些'}}),'root');
+  assert.equal(actor.state,'type');assert.equal(actor.label,'撰写回复');
+  assert.ok(actor.detail.endsWith('最后几个字是这些'),actor.detail);
+  assert.ok(!/[#*]/.test(actor.detail),actor.detail);
+  assert.equal(actor.tool,'');
+});
+
+// 工具执行:动词 + 调用预览(长路径保留文件名一端);等成员回报单独一种状态。
+test('tool work names the verb and keeps the end of long previews', () => {
+  const read=officeActor(session('root',{busy:true,activity:{phase:'tool_running',tool:'file_read',detail:'src/apps/desktop/some/very/deep/folder/desktop_pet_mac.mm'}}),'root');
+  assert.equal(read.state,'work');assert.equal(read.label,'读取');assert.equal(read.icon,'OpenFile');
+  assert.ok(read.detail.startsWith('…')&&read.detail.endsWith('desktop_pet_mac.mm'),read.detail);
+  assert.equal(officeActor(session('root',{busy:true,activity:{tool:'wait_subagent'}}),'root').state,'wait');
+  assert.equal(officeActor(session('root',{busy:true,activity:{tool:'agent_wait'}}),'root').label,'等成员回报');
+  const planning=officeActor(session('root',{busy:true,activity:{phase:'tool_planning',tool:'file_write'}}),'root');
+  assert.equal(planning.state,'type');assert.equal(planning.label,'准备写入文件');assert.equal(planning.icon,'Save');
+  assert.equal(toolActivityVerb('bash'),'运行命令');assert.equal(toolActivityVerb('mcp__x__y'),'调用 MCP');
+});
+
+// 「适合日常工作」模式的具体进度文案优先;引擎默认的笼统文案不进气泡。
+test('concrete progress titles win over generic engine labels', () => {
+  assert.equal(officeActor(session('root',{busy:true,activity:{phase:'model_waiting',label:'正在等待模型响应'}}),'root').label,'思考中');
+  assert.equal(officeActor(session('root',{busy:true,activity:{phase:'tool_running',tool:'bash',label:'正在调用工具 bash'}}),'root').label,'运行命令');
+  assert.equal(officeActor(session('root',{busy:true,activity:{phase:'tool_running',tool:'grep',label:'正在搜索代码并读取'}}),'root').label,'搜索代码并读取');
+  assert.equal(officeActor(session('root',{busy:true,activity:{phase:'reasoning',label:'正在推理',text:'check the config'}}),'root').detail,'check the config');
+});
+
+// 气泡宽度按半角单位计:汉字算 2,超出时保留末尾并以省略号开头。
+test('bubble text keeps the tail within its width budget', () => {
+  assert.equal(fitTail('abcdef',4),'…cdef');
+  assert.equal(fitTail('一二三四五',6),'…三四五');
+  assert.equal(fitTail('  short  ',28),'short');
+  assert.equal(speechTail('see [docs](http://x.test) `code`'),'see docs code');
+});
+
+// 子会话路径:/root/a/b 的上级是 /root/a,主会话没有上级。
+test('mesh workers know their dispatching parent', () => {
+  assert.equal(officeActor(session('c',{agent_path:'/root/a/b'}),'root').parentPath,'/root/a');
+  assert.equal(officeActor(session('root'),'root').parentPath,'');
+});
+
+function fixture(fetchSnapshot) {
+  const publications=[],retained=new Set(),released=[],timers=new Map(),delays=new Map();let timerId=0;
+  const controller=createDesktopOfficeController({fetchSnapshot,publish:value=>publications.push(value),
+    retainSession:id=>retained.add(id),releaseSession:id=>{retained.delete(id);released.push(id);},
+    schedule:(fn,delay)=>{timers.set(++timerId,fn);delays.set(timerId,delay);return timerId;},cancel:id=>timers.delete(id)});
+  // 只触发指定延迟的计时器(实时文字节流 vs 快照轮询),其余保持挂起。
+  const fire=delay=>{for(const [id,fn] of [...timers]) if(delays.get(id)===delay){timers.delete(id);fn();}};
+  return {controller,publications,retained,released,timers,fire};
+}
+const deferred=()=>{let resolve,reject;const promise=new Promise((a,b)=>{resolve=a;reject=b;});return {promise,resolve,reject};};
+
+await check('manual choice turns follow off and keeps office fixed', async () => {
+  const requests=[];const f=fixture(async ref=>{requests.push(ref.sessionId);return snapshot(ref.sessionId||'recent');});
+  f.controller.setActive({sessionId:'a'});await f.controller.refresh();
+  assert.equal(f.controller.state.follow,true);assert.equal(f.controller.state.selected.sessionId,'a');
+  f.controller.select({session_id:'b'});await f.controller.refresh();
+  f.controller.setActive({sessionId:'c'});await f.controller.refresh();
+  assert.equal(f.controller.state.selected.sessionId,'b');assert.equal(f.controller.state.follow,false);
+  f.controller.setFollow(true);await f.controller.refresh();
+  assert.equal(f.controller.state.selected.sessionId,'c');f.controller.dispose();
+  assert.equal(f.retained.size,0);assert.equal(f.timers.size,0);
+});
+
+await check('late responses cannot replace the new office or leak subscriptions', async () => {
+  const a=deferred(),b=deferred();const f=fixture(ref=>ref.sessionId==='a'?a.promise:b.promise);
+  f.controller.setActive({sessionId:'a'});const old=f.controller.refresh();
+  f.controller.select({sessionId:'b'});const next=f.controller.refresh();
+  b.resolve(snapshot('b'));await next;a.resolve(snapshot('a'));await old;
+  assert.equal(f.controller.state.selected.sessionId,'b');assert.deepEqual([...f.retained],['b']);
+  f.controller.dispose();assert.equal(f.retained.size,0);
+});
+
+await check('disposing with an in-flight response prevents further publication', async () => {
+  const pending=deferred();const f=fixture(()=>pending.promise);
+  const request=f.controller.refresh();f.controller.dispose();const count=f.publications.length;
+  pending.resolve(snapshot('late'));await request;assert.equal(f.publications.length,count);
+  assert.equal(f.retained.size,0);
+});
+
+await check('offline is explicit and reconnect recovers from a fresh snapshot', async () => {
+  let fail=false;const f=fixture(async()=>{if(fail)throw new Error('offline');return snapshot('root');});
+  await f.controller.refresh();fail=true;await f.controller.refresh();assert.equal(f.controller.state.connected,false);
+  fail=false;const releases=f.released.length;f.controller.reconnected();assert.equal(f.released.length,releases);await f.controller.refresh();assert.equal(f.controller.state.connected,true);
+  assert.equal(f.controller.state.selected.sessionId,'root');f.controller.dispose();
+});
+
+await check('completion releases a child while the selected office stays subscribed', async () => {
+  let done=false;const f=fixture(async()=>snapshot('root',{agents:[session('root'),session('child',{busy:!done,last_turn_outcome:done?'completed':''})]}));
+  await f.controller.refresh();assert.equal(f.retained.has('child'),true);
+  done=true;await f.controller.refresh();assert.equal(f.retained.has('child'),false);
+  assert.equal(f.controller.state.agents.some(a=>a.id==='child'),false);
+  assert.equal(f.retained.has('root'),true);f.controller.dispose();
+});
+
+// 流式 token 走 WebSocket 本地叠加:不发额外快照请求,按节流间隔发布;
+// 只认办公室里的成员;快照追上(seq 不再落后)后叠加层让位给服务端状态。
+await check('streamed tokens update the speaker between snapshots without extra requests', async () => {
+  let requests=0,serverActivity={seq:5,busy:true,phase:'model_waiting'};
+  const f=fixture(async()=>{requests++;return snapshot('root',{agents:[session('root',{busy:true,activity:serverActivity})]});});
+  await f.controller.refresh();requests=0;const published=f.publications.length;
+  f.controller.onEvent({type:'token',session_id:'root',seq:6,payload:{text:'你好'}});
+  f.controller.onEvent({type:'token',session_id:'root',seq:7,payload:{text:'世界'}});
+  f.controller.onEvent({type:'token',session_id:'outsider',seq:8,payload:{text:'别人'}});
+  assert.equal(f.publications.length,published,'节流期间不逐 token 发布');
+  f.fire(OFFICE_LIVE_PUBLISH_MS);
+  assert.equal(f.publications.length,published+1);
+  let root=f.publications.at(-1).agents[0];
+  assert.equal(root.state,'type');assert.equal(root.detail,'你好世界');assert.equal(requests,0);
+  // 服务端快照已包含到 seq 7 的正文:以服务端为准,本地叠加被丢弃。
+  serverActivity={seq:7,busy:true,phase:'responding',text:'你好世界'};
+  await f.controller.refresh();
+  root=f.controller.state.agents[0];assert.equal(root.detail,'你好世界');
+  // 叠加层被清掉后,服务端进入工具阶段不会再被旧的正文覆盖。
+  serverActivity={seq:9,busy:true,phase:'tool_running',tool:'bash',detail:'npm test'};
+  await f.controller.refresh();
+  root=f.controller.state.agents[0];assert.equal(root.state,'work');assert.equal(root.detail,'npm test');
+  // 快照之后又来的 token 接在服务端尾巴后面(同一段正文)。
+  serverActivity={seq:10,busy:true,phase:'responding',text:'前半'};
+  await f.controller.refresh();
+  f.controller.onEvent({type:'token',session_id:'root',seq:11,payload:{text:'后半'}});
+  assert.equal(f.controller.state.agents[0].detail,'前半后半');
+  f.controller.dispose();assert.equal(f.timers.size,0);
+});
diff --git a/web/src/lib/desktopOfficeController.js b/web/src/lib/desktopOfficeController.js
new file mode 100644
index 000000000..037a8c8c4
--- /dev/null
+++ b/web/src/lib/desktopOfficeController.js
@@ -0,0 +1,136 @@
+import { officeSessionRef, projectDesktopOffice } from './desktopOfficeState.js';
+
+// Streaming text reaches the office a few times per second, not per token.
+export const OFFICE_LIVE_PUBLISH_MS = 150;
+const LIVE_TEXT_CHARS = 400;
+
+// One App-owned controller; every asynchronous response belongs to a selection
+// generation. Inject IO, timers and publishing so lifecycle races are testable.
+export function createDesktopOfficeController({
+  fetchSnapshot, fetchModel, publish, retainSession = () => {}, releaseSession = () => {},
+  schedule = setTimeout, cancel = clearTimeout, initial = {},
+} = {}) {
+  let follow = initial.follow !== false, active = {}, selected = initial.selected || {};
+  let generation = 0, disposed = false, timer = null, timerDelay = Infinity, request = null;
+  let snapshot = {}, connected = true, queued = false, liveTimer = null;
+  const retained = new Set();
+  // session id -> {phase, seq, fromSeq, text}: token/reasoning events newer than the snapshot.
+  const live = new Map();
+  const project = () => projectDesktopOffice(snapshot, {follow, connected, live});
+  const emit = () => !disposed && publish(project());
+  const emitLive = () => {
+    if (disposed || liveTimer !== null) return;
+    liveTimer = schedule(() => {liveTimer = null; emit();}, OFFICE_LIVE_PUBLISH_MS);
+  };
+  const tracked = id => (snapshot.agents || []).some(session => session.id === id);
+  const pruneLive = () => {
+    for (const [id, entry] of live) {
+      const session = (snapshot.agents || []).find(item => item.id === id);
+      if (!session || entry.seq <= (Number(session.activity?.seq) || 0)) live.delete(id);
+    }
+  };
+  const syncRetained = () => {
+    const wanted = new Set();
+    for (const session of [...(snapshot.offices || []), ...(snapshot.agents || [])]) {
+      if (session.active && (session.id === snapshot.selected?.id || session.busy || session.status === 'running')) wanted.add(session.id);
+    }
+    for (const id of retained) if (!wanted.has(id)) {releaseSession(id); retained.delete(id);}
+    for (const id of wanted) if (!retained.has(id)) {retainSession(id); retained.add(id);}
+  };
+  function later(delay) {
+    if (disposed) return;
+    if (timer !== null && timerDelay <= delay) return;
+    if (timer !== null) cancel(timer);
+    timerDelay = delay;
+    timer = schedule(() => {timer = null; timerDelay = Infinity; void refresh();}, delay);
+  }
+  async function refresh() {
+    if (disposed) return;
+    if (request) {queued = true; return;}
+    const version = generation, controller = new AbortController();
+    request = controller;
+    try {
+      const wanted = follow && active.sessionId ? active : selected;
+      const next = await fetchSnapshot(wanted, {signal: controller.signal});
+      if (disposed || version !== generation || controller.signal.aborted) return;
+      // Dormant sessions need their model window; never use lifetime token totals.
+      if (next.selected && !next.selected.context_window && fetchModel) {
+        try {
+          const model = await fetchModel(next.selected.id, next.selected.workspace_hash || '');
+          if (disposed || version !== generation || controller.signal.aborted) return;
+          const limit = Number(model?.context_window ?? model?.contextWindow) || 0;
+          next.selected.context_window = limit;
+          for (const agent of next.agents || []) if (agent.id === next.selected.id) agent.context_window = limit;
+        } catch { /* Unknown context remains unknown until a later snapshot. */ }
+      }
+      snapshot = next; connected = true;
+      if (next.selected) selected = officeSessionRef(next.selected);
+      pruneLive(); syncRetained(); emit();
+    } catch (error) {
+      if (disposed || version !== generation || controller.signal.aborted) return;
+      if (error?.status === 404) {
+        selected = {}; snapshot = {...snapshot, selected:null, agents:[], offices:error.body?.offices || snapshot.offices || []};
+        if (follow) active = {};
+        live.clear(); syncRetained();
+      } else connected = false;
+      emit();
+    } finally {
+      if (request === controller) request = null;
+      if (!disposed && version === generation) {
+        const delay = queued ? 100 : snapshot.complete === false ? 500 : 3000;
+        queued = false; later(delay);
+      }
+    }
+  }
+  function change() {
+    generation++;
+    request?.abort(); request = null; queued = false;
+    snapshot = {...snapshot, selected:null, agents:[]};
+    live.clear(); syncRetained(); emit(); later(0);
+  }
+  function streamed(message) {
+    const id = String(message.session_id || '');
+    if (!id || !tracked(id)) return;
+    const phase = message.type === 'token' ? 'responding' : 'reasoning';
+    const seq = Number(message.seq) || 0, piece = String(message.payload?.text || '');
+    const prev = live.get(id);
+    live.set(id, prev && prev.phase === phase
+      ? {...prev, seq: Math.max(seq, prev.seq), text: (prev.text + piece).slice(-LIVE_TEXT_CHARS)}
+      : {phase, seq, fromSeq: seq, text: piece.slice(-LIVE_TEXT_CHARS)});
+    emitLive();
+  }
+  return {
+    start() {later(0);},
+    refresh,
+    setActive(value) {
+      const next = officeSessionRef(value);
+      if (next.sessionId === active.sessionId && next.workspaceHash === active.workspaceHash) return;
+      active = next;
+      if (follow && next.sessionId) change();
+    },
+    select(value) {selected = officeSessionRef(value); follow = false; change();},
+    setFollow(value) {follow = !!value; change();},
+    onEvent(message) {
+      if (message.type === 'token' || message.type === 'reasoning') {streamed(message); return;}
+      if (message.type === 'tool_update') return;
+      if (request) queued = true;
+      else later(100);
+    },
+    disconnected() {connected = false; emit(); later(500);},
+    reconnected() {
+      generation++; request?.abort(); request = null; queued = false;
+      // Preserve retained subscriptions while recovering: releasing them from
+      // an onopen callback would close/reopen an office-only connection forever.
+      later(0);
+    },
+    get state() {return project();},
+    dispose() {
+      disposed = true; generation++; request?.abort(); request = null;
+      if (timer !== null) cancel(timer);
+      if (liveTimer !== null) cancel(liveTimer);
+      timer = null; liveTimer = null; live.clear();
+      for (const id of retained) releaseSession(id);
+      retained.clear();
+    },
+  };
+}
diff --git a/web/src/lib/desktopOfficeState.js b/web/src/lib/desktopOfficeState.js
new file mode 100644
index 000000000..a6f076806
--- /dev/null
+++ b/web/src/lib/desktopOfficeState.js
@@ -0,0 +1,131 @@
+import { normalizeTokenBudget } from './tokenBudget.js';
+import { toolActivityVerb, toolIconName, toolIconSvg } from './toolIcons.js';
+
+export const OFFICE_LIMIT = 5;
+export const OFFICE_WORKER_SEATS = 7;
+const idOf = value => String(value?.id || value?.sessionId || value?.session_id || '');
+export const officeSessionRef = value => ({
+  sessionId: idOf(value),
+  workspaceHash: String(value?.workspaceHash || value?.workspace_hash || ''),
+});
+export function stableOfficeSeed(value) {
+  let hash = 2166136261;
+  for (const c of String(value)) hash = Math.imul(hash ^ c.codePointAt(0), 16777619);
+  return hash >>> 0;
+}
+export function recentOffices(sessions = []) {
+  const unique = new Map();
+  for (const session of sessions) {
+    if (!idOf(session) || session.archived || session.parent_session_id || !session.last_user_message_at) continue;
+    unique.set(idOf(session), session);
+  }
+  return [...unique.values()].sort((a,b) =>
+    String(b.last_user_message_at).localeCompare(String(a.last_user_message_at)) || idOf(a).localeCompare(idOf(b)))
+    .slice(0, OFFICE_LIMIT);
+}
+
+// Bubble text is measured in half-width units: CJK and full-width glyphs count twice.
+const charUnits = ch => (/[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦]/.test(ch)
+  || ch.codePointAt(0) > 0xffff ? 2 : 1);
+
+// Keep the end of a line (latest words of a reply, file name of a path).
+export function fitTail(text, units = 28) {
+  const chars = [...String(text || '').replace(/\s+/g, ' ').trim()];
+  let width = 0, start = chars.length;
+  while (start > 0 && width + charUnits(chars[start - 1]) <= units) width += charUnits(chars[--start]);
+  return start > 0 ? '…' + chars.slice(start).join('') : chars.join('');
+}
+
+// Last visible words of streamed Markdown, without the formatting punctuation.
+export function speechTail(text, units = 28) {
+  const plain = String(text || '')
+    .replace(/```[\w-]*/g, ' ')
+    .replace(/[`*#]+/g, '')
+    .replace(/^\s*>\s?/gm, '')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
+  return fitTail(plain, units);
+}
+
+const GENERIC_LABEL = /^正在(?:等待模型响应|推理|准备工具调用|准备调用\s|调用工具\s)/;
+const WAIT_TOOLS = new Set(['wait_subagent', 'agent_wait']);
+
+export function officeActor(session, rootId) {
+  const id = idOf(session), root = id === rootId, a = session.activity || {};
+  const busy = session.busy === true || session.status === 'running' || a.busy === true;
+  const outcome = String(a.outcome || session.last_turn_outcome || '');
+  const phase = String(a.phase || ''), tool = String(a.tool || '');
+  const raw = String(a.label || '');
+  // Concrete progress titles (work mode) are richer than generic engine labels.
+  const concrete = raw && !GENERIC_LABEL.test(raw) ? raw.replace(/^正在/, '') : '';
+  let state = 'idle', label = '待命', detail = '';
+  if (busy) {
+    if (phase === 'permission_waiting') {
+      state = 'permission'; label = '等待授权'; detail = tool ? toolActivityVerb(tool) : '';
+    } else if (phase === 'question_waiting') { state = 'question'; label = '等待回答'; }
+    else if (phase === 'compacting' || phase === 'context_repair') { state = 'compact'; label = '整理上下文'; }
+    else if (phase === 'model_retry') { state = 'retry'; label = '正在重试'; }
+    else if (phase === 'responding') { state = 'type'; label = '撰写回复'; detail = speechTail(a.text); }
+    else if (phase === 'tool_planning') {
+      state = 'type'; label = tool ? '准备' + toolActivityVerb(tool) : '准备调用工具';
+    } else if (tool || phase === 'tool_running') {
+      state = WAIT_TOOLS.has(tool.toLowerCase()) ? 'wait' : 'work';
+      label = concrete || (tool ? toolActivityVerb(tool) : '调用工具');
+      detail = fitTail(a.detail, 30);
+    } else if (phase === 'reasoning') { state = 'think'; label = concrete || '思考中'; detail = speechTail(a.text, 24); }
+    else { state = 'think'; label = concrete || '思考中'; }
+  } else if (outcome === 'completed') { state = root ? 'sleep' : 'done'; label = root ? 'zzz' : '已完成'; }
+  else if (outcome === 'error' || outcome === 'errored') { state = 'error'; label = '执行失败'; }
+  else if (outcome === 'aborted' || outcome === 'interrupted') { state = 'stopped'; label = '已停止'; }
+  const context = normalizeTokenBudget({usage: session.token_usage, contextWindow: session.context_window});
+  const shownTool = state === 'work' || state === 'wait' || state === 'permission' || phase === 'tool_planning' ? tool : '';
+  const path = String(session.agent_path || (root ? '/root' : ''));
+  return {
+    id, root, name: root ? 'Maestro' : String(session.title || session.agent_path?.split('/').pop() || session.summary || 'Agent'),
+    path, parentPath: path.includes('/', 1) ? path.slice(0, path.lastIndexOf('/')) : '',
+    state, label, detail, tool: shownTool, icon: shownTool ? toolIconName(shownTool) : '',
+    iconSvg: shownTool ? toolIconSvg(shownTool) : '', busy,
+    seed: stableOfficeSeed(id), contextKnown: context.known,
+    contextRatio: context.usedRatio, contextTokens: context.usedTokens, contextLimit: context.limitTokens,
+    compactId: String(a.compact_id || ''), seq: Number(a.seq) || 0,
+    transfers: Array.isArray(a.transfers) ? a.transfers : [],
+    // Completed workers leave immediately. Failed/stopped workers remain visible
+    // for their current parent turn, so they cannot masquerade as success.
+    present: root || busy || state === 'error' || state === 'stopped',
+    lastActivityAt: String(session.updated_at || session.last_user_message_at || ''),
+  };
+}
+
+// Streaming tokens arrive over the WebSocket faster than snapshots. The overlay
+// is newer than the snapshot only while its event sequence is ahead of it.
+export function withLiveActivity(session, entry) {
+  const a = session.activity || {};
+  const seq = Number(a.seq) || 0;
+  if (!entry || !(entry.seq > seq)) return session;
+  const continues = a.phase === entry.phase && entry.fromSeq > seq;
+  return {...session, busy: true, activity: {...a, busy: true, phase: entry.phase,
+    text: (continues ? String(a.text || '') : '') + entry.text, tool: '', detail: '', seq: entry.seq}};
+}
+
+export function projectDesktopOffice(snapshot = {}, { follow = true, connected = true, live = null } = {}) {
+  const selected = snapshot.selected || null;
+  const rootId = idOf(selected);
+  const rootTime = String(selected?.last_user_message_at || '');
+  const sessions = (snapshot.agents || []).map(session => withLiveActivity(session, live?.get(idOf(session))));
+  const actors = sessions.map(session => officeActor(session, rootId));
+  const agents = actors.filter(actor => actor.present && (actor.root || actor.busy || !rootTime || actor.lastActivityAt >= rootTime));
+  agents.sort((a,b) => Number(b.root) - Number(a.root) || a.id.localeCompare(b.id));
+  return {
+    version: 1, follow, connected, complete: snapshot.complete !== false,
+    offices: recentOffices(snapshot.offices).map(session => ({
+      ...officeSessionRef(session), title: String(session.title || session.summary || '未命名会话'),
+      busy: session.busy === true || session.status === 'running',
+      lastUserMessageAt: session.last_user_message_at,
+      workspaceName: String(session.workspace_name || ''),
+    })),
+    selected: selected ? { ...officeSessionRef(selected), title: String(selected.title || selected.summary || '未命名会话') } : null,
+    seed: stableOfficeSeed(rootId || 'empty-office'),
+    agents,
+    completed: actors.filter(actor => !actor.root && actor.state === 'done').map(actor => actor.id),
+    overflow: Math.max(0, agents.length - OFFICE_WORKER_SEATS - 1),
+  };
+}
diff --git a/web/src/lib/richComposerKeyboard.test.js b/web/src/lib/richComposerKeyboard.test.js
index 1a47a2075..e07cd6b83 100644
--- a/web/src/lib/richComposerKeyboard.test.js
+++ b/web/src/lib/richComposerKeyboard.test.js
@@ -52,6 +52,9 @@ function fixture({ kind = 'path', key = 'Backspace', selected = false } = {}) {
     parentCalls: 0,
     submissions: 0,
     removed: [],
+    adoptCalls: 0,
+    // 模拟用户看到的 DOM 光标;为 null 表示 DOM 与 Slate 一致、无需采纳。
+    domCaret: null,
   };
   const context = vm.createContext({ ...composerModel, ...contentModel, ...composerSelection, Editor, Range, Transforms, HistoryEditor, COMPOSER_CLIPBOARD_TYPE: 'application/x-acecode-composer-content' });
   const editor = withHistory(loadFunction('withComposerInlineTags', context)(createEditor()));
@@ -75,6 +78,12 @@ function fixture({ kind = 'path', key = 'Backspace', selected = false } = {}) {
     onKeyDown: () => { state.parentCalls += 1; },
     onSubmit: () => { state.submissions += 1; },
     onRemoveAttachment: (attachmentKey) => state.removed.push(attachmentKey),
+    adoptDomSelection: () => {
+      state.adoptCalls += 1;
+      if (!state.domCaret) return false;
+      Transforms.select(editor, state.domCaret);
+      return true;
+    },
     deleteAdjacentTag: loadFunction('deleteAdjacentTag', context),
     removeAttachmentReference: loadFunction('removeAttachmentReference', context),
     deleteSelectedPlainText: loadFunction('deleteSelectedPlainText', context),
@@ -103,6 +112,8 @@ function assertImeOwnsKey(test) {
   assert.deepEqual(test.state.removed, [], 'IME key must not remove attachments');
   assert.equal(test.state.parentCalls, 0, 'IME key must not invoke parent history navigation');
   assert.equal(test.state.submissions, 0, 'IME key must not submit');
+  // 合成期间 DOM 里有未提交的拼音,此时的 DOM 选区不能写回 Slate(由 compositionstart 负责)。
+  assert.equal(test.state.adoptCalls, 0, 'IME key must not adopt the DOM selection');
   assert.equal(handled, true, 'Slate keyboard fallthrough must be skipped');
   assert.equal(test.event.defaultPrevented, false, 'native IME default must remain available');
   assert.equal(test.event.propagationStopped, false);
@@ -358,6 +369,25 @@ for (const directory of ['@src/', '@"my docs/"']) run('entering a directory keep
   assert.equal(changed.parts.some((part) => part.type === 'path'), false);
 });
 
+// 场景:Slate 的 selectionchange 同步被卡住(例如拖拽结束事件丢失),editor.selection 停在
+// 行首(标签之前),用户看到的光标却在 "@main.js " 末尾。按普通 Backspace。
+// 期望:handleKeyDown 先采纳 DOM 光标,父组件 onKeyDown 读到的是采纳后的选区,退格按用户
+// 看到的位置删除前面的标签。
+// 修复前:退格在过期的行首选区上执行,标签不删(同一根因下输入法文字也会落到过期位置)。
+run('ordinary keys adopt the visible DOM caret before parent and deletion handlers read the selection', () => {
+  const test = fixture({ kind: 'path', key: 'Backspace' });
+  const visibleCaret = structuredClone(test.editor.selection);
+  Transforms.select(test.editor, Editor.start(test.editor, []));
+  test.state.domCaret = visibleCaret;
+  let parentSelection = null;
+  test.context.onKeyDown = () => { parentSelection = structuredClone(test.editor.selection); };
+  test.handleKeyDown(test.event);
+  assert.equal(test.state.adoptCalls, 1);
+  assert.deepEqual(parentSelection, visibleCaret);
+  assert.equal(test.event.defaultPrevented, true);
+  assert.equal(composerModel.composerTextFromDocument(test.editor.children), '');
+});
+
 run('queue editor lets Enter reach Slate when submitOnEnter is disabled', () => {
   const test = fixture({ key: 'Enter' });
   test.context.submitOnEnter = false;
diff --git a/web/src/lib/runTests.js b/web/src/lib/runTests.js
index 41556c201..51391e034 100644
--- a/web/src/lib/runTests.js
+++ b/web/src/lib/runTests.js
@@ -1,3 +1,4 @@
+import './desktopOffice.test.js';
 import './questionPicker.test.js';
 import './turnCancellation.test.js';
 import './modelReasoningSync.test.js';
@@ -97,6 +98,7 @@ import './composerLifecycle.test.js';
 import './composerDraftCallbacks.test.js';
 import './richComposerKeyboard.test.js';
 import './richComposerFocus.test.js';
+import './composerDomSelection.test.js';
 import './slateComposerArchitecture.test.js';
 import './chatFileDropFeedbackArchitecture.test.js';
 import './consoleDropPaths.test.js';
@@ -237,6 +239,7 @@ import './fileTypeIcons.test.js';
 import './builtinCommandRouting.test.js';
 import './slashCommandWorkspace.test.js';
 import './desktopNotify.test.js';
+import './channelsSettings.test.js';
 import './subagentCompletionNotificationArchitecture.test.js';
 import './desktopNotificationMonitor.test.js';
 import './desktopNotificationAuthorization.test.js';
diff --git a/web/src/lib/settingsNavigation.js b/web/src/lib/settingsNavigation.js
index a5b9a59a9..19541f7c0 100644
--- a/web/src/lib/settingsNavigation.js
+++ b/web/src/lib/settingsNavigation.js
@@ -17,6 +17,7 @@ export const SETTINGS_NAV_GROUPS = [
       { key: 'skills', label: '技能', icon: 'lightbulb' },
       { key: 'mcp', label: 'MCP 服务器', icon: 'mcp' },
       { key: 'connectors', label: '插件', icon: 'extension' },
+      { key: 'channels', label: '消息通道', icon: 'chat' },
     ],
   },
   {
diff --git a/web/src/lib/settingsNavigation.test.js b/web/src/lib/settingsNavigation.test.js
index 057d2b29c..633681646 100644
--- a/web/src/lib/settingsNavigation.test.js
+++ b/web/src/lib/settingsNavigation.test.js
@@ -32,7 +32,7 @@ test('settings navigation uses the confirmed Codex-style groups', () => {
       {
         key: 'integrations',
         label: '集成',
-        items: ['技能', 'MCP 服务器', '插件'],
+        items: ['技能', 'MCP 服务器', '插件', '消息通道'],
       },
       {
         key: 'coding',
@@ -64,6 +64,7 @@ test('flattened settings routes remain unique and complete', () => {
     'skills',
     'mcp',
     'connectors',
+    'channels',
     'models',
     'tools',
     'hooks',
diff --git a/web/src/lib/settingsSearch.js b/web/src/lib/settingsSearch.js
index ffa2a5946..45f365cc7 100644
--- a/web/src/lib/settingsSearch.js
+++ b/web/src/lib/settingsSearch.js
@@ -33,6 +33,13 @@ export function settingsSearchEntries(developerModeUnlocked = false) {
     ['personalization', '摘要模型', 'memory summary model 记忆摘要模型'],
     ['skills', '工作区 Skill 目录', 'workspace skill directory'],
     ['mcp', '服务器配置', 'mcp server config json'],
+    ['channels', 'QQ 机器人', 'qq bot 机器人 扫码 appid appsecret im channel 消息通道 连接 取消连接 owner approve revoke 机主 授权 审批 撤销'],
+    ['channels', '微信', 'weixin wechat 微信 扫码 ilink 机器人 im channel 消息通道 连接 取消连接'],
+    ['channels', '飞书', 'feishu lark 飞书 app id app secret 长连接 机器人 im channel 消息通道 连接 取消连接'],
+    ['channels', '钉钉', 'dingtalk 钉钉 stream client id client secret 机器人 im channel 消息通道 连接 取消连接'],
+    ['channels', 'Telegram', 'telegram bot token botfather 机器人 机主 im channel 消息通道 连接 取消连接 owner approve revoke 授权 审批 撤销'],
+    ['channels', 'Discord', 'discord bot token 机器人 服务器 im channel 消息通道 连接 取消连接'],
+    ['channels', 'LINE', 'line messaging api channel secret webhook cloudflared 机器人 im channel 消息通道 连接 取消连接'],
     ['tools', '内置工具', 'builtin tools'],
     ['tools', 'Agent 浏览器', 'agent browser'],
     ['tools', '电脑操控（实验性）', 'computer use experimental windows macos accessibility screen recording desktop mouse keyboard screenshot pointer cursor style theme color ace plain 指针 样式 主题色'],
diff --git a/web/src/lib/toolIcons.js b/web/src/lib/toolIcons.js
new file mode 100644
index 000000000..728563e6f
--- /dev/null
+++ b/web/src/lib/toolIcons.js
@@ -0,0 +1,46 @@
+import { interfaceIconSvg } from './interfaceIcons.js';
+
+const GROUPS = [
+  ['OpenFile', ['file_read', 'read_file', 'read', 'list_dir', 'ls', 'read_resource']],
+  ['Save', ['file_write', 'write_file', 'write']],
+  ['Edit', ['file_edit', 'edit_file', 'edit', 'apply_patch', 'multiedit']],
+  ['Search', ['grep', 'file_search', 'glob', 'search_files', 'find_files']],
+  ['BrowserGlobe', ['web_search', 'web_fetch', 'fetch', 'browse', 'open_url']],
+  ['TerminalReadWrite', ['bash', 'shell', 'exec_command', 'execute_command', 'write_stdin']],
+  ['Embedding', ['spawn_subagent', 'wait_subagent', 'agent_spawn', 'agent_wait', 'agent_list', 'agent_send_message', 'agent_followup_task', 'agent_interrupt']],
+  ['StatusHelp', ['askuserquestion', 'ask_user_question']],
+  ['List', ['todowrite', 'todo_write', 'todo_read']],
+  ['StatusOK', ['task_complete']],
+  ['Eye', ['vision_analyze', 'show_image', 'view_image']],
+  ['Extension', ['skill', 'skill_view', 'skills_list']],
+];
+const BY_TOOL = new Map(GROUPS.flatMap(([icon, names]) => names.map(name => [name, icon])));
+const LEGACY = new Map([['R','OpenFile'],['W','Save'],['E','Edit'],['S','Search'],['$','TerminalReadWrite'],['*','Tool'],['D','StatusOK'],['!','StatusWarning']]);
+
+// One mapping and SVG source for chat, background tasks and the native office.
+export function toolIconName(tool = '', summaryIcon = '') {
+  const name = String(tool).toLowerCase().replace(/^functions\./, '');
+  if (name.startsWith('mcp__') || name.startsWith('mcp:')) return 'MCP';
+  return BY_TOOL.get(name) || LEGACY.get(summaryIcon) || 'Tool';
+}
+
+export function toolIconSvg(tool = '', summaryIcon = '') {
+  return interfaceIconSvg(toolIconName(tool, summaryIcon), 14);
+}
+
+// Short present-tense verbs for the desktop office speech bubbles.
+const VERB_BY_ICON = new Map([
+  ['OpenFile', '读取'], ['Save', '写入文件'], ['Edit', '修改代码'], ['Search', '搜索代码'],
+  ['BrowserGlobe', '查阅网页'], ['TerminalReadWrite', '运行命令'], ['Embedding', '协作'],
+  ['StatusHelp', '提问'], ['List', '更新待办'], ['StatusOK', '收尾'], ['Eye', '看图'],
+  ['Extension', '使用技能'], ['MCP', '调用 MCP'], ['Tool', '调用工具'],
+]);
+const VERB_BY_TOOL = new Map([
+  ['spawn_subagent', '派发任务'], ['agent_spawn', '派发任务'], ['wait_subagent', '等成员回报'],
+  ['agent_wait', '等成员回报'], ['agent_send_message', '发消息'], ['agent_followup_task', '追加任务'],
+  ['agent_interrupt', '叫停成员'], ['agent_list', '查看成员'],
+]);
+export function toolActivityVerb(tool = '') {
+  const name = String(tool).toLowerCase().replace(/^functions\./, '');
+  return VERB_BY_TOOL.get(name) || VERB_BY_ICON.get(toolIconName(tool)) || '调用工具';
+}
diff --git a/web/src/lib/useDesktopOffice.js b/web/src/lib/useDesktopOffice.js
new file mode 100644
index 000000000..b135d8968
--- /dev/null
+++ b/web/src/lib/useDesktopOffice.js
@@ -0,0 +1,56 @@
+import { useEffect, useRef } from 'react';
+import { api } from './api.js';
+import { connection } from './connection.js';
+import { focusSession } from './desktopNotify.js';
+import { createDesktopOfficeController } from './desktopOfficeController.js';
+
+export function useDesktopOffice(activeRef) {
+  const current = useRef(activeRef);
+  current.current = activeRef;
+  const controllerRef = useRef(null);
+  useEffect(() => {
+    if (typeof window.aceDesktop_updateOffice !== 'function') return undefined;
+    let disposed = false, controller = null;
+    const onMessage = event => controller?.onEvent(event.detail || {});
+    const onOpen = () => controller?.reconnected();
+    const onDisconnect = () => controller?.disconnected();
+    const onAction = event => {
+      const action = event.detail || {};
+      if (action.type === 'select') controller?.select(action);
+      else if (action.type === 'follow') controller?.setFollow(action.follow);
+      else if (action.type === 'open') focusSession(action.workspace_hash, action.session_id);
+    };
+    const start = async () => {
+      let initial = {};
+      try {
+        const value = await window.aceDesktop_getOfficeState?.();
+        initial = typeof value === 'string' ? JSON.parse(value) : value || {};
+      } catch {}
+      if (disposed) return;
+      controller = createDesktopOfficeController({
+        initial, fetchSnapshot: api.getDesktopOffice, fetchModel: api.getSessionModel,
+        publish: state => {
+          try {Promise.resolve(window.aceDesktop_updateOffice(JSON.stringify(state))).catch(() => {});} catch {}
+        },
+        retainSession: id => connection.retainSession(id),
+        releaseSession: id => connection.releaseSession(id),
+      });
+      controllerRef.current = controller;
+      controller.setActive(current.current);
+      controller.start();
+    };
+    connection.addEventListener('message', onMessage);
+    connection.addEventListener('open', onOpen);
+    connection.addEventListener('disconnect', onDisconnect);
+    window.addEventListener('ace-desktop-office-action', onAction);
+    void start();
+    return () => {
+      disposed = true; controller?.dispose(); controllerRef.current = null;
+      connection.removeEventListener('message', onMessage);
+      connection.removeEventListener('open', onOpen);
+      connection.removeEventListener('disconnect', onDisconnect);
+      window.removeEventListener('ace-desktop-office-action', onAction);
+    };
+  }, []);
+  useEffect(() => {controllerRef.current?.setActive(activeRef);}, [activeRef]);
+}
diff --git a/web/src/styles/globals.css b/web/src/styles/globals.css
index 85e40bcc8..3652c5234 100644
--- a/web/src/styles/globals.css
+++ b/web/src/styles/globals.css
@@ -4159,6 +4159,7 @@ a.ace-thread-link:focus-visible {
 }
 
 .ace-chat-tail-progress {
+  --ace-chat-tail-dot-lift: -3px;
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -4173,14 +4174,15 @@ a.ace-thread-link:focus-visible {
   background: currentColor;
   animation: ace-chat-tail-dot-hop 1.2s ease-in-out infinite;
 }
-.ace-chat-tail-progress > span:nth-child(2) { animation-delay: .2s; }
-.ace-chat-tail-progress > span:nth-child(3) { animation-delay: .4s; }
+.ace-chat-tail-progress > span:nth-child(2) { animation-delay: .4s; }
+.ace-chat-tail-progress > span:nth-child(3) { animation-delay: .8s; }
 @keyframes ace-chat-tail-dot-hop {
-  0%, 16.667%, 100% { transform: translateY(0); }
-  8.333% { transform: translateY(-3px); }
+  0%, 33.333%, 100% { transform: translateY(0); }
+  16.667% { transform: translateY(var(--ace-chat-tail-dot-lift)); }
 }
 @media (prefers-reduced-motion: reduce) {
-  .ace-chat-tail-progress > span { animation: none; }
+  /* Keep the live-work signal visible without the full bounce amplitude. */
+  .ace-chat-tail-progress { --ace-chat-tail-dot-lift: -1.5px; }
 }
 
 /* hover actions on chat messages (复制 / 分叉) */