ln-013-config-syncer

**路径：**文件路径（references/）均相对于此技能目录。

Marketplace 和配置对齐器

**类型：**L3 Worker
**类别：**0XX Shared

安装或验证此仓库的 marketplace 和选定插件，供 Claude Code 和 Codex CLI 使用，同时不让任何一方成为另一方的事实来源。agile-workflow 是默认的开发插件；仅在明确请求或选中时才安装可选插件。确认 marketplace 健康状况后，以非破坏性方式对齐 MCP 和 Codex 策略设置。

必须阅读

**必须阅读：**加载 references/coordinator_summary_contract.md、references/environment_worker_runtime_contract.md 和 references/worker_runtime_contract.md
**必须阅读：**加载 references/agent_skill_roots_contract.md

---

输入 / 输出

方向	内容
输入	操作系统信息、每个 Agent 的 disabled 标志、targets（claude / codex / both / all）、plugins（默认 agile-workflow、明确列出的插件，或 all）、dry_run 标志、可选的 auto_install_providers 标志、可选的 runId、可选的 summaryArtifactPath
输出	结构化摘要信封，payload.status 为 completed / skipped / error，并在 changes / detail 中提供每个目标的对齐结果

如果提供了 summaryArtifactPath，则将相同的摘要 JSON 写入该路径。如果未提供，则在行内返回摘要，并保持完全独立运行。如果未提供 runId，则在输出摘要信封前生成独立的 run_id。

dry_run=true 仅用于检测：不得注册 marketplace、安装插件、编辑 MCP/Codex 配置、写入 .bak 文件或自动安装提供程序。在摘要中返回计划执行的操作和偏差详情。

运行时

运行时系列：environment-worker-runtime

阶段配置：

1. PHASE_0_CONFIG
2. PHASE_1_DISCOVER_STATE
3. PHASE_2_VERIFY_MARKETPLACE_INSTALLS
4. PHASE_3_ALIGN_MCP_SETTINGS
5. PHASE_4_ALIGN_CODEX_POLICY 5a. PHASE_4A_MCP_PROVIDER_CHECK
6. PHASE_5_WRITE_SUMMARY
7. PHASE_6_SELF_CHECK

运行时规则：

• 输出 summary_kind=env-marketplace-align
• 独立运行时生成自己的 run_id，并写入 Worker 系列的默认产物路径
• 托管运行必须同时提供 runId 和 summaryArtifactPath，且必须将摘要写入指定的确切路径
• 始终先写入经过验证的摘要产物，再给出最终结果

输出约定

始终按照以下文档构建结构化的 env-marketplace-align 摘要信封：

• references/coordinator_summary_contract.md
• references/environment_worker_runtime_contract.md

Payload 字段：

• targets
• plugin_alignment
• marketplace_health
• mcp_alignment
• mcp_providers
• codex_execution_defaults
• status

---

各操作系统的配置路径

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

---

工作流

Discover State -> Verify Marketplace Installs -> Align MCP -> Align Codex Policy -> Verify & Report

第 1 阶段：发现状态

1. 读取 Claude 设置：
   • ~/.claude.json（主要）+ ~/.claude/settings.json（备用）
   • 提取 mcpServers、已启用的市场和插件，以及钩子状态
2. 读取 Codex 配置：
   • ~/.codex/config.toml
   • 提取 [mcp_servers.*]、[marketplaces.*]、顶层的 approval_policy 和顶层的 sandbox_mode
3. 检查仓库中的市场相关内容：
   • Claude：.claude-plugin/marketplace.json
   • Codex：.agents/plugins/marketplace.json
   • Codex 插件清单：plugins/*/.codex-plugin/plugin.json
4. 确定插件选择：
   • 始终包含 agile-workflow
   • 如果 plugins=all，则包含市场列出的所有插件
   • 如果提供了明确列表，则安装 agile-workflow 和所请求的插件
   • 如果为交互模式且未指定可选插件，则询问要安装哪些可选插件
   • 如果为非交互模式且未指定可选插件，则仅安装或验证 agile-workflow
5. 显示当前状态表，列出已启用的目标、已选插件、市场健康状况、重复风险发现结果，以及 Codex 执行默认设置的偏差。

第 2 阶段：验证市场安装

对于 disabled 不为 true 的每个目标：

目标	预期安装模式	验证
Claude	Claude 原生市场	市场已通过 Claude 插件设置注册，且所选插件可从 .claude-plugin/marketplace.json 解析
Codex	Codex 原生市场	市场已通过 Codex 插件设置注册，且所选插件可从 .agents/plugins/marketplace.json / plugins/*/.codex-plugin/plugin.json 解析

