在这里插入图片描述

摘要:微信鸿蒙版 8.0.23 与 HDC 2026 的 HMAF 接连刷屏,而我的资讯 App 却在小艺里"查无此人"。本文完整复盘一次真实改造:把 68 个页面、200+ 功能点的资讯 App 拆成 23 个原子服务,全程 零业务代码改动,一周后被小艺对话、小艺搜索、小艺建议主动推荐。内容覆盖 Intents Kit 五类分发能力与两条运行逻辑、意图定义与 AGC 注册、完成时/将来时共享、本地搜索索引、意图调用与 IntentAdapter 适配层设计,以及 6 个"静默失败"级别的坑。核心观点:适配层不是多余的中间层,是业务代码的免疫系统。

目录

11 月 13 日,微信鸿蒙版 App 推送 8.0.23.37 正式版;HDC 2026 上,鸿蒙智能体框架 HMAF 正式发布。两条新闻挨着刷屏,我在工位上盯着自己那个上线三个月的资讯 App 后台,脸有点烫——DAU 曲线像一条躺平的心电图,几乎是一条直线。

先说个反直觉的数字:我这 App 足足有 68 个页面、200 多个功能点,功能比同赛道友商多得多。可我在小艺里搜"今天有什么 AI 科技新闻",返回的卡片里根本没有我。反过来看,那些功能比我少一大半的应用,却能被小艺对话、小艺搜索、小艺建议三个入口轮番推。

我当时百思不得其解,直到把 Intents Kit(意图框架)的文档翻了三遍才反应过来:App 做得再好,小艺搜不到,等于系统级隐形。 在 HarmonyOS 7 这一代,意图粒度已经下沉到服务级——你的 App 能不能被找到,不取决于你做了多少功能,而取决于你暴露了多少个"能被意图识别的原子服务"。

于是我干了一件当时看起来很疯的事:把资讯 App 拆成 23 个原子服务,全程 零业务代码改动,一周后小艺开始主动推我的内容。这篇文章就把这条链路从头到尾扒一遍,重点聊一个几乎没人认真写、但特别值钱的角度——意图适配层怎么在不碰业务代码的前提下接进去。

金句先放这:你以为你在做 App,其实你在做一组可被检索的服务。

一、实测环境(先把底裤亮出来)

老规矩,工程师的文章不亮环境就是耍流氓。下面是我这次真实跑通的环境,全部按"能复现"来写。

项目我的实测配置说明 / 坑点
主力设备HUAWEI Mate 70 ProHarmonyOS 7 开发者预览版,真机
备用设备MatePad Pro 13.2 英寸验证 Tablet 形态
系统版本HarmonyOS NEXT / 5.0.0 以上官方硬性要求 5.0+
开发工具DevEco Studio 5.0.3.300配套 SDK API 12+
账号类型AGC 企业开发者账号个人开发者申请不了,这是硬门槛
合规区域中国境内出境直接不可用,接口会静默失败
支持形态Phone / Tablet / PC·2in1官方明确不支持模拟器
业务载体自研资讯阅读 App(单机 + 云端)200+ 功能点,拆出 23 个原子服务

这里必须吐槽两句:第一,Intents Kit 目前只对企业开发者开放注册,个人开发者连申请的按钮都看不到,我一开始用个人账号折腾了半天,最后借了公司的企业账号才跑起来;第二,模拟器不支持,必须真机。我那几天包里常年揣着两台设备,同事以为我在搞什么地下交易。

环境这块记住一句话:企业账号 + 真机 + 中国境内,三样缺一样,后面全白搭。

二、背景与痛点:为什么"打开 App"这条路正在被删掉

我做资讯 App 三年,经历过两次流量逻辑的迁移,每一次都像被人拔了网线。

第一次是从"应用市场下载"迁移到"桌面图标 + 推送"。那会儿大家拼的是图标好不好看、推送标不标题党。第二次就是现在——用户越来越少"主动打开 App"了。你想想自己最近一周:是不是更多地直接对小艺说"帮我查一下明天北京天气",而不是先解锁、再翻抽屉、再点开一个天气 App?入口正在从"图标"变成"一句话"。

