旁问浮层 andrewhmir/dsh-btw

@andrewhmir/dsh-btw — 给 DSH Web GUI 的临时 /btw 旁问

DeepSeek Harness（DSH）的非官方社区插件。它给 Web GUI 输入框加了一个手势：

/btw how does the compaction checkpoint interact with the surface?

回答会以流式方式显示在应用上方的浮层里。关掉浮层后，会话里不留痕迹：问题和回答都不会写进对话记录，不会渲染成聊天行，也不会进入模型下一轮看到的内容。

它和子代理正好相反：子代理拿到完整工具面和一个空上下文；/btw 拿到完整对话上下文，没有工具。

/btw 做什么

| 属性 | 行为 |
| 调用方式 | 会话进行中，在输入框里输入 /btw <question>；也可以从 / 菜单里选 |
| 上下文 | 当前会话已提交的完整对话 |
| 工具 | 无 —— 请求不带任何工具 schema，也不带工具历史 |
| 回答 | 流式显示在应用框架上方的浮层里 |
| 关闭 | Space、Enter 或 Escape（也可以点关闭按钮 / 背景） |
| 持久化 | 无 —— 这轮问答不会进入会话历史 |
| 并发 | 主回合正在流式输出时也能用，且不会打断它 |
| 形态 | 单次问答；没有后续回合 |
| 模型 | 会话路由到的服务商 / 模型 / 推理强度 |
| 开销 | 一次无工具调用，消息前缀与父请求的前缀相同，因此能复用服务商的提示词缓存 |

要求

- DSH >= 0.2.0-rc.2，带 Web GUI（dsh web）。
- Node.js 22 或更新版本，仅验证脚本需要；插件本身跑在 harness 进程里。

安装

这个包是一个 DSH bundle：它声明了 dsh.bundle.patch，以及一行客户端 + 宿主插件（id: btw）。把它装进你运行的配置档，然后重启 dsh web。

从插件市场安装

启用 DSH 的自定义插件市场，添加一个列出这个包的社区索引（仓库带了 dsh-plugin GitHub topic，索引可以据此发现它），然后在 Discover 标签页里安装 @andrewhmir/dsh-btw。

用智能体安装

plugin_manager install_bundle target: @andrewhmir/dsh-btw@0.1.2

从本地检出安装

plugin_manager install_bundle target: /absolute/path/to/dsh-btw

安装之后

重启 dsh web。 正在运行的进程还持有安装前的模块图；重启才会加载新的宿主部分。然后确认组合结果：

dsh --profile web --dump-config

预期：退出码 0，并且有一行 id: btw / name: @andrewhmir/dsh-btw，没有 not found、unknown key 或 cannot resolve 这类行。

只改 client.js 时，harness 的客户端 HMR 会在保存后拾取重新构建的文件；改宿主部分需要重启。

工作原理

- ui-commands 认领会话宿主命令目录里存在的斜杠命令。/btw 故意不注册这样的命令：宿主命令的结果会持久记录（command/run / command/done），并进入会话历史。
- 改为由插件的客户端部分注册自己的 '/' 输入触发源。在 composer 裁决阶段，它会在任何宿主命令运行之前认领 /btw <question>，打开浮层，并调用插件自己的回环路由 POST /btw/ask。
- 宿主部分会为会话解析出当前活跃的智能体，用 Session.deriveMessages() 快照出模型可见的精确历史，追加一条携带附带问题的冻结用户消息，然后发起一次 ctx.llm.stream() 调用，不带工具、不带工具历史、也不带单独的系统提示词。由于消息列表就是父请求的前缀加一条尾部消息，服务商的提示词缓存得以复用。
- 回答以换行分隔的 JSON 流式返回，通过 shell 共享的 MarkdownText 组件渲染 Markdown（如果旧版 shell 没有注入该组件，则回退为纯文本），并显示在 shell.overlay 面板中。按 Space/Enter/Escape 中止请求并关闭面板。
- 在回合进行中取得的快照，可能以一条助手工具调用结尾，而它的 tool/result 尚未提交。宿主在重放历史前会裁掉这个尾部未完成的步骤，因此 /btw 会以最后一个完成的工具步骤时的对话状态作答，而不是让服务商拒绝请求（「tool calls need immediate results」）。
- 这条路径上没有任何环节调用 session.append、命令注册表、智能体循环或收件箱——这正是该交互短暂易逝的原因。

