前言¶
在 DeepSeek Harness（DSH）里接多台机器协作时，子网内的 UDP 广播只能覆盖同一局域网。公网没有固定 IP、也不想做端口映射时，需要一种不依赖 NAT 穿透的「会合」方式，同时又不能把明文挂在第三方信道上。
dsh-wan-peers 是社区维护者 Myco-Lee 提交的联网类插件：两台机器只要能访问同一个 ntfy 兼容会合服务（默认公共 https://ntfy.sh，也可自建），即可互相发现节点并收发加密文本。它与同作者的 dsh-lan-peers 是两个独立插件——后者靠 UDP 广播，只在同一子网有效。
本文按安装、配对、日常调用与安全边界说明用法；事实以 GitHub 仓库 README 为准。插件目录页见 SkillHub。社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
一句话：dsh-wan-peers 通过 ntfy 兼容的 pub/sub 做跨网节点发现，正文用 AES-256-GCM 端到端加密，会合服务侧仅见密文。
- 维护者：Myco-Lee
- 分类：联网工具
- 许可证：MIT（package 版本 0.2.0）
- 运行要求：Node.js >= 18
节点身份在首次运行时生成 uuid，写入 ~/.dsh/wan-peers/identity.json。接收侧默认使用长连接订阅（stream 模式），一条连接处理全部消息，避免反复轮询。
核心能力¶
传输与加密¶
- 会合通道：ntfy 兼容服务，默认
https://ntfy.sh，配置项service可改为自建实例。 - 加密：AES-256-GCM；密钥由
room + secret经 scrypt 派生。 - 与局域网插件的区别：不依赖端口映射与公网 IP，只要求双方能访问同一会合服务。
Agent 工具¶
插件向 DSH 注册下列工具（供智能体或 CLI 调用）：
| 工具 | 作用 |
|---|---|
wan_pair |
action=show/import/reset：生成配对码、导入并热切换房间、清除配对 |
wan_room |
房间号、会合服务、本机 id/名字、对端数、同步与退避状态 |
wan_peers |
列出房间内对端（在线/离线） |
wan_send |
向指定对端发送加密文本（peer 支持 id、名字、片段） |
wan_inbox |
拉取收件箱（limit、mark_read） |
wan_ping |
立即广播心跳并拉取一次消息 |
公共 ntfy.sh 额度（免费访客）¶
若长期使用默认公共会合服务，需留意 README 中记载的限制：单条消息 4096 字节、请求速率约 12 次/分钟、每日 250 条消息、单 IP 每日流量 200 MB。超限会返回 429 limit reached；插件指数退避（15s 起，翻倍，上限 300s），wan_room 中可见 backoffUntil。长期在线建议自建 ntfy 或选用付费计划。插件默认 announceMs: 0，不做定时心跳，以免耗尽公共每日额度；若需持续可见，可将 announceMs 设为 300000（5 分钟一次）。
安装与启用¶
README 给出的安装方式为本地链接或打包文件，装完后建议重启一次 DSH。
先用 dsh plugin --profile desktop add 指向本地插件目录：
dsh plugin --profile desktop add "link:D:\99-DP-D\01-代码项目\dsh-wan-peers"
或先打包再安装 tgz：
npm pack .
dsh plugin --profile desktop add "file:D:\99-DP-D\01-代码项目\dsh-wan-peers\dsh-wan-peers-0.2.0.tgz"
检查启动日志，期望出现 hub 与 tools 注册信息：
Get-Content ~\.dsh\wan-peers\boot.log -Tail 20
# 期望: hub started room=... mode=stream / stream connected / tools registered
无图形界面时可用 headless CLI 验证（需 DEEPSEEK_API_KEY）：
dsh --profile headless headless "调用 wan_room 看看配置"
注意：插件在 DSH 进程权限下运行，安装前应阅读源码与 MIT 许可证，确认会合服务地址与 secret 是否符合你的安全策略。
典型用法：配对与收发¶
方式 A：配对码（推荐）¶
在已配置好的一台机器上导出配对码：
wan_pair action=show
将返回的 base64url 配对码发到另一台机器并导入：
wan_pair action=import code=<配对码>
会写入 ~/.dsh/wan-peers/pairing.json 并热切换房间，无需重启。用 wan_peers 查看对端；清除配对用 wan_pair action=reset。
方式 B：手写配置¶
两台机器在各自 profile 的 cordis.patch.yml 中写入相同的 room 与 secret，例如：
- id: dsh-wan-peers
config:
room: my-team-room-815c8824
secret: 至少八个字符的口令
改配置会触发热重载；首次安装仍建议重启一次。任一端调用 wan_ping 广播心跳并刷新列表；对端出现在 wan_peers 后，用 wan_send 发送，wan_inbox 收取。
完整配置项参考¶
- id: dsh-wan-peers
config:
service: https://ntfy.sh
room: dsh-wan-815c8824
secret: ec40e0ee...
name: LMM
mode: stream
announceMs: 0
pollMs: 5000
ttlMs: 60000
maxTextChars: 2000
maxTextBytes: 2600
maxInbox: 500
room 须为 [A-Za-z0-9_-]{4,64}；secret 至少 8 字符，是信任根。密文体积受 maxTextBytes 约束，以免超过 ntfy 单条 4096 字节限制。
适用场景与注意¶
适合：需要在不暴露公网 IP、不做端口映射的前提下，让多台 DSH 节点跨互联网发现彼此并交换短文本（例如远程协作触发、跨机房 Agent 互通）。与同网 dsh-lan-peers 互补：局域网用 UDP，跨网用本插件。
安全边界（来自 README）：
- 端到端加密只保护正文；会合服务仍可见房间名、时间、大小与频率等元数据。
- 房间号应视为不可猜测的频道名；泄露
room+secret等同于房间对任意人开放。 secret宜随机且足够长；公共服务ntfy.sh不宜承载高度敏感内容，严隔离请自建 ntfy。
兼容性：README 记载已在 DSH 0.2.2-rc.1（cordis 4.1.0）与 0.2.1-rc.5（cordis 4.0.5）上验证。
结尾¶
dsh-wan-peers 把跨网发现收敛到「共享 ntfy 会合 + 本地 scrypt/AES 加密」一条路径，并通过 wan_pair 降低双机对齐 room/secret 的成本。部署前权衡公共 ntfy 额度与元数据暴露，按需自建会合服务。
