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