企业官网建设流程全解析

上礼拜往本机加了一个新的 MCP server，又双叒叕走了一遍熟悉流程：先在 Claude Code 里翻配置，再去改 Codex 的 TOML，接着打开 Cursor 的 mcp.json，最后还得手动给我的自研 Agent（内部代号 Hermes Agent）备一份。说实话，MCP 这个协议已经帮我们把“工具怎么接入”这件事统一了，结果每个 Agent 的配置文件还是各写各的，技能文件更是散落得到处都是——同一套最佳实践，我在三个工具里维护了三份，还经常不同步。

折腾多了，我干脆搭了一套本机全局的配置同步方案：一套注册表、一个生成脚本、几个符号链接，Claude Code / Codex / Cursor / Hermes Agent 全部吃同一份 MCP 配置、同一份技能目录。新增 MCP 不用再逐个 Edit 配置文件，技能目录里丢一个新技能，所有工具立刻可用。这篇就把完整思路和可复现的做法写出来，给同样被多 Agent 配置折磨的人一个可以直接抄的作业。

1. 多 Agent 环境下的配置分裂，问题出在三层

1.1 MCP 统一了协议，却没有统一配置文件

MCP（Model Context Protocol）解决的是“Agent 如何调用外部工具”的标准化问题。以前每接一个工具，要给每个 Agent 写一套自定义对接代码，现在只需要给 MCP server 配好 command、args、环境变量，Agent 就能通过协议跟它通信。

但它只统一到“协议”这层，没统一到“配置”这层。每个 Agent 都有自己接受的配置格式和存放位置：Claude Code 认 JSON，Codex 认 TOML，Cursor 有自己的 mcp.json，我这边自研的 Hermes Agent 又是一个约定好的目录结构。同一个 MCP server，想在四个工具里都能用，就得把同样的信息分别写四遍。

1.2 我本机实际维护过的四套配置

先列一份真实的本机清单，大家可以对照一下自己是不是也处于这个状态：

这里有个很容易踩的细节：Claude Code 的“用户级 MCP 配置”其实藏在~/.claude.json这个文件里，而这个文件同时还存了会话历史、项目状态等一堆东西。最初我图省事直接整体写这个文件，结果把会话记录弄丢过一次。后来改成脚本只合并mcpServers字段，才算是稳了。

1.3 配置分裂的直接代价

四套配置带来的问题，不是简单的“多写几行”：

第一，时间成本。接一个新 MCP，光配置就要改四个文件，每个文件格式还不一样，复制粘贴也得小心翼翼避免把 TOML 内容贴进 JSON。

第二，出错概率。我试过一次把 Codex 的 TOML 数组语法写成了 JSON 的数组语法，启动直接报错，找原因找了十分钟。

第三，技能不同步。Claude 侧更新了某个技能文件，Cursor 那边还是旧版本，同一个操作在两个工具里表现不一致。这个问题最隐蔽，因为不报错，只是结果有细微差异。

所以“统一配置”不是锦上添花，而是多 Agent 重度使用场景下的刚需。

2. 统一配置的两块基石：用户级配置与符号链接

2.1 配置继承顺序是“本机全局”的合法依据

几乎所有 CLI 类的 Agent 都有类似的配置优先级：内置默认值 < 用户级配置 < 项目级配置。Claude Code 会先加载用户级设置，再在项目目录里找.claude/下的覆盖项；Codex 类似，用户配置在~/.codex/，项目配置在项目根；Cursor 的 MCP 配置也可以分项目级和全局级。

这个继承顺序就是整套方案的合法性基础：把个人常用的 MCP server 和技能放到“用户级”这一层，它们就在本机所有项目里全局生效，同时不污染任何一个项目的仓库。项目级配置依然保留，专门放团队协作需要的那些 server 和规则。两者隔离，互不干扰。

2.2 符号链接：让所有 Agent 读到同一份数据

做同步的方案无非三种：复制、硬链接、符号链接。复制是最差的选择，因为改源文件后每个副本都要重新手动同步，过不了多久就又分叉了。硬链接在同一文件系统内可以，但跨文件系统（比如 Windows 上 C 盘和 D 盘）会失效。

符号链接（symlink）是我的选择。它本质是一个“快捷方式”，多个路径指向同一个真实文件或目录，Agent 读 A 路径时拿到的就是源目录里的最新内容，不需要任何同步动作。我这边 macOS 上一条ln -s就搞定，Windows 上需要New-Item -ItemType SymbolicLink或mklink /D，前提是开启开发者模式或者以管理员身份执行。

