skeeper

Skeeper 参考指南

skeeper CLI 的完整参考：这是一个 Go 二进制程序，可将规范制品镜像到带有受跟踪锁文件的边车 Git 仓库中，使主仓库的 PR 差异专注于代码，并让每次提交都能证明随其发布的规范状态。

什么是 Skeeper

• 由锁文件保障可靠性。 skeeper.lock 会提交到主仓库中，将主仓库的每次提交固定到各命名空间对应的确切边车提交，并记录内容摘要、文件数和字节数。
• 严格的托管钩子。 pre-commit 和 pre-merge-commit 会镜像已暂存的内容、推送边车、写入 skeeper.lock，并在 Git 创建主提交前将其暂存。pre-push 会在推送主仓库前检查锁文件。
• 共享边车中的命名空间。 多个项目可以共享一个边车 Git 远程而不会发生冲突，因为每个项目都拥有一个命名空间前缀，并使用分支感知引用，格式为 <namespace>/__branches__/<source-branch>。
• 类似 Git 的收敛行为。 pull 会拉取远程文档，push 会发布本地文档但不会清理仅存在于远程的文件，sync 会先执行 pull 再执行 push。
• 默认安全。 本地文件缺失不会导致删除仅存在于远程边车的文档，除非用户明确传入破坏性选项 --prune。
• 单一恢复入口。 status --check 会报告不健康状态，而 repair 负责安全的自动修复和恢复报告。
• 单二进制、本地优先。 Skeeper 会调用 git（仅当 skeeper init 创建全新的边车仓库时才会调用 gh）。每项操作都可以通过 Git 进行调试。

心智模型：四项不变量

1. skeeper.lock 是固定状态。 它记录边车 URL、源分支、命名空间分支、边车提交 SHA、内容摘要、文件数和字节数。切勿手动编辑 SHA。
2. 同步发生在主提交之前，而不是之后。 同步失败会导致提交失败。没有异步重试队列。
3. 除非选择退出，否则失败时会安全关闭。 SKEEPER_SKIP=1 允许单次绕过，并将其记录到 .git/skeeper/bypass.json，且会在 status、repair 和 pre-push 中显示，直到通过 skeeper sync 或 skeeper repair 清除。由于 Git 会跳过所有钩子代码，因此不支持 git commit --no-verify。
4. pre-push 会在远程看到提交前进行检查。 被绕过或过期的锁会阻止推送。

flowchart LR
    A[git commit] --> B[existing user hook content]
    B --> C[skeeper internal pre-commit]
    C --> D[collect owned staged specs]
    D --> E[fetch and rebase sidecar branch]
    E --> F[mirror namespace files into .skeeper/]
    F --> G[commit and push sidecar]
    G --> H[write and stage skeeper.lock]
    H --> I[main commit proceeds]
    I --> J[git push]
    J --> K[skeeper internal pre-push]

快速开始

# Inside any Git repository
skeeper init
$EDITOR src/auth/SPEC.md
git add src/auth/service.go src/auth/SPEC.md
git commit -m "auth: design OAuth provider flow"
# the hook syncs the sidecar and stages skeeper.lock; commit it normally
git push

如果工作树中已经包含应由边车管理的规范，请在设置期间传入 --track，或在 init 后运行 skeeper track <glob> --sync。

命令一览

命令	用途	只读？
skeeper init	以交互方式初始化 .skeeper.yml、sidecar 仓库、钩子和受管的 .gitignore	否
skeeper status	显示同步健康状况、按需显示路径偏移、钩子健康状况、绕过状态和后续操作	是
skeeper status --check	适用于 CI 的健康检查；需要采取操作时以非零状态码退出	是
skeeper pull	获取 sidecar 引用并生成远程文档，同时保留本地文档	否
skeeper push	将本地规范发布到 sidecar，并暂存 skeeper.lock	否
skeeper sync	拉取远程规范、推送本地规范，并暂存 skeeper.lock	否
skeeper restore <path...>	从 skeeper.lock 中记录的 sidecar 提交恢复选定文件	否
skeeper restore --all	将所有已锁定的受管文件恢复到全新克隆或检出中	否
skeeper track <glob>	将受管 glob 添加到 .skeeper.yml 和 .gitignore；可选择同步已有匹配项	否
skeeper untrack <path-or-glob>...	在 sidecar 同步后，停止跟踪主仓库中的规范	否
skeeper repair	诊断并安全修复本地 Skeeper 状态	否
skeeper repair --check	只读修复诊断	是
skeeper log <path>	显示单个规范文件的 sidecar 历史记录	是
skeeper version	输出构建元数据	是