我碰到的具体问题(Z 问题)特别典型:资讯 App 上线后,内容质量不差,但用户看完一篇就走,DAU 卡在几千上不去。我一开始以为是推荐算法不行,猛调了两周排序模型,结果曲线纹丝不动。后来拉日志才发现,根本不是算法问题,是压根没人进来。用户不打开 App,我算法算得再准也递不到他面前。

更扎心的是,我发现"小艺搜索"里搜"AI 科技新闻",返回的是几张别的 App 的卡片,点进去直接是对应的内容页——那种体验对用户来说叫"一步到位",对我这种没适配的应用来说叫"查无此人"。

这里有个关键认知差:传统的 App Linking / Deep Link 解决的是"用户已经打开 App 之后,怎么跳到指定页";而意图框架解决的是"用户还没打开 App 时,系统怎么发现你、怎么把你递到用户面前"。 这是两个完全不同的战场。前者是"进屋之后带路",后者是"让系统愿意敲你的门"。

我试过的错误方案有三个,逐个说:

  1. 堆推送:以为多推几条就能拉活。结果打开率不到 3%,还被用户投诉骚扰,推送权限差点被关。
  2. 做小组件:桌面上放个资讯卡片。有点用,但只能触达已经把组件加到桌面的老用户,拉新为零。
  3. 接第三方语音技能:绕一圈,体验割裂,还得维护另一套业务逻辑,越搞越乱。

直到我把 Intents Kit 的文档读完,才意识到正解一直摆在那儿——不是让用户来找你,是让系统替你找到用户。

反常识来了:拉活的正确姿势,不是把用户拽进 App,是把你的服务送出去。

三、意图框架全景与选型:先把地图铺开

3.1 智慧分发的五类能力

Intents Kit 是 HarmonyOS 级的意图标准体系,它把应用/元服务的业务功能,智能分发到系统级入口(小艺对话、小艺搜索、小艺建议)。官方把智慧分发分成五类特性,我按"我的资讯 App 能怎么用"重新翻译了一遍:

特性类别触发逻辑我的资讯 App 场景用户感知
习惯推荐基于用户长期使用习惯每天早 8 点推"科技晨报"小艺建议里固定出现
事件推荐基于特定事件触发某发布会开幕,推"实时图解"小艺建议弹卡片
位置推荐基于地理位置到园区推"本地科技活动"到某地自动出现
技能调用-语音语音直接触发“小艺,读今天的 AI 新闻”小艺对话直接播报
本地搜索系统全局检索小艺搜索里能搜到我的文章搜关键词出卡片

这五类不是选一个,而是可以全都要。我最后五个里接了四个(位置推荐因为资讯场景弱,暂时没上)。真正让我打开思路的是:原来"资讯内容"这种东西,天然就是可检索、可推荐的原子单元,比工具类 App 还好接。

3.2 意图运行逻辑:两条方向相反的路

理解 Intents Kit,最关键是搞清楚两条方向相反的运行逻辑,这也是我画的第一张图:

系统侧(HarmonyOS)

应用侧(我的资讯 App)

完成时 / 将来时

submitInsightIntent

用户点击/语音

InsightIntentExecutor

本地搜索索引

业务服务层
新闻详情/列表/搜索

意图适配层
参数翻译 + 结果封装

insight_intent.json
意图定义

Intents Kit
意图框架

意图注册中心

小艺对话 / 小艺搜索 / 小艺建议

图解读(这段要认真看):这张图的核心是那条贯穿左右的分水岭——应用侧和系统侧中间夹着一个橙色的"意图适配层"(A2),它就是本文的主角。上半部分箭头从应用流向系统,叫意图共享(应用→系统),分"完成时"(用户已经读完,上报既成事实)和"将来时"(用户想读,先预约意图);下半部分箭头从系统流回应用,叫意图调用(系统→应用),系统通过 InsightIntentExecutor 把用户意图递回来,适配层翻译成业务参数,业务服务层执行。注意蓝色虚线——本地搜索索引直接由注册中心供给小艺搜索,不需要每次回到 App。 Orange 的适配层一旦做好,业务代码一行都不用动,这是整个架构最值钱的地方。

3.3 两种运行逻辑的本质

