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
7.7 KiB
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 输出
- 默认输出简洁人类进度和最终证据摘要;
--jsonstdout 只输出版本化 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 发起的任务;点击“接管并继续”时:
- 请求旧 owner 正常停止;
- 对账活动 Device Run;
- 更新 per-task lock;
- resume 同一 Pi Session;
- 记录
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 完成标准
- macOS 安装包同时提供可启动 GUI 和相同版本 CLI/TUI/MCP;
- 四入口使用同一生产 Session 工厂和工具 allowlist;
- 同一健康卡任务的 Task/Run/Verifier/error 语义一致;
- Task 可跨 GUI/TUI/CLI 观察和继续,不产生双 writer;
- Claude Code/Codex 通过 MCP 可 start/status/steer/cancel/read artifact;
- 人工动作稳定返回 waiting_user,MCP 不存在批准/终端/烧录/凭据能力;
- MCP 进程无网络监听,stdout 协议纯净,workspace/Artifact 越界负例通过。