Cloudbase Operator

cloudbase-operator

用途

处理与小程序云开发云资源相关的所有操作。

典型任务：

• 列出可用云环境
• 检查已部署云函数
• 查询函数运行状态
• 部署或增量部署云函数
• 查询或修改云数据库集合与文档
• 查询或管理云存储文件

工作流

1. 识别目标 AppID 和目标云环境。
2. 通过运行时上下文解析环境信息。
3. 如果存在多个环境候选，则要求用户明确指定。
4. 选择能够回答当前问题的最窄云工具。
5. 输出结果。

通用约束

• CloudBase MCP 工具（cloud_db_*、cloud_stor_*）必须传 appid 和 env，不再要求项目本地路径。
• env 必须是云开发环境 ID；不明确时先用 cloud_env_list，不要猜测或自动选择候选环境。
• 写操作会触发确认门；用户拒绝或确认超时时不要重试破坏性操作。
• 临时下载链接属于短期签名 URL，可能包含签名、临时密钥和安全 token；只用于当前任务，不要写入代码、配置或长期文档。

工具列表

cloud_env_list — 列出云环境

只读列出当前项目或 AppID 可用的云环境。

wechatide -c <clientName> -t cloud_env_list --project <project>

cloud_fn_list — 列出云函数

只读列出指定云环境中的云函数。

wechatide -c <clientName> -t cloud_fn_list --appid <appid> --env <envId>

cloud_fn_info — 查询云函数信息

只读查询指定云函数的详情和状态。

wechatide -c <clientName> -t cloud_fn_info --appid <appid> --env <envId> --names fnName

cloud_fn_deploy — 部署云函数

按云函数目录路径完整部署单个云函数到指定云环境，属于写操作。一次只允许部署一个云函数目录，目录名即函数名称。

wechatide -c <clientName> -t cloud_fn_deploy --appid <appid> --env <envId> --path <cloudFunctionDir> --remote-npm-install

cloud_fn_inc_deploy — 增量部署云函数

按云函数目录路径增量部署变更文件或目录到指定云环境，属于写操作。固定使用 path + appid 链路，函数目录名即函数名称。

wechatide -c <clientName> -t cloud_fn_inc_deploy --appid <appid> --env <envId> --path <cloudFunctionDir> --file index.js

cloud_db_read_struct — 读取云数据库结构

只读查询 NoSQL 集合与索引结构。

wechatide -c <clientName> -t cloud_db_read_struct --appid <appid> --env <envId> --action listCollections

cloud_db_write_struct — 修改云数据库结构

创建或删除集合，管理集合索引。写操作，必须经过用户确认。

wechatide -c <clientName> -t cloud_db_write_struct \
  --appid <appid> --env <envId> \
  --action createCollection --collection-name <collection>

cloud_db_read_doc — 读取云数据库内容

只读查询集合文档，支持条件、投影、排序和分页。

wechatide -c <clientName> -t cloud_db_read_doc --appid <appid> --env <envId> --collection-name <collection> --query-file ./query.json --projection-file ./projection.json --sort-file ./sort.json --limit 10 --offset 0

JSON 文件用途：

• query.json：查询条件，用来筛选要读取的文档；不传则查询集合内文档。
• projection.json：字段投影，用来控制返回哪些字段。
• sort.json：排序规则，按字段升序或降序排列结果。

query.json 示例：

{ "field": "value" }

projection.json 示例：

{ "field": 1, "_id": 1 }

sort.json 示例：

[{ "key": "createdAt", "direction": -1 }]

cloud_db_write_doc — 修改云数据库内容

插入、更新或删除集合文档。写操作，必须经过用户确认。

# 插入文档：documents 是要插入的文档数组
wechatide -c <clientName> -t cloud_db_write_doc --appid <appid> --env <envId> --action insert --collection-name <collection> --documents-file ./documents.json

