返回 Skills
wecomteam/wecom-cli· MIT 内容可用

wecomcli-msg

企业微信消息技能。提供会话列表查询、消息记录拉取（支持文本/图片/文件/语音/视频）、多媒体文件获取和文本消息发送能力。当用户需要"查看消息"、"看聊天记录"、"发消息给某人"、"最近有什么消息"、"给群里发消息"、"看看发了什么图片/文件"时触发。

安装

与 skills.sh 相同的 Command / Prompt 安装方式

name: wecomcli-msg description: 企业微信消息技能。提供会话列表查询、消息记录拉取（支持文本/图片/文件/语音/视频）、多媒体文件获取和文本消息发送能力。当用户需要"查看消息"、"看聊天记录"、"发消息给某人"、"最近有什么消息"、"给群里发消息"、"看看发了什么图片/文件"时触发。 metadata: requires: bins: ["wecom-cli"] cliHelp: "wecom-cli msg --help"

企业微信消息技能

wecom-cli 是企业微信提供的命令行程序，所有操作通过执行 wecom-cli 命令完成。

通过 wecom-cli msg <接口名> '<json入参>' 与企业微信消息系统交互。

接口列表

get_msg_chat_list — 获取会话列表

wecom-cli msg get_msg_chat_list '{"begin_time": "2026-03-11 00:00:00", "end_time": "2026-03-17 23:59:59"}'

按时间范围查询有消息的会话列表，支持分页。参见 API 详情。

get_message — 拉取会话消息

wecom-cli msg get_message '{"chat_type": 1, "chatid": "zhangsan", "begin_time": "2026-03-17 09:00:00", "end_time": "2026-03-17 18:00:00"}'

根据会话类型和 ID 拉取指定时间范围内的消息记录，支持分页。支持 text/image/file/voice/video 消息类型，仅支持 7 天内。参见 API 详情。

get_msg_media — 获取消息文件内容

wecom-cli msg get_msg_media '{"media_id": "MEDIAID_xxxxxx"}'

根据文件 ID 自动下载文件到本地，返回文件的本地路径（local_path）、名称、类型、大小及 MIME 类型。用于获取图片、文件、语音、视频等非文本消息的实际内容。参见 API 详情。

send_message — 发送文本消息

wecom-cli msg send_message '{"chat_type": 1, "chatid": "zhangsan", "msgtype": "text", "text": {"content": "hello world"}}'

向单聊或群聊发送文本消息。参见 API 详情。

核心规则

时间范围规则

  • 格式：所有时间参数使用 YYYY-MM-DD HH:mm:ss 格式
  • 默认范围：用户未指定时，默认使用最近7天（当前时间往前推7天）
  • 限制：开始时间不能早于当前时间的7天前，不能晚于当前时间
  • 相对时间支持：支持"昨天"、"最近三天"等自动推算

chatid查找规则

  • 当用户提供人名或群名而非ID时：
    1. 调用 get_msg_chat_list 获取会话列表（时间范围与目标查询一致）
    2. 在 chats 中按 chat_name 匹配
    3. 匹配策略：
      • 精确匹配唯一结果：直接使用
      • 模糊匹配多个结果：展示候选列表让用户选择
      • 无匹配结果：告知用户未找到
  • chat_type 判断：get_msg_chat_list 返回中不含会话类型字段，需根据上下文推断：用户明确提到「群」时使用 chat_type=2，否则默认 chat_type=1（单聊）

userid 转 name

流程：

  1. 调用 wecomcli-contact 技能的 get_userlist 获取用户列表
  2. 建立 userid 到 name 的映射关系
  3. 展示策略：
    • 精确匹配：显示 name
    • 无匹配：保持显示 userid

强制交互步骤（不可跳过）

以下步骤在涉及非文本消息下载时必须逐一执行，不得合并、省略或跳过，即使用户未主动询问也必须执行：

  1. 必须主动告知文件位置：下载完成后必须立即向用户展示所有文件的完整路径和存放目录
  2. 必须询问是否删除：告知位置后必须立即询问用户是否需要清理临时文件

典型工作流

查看会话列表

用户query示例：

  • "看看我最近一周有哪些聊天"
  • "这几天谁给我发过消息"

执行流程：

  1. 确定时间范围（用户指定或默认最近7天）
  2. 调用 get_msg_chat_list 获取会话列表
  3. 展示会话名称、最后消息时间、消息数量
  4. 若 has_more 为 true，告知用户还有更多会话可继续查看

