微信小微AI - 【实战一】工程化落地|Taro 主工程里塞进一套原生 AI 代码,我们这样让它们共存

【实战一】工程化落地|Taro 主工程里塞进一套原生 AI 代码,我们这样让它们共存

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

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

案例代码已脱敏:业务场景以通用的「产品搜索」代称,公司、产品名、产品编号均以占位符表示。


写在前面

从这篇开始进入实战。第一个工程问题:AI 开发模式的代码放在哪、怎么注册、怎么和现有工程共存?

我们的主工程是 Taro 3.x(React + MobX),而 AI 开发模式要求的是原生小程序语法 (WXML/WXSS/JS/JSON + mcp.json)。两者怎么共存在一个工程里?答案是:独立分包 + 原样拷贝,不经 Taro 编译。


一、MiniAI 是一个独立分包

开发模式的代码官方要求放在一个独立分包 (independent subpackage)里,我们命名为 MiniAI/,放在项目根目录(与 src/ 平级):

ts 复制代码
// src/app.config.ts
subPackages: [
  ...routes,
  {
    root: "MiniAI",
    pages: [],
    independent: true,   // 独立分包
  },
],

三个注意点:

  1. root: "MiniAI" ------ 分包根目录就是项目根下的 MiniAI/ 文件夹,不在 src/ 里 。这是有意为之:MiniAI/ 是原生代码,不能进 Taro 的编译管线
  2. pages: [] ------ 这个分包注册的是「能力」而不是「页面」。AI 卡片页 / 接力页可以挂在这里,纯接口型 skill 可以没有页面
  3. independent: true ------ 独立分包,不依赖主包,符合官方对 AI 分包的隔离要求

目录结构

bash 复制代码
MiniAI/
├── AGENTS.md              # AI 整体行为规范(人设 / 能力边界 / 意图分发表)
├── config.js              # env / baseUrl(构建前由脚本写入)
├── page-meta.json         # 可跳转页面元数据(可选)
├── biz/                   # 业务逻辑
├── service/               # HTTP 服务层(原子接口调后端)
├── utils/                 # handoff / http / navigation / wx 等工具
├── enum/                  # 页面 / 用户 / 缓存枚举
├── eval/                  # 评测用例
└── skills/                # AI 技能,每个子目录一个 SKILL
    └── search-product-skill/
        ├── SKILL.md       # 业务说明(流程、边界、分流规则)
        ├── mcp.json       # 模型可调用能力声明(description / inputSchema / UI 配置)
        ├── index.js       # createSkill + registerAPI 入口
        ├── apis/          # 原子接口实现
        ├── components/    # 原子组件(对话流卡片)
        └── utils/         # skill 内部工具

一个 SKILL = 一个一句话能说完的完整任务(如「按名称/编号搜一个产品」)。我们的做法是一个 skill 一个子目录,接口、组件、说明全部内聚。


二、关键:agent 配置必须写在 app.config.ts

这是本篇最重要的一个点,也是新人最容易放错位置的地方。

skill 写好不等于被注册。必须在应用配置 (Taro 工程里即 src/app.config.ts)声明 agent 字段:

ts 复制代码
// src/app.config.ts
agent: {
  skills: [
    {
      name: "searchProduct",
      description:
        "产品搜索:用户想找平台在售的一个具体商品时调用,按商品名称或商品编号检索,命中即出卡片直达商品详情页。典型表达:「帮我搜索 XX 型号」「查 000001」(示例占位,请替换为你自己的业务实体)。",
      path: "MiniAI/skills/search-product-skill",
    },
    // ... 其余 skill 同理
  ],
  instruction: "MiniAI/AGENTS.md",
  // pageMetadata: "MiniAI/page-meta.json",  // 可选,见下文
},

2.1 三个字段各管什么

字段 作用 踩坑提醒
name skill 标识 官方仅要求 name / description / path 三项,不要自创字段------我们早期多声明了一个非官方字段,官方明确后已删除
description 意图匹配的首层信号 小微靠它判断「该不该调你」,是命中率优化的主战场之一(第 10 篇展开)。要写:能力 + 典型表达 + 不适用清单
path skill 目录 必须与 createSkill(path) 的路径逐字符一致 ,不一致 → Skill code loading failed

instruction 指向 AGENTS.md(AI 的整体人设与能力边界),pageMetadata(page-meta.json)是可选的页面元数据声明------注意:启用它会放开浏览类意图(账号卡片/服务直达),可能与你的能力边界冲突,我们目前保持不启用,见第 10 篇分析。

2.2 path 一致性,用代码说话

js 复制代码
// MiniAI/skills/search-product-skill/index.js
const searchProduct = require('./apis/searchProduct.js');

const skill = wx.modelContext.createSkill('MiniAI/skills/search-product-skill');
skill.registerAPI('searchProduct', searchProduct);

