局域网通讯 Movingelated/DSH-LanChat

LanChat —— 局域网消息 / 文件互传（含 DSH 原生插件）

同一个局域网内的几台 Windows 电脑之间，互发消息和文件。 不用服务器、不用注册、不用联网。
配一个 DSH（DeepSeek Harness）插件后，AI 之间也能互相通讯：AI 能收发消息、传文件，收到消息还会自动唤醒本机会话里的 AI 来处理。

- 只用 Windows 自带端口：TCP 80（网页与传输）、UDP 1900（自动发现，与系统 SSDP 共存）
- 单个 exe，零依赖（.NET Framework 4.x 自带），拷到哪都能跑
- 设备之间自动发现，不需要手填 IP
- 消息与文件在链路上加密传输（详见「注意事项」里的强度说明）

装它（第一次来的人看这里）

第 1 步：拿到两样东西

从本仓库下载或克隆，你会看到：

LanChat.exe ← 应用本体（双击即用） package.json ← DSH 插件清单 index.js ← DSH 插件（宿主侧：工具 + 联网 + 唤醒） client.js ← DSH 插件（界面侧：设置面板） cordis.patch.yml ← 插件声明

LanChat.exe 与插件文件放在同一个目录是刻意的：插件会自动在自己旁边找 exe，装上就能用。

第 2 步：先单独跑一次 LanChat（推荐）

双击 LanChat.exe。右下角托盘会出现图标，并弹出气泡提示。

第一次运行，Windows 防火墙会问「是否允许访问网络」——必须勾选"专用网络"并允许，否则别的机器发现不了你。

第 3 步：装 DSH 插件

在 DSH 里（或让 DSH 的 AI 执行）：

plugin_manager install_bundle target="<你放这些文件的目录>"

例如把文件放在 D:\DSH-LanChat，就填 D:\DSH-LanChat。

装完重启一次 DSH（客户端半身与插件代码需要从磁盘重新加载）。

第 4 步：确认装好了

重启后：

1. 设置 → 局域网通讯：能看到开关与参数（9 项）
2. 让 AI 调用 lanchat_status：能看到本机名称与在线的其它机器
3. 托盘里 LanChat 图标还在（插件不会把它藏起来）

到此结束。 之后每次开 DSH，若 LanChat 没在跑，插件会帮你启动；已经在跑就直接接入。

0. 给 AI 的 60 秒速览

这一节写给 DSH 里的 AI。读完即可开始通讯。

你有 5 个工具：

| 工具 | 一句话 |
| lanchat_status | 我是谁 + 局域网里有谁（通讯前先调它） |
| lanchat_recv | 收消息。peer 省略 = 群聊；waitSeconds 可长轮询等回复 |
| lanchat_send | 发消息/文件。默认攒批，同一目标连发会合并成一批 |
| lanchat_flush | 一轮内容发完后调用它，立即把这一批发出去 |
| lanchat_identity | 看/改本机名称与头像颜色 |

三条铁律：

1. 要发文字 + 文件、或连续说几句时：连续调 lanchat_send，最后调一次 lanchat_flush。
这样对面收到的是一条消息、一个批次号，能一次看全 —— 避免"文字先到把对面 AI 唤醒、文件后到被忽略"。
2. mine: true 的消息是自己发的，不要回复自己。
3. recv 返回的 next 就是游标，下次调用把它当 since，天然去重。

最短对话示例：

lanchat_status() # 看谁在线
lanchat_send(text="帮我查一下磁盘剩余空间", peer="对方的机器名")
lanchat_flush() # 立刻送出
lanchat_recv(peer="对方的机器名", since=0, waitSeconds=20) # 等回复

收到消息时，系统会自动往你会话里投一条「【LanChat 收到消息…】」的提示 ——看到就调 lanchat_recv 取全文（文件路径在 messages[].files[].path，可直接用 shell 读写）。

想用 HTTP 直接调（不装插件也能用，任何语言/工具都行）：见 DSH-API.md。

1. 人怎么用

1.1 启动与托盘

| 方式 | 效果 |
| 双击 LanChat.exe | 托盘图标 + 自动打开浏览器界面 |
| LanChat.exe --no-browser | 托盘图标，不自动开浏览器 |
| LanChat.exe --port=8080 | 换端口（默认 80） |
| LanChat.exe --name=我的电脑 | 指定在局域网里显示的名字 |
| LanChat.exe --data=D:\LanChatData | 指定数据目录 |

托盘右键菜单：

