Qwen Code 贡献者实战指南：从本地构建、测试到 PR 规范的完整开发工作流

Qwen Code 贡献者实战指南：从本地构建、测试到 PR 规范的完整开发工作流

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code

本文基于 qwen-code 仓库的官方贡献文档 contributing.md，系统梳理该项目的贡献流程与 PR 评审标准、本地开发环境的搭建与构建流程、单元测试与集成测试的完整跑法，以及 VS Code 调试、文档站点本地预览和沙箱发布的实操细节。读完本文，你可以独立完成 qwen-code 的克隆、构建、测试、调试全流程，并按项目标准提交一个能通过所有自动化检查的 Pull Request。

贡献流程与 PR 评审标准

代码评审要求

qwen-code 对所有提交（包括项目维护者本人的提交）都要求经过代码评审，评审通过 GitHub Pull Request 完成。任何绕过 PR 的直接推送都不被接受，这一点决定了贡献者必须习惯"先讨论、后写码"的工作方式。

六条 PR 准则

项目对 PR 设定了明确的准入标准，不达标的 PR 可能会被直接关闭。以下六条准则必须逐条对照：

1. 必须关联已有 Issue：所有 PR 都应当链接到 tracker 中已存在的 issue，确保每个改动在动手之前已经过讨论、并与项目目标对齐。

   • Bug 修复类 PR：链接到对应的 bug 报告 issue；
   • 功能类 PR：链接到已被维护者批准的功能请求或提案 issue。
   • 如果还没有对应的 issue，请先开一个，等待反馈后再开始编码。

2. 保持小而聚焦：项目偏好"原子化"的小 PR，一个 PR 只解决一个 issue 或添加一个自包含的功能。

   • 应该做：一个 PR 只修一个具体 bug，或只加一个具体功能；
   • 不应该做：把 bug 修复、新功能、重构等多类不相关改动塞进同一个 PR。
   • 经验法则：当 PR 改动量超过约1,200 行时就开始考虑拆分；超过约2,000 行的 PR 要么拆成一系列可独立评审、独立合并的小 PR，要么在 PR 描述中说明为什么这些改动必须一起落地。

3. 进行中的工作使用 Draft PR：如果想尽早获得反馈，使用 GitHub 的Draft Pull Request功能。这向维护者表明 PR 尚不准备正式评审，但开放讨论和初步反馈。

4. 确保所有检查通过：提交前必须运行npm run preflight，该命令会执行全部测试、lint 与样式检查（各检查项的完整拆解见下文代码质量门禁一节）。

5. 同步更新文档：如果 PR 引入了面向用户的变更（新命令、flag 变更、行为变化等），必须同时更新/docs目录下对应文档。特别地：新增或更新的设计文档必须同时包含完整英文版（<name>.md）和简体中文版（<name>.zh-CN.md），两者放在同一目录、同一个 PR 中提交，且结构、决策、约束与验收标准保持对齐，并加上互指的语言链接。具体格式要求见 设计文档规范（英文） 与 设计文档规范（简体中文）。

6. 清晰的提交信息与 PR 描述：PR 标题要清晰、有描述性，提交信息遵循 Conventional Commits 标准。

   • 好的 PR 标题：feat(cli): Add --json flag to 'config get' command
   • 坏的 PR 标题：Made some changes
   • PR 描述中要解释改动的"为什么"，并链接相关 issue（例如Fixes #123）。

开发环境搭建

前置条件

1. Node.js：
   • 开发环境要求 Node.js>=22。CLI 的 TUI 基于 Ink 7，该版本要求 Node 22；配套的 React 版本为react@^19.2.0系。仓库 package.json 中的engines字段明确声明了"node": ">=22.0.0"，根依赖中ink锁定为7.0.3，overrides中将react/react-dom统一为^19.2.4、@types/react为^19.2.0，与文档描述完全一致；
   • 生产环境运行 CLI 同样要求 Node.js>=22。
   • 可以使用 nvm 之类的工具管理 Node 版本。
2. Git

构建流程

克隆仓库（或使用你 fork 的地址）：

