【实战二】从零写一个 skill|卡片死活不出来?这 4 个坑我们全踩了一遍
系列《小微(微信小程序 AI)实战》第 4 篇
⚠️ 版本声明:本文基于小微内测版本(截至 2026-11-18 的官方文档与团队实测),微信官方尚未推出正式版本,文中接口协议、字段语义均可能随版本迭代调整,正式版发布后请以官方文档为准。
脱敏说明 :本文代码来自真实生产项目并做完整脱敏重构------业务统一为通用「产品搜索」,公司名/产品名/编号为占位符,域名替换为
h5.example.com,内部字段名已泛化;但文件组织、接口协议、分支设计、四层数据分工、所有踩坑结论均为原样,可直接作为脚手架参考。
写在前面
这是系列技术含量最高的一篇。我们把真实项目里最复杂的一个 skill------产品搜索------从目录到组件完整拆给你看:用户对小微说「帮我搜索 XX 型号」,小微命中 skill → 调原子接口搜索 → 出卡片 → 点卡片直达详情页。
全文按实现顺序展开:目录结构 → skill 入口 → mcp.json 能力声明 → 页面枚举与接力工具 → 原子接口(核心)→ 相关度校验 → 卡片组件 → SKILL.md。四个大坑穿插在对应章节:
- 坑 1 :
handoff是卡片渲染的开关(第五节) - 坑 2 :
inputSchema实体抽取 vscontext.query兜底(第三节、第五节) - 坑 3:模糊搜索必须做相关度校验,否则 AI「谎称已找到」(第六节)
- 坑 4 :
isError:true时 content 要写「指令式」(第五节)
一、先建立四层返回结构的心智模型
写任何原子接口前,先记住返回值的四层数据分工------这是开发模式最重要的心智模型,后面所有代码都围绕它:
| 字段 | 给谁用 | 管什么 |
|---|---|---|
content |
LLM | 给模型的引导文本(AI 回复用户的要点与约束,不是台词) |
structuredContent |
LLM | 供模型使用的最小结构化结果(如 {matched, productName}) |
_meta |
卡片组件 | 卡片渲染数据(不参与 schema 校验) |
handoff |
平台 | 接力数据:点卡片后去哪个页、带什么参数;同时是「出不出卡」的开关 |
二、目录结构与 skill 入口
一个 SKILL = 一个一句话能说完的完整任务。我们的组织方式:一个 skill 一个子目录,接口、组件、工具、说明全部内聚:
bash
MiniAI/skills/search-product-skill/
├── SKILL.md # 业务说明(流程、边界、铁律)
├── mcp.json # 模型可调用能力声明(description / inputSchema / UI 配置)
├── index.js # createSkill + registerAPI 入口
├── apis/
│ └── searchProduct.js # 原子接口实现(核心)
├── utils/
│ └── groupFields.js # 相关度校验 + 卡片字段归一化(纯函数)
└── components/
└── search-result-card/
├── index.js # 卡片组件逻辑(订阅接口结果)
├── index.wxml # 卡片结构(命中态 / 未命中态)
├── index.wxss # 样式
└── index.json # { "component": true }
入口 index.js 只有三行,但有一个铁律:
js
const searchProduct = require('./apis/searchProduct.js');
const skill = wx.modelContext.createSkill('MiniAI/skills/search-product-skill');
skill.registerAPI('searchProduct', searchProduct);
createSkill 的路径必须与 app.config.ts 里 agent.skills[].path 逐字符一致 (含大小写、连字符)。不一致时不报「配置错误」,而是报 Skill code loading failed------表象和第 2 篇的基础库版本问题几乎一样,根因完全不同,排查时先核对路径。
三、mcp.json:写给模型看的「能力说明书」
mcp.json 是模型路由的最高权重信号。完整版(脱敏):
json
{
"apis": [
{
"name": "searchProduct",
"description": "【业务归属】XX 商城(官方电商平台)产品检索,典型实体:XX 型号 Pro、XX 系列 2024 款、000001。按关键词模糊搜索【在售商品】,命中即出卡片并接力到该产品详情页。触发条件:用户在对话中给出【具体的产品名称 / 产品编号】,意图是【找这一个产品】(如「搜 XX 型号 Pro」「查 000001」)。【不适用清单|禁止调用本接口】:店铺 / 品牌查询;榜单 / 排行 / 销量 TOP 等浏览挑选意图(走 browseProduct)、首页(走 openHomePage)、内容资讯(走 openContentPage);也不直接回答价格对比 / 参数对比,一律不调用。",
"inputSchema": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "从本轮用户原话中抽取的检索词:只保留产品名称 / 产品编号实体,剥离「帮我 / 请 / 搜索 / 搜一下 / 查 / 找 / 看看 / 我想」等意图词与语气词(如「帮我搜索 XX 型号 Pro」→「XX 型号 Pro」,「查 000001」→「000001」)。多轮指代(如「换成 YY 型号」「刚才那个」)按历史对话补全为具体实体。【禁止编造】用户未提及且无法从上下文确定时填空字符串,禁止臆测产品名/编号。【禁止】填写店铺名 / 品牌名,以及榜单 / 排行 / 首页等浏览类关键词(这类意图分别走 browseProduct / openHomePage)。"
}
},
"required": ["keyword"]
},
"_meta": {
"context": {
"query": {
"desc": "本轮用户搜索原文,仅作 keyword 未抽取到时的兜底检索词(如模型返回空串),避免遗漏用户输入"
}
},
"ui": {
"componentPath": "components/search-result-card/index",
"pagePath": "pages/WebView/index"
}
}
}
],
"components": [
{
"path": "components/search-result-card/index",
"relatedPage": "pages/WebView/index"
}
]
}
四个写法要点(全部影响命中率与评测):
- description 三段式 :业务归属(+典型实体)→ 触发条件(给出具体实体 + 意图)→ 不适用清单(明确「这类意图走别的接口」)。不适用清单是防止误命中的关键,模型真的会照它分流
- inputSchema 的 description 是实体抽取的「批改标准」:给「输入 → 期望抽取结果」的例子、列出要剥离的意图词、多轮指代怎么补全、禁止编造兜空串(坑 2 详解见第五节)
_meta.context.query声明兜底:声明了平台才会把用户原文透传进接口第二参数_meta.ui.componentPath+pagePath:指定卡片组件与默认接力页。注意components[].relatedPage是卡片标题栏入口的关联页声明,不是渲染开关(坑 1 见第五节)
体积约束:mcp.json 去 outputSchema / 空白后 ≤ 24000 字节。真实文件里还可以声明
outputSchema(约束structuredContent的结构,帮助模型理解结果),本文示例为控制篇幅省略;description 是信息量最大的部分,写完记得量一下字节数。
四、页面枚举与接力工具
接力页地址集中在一个枚举文件里管理,不散落在代码中(脱敏版):
js
// MiniAI/enum/page.js
module.exports = {
/* 站内搜索页:未命中时引导用户更换关键词 */
searchProduct: 'https://h5.example.com/app/build/index.html#/search',
/* 产品详情页基址:末尾拼接 productId 直达 */
productDetail: 'https://h5.example.com/app/build/index.html#/product/detail/',
/* 列表页 / 分类页 / 内容页......其他 skill 的接力目标 */
}
handoff 接力统一走一个工具函数,把 H5 地址包装成 WebView 承载页的 jumpUrl 查询串:
js
// MiniAI/utils/handoff/index.js(脱敏简化版)
/**
* 构造 WebView 承载页的 jumpUrl 查询串
* @param {String} h5Url - H5 完整地址(可含各环境 host,先统一替换)
* @param {Object} params - 可选查询参数,追加到地址后
* @returns {String} 形如 '?jumpUrl=编码后地址' 的查询串
*/
function buildJumpUrlQuery(h5Url, params) {
let finalUrl = replaceH5Host(h5Url) // 按当前环境替换 H5 host(dev/test/prod)
const keys = params && typeof params === 'object' ? Object.keys(params) : []
if (keys.length > 0) {
const query = keys.map(key => key + '=' + params[key]).join('&')
const connector = finalUrl.indexOf('?') > -1 ? '&' : '?'
finalUrl = finalUrl + connector + query
}
/* 整体 URL 编码,规避特殊字符导致的参数截断 */
return '?jumpUrl=' + encodeURIComponent(finalUrl)
}
为什么要整体编码 + 专门封装:我们的接力页是 WebView 承载 H5,H5 地址里自带 #/、?、&,不整体编码会被小程序路由解析截断。所有 handoff.query 都从这个函数出,杜绝散拼。
五、原子接口:searchProduct.js 完整实现
核心来了。完整代码(脱敏重构,分支与结构原样):
js
// MiniAI/skills/search-product-skill/apis/searchProduct.js
const { productService } = require('../../../service/index.js')
const { pickBestProduct, toCardItem } = require('../utils/groupFields.js')
const { buildJumpUrlQuery } = require('../../../utils/handoff/index.js')
const pageEnum = require('../../../enum/page.js')
/**
* 产品搜索原子接口
* @param {Object} args - 模型生成的业务参数(inputSchema 抽取结果)
* @param {Object} context - 平台注入的只读上下文(_meta.context.query 声明后可用)
* @returns {Promise<Object>} content / structuredContent / _meta / handoff
*/
async function searchProduct(args = {}, context = {}) {
try {
/* ---- 坑 2 的解法:模型抽取的实体优先,用户原文兜底 ---- */
const keyword =
String((args && args.keyword) || '').trim() || (context.query || '').trim()
/* 分支一:空关键词 ------ 不硬失败追问,纯文本引导(无 handoff,不出卡) */
if (!keyword) {
return {
isError: false,
content: [{
type: 'text',
text: '请引导用户直接说出想找的产品名称或编号;简短即可,措辞与句数结合当前对话自然组织。'
}],
structuredContent: { matched: false }
}
}
/* 业务参数:公共参数(token / 设备信息等)由 http 层统一注入 */
const bizParams = {
keyword,
fuzzySearchType: 'product' // 检索模式收口:只搜商品,不搜文章/店铺等分组
}
const data = await productService.fuzzySearch(bizParams)
/* ---- 坑 3 的解法:相关度校验,无关结果一律视为未命中 ---- */
const matched = pickBestProduct((data && data.groupList) || [], keyword)
/* 分支二:未命中 ------ 如实告知,不把「名称相近的其他产品」当成目标 */
if (!matched) {
return {
isError: false,
content: [{
type: 'text',
text: `请如实告知用户:本次未检索到与「${keyword}」名称或编号匹配的产品;模糊结果里若有名称相近的其他产品,也不能当成用户要找的那个、不得谎称已找到;可建议用户更换关键词再试。简短即可,措辞与句数结合当前对话自然组织。`
}],
structuredContent: { matched: false }
}
}
/* 分支三:命中 ------ 详情定位缺失时降级,避免跳转空白详情页 */
const { groupKey, item } = matched
const productId = item.productId
const detailBase = pageEnum.productDetail
if (!productId || !detailBase) {
return {
isError: false,
content: [{
type: 'text',
text: `请引导用户前往搜索页查看该产品,需传达信息点:已找到与「${keyword}」相关的产品,但当前无法直达详情。简短即可,措辞自然组织。`
}],
structuredContent: { matched: false }
}
}
/* 分支四:正常命中 ------ 四层数据齐出 */
const cardItem = toCardItem(item) // { name, code } 卡片字段
const productName = cardItem.name || keyword
return {
isError: false,
/* content:给 LLM 的引导要点,不是台词(坑 4 详解) */
content: [{
type: 'text',
text: `请引导用户点击下方卡片查看产品详情,需传达信息点:已找到产品「${productName}」(必须包含该产品名称);若其与用户所述「${keyword}」名称不完全一致,请如实说明是按关键词找到的结果、由用户点卡核实,不得直接断言就是用户要找的那个;不得以纯文本罗列产品明细。简短即可,措辞与句数结合当前对话自然组织。接下来为用户展示产品卡片。`
}],
/* structuredContent:供模型使用的最小命中信息 */
structuredContent: { matched: true, productName },
/* _meta:卡片渲染数据,不参与 schema 校验 */
_meta: { item: cardItem, groupKey, keyword },
/* handoff:接力到产品详情页(WebView 承载 H5) */
handoff: {
query: buildJumpUrlQuery(detailBase + productId),
payload: { productName }
}
}
} catch (error) {
/* ---- 坑 4 的解法:不向 LLM 暴露内部错误详情 ---- */
console.error('searchProduct error:', error)
return {
isError: true,
content: [{
type: 'text',
text: '搜索服务暂时不可用。请简短告知用户当前无法检索、建议稍后重试,禁止复述任何内部错误信息;句数与措辞结合语境自然组织。'
}]
}
}
}
module.exports = searchProduct
5.1 坑 1 详解:handoff 是卡片渲染的开关
对比分支一/二(无 handoff)和分支四(有 handoff):
- 无
handoff→ 平台判定这是纯文本型调用,卡片组件完全不挂载 ,NotificationType.Result通知也收不到 - 有
handoff→ 平台识别为「接力型接口」,把_meta.ui.componentPath指定的组件挂载,派发 Result 通知,卡片渲染_meta里的数据
我们最初的 Bug 就是:接口返回了 content + structuredContent,模型也正确复述了引导语,但卡片死活不渲染------加一个 handoff 字段立刻好了。三条推论:
- 想出卡的分支必须 返回
handoff,哪怕接力目标只是关联页面 - 不需要出卡的纯分流分支(链式转交下一个接口)可以不带
relatedPage不是渲染开关------handoff是「出不出卡」,componentPath是「出什么卡」
5.2 坑 2 详解:为什么实体抽取必须放 inputSchema
平台透传的 context.query 是本轮用户原文------只有「帮我搜索 XX 型号 Pro」这一整句。直接拿它当检索词会出两类事故(我们都经历过):
- 意图词污染:「帮我搜索」混进检索词,后端模糊搜索结果跑偏
- 多轮指代丢实体:「换成 YY 型号」「刚才那个」------原文里根本没有实体,只有模型能结合历史对话补全
所以判定标准:复述原文的需求不需要 schema;抽取 / 归一化 / 多轮补全的需求必须放 inputSchema 让模型填,context.query 只在模型返回空串时兜底 (就是代码第一行的 || 逻辑)。取值公式:
js
const keyword =
String((args && args.keyword) || '').trim() // ① 模型抽取的实体优先
|| (context.query || '').trim() // ② 用户原文兜底
5.3 坑 4 详解:content 是「指令式」不是「台词式」
对比两种写法:
❌ 陈述式固定话术(我们最初的错误写法):
搜索服务暂时不可用,请稍后再试。
✅ 指令式(修正后,见上面 catch 分支):
搜索服务暂时不可用。请简短告知用户当前无法检索、建议稍后重试,禁止复述任何内部错误信息;句数与措辞结合语境自然组织。
三个原因:
- 固定话术会被评测判缺陷------平台「文档质量」评测对 SKILL.md 和返回内容里的固定句式、逐字措辞零容忍,该接口直接判缺陷(第 7 篇详述这个 0 分坑)
- 两层决定 AI 说什么 :接口
content(喂给 LLM 的料)+ SKILL.md 错误处理规则(约束)。只改一层,LLM 会照抄另一层把模板拉回来,必须两层同时改 error.message/ 错误码绝不拼进 content ------LLM 会原样复述给用户,泄露后端内部细节。console.error留给自己,给模型的只有指令
注意正常命中分支的 content 也是指令式:「请引导用户......需传达信息点:已找到产品「XX」(必须包含该名称)......简短即可,措辞与句数自然组织」。给模型的是要点和约束,不是台词。 其中「名称不完全一致时如实说明」这条约束,正是为坑 3 的误报场景上的第二道保险。
六、groupFields.js:相关度校验完整实现(坑 3)
先看事故:用户搜「AA 型号」,后端模糊搜索没找到完全一致的,返回第一条「AA 型号 Pro Max」。最初的处理是「取列表第一条」→ 模型对用户说「已为您找到 AA 型号!」------AI 谎称找到了。这在平台评测里是典型负例失败:期望「如实说明 + 兜底」。
为什么文案层解决不了:模型拿到的是接口处理后的单条结果,它不知道原始列表里有什么,你没法教它分辨「这条是不是用户要的」。误报必须拦在代码层。
完整实现(脱敏):
js
// MiniAI/skills/search-product-skill/utils/groupFields.js
/* 分组类型 → 卡片配置。
白名单机制:只有本 skill 支持的类型才配置,搜索结果里的文章/店铺等
其他分组一律无配置 → pickBestProduct 自动跳过,杜绝跨类型误配 */
const TYPE_CONFIG = {
'01': { groupKey: 'products', idField: 'productId', typeName: '产品' }
}
/* 代码类字段:关键词为纯数字(产品编号)时用于精确比对 */
const CODE_FIELDS = ['productCode', 'mainCode', 'productId']
/* 名称 / 关键词归一化:去空白、统一大写,规避大小写与空格差异漏判 */
function normalizeText(value) {
return String(value == null ? '' : value).replace(/\s+/g, '').toUpperCase()
}
/**
* 计算单条产品与检索词的匹配等级(先精确、后全文)
* 2 = 精确命中(编号精确 / 名称完全一致)
* 1 = 全文匹配(用户输入整体是产品名称的连续子串)
* 0 = 无关
*/
function matchLevel(keyword, item) {
const kw = normalizeText(keyword)
if (!kw) return 0
const it = item || {}
/* 纯数字关键词只认编号字段精确比对,不再回落名称匹配,避免数字误配名称 */
if (/^\d{4,}$/.test(kw)) {
for (let i = 0; i < CODE_FIELDS.length; i++) {
const code = normalizeText(it[CODE_FIELDS[i]])
if (code && code === kw) return 2
}
return 0
}
const name = normalizeText(it.productName)
if (!name) return 0
if (name === kw) return 2 /* 名称完全一致 */
if (name.indexOf(kw) > -1) return 1 /* 输入是名称的连续子串 */
return 0
}
/**
* 从模糊搜索结果中选出与关键词最匹配的一条
* 仅识别白名单分组;按匹配等级择优(精确命中提前返回);无相关命中返回 null
*/
function pickBestProduct(groupList, keyword) {
const groups = Array.isArray(groupList) ? groupList : []
let best = null
let bestLevel = 0
for (let i = 0; i < groups.length; i++) {
const group = groups[i] || {}
const config = TYPE_CONFIG[group.resultTypeCode]
if (!config) continue /* 白名单外分组直接跳过 */
const list = Array.isArray(group.list) ? group.list : []
for (let j = 0; j < list.length; j++) {
const level = matchLevel(keyword, list[j])
if (level > bestLevel) {
bestLevel = level
best = Object.assign({}, config, { item: list[j] })
if (level === 2) return best /* 精确命中,无需继续 */
}
}
}
return best /* 全部无关 → null */
}
/* 卡片展示字段归一化:只取名称 + 编号,字段口径与站内搜索页一致 */
function toCardItem(item) {
const it = item || {}
return { name: it.productName || '', code: it.productCode || '' }
}
module.exports = { TYPE_CONFIG, pickBestProduct, toCardItem }
四个设计要点:
- 「连续子串」是单向的:用户输入必须是产品名的连续子串。「AA 型号」匹配「AA 型号 Pro」✅(输入是候选名的子串);「AA 型号 Pro」不匹配「AA 型号」❌(用户要的比候选更具体,不能硬凑);「AA 型号 Prox」不是「AA 型号 Pro」的子串 ❌(错字不命中)
- 纯数字只按编号匹配 :
000001不会误配到名称里恰好含数字的产品 - 白名单跳过非目标分组:搜索接口可能返回文章、店铺、品牌等分组,只认本 skill 的产品分组
- null 就是「未命中」,绝不负条件取第一条------然后由接口分支二接住,纯文本如实告知
未命中分支的取舍 (我们踩完坑后的收敛结论):未命中也可以出卡接力到搜索页让用户自己再找,但最终我们收敛为未命中不出卡、纯文本如实告知------少一次跳转,更重要的是杜绝「名称相近的产品被当成目标」的任何误引导路径。
七、卡片组件:search-result-card 完整实现
原子组件与普通自定义组件的关键差异:没有父组件传参,渲染数据来自 wx.modelContext 的订阅。
js
// components/search-result-card/index.js
Component({
data: {
matched: false, /* 是否命中具体产品 */
item: null /* 命中时 { name, code } */
},
lifetimes: {
created() {
/* 模型上下文:订阅原子接口的 Result 通知 */
this._modelCtx = wx.modelContext.getContext(this)
/* 视图上下文:动态设置接力页 query(详情页地址随产品变化) */
this._viewCtx = wx.modelContext.getViewContext(this)
const { NotificationType } = wx.modelContext
this._modelCtx.on(NotificationType.Result, (data) => {
this._renderResult((data && data.result) || {})
})
}
},
methods: {
_renderResult(result) {
const sc = result.structuredContent || {}
const meta = result._meta || {}
this.setData({ matched: !!sc.matched, item: meta.item || null })
/* 用接口返回的 handoff.query 同步「进小程序」关联页,
保证命中跳详情页 ------ 这就是接口侧 handoff 与组件侧 setRelatedPage 的衔接点 */
const handoff = result.handoff || {}
if (handoff.query && this._viewCtx
&& typeof this._viewCtx.setRelatedPage === 'function') {
/* setRelatedPage 的 query 约定为裸 query(框架自动补 ?);
handoff.query 自带前导 ?,必须去掉,否则出现 ??jumpUrl 双问号 Bug */
const relatedQuery = handoff.query.charAt(0) === '?'
? handoff.query.slice(1) : handoff.query
this._viewCtx.setRelatedPage({ query: relatedQuery })
}
}
}
})
xml
<!-- components/search-result-card/index.wxml -->
<view class="sr-card">
<!-- 命中态 -->
<block wx:if="{{matched && item}}">
<view wx:if="{{item.name}}" class="sr-name">{{item.name}}</view>
<view wx:if="{{item.code}}" class="sr-code">{{item.code}}</view>
<view class="sr-tip">点击卡片查看产品详情</view>
</block>
<!-- 未命中态(当前口径下未命中不出卡,此态为兜底保留) -->
<block wx:else>
<view class="sr-empty">
<view class="sr-name">未找到相关产品</view>
<view class="sr-tip">请更换关键词再试</view>
</view>
</block>
</view>
三个实现细节:
getContext订阅 +getViewContext设接力 是原子组件的标准姿势:前者拿接口返回(渲染卡片),后者把handoff.query同步给卡片标题栏入口的跳转- 双问号坑 :
handoff.query由buildJumpUrlQuery生成自带?,而setRelatedPage约定传裸 query------不去掉前导?会产生??jumpUrl,接力页拿不到参数 - 原子组件约束:无网络请求、无定时器、无页面路由 API,跳转全部交给 handoff 机制
八、SKILL.md:业务规则收口
SKILL.md 是模型看的第三层说明书(权重:mcp.json > AGENTS.md > SKILL.md),只写业务流程与铁律,不重复 mcp.json 的长清单(避免多处漂移)。本 skill 的关键条目(脱敏节选):
markdown
## 业务流程(两段分支)
- A 命中:searchProduct()(关键词由模型从原话抽取实体,原文兜底)
→ 取最匹配的产品 → 简短引导语 + 单条产品卡片 → 点卡接力详情页
- B 未命中 / 空关键词:纯文本如实告知,不出卡
## 关键词取值(keyword)
- 只保留产品名 / 编号实体,剥离意图词;多轮指代按历史对话补全
- 未给具体对象 → 填空串,禁止编造;歧义短语 → 反问澄清,禁止猜测
## 输出形态
- 只出文本 + 一张卡片,禁止罗列产品名/编号/价格明细
- 命中:须包含产品名称,提示点卡查看详情;名称与搜索词不完全一致时
如实说明是按关键词找到的结果
- 未命中:如实告知未检索到,名称相近的其他产品不能当成目标
- 句数与措辞由 Agent 结合对话语境自然组织,不限定固定句式
注意最后一条------「不限定固定句式」与接口 content 的指令式写法是配套的,两层口径必须一致(坑 4)。
九、完整调用链总览
sql
用户:「帮我搜索 XX 型号」
↓
模型读 mcp.json description → 判断意图命中 searchProduct
↓
模型按 inputSchema.description 抽实体 → keyword = "XX 型号"
↓
调用 searchProduct(keyword, context)
├─ keyword 为空 → context.query 兜底;仍为空 → 纯文本引导(无 handoff)
├─ 调后端模糊搜索(http 层注入公共参数)
├─ pickBestProduct 相关度校验
│ ├─ null → 纯文本如实告知(无 handoff,不出卡)
│ └─ 命中 → content + structuredContent + _meta + handoff 四层齐出
└─ 异常 → isError:true + 指令式 content(不含内部错误)
↓
handoff 存在 → 框架挂载 search-result-card → 组件订阅 Result 渲染 _meta.item
└─ 组件 setRelatedPage(handoff.query 去前导?) 同步接力地址
↓
模型按 content 要点组织回复(含产品名,不罗列明细)
↓
用户点卡片 → WebView 承载页 ?jumpUrl=<编码后详情页地址>
十、本篇小结
- 四层返回结构:content(LLM 要点)/ structuredContent(LLM 结果)/ _meta(卡片数据)/ handoff(接力 + 出卡开关)
- skill 三件套:入口 path 逐字符一致、mcp.json description 三段式(归属 + 触发 + 不适用清单)、SKILL.md 只写铁律不重复清单
handoff是出卡开关 :无 handoff 组件不挂载;relatedPage只是关联页声明- 实体抽取放 inputSchema,
context.query只兜底:意图词污染和多轮指代两个事故都源于把原文当实体 - 相关度校验拦误报:分级匹配(精确 > 单向连续子串 > 无关)+ 类型白名单 + null 语义;未命中纯文本不出卡
- content 指令式 + 两层一致:接口 content 与 SKILL.md 口径同步,错误分支绝不外泄 error.message
- 组件侧两个细节 :getContext/getViewContext 分工、handoff.query 去前导
?防??jumpUrl
下一篇进入接收侧:小程序侧怎么衔接小微------handoff 接力页怎么接住 AI 送来的用户、WebView 怎么承载 H5、从 AI 进来的登录怎么做收尾。
参考
本文为实战经验整理(基于内测版本),官方能力与流程以微信开放文档及公众平台后台为准。