再展开讲讲这两条路,因为它直接决定了后面代码怎么写:

  • 意图共享(应用 → 系统):App 主动把"我这儿有个什么服务、用户做了什么"告诉系统。分为完成时(如"用户读完了这篇 AI 新闻",系统据此做习惯推荐)和将来时(如"用户想看发布会直播",提前登记,到点系统提醒)。共享的目的,是让系统在合适的时候把你的服务推给用户。
  • 意图调用(系统 → 应用):系统识别出用户意图后,回调你的 App 执行。比如用户说"读今天的 AI 新闻",系统匹配到你的 ReadTechNews 意图,回调你的 Executor,你的 App 打开对应页面播报。

一句话概括:共享是"我告诉系统我是谁",调用是"系统叫我出来干活"。

3.4 选型对比:Skill vs Intents Kit

接入前我纠结过一个选型问题:到底用 Skill(技能)还是 Intents Kit?很多同学会混。我列了个对比表:

维度Skill(技能)Intents Kit(意图框架)
定位面向语音技能的独立能力封装HarmonyOS 级统一意图标准体系
分发入口主要小艺对话小艺对话 + 小艺搜索 + 小艺建议全覆盖
粒度偏任务级/技能级HarmonyOS 7 下沉到服务级/原子级
推荐能力弱,靠技能触发强,习惯/事件/位置/语音/搜索五类分发
与系统搜索融合浅深,本地搜索索引直接进入系统检索
配置方式技能配置insight_intent.json + AGC 注册
适合场景单一语音交互内容/服务需要被系统发现、检索、推荐
我的选择弃用全量接入 Intents Kit

选型结论很直接:资讯内容这种"要被搜到、被推荐"的场景,Intents Kit 是唯一正解。Skill 更像"我有一条语音线",Intents Kit 是"我接入了整个鸿蒙的意图分发网络"。HDC 2026 发布 HMAF 智能体框架后,这个方向只会更明确——意图就是智能体之间、系统与应用的通用语言。

金句:Skill 是给 App 开一扇语音窗,Intents Kit 是把 App 接进整栋楼的神经网络。

四、接入实战:四个模块,从意图定义到被小艺推荐

下面是硬菜。我按真实接入顺序拆成四个模块,每个模块都有完整代码骨架。再次强调:以下接口为可复用骨架,具体签名以华为官方文档为准,我这边主要讲工程思路和踩坑。

4.1 模块一:意图定义与 AGC 配置

一切从"定义意图"开始。你要先告诉系统:我有哪几个原子服务,每个服务吃什么参数、吐什么结果。这一步落在 insight_intent.json 里,放在工程的 entry/src/main/resources/base/profile/ 目录下。

我把资讯 App 拆出了 23 个原子服务,这里贴最核心的三个作为骨架:

{
  "insightIntent": [
    {
      "intentName": "ReadTechNews",
      "intentId": "com.example.news.read_tech_news",
      "description": "按主题阅读科技资讯,支持语音播报与卡片展示",
      "parameterSchema": {
        "schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "required": ["topic"],
        "properties": {
          "topic": {
            "type": "string",
            "description": "资讯主题,如 AI / 鸿蒙 / 芯片"
          },
          "publishTime": {
            "type": "string",
            "description": "发布时间,将来时共享用于预约"
          }
        }
      },
      "supportAppLinking": true,
      "executeMode": ["foreground", "background"]
    },
    {
      "intentName": "SearchNewsByKeyword",
      "intentId": "com.example.news.search_by_keyword",
      "description": "根据关键词检索全站资讯,供小艺本地搜索直接调用",
      "parameterSchema": {
        "type": "object",
        "required": ["keyword"],
        "properties": {
          "keyword": { "type": "string", "description": "搜索关键词" }
        }
      },
      "supportAppLinking": true,
      "executeMode": ["foreground"]
    },
    {
      "intentName": "MorningBrief",
      "intentId": "com.example.news.morning_brief",
      "description": "科技晨报,习惯推荐场景,每天定时生成摘要",
      "parameterSchema": {
        "type": "object",
        "required": [],
        "properties": {
          "date": { "type": "string", "description": "晨报日期" }
        }
      },
      "supportAppLinking": false,
      "executeMode": ["background"]
    }
  ]
}