createSkill('MiniAI/skills/search-product-skill') 必须与 app.config.ts 里 agent.skills[].path 完全一致 (含大小写、连字符)。这是静默失败型的坑:配置对不上时不是报「配置错误」,而是报 skill 加载失败,很容易误判成代码问题(参考第 2 篇的 createSkill is not a function,两个坑的表象几乎一样,根因完全不同)。


三、原生代码与 Taro 主工程共存

MiniAI/ 是原生小程序语法,而主工程走 Taro 编译。我们的方案:构建时用 CopyWebpackPlugin 原样拷贝到 dist,完全绕开 Taro 编译管线:

js 复制代码
// config/prod.js(节选)
chain.plugin("copy-mini-ai").use(CopyWebpackPlugin, [
  [
    {
      from: path.resolve(__dirname, "..", "MiniAI"),
      to: path.resolve(__dirname, "..", "dist", "MiniAI"),
      transform: minifyMiniAI,   // 拷贝时做压缩
    },
  ],
]);

这个方案带来一个衍生问题:环境配置注入 。Taro 侧的环境变量(接口域名等)走编译期 defineConstants / env 注入,而 MiniAI/ 不经编译,拿不到这些注入。我们的做法是构建前脚本改写 MiniAI/config.js:

js 复制代码
// startupProgram.js(节选,构建前执行)
/**
 * MiniAI 目录被 copy 原样拷贝到 dist(不经 Taro 编译),
 * 因此需要在构建前将当前环境的 env / baseUrl 写入 MiniAI/config.js
 */
const changeMiniAIConfig = function () {
  const serviceConfig = require('./serviceConfig');
  let serviceUrlEnv = process.env.SERVICE_URL_ENV;
  // ... 从 serviceConfig(单一数据源)取当前环境 baseUrl,写入 MiniAI/config.js
};

要点:

  • 单一数据源 :MiniAI/config.js 的 baseUrl 从主工程的 serviceConfig.js 派生,避免两处配置漂移
  • 写入时机 :必须在 copy 发生之前(构建入口脚本里先改写、后构建)
  • 不用这套拷贝方案、直接把 AI 代码放进 src/ 让 Taro 编译行不行?理论上可探索,但原生语法(mcp.json、组件结构)不在 Taro 编译范围内,官方示例与调试工具链都按原生目录结构设计,不建议逆着来

四、配置硬约束速查

内测版本的硬性限制,超限直接过不了预检/评测:

约束项 上限
mcp.json(去 outputSchema/空白后) ≤ 24000 字节
SKILL.md ≤ 16000 字节
AGENTS.md ≤ 10000 字节
SKILL 数量 单小程序 ≤ 30 个

实务建议:

  • description 很容易写超------「典型表达 + 不适用清单」信息量大,写完量一下字节数(是去空白后的字节数,不是字符数)
  • 一个 skill 的 mcp.json 里可以放多个原子接口,接口多时优先拆 skill 还是拆接口?经验:按用户意图拆 skill,意图内多分支用接口(第 4 篇的案例会具体展示)

五、本篇小结

  1. AI 代码放独立分包 :项目根下 MiniAI/,subPackages 声明 root + independent: true,不在 src/ 里
  2. agent 配置必须写在 app.config.ts :skills[].description 是意图匹配首层信号;path 必须与 createSkill 路径逐字符一致;只声明官方三字段
  3. 共存方案 :原生代码 CopyWebpackPlugin 原样拷贝到 dist,环境配置用构建前脚本写入 config.js(单一数据源)
  4. 硬约束:mcp.json ≤24KB / SKILL.md ≤16KB / AGENTS.md ≤10KB / ≤30 skill

下一篇是系列技术含量最高的一篇:从零写一个「产品搜索」skill------handoff 为什么是卡片渲染的开关、inputSchema 实体抽取怎么做、模糊搜索结果为什么必须做相关度校验。


参考

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

相关推荐
小巫编程室8 分钟前
我造了一个 Java 能力包:让 AI 直接调用你的业务代码
java·前端·后端
小y的笔记13 分钟前
JavaScript URL 状态同步
前端·javascript
十有八七14 分钟前
手搓 Agent(五):学会翻书——RAG,先查资料再回答
前端·人工智能·后端
Swot27 分钟前
产品 RAG 知识库与 AI 顾问 设计与实现
前端·后端
htzyl2062 小时前
前端样式-弹窗淡入淡出,为什么你的 `transition` 一直不生效
前端·css·html
Brookty2 小时前
CSS基础知识(二):盒模型、内外边距、外边距折叠与父子元素的布局关系
前端·css
十有八七2 小时前
手搓 Agent(四):长点记性——上下文满了怎么办,怎么记住上一次
前端·人工智能·后端
工程小白菜3 小时前
ai-code-review 全链路:让 AI 来审 AI 的代码
ci/cd·ai编程
小虎AI生活3 小时前
8万星开源HyperFrames,我用WorkBuddy免费模型做了3条视频
aigc·ai编程