ZCF：把七种 AI 编程工具装进同一份配置里

想象这样一个场景：你同时在用 Claude Code 和 Codex，团队里还有人在用 Gemini CLI 和 OpenCode。每换一个工具，就要重新配一遍 API Key、MCP 服务、Skills 和自定义指令——四个工具，四份 JSON，改到第三个的时候你已经开始怀疑人生。

ZCF（Zero-Config Code Flow）要解决的就是这件小事：只维护一份配置，剩下的交给它。

它到底做了什么

ZCF 不是网关，也不做代理——这点很关键。用完 ZCF 之后，Claude Code 依然直接连你的 Anthropic 账号，Codex 依然直接连 OpenAI。它只做一件事：安装你选择的工具，然后把配置写进每个工具自己的原生格式里。

具体来说，它会用工具自带的命令来写配置，而不是自己重新造轮子：

• claude mcp add-json 写 Claude Code 的 MCP 服务
• codex mcp add 写 Codex 的
• npx skills add 安装技能包

只有当某个设置确实没有对应命令可用时，它才直接去改文件——而且是按键改，保留你的注释、缩进和键顺序。

支持的工具目前有七个：Claude Code、Codex、Gemini CLI、OpenCode、Cursor CLI、Pi 和 DeepSeek Harness。

一份配置长什么样

配置文件默认放在 ~/.ufomiao/zcf/zcf.json，用 JSONC 格式写（支持注释）：

{
  "version": 1,
  "tools": ["claude-code", "codex"],
  "provider": {
    "name": "My relay",
    "apiKey": "***",
    "anthropic": { "baseUrl": "https://relay.example.com" },
    "openai": { "baseUrl": "https://relay.example.com/v1", "model": "gpt-5.5" }
  },
  "mcpServers": {
    "context7": { "type": "stdio", "command": "npx", "args": ["-y", "@upstash/context7-mcp"] }
  }
}

更省事的方式是 zcf init 一条命令搞定：选个供应商预设（--preset 302ai）、带上 API Key、勾选工具和工作流，--yes 直接落地。

界面：终端 TUI 与浏览器二选一

ZCF v5 提供两个配置界面，编辑的是同一个文件、同一套页面：

npx zcf          # 终端里的 Ink TUI
npx zcf ui       # 浏览器里的 Web UI

终端版用 Ink + React 实现，且是懒加载的——只有 zcf tui 会把 Ink 和 React 拉进进程，zcf --version 这种快路径完全不背这个包袱。Web 版是 React + Vite，打包进 CLI 的 dist/web，由 zcf ui 起一个只监听 127.0.0.1 的本地服务。

Web UI 的安全细节做得相当克制：只绑本机、拒绝其他 Host 头（防 DNS rebinding）、每次运行生成随机 token 放在 URL fragment 里，API 调用不带 token 一律拒绝；plan/apply 的输出推到浏览器时是掩码过的，密钥不会出现在屏幕上。

先看再改：plan / apply 两段式

这是 ZCF 最值得借鉴的设计。所有修改都先做"计划"：

npx zcf plan          # 显示将要执行的命令 + 每个文件的 diff
npx zcf apply -y     # 才真正执行

不带 --yes 的 apply 也只显示计划，不动任何文件。每一步要么跑一条命令，要么改某个文件的若干键；不同工具并行处理，同一工具的步骤按顺序执行。每个文件在第一次修改前会自动备份到 ~/.ufomiao/zcf/backups/<时间>/。

对 AI 编程工具这种"配置即代码"的东西来说，这个"可预览 + 可回滚 + 不打印密钥"的组合是刚需，而不是加分项。

技术实现：pnpm monorepo 四包结构

v5 是一次彻底重写（ADR 002），pnpm workspace 分四个包：

包	职责
@zcf/core	无头引擎：配置 schema、工具适配器、plan/diff/apply 流水线，不含任何终端或 UI 代码
zcf	CLI，用 tsdown 打包成零依赖包
@zcf/ui-kit	TUI 与 Web UI 共享的积木：draft 模型、页面/字段定义、useConfigEditor、ZcfService 接口
@zcf/web	React + Vite 的网页界面

核心里有七个工具适配器（adapters/ 下的 claude-code、codex、cursor、gemini-cli、opencode、pi、dsh），用 valibot 做 schema 校验，用 jsonc-parser、yaml、@decimalturn/toml-patch 处理各家不同格式的配置文件。

UI 层用的是"draft"模型：编辑的是内存里的纯数据，保存时逐键 diff 回写配置文件，只写你本次改过的键。这样你用编辑器改配置的同时，另一边浏览器标签页的改动也能活下来。

工程质量

测试用 Vitest，覆盖率阈值四项全卡在 80%（branches/functions/lines/statements），CI 里跑 oxlint + oxfmt + typecheck + vitest + build。仓库里有 100+ 个 .zcf/plan/history/ 计划文档，把每次重构的设计思路都留了档——这种"把 AI 协作过程也版本化"的做法本身就是个信号。

贡献者方面，GitHub API 的 contributors 列表给出 13 人（含匿名统计），主维护者是 UfoMiao。

局限与争议

几个必须说清楚的地方：

1. v5 尚未发布。npx zcf 装到的仍是 v3（最新 release 是 zcf@3.7.3，2026-08-31），仓库 main 分支是重写中的 v5 alpha。文档站目前介绍的还是 v3。想试用 v5 得从源码构建。
2. 强依赖 Node.js 22+，且在 Windows 上还额外需要 PowerShell 才能装官方安装器形式的工具。
3. 商业模式明显向 API 中转站倾斜。README 里挂满了 AICodeMirror、GLM、302.AI、PatewayAI、Crazyrouter、APIKEY.FUN、Sublyx 等中转服务赞助商，还带邀请码和折扣码。项目本身 MIT 开源、不收费，但你用 ZCF 时大概率会被引导到某个第三方中转站——这对企业合规是个需要留意的点。
4. 它管不了模型行为。ZCF 只解决"配置分发"，真正写代码的质量仍取决于你选的模型和 agent 框架。

写在最后

ZCF 的价值不在技术难度——它本质上是一个多目标配置管理工具 + 适配器集合，技术上没有革命性。但它精准命中了一个真实痛点：当 AI 编程工具从一两个膨胀到四五个，"配置分发"本身就成了独立的工程问题。

从一个更大的视角看，BMAD-METHOD、Claude Code Router、CCometixLine 这些项目都被它列进了鸣谢名单——它自己就是"AI 编程工具碎片化"这条趋势的一个缩影。谁能成为这条链上的"配置中枢"，谁就能吃到工具数量增长的红利。