Nwflower/dsh-file-claim ↗★ 6

dsh-file-claim

提供多会话并发工作区的文件占用保护与三路合并 适合多会话同时操作同一工作区、需要防止文件被覆盖的协作任务。

套件
dsh-file-claim
相容性
待驗證
版本
0.2.0
授權
MIT
最近更新
2026年9月2日

安裝

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:Nwflower/dsh-file-claim

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):

KeyDefaultMeaning
staleMs7200000 (2h)Heartbeat expiry before a session is considered stale
guardtrueSet false to disable the pre-execute write guard
guardCommitfalseOpt-in: also deny git commit that explicitly stages paths actively claimed by another session
heartbeatMs600000 (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/.