安装策略：

• Claude 市场：/plugin marketplace add levnikolaevich/claude-code-skills
• Claude 插件：/plugin install {plugin}@levnikolaev-skills-marketplace
• Codex 市场：codex plugin marketplace add levnikolaevich/claude-code-skills
• Codex 插件选择：验证所选插件存在于 .agents/plugins/marketplace.json 和 plugins/{plugin}/.codex-plugin/plugin.json 中；如果已安装的 Codex 版本仅通过交互式原生流程提供插件级选择，则报告该确切步骤，而不是编造不存在的 CLI 命令

规则：

• 如果 dry_run=true，不要运行市场添加/安装命令；报告将要运行的确切命令。
• 不要将 Claude 插件根目录符号链接或联接到 Codex 发现根目录。
• 不要同时向同一个 Codex 运行时暴露 Claude 桥接界面和 Codex 原生界面；技能名称重复即表示对齐失败。
• 不要删除用户插件根目录。如果检测到重复的活动根目录，请报告确切路径并请求明确的清理批准。
• 不要静默安装可选插件。
• 当仓库根目录可用时，运行 node tools/marketplace/validate.mjs。将失败报告为市场偏差。

阶段 3：对齐 MCP 设置

MCP 设置按服务名称对齐。没有哪个目标是通用的唯一事实来源。

合并策略：

1. 合并 Claude mcpServers 和 Codex [mcp_servers.*]，取两者并集。
2. 对于名称匹配的服务，保留仅存在于目标中的字段，只更新语义等同的字段。
3. 对于缺失的服务，转换格式后将其添加到请求的目标中。
4. 修改任何配置文件前，先创建 .bak。
5. 保留仅存在于目标中的服务和无关的配置区段。
6. 如果 dry_run=true，仅报告合并计划；不要创建 .bak 文件或编辑配置。

字段映射：

语义字段	Claude JSON	Codex TOML
命令	command	command
参数	args	args
环境变量	env	[mcp_servers.{name}.env]
HTTP URL	type: "http" + url	url
请求头	headers	http_headers

仅 Codex 支持的字段，需保留： bearer_token_env_var、enabled_tools、disabled_tools、startup_timeout_sec、tool_timeout_sec、enabled、required

Windows 实现说明： 使用正则表达式或反斜杠转义进行配置格式转换时，必须使用临时 .mjs 脚本文件，不得使用内联 node -e 或 bash heredoc。

阶段 4：对齐 Hooks 和 Codex 策略

Claude hooks：

• Claude hook/样式同步仍仅适用于 Claude。
• 不要将 Claude hooks 投射到 Codex（两者的 wire 格式不同）。

Codex hooks：

• 不要将 Claude hooks 投射到 Codex（两者的 wire 格式不同）。
• 不要从此 marketplace 安装特定产品的 Codex hook 垫片。需要 Codex hooks 的运行时产品应自行负责其 hook 脚本、信任模型、验证和服务生命周期。
• 不要写入旧版 [features] codex_hooks = true 别名。当前 Codex 使用稳定版 hooks 功能，规范区块为纯 [hooks.*] TOML。
• 删除由较旧设置流程管理的过时 hook 区块时，编辑任何 config.toml 前都要先为其创建 .bak（与 MCP 合并使用相同策略）。

Codex 执行默认值：

适用于简化设置的 Codex 托管默认值：

approval_policy = "never"
sandbox_mode = "danger-full-access"

决策逻辑：

条件	操作
Codex 目标 disabled: true	跳过，报告 disabled
默认值已存在	跳过，报告 already aligned
一个或两个键缺失/有偏差	仅修补顶层托管键，保留无关的键/表，并先创建 .bak

规则：

• 仅管理顶层 approval_policy 和顶层 sandbox_mode。
• 不要重写 [windows].sandbox；它是 Windows 专用的不同设置项。
• 保留无关的 Codex 配置区段，例如 model、projects、notice、[marketplaces.*] 和 [mcp_servers.*]。

阶段 4a：MCP 提供程序检查

必须阅读： 加载 references/mcp_provider_requirements.md。

每次项目调用时，在 MCP 对齐后运行一次。目标是确保任何对齐配置中引用的每个 MCP 服务，都具备项目实际使用语言所需的语言分析器提供程序。

