yaodongH/dsh-better-summary

dsh-better-summary

DSH Web 插件：把对话流末尾的「本次产出」chip 行，替换为 Codex 风格的改动汇总卡片 —— 已编辑 N 个文件、总计与每文件 +新增 −删除 行数、折叠展开、按文件内联 diff、「在文件夹中显示」。行数统计不依赖 git，非 git 目录同样精确可用。

状态：v1 已实现并通过全部验证（typecheck / 143 项单元与组件测试 / 5 条 E2E lane）。
兼容性：当前版本 0.2.0 要求 DSH ≥ 0.1.6-alpha.2 —— 装到更早的宿主上，客户端半边会在装载期直接报错，卡片不出现（详见兼容性，不是静默降级）。
设计与决策记录见 docs/design.md。

效果

上图为真实运行截图（主题跟随 DSH，此处为深色）。数据来自 E2E 的 mock 场景：新建 a.txt 与 12 行的
b.txt，再把 a.txt 里的 beta 改成 BETA，故逐文件 +3 −1 / +12 −0、合计 +15 −1。图中两个文件
的 +N 位宽不同（2 位 vs 3 位）却与头部合计落在同一组列上；字号默认与 DSH 正文一致，可在设置里固定为具体 px。

核心特性

- 不依赖 git：统计来自每轮成功工具结果的 applied diff（write/edit 写入 tool result meta.diffs 并随会话日志持久化），新建文件由工具参数补齐。非 git 目录、临时目录与 git 仓库表现一致。
- 接管而非入侵：以 DSH 自带产出行所在的单元格 id 注册进 conversation.chat.turnTail（list 槽，priority -2），顶替自带的 ui-deliverables 行（0）与 dsh-better-sidebar 的 chip 行（-1）；关闭开关或卸载即恢复原样。不修改 DSH 任何源码。
- 与显示模式无关：自己注册 ConversationNodeDefinition 折叠原始事件（紧凑显示下工具节点会被折叠，读渲染节点会丢数据）；不发布任何视图节点。
- 可扩展的数据推导：变更来源三层抽象 + 策略注册表 + ctx.betterSummary 服务 —— 接入新工具只需注册一个来源，不改卡片。
- 设置即时生效：collapsedRows、inlineDiffMaxLines、folderReveal、fontSize、priority、enabled 在 DSH 设置的独立页面（「任务产出」）中调整，保存即生效，无需刷新。
- 「在文件夹中显示」：由本插件自研（Host 侧 argv 数组原生打开，不经过 shell）；带 WSL 分支（wslpath + explorer.exe /select, / Invoke-Item），并且打开失败会说原因，不再静默。

兼容性

| 插件版本 | 适用 DSH | 该版本 DSH 上 conversation.chat.turnTail 的槽契约 |
|---|---|---|
| 0.2.0（当前） | ≥ 0.1.6-alpha.2 | list 槽：条目按 id 划分单元格，同格只渲染优先级最低的一个 |
| 0.1.1 | 0.1.5-alpha.1 | chain 槽：条目靠 select 座位路由 |

DSH 0.1.6-alpha.2 把这个槽从 chain 换成 list，注册形态随之改变（0.2.0 注册 id，不再注册 select）。
两边都装错的症状相同：客户端半边在装载期抛错，插件不生效、卡片不出现（DSH 自带产出行照常显示），
日志里是槽注册表给出的明确原因 —— 不是渲染成空卡片，也不会静默降级。下面两条都是真实挂载的报错原文：

0.2.0 装到 DSH 0.1.5 及更早：
chain slot "conversation.chat.turnTail" requires options.select

0.1.1 装到 DSH 0.1.6 及更新：
list slot "conversation.chat.turnTail" requires options.id

package.json 用 engines.dsh 声明了这条下限。DSH 自身不读取也不校验该字段，它只是把版本要求
随清单一起暴露出来；真正的依据是上表的对应关系。

安装

插件以 profile bundle 方式挂载。三种渠道：

官方 CLI（推荐）

在 DSH checkout 内（本机 dsh 不在 PATH 上时）：
pnpm -C  dsh plugin --profile web add file:/dsh-better-summary-0.2.0.tgz

该命令会在 profile 目录里执行 pnpm add，并依据包的 dsh.bundle.patch 自动把 dsh-better-summary 追加进 dsh.profile.bundles。

从 GitHub 安装（git 依赖）

dsh plugin --profile web add github:yaodongH/dsh-better-summary
等价写法（github: 是 pnpm 的托管仓库简写）：
dsh plugin --profile web add git+https://github.com/yaodongH/dsh-better-summary

