前言¶

DeepSeek Harness（DSH）的 Web 界面以对话为主。做智能体调试时，常常还需要同时查看当前注入的上下文文档、项目目录，以及仓库的 Git 状态。

dsh-compass 是一个 DSH Web 插件，由 Happy2Git 维护，许可证为 MIT，Copyright (c) 2026 DeepSeek。它为 Web 界面新增右侧上下文、文件夹面板和 Git 状态监控，并提供会话日志下载动作。

需要先说明一点：npm 发布版 dsh 无法显示本插件；需要使用 GitHub 源码构建的 dsh，或作者 fork。

这是什么¶

dsh-compass 是 DSH 的 Web 插件。它把目录浏览、注入上下文文档和只读 Git 提交图放进 Web 界面右侧，并提供会话日志下载动作。

它适合需要在对话旁边核对上下文、文件和仓库状态的开发者。

核心能力¶

• 为 Web 界面新增右侧上下文、文件夹面板和 Git 状态监控。
• 目录浏览带 git 状态徽章。
• 注入上下文文档与压缩历史流水实时重投影。
• 上下文展示来源标注、实测占用条与未读信号。
• 带边框的只读 Git 提交图与工作区状态。
• 面板文件拖入对话。
• 会话日志下载动作。
• 宿主路由仅限回环。

安装前提¶

已核实信息表明：

• npm 发布版 dsh 无法显示本插件。
• 上游 master 源码构建（≥47f9438）可用。
• npm 发布版不可用。
• 作者 fork 的默认 web profile 已内置同一面板；若改用本包，需要禁用内置面板行。

安装与启用¶

本地 clone 安装¶

先克隆并构建插件：

git clone https://github.com/Happy2Git/dsh-compass.git
cd dsh-compass
pnpm install
pnpm run build

构建完成后，回到 dsh 的启动目录，按路径安装：

pnpm dsh plugin --profile web add /path/to/dsh-compass

这种安装随 clone 生灭：检出目录不能删除或移动。重新执行 pnpm run build 后，重启 pnpm dsh web 即可生效。

钉 commit 的 git 安装¶

如果不在本地保留 clone，可以用钉 commit 的 GitHub 安装方式：

pnpm dsh plugin --profile web add github:Happy2Git/dsh-compass#<commit-sha>

git 安装通过 prepare 脚本从源码构建。pnpm ≥10 会拦截构建脚本，需要放行构建后再继续安装。

使用固定 commit 可以明确安装来源。

作者 fork¶

作者 fork 的默认 web profile 已内置同一面板。若改用 dsh-compass 包，需要禁用内置面板行。

启动与验证¶

启动或重启 Web 服务：

pnpm dsh web

刷新页面后，核对右侧出现面板。

也可以通过 POST /dir/list 返回 JSON 验证 host 路由已挂载：

POST /dir/list
Content-Type: application/json

{
  "path": "<fully-qualified-path>"
}

请求体上限 64 KiB，且必须是 application/json；路径必须完全限定。

典型用法¶

• 在目录浏览中查看文件，并查看带 git 状态徽章的条目。
• 在上下文档查看注入上下文文档与压缩历史流水。
• 使用来源标注、实测占用条和未读信号判断上下文变化。
• 在 Git 面板查看带边框的只读提交图与工作区状态。
• 把面板中的文件拖入对话。
• 使用会话日志下载动作导出日志。

卸载¶

pnpm dsh plugin --profile web remove dsh-compass

适用场景与注意¶

适合使用 DSH Web 界面，并在开发调试时需要同时查看上下文、目录和 Git 状态的智能体开发者。

注意事项：

• 插件以当前 dsh 进程权限运行；安装前应检查源码和 MIT 许可证。
• npm 发布版 dsh 无法显示本插件；需要使用 GitHub 源码构建的 dsh，或作者 fork。
• 上游 master 源码构建（≥47f9438）可用；npm 发布版不可用。
• 宿主路由仅限回环。
• 请求体上限 64 KiB，且必须是 application/json；路径必须完全限定。
• 面板只读：git 命令从不写入，拖入图片从不复制进工作区。
• 本地 clone 安装随 clone 生灭，检出目录不能删除或移动；重新 build 后重启 pnpm dsh web 生效。
• git 安装通过 prepare 脚本从源码构建；pnpm ≥10 会拦截构建脚本，需要放行构建。
• 作者 fork 的默认 web profile 已内置同一面板；改用本包需禁用内置面板行。

结尾¶

dsh-compass 把 DSH Web 界面右侧空间用来集中查看上下文、文件和只读 Git 状态，并提供会话日志下载动作。

项目仓库：https://github.com/Happy2Git/dsh-compass