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

feat: update docs

Browse Source
This commit is contained in:
pomelo-nwu
2025-12-15 19:40:14 +08:00
parent e5a3670ed3
commit 5742a69d8a
4 changed files with 72 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
docs/developers/development/npm.md
View File

@@ -31,42 +31,57 @@ Releases are managed through the [release.yml](https://github.com/QwenLM/qwen-co
- **Dry Run**: Leave as `true` to test the workflow without publishing, or set to `false` to perform a live release. - **Dry Run**: Leave as `true` to test the workflow without publishing, or set to `false` to perform a live release.
5. Click **Run workflow**. 5. Click **Run workflow**.
## Nightly Releases ## Release Types
In addition to manual releases, this project has an automated nightly release process to provide the latest "bleeding edge" version for testing and development. The project supports multiple types of releases:
### Process ### Stable Releases
Every night at midnight UTC, the [Release workflow](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) runs automatically on a schedule. It performs the following steps: Regular stable releases for production use.
1. Checks out the latest code from the `main` branch. ### Preview Releases
2. Installs all dependencies.
3. Runs the full suite of `preflight` checks and integration tests.
4. If all tests succeed, it calculates the next nightly version number (e.g., `v0.2.1-nightly.20230101`).
5. It then builds and publishes the packages to npm with the `nightly` dist-tag.
6. Finally, it creates a GitHub Release for the nightly version.
### Failure Handling Weekly preview releases every Tuesday at 23:59 UTC for early access to upcoming features.
If any step in the nightly workflow fails, it will automatically create a new issue in the repository with the labels `bug` and `nightly-failure`. The issue will contain a link to the failed workflow run for easy debugging. ### Nightly Releases
### How to Use the Nightly Build Daily nightly releases at midnight UTC for bleeding-edge development testing.
To install the latest nightly build, use the `@nightly` tag: ## Automated Release Schedule
- **Nightly**: Every day at midnight UTC
- **Preview**: Every Tuesday at 23:59 UTC
- **Stable**: Manual releases triggered by maintainers
### How to Use Different Release Types
To install the latest version of each type:
```bash ```bash
# Stable (default)
npm install -g @qwen-code/qwen-code
# Preview
npm install -g @qwen-code/qwen-code@preview
# Nightly
npm install -g @qwen-code/qwen-code@nightly npm install -g @qwen-code/qwen-code@nightly
``` ```
We also run a Google cloud build called [release-docker.yml](../.gcp/release-docker.yml). Which publishes the sandbox docker to match your release. This will also be moved to GH and combined with the main release file once service account permissions are sorted out. ### Release Process Details
### After the Release Every scheduled or manual release follows these steps:
After the workflow has successfully completed, you can monitor its progress in the [GitHub Actions tab](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml). Once complete, you should: 1. Checks out the specified code (latest from `main` branch or specific commit).
2. Installs all dependencies.
3. Runs the full suite of `preflight` checks and integration tests.
4. If all tests succeed, it calculates the appropriate version number based on release type.
5. Builds and publishes the packages to npm with the appropriate dist-tag.
6. Creates a GitHub Release for the version.
1. Go to the [pull requests page](https://github.com/QwenLM/qwen-code/pulls) of the repository. ### Failure Handling
2. Create a new pull request from the `release/vX.Y.Z` branch to `main`.
3. Review the pull request (it should only contain version updates in `package.json` files) and merge it. This keeps the version in `main` up-to-date. If any step in the release workflow fails, it will automatically create a new issue in the repository with the labels `bug` and a type-specific failure label (e.g., `nightly-failure`, `preview-failure`). The issue will contain a link to the failed workflow run for easy debugging.
## Release Validation ## Release Validation
@@ -155,7 +170,7 @@ By performing a dry run, you can be confident that your changes to the packaging
## Release Deep Dive ## Release Deep Dive
The main goal of the release process is to take the source code from the packages/ directory, build it, and assemble a The main goal of the release process is to take the source code from the packages/ directory, build it, and assemble a
clean, self-contained package in a temporary `bundle` directory at the root of the project. This `bundle` directory is what clean, self-contained package in a temporary `dist` directory at the root of the project. This `dist` directory is what
actually gets published to NPM. actually gets published to NPM.
Here are the key stages: Here are the key stages:
@@ -177,83 +192,46 @@ Stage 2: Building the Source Code
- Why: The TypeScript code written during development needs to be converted into plain JavaScript that can be run by - Why: The TypeScript code written during development needs to be converted into plain JavaScript that can be run by
Node.js. The core package is built first as the cli package depends on it. Node.js. The core package is built first as the cli package depends on it.
Stage 3: Assembling the Final Publishable Package Stage 3: Bundling and Assembling the Final Publishable Package
This is the most critical stage where files are moved and transformed into their final state for publishing. A temporary This is the most critical stage where files are moved and transformed into their final state for publishing. The process uses modern bundling techniques to create the final package.
`bundle` folder is created at the project root to house the final package contents.
1. The `package.json` is Transformed: 1. Bundle Creation:
- What happens: The package.json from packages/cli/ is read, modified, and written into the root `bundle`/ directory. - What happens: The prepare-package.js script creates a clean distribution package in the `dist` directory.
- File movement: packages/cli/package.json -> (in-memory transformation) -> `bundle`/package.json - Key transformations:
- Why: The final package.json must be different from the one used in development. Key changes include: - Copies README.md and LICENSE to dist/
- Removing devDependencies. - Copies locales folder for internationalization
- Removing workspace-specific "dependencies": { "@qwen-code/core": "workspace:\*" } and ensuring the core code is - Creates a clean package.json for distribution with only necessary dependencies
bundled directly into the final JavaScript file. - Includes runtime dependencies like tiktoken
- Ensuring the bin, main, and files fields point to the correct locations within the final package structure. - Maintains optional dependencies for node-pty
2. The JavaScript Bundle is Created: 2. The JavaScript Bundle is Created:
- What happens: The built JavaScript from both packages/core/dist and packages/cli/dist are bundled into a single, - What happens: The built JavaScript from both packages/core/dist and packages/cli/dist are bundled into a single,
executable JavaScript file. executable JavaScript file using esbuild.
- File movement: packages/cli/dist/index.js + packages/core/dist/index.js -> (bundled by esbuild) -> `bundle`/gemini.js (or a - File location: dist/cli.js
similar name).
- Why: This creates a single, optimized file that contains all the necessary application code. It simplifies the package - Why: This creates a single, optimized file that contains all the necessary application code. It simplifies the package
by removing the need for the core package to be a separate dependency on NPM, as its code is now included directly. by removing the need for complex dependency resolution at install time.
3. Static and Supporting Files are Copied: 3. Static and Supporting Files are Copied:
- What happens: Essential files that are not part of the source code but are required for the package to work correctly - What happens: Essential files that are not part of the source code but are required for the package to work correctly
or be well-described are copied into the `bundle` directory. or be well-described are copied into the `dist` directory.
- File movement: - File movement:
- README.md -> `bundle`/README.md - README.md -> dist/README.md
- LICENSE -> `bundle`/LICENSE - LICENSE -> dist/LICENSE
- packages/cli/src/utils/\*.sb (sandbox profiles) -> `bundle`/ - locales/ -> dist/locales/
- Vendor files -> dist/vendor/
- Why: - Why:
- The README.md and LICENSE are standard files that should be included in any NPM package. - The README.md and LICENSE are standard files that should be included in any NPM package.
- The sandbox profiles (.sb files) are critical runtime assets required for the CLI's sandboxing feature to - Locales support internationalization features
function. They must be located next to the final executable. - Vendor files contain necessary runtime dependencies
Stage 4: Publishing to NPM Stage 4: Publishing to NPM
- What happens: The npm publish command is run from inside the root `bundle` directory. - What happens: The npm publish command is run from inside the root `dist` directory.
- Why: By running npm publish from within the `bundle` directory, only the files we carefully assembled in Stage 3 are uploaded - Why: By running npm publish from within the `dist` directory, only the files we carefully assembled in Stage 3 are uploaded
to the NPM registry. This prevents any source code, test files, or development configurations from being accidentally to the NPM registry. This prevents any source code, test files, or development configurations from being accidentally
published, resulting in a clean and minimal package for users. published, resulting in a clean and minimal package for users.
Summary of File Flow
```bash
graph TD
subgraph "Source Files"
A["packages/core/src/*.ts<br/>packages/cli/src/*.ts"]
B["packages/cli/package.json"]
C["README.md<br/>LICENSE<br/>packages/cli/src/utils/*.sb"]
end
subgraph "Process"
D(Build)
E(Transform)
F(Assemble)
G(Publish)
end
subgraph "Artifacts"
H["Bundled JS"]
I["Final package.json"]
J["bundle/"]
end
subgraph "Destination"
K["NPM Registry"]
end
A --> D --> H
B --> E --> I
C --> F
H --> F
I --> F
F --> J
J --> G --> K
```
This process ensures that the final published artifact is a purpose-built, clean, and efficient representation of the This process ensures that the final published artifact is a purpose-built, clean, and efficient representation of the
project, rather than a direct copy of the development workspace. project, rather than a direct copy of the development workspace.

4
docs/developers/development/telemetry.md
View File

@@ -47,6 +47,10 @@ observability framework — Qwen Code's observability system provides:
## Configuration ## Configuration
> [!note]
>
> **⚠️ Special Note: This feature requires corresponding code changes. This documentation is provided in advance; please refer to future code updates for actual functionality.**
All telemetry behavior is controlled through your `.qwen/settings.json` file. All telemetry behavior is controlled through your `.qwen/settings.json` file.
These settings can be overridden by environment variables or CLI flags. These settings can be overridden by environment variables or CLI flags.

3
docs/users/features/_meta.ts
View File

@@ -1,9 +1,10 @@
export default { export default {
commands: 'Commands',
'sub-agents': 'SubAgents', 'sub-agents': 'SubAgents',
headless: 'Headless Mode',
checkpointing: { checkpointing: {
display: 'hidden', display: 'hidden',
}, },
headless: 'Headless Mode',
'approval-mode': 'Approval Mode', 'approval-mode': 'Approval Mode',
'token-caching': 'Token Caching', 'token-caching': 'Token Caching',
mcp: 'MCP', mcp: 'MCP',

16
docs/users/reference/cli-reference.md → docs/users/features/commands.md
View File

@@ -1,4 +1,4 @@
# Qwen Code Command Reference # Commands
This document details all commands supported by Qwen Code, helping you efficiently manage sessions, customize the interface, and control its behavior. This document details all commands supported by Qwen Code, helping you efficiently manage sessions, customize the interface, and control its behavior.
@@ -183,10 +183,10 @@ Naming Rules: Path separator (`/` or `\`) converted to colon (`:`)
| Operation | User Interaction | | Operation | User Interaction |
| ------------------------------- | -------------------- | | ------------------------------- | -------------------- |
| 1. Parse command and parameters | - | | 1. Parse command and parameters | - |
| 2. Automatic Shell escaping | - | | 2. Automatic Shell escaping | - |
| 3. Show confirmation dialog | ✅ User confirmation | | 3. Show confirmation dialog | ✅ User confirmation |
| 4. Execute command | - | | 4. Execute command | - |
| 5. Inject output to prompt | - | | 5. Inject output to prompt | - |
Example: Git Commit Message Generation Example: Git Commit Message Generation
@@ -228,9 +228,9 @@ Review {{args}}, reference standards:
| Operation | Command/Code | | Operation | Command/Code |
| ----------------------------- | ------------------------------------------- | | ----------------------------- | ------------------------------------------- |
| 1. Create directory structure | `mkdir -p ~/.qwen/commands/refactor` | | 1. Create directory structure | `mkdir -p ~/.qwen/commands/refactor` |
| 2. Create command file | `touch ~/.qwen/commands/refactor/pure.toml` | | 2. Create command file | `touch ~/.qwen/commands/refactor/pure.toml` |
| 3. Edit command content | Refer to the complete code below. | | 3. Edit command content | Refer to the complete code below. |
| 4. Test command | `@file.js` → `/refactor:pure` | | 4. Test command | `@file.js` → `/refactor:pure` |
```# ~/.qwen/commands/refactor/pure.toml ```# ~/.qwen/commands/refactor/pure.toml
description = "Refactor code to pure function" description = "Refactor code to pure function"