主题：附录 B. Qwen Code 兼容性
难度级别：中级
预计学习时间：6-8 小时（理论 + 实践）
前置条件： 基本熟悉 Qwen Code 及其 CLI 界面
理解 Git 基础和仓库结构
具有 Markdown 文件和配置的工作经验
具备 Python 或其他脚本语言的基础知识
理解 CI/CD 概念（建议）
学习目标： 区分三个成熟度级别（标准、建议、前沿），并正确按实现层对生产流程进行分类
在 .qwen/commands/ 结构中创建用户自定义命令，使用正确的命名和停止契约
设计可复现的检查，以项目脚本形式呈现，不依赖于模型回答的说服力
配置 Qwen Code 钩子（PreToolUse、PostToolUse、UserPromptSubmit 等）用于护栏（guardrails）
通过 MCP 服务器集成外部生产 API，使用工具许可列表和密钥保护
概述：附录 B 确立了 Qwen Code 内置功能与团队需自行实现流程之间的关键边界。课程第二卷描述了围绕 Qwen Code 的生产流程：部分内置于工具中，部分需要用户自定义命令、技能、钩子、MCP 服务器或普通脚本。本学习指南围绕规范的三级成熟度标准——标准、建议和前沿——构建，该标准定义了对读者的期望和实现层。理解这一边界可防止将设计中的流程误认为标准 CLI 命令的错误，并允许在内置工具、项目配置和外部编排之间正确架构分配职责。
核心概念： 三级成熟度规范标准：一种分类系统，不评估想法质量，而是确定对读者期望的边界。标准——在普通 Qwen Code 中无需额外平台即可运行，课程基础材料，内置功能。建议——在重复流程中有用时可整理到项目中，需要仓库文件：用户自定义命令、技能、钩子或脚本。前沿——围绕 Qwen Code 的生产编排，需要外部 API、SRE 流程和模型预算的团队，通过外部编排器、MCP 和外部服务实现。
Qwen Code 内置层：无需额外配置即可按原样使用的基础功能：/plan（无编辑和 shell 执行的计划模式）、/review（具有确定性检查和并行审查代理的内置代码审查）、/skills（查看和显式运行技能）、/memory、/remember、/forget（管理内存和 QWEN.md）、/mcp 和 qwen mcp add（连接 MCP 服务器）、@path（将文件/目录添加到上下文）、!command（交互式会话中的 shell 命令）、qwen -p "..."（用于 CI 和脚本的无头运行）。
用户自定义命令：通过在 .qwen/commands/<namespace>/<command>.md 结构中创建 Markdown 文件来扩展 Qwen Code 的机制。命令以 /<namespace>:<<command> 调用，包含带 {{args}} 的提示、对 @specs/... 的引用和停止规则。允许复现第一卷命令（如 /clarify）的行为，而无需对其内置性的隐含假设。
项目脚本：以项目中普通脚本形式呈现的可复现检查，不依赖于模型。CI 的绿色状态应取决于检查代码，而非模型回答的说服力。示例：check_coverage.py、validate_schema.py、mutate_specs.py、run_duel.py、用于预算的 compile.py。
钩子（hooks）：Qwen Code 用于实现护栏（guardrails）的官方事件：PreToolUse、PostToolUse、UserPromptSubmit、SessionStart、Stop、SubagentStop、Notification、PreCompact 等。需要使用当前文档中的精确事件名称，而非自由变体。
MCP 服务器和外部 API：集成生产 API（Grafana、PagerDuty、Kubernetes、Jira）而不将其变为无限制 shell 命令的方法。需要工具许可列表（allowlist）：仅用于分类的读取权限、用于安全操作的单独写入工具、明确的确认和回滚条件、禁止在提示、痕迹和 QWEN.md 中传递密钥。
生产流程角色：验证者（Verifier）——通过 /review、单独会话、子代理或脚本投票。实现者（Implementor）——在计划批准后通过 Qwen Code 以默认/自动编辑模式投票。安全员（Safety）——在 critical_risk 时通过单独会话或爆炸半径检查脚本行使否决权。协调者（Coordinator）——无投票权的记录员，由人员、CI 或外部编排器实现。
文件仲裁（tribunal）：非内置命令；组合 /review、脚本、报告和 validation.md 中的规则，解决同时编辑时的冲突。
规范网关（spec ci）：GitHub Actions 或本地脚本，可仅将 qwen -p 用作辅助层，但主要检查为确定性代码。
预算守护者（budget keeper）：外部服务或脚本；Qwen Code 本身不管理模型层级的每日配额。
练习： 标题：按成熟度级别对流程进行分类
问题：给定五个生产流程：(1) 运行 /plan 进行任务分解，(2) 通过脚本 check_coverage.py 自动检查测试覆盖率，(3) 与 Kubernetes 集成进行滚动部署，(4) 使用 /review 进行代码审查，(5) 使用用户自定义命令 /sdd:validate 检查规范。按规范标准（标准、建议、前沿）对每个流程进行分类。为每种情况提供理由。
解答：1) 标准——/plan 是 Qwen Code 的内置命令，无需额外文件。2) 建议——脚本 check_coverage.py 需要在仓库中创建文件，无需模型即可复现，在重复使用时有用。3) 前沿——Kubernetes 是外部编排器，需要生产基础设施、SRE 流程。4) 标准——/review 内置于 Qwen Code，具有确定性检查。5) 建议——用户自定义命令需要创建 .qwen/commands/sdd/validate.md，属于项目层。关键标准：是否需要仓库中的文件（建议）或外部服务（前沿）。
难度：初级
标题：创建用户自定义命令 clarify
问题：第一卷中使用了 /clarify 命令在计划前澄清需求。它未内置于 Qwen Code。为复现第一卷行为的用户自定义命令 /sdd:clarify 创建文件结构和 Markdown 文件内容。定义停止契约和 {{args}} 及 @specs/ 的使用规则。
解答：结构：.qwen/commands/sdd/clarify.md。文件内容应包括：(1) 目标描述——在计划前澄清模糊需求；(2) 带 {{args}} 的模板用于传递上下文；(3) 引用 @specs/ 加载规范；(4) 停止规则——当所有歧义解决并形成澄清需求列表时命令停止；(5) 不开始计划或代码编辑的指令。调用示例：/sdd:clarify 'API 认证需求'。停止契约：达到'所有问题已澄清，答案以列表格式记录'状态时退出。
难度：中级
标题：设计 MCP 服务器实现安全集成
问题：团队使用 Grafana 进行监控，PagerDuty 进行告警。需要为 Qwen Code 提供对这些服务的访问，而不将其变为无限制的 shell 命令。设计具有工具许可列表的 MCP 服务器架构，定义写入操作的确认条件和密钥保护机制。
解答：MCP 服务器架构：(1) 仅读取工具：grafana_query_metrics（PromQL 查询）、grafana_list_dashboards、pagerduty_list_incidents、pagerduty_get_incident_details——用于分类和检查，无需确认。(2) 需明确确认的写入工具：pagerduty_acknowledge_incident（需确认并说明原因）、pagerduty_escalate_incident（需双重确认）。(3) 回滚条件：对于 pagerduty_create_incident——检查必填字段、每小时 5 个事件限制、5xx 错误时自动取消。(4) 密钥保护：API 密钥存储在服务器环境变量中，不传递到提示中；QWEN.md 不包含带凭据的端点地址；请求日志屏蔽授权头。(5) 配置：qwen mcp add pagerduty-ops --url http://localhost:3001/sse --tools allowlist:grafana_query_metrics,grafana_list_dashboards,pagerduty_list_incidents,pagerduty_acknowledge_incident。
难度：高级
标题：配置钩子实现护栏
问题：需要为以下场景实现护栏：(1) 禁止执行包含 rm -rf / 或 DROP TABLE 的 shell 命令，(2) 在执行前记录所有对外部 API 的访问，(3) 在内存压缩前归档会话上下文。选择合适的 Qwen Code 官方事件并描述钩子配置。
解答：(1) PreToolUse——检查 shell_execute 工具参数中是否存在禁止模式：rm -rf /、DROP TABLE、TRUNCATE。匹配时——取消执行并通知用户。(2) PreToolUse 或 PostToolUse——记录对外部 API 的访问：在结构化日志中固定端点、方法、时间戳。(3) PreCompact——在内存压缩前将当前会话上下文归档到文件 .qwen/archive/sessions/<timestamp>.md。重要：使用文档中的精确事件名称——PreToolUse、PostToolUse、PreCompact——而非 pretooluse 等变体。钩子配置需与 Qwen Code 当前文档核对格式和参数。
难度：中级
标题：在 Spec CI 中划分职责
问题：团队希望在每次 PR 时自动检查规范。讨论两种方法：(A) 使用 qwen -p '检查规范' 作为主要机制，(B) 创建带确定性检查的脚本 validate_schema.py，而 qwen -p 仅用于生成报告。应用附录 B 的原则选择正确方法并描述架构。
解答：正确方法是 (B)，对应建议/前沿层。架构：(1) 主要检查——脚本 validate_schema.py，检查 JSON Schema、链接完整性、标识符重复。CI 绿色状态仅取决于检查代码。(2) 辅助层——qwen -p '根据 validate_schema.py 结果生成可读报告'，仅用于格式化输出，不影响通过/失败。(3) GitHub Actions 集成：'Validate Schema' 步骤运行 python scripts/spec_ci/validate_schema.py --strict；'Generate Report' 步骤可选使用 qwen -p 改善可读性。(4) 原则：绿色状态不应取决于模型回答的说服力——这是附录 B 对项目脚本的关键要求。
难度：中级
案例研究： 标题：开发团队从隐式假设迁移到明确的 Qwen Code 架构
场景：12 人团队半年以来使用 Qwen Code 开发微服务平台。团队成员非正式使用 /clarify、/specify、/tasks 等命令，认为它们是 Qwen Code 内置的。新成员入职时不断出现冲突：命令在新项目中不工作、会话间行为不同、无法在 CI 中复现流程。
挑战：关于命令内置性的隐式假设导致：(1) 流程碎片化——每个开发者对步骤有不同理解；(2) 无法在 CI 中复现——交互模式工作的命令在无头模式中不存在；(3) 缺乏文档——停止契约是口头的；(4) 扩展风险——新成员花费数周弄清'我们这里怎么工作'。
解决方案：团队按附录 B 方法论进行审计。步骤 1：按规范标准对所有使用流程进行分类。发现 /plan 和 /review 是标准，而 /clarify、/specify、/tasks、/validate 需要创建用户自定义命令。步骤 2：创建 .qwen/commands/sdd/ 结构，namespace 为 'sdd'（Software Design Document），包含 clarify.md、specify.md、tasks.md、validate.md、constitution.md。每个文件包含明确的停止契约、带 {{args}} 的模板、对 @specs/ 的引用。步骤 3：将确定性检查转移到项目脚本：validate_schema.py、check_coverage.py、mutate_specs.py。步骤 4：在 GitHub Actions 中配置 Spec CI，qwen -p 仅用于报告。步骤 5：文档化边界：README 中明确说明哪些命令是内置的，哪些是项目的。
结果：3 周后：入职时间从 2 周缩短到 2 天；100% CI 检查可复现；团队间流程语言统一；通过 Git 实现命令版本控制的能力。团队扩展到 20 名开发者而流程未退化。关键思维转变：从'Qwen Code 什么都会'到'我们明确设计 Qwen Code 做什么，什么是我们项目的'。
经验教训： 关于内置性的隐式假设——团队流程碎片化的主要来源
规范标准——不仅是架构工具，也是沟通工具；它同步开发者间的期望
带明确停止契约的用户自定义命令创建成本更高，但扩展免费
CI 绿色状态应取决于代码而非模型——这难以接受，但对生产至关重要
相关概念： 三级成熟度规范标准
用户自定义命令
项目脚本
规范网关（Spec CI）
标题：通过 MCP 服务器为金融科技公司集成 SRE 流程
场景：受监管要求的金融科技公司使用 Qwen Code 开发支付网关。需要与 PagerDuty 集成进行事件升级、Grafana 用于部署前指标检查、内部 API 用于审计。提示中的 API 密钥直接 shell 命令造成关键安全风险。
挑战：监管要求：(1) 所有生产系统操作必须可审计；(2) API 密钥不得进入日志和提示；(3) 事件升级需双重确认；(4) 回滚必须在 5 分钟内可能。同时开发者希望不切换上下文就使用 Qwen Code 处理运维任务。
解决方案：按附录 B 原则（前沿层）的架构：(1) Go 编写的 MCP 服务器 'ops-bridge'，部署在 VPC 内，8 个工具的许可列表。仅读取：grafana_query_metrics、pagerduty_list_incidents、pagerduty_get_incident_details、audit_log_query。需确认的写入：pagerduty_acknowledge_incident（需原因 ≥ 20 字符）、pagerduty_escalate_incident（需 SMS 的 approval_code）、audit_log_append（仅结构化记录）。(2) 通过 PreToolUse 钩子禁止对生产的 shell 访问——阻止任何包含 kubectl、ssh、curl 到生产域的 !command。(3) 密钥：API 密钥在 HashiCorp Vault 中，MCP 服务器通过 mTLS 认证；QWEN.md 仅包含工具描述，绝不包含带凭据的端点 URL。(4) PostToolUse 钩子将所有调用记录到结构化审计跟踪。(5) 通过外部 Budget Keeper 进行预算管理——独立服务，跟踪模型调用成本，超出每日配额时阻止。
结果：通过监管审计，AI 工具方面无意见。通过 Qwen Code 访问指标，事件响应时间缩短 40%。零凭据泄露事件。模型预算可控可预测。团队获得开发和运维的'单一窗口'，不违反安全边界。
经验教训： 通过 MCP 和许可列表使用生产 API——受监管行业的唯一可接受方式
PreToolUse/PostToolUse 钩子——对纵深防御至关重要，但需文档中的精确事件名称
外部 Budget Keeper 是必需的，因为 Qwen Code 不管理每日配额——按定义这是前沿层
QWEN.md 绝不应包含敏感数据，即使是加密形式
相关概念： MCP 服务器和外部 API
钩子（Hooks）
预算守护者（Budget Keeper）
前沿——成熟度级别
学习技巧： 创建物理或数字'决策地图'：对任何生产流程问'这能用 Qwen Code 内置命令完成吗？'→ 如果可以，是标准；如果需要项目文件但不需要外部服务，是建议；如果需要 Kubernetes、Grafana、外部 API，是前沿
在真实仓库上练习：创建 .qwen/commands/demo/ 含 2-3 个用户自定义命令，调用它们，检查 git clone 到另一目录后的可复现性
为理解钩子：建立测试项目，配置 PreToolUse 和 PostToolUse 日志记录，分析不同操作产生的事件——这将提供拦截点的直觉
通过安全视角学习 MCP：为每个添加的工具明确记录'最坏情况是什么'以及许可列表/确认如何防止它
结对学习：一人将流程设计为'全部内置 Qwen Code'，另一人为'全部外部脚本'；然后应用规范标准进行合成——这训练架构思维
记录'边界日志'：记录您或同事假设命令是内置的而实际是项目的情况——这是常见错误，其模式会重复
对于无头模式（qwen -p）：在 GitHub Actions 或 GitLab CI 中配置最小 CI 流水线，感受交互式会话和自动运行之间的差异
研究第二卷角色（验证者、实现者、安全员、协调者）与 Qwen Code 具体机制之间的关系——为您的项目创建对应表
额外资源： Qwen Code 文档——命令：https://qwenlm.github.io/qwen-code-docs/en/users/features/commands/
Qwen Code 文档——无头模式：https://qwenlm.github.io/qwen-code-docs/en/users/features/headless/
Qwen Code 文档——钩子：https://qwenlm.github.io/qwen-code-docs/en/users/features/hooks/
Qwen Code 文档——技能：https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/
Qwen Code 文档——内存：https://qwenlm.github.io/qwen-code-docs/en/users/features/memory/
Qwen Code 文档——MCP：https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/
Qwen Code 文档——审批模式：https://qwenlm.github.io/qwen-code-docs/en/users/features/approval-mode/
Qwen Code 文档——代码审查：https://qwenlm.github.io/qwen-code-docs/en/users/features/code-review/
GitHub Spec Kit：https://github.com/github/spec-kit
AWS Kiro 文档概述：https://aws.amazon.com/documentation-overview/kiro/
OWASP LLM 应用十大风险：https://owasp.org/www-project-top-10-for-large-language-model-applications/
Google SRE 书籍：https://sre.google/sre-book/
古德哈特定律（维基百科）：https://en.wikipedia.org/wiki/Goodhart%27s_law
MCP（模型上下文协议）规范：建议学习 Anthropic 官方规范以深入理解 MCP 服务器架构
总结：附录 B 确立了 Qwen Code 内置功能与团队需自行实现流程之间的架构边界。关键工具是三级成熟度规范标准（标准、建议、前沿），它定义了期望和实现层。内置命令（/plan、/review、/skills、/memory、/mcp、@path、!command、qwen -p）按原样使用。用户自定义命令需要创建 .qwen/commands/<namespace>/<command>.md 并带明确停止契约。项目脚本确保独立于模型的可复现性。钩子通过 Qwen Code 官方事件实现护栏。带工具许可列表的 MCP 服务器安全集成外部 API。理解这一边界可防止内置性隐式假设的错误，确保流程可扩展，并使 Qwen Code 的生产使用可预测且可审计。