前言¶
在 DeepSeek Harness（DSH）里做多轮 Agent 开发时，常见情况是：同一会话里 Agent 会改多个文件，侧栏标题也不反映「当前在盯哪一份文档」；而 .mmd、.d2 这类图表源文件，内置预览往往只当普通文本打开。社区维护者 Sayi 在仓库 Sayi/dsh-plugin-kit 里打包了四个 DSH 插件：一个把会话锁定到唯一文件的 Agent 模式、一个可复用的预览外壳，以及两个基于外壳的 Mermaid / D2 预览。预览插件按扩展名各自注册，文件插件只负责「打开这个地址」；彼此可单独安装、单独缺席。目录页见 skillhub.cn/plugins/Sayi/dsh-plugin-kit（社区插件目录，与 DeepSeek / 幻方无官方从属关系）。
这是什么¶
dsh-plugin-kit（简介：deepseek harness plugin kit）是一个 monorepo 式插件集，面向 DSH 桌面端（仓库说明按 0.2.x 的插件 / 插槽接口编写）。根包 dsh-file-session 提供 Agent Preset「文件会话」；packages/ 下三个包提供预览能力。许可为 MIT © 2026 Sayi，各子包同为 MIT。
dsh-file-session 一个文件一个会话 ← 绑定 / 守卫 / 改名 / Agent 模式
dsh-preview-kit 预览外壳（被下面两个 require）
dsh-mermaid *.mmd *.mermaid → Mermaid 12，浏览器内渲染
dsh-d2 *.d2 → d2 CLI，Host 侧编译
核心功能¶
dsh-file-session：一个文件一个会话¶
下面介绍文件会话插件的行为边界，便于判断是否适合你的工作流。
- 绑定唯一文件：通过入口「新建文件 / 选择文件」，或由 Agent 在对话中创建；Agent 写入的第一个文件即绑定文件。
- 绑定终身有效：绑定后不可切换、不可解绑；要编辑另一个文件需另开会话（设计如此，非缺陷）。
- 写守卫：Agent 只能写绑定文件；写别处会被拒绝并说明原因，读取不受限。
- 文件被删：会明确提示文件不存在，且不允许静默重建；需用户明确要求后才可在原路径重建。
- 会话改名：绑定后会话标题为文件名，侧栏可辨。
- 右侧预览：绑定文件在右侧栏打开，由扩展名对应的预览插件渲染；未装专用预览时仍可用内置文本预览。
完整说明见仓库 docs/file-session.md。
dsh-preview-kit：预览外壳¶
两个图表预览插件都 require 本包。外壳提供：
- 头部行：路径、视图下拉、「重新读取文件」、「打开方式」（与内置预览同一套 Remote 接口）。
- 图表视图：拖拽平移，滚轮 / 捏合缩放，快捷键
+-0与方向键，比例菜单（25%–400%、适应宽度）。 - 代码视图：语法高亮由各预览插件自行提供。
- 诊断路由：浏览器侧向 Host 回报渲染进度与平台能力（仅布尔 / 数字 / 类型名，不含路径与密钥）。
dsh-mermaid 与 dsh-d2¶
| 插件 | 扩展名 | 渲染方式 |
|---|---|---|
| dsh-mermaid | *.mmd、*.mermaid |
Mermaid 12，浏览器内渲染；懒加载 chunk 约 5 MB；语法错误时同时显示错误与源码 |
| dsh-d2 | *.d2 |
Host 侧调用 d2 CLI 编译；chunk 约 22 KB（highlight.js + D2 语法） |
Mermaid 在 extension 带注册，优先级高于内置预览的 fallback 带。
安装与启用¶
在 DSH 插件管理器中逐个安装。README 写明每条地址都实测可行，且每次安装只应产生一条依赖变化（管理器据此判定装了哪个包）。不要用一条仓库根地址试图一次装四个包，会出现「无法从依赖变更中确定安装了哪一个包」。
| 装哪个 | 在 DSH 里填什么 |
|---|---|
dsh-file-session |
github:Sayi/dsh-plugin-kit |
dsh-preview-kit |
github:Sayi/dsh-plugin-kit#path:packages/dsh-preview-kit |
dsh-mermaid |
github:Sayi/dsh-plugin-kit#path:packages/dsh-mermaid |
dsh-d2 |
github:Sayi/dsh-plugin-kit#path:packages/dsh-d2 |
建议顺序：
- 若要用 Mermaid 或 D2 预览，先装
dsh-preview-kit；未装时预览会惰性加载并提示上述 path 地址。 - 再按需装
dsh-mermaid/dsh-d2；文件会话可单独使用，不依赖预览包。
前置条件
- DSH 桌面端（0.2.x 插件接口）。
- 仅
dsh-d2需要本机d2CLI，例如brew install d2，或用环境变量DSH_D2_BIN指定可执行文件路径。
验证文件插件
文件插件提供只读健康路由（不含路径与密钥）：
curl -s "$DSH_WEB_URL/dsh-file-session/health"
# 示例：{"ok":true,"bindings":1,"liveAgents":0,"client":{"stamp":"…","injected":[…],"seats":3}}
# 端口随重启变化：从页面 URL 或环境变量 DSH_WEB_URL 读取，勿写死端口。
卸载在插件管理器操作即可。dsh-preview-kit 缺席时两个预览插件会提示如何安装；dsh-file-session 可独立工作。
典型用法¶
- 安装
dsh-file-session（以及按需的 preview-kit + mermaid/d2）。 - 新建或选择 Agent Preset「文件会话」的会话，通过「新建文件 / 选择文件」绑定文档，或让 Agent 创建并写入首个文件完成绑定。
- 编辑绑定文件；若扩展名为
.mmd/.mermaid/.d2，右侧由对应预览插件渲染；改源码后点「重新读取文件」重渲染。 - 需要另一份文档时，新开一会话再绑定，勿在同一会话内尝试换绑。
适用场景与注意¶
适合谁
- 希望 Agent 只改一个文件、减少误改仓库其他路径的开发者。
- 在 DSH 里直接预览 Mermaid / D2 源文件，并需要平移缩放、代码视图与「打开方式」等统一外壳能力的人。
使用前请知悉
- 插件在当前 DSH 进程权限下运行；安装前建议阅读 GitHub 源码 与 MIT 许可证，自行评估信任边界。
- 诊断路由为开放 GET，仅回报计数与类型信息；不需要可自行移除相关能力（见 README「已知限制」）。
.mmd/.d2的「打开方式」依赖系统文件关联；无关联时回落到平台已知应用列表。- 仓库内各包带有 host + browser 两套测试（README 给出断言条数）；根包
dsh-file-session版本 0.1.0（见package.json）。
结尾¶
dsh-plugin-kit 把「单文件 Agent 会话」与「可组合的图表预览」拆成四个可独立安装的 DSH 插件，安装地址以 README 表格为准。进一步细节与开发约定见 GitHub 仓库 README；社区索引见 skillhub.cn/plugins/Sayi/dsh-plugin-kit。
