01. 安装、凭证与第一次跑通
查看已发现的配置
Matcha CLI 不从官方云同步配置。助手会用的,是当前工作目录下这次进程在磁盘上发现的内容:项目说明、权限、钩子、技能、助手、插件、MCP 服务器、LSP 配置,以及 config.toml 各层。
matcha inspect 是对该发现的一次性报告。它不启动 TUI,也不拉取托管或团队配置。matcha setup 不可用。
发现会走过什么
发现会走过当前目录(以及 git 根,若有),加上用户级 ~/.matcha,默认还会走过其他工具的兼容树:
| 种类 | 常见来源 | 报告里的来源标签 |
|---|---|---|
| 规则 / 说明 | AGENTS.md、CLAUDE.md、.claude/rules/、.cursor/rules/ | [claude]、[cursor],或无(原生) |
| 技能 / 命令 | ~/.matcha/skills/、仓库技能、~/.claude/skills/、~/.cursor/skills/ | 同上 |
| MCP | ~/.matcha 配置、.mcp.json、~/.claude.json、.cursor/mcp.json | [claude]、[cursor] |
| 钩子 | .matcha / .claude/settings.json / Cursor 钩子 | 同上 |
每个 Claude / Cursor 单元默认开启。在 ~/.matcha/config.toml 里关掉某个单元:
[compat.cursor]
skills = true
rules = true
agents = true
mcps = true
hooks = true
sessions = true # staged; no scanner consumer yet
[compat.claude]
skills = true
rules = true
agents = true
mcps = true
hooks = true
sessions = true像 MATCHA_CURSOR_MCPS_ENABLED / MATCHA_CLAUDE_SKILLS_ENABLED 这样的环境变量会覆盖对应单元(false 关闭该扫描)。解析顺序是环境 > config.toml > 默认(开)。Codex sessions 已预留;Codex 的 skills / rules / agents / mcps / hooks 单元已保留但无效果。
inspect 也会报告目录信任。当前项目未受信任时,仓库本地的项目钩子、插件和 MCP/LSP 条目会像实时会话一样被挡在列表外。人读报告打印 Project trusted: yes 或 no。
已禁用或厂商关闭的条目标 [disabled]。未解析的兼容单元(少见;需要会话开始时的解析)在人读输出里显示 [compat unresolved],JSON 里是 compatibilityStatus: "unresolved"。技能名冲突形如 [collides with /login → /acme:login]。
在项目目录里运行 inspect
cd /path/to/your/project
matcha inspect人读输出是带分区的树(盒线 └)。典型报告包括:
Environment
└ Version: … [channel]
└ CWD: …
└ Git root: … # omitted if not a git workdir
└ Project trusted: yes
Project Instructions
└ <path> (project, ~N tokens) [cursor]
Permissions
└ Source: …
└ N loaded, 0 skipped
Login Policy
└ disable_api_key_auth: (unset)
└ force_login_team_uuid: …
└ api_key_auth_disabled: false
Skills
Agents
Plugins
Marketplaces
MCP Servers
LSP Servers
Hooks
Config Sources
Config schema
Harness Compatibility
└ cursor
└ skills on (default)
└ rules OFF (config)
└ claude
└ …报告里的 Harness Compatibility 是当前 [compat.cursor] / [compat.claude] / [compat.codex] 矩阵:每个表面为 on 或 OFF,并标出生效来源(default、config、env,或 config error; fail closed)。
MCP 列表为空时仍会打印该分区。当前帮助行仍写 see grok mcp add --help — 请用 matcha mcp add --help(同一条命令,产品名)。那条遗留字符串是已知不一致,不是第二套 CLI。
机器可读的 JSON
matcha inspect --json同一份报告的美化 JSON。给脚本用。若树里含你视为私有的路径名,不要提交该输出;报告包含绝对 cwd 和说明文件路径。配置导出里的密钥打码为 [redacted]。
关掉兼容扫描并再检查
例如:停止读取 Cursor 规则,然后确认该单元和说明列表。在 ~/.matcha/config.toml:
[compat.cursor]
rules = falsematcha inspect你应在 cursor 下看到 rules OFF (config),Cursor 规则文件标 [disabled](或从生效说明集中省略)。把该单元设回 true(或删掉它)即可恢复默认。
inspect 不是什么
| 命令 | 作用 |
|---|---|
matcha inspect | 针对此目录的发现报告 |
matcha doctor | 终端 / 剪贴板 / 颜色 / 输入支持(见诊断) |
matcha setup | 不可用。不要把它当同步步骤来跑。没有托管配置服务 |
inspect 只展示会被发现的内容;它不写入配置。