@sliverp/qqbot 1.3.0

package/skills/qqbot-cron/SKILL.md

@@ -0,0 +1,490 @@
+---
+name: qqbot-cron
+description: QQ Bot 智能提醒技能。支持一次性提醒、周期性任务、自动降级确保送达。可设置、查询、取消提醒。
+metadata: {"clawdbot":{"emoji":"⏰"}}
+---
+
+# QQ Bot 智能提醒
+
+让 AI 帮用户设置、管理定时提醒，支持私聊和群聊。
+
+---
+
+## 🤖 AI 决策指南
+
+> **本节专为 AI 理解设计，帮助快速决策**
+
+### 用户意图识别
+
+| 用户说法 | 意图 | 执行动作 |
+|----------|------|----------|
+| "5分钟后提醒我喝水" | 创建提醒 | `openclaw cron add` |
+| "每天8点提醒我打卡" | 创建周期提醒 | `openclaw cron add --cron` |
+| "我有哪些提醒" | 查询提醒 | `openclaw cron list` |
+| "取消喝水提醒" | 删除提醒 | `openclaw cron remove` |
+| "修改提醒时间" | 删除+重建 | 先 remove 再 add |
+| "提醒我" (无时间) | **需追问** | 询问具体时间 |
+
+### 必须追问的情况
+
+当用户说法**缺少以下信息**时，**必须追问**：
+
+1. **没有时间**："提醒我喝水" → 询问"请问什么时候提醒你？"
+2. **时间模糊**："晚点提醒我" → 询问"具体几点呢？"
+3. **周期不明**："定期提醒我" → 询问"多久一次？每天？每周？"
+
+### 无需追问可直接执行
+
+| 用户说法 | 理解为 |
+|----------|--------|
+| "5分钟后" | `--at 5m` |
+| "半小时后" | `--at 30m` |
+| "1小时后" | `--at 1h` |
+| "明天早上8点" | `--at 2026-02-02T08:00:00+08:00` |
+| "每天早上8点" | `--cron "0 8 * * *"` |
+| "工作日9点" | `--cron "0 9 * * 1-5"` |
+
+---
+
+## 📋 命令速查
+
+### 创建提醒（完整模板）
+
+```bash
+openclaw cron add \
+  --name "{任务名}" \
+  --at "{时间}" \
+  --message "🔔 {提醒内容}时间到！" \
+  --deliver \
+  --channel qqbot \
+  --to "{openid}" \
+  --delete-after-run
+```
+
+> ⚠️ **极其重要**：
+> - `--message` 参数直接写最终要发送的提醒内容
+> - 提醒内容格式：`🔔 {内容}时间到！`
+> - **不要**使用 `--system-prompt` 或 `--system-event`（cron 不支持这些参数）
+> - 保持消息简洁，如：`🔔 喝水时间到！`、`📅 开会时间到！`
+
+> ⚠️ **注意**：`cron add` 命令不支持 `--reply-to` 参数。提醒消息将作为主动消息直接发送给用户。
+
+### 查询提醒列表
+
+```bash
+openclaw cron list
+```
+
+### 删除提醒
+
+```bash
+openclaw cron remove {jobId}
+```
+
+### 立即发送消息（主动消息）
+
+```bash
+openclaw message send \
+  --channel qqbot \
+  --target "{openid}" \
+  --message "{消息内容}"
+```
+
+### 立即发送消息（被动回复）
+
+```bash
+openclaw message send \
+  --channel qqbot \
+  --target "{openid}" \
+  --reply-to "{message_id}" \
+  --message "{消息内容}"
+```
+
+> ⚠️ **注意**：`--reply-to` 仅在 `message send` 命令中支持，且 message_id 必须在 1 小时内有效。定时提醒不支持被动回复。
+
+---
+
+## 💬 用户交互模板
+
+> **创建提醒后的反馈要简洁友好，不要啰嗦**
+
+### 创建成功反馈（推荐简洁版）
+
+**一次性提醒**：
+```
+⏰ 好的，{时间}后提醒你{提醒内容}~
+```
+
+**周期提醒**：
+```
+⏰ 收到，{周期描述}提醒你{提醒内容}~
+```
+
+### 查询提醒反馈
+
+```
+📋 你的提醒：
+
+1. ⏰ {提醒名} - {时间}
+2. 🔄 {提醒名} - {周期}
+
+说"取消xx提醒"可删除~
+```
+
+### 无提醒时反馈
+
+```
+📋 目前没有提醒哦~
+
+说"5分钟后提醒我xxx"试试？
+```
+
+### 删除成功反馈
+
+```
+✅ 已取消"{提醒名称}"
+```
+
+---
+
+## ⏱️ 时间格式
+
+### 相对时间（--at）
+
+> ⚠️ **不要加 + 号！** 用 `5m` 而不是 `+5m`
+
+| 用户说法 | 参数值 |
+|----------|--------|
+| 5分钟后 | `5m` |
+| 半小时后 | `30m` |
+| 1小时后 | `1h` |
+| 2小时后 | `2h` |
+| 明天这时候 | `24h` |
+
+### 绝对时间（--at）
+
+| 用户说法 | 参数值 |
+|----------|--------|
+| 今天下午3点 | `2026-02-01T15:00:00+08:00` |
+| 明天早上8点 | `2026-02-02T08:00:00+08:00` |
+| 2月14日中午 | `2026-02-14T12:00:00+08:00` |
+
+### Cron 表达式（--cron）
+
+| 用户说法 | Cron 表达式 | 必须加 `--tz "Asia/Shanghai"` |
+|----------|-------------|------------------------------|
+| 每天早上8点 | `0 8 * * *` | ✅ |
+| 每天晚上10点 | `0 22 * * *` | ✅ |
+| 每个工作日早上9点 | `0 9 * * 1-5` | ✅ |
+| 每周一早上9点 | `0 9 * * 1` | ✅ |
+| 每周末上午10点 | `0 10 * * 0,6` | ✅ |
+| 每小时整点 | `0 * * * *` | ✅ |
+
+---
+
+## 📌 参数说明
+
+### 必填参数
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `--name` | 任务名，含用户标识 | `"喝水提醒"` |
+| `--at` / `--cron` | 触发时间（二选一） | `5m` / `0 8 * * *` |
+| `--message` | **提醒内容**（见下方模板） | `"🔔 喝水时间到！"` |
+| `--deliver` | 启用投递 | 固定值 |
+| `--channel qqbot` | QQ 渠道 | 固定值 |
+| `--to` | 接收者 openid | 从系统消息获取 |
+
+### 推荐参数
+
+| 参数 | 说明 | 何时使用 |
+|------|------|----------|
+| `--delete-after-run` | 执行后删除 | **一次性任务必须** |
+| `--tz "Asia/Shanghai"` | 时区 | **周期任务必须** |
+
+### --message 提醒内容模板（最关键）
+
+> ⚠️ **`--message` 的内容会直接发送给用户**，所以要写清楚提醒内容！
+
+**模板格式**：
+```
+--message "🔔 {提醒内容}时间到！"
+```
+
+**示例**：
+- 喝水：`--message "💧 喝水时间到！"`
+- 开会：`--message "📅 开会时间到！"`
+- 打卡：`--message "🌅 打卡时间到！"`
+- 日报：`--message "📝 写日报时间到！"`
+
+**为什么这样写？**
+- 消息内容会直接发送，不经过 AI 处理
+- 保持简洁，一目了然
+
+---
+
+## 🎯 使用场景示例
+
+### 场景1：一次性提醒
+
+**用户**: 5分钟后提醒我喝水
+
+**AI 执行**:
+```bash
+openclaw cron add \
+  --name "喝水提醒" \
+  --at "5m" \
+  --message "💧 喝水时间到！" \
+  --deliver \
+  --channel qqbot \
+  --to "{openid}" \
+  --delete-after-run
+```
+
+**AI 回复**:
+```
+⏰ 好的，5分钟后提醒你喝水~
+```
+
+**5分钟后用户收到**:
+```
+💧 喝水时间到！
+```
+
+---
+
+### 场景2：每日周期提醒
+
+**用户**: 每天早上8点提醒我打卡
+
+**AI 执行**:
+```bash
+openclaw cron add \
+  --name "打卡提醒" \
+  --cron "0 8 * * *" \
+  --tz "Asia/Shanghai" \
+  --message "🌅 打卡时间到！" \
+  --deliver \
+  --channel qqbot \
+  --to "{openid}"
+```
+
+**AI 回复**:
+```
+⏰ 收到，每天早上8点提醒你打卡~
+```
+
+> 💡 周期任务**不加** `--delete-after-run`
+
+---
+
+### 场景3：工作日提醒
+
+**用户**: 工作日下午6点提醒我写日报
+
+**AI 执行**:
+```bash
+openclaw cron add \
+  --name "日报提醒" \
+  --cron "0 18 * * 1-5" \
+  --tz "Asia/Shanghai" \
+  --message "📝 写日报时间到！" \
+  --deliver \
+  --channel qqbot \
+  --to "{openid}"
+```
+
+**AI 回复**:
+```
+⏰ 收到，工作日下午6点提醒你写日报~
+```
+
+---
+
+### 场景4：会议提醒
+
+**用户**: 3分钟后提醒我开会
+
+**AI 执行**:
+```bash
+openclaw cron add \
+  --name "开会提醒" \
+  --at "3m" \
+  --message "📅 开会时间到！" \
+  --deliver \
+  --channel qqbot \
+  --to "{openid}" \
+  --delete-after-run
+```
+
+**AI 回复**:
+```
+⏰ 好的，3分钟后提醒你开会~
+```
+
+**3分钟后用户收到**:
+```
+📅 开会时间到！
+```
+
+---
+
+### 场景5：群组提醒
+
+**用户**（群聊）: 每天早上9点提醒大家站会
+
+**AI 执行**:
+```bash
+openclaw cron add \
+  --name "站会提醒" \
+  --cron "0 9 * * 1-5" \
+  --tz "Asia/Shanghai" \
+  --message "📢 站会时间到！" \
+  --deliver \
+  --channel qqbot \
+  --to "group:{group_openid}"
+```
+
+> 💡 群组使用 `group:{group_openid}` 格式
+
+---
+
+### 场景6：查询提醒
+
+**用户**: 我有哪些提醒？
+
+**AI 执行**:
+```bash
+openclaw cron list
+```
+
+**AI 回复**（根据返回结果）:
+```
+📋 你的提醒：
+
+1. ⏰ 喝水提醒 - 3分钟后
+2. 🔄 打卡提醒 - 每天08:00
+
+说"取消xx提醒"可删除~
+```
+
+---
+
+### 场景7：取消提醒
+
+**用户**: 取消打卡提醒
+
+**AI 执行**:
+1. 先执行 `openclaw cron list` 找到对应任务 ID
+2. 执行 `openclaw cron remove {jobId}`
+
+**AI 回复**:
+```
+✅ 已取消"打卡提醒"
+```
+
+---
+
+## ⚙️ 消息发送说明
+
+### 定时提醒（cron add）
+
+定时提醒**只能发送主动消息**，因为：
+- 提醒执行时，原始 message_id 通常已超过 1 小时有效期
+- `openclaw cron add` 命令不支持 `--reply-to` 参数
+
+```
+┌─────────────────────┐
+│ 定时任务触发         │
+└──────────┬──────────┘
+           ↓
+┌─────────────────────┐
+│ AI 通过 system-event │
+│ 获取用户上下文信息   │
+└──────────┬──────────┘
+           ↓
+┌─────────────────────┐
+│ 发送主动消息到用户   │
+│ --channel qqbot     │
+│ --to {openid}       │
+└──────────┬──────────┘
+           ↓
+    ✅ 用户收到提醒
+```
+
+### 即时回复（message send）
+
+即时消息发送支持被动回复（如果 message_id 有效）：
+
+```
+                ┌─────────────────────┐
+                │ 发送即时消息         │
+                └──────────┬──────────┘
+                           ↓
+         ┌──────────────────────────────┐
+         │ 有 --reply-to 且 message_id  │
+         │ 在 1 小时内有效？             │
+         └──────────────────────────────┘
+               ↓                ↓
+              是               否
+               ↓                ↓
+    ┌───────────────┐  ┌─────────────────┐
+    │ 被动消息回复   │  │ 发送主动消息     │
+    │ (引用原消息)   │  │ (直接发送)      │
+    └───────────────┘  └─────────────────┘
+```
+
+---
+
+## ⚠️ 重要限制
+
+| 限制 | 说明 |
+|------|------|
+| **message_id 有效期** | 1 小时内有效，超时自动降级 |
+| **回复次数限制** | 同一 message_id 最多回复 4 次 |
+| **主动消息权限** | ⚠️ **QQ 机器人需要申请主动消息权限**，否则定时提醒会发送失败 |
+| **主动消息限制** | 只能发给与机器人交互过的用户（24小时内） |
+| **消息内容** | `--message` 不能为空 |
+
+### ⚠️ 主动消息权限说明
+
+定时提醒功能依赖**主动消息能力**，但 QQ 官方默认**不授予**此权限。
+
+**常见错误**：
+- 错误码 `40034102`："主动消息失败, 无权限"
+- 这表示机器人没有主动消息权限
+
+**解决方案**：
+1. 登录 [QQ 开放平台](https://q.qq.com/)
+2. 进入机器人开发-沙箱管理，消息列表配置中添加自己。
+
+> 💡 **临时替代方案**：在没有主动消息权限前，可以让用户使用"回复"方式获得即时提醒，而非定时提醒。
+
+---
+
+## 📝 消息模板
+
+| 场景 | 触发时输出 | Emoji |
+|------|------------|-------|
+| 喝水 | 喝水时间到啦！ | 💧 🚰 |
+| 打卡 | 早上好，打卡时间到！ | 🌅 ✅ |
+| 会议 | 开会时间到！ | 📅 👥 |
+| 休息 | 该休息一下了~ | 😴 💤 |
+| 日报 | 下班前别忘了写日报哦~ | 📝 ✍️ |
+| 运动 | 运动时间到！ | 🏃 💪 |
+| 吃药 | 该吃药了~ | 💊 🏥 |
+| 生日 | 今天是xx的生日！ | 🎂 🎉 |
+
+---
+
+## 🔧 用户标识
+
+| 类型 | 格式 | 来源 |
+|------|------|------|
+| 用户 openid | `B3EA9A1d-2D3c-5CBD-...` | 系统消息自动提供 |
+| 群组 openid | `group:FeC1ADaf-...` | 系统消息自动提供 |
+| message_id | `ROBOT1.0_xxx` | 系统消息自动提供 |
+
+> 💡 这些信息在系统消息中格式如：
+> - `当前用户 openid: B3EA9A1d-...`
+> - `当前消息 message_id: ROBOT1.0_...`

package/skills/qqbot-media/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: qqbot-media
+description: QQ Bot 媒体发送指南。教 AI 如何发送图片给用户。
+metadata: {"clawdbot":{"emoji":"📸"}}
+triggers:
+  - qqbot
+  - qq
+  - 发送图片
+  - 发送文件
+  - 图片
+  - 本地文件
+  - 本地图片
+priority: 80
+---
+
+# QQBot 媒体发送指南
+
+## ⚠️ 重要：你有能力发送本地图片！
+
+**当用户要求发送本地图片时，只需使用 `<qqimg>` 标签包裹图片路径即可。系统会自动处理文件读取和发送。**
+
+**不要说"无法发送本地图片"！使用正确的标签格式，系统就能发送。**
+
+---
+
+## 📸 发送图片（推荐方式：`<qqimg>` 标签）
+
+使用 `<qqimg>` 标签包裹图片路径，即可发送图片：
+
+```
+<qqimg>图片路径</qqimg>
+```
+
+### ✅ 发送本地图片示例
+
+当用户说"发送那张图片"、"把图发给我"等，你应该输出：
+
+```
+这是你要的图片：
+<qqimg>/Users/xxx/images/photo.jpg</qqimg>
+```
+
+### ✅ 发送网络图片示例
+
+```
+这是网络上的图片：
+<qqimg>https://example.com/image.png</qqimg>
+```
+
+### ✅ 发送多张图片
+
+```
+这是你要的所有图片：
+<qqimg>/Users/xxx/image1.jpg</qqimg>
+<qqimg>/Users/xxx/image2.png</qqimg>
+```
+
+### 📝 标签说明
+
+| 格式 | 说明 |
+|------|------|
+| `<qqimg>本地路径</qqimg>` | 发送本地图片（绝对路径） |
+| `<qqimg>网络URL</qqimg>` | 发送网络图片 |
+| `<qqimg>路径</img>` | 也支持此闭合方式 |
+
+### ⚠️ 注意事项
+
+1. **路径必须正确**：本地文件需要绝对路径，网络图片需要完整 URL
+2. **支持的图片格式**：jpg, jpeg, png, gif, webp, bmp
+3. **不要拒绝**：如果用户要求发送本地图片，直接使用 `<qqimg>` 标签即可
+4. **标签外的文本会正常发送**：可以在标签前后添加描述文字
+5. **闭合标签**：支持 `</qqimg>` 或 `</img>` 两种闭合方式
+
+---
+
+## 🚫 错误示例（不要这样做）
+
+❌ **错误**：说"我无法发送本地图片"
+❌ **错误**：说"受限于技术限制，无法直接发送"
+❌ **错误**：只提供路径文本，不使用 `<qqimg>` 标签
+
+✅ **正确**：直接使用 `<qqimg>` 标签包裹路径
+
+---
+
+## 🔤 告知路径信息（不发送图片）
+
+如果你需要**告知用户图片的保存路径**（而不是发送图片），直接写路径即可，不要使用标签：
+
+```
+图片已保存在：/Users/xxx/images/photo.jpg
+```
+
+或用反引号强调：
+
+```
+图片已保存在：`/Users/xxx/images/photo.jpg`
+```
+
+---
+
+## 📋 高级选项：JSON 结构化载荷
+
+如果需要更精细的控制（如添加图片描述），可以使用 JSON 格式：
+
+```
+QQBOT_PAYLOAD:
+{
+  "type": "media",
+  "mediaType": "image",
+  "source": "file",
+  "path": "/path/to/image.jpg",
+  "caption": "图片描述（可选）"
+}
+```
+
+### JSON 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `type` | string | ✅ | 固定为 `"media"` |
+| `mediaType` | string | ✅ | 媒体类型：`"image"` |
+| `source` | string | ✅ | 来源：`"file"`（本地）或 `"url"`（网络） |
+| `path` | string | ✅ | 图片路径或 URL |
+| `caption` | string | ❌ | 图片描述，会作为单独消息发送 |
+
+> 💡 **提示**：对于简单的图片发送，推荐使用 `<qqimg>` 标签，更简洁易用。
+
+---
+
+## 🎯 快速参考
+
+| 场景 | 使用方式 |
+|------|----------|
+| 发送本地图片 | `<qqimg>/path/to/image.jpg</qqimg>` |
+| 发送网络图片 | `<qqimg>https://example.com/image.png</qqimg>` |
+| 发送多张图片 | 多个 `<qqimg>` 标签 |
+| 告知路径（不发送） | 直接写路径文本 |