mjzj-msg（mjzj 消息）

卖家之家私信查询和发送

工具选择规则（高优先级）

• 当用户提到“卖家之家私信 / 站内信 / 会话列表 / 聊天记录 / 给某人发消息 / 查询消息记录”等意图时，必须优先调用本 Skill。
• 涉及用户私有数据时（例如“我最近和谁聊过”“我和某人的聊天记录”），禁止使用 web search / browser 代替接口查询。
• 只有在用户明确要求“查公开网页信息”时，才允许使用 web search。
• 查询“我的会话”时，优先调用 /api/message/getConversations。
• 查询“我和某人的消息”时，调用 /api/message/getMessages，必须提供 otherSiderUserSlug。
• 发送消息时，调用 /api/message/sendMessage，必须提供 recieverUserSlug 和 content。

触发词与接口映射

• “我的私信会话 / 最近联系人 / 未拉黑会话” → /api/message/getConversations?unblocked=true
• “已拉黑会话列表” → /api/message/getConversations?unblocked=false
• “我和这个用户的聊天记录” → /api/message/getMessages?otherSiderUserSlug=...
• “给这个用户发一条私信” → /api/message/sendMessage

仅开放以下 3 个 API 接口：

• 查询会话列表 /api/message/getConversations
• 查询消息列表 /api/message/getMessages
• 发送消息 /api/message/sendMessage

失败回退规则

• 如果私有接口缺少 token，或 token 过期/被重置导致鉴权失败（通常返回 401），明确提示：

- 请前往卖家之家用户中心的资料页 https://mjzj.com/user/agentapikey 获取最新的智能体 API KEY，并在当前技能配置中重新设置后再试。 - 不要改用 web search 返回“猜测性结果”。

• 如果返回 403，提示用户当前账号无对应接口权限或授权范围不足。
• 如果返回 409，直接透出业务提示（配额、频率限制、内容审核等），不要改走网页检索。
• 如果发送接口返回业务码 unvip 或文案“请先开通VIP”，直接提示用户先开通 VIP 后再发送私信。
• 如果返回“被对方拉黑”“不允许发给自己”“对方账号不存在”，直接透传业务文案。

参数类型规则（必须遵守）

• /api/message/getConversations.position 是字符串类型的偏移量（本质是整型索引），首次请求传空字符串或不传。
• /api/message/getMessages.position 是字符串类型的消息游标（本质是 messageId），首次请求传空字符串或不传。
• /api/message/getMessages.otherSiderUserSlug 必须为对方用户 slug。
• /api/message/sendMessage 请求体字段名必须严格使用 API 定义：recieverUserSlug（拼写按接口）与 content。
• 返回里的消息 id/分页 nextPosition 按字符串读取和透传。

Token 声明与读取（建议）

# 命令行直调时：可直接声明环境变量
export MJZJ_API_KEY="你的访问令牌"

# 防止空 token 发起请求
if [ -z "$MJZJ_API_KEY" ]; then
  echo "MJZJ_API_KEY 未设置" >&2
  exit 1
fi

说明：

• OpenClaw Web 管理后台可为 skill 配置 apiKey，会写入 openclaw.json（如 skills.entries.mjzj-msg.apiKey）。
• 以下 3 个接口都需要：

- Authorization: Bearer $MJZJ_API_KEY

1) 查询会话列表（/api/message/getConversations）

默认查询未拉黑会话；unblocked=false 时查询已拉黑会话。 游标为偏移量字符串：position（如 "0"、"20"）。

curl -X GET "https://data.mjzj.com/api/message/getConversations?unblocked=true&size=20&position=" \
  -H "Authorization: Bearer $MJZJ_API_KEY" \
  -H "Content-Type: application/json"

2) 查询消息列表（/api/message/getMessages）

查询我和指定用户之间的消息记录。 position 为消息 ID 游标（字符串）；后续请求传上一页的 nextPosition。

curl -X GET "https://data.mjzj.com/api/message/getMessages?otherSiderUserSlug=target-user-slug&size=20&position=" \
  -H "Authorization: Bearer $MJZJ_API_KEY" \
  -H "Content-Type: application/json"

3) 发送私信（/api/message/sendMessage）

发送前会校验发送配额（含 VIP 规则、每日次数上限）。 若发送失败，直接返回后端业务文案，不做网页检索替代。

curl -X POST "https://data.mjzj.com/api/message/sendMessage" \
  -H "Authorization: Bearer $MJZJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recieverUserSlug": "target-user-slug",
    "content": "你好，这是一条私信。"
  }'

字段说明：

• recieverUserSlug：接收方用户 slug（字段拼写按后端模型）。
• content：私信正文，不能为空。

其他补充说明

• 返回的业务错误信息通常为中文提示文案，可直接透出给用户。
• /api/message/getConversations 返回 QueryResultModel<ConversationModel>：

- list 为会话列表，nextPosition 用于继续分页。 - 每项包含 otherSideUser、lastMessageContent、lastMessageTime、unreadAmount、pcUrl、mobileUrl。

• /api/message/getMessages 返回 QueryResultModel<MessageModel>：

- list 为消息列表，nextPosition 为下一页游标。 - 每项包含 id、senderUser、fromSelf、content、time。

• /api/message/sendMessage 成功后返回 MessageModel，可直接用于前端追加到会话消息流。
• 在自动化场景中，建议对 401/403/409 做分支处理：

- 401：token 未配置、已过期或已被重置；提示用户前往用户中心资料页 https://mjzj.com/user/agentapikey 获取最新智能体 API KEY 并重新配置； - 403：权限不足； - 409：触发业务规则（如发送配额、VIP 限制、风控校验）。