Главная Обзор Помощь
Вход
18307996893
/
openclaw-voc-skill
2
2
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Дерево: 1820525e2b
Ветки Метки
openclaw-voc-sk...
/
claude-code
/
claude-code-qiwe-assistant
/
README.md

README.md 20 KB
История Исходник

企业微信助手技能包

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

  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/<类别>/（login、api-calls、subscription、meetings、docs、messages、groups、portraits、tags、broker-playbooks、transfers、voice、webhook、smoke、tmp），根目录可用 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_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、可选转写

Webhook 与 Relay

工具 说明
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。
  • 企业微信接口访问凭据和设备上下文由 Fmode 网关管理，不会出现在技能配置或返回结果中。

首次使用

  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，用于在浏览器中管理智能会话、客户群和账号状态等：

cd claude-code/claude-code-qiwe-assistant
npm run dashboard

启动后访问：

http://127.0.0.1:4320/

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

Dashboard 优先使用启动进程或 MCP 请求中注入的 QIWEI_AUTH_TOKEN、QIWEI_UID 和 QIWEI_API_BASE，其次读取项目根目录的 .env.local、Fmode/Claude Code 用户配置。进程级凭据优先于本机文件，避免 Fmode Studio 当前账号被旧的本机 token 覆盖。仍建议从项目目录启动，以便知识库、账号工作台和输出路径落在正确项目中。

端口与状态

  • 默认端口 4320，可通过 QIWEI_DASHBOARD_PORT 覆盖；
  • 健康检查：curl http://127.0.0.1:4320/api/health；
  • 状态汇总：curl http://127.0.0.1:4320/api/status。

智能会话演示

Dashboard 的「智能会话」页把真实消息监听、意图识别、需求画像、业务匹配、自动回复和人工协同放在同一页面。启停逻辑如下：

  • 点击「启动 AI 监听」后，AI 自动回复白名单测试联系人；
  • 点击「关闭 AI 监听」后，轮询器停止，切换为人工回复；
  • 真实发送只允许命中 QIWEI_AUTO_REPLY_ALLOWED_SENDERS 白名单的联系人；
  • 可对单个客户切换「人工接管 / 恢复 Agent」；
  • 首次启动会同步并跳过历史消息，避免把历史消息当成新消息重复处理。

推荐的现场顺序：

  1. 打开 http://127.0.0.1:4320/#agent，确认测试账号显示在线；
  2. 点击「启动 AI 监听」；
  3. 用唯一白名单测试联系人发送一条新消息；
  4. 查看意图、需求画像、匹配结果和建议回复；
  5. 点击「关闭 AI 监听」，演示切换为人工回复；
  6. 如需展示单客户协同，可重新启动后演示「人工接管 / 恢复 Agent」。

离线恢复

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

Claude Code/Fmode 项目主控架构

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

  1. 调用 qiwei_agent_dashboard_start 启动 4320 工作台；
  2. 完成企微登录并用 qiwei_agent_listener 控制监听；
  3. 用 qiwei_agent_set_global 设置暂停、待审核、自动或人工策略；
  4. 每个白名单客户绑定独立 Claude Code Session，通过 Fmode 模型配置生成草稿；
  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 修改项目文件。

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

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

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

第二条命令会在当前 Fmode Studio 项目终端中打开一个 fork 后的审阅会话，保留客户 Session 的完整历史、模型思考和工具记录；审阅过程中发送的新问题只进入副本，不会污染生产客户 Session。

安装到客户项目

本地源码包已经支持 workspace 安装：

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

安装器会写入：

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

安装过程不会复制 .env、.env.local、.npmrc、真实运行输出、客户 Session、Playwright 会话、压缩包或源码目录中的 node_modules。当前版本已通过发布检查，尚未发布到 npm；发布状态与上传检查见 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-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-real-estate-auto-reply skills/qiwei-real-estate-auto-reply/SKILL.md 客户独立 Claude Code Session、待审核草稿和人工接管 qiweiagent*、npm run agent:session

限制

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

房产 AI 智能会话

技能包内置 30 套脱敏房源以及客户、标签和匹配规则，可直接用于演示；正式客户数据可通过 QIWEI_AGENT_PROPERTY_DATA_FILE 覆盖。

先在 .env.local 配置测试联系人白名单，并推荐复用 Fmode Studio 当前项目的 Claude Code 模型能力：

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

然后运行 npm run dashboard，在 Dashboard「智能会话」页点击「启动 AI 监听」。登录状态通过 Fmode 专用端点读取，消息同步和发送通过 Fmode 网关执行；技能包只保存 Fmode 设备绑定信息，不接触上游企业微信接口凭据，也不保留本地直连接口。

白名单为空时监听器会拒绝启动。默认使用审核模式，关闭监听后自动切回人工模式；状态、客户画像、待办、预警和审计记录写入 outputs/messages/。