# 更新文档：query 负责找文档，update 负责描述怎么改
wechatide -c <clientName> -t cloud_db_write_doc --appid <appid> --env <envId> --action update --collection-name <collection> --query-file ./query.json --update-file ./update.json

# 删除文档：query 负责找要删除的文档
wechatide -c <clientName> -t cloud_db_write_doc --appid <appid> --env <envId> --action delete --collection-name <collection> --query-file ./query.json

JSON 文件用途：

• documents.json：insert 使用，必须是数组，每一项是一条要插入的文档。
• query.json：update / delete 使用，用来筛选要修改或删除的文档。
• update.json：update 使用，只描述更新动作，不写查询条件；推荐使用 $set / $inc / $unset 等操作符。

documents.json 示例：

[{ "field": "value", "count": 1 }]

query.json 示例：

{ "_id": "<docId>" }

update.json 示例：

{ "$set": { "field": "newValue" } }

cloud_query_storage — 读取云存储

只读查询云存储文件列表、文件信息、临时下载链接或文本内容。

wechatide -c <clientName> -t cloud_query_storage --appid <appid> --env <envId> --action list --cloud-path <cloudPath>

返回提醒：

• action=url 返回的是 temporaryUrl，按 expireTime 过期，不是永久公开地址。
• 返回结果不暴露 publicUrl 和 note。

cloud_manage_storage — 修改云存储

上传、下载或删除云存储文件。upload / delete 是写操作，必须经过用户确认；download 不触发确认。

wechatide -c <clientName> -t cloud_manage_storage --appid <appid> --env <envId> --action upload --cloud-path <cloudPath> --local-path <localPath>

返回提醒：

• upload 成功后可能返回 temporaryUrl、expireTime 和 storageCdnDomain。
• 返回结果不暴露 publicUrl 和 note。
• 删除目录前要明确 cloudPath 范围；不要用空路径或过宽前缀做删除。

常见目标到工具

选择提醒

• 如果环境名还不明确，先做 cloud_env_list
• 如果只是想确认状态，优先函数只读查询，不要直接部署
• 部署云函数固定使用 appid + path，明确传入云函数目录的本地绝对路径
• 增量部署云函数固定使用 appid + path + file；file 必须相对云函数目录
• 云数据库工具必须显式传 appid 和 env；先用 cloud_env_list 获取环境 ID
• 云数据库写操作会触发确认；更新文档时优先使用 $set / $inc / $unset 等操作符
• 云存储工具必须显式传 appid 和 env；先用 cloud_env_list 获取环境 ID
• 云存储 upload/delete 会触发确认；delete 还需传 force=true
• cloud_query_storage 的 action=url 和 cloud_manage_storage 的 upload 返回临时签名链接，不可当作永久公开 URL
• 云存储返回结果不暴露 publicUrl 和 note；不要基于这两个字段编写后续流程

云数据库工具

• cloud_db_read_struct：读取集合、集合详情、索引列表。
• cloud_db_write_struct：创建 / 删除集合、添加 / 删除索引（写操作，需用户确认）。
• cloud_db_read_doc：查询集合文档，支持条件、投影、排序、分页。
• cloud_db_write_doc：插入、更新、删除文档（写操作，需用户确认）。

云存储工具

• cloud_query_storage：列出文件、获取文件信息、临时下载链接、读取文本内容。
• cloud_manage_storage：上传、下载、删除云存储文件；upload/delete 需用户确认，delete 还需 force=true。

使用边界

• 当存在多个候选环境时，绝不自动选择其中一个
• 部署云函数固定使用 appid + path 组合
• 云数据库写操作必须经过用户确认
• 云存储 upload/delete 必须经过用户确认
• 云存储 delete 必须明确目标路径；目录删除要传 --is-directory 并确认范围
• 当结果是部分成功或混合结果时，应保留真实返回结构

备注

• 如果需要在微信小程序中使用 FiledId 代表云存储资源，可按 cloud://<envid>.<bucketid>/xxx/ 拼接 FileId，其中 xxx/ 是资源路径。