Skip to content

Latest commit

 

History

History
179 lines (147 loc) · 14.2 KB

implementation-backlog.md

File metadata and controls

179 lines (147 loc) · 14.2 KB

架构与实现待决事项

本文件跟踪 RoboGuide V2 架构基线 尚未冻结的问题,以及应由 MVP 或实现证据决定的工程选择。当前架构语义以 V2 README 和已接受 ADR 为准;历史 DOCX 不是后续演进的 source of truth。

2026-10-12 全 ADR 遗留项核验与当前实施顺序见 ADR 遗留项清单。已由后续 ADR 实现的子集回写原 文档;Software implemented、默认关闭、物理验证待补与一般研究扩展保持不同状态。

V2 开放架构问题

ID 问题 需要回答的核心内容
Q1 State Authority 已有 source-aware federation 之上,Shared Belief 在何种新鲜度和不确定性条件下可驱动决策;冲突如何由显式 provider 归约
Q2 Spatial Authority Map、Pose、World Model 如何建立共同空间关系和系统级 reference authority
Q3 Control Topology 集中式 Control Plane、层级控制和 Federation 的适用边界
Q4 Execution Group Authority Mission-level Group、TaskExecution ownership、Context semantics 与成员节点权威如何划分
Q5 Scheduling vs Runtime Coordination Plan-time allocation、资源协调与 execution-time adaptation 的边界
Q6 Temporal Assurance 同步、时钟偏差、deadline 和时间窗口如何成为架构约束
Q7 Resource Commitment Semantics Commit、Lease expiry、preemption、partial release 需要何种一致性保证

Q2 实现切片:Distributed Spatial Memory v0

Q2 的首个可验证切片已接受 ADR-0016: 地图采用 immutable revision + SHA-256 CAS artifact,manifest/provenance/anchor/replica 状态进入 State & Memory Catalog,bytes 走独立 streaming Artifact data plane。v0 的 Spatial Authority 是 manifest 中显式声明的固定物理 anchor;跨 Mission 的消费者通过预分配 (MapId, MapRevisionId) pull,导入后必须单独验证 localization。该切片不解决 map fusion、 实时同步、active-map 选择、动态 output binding、删除/GC 或认证传输安全。

Spatial v0 的故障恢复仍受下述 Runtime Gate 约束:artifact publication 或 replica evidence 在本地动作完成后若无法确认,会保持 Unknown/recovery-pending,不能自动重放物理动作。 Node 已支持对完全相同 Execute 的 artifact-finalization-only resume,且不会重放 Local EAIOS;Node 重启看到 pending finalization marker 时会继续 fence,不会自行选择该 resume。 prepare-output 也会在首次读取可变 source 前持久化 freeze fence;崩溃遗留 fence 会进入 ReconciliationRequired,相同 Execute 不会再次冻结 source。Control/Orchestration 尚未根据 recovery decision 自动触发 exact retry。稳定基线仍需 RT-G2 闭环这一决策,或由 RT-G3 创建新的 physical attempt;在此之前只适用于有人值守、可人工停止的实验。

Spatial v0 的已知后续工作:

  • 真机部署需要版本化的 Local EAIOS/Robonix/ROS mapping 和完整的 build -> prepare-output -> publish -> stage -> import -> verify system test;当前场景 只提供配置驱动的 Node fixture 和外部 HTTP workflow 假设。
  • Generic Memory replica evidence 已包含 exact consumer provider;下一版仍应补充 consumer TaskRef、execution identity 和 artifact binding,以便 State 与 Runtime 审计关联到具体 TaskExecution。
  • Generic Memory 需要独立设计 Controller -> Node selective-import command,包括 exact consumer provider/revision、application-accepted durable ACK、重试 fence 和可选 ExecutionGroup 关联;在 该协议冻结前不得由 discovery 自动触发全量复制,也不得借普通 Execute 隐式改变 Task lifecycle。
  • Staged evidence 的 durable pre-dispatch 时点、文件句柄级 TOCTOU 约束,以及临时 upload identity 的随机/单调生成仍需独立决策,不能在 v0 中隐式改变事件语义。

Q1 实现切片:Federated State and Selective Memory v0.1

ADR-0024 已建立 Node/World/RoboGuide 对象、六类 State semantic、source/channel/time/TTL/confidence,以及对 Mission、Control、 Shared Node State、Runtime/Orchestration projection 的只读 federation。Node Config v0.5 和 Protocol v0.4 继承选择性 Reported/Observed push;State observation 不自动触发 recovery。

