用途
wiki-sync 用于安全地同步 vault 的 git 仓库，适合以下场景：
- 用户想把本地 vault 变更推送到远端。
- 用户想把远端变更拉取到本地 vault。
- 用户询问 vault 同步状态、git 状态或多设备协同。
- 多个 Claude Code 会话同时指向同一个 vault。
- 在编辑会话前后进行定期维护。
其核心目标是：通过建议锁（advisory lockfile）实现多会话安全，并系统化处理由 archive-commit × snapshot-stream 模式引发的 rebase 冲突风暴。
主要能力
- 多会话安全预检：在任何 git stash 或 pull/push 前，运行
skillwiki sync peers <vault>检测其他持有活跃锁或近期wiki-sync:*stash 的会话。若存在非自身的 peer（被锁定或有 5 分钟内的 stash），则向用户展示其 session_id、PID 和摘要，并要求等待或用--force继续。 - 建议锁：通过
skillwiki sync lock <vault> --summary "wiki-sync <op>"获取锁（op 为 pull 或 push）。若锁被占用（退出码 48），展示持有者并中止。退出时（无论成功或错误）需配对执行skillwiki sync unlock <vault>。 - stash 积压警告：每次调用时通过
skillwiki sync peers统计超过 24 小时的wiki-sync:*stash，若存在则警告用户先行审计清理，但不会自动 drop。 - 同步流程：运行
skillwiki sync status <vault>读取 JSON。退出码 0 表示干净（无需同步）；退出码 22 表示存在警告（dirty/ahead/behind，需要处理）。随后展示 status、dirty、ahead、behind、last_commit，并询问用户选择 push、pull 或两者。 - 推送流程：若 vault 为 dirty，先请用户检查未提交变更；运行
skillwiki sync lint-delta <vault> --base-ref origin/main，仅当 new_errors > 0 时阻止；lint 允许后执行git -C <vault> add -A、commit -m "sync: vault update $(date -u +%Y-%m-%dT%H:%MZ)"、git -C <vault> push origin HEAD。最后追加一条 log.md 记录（推送文件、lint 结果、commit hash）。 - 拉取流程：运行
skillwiki sync status <vault> --include-stashes检查未跟踪文件碰撞；若 dirty 则按命名规范先 stash；优先使用规范的 pull 辅助脚本（wiki-pull-with-auto-resolve.sh/vault-presync --execute）；若直接调用 git：git -C <vault> pull --rebase origin HEAD；随后 pop stash；若有冲突则交由用户解决；拉取后运行skillwiki lint <vault>校验完整性，并追加 log.md 记录。 - pull-then-push 流程：先执行拉取流程，再执行推送流程。
使用方式（关键机制）
- stash 命名规范：
wiki-sync:{session_id}:{cwd_hash}:{iso8601_timestamp}:{summary}。session_id 优先取$CLAUDE_SESSION_ID，否则用 shell PID，否则 unknown；cwd_hash 为 sha256(vault 路径) 前 8 位；ISO 时间戳为 UTC（如 2026-05-23T03:25:00Z）；summary 为 pre-pull、pre-push 等短标签。用于任意会话通过git stash list识别来源。 - 未跟踪文件指纹（拉取前）：对
git ls-files --others --exclude-standard列出的文件，若其在 origin/main 上存在且字节相同，可安全删除（presync 产物）；若内容不同，则向用户报告碰撞并请其手动解决，绝不静默--include-untracked；远端不存在的文件则不动。 - 冲突解决：frontmatter 的
updated:字段始终保留较新的时间戳，其他字段交由用户选择；正文冲突不自动解决，用单独一行???分隔两个版本；modify/delete 冲突时先查删除该文件的提交并判断删除是否有意，再决定git rm或git add，然后rebase --continue；解决后运行skillwiki lint <vault>再提交。 - rebase 冲突风暴处理：当连续 3 个及以上提交消息匹配
^archive: moved时判定为风暴。对每个 archive 提交，对所有冲突文件应用--ours（保留 HEAD）后add并rebase --continue；风暴过后 pop stash 并按常规冲突处理。预防手段包括更频繁同步（本地不要落后 origin/main 超 5 个提交）、用skillwiki archive --batch将 5-10 个 transcript 归档合并为一个提交、对带 snapshot cron 的 vault 使用更小更频繁的同步。 - 多设备协同：建议每台设备在每次编辑会话前 pull、编辑会话后 push；若两台设备在两次同步间编辑同一页面，冲突不可避免；建议在 Obsidian 启用 obsidian-git 插件的自动提交以减少 dirty 漂移。
适用场景
适用于以 git 作为版本控制、需要多会话或多设备协同编辑的 vault 知识库（如 SkillWiki 类）。文档还描述了 rclone 挂载 + git 快照的 cron 模式：~/wiki 为 rclone 挂载的实时 vault，~/wiki-git 为从 GitHub 克隆的快照目标，cron 每小时 rsync 后 commit 并 push，并提供了 wiki-snapshot.sh 实现示例。该模式下强调单一写入者（single-writer-git）模型，避免用 GitHub 网页或未协调的克隆直接编辑。
停止条件与禁止项
停止条件：状态为 not_a_repo（非 git 仓库）、推送前存在 lint 错误、网络错误、持有 peer 锁或存在 peer stash、检测到未跟踪文件碰撞。禁止项：有 lint 错误时推送、未经用户审查自动解决正文冲突、强制推送（git push --force）、为解冲突修改 raw/ 下文件（应归档并重新摄取）、不用规定命名格式的 stash、强制删除 peer 锁文件（仅在确认 peer 已死时用 --force）。
限制
关于收费、价格、支持平台与具体效果，资料暂未提供。