@tencent-ai/agent-sdk 0.3.98 → 0.3.100

package/cli/dist/web-ui/docs/cn/cli/installation.md

@@ -0,0 +1,291 @@
+# CodeBuddy Code 安装指南
+
+## 安装方式
+
+### 📦 使用包管理器安装
+
+#### Node.js 包管理器
+
+**前置要求:** Node.js 18.20 或更高版本
+
+选择你喜欢的包管理器执行以下命令:
+
+::: code-group
+
+```bash [npm]
+npm install -g @tencent-ai/codebuddy-code
+```
+
+```bash [pnpm]
+pnpm add -g @tencent-ai/codebuddy-code
+```
+
+```bash [yarn]
+yarn global add @tencent-ai/codebuddy-code
+```
+
+```bash [bun]
+bun install -g @tencent-ai/codebuddy-code
+```
+
+:::
+
+#### Homebrew (macOS/Linux)
+
+无需 Node.js，直接安装:
+
+::: code-group
+
+```bash [两步安装]
+# 添加 tap
+brew tap Tencent-CodeBuddy/tap
+
+# 安装工具
+brew install codebuddy-code
+```
+
+```bash [单命令安装]
+brew install Tencent-CodeBuddy/tap/codebuddy-code
+```
+
+```ruby [Brewfile]
+tap "Tencent-CodeBuddy/tap"
+brew "codebuddy-code"
+```
+
+:::
+
+#### 验证安装
+
+安装完成后,运行以下命令验证是否安装成功:
+
+```bash
+codebuddy --version
+```
+
+
+### ⚙️ 使用原生二进制安装（Beta）
+
+> ⚠️ **Beta 测试阶段**
+>
+> 原生二进制安装目前处于 Beta 测试阶段，功能仍在完善中。
+> 如遇到任何问题，请在 [Issues 页面](https://cnb.cool/codebuddy/codebuddy-code/-/issues) 提交问题报告，或联系技术支持（codebuddy@tencent.com）。
+
+#### 特性说明
+
+原生二进制安装相比 npm 版本提供以下特性：
+
+- 单一可执行文件，无需额外依赖
+- 无需 Node.js 运行时
+- 改进的自动更新机制
+
+#### 支持平台
+
+- macOS (Apple Silicon M1/M2/M3 或 Intel x86_64)
+- Linux (arm64 或 x86_64)
+- Windows (x86_64)
+
+#### 从 npm 版本迁移
+
+如果你已经通过 npm 安装了 CodeBuddy Code，可以使用以下命令迁移到原生二进制版本：
+
+```bash
+codebuddy install
+```
+
+#### 全新安装
+
+::: code-group
+
+```bash [macOS / Linux]
+curl -fsSL https://copilot.tencent.com/cli/install.sh | bash
+```
+
+```powershell [Windows]
+irm https://copilot.tencent.com/cli/install.ps1 | iex
+```
+
+:::
+
+#### 验证安装
+
+安装脚本会自动下载最新版本并配置环境变量。安装完成后，运行以下命令验证：
+
+```bash
+codebuddy --version
+```
+
+**如果命令不可用**,请手动将安装路径添加到环境变量 `PATH`:
+
+::: code-group
+
+```bash [macOS / Linux]
+export PATH="$HOME/.local/bin:$PATH"
+
+# 为了永久生效,建议添加到 shell 配置文件:
+# Bash: ~/.bashrc 或 ~/.bash_profile
+# Zsh: ~/.zshrc
+```
+
+```powershell [Windows]
+# 添加以下路径到用户环境变量:
+# %USERPROFILE%\AppData\Local\codebuddy\bin
+```
+
+:::
+
+
+## 📁 配置目录
+
+CodeBuddy Code 默认将配置文件存储在以下目录:
+
+| 平台 | 默认配置目录 |
+|------|-------------|
+| macOS / Linux | `~/.codebuddy` |
+| Windows | `%USERPROFILE%\.codebuddy` |
+
+### 配置目录内容
+
+```
+~/.codebuddy/
+├── settings.json      # 用户设置
+├── mcp.json           # MCP 服务器配置
+├── .mcp.json          # MCP 服务器配置（备选位置）
+└── skills/            # 用户自定义 Skills
+```
+
+### 自定义配置目录
+
+通过设置环境变量 `CODEBUDDY_CONFIG_DIR` 可以自定义配置目录位置:
+
+```bash
+export CODEBUDDY_CONFIG_DIR="$HOME/.my-codebuddy-config"
+```
+
+这在以下场景中非常有用:
+
+- 多个 CodeBuddy 实例需要独立配置
+- 企业环境中需要统一管理配置位置
+- 与其他使用 CodeBuddy 引擎的应用（如 WorkBuddy）共存时避免配置冲突
+
+
+## 🔄 更新
+
+### 自动更新
+
+CodeBuddy Code 默认会自动保持最新状态，以确保你拥有最新的功能和安全修复。
+
+#### 关闭自动更新
+
+如需关闭自动更新，可设置环境变量：
+
+```bash
+export DISABLE_AUTOUPDATER=1
+```
+
+### 手动更新
+
+使用以下命令手动更新到最新版本：
+
+```bash
+codebuddy update
+```
+
+`update` 命令会自动检测你的安装方式并执行相应的更新操作。
+
+#### 使用包管理器更新
+
+如果 `codebuddy update` 命令未能成功更新，你也可以使用包管理器重新安装：
+
+```bash
+npm install -g @tencent-ai/codebuddy-code
+```
+
+或使用其他包管理器（pnpm、yarn、bun）执行相应的安装命令。
+
+
+## 🔧 故障排查
+
+### 命令不可用
+
+**问题：** 安装后提示 `codebuddy: command not found`
+
+**解决方案：**
+
+1. 检查安装路径是否在 `PATH` 环境变量中：
+   ```bash
+   echo $PATH
+   ```
+
+2. 将 CodeBuddy 安装路径添加到 `PATH`（参考上方[验证安装](#验证安装）部分）
+
+3. 重启终端或重新加载配置文件：
+   ```bash
+   source ~/.bashrc  # 或 ~/.zshrc
+   ```
+
+### 网络问题
+
+**问题：** 安装或更新时网络连接失败
+
+**解决方案：**
+
+1. 检查网络连接
+2. 配置 npm 镜像源（如果使用 npm 安装）：
+   ```bash
+   npm config set registry https://registry.npmmirror.com
+   ```
+
+## 🗑️ 卸载
+
+### 包管理器版本卸载
+
+::: code-group
+
+```bash [Homebrew]
+# 卸载工具
+brew uninstall codebuddy-code
+
+# 移除 tap (可选)
+brew untap Tencent-CodeBuddy/tap
+```
+
+```bash [npm]
+npm uninstall -g @tencent-ai/codebuddy-code
+```
+
+```bash [pnpm]
+pnpm remove -g @tencent-ai/codebuddy-code
+```
+
+```bash [yarn]
+yarn global remove @tencent-ai/codebuddy-code
+```
+
+```bash [bun]
+bun remove -g @tencent-ai/codebuddy-code
+```
+
+:::
+
+### 原生二进制版本卸载
+
+#### macOS / Linux
+
+删除可执行文件:
+
+```bash
+rm -f ~/.local/bin/codebuddy
+```
+
+### 清理配置文件(可选)
+
+如需完全清理,可删除配置目录:
+
+**macOS / Linux:**
+```bash
+rm -rf ~/.codebuddy
+rm -rf ~/.local/share/codebuddy
+```
+
+> 💡 **提示:** 如果你使用了 `CODEBUDDY_CONFIG_DIR` 环境变量自定义了配置目录，请删除对应的目录。

package/cli/dist/web-ui/docs/cn/cli/interactive-mode.md

@@ -0,0 +1,233 @@
+# 交互模式
+
+> CodeBuddy Code 交互式会话中的完整键盘快捷键、输入模式和交互功能参考。
+
+## 键盘快捷键
+
+<Note>
+  键盘快捷键可能因平台和终端而异。在交互式会话中输入问号 `?` 可查看您环境中可用的快捷键。
+</Note>
+
+### 通用控制
+
+| 快捷键                                     | 描述                                                                                     | 上下文                                                     | CodeBuddy 支持 |
+| :----------------------------------------- | :--------------------------------------------------------------------------------------- | :--------------------------------------------------------- | :------------- |
+| `Ctrl+C`                                   | 取消当前输入或生成                                                                       | 标准中断                                                   | ✅ 支持        |
+| `Ctrl+D`                                   | 退出 CodeBuddy Code 会话（输入框为空且无进行中对话时）                                   | EOF 信号，连按两次退出                                     | ✅ 支持        |
+| `Ctrl+L`                                   | 清除终端屏幕                                                                             | 保留对话历史                                               | ✅ 支持        |
+| `Ctrl+O`                                   | 切换详细输出                                                                             | 显示详细的工具使用和执行信息                               | ✅ 支持        |
+| `Ctrl+R`                                   | 反向搜索命令历史                                                                         | 交互式搜索之前的命令                                       | ✅ 支持        |
+| `Ctrl+V` (macOS/Linux) 或 `Alt+V` (Windows) | 从剪贴板粘贴图片                                                                         | 粘贴图片或图片文件路径                                     | ✅ 支持        |
+| `Up/Down 方向键`                           | 导航命令历史                                                                             | 调用之前的输入                                             | ✅ 支持        |
+| `Esc` + `Esc`                              | 回退代码/对话                                                                            | 将代码和/或对话恢复到之前的状态 (需在输入框为空时连续按两次)                            | ✅ 支持      |
+| `Tab`                                      | 切换思考模式      | 在思考开启和思考关闭之间切换                               | ✅ 支持    |
+| `Shift+Tab` (macOS/Linux) 或 `Alt+M` (Windows) | 切换权限模式                                                                             | 在自动接受模式、计划模式和普通模式之间切换                 | ✅ 支持        |
+| `Option+P` (macOS) 或 `Alt+P` (Windows/Linux) | 切换模型                                                                                 | 快速打开模型选择面板                                       | ✅ 支持        |
+
+> **说明：**
+> - `Esc` + `Esc` 回退功能已支持：当输入框内容为空时，连续按两次 ESC 键可激活 `/rewind` 功能，快速回退代码或对话到之前的状态
+> - `Tab` 键在 CodeBuddy Code 中主要用于自动补全，扩展思考模式的切换功能部分支持
+> - `Shift+Tab` (macOS/Linux) 或 `Alt+M` (Windows) 用于切换权限模式，包括普通模式、自动接受编辑模式、跳过权限模式和计划模式。注意：在 Windows 上必须使用 `Alt+M`，`Shift+Tab` 不起作用
+
+### 多行输入
+
+| 方法           | 快捷键         | 上下文                           | CodeBuddy 支持 |
+| :------------- | :------------- | :------------------------------- | :------------- |
+| 快速转义       | `\` + `Enter`  | 在所有终端中工作                 | ✅ 支持        |
+| macOS 默认     | `Option+Enter` | macOS 上的默认设置               | ✅ 支持        |
+| 终端设置       | `Shift+Enter`  | 执行 `/terminal-setup` 后        | ✅ 支持        |
+| 控制序列       | `Ctrl+J`       | 多行的换行字符                   | ✅ 支持        |
+| 粘贴模式       | 直接粘贴       | 用于代码块、日志                 | ✅ 支持        |
+
+<Tip>
+  在终端设置中配置您首选的换行行为。运行 `/terminal-setup` 为 iTerm2 和 VS Code 终端安装 Shift+Enter 绑定。
+</Tip>
+
+### 快速命令
+
+| 快捷键       | 描述                        | 注释                                                         | CodeBuddy 支持 |
+| :----------- | :-------------------------- | :----------------------------------------------------------- | :------------- |
+| `#` 在开头   | 记忆快捷方式 - 添加到 CODEBUDDY.md | 提示选择文件                                                 | ✅ 支持        |
+| `/` 在开头   | 斜杠命令                    | 参见 [斜杠命令](slash-commands.md)                           | ✅ 支持        |
+| `!` 在开头   | Bash 模式                   | 直接运行命令并将执行输出添加到会话                           | ✅ 支持        |
+| `@`          | 文件路径提及                | 触发文件路径自动补全                                         | ✅ 支持        |
+
+### 编辑快捷键
+
+| 快捷键                    | 描述                     | CodeBuddy 支持 |
+| :------------------------ | :----------------------- | :------------- |
+| `Ctrl+A`                  | 移动到行首               | ✅ 支持        |
+| `Ctrl+E`                  | 移动到行尾               | ✅ 支持        |
+| `Ctrl+K`                  | 删除从光标到行尾         | ✅ 支持        |
+| `Ctrl+U`                  | 删除从行首到光标         | ✅ 支持        |
+| `Ctrl+W`                  | 删除前一个单词           | ✅ 支持        |
+| `Ctrl+Y`                  | 复制最后一条 AI 回复到剪贴板 | ✅ 支持        |
+| `Alt/Option+Backspace`    | 删除前一个单词           | ✅ 支持        |
+| `Alt/Option+Delete`       | 删除下一个单词           | ✅ 支持        |
+| `Alt/Option+Left`         | 移动到上一个单词         | ✅ 支持        |
+| `Alt/Option+Right`        | 移动到下一个单词         | ✅ 支持        |
+| `Ctrl+Left`               | 移动到行首               | ✅ 支持        |
+| `Ctrl+Right`              | 移动到行尾               | ✅ 支持        |
+| `Ctrl+G`                  | 打开外部编辑器编辑提示词 | ✅ 支持        |
+
+## Vim 编辑器模式
+
+使用 `/vim` 命令启用 vim 风格编辑,或通过 `/config` 永久配置。
+
+### 模式切换
+
+| 命令  | 操作                   | 从模式   | CodeBuddy 支持 |
+| :---- | :--------------------- | :------- | :------------- |
+| `Esc` | 进入 NORMAL 模式       | INSERT   | ✅ 支持        |
+| `i`   | 在光标前插入           | NORMAL   | ✅ 支持        |
+| `I`   | 在行首插入             | NORMAL   | ✅ 支持        |
+| `a`   | 在光标后插入           | NORMAL   | ✅ 支持        |
+| `A`   | 在行尾插入             | NORMAL   | ✅ 支持        |
+| `o`   | 在下方打开新行         | NORMAL   | ✅ 支持        |
+| `O`   | 在上方打开新行         | NORMAL   | ✅ 支持        |
+
+### 导航 （NORMAL 模式）
+
+| 命令            | 操作                   | CodeBuddy 支持 |
+| :-------------- | :--------------------- | :------------- |
+| `h`/`j`/`k`/`l` | 向左/下/上/右移动      | ✅ 支持        |
+| `w`             | 下一个单词             | ✅ 支持        |
+| `e`             | 单词末尾               | ✅ 支持        |
+| `b`             | 上一个单词             | ✅ 支持        |
+| `0`             | 行首                   | ✅ 支持        |
+| `$`             | 行尾                   | ✅ 支持        |
+| `^`             | 第一个非空白字符       | ✅ 支持        |
+| `gg`            | 输入开始               | ✅ 支持        |
+| `G`             | 输入结束               | ✅ 支持        |
+
+### 编辑 （NORMAL 模式）
+
+| 命令           | 操作                   | CodeBuddy 支持 |
+| :------------- | :--------------------- | :------------- |
+| `x`            | 删除字符               | ✅ 支持        |
+| `dd`           | 删除行                 | ✅ 支持        |
+| `D`            | 删除到行尾             | ✅ 支持        |
+| `dw`/`de`/`db` | 删除单词/到末尾/到开头 | ✅ 支持        |
+| `cc`           | 修改行                 | ✅ 支持        |
+| `C`            | 修改到行尾             | ✅ 支持        |
+| `cw`/`ce`/`cb` | 修改单词/到末尾/到开头 | ✅ 支持        |
+| `.`            | 重复上次修改           | ✅ 支持        |
+
+## 命令历史
+
+CodeBuddy Code 为当前会话维护命令历史：
+
+* 历史记录按工作目录存储
+* 使用 `/clear` 开启全新对话（旧对话可通过 `/resume` 恢复）
+* 使用 Up/Down 方向键导航 （参见上面的键盘快捷键）
+* **注意**：历史扩展 （`!`) 默认禁用
+
+### 使用 Ctrl+R 反向搜索
+
+按 `Ctrl+R` 交互式搜索您的命令历史：
+
+1. **开始搜索**：按 `Ctrl+R` 激活反向历史搜索
+2. **输入查询**：输入文本以在之前的命令中搜索 - 搜索词将在匹配结果中高亮显示
+3. **导航匹配**：再次按 `Ctrl+R` 循环浏览更早的匹配项
+4. **接受匹配**:
+   * 按 `Tab` 或 `Esc` 接受当前匹配并继续编辑
+   * 按 `Enter` 接受并立即执行命令
+5. **取消搜索**:
+   * 按 `Ctrl+C` 取消并恢复原始输入
+   * 在空搜索时按 `Backspace` 取消
+
+搜索显示匹配的命令并高亮搜索词，方便查找和重用之前的输入。
+
+## 后台 Bash 命令
+
+CodeBuddy Code 支持在后台运行 bash 命令，允许您在长时间运行的进程执行时继续工作。
+
+### 后台运行的工作原理
+
+当 CodeBuddy Code 在后台运行命令时，它会异步运行命令并立即返回后台任务 ID。CodeBuddy Code 可以在命令继续在后台执行时响应新的提示。
+
+要在后台运行命令，您可以：
+
+* 提示 CodeBuddy Code 在后台运行命令
+* 按 `Ctrl+B` 将常规 Bash 工具调用移至后台。(Tmux 用户必须按两次 `Ctrl+B`,因为 tmux 的前缀键。)
+
+**主要功能：**
+
+* 输出被缓冲，CodeBuddy 可以使用 TaskOutput 工具检索它
+* 后台任务具有唯一 ID,用于跟踪和输出检索
+* CodeBuddy Code 退出时，后台任务会自动清理
+
+**常见的后台命令：**
+
+* 构建工具 （webpack, vite, make)
+* 包管理器 （npm, yarn, pnpm)
+* 测试运行器 （jest, pytest)
+* 开发服务器
+* 长时间运行的进程 （docker, terraform)
+
+### 使用 `!` 前缀的 Bash 模式
+
+通过在输入前加上 `!` 前缀直接运行 bash 命令，无需通过 CodeBuddy:
+
+```bash
+! npm test
+! git status
+! ls -la
+```
+
+Bash 模式：
+
+* 将命令及其输出添加到对话上下文中
+* 显示实时进度和输出
+* 支持相同的 `Ctrl+B` 后台运行长时间运行的命令
+* 不需要 CodeBuddy 解释或批准命令
+
+这对于快速 shell 操作同时保持对话上下文非常有用。
+
+## 权限模式
+
+CodeBuddy Code 支持多种权限模式来控制工具使用的授权方式：
+
+### 可用模式
+
+| 模式                  | 描述                                                                 | 快捷键切换         |
+| :-------------------- | :------------------------------------------------------------------- | :----------------- |
+| **普通模式 （默认）**   | 根据权限规则询问工具使用确认                                         | `Shift+Tab` (macOS/Linux) / `Alt+M` (Windows) |
+| **自动接受编辑模式**  | 自动批准文件编辑操作 （Edit/Write),其他工具仍需确认                   | `Shift+Tab` (macOS/Linux) / `Alt+M` (Windows) |
+| **跳过权限模式**      | 绕过所有权限检查。建议仅在无互联网访问的沙箱中使用                   | `Shift+Tab` (macOS/Linux) / `Alt+M` (Windows) |
+| **计划模式**          | AI 将制定计划并等待批准后再执行                                      | `Shift+Tab` (macOS/Linux) / `Alt+M` (Windows) |
+
+### 切换权限模式
+
+* 使用 `Shift+Tab` (macOS/Linux) 或 `Alt+M` (Windows) 在模式之间切换。**注意：Windows 用户必须使用 `Alt+M`**
+* 使用 `--permission-mode` 命令行参数指定启动模式：
+  ```bash
+  codebuddy --permission-mode acceptEdits
+  codebuddy --permission-mode bypassPermissions
+  codebuddy --permission-mode plan
+  ```
+* 在 `settings.json` 中设置默认模式：
+  ```json
+  {
+    "permissions": {
+      "defaultMode": "acceptEdits"
+    }
+  }
+  ```
+
+### 权限规则
+
+权限模式与权限规则结合使用，以提供细粒度控制。参见 [IAM 文档](iam.md) 了解配置权限规则的详细信息。
+
+## 相关文档
+
+* [斜杠命令](slash-commands.md) - 交互式会话命令
+* [CLI 参考](cli-reference.md) - 命令行标志和选项
+* [设置配置](settings.md) - 配置选项
+* [记忆管理](memory.md) - 管理 CODEBUDDY.md 文件
+* [IAM 权限](iam.md) - 工具权限和访问控制
+* [Bash 沙箱](bash-sandboxing.md) - Bash 命令沙箱模式
+
+---
+
+> **提示**：在交互式会话中随时输入 `?` 可查看可用的快捷键和命令。使用 `/help` 命令获取更多帮助信息。