dsh-enhancement

简体中文 | English

给 DSH Web 加一层独立的密码入口，同时把它变成可以在手机主屏使用、会发通知的 Web 应用。

设置独立密码后，打开网关地址即可登录 DSH，无需携带 dsh web 启动时打印的 ?token= 地址；装入手机主屏后，任务完成、等待审批等事件会直接推送给你，点通知即可回到对应会话。

功能一览

功能	能做什么
密码网关	用独立端口和密码访问 DSH，无需 ?token=，适合局域网或远程使用
HTTPS	支持上传证书、使用自己的 CA 签发，或由插件自动生成本地 CA
PWA	把 DSH 添加到桌面/手机主屏，支持自定义应用名、主题色和图标
桌面通知	任务完成、等待回答、等待审批、后台任务结束等事件弹出系统通知
手机推送	通过 PWA Web Push 把通知推到手机，点击直接回到对应会话
会话请求头	让第三方 API 路由也携带 DSH 的 session id 请求头，便于上游网关按会话关联请求

独立密码网关

• 默认关闭，监听端口默认 3088，可在设置中改到其他空闲端口。
• 必须先设置访问密码，网关的启用开关才可用；密码只保存哈希，不保存明文。
• 登录后由网关自己的会话维持访问，不需要 DSH 的 ?token=；网关会替浏览器完成 DSH 认证。
• 可以选择监听的网卡地址，默认只在你指定的地址上提供服务。
• 支持 DSH 的正常聊天、文件、终端、WebSocket 和实时流，不只是静态页面。
• 可以设置登录会话的有效期；修改密码后，所有已登录的网关会话都会失效。

HTTPS

PWA 安装、Service Worker 和手机推送都要求 HTTPS（本机 localhost 除外）。设置里提供三种方式：

方式	适用场景
关闭（HTTP）	只在本机或完全可信的网络里临时使用；PWA 和推送不可用
使用已有证书	已经有域名证书，上传证书链和私钥即可
使用 CA 证书自签发	上传自己的 CA，或者让插件生成一个本地 CA，再为当前地址签发证书

使用自签/私有 CA 时，需要把 CA 证书安装到访问设备并设为信任：

• iOS：设置 → 通用 → VPN 与设备管理 安装描述文件，再到 关于本机 → 证书信任设置 开启完全信任。
• Android：设置 → 安全 → 加密与凭据 → 安装证书。

上传的证书必须包含你实际访问用的域名或 IP（SAN），否则浏览器仍会提示证书错误。

PWA

• 接管 DSH 的 manifest、图标、apple-touch-icon、Service Worker 和安装提示。
• 可以自定义应用名称、短名称、主题色，并分别替换桌面/Android/iOS 图标。
• Chromium / Edge 会显示安装提示；iPhone / iPad 使用 Safari 的“分享 → 添加到主屏幕”。
• 安装后从主屏启动，不显示浏览器地址栏，使用体验接近原生应用。
• 只有 HTTPS 下才能安装、注册 Service Worker 和接收推送。

会话请求头

DSH 只在直连官方 DeepSeek API 时发送 x-deepseek-harness-session-id；走 OpenAI 兼容网关（llm-pi-ai）的第三方路由不会携带任何会话标识。启用本功能后，插件会把当前会话的 session id 注入成请求头，让上游网关也能按会话关联请求。

• 默认关闭，默认头名与 DeepSeek 官方一致：x-deepseek-harness-session-id。
• 头名可改成上游网关约定的其它名称；值始终是 DSH 的原始 session id。
• 只作用于第三方 API adapter（llm-pi-ai）；官方 DeepSeek 路由本来就带该头，不受影响。
• 保存后下一次模型请求即生效，不需要重启 DSH。
• 上游若已存在同名头，插件的注入不会覆盖它。

