dsh-file-claim
提供多会话并发工作区的文件占用保护与三路合并 适合多会话同时操作同一工作区、需要防止文件被覆盖的协作任务。
安装
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:Nwflower/dsh-file-claim说明文档
阅读完整 README ↗Usage Examples
Two sessions, one workspace. Session A owns README.md; session B wants to edit it too:
// Session A
claim_files({ paths: ["README.md"], note: "rewriting the docs" })
write ... README.md // allowed: own claim
release_files({ paths: ["README.md"] })
// Session B — meanwhile
who_claims({ paths: ["README.md"] }) // → claimed by A
write ... README.md // → DENIED with a hint
pending_write({ path: "README.md", content: "..." }) // async, no blocking
// When A releases, the entry is auto 3-way merged (or surfaced for manual pending_apply)
Recover from a crashed session. Session A dies mid-work; its claims expire after staleMs
(2h default), then:
claim_status() # → A shows [stale]
claim_files({ paths: ["README.md"], force: true }) # take over
Configuration
Passed as plugin config in the bundle (cordis.patch.yml):
| Key | Default | Meaning |
|---|---|---|
staleMs | 7200000 (2h) | Heartbeat expiry before a session is considered stale |
guard | true | Set false to disable the pre-execute write guard |
guardCommit | false | Opt-in: also deny git commit that explicitly stages paths actively claimed by another session |
heartbeatMs | 600000 (10min) | Fallback heartbeat interval |
- insert:
- id: dsh-file-claim
name: dsh-file-claim
config:
staleMs: 3600000 # 1h
guardCommit: true # also guard explicit git commits
Since 0.2.0, state is stored as workspace sidecar files — the lock travels with the protected file
(the claude-code-file-locks .agentlock idiom, adopted because DSH reserves no in-workspace directory
convention):
README.md.dshclaim claim sidecar (JSON: version, path, tag, note, startedAt, lastSeenAt, pid)
README.md.dshpending/ pending-merge sidecar (content / base / meta.json), next to the target
.dsh-file-claim.audit.jsonl workspace-global audit log (append-only, at the root)
.dsh-file-claim.lock transient cross-process mutex (exists only during a mutation)
Recommend adding these to .gitignore:
*.dshclaim
*.dshpending/
.dsh-file-claim.audit.jsonl
.dsh-file-claim.lock
When a workspace still carries the ≤0.1.7 flat .dsh-file-claim/ directory (or an unpublished 0.2.0
.dsh/dsh-file-claim/), the first tool/command call migrates it to sidecars (the old directory is kept —
delete it manually once verified; its registry.json is renamed registry.json.migrated as the idempotency
marker). The write guard also reads the old registry until that first call, so protection is seamless across the
upgrade. State survives restarts; nothing ever touches .git/.