用生活里的话说：以前我是把同一份文档复印四份分发给四个同事，现在我在四个同事的桌上放了一张写有同一个档案柜位置的便签。档案柜里的内容变了，四个同事看到的自然都是新的。

2.3 所谓“0 配置”，不是没有配置，而是配置只写一处

标题里写了“0 配置”，这个话容易引起误解。MCP server 的注册信息不可能凭空消失，你总得告诉系统“这里有个 server，它用什么命令启动”。真正的 0 配置是：Agent 侧不需要你再动任何手工配置文件。

我的做法是引入一个“统一注册表”文件，所有 MCP server、技能目录都登记在这一个文件里，然后用脚本根据注册表自动生成各个 Agent 需要的那四份配置。日常操作从“改四个文件”变成“改一个文件”，其余全部自动化。这就是 0 配置的真实含义：配置收敛到一处，剩下交给程序。

3. 落地实现：一套目录结构、一个注册表、一个生成器

3.1 目录设计：源文件、注册表、生成物分开放

先看我最终采用的目录结构：

~/.agent-sync/ ├── registry.json # 统一注册表，全方案的唯一人工维护入口 ├── skills/ # 所有技能的源文件，SKILL.md + 关联脚本 ├── generated/ # 生成器输出的各 Agent 配置（不手工编辑） ├── scripts/ │ └── generate.py # 注册表 -> 各工具配置的生成器 └── logs/ └── sync.log # 每次生成的变更日志

设计原则很简单：人工只碰registry.json和skills/，generated/完全是机器产物，改名字、改路径都无所谓，重新生成一遍即可。这套结构花了最多心思的不是“怎么写”，而是“怎么让边界清晰”。

3.2 统一注册表的字段设计

registry.json是我定义的唯一事实源，核心按 MCP server 和技能两大部分组织。一个经过实战打磨的例子长这样：

{ "mcpServers": [ { "name": "github", "description": "GitHub API tools for search and issues", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_TOKEN": { "fromEnv": "GITHUB_TOKEN" } } }, { "name": "filesystem", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Downloads", "~/Documents"] } ], "skills": { "sourceDir": "~/.agent-sync/skills", "targets": { "claude": "~/.claude/skills", "cursor": "~/.cursor/rules", "hermes": "~/.hermes/skills" } } }

几个字段的用意要说明一下：

env里我特意不写死密钥，而是用fromEnv引用当前 shell 的环境变量GITHUB_TOKEN。这样registry.json本身可以安全地纳入 Git 管理，不会把个人 token 泄露进仓库。生成器在出配置的时候再去解析当前环境变量，把解析后的值写入生成的配置文件里——如果环境变量不存在，生成器会明确报错提示，而不是生成一个启动即挂的配置。

skills.targets记录每个 Agent 的技能目录应该软链接到哪个位置。之所以在注册表里统一声明，而不是写死在脚本里，是因为这些路径在不同系统上差异很大（Windows 的用户目录路径、macOS 的~/Library/Application Support都有可能）。

3.3 生成器核心逻辑：别整体覆盖，只合并关键字段

生成器的核心逻辑不复杂，难在“合并”而不是“覆盖”。以 Claude Code 为例，我不能把整个~/.claude.json覆盖掉，那里面还有会话数据和项目状态。正确做法是用 Python 读现有文件，只更新mcpServers字段，其他全部保留。

#!/usr/bin/env python3 import json, os, shutil, subprocess from pathlib import Path HOME = Path.home() SYNC_ROOT = HOME / ".agent-sync" def load_registry(): with open(SYNC_ROOT / "registry.json") as f: return json.load(f) def resolve_env(env_spec): resolved = {} for key, value in (env_spec or {}).items(): if isinstance(value, dict) and "fromEnv" in value: src = os.environ.get(value["fromEnv"]) if not src: raise RuntimeError(f"Missing required env var: {value['fromEnv']}") resolved[key] = src else: resolved[key] = value return resolved def merge_claude_code(registry): claude_json = HOME / ".claude.json" data = {} if claude_json.exists(): data = json.loads(claude_json.read_text()) servers = {} for srv in registry["mcpServers"]: servers[srv["name"]] = { "command": srv["command"], "args": [expand_user(a) for a in srv.get("args", [])], "env": resolve_env(srv.get("env", {})) } data["mcpServers"] = servers # 只动这个 key claude_json.write_text(json.dumps(data, indent=2, ensure_ascii=False)) def merge_codex(registry): config_path = HOME / ".codex" / "config.toml" config_path.parent.mkdir(parents=True, exist_ok=True) lines = [] if config_path.exists(): lines = config_path.read_text().splitlines() # 简单处理：定位 [mcp_servers] 段并替换，实际项目里建议用 toml 解析库 for srv in registry["mcpServers"]: lines.append(f'\n[mcp_servers."{srv["name"]}"]') lines.append(f'command = "{srv["command"]}"') args_list = [expand_user(a) for a in srv.get("args", [])] lines.append(f'args = {format_toml_array(args_list)}') config_path.write_text("\n".join(lines) + "\n") if __name__ == "__main__": reg = load_registry() merge_claude_code(reg) merge_codex(reg) link_skills(reg["skills"])

