QIWEI-skill

fmode-qiwei 企业微信助手技能包

本仓库 master 是通用版 fmode-qiwei 的唯一开发真源。本仓库只维护可复用的企业微信技能、MCP、工作台、监听、安装与发布能力；客户业务定制、真实数据、凭据、运行数据库、会话、日志和房源业务不进入本仓库。

Bun 独立交付包的版本来源、发布流程和回滚规则见 docs/VERSIONING.md，逐版本变更见 docs/CHANGELOG.md。npm 仅保留历史开发基线，客户更新使用 Bun ZIP 和 CDN 清单。

技能包支持两种产品运行模式：

1. 个人版：ESM Runtime 在客户主机主动轮询，单企微设备和本地数据；
2. 企业版：ESM Runtime 从中央 Relay 拉取统一回调，多企微设备消息归集、租户隔离和企业管理底座。

登录、联系人、群聊、发送消息和文件等业务接口，两种版本都通过 Fmode/Future Server 网关调用。版本差异只在消息接收、存储和设备管理方式。

使用 qiwei_product_mode_status 查看模式，使用 qiwei_product_mode_set 切换。企业版属于独立增值服务，当前报价接口金额为 0 元占位，和企微账号席位费分开。

同时提供两套相互独立的企业微信能力通道：

1. 原有 全量接口清单 + Fmode 网关转发 + 扫码登录 + 包月订阅管理；
2. 新增 企业微信官方 CLI，用于会议、文档等官方机器人能力。

原有接口、登录和订阅请求仍统一经过：

Claude Code / MCP
  → Fmode 网关转发的企业微信接口
  → Fmode 网关完成鉴权、订阅校验和设备上下文处理
  → 企业微信服务

当前技能侧已经按 Fmode 网关协议实现；正式使用前需要在 Fmode 网关启用企业微信接口路由。

官方 CLI 是第二条独立通道：技能包不会修改官方程序，而是在首次使用时把固定版本下载到用户缓存；官方机器人凭据由 CLI 在本地加密保存，不经过 Fmode 网关。

组成

├── .mcp.json
├── .env.example
├── bin/qiwei-official-cli.js
├── wecom-cli-runtime.json
├── mcp/
│   ├── catalog/qiwei-endpoints.json
│   └── src/
│       ├── server.js
│       ├── core/api-catalog.js
│       ├── core/wecom-cli-runtime.js
│       ├── core/credentials.js
│       ├── core/shared-gateway.js
│       ├── core/webhook-server.js
│       ├── core/output-paths.js
│       ├── providers/fmode-wecom-gateway.js
│       ├── providers/wecom-official-cli.js
│       └── tools/
│           ├── qiwei-api-catalog-run.js
│           ├── qiwei-login-run.js
│           ├── qiwei-subscription-run.js
│           ├── qiwei-customer-ops-run.js
│           ├── qiwei-group-management-run.js
│           ├── qiwei-portrait-tags-run.js
│           ├── qiwei-broker-playbook-run.js
│           ├── qiwei-customer-transfer-run.js
│           ├── qiwei-voice-run.js
│           ├── qiwei-webhook-relay-run.js
│           └── wecom-official-cli-run.js
├── skills/
│   ├── qiwei-api-catalog/SKILL.md
│   ├── qiwei-login/SKILL.md
│   ├── qiwei-subscription/SKILL.md
│   ├── qiwei-customer-ops/SKILL.md
│   ├── qiwei-group-management/SKILL.md
│   ├── qiwei-portrait-tags/SKILL.md
│   ├── qiwei-broker-playbook/SKILL.md
│   ├── qiwei-customer-transfer/SKILL.md
│   ├── qiwei-voice/SKILL.md
│   ├── qiwei-webhook-relay/SKILL.md
│   ├── qiwei-capability-router/SKILL.md
│   ├── qiwei-official-meeting/SKILL.md
│   └── qiwei-official-doc/SKILL.md
├── docs/                             # 文档（specs/ guides/ generated/，规则见 OUTPUT-STANDARD.md）
│   └── OUTPUT-STANDARD.md
└── outputs/                          # 运行期生成文件，按类别归档，git 忽略

输出与目录标准

所有生成文件遵循 docs/OUTPUT-STANDARD.md：

