kokubunshu/DSH-mobile-sync

Harness Sync 三件套整合包

本整合包按 Harness 交接链路拆成三个独立部分：

1. Harness 桌面插件；
2. relay 服务器模块和搭建教程；
3. Android 移动端 APK，以及可复现构建源码。

当前移动端版本为 0.1.0+11，Android 包名为 org.dsh.dsh_mobile，最低
支持 Android 7/API 24。整合包不包含真实配对码、deviceToken、Web UI
Cookie、服务器 IP、真实域名、SSH 私钥、签名密钥、Firebase 服务账号或
运行日志。

目录

| 目录 | 交付内容 |
|---|---|
| 01-harness-plugin/ | 桌面端 dsh-mobile-bridge 插件源码、构建脚本和协议验证脚本 |
| 02-relay-server/ | Node relay 源码、Docker/Caddy 配置、环境变量示例和部署教程 |
| 03-mobile-apk/ | 开发测试 APK、移动端 Flutter 源码和图标/通知兼容文档 |
| docs/ | 三件套共用的部署、协议、安全脱敏和截图资源 |

01 · Harness 桌面插件

进入 01-harness-plugin/dsh-mobile-bridge，先执行 npm install，然后按照
该目录 README 和 docs/DEPLOYMENT.md 安装到 Harness 的 web profile。
插件负责 LAN WebSocket、WSS relay 出站连接、移动端配对、HTTP 隧道、
会话事件和通知意图转发。

02 · relay 服务器

进入 02-relay-server/relay，使用其中的 .env.example、Dockerfile、
docker-compose.yml、Caddyfile 和 DEPLOY-STEP.md。先用 example.com 或
部署方自己的域名替换示例地址，再注入服务器环境变量。FCM 凭据是可选的
后续能力，不能放入这个包。

03 · Android 移动端

开发测试 APK：

~~~text
03-mobile-apk/artifacts/app-release-development-signed.apk
~~~

该 APK 使用 debug key 回退签名，因为整合包没有携带任何生产签名密钥。
它可以用于真实设备兼容性测试，但不能作为应用商店生产更新包。

移动端源码：

~~~text
03-mobile-apk/app-source/
~~~

进入 app-source 后执行 flutter pub get、flutter analyze、flutter test，
再执行 flutter build apk --release。生产构建前必须在本机配置未入库的
android/keystore.properties。

截图示例

以下图片由用户提供，作为 README 的界面和通知展示示例；它们不是本次
未连接设备的实时验证证据。

已连接后的任务列表

Harness Sync 已连接任务列表

开始配对页面

Harness Sync 开始配对页面

HyperOS 通知展示示例

Harness Sync HyperOS 通知展示

验收顺序

1. 服务器先通过 /health 检查；
2. Harness 插件加载并显示移动端配对面板；
3. 移动端在同一局域网完成 LAN 配对；
4. 再使用 WSS relay 完成 WAN 配对；
5. 验收 Android 13+ 通知权限、Android 14/15 前台服务和 OEM 后台策略；
6. 在 HyperOS 通知中心以及可穿戴设备通知中心查看一条新通知；
7. 对 APK 运行 aapt2 资源合同检查；
8. 发布前阅读 docs/SECURITY-REDACTION-REPORT.md。

安全边界

公共整合包只携带示例配置。真实 relay 域名、DNS、Docker secrets、
FCM service-account、签名密钥、配对码和设备数据必须由部署方在本机或
CI secret 中注入。不要把生成的二维码、adb serial、蓝牙地址、dumpsys
输出或用户会话截图追加到 Git。

详细总项目手册

本目录应作为一个整体交接。三个子模块必须使用同一份协议、同一套配对策略和同一套安全边界；只部署其中一个模块不能形成可工作的系统。

端到端数据流

text
LAN:
Android App -- ws://桌面IP:端口/ws --> Harness 桌面插件 --> Harness 本地 API/Web

WAN:
Android App -- wss://relay/connect --> 自有 relay VPS /01-harness-plugin/dsh-mobile-bridge 安装本地插件，安装后重启 Harness，并在设置页确认出现“移动端配对”。

插件 standalone 测试和更完整的安装说明见 01-harness-plugin/README.md。

设置页白名单

部分 Harness 版本会过滤第三方设置命名空间。如果插件已经加载但设置表单不显示，按 docs/DEPLOYMENT.md 的说明，将 mobile-bridge 加入 Harness apiproxy 的 WEB_SETTINGS_NAMESPACES。这是 Harness 安装树中的一次性兼容补丁，升级 Harness 后可能需要重新应用；不要把 Harness 的用户目录、绝对路径或私有补丁内容提交到本仓库。

