手机端配对面板 Eternalloveone/dsh-palm

dsh-palm

状态：1.0.0 稳定版 —— /m/api 方法面与帧格式向后兼容（只增不改）。欢迎反馈。

dsh-palm 演示

dsh web GUI 的独立移动端界面：扫码或输码配对设备信任、/m/ 手机端 UI、带实时 SSE mux 桥的 /m/api RPC 通道，以及桌面端配对面板。

衍生声明

dsh-palm 是 dsh-remote-web-ui（@linxin666/dsh-remote-web-ui，Apache-2.0，作者 zhu1090093659）的衍生作品。详见 NOTICE。

继承： 配对协议、设备存储格式原型、桌面端面板骨架。自研： /m/ 全部 UI、渲染栈、/m/api 白名单与 SSE mux、离线层。v1.3.0 起全部运行时契约为 dsh-palm 自有命名——设备存储移至 $DSH_HOME/dsh-palm-devices.json，settings namespace、cordis 配对服务与 settings 桥路径均不再沿用 dsh-remote-web-ui 的命名。

产品定位

dsh-palm 是窄屏优先的轻量指挥台：手机用于查看进度、响应通知、快速操作与轻量管理——而非深度工作终端。复杂配置（安装插件、编辑权限预设）建议在桌面端完成；手机端保持高频路径（打开会话、阅读、回复）一两步可达。每个组件以手机场景频率为准入标准：模型切换、任务与后台任务状态、会话管理是一等公民；桌面场景的便利设施（卡片首页、多 Tab 导航、树形侧边栏）刻意不做。界面保持单页状态机（工作区 → 会话 → 聊天）+ 底部面板扩展，不引入 Tab 架构。

快速开始

手机得能连到这台机器，三种方式：

- 同一 Wi-Fi（30 秒，够用）—— 点侧边栏手机图标打开配对面板，用面板给出的局域网地址。
- Tailscale（5 分钟，推荐）—— 两端都装 Tailscale；面板自动探测 tailnet 域名，一键填入。
- frp 或 Cloudflare Tunnel（已有基础设施的话 1 分钟）—— 把隧道地址粘贴进面板；保存前先验证可达性。

面板会自动探测本机隧道（Tailscale tailnet 域名、frpc.toml 条目、Cloudflare Tunnel 客户端）；没有隧道的小白会看到「局域网直连 / 创建隧道」分叉而非空白输入框。

然后：dsh plugin --profile web add @eternalloveone/dsh-palm → 打开配对面板 → 手机扫码或输入 6 位配对码。

初次接触？30 秒上手教程带您从安装走到手机上完成一次对话，并配好让手机端真正值得用的完成通知。

截图

| 聊天 | 聊天 —— 流式 Markdown，每轮一张过程卡（思考与工具按事件顺序混排）、可交互 diff 卡片与语法高亮代码块 |
| Diff 卡片 | Diff 卡片 —— diff 代码块渲染为可交互卡片，支持接受 / 拒绝 |
| 运行状态 | 运行状态 —— 任务清单与后台任务共用一个工具栏上方的实时状态条 |
| 配对 | 配对 —— 粘贴桌面端链接或输入 6 位配对码 |
| 用量 | 用量 —— 桌面端配置的每个提供方一张卡片：周用量进度条、账户余额与 OpenRouter 消耗/限额，可手动刷新 |

更多截图（工作区、会话列表、图片上传、设置、任务面板、配对面板）：docs/screenshots。所有截图均由真实 /m/ UI 渲染虚构演示数据（项目名、会话标题与聊天内容均为编造），仓库中不会泄露任何真实信息。

核心能力