• 运行期产物统一写入 outputs/<类别>/（包括消息、客户、群、画像、Dashboard、Runtime、语音、Webhook 等），根目录可用 QIWEI_OUTPUTS_DIR 覆盖；
• 覆盖型文件用 latest 模式（如 outputs/login/qiwei-login-qrcode.png），按次归档用 run 模式（outputs/<类别>/<YYYY-MM-DD>/<HHmmss>-<slug>/ + manifest.json）；
• 路径一律通过 mcp/src/core/output-paths.js 解析；
• 校验：npm run outputs:validate。

MCP 工具

基础能力

工具	说明
qiwei_product_mode_status	查看个人版/企业版、消息接收方式、Relay 状态和企业升级占位
qiwei_product_mode_set	切换个人版或企业版，并返回后续配置步骤
qiwei_api_search	检索 100+ 个企业微信接口
qiwei_api_doc	查看参数、返回字段和调用模板
qiwei_api_call	POST /api/qiwei/doApi，传 {uid, method, params}
qiwei_login_status	GET /api/qiwei/login/status?uid=
qiwei_login_start	POST /api/qiwei/login/start 并保存二维码
qiwei_login_check	POST /api/qiwei/login/check
qiwei_login_verify	POST /api/qiwei/login/verify
qiwei_subscription_status	查询订阅、席位、到期时间和余额
qiwei_subscribe	开通、续费或增购席位
qiwei_subscription_auto_renew	设置自动续费

客户运营

工具	说明
qiwei_batch_add_friends	按手机号批量搜索并添加企微好友
qiwei_auto_create_group	创建客户服务群、设置群名、邀请协作成员、发送欢迎语
qiwei_check_friend_status	检查好友申请状态
qiwei_get_customer_profile	查询客户档案

经营诊断

工具	说明
qiwei_business_diagnosis	只读汇总客户、真实会话和社群运营数据，输出结论、证据、数据缺口与可下钻动作
qiwei_business_action_candidate	将一条诊断建议加入统一任务候选池，等待人工确认后再转正式任务
qiwei_business_action_feedback	为已完成的诊断行动记录内部效果反馈，不发送客户消息或同步企微待办

群管理

工具	说明
qiwei_sync_external_groups	同步外部群列表
qiwei_list_external_groups	列出并识别客户群
qiwei_analyze_group_members	分析群详情
qiwei_confirm_external_group	确认外部群为客户群
qiwei_add_external_group	手动添加外部群
qiwei_sync_group_messages	同步群历史消息

画像与标签

工具	说明
qiwei_prepare_customer_portrait	准备客户画像分析上下文
qiwei_update_customer_portrait	更新客户画像（Agent 驱动 / keyword 模式）
qiwei_save_customer_portrait	保存客户画像
qiwei_batch_update_customer_portrait	批量更新客户画像
qiwei_batch_save_customer_portrait	批量保存客户画像
qiwei_export_customer_portraits	导出客户画像为 Excel
qiwei_add_customer_tags	添加客户本地标签
qiwei_remove_customer_tags	移除客户本地标签
qiwei_list_customer_tags	列出客户本地标签
qiwei_list_all_tags	列出所有本地标签
qiwei_sync_personal_labels	同步企微个人标签
qiwei_create_personal_label	创建企微个人标签
qiwei_update_personal_label	更新企微个人标签
qiwei_delete_personal_label	删除企微个人标签
qiwei_apply_personal_labels	应用企微个人标签到客户

顾问 Playbook

工具	说明
qiwei_prepare_broker_playbook	准备顾问 playbook 分析上下文
qiwei_distill_broker	蒸馏顾问 playbook
qiwei_save_broker_playbook	保存顾问 playbook
qiwei_batch_distill_broker	批量蒸馏顾问 playbook
qiwei_batch_save_broker_playbook	批量保存顾问 playbook
qiwei_export_broker_playbooks	导出顾问 playbook 为 Excel
qiwei_get_broker_playbook	读取顾问 playbook

客户交接

工具	说明
qiwei_preview_transfer_package	预览交接包
qiwei_execute_transfer	执行群成员变更完成交接

语音