查看聊天记录

用户query示例：

  • "帮我看看和张三最近的聊天记录"
  • "看看项目群里最近的消息"

执行流程：

  1. 确定时间范围（用户指定或默认最近7天）
  2. 通过 chatid查找规则 确定目标会话的 chatid 和 chat_type
  3. 调用 get_message 拉取消息列表
  4. 调用 wecomcli-contact 技能的 get_userlist 获取通讯录，建立 userid→姓名 映射
  5. 统计非文本消息：遍历消息列表，统计 msgtype 非 text 的消息（image/file/voice/video）数量和类型
  6. 展示消息时将 userid 替换为可读姓名，格式：
    • 文本消息：姓名 [时间]: 内容
    • 图片消息：姓名 [时间]:[图片]
    • 文件消息：姓名 [时间]:[文件] 文件名称
    • 语音消息：姓名 [时间]:[语音] 语音内容
    • 视频消息：姓名 [时间]:[视频]
  7. 非文本消息处理：展示完消息后，如果存在非文本消息：
    • 主动询问是否下载：告知用户非文本消息数量和类型（如："以上聊天中包含 2 张图片、1 个文件，是否需要下载到本地？"）
    • 用户确认后，逐个调用 get_msg_media 接口，接口会自动下载文件并返回 local_path
    • 检查文件后缀：每个文件下载完成后，检查 local_path 对应的文件是否具有正确的后缀名：
      • 根据 get_msg_media 返回的 content_type（MIME 类型）和 name 字段判断：
        • 如果文件名缺少后缀（如 screenshot 而非 screenshot.png），根据 content_type 自动补上正确后缀（如 image/png → .png，application/pdf → .pdf，audio/amr → .amr，video/mp4 → .mp4）
        • 如果文件名后缀与 content_type 不一致，以 content_type 为准进行修正
      • 补全或修正后缀后，将文件重命名为正确的文件名
      • 确认文件可正常读取（文件大小 > 0），若文件为空或损坏则告知用户该文件下载异常
    • ⚠️ 不要对下载的文件使用 MEDIA: 指令：这些文件是从聊天记录中下载的历史附件，仅需告知用户本地存放路径即可，严禁通过 MEDIA: 指令重新发送给用户
  8. ⚠️ 必须主动告知文件位置（此步骤不可跳过）：所有文件下载并检查完成后，必须立即、主动以汇总形式向用户展示文件存放目录和每个文件的完整路径，不要等用户询问。示例：

    📁 文件已下载到以下位置：

    • 图片：xxx/yyy.png
    • 文件：xxx/yyy.pdf

    你可以在 xxx/yyy/ 目录下找到所有下载的文件。

  9. ⚠️ 必须询问是否删除（此步骤不可跳过）：告知文件位置后，必须立即、主动询问用户是否需要删除已下载的临时文件（如："如果不再需要这些文件，是否需要我帮你清理？"）
    • 用户确认删除后，删除 local_path 对应的文件
    • 用户不需要删除则保留文件
  10. 若 next_cursor 不为空，告知用户还有更多消息可继续查看

发送消息

用户query示例：

  • "帮我给张三发一条消息：明天会议改到下午3点"
  • "在项目群里发一条消息：今天下午3点开会"

执行流程：

  1. 通过 chatid查找规则 确定目标会话的 chatid 和 chat_type
  2. 发送前确认：向用户确认发送对象和内容（如："即将向 张三 发送：'明天会议改到下午3点'，确认发送吗？"），用户确认后再执行
  3. 调用 send_message 发送（msgtype 固定为 text）
  4. 展示发送结果

查看消息并回复

用户query示例：

  • "看看张三给我发了什么，然后帮我回复收到"

执行流程：

  1. 先执行"查看聊天记录"流程（复用已获取的 chatid 和 chat_type）
  2. 展示消息后，执行"发送消息"流程（需确认后再发送）

错误处理

  • 时间范围超限：告知用户7天限制并调整为有效范围
  • 会话未找到：明确告知用户未找到对应会话
  • API错误：展示具体错误信息，必要时重试
  • 网络问题：HTTP错误时主动重试最多3次

附带文件

references/get-message.md
# get_message API

根据会话类型和会话 ID，拉取指定时间范围内的消息记录。支持文本、图片、文件、语音、视频类型消息。

