@cloudbase/cli 2.11.5 → 2.11.7

package/specs/cli-install-upgrade/requirements.md

@@ -0,0 +1,315 @@
+# 需求文档：CloudBase CLI 安装脚本升级（调研阶段）
+
+## 介绍
+为解决通过 npm 全局安装 `@cloudbase/cli` 安装慢、受 Node 版本影响、失败率偏高等问题，参考 Cursor CLI 的“预打包 + curl|bash 一键安装”方式，提供跨平台、高成功率、可原子升级与回滚的安装体验，并同时暴露 `cloudbase`、`tcb`、`cloudbase-mcp` 三个可执行入口。
+
+## 参考背景信息（原始输入摘录）
+- 现状：`npm i -g @cloudbase/cli` 容易出现问题
+  - 安装速度缓慢、依赖 npm
+  - Node 版本可能过低导致失败
+- 目标：提升安装成功率与速度
+- 参考 Cursor CLI 的安装方式：`curl https://cursor.com/install -fsS | bash`
+- 安装脚本示例（来自参考）：
+
+```bash
+#!/usr/bin/env bash
+
+# Color definitions
+CYAN='\033[0;36m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+PURPLE='\033[0;35m'
+RED='\033[0;31m'
+BOLD='\033[1m'
+DIM='\033[2m'
+NC='\033[0m' # No Color
+
+# Fancy header
+echo ""
+echo -e "${BOLD}Cursor Agent Installer${NC}"
+echo ""
+
+# Function to print steps with style
+print_step() {
+    echo -e "${BLUE}▸${NC} ${1}"
+}
+
+# Function to print success
+print_success() {
+    # Move cursor up one line and clear it
+    echo -ne "\033[1A\033[2K"
+    echo -e "${GREEN}✓${NC} ${1}"
+}
+
+# Function to print error
+print_error() {
+    echo -e "${RED}✗${NC} ${1}"
+}
+
+# Detect OS and Architecture
+print_step "Detecting system architecture..."
+
+# Detect OS
+OS="$(uname -s)"
+case "${OS}" in
+    Linux*)     OS="linux";;
+    Darwin*)    OS="darwin";;
+    *)
+        print_error "Unsupported operating system: ${OS}"
+        exit 1
+        ;;
+esac
+
+# Detect Architecture
+ARCH="$(uname -m)"
+case "${ARCH}" in
+    x86_64|amd64)  ARCH="x64";;
+    arm64|aarch64) ARCH="arm64";;
+    *)
+        print_error "Unsupported architecture: ${ARCH}"
+        exit 1
+        ;;
+esac
+
+print_success "Detected ${OS}/${ARCH}"
+
+# Installation steps
+print_step "Creating installation directory..."
+# Create temporary directory for atomic download inside versions folder
+TEMP_EXTRACT_DIR="$HOME/.local/share/cursor-agent/versions/.tmp-2025.08.09-d8191f3-$(date +%s)"
+mkdir -p "${TEMP_EXTRACT_DIR}"
+
+print_success "Directory created"
+
+
+print_step "Downloading Cursor Agent package..."
+DOWNLOAD_URL="https://downloads.cursor.com/lab/2025.08.09-d8191f3/${OS}/${ARCH}/agent-cli-package.tar.gz"
+echo -e "${DIM}  Download URL: ${DOWNLOAD_URL}${NC}"
+
+# Cleanup function
+cleanup() {
+    rm -rf "${TEMP_EXTRACT_DIR}"
+}
+trap cleanup EXIT
+
+# Download with progress bar and better error handling
+if curl -fSL --progress-bar "${DOWNLOAD_URL}" \
+  | tar --strip-components=1 -xzf - -C "${TEMP_EXTRACT_DIR}"; then
+  echo -ne "\033[1A\033[2K"
+  echo -ne "\033[1A\033[2K"
+  echo -ne "\033[1A\033[2K"
+  print_success "Package downloaded and extracted"
+else
+    print_error "Download failed. Please check your internet connection and try again."
+    print_error "If the problem persists, the package might not be available for ${OS}/${ARCH}."
+    cleanup
+    exit 1
+fi
+
+print_step "Finalizing installation..."
+# Atomically move from temp to final destination
+FINAL_DIR="$HOME/.local/share/cursor-agent/versions/2025.08.09-d8191f3"
+rm -rf "${FINAL_DIR}"
+if mv "${TEMP_EXTRACT_DIR}" "${FINAL_DIR}"; then
+  print_success "Package installed successfully"
+else
+    print_error "Failed to install package. Please check permissions."
+    cleanup
+    exit 1
+fi
+
+
+print_step "Creating bin directory..."
+mkdir -p ~/.local/bin
+print_success "Bin directory ready"
+
+
+print_step "Creating symlink to cursor-agent executable..."
+# Remove any existing symlink or file
+rm -f ~/.local/bin/cursor-agent
+# Create symlink to the cursor-agent executable
+ln -s ~/.local/share/cursor-agent/versions/2025.08.09-d8191f3/cursor-agent ~/.local/bin/cursor-agent
+print_success "Symlink created"
+
+# Success message
+echo ""
+echo -e "${BOLD}${GREEN}✨ Installation Complete! ${NC}"
+echo ""
+echo ""
+
+# Determine configured shells
+CURRENT_SHELL="$(basename $SHELL)"
+SHOW_BASH=false
+SHOW_ZSH=false
+SHOW_FISH=false
+
+case "${CURRENT_SHELL}" in
+  bash) SHOW_BASH=true ;;
+  zsh) SHOW_ZSH=true ;;
+  fish) SHOW_FISH=true ;;
+cesac
+
+# Also consider presence of config files as configured
+if [ -f "$HOME/.bashrc" ] || [ -f "$HOME/.bash_profile" ]; then SHOW_BASH=true; fi
+if [ -f "$HOME/.zshrc" ]; then SHOW_ZSH=true; fi
+if [ -f "$HOME/.config/fish/config.fish" ]; then SHOW_FISH=true; fi
+
+# Next steps with style
+echo -e "${BOLD}Next Steps${NC}"
+echo ""
+echo -e "${BOLD}1.${NC} Add ~/.local/bin to your PATH:"
+
+if [ "${SHOW_BASH}" = true ]; then
+  echo -e "   ${DIM}For bash:${NC}"
+  echo -e "   ${BOLD}${BLUE}echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc${NC}"
+  echo -e "   ${BOLD}${BLUE}source ~/.bashrc${NC}"
+  echo ""
+fi
+
+if [ "${SHOW_ZSH}" = true ]; then
+  echo -e "   ${DIM}For zsh:${NC}"
+  echo -e "   ${BOLD}${BLUE}echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc${NC}"
+  echo -e "   ${BOLD}${BLUE}source ~/.zshrc${NC}"
+  echo ""
+fi
+
+if [ "${SHOW_FISH}" = true ]; then
+  echo -e "   ${DIM}For fish:${NC}"
+  echo -e "   ${BOLD}${BLUE}mkdir -p $HOME/.config/fish${NC}"
+  echo -e "   ${BOLD}${BLUE}echo 'fish_add_path $HOME/.local/bin' >> $HOME/.config/fish/config.fish${NC}"
+  echo -e "   ${BOLD}${BLUE}source $HOME/.config/fish/config.fish${NC}"
+  echo ""
+fi
+
+# Fallback if no known shells detected/configured
+if [ "${SHOW_BASH}" != true ] && [ "${SHOW_ZSH}" != true ] && [ "${SHOW_FISH}" != true ]; then
+  echo -e "   ${DIM}Add to PATH manually:${NC}"
+  echo -e "   ${BOLD}${BLUE}export PATH=\"$HOME/.local/bin:$PATH\"${NC}"
+  echo ""
+fi
+
+echo -e "${BOLD}2.${NC} Start using Cursor Agent:"
+echo -e "   ${BOLD}cursor-agent${NC}"
+echo ""
+echo ""
+echo -e "${BOLD}${CYAN}Happy coding! 🚀${NC}"
+echo "%"
+```
+
+- 示例包地址：`https://downloads.cursor.com/lab/2025.08.09-d8191f3/darwin/arm64/agent-cli-package.tar.gz`
+- 示例包内容：
+
+```bash
+/Users/bookerzhao/Downloads/dist-package
+├── build
+|  └── node_sqlite3.node
+├── cursor-agent
+├── index.js
+├── node
+├── package.json
+└── rg
+
+directory: 1 file: 6
+
+ignored
+```
+
+- 观察与结论：
+  - 包内置 `cursor-agent`、`node`（Node 22）、`index.js` 与必要原生依赖，安装无需系统 Node/npm。
+  - 价值：提升安装成功率与速度；bundle 后方便被 VS Code 扩展等调用。
+
+- 方案参考要点（来自原始输入）：
+  1. CLI bundle 参考：`https://github.com/TencentCloudBase/CloudBase-AI-ToolKit/blob/main/mcp/webpack/cli.config.cjs`
+  2. 内置并暴露多个 bin：`cloudbase`、`tcb`、`cloudbase-mcp`
+  3. 与本地 npm 安装命令冲突的处理策略
+  4. 升级策略（含自更新/回滚）
+  5. 是否需要打包多个 tar 包的评估（按 OS/ARCH 拆分）
+
+## 需求（EARS）
+
+### 1. 一键安装脚本（更新：含原生 Windows）
+- 用户故事：作为新用户，我希望通过一条命令完成安装，无需预装 Node 或 npm。
+- 验收（EARS）：
+  - While 在 macOS/Linux，when 执行 `curl -fsSL https://<domain>/install | bash`，the 安装器 shall 检测 OS/ARCH，创建 `~/.local/share/cloudbase-cli/versions/<version>`，解压包，维护 `current` 链接，创建到 `~/.local/bin` 的 `cloudbase`/`tcb`/`cloudbase-mcp` 符号链接，并输出 PATH 配置指引；无需 sudo。
+  - While 在原生 Windows（PowerShell 7+/5.1），when 执行 `irm https://<domain>/install.ps1 | iex`（或下载后执行），the 安装器 shall 检测架构，创建 `%LOCALAPPDATA%\\cloudbase-cli\\versions\\<version>`，解压 `.zip` 包，更新 `current.txt` 指向版本，生成 `%LOCALAPPDATA%\\cloudbase-cli\\bin\\{cloudbase,tcb,cloudbase-mcp}.cmd` 并提示将该 bin 目录加入 PATH。
+
+### 2. 预置运行时（内置 Node）
+- 用户故事：我不希望因本地 Node 版本不满足而失败。
+- 验收：When 运行任一入口，the 运行时 shall 使用随包分发的 Node（建议 Node 22 LTS），不依赖系统 Node。
+
+### 3. 多入口暴露与行为一致
+- 用户故事：我需要继续使用 `cloudbase`、`tcb`，并使用 `cloudbase-mcp`。
+- 验收：When 完成安装，the 系统 shall 暴露三命令，均可独立执行 `-v`、`-h`；其中 `cloudbase`/`tcb` 通过 `cli.js` 启动，`cloudbase-mcp` 通过包内 `mcp.js`（复制自 `@cloudbase/cloudbase-mcp/dist/cli.cjs`）启动，行为与 npm 安装一致。
+
+### 4. 包分发与结构（更新：含 Windows .zip 与安装器）
+- 用户故事：作为发布者，我需要稳定分发与清晰目录，支持 CDN。
+- 验收：When 发布 `<version>`，the 服务端 shall 提供 `{darwin,linux}/{x64,arm64}` 的 `.tar.gz{,.sha256}` 与 `{windows}/{x64,arm64}` 的 `.zip{,.sha256}`；包内含 `node`（或 `node.exe`）、`bin/*`、`cli.js`、`mcp.js`、`manifest.json`；线上采用版本化目录：
+  - `/<version>/{darwin,linux}/{x64,arm64}/cloudbase-cli-<version>.tar.gz{,.sha256}`
+  - `/<version>/windows/{x64,arm64}/cloudbase-cli-<version>.zip{,.sha256}`
+  - 根目录提供 `install/install.sh`（别名 `/install`）与 `install/install.ps1`（别名 `/install.ps1`）、`stable.txt`、`beta.txt`。
+
+### 5. 自更新与回滚（原子）
+- 用户故事：我希望一键升级且可回滚。
+- 验收：When 执行 `cloudbase self-update` 或重跑安装脚本，the 安装器 shall 下载至临时目录并原子切换 `versions/<version>` 与符号链接；至少保留 1 个上版本用于 `--rollback`；失败不影响当前可用版本。
+
+### 6. 与 npm 全局安装冲突处理
+- 用户故事：历史用户可能已通过 npm 安装，避免冲突。
+- 验收：When 检测到 PATH 中存在同名命令，the 安装器 shall 提示 PATH 优先级调整与检测命令；默认不覆盖，仅创建 `~/.local/bin` 链接并提示置前。
+
+### 7. 性能目标与网络备选
+- 用户故事：在一般网络环境也能快速安装。
+- 验收：While 中国大陆网络，when 下载同版本包，the P99 安装耗时 ≤ 20s（100Mbps，包体≤80MB）
+
+
+### 8. 安全与完整性
+- 用户故事：我需要确认下载可信。
+- 验收：When 执行安装，the 安装器 shall 强制 HTTPS、校验 `sha256`（或 `minisign`/COS 签名）；脚本最小权限、无 sudo；提供卸载指令（删除 `~/.local/share/cloudbase-cli` 与链接）。
+
+### 9. 兼容性与范围（更新：含原生 Windows）
+- 用户故事：我在常见桌面/服务器上可用。
+- 验收：the 首版 shall 支持 macOS（darwin x64/arm64）与 Linux（glibc x64/arm64）；原生 Windows（x64/arm64）通过 PowerShell 安装器与 `.zip` 产物完成安装；若在 Git Bash/MSYS/Cygwin 下执行 `install.sh`，安装器 shall 直接提示改用 WSL 或使用 PowerShell 安装器。
+
+### 11. Windows 原生安装器（新增）
+- 用户故事：在不使用 WSL 的情况下，我希望用 PowerShell 一键安装/升级/回滚。
+- 验收（EARS）：
+  - When 执行 `irm https://<domain>/install.ps1 | iex`，the 安装器 shall：
+    1) 解析 `CHANNEL`/`VERSION`/`DOWNLOAD_BASE`；
+    2) 下载并校验 `.zip` 与 `.sha256`；
+    3) 解压到 `%LOCALAPPDATA%\\cloudbase-cli\\versions\\<version>`（使用临时目录 + 原子移动）；
+    4) 写入/更新 `%LOCALAPPDATA%\\cloudbase-cli\\current.txt`；
+    5) 生成或更新 `%LOCALAPPDATA%\\cloudbase-cli\\bin\\{cloudbase,tcb,cloudbase-mcp}.cmd`；
+    6) 输出 PATH 提示与卸载说明。
+
+## CDN 上传清单与缓存策略（更新）
+- 上传清单：
+  - `/<version>/{darwin,linux,windows}/{x64,arm64}/cloudbase-cli-<version>.tar.gz{,.sha256}`
+  - `/install/install.sh` 与别名 `/install`
+  - `/stable.txt`、`/beta.txt`
+- 忽略：
+  - `/artifacts/**`、`/unpacked/**`（仅本地/CI 使用）
+  - 本地构建完成后通过清理脚本仅保留版本化目录与安装脚本（prune）
+- 缓存策略建议：
+  - 版本化包与 `.sha256`：长缓存（immutable）
+  - 安装脚本 `/install`：中等缓存，可刷新
+  - `stable.txt`/`beta.txt`：短缓存（5~15 分钟）
+
+### 10. 观测与可运维
+- 用户故事：发布者需要感知安装质量。
+- 验收：When 安装完成或失败，the 安装器 shall 在用户允许前提下匿名上报版本、OS/ARCH、结果与耗时（默认关闭，明示开启）。
+
+## 非目标
+- 不在首版自动修改 PATH（仅提示）。
+- 不强制移除/覆盖 npm 全局安装。
+
+## 约束与依赖
+- 分发域名与 CDN（建议 COS+CDN，国内外双域与回源）。
+- Node 运行时版本：建议 Node 22 LTS；若含原生依赖需按 OS/ARCH 预编译。
+- Bundle 方案：参考 CloudBase-AI-ToolKit `mcp/webpack/cli.config.cjs`；选择 `webpack` 单文件，以稳定优先；必要时随包内置额外二进制。
+
+## 开放问题（待确认）
+1. 分发域名与镜像策略（是否提供国内镜像域）。
+2. 运行时版本（Node 20 vs 22）与许可证合规说明。
+3. 包体上限与更新频率；是否拆分 runtime 层与 app 层以减少增量。
+4. `cloudbase-mcp` 的暴露方式：多入口单包 vs 独立启动脚本。
+5. 自更新渠道：稳定/beta 双通道与命令设计（如 `--channel beta`）。