工具	说明
qiwei_transcribe_voice	保存语音、可选解码 silk、可选转写
qiwei_voice_profile_status	查询云端 IndexTTS2 与本人声音初始化状态
qiwei_enroll_voice	保存并校验当前企微账号的本人参考录音
qiwei_send_cloned_voice	人工确认后编码 24kHz SILK 并真实发送企微语音

语音合成遵循 Fmode 当前账户的计费说明，实际费用与余额以服务端返回为准；试听和发送都会消耗对应额度。

Webhook 与 Relay

运行时统一入口：

npm run runtime
npm run runtime:status
npm run runtime:stop

npm run preview 会在新启动 4320 工作台时自动嵌入 ESM Runtime，不增加用户操作步骤。个人版启动本地 Agent Poller；企业版启动 Relay Client。旧命令 npm run relay 保留兼容，内部同样进入企业版 ESM Runtime。

工具	说明
qiwei_webhook_server_start	启动本地 webhook server
qiwei_webhook_server_stop	停止本地 webhook server
qiwei_webhook_status	查询 webhook 状态
qiwei_webhook_discover	获取本地 webhook 回调地址
qiwei_webhook_auto_setup	企业版注册设备并连接服务端统一回调
qiwei_webhook_setup	旧隔离部署的显式直连回调（不属于个人版标准流程）
qiwei_relay_config	读取 relay 配置
qiwei_relay_save_config	保存 relay 公钥/租户配置
qiwei_relay_register	注册 Relay 租户并保存凭证
qiwei_relay_connect	配置 Relay 回调地址

官方 CLI

工具	说明
qiwei_official_status	检查官方 CLI 下载与授权状态
qiwei_official_prepare	下载并缓存固定版本官方 CLI
qiwei_official_help	读取官方 category/method 帮助
qiwei_official_call	结构化调用官方通讯录、文档、会议、消息、日程和待办能力

官方 CLI 通道

官方 CLI 保持原样，不复制或修改官方 Skills。本技能包自己的会议、文档 Skills 通过统一 MCP 适配层调用 CLI。

运行时版本固定在 wecom-cli-runtime.json，默认安装到用户缓存：

• Windows：%LOCALAPPDATA%\Fmode\qiwei-assistant\wecom-cli\<version>
• macOS：~/Library/Caches/fmode/qiwei-assistant/wecom-cli/<version>
• Linux：~/.cache/fmode/qiwei-assistant/wecom-cli/<version>

可以让 Skill 首次使用时调用 qiwei_official_prepare，也可以提前下载：

npm run wecom:install

首次使用官方能力需要完成一次企业微信扫码：

npm run wecom:init

检查状态：

npm run wecom:status

官方 CLI 的认证默认保存在 ~/.config/wecom，也可由 WECOM_CLI_CONFIG_DIR 覆盖。该认证与 Fmode token、QIWEI_UID 和个人企微设备登录完全独立。

鉴权和本地配置

• 请求头统一为 Authorization: Bearer <Fmode token>。
• 优先自动读取 Claude Code 已配置的 Fmode NewAPI sk- token。
• 也支持 QIWEI_AUTH_TOKEN、FMODE_API_KEY、FMODE_API_TOKEN、NEWAPI_TOKEN 或平台 sessionToken。
• QIWEI_API_BASE 默认 https://server.fmode.cn/api/qiwei。
• QIWEI_UID 是客户端设备别名；未配置时会生成随机稳定 uid，并写入 .env.local 和 ~/.claude/qiwei-credentials.json。
• 登录成功后会保存企微 userId 的本地标识，并使用其不可逆摘要隔离客户、画像、标签、群、消息归档、Dashboard 状态和工作台数据库；昵称、企业名和原始 userId 不进入目录名。
• 升级前已有的未分区数据默认归入 legacy-default。先运行 npm run migrate:legacy-account 查看 dry-run 计划，确认后再运行 npm run migrate:legacy-account -- --execute；可通过 QIWEI_LEGACY_ACCOUNT_KEY 指定兼容分区名。
• 企业微信接口访问凭据和设备上下文由 Fmode 网关管理，不会出现在技能配置或返回结果中。

快速启动与预览

在 Fmode Studio 中打开项目后，直接对 Claude Code 说：

启动并预览企微助手

Claude Code 会调用 qiwei_agent_dashboard_start，启动 4320 工作台，并返回产品模式、Fmode 鉴权、企微席位、企微在线、企业回调（仅企业版）和测试白名单状态。企业版消息接收不依赖 Dashboard。

