coolgech/dsh-siyuan

dsh-siyuan

DeepSeek Harness（dsh）插件：让 Agent 把思源笔记（SiYuan Note）当作个人知识库来使用。

通过思源内核 HTTP API（默认 http://127.0.0.1:6806），提供 30+ 个工具，覆盖：

- 笔记本 / 文档 / 块级管理
- 全文搜索、SQL 查询、标签搜索
- 反向链接 / 引用关系
- 资源文件与附件
- 每日笔记、模板、批量导入导出
- 属性 / 自定义元数据

特性

- 基于 dsh 官方工具协议：defineTool() + ctx.tools.register()
- 使用 Node.js 原生 fetch，零运行时依赖
- 统一处理思源 { code, msg, data } 信封、HTTP 错误、超时与取消信号
- 通过设置界面配置，修改后即时生效，无需重启
- 支持本机 127.0.0.1 与局域网思源实例
- 支持笔记本按 ID 或名称解析
- 内置浏览器端设置卡片

环境要求

- Node.js >= 18.17.0
- DeepSeek Harness（dsh）
- 已适配 DSH Desktop（桌面版）
- 思源笔记，并开启内核 HTTP API
- 建议使用最新稳定版思源

兼容性

- ✅ DeepSeek Harness Web
- ✅ DSH Desktop（桌面版）
- ✅ 思源笔记桌面版 / 局域网实例

安装

方式一：通过 git 安装（推荐）

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

方式二：通过 npm 安装

dsh plugin --profile web/desktop add dsh-siyuan

方式三：本地开发加载

dsh web --patch D:/path/to/dsh-siyuan/examples/local-dev.cordis.yml

配置

设置界面（推荐）

安装后打开：

设置 → 插件 → 插件配置 → 思源笔记

在配置卡片中填写：

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| baseUrl | string | http://127.0.0.1:6806 | 思源内核地址 |
| apiToken | string | '' | 思源 API Token（设置 → 关于 → API Token） |
| defaultNotebook | string | '' | 默认笔记本 ID 或名称 |
| defaultPath | string | '/' | 默认目录路径 |
| timeoutMs | number | 15000 | 请求超时（毫秒） |

配置文件

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

工具列表

基础笔记操作

| 工具 | 说明 |
| --- | --- |
| siyuan_list_notebooks | 列出笔记本 |
| siyuan_list_docs | 列出目录下文档 |
| siyuan_read_doc | 读取文档 Markdown |
| siyuan_create_doc | 创建文档 |
| siyuan_append_block | 追加内容 |
| siyuan_update_block | 更新块 |
| siyuan_query_sql | 执行只读 SQL |

知识库检索与关联

| 工具 | 说明 |
| --- | --- |
| siyuan_search | 全文搜索（支持排序/分组/高亮） |
| siyuan_get_backlinks | 反向链接 / 提及 |
| siyuan_list_assets | 列出资源文件 |
| siyuan_search_asset_content | 搜索资源内容 |
| siyuan_search_tag | 按标签搜索 |

文档整理

| 工具 | 说明 |
| --- | --- |
| siyuan_delete_doc | 删除文档 |
| siyuan_rename_doc | 重命名文档 |
| siyuan_move_doc | 移动文档 |
| siyuan_batch_export_markdown | 批量导出 Markdown |
| siyuan_batch_import_markdown | 批量导入 Markdown |

笔记本管理

| 工具 | 说明 |
| --- | --- |
| siyuan_create_notebook | 创建笔记本 |
| siyuan_rename_notebook | 重命名笔记本 |
| siyuan_remove_notebook | 删除笔记本 |

块级操作

| 工具 | 说明 |
| --- | --- |
| siyuan_get_block_children | 获取子块 |
| siyuan_get_block_info | 获取块信息 |
| siyuan_insert_block | 插入块 |
| siyuan_delete_block | 删除块 |
| siyuan_move_block | 移动块 |
| siyuan_get_block_attrs | 获取块属性 |
| siyuan_set_block_attrs | 设置块属性/标签 |

每日笔记 / 模板 / 文档树

| 工具 | 说明 |
| --- | --- |
| siyuan_create_daily_note | 创建/打开今日每日笔记 |
| siyuan_append_daily_note_block | 向每日笔记追加内容 |
| siyuan_list_doc_tree | 获取文档树 |
| siyuan_list_templates | 列出模板文档 |

示例

搜索知识库

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

读取文档

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

批量导入

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

安全说明

- siyuan_query_sql 只允许 SELECT / WITH 开头，但仍建议仅在受信任的本地环境使用。
- 请勿把真实 apiToken 提交到 Git。
- 思源内核默认只监听 127.0.0.1，请勿把带 Token 的端口暴露到公网。
- 删除/移动/重命名等操作不可逆，请谨慎调用。

开发

npm install
npm run build
npm test

发布

发布到 GitHub 和插件市场请参考：

- PUBLISHING.md

License

MIT