---

微信云开发（TCB）生态目前存在一个断层：AI Agent 想操作云开发应用时——没有入口。

交互方式	适合人类	适合 Agent	问题
微信开发者工具	✅	❌	GUI 操作，Agent 无法使用
TCB 控制台	✅	❌	纯 Web GUI，无 API 适配
tcb cli（官方 CLI）	⚠️	⚠️	面向开发者运维，非客户端用户视角
js-sdk / 客户端 SDK	✅	❌	运行时 SDK，非 CLI，Agent 难以直接调用

tcb-user-cli 为 AI Agent 打开一扇门——Agent 以独立身份或用户授权后的身份操作云开发应用，受安全规则约束，和真实用户一样。

💡 一句话总结：Agent 拥有自己的身份，或经用户授权后代表用户操作，始终受安全规则约束。

npm install -g tcb-user-cli

要求 Node.js 18+

安装完成后，验证安装是否成功：

tcb-user --version   # 查看版本号
tcb-user --help      # 查看帮助信息

💡 提示： 每个命令都需要 --env-id，你也可以设置环境变量 TCB_ENV_ID 来避免重复输入：

export TCB_ENV_ID=your-env-id

设置后所有命令将自动使用该值，无需再传 --env-id。详见 配置管理。

1️⃣ 登录

# 匿名登录（Agent 独立身份首选）
tcb-user auth login --anonymous --env-id your-env-id

# 或直接传入已有 token
tcb-user auth login --access-token <your-access-token> --refresh-token <your-refresh-token> --env-id your-env-id

2️⃣ 操作云数据库

# 查询记录（将 <collection> 替换为你的集合名）
tcb-user collection query <collection> --env-id your-env-id

# 新增记录
tcb-user collection add <collection> --env-id your-env-id --data '{"title":"示例","done":false}'

3️⃣ 调用云函数

tcb-user function call <function-name> --env-id your-env-id --data '{"type":"email"}'

就是这么简单~ 🎉

tcb-user auth login --anonymous                    # 匿名登录（Agent 独立身份首选）
tcb-user auth login --custom-token <token>         # 自定义登录（以特定用户身份）
tcb-user auth login --access-token <at> --refresh-token <rt>  # 直接传入已有 token
tcb-user auth status --env-id <envId>              # 查看登录状态
tcb-user auth logout --env-id <envId>              # 登出

💡 将 <collection> 替换为你的云数据库集合名称

tcb-user collection list --env-id <envId>                                     # 列出集合
tcb-user collection query <collection> --env-id <envId> [--filter '{...}']     # 查询记录（<collection> 替换为你的集合名）
tcb-user collection add <collection> --env-id <envId> --data '{...}'           # 新增记录
tcb-user collection update <collection> --env-id <envId> --id <id> --data '{..}' # 更新记录
tcb-user collection delete <collection> --env-id <envId> --id <id>             # 删除记录
tcb-user collection count <collection> --env-id <envId> [--filter '{...}']     # 统计记录数

tcb-user function call <name> --env-id <envId> [--data '{...}']             # 调用云函数（<name> 替换为你的函数名）

tcb-user storage upload <local-path> <cloud-path> --env-id <envId>    # 上传文件
tcb-user storage download <file-id> <local-path> --env-id <envId>    # 下载文件
tcb-user storage list [prefix] --env-id <envId>                       # 列出文件
tcb-user storage delete <file-id> --env-id <envId>                    # 删除文件

示例：

# 上传本地文件到云存储
tcb-user storage upload ./image.png cloud://my-env.6d78-my-env/images/avatar.png --env-id my-env

# 列出所有图片文件
tcb-user storage list cloud://my-env.6d78-my-env/images/ --env-id my-env

# 下载文件到本地
tcb-user storage download cloud://my-env.6d78-my-env/images/avatar.png ./downloaded.png --env-id my-env

# 删除文件
tcb-user storage delete cloud://my-env.6d78-my-env/images/avatar.png --env-id my-env

本项目专为 AI Agent 优化，确保 Agent 能顺畅地调用 CLI：