源码开发也可以执行：

npm run preview

安装到客户 workspace 后可以执行：

node .claude/plugins/qiwei-assistant/install.js preview .

启动器会自动打开浏览器并告诉用户当前第一项需要处理的动作。使用 --no-open 可禁止自动打开浏览器，使用 --port 4321 可切换端口。

底层登录顺序

1. qiwei_subscription_status 检查订阅；
2. 未订阅时调用 qiwei_subscribe，seats 表示企微账号席位数；
3. qiwei_login_start 生成二维码；
4. 用户扫码后每 3–5 秒调用 qiwei_login_check；
5. 状态 10 时用 qiwei_login_verify 提交 6 位验证码；
6. 状态 2 后用 qiwei_api_call 调业务接口。

业务调用只传清单中的业务参数：

{
  "id": "msg.sendText",
  "params": {
    "toId": "168...",
    "content": "hello",
    "isNoNeedRead": false
  }
}

安装与验证

npm install
npm run check
npm run smoke
npm run agent:smoke
npm run outputs:validate
node install.js --check

冒烟测试会启动本地 mock Fmode 网关，验证 Authorization、uid/method/params 请求信封、登录和订阅接口，不访问真实服务。 同时会使用本地假 CLI 验证官方运行时状态、结构化参数传递和命令注入防护，不访问真实企业微信。

Dashboard（本地 Web 界面）

本项目包含一个独立的本地 Web Dashboard，用于在浏览器中管理智能会话、客户群和账号状态等：

npm run preview

启动后访问：

http://127.0.0.1:4320/

为什么建议在项目目录下启动

Dashboard 优先使用启动进程或 MCP 请求中注入的 QIWEI_AUTH_TOKEN、QIWEI_UID 和 QIWEI_API_BASE，其次读取客户项目根目录的 .env.local、Fmode/Claude Code 用户配置。workspace 安装会将运行目录、输出目录和 Claude Code 工作目录绑定到客户项目根目录，避免客户数据落入隐藏插件目录。

端口与状态

• 默认端口 4320，可通过 QIWEI_DASHBOARD_PORT 覆盖；
• 健康检查：curl http://127.0.0.1:4320/api/health；
• 状态汇总：curl http://127.0.0.1:4320/api/status；页面启动探测使用 ?fast=true，避免上游 Fmode 不可达时阻塞本地工作台。
• 健康检查包含当前项目的 workspaceId，用于阻止不同项目误用同一个 4320 服务。

智能会话演示

Dashboard 的「智能会话」页把回调消息、意图识别、需求画像、业务匹配、自动回复和人工协同放在同一页面：

• 点击「管理白名单」，从当前企微外部联系人中搜索并勾选允许 Agent 处理的客户；
• 企业版由 MCP/Skill 自动连接公网回调并启动独立 Relay 守护进程；Dashboard 关闭后仍持续接收，离线期间的消息保留在服务端队列；
• 个人版仍可点击「启动 AI 监听」，仅处理已选白名单联系人；
• 已确认的客户群只通过公网回调采集新消息并触发画像增量更新，不进入客服工作台回复链路；
• 企业版通过全局 paused 或单会话人工接管停止 Agent 处理，但消息仍持续接收并保存；
• 真实发送只允许命中 QIWEI_AUTO_REPLY_ALLOWED_SENDERS 白名单的联系人；
• 客服输入文本后可自动识别「自然、友好、真诚致歉、温和关怀、明确提醒」，人工确认后通过 Fmode /api/voice/indextts2 生成并发送本人音色的原生企微语音；试听默认禁用，避免额外产生一次合成费用；
• 语音合成与媒体上传复用同一个 Fmode Token；媒体只通过已验证的 Fmode /api/qiwei/doFileApi multipart 路由直接上传，路由不可用时直接报错，不暴露公网音频回源地址；
• 「本人声音」支持浏览器录音或音频上传，参考录音按企微账号隔离，注销后删除；
• 已发送语音在消息流中显示为语音气泡，点击气泡播放或暂停；左侧「转文字」直接展开合成时保存的准确原文，不会再次调用语音识别服务；
• 使用待审核草稿发送语音成功后，该草稿会同步结算为已发送并关联语音消息，文字操作区恢复为「让 Agent 处理」，避免同一回复再次以文字发送；
• 可对单个客户切换「人工接管 / 恢复 Agent」；
• 未初始化的客户 Claude Code Session 可在工作台一键首次运行并生成待审核草稿；已初始化 Session 仍通过现有说明和命令打开隔离审阅副本；
• 客户长期记忆由 Workbench DB 独立管理：明确事实、偏好和约束带原消息证据保存，核心记忆限长注入，较早对话仅在与本轮相关时召回；
• 长期记忆默认作为后台能力运行，不在客服工作台增加治理面板；管理接口仍支持新增、编辑、确认推断、拒绝和彻底遗忘，并写入审计；
• Claude Code Session 使用 Epoch 模式，默认每 12 次生成或 24 小时轮换，避免单个 Session 无限增长；轮换不会丢失客户长期记忆；
• 首次启动会同步并跳过历史消息，避免把历史消息当成新消息重复处理。

