高级侧边栏工具集 navid-kianfar/dsh-advanced-sidebar

@achasoft/dsh-advanced-sidebar

为 DeepSeek Harness（dsh）Web Client 提供会话菜单和可调整大小的侧边停靠栏。会话标题栏里的 ⋯ 菜单会在对话右侧的一列中打开这些面板：

- Changes：git 状态、diff、暂存、提交、由模型撰写的提交信息，以及推送；
- Terminal：你自己的 shell，分标签页显示；
- Files：文件浏览器，带文本预览；
- Preview：开发服务器、工作区文件、URL，或草稿本；
- Background tasks：会话的任务。

同一个菜单里还有 Open in、Download session log、Archive 和 Delete。浏览器自己做不到的事（运行 git、打开伪终端、启动编辑器）由宿主执行，走本插件自己的 RPC 命名空间。还有一个可选的模型工具 ui_preview，让智能体查看并操作 Preview 面板。

停靠栏在对话旁打开，显示 Changes 面板，其中有已暂存和未暂存的文件、一个 diff 和提交框

功能

会话菜单

打开会话的标题栏里有一个 ⋯ 按钮。它作用于该会话，使用会话自己的工作目录；会话没有工作目录时，用它的工作区路径。

| 条目 | 作用 |
| Changes、Terminal、Files、Preview、Background tasks | 在停靠栏中打开对应面板。已打开面板的条目带勾选标记，再次选择它会关闭停靠栏。 |
| Open in ▸ | New window（Web Client 的第二个标签页）、每个已配置的编辑器，以及操作系统文件管理器：Finder、File Explorer，Linux 上是 xdg-open。 |
| Download session log | 通过 harness 自带的导出器，把会话导出为 ZIP。见下方说明。 |
| Archive | 隐藏会话。日志仍留在磁盘上。 |
| Delete | 请求确认，然后归档。见已知限制。 |

宿主无法提供某个条目时（没装 git、找不到编辑器命令、没有子进程能力），条目仍留在菜单里，但处于禁用状态，旁边写明原因。在设置里关掉的条目则完全不显示。菜单每次打开都会重新询问宿主，所以装了 git 或编辑器后无需重启即可生效。

Download session log。 harness 包 @deepseek-ai/dsh-session-log-export 会在同一行标题栏里加上自己的 ⋯ 按钮，只有这一个条目。本插件隐藏那个按钮：它以相同的 id（session-log-download）、优先级 -1 注册一个条目，并把该条目移进自己的菜单。导出仍使用 harness 的控制器和对话框，所以 /export 照常工作。如果 harness 包不存在，或它的控制器结构不同，则什么都不隐藏，菜单里也没有 Download 条目。
会话标题栏 ⋯ 菜单展开：面板条目、Open in 子菜单、Download session log、Archive 和 Delete

停靠区

面板在应用窗口右侧的一列中打开。对话区会收窄腾出空间，所以停靠区不会盖住对话。

- 调整大小。 拖动左边缘，在聚焦的手柄上按 Left 和 Right，或双击手柄恢复为配置的宽度。
- 宽度限制。 宽度保持在 280 px 到 960 px 之间，且对话区永远不会小于 400 px。
- 窄窗口。 当连最小宽度都会把对话区挤到 400 px 以下时，停靠区改为浮在对话区上方。

更改

- 状态。 工作目录的状态，按 Staged、Not staged、Untracked 和 Conflicted 分组，并显示分支、ahead 和 behind 计数。点击文件查看其补丁，可复制补丁。
- 暂存。 对单个文件执行 Stage / Unstage，或用 Stage all / Unstage all 对整组操作。
- 提交。 Commit 记录已暂存的内容，可选修补上一次提交。git 会记录的作者（git var GIT_AUTHOR_IDENT）显示在消息框下方，这样提交前就能发现缺失的 user.email。
- 生成。 用编辑器当前设置的模型写一条提交消息。模型只能看到已暂存的补丁，上限为 commitMessageMaxBytes。消息会填入框内供你编辑，不会自动提交。
- 推送。 把当前分支推送到其上游（不带参数的 git push）。没有上游的分支改为显示 Publish，它会推送到 origin；如果没有 origin，则推送到第一个远程，并设置上游。不提供强制推送、远程选择器和自定义 refspec。
- 不能丢弃。 此面板无法丢弃更改。请使用 Terminal 面板。

