mirror of
https://github.com/QwenLM/qwen-code.git
synced 2026-05-17 03:57:18 +00:00
cadda23782
* chore(deps): upgrade ink 6.2.3 -> 7.0.2 + bump Node engine to 22
ink 7 requires Node >=22 and react-reconciler 0.33 with React >=19.2,
so this PR also bumps:
- Node engines (root + cli + core) 20 -> 22
- React/react-dom 19.1 -> 19.2.4 (pinned exact via overrides to keep
the transitive React graph deduped to a single instance)
- @types/node pinned to 20.19.1 via overrides to avoid an unrelated
Dirent NonSharedBuffer regression in sessionService tests
- @vitest/eslint-plugin pinned to 1.3.4 to avoid an unrelated lint
regression introduced by the 1.6.x rule additions
- react-devtools-core 4.28 -> 6.1 (ink 7 peerOptional requires >=6.1.2)
- ink hoisted to root devDeps so workspace-private peer-dep contention
doesn't push ink-link/spinner/gradient into nested workspace
installs (which would skip transitive resolution for terminal-link)
Workflow + image + installer alignment:
- .nvmrc 20 -> 22
- Dockerfile node:20-slim -> node:22-slim
- CI test matrix drops 20.x (keeps 22.x + 24.x)
- terminal-bench workflow Node 20 -> 22
- Linux/Windows install scripts upgrade their Node version targets
Documentation alignment:
- README.md badge + prerequisites
- AGENTS.md, CONTRIBUTING.md, docs/users/quickstart.md,
docs/users/configuration/settings.md, docs/developers/contributing.md,
docs/developers/sdk-typescript.md, docs/users/extension/extension-releasing.md,
packages/sdk-typescript/README.md, packages/zed-extension/README.md,
scripts/installation/INSTALLATION_GUIDE.md
Test gating:
- Two AuthDialog/AskUserQuestionDialog tests that drive <SelectInput>
through ink-testing-library now race ink 7's frame-throttled input
delivery and land on the wrong option. The maintainers had already
marked one of them unreliable (skip on Win32 + CI+Node20). Extend
that gate to cover all environments until upstream
ink-testing-library ships an ink-7-compatible release that flushes
input deterministically. The other test now uses it.skip with the
same comment. No business code changes.
Verified locally:
- npm run typecheck across all workspaces: clean
- npm run lint (root): clean
- npm run test --workspaces:
cli 312/312 files, 4918 passed, 9 skipped
core 266/266 files, 6836 passed, 3 skipped
webui 6/6, 201 passed
sdk 40/40, 283 passed, 1 skipped
- npm ls ink: single ink@7.0.2 instance across all peer deps
- single react@19.2.4 instance
Generated with AI
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
* chore: align Node 22 floor across all shipping artifacts
Reviewer (tanzhenxin) flagged five surfaces where the >=22 engine bump
leaked: SDK package metadata, web-templates engines, /doctor runtime
check, main bundler target, and SDK bundler target. Each was a separate
escape hatch letting Node 18/20 consumers install or run the artifact
on an unsupported runtime.
- packages/sdk-typescript/package.json: engines.node >=18.0.0 -> >=22.0.0
- packages/web-templates/package.json: engines.node >=20 -> >=22
- packages/cli/src/utils/doctorChecks.ts: MIN_NODE_MAJOR 20 -> 22
- esbuild.config.js: target node20 -> node22 (main CLI bundle)
- packages/sdk-typescript/scripts/build.js: target node18 -> node22 (esm + cjs)
- packages/cli/src/utils/doctorChecks.test.ts: rename test label to v22+
Generated with AI
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
* ci(e2e): bump E2E workflow Node matrix to 22.x
Reviewer (tanzhenxin) flagged that e2e.yml still pinned node-version
20.x while root engines is now >=22, so every E2E run on push would
either fail at npm ci with engine error or silently exercise the bundle
on a runtime that's no longer in ci.yml's test matrix.
The macOS job in the same workflow already reads .nvmrc (which is 22)
so this only updates the Linux matrix.
Generated with AI
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
* fix(deps): drop root wrap-ansi override so ink 7 gets its declared dep
Reviewer (tanzhenxin) flagged that the root overrides.wrap-ansi: 9.0.2
predates this upgrade and forces every consumer (including ink) to v9,
while ink 7 declares wrap-ansi: ^10.0.0. The lockfile had no nested
install under node_modules/ink/, so ink 7 was running with a transitive
dep one major below its declared minimum.
Dropping the global override lets ink resolve its own wrap-ansi 10
nested install (now visible in the lockfile under
node_modules/ink/node_modules/wrap-ansi), while the cli package's own
direct `wrap-ansi: 9.0.2` dependency keeps the cli code path
(TableRenderer.tsx) on the version it has been tested against. The
nested cliui override is preserved for yargs which still needs v7.
Verified via `npm ls wrap-ansi`:
- ink@7.0.2 -> wrap-ansi@10.0.0 (newly nested)
- @qwen-code/qwen-code -> wrap-ansi@9.0.2 (unchanged)
- yargs/cliui -> wrap-ansi@7.0.0 (unchanged)
Generated with AI
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
* test(InputPrompt): un-skip placeholder ID reuse after deletion
Reviewer (tanzhenxin) flagged that the new it.skip on the
'should reuse placeholder ID after deletion' test was undisclosed in
the PR description and removed coverage of real product behavior
(freePlaceholderId / bracketed-paste backspace path) without a
TODO(#NNNN) link.
Their argument was sound: the skip rationale pointed at ink 7's input
throttle, but this same file just bumped the wait helper from 50ms to
150ms specifically to give ink 7 frame time. Re-running the test under
the bumped wait shows it passes reliably (5/5 runs in the full-file
context, 9/10 alone), so the skip was masking the throttle-flake that
the wait bump already addresses, not a real product bug.
Drop the it.skip and the now-stale comment so coverage of the
freePlaceholderId reuse logic is restored.
Generated with AI
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
* test(InputPrompt): bump first prompt-suggestion test wait to 350ms
The "accepts and submits the prompt suggestion on Enter when the buffer
is empty" test is the first in its describe block, so it pays the
renderer cold-start cost. On macOS-22.x CI runners that pushes the
Enter → onSubmit microtask past the default 150ms post-Enter wait. Match
the 350ms initial render wait used immediately above to absorb the cold
start.
* Revert "test(InputPrompt): bump first prompt-suggestion test wait to 350ms"
This reverts commit 6add83b62e.
* test(InputPrompt): wait for followup suggestion debounce before pressing Enter
Root cause of the failing prompt-suggestion tests on macOS and Windows
CI is not flaky timing of the test post-Enter wait — it's the 300ms
debounce inside createFollowupController.setSuggestion (shared core).
The Enter handler reads followup.state.isVisible synchronously, so if
the debounce timer has not fired before stdin.write('\\r'), the
suggestion path is skipped and onSubmit never runs. No amount of
post-Enter wait can recover from that — the keypress was already
processed against stale state.
The original wait(350) only left ~50ms margin over the 300ms debounce,
which ink 7 / React 19.2 mount overhead consumed on slow Windows
runners. Bump the initial wait to 700ms (named SUGGESTION_VISIBLE_WAIT_MS)
to give the debounce timer + cold-start render a generous buffer.
Apply to the two sibling tests too — without the wait their "does not
accept" assertions pass trivially when suggestion is never visible,
which is a false green that hides regressions in the actual reject path.
* fix(deps): align cli wrap-ansi with ink 7 (9.0.2 -> ^10.0.0)
Ink 7 ships its own wrap-ansi@10. CLI's direct dep was pinned to 9.0.2,
causing two copies of wrap-ansi in node_modules and a potential drift in
CJK width / ANSI handling between ink's internal text wrapping and our
TableRenderer.
Upgrading the CLI's direct dep to ^10.0.0 lets npm dedupe to a single
wrap-ansi@10 used by both ink and TableRenderer. API surface is
identical; the only documented behaviour change is that tabs are
expanded to 8-column tab stops before wrapping, which TableRenderer
doesn't feed in.
TableRenderer test suite (43 tests) passes against wrap-ansi@10.
Generated with AI
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
* chore(deps): document @types/node 20.x pin in overrides
The override pinning @types/node to 20.19.1 (while engines require
Node >=22) is intentional: bumping to @types/node@22.x re-introduces
a Dirent<NonSharedBuffer> type regression that breaks
@qwen-code/qwen-code-core/sessionService tests.
Add a sibling "//@types/node" note inside `overrides` so future
maintainers see the rationale and know when to revisit the pin
without having to dig through PR #3860 history.
Generated with AI
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
* test(AskUserQuestionDialog): link skipped Submit-tab test to tracking issue
The 'shows unanswered questions as (not answered) in Submit tab' test
was switched to `it.skip` in the ink 7 upgrade because
`ink-testing-library@4.0.0` doesn't flush input deterministically
through ink 7's 30fps throttle.
Add a `// TODO(#4036):` marker so the skip is greppable and can be
re-enabled once upstream ships an ink-7-compatible release.
Refs #4036
Generated with AI
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
* fix(deps): move @types/node pin comment out of overrides block
npm's `overrides` field requires every key to be a real package name —
the `"//@types/node"` comment-key added in 205855875 trips Arborist with
"Override without name" and breaks `npm ci` across all CI jobs.
Move the explanation to a sibling top-level `"//overrides"` key, which
npm ignores at the document root. Same documentation value, no
override-parser collateral damage.
---------
Co-authored-by: 秦奇 <gary.gq@alibaba-inc.com>
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
277 lines
8.5 KiB
Markdown
277 lines
8.5 KiB
Markdown
# Quickstart
|
|
|
|
> 👏 Welcome to Qwen Code!
|
|
|
|
This quickstart guide will have you using AI-powered coding assistance in just a few minutes. By the end, you'll understand how to use Qwen Code for common development tasks.
|
|
|
|
## Before you begin
|
|
|
|
Make sure you have:
|
|
|
|
- A **terminal** or command prompt open
|
|
- A code project to work with
|
|
- An API key from Alibaba Cloud Model Studio ([Beijing](https://bailian.console.aliyun.com/) / [intl](https://modelstudio.console.alibabacloud.com/)), or an Alibaba Cloud Coding Plan ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index) / [intl](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)) subscription
|
|
|
|
## Step 1: Install Qwen Code
|
|
|
|
To install Qwen Code, use one of the following methods:
|
|
|
|
### Quick Install (Recommended)
|
|
|
|
**Linux / macOS**
|
|
|
|
```sh
|
|
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash
|
|
```
|
|
|
|
**Windows (Run as Administrator)**
|
|
|
|
```cmd
|
|
powershell -Command "Invoke-WebRequest 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat' -OutFile (Join-Path $env:TEMP 'install-qwen.bat'); & (Join-Path $env:TEMP 'install-qwen.bat')"
|
|
```
|
|
|
|
> [!note]
|
|
>
|
|
> It's recommended to restart your terminal after installation to ensure environment variables take effect.
|
|
|
|
### Manual Installation
|
|
|
|
**Prerequisites**
|
|
|
|
Make sure you have Node.js 22 or later installed. Download it from [nodejs.org](https://nodejs.org/en/download).
|
|
|
|
**NPM**
|
|
|
|
```bash
|
|
npm install -g @qwen-code/qwen-code@latest
|
|
```
|
|
|
|
**Homebrew (macOS, Linux)**
|
|
|
|
```bash
|
|
brew install qwen-code
|
|
```
|
|
|
|
## Step 2: Set up authentication
|
|
|
|
When you start an interactive session with the `qwen` command, you'll be prompted to configure authentication:
|
|
|
|
```bash
|
|
# You'll be prompted to set up authentication on first use
|
|
qwen
|
|
```
|
|
|
|
```bash
|
|
# Or run /auth anytime to change authentication method
|
|
/auth
|
|
```
|
|
|
|
Choose your preferred authentication method:
|
|
|
|
- **Alibaba Cloud Coding Plan**: Select `Alibaba Cloud Coding Plan` for a fixed monthly fee with diverse model options. See the [Coding Plan guide](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index) ([intl](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)) for setup instructions.
|
|
- **API Key**: Select `API Key`, then enter your API key from Alibaba Cloud Model Studio ([Beijing](https://bailian.console.aliyun.com/) / [intl](https://modelstudio.console.alibabacloud.com/)). See the API setup guide ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3023091) / [intl](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2974721)) for details.
|
|
|
|
> ⚠️ **Note**: Qwen OAuth was discontinued on April 15, 2026. If you were previously using Qwen OAuth, please switch to one of the methods above.
|
|
|
|
> [!note]
|
|
>
|
|
> When you first authenticate Qwen Code with your Qwen account, a workspace called ".qwen" is automatically created for you. This workspace provides centralized cost tracking and management for all Qwen Code usage in your organization.
|
|
|
|
> [!tip]
|
|
>
|
|
> To configure authentication, start Qwen Code and run `/auth`. Use `/doctor` to check your current configuration at any time. See the [Authentication](./configuration/auth) page for details.
|
|
|
|
## Step 3: Start your first session
|
|
|
|
Open your terminal in any project directory and start Qwen Code:
|
|
|
|
```bash
|
|
# optiona
|
|
cd /path/to/your/project
|
|
# start qwen
|
|
qwen
|
|
```
|
|
|
|
You'll see the Qwen Code welcome screen with your session information, recent conversations, and latest updates. Type `/help` for available commands.
|
|
|
|
## Chat with Qwen Code
|
|
|
|
### Ask your first question
|
|
|
|
Qwen Code will analyze your files and provide a summary. You can also ask more specific questions:
|
|
|
|
```
|
|
explain the folder structure
|
|
```
|
|
|
|
You can also ask Qwen Code about its own capabilities:
|
|
|
|
```
|
|
what can Qwen Code do?
|
|
```
|
|
|
|
> [!note]
|
|
>
|
|
> Qwen Code reads your files as needed - you don't have to manually add context. Qwen Code also has access to its own documentation and can answer questions about its features and capabilities.
|
|
|
|
### Make your first code change
|
|
|
|
Now let's make Qwen Code do some actual coding. Try a simple task:
|
|
|
|
```
|
|
add a hello world function to the main file
|
|
```
|
|
|
|
Qwen Code will:
|
|
|
|
1. Find the appropriate file
|
|
2. Show you the proposed changes
|
|
3. Ask for your approval
|
|
4. Make the edit
|
|
|
|
> [!note]
|
|
>
|
|
> Qwen Code always asks for permission before modifying files. You can approve individual changes or enable "Accept all" mode for a session.
|
|
|
|
### Use Git with Qwen Code
|
|
|
|
Qwen Code makes Git operations conversational:
|
|
|
|
```
|
|
what files have I changed?
|
|
```
|
|
|
|
```
|
|
commit my changes with a descriptive message
|
|
```
|
|
|
|
You can also prompt for more complex Git operations:
|
|
|
|
```
|
|
create a new branch called feature/quickstart
|
|
```
|
|
|
|
```
|
|
show me the last 5 commits
|
|
```
|
|
|
|
```
|
|
help me resolve merge conflicts
|
|
```
|
|
|
|
### Fix a bug or add a feature
|
|
|
|
Qwen Code is proficient at debugging and feature implementation.
|
|
|
|
Describe what you want in natural language:
|
|
|
|
```
|
|
add input validation to the user registration form
|
|
```
|
|
|
|
Or fix existing issues:
|
|
|
|
```
|
|
there's a bug where users can submit empty forms - fix it
|
|
```
|
|
|
|
Qwen Code will:
|
|
|
|
- Locate the relevant code
|
|
- Understand the context
|
|
- Implement a solution
|
|
- Run tests if available
|
|
|
|
### Test out other common workflows
|
|
|
|
There are a number of ways to work with Qwen Code:
|
|
|
|
**Refactor code**
|
|
|
|
```
|
|
refactor the authentication module to use async/await instead of callbacks
|
|
```
|
|
|
|
**Write tests**
|
|
|
|
```
|
|
write unit tests for the calculator functions
|
|
```
|
|
|
|
**Update documentation**
|
|
|
|
```
|
|
update the README with installation instructions
|
|
```
|
|
|
|
**Code review**
|
|
|
|
```
|
|
review my changes and suggest improvements
|
|
```
|
|
|
|
> [!tip]
|
|
>
|
|
> **Remember**: Qwen Code is your AI pair programmer. Talk to it like you would a helpful colleague - describe what you want to achieve, and it will help you get there.
|
|
|
|
## Essential commands
|
|
|
|
Here are the most important commands for daily use:
|
|
|
|
| Command | What it does | Example |
|
|
| --------------------- | ------------------------------------------------ | ----------------------------- |
|
|
| `qwen` | start Qwen Code | `qwen` |
|
|
| `/auth` | Change authentication method (in session) | `/auth` |
|
|
| `/doctor` | Check current authentication and environment | `/doctor` |
|
|
| `/help` | Display help information for available commands | `/help` or `/?` |
|
|
| `/compress` | Replace chat history with summary to save Tokens | `/compress` |
|
|
| `/clear` | Clear terminal screen content | `/clear` (shortcut: `Ctrl+L`) |
|
|
| `/theme` | Change Qwen Code visual theme | `/theme` |
|
|
| `/language` | View or change language settings | `/language` |
|
|
| → `ui [language]` | Set UI interface language | `/language ui zh-CN` |
|
|
| → `output [language]` | Set LLM output language | `/language output Chinese` |
|
|
| `/quit` | Exit Qwen Code immediately | `/quit` or `/exit` |
|
|
|
|
See the [CLI reference](./features/commands) for a complete list of commands.
|
|
|
|
## Pro tips for beginners
|
|
|
|
**Be specific with your requests**
|
|
|
|
- Instead of: "fix the bug"
|
|
- Try: "fix the login bug where users see a blank screen after entering wrong credentials"
|
|
|
|
**Use step-by-step instructions**
|
|
|
|
- Break complex tasks into steps:
|
|
|
|
```
|
|
1. create a new database table for user profiles
|
|
2. create an API endpoint to get and update user profiles
|
|
3. build a webpage that allows users to see and edit their information
|
|
```
|
|
|
|
**Let Qwen Code explore first**
|
|
|
|
- Before making changes, let Qwen Code understand your code:
|
|
|
|
```
|
|
analyze the database schema
|
|
```
|
|
|
|
```
|
|
build a dashboard showing products that are most frequently returned by our UK customers
|
|
```
|
|
|
|
**Save time with shortcuts**
|
|
|
|
- Press `?` to see all available keyboard shortcuts
|
|
- Use Tab for command completion
|
|
- Press ↑ for command history
|
|
- Type `/` to see all slash commands
|
|
|
|
## Getting help
|
|
|
|
- **In Qwen Code**: Type `/help` or ask "how do I..."
|
|
- **Documentation**: You're here! Browse other guides
|
|
- **Community**: Join our [GitHub Discussion](https://github.com/QwenLM/qwen-code/discussions) for tips and support
|