这条路要多一步放行。lib/ 不在仓库里（被 gitignore），靠包的 prepare 钩子在安装时现场构建；而
pnpm 10 默认不执行依赖的构建脚本，不放行会被明确拒绝安装（不会装出一个缺 lib/ 的坏包）：

ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED
The git-hosted package "dsh-better-summary@0.2.0" needs to execute build scripts
但不在 "onlyBuiltDependencies" 允许列表中。

在 profile 的 pnpm-workspace.yaml（即 ~/.dsh/profiles/web/pnpm-workspace.yaml）里放行：

allowBuilds:
dsh-better-summary: true

onlyBuiltDependencies: [dsh-better-summary] 是等价写法（pnpm 报错文案里给的就是这个键）。放行后
安装会从源码构建出 lib/index.js、lib/client.js 与类型声明；pnpm 会缓存构建结果，换成新 commit 才会重跑。

安装输出里可能出现 missing peer @deepseek-ai/cordis / missing peer react 的警告：profile 的
pnpm-workspace.yaml 设了 autoInstallPeers: false，而这两个 peer 由 DSH 应用本身提供，不需要在
profile 里再声明一份。判定安装成功的依据是 dsh.profile.bundles 里出现 dsh-better-summary。

手工编辑 profile

1. pnpm pack 产出 tarball（prepack 钩子会自动先构建）；
2. 编辑 ~/.dsh/profiles/web/package.json：
- dependencies 增加 "dsh-better-summary": "file://dsh-better-summary-0.2.0.tgz"
- dsh.profile.bundles 数组追加 "dsh-better-summary"
3. pnpm install（在 ~/.dsh/profiles/web 内）；
4. 重启 dsh web。

回滚

从 dsh.profile.bundles 移除该包（或停用插件行）后重启，原有产出行立即回归；DSH 源码零改动。

配置

| 配置项 | 位置 | 默认 | 说明 |
|---|---|---|---|
| 折叠行数 | DSH 设置 → 任务产出 | 3 | 折叠时显示的文件行数（1–20） |
| 内联差异行数上限 | 同上 | 200 | 单文件 diff 最多渲染行数（20–2000） |
| 文件夹按钮 | 同上 | 图标加文字 | 图标加文字 / 仅图标 / 隐藏 |
| 卡片字号 | 同上 | 跟随正文 | 跟随正文（跟随 DSH 正文字号设置）或固定 11–18px |
| 槽位优先级 | 同上（高级） | -2 | 同一单元格内越小越优先渲染；自带侧栏产出行用 -1 |
| 启用 | 同上 | 开 | 关闭后恢复 DSH 原有产出行 |
| opener | cordis.patch.yml（部署级） | 平台默认 | 覆盖「在文件夹中显示」的命令，参数中 {path} 为打开目标 |

部署级 opener 覆盖示例（例如改用 nautilus，或用替身脚本记录 argv）：

- id: better-summary
config:
opener:
command: /usr/bin/nautilus
args: ['--select', '{path}']

平台默认：Linux xdg-open ；macOS open -R ；Windows explorer.exe /select,。

工作原理

1. 数据：本插件注册一个 ConversationNodeDefinition（kind better-summary），只折叠 turn/start、tool/call 与 append 语义的 tool/result，把成功结果的 {name, argsRaw, meta} 按日志顺序发布到 Turn 数据上；同时读取 DSH 自带的产出清单（Turn 数据 deliverables）作为文件顺序与兜底。
2. 推导：卡片用「变更来源」选举把这些数据变成每文件 +a −d 与 diff 分块 —— 内置两个来源：
- dsh.tool-result-diff-meta（优先级 100）：读工具自报的 applied diff（含 3 行上下文的 hunk）；
- dsh.tool-call-args（优先级 50）：新建文件时工具没有前像（meta.diffs 为空），由调用参数补齐。
3. 渲染：卡片在轮次尾部渲染；「审查」展开全部文件的内联 diff；行点击走 DSH 既有的文件打开漏斗。
4. 宿主：唯一的 Host 调用是「在文件夹中显示」——回环校验 + 路径解析 + argv 数组 spawn，不经过 shell。

「在文件夹中显示」的打开规则

| 平台 | 单文件（select） | 多文件 / 目录（folder） |
|---|---|---|
| macOS | open -R  | open  |
| Windows | explorer.exe /select, | explorer.exe  |
| WSL | wslpath -w → explorer.exe /select, | wslpath -w → powershell.exe Invoke-Item -LiteralPath '' |
| 桌面 Linux | xdg-open （Linux 无通用 select 协议） | xdg-open  |

