CLI 工具设计优化建议 - 提升用户体验 · Issue #36

humingx/tcb-user-cli

Public

WeChat Login

Code Issues

Pull requests Events Packages Insights

CLI 工具设计优化建议 - 提升用户体验#36

Open

胡明

created 4 days ago

Edit

胡明

概述

通过实际使用发现 CLI 工具存在一些设计上的不足，影响了用户体验和工具的易用性。本 issue 汇总这些问题并提出改进建议。

问题 1：参数设计不合理

现状

--app-id 是必需参数，但文档的「快速开始」中没有提及
所有示例命令都没有包含 --app-id
用户首次使用必然失败

影响

降低工具的易用性
增加用户的学习成本
给人"半成品"的印象

改进建议

方案 A：自动提取（推荐）

CLI 自动从 JWT token payload 中提取 project_id
Token 中已包含此信息，无需用户手动传入

方案 B：完善文档

在所有示例命令中添加 --app-id
在「快速开始」中醒目标注此参数为必需
说明如何在控制台获取 App ID

问题 2：错误提示不够友好

现状

当缺少 --app-id 时，只显示：

Appid missing

改进建议

改进后的错误提示：

Error: Appid missing

The --app-id parameter is required for this command.

Usage:
  tcb-user collection query <collection> --app-id <your-app-id> [options]

Example:
  tcb-user collection query todos --app-id 1328860866 --env-id test-xxx --region ap-shanghai

How to find your App ID:
  1. Visit CloudBase Console: https://console.cloud.tencent.com/tcb
  2. Select your project
  3. Find App ID in project settings

优点

用户立即知道问题所在
提供了解决方案和示例
减少用户查文档的次数

实施优先级

P0 - 立即修复
- 改进 "Appid missing" 错误提示
- 在文档中补充 --app-id 说明
P1 - 短期优化
- 实现从 token 自动提取 app-id
- 添加配置文件支持
P2 - 长期改进
- 实现参数自动补全
- 添加交互式模式

参考

优秀 CLI 工具的设计原则：

The Twelve-Factor CLI Apps
Command Line Interface Guidelines

希望这些改进能够提升 tcb-user-cli 的用户体验！

胡明

Creator

分析与建议

非常赞同这个 Issue 提出的问题！以下是我的分析：

✅ 合理的部分

1. 错误提示改进（P0 - 必须立即做）

当前的 "Appid missing" 确实太简陋了。建议改为：

❌ Error: App ID is required

The --app-id parameter is missing.

