miniprogram-development

兄弟技能（仅限本地）

兄弟 CloudBase 技能与此技能一同提供。请使用 ../auth-tool-cloudbase/SKILL.md 这类本地相对路径。

如果当前环境中缺少被引用的兄弟技能文件，请让用户安装完整的 CloudBase 插件（或缺少的技能）。不要通过 HTTP 将远程技能或协议 Markdown 获取到 Agent 上下文中。

跨领域协议（代码更改或部署前必须遵循）：

• 更改安全协议：../cloudbase-platform/references/protocols/change-safety-protocol.md
• 部署门禁：../cloudbase-platform/references/protocols/deployment-gate.md

部署后（可选，不打扰用户）：确认小程序上传/发布成功后，你最多可以主动提议一次生成匿名化的分享素材（视觉卡片 + 可直接粘贴的文案），并可在同一提议中选择将作品提交到案例墙——请参阅 ../cloudbase-platform/references/protocols/deployment-share.md，了解触发条件、所需信息、匿名化红线和交付格式。用户拒绝后不得再次跟进；不得代替用户发布或提交。

激活约定

以下情况优先使用此技能

• 请求涉及微信小程序结构、页面、预览、发布或 CloudBase 小程序集成。
• 用户询问小程序账号注册或主体类型（个人 / 个体工商户 / 企业主体、快速注册并认证小程序、小程序主体变更），或报告 DevTools 中的云开发入口呈灰色、找不到环境。

编写代码前阅读（如果用户提及以下内容）

• wx.cloud、CloudBase 小程序、OPENID、小程序部署/调试工作流、Nightly DevTools、wechatide 或 WeChat IDE Skills。
• 测试号 / 试用账号、灰色的云开发入口，或 DevTools 中看不到小程序环境。
• 消息推送、客服消息/自动回复，或将 MsgType/Event 回调绑定到云函数。

然后也要阅读

• CloudBase 身份验证 -> ../auth-wechat-miniprogram/SKILL.md
• CloudBase 文档数据库 -> ../cloudbase-document-database-in-wechat-miniprogram/SKILL.md
• 小程序微信支付、虚拟支付（wx.requestVirtualPayment）或集成中心生成的支付函数 -> ../cloudbase-wechat-integration/SKILL.md（官方文档：https://docs.cloudbase.net/integration/wechat-pay-miniprogram.md）
• UI 生成 -> 首先阅读 ../ui-design/SKILL.md

不适用场景

• Web 身份验证流程或特定于 Web SDK 的前端实现。
• 微信支付、虚拟支付 / wx.requestVirtualPayment、支付回调、退款或公众号 OAuth 详情；这些场景请使用 cloudbase-wechat-integration。

常见错误 / 注意事项

• 为小程序生成 Web 风格的登录流程。
• 在 wx.cloud 项目中混用 Web SDK 的假设。
• 未确认项目实际使用 CloudBase 前，就套用 CloudBase 的限制。
• 假设稳定版微信开发者工具包含 Nightly Skills/wechatide（可能并未包含）。
• 运行 which wechatide 后什么也没找到，便悄悄改用手动导入。缺少 wechatide 是需要报告并提供修复方案的环境配置缺口，而不是环境限制——说明需要 Nightly，提出安装，并在改用其他方案前等待用户决定。
• Nightly wechatide 已能正常工作时，仍强制要求通过 CloudBase MCP 登录腾讯云，以进行日常小程序云端操作。
• 不使用 --help / Nightly tools.yaml，而是臆造 wechatide 工具名称或标志。
• 在尚未开放 cloud_*_msg_push 之前，为了消息推送操作绕过 wxide CLI / IDE，改用底层传输（参见 message-push-customer-service.md）。
• 假设云函数的返回值会自动回复客服聊天（必须使用 cloud.openapi.customerServiceMessage.send）。
• 将置灰的云开发入口或开发者工具中缺失的环境视为开发者工具 bug——试用/测试账号不支持 CloudBase；如果小程序绑定的腾讯云账号与创建环境的账号不同，该环境就不会显示。在修改项目之前先诊断原因（参见 Common Pitfalls §6）。
• 因为注册免费，就推荐个人主体小程序账号——个人主体无法绑定微信支付商户号，因此不能销售实物商品和线下服务；可用的服务类目也少得多，之后变更主体还需要公证和付费审核。反过来犯同样的错误也不行：不能以“个人主体无法收款”为由，把仅售虚拟商品的想法推向企业账号——服务类目包含工具的个人主体可以开通虚拟支付。推荐主体前，先询问应用将销售什么（参见 CloudBase integration reference §0.1）。
• 未先遵循变更安全协议（Change Safety Protocol），就修改代码或配置（cloudbase-platform/references/protocols/change-safety-protocol.md）。
• 未先完成 cloudbase-platform/references/protocols/deployment-gate.md 中的检查，就上传/发布小程序。