git clone https://gitcode.com/GitHub_Trending/qw/qwen-code cd qwen-code

安装 package.json 中定义的依赖以及根目录依赖：

npm install

构建整个项目（所有包）：

npm run build

这个命令通常会将 TypeScript 编译为 JavaScript、打包资源并让各包进入可执行状态。从 package.json 可以看到，build实际执行的是cross-env NODE_OPTIONS="--max-old-space-size=3072" node scripts/build.js，即把 Node 堆内存上限调到 3GB 后再由 scripts/build.js 驱动构建。该脚本内部维护了一个按依赖顺序排列的构建清单（源码注释中列出的顺序为：core → channels/base → 各 channel 适配器 → audio-capture → acp-bridge → sdk → web-shell → web-templates → cli → vscode-ide-companion → external-context 集成等），并支持--cli-only参数跳过 CLI 打包不需要的包。构建前脚本还会检查node_modules是否存在，缺失时自动执行一次npm install。

如果需要同时构建qwenCLI 工具和沙箱容器，在根目录运行：

npm run build:all

从 package.json 可见，build:all等价于npm run build && npm run build:sandbox && npm run build:vscode，其中build:sandbox由 scripts/build_sandbox.js 驱动。如果不需要沙箱容器，只跑npm run build即可跳过。

运行项目

构建完成后，从根目录运行：

npm start

实际入口是 scripts/start.js（package.json 中start指向node scripts/start.js）。

如果希望在 qwen-code 目录之外运行源码构建产物，可以用：

npm link path/to/qwen-code/packages/cli

这样就能直接以qwen命令调用。package.json 中声明的bin映射为"qwen": "scripts/cli-entry.js"，即qwen命令最终落在 scripts/cli-entry.js。

测试体系：单元测试与集成测试

项目包含两类测试：单元测试和集成测试。

单元测试

执行项目单元测试套件：

npm run test

该命令会运行位于packages/core和packages/cli等目录中的测试。提交任何改动前务必确保测试通过；更全面的检查建议运行npm run preflight。

从 package.json 可以看到，根级test脚本实际是cross-env NODE_OPTIONS="--max-old-space-size=3072" npm run test --workspaces --if-present，即把test命令按 workspace 分发到各子包中、跳过没有test脚本的包，因此新增子包时只要在自己的package.json里定义test脚本即可自动纳入统一测试入口。

集成测试

集成测试用于验证 qwen-code 的端到端功能，不会随默认的npm run test一起运行。运行入口：

npm run test:e2e

package.json 中test:e2e的实际定义为cross-env VERBOSE=true KEEP_OUTPUT=true npm run test:integration:sandbox:none，即默认以开启详细输出、保留临时产物、无沙箱模式运行 integration-tests/ 目录下的套件。

仓库还提供了一组围绕沙箱矩阵的细分命令（package.json）：

• npm run test:integration:all：依次跑sandbox:none、sandbox:docker、sandbox:podman三种模式；
• npm run test:integration:sandbox:none/:docker/:podman：单独运行某一沙箱模式，其中 docker 模式会先执行npm run build:sandbox。

集成测试框架的完整说明（包括子集运行、按测试名过滤、诊断开关、产物目录结构、CI 工作流）见 集成测试文档，这里摘录几个高频操作：

# 只运行指定测试文件 npm run test:e2e list_directory write_file # 按测试名运行单个用例 npm run test:e2e -- --test-name-pattern "reads a file"

诊断技巧：

• KEEP_OUTPUT=true：保留测试过程中的临时文件以便检查，测试运行器会打印该次运行唯一目录的路径；
• VERBOSE=true：输出带来源标识的详细日志，格式形如--- TEST: <log dir>:<test-name> ---；
• 每次运行在.integration-tests/<run-id>/<test-file-name>.test.ts/<test-case-name>/下产出output.log等工件，方便定位失败现场。

代码质量门禁：preflight、lint 与 format

确保代码质量与格式一致性的一键入口是 preflight 检查：

npm run preflight

