rdkagentsun/docs/00-document-map.md
Codex e159b82ce7 docs(sim): SIM-R2 L2 status, full enumeration closed, AT-038..041 reserved
ADR-019 §11 open item 2 closed (12-row three-tier enumeration; bpu/camera
promoted real-sim with synthetic limitations; FIND-002 contradiction documented
not silently resolved). docs/02 §4.16 L2 paragraph; TEST_STRATEGY §12.2
synthetic-frame/BPU determinism; AT-038..041 reserved; traceability + 00/06
registration.
2026-08-27 16:03:16 +08:00

6.8 KiB
Raw Permalink Blame History

文档地图与规范管理

状态:Baseline v0.7 最后更新:2026-08-14 目标读者:产品负责人、架构师、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/S1-PLAN.md S1-A 实施、验收决定与带截止点的遗留项 是
docs/S1-B-PLAN.md S1-B 共享 TaskService 与 CLI/TUI/GUI/MCP 最小纵切片 是
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.7 仿真重建决策:接受 ADR-019,仿真系统重建为“虚拟 RDK”两层(板级 L2 可运行板 + 设备形态电路/几何仿真),不上刚体物理引擎,几何内核 OpenCascade/build123d,运行出身仿真/真机分列,验收自 AT-034 起。
  • v0.7 仿真 SIM-R2:L2 可运行板 Python 侧(审核模板真跑 + 合成相机帧 + BPU 结构化结果 + 完整接口面三档枚举),验收 AT-038..041;GUI/TUI 设计旅程为并行轨道。
  • 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. 设计冻结与变更流程

  1. 提出问题、动机和可选方案;
  2. 对安全边界、设备兼容性、数据迁移和测试影响做评审;
  3. 对不可轻易逆转的选择新增 ADR;
  4. 更新规范文档和验收用例;
  5. 再开始实现。

当前冻结项:产品目标为替代 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 和自动训练不进入当前路线。