用途:drift 把 Markdown 文档与代码绑定,并 lint 文档是否过期。代码改了而描述它的文档没改,文档就会过期,过期文档在后续会话中被当作上下文会产出错误代码,drift 让锚点显式且可强制检查,从而打断这个循环。
主要能力:锚点可指向代码文件、代码符号(file#Symbol)或文档标题(doc.md#heading-slug,标题片段用 GitHub 风格 slug)。drift link 把绑定写入 drift.lock,并记录内容签名 sig。对支持的语言(TS/TSX/JS/JSX、Python、Rust、Go、Zig、Java)比较是语法感知的,仅格式变化不会触发过期;不支持的语言按整文件原始内容指纹,不支持的符号锚点无法生成指纹。过期检测不查询 VCS 历史,因此未提交文件也可用。drift lint 还会检查文档中的 Markdown 链接是否存在,断链报 BROKEN。
使用方式:改代码后用 drift refs <target> 找引用该目标的文档,或用 drift check 检查全部;文档过期时先运行 drift link <doc-path>,它会打印审查上下文并拒绝,阅读文档段落与目标上下文后更新文档,再运行 drift link <doc-path> --doc-is-still-accurate 确认。改文档后用 drift link <doc-path> 刷新该文档所有绑定的来源信息;新增目标需显式 drift link <doc-path> <target>。删除或重命名代码时用 drift unlink 移除旧锚点,重命名则 unlink 旧路径再 link 新路径。CI 中 drift check 失败说明有人改了绑定代码未更新文档。drift check --changed <path> 可缩小检查范围;--format json 输出 schema_version: drift.check.v1,其中 blame.date 是提交者日期的 ISO 8601 严格格式,summary 含 verification_state(none | partial | full)。跨仓库文档可在绑定中加 origin(如 github:your-org/your-repo),使消费仓库跳过其锚点。
限制:drift link 的整文档模式不会从文档正文发现或添加内联 @./ 引用,新目标需显式添加。过期原因包括 changed after doc、file not found、file not readable、symbol not found、fingerprint unavailable、baseline unavailable、origin mismatch、link target not found。drift lint 是 drift check 的别名。安装方式与收费信息暂未提供。