rathflow-cli 0.1.0__py3-none-any.whl

rathflow_cli/commands/session.py

@@ -0,0 +1,237 @@
+"""session：会话、block、事件流与 block 分享。"""
+
+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="会话 / block / 事件流")
+
+SESSION_COLUMNS = [
+    ("SESSION ID", "sessionId"),
+    ("状态", "status"),
+    ("标题", "title"),
+    ("AGENT", "agentDefId"),
+    ("创建时间", "createdAt"),
+]
+BLOCK_COLUMNS = [
+    ("BLOCK ID", "blockId"),
+    ("标题", "title"),
+    ("事件区间", "fromSeq"),
+    ("到", "toSeq"),
+    ("创建时间", "createdAt"),
+]
+
+
+# ------------------------------------------------------------------ 会话
+
+@app.command("list")
+def list_(
+    page_size: int = PAGE_SIZE_OPT,
+    page_token: str = PAGE_TOKEN_OPT,
+    status: str = typer.Option(None, "--status", help="按状态过滤"),
+) -> None:
+    """列出本项目会话。"""
+    st = current()
+    payload = st.client().call(
+        "session.ListSessions", query=pagination(page_size or 50, page_token, {"status": status})
+    )
+    output.emit_items(payload, items_key="sessions", columns=SESSION_COLUMNS, json_out=st.json_out)
+
+
+@app.command("get")
+def get(session_id: str = typer.Argument(...)) -> None:
+    """会话详情。"""
+    st = current()
+    payload = st.client().call("session.GetSession", path_params={"session_id": session_id})
+    output.emit_object(payload, json_out=st.json_out)
+
+
+@app.command("create")
+def create(
+    body: str = BODY_OPT,
+    body_file: str = BODY_FILE_OPT,
+    title: str = typer.Option(None, "--title", help="标题（等价于 --body 里给 title）"),
+) -> None:
+    """建会话。"""
+    st = current()
+    payload_body = body_of(body, body_file)
+    if payload_body is None:
+        payload_body = {"title": title} if title else {}
+    payload = st.client().call("session.CreateSession", body=payload_body)
+    if st.json_out:
+        output.emit_json(payload)
+        return
+    typer.echo(payload.get("sessionId") or "")
+
+
+@app.command("delete")
+def delete(
+    session_id: str = typer.Argument(...),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+) -> None:
+    """删会话。"""
+    st = current()
+    if not yes:
+        typer.confirm(f"确认删除会话 {session_id}？", abort=True)
+    st.client().call("session.DeleteSession", path_params={"session_id": session_id})
+    typer.echo(f"已删除 {session_id}")
+
+
+@app.command("archive")
+def archive(session_id: str = typer.Argument(...)) -> None:
+    """归档会话。"""
+    st = current()
+    payload = st.client().call("session.ArchiveSession", path_params={"session_id": session_id})
+    output.emit_object(payload, json_out=st.json_out)
+
+
+@app.command("lineage")
+def lineage(session_id: str = typer.Argument(...)) -> None:
+    """血统（fork/派生关系）。"""
+    st = current()
+    payload = st.client().call("session.GetSessionLineage", path_params={"session_id": session_id})
+    output.emit_object(payload, json_out=st.json_out)
+
+
+@app.command("interrupt")
+def interrupt(session_id: str = typer.Argument(...)) -> None:
+    """打断正在跑的 run（agent.Interrupt）。"""
+    st = current()
+    payload = st.client().call("agent.Interrupt", path_params={"session_id": session_id}, body={})
+    output.emit_object(payload, json_out=st.json_out)
+
+
+# ------------------------------------------------------------------ block
+
+@app.command("blocks")
+def blocks(
+    session_id: str = typer.Argument(...),
+    page_size: int = PAGE_SIZE_OPT,
+    page_token: str = PAGE_TOKEN_OPT,
+) -> None:
+    """列会话下的 block。"""
+    st = current()
+    payload = st.client().call(
+        "session.ListBlocks",
+        path_params={"session_id": session_id},
+        query=pagination(page_size or 50, page_token),
+    )
+    output.emit_items(payload, items_key="blocks", columns=BLOCK_COLUMNS, json_out=st.json_out)
+
+
+@app.command("block")
+def block_get(block_id: str = typer.Argument(...)) -> None:
+    """看单个 block。"""
+    st = current()
+    payload = st.client().call("session.GetBlock", path_params={"block_id": block_id})
+    output.emit_object(payload, json_out=st.json_out)
+
+
+@app.command("block-create")
+def block_create(
+    session_id: str = typer.Argument(...),
+    body: str = BODY_OPT,
+    body_file: str = BODY_FILE_OPT,
+) -> None:
+    """给会话加 block（内容用 --body/--body-file 传）。"""
+    st = current()
+    payload_body = body_of(body, body_file)
+    if payload_body is None:
+        raise UsageError('需要 --body \'{"type":...,...}\' 或 --body-file <路径|->')
+    payload = st.client().call(
+        "session.CreateBlock", path_params={"session_id": session_id}, body=payload_body
+    )
+    if st.json_out:
+        output.emit_json(payload)
+        return
+    typer.echo(payload.get("blockId") or "")
+
+
+@app.command("block-delete")
+def block_delete(
+    block_id: str = typer.Argument(...),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+) -> None:
+    """删 block。"""
+    st = current()
+    if not yes:
+        typer.confirm(f"确认删除 block {block_id}？", abort=True)
+    st.client().call("session.DeleteBlock", path_params={"block_id": block_id})
+    typer.echo(f"已删除 {block_id}")
+
+
+@app.command("share")
+def share(
+    block_id: str = typer.Argument(...),
+    body: str = BODY_OPT,
+    body_file: str = BODY_FILE_OPT,
+) -> None:
+    """把 block 分享给别人（scope 用 --body 传）。"""
+    st = current()
+    payload = st.client().call(
+        "session.ShareBlock", path_params={"block_id": block_id}, body=body_of(body, body_file) or {}
+    )
+    output.emit_object(payload, json_out=st.json_out)
+
+
+@app.command("unshare")
+def unshare(share_id: str = typer.Argument(...)) -> None:
+    """撤销 block 分享。"""
+    st = current()
+    st.client().call("session.RevokeBlockShare", path_params={"share_id": share_id})
+    typer.echo(f"已撤销 {share_id}")
+
+
+# ------------------------------------------------------------------ 事件
+
+@app.command("events")
+def events(
+    session_id: str = typer.Argument(...),
+    page_size: int = PAGE_SIZE_OPT,
+    page_token: str = PAGE_TOKEN_OPT,
+) -> None:
+    """拉历史事件（一次性）。"""
+    st = current()
+    payload = st.client().call(
+        "session.GetSessionEvents",
+        path_params={"session_id": session_id},
+        query=pagination(page_size or 100, page_token),
+    )
+    output.emit_items(
+        payload,
+        items_key="events",
+        columns=[("SEQ", "seq"), ("数据", "payloadJson"), ("时间", "createdAt")],
+        json_out=st.json_out,
+    )
+
+
+@app.command("watch")
+def watch(
+    session_id: str = typer.Argument(...),
+    raw: bool = typer.Option(False, "--raw", help="逐帧原样打印 JSON，不渲染"),
+    from_seq: int = typer.Option(None, "--from-seq", help="从该 seq 续传（断线重连用）"),
+) -> None:
+    """跟事件流（:stream，长连，Ctrl-C 退出）。"""
+    st = current()
+    query = {"from_seq": from_seq} if from_seq is not None else None
+    for frame in st.client().stream(
+        "session.StreamSessionEvents", path_params={"session_id": session_id}, query=query
+    ):
+        if st.json_out or raw:
+            output.emit_json(frame)
+            continue
+        seq = frame.get("seq")
+        prefix = f"{str(seq).rjust(6)}  " if seq is not None else ""
+        typer.echo(prefix + output._cell(frame.get("payloadJson") or frame))

