DeepSeek Harness 插件：coolgech/dsh-siyuan

前言¶

DeepSeek Harness（DSH）旨在爲模型推理提供統一的工具接口。在開發本地化智能體時，連接本地知識庫是一個常見需求。思源筆記（SiYuan Note）作爲一款本地優先的知識管理工具，其 HTTP API 爲這種連接提供了基礎。coolgech/dsh-siyuan 插件即是在此基礎上構建的工具集，它讓 Agent 能夠直接調用思源筆記的接口，將其視爲個人知識庫進行讀寫與管理。

插件介紹¶

該插件由用戶 coolgech 維護，核心功能是通過思源內核 HTTP API（默認地址 http://127.0.0.1:6806）提供 30+ 個工具。這些工具覆蓋了從文檔的基礎增刪改查，到全文檢索、SQL 查詢、反向鏈接分析，以及資源管理和批量導入導出等操作。

在技術實現上，插件基於 DSH 官方工具協議（defineTool() + ctx.tools.register()）開發。它使用 Node.js 原生 fetch，實現了零運行時依賴。同時，插件統一處理了思源 API 的 { code, msg, data } 信封格式、HTTP 錯誤、超時以及取消信號，降低了上層調用的出錯概率。

安裝¶

安裝前請確保已安裝 DeepSeek Harness（dsh）以及思源筆記，並已開啓內核 HTTP API。建議使用 Node.js 版本 >= 18.17.0。

執行以下命令即可完成安裝：

dsh plugin --profile web/desktop add https://github.com/coolgech/dsh-siyuan.git

安裝完成後，插件會在設置界面提供配置卡片，修改配置後即時生效，無需重啓。

配置¶

通過設置界面配置是最快捷的方式。安裝後進入：

設置 → 插件 → 插件配置 → 思源筆記

在配置卡片中填寫以下參數：

你也可以使用 YAML 配置文件進行配置：

- id: dsh-siyuan
  name: dsh-siyuan
  config:
    baseUrl: http://127.0.0.1:6806
    apiToken: "你的思源 API Token"
    defaultNotebook: ""
    defaultPath: "/"
    timeoutMs: 15000

核心功能¶

該插件主要提供以下能力：

• 層級管理：支持筆記本、文檔及塊級內容的增刪改查。
• 檢索能力：提供全文搜索、標籤搜索，以及基於 SQL 的只讀查詢（siyuan_query_sql）。
• 關係梳理：支持獲取反向鏈接、引用關係以及文檔樹結構。
• 資產管理：支持列出資源文件、搜索資源內容。
• 日常與模板：提供每日筆記創建與追加、模板列表以及批量 Markdown 導入導出。
• 元數據：支持讀取和設置塊的屬性（自定義元數據）。
• 技術特性：
  • 零依賴：使用 Node.js 原生 fetch，無額外運行時庫。
  • 即時生效：設置界面修改配置後無需重啓。
  • 網絡支持：支持本機 127.0.0.1 以及局域網思源實例。
  • 識別方式：支持通過 ID 或名稱解析筆記本。
  • 內置工具：提供瀏覽器端的設置卡片。

使用示例¶

插件註冊的工具可直接被 Agent 調用。以下爲典型調用示例：

搜索知識庫

{
  "name": "siyuan_search",
  "arguments": {
    "query": "知識管理",
    "limit": 10,
    "highlight": true
  }
}

讀取文檔

{
  "name": "siyuan_read_doc",
  "arguments": {
    "path": "/項目/週報"
  }
}

批量導入 Markdown

{
  "name": "siyuan_batch_import_markdown",
  "arguments": {
    "notebook": "我的知識庫",
    "docs": [
      { "path": "/項目/週報", "markdown": "# 週報\n\n- 事項一" },
      { "path": "/項目/月報", "markdown": "# 月報\n\n- 事項二" }
    ]
  }
}

注意事項¶

在使用插件前，需注意以下安全與操作限制：

1. SQL 限制：siyuan_query_sql 僅允許 SELECT 或 WITH 開頭的語句。
2. 安全保密：請勿將真實的 apiToken 提交到 Git 倉庫；思源內核默認監聽 127.0.0.1，請勿將帶 Token 的端口暴露至公網。
3. 操作不可逆：文檔的刪除、移動、重命名等操作不可逆，調用時需謹慎。
4. 運行環境：插件以當前 DSH 進程的權限運行，建議在安裝前檢查源碼與許可證。

結語¶

coolgech/dsh-siyuan 爲 DeepSeek Harness 生態與本地知識庫之間建立了一條穩固的連接通道。通過提供標準化的工具接口，它簡化了智能體與思源筆記交互的複雜度。對於需要本地化、私有化知識管理的開發者而言，這是一個可以直接落地的解決方案。

• 插件目錄: https://www.skillhub.cn/plugins/coolgech/dsh-siyuan
• GitHub 倉庫: https://github.com/coolgech/dsh-siyuan