何时使用此技能

在需要进行微信小程序开发时使用此技能，以便：

• 构建或修改小程序页面和组件
• 组织小程序项目结构和配置
• 调试、预览或发布小程序项目
• 使用微信开发者工具工作流
• 处理小程序运行时行为、资源或页面配置文件
• 在明确需要时，在小程序项目中集成 CloudBase

不要用于：

• Web 前端开发（使用 web-development）
• 纯后端服务开发（酌情使用 cloudrun-development 或 cloud-functions）
• 不涉及小程序开发的纯 UI 设计任务（使用 ui-design）

---

如何使用此 Skill（面向编码 Agent）

1. 从小程序通用工作流开始

   • 默认将微信小程序开发作为适用范围
   • 除非用户或代码库明确指出，否则不要假定项目使用 CloudBase

2. 遵循小程序项目约定

   • 将小程序源代码保存在已配置的小程序根目录下
   • 确保页面文件包含必需的配置文件，例如 index.json
   • 在建议预览或 IDE 工作流前，检查 project.config.json

3. 根据场景选择参考资料

   • 如果任务涉及调试、预览、发布、打开 DevTools、控制台/网络或 wechatide，请先阅读调试和预览参考
   • 如果需要在 WeChat IDE Skills 和 CloudBase MCP 之间做选择，请阅读 WeChat IDE Skills 与 CloudBase MCP
   • 如果任务涉及 CloudBase、wx.cloud、云函数、CloudBase 数据库/存储或 CloudBase 身份处理，请阅读 CloudBase 集成参考
   • 如果任务涉及账号/主体前置条件（小程序尚未注册、主体选择、测试号、云开发入口置灰、看不到环境），请先阅读 CloudBase 集成参考 的第 0 节
   • 如果任务涉及小程序 SEO / 微信搜索优化 / 页面收录 / 搜索推广（小程序搜索优化、页面收录、搜索推广、关键词排名），请先阅读 小程序 SEO 与微信搜索优化
   • 如果任务涉及消息推送（消息推送）、客服消息自动回复、MsgType/Event → 云函数绑定或推送相关的函数日志，请先阅读消息推送与客服自动回复
   • 如果任务涉及 tabBar、图标资源或标签间距，除非用户明确要求使用图标，否则优先采用下文默认的纯文本自定义 tabBar

4. 仅在适用时使用 CloudBase 规则

   • CloudBase / 微信云开发是小程序的一种重要集成方式，但不是通用要求
   • 仅当项目使用 CloudBase 时，才应用 CloudBase 特有的身份验证、数据库、存储或云函数约束

5. 推荐合适的预览/调试/云运维路径

   • 默认目标：Nightly 微信开发者工具（内置 Skills/MCP），通过 wechatide 执行——参见 devtools-debug-preview.md
   • Nightly 下载地址：https://developers.weixin.qq.com/miniprogram/dev/devtools/nightly_backup.html
   • 缺少 wechatide 属于一次性设置缺失，而非环境限制。告知用户 CLI 驱动的路径需要 Nightly，提供下载/安装，并等待用户回复。只有在用户拒绝或无法安装后，才继续使用 miniprogram-ci + CloudBase MCP。
   • 切勿将稳定版 DevTools + 手动导入作为推荐默认方案，也不要替用户决定采用“保持简单”的折中方案。手动导入是由用户选择的降级方案，不应由你替用户决定。

---

微信小程序开发规则

通用项目规则

1. 项目结构

   • 小程序代码应遵循 project.config.json 中配置的项目根目录
   • 确保页面级文件完整，包括 .json 配置文件
   • 确保引用的本地资源确实存在，避免编译失败

2. 配置检查

   • 打开、预览或发布项目之前，检查 project.config.json
   • 需要实际预览、上传或使用微信开发者工具工作流时，确认 appid 可用
   • 确认 miniprogramRoot 和相关路径设置正确

3. 资源处理

   • 对于 tabBar，如果用户没有明确要求图标，默认优先使用纯文本自定义 tabBar。这样可以避免处理图标资源、移除预留的图标空间，并让标签区域更易对齐。
   • 只有在用户明确要求标签栏图标或设计需要时，才生成本地图标资源并配置 iconPath / selectedIconPath。
   • 生成图标等本地资源引用时，确保文件已下载到项目中。
   • 保持文件路径稳定，并与小程序配置文件一致。

