sync: BOWEI 2026-09-07 tools-sync 改为 junction 模型（registry 双向 ingest + 修复）

- sync_repos.ps1: 每个 skill 只在 ~\.claude\skills 有一份物理副本，其余 registry 一律 junction；新增 registry-only skill 的自动 ingest、MISDIRECTED 链接修复、同名内容分叉的 CONFLICT 报告，以及只对 -MirrorRegistry 做全量镜像。 - SKILL.md: 重写阶段 1/2，补 Codex MCP 存储模型（config.toml 惰性， codex mcp list --json 是唯一权威口径）与 CLI 升级会清空注册表的事实。 - sync_mcp_registrations.ps1 + references/codex_mcp_wanted_keys.json: 报告 codex-cli 无接口可设的键（tool_timeout_sec / env_vars）为 "registered, but incomplete" 而非失败。 - tests/test_sync_repos_registries.ps1: registry 对账的回归测试。 - .gitignore: orchestration（Orca 自带的发现桩，同 orca-cli）列为 local-only。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01438Zbcx49e4o46uSA71mFF
2026-09-07 16:22:09 +08:00
parent aca7c799a8
commit f665448376
8 changed files with 467 additions and 111 deletions
@@ -1,6 +1,6 @@
 ---
 name: tools-sync
-description: 在本机统一同步并配置 Claude Code 与 Codex 的 skills、MCP server 和开发环境：将 ~\.claude\skills 和 ~\.codex\skills 与 git.rpchannel.com 上的 bowei/skills-win 仓库保持同步，审计 skills 中的硬编码参数并迁移到本机 ~\skills_env.md，校验 langgraph conda 环境，双向发现并补齐 Claude Code 与 Codex 的用户 MCP 注册，同时确保 E:\MCP_design 下所有 MCP 均已注册。同步的传输一旦出问题，本 skill 还负责登录 gitea 服务器（上海 mac 的 Docker 容器）诊断并修复，直到同步真正成功。当用户提到"同步skills"、"skills同步"、"tools sync"、"tools-sync"、"同步codex"、"同步MCP"、"环境同步"、"skills-win"、"把skills推上去/拉下来"、"新电脑配置claude/codex环境"、"检查MCP注册"、"skills_env"，或者 git.rpchannel.com 出现"clone/fetch 失败"、"bad pack header"、"early EOF"、"RPC failed"、"推不上去/拉不下来"、"gitea 坏了/连不上/要修"时，必须使用此技能，即使用户没有明确说"skill"二字。
+description: 在本机统一同步并配置 Claude Code 与 Codex 的 skills（~\.claude\skills / ~\.codex\skills / ~\.agents\skills）、用户级 MCP 注册和开发环境：主副本与 git.rpchannel.com 上的 bowei/skills-win 仓库保持同步（其余目录一律是 junction），审计 skills 中的硬编码参数并迁移到本机 ~\skills_env.md，校验 langgraph conda 环境，双向发现并补齐 Claude Code 与 Codex 的用户 MCP 注册，同时确保 E:\MCP_design 下所有 MCP 均已注册。同步的传输一旦出问题，本 skill 还负责登录 gitea 服务器（上海 mac 的 Docker 容器）诊断并修复，直到同步真正成功。当用户提到“同步skills”、“skills同步”、“tools sync”、“tools-sync”、“同步codex”、“codex 里的 skill 怎么进仓库”、“把 codex 新写的 skill 收进来”、“同步MCP”、“MCP 注册/更新/补齐”、“检查MCP注册”、“codex mcp 没了”、“环境同步”、“skills-win”、“把skills推上去/拉下来”、“新电脑配置claude/codex环境”、“skills_env”、“skills 硬编码路径”，或者 git.rpchannel.com 出现“clone/fetch 失败”、“bad pack header”、“early EOF”、“RPC failed”、“推不上去/拉不下来”、“gitea 坏了/连不上/要修”时，必须使用此技能，即使用户没有明确说“skill”二字。也用于处理 junction 指错、两侧 skill 分叉、以及 skills 里的硬编码路径/密码需要迁进 ~\skills_env.md 的场合。
 ---

 # tools-sync：Claude Code / Codex 工具链同步
@@ -11,12 +11,22 @@ description: 在本机统一同步并配置 Claude Code 与 Codex 的 skills、M
 注册表。这个 skill 的职责是让它们保持一致，并且可以在一台新电脑上从零复原整套配置：

 - **skills 的唯一真源**是 `http://git.rpchannel.com/bowei/skills-win.git`（remote 名 `origin`）。