## 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `chat_type` | integer | ✅ | 会话类型，`1`-单聊，`2`-群聊 |
| `chatid` | string | ✅ | 会话 ID，单聊时为 userid，群聊时为群 ID，最大 256 字节 |
| `begin_time` | string | ✅ | 拉取开始时间，格式：`YYYY-MM-DD HH:mm:ss`，仅支持请求时刻往前 **7 天**内 |
| `end_time` | string | ✅ | 拉取结束时间，格式：`YYYY-MM-DD HH:mm:ss`，必须 ≥ `begin_time` |
| `cursor` | string | ❌ | 分页游标，首次请求不传，后续传入上次响应的 `next_cursor`，最大 256 字节 |

## 请求示例

单聊：

```bash
wecom-cli msg get_message '{"chat_type": 1, "chatid": "zhangsan", "begin_time": "2026-03-17 09:00:00", "end_time": "2026-03-17 18:00:00"}'
```

群聊：

```bash
wecom-cli msg get_message '{"chat_type": 2, "chatid": "wrxxxxxxxx", "begin_time": "2026-03-17 09:00:00", "end_time": "2026-03-17 18:00:00"}'
```

分页请求：

```bash
wecom-cli msg get_message '{"chat_type": 1, "chatid": "zhangsan", "begin_time": "2026-03-17 09:00:00", "end_time": "2026-03-17 18:00:00", "cursor": "CURSOR_xxxxxx"}'
```

## 返回字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `errcode` | integer | 返回码，`0` 表示成功 |
| `errmsg` | string | 错误信息 |
| `messages` | array | 消息列表 |
| `messages[].userid` | string | 消息发送者的 userid |
| `messages[].send_time` | string | 消息发送时间（北京时间），格式：`YYYY-MM-DD HH:mm:ss` |
| `messages[].msgtype` | string | 消息类型，`text`-文本消息，`image`-图片消息，`file`-文件消息，`voice`-语音消息，`video`-视频消息 |
| `messages[].text` | object | 文本消息内容，`msgtype` 为 `text` 时返回 |
| `messages[].text.content` | string | 消息内容 |
| `messages[].image` | object | 图片消息内容，`msgtype` 为 `image` 时返回 |
| `messages[].image.media_id` | string | 图片的 media_id，可通过 `get_msg_media` 接口下载 |
| `messages[].image.name` | string | 图片文件名称 |
| `messages[].file` | object | 文件消息内容，`msgtype` 为 `file` 时返回 |
| `messages[].file.media_id` | string | 文件的 media_id，可通过 `get_msg_media` 接口下载 |
| `messages[].file.name` | string | 文件名称 |
| `messages[].voice` | object | 语音消息内容，`msgtype` 为 `voice` 时返回 |
| `messages[].voice.media_id` | string | 语音的 media_id，可通过 `get_msg_media` 接口下载 |
| `messages[].video` | object | 视频消息内容，`msgtype` 为 `video` 时返回 |
| `messages[].video.media_id` | string | 视频的 media_id，可通过 `get_msg_media` 接口下载 |
| `next_cursor` | string | 分页游标，为空表示已拉取完毕 |

## 响应示例

```json
{
    "errcode": 0,
    "errmsg": "ok",
    "messages": [
        {
            "userid": "zhangsan",
            "send_time": "2026-03-17 09:30:00",
            "msgtype": "text",
            "text": {
                "content": "你好"
            }
        },
        {
            "userid": "lisi",
            "send_time": "2026-03-17 09:35:00",
            "msgtype": "image",
            "image": {
                "media_id": "MEDIAID_xxxxxx",
                "name": "screenshot.png"
            }
        },
        {
            "userid": "zhangsan",
            "send_time": "2026-03-17 09:40:00",
            "msgtype": "file",
            "file": {
                "media_id": "MEDIAID_yyyyyy",
                "name": "report.pdf"
            }
        }
    ],
    "next_cursor": "CURSOR_xxxxxx"
}
```

## 非文本消息处理

当 `msgtype` 为 `image`、`file`、`voice`、`video` 时，消息体中包含 `media_id`。需要调用 [get_msg_media](get-msg-media.md) 接口获取文件的本地路径（`local_path`），再进行展示。
references/get-msg-chat-list.md
# get_msg_chat_list API

获取指定时间范围内有消息的会话列表，支持分页查询。