| 菜单项 | 作用 |
| 打开界面 | 打开 WebUI |
| 打开接收文件夹 | 直接进文件目录 |
| 我的地址: http://<你的局域网IP>:80/ | 点一下复制，方便发给别人 |
| 其它网卡地址 ▸ | 多网卡时列出其它可用地址 |
| 退出 | 完全退出 LanChat |

双击托盘图标 = 打开 WebUI。

LanChat 完全独立：关掉 DSH 它照样运行，直到你从托盘点「退出」。

1.2 群聊与私聊

- 顶部一排是本机发现的其它机器（各自带头像字母与颜色）
- 双击任意头像或机器名 → 在左侧会话列表里新开一个私聊
- 私聊只有你们两台能看见，第三台机器拿不到（不是"不显示"，是接口层面拒绝）
- 私聊会话若一条消息都没发就切走，会自动清除，不留空壳

1.3 发文件 / 收文件

- 拖拽文件到输入框，或点「文件」按钮
- 收到的文件自动落在 数据目录\received\<发送方名字>\，按机器分文件夹
- 单文件几十 MB 没问题（走原始字节流，不做 base64 膨胀）

1.4 名片（头像与颜色）

每台机器在会话里都有一张名片：名称 + 头像字母 + 头像颜色。

- 头像字母取名称首字符；撞车会自动顺延到下一个可用字符
- 颜色从内置 256 色里随机分配，首次使用随机生成并存盘；撞色会自动换一个
- 名称若与别人重复，会自动改成可用名称，并把新名片广播给全网
- 每条消息的气泡底色 = 发送方头像色，文字颜色按背景亮度自动选深/浅，任何底色都看得清

想改自己的名片：点界面右上角 设置。

1.5 DSH 插件设置面板（设置 → 局域网通讯）

| 设置项 | 默认 | 说明 |
| 启用插件 | 开 | 总开关；关掉后不收发、也不唤醒 AI |
| LanChat.exe 路径 | 空 | 留空自动查找（插件同目录 → 工作目录 → 安装目录 → 局域网邻居） |
| LanChat 端口 | 80 | 改了自动重连 |
| 数据目录 | 空 | 留空用 LanChat 默认 |
| 自动拉起 LanChat | 开 | 没在跑就帮你启动（脱离式，与手动双击一样有托盘）；已在跑则直接接入 |
| 允许从局域网获取程序 | 开 | 本机没有 exe 时，从局域网里其它机器拉一份 |
| 合并窗口（毫秒） | 30000 | 同一批内容攒这么久没新增就自动发出 |
| 唤醒防抖（毫秒） | 4000 | 收到消息后安静这么久才唤醒本机 AI |
| AI 忙时不打断 | 开 | AI 正在跑就只入队，等它这一轮结束 |

改完立即生效，不用重启。 值保存在你的 DSH profile 配置里。

2. AI 怎么用（DSH 插件）

2.1 五个工具

lanchat_status({ includeFiles? })
返回本机名片、在线机器列表；（可选）最近的文件清单。

lanchat_recv({ peer?, since?, waitSeconds? })
peer 省略 = 群聊，填机器名/节点号 = 与它的私聊。since 用上次返回的 next。
waitSeconds>0 时若无新消息会挂起等待（最长 25 秒）——等对方回复就用它，比反复空轮询省资源。

{ "ok": true, "key": "public", "next": 7, "count": 1,
"messages": [ { "seq": 7, "from": "对方的机器名", "mine": false, "text": "在么" } ] }

文件消息会多一个 files 数组，每个元素带 name / size / path（磁盘绝对路径，直接用）。

lanchat_send({ text?, file?, peer?, mode?, kind? })
text 与 file 至少给一个，可反复调用累加。mode：stage（默认，攒批）/ flush（攒批并立即发）/ now（不合并、立刻单发，只适合一句话）。kind: "image" 表示图片，图片不参与合并（免得对方干等）。

lanchat_flush({ peer? })
把攒着的一批发出去。一轮内容发完请调用一次。

lanchat_identity({ name?, color? })
不带参数 = 查看；带了 = 修改（会自动同步给全网，重名/撞色自动避让）。

2.2 为什么默认要"合并发送"

这是本插件存在的核心理由。

真实的坑：AI 先发一条文字、再发一个文件。文字一到，对面的 AI 立刻被唤醒开始处理；随后到达的文件就成了"另一件事"，被延迟处理甚至直接忽略 —— 可它们明明是同一批。

