---
name: qiwei-login
description: 通过 Fmode 网关转发的企业微信接口完成扫码登录和订阅管理。适用于首次使用、设备掉线、qiwei_api_call 返回 needs_login、订阅未开通或席位不足；客户端只使用 Fmode 鉴权 token 和 uid，企业微信接口访问凭据由 Fmode 网关管理。
---

# 企业微信扫码登录

## 严格流程

1. **检查订阅**：调用 `qiwei_subscription_status`。
   - 未订阅或已到期：调用 `qiwei_subscribe`；
   - 席位已满：用 `qiwei_subscribe` 传新的总 `seats` 数增购；
   - 余额不足：引导用户充值飞马余额后重试。
2. **检查设备**：调用 `qiwei_login_status`。
   - `online=true`：无需重新登录；
   - 未配置或离线：继续下一步。
3. **生成二维码**：调用 `qiwei_login_start`。
   - 工具通过 `/api/qiwei/login/start` 请求 Fmode 网关；
   - 二维码保存到 `outputs/qiwei-login-qrcode.png`，默认打开 HTML 预览；
   - 把二维码展示给用户，用手机企业微信扫码并确认。
4. **轮询状态**：每 3–5 秒调用 `qiwei_login_check`。
   - `-1 / 1`：继续等待；
   - `0`：可传 `manual: true` 尝试免扫码登录；
   - `2`：登录成功；
   - `4`：用户取消，重新调用 `qiwei_login_start`；
   - `10`：进入验证码流程。
5. **验证码**：状态 `10` 时向用户索要手机端显示的 6 位验证码，调用 `qiwei_login_verify`，然后再次检查状态。
6. **验证业务链路**：登录成功后调用 `qiwei_api_call`（例如 `user.getProfile`）。

## 新账号与多账号切换

- “添加账号”必须为新账号生成新的 `uid`，启动、轮询和验证码请求始终携带同一个新 `uid`；新 `uid` 不复用当前账号的 `guid`。
- 扫码完成前使用 `persistConfig=false`，不提前覆盖当前项目配置；状态为 `2` 后再保存新账号并调用 Dashboard 的账号切换接口。
- 切换成功后同时持久化 `QIWEI_UID` 与对应 `QIWEI_GUID`；新账号没有 GUID 时必须清除旧 GUID，不得形成跨账号组合。
- 浏览器账号列表按 `workspaceId` 隔离。同一浏览器访问多个克隆项目时，不得把其他项目的当前账号自动写入本项目。
- 用户取消扫码或切换接口失败时恢复原当前账号；已经保存的其他账号继续保留，可再次选择。
- 切换账号会切换独立 Workbench 数据库和 Claude 客户 Session；监听重启只恢复连接，不改变原有审核/自动/人工模式。

## 配置

- `QIWEI_API_BASE` 默认 `https://server.fmode.cn/api/qiwei`；
- Fmode token 自动从 Claude Code / Fmode 配置读取，也可显式设置 `QIWEI_AUTH_TOKEN`；
- `QIWEI_UID` 未配置时自动生成并持久化；
- 不读取、保存或要求用户提供企业微信接口访问凭据。

## 安全约定

- 不展示或记录 Authorization 和 Fmode token；
- 不向用户暴露接口服务提供方名称、相关域名或控制台；
- 不绕过 Fmode 网关直连内部服务；
- 不通过 `qiwei_api_call` 调用 `/login/*` 或 `/client/*`。
- 不在对话、日志或测试报告中回显 Token、GUID 或完整账号标识。