LLM编码平台配置工具

序曲

overture 是一个CLI实用程序，用于扫描您的计算机以查找支持MCP的LLM编码 并报告每个平台的MCP服务器配置的状态。 当前发布的命令包括：

• overture detect — 只读 已安装的MCP平台清单。
• overture config show — 只读；打印已解析的用户级别 overture.jsonc.
• overture scan — 只读构建已安装的MCP服务器矩阵 对冲突进行分类。
• overture bootstrap — 写 正典 overture.jsonc 上 无旗奔跑时的成功。使用 overture bootstrap --dry-run [--json] 用于非交互式预览。
• overture apply — 写 每个代理配置的规范MCP意图 （每封信前面都有一个相邻的 .bak.<ts> 备份）。使用 overture apply --dry-run [--json] 预览而不写作。
• overture restore-last — 写 （恢复）最近的应用程序运行 通过 mv-ing每一个 .bak.<ts> 通过逆方向返回目标 mv -v 应用日志通告的恢复路径。

overture detect, overture config show, overture scan，以及 --dry-run [--json] 变体 bootstrap 和 apply 从不写作或 修改任何文件。

overture 已发布到npm @jander99/overture.

# Run without installing (uses the latest published version):
npx @jander99/overture@latest --help

需要 Node.js>=24 （CLI的第一个发布版本针对的是 节点24 LTS基线；本地节点25也工作）。

状态：npm包形状已准备就绪。第一次发布是封闭的 在手动审批步骤之后；看见 docs/publishing.md 用于发布runbook。

它做什么

overture detect 扫描主机并报告哪些支持MCP的LLM平台 已安装。对于每个平台，它报告三个正交信号：

• installed --平台应用程序或CLI位于此计算机上。
• mcpConfigured --用户已填充平台的预期MCP 配置文件中的部分（JSON、JSONC和TOML支持的解析器 格式）。
• mcpSupport --平台是否具有已知的MCP客户端界面 (supported, unsupported，或 unknown).

overture config show 打印已解析的用户级别 overture.jsonc 配置 如果存在。

看 docs/coding-platform-mcp-configurations.md 用于驱动检测的每个平台目录。

这 detect 命令

overture detect 是一个 只读 库存：它从不写入、同步或 修改任何配置文件。

它扫描主机并报告安装了哪些支持MCP的LLM平台， 使用两种互补的策略：

• 二进制优先 （例如。 claude, opencode, copilot, codex)：the 当在上找到其规范CLI时，平台被报告为已安装 过程 PATHCLI从不生成子流程；可执行文件发现是 纯文件系统扫描，尊重POSIX可执行位，Windows PATHEXT，WSL可见 .exe 条目。
• 仅标记 （目前没有支持的代理使用此策略）。该平台 当已知的配置或扩展存储路径为 现在。

对于每个平台，报告包括三个正交信号：

• installed --此计算机上有平台app/CLI。
• mcpConfigured --用户已在中填充了预期的MCP部分 平台的配置文件（支持JSON、JSONC和TOML格式的解析器）。
• mcpSupport --平台是否具有已知的MCP客户端界面 (supported, unsupported，或 unknown).

附加表面积：

• 陈旧配置 通过以下方式报告 orphanedMcpLocations：MCP配置文件 适用于当前未安装的平台。仅配置陈旧 从不暗示安装。
• 不支持的工具 作为已安装的库存条目显示 mcpSupport: unsupported 和 mcpConfigured: false，所以你可以看到它们 而不会被误导，以为MCP同步会起作用。（没有支持的代理 目前属于这一类。)

用法

# Print installed platforms, configured/unsupported/orphaned sections
overture detect

# Machine-readable: full 4-platform inventory with all additive fields
overture detect --json

# Print the resolved user-level overture config (XDG-aware)
overture config show

# Print usage and exit 0

overture detect --help
overture --help
overture help

人类可读的输出有三个部分，仅在相关时显示： “检测到支持MCP的平台”，“安装了不支持MCP的工具” （库存）”和“孤立MCP配置（未安装平台）”。否 发出ANSI颜色；输出是适合管道的纯文本。

JSON输出是完整的清单：所有4个平台条目，包括 那些没有安装的，添加剂场平坦(detectionStrategy, mcpSupport, executableNames, matchedExecutables, mcpConfigured, matchedMcpLocations, orphanedMcpLocations, reasonCode).

detect 不会写入或修改它检查的任何文件，也不会在任何地方写入。

这 scan 命令

overture scan 是一个 只读 检查两者之间的关系 规范用户级别 overture.jsonc 配置和每个已安装代理的MCP 服务器配置。喜欢 detect，它从不写入、同步或修改任何 配置文件——它只报告它看到的内容。

