前言¶
DeepSeek Harness（DSH）的 Web GUI 自带文档预览，对话里的 Markdown 链接、工具输出路径、@file 引用和文件树里的条目，默认都会在应用内打开。若你的笔记库本身就是 Obsidian vault，预览页缺少反向链接、图谱和插件环境，和日常写作流程是两套界面。
社区插件 dsh-obsidian-file-opener（维护者 Wang-Chuming，GitHub：Wang-Chuming/dsh-obsidian-file-opener）在「普通单击」时把库内文件路由到 Obsidian（或你在配置里指定的其他应用），Cmd/Ctrl + 单击 仍走 Harness 原有预览，行为与官方未改时一致。
这是什么¶
一句话：面向 DSH Web GUI 的 vault 文件打开器——单击库内引用时在 Obsidian 中打开笔记，可按规则把例如 .tex 交给 VS Code 并带上项目根目录。
插件在 DSH 生态里属于 客户端 类 bundle：Host 半部（index.js）注册 HTTP 路由与模型工具，Client 半部（client.js）包装 Web GUI 的统一导航入口 ctx.sidebarRight.openResource。许可证 MIT，运行时仅依赖 Node 内置模块；开发测例要求 Node.js ≥ 20。作者在 macOS 上开发与测试，Windows、Linux 打开逻辑已实现但练习较少。
核心功能¶
下面表格概括手势与结果（与 README 一致）：
| 手势 | 结果 |
|---|---|
对库内文件引用的 普通单击（对话 Markdown 链接、工具行路径、行内 file mention、@file、文件树中的 vault 文件） |
经 obsidian://open 在 Obsidian 中打开，Obsidian 置前 |
命中 openers 规则的 vault 文件（例如 .tex） |
在规则指定应用中打开；VS Code 规则会以 root 文件夹为工作区 |
| Cmd/Ctrl + 单击 | Harness 应用内文档预览（不变） |
不在 vaultRoot 内、扩展名不在 extensions 内、程序化或恢复时打开 |
应用内预览（不变） |
| 模型侧「帮我打开这个文件」 | open_vault_file 工具，路由与普通单击相同 |
Host 侧对每次打开做 realpath containment：路径必须在 vaultRoot 内，.. 与逃出 vault 的符号链接会被拒绝。三条路由均先走 ctx.connection.requestRejection(req)（Harness Host/Origin 防护与登录 cookie）；连接服务缺失时返回 503，不裸奔提供服务。任意环节失败时 Client 回退到官方内置预览。
Host 暴露的路由：
| 路由 | 方法 | 用途 |
|---|---|---|
/obsidian-file-opener/config |
GET | 向 Client 提供 vault 配置 |
/obsidian-file-opener/open |
POST | { path, source? } 打开单个 vault 文件 |
/obsidian-file-opener/diag |
POST | 追加浏览器诊断行 |
配置在 Host 启动时按顺序解析：bundle 行内 config: → ~/.dsh/obsidian-file-opener.config.json → 内置默认。两处都拿不到有效 vaultRoot 时插件加载但 不生效（config 路由 ok: false，界面仍全部走预览）。
安装与启用¶
1. 加入 profile¶
dsh plugin --profile <profile> add github:Wang-Chuming/dsh-obsidian-file-opener
<profile> 为 desktop、web 或 headless。命令会安装包并因包声明 dsh.bundle 自动写入 dsh.profile.bundles。Desktop 也可在 Settings → Plugins（或插件市场上架后）安装，由 Desktop profile 管理。
2. 指向你的 vault¶
推荐在用户目录写入配置文件（仅 vaultRoot 必填；路径中的 ~ 会展开，openers[].root 若为相对路径则相对 vaultRoot 解析）：
cat > ~/.dsh/obsidian-file-opener.config.json <<'JSON'
{
"vaultRoot": "/Users/you/Research/Research-Vault",
"vaultName": "Research-Vault",
"extensions": [".md", ".canvas", ".base"],
"openers": [
{
"app": "vscode",
"extensions": [".tex"],
"root": "physics/lshape-pt-symmetry/paper/manuscript"
}
]
}
JSON
文件缺失或格式错误视为「无覆盖项」，插件保持 inert，不会猜测路径。
3. 重启并确认¶
必须 重启 Harness（仅刷新 Client 不够：Host 在启动时读配置并注册路由与工具）。首次加载页面后，可查看 ~/.dsh/obsidian-file-opener.diag.jsonl，其中应出现 host-activate、client-activate、client-config、selftest-trigger、open 等事件行；README 给出了示例 JSON 结构。
环境要求：已安装 Obsidian 及要对齐的 vault；DSH 需具备 Web GUI 与 plugin-bundle 支持。
典型用法¶
- 完成安装与
vaultRoot配置并重启后，在对话里 普通单击 任意库内笔记链接，应在 Obsidian 中打开该笔记。 - 对同一链接 Cmd/Ctrl + 单击，应仍在 Harness 内预览。
- 若配置了
openers，单击 vault 内匹配扩展名的文件（如.tex）应在 VS Code 中打开，且 LaTeX 等工作区以配置的root为项目根。 - 需要模型代开文件时，Harness 侧提供的
open_vault_file与单击走路由一致。
Client 在首次加载会跑一遍自测链并写入上述 JSONL 日志，便于确认 Host/Client 与打开通道是否正常。
适用场景与注意¶
适合谁： 日常把 DSH 工作区与 Obsidian vault 叠在同一份 Markdown 库上的开发者或研究者；希望在 Harness 里点链接就回到 Obsidian 编辑、图谱与插件环境，而不是在 Web 预览里「第二份只读副本」。
生态背景： DSH 强调「一切皆插件」；SkillHub 目录页 等社区站点独立于 DeepSeek / 幻方，并非官方应用商店。
安全与权限： 插件以当前 DSH 进程权限在本地调用系统打开器（macOS open、Linux xdg-open、Windows cmd /c start），安装前请自行审阅 源码与 MIT 许可证。仅将 vaultRoot 指向你信任的路径；Host 会拒绝逃出 vault 的路径，但错误配置仍可能指向你不希望暴露给浏览器的目录——配置责任在用户侧。
平台： 非 macOS 用户若遇打开异常，可向仓库 Issues 反馈或提交补丁。
结尾¶
dsh-obsidian-file-opener 把 Web GUI 里「点 vault 文件」的默认目的地从内置预览改成 Obsidian（及可选的 VS Code 规则），同时保留修饰键预览与非 vault 文件的原有行为。需要详情、中文 README 与 issue 入口见 GitHub 仓库；插件索引见 SkillHub 目录页。
