first

SKILL.md

@@ -0,0 +1,118 @@
+---
+name: lark-send-message-as-bot
+description: |
+  以 Bot 身份通过飞书发送消息。支持两种目标：
+  (1) 给个人用户发私聊消息（基于 user_id）
+  (2) 给群组发消息（基于 chat_id）
+  当 agent 需要主动推送消息、通知用户、向群组发送信息时使用。
+  触发场景：发消息、通知某人、推送到群、Bot 发消息、主动消息。
+---
+
+# 以 Bot 身份发送飞书消息
+
+## 前置条件
+
+- Bot 应用的凭证已配置在 `/root/.openclaw/credentials/<agent_name>/config.json`
+- 目标用户必须在 Bot 应用的**可用范围**内（开发者后台配置）
+- 目标群必须已将 Bot 添加为群成员
+
+## 发送消息
+
+### 获取 tenant_access_token
+
+所有发送操作前先获取 token：
+
+```bash
+APP_ID=$(jq -r '.apps[0].appId' /root/.openclaw/credentials/<agent_name>/config.json)
+APP_SECRET=$(jq -r '.apps[0].appSecret' /root/.openclaw/credentials/<agent_name>/config.json)
+
+TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
+  -H "Content-Type: application/json" \
+  -d "{\"app_id\":\"$APP_ID\",\"app_secret\":\"$APP_SECRET\"}" \
+  | jq -r '.tenant_access_token')
+```
+
+token 有效期 2 小时，同一批操作复用即可。
+
+### 给个人用户发消息
+
+使用 `receive_id_type=user_id`，`receive_id` 填租户级员工 ID：
+
+```bash
+curl -s -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=user_id" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "receive_id": "<user_id>",
+    "msg_type": "text",
+    "content": "{\"text\":\"消息内容\"}"
+  }'
+```
+
+### 给群组发消息
+
+使用 `receive_id_type=chat_id`，`receive_id` 填群 ID：
+
+```bash
+curl -s -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "receive_id": "<chat_id>",
+    "msg_type": "text",
+    "content": "{\"text\":\"消息内容\"}"
+  }'
+```
+
+## 消息类型
+
+`msg_type` 和 `content` 对应关系：
+
+| msg_type | content 格式 | 示例 |
+|----------|-------------|------|
+| text | `{"text":"纯文本"}` | 普通文本消息 |
+| post | `{"zh_cn":{"title":"标题","content":[[{"tag":"text","text":"正文"}]]}}` | 富文本（支持 @、链接、图片） |
+| interactive | 卡片 JSON | 消息卡片 |
+
+富文本 post 支持的 tag：`text`、`a`（链接）、`at`（@用户）、`img`（图片）。
+
+## ID 查询方式
+
+### 查询 user_id
+
+通过 Bot 所在群的成员列表获取（指定 `member_id_type=user_id`）：
+
+```bash
+LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
+  lark-cli im chat.members get \
+  --params '{"chat_id":"<群的chat_id>","member_id_type":"user_id"}' \
+  --as bot
+```
+
+返回结果中 `member_id` 即为 `user_id`。
+
+> **注意：** 不要使用 `open_id` 跨应用发消息，`open_id` 是应用级别的，不同 Bot 看到的同一用户 open_id 不同。`user_id` 是租户级唯一标识，所有 Bot 通用。
+
+### 查询 chat_id
+
+列出 Bot 所在的所有群：
+
+```bash
+LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
+  lark-cli im chats list --params '{}' --as bot --page-all
+```
+
+返回结果中每个群的 `chat_id` 和 `name` 一一对应。
+
+## 常见错误
+
+| 错误码 | 含义 | 解决方式 |
+|-------|------|---------|
+| 230013 | Bot has NO availability to this user | 在开发者后台将该用户加入应用的可用范围 |
+| 230001 | Bot is not in the chat | 将 Bot 添加到目标群 |
+
+## 安全规则
+
+- 发送前必须确认用户意图，禁止未经确认自动发送
+- 禁止在终端明文输出 `appSecret` 或 `accessToken`
+- `<agent_name>` 根据当前 agent 身份确定（如 xiaokui、xiaoxi、xiaoban 等），参考 `lark-action-as-bot` 技能的凭证目录表