wechat-miniprogram-ailisted

# 微信小程序 AI 接入开发指南 本 Skill 面向 Codex、Claude Code、Cursor、Qwen Code 等代码代理。代理应扫描项目、判断接入模式、拆解业务闭环，并直接生成合理的代码补丁，而不是只输出概念说明。 先区分两个概念：本文件是给代码代理使用的“开发指南 Skill”；微信运行时里每个业务能力也有一个 `SKILL.md`，下文统一称为“微信 AI `SKILL.md`”。 ## 1. 官方状态护栏 - 默认把“小程序 AI 开发模式”视为 beta/内测能力，除非微信官方文档明确说明已开放正式提审。 - 涉及上线、审核、正式发布前，必须复查微信官方文档。按 2026-06 官方文档，当时暂未开放该模式代码提审，不应把相关代码合入正式版本提交审核。 - 优先依据微信官方文档和官方 Demo `wechat-miniprogram/ai-mode-demo`，不要以第三方博客作为规范来源。 - AI 模式代码应尽量隔离，避免影响普通小程序版本发布。 - 不要假设所有正式版微信开发者工具都支持调试 AI 开发模式；必要时提示使用支持该能力的 Nightly 版本。 ## 2. 先判断接入模式 拿到项目后，先判断模式，再动手改造。不要默认直接做开发模式。 ### 自动模式 适合： - 小程序业务流程短，页面结构清晰。 - 团队希望低成本先接入，暂时无法投入微信 AI SKILL 开发。 - 主要目标是让 AI 能理解页面、辅助用户操作，而不是稳定编排核心交易链路。 处理方式： - 优化页面标题、按钮文案、表单 label、空状态、错误提示、权限提示。 - 检查关键页面是否有明确用户动作路径：搜索、选择、填写、确认、支付、取消。 - 降低页面交互复杂度，避免隐藏入口、强运营位遮挡、流程依赖长链跳转。 风险： - AI 可能绕过首页、运营位、品牌露出。 - 页面复杂时 GUI 操作不稳定。 - 开发者对 AI 执行顺序、参数来源、错误处理的控制较弱。 ### 开发模式 适合： - 交易、预约、下单、查询、售后、会员、内容检索等核心流程。 - 需要稳定、可审计、可控的 AI 执行。 - 需要在微信 AI 对话流里展示自定义业务卡片。 处理方式：把业务拆成若干微信 AI SKILL，每个 SKILL 包含业务说明、`mcp.json`、原子接口、按需实现的原子组件，并在 `app.json` 的 `agent.skills` 中注册。 推荐策略：自动模式用于通用页面兜底，开发模式承接核心业务闭环。`pageMetadata` 是文字链/页面元数据能力，可作为兜底补充，不要把它当成自动模式的必要配置。 ## 3. 项目改造总流程 内部按以下顺序执行；除非用户只要方案，否则优先直接修改代码： 1. 审查项目现状：`pages`、`components`、`services`、`api`、`store`、`utils`、`app.json`、`project.config.json`。 2. 判断项目是原生小程序、Taro、uni-app 还是其他跨端框架。 3. 找到分包、业务 API/service、登录态、缓存、支付、地址、上传等关键流程。 4. 如果是 uni-app，检查是否会替换全局 `wx` 导致 `wx.modelContext` 丢失；必要时按官方 FAQ 给 `@dcloudio/uni-mp-weixin` 打补丁。 5. 找出 1-3 个最适合 AI 化的用户任务，不要贪