執行時狀態匯流排

返回：文件索引 / 開發指南

本文定義跨任務共享即時狀態的職責邊界、主題契約和消費方式。實現以 src/runtime_state/、src/tasks/mixin/runtime_state_mixin.py 和當前單元測試為準。

目錄名使用 runtime_state 而不是 runtime：後者會與 src/core/base_mixin/runtime_mixin.py 的“任務執行時能力”混淆，也容易被誤解為 整個應用執行時。這裡的包只承載跨任務共享狀態。

1. 職責邊界

模組	單一職責	不負責
src/runtime_state/state_hub.py	儲存 latest-value 快照、序號和時效	取樣、融合、任務排程
src/runtime_state/topics.py	定義穩定主題名	資料型別和業務邏輯
src/runtime_state/world_pose.py	把定位內部狀態對映為穩定座標契約	WS 連線、小地圖計算
src/tasks/mixin/runtime_state_mixin.py	給任務提供釋出、讀取、等待和定位取樣入口	識別演算法、路徑規劃
WorldPoseService	唯一維護應用級定位服務併發布 world.pose	導航、物品選擇、遊戲輸入
普通業務任務	讀取快照並執行自己的狀態機	直接啟動 WS、里程計或融合

RuntimeStateHub 使用 latest-value 語義：新快照覆蓋舊快照，消費者按 max_age 判斷是否仍可用。過期資料返回 None，不能繼續偽裝成即時狀態。

2. 主題

主題	型別	當前生產者	典型消費者
world.pose	最新值	WorldPoseService	物品導航、網格導航、滑索、除錯任務
world.scene	最新值	預留	自動互動、自動拾取、任務狀態機
world.targets	最新值	預留	物品導航、自動拾取
sensor.ws	最新值	預留	狀態列、診斷
system.health	最新值	預留	除錯面板、日誌

主題名通過 RuntimeTopic 引用，業務程式碼不要散落字串。

3. 座標契約

world.pose 至少包含：

欄位	含義
x / y / z	世界座標；x/z 為融合水平座標，y 為最新 WS 高度
heading / heading_score	羅盤方位角和朝向置信度
map_id	當前地圖
position_trusted / trust_reason	絕對座標是否可信及原因
anchor_set / rest	是否已錨定、當前是否靜止
odom_ok / odom_reason	本拍是否有有效里程計樣本
sync_seq / sync_checked / sync_needed	靜止校準狀態
ws / ws_xyz	原始 WS 水平座標和完整座標
sample_t	定位所有者使用的取樣時間
source	official_ws、local_ws 或 minimap

狀態閘道器會在信封中附加 sequence、published_at、expires_at 和釋出者名稱。

PoseProvider 是導航側依賴的最小定位介面，包含位置取樣、朝向控制、朝向閾值和 靜止診斷。導航模組不得匯入 src/localization/ 的具體實現。

4. 消費方式

普通任務繼承 RuntimeStateMixin，只調用下列介面：

pose = self.world_pose(frame=frame, max_age=0.6)
if pose is None:
    return

x = pose["x"]
z = pose["z"]
if not pose.get("position_trusted") or x is None or z is None:
    return

map_id = pose["map_id"]

等待條件成立時使用：

pose = self.wait_world_pose(
    lambda value: bool(value.get("position_trusted")),
    frame=frame,
    max_age=1.0,
    timeout=10.0,
    tick=0.1,
)

其他資訊使用通用介面釋出和讀取：

self.publish_runtime_state(
    RuntimeTopic.WORLD_SCENE,
    {"scene": "world"},
    source="SceneDetector",
    ttl=2.0,
)

scene = self.runtime_state(RuntimeTopic.WORLD_SCENE, max_age=1.0)

5. 排程約束

ok-script 的執行器是單執行緒協作排程。長任務執行期間，其他 TriggerTask 不會並行執行，因此定位不能假設自己會獨立按固定週期執行。

RuntimeStateMixin.world_pose(refresh=True) 會通過統一控制面呼叫定位所有者的 sample_world_pose()。消費者不接觸 WS、小地圖或融合物件，但可以請求所有者 採一幀併發布快照。這樣同時滿足單所有者、單執行緒排程和統一消費介面。

6. 擴充套件規則

• 高頻變化的資料使用 latest-value，消費者慢時丟棄舊值，不能阻塞生產者。
• 離散狀態變化使用事件流，每個訂閱者擁有獨立佇列，禁止共享單消費者佇列。
• OCR、模板掃描等按需任務使用請求響應，不要把所有請求廣播給全部消費者。
• 配置、物品點位、地圖檔案和網格檔案屬於參考資料，繼續通過 Config 或資料服務讀取。
• 狀態值必須帶時間、來源和可信狀態；需要舊值時返回過期錯誤，不返回陳舊值。