局域网聊天助手 jasonchan2026/dsh-lan-chat

局域网聊天助手（dsh-lan-chat）

完全离线的内网即时通讯插件。给 DeepSeek Harness 左侧新增一个 「局域网聊天助手」 入口，支持 单聊、群聊、文件传输，以及 按网段扫描发现同事。

不连任何外部服务：没有云端账号、没有中转服务器、没有 CDN 依赖。所有流量只在你自己的局域网里。

功能

| 能力 | 说明 |
| 单聊 | 与任意一位同事一对一聊天，支持未读数、已读位置、在线状态 |
| 群聊 | 自建群、拉人入群、改名、退群、删除；群资料自动同步给成员 |
| 文件传输 | 拖拽或点选发送，单文件上限可配（默认 512MB）；接收方按需下载（不占用对方磁盘两次） |
| 网段扫描 | 填 192.168.1.0/24 即可并发探测，进度实时显示 |
| 自动发现 | 每 30 秒 UDP 广播一次，同网段的人无需手动添加就能互相看到 |
| 手动探测 | 知道对方 IP 时直接探测单个地址 |
| 访问码 | 可选。设置后只有知道访问码的人能与你通信 |
| 联系人备注 | 给同事起本地备注名（如「隔壁老王」），只改自己这边的显示，不通知对方 |
| 删除消息 | 单条删除或整个会话清空；只删本机记录，对方那份不受影响 |
| 删除群聊 | 群主删=解散（通知全员一起删），成员删=只删本机这份；都会清掉该群本地消息 |
| 文件上限 | 设置里可改单文件上限（64MB ~ 64GB），发送框提示实时跟随 |
| 离线可用 | 对端不在线时消息照常记录在本地，联网后手动重发即可 |

界面

左侧会话列表 + 右侧聊天区，三个页签：

- 会话 — 所有单聊和群聊，带最后一条预览、时间、未读红点
- 联系人 — 已添加的同事，显示在线状态与 IP
- 发现 — 扫描网段 / 手动探测 / 一键添加

安装

从 1.x 升级到 2.x 请看 CHANGELOG。 2.0.0 是破坏性安全版本，协议不兼容，局域网内所有机器必须一起升级，否则互相连不上。

方式一：从 GitHub 装（推荐）

在 DSH Desktop 的插件市场里搜索 dsh-lan-chat，或者直接用命令：

dsh plugin --profile desktop add github:jasonchan2026/dsh-lan-chat

装完重启 DSH Desktop，左侧就会出现「局域网聊天助手」。

方式二：从本地目录装

已经 clone 到本地的话：

dsh plugin --profile desktop add link:$PWD

dsh plugin add 会自动做两件事：把包写进 profile 的 dependencies，并把包名追加进 dsh.profile.bundles（因为本包声明了 dsh.bundle）。

手动接线（了解原理用）

如果不用 dsh plugin add，手工接也只要改 profile 的 package.json 两处：

