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