sophhub 0.4.62 → 0.4.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sophhub",
-  "version": "0.4.62",
+  "version": "0.4.64",
   "description": "SophHub CLI - Manage and download AI Agent skills and agents",
   "type": "module",
   "bin": {

package/skills/claw-agent-get-send/skill.json

@@ -1,10 +1,24 @@
 {
   "name": "claw-agent-get-send",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "types": ["store"],
-  "displayName": "Claw Agent Get/Send",
-  "description": "Appia（IM 即时通讯）侧 claw.agent.groups.get / claw.agent.message.send：查询机器人在哪些群聊、向群发纯文本或 Markdown、发送文件附件；脚本封装 + HTTP/curl 参考（JWT、msg/md、错误码）",
+  "displayName": "Claw Agent 全量能力",
+  "description": "Appia（IM）Claw Agent 全量能力：群聊收发/读历史/公告/撤回/退群，扩展（scopes/搜人/通知/待办/搜频道/纪要/总览/建群/改待办）；脚本封装 + HTTP/curl 参考",
   "changelog": [
+    {
+      "version": "2.0.0",
+      "date": "2026-07-23",
+      "changes": [
+        "appia_claw.py：新增 get-messages / get-announcements / fetch-file / recall / leave 五个入群子命令（既有 groups/verify-target/send/send-md/send-file 不变）",
+        "appia_claw.py：send / send-md 新增 --mention（-m），经 agent.users.search 把显示名解析为 @username 前置到正文，可选按频道成员校验是否在群",
+        "新增 appia_common.py：共享凭证 + JWT + 通用 GET/POST/multipart/raw helper",
+        "新增 appia_extensions.py：scopes/scopes-request/users-search/notifications/todos/unread/channels-search/channel-info/channel-messages/channel-messages-search/channel-members/channel-attachments/channel-announcements/file-metadata/meeting-minutes/meeting-minutes-ingest/overview-resolve/overview-links/todos-update/channels-create/tool-invoke（21 子命令）",
+        "新增 references/ 目录：auth/creator-delegate-api/query-api/write-api/rooms-api/overview-api/session-flow",
+        "reference-http.md：追加 messages.get/announcements.get/file.fetch/recall/group.leave 章节与 references 指引",
+        "SKILL.md：重写为全量能力用法（入群/扩展）+ 文档地图 + --mention 说明；description 扩触发词",
+        "skill.json / pyproject.toml：bump 2.0.0；displayName 改为「Claw Agent 全量能力」"
+      ]
+    },
     {
       "version": "1.2.0",
       "date": "2026-07-06",
@@ -49,5 +63,5 @@
     }
   ],
   "createdAt": "2026-04-28",
-  "updatedAt": "2026-07-06"
+  "updatedAt": "2026-07-23"
 }

package/skills/claw-agent-get-send/src/SKILL.md

@@ -1,49 +1,125 @@
 ---
 name: claw-agent-get-send
-description: On Appia (an IM / team chat platform), list which group chats the bot agent is in (rid + name), or send plaintext or Markdown to a group via Appia Claw. Use when the user asks for group list / 群列表 / Appia 群聊 / rid, or to message a group / 向群发消息 / IM 通知；claw、agent.groups.get、agent.message.send。
+description: Appia（IM）Claw Agent 全量能力：群聊收发/读历史/公告/撤回/退群，扩展（scopes/搜人/通知/待办/搜频道/纪要/总览/建群/改待办）。当用户要求 Appia/Claw 群聊收发、查历史公告、撤回、搜人/频道、待办通知、建群、scopes 授权时使用。
 ---
 
-# Appia 即时通讯（IM）· Claw 群列表与发消息
+# Appia 即时通讯（IM）· Claw Agent 全量能力
 
-Appia 为 IM（即时通讯）工具中的群聊/会话场景。脚本 `{baseDir}/scripts/appia_claw.py` 通过 Claw HTTP API 拉取机器人所在群并发消息。`{baseDir}` 与本 `SKILL.md` 同级（安装根下一般有 `scripts/`）。
+Appia 为 IM（即时通讯）工具中的群聊/会话场景。操作者始终是机器人，凭证只有 JWT + `agentId` + 创建者 `userId`（JWT 的 `sub` 须等于 `userId`）；用户 `authToken` 永不给 Agent，写权限通过 scopes 授权。
 
-## 用法
+脚本位于 `{baseDir}/scripts/`，用 `uv run` 启动。`{baseDir}` 与本 `SKILL.md` 同级。
+
+## 鉴权与授权
+
+- 凭证：`--cred-file /path/to.cred.json`（或 `-c`）JSON 文件，非空字段优先于环境变量；不用凭证文件时设 `CLAW_JWT`、`APP_AGENT_ID`、`CLAW_USER_ID`（新脚本也接受 `MCP_JWT`）。
+- 缺写权限：服务端返回 `SCOPE_DENIED` → `appia_extensions.py scopes-request` → 用户在 myAgent 点「授权」→ `scopes` 或重试。不要向用户要 authToken。
+- 详情：[auth.md](references/auth.md) · [session-flow.md](references/session-flow.md)
+
+## 1. 入群能力（bot 须在频道）— `appia_claw.py`
+
+子命令前可加 `--cred-file /path/to.cred.json`（或 `-c`）、`--timeout 秒`。查群与收发：
+
+```bash
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json groups
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json groups --json
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json verify-target
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json send --text "正文" --rid "<rid>"
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json send --text "正文" --rid "<rid>" --mention "黄志举,李迅"
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json send --file /tmp/body.txt --rid "<rid>"
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json send-md --text "正文" --rid "<rid>"
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json send-md --text "正文" --rid "<rid>" --mention "黄志举"
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json send-md --md-file /tmp/md.json --rid "<rid>"
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json send-file report.pdf --rid "<rid>" --text "请查收"
+```
+
+读历史/公告、下载附件、撤回、退群：
+
+```bash
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json get-messages --rid "<rid>" --count 20
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json get-messages --rid "<rid>" --latest "<nextLatest>"
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json get-announcements --rid "<rid>"
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json fetch-file --file-id "<fid>" --rid "<rid>" -o ./attachment.pdf
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json recall --message-id "<msgId>"
+uv run {baseDir}/scripts/appia_claw.py -c /path/to.cred.json leave --rid "<rid>"
+```
+
+## 2. 扩展能力（同一机器人 + scopes）— `appia_extensions.py`
+
+授权与人员/通知/待办：
+
+```bash
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json scopes
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json scopes-request --scopes "channels:write" --reason "建群"
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json users-search --q "张三" --limit 20
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json notifications --limit 20
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json todos --limit 20
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json unread
+```
+
+频道发现与消息：
 
 ```bash
-# 子命令前可加：--cred-file /path/to.cred.json（或 -c）、--timeout 秒；凭证与路径示例见 docs/claw-agent-get-send.md
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json channels-search --name "产品周会"
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json channel-info --rid "<rid>"
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json channel-messages --rid "<rid>" --limit 20
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json channel-messages-search --rid "<rid>" --keyword "上线"
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json channel-members --rid "<rid>"
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json channel-attachments --rid "<rid>"
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json channel-announcements --rid "<rid>"
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json file-metadata --file-id "<fid>"
+```
 
-# 1. 列出当前 agent 已加入的群（rid、群名）
-uv run {baseDir}/scripts/appia_claw.py --cred-file /path/to.cred.json groups
+会议纪要 / 总览元数据：
 
-# 2. 同上，输出接口原始 JSON（便于复制 rid）
-uv run {baseDir}/scripts/appia_claw.py --cred-file /path/to.cred.json groups --json
+```bash
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json meeting-minutes --limit 20
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json meeting-minutes-ingest --limit 20
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json overview-resolve --url "https://projects.appia.vip/<id>?doc=<docKey>"
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json overview-links --rid "<rid>"
+```
+
+写操作（需对应 `:write` scope，缺则 `scopes-request`）与聚合调用：
 
-# 3. 双因子校验：凭证或环境里已配置 TARGET_RID、TARGET_GROUP_NAME
-uv run {baseDir}/scripts/appia_claw.py --cred-file /path/to.cred.json verify-target
+```bash
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json todos-update --id "<todoId>" --status "done"
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json channels-create --name "产品周会群" --members-json '["zhangsan","lisi"]'
+uv run {baseDir}/scripts/appia_extensions.py -c cred.json tool-invoke --tool "appia.todos.list" --args-json '{"limit":5}'
+```
 
-# 4. 向指定 rid 发纯文本（--rid 可换成本地凭证里的 target_rid）
-uv run {baseDir}/scripts/appia_claw.py --cred-file /path/to.cred.json send --text "正文" --rid "<rid>"
+## 文档地图
 
-# 5. 长文本从 UTF-8 文件发送
-uv run {baseDir}/scripts/appia_claw.py --cred-file /path/to.cred.json send --file /tmp/body.txt --rid "<rid>"
+| 文件 | 内容 |
+|------|------|
+| [reference-http.md](reference-http.md) | 入群端点 curl 参考（groups/messages/announcements/file.fetch/upload/send/recall/leave） |
+| [references/auth.md](references/auth.md) | 鉴权 + scopes 授权 |
+| [references/creator-delegate-api.md](references/creator-delegate-api.md) | 扩展能力端点表 |
+| [references/query-api.md](references/query-api.md) / [write-api.md](references/write-api.md) | 读 / 写补充 |
+| [references/rooms-api.md](references/rooms-api.md) | 建频道 |
+| [references/overview-api.md](references/overview-api.md) | 总览 |
+| [references/session-flow.md](references/session-flow.md) | 启动与轮询 |
 
-# 6. 发 Markdown AST：一段纯文本自动包成 md
-uv run {baseDir}/scripts/appia_claw.py --cred-file /path/to.cred.json send-md --text "正文" --rid "<rid>"
+## @提及（--mention）
 
-# 7. 从 JSON 文件读 md 数组
-uv run {baseDir}/scripts/appia_claw.py --cred-file /path/to.cred.json send-md --md-file /tmp/md.json --rid "<rid>"
+`send` 和 `send-md` 均支持 `--mention`（`-m`），接收显示名称或 username，逗号分隔。脚本会先通过 `agent.users.search` API 查询用户名，精确匹配 name/username 优先，否则取搜索结果第一条，再拼成 `@username` 前缀。
 
-# 8. 发送文件到群聊（一步到位：内部自动 upload + send，支持一个或多个文件）
-uv run {baseDir}/scripts/appia_claw.py --cred-file /path/to.cred.json send-file report.pdf --rid "<rid>" --text "请查收附件"
-# 多文件 + 无正文：
-uv run {baseDir}/scripts/appia_claw.py --cred-file /path/to.cred.json send-file a.pdf b.pdf --rid "<rid>"
+```bash
+# 单个 @
+uv run {baseDir}/scripts/appia_claw.py -c cred.json send --text "请查收" --rid "<rid>" --mention "黄志举"
+# 多个 @
+uv run {baseDir}/scripts/appia_claw.py -c cred.json send --text "开会了" --rid "<rid>" --mention "黄志举,李迅"
+# 也可直接用 username
+uv run {baseDir}/scripts/appia_claw.py -c cred.json send-md --text "请确认" --rid "<rid>" --mention "zhiju.huang"
 ```
 
-不用凭证文件时，可在环境中设置 `CLAW_JWT`、`APP_AGENT_ID`、`CLAW_USER_ID`（及场景需要的 `TARGET_RID` 等），命令相同，省略 `--cred-file …` 即可。
+⚠️ 必须先查用户再 @，不要猜测 username。
 
 ## 注意事项
 
-- 最小凭证字段（JSON 或环境变量）：JWT、机器人 `agentId`、创建者 `userId`；勿将填好真实值的文件提交 Git。
+- 最小凭证字段：JWT、机器人 `agentId`、创建者 `userId`；勿将填好真实值的凭证文件提交 Git。
 - 未设置 `APPIA_BASE_URL` 时，脚本默认 `https://sophgo.appia.cn`。
-- HTTP / curl / 错误码：技能根目录 **`../reference-http.md`**（相对本文件）。
-- 发送文件用 `send-file` 一步完成（内部自动 upload + send）；不存在单独的 `upload` 子命令，避免"只上传不发消息"的失败。
+- 入群能力须 bot 已在频道；扩展能力看 scopes。
+- 不猜 rid / username：入群 `groups`；按名 `channels-search`；人名 `users-search`。
+- 附件两步：`send-file` 一步完成（内部 upload → send）；下载用 `fetch-file`。
+- 建频道 `members` 用 username，不要默认把 Claw 创建者塞进去。
+- 总览行数据未落地，只用 `overview-resolve` / `overview-links`，勿调 `overview.read`。
+- 写操作先向用户确认。

package/skills/claw-agent-get-send/src/pyproject.toml

@@ -1,5 +1,5 @@
 [project]
 name = "claw-agent-get-send"
-version = "1.0.1"
-description = "Appia Claw groups.get / message.send helper"
+version = "2.0.0"
+description = "Appia Claw Agent 全量能力：入群收发 + 扩展(scopes)"
 requires-python = ">=3.10"

package/skills/claw-agent-get-send/src/reference-http.md

@@ -0,0 +1,296 @@
+# Claw HTTP API（curl 参考）
+
+---
+
+
+## `GET /api/v1/claw/agent.groups.get`
+
+用于按 `agentId` + `userId` 查询该机器人所在的所有群聊，返回 `rid` 和群名称。
+
+### 鉴权方式
+
+与 `mcpToDos` 一致：
+
+- `authRequired: false`
+- 通过请求头 `Authorization: Bearer <JWT>` 校验
+- 校验规则受以下设置控制：
+  - `Appia_Antagent_JWT_Enable`
+  - `APPIA_JWT_SECRET`
+
+### 请求示例
+
+```bash
+curl -sS -G 'https://YOUR_ROCKETCHAT_HOST/api/v1/claw/agent.groups.get' \
+  -H 'Authorization: Bearer YOUR_MCP_JWT_TOKEN' \
+  --data-urlencode 'agentId=AGENT_BOT_USER_ID' \
+  --data-urlencode 'userId=CREATOR_USER_ID'
+```
+
+### 参数
+
+- `agentId`（query，必填）：OpenClaw 侧 Agent ID（会映射到机器人用户）
+- `userId`（query，必填）：创建者 / 调用方用户 ID（脚本由凭证 `creator_user_id` 等提供）。缺失返回 `userId is required`。
+
+### 成功返回示例
+
+```json
+{
+  "success": true,
+  "data": {
+    "agentId": "AGENT_BOT_USER_ID",
+    "groups": [
+      {
+        "rid": "ROOM_ID_1",
+        "name": "群聊A"
+      },
+      {
+        "rid": "ROOM_ID_2",
+        "name": "群聊B"
+      }
+    ],
+    "total": 2
+  }
+}
+```
+
+### 常见失败
+
+- `{"success":false,"message":"401"}`：JWT 无效或过期
+- `{"success":false,"message":"agentId is required"}`：缺少 `agentId`
+- `{"success":false,"message":"userId is required"}`：缺少 `userId`
+- `{"success":false,"message":"agent not found by agentId"}`：找不到对应 agentId 的机器人
+
+---
+
+## `POST /api/v1/claw/agent.message.send`
+
+用于根据 **`userId` + `rid` + `agentId`** 向指定群聊发送消息。
+
+接口会校验：
+
+1. `rid` 对应房间存在
+2. `agentId` 对应用户存在、为 bot、且 active
+3. 该 `agentId` 确实在该 `rid` 的订阅列表里
+
+满足后，走后端正常发消息逻辑（`executeSendMessage`）。
+
+### 鉴权方式
+
+与 `mcpToDos` 一致：
+
+- `authRequired: false`
+- 通过请求头 `Authorization: Bearer <JWT>` 校验
+- 校验规则受以下设置控制：
+  - `Appia_Antagent_JWT_Enable`
+  - `APPIA_JWT_SECRET`
+
+### 请求示例
+
+#### 示例一：发送纯文本
+
+```bash
+curl -sS -X POST 'https://YOUR_ROCKETCHAT_HOST/api/v1/claw/agent.message.send' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_MCP_JWT_TOKEN' \
+  -d '{
+    "userId": "CREATOR_USER_ID",
+    "rid": "TARGET_ROOM_RID",
+    "agentId": "AGENT_BOT_USER_ID",
+    "msg": "这是一条由 Claw 机器人发送的消息"
+  }'
+```
+
+#### 示例二：发送 Markdown（`md`）
+
+```bash
+curl -sS -X POST 'https://YOUR_ROCKETCHAT_HOST/api/v1/claw/agent.message.send' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_MCP_JWT_TOKEN' \
+  -d '{
+    "userId": "CREATOR_USER_ID",
+    "rid": "TARGET_ROOM_RID",
+    "agentId": "OPENCLAW_AGENT_ID",
+    "md": [
+      {
+        "type": "PARAGRAPH",
+        "value": [
+          { "type": "PLAIN_TEXT", "value": "这是一条 *Markdown* 消息" }
+        ]
+      }
+    ]
+  }'
+```
+
+### 参数
+
+- `userId`（body，必填）：创建者 / 调用方用户 ID（与 `agent.groups.get` 的 query `userId` 同源；脚本由凭证 `creator_user_id` 等提供）
+- `rid`（body，必填）：目标群聊房间 ID
+- `agentId`（body，必填）：OpenClaw 侧 Agent ID（会映射到机器人用户）
+- `msg`（body，可选）：消息文本
+- `md`（body，可选）：Markdown AST（Rocket.Chat `md` 结构）
+- 约束：`msg` 和 `md` 至少提供一个
+
+### 成功返回示例
+
+```json
+{
+  "success": true,
+  "data": {
+    "rid": "TARGET_ROOM_RID",
+    "agentId": "AGENT_BOT_USER_ID",
+    "status": "sent"
+  }
+}
+```
+
+### 常见失败
+
+- `{"success":false,"message":"401"}`：JWT 无效或过期
+- `{"success":false,"message":"userId, rid and agentId are required, and either msg or md must be provided"}`：缺少 `userId`/`rid`/`agentId` 或未提供 `msg`/`md`
+- `{"success":false,"message":"room not found"}`：房间不存在
+- `{"success":false,"message":"agent not found by agentId"}`：找不到对应 agentId 的机器人
+- `{"success":false,"message":"agent must be a bot user"}`：agent 不是 bot
+- `{"success":false,"message":"agent is inactive"}`：机器人未激活
+- `{"success":false,"message":"agent is not in this room"}`：机器人不在该群里
+
+### 带附件发送（`fileIds`）
+
+先上传文件拿到 `file._id`，再放入 `send` 的 `fileIds` 数组：
+
+```json
+{
+  "userId": "CREATOR_USER_ID",
+  "rid": "TARGET_ROOM_RID",
+  "agentId": "AGENT_BOT_USER_ID",
+  "msg": "请查收附件",
+  "fileIds": ["uploaded-file-id"]
+}
+```
+
+---
+
+## `POST /api/v1/claw/agent.file.upload`
+
+上传文件到 Appia 群聊（**不发消息**），返回 `file._id` 供 `agent.message.send` 的 `fileIds` 使用。
+
+### 请求示例
+
+`multipart/form-data`，字段：
+
+| 字段 | 必填 |
+|------|------|
+| userId | 是 |
+| agentId | 是 |
+| rid | 是 |
+| file | 是 |
+
+```bash
+curl -sS -X POST 'https://YOUR_ROCKETCHAT_HOST/api/v1/claw/agent.file.upload' \
+  -H 'Authorization: Bearer YOUR_MCP_JWT_TOKEN' \
+  -F "userId=CREATOR_USER_ID" \
+  -F "agentId=AGENT_BOT_USER_ID" \
+  -F "rid=TARGET_ROOM_RID" \
+  -F "file=@./report.pdf"
+```
+
+### 成功返回示例
+
+```json
+{
+  "success": true,
+  "data": {
+    "file": {
+      "_id": "uploaded-file-id",
+      "name": "report.pdf",
+      "type": "application/pdf",
+      "size": 102400
+    }
+  }
+}
+```
+
+### 常见失败
+
+- `{"success":false,"message":"401"}`：JWT 无效或过期
+- `{"success":false,"message":"agent is not in this room"}`：机器人不在该群里
+- `{"success":false,"message":"file is required"}`：未上传文件
+
+---
+
+## `GET /api/v1/claw/agent.messages.get`
+
+读取频道历史消息（倒序），用响应 `nextLatest` 作为 `latest` 翻页。脚本：`appia_claw.py get-messages`。
+
+```bash
+curl -H "Authorization: Bearer $MCP_JWT" \
+  "$SITE_URL/api/v1/claw/agent.messages.get?userId=$USER_ID&agentId=$AGENT_ID&rid=$RID&count=20"
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| userId, agentId, rid | 是 | |
+| count, offset | 否 | 分页 |
+| latest | 否 | ISO 时间，返回此时间之前 |
+| showThreadMessages | 否 | 默认 true |
+
+---
+
+## `GET /api/v1/claw/agent.announcements.get`
+
+读取频道公告，支持类型过滤。脚本：`appia_claw.py get-announcements`。类型：`0/normal` 普通公告、`1/meeting` 会议公告、`2/summary` 会议纪要。
+
+```bash
+curl -H "Authorization: Bearer $MCP_JWT" \
+  "$SITE_URL/api/v1/claw/agent.announcements.get?userId=$USER_ID&agentId=$AGENT_ID&rid=$RID"
+```
+
+---
+
+## `GET /api/v1/claw/agent.file.fetch`
+
+下载频道附件（二进制流）。脚本：`appia_claw.py fetch-file`。
+
+```bash
+curl -H "Authorization: Bearer $MCP_JWT" \
+  "$SITE_URL/api/v1/claw/agent.file.fetch?userId=$USER_ID&agentId=$AGENT_ID&fileId=$FILE_ID&rid=$RID" \
+  -o ./attachment.pdf
+```
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| userId, agentId, fileId | 是 | |
+| rid | 否 | 建议传，校验文件属于该频道 |
+
+---
+
+## `POST /api/v1/claw/agent.message.recall`
+
+撤回 **bot 自己发送** 的消息。脚本：`appia_claw.py recall`。
+
+```bash
+curl -X POST "$SITE_URL/api/v1/claw/agent.message.recall" \
+  -H "Authorization: Bearer $MCP_JWT" -H "Content-Type: application/json" \
+  -d '{"userId":"'"$USER_ID"'","agentId":"'"$AGENT_ID"'","messageId":"'"$MSG_ID"'"}'
+```
+
+---
+
+## `POST /api/v1/claw/agent.group.leave`
+
+bot 退出指定群聊。脚本：`appia_claw.py leave`。
+
+```bash
+curl -X POST "$SITE_URL/api/v1/claw/agent.group.leave" \
+  -H "Authorization: Bearer $MCP_JWT" -H "Content-Type: application/json" \
+  -d '{"userId":"'"$USER_ID"'","agentId":"'"$AGENT_ID"'","rid":"'"$RID"'"}'
+```
+
+---
+
+## 扩展能力 / 会议纪要 / 总览
+
+`scopes.*`、`users.search`、`notifications/todos/unread`、`channels.*`、`channel.*`、`meeting.minutes.*`、`overview.*`、`tool.invoke` 的 curl 与工作流见 `references/` 目录：
+
+- [auth.md](references/auth.md) · [creator-delegate-api.md](references/creator-delegate-api.md) · [query-api.md](references/query-api.md) · [write-api.md](references/write-api.md)
+- [rooms-api.md](references/rooms-api.md)
+- [overview-api.md](references/overview-api.md) · [session-flow.md](references/session-flow.md)

package/skills/claw-agent-get-send/src/references/auth.md

@@ -0,0 +1,115 @@
+# 鉴权与授权
+
+## 三句话
+
+1. **干活的是机器人**（SophClaw），凭证只有 `MCP_JWT` + `userId` + `agentId`。  
+2. **用户 `authToken` 永不给 Agent。**  
+3. **「授权」** = 用户在 myAgent 点卡片，允许这个机器人使用某些 **scopes**；之后仍是机器人调接口，服务端查库校验。
+
+不是：换用户登录、下发 RC Token、或「创建者本人去操作」。
+
+---
+
+## 配置（USER.md）
+
+| 项 | 含义 |
+|----|------|
+| `SITE_URL` | 如 `https://ssc.appia.cn` |
+| `userId` | Agent 创建者 ID（归属校验，不是登录态） |
+| `agentId` | OpenClaw agent ID |
+| `MCP_JWT` | `Authorization: Bearer …` |
+
+企业识别码 → 地址（大小写不敏感）：SSC → `ssc.appia.cn`；BITMAIN → `appia.cn`；SOPHGO → `sophgo.appia.cn`。
+
+### JWT 规则
+
+- 开启 `Appia_Antagent_JWT_Enable` 时，Bearer JWT 必须有效且未过期。  
+- JWT 的 `sub`（或 `uid`）**必须等于**请求中的 `userId`。  
+- 入群、扩展均同一规则。
+
+> **本 skill 脚本**：`appia_claw.py` 读 `CLAW_JWT`；`appia_extensions.py`（经 `appia_common.py`）同时接受 `CLAW_JWT` 与 `MCP_JWT`，任一非空即可；`APP_AGENT_ID` / `CLAW_USER_ID` 同理。
+
+---
+
+## 两类能力（都是机器人在调）
+
+| | 入群 | 扩展（scopes） |
+|--|------|----------------|
+| 条件 | bot 已在频道 | 服务端 `appiaClawAgentScopes` 通过 |
+| 例子 | 发消息、附件、撤回 | 待办、搜人、建群、总览元数据 |
+| 凭证 | MCP JWT | MCP JWT（同一个） |
+
+扩展能力在服务端会按创建者可见范围执行业务，但对 Agent 而言**没有第二条登录线**。
+
+总览：**元数据**已落地（`overview.resolve`）；**行数据**未落地，见 [overview-api.md](overview-api.md)。
+
+---
+
+## 授权（scopes）
+
+### 是什么
+
+scopes = 服务端记在该 Agent 上的能力开关。  
+创建时默认**只读**；建群 / 改待办等 **write** 要用户点一次卡片。
+
+### 流程
+
+```text
+1. 机器人调写接口（如 channels.create）
+2. 返回 SCOPE_DENIED + missingScope
+3. 机器人 POST claw/agent.scopes.request（说明要哪些 scopes、原因）
+4. 创建者 myAgent 出现卡片 → 用户点「授权」或「拒绝」
+5. 授权成功：服务端合并写入 appiaClawAgentScopes
+6. 机器人 scopes.get 确认，或直接重试原接口
+   （全程只有 MCP_JWT，没有 authToken）
+```
+
+对用户可以说：「请到 Appia 的 myAgent / 我的助手 里点一下授权卡片。」  
+不要说：「请把登录密码/验证码/Token 发给我。」
+
+### 常用 scopes
+
+| Scope | 含义 |
+|-------|------|
+| `users:read` | 搜人（默认有） |
+| `channels:read` / `write` | 搜频道 / 建频道 |
+| `todos:read` / `write` | 待办 |
+| `notifications:read` | 通知 |
+| `meetings:read` | 会议纪要 |
+| `overview:read` | 总览元数据 |
+| `files:read` | 文件元数据 |
+
+默认只读：`channels:read`, `todos:read`, `notifications:read`, `meetings:read`, `overview:read`, `files:read`, `users:read`。
+
+### 相关接口
+
+| 方法 | 路径 | 作用 |
+|------|------|------|
+| GET | `claw/agent.scopes.get` | 查看当前 scopes |
+| POST | `claw/agent.scopes.request` | 申请开权限（发卡片） |
+
+完整扩展 API 见 [creator-delegate-api.md](creator-delegate-api.md)。
+
+---
+
+## 调用示例
+
+```bash
+# 查已授权 scopes
+curl -H "Authorization: Bearer $MCP_JWT" \
+  "$SITE_URL/api/v1/claw/agent.scopes.get?userId=$USER_ID&agentId=$AGENT_ID"
+
+# 申请写权限（用户去 myAgent 点授权）
+curl -X POST "$SITE_URL/api/v1/claw/agent.scopes.request" \
+  -H "Authorization: Bearer $MCP_JWT" -H "Content-Type: application/json" \
+  -d '{"userId":"'"$USER_ID"'","agentId":"'"$AGENT_ID"'","scopes":["channels:write"],"reason":"建群"}'
+```
+
+---
+
+## 明确不做
+
+- 向用户要 authToken / 短信码 / 密码  
+- 把授权说成「请用你的账号登录给 Agent」  
+- 用创建者 ID 冒充提问者读总览行（行接口本身也未落地）  
+- 调用不存在的 `agent.overview.read`