ai-mode-demo：小程序小微 AI Handoff 点单示例接入指南

ai-mode-demo 是微信小程序官方在 2026 年推出的 AI 模式示例工程，以 WeStoreCafe 咖啡店点单为场景，演示「小微 SubAgent」AI Handoff（接力）模式：用户在小微对话里和小程序 AI 交互，平台返回文本回复加小程序卡片，用户点击卡片后接力进入小程序的业务页，在小程序内完成选品、下单、支付。

一、项目官方信息

项目	信息
GitHub 仓库	https://github.com/wechat-miniprogram/ai-mode-demo
开源协议	MIT
主要语言	JavaScript（约 100%）
Star 数	约 304
场景	小微 AI Handoff 点单（WeStoreCafe）

与传统小程序页面不同，本示例演示的是小程序与微信 AI（小微）之间的接力协作：对话内不渲染原子组件，只展示「文本 + 小程序卡片」，用户点卡片后由小程序接管完整业务流程。

二、官方图片

项目仓库预览图（官方 AI 模式示例工程）：

ai-mode-demo 仓库预览

三、环境要求

微信开发者工具（最新版，基础库需支持 wx.onAgentHandoff 等小微 handoff 能力）。
一个已申请「AI 开发模式 + 小微 handoff 内测权限」的小程序 AppID。
微信客户端最新版（用于真机体验小微对话）。
本机无需额外后端，示例为前端工程，种子数据内置在 data/seed.js。

四、完整接入步骤

1. 下载源码

git clone https://github.com/wechat-miniprogram/ai-mode-demo.git

2. 导入微信开发者工具

打开微信开发者工具，选择「导入项目」，目录指向 ai-mode-demo，填入已开通 AI 开发模式与小微 handoff 内测权限的 AppID。

3. 了解 handoff 接力机制

核心流程如下：

对话 → 调用原子接口（返回 handoff） → 文本回复 + 小程序卡片
  → 用户点击卡片 → 按 pagePath 打开接力页
  → wx.onAgentHandoff(path/query/payload)
  → 接力页 onLoad(query) 展示业务内容 → 小程序内普通导航完成后续

4. 开发者适配四件套

mcp.json：在 apis[]._meta.ui.pagePath 声明接力页（不含 query）。
原子接口返回值：顶层增加 handoff: { query: 'string', payload?, card? }。
app.js：onLaunch 中注册 wx.onAgentHandoff，按 pageId 缓存 { path, query, payload }。
接力业务页：onLoad(query) 解析 query，可选按 pageId 取 payload 加速首屏。

5. 编译运行

在开发者工具点击编译，通过小微 AI 对话即可体验「文本 + 小程序卡片 → 点击接力进业务页」的完整流程。

五、使用方法

接口与接力页映射

接口	handoff.query	接力页	说明
searchDrinks	`keyword=拿铁`（可空=全部）	home	搜索/浏览全部（首页）
selectDrink	`drinkId=289`	sku-picker	详情 + 选规格
createOrder	`orderId=xxx`	checkout	新建订单 → 结算页
addToOrder	`orderId=xxx`	checkout	追加商品 → 结算页
removeOrderItem	`orderId=xxx`	checkout	删除某商品 → 结算页
viewOrder	`orderId=xxx`	checkout	查看进行中订单 → 结算页
cancelOrder	空	home	取消整单 → 回首页
saveAddress	`orderId=xxx`	checkout	保存地址 → 结算页

项目结构

├── app.js / app.json / app.wxss    # 全局配置；app.js 注册 wx.onAgentHandoff
├── data/seed.js                     # 首页目录种子数据（主包）
├── pages/home/                      # 首页 + 搜索 handoff 承接页
├── skills/drink-skill/              # WeStoreCafe SKILL（独立分包）
│   ├── SKILL.md                     # 业务说明（handoff 模式）
│   ├── mcp.json                     # 原子接口声明（含 _meta.ui.pagePath）
│   ├── apis/                        # 原子接口实现（返回 handoff）
│   └── components/                  # 原子组件（小微不渲染，保留兼容）
├── packageDetail/pages/             # 接力页（独立分包）
│   ├── sku-picker                   # 详情/选规格接力页
│   └── checkout                     # 订单结算接力页
└── page-meta.json                   # 页面元数据

六、常见问题 FAQ

1. 为什么在小微对话里看不到自定义原子组件？ 当前阶段小微对话内不渲染原子组件（GUI 卡片），只展示「文本 + 小程序卡片」。组件代码与 componentPath 保留是为后续复用，半屏页 openDetailPage 改为 handoff 进完整页。

2. 接力页里想返回小微对话可以吗？ wx.openAgent / wx.navigateBackAgent 当前不可用，接力页不要依赖「返回 Agent 对话」，应在小程序内完成后续导航。

3. handoff 传参时 query 是什么类型？ handoff query 是 string；接力页 onLoad 收到的是框架解析后的对象，直接在 onLoad 里读取即可。

4. 为什么导入后报 wx.onAgentHandoff 不存在？ 基础库版本太低。需要用最新版微信开发者工具，并把项目基础库调到支持小微 handoff 的版本。

5. 没有内测权限能跑吗？ 普通界面可编译预览，但完整的小微对话接力流程需要已申请 AI 开发模式 + 小微 handoff 内测权限的 AppID。

6. 种子数据在哪里？ 首页目录数据在 data/seed.js，主包内可直接修改；业务数据接口在 skills/drink-skill/apis/ 下实现。

七、跳转链接

GitHub 仓库：https://github.com/wechat-miniprogram/ai-mode-demo
微信开发者工具下载：https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html
小程序官方文档：https://developers.weixin.qq.com/miniprogram/dev/framework/