前言¶

在 DeepSeek Harness（DSH）里，多个会话可能同时处理同一个 workspace。如果没有显式协调，两个会话可能编辑同一个文件，造成覆盖；会话崩溃后也可能留下过期的占用状态；另一个会话想修改已被占用的文件时，只能等待或猜测。

dsh-file-claim 面向这个问题：它为并发 DSH 会话提供文件 claim/保护，包括 claim/release、心跳过期接管、异步待合并区（git 3-way merge）。下面介绍它的定位、核心能力、安装方式和典型用法。

这是什么¶

dsh-file-claim 是一个 DSH Host 插件，由 Nwflower 维护，采用 MIT 许可证。

它把文件占用声明、释放、状态查询、pending 合并等能力做成 tools，并通过 DSH 生命周期事件刷新心跳、释放离开会话的 claim。

核心功能¶

claim / release¶

• claim_files：会话在编辑前声明文件/目录路径的独占所有权。
• 重复 claim 会幂等合并。
• 目录 claim 覆盖子级路径。
• 对 '.' 的 claim 表示整个 workspace。
• release_files：释放 claim；owner release 后，pending 区可按规则合并。

heartbeat 与 stale 接管¶

• agent/created / agent/status 事件刷新心跳。
• agent/disposed 自动释放离开会话的所有 claim。
• 崩溃/强杀会话的 claim 在下次活动时清理，并由心跳间隔清扫。
• staleMs 过期和 --force takeover 作为慢速兜底；staleMs 默认 2h，适用于无 pid 记录的场景。

async pending merge area¶

• 对已被其他会话占用的文件，写入 pending 区，而不是直接阻塞。
• owner release 后，无冲突时通过 git 3-way merge 自动合并。
• 冲突时使用 pending_apply 手动合并。
• 辅助工具包括 pending_show 查看条目、pending_drop 丢弃条目。

write guard¶

• tools/pre-execute 守卫拒绝写入被其他会话 active claim 的文件。
• 被拒绝时给出 wait / takeover when stale / pend 提示。
• 可选 commit guard。
• 该守卫属于 cooperative tool-layer guardrail，标注为 fail-open，并匹配该类别 de-facto standard。

audit 与轻量运行¶

• claim/release/takeover/pending 变更追加为 JSON line，用于追溯和崩溃后 reconciliation。
• 插件为 pure Host plugin、zero dependencies，无 Browser 侧、无 build step，仅 node: builtins，Windows-friendly。

安装与启用¶

先确认环境满足：

• DSH with node >= 18
• git 在 PATH 中；git 仅用于 3-way merge

然后执行安装命令：

dsh plugin add dsh-file-claim

安装后，插件提供以下 tools：claim_files、release_files、who_claims、claim_status、pending_write、pending_apply、pending_show、pending_drop。

典型用法¶

先 claim，再编辑，最后 release¶

先声明所有权：

claim_files({ paths: ["README.md"] })

然后执行 write/edit。完成后释放：

release_files({ paths: ["README.md"] })

经过上面的步骤，本会话的 claim 被释放，pending 区中的相关条目会进入合并流程。

查看 claim 状态¶

查看某个路径被谁 claim：

who_claims({ paths: ["README.md"] })

查看 registry、claims、pending area 和 audit：

claim_status()

写入被其他会话占用的文件¶

写入被其他会话 claim 的文件会被 DENIED，并提示等待、stale 时 takeover 或 pend。

如果要把编辑内容先放到 pending 区：

pending_write({ path: "README.md", content: "..." })

owner release 后，无冲突时自动 git 3-way merge；冲突时运行：

pending_apply

也可以查看或丢弃 pending 条目：

pending_show
pending_drop

接管 stale claim¶

发现其他会话 claim stale 后，可用 takeover：

claim_files({ paths: ["README.md"], force: true })

适用场景与注意¶

适合：

• 多个 DSH 会话并发编辑同一个 workspace。
• 希望减少同一文件被并发覆盖的情况。
• 希望被占用文件可以写入 pending 区，而不是只能等待。
• 希望用 JSON line audit 追溯 claim/release/takeover/pending 变更。

注意：

• 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。
• write guard 是 cooperative tool-layer guardrail，且标注为 fail-open；它用于协作约束，不要把它当作强隔离边界。
• staleMs 默认 2h，--force takeover 是慢速兜底。
• git 仅用于 3-way merge；自动合并依赖该流程。
• 插件无 Browser 侧、无 build step、zero dependencies，部署时主要关注 DSH、node、git 和源码审查。

结尾¶

dsh-file-claim 把并发 DSH 会话中的文件 claim、release、pending 合并和 audit 放到同一组 tools 中，让「先 claim、再编辑、最后 release」成为可执行的协作流程。

插件名：dsh-file-claim

仓库地址：https://github.com/Nwflower/dsh-file-claim

目录页可按插件名 dsh-file-claim 查询。