sophhub 0.4.63 → 0.4.64

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。

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

@@ -0,0 +1,79 @@
+# 创建频道（Agent 扩展能力）
+
+**调用方是机器人：** `POST /api/v1/claw/agent.channels.create`  
+鉴权：MCP JWT。Scope：`channels:write`（`scopes.request` → myAgent 卡片）。  
+服务端按创建者权限落库，但对 Agent 而言仍是机器人调接口，无用户 authToken。
+
+---
+
+## 主入口
+
+```
+POST /api/v1/claw/agent.channels.create
+```
+
+| Body | 必填 | 说明 |
+|------|------|------|
+| `userId` / `agentId` | 是 | MCP 上下文 |
+| `members` | 建议 | username 字符串数组；按需加人，**不必**含 Claw Agent 创建者 |
+| `name` | 否 | 可空；空时服务端可按成员生成 |
+| `depIds` | 否 | 部门 id，整部门加入 |
+| `extraData` | 否 | 见下 |
+| `readOnly` | 否 | 默认 false |
+
+**`extraData` 常见字段：**
+
+```json
+{
+  "all": false,
+  "employeeType": [],
+  "topic": "",
+  "description": "",
+  "rt": "p",
+  "broadcast": false,
+  "appiaUsage": []
+}
+```
+
+会议专用频道可用 `"appiaUsage": ["Room_Sort_Meeting"]`。
+
+### 示例
+
+```bash
+curl -X POST "$SITE_URL/api/v1/claw/agent.channels.create" \
+  -H "Authorization: Bearer $MCP_JWT" -H "Content-Type: application/json" \
+  -d '{
+    "userId": "'"$USER_ID"'",
+    "agentId": "'"$AGENT_ID"'",
+    "name": "产品周会群",
+    "members": ["zhangsan", "lisi"],
+    "extraData": { "topic": "产品" }
+  }'
+```
+
+成功返回 `data.rid` / `data.channel`。可用作后续 Bot 入群发消息的 rid。
+
+---
+
+## 推荐链路
+
+```
+用户：建一个有张三李四的群
+  → users.search 解析 username
+  → members = [zhangsan, lisi]（按需；不要默认加 Claw 创建者）
+  → 若提问者本人也要进群 → 再 search 其 username 加入
+  → 确认 name
+  → 确认 Agent 已有 channels:write（否则 scopes.request）
+  → POST claw/agent.channels.create
+  → 返回 rid
+```
+
+> 预定会议（`agent.meeting.book`）暂未纳入本 skill；需要时引导用户在 Appia 网页操作。
+
+**注意：**
+
+- **不要默认把 Claw Agent 创建者加进 `members`**；只加用户明确要的人。  
+- 提问者要进群时单独加入其 username。  
+- 成员用 **username**，不是显示名；先用 `agent.users.search`。  
+- 缺 `channels:write` → `agent.scopes.request`，请创建者在 myAgent 点授权。  
+- 私有群 `groups.create` / 讨论组等尚未挂接；当前 Agent 只支持上述 `channels.create`。

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

@@ -0,0 +1,61 @@
+# Session 启动与轮询（MCP）
+
+业务见 [../SKILL.md](../SKILL.md)。鉴权见 [auth.md](auth.md)。
+
+---
+
+## 启动顺序
+
+```
+1. Read USER.md → SITE_URL、userId、agentId、MCP_JWT
+2. 缺配置 → 请用户在 Appia 创建 Claw Agent（不要向用户要登录态 / 短信）
+3. GET agent.groups.get → 已入群频道
+4. 可选：GET agent.todos.list / agent.scopes.get 探测扩展能力
+5. 写接口若 SCOPE_DENIED → scopes.request，请用户去 myAgent 点「授权」给本机器人，再重试
+```
+
+---
+
+## USER.md
+
+```markdown
+## Appia Claw
+
+| 项目 | 值 |
+|------|-----|
+| SITE_URL | `https://ssc.appia.cn` |
+| userId | `<创建者 RC ID>` |
+| agentId | `<OpenClaw agentId>` |
+| MCP JWT | `<Bearer token>` |
+
+### 企业识别码 → 地址（选型时用，大小写不敏感）
+
+| 识别码 | SITE_URL |
+|--------|----------|
+| SSC | https://ssc.appia.cn |
+| BITMAIN | https://appia.cn |
+| SOPHGO | https://sophgo.appia.cn |
+```
+
+---
+
+## sender_id → rid
+
+| 格式 | rid |
+|------|-----|
+| `SSC-{rid}-{YYYYMMDD}` | 中间段 |
+| `openclaw-control-ui` | 无 rid，问用户 |
+
+同条 stream 可能带 **`requestUserId`**（提问者）。总览行接口未落地；有该字段时也勿冒充去调不存在的 `overview.read`。
+
+---
+
+## 轮询（cron）
+
+`groups.get` → `messages.get` → 识别 @我 → 入群回复 / 扩展能力 API → `message.send`。
+
+---
+
+## 相关
+
+- [auth.md](auth.md) · [creator-delegate-api.md](creator-delegate-api.md) · [claw-api.md](claw-api.md)

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

@@ -0,0 +1,38 @@
+# 写操作
+
+调用方是机器人，MCP JWT。  
+**缺 write scope：** `scopes.request` → 用户在 myAgent 点「授权」→ **同一机器人**重试。不要要 authToken。  
+鉴权见 [auth.md](auth.md)。
+
+写前向用户确认。只读见 [query-api.md](query-api.md)。
+
+---
+
+## 1. 更新待办状态
+
+```
+POST /api/v1/claw/agent.todos.update-status
+```
+
+| Body | 说明 |
+|------|------|
+| `userId` / `agentId` | 必填 |
+| `id` | 待办 id |
+| `status` | 状态 |
+| `reminderTime` | 可选 |
+
+Scope：`todos:write`。
+
+---
+
+## 2. 创建频道
+
+见 [rooms-api.md](rooms-api.md)。需要 `channels:write`。
+
+> 预定会议（`agent.meeting.book`）暂未纳入本 skill；需要时引导用户在 Appia 网页操作或用独立 skill。
+
+---
+
+## 3. 尚未包装
+
+清通知、从消息创建待办、取消会议等**没有** claw 封装。缺能力时告知用户用网页操作，不要引导 RC 登录。