命令帮助系统

版本一升级，记忆就过期

上周还能用的子命令，同事这周提了一个你没听过的名字；升级提示一闪而过，帮助里多了几行。靠背命令来用工具，维护成本只会越来越高。

更稳的做法是记住「去哪里查」，而不是记住「答案是什么」。下面按问题类型把入口排一遍，都是打开终端就能用的。

按问题挑入口

你想知道	该敲什么	会看到
有哪些子命令和顶层标志	claude --help	一份总览
某个子命令怎么用	claude <子命令> --help	参数说明与示例
会话里能输入哪些斜杠命令	/help	按用途分组的列表
某个斜杠命令大致做什么	/help 列表里的说明	一句话描述
不想敲完整名字	Tab 键	命令或文件路径候选

帮助文本会随版本变化，看到的内容和示例不必和本文逐字一致，以你机器上的输出为准。

一次从粗到细的查找

先确认有没有这个能力：

claude --help | grep -A 2 "output-format"

输出太长时，接一个 less 分页，或者用 grep 直接过滤关键字。总览页适合先扫一遍子命令名，确认这一版多了什么、少了什么，再决定往哪一层钻。

找到子命令后，再往下钻一层：

claude mcp --help
claude mcp add --help

第二层的输出里，Examples 那段最值钱。它给的是能直接运行的骨架，把服务器名、传输方式、环境变量换成自己的即可。多数人卡住不是不懂参数含义，而是不知道几个参数该怎么排在一起，示例正好补这块。

版本差异要自己验：旧教程常写 claude help mcp，但在当前 2.1.x 里没有 help 这个子命令，敲下去会把 mcp 当成一段提示词去启动会话。判断方法很直接——claude --help 的 Commands: 列表里没有的名字，就不要按子命令用；子命令的参数一律用 claude <子命令> --help 查。

进了会话之后，路径换成斜杠命令：敲 /help 看按用途分组的清单。自定义命令也会混在这个列表里，做法在后面单独说。

清单通常按对话管理、配置、信息查询、项目操作几组排列，扫一遍就能判断有没有你要的能力。找到目标后别只看一行简介，具体参数回到官方文档；有些教程写 /help 命令名 可以展开单条命令，当前版本是否支持，以你输入后实际显示的为准。想看这一版改了什么，用 /release-notes；要对比更早的版本，去项目的发布页。

补全与拼写提示

会话里的补全最可靠，也不依赖额外配置：

• 在输入框敲一个 /，按 Tab 列出全部斜杠命令；
• 继续输入一两个字母，候选范围会缩小；
• 输入含 / 的路径片段，会出现文件和目录候选，Windows 上同样用正斜杠。

终端层面的标志补全则取决于你的 shell 配置，不能假定一定有。旧教程里那套 claude completion bash 的装法，在当前版本没有对应的子命令，照抄只会得到一段报错或启动输出，别在它上面浪费时间。不想敲全名时，先敲一两个字符，用 claude --help 配合 grep 找准确写法，比猜更快。

名字打错时，CLI 通常会给出最接近的建议：

error: unknown option '--modle'
(Did you mean --model?)

子命令也一样，例如把 update 打成 udpate，它会提示最接近的命令并退出。看到提示就直接照它改，不要回头翻文档。

如果 Tab 完全没反应，先确认光标在输入框里、且当前输入以 / 开头；在普通文本中间按 Tab，通常只是补全文件路径，不会列出命令。

自定义命令也会进帮助清单

常用的操作可以自己做成斜杠命令，做完之后 /help 清单里就能看到。在项目的 .claude/commands/ 目录新建一个 Markdown 文件，文件名就是命令名，例如 deploy.md 对应 /deploy；放在 ~/.claude/commands/ 则对所有项目生效。子目录会形成命名空间：.claude/commands/db/migrate.md 对应 /db:migrate。新版也支持把同样内容放进 .claude/skills/<名字>/SKILL.md，两种写法创建的是同一个命令。

正文里可以用 $ARGUMENTS 接收全部参数，也可以用 $0、$1 按位置取——注意它是从 0 开始数的，$0 才是第一个参数。文件开头可选的 frontmatter 写三件事就够：description 一句话说明用途（在命令列表里会带出来）、argument-hint 提示参数格式、allowed-tools 限定它能用哪些工具。

写完在输入框敲 / 看它是否出现在候选里；没有出现，先检查文件名有没有空格或特殊字符，再重启会话试一次。命令改名后旧名字立即失效，团队里要同步通知。

查不到时的三种情况

现象：总览输出一屏放不下。 接 less 翻页，或者用 grep 过滤关键字，例如 claude --help | grep -A 1 "model"。先过滤再通读，比从头翻快。

现象：本地帮助里没有同事提到的那个标志。 多半是你的版本旧了。先用 claude update 升级，再查一次；升级后仍然没有，才需要去官方文档确认它是不是还没发布。

现象：本地帮助和网页文档对不上。 本地帮助跟你安装的版本绑定，网页跟最新版走。判断「这台机器上能不能用」以本机输出为准，判断「推荐怎么用」以官网为准。读报错信息的一般方法可以看读懂报错信息：先看它给的下一步提示，再决定查帮助还是改命令。

本地帮助覆盖不到的地方

命令行帮助只讲「怎么敲」，不讲「为什么」。下面这些内容要转向官方文档：

• hook 支持哪些事件、每种事件的输入结构；
• 配置文件的完整字段与含义；
• MCP 的协议细节与接入方式；
• 每个版本改了什么。

还有一个省事的办法：直接问它自己。新开一个会话，把「去官方文档查某个配置怎么写」当成任务交给它，让它读完再给你结论。答案未必一次就对，但通常比在多个页面之间来回跳要快。

收束

帮助系统的用途不是让你背下所有命令，而是需要时能在几十秒内找到。想回顾命令是怎么跑起来的，可以看命令执行流程。下一节处理另一个现实问题：版本一直在变，怎么升级、怎么回退、怎么在流水线里钉住——命令版本管理。