LocalNetMsg/AGENTS.md

LocalNetMsg Agent Guide

LAN instant-messaging desktop app. Stack: Electron 32 + Vue 3 + TypeScript + Vite + Pinia + Element Plus + SQLite (better-sqlite3). Three independent processes built by electron-vite.

Commands

Task	Command
Dev (Electron + HMR)	npm run dev
Build (no installer)	npm run build
Typecheck main+preload	npm run typecheck:node
Typecheck renderer	npm run typecheck:web
Typecheck both	npm run typecheck
Remote feature self-test (terminal / forward / serial)	npm run selftest
Sync-drive end-to-end test (relation -> sync -> delete propagation)	npm run selftest:sync
Packaged-artifact smoke check (asar unpack + real pty spawn)	npm run selftest:package (run after npm run package:*)
Real-Electron nativeImage check (thumbnail encode / transparency / clipboard)	npm run selftest:image (needs a display)
Windows installer	npm run package:win → dist-Electron\LocalNetMsg-0.1.0-Setup.exe
macOS / Linux	npm run package:mac / npm run package:linux
Unpacked dir only	npm run package:dir

All package:* scripts bake in ELECTRON_MIRROR + ELECTRON_BUILDER_BINARIES_MIRROR (npmmirror.com). Do not remove unless on the open internet.

npm run selftest runs the remote (terminal / port-forward / serial) self-test: one process, two virtual nodes, real ChatServer + ChatClient + remote managers. See scripts/selftest/.

npm run selftest:sync runs the sync-drive end-to-end test (scripts/selftest/sync-e2e.ts): two virtual nodes, real WS + HTTP, covering 建立关系 → 双向同步 → 改文件 → 删文件 → 删除传播 → 墓碑防复活. 改同步引擎后跑它 —— 它守住的是"删了能删掉、删了不会复活"这两条命门。

npm run selftest:image 在真 Electron（需要显示器）下验 nativeImage 的实际行为: 缩略图编码阶梯、 PNG 透明通道、转 JPEG 丢透明、剪贴板写读、坏文件降级。它打的是生产代码 (src/main/image.ts, esbuild 打包且 --external:electron), 不是桩 —— 自测里的 electron 是桩, 那套只能验逻辑。

视觉验证 (UI 改动后用): scripts/selftest/inject-image-msg.cjs 往 App 的 SQLite 注入演示消息, scripts/selftest/cdp-shot.cjs 用 CDP 驱动真实窗口点按钮/右键并截图 (环境里没有 xdotool)。 用完记得把注入的数据清掉。

Verify changes via npm run typecheck + npm run selftest + npm run selftest:sync + manual npm run dev.

Layout

src/
  main/       Electron main process (Node) — entry: index.ts
    discovery.ts    UDP broadcast beacon (multi-NIC, per-interface subnet bcast)
    chat-server.ts  WebSocketServer on 0.0.0.0:47900
    chat-client.ts  Outgoing WS with backoff reconnect
    file-server.ts  HTTP /upload + /file, default cap 100GB
    db.ts           SQLite via better-sqlite3 (data/app.db)
    settings.ts     electron-store wrapper (~/AppData/Roaming/local-net-msg/config.json)
    notify.ts       System Notification + Windows overlay badge
    image.ts        nativeImage 封装: 缩略图生成 + 复制到剪贴板 + 读原图
    image-core.ts   图片纯逻辑 (阈值/编码选择/选图源) —— 不 import electron, 可单测
    ipc.ts          All ipcMain.handle() wiring
    protocol.ts     MessageEnvelope, WsFrame, DeviceInfo types
    relations.ts      关系层: 持久绑定 + per-peer 令牌 + 分级授权 (JSON 存储)
    relation-service.ts 关系服务(类): 建立/接受/拒绝/吊销 + 应用对方关系表
    sync-manifest.ts   文件关系表: 墓碑 + Lamport seq + 三方对比 (同步盘地基)
    sync.ts            同步引擎: 扫描 -> 三方对比 -> 上传/下载/删除传播
    auto-sync.ts       自动同步定时器 (60s 轮询 + 指数退避)
  preload/    contextBridge exposing typed API to renderer
  renderer/   Vue 3 SPA (Vite root)
    src/
      main.ts        createApp + Pinia + ElementPlus (full import) + zhCn
      App.vue        Global event listeners (device:*, message:*, settings:*)
      components/    Sidebar, ChatView, MessageInput, MessageItem, SettingsView, MarkdownView
      stores/        Pinia: device.ts, message.ts, session.ts
      api.ts         IPC typings (mirrors preload)
      utils/         format.ts (colorFor, initialsOf, formatSize, ...)
                    unread.ts (未读处理策略: unreadActionForIncoming)