解读:三个意图分别对应三种分发方式——ReadTechNews 对应技能调用-语音,SearchNewsByKeyword 对应本地搜索,MorningBrief 对应习惯推荐。intentId 必须用反向域名保证全局唯一;parameterSchema 是标准的 JSON Schema,必填字段(required)写错,系统直接不注册,而且不报错,这是最阴的坑(后面踩坑实录细说)。executeMode 决定前台还是后台执行,晨报这种不需要界面的用 background。

配置完工程文件,还要去 AGC(AppGallery Connect) 后台做一步"意图注册":进入应用 → 智慧分发 / 意图框架 → 添加意图 → 上传或校验 insight_intent.json。这一步必须用企业账号,个人账号看不到入口。注册成功后,系统会给你分配一个校验状态,只有状态为"已生效"的意图才会进入分发池。

踩坑提示:AGC 后台的意图定义必须和工程里的 insight_intent.json 完全一致,改了工程文件记得同步后台,否则本地能跑、线上搜不到。

4.2 模块二:意图共享——完成时与将来时

意图定义好,接下来告诉系统"用户干了啥"。这就是意图共享,分完成时和将来时两种,代码写在不同时机。

先看完成时的时序,这是我画的第二张图:

小艺建议 系统注册中心 Intents Kit 意图适配层 资讯 App 用户 小艺建议 系统注册中心 Intents Kit 意图适配层 资讯 App 用户 读完一篇 AI 新闻 触发"完成时共享"事件 参数翻译(新闻ID→topic标签) submitInsightIntent(完成时) 写入用户行为画像 累积习惯(连续3天读AI) 生成"科技晨报"推荐 小艺建议卡片曝光

图解读(认真看这张):这张时序图讲的是意图共享"完成时"的完整闭环。起点是用户在 App 里读完一篇 AI 新闻(一个普通得不能再普通的行为),经过适配层翻译成系统能懂的 topic 标签后,通过 submitInsightIntent 上报给 Intents Kit,写入系统侧的用户画像。关键在于中间那步 SYS-->>SYS:系统不是收到一次就推一次,而是累积习惯(比如连续三天读 AI 类),达到阈值才由小艺建议生成推荐卡片。这解释了为什么共享不是"立刻见效"——它是喂给系统一个长期画像,回报有延迟。也提醒我们:共享时机要在"用户真实完成行为之后",别在页面刚打开就上报,那是造假数据,系统画像会失真。

下面是完成时共享的代码骨架:

// @kit.IntentsKit:意图框架核心能力
import { insightIntent } from '@kit.IntentsKit';
import { BusinessError } from '@kit.BasicServicesKit';

/**
 * 完成时共享:用户已读完新闻,把"既成事实"上报系统
 * 用于习惯推荐(小艺建议)
 * 注意:具体 API 签名以华为官方文档为准
 */
export async function shareReadCompleted(
  newsId: string,
  topic: string,
  readDuration: number
): Promise<void> {
  // 1. 组装意图共享请求;完成时用 timestamp 标记既成事实
  const shareRequest: insightIntent.InsightIntentShare = {
    intentId: 'com.example.news.read_tech_news',
    intentName: 'ReadTechNews',
    parameters: {
      newsId: newsId,
      topic: topic,                 // 适配层已把原始标签归一化为系统可识别枚举
      readDuration: readDuration,   // 阅读时长用于判断"真实读完"而非误触
    },
    // 完成时:标记行为已经发生
    timestamp: Date.now(),
  };

  try {
    // 2. 提交给 Intents Kit,系统写入用户画像
    await insightIntent.submitInsightIntent(shareRequest);
    console.info('[Intent] 完成时共享成功, newsId=' + newsId);
  } catch (err) {
    const e = err as BusinessError;
    // 3. 共享失败不能影响主流程:用户读书是主业,上报是副业
    console.error(`[Intent] 完成时共享失败 code=${e.code}, msg=${e.message}`);
  }
}

再看将来时共享。它和完成时相反——用户"想做但还没做",先登记,到点系统提醒。比如用户点了"发布会开始时提醒我",这就是将来时:

import { insightIntent } from '@kit.IntentsKit';
import { BusinessError } from '@kit.BasicServicesKit';

