# 企微培训包部署与测试完整指南

## 一、打包准备

### 1.1 本机环境要求

- **Node.js**: v18+ (开发机打包用)
- **Bun**: 最新版 (用于 `bun build --compile`)
- **依赖安装**: `npm install` 完成

### 1.2 Bun 安装确认

```bash
# Windows
powershell -c "irm bun.sh/install.ps1 | iex"

# 验证安装
bun --version
```

打包脚本会自动探测以下位置：
- `PATH` 中的 `bun`
- `%BUN_INSTALL%\bin\bun.exe`
- `%USERPROFILE%\.bun\bin\bun.exe`
- `D:\bun\bin\bun.exe`
- `C:\bun\bin\bun.exe`

### 1.3 执行打包

```bash
cd E:\workspace\QIWEI-skill
node scripts/build-training-package.mjs

# 产物输出到：dist/qiwei-training/
```

**打包产物结构**：
```
dist/qiwei-training/
├── qiwei-workbench.exe     # 主程序（约 80-120 MB）
├── web/                     # 前端资源
│   ├── index.html
│   ├── app.js
│   ├── styles.css
│   └── echarts.min.js
├── knowledge/               # 知识库（可现场编辑）
│   ├── rules.md
│   ├── playbooks.md
│   ├── faq.md
│   └── ...
├── .env.local              # 凭据模板（空白）
├── .mcp.json               # MCP 配置，已注册 qiwei-assistant
├── qiwei.runtime.config.mjs # 监听配置
└── README.md               # 用户手册
```

## 二、上传与分发

### 2.1 上传到 CDN/对象存储

```bash
# 方式 1：打包整个目录为 ZIP
cd dist
zip -r qiwei-training-v1.0.zip qiwei-training/

# 方式 2：单独上传 qiwei-workbench.exe
# 用户需要配合下载其他资源文件
```

**推荐分发方式**：
- 整包 ZIP 下载（150-200 MB，包含所有依赖）
- 用户解压到本地任意目录即可使用

### 2.2 Bun Runtime 说明

**重要**：`qiwei-workbench.exe` 是 **Bun 单文件可执行文件**，已内置 Bun runtime，用户**不需要**单独安装 Bun。

打包时通过 `bun build --compile` 将 Node.js 代码、Bun runtime 和必要依赖全部打包进 exe。

## 三、现场部署（用户视角）

### 3.1 准备工作

1. **下载并解压**培训包到本地（如 `D:\qiwei-training\`）
2. **确保目录完整**，不要只拷贝 exe 文件
3. Windows 可能提示「已保护你的电脑」，选择「更多信息」→「仍要运行」

### 3.2 启动流程

```bash
# 双击或命令行启动
D:\qiwei-training\qiwei-workbench.exe

# 可选：指定端口
qiwei-workbench.exe --port 4321
```

**启动后自动完成**：
- 拉起监听 Runtime（后台进程）
- 启动 Dashboard Web 服务（127.0.0.1:4320）
- 打开浏览器访问工作台

### 3.3 现场配置四步走

#### 步骤 1：Fmode Token 检测

**自动检测来源**：
- `~/.fmode/config.json` (本机飞马客户端的配置)
- `.env.local` 中的 `QIWEI_AUTH_TOKEN`

**手动填写**（如未检测到）：
1. 工作台页面会显示「Token 未配置」
2. 粘贴以 `sk-` 开头的 Fmode token
3. 点击「验证」按钮
4. 验证通过后自动写入 `.env.local`

**Token 来源**：
- 飞马客户端：设置 → API Token
- 或服务端管理员提供的项目 Token

#### 步骤 2：开通席位

**前提**：已配置有效 Token

**流程**：
- 未开通时，工作台会显示「需要开通席位」
- 点击后自动打开 `http://127.0.0.1:4310`（付费流程页）
- 从飞马余额扣费：1 席位 = 500 元/月
- 开通后自动生成 `QIWEI_UID` 并写入 `.env.local`

**注意**：
- 付费流程页由工作台内置，不依赖外部服务
- 订阅状态实时同步，无需重启

#### 步骤 3：企微扫码登录

**前提**：已开通席位

**流程**：
1. 工作台显示「账号离线，需要登录」
2. 点击「开始登录」，页面展示企微二维码
3. 用**企业微信**扫码（不是个人微信）
4. 手机端可能要求输入 6 位验证码，照提示输入
5. 扫码成功后，工作台显示「账号在线」