终端

- 你自己的 shell。 会话工作目录中的交互式 shell，以标签页形式存在，最多 maxTerminals 个。它们与模型的终端相互独立。
- 控制。 Interrupt 和 Ctrl+C 向前台进程组发送 SIGINT。Clear 清屏，Restart 启动新 shell。
- shell 持续运行。 关闭停靠区或切换面板不会让它们停止。重新打开标签页会重放宿主保留的输出（terminalScrollback）。关闭标签页会结束其 shell，归档或删除会话同样如此。
- 模拟器。 屏幕由 @xterm/xterm 渲染，所以颜色、行编辑和全屏程序都能正常工作。

Terminal 面板，含两个 shell 标签页和 git 命令输出

文件

- 浏览。 工作目录，一次一层。除非开启 filesShowHidden，否则隐藏条目会被排除。
- 预览。 文本预览最多显示 filesMaxPreviewBytes 字节。二进制文件显示文件大小。
- 操作。 用默认应用打开 和 在文件管理器中显示。

文件面板列出目录内容，并预览一个文本文件

预览

四种模式，每种模式都带视口选择器（Desktop、Tablet、Mobile、Custom）。

| 模式 | 显示内容 |
| Server | 从工作区的 .claude/launch.json（Claude Code 的格式）和 previews 设置中读取启动配置。两者定义同名配置时，以文件为准。可以 Start 和 Stop 服务器、查看 Logs（启动失败时日志会自动打开）、Open in a new window，或 Open inspectable，后者会把 URL 交给 URL 模式。 |
| File | 工作区文件，按类型渲染：HTML 和 SVG 用 frame 渲染，Markdown 渲染后显示，还有图片、音频、视频、PDF 和纯文本。文件变化时面板会重新加载。超过 previewMaxFileBytes 的文件，或类型未知的文件，提供 用默认应用打开。 |
| URL | 任意 http(s) 地址。localhost、127.x.x.x 或 [::1] 地址通过宿主的代理加载，因此 frame 同源，可以读取它的 DOM 和控制台。其他地址直接嵌入 frame，并标记为跨源。 |
| Scratchpad | 你输入的 HTML，由宿主路由渲染。文本按工作区保存在当前浏览器的 localStorage 中。 |

对启动配置来说，就绪意味着配置的 port 能接受 TCP 连接，检查会持续到 previewReadyTimeoutMs。子进程会拿到 PORT、NO_COLOR=1 和 FORCE_COLOR=0。停止时先向进程树发送 SIGTERM，previewGraceMs 之后再发送 SIGKILL。

.claude/launch.json 示例：

{
"version": "0.0.1",
"configurations": [
{ "name": "web", "runtimeExecutable": "npm", "runtimeArgs": ["run", "dev"], "port": 3000 }
]
}

预览面板处于 Server 模式，正在运行一个启动配置，显示代理后的页面和视口选择器

后台任务

- 列表。 会话的后台任务，可按文本、状态和开始日期筛选，显示时长和状态。
- 停止。 需要 allowTaskKill。停止任务还会屏蔽模型原本会收到的完成通知。
- 输出。 需要 showTaskOutput，且只在任务结束并上报完成之后出现。提前读取输出会消耗模型要读的那份输出。

设置卡片

Settings → Plugins → Advanced sidebar 可以编辑大部分设置，并针对每个 Open in 目标和预览配置，显示它在本机是否可用。参见 配置。
高级侧边栏设置卡片，已展开，包含菜单项开关、限制和「打开方式」目标列表

环境要求

- DeepSeek Harness 0.1.5-rc.2，使用 web 配置档。插件针对这个版本测试。Node ^22.19 || >=24。
- pnpm 要在 PATH 里，因为 dsh plugin 会调用 pnpm。
- git 2.23 或更新版本要在宿主机的 PATH 里，供 Changes 使用，因为取消暂存依赖 git restore --staged。
- Harness 的各项能力，都是可选的。缺哪一项，只禁用需要它的菜单项，并显示原因：

