微信小微AI-【实战三】接力落地|用户点完 AI 卡片跨进小程序,那几秒才是体验的生死线

【实战三】接力落地|用户点完 AI 卡片跨进小程序,那几秒才是体验的生死线

系列《小微(微信小程序 AI)实战》第 5 篇

⚠️ 版本声明:本文基于小微内测版本(截至 2026-11-18 的官方文档与团队实测),微信官方尚未推出正式版本,文中接口协议、字段语义均可能随版本迭代调整,正式版发布后请以官方文档为准。

脱敏说明 :代码来自真实生产项目并做完整脱敏------域名替换为 h5.example.com,页面路径泛化为通用命名;文件组织、事件协议、分支设计、踩坑结论均为原样。


写在前面

前两篇实战都在讲「AI 侧」:skill 怎么注册、接口怎么写、卡片怎么出。这一篇讲接收侧------用户点了卡片,接力(handoff)落到你的小程序之后:

  1. 接力页怎么接住 AI 送来的用户(jumpUrl 承载 H5 / 原生页直达)
  2. 原子组件环境里怎么跳转(openDetailPage 与手势同步铁律)
  3. App 级 handoff 事件怎么消费(onAgentHandoff + pageId 投递)
  4. 从 AI 进来的登录怎么做收尾(最容易忽略、用户体验塌方的地方)
  5. 那些官方文档不会明说、但我们撞过的墙(返回不了对话、半屏页禁路由......)

先给全景图:一次接力从 AI 侧到小程序侧的完整链路。

scss 复制代码
AI 侧(第 4 篇)                        小程序侧(本篇)
─────────────────                       ─────────────────
接口返回 handoff.query
      ↓
组件 setRelatedPage(裸 query)  ──────→  ① 卡片标题栏「进小程序」入口 → 接力页
      ↓
用户点卡片主体                      ──→  ② handoff 落地 → 接力页(WebView 承载 / 原生页)
      ↓
(App 级事件)                      ──→  ③ Taro.onAgentHandoff({pageId, path, query, payload})
                                            └→ 按 pageId 投递给目标页消费(取后即删)

一、接力页设计:WebView 承载模式

我们的业务页面大多是 H5,所以接力的主流形态是:handoff 指向小程序的一个 WebView 承载页,由它打开 H5。

1.1 为什么不直接跳 H5

小程序里没有「直接打开 H5」的能力,必须经由 WebView 组件承载页。所以接力地址的形态是:

ini 复制代码
pages/WebView/index?jumpUrl=<URL 编码后的 H5 完整地址>

第 4 篇的 buildJumpUrlQuery 生成的就是这段 query。WebView 承载页 onLoad 时取出 jumpUrl 解码,塞给 <WebView src> 渲染。

1.2 两个必处理的细节

① H5 地址必须整体 URL 编码 。H5 地址自带 #/、?、&,不编码会被小程序路由当成自己的 query 解析截断。我们在第 4 篇的工具函数里统一做:

js 复制代码
return '?jumpUrl=' + encodeURIComponent(finalUrl)

② host 要按环境替换。枚举里存的 H5 地址可能是任意环境的(测试地址写死在枚举里很常见),接力前必须替换为当前环境 host,否则「测试包接力到生产 H5」「生产包接力到测试 H5」这类事故迟早发生:

js 复制代码
/* MiniAI/utils/navigation/navigation.js(脱敏) */
const { domainName } = require('../../config')

