多 Agent 技能同步

本机所有 agent 的用户级 skills 目录，通过 Windows 目录联结（junction）指向同一个仓库。仓库是唯一真相源：改仓库里的文件，所有 agent 立即生效，不需要任何同步命令。

一页式机制总览与各 agent 接入状态在总目录 D:\Projects\agent\skills\README.md（本机文档，不入库）；本文件讲操作细节与设计理由。

架构

D:\Projects\agent\skills\
        ├── hub\       ← 唯一真相源（git 仓库，自建技能）
        └── vendor\    ← 第三方技能（.gitignore 排除，不入库、不 lint）
                │
        ├── ~/.workbuddy/skills/<skill>      ← junction（国内版）
        ├── ~/.workbuddy-ai/skills/<skill>   ← junction（海外版，独立配置目录）
        ├── ~/.claude/skills/<skill>         ← junction
        ├── ~/.codex/skills/<skill>          ← junction
        ├── ~/.zcode/skills/<skill>          ← junction
        ├── ~/.gemini/config/skills/<skill>  ← junction (Gemini CLI)
        └── ~/.gemini/config/skills.json     ← Antigravity 官方原生直挂主库

WorkBuddy 国内版与海外版是两个独立安装，配置目录分别是 ~/.workbuddy 和 ~/.workbuddy-ai（程序在 D:\Software\WorkBuddy 与 D:\Software\New folder\WorkBuddyAI），技能目录互不相通，必须各自纳入 agents 配置。

第三方技能（Kimi/Wind 官方、Academic pack、FBSir 等）同样落在该仓库，但由 .gitignore 的 skillsync 标记区块排除，不入公开仓库、不参与 README 校验。

为什么这样设计（改动前必读）

所有决策都收敛到同一件事：消除副本。技能不能有副本，所以用链接；规则不能有副本，所以用分发；.gitignore 与 README 的一致性靠标记区块，不靠人工核对。

起点不是「同步做得不够好」。复制模式靠「记得同步」维持，而人会忘、脚本会漏——实测 79 份真实副本、29 个技能存了多份，能完全对上的只有 5 个。这是模式问题，不是执行问题。所以选的是共享而非同步器：不是让同步更可靠，而是让「同步」这个动作不存在。

边界：一台机器、用户级技能、你能控制所有 agent 的目录布局。多机、团队、项目级技能都要换方案。

当前状态（2026-11-03）：workbuddy / workbuddy-ai / codex / zcode / dsh 五渠道全 junction（zcode、dsh 均于 2026-11-03 接入，53/53）；claude / gemini / antigravity 已注册但 skills 目录不存在，尚未接入。skillsync.py scan 显示多副本漂移 = 0。junction 拓扑与权属细则见主记忆 skills-junction-architecture。

命令

工具在仓库内 scripts/skillsync.py，配置在 ~/.agents/skillsync.json。

python scripts/skillsync.py status        # 每个 agent 每个技能的状态矩阵
python scripts/skillsync.py scan          # 多份副本的漂移分类报告
python scripts/skillsync.py doctor        # 断链、链式嵌套、主库含链接；豁免项不计入问题数
python scripts/skillsync.py adopt         # 收编散落副本进仓库（默认 dry-run）
python scripts/skillsync.py link          # 把仓库技能分发到各 agent（默认 dry-run；--ensure 顺带建缺失的 agent 目录，需 --apply）
python scripts/skillsync.py gitignore     # 刷新 .gitignore 第三方区块（只减不增）
python scripts/skillsync.py prune         # 清理断链：技能删了、junction 还在（默认 dry-run）

安全约定：adopt / link / prune 默认只预演，加 --apply 才动文件；源目录只移动到 _skillsync_backup/<时间戳>/，绝不删除。

日常流程

改技能：直接编辑仓库里的文件，保存即生效，无需任何命令。

加技能：

不要用内置 skill-creator 的默认路径（~/.codebuddy/skills/）——该目录不在任何 agent 的扫描范围内，建了没人看得见。技能一律建在 <主库>/<skill-name>/，再用 link --apply 分发。

1. 在仓库建 <skill>/SKILL.md（frontmatter 必须有 name 与 description，name 与目录名一致）
2. 进了 README 表格（CI 强制双向校验）
3. python scripts/skillsync.py link --apply 分发到各 agent
4. Antigravity 侧：因 ~/.gemini/config/skills.json 已直挂主库根目录，主库新增技能重载窗口或新开会话即可自动识别；若新增技能未建在主库（放置在外部独立目录），必须同步加到 ~/.gemini/config/skills.json 的 entries 列表中。
5. 提交（.git/hooks/pre-commit 会自动跑一致性与结构闸门，见下节）

删技能：git rm -r <skill> → link --apply + prune --apply → doctor 回到 0。

主库把目录删了，各 agent 目录里那条 junction 就变成空壳——指向不存在的路径， 不报错，但 agent 会看到一个行为不可预期的技能条目。一次删 7 个技能会在 6 个 agent 目录里留下 42 条断链，doctor 只会逐条报，不会告诉你「删干净了没有」。

还要 grep 旧名字：别的技能正文里可能写着「画图 → 某某技能」，删了/改名了就成死指针， 而 lint 的 E6 只查路径、不查技能名，抓不到。删完跑一遍：

