标签页内嵌网页服务hyci3/obsidian-dsh-tab

DSH Tab — 在 Obsidian 中打开本机 DSH

在 Obsidian 标签页中直接打开本机运行的 DSH（DeepSeek Harness） 网页界面，并自动管理 DSH 的启动、检测与关闭。插件以当前 Obsidian 库作为 DSH 的工作目录，所有数据保存在本机，不上传云端。

平台：Windows 电脑版 Obsidian（1.10+）｜ 版本：0.1.0｜ License：MIT

项目介绍

DSH（DeepSeek Harness）是一个本地运行的 AI 编码助手网页服务，通常通过 dsh web --port 3080 在浏览器中打开。每次手动启动、关停、切换终端窗口都很麻烦。

本插件把 DSH 网页界面嵌入 Obsidian 的标签页：

- 点一下左侧功能区图标，DSH 没启动就自动拉起，启动了就直接显示界面
- 标签标题实时显示「DSH · 运行中 / 启动中 / 已停止…」等状态，动作按钮随状态切换
- 关闭 Obsidian 时 DSH 自动一起退出，无残留进程、无黑窗闪现
- 每个库有独立的 DSH 数据目录，会话与工作区互不干扰

无需全局安装 DSH：优先使用本机全局 dsh 命令；未安装时自动回退 npx --yes @deepseek-ai/dsh（首次运行由 npx 自动下载，之后走缓存）。

功能特性

- 功能区一键打开：左侧功能区按钮 → 打开 DSH 标签页；DSH 未运行时自动启动
- 六种状态视图：未运行 / 启动中（转圈）/ 运行中（内嵌网页）/ 关闭中（转圈）/ 已停止（可重启）/ 出错（可重试）

- 库即工作区：以当前库文件夹为 DSH 工作目录，DSH 产生的文件落在库里
- 智能生命周期：
- 关闭标签页不影响 DSH 运行，再打开直接显示界面
- 关闭 Obsidian 时自动关闭 DSH（可在设置中关闭）
- 插件加载时自动检测 DSH 是否已在运行
- 体验优化：
- 按钮点击动画（功能区图标 / 头部按钮 / 大按钮按压缩放反馈）
- 关闭过渡界面：点「关闭 dsh」立即显示「正在关闭 dsh…」，完成后再变「已关闭」
- 启动即时应答：点图标立即显示「正在打开 dsh…」，检测放后台
- 每库独立配置：每个库有独立的 DSH 数据目录，会话/工作区互不干扰，首次运行自动继承本机 ~/.dsh 的模型配置
- 外部进程隔离：只接管本插件启动的 DSH；端口被外部 DSH/程序占用时提示「端口被占用」，不进入、不接管、不杀
- 首次启动检查：启动前自动检查——dsh --version 可用则用 dsh 启动；不可用则查本地 npx 缓存（npm cache ls，纯本地、不触发下载），缓存中有 @deepseek-ai/dsh 则用 npx 启动；两者都不可用时显示错误页「没安装 dsh」并附官网下载链接（）；手动填写的自定义命令则严格按填写值执行
- 秒退：DSH 运行中退出 Obsidian 时的清理约 1ms（原生 kill 端口进程，外层 cmd 自然退出），退出不卡顿、无黑窗闪现、无残留进程
- 设置页：插件版本号、端口（默认 3080）、启动命令、随 Obsidian 关闭开关

安装

方式一：直接安装（无需构建）

1. 下载 latest release。
2. 将 main.js、manifest.json 和 styles.css 复制到 .obsidian/plugins/obsidian-dsh-tab/。
3. 重启 Obsidian。
4. 在 设置 → 第三方插件 中启用 DSH Tab。

方式二：从源码构建

git clone
cd plugin
npm install
npm run build    # 类型检查 + 生成 main.js

构建完成后按方式一的步骤 2、3 安装 main.js / manifest.json / styles.css。

说明：main.js 构建产物已随仓库提交（clone 即装），仅在改动源码后需要重新构建。

使用示例

首次使用

1. 打开 Obsidian，进入任意一个库，点击左侧功能区的 DSH 图标
2. 首次点击：标签页立即显示「正在打开 dsh…」（后台自动检测/启动），就绪后显示 DSH 网页
3. 插件会自动创建该库专属的 DSH 数据目录（库/.obsidian/plugins/obsidian-dsh-tab/.dsh-home/），首次运行继承本机 ~/.dsh 的模型配置