- 扫码配对设备信任 —— 手机扫码或输入 6 位配对码完成配对；设备持久化在 $DSH_HOME/dsh-palm-devices.json
- 原生手机端界面（/m/） —— 从零为窄屏设计的独立手机 bundle，而非桌面 GUI 的 CSS 适配层：触控优先的交互、安全区与动态视口适配、拇指友好的触控目标、零横向滚动
- 手机端与桌面端实时同步 —— 两端共享同一条宿主事件流（SSE mux 桥 + 轮询回退）；端到端延迟（桌面触发 → 手机端 mux 帧，中位数）：本机回环 4ms、公网隧道 9ms、Tailscale 13ms、弱网 246ms（Chrome DevTools 限速，模拟 200ms 延迟，每场景 N=5–8 轮，2026-08 实测）
- 输入法安全 —— 中文输入法组合期间不会误发半截拼音
- Diff 卡片与代码操作 —— 容错 diff 解析，支持接受 / 拒绝 / 评审；复制、插入编辑器、打开、下载、沙箱运行
- 运行状态条与任务面板 —— 任务清单与后台任务合并为一个工具栏上方的实时状态条
- 离线发件箱与 PWA —— 断网时消息排队（IndexedDB），联网自动发送；可安装、带版本号的服务工作者
- 完成通知 —— 任务完成与长回复提醒，三层投递：应用内系统通知（SSE）、Web Push（VAPID）、以及应用关闭时也能送达的第三方渠道（WxPusher / Server酱 / Bark / Telegram，另有降级保留的 PushPlus）；阈值与间隔可在手机端配置。分类型门控（规划完成 / 后台任务 / 长回复）可独立开关，后台任务与长回复默认安静
- 逐提供方用量与余额 —— 桌面端配置的每个模型提供方一张卡片：周用量进度条（Ollama Cloud）、账户余额（DeepSeek、Moonshot/Kimi）与 OpenRouter 消耗/限额，可手动刷新；无公开查询接口的提供方不展示
- 全局搜索与消息级定位 —— 首页搜索覆盖工作区与全部会话内容，命中按工作区分组并显示真实会话标题；点击直达并滚动高亮到匹配消息（深链 ?session=&seq=）。中文短词由有界子串回填兜底（SQLite FTS 把连续中文当作一个 token）
- 轮次导航（长会话回跳） —— 右下角浮出把手显示「当前 / 总轮」，向上翻历史时出现：轻点打开轮次清单（每轮带提问与回复预览，未加载的轮次会先分页再落位），按住左右拖动即刮擦条，松手直接跳到该轮；清单覆盖整个会话（实测 172 轮也能落到第 1 轮）
- 待发消息队列 dock —— turn 运行期间发送的消息进入 host 队列，在输入区上方显示队列条（桌面 QueueDock 对齐）：单条或可折叠的「N 条排队」头，每条可编辑（仅纯文本）、删除、或插话发送（agent 运行中）；dock 镜像 host 快照，会话停止后自动消失
- 全局运行总览 —— 全屏查看 host 当前在做的一切：跨工作区的运行中会话，每张卡片直接说清"在干什么"——运行命令 pnpm test · 第 7 步 · 已跑 12分04秒，下面是工作区与"几秒前有活动"（超过 90 秒转黄），后台任务压成一行；派出去的子代理逐个列出、点一行进它的只读会话页。跑完的会话不消失，落到「刚结束」带状态/用时/摘要，任何页面还会浮一条可点胶囊
- 聊天内文件与图片预览 —— 消息里的文件路径链接（裸路径或反引号包裹，现均可点击）打开底部预览面板：markdown 格式化渲染、HTML 在沙箱 iframe 中渲染、代码高亮、图片内嵌显示；消息中的 图片支持全屏 lightbox（双击放大）
- 干净的流式输出 —— 窗口化前缀渲染让长回复保持流畅；推理块折叠为可展开块

完整能力列表

架构、实时、交互、离线、韧性、体验、配对与引导 —— 完整列表

架构

- 方法级白名单 RPC —— /m/api 只暴露显式白名单 + 手机端本地方法；错误响应不泄露宿主路径与方法名（由 tests/mobile-api.spec.ts 覆盖）
- 手写渲染栈 —— GFM 子集 markdown 渲染器（先转义、协议白名单）、轻量语法高亮器、unified diff 解析器——渲染栈无第三方依赖；打包小于 1 MB（gzip 226 KB）

实时

- SSE mux 桥 + 轮询回退 —— 停滞检测（活跃流 36s）自动启动自适应历史轮询；事件不丢，SSE 恢复后立即切回；设备被撤销后停止轮询并回到配对页，而非无限空转
- 增量流式预览 —— 未闭合尾部按 chunk 增量转义，短块保留行内 Markdown 提升
- 推理块折叠 —— 正文中的思考内容折叠为可展开块

