@tencent-ai/agent-sdk 0.3.99 → 0.3.101

package/cli/dist/web-ui/docs/en/cli/tools-reference.md

@@ -0,0 +1,99 @@
+# Tools Reference
+
+> Complete reference for CodeBuddy Code's available tools, including permission requirements.
+
+CodeBuddy Code includes a set of built-in tools to help understand and modify your codebase. The tool names in the table below are the identifiers used in [permission rules](iam.md#tool-specific-permission-rules), [sub-agent tool lists](sub-agents.md), and [Hook matchers](hooks.md).
+
+| Tool | Description | Requires Permission |
+| :--- | :--- | :------- |
+| `Agent` | Spawns a [sub-agent](sub-agents.md) with an independent context window to handle tasks | No |
+| `AskUserQuestion` | Asks the user a multiple-choice question to gather requirements or clarify ambiguities | Yes |
+| `Bash` | Executes shell commands in your environment. See [Bash Tool Behavior](#bash-tool-behavior) | Yes |
+| `CronCreate` | Schedules recurring or one-time tasks within the current session (expires on exit). See [Scheduled Tasks](scheduled-tasks.md) | No |
+| `CronDelete` | Cancels a scheduled task by ID | No |
+| `CronList` | Lists all scheduled tasks in the current session | No |
+| `DeferExecuteTool` | Executes a deferred tool discovered via `ToolSearch` | No |
+| `Edit` | Performs precise string replacement edits on files | Yes |
+| `EnterPlanMode` | Switches to plan mode for designing implementation approaches before coding | No |
+| `EnterWorktree` | Creates an isolated [git worktree](worktree.md) and switches into it | Yes |
+| `ExitPlanMode` | Submits a plan for user approval and exits plan mode | Yes |
+| `Glob` | Finds files using glob patterns | No |
+| `Grep` | Searches file contents using regex patterns | No |
+| `ImageEdit` | Edits or modifies existing images based on text instructions | Yes |
+| `ImageGen` | Generates images from text descriptions | Yes |
+| `LeaveWorktree` | Exits the worktree session and returns to the original directory | Yes |
+| `LSP` | Provides code intelligence via Language Server. Automatically reports type errors and warnings after file edits. Also supports navigation operations such as go-to-definition, find references, get type info, list symbols, find implementations, and trace call hierarchies. Requires a [Code Intelligence Plugin](plugins.md) and its language server binary | No |
+| `MultiEdit` | Performs multiple edits on the same file in a single atomic operation | Yes |
+| `NotebookEdit` | Modifies Jupyter notebook cell contents | Yes |
+| `Read` | Reads file contents, supporting images, PDFs, and Jupyter notebooks | No |
+| `SendMessage` | Sends messages to teammates in an [Agent Team](agent-teams.md) | No |
+| `Skill` | Executes a [Skill](skills.md) in the main conversation | No |
+| `SlashCommand` | Executes a custom [slash command](slash-commands.md) | Yes |
+| `StructuredOutput` | Returns structured output conforming to a JSON Schema | No |
+| `TaskCreate` | Creates a new task in the task list | No |
+| `TaskGet` | Retrieves full details of a specific task | No |
+| `TaskList` | Lists all tasks with their current status | No |
+| `TaskOutput` | Retrieves output from a background task or sub-agent | No |
+| `TaskStop` | Stops a running background task by ID | No |
+| `TaskUpdate` | Updates task status, dependencies, details, or deletes a task | No |
+| `TeamCreate` | Creates an [Agent Team](agent-teams.md) for coordinating multiple agents | No |
+| `TeamDelete` | Deletes an Agent Team and its task directory | No |
+| `ToolSearch` | Searches and loads deferred tools, supporting both built-in tools and [MCP tools](mcp.md#deferred-loading-defer_loading) | No |
+| `WebFetch` | Fetches content from a specified URL and performs AI analysis | Yes |
+| `WebSearch` | Performs a web search | Yes |
+| `Write` | Creates or overwrites files | Yes |
+
+Permission rules can be configured via the `/permissions` command or in [permission settings](settings.md#permission-settings). See also [Tool-Specific Permission Rules](iam.md#tool-specific-permission-rules).
+
+## Tool Aliases
+
+Some tools have aliases that can be used interchangeably in permission rules:
+
+| Tool | Alias |
+| :--- | :--- |
+| `TaskOutput` | `BashOutput` |
+| `TaskStop` | `KillShell` |
+
+## Bash Tool Behavior
+
+The Bash tool executes each command in a separate process with the following persistence characteristics:
+
+* **Working directory** persists across commands. Set `CODEBUDDY_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` to reset to the project directory after each command.
+* **Environment variables do not persist**. An `export` in one command will not take effect in the next command.
+
+Activate your virtualenv or conda environment before launching CodeBuddy Code. To persist environment variables across Bash commands, set [`CODEBUDDY_ENV_FILE`](env-vars.md) to point to a shell script before startup, or use a [SessionStart Hook](hooks.md) to populate it dynamically.
+
+### Sandbox Mode
+
+The Bash tool supports [sandbox isolation](bash-sandboxing.md), which can restrict filesystem and network access. When sandbox is enabled, commands execute in a restricted environment to prevent unauthorized system access.
+
+The `dangerouslyDisableSandbox` parameter allows bypassing the sandbox on a per-command basis (requires user approval).
+
+### Background Execution
+
+The `run_in_background` parameter allows running commands in the background, using the `TaskOutput` tool to read the output. This is suitable for long-running builds, tests, and similar scenarios.
+
+## Deferred Tool Loading
+
+Some tools (such as those provided via [MCP servers](mcp.md)) use deferred loading. These tools do not appear in the initial tool list and must be discovered and activated via `ToolSearch`. Once activated, tools remain available for the rest of the session.
+
+Tools can be configured as deferred via product configuration:
+
+```json
+{
+  "tools": {
+    "ToolName": {
+      "deferLoading": true
+    }
+  }
+}
+```
+
+## See Also
+
+* [Identity and Access Management](iam.md): Permission system, rule syntax, and tool-specific rules
+* [Sub-Agents](sub-agents.md): Configuring tool access for sub-agents
+* [Hooks](hooks-guide.md): Running custom commands before and after tool execution
+* [MCP Integration](mcp.md): Extending available tools via MCP servers
+* [Scheduled Tasks](scheduled-tasks.md): Scheduling automated tasks with CronCreate
+* [Agent Teams](agent-teams.md): Multi-agent collaborative team system

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

@@ -0,0 +1,190 @@
+# Troubleshooting and Best Practices
+
+This document covers common problem solutions and usage optimization tips.
+
+
+## Common Issues
+
+### Shared Quota
+
+CLI, CodeBuddy IDE, and CodeBuddy Plugin share the same account's resource quota.
+
+### ESC Key Not Working in JetBrains IDE
+
+JetBrains terminal handles the ESC key differently. Use `Ctrl+ESC` or `Shift+ESC` instead.
+
+| Action | Standard Terminal | JetBrains Terminal |
+|-----|---------|---------------|
+| Exit/Cancel | `ESC` | `Ctrl+ESC` or `Shift+ESC` |
+
+### Model Switching
+
+```
+/model              # Interactive selection
+/model [model-name] # Switch directly
+/status             # View current model
+```
+
+### --serve Mode Network Access Issues
+
+#### LAN IP Access Returns `ERR_EMPTY_RESPONSE`
+
+**Symptom**: After starting with `codebuddy --serve`, accessing via LAN IP (e.g., `http://10.31.110.26:52477`) results in `ERR_EMPTY_RESPONSE` in the browser.
+
+**Cause**: The HTTP server listens on `127.0.0.1` (loopback address) by default, accepting only local connections. When accessing via LAN IP, the request reaches the machine but is rejected by the service.
+
+**Solution**: Add the `--host 0.0.0.0` parameter at startup to listen on all network interfaces:
+
+```bash
+codebuddy --serve --host 0.0.0.0 --port 8080
+```
+
+> Password authentication is automatically enabled when starting on a non-loopback address. The password is visible in the console output.
+
+#### Verify Service Listening Status
+
+You can check if the service is listening correctly with:
+
+```bash
+# macOS / Linux
+lsof -i :PORT_NUMBER
+
+# Or
+netstat -an | grep PORT_NUMBER
+```
+
+- If showing `127.0.0.1:PORT` — accepts local connections only
+- If showing `0.0.0.0:PORT` or `*:PORT` — accepts all network connections
+
+---
+
+## Updates
+
+### Auto Updates
+
+Enabled by default; new versions are automatically applied on next startup. Manage the toggle via `/config`.
+
+### Manual Update
+
+```bash
+codebuddy update                                    # Built-in command (recommended)
+npm install -g @tencent-ai/codebuddy-code@latest   # npm update
+```
+
+### Version Check
+
+```bash
+codebuddy --version                                 # Current version
+npm view @tencent-ai/codebuddy-code version        # Latest version
+```
+
+---
+
+## Migrating from Claude Code
+
+### Migration Content
+
+| Directory/File | Description |
+|----------|------|
+| `agents/` | Custom agents configuration |
+| `commands/` | Slash command definitions |
+| `skills/` | Skill definitions |
+| `CLAUDE.md` -> `CODEBUDDY.md` | AI instructions and memory documents |
+
+### Option 1: Symbolic Links (Recommended)
+
+Share configuration; changes in one place take effect in both.
+
+```bash
+# macOS/Linux
+cd ~/.codebuddy
+ln -s ~/.claude/agents agents
+ln -s ~/.claude/commands commands
+ln -s ~/.claude/skills skills
+ln -s ~/.claude/CLAUDE.md CODEBUDDY.md
+```
+
+```powershell
+# Windows (requires admin privileges)
+cd $env:USERPROFILE\.codebuddy
+New-Item -ItemType SymbolicLink -Path agents -Target $env:USERPROFILE\.claude\agents
+New-Item -ItemType SymbolicLink -Path commands -Target $env:USERPROFILE\.claude\commands
+New-Item -ItemType SymbolicLink -Path skills -Target $env:USERPROFILE\.claude\skills
+New-Item -ItemType SymbolicLink -Path CODEBUDDY.md -Target $env:USERPROFILE\.claude\CLAUDE.md
+```
+
+### Option 2: Copy Files
+
+Independent configuration; changes don't affect each other.
+
+```bash
+# macOS/Linux
+cp -r ~/.claude/agents ~/.codebuddy/agents
+cp -r ~/.claude/commands ~/.codebuddy/commands
+cp -r ~/.claude/skills ~/.codebuddy/skills
+cp ~/.claude/CLAUDE.md ~/.codebuddy/CODEBUDDY.md
+```
+
+```powershell
+# Windows
+Copy-Item -Recurse $env:USERPROFILE\.claude\agents $env:USERPROFILE\.codebuddy\agents
+Copy-Item -Recurse $env:USERPROFILE\.claude\commands $env:USERPROFILE\.codebuddy\commands
+Copy-Item -Recurse $env:USERPROFILE\.claude\skills $env:USERPROFILE\.codebuddy\skills
+Copy-Item $env:USERPROFILE\.claude\CLAUDE.md $env:USERPROFILE\.codebuddy\CODEBUDDY.md
+```
+
+### One-Click Plugin Skills Installation
+
+Skills from Claude Code plugins support one-click installation and are automatically loaded after installation.
+
+### Verify Migration
+
+```bash
+codebuddy         # Start
+/skills           # Check Skills
+/config           # View configuration
+```
+
+---
+
+## Cost Optimization
+
+### Core Principles
+
+- Use `/clear` to start a new session for new tasks
+- Use `/compact` to compress history for long conversations
+- Use `@filename` to reference files instead of pasting code
+
+### Session Management Commands
+
+| Command | Function |
+|-----|------|
+| `/cost` | View token consumption |
+| `/clear` | Start a new session |
+| `/compact` | Compress history |
+| `/resume` | Resume a previous conversation |
+
+### Cost Comparison
+
+| Approach | Input Tokens | Relative Cost |
+|-----|-----------|---------|
+| 10 tasks in a single session | ~50,000 | High |
+| New session per task | ~15,000 | Low |
+| Periodic `/compact` | ~25,000 | Medium |
+
+### Recommended Practices
+
+- Do start a new session for new tasks
+- Do use `/compact` every 20-30 turns
+- Do use `@filename` to reference files
+- Do keep prompts concise
+
+### Avoid
+
+- Don't handle multiple unrelated tasks in the same session
+- Don't go beyond 30 turns without cleanup
+- Don't repeatedly paste known code
+
+---
+
+**More help**: [Quick Start Guide](./quickstart.md)

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

@@ -0,0 +1,164 @@
+# Web UI
+
+CodeBuddy Code provides a built-in Web UI that offers a full-featured browser interface for interacting with the Agent. When you start CodeBuddy Code in serve mode or enable Remote Control, the Web UI is automatically available.
+
+## Overview
+
+The Web UI provides the same core capabilities as the terminal interface, with a visual layout optimized for browsers:
+
+- **Chat**: Send messages, view conversations, and monitor tool execution in real time
+- **Terminal**: Embedded terminal with split-pane support (up to 4 panels)
+- **Instances**: Manage and switch between multiple CodeBuddy Code instances
+- **Remote Control**: Connect WeChat and WeCom channels
+- **Tasks**: Browse and create scheduled tasks from templates
+- **Plugins**: Manage plugin installations and marketplaces
+- **Settings**: Configure theme, language, model, and permission mode
+- **Documentation**: Browse CLI documentation with full-text search
+- **API Reference**: View the interactive Swagger UI for HTTP API exploration
+
+## Accessing the Web UI
+
+### Method 1: Serve Mode
+
+Start CodeBuddy Code with the `--serve` flag:
+
+```bash
+codebuddy --serve --port 7890
+```
+
+Then open in your browser:
+
+```
+http://127.0.0.1:7890
+```
+
+### Method 2: Remote Control
+
+In an existing CodeBuddy Code session, start the Gateway:
+
+```
+/gateway
+```
+
+The terminal displays a QR code and URL. Scan the QR code with your phone or open the URL in any browser. See the [Remote Control](remote-control.md) documentation for details.
+
+## Authentication
+
+The Web UI supports two authentication modes:
+
+| Mode | Setting | Description |
+|:-----|:--------|:-----------|
+| No Auth (default) | `CODEBUDDY_GATEWAY_AUTH=none` | No password required |
+| Password | `CODEBUDDY_GATEWAY_AUTH=password` | Password shown in terminal on startup |
+
+Authentication methods (any one is sufficient):
+
+- **URL parameter**: `?password=xxx` — auto-login via URL
+- **Login page**: Enter the password displayed in the terminal
+- **Bearer token**: `Authorization: Bearer <password>` for API access
+
+Configure in `~/.codebuddy/settings.json`:
+
+```json
+{
+  "gateway.auth": "none"
+}
+```
+
+## Features
+
+### Chat View
+
+The default view for conversing with the Agent. Key features:
+
+- **Rich message rendering**: Markdown, syntax-highlighted code blocks, tables, and images
+- **Tool execution display**: See tool calls, their parameters, and results inline
+- **Permission management**: Approve or deny tool permissions directly in the browser
+- **Question panels**: Answer multi-choice questions from the Agent
+- **Task progress**: Monitor background tasks and team progress in real time
+- **Session management**: Create new chats, browse history, and switch sessions
+
+### Terminal View
+
+An embedded terminal powered by xterm.js:
+
+- **Split panes**: Split horizontally or vertically, up to 4 panels
+- **Independent sessions**: Each panel has its own PTY session
+- **Persistent connections**: Terminal sessions survive page refreshes
+- **Resize support**: Panels auto-resize when the window changes
+
+### Documentation View
+
+Browse the CLI documentation directly in the Web UI:
+
+- **Full-text search**: Search across all documents with MiniSearch
+- **Multi-language**: Automatically follows the UI language setting (Chinese/English)
+- **Table of contents**: Auto-generated from document headings, with scroll spy
+- **Internal navigation**: Document links navigate within the viewer (SPA)
+- **API Reference**: Quick link to the interactive Swagger UI at `/api/docs`
+
+### Instance Manager
+
+Manage multiple CodeBuddy Code instances:
+
+- **Instance list**: View all running instances with their working directories and status
+- **Quick switch**: Switch between instances with a single click
+- **Manual add**: Add remote instances by URL
+- **Tunnel support**: Access instances through Cloudflare Tunnel
+
+### Settings
+
+- **Theme**: Light, Dark, or System (auto-detect)
+- **Language**: Chinese, English, or System (auto-detect)
+- **Model**: Select the AI model from available options
+- **Permission mode**: Choose between Default, Accept Edits, Bypass Permissions, or Plan mode
+
+## API Reference
+
+When the HTTP server is running, an interactive API explorer is available at:
+
+```
+http://127.0.0.1:{PORT}/api/docs
+```
+
+This provides a Swagger UI where you can:
+
+- Browse all available REST API endpoints
+- View request/response schemas
+- Try out API calls directly from the browser
+- Download the OpenAPI 3.1 specification at `/api/openapi.json`
+
+See the [HTTP API Documentation](http-api.md) for the complete API reference.
+
+## Mobile Support
+
+The Web UI is fully responsive and works on mobile devices:
+
+- **Sidebar**: Collapses to a slide-out drawer on small screens
+- **PWA support**: Add to home screen for a native app-like experience
+- **Touch-friendly**: All interactions optimized for touch input
+- **QR code access**: Scan from the terminal to open on your phone instantly
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|:---------|:-------|
+| `Enter` | Send message |
+| `Shift+Enter` | New line in input |
+| `Escape` | Stop running agent |
+
+## Technical Details
+
+- **Framework**: React 18 with Zustand for state management
+- **Communication**: ACP protocol over HTTP/SSE (not WebSocket)
+- **Styling**: Tailwind CSS with CSS variable theming
+- **Terminal**: xterm.js with fit addon
+- **Search**: MiniSearch for client-side full-text search
+- **Markdown**: react-markdown with remark-gfm and syntax highlighting
+
+## Related
+
+- [Remote Control](remote-control.md) — Start the Web UI via Gateway and Tunnel
+- [HTTP API](http-api.md) — Complete REST API documentation
+- [ACP Protocol](acp.md) — Agent Client Protocol for IDE integration
+- [Settings](settings.md) — Configuration options