前言¶
在 DeepSeek Harness（DSH）裏做智能體時，知識往往落在本地筆記裏，而對話界面和筆記窗口通常是兩套應用。你只能自己複製粘貼，或者讓 Agent 去碰工作區裏的 .sy 文件和 siyuan.db，風險和權限都不好控。
@yogemow/dsh-siyuan（倉庫 YOGEMOW/dsh-siyuan）走另一條路：全部通過思源桌面內核的公開 HTTP API 與筆記本交互，不讀寫工作區文件。Agent 側提供 9 個工具用於檢索與讀寫；客戶端側提供左欄文檔樹、右欄邊聊邊讀的筆記視圖，以及把助手回答確認後寫入思源。維護者爲 YOGEMOW，在社區目錄 skillhub.cn 中歸類爲客戶端插件。
下面按定位、能力、安裝配置、用法與注意點說明如何在 DSH 0.2.x 環境下使用（思源側需 3.8.x 桌面端在運行）。
這是什麼¶
包名 @yogemow/dsh-siyuan，當前版本 0.3.5，許可證 MIT。入口分爲 Host 側 index.js（Agent 工具與 /siyuan/* 路由）和 Client 側 client.js（側欄、設置、回答動作）。設計細節見倉庫內 docs/DESIGN.md、docs/KERNEL-NOTES.md、docs/CONTRACT.md。
一句話定位：把思源筆記接入 DSH，讓 Agent 能搜讀寫作業記，並在界面裏按文檔樹瀏覽、在右欄預覽，回答可二次確認後存入思源。
核心功能¶
Agent 工具（9 個，默認只讀）¶
寫入能力受插件「寫入開關」約束；關閉時寫工具與寫路由返回 SIYUAN_WRITE_DISABLED。
| 工具 | 作用 | 讀/寫 |
|---|---|---|
siyuan_status |
連通性、版本、Token 狀態、寫入開關、筆記本清單 | 讀 |
siyuan_notebooks |
筆記本列表（id/名稱/文檔數） | 讀 |
siyuan_search |
全庫檢索（正文/標題/別名/備註子串） | 讀 |
siyuan_read_doc |
讀文檔 Markdown，行分頁（工具默認約 400 行） | 讀 |
siyuan_recent |
最近更新的文檔 | 讀 |
siyuan_sql |
只讀 SQL（單條 SELECT，內核 mode:'readonly'） |
讀 |
siyuan_create_doc |
新建文檔（可指定父文檔） | 寫 |
siyuan_append |
追加或前後插入；id="daily" 寫今日日記 |
寫 |
siyuan_open |
生成 siyuan:// 深鏈 / Web 鏈接 / 塊引用 |
讀 |
界面與交互¶
- 左欄「思源筆記」：筆記本下拉、可摺疊文檔樹（順序與思源一致，默認展開 8 層，更深層懶加載）、關鍵詞搜索（有詞時切平鋪結果）、新建文檔、設置抽屜。點筆記默認在右欄打開。
- 右欄「思源筆記」標籤（Agentero 風格）：筆記本、文檔樹、正文預覽，以及「在思源打開」「複製塊鏈接」「追加內容」「新建文檔」。左欄點筆記會直接在右欄展示；右欄不可用則退回左欄內聯預覽。
- 輸入框工具行「思源」按鈕：隨時打開右欄筆記視圖。
- 每條助手回答下方「存入思源」：選筆記本、標題（缺省取首行）、可追加到已有文檔，僅在你點「確認存入」後寫入。
正文預覽默認一次讀 1500 行，超過可「加載更多」按 offset 續讀。文檔樹會記住展開、選中與滾動（左右欄、按筆記本分開）；頂欄「重置」可摺疊回頂部。
安裝與啓用¶
前提：思源 3.8.x 桌面端保持運行（最小化到托盤亦可），DSH 0.2.x。
插件以當前 DSH 進程所在用戶的權限訪問本機思源內核；安裝前請自行審閱 源碼與 MIT 許可證。DSH 生態強調「一切皆插件」；skillhub.cn 爲社區目錄，與 DeepSeek / 幻方無官方從屬關係。
web / headless / 自建 profile¶
在對應 profile 下執行（命令出自項目 README）：
dsh plugin --profile web add github:YOGEMOW/dsh-siyuan
將 web 換成你的實際 profile 名稱。
desktop profile¶
桌面端 profile 由 Electron 獨佔，CLI 會拒絕 dsh plugin --profile desktop。需先把倉庫放到本地目錄，再在 DSH 會話裏用插件管理安裝 bundle：
git clone https://github.com/YOGEMOW/dsh-siyuan "<本地目錄>"
# 然後在 DSH 會話裏：
plugin_manager install_bundle target=<本地目錄>
安裝或卸載 bundle 後，Host 側需重啓對應 profile 纔會重新裝載；Client 側半刷新頁面後生效。
卸載：
plugin_manager remove_bundle target=@yogemow/dsh-siyuan
運行時無需額外 npm 依賴：fetch 用 Node 內置，React 由宿主提供。
配置¶
思源側¶
- 桌面端保持運行。
- 內核默認
http://127.0.0.1:6806；若改過端口，使用實際地址。 - 本機
127.0.0.1且未設訪問碼/鎖屏時可免 Token；否則在思源「設置 → 關於 → API token」複製，填入插件設置。
插件側¶
在 DSH「設置 → 思源筆記」或面板齒輪中配置。非 Token 項落在 $DSH_HOME/storages/siyuan/config.json。
| 項 | 默認 | 說明 |
|---|---|---|
| 內核地址 | http://127.0.0.1:6806 |
以 dsh 進程所在機器視角訪問 |
| API Token | 空 | 寫入 DSH 憑據庫（CredentialKey=siyuan），頁面不回顯；留空保存表示不修改 |
| 默認筆記本 | 空 | 寫入、日記、回答動作未指定筆記本時使用 |
| 默認打開文檔 | 空 | 22 位文檔 id 或精確路徑；首次打開且無當前筆記時自動打開 |
| 顯示對話區頁籤 | 開 | 關則對話區不再出現「思源筆記」頁籤 |
| 顯示輸入框按鈕 | 開 | 關則輸入框工具行不顯示「思源」按鈕 |
| 寫入開關 | 關 | 關則所有寫工具與寫路由禁用 |
配置好後可在設置頁使用「測試連接」驗證。
典型用法¶
直接對 Agent 發自然語言即可，例如（示例來自 README）：
- 「搜一下我記的 XX」
- 「把這篇筆記讀給我聽」
- 「把剛纔的結論存到 00-收件箱」
- 「今天日記裏追加一條：…」
側欄流程：搜索 → 預覽 → 在思源打開 / 追加 / 新建，可減少在 DSH 與思源窗口間來回切換。回答旁的「存入思源」只有你確認後纔會落庫。
安全模型與適用注意¶
- 僅使用內核公開 HTTP API；一期不做刪除、移動、重命名；不寫工作區文件。
- 寫入默認關閉；開啓後也只允許新建與追加，且回答寫入需二次確認。
siyuan_sql在插件側做單條 SELECT 預檢，並配合內核只讀 mode。- Token 只在 Host 進程內使用；
/siyuan/*路由不返回 Token；寫路由要求頭x-dsh-siyuan: 1。
適合誰： 已在用思源 3.8.x 做個人知識庫、希望在 DSH 裏讓 Agent 檢索與（在顯式開啓寫入時）更新筆記的開發者或重度用戶。
已知限制（節選）： 新建文檔後約 1 秒內索引未完成時讀取可能 404，可稍後重試；siyuan_read_doc 與面板預覽的行數上限策略不同；右欄「當前筆記」全局共享、不按會話隔離；左欄樹按單筆記本展示，無合併全庫樹。完整列表見 GitHub README「已知限制」。
結尾¶
dsh-siyuan 把思源留在內核 API 邊界之內，同時把檢索、閱讀、有條件的寫入和 Agentero 式右欄預覽放進同一會話。若你要在 DSH 裏以插件方式接本地筆記，可從社區目錄瞭解條目信息，並以 GitHub 倉庫 的安裝說明與 docs/ 文檔爲準部署與排錯。
