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
6.1 KiB
6.1 KiB
文档地图与规范管理
状态:Baseline v0.7 最后更新:2026-08-13 目标读者:产品负责人、架构师、Claude Code 实现者、测试与设备实验室维护者
1. 文档清单
| 文档 | 作用 | 是否规范性 |
|---|---|---|
README.md |
项目入口与范围摘要 | 否 |
CLAUDE.md |
Claude Code 的实现纪律和安全底线 | 是 |
docs/01-product-requirements.md |
用户、场景、范围、功能与非功能需求 | 是 |
docs/02-system-architecture.md |
组件、数据流、部署、扩展点与技术选型 | 是 |
docs/03-domain-model-and-protocol.md |
命令、状态机、Schema 与兼容规则 | 是 |
docs/04-skill-system.md |
本地 Project Pack;长期社区技能结构与治理 | 是 |
docs/05-security-and-safety.md |
人工开发工具与 Agent 分权、运行边界和硬件安全 | 是,优先级高 |
docs/06-implementation-plan.md |
替代产品 S0–S6、任务依赖、交付物和质量门禁 | 是 |
docs/07-operations-and-observability.md |
历史平台运维参考;当前路线以 docs/01、02、06、11 为准 | 否,历史文件 |
docs/08-pi-agent-runtime.md |
Pi SDK、工具、会话、非端侧 Agent 运行时与部署拓扑 | 是 |
docs/09-claude-code-handoff.md |
Claude Code 首轮任务、提交物和阶段评审协议 | 是 |
docs/10-student-experience-design.md |
GUI/TUI/CLI/MCP、桌面工作台、Agent 创作和作品体验 | 是 |
docs/11-rdk-studio-replacement-plan.md |
RDK Studio 能力承接矩阵、差异化和替代判定 | 是 |
docs/12-multi-surface-interface-spec.md |
CLI/TUI/GUI/MCP 命令、工具、任务接管与 macOS 分发 | 是 |
docs/13-rdk-project-positioning.md |
与其他类型 RDK 项目的关系、同目标方案差异和整合边界 | 是 |
docs/testing/TEST_STRATEGY.md |
分层测试、环境矩阵、证据和缺陷门槛 | 是 |
docs/testing/ACCEPTANCE_TESTS.md |
可执行的验收场景与预期结果 | 是 |
docs/testing/HIL_LAB_SPEC.md |
硬件在环工装、接线与实验室安全 | 是 |
docs/testing/CURRENT_HARDWARE_BASELINE.md |
当前 S100P 裸板、直连网络和待到货 USB 摄像头的事实基线 | 是 |
docs/testing/TRACEABILITY.md |
需求与验收测试的基线映射 | 是 |
docs/adrs/*.md |
已接受的关键架构决策 | 是,优先级最高 |
docs/references.md |
调研来源和适用结论 | 否 |
2. 需求标识
GOAL-*:产品目标;FR-*:功能需求;NFR-*:非功能需求;SEC-*:安全需求;C-GOAL-*/CFR-*/CNFR-*/CSEC-*:v0.7 面向学生的替代产品目标与需求;既有FR/NFR/SEC保留为底层契约和历史实现追踪,编号不得复用成不同含义;AT-*:验收测试;ADR-*:架构决策。
实现、Pull Request、测试报告和发布说明必须引用相关标识。需求变更不得仅修改代码;必须同步修改需求、协议、测试和受影响 ADR。
3. 冲突优先级
从高到低:已接受 ADR → 安全设计 → 协议与领域模型 → 系统架构 → 产品需求 → 实现计划。发现冲突时应提交 ADR 或规范修订,不允许实现者自行选择最方便的解释。
4. 版本策略
- 文档集使用
major.minor基线版本;当前为0.7。 v0.7变更:接受 ADR-013,明确产品不是 RDK Studio 的附加助手,而是以 Pi Agent 为核心、面向学生和个人开发者的下一代 RDK 桌面开发环境;新增工作台基线、替代矩阵、人与 Agent 分权及 S0–S6 路线。v0.7桌面决策:接受 ADR-014,S1 使用 Electron + TypeScript/React,避免并行维护多套 UI 技术路线,并冻结最小 preload IPC 与人机分权边界。v0.7多入口决策:接受 ADR-015,CLI、TUI、GUI 和 MCP stdio 成为共享同一 Pi Runtime 的一等入口;macOS arm64 为首发平台,MCP 用于其他 Agent 调用。v0.6变更:接受 ADR-012,将产品收敛为面向高校学生和个人开发者的 local-first RDK 机器人 DIY 编程伙伴;Student MVP 聚焦首次连接、项目推荐、可见作品、解释学习和本地 Project Pack,托管、多租户、relay、复杂技能供应链和强隔离 profile 后移。v0.5变更:接受 ADR-011,将硬件/软件环境盘点提升为 Agent 一等能力;注册信息不再充当设备事实,首次连接、快照过期和相关硬件变化时由受控 Inventory Engine 自动刷新。v0.4变更:接受 ADR-010,将首台真机从假定的 X5 改为实际可用的 S100P 裸板直连环境;USB 摄像头作为到货后的增量 HIL,舵机不作为本地门禁。v0.3变更:接受 ADR-009,将 PC、工作站、服务器和云统一为非端侧 Agent 部署目标,并把 direct/relay 下沉为正交的设备传输拓扑;无既有代码或数据迁移。- 传输与持久化对象各自携带
schema_version,规则见协议文档。 - 在 v1.0 前允许做不兼容设计修改,但必须提供迁移说明并更新所有示例与契约测试。
- v1.0 后,破坏性修改只能进入新的 Schema major 或 CLI major。
5. 设计冻结与变更流程
- 提出问题、动机和可选方案;
- 对安全边界、设备兼容性、数据迁移和测试影响做评审;
- 对不可轻易逆转的选择新增 ADR;
- 更新规范文档和验收用例;
- 再开始实现。
当前冻结项:产品目标为替代 RDK Studio 的 Agent 原生 RDK 开发环境;运行时采用固定版本 Pi SDK;CLI/TUI/GUI/MCP 共用同一 Runtime,macOS arm64 首发;目标用户为高校学生和个人开发者;local-first、单用户、单设备优先;PC、工作站、服务器和云仍是同一非端侧 Agent 的部署位置;MCP 首版仅 stdio;RDK 为端侧;首台真机为 S100P 裸板,通过网线 SSH stdio 连接;精确系统/BPU 版本由首次快照冻结;USB 摄像头到货前相机 HIL 为 blocked;GPIO/PWM/舵机/电机在安全套件完成前不可用;人工终端/烧录与 Agent/MCP 工具分权;任务完成由 verifier 决定;作品资产为本地 Project Pack。托管、多租户、远程 MCP/relay、复杂社区技能治理、多 Agent 和自动训练不进入当前路线。