实现说明：注入点在第三方 adapter 的 streamWithSnapshot 原型方法上（DSH 在该方法内重建 pi-ai 的 options，llm/stream 层改不动请求头）。因此本功能依赖宿主内部结构，宿主版本结构变化时会自动旁路并记录原因，不会阻断请求。

为什么显示「尚未挂载」

dsh-base 以休眠态挂载 llm-pi-ai：没有配置任何 provider 路由时它不会注册 adapter（routes.length === 0 直接返回），此时插件无处注入。这是正常状态，不是故障。设置页按原因区分：

提示	含义	处理
已挂载到 N 个第三方 API adapter	正常工作	—
当前没有已注册的第三方模型路由	尚未配置 OpenAI 兼容 provider	到「设置 → 模型」添加，或在本 profile 的 cordis.patch.yml 写 llm-pi-ai 的 providers
已注册 N 个 adapter，但没有一个是第三方 API adapter	只有官方 DeepSeek 路由	同上：需要添加第三方 provider
宿主 llm 服务不可用或结构已变化	版本漂移	插件已旁路，不影响正常请求

通知

支持这些事件，默认全部开启，可以按需勾选：

• 任务完成
• 等待你回答
• 等待审批
• 审批被拒绝
• 子任务结束
• 目标完成或受阻
• 后台任务结束（不会为每条命令都弹）

桌面通知和手机推送共用同一组事件选择，但可以分别关闭其中一个渠道。

点击桌面通知会打开对应会话。Linux 和 Windows 下，如果 DSH 已经打开，会优先切回已有页面并跳转到会话；macOS 使用系统通知的打开链接。Linux 需要系统通知守护支持 action（常见桌面环境都支持）；如果只显示通知、点击没反应，检查系统是否有 notify-send 和可用的通知服务。

手机推送

• 使用标准 Web Push，每台设备单独订阅。
• 在设置里点“订阅本设备”，浏览器会请求通知权限；权限必须由你主动点击触发。
• iOS / iPadOS 需要 16.4 或更高版本，并且必须先把 DSH 添加到主屏幕；Safari 普通标签页收不到推送。
• 可以随时取消订阅，或发送一条测试推送确认链路正常。

安装

dsh plugin --profile web add dsh-enhancement

安装后重启 DSH Web。插件会自动带入手机布局和竖屏布局依赖，不需要再单独安装或启用它们。

开始使用

1. 打开 DSH → 设置 → 插件 → dsh-enhancement。
2. 在“访问控制”里设置密码并保存。设置密码后，“网关配置”里的启用开关才会变为可用。
3. 在“网关配置”里选择监听地址和端口（默认 3088），打开“启用网关”，保存并应用。
4. 如果需要 HTTPS，在同一块里选择证书方式并保存；使用自签 CA 时，把 CA 证书安装到手机/电脑并设为信任。
5. 在手机或另一台电脑上打开网关地址，用刚设置的密码登录，无需 DSH 的 ?token=。
6. 需要主屏应用时，在浏览器里安装 PWA；iOS 使用“分享 → 添加到主屏幕”。
7. 进入“通知”块，确认事件勾选，点“测试桌面通知”；需要手机推送时，打开推送并点“订阅本设备”。

使用建议

• 把网关暴露到公网前，务必使用 HTTPS 和强密码。
• 网关端口不要和 DSH 自身端口（默认 3080）重复；冲突时换一个空闲端口。
• 自签证书只适合自己控制的设备；给多人使用建议上传正式证书。
• 如果只需要在本机用，保持网关关闭即可，DSH 原本的访问方式不受影响。

限制

• 网关、PWA 和推送默认关闭，需要手动配置；未设置密码不能启用网关。
• PWA 安装、Service Worker 和 Web Push 都需要 HTTPS。
• iOS 推送要求 16.4+ 且已添加到主屏幕。
• 自签/私有 CA 需要在每台访问设备上安装并信任。
• Linux 桌面通知的点击依赖系统通知服务的 action 支持。
• 修改密码会使所有网关登录会话失效，需要重新登录。

License

MIT