适合谁看

• 想理解鸿蒙系统入口模型的人

• 已经熟悉 Deep Link，但还没接过 Intents Kit 的开发者

• 正在做搜索直达、系统理解型入口的人

问题背景

很多跨端开发者一开始会问：既然已经有路由和 Deep Link，为什么还要 Intents Kit？

这个问题本质上是在问：鸿蒙系统希望理解的是"链接"，还是"意图"。

Deep Link 的思路是：给一个 URL，应用收到后解析并跳转。系统只负责传递 URL，不理解 URL 的含义。

Intents Kit 的思路是：应用声明自己支持哪些意图，系统理解这些意图后，在合适的时机调起应用执行。

项目中的真实场景

食界探味当前的 Intents Kit 链路：

层	文件	职责
配置层	insight_intent.json	声明意图名称、参数、搜索关键词
执行器	InsightIntentExecutorImpl.ets	校验参数、调用插件
插件层	IntentNavigationPlugin.ets	桥接 Flutter
Flutter 层	intent_navigation_channel.dart	路由跳转

核心实现

一、Deep Link 更像地址

普通 Deep Link 的思路通常是：

用户点击链接: foodvoyage://dish/beef-001
  ↓
应用收到 URL
  ↓
应用自己解析: "beef-001" 是菜品 ID
  ↓
跳转到详情页

它重点在"地址能不能打开"。系统只负责传递 URL，不理解 URL 里的内容。

Deep Link 的特点：

特点	说明
格式	URL 字符串（scheme://host/path）
系统理解	不理解，只传递
参数传递	靠 URL 解析
搜索集成	不支持，系统搜索找不到
语义化	弱，URL 不表达意图
发现性	用户需要知道 URL

二、Intents Kit 更像结构化意图

Intents Kit 的重点则是：

用户搜索"搜索美食"
  ↓
鸿蒙系统找到 JumpFunctionPage 入口
  ↓
系统知道这个入口支持搜索功能
  ↓
系统调起应用，传入 pageId="search"
  ↓
应用执行跳转

Intents Kit 的配置（insight_intent.json）：

{
  "intentName": "JumpFunctionPage",
  "inputParams": [{
    "properties": {
      "pageId": {
        "type": "string",
        "enum": [
          {
            "value": "search",
            "displayName": "搜索美食",
            "keywords": ["搜索", "找菜", "查菜"],
            "displayDescription": "搜索全球美食与食材"
          }
        ]
      }
    }
  }]
}

这段配置告诉系统：

• 入口名叫 JumpFunctionPage

• 支持 5 种页面跳转

• 每种都有 displayName、keywords、displayDescription

系统会根据 keywords 和 displayName 在搜索结果中展示这些入口。用户搜索"搜索"时，系统会推荐"搜索美食"入口。

Intents Kit 的特点：

特点	说明
格式	结构化 JSON 配置
系统理解	理解意图名称和参数
参数传递	结构化参数（pageId, dishId）
搜索集成	✅ 支持，系统搜索可直达
语义化	强，displayName + keywords
发现性	高，系统主动推荐

三、两者最大的区别——系统理解层

Deep Link 通常是应用自己解释 URL。系统只负责"这个 URL 属于哪个应用"，不理解 URL 的含义。

Intents Kit 则是先把能力描述给系统，再由系统决定何时调起。

Deep Link:
  系统: "这个 URL 属于 foodvoyage 应用"
  应用: "我来解析 URL，决定跳哪里"

Intents Kit:
  系统: "foodvoyage 支持 JumpFunctionPage 意图，有 search、explore 等页面"
  系统: "用户搜索了'搜索'，匹配到 search 入口"
  系统: "调起 foodvoyage，传入 pageId=search"
  应用: "收到 pageId，跳转到搜索页"

关键差异：Intents Kit 让系统参与了"用户意图理解"的过程，而 Deep Link 只是"传递一个地址"。

四、代码层面的差异

Deep Link 的代码：

// Deep Link: 应用需要自己解析 URL
void handleDeepLink(Uri uri) {
  if (uri.host == 'dish') {
    final dishId = uri.pathSegments.first;
    context.push('/dish/$dishId');
  }
}

应用需要自己解析 URL 结构，容易出错。

Intents Kit 的代码：

// Intents Kit: 系统已经解析好参数，应用只需要路由
static void _navigate(_NavigationPayload payload) {
  final route = _pageIdToRoute[payload.pageId];
  if (route == null) return;
  _router?.go(route);
}

系统已经把参数结构化了，应用只需要根据 pageId 路由。

五、Intents Kit 的 3 层优势

优势	Deep Link	Intents Kit
搜索直达	❌ 系统搜索找不到	✅ 用户搜索关键词可直达
语义化入口	❌ URL 不表达意图	✅ displayName + keywords
参数校验	❌ 应用自己校验	✅ 系统 + 执行器双重校验

搜索直达是最关键的优势。在鸿蒙设备上，用户可以在系统搜索框输入"搜索美食"，系统会直接推荐你的应用入口。Deep Link 做不到这一点。

语义化入口让系统能理解你的应用"能做什么"。displayName: "搜索美食" + keywords: ["搜索", "找菜", "查菜"] 让系统知道这个入口和"搜索"相关。

参数校验在执行器层完成，非法参数在到达 Flutter 之前就被拦截了。

