@wannanbigpig/dsh-sidebar

Readme

# DSH Sidebar Workbench

一个为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 最新源码补齐工程能力的外置插件（Bundle），无需修改宿主源码。插件直接融合进宿主原生 Right Sidebar、文件资源标签和底部 Dock：复用宿主已有的文件树、标签页、拆分/悬浮布局，只补充可编辑高亮、Git Review/提交、Worktree 和交互式 PTY。所有项目操作以当前 Session 的 `cwd` 为边界。

npm 包名：`@wannanbigpig/dsh-sidebar`。

宿主兼容性、交互修复和后续优化记录见 [宿主对齐检查](docs/host-alignment-2026-09-05.md)。

## 界面预览

以下截图展示插件在示例项目中的实际界面；图中的项目名、文件内容、分支和改动统计仅为演示。

<table>
  <tr>
    <td width="50%"><img src="https://raw.githubusercontent.com/wannanbigpig/dsh-sidebar/master/docs/images/screenshots/workbench-overview.png" alt="宿主开始页展示工作区文件、审查与终端入口"><br><sub><b>原生工作台入口</b>：文件、Review 与 Terminal 直接加入宿主 Guide，不额外提供第二套工作台或侧栏。</sub></td>
    <td width="50%"><img src="https://raw.githubusercontent.com/wannanbigpig/dsh-sidebar/master/docs/images/screenshots/git-tools.png" alt="会话右上角的 Git 工具卡展示改动统计、本地工作树和当前分支"><br><sub><b>Git 工具卡</b>：在当前会话列查看改动行数、工作树与分支，并进入审查或提交/推送流程。</sub></td>
  </tr>
  <tr>
    <td width="50%"><img src="https://raw.githubusercontent.com/wannanbigpig/dsh-sidebar/master/docs/images/screenshots/code-review.png" alt="审查视图展示未提交改动、行级 diff 和可筛选的变更文件树"><br><sub><b>代码审查</b>：支持范围选择、逐文件增删统计、行级 diff、上下文折叠和文件树筛选定位。</sub></td>
    <td width="50%"><img src="https://raw.githubusercontent.com/wannanbigpig/dsh-sidebar/master/docs/images/screenshots/file-editor.png" alt="原生文件标签内展示路径面包屑、未保存圆点和代码编辑器"><br><sub><b>文件浏览与编辑</b>：从宿主 Files 打开文件，在原生标签中获得路径面包屑、CodeMirror 6 编辑和未保存状态提示。</sub></td>
  </tr>
  <tr>
    <td colspan="2" align="center"><img width="70%" src="https://raw.githubusercontent.com/wannanbigpig/dsh-sidebar/master/docs/images/screenshots/terminal.png" alt="对话输入框下方展开交互式终端"><br><sub><b>交互式终端</b>：终端在对话输入框下方打开，与对话区域同步平滑伸缩，并支持多标签和高度调整。</sub></td>
  </tr>
</table>

## 功能

- **原生工作台融合**：宿主负责 Right Sidebar、Files、资源地址、标签页以及拆分/悬浮布局；插件不再提供第二套侧栏、起始页、通用文件树或工作台开关，只把 Review 与 Terminal 入口加入宿主 `+` 打开的 Guide。
- **文件编辑**：宿主 Files 与插件编辑器统一使用宿主公共 `FileTypeIcon`；从 Files、聊天文件链接或工具结果打开文本/代码文件时，由插件的原生资源查看器提供 CodeMirror 6 编辑、语法高亮、行号、路径面包屑、独立撤销历史和 `Cmd/Ctrl+S`；未保存文件在原生标签图标前显示圆点，图片和 PDF 保留宿主原生预览，草稿按原生标签隔离并使用版本令牌保存，避免覆盖其他写入者的更新。
- **Git 审查**：支持未提交、未暂存、已暂存、指定提交和分支范围；逐文件 diff、增删行统计、可折叠的上下文及可筛选的变更文件树；“已提交”菜单可按提交信息或哈希搜索当前分支相对基准的提交，支持方向键导航与 Escape 返回。
- **Git 操作**：工具卡显示当前分支与工作区改动；分支菜单支持创建或切换分支，提交弹窗支持提交、提交并推送、推送及模型生成提交信息；分支切换失败会显示原因，提交成功但推送失败后可直接重试推送。
- **Worktree**：工具卡的“本地”菜单列出主工作树、有效的链接工作树和失效记录；可选择已有工作树、返回主工作树或新建工作树，并按目标 `cwd` 复用已有 Session（没有时创建新 Session）。
- **终端**：输入框下方的 Dock 使用 xterm.js 连接持久 `zsh` PTY，打开和关闭时与对话区域同步平滑伸缩；支持输入、粘贴、控制键及 ANSI/256 色/True Color。宿主终端提供者支持时同步实际行列尺寸，输出受字节上限保护。
- **宿主打开方式**：复用宿主顶部统一的 Open In 应用选择，不重复探测或展示另一套文件管理器、终端和编辑器菜单；插件编辑器仍保留“在宿主预览中打开”的只读查看入口。
- **主题与语言**：界面、编辑器和终端跟随宿主明暗主题，提供中英文文案。

## 安装与使用

