HarmonyOS Agent×Skill 实战(第4篇):参数澄清与预算校验【共创稿事节】

图 01:AI 生成的技术主题封面。
一、先看故障现象
在出行应用里,最贵的错误并不一定是接口报错,而是结果看起来顺理成章。用户只说“下周末去苏州,两个人,花销别太高”,Agent 却生成了精确到分钟的日程,并给出未经查询的门票价格。文本完整、语气笃定,反而让这类错误更难被发现。本文处理的是模型填参、规则校验和澄清策略。
二、问题为什么会出现
自然语言输入经常把多种信息揉在一起:时间可能相对,人数可能隐含,预算可能只是“便宜些”这样的偏好。模型擅长把句子拆成结构,却不具备天然的事实权威。对外的 Skill 契约必须把“确定字段”和“未知字段”分开,不能因为模型能输出 JSON,就认为每个字段已经被证实。行旅助手内部采用 city、date、travelers、budgetItems 四类槽位,缺少城市或有效日期就返回 NEED_CITY_AND_DATE。
日期处理尤其需要谨慎。2026-02-30 在某些 JavaScript 日期处理路径里会被滚动到三月,导致不合法输入静悄悄变成另一天。这里用正则先限定 YYYY-MM-DD,再用 UTC 构造日期并反向对照年月日,发现溢出则拒绝。对于“周六”“明天”“月底”,需要明确基准日期、目标时区和用户意图。本系列没有接入实时设备时区接口,因此不偷偷按服务器时区解析;示例策略是先提问或要求用户确认完整日期。
预算规则同样不要被表面上的小数骗过。常见写法把 0.1 和 0.2 直接相加后转字符串,可能出现精度尾差。费用项目应按最小货币单位汇总,再统一格式化,禁止负数、非有限数字和明显超出业务范围的值。我们只计算用户明确给出的交通、住宿、餐饮等条目,不用所谓“模型常识”填入实时报价。报价涉及日期、城市、平台与库存,离开可靠来源就只能标为待估。
参数校验要双层设置:SKILL.md 的 JSON Schema 定义系统智能体可填写的字段类型、必填项和范围;业务入口再根据真正的业务约束二次校验。前者减少不合理调用,后者挡住边界和恶意输入。不能假设所有平台版本都严格执行 schema,也不能拿 TypeScript 类型声明充当运行时校验。字符串长度、人数上限、金额上下限、日期合法性都要在实际执行处判断。
还有一种很容易踩的坑是“为了减少追问,把所有缺失值都默认”。人数为一在很多场景还能容忍,但日期、付款人、目的地和具体执行时间不同。默认值一旦影响第三方系统写入,就可能造成真实副作用。合理做法是给字段标明风险等级:只影响展示的选填项可以用明确默认;影响执行目标与时间的字段必须澄清;涉及费用或授权的字段必须由用户确认。别让模型拿格式正确掩盖事实不确定。
建议保留每次澄清的 provenance,也就是字段来自用户原话、可信接口还是规则默认。出发日期若由用户手动确认,后续可以沿用;如果只是从对话中的模糊时段推断,页面要显示“待确认”。这样在第五篇生成多步计划时,调度器才知道哪一个节点可以运行、哪一个必须停下等待,而不是所有 JSON 字段都一视同仁。
三、实现取舍和系统边界
本篇的实现把人工确认看成结构化数据状态,而非一句提示词。normalizeInput 只接受可以校验的日期,返回有错误码的对象;budget 用整数分累计并给出固定两位小数。错误码和澄清文案分开维护,方便后续针对不同语言或页面优化展示,而不改变规则本身。对于用户只是想讨论旅行方案的场景,没必要强迫对方补齐每个字段,可以停留在建议阶段,等实际保存草稿时再获取必需信息。
尤其不要把“模型生成”和“操作完成”混为一谈。清单可以即时显示,预算可以显示合计,日程只能先显示草稿。列表里应该标记数据来源,例如“用户输入的金额”“应用规则生成的物品”;无法提供来源的精确报价不应该出现。开发者没有外部票价接口时,诚实地说“尚未获取价格”就是正确的功能行为。
四、关键代码与实现路径
以下代码对应下载包中的 项目源码,业务层代码可使用 Node.js 18+ 运行;涉及 scriptManager 的片段需要集成到 Stage 模型并按目标 SDK 验证。所给例子并不包含任何实际订票、真实支付或自动写入系统日历的实现。
import { normalizeInput, budget } from './agent-core.mjs';
const trip = normalizeInput({
city:'苏州', date:'2026-12-10', travelers:2
});
if (!trip.ok) {
console.log('需要澄清:', trip.code);
}
const expenses = budget([
{ amount: 0.10 }, { amount: 0.20 }
]);
console.log(expenses.amount); // '0.30'
// 非法日期:normalizeInput({city:'苏州',date:'2026-02-30'})
这段实现重点在于将“模型或系统提出的意图”与“程序真正允许执行的业务动作”分开:参数先经校验,再交给业务函数,最后用明确状态或错误码回报。不能直接用一句“执行成功”作为真实设备操作的证据。

