文档漂移检测 KairosSignal/driftlock-agent-docs

Driftlock

Tests

Driftlock 是一个 agent 技能，也是一个无依赖的 Python CLI，用于在仓库变化时保持项目文档与代码同步。

它确定性地检测文档漂移，通过声明的依赖关系传播评审影响，引导 agent 穿过分层索引，并将归档内容排除在默认上下文之外。

14 秒了解它

Driftlock 动画终端演示

对 src/auth/session.py 的一次改动会使认证契约变为 STALE，并且仅通过其声明的摘要链传播 REVIEW_REQUIRED。无关的计费契约保持 CURRENT，并留在更新队列之外。

为什么

长期运行的项目往往会积累多个状态文件、重复的架构说明、过时的交接文档以及庞大的归档。AI agent 随后可能会读取错误的文档、重复已完成的工作，或者将大部分上下文花在历史上。

Driftlock 让新鲜度变得确定。Markdown 文档在一个小型 JSON 索引块中声明其身份和关系。CLI 在 .driftlock.lock.json 中记录已评审内容的哈希，并报告计算出的状态：

- CURRENT
- STALE
- REVIEW_REQUIRED
- UNVERIFIED

功能

- 渐进式 L0/L1/L2 文档索引
- 用于 agent 路由的单一项目入口点
- 对文档和被监视代码路径进行 SHA-256 新鲜度检查
- 对摘要、状态和契约进行依赖传播
- 具备 Git 感知的验证，并带有脏路径保护
- 只读发现和归档规划
- 将归档与启动上下文和活动依赖图隔离
- 可选的问题登记模式，在不把每个观察结果都转换为已授权任务的情况下保留未解决的反馈
- 推荐的任务生命周期语义，区分评审接受、集成、部署、返工和最终关闭，而不强加通用的跟踪器模式
- 面向 agent 和 CI 的结构化 JSON 输出
- 使用标准库 Python，无运行时依赖

问题接收而不造成任务蔓延

Driftlock 区分未解决的观察结果与已授权的工作。项目可以将用户反馈、截图、UX 投诉或历史缺陷保存在外部问题跟踪器中，或保存在仓库原生的当前问题登记中。该登记是可选的；要求是只有一条权威的接收路径。

问题记录不授权实施。历史反馈通常应从 needs_revalidation 开始，然后在检查当前证据后变为 confirmed、obsolete、parked，或链接到权威任务。大型登记应留在默认启动上下文之外，并且仅在当前任务涉及受影响区域时才加载。

有关推荐状态，请参见 references/problem-register-and-feedback.md，最小字段、任务边界、去重规则，以及一个 Driftlock 索引示例。

当前版本：0.2.2

0.2.2 增加了推荐的任务生命周期/状态语义，使仓库原生项目能够区分实现、评审验收、集成、部署、返工和最终关闭。它还增加了一份具体的仓库问题登记采用清单，同时保留了问题受理不授权实现这一规则。

与 0.2.1 相比，没有索引模式变更，也没有破坏性的 CLI 命令变更。

智能体兼容性

Driftlock 不绑定于某一个模型或编码智能体：

- 任何具有 shell 访问权限的智能体都可以运行 Python CLI。
- 支持 SKILL.md 包的智能体可以将该仓库作为技能加载。
- 没有技能系统的智能体可以将 SKILL.md 用作项目指令，并直接调用 scripts/driftlock.py。
- 人类和 CI 可以在没有智能体的情况下使用同一 CLI。

agents/openai.yaml 提供可选的 OpenAI/Codex 接口元数据。核心技能和 CLI 不导入也不依赖 OpenAI 库。

安装

将仓库克隆到你的智能体所使用的技能或指令目录中：

git clone https://github.com/KairosSignal/driftlock-agent-docs.git

然后要么将克隆的目录注册为 driftlock 技能，要么从该目录运行 CLI。有关技能发现目录的信息，请查阅你的智能体文档。

Codex

让 Codex 安装公共技能：

Install the Driftlock skill from https://github.com/KairosSignal/driftlock-agent-docs

