rdkagentsun/docs/12-multi-surface-interface-spec.md
Codex dd3a2044e6
Some checks failed
ci / python (push) Has been cancelled
ci / typescript (push) Has been cancelled
feat(S1-A): multi-surface foundation + closeout fixes
M0/S0 base + S1-A non-GUI slice (docs/S1-PLAN.md, docs/12):
- s100-readonly Helper profile (rejects run.*, real S100 inventory)
- device registration + SSH transport + host-key TOFU (OpenSSH-standard fingerprint, cross-process candidate)
- rdk-agent-host serve --stdio rename; packages/rdk-agent-surface (CLI device + MCP stdio, 2 tools)
- atomic cross-process approval consumption + idempotency flock takeover + approval crash recovery

Evidence: docs/testing/evidence/{M0,S1-A}.md
2026-08-14 14:45:52 +08:00

7.7 KiB
Raw Permalink Blame History

CLI、TUI、GUI 与 MCP 接口规范

状态:Baseline v0.7 平台优先级:macOS arm64 → Linux headless → Windows/Linux GUI

1. 统一原则

四种入口是一个产品的不同适配器:

CLI ─┐
TUI ─┼─→ TaskService ─→ createRdkSession ─→ Pi Agent ─→ Host ─→ RDK
GUI ─┤
MCP ─┘

它们共享:Pi 版本、system prompt、ResourceLoader、tool allowlist、Session 工厂、AgentTask、checkpoint、预算、策略、Run、Verifier、错误码和证据。Adapter 不创建自己的 Agent loop 或设备命令。

GUI 提供最完整的人控工作台;TUI/CLI 提供 Agent 工作流;MCP 允许另一个 Agent 把整个 RDK Agent 当作高层任务执行者。

2. macOS 分发

macOS Alpha 发布一个签名的 RDK Agent.app,内含受支持的 Node/Python Runtime 和 rdk-agent 可执行文件。GUI 设置页提供“安装命令行工具”,默认在用户确认后链接到 ~/.local/bin/rdk-agent,不要求 sudo;同时显示需要加入 PATH 的一次性提示。

同一版本号覆盖 App、CLI/TUI/MCP、Pi package、Host 和 Device Helper。rdk-agent version --json 显示各组件版本和协议版本。

3. 统一命令

rdk-agent                         # 交互终端中默认进入 TUI,否则显示帮助
rdk-agent gui                     # 打开/聚焦 GUI
rdk-agent tui [workspace]
rdk-agent run "<goal>" [--workspace PATH] [--device ID] [--json]
rdk-agent task list [--json]
rdk-agent task status TASK_ID [--json] [--follow]
rdk-agent task steer TASK_ID "<message>" [--json]
rdk-agent task cancel TASK_ID [--json]
rdk-agent task resume TASK_ID [--take-over] [--json]
rdk-agent device list|inspect [DEVICE_ID] [--json]
rdk-agent mcp --stdio --workspace-root PATH
rdk-agent doctor [--json]
rdk-agent version [--json]

rdkctl 是另一项底层工具,用于确定性诊断/恢复和 CI。产品 CLI 不调用或解析 rdkctl 输出;两者直接调用相同的 Application Service。

3.1 CLI 输出

  • 默认输出简洁人类进度和最终证据摘要;
  • --json stdout 只输出版本化 JSON envelope;--follow 使用 JSONL event;
  • 日志写 stderr,不混入协议;
  • 退出码沿用 docs/03 §8;任务进入 waiting_user 时返回策略/批准类别退出码并保留可恢复 task_id,不当作内部崩溃。

最终 envelope 示例:

{
  "schema_version": "1.0",
  "ok": true,
  "data": {
    "task_id": "task_01...",
    "state": "completed",
    "outcome": "passed",
    "summary": "系统健康卡已生成并通过验证",
    "evidence_refs": ["verification:verify_01..."]
  },
  "error": null,
  "correlation_id": "corr_01..."
}

4. TUI

TUI 复用 Pi 的交互能力和 Session events,但只加载产品资源。最低布局:

顶部:模型 | 设备 | Task 阶段 | 预算
主体:对话与 Agent 事件
侧/弹层:计划、文件 diff、运行、Verifier、图片/Artifact 摘要
底部:输入、等待用户动作、取消/继续

最低命令:/device、/task、/plan、/diff、/runs、/evidence、/model、/resume、/cancel、/open-gui。内部 ID 默认隐藏;/details 展开。

连接新设备、核验 host key、烧录或网络配置可以暂停并提示 /open-gui。TUI 不为了“功能齐全”复制不适合终端的烧录和远程桌面 UI。

5. GUI

