11. 诊断

诊断与检查

屏幕看起来不对、复制没落盘，或项目没读到规则文件时，从这里开始。**Doctor** 检查当前终端。**Inspect** 列出 Matcha CLI 为当前目录发现的配置。

两条命令，两件工作

你想做的	运行
终端、颜色、剪贴板、键盘、多路复用器	`/doctor` 或 `matcha doctor`
规则、skills、MCP、插件、配置层	`matcha inspect`

Matcha CLI 已经打开时用 /doctor。TUI 起不来时，在 shell 里用 matcha doctor。matcha inspect 是一次性 CLI 报告，不会打开 TUI。

Doctor：检查当前会话

在 TUI 里：

/doctor

别名：/terminal-setup、/terminal-check、/terminal-info。

在 shell 里（不打开 TUI）：

matcha doctor
matcha doctor --json

--json 是同一份报告的机器可读形式。管道输出仍会报告与交互运行相同的颜色能力。

报告可以列出问题或建议，同时仍然成功退出。零问题并不表示每个可选功能都可用；只表示 Doctor 没有把它归类为损坏的项。

报告里有什么

给人看的报告以 **Matcha CLI Doctor** 开头，并分组列出事实：

**Environment** — 检测到的终端、多路复用器（tmux / Zellij / Byobu）、SSH、颜色深度、可用主题、键盘 / 换行行为、配置 schema、家目录迁移状态。
**Clipboard** — 系统原生剪贴板、tmux paste buffer、OSC 52、SSH wrap。
**Voice** — 本构建包含音频采集时，Doctor 会用的输入设备。探测不会开始录音。
**Findings** — ! 问题和 i 建议，每条都有稳定 id，例如 terminal.tmux-truecolor。
**Runtime leftovers** — 残留的 ~/.grok socket、锁或崩溃目录，只识别。Doctor 不会删除它们。

独立运行的 matcha doctor 看不到现场 TUI 事实（通知焦点、sandbox 配置冲突、全屏是否真的在生效）。报告这时会写 **Needs a running session**，并让你先启动 matcha 再跑 /doctor。

套用自动修复

某条发现有自动配置时，Doctor 会打印一条命令。列出这里能套用的修复：

/doctor fix

matcha doctor fix

一次只套用 **一项** 具名修复。短名或完整 id 都可以：

/doctor fix tmux-clipboard
/doctor fix terminal.tmux-truecolor

matcha doctor fix dcs-passthrough --yes
matcha doctor fix ssh-wrap

五项自动修复：

短名	写入内容
`ssh-wrap`	一条 shell 别名，让 SSH / 容器会话走 `matcha wrap`
`tmux-clipboard`	`set -g set-clipboard on`
`dcs-passthrough`	`set -wg allow-passthrough on`
`tmux-extended-keys`	`set -g extended-keys on`
`tmux-truecolor`	`set -as terminal-features ",*:RGB"`

不加 --yes 时，CLI 会打印预览并询问 Apply this fix? [y/N]。非交互 stdin 需要 --yes。

tmux 修复只改托管 tmux 服务端的那台机器上的**持久**配置（普通 tmux：$HOME/.tmux.conf；Byobu-tmux：实际生效的 BYOBU_CONFIG_DIR）。Matcha CLI 会保留换行与权限，改已有文件时做备份，并拒绝冲突或含糊的赋值。它**不会**运行 tmux source-file，也不会改正在运行的服务端。

用套用后打印的那条命令重载，或先 detach 再 attach，然后重新跑 /doctor。在重载之前，现场发现继续出现是预期的。

Inspect：这个目录发现了什么

在你关心的项目目录里：

matcha inspect
matcha inspect --json

Inspect 不会拉起 MCP 或 LSP 服务。它显示的是 Matcha CLI **将会**为这个工作目录加载的内容。

给人看的报告包括：

**Environment** — 版本、当前目录、git 根、项目文件夹是否受信任。
**Project Instructions** — AGENTS.md、CLAUDE.md、.cursor/rules 及同类文件，带作用域和大致 token 数。
**Permissions** — 已加载和已跳过的规则；策略强制的设置，不含密钥。
**Skills, agents, plugins, MCP, LSP, hooks** — 每条都标来源（project / user / plugin / builtin / config）。这些是报告上的标签。
**Config Sources** — 用户 ~/.matcha/config.toml、项目文件和其他层。某层可能标成 (empty) 或 (parse error)。
**Config Warnings** 与 **MCP Config Problems** — 无效字段或被跳过的 [mcp_servers.*] 条目，好让文件其余部分仍能加载。
**Harness Compatibility** — [compat.claude] / [compat.cursor] 单元格（on / OFF，以及来自配置还是默认值）。

当 **Project trusted** 为 no 时，仓库本地的 hooks、插件和 MCP/LSP 行会被同样门控，和现场会话一致。

--json 是机器可读形式，包含打码后的配置导出（configExport.redactedToml）。需要比较各层、又不想复制密钥时用它。

在 ~/.matcha/config.toml 里切换兼容来源，例如 [compat.cursor] rules = false，再跑一次 matcha inspect。被关掉的条目显示 [disabled]。

这两条命令不是什么

Doctor 和 inspect 只留在这台机器上。它们不会上传 traces、发送反馈，也不会检查产品更新。看起来像诊断的名字在这里不是恢复流程——读报错，修好点名的文件或终端设置，再跑同一条命令。