00. 怎么读这份文档

现场目录与书面教程

Matcha CLI 带三层帮助。它们不是彼此的副本。不一致时，以正在运行的二进制里的现场菜单为准。

应用内列表才是现场目录：你加入 skill 或插件时它会变长，当前屏幕模式无法运行的命令会被藏起。书面页 — 包括这些 — 可能落后于构建。把它们当成走完一件事的稳定路径，而不是第二份参数清单。

这几层

层怎么打开作用
现场斜杠菜单在提示符里输入 /Matcha CLI 此刻会执行的命令
命令面板Ctrl+P、?（焦点在回滚区）或 /help同样的命令，外加快捷键和 skills，可搜索
书面操作指南/docs，或 ~/.matcha/docs/user-guide/ 下的文件参数、别名、边界情况
第一小时浮层/tutorial（/tour、/onboarding）九页短文；仅全屏

/help 不是帮助文档。它打开的是和 Ctrl+P 同一个命令面板。精简模式没有常驻快捷键页脚，所以对外说明的入口是 /help。

打开现场斜杠菜单

  1. 把焦点放到提示符（如果焦点在回滚区，按 Tab）。
  2. 输入 /。
  3. 继续输入以模糊过滤。每一行显示名称、简短说明、参数提示，以及来源标记（built-in、skill · local、插件名……）。
  4. Tab 或 Enter 接受高亮的命令。

命令来自三处，出现在同一份菜单里：

  • 分页器内置 — 屏幕与会话操作（/theme、/docs、/minimal……）
  • 会话内置 — 助手后端操作（/compact、/model……）
  • Skills — 任何已启用、且 SKILL.md 里写了 user-invocable: true 的 skill

某个 skill 可能复用内置名称，例如 login。内置命令继续占用 /login；该 skill 仍可通过 /plugin-name:login 使用（两个 skill 冲突时则是 /local:login / /user:login）。菜单会给两者都打标记，让冲突可见。无前缀名称永远归内置命令。

插件和项目 skills 可以加入书面页没有列出的条目。这是预期行为。如果 / 里看得到，且 CLI 没有把该命令失败关闭，它就是真的。

菜单还会按渲染模式过滤。仅全屏的名称在精简模式里会消失（见全屏与精简）。

打开命令面板

Ctrl+P

或在回滚区有焦点时按 ?，或输入：

/help

输入以过滤，然后按 Enter。面板列出当前绑定的键盘快捷键、斜杠命令和可用 skills。适合你记得要做什么、却想不起按哪个键的时候。

Ctrl+P 和 / 相关，但不是同一个东西：/ 是给命令用的输入框菜单；面板是可搜索的动作浏览器。

打开书面操作指南：`/docs`

别名：/howto、/guides。

/docs
/docs how-to
/docs Getting Started
  • 单独的 /docs 或 /docs how-to 打开 How-to Guides 选择器。
  • /docs <title> 按不区分大小写的标题打开一篇指南。标题必须匹配应用内名称，而不是文件名。

已注册给 /docs 的标题（请按原样输入）：

  • Getting Started
  • Authentication
  • Keyboard Shortcuts
  • Slash Commands
  • Configuration
  • Theming and Appearance
  • MCP Servers
  • Skills
  • Plugins
  • Hooks
  • Custom Models
  • Project Rules (AGENTS.md)
  • Memory
  • Headless Mode and Scripting
  • Agent Mode and IDE Integration
  • Subagents and Personas
  • Session Management
  • Sandbox Mode
  • Plan Mode
  • Background Tasks and Monitoring
  • Terminal Support and Troubleshooting
  • Permissions and Safety
  • Agent Dashboard
  • Monitoring Usage
  • Hooks & Plugins Guide
  • Creating Custom Hooks

启动时，Matcha CLI 会把 user-guide 的 markdown 复制到 ~/.matcha/docs/user-guide/。你可以在编辑器里读这些文件。它们和 /docs 显示的是同一批页面。

打开第一小时浮层：`/tutorial`

/tutorial

别名：/tour、/onboarding。仅全屏（包括 --no-alt-screen）。在精简模式里，Matcha CLI 会让你先 /fullscreen。

不会自动弹出。浮层是一份第一小时主题短列表（第一次提示、@ 附件、导航、斜杠命令、worktrees、计划模式、自定义、从其他工具迁来）。每页大约读 30 秒；→ 进入下一主题。

第一天用 /tutorial。需要完整步骤时（会话、MCP……）用书面操作指南。需要某个参数或别名时用 /docs。

书面页不对的时候

教程可能落后于二进制，skill 可能新增命令，某个界面也可能失败即关闭（/marketplace、/feedback、/docs web、matcha update）。这时：

  1. 「这里有没有这条命令？」以 / 和 Ctrl+P 为准。
  2. 输入了门控或已禁用的名称，以拒绝文案为准。
  3. 把书面页当成走完一件事的路径，而不是第二份参数清单。

试一试

  1. matcha → / → 输入 doc → 打开 /docs。
  2. /docs Slash Commands，浏览模式门控那一节。
  3. Ctrl+P（或 /help）→ 输入 tutorial → 若在全屏则运行它。
  4. 如果之后安装了 user-invocable 的 skill，确认它会出现在 / 里，即使没有任何书面文章点过它的名。