abbyswag/qwen-code
1
0
Fork 0
mirror of https://github.com/QwenLM/qwen-code.git synced 2025-12-19 09:33:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: enhance architecture documentation and add contribution guidelines

Browse Source
This commit is contained in:
pomelo-nwu
2025-12-11 18:31:24 +08:00
parent 903113d749
commit 692d6e227e
2 changed files with 372 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

97
docs/developers/architecture.md
View File

@@ -2,53 +2,94 @@
This document provides a high-level overview of Qwen Code's architecture.
## Core components
## Core Components
Qwen Code is primarily composed of two main packages, along with a suite of tools that can be used by the system in the course of handling command-line input:
1. **CLI package (`packages/cli`):**
- **Purpose:** This contains the user-facing portion of Qwen Code, such as handling the initial user input, presenting the final output, and managing the overall user experience.
- **Key functions contained in the package:**
- [Input processing](./cli/commands.md)
- History management
- Display rendering
- [Theme and UI customization](./cli/themes.md)
- [CLI configuration settings](./cli/configuration.md)
### 1. CLI Package (`packages/cli`)
2. **Core package (`packages/core`):**
- **Purpose:** This acts as the backend for Qwen Code. It receives requests sent from `packages/cli`, orchestrates interactions with the configured model API, and manages the execution of available tools.
- **Key functions contained in the package:**
- API client for communicating with the Google Gemini API
- Prompt construction and management
- Tool registration and execution logic
- State management for conversations or sessions
- Server-side configuration
**Purpose:** This contains the user-facing portion of Qwen Code, such as handling the initial user input, presenting the final output, and managing the overall user experience.
3. **Tools (`packages/core/src/tools/`):**
- **Purpose:** These are individual modules that extend the capabilities of the Gemini model, allowing it to interact with the local environment (e.g., file system, shell commands, web fetching).
- **Interaction:** `packages/core` invokes these tools based on requests from the Gemini model.
**Key Functions:**
- **Input Processing:** Handles user input through various methods including direct text entry, slash commands (e.g., `/help`, `/clear`, `/model`), at commands (`@file` for including file content), and exclamation mark commands (`!command` for shell execution).
- **History Management:** Maintains conversation history and enables features like session resumption.
- **Display Rendering:** Formats and presents responses to the user in the terminal with syntax highlighting and proper formatting.
- **Theme and UI Customization:** Supports customizable themes and UI elements for a personalized experience.
- **Configuration Settings:** Manages various configuration options through JSON settings files, environment variables, and command-line arguments.
### 2. Core Package (`packages/core`)
**Purpose:** This acts as the backend for Qwen Code. It receives requests sent from `packages/cli`, orchestrates interactions with the configured model API, and manages the execution of available tools.
**Key Functions:**
- **API Client:** Communicates with the Qwen model API to send prompts and receive responses.
- **Prompt Construction:** Builds appropriate prompts for the model, incorporating conversation history and available tool definitions.
- **Tool Registration and Execution:** Manages the registration of available tools and executes them based on model requests.
- **State Management:** Maintains conversation and session state information.
- **Server-side Configuration:** Handles server-side configuration and settings.
### 3. Tools (`packages/core/src/tools/`)
**Purpose:** These are individual modules that extend the capabilities of the Qwen model, allowing it to interact with the local environment (e.g., file system, shell commands, web fetching).
**Interaction:** `packages/core` invokes these tools based on requests from the Qwen model.
**Common Tools Include:**
- **File Operations:** Reading, writing, and editing files
- **Shell Commands:** Executing system commands with user approval for potentially dangerous operations
- **Search Tools:** Finding files and searching content within the project
- **Web Tools:** Fetching content from the web
- **MCP Integration:** Connecting to Model Context Protocol servers for extended capabilities
## Interaction Flow
A typical interaction with Qwen Code follows this flow:
1. **User input:** The user types a prompt or command into the terminal, which is managed by `packages/cli`.
2. **Request to core:** `packages/cli` sends the user's input to `packages/core`.
3. **Request processed:** The core package:
1. **User Input:** The user types a prompt or command into the terminal, which is managed by `packages/cli`.
2. **Request to Core:** `packages/cli` sends the user's input to `packages/core`.
3. **Request Processing:** The core package:
- Constructs an appropriate prompt for the configured model API, possibly including conversation history and available tool definitions.
- Sends the prompt to the model API.
4. **Model API response:** The model API processes the prompt and returns a response. This response might be a direct answer or a request to use one of the available tools.
5. **Tool execution (if applicable):**
4. **Model API Response:** The model API processes the prompt and returns a response. This response might be a direct answer or a request to use one of the available tools.
5. **Tool Execution (if applicable):**
- When the model API requests a tool, the core package prepares to execute it.
- If the requested tool can modify the file system or execute shell commands, the user is first given details of the tool and its arguments, and the user must approve the execution.
- Read-only operations, such as reading files, might not require explicit user confirmation to proceed.
- Once confirmed, or if confirmation is not required, the core package executes the relevant action within the relevant tool, and the result is sent back to the model API by the core package.
- The model API processes the tool result and generates a final response.
6. **Response to CLI:** The core package sends the final response back to the CLI package.
7. **Display to user:** The CLI package formats and displays the response to the user in the terminal.
7. **Display to User:** The CLI package formats and displays the response to the user in the terminal.
## Configuration Options
Qwen Code offers multiple ways to configure its behavior:
### Configuration Layers (in order of precedence)
1. Command-line arguments
2. Environment variables
3. Project settings file (`.qwen/settings.json`)
4. User settings file (`~/.qwen/settings.json`)
5. System settings files
6. Default values
### Key Configuration Categories
- **General Settings:** vim mode, preferred editor, auto-update preferences
- **UI Settings:** Theme customization, banner visibility, footer display
- **Model Settings:** Model selection, session turn limits, compression settings
- **Context Settings:** Context file names, directory inclusion, file filtering
- **Tool Settings:** Approval modes, sandboxing, tool restrictions
- **Privacy Settings:** Usage statistics collection
- **Advanced Settings:** Debug options, custom bug reporting commands
## Key Design Principles
- **Modularity:** Separating the CLI (frontend) from the Core (backend) allows for independent development and potential future extensions (e.g., different frontends for the same backend).
- **Extensibility:** The tool system is designed to be extensible, allowing new capabilities to be added.
- **User experience:** The CLI focuses on providing a rich and interactive terminal experience.
- **Extensibility:** The tool system is designed to be extensible, allowing new capabilities to be added through custom tools or MCP server integration.
- **User Experience:** The CLI focuses on providing a rich and interactive terminal experience with features like syntax highlighting, customizable themes, and intuitive command structures.
- **Security:** Implements approval mechanisms for potentially dangerous operations and sandboxing options to protect the user's system.
- **Flexibility:** Supports multiple configuration methods and can adapt to different workflows and environments.

