bowei/skills-win
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1334ad4a6404e44c65a6200b628d1d2eddd44988
skills-win/tools-sync/SKILL.md
T
Myfro9 1334ad4a64 sync: WIN10-I9-64G 2026-07-20
2026-07-20 18:26:14 +08:00

9.4 KiB
Raw Blame History

name, description
name description
tools-sync 在本机统一同步并配置 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 是主工作副本，~\.codex\skills 是同一仓库的第二个检出（镜像）。 Codex 没有注册命令——它在会话启动时自动扫描 ~\.codex\skills 下所有含 SKILL.md 的目录，所以"注册到 Codex" = "目录出现在那里且含 SKILL.md"。
  • 机器相关的参数不进 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 做机械部分；它失败或报冲突时再人工介入。

# 从 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（镜像检出）

同一个脚本会接着处理 codex 侧。逻辑和原因：

  • 已是 git 仓库 → git pull --rebase 即可。
  • 还不是 git 仓库（首次转换）→ 脚本执行 git init + remote add origin + fetch + git reset origin/main，然后停下来列出"本地与仓库不一致"的文件。 这一步停是有原因的：codex 目录里可能有比仓库新的本地修改或 codex 独有的 skill。处理原则——codex 独有且有价值的 skill，先复制到 ~\.claude\skills 走阶段 1 入库，再回来；确认没有需要保留的差异后，用 -Force 重跑让脚本 git checkout -f 对齐到仓库版本。codex 自带的系统 skills（.system/、 vercel 系列等）已在 .gitignore 里，不会被动。
  • 同步完成后校验注册：仓库里每个顶层 skill 目录都应在 ~\.codex\skills 出现且含 SKILL.md。列出两侧目录做差集，差集应为空（忽略 .gitignore 中的 codex 专属条目）。提醒用户：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 一次，并在 codex 侧 pull，保证两边一致。

阶段 4 — langgraph 开发环境校验

很多 skills（vivado-mcp、fpga 系列、langgraph 系列）依赖 conda 的 langgraph 环境。 校验方式（路径以 skills_env.md 的 CONDA_LANGGRAPH_PYTHON 为准）：

& <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 起不来。
Reference in New Issue View Git Blame Copy Permalink