原则	说明
结构化输出	默认 JSON 输出，方便 Agent 解析
明确的退出码	成功=0，参数错误=1，API 错误=2
无交互式	所有参数通过 flags 传入，不弹出交互提示
清晰错误信息	错误信息结构化，包含 code / message / suggestion
幂等设计	重复执行不产生副作用

Agent 在操作云数据库和云函数前，需要知道目标集合名和函数名。获取方式因项目类型而异：

项目类型	Agent 如何获取	说明
Web 项目	阅读前端代码	Agent 直接获取前端源码，分析其中对云函数和集合的调用
小程序	阅读 Skill 文件	开发者生成 Skill（技能描述文件），Agent 阅读 Skill 后调用 CLI
通用	调用 collection list	tcb-user collection list --env-id <envId> 列出所有集合名

💡 Skill 是什么？ Skill 是一种结构化的项目描述文件（skill.yaml），由开发者编写，描述项目中可用的云函数、集合和操作方式。适用于代码不可直接阅读的场景（如小程序）。

Skill 文件示例：

# skill.yaml — 放置在项目根目录
name: my-miniprogram
version: "1.0"
description: 我的微信小程序云开发 Skill
env-id: your-env-id
collections:
  - name: todos
    description: 待办事项集合
  - name: users
    description: 用户信息集合
functions:
  - name: sendEmail
    description: 发送邮件
    params:
      - name: type
        type: string
        required: true

CLI 会自动查找当前目录及父目录中的 skill.yaml，Agent 读取后即可了解项目可用的云资源和操作方式。

成功响应：

{
  "ok": true,
  "data": [
    { "_id": "xxx", "title": "示例", "done": false }
  ]
}

错误响应：

{
  "ok": false,
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Not logged in",
    "suggestion": "Run `tcb-user auth login --anonymous --env-id <envId>` first"
  }
}

┌─────────────────────────────────────────────┐
│              AI Agent / LLM                 │
└──────────────────┬──────────────────────────┘
                   │ CLI 调用
┌──────────────────▼──────────────────────────┐
│         tcb-user-cli (本项目)              │
│                                              │
│  ┌────────────────┐  ┌────────────────────┐  │
│  │   命令解析层     │  │    输出格式化层     │  │
│  │  (Commander.js) │  │   (JSON/Table)    │  │
│  └───────┬────────┘  └────────┬───────────┘  │
│          │                     │              │
│  ┌───────▼─────────────────────▼───────────┐  │
│  │              核心业务层                   │  │
│  │  Auth │ Database │ Function │ Storage   │  │
│  └───────────────────┬────────────────────┘  │
│                      │                        │
│  ┌───────────────────▼────────────────────┐  │
│  │            HTTP 协议层（自研）            │  │
│  │  OAuth2Client │ GatewayClient           │  │
│  │  TokenManager │ FileStorage             │  │
│  └───────────────────┬────────────────────┘  │
│                      │                        │
│  ┌───────────────────▼────────────────────┐  │
│  │         HTTP 请求层 (fetch)              │  │
│  └───────────────────────────────────────┘  │
└──────────────────────────────────────────────┘

📖 详细架构设计请参考 技术方案文档

维度	传统工具（开发者工具）	本项目（用户端工具）
身份视角	开发者（腾讯云账号）	终端用户（微信用户）
技术基础	@cloudbase/node-sdk wx-server-sdk	cloudbase-js-sdk 小程序端 API
认证方式	SecretId / SecretKey	匿名登录 / 自定义登录 / 用户授权
权限范围	管理员权限，绕过安全规则	受安全规则约束，和真实用户一样
典型操作	部署云函数、管理环境、运维操作	新增记录、查询数据、调用云函数
使用场景	开发、部署、运维	终端用户操作、Agent 代用户操作
GUI 对应	微信开发者工具、TCB 控制台	小程序端、Web 端
Agent 友好度	部分支持	完全针对 Agent 优化

💡 简单理解：

• 传统工具 = 开发者在后台管理系统中的操作（如 tcb CLI、微信开发者工具）
• 本项目 = 终端用户在前端应用中的操作（如小程序、Web 应用），但以 CLI 形式提供给 Agent