- WSL 专门分支：WSL 的 Linux 侧通常没有桌面，xdg-open 会「启动成功、随即以退出码 3 失败」，表现为点了没反应；因此 WSL 一律把路径交给 Windows 桌面（wslpath -w 翻译，目录用 Invoke-Item——直接 explorer.exe  不能可靠唤起窗口，与 DSH 自带 path opener 同款结论）。
- 成功判据：进程没启动、或在 2 秒窗口内以非零码退出都算失败（explorer.exe 除外，它成功时也返回 1）；失败时卡片显示原因（例如 "xdg-open" exited with 3: no method available），不再静默。
- 路径解析：绝对路径直接采纳（产出常在 /tmp 或兄弟仓库），相对路径相对会话工作目录解析并禁止 .. 逃逸；一个有效路径都没有时回落到工作目录本身。

扩展：接入新工具

新工具的 result 若携带可识别 meta，或可从未变更的调用参数推导，注册一个来源即可：

const betterSummary = ctx.get('betterSummary')   // 客户端上下文
const dispose = betterSummary.registerNodeSource({
id: 'example.apply-patch',
priority: 60,
match: node => node.kind === 'tool-result' && node.call?.name === 'apply_patch',
extract: node => [{ path: 'x.ts', counts: { added: 3, removed: 1 } }],
})

ctx.betterSummary 提供 registerNodeSource / registerTurnSource / listSources / features / version；Host 侧另有 registerWorkspaceSource 注册位（留给后续 git 补漏等实现）。当前生效的来源可在设置页只读列表中查看。

已知限制（v1）

- 只覆盖 write / edit / str_replace_editor（与 DSH 自带产出清单口径一致）；bash、代码生成器等非工具途径改动的文件不在清单内。
- str_replace_editor 的 str_replace 为片段级计数，insert 只计新增行，view 不产出。
- 无撤销（计划：反向应用 hunk + staleness 校验 + 备份）。
- 外部直接编辑 settings.yaml 后，已打开的页面不会即时反映（设置页挂载或写入前会重新读取）。
- 打开文件夹依赖系统里有可用的文件管理器命令；命令不存在时卡片给出一次性提示，不抛异常。

开发

pnpm install
pnpm build          # Host ESM + Client bundle + 类型声明
pnpm typecheck      # tsc --noEmit
pnpm test           # 单元与组件测试（vitest）
pnpm test:e2e       # 构建 → pack → 真实挂载 + Playwright（L1–L4，无需 API key）
pnpm test:e2e:real  # 追加 L5 真实模型 lane（只读复用本机 ~/.dsh 的模型配置与凭据）
pnpm pack           # 产出可安装 tarball（prepack 钩子自动先构建，不会打出缺 lib/ 的空包）

E2E lane

| lane | 触发 | 验证内容 |
|---|---|---|
| L1 挂载冒烟 | test:e2e | 官方渠道真实挂载；外壳无 pageerror/console error/坏响应；设置导航出现「任务产出」且正文控件可见（同时证明 Host 与 Client 双侧生效） |
| L2 卡片与内联 diff | 同上 | mock 模型跑真实工具链；断言文件数、总计 +15 −1、逐文件数字、两段 hunk 的 6 行内联 diff、审查模式、行点击；另断言字号跟随正文字号、计数列跨行对齐、头部合计与行计数逐列同宽同右缘，以及两个计数共享同一条基线（注入行盒扰动模拟 − 的字体回退，扰动前后基线都必须重合） |
| L3 设置动态生效 | 同上 | 设置页改折叠行数、文件夹按钮与字号后，不刷新页面卡片即时变化；再改回并断言双向持久化 |
| L4 在文件夹中显示 | 同上 | profile 覆盖 opener 指向替身脚本，断言宿主把正确目录交给了操作系统；再把替身换成目录制造 spawn 失败，断言路由返回 5xx 且卡片给出提示 |
| L5 真实模型端到端 | test:e2e:real | 只读复制本机 ~/.dsh 的 settings.yaml/.credentials.yaml/.env 到 scratch，用真实 provider 与凭据在非 git 工作区跑一轮，断言卡片与真实统计 |

lane 编排（scripts/e2e-common.sh）：解析 dsh 命令 → 建 scratch DSH_HOME → dsh plugin add 挂载 → 播种设置 → 启动 dsh web --port 0 并解析地址 → Playwright。全程只写 scratch 目录，退出即删。

共存验证：E2E_EXTRA_PLUGINS 可挂载额外插件 tarball（冒号分隔），用于在真实插件组合下验证同一单元格的遮蔽顺序：

E2E_EXTRA_PLUGINS=/path/to/dsh-better-sidebar-0.20.0.tgz pnpm test:e2e
→ 卡片仍以 priority -2 渲染，统计与内联 diff 全部正确

list 槽按 id 划分单元格、每格只渲染优先级最低的一个条目，因此本包与
dsh-better-sidebar（priority -1）不会并排出现两行：-2 恒胜出，后者只是被遮蔽
（既占着内存也不渲染）。两者优先级相等时 register() 会在装载期抛错
（同格同优先级被视为配置冲突），共存时请保持数值不同。

许可证

MIT