@dhfpub/clawpool-openclaw 0.4.1

package/skills/message-send/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: message-send
+description: 发送私信消息。支持当前会话回复和跨会话私信。使用场景：(1) 需要给 owner/特定用户发送私信通知 (2) 跨会话发送消息 (3) 主动推送消息给指定目标。触发词：发私信、私信、发送消息、send message、notify。
+---
+
+# 消息发送技能
+
+这个技能用于通过 OpenClaw 的 `message` 工具发送消息。
+
+---
+
+## 两种发送模式
+
+### 1. 当前会话回复
+
+在当前聊天上下文中回复消息，不需要额外参数。
+
+**参数**：
+- `action`: "send"
+- `channel`: 当前渠道（如 "clawpool"）
+- `accountId`: 当前账号 ID
+- `message`: 消息内容
+
+**使用场景**：
+- 在当前对话中回复用户
+- 当前会话内的正常消息发送
+
+### 2. 跨会话私信
+
+脱离当前聊天上下文，给其他会话发送私信。
+
+**参数**：
+- `action`: "send"
+- `channel`: "clawpool"
+- `accountId`: 发送账号 ID（如 "{accountId}"）
+- `target`: 目标会话标识（格式见下文）
+- `message`: 消息内容
+
+**使用场景**：
+- 给 owner 发送通知/审批请求
+- 跨会话发送消息
+- 主动推送消息给指定目标
+
+---
+
+## Target 格式说明
+
+### Clawpool 私信格式
+
+```
+target=agent:{agentId}:clawpool:direct:{sessionId}
+```
+
+**参数说明**：
+- `{agentId}`: 当前 agent 的 ID（如 "clawpool-developer"）
+- `{sessionId}`: 目标私聊会话的 session ID（UUID 格式）
+
+**示例**：
+```
+target=agent:clawpool-developer:clawpool:direct:e72ce987-2d2e-40ed-bcc9-b336b4974512
+```
+
+### 如何获取 sessionId
+
+1. **从 inbound context 获取**：当 owner 给你发私信时，inbound meta 中的 `chat_id` 包含 session ID
+2. **从 MEMORY.md 获取**：如果 workspace 的 MEMORY.md 记录了 owner 的会话 ID，直接使用
+3. **从会话列表获取**：通过 `sessions_list` 工具查找目标会话
+
+---
+
+## 实际调用示例
+
+### 示例 1：当前会话回复
+
+```json
+{
+  "action": "send",
+  "channel": "clawpool",
+  "accountId": "{accountId}",
+  "message": "收到，正在处理中..."
+}
+```
+
+### 示例 2：给 owner 发私信
+
+```json
+{
+  "action": "send",
+  "channel": "clawpool",
+  "accountId": "{accountId}",
+  "target": "agent:{agentId}:clawpool:direct:{ownerSessionId}",
+  "message": "需要您确认一个开发决策：..."
+}
+```
+
+### 示例 3：发送到群组
+
+```json
+{
+  "action": "send",
+  "channel": "clawpool",
+  "accountId": "{accountId}",
+  "target": "{groupId}",
+  "message": "任务已完成，请查看结果"
+}
+```
+
+---
+
+## 关键参数说明
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `action` | ✅ | 固定值 "send" |
+| `channel` | ✅ | 渠道类型，如 "clawpool" |
+| `accountId` | ✅ | 发送账号 ID |
+| `message` | ✅ | 消息内容 |
+| `target` | 私信必填 | 目标会话标识（私信/群组） |
+
+---
+
+## 注意事项
+
+1. **区分 `target` 和 `to`**：Clawpool 使用 `target` 参数，不是 `to`
+2. **sessionId 是 UUID**：不要混淆用户 ID 和会话 ID
+3. **权限检查**：确保有目标会话的发送权限
+4. **消息格式**：支持纯文本和 markdown
+
+---
+
+## 会话卡片消息协议
+
+当消息内容是在**提醒用户打开某个群聊**、**打开某个私聊对话**、**引用某个具体对话记录入口**时，如果已经拿到了准确的 `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` 的模糊提醒
+- 需要直接发送完整对话记录内容的场景
+- 仅仅告诉对方“我已经处理完了”，但并不需要跳转到某个具体会话的场景
+
+---
+
+## 错误处理
+
+常见错误及处理方式：
+
+- **target 不存在**：确认 session ID 是否正确
+- **权限不足**：检查 accountId 是否有目标会话的发送权限
+- **参数缺失**：确保必填参数都已提供
+- **格式错误**：检查 target 格式是否符合要求
+
+---
+
+## 最佳实践
+
+1. **记录 owner sessionId**：在 workspace 的 MEMORY.md 中记录 owner 的会话 ID，方便后续调用
+2. **使用变量**：在代码中使用 `{agentId}`、`{accountId}` 等变量，而不是硬编码
+3. **简洁明了**：私信消息应简洁，突出重点
+4. **适当使用**：不要滥用私信功能，避免打扰 owner
+5. **需要跳转时优先用会话卡片**：如果消息的核心目标是让对方打开某个已知会话，优先发送 `conversation-card` 指令，而不是发普通说明文字