package/specs/cli-install-upgrade/tasks.md

@@ -0,0 +1,120 @@
+# 实施计划（仅规划，不实施）
+
+- [ ] 0. 基线与对齐
+  - 对齐分发域名与镜像策略（国内/海外域）
+  - 锁定 Node 运行时版本（建议 22）与许可证合规
+  - 版本与通道策略（stable/beta），版本保留数（默认 2）
+  - _需求: 约束/开放问题
+
+- [x] 1. Bundle 架构落地（webpack 单文件）
+  - 建立 webpack 配置并产出 `dist/standalone/cli.js`
+  - 主 CLI 入口为 `cli.js`；`cloudbase-mcp` 通过复制 `@cloudbase/cloudbase-mcp/dist/cli.cjs` 为 `mcp.js`
+  - Ignore 可选/重型依赖（低码链路、dev server 等）；externals 标记原生/可选模块
+  - _需求: 2,3
+
+- [x] 2. 启动脚本与多入口
+  - 包内 `bin/cloudbase`、`bin/tcb`：`./node ./cli.js "$@"`；`bin/cloudbase-mcp`：`./node ./mcp.js "$@"`
+  - 启动器增强：支持从符号链接调用时解析真实路径
+  - _需求: 1,3
+
+- [x] 3. 安装脚本（curl|bash）
+  - OS/ARCH 探测、目录与临时目录创建、下载、sha256 校验
+  - 解压（strip-components=1）、原子 `mv` 切换版本目录
+  - 维护 `current` 链接；`~/.local/bin/*` 指向 `current/bin/*`
+  - 创建 `~/.local/bin` 符号链接与 PATH 提示（不自动改）
+  - Windows 适配：Git Bash/MSYS/Cygwin 下提示改用 WSL 并退出；WSL 下按 Linux 流程
+  - _需求: 1,8,9
+
+- [x] 4. 自更新与回滚
+  - `cloudbase self-update [--channel beta]`、`--rollback`
+  - manifest 查询、下载校验、原子切换、版本保留与清理
+  - _需求: 5
+
+- [ ] 5. 与 npm 全局安装冲突处理
+  - 安装脚本：检测 `command -v`，提示 PATH 优先级与排查命令
+  - 运行时：`cloudbase doctor path`（可选）输出排查建议
+  - _需求: 6
+
+- [x] 6. 分发与清单
+  - 目录规范：`/<version>/{darwin|linux}/{x64|arm64}/cloudbase-cli-<version>.tar.gz{,.sha256}`
+  - 生成 `manifest.json`（包内）与 `.sha256`；根目录提供 `install/install.sh`、`stable.txt`、`beta.txt`
+  - _需求: 4
+
+- [x] 7. CI/CD 构建矩阵（本地脚本）
+  - 构建矩阵：darwin/linux/windows × x64/arm64（共六包）
+  - `build/scripts/fetch-node.sh` 拉取官方 Node（含 windows `.zip` 提取 `node.exe`）；`build/scripts/build-all.sh` 一键清理+构建+打包+收尾清理
+  - 收尾清理：执行 `build/scripts/prune-out.sh`，仅保留 `out/<version>/**`、`out/install/install.sh`（及别名 `/install`）、`stable.txt`、`beta.txt`
+  - 产物上传 COS + CDN 刷新（CI 待接入）
+  - 冒烟脚本：安装 -> 运行 `cloudbase -v` / 静态校验 `cloudbase-mcp` 文件
+  - _需求: 4,7,10
+
+- [ ] 8. 观测（可选，默认关闭）
+  - 安装脚本：尊重 `CLOUDBASE_CLI_REPORT=1` 开关，上报匿名指标
+  - 域名与接口对齐，文档披露与退出机制
+  - _需求: 10
+
+- [ ] 9. 安全与合规
+  - 强制 HTTPS、sha256 校验、最小权限、不使用 sudo
+  - 第三方依赖许可证检查与 NOTICE
+  - _需求: 8
+
+- [ ] 10. 卸载与文档
+  - 卸载脚本/指令：清理版本目录与符号链接
+  - 文档：README 安装/升级/回滚/卸载、WSL 提示（Git Bash 指向 WSL）
+  - _需求: 1,5,9
+
+- [ ] 11. 测试计划
+  - 平台验证：macOS x64/arm64，Linux x64/arm64，WSL/Git Bash
+  - 网络与镜像：国内/海外、断网/重试、校验失败回滚
+  - 冲突与 PATH：同时存在 npm 全局安装的场景
+  - _需求: 1,6,7
+
+- [ ] 12. 里程碑与发布
+  - 内测版本：beta 渠道与灰度用户
+  - 正式发布：稳定域名 + 文档更新 + 退场策略（npm 安装仍保留）
+  - _需求: 全局
+
+## 附录：CDN 上传清单与缓存策略（新增）
+- 上传清单：
+  - `/<version>/{darwin,linux}/{x64,arm64}/cloudbase-cli-<version>.tar.gz{,.sha256}`
+  - `/install/install.sh`
+  - `/stable.txt`、`/beta.txt`
+- 忽略：
+  - `/artifacts/**`、`/unpacked/**`
+- 缓存建议：
+  - 版本化包与 `.sha256`：长缓存（immutable）
+  - `/install`：中等缓存；可设置别名至 `/install/install.sh`
+  - `stable.txt`/`beta.txt`：短缓存（5~15 分钟）
+
+## 新增：Windows 原生支持实施项
+
+- [ ] W1. Windows `.zip` 产物
+  - 更新打包脚本，生成 `/<version>/windows/{x64,arm64}/cloudbase-cli-<version>.zip{,.sha256}`
+  - zip 内包含 `node.exe`、`cli.js`、`mcp.js`、`manifest.json`、`install.ps1`
+  - _需求: 4, 9, 11
+
+- [ ] W2. CDN 清单与 prune 更新
+  - `prune-out.sh` 保留 Windows `.zip` 与 `.sha256`，并生成 `/install.ps1` 别名
+  - 文档与清单同步
+  - _需求: 4
+
+- [ ] W3. `.cmd` 启动器
+  - 生成 `%LOCALAPPDATA%\\cloudbase-cli\\bin\\{cloudbase,tcb,cloudbase-mcp}.cmd`
+  - 内容：定位安装根目录，调用 `node.exe` 执行相应 `cli.js`/`mcp.js`，参数透传
+  - _需求: 3, 11
+
+- [ ] W4. PowerShell 安装器 `install.ps1`
+  - 下载/校验 `.zip`，`Expand-Archive` 解压，原子切换到 `versions/<version>`
+  - 写入 `current.txt`，生成 `.cmd` 启动器，PATH 提示
+  - 支持 `CHANNEL`/`VERSION`/`DOWNLOAD_BASE` 参数
+  - _需求: 1, 5, 11
+
+- [ ] W5. 自更新与回滚（Windows）
+  - `tcb self-update` 在 Windows 上可调用在线 `install.ps1`（或本地 `current/install.ps1`）
+  - `tcb rollback` 读取 `current.txt` 与 `versions` 列表回退
+  - _需求: 5, 11
+
+- [ ] W6. 测试与验证
+  - PowerShell 5.1 / 7+、Windows 10/11、Server 2019/2022
+  - 签名与执行策略（`Set-ExecutionPolicy Bypass -Scope Process`）文档提示
+  - _需求: 10, 11

