sophhub 0.4.63 → 0.4.65

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 登录。

package/skills/claw-agent-get-send/src/scripts/appia_claw.py

@@ -309,7 +309,7 @@ def _chunk_text(text: str, size: int) -> list[str]:
 
 
 def cmd_send(args: argparse.Namespace) -> int:
-    """发送纯文本消息（支持分段）。"""
+    """发送纯文本消息（支持分段与 @提及）。"""
     rid = args.rid or _cfg("TARGET_RID")
     if not rid:
         print("⚠️ send 需要 TARGET_RID 或 --rid", file=sys.stderr)
@@ -324,6 +324,10 @@ def cmd_send(args: argparse.Namespace) -> int:
     else:
         print("⚠️ 需要 --file 或 --text", file=sys.stderr)
         return 1
+    # 解析 @提及（传入 rid 以校验群内成员）
+    mentions = _resolve_mentions(getattr(args, "mention", "") or "", args.timeout, rid=rid)
+    if mentions:
+        text = " ".join(mentions) + " " + text
     chunk_raw = _cfg("APPIA_MSG_CHUNK_SIZE")
     chunk_size = int(chunk_raw) if chunk_raw else DEFAULT_CHUNK_SIZE
     parts = _chunk_text(text, chunk_size)
@@ -364,11 +368,16 @@ def cmd_send_md(args: argparse.Namespace) -> int:
             print(f"⚠️ 读取 --md-file 失败: {exc}", file=sys.stderr)
             return 1
     elif args.text:
+        # 解析 @提及（传入 rid 以校验群内成员）
+        text = args.text
+        mentions = _resolve_mentions(getattr(args, "mention", "") or "", args.timeout, rid=rid)
+        if mentions:
+            text = " ".join(mentions) + " " + text
         # 从纯文本自动构造简单 md 结构
         md = [
             {
                 "type": "PARAGRAPH",
-                "value": [{"type": "PLAIN_TEXT", "value": args.text}]
+                "value": [{"type": "PLAIN_TEXT", "value": text}]
             }
         ]
     else:
@@ -415,6 +424,253 @@ def cmd_send_file(args: argparse.Namespace) -> int:
     return 0
 
 
