训练包 Token 配置问题修复报告

问题描述

训练包用户在扫码登录后，Dashboard 所有面板显示为空，原因是：

根本原因：.env.local 没有配置 QIWEI_AUTH_TOKEN
表现症状：
- Dashboard 状态接口返回 "online": false
- 所有面板无数据
- 用户不知道需要配置 token
为什么会发生：
- 打包脚本生成的 .env.local 模板过于简单
- README 没有明确说明首次使用必须配置 token
- 用户以为扫码登录就够了，不知道还需要额外配置

修复方案

1. 改进 `.env.local` 模板

位置：scripts/build-training-package.mjs 的 writeEnvTemplate 函数

改进内容：

✅ 添加醒目的顶部说明：「首次使用必须配置 QIWEI_AUTH_TOKEN」
✅ 分区注释：必填项、自动生成项、可选配置
✅ 详细的 token 获取方式说明（Claude Code / 飞马平台 / Fmode 控制台）
✅ 每个字段都有清晰的用途说明

修改前：

# fresh
QIWEI_UID=
QIWEI_API_BASE=https://server.fmode.cn/api/qiwei

修改后：

# ============================================================
# 企微培训工作台 - 本机凭据配置
# ============================================================
# 首次使用必须配置 QIWEI_AUTH_TOKEN，否则所有功能无法使用。

# ---------- 必填项 ----------
# Fmode 认证 token（必须！格式：r:xxx 或 sk-xxx）
# 获取方式：
#   1. Claude Code 已配置 Fmode：自动检测
#   2. 飞马平台：登录后在个人中心获取
#   3. Fmode 控制台：https://server.fmode.cn/
QIWEI_AUTH_TOKEN=

# ---------- 自动生成项（登录后自动填充）----------
QIWEI_UID=
QIWEI_GUID=
QIWEI_API_BASE=https://server.fmode.cn/api/qiwei

2. 改进 README 文档

位置：scripts/build-training-package.mjs 的 writeFieldGuide 函数

改进内容：

✅ 第一步明确为「配置认证 Token」，放在启动之前
✅ 提供两种配置方式：手动编辑（推荐）+ 页面配置
✅ 添加「常见问题」章节，Q1 就是「面板为空」问题
✅ 明确说明 token 获取的三种途径

修改前：

## 用户实际要做的事

1. Fmode token：本机已经用过时会自动检测...
2. 开通席位...
3. 企微扫码...
4. 开启监听...

修改后：

## 快速开始

### 第一步：配置认证 Token（必须！）

**重要：不配置 Token 会导致所有功能无法使用，面板显示为空。**

#### 方式 A：手动编辑配置文件（推荐）
1. 打开 `.env.local` 文件
2. 找到 `QIWEI_AUTH_TOKEN=` 这一行
3. 在等号后面粘贴你的 Fmode token
4. 保存文件

### 第二步：启动工作台
...

## 常见问题

### Q1: 工作台打开后所有面板都是空的？
**原因：** 没有配置 `QIWEI_AUTH_TOKEN`。
**解决：** 编辑 `.env.local` 文件，在 `QIWEI_AUTH_TOKEN=` 后面填入 token。

验证结果

当前训练包（D:/qiwei-training）状态

$ curl http://127.0.0.1:4320/api/status

认证配置: true
设备在线: true
订阅状态: true
uid: qiwei-6597ebbd-12be-41dc-937f-61903af00a0d

✅ 所有状态正常，Dashboard 可以正常显示数据

新打包流程验证

$ node scripts/build-training-package.mjs --outdir test-output
$ cat test-output/.env.local
# 包含详细的配置说明
$ cat test-output/README.md
# 第一步就是配置 Token

✅ 新用户拿到训练包后，会立即知道需要配置 token

影响范围

已修改文件

scripts/build-training-package.mjs - 打包脚本（新文件）
- writeEnvTemplate() - 生成改进的 .env.local 模板
- writeFieldGuide() - 生成改进的 README

已更新训练包

D:/qiwei-training/.env.local - 更新为新模板（保留实际配置值）
D:/qiwei-training/README.md - 更新为新文档

未来打包

所有通过 scripts/build-training-package.mjs 生成的训练包都会包含：

✅ 清晰的配置说明
✅ 首次使用指引
✅ 常见问题解答

用户体验改进

修复前

用户拿到训练包
双击 exe，打开 Dashboard
扫码登录成功
所有面板都是空的 ❌
不知道哪里出了问题

修复后

用户拿到训练包
打开 README，第一步就是配置 Token ✅
编辑 .env.local，填入 token
双击 exe，打开 Dashboard
扫码登录成功
所有面板正常显示数据 ✅

建议

进一步改进方向

Dashboard 检测逻辑：
- 如果检测到 QIWEI_AUTH_TOKEN 为空，在页面顶部显示醒目提示
- 提供「点击配置」按钮，直接跳转到配置页面
首次启动向导：
- 检测到是首次启动（.env.local 中 token 为空）
- 自动打开配置向导页面
- 验证 token 后再继续后续流程
错误提示优化：
- 当前 /api/status 返回 "online": false 时，用户不知道原因
- 建议返回更具体的错误信息："reason": "QIWEI_AUTH_TOKEN not configured"

总结

✅ 核心问题已修复：

打包脚本生成的配置文件和文档更加清晰
现有训练包已更新为新格式
用户不会再遇到「扫码后面板为空」的困惑

✅ 可立即交付：

当前训练包（D:/qiwei-training）状态正常
新用户使用新打包的训练包时会得到清晰指引

📝 后续优化：

Dashboard 可以增加配置检测和友好提示
考虑添加首次启动向导

fix-training-package-token-issue.md 5.5 KB Istoric Crud