六、什么时候用 Deep Link，什么时候用 Intents Kit

场景	推荐方案	原因
应用内页面跳转	Deep Link	简单直接
从其他应用跳转	Deep Link	通用性好
系统搜索直达	Intents Kit	Deep Link 做不到
语义化入口	Intents Kit	系统能理解
被系统推荐	Intents Kit	系统搜索集成
需要参数校验	Intents Kit	执行器层校验

食界探味选择 Intents Kit 的原因：它需要被鸿蒙系统搜索理解和推荐。用户在鸿蒙搜索"搜索"时，应该能看到"搜索美食"入口并直达。

七、Intents Kit 的完整架构

┌─────────────────────────────────────────────────┐
│                  鸿蒙系统层                       │
│                                                   │
│  系统搜索 → 匹配 keywords/displayName             │
│  → 找到 JumpFunctionPage 入口                     │
│  → 调起应用，传入 pageId                           │
└──────────────────────┬──────────────────────────┘
                       │ intentName + params
                       ▼
┌─────────────────────────────────────────────────┐
│              执行器层（InsightIntentExecutorImpl） │
│                                                   │
│  校验 pageId 合法性                                │
│  校验额外参数（dishId）                             │
│  → 调用插件                                        │
└──────────────────────┬──────────────────────────┘
                       │ pageId + dishId
                       ▼
┌─────────────────────────────────────────────────┐
│              插件层（IntentNavigationPlugin）       │
│                                                   │
│  channel 可用 → 推给 Flutter                       │
│  channel 不可用 → 暂存 pending                     │
└──────────────────────┬──────────────────────────┘
                       │ pageId + dishId
                       ▼
┌─────────────────────────────────────────────────┐
│              Flutter 层（intent_navigation_channel）│
│                                                   │
│  pageId → Flutter 路由映射                         │
│  → 执行跳转                                        │
└─────────────────────────────────────────────────┘

关键代码位置

文件	作用
app/ohos/entry/src/main/resources/base/profile/insight_intent.json	意图配置
app/ohos/entry/src/main/ets/entryability/InsightIntentExecutorImpl.ets	参数校验
app/ohos/entry/src/main/ets/plugins/IntentNavigationPlugin.ets	桥接 Flutter
app/lib/core/platform/intent_navigation_channel.dart	路由跳转

Deep Link vs Intents Kit 对比表

维度	Deep Link	Intents Kit
本质	URL 跳转	结构化意图
系统理解	不理解，只传递	理解意图名称和参数
搜索集成	❌	✅ 系统搜索可直达
语义化	弱	强（displayName + keywords）
发现性	低（用户需知道 URL）	高（系统主动推荐）
参数校验	应用自己做	执行器层校验
适用场景	应用内/应用间跳转	系统搜索/语义入口
实现复杂度	低	中（需配置+执行器）
鸿蒙特色	通用方案	鸿蒙平台能力

常见坑

• 把 Intents Kit 当成 URL 跳转替代品 — 它的价值在系统理解，不在跳转

• 没有定义清楚 pageId 这类稳定参数 — 页面语义和路由路径不能混

• 原生侧不校验参数，直接把任意值传给 Flutter — 需要白名单校验

• Flutter 路由命名和系统意图命名混在一起 — pageId 是语义，路由是实现

• keywords 覆盖不全 — 用户搜索"查菜"时找不到入口

• 没有处理 pending navigation — Flutter 未 ready 时入口丢失

• Deep Link 和 Intents Kit 混用没协调 — 同一个入口不要两种方式都接

可复用模板

Intents Kit 配置模板

{
  "insightIntents": [{
    "intentName": "JumpToPage",
    "domain": "YourDomain",
    "intentVersion": "1.0.0",
    "srcEntry": "./ets/entryability/IntentExecutorImpl.ets",
    "uiAbility": {
      "ability": "EntryAbility",
      "executeMode": ["foreground"]
    },
    "inputParams": [{
      "properties": {
        "pageId": {
          "type": "string",
          "enum": [
            {
              "value": "home",
              "displayName": "首页",
              "keywords": ["首页", "主页", "推荐"],
              "displayDescription": "浏览推荐内容"
            }
          ]
        }
      }
    }]
  }]
}

选择决策模板

选择 Deep Link 还是 Intents Kit？

  需要被系统搜索发现？ → Intents Kit
  需要语义化入口？     → Intents Kit
  需要系统推荐？       → Intents Kit
  只是应用内跳转？     → Deep Link
  从其他应用跳转？     → Deep Link
  需要通用性？         → Deep Link

本篇总结

Intents Kit 和 Deep Link 的差别，核心在"系统是否理解你的入口"：

• Deep Link 偏地址——系统只传递 URL，应用自己解析

• Intents Kit 做结构化意图——系统理解意图名称和参数，在合适时机调起应用

做鸿蒙系统入口时，Intents Kit 更能体现平台能力：

1. 搜索直达 — 用户在系统搜索框输入关键词可直达

2. 语义化 — displayName + keywords 让系统理解入口含义

3. 参数校验 — 执行器层拦截非法参数

4. 发现性 — 系统主动推荐，用户不需要知道 URL

食界探味选择 Intents Kit，是因为它需要被鸿蒙系统搜索理解和推荐。这不是"另一种 Deep Link"，而是完全不同的入口模型。