-  `~\.claude\skills` 是唯一的 git 检出（主副本）；`~\.codex\skills` 下的每个 skill
-  是指向主副本对应目录的 **junction（目录联接）**——两个工具共享同一份物理文件，
-  从机制上杜绝两侧漂移，git 操作只发生在主副本一处。
-  Codex 没有注册命令——它在会话启动时自动扫描 `~\.codex\skills` 下所有含 `SKILL.md`
-  的目录（junction 对它透明），所以"注册到 Codex" = "junction 存在且指向的目录含
-  SKILL.md"，新开的 Codex 会话才会扫到新 skill。
+  `~\.claude\skills` 是唯一的 git 检出（主副本）；其余目录里的每个 skill 都是指向主副本
+  对应目录的 **junction（目录联接）**——所有工具共享同一份物理文件，从机制上杜绝漂移，
+  git 操作只发生在主副本一处。
+  受管的 registry 有两个：`~\.codex\skills`（Codex 自己的目录，主副本在这里做全量镜像）和
+  `~\.agents\skills`（Codex / Copilot CLI / Gemini CLI 都会扫的跨工具别名目录）。
+  **`~\.agents\skills` 只做发现与修复，不做全量镜像**：Codex 两个目录都扫，全量铺进去会让
+  同一个 skill 注册两遍。
+- **同步是双向的**。Codex 侧新建的 skill（真实目录、含 SKILL.md、主副本里没有同名）会被
+  **自动 ingest**：移进 `~\.claude\skills` 成为主副本，原地换成 junction，随后跟着阶段 1 入库。
+  这是"Codex 里写的 skill 如何进仓库"的唯一正规路径，不需要人工搬运。
+  Codex 没有注册命令——它在会话启动时自动扫描上述目录下所有含 `SKILL.md` 的目录
+  （junction 对它透明），所以"注册到 Codex" = "junction 存在且指向的目录含 SKILL.md"，
+  新开的 Codex 会话才会扫到新 skill。
+- **Codex 插件（`codex plugin list`）自带的 skill 和 MCP 归 marketplace 所有**，不属于可移植
+  用户配置，任何阶段都不要 ingest、不要复制到 Claude 侧。同理 `~\.agents\skills` 里指向
+  `~\.matlab\agentic-toolkits` 的 junction 是 MathWorks 装的，脚本只计数不动它。
 - **机器相关的参数不进 git**。每台电脑的软件安装路径、IP、账号等都记录在
  `~\skills_env.md`（用户主目录下，天然在两个仓库检出之外，不会被 git 同步）。
  skills 里引用参数时写"见 ~\skills_env.md 的 XXX 条目"，不写死路径。
@@ -137,23 +147,38 @@ powershell -File <skill目录>\scripts\gitea_doctor.ps1 -Fix     # 检查→登
 第三步能直接看出是 gitea 丢了 pack 还是 git 自己没产出——上次就是这一步定的案。
 定位到新根因后，把它补进 `gitea_triage.sh` 的检查表，别只修这一次。

-## 阶段 2 — 对齐 ~\.codex\skills（junction 对账）

-同一个脚本接着处理 codex 侧。它对主副本的每个顶层 skill 目录做三件事：
+## 阶段 2 — registry 对账（ingest + 修复 + 镜像）

- codex 侧没有同名条目 → 创建 junction（`New-Item -ItemType Junction`，
-  Windows 上不需要管理员权限，Codex 对 junction 完全透明）。
- 已是 junction → 跳过（内容天然一致，无需任何拷贝）。
- 是**真实目录**（挡住了链接）→ 脚本停下来列出这些目录。停的原因：真实目录
-  里可能有 codex 独有的、还没入库的内容。处理原则——有价值的内容先复制进
-  `~\.claude\skills` 走阶段 1 入库，确认无需保留后用 `-Force` 重跑，脚本会
-  删掉真实目录并建 junction。
+同一个脚本接着扫 `~\.codex\skills` 和 `~\.agents\skills`，对每个顶层条目分类处理：