插件功能

- LAN WebSocket 监听，默认端口为 3088；
- 出站连接自有 WSS relay；
- QR/配对码、待批准设备和撤销设备；
- HTTP tunnel 到 Harness /m 移动界面；
- session、event、mux、config 和 RPC 转发；
- 工作中状态、任务结束、等待回答、等待审批等通知意图；
- 通知开关和安静时段。

插件默认关闭高风险写操作，例如修改敏感 credentials、替换 settings、删除工作区和打开任意本地路径。若部署方确实需要放开，必须在桌面设置中明确启用并重新进行安全审查。

三、Android 移动端

使用现成 APK

APK 位于 03-mobile-apk/artifacts/app-release-development-signed.apk。包名为 org.dsh.dsh_mobile，版本为 0.1.0+11。此 APK 没有使用生产 upload keystore，只适合开发测试和设备兼容性验证。

从源码构建

进入 03-mobile-apk/app-source，依次执行 flutter pub get、flutter analyze、flutter test 和 flutter build apk --release。生成文件位于 build/app/outputs/flutter-apk/app-release.apk。

如果 android/keystore.properties 不存在，构建脚本会明确回退到 debug key。生产构建时复制 android/keystore.properties.example，填写真实 keystore，但不要把真实文件、keystore 或密码提交到 Git。

当前总项目限制

- APK 是开发测试签名，不是应用商店生产签名；
- 本轮没有重新连接物理 Android 设备安装回归；
- HyperOS 桌面、手环通知图标需要部署方用全新通知补充验证；
- FCM killed-process 推送尚未启用；
- Android API 24/25、非小米 OEM 和可穿戴设备矩阵需要交接方补测。

Android 兼容性矩阵

| 能力 | API 24–25 | API 26–32 | API 33+ | API 34/35 和 OEM |
|---|---|---|---|---|
| 启动图标 | 五套密度 PNG 回退 | adaptive icon | adaptive icon | 可能受桌面缓存影响 |
| 通知 | 基础通知 | 通知渠道 | 通知渠道 + 运行时权限 | 另受 OEM 后台/渠道策略影响 |
| 前台服务 | 基础前台服务 | 基础前台服务 | 通知权限影响可见性 | dataSync 类型和启动时机更严格 |
| WebView | loopback 隧道 | loopback 隧道 | loopback 隧道 | 仅允许当前 127.0.0.1 origin |
| FCM 强杀推送 | 未启用 | 未启用 | 未启用 | 未启用 |
Xiaomi/HyperOS、Huawei、OPPO 等 ROM 可能需要用户允许自启动、后台活动、后台联网和不受限制的电池使用。当前实现不能把“系统强杀 App 后仍然收到通知”写成已保证能力。

四、配对和使用流程

LAN

1. 手机和桌面连接同一个可信局域网；
2. 在 Harness 的移动端配对面板打开 LAN 监听；
3. 手机扫描 LAN 二维码，或手动输入 ws://桌面IP:端口/ws 和配对码；
4. 桌面面板先显示待批准设备，再点击允许；
5. 手机通过 loopback WebView 隧道打开 Harness /m；
6. 运行一个短任务，确认状态通知和完成通知。

LAN 使用明文 WebSocket，只适合可信网络。不要把 LAN 二维码或配对 URL 发布到公共网络。

WAN

1. relay /health 已通过 HTTPS 检查；
2. 桌面插件填入 wss://你的域名；
3. 手机扫描公网二维码，或手动输入同一个 wss:// 地址和配对码；
4. 桌面点允许；
5. 关闭手机 Wi-Fi，使用 4G/5G 验证重连；
6. 在任务完成、等待回答和等待审批场景分别验证通知。

配对码为短期凭据。刷新配对码、停止配对或撤销设备后，旧码/旧设备应失效。不要在日志或截图中保留 dshm://pair?...code=...、deviceToken 或 Cookie。

五、图标与通知验收

应用启动图标与 Android 通知 small icon 必须分开处理：

| 用途 | 资源 |
|---|---|
| 启动图标 | @mipmap/deepseek_launcher |
| API 26+ adaptive icon | mipmap-anydpi-v26/deepseek_launcher.xml |
| API 24–25 回退 | mipmap-mdpi/hdpi/xhdpi/xxhdpi/xxxhdpi/deepseek_launcher.png |
| 通知 small icon | @drawable/deepseek_notification_v2 |
| 前台服务 metadata | dsh_notification_icon |

通知 small icon 要使用透明背景的单色前景，不能直接拿 adaptive launcher icon 代替。HyperOS 桌面和可穿戴设备可能各自缓存图标，因此 APK 资源正确不等于所有界面立即刷新。