同一切片建立五类 Memory 的 provider discovery、immutable manifest catalog 和基于现有 CAS 的 selective exchange evidence。它解决共同上层语义与 local ownership,不关闭 Q1:Belief provider、fusion/conflict policy、允许哪些 Belief 影响 Control、访问控制、retention/GC、 多 Controller 的静态 quorum metadata profile 已由 ADR-0083 实现并通过合成进程检查; 跨主机、内容可用性与物理发布仍需场景证据。通用 Node Memory workflow 已由 ADR-0025 的 v0.6 provider discover/export/import workflow 与 filesystem/JSONL Node ledger/reference fallback 补齐;真实 EAIOS 继续拥有 semantic/storage authority,其 adapter 行为仍需现场证据。

MVP 定义待决事项

当前决策状态和冻结清单由 mvp-definition.md 统一记录:

  • 具体多机异构任务、节点组合和任务成功条件;
  • 正常路径与节点掉线、Capability degraded、Reservation conflict 等故障注入;
  • Proposal、Commit、Bind、Execute、Reconcile 各阶段的可观察验收证据;
  • 延迟、恢复时间、资源冲突和任务完成的最小指标;
  • 导盲等后续领域场景如何通过领域层接入通用核心。

Mission Front-half 后续切片

ADR-0030 已将 Mission 语义接纳 与当前部署可执行性分开。后续按独立合同切片处理,不能重新使用 live inventory 代替稳定语义:

  • Canonical Capability Catalog v0.3 已按 ADR-0034/ADR-0036 区分 Capability/attribute 与 Operation/parameter,并支持多 capability requirements、typed feasibility predicates 及 integrated operation 的 provider-level baseline;结构化 entity values、embodiment taxonomy 及 Catalog 分发/协商仍待后续版本;
  • MissionPlan v0.7 已正规化 Actor -> ContextRole -> TaskRole、semantic ExecutionIntent 及 Role requirements,并保持 Local EAIOS 的 Local How authority;
  • Node Contract v0.6 独立传输 Capability Profile、Operation Support,并把 v0.7 objective、 canonical operation 与 scalar parameters 完整交给 Local EAIOS;未来 structured entity/constraint values 仍需新的版本化协议合同,不能由 RoleId 推导或静默扩展;
  • Task Satisfaction v0.2 已实现 source-aware State/Verifier evidence 与 receive-time freshness; 多源融合、负向 verdict recovery、物理目标争议和持续 verification 仍待后续版本;
  • Mission Request v0.3 已将结构化 DialogueTurn、revision-bound Review/Repair history 和 approval reasons 分离;更丰富的 channel/attachment 身份仍待真实产品需求;
  • Mission timing constraints 已与带 provenance/freshness 的 Scheduler duration estimate 分离; candidate-specific prediction profile 和 estimate refresh policy 仍待真实执行证据。

真机 Runtime 稳定基线 Gate

ADR-0028 已完成 Runtime reliability 的最小软件闭环。它不等于真机断电、网络分区、exactly-once physical action 或无人值守安全认证; 这些仍必须由 deployment/hardware evidence 和明确 safety policy 关闭:

ID 当前状态 验收边界
RT-G1 Durable dispatch 软件闭环已完成 Controller 在网络副作用前持久化 immutable dispatch intent;Node receipt 只证明 journal admission,restart ambiguity 不自动重放
RT-G2 Recovery closed loop 单 Role 和独立 Session 整组 retained-binding 软件切片已完成 单 Role 复用 Partial Release -> Match -> Propose -> Commit -> Rebind;ADR-0061 的整组 continuation 保留绑定并要求完整 stop proof。coupled/migrating joint recovery 与 physical-world fencing 仍未完成
RT-G3 Attempt identity 已完成 logical (GroupId, TaskRef, RoleId) 与 durable-generation physical attempt 分离;rebind 保留旧 attempt history
RT-G4 Durable cancellation 最小两阶段语义已完成 Mission Cancelling、per-attempt cancel intent、Node cancel-before-execute tombstone 与 terminal-evidence finalization 已持久化;远程安全 stop deadline/policy 仍属于 RT-G9
RT-G5 Timer and liveness driving 已完成 application timer 推进 lease/session expiry、recovery、cancel、Ready Task 与 outbox,失败时 fail-stop
RT-G6 Fault-injection evidence 离线确定性矩阵已完成 runtime-reliability-fault-matrix.md 覆盖 crash/restart/disconnect/duplicate/cancel/rebind;真机断电与真实网络分区证据仍缺失
RT-G7 Capability readiness 软件闭环已完成,真机证据待补 Node/WebUI process health 与 exact canonical capability readiness 分离;真实 ROS/EAIOS probe 仍需部署验证
RT-G8 Verification evidence 强类型链路已完成,field mapping 待真机验证 localization evidence 包含 active map identity、mode、pose quality、frame、current attempt/Node/session provenance;has_map=true 仅为 legacy smoke
RT-G9 Relation actuation 未完成 relation violation/unknown 在 progression fence 之外仍需版本化 pause/stop command、durable acknowledgement、deadline 与 completion race;Local Safety authority 不得被远程动作覆盖