grep -rn "<旧技能名>" --include=SKILL.md .

改完再 lint_skills.py。

从某 agent 目录吸收新技能：python scripts/skillsync.py adopt --only <skill> --apply。

提交闸门

约定破了问题会立刻回来，所以把检查挂在提交上，而不是靠事后 scan 发现。scripts/precommit.py 装在 .git/hooks/pre-commit：

• check_consistency.py 失败 → 拒绝（README 与目录必须双向一致）
• lint_skills.py 有 error → 拒绝（frontmatter / description 80–600 字 / 正文引用断链 / BOM）
• 报出新增链式 junction → 拒绝（baseline 的 intentional 是设计上不共享的第三方技能，chained 是待修欠账、目标为空）
• 真实副本数上涨 → 只警告（归集要人工判断，不该堵住提交）

判定原则是只拦新增问题，不为历史欠账买单——否则归集前的 76 份副本和 9 项链式会让任何提交都过不去。

cp scripts/git-hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
python scripts/precommit.py --update-baseline   # 修好欠账后刷新豁免清单（只允许变短）
git commit --no-verify                          # 临时跳过

已知坑位

Antigravity Windows 扫描机制：Antigravity 底层在 Windows 下通过标准 io/fs 扫描，会跳过 ~/.gemini/config/skills/ 内部的二级 Junction 目录。因此 Antigravity 统一采用原生声明式配置 ~/.gemini/config/skills.json 直接挂载主库真实路径，绕过子目录 Junction 限制。

WorkBuddy 的指令通道不是 AGENTS.md：它读的是记忆文件——国内版 ~/.workbuddy/MEMORY.md、 海外版 ~/.workbuddy-ai/user-<id>/MEMORY.md，由 rules --apply 写入同一个规则区块。

dsh 的两条通道：技能读 ~/.dsh/skills（rank 400，junction 热生效，新增技能下一轮对话即可见）；规则读 ~/.dsh/AGENTS.md。不要同时写 ~/.agents/AGENTS.md——dsh 的全局指令链是 ~/.dsh/AGENTS.md → ~/.agents/AGENTS.md → 项目链，两处都写等于区块重复注入。

.gitignore 区块只减不增：早期按「目录存在但 git 未跟踪」自动判定第三方技能，结果把 自己新建的技能也一起扫了进去——从此进不了 git，而且没有任何提示（实测 31 个被排除的目录里 混着 8 个自建技能）。现在只保留已有条目、已跟踪的自动移出，新出现的一律不加，要排除得显式 gitignore --add <name>。判定第三方不能只看「未跟踪」，那和「刚建的」无法区分。

断链判定不能用 exists()：断链本身 exists() 就是 False，分不清「没有这个链接」和 「链接坏了」。要用 is_link() + link_target() + 目标存在性判断，删除用 os.rmdir() （只摘重解析点，不递归、不碰目标）。

链式链接：junction 指向另一个 agent 的目录（如 workbuddy→zcode→codex）会造成三层套娃，中间一层挪动全断。所有链接必须直接指向仓库。doctor 会把这类问题列出，但 baseline 里 intentional 的会标成「已豁免」且不计入问题数——它和提交闸门读同一份基线，两边不会给出相反结论。

冲突保护：若某 agent 目录的真实副本与仓库正文（SKILL.md 去掉 frontmatter 后）不同，link 会自动隔离该技能，既不分发也不回链——因为分发会把仓库版本塞给别的 agent，回链会丢掉 agent 侧的改动。这类必须人工定夺。

归集已有的真实副本（link 会跳过它们，得手工做）：先比对 mtime——副本早于主库 = 主库更新，可安全替换；再把副本移进 _skillsync_backup/<时间戳>/<agent>/，原位 mklink /J 指向主库。判断 junction 是否合规不能用 realpath：它会把整条链解析到底，workbuddy → zcode → 主库 这种两跳看起来和直连一样。要比对 os.readlink() 拿到的直接目标。

漂移多是渠道差异，不是内容冲突：zcode 的 skillhub 会往 frontmatter 注入 display_name/visibility/metadata，Claude 侧多 locales/zh-CN.json，还有完整仓库 vs 精简发布版之差（fixtures/tests/__pycache__）。scan 按「正文是否相同」分类，正文相同即可安全合并。

旧脚本已废弃：scripts/sync_zcode_skills.py 是单向复制（先 rmtree 仓库目录再 copytree），在 junction 布局下方向相反会覆盖仓库，已内置拒绝执行的硬保护。

跨盘 junction：仓库在 D 盘、agent 目录在 C 盘，属正常用法，已实测可读。D 盘不可用时 agent 会扫不到技能。

link 静默跳过目录不存在的 agent：在 skillsync.json 里注册了 agent ≠ 已接入——skills 目录 不存在时 link 不报错、不建目录，直接跳过，只有 status 末尾一行「未安装」能看出来 （zcode 就这样漏接过）。新增 agent 三步：登记 agents → mkdir <skills 目录> → link --apply；或一步 link --ensure --apply。验证接入与否看 status 矩阵里有没有该列， 别看 link 的退出码。