sophhub 0.4.63 → 0.4.65

package/agents/ai-cs-qa/.config.json

@@ -1,10 +1,68 @@
 {
-  "version": "1.0.10",
+  "version": "1.0.11",
   "agent_id": "ai-cs-qa",
   "description": "智能客服，通过 bot API 为客户提供服务",
   "bot_api_enabled": true,
   "workspace": "/home/node/.openclaw/workspace-knowledge/workspace-qa",
   "agent_dependencies": ["ai-cs-admin"],
+  "install": {
+    "bot_api": {
+      "commands": {
+        "text": false
+      },
+      "exec": {
+        "induceCommandStarters": [
+          "uv run",
+          "python",
+          "python3",
+          "node",
+          "bash",
+          "curl",
+          "kubectl",
+          "ls",
+          "env",
+          "cat",
+          "head",
+          "tail",
+          "find",
+          "grep"
+        ],
+        "commandContentDeny": [
+          "sophnet_tools",
+          "get_api_key",
+          "get-api-key",
+          "getApiKey",
+          "openclaw.json",
+          "models.providers",
+          "apiSecret",
+          "api_secret",
+          "apiKey",
+          "api_key",
+          ".base.json"
+        ],
+        "networkDenyTools": [
+          "curl",
+          "wget",
+          "ncat",
+          "nc",
+          "ssh"
+        ],
+        "networkDenyCode": [
+          "requests.",
+          "httpx",
+          "urllib",
+          "fetch(",
+          "http.client"
+        ],
+        "networkDetectUrls": true,
+        "networkAllowHosts": [
+          "sophnet.com",
+          "www.sophnet.com"
+        ],
+        "blockUnlistedNetwork": true
+      }
+    }
+  },
   "post_install": [
     {
       "name": "setup-links",

package/package.json

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

package/skills/agent-install/skill.json

@@ -1,12 +1,19 @@
 {
   "name": "agent-install",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "types": [
     "store"
   ],
   "displayName": "Agent安装",
   "description": "安装或升级 Sophclaw Agent（含占位替换、备份、post_install 脚本与自动安装 skill）。",
   "changelog": [
+    {
+      "changes": [
+        "bot-api 账号安装透传 commands/exec，升级改 deep-merge 保留已有黑名单，修复升级清空 exec 的 BUG"
+      ],
+      "date": "2026-07-24",
+      "version": "0.1.16"
+    },
     {
       "changes": [
         "修复 update_openclaw.py 新建实例时覆盖原实例的严重 BUG：改为按目标 openclaw_id 定位条目，新建时追加、不覆盖同源原实例"
@@ -103,5 +110,5 @@
     }
   ],
   "createdAt": "2026-04-21",
-  "updatedAt": "2026-07-09"
+  "updatedAt": "2026-07-24"
 }

package/skills/agent-install/src/scripts/common.py

@@ -354,12 +354,19 @@ def build_bot_api_account(
     account_name = bot_api.get("account_name") or resolved_name or identity_name_str or agent_label_str or source_agent_id
     enabled = bot_api.get("enabled", True)
 
-    return account_id, {
+    account: dict[str, Any] = {
         "agentId": agent_id,
         "name": account_name,
         "apiSecret": existing_secret or secrets.token_hex(32),
         "enabled": enabled,
     }
+    commands = bot_api.get("commands")
+    if isinstance(commands, dict):
+        account["commands"] = commands
+    exec_config = bot_api.get("exec")
+    if isinstance(exec_config, dict):
+        account["exec"] = exec_config
+    return account_id, account
 
 
 def load_openclaw_config(config_path: Path) -> dict[str, Any]:

package/skills/agent-install/src/scripts/update_openclaw.py

@@ -141,7 +141,11 @@ def ensure_bot_api(
     bot_api = channels.setdefault("bot-api", {})
     accounts = bot_api.setdefault("accounts", {})
     action = "updated" if account_id in accounts else "created"
-    accounts[account_id] = account
+    existing_account = accounts.get(account_id, {})
+    if isinstance(existing_account, dict):
+        accounts[account_id] = deep_merge_dict(existing_account, account)
+    else:
+        accounts[account_id] = account
 
     return {
         "account_id": account_id,

package/skills/agent-install/src/tests/test_bot_api_exec.py

@@ -0,0 +1,116 @@
+"""验证 bot-api 账号的 commands/exec 黑名单能从 .config.json 透传进 openclaw.json，
+且升级时不会覆盖已有黑名单。"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+SCRIPTS = Path(__file__).resolve().parent.parent / "scripts"
+sys.path.insert(0, str(SCRIPTS))
+
+from common import build_bot_api_account, deep_merge_dict  # noqa: E402
+from update_openclaw import ensure_bot_api  # noqa: E402
+
+
+def _agent_def(bot_api: dict | None = None) -> dict:
+    d = {"agent_id": "ai-cs-qa", "bot_api_enabled": True}
+    if bot_api is not None:
+        d["install"] = {"bot_api": bot_api}
+    return d
+
+
+def test_commands_and_exec_propagated():
+    bot_api = {
+        "commands": {"text": False},
+        "exec": {"commandContentDeny": ["apiSecret", "openclaw.json"]},
+    }
+    _, account = build_bot_api_account(_agent_def(bot_api))
+    assert account["commands"] == {"text": False}
+    assert account["exec"]["commandContentDeny"] == ["apiSecret", "openclaw.json"]
+    assert {"agentId", "name", "apiSecret", "enabled", "commands", "exec"} == set(account)
+
+
+def test_omitted_commands_exec_not_added():
+    _, account = build_bot_api_account(_agent_def())
+    assert "commands" not in account
+    assert "exec" not in account
+
+
+def test_upgrade_preserves_existing_exec_not_in_config():
+    """配置里没声明 exec 时，升级不得清掉 openclaw.json 已有 exec。"""
+    config = {
+        "channels": {
+            "bot-api": {
+                "accounts": {
+                    "ai-cs-qa": {
+                        "agentId": "ai-cs-qa",
+                        "name": "ai-cs-qa",
+                        "apiSecret": "old-secret",
+                        "enabled": True,
+                        "exec": {"commandContentDeny": ["hand-added"]},
+                    }
+                }
+            }
+        }
+    }
+    ensure_bot_api(config, _agent_def(), target_agent_id="ai-cs-qa")
+    account = config["channels"]["bot-api"]["accounts"]["ai-cs-qa"]
+    assert account["exec"]["commandContentDeny"] == ["hand-added"]
+    assert account["apiSecret"] == "old-secret"  # 复用旧密钥
+
+
+def test_upgrade_exec_in_config_overrides_existing():
+    """配置里声明了 exec，则以配置为准（source of truth），替换而非追加。"""
+    config = {
+        "channels": {
+            "bot-api": {
+                "accounts": {
+                    "ai-cs-qa": {
+                        "agentId": "ai-cs-qa",
+                        "name": "old-name",
+                        "apiSecret": "old-secret",
+                        "enabled": True,
+                        "exec": {"commandContentDeny": ["hand-added"], "networkDenyTools": ["curl"]},
+                    }
+                }
+            }
+        }
+    }
+    bot_api = {"exec": {"commandContentDeny": ["apiSecret", "openclaw.json"]}}
+    ensure_bot_api(config, _agent_def(bot_api), target_agent_id="ai-cs-qa")
+    account = config["channels"]["bot-api"]["accounts"]["ai-cs-qa"]
+    # 配置声明的列表整体替换
+    assert account["exec"]["commandContentDeny"] == ["apiSecret", "openclaw.json"]
+    # 配置未声明的子键保留
+    assert account["exec"]["networkDenyTools"] == ["curl"]
+    assert account["apiSecret"] == "old-secret"
+
+
+def test_deep_merge_lists_replace():
+    assert deep_merge_dict({"a": [1, 2]}, {"a": [3]}) == {"a": [3]}
+
+
+def test_corrupt_non_dict_account_does_not_crash():
+    """旧账号被写成 null/非 dict 时，退化为整体覆盖，不崩。"""
+    for bad in (None, "x", 0):
+        config = {"channels": {"bot-api": {"accounts": {"ai-cs-qa": bad}}}}
+        ensure_bot_api(config, _agent_def(), target_agent_id="ai-cs-qa")
+        account = config["channels"]["bot-api"]["accounts"]["ai-cs-qa"]
+        assert isinstance(account, dict)
+        assert {"agentId", "name", "apiSecret", "enabled"} <= set(account)
+
+
+def test_old_agent_without_install_bot_api_unchanged_shape():
+    """没有 install.bot_api 的老 agent，账号仍只有原四字段。"""
+    config = {"channels": {"bot-api": {"accounts": {}}}}
+    ensure_bot_api(config, _agent_def(), target_agent_id="ai-cs-qa")
+    account = config["channels"]["bot-api"]["accounts"]["ai-cs-qa"]
+    assert set(account) == {"agentId", "name", "apiSecret", "enabled"}
+
+
+if __name__ == "__main__":
+    for name, fn in list(globals().items()):
+        if name.startswith("test_") and callable(fn):
+            fn()
+            print(f"ok: {name}")

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"