Pocket H5 · DSH 面板
把独立的 Pocket · H5 预览工作台(上游 Electron / 浏览器版)复用为 DeepSeek Harness Web UI 里的一个 插件面板:左侧栏「Pocket H5」入口 + 主面板里的整套工作台(iPhone 17 尺寸、状态栏/灵动岛/安全区、 横竖屏、画布缩放与真机物理尺寸校准),并补了两个上游没有的入口:手机扫码(把当前预览地址 生成二维码,真机扫一下就能打开)、预览诊断(页面打不开时,直接告诉你「站点禁止被嵌入」还是 「被跳转到登录页」)和登录桥(把 Safari 里已登录的 Cookie 经本机代理注入预览,需要登录的页面 也能在手机框里看),以及和 FlowPilot 同语义的版本与更新(检查/自动检查远端发布 tag、 打开 release 页、复制安装命令)。界面重排为 FlowPilot 风格的工作台(顶栏 + 左侧设置卡 + 右侧画布卡), 并跟随 DSH 主题自动切换浅色/黑暗模式。
- 上游来源与版本:
ui/PROVENANCE.md(index.html144 行 /styles.css1000 行 /app.js323 行 /demo.html原样快照) - 复用与宿主适配说明:
docs/adaptation.md - 独立验证记录:
docs/verification.md
结构
dsh-pocket-h5/
├── package.json # bundle 清单:dsh.bundle.patch + dsh.client
├── cordis.patch.yml # 插入 loader 行 id=pocket-h5
├── index.js # Host 半:ctx.webServer 注册 demo / display / probe / bridge / update 路由
├── client.js # 构建产物(面板 React + 上游界面/逻辑),勿手改
├── build-client.mjs # 构建器:把 ui/ 快照机械适配成 client.js
├── src/client/panel.js # 面板外壳:Shadow DOM 挂载 + 槽位注册 + 侧栏图标 + Host 显示器尺寸回填
├── src/client/qr.js # 新增能力:地址栏二维码按钮 + 手机扫码对话框
├── src/client/diagnose.js # 新增能力:「诊断」按钮 + 嵌入/登录原因诊断对话框
├── src/client/bridge.js # 新增能力:「登录桥」按钮 + 登录态代理对话框/状态条
├── src/client/update.js # 版本与更新:侧栏版本行 + 检查/自动检查对话框
├── src/client/theme.js # 外观层:FlowPilot 风格骨架 + light-dark() 明暗令牌 + 设备边框背景
├── src/client/assets/ # 设备边框素材 (bezel.webp) 与几何 (bezel.json),见其 README
├── lib/bridge.js # Host 登录桥:Safari binarycookies 解析 + 本机反向代理
├── ui/ # 上游原样快照(复用源,不手改)
├── vendor/qrcode/ # 离线二维码编码器(node-qrcode 1.5.4 内核,MIT;PROVENANCE.md + LICENSE)
├── locale/{zh,en}.json # 插件管理页显示的名称与描述
├── icon.svg # 插件图标(复用上游手机图形)
├── tests/host-smoke.mjs # Host 冒烟测试(30 项:demo/display/probe/bridge + 方法/HEAD/穿越边界)
├── tests/client-smoke.mjs # 客户端 bundle 冒烟测试(107 项:factory/槽位/二维码/尺寸/诊断/登录桥/外观层/边框/控件/帮助)
├── tests/bridge-unit.mjs # 登录桥单测(27 项:Cookie 解析/过滤/代理注入/头部改写/隧道)
├── tests/update-unit.mjs # 版本检查单测(40 项:版本比较/tag 提取/缓存/错误/自动检查定时器)
└── docs/ # 复用/适配说明 + 验证记录
工作方式
- 面板:
mainkeyed slot(keypocket-h5)+sidebar.panellist(idpocket-h5,order 95)。 面板组件把上游styles.css与index.html标记装进面板内的 Shadow DOM(样式与宿主隔离), 再运行由ui/app.js机械转换出的mountPocketH5()。 - 预览:仍是
<iframe id="previewFrame">,输入端口 /localhost:3000/path/ 完整 HTTP(S) 地址即可。 - 内置示例:
ui/demo.html由 Host 半通过同源路由/pocket-h5/demo.html提供。 - 持久化:外观、最近地址、显示器校准仍写在
localStorage('pocket-h5-v1')(宿主同源)。 - 登录桥(新增):预览地址旁的「登录桥」按钮。Host 起一个只监听
127.0.0.1的反向代理, 把从 Safari 读取的该站点 Cookie 注入上游请求,iframe 改走代理 → 需要登录的页面在面板里也能打开。 Cookie 只在 Host 内存中;停止桥接、切换面板或闲置 30 分钟后释放。读 Safari Cookie 需要 「完全磁盘访问权限」;也支持手动粘贴 Cookie 头(不需要任何系统权限)。 - 版本与更新(新增):侧栏页脚显示当前版本(点击打开「版本与更新」),握手 Host 的
GET/POST /pocket-h5/update.json。Host 在本机用git ls-remote --tags读取远端发布 tag (30 分钟缓存、启动 5s 后检查一次、之后每 6 小时一次),面板据此提示可更新版本、打开发布页、 复制安装命令;自动检查开关存在本机,不自动安装(避免宿主进程改自己的安装目录)。 - 预览诊断(新增):预览地址旁的「诊断」按钮。Host 半请求目标地址(只读响应头、不跟随无限跳转、
6 秒超时),面板直接给出结论:
X-Frame-Options/ CSPframe-ancestors是否禁止嵌入、是否被重定向到 登录页(或 401/403)、服务是否根本访问不到,并给出下一步建议。 - 手机扫码(新增):地址栏右侧「二维码」按钮。二维码在本地生成(不联网、不把地址发给任何服务),
地址若是
127.0.0.1/localhost会提示改成电脑的局域网 IP;H5 开发服务需监听0.0.0.0/局域网地址。 - 真机尺寸(新增,Host 适配):上游 Electron 版用原生辅助程序读显示器毫米尺寸,浏览器页面读不到。
面板的 Host 半因此在 macOS 上通过 CoreGraphics 探测当前显示器(
/pocket-h5/display.json), Client 把它填进上游已有的window.pocketDisplayMetrics桥 →100%就是真机物理大小,无需校准。 非 macOS 或探测失败时退回浏览器估算(96 CSS px/英寸)+ 工作台自带尺子校准。
与上游 Electron 外壳的差异(能力降级,详见 docs/adaptation.md)
| 能力 | 面板版 |
|---|---|
| 应用内 SOCKS5 代理(Electron session proxy) | 不可用:保留分区但禁用;iframe 请求沿用宿主浏览器网络设置,不静默回退 |
| 原生显示器毫米度量 | 适配为 Host 侧 CoreGraphics 探测(macOS)+ Client 填上游 pocketDisplayMetrics 桥;其它平台退回 screen 估算 + 尺子校准 |
| 开发者工具 | 不可用,按钮保持隐藏 |
| webview 导航事件 / 独立存储分区 | 退化为 iframe load 事件与宿主同源 Cookie |
| 独立窗口、菜单快捷键、单实例锁 | 由宿主负责;面板卸载时清理监听器/定时器/观察器 |
构建
无依赖,需要 Node.js(与 Harness 相同版本即可):
node build-client.mjs
构建会读 ui/ 快照与 vendor/qrcode/,做可审查的宿主适配转换(规则逐条写在 build-client.mjs
文件头),随后自检:$('id') 引用齐全、无 <use>、:host 转换数量、CSS 花括号配对、
23 个二维码模块已打包、node --check client.js。
验证命令:
node tests/host-smoke.mjs # 30 项:demo/display/probe/bridge 路由、方法、HEAD、穿越、Cookie 注入与错误边界
node tests/client-smoke.mjs # 107 项:loader/factory、槽位、二维码、显示器匹配、诊断摘要、登录桥助手、外观层、边框几何、标准控件、? 提示、剪影裁切
node tests/bridge-unit.mjs # 27 项:Safari binarycookies、域名/路径过滤、代理注入、Set-Cookie/Location 改写、隧道
安装 / 打开
从 GitHub 安装(其他机器):
plugin_manager install_bundle target=github:Hazen223/dsh-pocket-h5
本地开发时安装本目录(install_bundle 的 target 传目录路径);已在作者机器的 desktop profile 安装。
更新 client.js 后:
node build-client.mjs # 重新生成 client.js
然后刷新 GUI(⌘R)让浏览器侧重新加载插件模块(修改 client.js 刷新即可;修改 Host 半 index.js
需要重启 DSH 进程——运行中的 Host 不会热重载,plugin_manager 会返回 restart-required)。
打开方式:左侧栏点击 Pocket H5;输入 H5 开发服务地址,点击「打开预览」。
外观与黑暗模式
界面重排为 FlowPilot 风格的工作台(src/client/theme.js):
- 48px 顶栏:左端是应用图标 + 「Pocket」名称(同一行,去掉了多余的「H5 预览」副标签); 右端以面板右边界对齐:当前网址 → 示例/登录桥/诊断 → 预览状态 → 刷新/在系统浏览器打开。
- 左侧设置区 = 一区一卡:预览地址、显示与尺寸、模拟设备、系统外观、页面布局各是一张独立 圆角卡片(不再用横线分隔),卡片内折叠项(代理/校准/屏幕规格)是下沉的小面板;分组标题是小号 加字距灰字,控件统一 34–36px 高的无描边面层,主按钮为黑/白反色(跟随主题)。底部帮助/自动保存/ 重置也单独成一张卡片。
- 说明文字不进版面:遵循「Avoid unnecessary secondary labels and descriptions」——静态说明、 校准/布局提示都不再常驻,收进分区标题旁的圆形 ? 图标里,hover / focus 出现(点击可固定, Esc 关闭);需要时还会附上当前实时状态(如校准状态、布局模式说明)。
- 右侧画布卡:点阵背景 + 手机预览,卡片 12px 圆角 + 1px 边界。
- 设备外框:用你提供的 iPhone 外框图片(
src/client/assets/bezel.webp,屏幕开口已抠成透明) 当「手机壳」盖在长方形页面之上:页面本身是矩形、没有 CSS 圆角,四角由不透明的边框内框自然裁切 (素材开口是 iOS 的 squircle,比 CSS 圆角更准)。屏幕开口按 402×874 @3x 的几何定位,横屏时同一张图 旋转 90°;换边框只需把新图交给python3 tools/prepare-bezel.py <frame.png>。 - iOS 标准状态栏 / 手势条:按 Apple 的几何重画(时间用系统 SF Pro)——状态栏 62pt 高、时间 17pt/600、左内边距 54, 信号 18×12 / Wi‑Fi 17×12 / 电池 27×13(百分比在电池体内),底部手势条 134×5、圆角 2.5、距底 8pt。
- 黑暗模式:所有颜色用
light-dark()成对声明(--p-*令牌),跟随 DSH 的color-scheme自动切换,不需要单独开关;在 DSH 设置里切到深色主题即可看到。设备外框/状态栏保持中性灰, 不参与主题映射(它们是「被预览的手机」,不是面板 chrome)。 - 上游
ui/styles.css仍是基础层(手机几何、控件结构),外观层在其后覆盖;所有上游 id 与事件 绑定保持不变,顶栏只是把品牌/页面/状态/刷新/新窗口节点移动到新的 header 里。
登录态与登录桥(在面板里用 Safari 的登录状态)
能做什么
- 登录桥:面板里的「登录桥」按钮。Host 起一个只监听
127.0.0.1的随机端口反向代理, 把 Safari 里该站点的 Cookie 注入发往目标站的请求;iframe 改走代理,所以原本需要登录的页面 在手机框里也能显示。代理同时会剥离X-Frame-Options/ CSPframe-ancestors,让「禁止被嵌入」 的站点也能看。 - Cookie 来源:
- 自动:从 Safari 的 Cookie 库读取(首次需要给 DSH 授「完全磁盘访问权限」);
- 手动:在登录桥对话框里粘贴
Cookie请求头(例如 DevTools 里任意请求的Cookie:或 「Copy as cURL」里的-H 'Cookie: …'),不需要任何系统权限。
- 边界:Cookie 只存在 Host 内存、不写盘、不打印;停止桥接 / 切换面板 / 闲置 30 分钟即释放; 只对 Cookie 认证有效(密码、扫码、OAuth 弹窗仍需在预览里完成或走系统浏览器)。
使用步骤
- 在 Safari(或 Chrome)里正常登录目标站点;
- 打开面板 → 输入并打开该站点地址 → 点「登录桥」→「从 Safari 导入并开启桥接」;
- 顶部出现「登录桥已启用」状态条即生效;「恢复直连」回到不带登录态的直接预览;
- 如果读不到 Safari Cookie:按提示到「系统设置 → 隐私与安全性 → 完全磁盘访问权限」添加
DSH NEXT并打开开关,退出并重开 DSH;或直接用「手动粘贴 Cookie」。
为什么不能「直接继承」系统浏览器登录态
- Safari/Chrome 的 Cookie 属于各自应用、由系统钥匙串加密,插件与 Host 没有合法的跨应用 API; 登录桥是在这个约束下用「读本机 Cookie + 本机代理」绕出的可用路径,不是浏览器原生能力。
- 内嵌预览本身没有自己的浏览器配置目录,登录桥启用前它用的是 DSH 应用的 Chromium 会话 (在预览里登录一次也会保留)。
- 上游 Electron 版 vs 面板:上游能创建同会话子窗口处理弹窗登录并回传 Cookie;DSH 桌面端会把
window.open交给系统浏览器。弹窗式登录请用「在系统浏览器打开」或手机扫码。
已知限制
- 面板界面沿用上游中文文案,未接入 DSH locale。
- 视觉层:面板跟随 DSH 的主题(浅色/黑暗)自动切换,不单独提供主题开关;设备预览里的 状态栏背景/文字颜色仍是工作台自己的设置项,不随宿主主题变化。
- 目标 H5 若设置
X-Frame-Options/ CSPframe-ancestors会空白(与上游一致,工具不绕过站点限制)。 - 桌面端页面 origin 是
dsh-app://app(安全上下文),预览非 loopback 的http://地址可能被浏览器按 混合内容拦截;127.0.0.1/localhost不受影响(被视为可信来源)。跨设备请在 H5 侧用 HTTPS,或在浏览器版 GUI(http://127.0.0.1:...)中使用。 - 尺寸校准:macOS 上面板会通过 Host 读取显示器物理尺寸,
100%默认就是真机大小 (这是上游 Electron 版的能力,浏览器页面自身读不到)。只有非 macOS 或 Host 探测失败时才需要 「显示与尺寸 → 校准实际尺寸」量一次 200px 线段;手动校准优先于系统估算,点「恢复系统估计」可回到自动值。 若尺寸仍偏小,先确认读数区显示「已按系统显示器尺寸估算」而不是「暂按标准屏幕估算」。 - 跨域 iframe 无法读取真实导航结果,状态条文案以
load事件和地址为准,不代表页面完全正常。 - 显示器尺寸探测失败时不会清掉上一次的探测值(多屏切换后若新屏探测失败,可能暂时沿用旧屏密度); 在同尺寸的两块屏之间移动窗口可能不触发 resize 重取——可切换一次面板或改一下窗口大小来刷新。
- macOS 之外的平台没有 CoreGraphics 探测,
100%仍按 96 CSS px/英寸估算,需要尺子校准一次。 - 登录桥只代理一个 target origin:页面里写死的绝对地址(指向其它域名/CDN)不会经过代理, 这些请求没有登录态;只带 Cookie 认证,Bearer/localStorage 类的登录态不会自动带入。
- 登录桥改变页面 origin(
http://127.0.0.1:<代理端口>):依赖location.origin或精确referer校验的页面可能需要验证;代理会改写请求的 origin/referer 与响应的 Location 以尽量兼容。
版本与发布
应用内检查更新:面板侧栏页脚显示当前版本,Host 每 6 小时用 git ls-remote --tags --refs
读取远端发布 tag(30 分钟缓存;启动 5 秒后先静默检查一次),有新版本时页脚出现 vX.Y.Z 可更新
徽标,点开可看当前/最新版本、构建身份(build-info.json)、仓库与发布页,并复制安装命令:
plugin_manager install_bundle target=github:Hazen223/dsh-pocket-h5#vX.Y.Z
自动检查默认开启,可在「版本与更新」里关闭(偏好存在本机);检查只读 tag,不下载文件、不自动安装。
本地 link: 开发安装会标记为「本地开发版」,仍可手动检查,但更新代码后重启 DSH 即可。
发布走本地脚本(私有仓库没有 Actions runner 配额,tag 推送后 run 会一直 queued):
npm run build # 生成 client.js + build-info.json
npm test # host smoke + client smoke
npm run release -- --version=0.2.0 # 门禁 → 升版本 → 构建 → 提交 → tag → push → Release(附产物)
npm run release -- --version=0.2.0 --dry-run # 只打印计划
npm run release -- --resume=v0.2.0 # 只给已有 tag 补 Release 资产
- 构建身份:
client.js只内嵌版本号(字节级可复现);完整身份(sha / dirty / channel / 时间)写进build-info.json(已 gitignore,进 Release 资产); - Release 标题只写版本号(如
v0.2.0),变更说明放正文; - 资产:
client.js+build-info.json;固定版本安装用#v0.2.0。
公共脱敏版
公共镜像 Hazen223/dsh-pocket-h5-public 由脚本生成(与 FlowPilot 同一套流程):
node tools/public-sync.mjs --version=0.2.0 --out=/tmp/ph5-public-gen # 只生成,便于 review
node tools/public-sync.mjs --source=v0.2.0 --version=0.2.0 --push # 生成 → 提交 → tag → 推送 → Release
- 脱敏:私有仓库地址 → 公共仓库、移除作者机器相关表述、
/Users/…→/Users/x; - 生成后自动跑禁词扫描(命中即中止)+ 构建 + host/client smoke;
- 公共仓库不带
.github(Actions 只在私有仓库手动触发),Release 标题只写版本号、附client.js+build-info.json。
License
本仓库代码以 MIT 发布(见 LICENSE,Copyright © 2026 Hazen223)。
ui/是上游 Pocket · H5 预览工作台(作者自有的独立项目)的原样快照,随仓库附带以保证构建可复现; 如上游项目另有许可证,以该许可证为准(见ui/PROVENANCE.md)。vendor/qrcode/是 node-qrcode 1.5.4 的矩阵内核及其依赖dijkstrajs1.0.3,两者均为 MIT,原始许可文本见vendor/qrcode/LICENSE与vendor/qrcode/node_modules/dijkstrajs/LICENSE.md。client.js是生成产物(由build-client.mjs生成),与源码同许可。
No comments yet. Be the first to write one.