sophhub 0.4.63 → 0.4.65

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

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""Appia Claw 共享 helper：凭证解析 + JWT + 通用 HTTP（GET/POST JSON/multipart/raw）。
+
+供 appia_extensions.py 复用。appia_claw.py 保留自己的实现不动。
+"""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import sys
+from typing import Any
+from urllib import error, parse, request
+
+DEFAULT_APPIA_BASE_URL = "https://sophgo.appia.cn"
+
+# 凭证文件解析后的规范字段；未用凭证文件时为 None。
+CRED: dict[str, str] | None = None
+
+# (规范名, JSON/文件中允许的别名)。任一别名非空即写入规范键。
+CRED_CANON_ALIASES: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("APPIA_BASE_URL", ("APPIA_BASE_URL", "appia_base_url", "base_url", "APPIA_HOST", "appia_host")),
+    ("CLAW_JWT", ("CLAW_JWT", "claw_jwt", "jwt", "APPIA_CLAW_JWT", "appia_claw_jwt", "MCP_JWT", "mcp_jwt")),
+    ("APP_AGENT_ID", ("APP_AGENT_ID", "app_agent_id", "agent_id", "AGENT_ID")),
+    (
+        "CLAW_USER_ID",
+        (
+            "CLAW_USER_ID",
+            "claw_user_id",
+            "user_id",
+            "USER_ID",
+            "creator_user_id",
+            "APPIA_USER_ID",
+            "appia_user_id",
+        ),
+    ),
+    ("TARGET_RID", ("TARGET_RID", "target_rid")),
+    ("TARGET_GROUP_NAME", ("TARGET_GROUP_NAME", "target_group_name")),
+    ("TARGET_GROUP_MATCH", ("TARGET_GROUP_MATCH", "target_group_match")),
+)
+
+
+def _scalar_from_raw(raw: dict[str, Any], aliases: tuple[str, ...]) -> str:
+    for key in aliases:
+        if key not in raw:
+            continue
+        val = raw[key]
+        if val is None:
+            continue
+        s = str(val).strip()
+        if s:
+            return s
+    return ""
+
+
+def load_cred_file(path: str) -> dict[str, str]:
+    exp = os.path.expanduser(path)
+    try:
+        with open(exp, encoding="utf-8") as f:
+            raw_any: Any = json.load(f)
+    except OSError as exc:
+        sys.exit(f"无法读取凭证文件 {exp}: {exc}")
+    except json.JSONDecodeError as exc:
+        sys.exit(f"凭证文件 JSON 无效 {exp}: {exc}")
+    if not isinstance(raw_any, dict):
+        sys.exit("凭证文件顶层必须是 JSON 对象")
+    out: dict[str, str] = {}
+    for canon, aliases in CRED_CANON_ALIASES:
+        v = _scalar_from_raw(raw_any, aliases)
+        if v:
+            out[canon] = v
+    return out
+
+
+def init_cred(cred_file: str | None) -> None:
+    """在 main() 解析完 --cred-file 后调用，设置模块级 CRED。"""
+    global CRED
+    if cred_file:
+        CRED = load_cred_file(cred_file)
+
+
+def _env(name: str, *fallbacks: str) -> str:
+    for key in (name,) + fallbacks:
+        v = os.environ.get(key, "").strip()
+        if v:
+            return v
+    return ""
+
+
+def cfg(canon: str, *env_fallbacks: str) -> str:
+    """凭证文件非空字段优先，否则回退环境变量。"""
+    if CRED:
+        v = CRED.get(canon, "").strip()
+        if v:
+            return v
+    return _env(canon, *env_fallbacks)
+
+
+def base_url() -> str:
+    base = cfg("APPIA_BASE_URL", "APPIA_HOST").rstrip("/")
+    if not base:
+        base = DEFAULT_APPIA_BASE_URL.rstrip("/")
+    return base
+
+
+def jwt() -> str:
+    tok = cfg("CLAW_JWT", "APPIA_CLAW_JWT", "MCP_JWT")
+    if not tok:
+        sys.exit("缺少配置：凭证文件或环境变量 CLAW_JWT（或 MCP_JWT）")
+    return tok
+
+
+def agent_id() -> str:
+    aid = cfg("APP_AGENT_ID", "AGENT_ID")
+    if not aid:
+        sys.exit("缺少配置：凭证文件或环境变量 APP_AGENT_ID（或 AGENT_ID）")
+    return aid
+
+
+def user_id() -> str:
+    uid = cfg("CLAW_USER_ID", "USER_ID", "APPIA_USER_ID")
+    if not uid:
+        sys.exit(
+            "缺少配置：凭证文件或环境变量 CLAW_USER_ID（或 USER_ID、APPIA_USER_ID、creator_user_id）"
+        )
+    return uid
+
+
+def _auth_headers() -> dict[str, str]:
+    return {"Authorization": f"Bearer {jwt()}", "Accept": "application/json"}
+
+
+def claw_url(path: str) -> str:
+    """path 形如 'agent.users.search'，返回 {base}/api/v1/claw/{path}。"""
+    return f"{base_url()}/api/v1/claw/{path}"
+
+
+def api_get(path: str, params: dict[str, Any], timeout: float) -> dict[str, Any]:
+    """GET {base}/api/v1/claw/{path}?params，返回 JSON dict。"""
+    qs = parse.urlencode({k: v for k, v in params.items() if v is not None and v != ""})
+    url = f"{claw_url(path)}?{qs}" if qs else claw_url(path)
+    req = request.Request(url, headers=_auth_headers(), 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 api_get_raw(path: str, params: dict[str, Any], timeout: float) -> bytes:
+    """GET 二进制流（如 agent.file.fetch），返回原始 bytes。"""
+    qs = parse.urlencode({k: v for k, v in params.items() if v is not None and v != ""})
+    url = f"{claw_url(path)}?{qs}" if qs else claw_url(path)
+    req = request.Request(url, headers=_auth_headers(), method="GET")
+    try:
+        with request.urlopen(req, timeout=timeout) as resp:
+            return resp.read()
+    except error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"HTTP {exc.code}: {body}") from exc
+
+
+def api_post_json(path: str, body: dict[str, Any], timeout: float) -> dict[str, Any]:
+    """POST JSON 到 {base}/api/v1/claw/{path}，返回 JSON dict。"""
+    raw = json.dumps(body, ensure_ascii=False).encode("utf-8")
+    headers = _auth_headers()
+    headers["Content-Type"] = "application/json; charset=utf-8"
+    req = request.Request(claw_url(path), data=raw, headers=headers, 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 api_post_multipart(
+    path: str,
+    fields: dict[str, str],
+    file_field: str,
+    file_path: str,
+    timeout: float,
+    file_field_name: str | None = None,
+) -> dict[str, Any]:
+    """POST multipart/form-data 到 claw/{path}，单文件。返回 JSON dict。
+
+    file_field_name 为上传表单里的 filename，默认取 file_path 的 basename。
+    """
+    fpath = os.path.expanduser(file_path)
+    fname = file_field_name or os.path.basename(fpath)
+    mime_type, _ = mimetypes.guess_type(fpath)
+    if not mime_type:
+        mime_type = "application/octet-stream"
+
+    boundary = "----ClawUploadBoundary" + os.urandom(16).hex()
+    parts: list[bytes] = []
+    for name, value in fields.items():
+        parts.append(f"--{boundary}\r\n".encode())
+        parts.append(f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode())
+        parts.append(f"{value}\r\n".encode())
+    parts.append(f"--{boundary}\r\n".encode())
+    parts.append(
+        f'Content-Disposition: form-data; name="{file_field}"; filename="{fname}"\r\n'.encode()
+    )
+    parts.append(f"Content-Type: {mime_type}\r\n\r\n".encode())
+    with open(fpath, "rb") as fh:
+        parts.append(fh.read())
+    parts.append(f"\r\n--{boundary}--\r\n".encode())
+    body = b"".join(parts)
+
+    headers = _auth_headers()
+    headers["Content-Type"] = f"multipart/form-data; boundary={boundary}"
+    req = request.Request(claw_url(path), data=body, headers=headers, 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 add_cred_arg(parser: Any) -> None:
+    parser.add_argument(
+        "--cred-file",
+        "-c",
+        metavar="PATH",
+        help="JSON 凭证文件（含 Appia 地址、JWT、agentId 等）；文件中非空字段优先于环境变量",
+    )
+
+
+def add_timeout_arg(parser: Any, default: float = 60.0) -> None:
+    parser.add_argument("--timeout", type=float, default=default)
+
+
+def add_json_arg(parser: Any) -> None:
+    parser.add_argument("--json", action="store_true", help="输出接口原始 JSON")
+
+
+def emit(data: Any, as_json: bool, human: str) -> int:
+    if as_json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+    else:
+        print(human)
+    return 0

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

@@ -0,0 +1,370 @@
+#!/usr/bin/env python3
+"""Appia Claw 扩展能力：scopes + 人员/通知/待办/未读 + 频道 + 会议纪要/总览 + 写操作 + 聚合调用。
+
+鉴权与 appia_claw.py 一致：MCP/CLAW JWT + userId + agentId。共享 helper 见 appia_common。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+import appia_common as ac
+
+
+def _channel_params(args: argparse.Namespace) -> dict[str, Any]:
+    """频道类接口：--rid 优先，否则用 --name / --channel-name。"""
+    rid = args.rid or ac.cfg("TARGET_RID")
+    if rid:
+        return {"rid": rid}
+    name = args.name or args.channel_name
+    if not name:
+        sys.exit("⚠️ 需要 --rid（或 TARGET_RID）或 --name")
+    return {"name": name}
+
+
+def _load_json_arg(json_str: str | None, json_file: str | None) -> Any:
+    if json_str is not None:
+        try:
+            return json.loads(json_str)
+        except json.JSONDecodeError as exc:
+            sys.exit(f"⚠️ --json 参数解析失败: {exc}")
+    if json_file:
+        import os
+
+        with open(os.path.expanduser(json_file), encoding="utf-8") as f:
+            return json.load(f)
+    return None
+
+
+def _common_params() -> dict[str, Any]:
+    return {"userId": ac.user_id(), "agentId": ac.agent_id()}
+
+
+# ---- 读：scopes / 人员 / 通知 / 待办 / 未读 ----
+
+
+def cmd_scopes(args: argparse.Namespace) -> int:
+    data = ac.api_get("agent.scopes.get", _common_params(), args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_scopes_request(args: argparse.Namespace) -> int:
+    scopes = [s.strip() for s in args.scopes.split(",") if s.strip()]
+    body = {**_common_params(), "scopes": scopes, "reason": args.reason or ""}
+    data = ac.api_post_json("agent.scopes.request", body, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_users_search(args: argparse.Namespace) -> int:
+    params = {**_common_params(), "q": args.q, "limit": args.limit}
+    data = ac.api_get("agent.users.search", params, args.timeout)
+    if args.json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return 0
+    users = (data.get("data") or {}).get("users") or []
+    print(f"total={len(users)}")
+    for u in users:
+        print(f"- _id={u.get('_id')} username={u.get('username')}")
+    return 0
+
+
+def cmd_notifications(args: argparse.Namespace) -> int:
+    params = {**_common_params(), "limit": args.limit, "since": args.since}
+    data = ac.api_get("agent.notifications.list", params, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_todos(args: argparse.Namespace) -> int:
+    params = {**_common_params(), "limit": args.limit, "status": args.status}
+    data = ac.api_get("agent.todos.list", params, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_unread(args: argparse.Namespace) -> int:
+    data = ac.api_get("agent.unread.summary", _common_params(), args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+# ---- 读：频道 ----
+
+
+def cmd_channels_search(args: argparse.Namespace) -> int:
+    params = {**_common_params(), "name": args.name, "keyword": args.keyword, "limit": args.limit}
+    data = ac.api_get("agent.channels.search", params, args.timeout)
+    if args.json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return 0
+    chans = (data.get("data") or {}).get("channels") or (data.get("data") or {}).get("items") or []
+    print(f"total={len(chans)}")
+    for c in chans:
+        print(f"- rid={c.get('rid', c.get('_id'))} name={c.get('name')}")
+    return 0
+
+
+def cmd_channel_info(args: argparse.Namespace) -> int:
+    data = ac.api_get("agent.channel.info.get", {**_common_params(), **_channel_params(args)}, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_channel_messages(args: argparse.Namespace) -> int:
+    params = {**_common_params(), **_channel_params(args), "limit": args.limit}
+    data = ac.api_get("agent.channel.messages.list", params, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_channel_messages_search(args: argparse.Namespace) -> int:
+    params = {**_common_params(), **_channel_params(args), "keyword": args.keyword, "limit": args.limit}
+    data = ac.api_get("agent.channel.messages.search", params, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_channel_members(args: argparse.Namespace) -> int:
+    data = ac.api_get("agent.channel.members.list", {**_common_params(), **_channel_params(args)}, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_channel_attachments(args: argparse.Namespace) -> int:
+    data = ac.api_get("agent.channel.attachments.list", {**_common_params(), **_channel_params(args)}, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_channel_announcements(args: argparse.Namespace) -> int:
+    data = ac.api_get("agent.channel.announcements.list", {**_common_params(), **_channel_params(args)}, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_file_metadata(args: argparse.Namespace) -> int:
+    if not args.file_id:
+        sys.exit("⚠️ file-metadata 需要 --file-id")
+    params = {**_common_params(), "fileId": args.file_id}
+    data = ac.api_get("agent.file.metadata.get", params, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+# ---- 读：会议纪要 / 总览 ----
+
+
+def cmd_meeting_minutes(args: argparse.Namespace) -> int:
+    params = {**_common_params(), "limit": args.limit}
+    data = ac.api_get("agent.meeting.minutes.list", params, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_meeting_minutes_ingest(args: argparse.Namespace) -> int:
+    params = {**_common_params(), "limit": args.limit}
+    data = ac.api_get("agent.meeting.minutes.ingest.list", params, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_overview_resolve(args: argparse.Namespace) -> int:
+    if not args.url:
+        sys.exit("⚠️ overview-resolve 需要 --url")
+    params = {**_common_params(), "url": args.url}
+    data = ac.api_get("agent.overview.resolve", params, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_overview_links(args: argparse.Namespace) -> int:
+    data = ac.api_get("agent.channel.overview.links.list", {**_common_params(), **_channel_params(args)}, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+# ---- 写：待办 / 频道 / 会议 ----
+
+
+def cmd_todos_update(args: argparse.Namespace) -> int:
+    if not args.id:
+        sys.exit("⚠️ todos-update 需要 --id")
+    body: dict[str, Any] = {**_common_params(), "id": args.id, "status": args.status}
+    if args.reminder_time:
+        body["reminderTime"] = args.reminder_time
+    data = ac.api_post_json("agent.todos.update-status", body, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+def cmd_channels_create(args: argparse.Namespace) -> int:
+    members = _load_json_arg(args.members_json, args.members_file)
+    if members is None:
+        members = []
+    body: dict[str, Any] = {**_common_params(), "name": args.name or "", "members": members}
+    if args.dep_ids:
+        body["depIds"] = [d.strip() for d in args.dep_ids.split(",") if d.strip()]
+    if args.read_only:
+        body["readOnly"] = True
+    extra = _load_json_arg(args.extra_json, args.extra_file)
+    if extra is not None:
+        body["extraData"] = extra
+    data = ac.api_post_json("agent.channels.create", body, args.timeout)
+    if args.json:
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return 0
+    d = data.get("data") or {}
+    print(f"created: rid={d.get('rid')} name={(d.get('channel') or {}).get('name', args.name or '')}")
+    return 0
+
+
+def cmd_tool_invoke(args: argparse.Namespace) -> int:
+    if not args.tool:
+        sys.exit("⚠️ tool-invoke 需要 --tool")
+    tool_args = _load_json_arg(args.args_json, args.args_file)
+    body = {**_common_params(), "tool": args.tool, "args": tool_args or {}}
+    data = ac.api_post_json("agent.tool.invoke", body, args.timeout)
+    return ac.emit(data, args.json, json.dumps(data.get("data", {}), ensure_ascii=False, indent=2))
+
+
+# ---- CLI ----
+
+
+def _channel_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--rid", help="频道 rid（覆盖 TARGET_RID）")
+    parser.add_argument("--name", "--channel-name", dest="name", help="频道名（无 rid 时用）")
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Appia Claw 扩展能力（scopes / 人员 / 通知 / 待办 / 频道 / 会议 / 总览 / 写操作）")
+    ac.add_cred_arg(p)
+    ac.add_timeout_arg(p)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def _json(sp):
+        ac.add_json_arg(sp)
+
+    sp = sub.add_parser("scopes", help="GET agent.scopes.get")
+    _json(sp)
+    sp.set_defaults(_run=cmd_scopes)
+
+    sp = sub.add_parser("scopes-request", help="POST agent.scopes.request（发 myAgent 授权卡片）")
+    sp.add_argument("--scopes", required=True, help="逗号分隔，如 channels:write")
+    sp.add_argument("--reason", help="申请原因")
+    _json(sp)
+    sp.set_defaults(_run=cmd_scopes_request)
+
+    sp = sub.add_parser("users-search", help="GET agent.users.search")
+    sp.add_argument("--q", required=True, help="姓名/username 关键词")
+    sp.add_argument("--limit", type=int, default=20)
+    _json(sp)
+    sp.set_defaults(_run=cmd_users_search)
+
+    sp = sub.add_parser("notifications", help="GET agent.notifications.list")
+    sp.add_argument("--limit", type=int, default=20)
+    sp.add_argument("--since", help="起始时间")
+    _json(sp)
+    sp.set_defaults(_run=cmd_notifications)
+
+    sp = sub.add_parser("todos", help="GET agent.todos.list")
+    sp.add_argument("--limit", type=int, default=20)
+    sp.add_argument("--status", help="状态过滤")
+    _json(sp)
+    sp.set_defaults(_run=cmd_todos)
+
+    sp = sub.add_parser("unread", help="GET agent.unread.summary")
+    _json(sp)
+    sp.set_defaults(_run=cmd_unread)
+
+    sp = sub.add_parser("channels-search", help="GET agent.channels.search")
+    sp.add_argument("--name", help="频道名")
+    sp.add_argument("--keyword", help="关键词")
+    sp.add_argument("--limit", type=int, default=20)
+    _json(sp)
+    sp.set_defaults(_run=cmd_channels_search)
+
+    sp = sub.add_parser("channel-info", help="GET agent.channel.info.get")
+    _channel_args(sp)
+    _json(sp)
+    sp.set_defaults(_run=cmd_channel_info)
+
+    sp = sub.add_parser("channel-messages", help="GET agent.channel.messages.list")
+    _channel_args(sp)
+    sp.add_argument("--limit", type=int, default=20)
+    _json(sp)
+    sp.set_defaults(_run=cmd_channel_messages)
+
+    sp = sub.add_parser("channel-messages-search", help="GET agent.channel.messages.search")
+    _channel_args(sp)
+    sp.add_argument("--keyword", required=True)
+    sp.add_argument("--limit", type=int, default=20)
+    _json(sp)
+    sp.set_defaults(_run=cmd_channel_messages_search)
+
+    sp = sub.add_parser("channel-members", help="GET agent.channel.members.list")
+    _channel_args(sp)
+    _json(sp)
+    sp.set_defaults(_run=cmd_channel_members)
+
+    sp = sub.add_parser("channel-attachments", help="GET agent.channel.attachments.list")
+    _channel_args(sp)
+    _json(sp)
+    sp.set_defaults(_run=cmd_channel_attachments)
+
+    sp = sub.add_parser("channel-announcements", help="GET agent.channel.announcements.list")
+    _channel_args(sp)
+    _json(sp)
+    sp.set_defaults(_run=cmd_channel_announcements)
+
+    sp = sub.add_parser("file-metadata", help="GET agent.file.metadata.get")
+    sp.add_argument("--file-id", required=True)
+    _json(sp)
+    sp.set_defaults(_run=cmd_file_metadata)
+
+    sp = sub.add_parser("meeting-minutes", help="GET agent.meeting.minutes.list")
+    sp.add_argument("--limit", type=int, default=20)
+    _json(sp)
+    sp.set_defaults(_run=cmd_meeting_minutes)
+
+    sp = sub.add_parser("meeting-minutes-ingest", help="GET agent.meeting.minutes.ingest.list")
+    sp.add_argument("--limit", type=int, default=20)
+    _json(sp)
+    sp.set_defaults(_run=cmd_meeting_minutes_ingest)
+
+    sp = sub.add_parser("overview-resolve", help="GET agent.overview.resolve（总览链接→元数据）")
+    sp.add_argument("--url", required=True, help="总览链接")
+    _json(sp)
+    sp.set_defaults(_run=cmd_overview_resolve)
+
+    sp = sub.add_parser("overview-links", help="GET agent.channel.overview.links.list")
+    _channel_args(sp)
+    _json(sp)
+    sp.set_defaults(_run=cmd_overview_links)
+
+    sp = sub.add_parser("todos-update", help="POST agent.todos.update-status")
+    sp.add_argument("--id", required=True, help="待办 id")
+    sp.add_argument("--status", required=True)
+    sp.add_argument("--reminder-time", dest="reminder_time")
+    _json(sp)
+    sp.set_defaults(_run=cmd_todos_update)
+
+    sp = sub.add_parser("channels-create", help="POST agent.channels.create")
+    sp.add_argument("--name", help="频道名")
+    sp.add_argument("--members-json", dest="members_json", help='username 数组 JSON，如 ["zhangsan","lisi"]')
+    sp.add_argument("--members-file", dest="members_file", help="username 数组 JSON 文件")
+    sp.add_argument("--dep-ids", dest="dep_ids", help="部门 id 逗号分隔")
+    sp.add_argument("--read-only", dest="read_only", action="store_true")
+    sp.add_argument("--extra-json", dest="extra_json", help="extraData JSON")
+    sp.add_argument("--extra-file", dest="extra_file", help="extraData JSON 文件")
+    _json(sp)
+    sp.set_defaults(_run=cmd_channels_create)
+
+    sp = sub.add_parser("tool-invoke", help="POST agent.tool.invoke（聚合调用）")
+    sp.add_argument("--tool", required=True, help="如 appia.todos.list")
+    sp.add_argument("--args-json", dest="args_json", help="args JSON")
+    sp.add_argument("--args-file", dest="args_file", help="args JSON 文件")
+    _json(sp)
+    sp.set_defaults(_run=cmd_tool_invoke)
+
+    args = p.parse_args()
+    ac.init_cred(args.cred_file)
+    runner = getattr(args, "_run", None)
+    if runner is None:
+        return 1
+    return int(runner(args))
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except Exception as exc:  # pragma: no cover - CLI
+        print(f"⚠️ {exc}", file=sys.stderr)
+        raise SystemExit(1)