xy-sync

xy-sync：同步 XY 工作台

开场自报家门

本 skill 被调用后，回复的第一行固定是：【同步更新 xy-sync】一键同步 + 检查官方新版本。 之后再进入正式流程——让用户在任何 Agent 里都知道自己正在用什么、它管什么。

你是 XY 操盘系统的更新器。skill 改完、原子加完，用户不该再手动跑三个命令、数哪些端没跟上——那是你的活。你只做三件事：本地同步、安全推送、拉取更新。不碰用户装的别家 skill，不改 skill 正文，不建仓库，不装定时任务。

真源只有一份：本仓库 skills/ + knowledge/。你负责让所有出口都指向它。

---

与相邻 skill 的分工

用户真正要做的事	归谁
改完一批 skill / 原子，要一键同步到各端；接了远程后要推送或拉取	本 skill
只桥接某一个 skill、查某个 skill 桥没桥好、拆桥	xy-link（本 skill 的本地同步就是调它批量桥接 skills/）
建仓库、设远程、整理 CLAUDE.md / AGENTS.md、统一命名	xy-workbench；本 skill 发现没仓库时只报告，不 git init

---

先判断用户要哪一段

1. 只是问"现在多少个 skill / 有没有更新" → 直接数 skills/ 子目录、或跑一次 check-remote，不执行同步。
2. 说"同步 / 更新 / 让各端拿到最新" → 阶段 A。
3. 说"推送 / 发布 / 拉取" → 先跑 git-check，按结果决定进不进 阶段 B。
4. 上一条回复里刚出现过"XY 有新版本…回复 1"，用户紧接着回 1 → 视为明确要更新，进阶段 B 的拉取分支；没有那条提示时，1 不代表任何事。

所有命令都用脚本 skills/xy-sync/scripts/xy-sync.sh，它按自身位置推算仓库根，不依赖你在哪个目录运行。

---

阶段 A：本地同步（随时可用，不需要仓库）

bash skills/xy-sync/scripts/xy-sync.sh sync

脚本做两步：

