# 企业微信助手技能包

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

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

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

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

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

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

## 组成

```text
├── .mcp.json
├── .env.example
├── bin/qiwe-official-cli.js
├── wecom-cli-runtime.json
├── mcp/
│   ├── catalog/qiwe-endpoints.json
│   └── src/
│       ├── server.js
│       ├── core/api-catalog.js
│       ├── core/wecom-cli-runtime.js
│       ├── core/credentials.js
│       ├── providers/fmode-wecom-gateway.js
│       ├── providers/wecom-official-cli.js
│       └── tools/
│           ├── qiwe-api-catalog-run.js
│           ├── qiwe-login-run.js
│           ├── qiwe-subscription-run.js
│           └── wecom-official-cli-run.js
├── skills/
│   ├── qiwe-api-catalog/SKILL.md
│   ├── qiwe-login/SKILL.md
│   ├── qiwe-capability-router/SKILL.md
│   ├── qiwe-official-meeting/SKILL.md
│   └── qiwe-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`、`smoke`、`tmp`），根目录可用 `QIWE_OUTPUTS_DIR` 覆盖；
- 覆盖型文件用 latest 模式（如 `outputs/login/qiwe-login-qrcode.png`），按次归档用 run 模式（`outputs/<类别>/<YYYY-MM-DD>/<HHmmss>-<slug>/` + `manifest.json`）；
- 路径一律通过 `mcp/src/core/output-paths.js` 解析；
- 校验：`npm run outputs:validate`。

## MCP 工具

| 工具 | 说明 |
|---|---|
| `qiwe_api_search` | 检索 100+ 个企业微信接口 |
| `qiwe_api_doc` | 查看参数、返回字段和调用模板 |
| `qiwe_api_call` | `POST /api/qiwe/doApi`，传 `{uid, method, params}` |
| `qiwe_login_status` | `GET /api/qiwe/login/status?uid=` |
| `qiwe_login_start` | `POST /api/qiwe/login/start` 并保存二维码 |
| `qiwe_login_check` | `POST /api/qiwe/login/check` |
| `qiwe_login_verify` | `POST /api/qiwe/login/verify` |
| `qiwe_subscription_status` | 查询订阅、席位、到期时间和余额 |
| `qiwe_subscribe` | 开通、续费或增购席位 |
| `qiwe_subscription_auto_renew` | 设置自动续费 |
| `qiwe_official_status` | 检查官方 CLI 下载与授权状态 |
| `qiwe_official_prepare` | 下载并缓存固定版本官方 CLI |
| `qiwe_official_help` | 读取官方 category/method 帮助 |
| `qiwe_official_call` | 结构化调用官方通讯录、文档、会议、消息、日程和待办能力 |

## 官方 CLI 通道

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

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

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

可以让 Skill 首次使用时调用 `qiwe_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、`QIWE_UID` 和个人企微设备登录完全独立。

## 鉴权和本地配置

- 请求头统一为 `Authorization: Bearer <Fmode token>`。
- 优先自动读取 Claude Code 已配置的 Fmode NewAPI `sk-` token。
- 也支持 `QIWE_AUTH_TOKEN`、`FMODE_API_KEY`、`FMODE_API_TOKEN`、`NEWAPI_TOKEN` 或平台 sessionToken。
- `QIWE_API_BASE` 默认 `https://server.fmode.cn/api/qiwe`。
- `QIWE_UID` 是客户端设备别名；未配置时会生成随机稳定 uid，并写入 `.env.local` 和 `~/.claude/qiwe-credentials.json`。
- 企业微信接口访问凭据和设备上下文由 Fmode 网关管理，不会出现在技能配置或返回结果中。

## 首次使用

1. `qiwe_subscription_status` 检查订阅；
2. 未订阅时调用 `qiwe_subscribe`，`seats` 表示企微账号席位数；
3. `qiwe_login_start` 生成二维码；
4. 用户扫码后每 3–5 秒调用 `qiwe_login_check`；
5. 状态 `10` 时用 `qiwe_login_verify` 提交 6 位验证码；
6. 状态 `2` 后用 `qiwe_api_call` 调业务接口。

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

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

## 安装与验证

```bash
npm install
npm run check
npm run smoke
npm run outputs:validate
```

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

## 限制

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