rathflow_cli/commands/workflow.py

@@ -0,0 +1,81 @@
+"""workflow：工作流定义与删除。"""
+
+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 ..state import current
+
+app = typer.Typer(no_args_is_help=True, help="工作流")
+
+COLUMNS = [
+    ("WORKFLOW ID", "workflowId"),
+    ("标题", "title"),
+    ("状态", "status"),
+    ("更新时间", "updatedAt"),
+]
+
+
+@app.command("list")
+def list_(
+    page_size: int = PAGE_SIZE_OPT,
+    page_token: str = PAGE_TOKEN_OPT,
+) -> None:
+    """列工作流。"""
+    st = current()
+    payload = st.client().call("workflow.ListWorkflows", query=pagination(page_size or 50, page_token))
+    output.emit_items(payload, items_key="workflows", columns=COLUMNS, json_out=st.json_out)
+
+
+@app.command("get")
+def get(workflow_id: str = typer.Argument(...)) -> None:
+    """工作流详情。"""
+    st = current()
+    payload = st.client().call("workflow.GetWorkflow", path_params={"workflow_id": workflow_id})
+    output.emit_object(payload, json_out=st.json_out)
+
+
+@app.command("create")
+def create(
+    title: str = typer.Option(None, "--title", "-t"),
+    body: str = BODY_OPT,
+    body_file: str = BODY_FILE_OPT,
+) -> None:
+    """建工作流（图定义用 --body 传）。"""
+    st = current()
+    payload_body = body_of(body, body_file) or {}
+    if title:
+        payload_body.setdefault("title", title)
+    payload = st.client().call("workflow.CreateWorkflow", body=payload_body)
+    if st.json_out:
+        output.emit_json(payload)
+        return
+    typer.echo(payload.get("workflowId") or "")
+
+
+@app.command("delete")
+def delete(
+    workflow_id: str = typer.Argument(...),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+) -> None:
+    """删工作流（连同其会话与沙箱；响应会报删了多少）。"""
+    st = current()
+    if not yes:
+        typer.confirm(f"确认删除工作流 {workflow_id}？其下会话与沙箱一并清理", abort=True)
+    payload = st.client().call("workflow.DeleteWorkflow", path_params={"workflow_id": workflow_id})
+    if st.json_out:
+        output.emit_json(payload)
+        return
+    typer.echo(
+        f"已删除；清理会话 {payload.get('sessionsDeleted', 0)} 个、"
+        f"沙箱 {payload.get('sandboxesTerminated', 0)} 个"
+    )