## 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `begin_time` | string | ✅ | 拉取开始时间，格式：`YYYY-MM-DD HH:mm:ss` |
| `end_time` | string | ✅ | 拉取结束时间，格式：`YYYY-MM-DD HH:mm:ss` |
| `cursor` | string | ❌ | 分页游标，首次请求不传，后续传入上次响应的 `next_cursor`，最大长度 256 |

## 请求示例

```bash
wecom-cli msg get_msg_chat_list '{"begin_time": "2026-03-11 00:00:00", "end_time": "2026-03-17 23:59:59"}'
```

分页请求：

```bash
wecom-cli msg get_msg_chat_list '{"begin_time": "2026-03-11 00:00:00", "end_time": "2026-03-17 23:59:59", "cursor": "NEXT_CURSOR"}'
```

## 返回字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `errcode` | integer | 返回码，`0` 表示成功 |
| `errmsg` | string | 错误信息 |
| `chats` | array | 会话列表 |
| `chats[].chat_id` | string | 会话 ID |
| `chats[].chat_name` | string | 会话名称 |
| `chats[].last_msg_time` | string | 最后一条消息时间，格式：`YYYY-MM-DD HH:mm:ss` |
| `chats[].msg_count` | integer | 消息数量 |
| `has_more` | boolean | 是否还有更多数据 |
| `next_cursor` | string | 分页游标，用于下一次请求 |

## 响应示例

```json
{
    "errcode": 0,
    "errmsg": "ok",
    "chats": [
        {
            "chat_id": "CHAT_ID",
            "chat_name": "张三",
            "last_msg_time": "2026-03-17 15:30:45",
            "msg_count": 128
        },
        {
            "chat_id": "CHAT_ID_2",
            "chat_name": "项目讨论群",
            "last_msg_time": "2026-03-16 09:12:33",
            "msg_count": 56
        }
    ],
    "has_more": true,
    "next_cursor": "NEXT_CURSOR"
}
```
references/get-msg-media.md
# get_msg_media API

获取消息文件内容。根据文件 ID 自动下载文件到本地，返回本地文件路径、文件名称、类型、大小及内容类型。

## 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `media_id` | string | ✅ | 文件 ID，长度 1~256 |

## 请求示例

```bash
wecom-cli msg get_msg_media '{"media_id": "MEDIAID_xxxxxx"}'
```

## 返回字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `errcode` | integer | 返回码，`0` 表示成功 |
| `errmsg` | string | 错误信息 |
| `media_item` | object | 文件内容 |
| `media_item.media_id` | string | 文件 ID |
| `media_item.name` | string | 文件名称 |
| `media_item.type` | string | 文件类型，`image`-图片，`voice`-语音，`video`-视频，`file`-普通文件 |
| `media_item.local_path` | string | 文件下载后的本地路径 |
| `media_item.size` | integer | 文件大小（字节） |
| `media_item.content_type` | string | 文件 MIME 类型，如 `image/png`、`application/pdf` 等 |

## 响应示例

```json
{
    "errcode": 0,
    "errmsg": "ok",
    "media_item": {
        "media_id": "MEDIAID_xxxxxx",
        "name": "screenshot.png",
        "type": "image",
        "local_path": "xxx/yyy/screenshot.png",
        "size": 102400,
        "content_type": "image/png"
    }
}
```
references/send-message.md
# send_message API

向单聊或群聊发送文本消息。

## 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `chat_type` | integer | ✅ | 会话类型，`1`-单聊，`2`-群聊 |
| `chatid` | string | ✅ | 会话 ID，单聊时为 userid，群聊时为群 ID，最大 256 字节 |
| `msgtype` | string | ✅ | 消息类型，目前仅支持 `text` |
| `text` | object | ✅ | 文本消息内容 |
| `text.content` | string | ✅ | 消息内容，最大 2048 字节 |

## 请求示例

单聊：

```bash
wecom-cli msg send_message '{"chat_type": 1, "chatid": "zhangsan", "msgtype": "text", "text": {"content": "hello world"}}'
```

群聊：

```bash
wecom-cli msg send_message '{"chat_type": 2, "chatid": "wrxxxxxxxx", "msgtype": "text", "text": {"content": "大家好"}}'
```

## 返回字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `errcode` | integer | 返回码，`0` 表示成功 |
| `errmsg` | string | 错误信息 |

## 响应示例

```json
{
    "errcode": 0,
    "errmsg": "ok"
}
```
    wecomcli-msg | Prompt Minder