rathflow-cli 0.1.0__py3-none-any.whl

rathflow_cli/__init__.py

@@ -0,0 +1,6 @@
+"""RathFlow CLI —— RathFlow 北向 REST 的命令行客户端。
+
+安装：``uv tool install rathflow-cli``（或 ``pip install rathflow-cli``）。
+"""
+
+__version__ = "0.1.0"

rathflow_cli/__main__.py

@@ -0,0 +1,6 @@
+"""支持 `python -m rathflow_cli`（与 `rathflow` 入口点等价）。"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

rathflow_cli/cli.py

@@ -0,0 +1,161 @@
+"""typer 根应用与全局选项。"""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from . import __version__, errors, state as state_mod
+from .state import State
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="RathFlow 命令行客户端（JWT 登录；命令覆盖北向 REST 全部端点）。",
+)
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        typer.echo(f"rathflow {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    profile: str = typer.Option(None, "--profile", "-p", help="配置档名（缺省 default）"),
+    base_url: str = typer.Option(None, "--base-url", help="gateway 地址（env RATHFLOW_BASE_URL）"),
+    project: str = typer.Option(None, "--project", help="项目作用域（env RATHFLOW_PROJECT）"),
+    json_out: bool = typer.Option(False, "--json", help="以 JSON 输出（脚本消费的稳定形态）"),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="只输出主键"),
+    version: bool = typer.Option(
+        False, "--version", callback=_print_version, is_eager=True, help="显示版本并退出"
+    ),
+) -> None:
+    ctx.obj = state_mod.install(
+        State(
+            profile_name=profile,
+            base_url=base_url,
+            project=project,
+            json_out=json_out,
+            quiet=quiet,
+        )
+    )
+
+
+def _register() -> None:
+    from .commands import (
+        admin,
+        agent,
+        api_cmd,
+        asset,
+        auth_cmd,
+        billing,
+        config_cmd,
+        memory,
+        org,
+        project,
+        sandbox,
+        session,
+        workflow,
+    )
+
+    app.add_typer(auth_cmd.app, name="auth")
+    app.add_typer(config_cmd.app, name="config")
+    app.add_typer(org.app, name="org")
+    app.add_typer(project.app, name="project")
+    app.add_typer(session.app, name="session")
+    app.add_typer(memory.app, name="memory")
+    app.add_typer(sandbox.app, name="sandbox")
+    app.add_typer(agent.app, name="agent")
+    app.add_typer(asset.app, name="asset")
+    app.add_typer(billing.app, name="billing")
+    app.add_typer(workflow.app, name="workflow")
+    app.add_typer(admin.app, name="admin")
+
+    from .commands.auth_cmd import whoami
+
+    app.command("whoami", help="显示登录身份、作用域与可访问项目")(whoami)
+    # 逃生舱直接挂根：`rathflow api <Key>` 不必多打一层 `call`
+    app.command("api", help="任意端点调用（`rathflow api --list` 看全部）")(api_cmd.call)
+
+
+_register()
+
+
+# 可以挪到命令行最前的全局选项：前者是布尔旗标，后者各吃一个值。
+_HOIST_FLAGS = frozenset({"--json", "--quiet"})
+_HOIST_OPTS = frozenset({"--profile", "--base-url", "--project"})
+
+
+def _value_opts() -> set[str]:
+    """全 app 里「吃下一个词」的选项名 —— 用来判断挪旗标安不安全。
+
+    走 click 命令树而非 Typer 对象：Typer 只是注册表，click Group 是懒构建的。
+    """
+
+    def walk(cmd) -> set[str]:
+        found: set[str] = set()
+        for param in getattr(cmd, "params", []):
+            if getattr(param, "is_flag", False) or getattr(param, "count", False):
+                continue
+            found.update(getattr(param, "opts", []))
+        for sub in getattr(cmd, "commands", {}).values():
+            found |= walk(sub)
+        return found
+
+    return walk(typer.main.get_command(app))
+
+
+def _hoist_globals(argv: list[str]) -> list[str]:
+    """把写在命令**后面**的全局选项挪到最前。
+
+    click 只认组级选项出现在子命令之前，故 `rathflow project list --json` 会被
+    当成给 `list` 传参而报错。脚本里这个顺序太自然了，于是这里做一次改写：
+    只挪白名单里的选项，且前一个词不是吃值的选项（否则那个词是被当值用的，
+    例如 `--body --json` 里的 `--json` 是值，不能动）。
+    """
+    if len(argv) < 2:
+        return argv
+    value_opts = _value_opts()
+    head, tail = [argv[0]], []
+    hoisted: list[str] = []
+    idx = 1
+    while idx < len(argv):
+        tok = argv[idx]
+        prev = argv[idx - 1]
+        # 前一个词若是吃值的选项，本词就是它的值（click 也这么看），别动
+        safe = prev not in value_opts
+        if safe and tok in _HOIST_FLAGS:
+            hoisted.append(tok)
+            idx += 1
+            continue
+        if safe and tok in _HOIST_OPTS and idx + 1 < len(argv) and not argv[idx + 1].startswith("-"):
+            hoisted.extend([tok, argv[idx + 1]])
+            idx += 2
+            continue
+        tail.append(tok)
+        idx += 1
+    return head + hoisted + tail
+
+
+def main() -> None:
+    sys.argv = _hoist_globals(sys.argv)
+    try:
+        app()
+    except errors.UsageError as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        sys.exit(errors.EXIT_USAGE)
+    except errors.ApiError as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        for detail in exc.details:
+            print(f"  - {detail}", file=sys.stderr)
+        sys.exit(exc.exit_code)
+    except KeyboardInterrupt:  # pragma: no cover
+        sys.exit(130)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

rathflow_cli/commands/_common.py

@@ -0,0 +1,78 @@
+"""命令间共用的小工具（参数解析与请求体装配）。"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+
+from ..errors import UsageError
+
+PATH_OPT = typer.Option(None, "--path", help="路径参数 k=v，可重复（如 --path session_id=abc）")
+QUERY_OPT = typer.Option(None, "--query", help="查询参数 k=v，可重复")
+BODY_OPT = typer.Option(None, "--body", help="请求体 JSON 字面量")
+BODY_FILE_OPT = typer.Option(None, "--body-file", help="从文件读请求体 JSON（- 读 stdin）")
+PAGE_SIZE_OPT = typer.Option(None, "--page-size", help="分页大小")
+PAGE_TOKEN_OPT = typer.Option(None, "--page-token", help="分页游标")
+
+
+def pairs(items: list[str] | None) -> dict:
+    """['k=v', ...] → {k: v}；值里的 = 保留（只切第一个）。"""
+    out: dict[str, str] = {}
+    for item in items or []:
+        if "=" not in item:
+            raise UsageError(f"参数需形如 k=v，收到 {item!r}")
+        key, _, value = item.partition("=")
+        out[key.strip()] = value
+    return out
+
+
+def body_of(body: str | None, body_file: str | None) -> dict | None:
+    """装配请求体：字面量或文件（`-` = stdin）。两者互斥。"""
+    if body and body_file:
+        raise UsageError("--body 与 --body-file 不能同时用")
+    raw: str | None = None
+    if body_file:
+        raw = sys.stdin.read() if body_file == "-" else _read(body_file)
+    elif body:
+        raw = body
+    else:
+        return None
+    raw = raw.strip()
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise UsageError(f"请求体不是合法 JSON：{exc}") from None
+    if not isinstance(parsed, dict):
+        raise UsageError("请求体必须是 JSON 对象")
+    return parsed
+
+
+def _read(path: str) -> str:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return fh.read()
+    except OSError as exc:
+        raise UsageError(f"读取请求体文件失败：{exc}") from None
+
+
+def pagination(page_size: int | None, page_token: str | None, extra: dict | None = None) -> dict:
+    """装配分页查询串（protojson 查询名用 proto 字段名 snake_case）。"""
+    query = dict(extra or {})
+    if page_size is not None:
+        query["page_size"] = page_size
+    if page_token:
+        query["page_token"] = page_token
+    return query
+
+
+def id_of(payload: dict, *keys: str) -> str:
+    """从响应里挑主键用于 -q 输出。"""
+    for key in keys:
+        value = (payload or {}).get(key)
+        if value:
+            return str(value)
+    return ""