rathflow_cli/config.py

@@ -0,0 +1,69 @@
+"""本地配置：~/.config/rathflow/config.json（多 profile）。
+
+选 JSON 而非 TOML：tomllib 只读，写 TOML 需额外依赖（违反 P4）。
+
+优先级（由调用方在 cli.py 统一合并）：flag > 环境变量 > profile > 内建默认。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+# 面向公开发布的内建默认：托管网关。本地开发用 --base-url 或 RATHFLOW_BASE_URL
+# 指回 http://127.0.0.1:8080。
+DEFAULT_BASE_URL = "https://rathflow.lynwe.com"
+
+# 环境变量名与 Get Started 页 curl 片段逐字同名，页面片段可直接喂 CLI。
+ENV_BASE_URL = "RATHFLOW_BASE_URL"
+ENV_PROJECT = "RATHFLOW_PROJECT"
+ENV_TOKEN = "RATHFLOW_TOKEN"
+ENV_CONFIG_DIR = "RATHFLOW_CONFIG_DIR"
+
+
+def config_dir() -> Path:
+    return Path(os.environ.get(ENV_CONFIG_DIR) or (Path.home() / ".config" / "rathflow"))
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+def load() -> dict:
+    p = config_path()
+    if not p.exists():
+        return {"current": "default", "profiles": {}}
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise SystemExit(f"配置文件损坏：{p}（{exc}）")
+    data.setdefault("current", "default")
+    data.setdefault("profiles", {})
+    return data
+
+
+def save(data: dict) -> Path:
+    """落盘并收紧权限到 0600（内含令牌，等同口令）。"""
+    p = config_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    tmp = p.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    tmp.replace(p)
+    try:
+        p.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass  # 非 POSIX 文件系统：尽力而为
+    return p
+
+
+def profile(data: dict, name: str | None = None) -> dict:
+    return data["profiles"].setdefault(name or data["current"], {})
+
+
+def mask(secret: str | None) -> str:
+    """令牌/密钥打码显示：保留前 8 位。"""
+    if not secret:
+        return "(未设置)"
+    return secret[:8] + "…" if len(secret) > 8 else "…"

rathflow_cli/endpoints.py

@@ -0,0 +1,207 @@
+"""REST 端点表 —— 全 CLI 的路径唯一事实源（**禁止在命令实现里写 URL 字面量**）。
+
+内容与 web/lib/api/generated/endpoints.ts 同源（proto → grpc-gateway 生成）。
+契约变了改本文件；后续可改为从 proto 生成（设计文档 §3.5）。
+
+值 = (HTTP 方法, 路径模板)。模板里的 `{name}` 是 proto 字段名（snake_case）。
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import quote
+
+from .errors import UsageError
+
+# key → (method, path)
+ENDPOINTS: dict[str, tuple[str, str]] = {
+    # ---- auth ----
+    "auth.IssueAPIKey": ("POST", "/api/v1/api-keys"),
+    "auth.ListAPIKeys": ("GET", "/api/v1/api-keys"),
+    "auth.Login": ("POST", "/api/v1/auth/login"),
+    "auth.Logout": ("POST", "/api/v1/auth/logout"),
+    "auth.Refresh": ("POST", "/api/v1/auth/refresh"),
+    "auth.Register": ("POST", "/api/v1/auth/register"),
+    "auth.RevokeAPIKey": ("DELETE", "/api/v1/api-keys/{key_id}"),
+    # ---- tenant：分享链接（能力凭证，明文只在创建/轮换时出现一次）----
+    "tenant.JoinSharedProject": ("POST", "/api/v1/shared-projects"),
+    "tenant.ListSharedProjects": ("GET", "/api/v1/shared-projects"),
+    "tenant.RevokeProjectShare": ("DELETE", "/api/v1/projects/{project_id}/share"),
+    "tenant.UpdateProjectShare": ("PATCH", "/api/v1/projects/{project_id}/share"),
+    # ---- tenant：org 成员身份 ----
+    "tenant.AcceptOrgInvitation": ("POST", "/api/v1/orgs/join"),
+    "tenant.CreateOrgInvitation": ("POST", "/api/v1/orgs/{org_id}/invitations"),
+    "tenant.ListMyOrgs": ("GET", "/api/v1/orgs"),
+    # ---- tenant：project ----
+    "tenant.CreateProject": ("POST", "/api/v1/projects"),
+    "tenant.DeleteProject": ("DELETE", "/api/v1/projects/{project_id}"),
+    "tenant.GetProject": ("GET", "/api/v1/projects/{project_id}"),
+    "tenant.GetProjectConfig": ("GET", "/api/v1/projects/{project_id}/config"),
+    "tenant.ListProjects": ("GET", "/api/v1/projects"),
+    "tenant.UpdateProject": ("PATCH", "/api/v1/projects/{project_id}"),
+    "tenant.UpdateProjectConfig": ("PATCH", "/api/v1/projects/{project_id}/config"),
+    # ---- session ----
+    "session.ArchiveSession": ("POST", "/api/v1/sessions/{session_id}:archive"),
+    "session.CreateBlock": ("POST", "/api/v1/sessions/{session_id}/blocks"),
+    "session.CreateSession": ("POST", "/api/v1/sessions"),
+    "session.DeleteBlock": ("DELETE", "/api/v1/blocks/{block_id}"),
+    "session.DeleteSession": ("DELETE", "/api/v1/sessions/{session_id}"),
+    "session.GetBlock": ("GET", "/api/v1/blocks/{block_id}"),
+    "session.GetSession": ("GET", "/api/v1/sessions/{session_id}"),
+    "session.GetSessionEvents": ("GET", "/api/v1/sessions/{session_id}/events"),
+    "session.GetSessionLineage": ("GET", "/api/v1/sessions/{session_id}/lineage"),
+    "session.ListBlocks": ("GET", "/api/v1/sessions/{session_id}/blocks"),
+    "session.ListSessions": ("GET", "/api/v1/sessions"),
+    "session.RevokeBlockShare": ("DELETE", "/api/v1/block-shares/{share_id}"),
+    "session.ShareBlock": ("POST", "/api/v1/blocks/{block_id}/shares"),
+    "session.StreamSessionEvents": ("GET", "/api/v1/sessions/{session_id}/events:stream"),
+    # ---- workflow ----
+    "workflow.CreateWorkflow": ("POST", "/api/v1/workflows"),
+    "workflow.DeleteWorkflow": ("DELETE", "/api/v1/workflows/{workflow_id}"),
+    "workflow.GetWorkflow": ("GET", "/api/v1/workflows/{workflow_id}"),
+    "workflow.ListWorkflows": ("GET", "/api/v1/workflows"),
+    "workflow.UpdateWorkflow": ("PATCH", "/api/v1/workflows/{workflow_id}"),
+    # ---- agent ----
+    "agent.CreateAgentDef": ("POST", "/api/v1/agents"),
+    "agent.DeleteAgentDef": ("DELETE", "/api/v1/agents/{agent_def_id}"),
+    "agent.GetAgentDef": ("GET", "/api/v1/agents/{agent_def_id}"),
+    "agent.GetAgentDefVersion": ("GET", "/api/v1/agents/{agent_def_id}/versions/{version}"),
+    "agent.GetRun": ("GET", "/api/v1/runs/{run_id}"),
+    "agent.Interrupt": ("POST", "/api/v1/sessions/{session_id}:interrupt"),
+    "agent.ListAgentDefs": ("GET", "/api/v1/agents"),
+    "agent.ListAgentDefVersions": ("GET", "/api/v1/agents/{agent_def_id}/versions"),
+    "agent.ListAgentDirectory": ("GET", "/api/v1/agent-directory"),
+    "agent.ListAgentMessages": ("GET", "/api/v1/agent-directory/{agent_id}/messages"),
+    "agent.ListRuns": ("GET", "/api/v1/sessions/{session_id}/runs"),
+    "agent.Prompt": ("POST", "/api/v1/sessions/{session_id}:prompt"),
+    "agent.ResolveAgentAddress": ("GET", "/api/v1/agent-directory/{agent_id}"),
+    "agent.UpdateAgentDef": ("PATCH", "/api/v1/agents/{agent_def_id}"),
+    # ---- memory ----
+    "memory.CommitSession": ("POST", "/api/v1/memories:commit"),
+    "memory.Delete": ("DELETE", "/api/v1/memories/{memory_path}"),
+    "memory.GetTask": ("GET", "/api/v1/memory-tasks/{task_id}"),
+    "memory.List": ("GET", "/api/v1/memories"),
+    "memory.ListTasks": ("GET", "/api/v1/memory-tasks"),
+    "memory.Read": ("GET", "/api/v1/memories/{memory_path}"),
+    "memory.Search": ("POST", "/api/v1/memories:search"),
+    "memory.Tree": ("POST", "/api/v1/memories:tree"),
+    "memory.WatchTask": ("GET", "/api/v1/memory-tasks/{task_id}:watch"),
+    "memory.Write": ("PUT", "/api/v1/memories/{memory_path}"),
+    # ---- sandbox ----
+    "sandbox.Create": ("POST", "/api/v1/sandboxes"),
+    "sandbox.ExposePort": ("POST", "/api/v1/sandboxes/{sandbox_id}/ports"),
+    "sandbox.Get": ("GET", "/api/v1/sandboxes/{sandbox_id}"),
+    "sandbox.List": ("GET", "/api/v1/sandboxes"),
+    "sandbox.ListDir": ("GET", "/api/v1/sandboxes/{sandbox_id}/directory"),
+    "sandbox.ReadFile": ("GET", "/api/v1/sandboxes/{sandbox_id}/files/{path}"),
+    "sandbox.Renew": ("POST", "/api/v1/sandboxes/{sandbox_id}:renew"),
+    "sandbox.RunCode": ("POST", "/api/v1/sandboxes/{sandbox_id}/code"),
+    "sandbox.RunCommand": ("POST", "/api/v1/sandboxes/{sandbox_id}/exec"),
+    "sandbox.Stat": ("GET", "/api/v1/sandboxes/{sandbox_id}/stat"),
+    "sandbox.StreamLogs": ("GET", "/api/v1/sandboxes/{sandbox_id}/logs"),
+    "sandbox.Terminate": ("DELETE", "/api/v1/sandboxes/{sandbox_id}"),
+    # ---- assets ----
+    "assets.CreateAsset": ("POST", "/admin/api/v1/assets"),
+    "assets.CreateAssetVersion": ("POST", "/admin/api/v1/assets/{asset_id}/versions"),
+    "assets.GetAssemblyArtifact": (
+        "GET",
+        "/admin/api/v1/assembly-artifacts/{project_id}/revisions/{revision}",
+    ),
+    "assets.GetAssemblyStatus": ("GET", "/api/v1/assembly-status"),
+    "assets.GetAsset": ("GET", "/api/v1/assets/{asset_id}"),
+    "assets.ListAssemblyRevisions": ("GET", "/admin/api/v1/assembly-revisions"),
+    "assets.ListAssets": ("GET", "/api/v1/assets"),
+    "assets.ListEnabledAssets": ("GET", "/api/v1/assets:enabled"),
+    "assets.PinAssetVersion": ("POST", "/api/v1/assets/{asset_id}:pin-version"),
+    "assets.PublishVersion": (
+        "POST",
+        "/admin/api/v1/assets/{asset_id}/versions/{version_id}:publish",
+    ),
+    "assets.PutAssetContent": (
+        "PUT",
+        "/admin/api/v1/assets/{asset_id}/versions/{version_id}/content",
+    ),
+    "assets.SetAssetConfig": ("POST", "/api/v1/assets/{asset_id}:set-config"),
+    "assets.SetAssetEnabled": ("POST", "/api/v1/assets/{asset_id}:set-enabled"),
+    "assets.SetAssetLifecycle": ("POST", "/admin/api/v1/assets/{asset_id}:set-lifecycle"),
+    "assets.SetCredential": ("POST", "/api/v1/assets/{asset_id}:set-credential"),
+    "assets.SetVisibility": ("POST", "/admin/api/v1/assets/{asset_id}:set-visibility"),
+    "assets.SyncCoreAssets": ("POST", "/admin/api/v1/assets:sync-core"),
+    "assets.TriggerAssemblyDispatch": ("POST", "/admin/api/v1/assembly-dispatch:trigger"),
+    "assets.UpdateAsset": ("PATCH", "/admin/api/v1/assets/{asset_id}"),
+    "assets.YankVersion": ("POST", "/admin/api/v1/assets/{asset_id}/versions/{version_id}:yank"),
+    # ---- billing ----
+    "billing.GetSubscription": ("GET", "/api/v1/billing/subscription"),
+    "billing.GetUsage": ("GET", "/api/v1/billing/usage"),
+    "billing.ListInvoices": ("GET", "/api/v1/billing/invoices"),
+    # ---- admin ----
+    "admin.ListUsers": ("GET", "/admin/api/v1/users"),
+    "admin.PromoteUser": ("POST", "/admin/api/v1/users/{user_id}:promote"),
+    "admin.RotateContextTokenKey": ("POST", "/admin/api/v1/context-token-keys:rotate"),
+    "admin.SetUserStatus": ("PUT", "/admin/api/v1/users/{user_id}/status"),
+}
+
+# 多段通配参数（模板里写作 {name=**}）：值含 `/`，须**逐段 encode 后以 `/` 连接**，
+# 不可整体 encodeURIComponent（否则 `notes/a.md` 会被压成单个 segment）。
+MULTI_PARAMS: dict[str, frozenset[str]] = {
+    "memory.Delete": frozenset({"memory_path"}),
+    "memory.Read": frozenset({"memory_path"}),
+    "memory.Write": frozenset({"memory_path"}),
+    "sandbox.ReadFile": frozenset({"path"}),
+}
+
+# 响应为流的端点（唯一事实源：contracts/gen/go-gateway 里 forward_*_0 =
+# runtime.ForwardResponseStream 的那几条）。流式端点必须走 Client.stream()：
+# 走 call() 会拿到逐行 JSON 的未解析正文。
+STREAMING: frozenset[str] = frozenset(
+    {
+        "sandbox.RunCommand",
+        "sandbox.RunCode",
+        "sandbox.ReadFile",
+        "sandbox.StreamLogs",
+        "session.StreamSessionEvents",
+        "memory.Search",
+        "memory.WatchTask",
+    }
+)
+
+
+def is_streaming(key: str) -> bool:
+    return key in STREAMING
+
+
+_TEMPLATE_RE = re.compile(r"\{([A-Za-z_][A-Za-z0-9_]*)(=\*\*)?\}")
+
+
+def path_params(key: str) -> list[str]:
+    """路径模板需要的参数名。"""
+    return [m.group(1) for m in _TEMPLATE_RE.finditer(_spec(key)[1])]
+
+
+def _spec(key: str) -> tuple[str, str]:
+    try:
+        return ENDPOINTS[key]
+    except KeyError:
+        raise UsageError(f"未知端点 {key!r}（用 `rathflow api --list` 查看全部）") from None
+
+
+def render_path(key: str, params: dict) -> str:
+    """把模板渲染成真实路径，逐参数 encode。缺参数 → UsageError。"""
+    _method, template = _spec(key)
+    multi = MULTI_PARAMS.get(key, frozenset())
+
+    def repl(m: re.Match) -> str:
+        name = m.group(1)
+        value = params.get(name)
+        if value is None or value == "":
+            raise UsageError(f"{key} 需要路径参数 --path {name}=<值>")
+        text = str(value)
+        if name in multi:
+            return "/".join(quote(seg, safe="") for seg in text.split("/"))
+        return quote(text, safe="")
+
+    return _TEMPLATE_RE.sub(repl, template)
+
+
+def method_of(key: str) -> str:
+    return _spec(key)[0]

