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