| 能力 | 使用方 |
| subprocess | Changes、Terminal、Preview servers、Open in |
| fs | Changes、Terminal、Files、Preview |
| jobs | 后台任务（Stop 和 Output） |
| workspaceRegistry | Delete；Preview 的 File 模式（文件只从已注册的工作区提供） |
| llm + agentDefaultModel | Generate 提交信息 |
| connection（带 requestRejection）+ webServer | Preview 的同源路由：File 模式、loopback 代理、Scratchpad |
| tools | ui_preview 模型工具 |
| sessionLogDownload（来自 @deepseek-ai/dsh-session-log-export） | 下载会话日志 |

- 操作系统： 在 macOS 上开发和测试。代码里有 Windows 和 Linux 分支（shell 回退、文件管理器命令），但未经验证。

安装

dsh plugin --profile web add @achasoft/dsh-advanced-sidebar
dsh web

dsh plugin --profile <name> … 会在 $DSH_HOME/profiles/<name>（默认 ~/.dsh/profiles/web）里，用剩余参数运行 pnpm。之后，dsh 会把每个 package.json 里声明了 dsh.bundle 的依赖加进 dsh.profile.bundles。本包声明了 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }，所以无需手动修改即可启用。安装后重启 dsh web。

卸载时，移除这个包即可。dsh 也会把它从 dsh.profile.bundles 里删掉：

dsh plugin --profile web remove @achasoft/dsh-advanced-sidebar

cordis.patch.yml 的应用方式

启动时，dsh 按以下顺序，从补丁层构建配置：

1. 每个 bundle 的 cordis.patch.yml，按 dsh.profile.bundles 的顺序。
2. $DSH_HOME/profiles/<name>/cordis.patch.yml。
3. $DSH_HOME/cordis.patch.yml。
4. 任何 --patch <file> 覆盖层。

后面的层按行 id 覆盖前面的层。本包插入三行：

| id | name | 作用 |
| advanced-sidebar | @achasoft/dsh-advanced-sidebar/host | 宿主服务、RPC 命名空间 advancedSidebar、advanced-sidebar 设置区，以及 preview 路由。 |
| advanced-sidebar-ui | @achasoft/dsh-advanced-sidebar | 浏览器端。这里必须写裸包名，因为 Web Client 通过解析 <row name>/package.json 来查找浏览器代码。 |
| advanced-sidebar-ui-preview | @achasoft/dsh-advanced-sidebar/ui-preview | ui_preview 模型工具。 |
如果只想保留侧边栏、不给模型提供工具，就在配置档的 cordis.patch.yml 里禁用第三行：

- id: advanced-sidebar-ui-preview
disabled: true

查看组合后的结果：

dsh --profile web --dump-config

配置

下面所有键都位于 advanced-sidebar 行的 config 中。补丁会替换整行的 config，所以覆盖时必须重写每一个键。从本包的 cordis.patch.yml 复制该行再改。

宿主 schema 不声明任何默认值，除 commitMessagePrompt 和 terminalShell 外，每个键都是必填。表中列出的默认值是 cordis.patch.yml 自带的取值。从设置卡片保存的改动，会作为用户层覆盖在补丁值之上。卡片一列标记卡片能编辑的键。Web Client 不在 loopback 上时，harness 设置作用域不可用，卡片和菜单只能只读显示宿主的取值。

菜单与行为

| 键 | 默认值 | 卡片 | 作用 |
| showInSessionHeader | true | 是 | 在会话头部显示 ⋯ 菜单。关闭后，如果还需要提供 Download session log，按钮仍会出现，但只提供这一项。 |
| showChanges、showTerminal、showFiles、showTasks、showPreview、showOpenIn、showArchive | true | 是 | 显示对应的菜单项。 |
| showDelete | true | 是 | 显示 Delete。关闭后，宿主也会拒绝 deleteSession。 |
| panelWidth | 460 | 是 | 停靠面板宽度，单位 px（schema 允许 280–1400；停靠面板最多用 960）。作用域可写时，拖动边缘会把宽度保存到这里。 |
| deleteMode | archive | 是 | archive 或 purge。本 harness 上 purge 不可用，见限制说明。 |
| confirmDelete | true | 是 | Delete 前先询问。deleteMode 为 purge 时必须为 true。 |
| allowTaskKill | true | 是 | 提供 Stop，由宿主强制执行。 |
| showTaskOutput | true | 是 | 为已完成任务提供 Output，由宿主强制执行。 |

