@tencent-ai/agent-sdk 0.3.99 → 0.3.101

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

@@ -0,0 +1,266 @@
+# CodeBuddy Code Installation Guide
+
+## 📋 Table of Contents
+
+- [Installation Methods](#installation-methods)
+  - [Install via Package Manager](#-install-via-package-manager)
+  - [Install via Native Binary (Beta)](#️-install-via-native-binary-beta)
+- [Updates](#-updates)
+- [Troubleshooting](#-troubleshooting)
+- [Uninstallation](#-uninstallation)
+
+---
+
+## Installation Methods
+
+### 📦 Install via Package Manager
+
+#### Node.js Package Managers
+
+**Prerequisites:** Node.js 18.20 or higher
+
+Choose your preferred package manager and run the following command:
+
+::: 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)
+
+No Node.js required, install directly:
+
+::: code-group
+
+```bash [Two-step Installation]
+# Add tap
+brew tap Tencent-CodeBuddy/tap
+
+# Install tool
+brew install codebuddy-code
+```
+
+```bash [Single Command Installation]
+brew install Tencent-CodeBuddy/tap/codebuddy-code
+```
+
+```ruby [Brewfile]
+tap "Tencent-CodeBuddy/tap"
+brew "codebuddy-code"
+```
+
+:::
+
+#### Verify Installation
+
+After installation, run the following command to verify successful installation:
+
+```bash
+codebuddy --version
+```
+
+
+### ⚙️ Install via Native Binary (Beta)
+
+> ⚠️ **Beta Testing Phase**
+>
+> Native binary installation is currently in Beta testing phase, and features are still being improved.
+> If you encounter any issues, please submit an issue report on the [Issues page](https://cnb.cool/codebuddy/codebuddy-code/-/issues), or contact technical support (codebuddy@tencent.com).
+
+#### Features
+
+Native binary installation provides the following features compared to the npm version:
+
+- Single executable file with no additional dependencies
+- No Node.js runtime required
+- Improved automatic update mechanism
+
+#### Supported Platforms
+
+- macOS (Apple Silicon M1/M2/M3 or Intel x86_64)
+- Linux (arm64 or x86_64)
+- Windows (x86_64)
+
+#### Migrating from npm Version
+
+If you have already installed CodeBuddy Code via npm, you can migrate to the native binary version using the following command:
+
+```bash
+codebuddy install
+```
+
+#### Fresh Installation
+
+::: 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
+```
+
+:::
+
+#### Verify Installation
+
+The installation script will automatically download the latest version and configure environment variables. After installation, run the following command to verify:
+
+```bash
+codebuddy --version
+```
+
+**If the command is not available**, manually add the installation path to the `PATH` environment variable:
+
+::: code-group
+
+```bash [macOS / Linux]
+export PATH="$HOME/.local/bin:$PATH"
+
+# For permanent effect, it's recommended to add to your shell configuration file:
+# Bash: ~/.bashrc or ~/.bash_profile
+# Zsh: ~/.zshrc
+```
+
+```powershell [Windows]
+# Add the following path to user environment variables:
+# %USERPROFILE%\AppData\Local\codebuddy\bin
+```
+
+:::
+
+
+## 🔄 Updates
+
+### Automatic Updates
+
+CodeBuddy Code automatically stays up to date by default to ensure you have the latest features and security fixes.
+
+#### Disable Automatic Updates
+
+To disable automatic updates, set the environment variable:
+
+```bash
+export DISABLE_AUTOUPDATER=1
+```
+
+### Manual Updates
+
+Use the following command to manually update to the latest version:
+
+```bash
+codebuddy update
+```
+
+The `update` command will automatically detect your installation method and perform the corresponding update operation.
+
+#### Update via Package Manager
+
+If the `codebuddy update` command fails to update successfully, you can also reinstall using your package manager:
+
+```bash
+npm install -g @tencent-ai/codebuddy-code
+```
+
+Or use the corresponding installation command with other package managers (pnpm, yarn, bun).
+
+
+## 🔧 Troubleshooting
+
+### Command Not Available
+
+**Issue:** After installation, you get `codebuddy: command not found`
+
+**Solution:**
+
+1. Check if the installation path is in the `PATH` environment variable:
+   ```bash
+   echo $PATH
+   ```
+
+2. Add the CodeBuddy installation path to `PATH` (refer to the [Verify Installation](#verify-installation) section above)
+
+3. Restart your terminal or reload the configuration file:
+   ```bash
+   source ~/.bashrc  # or ~/.zshrc
+   ```
+
+### Network Issues
+
+**Issue:** Network connection failure during installation or update
+
+**Solution:**
+
+1. Check network connection
+2. Configure npm registry mirror (if installing via npm):
+   ```bash
+   npm config set registry https://registry.npmmirror.com
+   ```
+
+## 🗑️ Uninstallation
+
+### Uninstall Package Manager Version
+
+::: code-group
+
+```bash [Homebrew]
+# Uninstall tool
+brew uninstall codebuddy-code
+
+# Remove tap (optional)
+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
+```
+
+:::
+
+### Uninstall Native Binary Version
+
+#### macOS / Linux
+
+Remove the executable file:
+
+```bash
+rm -f ~/.local/bin/codebuddy
+```
+
+### Clean Configuration Files (Optional)
+
+For complete cleanup, you can delete the configuration directories:
+
+**macOS / Linux:**
+```bash
+rm -rf ~/.codebuddy
+rm -rf ~/.local/share/codebuddy
+```

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

@@ -0,0 +1,233 @@
+# Interactive Mode
+
+> Complete keyboard shortcuts, input modes, and interactive features reference for CodeBuddy Code interactive sessions.
+
+## Keyboard Shortcuts
+
+<Note>
+  Keyboard shortcuts may vary by platform and terminal. Type a question mark `?` in an interactive session to see the shortcuts available in your environment.
+</Note>
+
+### General Controls
+
+| Shortcut                                   | Description                                                                              | Context                                                    | CodeBuddy Support |
+| :----------------------------------------- | :--------------------------------------------------------------------------------------- | :--------------------------------------------------------- | :---------------- |
+| `Ctrl+C`                                   | Cancel current input or generation                                                       | Standard interrupt                                         | ✅ Supported      |
+| `Ctrl+D`                                   | Exit CodeBuddy Code session (when input box is empty and no conversation in progress)    | EOF signal, press twice to exit                            | ✅ Supported      |
+| `Ctrl+L`                                   | Clear terminal screen                                                                    | Preserves conversation history                             | ✅ Supported      |
+| `Ctrl+O`                                   | Toggle verbose output                                                                    | Display detailed tool usage and execution information      | ✅ Supported      |
+| `Ctrl+R`                                   | Reverse search command history                                                           | Interactive search of previous commands                    | ✅ Supported      |
+| `Ctrl+V` (macOS/Linux) or `Alt+V` (Windows) | Paste image from clipboard                                                             | Paste image or image file path                             | ✅ Supported      |
+| `Up/Down Arrow Keys`                       | Navigate command history                                                                 | Recall previous inputs                                     | ✅ Supported      |
+| `Esc` + `Esc`                              | Rewind code/conversation                                                                 | Restore code and/or conversation to previous state (requires pressing ESC twice consecutively when the input box is empty) | ✅ Supported      |
+| `Tab`                                      | Toggle thinking mode                                                                     | Switch between thinking on and thinking off                | ✅ Supported      |
+| `Shift+Tab` (macOS/Linux) or `Alt+M` (Windows) | Toggle permission mode                                                                   | Switch between auto-accept, plan, and normal modes         | ✅ Supported      |
+| `Option+P` (macOS) or `Alt+P` (Windows/Linux) | Switch model                                                                             | Quickly open model selection panel                         | ✅ Supported      |
+
+> **Notes:**
+> - `Esc` + `Esc` rewind functionality is now supported: when the input box is empty, pressing the ESC key twice consecutively activates the `/rewind` feature, allowing you to quickly revert code or conversation to a previous state
+> - `Tab` key in CodeBuddy Code is primarily used for auto-completion, with partial support for thinking mode toggle
+> - `Shift+Tab` (macOS/Linux) or `Alt+M` (Windows) is used to toggle permission modes, including normal mode, auto-accept edits mode, skip permissions mode, and plan mode. Note: On Windows, you must use `Alt+M`; `Shift+Tab` does not work
+
+### Multi-line Input
+
+| Method            | Shortcut       | Context                           | CodeBuddy Support |
+| :---------------- | :------------- | :------------------------------- | :---------------- |
+| Quick escape      | `\` + `Enter`  | Works in all terminals            | ✅ Supported      |
+| macOS default     | `Option+Enter` | Default setting on macOS          | ✅ Supported      |
+| Terminal setup    | `Shift+Enter`  | After executing `/terminal-setup` | ✅ Supported      |
+| Control sequence  | `Ctrl+J`       | Line feed character for multi-line | ✅ Supported      |
+| Paste mode        | Direct paste   | For code blocks, logs             | ✅ Supported      |
+
+<Tip>
+  Configure your preferred line break behavior in terminal settings. Run `/terminal-setup` to install Shift+Enter bindings for iTerm2 and VS Code terminal.
+</Tip>
+
+### Quick Commands
+
+| Shortcut          | Description                        | Notes                                                      | CodeBuddy Support |
+| :---------------- | :--------------------------------- | :--------------------------------------------------------- | :---------------- |
+| `#` at start      | Memory shortcut - Add to CODEBUDDY.md | Prompts for file selection                               | ✅ Supported      |
+| `/` at start      | Slash commands                     | See [Slash Commands](slash-commands.md)                    | ✅ Supported      |
+| `!` at start      | Bash mode                          | Run commands directly and add execution output to session | ✅ Supported      |
+| `@`               | File path mention                  | Trigger file path auto-completion                          | ✅ Supported      |
+
+### Editing Shortcuts
+
+| Shortcut                  | Description                       | CodeBuddy Support |
+| :------------------------ | :-------------------------------- | :---------------- |
+| `Ctrl+A`                  | Move to start of line             | ✅ Supported      |
+| `Ctrl+E`                  | Move to end of line               | ✅ Supported      |
+| `Ctrl+K`                  | Delete from cursor to end of line | ✅ Supported      |
+| `Ctrl+U`                  | Delete from start of line to cursor | ✅ Supported      |
+| `Ctrl+W`                  | Delete previous word              | ✅ Supported      |
+| `Ctrl+Y`                  | Copy last AI reply to clipboard   | ✅ Supported      |
+| `Alt/Option+Backspace`    | Delete previous word              | ✅ Supported      |
+| `Alt/Option+Delete`       | Delete next word                  | ✅ Supported      |
+| `Alt/Option+Left`         | Move to previous word             | ✅ Supported      |
+| `Alt/Option+Right`        | Move to next word                 | ✅ Supported      |
+| `Ctrl+Left`               | Move to start of line             | ✅ Supported      |
+| `Ctrl+Right`              | Move to end of line               | ✅ Supported      |
+| `Ctrl+G`                  | Open external editor to edit prompt | ✅ Supported      |
+
+## Vim Editor Mode
+
+Enable vim-style editing with the `/vim` command, or configure permanently via `/config`.
+
+### Mode Switching
+
+| Command  | Action                   | From Mode | CodeBuddy Support |
+| :------- | :----------------------- | :-------- | :---------------- |
+| `Esc`    | Enter NORMAL mode        | INSERT    | ✅ Supported      |
+| `i`      | Insert before cursor     | NORMAL    | ✅ Supported      |
+| `I`      | Insert at start of line  | NORMAL    | ✅ Supported      |
+| `a`      | Insert after cursor      | NORMAL    | ✅ Supported      |
+| `A`      | Insert at end of line    | NORMAL    | ✅ Supported      |
+| `o`      | Open new line below      | NORMAL    | ✅ Supported      |
+| `O`      | Open new line above      | NORMAL    | ✅ Supported      |
+
+### Navigation (NORMAL Mode)
+
+| Command           | Action                   | CodeBuddy Support |
+| :---------------- | :----------------------- | :---------------- |
+| `h`/`j`/`k`/`l`   | Move left/down/up/right  | ✅ Supported      |
+| `w`               | Next word                | ✅ Supported      |
+| `e`               | End of word              | ✅ Supported      |
+| `b`               | Previous word            | ✅ Supported      |
+| `0`               | Start of line            | ✅ Supported      |
+| `$`               | End of line              | ✅ Supported      |
+| `^`               | First non-whitespace character | ✅ Supported      |
+| `gg`              | Start of input           | ✅ Supported      |
+| `G`               | End of input             | ✅ Supported      |
+
+### Editing (NORMAL Mode)
+
+| Command              | Action                   | CodeBuddy Support |
+| :------------------- | :----------------------- | :---------------- |
+| `x`                  | Delete character         | ✅ Supported      |
+| `dd`                 | Delete line              | ✅ Supported      |
+| `D`                  | Delete to end of line    | ✅ Supported      |
+| `dw`/`de`/`db`       | Delete word/to end/to start | ✅ Supported      |
+| `cc`                 | Change line              | ✅ Supported      |
+| `C`                  | Change to end of line    | ✅ Supported      |
+| `cw`/`ce`/`cb`       | Change word/to end/to start | ✅ Supported      |
+| `.`                  | Repeat last change       | ✅ Supported      |
+
+## Command History
+
+CodeBuddy Code maintains command history for the current session:
+
+* History is stored by working directory
+* Use `/clear` to start a fresh conversation (old conversations can be resumed via `/resume`)
+* Navigate using Up/Down arrow keys (see keyboard shortcuts above)
+* **Note**: History expansion (`!`) is disabled by default
+
+### Reverse Search with Ctrl+R
+
+Press `Ctrl+R` to interactively search your command history:
+
+1. **Start search**: Press `Ctrl+R` to activate reverse history search
+2. **Enter query**: Type text to search in previous commands - search terms will be highlighted in matching results
+3. **Navigate matches**: Press `Ctrl+R` again to cycle through earlier matches
+4. **Accept match**:
+   * Press `Tab` or `Esc` to accept the current match and continue editing
+   * Press `Enter` to accept and execute the command immediately
+5. **Cancel search**:
+   * Press `Ctrl+C` to cancel and restore original input
+   * Press `Backspace` on empty search to cancel
+
+The search displays matching commands and highlights search terms, making it easy to find and reuse previous inputs.
+
+## Background Bash Commands
+
+CodeBuddy Code supports running bash commands in the background, allowing you to continue working while long-running processes execute.
+
+### How Background Execution Works
+
+When CodeBuddy Code runs a command in the background, it runs the command asynchronously and immediately returns a background task ID. CodeBuddy Code can respond to new prompts while the command continues to execute in the background.
+
+To run a command in the background, you can:
+
+* Prompt CodeBuddy Code to run the command in the background
+* Press `Ctrl+B` to move a regular Bash tool call to the background. (Tmux users must press `Ctrl+B` twice due to tmux's prefix key.)
+
+**Key features:**
+
+* Output is buffered and CodeBuddy can retrieve it using the BashOutput tool
+* Background tasks have unique IDs for tracking and output retrieval
+* Background tasks are automatically cleaned up when CodeBuddy Code exits
+
+**Common background commands:**
+
+* Build tools (webpack, vite, make)
+* Package managers (npm, yarn, pnpm)
+* Test runners (jest, pytest)
+* Development servers
+* Long-running processes (docker, terraform)
+
+### Bash Mode with `!` Prefix
+
+Run bash commands directly by prefixing your input with `!`, without going through CodeBuddy:
+
+```bash
+! npm test
+! git status
+! ls -la
+```
+
+Bash mode:
+
+* Adds commands and their output to the conversation context
+* Displays live progress and output
+* Supports the same `Ctrl+B` for running long-running commands in the background
+* Doesn't require CodeBuddy to interpret or approve commands
+
+This is useful for quick shell operations while maintaining conversation context.
+
+## Permission Modes
+
+CodeBuddy Code supports multiple permission modes to control how tool usage is authorized:
+
+### Available Modes
+
+| Mode                       | Description                                                              | Toggle Shortcut     |
+| :------------------------- | :----------------------------------------------------------------------- | :------------------ |
+| **Normal Mode (Default)**  | Asks for confirmation of tool usage based on permission rules            | `Shift+Tab` (macOS/Linux) / `Alt+M` (Windows) |
+| **Auto-Accept Edits Mode** | Automatically approves file editing operations (Edit/Write), other tools still require confirmation | `Shift+Tab` (macOS/Linux) / `Alt+M` (Windows) |
+| **Skip Permissions Mode**  | Bypasses all permission checks. Recommended for use only in sandboxes without internet access | `Shift+Tab` (macOS/Linux) / `Alt+M` (Windows) |
+| **Plan Mode**              | AI will formulate a plan and wait for approval before execution          | `Shift+Tab` (macOS/Linux) / `Alt+M` (Windows) |
+
+### Toggling Permission Modes
+
+* Use `Shift+Tab` (macOS/Linux) or `Alt+M` (Windows) to cycle through modes. **Note: Windows users must use `Alt+M`**
+* Specify startup mode using the `--permission-mode` command line argument:
+  ```bash
+  codebuddy --permission-mode acceptEdits
+  codebuddy --permission-mode bypassPermissions
+  codebuddy --permission-mode plan
+  ```
+* Set default mode in `settings.json`:
+  ```json
+  {
+    "permissions": {
+      "defaultMode": "acceptEdits"
+    }
+  }
+  ```
+
+### Permission Rules
+
+Permission modes work in conjunction with permission rules to provide fine-grained control. See the [IAM documentation](iam.md) for details on configuring permission rules.
+
+## Related Documentation
+
+* [Slash Commands](slash-commands.md) - Interactive session commands
+* [CLI Reference](cli-reference.md) - Command line flags and options
+* [Settings Configuration](settings.md) - Configuration options
+* [Memory Management](memory.md) - Managing CODEBUDDY.md files
+* [IAM Permissions](iam.md) - Tool permissions and access control
+* [Bash Sandboxing](bash-sandboxing.md) - Bash command sandboxing mode
+
+---
+
+> **Tip**: Type `?` at any time in an interactive session to see available shortcuts and commands. Use the `/help` command for more help information.