# 常见问题

## 安装之后

### 界面里完全看不到面板

按顺序查：

1. **装对 profile 了吗？** 当前 GUI（`127.0.0.1:43120`）属于 **`desktop`** profile；
   `web` 是给独立 `dsh web` 服务器用的另一套插件栈，装错了界面里什么都不会有。
   ```powershell
   dsh --profile desktop --dump-config | Select-String dsh-team-panel
   ```
2. **重启过 DSH Desktop 吗？** 宿主端**不会热加载**插件，装完必须完全退出再打开。
3. **强刷过前端吗？** 重启后按 `Ctrl+F5`。

### 面板没出现，但 `/dsh-team/ping` 正常

打开 `http://127.0.0.1:43120/dsh-team/ping`，能出 JSON 就说明宿主端已加载，问题在前端：

- **左侧边栏是不是被收起成图标轨了？** 侧栏窄到约 56px 时面板会自动隐藏，把侧栏拉开就回来。
- 面板在**全局面板**（设置、定时任务等）打开时会隐藏——这是有意的，不是坏了。
- 看 F12 控制台有没有报错。

### 改代码后没生效

- 改 `lib/panel.js` → **不用重启**（宿主端每次请求都现读磁盘），刷新浏览器即可。
- 改 `lib/index.js` 或 `cordis.patch.yml` → **必须重启 DSH Desktop**。

---

## Token 统计

### Token 一直是 0（最常见）

按顺序排查：

1. **是不是还没选项目？** 展开面板看「我的监测状态」是不是 `未选择`。
   **没选就一个 token 都不统计**——这是本插件的核心口径。
2. **选的项目对不对？** 只有工作目录在该项目（含子目录）里的会话才计入。
   你在别的项目里干活不会被算。
3. **选完之后有没有新跑对话？** 统计从「开始监测」那一刻起算，**之前的历史用量不会追溯**。
4. 都对了还是 0 → 打开 `http://127.0.0.1:43120/dsh-team/ping` 看 `monitoring` 与 `selectedProject`。

### 数字比平台账单少

本插件统计的是 **DSH 会话**产生的用量。以下不算在内：

- 你在网页版 / 其它客户端里直接用 DeepSeek 的消耗
- 使用其它 provider（OpenAI、Kimi 等）的调用
- 插件安装之前产生的历史用量

另外花费是**按官方价目表估算**，不是账单实际扣费（缓存命中率、优惠活动都会让实际费用不同）。

### 数字比平台账单多

基本只会有一个原因：**同一个项目在两台机器上都被监测，hub 会把它们合并成一个项目条目**——
这是设计如此（同名项目合并），但总量看起来就像翻倍了。核对时用「成员」维度看，而不是项目维度。

---

## 联网 / 团队

### 队友连不上团队服务器

**在队友那台机器上**跑连通性自检，它会直接告诉你卡在哪一步：

```powershell
node scripts\netcheck.mjs http://服务器地址:7801 <邀请码>
```

最常见的两个原因（自检会点出来）：

1. **hub 只监听了 `127.0.0.1`** → 用 `scripts\start-hub-public.cmd` 起
2. **Windows 防火墙没放行入站端口** → 服务器那台跑 `scripts\allow-firewall.cmd 7801`（需管理员）

详见 [联网方案](networking.md)。

### 填完服务器地址，一填邀请码地址框就自己变空了

**症状**：第二台设备上先填「团队服务器地址」，再点进「邀请码」框输入 —— 地址框里的地址凭空消失，
接着点「加入团队」只会报 `请先填写团队服务器地址`。

**原因**：`0.2.0` 及更早版本的面板每 3 秒轮询一次宿主状态并重绘设置区，
重绘时用「服务器那边已保存的地址」（此时还是空的）覆盖了输入框。
只有**当前光标所在**的那个框受保护，所以一从地址框切到邀请码框，地址就没了。

**处理**：

- **临时办法**（不升级也能加入）：每填一个框就点一次「**保存本机设置**」——
  地址一旦存进宿主，轮询回填的就是同一个值，不会再清空。
- **彻底修好**：用修复后的仓库覆盖第二台机器上那份目录（至少是 `lib/panel.js`），
  然后在那台机器的浏览器里 **F5 / Ctrl+F5** 刷新即可（面板脚本是每次请求现读的，不用重启 DSH）。

> 回归用例见 `scripts/mounttest.mjs` 的 `[6]` / `[7]`：仿 DOM 跑真实 `panel.js`，
> 模拟「填地址 → 切到邀请码框 → 轮询」，断言地址不会被抹掉。

### 显示「离线」红点

展开面板看标题行的错误信息，或直接跑 `netcheck`。逐项排查：
服务器起了吗 → `http://地址/api/health` 通不通 → 防火墙/安全组放行了吗 → 地址是不是漏了 `http://`。

### 装了开机自启之后，看不到邀请码了

后台任务以 SYSTEM 身份运行，**没有控制台可以看横幅**。用：

```powershell
node scripts\hub-info.mjs
```

### 队友的「最后消耗」一直是很久以前

