ln-004-agent-config-sync

路径： 文件路径（shared/、references/、../ln-*）均相对于技能仓库根目录。如果在当前工作目录中找不到，请定位此 SKILL.md 目录，并向上一级找到仓库根目录。

Agent 同步（独立实用工具）

类型： 独立实用工具
类别： 0XX 共享

将 Claude Code 中的技能和 MCP 服务配置（作为事实来源）同步到 Gemini CLI 和 Codex CLI。为技能创建符号链接，并复制/转换 MCP 设置。

---

何时使用此技能

• 在 Claude Code 设置中添加/移除 MCP 服务后
• 在 Claude Code 中安装新插件后
• 首次在 Claude Code 旁设置 Gemini CLI 或 Codex CLI 时
• 定期同步，确保所有 Agent 保持一致

---

输入参数

参数	必填	默认值	说明
targets	否	both	gemini、codex 或 both
mode	否	full	skills（仅符号链接）、mcp（仅 MCP）或 full（两者）
dry_run	否	false	显示计划执行的操作，但不执行

---

工作流

Detect OS → Discover Configs → Sync Skills → Sync MCP → Report

阶段 0：检测操作系统

检查项	结果	影响
uname 或平台	win32 / darwin / linux	Junction 还是符号链接
主目录	$HOME 或 $USERPROFILE	配置路径

各操作系统的路径：

Agent	Windows	macOS / Linux
Claude	%USERPROFILE%\.claude.json（主要）	~/.claude.json（主要）
Claude	%USERPROFILE%\.claude\settings.json（备用）	~/.claude/settings.json（备用）
Gemini	%USERPROFILE%\.gemini\settings.json	~/.gemini/settings.json
Codex	%USERPROFILE%\.codex\config.toml	~/.codex/config.toml

阶段 1：发现当前状态

1. 读取 Claude 设置（检查两个来源并合并）：

   • 解析 ~/.claude.json → 提取 mcpServers 块（主要来源，应用状态文件）
   • 解析 ~/.claude/settings.json → 提取 mcpServers 块（备用来源，用户设置文件）
   • 合并：按服务名称以主要来源覆盖备用来源
   • 如果两者都没有 mcpServers → 警告“No MCP servers configured in Claude”，跳过 MCP 同步

2. 读取目标配置（如果存在）：

   • Gemini：解析 ~/.gemini/settings.json → 提取现有的 mcpServers
   • Codex：解析 ~/.codex/config.toml → 提取现有的 [mcp_servers.*]

