Introduction

DeepSeek Harness (DSH) aims to provide a unified tool interface for model inference. When developing local agents, connecting to a local knowledge base is a common requirement. SiYuan Note, as a local-first knowledge management tool, provides the foundation for this connection through its HTTP API. The coolgech/dsh-siyuan plugin is a toolset built on this foundation, enabling agents to directly invoke SiYuan Note’s APIs and treat it as a personal knowledge base for reading, writing, and management.

Plugin Overview

The plugin is maintained by user coolgech, and its core function is to provide 30+ tools through the SiYuan kernel HTTP API (default address http://127.0.0.1:6806). These tools cover basic document CRUD, full-text search, SQL queries, backlink analysis, resource management, and batch import/export operations.

Technically, the plugin is developed based on the DSH official tool protocol (defineTool() + ctx.tools.register()). It uses Node.js native fetch, achieving zero runtime dependencies. At the same time, the plugin uniformly handles SiYuan API’s { code, msg, data } envelope format, HTTP errors, timeouts, and cancellation signals, reducing the probability of errors in upstream calls.

Installation

Before installation, ensure that DeepSeek Harness (dsh) and SiYuan Note are installed, and that the kernel HTTP API is enabled. It is recommended to use Node.js version >= 18.17.0.

Run the following command to complete installation:

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

After installation, the plugin will provide a configuration card in the settings interface. Configuration changes take effect immediately without requiring a restart.

Configuration

Configuring through the settings interface is the quickest way. After installation, go to:

Settings → Plugins → Plugin Config → SiYuan Note

Fill in the following parameters in the configuration card:

Config Item Type Default Description
baseUrl string http://127.0.0.1:6806 SiYuan kernel address
apiToken string '' SiYuan API Token (must be obtained from SiYuan “Settings → About”)
defaultNotebook string '' Default notebook ID or name
defaultPath string '/' Default directory path
timeoutMs number 15000 Request timeout (milliseconds)

You can also use a YAML config file:

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

Core Features

This plugin mainly provides the following capabilities:

  • Hierarchy management: Supports CRUD for notebooks, documents, and block-level content.
  • Search capabilities: Provides full-text search, tag search, and read-only SQL-based queries (siyuan_query_sql).
  • Relationship mapping: Supports retrieving backlinks, citation relationships, and document tree structure.
  • Asset management: Supports listing resource files and searching resource content.
  • Daily notes and templates: Provides daily note creation and appending, template lists, and batch Markdown import/export.
  • Metadata: Supports reading and setting block properties (custom metadata).
  • Technical characteristics:
    • Zero dependencies: Uses Node.js native fetch, no additional runtime libraries.
    • Instant activation: Configuration changes in the settings interface take effect without a restart.
    • Network support: Supports local 127.0.0.1 and LAN SiYuan instances.
    • Resolution methods: Supports resolving notebooks by ID or name.
    • Built-in tools: Provides a configuration card on the browser side.

Usage Examples

Tools registered by the plugin can be directly invoked by the agent. The following are typical invocation examples:

Search the knowledge base

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

Read a document

{
  "name": "siyuan_read_doc",
  "arguments": {
    "path": "/项目/周报"
  }
}

Batch import Markdown

{
  "name": "siyuan_batch_import_markdown",
  "arguments": {
    "notebook": "我的知识库",
    "docs": [
      { "path": "/项目/周报", "markdown": "# 周报\n\n- 事项一" },
      { "path": "/项目/月报", "markdown": "# 月报\n\n- 事项二" }
    ]
  }
}

Notes

Before using the plugin, pay attention to the following security and operational restrictions:

  1. SQL restrictions: siyuan_query_sql only allows statements starting with SELECT or WITH.
  2. Security and confidentiality: Do not commit real apiToken values to Git repositories. The SiYuan kernel listens on 127.0.0.1 by default. Do not expose Token-enabled ports to the public internet.
  3. Irreversible operations: Document deletion, moving, and renaming operations are irreversible. Invoke them with caution.
  4. Runtime environment: The plugin runs with the permissions of the current DSH process. It is recommended to review the source code and license before installation.

Conclusion

coolgech/dsh-siyuan establishes a stable connection channel between the DeepSeek Harness ecosystem and local knowledge bases. By providing standardized tool interfaces, it simplifies the complexity of agent interaction with SiYuan Note. For developers who need localized and private knowledge management, this is a directly deployable solution.

  • Plugin Directory: https://www.skillhub.cn/plugins/coolgech/dsh-siyuan
  • GitHub Repository: https://github.com/coolgech/dsh-siyuan