HarmonyOS 7 小艺智能体参数校验：不可信意图输入，怎样避免宽松转换执行错误动作

HarmonyOS 7 小艺智能体参数校验：不可信意图输入，怎样避免宽松转换执行错误动作

意图输入来自外部入口时，不能直接把 count 转成 Number 再执行。空字符串会变成 0，小数会被下游截断，未知动作可能走到默认分支。更稳的边界是白名单动作加严格字段校验，在进入业务执行之前输出一份规范化的独立参数。

版本与适用范围

HarmonyOS 7 官方介绍 Agent 能力与智能入口。系统帮助应用获得入口不等于应用可以信任任意外部参数。下面演示应用侧解析，不代替系统认证、调用者授权或开发平台的意图 Schema。

官方参考文档，核对日期：2026-09-14。下面的 JavaScript 实验可以直接用 Node.js 运行；它验证应用侧算法与状态边界，不是已经在 HarmonyOS SDK 或真机上跑通的完整应用。应用接入时，SDK 调用、事件订阅和资源释放应分别验证。

问题是怎样发生的

空字符串和小数都应被拒绝，不能先 Number 转换再判断范围。要求调用方明确提供整数，能让错误更早暴露。

复现不依赖随机等待。测试用固定输入、显式完成的异步结果或明确的状态变化，让错误条件可以重复出现。先保留失败信号，再检查修复后的状态，避免只看“没有抛异常”就认为问题解决。

案例一：宽松数值转换

空字符串和小数都应被拒绝，不能先 Number 转换再判断范围。要求调用方明确提供整数，能让错误更早暴露。

案例二：未知动作和多余字段

delete 不在白名单，admin 字段也不允许。规范化结果只复制三个字段，后续修改原对象不会改变待执行参数。

实现代码

export function parseIntent(raw) { if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw Error('invalid_payload'); const allowed = new Set(['action','resourceId','count']); if (Object.keys(raw).some(k => !allowed.has(k))) throw Error('unknown_field'); if (raw.action !== 'preview' && raw.action !== 'export') throw Error('unknown_action'); if (typeof raw.resourceId !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(raw.resourceId)) throw Error('invalid_resource'); if (typeof raw.count !== 'number' || !Number.isSafeInteger(raw.count) || raw.count < 1 || raw.count > 20) throw Error('invalid_count'); return Object.freeze({action:raw.action,resourceId:raw.resourceId,count:raw.count}); }

运行验证

把上面的实现和下面的测试按顺序放进同一个 example.mjs 文件，使用 Node.js 执行 node example.mjs。测试采用 Node 内置的 assert，不需要第三方依赖。断言失败时进程报错，全部通过时正常退出。

import assert from 'node:assert/strict'; assert.equal(Number(''), 0); assert.throws(() => parseIntent({action:'export',resourceId:'A',count:''}), /invalid_count/); assert.throws(() => parseIntent({action:'export',resourceId:'A',count:1.5}), /invalid_count/); assert.throws(() => parseIntent({action:'delete',resourceId:'A',count:1}), /unknown_action/); assert.throws(() => parseIntent({action:'preview',resourceId:'../A',count:1})); assert.throws(() => parseIntent({action:'preview',resourceId:'A',count:1,admin:true})); const raw = {action:'export',resourceId:'A',count:2}; const parsed = parseIntent(raw); raw.count = 20; assert.equal(parsed.count, 2);

核对时不要把输入样本当作性能数据。上述测试已经在 Node.js 环境逐项执行通过，验证的是代码中写出的条件。涉及窗口、材质、音频或系统入口的真实表现，需要另外在适配设备验证。

为什么选择这个方案

拒绝未知字段便于发现入口协议变化，代价是新版本字段需要协商。允许未知字段并忽略也可以，但要在安全相关动作里谨慎选择。严格类型、范围与资源格式检查应相互独立，日志才能明确指出失败字段。

错误转换会吞掉哪些输入问题

宽松转换经常把协议错误变成合法的业务数字。下面的错误函数让空字符串变成 0、小数被截断、数字字符串被当作数值使用。严格解析保留协议类型要求，分别拒绝这些输入，再允许真正的整数。调用方若需要兼容字符串协议，应在单独的、明确受控的适配层转换，不能让业务边界悄悄替外部输入猜类型。

继续在同一个 example.mjs 文件中追加以下代码，使用已经定义的实现和 assert 再运行一次。

export function badCountConversion(value) {return Math.floor(Number(value));} assert.equal(badCountConversion(''), 0); assert.equal(badCountConversion(1.9), 1); assert.equal(badCountConversion('2'), 2); await assert.rejects(async () => parseIntent({action:'export',resourceId:'A',count:'2'})); assert.throws(() => parseIntent({action:'export',resourceId:'A',count:Infinity})); assert.throws(() => parseIntent({action:'export',resourceId:'A',count:21})); assert.throws(() => parseIntent({action:'export',resourceId:'A',count:0})); assert.deepEqual(parseIntent({action:'preview',resourceId:'sample_1',count:1}), {action:'preview',resourceId:'sample_1',count:1});

接入应用时的取舍

解析失败时给入口返回明确的字段错误，但不要把整个原始输入原样写日志。执行前还要查询资源是否属于当前会话，且高风险动作必须进入独立确认流程。协议升级时给 Schema 版本明确的兼容规则，不能在默认分支偷偷接受未知动作。对于大输入先限制长度与层级，再做字段校验，避免解析阶段本身产生资源开销。示例资源 ID 是白名单标识，不应直接拼接成本地文件路径。

封装与复用

把上面的纯逻辑保留为独立模块，界面层只提交输入和消费结果。系统事件适配层负责取得当前窗口、设备或入口的实际数据，不要把测试常量直接搬到正式应用。这样单元测试仍可在没有设备时运行，SDK 接入问题也能和算法问题分开排查。

复用之前先检查实例的作用域：窗口、播放器或请求协调器是否属于同一个会话。复用函数不等于共享所有状态。对于异步回调，需要同时考虑结果失效与底层任务取消；对于同步计算，需要确认单位、取样范围和输入上限。

边界与后续检查

resourceId 格式正确不代表资源属于当前账号，执行前仍必须做资源权限校验。正则拒绝路径分隔符只服务于这个 ID 协议，不能被当作完整的文件系统安全方案。

回归测试应保留两个案例，再增加空输入、重复入口和生命周期结束后的操作。日志记录输入身份、状态修订与失败原因，不记录敏感内容。升级 SDK 后先检查官方接口签名、支持设备与版本说明，再运行同一组实验和设备回归，避免把旧版本假设带入新环境。