npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

dsh-mobile-ios

v0.2.16

Published

DSH iOS移动伴侣:iPhone/iPad 扫码连接 DSH 桌面端,局域网直连 + Cloudflare Tunnel 固定域名远程两种通道

Readme

DSH Mobile iOS(dsh-mobile-ios)

在 iPhone 上安全地掌控你电脑里的 DeepSeek Harness。

DSH Mobile iOS 是 DSH Moblie 项目的桌面端插件与 iOS移动伴侣 App 的组合:插件在电脑端提供移动网关(REST + WebSocket),iPhone App 通过局域网或隧道配对连接,实时查看任务进度、追加指令、审批待办、查看产物。桌面端侧栏左下角有「iOS移动伴侣」入口,点开即见连接状态与配对码。

面向 iPhone / iPad 采用 SwiftUI 原生界面:钥匙串凭证、系统通知、双栏自适应,而非移动网页布局适配。

安装

在 DSH 桌面端:插件 → 添加插件,输入框填包名 dsh-mobile-ios,点安装即可。 输入框接受的就是 npm 包名(也可带版本,如 [email protected])、Git 仓库 地址或本地插件目录路径。安装源展开后可选:

  • npm 官方源 registry.npmjs.org
  • 中国大陆镜像源 registry.npmmirror.com
  • 自定义地址(内网/私有源,凭据放本机 ~/.npmrc)

首次未显式选源时,DSH 会并发探测官方源与镜像源的 /–/ping,自动选最先响应的那个。 安装前 DSH 会先 pluginManager.inspect 校验包名与 bundle patch(本包带 cordis.patch.yml,校验可过),再按所选源安装。装好后桌面侧栏左下角出现 「📱 iOS移动伴侣」入口,点开即可生成配对码,iPhone App 扫码连接。

本包已发布至 npm:https://www.npmjs.com/package/dsh-mobile-ios。 也可粘贴仓库地址 https://github.com/yelter666/dsh-mobile-ios 或本地目录路径安装。

更新

插件面板右上角的「插件更新」会读 npm registry 的 latest 与当前版本比对:

  • npm 已发布且有新版:提示到插件页卸载后重新安装(或输 dsh-mobile-ios@版本号 更新)——DSH 对非官方按需插件的升级方式是"删除已装包再按相同选择重装";
  • 本地 link 安装的开发态(读不到 registry 版本):提示 git pull 后重启 DSH 桌面端,插件随源码热重载;
  • 网络不可达:如实报不可达,不假装已是最新。

Windows 注意

远程通道依赖外部可执行文件 cloudflared(不含在本包内,插件本体纯 JS 双平台通用)。 Windows 上请下载 cloudflared.exe 加入 PATH,或设 CLOUDFLARED_BIN 指向它; macOS 用 brew install cloudflared。未安装时插件如实隐藏远程入口并给出对应平台指引, 不会伪装可用;局域网通道不依赖 cloudflared,任何平台开箱即用。


能做什么

  • 任务实时同步:桌面会话在手机上以卡片流呈现——需要你 / 进行中 / 更早三段分组,状态徽标与进度条实时刷新;
  • 追加指令与排队:断线也能写,恢复后自动发送(排队语义如实标注,不假装已送达);
  • 待办审批:任务需要你决策时提醒,手机上直接答复;
  • 产物列表:任务生成的文件卡片(名称 / 类型 / 体积),事件流实时推送;
  • 桌面端侧栏入口:左下角「iOS移动伴侣」banner——连接状态点、网关摘要(适配器 / 已配对设备 / 隧道)、一键生成配对码;
  • 多种通道:局域网直连(secure-by-default,默认只听回环)+ cloudflared Quick Tunnel(自动重拉 + 地址漂移广播);
  • 凭证安全:设备凭证存 iOS 钥匙串;配对码 2 分钟有效、限速防爆破、可全量撤销;
  • 崩溃隔离(R12):网关端口冲突自动顺延(3081–3085),隧道崩溃自动重启,插件 apply 永不向宿主抛异常。

