sophhub 0.4.63 → 0.4.65

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`

package/skills/claw-agent-get-send/src/references/creator-delegate-api.md

@@ -0,0 +1,90 @@
+# 扩展能力 API
+
+调用方：**机器人**。鉴权：`Authorization: Bearer MCP_JWT` + `userId` + `agentId`（JWT `sub` === `userId`）。  
+前缀：`{SITE_URL}/api/v1/claw/`。
+
+**授权说明**见 [auth.md](auth.md)。此处只列 **scopes 管控** 的端点。  
+入群见 [../reference-http.md](../reference-http.md)。
+
+---
+
+## 授权相关
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `agent.scopes.get` | 当前 scopes |
+| POST | `agent.scopes.request` | 发 myAgent 授权卡片 |
+
+缺权限业务响应：`code: SCOPE_DENIED`，`missingScope: "channels:write"` 等。
+
+默认只读：`channels:read`, `todos:read`, `notifications:read`, `meetings:read`, `overview:read`, `files:read`, `users:read`。
+
+```bash
+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":"建群"}'
+```
+
+Agent 收到 `SCOPE_DENIED` 时：`scopes.request` → 请用户去 myAgent 点授权 → `scopes.get` 或重试。**不要**要 authToken。
+
+---
+
+## 人员
+
+| 方法 | 路径 | Scope |
+|------|------|-------|
+| GET | `agent.users.search` | `users:read` |
+
+Query：`q`（或 `name`/`text`/`keyword`）、`limit`（默认 20，上限 50）。  
+返回：`users[]` 仅 `_id`、`username`。
+
+---
+
+## 通知 / 待办 / 未读
+
+| 方法 | 路径 | Scope |
+|------|------|-------|
+| GET | `agent.notifications.list` | `notifications:read` |
+| GET | `agent.todos.list` | `todos:read` |
+| GET | `agent.unread.summary` | `channels:read` |
+| POST | `agent.todos.update-status` | `todos:write` |
+
+---
+
+## 频道
+
+| 方法 | 路径 | Scope |
+|------|------|-------|
+| GET | `agent.channels.search` | `channels:read` |
+| GET | `agent.channel.info.get` | `channels:read` |
+| GET | `agent.channel.messages.list` | `channels:read` |
+| GET | `agent.channel.messages.search` | `channels:read` |
+| GET | `agent.channel.members.list` | `channels:read` |
+| GET | `agent.channel.attachments.list` | `channels:read` |
+| GET | `agent.channel.announcements.list` | `channels:read` |
+| GET | `agent.file.metadata.get` | `files:read` |
+| POST | `agent.channels.create` | `channels:write` |
+
+建频道：`members` 按需加人，不要默认加 Claw 创建者。见 [rooms-api.md](rooms-api.md)。
+
+---
+
+## 会议纪要 / 总览元数据
+
+| 方法 | 路径 | Scope |
+|------|------|-------|
+| GET | `agent.meeting.minutes.list` | `meetings:read` |
+| GET | `agent.meeting.minutes.ingest.list` | `meetings:read` |
+| GET | `agent.overview.resolve` | `overview:read` |
+| GET | `agent.channel.overview.links.list` | `overview:read` |
+
+> 预定会议（`agent.meeting.book`）暂未纳入本 skill。  
+总览**行**接口未落地，见 [overview-api.md](overview-api.md)。
+
+---
+
+## 聚合
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `agent.tool.invoke` | `{ userId, agentId, tool, args }` |

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

@@ -0,0 +1,47 @@
+# 项目总览表 API
+
+读取**普通项目总览表**（`type=overview`）。
+
+**不要**直连 `projects.appia.vip/.../overview-rows`。
+
+---
+
+## 已落地：总览元数据
+
+不拉行数据，只解析链接 / id → 元数据。Scope：`overview:read`。  
+调用方：机器人 + MCP JWT。
+
+| 方法 | 路径 |
+|------|------|
+| GET | `claw/agent.overview.resolve` |
+| GET | `claw/agent.channel.overview.links.list` |
+
+```bash
+curl -G "$SITE_URL/api/v1/claw/agent.overview.resolve" \
+  -H "Authorization: Bearer $MCP_JWT" \
+  --data-urlencode "userId=$USER_ID" \
+  --data-urlencode "agentId=$AGENT_ID" \
+  --data-urlencode "url=https://projects.appia.vip/671b5197d786b2b857af5e60?doc=LbU1uE"
+```
+
+参数与 C3A `appia.overview.resolve` 一致（另加 `userId`+`agentId`）。详见 [query-api.md](query-api.md)、[creator-delegate-api.md](creator-delegate-api.md)。
+
+### 如何拿到 overview 链接
+
+1. 入群：`GET agent.announcements.get?rid=...`  
+2. 扩展：`agent.channel.overview.links.list`  
+3. 从 URL 提取 24 位 hex：`https://projects.appia.vip/{overviewId}?doc={docKey}`
+
+---
+
+## 行级读取：未落地
+
+`agent.overview.read` / `agent.overview.permission` **当前未注册**。  
+
+用户要看延期行 / 周报时：
+
+1. 用 `overview.resolve` 确认链接与元数据；  
+2. 告知用户「行级数据接口尚未开通，请在网页打开该总览查看」；  
+3. **不要**猜测调用 `overview.read`，也**不要**用创建者身份冒充提问者去读。
+
+将来若落地，须按提问者 `requestUserId`（来自 stream）鉴权，不能用创建者 `userId` 顶替。

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

