用途
小程序 AI 开发模式（beta）开发指南，提供该模式的完整技术规范参考。开发者将小程序功能抽象为原子接口（API）和原子组件（Component），封装成 SKILL，供小程序 AI 调用。当用户通过小程序 AI 发起对话时，小程序 AI 通过小程序 MCP 协议选择合适的原子接口和原子组件，完成数据处理和任务执行，最终以 GUI 卡片展示结果。用户身份与原小程序保持一致（可通过 storage 共享登录凭证）。
职责边界
提供：AI 开发模式的完整技术规范参考；原子接口/组件的设计规范、最佳实践和禁令；content 文本写法、description 三段式模板、注意力权重原则；接入配置、调试流程、FAQ 的完整指引。
不负责：不生成业务原子接口/组件代码（交给 wxa-skills-generate）；不执行校验和修复（交给 wxa-skills-validate）；不进行端到端评测（交给 wxa-skills-eval）；不创建新小程序项目（交给 wxa-create-ai-miniprogram）。
交付物为参考文档与规范说明。
术语
- 小程序 MCP：向小程序 AI 暴露可调用能力的协议，与标准 MCP 不同，适配小程序开发特点。
- 原子接口（API）：最小执行单元，封装单一业务功能，标准化输入/输出，运行在微信客户端独立 JS 环境。
- 原子组件（Component）：原子接口的可视化展示单元，将结构化数据渲染为 GUI 卡片展示在对话流中。
- SKILL：完成特定场景任务的完整能力封装，包含 SKILL.md、mcp.json、原子接口实现、原子组件实现。
主要能力与核心概念
三层架构下的数据传递：原子接口上下文、原子组件上下文、实时动态组件上下文三者全局变量不共享，数据只能通过返回值传递；半屏页面与小程序运行环境一致，部分接口受限。
返回值字段中，content（TextContent[]，≤200KB）对 LLM 可见，用于 LLM 决策的上下文和指令；structuredContent（≤200KB）对 LLM 可见，用于 LLM 理解屏幕展示内容；_meta（≤200KB）对 LLM 不可见，为纯渲染数据（如图片 URL）。
使用方式
接入需进行全局配置 app.json，开启 lazyCodeLoading: "requiredComponents"，SKILL 必须放在独立分包中（independent: true），最多 30 个 SKILL，一个 SKILL 只能在一个分包中。SKILL 目录结构固定：SKILL.md（≤16000 字节）、mcp.json（≤24000 字节，不计 outputSchema）、index.js 以及建议目录 apis/ 与 components/。
原子接口通过 wx.modelContext.createSkill 创建实例、skill.registerAPI 注册接口、skill.use 注册中间件（洋葱模型，用于统一登录、上报、错误监听等）。接口返回 isError、content、structuredContent、_meta。mcp.json 声明 apis 与 components，处理图片/文件的接口需在 inputSchema 对应字段加 "format": "image" 或 "format": "file"。原子组件通过 wx.modelContext.getContext/getViewContext 获取上下文，监听 Result、Overflow、Expire 等事件，必须设置关联小程序页面，可通过 sendFollowUpMessage 代用户上行消息、openDetailPage 打开半屏页面。
page-meta.json（≤8000 字节）定义文字链元数据；小程序与小程序的交互接口包括 wx.openAgent、wx.navigateBackAgent、wx.checkIsSupportAgent、wx.onAgentOpen。
关键规范
注意力权重原则按优先级排列：原子接口返回的 content（★★★★★）＞ mcp.json 的 description（★★★★）与 inputSchema 字段 description（★★★★）＞ SKILL.md（★★★）。多处约束冲突时，LLM 遵循高权重位置的指令。
字段 description 三段式模板：字段语义、取值来源、【禁止编造】兜底动作，三段缺一不可。content 文本采用事实陈述 + 业务动作两段式，避免裸指令。SKILL.md 承载业务 SOP，包含业务流程图、接口依赖关系表、业务约束、用户意图分流表，且不重复 mcp.json 内容、不写 URL 字面量。
原子组件硬性约束：卡片宽度随屏幕固定，高度最小 4:1、最大 1:1 且初始化后不可变；仅支持 tap 点击与 image load/error 事件；默认不支持网络请求和定时器（需声明 permissions scope.dynamic 为实时动态组件）；不支持动画、禁止竖向滚动；必须配置 relatedPage；不支持页面路由接口。WXSS 选择器仅支持类、ID、标签、后代选择器；内置组件中 view 完全支持，text 不支持 user-select，image 仅网络地址且仅 png/jpg，canvas 仅 2d，scroll-view 仅横向滚动等。
调试与评测
开发者工具需下载 Nightly Electron Build 最新版，切换至「小程序 AI 编译」模式，基础库切至 3.16.1；真机预览需 iOS 微信 ≥8.0.74，支持打开 vConsole。生成、校验、评测分别使用 wxa-skills-generate、wxa-skills-validate、wxa-skills-eval；使用校验和评测工具前，必须在微信开发者工具「设置 → 安全设置」中开启服务端口。
适用场景与限制
适用于将小程序改造为 AI 开发模式、封装 SKILL、编写原子接口/原子组件、编写 SKILL.md 或 mcp.json 的开发者。
限制：当前处于内测阶段，暂未开放代码提审，请勿将 AI 模式代码合入正式版本提交审核；仅支持 iOS（微信 ≥8.0.74），安卓/鸿蒙暂不支持，基础库 ≥3.16.1；AI 回复不支持流式输出，仅支持纯文本或「文本 + 卡片」两种格式；原子接口超时上限为 300s（含中间件链）；半屏页面禁止所有跳转、路由、广告接口；uni-app 项目需用 patch-package 补 @dcloudio/uni-mp-weixin 的 modelContext。