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 仓库