@@ -0,0 +1,109 @@
+# 查询 API（Agent 扩展能力）
+
+**调用方是机器人**，MCP JWT。完整端点见 [creator-delegate-api.md](creator-delegate-api.md)。鉴权见 [auth.md](auth.md)。
+
+群聊代发：见 [claw-api.md](../reference-http.md)。  
+总览**元数据**：见 [overview-api.md](overview-api.md)（行数据未落地）。
+
+只有**频道名**时：先 `agent.channels.search`（参数 `name`），不要把频道名当 rid。  
+只有**人名**时：先 `agent.users.search`（参数 `q`），再用返回的 `username`。
+
+---
+
+## 鉴权（所有 claw 查询）
+
+```
+Authorization: Bearer <MCP_JWT>
+Query/Body: userId=<创建者> & agentId=<agentId>
+```
+
+JWT 的 `sub`/`uid` 必须等于 `userId`。对应 scope 见下表。
+
+---
+
+## 0. 搜人
+
+| 做什么 | 方法 | 路径 | Scope |
+|--------|------|------|-------|
+| 按姓名/username 搜人 | GET | `claw/agent.users.search` | `users:read` |
+
+Query：`q`（或 `name`/`text`/`keyword`）、`limit`。
+
+---
+
+## 1. 通知 / 待办 / 未读
+
+| 做什么 | 方法 | 路径 | Scope |
+|--------|------|------|-------|
+| 通知列表 | GET | `claw/agent.notifications.list` | `notifications:read` |
+| 待办列表 | GET | `claw/agent.todos.list` | `todos:read` |
+| 未读汇总 | GET | `claw/agent.unread.summary` | `channels:read` |
+
+常用 query：`limit`、`status`（待办）、`since`（通知）。
+
+```bash
+curl -H "Authorization: Bearer $MCP_JWT" \
+  "$SITE_URL/api/v1/claw/agent.todos.list?userId=$USER_ID&agentId=$AGENT_ID&limit=20"
+```
+
+---
+
+## 2. 频道发现与消息
+
+| 做什么 | 方法 | 路径 | Scope |
+|--------|------|------|-------|
+| 按名搜频道 | GET | `claw/agent.channels.search` | `channels:read` |
+| 频道信息 | GET | `claw/agent.channel.info.get` | `channels:read` |
+| 成员 | GET | `claw/agent.channel.members.list` | `channels:read` |
+| 最近消息 | GET | `claw/agent.channel.messages.list` | `channels:read` |
+| 频道内搜索 | GET | `claw/agent.channel.messages.search` | `channels:read` |
+| 附件列表 | GET | `claw/agent.channel.attachments.list` | `channels:read` |
+| 公告 | GET | `claw/agent.channel.announcements.list` | `channels:read` |
+| 文件元数据 | GET | `claw/agent.file.metadata.get` | `files:read` |
+
+频道类参数：`rid` 或 `name`/`channelName`；搜索另需 `keyword`。
+
+---
+
+## 3. 会议纪要 / 总览元数据
+
+| 做什么 | 方法 | 路径 | Scope |
+|--------|------|------|-------|
+| 纪要列表 | GET | `claw/agent.meeting.minutes.list` | `meetings:read` |
+| 纪要入库记录 | GET | `claw/agent.meeting.minutes.ingest.list` | `meetings:read` |
+| 总览链接→元数据 | GET | `claw/agent.overview.resolve` | `overview:read` |
+| 扫频道总览链接 | GET | `claw/agent.channel.overview.links.list` | `overview:read` |
+
+行级总览（延期/周报）须 `requestUserId`，见 [overview-api.md](overview-api.md)。
+
+---
+
+## 4. 聚合调用
+
+```
+POST /api/v1/claw/agent.tool.invoke
+```
+
+```json
+{
+  "userId": "<creator>",
+  "agentId": "<agentId>",
+  "tool": "appia.channels.search",
+  "args": { "name": "产品周会", "limit": 5 }
+}
+```
+
+`tool` 为对应 C3A 名（如 `appia.todos.list`）；仅支持上表已映射工具。
+
+---
+
+## 5. 推荐链路
+
+```
+「某某频道最近聊什么」→ agent.channels.search → channel.messages.list / search
+「我的待办 / 通知」    → agent.todos.list / notifications.list
+「会议纪要」          → agent.meeting.minutes.list
+「总览链接是啥」      → agent.overview.resolve（行数据未落地，勿调 overview.read）
+```
+
+写操作（改待办、建频道）见 [write-api.md](write-api.md)、[rooms-api.md](rooms-api.md)。预定会议暂未纳入本 skill。