无需提前安装 DSH：插件会自动检查——dsh --version 可用则直接启动；不可用则查本地 npx 缓存（npm cache ls，不触发下载），缓存中有则用 npx 启动；两者都不可用时显示「没安装 dsh」错误页，附官网下载链接（），装好后点「重试」即可。

关闭标签页 vs 关闭 DSH

| 操作 | 结果 |
|---|---|
| 点标签页的 × | 只关闭标签页，DSH 继续在后台运行 |
| 点标签行头部的关闭按钮 | 停止 DSH（先显示「正在关闭 dsh…」，完成后再变「已关闭」） |
| 关闭 Obsidian | 自动一起关闭 DSH（可在设置中改为保留） |

之后想再次使用：再点一次功能区图标，若 DSH 仍在运行则直接显示界面，无需等待。

端口被外部占用时

若你在终端手动启动过 DSH（如 dsh web --port 3080），插件检测到端口被占用时会显示「端口被占用」错误页：

- 插件不会进入、接管或杀掉外部进程
- 请自行关闭外部 DSH 进程，或在插件设置中更换端口后重启 Obsidian

修改端口 / 启动命令

设置页支持修改端口（默认 3080）与启动命令（默认 dsh），修改后需重启 Obsidian 生效。

开发与测试

cd plugin
npm install        # 安装依赖
npm run dev        # 监听模式编译（main.js）
npm run build      # 类型检查 + 生产构建
npm test           # 运行全部测试（单元 + 真实进程集成）
npm run verify     # 构建 + 全部测试
npm run sync       # 把产物同步到本地 test-vault（测试库）
npm run package    # 打发布安装包到 ../dist/

测试说明：共 119 个测试，覆盖状态机（含关闭中）、进程管理（启动/停止/崩溃/超时/端口占用/命令回退）、界面渲染、设置、styles.css 约束、外部进程隔离、退出关闭速度与幂等、退出零弹窗零残留、DSH 真实进程生命周期等。集成测试通过 DSH_HOME 环境变量把数据重定向到工作区目录，不会触碰本机真实 ~/.dsh 数据，也不会占用 3080 端口。

仓库结构

├── docs/                  # 项目文档（PRD、设计、开发计划、优化需求、验收记录、问题清单）
├── plugin/                # 插件源码与测试
│   ├── src/               # 源码（进程管理、状态机、视图、设置等）
│   ├── tests/             # 单元测试 + 真实进程集成测试
│   ├── scripts/           # 同步 / 打包脚本
│   ├── main.js            # 构建产物（已入库，clone 即装）
│   └── manifest.json      # 插件声明
└── dist/                  # 发布用安装包（zip，含 main.js / manifest.json / styles.css）

文档索引

| 文档 | 说明 |
|---|---|
| docs/PRD.md | 产品需求文档（目标、功能、验收标准） |
| docs/01-页面结构与交互设计.md | 页面结构与交互设计 |
| docs/02-开发计划.md | 详细开发计划 |
| docs/03-M1验证记录.md | 技术验证记录 |
| docs/04-验收记录.md | 自动化验收记录 |
| docs/05-手动验收清单.md | 手动 GUI 验收清单 |
| docs/06-优化需求.md | v0.2 优化需求（O1-O4） |
| docs/07-优化开发计划.md | v0.2 优化开发计划 |
| docs/08-待修复问题清单.md | 问题清单与修复记录（FIX-01 ~ FIX-08） |

注意事项

- 仅支持电脑版 Obsidian（桌面端），手机版不支持（isDesktopOnly）
- 启动方式：自动检查 dsh --version 可用则用 dsh 启动；不可用则查本地 npx 缓存（npm cache ls，不触发下载），缓存中有 @deepseek-ai/dsh 则用 npx 启动；两者都不可用则显示错误页并附官网下载链接
- 若在设置里手动填写「启动命令」，插件严格按填写值执行（含空格路径请用引号包裹），不再自动回退
- 当前版本支持单标签页、单端口；修改设置后需重启 Obsidian 生效
- 插件的 DSH 数据目录位于 库/.obsidian/plugins/obsidian-dsh-tab/.dsh-home/，随库一起保存在本机
- 目前未发布到 Obsidian 社区插件市场，请按上方「安装」手动安装

许可证

MIT

致谢

本项目由 DeepSeek Harness（DSH） 开发完成 —— 一个本地运行的开源 AI 编码助手（npm 包：@deepseek-ai/dsh）。