这个脚本故意保持了“看得懂”的程度。真实工程里，Codex 的 TOML 合并建议直接用 Python 的toml库做结构化读写，而不是文本行操作——我这里用文本追加只是为了表达核心思路，大家自己落地时优先用成熟的解析库。

3.4 一次性部署命令序列

把整个方案从零搭起来，按下面的顺序操作：

# 1. 创建目录骨架 mkdir -p ~/.agent-sync/{skills,generated,scripts,logs} # 2. 写 registry.json（参照上文示例） # 3. 创建各 Agent 技能目录的初始软链接 # 先备份已有技能目录（如果有） [ -d ~/.claude/skills ] && mv ~/.claude/skills ~/.claude/skills.bak mkdir -p ~/.claude/skills ln -s ~/.agent-sync/skills ~/.claude/skills/agent-sync # 4. 运行生成器 python3 ~/.agent-sync/scripts/generate.py # 5. 重启对应 Agent 验证 claude

ln -s ~/.agent-sync/skills ~/.claude/skills/agent-sync这行值得解释一下：我没有把~/.claude/skills整个替换成软链（虽然技术上可行），而是建了一个子目录软链agent-sync。这样 Claude Code 自带的默认技能目录还在，不会因为我的操作而影响工具自身行为，同时我在~/.agent-sync/skills/里新增技能，Claude 侧立刻就能看到。

3.5 日常新增 MCP server 的操作节奏

搭完这套体系之后，我新增一个 MCP server 的流程变成了：

1. 在registry.json里追加一个 server 条目（一分钟）。
2. 运行python3 ~/.agent-sync/scripts/generate.py。
3. 重启对应的 Agent（或重载 MCP 配置）。

整个过程不需要再碰任何工具的原生配置文件。如果某个 Agent 报“找不到配置”，我第一反应是检查注册表里这个 server 的command和args是否写对了，而不是怀疑其他地方——排查范围一下子缩到一个小文件里，省了很多事。

4. 各 Agent 的配置差异与适配细节

4.1 Claude Code：合并mcpServers字段

Claude Code 的用户级配置分布在两个地方：MCP server 清单在~/.claude.json的mcpServers字段里，技能目录默认是~/.claude/skills/（部分版本也支持项目级.claude/skills/）。

处理时要特别小心~/.claude.json是会话和项目状态的大杂烩，生成器必须走“读整个文件 -> 只改mcpServers-> 写回整个文件”的路线。我最初版本就是漏了这一步，导致每次生成都覆盖掉会话记录，后来加了字段级合并才算稳。

技能目录用软链接方案，我实测对SKILL.md的识别没问题，工具会把软链目录当成普通技能目录扫描。

4.2 Codex：TOML 格式与 AGENTS.md 指令

Codex 的 MCP 配置在~/.codex/config.toml，格式是：

[mcp_servers.github] command = "npx" args = ["-y", "@modelcontextprotocol/server-github"]

生成器要把 JSON 结构转成这个 TOML 片段。注意 TOML 的数组语法是["a", "b"]，不是 JSON 那样带尾逗号，生成时别偷懒用简单字符串拼接，最好用toml库输出，避免转义问题。

Codex 里“技能”的表现形式不是独立的技能文件，而是AGENTS.md这种说明文档。所以我处理 Codex 的方式略有不同：把~/.agent-sync/skills/里适合 Codex 的知识性技能（比如编码规范、工具使用说明）合并生成一份~/.codex/AGENTS.md，而不是做目录软链。这里的取舍是：Claude 的技能强调“可调用的能力包”，Codex 的 AGENTS.md 更强调“上下文说明”，两者语义不完全对等。

4.3 Cursor：项目级 mcp.json 与用户级规则的方向

