前言¶
在 DeepSeek Harness（DSH）里跑智能体时，模型会通过 edit、write、apply_patch 等工具改工作区文件。宿主默认能展示工具调用，但若缺少逐次修改的 diff、轮级汇总和可撤销能力，开发者很难像在用 GitHub Copilot 那样「改一处看一处、整轮审一遍、不满意就撤」。
社区里已有 change-review、diff-approval、file-changes 等插件，各自覆盖追踪、审批或轮末展示的一部分。dsh-copilot-diff 由 huieric 维护，定位为 Copilot 风格的内联 diff + 右侧 Changes 审阅，并带 Keep／Undo、轮前 Restore Checkpoint 与命令行改写保护。它不调用模型，只做变更观察与 UI。
下面介绍插件定位、能力、安装与日常用法；事实以 GitHub 仓库 README 为准（当前 npm 包版本 0.8.3，MIT 许可证）。
这是什么¶
dsh-copilot-diff 是一个 DSH Web 客户端插件（platform: web）。服务端为纯 ESM，客户端为手写 module-loader bundle，零依赖、零构建。
它解决三类问题：
- 每次文件修改都有可读的 diff：跟在真实工具调用行后面就地展开，或进右侧 Changes 做整文件审阅。
- 轮级视角：一轮结束有
+A −R统计、文件卡或紧凑 chip，并可 保留、撤销 整轮或单条记录。 - 工作区一致性：默认拦截
sed -i、重定向等静默改写，引导模型走文件工具，保证 diff 能挂在对应调用上；轮开始前可 恢复检查点 把磁盘回到该轮之前（在快照覆盖范围内）。
文件工具的逐调用 diff 仍由宿主保留；本插件另做按轮工作区快照，识别脚本、sed、Python replace 等命令行造成的磁盘变化，并提供持久化检查点。超出快照范围或未覆盖的文件不会假装能恢复。
核心功能¶
修改追踪¶
插件观察以下工具（一次调用一条独立记录；一次改多文件时按文件各记一条）：
- 常规：
edit/write/apply_patch - 编辑器风格：
replace_string_in_file、multi_replace_string_in_file、edit_file、multi_edit、create_file、write_to_file
对「只换字符串、结果里没有前后全文」的调用：调用前快照目标文件，调用后再读一遍，用两份文本算 diff。拿不到快照时（例如导入的历史会话）退化为用参数里的 oldString / newString 画片段。
就地 diff 与 Changes 面板¶
| 位置 | 行为 |
|---|---|
| 聊天内工具行 | diff 长在对应编辑调用处，默认收起；点行首 > 就地展开；右侧 +A −R 可点开右侧审阅并定位到该次修改 |
| 右侧 Changes | 0.8.0 起类似 Copilot「Response File Changes」：整轮所有文件 diff 平铺一列，段头文件名 + 目录 + +A −R 滚动吸顶；可切统一／并排、展开 ⋯ N 行未改动；顶部整轮 保留／撤销 |
| 会话侧栏 | 每个会话行下方显示该会话累计 +A −R（0.8.2 起颜色在面板外也有完整绿／红回退链） |
大文件 diff 按行虚拟化（约 22px 行高），未改动区超过 40 行先折叠，可继续展开。
Keep、Undo 与检查点¶
- 单次撤销：每条记录独立 Undo，只回写该次编辑替换掉的文本；若磁盘已不等于该次的
after，会拒绝并提示先撤较新的那次。 - 轮间边界（0.8.1 起）：两轮之间单独一行（默认透明，悬停淡入），提供 恢复检查点 与 分叉（在整轮末尾 seq 开新会话并切换）。
- Restore Checkpoint：确认后把文件恢复到该轮开始前（含之后轮次已记录修改范围内），聊天记录保留；0.8.3 起边界行排在用量统计行下一行，一轮只留一张文件卡（归宿主
@deepseek-ai/dsh-client-ui-deliverables，保留／撤销仍在右侧审阅面板）。
命令行改写保护¶
默认在执行前拦截：sed -i、perl -i、写文件的 Python heredoc、tee／> 重定向、dd、truncate、git apply/checkout/restore、patch 等；node_modules、dist、build、output、/tmp 等目录放行。命中时返回明确错误，引导改用 edit / write / apply_patch。
历史会话¶
装上插件前已发生的修改，可在打开旧会话时由服务端从 session.v4.jsonl(.zstd) 重放 tool/call + tool/result 补 diff（标为「已保留」，不提供诚实回滚意义上的撤销）。全量回填可运行：
node tools/backfill.mjs
与其它审阅插件的关系¶
可与 diff-approval 同时安装：后者管改前改后审批，本插件管改完后的摊开审阅与逐条撤回。两者若占同一 tool.call.toolview key，后注册的生效；只需其一可卸载另一个。能力对比表见仓库 README「与现有三个插件的关系」一节。
安装与启用¶
推荐从 npm 安装到 Web profile：
dsh plugin --profile web add dsh-copilot-diff
也可从 GitHub 添加（需 pnpm 支持 git 依赖）：
dsh plugin --profile web add github:huieric/dsh-copilot-diff
安装后重启 Web：
dsh web
插件自带 cordis.patch.yml（dsh.bundle.patch），装入 profile 后会自动插入插件行，一般无需手改配置。
装不上或装完不生效¶
- pnpm 锁目录无写权限（容器或
$XDG_RUNTIME_DIR不可写）：
XDG_RUNTIME_DIR="$HOME/.run" dsh plugin --profile web add dsh-copilot-diff
-
启动摘要里插件
did not activate：按摘要原因处理；0.1.0曾缺webServer注入，0.1.1已修复，升级到当前版即可。 -
与宿主 UI 插件 priority 冲突（如装在
0.2.2-rc.1上整包加载失败）：0.8.3已将tool.call.toolview与conversation.chat.node的turn-process注册为priority: -1，避免与宿主file-mutation-toolview等同 priority 占位冲突。
完全不依赖 pnpm 时，可用仓库内脚本（复制文件 + 注册 bundle）：
./scripts/install-local.sh
要求 Node >=20.11（见 package.json engines）。
典型用法¶
安装并 dsh web 后，在 Web 里正常让智能体改文件即可，无需额外配置项。
轮次内：看到 编辑 … 1KB +22 −0 一类行时，点行首 > 展开就地 diff；点右侧 +A −R 或文件名，右侧 Changes 滚动到该次修改。
轮次末：在「已完成 … 步，用时 … +A −R」或文件卡上使用 审查 打开整轮 Changes；用 保留／撤销 处理整轮，或在面板里对单文件 Keep／Undo。
两轮之间：鼠标移到轮间缝上，使用 恢复检查点 回滚磁盘，或 分叉 从该轮末尾开新会话。
本地验证 UI（合成数据，不含真实会话）：
npm test
node tools/preview.mjs > docs/preview.html
浏览器打开 docs/preview.html 可交互预览组件；README 中 docs/screenshots/ 下有 overview、inline、expanded 等示意图。
适用场景与注意¶
适合：长期在 DSH Web 里做代码类智能体开发、希望 diff 与 Copilot 审阅习惯对齐、需要逐次撤销或轮前检查点的用户。
注意：
- 插件以当前 dsh 进程权限 读写工作区；安装前请浏览源码与 MIT 许可证，确认符合你的安全策略。
- 检查点与撤销依赖快照覆盖范围；README 明确超出范围的文件不会假装可恢复。
- 与
dsh-chat-import导入的 Copilot 历史类似，无服务端记录时 diff 可能仅由调用参数绘制。 - 社区目录 skillhub.cn 插件页 与 GitHub 为独立来源，与 DeepSeek／幻方无官方从属关系；生态理念是「一切皆插件」。
结尾¶
dsh-copilot-diff 把「每次编辑一行 diff、右侧整轮 Changes、Keep／Undo、恢复检查点」接到 DSH Web 上，并默认挡住容易绕过工具管线的命令行改写。若你已在用 DSH 做文件级智能体开发，可用官方命令装进 web profile，按 Copilot 习惯审阅每一轮改动。
- 目录页：https://www.skillhub.cn/plugins/huieric/dsh-copilot-diff
- 源码与文档：https://github.com/huieric/dsh-copilot-diff