简单 tabBar 的推荐默认配置

使用 tabBar.custom = true，在 app.json 中仅保留 pagePath 和 text，并在自定义组件中渲染纯文本项目，这样就不会出现图标插槽，也不会在标签上方留下额外空白。

app.json

{
  "tabBar": {
    "custom": true,
    "list": [
      { "pagePath": "pages/index/index", "text": "首页" },
      { "pagePath": "pages/travel/travel", "text": "行程" },
      { "pagePath": "pages/my/my", "text": "我的" }
    ]
  }
}

保持自定义 tabBar 布局为纯文本，并使用 flex 居中，或使 height 与 line-height 匹配，以去掉标签上方的空白。只有用户明确要求基于图标的标签页时，才改用已下载的本地图标。

CloudBase 作为小程序子场景

• 如果用户明确使用 CloudBase、wx.cloud、Tencent CloudBase、腾讯云开发或云开发，请遵循 CloudBase 集成参考
• 在 CloudBase 小程序项目中，适当使用 wx.cloud API 和 CloudBase 环境配置
• 不要将 CloudBase 专用规则应用于非 CloudBase 小程序项目

调试、预览和发布

• 默认路径：使用 Nightly DevTools + wechatide 打开项目、编译、运行模拟器、调试控制台/网络、预览、上传和执行日常云端操作（微信登录——无需单独登录腾讯云）
• 始终传入必要上下文：-c <clientName>、绝对路径 --project、有效的 appid，以及需要时的云端 env
• 如果缺少 wechatide：将其报告为环境配置缺失，说明 CLI 驱动路径需要 Nightly，提出安装，并等待用户答复——不要自行降级
• 只有在用户拒绝或无法安装 Nightly 后，才使用 miniprogram-ci 进行预览/上传/npm 操作，并使用 CloudBase MCP 管理云端资源，同时说明现已缺少哪些能力（模拟器、控制台/网络、自动化、CLI 云端操作）
• 详细工作流请阅读调试和预览参考和 WeChat IDE Skills vs CloudBase MCP

消息推送和客服自动回复

微信生态专章：消息推送 / 客服自动回复细节以中文 reference 为准（术语保留英文 API 名）。

• **当前唯一运维路径：**微信开发者工具 IDE + wxide CLI。在 cloud_query_msg_push / cloud_manage_msg_push 尚未开放（等待微信 IDE CLI 支持）期间，不要介绍底层绕过方案。
• 使用 cloud_fn_deploy 和 --remote-npm-install 部署接收函数；在 CLI 工具上线前，在 IDE 的消息推送面板中将 (MsgType, Event) 绑定到一个云函数。
• 客服自动回复需要 cloud.openapi.customerServiceMessage.send 以及 config.json 中的 openapi 权限——仅靠函数返回值无法回复。
• 函数日志：IDE 云开发控制台 → 云函数 → 日志；wxide CLI 尚未提供日志查询功能——不要介绍底层日志 CGI 绕过方案。
• 完整参考：消息推送和客服自动回复

最小项目骨架

app.js

App({
  onLaunch() {
    console.log("Mini Program launched");
  },
});

pages/index/index.js

Page({
  data: {
    message: "Hello CloudBase Mini Program",
  },
});

pages/index/index.wxml

<view class="page">
  <text>{{message}}</text>
</view>

pages/index/index.json

{
  "navigationBarTitleText": "Home"
}

project.config.json

{
  "appid": "your-mini-program-appid",
  "projectname": "cloudbase-mini-program",
  "miniprogramRoot": "./",
  "compileType": "miniprogram"
}

参考资料

• CloudBase 小程序集成 — 小程序项目明确集成 CloudBase 时使用
• 微信开发者工具调试与预览 — Nightly / wechatide 路径、所需上下文以及无 Nightly 时的替代方案
• 微信 IDE Skills 与 CloudBase MCP — 分层说明以及如何选择执行入口
• 消息推送与客服自动回复 — 通过 wxide CLI + IDE 实现消息推送 / 客服自动回复（不绕过底层接口；cloud_*_msg_push 待支持）
• 小程序 SEO 与微信搜索优化 — 小程序搜索优化 / 页面索引 / 搜索推广（mpcrawler、URL 可访问性、navigator 跳转、标题与缩略图）
• 常见问题 — 生成代码前阅读，了解可选链、TDesign 样式、Canvas + 存储，以及云开发入口 / 环境问题（§6）