【HarmonyOS学习笔记】2026-08-05 | 端插件卡片绑定与跨上下文判断

---

date: 2026-08-05
tags: [HarmonyOS, 端插件, InsightIntentEntry, 小艺开放平台, 卡片绑定, 长期记忆, LLM]
type: 实战笔记

一、小艺结果卡片绑定规则

卡片参数类型与绑定关系

小艺结果卡片绑定端插件返回值时，卡片参数类型决定了能绑定什么：

卡片参数类型	能否绑定端插件result	说明
string	❌	类型不匹配，result是object不是string
number	❌	同上
object	✅	需要声明子项，子项名与result字段名一致

正确绑定方式

1. 卡片参数 result 定义为 object 类型
2. 在 object 内声明子项，子项名与端插件返回值 result 中的字段名完全一致
3. 子项按名称自动匹配端插件 result 的字段

卡片参数定义：
  result (object)
    ├─ actionId (string)
    ├─ _source (string)
    └─ _timestamp (string)

端插件返回：
  { code: 0, result: { actionId: "act_11", _source: "MyEndPlugin", _timestamp: "..." } }

绑定结果：
  卡片result(object) ← 端插件result(object) ✅ 自动匹配
  卡片result.actionId ← 端插件result.actionId ✅ 子项自动对应

关键规则

• 每个端插件的返回值 result 字段必须在卡片参数 object 子项中完整声明，否则绑不到
• code 是顶级字段（与 result 同级），卡片参数可直接定义为 number 类型绑定
• 如果卡片 result 定义成 string 类型，永远绑不上端插件的 object 类型 result

---

二、端插件返回值设计

返回值结构

InsightIntentEntryExecutor<T> 的返回类型是 insightIntent.IntentResult<T>，结构固定：

{
  code: number,      // 0=成功，非0=失败
  result: T          // 泛型，由开发者自定义
}

返回值是端侧代码决定的，不需要在平台配置。 LLM 调用工具后会收到端侧的返回值，基于真实数据回复用户。

（返回值中的可观测标记 _source/_timestamp 用于确认端侧真实执行，细节我在上一篇端插件笔记中写过，这里不重复展开。）

输入参数 vs 返回值，两个方向

方向1：平台 → 端侧（输入参数）
  平台工具配置的parameters → LLM填充值 → 框架注入端侧public属性

方向2：端侧 → LLM（返回值）
  onExecute()返回IntentResult → 系统传给LLM → LLM基于返回值回复用户

平台工具配置只管输入参数（方向1），返回值（方向2）是端侧代码自己决定的。

---

三、上下文内 vs 上下文外的判断

问题场景

LLM 智能体在调用端插件时，需要判断数据是"新建"还是"更新已有"。但 LLM 的判断能力受限于对话上下文：

场景1：上下文内（同一轮对话）
─────────────────────────────
用户："我有C1驾照"
LLM上下文中有之前存的条件列表 → 判断"有C1驾照"不存在 → 调用工具(action=upsert)

场景2：上下文外（新一轮对话/重启后）
─────────────────────────────────
用户："我有C1驾照"
LLM上下文中没有历史数据 → 不知道已存在 → 可能重复创建

解决方案：搜索先行

1. 提供 Search 类工具，让 LLM 在不确定时先查本地数据再决定操作
2. 提示词引导：不确定数据是否已存在时，先搜索再操作
3. upsert 语义：存储操作本身做成幂等的（按 title 去重更新），即使 LLM 不搜索也不会产生重复

长期记忆辅助（未来方向）

小艺 LLM 模式的长期记忆能力可以存储总结性信息，辅助跨上下文判断：

• 长期记忆存储"用户已有 X 条条件"这类摘要信息
• 新对话开始时 LLM 先查看长期记忆，了解用户大致情况
• 再调用 Search 工具精确查询，避免重复操作
• 结构化数据仍走端插件存本地，长期记忆只做总结性参考，不做主存储

判断策略总结

场景	判断依据	操作
上下文内，LLM记得已有	LLM上下文记忆	直接判断新建/更新
上下文外，不确定	先调Search查本地	根据搜索结果决定
长期记忆有摘要	参考长期记忆	再调Search精确确认
upsert操作	不确定时直接upsert	幂等操作，按title去重

---

学习小结：这次补充了端插件开发中两个之前没写透的点。一是小艺结果卡片绑定有硬规则——卡片参数必须是 object 且子项名与返回值 result 字段完全一致才能自动匹配，string 类型永远绑不上 object 的 result，code 作为顶级字段可直接绑定 number。二是返回值设计上"平台只管输入、端侧决定输出"，IntentResult 的 result 由泛型自定义。最核心的收获是跨上下文的"新建 vs 更新"判断：上下文外 LLM 没有历史数据容易重复创建，解决要靠搜索先行（Search 工具 + 提示词引导 + upsert 幂等语义），长期记忆存摘要做跨上下文的辅助参考，但结构化数据的主存储仍在端插件本地。

懿路向前 · AI辅助整理
2026-08-05