做法：在发送侧暂存。同一目标的内容攒够 30 秒没有新增，才作为一整批发出去；对面收到的是一条消息 + 一个批次号 + files 数组，一次就能看全。

lanchat_send(text="这是需求说明") → 攒入本批（1 件）
lanchat_send(file="D:/需求.docx") → 攒入本批（2 件）
lanchat_send(file="D:/数据.csv") → 攒入本批（3 件）
lanchat_flush() → 3 件作为一整批立刻发出 ✅

即使忘了 flush 也不会丢：30 秒空闲后自动发出，依然是一批。

2.3 收到消息会自动唤醒本机 AI

插件在后台收消息，然后：

1. 等 4 秒内没有新消息；
2. 且本会话 AI 处于空闲；
3. 才把合并后的一条用户消息投进你的会话。

AI 正在处理别的事务 → 只入队不打断，等它这一轮结束再处理。
配合上面的合并发送，同一批消息既不会被拆开唤醒，也不会被漏看。

2.4 完整对话示例

A 机（发任务）：

lanchat_status()
→ peers: [{ name: "B机", online: true }]
lanchat_send(text="把 D:/报告.docx 和 D:/数据.csv 一起看，给我一份摘要", peer="B机")
lanchat_send(file="D:/报告.docx")
lanchat_send(file="D:/数据.csv")
lanchat_flush() # 三件作为一整批发给 B 机
lanchat_recv(peer="B机", since=0, waitSeconds=20) # 等 B 机回复

B 机（被唤醒后）：

收到提示：【LanChat 收到 1 条消息（同一批）｜来自 A机】
lanchat_recv(peer="A机", since=0)
→ messages[0].files = [{ name:"报告.docx", path:"...\received\A机\报告.docx" }, …] 用 shell 读取 path 指向的文件，处理完回信
lanchat_send(text="摘要：……", peer="A机")
lanchat_flush()

3. 不用插件也能用（HTTP 接口）

LanChat 暴露了一套极简 JSON 接口，任何语言、任何工具都能直接调：

GET /dsh/whoami 我是谁 GET /dsh/peers 局域网里有谁 GET /dsh/recv?peer=&since=&timeout= 收消息（timeout = 长轮询秒数） GET /dsh/send?text=&to= 发消息 POST /dsh/stage 合并发送（推荐） GET /dsh/stage/flush 立即送出一批 GET /dsh/files 文件清单（含磁盘路径） GET /dsh/doc 完整接口文档（Markdown）

完整字段说明、示例与注意事项见 DSH-API.md（也可以直接 GET /dsh/doc 取回原文）。

4. 注意事项（务必看）

4.1 网络范围

- 设计目标是同一个局域网。跨网段、跨公网、异地组网不保证可用（自动发现依赖 UDP 广播/组播）。
- 手动填 IP 可以跨网段直连（lanchat_send 的 peer 支持 ip:端口），但需要路由可达。

4.2 端口与防火墙

| 端口 | 协议 | 用途 |
| 80 | TCP | 网页界面、消息、文件传输 |
| 1900 | UDP | 自动发现（与 Windows 自带的 SSDP 共用，靠 SO_REUSEADDR 共存） |

- 端口 80 被占用时（例如 IIS、其它 Web 服务），用 --port= 换端口；换端口后同一局域网内的机器仍能互相发现，但要用新端口访问界面。
- 防火墙必须放行，否则别人发现不了你。

4.3 加密强度（请如实理解）

- 消息与文件在传输链路上是加密的：嗅探抓包看不到明文。
- 但密钥是编译进 exe 的固定密钥 —— 属于「防明文嗅探」级别，不是端到端加密，也不能防中间人。
- 反编译 exe 可以取出密钥。不要在不可信网络里传敏感数据（公司内网、家庭局域网这类可信环境才是设计场景）。

4.4 LanChat 与 DSH 的关系

- LanChat 是独立软件，不依赖 DSH。DSH 插件只是「接口适配层」。
- 关掉 DSH，LanChat 继续运行（托盘常驻），直到你手动退出。
- 插件只会在 LanChat 没在跑的时候帮你启动；已经在跑就直接接入，不会有两个托盘图标。

4.5 数据位置与备份

- 默认在 exe 同目录下的 LanChatData\：history.jsonl（聊天历史）、identity.json（名片）、 received\（收到的文件）。
- 想换位置用 --data=，或插件的「数据目录」设置项。
- 备份 = 直接复制这个目录。

4.6 隐私

- 私聊只有参与的两台机器能拿到内容，第三台机器在接口层面被拒绝。
- 别人之间的私聊，即使因为网络广播被你收到，也只落库、不进任何界面与接口。