git（Changes 面板）

| 键 | 默认值 | 卡片 | 作用 |
| gitMaxFiles | 500 | 是 | 单次状态读取的最大文件数。 |
| gitDiffMaxBytes | 262144 | 否 | 单个文件返回的最大补丁字节数。 |
| gitTimeoutMs | 20000 | 是 | 每条只读 git 命令的时限。 |
| allowGitStaging | true | 是 | 暂存与取消暂存，由宿主强制执行。 |
| allowGitCommit | true | 是 | 提交，由宿主强制执行。同时要求开启暂存。 |
| gitCommitTimeoutMs | 120000 | 是 | git commit 的时限，该命令会运行钩子。 |
| allowGitPush | true | 是 | Push 与 Publish，由宿主强制执行。 |
| gitPushTimeoutMs | 180000 | 是 | 推送的时限。 |
| allowCommitMessageDraft | true | 是 | Generate，由宿主强制执行。同时要求开启提交。 |
| commitMessagePrompt | '' | 否 | 替换内置的提交信息指令。留空则使用内置指令。 |
| commitMessageMaxBytes | 65536 | yes | 发送给模型的最大暂存补丁。补丁过长会被截断，并告知模型内容已被裁剪。 |

终端与文件

| 键 | 默认值 | 卡片 | 作用 |
| terminalShell | '' | yes | 要运行的 shell。留空则使用 $SHELL，再回退到 /bin/sh（Windows 上为 %COMSPEC% 或 powershell.exe）。 |
| terminalScrollback | 200000 | no | 每个终端保留的输出字符数，用于回放。 |
| maxTerminals | 4 | yes | 同时打开的面板终端上限（1–32）。 |
| terminalGraceMs | 3000 | no | 终端关闭时，TERM 与 KILL 之间的延迟。 |
| filesMaxPreviewBytes | 262144 | no | 文件预览中显示的最大文件。 |
| filesMaxEntries | 2000 | no | 每个目录列出的条目上限。 |
| filesShowHidden | false | no | 是否列出点文件。 |

预览

| 键 | 默认值 | 卡片 | 作用 |
| previewsFromLaunchFile | true | yes | 读取 .claude/launch.json。 |
| previews | [] | no（会列出） | 额外的启动行：name、runtimeExecutable、runtimeArgs、port、url、cwd。runtimeExecutable 留空时，该行只做挂载：把框架指向 url，不启动任何东西。 |
| maxPreviews | 3 | yes | 同时运行的开发服务器上限。 |
| previewReadyTimeoutMs | 60000 | yes | 等待端口接受连接的时间。 |
| previewScrollback | 200000 | no | 每个服务器保留的日志字符数。 |
| previewGraceMs | 3000 | no | 服务器停止时，TERM 与 KILL 之间的延迟。 |
| previewMaxFileBytes | 33554432 | no | 提供给框架的最大工作区文件。 |
| previewProxyTimeoutMs | 30000 | no | 单个代理请求发往回环服务器的时间上限。 |
| previewCommandTimeoutMs | 15000 | no | ui_preview 命令中除 open 之外的其他命令，等待面板的时间。 |
| previewBindTtlMs | 6000 | no | 面板最后一次轮询后，仍算作打开状态的时长。 |

打开方式

| 键 | 默认值 | 卡片 | 作用 |
| editors | VS Code（code）、Cursor（cursor）、Zed（zed） | no（会列出可用项） | 由 id、label、command、args 组成的行。args 放在路径之前。id 必须匹配 ^[a-z][a-z0-9-]$，不可重复，且不能是 reveal。 |

加载时，出现以下情况，宿主会拒绝该配置：

