我第一次真机调试，智能体在网页里答得挺好，推到手机上却怎么都唤不起来。折腾半天才发现原因特别蠢：我没把自己的设备账号加进真机调试名单。

更蠢的是我当时的排查方向——我一直以为是触发意图写得不对，改了两轮描述，越改越糟。这一篇讲调试到底怎么走，以及我后来固定下来的自测顺序。

一、调试入口在哪

编排页面右侧就是「调试与预览」面板。输入测试话术模拟用户对话，能看到会话日志、节点执行链路和变量输出——报错、超时、答非所问，基本都能在这三样里定位到。

我的习惯是分两轮：先用典型话术跑一遍，确认主链路通；再用边界话术跑一遍，确认它没有越界回答。这两轮做完才谈真机。只跑典型话术就上真机，等于把"该不该响应"这个问题留到端上去暴露，排查成本高得多。

二、网页调试和真机预览，是两件事

很多人以为网页里通了就完事，我当初就是这么栽的。

网页调试解决的是"逻辑对不对"：意图匹配、Prompt 效果、插件调用、变量传递。它不需要设备，快，改完立刻能试。但它验证不了端侧兼容性——网页里没有真实的设备权限、没有真实的卡片渲染、没有真实的唤起链路。

真机预览解决的是"端上能不能用"：卡片展示、交互流畅度、指令响应、端侧权限、连续对话会不会断。这一步必做，因为端侧的表现和网页里根本不是一回事。

真机预览的顺序是三步：先在平台配置「真机调试名单」，录入自己的鸿蒙设备账号（就是我漏掉的那步）；然后在手机的小艺里搜索你的智能体名称，把它唤起；最后逐项测交互——卡片渲染对不对、指令响应及不及时、连续对话会不会断、权限弹窗有没有正常出现。

三、日志、沙箱与权限

调试时最有价值的三样东西：

会话日志看完整对话过程，节点执行链路看每一步走了哪个节点、耗时多少，变量输出看中间结果对不对。超时问题在链路里一眼可见——哪个节点卡住、卡多久，都有数。

还有个容易误判的点：Skill 执行受沙箱约束，端侧能力需要授权。权限没申请到位的时候，调用往往是静默失败——不报错，但也没结果。我排查过一次"明明配了却不生效"，翻遍日志没看到异常，最后发现是权限没声明，调用在授权那一层就被拦了，根本没走到业务逻辑。

所以遇到"配置看着都对但就是不生效"，我的排查顺序是：版本 → 权限 → 触发意图 → 业务逻辑。这个顺序是我用几次白干换来的。

四、老设备会浪费你半天

再提醒一次版本：真机调试和端插件开发要求设备是 HarmonyOS 5.1.0 Release 及以上，小艺 App 版本也要够新（第 2 篇清单里的 ROM ≥ 6.0.0、小艺 App ≥ 11.3.8.300）。

我那次是 ROM 太低，端插件怎么调都不通，日志里也看不出所以然——因为问题不在代码层，在运行时层。换了台机器立刻就正常了。

这类坑的共同特点是：它不报错，只是不工作。所以调试不通的时候，先花两分钟确认版本清单，再怀疑代码，能省下大半天。

五、我的自测清单

提审之前我会过这五项：

1. 网页对话：典型话术 + 边界话术都跑通，边界话术确认它会拒绝而不是硬答；
2. 真机：能唤起、卡片正常、响应及时、连续对话不断、权限弹窗正常；
3. 超时：慢接口有没有兜底，别让用户对着空白干等；
4. 权限：端侧能力都声明并授权了，没有静默失败；
5. 误触发：换个不相关的说法，确认它不会被错误唤起。

第五项最容易被跳过，但它恰恰决定上线后的口碑——用户不会告诉你"你这个智能体老是乱插话"，他们只会不再用它。

这五项过完，我才敢点提交。下一篇讲的就是提交前那道更麻烦的关——合规自查和素材准备，我的第一个智能体正是在那一步被打回的。