或者将其克隆到 Codex 技能目录中：

git clone https://github.com/KairosSignal/driftlock-agent-docs.git \
~/.codex/skills/driftlock

安装后重启 Codex，以便发现该技能。

与智能体一起使用

对于任何智能体，让它读取 SKILL.md 并使用捆绑的 CLI：

Read the Driftlock SKILL.md, audit this repository's documentation, and report
the minimum updates needed. Do not read archives unless required.

Codex

显式调用该技能：

Use $driftlock to audit this repository's documentation and report the minimum
updates needed. Do not read archives unless required.

该技能还会在文档审计、重组、新鲜度验证、归档隔离、项目地图创建以及任务/报告泛滥时触发。

CLI

要求：

- Python 3.9 或更高版本
- Git 2.25 或更高版本，用于感知提交的验证
- Linux、macOS 或 Windows

仅在显式的仅哈希模式下，Git 才是可选的。没有 Git 时，verify 需要 --allow-hash-only，并会报告降低的保证级别。

直接从技能目录运行 CLI：

python3 scripts/driftlock.py discover /path/to/project
python3 scripts/driftlock.py check /path/to/project
python3 scripts/driftlock.py impact /path/to/project --since HEAD~1
python3 scripts/driftlock.py verify /path/to/project \
--doc project-entry --status-effect initial
python3 scripts/driftlock.py archive-plan /path/to/project
添加 --format json 以用于自动化。

discover、check、impact 和 archive-plan 是只读的。verify 是唯一会写入的命令，并且它只以原子方式写入 .driftlock.lock.json。

CLI JSON 报告和生成的锁文件都包含 tool_version。当前发布线是 0.2.2。

文件格式

Driftlock 使用自己的 v0.2 格式：

- .driftlock.lock.json 存储已验证的文档状态。
- driftlock-index 是 Markdown 元数据围栏。
- scripts/driftlock.py 是唯一的 CLI 实现。

目标仓库始终在运行时通过 project_root 选择；这些标识符都不是目标项目名称。

可运行演示

从任意检出目录运行捆绑示例：

python3 examples/run_demo.py

该演示会创建一个临时 Git 仓库，将四个文档验证为 CURRENT，更改认证代码，并检查只有认证契约及其摘要链进入更新队列。它还演示了 CI 契约：退出码 1 是普通的过期状态，而只有 2 和 3 会阻断。

最小索引

每个受管理的 Markdown 文件都包含一个带有严格 JSON 的围栏 driftlock-index 块。一个最小的 L0 条目如下所示：

driftlock-index
{
"schema_version": 2,
"id": "project-entry",
"authority_key": "project.entry",
"level": 0,
"role": "project_entry",
"lifecycle_status": "active",
"startup": [
"docs/current/status.md",
"docs/current/task-board.md"
],
"startup_budget": {
"max_files": 5,
"max_characters": 12000
},
"archive_roots": [
"docs/archive"
]
}

当仓库没有有效的 L0 条目时，请先使用 discover。它会报告候选条目，而不会凭空创造权威或移动文件。

推荐工作流

1. 运行 discover 以了解现有文档。
2. 建立一个 L0 条目并收窄 L1 分支。
3. 确定权威任务系统，并在需要时确定权威的未解决问题/反馈接收渠道。不要让任务板同时承担这两个角色。
4. 添加索引和显式依赖边。
5. 审查每个文档并运行 verify。
6. 将 .driftlock.lock.json 与已审查的文档一起提交。
7. 在代理工作流或 CI 中运行 check。

Driftlock 从不自动重写语义内容、分配权威、移动文档或删除归档。这些仍然是明确的人类或代理决策。

退出码

| 代码 | 含义 |
| 0 | 最新且结构有效 |
| 1 | 普通过期、需要审查或未验证状态 |
| 2 | 结构错误或拒绝验证 |
| 3 | 参数、Git、权限、JSON 或文件系统失败 |

CI 包装器应将 0 和 1 视为非阻断，并仅阻断 2 或 3。

测试

python3 -m unittest discover -s tests -p 'test_*.py'

许可证

MIT