HarmonyOS 7.0 / API 26 小藝智能體入口實(shí)戰(zhàn)意圖參數(shù)、會(huì)話上下文和錯(cuò)誤兜底如何閉環(huán)先把問(wèn)題說(shuō)清楚智能體入口看起來(lái)像一句話跳轉(zhuǎn)實(shí)際落到應(yīng)用里會(huì)變成參數(shù)缺失、上下文過(guò)期和頁(yè)面狀態(tài)不一致。 這類問(wèn)題看起來(lái)像一個(gè)新能力適配問(wèn)題真正寫代碼時(shí)會(huì)變成三件事什么時(shí)候能用、失敗時(shí)怎么退、結(jié)果怎么驗(yàn)證。我這篇不按功能介紹來(lái)寫而是按排查順序?qū)?。先確定 HarmonyOS 7.0 / API 26 的能力邊界再做兩個(gè)能復(fù)現(xiàn)的場(chǎng)景最后把處理邏輯收口成一個(gè)小封裝。這樣以后換到別的頁(yè)面或者別的設(shè)備形態(tài)也能沿用同一套判斷方式。官方能力點(diǎn)先對(duì)齊檢查項(xiàng)這篇怎么落地系統(tǒng)版本面向 HarmonyOS 7.0 / API 26 的能力適配思路底線滿足 HarmonyOS 5.0.0 及以上活動(dòng)要求文章方向HarmonyOS 新能力、多設(shè)備應(yīng)用開(kāi)發(fā)、性能穩(wěn)定性或上架質(zhì)量核心特性小藝智能體舊版本差異舊寫法容易把智能體入口當(dāng)普通路由只傳一個(gè)頁(yè)面名剩下的讓頁(yè)面自己猜。新處理重點(diǎn)API 26 方向要把意圖、參數(shù)校驗(yàn)、會(huì)話上下文、頁(yè)面兜底和日志串起來(lái)。這里最容易踩坑的是把“能調(diào)通”當(dāng)成“能上線”。能調(diào)通只說(shuō)明主路徑?jīng)]問(wèn)題真正上線前還要看失敗路徑、降級(jí)路徑、日志字段和多設(shè)備邊界。驗(yàn)證環(huán)境和復(fù)現(xiàn)口徑這篇按 HarmonyOS 7.0 / API 26 的開(kāi)發(fā)口徑來(lái)拆不寫成泛泛的概念介紹。為了避免方案只停在文字上我把驗(yàn)證范圍先定死版本口徑HarmonyOS 7.0 / API 26兼容活動(dòng)要求里的 HarmonyOS 5.0.0 及以上技術(shù)分享范圍。驗(yàn)證入口先用一個(gè)獨(dú)立 controller 跑狀態(tài)流再接到 ArkUI 頁(yè)面。復(fù)現(xiàn)方式主路徑跑一次重復(fù)進(jìn)入跑一次能力不可用或中斷場(chǎng)景再跑一次?；貧w標(biāo)準(zhǔn)狀態(tài)順序不能亂失敗原因必須能在日志里看到頁(yè)面不能出現(xiàn)舊任務(wù)回寫新?tīng)顟B(tài)。如果這四點(diǎn)做不到就算文章里把特性名稱寫得再新也不能算真正解決開(kāi)發(fā)問(wèn)題。問(wèn)題是怎么發(fā)生的舊寫法容易把智能體入口當(dāng)普通路由只傳一個(gè)頁(yè)面名剩下的讓頁(yè)面自己猜。這個(gè)寫法短期看很快但只要遇到狀態(tài)變化就會(huì)暴露問(wèn)題。比如設(shè)備能力變化、窗口尺寸變化、任務(wù)中斷、用戶重復(fù)點(diǎn)擊、后臺(tái)恢復(fù)、審核材料檢查這些都不是主路徑能覆蓋的。我一般會(huì)把它拆成四個(gè)階段第一階段先判斷版本、設(shè)備和上下文不直接執(zhí)行重邏輯。第二階段把任務(wù)狀態(tài)寫清楚避免重復(fù)進(jìn)入。第三階段執(zhí)行過(guò)程中保留取消、降級(jí)和失敗原因。第四階段回到頁(yè)面以后用日志和可見(jiàn)狀態(tài)驗(yàn)收。案例一主路徑可復(fù)現(xiàn)用戶說(shuō)“打開(kāi)上次生成的方案”但本地沒(méi)有上次方案智能體要追問(wèn)或引導(dǎo)創(chuàng)建而不是打開(kāi)空頁(yè)。這類場(chǎng)景的關(guān)鍵不是多寫 if而是讓狀態(tài)機(jī)擋住錯(cuò)誤順序。下面這個(gè)小封裝保留了 stage、reason、traceId 和 updatedAt排查時(shí)能看到每一步發(fā)生了什么。type Stage idle | checking | running | fallback | done | failed; interface AgentIntentRouterState { stage: Stage; reason?: string; traceId: string; updatedAt: number; } class AgentIntentRouter { private current: AgentIntentRouterState { stage: idle, traceId: trace- Date.now(), updatedAt: Date.now() }; start(scene: string): AgentIntentRouterState { if (this.current.stage running) { return this.fail(已有任務(wù)正在執(zhí)行拒絕重復(fù)進(jìn)入); } this.current { stage: checking, traceId: scene - Date.now(), updatedAt: Date.now() }; return this.current; } run(): AgentIntentRouterState { if (this.current.stage ! checking) { return this.fail(狀態(tài)順序不對(duì)先檢查再執(zhí)行); } this.current.stage running; this.current.updatedAt Date.now(); return this.current; } fallback(reason: string): AgentIntentRouterState { this.current.stage fallback; this.current.reason reason; this.current.updatedAt Date.now(); return this.current; } done(): AgentIntentRouterState { this.current.stage done; this.current.updatedAt Date.now(); return this.current; } private fail(reason: string): AgentIntentRouterState { this.current.stage failed; this.current.reason reason; this.current.updatedAt Date.now(); return this.current; } }這段代碼不依賴頁(yè)面組件所以可以先用普通 ArkTS/TypeScript 思路驗(yàn)證狀態(tài)流再接到 ArkUI 頁(yè)面里。頁(yè)面只負(fù)責(zé)展示狀態(tài)不應(yīng)該直接決定任務(wù)能不能繼續(xù)。案例二失敗和降級(jí)路徑用戶從智能體進(jìn)來(lái)時(shí)已有應(yīng)用會(huì)話要合并當(dāng)前頁(yè)面上下文避免覆蓋正在編輯的狀態(tài)。失敗路徑一定要有明確的 reason。沒(méi)有 reason 的失敗提示開(kāi)發(fā)階段不好排查上線后用戶也不知道該重試、切換設(shè)備還是返回上一頁(yè)。const flow new AgentIntentRouter(); console.info(case-a-start, JSON.stringify(flow.start(case-a))); console.info(case-a-run, JSON.stringify(flow.run())); console.info(case-a-done, JSON.stringify(flow.done())); const conflict new AgentIntentRouter(); conflict.start(case-b); conflict.run(); console.info(case-b-repeat, JSON.stringify(conflict.start(case-b-repeat))); console.info(case-b-fallback, JSON.stringify(conflict.fallback(能力不可用進(jìn)入降級(jí)鏈路)));預(yù)期日志大概是這樣case-a-start stagechecking case-a-run stagerunning case-a-done stagedone case-b-repeat stagefailed reason已有任務(wù)正在執(zhí)行拒絕重復(fù)進(jìn)入 case-b-fallback stagefallback reason能力不可用進(jìn)入降級(jí)鏈路為什么我選狀態(tài)機(jī)而不是到處寫布爾值方案好處問(wèn)題多個(gè) boolean 字段寫起來(lái)快很容易出現(xiàn) isLoadingtrue 但 error 也存在的矛盾狀態(tài)只靠頁(yè)面生命周期頁(yè)面代碼少多窗口、后臺(tái)恢復(fù)和異步回調(diào)容易串線小狀態(tài)機(jī)封裝狀態(tài)順序清楚日志也好查一開(kāi)始要多寫一點(diǎn)結(jié)構(gòu)我更傾向第三種。HarmonyOS 7.0 / API 26 的新能力越來(lái)越多很多能力都不是一次性調(diào)用就結(jié)束而是有環(huán)境判斷、執(zhí)行過(guò)程、降級(jí)策略和驗(yàn)證結(jié)果。狀態(tài)機(jī)不是為了顯得復(fù)雜是為了讓排查變得可控。接到 ArkUI 頁(yè)面時(shí)注意什么頁(yè)面層建議只做三件事顯示當(dāng)前 stage讓用戶知道是在檢查、執(zhí)行、降級(jí)還是失敗。根據(jù) reason 給出下一步操作比如重試、切換設(shè)備、繼續(xù)普通模式。在 aboutToDisappear 或頁(yè)面切換時(shí)處理取消和回收避免舊任務(wù)回寫新頁(yè)面。一個(gè)比較穩(wěn)的寫法是把能力判斷和任務(wù)控制放在 controller 里頁(yè)面只訂閱結(jié)果。這樣后面換成折疊屏、平板、鴻蒙電腦窗口頁(yè)面結(jié)構(gòu)變了核心策略也不用跟著重寫。驗(yàn)收清單驗(yàn)收點(diǎn)通過(guò)標(biāo)準(zhǔn)重復(fù)點(diǎn)擊不會(huì)并發(fā)創(chuàng)建兩條互相覆蓋的任務(wù)能力不可用能進(jìn)入降級(jí)路徑并給出明確提示頁(yè)面退出舊任務(wù)不會(huì)繼續(xù)回寫已經(jīng)銷毀的頁(yè)面多設(shè)備窗口窗口變化后狀態(tài)不丟展示不亂日志回放能通過(guò) traceId 找到完整鏈路最后總結(jié)小藝智能體 這類 HarmonyOS 7.0 / API 26 能力文章和代碼都不能只寫主路徑。真正有價(jià)值的是把問(wèn)題怎么發(fā)生、怎么復(fù)現(xiàn)、怎么降級(jí)、怎么驗(yàn)證講清楚。我的判斷標(biāo)準(zhǔn)很簡(jiǎn)單如果這段方案以后換一個(gè)頁(yè)面還能復(fù)用日志里也能查到失敗原因那它才算工程上站得住。