-脚本还会清理"指向已删除主副本目录"的失效 junction（skill 在仓库里被删除或
-改名后残留的链接）。codex 自带的系统 skills（`.system\`）永远不动。
+| 现状 | 脚本动作 |
+|------|----------|
+| junction 指向主副本，目标存在 | 跳过（正确状态） |
+| junction 指向主副本，目标已消失 | 删除失效链接（skill 在仓库里被删或改名后的残留） |
+| junction 指向受管 registry 之外（如 `~\.matlab\agentic-toolkits`） | 只计数，不动（宿主自己装的） |
+| junction 指向**另一个 registry** 里的副本 | 报 MISDIRECTED，解析那份副本后把链接改指主副本 |
+| 真实目录，含 SKILL.md，主副本**无**同名 | **INGEST**：移进主副本 + 原地建 junction（`-NoIngest` 可关闭） |
+| 真实目录，与主副本同名且内容**相同** | 直接塌缩成 junction（丢不了东西） |
+| 真实目录，与主副本同名但内容**不同** | 报 CONFLICT，两边都不动，退出码 2 |
+| 目录里没有 SKILL.md | 忽略并说明 |

-校验注册：主副本每个 skill 目录在 codex 侧都应有同名 junction 且透出
-`SKILL.md`（脚本已内置该检查）。提醒用户：Codex 要开新会话才会扫到新 skills。
+最后把主副本每个 skill 镜像进 `-MirrorRegistry`（默认 `~\.codex\skills`）。
+`.system\` 等点开头目录永远不动。
+
+判断力要点：
+
+- **CONFLICT 是唯一需要人裁决的分支。** 内容指纹排除了 `.git`、`__pycache__`、
+  `.langgraph_api`、`*.pckl`、`*.sqlite` 这类运行时产物，所以报出来的分叉是真分叉。
+  处理方式：把想留的内容并进主副本，再带 `-Force` 重跑（`-Force` 一律主副本胜出）。
+- **ingest 进来的 skill 可能命中 `.gitignore` 的 local-only 段**（仓库里有一段
+  `/orca-cli/` 之类的本机专用规则）。脚本会 `git check-ignore` 并在报告里点名——
+  这种 skill 留在本机、不会推上远端，换电脑时不会出现。要它进仓库就删掉那条规则。
+- **registry 自带 `.git` 是历史遗留的竞争检出。** 本机 `~\.agents\skills` 就有一个指向
+  github 镜像的检出。脚本只报告不动手；等它的独有内容都 ingest 完，再由用户决定删。
+
+校验注册：主副本每个 skill 在镜像 registry 都应有同名 junction 且透出 `SKILL.md`
+（脚本已内置该检查）。提醒用户：Codex 要开新会话才会扫到新 skills。

 ## 阶段 3 — 硬编码审计与 skills_env.md 回填

@@ -194,8 +219,31 @@ commit + push 一次（junction 模型下 codex 侧自动同步，无需额外

 ## 阶段 5 — MCP server 双向发现、注册与校验（Claude Code ↔ Codex）

+### Codex 的 MCP 存储模型（codex-cli 0.150.1 实测，官方无文档）
+
+动手前必须知道这三条，否则会写出"看起来成功、实际无效"的配置：
+
+- **`codex mcp list --json` / `add` / `remove` 是唯一有效接口。** 审计读它，注册写它。
+- **`~\.codex\config.toml` 的 `[mcp_servers.*]` 节是惰性的，Codex 不读。** 实测：把
+  `node_repl` 的 `startup_timeout_sec` 从 120 改成 137，`codex mcp list` 仍报 120；
+  手写一整节则完全不出现。config.toml 里现存的那几节是历史遗留。
+  **本 skill 旧版"缺失的补写 TOML 节"是错的，别再那样做——它静默地什么也没干。**
+- **这个存储不跨 CLI 升级存活。** 2026-08-29 注册好的 7 个用户 MCP，在升级到 0.150.1
+  后全部消失。所以每次同步都要重新审计 Codex 侧，`~\skills_env.md` 的 MCP 配置节
+  才是可重建的真源。
+
+由此还有一个已知缺口：`codex mcp add` 没有 `--tool-timeout-sec` / `env_vars` 之类的参数，
+config.toml 又不生效，所以这两个键**目前无任何设置入口**。需要它们的 MCP 记在
+`references/codex_mcp_wanted_keys.json`，脚本注册完会单独报"registered, but incomplete"，
+不要把它当失败，也不要假装已配好。每次 codex-cli 升级后复查是否已有新接口。
+
+另：这两个脚本都要用 PowerShell 跑，不要用 git-bash——MSYS 会改写 `/c` 形式的参数和
+Windows 路径（实测 `codex mcp add ... /c echo hi` 的 `/c` 被改成了 `C:/`）。
+
+### 双向审计
+
 先运行双向审计脚本。它读取 Claude Code 用户级 `~\.claude.json` 的 `mcpServers` 和
-Codex 用户级 `~\.codex\config.toml` 的 `[mcp_servers.*]`，对用户可配置 MCP 做并集：
+`codex mcp list --json`，对用户可配置 MCP 做并集：

 ```powershell
 # 只审计；发现差集或漂移时退出码为 2，不修改配置
