企业官网建设流程全解析

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 是一款运行在终端中的开源 AI 编程智能体（AI coding agent），其代码库采用 monorepo 结构，包含 CLI、核心逻辑、文档站点等多个子包。本文以仓库根目录下的 CONTRIBUTING.md 为骨架，系统梳理贡献者需要掌握的全部流程：Pull Request 的评审标准、Provider 预设（Provider Preset）的准入与实现模式、开发环境搭建、构建/测试/格式化工具链、文档站本地预览、VS Code 与 React DevTools 调试技巧，以及手动发布流程。读完本文，你将能够按照项目维护者的真实期望提交高质量 PR，并独立在本地完成从克隆、构建到调试、验证的完整开发闭环。

贡献总览：所有提交都必须经过评审

Qwen Code 采用与多数开源项目一致的做法：所有提交（包括项目成员自己的提交）都必须经过代码评审，评审通过 GitHub pull requests 机制完成。这一规定意味着即便是维护者本人也不存在"直接推送"的特权，每一行代码变更都要在合并前接受他人检视。

对于不合规的 PR，维护者明确保留关闭的权利（"PRs that do not meet these standards may be closed"），因此熟悉下文 7 条 PR 规范是贡献的第一步。

Pull Request 指南：7 条必须遵守的规范

1. 必须关联已有 Issue

所有 PR 都应关联到项目问题追踪器（issue tracker）中已存在的 Issue：

• Bug 修复：PR 应关联对应的 bug 报告 Issue；
• 新功能：PR 应关联已获维护者批准的功能请求或提案 Issue。

如果尚不存在对应 Issue，请先创建 Issue 并等待反馈，再开始写代码。这条规则确保任何变更在动笔之前就已经过讨论、与项目目标对齐，避免无效劳动。

2. 保持 PR 小而聚焦

项目偏爱小型、原子化的 PR——一个 PR 只解决一个 bug 或增加一个自包含的功能：

• ✅应该做：一个 PR 修复一个具体 bug，或增加一个具体功能；
• ❌不要做：把 bug 修复、新功能、重构等多个无关变更捆绑在同一个 PR 里。

文档给出了可操作的量化阈值：

3. 进行中的工作使用 Draft PR

如果希望尽早获得反馈，请使用 GitHub 的Draft Pull Request功能。它向维护者传达的信号是：该 PR 尚未准备好接受正式评审，但欢迎讨论和初步反馈。

4. 提交前确保所有检查通过

提交 PR 之前，务必在本地运行：

npm run preflight

该命令会运行全部测试、lint 及其他风格检查（其具体内容定义在根目录 package.json 的scripts字段中）。这是合并前的硬性门槛，任何未通过 preflight 的 PR 都会被拦下。

5. 用户可见变更必须更新文档

如果 PR 引入了面向用户的行为变化（例如新命令、修改的 flag、行为变更），必须同步更新/docs目录下的相关文档。Qwen Code 的文档体系非常庞大，仓库根目录的 docs 下按design/（设计文档）、developers/（开发者文档）、users/（用户文档）、plans/（实现计划）等维度组织，贡献者应根据变更影响面选择对应目录补充说明。

6. 附带截图或视频演示

为了帮助评审者快速理解变更并优先安排评审，请在 PR 中附上展示变更效果的截图或短视频：

• Bug 修复：展示修复前后的行为对比；
• 新功能：展示功能端到端运行的效果；
• 重构或纯内部变更：在演示小节中注明 "N/A — no user-facing change" 即可。

文档特别强调：带可视化演示的 PR 评审速度明显更快。

7. 规范的 Commit Message 与 PR 描述

PR 标题应清晰、具有描述性，Commit Message 遵循 Conventional Commits 标准：

• ✅ 好的标题：feat(cli): Add --json flag to 'config get' command
• ❌ 差的标题：Made some changes

PR 描述中要解释变更背后的"为什么"（why），并关联相关 Issue（例如Fixes #123）。

添加 Provider Preset：内置预设是高门槛的"背书"

这是贡献指南中技术含量最高的一节。内置预设（built-in preset）是一种背书（endorsement），而不仅仅是便利设施——用户会通过这些端点路由 API Key 和完整的 prompt 数据，因此准入门槛很高。

Tier 1 —— 内置预设的硬性要求

要将某个模型提供商做成内置预设，必须同时满足以下全部条件：

默认路径：自定义 Provider