/**
 * 将来时共享:用户预约了未来行为,提前登记意图
 * 到点由系统(事件推荐)触发提醒
 * 注意:具体 API 签名以华为官方文档为准
 */
export async function shareFutureIntent(
  eventName: string,
  triggerTime: number
): Promise<void> {
  // 与完成时最大的区别:带一个未来的触发时间 triggerTime
  const futureRequest: insightIntent.InsightIntentShare = {
    intentId: 'com.example.news.read_tech_news',
    intentName: 'ReadTechNews',
    parameters: {
      topic: eventName,
      // 将来时关键字段:系统据此在 triggerTime 到点时触发事件推荐
      scheduledTime: triggerTime,
    },
  };

  try {
    await insightIntent.submitInsightIntent(futureRequest);
    console.info('[Intent] 将来时共享已登记: ' + eventName);
  } catch (err) {
    const e = err as BusinessError;
    console.error(`[Intent] 将来时共享失败 code=${e.code}`);
  }
}

对比总结:完成时用 timestamp(已发生),将来时用 scheduledTime(将发生)。这两个字段用反了,系统画像直接乱套——这是我踩过的最隐蔽的坑之一。还有个工程原则藏在代码注释里:共享失败必须 catch 掉,绝不能让它阻断用户主流程。上报是锦上添花,用户读书才是主业。

4.3 模块三:本地搜索索引

第三块是本地搜索。目标是:用户在小艺搜索里敲"AI 新闻",能直接搜到我的文章卡片。这靠的是把可检索内容喂给系统的本地搜索索引。

import { insightIntent } from '@kit.IntentsKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 业务侧的资讯数据结构(这是原有业务模型,不改)
interface NewsEntity {
  id: string;
  title: string;
  summary: string;
  topic: string;
  publishTime: number;
}

/**
 * 构建本地搜索索引:把业务数据批量喂给系统搜索
 * 关键点:在"内容发布/更新"时增量同步,而不是全量重建
 * 注意:具体 API 签名以华为官方文档为准
 */
export async function buildSearchIndex(newsList: NewsEntity[]): Promise<void> {
  // 1. 把业务实体映射为系统搜索项;这一步在适配层完成,业务层无感
  const searchItems = newsList.map((news) => ({
    // 唯一 ID:用业务 ID 保证幂等,重复同步不会生成重复索引
    key: news.id,
    // 可检索文本:标题 + 摘要拼在一起,提升命中率
    keywords: `${news.title} ${news.summary}`,
    // 点击后交给哪个意图处理
    intentId: 'com.example.news.search_by_keyword',
    // 附加参数:系统回调时原样带回
    parameters: {
      keyword: news.topic,
      newsId: news.id,
    },
  }));

  try {
    // 2. 批量提交索引;官方依据场景提供全量/增量接口
    await insightIntent.setSearchableItems(searchItems);
    console.info(`[Intent] 搜索索引同步成功, count=${searchItems.length}`);
  } catch (err) {
    const e = err as BusinessError;
    console.error(`[Intent] 搜索索引同步失败 code=${e.code}`);
  }
}

解读:这段代码最值钱的设计是用业务 ID 做 key 保证幂等。资讯 App 内容会不断更新,如果每次全量重建索引,既浪费又容易出重复卡片;用 ID 做 key,重复同步就是覆盖,天然幂等。另外 keywords 把标题和摘要拼在一起,命中率明显提升——这是个土办法但特别有效。整段代码依然没有碰业务模型 NewsEntity,映射全在适配层,这就是"不改业务代码"的兑现。

4.4 模块四:意图调用 + 业务服务层复用适配层设计

最后一块是意图调用:系统把用户意图递回来,App 执行。这里我要重点讲适配层设计——这是本文的核心观点,也是被严重低估的工程角度。

先看状态机,我把一个原子服务从注册到被调用的完整状态画出来:

写 insight_intent.json

AGC 后台注册成功

系统校验通过

完成时/将来时上报

本地搜索索引同步

习惯/事件/位置触发

用户关键词命中

用户点击卡片

用户点击结果

适配层翻译参数

产生新行为闭环

执行完成归还

已定义

已注册

已生效

已共享

已索引

被推荐

被搜索

被调用

业务执行

