【实战一】工程化落地|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, // 独立分包
},
],
三个注意点:
root: "MiniAI"------ 分包根目录就是项目根下的MiniAI/文件夹,不在src/里 。这是有意为之:MiniAI/是原生代码,不能进 Taro 的编译管线pages: []------ 这个分包注册的是「能力」而不是「页面」。AI 卡片页 / 接力页可以挂在这里,纯接口型 skill 可以没有页面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 篇的案例会具体展示)
五、本篇小结
- AI 代码放独立分包 :项目根下
MiniAI/,subPackages声明root + independent: true,不在src/里 agent配置必须写在 app.config.ts :skills[].description是意图匹配首层信号;path必须与createSkill路径逐字符一致;只声明官方三字段- 共存方案 :原生代码 CopyWebpackPlugin 原样拷贝到 dist,环境配置用构建前脚本写入
config.js(单一数据源) - 硬约束:mcp.json ≤24KB / SKILL.md ≤16KB / AGENTS.md ≤10KB / ≤30 skill
下一篇是系列技术含量最高的一篇:从零写一个「产品搜索」skill------handoff 为什么是卡片渲染的开关、inputSchema 实体抽取怎么做、模糊搜索结果为什么必须做相关度校验。
参考
本文为实战经验整理(基于内测版本),官方能力与流程以微信开放文档及公众平台后台为准。