/* 剥协议头,取当前环境 host */
const currentHost = domainName.replace(/^https?:\/\//, '').split('/')[0]

/* 匹配任意环境的 H5 host(dev- / test- / pre- 前缀等),全量替换为当前环境 */
const H5_HOST_PATTERN = /([a-zA-Z0-9]+-)?h5\.example\.com/g

function replaceH5Host(h5Url) {
  return h5Url.replace(H5_HOST_PATTERN, currentHost)
}

function encodeH5Url(h5Url) {
  /* 先 host 替换,再整体编码,规避 #、? 等特殊字符截断 */
  return encodeURIComponent(replaceH5Host(h5Url))
}

所有 handoff 地址都从这两个函数出,杜绝散拼------散拼的下场就是某天某条链路忘了编码或忘了换 host,而且一定是线上才暴露。


二、原子组件内的跳转:openDetailPage 与手势同步铁律

原子组件(卡片)内部如果需要主动接力(不只是被动等用户点卡),唯一通道是视图上下文的 openDetailPage:

js 复制代码
/* MiniAI/utils/navigation/navigation.js(脱敏,接上文) */

/**
 * 跳转至小程序原生页
 * 必须在 tap 手势同步回调链路内调用,禁止放入 async / setTimeout
 */
function navigateToPage(viewContext, url) {
  if (viewContext && typeof viewContext.openDetailPage === 'function') {
    viewContext.openDetailPage({ url })
  }
}

/**
 * 跳转至 WebView 页并打开指定 H5 地址
 */
function navigateToWebView(viewContext, h5Url) {
  const webViewUrl = 'pages/WebView/index?jumpUrl=' + encodeH5Url(h5Url)
  if (viewContext && typeof viewContext.openDetailPage === 'function') {
    viewContext.openDetailPage({ url: webViewUrl })
  }
}

两条铁律(都是实测撞墙的结论):

  1. openDetailPage 必须在 tap 手势的同步调用链里 。塞进 async/setTimeout/Promise .then 里 = 静默失败。要做「先请求再跳转」?不行------要么先跳再补数据,要么把决策前置到接口层(这正是第 4 篇接口返回 handoff、组件只做 setRelatedPage 的设计原因之一)
  2. viewContext 只存在于原子组件环境 。wx.modelContext.getViewContext(this) 在普通页面里拿不到,所有跳转工具都做了存在性兜底,防止复用到普通页面时报错

三、App 级事件:onAgentHandoff 的 pageId 投递模式

接力落地时,平台会向小程序派发一个 App 级事件 onAgentHandoff,回调参数:

字段 含义
pageId 目标接力页标识(精确投递的钥匙)
path / query 接力目标路径与参数
payload 接口返回 handoff 里带的业务数据

难点在于:事件在 App 层触发,但数据要在具体页面里消费 ,而且时序不保证(事件可能先于页面 onLoad 到达)。我们的解法是「App 层登记、页面层认领、认领即销毁」:

ts 复制代码
// src/hooks/useAgentHandoff.ts(脱敏)
import Taro from '@tarojs/taro'
import useSessionStorage from 'src/hooks/useSessionStorage'

const useAgentHandoff = () => {
  const CACHE_KEY = 'agentHandoffsCacheKey'
  const sessionStore = useSessionStorage()

  /**
   * 注册小微 AI Handoff 监听(App 启动时调用一次)
   * 用户点击卡片进入接力页时触发,每次进入 1 次
   */
  const registerAgentHandoff = () => {
    // @ts-ignore - onAgentHandoff 为小微 AI 基础库能力,Taro 类型未覆盖
    if (!Taro.onAgentHandoff) {
      console.warn('[App] 当前基础库不支持 onAgentHandoff')
      return
    }
    // @ts-ignore
    Taro.onAgentHandoff(({ pageId, path, query, payload }) => {
      // 按 pageId 精确投递给目标接力页(时序兜底:先登记,页面 onLoad 后认领)
      const map = sessionStore.getItem(CACHE_KEY) || {}
      map[pageId] = { path, query, payload }
      sessionStore.setItem(CACHE_KEY, map)
    })
  }

  /**
   * 接力页取走 handoff(取后删除,避免重复消费)
   */
  const takeAgentHandoff = (pageId: string) => {
    const map = sessionStore.getItem(CACHE_KEY) || {}
    const handoff = map[pageId]
    if (handoff) {
      delete map[pageId]
      sessionStore.setItem(CACHE_KEY, map)
    }
    return handoff || null
  }

  return { registerAgentHandoff, takeAgentHandoff }
}

挂载与消费两侧:

ts 复制代码
// src/app.tsx(节选)
const { registerAgentHandoff } = useAgentHandoff()
useLaunch(() => {
  registerAgentHandoff()   // App 启动注册一次
})
ts 复制代码
// 任意接力页(节选)
useDidShow(() => {
  const handoff = takeAgentHandoff(pageId)
  if (handoff) {
    // 消费 payload:回填搜索词、定位 tab、预填表单......
  }
})

三个设计要点:

  1. sessionStorage 中转解决时序:不管事件先到还是页面先到,「登记 → 认领」都能对上
  2. 取后即删 :take 语义保证同一 handoff 只消费一次,避免页面反复进出导致重复初始化
  3. 基础库兜底 :onAgentHandoff 不存在时 warn 降级,老版本客户端不至于崩

注意 @ts-ignore:这是 AI 基础库新增 API,Taro 类型定义还没覆盖,直接调用会报类型错误------别忘了加。


四、登录衔接:最容易被忽略的塌方点

场景:用户在小微里说「查看我的订单」→ AI 出卡 → 点卡进小程序 → 发现没登录 → 走登录流程 → 登录成功------然后呢?

如果走小程序默认的「登录后跳首页」,用户会迷路:我是从小微对话里来的,怎么到了首页?怎么回去?

4.1 全链路设计

我们踩完坑后的完整方案分三步:

第一步:AI 侧的登录地址带来源标记。 MiniAI 生成的登录页地址统一走 buildLoginUrl,默认拼 loginSource=miniai:

js 复制代码
// MiniAI/utils/navigation/buildLoginUrl.js(脱敏)
/* 登录页路径:不带前导 /,可直接交给 navigateToPage 接力 */
const LOGIN_PAGE_PATH = 'pages/Login/ChooseLogin/index'

/* 小微来源标识:须与小程序侧的枚举保持一致 */
const MINI_AI_LOGIN_SOURCE = 'miniai'

function buildLoginQuery(options = {}) {
  const { sessionIdOverdue = false, url = '', loginSource = MINI_AI_LOGIN_SOURCE } = options
  const parts = []
  parts.push('isPush=true')
  parts.push('loginSource=' + loginSource)   // 来源标记恒定拼入
  parts.push('sessionIdOverdue=' + sessionIdOverdue)
  if (url) {
    parts.push('redirectUrl=' + encodeURIComponent(url))   // 登录后回跳目标
  }
  /* filter(Boolean) 剔除空片段,杜绝双 & 脏参数 */
  return parts.filter(Boolean).join('&')
}

function buildLoginUrl(options = {}) {
  return LOGIN_PAGE_PATH + '?' + buildLoginQuery(options)
}

第二步:登录成功后,收尾守卫按来源分流。 所有登录/注册成功页的跳转逻辑最前面,先过 aiLoginSuccess 守卫:

ts 复制代码
// src/utils/jumpMiddle.ts(脱敏节选)
/**
 * 小微 AI 来源登录成功收尾
 * 从 AI 进入时无法程序化返回 AI 对话,统一跳转登录成功提示页
 * @returns true=已按小微来源处理,调用方应直接 return
 */
aiLoginSuccess(urlParams: any) {
  const miniAiSource = loginSourceEnum.miniai
  if (!urlParams || urlParams.loginSource !== miniAiSource) {
    return false   // 非小微来源,走默认跳转
  }
  try { Taro.hideLoading() } catch (e) { /* 忽略无 loading */ }

  // redirectTo 替换当前登录页:返回键不会回到「已登录的登录页」,
  // 返回即回到微信 AI 对话
  Taro.redirectTo({
    url: '/pages/Login/AiLoginSuccess/index',
    // 路由异常时回退 Toast,避免停留在登录页且无任何反馈
    fail: () => {
      Taro.showToast({ icon: 'none', title: '登录成功,请返回小微继续', duration: 3000 })
    }
  })
  return true
}

第三步:专门的「登录成功」提示页。 页面无任何按钮,只做一件事------告诉用户回去:

jsx 复制代码
// src/pages/Login/AiLoginSuccess/index.jsx(脱敏)
/**
 * 小微 AI 登录成功提示页
 * 登录成功后 redirectTo 到本页,提示用户返回小微对话框继续;
 * 返回即回到微信 AI 对话(无操作按钮)
 */
const AiLoginSuccess = () => {
  return (
    <View className='aiLoginSuccessContainer'>
      <View className='successMainTitle'>
        <View className='successIcon' />
        <View className='successText'>登录成功</View>
      </View>
      <View className='successSubTitle'>请返回小微对话框继续即可</View>
    </View>
  )
}

4.2 为什么是这个形态:三条硬约束

这套「绕」的设计不是审美偏好,是三条硬约束逼出来的:

  1. 无法程序化返回 AI 对话 。小程序侧没有任何 API 能「关掉自己回到小微对话框」------wx.exitMiniProgram 需要用户点击触发,且退出后不保证回到对话上下文。唯一可靠的「返回」方式是用户按左上角返回键。所以收尾页必须让返回键落在正确的地方
  2. redirectTo 而非 navigateTo:替换掉登录页,返回键不会先回到「已经登录完的登录页」(一个死胡同页面)再按一次才回到对话
  3. Toast 只是兜底 :redirectTo 在 AI 容器内有失败风险(进入路径问题),fail 回退 Toast 保证用户至少有反馈;失败时用户多按一次返回,仍能回对话

4.3 守卫的接入位置

守卫必须放在每个 登录/注册成功出口的 routeJumpLogic 最前面(其他默认跳转之前),包括:登录方式选择页、账号密码登录、短信登录、注册页等。漏一个,那个入口的小微用户就会掉进默认跳转------我们复盘时挨个页面排查过一遍。


五、约束清单:官方不明说、但会撞的墙

接收侧的坑大多是「能力边界」型的,汇总成清单:

约束 影响 应对
无法程序化返回 AI 对话 收尾只能靠用户按返回键 专用提示页 + redirectTo 让返回键落在对话
openDetailPage 仅限 tap 同步链路 「先请求后跳转」不可行 决策前置到接口层;组件只做 setRelatedPage
半屏页禁用全部页面路由 API 半屏页内不能 A→B→C 跳转 半屏内用 step 条件渲染(单页多态);重流程别放半屏
半屏页内拿不到 openDetailPage 不能从半屏再接力半屏 原子组件卡片 → 半屏页仅一次接力,不叠半屏
onAgentHandoff 为新增 API 老基础库/老客户端没有 注册前判空降级
AI 容器内 navigateTo 可能受限 手动登录页跳转有失败风险 fail 兜底 Toast;非必须不嵌套跳转

其中「半屏页禁路由」值得单独强调:官方对半屏页(Detail Page)明令禁用所有 页面路由接口(navigateTo / redirectTo / switchTab / reLaunch / navigateBack 全部不行)。想在半屏里做多步流程,只有页内 step 状态切换一条路;真的需要跨页面重流程,就别用半屏,改整页方案。


六、本篇小结

  1. 接力主流形态是 WebView 承载 :pages/WebView/index?jumpUrl=<整体编码的 H5 地址>;host 按环境替换 + 整体编码,统一从工具函数出,杜绝散拼
  2. 原子组件内跳转只走 openDetailPage ,且必须在 tap 同步链路里;viewContext 只在组件环境存在,工具做兜底
  3. onAgentHandoff 用「登记-认领-销毁」模式 :App 层按 pageId 写 sessionStore,接力页 take 后即删,天然解决时序与重复消费
  4. 登录收尾是体验塌方点 :来源标记(loginSource=miniai)→ 守卫(aiLoginSuccess)→ redirectTo 提示页 → fail 兜底 Toast;守卫要覆盖所有登录/注册出口
  5. 核心约束:无法程序化返回对话------所有收尾设计都是围绕「让用户的返回键落在正确位置」展开的
  6. 半屏页禁全部路由 API:多步流程只能页内 step 切换,重流程别放半屏

至此「端的实现」告一段落(工程落地 → skill 开发 → 接收衔接)。但三者拼起来后,谁来统筹「该用哪个 skill、用什么口吻说话、什么该拒绝」?下一篇补齐整个 Agent 的大脑:AGENTS.md 人设与意图分发------身份口径、意图 → 接口的分发表、超范围清单与失败兜底。再往后才进入上线关卡(评测)。


参考

本文为实战经验整理(基于内测版本),官方能力与流程以微信开放文档及公众平台后台为准。

相关推荐
费曼学习法6 分钟前
为什么你的 Subagent 拆完反而更慢?我把 12 万 token 的任务重做了一遍
前端
颜进强11 分钟前
微信小微AI-接入模式与开通准备|两种模式选错,后面全白干——小微接入的隐藏门槛
前端·ai编程·全栈
htzyl20614 分钟前
CSS中,`:has()` 能帮你删掉的 4 类 JS
前端·css
verohh19 分钟前
(四)配置驱动与动态渲染——从固定页面到可组合的前端架构
前端
颜进强23 分钟前
认识小微|一句话就能直接调起你小程序的微信 AI,多数人第一眼就理解错了
前端·ai编程·全栈
锐影用AI做小程序30 分钟前
uni-app X + Spring Boot 做在线工具站:6 个真实踩坑与解法
前端
掘金挖土30 分钟前
前端手摸手跑路之 AI 应用开发(十二)
前端·后端
颜进强31 分钟前
微信里冒出一个新 AI 入口,我们把接入它的每一步坑都写下来了
前端·ai编程
不要试图纠正别人31 分钟前
178 个 IPC 通道不可怕,可怕的是 preload 里那一行
前端·electron