推荐的现场顺序：

1. 打开 http://127.0.0.1:4320/#agent，确认测试账号显示在线；
2. 点击「管理白名单」，搜索并选择一位测试联系人；
3. 确认页面显示「公网回调常驻」；
4. 用已选白名单联系人发送一条新消息，无需启动监听；
5. 查看意图、需求画像、匹配结果和建议回复；
6. 切换全局暂停或单客户「人工接管」，验证消息继续入库但 Agent 不再生成回复；
7. 恢复待审核或自动策略，演示继续处理后续回调消息。

离线恢复

账号离线时，Dashboard「账号状态」页会显示「恢复登录」按钮。系统也会自动尝试免扫码恢复登录；若无法自动恢复，点击按钮后会进入二维码/验证码登录流程。

「智能会话」使用本地保存的账号绑定、会话、记忆、任务和审计数据先行加载，不等待远程登录状态探测。Fmode 暂时离线时，页面会显示离线状态，但本地客服工作台仍可查看和治理；真实收发及需要上游接口的操作会在连接恢复后可用。账号列表保存在当前 Dashboard origin 的浏览器存储中，因此应固定使用正式地址 http://127.0.0.1:4320/，临时测试端口不会共享该列表。

Claude Code/Fmode 项目主控架构

客户把技能包安装到独立项目目录后，在该目录中的 Claude Code 会话作为项目主控入口：

1. 完成企微登录；企业版 MCP 启动时会自动连接回调并确保 Relay 守护进程常驻；
2. Dashboard 仅用于可视化管理，qiwei_agent_status、qiwei_agent_list_conversations 和 qiwei_agent_inbox 不依赖 Dashboard；
3. 用 qiwei_agent_set_global 设置暂停、待审核、自动或人工策略；
4. 每个白名单客户绑定独立 Claude Code Session Epoch，通过 Fmode 模型配置生成草稿；客户长期记忆独立保存在 Workbench DB；
5. 前端和客户 Session 的动作统一写入 Workbench，主控会话通过 qiwei_agent_inbox 读取事件；
6. qiwei_agent_generate_draft 只生成草稿，不会发送。真实发送仍需通过 Dashboard 审核和白名单校验。

客户 Session 映射按企微账号隔离保存在 outputs/messages/claude-code-sessions-<账号哈希>.json，包含项目 ID、项目控制器关联和每客户独立 Session。旧版单账号工作台会在首次启动时自动迁入当前账号的独立数据库。默认仅开放 Read,Glob,Grep，不允许客户 Agent 修改项目文件。

客户记忆与上下文

客服 Agent 采用 Hermes-style 分层上下文，但不依赖 Claude Code 自带 auto-memory：

1. messages 保存完整情景历史，是审计事实源；
2. customer_profiles/tasks/alerts/recommendations 保存结构化业务状态；
3. customer_memory_items 保存带证据的明确事实、偏好和约束，模型推断必须以 hypothesis 隔离；
4. customer_memory_snapshots 保存限长核心记忆快照；默认最多 4000 字符；
5. 每轮只注入核心快照、最多 6 条相关历史和近期有效会话，不把完整历史重复塞入提示词；
6. Session 达到轮次或时长上限后创建新 Epoch，并保留父 Session 与最近 50 个 Epoch 的审计元数据。

