mc-tunnel 0.1.0 → 0.2.0

package/docs/USAGE.md

@@ -0,0 +1,1220 @@
+# mc-tunnel 使用文档
+
+面向 **Electron / Node.js** 的 Minecraft 局域网联机模块。房主在游戏里「对局域网开放」，把**房间码**发给朋友；朋友输入房间码后，游戏「多人游戏 → 局域网世界」里就会出现这条房间，双击即可进入。
+
+本文档按「摸清概念 → 跑起来 → 查 API → 排错」的顺序组织，**所有参数默认值、端口、超时、事件时机都来自当前源码**（v0.1.1），可直接对照排查。
+
+---
+
+## 目录
+
+1. [它能做什么 / 不能做什么](#1-它能做什么--不能做什么)
+2. [工作原理](#2-工作原理)
+3. [环境与依赖](#3-环境与依赖)
+4. [安装与 EasyTier 准备](#4-安装与-easytier-准备)
+5. [五分钟上手](#5-五分钟上手)
+6. [房主 API（createHost）](#6-房主-apicreatehost)
+7. [客人 API（createGuest）](#7-客人-apicreateguest)
+8. [事件与状态机](#8-事件与状态机)
+9. [房间码与凭据](#9-房间码与凭据)
+10. [协调协议（HTTP 接口）](#10-协调协议http-接口)
+11. [工具函数参考](#11-工具函数参考)
+12. [Electron 集成](#12-electron-集成)
+13. [网络部署模式](#13-网络部署模式)
+14. [错误码与故障排查](#14-错误码与故障排查)
+15. [生命周期与进程管理](#15-生命周期与进程管理)
+16. [安全模型](#16-安全模型)
+17. [兼容性 / 已知限制](#17-兼容性--已知限制)
+18. [性能与资源占用](#18-性能与资源占用)
+19. [附录：类型与默认值速查](#19-附录类型与默认值速查)
+
+---
+
+## 1. 它能做什么 / 不能做什么
+
+### 能做
+
+| 场景 | 说明 |
+|---|---|
+| 公网联机 | 双方各自在任意网络（家庭宽带、4G/5G、公司网），凭一个 19 字符房间码互联 |
+| 局域网直连 | 同一局域网内用 `peers` 直连，完全绕开公共节点，无需外网 |
+| 自建节点 | 用 `listeners` + `peers` 指向自建 EasyTier 节点，`p2pOnly: false` 可走中继 |
+| 免管理员权限 | EasyTier 以 `--no-tun` 运行，不创建虚拟网卡，普通用户即可 |
+| 无 mod | 通过伪造 Minecraft 局域网多播，原版客户端直接可见 |
+| Electron 桌面应用 | 提供 `mc-tunnel/electron` 子入口，自动处理 userData 路径与退出清理 |
+
+### 不能做
+
+- **不是 Minecraft 服务端**：它只做网络打通 + 广播伪造，Minecraft 本身要房主自己开。
+- **不打包 EasyTier 二进制**：体积与许可原因，需要你自己放置 `easytier-core` / `easytier-cli`。
+- **不支持 IPv6 多播**：扫描与广播均只实现 `udp4`（IPv4）。
+- **不支持同一台机器开多个房主**：协调端口默认固定 `25991`，第二个房主会失败。
+- **不提供中继服务器**：默认 `p2pOnly: true`，对称 NAT 双端可能连不上（见 §13）。
+- **不修改游戏、不需要客户端装 mod**，但要求 MC 版本支持「对局域网开放」（1.3+ 全部支持）。
+
+---
+
+## 2. 工作原理
+
+```
+房主（Host）                                      客人（Guest）
+────────────                                     ────────────
+① 监听 UDP 4445 多播，发现本机 MC 端口           ① 房间码 → 派生网络名 / 网络密钥
+   （或直接传 mcPort 跳过）                          ↓
+        ↓                                       ② easytier-core 以 DHCP 入网
+② easytier-core 固定虚拟 IP 10.144.144.1            ↓
+        ↓                                       ③ 轮询 peer 列表，等 10.144.144.1 出现
+③ 本地 HTTP 协调服务 0.0.0.0:25991                  ↓
+   （/v1/hello /v1/session /v1/players）        ④ 端口映射 tcp://0.0.0.0:<随机> → 10.144.144.1:25991
+        ↓                                           ↓
+④ 提供 session：返回 MC 端口与玩家列表          ⑤ GET /v1/hello 校验 probe（确认对端真是房主）
+                                                    ↓
+                                                ⑥ GET /v1/session（带 x-mct-token）拿到 MC 端口
+                                                    ↓
+                                                ⑦ 端口映射 tcp/udp 0.0.0.0:<localPort> → 10.144.144.1:<mcPort>
+                                                    ↓
+                                                ⑧ 本地 ping 127.0.0.1:<localPort> 确认可用
+                                                    ↓
+                                                ⑨ 每 1.5s 伪造多播「局域网世界」，端口写 localPort
+                                                    ↓
+                                                ⑩ 每 5s POST /v1/players 心跳 + 刷新玩家列表
+```
+
+关键设计取舍：
+
+1. **房主虚拟 IP 固定** `10.144.144.1`（EasyTier 默认网段 `10.144.144.0/24`）。这样客人不需要任何发现协议，直接按地址连协调服务。
+2. **协调协议用 HTTP/JSON**，跑在隧道内部，`curl` 就能调试，不引入任何 npm 依赖。
+3. **房间码自包含凭据**：网络名、网络密钥、握手探针、访问令牌全部由房间码里的 64 bit 种子经 HMAC-SHA256 派生，房间码本身不含明文。
+4. **端口白名单**：房主 `--tcp-whitelist` 只放行协调端口 + MC 端口，客人 `--tcp-whitelist=0`（不提供任何服务）。
+
+---
+
+## 3. 环境与依赖
+
+| 项 | 要求 | 说明 |
+|---|---|---|
+| Node.js | **>= 18.17** | 需要内置 `fetch`（18.0+ 实验性）与 `AbortSignal.timeout`（17.3+）；`node --test` 跑测试需要 18+ |
+| 操作系统 | Windows / macOS / Linux | Windows 下二进制名自动补 `.exe` |
+| 运行时 npm 依赖 | **零** | 只用 `node:http` `node:dgram` `node:net` `node:child_process` `node:crypto` `node:os` `node:fs` `node:path` |
+| 权限 | 普通用户 | 不开 TUN 网卡，不需要管理员 / root |
+| 网络 | 出站 UDP 可用 | EasyTier 需要 UDP 打洞；公司网封 UDP 时需 `p2pOnly: false` + 自建 TCP 节点 |
+| EasyTier | 自备二进制 | `easytier-core` + `easytier-cli`，两者放在同一目录 |
+
+### 运行时端口一览
+
+| 端口 | 协议 | 谁监听 | 用途 | 是否可改 |
+|---|---|---|---|---|
+| `4445` | UDP 多播 `224.0.2.60` | 读：房主扫描 / 写：客人广播 | Minecraft 局域网发现 | 不可改（MC 固定） |
+| `25991` | TCP | 房主 | 协调服务 | `HostOptions.coordPort` 可改，但**客人侧硬编码 25991**，见 §17 |
+| 随机高位端口 | TCP | 房主 / 客人 | EasyTier RPC（`-r`） | 内部自动分配 |
+| `11010` 等 | TCP/UDP | 双方 | EasyTier 监听（默认 `0.0.0.0:0` 随机，可加 `listeners`） | 可配置 |
+| `25565` 或房主实际端口 | TCP+UDP | 客人 | 本地映射端口 `localPort` | `preferredLocalPort` |
+| 随机高位端口 | TCP | 客人 | 协调服务临时映射 | 内部自动分配 |
+
+---
+
+## 4. 安装与 EasyTier 准备
+
+### 4.1 安装本包
+
+```bash
+npm install mc-tunnel
+# 国内镜像
+npm install mc-tunnel --registry=https://registry.npmmirror.com
+```
+
+包同时提供 ESM 与 CJS：
+
+```ts
+// ESM / TypeScript
+import { createHost, createGuest } from 'mc-tunnel';
+```
+
+```js
+// CommonJS
+const { createHost, createGuest } = require('mc-tunnel');
+```
+
+子路径：
+
+```ts
+import { createHostInElectron, manageSessions } from 'mc-tunnel/electron';  // Electron 适配
+import { toChineseRoomCode } from 'mc-tunnel/zh';                            // 中文房间码（彩蛋，可选）
+```
+
+### 4.2 放置 EasyTier 二进制
+
+需要两个文件（Windows 带 `.exe`）：
+
+```
+easytier-core(.exe)
+easytier-cli(.exe)
+```
+
+**查找顺序**（`resolveBinaries()` 实现，命中即用）：
+
+1. `easyTier.binDir` —— 可以是**目录**，也可以是 `easytier-core` 的**完整文件路径**（会自动取父目录）
+2. 环境变量 `MC_TUNNEL_EASYTIER` —— 同上，目录或文件路径
+3. `<process.cwd()>/easytier`
+4. `<process.resourcesPath>/easytier` —— 仅在 Electron 打包后存在
+
+四个位置都没找到会抛：
+
+```
+TunnelError: EASYTIER_NOT_FOUND
+Cannot find easytier-core.exe / easytier-cli.exe. Tried:
+  <逐个列出的候选路径>
+请通过 easyTier.binDir 或环境变量 MC_TUNNEL_EASYTIER 指定目录。
+```
+
+> 提示：只需保证 `core` 与 `cli` 在**同一目录**；`core` 子进程的 `cwd` 会被设为该目录。
+
+### 4.3 三种放置方式示例
+
+```bash
+# 方式 1：环境变量（开发时最方便）
+# Windows PowerShell
+$env:MC_TUNNEL_EASYTIER = "D:\tools\easytier"
+# macOS / Linux
+export MC_TUNNEL_EASYTIER=/opt/easytier
+```
+
+```ts
+// 方式 2：代码里显式指定
+const host = await createHost({ mcPort: 25565, easyTier: { binDir: 'D:/tools/easytier' } });
+```
+
+```jsonc
+// 方式 3：Electron 打包时放进 resources
+// electron-builder 配置
+{
+  "extraResources": [
+    { "from": "vendor/easytier", "to": "easytier" }
+  ]
+}
+```
+
+> ⚠️ 若使用 ASAR：**不要**把 EasyTier 打进 `asar`，ASAR 内的可执行文件无法 `spawn`。必须走 `extraResources`。
+
+---
+
+## 5. 五分钟上手
+
+### 5.1 房主
+
+```ts
+import { createHost } from 'mc-tunnel';
+
+const host = await createHost({
+  playerName: 'Alice',
+  mcPort: 25565,          // 不传则自动扫描局域网广播（最多 30s）
+});
+
+console.log('房间码:', host.roomCode);      // 2GJY-DYSK-8825-DZJY
+console.log('MC 端口:', host.mcPort);
+console.log('虚拟 IP:', host.virtualIp);    // 10.144.144.1
+
+host.on('player-join', (p) => console.log(`${p.name} 加入了`));
+host.on('player-leave', (p) => console.log(`${p.name} 离开了`));
+host.on('players', (list) => console.log('当前玩家:', list.map((x) => x.name).join(', ')));
+host.on('mc-closed', ({ port }) => console.log(`端口 ${port} 上的存档已关闭`));
+host.on('error', (err) => console.error('房主异常:', err.code, err.message));
+
+console.log('状态:', host.phase);           // ready
+```
+
+房主要做的事：**别关程序**。玩家退出存档时 `mc-closed` 会触发，但会话不会自动销毁（方便玩家重新开放）。
+
+### 5.2 客人
+
+```ts
+import { createGuest } from 'mc-tunnel';
+
+const guest = await createGuest({
+  roomCode: '2GJY-DYSK-8825-DZJY',
+  playerName: 'Bob',
+});
+
+console.log('在游戏里连接:', guest.address);    // 127.0.0.1:25565
+console.log('NAT 难度:', guest.natDifficulty);  // easiest | simple | medium | tough | unknown
+
+guest.on('server-status', (st) => console.log('房主存档:', st.version, st.players));
+guest.on('players', (list) => console.log('房间里:', list.map((x) => x.name).join(', ')));
+guest.on('error', (err) => console.error('客人异常:', err.code, err.message));
+```
+
+此时打开 Minecraft → 多人游戏 → **局域网世界**，就会出现一条房间（MOTD 默认 `§b§lMC Tunnel 联机房间（请保持程序运行）`），双击进入。
+
+### 5.3 一定要关闭
+
+```ts
+await guest.close();
+await host.close();
+```
+
+不调用 `close()` 会残留 `easytier-core` 子进程，端口也被占着。库里有兜底（宿主进程 `exit` 时 `kill`），但只对正常退出有效，`SIGKILL` / 任务管理器强杀无效。
+
+### 5.4 最小可运行脚本（两个文件、两台机器）
+
+`host.mjs`：
+
+```js
+import { createHost } from 'mc-tunnel';
+
+const host = await createHost({ playerName: 'Alice' });
+console.log('\n房间码（发给朋友）:\n  ' + host.roomCode + '\n');
+
+process.on('SIGINT', async () => {
+  await host.close();
+  process.exit(0);
+});
+```
+
+`guest.mjs`：
+
+```js
+import { createGuest } from 'mc-tunnel';
+
+const guest = await createGuest({
+  roomCode: process.argv[2],
+  playerName: 'Bob',
+});
+console.log('\n在 Minecraft 里连接:\n  ' + guest.address + '\n');
+
+process.on('SIGINT', async () => {
+  await guest.close();
+  process.exit(0);
+});
+```
+
+```bash
+node host.mjs
+node guest.mjs 2GJY-DYSK-8825-DZJY
+```
+
+---
+
+## 6. 房主 API（createHost）
+
+```ts
+function createHost(options?: HostOptions): Promise<TunnelHost>;
+```
+
+返回 `TunnelHost`（`extends EventEmitter`，同时实现 `HostSession` 接口）。
+
+### 6.1 参数
+
+| 参数 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `roomCode` | `string` | 随机生成 | 指定房间码；非法时抛 `INVALID_ROOM_CODE`。与 `passphrase` 二选一 |
+| `passphrase` | `string` | `undefined` | **口令模式**：用一段短语代替房间码（§9.5）。与 `roomCode` 二选一，同时给会抛 `INVALID_OPTIONS` |
+| `mcPort` | `number` | 自动扫描 | 指定 MC 端口；**不传时监听 UDP 4445 多播自动发现** |
+| `playerName` | `string` | `'Host'` | 昵称，会出现在玩家列表 `/v1/session` 里 |
+| `motd` | `string` | `'§b§lMC Tunnel 联机房间（请保持程序运行）'` | 局域网列表显示名；**同时用于排除自己发出的广播** |
+| `coordPort` | `number` | `25991` | 协调服务端口。⚠️ 客人侧硬编码 25991，改了客人连不上（§17） |
+| `listeners` | `string[]` | `undefined` | 额外 EasyTier 监听，如 `["tcp://0.0.0.0:11010"]` |
+| `peers` | `string[]` | `undefined` | 直连对端，如 `["tcp://192.168.1.7:11010"]`。**不能写 127.0.0.1** |
+| `scanTimeoutMs` | `number` | `30000` | 自动发现 MC 的超时 |
+| `dataDir` | `string` | `<tmp>/mc-tunnel` | 设备标识存储目录 |
+| `easyTier.binDir` | `string` | 见 §4.2 | EasyTier 目录或 core 路径 |
+| `easyTier.publicNodes` | `string[]` | `undefined` | 额外公共节点，如 `["tcp://public.easytier.top:11010"]` |
+| `easyTier.p2pOnly` | `boolean` | `true`（未传即视为 true） | 是否只用 P2P、禁止中继 |
+
+### 6.2 只读属性
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `roomCode` | `string` | 规范化后的房间码（含 `-` 分组、大写） |
+| `mcPort` | `number` | 房主 MC 端口 |
+| `coordPort` | `number` | 协调服务端口（实际生效值） |
+| `virtualIp` | `string` | 恒为 `'10.144.144.1'` |
+| `phase` | `Phase` | 当前阶段 |
+
+### 6.3 方法
+
+| 方法 | 说明 |
+|---|---|
+| `players(): Player[]` | 当前玩家列表，**房主自己在第一位**，其余按 `id` 字典序。`close()` 后返回 `[]` |
+| `close(): Promise<void>` | 幂等。停 watchdog → 关协调服务 → 停 EasyTier → 置 `closed` |
+
+### 6.4 事件
+
+| 事件 | 载荷 | 触发时机 |
+|---|---|---|
+| `state` | `Phase` | 每次阶段变化（含 `closed`） |
+| `players` | `Player[]` | 玩家加入 / 被剔除 |
+| `player-join` | `Player` | **首次**收到某 `id` 的心跳（`{ id, name }`，注意不含 `role`） |
+| `player-leave` | `Player` | 12 秒无心跳被剔除（`{ id, name }`） |
+| `mc-closed` | `{ port: number }` | 连续 3 次（约 15s）ping 不通本机 MC 端口 |
+| `error` | `TunnelError` | EasyTier 进程异常退出（**仅此一种**，见下） |
+
+> ⚠️ 非常关键：`error` 事件**只有房主 watchdog 检测到 EasyTier 退出时才发**，而且**没有监听者时不会 emit**（代码里做了 `listenerCount('error') > 0` 判断）。初始化阶段的失败是**直接 reject Promise**，不会走事件。
+
+### 6.5 初始化流程（`createHost` 内部顺序）
+
+```
+getDeviceId(dataDir)                    ← 读/生成设备标识（24 位 hex）
+parseRoomCode(roomCode ?? generate)     ← 得到网络名 / 网络密钥
+deriveRoomSecrets(code)                 ← 得到 probe / token
+emit('state', 'scanning')
+  ├─ 有 mcPort：直接用
+  └─ 无 mcPort：McLanScanner 监听 4445，filter: motd !== 自己的 motd
+                命中第一条广播即取端口；超时抛 MC_NOT_FOUND
+emit('state', 'starting-tunnel')
+resolveBinaries() → pickTcpPort()（内部 RPC 端口） → coordPort = options.coordPort ?? 25991
+EasyTierNode.start({ ipv4: '10.144.144.1', tcpWhitelist: [coordPort, mcPort], udpWhitelist: [mcPort] })
+CoordServer.start({ port: coordPort, ... })
+startWatchdog()   ← 每 5s：EasyTier 存活？pingMc(mcPort) 通吗？
+emit('state', 'ready')
+```
+
+### 6.6 watchdog 的精确行为
+
+- 间隔 `5000ms`（定时器 `unref()`，不阻止进程退出）。
+- 先判 EasyTier 是否存活：不存活 → `state = error` + `emit('error', EASYTIER_EXITED)`，**但不自动 close**。
+- 再 `pingMc(mcPort)`：
+  - 成功 → 失败计数清零
+  - 失败 → 计数 +1，累计到 3 才 `emit('mc-closed', { port })`，然后计数清零
+- 也就是说：**Minecraft 关掉后大约 15 秒**才会通知，且不会重复轰炸（再次失败要再攒 3 次）。
+
+---
+
+## 7. 客人 API（createGuest）
+
+```ts
+function createGuest(options: GuestOptions): Promise<TunnelGuest>;
+```
+
+`roomCode` 必填。失败时 Promise **reject 为 `TunnelError`**，并且内部已经 `close()` 过，不会残留进程。
+
+### 7.1 参数
+
+| 参数 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `roomCode` | `string` | 二选一必填 | 支持容错输入（§9.3）。与 `passphrase` 二选一 |
+| `passphrase` | `string` | 二选一必填 | 口令模式，需与房主同口令（大小写、空白、全角不敏感）；两者都不给或都给都抛 `INVALID_OPTIONS` |
+| `playerName` | `string` | `'Guest'` | 昵称，最长 32 字符（服务端截断） |
+| `motd` | `string` | 同房主默认值 | 局域网列表显示名 |
+| `preferredLocalPort` | `number` | 房主 MC 端口 | 期望的本地端口；TCP/UDP 都被占则随机 |
+| `peers` | `string[]` | `undefined` | 直连对端；**不能写 127.0.0.1** |
+| `timeoutMs` | `number` | `90000` | 整个建链的**总预算**，不是单步超时 |
+| `dataDir` | `string` | `<tmp>/mc-tunnel` | 设备标识目录 |
+| `easyTier.binDir` / `publicNodes` / `p2pOnly` | 同上 | | 客人未暴露 `listeners` |
+
+### 7.2 只读属性
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `roomCode` | `string` | 规范化房间码 |
+| `mcPort` | `number` | **房主**（远端）的 MC 端口 |
+| `localPort` | `number` | 本地映射端口 |
+| `address` | `string` | `127.0.0.1:<localPort>`，直接喂给 Minecraft |
+| `natDifficulty` | `NatDifficulty` | 基于双方 NAT 类型的展示用难度 |
+| `phase` | `Phase` | 当前阶段 |
+
+### 7.3 方法
+
+| 方法 | 说明 |
+|---|---|
+| `hostPlayers(): Player[]` | 缓存的上一次玩家列表（含房主） |
+| `close(): Promise<void>` | 幂等。停心跳 → 停广播 → 停 EasyTier → 置 `closed` |
+
+### 7.4 事件
+
+| 事件 | 载荷 | 触发时机 |
+|---|---|---|
+| `state` | `Phase` | 每次阶段变化 |
+| `players` | `Player[]` | 握手拿到初始列表 + 每次心跳返回（**每 5s 一次**） |
+| `server-status` | `McStatus` | 本地映射首次 ping 通房主 MC 时（**只发一次**；被插件屏蔽状态查询时不发） |
+| `error` | `TunnelError` | ⚠️ **库本身不会 emit 这个事件**，初始化失败是 reject；保留给使用者自行 emit 的约定 |
+
+> 实用提示：`players` 事件每 5 秒发一次，UI 上做 diff 再渲染，避免无谓重绘。
+
+### 7.5 初始化流程
+
+```
+parseRoomCode(roomCode)                     ← 非法 → INVALID_ROOM_CODE
+deriveRoomSecrets(code)
+emit('state', 'starting-tunnel')
+EasyTierNode.start({ dhcp: true, tcpWhitelist: [0], udpWhitelist: [0] })
+emit('state', 'waiting-peer')
+  每 1s 查一次 peer 列表，找 ipv4 === '10.144.144.1' 且 !isLocal 的节点
+  期间 EasyTier 退出 → EASYTIER_EXITED
+  直到 deadline（timeoutMs）→ PEER_NOT_FOUND
+emit('state', 'connecting')
+  pickTcpPort() → 端口映射 tcp 0.0.0.0:<tmp> → 10.144.144.1:25991
+  CoordClient('http://127.0.0.1:<tmp>', token)
+  每 1s 重试 GET /v1/hello，probe 匹不上就继续重试
+  超过 deadline → HANDSHAKE_FAILED
+  GET /v1/session（x-mct-token）→ mcPort、players
+  mcPort 非 1..65535 → HANDSHAKE_FAILED
+localPort = preferredLocalPort ?? mcPort → pickDualPort(优先同号，TCP+UDP 同时空闲)
+  端口映射 tcp 0.0.0.0:<localPort> → 10.144.144.1:<mcPort>
+  端口映射 udp 0.0.0.0:<localPort> → 10.144.144.1:<mcPort>
+最多 10 次（每次间隔 1s）：pingMc(localPort)
+  成功 → emit('server-status')
+  失败 → isPortOpen(localPort) 兜底（有服务端插件屏蔽状态查询时）
+  都失败 → TIMEOUT('端口映射已建立，但无法连到房主的 Minecraft 服务端。')
+McLanAnnouncer.start()   ← 每 1500ms 发 [MOTD]...[AD]localPort[/AD]
+natDifficulty(本地 NAT, 房主 NAT)
+startHeartbeat()         ← 立即一次 + 每 5s POST /v1/players
+emit('state', 'ready')
+```
+
+任一环节抛错 → 内部 `close()` → 原样抛 `TunnelError`（非 `TunnelError` 会被包成 `UNKNOWN`）。
+
+### 7.6 NAT 难度判定规则
+
+```ts
+open   = ['OpenInternet']
+simple = ['NoPat', 'FullCone']
+medium = ['Restricted', 'PortRestricted']
+
+任一方在 open   → 'easiest'
+任一方在 simple → 'simple'
+任一方在 medium → 'medium'
+双方都是 Unknown → 'unknown'
+其余（含 Symmetric 等） → 'tough'
+```
+
+---
+
+## 8. 事件与状态机
+
+### 8.1 Phase 枚举
+
+```ts
+type Phase =
+  | 'idle'            // 刚创建，尚未初始化（外部几乎观察不到）
+  | 'scanning'        // 房主：正在扫局域网广播
+  | 'starting-tunnel' // 双方：EasyTier 启动中（含等待 RPC 就绪，最长 20s）
+  | 'waiting-peer'    // 客人：等房主 10.144.144.1 出现
+  | 'connecting'      // 客人：协调握手 + 建端口映射
+  | 'ready'           // 可用
+  | 'closed'          // 已关闭
+  | 'error'           // 房主：EasyTier 异常退出后
+```
+
+> 注：`'error'` 只在房主 watchdog 检测到 EasyTier 退出时出现；客人出错是抛异常 + 直接进 `closed`。
+
+### 8.2 状态流转
+
+房主：
+
+```
+idle → scanning → starting-tunnel → ready → closed
+                                     └→ error （EasyTier 崩溃）
+```
+
+客人：
+
+```
+idle → starting-tunnel → waiting-peer → connecting → ready → closed
+  └────────────── 任何一步失败：内部 close() → closed，同时 reject
+```
+
+### 8.3 订阅建议
+
+```ts
+// 事件监听要在 await 之前? 不行——createHost 返回后已经 ready 了。
+// 若要观察 scanning 等早期阶段，请改用类静态方法并自行 hook（见下）
+const host = await createHost({ mcPort: 25565 }); // 此时 phase 已是 'ready'
+host.on('state', (p) => console.log('phase:', p)); // 只能看到后续变化
+```
+
+如果你需要 UI 上显示「正在扫描 / 正在启动」：`createHost` 是原子的（内部完成全部初始化才 resolve），因此**UI 层应在调用前先渲染一个「初始化中」的占位状态**，不要指望中间 phase 事件。
+
+---
+
+## 9. 房间码与凭据
+
+### 9.1 格式
+
+```
+[4 bit 版本][64 bit 随机种子][12 bit CRC]  = 80 bit = 16 字符 × 5 bit
+```
+
+- 字符集：**Crockford Base32**（`0-9A-Z` 去掉 `I` `L` `O` `U`）
+- 展示：`XXXX-XXXX-XXXX-XXXX`，长度 **19**（`ROOM_CODE_LENGTH`）
+- 版本号当前为 `1`；其他版本一律视为非法
+- CRC-12，多项式 `0x80F`
+
+示例：`2GJY-DYSK-8825-DZJY`
+
+### 9.2 派生关系
+
+```
+seed（64 bit）
+ ├─ HMAC-SHA256(seed, "mc-tunnel/v1/network-name")[0..8]  → mct-<hex>   EasyTier --network-name
+ ├─ HMAC-SHA256(seed, "mc-tunnel/v1/network-secret")[0..16]→ <hex>      EasyTier --network-secret
+ ├─ HMAC-SHA256(seed, "mc-tunnel/v1/probe")[0..8]         → <hex>       /v1/hello 的 probe
+ └─ HMAC-SHA256(seed, "mc-tunnel/v1/token")[0..16]        → <hex>       x-mct-token
+```
+
+**安全语义**：拿到房间码 = 拿到入网凭据。房间码本身不含明文密码，但 64 bit 种子等价于密钥。
+熵为 2^64，配合 12 bit CRC 的误输入拦截，暴力猜码不现实；但**房间码泄露即等于房间被加入**，不要公开发布在公共频道。
+
+### 9.3 输入容错（`normalizeRoomCode`）
+
+| 输入 | 处理 |
+|---|---|
+| 小写 | 转大写 |
+| 空格、`-`、任意非 `0-9A-Z` 字符 | 全部剔除 |
+| `MT-` 前缀 | 剔除后若正好 16 位才剥（避免误伤以 `MT` 开头的合法码） |
+| `I` / `L` | → `1` |
+| `O` | → `0` |
+| `U` | → `V` |
+| 结果不是 16 位 / 含非法字符 | 返回 `null` |
+
+```ts
+normalizeRoomCode('2gjy dysk-8825 dzjy'); // '2GJYDYSK8825DZJY'
+normalizeRoomCode('MT-2GJY-DYSK-8825-DZJY'); // '2GJYDYSK8825DZJY'
+normalizeRoomCode('hello'); // null
+```
+
+### 9.4 校验
+
+```ts
+import { verifyRoomCode, parseRoomCode } from 'mc-tunnel';
+
+verifyRoomCode('2GJY-DYSK-8825-DZJY'); // true/false，含版本与 CRC 校验
+parseRoomCode('2GJY-DYSK-8825-DZJY');
+// { code: '2GJY-DYSK-8825-DZJY',
+//   networkName: 'mct-3f9a...',
+//   networkSecret: 'c1d2...' }
+```
+
+非法输入 `parseRoomCode` 抛 `TunnelError('INVALID_ROOM_CODE', 'Invalid room code')`。
+
+### 9.5 口令模式（用一段短语代替房间码）
+
+```ts
+import { createHost, createGuest, roomCodeFromPassphrase } from 'mc-tunnel';
+
+// 房主
+const host = await createHost({ mcPort: 25565, passphrase: '彩蛋口令 演示' });
+console.log(host.roomCode); // 等价房间码，UI 可以二选一展示
+
+// 客人：口令相同即可加入（大小写、首尾/连续空白、全角都不敏感）
+const guest = await createGuest({ passphrase: '  彩蛋口令    演示  ' });
+```
+
+原理：
+
+```
+口令 → NFKC 归一化 → 小写 / 折叠空白
+     → HMAC-SHA256('mc-tunnel/v1/passphrase', 口令) 前 8 字节 = 64 bit 种子
+     → 与随机房间码走**完全相同**的派生链（网络名 / 网络密钥 / probe / token）
+```
+
+因此「口令」和「房间码」是同一个种子的两种表达方式，两者可互换：
+
+```ts
+roomCodeFromPassphrase('彩蛋口令 演示'); // => '2GJY-DYSK-8825-DZJY' 这样的标准码
+```
+
+| 工具 | 说明 |
+|---|---|
+| `normalizePassphrase(text)` | NFKC → trim → 折叠空白 → 小写；返回归一化后的口令 |
+| `seedFromPassphrase(text)` | 口令 → `bigint` 64 bit 种子；空口令抛 `INVALID_PASSPHRASE` |
+| `roomCodeFromPassphrase(text)` | 口令 → 标准房间码 |
+| `passphraseStrength(text)` | `'weak' \| 'fair' \| 'good'`，纯中文按更短阈值评估（<4 弱、≥6 好） |
+
+> ⚠️ 安全边界：口令的强度**完全由口令本身决定**。`1234`、`芝麻开门` 这类弱口令等于把房间公开——64 bit 种子并不等于 64 bit 安全性。需要严格安全时请用随机房间码（默认行为）。
+> 另外，口令一旦泄露，攻击者不仅能进房间，还能反推出同一个房间码；反之从房间码也推不出口令（HMAC 单向）。
+
+### 9.6 中文房间码（彩蛋，需显式引入）
+
+中文码是**可选模块**，放在子入口 `mc-tunnel/zh`，普通用户不会为它付体积代价（数据约 12 KB 源码）。
+
+```ts
+import { toChineseRoomCode, parseChineseRoomCode, formatChineseRoomCode } from 'mc-tunnel/zh';
+
+const zh = toChineseRoomCode(host.roomCode);   // 例如 '朱上岸雪存违户'
+formatChineseRoomCode(zh);                     // '朱 上 岸 雪 存 违 户'（便于抄写/朗读）
+
+// 客人：把中文码解析回标准码再传进去
+const guest = await createGuest({ roomCode: parseChineseRoomCode('朱 上 岸 雪 存 违 户') });
+```
+
+编码关系（无损双向）：
+
+```
+16 个 Base32 字符  = 5 bit × 16 = 80 bit（版本 1 时高 3 bit 恒为 0）
+        ⇅
+7 个汉字           = 11 bit × 7  = 77 bit（2048⁷ = 2⁷⁷）
+```
+
+字符集是 **BIP39 简体中文词表**的 2048 个去重单字（标准、MIT、永不改动），因此不需要自己维护词库。
+
+| 工具 | 说明 |
+|---|---|
+| `toChineseRoomCode(code)` | 标准码 → 7 个字；版本号无法表示时抛 `INVALID_ROOM_CODE` |
+| `parseChineseRoomCode(input)` | 7 个字 → 标准码；含字数/表外字/CRC 校验，报错会指出是第几个字 |
+| `normalizeChineseRoomCode(input)` | 归一化（去标点空白、繁转简），非法返回 `null` |
+| `isChineseRoomCode(input)` | 布尔判断 |
+| `formatChineseRoomCode(code)` | 按字加空格便于展示 |
+| `ZH_ALPHABET` / `ZH_CODE_LENGTH` | 字表（2048 字）/ 字数（7） |
+
+容错范围：
+
+- 空格、换行、中英文标点、全角标点 → 忽略
+- **繁体字形自动折简**（`這→这`、`為→为`…共 773 对，由简/繁两张 BIP39 表逐位对齐自动生成）
+- 全角字符经 NFKC 折叠
+
+```text
+parseChineseRoomCode('的一是')            // 抛：中文房间码应为 7 个字，当前是 3 个字
+parseChineseRoomCode('朱上岸雪存违龘')     // 抛：第 7 个字「龘」不在房间码字符集中
+parseChineseRoomCode('朱上岸雪存违這')     // 抛：第 7 个字「這」不在字符集中，是不是想输「这」？
+```
+
+已知限制：
+
+1. **只支持编码版本 ≤ 1**。`2048⁷ = 2⁷⁷`，而版本 2 以上会用到第 78/79 位，7 个字装不下（届时需要改成 8 个字）。
+2. 词表是**单字**而非词，2048 个字摊在约 400 个拼音音节上，同音字很多。**适合复制/扫码/点选，不适合电话口述**。
+3. 继承房间码的 CRC-12 校验，而它并没有想象中强（实测数据，`test/room-code.test.mjs` 里有对应用例）：
+   - **随机抄错一个字**：拒绝率约 `99.7%`（漏检 ≈ `0.3%`，比理论值 `1/4096` 高，因为进位链会构成多项式倍式）
+   - **固定偏移式错误**（把某个字换成字符表里相邻的字）：在最敏感的位数上漏检率可达 `25%`
+   - 结论：CRC 只能挡住绝大多数误输，不能当强校验和用；抄错的极端情况会表现成「房间码合法但连不上房主」（`PEER_NOT_FOUND`），而不是「房间码错误」。
+
+---
+
+## 10. 协调协议（HTTP 接口）
+
+跑在隧道内，房主监听 `0.0.0.0:<coordPort>`，客人通过本地端口映射访问。
+协议常量：`COORD_PROTOCOL_VERSION = 1`、`COORD_TOKEN_HEADER = 'x-mct-token'`。
+
+### 10.1 `GET /v1/hello`（无需令牌）
+
+```json
+{ "app": "mc-tunnel", "protocol": 1, "probe": "a1b2c3d4e5f60718" }
+```
+
+客人用**恒定时间比较**（`timingSafeEqual`）核对 `probe`，确认对端确实是持相同房间码的房主。
+
+### 10.2 `GET /v1/session`（需 `x-mct-token`）
+
+```json
+{
+  "room": "2GJY-DYSK-8825-DZJY",
+  "mcPort": 25565,
+  "host": { "id": "6f1c...", "name": "Alice" },
+  "players": [
+    { "id": "6f1c...", "name": "Alice", "role": "host" },
+    { "id": "9ab3...", "name": "Bob",   "role": "guest" }
+  ]
+}
+```
+
+### 10.3 `POST /v1/players`（需 `x-mct-token`）
+
+请求体（≤ 4096 字节）：
+
+```json
+{ "id": "9ab3...", "name": "Bob" }
+```
+
+- `id` 必须匹配 `^[0-9a-z]{8,64}$/i`，`name` 非空且截断到 32 字符，否则 `400 { error: 'bad-player' }`
+- `id` 与房主冲突 → `409 { error: 'id-conflict' }`
+- 成功 → `200 { players: [...] }`（返回**全量**列表，客人据此刷新）
+
+### 10.4 其他
+
+| 情况 | 响应 |
+|---|---|
+| 缺令牌 / 令牌错误 | `401 { error: 'unauthorized' }` |
+| 未知路径 | `404 { error: 'not-found' }` |
+| 服务端内部异常 | `500 { error: 'internal' }` |
+
+### 10.5 手工调试
+
+房主本机（不经过隧道）：
+
+```bash
+curl -s http://127.0.0.1:25991/v1/hello
+curl -s -H "x-mct-token: <由房间码派生>" http://127.0.0.1:25991/v1/session
+```
+
+令牌由 `deriveRoomSecrets()` 生成，但它**没有从包入口导出**（`package.json` 的 `exports` 也只放开了 `.` 与 `./electron`，不能深引 `dist/...`）。手工调试时按下面的等价算法自行复算即可：
+
+```js
+// 复算 probe / token：房间码 → 80bit → 取 64bit 种子 → HMAC-SHA256 域分离
+import { createHmac } from 'node:crypto';
+
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const code = '2GJYDYSK8825DZJY';          // 去掉分隔符、转大写
+
+let value = 0n;
+for (const c of code) value = (value << 5n) | BigInt(ALPHABET.indexOf(c));
+
+const seed = Buffer.alloc(8);
+seed.writeBigUInt64BE((value >> 12n) & ((1n << 64n) - 1n), 0);   // 低 12 bit 是 CRC
+
+const derive = (label, n) =>
+  createHmac('sha256', seed).update(label, 'utf8').digest().subarray(0, n).toString('hex');
+
+console.log('probe:', derive('mc-tunnel/v1/probe', 8));
+console.log('token:', derive('mc-tunnel/v1/token', 16));
+```
+
+---
+
+## 11. 工具函数参考
+
+```ts
+import {
+  generateRoomCode, normalizeRoomCode, verifyRoomCode, parseRoomCode, ROOM_CODE_LENGTH,
+  normalizePassphrase, seedFromPassphrase, roomCodeFromPassphrase, passphraseStrength,
+  pingMc, isPortOpen,
+  resolveBinaries,
+  getDeviceId, defaultDataDir,
+  McLanScanner, McLanAnnouncer, MC_MULTICAST_GROUP, MC_MULTICAST_PORT,
+  natDifficulty, EasyTierNode,
+  CoordServer, CoordClient, COORD_PROTOCOL_VERSION, COORD_TOKEN_HEADER,
+  TunnelError, isTunnelError, VERSION,
+  TunnelHost, TunnelGuest,
+} from 'mc-tunnel';
+```
+
+| 函数 | 签名 | 说明 |
+|---|---|---|
+| `generateRoomCode` | `() => string` | CSPRNG 生成，格式 `XXXX-XXXX-XXXX-XXXX` |
+| `normalizeRoomCode` | `(input) => string \| null` | 见 §9.3 |
+| `verifyRoomCode` | `(input) => boolean` | 长度 + 字符集 + 版本 + CRC |
+| `parseRoomCode` | `(input) => RoomInfo` | 非法抛 `INVALID_ROOM_CODE` |
+| `pingMc` | `(port, host='127.0.0.1', timeoutMs=3000) => Promise<McStatus \| null>` | 自实现 1.7+ 状态查询（协议版本号 769），失败返回 `null` |
+| `isPortOpen` | `(port, host='127.0.0.1', timeoutMs=2000) => Promise<boolean>` | 仅 TCP 连通性 |
+| `resolveBinaries` | `(binDir?) => { core, cli }` | 找不到抛 `EASYTIER_NOT_FOUND` |
+| `getDeviceId` | `(dataDir?) => string` | 24 位 hex，落盘 `device-id`，按目录缓存 |
+| `defaultDataDir` | `() => string` | `<os.tmpdir()>/mc-tunnel` |
+| `natDifficulty` | `(local, remote) => NatDifficulty` | 纯展示 |
+| `normalizePassphrase` | `(text) => string` | NFKC + trim + 折叠空白 + 小写 |
+| `seedFromPassphrase` | `(text) => bigint` | 口令 → 64 bit 种子；空口令抛 `INVALID_PASSPHRASE` |
+| `roomCodeFromPassphrase` | `(text) => string` | 口令 → 标准房间码 |
+| `passphraseStrength` | `(text) => 'weak' \| 'fair' \| 'good'` | 粗略强度分档（供 UI 提示） |
+| `isTunnelError` | `(e, code?) => boolean` | 类型守卫 |
+| `VERSION` | `string` | 与 `package.json` 同步 |
+
+### 11.1 `McStatus`
+
+```ts
+interface McStatus {
+  version?: string;                     // 如 '1.20.4'
+  players?: { online: number; max: number };
+  description?: string;                 // 仅 string 形式的 description
+  latency: number;                      // 毫秒
+}
+```
+
+### 11.2 底层类（一般不用，但可用）
+
+`McLanScanner`：`new McLanScanner({ group?, port?, ttlMs=5000, filter? })`，`start()` / `stop()` / `list(): LanServer[]`，事件 `update`（**新增端口或被判定过期时**才发）、`error`。
+`ttlMs` 默认 5s：MC 客户端退出广播后，5 秒内从列表消失。
+
+`McLanAnnouncer`：`new McLanAnnouncer({ port, motd, group?, multicastPort?, intervalMs=1500, interfaces? })`，`start()` / `stop()`，`payload` getter 返回实际报文（排查用）。
+
+`EasyTierNode`：`EasyTierNode.start(config, binaries, readyTimeoutMs=20000)`，属性 `alive`，方法 `peers()` / `addPortForward('tcp'|'udp', local, remote)` / `logTail(n=20)` / `stop()`。
+
+`CoordServer` / `CoordClient`：协调服务与客户端，通常在测试里单独用。
+
+---
+
+## 12. Electron 集成
+
+### 12.1 为什么有单独的 `mc-tunnel/electron`
+
+主包不 `import electron`（避免硬依赖），`electron.ts` 只用 duck typing 访问 `app.getPath` / `app.on` / `app.quit`，所以在纯 Node、测试里也能 import。
+
+### 12.2 三个工具
+
+```ts
+import { electronDefaults, createHostInElectron, createGuestInElectron, manageSessions }
+  from 'mc-tunnel/electron';
+
+electronDefaults(app);
+// { dataDir: app.getPath('userData'),
+//   easyTier: { binDir: '<resourcesPath>/easytier' } }
+
+createHostInElectron(app, options);   // = createHost(合并默认 dataDir / binDir)
+createGuestInElectron(app, options);  // = createGuest(同上)
+manageSessions(app, host, guest);     // 绑到 before-quit，返回解绑函数
+```
+
+`manageSessions` 的行为：`before-quit` 时 `preventDefault()` → `Promise.allSettled` 关闭所有会话 → 再 `app.quit()`；重复触发有 `closing` 闸门保护。
+
+### 12.3 主进程完整示例
+
+```ts
+// src/main/index.ts
+import { app, BrowserWindow, ipcMain } from 'electron';
+import path from 'node:path';
+import {
+  createGuestInElectron,
+  createHostInElectron,
+  manageSessions,
+} from 'mc-tunnel/electron';
+import type { TunnelHost, TunnelGuest } from 'mc-tunnel';
+
+let host: TunnelHost | undefined;
+let guest: TunnelGuest | undefined;
+
+function send(channel: string, payload: unknown) {
+  for (const win of BrowserWindow.getAllWindows()) {
+    win.webContents.send(channel, payload);
+  }
+}
+
+ipcMain.handle('tunnel:host-start', async (_e, opts: { mcPort?: number }) => {
+  if (host) throw new Error('已在房间中');
+  host = await createHostInElectron(app, opts);
+  manageSessions(app, host);          // 应用退出时自动 close
+  host.on('state', (p) => send('tunnel:state', p));
+  host.on('players', (list) => send('tunnel:players', list));
+  host.on('mc-closed', () => send('tunnel:mc-closed', null));
+  host.on('error', (err) => send('tunnel:error', { code: err.code, message: err.message }));
+  return { roomCode: host.roomCode, mcPort: host.mcPort };
+});
+
+ipcMain.handle('tunnel:guest-join', async (_e, opts: { roomCode: string; playerName?: string }) => {
+  if (guest) throw new Error('已在房间中');
+  guest = await createGuestInElectron(app, opts);
+  manageSessions(app, guest);
+  guest.on('players', (list) => send('tunnel:players', list));
+  guest.on('server-status', (st) => send('tunnel:server-status', st));
+  return { address: guest.address, localPort: guest.localPort };
+});
+
+ipcMain.handle('tunnel:close', async () => {
+  await Promise.allSettled([host?.close(), guest?.close()]);
+  host = undefined;
+  guest = undefined;
+});
+```
+
+### 12.4 electron-builder 配置
+
+```jsonc
+{
+  "build": {
+    "asar": true,
+    "files": ["dist/**", "node_modules/**"],
+    "extraResources": [
+      { "from": "vendor/easytier", "to": "easytier" }
+    ]
+  }
+}
+```
+
+打包后实际路径：`<安装目录>/resources/easytier/easytier-core.exe`，正是 `electronDefaults()` 推导出来的 `binDir`。
+
+### 12.5 常见坑
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| 打包后报 `EASYTIER_NOT_FOUND` | 二进制被打进 asar，或 `extraResources` 的 `to` 不是 `easytier` |
+| 开发时能跑、打包后不行 | 开发下 `process.cwd()` 可能命中 `easytier/`，打包后只有 `resourcesPath` 那条有效 |
+| 关窗后残留 `easytier-core.exe` | 没调用 `manageSessions`，或用了 `app.exit()` 强退 |
+| 房间码在渲染进程丢失 | 通过 IPC 存到主进程；`roomCode` 只是内存值 |
+
+---
+
+## 13. 网络部署模式
+
+### 13.1 默认：公网 + 公共节点 + 只走 P2P
+
+不需要任何配置，双方能打洞即通。代价是依赖公共节点做信令（`-p` 未显式指定时由 EasyTier 默认节点承担）。
+
+### 13.2 局域网直连（完全离线，无需外网）
+
+```ts
+const IP = '192.168.1.7';  // 房机真实网卡 IP，不能用 127.0.0.1
+
+// 房主
+await createHost({ mcPort: 25565, listeners: ['tcp://0.0.0.0:11010'], peers: [`tcp://${IP}:11010`] });
+
+// 客人
+await createGuest({ roomCode, peers: [`tcp://${IP}:11010`] });
+```
+
+> `127.0.0.1` 会触发 EasyTier 的 `10049 AddrNotAvailable`（绑定本地地址时失败）。
+> 拿真实 IP 的办法：`os.networkInterfaces()` 里挑一个非 `internal` 的 IPv4；参考仓库里 `test/helpers.mjs` 的 `primaryIpv4()`。
+
+### 13.3 自建节点 / 需要中继（对称 NAT）
+
+```ts
+await createHost({
+  mcPort: 25565,
+  easyTier: {
+    p2pOnly: false,                                  // 允许中继
+    publicNodes: ['tcp://your-node.example.com:11010'],
+  },
+});
+
+await createGuest({
+  roomCode,
+  easyTier: { p2pOnly: false, publicNodes: ['tcp://your-node.example.com:11010'] },
+});
+```
+
+自建节点用 EasyTier 官方方式起（例如 `easytier-core -d --network-name <任意> --network-secret <任意> -l tcp://0.0.0.0:11010`），中继流量会走它。
+
+### 13.4 公司网 / 弱网
+
+- 只允许 TCP 出站：给双方都加 `publicNodes: ['tcp://...:11010']`，并考虑 `p2pOnly: false`。
+- UDP 被限速：优先考虑自建 TCP 节点。
+- MTU 异常（能握手但大包丢）：EasyTier 侧可加 `--mtu` 参数——本库未暴露，需要自行 `EasyTierNode` 或改 `buildArgs`。
+
+---
+
+## 14. 错误码与故障排查
+
+### 14.1 `TunnelErrorCode` 全表
+
+| code | 抛出位置 | 典型原因 | 处置 |
+|---|---|---|---|
+| `EASYTIER_NOT_FOUND` | `resolveBinaries` | 四个候选路径都没有 `core+cli` | 设 `binDir` / `MC_TUNNEL_EASYTIER`；检查文件名（Windows 要 `.exe`） |
+| `EASYTIER_EXITED` | `EasyTierNode.start` / 客人 `waitForHost` / 房主 watchdog（事件） | 二进制不完整、端口/参数不兼容、被杀 | 看 `error.message` 里附的 `logTail()`；手工跑一次 `easytier-core` 复现 |
+| `INVALID_ROOM_CODE` | `parseRoomCode` / `parseChineseRoomCode` | 房间码长度/字符/CRC/版本错；中文码还会指出第几个字有问题 | 先 `normalizeRoomCode` + `verifyRoomCode` 再传；中文码用 `isChineseRoomCode` 预检 |
+| `INVALID_PASSPHRASE` | `seedFromPassphrase` | 口令为空（或归一化后为空） | UI 侧要求非空，并配合 `passphraseStrength` 提示 |
+| `INVALID_OPTIONS` | `createHost` / `createGuest` | `roomCode` 与 `passphrase` 同时给（或客人都没给） | 二选一；客人必须提供其中之一 |
+| `MC_NOT_FOUND` | 房主 `scanMinecraft` | 30s 内没扫到广播 | 先开 MC 的「对局域网开放」；或直接传 `mcPort` |
+| `PEER_NOT_FOUND` | 客人 `waitForHost` | 90s 内没见到 `10.144.144.1` | 房间码是否一致；UDP 是否被墙；试 `p2pOnly:false` + 自建节点 |
+| `HANDSHAKE_FAILED` | 客人 `connectCoord` | probe 不匹配 / 返回端口非法 | 双方版本是否一致（协议版本 1）；房间码是否抄错 |
+| `PORT_FORWARD_FAILED` | `addPortForward` | CLI 3 次重试仍失败 | 端口被占用、EasyTier 权限不足；查 `logTail()` |
+| `TIMEOUT` | 客人 `waitForLocalMinecraft` / `EasyTierNode.start` | 映射建好但连不到 MC；或 EasyTier 20s 未就绪 | 确认房主 MC 真的在跑且未被防火墙拦 |
+| `CLOSED` | `delay()` | 会话已被 `close()`，正在等待的步骤被唤醒 | 正常收尾，不必上报用户 |
+| `UNKNOWN` | 客人初始化兜底 | 非 `TunnelError` 的异常 | 看 `error.cause` |
+| `EASYTIER_CLI_FAILED` | —（当前未使用） | 预留 | — |
+| `COORD_PORT_BUSY` | —（当前未使用） | 实际抛的是普通 `Error('Coord port 25991 is already in use')` | 见 §14.3 |
+
+### 14.2 `isTunnelError` 用法
+
+```ts
+import { isTunnelError } from 'mc-tunnel';
+
+try {
+  guest = await createGuest({ roomCode });
+} catch (error) {
+  if (isTunnelError(error, 'PEER_NOT_FOUND')) {
+    ui.hint('对方还没开房间，或网络打洞失败');
+  } else if (isTunnelError(error)) {
+    ui.hint(`联机失败（${error.code}）: ${error.message}`);
+  } else {
+    throw error;
+  }
+}
+```
+
+### 14.3 故障排查对照表
+
+| 症状 | 排查步骤 |
+|---|---|
+| `Coord port 25991 is already in use` | 本机已有房主在跑，或别的程序占了 25991。`netstat -ano \| findstr 25991`（Windows）/ `lsof -i:25991` |
+| 房主卡在 `scanning` 直到 `MC_NOT_FOUND` | ①MC 是否已「对局域网开放」②是否开了 VPN/虚拟网卡导致多播走错网卡（关掉）③直接传 `mcPort` 绕过 |
+| 客人 `PEER_NOT_FOUND` | ①房间码两端一致？②双方网络能否出 UDP？③临时 `p2pOnly:false` 验证是否对称 NAT |
+| 客人 `HANDSHAKE_FAILED` | 房间码抄错（CRC 会拦住大部分）、双方包版本不同、隧道没通（probe 一直不匹配） |
+| `ready` 但游戏里看不到世界 | ①`localPort` 是否被防火墙拦（UDP 广播是出站，一般不用放行）②MC 版本与「局域网世界」是否同一网段 ③某些杀软拦多播 |
+| 游戏里能看到但进不去 | 房主 MC 端口之外的服务（如 SimpleVoiceChat 的 UDP）没映射；用 `preferredLocalPort` 固定同号端口 |
+| 玩家列表不更新 | 客人是否 `ready`（心跳只在 ready 后每 5s 一次）；`players` 事件是否被节流 |
+| `mc-closed` 误报 | 房主 MC 端口被别的程序短暂占用或 MC 卡顿；3 次（15s）连续失败才报，可据此放宽 |
+| 关闭很慢（最多 3s） | `EasyTierNode.stop()` 会等进程退出最多 3s，属正常 |
+| 进程退出后仍有 `easytier-core` | 宿主被强杀（SIGKILL / 任务管理器）时兜底钩子无效；下次启动可先杀同名进程 |
+
+### 14.4 打开 EasyTier 日志
+
+```ts
+try {
+  await createGuest({ roomCode });
+} catch (e) {
+  // EASYTIER_EXITED / TIMEOUT 的 message 已附最后 20 行日志
+  console.error(e.message);
+}
+```
+
+若需更多，临时用 `EasyTierNode` 自己起一个节点，观察 `logTail(200)`。
+
+---
+
+## 15. 生命周期与进程管理
+
+### 15.1 子进程归属
+
+- 每个会话（房主/客人）**各起一个** `easytier-core`。
+- `easytier-cli` 是**一次性**调用（`execFile`，8s / 10s 超时），不是常驻进程。
+- `EasyTierNode` 注册了 `process.once('exit', killer)`，宿主正常退出时杀子进程；子进程自己退出时移除该钩子。
+
+### 15.2 `close()` 做了什么
+
+房主：置 `closed` → `abort` 唤醒所有 `delay` → 清 watchdog → 停扫描器 → `CoordServer.stop()`（含 `closeAllConnections`）→ `EasyTierNode.stop()`（最多等 3s）→ `state='closed'`。
+
+客人：置 `closed` → `abort` → 清心跳 → 停广播 → `EasyTierNode.stop()` → `state='closed'`。
+
+两者都**幂等**，重复调用立即返回。
+
+### 15.3 推荐的生命周期写法
+
+```ts
+const host = await createHost({ mcPort: 25565 });
+try {
+  // ... 业务
+} finally {
+  await host.close();
+}
+```
+
+Electron 里用 `manageSessions(app, host)`；CLI 里监听 `SIGINT` / `SIGTERM`：
+
+```ts
+for (const sig of ['SIGINT', 'SIGTERM'] as const) {
+  process.once(sig, () => { void session.close().finally(() => process.exit(0)); });
+}
+```
+
+### 15.4 定时器不拖住进程
+
+所有内部定时器（watchdog、心跳、广播、prune、`delay`）都调了 `unref()`，因此**即使忘了 close，Node 进程也能正常退出**；但子进程仍需 close 才干净。
+
+---
+
+## 16. 安全模型
+
+| 面 | 做法 |
+|---|---|
+| 房间码 | 64 bit CSPRNG 种子 + 12 bit CRC；版本字段预留升级 |
+| 网络凭据 | 网络名/密钥由种子 HMAC 派生，房间码不含明文 |
+| 协调鉴权 | `x-mct-token`，`timingSafeEqual` 恒定时间比较，防时序侧信道 |
+| 对端确认 | `/v1/hello` 的 probe，同样恒定时间比较 |
+| 最小暴露 | 房主 TCP 白名单只放行 `coordPort` + `mcPort`，UDP 白名单只放行 `mcPort`；客人白名单为 `0` |
+| 输入校验 | `/v1/players`：`id` 正则、`name` 截断 32、body ≤ 4KB；`id` 与房主冲突返回 409 |
+| 设备标识 | 本地随机 24 位 hex，落盘 `device-id`，无硬件指纹 |
+| 无 TUN | `--no-tun`，不创建虚拟网卡，不改变系统路由 |
+
+**注意**：
+
+- 房间码 = 入网凭据，泄露即可被加入；不要贴在公开群组。
+- 协调服务监听 `0.0.0.0`，但在 `--no-tun` 下只有虚拟网段内的节点可达；同时受 EasyTier 白名单限制。
+- 本包不做内容审计，Minecraft 服务端自身的防护（正版验证、白名单）请自行开启。
+
+---
+
+## 17. 兼容性 / 已知限制
+
+| # | 限制 | 影响 | 规避 |
+|---|---|---|---|
+| 1 | **客人协调端口硬编码 `25991`**（`guest.ts` 里直接用 `DEFAULT_COORD_PORT`，不读选项） | 房主改 `coordPort` 后客人必然 `HANDSHAKE_FAILED` | 不要改 `coordPort`，或 fork 后让客人也读该值 |
+| 2 | 同一台机器只能开一个房主 | 第二实例报 `Coord port 25991 is already in use`（普通 `Error`，非 `TunnelError`） | 虚拟机 / 容器隔离 |
+| 3 | `peers` 不能写 `127.0.0.1` | EasyTier 报 `10049 AddrNotAvailable` | 用真实网卡 IP |
+| 4 | 只支持 IPv4 多播 | IPv6-only 环境扫描/广播失效 | 传 `mcPort` 绕过扫描；广播仍需 IPv4 网卡 |
+| 5 | 房主自动发现依赖同机多播 | MC 在另一台机器上时扫不到 | 直接传 `mcPort` |
+| 6 | 单机同时跑房主+客人（测试）时靠 `motd` 过滤自身广播 | 若把客人 `motd` 改成与 MC 真实 MOTD 相同，可能误判 | 保持默认 MOTD 或自定义独特字符串 |
+| 7 | 对称 NAT 双端 | 默认 `p2pOnly: true` 下打不通 | `p2pOnly: false` + 自建节点 |
+| 8 | 状态查询可能被插件屏蔽 | 客人拿不到 `server-status` | 已内置 `isPortOpen` 兜底，仅影响展示 |
+| 9 | MC 端口变化（重开存档换端口） | watchdog 会一直报 `mc-closed` | 重新 `createHost` |
+| 10 | 无 TLS | 协调协议是明文 HTTP，但跑在加密隧道（EasyTier）内 | 无需处理 |
+| 11 | `HostOptions.coordPort` 等少数选项未在文档化的 `GuestOptions` 对齐 | 见 #1 | — |
+| 12 | `error` 事件仅房主 EasyTier 退出时触发 | 别指望靠 `on('error')` 捕获初始化失败 | 用 `try/catch` 包 `createHost` / `createGuest` |
+| 13 | CRC-12（`0x80F`）对进位链式错误存在系统性漏检 | 随机单字符误输拒绝率约 99.7%；**固定偏移**在最敏感位数上漏检可达 25% | 只当「大概率」发现误输；关键流程可在 UI 上做二次确认（如要求重复输入） |
+| 14 | 中文码只支持编码版本 ≤ 1 | 将来升版本后 7 个字装不下 | 届时改 8 个字；现在遇到会明确抛 `INVALID_ROOM_CODE` |
+| 15 | 口令模式强度取决于口令 | 弱口令等于公开房间 | UI 用 `passphraseStrength` 提示，或直接用随机房间码 |
+
+---
+
+## 18. 性能与资源占用
+
+| 指标 | 实测/设计值 |
+|---|---|
+| 常驻进程 | 每会话 1 个 `easytier-core`（空载内存约 20–40 MB，视版本） |
+| CPU | 空载接近 0；`easytier-cli` 轮询只在启动阶段（每 500ms / 1s） |
+| 启动耗时 | 房主：扫描决定（立即传 `mcPort` 时约 1–3s）；客人：通常 3–10s，最坏 `timeoutMs` |
+| 心跳/广播流量 | 客人：HTTP 心跳每 5s（<200B）+ 多播广播每 1.5s（~60B/网卡） |
+| 定时器 | 全部 `unref()`，不阻止进程退出 |
+| 端口映射 | 房主 1 个协调服务；客人 2 个（协调临时 + MC 双协议） |
+
+---
+
+## 19. 附录：类型与默认值速查
+
+### 19.1 默认值总表
+
+| 常量 | 值 |
+|---|---|
+| `HOST_VIRTUAL_IP` | `10.144.144.1` |
+| `DEFAULT_COORD_PORT` | `25991` |
+| `DEFAULT_MOTD` | `§b§lMC Tunnel 联机房间（请保持程序运行）` |
+| `HEARTBEAT_INTERVAL_MS` | `5000` |
+| `MC_WATCH_INTERVAL_MS` | `5000` |
+| `MC_MULTICAST_GROUP` | `224.0.2.60` |
+| `MC_MULTICAST_PORT` | `4445` |
+| 玩家超时 | `12000`（`PLAYER_TIMEOUT_MS`，内部） |
+| EasyTier 就绪超时 | `20000` |
+| 端口映射重试 | 3 次，间隔 400/800/1200ms |
+| 停止等待 | 3000ms |
+| `ROOM_CODE_LENGTH` | `19` |
+| `ZH_CODE_LENGTH`（`mc-tunnel/zh`） | `7` |
+| `ZH_ALPHABET`（`mc-tunnel/zh`） | BIP39 简体中文 2048 字 |
+
+### 19.2 类型定义
+
+```ts
+type Phase = 'idle' | 'scanning' | 'starting-tunnel' | 'waiting-peer'
+           | 'connecting' | 'ready' | 'closed' | 'error';
+
+type NatDifficulty = 'unknown' | 'easiest' | 'simple' | 'medium' | 'tough';
+
+interface Player { id: string; name: string; role: 'host' | 'guest'; }
+
+interface RoomInfo { code: string; networkName: string; networkSecret: string; }
+
+interface McStatus { version?: string; players?: { online: number; max: number }; description?: string; latency: number; }
+
+interface EasyTierOptions { binDir?: string; publicNodes?: string[]; p2pOnly?: boolean; }
+
+interface HostOptions {
+  roomCode?: string; passphrase?: string;            // 二选一
+  mcPort?: number; playerName?: string; motd?: string;
+  coordPort?: number; listeners?: string[]; peers?: string[];
+  scanTimeoutMs?: number; dataDir?: string; easyTier?: EasyTierOptions;
+}
+
+interface GuestOptions {
+  roomCode?: string; passphrase?: string;            // 二选一，必须提供一个
+  playerName?: string; motd?: string;
+  preferredLocalPort?: number; peers?: string[]; timeoutMs?: number;
+  dataDir?: string; easyTier?: EasyTierOptions;
+}
+```
+
+### 19.3 返回值一览
+
+```ts
+createHost(opts?) → Promise<TunnelHost>
+  .roomCode .mcPort .coordPort .virtualIp .phase
+  .players() .close()
+  on: 'state' | 'players' | 'player-join' | 'player-leave' | 'mc-closed' | 'error'
+
+createGuest(opts) → Promise<TunnelGuest>
+  .roomCode .mcPort .localPort .address .natDifficulty .phase
+  .hostPlayers() .close()
+  on: 'state' | 'players' | 'server-status' | 'error'
+```
+
+### 19.4 一页速记
+
+```ts
+// 房主
+const host = await createHost({ mcPort: 25565, playerName: 'Alice' });
+share(host.roomCode);
+
+// 客人
+const guest = await createGuest({ roomCode: code, playerName: 'Bob' });
+connectMc(guest.address);            // 127.0.0.1:xxxxx
+
+// 收尾
+await guest.close();
+await host.close();
+```
+
+---
+
+**版本**：本文档对应 `mc-tunnel@0.2.0`（`VERSION` 常量同步）。
+若你改了 `src/constants.ts` 里的默认端口/间隔，请同步更新本文档对应的表格。