electron.vite.config.ts   Three builds → out/{main,preload,renderer}/

Renderer alias: @ → src/renderer/src.

同步盘 (sync drive) — 三层模型

发现 ≠ 信任。拆成三层: 发现(临时) → 关系(持久, 用户显式建立) → 授权(分级, 双方各自独立)。

• 关系怎么建立: 跟远程终端的授权闸门完全一致 —— 对方直接弹窗, 不用邀请码/6位码/系统消息卡片。 A 点"发起同步关系" → WS 帧 relation:request → B 侧 enqueueApproval()(kind='relation') → 弹窗同意 → 回 relation:accept。 帧定义在 protocol.ts, 路由在 ipc.ts 的 routeRelationFrame()。
• 令牌: myToken=我签发给对方的, peerToken=对方签发给我的。旧的全局 driveToken 不再进 UDP 广播包 (同网段任何进程拿到广播包就能浏览你整个网盘)。file-server 在关系令牌 匹配不上时回退到旧的全局 token, 给还没升级的对端留过渡通道。
• 两套独立空间:
  • /drive/* 网盘 —— 要 drive 授权, 路径限制在网盘根内
  • /sync/* 同步区 —— 要 sync 授权, 路径限制在该关系的同步目录内 (任意位置, 不必在网盘里) 只给 sync 时完全不能浏览网盘。
• 文件关系表 (manifest): 每个关系一份 (key=relationId, 所以同一个本地目录跟多个关系同步也不串)。
  • 墓碑: 删除不抹记录, 只标 state='deleted' —— 直接抹掉的话, 对方离线回来会把已删文件 当成"新增"重新下载, 删除永远删不掉; 对方从备份恢复也会让删除被静默撤销。
  • seq = Lamport 时钟: hash 只能答"一样不一样", seq 才能答"谁更晚" —— 判定删除方向的关键。
  • 三方对比: 基线(上次两边一致的 hash) + 本地 + 远端。缺基线时退回 mtime 兜底 (宁可多弹窗)。
  • 墓碑保留 90 天 (比大品牌默认 30 天保守), 且要"对方已越过该 seq"才清理。
  • 删除传播落点: RelationService.applyPeerManifest() —— 对方说删了, 我比对基线确认没改过才删本地; 改过则报冲突, 绝不静默丢数据。

详细设计见 docs/relation-and-sync.md。

Network protocol

UDP discovery on 47800, chat WS on 47900, file HTTP on 47901. All three bind 0.0.0.0 and auto-shift on conflict.

DeviceInfo carries address (chosen from the first non-internal IPv4 of the responding NIC) plus chatPort/filePort. The chat server sends no broadcast of its own — discovery comes purely from UDP. Receiver uses rinfo.address (real source IP), never the payload's self.address.

Hard-won pitfalls (don't repeat these)

1. chat-client MUST have an on('error') listener. Node EventEmitter throws ERR_UNHANDLED_ERROR and kills the main process if 'error' fires with no listener. The WS 'error' event is followed by 'close' which triggers reconnect. Don't try to "fix" by emitting on the client; just console.warn and move on.

2. Drag-drop file path. Electron 32 removed File.path. Use webUtils.getPathForFile(file) from electron — exposed in src/preload/index.ts as getPathForFile(file). Callers must read it via window.api.getPathForFile(f) BEFORE the await boundary.

3. Native rebuild —— 只重建 better-sqlite3, 别用 electron-builder install-app-deps. better-sqlite3 不是 N-API, 绑死 V8/ABI (Electron 32 → node ABI 128), 必须对着 Electron 头文件编译; npm i 或升级 Electron 后必须重编, 否则 sqlite 打开即崩。 postinstall 现在是 node scripts/postinstall.js: 只重建 better-sqlite3, 装完在 Electron 下 真跑一次读写校验 (失败就 exit 1, 把"启动即崩"提前到 install 阶段暴露)。 别改回 electron-builder install-app-deps —— 它重建所有原生模块, 且给子进程塞 npm_config_build_from_source=false; npm 11 对未知 npm_config_* 保留原始字符串, 于是子进程里 它是字符串 "false" —— JS 里是真值 —— pkg-prebuilds-verify 直接 exit 1 (node_modules/pkg-prebuilds/bin/verify.mjs:14), 强制源码编译。node-hid 于是去编译它自带的 node-addon-api 3.2.1, 和现代 Node 头文件不兼容, 编译失败, 整个 npm install 挂掉 —— 而它本来根本不需要编译 (自带 N-API 预编译产物, 任何 ABI 都能加载)。 同理, node-pty 1.2 的二进制在平台包 @lydell/node-pty-<plat>-<arch> 里, 主包没有 prebuilds/ 目录 —— 按主包去找只会误报。 npm 11 还有个 allowScripts 机制 (根 package.json 的 allowScripts 字段): 没被显式列入的 安装脚本只会被"提醒"而非拦截, 但建议把信任的包列进白名单, 免得将来 npm 真的开始拦截。

4. mkdir for Windows reserved names. Output dir is dist-Electron\ (escaped; dist\electron chokes on Windows). Don't rename without verifying the build still produces a valid path.

5. nsis is oneClick: false. Installer asks for install path + creates Desktop/Start-Menu shortcuts. Permissions are user-scoped.

6. Renderer global drag highlight. Track dragenter/dragleave with a depth counter (not a boolean) — child elements fire leave/enter pairs. See MessageInput.vue's dragDepth.

7. WS 通道状态要"拉取式"同步, 不能只靠事件推送. 聊天框顶部显示的是"通道可用"（outgoing 或 inbound 任一 WS 活着），跟侧边栏的"设备在线"（UDP 发现）是两回事。启动时主进程往往先连上对端（index.ts 里 connectTo 早于 createMainWindow），那条 device:wsState 事件会在渲染层订阅之前就发出去被丢掉 —— 早期实现只有事件推送，UI 因此永久停在"等待重连…"，而连接其实一直是好的。规矩：(1) device:wsState 推全量快照而不是增量；(2) 渲染层 mount 时主动 invoke('app:state') 拉一次；(3) 渲染层先注册监听再 await，否则 await 期间的事件也会丢。详见 docs/connection-status.md。

8. File conflict naming. Append _N before the first .: archive.tar.gz → archive_1.tar.gz, .bashrc → .bashrc_1. Logic in file-server.ts targetPath().

9. 图片消息: 缩略图随消息体走, 右键复制写的是原图. 气泡里显示的是 body.thumbDataUrl (data URL), 发送方生成一次, 对方直接拿来显示 —— 所以对端不用再解码一遍, 老版本对端也看得到图。 缩略图用 Electron 的 nativeImage 生成 (src/main/image.ts), 不引 sharp/jimp: 宽度上限 480, PNG 优先 (保透明 —— 截图转 JPEG 会变黑底), PNG 超 60KB 才退 JPEG, 然后按"降质量 → 缩尺寸"的阶梯找一档够小的 (src/main/image-core.ts 里的纯逻辑, 可单测)。 源文件超过 20MB 不生成缩略图 —— nativeImage 解码会把整张图铺成 RGBA 内存。 拖拽/选中的图片必须走 sendFile(asImage: true) (有真实路径, 流式上传), 只有粘贴的图片才走 sendBuffer (整图 base64 进 WS 帧, 大图会撑爆带宽)。 右键"复制图片"走 image:copy IPC -> clipboard.writeImage, 写的是原图 (本地文件优先, 退回 dataBase64), 不是气泡里那个缩略图。 缩略图缺失时 (老消息 / 老版本对端) 渲染层退到 image:thumb 现场生成, 失败才显示文件卡片。

10. USB 字节桥和 USB/IP 已下线, 只剩串口. v0.2.0 把 src/main/remote/usb.ts 换成了 src/main/remote/serial.ts —— 只做串口映射 (Linux/macOS 用 socat 建 PTY 配对, Windows 用 com0com) + 串口助手 (应用自己收发字节: 文本/HEX、循环发送、保存日志)。 删掉的: node-usb 的 control/bulk 字节桥、USB/IP 真透传, 以及 node-usb / node-hid 两个原生依赖 (它们其实压根没被真正用到)。 线上格式一个字节都没动 —— WS 帧类型仍然叫 'usb', PROTOCOL_VERSION 仍是 1, 内部类型全改名成 Serial*。原因: 局域网里常有一台机器还跑着旧版本, 升协议版本会让 两边连不上 (连文字消息都发不了), 代价太大。现在新旧版本之间: 聊天照常, 串口映射也照常 (老版本本来就支持 kind:'serial'), 只有 USB 字节桥在混版本时用不了 —— 而那功能已下线。 代价: 协议里那个 'usb' 帧名和实际内容对不上, 改的时候别手贱"顺手改对" —— 会把 所有还在跑旧版本的对端一起踢下线。 另注: 拉对端的串口列表要对方用户批准 (新旧版本都这样), 对方没点批准就是 15 秒超时 -> 列表空 + 报"超时"。这是审批机制不是 bug, 别去加"自动跳过审批"的逻辑。

11. 未读/角标: 正在看的会话必须立刻清未读, 且不能被 savedPath 拦下来. 踩过的坑: App.vue 的 message:received 里先判断 if (!savedPath) return (等文件落地再算未读), 结果文字消息没有 savedPath —— 正好在"清未读"之前就 return 了, 于是用户明明在看这个会话, 角标数字却一直挂着。文件/图片消息因为第二帧带 savedPath 才碰巧能清掉, 所以只有文字消息暴露这个 bug。 规矩: 先判 isActive -> 清未读 + 回已读回执, 再判 savedPath。 决策抽成了纯函数 src/renderer/src/utils/unread.ts 的 unreadActionForIncoming() (clear / wait / count), 自测 U1/U2 守着它 —— 别再把顺序写回 if 里。 另外两处也要清: 侧边栏重复点同一个设备时 activePeerId 不变, watch 不触发, 得显式清一次; 主进程 device:delete 清了 unread 但忘了 updateBadge(), 角标数字会残留。

Configuration knobs

• LNM_MAX_FILE_SIZE=<bytes> env var overrides the 100 GB default in file-server.ts. Useful for testing the limit path.
• deviceName, downloadDir, notifications, autoStart live in ~/AppData/Roaming/local-net-msg/config.json via electron-store. Edit the file directly while dev is stopped.
• data/app.db — SQLite DB. DELETE to reset all devices/messages. Auto-migrates on next launch.

提交与推送

远端是自建 Gitea (https://git.xsinfo.vip/xiaoshuai/LocalNetMsg.git)。HTTPS 没有配 credential helper，非交互式 git push 会卡在 could not read Username 上 —— 所以 push URL 已经指到 SSH：

origin  https://git.xsinfo.vip/xiaoshuai/LocalNetMsg.git (fetch)
origin  git@git.xsinfo.vip:xiaoshuai/LocalNetMsg.git      (push)

fetch 走 HTTPS、push 走 SSH，直接 git push 就能用。SSH key 失效时退回： git push git@git.xsinfo.vip:xiaoshuai/LocalNetMsg.git main:main（显式指定 URL 不改 remote 配置）。

拉远端最新提交用 git fetch git@git.xsinfo.vip:xiaoshuai/LocalNetMsg.git main:refs/remotes/origin/main —— 否则 origin/main 是陈的，git status 里的 "领先 N" 是假的。

Packaging gotcha

release/ contains an app.asar Windows cannot delete while the previous app instance holds a file handle. Build now writes to dist-Electron\ to dodge this. If you ever switch back, kill the running app first or you'll get EPERM.

Linux packaging (icon + taskbar)

Ubuntu 装完"没图标"是个坑，有两个独立原因：

1. linux.icon 必须指向目录，不能是单张 PNG。 electron-builder 把图标装进 /usr/share/icons/hicolor/<size>x<size>/apps/<exe>.png，而单张 PNG 交给 app-builder 时它解析不出尺寸（返回 size: 0），于是装进 hicolor/0x0/ 这种非法目录，桌面环境根本找不到 → 启动器没图标。正确做法是给一个目录，里面按 <size>x<size>.png 命名：resources/icons/{16,24,32,48,64,128,256,512}x{...}.png，然后 linux.icon = "resources/icons"。图标集用 node scripts/make-icon.js 生成（需要 ImageMagick 的 convert；生成结果已提交，平时不用跑）。

2. StartupWMClass 要跟窗口真实的 WM_CLASS 一致。 electron-builder 默认填 productName（LocalNetMsg），但 Electron 实际设的是可执行文件名（local-net-msg）—— 对不上，任务栏就找不到对应启动器，显示成通用图标。用 xprop -id <wid> WM_CLASS 确认真实值，然后在 build.linux.desktop.StartupWMClass 里写它。

Windows / macOS 仍用单张 resources/icon.png（那里不按尺寸分目录）。

Windows 兼容性

完整的分析、已修问题和待验证清单见 docs/windows-compat.md。最容易踩的两个：

1. build.asarUnpack 里的原生模块规则必须递归（**/*）。 node-pty 1.2 是"主包 + 平台包"拆包架构，平台包 @lydell/node-pty-<platform>-<arch> 里除了 .node 还有 conpty.dll / OpenConsole.exe，而 node-pty 的 ConPTY worker 用 worker_threads.Worker 起脚本——都必须是磁盘上的真实文件。规则写成 .../node-pty-*/*（单层）会把 prebuilds/<plat>/ 下的东西留在 asar 里，Windows 终端直接起不来（Linux 上看不出来，因为只需要一个 .node）。自测 S7 守着这条规则。

2. Windows 保留设备名：CON PRN AUX NUL COM1-9 LPT1-9（带扩展名也算）不能直接当文件名——对它们 open() 打开的是设备不是文件。落盘前统一走 src/main/safe-name.ts 的 safeFileName()（按本机平台决定要不要改写，Linux 上 CON 是合法文件名，不该动）。