已有客户在升级后会执行一次幂等回填：把现有画像字段和历史消息中的明确偏好、约束转为本地记忆。人工修改客户主档时，对应 profile:<field> 记忆会同步更新；清空字段会将旧记忆标记为 superseded。设置了 expires_at 的临时记忆到期后也会自动退出 active 快照。

后台记忆管理接口（默认不在 Dashboard 暴露入口）：

POST /api/agent/conversations/:conversationId/memories
POST /api/agent/memories/:memoryId

第二个接口支持 update、confirm、reject 和 forget。其中 forget 会物理删除本地记忆；原始客户消息仍按 Workbench 消息保留策略独立管理。

可通过 .env.local 调整：

QIWEI_AGENT_MEMORY_ENABLED=true
QIWEI_AGENT_MEMORY_CORE_CHAR_LIMIT=4000
QIWEI_AGENT_MEMORY_RECALL_LIMIT=6
QIWEI_AGENT_MEMORY_RECENT_MESSAGES=12
QIWEI_AGENT_MEMORY_HISTORY_SCAN_LIMIT=240
QIWEI_AGENT_MEMORY_EXTRACTION_INTERVAL_MS=1000
QIWEI_AGENT_MEMORY_EXTRACTION_RETRY_BASE_MS=1000
QIWEI_AGENT_MEMORY_EXTRACTION_MAX_ATTEMPTS=3
QIWEI_AGENT_CONTEXT_FILES=personality.md,context.md,rules.md
QIWEI_AGENT_CONTEXT_CHAR_LIMIT=6000
QIWEI_AGENT_PROMPT_CHAR_LIMIT=16000
QIWEI_AGENT_SYSTEM_PROMPT_CHAR_LIMIT=12000
CLAUDE_CODE_SESSION_MAX_TURNS=12
CLAUDE_CODE_SESSION_MAX_AGE_MS=86400000

完整设计、数据边界和后续 provider 接口见 企微客服记忆与上下文架构。

项目级人格和上下文分别放在 knowledge/personality.md、knowledge/context.md，硬规则放在 knowledge/rules.md。这些文件按固定字符预算每轮注入，不依赖 Session 是否轮换；需要引用其他知识片段时，可在上下文文件中单独写一行 @context faq.md#标题。引用只能解析 QIWEI_AGENT_KNOWLEDGE_DIR 内已经索引的 Markdown 片段。

AgentContextBuilder 统一组装项目上下文、长期记忆、结构化业务状态和本轮权威会话。Claude Code 与其他模型 provider 共用同一套边界；总 prompt 和 system prompt 分别受 QIWEI_AGENT_PROMPT_CHAR_LIMIT、QIWEI_AGENT_SYSTEM_PROMPT_CHAR_LIMIT 控制，预算不足时优先保留最新客户会话。

Claude Code 返回的结构化结果会经过统一归一化：支持纯 JSON、Markdown JSON 代码块、带说明文字的 JSON，以及 reply 内再次嵌套 JSON。最终客户回复出口只接受自然语言；无法安全解析的结构化文本会留空并转人工审核，不会把 JSON 原文发送给客户。

claude_code_session 的 toolTrace 会记录 durationMs、resumed、sessionResetReason、systemChars、businessPromptChars 和 promptChars。正常恢复 Session 通常快于 Epoch 轮换或失效后的冷启动；排查速度时应先按 resumed 分组比较，避免把一次性的冷启动与日常处理耗时混在一起。结构化业务状态只在业务 prompt 注入一次，以减少重复上下文。

长期记忆提取不再阻塞回复草稿落库。主链只写入 memory_extraction_jobs，后台 worker 完成规则提取、证据关联和快照刷新；处理中断的任务会在下次打开数据库时恢复为 pending，失败任务按指数退避重试，达到 QIWEI_AGENT_MEMORY_EXTRACTION_MAX_ATTEMPTS 后才标记为 failed。

稳定记忆键出现新内容、人工修改或到期失效时，旧值和新值会写入 customer_memory_revisions，包含当时的证据消息 ID 和变更原因。当前有效记忆仍只保留一条，避免把互相冲突的事实同时注入模型；执行彻底遗忘时，修订历史随记忆一起级联删除。

