企业官网建设流程全解析

Qwen Code 内置 qc-helper 技能详解：让终端 AI 代理自带文档问答与配置调优能力

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

本文以 Qwen Code 仓库中的内置技能清单 packages/core/src/skills/bundled/qc-helper/SKILL.md 为主体，完整拆解qc-helper技能的功能定位、frontmatter 结构、文档索引、配置速查表与标准工作流，并结合仓库中的技能加载系统（packages/core/src/skills/skill-load.ts）与构建脚本（scripts/copy_bundle_assets.js）佐证该技能从源码到发布产物的完整交付链路。读完后你既能正确调用/qc-helper完成文档问答与 settings.json 修改，也能参考它的设计模式为自己的项目编写同类"文档问答型"技能。

一、qc-helper 是什么：开箱即用的文档问答与配置助手

qc-helper是 Qwen Code 随包内置（bundled）的技能之一。按其清单中的description字段定义：

Answer any question about Qwen Code usage, features, configuration, and troubleshooting by referencing the official user documentation. Also helps users view or modify their settings.json.

即它承担两件事：

1. 文档问答：回答关于 Qwen Code 使用方法、功能、配置与排障的任意问题，且答案必须基于官方用户文档；
2. 配置变更：在用户明确要求时，帮助用户查看和修改自己的settings.json。

调用方式为/qc-helper后接问题，清单中的argument-hint声明了参数占位符<question>，官方给出的两个典型用法示例是：

/qc-helper how do I configure MCP servers? /qc-helper change approval mode to yolo

清单的 frontmatter 中通过allowedTools精确圈定了该技能可调用的工具集合，共 5 个：

从工具集合可以看出该技能的安全边界：搜索与读取为主、仅允许编辑配置文件，不包含 shell 执行类工具——这是一个典型的"受限读写"技能设计。

二、清单字段逐行解读：frontmatter 的解析规则

qc-helper清单的完整 frontmatter 如下（摘自 SKILL.md）：

--- name: qc-helper description: Answer any question about Qwen Code usage, features, configuration, and troubleshooting by referencing the official user documentation. Also helps users view or modify their settings.json. Invoke with `/qc-helper` followed by a question, e.g. `/qc-helper how do I configure MCP servers?` or `/qc-helper change approval mode to yolo`. argument-hint: '<question>' allowedTools: - read_file - edit_file - grep_search - glob - read_many_files ---

各字段在解析链路中的行为可以从源码得到印证。解析入口是 skill-load.ts 中的parseSkillContent，其关键规则包括：

• frontmatter 切分：用正则^---\n([\s\S]*?)\n---(?:\n|$)([\s\S]*)$把 YAML 头与正文分开；缺失 frontmatter 会直接抛出Invalid format: missing YAML frontmatter。
• 必填字段：name与description必须存在且非空，否则分别抛出Missing "name" in frontmatter/Missing "description" in frontmatter。解析后还会调用validateSkillName(name)提前拒绝不安全命名——源码注释说明，name 会流入工具描述、schema 枚举与路径激活的<system-reminder>，模型会将这些文本视为可信内容，因此必须在入口处校验。
• 可选字段：allowedTools经parseAllowedToolsField解析为字符串数组（validateConfig中会校验数组元素均为字符串）；argument-hint按字符串直接提取，用于提示/qc-helper <question>这类调用形式。
• 清单还支持但 qc-helper 未使用的字段：源码中可见model、when_to_use、disable-model-invocation、user-invocable、paths（glob 门控，条件激活）、priority（排序提示，必须是有限数字，非法值仅告警而不阻断加载，见 parsePriorityField）。写自定义技能时这些字段都可以直接借用。
• 正文（body）：frontmatter 之后的 Markdown 全文作为技能正文注入给模型，qc-helper 的"文档索引 + 配置速查 + 工作流"正是通过正文实现的提示词工程。

源码注释还提醒：SKILL.md 的解析逻辑存在于两处——skill-load.ts（扩展技能路径）与SkillManager.parseSkillContent（project/user/bundled 路径），新增 frontmatter 字段必须两边同时接线，否则扩展技能作者会发现字段被静默丢弃。这解释了为什么qc-helper只用到了两个解析路径都稳定支持的核心字段。

三、文档索引：qc-helper 如何按需定位文档

清单正文的核心机制是一条明确规则：官方用户文档位于相对技能目录的docs/子目录中，技能用read_file工具把"技能基础目录路径 + 下表的相对文档路径"拼接后按需加载，并且只读与问题相关的文档，不要一次全读：