服务器判定在线的阈值是 70 秒，插件每 20 秒心跳一次。对方 DSH 关着就会显示旧时间——这是预期行为。

### 下拉框里没有我要的项目

列表来自 DSH 自己的工作区注册表（与左侧栏「工作区」同源）。三种办法：

1. 先在 DSH 左侧栏把那个目录添加成工作区，再回来刷新；
2. **在它下面开一个会话**——插件见过该目录后会把它补进兜底列表；
3. 点选择器下方的 **「手动填写目录路径…」**，贴绝对路径点「使用」（目录必须存在）。

### 队友页面上我的项目显示成「未选择监测项目」

说明你这台机器当前没有选定项目，或点了「取消监测」。选好项目点「开始监测」，
下一次上报（最多 20 秒）就会更新。

---

## 团队服务器运维

### 换了机器 / 换了端口

队友在设置里改「团队服务器地址」重新保存即可；换团队要先「退出团队」。

### 怎么移除已经不用了的成员

浏览器打开管理页面（需要管理密钥，见 `hub-info.mjs` 的输出）→ 该成员 → 移除。

### 数据存在哪，怎么备份

- 服务器侧：`--data` 指定的 JSON 文件（脚本默认 `data/team-hub-data.json`）。
  **备份这一个文件即可**，团队、邀请码、成员账本都在里面。
- 本机侧：`%DSH_HOME%/team-panel/state.json`（成员 ID、显示名、成员令牌、所选项目、账本）。
  **该文件含成员令牌（等同密码），不要提交或分享。**

### 想彻底重置

1. 面板里点「取消监测」+「退出团队」
2. 删掉 `%DSH_HOME%/team-panel/` 目录
3. 服务器侧删掉数据文件后重启 hub（会重新建团队并打印新邀请码）
4. 队友需要重新加入

---

## 推送到 GitHub / 从 GitHub 克隆

本机**直连 `github.com` 是不通的**（TCP 握手就超时），必须走代理。

先用 **`proxyprobe`（代理探针）** 确认代理**是不是真的能出去**。

> `proxyprobe` 是一个**独立工具，不随本插件分发**（本插件的运行时零依赖，不掺进这类环境排查工具）。
> 它放在 `D:\Project\proxyprobe\`，也可以从它的[独立仓库](https://github.com/guooo1380/proxyprobe)获取。

```powershell
node D:\Project\proxyprobe\proxyprobe.mjs              # 自动找代理（参数 → git 配置 → 环境变量 → 常见端口）
node D:\Project\proxyprobe\proxyprobe.mjs --json       # 机读输出
```

它的判定标准是**在 CONNECT 隧道里真的完成 TLS 握手并收到 HTTP 响应**
—— 这也是它叫 probe（探针）而不是 check 的原因：**主动打一次真实握手去探路**。
这一点很重要 —— **Clash 类代理会先答应 CONNECT、之后再失败**，
只看「CONNECT 返回 200」会被骗（实测 1ms 就返回 200，其实根本连不出去）。

**「代理软件开着」不等于「代理真的能出去」**，两种常见假象：

1. 端口在监听、CONNECT 也返回 200，但隧道里出不去 → 换节点 / 检查订阅是否过期
2. **只开了 TUN 模式** —— 应用往往仍走直连，**端口代理才是可靠路径**

确认代理可用后，让 git 走它：

```powershell
# 只对当前仓库生效（推荐，推荐用它做一次性推送）
git config http.proxy  http://127.0.0.1:7993
git config https.proxy http://127.0.0.1:7993

# 或全局生效
git config --global http.proxy  http://127.0.0.1:7993
git config --global https.proxy http://127.0.0.1:7993
```

> ⚠️ **git 默认不读 Windows 系统代理**。即使代理客户端把系统代理打开了（`ProxyEnable=1`），
> git 依然会尝试直连并超时 —— 必须像上面这样单独配。

推完想撤掉：

```powershell
git config --unset http.proxy
git config --unset https.proxy
```

### 报 `cannot create standard input pipe for remote-https`

这不是网络问题，是**当前进程被沙箱限制了命名管道**（例如由受限的 agent 会话执行）。
在你自己的终端里不会有这个限制。

---

## 平台 / 环境

### 面板里的中文变成乱码

面板（`lib/panel.js`）在浏览器里按 UTF-8 解析，正常不会乱码。
会乱码的是**控制台**——本机代码页是 GBK，而 Node 输出 UTF-8。`.cmd` 脚本里已经用
`chcp 65001` 切到 UTF-8 再启动 Node，所以从脚本启动是正常的。

如果你自己在普通 PowerShell 里跑 `node lib/team-hub.mjs` 看到乱码，先执行一次 `chcp 65001`。

> 顺带：用 `Get-Content` 读 UTF-8 文件也会显示乱码（它按 GBK 解码）。
> **这是显示假象，文件本身没问题**——要确认请用 `Get-Content -Encoding UTF8`，或看字节。

### 每年要维护什么

`lib/peak.mjs` 里的 `HOLIDAY_VALLEY` 需要按国务院次年放假安排补日期。
没补的后果：次年法定节假日会被当成高峰计费时段，预估花费偏高（仅影响估算，不影响统计）。