Dashboard 会在每个客户会话标题下主动显示 Session 状态、客户可识别会话名和打开入口；主控 Claude Code 也可以调用 qiwei_agent_session_guide 获取同样说明。两处都不会暴露原始 Session ID。

Dashboard 默认给 Claude Code 单次生成设置 $1 预算，遇到 error_max_budget_usd 时会重建 Session 并以 $3 预算重试一次；可分别通过 CLAUDE_CODE_MAX_BUDGET_USD 和 CLAUDE_CODE_RETRY_MAX_BUDGET_USD 调整，最高 $5。这里限制的是单次任务开销，不是 Claude 账户余额。

查看某个客户对应的 Claude Code 历史时，不需要查找或复制原始 Session ID：

npm run agent:session:list
npm run agent:session -- --customer 王刚

第二条命令会在当前 Fmode Studio 项目终端中打开当前 Session Epoch 的 fork 审阅副本，保留该 Epoch 的历史、模型思考和工具记录；审阅过程中发送的新问题只进入副本，不会污染生产客户 Session。跨 Epoch 的客户事实以 Workbench 长期记忆和完整消息记录为准。

安装到客户项目

npm 发布版推荐直接安装到当前客户项目：

npx --yes fmode-qiwei@latest workspace --smoke
npx --yes fmode-qiwei@latest preview

本地源码调试也可以执行：

node install.js workspace <客户项目目录> --smoke

安装器会写入：

<客户项目>/.claude/plugins/qiwei-assistant
<客户项目>/.claude/skills/<qiwei-skill>
<客户项目>/.mcp.json
<客户项目>/.gitignore

安装器会幂等补全项目根目录 .gitignore，保留项目已有规则，并忽略本地凭据、运行数据库、Session、日志和依赖目录。安装过程不会复制 .env、.env.local、.npmrc、真实运行输出、客户 Session、Playwright 会话、压缩包或源码目录中的 node_modules。当前版本为 fmode-qiwei@0.5.2；版本与验证记录见 docs/RELEASE.md。

子 Skill 索引

Agent 可按业务场景直接定位到对应 Skill 文档，每个 Skill 内部包含标准流程、前置条件、错误处理和工具选择建议。

Skill	路径	适用场景	核心工具
qiwei-dashboard	skills/qiwei-dashboard/SKILL.md	经营驾驶舱、服务状态、统一任务中心与本地知识库	npm run dashboard、/api/health、/api/business-diagnosis、/api/knowledge/tasks
qiwei-api-catalog	skills/qiwei-api-catalog/SKILL.md	检索、阅读、调用企业微信开放接口	qiwei_api_search、qiwei_api_doc、qiwei_api_call
qiwei-login	skills/qiwei-login/SKILL.md	设备登录、扫码、验证码	qiwei_login_status、qiwei_login_start、qiwei_login_check、qiwei_login_verify
qiwei-subscription	skills/qiwei-subscription/SKILL.md	订阅查询、开通、续费、自动续费	qiwei_subscription_status、qiwei_subscribe、qiwei_subscription_auto_renew
qiwei-customer-ops	skills/qiwei-customer-ops/SKILL.md	批量加好友、自动建群、客户档案	qiwei_batch_add_friends、qiwei_auto_create_group、qiwei_check_friend_status、qiwei_get_customer_profile
qiwei-group-management	skills/qiwei-group-management/SKILL.md	同步群列表、识别/确认客户群、同步群消息	qiwei_sync_external_groups、qiwei_list_external_groups、qiwei_confirm_external_group、qiwei_sync_group_messages
qiwei-group-operations	skills/qiwei-group-operations/SKILL.md	社群 SOP、计划、话术审核、质检整改与受控自动化	qiwei_groupops*
qiwei-business-diagnosis	skills/qiwei-business-diagnosis/SKILL.md	诊断经营问题、采纳行动候选并复盘已完成行动效果	qiwei_business_diagnosis、qiwei_business_action_candidate、qiwei_business_action_feedback
qiwei-portrait-tags	skills/qiwei-portrait-tags/SKILL.md	客户画像分析、标签管理、企微个人标签	qiwei_update_customer_portrait、qiwei_save_customer_portrait、qiwei_add_customer_tags、qiwei_apply_personal_labels
qiwei-broker-playbook	skills/qiwei-broker-playbook/SKILL.md	顾问 playbook 蒸馏、保存、导出	qiwei_distill_broker、qiwei_save_broker_playbook、qiwei_export_broker_playbooks
qiwei-customer-transfer	skills/qiwei-customer-transfer/SKILL.md	客户交接预览与执行	qiwei_preview_transfer_package、qiwei_execute_transfer
qiwei-voice	skills/qiwei-voice/SKILL.md	语音转写、本人声音初始化、受控情绪合成与企微语音发送	qiwei_transcribe_voice、qiwei_voice_profile_status、qiwei_enroll_voice、qiwei_send_cloned_voice
qiwei-webhook-relay	skills/qiwei-webhook-relay/SKILL.md	本地 webhook 接收、企微回调配置、Relay 自动注册与配置	qiwei_webhook_server_start、qiwei_webhook_auto_setup、qiwei_relay_register、qiwei_relay_connect、qiwei_relay_save_config
qiwei-capability-router	skills/qiwei-capability-router/SKILL.md	选择 Fmode 网关还是官方 CLI 通道	按 Skill 内部规则路由
qiwei-official-meeting	skills/qiwei-official-meeting/SKILL.md	官方会议能力	qiwei_official_call
qiwei-official-doc	skills/qiwei-official-doc/SKILL.md	官方文档能力	qiwei_official_call
qiwei-official-schedule	skills/qiwei-official-schedule/SKILL.md	官方日程与多人空闲时间协调	qiwei_official_help、qiwei_official_call
qiwei-official-todo	skills/qiwei-official-todo/SKILL.md	官方待办创建、分配与推进	qiwei_official_help、qiwei_official_call
qiwei-goal-management	skills/qiwei-goal-management/SKILL.md	大目标拆解、会议行动项和进度台账	qiwei_goal_create_plan、qiwei_goal_import_meeting_actions、qiwei_goal_update_task、qiwei_goal_get

