@marktrue/dsh-mobile-remote 3.2.1-alpha.1 → 3.2.1-alpha.2-app

package/docs/09-compatibility.md

@@ -1,195 +0,0 @@
-# 09 兼容性说明（Compatibility）
-
-> 版本：v3.2.0（用量与额度；机制基线 0.1.2-rc.1） · 面向：开源使用者 / 二次开发 / 多设备部署
-
-本文回答两个问题：**App 在哪些手机上能跑**，以及**插件在什么样的 Harness 上能跑**。
-
----
-
-## 1. 版本要求
-
-| 组件 | 要求 |
-|---|---|
-| 桌面端 DSH（Harness） | **v3.1.6 起同时适配两代宿主 API：`0.1.x` 与 `0.2.x`**（见 §2.5）；**`0.2.1` 起进程内网关调用强制 Peer，由 §2.6 适配（issue #34）**。机制基线：`0.1.2-rc.1` 服务包 = DSH Desktop v2.0.5（approval/request 瀑布 answerer + `$events` 远程事件双端审批 + RPC 网关，见 §2）；更早的 `0.1.1-rc.2` 基线 = v2.0.2 起适配。**不按宿主版本号硬拦截**，按能力探测适配（ADR 0017） |
-| dsh-mobile-remote 插件 | **v3.0.0 基线；v3.2.0+ 才提供用量与额度**；`/m/api/diagnostics` 可自检 |
-| 手机 App（Android） | v3.0.0 基线（用量与额度需 v3.2.0+；与插件同版本 = 完美配对）；不同版本可用但"谁旧谁吃亏"，详见 README「版本与兼容」；Android 7.0+、64 位机型 |
-| 字段级兼容（v3.1.0 候选） | `reasoning`/`title` 为纯增量字段：新插件+旧 App 无影响（忽略新字段）；新 App+旧插件自动回退（不渲染折叠块 / 悬浮球标题兜底短码）——任意组合均可使用 |
-| 字段级兼容（v3.1.1） | `/m/api/directories` 根视图新增 `sep`（服务端路径分隔符）；新插件+旧 App 忽略该字段即可（旧 App 在 WSL 上仍按 `\` 拼接，由服务端`normalizeServerPath` 归一化兜底，浏览/建夹/建会话均可用）；新 App+旧插件缺少 `sep` 时按根视图推断分隔符——任意组合均可使用 |
-| 用量与额度（v3.2） | 新插件+新 App 通过 `/m/api/account-usage` 显示 DeepSeek/Codex/OpenCode Go；旧 App 忽略新端点。新 App+旧插件进入该入口会显示“电脑端插件版本过旧”，不影响其它功能；升级插件后无需重新配置凭据 |
-| 悬浮球面板用量与额度（v3.2） | 新 App+新插件：面板展开时按需展示三来源区块（金额行文字 + 配额行细条/颜色），整块可点进详情页。新 App+旧插件：区块整体降级为原有单行余额（点击仍=去充值），其余面板功能不受影响；旧 App 忽略新端点。无新增服务端契约 |
-| Flutter 构建环境 | Flutter 3.35+（Dart SDK ^3.13） |
-
-**声明式兼容范围（`peerDependencies`）**：`@deepseek-ai/dsh-{credentials,llm,sandbox-policy,scope}` 声明 `>=0.1.0-rc.6 <0.3.0`。宿主 `@deepseek-ai/dsh-app-boot` 的 `evaluatePluginCompatibility()` 用 `semver.satisfies(runtimeVersion, range, { includePrerelease: true })` 判定（**prerelease 参与比较**），因此该范围同时覆盖 `0.1.x`、`0.2.0-rc.*` 与 `0.2.x` 正式版，而 `0.3.0+` 会被判为不兼容。上界**只用于声明可安装边界**，功能路径仍按能力探测（ADR 0017），不按版本号做功能门禁。
-
-**快速自检**：手机 App → 设置 → 环境诊断。`services` 一节列出每个内核服务是否存在；**v3.1.3+ 看 `checks.approvalMode`**（生效策略）与 **`checks.remoteEvents`**（`true` = `$events` 双端呈现通道就绪，`false` = both 降级 mobile 或配置即 mobile/desktop）；`notes` 说明当前审批策略实际语义与**任何非全绿的宿主能力**。
-
-**v3.1.6+ 新增两项宿主能力自检**（ADR 0017）：
-
-- `checks.hostCapabilities`：逐项给出三态——`ok` / `drift` / `missing`。`drift` 是**能力语义漂移**（服务在、调用不报错，但成员形状不是插件认识的样子），这正是 0.2.0 四处变更与 0.2.1 peer 收紧的形态，旧的两分法看不见它们。**`gateway.eventsPeer`（issue #34）** 专门覆盖"网关入口都在、但进程内 Peer 来源缺失"这一种漂移，原因码为 `gateway-peer-source-missing`。
-- `checks.hostGeneration`：插件**实际走了哪条代际路径**（`jobsCaller` / `settingsRead` / `wireStreamArgs` / `eventsPeer`），排查"为什么同一功能在两台机器上表现不同"时先看这里。`eventsPeer` 取值：`createPeer`（0.2.1+）/ `operatorPeer`（0.2.0 网关兜底）/ `legacy`（旧代 3 参开流不需要 peer）/ `none`（必失败）/ `unknown`（网关服务缺失，无法判定）。
-
-`services.apiProxy` / `checks.respondBridge` / `checks.frameBridge` **已随 v3.1.6 删除**：该服务自 `0.1.2-rc.1` 起就不存在，保留它们只会让人以为有一条可用的旧代降级通道。同样地，`/m/api/respond` 在待办不在本地清单时返回 `404 respond-not-pending`（此前返回 `503` 并归咎于"内核过旧"，属误导——真实原因通常是"另一端已先答"或"已超时"）。
-
----
-
-## 2. 内核耦合点与降级行为
-
-插件与 Harness 的耦合分三档：**硬依赖**（缺失 = 对应功能不可用）、**软依赖**（缺失 = 功能降级）、**可选**（缺失 = 自动禁用该功能）。插件对每个依赖都做了存在性探测，**任何一项缺失都不会让插件崩溃或影响其他功能**。
-
-### 2.1 服务（`ctx.get` / `ctx.inject`）
-
-| 服务 | 用途 | 档位 | 缺失时行为 |
-|---|---|---|---|
-| `webServer` | 挂载 `/m/api`、`/m/events`、`/m/qr.png` 路由 | 硬依赖（插件存在的意义） | v2.4 起守卫：纯 headless 形态下插件静默无操作，不崩进程 |
-| `sessions` | 会话列表/touch/创建/停止 | 硬依赖（内核核心） | 移动端会话功能不可用 |
-| `agents` | 会话创建、状态 | 硬依赖（内核核心） | 同上 |
-| `workspaceRegistry` | 工作区列表、会话归档（与 PC 端同一份状态） | 软依赖 | 归档/工作区筛选不可用；App 回退为 cwd 前缀分组（旧版兼容路径） |
-| `sessionProjections` | `turnOutline` 投影单元注册探测（轮次导航，决定 `capabilities.turnOutline`） | 软依赖 | 缺失或未注册 → 能力位 `supported: false`，App 退回「只用已加载轮次」，不按宿主机版本推断 |
-| `messageFeedback` | 消息 👍/👎（与 PC 端同一份） | 软依赖 | 反馈菜单隐藏/报错 |
-| `approval` | 权限策略读取（`setPolicy` 仅当存在时调用） | 可选 | 跳过策略写入 |
-| `credentials` | DeepSeek 余额查询 | 可选 | 回退环境变量 `DEEPSEEK_API_KEY`；都没有则余额不可用 |
-| `userQuestions` | （间接）问询链路 | 可选 | 无弹窗（同上） |
-| `approval/request`·`user-questions/request` 瀑布（0.1.2-rc.1+） | Agent 作用域 Cordis 瀑布，插件 answerer 应答（0.1.2 移除了 apiProxy 后的新机制） | 软依赖 | 手机弹窗功能不受影响；该机制是问询/审批的**唯一**现行路径 |
-| `typertGateway` `$events` 远程事件（0.1.2-rc.1+，`both` 模式） | 插件进程内 $events 客户端：瀑布经内核转发到网关后与桌面 GUI 同收事件副本、先答生效（issue #9 双端呈现） | 可选（v3.1.3） | `approvalMode: both` 自动降级为 mobile（手机在线独占），日志与诊断 notes 说明；**0.2.1+ 还要求显式进程内 Peer（§2.6）** |
-
-> ⚠ **approvalMode（v3.1.3，issue #9）语义**：`both`（默认）= 桌面 GUI 与手机同时弹卡、任一端先答即生效、另一端自动收卡（对齐 v3.1.1 帧桥体验；仅 0.1.2-rc.1+ 网关可用，旧宿主自动降级 mobile）；`mobile` = 手机在线独占应答（v3.1.2 行为），离线交桌面 GUI；`desktop` = 一律交桌面 GUI（手机不弹卡）。手机在场时待办 120s 无应答 fail-close（`unavailable` / 问询跳过），与 v3.1.2 一致。配置于 `cordis.patch.yml` → mobile-remote 行 `config.approvalMode`，重启生效。
->
-> ⚠ **apiProxy 帧桥已于 v3.1.6 整块删除**（issue #19）：该服务自 `0.1.2-rc.1` 起已从内核移除，`0.1.5` 与 `0.2.0` 内核树内均 0 命中。保留它的唯一效果是让读者以为存在一条可用的旧代降级通道。目前**两代宿主都不存在**该服务，问询/审批一律走上表的两个瀑布 + `$events` 双端呈现。
-
-### 2.2 事件与 RPC
-
-| 内核接口 | 用途 | 风险与降级 |
-|---|---|---|
-| `ctx.on("session/event")` | 消息流/通知聚合/上下文窗口/Conversation timeline | 事件形态随版本演进；未知类型进入通用事件卡，能力缺失时 App 回退摘要模式 |
-| `sessionQuery.readEvent`（可选） | Tool activity 与未知 Visible event 的按需无损详情 | 不存在时回退快照；旧历史详情明确显示不可用，不猜测重建 |
-| `sessionQuery.observeSession`（可选） | 投影感知的会话观察（轮次大纲，轮次导航） | 不存在时 `/m/api/turn-outline` 显式返回 `capability-missing`；不把「宿主不支持」误报成「该会话没有轮次」 |
-| `ctx.on("agent/status")` | 状态点（绿/橙） | 同上 |
-| `typertGateway`（`invokeRpc` / `stream` / `openWireStream` / `dispatchRpc`） | 全部内核 RPC 与 `$events` 双端审批通道 | **0.2.1 起必须显式传活 Peer（§2.6）**；漏传/传错时返回 `gateway/internal: …reading 'signal'`，由错误映射转成业务错误码（不再静默） |
-| `session.models` RPC | 模型目录（App 模型选择器） | 失败 → 目录为空，App 隐藏模型胶囊 |
-| `settings.update`（`agent-presets` / `permission` 命名空间） | 默认预设修改 | 与 PC 端同一写入通道；命名空间变更会导致设置失败（App 报错提示） |
-| `session.fork` | 消息分支 | 内核接口变化 → fork 失败提示 |
-| `agent.followup` / `session.cancel` | 发消息/停止 | 同上 |
-
-> ⚠ **子代理通知判定需要 `session.header.origin`（DSH ≥ 0.1.1-rc.2）**：通知聚合对子代理会话（`origin === "subagent"`）抑制完成/失败通知（与内核自身通知一致）。旧内核 header 无 `origin` 字段时，子代理完成/失败通知会被放行（不影响功能正确性，仅通知噪音）；fork 出的独立会话（无 origin）照常通知。
->
-> ⚠ **v3.1.0 候选新增字段（纯增量，无协议破坏）**：`assistant/message` 摘要的 `reasoning`（思维链正文，仅非空时下发，≤20000 字符）与 `/m/api/bootstrap` 的 `agents[*].title` / `sessions[*].title`（会话标题，空则兜底短码）。旧版 App 按 key 取值、忽略未知字段；旧版插件缺少这些字段时新版 App 自动回退（不渲染折叠块 / 悬浮球显示 id 短码）。两端任意组合均可正常使用。
-
-> ⚠ **Issue #1 时间线能力协商（纯增量）：** `/bootstrap` 与 SSE `hello` 的 `capabilities.eventTimeline` 声明 `detail`、`unknownEvents`、`callCorrelation` 等能力。新版 App 只在 `capabilities.eventTimeline.detail` 且事件摘要带 `detail.available` 时请求 `/event-detail`；能力是端点级声明，单事件仍可能因旧日志/离线而不可用。旧插件没有声明时继续使用已有摘要/历史路径，并把详情显示为不可用，不按插件版本号猜测能力。
->
-> ⚠ **当前界面降级与 dormant-session 依赖：** seeded session 若只能读取当前 surface，`/event-detail` 返回 `degraded: true` 与 `detailMode: "current-surface"`，新版 App 展示不完整提示；无法读取时使用稳定错误码和重试，不显示原始异常。休眠会话的完整读取依赖 issue #7 的独立修复，本分支不复制该实现。
->
-> ⚠ **`/bootstrap` 的 `agents[*].sessionId`（纯增量）**：`agentId` 与 `sessionId` 不是同一标识（`session:` 前缀、子代理场景），新版 App 按 session 维护运行状态，需要 bootstrap 一并下发映射，否则冷启动/重连后要等 `agent/status` 变化帧才知道会话在跑（发送键会短暂显示为「发送」而非「停止」）。旧插件不发该字段时 App 回退按 `agentId == sessionId` 取值。`agents[*].title` 的兜底短码也改由 sessionId 派生（旧插件缺字段时不影响）。
-
-### 2.3 高度自定义化的 Harness
-
-- **自定义权限预设/模型/Agent 预设**：App 全部从内核动态读取（catalog、session-config），不内置白名单；未知预设名显示为「…」（后续版本可拉取预设清单美化）。
-- **第三方插件动作**：`ctx.mobileActions.register(...)` 注册后自动出现在 App 动作区（v0.1 契约：仅 text 字段）。
-- **自定义问答 provider / 自动审批策略**：若用户的 Harness 已经接管人类问询（如自动答题插件、审批策略改为自动放行），内核**不会产生** `question/requested` / `approval/requested` 帧——手机不弹窗是**正确行为**，不是 bug。
-- **多 profile**：插件按 profile 安装（`<profile>/node_modules/dsh-mobile-remote`），每个 profile 独立配置口令/连接。
-
----
-
-### 2.5 两代宿主 API 适配（v3.1.6，issue #19）
-
-宿主 `0.2.0` 有**四处**接口与 `0.1.x` 不同。四处**全部表现为静默失败**——服务在、调用不报错、行为却已变（"能力语义漂移"，见 `CONTEXT.md`）。插件按**结构特征**探测代际并各走一条路径，不查版本号（ADR 0017）：
-
-| 差异 | `0.1.x` | `0.2.x` | 插件如何判别 | 传错的后果 |
-|---|---|---|---|---|
-| 任务查询/终止的 caller | **Agent 对象**（实现内部取其 `.id`） | **SessionId 字符串** | `jobs.events.subscribe` 是否存在（两处差异同版发生） | 列表恒返回空（像"确实没有任务"）；终止报"任务属于另一个会话" |
-| 任务事件订阅 | `onJobsChanged` + `onJobDone` 两个回调 | 统一的 `events.subscribe(filter, listener)` | 同上 | 实时推送静默退化为轮询 |
-| 设置读取 | `get(ns)` 返回配置节 | `describe()` 返回描述符数组（取 `value`） | `typeof settings.get === "function"` | 抛出的类型错误被 `try/catch` 吞掉，提供商配置页字段凭空消失 |
-| 事件流打开的参数位次 | `(端点, 载荷, 取消信号)` | `(端点, 载荷, uplink, peer, 取消信号, 控制)`；**0.2.1 末尾又加 `uplinkWindow`（7 参）** | 形参个数（3 vs ≥5 判 control 位次） | 信号落进 `uplink`、真 signal 为 `undefined`，宿主在 `AbortSignal.any` 处抛错并被重试吞掉 → `approvalMode: both` 的双端呈现**永远不就绪**。peer 从 0.2.1 起必填，见 §2.6 |
-
-**另有一类风险单独处理**：插件依赖的若干宿主成员是 **TS-private**（无契约保证）——权限预设的 `names`/`presets`/`apply`，以及工作区注册表的 `enqueueOperation`/`requireState`/`setState`（后者此前**完全无守卫**）。v3.1.6 起这些成员缺失时**显式报错**（503）或显式降级，不再让 `TypeError` 在深处被吞成"按了没反应"。**不迁移**到公开 API——那是行为改变，与本次兼容修复分开评估。
-
-**`$events` 流断开改为退避重连**：原实现"就绪后一旦断开即永久放弃"，使 `approvalMode: both` 在首次断流后永久退化为手机独占，直到重启宿主——而桌面 GUI 每次开关浏览器都会断流。现语义：**就绪前**失败 = 事件源尚未注册（有界重试 ≈15s）；**就绪后**断开 = 瞬时断开（3s 起退避、上限 60s、无限重连，仅插件卸载才停止）。重新就绪后退避复位。
-
-**验证范围（如实标注）**：只对 **`0.2.x` 做真实宿主端到端验证**（本机宿主即 0.2.x）。`0.1.x` 那条路径的真实宿主验不到，**靠两代假宿主夹具保护**（`test/host-compat-020.test.mjs`：按真实签名复刻两代差异，让两条分支都被实际执行到）。因此 0.1.x 一侧属于"夹具已验证、真实宿主未验证"。
-
----
-
-### 2.6 `0.2.1`：进程内网关调用强制 Peer（issue #34）
-
-宿主 `0.2.1-rc.2` 把 `0.2.0` 的"peer 可省"收紧为"**每个进程内网关调用都必须显式传一个活着的 Peer**"。与 §2.5 同类：**服务在、成员在、调用不报参数错，但内部先解引用 `peer.signal`**——漏传只会得到 `gateway/internal: Cannot read properties of undefined (reading 'signal')`，或在插件的重试循环里被吞成"通道不可用"。插件按能力探测（不按版本号）选择 peer 来源：
-
-| 差异 | `0.2.0` | `0.2.1-rc.2` | 插件如何判别 | 传错的后果 |
-|---|---|---|---|---|
-| 进程内 Peer 来源 | 网关自带 `operatorPeer()` 兜底（`connection.operator` 单例） | **兜底删除**；改由 `ctx.connection.createPeer({ principal, interactions })` 现造 | `typeof connection.createPeer === "function"` → `createPeer`；否则看 `gateway.operatorPeer` → `operatorPeer`；都没有 → `none` | unary RPC 恒返回 `gateway/internal`；`$events` 永不就绪、`approvalMode: both` 静默降级 mobile |
-| 网关四入口的 peer 实参 | 可省 | `invokeRpc(e,p,s,**peer**)` / `stream({…,**peer**})` / `openWireStream(e,p,uplink,**peer**,s,…)` / `dispatchRpc(e,p,s,**peer**)` 均要求必填 | 同上一行（`hostPeerSource`） | 同上 |
-| `$events/result` 结算身份 | peer 不参与 | `assertPeerLive` + `requireInteractions` + owner + **`client.peer !== peer` 拒绝** | 插件把**开流用的同一个 Peer 实例**用于结算 | 结算被 `gateway/interactions-forbidden` 拒绝，手机答了却"没生效" |
-
-**插件做法（issue #34 实现）**：
-
-- 插件级**单例** Peer：首次真正调用网关时惰性创建（`owner` + `interactions: "answer"`），跨 RPC 与 `$events` 开流共用；**开流与结算同一个实例**（宿主按 Peer 身份匹配），插件卸载时 `dispose()`。
-- `connection` 服务可能晚于插件挂载（0.2.1 实测首次 `ctx.get("connection")` 为 `undefined`）——首次取不到就不缓存，交给既有 `$events` 有界重试/下次调用再建。
-- `0.2.0`/`0.1.x` 不改变行为：没有 `createPeer` 时继续传 `undefined`，由网关兜底 / 旧代 3 参开流不需要 peer。
-- 诊断显式化：`checks.hostCapabilities["gateway.eventsPeer"]`（`ok`/`drift`）+ `checks.hostGeneration.eventsPeer`（`createPeer`/`operatorPeer`/`legacy`/`none`/`unknown`），`drift` 时附原因码 `gateway-peer-source-missing`；`approvalMode: both` 的降级文案不再归咎"宿主版本过低"。
-
-**验证范围（如实标注）**：`0.2.1-rc.2` 路径已在**隔离宿主**（`HOME`/`DSH_HOME` 独立、`--profile compat`、端口 3099）完成端到端验证：`checks.remoteEvents=true`、`POST /m/api/defaults {"permissionPreset":…}` 返回 `200 {"ok":true}`；三代的实参位次与 peer 同源/释放由 `test/host-compat-021.test.mjs` 夹具钉住；`0.2.0`/`0.1.x` 回归由既有 `test/host-compat-020.test.mjs` 保护（其 0.2.0 夹具补了真实网关的 `operatorPeer`）。
-
----
-
-## 3. Android 多品牌适配
-
-App 为 Flutter 原生 APK（`com.dsh.remote`），渲染后端为 **Impeller（Vulkan，自动回退 OpenGLES）**。
-
-| 维度 | 状态 | 说明 |
-|---|---|---|
-| 渲染 | ✅ 已验证（小米 17 Pro Max） | Flutter 引擎在无 Vulkan 机型自动回退 GLES；再老机型回退 Skia。历史风险点：部分旧 Mali GPU 的 Impeller 花屏（2024 年问题，现版本基本修复） |
-| 系统版本 | Android 7.0+ | minSdk 跟随引擎默认 |
-| 明文 HTTP | ✅ | `usesCleartextTraffic=true` 已配置（Android 9+） |
-| 扫码 | ✅ | mobile_scanner（CameraX）全品牌通用 |
-| 后台存活 | 部分依赖系统 | 国产 ROM 杀后台会断 SSE；App 有指数退避重连 + 回前台自动探测。系统级提醒走推送桥（ntfy/Bark/Server酱），不依赖 App 存活 |
-| 深色/字体缩放 | ✅ | Flutter 主题自适应 |
-
-**建议发布前实测**（借 1~2 台其他品牌即可）：① 长时间流式回复渲染；② 上翻深历史（Impeller 表现）；③ 熄屏后回前台自动重连。
-
-**如遇渲染异常**：把 `dsh-mobile-app/android/app/src/main/AndroidManifest.xml` 中 `EnableImpeller` 改为 `false` 出一个 Skia 版验证；App 代码无需改动（列表结构两种后端都验证过）。
-
-## 4. iOS（未开发）
-
-> **原因**：开发者手上没有苹果设备（Mac/iPhone），无法构建、真机调试与签名分发 iOS 版本——因此 iOS 端**暂未开发**。**欢迎社区贡献**：iOS 适配工作量不大，任何有 Mac 的开发者都可以按下面清单完成并提交 PR（见 CONTRIBUTING.md）。
-
-- **Dart 代码零平台依赖**，5 个插件（shared_preferences / http / path_provider / mobile_scanner / url_launcher）均有 iOS 实现；iOS 只有 Impeller 后端，而列表结构恰在 Impeller 下验证过——代码几乎不用改。
-- 需要：Mac + Xcode + Apple 开发者账号（自用免签/TestFlight）。
-- 必须的配置项（预计半天）：`Info.plist` 放行局域网 http（ATS `NSAllowsLocalNetworking`）、iOS 14+ 本地网络权限文案（`NSLocalNetworkUsageDescription`）、相机权限文案。
-- 分发：自用可用免费账号侧载（7 天重签）；公开分发走 TestFlight/App Store（需付费开发者账号）。
-
-## 5. 已知问题清单（发布时如实告知）
-
-| # | 问题 | 影响 | 状态/缓解 |
-|---|---|---|---|
-| 1 | 宿主 API 存在**静默语义漂移**（服务在、不报错、行为已变） | 升级宿主后功能"没反应"，且旧的两分法探测看不见 | 能力三态报告（`checks.hostCapabilities` / `checks.hostGeneration`）+ 两代假宿主夹具；见 §2.5、§2.6 |
-| 2 | 自定义权限预设名在 App 显示「…」 | 纯展示 | 后续拉取预设清单 |
-| 3 | 国产 ROM 杀后台导致通知延迟（App 内角标） | 通知不及时 | 推送桥不受影响；App 重连后补拉 |
-| 4 | Impeller 在极老 GPU 的潜在渲染问题（未实测） | 少数旧机可能花屏 | manifest 一行回退 Skia |
-| 5 | 大体积消息（数万字符）首次滚动定位 | 仅首屏定位，无功能损失 | 列表已按段加载（50 条/页） |
-| 6 | 明文 HTTP 通信 | 仅限可信内网 | 设计如此（docs/04-security.md）；公网必须虚拟组网（蒲公英推荐）/ TLS 反代（docs/06 §5/§6b） |
-| 7 | 通知记录删除后，同会话同类事件会再生成新通知 | 符合预期（删除≠静音） | 已文档化 |
-| 8 | GIF 发送后显示静态 | 与 PC 端一致（内核附件规范化取首帧重编码）| 动态链路已就绪（Flutter 原生支持），待内核保留动画附件 |
-| 9 | 思维链块仅标题行（图标+字数+箭头）可点击切换，正文为可选中文本（点正文不切换，属设计） | 轻微认知成本 | 已文档化；折叠状态 v3.1.0 起按消息持久化（滚动/重进/重启保持） |
-| 10 | 旧版 App（≤v3.0.0）在 WSL/类 Unix 服务端浏览目录会拼出 `/\home` 形态的路径 | 旧 App 在 WSL 端目录浏览受限 | **v3.1.1 已修复**（服务端 `normalizeServerPath` 归一化）；新版 App 按服务端 `sep` 拼接，任意组合可用 |
-| 11 | 与 dsh-web 移动端远程（`@linxin666/dsh-remote-web-ui`）同装冲突 | 两者抢 `/m` 路由前缀（对方写死不可配），可能异常/崩溃 | 本插件 `path` 改 `/mr` 等非 `/m` 单段即可共存（App 自动适配，无需重装）；详见 FAQ |
-| 12 | 手机在线时桌面端不弹审批/问询框（v3.1.2，issue #9） | 桌面用户无法在 PC 审批/应答（只能手机答或 120s fail-close） | **v3.1.3 修复**：默认 `approvalMode: both` 双端同卡、先答生效（0.1.2-rc.1+）；旧宿主/历史版本可用 `approvalMode: mobile \| desktop` 明确策略 |
-| 13 | `approvalMode: both` 依赖内核 `$events` 通道 | 旧宿主（0.1.1-rc.2 及更早）无法双端同卡 | 自动降级 mobile 并写日志；诊断 `notes` 可查 |
-| 14 | `0.2.1-rc.2` 起进程内网关调用强制显式 Peer（§2.6） | 未适配的插件版本上：RPC 功能报 `gateway/internal`，`$events` 双端审批静默降级 | 已按能力探测适配（`connection.createPeer`）；诊断 `gateway.eventsPeer` 可归因；旧代行为不变 |
-
-## 6. 内置常量与"写死"数据速查
-
-**零敏感写死**：口令、密钥、推送凭据全部在用户配置（`cordis.patch.yml`）或手机本地，代码与仓库中无任何密钥硬编码。
-
-| 类别 | 内容 | 说明 |
-|---|---|---|
-| 设计令牌（有意） | 品牌色 `#426EFE` / 深色 `#0E1116` 等（App `theme.dart`）、`com.dsh.remote`、QR 协议 `DSHREMOTE\|地址\|口令`、`EnableImpeller=true` | 产品设计/通信契约，勿随意改 |
-| 内核耦合词（有意） | 系统消息过滤词 `Current runtime context` / `This snapshot supersedes` / `background job `（App `chat_screen.dart`） | 与内核/PC 端保持一致的隐藏规则；apiProxy 帧桥已于 v3.1.6 删除，见 §1.4 |
-| 插件可配置项 | `path` / `authToken` / `cookieName` / `sessionTtlMs` / `rechargeUrl` / `maxConnections` / `pushUrls` / `pushCooldownMs` / `pushContent` / `rateLimit` / `trustedHosts` / `doneGraceMs`（v2.8.0）/ `lanBridge`（v3.0.0：`enabled` 可选；未配置时仅可信 Desktop 自动启用，显式 `false` 关闭，可配 `port`/`host`）/ `approvalMode`（v3.1.3：`both` 默认 \| `mobile` \| `desktop`）/ `turnOutlineTimeoutMs`（轮次大纲端点有界等待，默认 5000ms，契约门禁可调短） | schema 默认值，改配置即可 |
-| 插件内置常量 | 通知上限 100、catalog 缓存 15s、SSE 心跳 25s、SSE 超时 15s、登录限流默认 10 次/60s（`rateLimit` 可配）、状态文件 `~/.dsh/mobile-remote/` | 合理默认，无需配置 |
-| App 内置常量 | HTTP 超时 15/20s（余额 25s）、连接/探测超时 8s、地址表上限 8、重试退避 1s→15s、看门狗 15s 检查 / 心跳 75s（3 周期）、日志保留 15 天/256KB、聊天初始窗口 50 条、历史分段 30 条、上下文圆环阈值 70%/90%、思维链折叠手动状态键 `dsh_mr_reasoning_overrides`（按会话持久化，每会话软上限 100 条） | 合理默认；修改点集中在各文件顶部常量 |
-| 已消除的写死 | 充值链接（原 App 硬编码 `platform.deepseek.com/top_up`） | v2.4.2 起走 `catalog.rechargeUrl`（插件配置为准） |
-
-## 7. 发布签名
-
-- Release APK 需正式 keystore：`dsh-mobile-app/android/app/dsh-release.jks` + `android/key.properties`（**均已 gitignore，切勿提交**）。
-- 干净克隆无 key.properties 时自动回退 debug 签名（仅自用可安装；商店/公开分发必须自建 keystore）。
-- 自建方法见 `dsh-mobile-app/README.md`「构建」一节。
-- ⚠ 更换签名 = 新应用：用户需卸载重装并重新扫码。