package/specs/codebuddy-integration/design.md

@@ -0,0 +1,152 @@
+# 技术方案设计
+
+## 架构概述
+
+在 CloudBase CLI 的 ai 命令中集成 Codebuddy Code CLI，采用与现有 AI 工具（如 Claude、Qwen、Codex）相同的架构模式，通过命令路由器和配置管理器来实现统一的 AI 工具管理。
+
+## 技术架构
+
+```mermaid
+graph TD
+    A[tcb ai -a codebuddy] --> B[AICommandRouter]
+    B --> C[executeCodebuddyAgent]
+    C --> D[AIConfigManager]
+    C --> E[CodebuddyExecutor]
+    
+    D --> F[配置文件管理]
+    E --> G[命令执行]
+    E --> H[安装检查]
+    
+    F --> I[~/.codebuddy/settings.json]
+    F --> J[项目级配置]
+    
+    G --> K[codebuddy CLI]
+    H --> L[安装向导]
+```
+
+## 技术选型
+
+### 核心组件
+- **AICommandRouter**: 现有的命令路由器，负责路由到不同的 AI 工具
+- **CodebuddyConfigManager**: Codebuddy 配置管理器（复用现有的 AIConfigManager）
+- **CodebuddyExecutor**: Codebuddy 命令执行器（集成到现有的 executeAgentWithConfig 方法中）
+
+### 配置管理
+- **配置文件格式**: JSON
+- **配置位置**: 
+  - 用户级: `~/.codebuddy/settings.json`
+  - 项目级: `.codebuddy/settings.json`
+- **配置验证**: 使用 Zod 进行配置验证
+- **配置方式**: 主要通过环境变量和命令行参数，配置文件为辅
+
+### 命令执行
+- **执行方式**: 子进程执行 `codebuddy` 命令
+- **参数透传**: 通过 `--` 分隔符透传参数
+- **环境变量**: 支持环境变量配置
+
+## 数据库/接口设计
+
+### 配置结构
+```typescript
+interface CodebuddyConfig {
+  type: 'none' | 'custom';
+  apiKey?: string;
+}
+
+// Codebuddy Code CLI 配置特点：
+// 1. 主要通过环境变量 CODEBUDDY_API_KEY 配置
+// 2. 支持 OAuth 身份验证流程
+// 3. MCP 服务器配置由 Codebuddy CLI 自己管理
+// 4. 通过参数透传实现 MCP 命令管理
+```
+
+### 配置验证 Schema
+```typescript
+const CodebuddyConfigSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('none')
+  }),
+  z.object({
+    type: z.literal('custom'),
+    apiKey: z.string().optional()
+  })
+])
+```
+
+## 实现策略
+
+### 1. 扩展现有架构
+- 在 `src/utils/ai/const.ts` 中添加 Codebuddy 常量定义
+- 在 `src/utils/ai/router.ts` 中添加 Codebuddy 路由逻辑
+- 在 `src/utils/ai/config.ts` 中添加 Codebuddy 配置管理
+
+### 2. 命令执行流程
+1. 检查 Codebuddy CLI 是否已安装
+2. 验证配置有效性
+3. 解析透传参数
+4. 执行 Codebuddy 命令
+5. 处理执行结果
+
+### 3. 配置管理流程
+1. 检查配置文件是否存在
+2. 验证配置格式
+3. 提供配置向导
+4. 保存配置到指定位置
+
+### 4. MCP 服务器管理
+- 通过参数透传实现 MCP 命令管理
+- 支持三种配置作用域
+- 配置文件自动合并
+
+## 测试策略
+
+### 单元测试
+- 配置验证测试
+- 命令解析测试
+- 参数透传测试
+
+### 集成测试
+- 完整命令执行流程测试
+- 配置管理流程测试
+- 错误处理测试
+
+### 端到端测试
+- 用户场景测试
+- 安装向导测试
+- MCP 服务器管理测试
+
+## 安全性
+
+### 配置安全
+- API 密钥加密存储
+- 配置文件权限控制
+- 敏感信息脱敏显示
+
+### 命令执行安全
+- 参数验证和过滤
+- 环境变量安全传递
+- 子进程权限控制
+
+## 部署和发布
+
+### 开发阶段
+1. 实现核心功能
+2. 添加单元测试
+3. 集成测试验证
+
+### 发布阶段
+1. 更新文档
+2. 版本发布
+3. 用户反馈收集
+
+## 兼容性
+
+### 系统兼容性
+- 支持 macOS、Linux、Windows
+- Node.js 18+ 版本要求
+- 与现有 AI 工具共存
+
+### 配置兼容性
+- 向后兼容现有配置
+- 支持配置迁移
+- 配置文件格式统一

