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.
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.
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.
### Preview Releases
### 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
# 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
```
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.
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.
### Failure Handling
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
@@ -155,7 +170,7 @@ By performing a dry run, you can be confident that your changes to the packaging
## 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
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.
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
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
`bundle` folder is created at the project root to house the final package contents.
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.
1. The `package.json` is Transformed:
- What happens: The package.json from packages/cli/ is read, modified, and written into the root `bundle`/ directory.
- 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": { "@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.
1. Bundle Creation:
- What happens: The prepare-package.js script creates a clean distribution package in the `dist` directory.
- Key transformations:
- Copies README.md and LICENSE to dist/
- Copies locales folder for internationalization
- Creates a clean package.json for distribution with only necessary dependencies
- Includes runtime dependencies like tiktoken
- Maintains optional dependencies for node-pty
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,
executable JavaScript file.
- File movement: packages/cli/dist/index.js + packages/core/dist/index.js -> (bundled by esbuild) -> `bundle`/gemini.js (or a
similar name).
executable JavaScript file using esbuild.
- File location: dist/cli.js
- 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:
- 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:
- README.md -> `bundle`/README.md
- LICENSE -> `bundle`/LICENSE
- packages/cli/src/utils/\*.sb (sandbox profiles) -> `bundle`/
- README.md -> dist/README.md
- LICENSE -> dist/LICENSE
- locales/ -> dist/locales/
- Vendor files -> dist/vendor/
- Why:
- 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
function. They must be located next to the final executable.
- Locales support internationalization features
- Vendor files contain necessary runtime dependencies
Stage 4: Publishing to NPM
- What happens: The npm publish command is run from inside the root `bundle` directory.
- Why: By running npm publish from within the `bundle` directory, only the files we carefully assembled in Stage 3 are uploaded
- What happens: The npm publish command is run from inside the root `dist` directory.
- 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
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
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
> [!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.
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 {
commands: 'Commands',
'sub-agents': 'SubAgents',
headless: 'Headless Mode',
checkpointing: {
display: 'hidden',
},
headless: 'Headless Mode',
'approval-mode': 'Approval Mode',
'token-caching': 'Token Caching',
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.
@@ -183,10 +183,10 @@ Naming Rules: Path separator (`/` or `\`) converted to colon (`:`)
| Operation | User Interaction |
| ------------------------------- | -------------------- |
| 1. Parse command and parameters | - |
| 2. Automatic Shell escaping | - |
| 3. Show confirmation dialog | ✅ User confirmation |
| 4. Execute command | - |
| 5. Inject output to prompt | - |
| 2. Automatic Shell escaping | - |
| 3. Show confirmation dialog | ✅ User confirmation |
| 4. Execute command | - |
| 5. Inject output to prompt | - |
Example: Git Commit Message Generation
@@ -228,9 +228,9 @@ Review {{args}}, reference standards:
| Operation | Command/Code |
| ----------------------------- | ------------------------------------------- |
| 1. Create directory structure | `mkdir -p ~/.qwen/commands/refactor` |
| 2. Create command file | `touch ~/.qwen/commands/refactor/pure.toml` |
| 3. Edit command content | Refer to the complete code below. |
| 4. Test command | `@file.js` → `/refactor:pure` |
| 2. Create command file | `touch ~/.qwen/commands/refactor/pure.toml` |
| 3. Edit command content | Refer to the complete code below. |
| 4. Test command | `@file.js` → `/refactor:pure` |
```# ~/.qwen/commands/refactor/pure.toml
description = "Refactor code to pure function"