小程序 AI 开发模式 Skills 工具集

小程序 AI 开发模式 Skills 工具集#

资源概述#

wechat-miniprogram/ai-mode-skills 是微信官方维护的小程序 AI 开发模式工具集 monorepo。它解决了将现有小程序改造成 AI 可调用形态的全流程问题：从源码分析到 SKILL 生成、校验、评测。

三个核心 Skill 形成完整的流水线：

小程序源码 → wxa-skills-generate → skills/ 产物 → wxa-skills-validate → 真机/渲染验证 → wxa-skills-eval → 评测报告

适用场景#

• 将现有小程序的业务功能改造为小程序 AI 可调用的原子接口+原子组件
• 批量校验已生成的 skills/ 是否符合微信规范
• 评估 AI 调用 skill 的准确性和质量

核心概念#

• SKILL：完成特定场景任务的完整能力封装，包含 SKILL.md（业务说明）+ mcp.json（接口声明）+ apis/（接口实现）+ components/（原子组件）
• 原子接口：最小执行单元，封装单一业务功能，标准输入输出，运行在微信客户端独立 JS 环境
• 原子组件：原子接口的可视化展示单元，将结构化数据渲染为 GUI 卡片
• Handoff（接力）：原子接口返回接力数据，用户点击小程序卡片后跳转到小程序页面完成业务

设计规范#

SKILL 目录结构#

skills/{skill-name}/
├── SKILL.md          # 业务说明（≤16000 字节，单文件）
├── mcp.json          # 原子接口 Schema 声明（≤24000 字节）
├── index.js          # 注册所有原子接口
├── apis/             # 原子接口实现
└── components/       # 原子组件实现

mcp.json Schema#

每个原子接口需要声明：

• name：标识符（与 index.js 导出函数名一致）
• description：功能描述
• inputSchema：入参 JSON Schema（支持 format: "image"|"file" 多模态）
• outputSchema：建议填写，structuredContent 的 Schema
• _meta.ui.componentPath：原子组件路径
• _meta.ui.pagePath：接力页路径

app.json 配置#

{
  "lazyCodeLoading": "requiredComponents",
  "subPackages": [{
    "root": "path/to/pkg",
    "independent": true,
    "pages": []
  }],
  "agent": {
    "skills": [{
      "name": "skillName",
      "description": "技能描述",
      "path": "path/to/pkg/skillName"
    }],
    "instruction": "path/to/AGENTS.md"
  }
}

约束限制#

• 每个小程序最多 30 个 SKILL
• SKILL.md 最大 16000 字节
• mcp.json 最大 24000 字节（除去 outputSchema 后计算）
• 全局提示词（AGENTS.md）最大 10000 字节
• 原子接口返回 content / structuredContent 各最大 200 KB
• SKILL 必须封装在独立分包中

审核规范#

• 当前状态：小程序 AI 开发模式处于 内测阶段，暂未开放代码提审
• 注意事项：请勿将 AI 模式相关代码合入正式版本提交审核，以免影响正常版本发布
• 适用范围：需在「微信公众平台 - 基础功能 - AI 能力」或「微信开发者助手」中申请「开发模式」
• AppID 要求：需使用已申请 AI 开发模式内测权限的 AppID

开发指南#

快速上手：生成 SKILL#

在支持 Skills 的 IDE 中加载小程序源码后：

使用 wxa-skills-generate 帮我把这个小程序的"商品检索 + 订单管理"做成小程序 AI 的 SKILL

Skill 会按 6 个阶段执行：

1. 业务澄清：与开发者确认要覆盖的业务场景
2. 项目扫描：分析小程序源码目录结构和依赖
3. 业务识别：识别核心业务步骤和数据流
4. 接口提取：提取网络接口和 JSAPI 调用
5. 接口设计：设计原子接口的 inputSchema/outputSchema
6. 代码生成：输出完整的 skills/{skill-name}/ 目录
7. 配置集成：自动修改 app.json / project.config.json

快速上手：校验 SKILL#

使用 wxa-skills-validate 校验 ./skills 目录

校验流程：

1. 静态校验（V001~V018）：目录结构、mcp.json schema、组件文件齐全性、handoff 合法性、WXSS 禁用清单
2. 真机执行：通过微信开发者工具 CLI 运行每个原子接口，比对 outputSchema
3. 渲染验证：截图原子组件，检查溢出、空数据、深色模式
4. 就地修复：按错误类型自动修复 skill 源文件

原子接口实现示例#

// skills/drink-skill/apis/searchDrinks.js
export async function searchDrinks({ keyword }) {
  const res = await wx.request({
    url: 'https://api.example.com/drinks',
    data: { q: keyword || '' }
  })
  return {
    content: [{ type: 'text', text: `找到 ${res.data.length} 杯饮品` }],
    structuredContent: { drinks: res.data },
    handoff: {
      query: `keyword=${keyword || ''}`,
      payload: { drinks: res.data }
    }
  }
}

Handoff 接力实现#

// app.js
App({
  onLaunch() {
    wx.onAgentHandoff((path, query, payload) => {
      // 缓存 handoff 数据，接力页可读取
      const pages = getCurrentPages()
      // 导航到接力页
      wx.navigateTo({ url: `${path}` })
    })
  }
})

// 接力页
Page({
  onLoad(query) {
    // query 包含原子接口返回的 handoff.query
    // 可从缓存取 payload 加速首屏
  }
})

常见陷阱#

1. 独立 JS 环境：原子接口运行在微信客户端的独立 JS 环境，不同于小程序运行环境。部分小程序 API 不可用，需测试验证
2. 开发者工具版本：必须使用 Nightly Electron Build 最新版本，稳定版不支持 AI 模式
3. 服务端口：开发者工具内「设置 → 安全设置 → 服务端口」必须开启
4. lazyCodeLoading：必须全局开启 requiredComponents 按需注入
5. SKILL 必须在独立分包：不支持主包中的 SKILL
6. wx.onAgentHandoff / wx.openAgent 当前限制：wx.openAgent/wx.navigateBackAgent 可能不可用，接力页不要依赖「返回 Agent 对话」
7. 多模态输入：inputSchema 中 "format": "image" 或 "format": "file" 的字段会被传入用户上传的图片/文件
8. 内测阶段勿提审：AI 模式代码不能合入正式版提交审核

生态资源#

相关官方仓库#

官方文档#

• 小程序 AI 开发模式接入指南
• 接入方式
• 组件与 API 支持

社区资源#

• GitHub Issues：反馈问题
• 微信开放社区：官方技术支持

版本更新#

当前版本（核实日期：2026-07-17）#

• wxa-skills-generate：v0.2.1
• wxa-skills-validate：v0.2.1
• wxa-skills-eval：v0.1.18（升级中，暂不开放使用）
• 仓库最后活跃：2026-07-03
• License：MIT
• 创建时间：2026-06（小程序 AI 开发模式发布期间）

重要说明#

• 评测工具正在升级，开发者可关注微信开放文档或微信开发者工具获取新版
• 小程序 AI 开发模式当前处于内测阶段，API 和规范可能调整