微信小程序 CI 部署、代码审查与交付工作流
完整覆盖从 CI 自动部署 到 代码审查 到 打包发布交付 的全流程。
配置
开始前确认：
- CNB_TOKEN 环境变量已设置
- CNB_API 默认 https://api.cnb.cool
- Node.js >= 18 已安装
部署所需额外凭据（仅在执行部署阶段时需要）
以下凭据由用户提供，不要硬编码，使用时由用户通过安全渠道传入：
| 凭据 | 用途 | 获取方式 |
|---|---|---|
| 微信小程序 AppID | 标识目标小程序 | 微信公众平台后台 |
| 代码上传密钥 (private.key) | miniprogram-ci 上传认证 | 微信公众平台 → 开发管理 → 代码上传密钥 |
| 腾讯云 API SecretId/Key | tcb login 登录 | 腾讯云访问管理控制台 |
> ⚠️ 安全提醒：密钥通过微信等即时通讯工具传输时可能被截断/损坏，务必用 openssl rsa -in private.key -check -noout 验证后再使用。建议通过 SSH/scp 或安全文件传输通道传递密钥。
阶段 0：CI 自动部署（新增）
> 基于实际跑通的工作流提炼，支持一键从 CNB 源码仓库克隆 → 构建 → 上传到微信后台。
0.1 环境准备
提示词参考：
> 「先安装 CloudBase Skills：命令 npx skills add tencentcloudbase/cloudbase-skills -y」
> 「执行 npm i -g @cloudbase/cli 然后执行 tcb login --key --apiKeyId <ID> --apiKey <KEY>」
> 「安装 cnb-openapi 技能：npx skills add https://cnb.cool/cnb/sdk/cnb-openapi-skills.git -y」
自动化步骤：
# 1. 安装 miniprogram-ci（项目级别）
cd <project_dir>
NODE_OPTIONS="--max-old-space-size=384" npm install --no-optional --no-audit miniprogram-ci
# 2. 安装 CloudBase CLI（全局）
npm i -g @cloudbase/cli
tcb login --key --apiKeyId <SECRET_ID> --apiKey <SECRET_KEY>
# 3. 验证上传密钥完整性（关键步骤！）
openssl rsa -in private.key -check -noout
# 输出 "RSA key ok" 才能继续
踩坑备忘：
- 🚨 npm install miniprogram-ci 在低内存服务器（<2GB）容易 OOM kill → 用 NODE_OPTIONS="--max-old-space-size=384" + --no-optional --no-audit
- 🚨 微信传输的 RSA 密钥经常被截断/损坏 → 必须 用 openssl 验证
- 🚨 ENOTEMPTY 错误 → 先 rm -rf node_modules package-lock.json 再重装
0.2 拉取源码
git clone <cnb_repo_url> <project_dir>
# 后续更新：
cd <project_dir> && git pull
0.3 保存上传密钥
将用户提供的 RSA Private Key 写入项目目录（注意权限）：
cat > <project_dir>/private.key << 'KEYEOF'
-----BEGIN RSA PRIVATE KEY-----
<用户提供的完整密钥内容>
-----END RSA PRIVATE KEY-----
KEYEOF
chmod 600 <project_dir>/private.key
0.4 上传代码
创建上传脚本并执行：
const ci = require('miniprogram-ci');
const project = new ci.Project({
appid: '<APPID>', // 从用户输入获取
type: 'miniProgram',
projectPath: '<PROJECT_DIR>', // 项目根目录
privateKeyPath: '<PROJECT_DIR>/private.key',
ignores: ['node_modules/**/*', '.git/**/*'],
});
async function main() {
const result = await ci.upload({
project,
version: '<VERSION>', // 如 "1.0.1"，每次递增
desc: '<DESCRIPTION>', // 描述本次变更内容
setting: {
es6: true,
minify: true,
autoAudits: false,
},
});
console.log('上传成功:', JSON.stringify(result, null, 2));
}
main().catch(err => {
console.error('上传失败:', err.message || err);
process.exit(1);
});
执行：
cd <project_dir> && node upload.js
成功输出示例：
上传成功: {
"subPackageInfo": [{"name": "__FULL__", "size": 101589}],
"pluginInfo": []
}
0.5 设为体验版
> ⚠️ miniprogram-ci 没有设置体验版的 API 接口，需用户在微信后台手动操作。
提示用户：
1. 登录 mp.weixin.qq.com
2. 进入 管理 → 版本管理
3. 在「开发版本」中找到对应版本 → 点击 选为体验版
0.6 后续更新流程（增量）
提示词参考：
> 「源代码有更新」
每次源码更新后，执行：
cd <project_dir>
git pull # 拉取最新代码
# 更新 upload.js 中的 version 和 desc
node upload.js # 重新上传
阶段 0 完整提示词模板
当用户说「部署小程序」或「上传版本」时，Agent 应按以下流程引导：
请提供以下信息：
1. 小程序 AppID
2. 代码上传密钥（RSA Private Key，完整内容）
3. 源码仓库地址（CNB URL）
4. （可选）腾讯云 API 密钥（用于 tcb login）
收到后将自动执行：拉取源码 → 安装依赖 → 验证密钥 → 上传代码 → 提示设体验版
阶段 1：代码审查
- 解压项目：
unzip -o <project.zip> -d /tmp/review-<timestamp> - 审查代码：用子代理扫描 JS 文件，关注：
- 安全问题（SQL注入、未校验输入、硬编码密钥）
- 云函数逻辑缺陷（竞态条件、缺少事务、非原子操作）
- 小程序 API 使用（wx.xxx 调用是否正确、回调处理） - 生成审查报告，按三级分类：
- 🔴 严重（P0）：安全漏洞、数据丢失风险
- 🟡 重要（P1）：逻辑缺陷、异常未处理
- 🔵 建议（P2）：代码规范、性能优化
阶段 2：NPC 评审
> NPC = CNB 云开发工程师，通过 Issue + @mention 触发
2.1 准备代码
- 确保 CNB 仓库已最新：
git push（冲突用pull --rebase） - 记录审查报告中的问题清单
2.2 创建评审 Issue
CNB API 参考：references/cnb-api.md
Issue 模板：references/npc-issue-template.md
关键规则：
- assignees 必须含 ["cnbnn"]
- body 必须包含 @tencent/cloud/cloudbase/community(云开发工程师) 才能触发 NPC
- body 必须包含积分授权声明：本 Issue 授权 NPC 使用发起人剩余积分余额，确保 NPC 有积分可用
- priority: "P0"
- body 包含：审查范围、已知问题列表、修复要求、技术栈说明、积分授权声明
2.3 等待并审查 NPC PR
- 定期用
GET /{repo}/-/pulls?state=open&author=cnbnn检查新 PR - 审查 PR diff，确认修复正确
- 冲突处理：
- pull --rebase 后的普通冲突：手动解决
- add/add 冲突（两边都新增同名文件）：用 NPC 版本（含修复）
- 通过后合并：
PUT /{repo}/-/pulls/{number}/merge
阶段 3：云函数专项评审
3.1 创建云函数 Issue
单独派 Issue 给 NPC，专注云函数评审。评审要点：
- 原子操作：
_.inc()替代 read-modify-write - 事务保护：
db.runTransaction()包裹关键操作 - 输入校验：所有入参类型和范围检查
- 权限校验：
wx.cloud.callContext/ openid 验证 - 错误处理：完整 try-catch，错误信息不泄露内部细节
- 性能：避免 N+1 查询，合理使用索引
- 代码规范：命名、注释、错误码
3.2 审查合并
同阶段 2.3 流程。
阶段 4：打包发布
4.1 打包
运行 scripts/pack.sh：
scripts/pack.sh <source_dir> <output_zip>
自动排除：.git/、node_modules/、miniprogram_npm/
4.2 创建 CNB Release
- 生成改动清单（从 git log 或审查报告提取）
POST /{repo}/-/releases创建 Release，body 含完整改动清单- 上传 zip 附件：
scripts/upload-release-asset.sh
上传流程见 references/cnb-api.md 的附件上传部分。
阶段 5：交付测试
生成测试用例清单，按优先级：
P0 安全验证
- 输入校验绕过测试
- 权限边界测试
- 数据一致性验证
P1 功能回归
- 核心业务流程
- 云函数正常/异常路径
P2 边界异常
- 空值、超长输入
- 并发操作
- 网络异常恢复
输出格式：Markdown 清单，可直接作为测试依据。
注意事项
- NPC 派活 body 必须包含
@tencent/cloud/cloudbase/community(云开发工程师)，仅 assignees 不够 - NPC 派活 body 必须包含积分授权声明：
本 Issue 授权 NPC 使用发起人剩余积分余额，否则 NPC 可能因积分不足无法执行任务 - Claude Code ACP 可能误改非目标文件（wxml/wxss/json），精确修改用子代理
- CNB Release 上传需要
asset_name和size参数 - 各步骤间用
read references/cnb-api.md查询具体 API 调用方式 - miniprogram-ci 不支持设置体验版，需用户在微信后台手动操作
- 低内存服务器 npm install 可能 OOM，需要
NODE_OPTIONS限制
