Nwflower/dsh-file-claim
40最近提交 2026年8月14日
dsh-file-claim DSH 插件
dsh-file-claim 为并行 DSH 会话提供协调协议，避免相互覆盖文件。它提供声明/释放工具、基于心跳的过期检测，以及带有 git 三路合并的异步待处理合并区域。
如何安装 dsh-file-claim DSH 插件
dsh plugin add dsh-file-claim复制不会执行命令。安装 dsh-file-claim DSH 插件前请核对仓库和版本。
dsh-file-claim DSH 插件数据来源
dsh-file-claim DSH 插件快照日期：2026年8月16日
discovered
dsh-file-claim DSH 插件能做什么
- 在编辑前声明和释放文件路径的独占所有权，支持目录和整个工作空间声明。
- 通过代理生命周期事件自动刷新心跳；下次活动或心跳间隔清除过期声明。
- 异步待处理合并区域：将编辑内容写入待处理区，当所有者释放时通过 git 三路合并自动合并。
- 写保护：拒绝写入被其他会话积极声明的文件，并提示等待、接管或挂起。
- 所有声明/释放/待处理变更的审计日志，用于追踪和崩溃后恢复。
dsh-file-claim DSH 插件适合哪些场景
- 两个会话编辑同一文件：一个声明，另一个使用 pending_write 避免阻塞。
- 恢复崩溃的会话：声明变过期或立即清除，允许接管。
- 协调多个代理在共享代码库上工作，避免文件冲突。
- 使用 /claim-status 检查当前声明和待处理区以调试。
dsh-file-claim DSH 插件适合谁
- 在同一个工作空间中使用 DSH 进行并行代理工作流的开发者。
- 需要无需外部锁定服务器的健壮文件级协调的用户。
dsh-file-claim DSH 插件的限制
- 写保护是协作性的（失败开放）：不阻止 DSH 外部的直接文件系统写入。
- Git 三路合并需要在 PATH 上安装 git；冲突时可能需要手动解决。
- 仅支持 Node >=18；无需浏览器端或构建步骤。
- 状态目录 (.dsh-file-claim) 应加入 .gitignore 以避免混乱。
dsh-file-claim DSH 插件的仓库 README 摘录
以下文字摘自 dsh-file-claim DSH 插件的上游仓库 Nwflower/dsh-file-claim 的 README，版权归原作者，仅作引用。
> **Write in parallel. Never overwrite.** > File claim / protection for concurrent DeepSeek Harness (DSH) sessions working the same workspace. When several DSH sessions run in parallel against one workspace, they have no awareness of each other: two sessions can overwrite the same file, a crashed session leaves stale state behind, and a session that wants to edit a file another session owns can only wait or guess. `dsh-file-claim` turns a proven coordination protocol into native DSH tools, lifecycle events, and a write guard — so parallel agents cooperate instead of clobbering each other. ```text claim_files({ paths: ["README.md"] }) # "I'm editing this" write / edit ... # writes to files claimed by others are denied release_files({ paths: ["README.md"] }) # "done — pending edits auto-merge now" ``` ## Table of Contents - [Features](#features) - [Why](#why) - [Install](#install) - [Quick Start](#quick-start) - [Usage Examples](#usage-examples) - [Tools](#tools) - [Commands](#commands) - [Write Guard](#write-guard) - [Configuration](#configuration) - [Audit Log](#audit-log) - [Pending Merge Area](#pending-merge-area) - [Enforcement Boundary](#enforcem
阅读完整 README仓库许可: MIT
dsh-file-claim DSH 插件常见问题
如何安装 dsh-file-claim？
在 DSH 环境中运行 `dsh plugin add dsh-file-claim` 即可从 npm 安装。需要 Node >= 18 以及 git 在 PATH 上。
如果持有声明的会话崩溃了怎么办？
心跳机制会检测到崩溃：代理生命周期事件 `agent/disposed` 会自动释放所有声明。此外，staleMs 超时（默认2小时）会清除没有心跳的声明。你也可以通过 `claim_files(force: true)` 强制接管。
我可以写入被其他会话声明的文件吗？
写保护会拒绝写入并给出提示。你可以等待所有者释放，使用 `pending_write` 将编辑内容放入待处理区等待自动合并，或者如果声明过期则接管。
待处理合并是如何工作的？
当你调用 `pending_write` 时，插件会记录你的编辑内容以及 git HEAD 的基础版本。当原始所有者释放时，会执行 git 三路合并（当前版本 × 基础版本 × 待处理版本）。如果没有冲突，则自动应用；否则你可以手动运行 `pending_apply` 解决冲突。
写保护安全吗？能不能绕过？
写保护作用于 DSH 工具层，是协作性的（失败开放）。它不阻止 DSH 工具外部的直接文件系统写入。如需完全强制，请考虑使用工作空间隔离。可以通过插件配置设置 `guard: false` 禁用写保护。