mirror of
https://github.com/QwenLM/qwen-code.git
synced 2025-12-20 16:57:46 +00:00
Merge branch 'main' into chore/sync-gemini-cli-v0.3.4
This commit is contained in:
mingholy.lmh
@@ -4,7 +4,7 @@ Your uninstall method depends on how you ran the CLI. Follow the instructions fo
|
||||
|
||||
## Method 1: Using npx
|
||||
|
||||
npx runs packages from a temporary cache without a permanent installation. To "uninstall" the CLI, you must clear this cache, which will remove gemini-cli and any other packages previously executed with npx.
|
||||
npx runs packages from a temporary cache without a permanent installation. To "uninstall" the CLI, you must clear this cache, which will remove qwen-code and any other packages previously executed with npx.
|
||||
|
||||
The npx cache is a directory named `_npx` inside your main npm cache folder. You can find your npm cache path by running `npm config get cache`.
|
||||
|
||||
|
||||
@@ -35,6 +35,17 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
- **Description:** Clear the terminal screen, including the visible session history and scrollback within the CLI. The underlying session data (for history recall) might be preserved depending on the exact implementation, but the visual display is cleared.
|
||||
- **Keyboard shortcut:** Press **Ctrl+L** at any time to perform a clear action.
|
||||
|
||||
- **`/summary`**
|
||||
- **Description:** Generate a comprehensive project summary from the current conversation history and save it to `.qwen/PROJECT_SUMMARY.md`. This summary includes the overall goal, key knowledge, recent actions, and current plan, making it perfect for resuming work in future sessions.
|
||||
- **Usage:** `/summary`
|
||||
- **Features:**
|
||||
- Analyzes the entire conversation history to extract important context
|
||||
- Creates a structured markdown summary with sections for goals, knowledge, actions, and plans
|
||||
- Automatically saves to `.qwen/PROJECT_SUMMARY.md` in your project root
|
||||
- Shows progress indicators during generation and saving
|
||||
- Integrates with the Welcome Back feature for seamless session resumption
|
||||
- **Note:** This command requires an active conversation with at least 2 messages to generate a meaningful summary.
|
||||
|
||||
- **`/compress`**
|
||||
- **Description:** Replace the entire chat context with a summary. This saves on tokens used for future tasks while retaining a high level summary of what has happened.
|
||||
|
||||
@@ -116,6 +127,20 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
- **`/about`**
|
||||
- **Description:** Show version info. Please share this information when filing issues.
|
||||
|
||||
- **`/agents`**
|
||||
- **Description:** Manage specialized AI subagents for focused tasks. Subagents are independent AI assistants configured with specific expertise and tool access.
|
||||
- **Sub-commands:**
|
||||
- **`create`**:
|
||||
- **Description:** Launch an interactive wizard to create a new subagent. The wizard guides you through location selection, AI-powered prompt generation, tool selection, and visual customization.
|
||||
- **Usage:** `/agents create`
|
||||
- **`manage`**:
|
||||
- **Description:** Open an interactive management dialog to view, edit, and delete existing subagents. Shows both project-level and user-level agents.
|
||||
- **Usage:** `/agents manage`
|
||||
- **Storage Locations:**
|
||||
- **Project-level:** `.qwen/agents/` (shared with team, takes precedence)
|
||||
- **User-level:** `~/.qwen/agents/` (personal agents, available across projects)
|
||||
- **Note:** For detailed information on creating and managing subagents, see the [Subagents documentation](../subagents.md).
|
||||
|
||||
- [**`/tools`**](../tools/index.md)
|
||||
- **Description:** Display a list of tools that are currently available within Qwen Code.
|
||||
- **Usage:** `/tools [desc]`
|
||||
@@ -128,8 +153,18 @@ Slash commands provide meta-level control over the CLI itself.
|
||||
- **`/privacy`**
|
||||
- **Description:** Display the Privacy Notice and allow users to select whether they consent to the collection of their data for service improvement purposes.
|
||||
|
||||
- **`/quit-confirm`**
|
||||
- **Description:** Show a confirmation dialog before exiting Qwen Code, allowing you to choose how to handle your current session.
|
||||
- **Usage:** `/quit-confirm`
|
||||
- **Features:**
|
||||
- **Quit immediately:** Exit without saving anything (equivalent to `/quit`)
|
||||
- **Generate summary and quit:** Create a project summary using `/summary` before exiting
|
||||
- **Save conversation and quit:** Save the current conversation with an auto-generated tag before exiting
|
||||
- **Keyboard shortcut:** Press **Ctrl+C** twice to trigger the quit confirmation dialog
|
||||
- **Note:** This command is automatically triggered when you press Ctrl+C once, providing a safety mechanism to prevent accidental exits.
|
||||
|
||||
- **`/quit`** (or **`/exit`**)
|
||||
- **Description:** Exit Qwen Code.
|
||||
- **Description:** Exit Qwen Code immediately without any confirmation dialog.
|
||||
|
||||
- **`/vim`**
|
||||
- **Description:** Toggle vim mode on or off. When vim mode is enabled, the input area supports vim-style navigation and editing commands in both NORMAL and INSERT modes.
|
||||
|
||||
@@ -27,6 +27,7 @@ Qwen Code uses JSON settings files for persistent configuration. There are four
|
||||
- **Project settings file:**
|
||||
- **Location:** `.qwen/settings.json` within your project's root directory.
|
||||
- **Scope:** Applies only when running Qwen Code from that specific project. Project settings override user settings.
|
||||
|
||||
- **System settings file:**
|
||||
- **Location:** `/etc/qwen-code/settings.json` (Linux), `C:\ProgramData\qwen-code\settings.json` (Windows) or `/Library/Application Support/QwenCode/settings.json` (macOS). The path can be overridden using the `QWEN_CODE_SYSTEM_SETTINGS_PATH` environment variable.
|
||||
- **Scope:** Applies to all Qwen Code sessions on the system, for all users. System settings override user and project settings. May be useful for system administrators at enterprises to have controls over users' Qwen Code setups.
|
||||
@@ -404,37 +405,16 @@ The CLI automatically loads environment variables from an `.env` file. The loadi
|
||||
|
||||
**Environment Variable Exclusion:** Some environment variables (like `DEBUG` and `DEBUG_MODE`) are automatically excluded from project `.env` files by default to prevent interference with the CLI behavior. Variables from `.qwen/.env` files are never excluded. You can customize this behavior using the `excludedProjectEnvVars` setting in your `settings.json` file.
|
||||
|
||||
**To avoid confusion, we will reorganize all available environment variables in an upcoming release.**
|
||||
|
||||
- **`GEMINI_API_KEY`**:
|
||||
- Your API key for the Gemini API.
|
||||
- **`OPENAI_API_KEY`**:
|
||||
- One of several available [authentication methods](./authentication.md).
|
||||
- Set this in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or an `.env` file.
|
||||
- **`GEMINI_MODEL`**:
|
||||
- Specifies the default Gemini model to use.
|
||||
- **`OPENAI_BASE_URL`**:
|
||||
- One of several available [authentication methods](./authentication.md).
|
||||
- Set this in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or an `.env` file.
|
||||
- **`OPENAI_MODEL`**:
|
||||
- Specifies the default OPENAI model to use.
|
||||
- Overrides the hardcoded default
|
||||
- Example: `export GEMINI_MODEL="gemini-2.5-flash"`
|
||||
- **`GOOGLE_API_KEY`**:
|
||||
- Your Google Cloud API key.
|
||||
- Required for using Vertex AI in express mode.
|
||||
- Ensure you have the necessary permissions.
|
||||
- Example: `export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`.
|
||||
- **`GOOGLE_CLOUD_PROJECT`**:
|
||||
- Your Google Cloud Project ID.
|
||||
- Required for using Code Assist or Vertex AI.
|
||||
- If using Vertex AI, ensure you have the necessary permissions in this project.
|
||||
- **Cloud Shell Note:** When running in a Cloud Shell environment, this variable defaults to a special project allocated for Cloud Shell users. If you have `GOOGLE_CLOUD_PROJECT` set in your global environment in Cloud Shell, it will be overridden by this default. To use a different project in Cloud Shell, you must define `GOOGLE_CLOUD_PROJECT` in a `.env` file.
|
||||
- Example: `export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`.
|
||||
- **`GOOGLE_APPLICATION_CREDENTIALS`** (string):
|
||||
- **Description:** The path to your Google Application Credentials JSON file.
|
||||
- **Example:** `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"`
|
||||
- **`OTLP_GOOGLE_CLOUD_PROJECT`**:
|
||||
- Your Google Cloud Project ID for Telemetry in Google Cloud
|
||||
- Example: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`.
|
||||
- **`GOOGLE_CLOUD_LOCATION`**:
|
||||
- Your Google Cloud Project Location (e.g., us-central1).
|
||||
- Required for using Vertex AI in non express mode.
|
||||
- Example: `export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`.
|
||||
- Example: `export OPENAI_MODEL="qwen3-coder-plus"`
|
||||
- **`GEMINI_SANDBOX`**:
|
||||
- Alternative to the `sandbox` setting in `settings.json`.
|
||||
- Accepts `true`, `false`, `docker`, `podman`, or a custom command string.
|
||||
@@ -464,7 +444,7 @@ The CLI automatically loads environment variables from an `.env` file. The loadi
|
||||
Arguments passed directly when running the CLI can override other configurations for that specific session.
|
||||
|
||||
- **`--model <model_name>`** (**`-m <model_name>`**):
|
||||
- Specifies the model to use for this session.
|
||||
- Specifies the Qwen model to use for this session.
|
||||
- Example: `npm start -- --model qwen3-coder-plus`
|
||||
- **`--prompt <your_prompt>`** (**`-p <your_prompt>`**):
|
||||
- Used to pass a prompt directly to the command. This invokes Qwen Code in a non-interactive mode.
|
||||
@@ -537,7 +517,7 @@ Arguments passed directly when running the CLI can override other configurations
|
||||
|
||||
While not strictly configuration for the CLI's _behavior_, context files (defaulting to `QWEN.md` but configurable via the `contextFileName` setting) are crucial for configuring the _instructional context_ (also referred to as "memory"). This powerful feature allows you to give project-specific instructions, coding style guides, or any relevant background information to the AI, making its responses more tailored and accurate to your needs. The CLI includes UI elements, such as an indicator in the footer showing the number of loaded context files, to keep you informed about the active context.
|
||||
|
||||
- **Purpose:** These Markdown files contain instructions, guidelines, or context that you want the model to be aware of during your interactions. The system is designed to manage this instructional context hierarchically.
|
||||
- **Purpose:** These Markdown files contain instructions, guidelines, or context that you want the Qwen model to be aware of during your interactions. The system is designed to manage this instructional context hierarchically.
|
||||
|
||||
### Example Context File Content (e.g., `QWEN.md`)
|
||||
|
||||
@@ -649,3 +629,11 @@ You can opt out of usage statistics collection at any time by setting the `usage
|
||||
```
|
||||
|
||||
Note: When usage statistics are enabled, events are sent to an Alibaba Cloud RUM collection endpoint.
|
||||
|
||||
- **`enableWelcomeBack`** (boolean):
|
||||
- **Description:** Show welcome back dialog when returning to a project with conversation history.
|
||||
- **Default:** `true`
|
||||
- **Category:** UI
|
||||
- **Requires Restart:** No
|
||||
- **Example:** `"enableWelcomeBack": false`
|
||||
- **Details:** When enabled, Qwen Code will automatically detect if you're returning to a project with a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. This feature integrates with the `/chat summary` command and quit confirmation dialog. See the [Welcome Back documentation](./welcome-back.md) for more details.
|
||||
|
||||
@@ -10,6 +10,7 @@ Within Qwen Code, `packages/cli` is the frontend for users to send and receive p
|
||||
- **[Token Caching](./token-caching.md):** Optimize API costs through token caching.
|
||||
- **[Themes](./themes.md)**: A guide to customizing the CLI's appearance with different themes.
|
||||
- **[Tutorials](tutorials.md)**: A tutorial showing how to use Qwen Code to automate a development task.
|
||||
- **[Welcome Back](./welcome-back.md)**: Learn about the Welcome Back feature that helps you resume work seamlessly across sessions.
|
||||
|
||||
## Non-interactive mode
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ Qwen Code automatically optimizes API costs through token caching when using API
|
||||
|
||||
**Token caching is available for:**
|
||||
|
||||
- API key users (Gemini API key)
|
||||
- API key users (Qwen API key)
|
||||
- Vertex AI users (with project and location setup)
|
||||
|
||||
**Token caching is not available for:**
|
||||
|
||||
133
docs/cli/welcome-back.md
Normal file
133
docs/cli/welcome-back.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# Welcome Back Feature
|
||||
|
||||
The Welcome Back feature helps you seamlessly resume your work by automatically detecting when you return to a project with existing conversation history and offering to continue from where you left off.
|
||||
|
||||
## Overview
|
||||
|
||||
When you start Qwen Code in a project directory that contains a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`), the Welcome Back dialog will automatically appear, giving you the option to either start fresh or continue your previous conversation.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Automatic Detection
|
||||
|
||||
The Welcome Back feature automatically detects:
|
||||
|
||||
- **Project Summary File:** Looks for `.qwen/PROJECT_SUMMARY.md` in your current project directory
|
||||
- **Conversation History:** Checks if there's meaningful conversation history to resume
|
||||
- **Settings:** Respects your `enableWelcomeBack` setting (enabled by default)
|
||||
|
||||
### Welcome Back Dialog
|
||||
|
||||
When a project summary is found, you'll see a dialog with:
|
||||
|
||||
- **Last Updated Time:** Shows when the summary was last generated
|
||||
- **Overall Goal:** Displays the main objective from your previous session
|
||||
- **Current Plan:** Shows task progress with status indicators:
|
||||
- `[DONE]` - Completed tasks
|
||||
- `[IN PROGRESS]` - Currently working on
|
||||
- `[TODO]` - Planned tasks
|
||||
- **Task Statistics:** Summary of total tasks, completed, in progress, and pending
|
||||
|
||||
### Options
|
||||
|
||||
You have two choices when the Welcome Back dialog appears:
|
||||
|
||||
1. **Start new chat session**
|
||||
- Closes the dialog and begins a fresh conversation
|
||||
- No previous context is loaded
|
||||
|
||||
2. **Continue previous conversation**
|
||||
- Automatically fills the input with: `@.qwen/PROJECT_SUMMARY.md, Based on our previous conversation, Let's continue?`
|
||||
- Loads the project summary as context for the AI
|
||||
- Allows you to seamlessly pick up where you left off
|
||||
|
||||
## Configuration
|
||||
|
||||
### Enable/Disable Welcome Back
|
||||
|
||||
You can control the Welcome Back feature through settings:
|
||||
|
||||
**Via Settings Dialog:**
|
||||
|
||||
1. Run `/settings` in Qwen Code
|
||||
2. Find "Enable Welcome Back" in the UI category
|
||||
3. Toggle the setting on/off
|
||||
|
||||
**Via Settings File:**
|
||||
Add to your `.qwen/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enableWelcomeBack": true
|
||||
}
|
||||
```
|
||||
|
||||
**Settings Locations:**
|
||||
|
||||
- **User settings:** `~/.qwen/settings.json` (affects all projects)
|
||||
- **Project settings:** `.qwen/settings.json` (project-specific)
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
- **Escape:** Close the Welcome Back dialog (defaults to "Start new chat session")
|
||||
|
||||
## Integration with Other Features
|
||||
|
||||
### Project Summary Generation
|
||||
|
||||
The Welcome Back feature works seamlessly with the `/chat summary` command:
|
||||
|
||||
1. **Generate Summary:** Use `/chat summary` to create a project summary
|
||||
2. **Automatic Detection:** Next time you start Qwen Code in this project, Welcome Back will detect the summary
|
||||
3. **Resume Work:** Choose to continue and the summary will be loaded as context
|
||||
|
||||
### Quit Confirmation
|
||||
|
||||
When exiting with `/quit-confirm` and choosing "Generate summary and quit":
|
||||
|
||||
1. A project summary is automatically created
|
||||
2. Next session will trigger the Welcome Back dialog
|
||||
3. You can seamlessly continue your work
|
||||
|
||||
## File Structure
|
||||
|
||||
The Welcome Back feature creates and uses:
|
||||
|
||||
```
|
||||
your-project/
|
||||
├── .qwen/
|
||||
│ └── PROJECT_SUMMARY.md # Generated project summary
|
||||
```
|
||||
|
||||
### PROJECT_SUMMARY.md Format
|
||||
|
||||
The generated summary follows this structure:
|
||||
|
||||
```markdown
|
||||
# Project Summary
|
||||
|
||||
## Overall Goal
|
||||
|
||||
<!-- Single, concise sentence describing the high-level objective -->
|
||||
|
||||
## Key Knowledge
|
||||
|
||||
<!-- Crucial facts, conventions, and constraints -->
|
||||
<!-- Includes: technology choices, architecture decisions, user preferences -->
|
||||
|
||||
## Recent Actions
|
||||
|
||||
<!-- Summary of significant recent work and outcomes -->
|
||||
<!-- Includes: accomplishments, discoveries, recent changes -->
|
||||
|
||||
## Current Plan
|
||||
|
||||
<!-- The current development roadmap and next steps -->
|
||||
<!-- Uses status markers: [DONE], [IN PROGRESS], [TODO] -->
|
||||
|
||||
---
|
||||
|
||||
## Summary Metadata
|
||||
|
||||
**Update time**: 2025-01-10T15:30:00.000Z
|
||||
```
|
||||
@@ -1,6 +1,6 @@
|
||||
# IDE Integration
|
||||
|
||||
Gemini CLI can integrate with your IDE to provide a more seamless and context-aware experience. This integration allows the CLI to understand your workspace better and enables powerful features like native in-editor diffing.
|
||||
Qwen Code can integrate with your IDE to provide a more seamless and context-aware experience. This integration allows the CLI to understand your workspace better and enables powerful features like native in-editor diffing.
|
||||
|
||||
Currently, the only supported IDE is [Visual Studio Code](https://code.visualstudio.com/) and other editors that support VS Code extensions.
|
||||
|
||||
@@ -11,13 +11,13 @@ Currently, the only supported IDE is [Visual Studio Code](https://code.visualstu
|
||||
- Your active cursor position.
|
||||
- Any text you have selected (up to a 16KB limit; longer selections will be truncated).
|
||||
|
||||
- **Native Diffing:** When Gemini suggests code modifications, you can view the changes directly within your IDE's native diff viewer. This allows you to review, edit, and accept or reject the suggested changes seamlessly.
|
||||
- **Native Diffing:** When Qwen suggests code modifications, you can view the changes directly within your IDE's native diff viewer. This allows you to review, edit, and accept or reject the suggested changes seamlessly.
|
||||
|
||||
- **VS Code Commands:** You can access Gemini CLI features directly from the VS Code Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`):
|
||||
- `Gemini CLI: Run`: Starts a new Gemini CLI session in the integrated terminal.
|
||||
- `Gemini CLI: Accept Diff`: Accepts the changes in the active diff editor.
|
||||
- `Gemini CLI: Close Diff Editor`: Rejects the changes and closes the active diff editor.
|
||||
- `Gemini CLI: View Third-Party Notices`: Displays the third-party notices for the extension.
|
||||
- **VS Code Commands:** You can access Qwen Code features directly from the VS Code Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`):
|
||||
- `Qwen Code: Run`: Starts a new Qwen Code session in the integrated terminal.
|
||||
- `Qwen Code: Accept Diff`: Accepts the changes in the active diff editor.
|
||||
- `Qwen Code: Close Diff Editor`: Rejects the changes and closes the active diff editor.
|
||||
- `Qwen Code: View Third-Party Notices`: Displays the third-party notices for the extension.
|
||||
|
||||
## Installation and Setup
|
||||
|
||||
@@ -25,11 +25,11 @@ There are three ways to set up the IDE integration:
|
||||
|
||||
### 1. Automatic Nudge (Recommended)
|
||||
|
||||
When you run Gemini CLI inside a supported editor, it will automatically detect your environment and prompt you to connect. Answering "Yes" will automatically run the necessary setup, which includes installing the companion extension and enabling the connection.
|
||||
When you run Qwen Code inside a supported editor, it will automatically detect your environment and prompt you to connect. Answering "Yes" will automatically run the necessary setup, which includes installing the companion extension and enabling the connection.
|
||||
|
||||
### 2. Manual Installation from CLI
|
||||
|
||||
If you previously dismissed the prompt or want to install the extension manually, you can run the following command inside Gemini CLI:
|
||||
If you previously dismissed the prompt or want to install the extension manually, you can run the following command inside Qwen Code:
|
||||
|
||||
```
|
||||
/ide install
|
||||
@@ -41,8 +41,8 @@ This will find the correct extension for your IDE and install it.
|
||||
|
||||
You can also install the extension directly from a marketplace.
|
||||
|
||||
- **For Visual Studio Code:** Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=google.gemini-cli-vscode-ide-companion).
|
||||
- **For VS Code Forks:** To support forks of VS Code, the extension is also published on the [Open VSX Registry](https://open-vsx.org/extension/google/gemini-cli-vscode-ide-companion). Follow your editor's instructions for installing extensions from this registry.
|
||||
- **For Visual Studio Code:** Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion).
|
||||
- **For VS Code Forks:** To support forks of VS Code, the extension is also published on the [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion). Follow your editor's instructions for installing extensions from this registry.
|
||||
|
||||
> NOTE:
|
||||
> The "Gemini CLI Companion" extension may appear towards the bottom of search results. If you don't see it immediately, try scrolling down or sorting by "Newly Published".
|
||||
@@ -64,7 +64,7 @@ You can control the IDE integration from within the CLI:
|
||||
/ide disable
|
||||
```
|
||||
|
||||
When enabled, Gemini CLI will automatically attempt to connect to the IDE companion extension.
|
||||
When enabled, Qwen Code will automatically attempt to connect to the IDE companion extension.
|
||||
|
||||
### Checking the Status
|
||||
|
||||
@@ -86,14 +86,14 @@ When you ask Gemini to modify a file, it can open a diff view directly in your e
|
||||
|
||||
- Click the **checkmark icon** in the diff editor's title bar.
|
||||
- Save the file (e.g., with `Cmd+S` or `Ctrl+S`).
|
||||
- Open the Command Palette and run **Gemini CLI: Accept Diff**.
|
||||
- Open the Command Palette and run **Qwen Code: Accept Diff**.
|
||||
- Respond with `yes` in the CLI when prompted.
|
||||
|
||||
**To reject a diff**, you can:
|
||||
|
||||
- Click the **'x' icon** in the diff editor's title bar.
|
||||
- Close the diff editor tab.
|
||||
- Open the Command Palette and run **Gemini CLI: Close Diff Editor**.
|
||||
- Open the Command Palette and run **Qwen Code: Close Diff Editor**.
|
||||
- Respond with `no` in the CLI when prompted.
|
||||
|
||||
You can also **modify the suggested changes** directly in the diff view before accepting them.
|
||||
@@ -102,10 +102,10 @@ If you select ‘Yes, allow always’ in the CLI, changes will no longer show up
|
||||
|
||||
## Using with Sandboxing
|
||||
|
||||
If you are using Gemini CLI within a sandbox, please be aware of the following:
|
||||
If you are using Qwen Code within a sandbox, please be aware of the following:
|
||||
|
||||
- **On macOS:** The IDE integration requires network access to communicate with the IDE companion extension. You must use a Seatbelt profile that allows network access.
|
||||
- **In a Docker Container:** If you run Gemini CLI inside a Docker (or Podman) container, the IDE integration can still connect to the VS Code extension running on your host machine. The CLI is configured to automatically find the IDE server on `host.docker.internal`. No special configuration is usually required, but you may need to ensure your Docker networking setup allows connections from the container to the host.
|
||||
- **In a Docker Container:** If you run Qwen Code inside a Docker (or Podman) container, the IDE integration can still connect to the VS Code extension running on your host machine. The CLI is configured to automatically find the IDE server on `host.docker.internal`. No special configuration is usually required, but you may need to ensure your Docker networking setup allows connections from the container to the host.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -113,10 +113,10 @@ If you encounter issues with IDE integration, here are some common error message
|
||||
|
||||
### Connection Errors
|
||||
|
||||
- **Message:** `🔴 Disconnected: Failed to connect to IDE companion extension in [IDE Name]. Please ensure the extension is running. To install the extension, run /ide install.`
|
||||
- **Cause:** Gemini CLI could not find the necessary environment variables (`GEMINI_CLI_IDE_WORKSPACE_PATH` or `GEMINI_CLI_IDE_SERVER_PORT`) to connect to the IDE. This usually means the IDE companion extension is not running or did not initialize correctly.
|
||||
- **Message:** `🔴 Disconnected: Failed to connect to IDE companion extension for [IDE Name]. Please ensure the extension is running and try restarting your terminal. To install the extension, run /ide install.`
|
||||
- **Cause:** Qwen Code could not find the necessary environment variables (`QWEN_CODE_IDE_WORKSPACE_PATH` or `QWEN_CODE_IDE_SERVER_PORT`) to connect to the IDE. This usually means the IDE companion extension is not running or did not initialize correctly.
|
||||
- **Solution:**
|
||||
1. Make sure you have installed the **Gemini CLI Companion** extension in your IDE and that it is enabled.
|
||||
1. Make sure you have installed the **Qwen Code Companion** extension in your IDE and that it is enabled.
|
||||
2. Open a new terminal window in your IDE to ensure it picks up the correct environment.
|
||||
|
||||
- **Message:** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable`
|
||||
@@ -125,8 +125,8 @@ If you encounter issues with IDE integration, here are some common error message
|
||||
|
||||
### Configuration Errors
|
||||
|
||||
- **Message:** `🔴 Disconnected: Directory mismatch. Gemini CLI is running in a different location than the open workspace in [IDE Name]. Please run the CLI from one of the following directories: [List of directories]`
|
||||
- **Cause:** The CLI's current working directory is outside the workspace you have open in your IDE.
|
||||
- **Message:** `🔴 Disconnected: Directory mismatch. Qwen Code is running in a different location than the open workspace in [IDE Name]. Please run the CLI from the same directory as your project's root folder.`
|
||||
- **Cause:** The CLI's current working directory is outside the folder or workspace you have open in your IDE.
|
||||
- **Solution:** `cd` into the same directory that is open in your IDE and restart the CLI.
|
||||
|
||||
- **Message:** `🔴 Disconnected: To use this feature, please open a workspace folder in [IDE Name] and try again.`
|
||||
@@ -135,10 +135,10 @@ If you encounter issues with IDE integration, here are some common error message
|
||||
|
||||
### General Errors
|
||||
|
||||
- **Message:** `IDE integration is not supported in your current environment. To use this feature, run Gemini CLI in one of these supported IDEs: [List of IDEs]`
|
||||
- **Cause:** You are running Gemini CLI in a terminal or environment that is not a supported IDE.
|
||||
- **Solution:** Run Gemini CLI from the integrated terminal of a supported IDE, like VS Code.
|
||||
- **Message:** `IDE integration is not supported in your current environment. To use this feature, run Qwen Code in one of these supported IDEs: [List of IDEs]`
|
||||
- **Cause:** You are running Qwen Code in a terminal or environment that is not a supported IDE.
|
||||
- **Solution:** Run Qwen Code from the integrated terminal of a supported IDE, like VS Code.
|
||||
|
||||
- **Message:** `No installer is available for IDE. Please install the Gemini CLI Companion extension manually from the marketplace.`
|
||||
- **Cause:** You ran `/ide install`, but the CLI does not have an automated installer for your specific IDE.
|
||||
- **Solution:** Open your IDE's extension marketplace, search for "Gemini CLI Companion", and [install it manually](#3-manual-installation-from-a-marketplace).
|
||||
- **Solution:** Open your IDE's extension marketplace, search for "Qwen Code Companion", and install it manually.
|
||||
|
||||
@@ -31,6 +31,7 @@ This documentation is organized into the following sections:
|
||||
- **[Web Fetch Tool](./tools/web-fetch.md):** Documentation for the `web_fetch` tool.
|
||||
- **[Web Search Tool](./tools/web-search.md):** Documentation for the `web_search` tool.
|
||||
- **[Memory Tool](./tools/memory.md):** Documentation for the `save_memory` tool.
|
||||
- **[Subagents](./subagents.md):** Specialized AI assistants for focused tasks with comprehensive management, configuration, and usage guidance.
|
||||
- **[Contributing & Development Guide](../CONTRIBUTING.md):** Information for contributors and developers, including setup, building, testing, and coding conventions.
|
||||
- **[NPM](./npm.md):** Details on how the project's packages are structured
|
||||
- **[Troubleshooting Guide](./troubleshooting.md):** Find solutions to common problems and FAQs.
|
||||
|
||||
@@ -148,7 +148,7 @@ This command will do the following:
|
||||
3. Create the package tarballs that would be published to npm.
|
||||
4. Print a summary of the packages that would be published.
|
||||
|
||||
You can then inspect the generated tarballs to ensure that they contain the correct files and that the `package.json` files have been updated correctly. The tarballs will be created in the root of each package's directory (e.g., `packages/cli/google-gemini-cli-0.1.6.tgz`).
|
||||
You can then inspect the generated tarballs to ensure that they contain the correct files and that the `package.json` files have been updated correctly. The tarballs will be created in the root of each package's directory (e.g., `packages/cli/qwen-code-0.1.6.tgz`).
|
||||
|
||||
By performing a dry run, you can be confident that your changes to the packaging process are correct and that the packages will be published successfully.
|
||||
|
||||
@@ -187,7 +187,7 @@ This is the most critical stage where files are moved and transformed into their
|
||||
- File movement: packages/cli/package.json -> (in-memory transformation) -> `bundle`/package.json
|
||||
- Why: The final package.json must be different from the one used in development. Key changes include:
|
||||
- Removing devDependencies.
|
||||
- Removing workspace-specific "dependencies": { "@gemini-cli/core": "workspace:\*" } and ensuring the core code is
|
||||
- Removing workspace-specific "dependencies": { "@qwen-code/core": "workspace:\*" } and ensuring the core code is
|
||||
bundled directly into the final JavaScript file.
|
||||
- Ensuring the bin, main, and files fields point to the correct locations within the final package structure.
|
||||
|
||||
@@ -277,4 +277,4 @@ This tells NPM that any folder inside the `packages` directory is a separate pac
|
||||
|
||||
- **Simplified Dependency Management**: Running `npm install` from the root of the project will install all dependencies for all packages in the workspace and link them together. This means you don't need to run `npm install` in each package's directory.
|
||||
- **Automatic Linking**: Packages within the workspace can depend on each other. When you run `npm install`, NPM will automatically create symlinks between the packages. This means that when you make changes to one package, the changes are immediately available to other packages that depend on it.
|
||||
- **Simplified Script Execution**: You can run scripts in any package from the root of the project using the `--workspace` flag. For example, to run the `build` script in the `cli` package, you can run `npm run build --workspace @google/gemini-cli`.
|
||||
- **Simplified Script Execution**: You can run scripts in any package from the root of the project using the `--workspace` flag. For example, to run the `build` script in the `cli` package, you can run `npm run build --workspace @qwen-code/qwen-code`.
|
||||
|
||||
469
docs/subagents.md
Normal file
469
docs/subagents.md
Normal file
@@ -0,0 +1,469 @@
|
||||
# Subagents
|
||||
|
||||
Subagents are specialized AI assistants that handle specific types of tasks within Qwen Code. They allow you to delegate focused work to AI agents that are configured with task-specific prompts, tools, and behaviors.
|
||||
|
||||
## What are Subagents?
|
||||
|
||||
Subagents are independent AI assistants that:
|
||||
|
||||
- **Specialize in specific tasks** - Each subagent is configured with a focused system prompt for particular types of work
|
||||
- **Have separate context** - They maintain their own conversation history, separate from your main chat
|
||||
- **Use controlled tools** - You can configure which tools each subagent has access to
|
||||
- **Work autonomously** - Once given a task, they work independently until completion or failure
|
||||
- **Provide detailed feedback** - You can see their progress, tool usage, and execution statistics in real-time
|
||||
|
||||
## Key Benefits
|
||||
|
||||
- **Task Specialization**: Create agents optimized for specific workflows (testing, documentation, refactoring, etc.)
|
||||
- **Context Isolation**: Keep specialized work separate from your main conversation
|
||||
- **Reusability**: Save and reuse agent configurations across projects and sessions
|
||||
- **Controlled Access**: Limit which tools each agent can use for security and focus
|
||||
- **Progress Visibility**: Monitor agent execution with real-time progress updates
|
||||
|
||||
## How Subagents Work
|
||||
|
||||
1. **Configuration**: You create subagent configurations that define their behavior, tools, and system prompts
|
||||
2. **Delegation**: The main AI can automatically delegate tasks to appropriate subagents
|
||||
3. **Execution**: Subagents work independently, using their configured tools to complete tasks
|
||||
4. **Results**: They return results and execution summaries back to the main conversation
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Quick Start
|
||||
|
||||
1. **Create your first subagent**:
|
||||
|
||||
```
|
||||
/agents create
|
||||
```
|
||||
|
||||
Follow the guided wizard to create a specialized agent.
|
||||
|
||||
2. **Manage existing agents**:
|
||||
|
||||
```
|
||||
/agents manage
|
||||
```
|
||||
|
||||
View and manage your configured subagents.
|
||||
|
||||
3. **Use subagents automatically**:
|
||||
Simply ask the main AI to perform tasks that match your subagents' specializations. The AI will automatically delegate appropriate work.
|
||||
|
||||
### Example Usage
|
||||
|
||||
```
|
||||
User: "Please write comprehensive tests for the authentication module"
|
||||
|
||||
AI: I'll delegate this to your testing specialist subagent.
|
||||
[Delegates to "testing-expert" subagent]
|
||||
[Shows real-time progress of test creation]
|
||||
[Returns with completed test files and execution summary]
|
||||
```
|
||||
|
||||
## Management
|
||||
|
||||
### CLI Commands
|
||||
|
||||
Subagents are managed through the `/agents` slash command and its subcommands:
|
||||
|
||||
#### `/agents create`
|
||||
|
||||
Creates a new subagent through a guided step wizard.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```
|
||||
/agents create
|
||||
```
|
||||
|
||||
#### `/agents manage`
|
||||
|
||||
Opens an interactive management dialog for viewing and managing existing subagents.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```
|
||||
/agents manage
|
||||
```
|
||||
|
||||
### Storage Locations
|
||||
|
||||
Subagents are stored as Markdown files in two locations:
|
||||
|
||||
- **Project-level**: `.qwen/agents/` (takes precedence)
|
||||
- **User-level**: `~/.qwen/agents/` (fallback)
|
||||
|
||||
This allows you to have both project-specific agents and personal agents that work across all projects.
|
||||
|
||||
### File Format
|
||||
|
||||
Subagents are configured using Markdown files with YAML frontmatter. This format is human-readable and easy to edit with any text editor.
|
||||
|
||||
#### Basic Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: agent-name
|
||||
description: Brief description of when and how to use this agent
|
||||
tools: tool1, tool2, tool3 # Optional
|
||||
---
|
||||
|
||||
System prompt content goes here.
|
||||
Multiple paragraphs are supported.
|
||||
You can use ${variable} templating for dynamic content.
|
||||
```
|
||||
|
||||
#### Example Usage
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: project-documenter
|
||||
description: Creates project documentation and README files
|
||||
---
|
||||
|
||||
You are a documentation specialist for the ${project_name} project.
|
||||
|
||||
Your task: ${task_description}
|
||||
|
||||
Working directory: ${current_directory}
|
||||
Generated on: ${timestamp}
|
||||
|
||||
Focus on creating clear, comprehensive documentation that helps both
|
||||
new contributors and end users understand the project.
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Development Workflow Agents
|
||||
|
||||
#### Testing Specialist
|
||||
|
||||
Perfect for comprehensive test creation and test-driven development.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: testing-expert
|
||||
description: Writes comprehensive unit tests, integration tests, and handles test automation with best practices
|
||||
tools: read_file, write_file, read_many_files, run_shell_command
|
||||
---
|
||||
|
||||
You are a testing specialist focused on creating high-quality, maintainable tests.
|
||||
|
||||
Your expertise includes:
|
||||
|
||||
- Unit testing with appropriate mocking and isolation
|
||||
- Integration testing for component interactions
|
||||
- Test-driven development practices
|
||||
- Edge case identification and comprehensive coverage
|
||||
- Performance and load testing when appropriate
|
||||
|
||||
For each testing task:
|
||||
|
||||
1. Analyze the code structure and dependencies
|
||||
2. Identify key functionality, edge cases, and error conditions
|
||||
3. Create comprehensive test suites with descriptive names
|
||||
4. Include proper setup/teardown and meaningful assertions
|
||||
5. Add comments explaining complex test scenarios
|
||||
6. Ensure tests are maintainable and follow DRY principles
|
||||
|
||||
Always follow testing best practices for the detected language and framework.
|
||||
Focus on both positive and negative test cases.
|
||||
```
|
||||
|
||||
**Use Cases:**
|
||||
|
||||
- "Write unit tests for the authentication service"
|
||||
- "Create integration tests for the payment processing workflow"
|
||||
- "Add test coverage for edge cases in the data validation module"
|
||||
|
||||
#### Documentation Writer
|
||||
|
||||
Specialized in creating clear, comprehensive documentation.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: documentation-writer
|
||||
description: Creates comprehensive documentation, README files, API docs, and user guides
|
||||
tools: read_file, write_file, read_many_files, web_search
|
||||
---
|
||||
|
||||
You are a technical documentation specialist for ${project_name}.
|
||||
|
||||
Your role is to create clear, comprehensive documentation that serves both
|
||||
developers and end users. Focus on:
|
||||
|
||||
**For API Documentation:**
|
||||
|
||||
- Clear endpoint descriptions with examples
|
||||
- Parameter details with types and constraints
|
||||
- Response format documentation
|
||||
- Error code explanations
|
||||
- Authentication requirements
|
||||
|
||||
**For User Documentation:**
|
||||
|
||||
- Step-by-step instructions with screenshots when helpful
|
||||
- Installation and setup guides
|
||||
- Configuration options and examples
|
||||
- Troubleshooting sections for common issues
|
||||
- FAQ sections based on common user questions
|
||||
|
||||
**For Developer Documentation:**
|
||||
|
||||
- Architecture overviews and design decisions
|
||||
- Code examples that actually work
|
||||
- Contributing guidelines
|
||||
- Development environment setup
|
||||
|
||||
Always verify code examples and ensure documentation stays current with
|
||||
the actual implementation. Use clear headings, bullet points, and examples.
|
||||
```
|
||||
|
||||
**Use Cases:**
|
||||
|
||||
- "Create API documentation for the user management endpoints"
|
||||
- "Write a comprehensive README for this project"
|
||||
- "Document the deployment process with troubleshooting steps"
|
||||
|
||||
#### Code Reviewer
|
||||
|
||||
Focused on code quality, security, and best practices.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Reviews code for best practices, security issues, performance, and maintainability
|
||||
tools: read_file, read_many_files
|
||||
---
|
||||
|
||||
You are an experienced code reviewer focused on quality, security, and maintainability.
|
||||
|
||||
Review criteria:
|
||||
|
||||
- **Code Structure**: Organization, modularity, and separation of concerns
|
||||
- **Performance**: Algorithmic efficiency and resource usage
|
||||
- **Security**: Vulnerability assessment and secure coding practices
|
||||
- **Best Practices**: Language/framework-specific conventions
|
||||
- **Error Handling**: Proper exception handling and edge case coverage
|
||||
- **Readability**: Clear naming, comments, and code organization
|
||||
- **Testing**: Test coverage and testability considerations
|
||||
|
||||
Provide constructive feedback with:
|
||||
|
||||
1. **Critical Issues**: Security vulnerabilities, major bugs
|
||||
2. **Important Improvements**: Performance issues, design problems
|
||||
3. **Minor Suggestions**: Style improvements, refactoring opportunities
|
||||
4. **Positive Feedback**: Well-implemented patterns and good practices
|
||||
|
||||
Focus on actionable feedback with specific examples and suggested solutions.
|
||||
Prioritize issues by impact and provide rationale for recommendations.
|
||||
```
|
||||
|
||||
**Use Cases:**
|
||||
|
||||
- "Review this authentication implementation for security issues"
|
||||
- "Check the performance implications of this database query logic"
|
||||
- "Evaluate the code structure and suggest improvements"
|
||||
|
||||
### Technology-Specific Agents
|
||||
|
||||
#### React Specialist
|
||||
|
||||
Optimized for React development, hooks, and component patterns.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: react-specialist
|
||||
description: Expert in React development, hooks, component patterns, and modern React best practices
|
||||
tools: read_file, write_file, read_many_files, run_shell_command
|
||||
---
|
||||
|
||||
You are a React specialist with deep expertise in modern React development.
|
||||
|
||||
Your expertise covers:
|
||||
|
||||
- **Component Design**: Functional components, custom hooks, composition patterns
|
||||
- **State Management**: useState, useReducer, Context API, and external libraries
|
||||
- **Performance**: React.memo, useMemo, useCallback, code splitting
|
||||
- **Testing**: React Testing Library, Jest, component testing strategies
|
||||
- **TypeScript Integration**: Proper typing for props, hooks, and components
|
||||
- **Modern Patterns**: Suspense, Error Boundaries, Concurrent Features
|
||||
|
||||
For React tasks:
|
||||
|
||||
1. Use functional components and hooks by default
|
||||
2. Implement proper TypeScript typing
|
||||
3. Follow React best practices and conventions
|
||||
4. Consider performance implications
|
||||
5. Include appropriate error handling
|
||||
6. Write testable, maintainable code
|
||||
|
||||
Always stay current with React best practices and avoid deprecated patterns.
|
||||
Focus on accessibility and user experience considerations.
|
||||
```
|
||||
|
||||
**Use Cases:**
|
||||
|
||||
- "Create a reusable data table component with sorting and filtering"
|
||||
- "Implement a custom hook for API data fetching with caching"
|
||||
- "Refactor this class component to use modern React patterns"
|
||||
|
||||
#### Python Expert
|
||||
|
||||
Specialized in Python development, frameworks, and best practices.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: python-expert
|
||||
description: Expert in Python development, frameworks, testing, and Python-specific best practices
|
||||
tools: read_file, write_file, read_many_files, run_shell_command
|
||||
---
|
||||
|
||||
You are a Python expert with deep knowledge of the Python ecosystem.
|
||||
|
||||
Your expertise includes:
|
||||
|
||||
- **Core Python**: Pythonic patterns, data structures, algorithms
|
||||
- **Frameworks**: Django, Flask, FastAPI, SQLAlchemy
|
||||
- **Testing**: pytest, unittest, mocking, test-driven development
|
||||
- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks
|
||||
- **Async Programming**: asyncio, async/await patterns
|
||||
- **Package Management**: pip, poetry, virtual environments
|
||||
- **Code Quality**: PEP 8, type hints, linting with pylint/flake8
|
||||
|
||||
For Python tasks:
|
||||
|
||||
1. Follow PEP 8 style guidelines
|
||||
2. Use type hints for better code documentation
|
||||
3. Implement proper error handling with specific exceptions
|
||||
4. Write comprehensive docstrings
|
||||
5. Consider performance and memory usage
|
||||
6. Include appropriate logging
|
||||
7. Write testable, modular code
|
||||
|
||||
Focus on writing clean, maintainable Python code that follows community standards.
|
||||
```
|
||||
|
||||
**Use Cases:**
|
||||
|
||||
- "Create a FastAPI service for user authentication with JWT tokens"
|
||||
- "Implement a data processing pipeline with pandas and error handling"
|
||||
- "Write a CLI tool using argparse with comprehensive help documentation"
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Design Principles
|
||||
|
||||
#### Single Responsibility Principle
|
||||
|
||||
Each subagent should have a clear, focused purpose.
|
||||
|
||||
**✅ Good:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: testing-expert
|
||||
description: Writes comprehensive unit tests and integration tests
|
||||
---
|
||||
```
|
||||
|
||||
**❌ Avoid:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: general-helper
|
||||
description: Helps with testing, documentation, code review, and deployment
|
||||
---
|
||||
```
|
||||
|
||||
**Why:** Focused agents produce better results and are easier to maintain.
|
||||
|
||||
#### Clear Specialization
|
||||
|
||||
Define specific expertise areas rather than broad capabilities.
|
||||
|
||||
**✅ Good:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: react-performance-optimizer
|
||||
description: Optimizes React applications for performance using profiling and best practices
|
||||
---
|
||||
```
|
||||
|
||||
**❌ Avoid:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: frontend-developer
|
||||
description: Works on frontend development tasks
|
||||
---
|
||||
```
|
||||
|
||||
**Why:** Specific expertise leads to more targeted and effective assistance.
|
||||
|
||||
#### Actionable Descriptions
|
||||
|
||||
Write descriptions that clearly indicate when to use the agent.
|
||||
|
||||
**✅ Good:**
|
||||
|
||||
```markdown
|
||||
description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns
|
||||
```
|
||||
|
||||
**❌ Avoid:**
|
||||
|
||||
```markdown
|
||||
description: A helpful code reviewer
|
||||
```
|
||||
|
||||
**Why:** Clear descriptions help the main AI choose the right agent for each task.
|
||||
|
||||
### Configuration Best Practices
|
||||
|
||||
#### System Prompt Guidelines
|
||||
|
||||
**Be Specific About Expertise:**
|
||||
|
||||
```markdown
|
||||
You are a Python testing specialist with expertise in:
|
||||
|
||||
- pytest framework and fixtures
|
||||
- Mock objects and dependency injection
|
||||
- Test-driven development practices
|
||||
- Performance testing with pytest-benchmark
|
||||
```
|
||||
|
||||
**Include Step-by-Step Approaches:**
|
||||
|
||||
```markdown
|
||||
For each testing task:
|
||||
|
||||
1. Analyze the code structure and dependencies
|
||||
2. Identify key functionality and edge cases
|
||||
3. Create comprehensive test suites with clear naming
|
||||
4. Include setup/teardown and proper assertions
|
||||
5. Add comments explaining complex test scenarios
|
||||
```
|
||||
|
||||
**Specify Output Standards:**
|
||||
|
||||
```markdown
|
||||
Always follow these standards:
|
||||
|
||||
- Use descriptive test names that explain the scenario
|
||||
- Include both positive and negative test cases
|
||||
- Add docstrings for complex test functions
|
||||
- Ensure tests are independent and can run in any order
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- **Tool Restrictions**: Subagents only have access to their configured tools
|
||||
- **Sandboxing**: All tool execution follows the same security model as direct tool use
|
||||
- **Audit Trail**: All subagent actions are logged and visible in real-time
|
||||
- **Access Control**: Project and user-level separation provides appropriate boundaries
|
||||
- **Sensitive Information**: Avoid including secrets or credentials in agent configurations
|
||||
- **Production Environments**: Consider separate agents for production vs development environments
|
||||
@@ -193,7 +193,7 @@ Logs are timestamped records of specific events. The following events are logged
|
||||
- `error_type` (if applicable)
|
||||
- `metadata` (if applicable, dictionary of string -> any)
|
||||
|
||||
- `qwen-code.api_request`: This event occurs when making a request to Gemini API.
|
||||
- `qwen-code.api_request`: This event occurs when making a request to Qwen API.
|
||||
- **Attributes**:
|
||||
- `model`
|
||||
- `request_text` (if applicable)
|
||||
@@ -207,7 +207,7 @@ Logs are timestamped records of specific events. The following events are logged
|
||||
- `duration_ms`
|
||||
- `auth_type`
|
||||
|
||||
- `qwen-code.api_response`: This event occurs upon receiving a response from Gemini API.
|
||||
- `qwen-code.api_response`: This event occurs upon receiving a response from Qwen API.
|
||||
- **Attributes**:
|
||||
- `model`
|
||||
- `status_code`
|
||||
@@ -275,7 +275,7 @@ Metrics are numerical measurements of behavior over time. The following metrics
|
||||
- `user_removed_lines` (Int, if applicable): Number of lines removed/changed by user in AI proposed changes.
|
||||
- `programming_language` (string, if applicable): The programming language of the file.
|
||||
|
||||
- `gemini_cli.chat_compression` (Counter, Int): Counts chat compression operations
|
||||
- `qwen-code.chat_compression` (Counter, Int): Counts chat compression operations
|
||||
- **Attributes**:
|
||||
- `tokens_before`: (Int): Number of tokens in context prior to compression
|
||||
- `tokens_after`: (Int): Number of tokens in context after compression
|
||||
|
||||
@@ -157,7 +157,7 @@ search_file_content(pattern="function", include="*.js", maxResults=10)
|
||||
- If `old_string` is provided, it reads the `file_path` and attempts to find exactly one occurrence of `old_string`.
|
||||
- If one occurrence is found, it replaces it with `new_string`.
|
||||
- **Enhanced Reliability (Multi-Stage Edit Correction):** To significantly improve the success rate of edits, especially when the model-provided `old_string` might not be perfectly precise, the tool incorporates a multi-stage edit correction mechanism.
|
||||
- If the initial `old_string` isn't found or matches multiple locations, the tool can leverage the Gemini model to iteratively refine `old_string` (and potentially `new_string`).
|
||||
- If the initial `old_string` isn't found or matches multiple locations, the tool can leverage the Qwen model to iteratively refine `old_string` (and potentially `new_string`).
|
||||
- This self-correction process attempts to identify the unique segment the model intended to modify, making the `edit` operation more robust even with slightly imperfect initial context.
|
||||
- **Failure conditions:** Despite the correction mechanism, the tool will fail if:
|
||||
- `file_path` is not absolute or is outside the root directory.
|
||||
|
||||
@@ -25,7 +25,7 @@ The discovery process is orchestrated by `discoverMcpTools()`, which:
|
||||
1. **Iterates through configured servers** from your `settings.json` `mcpServers` configuration
|
||||
2. **Establishes connections** using appropriate transport mechanisms (Stdio, SSE, or Streamable HTTP)
|
||||
3. **Fetches tool definitions** from each server using the MCP protocol
|
||||
4. **Sanitizes and validates** tool schemas for compatibility with the Gemini API
|
||||
4. **Sanitizes and validates** tool schemas for compatibility with the Qwen API
|
||||
5. **Registers tools** in the global tool registry with conflict resolution
|
||||
|
||||
### Execution Layer (`mcp-tool.ts`)
|
||||
@@ -333,7 +333,7 @@ Upon successful connection:
|
||||
1. **Tool listing:** The client calls the MCP server's tool listing endpoint
|
||||
2. **Schema validation:** Each tool's function declaration is validated
|
||||
3. **Tool filtering:** Tools are filtered based on `includeTools` and `excludeTools` configuration
|
||||
4. **Name sanitization:** Tool names are cleaned to meet Gemini API requirements:
|
||||
4. **Name sanitization:** Tool names are cleaned to meet Qwen API requirements:
|
||||
- Invalid characters (non-alphanumeric, underscore, dot, hyphen) are replaced with underscores
|
||||
- Names longer than 63 characters are truncated with middle replacement (`___`)
|
||||
|
||||
@@ -468,7 +468,7 @@ Discovery State: COMPLETED
|
||||
|
||||
### Tool Usage
|
||||
|
||||
Once discovered, MCP tools are available to the Gemini model like built-in tools. The model will automatically:
|
||||
Once discovered, MCP tools are available to the Qwen model like built-in tools. The model will automatically:
|
||||
|
||||
1. **Select appropriate tools** based on your requests
|
||||
2. **Present confirmation dialogs** (unless the server is trusted)
|
||||
@@ -566,7 +566,7 @@ The MCP integration tracks several states:
|
||||
|
||||
### Schema Compatibility
|
||||
|
||||
- **Property stripping:** The system automatically removes certain schema properties (`$schema`, `additionalProperties`) for Gemini API compatibility
|
||||
- **Property stripping:** The system automatically removes certain schema properties (`$schema`, `additionalProperties`) for Qwen API compatibility
|
||||
- **Name sanitization:** Tool names are automatically sanitized to meet API requirements
|
||||
- **Conflict resolution:** Tool name conflicts between servers are resolved through automatic prefixing
|
||||
|
||||
@@ -620,7 +620,7 @@ When Qwen Code receives this response, it will:
|
||||
2. Present the image data as a separate `inlineData` part.
|
||||
3. Provide a clean, user-friendly summary in the CLI, indicating that both text and an image were received.
|
||||
|
||||
This enables you to build sophisticated tools that can provide rich, multi-modal context to the Gemini model.
|
||||
This enables you to build sophisticated tools that can provide rich, multi-modal context to the Qwen model.
|
||||
|
||||
## MCP Prompts as Slash Commands
|
||||
|
||||
|
||||
@@ -35,7 +35,7 @@ save_memory(fact="My preferred programming language is Python.")
|
||||
Store a project-specific detail:
|
||||
|
||||
```
|
||||
save_memory(fact="The project I'm currently working on is called 'gemini-cli'.")
|
||||
save_memory(fact="The project I'm currently working on is called 'qwen-code'.")
|
||||
```
|
||||
|
||||
## Important notes
|
||||
|
||||
@@ -42,7 +42,7 @@ web_fetch(url="https://arxiv.org/abs/2401.0001", prompt="What are the key findin
|
||||
Analyze GitHub documentation:
|
||||
|
||||
```
|
||||
web_fetch(url="https://github.com/google/gemini-react/blob/main/README.md", prompt="What are the installation steps and main features?")
|
||||
web_fetch(url="https://github.com/QwenLM/Qwen/blob/main/README.md", prompt="What are the installation steps and main features?")
|
||||
```
|
||||
|
||||
## Important notes
|
||||
|
||||
@@ -9,16 +9,6 @@ This guide provides solutions to common issues and debugging tips, including top
|
||||
|
||||
## Authentication or login errors
|
||||
|
||||
- **Error: `Failed to login. Message: Request contains an invalid argument`**
|
||||
- Users with Google Workspace accounts or Google Cloud accounts
|
||||
associated with their Gmail accounts may not be able to activate the free
|
||||
tier of the Google Code Assist plan.
|
||||
- For Google Cloud accounts, you can work around this by setting
|
||||
`GOOGLE_CLOUD_PROJECT` to your project ID.
|
||||
- Alternatively, you can obtain the Gemini API key from
|
||||
[Google AI Studio](http://aistudio.google.com/app/apikey), which also includes a
|
||||
separate free tier.
|
||||
|
||||
- **Error: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` or `unable to get local issuer certificate`**
|
||||
- **Cause:** You may be on a corporate network with a firewall that intercepts and inspects SSL/TLS traffic. This often requires a custom root CA certificate to be trusted by Node.js.
|
||||
- **Solution:** Set the `NODE_EXTRA_CA_CERTS` environment variable to the absolute path of your corporate root CA certificate file.
|
||||
@@ -37,7 +27,7 @@ This guide provides solutions to common issues and debugging tips, including top
|
||||
Refer to [Qwen Code Configuration](./cli/configuration.md) for more details.
|
||||
|
||||
- **Q: Why don't I see cached token counts in my stats output?**
|
||||
- A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Gemini API key or Google Cloud Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts like Google Gmail or Google Workspace, respectively). This is because the Gemini Code Assist API does not support cached content creation. You can still view your total token usage using the `/stats` command.
|
||||
- A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Qwen API key or Google Cloud Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts like Google Gmail or Google Workspace, respectively). This is because the Qwen Code Assist API does not support cached content creation. You can still view your total token usage using the `/stats` command.
|
||||
|
||||
## Common error messages and solutions
|
||||
|
||||
|
||||
Reference in New Issue
Block a user