交互

- 审批与问题面板 —— 工具审批实时推送、就地解决；应答绑定所属设备会话（多端不能互相抢占）
- 命令卡片 —— slash 命令发现与执行，带运行中 / 成功 / 失败生命周期
- 斜杠命令 chip —— 从 / 面板选命令时只把命令词做成蓝色 chip 填进输入框，参数可以继续改；发送时拼回整行，撤掉 chip 等于取消该命令
- 图片上传 —— 粘贴或选择；canvas 压缩把载荷控制在固定预算内；超限与解码失败以 toast 提示而非静默丢弃
- 文件附件 —— 「+」菜单收任意文件（文档、表格、压缩包、代码）：一次最多 5 个、单个 20 MB，经宿主附件服务暂存后消息里只带引用；输入区上方出现待发附件条（文件名、大小、移除）。手机自己的选择器只给相机和相册时（有些 Android 机型根本没注册文件入口），电脑文件改从这台电脑的目录里挑，选中后把 @绝对路径 写进输入框
- 语音输入与转写 —— 浏览器内 WAV 录音（60s 自动收尾、离开页面自动清理），OpenAI 兼容多服务按序回退（默认 SenseVoiceSmall），手机端可管理服务列表；宿主配置的服务仅作展示——宿主 API key 绝不离开宿主。录音时同步显示实时字幕。
- 会话管理 —— 聊天更多菜单或列表长按删除会话；离线发件箱随会话一并清理
- 全局搜索 —— 首页搜索覆盖工作区与全部会话内容，按工作区分组并显示真实会话标题；会话列表页搜索收窄到当前工作区。命中点击直达并滚动高亮到匹配消息（深链 ?session=&seq=）；中文短词由有界子串回填兜底
- 轮次导航 —— 右下角浮出把手显示「当前 / 总轮」，离开最新消息后就出现：轻点开轮次清单（每轮提问 + 回复预览，未加载的轮次先分页再落位），按住把手左右拖动＝横向刮擦条，松手跳到手指所指的那一轮。清单把宿主的 turnOutline 投影与本地已加载轮次合并（去重、按轮次升序），整段会话都可达；刮擦条按手指的绝对位置映射（拖到屏幕两端即最早/最新），深轮跳转按「下一轮的边界」取页并带页数预算，取不到会明确提示而非停在「正在载入…」
- 待发消息队列 dock —— turn 运行期间发送的消息进入 host 队列，在输入区上方显示队列条（桌面 QueueDock 对齐）：单条或可折叠的「N 条排队」头；每条可编辑（仅纯文本）、删除、或插话发送（agent 运行中）；dock 镜像 host 快照，会话停止后自动消失
- 目标条 —— 手机端的桌面目标条，夹在排队条与模型／权限行之间：暂停／继续跟随宿主的 activate 状态，展开后按正文换行排版，并给出可见的收起出口
- 会话内文件预览 —— 消息里的文件路径链接（裸路径或反引号包裹）打开底部面板，而非仅桌面可用的打开器：markdown 格式化渲染（可交互代码围栏 / diff 卡片）、HTML 在沙箱 iframe 中渲染（脚本失效）、其他代码高亮、图片路径内嵌显示；相对路径按会话 cwd、宿主进程 cwd、各工作区或聊天中已有的绝对路径解析
- 会话内图片灯箱 —— 消息中的 （远程 URL 或附件 data URL）全屏打开，双击切换「适应 / 1:1」缩放
- 全局运行总览 —— 全屏跨会话视图：跨工作区的运行中会话、实时后台任务，以及各会话正在等待的子代理；从首页快捷 chip 进入（带实时徽标），每张卡片可直达该会话。卡片自己会说清"正在干什么"：运行命令 pnpm test · 第 7 步 · 已跑 12分04秒，下面是工作区与"几秒前有活动"（超过 90 秒转黄，用来判断是不是真卡住）
- 子代理可点开 —— 每张卡片下面把这一轮派出去的子代理逐个列出来（运行中带已跑时长、结束的显示"几分钟前"）；点一行进它自己的只读会话页，能看到它收到的任务、每一步工具调用和回答，页脚明确写"只读视图 · 子代理不能从这里接收新消息"
- 刚结束驻留 —— 跑完的会话不会凭空消失：落到「刚结束」，带状态（已完成／出错退出／已中断）、用时、几分钟前和一句摘要，留 30 分钟、最多 8 条，写进 localStorage，退出重进还在；任何页面收到收工还会浮一条可点胶囊，直接跳到那个会话
- 插件市场 —— 手机端浏览、搜索、安装插件（建议在桌面端执行）
- 桌面级设置同步 —— 手机端设置与桌面同步（schema 表单、级联模型选择、权限预设；复杂预设建议在桌面端编辑）
- 设置搜索 —— 设置页搜索同时索引子配置项（通知门控、推送渠道、Web Push、语音服务），点击自动打开所属子页并滚动定位