- 编辑器 id 无效或重复，或者编辑器命令为空；
- 预览名称为空或重复；
- 预览行既没有命令，也没有 URL，也没有端口；
- deleteMode 为 purge，而 confirmDelete 为 false。

advanced-sidebar-ui-preview 行只有一个键 commandTimeoutMs（默认 15000，范围 1000–600000）。当调用没有传入 waitMs 时，它就是 ui_preview open 的默认等待时间。

模型工具与 RPC

ui_preview

只有组装了 advanced-sidebar-ui-preview 行时才会注册。它只在同一会话中 Preview 面板打开时可用。否则会立即返回一条消息，让模型打开面板。
| 操作 | 参数 | 结果 |
| open | url 或 path；可选 workspace、waitMs | 把面板指向 http(s) URL 或工作区文件，并报告页面能否被检查。 |
| dom | 可选 selector | 渲染后的 DOM：标签、id 和 class、文本、display、盒模型尺寸，外加页面文本、视口和 URL。 |
| eval | expression | 在 frame 里运行 JavaScript，把返回值以 JSON 返回。 |
| console | 可选 cursor | 自 cursor 起记录的 console 消息、未捕获错误和未处理的 rejection。 |
| click | selector | 在元素上派发 click()。 |
| type | selector、text，可选 key | 设置元素的值，派发 input 和 change，然后可选地派发按键。 |
| reload | 无 | 重载 frame。 |
| resize | width、height | 设置 frame 视口尺寸。 |
| close | 无 | 关闭预览。 |

dom、eval、click、type 遇到跨域 frame 会按名字拒绝，而不是返回空。

RPC 命名空间 advancedSidebar

浏览器端通过 harness 的客户端连接调用这些端点：

- describe
- gitStatus、gitDiff、gitStage、gitUnstage、gitCommit、gitPush、gitCommitMessage
- terminalOpen、terminalRead、terminalWrite、terminalSignal、terminalClose
- listEntries、readFile
- previewList、previewStart、previewStop、previewLogs、previewFileInfo、previewPoll、previewResult、previewRelease
- openIn
- taskKill、taskOutput
- deleteSession

每个端点都返回带失败码的结果值，不抛异常。根导出会重新导出这些类型。

安全说明

- git 不运行仓库配置的程序。
- 每条 git 命令都带 -c core.fsmonitor=false。
- 每次 git diff 都带 --no-ext-diff --no-textconv。
- 只读命令（status、diff、log、identity、remote list）会从仓库的本地配置和每个 worktree 的配置里关掉 filter.<driver>.clean/process。全局和系统级过滤器（例如 git-lfs）照常运行。如果驱动名里含 =，没法用这种方式禁用，读取就会直接失败。
- stage、commit、push 是用户显式操作，保持 git 的正常行为，包括钩子和过滤器。
- 不注入选项。
- 路径会先检查是否在仓库内，再放在 -- 之后传入。
- 提交信息作为单个 -m 参数传入。
- 发布时用 git check-ref-format --branch 检查分支，用 refs/remotes/<remote>/HEAD 检查远端，然后推送 -- <remote> refs/heads/:refs/heads/。
- 凭据提示已禁用（GIT_TERMINAL_PROMPT=0），所以需要凭据的推送会直接失败，不会挂住。
- 宿主强制开关。 allowGitStaging、allowGitCommit、allowGitPush、allowCommitMessageDraft、allowTaskKill、showTaskOutput、showDelete 由宿主检查，不只是界面上隐藏。
- 路径始终留在工作区内。 文件、Preview File 模式以及 ui_preview 的文件参数，都要经过 harness 文件系统的包含性检查，因此符号链接无法逃逸。
- 面板终端与模型的终端相互独立。 它们通过 ctx.subprocess.spawnTerminal 分配，不走智能体的终端注册表，因此你的按键永远不会进入模型控制的终端。
- 预览路由有门禁。 路由 /advanced-sidebar/preview-file、/advanced-sidebar/preview-proxy（及其 websocket 升级）和 /advanced-sidebar/preview-scratchpad 都会先调用 harness 连接的 requestRejection。这与保护 /api 的是同一套 host/origin 检查和签名 dsh-auth- cookie 检查，不通过就返回 401/403。如果连接没有这道门禁，这些路由根本不会注册。
- 仅限回环地址。 代理只转发到字面意义上的回环主机（localhost、127.0.0.0/8、[::1]）。仅仅解析到回环地址的主机名会被拒绝。
- 不转发凭据。 harness 的 dsh-auth-* cookie 会从转发请求和上游 Set-Cookie 响应头中剥离。
- 仅限已注册工作区。 文件路由只提供 workspaceRegistry 中某个工作区内的文件。
- Scratchpad 大小。 Scratchpad 文档限制为 1 MiB。
- 不缓存。 响应以 no-store 发送。
- 被代理的页面以 Web Client 的源运行。 它的脚本可以用你的会话调用 harness API。只预览你信任的开发服务器，信任程度要等同于一个已登录 harness 的浏览器标签页。
- ui_preview open 接受任意 http(s) URL，和地址栏一样。只有回环 URL 才会变成同源、可检查。

