@dhfpub/clawpool 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhfpub/clawpool",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "OpenClaw channel plugin for ClawPool",
   "type": "module",
   "main": "./dist/index.js",

package/skills/message-send/SKILL.md

@@ -128,6 +128,83 @@ target=agent:clawpool-developer:clawpool:direct:e72ce987-2d2e-40ed-bcc9-b336b497
 
 ---
 
+## 会话卡片消息协议
+
+当消息内容是在**提醒用户打开某个群聊**、**打开某个私聊对话**、**引用某个具体对话记录入口**时，如果已经拿到了准确的 `session_id`，不要发送自然语言链接，也不要发送前端内部 JSON；必须发送显式的 `conversation-card` 指令文本，由前端统一解析并渲染为可点击的会话卡片。
+
+### 标准格式
+
+群聊：
+
+```text
+[[conversation-card|session_id=<SESSION_ID>|session_type=group|title=<GROUP_TITLE>]]
+```
+
+私聊：
+
+```text
+[[conversation-card|session_id=<SESSION_ID>|session_type=private|title=<CHAT_TITLE>|peer_id=<PEER_ID>]]
+```
+
+### 字段规则
+
+- `session_id`：必填。必须是准确的目标会话 ID。
+- `session_type`：必填。只能是 `group` 或 `private`。
+- `title`：必填。展示给用户看的群标题或私聊标题。
+- `peer_id`：仅私聊可选。用于补充私聊对象信息，但前端打开行为仍以 `session_id` 为准。
+
+### 编码规则
+
+为了避免标题里出现 `|`、`=`、`]`、空格、换行或其他保留字符导致前端解析失败，`conversation-card` 的字段值应按 URI component 规则编码后再写入指令。
+
+- 推荐：对 `title`、`peer_id`、以及未来可能扩展的文本字段统一做 URI component 编码
+- `session_id` 和 `session_type` 如果本身只包含安全字符，可以直接原样输出
+- 前端会按 URI component 解码后再渲染
+
+示例：
+
+```text
+[[conversation-card|session_id=session-9|session_type=group|title=%E4%BA%A7%E5%93%81%E8%AE%A8%E8%AE%BA%E7%BE%A4%20A]]
+```
+
+### 使用要求
+
+1. 只有在**已知准确 `session_id`** 时，才允许输出 `conversation-card`。
+2. 如果没有 `session_id`，只能发送普通文本说明，不能伪造会话卡片。
+3. 不要输出 `chat://...`、网页链接、或“点这里打开会话”之类的自然语言链接替代方案。
+4. 不要构造前端内部 `biz_card` JSON，也不要尝试发送 Flutter/前端私有协议结构。
+5. `conversation-card` 必须单行发送，不要换行，不要在同一条指令里混入多余说明文字。
+6. 如果字段值包含特殊字符，先做 URI component 编码，再拼进指令文本。
+
+### 示例
+
+示例 1：提醒用户进入群聊
+
+```text
+[[conversation-card|session_id=9d6a4b1d-5d37-4e38-ae6a-0c12a2c4c901|session_type=group|title=产品群]]
+```
+
+示例 2：提醒用户进入某个私聊
+
+```text
+[[conversation-card|session_id=e72ce987-2d2e-40ed-bcc9-b336b4974512|session_type=private|title=Alice|peer_id=1001]]
+```
+
+### 适用场景
+
+- 给 owner 或其他用户发送“请进入这个对话继续处理”的提醒
+- 发送“这是你要查看的群聊/私聊入口”的通知
+- 发送引用型对话入口，而不是发送完整对话记录内容
+
+### 不适用场景
+
+- 普通文本通知
+- 没有准确 `session_id` 的模糊提醒
+- 需要直接发送完整对话记录内容的场景
+- 仅仅告诉对方“我已经处理完了”，但并不需要跳转到某个具体会话的场景
+
+---
+
 ## 错误处理
 
 常见错误及处理方式：
@@ -145,3 +222,4 @@ target=agent:clawpool-developer:clawpool:direct:e72ce987-2d2e-40ed-bcc9-b336b497
 2. **使用变量**：在代码中使用 `{agentId}`、`{accountId}` 等变量，而不是硬编码
 3. **简洁明了**：私信消息应简洁，突出重点
 4. **适当使用**：不要滥用私信功能，避免打扰 owner
+5. **需要跳转时优先用会话卡片**：如果消息的核心目标是让对方打开某个已知会话，优先发送 `conversation-card` 指令，而不是发普通说明文字