设计上保证私密

短暂易逝是一项契约，不是渲染上的选择：

- 问题和回答从不写入会话日志，因此不会出现在转录记录、token 计量器的会话历史或任何导出中；
- 宿主路由从不触碰 session.append、命令注册表、智能体循环或收件箱；
- 唯一持久的影响是服务商对一次调用的计费。

这一点已用真实会话日志验证：test/e2e/ephemerality-check.mjs 会解码测试 home 目录下的每个 session.v.jsonl.zstd，如果问题或回答的任何部分出现在持久化事件中，就判定失败。对照运行证明扫描器能检出确实被合法持久化的文本。两个受支持的 harness 版本的结果都记录在 docs/VERIFICATION.md 中。

配置

插件行接受两个可选值；两者都有安全默认值，读取时不经过 Config schema：

- insert:
- id: btw
name: '@andrewhmir/dsh-btw'
config:
maxTokens: 1200 # completion cap for one side answer (default 1200)
timeoutMs: 120000 # hard deadline for one side call (default 120000)

问题长度上限为 4000 字符；请求体上限为 32 KiB。

已知限制

- 不包含进行中的部分助手文本。 快照读取的是已提交的会话表面；主回合正在流式输出时，当前的助手消息尚未提交。/btw 看到的是最后一次已提交事件时的对话。

- 会话日志成本面板里看不到。 临时调用不会在会话日志留下痕迹；这类调用的计费以服务商账单为准。
- 仅限 Web GUI。 宿主路由是通用的，但调用和浮层属于客户端 Web 功能。
- 浮层文案为英文。 展示元数据提供英文和中文两版；本版本的浮层内文案为英文。
- 未来宿主若提供 btw 命令，会遮蔽本插件。 宿主目录先于插件来源裁决；如果未来 harness 版本提供同名宿主命令，/btw 将改为执行该命令。
- 单次调用。 浮层内没有后续轮次。

兼容性

engines.dsh 声明 >=0.2.0-rc.2。两个标签均在干净环境安装中验证过，该环境只含官方 bundle 加本插件：

| Harness | 结果 |
| 0.2.0-rc.2（npm latest） | 浮层 + 流式回答、大写 /BTW、Markdown、Escape/Space/Enter 关闭、热缓存 |
| 0.2.1-rc.2（npm next） | 上述全部，外加流中并发（工具调用期间 4/4 回答）和严格临时性 |

测量数据与确切命令见 docs/VERIFICATION.md。

验证

在本目录下执行：

node --test "test/.test.mjs"
node tools/build-client.mjs --check
node --check client.js

干净环境与浏览器测试装置位于 test/e2e/，文档也在那里。它不会随发布包分发：

- clean-room.ps1 构建全新的 DSH home，只含官方 bundle 加本插件，写入工作区状态，组合、启动并打印 URL；
- first-run.mjs 关闭首次运行预览提示，并验证输入框可接受文本；
- cdp-e2e.mjs 通过 DevTools 协议驱动真实 GUI（probe、full、dismiss-keys、mid-stream）；
- ephemerality-check.mjs 断言没有任何交互进入会话日志。

开发

node tools/build-client.mjs # regenerate client.js from src/client/.mjs
node tools/build-client.mjs --check # fail when client.js is stale
node --test "test/.test.mjs"

client.js 是生成的经典脚本，以包名向 harness 的模块加载器注册自身。src/client/ 下的源模块是纯 ESM，只使用相对 .mjs 导入；宿主部分位于 src/host/，通过 harness 服务（webServer、llm、agents）注入。

独立性与许可

这是非官方社区插件，与 DeepSeek 无隶属关系。它独立实现 /btw 这一想法，未复用其他同名社区包（dsh-btw@0.0.3 和 @michengai/dsh-btw）的代码。上游 DSH 目前不接受外部 pull request，因此以独立包分发；仓库带有 dsh-plugin 话题，方便社区插件索引发现它。

MIT 协议。见 LICENSE。