drift

Drift

drift 将 Markdown 文档绑定到代码，并检查文档是否过时。

这对 Agent 为什么重要

更改代码却不更新描述它的文档，会导致文档过时。未来的会话会将过时文档加载为上下文，并根据错误的描述生成错误的代码。问题会不断累积——每个信任过时文档的会话都会让情况变得更糟。drift 将锚点明确化并使其可强制执行，从而打破这一反馈循环。

重新关联门槛

drift link 不会在没有明确审查的情况下重新记录过时锚点。当目标的签名发生变化时，drift link 会打印相关文档段落；对于符号或 Markdown 标题锚点，还会打印当前目标上下文。在非 TTY 运行中，它会以 1 退出；在 TTY 运行中，它可以提示确认。

这意味着你不能盲目重新关联。你必须审查文档正文，并确认其仍然准确。使用：

drift link docs/auth.md --doc-is-still-accurate

更改代码后

查找引用了你所更改的确切目标的文档：

drift refs src/auth/login.ts
drift refs src/auth/provider.ts#AuthConfig

或者一次检查所有文档：

drift check

如果某个文档因你的更改而过时：

1. 运行 drift link <doc-path>——它会打印审查上下文，然后拒绝操作
2. 阅读文档段落及打印出的任何目标上下文，了解哪些内容不同步
3. 更新文档正文以反映你的更改
4. 运行 drift link <doc-path> --doc-is-still-accurate——审查完成后，此命令会成功
5. 验证：drift check

不要跳过这一步。让文档过时比没有文档更糟。

更改文档后

刷新文档中的所有锚点，以记录当前状态：

drift link docs/my-doc.md

这会更新 drift.lock 中该文档所有现有绑定的来源信息。当前 drift link <doc-path> 的批量模式不会发现或添加文档正文中的内联 @./ 引用；如需添加新目标，请使用 drift link <doc-path> <target> 显式添加。

创建新代码时

如果现有文档涵盖了新代码，请添加锚点：

drift link docs/auth.md src/auth/new-handler.ts

如果新代码值得单独编写文档，请撰写文档并关联它：

drift link docs/new-feature.md src/feature/index.ts
drift link docs/new-feature.md src/feature/types.ts#Config

删除或重命名代码时

如果绑定的文件被删除或重命名，drift check 会将其报告为 STALE，并显示“file not found”。移除过时锚点：

drift unlink docs/auth.md src/auth/old-handler.ts

如果你重命名了文件，请取消关联旧路径，并关联新路径：

drift unlink docs/auth.md src/auth/old-name.ts
drift link docs/auth.md src/auth/new-name.ts

更新文档正文以反映重命名。

重构时

将代码移至其他文件或重命名符号的重构，可能会同时影响多篇文档。重构后运行 drift check，找出所有受影响的文档，然后逐一更新。

CI 中 drift check 失败时

有人更改了绑定的代码，却没有更新文档。查看 lint 输出，了解哪些文档已过时以及原因，更新文档正文，然后运行 drift link 以刷新来源信息。

锚点语法

drift.lock 中的绑定：

version = 1

[[bindings]]
doc = "docs/auth.md"
target = "src/auth/login.ts"
sig = "a1b2c3d4e5f6a7b8"

[[bindings]]
doc = "docs/auth.md"
target = "src/auth/provider.ts#AuthConfig"
sig = "c3d4e5f6a7b8a1b2"

[[bindings]]
doc = "docs/overview.md"
target = "docs/auth.md#authentication"
sig = "b3c4d5e6f7a8b9c0"

锚点可以指向代码文件、代码符号（file#Symbol）或文档标题（doc.md#heading-slug）。标题片段使用 GitHub 风格的 slug（小写字母，以连字符分隔）。

drift link 会将绑定及其内容签名（sig = "<hex>"）写入 drift.lock。内容签名是对受支持语言进行语法感知的指纹；对于不受支持的整文件锚点，则使用原始内容指纹。不受支持的符号锚点无法生成指纹。检测内容是否过时无需查询 VCS 历史，因此 drift link 可用于未提交的文件——无需先提交。

重新关联过时锚点时，drift link 会拒绝操作并打印审查上下文，以便你检查更改。传入 --doc-is-still-accurate，即可确认文档无需更新。

drift lint 还会检查锁文件根目录下发现的 Markdown 文档中的 Markdown 链接（[text](path.md)）是否存在——失效链接会报告为 BROKEN，无需在锁文件中添加条目。

跨仓库文档（origin）

从其他仓库安装的文档（如本技能）会在 drift.lock 的绑定中携带 origin，这样 drift check 就会跳过使用方仓库中的这些锚点。如果你正在编写要分发到其他仓库的文档，请添加 origin，以避免误报：

version = 1

[[bindings]]
doc = "docs/skill.md"
target = "src/main.ts"
origin = "github:your-org/your-repo"
sig = "a1b2c3d4e5f6a7b8"

过时检查

drift check 会读取 drift.lock 中的绑定项；如果有任何锚点已过时或 Markdown 链接失效，就会以 1 退出。使用 drift check --changed <path> 可将检查范围限定为受影响的文档；如果你知道哪些文件发生了更改，这在 CI 中很有用。对于支持的语言（TypeScript 系列文件，包括 TS/TSX/JS/JSX、Python、Rust、Go、Zig、Java），比较会考虑语法，因此仅格式变更不会触发过时检查。对于已更改的锚点，过时报告会尽可能附上目标文件的 Git 上下文（作者、提交、提交者日期、主题），方便你查看更改内容。

对于 --format json，负载为 schema_version: drift.check.v1（请参阅仓库中的 docs/check-json-schema.md）。其中，blame.date 是 ISO 8601 严格格式的提交者日期，而非作者日期；如果你需要在变基后按稳定的时间顺序排序，请使用它。摘要包含 verification_state（none | partial | full），用于说明实际检查与跳过的文档数量（例如，来源不匹配）。

常见原因：

• 文档编写后内容已更改 — 文件或符号内容与来源快照不同
• 未找到文件 — 绑定的文件已不存在
• 文件不可读 — 绑定的文件存在，但无法读取
• 未找到符号 — 绑定的符号已不在文件中
• 指纹不可用 — drift 无法计算目标指纹
• 基线不可用 — 绑定项没有可用的来源信息
• 来源不匹配 — 绑定项属于其他仓库，因此被跳过
• 未找到链接目标 — Markdown 链接指向不存在的文件

drift lint 是 drift check 的别名。