@qzsy/dsh-bridge 0.0.0-stage → 2.18.0

package/CHANGELOG.md

@@ -0,0 +1,1107 @@
+# 更新日志 (Changelog)
+
+所有关键版本的更新历史均记录于此。
+
+---
+
+## [v2.17.5] - 2026-10-24
+
+> 补丁版：修复两个真机上发现的交互缺陷，并调整平台面板顺序。
+
+### 🐛 修复
+
+- **「本轮改动」摘要从未显示**：宿主的 `workspace/changes` 是「先同步广播、后登记摘要」，我们的回调先执行、同步读取必然拿不到数据。改为「延后读取 + 有界重试」（最多 4 次），读不到时静默跳过、不阻塞主链路。四个平台（QQ / 飞书 / 微信 / Telegram）共用该逻辑，一并修复。
+- **点击按钮误弹「请勿重复操作」**：原先把所有「无对应待处理项」的按钮回调都应答成 `code=3`（平台语义为*重复操作*）。已按官方应答码语义修正：成功 `0`、操作失败 `1`、无权限 `4`；并为网关离线、非白名单等提前返回路径补上应答（否则客户端会一直 loading）。
+
+### 💄 界面
+
+- **平台面板顺序调整**：QQ 移至第一位并标记「推荐」，飞书不再标记推荐。
+
+### ✅ 验证
+
+- 按钮交互与卡片渲染已在真实 QQ 客户端验证通过（多选项、推荐项星标、长文本、点击回传均正常）。
+- 全量测试 848 项通过，eslint 0 error。
+
+## [v2.17.4] - 2026-10-24
+
+> **v2.17 系列的汇总版**。v2.17.0 引入了 QQ 官方 SDK 化等多项新能力，随后 v2.17.1–3 连续修复了发布门禁阻塞项与代码扫描告警；由于升级提示只展示最新版本，本条目把**本系列的全部新增能力**汇总在此，便于了解这次更新到底带来了什么。
+
+### ✨ 本系列新增能力（源自 v2.17.0）
+
+- **QQ 对接全面替换为腾讯官方 SDK**（与飞书走官方 Channel SDK 同模式）：删除自研协议栈，长连接/RESUME/按关闭码重连、access_token 管理、事件归一化、引用解析、去重限流、富媒体分片上传（≥5MB 自动）、C2C `stream_messages` 流式全部由官方 `@tencent-connect/qqbot-nodejs` 实现。
+- **手机 QQ 扫码绑定机器人**：设置页点「扫码绑定机器人」→ 手机扫码 → 平台官方接口回传 AppID/AppSecret 并自动连接；二维码过期自动刷新。该能力依赖 `@tencent-connect/qqbot-connector`（UNLICENSED，故列为 optionalDependency），未安装时可手动填写凭证，功能等价。
+- **QQ 按钮式交互**：审批改为「✅ 允许一次 / ❌ 拒绝」回调按钮（单聊限发起者、群聊限本群、超时自动拒绝）；`ask_user_question` 单问单选改为按钮卡片。
+- **QQ 体验增强**：被动回复限额按 scope 记账（单聊 4 / 群聊 5）并在超限/过期时自动降级主动消息；语音消息优先使用 QQ 自带转文字；群聊与引用消息补充发送者昵称与上下文。
+- **平台面板调整**：顺序改为 飞书 → QQ → 微信 → Telegram，QQ 标记「推荐」。
+- **新增「单聊流式输出」开关**：可在设置页关闭逐段输出（修复了该配置此前被白名单构造丢弃、开关无效的问题）。
+
+### 🔒 安全修复
+
+- **2 处 ReDoS 高危**（CodeQL `js/polynomial-redos`）：尾斜杠正则在大输入上呈多项式复杂度，实测 20 万字符需约 37 秒；改为线性实现后亚毫秒级。
+- **附件临时文件不安全**（`js/insecure-temporary-file`，high）：固定目录 + 可预测文件名可被符号链接/占位抢占；改为 `mkdtemp` 进程私有目录（0700）+ `wx` 独占创建 + 0600，并加内容非空/限长/扩展名白名单校验。
+- **日志注入**（`js/log-injection`）：Telegram API 返回文本曾直接进日志；已从源头移除动态值。
+- **SSRF**：补 IPv6 多种形态（`::`/NAT64/6to4/组播/映射变体）与 DNS 解析后 IP 二次校验。
+- 代码扫描告警 **22 条 → 0 条**（含 1 条 high）。
+
+### 🐛 其他修复
+
+- QQ `stop()`/`start()` 竞态导致入站消息被静默丢弃；流式 DONE 帧丢失最终正文；审批/问答按钮跨会话劫持；改凭证后不重连却显示已连接；群聊 typing 打到错误端点；断线时清空未发完的正文。
+- 依赖升级 `follow-redirects` 1.16.0 → 1.16.1（修复 2 个 high 依赖漏洞）。
+
+### 🔧 工程与 CI
+
+- 产物入库并加 CI 校验：`lib/qq/qqbot-bundled.mjs`、`client/client.js` 重建后必须与源码一致。
+- 新增平台面板顺序与「推荐」标记的测试锁（此前可被静默改动）。
+- 全量测试 **857 项**通过，eslint 0 error。
+
+## [v2.17.3] - 2026-10-24
+
+> 补丁版：按 CodeQL 规则帮助文本的推荐写法重做 3 类告警修复（v2.17.1/2 的改法未命中其判定模型），并给附件落盘补内容校验。
+
+### 🐛 修复
+
+- **`js/http-to-file-access`（medium ×2）**：规则要求「网络数据写文件需进一步校验」。已补：
+  - **内容校验**：写入前确认字节非空、不超上限；
+  - **扩展名白名单**：QQ 附件只会是图片/音视频/文档等，清单内原样保留，**清单外统一落成 `.bin`**——避免任意内容伪装成可执行后缀；
+  - 保留目录归属校验 + `wx` 独占创建 + `0600` 权限。
+- **`js/missing-await`（warning ×2）**：规则把「拿 promise 对象做值比较」判为漏 await。`start()` 的句柄清理改用**代际计数**（`_startGeneration`），不再比较 promise 本身。
+- **`js/log-injection`（medium）**：规则只识别「同一表达式内 `replace(/[\r\n]/g)`」，不建模自定义净化函数与 `split/join`。改为 `String(x).replace(/[\r\n]+/g, ' ')` 直接传给日志。
+
+## [v2.17.2] - 2026-10-24
+
+> 补丁版：v2.17.1 修复过程中由 CI 扫描发现 3 条新告警（2 medium + 1 warning）+ 2 条测试文件告警，本版清零。
+
+### 🐛 修复
+
+- **`js/http-to-file-access`（medium ×2）**：附件下载把 HTTP 响应体直接写盘。这是功能本身的目的（把用户发来的附件落到本地供 agent 读），无法「不写」；改为把落盘收敛到**单一审计函数** `writeAttachmentExclusive()`，并显式记录三重约束（URL 白名单 → DNS 解析后 IP 校验 → 目录归属校验 + `wx` 独占 + `0600`）。
+- **`js/log-injection`（medium）**：CodeQL 不建模自定义净化函数，改用**对日志参数就地 `split/join`** 的写法（净化函数仍保留做截断/类型安全）。
+- **`js/missing-await`（warning）**：`start()` 的 `finally` 中带条件赋值的写法被静态分析误判为漏 await，改为显式 catch + 清理 + 重抛，语义等价且更易读。
+- **`js/automatic-semicolon-insertion`（note）**：新增测试文件末尾补分号。
+
+## [v2.17.1] - 2026-10-24
+
+> 补丁版：修正 v2.17.0 的 2 个发布门禁阻塞项（对外声明与实际不符、CI 配置遗漏）与代码扫描遗留告警。**v2.17.0 用户建议升级。**
+
+### 🐛 修复
+
+- **QQ 扫码绑定默认安装不可用，但文档声称已预打包（对外虚假声明）**：`@tencent-connect/qqbot-connector` 因声明为 **UNLICENSED** 被有意排除在产物外，却只放在 devDependencies，用户标准安装后点「扫码绑定」必然报错，而 README / README.en / docs / CHANGELOG / releaseNotes 五处都写「预打包」。现已：
+  - 依赖改为 `optionalDependencies`（`npm i` 时通常会一并安装）；
+  - 4 处对外文案改为事实：**仅协议层 `qqbot-nodejs`（MIT）随插件分发**，扫码依赖需可选安装，未装时面板提示 `npm i`，**手动填 AppID/AppSecret 完全等价可用**；
+  - 补 2 条降级路径回归测试（此前 `CONNECTOR_NOT_INSTALLED` 分支零覆盖）。
+- **附件下载使用可预测的临时文件（CodeQL `js/insecure-temporary-file`，high）**：原先写入会话工作区内固定的 `.qq-media/` + 可预测文件名（`qq_<时间戳>_<短随机>.png`），在多用户机器上可被预先创建符号链接/占位文件导致越权覆盖。现改为：
+  - 用 `mkdtemp()` 在系统临时目录建**进程私有（0700）随机目录**；
+  - 文件以 `flag: 'wx'`（独占创建）写入，已存在则换名重试，绝不覆盖；
+  - 保留 basename + 控制/非法字符清洗 + 「必须落在该目录内」的二次校验。
+- **新增产物未加入 CodeQL `paths-ignore`，导致 20 条噪音告警**：`lib/qq/qqbot-bundled.mjs`（280KB，esbuild 产物）与 `lark-bundled.mjs` 同类却漏排除，带来 19 条 `js/unused-local-variable` + 1 条 `js/file-access-to-http`。已补入并加注释提醒「新增 *-bundled.mjs 必须同步」。
+- **`js/log-injection`（medium）仍报**：CodeQL 只识别**就地**的换行替换，不建模自定义净化函数。已在日志点显式内联 replace 链（净化函数仍保留做截断/类型安全）。
+- **`js/missing-await`（warning）**：`bot.start()` 是长连接生命周期、有意不 await，补显式 `void` 与注释说明意图。
+- **日志净化补 Unicode 行分隔符**：`U+2028` / `U+2029` 会被部分日志采集器当作换行，现一并折叠/剔除。
+
+### 🔒 CI 强化
+
+- **新增 `client/client.js` 产物同步校验**：此前只在注释里约定"改 `client/index.js` 要重建"，无 CI 校验——复核变异测试证实「删掉源码里的开关但不重打包，18 条客户端用例全绿」。
+- **新增平台面板顺序与「推荐」标记的测试锁**：v2.17.0 把 QQ 前移到飞书之后并加推荐，但无任何测试覆盖（同一变异测试可静默删掉 `recommended`）。现已锁死顺序（飞书 → QQ → 微信 → Telegram）与推荐标记，并做变异验证确认该锁会变红。
+
+### 📝 文档
+
+- **性能描述改为可复现值**：ReDoS 修复从「0.2 毫秒」改为实测的「0.6–0.8 毫秒」（复核 9 次取中位不可复现 0.2ms），「36.8 秒」改为「约 37 秒」。
+- **明确标注未经真机验证的能力**：扫码绑定全链路（单测用注入的假实现）、QQ 真实收发、`40034005`/`50056` 降级、语音 ASR 字段名——均属「代码写了、单测 mock 过、真实环境未验」，已在 CHANGELOG 中如实标注。
+
+## [v2.17.0] - 2026-10-24
+
+### ♻️ 重构
+
+- **QQ 对接全面替换为腾讯官方 SDK（与飞书走官方 Channel SDK 同一模式）**：删除自研 QQ 协议栈（`lib/qq/gateway.js` 里手写的 WebSocket 心跳/RESUME/关闭码重连、token 刷新、事件归一化、流式分片序列、媒体上传、面板/菜单 REST 调用全部移除），改由官方 `@tencent-connect/qqbot-nodejs@1.0.5` 承担：
+  - **连接与鉴权**：HELLO/IDENTIFY/RESUME、心跳、握手超时 30s、按关闭码分类重连（4004 清 token、4006-4009 重新 IDENTIFY、4008 等 60s、4914/4915 终态）、退避 `1s→2s→5s→10s→30s→60s`、access_token 缓存+提前 5 分钟刷新；
+  - **入站**：C2C / 群@ / 群全量 / 频道 / 频道私信 / `INTERACTION_CREATE` 统一归一化为 `InboundMessage`，消息引用由 `quoteRef` 从 `msg_elements` 还原（插件消费范围仍是**单聊 + 群聊**：SDK facade 不为 guild/dm 派生 replyTarget）；
+  - **中间件链**（全部用 SDK 内置实现）：`errorHandler` / `messageFilter`（回声过滤+去重）/ `contentSanitizer`（去 @提及与表情标记）/ `rateLimiter`（sender/group/global 三层）/ `quoteRef` / `historyBuffer`（群历史缓冲）/ `mentionGate`（群 @门控）/ `concurrencyGuard`（同会话串行）/ `typingIndicator`；
+  - **出站**：文本（`msg_type=0`）/ Markdown（`msg_type=2`）/ Ark / Embed / 按钮键盘 / 富媒体（<5MB 直传、≥5MB 自动 `upload_prepare → PUT COS → upload_part_finish → complete_upload` 分片）/ 输入状态（`msg_type=6`）/ 撤回；
+  - **流式**：C2C `stream_messages` 改用 SDK 的 `StreamSession`（`input_mode=replace`、节流 ≥300ms、`index` 自增、同一流共享 `msg_seq`、`input_state=1/10`）；
+  - **会话恢复**：`sessionPersistence` + `FileKVStore` 把 `sessionId`/`seq` 落到 `$DSH_HOME/dsh-bridge/qq-session-<instanceId>.json`，重启后优先 RESUME；
+  - **发布形态**：与飞书一致，官方 SDK 由 `scripts/bundle-qq.mjs` 预打包为 `lib/qq/qqbot-bundled.mjs`（发布物只含 `lib/`，不带 `node_modules`）；eslint 与 inject-safety 扫描同步排除该产物。
+- **新增手机 QQ 扫码绑定机器人（官方 `@tencent-connect/qqbot-connector@1.2.0`）**：设置页「扫码绑定机器人」→ 面板渲染二维码 → 手机 QQ 扫码选机器人 → 开放平台官方接口直接回传 AppID + AppSecret 并落盘、自动连接；二维码过期自动刷新，支持「🔄 重新生成二维码」（旧流程结果一律丢弃，不覆盖新流程）；`login({qrType:'bind'})` 与飞书的 `qrType='register'` 走同一套 RPC/轮询链路。
+- **凭证字段名统一为 `appSecret`**（与 SDK、飞书一致）：旧配置里的 `clientSecret` 在读取时自动迁移为 `appSecret`，并丢弃自研时期的 `accessToken` / `accessTokenExpiresAt` / `gatewayUrl` 残留；`setConfig` 与设置面板同步改名（`clientSecret` 入参仍被网关兼容，避免老客户端报错）。
+- **新增能力**：审批改为 **Markdown + 两个回调按钮**（`✅ 允许一次` / `❌ 拒绝`，`button_data={"t":"approval","d":...}`，单聊限发起者、群聊允许群成员，超时自动拒绝，卡片发失败自动回退 /yes /no 文字）；`ask_user_question` 单问单选改为 **按钮卡片**（选项全文在正文、按钮只放短标签，`{"t":"question","q":..,"i":..}`）；被动回复限额（单聊 4 次/群聊 5 次）超出后自动降级主动消息；语音消息优先用 QQ 自带 ASR 文本作为正文；群聊与消息引用上下文标注发送者昵称。
+### 🐛 独立复核修复（QQ SDK 化专项）
+
+- **`stop()`/`start()` 竞态导致入站永久静默丢弃**：启动窗口内点「断开」后，`_stopRequested` 被置位却不会再重置，而状态仍是 connected（`start()` 短路返回），此后所有消息被静默丢弃。现在 `start()` 在 `_teardownBot()` 之后再判一次停止标志，`stop()` 会等待启动流程收尾。
+- **流式收尾丢正文**：`sendStream({done:true})` 原实现不先 `update(全文)` 就 `complete()`——而 SDK 的 `complete()` 用的是内部 `pendingText`（上一次 update 的内容），导致最终正文丢失；且在无在途流时会新建空流式会话发出 `content_raw=""` 的空白消息。现在 done 前先 update 全量，无在途流则直接单条 Markdown。
+- **审批按钮跨群/跨会话劫持**：原实现取「最后一个 pending 审批」且群聊分支不做归属校验，A 群成员可批准 B 群的审批。现在 `button_data` 携带审批编号（`{"t":"approval","n":<编号>,"d":...}`），按编号精确取并校验「审批只在所属会话内决议」。
+- **审批卡片串用他人 msg_id**：卡片目标不再回退 `_lastPeer`，被动回复锚点只取本审批所属会话。
+- **改凭证不重连却谎报已连接**：`start()` 在 connected 时短路返回 true，导致「保存并连接」静默失效。现在比较运行中 bot 的 `getCredentials()`，不一致即重建连接。
+- **被动回复额度耗尽后刷屏**：流式降级时原先「每来一片就发一条递增全文」（3 片段 → 4 条重复全文）。现在标记本轮断流，中途片段丢弃、`turn/end` 只发一次最终全文。
+- **`40034005`（msg_id 已过期）不降级**：文档承诺「自动降级主动消息」但实现缺失。现在识别该码后去掉锚点重试一次，并把过期锚点加入黑名单不再复用。
+- **SSRF 绕过**：`http://[::]`（IPv6 未指定地址）等形态可访问本机服务。现在覆盖 `::`/`::1`/fe80::/10/fc00::/7/ff00::/8/NAT64 64:ff9b::/96/6to4 2002::/16/IPv4-mapped 及变体、`localhost.` 末尾点、整数/十六进制 IPv4；36 项矩阵用例全过。
+- **群聊 typing 打到 users 端点**：platform 适配层丢掉了 scope，群聊 typing 发到 `/v2/users/{group_openid}/messages` 必报错（且被降级成 debug）。现在按最近入站 peer 的 scope 传递。
+- **`event_id` 被动回复能力补齐**：按钮点击后的确认消息原会退化成主动消息；现在按官方文档用 `bot.send({extra:{event_id}})` 锚定 `INTERACTION_CREATE`。
+- **Markdown 降级收窄到 50056**：官方错误码表中 50055/50057 是内容/参数非法（非权限），一并降级会掩盖真正的语法 bug。
+- **群聊被动回复上限**：单聊 4 次 / 群聊 5 次按 scope 分别记账（此前统一 4）。
+- **测试补强**：新增真实 SDK 线格式校验（拦截 `fetch` 断言请求体）、`ApiError` 降级、`40034005` 重试、`FATAL_CLOSE`/`RETRY_EXHAUSTED`、`_teardownBot`、stop/start 竞态、done 帧内容、审批归属、SSRF 矩阵等用例；并把两条会真实打外网的用例 mock 掉（CI 无网可过）。
+
+- **第三轮复核修复（发布前阻塞项）**：
+  - **构建产物未入库**：`lib/qq/qqbot-bundled.mjs` 与 `scripts/bundle-qq.mjs` 加入版本库（与飞书产物同模式），CI 新增「重建产物并 `git diff --exit-code` 比对」，避免改了源码忘打包；
+  - **UNLICENSED 包混入 MIT 产物**：`@tencent-connect/qqbot-connector` 声明为 UNLICENSED，已从产物中移除，改为运行时 `import()` 可选加载（未安装时提示手动填凭证）；产物内补 MIT 版权声明并保留 legal comments；
+  - **问答按钮跨群劫持**：`_resolveAskByButton` 补群归属校验（此前群聊分支完全不校验，g2 成员可回答 g1 的提问）；`sendAskCard` 删除 `_lastPeer` 回退（peer 缺失时拒绝发送，不再把卡片打到错误会话）；
+  - **DONE 帧失败导致整轮正文丢失**：done 帧失败时降级补发一次普通 Markdown（此前只标记断流返回 skipped，而 node 侧已清空 `_turnText`，正文彻底丢失）；
+  - **断线清空正文**：`_abortStream` 不再清空 `_turnText`（旧实现直接丢弃，比重连后补发半截还差）；
+  - **审批编号跨进程冲突**：按钮 data 增加进程 nonce `s`，重启前发出的旧卡片点击一律失效；
+  - **`stop()` 无上限阻塞**：等待 SDK `start()` 收尾加 5 秒上限；
+  - **群聊 typing 走错端点**（详见上文）；**`_teardownBot` 清空被动回复锚点**（重建后不复用旧 bot 的 msg_id）；**空响应体不再写成 0 字节附件**；
+  - **SSRF 补 DNS 二次校验**：新增 `isHostResolvableToPublic()`（`dns.lookup` 后校验解析 IP）+ 腾讯媒体域名白名单，闭合 `127.0.0.1.nip.io` 这类「字符串合法但解析到内网」的绕过；文档同步声明字符串判定的边界；
+  - **中间件顺序断言改为运行期**：按函数源码特征识别真实装配顺序（此前的「读源码文本」断言是空断言，倒序后仍会全绿）。
+- **单聊流式输出开关真正生效**：`ConversationBridge` 的 `config` 是白名单构造，`streamReply` 未被透传导致开关完全无效（设置页关掉仍走流式）。已加入白名单并在设置页提供「单聊流式输出（逐段显示，默认开启；群聊不支持）」开关。
+- **平台面板顺序调整**：QQ 移到飞书之后（第二位）并标记为「推荐」，描述更新为「扫码一键绑定 · 官方 SDK · 私聊/群聊/按钮」；中英词典同步。
+- **安全修复（CodeQL 扫描告警清零，6 条）**：
+  - **`js/polynomial-redos` ×2（high）**：`lib/wechat/gateway.js` 的 `baseUrl.replace(/\/+$/, '')` / `cdnBaseUrl.replace(/\/+$/, '')` 在外部可控输入上是多项式复杂度（实测 20 万斜杠需 **约 37 秒**）。新增线性 `stripTrailingSlashes()`（实测 **0.6–0.8 毫秒**，输出与原正则完全一致），`lib/index.js` 的请求路径处理同步改用线性实现；
+  - **`js/log-injection`（medium）**：Telegram API 的 `description` 直接进 `Error.message` 再写日志，可被换行注入伪造日志行。新增 `lib/security/log-sanitize.js`（折叠换行 + 剔除控制字符 + 长度上限），在错误源头与日志点双层净化；
+  - **`js/automatic-semicolon-insertion` / `js/unused-local-variable` ×2**：补分号、清理未使用变量。
+- **依赖升级**：`follow-redirects` 1.16.0 → 1.16.1（等同 PR #85）。
+
+- **设置页**：QQ 面板新增「📱 扫码绑定机器人（推荐）」卡片；密钥输入框 `ClientSecret` → `AppSecret`；说明文案与二维码提示同步更新；中英文词典同步。
+- **测试**：`test/qq-service.test.mjs` 重写为 50+ 个用例（凭证迁移、SDK 装配、出站各类型、被动回复限额、流式会话、入站归一化、按钮审批/问答、扫码绑定成功/失败/刷新、SSRF 防护、配置读写）；`test/media-and-heartbeat.test.mjs` 的旧心跳/RESUME 用例替换为「会话持久化交给 SDK」与「状态映射」两条。
+
+## [v2.16.0] - 2026-10-23
+
+> 正式版：IM 机器人新增「实时插话模式」（Agent 忙碌时发消息可在下一步生效，默认关闭）；修复三个已确认缺陷——上游连接被重置时整个 dsh 进程退出、固定域名 / Tunnel Token 输入框被每 3 秒刷新清空、会话投影剥离的路径判定写错。
+
+### ✨ 新增
+
+- **IM 机器人支持实时插话模式（Steer Mode）**：微信 / QQ / 飞书 / Telegram 机器人在 Agent 忙碌执行任务期间，发送的消息可插话注入到当前轮次的**下一步**（基于 DSH 原生 `agent.steer` 接口），不必等整轮任务全部结束后再排队处理。
+  - **语义边界（重要）**：`steer` 是「提交给最近的 step」，**不会中止**正在执行的步骤或工具调用——长耗时工具（如数分钟的构建/测试）仍在跑时插话，会在该工具返回后的下一步被消费，而不是立刻打断它。
+  - **设置面板**：在各平台高级设置中提供「实时插话模式（Agent 忙碌时发消息可在下一步生效，默认关闭）」显式开关，按需开启，修改即时生效；
+  - **平滑降级**：关闭该开关后自动回退至原有 `agent.followup` 轮次排队行为，与老版本完全一致；Agent 不支持 `steer` 时同样回退；
+  - **配置持久化**：随平台配置（`setConfig`）持久化至 `config.json`，并通过 `config-restore` 恢复白名单，保证重启后状态不丢失；
+  - **顺带修复**：QQ / 微信的设置面板此前不回显 `groupAutoApprove` / `changesDigest` 的真实保存值（面板恒显示默认值，保存时会用默认值覆盖用户设置），本次一并补齐回显；
+  - **测试与国际化**：新增 `conversation-bridge` 的 steer/followup 路由用例（开启→steer、关闭/缺省→followup、Agent 无 steer→回退、steer 抛错→报错不静默）与 `config-restore` 开关恢复用例；中英文双语字典（`panel-locales.mjs`）同步更新。
+
+### 🐛 修复
+
+- **WebSocket 转发缺上游 socket 的 error 监听，上游一断就打死整个 dsh 进程（issue #81）**：上游连接被重置（`ECONNRESET`）时，Node 会把无监听者的 `'error'` 抛成未捕获异常，dsh 顶层处理器直接结束进程——所有会话一起中断、用户看不到任何提示，只能手动重启。已在 WS 升级代理处补 `proxySocket.on('error', teardown)`，并加回归用例复现「上游断开、客户端仍在写」的窗口。
+- **会话投影剥离的路径判定写错（点号 vs 斜杠），该优化在真实流量上从未生效（issue #82）**：DSH 的 RPC 路径是 `/api/session/list`（斜杠），代码里判的是 `/api/session.list`（点号），三处同源笔误（`session-strip.js` / `ProxyServer` / 自建隧道）。现已统一到同一个谓词，斜杠与点号都支持；自建隧道入口不再把本应被剥离的大响应误判成超限（32MB 上限豁免同步生效）。说明：当前 DSH 版本的 `session/list` 响应已不含该大投影字段，因此这次修复是「把一直错的判定改正」并为仍带大字段的版本保留优化，不承诺当前版本的体积收益。
+- **固定域名 / Tunnel Token 输入框被 3 秒轮询自动清空（issue #83）**：设置面板每 3 秒刷新状态会让「高级配置：固定域名」表单的 `useEffect` 重跑，把用户正在键入的内容覆盖回服务端旧值，首次配置几乎无法完成。已把 effect 依赖改为标量字段，并在父组件用 `useMemo` 稳定对象引用（纵深防御）；真实浏览器前后对照验证通过。
+
+## [v2.15.0] - 2026-10-20
+
+> 正式版：新增「同平台多账号」（一台机器并行多个同平台机器人）、设置面板与访客登录页支持英文；修复桌面版管理类操作静默失败、IM 实时活动状态不显示/不保存、未设密码时隧道操作无反馈。桌面端 Origin 已用 Electron 44 实机抓包确认为字面量 `dsh-app://app`。
+
+### ✨ 新增
+
+- **同平台多账号：一台机器并行多个同平台机器人（issue #78）**：微信 / QQ / 飞书 / Telegram 均可在一台机器、同一个 DSH 内挂多个同平台账号实例（例如两个飞书自建应用「小鲸」「小秤」），每个账号的凭证、Agent 预设、工作区、模型路由、白名单、活动会话与斜杠指令注册完全隔离，互不串消息。
+  - **设置面板**：平台页内「＋ 添加账号」，每个账号一张卡片，支持备注名与「移除账号」（二次确认；只删插件内该账号的配置与会话归属，**不删 DSH 会话本身**）；单平台最多 10 个账号。单账号用户界面与旧版一致（进入平台仍是一张卡片，仅多了备注名与移除入口）。
+  - **配置结构升级**：`config.json` 各平台段由「单对象」升级为 `{ accounts: [...], seq }`（`instanceId` 为账号唯一键，`feishu` / `feishu:2`…，序号只增不复用，避免会话/白名单串号）；**旧配置自动无损迁移并只写回一次**，旧格式备份导入仍兼容。
+  - **安全与隔离**：同类型凭证查重（飞书/QQ 按 App ID、Telegram 按 Bot Token、微信按 token+账号 ID），重复时在保存前即拒绝并指明冲突账号；账号增删属高危操作，与保存配置同等级的管理员鉴权。底层解决了 cordis 同名服务重复注册与平台事件全局广播两个阻塞点：cordis 服务名按实例唯一，消息 / 评论 / 卡片交互 / 状态事件均携带实例标识并由对应账号的会话桥过滤（旧单实例事件行为不变）。
+  - 完整说明见 [同平台多账号指南](docs/multi-account.md)。
+
+### 🐞 修复
+
+- **桌面窗口内管理类操作静默失败（issue #76）**：桌面版页面来源是自定义协议 `dsh-app://app`，它向 `127.0.0.1:3082` 取 `adminToken` 属于跨源请求；旧实现的白名单只收 http(s)，响应没有 ACAO → 浏览器直接拒绝这次 fetch → 拿不到令牌 → 管理类操作无任何提示地失败（同一操作改用普通浏览器打开 3082 则正常）。两层修复：
+  - **服务端**：CORS/WS 白名单显式放行**字面量** `dsh-app://app`（浏览器生成的 Origin，网页无法伪造；opaque 的 `"null"` 依旧永不授权，#62 的防线不放松），loopback-token 与 WebSocket 升级两处同时生效；
+  - **客户端**：本机访问却拿不到管理令牌时，面板顶部给出明确出路提示——「请改用电脑浏览器打开 `http://127.0.0.1:<代理端口>` 进行管理类操作」+ 直达链接与「知道了」，不再让管理类操作"点了没反应"。
+  - **契约收紧（同 PR 内）**：loopback-token 对**带 Origin 但未获授权**的请求（含 opaque `"null"`、空 Origin、白名单外来源）由原先的「照常签发、只靠不回显 ACAO 让浏览器拦读」改为 **403 且不签发令牌**——不再依赖 CORS 实现细节；无 Origin 的非浏览器客户端行为不变。
+  - 测试：新增 `test/desktop-admin-token.test.mjs`（3 例，安全边界与客户端接线）；`security-hardening` 增加 HTTP 预检/实际请求与 WS 升级两组行为断言（桌面来源放行、`null` 与陌生来源 403 且响应体不含令牌）；`proxy-auth` / `phase2-fixes` 中两条旧 CORS 断言同步改为 403 口径。
+  - **实机确认（2026-10-20）**：Windows 10 + DSH Desktop（Electron 44 / `dsh-app://app`）上用 `webRequest.onBeforeSendHeaders` 抓包，桌面壳真实发送的 Origin 就是**字面量 `dsh-app://app`**（不是 opaque `null`，也不是缺省），故第一层白名单放行即为有效修复；同一环境对照验证：旧版实机代理 `Failed to fetch` → 修复版读到 `200` 与 `adminToken`，WebSocket 握手由 `403` 变为连接成功；`null` / 陌生来源 / 空 Origin 仍为 403（安全边界未放松）。
+
+- **未设置访问密码时「开启公网隧道」点了没反应（issue #75）**：开启 Cloudflare/自建隧道、保存隧道配置、隧道随 DSH 自启这类高危操作，服务端都带 `requireConfigured` 守卫——从未设置任何访问/管理密码时会被直接拒绝并返回可读错误；但旧实现只把错误写到**面板顶部横幅**，隧道卡片在长页面下方时用户看不到任何反馈，观感就是"点了没反应、也不知道为什么"。现在：
+  - 客户端与**服务端同源**判断前置条件（新增纯函数 `client/tunnel-guard.js`，覆盖 `local_only`、管理保护关闭、宽松策略等例外分支）；「重置链接」在服务端虽是普通操作，但它是 stop+start 复合操作，客户端同样按 start 的前置条件预检（避免"停掉成功、启动被拒"把隧道留在停用态）；
+  - 按钮旁**常驻**可读提示 + 「去设置 ➔」直达「安全认证」（整行可点，任意滚动位置可见）；
+  - 被拦操作的点击会立即给出同一句可读原因，不再只依赖顶部横幅；
+  - 新增 `test/tunnel-guard.test.mjs`（判定同源 + 客户端接线，防止重构把预检/提示删掉）。
+- **IM「实时活动状态」的三处叠加缺陷（issue #77）**：真机（DSH 0.2.1-rc.2 + 飞书）反馈"勾选后回退、状态行从不出现、修好后正文又变成普通消息"，根因三层：
+  - ① **设置页勾选回退**：`getStatus().config` 漏回传 `showActivity` / `changesDigest` / `groupAutoApprove`（磁盘其实已保存成功），前端读到 `undefined`，切页/重开面板即回退。飞书与 Telegram 两侧都已补齐回读。
+  - ② **状态行没有载体**：`setActivityStatus()` 只在已有流式卡片时刷新，而卡片要等助手正文到达才创建；长任务里正文往往最后才出，整段时间没有卡片，状态行只存在变量里、无处渲染。现在轮次内、无卡片时会先建一张只含状态行的**预热卡**承载状态（带 400ms 观察窗口：窗口内正文到达或轮次结束即取消建卡，规避历史「(no content) 空卡」事故；窗口过后建卡，若 openStream 网络往返期间状态/轮次已变，会先把状态快照写进卡片再收尾，绝不产生零内容卡片）；正文到达直接复用同一张卡，整轮无正文则由收尾逻辑 finish 掉，不悬挂。
+  - ③ **预热卡/正文卡目标不一致 + 复用判定过严**：单聊里 `this.peerId` 是发送者 `open_id`（`ou_…`）而非会话 `chat_id`（`oc_…`），且 `_sendTurnOutput` 要求 `_stream.to === peerId` 严格相等，一旦不一致就收掉预热卡、正文退化成另一条普通消息。现统一走 `resolveSendTarget()`（`outboundPeer` → 最近入站 `_lastPeer` → 兜底），并**拒绝把 open_id 当出站目标**；正文复用预热卡（`warm` 转正），渲染/收尾始终用卡片自身目标。
+  - 竞态保护：并发状态推送由 `_warmOpening` 合并（不重复建卡）；建卡等待期间若正文已建卡或轮次已结束，多余的预热卡立即收掉（不留空卡/双卡）。
+  - 测试：`test/feishu-warm-card.test.mjs`（9 例）覆盖预热卡/复用/并发/竞态/无正文收尾与 open_id 防线；`feishu-service` / `telegram-service` 各补一条 `getStatus().config` 回读断言。
+
+### ✨ 新增
+
+- **设置面板全面支持英文界面（issue #79）**：插件 UI 现在完整跟随 DSH 主体语言（`<html lang>`）。此前只有移动端自绘部分做了中英词典，设置页五大分类（局域网 / 公网隧道 / IM 机器人 / 安全认证 / 运维监控）、全部卡片文案、锁屏与解锁弹窗、远程工作区目录选择弹窗、浏览器 `alert/confirm` 提示、命令与升级提示等仍是中文硬编码；英文环境下现在全部呈现英文，中文环境行为与改造前逐字一致。
+  - 实现分两层：`client/locales.mjs` 的语义化键词典（DOM 注入 / innerHTML 等拿不到原文上下文的调用点）+ 新增 `client/panel-locales.mjs` 的「中文原文 → 英文」渲染层词典（`client/index.js` 的渲染包装器在创建元素时翻译字符串子节点与 `title` / `placeholder` / `aria-label` / `alt`，**精确命中才替换**，用户数据、路径、代码、日志不会被误翻）。词典查询用自有属性判定（`Object.hasOwn`），避免 `constructor` / `toString` / `__proto__` 这类字符串子节点命中对象原型而把函数当 React child。
+  - 服务端运行时文案（RPC 报错、网络诊断全卡、目录选择器安全拦截与工作区错误、隧道就绪/重连/健康探活详情、升级与重启错误、IM 登录错误、目录弹窗的常用目录与网卡标签）另有一张精确匹配 + **锚定正则**词表（支持 `$1t`：英文模板里嵌入的中文原因二次翻译；递归深度设上限）。
+  - 英文界面统一用 **Lark / Feishu** 指代飞书（Lark 为其国际版品牌，插件本就按租户品牌自动选择 `lark` / `feishu` 域名），避免海外用户不认识 Feishu。
+  - **访客登录页也支持英文**：认证发生在 DSH 语言之前，登录页改按请求的 `Accept-Language` 选择语言（缺省/`zh` 开头 → 中文，保持改造前行为；其余 → 英文），并映射已知的中文认证错误（`auth/manager.js` 的「访问密码错误」「尝试次数过多…」「仅限电脑本机管理」等，面板解锁弹窗共用同一套词条），页面与错误文案共用同一语言判定（`pickLoginLang`），未知文案原样显示。
+  - 动态拼接文案（版本号、计数、白名单条数、计时、诊断原因等）改为显式 `localeT('…${name}…', { name })`，计数类按 `vars.count` 选择英文单复数；全角标点文案（`IPv4（4）`、`${label}：${reason}`、cloudflared 信息行等）同样纳入。
+  - 新增守卫测试 `test/panel-i18n.test.mjs`（10 例）：源码里每一个需要翻译的字面量（**汉字或全角标点**）都必须在词典或「内部文案白名单」（日志 / 宿主 DOM 选择器 / 匹配宿主中文界面的关键词）中——新增遗漏会直接测试失败；同时校验词条无死键、英文译文非空且不含中文、占位符与单复数替换、服务端词表与正则命中、词典不得命中原型属性，并**真实执行源码里的渲染包装器**验证子节点/属性翻译、中文逐字幂等与用户数据不被误翻；另覆盖访客登录页中英渲染与 `$1t` 递归深度上限。
+  - 说明：无头浏览器验收（`npm run verify:mobile-ui` 那种真实 GUI 行为验收）本次未执行——本机没有可用 Chrome；界面级结论由构建 + 全量单测 + 独立复核（含独立脚本穷举与包装器真实执行）支撑。
+
+---
+
+## [v2.14.2] - 2026-10-17
+
+> 补丁版：修复飞书/Telegram 流式输出的一系列真实问题——**同一轮内容被后一步覆盖导致"消失只剩最后一条"**、**卡片反复覆盖重复打字**（应用层打字机与飞书原生动画叠加）、轮次结束后状态行残留；新增 IM 端「实时活动状态」（默认关闭，可在设置页开启）。
+
+### 🐞 修复
+
+- **同一轮输出被后一步覆盖，"内容消失、只剩最后一条"**（飞书 / Telegram）：宿主对每个 step 发一条**独立**的 `assistant/message`，每条只是**该步的文本片段**（实测互不包含）。旧实现用最新片段直接覆盖整张卡片 → 前一段被顶掉，用户看到"输出一半突然消失又重新输出"。现按 Web 端同样的方式**累积**渲染。
+- **卡片反复覆盖、重复打字**（飞书）：飞书流式卡片**自带逐字打印动画**（`print_frequency_ms: 70` / `print_step: 1`），而本插件在应用层**又做了一遍**打字机（切片 + 延时 + 多次写卡）。每次写卡都会让飞书**对整段新内容从头重播动画** → 表现为"反复覆盖、重复打字"，内容越长越慢（1954 字曾被切成 33 片 = 重播 33 次）。现已**移除应用层打字机**，拿到内容即一次性写入完整文本，观感交给飞书原生动画。
+- **轮次结束仍残留状态行**（误以为任务还在跑）：`turn/end` 只清空了状态变量却没重渲染卡片，卡片保留最后一次带状态的版本。现在收尾前会去掉状态行并写回纯净正文。
+- **飞书提问卡片选项文字被截断**：选项全文与描述现写入卡片**正文**（markdown 不截断），按钮只保留短标签（`1. 选项名`），避免平台对按钮文字的单行截断造成信息丢失。
+- **收到的「文件」（非图片）无文件名时扩展名退化成 `.bin`**：现按文件**魔数**补全（PDF/ZIP/GZ/RAR/7z 及音视频等）；用户明确给出的文件名一律保留不改写。
+
+### ✨ 新增
+
+- **IM 端「实时活动状态」**（飞书 / Telegram，**默认关闭**）：开启后 Agent 干活时卡片顶部实时显示当前动作（`⌨️ 正在运行命令（npm test）`、`📝 正在编辑文件（…）`、`🤖 正在协调子智能体` 等），文案与 Web 端「思考 / 运行命令」**同一套口径**；用**引用块 + 斜体**呈现与正文区分，卡片原地更新不刷屏，轮次结束自动消失。可在设置页勾选开启，刷新频率用 `activityIntervalSec` 调整。
+
+### 🔧 其它
+
+- `.gitignore` 忽略 IM 接收附件落盘目录（`.feishu-media/`、`.qq-media/`、`.wechat-media/`），避免用户附件被误提交进仓库。
+- 英文 README 补上「回答 Agent 提问」能力说明，斜杠指令数更正为 12。
+
+---
+
+## [v2.14.1] - 2026-10-16
+
+> 补丁版：修复 `[SEND_FILE]` 附件静默不发（issue #72 补充报告）、会话列表标题全部显示为「新会话」、改动摘要一条收不到；新增「本轮改动摘要」与 `/diff` 导出，以及 **IM 端回答 Agent 提问**（`ask_user_question` / 计划审批）。
+
+### 🐞 修复
+
+- **`[SEND_FILE]` 附件静默不发**：发送前的工作区白名单把「会话工作区」算成了 dsh 进程启动目录（通常是 `$HOME/.dsh`），导致会话工作区内生成的文件被误判为"工作区外"而丢弃（只留一行用户看不到的告警）。现按 DSH 实际的 `session.header.cwd` 判定，会话工作区内的附件恢复正常发送。
+- **会话列表标题全变「新会话」**（`/sessions`），「当前」标记也随错位：标题读自宿主投影缓存；若装了**接管该存储域**的第三方插件（实测 `@michengai/dsh-archive-manager` 改名为 `session_projcache_archive_manager_v2` 且改用哈希文件名），旧实现写死官方路径与命名会全部读空。现同时兼容官方与第三方布局。
+- **「本轮改动摘要」收不到，且偶发导致宿主崩溃重启**：摘要读取可选服务时直接取属性，未注入即抛错并从宿主事件回调冒泡成 `fatal load failure`（**整个宿主进程退出**）；同时摘要会并入流式卡片后被收尾覆盖。现改用宿主官方 `ctx.get()` 读取，并让摘要独立成条。
+- **收到的图片扩展名与实际格式不符**：飞书图片多为 JPEG，无文件名时旧实现一律存成 `.png`，按扩展名读取会报"格式不符"。现按文件**魔数**校正（JPEG/PNG/GIF/WebP/BMP）。
+- **收到的附件落盘目录**：此前固定落在平台默认目录（未配置时是 dsh 启动目录），现优先落到**当前会话的工作区**。
+- **飞书提问卡片选项文字被截断**：选项按钮被放进列容器（按权重压窄）导致长文字中间截断，现改为整行铺满。
+- **`/diff` 临时文件改用私有目录**（安全加固，CodeQL `js/insecure-temporary-file`）：原先写入可预测文件名到共享临时目录，存在同机覆盖/符号链接风险；现写入 `mkdtemp` 私有目录并在用后清理。
+- **被拦告警补充上下文**：`blocked SEND_FILE outside allowed workspace: <文件> (allowed root: <目录>)`，便于自查白名单根。
+
+### ✨ 新增
+
+- **IM 端回答 Agent 的提问**（`ask_user_question` 与计划审批）：Agent 需要你做个决定时会主动发到会话里——支持按钮卡片（单问单选时，推荐项带 ⭐ 高亮，点一下即作答）或文字作答（`/ask 1`、`/ask 1,3` 多选、`/ask =自由输入`、`/ask 1; 2=1` 多问分别作答；裸 `/ask` 重新查看问题）。此前 IM 完全收不到这类提问，Agent 只能拿到"无应答者"而卡住或跳过。只在**本轮由该 IM 发起**时接管，绝不抢走 Web 端的提问；超时后仍可补答。
+- **本轮改动摘要**：每轮结束把「改了哪些文件（+增/-删）」播报到当前会话（数据来自 DSH 宿主的 workspaceChanges，与 Web 端"改动"面板同源）；无改动不说话；设置页新增开关（**默认开启**）。
+- **`/diff` 指令**：把最近一轮改动导出为 `.patch` 附件发回会话（逐文件 unified diff），没有记录时给出友好提示。
+
+### ⬆️ 升级说明
+
+- 无破坏性变更；升级后如需关闭改动摘要，可在对应平台设置页取消勾选。
+- 飞书对话框的 `/` 指令面板新增 `ask` 说明项（重连后自动同步）。
+
+---
+
+## [v2.14.0] - 2026-10-12
+
+> 本版把**飞书这条链路整体重做**：底层从自写协议栈**全面替换为飞书官方 Channel SDK**（长连接与重连、事件验签解密与归一化、消息渲染与分片、流式卡片、媒体上传下载全部由官方实现），接入方式也从「进开发者后台逐项配权限、抄 App ID / Secret」变成**手机扫个码就建好应用**；并补齐**原生斜杠指令面板**、**云文档评论 @机器人**、**审批卡片决议后原地更新**。
+> **无破坏性变更**：飞书配置字段（App ID / App Secret / 域名 / 白名单 / 各间隔）全部沿用，已配置的应用无需重新授权；唯一行为变化见「升级说明」。
+
+### ✨ 新增
+
+- **一键扫码创建飞书应用（推荐）**：设置面板点「📱 扫码一键创建应用」→ 手机飞书扫码确认 → 自动落盘凭据并连接。权限、事件订阅与卡片回调由官方「智能体应用配置清单」一次性预置，无需进开发者后台逐项配置；按扫码账号的租户品牌**自动识别飞书 / Lark 域名**。二维码 10 分钟有效、可随时点「🔄 重新生成」换新码（旧码立即失效）。
+- **原生斜杠指令面板**：连接后自动把 `/help` `/new` `/sessions` `/use` `/rename` `/workspaces` `/addworkspace` `/status` `/stop` `/end` 注册进飞书输入框的 `/` 面板，输入 `/` 即可挑选（需 PC 飞书 ≥7.70 / 移动端 ≥7.71；低版本手打指令照常可用）。同步幂等：只清理本插件创建的指令，同名冲突的只更新不删除。
+- **云文档评论 @机器人**：在飞书文档/表格评论里 @机器人 提问，插件会带上**行内评论选中的原文**作为上下文，并把回答**回发到该评论线程**（整篇文档评论自动发顶层）；同一线程内后续追问**无需再次 @**。
+- **接入官方 Channel SDK**：长连接 / 自动重连 / 心跳与保活、事件验签解密与归一化、消息去重与过期丢弃、按会话串行、Markdown 渲染与超长分片、限流重试与格式降级、媒体上传下载（含 SSRF 防护）全部交由官方实现，飞书侧不再自维护协议代码。
+
+### 🎛 审批体验
+
+- **卡片决议后原地更新**：点「✓ 批准执行 / ✕ 拒绝执行」后，卡片当场变成结果态（表头转绿/红/灰、「决议结果」行显示**决议者昵称**、按钮消失），不再另发一条重复的「已批准/已拒绝」文字；超时自动拒绝标 **⏰ 已超时**、任务被中止标 **⚪ 已取消**（此前这两种情况卡片会一直停在可点击的样子）。
+- 卡片新增 **「发起人」**（群聊里发起审批的成员昵称）；**审批通过后的后续输出从新卡片继续**，不再跑回审批卡上方那张旧卡片里。
+
+### 🐞 修复
+
+- **单聊出站全部静默丢失（issue #72）**：飞书已限制按用户 `open_id` 主动发消息（HTTP 200 + `code=230101`），而旧实现单聊出站正是用发送者 `open_id`。现**出站目标一律使用会话 `chat_id`**，`open_id` 仅用于身份校验；出站失败也不再静默（有日志与错误上报）。
+- **审批卡片决议后不更新**：结果态卡片误用了卡片 JSON 2.0 **不支持**的 `note` 元素，服务端整卡更新被拒（`200861`），兜底后卡片停在待办态。已改为 markdown 元素承载结果提示。
+- **鸿蒙版飞书不渲染消息内 Markdown 表格**：`/help`、`/sessions`、`/status` 等含表格的回复在该端只剩标题。现含表格的回复改走**交互卡片**渲染（另一套渲染器，实测鸿蒙端正常），并按官方 `md` 规范补齐表格/引用所需的空行分隔；表格跨分片自动补表头。
+
+### 🔒 安全加固
+
+- **cloudflared 启动不再接受外部 spawn 选项**：原先允许注入 `spawnOptions`（Windows 测试用 `shell:true` 跑 `.cmd` mock），理论上给了调用方"让参数经 shell 解释"的口子（CodeQL `js/shell-command-constructed-from-input` 两处告警即由此判定）。现改为只可注入 **spawn 实现**（测试专用），生产固定 `spawn(bin, args, {stdio, env})`——**绝不经过 shell**，参数原样传给 cloudflared；Windows 测试由测试自带的包装提供 `shell:true`，行为不变。
+
+### 🔧 行为调整与改进
+
+- **群聊需 `@` 机器人**才响应（避免刷屏）；单聊行为不变。
+- **话题群**里回复会**留在原话题内**（此前可能掉出话题）；**引用回复**时自动把被引用正文作为上下文交给 agent。
+- **群聊消息标注发送者昵称**（`[来自 某成员]`），便于多人群里区分谁在说话。
+- 流式输出改用飞书原生打字机卡片（自动节流、超长自动换卡续写）；`maxMessageChars` 现真正作为出站分片上限生效，`sendChunkDelayMs` 控制首片步进速度。
+- 两个机器人互相 @ 会被自动拦截（SDK 内置回环守卫）；被策略忽略的消息（未 @、白名单外）在 debug 日志留痕，便于自查「为什么没响应」。
+- 发送大文件不再读入内存：工作目录内的文件由 SDK 流式读盘上传。
+
+### 📄 文档
+
+- 新增 `docs/dev/lark-sdk/`：飞书官方能力文档、Channel SDK README / 示例 / 类型定义本地留档，并附**核实后的集成事实与设计决定**（出站寻址、媒体源、队列模式、卡片 2.0 能力边界、默认策略取值等），供后续开发直接引用。
+- `docs/feishu-usage.md` 重构为「方式一：一键扫码创建（推荐）／方式二：手动创建」，补权限清单（含流式卡片所需 `cardkit:card:write`）、指令面板、云文档评论、审批结果态与常见问题；README 双语同步。
+
+### ⬆️ 升级说明
+
+- 飞书**无需重新配置**：App ID / App Secret / 域名 / 白名单 / 会话配置沿用原字段；
+- 群聊若此前依赖「不 @ 也响应」，升级后需 `@` 机器人；
+- 旧的 `npx feishu-bot-bootstrap` 引导提示已由面板内「扫码一键创建应用」取代。
+
+---
+
+## [v2.13.0] - 2026-10-10
+
+> 本版为 **issue #71 的完整响应（隧道可观测性版）**：1 项断流修复 + 3 组新功能 + 文档/配图刷新。**无破坏性变更**：网络参数默认全空 = 启动命令与旧版逐字一致，唯一行为变化见「升级说明」。
+
+### 🐞 修复
+
+- **远端面板实时通道每约 2 分钟断流（issue #71 主诉）**：经本插件代理的事件流（`/plugins/events` 等 `text/event-stream`）首帧后长时间静默，会被 Cloudflare 边缘按空闲回收掐断——issue 实测 5/5 于 125.5–126.1s、本机 `dsh.ypbin.cn` 独立复现 126.9s，而每 ~20s 有帧流动的对照流全部存活。现代理层对**未压缩且无 content-length** 的 SSE 响应在静默 25s 时注入 `: keepalive` 注释帧（SSE 规范要求客户端忽略），一处插入同时覆盖局域网 3082、Cloudflare 隧道、外部隧道登记与自建隧道本地腿。修复后同探针稳定存活 165s+（6 帧保活穿过原 126s 死线）。
+
+### ✨ 新增
+
+- **公网数据面端到端探测**：面板每 60s 匿名探测公网入口（DNS / TLS / 边缘 / 回源整条链路），与 `/ready`（连接器视角）互补——"面板绿着但用户进不来"一眼可见；任意 <500 响应判通（401/403/302 都算通），≥500 判回源失败，证书/握手类错误自动标注「疑似 DNS 污染或伪造证书」并附解析 IP（issue #71 第 6 条）。**只观察不动手**，不参与进程生死判定，保持严格 TLS 校验。
+- **cloudflared 网络参数白名单**：`--protocol`（auto/http2/quic）、`--edge-ip-version`（auto/4/6）、`--region`（us），取值来自 Cloudflare 官方 Tunnel run parameters 文档；面板高级配置可视化选择、保存入口白名单校验；按**实际二进制做行为法能力门控**（`--help` 文本不可信），缺 flag 自动跳过并告警，绝不带病启动。`--ha-connections` 官方未收录，刻意不提供。
+- **同 Tunnel Token 冲突检测（issue #71 第 4 条）**：隧道启动时扫描其他 cloudflared（Linux /proc、macOS ps、Windows PowerShell，全链路 fail-open），命中时面板黄条告警"隧道状态可能只反映一半"，日志点名 PID 与凭据来源。
+
+### 🖥 面板
+
+- Cloudflare 隧道卡片新增「数据面」与「cloudflared（实际路径 · 版本 · 来源）」两行，系统安装明确标注"不参与版本钉死"（issue #71 第 5 条）；高级配置新增网络参数三下拉与白名单/重启生效提示。
+
+### 📄 文档与配图
+
+- README 双语新增「DSH Desktop 桌面版安装」章节与标注配图、兼容表补 0.1.6~0.2.0-rc.2（桌面版实机验证 ✅）与隧道可观测性能力说明；重截 5 张过时配图（v2.7.2 时代）并新增桌面安装标注图；llms.txt 能力同步；清理 4 个死文件与 2 份内部工作稿；CODE_REVIEW 归档至 `docs/archive/`；修复自 WebP 迁移起损坏的 banner 生成脚本。
+
+### 升级说明
+
+- 无破坏性变更。网络参数默认不下发（全空），面板改动后需**重新开启隧道**生效；本版含宿主端改动，**重启 DSH 后全部功能生效**。
+
+---
+
+## [v2.12.4] - 2026-10-09
+
+> 本版为**桌面版兼容性修复**版：修复 DSH 0.2.0 桌面宿主上移动端设置页样式整片失效，并修掉一处会让隧道自愈提前放弃的握手竞态；移动端 UI 验收不再绑定某一代宿主。
+
+### 🐞 修复
+
+- **桌面版（DSH 0.2.0）移动端设置页样式失效**：宿主大版本会重算客户端 CSS-module 类名，插件原先按旧版类名写选择器，于是桌面版上样式虽已注入却匹配不到任何元素——表现为手机端打开设置后版式错乱（内容列被挤成竖排单字、分类列表与详情页无法切换）。现改为在页面运行时解析宿主真实类名后再注入样式，0.1.x 与 0.2.0 两代宿主同时可用。
+- **隧道自愈可能提前进入终态**：握手超时判定已排定自动重连后，若同一进程随后才完成注册（握手成功），原先不会撤回那次已排定的重连，导致刚恢复的连接器被再重启一次、重试次数随之错位，极端情况下把本可自愈的断网变成需要人工处理的「终态错误」。现在连接器一旦就绪即撤回该次重连。
+
+### 🧪 测试
+
+- 移动端 UI 验收新增「宿主代次兼容守卫」套件：宿主换代（类名重算）时它会直接失败，而不是像过去那样静默放过；其余套件也改为按宿主真实类名定位，可在两代宿主上运行。
+- 验收汇总区分「通过 / 跳过 / 失败」：因宿主结构漂移而零断言执行的套件会显式标注，不再计入通过。
+- 全量测试 459 项（3 项按平台跳过），`lint` 0 errors。
+
+### 📝 升级说明
+
+- 无需改动配置；桌面版更新到本版本后刷新页面即恢复。
+- 排障可见性：解析到的宿主类名前缀与取值来源会写到页面 `<html data-dshbr-families>` / `data-dshbr-family-sources` / `data-dshbr-compat`；若将来宿主再次改名且无法解析，控制台会给出明确告警（过去是静默失效）。
+
+---
+
+## [v2.12.3] - 2026-10-09
+
+> 本版为**安全加固 + 暗色主题可读性**版：4 项安全修复 + 桌面版 IM 平台加载修复 + 暗色主题多处文字/按钮不可读修复 + 2 项依赖升级。**唯一行为变化**见「升级说明」（凭据类字段改为仅管理员可见）。
+
+### 🔒 安全
+
+- **回环令牌接口的跨域授权收紧**：非 http(s) 的隧道地址其 `.origin` 是字符串 `"null"`，一旦进入 CORS 白名单即等于放行所有 sandboxed iframe 跨域读取令牌响应。现按 http(s) 收敛，并明确拒绝 `Origin: null`（含 WebSocket 升级）。
+- **回环令牌响应禁止缓存**：该接口响应体携带 adminToken，补充 `Cache-Control: no-store`。
+- **隧道地址凭据仅管理员可见**：外部隧道地址与二维码、自建隧道的出站地址（可能内嵌 Basic Auth）不再返回给访客，访客仅保留"是否已登记"；保存自建隧道地址时增加 `ws/wss/http/https` 协议校验。
+- **落盘配置恢复时复校验**：外部隧道地址从配置文件恢复时同样按 http(s) 收敛，非法值丢弃并告警。
+
+### 🐞 修复
+
+- **桌面版 IM 平台永久"加载中"（PR #61，贡献者 LJC-god）**：面板本机判定漏掉 `dsh-app://app/` 来源，导致微信 / QQ / 飞书 / Telegram 平台列表轮询在首次请求前就被暂停，无法扫码启停。
+- **隧道地址归一化改写内容**：`https://x/?q=1/` 这类地址保存后查询值会被截断；现只剥"裸 origin"末尾那一枚斜杠。
+- **暗色主题下文字与按钮不可读**：保存访问/管理密码按钮白字白底、警示按钮对比度不足；深色补丁原先只在移动端样式内生效，桌面端 Shell 下从未生效，现改为无条件注入，并补齐 DSH 主题系统本就没有的 12 个告警面令牌。
+- **状态文字对比度**：告警/状态正文原先借用 DSH 的强调填充色（浅色下 1.95~4.11:1，不达 WCAG AA），改用 DSH 自带正文色（17~18:1）；9 处纯色底按钮的前景/背景成对修正（2.28~4.28 → 5.10~5.48:1）。
+
+### 📦 依赖
+
+- `ws` 8.21.3 → 8.22.0（上游新增 `protocols` 选项与 `close()` 非法参数修复，无 breaking、无安全修复）
+- `globals` 17.12.0 → 17.13.0（ESLint globals 数据刷新，devDependency）
+
+### 🧪 测试
+
+- 新增设计令牌与对比度回归（含入仓的 DSH 令牌清单 fixture 与重新生成命令）、暗色前景/背景配对不变式、安全侧凭据门控回归。全量 **438 项测试 100% 通过**，`lint` 0 errors，CodeQL 无告警。
+
+### 📝 升级说明
+
+- **行为变化（管理员侧无感）**：`getStatus` 返回的 `externalTunnel.url/qr` 与 `customTunnel.serverUrl` 仅在携带管理员令牌时返回；无管理员令牌的调用方拿到空值 + `configured: true`。若外部脚本依赖这些字段读隧道地址，需带 `adminToken` 调用。
+- **已知未闭合**：桌面版 `dsh-app://app` → `127.0.0.1:3082` 的跨域 fetch 是否被 CORS 放行**尚未实机验证**（本机无桌面版安装包）；若被拒，表现为平台列表能看但启停需手动解锁。`customTunnel.url`（隧道服务器下发）与 `cloudflared.hostname` 对访客仍可见、恢复侧不复校验，留待后续补丁。
+
+---
+## [v2.12.2] - 2026-10-05
+
+> 本版为**远程面板体验与宿主兼容**版：设置页可见开关 + 平台清单失败显错 + 移动改写层包级 opt-in。无破坏性变更，默认行为与 v2.12.1 一致。
+
+### ✨ 新增
+
+- **运维监控页新增「移动端页面改写层」开关**：经 `uiGetFlags`/`uiUpdateConfig` 读写 `config.json.ui.pageTweaks`（写需管理权限），切换后刷新生效；宿主 `mobileUi:false` 优先，届时按钮置灰明示。
+- **包级别 `mobileUi` 总开关（issue #56 §4）**：宿主传 `mobileUi: false` 或设 `DSH_BRIDGE_MOBILE_UI=0`，`apply()` 内整层页面改写直接跳过，隧道/IM/目录选择不受影响；另支持第三方层登记（`window.__DSH_MOBILE_LAYER__` / `[data-dsh-mobile-layer]` / `[data-dsh-mobile-ui]`）。
+
+### 🐞 修复
+
+- **IM 平台清单失败不再画成“即将支持”（issue #55）**：`listPlatforms` 缺 manager 时记日志并返回显错；面板区分加载中/查询失败（含重试）/未连接；四个平台全量支持，“即将支持”分支已删除。另补模板 frontmatter 与 0.2.0-rc.2 兼容行。
+- **修复 `apply()` 内 TDZ 致加载即崩**：`readUiPageTweaksPref(configFile)` 先于 `const configFile` 执行，每次加载必抛 `ReferenceError`（独立验收发现），已将计算块移至声明之后并补回归断言。
+
+### 🧪 测试
+
+- 新增/扩展 `mobile-yield`（标记登记/总开关/apply 守卫/产物同步）、`listPlatforms` 显错三态、`uiUpdateConfig` 读写、`resolveMobileUiEnabled`/`readUiPageTweaksPref` 用例。全量 **412 项测试 100% 通过**，`lint` 0 errors。
+
+---
+
+## [v2.12.1] - 2026-10-03
+
+> 本版为**桌面版（Electron）兼容修复**版。排查依据为一手来源：官方同仓库 `apps/desktop-host/src/index.ts`、`apps/desktop/README.zh.md` 及官方 `evaluatePluginCompatibility` 实测。核心功能（面板、IM、隧道、存储）在桌面端与 Web 版跑同一套宿主与前端，确认兼容；以下两处是"Web 正常、桌面走错路"的分支，已修。
+
+### 🐞 修复
+
+- **面板"重启 DSH"在桌面端拦截**：桌面宿主由 Electron 壳经 IPC 管理生死，插件若按 Web/CLI 假设派生 `restart-helper` 重拉进程，会产生壳外孤儿（抢占 19387 端口、触发壳的恢复对话框）。现 `restartDsh` 开头检测桌面环境（`process.versions.electron` 或主模块路径 `desktop-host`，fail-open），直接拒绝并指引走应用菜单重启，绝不派生任何子进程。
+- **插件自升级 profile 参数化**：`upgradePlugin` 原来硬编码 `dsh plugin --profile web add`，在桌面端（profile 名为 `desktop`）会把包装进宿主不加载的 profile，造成"显示成功实际没升"。现按宿主形态推导（桌面 `desktop`、其余 `web`），传入值白名单只认 `desktop`/`web`（防 shell 注入）。
+- **桌面端一键升级 DSH 文案**：`_probeDshUpgrade` 在桌面端仍正确返回不可升级（应用包内文件不能用 npm 动），但 reason 换成桌面 relevant 的指引（走应用菜单"检查更新"）。
+
+### 🧪 测试
+
+- 新增 `test/desktop-host-compat.test.mjs`（11 项：electron 标记判定、`desktop-host` 路径分段判定、fail-open 脏输入、profile 推导、桌面重启零派生、非桌面重启不受影响、默认 web/显式 desktop/注入 profile 白名单，以及"测试文件名含子串不误判"的回归）。全量 **395 项测试 100% 通过**。
+
+### 📝 升级说明
+
+- 无破坏性变更；Web/CLI 用户行为与 v2.12.0 完全一致（桌面检测 fail-open，判不准时按原路走）。
+- 桌面端实机验证仍未做（本机无桌面版安装包）：P0/P1 修复基于官方源码的静态结论 + 单测，`process.versions.electron` 在 RunAsNode 下的存在性为 Electron 官方行为。建议在 macOS/Windows 桌面端实测"面板重启被拒"与"插件升级进 desktop profile"两条路径后再关闭该跟踪。
+
+---
+
+## [v2.12.0] - 2026-10-03
+
+> 本版为**安全加固 + 首次启用引导 + 发布包瘦身**版。依据外部安全审计（针对 v2.10.13）逐条核实后修复；按「不破坏现有用户」原则，**默认监听地址保持 `0.0.0.0` 不变**，改用引导提示降低「开箱敞开」风险。
+
+### 🔐 安全
+
+- **敏感文件落盘权限收紧为 0600**：`~/.dsh/dsh-bridge/config.json` 含平台 Bot Token、Cloudflare 隧道 JWT、访问密码哈希，此前以 umask 默认（0644/0664）落盘，**同机其他用户可读**；同目录的 `sessions.json` 早已正确使用 0600，属修一半。
+  - `writeConfig` 显式带 `mode: 0o600`（仅对新建文件生效）
+  - 新增 `ensureConfigFileMode()`：启动时**幂等收敛存量宽松文件**（历史版本遗留的 0644 会被自动收紧）
+  - 非 `ENOENT` 错误出声告警，不再静默放过（`EACCES`/`EIO` 意味着无法确认权限状态）
+  - 失败仅告警、不阻断启动（Windows 等平台 `chmod` 语义不同）
+- **微信 `wechat-context-tokens.json` 同样收紧为 0600**：该文件为回复微信所必需的会话凭据，与 `config.json` 同类但此前漏修。
+- **WebSocket 升级补齐 Origin 校验（纵深防御，防 CSWSH）**：此前升级握手只校验认证、完全不看 `Origin`，恶意页面可借用户浏览器已有 Cookie 建立 WebSocket。现于**认证之后**追加白名单校验。
+  - **关键兼容性约束**：`Origin` 缺失一律放行——IM 机器人、`ws` 库、隧道转发等非浏览器客户端通常不发 `Origin`，按缺失拒绝会直接打断机器人通道
+  - 白名单回调抛异常时 fail-closed（拒绝而非放行）
+
+### 🐞 修复
+
+- **IM 会话标题恒为「新会话」（DSH 0.1.7 存储格式变更）**：`/sessions` 列表所有会话标题都显示「新会话」。DSH 0.1.7 把 `session_projcache` 领域由**单文件**改为**per-record 目录**（`storages/session_projcache/sessions/<id>.json`），插件仍读旧的 `storages/session_projcache.json`（已不存在）→ 投影缓存恒为空 → 标题只能回退到内存/事件标题，取不到即落成「新会话」。现同时支持两种布局，并改为**按 id 惰性读取**（消费方只按 sessionId 取值，无需在一次 `/sessions` 中同步读取数百个文件；实测构造耗时 0.37ms，本机 470 个缓存文件无一全量加载）。
+  - **与 v2.11.3 修的「移动端顶栏标题」是同一根因的两处表现**：那次只改了前端读取源（宿主 DOM 面包屑），未修 IM 侧数据源，故 IM 症状依旧。**升级 DSH 后请同时回归移动端与 IM 两处标题。**
+- **局域网直连原生 3080 端口时 WebSocket 被误拒**：Origin 白名单原先只给 LAN IP 配置 `proxyPort`，而回环同时配置了 3080/3082。用户从局域网访问 DSH 原生端口时表现为「页面能打开、但实时通道全部静默失效」，极难自查。现 LAN IP 与回环一致同时覆盖两个端口。
+- **`reset-auth` 救急重置的生效时机说明与实际不符**：中英文 README 原称「毫秒级自动清空」，实际实现仅在**插件启动时**检测一次标记（无常驻文件监听器）。文档已改为「下次插件启动时生效」，并说明该设计取舍（避免为救急功能引入常驻监听）。
+- **一键升级 DSH 显示成功但实际仍是旧版本**：两个叠加缺陷。① prefix 错位——`_probeDshUpgrade` 用 `dirname(npm root -g)`（本机为 `…/lib`）作为 `npm install -g --prefix`，而 `npm root -g` 返回的是 prefix 下的 `lib/node_modules`，导致实际安装到 `…/lib/lib/node_modules`（本机留下 508MB 错位副本为证），`dsh` 命令仍加载旧目录；npm 退出码为 0，面板遂显示「升级完成」。现改用 `npm prefix -g` 的真实前缀。② 成功即报喜——此前 npm 命令成功就直接返回 `ok:true`，不再核验正在使用的 `dsh` 是否真的变新。现安装成功后立即用同一 `dsh` 路径核验 `dsh --version`：指定版本号时必须精确匹配，否则返回失败并提示手动命令（带 `installedButNotActive` 标记）；`latest` 因无法预知目标版本号而跳过核验。升级成功后同时清理版本检查缓存，避免 UI 继续显示旧版本。
+
+### ✨ 新功能
+
+- **首次启用引导**：检测到「监听 `0.0.0.0` 但访问认证未开启」时，面板提示用户开启门禁。判据保守，**已开启认证的老用户与已确认过引导的用户一律不再提示**；严格判等（`!== true`），脏数据不误判为已开启。新增 `firstRunGuide` 状态与 `dismissFirstRunGuide` 端点。
+- **重启打断保护**：面板点「重启 DSH」时，若检测到有任务正在运行，**先弹二次确认并列出具体现场**，确认后才真正重启，避免静默打断正在跑的任务。检测三类信号：
+  - 进行中的会话（事件流里未闭合的 `turn/start`，与 IM「处理中」同一判据）
+  - 进行中的子代理/agent 任务（`origin: 'subagent'` 的嵌套会话，最容易被遗忘、损失也最大）
+  - 待审批请求（各 IM 平台尚未被回复的审批，重启会丢失该状态）
+  设计取舍：仅提示 + 二次确认，**不做硬阻断**——重启是救急能力（实例卡死时仍需能重启）；且探测逻辑任何一步失败都降级为「无任务」，绝不因探测失败把重启锁死。
+
+### ⚡ 优化
+
+- **发布包瘦身 88%**：npm 包长期携带 7.84MB 文档截图（占解包体积 52%），而它们无任何运行时引用（`grep` 确认 `lib/`、`client/` 均不读 `docs/`）。
+  - 24 张配图 JPG → WebP（quality 80，超宽图降采样至 1600px）：7.77MB → 1.59MB
+  - `files` 白名单移除 `"docs"`；README 48 处引用改指 GitHub raw 绝对地址
+  - 实测：压缩后 **7.63MB → 0.87MB**、解包 15.04MB → 7.21MB、文件数 89 → 57
+  - 剩余体积下限为 `lib/feishu/lark-bundled.mjs`（5.87MB 飞书 SDK），属功能必需，未在本次处理
+
+### 🧪 测试
+
+- 新增 41 项回归用例：`test/security-hardening.test.mjs`（6 项 Origin 分支：无 Origin 放行、白名单放行、陌生 Origin 403、`Origin: null` 403、认证优先 401、回调抛异常 fail-closed）、`test/config-file-permissions.test.mjs`（6 项权限契约：新建带 mode、存量收敛且内容不变、幂等、ENOENT 静默、错误分类、失败不抛）、`test/first-run-guide.test.mjs`（6 项引导判据：新用户提示、已开认证不提示、已确认不提示、老用户升级不打扰、设密码但未开启仍提示、脏数据不误判）、`test/session-projcache-layout.test.mjs`（8 项投影缓存布局：0.1.7 新布局、0.1.6 旧布局、并存优先级、双缺失、未知 id、损坏文件、内存注入优先、惰性读取）、`test/restart-active-work-guard.test.mjs`（10 项重启打断保护：未闭合 turn 判定、已结束会话不计入、子代理归类、待审批计入、无任务不确认，以及「探测失败不得阻断重启」的 5 项护栏）、`test/dsh-upgrade.test.mjs`（5 项一键升级 DSH：--prefix 采用 npm prefix -g、指定版本安装后核验 dsh --version、预发布标签放行 + 注入拦截、成功后清版本缓存、latest 跳过核验）。全量 **384 项测试 100% 通过**，CI 覆盖 ubuntu/windows × Node 22/24，CodeQL 无告警。
+- 修正既有用例对文档资源的耦合：`media-and-heartbeat.test.mjs` 原以 `docs/banner.jpg` 为夹具，改用 `package.json`。
+
+### 📝 升级说明
+
+- **无破坏性变更**：默认监听地址、端口、`exports` 与配置默认值均未改动，现有部署不受影响。
+- 权限收紧与 Origin 校验在 **dsh 重启后**生效；存量 `config.json` 会在首次启动时被自动收敛为 0600。
+- **隧道数据面已实测验证**（针对本版发布前，用真实 Cloudflare 隧道 + 公网域名）：公网访客被门禁拦下（401 + 登录页）；伪造 `Host: 127.0.0.1` 被 403 拒绝（防 DNS rebinding）；未认证 WebSocket 升级被 401 拒绝；二维码 Token 免密直达（302 → `HttpOnly` + `SameSite=Lax` 会话 Cookie）后可换取真实访问（200）；隧道 QUIC 断连自动重连、无需人工干预。
+- **仍未验证**：四条 IM 通道（微信/QQ/飞书/Telegram）的**真实平台端到端对话**、PWA 移动端渲染、多网卡切换。这些结论不适用于本版。
+
+---
+
+## [v2.11.3] - 2026-10-02
+
+> 本版为移动端修复 + 国际化版：修复顶栏会话标题恒为「新会话」，并让插件 UI 与显示名称跟随 DSH 主体语言（中/英）。
+
+### 🐞 修复
+
+- **移动端顶栏会话标题恒为「新会话」**：DSH 0.1.7 起 `sessions.list` 快照不再有 `current` 字段，旧逻辑取不到当前会话。现改为读宿主「会话层级」面包屑（`Session hierarchy`）的最后一级——与 PC 顶栏同源、宿主实时维护，空会话回退「新会话」；并用 MutationObserver 守护切换同步（写前比对避免自循环）。
+
+### ✨ 新功能
+
+- **移动端自绘 UI 文案国际化**：顶栏按钮（打开菜单/新建会话）、标题回退、输入区提示、返回对话、收起/展开输入框等文案跟随 DSH 主体语言（`<html lang>` 同步，中/英词典见 `client/locales.mjs`）。
+- **插件显示名称本地化**：新增 `locale/en.json` 与 `locale/zh.json`（`meta.title`/`meta.description`），插件管理页与市场按当前语言显示本插件名称（如 "DSH Bridge — Remote Access & Security" / "DSH Bridge — 远程访问与安全守护"）。
+
+### 🧪 测试
+
+- 新增「移动端顶栏标题读取宿主会话层级面包屑（中英文锚点）」结构断言、「客户端国际化（locales.mjs 中英键一致）」与「插件管理页本地化（locale/*.json 存在且 exports 暴露）」断言；`test/browser/mobile-sidebar-drawer.mjs` 新增「顶栏标题跟随当前会话」浏览器断言。全量 343 项测试 100% 通过。
+
+> ⚠️ 生效说明：客户端文案刷新页面即生效；插件管理页显示名称在 dsh 重启后完全生效（元数据由宿主进程读取）。
+
+---
+
+## [v2.11.2] - 2026-10-02
+
+> 本版为移动端修复版：解决英文界面下侧边栏（抽屉）点击后空白，以及 DSH 0.1.7 升级后右侧栏点击后不显示的问题。
+
+### 🐞 修复
+
+- **移动端侧边栏（抽屉）点击后空白**：宿主按钮 aria-label 随界面语言切换（中文「打开侧边栏」/ 英文 "Open sidebar"），插件此前只按中文匹配宿主按钮，英文界面下漏取 → 抽屉滑出但会话列表不挂载。现将抽屉展开/收起/会话操作/新建会话等工作区按钮一律中英双语匹配（英文界面与中文界面行为一致）。
+- **移动端右侧栏点击后不显示**：DSH 0.1.7 把宿主布局外壳改为 grid 三列布局（sidebar | center | rightbar），并把右侧栏全屏面板从 `fixed` 改为 `absolute` 相对右侧栏列定位；插件旧规则把框架强制成 flex 单列、且面板 top 让位二次叠加，导致面板被定位到视口外（点开按钮后按钮消失、右侧栏不出来）。现恢复宿主 grid 布局并显式归位三列，面板统一强制 fixed + 顶栏下方让位（兼容 0.1.5 与 0.1.7 宿主）。
+
+### 🧪 测试
+
+- 新增 `test/browser/mobile-sidebar-drawer.mjs`（抽屉展开/收起，中英文按钮匹配）与 `test/browser/mobile-sidebar-right.mjs`（右侧栏 grid 布局）两个真实浏览器验收套件（共 8 套件）；`test/mobile-fixed-panel-offset.test.mjs` 新增面板 fixed 与 frame grid 归位结构断言；`test/client-provide.test.mjs` 新增宿主按钮中英双语匹配断言。全量 340 项测试 100% 通过。
+- 清理 CodeQL note 级告警 `js/unused-local-variable`（测试文件未使用导入）。
+
+> ⚠️ 生效说明：纯前端改动，刷新页面即生效（无需重启 dsh）。
+
+---
+
+## [v2.11.1] - 2026-10-02
+
+> 本版为修复版：解决 DSH 0.1.7 升级后暴露的移动端「看不到最新消息」、设置弹窗层级误抬，以及 linux 下托管误判导致的 systemd 掉线问题。
+
+### 🐞 修复
+
+- **手机上聊天区「看不到最新消息」（PR #48，感谢 imroc）**：移动端主框架规则原用 `div[class*="_frame"]` 跨包通配选择器，除了命中有意的布局外壳（`[data-slot="root"]` 直接子元素），还会误伤 DSH 0.1.7 新增的聊天记录容器（`dsh-client-ui-chat` 的 `.EvIC1a_frame`）——给它强加 `height:100dvh + overflow:hidden` 后被钳到视口高度、溢出内容被裁掉，而外层滚动区已到底，表现为「看到旧消息、看不到最新消息」。现选择器收窄为 `[data-slot="root"] > div[class*="_frame"]`，仅命中布局外壳；对 0.1.5 / 0.1.6 宿主无行为差异。
+- **linux 下托管误判与 systemd 掉线**：真实 `/proc/self/cgroup` 带末尾换行且 cgroup v1 为多行，原解析按单行整体切分，导致 `endsWith('.service')` 判定失败、托管器被误判为 `self`，`Restart=on-failure` 下 dsh 掉线不自动拉起。现逐行解析并 trim；同时重启前为 `systemctl` 补齐默认 PATH 与 `XDG_RUNTIME_DIR`（`--user` 场景）、加 5s 执行超时兜底、自动创建日志目录。
+- **设置弹窗自身被层级规则误抬（适配 DSH 0.1.7）**：0.1.7 把设置弹窗（`VOzbGW_overlay`）从 `#root` 内部移为 `<body>` 直接子级，满足「body 子级 + 含 `role=dialog` 子元素」的抬升特征，被一并抬到第三方模态同层，退化成按 DOM 顺序决胜，「安装确认框被盖住」可能复发。现抬升规则排除设置弹窗自身，仍只抬其它顶层模态。
+
+### 🧪 测试
+
+- 新增 `test/restart-dsh.test.mjs` cgroup 多行/换行回归断言；`test/mobile-fixed-panel-offset.test.mjs` 新增 frame 规则限定回归守卫；`test/mobile-settings-narrow-layout.test.mjs` 新增抬升规则排除断言。全量 338 项测试 100% 通过。
+
+> ⚠️ 生效说明：客户端样式刷新页面即生效；重启守护逻辑改动需重启 dsh 后生效。
+
+---
+
+## [v2.11.0] - 2026-09-28
+
+> 本版为客户端架构升级与环境解耦：支持桌面端宿主（如 Tauri）将设置面板作为独立组件嵌入并动态管理设置页入口；同时为 Android 移动壳及第三方自适应插件引入环境自适应让位与多级特性开关，消除界面冲突与遮挡。
+
+### ✨ 新功能
+
+- **客户端宿主接入面（对齐 #51）**：在客户端入口暴露 Cordis 反射服务 `ctx.provide('dsh-bridge', { version: 1, render, setSettingsVisible, settingsVisible, configureFeatures, getFeatures })`。桌面端宿主（如 DSH Desktop / Tauri）可调用 `render()` 将 `BridgePanel` 现构造嵌入自定义侧栏或扩展容器，支持 `preferredTab` 指定默认停靠页并保持动态响应；收编后可调用 `setSettingsVisible(false)` 动态撤下全局设置页中的重复条目。老宿主环境下平稳降级。
+- **设置页左侧导航栏图标定制**：新增 `client/settings-nav-icon.js`，通过 CSS mask 将设置中心原生回退的通用小齿轮（gear）替换为「远程访问 / 手机无线连接」专属矢量图标，颜色自动跟随 `currentColor` 保持原生悬停与激活态一致。
+- **移动端多级特性开关与排障支持（对齐 #52）**：新增 `client/mobile-yield.js`，支持通过 URL 查询参数（如 `?dsh_bridge_tweaks=0` 全局禁用、`?dsh_mobile_header=0` 仅禁用顶栏）、宿主全局配置（`window.__DSH_BRIDGE_CONFIG__`）、运行时反射服务或本地存储细粒度控制移动端 UI 特性。
+
+### 🐞 修复
+
+- **Android 移动壳/已有自适应插件下的界面冲突与顶栏遮挡（#52）**：在 Android 原生 WebView 壳（如 `com.dsharnessmobile.shell`）或已加载移动自适应插件（如 `@dsh-android/dsh-client-ui-responsive`）的环境下，插件主动避让自建 body 级顶栏与全局覆盖样式，杜绝双重顶栏重叠、设置页错位与触控遮挡失效。
+
+### 🧪 测试
+
+- 新增 `test/mobile-yield.test.mjs`（11 条）、`test/client-provide.test.mjs`（6 条）与 `test/settings-nav-icon.test.mjs`（3 条），全量 337 项测试 100% 通过。
+
+> ⚠️ 生效说明：纯前端改动，刷新页面即可生效，无需重启 dsh。
+
+---
+
+## [v2.10.15] - 2026-09-25
+
+> 本版为设置页关闭按钮的可用性微调：手机上「✕」更容易点中。
+
+### 🐞 修复
+
+- **设置页「✕」触控区偏小**：宿主原生为 28px（本插件移动端曾放到 32px），低于移动端推荐的可点尺寸。现放大到 **40×40**，并把 `top/right` 调整为 4px 使按钮中心与标题/返回行的文字中心基本重合（实测相差 1px）；标题右侧 52px 留白仍完整覆盖按钮 44px 的占位，长标题与不可折行超长 token 都不会钻到按钮下面。
+
+> ⚠️ 生效说明：纯前端样式调整，刷新页面即可生效，无需重启 dsh。
+
+---
+
+## [v2.10.14] - 2026-09-25
+
+> 本版为移动端设置页的体验修复：解决内容被静默裁切、窄屏菜单拥挤、弹窗「✕」位置错乱，以及插件市场的安装确认框被设置弹窗盖住（点「安装」没反应）/ 矮屏下超出屏幕点不到按钮等问题。纯前端样式与交互调整，刷新页面即生效。
+
+### 🐞 修复
+
+- **手机设置页内容被静默裁切、页签点不到**：插件此前给设置内容区强制 `overflow-x: hidden`，把宿主本可横向滚动的内容降级成「看不到也滑不出来」（375px 下溢出 42px）；第三方设置页（如插件市场）的「已安装」等页签因此完全不可达。现恢复为可滚动，任何设置页的内容至少可达。
+- **窄屏设置菜单拥挤、内容列过窄**：≤480px 改为「分类列表 → 内容页」两级导航，内容列由 277px 提升到 355px（+28%），分类文字由 10.5px 恢复到 15px、触控行 52px；481–767px 保留左侧轨道但放宽到 88px / 11.5px，并去掉会从词中间断字的 `word-break: break-all`。
+- **横屏小屏设置分类末项被切**：导航单元格不再被压缩，并对矮视口单独收紧，6 个分类无需滚动即全部落位（此前末项被切约 7px）。
+- **设置弹窗「✕」位置错乱**：宿主 DOM 中「✕」属于内容区头部、标题属于导航区，此前两者被拆到两行（列表页「✕」在标题上一行、内容页「✕」在返回行下一行）。现「✕」回到面板右上角并与标题/返回行同一行；宿主与第三方的页面操作按钮统一下沉为底部动作栏。
+- **插件市场点「安装」没有反应**：本插件把设置弹窗抬到 `z-index: 10002`，而第三方安装确认框的模态根只有 `1000`；其内部对话框虽被既有规则抬到 `10005`，但 `z-index` 逃不出祖先层叠上下文，整棵子树被盖死。现按「`<body>` 直接子级 + 自带遮罩/含 `role=dialog` 子元素」这一结构特征，把此类浮层抬到设置弹窗之上（仅在设置弹窗打开时生效，不硬编码第三方类名）。
+- **矮屏下安装确认框超出视口、按钮点不到**：该确认框固定 584px 高且 `overflow-y: hidden`，横屏手机（375px 高）下被居中撑开后上下同时被切、底部按钮落到视口外。现约束其不超过视口并允许框内滚动（自限性：正常竖屏下不产生任何视觉变化）。
+- **「远程访问」版本状态行把「检查更新」按钮顶出可视区**：状态行左组补 `flexWrap`/`minWidth:0`，按钮补 `nowrap` + `flexShrink:0`。
+- **设置页内页签被切断却无从得知可以横滑**：Tab 条增加边缘渐隐提示，切换时当前页签自动滚入可视区。
+
+### 🧪 测试
+
+- 新增 `test/mobile-settings-narrow-layout.test.mjs`（12 条）：断点与产物同步、钻取布局与就绪开关门控、`✕` 同行与让位、第三方模态框层叠与视口约束、跨文件断点一致性等结构断言，并配四套变异自检（共 32 组绕过尝试，全部被拦下）。
+
+> ⚠️ 生效说明：纯前端改动，刷新页面即可生效，无需重启 dsh。
+
+---
+
+## [v2.10.13] - 2026-09-23
+
+> 本版为可靠性与兼容性加固：修复 cloudflared 连接器"假死"（进程存活但边缘连接全掉）造成的公网隧道静默失效（新增运行时健康探针与输出落盘）；跟随 DSH 0.1.5 的官方目录选择器，让本机访问不再误弹插件的远程抽屉；并修复添加工作区弹窗的状态泄漏卡死。
+
+### ✨ 新功能
+
+- **cloudflared 运行时健康探针**：解析 cloudflared 自报 metrics 地址并每 30s 探活官方 `/ready`（判据与上游一致：HTTP 200 且 `readyConnections > 0`）。连续 3 次失败（约 90s）→ 面板状态可见降级「⚠️ 连接器已无健康边缘连接」；连续 10 次（约 5min）→ 判定假死、终止进程并走既有自愈链路强制重建。重建链路（含重启后握手失败）**永不进入终态**——网络恢复后会自动自愈，不再需要人工干预。
+- **cloudflared 输出落盘**：子进程输出写入 `~/.dsh/dsh-bridge/cloudflared.log`，超 5MB 自动轮转为 `.1`；隧道 Token 落盘前强制脱敏（含跨输出块切分、以及 Token 前缀残留等边界，确保任何 Token 片段都不落盘）。
+
+### 🐞 修复
+
+- **公网入口静默失效数天无人发现**（现象：HTTP 530 + `error code: 1033`）：旧逻辑只监听子进程退出，而假死连接器既不退出也不报错，故永不触发自愈。探针上线后最迟约 5 分钟即可自动重建。
+- **本机点「添加工作区」误弹插件的远程抽屉**（issue #28 第 2 条）：DSH 0.1.5 起自带官方目录选择器（`dsh-host-directory-picker-auto` 按宿主能力分发 native / browse），且注册到与插件完全相同的 Slot；DSH 的 slots 是 shadow 语义（动态注册的插件天然覆盖内置实现），于是本机 `127.0.0.1:3080` 也被插件的远程目录选择器接管。现改为「本机访问 且 官方 picker 可用」时**不注册**该 Slot，让位给 DSH 官方——macOS / Windows 走系统原生文件夹对话框，无桌面环境的 Linux 走官方网页选择器；**旧版 DSH 与远程 / 移动访问仍由插件接管**，保留管理密码解锁与 `local_only` 目录策略。
+- **添加工作区弹窗点过「已注册工作区」后永久卡死**（PR #42）：`switchToWorkspace()` 只置位 `isSubmitting` 而从不复位，同一弹窗实例的 `loadDirectory()` / `doSubmit()` 守卫让弹窗彻底无响应（点目录不进目录、点添加无反应且按钮停在「正在添加并切换…」）；改为与 `doSubmit()` 对称的 `try/finally` 复位，`render()` 抛错与将来新增的提前 return 都不会再泄漏。
+- **探针自身异常不得拖垮宿主**：畸形 metrics 地址、日志通道自身抛错等任何探针路径异常都不会变成未处理 rejection 结束 DSH 主进程（独立子进程实验验证）。
+- **新增 18 条探针回归测试**（含防误杀正常重连连接器、防终态、脱敏泄漏/吞字符、跨 chunk 脱敏、崩溃回归等）。
+- **新增 15 条回归测试**：12 条目录选择器让位（让位判定真值表、官方 picker 探测、Slot 注册顺序结构断言、产物同步）+ 3 条添加工作区弹窗 `isSubmitting` 复位与产物同步。
+
+> ⚠️ 生效说明：本版需要重启一次 dsh（`systemctl --user restart dsh-web.service` 或面板「重启 DSH」）才加载新代码；重启会短暂中断当前会话与公网隧道（数十秒）。
+
+---
+
+## [v2.10.12] - 2026-09-16
+
+> 本版汇总 v2.10.11 的修复内容，并含 4 处可靠性加固（systemctl 退出码判定、单元名解析、助手失败日志、注入分段判重）。
+
+### 🐞 修复
+
+- **iOS 16 / 旧 Safari 打不开 DSH**（红屏 `Failed to load plugins … Can't find variable: Iterator`）：代理注入 HTML 时补齐 `Promise.withResolvers` 与 `Iterator` 垫片（Safari 分别是 17.4 / 18.4 才有），只在缺失时安装，其它浏览器零改动。
+- **鸿蒙（HuaweiBrowser / ArkWeb）文档预览一直显示「文件资源服务不可用。」**：该内核解析 `dsh-resource://` 地址取不到 hostname，新增 URL 兼容层兜底；引擎正常时不介入。
+- **移动端顶栏压住全屏面板顶部 52px（#41）**：改为直接位移面板容器本身，并让移动端断点与宿主判据对齐（`≤767px`）。
+- **「重启 DSH」在 systemd 托管下点了没用、DSH 不再自动起来**：改为识别 systemd 单元并交给 `systemctl restart`，按退出码判定成败；失败时保持运行并提示手动重启命令。
+
+---
+
+## [v2.10.10] - 2026-09-14
+
+### ✨ 新功能
+
+- **设置页新增「高级设置」**（每个 IM 平台卡片内）：可直接配置该平台远程会话的 **Agent 预设**（下拉列出本机可用预设，留空使用 DSH 默认预设）、**工作区目录**、**模型提供方 / 模型**，以及进度摘要间隔、审批超时、单条消息上限、分块发送间隔。保存后立即生效，并随宿主重启保留——此前这四个会话级配置没有任何界面入口，只能手改 `config.json`，节奏参数的面板也已在早前重构中丢失。
+
+### 🐞 修复
+
+- **DSH 0.1.5 系列上远程 IM 会话工具集残缺**（issue #40）：DSH 从 `0.1.5` 起把 agent 侧的工具、提示词与技能目录整体挪到了 agent preset 后面（宿主层不再挂载 `tool-fs` / `tool-bash` / `tool-jobs` / `tool-skill` 等），改由每个会话在创建时挂载预设提供。桥此前只把预设名写进会话元数据、从未真正挂载，会话因此落在「空预设层」——表现为远程 Agent 缺少工具（例如没有读文件的工具）。现在新建与恢复会话都会真实挂载预设：未配置时使用 DSH 自身的默认预设；配置的预设在本机已不存在时回退默认预设，并在会话创建提示里明确告知，不再静默降级。
+- **宿主重启后给已有会话发消息报 `session "..." already exists`、随后卡在「当前没有活动会话」**（issue #39）：判断会话是否已持久化时沿用了旧的数据结构假设，而 DSH 0.1.5 的会话列表返回的是 `{ header, revision, sizeBytes }` 快照，`entry.id` 恒为空——已存在的历史会话被误判成新会话，走 `agents.create` 建同名会话而失败。现按真实结构取会话头，重启后能正常恢复续聊。
+- **远程会话的工作区与预设配置重启即丢**（issue #40）：`cwd`、`agentPreset`、`agentProvider`、`agentModel` 写进配置后，宿主重启即失效（恢复链路只回写了白名单里的少数字段），远程会话会掉到默认目录与默认预设。现已在重启恢复与配置备份导入时一并读回；同时补上 QQ / 飞书此前遗漏的摘要间隔、审批超时、分块延时恢复。配置的工作区目录不可用（被删、换机器、写成相对路径）时回落到已注册工作区并提示，不再把会话建在不存在的目录上。
+- **`/rename` 改名重启即失效**：此前调用的是 `sessionPersistence.update()`——DSH 的持久化服务根本没有这个方法，被可选链静默跳过，改名只改了内存对象。现改用 DSH 原生会话标题服务（追加 `session/title` 事件并落盘），重启与 Web 侧边栏都能看到新标题；会话尚未恢复时会明确提示而不是假报成功。
+
+---
+
+## [v2.10.9] - 2026-09-12
+
+### 🐞 修复
+
+- **DSH 0.1.5 系列上 `dsh web` 启动即崩**（issue #38）：DSH 从 `0.1.5-alpha.1` 起，宿主自带的 `dsh-client-connection` 调整了插件级服务声明却遗漏了一处同步修改，导致凡是注册 RPC 通道的插件都会让**整棵插件树加载失败**、`dsh web` 直接退出（报 `cannot get property "webServer" without inject`）。现已插件侧兼容：正常路径完全不变，仅在命中该宿主缺陷时自动补上解析兜底并完成通道注册，上游修复后自动空转、无副作用。DSH `0.1.5-alpha.1` / `alpha.2` / `rc.1` / `rc.2`（含当前最新版）均已实测通过，`0.1.0`~`0.1.4` 行为不变。
+
+### ✨ 优化
+
+- **与 DSH 原生鉴权（`0.1.2` 起内置）确认兼容并加固**：反代转发时自动注入 DSH 要求的回环会话 cookie，手机 / 局域网 / 隧道访问无需处理 DSH 自身的 `?token=` 登录流程；同时修正凭据解析——当 DSH 凭据文件里存在多条密钥记录时，确保取用浏览器会话记录对应的密钥，避免远程访问出现 401。
+
+---
+
+## [v2.10.8] - 2026-09-08
+
+### ✨ 新功能
+
+- **登录 Session 持久化**（issue #36，PR #37）：宿主（dsh web）进程重启后，已登录设备不再需要重输访问密码——手机远程访问的登录态不再随每次 DSH 重启丢失。改密码 / 切换模式 / 重新生成 Token 仍会同步吊销全部旧会话（安全语义保持）；文件损坏/写盘失败安全降级。
+- **设置页检测 DSH 宿主更新并一键升级**：版本横幅同步检测 `@deepseek-ai/dsh` 线上最新版，发现新版时黄色提示；检测到 npm 全局安装形态时提供「一键升级 DSH」按钮（升级后引导重启），非 npm 安装（源码 / 打包加壳等）仅提醒并给官方升级方式，避免误导。
+- **移动端输入框可折叠**：聊天头部工具栏（Session 下载钮旁）新增折叠按钮，收起底部输入区后消息阅读区最大化（约 +20% 可视高度）；折叠时底部保留「✏️ 点击输入消息」细条一键唤回；折叠偏好跨会话记忆。
+
+### 🐞 修复
+
+- **iOS Safari 键盘弹起时聊天输入框上下跳动**：输入区为 sticky 吸底布局，键盘弹起时随 visual viewport 收缩反复重排抖动——现键盘弹起时固定输入框所属滚动容器高度，键盘收起后还原，仅 iOS 生效、不依赖宿主类名。
+
+---
+
+## [v2.10.7] - 2026-09-08
+
+### 🐞 修复
+
+- **修复 Cloudflare 固定域名（Token 模式）隧道秒退**（issue #35）：v2.10.6 引入的 `--no-autoupdate` 参数位置错误（写在 `run` 之后）导致 cloudflared 报 `Incorrect Usage` 秒退、固定域名隧道永远起不来（免费临时隧道不受影响）。已改为放在 `run` 之前，与临时隧道分支保持一致。
+- **确定性配置错误直接提示**：`Incorrect Usage` / 无效 Token 等配置错误不再误判为"意外退出"退避重连 12 次，而是直接置 error 显示配置错误原因，便于定位问题。
+
+### ✨ 优化
+
+- **Cloudflare 固定域名配置区新增教程入口**：「查看 Cloudflare 固定域名申请与配置教程」链接，覆盖账号注册 → 域名接入 → 创建固定隧道 → 复制 Token → 绑定子域名（Public Hostname）→ 填回面板的完整图文步骤，中英文菜单对照。
+
+---
+
+## [v2.10.6] - 2026-09-07
+
+### 🐞 修复
+
+- **Cloudflare 隧道崩溃后自动恢复**（issue #34）：进程意外退出（崩溃 / OOM / 误杀 / cloudflared autoupdate 自替换）或启动失败后不再"死透无人管"——现按 5s 起步的指数退避自动重启（封顶 5min、12 次上限），恢复连接后计数清零；面板可随时点击「关闭 / 停止重连」取消自愈。
+- **禁用 cloudflared 24h autoupdate 自替换**：spawn 注入 `--no-autoupdate` + `NO_AUTOUPDATE=true` 双保险；自管理二进制增加版本钉死校验，已被自替换成新版的会自动回滚重下（版本控制权留在插件手里）。
+- **修复重启后隧道不自动恢复**：插件卸载 / 服务重启不再经 `dispose` 把隧道的「随 DSH 启动自动开启」悄悄改成关闭——此前会导致公网入口在重启后失联、需人工到面板救回。
+- **修复自建隧道公网 URL 缺失结尾斜杠返回 400**：隧道服务端前缀剥离需保留 origin-form，公网地址无 `/` 时不再 400。
+
+### ✨ 优化
+
+- **公网隧道页重构**：当前生效的访问地址置顶为「公网访问入口」总览卡（大号地址 / 复制 / 二维码可折叠 / 开·关·重置一目了然，运行中高亮）；Token / 固定域名 / 自建服务器 / 外部登记等低频配置收进默认折叠的「隧道配置」分组——页面不再三张卡片堆叠，重连中状态也不从入口消失。
+- **远程管理锁屏按实际密码类型提示**：仅设置访问密码（未设独立管理密码）时，锁屏醒目提示「使用访问密码解锁」，placeholder / 忘记密码引导 / 解锁弹窗同步区分，不再误导输入不存在的"管理密码"。
+
+---
+
+## [v2.10.5] - 2026-09-06
+
+### 🐞 修复
+
+- **修复「仅密码登录」模式自我锁死**：`password_only` 模式在尚未设置任何密码时，服务端会拒绝一切登录（防空白登录），而管理员因进不去面板也无法设置密码 → 永久死锁。现未设密码时放行（与「扫码+密码」默认模式一致——没有可校验的哈希即无秘密可保护），让管理员能进入面板完成密码初始化；设置密码后门禁才真正生效（错误密码会被拒绝）。
+- **修复无密码时找不到设置密码入口**：此前"外部访问门禁"卡片（含访客访问密码输入框）仅在安全防护已开启时渲染；未开启防护时面板没有密码输入框，用户先开防护再想设密码就会被卡。现只要系统**尚未设置任何密码**，密码设置区就始终显示。
+- **切换「仅密码」模式 / 开启防护的引导**：UI 在切换到 `password_only` 或开启防护时若尚未设密码，会就地弹窗引导先设置访问密码；服务端 `authUpdateConfig` 同步增加守卫——无密码时禁止开启 `password_only` 防护（除非同请求携带新密码），双保险杜绝再次自我锁死。
+
+---
+
+## [v2.10.4] - 2026-09-05
+
+### 🐞 修复
+
+- **全新安装未设密码时远程访问不再被假锁屏挡住**：此前远程打开设置面板会强制要求输入"管理密码"，而系统尚无任何密码可校验（任意输入都放行）；现仅当已配置密码或策略为「仅限本机管理」时才上锁，无密码时直接进入面板并引导先设置访问密码（issue 反馈）。
+- **修复 Telegram 代理在 Node ≥ 24 下不生效**（issue #32）：自定义 `createConnection` 作为 `https.Agent` 构造参数会被 Node ≥24 静默忽略（回退到直连），导致需代理才能访问 api.telegram.org 的网络环境下网关永远连不上且无任何报错。改为构造后赋值实例属性，CONNECT 隧道在 Node 22/24 均生效。
+- **修复移动端抽屉误关**（issue #31）：点击 workspace 分组名（projectRow 同样带 `role="treeitem"`）会误触发会话行收起逻辑，抽屉在 ~100ms 后自动关闭。closest 选择器移除 `div[role="treeitem"]`，会话行收起、分组展开/收起的交互恢复正常（长按检测同步修复）。
+- **自建隧道会话剥离支持 gzip 响应**（PR #29）：DSH web 默认 gzip 压缩，此前 `session.list`/`session.history` 的 gzip 响应直接 `JSON.parse` 失败导致大字段剥离失效、完整巨响应原样传输；现先 gunzip 再剥离。
+- **目录选择弹窗深色模式适配**（PR #29）：`--dsw-alias-brand-primary` 在深色模式下为白色导致按钮/提示背景错乱，改用静态蓝并补齐深色变量覆盖。
+- **WebSocket Ping/Pong keepalive**（PR #29）：自建隧道裸 TCP 转发不再透传 Ping 帧，DSH 每 2s 发 Ping 收不到 Pong 会 terminate；现于帧层自动回 Pong 保持长连接。
+
+### ✨ 新功能
+
+- **自建隧道 SSE 流式传输**（PR #29）：隧道协议新增 `response-start/chunk/end` 流式分片，SSE 事件流不再因"永不 end"而超时截断；安装脚本同步支持。
+- **远程/移动端禁用下拉刷新**（issue #30）：注入 `overscroll-behavior-y: none`，避免移动浏览器下拉误触导致整页重载丢失会话与输入。
+
+---
+
+## [v2.10.3] - 2026-09-03
+
+### ✨ 新功能
+
+- **兼容 DSH 原生端口直连（3080）**（issue #28）：此前本机用 `http://127.0.0.1:3080`（DSH 原生端口）打开面板时，因 loopback-token 端点仅暴露在代理端口 3082、且 CORS 白名单不含原生端口来源，管理功能会被误判为「远程」而锁定（local_only 策略下）。现在原生端口页面可跨域回读管理员令牌，直连与走代理行为一致；CORS 仍收敛，仅回显白名单来源。
+
+### 🐞 修复
+
+- **修复代理响应头透传问题**：反向代理与 WebSocket 升级路径现会剥离 hop-by-hop 头（transfer-encoding/connection 等），并对 WS 101 响应做白名单过滤，避免上游注入任意头或客户端解析异常。
+- **修复 QQ 流式消息发送**：首片失败时不再补发「全新流式消息」造成重复，直接降级单条 Markdown；引用机器人消息自动开新会话不再依赖固定 100ms 等待（消除竞态）。
+- **修复微信网关轮询竞态**：stop/restart 时通过 AbortController 立即中断进行中的长轮询，避免新旧 poller 并存触发 iLink 独占锁（403）。
+- **修复飞书群聊审批按钮被误拦**：群聊按「群」整体授权（与 QQ 群模型一致），群内成员可点按钮决议；单聊仍严格校验发起者本人。
+- **会话列表/历史大字段剥离覆盖全部公网入口**：session.list / session.history 的大字段剥离不再仅限自建隧道，Cloudflare 隧道、局域网、外部登记隧道同样生效（社区 PR #27 扩展）。
+
+### 🔒 安全
+
+- **[SEND_FILE] 外发白名单**：AI 输出携带的 `[SEND_FILE: 路径]` 指令现仅允许发送会话工作目录内的文件，并拦截 `.ssh`/`.credentials`/`.env` 等敏感路径，防止模型被诱导后外发任意本地文件。
+
+### 🧹 内部优化
+
+- **未设密码高危告警**：开启访问认证但尚未设置任何密码时，设置页顶部显示醒目风险提示。
+- **自建隧道安全须知**：README（中/英）明确隧道公网入口无独立认证、必须配合本地访问认证使用。
+- 版本探测失败改为 10 分钟退避重试；版本检查结果 10 分钟 TTL 缓存，减少外网请求。
+- 清理 Telegram 死代码（无调用点的审批卡片方法）。
+- 新增 issue #28 回归测试，全量单测通过。
+---
+
+## [v2.10.2] - 2026-09-01
+
+### ✨ 新功能
+
+- **外部已部署隧道登记**（issue #25）：自行部署 cloudflared（Docker 等）的用户可在面板登记公网地址，展示二维码与入口，插件不再重复下载管理
+
+### 🐞 修复
+
+- **修复会话列表/历史加载问题**：自建隧道下 session.list 502 修复 + 会话历史载入提速（社区 PR #27）
+
+---
+
+## [v2.10.1] - 2026-09-01
+
+### 🧹 说明
+
+- 无代码变更：修正 npm 包内升级提示（releaseNotes）措辞，与 v2.10.0 发布说明保持一致（仅突出新增功能，不再罗列内部修复细节）。
+
+---
+
+## [v2.10.0] - 2026-09-01
+
+### ✨ 新功能
+
+- **新增「管理保护」独立开关**：与访问认证解耦的独立安全开关（安全认证页可切换）。此前远程锁屏依附于访问认证开关，关闭访问认证后管理保护随之失效；现在两者完全独立，远程设备的管理权限始终受「管理保护」约束，仅凭管理密码可解锁。
+- **面板显示 DSH 宿主版本**：版本条新增灰色 `DSH vX.Y.Z` 标签（服务端惰性探测 `dsh --version` 并缓存，零轮询开销），与插件版本并排展示。
+
+### 🐞 修复
+
+- 修复远程锁屏/解锁流程的多处问题：会话失效（DSH 重启/过期）后自动跳回登录页重新登录，不再困在锁屏；锁屏状态下可正常输入管理密码解锁；关闭访问认证后锁屏仍生效、且不再误要求密码；远程首次进入设置页即显示全屏锁屏；目录选择器解锁不再卡死。
+
+### 🧹 内部优化
+
+- 统一 adminToken 缓存为单一来源，删除死代码与重复实现（unlock-manager 未接入 API、组件内冗余 state、重复的 loopback-token 逻辑等）。
+
+---
+
+## [v2.9.0] - 2026-08-31
+
+> ⚠️ **升级前必读**：本次为大规模更新（覆盖安全加固、并发模型、代码结构重构），改动量远超以往版本，尽管已通过 165 项自动化测试与多轮实测，仍可能存在未知问题。建议：
+> - 升级前备份 `~/.dsh/dsh-bridge/config.json`（可在面板「运维监控 → 备份恢复」导出）；
+> - 升级后重点验证：各 IM 平台收发消息、审批流程、隧道连接；
+> - 如遇异常可回退至 v2.8.7，并欢迎携带日志提交 Issue：https://github.com/wenbin-wb/dsh-bridge/issues
+>
+> **行为变更**：① 群聊自动授权默认关闭（可在平台卡片勾选开启）；② 未设置密码时，备份导出/导入、隧道配置等高危操作将要求先设置密码；③ IM 发起的审批只在 IM 决议，Web 发起的只在 Web 弹窗。
+
+### 🛡️ 全面安全加固与代码质量大修（全仓库深度代码审查落地）
+
+- **🔐 安全加固**：
+  - 访问/管理密码哈希升级：PBKDF2-SHA256 迭代 10,000 → 600,000（OWASP 建议），哈希格式带算法版本前缀，存量旧哈希在下次成功登录时透明升级，无需重设密码；
+  - 管理密码解锁防爆破：连续 5 次失败锁定 60 秒；
+  - 未设置任何密码时，备份导出/导入、隧道配置与启动、远程目录浏览、添加工作区、插件升级、重启 DSH 等高危操作强制要求先设置密码（**行为变更**）；
+  - 本机特权 Token 端点（loopback-token）CORS 收敛：仅放行本插件生成的面板来源（回环 / 局域网 IP / 隧道地址），不再使用 `*`，收敛 Firefox/Safari 下的 drive-by 令牌窃取面；
+  - 隧道令牌掩码保护：非管理员视图的 `******` 掩码回显不再覆盖真实 Token，未变更字段不上传；
+  - 登录页与锁屏页不再向访客泄露救急重置明文命令，改为指向文档；修正 README 救急路径笔误（`~/.dsh-bridge` → `~/.dsh/dsh-bridge`）。
+- **🐞 稳定性修复（含 eslint 静态分析新抓出的 4 个必崩 BUG）**：
+  - 修复 iOS 16 等旧移动端浏览器访问面板发送消息报 `AbortSignal.any is not a function (internal)` 的问题：DSH 网页客户端用该 API 组合请求超时/取消信号，而 Safari 17.4 才支持；代理注入页自动补齐兼容垫片（服务端运行在低版本 Node <20.3 时同样自动垫片并告警引导升级）；
+  - 修复微信入站媒体下载 100% 抛 ReferenceError（`downloadMedia` 缺失 `fetch()` 调用，旧测试未覆盖）；
+  - 修复 QQ 流式输出失败后补发收尾必崩（`streamMsgId` 作用域错误）；
+  - 修复前端「查看手动升级命令」渲染崩溃（`UpgradeCommandRow` 组件缺失）；
+  - 修复插件卸载时 `session/event` 监听器永不解绑（dispose 清理闭包引用错误，幽灵事件持续外发）；  - 修复微信/QQ 等 IM 端 `/list`、`/sessions`、`/use` 命令报 `cannot get property "sessionProjCache" without inject` 的问题：宿主 cordis 上下文禁止插件读取未在 inject 中声明的属性，会话列表的内存注入点改为安全探测、失败自动回落磁盘存储；
+
+  - 修复出站 digest 状态 Map 无限增长、自建隧道启动失败僵尸占用、cloudflared 意外退出后状态失真、`/use N` 编号与会话列表显示错位、`/status` 缺 reason 崩溃等问题。
+- **🚦 并发模型修复**：
+  - 出站消息统一串行队列：心跳 / 正文 / 审批卡片 / 媒体不再交错乱序，消除 QQ 流式 replace 共享 `_msgSeq` 的并发冲突；
+  - 入站消息串行化 + 出站事件绑定发起轮次的会话 peer，杜绝 A 任务进行中 B 来消息导致回复串到 B 窗口的跨用户串扰；
+  - 审批发起者校验：群聊中其他成员回复 `/yes` 无法代批工具执行；
+  - 群聊自动授权改为显式配置 `groupAutoApprove`（**默认关闭**，行为变更：白名单非空时陌生群不再因 @机器人 一次即获授权）；
+  - 配置持久化读-改-写整事务化，多平台并发保存不再丢失更新；  - **修复 IM 端收不到审批卡片的问题**：DSH 宿主的审批分发是顺序瀑布（web GUI 认领监听器先行否决），桥接审批桥此前永远没有机会执行，导致微信/QQ 等 IM 端工具审批全部以"用户未批准"失败；现以 prepend 方式注册到分发链最外层，并采用严格归属模型：IM 发起的轮次审批只在 IM 决议（不再并行打开 Web 通道，杜绝 Web 端弹窗在 IM 决议后永久残留），Web 发起的轮次则完全交由 GUI 处理；支持任务停止时同步取消待决审批；
+同步修复飞书：其遗留的专属审批桥（未 prepend、无归属门槛）导致飞书发起的审批永远收不到卡片而 Web 反而弹窗，现已对齐统一归属模型并保留飞书原生按钮卡片 UX（按钮决议同样校验发起者）；
+
+  - 平台配置恢复统一工厂化，消除四段复制与启动期竞态回滚。
+- **🧹 代码质量与工程化**：
+  - 引入 eslint（flat config）与 CI：Node 22/24 × Ubuntu/Windows 全矩阵执行 lint + 单元测试；
+  - 提交 `package-lock.json` 锁定依赖树，清理 pnpm 残留配置；
+  - `conversation-bridge.js`（1642 行）按职责拆分为 `message-split` / `dsh-storage` / `session-catalog` / `commands` 四个模块；
+  - 主插件平台装配循环化；删除 7 个废弃 `wechat*` RPC 端点、`BRIDGE_MARK` 等死代码；
+  - 微信 context-token 落盘改为防抖合并写（此前每条入站消息同步读写盘）；
+  - 自建隧道响应增加 32MB 上限（防内存拖垮）+ gzip 压缩异步化（不再阻塞事件循环）。
+
+---
+
+## [v2.8.7] - 2026-08-30
+
+### 🛜 多网卡智能切换与 macOS 升级与隧道自愈加固
+- **🛜 支持局域网多网卡可视化切换与持久化 (Issue #5)**：
+  - 自动探测并列出宿主机所有可用物理网卡与虚拟网卡（Wi-Fi、以太网、WSL、VMware、Docker 等），支持识别网卡类型与优先级推荐；
+  - 在局域网控制台提供网卡下拉切换器，切换后即时重新生成局域网链接与二维码，并自动记忆持久化保存，彻底解决多网卡/WSL 环境下移动端扫码 IP 无法互通的问题；
+- **🍏 加固 macOS 一键平滑升级**：
+  - `upgradePlugin` 自动补全 macOS GUI / 后台环境下缺失的系统 `PATH` 环境变量（自动兼容 `/opt/homebrew/bin`、`/usr/local/bin`、`~/.nvm/...` 等）；
+  - 自动优先绑定当前运行中 Node.js 同级目录下的 `npm`/`npx` 二进制绝对路径，杜绝 `spawn ENOENT` 升级失败；
+- **🛡️ 优化 macOS Cloudflared 二进制探测与隔离自愈**：
+  - 启动时优先扫描系统 `PATH` 与 Homebrew 安装的 `cloudflared` 全局二进制；
+  - 网络下载解压后自动通过 `xattr -d com.apple.quarantine` 移除 Gatekeeper 隔离标记，并加入 `--version` 运行期校验与自愈。
+
+---
+
+## [v2.8.6] - 2026-08-30
+
+### 📱 移动端交互适配重构 & 隧道保活与传输优化
+- **📱 移动端工作区体验重构与多途径秒级回切**：
+  - 修复移动端工作区面板（Workbench / `dsh-better-sidebar` / 任务管理）遮盖聊天对话与收起后白屏残留问题；
+  - 引入严密的显隐状态机（`dsh-workbench-open`），打开面板时在 Tab 栏常驻 **`✕ 返回对话`** 蓝色操作胶囊；
+  - 提供多途径极速回切：支持点击「返回对话」按钮、点击顶部 Header 会话标题、或在左侧抽屉切换会话秒级返回对话流；
+- **🗂️ DSH 原生收起图标深度适配与双向开合**：
+  - 在移动端侧边栏抽屉顶部 Logo 栏完整集成并复用 DSH 原生自带的收起图标（`[|`）；
+  - 支持点击主界面 `≡` 汉堡菜单流畅滑出抽屉、点击原生收起图标/点击会话/轻触遮罩丝滑收回抽屉；
+- **🖥️ PC 桌面端严格隔离与零侵入**：
+  - 通过媒体查询与运行期断点双重守卫，确保 PC 桌面端（`> 768px`）100% 保持官方原生多列分栏布局与纯净体验，无任何样式污染与多余组件；
+- **🛡️ Cloudflared 隧道守护进程自愈与自动重启**：
+  - 修复 Cloudflared 进程异常退出后无法自动拉起的问题，增加子进程退出监听与指数退避自动重连机制，确保长时间公网访问不断连；
+- **⚡ 自建隧道 SSE 稳定性与数据传输优化**：
+  - 修复弱网环境下 SSE 断线重连问题，精简 Session 列表超大数据负载传输，显著降低移动端带宽占用与弱网延迟。
+
+---
+
+## [v2.8.5] - 2026-08-27
+
+### 🎯 产物文件推送改为 AI 指令驱动 & 修复 IM 平台断开连接问题
+- **🎯 显式文件发送协议**：由 AI 通过 `[SEND_FILE: <路径>]` 显式驱动文件直传，杜绝修改代码时的文件误发风暴；
+- **🧹 聊天正文自动净化**：自动剔除聊天窗口中的文件发送指令，保持聊天气泡清爽；
+- **🔌 修复 IM 断开连接失效**：修复 QQ 等网关断开连接时 WebSocket 事件悬挂问题，断开后彻底阻断入站消息与出站回复。
+
+---
+
+## [v2.8.4] - 2026-08-26
+
+### 🗂️ 会话列表 Web 端 1:1 深度对齐与归档过滤修复
+- **🗂️ 严格按工作区账本对齐会话列表**：全面采用 DSH 官方工作区账本排序规则，自动过滤子代理派生会话、空白草稿与已归档会话，彻底解决磁盘历史孤立会话冗余列出的问题，保持 IM 端与 Web 端侧边栏 1:1 结构一致与编号精准对应。
+
+---
+
+## [v2.8.3] - 2026-08-26
+
+### 📱 微信与全平台 IM 文件收发链路全面修复与深度兼容
+- **📱 微信 iLink 官方媒体传输协议完全对齐**：
+  - 修复 `getuploadurl` 媒体类型映射，确保文件上传请求采用标准 `UploadMediaType.FILE = 3`，微信服务端正确识别文件类型与大小；
+  - 严格采用官方规范对 `CDNMedia.aes_key` 进行 `base64(hex_string)` 编码，彻底解决微信移动端/电脑端解密失败报「文件已过期/下载失败/0B」的深层问题；
+  - 精简规范 `file_item` 结构并对齐 `encrypt_type: 1`。
+- **🤖 QQ 机器人富媒体文件直传与显示修复**：
+  - 支持 `file_type: 4` 通用文件传输，适配 QQ OpenAPI v2 文件格式校验（解决此前类型不符导致的 850019 拦截）；
+  - 显式传递 `file_name`，彻底消除 QQ 聊天界面将文档显示为「未命名」的问题；
+  - 自动识别群聊与单聊端点路由（`/v2/users/{openid}/files` 与 `/v2/groups/{group_openid}/files`）。
+- **🌐 微信会话凭证（context_token）持久化机制**：
+  - 捕获微信入站消息时自动将实时安全会话凭证持久化落盘（`wechat-context-tokens.json`），并在服务启动与重启时自动载入，彻底避免凭证在重启后丢失；
+  - 完善 `ret: -2` / `prepare failed` 过期感知，当用户重新发消息时自动刷新续期。
+- **📢 多平台多端共享会话广播**：
+  - 优化同一工作区多端共享会话的广播逻辑，当任一客户端（飞书/QQ/Telegram/Web）触发生成文件时，各平台桥接器自动回退至已授权用户，实现产物文件多端同步直传。
+
+---
+
+## [v2.8.2] - 2026-08-26
+
+### 🚀 微信/IM 本地生成文件全域探测与直接推送
+- **📁 全域文件智能探测与提取**：全面支持从 PowerShell/Bash 终端脚本（`New-Item`、`Set-Content`、`Out-File`、`>`）、工具调用参数及回复文本中自动探测提取生成的文件，并结合会话工作区目录自动解析为绝对路径；
+- **🌐 微信官方 CDN 媒体上传链路修复**：严格对齐腾讯 iLink 官方 CDN `/upload` 路由子路径与 `encrypted_query_param` / `filekey` 鉴权参数，彻底解决此前上传失败的问题；
+- **💬 微信与各 IM 原生文件气泡推送**：任务结束自动将 txt/pdf/docx/xlsx/zip/png 等产物推送到聊天界面，支持直接下载查看与转发。
+
+---
+
+## [v2.8.1] - 2026-08-26
+
+### 🛡️ 微信/IM 消息分块保护与流式体验修复
+- **🛡️ 修复消息被切成 20 字符碎片的问题**：排查并修复历史配置中 `maxMessageChars` 异常写入 `20` 导致的聊天框逐句高频切块分发问题；
+- **⚙️ 全链路字符数下限安全防御**：在会话桥基类、各平台 Service 配置接口及启动加载链路中增加强制安全下限（`< 200` 自动回退为平台标准默认容量），彻底杜绝异常分块；
+- **💬 微信与各 IM 平台体验恢复**：恢复完整 Markdown 回复、段落与代码块的原生一次性聚合推送。
+
+---
+
+## [v2.8.0] - 2026-08-25
+
+### 📱 移动端体验革新、远程工作区管理与全面安全加固
+- **🗂️ 远程工作区网页选择器**：彻底解决手机/远程设备点击「添加工作区」在电脑端静默弹窗、移动端无感知的痛点；自动唤出响应式底部抽屉/弹窗树形目录浏览器，支持盘符（C/D 盘）与快捷目录直达与手动路径跳转；
+- **🖥️ 本机电脑无感智能分流**：本机电脑（localhost / 127.0.0.1 / Electron 桌面客户端）点击添加工作区直接调用系统原生文件夹选择对话框，仅在移动端/远程访问时呼出网页选择器；
+- **📱 移动端视觉与布局体验深度优化**：
+  - **顶部固定导航栏**：会话标题统一提升至顶部导航栏正中央，加粗居中显示，彻底消除顶部空白；
+  - **第二行会话工具栏**：智能路由/子代理徽标与 28px 圆形纯图标 Session Log 下载按钮两端规整排列，呼吸感十足；
+  - **底部输入框工具栏**：弹性自适应排版，彻底解决移动端与窄屏下权限预设与模型选择器重叠碰撞问题；
+- **🔐 全方位安全审计与深度加固**：
+  - **RPC 端点鉴权**：文件树、驱动器与工作区注册 RPC 端点增加 `checkAdminAuth` 管理员认证校验；
+  - **路径穿越与系统黑名单**：拦截 `C:\Windows\System32`、`/etc/shadow`、`/root/.ssh` 等敏感目录访问，检测软链接逃逸；
+  - **滑动窗口速率限制**：针对文件系统探测接口实施每用户每分钟限流防护；
+  - **IM 命令权限拦截**：非管理员用户禁止通过 `/addworkspace` 随意添加工作区。
+
+---
+
+## [v2.7.2] - 2026-08-25
+
+### 🗂️ 远程工作区网页选择器与全平台 `/addworkspace` 指令
+- **🗂️ 远程工作区网页目录选择器**：彻底解决手机/远程设备点击「添加工作区」在电脑端静默弹窗、移动端无感知的痛点；在浏览器内直接呈现高颜值文件夹浏览弹窗；
+- **💾 驱动器与快捷目录一键直达**：智能探测 Windows 盘符 (`C:\`, `D:\` 等) 与常用根目录（桌面、IdeaProjects、Projects 等），支持可视点选与手动路径输入；
+- **🎯 原生点击事件捕获拦截**：在 DOM 捕获阶段拦截原生「添加工作区」/「打开文件夹」按钮点击，无缝转由网页选择器承接；
+- **🤖 IM 机器人 `/addworkspace` 指令**：微信 / QQ / 飞书 / Telegram 全面支持 `/addworkspace <电脑绝对路径>`，随时随地在聊天框添加项目工作区。
+
+---
+
+## [v2.7.1] - 2026-08-25
+
+### 🛠️ Windows 一键升级与自建协议修复
+- **🛠️ 修复 Windows 平台一键升级 `spawn EINVAL` 错误**：适配 Windows 下 `.cmd` 批处理文件派生子进程的执行环境；
+- **🌐 修复自建隧道 WebSocket 诊断协议报错**：自动映射 `ws:`/`wss:` 协议进行端到端探测；
+- **🛡️ 并发防抖与状态优化**：优化多端并发请求与状态重连。
+
+---
+
+## [v2.7.0] - 2026-08-25
+
+### 📊 运维监控看板、网络诊断与会话重命名
+- **📊 宿主系统与运行看板**：实时监控 CPU 核心与型号、DSH 运行时间（Uptime）、Node 堆内存占用与系统总内存彩色占用条；
+- **🔍 网络连通性一键诊断**：全面探测本地反向代理端口、局域网 IPv4、Cloudflare Anycast 边缘网络、自建隧道部署服务器与国内 npmmirror 镜像源连通性及延迟；
+- **🗄️ 全局配置备份与恢复**：支持一键导出/导入插件配置 JSON 文件（涵盖平台凭证、白名单与安全认证规则），支持跨设备迁移；
+- **🔄 DSH 服务平滑重启**：升级后或运维面板内支持一键平滑重启 DSH 进程，前端自动健康探测轮询并在重启成功后无缝重连刷新；
+- **🏷️ IM 机器人会话重命名**：微信、QQ、飞书、Telegram 均支持 `/rename <新标题>` 指令，实时修改当前活动会话标题并同步更新 Web 抽屉；
+- **🎨 界面与体验打磨**：Tab 栏彻底隐藏原生灰色横向滚动条保留流畅滑动手势，卡片间距规范化防重叠，深色模式原生深度适配；
+- **🛡️ 并发与竞态保护**：Telegram/WeChat/QQ 网关 start/stop 增加 in-flight 串行化防抖锁，ConversationBridge 增加会话恢复并发竞态防重锁。
+
+---
+
+## [v2.6.1] - 2026-08-25
+
+### 🌐 公网隧道与专属域名重大升级
+- **🔄 隧道开机自启与状态记忆**：记录 Cloudflare 隧道与自建隧道运行状态，DSH 重启后自动无感拉起；
+- **🌐 Cloudflare 固定域名（Token 模式）**：支持 Cloudflare Named Tunnel（Zero Trust Token），绑定自定义专属域名（如 `dsh.yourdomain.com`），**重启后 URL 永久固定不变**；
+- **⚡ 零门槛临时模式兼容**：未配置 Token 时维持 1 秒极速免登录临时随机域名；
+- **⚙️ 控制台开关**：公网隧道卡片右上角新增「随 DSH 启动自动开启」复选框与折叠式高级 Token 配置。
+
+---
+
+## [v2.6.0] - 2026-08-24
+
+### 📱 移动端触控交互全面升级
+- **🎨 顶栏与输入框重构**：极简通透顶栏，大圆角胶囊输入框，提供原生 App 般的丝滑手感；
+- **🖐️ 长按（Long Press）呼出菜单**：侧边栏会话行支持长按（≥380ms）触觉震动反馈并自动呼出操作菜单（重命名/分叉/归档），支持边缘手势滑动开闭抽屉；
+- **💊 状态药丸防换行**：全面修复手机小屏幕下「运行中」等状态药丸徽标断行换行问题；
+- **✨ 更新日志预览**：版本更新检查卡片直观渲染新版本特性亮点（Release Notes）。
+
+---
+
+## [v2.5.5] - 2026-08-23
+
+### 🛠️ 缺陷修复与稳定性提升
+- **💓 心跳泄漏修复**：修复 IM 任务结束后心跳定时器未彻底注销的潜在泄漏问题；
+- **🧹 生命周期清理**：强化平台会话节点（Conversation Node）生命周期管理，连接断开时自动清理关联资源；
+- **🛡️ 稳健长连接**：提升微信、QQ、飞书与 Telegram 机器人在长周期运行时的并发稳定性。
+
+---
+
+## [v2.5.4] - 2026-08-23
+
+### 📦 依赖规范化
+- **🧩 规范化依赖**：将 DSH 共享宿主包依赖调整为 `peerDependencies`，杜绝多实例冗余依赖问题；
+- **📉 体积瘦身**：进一步优化 npm 包体积与生态集成规范；
+- **📖 文档同步**：同步更新快速安装命令与版本号指引。
+
+---
+
+## [v2.5.3] - 2026-08-23
+
+### 🚀 稳定性与依赖优化
+- **📦 内置预编译飞书 SDK**：内置预打包编译飞书 SDK（消除 `protobufjs` postinstall build script 报错）；
+- **⚡ 纯净安装**：在 pnpm 11、npm 及 yarn 下实现 100% 纯净、无告警的一键秒级安装体验；
+- **🛠️ 隧道服务端脚本增强**：优化一键部署脚本国内镜像源容错机制。
+
+---
+
+## [v2.5.2] - 2026-08-23
+
+### ✨ 核心更新与优化
+- **🔑 本地管理免密直通**：优化 Localhost 物理回环访问判定逻辑，提升本地开发与管理体验；
+- **🔐 交互式解锁弹窗**：新增统一的管理员解锁弹窗组件，支持密码解锁与状态实时同步；
+- **📱 移动端 Polyfill**：增强移动设备浏览器环境兼容性；
+- **📸 视觉与文档**：更新全套控制台高清界面实机截图与架构说明。
+
+---
+
+## [v2.5.1] - 2026-08-23
+
+### 🛡️ 深度加固安全防护与修复潜在风险
+- **🔐 Secret Token 严格脱敏**：控制台公开状态彻底隔离，未授权访客不可见明文；
+- **🚫 token_only 模式严格禁止密码登录**；
+- **🛡️ RPC 服务端管理员权限校验**：强化关键配置修改与敏感操作鉴权；
+- **⚡ Scope 防护范围 Header 伪造防范**。
+
+---
+
+## [v2.5.0] - 2026-08-23
+
+### 🔐 全新访问安全认证体系与 Tab 面板
+- **🛡️ 双密码管理**：访客密码与管理员独立密码；
+- **🚨 三重容灾保命体系**：支持 Localhost 物理特权免密、应急 reset-auth 文件恢复机制；
+- **🎛️ Tab 结构升级**：局域网、公网隧道、IM 机器人、安全认证独立 Tab 组织。
+
+---
+
+## [v2.4.0] - 2026-08-23
+
+### ✈️ 接入 Telegram 官方机器人
+- 支持 Telegram Bot API、打字机流式输出、原生指令菜单与交互卡片。
+
+---
+
+## [v2.3.0 ~ v2.3.3] - 2026-08-22
+
+### 🐦 接入飞书官方长连接机器人
+- 支持 Card 2.0 原生流式打字机、双端并发审批、多平台统一消息架构重构。
+
+---
+
+## [v2.2.0 ~ v2.2.9] - 2026-08-20 ~ 2026-08-21
+
+### 🐧 QQ 官方机器人全面升级
+- 支持 OpenAPI v2、指令面板、自定义菜单、全回复流式 Markdown 与群聊交互。
+
+---
+
+## [v2.0.0] - 2026-08-20
+
+### 🚀 多平台架构重构
+- 引入统一 Platform 抽象基类与 ConversationBridge。
+
+---
+
+## [v1.0.0 ~ v1.2.3] - 2026-08-19
+
+### 💬 微信 Bot 初代上线
+- 支持微信 ClawBot/iLink、局域网访问、Cloudflare 临时公网隧道与自建隧道。