Wx Cloudfunctions

WX Cloud Functions

Contract

Use this skill to develop TypeScript WeChat cloud functions following the project's layered module conventions, and to package them with vite-plugin-uni-cloudfunctions.

Do not use this skill for:

• 运营数据写入（新增提示词/分类/图片）— redirect to content-ops.
• CloudBase 环境管理、安全规则、云存储 — redirect to cloudbase skill.
• 微信开发者工具的预览/自动化操作 — redirect to wechatide-skill.

Stop and ask when: 新集合的数据模型 ER 图未经用户确认就要求云端同步；或某个 action 预期高并发/长耗时，需要用户决定是否拆独立云函数。

Input Contract

Required:

• 业务需求：函数名（module 名）、action 列表、每个 action 的输入/输出
• 涉及的 CloudBase 集合与字段

Optional (read when needed):

• references/conventions.md — 完整 13 条规范 + CloudBase 系统字段清单（新建函数或做 review 时必读）
• references/mcp-setup.md — cloudbase MCP 不可用时的配置模板（Claude Code / Cursor / Codex，占位符版）
• assets/function-scaffold.md — 新建云函数时复制的文件骨架模板
• assets/tsconfig.json / assets/tsconfig.app.json / assets/tsconfig.cloudfunctions.json — project references 三件套模板（项目缺少时复制到项目根目录）

Output Contract

Return:

• 变更的文件路径清单
• 类型检查与单测结果（命令 + pass/fail）
• 构建产物验证结果（dist/**/cloudfunctions/<fn>/index.js 是否生成）
• 若新增/变更数据模型：mermaid ER 图（含字段类型与关联）与用户确认记录

新增云函数（一个函数 = 一个业务 module）

1. 读 references/conventions.md，确认分层与命名规则。
2. 若涉及新集合：先用 mermaid erDiagram 画数据模型（注明字段类型、关联关系），给用户确认；字段不得与 CloudBase 系统字段重名（清单见 references）。确认后才可经 cloudbase MCP 同步云端。
   • 若会话中没有可用的 cloudbase MCP 工具：按 references/mcp-setup.md 把对应客户端的 MCP 配置写入项目（Claude Code → .mcp.json，Cursor → .cursor/mcp.json，Codex → .codex/config.toml），环境变量只写占位符，然后提示用户手动填入真实 CLOUDBASE_ENV_ID / CLOUDBASE_API_KEY 并重载 MCP；配置好之前跳过云端同步步骤。
3. 按 assets/function-scaffold.md 创建目录骨架：
   • cloudfunctions/<fn>/：index.ts、package.json、handlers.ts、services.ts、repository.ts（CloudBase 数据访问 + DTO 转换）、model.ts（zod v4 schema）、model.d.ts（纯 TS 类型）、__tests__/、debug/
   • 跨函数复用件放 cloudfunctions/_shared/lib/：runtime.ts（SDK 初始化+入口装配封装）、errors.ts、sort.ts、通用校验件
   • 项目根目录若缺 project references 配置，从 assets 复制三份 tsconfig 模板（tsconfig.json / tsconfig.app.json / tsconfig.cloudfunctions.json）；app 侧必须 exclude 掉 cloudfunctions/
4. 实现顺序：model.ts schema → services.ts 接口+默认实现 → handlers.ts action 分发 → repository.ts 真实实现 → index.ts 经 _shared/lib/runtime.ts 装配导出 main。
5. payload 校验默认 .strict()，非法输入抛 BAD_REQUEST；对接三方 API 等场景可放宽，但要在代码注释说明原因。
6. 每个 action 在 debug/ 下补一个 event JSON 样例，供微信开发者工具本地调试直接粘贴。
7. __tests__/ 注入 mock services 做纯逻辑单测，不依赖真实 CloudBase。

修改既有云函数

1. 先读目标函数全部分层文件，再动手；新增 action 时同步更新 action 枚举、model schema、debug 样例、单测。
2. 不做顺带重构；函数间禁止互相 import，禁止 import cloudfunctions/ 之外的本地文件（插件会强制校验）。

打包与发布（vite-plugin-uni-cloudfunctions）

打包统一使用 npm 包 vite-plugin-uni-cloudfunctions（Vite 插件，peer 依赖 Vite ^5.2.8）：

// vite.config.ts
import { uniCloudFunctions } from 'vite-plugin-uni-cloudfunctions';

export default defineConfig({
  plugins: [uniCloudFunctions({ external: ['wx-server-sdk'] })],
});

• 开发期：UNI_PLATFORM=mp-weixin 下 dev server watcher 增量编译 → dist/dev/mp-weixin/cloudfunctions/
• 生产期：常规小程序构建即可，插件在 writeBundle 编译发布 → dist/build/mp-weixin/cloudfunctions/
• 每个函数输出自包含单文件 index.js + 自己的 package.json；external 只允许 bare package name（默认 ['wx-server-sdk']），external 的依赖必须写进函数级 package.json dependencies
• 禁止手写部署/拷贝脚本；不要绕过插件直接往 dist 写产物

Validation

# 云函数独立类型检查
pnpm exec tsc -p tsconfig.cloudfunctions.json --noEmit

# 单测
pnpm vitest run cloudfunctions

# 构建产物验证
pnpm build:mp-weixin
test -f dist/build/mp-weixin/cloudfunctions/<fn>/index.js && echo OK

全部通过才算完成；报告中附命令与结果。数据模型变更需附用户已确认 ER 图的记录。

Common Mistakes

• 手动给写操作传 _openid —— SDK 自动管理，手动传会直接报错。
• 自定义字段撞 CloudBase 系统字段（createdAt/updatedAt/owner 等，全表见 references）。
• 在 _shared 里放函数私有的 action 枚举/payload schema —— 函数专属 schema 留在函数内 model.ts，_shared 只放真正通用件。
• 云函数持有跨请求内存状态 —— 必须无状态、幂等；限流/去重走审计集合。
• 新增 action 忘了同步 debug JSON 样例和单测。