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
14 KiB
RDK Agent 实现计划
状态:Baseline v0.7 实施原则:以替代 RDK Studio 为产品门槛;CLI/TUI/GUI/MCP 同内核;macOS 优先;以学生首次成功为体验标准;集成成熟组件;Fake 不替代真机和可用性证据
1. 路线结论
项目不是 RDK Studio 之外的学生助手,而是以 Pi Agent 为核心的下一代 RDK 开发环境。路线同时承担:
- 完整承接设备准备、连接、项目、编辑、文件、终端、串口、网络、烧录、模型和运行观察;
- 用 Inventory、Agent 编程闭环、Verifier 和 Project Pack 形成差异。
实现仍保持 local-first、单用户、单设备优先,不恢复企业多租户、relay、设备池、复杂审批和多 Agent。先在当前 macOS arm64 + S100P 上同时交付 CLI/TUI/GUI/MCP 的共享垂直切片;Linux 先做 CI/headless 契约,随后扩展替代矩阵。
2. 阶段与发布关系
| 阶段 | 目标 | 关键出口 | 发布含义 |
|---|---|---|---|
| S0 | 修稳现有 M0 | 生产 Pi 入口、原子幂等、基线全绿 | 工程底座 |
| S1 | 多入口 macOS 基础 | CLI/TUI/GUI/MCP 共用 Session/Task;macOS 壳 + S100P SSH/Inventory | macOS Alpha 起点 |
| S2 | Agent 开发闭环 | Pi 在项目中编写、运行、验证、恢复 | Agent Alpha |
| S3 | 三个 Starter 与作品 | 健康卡、BPU、USB Camera、Project Pack | macOS Alpha |
| S4 | 设备中心补齐 | SSH、Type-C、串口、网络、远程文件/终端/桌面 | Preview |
| S5 | 系统准备与生态 | 产品内烧录、板型/镜像、项目/NodeHub 导入 | Preview |
| S6 | 替代发布 | Windows/macOS/Linux、目标板型、迁移与替代任务集通过 | Replacement Release |
任何阶段可以内部演示,但只有 S6 全部门禁通过后才能宣称“已经替代 RDK Studio”。
3. 技术基线与简化约束
- Pi SDK 固定精确版本,Node
>=22.19.0; - TypeScript:Pi Runtime、共享 TaskService、CLI/TUI/MCP 和桌面应用;Python 3.10+:Host/Device、RDK API 与底层
rdkctl; - 桌面技术栈按 ADR-014 固定为 Electron + TypeScript/React;编辑器采用 Monaco,终端呈现采用 xterm.js;不同时维护多个 UI 方案;
- 编辑器、终端、串口、远程桌面优先集成成熟组件;烧录优先调用官方 XBurn 引擎;
- CLI/TUI/GUI/MCP 共用一个
createRdkSession、TaskService 和 Task store;Host Application Service 是 Pi tools、TaskService 和rdkctl的共同设备业务入口; - MCP 首版仅 stdio、高层 Device/Task/Artifact tools;不复制内部 Pi tool,不实现 HTTP;
- Agent 和人工工具可以共享连接元数据,不能共享命令通道、授权和确认;
- Pydantic/JSON Schema 只用于跨语言、跨进程或持久化边界;
- 本地 JSON/JSONL + 普通文件优先;出现真实查询/迁移需求再引入 SQLite;
- 不新增企业身份、租户、relay、签名市场、插件平台或通用策略语言。
4. S0:修稳现有 M0
4.1 必修项
createRdkSession只保留一条生产/测试共用装配路径:一个 Host client、显式 extension factories、一次reload();run.start使用原子 claim/complete,覆盖并发相同 request id 和响应丢失;- Pi 包支持 Node
>=22.19.0,不修改node_modules规避依赖问题; - Secret guard 区分真实秘密阻断与日志字段脱敏,允许正常环境变量引用;
- 清理重复组装、未使用 client、错误 fixture 和失实证据;
- 测试直接覆盖生产 Session 入口。
4.2 出口
- Python/TS 全部门禁通过;
- 生产 Session 精确加载受信 RDK tools,built-in tools 不可见;
- 100 轮并发相同 request id 每轮只产生一个 Host Run 和 Device Run;
- 正常 Python 环境变量引用可写,canary secret 仍被阻断/清洗。
5. S1:多入口 macOS 基础
5.1 用户旅程
在 macOS 安装 RDK Agent
→ 从 GUI 配置模型并连接 S100P
→ GUI/TUI/CLI 查看同一设备盘点
→ 从 CLI 启动健康卡任务,在 TUI/GUI 观察并继续
→ 由另一个 Agent 通过 MCP stdio 启动同类低风险任务
→ 所有入口得到同一 Task/Run/Verifier 语义
5.2 交付物
- 共享
TaskService、唯一生产createRdkSession、持久 Task store 和单 writer owner lease; rdk-agent run|task ... --json产品 CLI,与rdkctl底层诊断 CLI 分离;rdk-agent tui:复用 Pi TUI 能力,呈现设备、计划、diff、run、evidence、resume/cancel;rdk-agent mcp --stdio:显式 Device/Task/Artifact tool allowlist、waiting_user和 workspace root;- macOS Electron 壳:工作台、项目、设备、作品、设置五个一级入口;
- 按 ADR-014 提供可分发开发构建、最小 preload API 和 renderer 隔离测试;
- 项目创建/打开、项目树、代码编辑/搜索/diff、问题/输出和人工终端;
- 模型中心:Pi provider 配置、连通性测试、系统钥匙串;
- S100P SSH 连接向导、产品独立 known_hosts、保存连接和状态;
- 普通用户目录安装/更新 Device Helper,不安装 root daemon;
- S100P board/OS/resources/temp/BPU/USB/video/TROS Inventory 与设备卡;
- CLI/TUI/GUI/MCP、Pi Runtime 和 Host 之间一条生产事件通路;
- 将 Python Host 内部入口从冲突的
rdk-agent serve迁移为rdk-agent-host serve --stdio,TS Host client 使用固定 argv 调用。
5.3 出口
- 干净 macOS arm64 环境能安装/打开 GUI 并运行 CLI/TUI/MCP,不要求预装 Node/Python 或外部 IDE;
- 用户只提供连接信息,不预填硬件事实;关键盘点字段有 evidence;
- 同一健康卡契约经四入口产生一致 Task/Run/Verifier 结果;Task 跨入口可观察、resume 和显式接管,无双 Agent writer;
- Claude Code/Codex 等 MCP client 可启动、status、steer、cancel 和读取声明产物;人工动作返回
waiting_user,调用方不能 self-approve; - 人工终端能使用已核验 SSH,但不出现在 Pi tool 列表,Agent 不能读取其历史;
- 5 名目标学生至少 4 名在无口头技术指导下完成项目创建、连接和设备卡查看;
- 不为 MCP HTTP、Type-C、烧录或 Windows 建空 adapter;出现真实实现/需求时再抽象。
6. S2:Agent 开发闭环
6.1 交付物
- 受控 Agent Workspace:list/read/search/write/patch/diff/checkpoint;
- “我写了什么”的 diff、解释和 UI/Agent 并发版本冲突;
- UserProcessBackend:普通 SSH 用户、产品 run root、固定 cwd 和有界资源;
- source/snapshot-bound Plan、原子 start、单写 Run;
- start/watch/cancel、进程树清理和断线对账;
- stdout/file/JSON/image Artifact 与基础 Verifier;
- AgentTask checkpoint、预算和恢复;
- Starter 1:系统健康卡。
6.2 出口
- 全新 Session 仅凭自然语言完成 inspect → code → plan → run → verify → result;
- 用户能看到代码、运行位置、输出和成功依据;
- 源码/快照变化使旧 Plan 失效,相同 start 重试不重复;
- timeout/cancel 清理全部子进程,Verifier 无法确认时不假报成功;
- Agent 与 MCP caller 无法调用人工终端、远程文件、串口写、网络、烧录或 approval decision。
7. S3:三个 Starter 与 Project Pack
7.1 Starter
- 系统健康卡:版本、资源、温度、磁盘、BPU 状态与 Schema 验证;
- 静态 BPU 推理:固定摘要的已验证模型/输入,显示结构结果、耗时和温度;
- USB Camera:缺失状态、插入 Delta、模式协商、单帧图片和图像验证;摄像头到货前 HIL 保持 blocked。
每个 Starter 都有正常、能力缺失、参数错误、取消和一次 Remix 路径。
7.2 Project Pack
- 用户保存成功 Run 时生成 Project Pack draft,并可同时生成不默认加载的 Skill Candidate draft;
- 干净 workspace 复跑后成为 verified-local;
- 清除 IP、用户名、设备身份、绝对路径、秘密和临时产物后导出 shareable;
- 导入后重新 Inventory、兼容检查和普通 Plan/Run/Verifier;
- Skill Candidate 只引用 Pack/Run/Capability 和证据,不复制源码/Manifest/Verifier;在第二个不同任务中复用通过且用户确认后才启用;
- 只用本地
project-packs/与skill-candidates/文件目录,不实现两个服务、社区账号、签名、评分或撤销服务。
7.3 出口
- 三个项目从桌面首页进入,不要求 prompt engineering;
- S100P 真机 20 次低风险 smoke 成功率 ≥95%,无 orphan/假成功;
- 至少一个 Pack 在干净项目中复跑和清洗导出;
- 至少一个 Skill Candidate 与来源 Pack 正确关联;删除或改变来源兼容条件后不会继续加载,且不能获得额外工具或权限;
- 5–8 名学生完成一个作品、解释修改/运行/成功依据并 Remix,门槛达到
CNFR-002/003。
8. S4:设备中心补齐
8.1 交付物
- SSH 连接管理完善:多保存连接、发现、编辑、删除和断线恢复;
- Type-C 直连发现与确定性网络配置;
- 串口发现、只读日志、人工交互和占用/断开恢复;
- 远程文件、人工终端和声明支持的远程桌面;
- 连接方式与 DeviceSnapshot 统一展示,但不把串口存在误判为 Agent 可运行;
- 各主机系统/板型的能力矩阵和不可用提示。
8.2 出口
- 声明支持的连接方式完成自动化 + 真机矩阵;
- 网络变更有预览、用户确认和失联恢复;
- 串口默认只读,Agent 只能读取裁剪/脱敏日志,不能写入;
- 人工工具的权限和会话仍未进入 Pi tool surface;
- 用户可在一个应用内完成常见连接、观察和远程调试。
9. S5:系统准备与内容生态
9.1 烧录
- 调研并冻结可复用的 XBurn 集成接口、许可和平台分发方式;
- 板型/镜像目录、来源、摘要、兼容和缓存;
- 设备识别、数据清除/断电提示、最终用户确认、进度、取消边界和失败恢复;
- fake engine 覆盖状态机;真实写入只在专用可恢复设备与人工值守 HIL 执行;
- Agent 只能建议打开向导和解释错误,不能触发最终 flash。
9.2 项目生态
- Starter/课程/NodeHub 项目导入到普通项目和 Project Pack;
- 导入时展示来源、依赖、支持板型和可见结果;
- 不在本阶段建设社区账号、推荐服务和复杂供应链。
9.3 出口
- 目标板型从镜像选择到首次启动完成一次受控真机流程;
- 板型不符、摘要错误、拔线、失败和恢复路径有证据;
- 新板用户无需打开外部烧录 UI;底层可以合法复用官方引擎;
- 一个外部示例能导入、Agent 修改、真机验证并保存为 Pack。
10. S6:替代发布
10.1 兼容与迁移
- Windows、macOS、Linux 安装、升级、卸载和项目数据恢复;
- 明确承诺的 RDK 板型、系统版本和连接能力矩阵;
- 至少一个通用 SSH Linux 设备的连接、编辑、文件、人工终端和远程观察;RDK 专属能力正确降级;
- 从常见项目目录和连接配置迁移,不能迁移的设置给出重新配置向导;
- 发布包签名、自动更新、崩溃恢复和本地诊断导出。
10.2 替代门禁
至少 8 名目标用户完成:安装/模型 → 新板系统准备 → 两种设备连接 → 串口/状态 → 项目创建/编辑/人工终端 → Agent 开发与修复 → 验证 → Pack 复用。全过程不打开 RDK Studio 或外部 IDE,独立完成率 ≥80%。
docs/11-rdk-studio-replacement-plan.md 每一行必须有自动化、HIL 或可用性证据。任何高频任务需要回退都使门禁失败;未支持能力明确记录,不以“可以在终端做”代替产品集成。
11. 保留与停止扩展
必须保留
- 设备事实与用户 hint 分离;
- host key、Agent workspace/non-root、秘密隔离和人机分权;
- source/snapshot-bound Plan;
- 原子幂等、单写、超时、取消和清理;
- Verifier 决定完成;
- Task/checkpoint 恢复;
- Pi 精确版本与生产装配契约。
停止扩展
- 多租户、组织 actor、relay/Connector、mTLS、设备池;
- 通用策略语言、复杂审批服务和 root Supervisor;
- 所有硬件一律 Broker 化;
- CAS/数据库/遥测平台的预先抽象;
- 完整 Skill 六阶段、签名/撤销/复杂检索;
- 多 Agent orchestration;
- 远程 MCP/HTTP、为外部 Agent 复制内部 tools 或单独 Agent loop。
12. 给 Claude Code 的执行模板
请先阅读 CLAUDE.md、ADR-012–015、docs/01、docs/11、docs/12 和本文件。本轮只实现 S<n>。
产品是面向高校学生和个人开发者、目标替代 RDK Studio 的 Agent 原生 RDK 开发环境,macOS 优先并同时提供 CLI/TUI/GUI/MCP。先列出:
1. 本阶段直接承接的替代工作流;
2. CFR/CNFR/CSEC 与验收 ID;
3. 一条用户可见的桌面垂直旅程;
4. 最多 6 个实现任务;
5. 将集成的成熟组件,以及确需新增的抽象。
实现时:
- 直接测试生产入口;
- CLI/TUI/GUI/MCP 不复制 Session 工厂、prompt、Pi tools 或业务逻辑;
- MCP 只做 stdio 高层 Task API,不镜像内部 tools,不实现远程 HTTP;
- 人工终端/文件/串口/烧录绝不能注册为 Pi tool 或继承 Agent 授权;
- 保留 host key、non-root、路径、幂等、取消、危险动作拒绝和 verifier;
- 不实现托管、租户、relay、多 Agent、复杂 registry 或 root Supervisor;
- 不用宽泛秘密/危险扫描阻止正常学生代码;
- 不连接真实设备执行本阶段未批准的写操作。
结束时报告:桌面旅程、代码与测试、真机/平台 tested/not tested/blocked、替代矩阵进展、剩余 P0–P2 和阶段出口。Fake 不能宣称真机、跨平台或替代通过。
13. 完成定义
阶段完成必须同时满足功能、各阶段要求的产品入口、Agent 安全边界、生产入口、对应真机/平台证据和用户门禁。S1 缺少 CLI/TUI/GUI/MCP 任一入口、四者不共享 Task/Session、只有 Fake,或者仍必须打开 RDK Studio 才能完成目标,都不算完成。