从 package.json 看，这条命令会依次执行：npm run clean（清理构建产物）→npm ci（干净安装依赖）→npm run format（Prettier 格式化）→npm run lint:ci（ESLint 零警告模式）→npm run build（全量构建）→npm run typecheck（所有 workspace 的类型检查 + integration-tests/tsconfig.json 的类型检查）→npm run test:ci（各 workspace 的 CI 测试 + scripts/tests/ 下的脚本测试）→npm run check:serve-fast-path-bundle（serve 快速路径打包校验）。这也解释了为什么 PR 指南要求"提交前必须跑 preflight"——它覆盖了 CI 上的全部关卡。

如果想单独执行格式化或 lint：

npm run format # Prettier 按项目风格格式化 npm run lint # ESLint 检查（eslint . --ext .ts,.tsx && eslint integration-tests） npm run lint:fix # 自动修复可修复的 lint 问题

ProTip（官方建议）：克隆仓库后创建一个 git pre-commit hook，保证每次提交都是干净的：

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

仓库内置的提交前检查：husky + lint-staged

其实仓库已经内置了提交前检查，无需手动建 hook。.husky/pre-commit 会在每次git commit时执行npm run pre-commit（允许紧急情况下git commit --no-verify跳过），该脚本对应 scripts/pre-commit.js，其实现是通过 API 直接调用lint-staged。而 package.json 中的lint-staged配置为：

• *.{js,jsx,ts,tsx}：执行prettier --write+eslint --fix --max-warnings 0 --no-warn-ignored；
• *.{mjs,cjs,json,md,yml,yaml,css,html}：执行prettier --write。

也就是说，只有暂存区中的文件会被格式化和 lint，而不是全仓库，提交速度远快于完整 preflight。日常开发建议：提交前靠 lint-staged 快速把关，合并前跑一次完整npm run preflight。

编码约定

• 遵循现有代码库中的编码风格、模式和约定；
• 特别注意 import 路径：项目用 ESLint 强制限制包与包之间的相对导入。仓库 eslint-rules/ 目录下提供了多条自定义规则，其中 no-relative-cross-package-imports.js 禁止跨包的相对路径 import，另有no-core-root-barrel-import.js、no-utils-upward-import.js、no-core-utils-upward-import.js、no-config-object-create.js等规则约束核心包的内部依赖方向。写跨包引用时请走包导出入口，不要写../../式的深层相对路径。

编辑器侧，仓库提供了现成的 VS Code 配置：.vscode/extensions.json 推荐安装vitest.explorer、esbenp.prettier-vscode、dbaeumer.vscode-eslint三个扩展；.vscode/settings.json 已把 Prettier 设为 TS/JS/JSON 的默认格式化器，并配置了 2 空格缩进与 80 列标尺。

项目结构