推荐验收顺序：

1. 用 aapt2 dump resources 确认资源确实进入 APK；
2. 检查 manifest 的 icon、roundIcon 和通知 metadata 没有指向旧资源；
3. 完全停止并重新打开 App；
4. 发送一条全新的通知；
5. 如果手机桌面仍为旧图标，重启 HyperOS 桌面或重启手机；
6. 如果手环仍为旧通知图标，清理/刷新手环端通知缓存，再发送新通知；
7. 分别记录手机桌面、手机通知中心和手环通知中心的结果。

根因报告见 docs/ANDROID-ICON-NOTIFICATION-REPORT.md，兼容性细节见 docs/COMPATIBILITY-SECURITY-PACKAGING.md。

六、构建和验收

插件和 relay

在 01-harness-plugin/dsh-mobile-bridge 执行 npm install 后运行 node test/standalone-test.mjs；在 02-relay-server/relay 执行 npm install 后运行 node test/run-mock.js。

Android 静态检查

在 03-mobile-apk/app-source 执行 flutter pub get、flutter analyze、flutter test 和 flutter build apk --release。然后对生成 APK 执行：

- aapt2 dump badging app-release.apk：确认包名、版本和 SDK；
- aapt2 dump resources app-release.apk：确认 launcher 和 notification 资源；
- aapt2 dump xmltree app-release.apk --file AndroidManifest.xml：确认 manifest 图标和前台服务 metadata；
- apksigner verify --verbose app-release.apk：确认签名可验证。

至少确认：包名为 org.dsh.dsh_mobile、最低 API 为 24、manifest 图标为 deepseek_launcher、五套 PNG 回退存在、deepseek_notification_v2 存在、APK 的签名类型与交付标签一致。

设备矩阵

交付方至少补充以下设备验证：

- Android 7/8：启动图标回退、通知创建、相机扫码；
- Android 12：前台服务、锁屏通知、loopback WebView；
- Android 13：首次通知权限、通知渠道、扫码权限；
- Android 14/15：dataSync 前台服务、切后台、锁屏、应用更新；
- 一台 Xiaomi/HyperOS：通知渠道、图标缓存和后台策略；
- 一台非小米 Android 设备：通知 small icon 对照；
- 一台可穿戴设备：新通知图标和通知正文显示。

没有物理设备时只能报告“未执行”，不能把 aapt2 或 Flutter build 结果写成真机兼容证明。

七、安全脱敏规则

允许提交

- .env.example、keystore.properties.example；
- example.com、example.invalid 等示例地址；
- 不包含用户会话数据的界面截图；
- 协议样例、mock 测试和静态资源合同；
- 构建说明和故障排查模板。

禁止提交

- 真实 relay 域名、服务器 IP、SSH 用户、密码和私钥；
- 配对码、二维码 payload、deviceToken、mobileCookie；
- Firebase google-services.json 和 FCM service account；
- Android keystore、keystore.properties 和签名密码；
- android/local.properties、.dart_tool、build、node_modules；
- adb serial、蓝牙地址、MAC、完整 dumpsys 和运行日志；
- 含工作区路径、任务内容、内部域名或模型上下文的原始截图。

真实配置只通过部署机器、CI secret、Docker secret 或本机 keystore 注入。公共 Git 中只保留模板，不能把模板当成“可以填写后直接提交”的配置文件。

脱敏结果见 docs/SECURITY-REDACTION-REPORT.md，包内文件边界见 docs/PACKAGE-MANIFEST.md。

八、常见故障

| 现象 | 优先检查 |
|---|---|
| 设置页没有移动端配对 | 插件列表、Harness 重启、WEB_SETTINGS_NAMESPACES 白名单 |
| relay 未连接 | HTTPS /health、DNS、80/443 安全组、Caddy 证书、wss:// 前缀 |
| LAN 配对失败 | 同一可信 Wi-Fi、桌面 IP、端口、防火墙、配对码是否过期 |
| 手机页面空白 | 桌面插件在线、loopback 隧道、WebView origin、HTTP tunnel 帧 |
| 通知完全不出现 | Android 13+ 权限、通知渠道、桌面开关、免打扰、OEM 后台策略 |
| 手机上的图标正确但手环旧 | 新通知、手环缓存、手环同步设置；不要只重装 App |
| WAN 强杀后收不到通知 | 当前 FCM 未启用，属于已知能力边界，不是 relay /health 故障 |
| 重启 Harness 后需要重新批准 | 当前桌面配对记录以内存为主，属于已知限制 |

排障日志提交前必须删除真实域名、IP、路径、配对码、token、Cookie、任务正文和设备标识。

九、文档导航