CLI 参考中列出的命令支持 --json，可生成确定性的机器可读输出。支持预览计划的变更命令可使用 --dry-run。--force 可覆盖 settings.guardrails 中声明的宽泛计划防护措施。

隐藏的 skeeper internal ... 命令用于 Git 钩子和合并驱动程序的底层机制。除非是在测试 Skeeper 本身，否则不要向用户推荐这些命令，也不要手动调用。

时效性约定

请将此目录视为随仓库发布的官方 Skeeper 技能。CLI 接口发生变化时，请在同一项更改中更新此文件和 references/cli-reference.md。请根据 skeeper --help 和每个公开子命令的 --help 进行核对；不要根据旧文档、旧日志或实现辅助工具推断命令。

hydrate、update、diff、reconcile、resolve、rescue、verify、fsck、hooks、merge-driver、adopt 和 pattern 等历史命令不属于公开工作流指南。如果用户提到这些命令，请将其意图转换为当前公开命令模型：status、pull、push、sync、restore、track、untrack 或 repair。

如需查看各标志的完整详情，请阅读 references/cli-reference.md。

配置速查表

.skeeper.yml 位于仓库根目录，并提交到仓库。最小必需结构：

sidecar: [email protected]:user/myproject-specs.git

namespaces:
  - name: project
    patterns:
      - "**/SPEC.md"
      - "docs/specs/**"
      - ".claude/plans/**"
      - "**/*.spec.md"
    exclude:
      - "docs/specs/private/**"

可选的运行默认值：

settings:
  guardrails:
    max_files: 100 # default 100
    max_bytes: 10485760 # default 10 MiB
  hooks:
    pre_push_timeout: 30s # default 30s
    allow_skip_env: SKEEPER_SKIP # default SKEEPER_SKIP

需要了解的四条规则：

1. 拒绝未知键。 解码采用严格模式。
2. exclude 是唯一公开的排除机制。 patterns 中不允许使用否定 glob（!docs/private/**）。
3. 归属关系必须唯一。 如果两个命名空间匹配同一个文件，计划会失败，并要求添加 exclude。
4. __branches__ 为保留字段。 它是用于分隔命名空间与分支感知引用的片段。

如需查看包含所有字段和默认值的完整架构，请阅读 references/config-reference.md。

常见工作流

初始化新仓库

skeeper init \
  --sidecar-name myproject-specs \
  --visibility private \
  --namespace project \
  --track "**/SPEC.md" \
  --track "docs/specs/**"
git add .skeeper.yml .gitignore
git commit -m "chore: bootstrap skeeper"

加入已有旁置仓库的仓库

skeeper init --sidecar [email protected]:user/shared-specs.git \
  --namespace project \
  --track "**/SPEC.md"
skeeper restore --all
skeeper repair

init 会安装或刷新钩子和合并驱动配置。restore --all 会还原当前 skeeper.lock 固定的文件；克隆设置完成后，可以安全地运行 repair，它会在需要时刷新本地钩子状态。

跟踪工作树中已有的文件

skeeper track "docs/adrs/**" --sync
git add .skeeper.yml .gitignore skeeper.lock
git commit -m "chore: track ADRs in skeeper"

如果你只想更新覆盖范围，并计划在之后的 skeeper sync 中发布对应文件，请在运行 track 时不要使用 --sync。

合并两个克隆中的文档

# clone A
skeeper sync
git commit -m "skeeper: sync docs"
git push

# clone B
git pull
skeeper sync
git commit -m "skeeper: sync docs"
git push

默认情况下，sync 会保留两边的内容。它会获取旁置仓库状态，将仅存在于远程的文档还原到本地，发布仅存在于本地的文档，并更新 skeeper.lock。