+# ------------------------------------------------------------------
+# 入群扩展子命令：messages.get / announcements.get / file.fetch / recall / leave
+# 复用上方 _cfg / _jwt / _agent_id / _user_id / _base_url，不改动既有子命令。
+# ------------------------------------------------------------------
+
+
+def _claw_get(path: str, params: dict[str, Any], timeout: float) -> dict[str, Any]:
+    base = _base_url()
+    q = parse.urlencode({k: v for k, v in params.items() if v is not None and v != ""})
+    url = f"{base}/api/v1/claw/{path}?{q}" if q else f"{base}/api/v1/claw/{path}"
+    req = request.Request(
+        url,
+        headers={"Authorization": f"Bearer {_jwt()}", "Accept": "application/json"},
+        method="GET",
+    )
+    try:
+        with request.urlopen(req, timeout=timeout) as resp:
+            body = resp.read().decode("utf-8")
+    except error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"HTTP {exc.code}: {body}") from exc
+    data = json.loads(body)
+    if not data.get("success"):
+        raise RuntimeError(json.dumps(data, ensure_ascii=False))
+    return data
+
+
+def _claw_post(path: str, body_obj: dict[str, Any], timeout: float) -> dict[str, Any]:
+    base = _base_url()
+    url = f"{base}/api/v1/claw/{path}"
+    raw = json.dumps(body_obj, ensure_ascii=False).encode("utf-8")
+    req = request.Request(
+        url,
+        data=raw,
+        headers={
+            "Authorization": f"Bearer {_jwt()}",
+            "Content-Type": "application/json; charset=utf-8",
+            "Accept": "application/json",
+        },
+        method="POST",
+    )
+    try:
+        with request.urlopen(req, timeout=timeout) as resp:
+            out = resp.read().decode("utf-8")
+    except error.HTTPError as exc:
+        out = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"HTTP {exc.code}: {out}") from exc
+    data = json.loads(out)
+    if not data.get("success"):
+        raise RuntimeError(json.dumps(data, ensure_ascii=False))
+    return data
+
+
+def _resolve_mentions(names: str, timeout: float, rid: str | None = None) -> list[str]:
+    """将逗号分隔的显示名称（或 username）通过 agent.users.search 解析为 @mention 列表。
+
+    规则：
+    1. 先精确匹配 name 或 username，否则取搜索结果第一条。找不到则 stderr 警告并跳过。
+    2. 若指定 rid，则拉取频道成员，检查用户是否在群内：在群内用 @username，不在群内用 @显示名称。
+    """
+    if not names or not names.strip():
+        return []
+
+    # 有 rid 时预取频道成员 username 集合（一次拉取，全员复用）
+    member_usernames: set[str] = set()
+    if rid:
+        try:
+            mparams: dict[str, Any] = {
+                "userId": _user_id(),
+                "agentId": _agent_id(),
+                "rid": rid,
+            }
+            mdata = _claw_get("agent.channel.members.list", mparams, timeout)
+            members = (mdata.get("data") or {}).get("members") or []
+            for m in members:
+                if isinstance(m, dict) and m.get("username"):
+                    member_usernames.add(m["username"])
+        except Exception as exc:
+            print(f"⚠️ 获取频道成员失败（将跳过群内校验）: {exc}", file=sys.stderr)
+
+    result: list[str] = []
+    for raw_name in names.split(","):
+        name = raw_name.strip()
+        if not name:
+            continue
+        params: dict[str, Any] = {
+            "userId": _user_id(),
+            "agentId": _agent_id(),
+            "q": name,
+            "limit": 5,
+        }
+        data = _claw_get("agent.users.search", params, timeout)
+        users = (data.get("data") or {}).get("users") or []
+        if not users:
+            # 查不到用户，直接用显示名称
+            print(f"⚠️ 未找到用户: {name}，将直接 @显示名称", file=sys.stderr)
+            result.append(f"@{name}")
+            continue
+        # 精确匹配优先
+        matched: dict[str, Any] | None = None
+        for u in users:
+            if u.get("name") == name or u.get("username") == name:
+                matched = u
+                break
+        if matched is None:
+            matched = users[0]
+        matched_name = (matched.get("name") or "").strip()
+        username = (matched.get("username") or "").strip()
+        if not matched_name:
+            matched_name = name
+        if not username:
+            print(f"⚠️ 用户 {name} 缺少 username 字段，将直接 @显示名称", file=sys.stderr)
+            result.append(f"@{matched_name}")
+            continue
+        # 有 rid 时校验是否在群内
+        if rid and member_usernames and username not in member_usernames:
+            result.append(f"@{matched_name}")
+        else:
+            result.append(f"@{username}")
+    return result
+
+
+def cmd_get_messages(args: argparse.Namespace) -> int:
+    """读取频道历史消息（倒序，nextLatest 翻页）。"""
+    rid = args.rid or _cfg("TARGET_RID")
+    if not rid:
+        print("⚠️ get-messages 需要 TARGET_RID 或 --rid", file=sys.stderr)
+        return 1
+    params: dict[str, Any] = {
+        "userId": _user_id(),
+        "agentId": _agent_id(),
+        "rid": rid,
+        "count": args.count,
+        "offset": args.offset,
+        "latest": args.latest,
+        "showThreadMessages": "true" if args.show_thread else "false",
+    }
+    data = _claw_get("agent.messages.get", params, args.timeout)
+    if args.json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return 0
+    payload = data.get("data") or {}
+    msgs = payload.get("messages") or []
+    print(f"rid={rid} count={len(msgs)} nextLatest={payload.get('nextLatest', '')}")
+    for m in msgs:
+        if not isinstance(m, dict):
+            continue
+        print(f"- ts={m.get('ts')} from={m.get('u', {}).get('username', '')} msg={m.get('msg', '')}")
+    return 0
+
+
+_ANN_TYPE_MAP = {"0": "普通", "1": "会议", "2": "纪要", "3": "HORS"}
+
+
+def cmd_get_announcements(args: argparse.Namespace) -> int:
+    """读取频道公告，支持类型过滤。"""
+    rid = args.rid or _cfg("TARGET_RID")
+    if not rid:
+        print("⚠️ get-announcements 需要 TARGET_RID 或 --rid", file=sys.stderr)
+        return 1
+    params: dict[str, Any] = {
+        "userId": _user_id(),
+        "agentId": _agent_id(),
+        "rid": rid,
+        "type": args.type,
+        "announcementType": args.announcement_type,
+    }
+    data = _claw_get("agent.announcements.get", params, args.timeout)
+    if args.json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return 0
+    payload = data.get("data") or {}
+    anns = payload.get("announcements") or payload.get("items") or []
+    print(f"rid={rid} total={len(anns)}")
+    for a in anns:
+        if not isinstance(a, dict):
+            continue
+        t = str(a.get("type", a.get("announcementType", "")))
+        tname = _ANN_TYPE_MAP.get(t, t)
+        print(f"- type={tname} ts={a.get('ts', a.get('createdAt', ''))} msg={a.get('message', a.get('msg', ''))}")
+    return 0
+
+
+def cmd_fetch_file(args: argparse.Namespace) -> int:
+    """下载频道附件（agent.file.fetch，二进制流）。"""
+    if not args.file_id:
+        print("⚠️ fetch-file 需要 --file-id", file=sys.stderr)
+        return 1
+    params: dict[str, Any] = {
+        "userId": _user_id(),
+        "agentId": _agent_id(),
+        "fileId": args.file_id,
+        "rid": args.rid or _cfg("TARGET_RID"),
+    }
+    base = _base_url()
+    q = parse.urlencode({k: v for k, v in params.items() if v is not None and v != ""})
+    url = f"{base}/api/v1/claw/agent.file.fetch?{q}"
+    req = request.Request(
+        url,
+        headers={"Authorization": f"Bearer {_jwt()}"},
+        method="GET",
+    )
+    try:
+        with request.urlopen(req, timeout=args.timeout) as resp:
+            content = resp.read()
+    except error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        print(f"⚠️ HTTP {exc.code}: {body}", file=sys.stderr)
+        return 1
+    out_path = os.path.expanduser(args.output)
+    with open(out_path, "wb") as fh:
+        fh.write(content)
+    print(f"saved: {out_path}  bytes={len(content)}")
+    return 0
+
+
+def cmd_recall(args: argparse.Namespace) -> int:
+    """撤回 bot 自己发送的消息。"""
+    if not args.message_id:
+        print("⚠️ recall 需要 --message-id", file=sys.stderr)
+        return 1
+    body_obj: dict[str, Any] = {
+        "userId": _user_id(),
+        "agentId": _agent_id(),
+        "messageId": args.message_id,
+    }
+    data = _claw_post("agent.message.recall", body_obj, args.timeout)
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_leave(args: argparse.Namespace) -> int:
+    """bot 退出指定群聊。"""
+    rid = args.rid or _cfg("TARGET_RID")
+    if not rid:
+        print("⚠️ leave 需要 TARGET_RID 或 --rid", file=sys.stderr)
+        return 1
+    body_obj: dict[str, Any] = {
+        "userId": _user_id(),
+        "agentId": _agent_id(),
+        "rid": rid,
+    }
+    data = _claw_post("agent.group.leave", body_obj, args.timeout)
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+    return 0
+
+
 def main() -> int:
     global _CRED
     p = argparse.ArgumentParser(description="Appia Claw (groups.get / message.send)")
