# 两台设备互连：超详细操作手册

> 这份手册假设你**没做过类似的事**，所以每一步都写清三件事：
> **① 在哪台电脑上做 → ② 点什么 / 敲什么 → ③ 正常应该看到什么**。
> 凡是「应该看到什么」对不上的地方，都指向 [D 部分：出问题怎么查](#d-部分出问题怎么查)。
>
> 只要一台电脑，就能先把整条链路跑通（[A 部分](#a-部分一台电脑先把整条链路跑通)）；
> 等你有了第二台电脑，再做 [B 部分](#b-部分把第二台真电脑加进来)。

## 目录

- [先确认你在哪一档](#先确认你在哪一档)
- [A 部分：一台电脑，先把整条链路跑通](#a-部分一台电脑先把整条链路跑通)
  - [A0. 先认 4 个词](#a0-先认-4-个词)
  - [A1. 起「团队服务器」（双击一个文件）](#a1-起团队服务器双击一个文件)
  - [A2. 把地址和邀请码填进面板](#a2-把地址和邀请码填进面板)
  - [A3. 确认成功](#a3-确认成功)
  - [A4. 想看看「两台设备」是什么样（可选）](#a4-想看看两台设备是什么样可选)
- [B 部分：把第二台**真**电脑加进来](#b-部分把第二台真电脑加进来)
- [C 部分：两台电脑不在同一个网络](#c-部分两台电脑不在同一个网络)
- [D 部分：出问题怎么查](#d-部分出问题怎么查)
- [附录 1：一张纸命令速查](#附录-1一张纸命令速查)
- [附录 2：文件在哪、会不会泄露](#附录-2文件在哪会不会泄露)
- [附录 3：退出 / 重置 / 卸载](#附录-3退出--重置--卸载)

---

## 先确认你在哪一档

| 你的情况 | 要做的部分 | 大概耗时 |
|---|---|---|
| **现在只有一台电脑** | [A 部分](#a-部分一台电脑先把整条链路跑通)，做完就能看到面板里出现团队和在线人数 | 5 分钟 |
| 有两台电脑，在同一个 Wi-Fi / 同一个办公室 | A 部分 + [B 部分](#b-部分把第二台真电脑加进来) | 15 分钟 |
| 两台电脑不在一起（异地） | A 部分 + B 部分 + [C 部分](#c-部分两台电脑不在同一个网络) | 25 分钟 |

> **「A 机」「B 机」是本手册的叫法**：A 机 = 跑团队服务器的那台（建议用常开的那台），
> B 机 = 加入的那台。只有一台电脑时，这台机器同时扮演 A 机的角色。

---

## A 部分：一台电脑，先把整条链路跑通

### A0. 先认 4 个词

| 词 | 是什么 | 在哪能看到 |
|---|---|---|
| **团队服务器**（hub） | 一个**在 A 机后台跑着的小程序**，负责把各台机器的用量汇总到一起。它不是网页，也没有界面，就是一个黑窗口 | 双击脚本后弹出的那个黑色窗口 |
| **团队服务器地址** | 一个形如 `http://192.168.1.10:7801` 的网址，就是黑窗口里 `👉` 那一行 | 黑窗口横幅 |
| **邀请码** | 8 位字母数字，例如 `UBQ8X853`。作用相当于进团队的口令 | 黑窗口横幅「邀请码」那一行 |
| **面板** | DSH 界面左侧边栏最底部的那个小方块 —— 就是你要操作的地方 | 见 [A2](#a2-把地址和邀请码填进面板) |

记住这条分工：**黑窗口负责“收”，面板负责“填”。** 两者缺一不可。

---

### A1. 起「团队服务器」（双击一个文件）

**在哪台电脑上做**：就你现在这台（以后有了第二台，也永远是这一台做）。

**做法一（推荐，最简单）**

1. 打开文件资源管理器，地址栏粘贴这个路径后回车：
   ```
   D:\Project\DSHplugins\teamplugin\scripts
   ```
   > 如果你的仓库放在别的地方，就换成 `<仓库目录>\scripts`。
2. 在文件列表里找到 **`start-hub-public`**（类型是「Windows 批处理文件」），**双击它**。
3. （第一次可能弹）Windows 防火墙提示 → 勾上**专用网络** → 点「**允许访问**」。
   这是让别的机器以后能连进来，只有第一次会问。

**做法二（如果双击一闪而过、什么都没看清）**

一闪而过通常意味着**报错了但你来不及看**。改成在终端里跑，报错就会留在屏幕上：

1. 点开始菜单 → 搜 `PowerShell` → 打开「Windows PowerShell」；
2. 粘贴下面两行，每行回车：
   ```powershell
   cd 'D:\Project\DSHplugins\teamplugin'
   .\scripts\start-hub-public.cmd
   ```
   > 注意前面那个 `.\` 不能省 —— PowerShell 不会从当前目录直接找程序。少写会报
   > `无法将“scripts\start-hub-public.cmd”项识别为 cmdlet…`，那不是脚本坏了。

**正常应该看到什么**

会弹出一个黑窗口，内容大致如下（数字和邀请码每台机器不同）：

```
  ┌──────────────────────────────────────────────────────────────┐
  │        dsh-team-panel 团队服务器已启动                        │
  └──────────────────────────────────────────────────────────────┘
   监听地址      http://0.0.0.0:7801
   数据文件      D:\Project\DSHplugins\teamplugin\data\team-hub-data.json

   团队名称      我的团队
   邀请码        UBQ8X853      <-- 给队友这个
   管理密钥      dc07cb0b0825f25168a62b18adcbc268
   管理页面      http://127.0.0.1:7801/admin?key=dc07cb...

   局域网地址    http://10.51.3.25:7801  (以太网)
   Tailscale     http://100.77.74.56:7801  (Tailscale)

   👉 队友「团队服务器地址」填：http://10.51.3.25:7801
```

**现在做两件事**：

1. **把「邀请码」抄下来**（8 位，字母数字，不会含 `0 O 1 I L` 这些容易看错的字符）；
2. **记住 `👉` 那一行的地址**（同一台电脑自己连，用 `http://127.0.0.1:7801` 也行）。

> ⚠️ **这个黑窗口不能关。** 关掉 = 团队服务器停机，面板立刻显示离线。
> 用完想停就按 `Ctrl+C`，或在窗口里直接关。
>
> 想让它在后台常驻、开机自动起：用**管理员**窗口跑一次
> `.\scripts\install-autostart.cmd 7801`；装完就没有黑窗口了，邀请码改从
> `node scripts\hub-info.mjs` 查。详见 [附录 1](#附录-1一张纸命令速查)。

---

### A2. 把地址和邀请码填进面板

**在哪台电脑上做**：打开你的 DSH 界面（就是 `http://127.0.0.1:43120` 那个界面）。

**第 1 步：找到面板**

看界面**左侧边栏的最下面**，在「**设置**」这一行的**正上方**，有一小块东西：

```
   ┌─────────────────────────────┐
   │  (谷)   —            ( ⊕ )  │   ← 折叠状态：左边是峰/谷圆标，右边是 ⊕
   │  ●  总 Token 0    ¥0.00     │
   └─────────────────────────────┘
              ─────────────
                 设置              ← DSH 自己的「设置」行，面板就在它上面
```

找不到它，先排除这三种情况（都是正常的，不是坏了）：

| 情况 | 怎么办 |
|---|---|
| 左侧边栏被收成了**一条窄窄的图标轨**（宽约 56px） | 把侧栏**拉宽**，面板就会回来 |
| 你正开着 DSH 的**全局面板**（设置、定时任务等） | 关掉它，面板是有意隐藏的 |
| 整个侧栏底部什么都没有 | 插件还没加载 → 见 [D 部分](#d-部分出问题怎么查) 第 1 条 |

**第 2 步：展开面板**

点折叠条**右侧那个 `⊕`**。面板展开，你会看到从上到下三块：
①「选择要监测的 DSH 项目」、中间成员列表、②「加入团队」。

**第 3 步：打开加入表单**

看面板标题那一行：`未加入团队` 右边有两个按钮 ——「**同步**」和「**设置**」。
点「**设置**」（点完它的文字会变成「**收起设置**」）。

下面会出现「**② 加入团队（可选）**」，里面有三个输入框和一个按钮：

| 输入框 | 填什么 |
|---|---|
| 我的 DSH 名字 | 给**这台电脑**起个名，例如 `小明的 DSH`、`服务器`。全队成员列表里显示的就是它 |
| 团队服务器地址 | 就这一台电脑自己连：`http://127.0.0.1:7801`；<br>以后有第二台：填黑窗口里 `👉` 那一行（例如 `http://10.51.3.25:7801`） |
| 邀请码 | 黑窗口里抄下来的那 8 位，例如 `UBQ8X853`（大小写都行） |

**第 4 步：点「加入团队」**

**正常应该看到什么**（三个变化同时发生）：

1. 面板标题从 `未加入团队` 变成**团队名**（例如 `我的团队`）；
2. 标题行右边出现 `在线 1/1 人 · N 个项目 · 更新于 21:31:05`；
3. 面板底部右下角出现 `在线 1/1`。

**如果没成功**，表单下方会出一行红色提示，对照处理：

| 提示 | 意思 | 怎么办 |
|---|---|---|
| `请先填写团队服务器地址` | 地址框是空的 | 填 `http://127.0.0.1:7801` |
| 地址**刚填完就自己变空**了 | 旧版面板的轮询把没保存的输入清掉了（见 [troubleshooting](troubleshooting.md)） | 临时：每填一个框就点一次「保存本机设置」；彻底：换成修复版仓库并 F5 |
| `邀请码不正确` | 8 位抄错了 / 用了旧数据文件的码 | 回黑窗口重抄；黑窗口关了就用 `node scripts\hub-info.mjs` 查 |
| `连不上…` / 一直转圈 | 黑窗口被关了，或端口不对 | 回 [A1](#a1-起团队服务器双击一个文件) 重新双击，确认窗口还在 |

---

### A3. 确认成功

按顺序看这三处，全对就是通了：

1. **面板标题** = 你的团队名，右边有 `在线 1/1 人…`；
2. **面板底部**「总 Token」下面的数字，和你这台机器实际用掉的量对得上
   （注意：**统计从你点「开始监测」那一刻起算**，之前的历史用量不追溯）；
3. **打开管理页面**（浏览器新标签，粘贴黑窗口里「管理页面」那一整行，别漏 `?key=`）：
   能看到团队名、邀请码、以及一名成员。这就是服务器侧的账本。

> 面板最上面那块「**① 选择要监测的 DSH 项目**」是另一件事：
> **没选项目就一个 token 都不统计**。下拉选一个项目 → 点「**开始监测**」。
> 下拉里没有你要的项目时，点下面的「**手动填写目录路径…**」，贴绝对路径 →「使用」。

---

### A4. 想看看「两台设备」是什么样（可选）

只有一台电脑，也想亲眼看到「在线 2/2、两名成员」，可以用仓库里的**模拟队友**工具 ——
它用**和真插件完全相同的协议**冒充第二台设备（数字是造出来的，只用来验证连接与显示）。

1. 打开 `D:\Project\DSHplugins\teamplugin\scripts`；
2. 双击 **`demo-teammate`**（Windows 批处理文件）；
3. 黑窗口提示 `Invite code:` → 粘贴那 8 位邀请码 → **回车**。

黑窗口会每 3 秒打印一行：

```
[21:35:02] 已上报 12,300 tokens   · 服务器现在：2/2 在线 · 1 个项目 · 全队 24,300 tokens
```

同时回头看 DSH 面板：**成员列表多出一行「模拟队友」，「在线」变成 `2/2`，总 Token 变大。**

按 `Ctrl+C` 停止 → 这个模拟成员会自动从团队里移除，面板回落到 `1/1`。

> 想换名字/项目/上报速度，也可以直接用命令行跑：
> `node scripts\fake-device.mjs http://127.0.0.1:7801 <邀请码> --name 小明的 DSH --project 演示项目 --interval 3`
> 加 `--keep` 则退出时**保留**成员（留在列表里显示为离线）。

---

## B 部分：把第二台**真**电脑加进来

B 机只需要做三件事：**装插件 → 选项目 → 填地址加入**。团队服务器（黑窗口）始终只在 A 机上跑。

### B1. 在第二台电脑上装插件

**前提**：第二台电脑上也有一份**这个仓库的目录**（整个文件夹复制过去即可）。

| 要求 | 为什么 |
|---|---|
| 路径**纯 ASCII**、别放桌面/下载目录 | 中文路径会让控制台显示成乱码，容易被误判成“配置坏了” |
| 放好之后**别再移动或改名** | 插件是用 `link:<绝对路径>` 装的，路径一变就失效 |

在**第二台电脑**上打开 **DSH Desktop 自带的终端**（`dsh` 这个命令只有它里面有），逐条执行：

```powershell
# 1) 装插件（<仓库目录> 换成第二台上的实际路径）
dsh plugin --profile desktop add link:<仓库目录>

# 2) 验证 —— 看配置里有没有 dsh-team-panel 这一项
dsh --profile desktop --dump-config | Select-String dsh-team-panel

# 3) 完全退出 DSH Desktop，再重新打开；然后按 Ctrl+F5 强刷界面
```

**正常应该看到什么**：第 2 条会打印出包含 `dsh-team-panel` 的那一行；
重启后第二台的侧栏底部出现同一个面板。没有的话 → [D 部分](#d-部分出问题怎么查) 第 1 条。

> 当前 GUI（`127.0.0.1:43120`）属于 **`desktop`** profile。装进 `web` 是给独立
> `dsh web` 服务器的另一套插件栈，装了在界面里也**不会**出现。

### B2. 在第二台上选一个要监测的项目

面板会自动展开并提示「还没选项目」→ 下拉选一个项目 → 点「**开始监测**」。
**不选就不统计**，队友那边会一直显示「未选择监测项目」。

### B3. 在第二台上填地址 + 邀请码

第二台上重复 [A2](#a2-把地址和邀请码填进面板) 的第 1~4 步，**地址要改**：

| 两台电脑的位置 | 「团队服务器地址」填 |
|---|---|
| 同一个 Wi-Fi / 局域网 | A 机黑窗口里 `局域网地址` 那一行，例如 `http://10.51.3.25:7801` |
| 都在同一个 Tailscale 网络里 | `Tailscale` 那一行，例如 `http://100.77.74.56:7801` |

> ⚠️ **在 B 机上千万别填 `127.0.0.1`** —— 那指的是 B 机自己，永远连不上 A 机。

**还差一步（只做一次）**：在 **A 机**上用**管理员**身份放行端口：

```powershell
# A 机，管理员 PowerShell
cd 'D:\Project\DSHplugins\teamplugin'
.\scripts\allow-firewall.cmd 7801
```

不做这步，B 机大概率表现为「连不上」。

**别忘了 A 机自己也要加入**：黑窗口跑在 A 机上 ≠ A 机已经是成员。
A 机也要按 [A2](#a2-把地址和邀请码填进面板) 加入一次（地址填 `http://127.0.0.1:7801` 最稳）。
漏了这步，团队里永远只有 1 台。

### B4. 验收：四条判据

| # | 在哪看 | 应该看到 |
|---|---|---|
| 1 | A 机跑 `node scripts\hub-info.mjs` | 成员列表里**两名成员**，前面都是 `🟢` |
| 2 | A、B 两台的 DSH 面板 | 「总 Token」是**同一个数**，`在线 2/2` |
| 3 | 在 B 机上就所选项目跑一段对话 | **20 秒内** A 机面板上的数字跟着涨（心跳间隔 20 秒） |
| 4 | B 机浏览器打开 `http://10.51.3.25:7801/api/health` | 能看到一小段 JSON |

想先单独确认网络这一层，可以在 **B 机**上跑连通性自检：

```powershell
# B 机，仓库目录里
node scripts\netcheck.mjs http://10.51.3.25:7801 <邀请码>
```

全绿时会打印 **`这个地址从本机可用 ✅`**，再回面板填地址。

---

## C 部分：两台电脑不在同一个网络

插件不解决连通性，它只要求一件事：**两台电脑都能访问到同一个地址**。
所以只要把「A 机的 7801 端口」变成 B 机能访问的地址，**插件侧不用改任何配置**。

### 推荐：Tailscale（地址永久固定，免费）

装一次，两台电脑在同一个虚拟局域网里，像在同一个办公室一样互联。

1. **两台电脑都装** Tailscale 并登录**同一个账号**：<https://tailscale.com/download/windows>
2. **A 机**：让团队服务器重新读取网卡 —— 管理员窗口跑
   ```powershell
   schtasks /end /tn "dsh-team-panel hub" ; schtasks /run /tn "dsh-team-panel hub"
   node scripts\hub-info.mjs
   ```
   （如果你还在用黑窗口模式：关掉黑窗口，重新双击 `start-hub-public.cmd` 也一样。）
3. **在 `hub-info.mjs` 的输出里找 `100.x.x.x` 那一行**，例如 `http://100.77.74.56:7801` —— 这就是 B 机要填的地址。
4. **B 机**：先自检 `node scripts\netcheck.mjs http://100.77.74.56:7801 <邀请码>`，
   打印 `这个地址从本机可用 ✅` 后，填进面板 → 加入团队。

> · 免费版额度：**最多 6 个用户、设备数量不限**。
> · A 机（团队服务器）建议**常开**，否则队友看到的一直是离线。
> · 有人死活装不上 Tailscale 时，可以在 A 机另开一个临时隧道只给他用：
>   `cloudflared tunnel --url http://127.0.0.1:7801`（地址会变，只适合应急）。

其它路线（公网 VPS + HTTPS、Cloudflare 命名隧道）的对比与中国大陆特有的坑
→ [networking.md](networking.md)。

---

## D 部分：出问题怎么查

### 第 1 条：面板根本看不到

按顺序排（这是最常见的三个原因）：

1. **插件装对 profile 了吗？** 当前 GUI 属于 `desktop`。在 DSH Desktop 自带终端里跑：
   ```powershell
   dsh --profile desktop --dump-config | Select-String dsh-team-panel
   ```
   没有输出 = 没装成功 → 回到 [B1](#b1-在第二台电脑上装插件)。
2. **重启过 DSH Desktop 吗？** 宿主端**不会热加载**，装完必须完全退出再打开。
3. **强刷过前端吗？** 重启后按 `Ctrl+F5`。

顺带两个“看着像坏了其实没坏”的情况：左侧边栏收窄成图标轨（把侧栏拉宽）、
DSH 全局面板打开着（关掉它）。

### 第 2 条：按症状查

| 症状 | 多半是 | 怎么修 |
|---|---|---|
| 双击 `start-hub-public.cmd` 一闪而过 | 报错了但没看清 | 用 [A1 做法二](#a1-起团队服务器双击一个文件) 在终端里跑，看报错 |
| 终端里报 `node 不是内部或外部命令` | 这台机器没装 Node / 没进 PATH | 装 Node.js ≥ 20，重开终端 |
| `scripts\start-hub-public.cmd` 无法识别 | PowerShell 少了 `.\` 前缀 | 写成 `.\scripts\start-hub-public.cmd` |
| 面板加入后马上「离线」 | 黑窗口被关了 / 电脑休眠了 | 重新双击脚本；确认黑窗口一直在 |
| B 机连不上，`netcheck` 报连不上 | hub 只监听 `127.0.0.1`（最常见） | A 机改用 `start-hub-public.cmd`（监听 `0.0.0.0`） |
| 同上 | A 机防火墙没放行（第二常见） | A 机管理员跑 `.\scripts\allow-firewall.cmd 7801` |
| 同上 | 两台不在同一个网络 | 连同一个 Wi-Fi，或走 [C 部分 Tailscale](#c-部分两台电脑不在同一个网络) |
| B 机浏览器打不开地址、面板报错 | 地址填成了 `127.0.0.1` | 改成 A 机的局域网 / Tailscale 地址 |
| `邀请码不正确` | 抄错 / 用了旧数据文件的码 | 看黑窗口，或 A 机跑 `node scripts\hub-info.mjs` |
| 加入成功但 Token 一直是 0 | **没选监测项目**，或选完没有新对话 | 面板 →「开始监测」；统计不追溯历史用量 |
| 队友那行显示「未选择监测项目」 | 对方点了「取消监测」 | 对方重新选项目 →「开始监测」，最多 20 秒后更新 |
| 「最后消耗」时间很旧 | 对方 DSH 关着（在线阈值 70 秒） | 预期行为，不用管 |
| A 机换了机器 / 换了端口，队友掉线 | 队友存的是旧地址 | 队友在「设置」里改地址重新加入 |
| 自己拼命令看到中文乱码 | 控制台按 GBK 显示 UTF-8 输出 | 先执行 `chcp 65001`；文件本身没问题 |

更多条目（提示词/乱码/自启后看不到邀请码等）→ [troubleshooting.md](troubleshooting.md)。

---

## 附录 1：一张纸命令速查

在**仓库目录**里执行（`cd 'D:\Project\DSHplugins\teamplugin'` 之后）：

| 想做什么 | 命令 / 操作 |
|---|---|
| 起团队服务器（能看横幅，最简单） | 双击 `scripts\start-hub-public.cmd` |
| 起团队服务器（前台，看报错用） | `.\scripts\start-hub-public.cmd 7801` |
| 装成开机自启 + 崩溃自动重启 | 管理员：`.\scripts\install-autostart.cmd 7801` |
| 放行入站端口 / 撤销 | 管理员：`.\scripts\allow-firewall.cmd 7801` / `... remove` |
| 查邀请码、管理密钥、推荐地址 | `node scripts\hub-info.mjs` |
| 测连通性（在连不上的那台机器上跑） | `node scripts\netcheck.mjs http://<地址>:7801 <邀请码>` |
| 模拟第二台设备（单机演示） | 双击 `scripts\demo-teammate.cmd`，输入邀请码回车 |
| 卸掉自启 | 管理员：`.\scripts\uninstall-autostart.cmd` |
| 管理页面（看成员、移除成员） | 浏览器打开黑窗口 / `hub-info.mjs` 里的 `http://127.0.0.1:7801/admin?key=...` |

## 附录 2：文件在哪、会不会泄露

| 位置 | 是什么 | 注意 |
|---|---|---|
| A 机 `data\team-hub-data.json` | 团队、邀请码、管理密钥、全队账本 | **备份只需要这一个文件**；含管理密钥，别外发 |
| 每台机器 `%DSH_HOME%\team-panel\state.json` | 成员 ID、显示名、**成员令牌**、所选项目、本机账本 | **成员令牌等同密码**，不要提交或分享 |
| 每台机器 `%DSH_HOME%\team-panel\`（整个目录） | 上面那个文件所在目录 | 想彻底重置就删它（见附录 3） |

插件**只上报计数**：成员名、机器名、项目名与路径、Token 数、估算花费、最后消耗时间。
提示词、模型回复、文件内容、会话标题、代码、任何凭据一概不出本机。详见 [SECURITY.md](../SECURITY.md)。

## 附录 3：退出 / 重置 / 卸载

- **只想停止上报**：面板 →「取消监测」（保留成员身份，队友仍能看到你这台机器）。
- **退出团队**：面板 →「设置」→「退出团队」。
- **彻底重置**：① 面板点「取消监测」+「退出团队」→ ② 删掉 `%DSH_HOME%\team-panel\` 目录
  → ③ A 机删掉 `data\team-hub-data.json` 后重启团队服务器（会重新建团队、打印**新邀请码**）
  → ④ 两台机器重新加入。
- **卸载插件**：`dsh plugin --profile desktop remove dsh-team-panel`，然后重启 DSH Desktop。
  （用 `link:` 装的，装之前先别删仓库目录。）