该命令显示由 @overture/scan-matrix 包：四个代理注册表（claude代码、opencode、github copilot-cli、， openai codex）以规范顺序运行，读取每个代理的MCP配置 并归一化为规范服务器条目，得到的矩阵为 分为可选择的冲突和艰难的拒绝。未来的引导者或 apply命令将消耗此矩阵；今天，这是第一次实施 视觉的阅读行为。

用法

# Print a human-readable summary (default summary shape)
overture scan

# Machine-readable: full scan matrix + conflict classification as JSON
overture scan --json

# Print usage and exit 0
overture scan --help

默认摘要形状

无标志路径发出C2详细报告：一个纯文本、分段视图 扫描矩阵发现了什么。它保持相同的只读行为，但 在五行摘要中，它呈现了七个标题及其匹配的表格，或者 笔记：

• Agents
• Aligned servers
• Missing from agents
• Agent-only servers
• Pickable conflicts
• Hard refuses
• Parse errors

示例形状：

Agents
...
Aligned servers
...
Missing from agents
...
Agent-only servers
...
Pickable conflicts
...
Hard refuses
...
Parse errors
...

当 N === 0 附加了一个附加的安装建议块，其名称为 四个受支持的CLI和主机操作系统的序曲都在上面运行。摘要行 成为 Scan completed with blocking issues. 当退出代码为 1 JSON指针行总是最后发出，因此终端用户总是知道在哪里 接下来。不发出ANSI颜色；输出是适合的纯文本 管道。

JSON输出形状

overture scan --json 精确地发出两个顶级密钥（无版本信封， 不 generatedAt，没有 duration):

{
  "matrix": {
    "canonicalState": "absent",
    "canonicalProfileName": null,
    "canonicalIntent": {},
    "agents": [
      /* AgentSnapshot[] */
    ],
    "rows": [
      /* ServerStatusRow[] */
    ]
  },
  "conflicts": {
    "pickable": [
      /* PickableConflict[] */
    ],
    "hardRefuses": [
      /* HardRefuseConflict[] */
    ]
  }
}

• matrix.canonicalState 是其中之一 absent （未写入配置）， ready （配置+配置文件已解析），或 invalid-profile （配置 存在但缺少默认配置文件）。
• matrix.canonicalIntent 是 {} 当用户没有编写规范时 配置；前规范用户仍然可以获得有意义的库存扫描。
• matrix.agents 不管怎样，四个代理注册表是否按规范顺序排列 安装了多少。
• matrix.rows 是每台服务器的状态分类(aligned, missing-from-agent, extra-in-agent, different-settings, shape-conflict, parse-error, unsupported-agent, not-installed).
• conflicts.pickable 仅在规范意图缺失时填充： 每个服务器名称组有一个条目，至少有两个不相等的规范化条目 候选人。
• conflicts.hardRefuses 涵盖解析错误、形状冲突、规范 设置漂移，同名组跨越两者 stdio 和 remote 运输。

退出代码

scan 不会写入或修改它检查的任何文件，也不会在任何地方写入。

这 bootstrap 命令

overture bootstrap 是一个 一次性设置 命令：它生成 规范用户级别 overture.jsonc 从代理的当前MCP配置 服务器清点并在成功时将其写入解析的XDG路径。

D1是 规划器 引导阶段。D2是 互动冲突 提示 阶段：它引导用户逐一解决可选择的冲突 并应用所选候选人或 skip 在记忆中。D3添加 写 阶段：当无标志交互式运行完成时，没有任何困难 拒绝/阻止剩余，它写道规范 overture.jsonc.

用法

# D3 one-time setup: walks pickable conflicts one at a time, then writes the
# canonical `overture.jsonc` to the resolved XDG path on success. Prints
# `Wrote config: <absolute path>` on stdout. Does NOT modify any agent config.
overture bootstrap

# Non-interactive human-readable preview of the proposed canonical config.
# Does NOT write any file.
overture bootstrap --dry-run

# Machine-readable: full proposal + conflicts + blockers. Does NOT write.
overture bootstrap --dry-run --json

# Print usage and exit 0
overture bootstrap --help

无旗 overture bootstrap 是D3一次性设置。它引导用户 通过一次一个可选择的冲突，应用所选的候选人或 skip《成功论》 overture.jsonc 到 已解析XDG路径，打印 Wrote config: <absolute path> 在stdout上。使用 overture bootstrap --dry-run 对于非交互式预览 写入任何文件。无旗路径出口 2 当stdin不是TTY时（提示： Run overture bootstrap --dry-run for a non-interactive preview.).

默认摘要形状

不---json 路径发出纯文本、分段预览。无旗 交互式run编写规范 overture.jsonc 并打印 Wrote config: <absolute path> 在stdout上；这 --dry-run 路径发出 仅预览，不写入任何文件。