@@ -438,6 +694,7 @@ def main() -> int:
     sp.add_argument("--file", "-f", help="长文本文件")
     sp.add_argument("--text", "-t", help="短文本")
     sp.add_argument("--rid", help="覆盖 TARGET_RID")
+    sp.add_argument("--mention", "-m", help="要 @ 的用户显示名称或 username，逗号分隔（如：张三,李四）。先通过 API 查用户名再 @")
     sp.add_argument("--json", action="store_true")
     sp.set_defaults(_run=cmd_send)
 
@@ -446,6 +703,7 @@ def main() -> int:
     smp.add_argument("--md-file", "-f", help="md JSON 文件路径")
     smp.add_argument("--text", "-t", help="纯文本（自动转为简单 md 结构）")
     smp.add_argument("--rid", help="覆盖 TARGET_RID")
+    smp.add_argument("--mention", "-m", help="要 @ 的用户显示名称或 username，逗号分隔（如：张三,李四）。先通过 API 查用户名再 @")
     smp.add_argument("--json", action="store_true")
     smp.set_defaults(_run=cmd_send_md)
 
@@ -456,6 +714,36 @@ def main() -> int:
     sfp.add_argument("--json", action="store_true")
     sfp.set_defaults(_run=cmd_send_file)
 
+    gmp = sub.add_parser("get-messages", help="GET agent.messages.get（频道历史，倒序，nextLatest 翻页）")
+    gmp.add_argument("--rid", help="覆盖 TARGET_RID")
+    gmp.add_argument("--count", type=int, default=20)
+    gmp.add_argument("--offset", type=int, default=0)
+    gmp.add_argument("--latest", help="ISO 时间，返回此时间之前的消息（翻页用 nextLatest）")
+    gmp.add_argument("--show-thread", dest="show_thread", action="store_true", default=True)
+    gmp.add_argument("--json", action="store_true")
+    gmp.set_defaults(_run=cmd_get_messages)
+
+    gap = sub.add_parser("get-announcements", help="GET agent.announcements.get（频道公告，可按类型过滤）")
+    gap.add_argument("--rid", help="覆盖 TARGET_RID")
+    gap.add_argument("--type", help="normal/meeting/summary/hors 或 0-3")
+    gap.add_argument("--announcement-type", dest="announcement_type", help="同 --type 的另一字段名")
+    gap.add_argument("--json", action="store_true")
+    gap.set_defaults(_run=cmd_get_announcements)
+
+    ffp = sub.add_parser("fetch-file", help="GET agent.file.fetch（下载频道附件，二进制流）")
+    ffp.add_argument("--file-id", required=True, help="附件 fileId")
+    ffp.add_argument("--rid", help="覆盖 TARGET_RID（建议传，校验文件属于该频道）")
+    ffp.add_argument("-o", "--output", required=True, help="保存到本地路径")
+    ffp.set_defaults(_run=cmd_fetch_file)
+
+    rp = sub.add_parser("recall", help="POST agent.message.recall（撤回 bot 自己发的消息）")
+    rp.add_argument("--message-id", required=True, help="消息 id")
+    rp.set_defaults(_run=cmd_recall)
+
+    lp = sub.add_parser("leave", help="POST agent.group.leave（bot 退出群聊）")
+    lp.add_argument("--rid", help="覆盖 TARGET_RID")
+    lp.set_defaults(_run=cmd_leave)
+
     args = p.parse_args()
     if args.cred_file:
         _CRED = load_cred_file(args.cred_file)