@@ -231,17 +279,17 @@ powershell -File <skill目录>\scripts\sync_mcp_registrations.ps1 -Apply -Confli
 1. **Claude Code 侧**：`claude mcp list` 或读 `~\.claude.json` 的 `mcpServers`，
   确认存在对应条目。缺失的用 `claude mcp add <name> ...` 注册，命令、解释器
   路径和 env 变量都取自 `~\skills_env.md` 的 MCP 配置节。
-2. **Codex 侧**：读 `~\.codex\config.toml` 的 `[mcp_servers.<name>]` 节。
-   缺失的按 skills_env.md 里的同一份配置补写 TOML 节（stdio 类型，
-   记得带 `PYTHONIOENCODING=utf-8`、`PYTHONUTF8=1`，Codex 在 Windows 上
-   没有这两个变量时中文输出会乱码）。
+2. **Codex 侧**：`codex mcp list --json` 确认存在对应条目。缺失的用
+   `codex mcp add <name> --env K=V -- <command> <args...>` 注册，配置取自 skills_env.md
+   的同一份表（stdio 类型记得带 `PYTHONIOENCODING=utf-8`、`PYTHONUTF8=1`，Codex 在
+   Windows 上没有这两个变量时中文输出会乱码）。
 3. **可启动性抽查**：对新注册的 MCP，直接运行其 command + args 数秒，
   确认进程能起来、没有立刻报 import/路径错误（stdio MCP 起来后会静默等
   输入，这就算通过，Ctrl-C 掉即可）。

-注意两侧配置语义相同但格式不同（JSON vs TOML）。先由双向脚本发现差集和漂移，再用
-`mcp_list.md` 查漏，最后以 skills_env.md 和实际可启动结果判定正确值。不要因为某项当前
-只在一侧出现，就假设另一侧没有安装需求。
+先由双向脚本发现差集和漂移，再用 `mcp_list.md` 查漏，最后以 skills_env.md 和实际可启动
+结果判定正确值。不要因为某项当前只在一侧出现，就假设另一侧没有安装需求——尤其 Codex 侧
+可能只是被上一次 CLI 升级清空了。

 ### MATLAB / Simulink Agentic Toolkit 专项检查与安装

@@ -256,13 +304,17 @@ powershell -File <skill目录>\scripts\sync_mcp_registrations.ps1 -Apply -Confli
   且已安装 Simulink。实际 MATLAB 根目录记录到 `~\skills_env.md` 的 `MATLAB_ROOT`。
 2. `~\.matlab\agentic-toolkits\bin\matlab-mcp-server.exe` 存在且 `--version` 可运行；
   `config.json` 的 `toolkits` 同时包含 `matlab` 与 `simulink`。
-3. Claude `~\.claude.json` 与 Codex `~\.codex\config.toml` 均有用户级 `matlab` MCP，
+3. Claude `~\.claude.json` 与 `codex mcp list --json` 均有用户级 `matlab` MCP，
   command 指向同一二进制，args 同时包含 `--matlab-session-mode=existing` 和正确的
   `--extension-file`。Claude 条目应有 `alwaysLoad=true`。