RT-G7/RT-G8 的最小边界由 ADR-0019 已确定:RT-G7 复用 Node Protocol v0.4 的 RegistrationUpdate,其 v0.5 config、精确 contract readiness 和 后续 Matching 传播已实现。双狗配置和 Robonix adapter 已按历史现场证据接入 exact ROS service discovery probe,但仍需全新真机故障注入。RT-G8 已建立独立结构化合同、Node journal 持久化接口、Artifact transition 与 State projection;Node completion extraction 和真实 adapter mapping 仍未闭环。双狗验收条件见 scenarios/distributed-spatial-memory-v0.1/acceptance.md。

Node Service durable journal、本地幂等保护、Controller dispatch outbox、Runtime attempt history 和 Mission-level cancellation/recovery transaction 已分别落在各自 authority。后续实现仍不得把 Recovery Decision 下沉到 Runtime,也不得让 Integration 获得 execution lifecycle authority。

ADR-0020 建立 lifecycle-derived requires-active relation、Runtime live state、checkpoint 和 progression fence;ADR-0028 已关闭 其 RT-G3 attempt-identity 依赖,但不关闭 RT-G9。hazard/距离/速度等条件事实、relation composition 和硬实时 actuation 需要独立合同、 现场时序证据与安全决策,不能用自由字符串表达式提前固化。

历史 Bootstrap 提案

以下内容保留早期开发基线的上下文;已经被后续 ADR 和当前实现取代的条目不再表示开放决策。

  • 提议使用 Rust 实现 Domain、Control、Runtime 和 State 核心,Python 承载 Mission Intelligence、模型、仿真和研究型 Adapter;
  • 提议从模块化单体、内存 Port 实现和确定性 Fake Nodes 开始,不预先拆分微服务;
  • 提议让仿真与真实硬件通过 Adapter 接入,不作为核心框架开发的前置依赖;
  • 目标目录和依赖方向提案见 development/README.md;
  • 所有手写函数均需文档注释,质量门槛以 development/coding-standards.md 为准;
  • 语言职责决策由 ADR-0001 记录。
  • DEAIOS 与本地 EAIOS 的接入边界由 ADR-0002 记录。

这些提案仍在评审,不构成已接受的 MVP。即使被接受,也不冻结跨进程 Transport、序列化格式、数据库、调度算法或部署拓扑。

延后的实现选型

  • Capability Schema、Contract 字段、类型系统和版本兼容策略;
  • 节点接入的当前正式边界已由 ADR-0010、 ADR-0021 和 ADR-0022 固定为单一 roboguide-node、声明式 Local Integration Engine 与 deployment-owned Local EAIOS facade; Agent、SDK、Plugin、ROS Bridge 等仅是 facade 内部实现选择,不再是 RoboGuide core 的待决接入架构。
  • Control Plane 已有 ADR-0083 的 OpenRaft 静态三成员 loopback 软件 profile; 跨主机认证、动态 membership、policy/history 升级与物理高可用发布仍待决;
  • State / Belief / Memory 的数据库、缓存、事件总线和复制方式;
  • Observation 融合采用投票、滤波、因子图或其他方法;
  • Scheduler v0.2 已采用 deterministic bounded joint search,ADR-0082 已实现 Orchestration logical priority/fairness 和有界准入,ADR-0084 已实现显式 future planning preemption; 运行中物理抢占、真实 cost model、travel/traffic prediction、divisible quota、auction 或 RL policy 仍待独立设计/证据 gate;
  • Shared Resource Coordination 的时空图、Reservation 和冲突求解;
  • Messaging / Invocation 使用 DDS、Zenoh、gRPC、MQTT、WebRTC 或其他协议;
  • Memory 使用向量库、图数据库、关系库、对象存储或组合;
  • Benchmark、SLO、QoS、资源预测和成本函数;
  • 真实硬件的 Safety、权限、Heartbeat、Lease、超时和恢复验证。

决策规则

如果一个问题会改变模块职责、状态权威、Proposal / Commit 语义、Execution Group 定义或 Recovery 层级,它属于架构决策,必须先更新 V2 基线。若架构可以承载多种方案,则保留为实现选择,使用 MVP 和工程证据再决定。