离线与弱网

- PWA —— 可安装、带版本号的服务工作者、可离线使用的打包产物
- gzip 压缩 API 响应 —— 弱网友好
- 按需加载 —— 工作区列表轻量拉取；会话只在打开时加载
- 瞬时切换 —— 折叠视图读取、批量预览与跨挂载缓存让列表/聊天切换近乎即时，弱网下同样流畅

韧性与诊断

- 错误不再留白屏 —— React 错误边界渲染可读错误页（重试 / 重新加载）；window 错误、未处理的 Promise 拒绝与资源加载失败进入有界错误环（存宿主侧），宿主可把报告转发到你配置的渠道——手机自己崩了是发不出消息的
- 缓存不会被系统悄悄清掉 —— 首次写缓存后请求持久化存储，长时间后台的 PWA 不会静默丢失历史缓存
- 卡顿与进程挂起可分辨 —— Long Tasks 观测 + 隐藏窗口记录：起始于隐藏期间的任务单独标记，并给出 suspension.hiddenMs——「应用卡了」与「系统把我们冻住了」不再产生同一个数字

通知

- 一次判定，三条通道 —— 宿主监听共享事件流并统一判定（任务终态 + 超过可配置阈值的回复，带同会话冷却）；每条通道投递同一判定结果
- 分类型通知门控 —— 规划完成 / 后台任务 / 长回复三类事件在设置页各有独立开关；存量配置默认后台任务与长回复安静（行为变更）
- 应用内系统通知（SSE） —— 应用打开时手机端弹出系统通知；点击直达对应会话
- 通知收件箱 —— 通知页列出宿主引擎最近 50 条判定记录，错过即丢的通知可回看并点击直达所属会话
- 锁屏隐私 —— 开启后所有通道的通知统一降级为通用文案（不携带会话标题与任务名）
- Web Push（VAPID） —— 应用关闭时由服务工作者接收推送（Android Chrome/Edge/Firefox；iOS Safari 16.4+ 仅限已安装的 PWA；国内网络可能无法到达 FCM 后端——由第三方渠道覆盖）
- 第三方渠道 —— WxPusher（微信，国内用户推荐首选）、Server酱（微信）、Bark（iOS）、Telegram webhook，应用完全关闭也能送达；PushPlus 降级保留（现需付费认证，旧 Token 仍可发）。凭据只存宿主端，不经过设置面
- 通知设置 —— 权限、时长阈值、冷却间隔、Web Push 开关与渠道凭据都在手机端设置页，附「发送测试」按钮可端到端验证整条链路；各渠道显示凭据状态（已配置 / 未配置），重启后不再误以为 key 丢失

体验

- 显示偏好 —— 字号、密度、行号、自动滚动
- 主题联动 —— 桌面主题偏好同步到手机
- 会话列表 —— 完整项目名、按 cwd 过滤、完整时间戳
- 检查更新 —— 关于页代查 npm registry（手机端 CSP 禁止直连，由宿主代查），提示「发现新版本」或「已是最新」

配对与引导

