0 Fork 0

Files

T

creatixchu f937f4e23b feat(web): record turn file changes with git snapshots and render the changed-files card

Add the dsh-workspace-changes Host plugin that snapshots the working tree at
turn start and end through a private git index, diffs the two trees, folds in
file-tool hunks for ignored and out-of-tree files, and appends a log-only
workspace/changes event. The Web deliverables plugin renders that event as the
changed-files card in place of the mutation-call row, with default-app and
common-folder opening through a new authenticated route.

2026-09-11 16:47:40 +08:00

6.2 KiB

Raw Blame History

description, kind

description	kind
用 git 工作树快照把每个顶层轮次改动的文件记录为持久的 workspace/changes Session 事件；配置、仓库分档与覆盖规则。	package-reference

@deepseek-ai/dsh-workspace-changes

English | 中文

概述

本插件把每个顶层轮次改动了哪些文件、每个文件的增删行数记录为 workspace/changes Session 事件。它在轮次开始和结束时用 git 对工作树做快照，比较两次快照，并补上 git 覆盖不到的文件工具编辑。Web 的改动文件卡片渲染该事件；模型看不到它。

使用本包

正式提供的 Web bundle 挂载本插件。任何具备 subprocess 能力且 Host 上有 git 可执行文件的组合都可以挂载它：

- name: '@deepseek-ai/dsh-workspace-changes'
  config:
    maxFiles: 500

字段	默认值	含义
`dshHome`	`$DSH_HOME`，其次 `~/.dsh`	Harness home，其 `workspace-changes/` 目录存放影子仓库
`timeoutMs`	`30000`	单条 git 命令允许运行的毫秒数，超时则放弃本轮记录
`outputMaxBytes`	`8388608`	每条命令保留的 git 输出字节数，diff 列表更大时放弃本轮记录
`maxFiles`	`500`	单个事件携带的最大文件数；`total` 仍报告完整数量
`shadowExcludes`	`.git/`、`.dsh/`、`node_modules/`、构建与缓存目录	影子仓库的 `info/exclude` 模式

每个有工作目录且不是子代理来源的 Session 都会被记录；子代理 Session 不记录。工作目录位于 git 仓库内时，快照通过私有 index 写入该仓库的对象库，仓库自己的 index、工作树和 ref 保持不变，用户此前未提交的改动也不会进入摘要。工作目录不在任何仓库内时，快照写入 Harness home 下的影子仓库，其工作树就是该工作目录；shadowExcludes 模式代替缺失的 .gitignore，位于工作目录内的 Harness home 会被自动排除。工作目录内的嵌套仓库和 submodule 记录为 gitlink，其内部改动不会出现。没有 git 时——或者 macOS 上只有 /usr/bin/git 的开发者工具桩程序时——本插件不记录任何内容，并记录一次日志。

文件工具改动但快照覆盖不到的文件，由这些工具随结果持久化的 hunk 补入：匹配忽略模式的文件，以及仓库或影子工作树之外的文件。/tmp 与平台临时目录下的文件被排除，除非它们位于工作目录内。这些文件的行数按记录的 hunk 累加，因此同一轮内对一个文件的重复编辑可能把一行计算多次。快照覆盖范围之外通过 shell 命令做出的改动不会被记录。

每个文件携带持久的 path——位于工作目录内时为相对路径，否则为绝对路径——以及用于排序和标签的 display 路径：相对路径，仓库内位于工作目录之上的文件为 ../ 路径，家目录下的文件为 ~ 路径，其余为绝对路径。文件按 display 的码元顺序排序，因此上级路径和绝对路径排在工作目录自身文件之前。事件还携带两次快照的 tree id。

理解实现

实现细节——点击展开

每个 Session 一个 TurnRecorder，串行化其 git 工作。turn/start 排入基线：rev-parse 定位仓库或初始化影子仓库，然后以持久 index 为种子在临时 index 上执行 add --all 与 write-tree 得到 tree id。每次 tools/pre-execute 都等待该队列，因此没有修改能先于其基线发生。tool/result 事件收集文件工具的 hunk。agent/turn-stopping 在轮内记录：第二次快照、两棵树之间的 diff-tree -r -M --numstat、对工作树内 hunk 路径的 check-ignore，以及追加事件。turn/end 仅在最后一次记录之后仍有工具结果结束时再次记录，这覆盖了中止、失败和被转向的轮次；早先记录之后的空列表会取代它。影子仓库保留刷新后的 index 供下次快照使用；真实仓库的 index 只读取。

git 通过 subprocess 能力运行，使用净化后的环境、GIT_TERMINAL_PROMPT=0、GIT_OPTIONAL_LOCKS=0、配置的超时与有界输出。任何步骤失败都会放弃本轮记录并给出警告；下一轮重新开始。Session 释放与插件释放会中止排队的工作。

运行时不变式： 不发布伴生入口。事件监听归 effect 所有，Session 日志拥有记录的摘要，git 对象库拥有快照树；没有独立观察会与它们分歧。

进一步探索

Web 产出物——渲染该事件并打开其文件的改动文件卡片。
子进程能力——git 运行所经过的接缝。
本轮改动文件卡片决策——快照设计、覆盖规则与被否决的备选方案。

模型体验

无，因为记录器只追加一条仅写日志、只有客户端读取的 workspace/changes 事件，不注册任何面向模型的内容。

KV Cache 影响

这里的内容不会进入模型请求，因此不影响提供方缓存复用。

已知限制与延期工作

快照树是无引用对象，仓库的垃圾回收会在其过期期限后删除它们；记录的计数保留，而将来做整文件对比所需的树不会保留。
用户在轮次进行中自己做的编辑会被算到该轮。
快照覆盖范围之外的文件按 hunk 累加计数，不是首尾对比，且只覆盖文件工具。
Windows 路径在 path 中保留原生分隔符；display 始终用斜杠分隔。

开发备注

维护者的工作上下文——点击展开

无。

6.2 KiB Raw Blame History