微信小微AI-【实战二】从零写一个 skill|卡片死活不出来?这 4 个坑我们全踩了一遍

【实战二】从零写一个 skill|卡片死活不出来?这 4 个坑我们全踩了一遍

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

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

脱敏说明 :本文代码来自真实生产项目并做完整脱敏重构------业务统一为通用「产品搜索」,公司名/产品名/编号为占位符,域名替换为 h5.example.com,内部字段名已泛化;但文件组织、接口协议、分支设计、四层数据分工、所有踩坑结论均为原样,可直接作为脚手架参考。


写在前面

这是系列技术含量最高的一篇。我们把真实项目里最复杂的一个 skill------产品搜索------从目录到组件完整拆给你看:用户对小微说「帮我搜索 XX 型号」,小微命中 skill → 调原子接口搜索 → 出卡片 → 点卡片直达详情页。

全文按实现顺序展开:目录结构 → skill 入口 → mcp.json 能力声明 → 页面枚举与接力工具 → 原子接口(核心)→ 相关度校验 → 卡片组件 → SKILL.md。四个大坑穿插在对应章节:

  1. 坑 1 :handoff 是卡片渲染的开关(第五节)
  2. 坑 2 :inputSchema 实体抽取 vs context.query 兜底(第三节、第五节)
  3. 坑 3:模糊搜索必须做相关度校验,否则 AI「谎称已找到」(第六节)
  4. 坑 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"
    }
  ]
}

四个写法要点(全部影响命中率与评测):

  1. description 三段式 :业务归属(+典型实体)→ 触发条件(给出具体实体 + 意图)→ 不适用清单(明确「这类意图走别的接口」)。不适用清单是防止误命中的关键,模型真的会照它分流
  2. inputSchema 的 description 是实体抽取的「批改标准」:给「输入 → 期望抽取结果」的例子、列出要剥离的意图词、多轮指代怎么补全、禁止编造兜空串(坑 2 详解见第五节)
  3. _meta.context.query 声明兜底:声明了平台才会把用户原文透传进接口第二参数
  4. _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 字段立刻好了。三条推论:

  1. 想出卡的分支必须 返回 handoff,哪怕接力目标只是关联页面
  2. 不需要出卡的纯分流分支(链式转交下一个接口)可以不带
  3. 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 分支):

复制代码
搜索服务暂时不可用。请简短告知用户当前无法检索、建议稍后重试,禁止复述任何内部错误信息;句数与措辞结合语境自然组织。

三个原因:

  1. 固定话术会被评测判缺陷------平台「文档质量」评测对 SKILL.md 和返回内容里的固定句式、逐字措辞零容忍,该接口直接判缺陷(第 7 篇详述这个 0 分坑)
  2. 两层决定 AI 说什么 :接口 content(喂给 LLM 的料)+ SKILL.md 错误处理规则(约束)。只改一层,LLM 会照抄另一层把模板拉回来,必须两层同时改
  3. 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 }

四个设计要点:

  1. 「连续子串」是单向的:用户输入必须是产品名的连续子串。「AA 型号」匹配「AA 型号 Pro」✅(输入是候选名的子串);「AA 型号 Pro」不匹配「AA 型号」❌(用户要的比候选更具体,不能硬凑);「AA 型号 Prox」不是「AA 型号 Pro」的子串 ❌(错字不命中)
  2. 纯数字只按编号匹配 :000001 不会误配到名称里恰好含数字的产品
  3. 白名单跳过非目标分组:搜索接口可能返回文章、店铺、品牌等分组,只认本 skill 的产品分组
  4. 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>

三个实现细节:

  1. getContext 订阅 + getViewContext 设接力 是原子组件的标准姿势:前者拿接口返回(渲染卡片),后者把 handoff.query 同步给卡片标题栏入口的跳转
  2. 双问号坑 :handoff.query 由 buildJumpUrlQuery 生成自带 ?,而 setRelatedPage 约定传裸 query------不去掉前导 ? 会产生 ??jumpUrl,接力页拿不到参数
  3. 原子组件约束:无网络请求、无定时器、无页面路由 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=<编码后详情页地址>

十、本篇小结

  1. 四层返回结构:content(LLM 要点)/ structuredContent(LLM 结果)/ _meta(卡片数据)/ handoff(接力 + 出卡开关)
  2. skill 三件套:入口 path 逐字符一致、mcp.json description 三段式(归属 + 触发 + 不适用清单)、SKILL.md 只写铁律不重复清单
  3. handoff 是出卡开关 :无 handoff 组件不挂载;relatedPage 只是关联页声明
  4. 实体抽取放 inputSchema,context.query 只兜底:意图词污染和多轮指代两个事故都源于把原文当实体
  5. 相关度校验拦误报:分级匹配(精确 > 单向连续子串 > 无关)+ 类型白名单 + null 语义;未命中纯文本不出卡
  6. content 指令式 + 两层一致:接口 content 与 SKILL.md 口径同步,错误分支绝不外泄 error.message
  7. 组件侧两个细节 :getContext/getViewContext 分工、handoff.query 去前导 ? 防 ??jumpUrl

下一篇进入接收侧:小程序侧怎么衔接小微------handoff 接力页怎么接住 AI 送来的用户、WebView 怎么承载 H5、从 AI 进来的登录怎么做收尾。


参考

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

相关推荐
小虎AI生活12 分钟前
太好了!豆包终于接入了多模型,正面硬刚WorkBuddy
aigc·ai编程
颜进强15 分钟前
微信小微AI-命中效果调优|在 AI 的「选择题」里,怎么让小微更愿意选中你(系列收官)
前端·ai编程·全栈
颜进强16 分钟前
微信小微AI-【实战四】给 Agent 立人设|一份 AGENTS.md,决定小微是靠谱助手还是满嘴跑火车
前端·ai编程·全栈
颜进强16 分钟前
微信小微AI - 【实战一】工程化落地|Taro 主工程里塞进一套原生 AI 代码,我们这样让它们共存
前端·ai编程·全栈
颜进强22 分钟前
微信小微AI-【实战三】接力落地|用户点完 AI 卡片跨进小程序,那几秒才是体验的生死线
前端·ai编程·全栈
费曼学习法24 分钟前
为什么你的 Subagent 拆完反而更慢?我把 12 万 token 的任务重做了一遍
前端
颜进强29 分钟前
微信小微AI-接入模式与开通准备|两种模式选错,后面全白干——小微接入的隐藏门槛
前端·ai编程·全栈
htzyl20632 分钟前
CSS中,`:has()` 能帮你删掉的 4 类 JS
前端·css
verohh37 分钟前
(四)配置驱动与动态渲染——从固定页面到可组合的前端架构
前端