5. 排错

| 现象 | 处理 |
| 别人看不到我 | 防火墙没放行；或不在同一网段（UDP 1900 被路由器拦了） |
| 界面打不开 | 端口 80 被别的程序占了 → --port=8080 |
| AI 的工具里没有 lanchat_ | 插件没装或没启用；装完重启 DSH |
| 设置里没有「局域网通讯」 | 客户端半身需重启 DSH 后才加载；确认 client.js 与 package.json 在同一目录 |
| 收到消息但 AI 没被唤醒 | 本会话需先调用过任意 lanchat_ 工具（用于绑定会话）；看 DSH 日志里的 [lanchat] 前缀 |
| 消息攒着不发 | 调 lanchat_flush；或等「合并窗口」自动发出 |
| 对面收到 LCE1:… 乱码 | 对面是旧版本 LanChat（不支持加密），双方都升级即可 |
| 插件找不到 LanChat.exe | 把 LanChat.exe 与插件放同目录，或在设置里填「LanChat.exe 路径」 |
| 托盘图标没了 | 确认不是用 --nogui 启动的（那会隐藏托盘，仅用于无界面场景） |

6. 卸载

1. DSH 里：plugin_manager 停用或移除 @local/dsh-plugin-lanchat
2. 托盘右键「退出」关掉 LanChat
3. 删掉程序目录（想留聊天记录就保留 LanChatData\）

7. 版本与兼容性

| 组件 | 版本 |
| LanChat | 1.6.1 |
| DSH 插件 | 1.0.x（宿主 index.js + 客户端 client.js） |

DSH 版本兼容性（已按两版类型声明逐条核对）：

| 插件依赖的契约 | 0.1.7-rc.2 | 0.2.0-rc.2 |
| tools.register(ToolDefinition) | 一致 | 一致 |
| sessionController.prompt({requestId, sessionId, mode, content}) | 一致 | 一致 |
| subprocess / SubprocessSpawnSpec | 存在 | 存在 |
| agent/status 事件（idle ⇄ running） | 没有 | 有 |

- 0.2.0-rc.2：全部功能可用（含「AI 忙就不打断」的精确判忙）。
- 0.1.7-rc.2：也能用。唯一差别是判忙 —— 收不到 agent/status 时插件不再自己判忙，直接交给 sessionController.prompt(mode:'queue')（它本身就是「正在跑就排队、空闲才起跑」的语义），所以队列行为仍然正确，只是唤醒时机不如有事件时精确。启动 5 秒后日志会提示这一点。
- 插件只 import Node 内置模块，不会因为 DSH 内部包升级而崩。

升级 DSH 前后建议各跑一次 lanchat_status；若工具消失或唤醒失效，就是上表发生了变化。

1.6 一台电脑只有一个身份（v1.5.3+）

有虚拟机（VMware/VirtualBox）、VPN 或多张网卡的机器，以前会被 LanChat 识别成好几个身份：每张网卡一个地址、各聊各的。现在改为：

- 只认「有默认网关」的那张网卡（= 由路由器派发的那个网段）作为本机身份；没有网关的虚拟网卡、169.254 自动地址、VPN 隧道统统不参与
- 广播里带上自己的主 IP，别人看到副网卡发来的广播会直接忽略
- 邻居列表里同一台机器只会有一条，自己也不会出现在自己的邻居里

换网后会每 20 秒重新判定一次，插拔网线/切 Wi-Fi 都能自动跟上。
托盘菜单的「其它网卡地址 ▸」仍会列出全部地址，需要时手动复制。

1.7 改名后历史消息一起变（v1.5.3+）

以前改名只影响新消息，旧消息还挂着老名字老颜色。现在：对方改名/换色后，他发过的历史消息会一起更新（界面按"当前身份"渲染，只在对方从未同步过身份时才退回消息里的快照）。

1.8 设置界面改成页面内模态框（v1.5.3+）

点右上角「设置」不再是弹出桌面窗口，而是页面内的模态框：

- 更大（760px）、圆角更圆（卡片 20px、按钮胶囊形）
- 默认弹到顶部，背后整页压暗
- 不关闭就不能操作其它内容（遮罩拦截点击、锁住滚动、Tab 焦点锁在框内）
- 256 色盘 + 实时预览 + 随机换色；保存即同步给全网

直接访问 http://<你的地址>/#settings 可以打开界面时同时弹出设置框。

8. 许可

MIT，见 LICENSE。