dsh-workspace-change-awareness：在智能體繼續前暴露併發工作區變更

前言¶

在使用 DeepSeek Harness (DSH) 構建智能體時，如果工作區在智能體處理過程中發生變化（例如，另一個智能體、IDE 或命令行工具編輯了文件），智能體可能會繼續依賴陳舊或過時的緩存文件，從而導致不一致。

核心功能¶

這個插件在智能體繼續工作前，會暴露併發工作區變更。它通過以下機制實現：

1. 共享監視器：使用相同規範化工作區根目錄的實時會話共享一個 Chokidar 監視器。
2. 路徑驗證：監視器事件僅使路徑失效；在模型請求之前，插件通過 ctx.fs 解析並統計每個路徑。
3. 版本控制：僅當權威的外部工具結果成功、其 tool/result 被附加並且封閉的 step/end 提交時，才保留會話的 DSH fs/observed 版本。嵌套代碼模式效果如果其外部調用失敗，則保持“髒”狀態而不是自我承認。
4. 持久化日誌：成功的、持久化記錄的 DSH 讀取/寫入/編輯成爲該會話的承認版本，因此寫入者不會收到冗餘通知，而其他智能體仍會收到通知。
5. 用戶通知：在 agent/pre-step 插入源用戶角色通知，以便它在模型看到之前持久化。
6. 最終檢查：agent/turn-stopping 在新文件系統狀態或監視器邊界降級到達時執行最終檢查並引導一步。
7. 狀態分離：已交付狀態與 DSH 讀取/寫入基線分開記憶，防止重複引導同時仍報告新版本。
8. 精確接收器：精確的進程本地監視器接收器僅承認由持久化通知覆蓋的路徑生成。不可用的路徑保持待定直到驗證恢復。
9. 有界啓動：監視器啓動有界且可取消。

安裝與啓用¶

前置要求：
- Node.js: ^22.19.0 || >=24.0.0
- pnpm: 11.7.0

先構建項目，然後從檢出的相對包路徑運行配置文件安裝程序，以確保相對路徑正確錨定：

pnpm build
pnpm exec dsh plugin --profile <profile-name> add .

該包聲明瞭 dsh.bundle.patch，因此 dsh plugin 會自動激活 cordis.patch.yml。

配置¶

該包無需配置即可工作。稍後的配置文件補丁可以替換其行並設置值，例如：

- id: workspace-change-awareness
  name: dsh-workspace-change-awareness
  config:
    debounceMs: 75
    maxWaitMs: 500
    maxNoticePaths: 50
    statConcurrency: 16
    usePolling: false
    pollIntervalMs: 100
    verifyAtTurnStop: true
    ignoredDirectories: [.git, node_modules]

適用場景與注意¶

該插件以當前 DSH 進程權限運行。安裝前應檢查源碼與許可證。

需要注意以下邊界情況：
- 監視器事件僅使路徑失效；它們不直接跟蹤文件內容。
- 文件系統事件無法證明是誰做的更改。通知說明路徑在會話的承認文件系統觀察之外發生了變化，而不是聲稱是人類作者。
- 主機監視不覆蓋遠程文件系統提供程序。以前觀察到的遠程目標通過 ctx.fs.stat() 在 pre-step 處重新驗證。
- 新智能體從當前工作區狀態開始；初始文件不報告爲更改。
- 恢復或壓縮會話收到保守的重新讀取提醒，因爲進程本地觀察無法覆蓋 DSH 停止期間所做的編輯。
- 監視器啓動有界且可取消。
- 文件名是 JSON 轉義的，可見列表是有界的。
- 在最終 pre-step 統計之後的變化在下一個邊界被觀察到。DSH 現有的文件系統觀察策略仍然爲第一方寫入和編輯提供原子過期版本保護；任意 shell 寫入繞過該策略。

結尾¶

這個插件通過在智能體繼續前強制驗證文件系統狀態，解決了併發編輯導致的緩存不一致問題。

GitHub 倉庫