tcb-user-cli

AI Agent 友好的云开发用户端 CLI

让 Agent 以终端用户身份操作云开发应用

（与开发者工具的管理员身份不同，用户身份受安全规则约束，和真实用户一样）

English · 提交 Issue · 贡献指南

为什么需要它？

微信云开发（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      # 查看帮助信息

3 步上手

💡 提示： 每个命令都需要 --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"}'

就是这么简单~ 🎉

功能概览

认证（Auth）

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>              # 登出

云数据库（Database）

💡 将 <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 '{...}']     # 统计记录数

云函数（Function）

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

云存储（Storage）✅

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

Agent 友好设计

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

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

Agent 如何确定集合名和函数名

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)              │  │
│  └───────────────────────────────────────┘  │
└──────────────────────────────────────────────┘

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

与传统工具的区别

核心差异：开发者身份 vs 终端用户身份

| 维度 | 传统工具（开发者工具） | 本项目（用户端工具） | |---|---|---| | 身份视角 | 开发者（腾讯云账号） | 终端用户（微信用户） | | 技术基础 | @cloudbase/node-sdkwx-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 |

开发路线

v0.1 — MVP ✅

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

v0.2 — 扩展 🚧

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

v0.3 — 进阶 🔮

• [ ] 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 适配层。

常见问题（FAQ）

匿名登录失败怎么办？

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

env-id 在哪里获取？

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

安全规则如何配置才能让 Agent 正常操作？

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

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

不同区域的环境怎么选？

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

安装后命令找不到？

• 确认使用 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 包

License

MIT © humingx