1. 枚举 MCP 服务。 汇总 Claude 和 Codex 配置中的 MCP 服务并集。按名称去重。
2. 检测项目语言。 按顺序探测，优先选择成本最低的方式：pyproject.toml、package.json、tsconfig.json、Cargo.toml、go.mod、*.csproj。使用 mcp__hex-line__inspect_path 进行探测；不要调用 shell。
3. 查询提供程序要求。 阅读 references/mcp_provider_requirements.md。对于 hex-graph，委派给 mcp__hex-graph__install_graph_providers。
4. 运行提供程序检查。 调用 mcp__hex-graph__install_graph_providers({ mode: "check", path: <project_root> })。除非 auto_install_providers=true，否则不要自动安装。
5. 记录结果。 将结果写入 environment_state.json 的 mcp_providers 下。

阶段 5：验证并报告

验证：

• Claude 市场注册是否指向预期来源
• Codex 市场注册是否指向预期来源
• Codex 原生插件清单是否通过 Claude 市场验证
• 是否没有指向此仓库的重复 Codex 活跃技能入口
• Codex approval_policy = "never"
• Codex sandbox_mode = "danger-full-access"
• MCP 目标配置是否已合并，且未删除目标专有设置

Marketplace and Config Alignment:
| Action         | Target | Status                                              |
|----------------|--------|-----------------------------------------------------|
| Marketplace    | Claude | registered; agile-workflow installed               |
| Marketplace    | Codex  | registered; native plugin manifests validated      |
| MCP align      | Claude | 4 servers aligned (0 deleted)                       |
| MCP align      | Codex  | 4 servers aligned (1 new)                           |
| Execution mode | Codex  | approval_policy=never; sandbox_mode=danger-full-access |
| Hooks          | Codex  | skipped (not supported)                             |

---

关键规则

1. 独立安装。 Claude 和 Codex 通过各自原生的市场流程安装技能。
2. 任何 Agent 都不能作为其他 Agent 技能安装的事实来源。
3. 默认插件集。 默认安装或验证 agile-workflow，因为它包含开发工作流。
4. 明确选择可选插件。 仅在用户请求、选择或设置 plugins=all 时安装非默认插件。
5. 不复制项目命令。 不要将 .claude/commands 复制到 Codex；项目本地命令仅适用于特定宿主，除非将其表示为市场技能／插件。
6. 非破坏性合并。 保留目标专有的服务和设置。
7. 不保留重复的活跃入口。 一个运行时不能同时从旧版桥接根目录和原生插件根目录看到相同的技能名称。
8. 不丢失数据。 如果目标路径上存在真实目录，则发出警告并跳过，绝不盲目删除。
9. 写入前备份。 修改任何配置文件前，创建 .bak 文件。
10. 试运行只读。 dry_run=true 仅报告计划执行的命令和配置变更，不修改用户状态或仓库跟踪的状态。
11. 遵循 disabled 标记。 对已禁用的 Agent 跳过所有操作。
12. 幂等。 可安全地多次运行。已符合要求的状态将跳过。
13. 仅支持 Claude 和 Codex。 不要添加无关的 Agent 分支。

反模式

不要	应当
将 Claude 视为 Codex 的事实来源	分别为每个 Agent 安装
将 .codex/skills 符号链接到 .claude/plugins	使用 Codex 原生市场注册
同时启用桥接和原生 Codex 入口	仅保留一个活跃的 Codex 安装入口
默认安装市场中的所有插件	默认安装 agile-workflow，其余插件须明确选择
将项目本地的 .claude/commands 复制到 Codex	将可复用行为表示为市场技能／插件
从头覆盖目标配置	读取 → 深度合并 → 备份 → 编辑
自动删除插件／缓存目录	报告具体清理步骤，并要求明确批准

---

完成标准

• 已发现 Claude 和 Codex 目标配置
• 已根据目标验证或安装市场注册
• 已为启用的目标验证或安装 agile-workflow
• 仅在明确请求或选择时安装可选插件
• dry_run=true 未执行任何市场、插件、配置、备份或提供方变更
• 已验证技能安装入口，且不存在重复的活跃根目录
• 已验证 Codex 原生插件清单
• 已对齐 MCP 设置，且未删除目标专有设置
• 已对齐 Codex 执行默认值，或明确报告偏差
• 仅为受支持的目标处理钩子（Claude 钩子仅适用于 Claude；特定于产品的 Codex 钩子交由所属运行时处理）
• 已完成 MCP 提供方检查，或明确跳过
• 已返回结构化摘要
• 已将摘要产物写入受管或独立运行时路径

---

版本： 2.0.0
最后更新： 2026-04-14