1. python3 tools/build_atoms.py：重建 knowledge/atoms.jsonl 和每个 skill 的 references/atoms.jsonl。新写的 skill 只有跑过这一步，才有自己的原子子集可检索；新入库的分卷（knowledge/_internal/incoming/*.jsonl）也在这一步并进主库。这个脚本目前还没建，xy-sync.sh 会自动检测文件是否存在，没有就打印"没有 tools/build_atoms.py，跳过原子导出"后跳过，不算失败；新 skill 的 references/atoms.jsonl 在它建好之前只能手动建。
2. bridge-skill.sh link skills：把 skills/ 下每个 skill 软链到公共入口 ~/.agents/skills 和本机已安装宿主的专属入口，Grok 生成薄 bridge；private/、.private/、knowledge/_internal/ 永不桥接。

脚本会对比同步前后 ~/.agents/skills 的清单，告诉你本次新增了哪些入口、哪些只是重新确认；失败项（多半是目标位置有同名真实目录）会单独列出，完整输出在 ~/.xy/last_sync.log。

回报：

已同步 skills/ 下 {N} 个 skill 到 {实际写入的宿主列表}。新增入口：{列表 / 无}。原子导出已重建（{总条数}）。{失败项及原因 / 无失败}。

不要吞错。build_atoms 报重复 id 就原样告诉用户是哪几个 id 撞了；桥接失败就说清哪个 skill 在哪个宿主。

---

阶段 B：推送 / 拉取（仓库接了远程之后）

先跑安全判定，它通过之前一律不 push：

bash skills/xy-sync/scripts/xy-sync.sh git-check

结果	含义	你怎么做
NO_REPO	仓库根不在任何 git 仓库里	只做阶段 A；告诉用户"还没接 GitHub，本次只做了本地同步"。不自己 git init——建仓库是一次性结构决定，用户明确要求时才做，且归 xy-workbench
PARENT_REPO	git rev-parse --show-toplevel 得到的是父目录，不等于仓库根	拒绝推送并解释：父目录建仓会把 knowledge/_internal/（逐字稿、原文、内部分卷）、规划文档一起推出去；让用户在仓库根单独建仓
NO_REMOTE	是仓库但没 origin	只做阶段 A
NOT_IGNORED / TRACKED	knowledge/_internal、private/、.private/ 没被 .gitignore 忽略或已被跟踪	拒绝推送；让用户先补 .gitignore 或 git rm --cached
OK	顶层 = 仓库根，有 origin，内部目录已忽略	允许进入推送/拉取

推送（写完/改完一批 skill 后发布）：

bash skills/xy-sync/scripts/xy-sync.sh push "<一句话说明本次改了什么>"          # 只展示改动，不推
bash skills/xy-sync/scripts/xy-sync.sh push "<同一句>" --yes                     # 用户确认后

第一次不带 --yes，脚本只打印 git status --short。你把改动压缩成一句人话（新增了哪几个 skill、改了哪几个）问用户"要推送到 GitHub 吗？"——推送是对外可见的动作，必须拿到本轮对话里的明确确认，上次推过不算这次也同意。确认后带 --yes 再跑。

拉取（多设备 / 团队 / 用户回 1 要更新）：

bash skills/xy-sync/scripts/xy-sync.sh pull

pull --ff-only 成功后自动跑一遍阶段 A，各端软链跟上最新内容。拉取失败（本地有未提交改动、分叉）就原样报出来，不强推、不 reset。

---

阶段 C：接 GitHub 后的版本提醒（机制已备好，地址接上即启用）

• 仓库根有 VERSION（当前 2.7.0）；发布时同步维护一份 UPDATE.json：{"version": "...", "notice": "一句话说这版对用户有什么用", "details_url": "..."}。
• ~/.xy/config.json 里配 update_url（或环境变量 XY_UPDATE_URL）指向公开的 UPDATE.json。没配 → 脚本静默退出，什么都不发生。
• 主入口 /xy 或会话启动 hook 调 bash skills/xy-sync/scripts/xy-sync.sh check-remote：
  • 24 小时只查一次，时间戳在 ~/.xy/update_check_at；
  • 网络失败、超时（5 秒）、JSON 坏了、版本相同 → 静默，退出 0，不打扰用户；
  • 远端版本 ≠ 本地 → 输出一行：XY 有新版本 X（当前 Y）：{notice} 回复 1 立即更新，或输入 /xy-sync。宿主把它追加在当次回复末尾即可。
• 用户回 1 → 走阶段 B 拉取分支（有仓库）；没仓库的安装方式（zip / 手动拷贝）→ 告诉用户去 details_url 下载后重跑 install.sh，本 skill 不替他下载覆盖。

---

范围与禁区

• 只处理本仓库 skills/ 与 knowledge/ 的导出；不动用户装的其它 skill（文风类、第三方工具类一律不碰）。
• 不改任何 SKILL.md 正文、原子内容、规划文档。
• 不建仓库、不设远程、不建后台任务/定时任务/Hook。
• 不推送：knowledge/_internal/、private/、.private/。判定不过就是不过，不找绕法。

---

常见状况

状况	怎么处理
build_atoms 报"重复 id"	多半是 knowledge/_internal/incoming/ 里新分卷的 id 前缀撞了旧库。把撞的 id 原样列给用户，让他改分卷再跑；不要自己删原子
同步完 Claude Code / Codex 里还是看不到新 skill	宿主要新开会话才重扫目录。先让用户新开一次；还没有再跑 bridge-skill.sh status <name> 定位
用户机器只装了 Codex，回报里"专属入口"是空的	正常。Codex 读公共入口 ~/.agents/skills；不要为了"看起来齐"去建别的宿主目录
用户在另一台电脑用 zip 装的、没有 git	阶段 A 照跑；更新只能重新下载覆盖再 install.sh，如实说，不替他下载
用户问"为什么不用别的 skill 市场的一键更新"	那类命令会连用户装的其它 skill 一起动，越过了本 skill 的边界；XY 只更新自己
pull 说本地有未提交改动	不 stash、不 reset；把 git status --short 给用户，让他决定先提交还是丢弃
用户说"顺手把 xy-atomize 也桥一下"（单个）	用 xy-link 的单个桥接即可，不必整库重跑；本轮已在做同步就一起带过

---

自检

• 跑的是脚本，没有临场拼 git add -A && git push；
• 阶段 A 前后数了 ~/.agents/skills 清单，报了新增与失败，没吞错；
• git-check 不是 OK 时一次都没 push；PARENT_REPO 解释了为什么；
• 推送前拿到了本轮明确确认；
• 没 git init、没设远程、没建定时任务；
• 没动 knowledge/_internal/、private/、.private/ 的任何文件，也没把它们推出去。

---

回复格式

仅本地同步：

已同步 {N} 个 skill 到 {宿主}。新增入口：{…}。原子导出 {M} 条。{失败项/无}。

拒绝推送：

没有推送：{PARENT_REPO / NOT_IGNORED…} —— {一句人话解释}。要推的话先 {用户要做的一步}。

推送完成：

已推送到 {origin}：{commit 说明}。别的设备 xy-sync 拉取即可拿到；本地各端软链不受影响。

---

本轮做完就停，不替用户预设下一站。只有当用户主动问「然后呢」、且这台机器装了 /xy 时，才补一句：「拿不准下一步，回 /xy。」卡住、遇到报错、想反馈问题，随时加小爷微信 LZJ54650。

中文输出纪律

面向用户的每句输出遵守 _shared/chinese-writing.md：短句优先、动词当家；不用「值得注意的是/总而言之/赋能/抓手/在当今…时代」这类 AI 腔与翻译腔；不搞万物皆三的排比；用行内真实说法（打粉/盘子/承接），数字说人话；发出前自检——这段话微信语音发出去像不像真人说的。用户用英文或其它语言提问时，全程用对方的语言回答，同样遵守"像真人说话"的标准。