- 总部署顺序：docs/DEPLOYMENT.md
- WebSocket 协议：docs/PROTOCOL-v1.md
- 插件说明：01-harness-plugin/README.md
- relay 说明：02-relay-server/README.md
- relay VPS 操作：02-relay-server/relay/DEPLOY-STEP.md
- APK 说明：03-mobile-apk/README.md
- Flutter 源码说明：03-mobile-apk/app-source/README.md
- Android 图标通知根因：docs/ANDROID-ICON-NOTIFICATION-REPORT.md
- 兼容性和安全：docs/COMPATIBILITY-SECURITY-PACKAGING.md
- 脱敏报告：docs/SECURITY-REDACTION-REPORT.md
- 文件清单：docs/PACKAGE-MANIFEST.md

十、交付前清单

- [ ] relay 的真实域名和 secrets 只存在于部署方私有环境；
- [ ] /health、Docker/Caddy 和 WSS 连接检查通过；
- [ ] 插件加载、设置页、配对面板和 standalone 测试通过；
- [ ] relay mock 测试通过；
- [ ] Flutter analyze、test、release build 通过；
- [ ] aapt2 和 apksigner 合同检查通过；
- [ ] 已明确 APK 是 development-signed 还是生产签名；
- [ ] 已完成 LAN 配对、WAN 配对、断线重连和任务通知；
- [ ] 已检查 Android 13+ 权限、Android 14/15 前台服务和 OEM 后台策略；
- [ ] 已在 HyperOS 手机、非小米手机和可穿戴设备发送新通知；
- [ ] 已阅读脱敏报告，没有新增 .env、keystore、二维码或设备数据；
- [ ] 已重新生成并验证 SHA256SUMS.txt；
- [ ] Git 工作区干净后再交付 ZIP。

十一、交接结论

本包已经把 Harness 插件、relay 服务器和 Android APK 整合为一个 Git 项目，并保留三张用户提供的 README 展示截图。接手者应把它当作一个端到端系统维护：协议、配对、通知资源、Android 权限和 relay 配置任何一项变更，都要同步专项文档与测试。

当前可交付的是“开发测试整合包”，不是带生产密钥的最终商店包。生产交接时必须由维护者补充私有 relay、生产签名、真实设备矩阵和可穿戴设备验收；如果需要强杀后仍收通知，再单独设计和审查 FCM 方案。

英文项目指南

Harness Sync 是一个端到端项目，包含三个协同工作的交付物：

1. 01-harness-plugin/ — 桌面 Harness 桥接；
2. 02-relay-server/ — 由运维方控制的 WebSocket relay 及部署教程；
3. 03-mobile-apk/ — Android APK、Flutter 源码和兼容性文档。
桌面插件和 Android 应用可以通过 ws:// 在受信任的局域网内直接配对，或者双方都可以拨号连接运营商拥有的 wss:// 中继以实现广域网访问。手机通过桌面端隧道传输 Harness /m 界面，接收会话事件，并显示本地 Android 通知。

英文快速开始

1. 在 Caddy 后面部署 02-relay-server/relay，并验证 https://your-domain/health；
2. 在 Harness Web 配置文件中安装 01-harness-plugin/dsh-mobile-bridge 并重启 Harness；
3. 从 03-mobile-apk/artifacts/ 安装开发版 APK，或使用私有生产密钥库重新构建它；
4. 先完成局域网配对，再完成广域网配对；
5. 授予 Android 13+ 通知权限并配置 OEM 后台策略；
6. 在手机和可穿戴设备上验证一条新通知，而不仅仅是旧的缓存通知；
7. 在交接前运行插件、中继、Flutter、APK 资源和签名检查。

英文安全边界

本仓库仅包含模板和经过脱敏处理的示例。切勿提交真实的中继域名、服务器 IP、SSH 密钥、配对码、设备令牌、Web UI cookie、Firebase 文件、Android 密钥库、二维码载荷、adb 序列号、蓝牙地址、用户路径或包含私密内容的任务截图。协议 v1 将中继视为受信任边界，不提供端到端加密。FCM 进程被杀后的投递未启用。

英文文档地图

- 部署：docs/DEPLOYMENT.md
- 协议：docs/PROTOCOL-v1.md
- 兼容性与打包：docs/COMPATIBILITY-SECURITY-PACKAGING.md
- 图标与通知根本原因：docs/ANDROID-ICON-NOTIFICATION-REPORT.md
- 脱敏报告：docs/SECURITY-REDACTION-REPORT.md
- 发布下载：release/README.md

随附的 APK 版本为 0.1.0+11，包名为 org.dsh.dsh_mobile，最低 API 为 24。它使用开发签名，不是应用商店的生产更新。