diagnosing-commands

用途：定位并修复 ZCode 客户端中自定义斜杠命令（/command）的配置问题，目标是把任意 /command 故障归结为一个具体修复动作。用户可在输入框的 / 菜单（Commands 组）中查看命令，智能体则通过读取各位置的命令文件进行检查。\n\n两个常见误解：嵌套命令名用冒号连接（review/code.md 变成 /review:code，而不是 /review/code）；命令是 .md 文件，文件名即命令名。\n\n发现顺序（越靠前优先级越高）：显式配置的根目录；用户 ~/.zcode/commands；用户 ~/.agents/commands；工作区 .zcode/commands（从当前目录向上到仓库根，每一层都算）；工作区 .agents/commands；已启用插件的命令根（优先级最低）。同一层级内先扫描 .zcode 再扫描 .agents，子目录递归扫描，嵌套路径用冒号拼入命令名。\n\n去重规则：以规范化命令名为键（相对路径去掉 .md、分隔符替换为冒号、转为小写），首次出现者胜出——用户覆盖工作区、.zcode 覆盖 .agents、本地文件覆盖插件，重复项被忽略。另有仅作用于交互界面的过滤：命令名与内置斜杠命令（或 compress）相同的命令会从实时 / 菜单中过滤掉，但磁盘上仍然存在。\n\n命令 .md 格式：命令名来自文件名，须匹配 ^[a-z0-9][a-z0-9_:-]{0,63}$（小写字母或数字开头，不含空格、点或开头的 -/，最长 64 字符），违规即被丢弃。frontmatter 使用扁平解析器（缩进行被忽略），识别 description、argument-hint、allowed-tools、model、skills、disable-noninteractive（均为连字符形式）；未知键被忽略但命令仍加载。description 或非空正文至少需有其一，否则命令被丢弃；缺 description 时取正文第一条非空行。参数替换：$ARGUMENTS 为完整参数字符串，$1/$2 为位置参数（越界为空）；若提供了参数但正文无占位符，参数会以“User arguments:”标题追加。skills 会自动挂载，内联动态 shell（!cmd 或围栏 ! 块）会被拒绝。\n\n检查方式：客户端中输入 / 打开 Commands 组，可按关键词搜索，每条显示名称与描述；作为智能体则按发现顺序读取各位置的 .md 文件，由路径推导命令名（子目录变为冒号），同名命令以发现顺序最前者为准。\n\n常见问题（症状→原因→修复）：命令缺失因目录错误（如单数 .zcode/command/ 或位于仓库根之上），需移到 ~/.zcode/commands/ 或 <repo>/.zcode/commands/；缺失因文件名不合法（大写、空格、点、开头 -/、超 64 字符），需改为合法小写名并用子目录而非点做命名空间；被更高优先级同名副本覆盖时，需在发现顺序中找到并重命名或删除该副本（本地文件总是胜过插件）；frontmatter 解析错误导致键静默丢失，因扁平解析器只读单行顶层键，需把每个值写在一行、列表内联（如 allowed-tools: Read, Bash）；description 与正文皆空导致命令被丢弃，需补 description: 或至少一行非空正文；键名拼写错误（如 allowed_tools）导致 model/skills/allowed-tools 无效，需使用连字符键；$ARGUMENTS/$1 不替换，原因可能是无占位符（参数按设计追加）、$1 越界或 ${ARGUMENTS} 形式不被识别，需改用精确的 $ARGUMENTS/$1；动态 shell 被拒绝，需移除 !... 或 ! 围栏块，改用静态文本或 $ARGUMENTS；插件命令缺失，需在设置→插件管理中启用插件，并确认无本地同名文件遮蔽；配置禁用（按命令文件绝对路径而非命令名）使有效命令静默消失，需将该路径 enable 设为 true 或删除该配置；/ 与 : 混淆（/review/code 报未找到），实际名称为 review:code；保留名冲突（仅交互界面）使命令在实时 / 菜单中无法触发，需改为非保留名。\n\n本地化排查流程（按序）：1）是否在 / 菜单中？打开 Commands 组，不在则进入第 2 步；存在但运行内容不对则进入第 4 步（重复项）。2）确认文件及其根目录，确保 .md 直接位于当前工作目录可扫描的 commands 根下，且文件名合法。3）检查 frontmatter，键缺失或乱码指向扁平解析规则或空命令，键无效多为拼写错误。4）解决重复：同名以发现顺序最前者胜出，找到并重命名或删除不需要的副本。5）检查正文：确认参数占位符，且无被拒绝的动态 shell。6）仍无明显原因？检查配置禁用（按绝对文件路径）、插件是否禁用、保留名过滤。