vedic-astro-skills 多发行面同步机制详解：skill_sync.py 与 check_skill

【免费下载链接】vedic-astro-skills

🔱 Vedic/Jyotish AI analysis toolkit | 吠陀占星AI分析工具包——从排盘开始，到以后的长期追问。支持所有可以挂载Skill的平台。感谢大家的支持。

项目地址：https://gitcode.com/gh_mirrors/ve/vedic-astro-skills

本文介绍吠陀占星AI分析工具包 vedic-astro-skills 的多发行面同步机制：skill_sync.py如何把仓库真源skills/推送到 Claude Code、Codex 两个平台发行面和本机安装目录，check_skill_parity.py又如何用 SHA-256 文件指纹逐文件校验三端一致，让八个vedic-*Skill 在任一平台上都以同一份内容运行。

🎯 为什么同一套 Skill 需要维护三端副本

vedic-astro-skills 是一套从出生信息直接排盘、再进入完整吠陀占星分析的 AI Skill 工具包，包含vedic-calculator、vedic-core、vedic-prashna等八个 Skill。它要同时服务 Claude Code、Codex 以及其它读取 Claude Skill 格式的客户端（如 Antigravity），因此仓库里存在三份"长得几乎一样"的目录：

目录	角色	说明
skills/	真源（canonical）	所有发行面的唯一来源，不含平台专属元数据
claude-code/skills/	Claude Code 发行面	必须与真源逐文件一致
codex/skills/	Codex 发行面	与真源一致，且每个 Skill 额外带一个`agents/openai.yaml`

手工复制的目录结构详见 README.md 的"仓库结构与更新"一节。

只要允许手工维护多份副本，"改了 A 忘了 B"的漂移就迟早发生。vedic-astro-skills 的做法很直白：一个脚本负责推（skill_sync.py），一个脚本负责查（check_skill_parity.py）。

🚚 skill_sync.py：把"仓即源"变成一条单向管道

skill_sync.py 位于仓库根目录，是跨平台的同步器。它的核心设定写在文件头部：

真源只有<repo>/skills/一处（代码中的CANON_DIR），发行面由真源派生，方向永远是"仓 → 外部"；
只同步白名单内的内容：SYNC_ITEMS = ['SKILL.md', 'resources', 'scripts', 'requirements.txt', 'tests']，平台专属的手工层（如 Codex 的agents/openai.yaml）不在其中，不会被覆盖；
不执行任何 git 操作，commit/push 一律手工完成，从机制上杜绝"脚本自动 push 出去"的失控风险。

三个子命令

python skill_sync.py platforms # 仓内 skills/ → claude-code + codex python skill_sync.py install # 仓 → 本机 ~/.claude/skills、~/.gemini/config/skills python skill_sync.py all # 先 platforms 后 install python skill_sync.py all --dry-run # 只报差异，不写文件

三个值得学习的设计细节

1. 指纹比对，零差异零写入。每个文件拷贝前都会比较 SHA-1 摘要（见 skill_sync.py 中的sha()与copy_one()），内容相同就跳过。已同步的端点跑all --dry-run会得到"0 个文件待同步"，磁盘零变动。

2. 孤儿文件"只报不删"。find_orphans()会列出"本机有、仓库没有"的文件并以[ORPHAN]标记，默认不删除；确认无用后加--prune才清理。静默留旧比多打几行提示更危险，这是它注释里明说的取舍。

3. 双仓 shared 一致性预警。开源仓与 Pro 私有仓各自存有一份 shared Skill，check_shared_parity()在 install 前逐文件比对两仓，不一致时打印[WARN]提醒，不让差异静默进入本机。

一个容易踩的坑：SKILLS表最后一行把 Pro 仓里的vedic-core安装成本机vedic-core-pro——手工安装时最容易在这里把 Pro 版覆盖到开源版头上且不报错。用脚本安装可以规避这个歧义。

✅ check_skill_parity.py：一条命令验证三端一致

scripts/check_skill_parity.py 是一个纯只读的校验器，不做任何修改。它按 README.md 的要求在"修改或同步后"运行：

python3 scripts/check_skill_parity.py

校验逻辑分四层

第一层：Skill 集合对齐。扫描真源skills/、claude-code/skills/、codex/skills/三个目录下以vedic-开头的文件夹，三端的 Skill 名单必须完全相同，缺失或多出的都会报错。

第二层：逐文件指纹比对。对每个发行面计算全部文件的SHA-256摘要（跳过.DS_Store、__pycache__、agents/下的平台元数据），与真源比对后分三类报告：

missing files：真源有、发行面没有；
extra files：发行面有、真源没有；
changed files：两边都有但内容不同。

第三层：Codex 专属元数据检查。Codex 发行面要求"每个 Skill 恰好一个agents/openai.yaml"，且该文件必须包含display_name:、short_description:、default_prompt:三个字段，default_prompt里必须真正调用${skill_name}。以 codex/skills/vedic-core/agents/openai.yaml 为例：

interface: display_name: "Vedic Core Analysis" short_description: "Run a Vedic astrology life and planet audit" default_prompt: "Use $vedic-core to perform a complete analysis of my structured chart data."

第四层：反向与遗留检查。真源和 Claude Code 发行面不允许出现agents/元数据；历史上停更的四份遗留文件（.claude/commands/vedic-{core,career,love}.md与根目录旧版scripts/report_builder.py）必须保持已删除状态。

全部通过时的输出非常干净：

[OK] 8 skills match across canonical skills/, Claude Code, and Codex. [OK] Codex has exactly one agents/openai.yaml per skill. [OK] No legacy Claude commands or root report builder remain.

任何一条不满足都会打印[FAIL] ...并以退出码 1 结束，方便接入 CI。

🔁 推荐的日常使用顺序

# 1. 改完 skills/ 下的真源内容后，先预览差异 python skill_sync.py all --dry-run # 2. 确认无误后正式同步 python skill_sync.py all # 3. 最后跑一致性校验，确认三端逐文件一致 python3 scripts/check_skill_parity.py

这套"同步 → 校验"的分工很清晰：skill_sync.py是写的一方，负责把真源铺到各发行面和本机；check_skill_parity.py是读的一方，负责在任何时候回答"现在到底一不一致"。即使同步脚本有遗漏（比如某次新增 Skill 漏掉某个平台），校验器也能在提交前把它拦下来。

💡 机制演进中的两个真实教训

项目 CHANGELOG.md 记录了这套机制修复过的两个典型问题，对做类似多副本管理的同学很有参考价值：

潜伏的排除规则缺陷：早期skill_sync.py把星历文件ephe/、.se1列在排除名单里，导致全新端点首次安装到空目录时会缺失天文数据。因为老端点上都有历史遗留文件，问题一直无症状，直到新端点首次安装才暴露——"排除项"需要随数据需求一起审查；
概念错误引发的位置耦合：真源目录曾叫antigravity/skills/，被当成"某个平台的发行面"塞进PLATFORMS列表，再靠一条continue把自己跳过去。改名压平为skills/后，CANON_DIR与PLATFORMS彻底分离，绕行代码随之删除。