01. 安装、凭证与第一次跑通

查看已发现的配置

Matcha CLI 不从官方云同步配置。助手会用的,是当前工作目录下这次进程在磁盘上发现的内容:项目说明、权限、钩子、技能、助手、插件、MCP 服务器、LSP 配置,以及 config.toml 各层。

matcha inspect 是对该发现的一次性报告。它不启动 TUI,也不拉取托管或团队配置。matcha setup 不可用。

发现会走过什么

发现会走过当前目录(以及 git 根,若有),加上用户级 ~/.matcha,默认还会走过其他工具的兼容树:

种类常见来源报告里的来源标签
规则 / 说明AGENTS.mdCLAUDE.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: yesno

已禁用或厂商关闭的条目标 [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] 矩阵:每个表面为 onOFF,并标出生效来源(defaultconfigenv,或 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 = false
matcha inspect

你应在 cursor 下看到 rules OFF (config),Cursor 规则文件标 [disabled](或从生效说明集中省略)。把该单元设回 true(或删掉它)即可恢复默认。

inspect 不是什么

命令作用
matcha inspect针对此目录的发现报告
matcha doctor终端 / 剪贴板 / 颜色 / 输入支持(见诊断)
matcha setup不可用。不要把它当同步步骤来跑。没有托管配置服务

inspect 只展示会被发现的内容;它不写入配置。