图解读(这张是全文最该琢磨的):这个状态机揭示了一个大多数人忽略的事实——原子服务不是"注册完就完事",它有一条完整的生命周期。从已定义到已注册到已生效是冷启动阶段;已共享和已索引是两条并行的"喂系统"路径(分别对应推荐和搜索);被推荐/被搜索到被调用是系统把流量还给你的时刻;最关键的是 业务执行 --> 已共享 这条回边——每次被调用都会产生新的用户行为,新的行为又喂回系统画像,形成正反馈闭环。这就是为什么越早接入、暴露越多原子服务的 App,会像滚雪球一样越推越多。看不懂这条回边,就理解不了为什么这是"长期主义"的生意。

下面是意图调用的核心代码——InsightIntentExecutor:

import { InsightIntentExecutor, insightIntent } from '@kit.IntentsKit';
import { IntentAdapter } from '../adapter/IntentAdapter';
import { NewsService } from '../service/NewsService';

/**
 * 意图执行器:系统 → 应用的回调入口
 * 这里只做"翻译 + 转发",不写任何业务逻辑
 * 注意:具体 API 签名以华为官方文档为准
 */
export default class NewsIntentExecutor extends InsightIntentExecutor {

  /**
   * 前台模式执行:需要打开页面(如阅读新闻)
   */
  async executeInUIAbilityForegroundMode(
    intentName: string,
    params: Record<string, Object>,
    pageLoader: object
  ): Promise<insightIntent.ExecuteResult> {
    // 1. 适配层:把系统参数翻译成业务 Query(核心解耦点)
    const query = IntentAdapter.toNewsQuery(intentName, params);

    // 2. 复用已有业务服务:一行业务代码都不用改
    const result = await NewsService.getInstance().query(query);

    // 3. 适配层:把业务结果封装成系统期望的返回结构
    return IntentAdapter.toExecuteResult(result);
  }

  /**
   * 后台模式执行:不需要界面(如晨报生成)
   */
  async executeInUIAbilityBackgroundMode(
    intentName: string,
    params: Record<string, Object>
  ): Promise<insightIntent.ExecuteResult> {
    const query = IntentAdapter.toNewsQuery(intentName, params);
    const result = await NewsService.getInstance().query(query);
    return IntentAdapter.toExecuteResult(result);
  }
}

重点看那个 IntentAdapter——它是整个"不改业务代码"承诺的兑现者。它做两件事:把系统参数翻译成业务 Query,把业务结果封装成系统返回结构。业务服务 NewsService 从头到尾不知道 Intents Kit 的存在。

import { insightIntent } from '@kit.IntentsKit';

// 业务侧查询对象(原有,不动)
interface NewsQuery {
  topic?: string;
  keyword?: string;
  newsId?: string;
}

/**
 * 意图适配层:系统语义 ⇄ 业务语义 的唯一翻译官
 * 价值:所有意图框架的"脏活"都关在这里,业务层保持纯净
 */
export class IntentAdapter {

  /** 系统参数 → 业务 Query */
  static toNewsQuery(intentName: string, params: Record<string, Object>): NewsQuery {
    const query: NewsQuery = {};
    switch (intentName) {
      case 'ReadTechNews':
        query.topic = params['topic'] as string;
        query.newsId = params['newsId'] as string;
        break;
      case 'SearchNewsByKeyword':
        // 系统关键词直接映射为业务搜索词
        query.keyword = params['keyword'] as string;
        break;
      case 'MorningBrief':
        query.topic = '晨报';
        break;
      default:
        console.warn('[Adapter] 未知意图: ' + intentName);
    }
    return query;
  }

  /** 业务结果 → 系统返回结构 */
  static toExecuteResult(result: unknown): insightIntent.ExecuteResult {
    return {
      // 只有适配层知道系统要什么字段;业务层只管吐自己的数据
      resultCode: 0,
      resultData: JSON.stringify(result),
    } as insightIntent.ExecuteResult;
  }
}

这个设计的价值:如果哪天 HarmonyOS 改了意图参数结构,或者我要接第二种分发框架,我只需要改 IntentAdapter 一个类,NewsService 和 23 个原子服务对应的业务代码一个字都不用动。适配层就是那道防火墙,把"系统侧的快速演进"和"业务侧的稳定"隔开。 这是我这次改造最大的收获,也是我劝所有团队一定要单独抽出来的东西。

