wecome-send-message

# 企业微信 API Skill

## 触发条件

当用户说以下任意内容时启动：
- `/wecom-api`
- "发企微消息给 XX"
- "在企微上通知 XX"
- "查一下 XX 的企微"
- "给 XX 发个通知"
- "企微推送"
- "wecom send"

---

## 工具使用规则

本 Skill 运行在 Claude Code 环境，使用以下工具：

| 任务 | 使用工具 |
|------|---------|
| 检查配置状态 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py check` |
| 写入 Skill 私有配置 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py setup --corp-id "xxx" --agent-id "1000002" --secret "xxx"` |
| 验证 API 连接 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py verify` |
| 通过姓名查用户 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-name --name "XX"` |
| 通过手机号查用户 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-mobile --mobile "138xxxx"` |
| 通过邮箱查用户 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-email --email "[email protected]"` |
| 获取用户详情 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py user-info --userid "XX"` |
| 发送文本消息 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text --to "userid" --content "内容"` |
| 发送 Markdown 消息 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-markdown --to "userid" --content "内容"` |
| 发送卡片消息 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-card --to "userid" --title "标题" --desc "描述" --url "链接"` |
| 群发/全员发送预览 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text --to "a|b" --content "内容" --preview` |
| 查看最近发送审计日志 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py history --limit 10` |
| 获取部门列表 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py dept-list` |
| 获取部门成员 | `Bash` → `python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py dept-users --dept-id 1 --recursive` |

前置依赖：
- 已安装 Python 3
- 已安装 `requests`：`pip install requests`

---

## 主流程

### Step 0：首次使用 — 初始化配置

每次执行任务前，先检查配置状态：

```bash
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py check
```

如果返回 `"ready": false`，进入初始化引导流程：

#### 引导话术

```
企业微信 API 需要先配置凭证才能使用。你需要准备以下信息：

  1. CorpID（企业 ID）
     → 企业微信管理后台 → 我的企业 → 页面底部

  2. AgentID（应用 ID）
     → 应用管理 → 你的自建应用 → 应用详情页

  3. Secret（应用密钥）
     → 同上，应用详情页

  4. Contact Secret（通讯录密钥，可选）
     → 管理工具 → 通讯录同步 → Secret
     → 如果 IT 没有单独提供，可以先跳过，会用应用 Secret 兜底

还没有自建应用？需要在企微管理后台申请创建，或者联系你们的 IT 管理员走工单流程。
申请时需要提供：应用名称、可见范围、应用图标、用途说明。

已经有了？请把这些值告诉我，我来帮你配置。
```

#### 配置方式

用户提供凭证后，引导用户通过以下方式之一配置。推荐优先使用 Skill 私有 `.env`，这样在 OpenClaw workspace 中更可控。

**方式 A：Skill 私有 setup（推荐）**

```bash
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py setup \
  --corp-id "你的企业ID" \
  --agent-id "你的AgentID" \
  --secret "你的应用Secret" \
  --contact-secret "你的通讯录Secret"
```

这会把配置写到 `${CLAUDE_SKILL_DIR}/.env`，并默认把 token 缓存和运行状态放到 skill 私有目录：
- `${CLAUDE_SKILL_DIR}/.cache/`
- `${CLAUDE_SKILL_DIR}/.state/`

之后执行：
```bash
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py verify
```

---

**方式 B：OpenClaw Secrets**

如果用户使用 OpenClaw，提示通过 secrets 管理：
```
请在 OpenClaw 中执行以下命令配置 secrets：

openclaw secrets set WECOM_CORP_ID "你的企业ID"
openclaw secrets set WECOM_AGENT_ID "你的AgentID"
openclaw secrets set WECOM_SECRET "你的应用Secret"
openclaw secrets set WECOM_CONTACT_SECRET "你的通讯录Secret"  # 可选
```

**方式 C：手动设置环境变量**

Linux / macOS:
```bash
export WECOM_CORP_ID="你的企业ID"
export WECOM_AGENT_ID="你的AgentID"
export WECOM_SECRET="你的应用Secret"
export WECOM_CONTACT_SECRET="你的通讯录Secret"  # 可选
```

PowerShell:
```powershell
$env:WECOM_CORP_ID="你的企业ID"
$env:WECOM_AGENT_ID="你的AgentID"
$env:WECOM_SECRET="你的应用Secret"
$env:WECOM_CONTACT_SECRET="你的通讯录Secret"  # 可选
```

**方式 D：手动写入 .env 文件**

直接在 `${CLAUDE_SKILL_DIR}/.env` 创建文件，例如：

```dotenv
WECOM_CORP_ID=你的企业ID
WECOM_AGENT_ID=你的AgentID
WECOM_SECRET=你的应用Secret
WECOM_CONTACT_SECRET=你的通讯录Secret
WECOM_CACHE_DIR=./.cache
```

OpenClaw / workspace 场景下，默认只读取 `${CLAUDE_SKILL_DIR}/.env`，避免误读当前工作目录下其他项目的 `.env`。
如果确实需要自定义位置，先设置 `WECOM_ENV_FILE`，再执行命令，例如：

```bash
export WECOM_ENV_FILE="/path/to/wecom.env"
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py verify
```

PowerShell:
```powershell
$env:WECOM_ENV_FILE="C:\\path\\to\\wecom.env"
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py verify
```

配置完成后，验证连接：
```bash
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py verify
```

如果返回 `"success": true`，配置完成，进入正常使用流程。

---

### Step 1：理解用户意图

用户的请求通常是以下几类：

| 用户说的话 | 意图 | 需要的操作 |
|-----------|------|-----------|
| "给张三发消息说明天开会" | 发消息 | 先查 UserID → 再发消息 |
| "通知研发部全员版本已发布" | 群发 | 查部门 → 获取成员 → 批量发送 |
| "查一下李四的企微信息" | 查通讯录 | 按姓名/手机/邮箱搜索 |
| "发个 markdown 格式的周报给老板" | 发 Markdown | 查 UserID → 发 Markdown |

---

### Step 2：查找目标用户

如果用户提供了姓名而非 UserID，需要先查找：

**优先级：姓名 → 手机号 → 邮箱 → 部门浏览**

```bash
# 按姓名搜索（模糊匹配）
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-name --name "张三"

