用途
在同一个代码仓库上并行运行多个 AI 编码代理（Claude Code、Codex、Cline、Cursor 等）已经是一种常见工作流，通常每个代理使用一个 git worktree。这些会话之间不共享状态：代理看不到同伴在做什么，两个代理触碰相同文件会导致静默覆盖和无法合并的差异。
dibs 提供缺失的协调原语，让并行编码代理不再碰撞。
主要能力
- 文件声明与过期：声明是一个 JSON 文件，包含代理名称、一组模式、原因和过期时间。冲突检查在建议锁（advisory lock）下运行，过期时间在读取时惰性评估，无需守护进程。
- 模式匹配：模式是相对于仓库根目录的 doublestar glob（绝对路径会被解析进仓库根目录）。声明一个目录即声明其子树，尚不存在的路径也按同样方式处理。只有已存在的常规文件会被按字面声明。glob 到 glob 的冲突检测是保守的：静态前缀嵌套的两个 glob 被视为冲突。
- 身份解析：身份按 --agent、DIBS_AGENT、从 worktree 路径派生的稳定名称的顺序解析，因此每个 worktree 都有零配置的一致身份。
- 日志：每次声明、拒绝、释放、过期和备注都会追加到 JSONL 日志（dibs log）。
- 强制执行钩子（可选启用）：
- Claude Code：dibs hook install claude 注册一个 PreToolUse 钩子。当代理试图编辑被其他代理声明覆盖的文件时，工具调用被阻止（退出码 2），模型会收到一条消息，指明持有者、原因和过期时间。
- 任何代理：dibs hook install pre-commit 注册一个 git 钩子，拒绝触碰其他代理声明文件的提交。
- 钩子安装是叠加且幂等的：.claude/settings.json 中的现有条目和现有 git 钩子都会被保留，dibs hook uninstall claude 只会移除添加的内容。两个钩子都失败开放（fail open）：如果 dibs 无法运行，编辑和提交正常进行。
- 经验教训（Lessons）：捕获代理学到的东西，让下一个会话不必重新发现。经验教训是 .dibs/lessons/ 下带 YAML frontmatter 的 Markdown 文件，通过 git 共享——整个团队和 CI 通过 git pull 获得；可像代码一样经过拉取请求审查、纠正或还原；使用 BM25 排序并对标题、标签和正文做轻量词干提取，每次查询在内存中计算，无需嵌入模型或向量存储。
- MCP 服务器：dibs mcp 运行一个 stdio MCP 服务器，代理通过类型化工具而非 shell 命令进行协调。服务器指令和工具描述编码了协议（编辑前声明、完成后释放、留下备注、记录经验教训）。支持任何具备 stdio 传输的 MCP 客户端。
使用方式
从 releases 页面获取 Linux、macOS、Windows（amd64/arm64）的预编译二进制文件。从源码构建需要 Go 1.26+；运行时需要 git。
多架构容器镜像发布在 GHCR——将仓库挂载到 /workspace。同一镜像也可从包含的 Dockerfile 本地构建（docker build -t dibs .）。
退出码：0 表示正常/空闲，1 表示错误，2 表示被拒绝或被其他代理持有。所有读取状态的命令都接受 --json 以便脚本化。
可以与任务跟踪工具（如 beads）配合，例如 dibs claim src/auth --reason "bd-142: refactor auth"；也可以与任何会话管理器配合，因为协调独立于会话的启动方式。
适用场景
- 在同一台工作站上并行运行多个编码代理的团队。
- 希望代理在编辑前声明文件、避免静默覆盖的场景。
- 希望让代理积累的经验教训随代码一起经过 git 审查和共享。
- 希望用类型化 MCP 工具而非 shell 命令来协调代理的场景。
限制
- 无基础设施：没有守护进程、服务器、数据库或遥测。所有状态是磁盘上的纯 JSON 和 Markdown。移除 dibs 后仓库会恢复原样，只少一个目录。
- 租约而非锁：每个声明都会过期。崩溃或被遗弃的代理无法阻塞仓库（默认 TTL 30 分钟，过期会记录到日志）。
- 失败开放的强制执行：钩子故障绝不能阻止合法工作；强制执行倾向于允许编辑。
- 合作信任模型：dibs 协调行为良好的代理，并在 Claude Code 内和提交时强制执行声明。它不是针对刻意绕过它的进程的安全边界。
- 机器本地协调：实时声明是按机器本地存储的，匹配在一台工作站上并行代理的主流工作流。经验教训通过 git 跨机器传播。跨机器实时协调在路线图中。
- 保守的冲突检测：重叠的 glob 前缀即使可能不相交也会被视为冲突。误报成本低；静默碰撞则不是。
- 单代理使用：dibs 对单个代理在缩减角色下也有用：经验教训提供跨会话的持久知识，日志提供何时声明的审计线索。
与其他方案比较
相邻工具解决不同问题。dibs 与这些工具组合而非替代它们。不使用 git lfs locks 或提交到仓库的锁文件，因为 LFS 锁需要服务器且不会过期；提交的锁文件会产生提交噪音，且对未提交的 worktree 不可见；两者都不支持 glob 模式，也无法向被阻止的代理传达上下文。
项目信息
MIT © 2026 polymatx。项目有意保持小规模：标准库加三个依赖，无守护进程、无数据库。贡献指南见 CONTRIBUTING.md，完整协调协议见 docs/protocol.md。