维度	选型	理由
语言	TypeScript	类型安全，降低协议封装出错率
CLI 框架	Commander.js	轻量成熟，TypeScript 友好
HTTP 客户端	Node.js 内置 fetch	Node 18+ 原生支持，零依赖
Token 存储	JSON 文件	~/.tcb-user/auth/{envId}.json，简单可靠
输出格式	JSON（默认）/ Table	JSON 给 Agent，Table 给人类
打包发布	npm 包 + bin	npm install -g tcb-user-cli

• 认证：匿名登录 / 自定义登录 / Token 直接传入
• 云数据库：query / add / update / delete / count
• 云函数：call（客户端调用）
• 云存储：upload / download / list / delete
• 结构化 JSON 输出 + 错误处理
• 环境配置（env-id）

• 更多登录方式
• 实时数据监听（watch）
• 云存储进阶：批量操作、目录管理

• MCP Server 封装，让更多 Agent 框架原生接入
• CI/CD 集成能力
• 批量操作 & 模板

💡 什么是 MCP？ Model Context Protocol (MCP) 是一种让 AI Agent 与外部工具通信的标准协议。将本 CLI 封装为 MCP Server 后，Claude、Cursor 等 Agent 框架可以直接通过 MCP 协议调用云开发能力，无需手动拼接 CLI 命令。当前 CLI 是 MCP Server 的底层执行引擎，v0.3 将在此之上构建 MCP 适配层。

• 确认 env-id 是否正确
• 确认云环境已开启匿名登录（在微信云开发控制台 → 设置 → 登录方式中开启）
• 检查网络连接是否正常

在微信云开发控制台中，选择你的环境，环境 ID 显示在环境名称下方（格式如 cloud1-xxx 或自定义 ID）。

Agent 使用匿名登录或自定义登录身份，受云开发安全规则约束。你需要在云开发控制台的「安全规则」中为相应集合或云函数设置允许这些身份访问的规则。例如：

{
  "read": true,
  "write": "auth.uid != null"
}

如果你的云环境不在默认的上海区域，请通过 --region 参数指定，支持的区域：ap-shanghai（默认）、ap-guangzhou、ap-beijing。

App ID 是云开发环境的内部标识符（10位纯数字）。CLI 支持自动保存，避免重复输入。

首次使用时指定 --app-id，CLI 会自动保存：

# 首次使用时传入 --app-id
tcb-user collection query todos --app-id 1328860866 --env-id test-xxx
# CLI 自动保存到 ~/.tcb-user/config.json

# 后续命令无需再传（自动使用已保存的）
tcb-user collection query todos --env-id test-xxx
tcb-user storage upload file.txt cloud://file.txt --env-id test-xxx

从应用的静态托管域名中提取：

1. 打开您使用的微信小程序或 Web 应用
2. 查看浏览器地址栏（Web 应用）或页面访问的域名
3. 静态托管域名格式：https://{env-id}-{app-id}.tcloudbaseapp.com/
4. 从域名中提取 - 后面的数字部分（10位纯数字）即为 App ID

示例：

域名：https://my-env-1328860866.tcloudbaseapp.com/
App ID：1328860866

也可以直接编辑配置文件 ~/.tcb-user/config.json：

{
  "envId": "your-env-id",
  "appId": "1328860866",
  "region": "ap-shanghai"
}

域名：https://my-env-1328860866.tcloudbaseapp.com/
App ID：1328860866

# 示例：云存储操作需要 --app-id
tcb-user storage upload ./file.txt cloud://my-env/file.txt \
  --env-id my-env \
  --app-id 1328860866

💡 为什么需要 App ID？ 这是 CloudBase 后端 API 的设计要求。相关改进建议已在 Issue #34 中讨论。

• 确认使用 npm install -g 全局安装
• 检查 npm 全局 bin 目录是否在 PATH 中：npm config get prefix
• 如果使用 nvm，执行 nvm use <version> 后重试

我们欢迎各种形式的贡献！无论是 Bug 报告、功能建议还是代码贡献。

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/your-feature
3. 提交变更：git commit -m 'feat: add some feature'
4. 推送分支：git push origin feature/your-feature
5. 创建 Pull Request

开发前请先阅读 贡献指南 和 技术方案。

• 🐛 提交 Issue
• 💬 讨论区
• 📦 npm 包

MIT © humingx