Example: If the user asks about MCP servers, readdocs/features/mcp.md(relative to this skill's directory).

完整的 Documentation Index 按七大类组织（以下路径均为相对技能目录的契约路径，保持清单原文）：

Getting Started

Configuration

Features

Daemon Mode

IDE Integration

Extensions

Reference & Support

运行时映射关系：这套"相对技能目录"的路径不是悬空的。构建脚本 copy_bundle_assets.js 中有专门注释说明：Copy user docs into qc-helper bundled skill so it can reference them at runtime. The qc-helper skill reads docs from adocs/subdirectory relative to its own directory. In the esbuild bundle this becomes dist/bundled/qc-helper/docs/.。也就是说，仓库中docs/users/目录（例如 docs/users/common-workflow.md、docs/users/integration-vscode.md，以及docs/users/features/、docs/users/configuration/等子目录）会在打包时被整体复制到dist/bundled/qc-helper/docs/，与技能本体同目录发布。这个设计让技能"自带知识库"：索引表中的docs/common-workflow.md在发布包中就解析为技能目录旁的docs/common-workflow.md，与docs/users/下的源文件一一对应。

四、配置速查：settings.json 的位置、优先级与格式

清单的"Configuration Quick Reference"部分告诉技能：当用户问配置问题时，首要参考是docs/configuration/settings.md，并给出了三份配置文件的定位表（原文保留）：

优先级（从高到低）：CLI args > env vars > system settings > project settings > user settings > defaults。

格式约定：JSON with Comments（JSONC，支持//与/* */注释），并支持环境变量插值（$VAR或${VAR}）。

常见配置分类速查表（原文保留）：

这张表本质上是给模型的一张"配置路由表"：先按类别落到配置键，再按 Reference 列去读对应文档确认类型、取值与默认值——避免凭记忆猜配置键。

五、标准工作流：回答问题的纪律与修改配置的五步流程

清单把技能行为收敛为两条明确流程。

回答问题（Answering Questions）

1. 识别主题：用上面的 Documentation Index 从用户问题中定位主题；
2. 按需加载：用read_file只加载相关文档，而不是全部读取；
3. 基于文档作答：给出清晰、简洁、以文档内容为依据的答案；
4. 诚实声明覆盖边界：如果文档没覆盖该问题，直接说明，并建议去哪里查。

修改配置（Helping with Configuration Changes）

1. 读文档：先读相关文档，弄清配置键的类型、允许取值与默认值；
2. 确认层级：若用户未指定，询问改哪个层级——user（~/.qwen/settings.json）还是 project（.qwen/settings.json）；
3. 读现状：用read_file查看目标 settings 文件当前内容；
4. 应用修改：用edit_file以正确的 JSON 语法写入变更；
5. 强制提醒：每次配置变更后必须提醒用户——"多数配置变更需要重启 Qwen Code（/exit后重新启动）才能生效，仅少数配置（如permissions）会被动态拾取"。

重要注意事项（Important Notes）

• 答案必须锚定在实际文档内容上，不得猜测或杜撰配置键；
• 展示配置示例时使用带注释的 JSONC 格式；
• 跨主题问题（例如"如何同时配置 MCP 与 sandbox"）要读取所有相关文档；
• 涉及从其他工具（Claude Code、Gemini CLI 等）迁移的问题，查docs/configuration/settings.md找等价配置键。

这四条注意事项是典型的"反幻觉护栏"写法：把"不许猜配置键"和"文档没覆盖就明说"写进技能提示词，而不是指望模型自觉。

六、实现佐证：qc-helper 如何从源码走到发布产物

结合仓库源码，可以把qc-helper的交付与加载链路完整串起来：

1. 源码位置：技能本体位于 packages/core/src/skills/bundled/qc-helper/，与review、loop、computer-use等内置技能并列，每个技能一个目录、以SKILL.md为清单（skill-paths.ts 中SKILL_FILE_NAME = 'SKILL.md'）。
2. 构建复制：copy_bundle_assets.js 的copyBundleAssets先把packages/core/src/skills/bundled/整体复制到dist/bundled/（跳过测试文件与 DESIGN.md），再把docs/users/复制到dist/bundled/qc-helper/docs/，补齐技能的运行时知识库。
3. 加载层级：index.ts 的文件头注释说明技能有四个加载层级，优先级project > user > extension > bundled，分别对应.qwen/skills/、~/.qwen/skills/、已安装扩展、以及随包内置目录。qc-helper属于最低优先级的 bundled 层——这意味着它默认恒可用，同时允许用户在 project/user 层用同名技能覆盖（shadow）它。skill-manager.ts 中SkillManager将 bundled 目录锚定在cli.js的同级磁盘位置（即dist/bundled/），并在加载时若发现目录缺失则记录"incomplete installation"告警，说明该目录是发布完整性的组成部分。
4. 目录扫描：loadSkillsFromDir 负责扫描技能目录：跳过崩溃重装遗留的.backup-<pid>-<timestamp>/.installing-<pid>-<timestamp>临时产物，忽略普通文件，对符号链接先校验其指向目录再解析SKILL.md，解析失败的技能记录错误后继续，不阻断其他技能加载。

从源码结构看，这套"清单 + 索引表 + 工作流"的写法可抽象为一个可复用的模式：把技能的知识库放在技能目录旁、在清单正文中维护一张"主题→文档相对路径"的索引表、用allowedTools收窄为读文件为主、把"基于文档作答 + 诚实声明未覆盖"写进强制纪律。需要自己为项目做一个"文档问答技能"时，qc-helper的这份 SKILL.md 就是最直接的参照模板。

七、小结

qc-helper是 Qwen Code 把"官方文档"直接变成"可调用问答与配置服务"的内置技能：frontmatter 声明身份与工具白名单，正文提供文档索引、配置速查与强约束工作流；构建脚本把docs/users/随包打进技能目录，四级技能加载体系保证它默认可用且可被用户级技能覆盖。对使用者，记住两点即可：提问用/qc-helper <question>并尽量指明主题（便于技能按需读文档）；要求改配置时明确指定 user 还是 project 层级，并在改完后按提醒重启。对开发者，这份清单连同 packages/core/src/skills/ 下的解析与加载实现，展示了 Qwen Code 技能系统的完整契约，可作为编写自有技能的设计范本。

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