对于不满足 Tier 1 的提供商，用户无需任何代码改动或项目背书，直接通过内置的custom-provider 流程接入（在 CLI 中通过/auth或/model命令选择 Custom Provider）即可。

Tier 1 预设的源码实现模式

一旦 Tier 1 预设获批，PR 应遵循现有openrouter.ts/requesty.ts的既有模式。这两个预设的实际源码位于 packages/core/src/providers/presets/openrouter.ts 与 packages/core/src/providers/presets/requesty.ts，贡献指南要求的新预设需对齐以下几点：

① 通过customHeaders实现归因（attribution）

以 Requesty 预设为例（见 requesty.ts）：

customHeaders: { 'HTTP-Referer': 'https://github.com/QwenLM/qwen-code.git', 'X-Title': 'Qwen Code', },

OpenRouter 预设则使用X-OpenRouter-Title（见 openrouter.ts），向提供商标识流量来自 Qwen Code。

② 实现ownsModel双重门禁（env key + hostname）

ownsModel用于判断某个模型配置是否归属该预设，采用"环境变量键 + 主机名"双重校验。以 openrouter.ts 为例：

ownsModel: (model) => { if (model.envKey !== OPENROUTER_ENV_KEY) return false; try { const host = new URL(model.baseUrl ?? '').hostname; return host === 'openrouter.ai' || host.endsWith('.openrouter.ai'); } catch { return false; } },

第一道门校验envKey必须是预设专属的OPENROUTER_API_KEY，第二道门校验baseUrl的主机名必须匹配提供商域名（含子域名），两者同时满足才算"归属"。requesty.ts中的实现完全同构（见 requesty.ts）。

③ 将环境变量键加入SECRET_ENV_VARS

文档中提到的packages/cli/src/serve/envSnapshot.ts在仓库中的实际路径为 packages/cli/src/serve/env-snapshot.ts。该模块定义了守护进程（daemon）在/workspace/env端点暴露的白名单环境变量——对于密钥类变量，只上报present: boolean（是否存在），绝不暴露值本身，连脱敏后的值也不输出。当前SECRET_ENV_VARS列表（见 env-snapshot.ts）为：

const SECRET_ENV_VARS = [ 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'GOOGLE_API_KEY', 'DASHSCOPE_API_KEY', 'OPENROUTER_API_KEY', 'QWEN_SERVER_TOKEN', ] as const;

可以看到OPENROUTER_API_KEY已在其中，新增 Tier 1 预设时需把其专属 env key 追加到此数组。文件同时维护了非密钥类白名单NONSECRET_ENV_VARS（如OPENAI_BASE_URL、NODE_EXTRA_CA_CERTS、TZ、LANG等，见 env-snapshot.ts），两者统一输出{ name, present }形状，客户端无需自行判断值是否安全可展示。

④ 配套测试断言

预设逻辑须有对应测试覆盖，文档点名的两个测试文件在仓库中的实际位置为：

• packages/cli/src/serve/auth.test.ts —— 覆盖守护进程认证相关的环境变量行为；
• packages/core/src/providers/tests/provider-config.test.ts —— 其中包含对ownsModel的断言用例（如校验 envKey 匹配、主机名前缀等场景，见 provider-config.test.ts）。

开发环境搭建与工作流

环境前置条件

推荐使用 nvm 管理 Node.js 版本。此外还需要安装Git。

克隆与构建

克隆仓库（可替换为你的 fork 地址）：

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

安装根目录依赖（同时安装package.json定义的依赖与根依赖）：

npm install

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

npm run build

该命令通常完成 TypeScript 到 JavaScript 的编译、资源打包并准备好可执行的包。具体构建细节可查阅 scripts/build.js 与根目录 package.json 中的 scripts 定义。

启用沙箱（Sandboxing）

沙箱机制（详见下文"Sandboxing"一节）强烈推荐启用。最低要求是在~/.env中设置QWEN_SANDBOX=true，并确保本机有可用的沙箱提供方（如macOS Seatbelt、docker或podman）。

需要同时构建qwen-codeCLI 工具与沙箱容器时，在根目录执行：

npm run build:all

若想跳过沙箱容器的构建，使用npm run build即可。

运行

构建完成后，在根目录执行：

npm start

即可从源码启动 Qwen Code 应用。如果希望在 qwen-code 目录之外运行源码构建版本，可以使用npm link建立链接：

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

之后便可以直接用qwen-code命令运行（详见 npm 官方文档中关于 npm-link 的说明）。

运行测试

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

单元测试

npm run test

