168 lines
9.7 KiB
Markdown
168 lines
9.7 KiB
Markdown
---
|
||
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 环境，并确保 E:\MCP_design 下所有 MCP 都已在 Claude Code 和 Codex 中注册。当用户提到"同步skills"、"skills同步"、"tools sync"、"tools-sync"、"同步codex"、"同步MCP"、"环境同步"、"skills-win"、"把skills推上去/拉下来"、"新电脑配置claude/codex环境"、"检查MCP注册"、"skills_env"时，必须使用此技能，即使用户没有明确说"skill"二字。
|
||
---
|
||
|
||
# tools-sync：Claude Code / Codex 工具链同步
|
||
|
||
## 目标与总体思路
|
||
|
||
一台开发机上有两个 AI 编码工具（Claude Code 和 Codex），它们各自有 skills 目录和 MCP
|
||
注册表。这个 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。
|
||
- **机器相关的参数不进 git**。每台电脑的软件安装路径、IP、账号等都记录在
|
||
`~\skills_env.md`（用户主目录下，天然在两个仓库检出之外，不会被 git 同步）。
|
||
skills 里引用参数时写"见 ~\skills_env.md 的 XXX 条目"，不写死路径。
|
||
- **凭据不写进任何会被同步的文件**。git.rpchannel.com 的凭据优先用 Windows
|
||
凭据管理器（`cmdkey /list` 里应有 `git:http://git.rpchannel.com` 条目）；
|
||
只有在新机器首次配置时，才从 `~\skills_env.md` 读取用户名/密码完成首次
|
||
clone（之后 credential helper 会缓存）。
|
||
|
||
完整跑一遍下面 6 个阶段就是一次"同步"。用户只要求其中一部分（比如"把 skills 推上去"）
|
||
时，跑对应阶段即可，但阶段 0 永远先做。
|
||
|
||
## 阶段 0 — 读取本机环境档案 ~\skills_env.md
|
||
|
||
先读 `~\skills_env.md`。后续所有阶段的路径、URL、账号都以它为准。
|
||
|
||
- 如果文件不存在（通常是新电脑）：从本 skill 的
|
||
`references/skills_env_template.md` 复制一份到 `~\skills_env.md`，
|
||
然后逐项核对模板里的路径在本机是否真实存在（`Test-Path`），把不符的改成实际值，
|
||
缺失的软件记为"未安装"。凭据字段让用户填写或从用户处确认，不要猜。
|
||
- 如果存在：快速通读，注意 `status` 类标记和上次同步遗留的 TODO。
|
||
|
||
## 阶段 1 — 同步 ~\.claude\skills（主副本）
|
||
|
||
用 `scripts/sync_repos.ps1` 做机械部分；它失败或报冲突时再人工介入。
|
||
|
||
```powershell
|
||
# 从 skill 目录运行；RepoUrl 取自 skills_env.md
|
||
powershell -File <skill目录>\scripts\sync_repos.ps1 -RepoUrl <origin_url>
|
||
```
|
||
|
||
脚本对主副本做的事：`git add -A` → 有变更则 commit（消息格式
|
||
`sync: <机器名> <日期> <一句话摘要>`）→ `git pull --rebase` → `git push`。
|
||
|
||
人工介入的情形：
|
||
|
||
- **rebase 冲突**：逐个文件看冲突双方，skills 文本冲突通常保留两边语义合并；
|
||
解不了就 `git rebase --abort` 并向用户报告冲突文件清单，让用户裁决。
|
||
- **push 被拒（认证）**：检查凭据管理器条目；新机器上用
|
||
`git config --global credential.helper manager` 后重试一次，让 credential
|
||
helper 弹窗或从 skills_env.md 读凭据拼一次性 URL 完成首次认证。
|
||
认证成功后确认凭据已被缓存（再 fetch 一次不应再要密码）。
|
||
- **不该入库的文件**：commit 前扫一眼 `git status`，运行时产物（.sqlite、.pckl、
|
||
日志、缓存目录）应加进 `.gitignore` 而不是提交。看到就顺手补 `.gitignore`。
|
||
|
||
## 阶段 2 — 对齐 ~\.codex\skills（junction 对账）
|
||
|
||
同一个脚本接着处理 codex 侧。它对主副本的每个顶层 skill 目录做三件事：
|
||
|
||
- codex 侧没有同名条目 → 创建 junction（`New-Item -ItemType Junction`，
|
||
Windows 上不需要管理员权限，Codex 对 junction 完全透明）。
|
||
- 已是 junction → 跳过（内容天然一致，无需任何拷贝）。
|
||
- 是**真实目录**（挡住了链接）→ 脚本停下来列出这些目录。停的原因：真实目录
|
||
里可能有 codex 独有的、还没入库的内容。处理原则——有价值的内容先复制进
|
||
`~\.claude\skills` 走阶段 1 入库，确认无需保留后用 `-Force` 重跑，脚本会
|
||
删掉真实目录并建 junction。
|
||
|
||
脚本还会清理"指向已删除主副本目录"的失效 junction（skill 在仓库里被删除或
|
||
改名后残留的链接）。codex 自带的系统 skills（`.system\`）永远不动。
|
||
|
||
校验注册：主副本每个 skill 目录在 codex 侧都应有同名 junction 且透出
|
||
`SKILL.md`（脚本已内置该检查）。提醒用户：Codex 要开新会话才会扫到新 skills。
|
||
|
||
## 阶段 3 — 硬编码审计与 skills_env.md 回填
|
||
|
||
目的：让仓库里的 skills 在任何一台按 `~\skills_env.md` 配置好的电脑上都能用。
|
||
|
||
在 `~\.claude\skills`（排除 `.system`）里搜这几类硬编码：
|
||
|
||
- 盘符绝对路径：正则 `[A-Za-z]:[\\/]`（如 `D:\Xilinx\Vivado`、`E:\MCP_design`）
|
||
- IP 地址：`\d+\.\d+\.\d+\.\d+`
|
||
- 明文凭据：`password`、`密码`、常见口令字样
|
||
|
||
对每个命中做判断，不要机械替换：
|
||
|
||
- **机器相关的值**（安装路径、板卡 IP、conda 路径）→ 确认已记录在
|
||
`~\skills_env.md` 对应条目（没有就补上），然后把 skill 原文改成引用式写法，
|
||
例如"Vivado 路径见 `~\skills_env.md` 的 `VIVADO_PATH`"。skill 的执行逻辑
|
||
改为：运行时先读 skills_env.md 取值。
|
||
- **明文密码出现在会被 git 同步的文件里** → 这是必须当场修复的问题：
|
||
从文件里删掉，移入 `~\skills_env.md`，并向用户报告（密码已进过 git
|
||
历史的话，建议用户改密码）。
|
||
- **协议性/普适的值**（如标准端口号、公开 URL）→ 保留，不算硬编码。
|
||
|
||
一次审计不必把所有历史 skills 全部重构完；至少保证：新增/本次改动的 skill 零硬编码，
|
||
存量 skill 的命中清单写进最终报告，让用户决定分批改。改动之后回到阶段 1 再
|
||
commit + push 一次（junction 模型下 codex 侧自动同步，无需额外操作）。
|
||
|
||
## 阶段 4 — langgraph 开发环境校验
|
||
|
||
很多 skills（vivado-mcp、fpga 系列、langgraph 系列）依赖 conda 的 `langgraph` 环境。
|
||
校验方式（路径以 skills_env.md 的 `CONDA_LANGGRAPH_PYTHON` 为准）：
|
||
|
||
```powershell
|
||
& <CONDA_LANGGRAPH_PYTHON> -c "import langgraph, langgraph.graph, langchain_core; print('langgraph env OK')"
|
||
```
|
||
|
||
失败（环境不存在或包缺失）→ 调用 `langgraph-vivado-install` skill 完成安装，
|
||
装好后把实际的 python 路径回填到 `~\skills_env.md`。
|
||
|
||
## 阶段 5 — MCP server 注册校验（Claude Code + Codex 两边）
|
||
|
||
MCP 的清单真源是 `E:\MCP_design\mcp_list.md`（路径见 skills_env.md 的
|
||
`MCP_DESIGN_ROOT`），每行一个 MCP 工程目录。对清单里的每一项：
|
||
|
||
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 上
|
||
没有这两个变量时中文输出会乱码）。
|
||
3. **可启动性抽查**：对新注册的 MCP，直接运行其 command + args 数秒，
|
||
确认进程能起来、没有立刻报 import/路径错误（stdio MCP 起来后会静默等
|
||
输入，这就算通过，Ctrl-C 掉即可）。
|
||
|
||
注意两侧配置语义相同但格式不同（JSON vs TOML），同一个 MCP 在两边的
|
||
command/args/env 应当一致；发现两边漂移（比如只有一边改了 VIVADO_PATH）时，
|
||
以 skills_env.md 记录的值为准改齐两边。
|
||
|
||
## 阶段 6 — 输出同步报告
|
||
|
||
最后用这个结构向用户汇报（有问题的条目放前面）：
|
||
|
||
```
|
||
# tools-sync 同步报告 <日期>
|
||
## skills 同步
|
||
- ~\.claude\skills: <pull/push 结果，commit 摘要>
|
||
- ~\.codex\skills: <pull 结果，注册差集>
|
||
## 硬编码审计
|
||
- 本次修复: <清单>
|
||
- 遗留待改: <清单>
|
||
## 环境
|
||
- langgraph env: OK / 已重装 / 失败原因
|
||
- MCP 注册: <两侧各缺了什么、补了什么、抽查结果>
|
||
## 需要用户决定的事项
|
||
- <冲突、密码泄露、codex 独有 skill 去留……没有则写"无">
|
||
```
|
||
|
||
## 边界与安全
|
||
|
||
- 本 skill 会 push 到远端仓库——commit 前把将要提交的文件列表给用户过目
|
||
（自动化场景下至少写进报告）。绝不 `push --force`。
|
||
- `~\skills_env.md` 含凭据，任何情况下不将其内容或凭据字段写入仓库内文件、
|
||
commit message 或对外输出。
|
||
- 不动 `~\.codex\skills\.system\`（Codex 自带系统 skills）和
|
||
`~\.claude\skills\.system\`。
|
||
- 修改 `~\.codex\config.toml` 前先备份为 `config.toml.bak-<日期>`，TOML 写坏
|
||
会导致 Codex 起不来。
|