# 按手机号精确查找
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-mobile --mobile "13800138000"

# 按邮箱精确查找
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-email --email "[email protected]"
```

如果搜索到多个匹配结果，展示给用户确认：
```
找到以下匹配用户：
  1. 张三（研发部）- UserID: zhangsan
  2. 张三丰（产品部）- UserID: zhangsanfeng

你要发给哪一位？
```

如果搜索不到，提示可能原因：
- 该用户不在应用的可见范围内
- 姓名输入有误
- 需要通讯录权限（WECOM_CONTACT_SECRET）

---

### Step 3：发送消息

确认目标用户后，根据消息类型选择发送方式：

**文本消息**（默认）：
```bash
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text \
  --to "zhangsan" \
  --content "明天上午10点开会，请准时参加。"
```

**Markdown 消息**（适合格式化内容）：
```bash
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-markdown \
  --to "zhangsan" \
  --content "## 会议通知\n> 时间：明天 10:00\n> 地点：3楼会议室\n\n请准时参加。"
```

**文本卡片消息**（带跳转链接）：
```bash
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-card \
  --to "zhangsan" \
  --title "周报已提交" \
  --desc "点击查看详情" \
  --url "https://example.com/report"
```

**多人发送**：UserID 用 `|` 分隔：
```bash
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text \
  --to "zhangsan|lisi|wangwu" \
  --content "提醒：今天下班前提交周报" \
  --preview
```

**全员发送**：使用 `@all`：
```bash
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text \
  --to "@all" \
  --content "系统维护通知：今晚 22:00-23:00 系统升级" \
  --preview
```

对于多人发送和 `@all`：
- 默认只允许先输出预览，避免误发
- 真正发送时，必须在确认后追加 `--yes`

示例：
```bash
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text \
  --to "zhangsan|lisi|wangwu" \
  --content "提醒：今天下班前提交周报" \
  --yes
```

---

### Step 4：确认发送结果

检查 API 返回值：
- `errcode: 0` → 发送成功，告知用户
- `errcode: 60020` / `invaliduser` → 用户不在可见范围，建议联系 IT 扩大应用可见范围
- `errcode: 40014` → access_token 过期，自动清理本地缓存并重试一次
- 其他错误 → 展示错误码和描述，建议用户检查配置

每次真正发送后，都会写入 `${CLAUDE_SKILL_DIR}/.state/message_audit.json` 审计日志。
如需查看最近记录：

```bash
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py history --limit 10
```

成功后的回复示例：
```
已通过企微向 张三 发送消息：「明天上午10点开会，请准时参加。」
```

---

## 错误处理

| 错误码 | 含义 | 处理方式 |
|--------|------|---------|
| 40001 | Secret 无效 | 提示用户检查 WECOM_SECRET |
| 40014 | access_token 过期 | 清除缓存重新获取 |
| 41001 | 缺少 access_token | 检查配置是否完整 |
| 60011 | 无通讯录权限 | 提示配置 WECOM_CONTACT_SECRET |
| 60020 | 接收者不在可见范围 | 提示联系 IT 扩大应用可见范围 |
| 81013 | 接收者 UserID 无效 | 重新搜索确认 UserID |
| -2 | 网络请求失败 | 检查网络、代理、企业微信 API 可达性 |
| -3 | 接口返回非 JSON | 检查网关、代理或接口异常页面 |

---

## 安全注意事项

1. **绝不在代码或日志中明文输出 Secret** — 所有凭证通过环境变量传入
2. **access_token 缓存在 Skill 私有目录** — 默认路径 `${CLAUDE_SKILL_DIR}/.cache/`，2 小时自动过期
3. **运行状态独立存放** — 运行状态和发送审计日志默认位于 `${CLAUDE_SKILL_DIR}/.state/`
4. **发送消息前确认** — 对于群发（多人或 @all）场景，默认要求先预览，再显式追加 `--yes`
5. **通讯录信息敏感** — 查询结果中的手机号、邮箱等不要在不必要的场景下展示

如需改缓存位置，可显式设置 `WECOM_CACHE_DIR`：

```bash
export WECOM_CACHE_DIR="/path/to/wecom-cache"
```

PowerShell:
```powershell
$env:WECOM_CACHE_DIR="C:\\path\\to\\wecom-cache"
```

如果写相对路径，例如 `./.cache`，会按 `${CLAUDE_SKILL_DIR}` 解析，而不是按当前 workspace 目录解析。

---

## 常见使用场景

### 场景 1：快速通知某人
```
用户：「告诉张三明天开会」
→ search-name "张三" → 找到 userid → send-text → 完成
```

### 场景 2：部门群发
```
用户：「通知研发部全员版本已发布」
→ dept-list 找到研发部 ID → dept-users 获取成员 → 拼接 userid → send-text → 完成
```

### 场景 3：格式化通知
```
用户：「发个 markdown 格式的上线通知给运维组」
→ 查找运维组成员 → 构造 markdown 内容 → send-markdown → 完成
```

### 场景 4：查人
```
用户：「帮我查一下工号 20260690 对应的人」
→ 如果知道 userid 直接 user-info，否则需要通过其他方式搜索
```