wx-cloudfunctions

用途

该技能用于在 uni-app 项目中开发 TypeScript 微信云函数，遵循项目的分层模块约定，并使用 vite-plugin-uni-cloudfunctions 进行打包。适用于创建、修改、审查或打包微信云函数，包括新增云函数、修改云函数、添加 action、处理云函数分层与目录结构、编写 zod 校验等。

不适用场景：

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

遇到以下情况应停下询问用户：新集合的数据模型 ER 图未经用户确认就要求云端同步；或某个 action 预期高并发/长耗时，需要用户决定是否拆独立云函数。

输入契约

必需项：

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

可选项（按需读取）：

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 三件套模板（项目缺少时复制到项目根目录）

输出契约

需返回：

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

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

读 references/conventions.md，确认分层与命名规则。
若涉及新集合：先用 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；配置好之前跳过云端同步步骤。
按 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/
实现顺序：model.ts schema → services.ts 接口+默认实现 → handlers.ts action 分发 → repository.ts 真实实现 → index.ts 经 _shared/lib/runtime.ts 装配导出 main。
payload 校验默认 .strict()，非法输入抛 BAD_REQUEST；对接三方 API 等场景可放宽，但要在代码注释说明原因。
每个 action 在 debug/ 下补一个 event JSON 样例，供微信开发者工具本地调试直接粘贴。
tests/ 注入 mock services 做纯逻辑单测，不依赖真实 CloudBase。

修改既有云函数

先读目标函数全部分层文件，再动手；新增 action 时同步更新 action 枚举、model schema、debug 样例、单测。
不做顺带重构；函数间禁止互相 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 写产物

验证

# 云函数独立类型检查
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 图的记录。

常见错误

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