推送失败或绕过流程后恢复

skeeper status --paths
skeeper repair --check
# fix network/auth/contention if reported, then:
skeeper repair
skeeper sync
skeeper status --check

repair --check 只读。repair 会修复安全的本地问题，例如钩子偏差、可安全恢复的中断事务、健康同步后过期的绕过记录，以及缺失的本地旁置仓库对象。遇到有歧义的覆盖或删除决策时，它会停止。

从锁文件还原文件

skeeper restore docs/specs/auth.md
skeeper restore --all

默认情况下，restore 使用锁定的旁置仓库提交。如果你想使用旁置仓库远程端的最新状态，而不是当前锁定的状态，请使用 pull。

解决 skeeper.lock 合并冲突

git merge feature/auth-redesign
# if the automatic merge driver was not wired locally:
skeeper repair
skeeper sync
git add skeeper.lock
git commit

不支持手动编辑旁置仓库 SHA 标量值。请通过 Skeeper 重新生成锁文件。

CI 集成

同仓库 GitHub Action 封装了已发布的二进制文件：

name: skeeper

on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: compozy/[email protected]
        with:
          args: |
            status
            --check
            --json
          ssh-private-key: ${{ secrets.SKEEPER_SSH_PRIVATE_KEY }}

凭据优先级：

1. ssh-private-key 会写入临时密钥并设置 GIT_SSH_COMMAND。清理时会擦除密钥。
2. token 会在每个作业独有的 GIT_CONFIG_GLOBAL 中配置 HTTPS GitHub 凭据。
3. 如果未提供这两项输入，则使用运行器现有的 Git/SSH 配置。

配置前始终会通过 ::add-mask:: 将密钥屏蔽。

不适合使用 Skeeper 的情况

• **已经在主树中对规格文件进行版本管理，**并希望它们与代码一同出现在 PR 差异中的仓库。Skeeper 的作用就是让规格文件不出现在这些差异中。
• 需要在合并前对规格文件内容进行 PR 审查的团队。 Skeeper 会在主提交成功后才进行镜像同步，因此必须在旁置仓库中审查规格文件，或在提交前审查主树工作副本。
• 没有稳定旁置仓库托管端的仓库。 Skeeper 要求工作树在提交期间能够访问 Git 远程端；如果远程端无法访问，每次提交都会失败关闭，除非有人使用 SKEEPER_SKIP=1。
• 存储构建产物、生成的代码或大型二进制文件。 Skeeper 面向规格类文本产物。防护限制默认设为每个计划最多 100 个文件、10 MiB，正是为了确保用途不偏离这一范围。

Agent 的反模式

1. 切勿在启用了 skeeper 的仓库中使用 git commit --no-verify。 请改用 SKEEPER_SKIP=1，以便记录绕过操作。
2. 切勿手动编辑 skeeper.lock 中的 SHA。 请使用 skeeper sync 重新生成锁文件。
3. 切勿在多个项目之间重复使用未设置唯一命名空间的 sidecar 远程服务。 Skeeper 要求路由明确无歧义；每个文件必须有唯一的所有者。
4. 切勿使用 SKEEPER_SKIP=1 绕过检查后忘记运行 skeeper sync。 在清除绕过状态之前，它会持续出现在 status、repair 和 pre-push 中。
5. 切勿在 patterns 中使用否定 glob。 请改用 exclude；加载器会明确拒绝否定 glob。
6. 切勿为了修复合并冲突而删除 skeeper.lock。 请使用 skeeper repair/skeeper sync 解决冲突。
7. 切勿以为 skeeper restore 会追踪最新版本。 它会从锁定的提交中恢复；要获取远程文档的最新版本，请使用 skeeper pull。
8. 切勿意外清理仅存在于远程的 sidecar 文件。 只有在有意将本地文件集设为权威版本时，才使用 skeeper push --prune。
9. 切勿在面向用户的工作流指南中调用 skeeper internal 命令。 它们属于钩子和合并驱动程序的底层机制。

参考资料

• references/cli-reference.md — 所有公开命令和标志。
• references/config-reference.md — 完整的 .skeeper.yml 架构、默认值和验证规则。