• Bootstrap proposal (dry-run) （标题）-- --dry-run 仅
• Bootstrap proposal （标题）--无旗互动运行
• Config path: --已解决的XDG overture.jsonc 路径
• Proposal status: — ready 或 blocked
• Target agents: --逗号分隔的代理ID
• Adopted servers: --计数+每个采用的服务器一个缩进子弹
• Pickable conflicts: --每个可拾取冲突的计数+子弹数
• Hard refuses: --计数+每个硬垃圾的子弹数
• Blockers: --计数+每个阻断器的子弹数（例如。 no-readable-agents)
• 页脚（无旗，成功）： Wrote config: <absolute path>
• 页脚(--dry-run): No files were written. 和 Run "overture bootstrap --dry-run --json" for machine-readable details.

不发出ANSI颜色；输出是适合管道的纯文本。 服务器详细信息（env、headers、args）永远不会呈现；仅编辑 指纹。

JSON输出形状

overture bootstrap --dry-run --json 精确地发出三个顶级密钥：

{
  "proposal": {
    "status": "ready | blocked",
    "configPath": "/absolute/path/to/overture.jsonc",
    "config": { "version": 1, "settings": {}, "profiles": {} },
    "adoptedServers": [
      {
        "name": "filesystem",
        "source": "single-agent | all-agents-equal",
        "agentIds": ["claude-code"]
      }
    ],
    "targetAgents": ["claude-code"]
  },
  "conflicts": {
    "pickable": [],
    "hardRefuses": []
  },
  "blockers": []
}

退出代码

bootstrap --dry-run 不会写入或修改任何文件 检查时，它不会在任何地方写字。D3将规范配置写入 成功。 应用+恢复上次发货时的状态——见下文。

这 apply 命令

overture apply 读取规范用户级别 overture.jsonc 并写道 解析的MCP服务器设置为每个目标代理的MCP配置文件。它是 逆 bootstrap: bootstrap 从 代理人， apply 将规范意图传播回代理。

用法

# Preview every planned per-agent change without writing any file.
overture apply --dry-run

# Machine-readable preview. Same shape as the human report — never the
# real-write shape (see F2 gate F2-4).
overture apply --dry-run --json

# Real write. For every target whose writer plans an update, the
# orchestrator snapshots the existing file to <target>.bak.<YYYYMMDD-HHmmssSSS>
# (with a -<randomHex(4)> collision suffix, 3 retries) and only then
# performs the real write. Refusal statuses skip both the backup step
# and the real write.
overture apply

# Skip the backup step: set `settings.backupBeforeWrite: false` in the
# canonical config. The CLI honors the setting (default `true`) — there
# is no `--no-backup` flag. Pass 2 still runs; only the snapshot step is
# omitted. Refusal statuses are unaffected.
# (in overture.jsonc)
# { "settings": { "backupBeforeWrite": false }, ... }

# Print usage and exit 0
overture apply --help

编排器加载规范 overture.jsonc，选择活动 个人资料by settings.defaultProfile （默认值 'default')，过滤器 服务器反对 profile.sync.disabledServers，然后迭代 profile.sync.targets 整齐。对于每个目标，它都会运行两次写入： 通行证1(dryRun: true)发现目标路径和变更决策；如果 Pass 1计划更新 backupBeforeWrite 是 true，编排者 通过以下方式快照每个目标 fs.copyFile；通过2(dryRun: false)执行 真正的写作。F3设置漂移拒绝备份前短路 通过2。

模拟JSON信封

overture apply --dry-run --json 精确地发出四个顶级密钥：

{
  "profile": "default",
  "configPath": "/absolute/path/to/overture.jsonc",
  "disabledServers": [],
  "results": [
    {
      "agentId": "opencode",
      "displayName": "OpenCode",
      "status": "would-update",
      "result": {
        "targetPaths": [{ "base": "/abs/path", "path": "/abs/path" }],
        "resolvedPath": "/abs/path",
        "changed": true,
        "bytesChanged": 123,
        "serversWritten": ["filesystem"]
      }
    }
  ]
}

看 ApplyDryRunResult / ApplyDryRunAgentResult 在 apps/cli/src/apply-command.ts 对于完整的模式。F1计划锁定了 包络形状和F2门F2-4保持不变 --json 保留给 仅限干跑道。

退出代码

apply --dry-run [--json] 不会写入或修改任何文件 检查时，它不会在任何地方写字。真正的写入路径是成对的 与 overture restore-last --见下文——这是反向恢复 路径。

这 restore-last 命令

