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

一、打包准备

1.1 本机环境要求

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

1.2 Bun 安装确认

# 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 执行打包

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/对象存储

# 方式 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 准备工作

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

3.2 启动流程

# 双击或命令行启动
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

手动填写（如未检测到）：

工作台页面会显示「Token 未配置」
粘贴以 sk- 开头的 Fmode token
点击「验证」按钮
验证通过后自动写入 .env.local

Token 来源：

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

步骤 2：开通席位

前提：已配置有效 Token

流程：

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

注意：

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

步骤 3：企微扫码登录

前提：已开通席位

流程：

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

卡点说明：

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

步骤 4：开启监听

前提：账号已在线

流程：

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

白名单机制：

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

四、核心功能验证

4.1 工作台基本功能

# 访问工作台
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 状态

# 方式 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
监听已开启
测试客户在白名单内

测试步骤：

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

无 Claude Code 的情况：

消息仍会进入工作台
不会自动生成草稿
需要人工手动编写回复

4.4 知识库生效验证

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

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

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

4.5 MCP 注册与工具发现验证

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

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

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

五、常见卡点与排查

5.1 Token 检测失败

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

原因：

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

解决：

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

5.2 席位阻塞

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

原因：

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

解决：

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

5.3 监听未启动

现象：

消息发送后工作台无反应
Runtime 状态显示 stopped

原因：

监听未手动开启
Runtime 进程异常退出

解决：

# 检查 Runtime 状态
qiwei-workbench.exe runtime status

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

# 或重启整个工作台

5.4 智能回复不生效

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

原因：

本机未安装 Claude Code
Claude Code 未在 PATH 中
会话不在白名单内

解决：

安装 Claude Code Desktop 或 CLI
确认 claude --version 可执行
检查白名单配置

5.5 端口冲突

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

原因：

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

解决：

# 查看端口占用
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 培训结束后的清理

# 删除敏感数据
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 数据库损坏恢复

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

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

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

8.3 完全重置

# 停止所有进程
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/ 目录大小可控
内存占用稳定

十、交付清单

培训包交付应包含：

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

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

training-package-deployment-guide.md 11 KB Permanentný odkaz História Raw