快速开始

1. 安装插件(DSH Desktop)

普通用户直接用上文「安装」里的包名方式即可。开发态想从源码加载:

# 在桌面端 profile 注册本地 bundle(改源码后重启 DSH 生效)
dsh plugin --profile desktop add /path/to/dsh-mobile-ios

安装后侧栏左下角出现「iOS移动伴侣」入口(窄栏时为手机图标 + 状态点)。状态点含义:绿色 = 网关健康,红色 = 网关不可达(插件端口被占时会自动顺延并自恢复)。

2. 连接 iPhone(局域网)

  1. 电脑与手机连上同一 Wi-Fi;
  2. 点侧栏「iOS移动伴侣」→ 面板内 生成配对码(6 位数字,约 2 分钟有效);
  3. iPhone 打开 DSH App → 连接 → 输入电脑地址(局域网IP:端口,端口见面板「网关地址」行)与配对码;
  4. 首次连接 iOS 会请求「本地网络」权限,请点允许。

开发联调可用 sidecar 独立进程模式:node entries/sidecar.mjs --host=mock --dev --lan=true(mock 宿主回放契约数据,端口 3199)。

3. 远程访问(外网)

支持 cloudflared Quick Tunnel(插件自动拉起并广播地址漂移)。命名隧道 / 自建反代接入方式与局域网相同——手机端把地址换成隧道域名即可,凭证与配对机制不变。未安装 cloudflared 时客户端如实隐藏入口(不伪装可用)。

安全

  • secure-by-default:网关默认只监听 127.0.0.1;开放局域网是显式动作(allowLan: true);
  • 管理面回环-only:配对码生成、设备撤销、桌面端摘要只允许主机本机操作(同网段设备刷不了码、炸不了同伴设备);
  • 配对凭证:设备 Token 存 iOS 钥匙串;WS 走一次性票据(TTL 30s);配对码 5 次/窗限速;
  • 脱敏:隧道日志与诊断包自动抹除 JWT / dt_ token / Bearer 头;诊断包不含绝对路径、prompt 正文、产物内容;
  • 最小摘要:/mobile/v1/desktop/summary 只含版本 / 适配器 / 设备数 / 隧道态等展示字段。

故障排查

| 现象 | 处理 | |---|---| | 手机提示「无法连接到电脑」 | 确认电脑端 DSH 在运行、手机与电脑同一 Wi-Fi、地址含端口(如 192.168.x.x:3081) | | 配对码过期 | 点侧栏「iOS移动伴侣」重新生成(同窗口限 5 次,旧码立即失效) | | banner 状态点红色 | 网关未起或端口被占——插件自动顺延 3082–3085,重启 DSH 再试 | | 手机「需要重新配对」 | 设备被电脑端撤销或凭证过期;手机端「重新配对」不清本地历史 | | 隧道地址变了 | Quick Tunnel 重启后域名会变(网关会广播 addr_changed),手机端用新地址重配对 |

兼容性

| 组件 | 要求 | |---|---| | 桌面端 | DeepSeek Harness(desktop profile,Node ≥ 20) | | 手机端 | iOS 18+(iPhone / iPad 通用,双栏自适应;Duo 展开态横屏双栏) | | 通道 | 局域网 / cloudflared Quick Tunnel / 任意 HTTPS 反代 |

工作原理

iPhone App ──REST/WS──> dsh-mobile-ios 网关(宿主进程内,回环或 LAN)
                              │
                              ├─ mock 宿主   契约夹具回放(联调基线)
                              └─ mux 宿主    进程内直取宿主 cordis 服务
                                             (sessionController 等,真数据进手机)
