1. 安装 Qwen Code
1.1 基本信息
核心功能
- 从描述构建功能:用简单语言告诉 Qwen Code 想构建的内容,它会制定计划、编写代码并确保正常运行。
- 调试和修复问题:描述 bug 或粘贴错误信息,Qwen Code 会分析代码库、识别问题并修复。
- 导航任何代码库:询问团队代码库相关问题,获得答案;维护项目结构感知,可从网络获取最新信息,通过 MCP 拉取 Google Drive、Figma、Slack 等外部数据。
- 自动化繁琐任务:修复 lint 问题、解决合并冲突、编写发布说明等,可通过单个命令在开发机器或 CI 中自动执行。
1.2 安装步骤
第一步:全局安装 CLI
npm install -g @qwen-code/qwen-code@latest
第二步:配置 Qwen Code
支持两种认证方式(公司电脑无法使用 Qwen OAuth,需用第二种):
- Qwen OAuth(免费):浏览器登录 qwen.ai 账户。
- OpenAI 兼容 API:使用 API 密钥(OpenAI 或兼容提供商/端点)。
配置时需输入:
API key:大语言模型供应商的密钥
Base URL:大语言供应商提供的模型地址
Model:大语言模型的名称
1.3 支持 Agent Skill
Agent Skill 将专业知识打包为可发现能力,含 SKILL.md(模型加载指令)及可选支持文件(脚本、模板)。
启动方式
1. 通过 CLI 标志
qwen --experimental-skills
2. 通过 settings.json
添加到 ~/.qwen/settings.json 或项目的 .qwen/settings.json:
{"tools":{"experimental":{"skills":true}}}
其他说明
- 存储位置:
~/.qwen/skills/
- 运行命令:
/skills <skill-name>
2. 安装 OpenSpec
2.1 基本信息
主流开源 SDD 工具对比
| 特性维度 | SpecKit | OpenSpec | BMAD |
|---|
| 核心理念 | '规范即代码源',开发者维护规范,代码由 AI 生成 | '规范锚定',规范作为长期资产贯穿 AI 辅助开发 | '规范优先',规范是人类与 AI 代理沟通的'单一事实来源' |
| 核心主张 | 四阶段流程(Specify->Plan->Tasks->Implement)将意图转代码 | 轻量级流程引擎,规范驱动开发注入现有代码库 | 定义智能体行为、交互和工具使用编排 |
| 工作流 | 严格线性流程 | 轻量级、非侵入式流程引擎 | 基础方法框架,需自行实现协作逻辑 |
| AI 工具兼容性 | 深度集成 GitHub Copilot,兼容差 | 支持 Claude Code、Cursor、Copilot 等十几种工具 | 基础构件,需大量自行集成 |
| 项目适配性 | 零到一(Zero to One)项目 | 无缝融入现有项目,不改变开发习惯 | 提供基础构件,需大量自行实现 |
OpenSpec 核心流程
┌────────────────────┐ │ Draft Change │ │ Proposal │ └────────┬───────────┘ │ share intent with your AI ▼ ┌────────────────────┐ │ Review & Align │ │ (edit specs/tasks) │◀──── feedback loop ──────┐ └────────┬───────────┘ │ │ approved plan │ ▼ │ ┌────────────────────┐ │ │ Implement Tasks │──────────────────────────┘ │ (AI writes code) │ └────────┬───────────┘ │ ship the change ▼ ┌────────────────────┐ │ Archive & Update │ │ Specs (source) │ └────────────────────┘
流程步骤:
- 起草变更提案(捕获规范更新意图)。
- 与 AI 助手审核提案至共识。
- 实施引用已批准规范的 task(AI 写代码)。
- 归档变更,将批准的更新合并回源规范。
2.2 安装步骤
前置条件
Node.js ≥ 20.19.0(通过 node --version 检查版本)。
第一步:全局安装 CLI
npm install -g @fission-ai/openspec@latest
openspec --version
第二步:项目中初始化 OpenSpec
cd my-project
openspec init
初始化过程:
- 提示选择原生支持的 AI 工具(Claude Code、CodeBuddy 等),其他 agent 依赖共享存根
AGENTS.md。
- 自动配置所选工具的斜杠命令,在项目根写入受管理的交接
AGENTS.md。
创建 openspec/ 目录,结构如下:
openspec - AGENTS.md - project.md
project.md 参考:一个 AI 编码的项目规范约束(project 规范)。
第三步:检查状态
openspec list
初始化后,主流 AI 工具可直接使用 /openspec 相关命令。
2.3 配置 Qwen Code
执行 openspec init 选择 AI 模型时选 qwen-code,会在当前目录创建 .qwen 目录,含三个配置文件:
.qwen - commands - openspec-apply.toml - openspec-archive.toml - openspec-proposal.toml
3. AI 编码实践
3.1 配置 OpenSpec 项目约束文件
openspec init 后生成:
AGENTS.md:定义 AI 模型 agent 的引导。
project.md:定义项目规范约束(可由 AI 生成)。
3.2 创建变更(五步骤)
1. 起草提案
启动 qwen-code(qwen 或 qwen --experimental-skills),提交变更请求:
/openspec-proposal 构建一个业务场景 agent 注册中心生成注册表,提供新增、编辑和查询功能,一个业务场景只有一个生效的智能
生成目录结构:
openspec - changes - 对应变更名称(AI 创建的名称) - design.md (提案设计) - proposal.md (变更提案) - tasks.md (完成任务所需任务)
2. 核实与审核
检查变更是否正确创建并审查提案:
$ openspec list
$ openspec validate add-profile-filters
$ openspec show add-profile-filters
3. 检查与完善
若 AI 理解偏差或提案不符需求,可:
- 与 AI 多轮交流修正提案设计。
- 手动修改
design.md、proposal.md 等文档。
4. 实施任务
文档完善后,执行实施:
/openspec-apply 指定开始实施的任务
5. 归档变更
验证无误后归档:
/openspec-archive 指定归档的变更