3. 检测已安装的插件：

   • 对 ~/.claude/plugins/*/plugin.json 执行 Glob → 列出插件目录
   • 同时检查技能仓库本身是否为插件来源

4. 检查现有符号链接：

   • ~/.gemini/skills → 是否存在？指向何处？
   • ~/.codex/skills → 是否存在？指向何处？

5. 显示当前状态：

   Current State:
   | Agent | Skills | MCP Servers | Config Exists |
   |-------|--------|-------------|---------------|
   | Claude (source) | 5 plugins | 4 servers | yes |
   | Gemini | no link | 2 servers | yes |
   | Codex | → ~/.claude/plugins | 4 servers | yes |
   

阶段 2：同步技能（符号链接/Junction）

对 targets 中的每个目标（gemini、codex）执行：

1. 确定链接路径：

   • Gemini：~/.gemini/skills
   • Codex：~/.codex/skills

2. 检查链接是否已正确创建：

   • 如果链接存在且指向正确来源 → 跳过（已同步）
   • 如果链接存在但指向错误来源 → 发出警告，并在替换前询问用户
   • 如果存在常规目录（而非链接） → 警告“目标是真实目录，而非链接。为避免数据丢失，跳过。”

3. 确定来源：

   • 如果只有一个插件：直接链接到该插件目录
   • 如果有多个插件：询问用户要共享哪个插件

4. 创建链接：

   操作系统	命令
   Windows	cmd /c mklink /J "{target_path}" "{source_path}"
   macOS / Linux	ln -s "{source_path}" "{target_path}"

5. 验证： 检查链接是否存在且能正确解析

阶段 3：同步 MCP 设置

来源： ~/.claude.json（主要）+ ~/.claude/settings.json（备用）→ 合并后的 mcpServers

3a：Claude → Gemini（JSON → JSON）

1. 将 Claude mcpServers 读取为 JSON 对象
2. 读取 Gemini settings.json（如果文件缺失，则创建 {}）
3. 合并策略： Claude 服务按键名覆盖 Gemini 服务。保留仅存在于 Gemini 中的服务。
4. 写入更新后的 settings.json

转换： 必须映射传输类型：

Claude 字段	Gemini 字段	备注
type: "http" + url	httpUrl	Streamable HTTP
type: "sse" + url	url	SSE 传输
command + args	command + args + cwd	stdio（格式相同）
env	env	格式相同（Gemini 使用 $VAR_NAME 语法）
headers	headers	格式相同（JSON 对象，用于 url/httpUrl）

仅限 Gemini 的字段（不从 Claude 映射）：

• timeout — 请求超时时间，单位为 ms（默认：10min）
• trust — 跳过工具确认
• includeTools / excludeTools — 工具允许列表／禁止列表

3b：Claude → Codex（JSON → TOML）

1. 将 Claude mcpServers 读取为 JSON 对象

2. 读取 Codex config.toml（如果文件缺失，则创建空文件）

3. 转换每个服务：

   Claude JSON 字段	Codex TOML 字段	备注
   command	command	相同
   args	args	JSON 数组 → TOML 数组
   env	[mcp_servers.{name}.env]	嵌套表
   type: "http" + url	url	Streamable HTTP（Codex 会根据是否存在 url 自动检测）
   type: "sse" + url	url	SSE → Streamable HTTP（使用相同的 url 字段）
   headers	http_headers	键名不同！ 静态标头值

   转换示例：

   "context7": {
     "command": "npx",
     "args": ["-y", "@upstash/context7-mcp"]
   }
   

   [mcp_servers.context7]
   command = "npx"
   args = ["-y", "@upstash/context7-mcp"]
   

4. 合并策略： Claude 服务覆盖 Codex 服务。保留仅存在于 Codex 中的服务。

5. 写入更新后的 config.toml

仅限 Codex 的字段（原样保留，Claude 中没有对应项）：

• bearer_token_env_var — Codex bearer token 身份验证
• enabled_tools / disabled_tools — Codex 工具筛选
• startup_timeout_sec / tool_timeout_sec — Codex 超时时间
• enabled / required — Codex 服务生命周期
• env_vars / env_http_headers — 基于 Codex 环境变量的标头

阶段 4：报告

Sync Complete:
| Action | Target | Status |
|--------|--------|--------|
| Skills symlink | Gemini | Created → ~/.claude/plugins/... |
| Skills symlink | Codex | Already linked |
| MCP sync | Gemini | 4 servers synced (2 new, 2 updated) |
| MCP sync | Codex | 4 servers synced (1 new, 3 updated) |

---

关键规则

1. Claude = 唯一事实来源。 切勿写入 Claude 设置。只读来源。
2. 非破坏性合并。 保留仅存在于目标端的服务／设置。仅添加或更新 Claude 服务。
3. 不丢失数据。 如果目标是真实目录（不是符号链接），则发出警告并跳过，绝不删除。
4. 写入前备份。 修改任何配置文件前，创建 .bak 副本。
5. 先试运行。 如果 dry_run=true，则显示所有计划操作，不执行任何操作。
6. 冲突时询问。 如果符号链接指向不同的来源，则询问用户，不要自动替换。

反模式

• 从 Gemini/Codex 写入 Claude 设置（反向同步）
• 同步时删除仅存在于目标端的 MCP 服务
• 在符号链接内创建符号链接（形成循环）
• 不备份就修改配置文件

---

完成定义

• 成功读取 Claude 设置
• 为每个目标创建／验证 Skills 符号链接
• 已同步 MCP 设置并完成格式转换（Codex 使用 JSON→TOML）
• 修改任何配置前已创建备份文件
• 已显示包含所有操作和警告的报告

---

版本： 1.1.0 最后更新： 2026-03-09