- 6 位配对码 —— 桌面面板在二维码旁显示人类可读的配对码，手机可直接输入。配对码一次性、随令牌过期（默认 10 分钟）、刷新或停止即失效；/api/pair/accept 有速率限制（30 秒窗口：每源 IP 40 次、每 XFF hop 10 次），未知或已用密钥统一返回 invalid，探测无法区分二者
- 面板内公网地址编辑器 —— 直接在配对面板配置隧道地址（frp / Cloudflare Tunnel / Tailscale）；保存前自动探测可达性，死隧道在保存前就被拦下
- 三步向导 —— 面板是「配置 → 配对 → 使用」向导；步骤指示器兼作导航（已完成步骤可点击回看），已配对用户直接进入简洁的设备管理视图
- 隧道检测 —— 宿主探测 Tailscale（tailnet 域名一键填入）、解析 frpc.toml 给出具体 frp 入口、识别 Cloudflare Tunnel 客户端；没有隧道的小白会看到「局域网直连 / 创建隧道」分叉而非空白输入框
- 首次使用引导 —— 可关闭的欢迎横幅、侧边栏入口未配置红点、人话文案（"手机连不上这台电脑"）且操作入口就在下方
- 首次上手欢迎卡 —— 配对成功后工作区首页展示一次性三步引导（开始对话 / 配通知 / 看用量），可关闭且仅显示一次
- 工作区原生主题 —— 面板通过 prefers-color-scheme 跟随系统深浅色（无手动切换），所有颜色 0.2s 过渡
- 手机端服务器切换 —— 配对页显示服务器地址，可通过 ?code= / ?pair= 深链切换到其他隧道入口；配对码被立即消费，URL 随即替换为干净路径，所有响应携带 Referrer-Policy: no-referrer
- 桌面级命令菜单 —— 手机端 + 菜单按会话的 agent 视图解析，/plan、/compact 等按 agent 挂载的命令与桌面 / 弹窗一致

通知

dsh-palm 在任务完成或长回复结束时提醒手机。宿主端统一决策引擎（NotifyEngine）监听共享事件流，把每个决策扇出到三层投递通道——无论应用打开、关闭还是浏览器完全退出，同一事件都能到达手机。

原理

一个触发，三条通道。 宿主监听 mux 事件流并统一判定：

- 任务终态 —— 后台任务（bash、pwsh 等）从 running 变为 completed/failed 时立即发通知
- 长回复 —— 完成的 turn（agent 回复）耗时超过可配置阈值（默认 30 秒）时发通知；同一会话受冷却间隔（默认 2 分钟）节流，避免连续长回复轰炸手机。中止与出错 turn 永不通知

决策通过三条独立通道投递：

| 层 | 通道 | 生效场景 | 说明 |
| L1 | SSE → 系统通知 | 应用打开（前台或后台） | 点击直达对应会话；页面可见时不弹 |
| L2 | Web Push（VAPID） | 应用关闭、浏览器运行中 | Android Chrome/Edge/Firefox；iOS Safari 16.4+ 仅限已安装 PWA；国内网络可能无法到达 FCM 后端 |
| L3 | WxPusher / Server酱 / Bark / Telegram / PushPlus（降级）webhook | 应用关闭、浏览器已退出 | 凭据只存宿主端 |

L1（应用内）。 手机保持一条到 /m/api/events.notify 的 SSE 连接——刻意与聊天 mux 流分离（其 schema 会丢弃未知帧）。收到通知帧即弹系统通知；点击深链到 /m/?workspace=…&session=…。页面可见时不弹——你本来就在看应用。

L2（Web Push）。 服务工作者（v4）接收推送，应用关闭时也能弹通知（只要浏览器在运行）。VAPID 密钥首次使用时生成，存于 $DSH_HOME/dsh-palm-notify.json；手机通过 pushManager 订阅，以配对 cookie 作为订阅身份。失效订阅（推送服务返回 410/404）自动清理。出站投递优先读 DSH_PALM_PUSH_PROXY，其次 HTTPS_PROXY / HTTP_PROXY——部分网络（国内）不配代理无法到达 FCM。

L3（第三方）。 WxPusher（微信）、Server酱（微信）、Bark（iOS）、Telegram webhook 在应用完全关闭、浏览器退出后仍能送达；PushPlus 降级保留（现需付费认证）。凭据只存宿主端，设置面只显示各渠道是否已配置。

用法