限制

• 通用 qiwei_api_call 仍拒绝 multipart；语音媒体由专用 /api/qiwei/doFileApi 路由上传。
• /login/*、/client/* 不允许通过 qiwei_api_call 透传，必须使用登录专用工具。
• 服务端未挂载前，默认生产地址会返回不可用；可通过 QIWEI_API_BASE 指向测试环境。
• 官方 CLI 首次下载需要 npm 网络访问，首次业务调用前需要独立完成企业微信机器人扫码授权。
• 官方 CLI 通道失败不会替代或改变原有 Fmode 网关接口通道。

AI 智能会话

启动 Dashboard 后，在「智能会话」页点击「管理白名单」，直接从企微联系人中搜索并勾选客户。保存后立即写入当前企微账号的独立 Workbench DB 并热加载，无需手工查找联系人 ID 或重启技能包；扫码切换账号不会复用或覆盖另一账号的白名单、自动纳入名单和监听开关。

个人消息接入默认使用 allowlist_only。可在 Agent 设置中显式选择 auto_enroll_review，让未知私聊自动加入当前账号白名单但只生成待审核草稿；未知群聊不会自动纳入。auto_enroll_autopilot 选择后立即生效，仍受白名单、质量门和失败降级规则约束。欢迎语默认是幂等草稿，显式选择发送后才真实外发；失败可重试，无法确认发送结果时先人工核对。

只有在页面暂时无法读取联系人时，才需要使用下面的手工配置作为兜底；同时推荐复用 Fmode Studio 当前项目的 Claude Code 模型能力：

QIWEI_AUTO_REPLY_ALLOWED_SENDERS=<测试联系人 userId，多个用逗号分隔>
AGENT_PROVIDER=claude-code

企业版无需运行 Dashboard 或点击监听。MCP/Skill 会自动连接 Fmode 服务端全局回调并启动独立 Relay 守护进程；公网 Relay 持久排队，本地处理成功后才 ACK。登录状态和发送通过 Fmode 专用网关执行，技能包不接触上游企业微信接口凭据。

白名单为空时私聊回调仍会安全落盘，但不会进入 Agent 客户会话。默认使用审核模式；全局暂停和人工接管只停止 Agent 处理，不停止消息接收。状态、客户画像、待办、预警和审计记录写入 outputs/messages/。