rathflow_cli/errors.py

@@ -0,0 +1,70 @@
+"""错误信封与退出码（contracts/docs/error-envelope.md）。
+
+信封形状：{"error": {"code","message","details"}}。终端只显示 message，code 供程序判定。
+"""
+
+from __future__ import annotations
+
+# 退出码约定（docs：CLI 设计 §3.8）
+EXIT_OK = 0
+EXIT_ERROR = 1        # 未分类
+EXIT_USAGE = 2        # 参数/缺 project/未登录
+EXIT_AUTH = 3         # 401（刷新也无效）
+EXIT_FORBIDDEN = 4    # 403
+EXIT_NOT_FOUND = 5    # 404
+EXIT_INVALID = 6      # 400 INVALID_ARGUMENT / FAILED_PRECONDITION / OUT_OF_RANGE
+EXIT_CONFLICT = 7     # 409
+EXIT_RATE_LIMIT = 8   # 429
+EXIT_SERVER = 9       # 5xx
+
+_BY_STATUS = {
+    400: EXIT_INVALID,
+    401: EXIT_AUTH,
+    403: EXIT_FORBIDDEN,
+    404: EXIT_NOT_FOUND,
+    409: EXIT_CONFLICT,
+    429: EXIT_RATE_LIMIT,
+    499: EXIT_ERROR,
+    500: EXIT_SERVER,
+    501: EXIT_SERVER,
+    503: EXIT_SERVER,
+    504: EXIT_SERVER,
+}
+
+
+class ApiError(Exception):
+    """一次失败的 API 调用（信封已解出，或传输层失败）。"""
+
+    def __init__(self, status: int, code: str, message: str, details=None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.details = list(details or [])
+
+    @property
+    def exit_code(self) -> int:
+        return _BY_STATUS.get(self.status, EXIT_ERROR)
+
+    def __str__(self) -> str:
+        if self.code and self.code not in ("UNKNOWN", ""):
+            return f"{self.message} [{self.code}]"
+        return self.message
+
+
+class UsageError(Exception):
+    """本地用法错误（未登录、缺 project、参数不合法）。退出码 2。"""
+
+
+def from_response(status: int, payload) -> ApiError:
+    """从响应体解出信封；形状不符时退回通用文案（不外泄内部细节）。"""
+    body = payload if isinstance(payload, dict) else {}
+    err = body.get("error")
+    if not isinstance(err, dict):
+        return ApiError(status, "UNKNOWN", f"请求失败（HTTP {status}）")
+    return ApiError(
+        status,
+        str(err.get("code") or "UNKNOWN"),
+        str(err.get("message") or f"请求失败（HTTP {status}）"),
+        err.get("details"),
+    )