1. 打开手机端设置页 → 通知卡片
2. 按提示允许通知权限
3. 调整时长阈值（长回复触发）与冷却间隔（同会话节流）
4. 打开 Web Push 开关订阅当前浏览器（L2）
5. 可选配置 L3 渠道（设置 → 通知 以 WxPusher 卡片打头）：
- WxPusher —— 按 WxPusher 文档「极简推送 SPT」 微信扫码拿一个 SPT… 令牌填进去；免费、不用注册应用、国内直连
- Server酱 —— 在 sct.ftqq.com 注册（微信扫码），把 SendKey（SCT…）填入设置页
- Bark —— 安装 Bark 应用（iOS），复制设备 key
- Telegram —— 通过 @BotFather 创建机器人，获取 bot token 与 chat id
- PushPlus —— 旧渠道，现已需付费认证；已填旧 Token 的配置继续可用
6. 点「发送测试」把一条合成事件端到端推过已配置的 L3 渠道

注意事项

- L1 依赖应用存活（SSE 连接）；锁屏或系统杀掉浏览器后失效
- L2 依赖浏览器运行；部分国产 ROM（OPPO/vivo、小米、华为）即使装了 Google 服务也会拦截 FCM 通道——请改用 L3
- iOS Safari 的 Web Push 需要 PWA 添加到主屏幕（16.4+）
- 设置页测试按钮只走 L3；L2 需通过完成真实任务验证

安装

已在 dsh 0.1.5-rc.2、0.1.5-rc.3 与 0.1.7-rc.1 上测试（peer 范围：cordis >=4.0.1 <5，dsh-client-ui-slots / dsh-settings 均为 >=0.1.5-rc.1 <0.1.8-0）。0.1.6 起 DSH 新增插件版本门：peerDependencies 不覆盖当前版本时插件会被静默跳过（手机面全死、桌面端无任何提示），所以声明范围不能写窄；若使用其他 dsh 版本，安装后请验证配对面板与 /m/ 界面。完整版本兼容矩阵见 COMPATIBILITY.md。

从 npm 安装：

dsh plugin --profile web add @eternalloveone/dsh-palm

从源码安装：

git clone https://github.com/Eternalloveone/dsh-palm.git
dsh plugin --profile web add link:/path/to/dsh-palm/packages/dsh-palm

v1.3.0 注意： 旧版 dsh-palm / dsh-remote-web-ui 已配对的设备不会沿用（设备存储已移至 dsh-palm-devices.json、settings namespace 已改名）——升级后需重新扫码配对一次。

PWA 平台支持（真机实测）

| 平台 | 安装 PWA | 说明 |
| Android | ✅ Chrome / Edge / Firefox | 浏览器菜单「安装应用」（需受信 HTTPS 入口） |
| iOS | ✅ 仅 Safari | 用 Safari「添加到主屏幕」；Chrome 等 iOS 浏览器不支持完整 PWA 安装——请用 Safari 打开 /m/ |

iOS Web Push（16.4+）同样要求 Safari 安装的 PWA；Android 的推送后端（FCM）在国内网络可能不可达——请使用第三方渠道（L3）。

远程访问配置

点侧边栏手机图标打开配对面板，按三步向导操作：配置 → 配对 → 使用。

1. 配置 —— 填写手机可达的公网地址（frp / Cloudflare Tunnel / Tailscale）。面板会自动检测本机隧道并给出具体入口建议；保存前先验证可达性。
2. 配对 —— 手机扫码，或直接输入面板上的 6 位配对码。
3. 使用 —— 已配对设备在简洁的状态视图中管理。

完整教程（含 frp 拓扑实例：服务器 frps + nginx TLS、客户端 frpc、面板配置、验证与常见问题）见远程访问配置手册。

性能

各接入路径下 /m/ 壳页的端到端延迟，国内客户端实测（每条路径 20 次顺序请求，Node HTTP 客户端，2026-09）：

| 接入路径 | min | P50 | P95 | max |
| 本机回环 | 1ms | 2ms | 4ms | 9ms |
| frp 直连（HTTP） | 10ms | 14ms | 27ms | 35ms |
| nginx TLS（受信证书） | 13ms | 15ms | 24ms | 57ms |
| Cloudflare Tunnel | 405ms | 413ms | 463ms | 1209ms |

