ZCode 配置指南技能用于帮助用户或智能体定位和修改 ZCode 客户端的扩展配置。资料说明 ZCode 支持五类扩展资源以及 AGENTS.md 指令文件,本技能提供这些资源的配置位置与冲突解决规则。
用途 当用户需要配置 ZCode 的 MCP 服务器、斜杠命令、技能、Hooks、插件,或需要设置 AGENTS.md 指令文件时,可加载本技能;当配置失效或报错时,本技能会指向相应的诊断技能。
两种操作方式 用户可以通过客户端图形界面管理资源,包括设置中的插件管理、技能、子代理、MCP 以及输入框中的 / 菜单;智能体则可以直接用文件工具读取和编辑底层配置文件。
作用域与主要配置文件 用户级配置位于主目录,对所有工作区生效;工作区级配置位于仓库内,仅对该项目生效,并可通过版本控制与团队共享。用户配置文件为 ~/.zcode/cli/config.json,工作区配置文件为 <repo>/.zcode/config.json 或 <repo>/zcode.json。用户指令文件为 ~/.zcode/AGENTS.md,工作区指令文件为 <repo>/AGENTS.md。
五类资源概览 技能以目录加 SKILL.md 形式存在,优先级为用户级 ~/.zcode/skills/、~/.agents/skills/,工作区级 <repo>/.zcode/skills/、<repo>/.agents/skills/;同名技能以发现顺序第一个加载,用户级优先。 命令为 .md 文件,按规范化命令名去重,第一个匹配生效,用户级覆盖工作区级。 MCP 以 JSON 对象配置,用户配置写入 ~/.zcode/cli/config.json 的 mcp.servers,回退到 ~/.agents/mcp.json 的 mcpServers;工作区配置同理。同名服务器用户级覆盖工作区级,各作用域的服务器默认受信任并自动连接。 Hooks 通过 hooks.json 或配置对象设置,配置文件中的 Hooks 需要 hooks.enabled: true 才运行,插件提供的 Hooks 会自动追加。 插件以目录加 plugin.json 形式存在,从市场安装,启用状态保存在用户配置文件中,一个插件可贡献技能、命令、Hooks、MCP 服务器和代理。
AGENTS.md 合并顺序 ZCode 从当前工作目录向上搜索工作区 AGENTS.md 直至项目根目录,用户默认文件从主目录解析。两者都存在时,先注入用户级文件,再注入工作区文件,因此工作区指令可以收窄或覆盖用户默认值。引导流程可将 ~/.claude/CLAUDE.md 迁移到 ~/.zcode/AGENTS.md,内置 /init 命令针对当前工作区 AGENTS.md 创建或更新。
技能与命令的发现顺序 扫描顺序为:显式配置的根目录、用户 ~/.zcode/skills(或 commands)、用户 ~/.agents/skills、工作区 .zcode/skills(从当前目录到仓库根,每层都计入)、工作区 .agents/skills、已启用插件的根目录(优先级最低)。同一层内先扫描 .zcode 再扫描 .agents;更深层的工作目录位置优先于仓库根位置。技能以文件路径为身份,同名技能都会被发现,但只加载发现顺序中的第一个;命令以规范化名称为键,第一个匹配生效,嵌套目录用冒号连接名称,例如 review/code.md 变为 /review:code。
MCP 合并与自动连接 同名服务器的覆盖顺序为 CLI 覆盖 → 环境 → 用户 → 工作区 → 系统默认,用户级覆盖工作区级;插件提供的服务器构成基础层,并被显式配置覆盖。各作用域的 MCP 服务器均在会话开始时受信任并自动连接,可通过设置中的 MCP 查看状态和修复配置。
Hooks 要点 支持的事件共七种:SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、Stop。配置文件中的 Hooks 默认禁用,需设置 hooks.enabled: true;任一插件提供 Hook 时,Hook 运行器会自动启用。
插件要点 在设置中的插件管理(已安装与发现标签页)管理。插件目录清单位于 .zcode-plugin/plugin.json,也识别 .claude-plugin/ 和 .codex-plugin/ 兼容名称;最小清单只需 name,需匹配 ^[a-z0-9][a-z0-9._-]{0,127}$。组件字段包括 commands、skills、hooks、mcpServers、agents,各字段可为目录名、数组或内联;channels、lspServers、outputStyles、settings 字段会被记录但不执行。启用状态保存在用户配置文件的 plugins 下,内置插件可禁用但不可卸载。发现标签页可通过 + 按钮从 GitHub 仓库、Git URL、本地目录或文件添加市场。
选择配置位置 个人跨项目使用选用户级;团队或项目共享并纳入版本控制选工作区级;与其他读取 ~/.agents/skills/ 的编码代理共享技能时放在该目录,若要在 ZCode 内覆盖同名技能则用 .zcode/skills/。个人默认指令放 ~/.zcode/AGENTS.md,仓库规则放 <repo>/AGENTS.md。MCP 服务器按个人或团队需求选择作用域,因打开项目会自动连接其配置中的服务器,只应打开受信任的工作区。密钥不得提交到版本控制,应使用环境变量或本地设置。
诊断路由 配置被读取但无效或报错时,加载对应诊断技能,每个技能提供症状→原因→检查→修复流程:MCP 不连接、工具缺失、不受信任或超时用 diagnosing-mcp;技能未被发现、未触发、被遮蔽或禁用用 diagnosing-skills;命令缺失、被覆盖、frontmatter 错误或参数不替换用 diagnosing-commands;Hook 不触发、匹配器不匹配、脚本不可执行或意外阻塞用 diagnosing-hooks;插件未列出、安装失败、组件缺失或未启用用 diagnosing-plugins。