从 npm 安装预构建包（无需克隆宿主源码或本地构建），加入某个 DSH Profile：

```sh
dsh plugin --profile workbench add @wannanbigpig/dsh-sidebar
dsh --profile workbench --dump-config
dsh --profile workbench
```

安装后：

1. `--dump-config` 输出中出现 `# == @wannanbigpig/dsh-sidebar` 即注册成功；插件只插入自身服务行，不覆盖宿主既有配置。
2. 从宿主 Right Sidebar 的“文件”入口浏览项目；点击文件后会在原生资源标签中直接使用插件编辑器。
3. 宿主 `+` 打开的 Guide 会列出文件、Review 与 Terminal；选择内容后 Guide 被原位替换，不额外保留一套插件“开始”页。会话右上角的 Git 工具浮在当前会话列内，“更改”打开原生 Review；终端在输入框下方的宿主 Dock 打开。

## 使用须知与已知限制

**文件与编辑**

- 只允许读取和保存已存在的普通文件；不提供删除、重命名、创建文件，也不提供 `git reset`、`git checkout --` 或强制切换分支。
- 未配置语言模式的文件回退为纯文本；文件大小默认上限 8,000,000 字节（可通过 `maxFileBytes` 配置），超过 400,000 字符时跳过语法解析以避免大文件卡顿。当前未接入语言服务补全、诊断或代码折叠。

**Git 与 Worktree**

- 审查的“分支”范围以工作树与所选基准（含未提交/未跟踪文件）对比，参数契约以当前核对的最新宿主为准。
- 新建 worktree 以 Git 主工作树为基准，在仓库同级创建持久目录和独立分支；插件不自动删除、prune 或清理它们。
- Session 的 `cwd` 是不可变元数据。切换工作树会打开目标路径已有 Session 或创建新 Session；未提交更改保留在原工作树，不会自动 stash 或搬运。
- Git 工具卡和分支菜单依赖宿主公开的 Git 状态接口；工作区不可读时会显示错误而不是空白。

**终端与宿主打开方式**

- PTY 使用宿主公开的持久终端原语；宿主不支持 `resize` 时终端仍可用，但依赖动态行列的全屏 TUI（如 vim、htop）可能无法正确重排。
- 终端跟随宿主明暗主题；插件无法读取 Terminal.app 或 iTerm 的私有主题配置，prompt 与输出中的 ANSI 颜色原样保留。
- 顶部 Open In 菜单由宿主统一提供并作用于 Session 工作区；插件不再提供直接用外部应用打开当前文件的第二套菜单。

**宿主版本**

- 当前代码只面向核对基线 `c291e7961a515f6d7af9304e7fd1d257929aef26`（`0.1.5-rc.2`）的最新宿主源码，不保留旧版宿主兼容分支，也不替换宿主 Right Sidebar 或 Files 组件。Git 浮层使用 Portal，并按当前会话区域重新计算锚点。
- 宿主 `+` 的公开契约固定新建 Guide，插件不拦截或重写该按钮；插件把 Review/Terminal 作为 Guide 条目注册，用户选中内容后再原位替换 Guide。
- 宿主已公开统一的 `FileTypeIcon` 并在 Files 内原生使用；插件直接复用该组件，不再通过 `data-files-*` 选择器隐藏或覆盖宿主图标。图片和 PDF 由宿主原生 document preview 呈现，插件只接管可编辑的文本/代码资源。
- 插件自带预构建 Typert 描述符；运行时仅使用宿主公开的 Right Sidebar、Slot、Session、Remote、`fs`、`subprocess` 与 Client Module API。宿主缺少这些必需服务时插件不会激活。

## 本地开发

此开发目录假设它与宿主源码相邻：

```text
openSource/
├── deepseek-harness/
└── dsh-sidebar/
```

构建复用相邻宿主已安装的 TypeScript、tsdown 和公开类型，只在本仓库 `lib/` 写入产物，不要对宿主源码执行该构建：

```sh
npm install
npm run build
npm test
```

实时调试时，先启动持续构建器把 `src/` 的每次保存编译到 `lib/`：

```sh
npm run dev
```

首次调试把本地目录加入 `web` profile（目录安装建立 `link:` 依赖后无需重复执行）：

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

再另开一个终端，从需要测试的 Git 项目目录启动 Web：

```sh
cd /path/to/your/git-project
DSH_SIDEBAR_ROOT=/path/to/dsh-sidebar \
  dsh web --patch /path/to/dsh-sidebar/dev/host-hmr.patch.yml --no-open
```

- 修改 `src/client/**`：Client HMR 约 500ms 后自动更新页面，无需刷新。
- 修改 Host 侧代码（`src/index.ts`、`src/remote.ts`、`src/contribution.ts`）：通过 `dev/host-hmr.patch.yml` 监视 `lib/` 并重载 Host 插件，浏览器保持打开即可。
- 只调 UI 用 `npm run dev:client`；只调 Host 用 `npm run dev:host`。
- 不带 `--patch` 启动时，Host 修改需要重启 `dsh web`，客户端修改需要硬刷新浏览器。
- `dsh web` 不可用时，可用已构建的宿主 CLI 代替：`node ../deepseek-harness/apps/cli/lib/bin.js web …`。