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

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

1. **个人版**：本地主动监听、单企微设备和本地数据；
2. **企业版**：服务端统一回调、多企微设备消息归集、租户隔离和企业管理底座。

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

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

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

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

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

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

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

## 组成

```text
├── .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](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_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 并真实发送企微语音 |

### 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`，也可以提前下载：

```bash
npm run wecom:install
```

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

```bash
npm run wecom:init
```

检查状态：

```bash
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 网关管理，不会出现在技能配置或返回结果中。

## 快速启动与预览

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

```text
启动并预览企微助手
```

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

源码开发也可以执行：

```bash
npm run preview
```

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

```bash
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` 调业务接口。

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

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

## 安装与验证

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

```bash
npm run preview
```

启动后访问：

```text
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`。
- 健康检查包含当前项目的 `workspaceId`，用于阻止不同项目误用同一个 4320 服务。

### 智能会话演示

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

- 点击「管理白名单」，从当前企微外部联系人中搜索并勾选允许 Agent 处理的客户；
- 企业版由 MCP/Skill 自动连接公网回调并启动独立 Relay 守护进程；Dashboard 关闭后仍持续接收，离线期间的消息保留在服务端队列；
- 个人版仍可点击「启动 AI 监听」，仅处理已选白名单联系人；
- 已确认的客户群会进入独立的「群聊智能回复」列表，Agent 自动生成草稿，但必须人工编辑或审核后才能发送到群；
- 企业版通过全局 `paused` 或单会话人工接管停止 Agent 处理，但消息仍持续接收并保存；
- 真实发送只允许命中 `QIWEI_AUTO_REPLY_ALLOWED_SENDERS` 白名单的联系人；
- 客服输入文本后可自动识别「自然、友好、真诚致歉、温和关怀、明确提醒」，人工确认后直接生成并发送本人音色的原生企微语音；试听默认禁用，避免额外产生一次云端合成费用；
- 语音媒体只通过已验证的 Fmode `/doFileApi` multipart 路由直接上传，路由不可用时直接报错，不暴露公网音频回源地址；
- 「本人声音」支持浏览器录音或音频上传，参考录音按企微账号隔离，注销后删除；
- 已发送语音在消息流中显示为语音气泡，点击气泡播放或暂停；左侧「转文字」直接展开合成时保存的准确原文，不会再次调用语音识别服务；
- 使用待审核草稿发送语音成功后，该草稿会同步结算为已发送并关联语音消息，文字操作区恢复为「让 Agent 处理」，避免同一回复再次以文字发送；
- 可对单个客户切换「人工接管 / 恢复 Agent」；
- 未初始化的客户 Claude Code Session 可在工作台一键首次运行并生成待审核草稿；已初始化 Session 仍通过现有说明和命令打开隔离审阅副本；
- 首次启动会同步并跳过历史消息，避免把历史消息当成新消息重复处理。

推荐的现场顺序：

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

### 离线恢复

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

## 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，通过 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。

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：

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

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

## 安装到客户项目

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

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

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

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

安装器会写入：

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

安装过程不会复制 `.env`、`.env.local`、`.npmrc`、真实运行输出、客户 Session、Playwright 会话、压缩包或源码目录中的 `node_modules`。当前公开版本为 `fmode-qiwei@0.4.3`；版本与验证记录见 `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_group_ops_* |
| 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-real-estate-auto-reply | skills/qiwei-real-estate-auto-reply/SKILL.md | 客户独立 Claude Code Session、待审核草稿和人工接管 | qiwei_agent_*、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` 覆盖。

启动 Dashboard 后，在「智能会话」页点击「管理白名单」，直接从企微联系人中搜索并勾选客户。保存后立即生效并写入客户项目 `.env.local`，无需手工查找联系人 ID 或重启技能包。

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

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

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

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