# CMVR-ES 统一设备安全控制面架构设计 状态：Implemented in software；默认 Shadow rollout；真实硬件与发布验收待完成 修订：2026-08-14，具体认证实现延后，保留统一安全扩展边界并收紧匿名 Recover 暴露 范围：设备命令准入、控制权、StopAll、软件锁止恢复、gRPC 请求上下文与安全扩展边界、命令幂等、设备安全状态上报 实施方式：阶段 0 到阶段 5，共六个阶段 ## 当前实施状态（2026-08-14） 当前分支已经完成六阶段所需的软件骨架和主要入口迁移，但没有把“代码已具备能力”误写成 “生产安全验收已完成”。源码默认配置仍使用 `SHADOW`、`INSECURE + DISABLED` 和 `RECOVERY_DISABLED`；切换 `ENFORCE_SELECTED/ENFORCE_ALL` 或开放本机恢复前，必须先完成 对应设备和部署环境的验收。 | 阶段 | 当前状态 | 已落地内容 | 尚未完成 | | --- | --- | --- | --- | | 0 | 软件完成 | 统一 RequestContext、完整 method policy/call guard、anonymous principal、显式 Insecure/Disabled 配置、RecoveryExposure 和持久审计边界 | TLS、Token、JWT、mTLS provider 按本轮决策不实现 | | 1 | 软件完成 | safety types、SnapshotStore、设备 adapter、公共 reason/execution state、service instance、CommandLedger | 厂商结果语义仍需逐台真机校准 | | 2 | 软件完成 | DeviceManager 持有 SafetyManager、legacy participant、GetSafetyState、启动 coverage 校验、Shadow/Enforce 配置 | 真实运行 Shadow 日志评审 | | 3 | 软件完成 | Arm、ArmTeleop、AGV、Motor、DexHand、PTZ、ActionQueue 统一准入；dispatch 前 permit/final check；PTZ START/STOP 服务端派生 lane | 每类设备真实停车确认和 ACK/断网故障注入 | | 4 | 软件完成 | 通用 participant StopAll、RecoveryLedger、RecoverSafetyState、LocalOnly/Authorized policy、审计失败 fail-closed、shutdown quiesce | LocalOnly 现场入口和审计文件运维验收 | | 5 | 部分完成 | Camera/Microphone/Speaker/BioHead/HLC、TouchScreenTask、媒体 Hub/QUIC Sensor start 已迁移；Enforce 启动覆盖校验已实现 | 默认切换 EnforceAll、删除兼容 gate、capability manifest、安装产物 smoke、TSAN 和真机台架 | 认证和证书不是本次整改的运行前提。当前只实现无证书的兼容 Profile；配置选择尚未实现的 认证或 TLS 模式会启动失败，不会静默回退。匿名部署的恢复默认关闭，只有显式配置 `RECOVERY_LOCAL_ONLY`、服务端确认实际 peer 为 loopback/Unix socket 且持久审计可写时才可开放。 AUBO 另有一条设备内硬件语义：真实硬件急停曾有效、随后输入消失且控制器重新报告 `Normal/ReducedMode` 时，驱动会自动上电到 `Idle`、清理旧队列、执行 `startup()`，并在 `Running` 下再次确认 quiescent 后解除该硬件锁存，使新的 gRPC 指令可以重新准入； 软件 `emergencyStop()` 使用独立 `SoftwareEmergencyStop` 锁存，即使它与硬件急停重叠也绝不被 硬件输入释放自动清除。自动流程不 resume、不重放旧目标；显式 Stop/PowerOff 会取消本轮自动上电。 ## 1. 决策摘要 本设计采用以下核心决策： 1. `DeviceManager` 继续负责设备注册和生命周期，并持有一个独立、可测试的 `SafetyManager`。状态机代码不直接堆入 `DeviceManager`。 2. Service 不再自行组合 StopAll gate、设备状态和控制权判断。所有会改变设备或 活动状态的命令必须声明 `CommandIntent`，通过统一准入获得短生命周期的 `AdmissionPermit`。 3. 设备层不把厂商硬件规则上移。设备或设备适配器持续发布硬件事实，并在真正下发 命令前执行最后一次硬件安全检查。 4. 生命周期、健康状态和安全状态保持正交。`Running`、`Healthy` 都不等于当前可以 接受执行器命令。 5. 策略分为 `SensorPolicy` 和 `ControlPolicy` 两个默认族，但最终按命令意图判定。 DexHand、Camera PTZ 等混合设备不能只按整个设备归类。 6. Stop、状态查询和安全恢复使用独立安全通道，不受普通命令 gate 阻塞。 7. 对外接口命名为 `RecoverSafetyState`。它只在重新验证硬件事实后清除软件准入锁止， 不能忽略急停、保护停、未知状态或仍未确认的运动。 8. 普通 unary 控制命令使用统一幂等账本；流式控制使用 session epoch 和严格递增的 sequence。任何 `OUTCOME_UNKNOWN` 都不得自动重发。 9. 当前小范围部署不把 TLS、Token、mTLS 等具体认证实现作为设备安全架构的前置条件， 但阶段 0 必须先建立统一 `RequestContext`、认证提供者、授权策略和审计扩展边界。 10. 认证关闭时由服务端注入固定的 `anonymous` principal，不能接受客户端自报身份或角色； `RecoverSafetyState` 默认禁用，只有本机受限模式可以显式开放。 11. 传输加密、身份认证和方法授权是三个正交层。后续增加静态 Token、JWT 或 mTLS 时， 只能替换安全网关组件，不修改设备、`SafetyManager` 或业务 Proto。 12. 该软件控制面不替代独立物理急停，也不声明 SIL、PL 或其他功能安全等级。 ## 2. 改造前基础与需要保留的行为 项目已有一些经过并发测试的能力，应当迁移和复用，而不是重新实现： | 当前能力 | 目标用法 | | --- | --- | | `ControlAuthorityManager` 的 lease、generation、dispatch fence、quarantine | 作为 `SafetyManager` 内部控制权组件 | | `StopAllAdmissionGate` 的并发 round 和失败后 fail-closed | 作为阶段 2、3 的兼容参与者，最终由统一状态机接管 | | `ActionQueueExecutor` 的 `action_id`、service instance 和精确 retired ID 账本 | 作为普通命令幂等账本的语义模板 | | Motor、Media、Camera activity coordinator | 先包装为 `SafetyParticipant`，最后逐步合并 | | `StopOperationDispatcher` 的有界异步停止和生命周期管理 | 作为统一 StopAll 执行器的基础 | | `DeviceManager::inventorySnapshot()` | StopAll 枚举设备时继续使用，禁止持锁进入驱动 | | `Runtime` 的启动失败回滚和退出时 Task/Device 停止 | 保留，并在退出前增加全局安全准入关闭 | 整改开始时的主要缺口是： - gRPC 默认全网卡明文监听，没有认证和授权；当前阶段可以接受该部署风险，但必须通过显式配置、 网络隔离和恢复接口限制控制暴露范围； - 普通控制 RPC 缺少 `command_id` 和统一重试语义； - StopAll 在 `grpc_system_service.cpp` 内按设备类型硬编码； - Arm、AGV、Motor、Media、ActionQueue 分别维护 gate 和 generation； - 只有少数设备实现 `healthSnapshot()`，且健康状态不能表示硬件安全事实； - `DeviceManager::snapshot()` 仍会在调用线程逐个调用设备方法； - 普通 service 直接取得设备并调用驱动，无法保证所有入口都经过同一准入； - Aubo 等驱动存在“硬件可能已接受，但软件未观察到执行 ID”的不确定结果窗口； - 错误类型没有统一映射，客户端容易对不应重试的命令进行重试。 当前实现锚点： - gRPC 监听和 credentials：`cmvr-es/task/grpc_server_task/src/grpc_server_task.cpp`； - SystemService StopAll：`cmvr-es/service/grpc/server/src/grpc_system_service.cpp`； - 全局 gate：`cmvr-es/service/grpc/stop_all/include/stop_all_admission_gate.h`； - 控制权：`cmvr-es/manager/control_authority_manager/include/control_authority_manager.h`； - 设备生命周期和快照：`cmvr-es/manager/device_manager/`； - 通用请求头：`protos/cmvr/api/common.proto`； - System API：`protos/cmvr/api/system_service.proto` 和 `system_command.proto`。 ## 3. 目标、非目标与安全不变量 ### 3.1 目标 - 所有 gRPC、ActionQueue、Teleoperation 和未来 QUIC 控制入口共享同一安全准入。 - 新增设备时，安全层只要求注册能力和策略，不修改 StopAll 或 SystemService 主流程。 - 单个驱动、网络或状态刷新阻塞不能拖住其他设备的 Stop、Status 或 Recover。 - StopAll、设备级不确定结果和进程重启都能通过 generation 使旧命令永久失效。 - 锁止原因、状态新鲜度、阻塞设备和恢复结果能够被机器读取和审计。 - 迁移期间保持现有 API wire compatibility，并允许按设备逐步启用 enforce。 - 具体认证实现延后时，所有请求仍经过稳定的安全上下文边界；未来启用认证不需要改动 Service 业务分支、状态机、驱动接口或业务 Proto。 ### 3.2 非目标 - 不把厂商协议、关节限制、工作空间或设备专用故障码搬入 `DeviceManager`。 - 不允许远程接口绕过真实硬件急停或保护停。 - 不保证所有设备在一个阶段内同时完成迁移。 - 不用软件 StopAll 替代机器人、PLC、驱动器或安全控制器的独立安全回路。 - 不在本设计中实现运行期卸载设备插件；只消除安全协调器中的设备类型硬编码。 - 首轮六阶段实施不要求交付证书、静态 Token、JWT 或 mTLS；这些能力作为独立的后续安全加固项。 ### 3.3 必须始终成立的不变量 1. `Stop`、`Status`、`GetSafetyState` 和 `RecoverSafetyState` 不依赖普通准入为 OPEN。 2. 一次 StopAll 开始后，旧 epoch 的命令不能再进入设备下发点。 3. StopAll 与正常命令竞态时，命令只能是“未下发”或“已被登记并纳入停止”，不能存在 未登记的第三种状态。 4. 状态过期、设备失联、安全能力缺失对控制命令一律 fail-closed。 5. 同一 effective principal 的同一 `command_id` 最多触发一次硬件提交；认证关闭时所有调用者 共享服务端生成的 `anonymous` principal，因此 command ID 必须在整个匿名部署内唯一。 6. 相同 ID、不同语义 payload 必须返回冲突，不能覆盖旧记录。 7. 硬件结果不确定时保存 `OUTCOME_UNKNOWN`，重试只能查询该结果，不能再次下发。 8. 通用 `RecoverSafetyState` 成功只表示软件准入可重新评估，不表示设备被上电、使能、 解除急停或自动运动。AUBO 物理急停释放后的自动上电是独立、显式配置的设备内策略。 9. `SafetyManager` 持有内部锁时不得调用设备、网络或可能阻塞的 participant 方法。 10. 驱动最终安全检查失败时，即使已经获得 permit，也不能下发设备命令。 11. 进程重启后，控制设备在新鲜状态确认完成前不能自动恢复到可控制状态。 12. 所有安全状态转换都增加 epoch、产生事件，并记录明确 reason code。 13. 匿名网络调用不能执行 `RecoverSafetyState`；认证关闭时只能显式禁用恢复，或仅允许 服务端判定为 loopback/Unix Domain Socket 的本机调用。该限制不能由请求字段覆盖。 ## 4. 统一概念模型 ### 4.1 三个互不替代的状态维度 | 维度 | 说明 | 示例 | | --- | --- | --- | | Lifecycle | 进程对设备对象的生命周期管理 | Initializing、Running、Stopped、Error | | Health | 设备是否正常工作和是否存在故障 | Healthy、Degraded、Fault、Unknown | | Safety | 当前事实是否足以接受某一类命令 | Nominal、Restricted、Unsafe、Unknown | `Lifecycle=Running` 只说明设备 worker 已启动；`Health=Healthy` 只说明没有已知故障； 两者都不能替代 Safety 中的状态新鲜度、急停、运动、使能和代际信息。 ### 4.2 命令意图 ```cpp enum class CommandIntent { Observe, // 只读状态、图像、传感数据 StartActivity, // 启动采集、录制、播放等非运动活动 Configure, // 修改参数、地图、非安全 IO 等 Actuate, // 运动、速度、力、位置、使能、扭矩输出 Stop, // 停车、取消、torque-off、停止活动 ResetFault, // 设备级、不会自动产生运动的故障复位 RecoverAdmission, // 系统级软件锁止恢复 }; ``` 每个 handler 必须在代码中声明固定意图。客户端不能通过请求字段自行选择意图。 ### 4.3 两个默认策略族 ```cpp enum class SafetyPolicyFamily { Sensor, Control, }; ``` - `Sensor` 表示非运动型采集或外围活动，不要求它在字面上一定是传感器。Camera、 Microphone、Battery、普通 Speaker activity 可使用该策略。 - `Control` 表示能够导致位置、速度、力、扭矩或机械结构变化的能力。Arm、AGV、Motor、 DexHand 动作、Camera PTZ、BioHead 表情和仿真执行器使用该策略。 - 混合设备按命令选择策略。例如 Camera 图像流是 Sensor，PTZ START 是 Control， PTZ STOP 是 Stop。 ### 4.4 硬件事实使用三值逻辑 安全事实不能把“未实现”解释为 false： ```cpp enum class TriState { Unknown, False, True }; enum class SafetyCondition { Nominal, // 已知正常，可继续按具体命令规则判断 Restricted, // 已知静止或受硬件抑制，但不满足普通执行条件 Unsafe, // 已观察到不允许继续控制的状态 Unknown, // 缺失、过期、失联或无法解释 }; ``` 推荐的进程内快照： ```cpp struct DeviceSafetySnapshot { std::string device_id; SafetyCondition condition{SafetyCondition::Unknown}; std::uint64_t device_generation{0}; std::uint64_t sample_sequence{0}; std::chrono::steady_clock::time_point observed_at; std::uint64_t observed_at_unix_ms{0}; TriState connected{TriState::Unknown}; TriState operational_ready{TriState::Unknown}; TriState quiescent{TriState::Unknown}; TriState motion_active{TriState::Unknown}; TriState actuator_enabled{TriState::Unknown}; TriState emergency_stop_active{TriState::Unknown}; TriState protective_stop_active{TriState::Unknown}; TriState fault_active{TriState::Unknown}; std::vector blockers; }; ``` `SafetyBlocker` 必须包含稳定 reason、来源和作用域： ```cpp enum class BlockerScope { Device, System }; enum class RecoveryRequirement { RefreshOnly, ClearSoftwareLatch, HardwareReleaseRequired, ManualInspectionRequired, }; struct SafetyBlocker { SafetyReason reason; BlockerScope scope; RecoveryRequirement recovery_requirement; std::string source_id; std::string operation_id; }; ``` 设备本地急停可以只阻塞该设备；连接到整机安全链的急停必须发布 `System` scope，并阻止 全局准入恢复。作用域由经过评审的设备/安全链 adapter 固定，不能由客户端或普通配置修改。 安全判断使用本机 monotonic age。UTC 只用于日志和跨系统诊断，不能参与准入时序。 `device_generation` 在以下情况增加： - 设备后端重新初始化； - SDK、总线或网络 session 重连； - 驱动状态机执行需要使旧命令失效的 reset； - 设备被重新注册。 ## 5. 目标架构与所有权 ```mermaid flowchart LR Client["gRPC / QUIC / Local Task"] --> Gateway["Request Context Gateway
限制 可选认证 授权策略 审计"] Gateway --> Adapter["Typed Service Adapter
声明 CommandIntent"] Adapter --> Ledger["CommandLedger
幂等和结果"] Adapter --> Coordinator["DeviceManager::SafetyManager"] Coordinator --> Policy["SensorPolicy / ControlPolicy"] Coordinator --> Authority["ControlAuthorityManager"] Coordinator --> Participants["SafetyParticipant Registry"] Coordinator --> Cache["SafetySnapshotStore"] Coordinator --> Permit["AdmissionPermit"] Permit --> Driver["DeviceSafetyEndpoint + Driver"] Driver --> Cache StopRecover["StopAll / Recover 安全通道"] --> Coordinator ``` ### 5.1 建议目录 ```text cmvr-es/manager/safety_manager/ include/safety_types.h include/safety_reason.h include/device_safety_endpoint.h include/safety_participant.h include/safety_snapshot_store.h include/command_admission_controller.h include/command_ledger.h include/safety_operation_orchestrator.h include/safety_manager.h src/... tests/... cmvr-es/service/grpc/security/ include/grpc_request_context.h include/grpc_authentication_provider.h include/grpc_authorization_policy.h include/grpc_method_policy_registry.h include/grpc_security_interceptor.h src/... tests/... ``` 新增 CMake target：`cmvr_es::safety_manager`。它可以依赖通用类型和 `ControlAuthorityManager`，但不能依赖 gRPC、具体设备后端或厂商 SDK。 ### 5.2 `DeviceManager` 的职责变化 `DeviceManager` 增加： ```cpp SafetyManager& safetyManager() noexcept; const SafetyManager& safetyManager() const noexcept; ``` 它负责： - 在设备创建后注册设备描述、Safety endpoint 和快照槽位； - 在设备销毁前注销 participant； - 在 lifecycle start/stop/restart 时推进 device generation； - 在 Runtime shutdown 开始时先关闭全局准入； - 对外提供纯内存的 Manager + Safety 联合快照。 它不负责： - 解析 Aubo、Huayan、SEER、Modbus 等厂商状态； - 根据 `DeviceKind` 写具体停止逻辑； - 在 Manager mutex 下执行硬件 I/O； - 判断具体运动目标是否超限。 ### 5.3 依赖注入 最终状态下，gRPC service 构造函数显式接收： ```cpp DeviceManager& SafetyManager& CommandLedger& GrpcSecurityGateway& ``` 每个 handler 通过一个统一 call guard 取得不可变 `RequestContext`。认证 metadata 的解析、 peer 归一化、角色生成和恢复接口暴露检查只存在于 `GrpcSecurityGateway`；业务 Service 不直接 解析 metadata，也不从 request message 读取 principal 或 role。具体实现可以由 interceptor 完成前置检查，再由 call guard 取得同一次调用的上下文，但不能依赖 thread-local 传递上下文。 阶段 2 可以保留无参构造函数作为兼容入口，但它只能转发到上述依赖。阶段 5 删除业务 代码对进程级 safety singleton 的直接访问。测试使用独立 coordinator，不再依赖 `clearForTesting()` 清理全局状态。 ### 5.4 管理面与设备运行面分离 “Stop/Status/Recover 始终可达”不仅要求它们绕过普通 gate，也要求单个设备初始化失败时 gRPC 管理面仍能启动。目标 Runtime 启动顺序为： ```text load config and logging -> construct DeviceManager core and SafetyManager -> validate selected gRPC security profile and start management-plane services -> initialize/start devices -> reconcile required control snapshots -> start operational tasks -> Open with device-level Blocked, or global Latched ``` - 配置损坏、所选安全 Profile 的身份材料无效或 SafetyManager 核心构造失败仍使进程启动失败； - `AuthenticationMode::Disabled` 是显式兼容模式，不伪装成“已认证”；如果使用非 loopback 明文监听，启动日志、GetSystemInfo 和指标必须持续暴露该风险； - 单个设备 create/init/start 失败记录在 inventory，并使相关资源 Blocked； - Device scope 的动态 Unknown/Unsafe 使相关资源 Blocked，System scope blocker 使全局 Latched， 两者都不停止 SystemService； - 普通设备 service 可以继续注册，访问失败设备时返回结构化 DEVICE_UNAVAILABLE； - TaskManager 需要区分 ManagementPlane 和 Operational task，后者失败不能回滚前者； - 物理急停和本机停机手段始终独立于该网络管理面。 在完成该拆分前，“始终可达”只保证 gRPC server 已成功运行期间的行为，不能覆盖当前 Runtime 在任一 required device 启动失败时直接退出的情况。 ## 6. 快照发布与线程模型 ### 6.1 发布模型 正常准入和状态查询只能读取 `SafetySnapshotStore`，不能同步查询驱动。 ```text driver callback / polling worker | v DeviceSafetyEndpoint normalizes vendor facts | v SafetySnapshotPublisher::publish(value) | v SafetySnapshotStore atomic value slot ``` 现有设备可以先通过独立 adapter worker 拉取状态；新设备应优先在自己的 SDK callback 或 状态轮询线程中发布。Manager heartbeat、gRPC Status 和准入只复制值。 现有 `healthSnapshot()` 在迁移期只能由 DeviceMonitor 后台 worker 调用，并使用每设备隔离和 超时；不能继续由 `DeviceManager::snapshot()` 的调用线程执行。目标状态是设备同时发布缓存的 Health 和 Safety，两者仍保持独立字段。 ### 6.2 Freshness 每个 `DeviceSafetyDescriptor` 声明默认最大状态年龄。配置只允许将阈值收紧，不能在生产模式下 放宽超过代码定义的硬上限。 - Sensor Observe 可在业务允许时返回带 `stale=true` 的历史值； - Sensor StartActivity 在 Missing/Stale 时拒绝； - Control Actuate、Configure 和 ResetFault 在 Missing/Stale 时拒绝； - Stop 不因状态过期而拒绝，仍直接尝试安全停止； - Recover 必须获得一个晚于本次 refresh request 的新样本。 ### 6.3 主动刷新 `RecoverSafetyState` 需要主动复核，但仍不在 gRPC 线程直接做设备 I/O： 1. 记录当前 `sample_sequence`； 2. 调用 endpoint 的非阻塞 `requestSafetyRefresh()`； 3. 在专用 recovery executor 等待 sequence 增加； 4. 超时则产生 `SAFETY_STATE_STALE` blocker，保持锁止。 ### 6.4 锁和执行器约束 - Coordinator 锁只保护状态转换、epoch、slot 和 participant registry； - Snapshot slot 使用原子 shared snapshot 或短持有独立 mutex； - `beginDispatch()` 只建立 fence 和 in-flight 计数，不等待物理运动结束； - 设备调用、停止和刷新均在锁外执行； - Stop/Recover 使用有界 worker pool，不为每次调用创建 detached thread； - 每个 legacy health probe 最多允许一个 in-flight worker，卡住后只标记 stale，不重复创建线程； - participant 注销前必须等待自己的 callback 和 stop handle 退出。 ## 7. 状态机 ### 7.1 系统准入状态 ```mermaid stateDiagram-v2 [*] --> Starting Starting --> Open: required snapshots reconciled Starting --> Latched: unknown active control or startup failure Open --> Stopping: StopAll Stopping --> Open: all participants quiescent Stopping --> Latched: timeout or unconfirmed stop Latched --> Recovering: authorized recovery Recovering --> Open: every required latch cleared Recovering --> Latched: blocker remains Starting --> ShuttingDown: shutdown Open --> ShuttingDown: shutdown Stopping --> ShuttingDown: shutdown Latched --> ShuttingDown: shutdown Recovering --> ShuttingDown: shutdown ``` 每次进入 `Stopping`、`Latched`、`Recovering` 或 `ShuttingDown` 都增加 `safety_epoch`。 ### 7.2 设备准入状态 ```cpp enum class DeviceAdmissionState { Observing, // 已注册，等待第一份有效快照 Open, Blocked, // 确定的硬件或生命周期条件不满足 Quarantined, // 命令或停止结果不确定，需要人工恢复流程 Recovering, Removed, }; ``` - `Blocked` 可以在新鲜硬件事实改善后自动回到 Open，例如设备故障被合法清除； - `Quarantined` 不能仅靠一份健康快照自动清除，必须经过 recovery transaction； - 一个普通设备命令的结果不确定时，默认只 quarantine 对应 control resource； - StopAll 无法确认全部参与者时，全局状态进入 Latched。 ### 7.3 命令生命周期 ```text RECEIVED -> RESERVED -> REJECTED_BEFORE_DISPATCH -> ADMITTED -> DISPATCHING -> ACCEPTED_BY_HARDWARE -> COMPLETED | FAILED | CANCELED | OUTCOME_UNKNOWN ``` `ACCEPTED_BY_HARDWARE` 的含义必须由每个 adapter 明确定义。SDK 返回码、queue ID、任务 ID、 ACK 或写入总线分别可能具有不同强度，不能统一解释成“运动完成”。 ## 8. 命令准入算法 ### 8.1 普通 unary 控制命令 1. Request Context Gateway 完成大小限制、correlation ID、上下文构造和授权策略检查；只有 当前 Profile 启用 AuthN 时才执行身份认证。 2. 解析 `command_id`、service instance、device generation 和本地有效期。 3. CommandLedger 按 effective principal 预留 ID，并计算语义 payload hash；Disabled 模式使用 服务端固定的 `anonymous` namespace。 4. 若存在同 ID 记录：相同 hash 返回/等待原结果；不同 hash 返回冲突。 5. Service 使用固定 `CommandDescriptor` 调用 `SafetyManager::admit()`。 6. Coordinator 在短锁内读取 global state、safety epoch、device slot 和 cached snapshot。 7. Policy 判断意图、freshness、硬件事实、设备状态和调用角色。 8. Control intent 获取或校验 `ControlAuthorityManager` lease。 9. 返回 move-only `AdmissionPermit`，其中固定所有 generation 和 deadline。 10. Service 调用 `beginDispatch(permit)`。这里是 StopAll 与命令提交的线性化点。 11. 驱动在自己的串行化上下文中执行最终硬件检查。 12. 通过检查后调用 SDK，并把结果写入 ledger；失败或异常也必须终结 ledger 记录。 `AdmissionPermit` 至少包含： ```cpp struct AdmissionPermit { std::string command_id; std::string device_id; CommandIntent intent; std::uint64_t safety_epoch; std::uint64_t device_generation; std::uint64_t authority_generation; std::chrono::steady_clock::time_point deadline; }; ``` ### 8.2 Stop 与 ResetFault - Stop 走安全通道，不需要普通 permit，也不受全局 Latched 阻塞； - Stop 仍需经过 RequestContext、当前 Profile 的访问策略、参数校验、超时和审计；认证关闭时 不额外拒绝 Stop，因为停止能力必须保持可达； - Stop 不因 expected service instance、device generation 或 safety epoch 过期而拒绝；这些字段 对 Stop 仅用于诊断，因为安全停止必须优先于防重放限制； - 重复 Stop 应加入当前 stop operation 或执行幂等停止，不能因为缺少 command ID 而拒绝； - ResetFault 可在 Latched 下执行，但必须声明为不会上电、使能或恢复运动； - 如果某厂商的 clear-fault 同时会 resume、enable 或移动，必须拆成两个 typed 操作， 不能把它登记成 ResetFault； - ResetFault 成功只触发安全快照刷新，不直接清除 central quarantine。 ### 8.2.1 整机运行态恢复 `SystemService.RestoreOperationalState` 是面向上层平台的整机恢复事务，与 `RecoverSafetyState` 的软件准入恢复语义分离： - 请求必须携带唯一 `recovery_id`、非空 `reason`，并通过与 Recover 相同的 `RecoveryExposure` 和持久审计策略； - 事务固定覆盖全部已注册设备，并与 StopAll、其他恢复事务通过 process operation mutex 串行；事务期间系统处于 Recovering，拒绝新的普通运动命令； - 硬件恢复前必须主动取得新鲜快照，确认设备已连接；Control 设备还必须确认物理急停已释放 且已经静止。条件未知、急停仍有效、设备仍运动或审计授权失败时，不调用设备恢复能力； - 对尚未达到 Nominal/operational-ready 的支持设备调用 `DeviceSafetyEndpoint::restoreOperationalState()`。Legacy Arm 和 AGV adapter 分别调用设备 `clearFault()`；该操作允许按设备实现执行上电、使能和故障复位，但不得恢复旧轨迹、导航、 teleop session、control lease 或 ActionQueue； - 每个硬件恢复动作完成后必须再次主动刷新，确认连接、新鲜度、急停、保护停、fault、静止和 operational-ready。任一设备失败时系统保持 Latched，并返回逐设备失败原因；中央 quarantine、 retained barrier 和全局 gate 不做部分释放； - 只有全部必需设备验证成功后，才协调释放软件 latch 和 retained barrier，将系统切回 Open。 调用成功只表示整机已使能、空闲并可接受新的 gRPC 命令，不会续跑中断前的任务。 ### 8.3 流式控制 Teleoperation、Motor cyclic stream 和未来连续控制不为每个 setpoint 写 unary ledger： 1. OPEN frame 生成 `control_session_id`，绑定 service instance、device generation、 safety epoch 和 control lease； 2. setpoint sequence 必须严格递增，且带本地可解释的 `valid_for`； 3. 每个 setpoint 下发前轻量校验 session epoch、permit epoch、watchdog 和快照 freshness； 4. StopAll 或 Recover 增加 epoch 后，旧 stream 立即进入 HOLD/STOP，不可自动续接； 5. reconnect 必须创建新 session，不能恢复旧 ACTIVE 状态； 6. stream 结束、write/read 失败和 watchdog 均执行可验证的安全停止。 ### 8.4 ActionQueue - 保留现有 ActionQueue `action_id` 和 service instance； - 预校验阶段确认所有 step 已分类，但不提前获取可长期持有的 permit； - 每个 step 真正开始前重新准入并取得当前 epoch 的 permit； - step 的内部 command ID 由 `action_id + step_id` 确定性派生，不能要求嵌套请求再提供一个 可与 action 身份冲突的独立 ID； - StopAll 仍能抢占队列和活动 step； - 迁移完成后 ActionQueue 不再拥有独立的普通准入 generation，只保留队列执行 generation； - 队列结果和单步 CommandLedger 记录使用关联 ID，但不得造成一次 step 两套独立重试语义。 ## 9. 策略矩阵 ### 9.1 SensorPolicy | Intent | Global Latched | Snapshot 要求 | 默认结果 | | --- | --- | --- | --- | | Observe | 允许 | 可返回 stale 标记；不能伪造为 fresh | Allow | | StartActivity | 拒绝或按设备 Blocked | connected、fresh、无已知 fault | Conditional | | Configure | 拒绝 | connected、fresh、配置操作已分类 | Conditional | | Stop | 允许 | 不要求 fresh | Allow safety lane | | ResetFault | 仅明确支持的设备 | fresh，且操作不会启动活动 | Conditional | | RecoverAdmission | SafetyAdmin only | fresh sample required | Safety lane | ### 9.2 ControlPolicy | Intent | 必要条件 | | --- | --- | | Observe | 始终允许读取缓存；返回 freshness 和 blocker | | Configure | 全局 Open、设备非 Quarantined、fresh、命令不会隐式 Actuate | | Actuate | 全局 Open、设备 Open、condition=Nominal、fresh、generation 匹配、lease 有效、deadline 有效、最终硬件检查通过 | | Stop | 无条件进入安全通道；状态未知仍尝试 stop | | ResetFault | 允许在 Blocked/Latched 下执行，但只允许非使能、非运动的 typed reset | | RecoverAdmission | SafetyAdmin、expected epoch 匹配、主动刷新完成、quiescent=true、没有未知 stop worker | `emergency_stop_active=true` 或 `protective_stop_active=true` 可以表示设备被硬件抑制且物理上 静止，但不能被 Recover 清除。Device scope blocker 继续阻止该设备 Actuate；System scope blocker 继续保持全局 Latched。只有硬件被合法处理并发布新的事实后，恢复事务才可清理对应 软件 latch。 ## 10. 设备安全能力接口 ### 10.1 描述与注册 ```cpp struct DeviceSafetyDescriptor { std::string device_id; DeviceKind kind; SafetyPolicyFamily default_policy; std::chrono::milliseconds maximum_snapshot_age; bool requires_safe_stop; bool supports_active_refresh; bool supports_non_enabling_fault_reset; }; struct DeviceSafetyRegistration { DeviceSafetyDescriptor descriptor; std::shared_ptr endpoint; std::shared_ptr participant; }; ``` 控制设备在 enforce 模式下缺少 endpoint、fresh snapshot 或 safe-stop participant 时： - 启动阶段标记设备 safety capability invalid； - 设备可以继续出现在 inventory 和诊断接口中； - 所有 Actuate 命令拒绝； - 配置要求严格启动时，可以直接使 Runtime 初始化失败。 新增全新 DeviceKind 仍可能需要修改现有 DeviceFactory、配置 Proto 和对外业务 API；本设计 保证的是不再修改 SafetyManager、StopAll 和 Recover 的设备类型分支。 ### 10.2 Endpoint ```cpp class DeviceSafetyEndpoint { public: virtual ~DeviceSafetyEndpoint() = default; virtual DeviceSafetyDescriptor descriptor() const = 0; virtual void bindPublisher(SafetySnapshotPublisher publisher) = 0; virtual void requestSafetyRefresh() noexcept = 0; // 在驱动自己的串行化上下文内执行。不得更改设备状态。 virtual HardwareCheckResult validateBeforeDispatch( const AdmissionPermit&) = 0; // 只协调驱动内部软件状态，不得上电、使能或启动运动。 virtual RecoveryCheckResult reconcileAdmissionState( const RecoveryContext&) = 0; }; ``` 如果最终检查需要厂商 I/O，它必须有设备级 deadline，并在驱动 executor 中执行；Manager 不持锁等待。超时返回 Unknown，不允许继续下发。 ### 10.3 Safe-stop participant ```cpp class SafetyParticipant { public: virtual ParticipantDescriptor descriptor() const = 0; // 纯内存、快速关闭本 participant 的新工作准入。 virtual BarrierToken beginBarrier(const SafetyOperationContext&) = 0; // 非阻塞提交停止，返回可等待 handle。 virtual StopHandle requestQuiesce( const BarrierToken&, const SafetyOperationContext&) = 0; // 验证“旧 generation 不会继续、当前输出已静止”。 virtual QuiescenceResult verifyQuiescent( const BarrierToken&, const SafetyOperationContext&) = 0; // 只清理软件 gate、retired holder 或内部 session。 virtual RecoveryCheckResult recoverAdmission( const BarrierToken&, const RecoveryContext&) = 0; virtual void releaseBarrier(const BarrierToken&) noexcept = 0; }; ``` participant 可以代表设备，也可以代表 ActionQueue、MediaSourceManager、Motor session registry 等 跨设备活动域。StopAll 不再知道具体 C++ 设备类型。 ## 11. CommandLedger 与结果语义 ### 11.1 Key 和 payload hash 推荐 key：`(effective_principal_id, command_id)`。 `effective_principal_id` 只能由服务端安全网关产生：认证启用时取认证结果中的稳定 principal ID； 认证关闭时固定为 `anonymous`。不能使用 request、普通 metadata 中自报的 client ID，也不使用 易变化的 TCP source port。匿名模式因此要求 command ID 在整个部署内全局唯一。 payload hash 包含： - 完整 gRPC method 名； - device/resource ID； - deterministic protobuf semantic payload； - expected service instance 和 device generation； - 不包含诊断 timestamp、认证 metadata 和 command ID 本身。 同一 effective principal 内 command ID 必须全局唯一。不同 method 复用同一 ID 会因 hash 不同而冲突。 ### 11.2 记录内容 ```cpp struct CommandRecord { CommandKey key; PayloadHash payload_hash; CommandLifecycle lifecycle; CommandOutcome outcome; std::uint64_t safety_epoch; std::uint64_t device_generation; bool hardware_submission_possible; steady_clock::time_point accepted_at; steady_clock::time_point terminal_at; }; ``` - In-flight 和近期 terminal 结果保留完整响应； - 淘汰完整结果后保留精确 retired-ID tombstone； - 达到硬容量后拒绝新 ID，不淘汰仍可能被重放的 tombstone； - 账本耗尽使用 `RESOURCE_EXHAUSTED/LEDGER_EXHAUSTED`，不能降级成无幂等执行； - 进程内账本不要求落盘，但客户端必须携带 expected service instance； - 进程重启后旧 instance 请求拒绝，控制设备先完成 startup reconciliation 才可 Open。 ### 11.3 RPC 取消 - 在 RESERVED/ADMITTED 且未 dispatch 时取消：终结为 `CANCELED_BEFORE_DISPATCH`； - 硬件已接受后客户端断开：不能假设命令取消，继续记录实际结果； - 需要“断线即停”的命令必须显式使用 session/watchdog 协议； - retry 相同 ID 只能加入原执行或读取原结果。 ## 12. StopAll 统一事务 ### 12.1 Participant 分组 建议固定阶段而非依赖注册顺序： 1. `Ingress`：关闭 gRPC/QUIC/local task 普通准入； 2. `Scheduler`：取消 ActionQueue 和待执行作业； 3. `ControlSession`：撤销 teleop、motor cyclic、velocity 等连续控制 session； 4. `Actuator`：Arm、AGV、Motor、DexHand、PTZ、BioHead 请求安全停止； 5. `PeripheralActivity`：Camera、Microphone、Speaker、recording 和媒体 producer； 6. `Verification`：等待每个 required participant 的 quiescence 证明。 组内可以并行，组间顺序固定。每个 participant 有独立 timeout，外层还有总 deadline。 ### 12.2 算法 1. 使用 process-wide operation mutex 创建或加入当前 StopAll round； 2. 状态设为 Stopping，增加 safety epoch，关闭全局准入； 3. 对当前 participant registry 建立不可变快照； 4. 对所有 participant 调用 `beginBarrier()`； 5. 撤销普通 control lease，并等待已进入 dispatch fence 的短提交退出； 6. 分阶段提交 `requestQuiesce()`； 7. 等待 handle，并调用 `verifyQuiescent()`； 8. 任一 required participant 超时、异常或 Unknown：保留其 barrier，记录 blocker，进入 Latched； 9. 全部成功：清理旧 retired holders，释放本轮 barrier，状态回到 Open； 10. 返回结构化 per-participant 结果和新 epoch。 多个 StopAll 调用加入同一 round，并各自得到同一最终结果。RPC waiter 取消不能取消已经开始的 系统停止事务。 成功 StopAll 是一个“已经在本轮确认全部静止”的同步屏障，不是持续维护锁。状态回到 Open 后， 其他通过当前访问策略的客户端可以提交新命令，甚至可能在 StopAll 调用方收到响应前完成准入。需要长期禁止 控制时应设计独立的 maintenance lock，不复用 StopAll 或 Recover 语义。 ### 12.3 迟到结果 - 旧 round 的 worker 完成后只允许更新该 round 的诊断记录； - worker 不能凭旧 token 重新打开准入； - participant 的 release 必须验证 operation ID 和 epoch； - worker 仍运行时 participant 保持 blocker，Recover 不得跳过它。 ## 13. RecoverSafetyState 事务 ### 13.1 语义边界 `RecoverSafetyState` 的准确含义是： > 在独立安全通道中重新确认设备和活动域已经静止，并清除由软件 StopAll、超时、取消、 > 旧 session 或不确定结果留下的准入锁止。 它不执行： - 解除物理急停； - 自动解除保护停； - torque-on、power-on、brake-release； - 自动继续旧轨迹、导航、ActionQueue 或 teleop session； - 把 Unknown 解释为 Safe； - 调用测试接口 `clearForTesting()`。 ### 13.2 恢复算法 1. Request Context Gateway 先执行恢复暴露策略：认证模式要求 `SafetyAdmin`；认证关闭时默认 禁用，只有 `LOCAL_ONLY` 且服务端确认 peer 为 loopback/Unix Domain Socket 才允许继续； 随后校验 `recovery_id`、scope、reason 和 deadline； 2. RecoveryLedger 对 `recovery_id` 做幂等处理； 3. 与 StopAll 串行化；expected safety epoch 不匹配立即拒绝； 4. 状态转为 Recovering 并增加 epoch，使所有旧 permit/session 失效； 5. 选取 scope 内处于 Blocked/Quarantined 的 device 和 subsystem participant； 6. 确认没有旧 stop worker、dispatch fence 或 active command 仍未退出； 7. 对设备发起 active refresh，等待晚于本次请求的新 snapshot； 8. 控制设备要求 `quiescent=true`，且 condition 不能是 Unsafe/Unknown；任何 System scope hardware blocker 都保持全局锁止； 9. 调用 endpoint/participant 的非使能 `reconcileAdmissionState()` 和 `recoverAdmission()`； 10. 清理已经验证的 quarantine、retired safety holder 和软件 gate； 11. scope 外 blocker 或失败 participant 继续保留；只有全部 required latch 清除才回到 Open； 12. 返回 previous/new epoch、每个对象的 before/after 状态和 blocker。 ### 13.3 部分恢复 - 请求可以只恢复指定 device，但不能偷偷排除 subsystem blocker； - 设备级 quarantine 可以单独清除； - 如果 global gate 仍被其他 participant 持有，系统状态仍为 Latched； - response 必须区分 `RECOVERED`、`VERIFIED_BUT_STILL_BLOCKED`、`BLOCKER_REMAINS`、 `EPOCH_MISMATCH` 和 `NOTHING_TO_RECOVER`。 ## 14. gRPC API 设计 ### 14.1 扩展公共命令头 保持字段 1、2 不变，使用新 tag 增量扩展： ```protobuf message CommandHeader { message Request { string device_id = 1; google.protobuf.Timestamp timestamp = 2; // 仅诊断 string command_id = 3; string expected_service_instance_id = 4; optional uint64 expected_device_generation = 5; uint32 valid_for_ms = 6; } message Feedback { bool success = 1; string error_message = 2; google.protobuf.Timestamp timestamp = 3; CommandReasonCode reason_code = 4; string command_id = 5; string service_instance_id = 6; uint64 safety_epoch = 7; uint64 device_generation = 8; CommandExecutionState execution_state = 9; } } ``` 兼容阶段中旧客户端字段为空： - Legacy/Shadow 模式允许，但记录 `missing_command_identity`； - EnforceSelected 只对已迁移设备要求； - EnforceAll 下所有普通 mutating unary 命令必须提供； - Observe 不要求 command ID；安全 Stop 为保持可达性不把 ID/epoch 作为前置条件，但有 ID 时 用于合并结果和审计；Recover 必须提供 recovery ID 和 expected safety epoch。 `valid_for_ms` 从服务端收到请求的 monotonic time 开始计算，不能信任跨机器 timestamp。 Safety Stop 忽略已经过期的普通命令有效期，但仍受服务端 stop operation 总 deadline 约束。 - `command_id` 建议使用 UUID，服务端至少限制字符集和最大长度； - `valid_for_ms=0` 在 Legacy/Shadow 下使用有界服务端默认值，不能表示无限； - EnforceSelected/EnforceAll 可以要求 Actuate 显式提供非零有效期； - 服务端对所有客户端有效期施加硬上限，retry 不能延长原 ledger 记录的 deadline； - expected service instance 为空只在兼容模式接受。 ### 14.2 新增安全 API 建议新增 `protos/cmvr/api/safety_command.proto`，并在现有 `SystemService` 增加： ```protobuf rpc GetSafetyState(GetSafetyStateCommand.Request) returns (GetSafetyStateCommand.Feedback); rpc RecoverSafetyState(RecoverSafetyStateCommand.Request) returns (RecoverSafetyStateCommand.Feedback); ``` 建议核心消息： ```protobuf message DeviceIdList { repeated string device_ids = 1; } message SafetyScope { oneof target { bool all_devices = 1; // 必须显式为 true DeviceIdList devices = 2; // 必须非空且无重复 } } message RecoverSafetyStateCommand { enum Mode { MODE_UNSPECIFIED = 0; VERIFY_ONLY = 1; CLEAR_SOFTWARE_LATCH = 2; } message Request { string recovery_id = 1; SafetyScope scope = 2; uint64 expected_safety_epoch = 3; Mode mode = 4; string reason = 5; uint32 timeout_ms = 6; } message Feedback { CommandHeader.Feedback header = 1; RecoveryResult result = 2; uint64 previous_safety_epoch = 3; uint64 current_safety_epoch = 4; SystemAdmissionState system_state = 5; repeated RecoveryTargetResult targets = 6; } } ``` 不要增加 `force=true` 或 `ignore_hardware_state=true`。 ### 14.3 GetSafetyState 至少返回： - global admission state、safety epoch、control service instance ID； - device lifecycle、health、device admission state； - SafetyCondition、snapshot fresh、sample age、device generation； - active control owner 的脱敏标识； - blocker reason code、首次发生时间、最后更新时间、来源 operation/command ID； - 当前 StopAll/Recover operation 的阶段和 deadline； - subsystem participant 状态。 该接口只读内存，即使设备失联或 driver worker 卡住也必须及时返回。 ### 14.4 gRPC status 与业务结果 - 没有产生有效业务结果时使用非 OK status：认证失败、权限不足、格式错误、服务关闭； - command ID 已预留后，执行结果使用 `grpc::Status::OK + CommandOutcome`，便于相同 ID 重放完整结果； - Recover 的部分失败也返回 OK 和 per-target result； - `INTERNAL` 只表示代码异常或不变量破坏； - 兼容旧服务时继续填充 `success/error_message`，客户端应迁移到 reason code。 ## 15. 稳定错误模型 建议公共 reason code 至少包括： | Reason | gRPC 映射 | 是否可用同 ID 重试 | | --- | --- | --- | | INVALID_ARGUMENT | INVALID_ARGUMENT | 否，修正后使用新 ID | | UNAUTHENTICATED | UNAUTHENTICATED | 认证后重新请求 | | PERMISSION_DENIED | PERMISSION_DENIED | 否 | | RECOVERY_RPC_DISABLED | FAILED_PRECONDITION | 是；未进入 RecoveryLedger，本机改配置并重启后可重试 | | DEVICE_NOT_FOUND | NOT_FOUND | 否 | | UNSUPPORTED_COMMAND | UNIMPLEMENTED | 否 | | SYSTEM_STOPPING | ABORTED | 原 ID 查询，不重新下发 | | SAFETY_LATCHED | FAILED_PRECONDITION | 恢复后新 ID | | SAFETY_STATE_STALE | UNAVAILABLE | 状态刷新后新 ID | | HARDWARE_UNSAFE | FAILED_PRECONDITION | 处理硬件后新 ID | | EMERGENCY_STOP_ACTIVE | FAILED_PRECONDITION | 物理处理后新 ID | | PROTECTIVE_STOP_ACTIVE | FAILED_PRECONDITION | 合法复位后新 ID | | DEVICE_DISCONNECTED | UNAVAILABLE | 重连并校验 generation 后新 ID | | CONTROL_BUSY | RESOURCE_EXHAUSTED | 释放控制权后新 ID | | GENERATION_MISMATCH | ABORTED | 刷新状态后新 ID | | COMMAND_ID_CONFLICT | ALREADY_EXISTS | 否 | | LEDGER_EXHAUSTED | RESOURCE_EXHAUSTED | 稍后提交新 ID | | BACKPRESSURE | RESOURCE_EXHAUSTED | 仅确认未接收后使用新 ID | | DEADLINE_EXCEEDED_BEFORE_DISPATCH | DEADLINE_EXCEEDED | 新 ID | | OUTCOME_UNKNOWN | ABORTED | 不得自动重下发 | | INTERNAL_ERROR | INTERNAL | 不得自动重下发运动 | response 可以附带 retry directive，但 `retryable=true` 不能用于 `OUTCOME_UNKNOWN`。 ## 16. gRPC 请求上下文与安全扩展设计 ### 16.1 延后认证的边界 本轮设备安全改造允许不实现 TLS、静态 Token、JWT 和 mTLS，但不能把“暂不认证”等同于 “不设计认证边界”。现在必须固定以下三层接口，后续安全加固只能替换实现： | 层 | 当前小范围部署 | 后续可选实现 | 业务层是否感知 | | --- | --- | --- | --- | | Transport security | Insecure，可受限到 loopback/隔离网 | Server TLS、mTLS、Unix Domain Socket | 否 | | Authentication | Disabled，服务端生成 `anonymous` | Static Token、JWT/OIDC、TLS client certificate、Unix peer credential | 否 | | Authorization | Compatibility policy + Recover exposure policy | 基于 role/capability 的 policy | 只接收允许/拒绝结果 | 这种调整只表示认证交付可以延后，不表示明文匿名网络具备安全性。使用非 loopback 明文监听时， 安全依赖部署网络、主机防火墙和物理访问控制；该风险必须在配置、启动日志、SystemInfo 和指标中 保持可见。 认证信息继续使用 gRPC metadata 或 transport auth context，不进入业务 request Proto。这样不会 污染设备 API，也避免以后为了增加 Token 给所有命令消息增加字段。 ### 16.2 `RequestContext` 与扩展接口 建议定义与设备层无关的不可变上下文： ```cpp enum class AuthenticationMethod { Disabled, StaticToken, Jwt, TlsClientCertificate, UnixPeerCredential, }; struct Principal { std::string id; // 由服务端生成 AuthenticationMethod method; bool authenticated; std::vector roles; // Disabled 模式只能是 Anonymous }; struct RequestContext { std::string correlation_id; std::string full_method_name; std::string peer; Principal principal; bool transport_encrypted; bool local_peer; std::chrono::steady_clock::time_point received_at; std::chrono::steady_clock::time_point deadline; }; ``` 核心扩展接口： ```cpp class GrpcAuthenticationProvider { public: virtual ~GrpcAuthenticationProvider() = default; virtual AuthenticationResult authenticate(const GrpcCallFacts&) = 0; }; class GrpcAuthorizationPolicy { public: virtual ~GrpcAuthorizationPolicy() = default; virtual AuthorizationDecision authorize( const RequestContext&, const GrpcMethodPolicy&) const = 0; }; class GrpcSecurityGateway { public: virtual GrpcCallGuard beginCall( grpc::ServerContext&, const GrpcMethodPolicy&) = 0; }; ``` 当前提供 `DisabledAuthenticationProvider`：它不读取客户端自报身份，始终产生 `{id="anonymous", authenticated=false, roles=[Anonymous]}`。同时提供可注入的 fake provider， 用于证明未来切换认证实现时不需要修改 handler。 每个 gRPC handler 在入口取得 `GrpcCallGuard`，之后只使用其中的 `RequestContext`。call guard 负责上下文生命周期、统一拒绝状态和审计结束事件。可以用 server interceptor 完成全局前置检查， 但不能依赖 thread-local 在 interceptor 和 handler 之间传递身份；同步、异步和 callback RPC 都必须 具有明确的 per-call 所有权。 `SafetyManager` 不依赖 gRPC 类型。Service 只把从 `RequestContext` 派生的稳定 `CommandActor`/capability 传给准入和 ledger；驱动层完全不可见认证方式。 ### 16.3 部署 Profile 建议提供以下验证 Profile。Profile 是一组配置约束，不是散落在 Service 中的条件分支： | Profile | 监听与传输 | AuthN | Recover | 适用范围 | | --- | --- | --- | --- | --- | | `LOCAL_COMPATIBILITY` | loopback 或 Unix Domain Socket，可明文 | Disabled | 默认 Disabled，可显式 LocalOnly | 单机开发和维护 | | `TRUSTED_NETWORK_COMPATIBILITY` | 显式受控网卡，可明文 | Disabled | Disabled | 当前隔离的小范围运行 | | `LIGHTWEIGHT_AUTHENTICATED` | Server TLS | Static Token | SafetyAdmin | 客户端无需证书的轻量方案 | | `PRODUCTION_AUTHENTICATED` | Server TLS 或 mTLS | JWT/Token/client certificate | SafetyAdmin | 后续正式部署 | 本轮只要求实现前两个 Compatibility Profile 和后两个 Profile 的配置校验占位；选择尚未编译的 认证 provider 必须启动失败，不能静默退回 Disabled。 约束如下： - Disabled 必须是显式模式，不能因为证书或 Token 文件加载失败而自动进入； - 非 loopback 的 Insecure + Disabled 必须额外配置 `allow_insecure_non_loopback=true`，并产生 高可见度持续告警； - Profile 只能通过本机配置和进程重启改变，不提供远程降级接口； - QUIC heartbeat 和 GetSystemInfo 发布实际 transport/authentication/recovery exposure，不能 根据配置意图伪报； - 后续 Static Token 客户端通过统一 client interceptor 添加 `authorization: Bearer ...`， 业务调用点不变化； - 启用了 TLS 时才校验证书、私钥、CA、有效期和文件权限。 ### 16.4 授权与 Recover 暴露策略 方法权限仍预先分类，作为未来认证启用后的稳定契约： | Role | 权限 | | --- | --- | | Anonymous | Compatibility Profile 中除 Recover 外的现有兼容行为 | | Observer | GetSystemInfo、GetDeviceList、GetSafetyState、只读状态和传感流 | | Operator | Observer + 普通控制 + 设备 Stop + StopAll | | SafetyAdmin | Operator + RecoverSafetyState + 安全配置诊断 | `GrpcMethodPolicyRegistry` 至少保存完整 method 名、read/mutate/stop/recover 分类、 `CommandIntent` 和最低 role。未知方法在 Authenticated Profile 中 fail-closed；Compatibility Profile 可以只为已有 RPC 保留当前行为，但仍必须产生 `unclassified_method` 告警并在阶段 2 前清零。 `RecoverSafetyState` 和 `RestoreOperationalState` 额外使用独立的 `RecoveryExposure`： | RecoveryExposure | 行为 | | --- | --- | | `DISABLED` | 返回稳定的 `RECOVERY_RPC_DISABLED`，不进入 RecoveryLedger | | `LOCAL_ONLY` | 仅接受服务端从实际 peer 判定的 loopback/Unix Domain Socket 调用 | | `AUTHORIZED` | 要求 authenticated principal 且具有 SafetyAdmin | 校验规则： - Authentication Disabled + Recovery Authorized 是非法配置； - `TRUSTED_NETWORK_COMPATIBILITY` 不能配置 LocalOnly 后再信任代理转发的 IP/header；只有 gRPC 连接的实际 peer 可以用于本机判定； - LocalOnly 是部署范围限制，不宣称调用者身份已经认证；优先使用 Unix Domain Socket， 平台支持时再校验 UID/GID； - TCP loopback 的 LocalOnly 等价于信任主机上的所有进程。多用户主机、共享容器宿主机或存在 不可信本地进程时必须保持 Disabled，或改用具有文件权限/peer credential 的 Unix Domain Socket； - request 中的 role、principal、`force=true` 或类似字段一律不能改变该策略； - Stop/StopAll 始终走独立安全通道，不受普通 safety gate 或审计 sink 故障阻塞；Authenticated Profile 仍执行其访问策略，独立物理急停不能依赖网络认证服务。 ### 16.5 调用链与状态码 ```text request limits -> correlation ID -> selected authentication provider -> immutable RequestContext -> method/recovery authorization policy -> audit begin -> service handler -> audit outcome ``` - Disabled provider 成功结果仍标记 `authenticated=false`，不能伪造为 Observer/Operator； - 认证信息无效返回 `UNAUTHENTICATED`，身份有效但权限不足返回 `PERMISSION_DENIED`； - Recover 被部署配置关闭返回业务 reason `RECOVERY_RPC_DISABLED`； - LocalOnly 收到非本机 peer 返回 `PERMISSION_DENIED`； - reflection 独立配置。Authenticated Profile 默认关闭或仅向 SafetyAdmin 开放；Compatibility Profile 保持显式开关，不能依靠 reflection 状态表示访问安全。 ### 16.6 审计字段与失败策略 - effective principal ID、authentication method、authenticated、roles、peer； - transport encrypted、security profile、recovery exposure； - gRPC method、device/resource、intent； - correlation ID、command/recovery/stop operation ID； - payload hash，不记录 Token、Authorization metadata、原始音视频和敏感大 payload； - 准入结果、reason code、safety/device/authority generation； - 硬件提交状态、终态、耗时； - Recover reason、before/after blocker； - 审计写入失败的处理策略。 阶段 0 可以先把统一审计事件接入现有日志 sink，但事件 schema 必须稳定。阶段 4 开放任何形式的 Recover 前必须具备持久本地审计；Recover 审计无法写入时 fail-closed。Stop/StopAll 不能因审计 sink 不可用而被拒绝，实现应保留本地应急日志并继续停止。普通控制是否因审计失败而拒绝由 Profile 决定。 ### 16.7 后续启用认证的变更面 阶段 0 边界完成后，从 Disabled 升级到 Static Token/JWT/mTLS 只允许修改或新增： - `GrpcServerTask` 的 credential/provider builder； - `GrpcAuthenticationProvider` 实现、secret/identity 配置加载和角色映射； - 客户端统一 metadata interceptor 或 channel credential； - 对应 Profile 的集成测试、密钥轮换和部署 Runbook。 以下内容不应因认证升级而修改： - 设备命令 request/feedback Proto； - `DeviceManager`、`SafetyManager`、Sensor/Control policy； - `DeviceSafetyEndpoint`、`SafetyParticipant` 和厂商驱动； - handler 内的命令准入、StopAll 或 Recover 业务分支。 安全 Profile 只能在重启时切换。重启会生成新的 service instance ID，进程内 anonymous ledger 自然失效；不做运行期 `anonymous -> authenticated principal` 账本迁移，也不允许认证加载失败时 保留旧监听并降级运行。 ## 17. 配置设计 ### 17.1 SafetyManagerConfig 建议在 `DeviceManagerConfig` 中增加： ```protobuf message SafetyManagerConfig { enum EnforcementMode { ENFORCEMENT_MODE_UNSPECIFIED = 0; LEGACY = 1; SHADOW = 2; ENFORCE_SELECTED = 3; ENFORCE_ALL = 4; } EnforcementMode mode = 1; repeated string enforced_device_ids = 2; uint32 stop_all_timeout_ms = 3; uint32 recovery_timeout_ms = 4; uint32 command_ledger_result_capacity = 5; uint32 command_ledger_total_id_capacity = 6; uint32 event_history_capacity = 7; bool fail_startup_on_missing_control_capability = 8; } ``` 阶段 1 到阶段 4 允许旧配置缺失并进入 Legacy/Shadow，同时产生高可见度告警。阶段 5 的 Production 配置若仍为 UNSPECIFIED 或 LEGACY，启动失败。 ### 17.2 设备级覆盖 设备 entry 可增加： - 是否纳入当前 enforce rollout； - 更短的 snapshot freshness； - 更短的 stop/recovery timeout； - 是否为启动所必需。 配置不能： - 把 Control endpoint 改成 Sensor； - 把 required safe-stop 改成 optional； - 允许 Unknown 通过； - 关闭驱动最终硬件检查； - 远程修改 enforce 为 legacy。 策略族和 capability 由编译后的 adapter 注册，配置只能收紧。 该启动失败开关只针对结构性缺陷，例如控制设备没有 endpoint 或 safe-stop capability。运行时 设备断线、急停或动态 Unknown 应进入 Blocked/Latched，并保持管理面在线。 ### 17.3 GRPCSecurityConfig 建议在现有 `GRPCServerConfig` 中增加独立安全配置。Transport 和 Authentication 不合并成一个 布尔值，避免以后只能通过客户端证书获得加密连接： ```protobuf message GRPCSecurityConfig { enum TransportMode { TRANSPORT_MODE_UNSPECIFIED = 0; INSECURE = 1; SERVER_TLS = 2; MUTUAL_TLS = 3; } enum AuthenticationMode { AUTHENTICATION_MODE_UNSPECIFIED = 0; DISABLED = 1; STATIC_TOKEN = 2; JWT = 3; TLS_CLIENT_CERTIFICATE = 4; } enum RecoveryExposure { RECOVERY_EXPOSURE_UNSPECIFIED = 0; RECOVERY_DISABLED = 1; RECOVERY_LOCAL_ONLY = 2; RECOVERY_AUTHORIZED = 3; } TransportMode transport_mode = 1; AuthenticationMode authentication_mode = 2; RecoveryExposure recovery_exposure = 3; bool allow_insecure_non_loopback = 4; bool enable_reflection = 5; string server_certificate_file = 6; string server_private_key_file = 7; string client_ca_file = 8; string static_token_file = 9; string jwt_issuer = 10; string jwt_audience = 11; string audit_file = 12; } ``` 阶段 0 只实现 `INSECURE + DISABLED`，以及 `RECOVERY_DISABLED/RECOVERY_LOCAL_ONLY` 的策略； 其他枚举值先形成稳定配置契约，选择未编译能力时返回明确启动错误。旧配置缺失该 message 时可有 一个发布周期映射到当前行为，但必须告警；迁移窗口结束后 UNSPECIFIED 一律启动失败。 后续 provider 实现后的组合约束： | Transport | Authentication | 是否允许 | 说明 | | --- | --- | --- | --- | | Insecure/Unix socket | Disabled | 是 | Compatibility；按监听范围和 RecoveryExposure 限制 | | Insecure TCP | StaticToken/JWT | 否 | 凭据可被监听和重放 | | Server TLS | Disabled | 是 | 只加密，不识别客户端，仍属于 Compatibility | | Server TLS | StaticToken/JWT | 是 | 推荐的轻量远程认证 | | Mutual TLS | TLSClientCertificate | 是 | 后续强身份 Profile | | Mutual TLS | Disabled | 否 | 要求客户端证书却丢弃身份没有明确语义 | 首轮不实现多因素组合；如果未来需要 mTLS + Token，必须定义唯一 principal、角色合并和审计规则， 不能简单拼接两个 provider 的结果。 配置只保存凭据文件路径，不保存 Token 明文。后续实现静态 Token 时使用权限受限的独立文件， 日志和审计只能记录 token ID，不能记录 secret。所有组合在启动时集中校验，并把实际生效值写入 capability manifest/SystemInfo。 ## 18. 当前设备迁移映射 | 设备/入口 | 策略 | 关键安全事实 | Stop/恢复要点 | | --- | --- | --- | --- | | Aubo Arm | Control | connected、robot mode、exec/queue、power、硬件/软件 EStop、protective stop、fault | 硬件 EStop 释放后在 Normal/Reduced 下自动 poweron/startup，Running 且队列清空、quiescent 后才重新准入；显式 Stop/PowerOff 优先；软件 EStop 独立锁存；无法确认 exec 时 OutcomeUnknown | | Huayan Arm | Control | lifecycle generation、motion state、fault、stop confirmation | 保留已强化的 fail-closed 生命周期，映射为统一 endpoint | | MotorRobotArm | Control | group atomicity、joint freshness、bus generation | 不具备原子 group servo 时继续拒绝 teleop capability | | UME RobotArm | Control | CAN session、watchdog、torque enable、feedback freshness | reconnect 不恢复 torque；本地 haptic loop 不做网络调用 | | ArmTeleopService | Control（stream） | session ID、sequence、watchdog、lease、safety epoch | OPEN 时准入；每帧校验 epoch；StopAll 后必须新 session | | SEER AGV | Control | controller session、navigation terminal、velocity、EStop、fault | cancel ACK 不等于停稳；连续零速度采样后才 quiescent | | MotorManager/Motor | Control | bus session epoch、CiA402 state、enabled、quick-stop、actual velocity | 每个 motor resource 注册；Quick Stop 未确认则 quarantine | | DexHand control | Control | hand lifecycle、command generation、actuator idle | tactile stream 与控制命令分开分类；stopOperationalActivity 必须可证明 | | DexHand tactile | Sensor | polling worker、sample freshness | StopAll 可停 stream，但不能把 stream 状态当作手部运动状态 | | Camera capture | Sensor | opened、streaming、worker generation | 复用 MediaSourceManager；gRPC/QUIC 和直接 startStreaming 在启动设备 producer 前取得 Sensor/StartActivity dispatch guard | | Camera PTZ | Control | PTZ activity generation、stop ACK | 服务端按已校验 action 派生 START=Actuate、STOP=安全通道，锁止时 STOP 仍可下发 | | Microphone | Sensor | capture lifecycle、sample freshness | activity participant | | Speaker | Sensor | playback lifecycle、worker generation | Stop 始终允许；不视为机械执行器 | | BioHead | Control | expression/speech activity、hardware fault | 表情可能产生机械运动，不能归入纯媒体 | | Battery | Sensor | sample freshness、communication state | 只读；不参与 actuator StopAll | | MuJoCo control | Control | simulation generation、active command | 使用与真机相同策略，便于故障注入，但不能代替真机验收 | | HLC/touch | Control | 服务端解析真实 arm ID、任务 safety session、每次 arm submission 复核 | `touch` 为 Actuate；每次 move/speed/servo 前依次复核 permit、control authority、Coordinator dispatch 和设备最终检查；撤销后走 Stop lane | | QUIC media | Sensor | Camera/Microphone source ID、snapshot freshness、media generation | 不提供执行器控制；全局 Hub 的设备 producer 启动使用与 gRPC 相同的 Sensor/StartActivity dispatch guard | Aubo JSON `get_di/get_do` 可以归类 Observe；`set_do` 必须归类 Configure/Control，并最终迁移 为 typed RPC。未知 JSON command 在 Control 设备上默认拒绝。 ## 19. 六阶段实施方案 | 阶段 | 核心产物 | 是否改变生产准入 | | --- | --- | --- | | 0 | RequestContext、AuthN/AuthZ/Audit 扩展边界 | 否，显式保持现有兼容行为 | | 1 | 类型、快照、错误、幂等契约 | 否，旧 gate 仍权威 | | 2 | SafetyManager shadow | 否，只比较决策 | | 3 | 高风险设备逐个 enforce | 仅改变选中设备 | | 4 | 泛化 StopAll、正式 Recover | 改变系统安全事务 | | 5 | EnforceAll、真机签字、移除旧路径 | 全量切换 | 每个阶段只有满足退出条件后才能进入下一阶段；不能为了尽快提供 Recover 而跳过阶段 0、1、 2 或高风险设备迁移。 ### 阶段 0：建立控制面安全扩展边界 #### 目标 在不增加现有客户端证书或 Token 配置负担的前提下，建立统一请求上下文和可替换的安全网关， 使以后增加认证只替换 provider/policy，不横向修改所有 Service。当前明文匿名暴露被显式记录， 但本阶段不改变已有普通 RPC 的允许/拒绝行为。 #### 实施项 1. 扩展 `grpc_server_config.proto`，增加 Transport、Authentication、RecoveryExposure 和 `allow_insecure_non_loopback`；本阶段只实现 Insecure + Disabled。 2. 定义不可变 `RequestContext`、`Principal`、与 gRPC 无关的 `CommandActor`，以及明确的 effective principal 规则。 3. 实现 `DisabledAuthenticationProvider`、`GrpcAuthorizationPolicy`、 `GrpcSecurityGateway/GrpcCallGuard` 和可注入 fake provider。 4. 建立完整 method 名驱动的 `GrpcMethodPolicyRegistry`，先固定 read/mutate/stop/recover、 最低未来 role；CommandIntent 最迟在阶段 2 补齐。 5. 所有现有 handler 统一通过 call guard 取得上下文；Service 不直接读取认证 metadata， 不从 request 读取 principal/role。 6. Compatibility policy 保持现有 RPC 行为。`RecoverSafetyState` 标记为独立 Recovery policy， 此阶段只预留，不注册实现。 7. 增加 correlation ID 和统一审计事件 schema，先接入现有日志 sink；保留 error logging interceptor，并明确多个 interceptor/call guard 的生命周期顺序。 8. GrpcServerTask 集中校验配置组合；选择 StaticToken/JWT/mTLS 等未实现 provider 时启动失败， 不允许静默退回 Disabled。 9. QUIC heartbeat、GetSystemInfo、启动日志和指标发布实际 transport、authentication 和 recovery exposure；非 loopback 明文匿名模式持续告警。 10. 为旧配置提供一个发布周期的兼容映射，并更新部署文档和显式示例配置。 #### 测试 - Disabled provider 忽略伪造的 principal/role metadata，结果始终是未认证 `anonymous`； - 现有客户端不增加 metadata 仍可调用已有 RPC，允许/拒绝结果不变； - IPv4/IPv6 loopback、Unix Domain Socket 和非本机 peer 分类； - Disabled + Authorized Recovery、未实现 provider、非 loopback insecure 未显式确认等非法组合； - fake authenticated provider 下 Observer/Operator/SafetyAdmin 的 method policy； - sync、stream、callback、deadline/cancellation 下 RequestContext 生命周期和清理； - correlation ID、审计字段脱敏、audit sink 异常和 interceptor 顺序； - 旧配置迁移及实际 security capability 上报。 #### 退出条件 - 每个现有 gRPC method 都经过统一 gateway，并有 access class； - `anonymous` 只能由服务端生成，伪造 metadata 不会获得 role； - 当前兼容模式行为未改变，但明文/匿名/监听范围在配置和运行状态中可见； - 非本机匿名 Recover 没有可执行路径； - fake provider 测试证明启用认证不需要修改业务 handler、Coordinator 或驱动； - 部署文档、风险说明和显式示例配置已更新。 #### 回滚边界 可以让 Compatibility policy 继续保持旧行为，但 RequestContext、method registry 和配置字段 不能删除；否则会重新引入后续横向改造。任何安全 Profile 变化只能通过本机配置和进程重启， 不能提供远程降级 RPC。 ### 阶段 1：统一类型、快照、错误与幂等契约 #### 目标 建立后续状态机所需的数据契约，但不改变现有命令准入结果。 #### 实施项 1. 新建 `manager/safety_manager` target 和 `safety_types.h`。 2. 定义 CommandIntent、SafetyCondition、TriState、SafetyBlocker、SafetySnapshot。 3. 定义 DeviceSafetyDescriptor、Endpoint、Participant 接口。 4. 在 DeviceManager 中建立 `SafetySnapshotStore`，Manager snapshot 只读缓存。 5. 为现有设备建立 adapter；未支持设备发布 Unknown，不伪造安全。 6. 扩展 `CommandHeader` 和 Feedback；新增 reason code 和 execution state。 7. 生成统一 control service instance ID，并通过 GetSystemInfo 暴露。 8. 实现进程内 CommandLedger，复用 ActionQueue 的容量和 retired-ID 设计原则。 9. 建立 vendor result 到公共 reason code 的映射层。 10. 给 AbstractDevice 的宽松默认生命周期能力增加弃用标记；Control 注册要求显式能力。 11. 更新 Manager/Service/Proto 文档中已经过时的生命周期说明。 #### 测试 - snapshot 并发发布/读取、stale 计算、generation 单调性； - endpoint 未实现、设备重连、设备重新注册； - ledger 同 ID 同 payload、不同 payload、in-flight join、淘汰和容量耗尽； - deterministic payload hash； - reason code 映射完整性； - protobuf 旧 client payload 解析和旧配置解析。 #### 退出条件 - gRPC 状态查询和 QUIC heartbeat 不再调用设备方法； - 所有 Control 类型至少有显式 Unknown adapter，不再依赖默认 Healthy； - 新字段保持 wire compatible； - ledger 的 OutcomeUnknown 测试证明不会二次 dispatch； - 此阶段生产行为仍由旧 gate 决定。 #### 回滚边界 新 Proto 字段不可删除或复用；可以停止使用新字段，但必须保留 wire schema。SnapshotStore 可以退回仅诊断模式，不影响旧 gate。 ### 阶段 2：SafetyManager 影子运行 #### 目标 在不改变线上允许/拒绝结果的情况下，对全部命令计算新策略结果并验证分类完整性。 #### 实施项 1. DeviceManager 构造并持有 SafetyManager。 2. 在阶段 0 的 GrpcMethodPolicyRegistry 中补齐 CommandIntent，并引入 typed CommandDescriptor。 3. gRPC service 增加可注入构造函数；GrpcServerTask 统一传入 coordinator/ledger，沿用既有 GrpcSecurityGateway。 4. 每个 handler 在旧 gate 前后调用 shadow evaluation，记录旧/新决策差异。 5. 把 StopAll gate、Motor、Media、Camera registry、ActionQueue 包装成 legacy participant。 6. 新增只读 `GetSafetyState`，先发布 shadow decision、freshness 和 blocker。 7. 增加 admission latency、decision mismatch、unknown snapshot、unclassified method 指标。 8. 启动状态使用 Starting；只做诊断，不因 shadow 结果阻止旧业务。 9. 将 Runtime/TaskManager 划分为 management-plane 和 operational 启动组；设备动态故障不再 使已经通过所选安全 Profile 配置校验的 SystemService 一并退出。 #### 影子比较分类 | 旧结果 | 新结果 | 处理 | | --- | --- | --- | | Allow | Allow | 正常 | | Deny | Deny | 正常，比较 reason | | Allow | Deny | 记录 `would_deny`，优先修正快照或旧行为 | | Deny | Allow | 高风险 `would_allow`，在进入阶段 3 前必须归零或有书面解释 | #### 测试 - 所有 protobuf service method 都在 method access policy 和 command-intent registry 中； - shadow evaluation 无硬件 I/O； - coordinator 销毁时 participant 全部注销且无 callback； - StopAll 与 shadow admit 并发不改变旧 gate 行为； - GetSafetyState 在设备 endpoint 阻塞时仍快速返回。 - 单个设备 create/init/start 失败时，GetSafetyState 仍可按当前安全 Profile 访问。 #### 退出条件 - 所有 mutating method 均有固定 intent； - 所有 Control 设备都有 DeviceSafetyDescriptor； - 没有未解释的 `legacy deny / new allow`； - Shadow 准入 p99 只包含内存操作，不受硬件 RTT 影响； - 至少完成一轮真实运行日志评审。 - 管理面 degraded-start 和正常 shutdown 路径都有生命周期测试。 #### 回滚边界 可关闭 shadow evaluation，但保留 snapshot 和 method registry。旧 gate 仍是唯一 authority。 ### 阶段 3：迁移高风险控制设备 #### 目标 让 Arm、Teleoperation、AGV、Motor、DexHand control 和 Camera PTZ 的普通命令由 SafetyManager 权威准入，并统一幂等与执行结果语义。 #### 迁移顺序 1. Aubo/Huayan unary Arm； 2. ArmTeleopService 和 UME session； 3. AGV navigation/velocity； 4. Motor unary 和 cyclic stream； 5. DexHand control； 6. Camera PTZ； 7. ActionQueue step dispatch。 #### 单设备迁移步骤 1. 完成 endpoint 和新鲜 snapshot； 2. 明确每个 SDK 返回值的 Accepted/Completed/Rejected/Unknown 语义； 3. 实现 safe-stop request 和 quiescence verification； 4. handler 先通过 Coordinator，再保留 legacy gate 作为第二道 deny-only adapter； 5. dispatch 前执行 permit revalidation 和 driver final check； 6. unary mutating 命令接入 CommandLedger； 7. 流式命令绑定 safety epoch、device generation 和 lease generation； 8. 开启该设备 `ENFORCE_SELECTED`； 9. 通过 fake、并发和真机测试后，删除该设备 handler 中重复的旧状态判断。 #### 驱动执行契约 - Aubo queue full 只有在 SDK 能证明命令未接收时才能返回 Backpressure； - 未及时观察到 exec ID 但无法证明未接收时返回 OutcomeUnknown，并 quarantine arm； - Huayan 保留已有的停止确认和生命周期 generation； - AGV cancel/zero command ACK 后继续等待导航终态和连续零速度样本； - Motor Quick Stop 未确认时保留 motor resource quarantine； - Teleop/stream 的 reconnect 总是新 session，旧轨迹不续跑； - DexHand void 返回接口逐步改为结构化 result，不能只靠日志判断成功。 #### 测试 - admit 与 StopAll 的线性化竞态； - snapshot 在 admit 后、dispatch 前过期； - lease 在 dispatch 前被抢占； - ACK 丢失、队列满、控制器断线、进程重连； - 同 command ID 并发请求； - stream sequence 重复、倒退、watchdog、断线； - Stop 后旧 session/permit 无法恢复； - 每个设备的真实停车确认。 #### 退出条件 - 上述高风险入口不存在绕过 Coordinator 的设备调用； - 每类命令都有结构化结果，Internal 不再承载所有业务错误； - 旧 gate 只作为兼容 deny，不再能单独 reopen 新 Coordinator； - 设备级 OutcomeUnknown 可通过 GetSafetyState 定位并进入恢复流程； - 新控制设备接入安全层不需要修改 SafetyManager switch。 #### 回滚边界 按 device ID 从 EnforceSelected 退回 Shadow。已产生的 quarantine 不能因回滚配置自动清除， 必须 StopAll 成功或通过当前 RecoveryExposure 允许的恢复流程处理。 ### 阶段 4：泛化 StopAll 并开放正式恢复 RPC #### 目标 删除 SystemService 中的设备类型停止编排，使 StopAll 和 Recover 成为统一、可观察、可重试的 安全事务。 #### 实施项 1. 实现 `SafetyOperationOrchestrator` 和 participant 分阶段执行。 2. 所有 legacy coordinator 注册为 participant，保留其已有 barrier 语义。 3. 设备通过注册的 safe-stop participant 加入，不再由 SystemService dynamic cast。 4. `gRPCSystemServiceImpl::StopAll` 缩减为 RequestContext、参数适配和结果映射。 5. StopAll 请求增加 operation ID、诊断用 service instance 和结构化 per-target response；旧或 缺失 instance 不能阻止安全停止。 6. 实现 RecoveryLedger、active refresh、quiescence check 和软件 latch reconcile。 7. 在 SystemService 注册 `GetSafetyState` 和 `RecoverSafetyState`。 8. Recover 统一执行 RecoveryExposure：Disabled 拒绝、LocalOnly 校验实际本机 peer、 Authorized 要求 authenticated SafetyAdmin；所有允许路径都要求非空 reason 并写持久审计。 9. `clearForTesting()` 保持测试可见或移入 test support，运行代码无法调用。 10. 调整 Runtime shutdown：先进入 ShuttingDown/关闭准入，再在 participant 存活时执行 有界 quiesce，之后停止 TaskManager 和 DeviceManager。 #### 并发规则 | 并发场景 | 规则 | | --- | --- | | StopAll vs normal command | epoch 线性化；命令要么被拒绝，要么被登记并停止 | | StopAll vs StopAll | 加入同一 round，返回同一结果 | | Recover vs normal command | Recovering 全程关闭普通准入 | | Recover vs StopAll | process operation mutex 串行化，Stop 优先 | | Recover vs Recover | 相同 recovery ID join；不同 ID 串行 | | RPC cancellation vs Stop/Recover | 只取消 waiter，不取消已开始的系统安全事务 | | late worker vs new epoch | 只能写旧 operation 诊断，不能 release 新 barrier | | shutdown vs Recover | shutdown 终止新 recovery，保持 gate 关闭并执行 quiesce | #### 测试 - participant 注册顺序随机但执行阶段稳定； - participant throw、timeout、永不返回、返回 Unknown； - 部分恢复和 global blocker； - Recover 时硬件 EStop、protective stop、fault、stale、disconnect、still moving； - 恢复过程中状态再次变坏； - expected epoch mismatch 和 recovery ID payload conflict； - Disabled/LocalOnly/Authorized 三种 RecoveryExposure，尤其是非本机伪造 metadata 无法绕过； - audit 写失败； - service 析构、dispatcher join 和 Runtime shutdown。 #### 退出条件 - SystemService StopAll 不包含具体 DeviceKind 停止分支； - StopAll/Recover 都返回 per-participant 结构化结果； - 任何失败路径都保持明确 Latched/Quarantined 状态； - Recover 无法绕过 Unknown、未结束 worker 或未确认运动； - 一次成功 Recover 使系统能接受新命令，但不会恢复旧命令或自动使能硬件； - Recover RPC 默认 Disabled；匿名部署只有 LocalOnly 验收通过才能开放，远程开放必须启用 authenticated SafetyAdmin；任何开放模式都要求持久审计验收通过。 #### 回滚边界 保留旧 StopAll adapter 一个发布周期，可通过本地启动配置切换实现。正式 Recover 已产生的 epoch 和审计不能回滚；禁止退回运行期无检查 clear。 ### 阶段 5：全量 enforce、真机验证和旧路径移除 #### 目标 覆盖剩余外围设备和所有命令入口，验证发布产物与真实硬件，并删除重复全局状态。 #### 实施项 1. 迁移 Camera/Microphone/Speaker/BioHead/HLC 和剩余 local task； 2. 对所有 protobuf method 做 descriptor 驱动的 access-policy/intent 完整性测试； 3. Production 强制 `ENFORCE_ALL`，Control Unknown 拒绝； 4. 删除 service 对 `globalStopAllAdmissionGate()`、global media/motor registry 的业务依赖； 5. 保留必要 registry 的领域功能，但准入 authority 只属于 Coordinator； 6. 建立 build capability manifest，包含已编译的 transport/auth provider、MsQuic、硬件 SDK、 Safety schema version； 7. GetSystemInfo 和启动日志发布实际 capability，不以源码存在推断二进制能力； 8. 建立安装产物 smoke test，而不只测试 build tree； 9. 建立真实设备台架和故障注入矩阵； 10. 完成运维 Runbook：StopAll、blocker 诊断、硬件处理、dry-run、Recover 和审计查询。 #### 真机矩阵 至少覆盖： - Aubo/Huayan：运动中断网、ACK 丢失、queue full、保护停、急停释放、SDK reconnect； - AGV：导航取消 ACK 后仍移动、速度反馈丢失、地图切换中 StopAll； - Motor：Modbus/EtherCAT 断线、bus epoch 改变、Quick Stop 未确认、stream watchdog； - DexHand/PTZ/BioHead：连续命令中 StopAll、stop ACK 丢失、sensor stream 并发； - 进程：控制中 SIGTERM、任务启动失败、服务重启后硬件仍活动； - 网络：RPC 超时后相同 ID 重试、不同 payload 冲突、匿名 namespace、实际 peer 分类；如果构建 包含认证 provider，再覆盖 Token/证书轮换和权限变化； - 多平台 QUIC：重连和多 heartbeat 不能改变本地控制 safety epoch。 #### 退出条件 - 所有 mutating 入口都经过 Coordinator 或显式安全通道； - 所有 Control capability 都有 fresh snapshot、final check、safe-stop 和真机签字； - 进程重启不会自动继续运动或接受旧请求； - install artifact capability 与配置一致； - 全量自动测试、TSAN/并发测试和硬件台架通过； - 运维人员能只依赖结构化状态完成一次故障定位和恢复； - 删除遗留 runtime clear 和无主 global gate。 #### 回滚边界 单设备可以通过本地配置从 EnforceSelected 退回 Shadow，但 RequestContext 安全边界、幂等和 Stop/Recover epoch 不能关闭。RecoveryExposure 或网络暴露范围的任何放宽都要求重启、审计和 现场审批，不能通过远程 RPC 修改。 ## 20. 测试体系 ### 20.1 单元测试 - Sensor/Control policy 全状态表； - safety state transition 和非法 transition； - snapshot freshness 和 generation； - permit move/expiry/revalidation； - ledger 和 recovery ledger； - reason code 与 gRPC 映射； - participant barrier/token epoch； - RequestContext 构造、anonymous effective principal、provider/policy 组合； - RecoveryExposure 和 actual peer classifier。 ### 20.2 并发与性质测试 建议用可控 scheduler/fake clock 重复验证： 1. StopAll 和 dispatch 的所有交错最终满足“不丢失活动”； 2. Recover 和 late stop callback 的所有交错都不能提前 reopen； 3. 相同 command ID 任意并发度下 dispatch count 最大为 1； 4. generation 单调增加，旧 permit 永远无法重新合法； 5. participant 异常不会跳过其他 required stop； 6. Coordinator 销毁后不存在访问已释放对象的 callback。 ### 20.3 Service 集成测试 - Disabled/Fake provider、method policy 和伪造 metadata； - legacy/new protobuf client； - handler 分类完整性； - Stop/Status 在 Latched 时可调用，Recover 在 exposure 允许时不受普通 gate 阻塞； - Recover per-target response； - gRPC deadline/cancellation 与 operation 生命周期分离。 ### 20.4 故障注入 | 故障点 | 期望结果 | | --- | --- | | Admit 后 snapshot 过期 | final check 拒绝，无 SDK dispatch | | SDK 调用超时且接收状态未知 | OutcomeUnknown + device quarantine | | Stop worker 超时 | global Latched，worker token 保留 | | Recovery refresh 超时 | blocker remains，不清 gate | | 相同 ID 不同 payload | conflict，无第二次 dispatch | | 进程重启期间硬件仍运动 | Starting/Latched，不自动 Open | | 审计落盘失败 | Recover fail-closed | | 一个设备 health worker 卡住 | 其他 Status/Stop/Recover 仍可执行 | ### 20.5 发布产物验证 - 对安装目录启动二进制； - 校验 capability manifest； - Insecure + Disabled 的 loopback 和显式 trusted-network grpcurl smoke； - Recovery Disabled/LocalOnly 的实际 peer smoke； - reflection 与安全 Profile 的显式配置 smoke； - 配置要求未编译 AuthN/Transport provider、MsQuic 或 driver capability 时启动失败； - 构建包含可选 Token/TLS/mTLS provider 时，才执行对应认证矩阵； - 生成 C++ 和 Java API 兼容测试。 ## 21. 可观测性与运维 ### 21.1 指标 建议至少提供： ```text cmvr_safety_admission_decisions_total{device,intent,decision,reason} cmvr_safety_snapshot_age_ms{device} cmvr_safety_device_state{device,state} cmvr_safety_global_state{state} cmvr_safety_stop_duration_ms{participant,result} cmvr_safety_recovery_attempts_total{result} cmvr_command_dedup_total{status} cmvr_command_outcome_unknown_total{device,method} cmvr_control_lease_conflicts_total{resource} cmvr_grpc_authz_denied_total{method,role} cmvr_grpc_requests_total{auth_method,authenticated} cmvr_grpc_insecure_listener{non_loopback} cmvr_grpc_recovery_access_denied_total{exposure,peer_kind,reason} ``` ### 21.2 事件历史 Coordinator 保存有界内存事件环，并将关键事件写入持久审计： - global/device transition； - snapshot stale/fresh、generation changed； - quarantine 创建和清除； - StopAll/Recover phase； - permit reject、final check reject； - OutcomeUnknown； - participant timeout/late completion。 错误字符串只用于人读，自动化必须使用 reason code 和结构化 blocker。 ### 21.3 Runbook 顺序 1. 调用 GetSafetyState 获取 epoch 和 blocker； 2. 确认当前 RecoveryExposure；Disabled 模式不能尝试网络绕过，需按本机变更流程处理； 3. 在现场确认物理环境和设备状态； 4. 必要时调用 typed ResetFault，不能直接 Recover 代替硬件处理； 5. 使用符合 LocalOnly/Authorized 策略的调用方执行 RecoverSafetyState `VERIFY_ONLY`； 6. blocker 全部满足后调用 `CLEAR_SOFTWARE_LATCH`； 7. 重新读取 SafetyState，确认新 epoch 和 Open/设备级状态； 8. 使用新的 command ID、service instance 和 device generation 下发后续命令。 ## 22. 建议 PR 拆分 为避免一次性改动所有设备，建议按以下独立可回滚单元提交： 1. 设计文档和安全不变量； 2. GRPCSecurityConfig、RequestContext、Disabled/Fake provider、method policy 和 call guard； 3. correlation/audit schema、实际 security capability 上报和 Compatibility Profile 测试； 4. Safety types、snapshot store 和 tests； 5. CommandHeader/reason code additive Proto； 6. CommandLedger； 7. SafetyManager shadow 和 GetSafetyState； 8. legacy participant adapters； 9. Arm + ArmTeleop migration； 10. AGV migration； 11. Motor migration； 12. DexHand/PTZ/ActionQueue migration； 13. generic StopAll； 14. RecoverSafetyState； 15. peripheral migration、EnforceAll 和 legacy removal； 16. capability manifest、install smoke 和硬件验证报告； 17. 可选后续：Server TLS + Static Token provider 和客户端 interceptor； 18. 可选后续：JWT/OIDC 或 mTLS provider、正式身份生命周期和密钥轮换。 每个迁移 PR 必须包含：命令分类表、snapshot 定义、stop verification、错误映射、竞态测试和 回滚开关。不得只把 handler 前的一个 `if` 移到 Coordinator 就宣称完成迁移。 ## 23. 最终验收清单 - [x] 所有 gRPC handler 都通过统一 RequestContext/call guard，业务代码不解析认证 metadata - [x] Disabled 模式始终产生未认证 anonymous principal，实际安全 Profile 和监听风险可观测 - [x] 所有方法都有 access policy 和 CommandIntent，未知方法不会绕过安全网关 - [x] Recover 默认 Disabled；匿名模式只允许 LocalOnly，远程模式只允许 authenticated SafetyAdmin - [x] Recover 所有开放方式都要求持久审计，审计失败时 fail-closed - [ ] 启用 Authenticated Profile 时，传输/AuthN/AuthZ 按该 Profile 的独立验收矩阵通过 - [x] 生命周期、健康和安全状态是独立字段 - [x] Manager snapshot/status 路径只读 Manager 缓存，不执行设备 I/O - [x] 普通 mutating unary 命令使用 command ID、service instance 和统一 ledger 语义 - [x] 流式控制绑定 session、sequence、watchdog 和 safety epoch - [x] 已迁移的 Control 命令经过统一准入和驱动最终检查 - [x] Stop/Status 在软件锁止状态下可达；Recover 在 exposure 允许时不受普通 gate 阻塞 - [x] SystemService StopAll 不按 DeviceKind 硬编码设备停止逻辑 - [x] StopAll 失败留下结构化 blocker 和不可绕过 latch - [x] Recover 不能忽略 Unknown、EStop、未确认运动或旧 worker - [x] Recover 不上电、不使能、不恢复旧轨迹或旧 session - [x] 同一 command ID 最大一次 dispatch，OutcomeUnknown 不自动重发 - [x] 新设备只需注册 DeviceSafetyDescriptor、Endpoint、Participant 和 method intent - [x] startup/shutdown 与 safety epoch 有明确顺序 - [x] 单个设备动态故障不会关闭按当前安全 Profile 启动的 SystemService 管理面 - [ ] 所有发布 capability 来自实际安装二进制 - [ ] fake、并发、故障注入、安装产物和真机台架全部完成 ## 24. 实施前需要确定的工程参数 以下参数需要通过设备手册和台架测量确定，但不改变架构： - 各设备 snapshot polling 周期和 maximum age； - StopAll 总 deadline 与每类 participant timeout； - 连续零速度/静止确认的阈值和样本数； - Aubo、Huayan、SEER 等 SDK 对“已接受命令”的精确定义； - ledger 容量和结果保留时间； - 审计文件保留、轮转和上传策略； - 当前部署允许监听的网卡/CIDR、主机防火墙规则和 `allow_insecure_non_loopback` 责任人； - RecoveryExposure 初始选择 Disabled 还是 LocalOnly，以及本机维护入口； - 旧安全配置兼容窗口长度，以及启用 Static Token/Server TLS 的触发条件； - 后续认证启用时的 principal 命名、Token/证书轮换和角色绑定； - 哪些设备是启动时 required control device。 这些值必须以显式配置和硬上限进入代码，不能以缺省零值表达“无限”或“允许全部”。