桌面端侧栏 banner ← slots 注入 ← lib/client.js(本包 ./client 导出)
  • 插件与宿主之间走进程内适配器(cordis 子上下文向上解析 sessionController 等服务),宿主 RPC 的 9 个控制器动作全集与方法映射见 spike0/RUNBOOK.md §10;
  • 未映射的方法一律返回协议码 4021(契约保留位),绝不假装成功;
  • 桌面端 banner 通过 dsh.client 声明注入宿主 web app(slots.inject("sidebar.footer.action")),面板数据来自回环-only 摘要端点。

许可

MIT


开发与架构(附录)

1. 目录

gateway/                     # 包名 dsh-mobile-ios(插件标识)
├── src/
│   ├── protocol.mjs        契约常量 + 错误码表(含 HTTP 状态与"是否该重试")
│   ├── ring.mjs            每任务 seq + 环缓冲(容量 2000,缺口如实标记)
│   ├── pairing.mjs         配对码 / 设备凭证 / 限速 / 撤销(损坏自愈 R12)
│   ├── gateway.mjs         传输无关核心:会话、扇出、握手、幂等   ← ADR-12
│   ├── rest.mjs            /mobile/v1/* 一元接口 + 桌面端 CORS 白名单
│   ├── ws.mjs              RFC6455 子集 + 票据鉴权 + 握手泵
│   ├── server.mjs          组装 + 只监听回环 + 端口顺延
│   ├── tunnel.mjs          cloudflared Quick Tunnel 生命周期(GW-8,自动重拉+脱敏)
│   └── adapter/
│       ├── mock-host.mjs   夹具驱动的宿主(D3)
│       ├── mux-host.mjs    HTTP 探测适配器(X2 考古用)
│       └── cordis-host.mjs 进程内真宿主适配器(X2 落地,session/* 映射)
├── lib/client.js           桌面端 UI 注入模块(X3:banner + 面板)
├── entries/
│   ├── plugin.mjs          Cordis 插件入口(apply 永不外抛)
│   └── sidecar.mjs         独立进程入口
├── spike0/
│   ├── probe.mjs           六项验收探测 → last-report.json
│   ├── RUNBOOK.md          验证手册(X1/X2 证据链、借鉴机制、方法表)
│   └── demo-swift/main.swift  Apple 原生协议栈演示客户端
└── test/
    ├── selftest.mjs        端到端自检(鉴权/幂等/握手/续传/隔离/桌面端 CORS)
    ├── resilience.mjs      韧性验收(断链续传/缺口/宿主重启)
    ├── ops.mjs             运维验收(隧道启停/地址漂移/诊断包)
    ├── borrowed.mjs        借鉴机制验收(配对自愈/隧道重拉/脱敏/回环管理面)
    └── mux-table.mjs       X2 方法表验收(32 断言)

2. 开发命令

# ① 起服务(mock 宿主,附带开箱可用的配对码)
node entries/sidecar.mjs --host=mock --dev
#    REST  http://127.0.0.1:3081/mobile/v1/health
#    WS    ws://127.0.0.1:3081/ws/mobile

# ② 全量契约测试(11 套件 532 断言)
npm test

# ③ Spike-0 六项验收(本机)
node spike0/probe.mjs
#    真机:node spike0/probe.mjs --host=mux --mux-url=http://127.0.0.1:3000

# ④ Apple 原生客户端演示(先编译一次)
swiftc -O spike0/demo-swift/main.swift -o /tmp/dsh-demo
bash spike0/run-demo.sh            # 自动起服务 → 造 3 帧 → 跑客户端 → 收工

3. 契约增补(v0.1 → v0.2,全部是加法)

| 增补 | 内容 | 为什么必须加 | |---|---|---| | POST /mobile/v1/ws-ticket | 返回一次性票据(TTL 30s),能力名 ws.ticket | 长期凭证不应出现在 WS 升级路径里;ADR-13 | | Authorization: Ticket <t> | 票据的第二条承载方式 | URLSession 不允许自定义 Sec-WebSocket-Protocol 时仍能鉴权(已实测) | | hello.cursors | {taskId: seq} 逐任务游标 | 契约 v0.1 的 hello.lastSeq 是单值,而 seq 是每任务独立的——两者不自洽 | | ready.degraded | 宿主未就绪时为 true + reason | 否则网关会连启动都失败,用户只看到「连不上」 | | 4021 的用法 | 能力缺失一律 4021,不返回 5xx | 客户端据此隐藏控件,而不是弹错 | | hello.gen / ready.genChanged | 客户端回带上次的 gen;不一致则 gap=true、resumed=0 | 只靠客户端比 gen 会晚一步——它会先收到「补不到帧」的 ready,误读成「没有新事件」,静默丢数据 | | gateway 事件 host.restarted | 重启时推 {gen, prevGen},随后 1012 关闭 | 让在线客户端不必等重连才发现代际变了 | | GET /mobile/v1/desktop/summary | 桌面端 banner 状态摘要(回环-only + CORS 白名单) | X3 侧栏注入需要跨源读健康态与设备数 |

未改动的部分:帧形状、错误码含义、seq 语义、幂等窗口。v0.1 的 31 份夹具仍可直接回放。

4. 边界纪律(ADR-12)

改宿主对接只碰 src/adapter/,其余目录不允许出现任何宿主 API 字面量。 判定方法:grep -rn "remote.mux" src/ entries/ 的结果必须只出现在 adapter/ 内。

core 只依赖适配器的 9 个方法: info / listTasks / getTask / listArtifacts / createTask / appendMessage / cancelTask / answerTodo / subscribe。 换插件换 sidecar、换 mock 换真机,都不触碰 core。

5. 插件接入

entries/plugin.mjs 导出 apply(ctx, config),对 Cordis 的假设只有两条:

  1. ctx.effect(cb) 或 ctx.on('dispose', fn) 提供卸载钩子(两者都支持,取先存在的);
  2. ctx.logger.info 或可调用 logger 用于日志(都没有则退回 console)。

配置项(见 cordis.patch.yml):port / host(mock|mux)/ muxUrl / dev / allowLan / hostSuffixes / printPairingCode / autoRestart / pairingFile。 apply 返回 {ok, steps, address, error, ready},probe.mjs 就是靠 steps 判定「挂载」是否成立。

若宿主的插件签名不是 apply(ctx, config)(例如要求 export const inject、或插件目录有 manifest 约束),只改 entries/plugin.mjs,不要动 src/。这是 ADR-12 的收益点。

6. 验证证据(本机实测)

| 项 | 结果 | |---|---| | npm test(11 套件) | 532 通过 / 0 失败(自检 67 + 运维 44 + 韧性 29 + 借鉴 54 + mux 方法表 53 + 隧道 148 + 帧/产物/附件/增强/会话动作等) | | node spike0/probe.mjs(mock) | PASS,6 项阻塞全过;真宿主与 mux 两项目标为 WARN/SKIP(不假装通过) | | node spike0/probe.mjs --host=mux(不可达) | FAIL,如实报「宿主降级」与 status=0,不是假绿 | | X1 宿主挂载 | 已验证(2026-11-16):desktop profile bundle 加载,127.0.0.1:3081 服务,/health + 配对码 + 4001 鉴权 | | X2 方法表 | 已落地:cordis-host.mjs 进程内适配器 + 32 断言;真宿主对照 diag 待验 | | iOS 端到端(ios/DSHMobileKit) | 634 / 634 全绿(Kit spike)+ 模拟器真跑截图链路 |

韧性验收覆盖的关键行为:异常断链后按游标续传(1..7 零丢失零重复)、缺口时 gap=true 且 resumeFrom 指向真实下界、宿主重启后旧 gen 握手被要求全量重建(gap=true/resumed=0)而新 gen 不误报、重启后 seq 从 1 重开、幂等窗口不随重启失效(duplicate=true)。

自检覆盖的关键行为:凭证 4001/4009 分流、配对码单次有效与 5 次限速(4029)、submissionId 幂等重放、/rollback 返 4021、票据一次性(重放 401)、协议版本 4004 + close 1008、installId 不一致 4009、同任务 seq 连续、lastSeq 续传、环缓冲缺口标记、停服端口释放、插件卸载端口释放、插件异常不外抛、桌面端 CORS 白名单与预检。

7. 明确的未验证项(不要在汇报里说成已完成)

| 项 | 现状 | 谁能解开 | |---|---|---| | X2 真宿主实跑对照 | cordis-host 适配器落地但未在真宿主里对照 diag 服务可见性 | 桌面端打开 host: mux 重启 | | R12 插件在宿主进程内的崩溃隔离压测 | 已做 try/catch 与端口顺延,未在真实宿主里压测 | 真机 | | R9 本地网络权限弹窗取证 | 真机已通基础链路,弹窗文案与「不允许」分支取证待记录 | iPhone 真机 | | Live Activity | 未实现 | S-2/S-3 |

8. S-1 故障注入(本机可跑,不需要真机)

三类失败必须能「可编程复现」,否则 iOS 的「断线不误判」根本测不实。仅 --dev 模式开放:

| 端点 | 作用 | 对应验收 | |---|---|---| | POST /__mock/drop | 不发 close 帧,直接掐 socket | 异常断链 → 重连按游标补帧,零丢失零重复 | | POST /__mock/gap {taskId, keep} | 裁掉旧帧,抬高环缓冲下界 | 游标早于下界 → gap=true 且 resumeFrom 指向真实下界 | | POST /__mock/restart-host {reason} | 换 gen + 清环 + 推 host.restarted + 1012 断开 | 旧 gen 握手 → gap=true / resumed=0,强制全量重建 |

两条与宿主有关的约定,都是端到端跑出来才补的:

| 约定 | 原因 | |---|---| | restart-host 会调用 host.onHostRestart(),宿主应把在跑的任务标成 interrupted | 真实宿主重启后任务不会复活。宿主若仍报 running,客户端刚降级的「已中断 · 可续」会被下一份列表快照覆盖回去,永远转圈(FR-TASK-06) | | 列表与详情里的 lastSeq 由网关补齐(取环缓冲的 maxSeq) | seq 属于网关的事件空间,宿主不掌握。宿主返回 0 会让客户端把每份快照判成「比事件旧」而拒用,任务永远停在占位行 |

9. 隧道(GW-8)与诊断包(GW-9)

| 接口 | 说明 | |---|---| | GET /mobile/v1/tunnel | 状态。executable: missing 表示主机未装 cloudflared,客户端应隐藏入口 | | POST /mobile/v1/tunnel/start | 启动,幂等。地址漂移时向在线会话广播 gateway{event:"addr_changed"} | | POST /mobile/v1/tunnel/stop | 关闭并回收子进程(网关退出时也会收,不留孤儿) | | GET /mobile/v1/diag/bundle | 脱敏诊断包,含可直接粘贴的 text 字段 |

三条硬约束:

  1. 不伪装:未安装 cloudflared → 4021 + 可执行指导,不返回 500,也不给假地址。
  2. 地址漂移必须广播:Quick Tunnel 重启后域名会变,不推 addr_changed 客户端会一直连旧域名。 lastUrl 跨 stop/start 保留,正是为了检测这种真实漂移。
  3. 诊断包不外发隐私:不含设备 token、绝对路径、prompt 正文、产物内容(test/ops.mjs 有对应断言)。

10. 下一步

  1. X2 真宿主实跑:desktop profile 的 cordis.patch.yml 打开 host: mux 重启,对照 diag 服务可见性。
  2. 真机安装 cloudflared 后(macOS brew install cloudflared;Windows 下载 cloudflared.exe 加入 PATH),把 --tunnel-bin 指向真实可执行文件复跑 test/ops.mjs,确认解析逻辑与真实 输出格式一致(当前用假脚本验证的是格式契约,不是真实二进制)。
  3. iOS 界面层持续完善(连接指引页 / 附件契约升级 / 模型选择宿主映射)。