该命令会运行packages/core与packages/cli目录下的测试。提交任何变更前请确保测试通过；更全面的检查建议运行npm run preflight。

集成测试

集成测试用于验证 Qwen Code 的端到端功能，默认不会随npm run test运行：

npm run test:e2e

集成测试框架的详细介绍见 docs/developers/development/integration-tests.md。该目录下还可以看到大量面向真实场景的测试用例，例如 integration-tests/cli/qwen-serve-streaming.test.ts、integration-tests/cli/write_file.test.ts 等，可作为编写端到端用例的参考。

Lint 与 Preflight 检查

统一执行代码质量与格式检查：

npm run preflight

该命令按根目录 package.json 的 scripts 定义，运行 ESLint、Prettier、全部测试及其他检查项。

ProTip：克隆后创建一个 Git pre-commit 钩子，确保每次提交都是干净的：

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

格式化

npm run format

使用 Prettier 按项目风格规范统一格式化代码。

Lint

npm run lint

单独运行 lint 检查。

编码规范与项目结构

• 遵循代码库中已有的编码风格、模式与约定；
• 导入路径需要特别注意：项目通过 ESLint 限制包之间的相对导入（仓库根目录 eslint.config.js 以及 eslint-rules 下的自定义规则正是为此服务，例如no-relative-cross-package-imports.js）。

项目目录结构概览：

packages/ 各独立子包 ├── cli/ 命令行界面 └── core/ Qwen Code 核心后端逻辑 docs/ 全部项目文档 scripts/ 构建、测试与开发任务的工具脚本

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

文档站本地开发

Qwen Code 的文档站点基于 Next.js 构建（见 docs-site）。在本地开发并预览文档变更的步骤如下：

前置条件：Node.js 22+，并具备 npm 或 yarn。

1. 进入文档站点目录：

   cd docs-site

2. 安装依赖：

   npm install

3. 链接主docs目录的文档内容：

   npm run link

   该命令在 docs-site 项目中创建从../docs到content的符号链接，使文档内容能够被 Next.js 站点伺服（实现脚本见 docs-site/scripts/link-public-docs.mjs）。

4. 启动开发服务器：

   npm run dev

5. 在浏览器打开 http://localhost:3000 即可看到文档站点，并实时反映修改。

此后对主docs目录中文档文件的任何修改都会立即反映到文档站点上。

调试

VS Code 调试

1. 在 VS Code 中按F5即可交互式调试 CLI（使用.vscode/launch.json中预置的启动配置）；

2. 或在根目录以调试模式启动 CLI：

   npm run debug

   该命令在packages/cli目录下执行node --inspect-brk dist/index.js，会暂停执行等待调试器连接；随后可在 Chrome 浏览器打开chrome://inspect连接调试器；

3. 在 VS Code 中使用 "Attach" 启动配置（位于.vscode/launch.json）附加到调试进程。

若要在沙箱容器内命中断点，运行：

DEBUG=1 qwen-code

注意：如果项目的.env文件中设置了DEBUG=true，由于自动排除机制它不会影响 qwen-code；请改用.qwen-code/.env文件存放 qwen-code 专属的调试设置。

React DevTools

CLI 的界面基于 React 构建（由 Ink 驱动），因此可以使用 React DevTools 调试。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）

CONTRIBUTING.md 中 "Sandboxing" 一节目前标注为TBD（待补充）。综合前文"启用沙箱"一节的说明可以确认：该项目通过QWEN_SANDBOX环境变量开关沙箱功能，并依赖macOS Seatbelt、docker或podman等外部提供方实现进程隔离，其完整设计细节可关注仓库后续文档更新。

手动发布（Manual Publish）

项目默认对每次提交向内部注册表发布产物。如果需要手动裁剪一个本地构建版本，按顺序执行以下命令：

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

各步骤含义：clean清理旧构建产物，install重新安装依赖，auth完成发布认证，prerelease:dev执行预发布检查与版本准备，最后npm publish --workspaces将各子包发布到注册表。

小结

为 Qwen Code 贡献代码的完整路径可以概括为：先开 Issue 对齐目标 → 小步提交、严格遵循 Conventional Commits → 本地跑通preflight→ 附上演示截图/视频 → 走 GitHub PR 评审。如果涉及新增 Provider 预设，则要格外注意 Tier 1 的背书门槛与customHeaders/ownsModel/SECRET_ENV_VARS/测试四件套的既定模式。本文所有命令与文件路径均可在仓库中直接验证，可作为贡献者的落地清单反复查阅。

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