nginx TLS 路径是推荐公网入口：受信证书（可安装 PWA）且接近直连延迟；Cloudflare Tunnel 仅作备用——其边缘绕路在国内网络下约慢 20-30 倍。可用 scripts/measure-paths.mjs 复测（URL 通过参数或 DSH_PALM_PATHS 环境变量传入）。

开发

pnpm install # 在 packages/dsh-palm 内
pnpm test # vitest 全量测试
pnpm typecheck # tsc -b
pnpm build # tsc -b && tsdown -> lib/index.js + lib/mobile.js

发版前的四道验收入口（全绿才发；完整流程见 RELEASING.md）：

pnpm verify:mobile # 手机端 41 条端到端用例（真宿主 + 真浏览器）
pnpm verify:secrets # 密钥扫描（有 gitleaks 用它，没有用内置规则兜底）
pnpm verify:adapt # 容器里逐版本重装 DSH SDK，再编译 + 全量单测
pnpm verify:mobile:fast # 只跑最快的四组，改代码时用
node ../../tools/dsh-canary/start.ps1 # 起金丝雀（最新 DSH，独立 HOME，端口 3099）

架构

- 宿主侧（src/）：配对（pairing.ts）、/api/pair 路由（routes.ts）、api/gate 监听器（gate.ts）、/m/ 页面路由（mobile-routes.ts）、带 events.mux SSE 桥的 /m/api RPC 通道（mobile-api.ts）、方法白名单与通道规则（remote-methods.ts）
- 移动端（src/mobile/）：独立手机端打包 —— ChatView、工作区、审批、图片上传、mux、rpc、样式
- 测试：tests/ + src//.test.（vitest）

安全

设备信任通过扫码或输入 6 位配对码建立；每次 /m/api 调用都由配对 cookie 与方法白名单把关。/m/ 页面提供以下 Content-Security-Policy 作为渲染器之后的最后防线：

default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https: http:; connect-src 'self'; font-src 'self' data:; worker-src 'self'; manifest-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'

- 未知方法被拒、宿主错误细节不回显给手机 —— 由 tests/mobile-api.spec.ts 覆盖（如 "does not leak the host command error message to the phone"）
- 吊销是服务端即时生效的 —— 被撤销设备的下一请求在 api/gate 监听器处 403；手机端停止轮询并回到配对页
- 配对码防暴力破解 —— /api/pair/accept 有速率限制（30 秒窗口：每源 IP 40 次、每 XFF hop 10 次），令牌默认 10 分钟过期，未知或已用密钥统一返回 invalid（无有效性 oracle）；由 tests/routes.spec.ts 覆盖
- 宿主语音转写 API key 绝不离开宿主 —— 手机端仅见展示信息
- 审批应答绑定所属设备会话 —— 多端不能互相抢占
- 未经审计 —— 本项目未经过第三方安全审计，上游 dsh 项目本身也是开发者预览版。在受信网络之外暴露部署前，请自行审阅配对与 gate 源码

漏洞报告流程与部署注意事项见 SECURITY.md。

API 稳定性

自 1.0.0 起，dsh-palm 自身的协议向后兼容：

- /m/api 方法面与 mux/queue/jobs 帧格式只会新增方法/帧——既有方法保持语义不变（破坏性变更需升主版本）
- dsh-palm 运行在 DSH 宿主 API 之上（当前 0.1.5-rc 线）。对宿主 API 变化的适配经预验证升级流程合入，不视为 dsh-palm 自身协议的破坏性变更——宿主 rc 线本身不承诺稳定

项目文档

- CHANGELOG.md —— 版本历史
- COMPATIBILITY.md —— DSH 版本兼容矩阵
- CONTRIBUTING.md —— 开发环境与贡献指南
- SECURITY.md —— 漏洞报告
- packages/dsh-palm/docs/quickstart-tutorial.md —— 三步上手
- packages/dsh-palm/docs/remote-access-guide.md —— 手机如何连上宿主（含完整 frp 拓扑）
- perf/PERFORMANCE-REPORT.md —— 真机延迟实测、基线与抓取方法
- docs/lifecycle —— 带日期的设计文档与发布复盘

许可证

Apache-2.0 —— 见 LICENSE。本项目是 dsh-remote-web-ui 的衍生作品；详见 NOTICE。英文版为本文档的权威版本，中文版随其更新。