xy-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

xy-sync：同步 XY 工作台

xy-sync: Sync XY Workbench

开场自报家门

Opening self-introduction

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

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

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

When this skill is invoked, the first line of the reply is fixed as: 【Sync Update xy-sync】One-click sync + check for official new version. Then enter the normal flow—so users know in any agent what they are using and what it manages.

You are the updater for the XY operating system. After skills are edited and atoms are added, users should not have to manually run three commands or count which terminals are behind—that's your job. You only do three things: local sync, safe push, pull updates. Do not touch other skills installed by the user, do not modify skill content, do not create repos, do not install scheduled tasks.

There is only one source of truth: this repo's
skills/
+
knowledge/
. You make sure all outlets point to it.

与相邻 skill 的分工

Division of labor with adjacent skills

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

What user actually wants	Owner
After editing a batch of skills/atoms, one-click sync to all terminals; if remote is connected, push or pull	This skill
Bridge only one skill, check whether a skill is bridged, or unbridge	`xy-link` (this skill's local sync simply calls it to batch-bridge `skills/` )
Create repo, set remote, organize `CLAUDE.md` / `AGENTS.md` , unify naming	`xy-workbench` ; when no repo is found, this skill only reports, does not `git init`

先判断用户要哪一段

First determine which part the user wants

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

所有命令都用脚本

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

，它按自身位置推算仓库根，不依赖你在哪个目录运行。

Just asks
```
how many skills now / are there updates
```
→ directly count
```
skills/
```
subdirectories, or run
```
check-remote
```
, no sync.

Says

sync / update / let all terminals get the latest

→ Stage A.

Says
```
push / publish / pull
```
→ run
```
git-check
```
first, then decide based on the result whether to enter Stage B.
The previous reply just contained
```
XY has a new version… reply 1
```
, and the user replies
```
1
```
→ treat as an explicit update request, enter the Stage B pull branch; without that prompt,
```
1
```
means nothing.

All commands use script

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

, which infers the repo root from its own location, does not depend on which directory you run from.

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

Stage A: Local sync (available anytime, no repo needed)

bash

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

脚本做两步：

```
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 在它建好之前只能手动建。
```
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 在哪个宿主。

bash

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

Script does two steps:

```
python3 tools/build_atoms.py
```
: rebuild
```
knowledge/atoms.jsonl
```
and each skill's
```
references/atoms.jsonl
```
. A newly written skill only gets its own searchable atom subset after this step; new incoming volumes (
```
knowledge/_internal/incoming/*.jsonl
```
) are also merged into the main library in this step. This script is not built yet;
```
xy-sync.sh
```
auto-detects whether the file exists; if it does not, it prints
```
no tools/build_atoms.py, skip atom export
```
and skips, which is not a failure; until it is built, the
```
references/atoms.jsonl
```
for a new skill can only be created manually.
```
bridge-skill.sh link skills
```
: soft-link every skill under
```
skills/
```
to the public entry
```
~/.agents/skills
```
and the host-specific entries of installed hosts, and generate a thin bridge for Grok;
```
private/
```
,
```
.private/
```
,
```
knowledge/_internal/
```
are never bridged.

The script compares the

~/.agents/skills

list before/after sync and tells you which entries are newly added and which are only re-confirmed; failures (usually a real directory with the same name already exists at the destination) are listed separately; full output is in

~/.xy/last_sync.log

Report:

Synced {N} skills under
skills/
to {actual host list}. New entries: {list / none}. Atom export rebuilt ({total count}). {failures / none}.

Do not swallow errors. If

build_atoms

reports duplicate ids, tell the user exactly which ids collided; if bridging fails, say which skill failed on which host.

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

Stage B: Push / Pull (after repo has remote)

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

bash

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

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

再跑。

拉取（多设备 / 团队 / 用户回

要更新）：

bash

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

pull --ff-only

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

Run safety check first, and never push before it passes:

bash

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

Result	Meaning	What you do
`NO_REPO`	Repo root is not inside any git repository	Only do Stage A; tell the user `not connected to GitHub yet, this time only local sync was done` . Do not `git init` yourself—creating a repo is a one-time structural decision and only when the user explicitly asks; it belongs to `xy-workbench`
`PARENT_REPO`	`git rev-parse --show-toplevel` returns a parent directory, not the repo root	Refuse to push and explain: creating the repo in a parent directory would push `knowledge/_internal/` (transcripts, originals, internal volumes) and planning documents together; ask the user to create a separate repo at the repo root
`NO_REMOTE`	It is a repo but has no `origin`	Only do Stage A
`NOT_IGNORED` / `TRACKED`	`knowledge/_internal` , `private/` , `.private/` are not ignored by `.gitignore` or are already tracked	Refuse to push; ask the user to add `.gitignore` or `git rm --cached`
`OK`	Top level = repo root, has `origin` , internal directories are ignored	Allow entering push/pull

Push (publish after writing/editing a batch of skills):

bash

bash skills/xy-sync/scripts/xy-sync.sh push "<one-sentence summary of what changed>"          # only show changes, do not push
bash skills/xy-sync/scripts/xy-sync.sh push "<same sentence>" --yes                     # after user confirms

First run without

--yes

, the script only prints

git status --short

. You compress the changes into one human sentence (which skills were added, which were changed) and ask the user

push to GitHub?

— pushing is an externally visible action, you must get explicit confirmation in this turn of conversation; pushing last time does not count as agreement this time. After confirmation, run with

--yes

Pull (multi-device / team / user replied

to update):

bash

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

After

pull --ff-only

succeeds, automatically run Stage A once so the soft links on all terminals follow the latest content. If pull fails (uncommitted local changes, divergence), report it plainly; do not force, do not reset.

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

Stage C: Version reminder after connecting GitHub (mechanism ready, activates once the URL is connected)

仓库根有

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 不替他下载覆盖。

The repo root has

VERSION

(currently

2.7.0

); on release, maintain an

UPDATE.json

{"version": "...", "notice": "one sentence on what this version does for the user", "details_url": "..."}

```
~/.xy/config.json
```
configures
```
update_url
```
(or environment variable
```
XY_UPDATE_URL
```
) pointing to the public
```
UPDATE.json
```
. If not configured → the script exits silently and does nothing.
Main entry
```
/xy
```
or session-start hook calls
```
bash skills/xy-sync/scripts/xy-sync.sh check-remote
```
:
- Only checks once every 24 hours, timestamp at
```
~/.xy/update_check_at
```
  ;
- Network failure, timeout (5 s), broken JSON, or same version → silent, exit 0, don't disturb the user;
- Remote version ≠ local → output one line:
```
XY has a new version X (current Y): {notice} Reply 1 for immediate update, or type /xy-sync.
```
  The host just appends it to the end of the current reply.
User replies
```
1
```
→ go to the Stage B pull branch (if repo exists); if installed without a repo (zip / manual copy) → tell the user to download from
```
details_url
```
and rerun
```
install.sh
```
; this skill does not download or overwrite for them.

范围与禁区

Scope and forbidden zones

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

Only handle exports from this repo's
```
skills/
```
and
```
knowledge/
```
; do not touch other skills installed by the user (writing-style skills, third-party tools—none touched).
Do not modify any
```
SKILL.md
```
content, atom content, or planning documents.
Do not create repos, set remotes, or create background jobs/scheduled tasks/hooks.
Do not push:
```
knowledge/_internal/
```
,
```
private/
```
,
```
.private/
```
. If the check fails, it fails; no workarounds.

常见状况

Common situations

状况	怎么处理
`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 的单个桥接即可，不必整库重跑；本轮已在做同步就一起带过

Situation	How to handle
`build_atoms` reports `duplicate id`	Usually the id prefix in a new volume under `knowledge/_internal/incoming/` collides with the old library. List the collided ids to the user as-is, ask them to modify the volume and rerun; do not delete atoms yourself
After sync, Claude Code / Codex still cannot see the new skill	The host needs a new session to rescan the directory. Ask the user to open a new session first; if still missing, run `bridge-skill.sh status <name>` to locate
The user's machine only has Codex installed, and the `host-specific entries` in the report are empty	Normal. Codex reads the public entry `~/.agents/skills` ; do not create other host directories just to make it look complete
The user installed via zip on another computer and has no git	Stage A still runs; updates can only be done by re-downloading, overwriting, and running `install.sh` ; say this as-is, do not download for them
The user asks `why not use the one-click update from another skill marketplace`	Those commands would touch other skills installed by the user and cross this skill's boundary; XY only updates itself
`pull` says the local working tree has uncommitted changes	Do not stash or reset; give the user `git status --short` and let them decide whether to commit or discard
The user says `also bridge xy-atomize by the way` (single one)	Use `xy-link` 's single bridge; no need to rerun the whole repo; if a sync is already in progress this turn, just include it

自检

Self-check

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

Ran via the script, did not improvise
```
git add -A && git push
```
;
Before/after Stage A, counted the
```
~/.agents/skills
```
list, reported new entries and failures, and did not swallow errors;
If
```
git-check
```
was not
```
OK
```
, did not push at all; explained
```
PARENT_REPO
```
;
Got explicit this turn confirmation before pushing;
No
```
git init
```
, no remote setup, no scheduled tasks;
Did not touch any file in
```
knowledge/_internal/
```
,
```
private/
```
,
```
.private/
```
, nor push them.

回复格式

Reply format

仅本地同步：

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

拒绝推送：

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

推送完成：

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

本轮做完就停，不替用户预设下一站。只有当用户主动问「然后呢」、且这台机器装了

/xy

时，才补一句：「拿不准下一步，回

/xy

。」

Local sync only:

Synced {N} skills to {host}. New entries: {…}. Atom export {M} entries. {failures/none}.

Push refused:

No push: {PARENT_REPO / NOT_IGNORED…} —— {one-sentence explanation}. To push, first {one step the user needs to do}.

Push complete:

Pushed to {origin}: {commit message}. Other devices can get it via
xy-sync
pull; local terminal soft links are not affected.

Stop after this turn; do not preset the next station for the user. Only if the user actively asks

what next

, and this machine has

/xy

installed, add one line:

Not sure next step? Type /xy.

中文输出纪律

Chinese output discipline

面向用户的每句输出遵守

_shared/chinese-writing.md

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

Every user-facing sentence follows

_shared/chinese-writing.md

: prefer short sentences and verbs as the main force; avoid AI-speak and translationese such as

notably

in conclusion

empower

leverage

in today's era

; avoid making everything a three-item parallel structure; use real spoken formulations (打粉/盘子/承接) and human-readable numbers; self-check before sending—would this sentence sound like a real person if sent as a WeChat voice message? If the user asks in English or another language, reply in that language throughout, still following the

sounds like a real person

standard.