{
"dependencies": {
"dsh-lan-chat": "link:/path/to/dsh-lan-chat" // 或 github:<用户名>/dsh-lan-chat },
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-lan-chat" // ← 追加这一项 ] } } }

插件的 Loader 条目由包内自带的 cordis.patch.yml 提供，由 bundle 机制自动叠加：

- insert:
- id: lan-chat
name: dsh-lan-chat

⚠️ 不要再往 profile 自己的 cordis.patch.yml 里写同样一条 —— DSH 会先叠所有 bundle 的 patch，最后才叠 profile 的 patch，重复写会注册两次同一个条目。

安装要求

- DSH Desktop 0.2.1-rc.3 或更高
- Node.js 22+（DSH 自带，通常不用管）
- 零运行时依赖 —— 全部用 Node 内置模块实现，包括手写的 WebSocket，所以在完全离线的机器上也能装（只要能把包拷过去）

配置

插件在 cordis.patch.yml 里支持三个可选参数：

- insert:
- id: lan-chat
name: dsh-lan-chat
config:
port: 45871 # 局域网监听端口 nickname: 我的电脑 # 初始昵称 dataDir: /path/to/data # 数据目录

| 参数 | 默认值 | 说明 |
| port | 45871 | 局域网 TCP 端口。发现用的 UDP 端口是 port + 1 |
| nickname | 主机名 | 首次启动写入，之后以界面设置为准 |
| dataDir | $DSH_HOME/plugin-data/dsh-lan-chat | 消息、文件、身份、设置的存放位置 |

大部分设置直接在界面的「设置」里改，不需要编辑配置文件，包括：

| 界面设置项 | 说明 |
| 昵称 | 自己对外显示的名字，改完会自动推给在线联系人 |
| 访问码 | 留空表示不设；已设置时会显示「已设置」并提供「清除」勾选框 |
| 单文件上限 | 64MB ~ 64GB，默认 512MB；发送框右下角提示会跟着变 |
| 联系人备注 | 在「联系人」里点标签图标设置，只影响本机显示 |

文件总量配额（默认 2 GiB）通过 /lan-chat/settings 的 maxTotalBytes 调整，暂未做进界面。

工作原理

一台机器 = 一个节点

插件在宿主进程里起一个独立的 HTTP + WebSocket 服务，监听 0.0.0.0:<port>。
之所以不复用 DSH 自己的 web server，是因为它只监听回环地址，局域网里的其他机器根本连不上。

浏览器界面 ──同源 HTTP──> DSH web server ──> 插件宿主半侧 ──LAN──> 其他机器 │ SSE 实时推送

- 浏览器 ↔ 宿主：走 DSH 自带的 web server（同源，无需 CORS，复用 DSH 的登录态）
- 宿主 ↔ 宿主：走插件自己的监听端口，机器之间直连

协议

HTTP 接口（/lan-chat/v1/...）：

| 方法 | 路径 | 用途 |
| GET | /info | 读取节点身份（扫描用，不鉴权） |
| POST | /hello | 握手，校验访问码 |
| POST | /send | 投递一条消息 |
| POST | /sync | 拉取增量消息 |
| POST | /group | 同步群资料 |
| POST | /group-removed | 群主解散群时通知成员（2.2.0 新增） |
| POST | /profile | 同步昵称 |
| POST | /upload | 上传文件实体 |
| GET | /file/:id | 下载文件实体 |
| GET | /ws | WebSocket 实时通道 |

发现

两条腿：

1. 被动广播 — 每 30 秒往 255.255.255.255 和各网段广播地址发一个 UDP 包（端口 port+1），收到的人回一条带自己身份的应答。
2. 主动扫描 — 把 CIDR 展开成地址列表，48 并发地做 TCP 连接 + GET /info，700ms 超时。

扫描上限 1024 个地址（/22 及更宽），避免误填 /8 把界面拖死。

消息流

发一条消息时：

1. 先落到本地 messages/<conv>.jsonl（先写本地，保证不丢）
2. 通过已有的 WebSocket 推给对端
3. WebSocket 没连上就退回 HTTP POST /send
4. 无论成功失败，本地记录都在

收一条消息时：normalizeMessage 校验 → 幂等检查（同 id 跳过）→ 落盘 → 广播给界面和所有已连的 peer。

存储

$DSH_HOME/plugin-data/dsh-lan-chat/
├── identity.json 本机身份（peerId + secret，首次启动生成） ├── state.json 设置、联系人、群、已读位置、文件索引 ├── messages/ │ ├── dm%3AlcA%7ClcB.jsonl 单聊（每个会话一个追加日志） │ └── grp%3Ag1.jsonl 群聊 └── files/ └── f<id> 文件实体

消息用 JSONL 追加写，不重写整个文件；读取时只回看尾部 8MB，避免长年累积后打开变慢。

常见问题

对方看不到我 / 我扫不到对方

1. 确认双方都启用了插件，且界面上「在线 · 端口 xxxxx」不是「未监听」
2. 确认在同一网段（192.168.1.x 和 192.168.2.x 通常不通）
3. 检查系统防火墙是否放行了该端口（macOS：系统设置 → 网络 → 防火墙）
4. 公司网络如果开了「AP 隔离 / 客户端隔离」，同一 WiFi 下的设备互相不可见 —— 这是交换机/AP 的限制，插件绕不过去

端口被占用

插件启动失败时界面顶部会显示红色提示，不影响其他功能。提示里会直接写出 占用者的 PID 和已运行时长：

- 如果占用者是上一次 DSH 退出后残留的宿主进程（父进程已被 launchd 收养），界面会出现「强制释放」按钮，点一下就会结束它并重新监听，不用重启 DSH。
宿主只对确认过身份的残留进程动手，判据是「命令行是 DSH 宿主 + 父进程为 1 + 不是当前进程或其祖先」，三条缺一不可。
- 如果是别的程序占着，按钮不会出现（强行杀别人的进程不安全），改 cordis.patch.yml 里的 port，或者关掉那个程序。

/listen/retry 只重试绑定、从不杀进程；/listen/release 才会结束残留宿主。

消息发不出去

看会话标题下面显示的是「在线」还是「离线」。离线时消息仍会记录在本地，等对方上线后可以重发。
文件也一样：接收方点下载时如果本地没有实体，会回源到发送方拉取。

能不能跨网段 / 跨 VLAN

不能自动发现，但如果路由可达，可以在「发现」页手动填对方 IP 探测，然后添加。

自测

六套离线测试，不需要网络，也不需要 DSH 在跑：

node scripts/selftest.mjs # 协议层：WS 帧、文件、群、扫描、鉴权、昵称同步、持久化（34 项）
node scripts/hosttest.mjs # 宿主路由：全部 /lan-chat/* 接口 + 桌面端来源校验 + 端口重试与强制释放 + 删群（111 项）
node scripts/clienttest.mjs # 界面：真 React + jsdom 挂载并驱动交互（67 项）
node scripts/e2etest.mjs # 两台机器互联：发现→添加→单聊→群聊→文件→解散群（40 项）
node scripts/sectest.mjs # 安全回归：22 个渗透测试发现逐条验证 + 解散群越权（52 项）
node scripts/themetest.mjs # 主题配色：DSH token 存在性 + 明暗两套 WCAG 对比度（65 项）

合计 302 项（不含需要额外开发依赖的 clienttest.mjs）。

themetest.mjs 是补上「深色主题下配色失效」这个缺陷后加的。它做两件事：把插件引用的每个 --dsw-alias- 变量拿去和 DSH 主题比对，名字写错立刻失败
（var() 写错不会报错，只会静默用兜底值，这类 bug 功能测试全绿也发现不了）；
用 DSH 真实的明 / 暗两套取值算 WCAG 对比度，挡住「能解析但看不清」。

clienttest.mjs 需要开发依赖 react / react-dom / jsdom（不进插件包）：

pnpm add -D react react-dom jsdom

也可以用 REACT_ROOT=/path/to/node_modules 指向已经装好它们的目录。

安全说明

2026-10-25 做过一次完整渗透测试，以下描述是修复后的实际行为（报告见 docs/，不入库）。

网络层（局域网端口，默认 45871）

- 只有 /lan-chat/v1/info 和 /hello 匿名可读，其余 8 个接口（/send /sync /group /group-removed /profile /upload /file /ws）全部要求 token，否则 401
- token 由 /hello 签发：<随机串>.<HMAC-SHA256>，有效期 24 小时，最多同时保留 512 个
- 每个节点在 identity.json 里有一份 secret 作为身份密钥。首次握手时对端会记住它（TOFU），之后同一个 peerId 必须拿同一把密钥，否则 403 —— 防止别人顶替已知节点
- /send 会用 token 持有者的 peerId 覆盖 from 字段，不能伪造发送者
- 消息不再广播给所有连接，只投递给会话参与者
- 只向 RFC1918 私网地址发起连接；公网、127.0.0.0/8、169.254.0.0/16（云元数据服务）一律拒绝，避免被当作 SSRF 跳板
- 入站同理：来自公网或链路本地地址的请求直接 403，不进入任何处理逻辑
- /info 不再返回主机名；/diag 只返回目录名，不回绝对路径

浏览器层（/lan-chat/，走 DSH web）

- 全部 22 条路由都过同源检查：Host 必须是回环地址，Sec-Fetch-Site 必须是 same-origin/none/空，带 Origin 时必须与 Host 一致
- 写操作（POST/PUT/DELETE）必须带 Origin，堵掉无 Origin 的表单型 CSRF
- /state 和 /settings 不再回显明文访问码，只给 hasAccessCode: true/false
- /listen/release 会结束进程，因此只对通过三条判据（DSH 宿主命令行、父进程为 1、非当前进程/祖先）的残留宿主生效；其余情况返回 409 拒绝，绝不误杀别的程序

访问码

- 可选。设置后，对方必须在 /hello 里带上相同的码才能拿到 token
- 访问码只是「入场券」，真正防越权的是 token；访问码本身不会被下发到前端

其它

- 不加密传输：局域网内可被同网段的人抓包。不要用它传敏感凭据
- 默认监听 0.0.0.0（局域网内可用），但入站会按来源地址过滤：只有内网来源能访问。
若本机有公网地址，启动时会打 warn 日志；只想本机用可以设 bind: 'local'，只绑 127.0.0.1
- 文件上传有总量配额（默认 2 GiB，可在设置里改）与 7 天回收，WebSocket 有单帧 8 MiB / 单连接 256 条 / 60 帧每秒上限

目录结构

dsh-lan-chat/
├── package.json
├── cordis.patch.yml
├── LICENSE
├── lib/
│ ├── index.js 宿主半侧：DSH 路由 + 生命周期 │ ├── node.js 网络层：HTTP API + UDP 发现 + 扫描 │ ├── ws.js 手写 RFC6455 WebSocket（不依赖第三方包） │ ├── store.js 持久化：身份、消息日志、文件、群 │ └── client.js 界面半侧：侧边栏入口 + 聊天面板 └── scripts/ ├── selftest.mjs ├── hosttest.mjs ├── clienttest.mjs ├── e2etest.mjs ├── sectest.mjs 安全回归（渗透测试用例转成的可提交测试） ├── themetest.mjs 主题配色（token 存在性 + 明暗对比度） └── wire-profile.mjs

许可

MIT