• packages/：项目的各个子包。
  • packages/cli/：命令行界面；
  • packages/core/：qwen-code 的核心后端逻辑；
  • 此外还有packages/channels/*（各渠道适配器）、packages/acp-bridge/、packages/web-shell/等，package.json 的workspaces字段列出了全部参与构建的包。
• docs/：全部项目文档。
• scripts/：构建、测试与开发任务工具脚本。

更详细的架构说明见 architecture.md。

文档站本地开发与预览

文档站点位于docs-site/，基于 Next.js + Nextra 构建（见 docs-site/README.md 与 docs-site/package.json）。前置条件：Node.js 22+、npm 或 yarn。

在docs-site目录下按顺序执行：

cd docs-site npm install # 安装依赖 npm run link # 把主 docs 目录的内容链接进文档站 npm run dev # 启动开发服务器

然后打开http://localhost:3000，即可看到带实时更新的文档站。对主docs目录中任何文档文件的修改都会立即反映在站点上。

从 docs-site/scripts/link-public-docs.mjs 的源码可以看到npm run link的实际行为：删除并重建content/目录，拷贝../docs/index.md和../docs/_meta.ts，再按PUBLIC_DOC_ROOTS列表将各公开文档根目录以符号链接形式挂入content/；内部规划、设计与 E2E 笔记不会进入文档站内容树。npm run dev则对应next --turbopack启动。

调试

VS Code 调试 CLI

仓库提供了完整的.vscode/launch.json调试配置：

1. F5 快速调试：Build & Launch CLI配置会以npm run build-and-start（先构建后启动）在集成终端中运行 CLI，并自动设置QWEN_SANDBOX=false，是最常用的调试入口；

2. 命令行挂起断点调试：在根目录运行

   npm run debug

   实际执行cross-env DEBUG=1 node --inspect-brk scripts/start.js（package.json），进程启动时即挂起等待调试器接入，随后可在 Chrome 中打开chrome://inspect连接；

3. Attach 附加调试：使用 launch.json 中的Attach配置（端口 9229）。该配置还通过remoteRoot/localRoot映射（/usr/local/share/npm-global/lib/node_modules/@qwen-code→${workspaceFolder}/packages）修正了在全局安装环境（如沙箱容器内）调试时的 source mapping；

4. 其他可用配置：Debug Test File（用--inspect-brk=9229 --no-file-parallelism调试指定单测文件）、Debug Integration Test File（对integration-tests下的文件启动 vitest 调试）、Launch CLI Non-Interactive（以-p <prompt> --output-format stream-json非交互模式运行）等，均可直接 F5 使用。

在沙箱容器内打断点

DEBUG=1 qwen

注意：如果项目的.env里设置了DEBUG=true，它不会影响qwen（被自动排除）。需要为 qwen 单独设置调试开关时，请使用.qwen/.env文件。

React DevTools 调试 TUI

CLI 的 UI 是 React 实现的，可以使用 React DevTools 调试。CLI 所用的 Ink 库与 React DevTools 4.x 兼容：

1. 以开发模式启动应用：

   DEV=true npm start

2. 安装并运行 React DevTools 4.28.5（或最新兼容的 4.x 版本）。全局安装：

   npm install -g react-devtools@4.28.5 react-devtools

   或直接用 npx 运行：

   npx react-devtools@4.28.5

   运行中的 CLI 应用会自动连接到 React DevTools。

沙箱（Sandboxing）

贡献文档中的沙箱章节目前仍标注为 TBD，但仓库中的脚本与配置已经透露了完整的启用方式：

• 最低要求是在~/.env中设置QWEN_SANDBOX=true，并确保有可用的沙箱提供方（如 macOS Seatbelt、docker 或 podman）；
• package.json 中的集成测试脚本展示了QWEN_SANDBOX的取值语义：false（不启用）、docker、podman分别对应三种运行模式，docker 模式会先构建沙箱镜像（npm run build:sandbox，由 scripts/build_sandbox.js 驱动）；
• package.json 的config.sandboxImageUri字段记录了预构建沙箱镜像的内部仓库地址（ghcr.io/qwenlm/qwen-code:<version>），package.json 的build:all会在本地构建时把镜像一并产出；
• VS Code 的Build & Launch CLI等调试配置默认注入QWEN_SANDBOX=false，方便在本地无容器环境下调试。

手动发布

项目会为每个 commit 向内部 registry 发布产物。如果需要手动切一个本地构建，按顺序执行：

npm run clean npm install npm run auth npm run prerelease:dev npm publish --workspaces

其中npm run clean对应 scripts/clean.js（清理构建产物）；npm publish --workspaces会遍历 package.json 定义的各 workspace 包逐个发布，这也是"先 auth、再 publish"顺序的原因——发布前必须先完成内部 registry 的鉴权。

小结

qwen-code 的贡献工作流可以归纳为一条清晰的流水线：先开 issue 讨论 → 拆出小而聚焦的 PR → 本地npm run build+npm run test快速验证 → 提交前 lint-staged 自动把关（husky pre-commit 已内置）→ 合并前npm run preflight全量自检 → PR 描述遵循 Conventional Commits 并链接 issue → 用户可见变更同步更新/docs（设计文档需中英双版本）。配合本文给出的 workspace 测试分发机制、集成测试沙箱矩阵、VS Code 调试配置与文档站本地预览等仓库实证细节，即可完整覆盖从第一次 clone 到 PR 合并的全部环节。

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code