dsh-mobile-ios 0.2.16 → 0.2.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,284 +1,311 @@
1
- # DSH Mobile iOS(dsh-mobile-ios)
2
-
3
- **在 iPhone 上安全地掌控你电脑里的 DeepSeek Harness。**
4
-
5
- DSH Mobile iOS 是 DSH Moblie 项目的桌面端插件与 iOS移动伴侣 App 的组合:插件在电脑端提供移动网关(REST + WebSocket),iPhone App 通过局域网或隧道配对连接,实时查看任务进度、追加指令、审批待办、查看产物。桌面端侧栏左下角有「**iOS移动伴侣**」入口,点开即见连接状态与配对码。
6
-
7
- 面向 iPhone / iPad 采用 **SwiftUI 原生界面**:钥匙串凭证、系统通知、双栏自适应,而非移动网页布局适配。
8
-
9
- ## 安装
10
-
11
- 在 DSH 桌面端:**插件 → 添加插件**,输入框填包名 `dsh-mobile-ios`,点安装即可。
12
- 输入框接受的就是 **npm 包名**(也可带版本,如 `dsh-mobile-ios@0.2.2`)、Git 仓库
13
- 地址或本地插件目录路径。安装源展开后可选:
14
-
15
- - **npm 官方源** `registry.npmjs.org`
16
- - **中国大陆镜像源** `registry.npmmirror.com`
17
- - **自定义地址**(内网/私有源,凭据放本机 `~/.npmrc`)
18
-
19
- 首次未显式选源时,DSH 会并发探测官方源与镜像源的 `/–/ping`,自动选最先响应的那个。
20
- 安装前 DSH 会先 `pluginManager.inspect` 校验包名与 bundle patch(本包带
21
- `cordis.patch.yml`,校验可过),再按所选源安装。装好后桌面侧栏左下角出现
22
- 「📱 iOS移动伴侣」入口,点开即可生成配对码,iPhone App 扫码连接。
23
-
24
- > 本包已发布至 npm:`https://www.npmjs.com/package/dsh-mobile-ios`。
25
- > 也可粘贴仓库地址 `https://github.com/yelter666/dsh-mobile-ios` 或本地目录路径安装。
26
-
27
- ### 更新
28
-
29
- 插件面板右上角的「插件更新」会读 npm registry 的 `latest` 与当前版本比对:
30
-
31
- - npm 已发布且有新版:提示到插件页**卸载后重新安装**(或输 `dsh-mobile-ios@版本号`
32
- 更新)——DSH 对非官方按需插件的升级方式是"删除已装包再按相同选择重装";
33
- - 本地 link 安装的开发态(读不到 registry 版本):提示 `git pull` 后重启 DSH
34
- 桌面端,插件随源码热重载;
35
- - 网络不可达:如实报不可达,不假装已是最新。
36
-
37
- ### Windows 注意
38
-
39
- 远程通道依赖外部可执行文件 `cloudflared`(**不含在本包内**,插件本体纯 JS 双平台通用)。
40
- Windows 上请下载 `cloudflared.exe` 加入 PATH,或设 `CLOUDFLARED_BIN` 指向它;
41
- macOS 用 `brew install cloudflared`。未安装时插件如实隐藏远程入口并给出对应平台指引,
42
- 不会伪装可用;局域网通道不依赖 cloudflared,任何平台开箱即用。
43
-
44
- ---
45
-
46
- ## 能做什么
47
-
48
- - **任务实时同步**:桌面会话在手机上以卡片流呈现——需要你 / 进行中 / 更早三段分组,状态徽标与进度条实时刷新;
49
- - **追加指令与排队**:断线也能写,恢复后自动发送(排队语义如实标注,不假装已送达);
50
- - **待办审批**:任务需要你决策时提醒,手机上直接答复;
51
- - **产物列表**:任务生成的文件卡片(名称 / 类型 / 体积),事件流实时推送;
52
- - **桌面端侧栏入口**:左下角「iOS移动伴侣」banner——连接状态点、网关摘要(适配器 / 已配对设备 / 隧道)、一键生成配对码;
53
- - **多种通道**:局域网直连(secure-by-default,默认只听回环)+ cloudflared Quick Tunnel(自动重拉 + 地址漂移广播);
54
- - **凭证安全**:设备凭证存 iOS 钥匙串;配对码 2 分钟有效、限速防爆破、可全量撤销;
55
- - **崩溃隔离(R12)**:网关端口冲突自动顺延(3081–3085),隧道崩溃自动重启,插件 apply 永不向宿主抛异常。
56
-
57
- ## 快速开始
58
-
59
- ### 1. 安装插件(DSH Desktop)
60
-
61
- 普通用户直接用上文「安装」里的包名方式即可。开发态想从源码加载:
62
-
63
- ```bash
64
- # 在桌面端 profile 注册本地 bundle(改源码后重启 DSH 生效)
65
- dsh plugin --profile desktop add /path/to/dsh-mobile-ios
66
- ```
67
-
68
- 安装后侧栏左下角出现「**iOS移动伴侣**」入口(窄栏时为手机图标 + 状态点)。状态点含义:**绿色** = 网关健康,**红色** = 网关不可达(插件端口被占时会自动顺延并自恢复)。
69
-
70
- ### 2. 连接 iPhone(局域网)
71
-
72
- 1. 电脑与手机连上**同一 Wi-Fi**;
73
- 2. 点侧栏「iOS移动伴侣」→ 面板内 **生成配对码**(6 位数字,约 2 分钟有效);
74
- 3. iPhone 打开 DSH App → 连接 → 输入电脑地址(`局域网IP:端口`,端口见面板「网关地址」行)与配对码;
75
- 4. 首次连接 iOS 会请求「本地网络」权限,请点**允许**。
76
-
77
- > 开发联调可用 sidecar 独立进程模式:`node entries/sidecar.mjs --host=mock --dev --lan=true`(mock 宿主回放契约数据,端口 3199)。
78
-
79
- ### 3. 远程访问(外网)
80
-
81
- 支持 cloudflared Quick Tunnel(插件自动拉起并广播地址漂移)。命名隧道 / 自建反代接入方式与局域网相同——手机端把地址换成隧道域名即可,凭证与配对机制不变。未安装 cloudflared 时客户端如实隐藏入口(不伪装可用)。
82
-
83
- ## 安全
84
-
85
- - **secure-by-default**:网关默认只监听 `127.0.0.1`;开放局域网是显式动作(`allowLan: true`);
86
- - **管理面回环-only**:配对码生成、设备撤销、桌面端摘要只允许主机本机操作(同网段设备刷不了码、炸不了同伴设备);
87
- - **配对凭证**:设备 Token 存 iOS 钥匙串;WS 走一次性票据(TTL 30s);配对码 5 次/窗限速;
88
- - **脱敏**:隧道日志与诊断包自动抹除 JWT / `dt_` token / Bearer 头;诊断包不含绝对路径、prompt 正文、产物内容;
89
- - **最小摘要**:`/mobile/v1/desktop/summary` 只含版本 / 适配器 / 设备数 / 隧道态等展示字段。
90
-
91
- ## 故障排查
92
-
93
- | 现象 | 处理 |
94
- |---|---|
95
- | 手机提示「无法连接到电脑」 | 确认电脑端 DSH 在运行、手机与电脑同一 Wi-Fi、地址含端口(如 `192.168.x.x:3081`) |
96
- | 配对码过期 | 点侧栏「iOS移动伴侣」重新生成(同窗口限 5 次,旧码立即失效) |
97
- | banner 状态点红色 | 网关未起或端口被占——插件自动顺延 3082–3085,重启 DSH 再试 |
98
- | 手机「需要重新配对」 | 设备被电脑端撤销或凭证过期;手机端「重新配对」不清本地历史 |
99
- | 隧道地址变了 | Quick Tunnel 重启后域名会变(网关会广播 `addr_changed`),手机端用新地址重配对 |
100
-
101
- ## 兼容性
102
-
103
- | 组件 | 要求 |
104
- |---|---|
105
- | 桌面端 | DeepSeek Harness(desktop profile,Node ≥ 20) |
106
- | 手机端 | iOS 18+(iPhone / iPad 通用,双栏自适应;Duo 展开态横屏双栏) |
107
- | 通道 | 局域网 / cloudflared Quick Tunnel / 任意 HTTPS 反代 |
108
-
109
- ## 工作原理
110
-
111
- ```
112
- iPhone App ──REST/WS──> dsh-mobile-ios 网关(宿主进程内,回环或 LAN)
113
- │
114
- ├─ mock 宿主 契约夹具回放(联调基线)
115
- └─ mux 宿主 进程内直取宿主 cordis 服务
116
- (sessionController 等,真数据进手机)
117
- 桌面端侧栏 banner ← slots 注入 ← lib/client.js(本包 ./client 导出)
118
- ```
119
-
120
- - 插件与宿主之间走**进程内适配器**(cordis 子上下文向上解析 `sessionController` 等服务),宿主 RPC 的 9 个控制器动作全集与方法映射见 `spike0/RUNBOOK.md` §10;
121
- - 未映射的方法一律返回协议码 `4021`(契约保留位),绝不假装成功;
122
- - 桌面端 banner 通过 `dsh.client` 声明注入宿主 web app(`slots.inject("sidebar.footer.action")`),面板数据来自回环-only 摘要端点。
123
-
124
- ## 许可
125
-
126
- MIT
127
-
128
- ---
129
-
130
- # 开发与架构(附录)
131
-
132
- ## 1. 目录
133
-
134
- ```
135
- gateway/ # 包名 dsh-mobile-ios(插件标识)
136
- ├── src/
137
- │ ├── protocol.mjs 契约常量 + 错误码表(含 HTTP 状态与"是否该重试")
138
- │ ├── ring.mjs 每任务 seq + 环缓冲(容量 2000,缺口如实标记)
139
- │ ├── pairing.mjs 配对码 / 设备凭证 / 限速 / 撤销(损坏自愈 R12)
140
- │ ├── gateway.mjs 传输无关核心:会话、扇出、握手、幂等 ← ADR-12
141
- │ ├── rest.mjs /mobile/v1/* 一元接口 + 桌面端 CORS 白名单
142
- │ ├── ws.mjs RFC6455 子集 + 票据鉴权 + 握手泵
143
- │ ├── server.mjs 组装 + 只监听回环 + 端口顺延
144
- │ ├── tunnel.mjs cloudflared Quick Tunnel 生命周期(GW-8,自动重拉+脱敏)
145
- │ └── adapter/
146
- │ ├── mock-host.mjs 夹具驱动的宿主(D3)
147
- │ ├── mux-host.mjs HTTP 探测适配器(X2 考古用)
148
- │ └── cordis-host.mjs 进程内真宿主适配器(X2 落地,session/* 映射)
149
- ├── lib/client.js 桌面端 UI 注入模块(X3:banner + 面板)
150
- ├── entries/
151
- │ ├── plugin.mjs Cordis 插件入口(apply 永不外抛)
152
- │ └── sidecar.mjs 独立进程入口
153
- ├── spike0/
154
- │ ├── probe.mjs 六项验收探测 → last-report.json
155
- │ ├── RUNBOOK.md 验证手册(X1/X2 证据链、借鉴机制、方法表)
156
- │ └── demo-swift/main.swift Apple 原生协议栈演示客户端
157
- └── test/
158
- ├── selftest.mjs 端到端自检(鉴权/幂等/握手/续传/隔离/桌面端 CORS)
159
- ├── resilience.mjs 韧性验收(断链续传/缺口/宿主重启)
160
- ├── ops.mjs 运维验收(隧道启停/地址漂移/诊断包)
161
- ├── borrowed.mjs 借鉴机制验收(配对自愈/隧道重拉/脱敏/回环管理面)
162
- └── mux-table.mjs X2 方法表验收(32 断言)
163
- ```
164
-
165
- ## 2. 开发命令
166
-
167
- ```bash
168
- # ① 起服务(mock 宿主,附带开箱可用的配对码)
169
- node entries/sidecar.mjs --host=mock --dev
170
- # REST http://127.0.0.1:3081/mobile/v1/health
171
- # WS ws://127.0.0.1:3081/ws/mobile
172
-
173
- # ② 全量契约测试(11 套件 532 断言)
174
- npm test
175
-
176
- # ③ Spike-0 六项验收(本机)
177
- node spike0/probe.mjs
178
- # 真机:node spike0/probe.mjs --host=mux --mux-url=http://127.0.0.1:3000
179
-
180
- # ④ Apple 原生客户端演示(先编译一次)
181
- swiftc -O spike0/demo-swift/main.swift -o /tmp/dsh-demo
182
- bash spike0/run-demo.sh # 自动起服务 → 造 3 帧 → 跑客户端 → 收工
183
- ```
184
-
185
- ## 3. 契约增补(v0.1 → v0.2,全部是加法)
186
-
187
- | 增补 | 内容 | 为什么必须加 |
188
- |---|---|---|
189
- | `POST /mobile/v1/ws-ticket` | 返回一次性票据(TTL 30s),能力名 `ws.ticket` | 长期凭证不应出现在 WS 升级路径里;ADR-13 |
190
- | `Authorization: Ticket <t>` | 票据的第二条承载方式 | `URLSession` 不允许自定义 `Sec-WebSocket-Protocol` 时仍能鉴权(已实测) |
191
- | `hello.cursors` | `{taskId: seq}` 逐任务游标 | 契约 v0.1 的 `hello.lastSeq` 是单值,而 `seq` 是每任务独立的——两者不自洽 |
192
- | `ready.degraded` | 宿主未就绪时为 `true` + `reason` | 否则网关会连启动都失败,用户只看到「连不上」 |
193
- | `4021` 的用法 | 能力缺失一律 4021,不返回 5xx | 客户端据此隐藏控件,而不是弹错 |
194
- | `hello.gen` / `ready.genChanged` | 客户端回带上次的 `gen`;不一致则 `gap=true`、`resumed=0` | 只靠客户端比 `gen` 会晚一步——它会先收到「补不到帧」的 ready,误读成「没有新事件」,静默丢数据 |
195
- | `gateway` 事件 `host.restarted` | 重启时推 `{gen, prevGen}`,随后 1012 关闭 | 让在线客户端不必等重连才发现代际变了 |
196
- | `GET /mobile/v1/desktop/summary` | 桌面端 banner 状态摘要(回环-only + CORS 白名单) | X3 侧栏注入需要跨源读健康态与设备数 |
197
-
198
- **未改动的部分**:帧形状、错误码含义、`seq` 语义、幂等窗口。v0.1 的 31 份夹具仍可直接回放。
199
-
200
- ## 4. 边界纪律(ADR-12)
201
-
202
- 改宿主对接只碰 `src/adapter/`,其余目录**不允许出现任何宿主 API 字面量**。
203
- 判定方法:`grep -rn "remote.mux" src/ entries/` 的结果必须只出现在 `adapter/` 内。
204
-
205
- `core` 只依赖适配器的 9 个方法:
206
- `info / listTasks / getTask / listArtifacts / createTask / appendMessage / cancelTask / answerTodo / subscribe`。
207
- 换插件换 sidecar、换 mock 换真机,都不触碰 `core`。
208
-
209
- ## 5. 插件接入
210
-
211
- `entries/plugin.mjs` 导出 `apply(ctx, config)`,对 Cordis 的假设只有两条:
212
-
213
- 1. `ctx.effect(cb)` 或 `ctx.on('dispose', fn)` 提供卸载钩子(两者都支持,取先存在的);
214
- 2. `ctx.logger.info` 或可调用 logger 用于日志(都没有则退回 `console`)。
215
-
216
- 配置项(见 `cordis.patch.yml`):`port` / `host`(`mock|mux`)/ `muxUrl` / `dev` / `allowLan` / `hostSuffixes` / `printPairingCode` / `autoRestart` / `pairingFile`。
217
- `apply` 返回 `{ok, steps, address, error, ready}`,`probe.mjs` 就是靠 `steps` 判定「挂载」是否成立。
218
-
219
- > 若宿主的插件签名不是 `apply(ctx, config)`(例如要求 `export const inject`、或插件目录有 manifest 约束),**只改 `entries/plugin.mjs`,不要动 `src/`**。这是 ADR-12 的收益点。
220
-
221
- ## 6. 验证证据(本机实测)
222
-
223
- | 项 | 结果 |
224
- |---|---|
225
- | `npm test`(11 套件) | **532 通过 / 0 失败**(自检 67 + 运维 44 + 韧性 29 + 借鉴 54 + mux 方法表 53 + 隧道 148 + 帧/产物/附件/增强/会话动作等) |
226
- | `node spike0/probe.mjs`(mock) | **PASS**,6 项阻塞全过;真宿主与 mux 两项目标为 WARN/SKIP(不假装通过) |
227
- | `node spike0/probe.mjs --host=mux`(不可达) | **FAIL**,如实报「宿主降级」与 `status=0`,不是假绿 |
228
- | X1 宿主挂载 | **已验证**(2026-11-16):desktop profile bundle 加载,127.0.0.1:3081 服务,/health + 配对码 + 4001 鉴权 |
229
- | X2 方法表 | **已落地**:`cordis-host.mjs` 进程内适配器 + 32 断言;真宿主对照 diag 待验 |
230
- | iOS 端到端(`ios/DSHMobileKit`) | **634 / 634** 全绿(Kit spike)+ 模拟器真跑截图链路 |
231
-
232
- 韧性验收覆盖的关键行为:异常断链后按游标续传(1..7 零丢失零重复)、缺口时 `gap=true` 且 `resumeFrom` 指向真实下界、宿主重启后旧 gen 握手被要求全量重建(`gap=true/resumed=0`)而新 gen 不误报、重启后 seq 从 1 重开、幂等窗口不随重启失效(`duplicate=true`)。
233
-
234
- 自检覆盖的关键行为:凭证 4001/4009 分流、配对码单次有效与 5 次限速(4029)、`submissionId` 幂等重放、`/rollback` 返 4021、票据一次性(重放 401)、协议版本 4004 + close 1008、installId 不一致 4009、同任务 seq 连续、`lastSeq` 续传、环缓冲缺口标记、停服端口释放、插件卸载端口释放、插件异常不外抛、桌面端 CORS 白名单与预检。
235
-
236
- ## 7. 明确的未验证项(不要在汇报里说成已完成)
237
-
238
- | 项 | 现状 | 谁能解开 |
239
- |---|---|---|
240
- | X2 真宿主实跑对照 | cordis-host 适配器落地但未在真宿主里对照 diag 服务可见性 | 桌面端打开 `host: mux` 重启 |
241
- | R12 插件在宿主进程内的崩溃隔离压测 | 已做 try/catch 与端口顺延,未在真实宿主里压测 | 真机 |
242
- | R9 本地网络权限弹窗取证 | 真机已通基础链路,弹窗文案与「不允许」分支取证待记录 | iPhone 真机 |
243
- | Live Activity | 未实现 | S-2/S-3 |
244
-
245
- ## 8. S-1 故障注入(本机可跑,不需要真机)
246
-
247
- 三类失败必须能「可编程复现」,否则 iOS 的「断线不误判」根本测不实。仅 `--dev` 模式开放:
248
-
249
- | 端点 | 作用 | 对应验收 |
250
- |---|---|---|
251
- | `POST /__mock/drop` | 不发 close 帧,直接掐 socket | 异常断链 → 重连按游标补帧,零丢失零重复 |
252
- | `POST /__mock/gap {taskId, keep}` | 裁掉旧帧,抬高环缓冲下界 | 游标早于下界 → `gap=true` 且 `resumeFrom` 指向真实下界 |
253
- | `POST /__mock/restart-host {reason}` | 换 gen + 清环 + 推 `host.restarted` + 1012 断开 | 旧 gen 握手 → `gap=true / resumed=0`,强制全量重建 |
254
-
255
- 两条与宿主有关的约定,都是端到端跑出来才补的:
256
-
257
- | 约定 | 原因 |
258
- |---|---|
259
- | `restart-host` 会调用 `host.onHostRestart()`,宿主应把在跑的任务标成 `interrupted` | 真实宿主重启后任务不会复活。宿主若仍报 `running`,客户端刚降级的「已中断 · 可续」会被下一份列表快照覆盖回去,永远转圈(FR-TASK-06) |
260
- | 列表与详情里的 `lastSeq` **由网关补齐**(取环缓冲的 `maxSeq`) | `seq` 属于网关的事件空间,宿主不掌握。宿主返回 0 会让客户端把每份快照判成「比事件旧」而拒用,任务永远停在占位行 |
261
-
262
- ## 9. 隧道(GW-8)与诊断包(GW-9)
263
-
264
- | 接口 | 说明 |
265
- |---|---|
266
- | `GET /mobile/v1/tunnel` | 状态。`executable: missing` 表示主机未装 cloudflared,客户端应**隐藏**入口 |
267
- | `POST /mobile/v1/tunnel/start` | 启动,幂等。地址漂移时向在线会话广播 `gateway{event:"addr_changed"}` |
268
- | `POST /mobile/v1/tunnel/stop` | 关闭并回收子进程(网关退出时也会收,不留孤儿) |
269
- | `GET /mobile/v1/diag/bundle` | 脱敏诊断包,含可直接粘贴的 `text` 字段 |
270
-
271
- 三条硬约束:
272
-
273
- 1. **不伪装**:未安装 cloudflared → `4021` + 可执行指导,不返回 500,也不给假地址。
274
- 2. **地址漂移必须广播**:Quick Tunnel 重启后域名会变,不推 `addr_changed` 客户端会一直连旧域名。
275
- `lastUrl` 跨 stop/start 保留,正是为了检测这种真实漂移。
276
- 3. **诊断包不外发隐私**:不含设备 token、绝对路径、prompt 正文、产物内容(`test/ops.mjs` 有对应断言)。
277
-
278
- ## 10. 下一步
279
-
280
- 1. **X2 真宿主实跑**:desktop profile 的 `cordis.patch.yml` 打开 `host: mux` 重启,对照 diag 服务可见性。
281
- 2. 真机安装 cloudflared 后(macOS `brew install cloudflared`;Windows 下载 `cloudflared.exe`
282
- 加入 PATH),把 `--tunnel-bin` 指向真实可执行文件复跑 `test/ops.mjs`,确认解析逻辑与真实
283
- 输出格式一致(当前用假脚本验证的是格式契约,不是真实二进制)。
284
- 3. iOS 界面层持续完善(连接指引页 / 附件契约升级 / 模型选择宿主映射)。
1
+ # DSH Mobile iOS(dsh-mobile-ios)
2
+
3
+ **在 iPhone 上安全地掌控你电脑里的 DeepSeek Harness。**
4
+
5
+ DSH Mobile iOS 是 DSH Moblie 项目的桌面端插件与 iOS移动伴侣 App 的组合:插件在电脑端提供移动网关(REST + WebSocket),iPhone App 通过局域网或隧道配对连接,实时查看任务进度、追加指令、审批待办、查看产物。桌面端侧栏左下角有「**iOS移动伴侣**」入口,点开即见连接状态与配对码。
6
+
7
+ 面向 iPhone / iPad 采用 **SwiftUI 原生界面**:钥匙串凭证、系统通知、双栏自适应,而非移动网页布局适配。
8
+
9
+ ## 安装
10
+
11
+ 在 DSH 桌面端:**插件 → 添加插件**,输入框填包名 `dsh-mobile-ios`,点安装即可。
12
+ 输入框接受的就是 **npm 包名**(也可带版本,如 `dsh-mobile-ios@0.2.2`)、Git 仓库
13
+ 地址或本地插件目录路径。安装源展开后可选:
14
+
15
+ - **npm 官方源** `registry.npmjs.org`
16
+ - **中国大陆镜像源** `registry.npmmirror.com`
17
+ - **自定义地址**(内网/私有源,凭据放本机 `~/.npmrc`)
18
+
19
+ 首次未显式选源时,DSH 会并发探测官方源与镜像源的 `/–/ping`,自动选最先响应的那个。
20
+ 安装前 DSH 会先 `pluginManager.inspect` 校验包名与 bundle patch(本包带
21
+ `cordis.patch.yml`,校验可过),再按所选源安装。装好后桌面侧栏左下角出现
22
+ 「📱 iOS移动伴侣」入口,点开即可生成配对码,iPhone App 扫码连接。
23
+
24
+ > 本包已发布至 npm:`https://www.npmjs.com/package/dsh-mobile-ios`。
25
+ > 也可粘贴仓库地址 `https://github.com/yelter666/dsh-mobile-ios` 或本地目录路径安装。
26
+
27
+ ### 更新
28
+
29
+ 插件面板右上角的「插件更新」会读 npm registry 的 `latest` 与当前版本比对:
30
+
31
+ - npm 已发布且有新版:提示到插件页**卸载后重新安装**(或输 `dsh-mobile-ios@版本号`
32
+ 更新)——DSH 对非官方按需插件的升级方式是"删除已装包再按相同选择重装";
33
+ - 本地 link 安装的开发态(读不到 registry 版本):提示 `git pull` 后重启 DSH
34
+ 桌面端,插件随源码热重载;
35
+ - 网络不可达:如实报不可达,不假装已是最新。
36
+
37
+ ### Windows 注意
38
+
39
+ 远程通道依赖外部可执行文件 `cloudflared`(**不含在本包内**,插件本体纯 JS 双平台通用)。
40
+ Windows 上请下载 `cloudflared.exe` 加入 PATH,或设 `CLOUDFLARED_BIN` 指向它;
41
+ macOS 用 `brew install cloudflared`。未安装时插件如实隐藏远程入口并给出对应平台指引,
42
+ 不会伪装可用;局域网通道不依赖 cloudflared,任何平台开箱即用。
43
+
44
+ ---
45
+
46
+ ## 能做什么
47
+
48
+ - **任务实时同步**:桌面会话在手机上以卡片流呈现——需要你 / 进行中 / 更早三段分组,状态徽标与进度条实时刷新;
49
+ - **追加指令与排队**:断线也能写,恢复后自动发送(排队语义如实标注,不假装已送达);
50
+ - **待办审批**:任务需要你决策时提醒,手机上直接答复;
51
+ - **产物列表**:任务生成的文件卡片(名称 / 类型 / 体积),事件流实时推送;
52
+ - **桌面端侧栏入口**:左下角「iOS移动伴侣」banner——连接状态点、网关摘要(适配器 / 已配对设备 / 隧道)、一键生成配对码;
53
+ - **多种通道**:局域网直连(secure-by-default,默认只听回环)+ cloudflared Quick Tunnel(自动重拉 + 地址漂移广播);
54
+ - **凭证安全**:设备凭证存 iOS 钥匙串;配对码 2 分钟有效、限速防爆破、可全量撤销;
55
+ - **崩溃隔离(R12)**:网关端口冲突自动顺延(3081–3085),隧道崩溃自动重启,插件 apply 永不向宿主抛异常。
56
+
57
+ ## 快速开始
58
+
59
+ ### 1. 安装插件(DSH Desktop)
60
+
61
+ 普通用户直接用上文「安装」里的包名方式即可。开发态想从源码加载:
62
+
63
+ ```bash
64
+ # 在桌面端 profile 注册本地 bundle(改源码后重启 DSH 生效)
65
+ dsh plugin --profile desktop add /path/to/dsh-mobile-ios
66
+ ```
67
+
68
+ 安装后侧栏左下角出现「**iOS移动伴侣**」入口(窄栏时为手机图标 + 状态点)。状态点含义:**绿色** = 网关健康,**红色** = 网关不可达(插件端口被占时会自动顺延并自恢复)。
69
+
70
+ ### 2. 连接 iPhone(局域网)
71
+
72
+ 1. 电脑与手机连上**同一 Wi-Fi**;
73
+ 2. 点侧栏「iOS移动伴侣」→ 面板内 **生成配对码**(6 位数字,约 2 分钟有效);
74
+ 3. iPhone 打开 DSH App → 连接 → 输入电脑地址(`局域网IP:端口`,端口见面板「网关地址」行)与配对码;
75
+ 4. 首次连接 iOS 会请求「本地网络」权限,请点**允许**。
76
+
77
+ > 开发联调可用 sidecar 独立进程模式:`node entries/sidecar.mjs --host=mock --dev --lan=true`(mock 宿主回放契约数据,端口 3199)。
78
+
79
+ ### 3. 远程访问(外网)
80
+
81
+ 支持 cloudflared Quick Tunnel(插件自动拉起并广播地址漂移)。命名隧道 / 自建反代接入方式与局域网相同——手机端把地址换成隧道域名即可,凭证与配对机制不变。未安装 cloudflared 时客户端如实隐藏入口(不伪装可用)。
82
+
83
+ ## 安全
84
+
85
+ - **secure-by-default**:网关默认只监听 `127.0.0.1`;开放局域网是显式动作(`allowLan: true`);
86
+ - **管理面回环-only**:配对码生成、设备撤销、桌面端摘要只允许主机本机操作(同网段设备刷不了码、炸不了同伴设备);
87
+ - **配对凭证**:设备 Token 存 iOS 钥匙串;WS 走一次性票据(TTL 30s);配对码 5 次/窗限速;
88
+ - **脱敏**:隧道日志与诊断包自动抹除 JWT / `dt_` token / Bearer 头;诊断包不含绝对路径、prompt 正文、产物内容;
89
+ - **最小摘要**:`/mobile/v1/desktop/summary` 只含版本 / 适配器 / 设备数 / 隧道态等展示字段。
90
+
91
+ ## 故障排查
92
+
93
+ | 现象 | 处理 |
94
+ |---|---|
95
+ | 手机提示「无法连接到电脑」 | 确认电脑端 DSH 在运行、手机与电脑同一 Wi-Fi、地址含端口(如 `192.168.x.x:3081`) |
96
+ | 配对码过期 | 点侧栏「iOS移动伴侣」重新生成(同窗口限 5 次,旧码立即失效) |
97
+ | banner 状态点红色 | 网关未起或端口被占——插件自动顺延 3082–3085,重启 DSH 再试 |
98
+ | 手机「需要重新配对」 | 设备被电脑端撤销或凭证过期;手机端「重新配对」不清本地历史 |
99
+ | 隧道地址变了 | Quick Tunnel 重启后域名会变(网关会广播 `addr_changed`),手机端用新地址重配对 |
100
+ | 提示「登录的 Cloudflare 账号不对」 | 本机 `~/.cloudflared/cert.pem` 不是持有该域名那个账号签发的:在终端执行 `cloudflared tunnel login`,浏览器里选**持有该域名**的账号授权,再回面板点「重新检测」。重装插件 / 重启宿主 / 改 NS 都无效 |
101
+ | 固定地址忽然变成另一个前缀 | 本机状态被重置或来自另一台电脑(`tunnel-credentials.mjs` 的 machine 归属校验会拒绝冒充)。点「开启远程」重新分配,或先「重置本机状态」 |
102
+
103
+ ## 兼容性
104
+
105
+ | 组件 | 要求 |
106
+ |---|---|
107
+ | 桌面端 | DeepSeek Harness(desktop profile,Node ≥ 20) |
108
+ | 手机端 | iOS 18+(iPhone / iPad 通用,双栏自适应;Duo 展开态横屏双栏) |
109
+ | 通道 | 局域网 / cloudflared Quick Tunnel / 任意 HTTPS 反代 |
110
+
111
+ ## 工作原理
112
+
113
+ ```
114
+ iPhone App ──REST/WS──> dsh-mobile-ios 网关(宿主进程内,回环或 LAN)
115
+ │
116
+ ├─ mock 宿主 契约夹具回放(联调基线)
117
+ └─ mux 宿主 进程内直取宿主 cordis 服务
118
+ (sessionController 等,真数据进手机)
119
+ 桌面端侧栏 banner ← slots 注入 ← lib/client.js(本包 ./client 导出)
120
+ ```
121
+
122
+ - 插件与宿主之间走**进程内适配器**(cordis 子上下文向上解析 `sessionController` 等服务),宿主 RPC 的 9 个控制器动作全集与方法映射见 `spike0/RUNBOOK.md` §10;
123
+ - 未映射的方法一律返回协议码 `4021`(契约保留位),绝不假装成功;
124
+ - 桌面端 banner 通过 `dsh.client` 声明注入宿主 web app(`slots.inject("sidebar.footer.action")`),面板数据来自回环-only 摘要端点。
125
+
126
+ ## 许可
127
+
128
+ MIT
129
+
130
+ ---
131
+
132
+ # 开发与架构(附录)
133
+
134
+ ## 1. 目录
135
+
136
+ ```
137
+ gateway/ # 包名 dsh-mobile-ios(插件标识)
138
+ ├── src/
139
+ │ ├── protocol.mjs 契约常量 + 错误码表(含 HTTP 状态与"是否该重试")
140
+ │ ├── ring.mjs 每任务 seq + 环缓冲(容量 2000,缺口如实标记)
141
+ │ ├── pairing.mjs 配对码 / 设备凭证 / 限速 / 撤销(损坏自愈 R12)
142
+ │ ├── gateway.mjs 传输无关核心:会话、扇出、握手、幂等 ← ADR-12
143
+ │ ├── rest.mjs /mobile/v1/* 一元接口 + 桌面端 CORS 白名单
144
+ │ ├── ws.mjs RFC6455 子集 + 票据鉴权 + 握手泵
145
+ │ ├── server.mjs 组装 + 只监听回环 + 端口顺延
146
+ │ ├── tunnel.mjs cloudflared Quick Tunnel 生命周期(GW-8,自动重拉+脱敏)
147
+ │ └── adapter/
148
+ │ ├── mock-host.mjs 夹具驱动的宿主(D3)
149
+ │ ├── mux-host.mjs HTTP 探测适配器(X2 考古用)
150
+ │ └── cordis-host.mjs 进程内真宿主适配器(X2 落地,session/* 映射)
151
+ ├── lib/client.js 桌面端 UI 注入模块(X3:banner + 面板)
152
+ ├── entries/
153
+ │ ├── plugin.mjs Cordis 插件入口(apply 永不外抛)
154
+ │ └── sidecar.mjs 独立进程入口
155
+ ├── spike0/
156
+ │ ├── probe.mjs 六项验收探测 → last-report.json
157
+ │ ├── RUNBOOK.md 验证手册(X1/X2 证据链、借鉴机制、方法表)
158
+ │ └── demo-swift/main.swift Apple 原生协议栈演示客户端
159
+ └── test/
160
+ ├── selftest.mjs 端到端自检(鉴权/幂等/握手/续传/隔离/桌面端 CORS)
161
+ ├── resilience.mjs 韧性验收(断链续传/缺口/宿主重启)
162
+ ├── ops.mjs 运维验收(隧道启停/地址漂移/诊断包)
163
+ ├── borrowed.mjs 借鉴机制验收(配对自愈/隧道重拉/脱敏/回环管理面)
164
+ └── mux-table.mjs X2 方法表验收(32 断言)
165
+ ```
166
+
167
+ ## 2. 开发命令
168
+
169
+ ```bash
170
+ # ① 起服务(mock 宿主,附带开箱可用的配对码)
171
+ node entries/sidecar.mjs --host=mock --dev
172
+ # REST http://127.0.0.1:3081/mobile/v1/health
173
+ # WS ws://127.0.0.1:3081/ws/mobile
174
+
175
+ # ② 全量契约测试(11 套件 532 断言)
176
+ npm test
177
+
178
+ # ③ Spike-0 六项验收(本机)
179
+ node spike0/probe.mjs
180
+ # 真机:node spike0/probe.mjs --host=mux --mux-url=http://127.0.0.1:3000
181
+
182
+ # ④ Apple 原生客户端演示(先编译一次)
183
+ swiftc -O spike0/demo-swift/main.swift -o /tmp/dsh-demo
184
+ bash spike0/run-demo.sh # 自动起服务 → 造 3 帧 → 跑客户端 → 收工
185
+ ```
186
+
187
+ ## 3. 契约增补(v0.1 → v0.2,全部是加法)
188
+
189
+ | 增补 | 内容 | 为什么必须加 |
190
+ |---|---|---|
191
+ | `POST /mobile/v1/ws-ticket` | 返回一次性票据(TTL 30s),能力名 `ws.ticket` | 长期凭证不应出现在 WS 升级路径里;ADR-13 |
192
+ | `Authorization: Ticket <t>` | 票据的第二条承载方式 | `URLSession` 不允许自定义 `Sec-WebSocket-Protocol` 时仍能鉴权(已实测) |
193
+ | `hello.cursors` | `{taskId: seq}` 逐任务游标 | 契约 v0.1 的 `hello.lastSeq` 是单值,而 `seq` 是每任务独立的——两者不自洽 |
194
+ | `ready.degraded` | 宿主未就绪时为 `true` + `reason` | 否则网关会连启动都失败,用户只看到「连不上」 |
195
+ | `4021` 的用法 | 能力缺失一律 4021,不返回 5xx | 客户端据此隐藏控件,而不是弹错 |
196
+ | `hello.gen` / `ready.genChanged` | 客户端回带上次的 `gen`;不一致则 `gap=true`、`resumed=0` | 只靠客户端比 `gen` 会晚一步——它会先收到「补不到帧」的 ready,误读成「没有新事件」,静默丢数据 |
197
+ | `gateway` 事件 `host.restarted` | 重启时推 `{gen, prevGen}`,随后 1012 关闭 | 让在线客户端不必等重连才发现代际变了 |
198
+ | `GET /mobile/v1/desktop/summary` | 桌面端 banner 状态摘要(回环-only + CORS 白名单) | X3 侧栏注入需要跨源读健康态与设备数 |
199
+
200
+ **未改动的部分**:帧形状、错误码含义、`seq` 语义、幂等窗口。v0.1 的 31 份夹具仍可直接回放。
201
+
202
+ ## 4. 边界纪律(ADR-12)
203
+
204
+ 改宿主对接只碰 `src/adapter/`,其余目录**不允许出现任何宿主 API 字面量**。
205
+ 判定方法:`grep -rn "remote.mux" src/ entries/` 的结果必须只出现在 `adapter/` 内。
206
+
207
+ `core` 只依赖适配器的 9 个方法:
208
+ `info / listTasks / getTask / listArtifacts / createTask / appendMessage / cancelTask / answerTodo / subscribe`。
209
+ 换插件换 sidecar、换 mock 换真机,都不触碰 `core`。
210
+
211
+ ## 5. 插件接入
212
+
213
+ `entries/plugin.mjs` 导出 `apply(ctx, config)`,对 Cordis 的假设只有两条:
214
+
215
+ 1. `ctx.effect(cb)` 或 `ctx.on('dispose', fn)` 提供卸载钩子(两者都支持,取先存在的);
216
+ 2. `ctx.logger.info` 或可调用 logger 用于日志(都没有则退回 `console`)。
217
+
218
+ 配置项(见 `cordis.patch.yml`):`port` / `host`(`mock|mux`)/ `muxUrl` / `dev` / `allowLan` / `hostSuffixes` / `printPairingCode` / `autoRestart` / `pairingFile`。
219
+ `apply` 返回 `{ok, steps, address, error, ready}`,`probe.mjs` 就是靠 `steps` 判定「挂载」是否成立。
220
+
221
+ > 若宿主的插件签名不是 `apply(ctx, config)`(例如要求 `export const inject`、或插件目录有 manifest 约束),**只改 `entries/plugin.mjs`,不要动 `src/`**。这是 ADR-12 的收益点。
222
+
223
+ ## 6. 验证证据(本机实测)
224
+
225
+ | 项 | 结果 |
226
+ |---|---|
227
+ | `npm test`(11 套件) | **532 通过 / 0 失败**(自检 67 + 运维 44 + 韧性 29 + 借鉴 54 + mux 方法表 53 + 隧道 148 + 帧/产物/附件/增强/会话动作等) |
228
+ | `node spike0/probe.mjs`(mock) | **PASS**,6 项阻塞全过;真宿主与 mux 两项目标为 WARN/SKIP(不假装通过) |
229
+ | `node spike0/probe.mjs --host=mux`(不可达) | **FAIL**,如实报「宿主降级」与 `status=0`,不是假绿 |
230
+ | X1 宿主挂载 | **已验证**(2026-11-16):desktop profile bundle 加载,127.0.0.1:3081 服务,/health + 配对码 + 4001 鉴权 |
231
+ | X2 方法表 | **已落地**:`cordis-host.mjs` 进程内适配器 + 32 断言;真宿主对照 diag 待验 |
232
+ | iOS 端到端(`ios/DSHMobileKit`) | **634 / 634** 全绿(Kit spike)+ 模拟器真跑截图链路 |
233
+
234
+ 韧性验收覆盖的关键行为:异常断链后按游标续传(1..7 零丢失零重复)、缺口时 `gap=true` 且 `resumeFrom` 指向真实下界、宿主重启后旧 gen 握手被要求全量重建(`gap=true/resumed=0`)而新 gen 不误报、重启后 seq 从 1 重开、幂等窗口不随重启失效(`duplicate=true`)。
235
+
236
+ 自检覆盖的关键行为:凭证 4001/4009 分流、配对码单次有效与 5 次限速(4029)、`submissionId` 幂等重放、`/rollback` 返 4021、票据一次性(重放 401)、协议版本 4004 + close 1008、installId 不一致 4009、同任务 seq 连续、`lastSeq` 续传、环缓冲缺口标记、停服端口释放、插件卸载端口释放、插件异常不外抛、桌面端 CORS 白名单与预检。
237
+
238
+ ## 7. 明确的未验证项(不要在汇报里说成已完成)
239
+
240
+ | 项 | 现状 | 谁能解开 |
241
+ |---|---|---|
242
+ | X2 真宿主实跑对照 | cordis-host 适配器落地但未在真宿主里对照 diag 服务可见性 | 桌面端打开 `host: mux` 重启 |
243
+ | R12 插件在宿主进程内的崩溃隔离压测 | 已做 try/catch 与端口顺延,未在真实宿主里压测 | 真机 |
244
+ | R9 本地网络权限弹窗取证 | 真机已通基础链路,弹窗文案与「不允许」分支取证待记录 | iPhone 真机 |
245
+ | Live Activity | 未实现 | S-2/S-3 |
246
+
247
+ ## 8. S-1 故障注入(本机可跑,不需要真机)
248
+
249
+ 三类失败必须能「可编程复现」,否则 iOS 的「断线不误判」根本测不实。仅 `--dev` 模式开放:
250
+
251
+ | 端点 | 作用 | 对应验收 |
252
+ |---|---|---|
253
+ | `POST /__mock/drop` | 不发 close 帧,直接掐 socket | 异常断链 → 重连按游标补帧,零丢失零重复 |
254
+ | `POST /__mock/gap {taskId, keep}` | 裁掉旧帧,抬高环缓冲下界 | 游标早于下界 → `gap=true` 且 `resumeFrom` 指向真实下界 |
255
+ | `POST /__mock/restart-host {reason}` | 换 gen + 清环 + 推 `host.restarted` + 1012 断开 | 旧 gen 握手 → `gap=true / resumed=0`,强制全量重建 |
256
+
257
+ 两条与宿主有关的约定,都是端到端跑出来才补的:
258
+
259
+ | 约定 | 原因 |
260
+ |---|---|
261
+ | `restart-host` 会调用 `host.onHostRestart()`,宿主应把在跑的任务标成 `interrupted` | 真实宿主重启后任务不会复活。宿主若仍报 `running`,客户端刚降级的「已中断 · 可续」会被下一份列表快照覆盖回去,永远转圈(FR-TASK-06) |
262
+ | 列表与详情里的 `lastSeq` **由网关补齐**(取环缓冲的 `maxSeq`) | `seq` 属于网关的事件空间,宿主不掌握。宿主返回 0 会让客户端把每份快照判成「比事件旧」而拒用,任务永远停在占位行 |
263
+
264
+ ## 9. 隧道(GW-8)与诊断包(GW-9)
265
+
266
+ | 接口 | 说明 |
267
+ |---|---|
268
+ | `GET /mobile/v1/tunnel` | 状态。`executable: missing` 表示主机未装 cloudflared,客户端应**隐藏**入口 |
269
+ | `POST /mobile/v1/tunnel/start` | 启动,幂等。地址漂移时向在线会话广播 `gateway{event:"addr_changed"}` |
270
+ | `POST /mobile/v1/tunnel/stop` | 关闭并回收子进程(网关退出时也会收,不留孤儿) |
271
+ | `POST /mobile/v1/tunnel/provision` | 开通固定地址(幂等)。写 DNS 前先做凭据预检,见 9.1 |
272
+ | `POST /mobile/v1/tunnel/recheck-dns` | 强制重探解析 + 强制刷新凭据预检(解开「解析异常」自锁死) |
273
+ | `POST /mobile/v1/tunnel/reset` | 清本机固定地址状态与 ingress(不碰 cert.pem、不删云端隧道),幂等 |
274
+ | `POST /mobile/v1/tunnel/install-cloudflared` | 用户同意后从官方源自举安装 cloudflared 到私有目录 |
275
+ | `GET /mobile/v1/diag/bundle` | 脱敏诊断包,含可直接粘贴的 `text` 字段 |
276
+
277
+ 三条硬约束:
278
+
279
+ 1. **不伪装**:未安装 cloudflared → `4021` + 可执行指导,不返回 500,也不给假地址。
280
+ 2. **地址漂移必须广播**:Quick Tunnel 重启后域名会变,不推 `addr_changed` 客户端会一直连旧域名。
281
+ `lastUrl` 跨 stop/start 保留,正是为了检测这种真实漂移。
282
+ 3. **诊断包不外发隐私**:不含设备 token、绝对路径、prompt 正文、产物内容(`test/ops.mjs` 有对应断言)。
283
+
284
+ ### 9.1 固定地址开通:换台电脑也必须能自证
285
+
286
+ 分发到另一台电脑后「分配不出固定地址」的根因不是网络,而是**本机凭据与状态的归属**。
287
+ 这条链路上有五条不可放松的规则(对应 `test/tunnel-credentials.mjs`):
288
+
289
+ | 规则 | 实现 | 为什么 |
290
+ |---|---|---|
291
+ | 开通前预检 cert 的可用性 | `zone-health.verifyCertAccess` | 跨账号的 cert 能列/建隧道、只有写 DNS 会失败;等 CLI 报错时用户已拿到「隧道正常」的假象 |
292
+ | 预检只在**确定**不可用时拦人 | `blocking` 状态集 | 断网/证书格式不认识 → `unknown`,不能因此判死一台本来能用的机器 |
293
+ | 失败信息保留 `code/reason` | `tunnel-error.explainTunnelFailure` | 旧实现 `split('\n')[0]` 把 `code: 10000, Authentication error` 丢掉,只剩命令回显 |
294
+ | 状态带机器归属 | `tunnel-state.machineIdentity` + `isForeignState` | 整份 `~/.dsh` 被拷到新机器时,旧地址指向旧机器;新机器绝不能冒充 |
295
+ | 没有 cert.pem 也能起隧道 | `LocalStateProvisioner` | 本地 ingress 与 tunnel 凭据都在本机,日常启动不需要 zone 凭据;端口顺延只重写本地配置 |
296
+
297
+ 诊断矩阵(`TunnelStatus.credentials.state`):`ok` / `missing`(没有 cert) / `unreadable`(解析不了,降级)
298
+ / `no-token`(旧版证书,降级) / `forbidden`(403) / `zone-missing`(这账号看不到域名) /
299
+ `account-mismatch`(证书账号 ≠ zone 账号) / `stale-zone`(证书指向已被重建的 zone) /
300
+ `zone-moved`(域名被另一账号接管) / `unknown`(网络不可达)。
301
+
302
+ 唯一正确的修法只有一个:**用持有该域名的账号重跑 `cloudflared tunnel login`**。
303
+ 换账号后 `ensure()` 会自动识别账号变更、重建隧道并**沿用同一个子域**(地址不变、无需重新配对)。
304
+
305
+ ## 10. 下一步
306
+
307
+ 1. **X2 真宿主实跑**:desktop profile 的 `cordis.patch.yml` 打开 `host: mux` 重启,对照 diag 服务可见性。
308
+ 2. 真机安装 cloudflared 后(macOS `brew install cloudflared`;Windows 下载 `cloudflared.exe`
309
+ 加入 PATH),把 `--tunnel-bin` 指向真实可执行文件复跑 `test/ops.mjs`,确认解析逻辑与真实
310
+ 输出格式一致(当前用假脚本验证的是格式契约,不是真实二进制)。
311
+ 3. iOS 界面层持续完善(连接指引页 / 附件契约升级 / 模型选择宿主映射)。