已知限制

- 删除只能归档。 harness 的会话持久化 API（0.1.5-rc.2）无法移除会话。因此 deleteMode: purge 会报告为不可用，卡片不会选中它；配置了 purge 时，它会归档并返回保留日志的原因。
- 没有推送通道。 树外插件无法添加 wire frame，所以终端输出、预览日志和 ui_preview 命令都靠轮询。
- 有任务时命令轮询每 600 ms 一次，空闲时每 2 s 一次。
- 被监视的预览文件每 900 ms 检查一次。
- 后台任务是例外：它们使用 harness 现有的 session/jobs 推送。
- 终端不能调整大小。 subprocess API 没有 resize 调用。模拟器跟随 dock，但 shell 会保持启动时的大小，直到你点 Restart。
- 服务器模式的 frame 是跨源的。 启动的开发服务器用自己的 URL 直接做 frame。用 Open inspectable 通过代理加载它。
- Websocket 代理只在代理根路径生效。 开发服务器若在子路径上开 live-reload socket，就不会被隧道。页面仍能渲染，HTTP 流式传输（包括 SSE）会走代理。
- ui_preview eval 以函数体运行。 声明不会在调用之间保留。
- 控制台捕获只能看到页面的 console 和错误事件，看不到网络失败，也看不到 worker。
- 字节范围请求需要 fs.readByteRange。 没有它，文件路由会返回完整的 200，媒体能播放，但无法拖动进度。
- dock 依赖 frame 的 DOM。 它靠在 shell.overlay 这个 frame 元素上设置一个 CSS 属性和一个 data 属性来预留宽度。harness 的布局一旦改动，这里可能也要跟着改。
- 浏览器端包体很大。 终端模拟器占了大部分，而 harness 每个插件只提供一个文件，所以没法懒加载。
- Generate 会消耗模型的 token。 每按一次都会调用部署配置的服务商。把 allowCommitMessageDraft 设为 false 可以去掉它。
- 停止任务会让模型看不到任务的完成情况。 把 allowTaskKill 设为 false 可以去掉 Stop。

开发

开发依赖是指向 DeepSeek Harness 源码检出目录的 link: 说明符，路径为 ../../deepseek-harness，相对于本目录。安装前先把 harness 克隆到那里。

pnpm install
pnpm run typecheck
pnpm test # checks generated/ against src/host, then runs vitest
pnpm run build # tsc -p tsconfig.build.json, then tsdown -> lib/

generated/ 是已提交的 Typert RPC 契约，由 harness 生成器里的 scripts/emit-typert.mjs 按生成器格式写出。如果你改了 src/host/types.ts 或其中的 @Remote 方法，就要更新该脚本的 spec 并重新生成：

pnpm run regen:typert # rewrites generated/ and its fingerprint
pnpm run check:typert # the same check pnpm test runs first

要把你的检出加载到本地配置档，先构建，再按路径添加：

pnpm run build
dsh plugin --profile web add "$(pwd)"
dsh web

配置档加载的是构建产物 lib/，所以要先构建。改完浏览器端代码后，重新构建并刷新页面。改完 src/host/ 下的任何内容，或者重新生成 generated/ 之后，重启 dsh web。

许可证

MIT