overture restore-last 与 apply：它恢复每个目标 将最近运行的应用程序归档 mv-邻近 .bak.<ts> 备份到目标上。这是一个便利之上 mv -v 应用日志通告的恢复片段--复制片段 退出日志并运行 overture restore-last 生产同样的产品 -v 同一行 mv 调用。

用法

# Dry-run: print the restore plan without moving any file.
overture restore-last --dry-run

# Real restore: require `--yes` to skip the interactive confirm prompt
# (or run interactively on a TTY).
overture restore-last --yes

# Force a restore even when the current target bytes do not match the
# G1-recorded pre-write sha256 (user has edited the target since apply).
overture restore-last --yes --force

# Restore a specific apply run by id instead of the last.json pointer.
overture restore-last --run-id 20260704-120304123-abcdef12 --yes

# Print usage and exit 0
overture restore-last --help

restore-last 读取 <stateDir>/apply/last.json （G1指针文件） 解析运行id，然后加载 <runId>.json （G1状态记录-- 首选，携带 preWriteSha256)或 <runId>.log （G2人类 log——回退，通过 backup: / target: 标签线；不 sha256）。 stateDir 通过以下方式解决 defaultOverturePaths() — $XDG_STATE_HOME/overture 当设置时，否则 ~/.local/state/overture.

完整性检查

对于每一个 (backup, target) 配对编排器计算当前 目标的sha256，并将其与G1记录进行比较 preWriteSha256The 结果是四个结果之一 integrityStatus 值：

执行

restore-last 生成 child_process.spawn('mv', ['-v', backup, target]) 每双——从不 fs.rename --所以 -v 线路用户看到匹配项 mv -v 应用程序日志中的行逐字记录。配对按顺序执行；这 第一 mv exit≠0中止批处理，并呈现部分结果。 原子整体运行语义：要么每对恢复，要么没有恢复。

退出代码

restore-last 是反向恢复路径；磁盘恢复 在应用程序日志中发布的广告只是 mv -v 每双。备份持续存在 成功还原后--下一个 overture apply 会修剪它们 通过G1的锁步 pruneApplyArtifacts.

存储库布局

overture/
├── apps/
│   └── cli/              # The `@jander99/overture` CLI (entry point: src/main.ts)
├── packages/
│   ├── os/               # `@overture/os`: cross-platform OS detection
│   ├── agents/           # `@overture/agents`: per-agent MCP registry, parsers, writers
│   ├── config/           # `@overture/config`: user-level config loading and schema
│   └── scan-matrix/      # `@overture/scan-matrix`: pure scan matrix model + conflict classification
├── docs/
│   ├── coding-platform-mcp-configurations.md
│   ├── overture-config.md
│   ├── overture-vision.md
│   └── publishing.md
├── nx.json               # NX workspace configuration
└── package.json          # Yarn 4 workspaces root

工作空间是由NX 22编排的Yarn 4 monorepo。

构建和执行

CLI存在于 apps/cli。它是用 @nx/esbuild 执行人和 作为CommonJS Node捆绑包发布。

在dev中运行（一次）

yarn nx serve @jander99/overture

这将构建项目并通过Node运行输出。

仅构建

yarn nx build @jander99/overture
# Output: apps/cli/dist/main.js

测试

yarn nx test @jander99/overture

制造 overture 可运行为 npx @jander99/overture 本地

CLI公开了一个 bin 输入，以便您可以通过运行它 npx @jander99/overture （或 overture 之后 npm link)从任何地方 您的机器无需等待首次发布。工作流程为：

# 1. Build and create a global symlink
yarn nx run @jander99/overture:link

# 2. Run it
npx @jander99/overture
# or simply
overture

# 3. When you're done, remove the global symlink
yarn nx run @jander99/overture:unlink

这 link 脚本在 apps/cli/package.json 包含两个步骤：

{
  "scripts": {
    "link": "yarn nx build @jander99/overture --skip-nx-cache && npm link",
    "unlink": "npm unlink -g @jander99/overture"
  }
}

编辑后 apps/cli/src/main.ts，重建并重新链接：

yarn nx run @jander99/overture:link

构建配置说明

apps/cli/package.json 构建与 bundle: true 和 thirdParty: true 所以 esbuild内联网 jsonc-parser 放入捆包中。 smol-toml 装载时间为 运行时通过 createRequire 并被宣布为 dependency 所以 npm install 为npm消费者设置查找路径。shebang定义于 src/main.ts 由esbuild保存 bundle: true 选项。编译 dist/main.js 是什么 npm link （以及 npx)注册为 overture 命令。

需求

• Node.js>=24（CLI针对Node 24 LTS基线；匹配 @types/node 在CI脱离节点20之后）
• Yarn 4（此仓库通过以下方式使用Corepack .yarnrc.yml)
• POSIX shell npm link 工作流