-4. Codex 的 `[mcp_servers.matlab]` 还必须有 `tool_timeout_sec = 600` 和 Windows 所需的
-   `env_vars = ["WINDIR"]`；缺少 `WINDIR` 时 Simulink 子进程可能无法正常工作。
-5. `~\.agents\skills` 中存在指向两套 Toolkit 的 junction；Claude Code 的 MATLAB /
-   Simulink plugin 或等效 skill 注册存在。
+4. Codex 侧本应还有 `tool_timeout_sec = 600` 和 Windows 所需的 `env_vars = ["WINDIR"]`
+   （缺 `WINDIR` 时 Simulink 子进程可能起不来），但 0.150.1 **没有任何接口能设置它们**
+   （见本阶段开头的存储模型）。所以这一条是**已知缺口，不作为安装完整性的判定项**：
+   脚本报出 "registered, but incomplete" 即可，写进报告的遗留事项，不要标记为失败，
+   也不要试图靠改 config.toml 绕过——那不生效。
+5. `~\.agents\skills` 中存在指向两套 Toolkit 的 junction（阶段 2 会把这类指向
+   `~\.matlab\agentic-toolkits` 的 junction 识别为宿主自有，只计数不动）；Claude Code 的
+   MATLAB / Simulink plugin 或等效 skill 注册存在。

 缺失时使用 MathWorks 官方统一安装器，不使用旧版 agent-driven 安装法：

@@ -290,8 +342,9 @@ setupAgenticToolkit("configure", Agents=["claude-code","codex"], ...
  Setup” 与 “MATLAB MCP Server Toolbox” 两个官方 Toolbox 根目录加入 path 并
  `savepath`，再用全新 MATLAB 进程通过 `which setupAgenticToolkit`、
  `which shareMATLABSession` 验证。
- 安装后重新运行双向审计脚本；`matlab` 必须显示为 Matched。再直接解析两边配置，确认
-  Simulink extension、Codex timeout 与 `WINDIR` 未被规范化比较遗漏。
+- 安装后重新运行双向审计脚本；`matlab` 必须显示为 Matched。再直接比对两边的 command/args，
+  确认 Simulink extension 未被规范化比较遗漏（Codex timeout 与 `WINDIR` 见上面第 4 条，
+  当前无法设置，不必核对）。
 - 使用 Simulink 工具前，每个 MATLAB 会话运行
  `addpath("~/.matlab/agentic-toolkits/simulink"); satk_initialize`，然后重启 Claude Code /
  Codex 会话。MCP 健康检查在没有共享 MATLAB 会话时可能显示连接失败，这不等于未安装。
@@ -306,15 +359,17 @@ setupAgenticToolkit("configure", Agents=["claude-code","codex"], ...
 - ~\.claude\skills: <pull/push 结果，commit 摘要>
 - 远端校验: origin/main = <sha>，与本地一致 / **不一致：N 个 commit 滞留本机**
 - 服务端: 传输两面均正常 / 医生修复了 <哪几项> / **仍不可用：<RESULT 行>**
- ~\.codex\skills:  <pull 结果，注册差集>
+- 从 registry ingest: <被自动收进主副本的 codex/agents 侧 skill；没有则写"无">
+- junction 对账: <修复的 MISDIRECTED、塌缩的重复、清理的失效链接、镜像新建数>
 ## 硬编码审计
 - 本次修复: <清单>
 - 遗留待改: <清单>
 ## 环境
 - langgraph env: OK / 已重装 / 失败原因
 - MCP 注册: <Claude 独有、Codex 独有、同名漂移、已补齐、排除项、清单查漏、MATLAB/Simulink 专项检查、抽查结果>
+- MCP 已注册但不完整: <codex-cli 无接口可设的键；没有则写"无">
 ## 需要用户决定的事项
- <冲突、密码泄露、codex 独有 skill 去留……没有则写"无">
+- <CONFLICT 分叉、密码泄露、local-only 的 ingest 项、registry 里的竞争检出……没有则写"无">
 ```

 ## 边界与安全
@@ -324,6 +379,9 @@ setupAgenticToolkit("configure", Agents=["claude-code","codex"], ...
 - `~\skills_env.md` 含凭据，任何情况下不将其内容或凭据字段写入仓库内文件、
  commit message 或对外输出。
 - 不动 `~\.codex\skills\.system\`（Codex 自带系统 skills）和
-  `~\.claude\skills\.system\`。
+  `~\.claude\skills\.system\`；也不动 `codex plugin` 装的 marketplace 插件。
 - 修改 `~\.codex\config.toml` 前先备份为 `config.toml.bak-<日期>`，TOML 写坏
  会导致 Codex 起不来。
+- **ingest 会 `Move-Item`，`-Force` 会 `Remove-Item -Recurse`。** 先 `-DryRun` 看清单，
+  确认没有误判再实跑；CONFLICT 项在用户裁决前脚本不会碰。
+- 两个脚本都从 PowerShell 运行，不要用 git-bash（MSYS 会改写参数里的 `/c` 和 Windows 路径）。