图 02:AI 生成的 DevEco Studio 风格开发界面,代码窗口、调试状态与项目名称用于讲解本文排查位置。
五、四类高频踩坑与修复证据
坑 1:2026-02-30 被保存成三月的某一天
表现:2026-02-30 被保存成三月的某一天。
原因:直接 new Date 可能发生无提示的日期滚动,字符串格式正确不等于日期存在。
处理:以严格格式校验和年月日回读比较拒绝溢出,并明确时区处理责任。
复验:测试闰年、月底、跨年和不同系统时区,非法输入必须保留在待澄清状态。
坑 2:预算相加后出现 0.30000000000000004
表现:预算相加后出现 0.30000000000000004。
原因:浮点数直接作为金额存储并多次累计,展示格式不应弥补底层错误。
处理:以分为单位存入整数,先检查有限性和业务边界,再合计。
复验:用 0.1+0.2、零元、负值和极大值保证结果及错误码稳定。
坑 3:用户说“便宜点”却显示精确机票价
表现:用户说“便宜点”却显示精确机票价。
原因:把模型推测当成实时商业信息,输出缺少来源和时间戳。
处理:把预算计算限定为用户已提供项目,外部价格标为待估并要求可靠数据接入。
复验:关闭网络接口后仍不应凭空出现酒店或机票的具体成交价格。
坑 4:“下周末”自动变成错误的出发日期
表现:“下周末”自动变成错误的出发日期。
原因:缺少用户所在时区、基准日期以及周末的具体日定义。
处理:将含糊日期保留成原始表达,待用户确认 YYYY-MM-DD 再执行日期相关动作。
复验:在跨时区和周日夜间情境下检查,系统不会静默改变用户选择。
六、深入复盘:工程上还要补什么
把自然语言变成确定事实之前必须过三道关
第一道关是识别用户是否在表达执行意愿。“下周末去苏州怎么样”可能只是咨询方案,而“给我准备一份下周末的行李清单”才是相对明确的任务。第二道关是判断槽位是否足够明确。没有完整日期可以先给通用建议,但不能把一个含糊时间写入系统日程。第三道关是校验格式与业务规则,即使模型输出了符合 JSON 格式的字符串,也不代表日期真的存在、人数在支持范围内、金额符合单位要求。
不少问题来自过度依赖解析库的宽容模式。某些语言会把非法日期滚动到下个月;某些数字转换会把空字符串当作零;某些金额字符串包含逗号、货币符号或空格,直接转换可能悄悄失败。应用不要为了“尽量成功”而接受所有输入。与其让非法数据混入计划,不如在明确字段上立刻返回有解释的失败分支,向用户请求可以核对的值。
槽位来源为何必须进入结果结构
如果预算中“交通 380 元”来自用户明确输入,系统可以据此计算;如果“交通 380 元”来自历史攻略文本,那么这只是候选估算而非当前可用报价。把两者都放在 amount 字段里,会让后续汇总错误地认为来源相同。建议为关键数据增加 source、confirmedAt 与 scope,说明它是直接输入、资料提取、规则默认还是外部接口返回。失效的外部数据不能无限期继承,尤其是日期相关的价格与时刻。
页面也应该把“建议”“草稿”“已确认”分开。用户可以先收到一份粗略旅行准备单,再逐步补全准确日期和费用。这样不会因追问过多破坏体验,也不会用虚假的精确信息制造安心感。对 Agent 而言,能够承认“目前缺少一项必要信息”是一种专业行为,而不是能力不足。
编写真正有用的参数测试集
参数测试不能只覆盖正常日期,至少还要覆盖月底、闰年、跨年、空格、全角字符、人数零、人数过大和金额小数精度。每个测试都应该有明确的输入与预期错误码。对时间相关场景,先把“字符串日期是否合法”和“相对时间应该落在哪一天”拆成两个问题:前者可在 Node.js 中稳定验证,后者必须引入可靠基准时间、时区和业务语境。没有这个前提,测试中的“明天”本身就是不确定变量。
更进一步,用户修改其中一个槽位时,依赖它的结果必须失效。例如把苏州改成杭州,行李清单可能变化不大,但当地天气、交通与提醒时间都需要重新确认。不能只更新标题,让旧目的地的详细结果继续留在页面。后面一篇的状态机正是为解决这类依赖失效而准备。
七、运行、验证与边界检查
验证使用四组边界集:第一组是非法日期与闰年,第二组是不同人数和空城市,第三组是小数、负数和巨大预算,第四组是“明天”“周末”等未指明基准的自然语言。成功条件不是“生成了一份看似合理的行程”,而是所有不能确认的字段都停在澄清或待确认状态。为避免时区差异,Node.js 用 UTC 校验日期合法性,这不代表已经解析用户当地的真实旅行时间。
当测试发现预算合计不对,应先查输入来源和最小单位,再查界面格式化;日期出错先查是否存在 Date 自动溢出或时区转化;人数异常先查 schema 是否限制最大值。下一篇会把这些槽位拼成有依赖的任务计划,并解释为什么“让模型一次性输出十个工具调用”非常危险。

图 03:AI 生成的 HarmonyOS 风格手机操作界面,所有页面数据用于功能说明。
与用户沟通时,最好把“尚无精确数据”作为明确的结果类型,而不是让页面空白。预算卡片可显示已输入项目的合计与未填写的类别,日期卡片可显示“需要确认准确出发日”。这些状态应能恢复和编辑,避免每次澄清都让用户从头输入。让模型恰当地提出一个问题,往往比编出五个不确定字段更能提高真实任务完成率。
八、本篇小结与下一篇预告
本篇将具体问题限定在可观察的调用链、可复现的业务规则与明确的拒绝分支中,给出了代码与手动验证顺序。尚未在目标设备上验证的系统行为应继续按当前 SDK 与官方文档核实。下一篇将多个有依赖的 Skill 拼成可恢复计划,避免跳步、循环和重复执行。
官方核对资料
更多推荐


所有评论(0)