rathflow_cli/commands/admin.py

@@ -0,0 +1,83 @@
+"""admin：平台管理（用户、上下文令牌签名密钥）。"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import output
+from ..commands._common import PAGE_SIZE_OPT, PAGE_TOKEN_OPT, pagination
+from ..state import current
+
+app = typer.Typer(no_args_is_help=True, help="平台管理（需平台管理员）")
+
+
+@app.command("users")
+def users(
+    page_size: int = PAGE_SIZE_OPT,
+    page_token: str = PAGE_TOKEN_OPT,
+) -> None:
+    """列平台用户。"""
+    st = current()
+    payload = st.client().call("admin.ListUsers", query=pagination(page_size or 50, page_token))
+    output.emit_items(
+        payload,
+        items_key="users",
+        columns=[
+            ("USER ID", "userId"),
+            ("邮箱", "email"),
+            ("名称", "displayName"),
+            ("状态", "status"),
+            ("管理员", "isPlatformAdmin"),
+            ("注册时间", "createdAt"),
+        ],
+        json_out=st.json_out,
+    )
+
+
+@app.command("promote")
+def promote(
+    user_id: str = typer.Argument(...),
+    admin: bool = typer.Option(True, "--admin/--demote", help="授予或收回平台管理员"),
+) -> None:
+    """授予/收回平台管理员。"""
+    st = current()
+    body = {"isPlatformAdmin": admin}
+    payload = st.client().call(
+        "admin.PromoteUser", path_params={"user_id": user_id}, body=body
+    )
+    if st.json_out:
+        output.emit_json(payload)
+        return
+    typer.echo(f"{user_id} → {'平台管理员' if admin else '普通用户'}")
+
+
+@app.command("set-status")
+def set_status(
+    user_id: str = typer.Argument(...),
+    status: str = typer.Option(..., "--status", help="active | disabled"),
+) -> None:
+    """启用/停用账号。"""
+    st = current()
+    body = {"status": f"USER_STATUS_{status.upper()}"}
+    payload = st.client().call(
+        "admin.SetUserStatus", path_params={"user_id": user_id}, body=body
+    )
+    if st.json_out:
+        output.emit_json(payload)
+        return
+    typer.echo(f"{user_id} → {status}")
+
+
+@app.command("rotate-context-key")
+def rotate_context_key(
+    reason: str = typer.Option(None, "--reason", help="轮换原因（记入审计）"),
+) -> None:
+    """轮换上下文令牌签名密钥（reason 走 query，该接口无 body）。"""
+    st = current()
+    payload = st.client().call(
+        "admin.RotateContextTokenKey", query={"reason": reason} if reason else None
+    )
+    if st.json_out:
+        output.emit_json(payload)
+        return
+    typer.echo(f"新密钥 {payload.get('keyId')} 生效于 {payload.get('effectiveAt')}")

rathflow_cli/commands/agent.py

@@ -0,0 +1,288 @@
+"""agent：Agent 定义、版本、运行与 Agent 目录。"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import output
+from ..commands._common import (
+    BODY_FILE_OPT,
+    BODY_OPT,
+    PAGE_SIZE_OPT,
+    PAGE_TOKEN_OPT,
+    body_of,
+    pagination,
+)
+from ..errors import UsageError
+from ..state import current
+
+app = typer.Typer(no_args_is_help=True, help="Agent 定义 / 版本 / 运行 / 目录")
+
+DEF_COLUMNS = [
+    ("AGENT DEF ID", "agentDefId"),
+    ("名称", "name"),
+    ("版本", "version"),
+    ("状态", "status"),
+    ("更新时间", "updatedAt"),
+]
+RUN_COLUMNS = [
+    ("RUN ID", "runId"),
+    ("状态", "status"),
+    ("提示词", "promptText"),
+    ("创建时间", "createdAt"),
+]
+
+
+# ------------------------------------------------------------------ 定义
+
+@app.command("defs")
+def defs(
+    page_size: int = PAGE_SIZE_OPT,
+    page_token: str = PAGE_TOKEN_OPT,
+) -> None:
+    """列 Agent 定义。"""
+    st = current()
+    payload = st.client().call("agent.ListAgentDefs", query=pagination(page_size or 50, page_token))
+    output.emit_items(payload, items_key="agentDefs", columns=DEF_COLUMNS, json_out=st.json_out)
+
+
+@app.command("def")
+def def_get(agent_def_id: str = typer.Argument(...)) -> None:
+    """看定义详情。"""
+    st = current()
+    payload = st.client().call("agent.GetAgentDef", path_params={"agent_def_id": agent_def_id})
+    output.emit_object(payload, json_out=st.json_out)
+
+
+@app.command("def-create")
+def def_create(
+    name: str = typer.Option(..., "--name", "-n"),
+    description: str = typer.Option(None, "--description", "-d"),
+    config: str = typer.Option(None, "--config", help="config_json 字面量（自由 JSON 文本）"),
+    config_file: str = typer.Option(None, "--config-file", help="从文件读 config_json（- 读 stdin）"),
+    memory_binding: str = typer.Option(None, "--memory-binding", help="记忆绑定，如 memories/agents"),
+    body: str = BODY_OPT,
+    body_file: str = BODY_FILE_OPT,
+) -> None:
+    """建 Agent 定义。"""
+    st = current()
+    payload_body = body_of(body, body_file) or {}
+    payload_body.setdefault("name", name)
+    if description:
+        payload_body.setdefault("description", description)
+    if memory_binding:
+        payload_body.setdefault("memoryBinding", memory_binding)
+    text = _text_of(config, config_file)
+    if text is not None:
+        payload_body.setdefault("configJson", text)
+    payload = st.client().call("agent.CreateAgentDef", body=payload_body)
+    if st.json_out:
+        output.emit_json(payload)
+        return
+    typer.echo(payload.get("agentDefId") or "")
+
+
+@app.command("def-update")
+def def_update(
+    agent_def_id: str = typer.Argument(...),
+    name: str = typer.Option(None, "--name", "-n"),
+    description: str = typer.Option(None, "--description", "-d"),
+    config: str = typer.Option(None, "--config"),
+    config_file: str = typer.Option(None, "--config-file"),
+    memory_binding: str = typer.Option(None, "--memory-binding"),
+    status: str = typer.Option(None, "--status", help="AgentDefStatus 枚举"),
+    body: str = BODY_OPT,
+    body_file: str = BODY_FILE_OPT,
+) -> None:
+    """改定义（PATCH 语义；改完通常产生新版本）。"""
+    st = current()
+    payload_body = body_of(body, body_file) or {}
+    for key, value in (
+        ("name", name),
+        ("description", description),
+        ("memoryBinding", memory_binding),
+        ("status", status),
+    ):
+        if value:
+            payload_body.setdefault(key, value)
+    text = _text_of(config, config_file)
+    if text is not None:
+        payload_body.setdefault("configJson", text)
+    if not payload_body:
+        raise UsageError("至少给一项要改的字段（--name/--description/--config/--memory-binding/--status）")
+    payload = st.client().call(
+        "agent.UpdateAgentDef", path_params={"agent_def_id": agent_def_id}, body=payload_body
+    )
+    output.emit_object(payload, json_out=st.json_out)
+
+
+@app.command("def-delete")
+def def_delete(
+    agent_def_id: str = typer.Argument(...),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+) -> None:
+    """删定义。"""
+    st = current()
+    if not yes:
+        typer.confirm(f"确认删除 Agent 定义 {agent_def_id}？", abort=True)
+    st.client().call("agent.DeleteAgentDef", path_params={"agent_def_id": agent_def_id})
+    typer.echo(f"已删除 {agent_def_id}")
+
+
+@app.command("versions")
+def versions(
+    agent_def_id: str = typer.Argument(...),
+    page_size: int = PAGE_SIZE_OPT,
+    page_token: str = PAGE_TOKEN_OPT,
+) -> None:
+    """列定义的版本。"""
+    st = current()
+    payload = st.client().call(
+        "agent.ListAgentDefVersions",
+        path_params={"agent_def_id": agent_def_id},
+        query=pagination(page_size or 50, page_token),
+    )
+    output.emit_items(
+        payload,
+        items_key="versions",
+        columns=[("版本", "version"), ("创建人", "createdBy"), ("创建时间", "createdAt")],
+        json_out=st.json_out,
+    )
+
+
+@app.command("version")
+def version(
+    agent_def_id: str = typer.Argument(...),
+    version: int = typer.Argument(...),
+) -> None:
+    """看某个版本。"""
+    st = current()
+    payload = st.client().call(
+        "agent.GetAgentDefVersion",
+        path_params={"agent_def_id": agent_def_id, "version": version},
+    )
+    output.emit_object(payload, json_out=st.json_out)
+
+
+# ------------------------------------------------------------------ 运行
+
+@app.command("prompt")
+def prompt(
+    session_id: str = typer.Argument(...),
+    text: str = typer.Argument(None, help="提示词；缺省或 - 读 stdin"),
+    body: str = BODY_OPT,
+    body_file: str = BODY_FILE_OPT,
+) -> None:
+    """给会话发提示词，起一个 run（返回 runId；进度用 `session watch` 跟）。"""
+    st = current()
+    payload_body = body_of(body, body_file)
+    if payload_body is None:
+        if text in (None, "-"):
+            import sys
+
+            text = sys.stdin.read()
+        payload_body = {"text": text}
+    payload = st.client().call(
+        "agent.Prompt", path_params={"session_id": session_id}, body=payload_body
+    )
+    if st.json_out:
+        output.emit_json(payload)
+        return
+    typer.echo(payload.get("runId") or "")
+
+
+@app.command("runs")
+def runs(
+    session_id: str = typer.Argument(...),
+    page_size: int = PAGE_SIZE_OPT,
+    page_token: str = PAGE_TOKEN_OPT,
+) -> None:
+    """列会话下的 run。"""
+    st = current()
+    payload = st.client().call(
+        "agent.ListRuns",
+        path_params={"session_id": session_id},
+        query=pagination(page_size or 50, page_token),
+    )
+    output.emit_items(payload, items_key="runs", columns=RUN_COLUMNS, json_out=st.json_out)
+
+
+@app.command("run")
+def run(run_id: str = typer.Argument(...)) -> None:
+    """看单个 run。"""
+    st = current()
+    payload = st.client().call("agent.GetRun", path_params={"run_id": run_id})
+    output.emit_object(payload, json_out=st.json_out)
+
+
+# ------------------------------------------------------------------ 目录
+
+@app.command("directory")
+def directory(
+    page_size: int = PAGE_SIZE_OPT,
+    page_token: str = PAGE_TOKEN_OPT,
+) -> None:
+    """列 Agent 目录（跨 project 可见的 agent 地址）。"""
+    st = current()
+    payload = st.client().call(
+        "agent.ListAgentDirectory", query=pagination(page_size or 50, page_token)
+    )
+    output.emit_items(
+        payload,
+        items_key="entries",
+        columns=[("AGENT ID", "agentId"), ("地址", "address"), ("状态", "status")],
+        json_out=st.json_out,
+    )
+
+
+@app.command("resolve")
+def resolve(agent_id: str = typer.Argument(...)) -> None:
+    """把 agent id 解析成地址。"""
+    st = current()
+    payload = st.client().call(
+        "agent.ResolveAgentAddress", path_params={"agent_id": agent_id}
+    )
+    output.emit_object(payload, json_out=st.json_out)
+
+
+@app.command("messages")
+def messages(
+    agent_id: str = typer.Argument(...),
+    page_size: int = PAGE_SIZE_OPT,
+    page_token: str = PAGE_TOKEN_OPT,
+) -> None:
+    """看某个 agent 的消息记录。"""
+    st = current()
+    payload = st.client().call(
+        "agent.ListAgentMessages",
+        path_params={"agent_id": agent_id},
+        query=pagination(page_size or 50, page_token),
+    )
+    output.emit_items(
+        payload,
+        items_key="messages",  # 见 ListAgentMessagesResponse
+        columns=[
+            ("MESSAGE ID", "messageId"),
+            ("方向", "direction"),
+            ("对端", "peerAgentId"),
+            ("负载", "payloadJson"),
+        ],
+        json_out=st.json_out,
+    )
+
+
+def _text_of(text: str | None, file: str | None) -> str | None:
+    """config_json 是自由 JSON 文本：字面量或文件（- 读 stdin）。"""
+    if text and file:
+        raise UsageError("--config 与 --config-file 不能同时用")
+    if file:
+        if file == "-":
+            import sys
+
+            return sys.stdin.read()
+        try:
+            with open(file, encoding="utf-8") as fh:
+                return fh.read()
+        except OSError as exc:
+            raise UsageError(f"读取失败：{exc}") from None
+    return text