📖 How to find your App ID:
  1. Visit CloudBase Console: https://console.cloud.tencent.com/tcb
  2. Select your environment
  3. Go to "Static Website Hosting" or "HTTP Service"
  4. Find the default domain (format: https://{env-id}-{app-id}.tcloudbaseapp.com/)
  5. Extract the number after "-" (e.g., 1328860866)

📝 Example:
  tcb-user collection query todos \
    --app-id 1328860866 \
    --env-id test-xxx \
    --region ap-shanghai

For more help, run: tcb-user collection query --help

2. 完善文档（P0 - 必须立即做）

在所有示例命令中添加 --app-id
在 Quick Start 中明确说明如何获取 App ID
添加 FAQ 条目专门解释这个问题

⚠️ 需要修正的部分

"从 token 自动提取 app-id"（P1）

根据我在 Issue #34 中的深入分析（已经过实际验证）：

❌ Token 中并不包含 app_id 字段（这是我最初的错误假设）
❌ 普通用户（C端）没有 API 可以自动查询 App ID
✅ 用户只能手动从静态托管默认域名中提取

详见：

Issue #34 的最终评论：#34
PR #37（添加 FAQ 说明）：#37

💡 修正后的实施优先级

P0 - 立即修复

✅ 改进 "Appid missing" 错误提示（添加详细说明 + 示例 + 获取方法）
✅ 在文档 Quick Start 中补充 --app-id 说明
✅ 添加 FAQ：如何从默认域名提取 App ID

P1 - 短期优化

✅ 添加配置文件支持（~/.tcb-user/config.json），允许用户保存默认 app-id
✅ 添加交互式提示：当缺少 --app-id 时，询问用户是否输入并保存到配置文件
❌ ~~实现从 token 自动提取~~（不可行，token 中没有这个字段）

P2 - 长期改进

✅ 实现参数自动补全（基于配置文件）
✅ 添加交互式模式
⭐ 根本解决方案：推动 CloudBase 后端接口改造，让 SDK/CLI 只传 env-id 和 token，后端自动解析 app-id（这才是正确的设计）

🎯 建议的实现顺序

阶段 1：快速修复（1-2 天）

改进错误提示（含详细说明和示例）
更新 README 的 Quick Start（添加 --app-id 说明）
合并 PR #37（添加 FAQ）

阶段 2：体验优化（3-5 天）

实现配置文件支持
添加交互式 --app-id 提示
实现参数自动补全

阶段 3：根本解决（需要平台团队配合）

向 CloudBase 团队提交接口改造需求
后端接口改为只接受 env-id + token
彻底隐藏 app-id

📚 参考资料

更新：方案修正

感谢指正！我重新理解了问题。

🎯 唯一可行的方案

用户无法登录 CloudBase Console（C 端用户工具），所以：

✅ 从网站默认域名中自动提取 App ID
✅ 用户不需要每次都传 --app-id

💡 实现方案

首次使用时自动提取并保存：

# 首次登录
tcb-user login --env-id test-xxx
# CLI 自动：调用 API → 获取默认域名 → 提取 App ID → 保存到 ~/.tcb-user/config.json

# 后续命令无需 --app-id
tcb-user collection query todos --env-id test-xxx
tcb-user storage upload file.txt --env-id test-xxx

🔧 核心逻辑

async function getAppId(envId) {
  // 1. 先从配置文件读取
  const config = readConfig();
  if (config.appId) return config.appId;
  
  // 2. 调用 API 获取环境信息
  const envInfo = await getEnvInfo(envId);
  
  // 3. 从域名提取: https://test-xxx-1328860866.tcloudbaseapp.com/
  const appId = envInfo.domain.match(/-(d+).tcloudbaseapp.com/)[1];
  
  // 4. 保存到配置文件
  saveConfig({ appId });
  return appId;
}

📝 用户体验对比

❌ 当前（每次都传）

tcb-user collection query todos --app-id 1328860866 --env-id test-xxx

✅ 改进后（自动提取）

tcb-user collection query todos --env-id test-xxx

🎯 实施优先级

P0 - 立即实现

从域名自动提取 App ID
首次使用时保存到配置文件
所有命令改为可选参数
改进错误提示

P1 - 补充优化
5. 更新文档（移除 --app-id）
6. 添加 tcb-user config show 命令

我会立即提交 PR 实现这个方案。

胡明

feat: auto-extract and save App ID from environment

ac59c8eb

胡明

referenced ISSUE

#38 feat: auto-extract and save App ID from environment

Merged

胡明

feat: auto-save App ID to config file

91e219fc

胡明

Creator

更新：已实现自动保存方案

感谢指正！已经实现了更实际的解决方案。

✅ 最终方案：自动保存机制

用户体验：

首次使用时传入 --app-id（CLI 自动保存到配置文件）
后续命令自动使用已保存的值（无需再传）

📝 使用示例

改进前（每次都传）：

tcb-user collection query todos --app-id 1328860866 --env-id test-xxx
tcb-user storage upload file.txt cloud://file.txt --app-id 1328860866 --env-id test-xxx

改进后（只需传一次）：

# 首次使用时传入（自动保存）
tcb-user collection query todos --app-id 1328860866 --env-id test-xxx

# 后续命令自动使用（无需再传）
tcb-user storage upload file.txt cloud://file.txt --env-id test-xxx
tcb-user functions call myFunc --env-id test-xxx