---
name: feishu-push
description: >-
  向飞书指定用户（通过 user_id）推送消息。
  支持文本、卡片、图片、文件等多种消息类型。当用户需要给飞书用户发送推送消息时自动使用。
allowed-tools: Bash(curl *), node(*)
argument-hint: <user_id> <message-content> [msg_type]
---

# Feishu Push Message Skill

通过飞书开放平台 API 向指定飞书用户推送消息。

## 前提条件

1. 需要已经创建飞书自定义应用，并启用机器人能力
2. 应用已获取 `im:message`（或 `im:message:send_as_bot`）权限
3. 目标用户需要在应用的可用范围内
4. 需要配置以下环境变量或凭据：
   - `FEISHU_APP_ID`: 飞书应用 App ID (如 `cli_a94a1d897cb85cbb`)
   - `FEISHU_APP_SECRET`: 飞书应用 App Secret

## API 端点

```
POST https://open.feishu.cn/open-apis/im/v1/messages
```

## 使用方式

### 命令行方式（curl）

```bash
# 获取 tenant_access_token
TOKEN=$(curl -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d "{\"app_id\":\"$FEISHU_APP_ID\",\"app_secret\":\"$FEISHU_APP_SECRET\"}" | \
  node -e "let s=''; process.stdin.on('data', c => s += c); process.stdin.on('end', () => console.log(JSON.parse(s).tenant_access_token));")

# 发送文本消息
curl --request POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=user_id" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json; charset=utf-8" \
  --data-raw '{
    "receive_id": "<USER_ID>",
    "msg_type": "text",
    "content": "{\"text\":\"你的消息内容\"}"
  }'
```

### 接收者 ID 类型

当前技能只接收飞书租户内用户 ID，即 `receive_id_type=user_id`。调用时传入的第一个参数必须是 `user_id`。

### 支持的消息类型

| msg_type | 说明 |
|----------|------|
| `text` | 文本消息 |
| `post` | 富文本消息 |
| `image` | 图片消息（需要先上传图片获取 key）|
| `file` | 文件消息（需要先上传文件获取 key）|
| `audio` | 音频消息 |
| `media` | 视频消息 |
| `sticker` | 表情 |
| `interactive` | 互动卡片 |
| `share_chat` | 分享群名片 |
| `share_user` | 分享个人名片 |
| `system` | 系统消息（仅单会话有效）|

## 示例

### 发送文本消息给指定 user_id 用户

```bash
# 用法: feishu-push text <user_id> "你的消息内容"
```

### 环境变量配置

推荐在环境中配置应用凭证：
```bash
export FEISHU_APP_ID="cli_a94a1d897cb85cbb"
export FEISHU_APP_SECRET="your_app_secret_here"
```

## 错误处理

常见错误码及处理：

- `230013`: Bot 对该用户无可用权限 → 将用户添加到应用可用范围
- `230006`: 未启用机器人能力 → 在飞书开发者后台启用 bot 能力
- `230029`: 用户已离职 → 无法发送给已离职用户
- `230053`: 用户停止接收机器人消息 → 用户需要取消拉黑

## NodeJS 示例

```js
const tokenUrl = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal";
const messageUrl = "https://open.feishu.cn/open-apis/im/v1/messages";

async function postJson(url, payload, headers = {}) {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json; charset=utf-8",
      ...headers,
    },
    body: JSON.stringify(payload),
  });
  return response.json();
}

async function getTenantAccessToken() {
  const data = await postJson(tokenUrl, {
    app_id: process.env.FEISHU_APP_ID,
    app_secret: process.env.FEISHU_APP_SECRET,
  });

  if (data.code !== 0) {
    throw new Error(`Failed to get token: ${data.msg}`);
  }

  return data.tenant_access_token;
}

async function sendTextMessage(userId, content) {
  const token = await getTenantAccessToken();

  return postJson(
    `${messageUrl}?receive_id_type=user_id`,
    {
      receive_id: userId,
      msg_type: "text",
      content: JSON.stringify({ text: content }),
    },
    {
      Authorization: `Bearer ${token}`,
    },
  );
}

const [, , userId, message] = process.argv;
if (userId && message) {
  const result = await sendTextMessage(userId, message);
  console.log(JSON.stringify(result, null, 2));
}
```

## 调用示例

```
/feishu-push 给用户 7g9f6e2d 发送文本消息 "Hello from OpenClaw!"
/feishu-push send user_id 7g9f6e2d "这是一条测试推送消息"
```