Qwen Code 贡献指南从 PR 提交流程到开发环境搭建的完整实战手册【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-codeQwen 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中已存在的 IssueBug 修复PR 应关联对应的 bug 报告 Issue新功能PR 应关联已获维护者批准的功能请求或提案 Issue。如果尚不存在对应 Issue请先创建 Issue 并等待反馈再开始写代码。这条规则确保任何变更在动笔之前就已经过讨论、与项目目标对齐避免无效劳动。2. 保持 PR 小而聚焦项目偏爱小型、原子化的 PR——一个 PR 只解决一个 bug 或增加一个自包含的功能✅应该做一个 PR 修复一个具体 bug或增加一个具体功能❌不要做把 bug 修复、新功能、重构等多个无关变更捆绑在同一个 PR 里。文档给出了可操作的量化阈值变更行数处理建议约 1,200 行以内正常范围可直接提交超过约 1,200 行开始考虑拆分超过约 2,000 行必须拆分成一系列更小、可独立评审与合并的逻辑 PR或在 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 changesPR 描述中要解释变更背后的为什么why并关联相关 Issue例如Fixes #123。添加 Provider Preset内置预设是高门槛的背书这是贡献指南中技术含量最高的一节。内置预设built-in preset是一种背书endorsement而不仅仅是便利设施——用户会通过这些端点路由 API Key 和完整的 prompt 数据因此准入门槛很高。Tier 1 —— 内置预设的硬性要求要将某个模型提供商做成内置预设必须同时满足以下全部条件要求说明关联关系披露Affiliation DisclosurePR 作者必须披露与提供商之间的任何关联关系运营成熟度Operational Maturity公开运营且有实际运行时间的证明优先要求公开 SLA 或状态页真实用户需求Organic User Demand有社区需求的证据Issue、Discussion而非单纯的自荐数据与安全透明Data and Security Transparency提供商的数据处理实践必须公开文档化维护承诺Maintenance Commitment提供商团队承诺跟进 Qwen Code 协议变更默认路径自定义 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.tscustomHeaders: { HTTP-Referer: https://github.com/QwenLM/qwen-code.git, X-Title: Qwen Code, },OpenRouter 预设则使用X-OpenRouter-Title见 openrouter.ts向提供商标识流量来自 Qwen Code。② 实现ownsModel双重门禁env key hostnameownsModel用于判断某个模型配置是否归属该预设采用环境变量键 主机名双重校验。以 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。开发环境搭建与工作流环境前置条件环境Node.js 版本要求说明开发环境22Ink 7TUI 渲染库要求 Node 22react^19.2.0是配套的 peer 依赖生产环境22运行 CLI 任意22版本均可推荐使用 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_SANDBOXtrue并确保本机有可用的沙箱提供方如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 按项目风格规范统一格式化代码。Lintnpm 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。进入文档站点目录cd docs-site安装依赖npm install链接主docs目录的文档内容npm run link该命令在 docs-site 项目中创建从../docs到content的符号链接使文档内容能够被 Next.js 站点伺服实现脚本见 docs-site/scripts/link-public-docs.mjs。启动开发服务器npm run dev在浏览器打开 http://localhost:3000 即可看到文档站点并实时反映修改。此后对主docs目录中文档文件的任何修改都会立即反映到文档站点上。调试VS Code 调试在 VS Code 中按F5即可交互式调试 CLI使用.vscode/launch.json中预置的启动配置或在根目录以调试模式启动 CLInpm run debug该命令在packages/cli目录下执行node --inspect-brk dist/index.js会暂停执行等待调试器连接随后可在 Chrome 浏览器打开chrome://inspect连接调试器在 VS Code 中使用 Attach 启动配置位于.vscode/launch.json附加到调试进程。若要在沙箱容器内命中断点运行DEBUG1 qwen-code注意如果项目的.env文件中设置了DEBUGtrue由于自动排除机制它不会影响 qwen-code请改用.qwen-code/.env文件存放 qwen-code 专属的调试设置。React DevToolsCLI 的界面基于 React 构建由 Ink 驱动因此可以使用 React DevTools 调试。Ink 兼容 React DevTools 4.x 版本。以开发模式启动应用DEVtrue npm start安装并运行 React DevTools 4.28.5或最新兼容的 4.x 版本npm install -g react-devtools4.28.5 react-devtools或直接用 npx 运行npx react-devtools4.28.5运行中的 CLI 应用会自动连接到 React DevTools。沙箱机制SandboxingCONTRIBUTING.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考