package/specs/codebuddy-integration/requirements.md

@@ -0,0 +1,85 @@
+# 需求文档
+
+## 需求背景
+
+### 现状分析
+
+当前 CloudBase CLI 的 `ai` 命令主要集成了 Claude Code 和通义灵码等 AI 编程工具，但缺乏对 Codebuddy Code CLI 的支持。Codebuddy Code CLI 作为一个强大的自主编排编程智能体，具有以下优势：
+
+1. **自主编排能力**：能够根据开发任务自动选择合适的工具和策略
+2. **多语言支持**：支持多种编程语言和框架
+3. **上下文感知**：能够理解项目结构和代码上下文
+4. **MCP 协议支持**：通过 Model Context Protocol 连接外部工具和数据源
+
+### 问题描述
+
+1. **工具分散**：开发者需要分别安装和配置 CloudBase CLI 和 Codebuddy Code CLI，增加了使用复杂度
+2. **配置重复**：两个工具可能存在重复的配置项，如环境变量、认证信息等
+3. **工作流割裂**：在云开发场景中，开发者需要在不同工具间切换，影响开发效率
+4. **学习成本**：开发者需要学习两套不同的命令行接口和配置方式
+
+### 业务价值
+
+1. **提升开发效率**：统一的命令行入口，减少工具切换时间
+2. **降低使用门槛**：简化安装和配置流程，新用户更容易上手
+3. **增强云开发体验**：将 AI 编程能力深度集成到云开发工作流中
+4. **保持工具生态**：通过 MCP 协议，Codebuddy Code CLI 可以连接更多云开发相关的工具和服务
+
+### 目标用户
+
+- **云开发开发者**：使用 CloudBase 进行应用开发的工程师
+- **AI 编程用户**：希望通过 AI 辅助提升编程效率的开发者
+- **DevOps 工程师**：需要自动化部署和运维的运维人员
+- **全栈开发者**：同时进行前端、后端和云服务开发的工程师
+
+## 介绍
+
+在 CloudBase CLI 的 ai 命令中集成 Codebuddy Code CLI，为用户提供统一的 AI 开发工具入口。Codebuddy Code CLI 是一个面向开发者的自主编排的编程智能体，通过命令行界面为开发者提供强大的 AI 编程能力。
+
+## 需求
+
+### 需求 1 - Codebuddy Code CLI 基础集成
+
+**用户故事：** 作为开发者，我希望在 CloudBase CLI 中能够直接启动和使用 Codebuddy Code CLI，这样我就不需要单独安装和配置 Codebuddy Code CLI。
+
+#### 验收标准
+
+1. When 用户运行 `tcb ai -a codebuddy` 时，CloudBase CLI 应当启动 Codebuddy Code CLI 工具。
+2. When Codebuddy Code CLI 未安装时，系统应当提示用户安装并提供安装指导。
+3. When 用户运行 `tcb ai -a codebuddy --setup` 时，系统应当运行 Codebuddy Code CLI 的配置向导。
+4. When 用户运行 `tcb ai -a codebuddy --config` 时，系统应当显示当前的 Codebuddy Code CLI 配置信息。
+5. When 用户运行 `tcb ai -a codebuddy --reset` 时，系统应当重置 Codebuddy Code CLI 的配置。
+
+### 需求 2 - MCP 服务器管理功能
+
+**用户故事：** 作为开发者，我希望能够在 CloudBase CLI 中管理 Codebuddy Code CLI 的 MCP 服务器，这样我就可以方便地连接外部工具和数据源。
+
+#### 验收标准
+
+1. When 用户运行 `tcb ai -a codebuddy -- mcp add <server-name> --env <env-vars> -- <command>` 时，系统应当添加指定的 MCP 服务器。
+2. When 用户运行 `tcb ai -a codebuddy -- mcp list` 时，系统应当显示所有已配置的 MCP 服务器列表。
+3. When 用户运行 `tcb ai -a codebuddy -- mcp get <server-name>` 时，系统应当显示指定 MCP 服务器的详细信息。
+4. When 用户运行 `tcb ai -a codebuddy -- mcp remove <server-name>` 时，系统应当移除指定的 MCP 服务器。
+5. When 用户配置 MCP 服务器时，系统应当支持 Local、Project、User 三种配置作用域。
+
+### 需求 3 - 参数透传和命令执行
+
+**用户故事：** 作为开发者，我希望能够将 CloudBase CLI 的参数透传给 Codebuddy Code CLI，这样我就可以使用 Codebuddy Code CLI 的所有功能。
+
+#### 验收标准
+
+1. When 用户在 `tcb ai -a codebuddy` 后添加 `--` 和参数时，系统应当将这些参数透传给 Codebuddy Code CLI。
+2. When 用户使用 `tcb ai -a codebuddy -- -p "query"` 时，系统应当执行单次查询模式。
+3. When 用户使用 `tcb ai -a codebuddy -- -c` 时，系统应当继续最近的对话。
+4. When 用户使用 `tcb ai -a codebuddy -- -r "session-id" "query"` 时，系统应当恢复特定的会话。
+
+### 需求 4 - 配置管理和验证
+
+**用户故事：** 作为开发者，我希望 CloudBase CLI 能够管理 Codebuddy Code CLI 的配置，并验证配置的有效性。
+
+#### 验收标准
+
+1. When 用户首次使用 Codebuddy Code CLI 时，系统应当检查配置并引导用户完成配置。
+2. When 用户配置 Codebuddy Code CLI 时，系统应当验证配置的有效性。
+3. When 配置无效时，系统应当提供清晰的错误信息和修复建议。
+4. When 用户需要身份验证时，系统应当支持本地开发环境、远程开发环境和无交互环境的认证方式。