**卡点说明**：
- **席位不足**：已有设备占用席位时无法登录，需在服务端释放
- **二维码过期**：2 分钟未扫码会过期，刷新页面重新生成
- **企微限制**：同一账号同时只能在 1 个设备登录

#### 步骤 4：开启监听

**前提**：账号已在线

**流程**：
1. 回到工作台首页
2. 在「测试白名单」区域添加测试客户的手机号或企微 ID
3. 点击「开启智能监听」
4. 监听状态显示「运行中」

**白名单机制**：
- 只有白名单内的客户消息才会触发 AI 回复
- 避免测试期间误回复真实客户

## 四、核心功能验证

### 4.1 工作台基本功能

```bash
# 访问工作台
http://127.0.0.1:4320/

# 检查状态接口
curl http://127.0.0.1:4320/api/status | jq

# 期望返回：
{
  "summary": {
    "authConfigured": true,
    "online": true,
    "subscribed": true
  }
}
```

### 4.2 监听 Runtime 状态

```bash
# 方式 1：命令行查询
qiwei-workbench.exe runtime status

# 方式 2：查看状态文件
type outputs\runtime\qiwei-runtime.json

# 期望输出：
{
  "status": "running",
  "pid": 12345,
  "mode": "personal",
  "transport": "local_polling"
}
```

### 4.3 智能回复测试

**前提**：
- 本机已安装 **Claude Code**
- 监听已开启
- 测试客户在白名单内

**测试步骤**：
1. 测试客户通过企微发送消息「你好」
2. 工作台「会话」页面实时显示消息
3. Claude Code 自动生成回复草稿
4. 草稿进入「待审核」状态（默认不自动发送）
5. 人工审核后点击「发送」

**无 Claude Code 的情况**：
- 消息仍会进入工作台
- 不会自动生成草稿
- 需要人工手动编写回复

### 4.4 知识库生效验证

```bash
# 修改知识库
notepad knowledge\rules.md

# 重启工作台（自动重新加载）
# 或等待约 60 秒自动热重载

# 查看加载状态
curl http://127.0.0.1:4320/api/agent/config | jq .knowledge
```

### 4.5 MCP 注册与工具发现验证

交付包自带 `.mcp.json`，其中已注册 `qiwei-assistant`，不需要客户手动创建。解压后可执行：

```powershell
node scripts/verify-training-package-mcp.js D:\qiwei-training
```

期望结果为 `status: ok`，并显示已发现企微 MCP 工具。该检查只执行 MCP 初始化和工具列表发现，不发送群消息、不启动自动回复。

## 五、常见卡点与排查

### 5.1 Token 检测失败

**现象**：工作台显示「Token 未配置」

**原因**：
- 本机未安装飞马客户端
- `~/.fmode/config.json` 不存在或格式错误
- `.env.local` 未填写或 token 无效

**解决**：
1. 在工作台页面手动粘贴 token
2. 或预先填写 `.env.local`：
   ```
   QIWEI_AUTH_TOKEN=sk-xxxxx
   ```

### 5.2 席位阻塞

**现象**：扫码后提示「席位已满」

**原因**：
- 订阅的席位已被其他设备占用
- 同一账号在其他机器登录

**解决**：
- 联系管理员在服务端释放席位
- 或在其他设备上退出登录
- 或购买更多席位

### 5.3 监听未启动

**现象**：
- 消息发送后工作台无反应
- Runtime 状态显示 `stopped`

**原因**：
- 监听未手动开启
- Runtime 进程异常退出

**解决**：
```bash
# 检查 Runtime 状态
qiwei-workbench.exe runtime status

# 重启 Runtime
qiwei-workbench.exe runtime stop
qiwei-workbench.exe runtime start

# 或重启整个工作台
```

### 5.4 智能回复不生效

**现象**：消息进入工作台，但无草稿生成

**原因**：
- 本机未安装 Claude Code
- Claude Code 未在 PATH 中
- 会话不在白名单内

**解决**：
1. 安装 Claude Code Desktop 或 CLI
2. 确认 `claude --version` 可执行
3. 检查白名单配置

### 5.5 端口冲突

**现象**：启动时提示「端口已被占用」

**原因**：
- 4320 或 4310 端口被其他程序占用
- 上次启动的进程未正常退出