金句:适配层不是多余的中间层,是业务代码的免疫系统。

五、踩坑实录:我踩过的 6 个坑,一个比一个阴

理论讲完,该上血泪史了。下面六个坑,每一个都让我至少浪费半天,写出来你们就别再踩了。

坑 1:个人开发者根本申请不了

现象:我用个人开发者账号登录 AGC,意图框架那一栏压根找不到注册入口,还以为是我权限没刷新。
原因:官方明确——仅企业开发者可申请注册意图。个人账号没有这个能力。
解法:老老实实用企业账号。如果暂时没有,先用企业的测试账号跑通,别在个人账号上死磕。我当初在这上面浪费了一整个晚上,最后借了公司账号十分钟搞定。

坑 2:模拟器不支持,必须真机

现象:我在 DevEco 模拟器上跑,意图共享接口调用永远返回成功但小艺毫无反应,日志干干净净。
原因:官方明确不支持模拟器,所有意图能力必须真机验证。
解法:准备一台 HarmonyOS 5.0+ 的真机。我的做法是主测 Mate 70 Pro,备机 MatePad 验证多形态。

// 避坑:在代码里加环境判断,模拟器直接给出明确提示,别让自己傻等
import { deviceInfo } from '@kit.BasicServicesKit';

function assertRealDevice(): boolean {
  // 模拟器通常有特定标识;具体判定以官方文档为准
  const isEmulator = deviceInfo.productType === 'emulator';
  if (isEmulator) {
    console.error('[Intent] 当前为模拟器,意图能力不可用,请切换真机');
    return false;
  }
  return true;
}

坑 3:意图 Schema 字段写错,不报错但也不注册

现象:intentName 里我手滑写了个下划线变中划线,AGC 后台显示"已注册",但小艺永远搜不到,required 字段少写一个也没任何报错。
原因:意图 Schema 校验是静默失败——字段不合法时系统直接跳过注册,不抛异常。
解法:工程文件和 AGC 后台逐字符比对;用 JSON Schema 校验工具先本地校验;intentId 用反向域名全小写。我现在的习惯是写个脚本每次构建后校验一遍:

// 构建期自检:把容易错的字段拉出来人工核对
const REQUIRED_FIELDS = ['intentName', 'intentId', 'description', 'parameterSchema'];
function validateIntentDef(def: Record<string, unknown>): boolean {
  return REQUIRED_FIELDS.every((field) => {
    const ok = Object.prototype.hasOwnProperty.call(def, field);
    if (!ok) console.error(`[Intent] 缺少必填字段: ${field}`);
    return ok;
  });
}

坑 4:共享时机搞反——完成时写成将来时

现象:用户读完新闻后我调了共享,但小艺建议里死活不推;反过来我预约提醒时用完成时,到点也不提醒。
原因:完成时用 timestamp,将来时用 scheduledTime,我用反了,系统把"已发生"当成"待发生",画像彻底错乱。
解法:把两种共享封装成两个独立函数(就像我上面代码那样),从 API 层面杜绝混用,别用一个通用函数加开关参数——开关参数迟早会被写反。

坑 5:重复建设业务逻辑,越接越乱

现象:为了接意图,我在 Executor 里直接写了查询新闻的代码,和原有 NewsService 逻辑几乎一模一样。两个月后业务改了分页规则,我改了业务代码忘了改意图代码,结果小艺返回的数据和用户App里看到的不一致,被测试提了 bug。
原因:把意图调用当成了"新功能",另起炉灶写业务,而不是"给现有服务加一个入口"。
解法:这就是前面反复强调的 IntentAdapter——Executor 里只做翻译和转发,业务一律复用 NewsService。我重构后,意图相关的业务代码从 400 多行降到 60 行适配代码。记住:意图框架是入口,不是新业务。

坑 6:只在中国境内可用,出境静默失败

现象:有次出差到境外调试,所有意图接口都返回成功但系统毫无反应,我一度以为账号被封了。
原因:官方约束——仅中国境内可用,出境后接口静默失败。
解法:调试前先确认网络位置;代码里对"长期无反馈"加日志告警,避免误判。这个坑 hardest 的地方是它"看起来一切正常"。