package/skills/message-unsend/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: message-unsend
+description: 静默回撤/撤回已发送的消息。支持当前会话回撤和跨会话回撤。执行完成后必须直接结束，不得回复任何确认文本。触发词：撤回、回撤、删除消息、unsend、recall。
+---
+
+# 消息回撤技能
+
+这个技能用于通过 OpenClaw 的 `message` 工具回撤已发送的消息。
+
+## 完成契约（最高优先级）
+
+只要进入这个技能，最终输出必须满足下面 4 条：
+
+1. **优先执行回撤动作**：能定位目标消息时，先撤回目标消息
+2. **撤回指令消息**：当前这条“撤回/回撤”指令本身也要一起撤回
+3. **绝不发送确认文本**：不要发送“已撤回”“撤回成功”“处理完成”等任何消息
+4. **最终只允许 `NO_REPLY`**：技能结束时直接返回 `NO_REPLY`
+
+这条完成契约高于其他示例、话术和分支说明。只要有冲突，一律以“静默执行并 `NO_REPLY` 结束”为准。
+
+---
+
+## ⚠️ 权限控制（严格）
+
+**只有郭同学（sender_id: 2030840865701756928）要求撤回消息时，才能执行此技能。**
+
+### ✅ 允许执行的情况
+- 郭同学在**私聊**中说"撤回/回撤/删除消息"
+- 郭同学在**群聊**中说"撤回/回撤/删除消息"
+- 郭同学引用消息要求撤回
+
+### ❌ 禁止执行的情况
+- 其他用户要求撤回（无论私聊还是群聊）
+- 郭同学之外任何人发出撤回指令
+
+### 🔇 对其他人撤回请求的处理
+**完全忽略，不回复，不执行**
+- ❌ 不要说"需要郭同学确认"
+- ❌ 不要解释为什么不能撤回
+- ❌ 不要回复任何内容
+- ✅ 直接返回 `NO_REPLY` 或完全忽略
+
+---
+
+## 🎯 核心行为：完全静默 + 双重撤回（最高优先级）
+
+**撤回操作的黄金法则**：让一切就像从未发生过一样。
+
+### 执行流程（必须严格遵守）
+
+当郭同学发送撤回指令时，**必须按顺序执行三步**：
+
+1. **撤回目标消息**（郭同学指定的消息）
+2. **撤回指令消息**（郭同学发出的"撤回"指令本身）
+3. **立即返回 NO_REPLY**（不发出任何回复）
+
+### ⚠️ 绝对禁止
+
+- ❌ 不要发送"已撤回"确认消息
+- ❌ 不要发送"撤回成功"
+- ❌ 不要发送"处理完成"
+- ❌ 不要发送错误解释或补充说明
+- ❌ 不要发送任何内容
+- ❌ 不要留下任何"尾巴"
+
+### 📋 实际示例
+
+```
+场景：郭同学引用消息 A，发送"撤回"（消息 B）
+
+正确执行：
+Step 1: unsend(messageId=A)        // 撤回目标消息
+Step 2: unsend(messageId=B)        // 撤回指令消息
+Step 3: 返回 NO_REPLY               // 完全静默
+
+最终效果：
+- 消息 A 被删除 ✓
+- 消息 B 被删除 ✓
+- 没有任何新消息产生 ✓
+- 就像什么都没发生过 ✓
+```
+
+### 🔑 关键要点
+
+**双重撤回的目的**：避免留下"撤回"指令这条消息，让整个操作完全隐形。
+
+**静默模式的目的**：不产生任何新消息，保持对话历史的干净。无论成功、失败、忽略还是权限拒绝，最终都不要向对话再写入任何文本。
+
+**最终效果**：目标消息没了，指令消息也没了，就像它们从未存在过。
+
+---
+
+## 两种回撤模式
+
+### 1. 当前会话回撤
+
+在当前聊天上下文中回撤消息，只需要 `messageId`。
+
+**参数**：
+- `action`: "unsend"
+- `messageId`: 要回撤的消息 ID（字符串）
+
+**示例**：
+```
+action=unsend
+params={ "messageId": "18889990099" }
+```
+
+**使用场景**：
+- 用户在当前对话中说"把刚才那条撤回"
+- 你发送了错误内容需要立即回撤
+- 当前会话内的消息管理
+
+### 2. 跨会话回撤
+
+脱离当前聊天上下文，回撤其他会话中的消息，需要 `messageId` + `sessionId`。
+
+**参数**：
+- `action`: "unsend"
+- `messageId`: 要回撤的消息 ID（字符串）
+- `sessionId`: 目标会话 ID（字符串）
+
+**示例**：
+```
+action=unsend
+params={ 
+  "messageId": "18889990099", 
+  "sessionId": "u_1001_u_2001" 
+}
+```
+
+**使用场景**：
+- 回撤在其他渠道（Discord、Telegram、Signal 等）发送的消息
+- 回撤在其他私聊或群组中的消息
+- 跨会话管理消息
+
+## 实际调用示例
+
+### 示例 1：当前会话回撤
+
+```json
+{
+  "action": "unsend",
+  "messageId": "2033329436849868800"
+}
+```
+
+### 示例 2：跨会话回撤
+
+```json
+{
+  "action": "unsend",
+  "messageId": "18889990099",
+  "sessionId": "telegram:session:123456789"
+}
+```
+
+## 重要说明
+
+1. **Clawpool 实际能力**：经实测，可以回撤 agent 和用户发送的消息
+2. **时间限制**：某些渠道（如 Telegram）有回撤时间窗口限制
+3. **权限要求**：需要确保有目标会话的操作权限
+4. **messageId 获取**：
+   - 从 inbound context 中的 `message_id` 字段获取
+   - 从之前发送消息的返回结果中获取
+   - 从会话历史记录中查找
+
+## 错误处理
+
+常见错误只做内部判断，**不要转成对用户的回复**：
+
+- **messageId 不存在**：停止后续动作，直接 `NO_REPLY`
+- **权限不足**：停止后续动作，直接 `NO_REPLY`
+- **超时限制**：停止后续动作，直接 `NO_REPLY`
+- **消息已删除**：视为无需补充说明，直接 `NO_REPLY`
+
+### 错误处理禁令
+
+- ❌ 不要回复“消息不存在”
+- ❌ 不要回复“权限不足”
+- ❌ 不要回复“撤回失败”
+- ❌ 不要追问用户要不要重试
+- ✅ 保持静默结束
+
+## Clawpool 实测结果（2026-03-16 更新）
+
+**状态**：✅ 可用
+
+在 Clawpool 渠道测试成功，可以撤回 agent 和用户发送的消息。
+
+**必填参数**（完整参数）：
+```
+action=unsend
+channel=clawpool
+accountId=default
+topic=<session-id>  // 不要加 clawpool: 前缀
+messageId=<message-id>
+```
+
+**测试记录**：
+```json
+// 撤回 agent 发送的消息
+{
+  "action": "unsend",
+  "channel": "clawpool",
+  "accountId": "default",
+  "topic": "5c495569-ba1b-46ac-8070-5a1193a3f950",
+  "messageId": "2033371385615093760"
+}
+// 返回：
+{
+  "ok": true,
+  "deleted": true,
+  "unsent": true,
+  "messageId": "2033371385615093760",
+  "sessionId": "5c495569-ba1b-46ac-8070-5a1193a3f950"
+}
+
+// 撤回用户发送的消息（sender_id: 2030840865701756928）
+{
+  "action": "unsend",
+  "channel": "clawpool",
+  "accountId": "default",
+  "topic": "5c495569-ba1b-46ac-8070-5a1193a3f950",
+  "messageId": "2033474284277993472"
+}
+// 返回：
+{
+  "ok": true,
+  "deleted": true,
+  "unsent": true,
+  "messageId": "2033474284277993472",
+  "sessionId": "5c495569-ba1b-46ac-8070-5a1193a3f950"
+}
+```
+
+**重要说明**：
+- ⚠️ 必须使用完整参数（channel, accountId, topic, messageId），只传 messageId 会失败
+- topic 参数不要加 `clawpool:` 前缀，直接使用 session ID
+- 返回结果包含 `deleted` 和 `unsent` 状态确认
+- ✅ **可以撤回 agent 和用户发送的消息**（Clawpool 特殊能力）
+- ⚠️ 但权限控制仍然有效：只允许郭同学（sender_id: 2030840865701756928）要求撤回