**解决**：
```bash
# 查看端口占用
netstat -ano | findstr 4320

# 杀掉占用进程
taskkill /PID <进程ID> /F

# 或指定其他端口启动
qiwei-workbench.exe --port 4321
```

### 5.6 防火墙拦截

**现象**：
- 浏览器无法访问 127.0.0.1:4320
- Windows 提示「防火墙已阻止此应用」

**解决**：
- 点击「允许访问」
- 仅允许「专用网络」即可（不需要公用网络）

## 六、数据持久化

### 6.1 关键文件说明

| 文件/目录 | 用途 | 是否保留 |
|----------|------|---------|
| `.env.local` | Fmode token、UID、GUID | **保留** |
| `outputs/` | 会话数据、消息记录、SQLite 数据库 | **保留** |
| `qiwei.runtime.config.mjs` | 监听轮询配置 | **保留** |
| `knowledge/` | 知识库（可现场编辑） | 按需保留 |

### 6.2 重打包时的保留策略

打包脚本已内置 `REBUILD_PRESERVED` 机制：
- 重新打包时，上述文件**不会被删除**
- 可以在测试机上反复重打，凭据和数据不丢失

### 6.3 培训结束后的清理

```bash
# 删除敏感数据
del .env.local
rmdir /s outputs

# 保留干净的可执行文件和知识库
# 供下次培训使用
```

## 七、性能与限制

### 7.1 资源占用

- **exe 大小**：80-120 MB（包含 Bun runtime）
- **内存占用**：200-400 MB（Dashboard + Runtime）
- **磁盘占用**：outputs/ 随会话增长，约 10-50 MB/天

### 7.2 并发限制

- **单机支持**：1 个企微账号
- **会话并发**：理论无限，实际受 Claude Code 速率限制
- **监听轮询**：每 3 秒一次（可在 `qiwei.runtime.config.mjs` 调整）

### 7.3 不支持的功能

本培训包**不包含**以下功能：
- 语音克隆与 TTS
- 企微官方 CLI（文档、会议、待办）
- 多设备、多账号并发
- 企业版中央 Relay

## 八、故障恢复

### 8.1 监听崩溃自动恢复

Runtime 进程意外退出时：
- 工作台会显示「监听已停止」
- 点击「重启监听」即可恢复
- 未发送的草稿会保留在数据库中

### 8.2 数据库损坏恢复

```bash
# 备份现有数据库
copy outputs\workbench.db outputs\workbench.db.bak

# 删除损坏的数据库（会话数据丢失）
del outputs\workbench.db

# 重启工作台，自动创建新数据库
```

### 8.3 完全重置

```bash
# 停止所有进程
qiwei-workbench.exe runtime stop
taskkill /IM qiwei-workbench.exe /F

# 清空所有数据
rmdir /s outputs

# 重新启动，回到初始状态
qiwei-workbench.exe
```

## 九、测试检查清单

### 9.1 打包后验证

- [ ] exe 文件可以正常启动
- [ ] 目录结构完整（web/, knowledge/, .env.local）
- [ ] `.mcp.json` 存在且注册 `qiwei-assistant`
- [ ] README.md 内容正确

### 9.2 部署验证

- [ ] 解压后目录结构完整
- [ ] 双击 exe 可以启动
- [ ] 浏览器自动打开工作台

### 9.3 功能验证

- [ ] Token 自动检测或手动填写成功
- [ ] 订阅开通流程完整
- [ ] 扫码登录成功，账号在线
- [ ] 白名单配置生效
- [ ] 监听启动成功
- [ ] 消息实时进入工作台
- [ ] Claude Code 自动生成草稿
- [ ] 人工审核与发送流程正常
- [ ] 知识库修改后生效

### 9.4 压力测试

- [ ] 连续运行 24 小时无崩溃
- [ ] 100+ 条消息处理无阻塞
- [ ] outputs/ 目录大小可控
- [ ] 内存占用稳定

## 十、交付清单

培训包交付应包含：

1. **可执行文件**：`qiwei-workbench.exe`
2. **资源文件**：`web/`, `knowledge/`
3. **配置模板**：`.env.local`, `.mcp.json`, `qiwei.runtime.config.mjs`
4. **用户文档**：`README.md`
5. **本指南**：`training-package-deployment-guide.md`（可选，供技术支持）

---

**最后更新**：2026-08-20  
**打包版本**：v1.0  
**目标平台**：Windows x64  
**运行时**：Bun 1.x (内置)