303
docs/developers/contributing.md
View File

@@ -0,0 +1,303 @@
# How to Contribute
We would love to accept your patches and contributions to this project.
## Contribution Process
### Code Reviews
All submissions, including submissions by project members, require review. We
use [GitHub pull requests](https://docs.github.com/articles/about-pull-requests)
for this purpose.
### Pull Request Guidelines
To help us review and merge your PRs quickly, please follow these guidelines. PRs that do not meet these standards may be closed.
#### 1. Link to an Existing Issue
All PRs should be linked to an existing issue in our tracker. This ensures that every change has been discussed and is aligned with the project's goals before any code is written.
- **For bug fixes:** The PR should be linked to the bug report issue.
- **For features:** The PR should be linked to the feature request or proposal issue that has been approved by a maintainer.
If an issue for your change doesn't exist, please **open one first** and wait for feedback before you start coding.
#### 2. Keep It Small and Focused
We favor small, atomic PRs that address a single issue or add a single, self-contained feature.
- **Do:** Create a PR that fixes one specific bug or adds one specific feature.
- **Don't:** Bundle multiple unrelated changes (e.g., a bug fix, a new feature, and a refactor) into a single PR.
Large changes should be broken down into a series of smaller, logical PRs that can be reviewed and merged independently.
#### 3. Use Draft PRs for Work in Progress
If you'd like to get early feedback on your work, please use GitHub's **Draft Pull Request** feature. This signals to the maintainers that the PR is not yet ready for a formal review but is open for discussion and initial feedback.
#### 4. Ensure All Checks Pass
Before submitting your PR, ensure that all automated checks are passing by running `npm run preflight`. This command runs all tests, linting, and other style checks.
#### 5. Update Documentation
If your PR introduces a user-facing change (e.g., a new command, a modified flag, or a change in behavior), you must also update the relevant documentation in the `/docs` directory.
#### 6. Write Clear Commit Messages and a Good PR Description
Your PR should have a clear, descriptive title and a detailed description of the changes. Follow the [Conventional Commits](https://www.conventionalcommits.org/) standard for your commit messages.
- **Good PR Title:** `feat(cli): Add --json flag to 'config get' command`
- **Bad PR Title:** `Made some changes`
In the PR description, explain the "why" behind your changes and link to the relevant issue (e.g., `Fixes #123`).
## Development Setup and Workflow
This section guides contributors on how to build, modify, and understand the development setup of this project.
### Setting Up the Development Environment
**Prerequisites:**
1. **Node.js**:
- **Development:** Please use Node.js `~20.19.0`. This specific version is required due to an upstream development dependency issue. You can use a tool like [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions.
- **Production:** For running the CLI in a production environment, any version of Node.js `>=20` is acceptable.
2. **Git**
### Build Process
To clone the repository:
```bash
git clone https://github.com/QwenLM/qwen-code.git # Or your fork's URL
cd qwen-code
```
To install dependencies defined in `package.json` as well as root dependencies:
```bash
npm install
```
To build the entire project (all packages):
```bash
npm run build
```
This command typically compiles TypeScript to JavaScript, bundles assets, and prepares the packages for execution. Refer to `scripts/build.js` and `package.json` scripts for more details on what happens during the build.
### Enabling Sandboxing
[Sandboxing](#sandboxing) is highly recommended and requires, at a minimum, setting `QWEN_SANDBOX=true` in your `~/.env` and ensuring a sandboxing provider (e.g. `macOS Seatbelt`, `docker`, or `podman`) is available. See [Sandboxing](#sandboxing) for details.
To build both the `qwen-code` CLI utility and the sandbox container, run `build:all` from the root directory:
```bash
npm run build:all
```
To skip building the sandbox container, you can use `npm run build` instead.
### Running
To start the Qwen Code application from the source code (after building), run the following command from the root directory:
```bash
npm start
```
If you'd like to run the source build outside of the qwen-code folder, you can utilize `npm link path/to/qwen-code/packages/cli` (see: [docs](https://docs.npmjs.com/cli/v9/commands/npm-link)) to run with `qwen-code`
### Running Tests
This project contains two types of tests: unit tests and integration tests.
#### Unit Tests
To execute the unit test suite for the project:
```bash
npm run test
```
This will run tests located in the `packages/core` and `packages/cli` directories. Ensure tests pass before submitting any changes. For a more comprehensive check, it is recommended to run `npm run preflight`.
#### Integration Tests
The integration tests are designed to validate the end-to-end functionality of Qwen Code. They are not run as part of the default `npm run test` command.
To run the integration tests, use the following command:
```bash
npm run test:e2e
```
For more detailed information on the integration testing framework, please see the [Integration Tests documentation](./docs/integration-tests.md).
### Linting and Preflight Checks
To ensure code quality and formatting consistency, run the preflight check:
```bash
npm run preflight
```
This command will run ESLint, Prettier, all tests, and other checks as defined in the project's `package.json`.
_ProTip_
after cloning create a git precommit hook file to ensure your commits are always clean.
```bash
echo "
# Run npm build and check for errors
if ! npm run preflight; then
echo "npm build failed. Commit aborted."
exit 1
fi
" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
```
#### Formatting
To separately format the code in this project by running the following command from the root directory:
```bash
npm run format
```
This command uses Prettier to format the code according to the project's style guidelines.
#### Linting
To separately lint the code in this project, run the following command from the root directory:
```bash
npm run lint
```
### Coding Conventions
- Please adhere to the coding style, patterns, and conventions used throughout the existing codebase.
- **Imports:** Pay special attention to import paths. The project uses ESLint to enforce restrictions on relative imports between packages.
### Project Structure
- `packages/`: Contains the individual sub-packages of the project.
- `cli/`: The command-line interface.
- `core/`: The core backend logic for Qwen Code.
- `docs/`: Contains all project documentation.
- `scripts/`: Utility scripts for building, testing, and development tasks.
For more detailed architecture, see `docs/architecture.md`.
## Documentation Development
This section describes how to develop and preview the documentation locally.
### Prerequisites
1. Ensure you have Node.js (version 18+) installed
2. Have npm or yarn available
### Setup Documentation Site Locally
To work on the documentation and preview changes locally:
1. Navigate to the `docs-site` directory:
```bash
cd docs-site
```
2. Install dependencies:
```bash
npm install
```
3. Link the documentation content from the main `docs` directory:
```bash
npm run link
```
This creates a symbolic link from `../docs` to `content` in the docs-site project, allowing the documentation content to be served by the Next.js site.
4. Start the development server:
```bash
npm run dev
```
5. Open [http://localhost:3000](http://localhost:3000) in your browser to see the documentation site with live updates as you make changes.
Any changes made to the documentation files in the main `docs` directory will be reflected immediately in the documentation site.
## Debugging
### VS Code:
0. Run the CLI to interactively debug in VS Code with `F5`
1. Start the CLI in debug mode from the root directory:
```bash
npm run debug
```
This command runs `node --inspect-brk dist/index.js` within the `packages/cli` directory, pausing execution until a debugger attaches. You can then open `chrome://inspect` in your Chrome browser to connect to the debugger.
2. In VS Code, use the "Attach" launch configuration (found in `.vscode/launch.json`).
Alternatively, you can use the "Launch Program" configuration in VS Code if you prefer to launch the currently open file directly, but 'F5' is generally recommended.
To hit a breakpoint inside the sandbox container run:
```bash
DEBUG=1 qwen-code
```
**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect qwen-code due to automatic exclusion. Use `.qwen-code/.env` files for qwen-code specific debug settings.
### React DevTools
To debug the CLI's React-based UI, you can use React DevTools. Ink, the library used for the CLI's interface, is compatible with React DevTools version 4.x.
1. **Start the Qwen Code application in development mode:**
```bash
DEV=true npm start
```
2. **Install and run React DevTools version 4.28.5 (or the latest compatible 4.x version):**
You can either install it globally:
```bash
npm install -g react-devtools@4.28.5
react-devtools
```
Or run it directly using npx:
```bash
npx react-devtools@4.28.5
```
Your running CLI application should then connect to React DevTools.
## Sandboxing
> TBD
## Manual Publish
We publish an artifact for each commit to our internal registry. But if you need to manually cut a local build, then run the following commands:
```
npm run clean
npm install
npm run auth
npm run prerelease:dev
npm publish --workspaces
```