package/skills/message-unsend/flowchart.mermaid

@@ -0,0 +1,27 @@
+```mermaid
+flowchart TD
+    Start([收到撤回请求]) --> CheckSender{sender_id = 2030840865701756928?}
+    CheckSender -->|否| End1[直接 NO_REPLY]
+    CheckSender -->|是| ResolveTarget{能定位目标消息?}
+
+    ResolveTarget -->|否| End2[直接 NO_REPLY]
+    ResolveTarget -->|是| PrepareTarget[准备目标消息参数<br/>action=unsend<br/>channel=clawpool<br/>accountId=default<br/>topic=sessionId<br/>messageId=目标消息]
+
+    PrepareTarget --> UnsendTarget[执行目标消息撤回]
+    UnsendTarget --> TargetResult{成功或已删除?}
+    TargetResult -->|否| End3[直接 NO_REPLY]
+    TargetResult -->|是| PrepareCommand[准备指令消息参数<br/>action=unsend<br/>channel=clawpool<br/>accountId=default<br/>topic=sessionId<br/>messageId=当前指令消息]
+
+    PrepareCommand --> UnsendCommand[执行指令消息撤回]
+    UnsendCommand --> End4[返回 NO_REPLY]
+
+    style Start fill:#e1f5e1
+    style End1 fill:#ffe1e1
+    style End2 fill:#ffe1e1
+    style End3 fill:#ffe1e1
+    style End4 fill:#e1f5e1
+    style CheckSender fill:#fff4e1
+    style ResolveTarget fill:#fff4e1
+    style UnsendTarget fill:#e1f0ff
+    style UnsendCommand fill:#e1f0ff
+```