先級：排他鎖、復(fù)合權(quán)重與音量閃避)
一、從一個(gè)字段名說起AudioFile.msg里有這么一行注釋# 可選項(xiàng)(1~100) priority priority_weight% is final priority uint32 priority_weight而PlayTtsRequest.msg里同樣叫priority_weight的字段注釋是這樣的# 可選非產(chǎn)品要求勿用優(yōu)先級加權(quán)參數(shù)(0-99)最小單位為 1 uint32 priority_weight兩個(gè)字段同名、同類型都是uint32含義卻差得很遠(yuǎn)。前者的取值范圍是 1–100是個(gè)百分比后者是 0–99是個(gè)絕對偏移。更關(guān)鍵的是PlayTts的最終權(quán)重算法在《接口說明.md》里寫得很明確最終權(quán)重 主級 * 100 子權(quán)也就是說TTS 的priority_weight直接加到百位以上而音頻文件那邊它是對priority做一個(gè)百分比調(diào)整。同樣是「微調(diào)優(yōu)先級」一處加在百位一處加在個(gè)位還帶著百分號。我最初以為這是文檔寫錯(cuò)了。把三套機(jī)制的定義都取出來放在一起之后才看清楚不是寫錯(cuò)是三套獨(dú)立設(shè)計(jì)的優(yōu)先級機(jī)制恰好共享了兩個(gè)字段名。這篇文章拆的就是這三套機(jī)制。它們分別屬于運(yùn)控輸入源、TTS 播報(bào)、音頻文件播放各有各的取值空間、比較方式和失敗行為。搞混任何一處代碼都會(huì)在沒有任何報(bào)錯(cuò)的情況下做出錯(cuò)誤行為——這是我在實(shí)測里反復(fù)撞到的同一類問題。二、三套機(jī)制并排看先把三套機(jī)制放在一張表里。機(jī)制接口字段取值空間主級形態(tài)比較方式低優(yōu)先級方的結(jié)果運(yùn)控輸入源SetMcInputSourcepriority0–100 連續(xù)整數(shù)連續(xù)排他鎖先到先得幀被靜默丟棄1000 ms 看門狗脫鎖TTS 播報(bào)PlayTtspriority_levelpriority_weight主級 6 檔 × 子權(quán) 0–99跳段復(fù)合權(quán)重比大小同步返回is_successfalse高權(quán)重可中途掐斷音頻文件PlayAudioFileprioritypriority_weightmedia_rolepriority1–10weight1–100(%)連續(xù)百分比加權(quán)不終止靠音量閃避duck讓位三套機(jī)制連「失敗」的定義都不同運(yùn)控那邊輸?shù)囊环绞裁炊疾粫?huì)收到只能靠自己周期性查詢才發(fā)現(xiàn)控制權(quán)沒了TTS 那邊輸?shù)囊环綍?huì)收到一個(gè)明確的false音頻那邊輸?shù)囊环郊葲]有錯(cuò)誤也沒有終止只是音量被壓低。把它們畫成刻度形狀的差異更直觀。圖 1 中三條刻度各自獨(dú)立歸一化橫向長度不代表數(shù)值大小只用來看結(jié)構(gòu)運(yùn)控是均質(zhì)的連續(xù)刻度TTS 是跳段的離散塊跳過 3、5、9音頻是連續(xù)刻度上再疊一套四檔角色。圖中 L1–L10 的權(quán)重區(qū)間、priority的 1–10 取值、media_role的 40/60/80/100 四檔全部取自對應(yīng).msg文件與《接口說明.md》§2.1.1.4、§2.2.1.2、§2.2.1.3 三節(jié)。有一處值得單獨(dú)指出音頻文件播放那一行priority是 1–10而 TTS 的主級恰好也是 1、2、4、6、8、10 這幾個(gè)數(shù)字。數(shù)值看起來一樣含義毫無關(guān)系。AudioFile.priority是連續(xù)的 1–10默認(rèn) 6相鄰值只差一檔TtsPriorityLevel的主級是枚舉語義層跳過的那些值是為將來插入新檔位預(yù)留的位置。把priority_level 6的經(jīng)驗(yàn)搬到AudioFile.priority 6讀起來像實(shí)際語義完全不同。三、TTS 的權(quán)重空間99 與 100 的那 1 之隔TTS 這套最值得細(xì)看因?yàn)樗乃阈g(shù)規(guī)則寫得最明確而邊界恰好踩在一個(gè)很微妙的位置上。TtsPriorityLevel.msg在接口里實(shí)際只定義了 6 個(gè)有效檔位uint8 value uint8 UNKNOWN 0x00 # 后臺(tái)服務(wù)層 uint8 BACKGROUND_L1 0x01 # 主動(dòng)服務(wù)層 uint8 SERVICE_L2 0x02 # 任務(wù)執(zhí)行層 uint8 MISSION_L4 0x04 # 交互相應(yīng)層 uint8 INTERACTION_L6 0x06 # 危險(xiǎn)預(yù)警層 uint8 WARNING_L8 0x08 # 生命安全層 uint8 SAFETY_L10 0x0a主級取 1、2、4、6、8、10步長 2跳過 3、5、7、9。配合「最終權(quán)重 主級 × 100 子權(quán)」就得到下面這張取值表。常量value最終權(quán)重區(qū)間來源BACKGROUND_L10x01100 – 199接口 文檔SERVICE_L20x02200 – 299接口 文檔MISSION_L40x04400 – 499接口 文檔INTERACTION_L60x06600 – 699接口 文檔WARNING_L80x08800 – 899接口 文檔SAFETY_L100x0a1000 – 1099接口 文檔SYSTEM_L77700 – 799僅文檔接口無此常量表中最后一行的SYSTEM_L7是這篇文章的一個(gè)關(guān)鍵發(fā)現(xiàn)后面第七節(jié)會(huì)給出實(shí)測證據(jù)。先看一個(gè)更基礎(chǔ)的性質(zhì)。子權(quán)上限是 99主級步長是 100。相差 1這個(gè) 1 不是巧合。圖 2 的橫軸是最終權(quán)重1 單位對應(yīng) 1 像素?？梢灾庇^看到L4用滿子權(quán)封頂 499L6一個(gè)子權(quán)都不給也有 600兩者相差 101。中間那 100 個(gè)整數(shù)位500–599沒有任何檔位覆蓋。這意味著子權(quán)的作用半徑被精確限制在同檔內(nèi)部。任何一個(gè)「低一檔但更緊急」的播報(bào)都沒有任何可用手段能頂?shù)缴弦粰n去——把priority_weight調(diào)到 99也只是讓它在本檔里排到最前面。這是設(shè)計(jì)上的精確也是設(shè)計(jì)上的代價(jià)。它換來的是排序的絕對可預(yù)測性主級一旦確定跨檔關(guān)系就鎖死了不會(huì)因?yàn)槟硞€(gè)調(diào)用方擅自把子權(quán)拉滿而產(chǎn)生檔位穿透。代價(jià)是分層變得剛性——如果產(chǎn)品上確實(shí)需要「低一檔的緊急播報(bào)壓過高檔的例行播報(bào)」這套算術(shù)給不出解法只能改主級。再看那些空檔。接口里的主級是 1、2、4、6、8、10跳過 3、5、7、9對應(yīng) 300–399、500–599、700–799、900–999 四段。其中 700–799 被文檔的SYSTEM_L7填上了另外三段仍然空著。這不是浪費(fèi)是預(yù)留往這些區(qū)間插入新檔位不會(huì)擾動(dòng)任何已有排序。SYSTEM_L7的位置完全合理——它就在L6與L8之間那個(gè)天然的空位里問題只在于接口沒給它常量。四、仲裁矩陣兩格與字面意思相反權(quán)重算出來之后誰先播、誰被打斷由《接口說明.md》§2.2.1.2 的四格矩陣決定。文檔原文是這樣的權(quán)重對比is_interrupted: trueis_interrupted: false新任務(wù)權(quán)重 ≥ 當(dāng)前任務(wù)當(dāng)前播報(bào)被立即掐斷且不可恢復(fù)新語音開始播放仲裁優(yōu)先級相同時(shí)存入緩沖區(qū)仲裁優(yōu)先級大于當(dāng)前任務(wù)時(shí)強(qiáng)制打斷新任務(wù)權(quán)重 當(dāng)前任務(wù)請求丟棄is_success: false請求丟棄is_success: false這張表里藏著兩個(gè)與字段名字面意思相反的結(jié)論我在實(shí)測中逐一確認(rèn)過。圖 3 把四格矩陣與實(shí)測樣本畫在一起。格內(nèi)樣本編號對應(yīng)第七節(jié) 8 個(gè)場景的序號服務(wù)端為按該矩陣實(shí)現(xiàn)的 mock非真機(jī)行為。第一個(gè)反直覺點(diǎn)is_interrupted true不是強(qiáng)制插隊(duì)開關(guān)。按字面理解「打斷true」應(yīng)該意味著「我有話要說現(xiàn)在就說」。但矩陣寫得清楚這一列只在「新權(quán)重 ≥ 當(dāng)前」那一行才起作用權(quán)重不足時(shí)填true一樣被丟棄。實(shí)測中第 5 條請求L62 602當(dāng)前播報(bào)是 700即使is_interruptedtrue返回的仍是is_successfalseerror_message寫著「權(quán)重 602 當(dāng)前 700」。第二個(gè)反直覺點(diǎn)is_interrupted false不保證不被打斷。同樣按字面理解「不打斷」應(yīng)該意味著「別掐我」。但矩陣在false這一列寫的是「大于則強(qiáng)制打斷」。實(shí)測第 3 條請求L660 660當(dāng)前是 600is_interruptedfalse結(jié)果仍是PREEMPT_NOW——非搶占模式下權(quán)重更高照樣掐斷。兩點(diǎn)合起來這個(gè)字段的真實(shí)語義是「權(quán)重足夠時(shí)同檔要不要讓」。它管的是同級仲裁不是插隊(duì)權(quán)。而文檔對這個(gè)字段有三處描述只有一處與矩陣一致出處原文與矩陣是否一致PlayTtsRequest.msg注釋是否打斷同等優(yōu)先級播報(bào)true打斷false不打斷進(jìn)入隊(duì)列播報(bào)一致§2.2.1.2 字段表是否打斷現(xiàn)有任務(wù)true: 立即搶占false: 自動(dòng)排隊(duì)不一致§2.2.1.2 仲裁矩陣見上表—.msg注釋說的是「同等優(yōu)先級」與矩陣吻合字段表說的是「現(xiàn)有任務(wù)」把范圍放大了。差別就在這一行照字段表理解會(huì)寫出一個(gè)自己以為安全的調(diào)用——以為什么都不填就萬事大吉實(shí)際只要權(quán)重夠高就會(huì)被掐。五、音頻一處未閉合的歧義AudioFile.msg那一行的原文是# 可選項(xiàng)(1~100) priority priority_weight% is final priority uint32 priority_weight它給了表達(dá)式?jīng)]給運(yùn)算次序。至少有兩種都能自圓其說的讀法讀法 A加性final priority weight / 100讀法 B乘性final priority × (1 weight / 100)兩種讀法在權(quán)重較小時(shí)結(jié)果相近在權(quán)重接近上限時(shí)結(jié)論相反。輸入 1A 值輸入 2A 值A(chǔ) 判定B 值 1B 值 2B 判定是否分歧p6 50%6.50p7 0%7.00后者9.007.00前者分歧p6 100%7.00p7 0%7.00平手12.007.00前者分歧p6 100%7.00p10 0%10.00后者12.0010.00前者分歧p6 10%6.10p7 0%7.00后者6.607.00后者一致讀法 A 的跨檔上限是固定的增量恒 ≤ 1.0所以priority6用滿權(quán)重最多追平 7永遠(yuǎn)超不過相當(dāng)于「一檔之內(nèi)微調(diào)」。讀法 B 在weight100時(shí)直接翻倍priority6可以壓過 7 甚至 10相當(dāng)于「變相增加一到兩檔」。同一個(gè)字段兩種讀法跨檔能力差了兩檔。這不是筆誤級別的歧義是會(huì)影響排序結(jié)果的歧義。我沒有替它下結(jié)論因?yàn)檫@需要真機(jī)實(shí)測才能確定用兩個(gè)不同priority的音頻文件同時(shí)播放觀察實(shí)際輸出順序。在沒有真機(jī)的情況下斷言其中一種就是在編數(shù)據(jù)。這一處我留在第九節(jié)的「未決問題」里。順帶一提AudioFile還有第三個(gè)維度media_role。# 可選項(xiàng)PulseAudio media.role不傳默認(rèn) Music # 可選值A(chǔ)lert(系統(tǒng)告警,優(yōu)先級100) | Notification(系統(tǒng)提示音,優(yōu)先級80) | Communication(對話語音,優(yōu)先級60) | Music(音樂/媒體,優(yōu)先級40,默認(rèn)) # 非 Music 角色播放時(shí)會(huì)自動(dòng)降低(duck)音樂音量 string media_role這是第四套編號40/60/80/100由 PulseAudio 的角色體系決定與priority完全并行。所以嚴(yán)格說音頻這一路內(nèi)部同時(shí)跑著兩套排序一套是應(yīng)用層的priority 百分比一套是系統(tǒng)音頻服務(wù)層的media_role。前者決定誰先播后者決定誰壓低誰。這兩套之間如何交互文檔沒有展開。六、驗(yàn)證一把規(guī)則寫成代碼三套機(jī)制的規(guī)則都是純算術(shù)可以脫離 ROS 完整復(fù)現(xiàn)。我把它們寫成了一個(gè)零依賴的模塊只用標(biāo)準(zhǔn)庫。下面節(jié)選自taxonomy/levels.py完整文件在倉庫里。TTS_LEVEL_STRIDE 100 TTS_WEIGHT_MAX 99 def tts_final_weight(level_value: int, priority_weight: int) - int: 最終權(quán)重 主級 * 100 子權(quán)。 return level_value * TTS_LEVEL_STRIDE priority_weight def sub_weight_can_cross_level() - bool: 子權(quán)能否跨越主級子權(quán)上界 99主級步長 100。 return (TTS_WEIGHT_MAX 1) TTS_LEVEL_STRIDE這個(gè)函數(shù)不做范圍鉗制因?yàn)榻涌趯油瑯硬蛔觥猵riority_weight聲明為uint320–99 只是文檔約定類型系統(tǒng)擋不住 100 以上的輸入。這一點(diǎn)第七節(jié)的實(shí)測會(huì)確認(rèn)。跑一遍邊界場景命令與輸出都在圖 4 里。從這一處起凡是程序輸出一律給真實(shí)終端截圖不再手抄——寫稿時(shí)把輸出貼進(jìn)代碼塊最容易出的錯(cuò)不是抄錯(cuò)數(shù)字而是抄錯(cuò)一個(gè)自己沒注意到的對齊空格。python3 scenarios/run.py weight圖 4 是容器pgc/primebot-humble:1.0內(nèi)的真實(shí)終端畫面Xvfb 上起一個(gè) 80×32 的 xterm用偽終端把命令逐條敲進(jìn)交互式 bash等輸出定格后用 ImageMagick 抓窗口未做任何裁剪與修飾。畫面上半部分是七個(gè)檔位的取值區(qū)間下半部分是相鄰兩級的臨界值——L1滿子權(quán) 199 對上L2零子權(quán) 200只差 1其余各相鄰對都差 101。這個(gè)「差 1」正是子權(quán)跨不了級的算術(shù)來源。抓圖腳本在倉庫tools/shot/下all_shots.sh一次跑完本文全部五張終端圖可以原樣復(fù)現(xiàn)。除了驗(yàn)證算術(shù)我還用窮舉確認(rèn)了一個(gè)文檔沒寫、但可以從矩陣推出來的結(jié)論。問題是is_interruptedfalse時(shí)入隊(duì)的任務(wù)按什么順序出隊(duì)文檔只寫「存入緩沖區(qū)在當(dāng)前任務(wù)播放完成后再進(jìn)行處理」沒說排序鍵。# 節(jié)選自 scenarios/exhaustive_queue.py 的 compute() def compute(): 返回 (入隊(duì)總數(shù), 差值-次數(shù), 主級-入隊(duì)數(shù))。純函數(shù)供 run.py 復(fù)用。 queued_diffs: dict {} per_level: dict {lv: 0 for lv in TTS_VALID_LEVEL_VALUES} total_queued 0 for level in TTS_VALID_LEVEL_VALUES: # 6 個(gè)合法主級 for w in range(0, TTS_WEIGHT_MAX 1): # 子權(quán) 0-99 req TtsRequest(probe, level, w, False) for current in range(CURRENT_MIN, CURRENT_MAX 1): # 100-1099 if arbitrate(req, current) is Verdict.QUEUED: total_queued 1 per_level[level] 1 diff req.weight - current queued_diffs[diff] queued_diffs.get(diff, 0) 1 return total_queued, queued_diffs, per_level圖 5 與圖 4 出自同一個(gè)容器、同一次會(huì)話、同一套抓圖流程。畫面里先確認(rèn)解釋器版本為 Python 3.10.12再執(zhí)行scenarios/exhaustive_queue.py600 個(gè)合法請求 × 1000 個(gè)當(dāng)前權(quán)重共 600000 種組合判為 QUEUED 的只有 600 組「新權(quán)重 ? 當(dāng)前權(quán)重」的取值集合只有一個(gè)元素[0]。畫面下半部分按主級拆成六行每行 100 組正好等于該主級下合法的子權(quán)個(gè)數(shù)——每個(gè)請求只在「與自己權(quán)重相等」的那一個(gè)當(dāng)前權(quán)重上入隊(duì)。也就是說能被入隊(duì)的任務(wù)權(quán)重必然與當(dāng)前播報(bào)權(quán)重嚴(yán)格相等——更高會(huì)被立即搶占更低會(huì)被丟棄只有相等才進(jìn)緩沖區(qū)。于是緩沖區(qū)里所有任務(wù)的權(quán)重全都相同F(xiàn)IFO 與「按權(quán)重排序」給出完全一樣的出隊(duì)順序。文檔沒寫排序鍵但在這個(gè)矩陣下寫不寫都不影響結(jié)果。這類推斷比「文檔沒寫所以不知道」有用得多。七、驗(yàn)證二用官方接口跑一次真實(shí)回環(huán)純算術(shù)只能驗(yàn)證規(guī)則驗(yàn)證不了契約。真正要確認(rèn)的是三件事接口里到底有哪些常量、越界值能不能發(fā)出去、矩陣的實(shí)際裁決是什么樣。先在容器里核對枚舉的可用性。這段代碼不需要真機(jī)、不需要啟動(dòng)節(jié)點(diǎn)只要 import 消息類型。# 節(jié)選自 ros2_ws/src/priority_lab/priority_lab/enum_probe.py # 為便于展示省略了「與文檔值是否相等」的比較分支 from aimdk_msgs.msg import TtsPriorityLevel # 依據(jù)《接口說明.md》2.2.1.2「TtsPriorityLevel (推薦主級常量列表)」逐條核對 DOC_TABLE [(BACKGROUND_L1, 1), (SERVICE_L2, 2), (MISSION_L4, 4), (INTERACTION_L6, 6), (SYSTEM_L7, 7), (WARNING_L8, 8), (SAFETY_L10, 10)] for name, doc_value in DOC_TABLE: try: actual int(getattr(TtsPriorityLevel, name)) print(f{name:16}{doc_value:8}0x{actual:02x}) except AttributeError: print(f{name:16}{doc_value:8}接口無此常量)圖 6 是ros2 run priority_lab enum_probe的原樣輸出。上半段逐條核對文檔 §2.2.1.2 的七個(gè)常量六個(gè)能取到SYSTEM_L7取不到分隔線以下的兩段是同一個(gè)腳本緊接著做的越界試驗(yàn)下面會(huì)用到。SYSTEM_L7在文檔 §2.2.1.2 的推薦常量表里帶著完整語義——「系統(tǒng)重要提示如電量低、網(wǎng)絡(luò)斷開」但它不在ros2 interface show里也不在aimdk_msgs/interaction/msg/、install/、build/三處.msg副本的任何一處。寫TtsPriorityLevel.SYSTEM_L7會(huì)直接拋AttributeError。那能不能硬填數(shù)字可以。類型層完全不校驗(yàn)——圖 6 下半段就是這件事value填 7、5、9、11 全部寫入成功并原樣讀回priority_weight填 100、250 也被接受按公式算出的最終權(quán)重分別是 700 與 850。weight 250這一條值得停一下850 直接落進(jìn)WARNING_L8的 800–899 區(qū)間——一個(gè)本該「微調(diào)」的參數(shù)越界之后能頂?shù)粽麢n。接口不攔只能靠調(diào)用方自覺。接下來是端到端。我按第四節(jié)那張矩陣實(shí)現(xiàn)了一個(gè)PlayTts服務(wù)端掛到官方aimdk_msgs/srv/PlayTts上然后依次發(fā) 8 個(gè)請求。# 節(jié)選自 ros2_ws/src/priority_lab/priority_lab/tts_client.py def build_request(level: int, weight: int, interrupt: bool, text: str) - PlayTts.Request: req PlayTts.Request() req.header.header.stamp.sec 0 req.tts_req.text text req.tts_req.priority_level.value level req.tts_req.priority_weight weight req.tts_req.domain priority_lab req.tts_req.trace_id flab-{level}-{weight}-{int(interrupt)} req.tts_req.is_interrupted interrupt return req客戶端看到的回執(zhí)圖 7 是ros2 run priority_lab tts_client的原樣輸出。code與state兩列取自aimdk_msgs通用響應(yīng)頭成功是 0/1失敗是 1/2時(shí)長列對應(yīng)estimated_duration八條全是 0。第 5、6 條被丟棄時(shí)客戶端多打一行└─ error_message把服務(wù)端給的原因原樣帶回來。服務(wù)端側(cè)的裁決日志真實(shí)時(shí)序[#n]是請求序號圖 8 是同一個(gè)容器里cat /tmp/mock.log的結(jié)果客戶端剛跑完日志就是那一刻寫下的。默認(rèn)的日志前綴級別、納秒時(shí)間戳、節(jié)點(diǎn)名被RCUTILS_CONSOLE_OUTPUT_FORMAT{message}去掉——帶上它每行超過 100 列終端里必然折行消息體一個(gè)字沒改。這份日志確認(rèn)了四件事第 4 條把value7填進(jìn)去接口照收且按 700 參與了排序成功搶占了 660。文檔檔位在類型層可用在枚舉層不可見——兩種狀態(tài)同時(shí)成立。第 3 條is_interruptedfalse仍被掐斷與矩陣一致與字段名字面相反。第 5 條is_interruptedtrue仍被丟棄同上。排隊(duì)任務(wù)最終自行出隊(duì)mock 里把單次播報(bào)占用設(shè)為 3 秒這是我設(shè)定的占位時(shí)長不是官方數(shù)值但客戶端全程收不到任何通知。這是個(gè)結(jié)構(gòu)性的缺口下面單獨(dú)說。關(guān)于最后一點(diǎn)的成因文檔寫得很直白時(shí)長字段局限由于 TTS 采用云端/本地流式合成當(dāng)前版本下estimated_duration固定返回0。任務(wù)閉環(huán)建議系統(tǒng)暫未開放播報(bào)結(jié)束的話題通知。若業(yè)務(wù)邏輯需在語音播報(bào)后執(zhí)行如先說話后走動(dòng)建議通過字?jǐn)?shù)預(yù)估約 200ms/字進(jìn)行延時(shí)處理?；貓?zhí)里的estimated_duration字段實(shí)測確實(shí)是0圖 7 的「時(shí)長」列八行全為 0。也就是說TTS 是一條開環(huán)鏈路調(diào)用方知道「請求進(jìn)隊(duì)了」但永遠(yuǎn)不知道「說完了沒有」只能拿字?jǐn)?shù)乘以 200 ms 去估。相比之下運(yùn)控的CommonTaskResponse帶task_id可以追蹤任務(wù)狀態(tài)。同一個(gè) SDK 里一個(gè)異步接口有任務(wù) ID另一個(gè)沒有——這屬于接口層的空白不是使用者的疏忽。需要說明的是這個(gè)PlayTts服務(wù)端是我按文檔矩陣實(shí)現(xiàn)的不是啟元的實(shí)現(xiàn)。它的作用是讓請求走真實(shí)的 ROS 2 序列化通道驗(yàn)證契約能通、字段能填、回執(zhí)能解析。真機(jī)上「第 3 條請求到底會(huì)不會(huì)被掐斷」「value7會(huì)不會(huì)被接受」仍需真機(jī)確認(rèn)。凡是 mock 得出的結(jié)論我在上文都標(biāo)了來源。八、為什么會(huì)分成三套把三處定義的文件路徑擺出來原因就清楚了aimdk_msgs/interaction/msg/PlayTtsRequest.msg—— TTS屬于交互控制模塊aimdk_msgs/hal/audio/msg/AudioFile.msg—— 音頻文件屬于硬件抽象模塊的audio子包aimdk_msgs/mc/msg/McInputSource.msg—— 輸入源屬于運(yùn)動(dòng)控制模塊三套機(jī)制分屬三個(gè)包、三個(gè)模塊、三撥人。它們各自解決各自領(lǐng)域里的排序問題各自設(shè)計(jì)了字段最終在字段名上撞了車。這不是誰抄錯(cuò)了誰而是分層架構(gòu)下同一概念在不同層各自演化的必然結(jié)果。從這個(gè)角度看三套設(shè)計(jì)其實(shí)各自都很合理運(yùn)控要的是安全兜底?？刂茩?quán)必須唯一否則兩路指令同時(shí)作用于關(guān)節(jié)后果是物理的。所以它用排他鎖還用 1000 ms 超時(shí)做看門狗——發(fā)流的一方一旦掛掉控制權(quán)必須自動(dòng)釋放不能讓機(jī)器人保持最后一條指令繼續(xù)動(dòng)。這里「優(yōu)先級」回答的是「誰在控制」。TTS 要的是順序與可打斷。語音是流式的可以排隊(duì)、可以中途掐斷掐斷了也不會(huì)有物理后果。所以它用復(fù)合權(quán)重主級管檔、子權(quán)管同檔內(nèi)的先后還單獨(dú)給了is_interrupted控制同級是否讓位。這里「優(yōu)先級」回答的是「誰先說」。音頻要的是混音。提示音和背景音樂可以同時(shí)響不需要一方靜音。所以它用百分比微調(diào)加音量閃避——警報(bào)聲響起時(shí)把音樂壓低而不是掐掉音樂。這里「優(yōu)先級」回答的是「誰蓋過誰」。三種「優(yōu)先級」對應(yīng)三種完全不同的資源模型獨(dú)占資源、隊(duì)列資源、混音資源。資源模型不同仲裁方式自然不能通用。硬要統(tǒng)一成一套字段反而會(huì)把三處都做壞。真正的問題不在設(shè)計(jì)在命名。三個(gè)模塊都用了priority和priority_weight這兩個(gè)詞而它們的量綱、算法、邊界各不相同?？缒K開發(fā)時(shí)前一處的直覺會(huì)直接帶到后一處出問題的地方往往連報(bào)錯(cuò)都沒有——運(yùn)控那邊靜默丟幀音頻那邊悄悄 duck只有 TTS 會(huì)給一個(gè)false。九、還沒解決的問題按重要程度排有五處AudioFile.priority_weight的運(yùn)算次序未定。第五節(jié)那兩種讀法跨檔能力差兩檔需要真機(jī)同時(shí)播兩個(gè)不同priority的文件、觀察實(shí)際輸出順序才能確定。無真機(jī)時(shí)斷言任何一種都是編數(shù)據(jù)。SYSTEM_L7是預(yù)留還是遺漏無法判斷。它在文檔里有完整語義在接口里沒有常量在權(quán)重空間里有位置。三種可能都存在正在實(shí)現(xiàn)中、文檔先寫了、或者實(shí)現(xiàn)時(shí)被砍了但文檔沒同步。沒有官方說明只能標(biāo)注現(xiàn)狀。緩沖區(qū)容量與溢出策略未定義。第六節(jié)能推出「緩沖區(qū)內(nèi)的任務(wù)權(quán)重全都相同」但推不出緩沖區(qū)能裝幾個(gè)、裝滿了丟新還是丟舊。TTS與音頻文件兩路之間如何交互文檔未展開。一個(gè) TTS 播報(bào)INTERACTION_L6權(quán)重 600與一個(gè)media_roleAlert的告警音角色優(yōu)先級 100同時(shí)觸發(fā)時(shí)誰讓誰兩者在不同模塊、不同層各自的排序鍵無法直接比較。media_role與priority的優(yōu)先級關(guān)系未說明。文檔只說「非 Music 角色播放時(shí)會(huì)自動(dòng)降低duck音樂音量」沒說priority高的 Music 會(huì)不會(huì)拒絕被 duck。這五處我都留在原樣沒有替它補(bǔ)。補(bǔ)出來的東西看著完整實(shí)際是錯(cuò)的——尤其第 1 條和第 4 條隨便寫一個(gè)「應(yīng)該是這樣」讀的人照著做問題會(huì)出現(xiàn)在幾個(gè)月后的現(xiàn)場調(diào)試?yán)铩Ｊ?、接手這套接口時(shí)先做四件事如果要在啟元 Q1 上寫播報(bào)相關(guān)的業(yè)務(wù)按這個(gè)順序過一遍能避開大部分坑第一先確定你要用的是哪一套。是讓機(jī)器人「說一句話」PlayTts還是「放一個(gè)音頻文件」PlayAudioFile前者走交互模塊后者走硬件抽象模塊兩套的priority_weight含義不同。選錯(cuò)了接口后面調(diào)參數(shù)全是白調(diào)。第二priority_level只用接口里那 6 個(gè)常量。不要照著文檔寫SYSTEM_L7——編譯期就會(huì)失敗。如果確實(shí)需要「系統(tǒng)重要提示」這一檔用INTERACTION_L6或WARNING_L8或者硬填value7并接受它是一個(gè)接口不承認(rèn)的檔位。第三不要把is_interrupted當(dāng)成插隊(duì)開關(guān)。它只決定同級是否讓位。想讓一句話壓過正在播的內(nèi)容唯一可靠的手段是提高priority_level——但記住子權(quán)跨不了級L499仍然低于L60。第四給播報(bào)留出時(shí)間余量。PlayTts返回is_successtrue只代表進(jìn)隊(duì)了estimated_duration恒為 0沒有播報(bào)結(jié)束話題。要在播報(bào)后執(zhí)行動(dòng)作比如先說話再走動(dòng)只能按字?jǐn)?shù)估——文檔給的經(jīng)驗(yàn)值是約 200 ms/字單次播報(bào)建議控制在 100 字以內(nèi)。這四條不需要真機(jī)就能驗(yàn)證前三條第四條在真機(jī)上用秒表對一次字?jǐn)?shù)與時(shí)長就能把估算公式校準(zhǔn)成自己的系數(shù)。三套優(yōu)先級并存的局面短期不會(huì)改變——它們分屬三個(gè)模塊各自服務(wù)不同的資源模型統(tǒng)一命名的收益遠(yuǎn)小于改動(dòng)的風(fēng)險(xiǎn)。對開發(fā)者來說能做的事只有一件把它們的差異記清楚別用一套的直覺去寫另一套的代碼。本文用到的規(guī)則復(fù)現(xiàn)、枚舉核對、矩陣驗(yàn)證腳本都放在 AtomGit 上無需真機(jī)即可復(fù)現(xiàn)https://atomgit.com/2301_76341691/primebot-priority-taxonomy-lab如果你也在啟元機(jī)器人上做二次開發(fā)歡迎到啟元機(jī)器人開發(fā)者社區(qū) https://dev.primebot.com/ 交流那里有官方文檔、SDK 倉庫入口和開發(fā)者討論區(qū)。文中若有不準(zhǔn)確的地方也歡迎在倉庫提 Issue 指出來。 啟元 Q1 的三套優(yōu)先級：排他鎖、復(fù)合權(quán)重與音量閃避
一、從一個(gè)字段名說起AudioFile.msg里有這么一行注釋# 可選項(xiàng)(1~100) priority priority_weight% is final priority uint32 priority_weight而PlayTtsRequest.msg里同樣叫priority_weight的字段注釋是這樣的# 可選非產(chǎn)品要求勿用優(yōu)先級加權(quán)參數(shù)(0-99)最小單位為 1 uint32 priority_weight兩個(gè)字段同名、同類型都是uint32含義卻差得很遠(yuǎn)。前者的取值范圍是 1–100是個(gè)百分比后者是 0–99是個(gè)絕對偏移。更關(guān)鍵的是PlayTts的最終權(quán)重算法在《接口說明.md》里寫得很明確最終權(quán)重 主級 * 100 子權(quán)也就是說TTS 的priority_weight直接加到百位以上而音頻文件那邊它是對priority做一個(gè)百分比調(diào)整。同樣是「微調(diào)優(yōu)先級」一處加在百位一處加在個(gè)位還帶著百分號。我最初以為這是文檔寫錯(cuò)了。把三套機(jī)制的定義都取出來放在一起之后才看清楚不是寫錯(cuò)是三套獨(dú)立設(shè)計(jì)的優(yōu)先級機(jī)制恰好共享了兩個(gè)字段名。這篇文章拆的就是這三套機(jī)制。它們分別屬于運(yùn)控輸入源、TTS 播報(bào)、音頻文件播放各有各的取值空間、比較方式和失敗行為。搞混任何一處代碼都會(huì)在沒有任何報(bào)錯(cuò)的情況下做出錯(cuò)誤行為——這是我在實(shí)測里反復(fù)撞到的同一類問題。二、三套機(jī)制并排看先把三套機(jī)制放在一張表里。機(jī)制接口字段取值空間主級形態(tài)比較方式低優(yōu)先級方的結(jié)果運(yùn)控輸入源SetMcInputSourcepriority0–100 連續(xù)整數(shù)連續(xù)排他鎖先到先得幀被靜默丟棄1000 ms 看門狗脫鎖TTS 播報(bào)PlayTtspriority_levelpriority_weight主級 6 檔 × 子權(quán) 0–99跳段復(fù)合權(quán)重比大小同步返回is_successfalse高權(quán)重可中途掐斷音頻文件PlayAudioFileprioritypriority_weightmedia_rolepriority1–10weight1–100(%)連續(xù)百分比加權(quán)不終止靠音量閃避duck讓位三套機(jī)制連「失敗」的定義都不同運(yùn)控那邊輸?shù)囊环绞裁炊疾粫?huì)收到只能靠自己周期性查詢才發(fā)現(xiàn)控制權(quán)沒了TTS 那邊輸?shù)囊环綍?huì)收到一個(gè)明確的false音頻那邊輸?shù)囊环郊葲]有錯(cuò)誤也沒有終止只是音量被壓低。把它們畫成刻度形狀的差異更直觀。圖 1 中三條刻度各自獨(dú)立歸一化橫向長度不代表數(shù)值大小只用來看結(jié)構(gòu)運(yùn)控是均質(zhì)的連續(xù)刻度TTS 是跳段的離散塊跳過 3、5、9音頻是連續(xù)刻度上再疊一套四檔角色。圖中 L1–L10 的權(quán)重區(qū)間、priority的 1–10 取值、media_role的 40/60/80/100 四檔全部取自對應(yīng).msg文件與《接口說明.md》§2.1.1.4、§2.2.1.2、§2.2.1.3 三節(jié)。有一處值得單獨(dú)指出音頻文件播放那一行priority是 1–10而 TTS 的主級恰好也是 1、2、4、6、8、10 這幾個(gè)數(shù)字。數(shù)值看起來一樣含義毫無關(guān)系。AudioFile.priority是連續(xù)的 1–10默認(rèn) 6相鄰值只差一檔TtsPriorityLevel的主級是枚舉語義層跳過的那些值是為將來插入新檔位預(yù)留的位置。把priority_level 6的經(jīng)驗(yàn)搬到AudioFile.priority 6讀起來像實(shí)際語義完全不同。三、TTS 的權(quán)重空間99 與 100 的那 1 之隔TTS 這套最值得細(xì)看因?yàn)樗乃阈g(shù)規(guī)則寫得最明確而邊界恰好踩在一個(gè)很微妙的位置上。TtsPriorityLevel.msg在接口里實(shí)際只定義了 6 個(gè)有效檔位uint8 value uint8 UNKNOWN 0x00 # 后臺(tái)服務(wù)層 uint8 BACKGROUND_L1 0x01 # 主動(dòng)服務(wù)層 uint8 SERVICE_L2 0x02 # 任務(wù)執(zhí)行層 uint8 MISSION_L4 0x04 # 交互相應(yīng)層 uint8 INTERACTION_L6 0x06 # 危險(xiǎn)預(yù)警層 uint8 WARNING_L8 0x08 # 生命安全層 uint8 SAFETY_L10 0x0a主級取 1、2、4、6、8、10步長 2跳過 3、5、7、9。配合「最終權(quán)重 主級 × 100 子權(quán)」就得到下面這張取值表。常量value最終權(quán)重區(qū)間來源BACKGROUND_L10x01100 – 199接口 文檔SERVICE_L20x02200 – 299接口 文檔MISSION_L40x04400 – 499接口 文檔INTERACTION_L60x06600 – 699接口 文檔WARNING_L80x08800 – 899接口 文檔SAFETY_L100x0a1000 – 1099接口 文檔SYSTEM_L77700 – 799僅文檔接口無此常量表中最后一行的SYSTEM_L7是這篇文章的一個(gè)關(guān)鍵發(fā)現(xiàn)后面第七節(jié)會(huì)給出實(shí)測證據(jù)。先看一個(gè)更基礎(chǔ)的性質(zhì)。子權(quán)上限是 99主級步長是 100。相差 1這個(gè) 1 不是巧合。圖 2 的橫軸是最終權(quán)重1 單位對應(yīng) 1 像素?？梢灾庇^看到L4用滿子權(quán)封頂 499L6一個(gè)子權(quán)都不給也有 600兩者相差 101。中間那 100 個(gè)整數(shù)位500–599沒有任何檔位覆蓋。這意味著子權(quán)的作用半徑被精確限制在同檔內(nèi)部。任何一個(gè)「低一檔但更緊急」的播報(bào)都沒有任何可用手段能頂?shù)缴弦粰n去——把priority_weight調(diào)到 99也只是讓它在本檔里排到最前面。這是設(shè)計(jì)上的精確也是設(shè)計(jì)上的代價(jià)。它換來的是排序的絕對可預(yù)測性主級一旦確定跨檔關(guān)系就鎖死了不會(huì)因?yàn)槟硞€(gè)調(diào)用方擅自把子權(quán)拉滿而產(chǎn)生檔位穿透。代價(jià)是分層變得剛性——如果產(chǎn)品上確實(shí)需要「低一檔的緊急播報(bào)壓過高檔的例行播報(bào)」這套算術(shù)給不出解法只能改主級。再看那些空檔。接口里的主級是 1、2、4、6、8、10跳過 3、5、7、9對應(yīng) 300–399、500–599、700–799、900–999 四段。其中 700–799 被文檔的SYSTEM_L7填上了另外三段仍然空著。這不是浪費(fèi)是預(yù)留往這些區(qū)間插入新檔位不會(huì)擾動(dòng)任何已有排序。SYSTEM_L7的位置完全合理——它就在L6與L8之間那個(gè)天然的空位里問題只在于接口沒給它常量。四、仲裁矩陣兩格與字面意思相反權(quán)重算出來之后誰先播、誰被打斷由《接口說明.md》§2.2.1.2 的四格矩陣決定。文檔原文是這樣的權(quán)重對比is_interrupted: trueis_interrupted: false新任務(wù)權(quán)重 ≥ 當(dāng)前任務(wù)當(dāng)前播報(bào)被立即掐斷且不可恢復(fù)新語音開始播放仲裁優(yōu)先級相同時(shí)存入緩沖區(qū)仲裁優(yōu)先級大于當(dāng)前任務(wù)時(shí)強(qiáng)制打斷新任務(wù)權(quán)重 當(dāng)前任務(wù)請求丟棄is_success: false請求丟棄is_success: false這張表里藏著兩個(gè)與字段名字面意思相反的結(jié)論我在實(shí)測中逐一確認(rèn)過。圖 3 把四格矩陣與實(shí)測樣本畫在一起。格內(nèi)樣本編號對應(yīng)第七節(jié) 8 個(gè)場景的序號服務(wù)端為按該矩陣實(shí)現(xiàn)的 mock非真機(jī)行為。第一個(gè)反直覺點(diǎn)is_interrupted true不是強(qiáng)制插隊(duì)開關(guān)。按字面理解「打斷true」應(yīng)該意味著「我有話要說現(xiàn)在就說」。但矩陣寫得清楚這一列只在「新權(quán)重 ≥ 當(dāng)前」那一行才起作用權(quán)重不足時(shí)填true一樣被丟棄。實(shí)測中第 5 條請求L62 602當(dāng)前播報(bào)是 700即使is_interruptedtrue返回的仍是is_successfalseerror_message寫著「權(quán)重 602 當(dāng)前 700」。第二個(gè)反直覺點(diǎn)is_interrupted false不保證不被打斷。同樣按字面理解「不打斷」應(yīng)該意味著「別掐我」。但矩陣在false這一列寫的是「大于則強(qiáng)制打斷」。實(shí)測第 3 條請求L660 660當(dāng)前是 600is_interruptedfalse結(jié)果仍是PREEMPT_NOW——非搶占模式下權(quán)重更高照樣掐斷。兩點(diǎn)合起來這個(gè)字段的真實(shí)語義是「權(quán)重足夠時(shí)同檔要不要讓」。它管的是同級仲裁不是插隊(duì)權(quán)。而文檔對這個(gè)字段有三處描述只有一處與矩陣一致出處原文與矩陣是否一致PlayTtsRequest.msg注釋是否打斷同等優(yōu)先級播報(bào)true打斷false不打斷進(jìn)入隊(duì)列播報(bào)一致§2.2.1.2 字段表是否打斷現(xiàn)有任務(wù)true: 立即搶占false: 自動(dòng)排隊(duì)不一致§2.2.1.2 仲裁矩陣見上表—.msg注釋說的是「同等優(yōu)先級」與矩陣吻合字段表說的是「現(xiàn)有任務(wù)」把范圍放大了。差別就在這一行照字段表理解會(huì)寫出一個(gè)自己以為安全的調(diào)用——以為什么都不填就萬事大吉實(shí)際只要權(quán)重夠高就會(huì)被掐。五、音頻一處未閉合的歧義AudioFile.msg那一行的原文是# 可選項(xiàng)(1~100) priority priority_weight% is final priority uint32 priority_weight它給了表達(dá)式?jīng)]給運(yùn)算次序。至少有兩種都能自圓其說的讀法讀法 A加性final priority weight / 100讀法 B乘性final priority × (1 weight / 100)兩種讀法在權(quán)重較小時(shí)結(jié)果相近在權(quán)重接近上限時(shí)結(jié)論相反。輸入 1A 值輸入 2A 值A(chǔ) 判定B 值 1B 值 2B 判定是否分歧p6 50%6.50p7 0%7.00后者9.007.00前者分歧p6 100%7.00p7 0%7.00平手12.007.00前者分歧p6 100%7.00p10 0%10.00后者12.0010.00前者分歧p6 10%6.10p7 0%7.00后者6.607.00后者一致讀法 A 的跨檔上限是固定的增量恒 ≤ 1.0所以priority6用滿權(quán)重最多追平 7永遠(yuǎn)超不過相當(dāng)于「一檔之內(nèi)微調(diào)」。讀法 B 在weight100時(shí)直接翻倍priority6可以壓過 7 甚至 10相當(dāng)于「變相增加一到兩檔」。同一個(gè)字段兩種讀法跨檔能力差了兩檔。這不是筆誤級別的歧義是會(huì)影響排序結(jié)果的歧義。我沒有替它下結(jié)論因?yàn)檫@需要真機(jī)實(shí)測才能確定用兩個(gè)不同priority的音頻文件同時(shí)播放觀察實(shí)際輸出順序。在沒有真機(jī)的情況下斷言其中一種就是在編數(shù)據(jù)。這一處我留在第九節(jié)的「未決問題」里。順帶一提AudioFile還有第三個(gè)維度media_role。# 可選項(xiàng)PulseAudio media.role不傳默認(rèn) Music # 可選值A(chǔ)lert(系統(tǒng)告警,優(yōu)先級100) | Notification(系統(tǒng)提示音,優(yōu)先級80) | Communication(對話語音,優(yōu)先級60) | Music(音樂/媒體,優(yōu)先級40,默認(rèn)) # 非 Music 角色播放時(shí)會(huì)自動(dòng)降低(duck)音樂音量 string media_role這是第四套編號40/60/80/100由 PulseAudio 的角色體系決定與priority完全并行。所以嚴(yán)格說音頻這一路內(nèi)部同時(shí)跑著兩套排序一套是應(yīng)用層的priority 百分比一套是系統(tǒng)音頻服務(wù)層的media_role。前者決定誰先播后者決定誰壓低誰。這兩套之間如何交互文檔沒有展開。六、驗(yàn)證一把規(guī)則寫成代碼三套機(jī)制的規(guī)則都是純算術(shù)可以脫離 ROS 完整復(fù)現(xiàn)。我把它們寫成了一個(gè)零依賴的模塊只用標(biāo)準(zhǔn)庫。下面節(jié)選自taxonomy/levels.py完整文件在倉庫里。TTS_LEVEL_STRIDE 100 TTS_WEIGHT_MAX 99 def tts_final_weight(level_value: int, priority_weight: int) - int: 最終權(quán)重 主級 * 100 子權(quán)。 return level_value * TTS_LEVEL_STRIDE priority_weight def sub_weight_can_cross_level() - bool: 子權(quán)能否跨越主級子權(quán)上界 99主級步長 100。 return (TTS_WEIGHT_MAX 1) TTS_LEVEL_STRIDE這個(gè)函數(shù)不做范圍鉗制因?yàn)榻涌趯油瑯硬蛔觥猵riority_weight聲明為uint320–99 只是文檔約定類型系統(tǒng)擋不住 100 以上的輸入。這一點(diǎn)第七節(jié)的實(shí)測會(huì)確認(rèn)。跑一遍邊界場景命令與輸出都在圖 4 里。從這一處起凡是程序輸出一律給真實(shí)終端截圖不再手抄——寫稿時(shí)把輸出貼進(jìn)代碼塊最容易出的錯(cuò)不是抄錯(cuò)數(shù)字而是抄錯(cuò)一個(gè)自己沒注意到的對齊空格。python3 scenarios/run.py weight圖 4 是容器pgc/primebot-humble:1.0內(nèi)的真實(shí)終端畫面Xvfb 上起一個(gè) 80×32 的 xterm用偽終端把命令逐條敲進(jìn)交互式 bash等輸出定格后用 ImageMagick 抓窗口未做任何裁剪與修飾。畫面上半部分是七個(gè)檔位的取值區(qū)間下半部分是相鄰兩級的臨界值——L1滿子權(quán) 199 對上L2零子權(quán) 200只差 1其余各相鄰對都差 101。這個(gè)「差 1」正是子權(quán)跨不了級的算術(shù)來源。抓圖腳本在倉庫tools/shot/下all_shots.sh一次跑完本文全部五張終端圖可以原樣復(fù)現(xiàn)。除了驗(yàn)證算術(shù)我還用窮舉確認(rèn)了一個(gè)文檔沒寫、但可以從矩陣推出來的結(jié)論。問題是is_interruptedfalse時(shí)入隊(duì)的任務(wù)按什么順序出隊(duì)文檔只寫「存入緩沖區(qū)在當(dāng)前任務(wù)播放完成后再進(jìn)行處理」沒說排序鍵。# 節(jié)選自 scenarios/exhaustive_queue.py 的 compute() def compute(): 返回 (入隊(duì)總數(shù), 差值-次數(shù), 主級-入隊(duì)數(shù))。純函數(shù)供 run.py 復(fù)用。 queued_diffs: dict {} per_level: dict {lv: 0 for lv in TTS_VALID_LEVEL_VALUES} total_queued 0 for level in TTS_VALID_LEVEL_VALUES: # 6 個(gè)合法主級 for w in range(0, TTS_WEIGHT_MAX 1): # 子權(quán) 0-99 req TtsRequest(probe, level, w, False) for current in range(CURRENT_MIN, CURRENT_MAX 1): # 100-1099 if arbitrate(req, current) is Verdict.QUEUED: total_queued 1 per_level[level] 1 diff req.weight - current queued_diffs[diff] queued_diffs.get(diff, 0) 1 return total_queued, queued_diffs, per_level圖 5 與圖 4 出自同一個(gè)容器、同一次會(huì)話、同一套抓圖流程。畫面里先確認(rèn)解釋器版本為 Python 3.10.12再執(zhí)行scenarios/exhaustive_queue.py600 個(gè)合法請求 × 1000 個(gè)當(dāng)前權(quán)重共 600000 種組合判為 QUEUED 的只有 600 組「新權(quán)重 ? 當(dāng)前權(quán)重」的取值集合只有一個(gè)元素[0]。畫面下半部分按主級拆成六行每行 100 組正好等于該主級下合法的子權(quán)個(gè)數(shù)——每個(gè)請求只在「與自己權(quán)重相等」的那一個(gè)當(dāng)前權(quán)重上入隊(duì)。也就是說能被入隊(duì)的任務(wù)權(quán)重必然與當(dāng)前播報(bào)權(quán)重嚴(yán)格相等——更高會(huì)被立即搶占更低會(huì)被丟棄只有相等才進(jìn)緩沖區(qū)。于是緩沖區(qū)里所有任務(wù)的權(quán)重全都相同F(xiàn)IFO 與「按權(quán)重排序」給出完全一樣的出隊(duì)順序。文檔沒寫排序鍵但在這個(gè)矩陣下寫不寫都不影響結(jié)果。這類推斷比「文檔沒寫所以不知道」有用得多。七、驗(yàn)證二用官方接口跑一次真實(shí)回環(huán)純算術(shù)只能驗(yàn)證規(guī)則驗(yàn)證不了契約。真正要確認(rèn)的是三件事接口里到底有哪些常量、越界值能不能發(fā)出去、矩陣的實(shí)際裁決是什么樣。先在容器里核對枚舉的可用性。這段代碼不需要真機(jī)、不需要啟動(dòng)節(jié)點(diǎn)只要 import 消息類型。# 節(jié)選自 ros2_ws/src/priority_lab/priority_lab/enum_probe.py # 為便于展示省略了「與文檔值是否相等」的比較分支 from aimdk_msgs.msg import TtsPriorityLevel # 依據(jù)《接口說明.md》2.2.1.2「TtsPriorityLevel (推薦主級常量列表)」逐條核對 DOC_TABLE [(BACKGROUND_L1, 1), (SERVICE_L2, 2), (MISSION_L4, 4), (INTERACTION_L6, 6), (SYSTEM_L7, 7), (WARNING_L8, 8), (SAFETY_L10, 10)] for name, doc_value in DOC_TABLE: try: actual int(getattr(TtsPriorityLevel, name)) print(f{name:16}{doc_value:8}0x{actual:02x}) except AttributeError: print(f{name:16}{doc_value:8}接口無此常量)圖 6 是ros2 run priority_lab enum_probe的原樣輸出。上半段逐條核對文檔 §2.2.1.2 的七個(gè)常量六個(gè)能取到SYSTEM_L7取不到分隔線以下的兩段是同一個(gè)腳本緊接著做的越界試驗(yàn)下面會(huì)用到。SYSTEM_L7在文檔 §2.2.1.2 的推薦常量表里帶著完整語義——「系統(tǒng)重要提示如電量低、網(wǎng)絡(luò)斷開」但它不在ros2 interface show里也不在aimdk_msgs/interaction/msg/、install/、build/三處.msg副本的任何一處。寫TtsPriorityLevel.SYSTEM_L7會(huì)直接拋AttributeError。那能不能硬填數(shù)字可以。類型層完全不校驗(yàn)——圖 6 下半段就是這件事value填 7、5、9、11 全部寫入成功并原樣讀回priority_weight填 100、250 也被接受按公式算出的最終權(quán)重分別是 700 與 850。weight 250這一條值得停一下850 直接落進(jìn)WARNING_L8的 800–899 區(qū)間——一個(gè)本該「微調(diào)」的參數(shù)越界之后能頂?shù)粽麢n。接口不攔只能靠調(diào)用方自覺。接下來是端到端。我按第四節(jié)那張矩陣實(shí)現(xiàn)了一個(gè)PlayTts服務(wù)端掛到官方aimdk_msgs/srv/PlayTts上然后依次發(fā) 8 個(gè)請求。# 節(jié)選自 ros2_ws/src/priority_lab/priority_lab/tts_client.py def build_request(level: int, weight: int, interrupt: bool, text: str) - PlayTts.Request: req PlayTts.Request() req.header.header.stamp.sec 0 req.tts_req.text text req.tts_req.priority_level.value level req.tts_req.priority_weight weight req.tts_req.domain priority_lab req.tts_req.trace_id flab-{level}-{weight}-{int(interrupt)} req.tts_req.is_interrupted interrupt return req客戶端看到的回執(zhí)圖 7 是ros2 run priority_lab tts_client的原樣輸出。code與state兩列取自aimdk_msgs通用響應(yīng)頭成功是 0/1失敗是 1/2時(shí)長列對應(yīng)estimated_duration八條全是 0。第 5、6 條被丟棄時(shí)客戶端多打一行└─ error_message把服務(wù)端給的原因原樣帶回來。服務(wù)端側(cè)的裁決日志真實(shí)時(shí)序[#n]是請求序號圖 8 是同一個(gè)容器里cat /tmp/mock.log的結(jié)果客戶端剛跑完日志就是那一刻寫下的。默認(rèn)的日志前綴級別、納秒時(shí)間戳、節(jié)點(diǎn)名被RCUTILS_CONSOLE_OUTPUT_FORMAT{message}去掉——帶上它每行超過 100 列終端里必然折行消息體一個(gè)字沒改。這份日志確認(rèn)了四件事第 4 條把value7填進(jìn)去接口照收且按 700 參與了排序成功搶占了 660。文檔檔位在類型層可用在枚舉層不可見——兩種狀態(tài)同時(shí)成立。第 3 條is_interruptedfalse仍被掐斷與矩陣一致與字段名字面相反。第 5 條is_interruptedtrue仍被丟棄同上。排隊(duì)任務(wù)最終自行出隊(duì)mock 里把單次播報(bào)占用設(shè)為 3 秒這是我設(shè)定的占位時(shí)長不是官方數(shù)值但客戶端全程收不到任何通知。這是個(gè)結(jié)構(gòu)性的缺口下面單獨(dú)說。關(guān)于最后一點(diǎn)的成因文檔寫得很直白時(shí)長字段局限由于 TTS 采用云端/本地流式合成當(dāng)前版本下estimated_duration固定返回0。任務(wù)閉環(huán)建議系統(tǒng)暫未開放播報(bào)結(jié)束的話題通知。若業(yè)務(wù)邏輯需在語音播報(bào)后執(zhí)行如先說話后走動(dòng)建議通過字?jǐn)?shù)預(yù)估約 200ms/字進(jìn)行延時(shí)處理?；貓?zhí)里的estimated_duration字段實(shí)測確實(shí)是0圖 7 的「時(shí)長」列八行全為 0。也就是說TTS 是一條開環(huán)鏈路調(diào)用方知道「請求進(jìn)隊(duì)了」但永遠(yuǎn)不知道「說完了沒有」只能拿字?jǐn)?shù)乘以 200 ms 去估。相比之下運(yùn)控的CommonTaskResponse帶task_id可以追蹤任務(wù)狀態(tài)。同一個(gè) SDK 里一個(gè)異步接口有任務(wù) ID另一個(gè)沒有——這屬于接口層的空白不是使用者的疏忽。需要說明的是這個(gè)PlayTts服務(wù)端是我按文檔矩陣實(shí)現(xiàn)的不是啟元的實(shí)現(xiàn)。它的作用是讓請求走真實(shí)的 ROS 2 序列化通道驗(yàn)證契約能通、字段能填、回執(zhí)能解析。真機(jī)上「第 3 條請求到底會(huì)不會(huì)被掐斷」「value7會(huì)不會(huì)被接受」仍需真機(jī)確認(rèn)。凡是 mock 得出的結(jié)論我在上文都標(biāo)了來源。八、為什么會(huì)分成三套把三處定義的文件路徑擺出來原因就清楚了aimdk_msgs/interaction/msg/PlayTtsRequest.msg—— TTS屬于交互控制模塊aimdk_msgs/hal/audio/msg/AudioFile.msg—— 音頻文件屬于硬件抽象模塊的audio子包aimdk_msgs/mc/msg/McInputSource.msg—— 輸入源屬于運(yùn)動(dòng)控制模塊三套機(jī)制分屬三個(gè)包、三個(gè)模塊、三撥人。它們各自解決各自領(lǐng)域里的排序問題各自設(shè)計(jì)了字段最終在字段名上撞了車。這不是誰抄錯(cuò)了誰而是分層架構(gòu)下同一概念在不同層各自演化的必然結(jié)果。從這個(gè)角度看三套設(shè)計(jì)其實(shí)各自都很合理運(yùn)控要的是安全兜底?？刂茩?quán)必須唯一否則兩路指令同時(shí)作用于關(guān)節(jié)后果是物理的。所以它用排他鎖還用 1000 ms 超時(shí)做看門狗——發(fā)流的一方一旦掛掉控制權(quán)必須自動(dòng)釋放不能讓機(jī)器人保持最后一條指令繼續(xù)動(dòng)。這里「優(yōu)先級」回答的是「誰在控制」。TTS 要的是順序與可打斷。語音是流式的可以排隊(duì)、可以中途掐斷掐斷了也不會(huì)有物理后果。所以它用復(fù)合權(quán)重主級管檔、子權(quán)管同檔內(nèi)的先后還單獨(dú)給了is_interrupted控制同級是否讓位。這里「優(yōu)先級」回答的是「誰先說」。音頻要的是混音。提示音和背景音樂可以同時(shí)響不需要一方靜音。所以它用百分比微調(diào)加音量閃避——警報(bào)聲響起時(shí)把音樂壓低而不是掐掉音樂。這里「優(yōu)先級」回答的是「誰蓋過誰」。三種「優(yōu)先級」對應(yīng)三種完全不同的資源模型獨(dú)占資源、隊(duì)列資源、混音資源。資源模型不同仲裁方式自然不能通用。硬要統(tǒng)一成一套字段反而會(huì)把三處都做壞。真正的問題不在設(shè)計(jì)在命名。三個(gè)模塊都用了priority和priority_weight這兩個(gè)詞而它們的量綱、算法、邊界各不相同?？缒K開發(fā)時(shí)前一處的直覺會(huì)直接帶到后一處出問題的地方往往連報(bào)錯(cuò)都沒有——運(yùn)控那邊靜默丟幀音頻那邊悄悄 duck只有 TTS 會(huì)給一個(gè)false。九、還沒解決的問題按重要程度排有五處AudioFile.priority_weight的運(yùn)算次序未定。第五節(jié)那兩種讀法跨檔能力差兩檔需要真機(jī)同時(shí)播兩個(gè)不同priority的文件、觀察實(shí)際輸出順序才能確定。無真機(jī)時(shí)斷言任何一種都是編數(shù)據(jù)。SYSTEM_L7是預(yù)留還是遺漏無法判斷。它在文檔里有完整語義在接口里沒有常量在權(quán)重空間里有位置。三種可能都存在正在實(shí)現(xiàn)中、文檔先寫了、或者實(shí)現(xiàn)時(shí)被砍了但文檔沒同步。沒有官方說明只能標(biāo)注現(xiàn)狀。緩沖區(qū)容量與溢出策略未定義。第六節(jié)能推出「緩沖區(qū)內(nèi)的任務(wù)權(quán)重全都相同」但推不出緩沖區(qū)能裝幾個(gè)、裝滿了丟新還是丟舊。TTS與音頻文件兩路之間如何交互文檔未展開。一個(gè) TTS 播報(bào)INTERACTION_L6權(quán)重 600與一個(gè)media_roleAlert的告警音角色優(yōu)先級 100同時(shí)觸發(fā)時(shí)誰讓誰兩者在不同模塊、不同層各自的排序鍵無法直接比較。media_role與priority的優(yōu)先級關(guān)系未說明。文檔只說「非 Music 角色播放時(shí)會(huì)自動(dòng)降低duck音樂音量」沒說priority高的 Music 會(huì)不會(huì)拒絕被 duck。這五處我都留在原樣沒有替它補(bǔ)。補(bǔ)出來的東西看著完整實(shí)際是錯(cuò)的——尤其第 1 條和第 4 條隨便寫一個(gè)「應(yīng)該是這樣」讀的人照著做問題會(huì)出現(xiàn)在幾個(gè)月后的現(xiàn)場調(diào)試?yán)铩Ｊ?、接手這套接口時(shí)先做四件事如果要在啟元 Q1 上寫播報(bào)相關(guān)的業(yè)務(wù)按這個(gè)順序過一遍能避開大部分坑第一先確定你要用的是哪一套。是讓機(jī)器人「說一句話」PlayTts還是「放一個(gè)音頻文件」PlayAudioFile前者走交互模塊后者走硬件抽象模塊兩套的priority_weight含義不同。選錯(cuò)了接口后面調(diào)參數(shù)全是白調(diào)。第二priority_level只用接口里那 6 個(gè)常量。不要照著文檔寫SYSTEM_L7——編譯期就會(huì)失敗。如果確實(shí)需要「系統(tǒng)重要提示」這一檔用INTERACTION_L6或WARNING_L8或者硬填value7并接受它是一個(gè)接口不承認(rèn)的檔位。第三不要把is_interrupted當(dāng)成插隊(duì)開關(guān)。它只決定同級是否讓位。想讓一句話壓過正在播的內(nèi)容唯一可靠的手段是提高priority_level——但記住子權(quán)跨不了級L499仍然低于L60。第四給播報(bào)留出時(shí)間余量。PlayTts返回is_successtrue只代表進(jìn)隊(duì)了estimated_duration恒為 0沒有播報(bào)結(jié)束話題。要在播報(bào)后執(zhí)行動(dòng)作比如先說話再走動(dòng)只能按字?jǐn)?shù)估——文檔給的經(jīng)驗(yàn)值是約 200 ms/字單次播報(bào)建議控制在 100 字以內(nèi)。這四條不需要真機(jī)就能驗(yàn)證前三條第四條在真機(jī)上用秒表對一次字?jǐn)?shù)與時(shí)長就能把估算公式校準(zhǔn)成自己的系數(shù)。三套優(yōu)先級并存的局面短期不會(huì)改變——它們分屬三個(gè)模塊各自服務(wù)不同的資源模型統(tǒng)一命名的收益遠(yuǎn)小于改動(dòng)的風(fēng)險(xiǎn)。對開發(fā)者來說能做的事只有一件把它們的差異記清楚別用一套的直覺去寫另一套的代碼。本文用到的規(guī)則復(fù)現(xiàn)、枚舉核對、矩陣驗(yàn)證腳本都放在 AtomGit 上無需真機(jī)即可復(fù)現(xiàn)https://atomgit.com/2301_76341691/primebot-priority-taxonomy-lab如果你也在啟元機(jī)器人上做二次開發(fā)歡迎到啟元機(jī)器人開發(fā)者社區(qū) https://dev.primebot.com/ 交流那里有官方文檔、SDK 倉庫入口和開發(fā)者討論區(qū)。文中若有不準(zhǔn)確的地方也歡迎在倉庫提 Issue 指出來。