前言¶
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 目錄頁。