Cursor 的 MCP 配置默认在项目目录.cursor/mcp.json，这样做的后果是：你在 A 项目里配了一个 MCP，切到 B 项目就没了。要想全局生效，要么每次生成器往各个项目里同步，要么确认你的 Cursor 版本支持用户级 MCP 配置。

我的方案是：在部署时一次性往常用项目的.cursor/mcp.json写入生成结果，同时在registry.json里维护一份“需要同步的 Cursor 项目列表”，生成器每次把这些项目全部同步一遍。Cursor 的全局 Rules 则放在对应系统设置目录里，用法跟 Claude 类似，做一个子目录软链即可。

我这里要明确一个负责任的提醒：Cursor 各个版本的全局配置路径变化比较频繁，部署前建议先实测一次你那个版本的读取路径，再决定软链落到哪里。

4.4 Hermes Agent：自研 Agent 直接读注册表

自研 Agent 最大的好处是配置格式你自己定。Hermes Agent 我压根不做生成环节，直接在代码里让 MCP manager 读取~/.agent-sync/registry.json作为唯一来源。新增 server 只需写一次注册表，Hermes 下次启动自动发现。

其他自研 Agent 接入时也同理——配置文件格式既然是自定义的，直接消费 registry 就是最省事的方式。这也算是整套方案的“自举”：标准是统一的，越晚接入的工具反而越简单。

4.5 环境变量与路径的归一化处理

适配过程中最容易忽视的雷是路径问题。注册表里我写了"~/Downloads"这种带波浪号的路径，不同 Agent 解析这条路径的行为不一，有的能自动展开，有的原样传给子进程导致启动失败。所以生成器里必须有统一的expand_user步骤，把所有路径规范成绝对路径再生成。

同理，环境变量里的 token 如果是通过 shell 配置的，有的 Agent 启动时能继承，有的需要写到配置里。我在注册表里用fromEnv标记，生成时统一解析，规避了“同一个变量名，这个 Agent 认那个 Agent 不认”的混乱。

5. 技能文件的跨 Agent 同步

5.1 技能的常见载体：都是带 frontmatter 的 Markdown

先说一个观察：Claude Code 的 SKILL.md、Cursor 的 Rules（.mdc 文件）、很多开源 Agent 的技能包，本质都是“带 YAML frontmatter 的 Markdown”。frontmatter 里包含 name、description、globs 之类元信息，正文是给模型读的推理步骤或指令。

这个共性就是统一技能格式的基础。我把技能的源文件全部放在~/.agent-sync/skills/<技能名>/SKILL.md，每个技能一个目录，目录里可以带参考脚本或资源文件：

~/.agent-sync/skills/ ├── code-review/ │ ├── SKILL.md │ └── review-checklist.json ├── test-coverage/ │ ├── SKILL.md │ └── templates/ └── database-troubleshoot/ └── SKILL.md

5.2 源目录如何分发到各 Agent

分发方式取决于目标 Agent 的技能目录结构：

• Claude Code：软链~/.claude/skills/agent-sync指向源目录，它自动扫描子目录里的 SKILL.md。
• Hermes Agent：直接配置技能搜索路径包含~/.agent-sync/skills。
• Cursor：如果源技能带 frontmatter，可以做兼容规则文件软链；某些规则专用字段（比如 globs 的匹配语法）因工具而异，需要转换。
• Codex：不走目录软链，而是用生成器把技能描述片段汇总进AGENTS.md，让模型在上下文里感知。

这里必须讲一个实操教训：软链整个技能目录虽然省事，但有的工具（比如某些版本的自研 Agent）会在技能目录里写入索引缓存或者“最近使用”标记，这样会反过来污染源目录。稳妥的折中方案是：只让工具对源目录有读权限，或者接受源目录里出现缓存文件并在.gitignore里忽略它们。我在源目录外挂.gitignore就是为了挡住这些垃圾文件，否则 Git 仓库会越来越脏。

5.3 需要格式转换时，写一个小转换器

如果某个 Agent 对技能格式要求严格（比如 Cursor 的 Rules 必须带metadata.author之类的专用字段），直接软链同一个文件会识别失败。这时生成器里加一个转换函数：

def convert_skill_for_cursor(src_skill_md, out_mdc): data = parse_frontmatter(src_skill_md) # 读 SKILL.md 的 YAML metadata = { "name": data.get("name"), "description": data.get("description"), "globs": data.get("globs", "**/*"), } with open(out_mdc, "w") as f: f.write("---\n") f.write(yaml.dump(metadata)) f.write("---\n\n") f.write(read_body(src_skill_md))