六个坑浓缩成一句:意图框架的坑,大多不报错——静默失败才是最贵的坑。

六、反思与反常识:任务级注册,才是下一波红利

写到这里,我想退一步聊点不那么"操作"的东西。

接完这一整条链路,我最大的反思是:我一开始把意图框架理解错了。 我原本以为它是"给 App 加一个新功能",做完才发现,它其实是"给 App 加一组新入口"。这两者的区别,就像"给店铺装修"和"把店铺开到商场主通道"——前者是内部优化,后者是流量重构。

HDC 2026 上 HMAF 智能体框架发布后,这个趋势只会加速。HarmonyOS 7 把意图粒度下沉到服务级,意味着系统不再是把"一个 App"整体分发给你,而是把"一个个原子服务"分发给你。用户说"读今天的 AI 新闻",系统匹配的是 ReadTechNews 这个服务,而不是"某某资讯 App"这个整体。

这里就是那条反常识:App 拆得越碎、暴露的原子服务越多,反而越容易被找到。 传统软件工程讲"高内聚",恨不得把所有功能拢成一个整体;但在意图时代,"可被识别的原子服务数量"直接决定了你的曝光面。我那 23 个原子服务,就是 23 个独立被检索、被推荐的入口。这不是架构的降级,是架构的重新定价。

再往前想一步,我判断**“任务级注册"是下一波红利**。现在大家还在卷"服务级”(我能提供什么),再往后一定会卷到"任务级"(我能替用户完成什么)。服务级是"我有一篇 AI 新闻",任务级是"我能帮你把今天所有 AI 新闻读完并生成摘要"。当 HMAF 让智能体之间能互相调用,谁把自己注册成"可被编排的任务节点",谁就站在了下一波分发的中心。

这也是我坚持"长期主义"的原因。意图框架的回报不是即时的——你今天共享的行为,可能三天后才变成一次推荐;你今天拆的原子服务,可能半年后才被某个新场景调用。但一旦正反馈闭环转起来(就是那张状态机图里的回边),它就是复利。 那些追风口、哪个热做哪个的 App,永远吃不到这波复利,因为他们没有沉淀可被系统识别的资产。

反思一句话:短期看,适配意图是成本;长期看,它是资产——区别只在于你愿不愿意先付费。

七、小结:把服务送出去,而不是把用户拽进来

一路写下来,从热点钩子到六个坑,这条链路我算是扒干净了。最后把最关键的几点收一收:

  1. 认知:App 做得再好,小艺搜不到等于系统级隐形。入口正在从"图标"变成"一句话"。
  2. 地图:Intents Kit 五类分发能力(习惯/事件/位置/语音/本地搜索),两条运行逻辑(意图共享、意图调用)。
  3. 实战:意图定义 → 完成时/将来时共享 → 本地搜索索引 → 意图调用,四步走通。
  4. 核心工程角度:单独抽 IntentAdapter,把系统语义和业务语义隔开,业务代码零改动。
  5. 坑:企业账号、真机、Schema 静默失败、共享时机、重复造轮子、境内限制——六个坑一个比一个阴。
  6. 趋势:粒度下沉到服务级,拆得越碎越容易被找到;任务级注册是下一波红利。

三句金句,送给看到这里的你:

你以为你在做 App,其实你在做一组可被检索的服务。

拉活的正确姿势,不是把用户拽进 App,是把你的服务送出去。

适配层不是多余的中间层,是业务代码的免疫系统。

最后留个评论区钩子:你的 App 现在能被小艺搜到吗?你打算先从哪一类分发能力接起——习惯推荐、事件推荐,还是本地搜索?评论区扣个「1」+ 你的场景,我把这次整理的一份意图接入自检清单(含 AGC 注册核对表 + Schema 字段校验脚本)发出来,限前 50 位。 下期我准备写《从服务级到任务级:我把晨报意图改造成 HMAF 可编排任务节点的全过程》,想看的同学评论区留个「任务级」。


本文为原创首发技术实战,基于 HarmonyOS Intents Kit 意图框架,代码为可复用骨架,实际接口以华为官方文档为准。【鸿蒙心迹】系列。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