# Xhs Im

小红书私信会话、单聊与群聊历史、未读、文本收发、标记已读、撤回消息及删除会话；复用 xhs-hunter PC 会话。

- Repository: https://github.com/TeamWiseFlow/xiaobei (8678 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add TeamWiseFlow/xiaobei --skill xhs-im -g -a claude-code -y`
Codex: `npx skills add TeamWiseFlow/xiaobei --skill xhs-im -g -a codex -y`
Cursor: `npx skills add TeamWiseFlow/xiaobei --skill xhs-im -g -a cursor -y`
Gemini CLI: `npx skills add TeamWiseFlow/xiaobei --skill xhs-im -g -a gemini-cli -y`

## Description

小红书私信会话、单聊与群聊历史、未读、文本收发、标记已读、撤回消息及删除会话；复用 xhs-hunter PC 会话。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 小红书私信

先运行 `xhs-hunter check`，会话缺失或失效走 `xhs-hunter login`。本工具归 expert-bd，复用 `xhs-hunter` 保存的 PC 会话，不混用 Creator Cookie。

## 读取

```bash
xhs-im list --limit 30 --cursor 0
xhs-im groups --limit 30 --cursor 0
xhs-im history --conversation 用户ID --limit 30 --cursor 0
xhs-im history --conversation group:群ID --limit 30 --cursor 0
xhs-im unread
xhs-im listen --seconds 60 --max-events 100
```

列表 cursor 是页码，历史 cursor 是上一页真实 store_id。保留原始响应，不猜游标或字段。群聊仅支持列表和历史，字段需用真实返回核对。监听逐行输出 JSON，每次最多 3600 秒、1000 条。

## 写操作

以下命令默认只预览；已有用户授权时，在同一命令加 `--confirm`。

```bash
xhs-im send 用户ID "用户授权的文本"
xhs-im read --conversation 用户ID
xhs-im revoke --conversation 用户ID --message 真实消息ID
xhs-im delete --conversation 用户ID
```

仅支持单聊文本发送。`read` 使用真实会话游标（含实际返回的 `max_store_id`）和独立未读接口状态；缺会话、目标未读数或必要统计时安全停止，不用默认零伪造回执，不清空其他会话计数。`revoke` 撤回指定消息，`delete` 删除本账号的会话，不能解释为替对方删除消息。群聊拒绝发送、已读、撤回和删除。

已读请求按网页 IM 客户端的实际构造逻辑生成：目标游标来自 `max_store_id`，目标 `unread_count=0` 表示标记后的剩余未读；单聊类型按真实 `info.is_friend` / `info.is_mute` 区分普通、免打扰、陌生会话。全局计数在本地把目标未读置零后计算，保留其他单聊计数，不把群聊未读混入单聊统计；字段来源或列表覆盖不完整时安全停止。协议证据见仓库 `docs/xhs-im-read-protocol-2026-10-24.md`，不要把通知接口的赞、关注、提及未读数代入，也不要让 agent 手填全局计数。

WebSocket `send` 返回 submitted 与 mid 只代表向连接提交，不能当作送达或已读。提交结果不明先查历史，不直接重发。只有确认未提交时才用 HTTP 发送：

```bash
xhs-im call send_short_link_message --kwargs '{"receiver":"用户ID","content":"已授权正文"}' --confirm
```

`methods` 列出底层接口；`call` 的写方法同样默认预览，加 `--confirm` 执行。只传真实接口字段，不猜捕获帧或加密消息。

## 自动回复前置判断（本地，不联网发送）

已授权的私信自动回复流程可使用 `_shared/xhs_im_reply_guard.py`（相对本技能目录为 `../../../_shared/xhs_im_reply_guard.py`）：

```bash
python3 <guard路径> check --conversation 用户ID --history-file <原始history响应JSON> --ledger <本workspace账本路径>
python3 <guard路径> record --conversation 用户ID --incoming-id <真实客户消息ID> --outcome unknown --ledger <账本路径>
```

The rest: https://github.com/TeamWiseFlow/xiaobei/blob/HEAD/crews/main/skills/expert-bd/tools/xhs-im/SKILL.md