dsh-sidecar

Readme

# dsh-sidecar

[简体中文](README.md) | [English](README.en.md)

为 DeepSeek Harness 带来类似 Codex 的侧边上下文追问体验：选中 AI 回答中的任意片段，即可在选区旁直接发起追问；如果没有选区，也可以从回答末尾针对整条内容继续提问。

每个追问都在独立、持久化的 child Session 中进行，完整继承原回答结束前的上下文，却不会跳转、复制或污染主对话。你可以同时保留多个探索分支，随时关闭、恢复、重命名或归档。

## 它能解决什么

- **不中断主线**：验证细节、解释代码或探索替代方案时，主对话保持原样。
- **精确追问**：准确保留选中文字中的标点、换行和代码，避免重新复制粘贴。
- **持续分支**：侧边对话自动保存，同一回答可维护多个独立追问方向。
- **原生融合**：跟随 Harness 的中英文界面和明暗主题，并沿用原有权限边界。

`选中回答片段 → 点击选区旁“追问” → 在右侧继续对话 → 关闭后可随时恢复`

> 当前状态：`0.1.0-beta.0`，面向 `@deepseek-ai/dsh@0.1.0-rc.6`。核心运行路径曾通过真实安装与浏览器冒烟；当前自动化回归包含 87 项测试，并通过类型检查、构建和 Bundle（产物包）契约验证。Harness 仍处于预览期，后续 RC 可能带来破坏性变化。

## 已实现

- 选中当前 Assistant 回答中的文字后，立即在选区旁显示浮动“追问”按钮；回答末尾仍保留整条追问入口和已有分支数量。
- 只接受当前回答内部的有效选区，并精确保留标点、换行和代码；child 仍继承该回答结束前的完整上下文。
- 打开侧栏时不创建 Session；首次发送时才从回答结束边界 fork，并立即从普通对话列表隐藏，不切换当前主会话。
- 同一回答支持多个持久分支，可选择已有分支或显式新建分支。
- 可重命名当前分支；归档前需要二次确认，归档后自动切换到剩余分支。
- 在右侧抽屉显示 child 新增历史，继承内容不会重复显示。
- 直接向 child 发送追问、查看流式回答、工具摘要和回合错误。
- child 等待审批、回答或计划确认时给出提示，可显式打开原生子会话处理。
- 关闭按钮或 `Escape` 只收起抽屉，不删除 child；再次点击可恢复原问答。
- 打开时聚焦侧栏输入框，关闭后把焦点还给原“追问”按钮。
- 跟随 Harness 的中文/英文语言设置和明暗主题 token。
- 通过官方 `storageDomain` 持久保存最小 `childId -> anchor` 记录；普通 Harness fork 不会被误认成 sidecar。
- 系统隐藏的 sidecar 仍参与按钮计数和恢复；用户主动归档后才退出索引。
- 插件卸载时清理 slot、轮询和样式节点。

## 安装

当前 Beta 尚未发布到 npm。源码安装需要 Node.js `^22.19.0 || >=24.0.0`、pnpm `11.7.0` 和 DeepSeek Harness `0.1.0-rc.6`：

```powershell
git clone https://github.com/Srien11/dsh-sidecar.git
cd dsh-sidecar
pnpm install
pnpm build
dsh plugin --profile web add link:D:\absolute\path\to\dsh-sidecar
```

安装后重启 Web profile。npm 发布后，安装命令将简化为：

```sh
dsh plugin --profile web add dsh-sidecar
```

## 使用

1. 打开包含已完成 AI 回答的会话。
2. 如需针对具体片段，选中当前回答中的文字，然后点击选区旁立即出现的“追问”。
3. 如未选择文字，可点击回答尾部的“追问”，针对整条回答继续提问。
4. 补充问题后按 `Enter` 发送，按 `Shift+Enter` 换行。主会话保持选中且不会被追加消息。
5. 可在侧栏顶部选择、新建、重命名或归档分支。
6. 点击关闭按钮或按 `Escape` 收起，之后从同一回答再次打开。

## 隔离边界

本插件保证的是对话记录隔离：追问和回答只进入隐藏的 child Session，不出现在普通对话列表，也不会自动写回、截断、重命名或归档 parent Session。

工具副作用不隔离。child 与 parent 仍可能使用相同工作区、文件系统和外部服务；如果 child 获准调用写入型工具，这些效果对主工作区同样可见。请使用 Harness 权限模式控制工具访问。

## 实现方式

插件只使用 Harness `0.1.0-rc.6` 的公开接口：

- `sessions.fork` 创建持久 child；
- `sessions.history` 投影 child 历史；
- `SessionFace.prompt`、`cancel` 和 `rename` 驱动 child；
- `workspaces.archiveSession` 将 child 从普通会话分组中隐藏；
- `storageDomain` 和插件 RPC 通道持久化、读取分支锚点；
- `conversation.chat.assistant-actions` 注入回答操作；
- `shell.overlay` 承载抽屉。

当前 Client Runtime 一次只能 stage 一个原生 Session surface，因此抽屉使用轻量历史投影，不挂载第二个原生 Conversation surface，也不切换 `sessions.current`。

## 开发验证

```sh
pnpm typecheck
pnpm test
pnpm build
pnpm check:bundle
pnpm pack --dry-run
```

当前 87 项测试覆盖锚点存储/RPC、sidecar 身份与归档边界、fork 原子性、即时精确选区、多分支管理、焦点、双语词典、主题契约和 child transcript 投影。

上述命令只复用现有 `node_modules`。完整 Harness 安装与浏览器冒烟属于发布前的独立验收，不作为日常本地回归步骤。

## 文档

- [官方插件要求与曝光方式](docs/research/official-plugin-requirements.md)
- [产品规格](docs/product-spec.md)
- [并发 Session 技术决策](docs/decisions/0001-concurrent-session-surface.md)
- [锚点持久化技术决策](docs/decisions/0002-anchor-persistence.md)
- [真实双 Session 验证结果](docs/research/dual-session-spike-results.md)
- [详细实施计划（English）](docs/plans/2026-08-17-dsh-sidecar.md)
- [详细实施计划（中文）](docs/plans/2026-08-17-dsh-sidecar.zh.md)

## 许可证

[MIT](LICENSE)