sophhub 0.4.63 → 0.4.64

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)

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