转换器不复杂，但能解决真实障碍：我之前直接把 SKILL.md 复制成 .mdc，结果 Cursor 一直不识别，就是因为缺了新版要求的关键元数据字段。规则是：凡是跨工具同步的技能，先确认目标工具对 frontmatter 字段的最小要求，再决定是软链还是转换。

5.4 技能和 MCP 的联动校验

我踩过的一个坑是：技能文件里引用了某个 MCP 工具（比如让模型调用 GitHub 搜索接口），但这个 MCP server 从来没在注册表里登记过。结果模型在 Claude Code 里可以执行，在 Cursor 里直接找不到工具，报错信息还不明确。

后来我在生成器里加了一个“引用完整性检查”：扫描所有 SKILL.md 正文，提取形如mcp__<server>__<tool>的工具引用，再去 registry 的 MCP server 列表里比对，找不到就在日志里打警告。这个检查把技能和 MCP 两条线闭环了起来，配置问题从“运行时报错”提前到“生成时报错”。

6. 实测对比与避坑清单

6.1 新增 MCP server 的成本变化

用我本机真实维护的数据做一个对比：

时间节省不是最关键的，关键是心智负担轻了：以前每次接新工具都如临大敌，现在更像走个流程。

6.2 实战中踩过的坑

坑一：软链目标目录不存在。第一次部署时我建软链，结果 Claude 的技能目录不存在，ln -s直接失败。后来脚本里统一加mkdir -p兜底。

坑二：Windows 上符号链接需要权限。Windows 默认不给普通用户创建软链的权限，要么以管理员运行终端，要么在“开发者模式”里打开相关开关。跨盘符建链也会失败，需要保证软链和源目录在同一卷内。

坑三：有的工具升级后配置字段改名。我经历过的典型变化：某个版本把 MCP 配置从mcpServers改成mcp_servers。应对办法是生成器里加一个“适配层”，先用实测确认当前版本的字段，再把注册表里的标准字段转成目标字段。所以注册表用一个抽象结构，而不是直接照搬某工具的 schema，这很重要。

坑四：配置缓存。改完配置不重启 Agent，很多时候不生效。Claude Code 一般需要重启会话，Cursor 需要重新加载窗口，Codex 有时需要退出重进。我把“重启验证”写进了部署脚本的提示里，避免自己忘了。

坑五：不要整体覆盖用户级配置文件。这个已经强调过，是整套方案里最容易造成数据损失的操作。凡是和会话状态、历史记录混在一起的配置文件，一律字段级合并。

坑六：远程开发和容器环境需要单独处理。这个方案默认“本机单一用户”，如果你用 VS Code Remote 或者其他方式连到容器/远程机器，本机用户目录和远程路径不是一回事，软链要针对远程环境重新配置。我目前对远程容器还是用项目级配置，不强行全局同步。

6.3 什么场景不适合这套方案

这套方案适合“单人单机全 Agent 统一维护”的场景。它不适合：

• 团队协作项目：项目级配置要保留在仓库里，个人 MCP 不应该进入团队仓库，否则队友拉到你的 server 配置直接启动失败。
• 保密性要求高的环境：registry.json虽然不存真实 token，但 server 名称、用途本身可能泄露业务信息，别随便传到公共仓库。
• 工具版本跨度大的环境：不同大版本的 Agent 对配置 schema 兼容性很差，适配层工作量大，可能得不偿失。

6.4 进阶：把生成器变成一条命令

最后分享一个让体验更丝滑的技巧：把整个流程封装成一个 alias 或者脚本命令。

alias agent-sync="python3 ~/.agent-sync/scripts/generate.py && echo 'Done. Restart agents.'"

以后所有的新增 server、新增技能、技能引用校验，全部变成agent-sync一句话的事。我的registry.json和skills/目录都放进了 Git 仓库，每次改动都有历史记录，哪次配置出问题可以git diff快速回滚。

跑得时间久了，我最大的体会是：这套方案真正解决的问题不是“少写几行配置”，而是把 AI 编程工具的配置从“各工具自治”变成了“统一治理”。当你同时用多个 Agent 写代码时，MCP 配置的维护成本和技能版本的分叉是比想象中更耗精力的隐形负担。我现在的日常已经稳定在“注册表改一条 + 重启 + 继续写码”的节奏上，希望这篇分享也能帮你把类似的负担卸下来。