kingcheng12/dsh-workspace-change-awareness

dsh-workspace-change-awareness

一个可安装的 DeepSeek Harness 包，用于在 agent 工作时告知其工作区发生了变化。它适用于由人员、另一个 agent、IDE 或 Harness 文件系统工具之外的命令并发编辑的仓库。

该包固定并针对 @deepseek-ai/dsh 0.1.0-rc.7 进行了测试。该 CLI 目前在 0.1.0-rc.8 解析公共 Agent、文件系统和 LLM API；这些 peer 和开发版本已固定在 package.json 中。

行为

- 使用相同规范化工作区根的实时会话共享一个 Chokidar 监视器。
- 监视器事件仅使路径失效。在模型请求之前，插件通过 ctx.fs 解析并 stat 每个路径。
- DSH fs/observed 版本仅在权威的外部工具结果成功、其 tool/result 被追加且外层 step/end 提交后，才按会话保留。外层调用失败的嵌套 Code Mode 效果保持脏状态，而不是自我确认。
- 一次成功且持久记录到日志的 Harness 读/写/编辑会成为该会话已确认的版本，因此写入者不会收到冗余通知，而其他 agent 仍会收到。
- 在 agent/pre-step 插入一条带来源的用户角色通知，因此它在模型看到之前就被持久化。
- 当模型工作时到达新的文件系统状态或降级的监视器边界时，agent/turn-stopping 执行最终检查并引导一个额外步骤。
- 已投递的状态与 DSH 的读/写基线分开记忆，防止重复引导，同时仍报告更新的版本。
- 精确的进程本地监视器回执仅确认持久通知实际覆盖的路径生成。不可用的路径保持待处理，直到验证恢复。
- 监视器启动是有界的且可感知取消的。监视器错误会在注册表尝试新监视器之前产生模型可见的降级覆盖通知。
- 恢复或压缩的会话会收到保守的提醒，要求重新读取文件，因为进程本地观察无法覆盖 DSH 停止期间所做的编辑。

该通知要求模型重新读取受影响的文件，并在依赖缓存内容之前检查当前 diff。文件名经过 JSON 转义，可见列表是有界的。

开发

要求：Node.js ^22.19.0 || >=24.0.0 和 pnpm 11.7.0。

pnpm install
pnpm check

所有依赖版本和包管理器版本都是精确的。pnpm-workspace.yaml 记录了现代 pnpm 所需的经审查的依赖构建脚本策略。生成的输出（lib/）、依赖、日志、覆盖率以及本地环境文件均被忽略。

安装到 DSH profile

先构建，然后从此检出目录运行 profile 安装程序，以便相对包路径被正确锚定：

pnpm build
pnpm exec dsh plugin --profile  add .
pnpm exec dsh --profile  --dump-config
该包声明了 dsh.bundle.patch，因此 dsh plugin 会自动激活 cordis.patch.yml。通过 Git 托管的安装会运行固定版本的 prepare 构建；pnpm 要求配置文件所有者显式允许该安装时构建。

配置

该 bundle 无需配置即可工作。后续的配置文件补丁可以将其行替换为如下值：

- 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]

边界

- 文件系统事件无法证明是谁做出了更改。通知会说明某个路径在会话已确认的文件系统观察之外发生了更改，而不是声称某个人类作者所为。
- 宿主监视不覆盖远程文件系统提供程序。先前观察到的远程目标仍会在 pre-step 时通过 ctx.fs.stat() 重新验证。
- 全新的 agent 从当前工作区状态开始；初始文件不会被报告为更改。
- 如果没有插件自有的持久清单存储，就无法进行精确的离线比较。因此，恢复时会发出保守的重新读取提醒。
- 监视器中断无法重建在中断期间发生的所有未观察到的宿主更改。插件会警告 agent 覆盖范围已降级，并要求其检查当前 Git 状态，然后重启监视器；先前观察到的目标会继续通过 ctx.fs 重新验证。
- 在最后一次 pre-step stat 之后发生的更改会在下一个边界被观察到。DSH 现有的文件系统观察策略仍为第一方写入和编辑提供原子性的过期版本保护；任意的 shell 写入会绕过该策略。