GUI 按 docs/10 提供工作台、项目、设备、作品和设置。它和 TUI 订阅相同 Session/Task events,不通过解析终端输出展示 Agent。

GUI 可观察 CLI/MCP 发起的任务;点击“接管并继续”时:

  1. 请求旧 owner 正常停止;
  2. 对账活动 Device Run;
  3. 更新 per-task lock;
  4. resume 同一 Pi Session;
  5. 记录 task.owner_changed 事件。

6. MCP Server

6.1 Transport 与生命周期

  • 命令:rdk-agent mcp --stdio --workspace-root <absolute-path>;
  • 协议基线:MCP 2025-11-25,实现时锁定兼容 SDK;不使用实验性 MCP Tasks,产品返回自己的稳定 task_id;
  • stdout 只写 MCP JSON-RPC,日志写 stderr;
  • Alpha 不打开 HTTP/TCP/Unix socket,不使用 MCP sampling;
  • server 名称 rdk-agent,工具按确定顺序返回。

6.2 Tool allowlist

rdk_device_list
rdk_device_inspect
rdk_task_start
rdk_task_status
rdk_task_steer
rdk_task_cancel
rdk_artifact_read

rdk_device_list

输入为空对象。输出已注册设备的 ID、alias、连接状态、板型和 snapshot freshness;不输出地址、用户名、host key 或凭据。

rdk_device_inspect

输入:device_id、refresh: cached|quick|full。只调用受控 Inventory profile,调用方不能提交 probe 命令。host key 未确认时返回 waiting_user。

rdk_task_start

输入:

{
  "goal": "拍一张 USB 摄像头图片并验证尺寸",
  "workspace": "camera-demo",
  "device_ids": ["device_01..."],
  "mode": "guide"
}

workspace 是启动参数 workspace-root 下的相对项目路径;mode 仅为 guide|auto_low_risk。输出 task_id、当前 state 和事件 cursor。不存在任意 policy、shell 或 approval 参数。

rdk_task_status

输入:task_id、可选 after_event_seq。输出 state、phase、outcome、截断进度、evidence、error 和 required action;不输出模型长推理或未清洗日志。

rdk_task_steer

输入:task_id、message。只向既有 Task 添加用户意图;不能改变 policy、required verifier、workspace root、device identity 或批准状态。

rdk_task_cancel

输入:task_id、可选短 reason。幂等取消 Agent turn 和活动 Run;输出最终/清理状态。取消请求不能被模型忽略。

rdk_artifact_read

输入:task_id、artifact_id。只读取该 Task 已声明、摘要验证并完成清洗的 text/JSON/image preview。首版上限 1 MiB;大文件返回元数据和“请在 GUI/CLI 中显式导出”,不返回任意本地路径。

6.3 统一等待用户动作

{
  "task_id": "task_01...",
  "state": "waiting_user",
  "required_action": {
    "type": "verify_host_key",
    "title": "请核验开发板身份",
    "description": "这台设备尚未确认 SSH 指纹。",
    "allowed_surfaces": ["gui", "tui"]
  }
}

允许的 action type 首版固定为:verify_host_key、connect_device、attach_hardware、open_network_settings、open_flash_wizard、review_risk。MCP 不提供 complete_required_action 或 approve tool;真人必须转到允许的界面完成,随后外部 Agent 查询/继续 Task。

7. 跨入口并发

Alpha 使用 state/task-locks/<task-id>.json 和原子 create/rename:

{
  "schema_version": "1.0",
  "task_id": "task_01...",
  "owner_instance_id": "instance_01...",
  "pid": 1234,
  "process_started_at": "2026-08-13T08:00:00Z",
  "heartbeat_at": "2026-08-13T08:00:03Z"
}

锁文件只是本地主机单写保护,不是领域对象或分布式服务。进程存在且 heartbeat 新鲜时不能窃取;锁陈旧时先检查 PID/start time、防 PID 复用,再对账活动 Run。显式 take-over 必须产生事件。真正设备副作用仍由 request id 幂等与 Device 写租约保护。

8. Alpha 完成标准

  1. macOS 安装包同时提供可启动 GUI 和相同版本 CLI/TUI/MCP;
  2. 四入口使用同一生产 Session 工厂和工具 allowlist;
  3. 同一健康卡任务的 Task/Run/Verifier/error 语义一致;
  4. Task 可跨 GUI/TUI/CLI 观察和继续,不产生双 writer;
  5. Claude Code/Codex 通过 MCP 可 start/status/steer/cancel/read artifact;
  6. 人工动作稳定返回 waiting_user,MCP 不存在批准/终端/烧录/凭据能力;
  7. MCP 进程无网络监听,stdout 协议纯净,workspace/Artifact 越界负例通过。