前言¶

在 DeepSeek Harness（DSH）里做知识库类智能体时，常见做法是另起服务、扫工作区文件，或直接碰 SQLite。思源笔记（SiYuan）本身提供内核 HTTP API（默认 http://127.0.0.1:6806），写入走内核事务层，索引与同步仍由思源负责。若希望模型能搜笔记、建文档、读块与追加内容，又不想在思源里再装插件、也不改 siyuan.db 文件，就需要一个挂在 DSH 侧、只调 API 的桥接插件。

下面介绍社区维护的 dsh-siyuan-api（仓库 SherinG-official/dsh-siyuan-api），在 SkillHub 目录中归类为「联网工具」。

这是什么¶

dsh-siyuan-api 是 DeepSeek Harness 的思源笔记插件：通过思源内核 HTTP API 搜索笔记、创建文档、读取与追加块内容，并支持对本地索引库执行只读 SQL。维护者为 SherinG-official；许可证 MIT；运行时仅依赖 Node 内置 fetch，不需要在思源侧安装插件，也不需要 Python。

与「直接读工作区 / 改数据库」相比，本插件刻意只走 API：所有写入经内核事务层，思源能正常做索引与同步。

核心功能¶

插件向 DSH 注册 5 个工具，并在有 HTTP 宿主时提供只读诊断路由 GET /dsh-siyuan-api/status（不回显 Token）。可选向系统提示词注入使用规范（配置 prompt: false 可关闭）。

错误处理上，思源未启动、鉴权失败、笔记本不存在等情况会以带原因码的可读 message 返回（如 SIYUAN_UNREACHABLE、SIYUAN_AUTH_FAILED 等），而不是抛异常打断整轮对话。只读 SQL 在插件侧做 SELECT/WITH 预检并补 LIMIT，请求内核时始终带 mode: "readonly"。

安装与启用¶

安装方式以 README 为准：从本地目录打 tarball，再装进目标 profile。不要凭仓库名拼接 dsh plugin add github:…；README 未给出该形式的一键安装命令。

从 tarball 安装（web / headless 等 profile）¶

路径中不要有空格（pnpm 的 file: 依赖会被空格切断）：

node <pnpm> pack --pack-destination C:/somewhere/no-spaces

dsh plugin --profile web add "file:C:/somewhere/no-spaces/dsh-siyuan-api-0.1.2.tgz"

dsh plugin add 会写入 profile 的 dependencies，并把包名加进 dsh.profile.bundles。装完重启该 profile 生效。

desktop profile¶

CLI 会拒绝 dsh plugin --profile desktop …（桌面 profile 由 Electron 独占）。可用手工改清单或包内脚本：

node scripts/add-to-profile.mjs \
  "$DSH_HOME/profiles/desktop/package.json" \
  "C:/somewhere/no-spaces/dsh-siyuan-api-0.1.2.tgz"

cd "$DSH_HOME/profiles/desktop" && pnpm install

改完重启 DSH Desktop。

环境与依赖¶

• Node：>=22.13.0（见 package.json 的 engines）。
• @deepseek-ai/dsh-tools、@deepseek-ai/cordis 等由 dsh 宿主提供，未写入插件 dependencies，避免 profile 的 pnpm install 去 npm 拉宿主私有包而失败。

配置¶

思源侧¶

1. 思源处于运行状态（托盘最小化仍可；完全退出则内核不可用）。
2. 确认内核地址：桌面端默认 127.0.0.1:6806；若改过端口或开启「网络伺服」，以「设置 → 关于」为准。
3. API Token：「设置 → 关于 → API token」。本机 127.0.0.1 且未设锁屏密码时可免鉴权，Token 可留空；有锁屏密码或非本机访问时必须填 Token。

插件配置¶

写入 profile 的 cordis.patch.yml 或使用设置页：

- id: dsh-siyuan-api
  name: dsh-siyuan-api
  config:
    apiUrl: http://127.0.0.1:6806
    token: ''
    timeoutMs: 15000
    maxRows: 64
    defaultNotebook: ''
    prompt: true
    debug: false

Token 也可放在环境变量 SIYUAN_TOKEN（配置文件优先）。patch 中可用 !!js，例如 token: !!js process.env.SIYUAN_TOKEN || ''，避免 Token 落盘。

自检¶

装好后可调用 siyuan_status，或在 web profile 访问：

http://127.0.0.1:<dsh端口>/dsh-siyuan-api/status

典型用法¶

探活与笔记本¶

先确认连通，再用 siyuan_notebooks 拿到准确的笔记本名称或 ID，供后续 notebook 参数使用。

搜索¶

siyuan_search 的 query 必填；mode 默认 keyword，在 blocks 的 content、name、alias、memo 等字段模糊匹配，返回块 ID、文档路径等，供 siyuan_block 或 siyuan_create_doc 的 parentID 使用。

mode=sql 时传入完整 SELECT，例如：

SELECT id, content, hpath, updated FROM blocks WHERE type = 'd' ORDER BY updated DESC LIMIT 10

单次返回条数受 limit 与配置项 maxRows（1–1000）约束。

新建文档¶

siyuan_create_doc：title 必填；notebook 不传则用 defaultNotebook；markdown 可省略以建空文档；parentID 优先于标题中的 / 层级写法。

读写块¶

siyuan_block：id 为 22 位块 ID，传文档 ID 即整篇文档。mode=read 默认；append / insert 需传 data，且必须显式 confirm: true，避免误写。

写入前建议 read 确认目标块，再带 confirm=true 落笔。

适用场景与注意¶

适合谁： 已在本地或局域网运行思源、希望 DSH 智能体把笔记当可检索、可写入的知识库，且接受「只经官方内核 API、不碰工作区文件」边界的人。

权限与安全： 插件以当前 DSH 进程权限运行，Token 与内核地址相当于对笔记库的访问凭据。安装前应自行查看 GitHub 源码 与 MIT 许可证；siyuan_block 的写入能力需结合 confirm 与业务策略使用。

生态说明： DSH 采用「一切皆插件」的扩展方式；SkillHub 插件目录 为社区站点，与 DeepSeek / 幻方无官方从属关系。

版本： 仓库 package.json 当前版本为 0.1.4；README 安装示例中的 tarball 文件名为 dsh-siyuan-api-0.1.2.tgz，打包后请以你本地 pnpm pack 生成的文件名为准。

结尾¶

dsh-siyuan-api 把思源笔记的能力收敛为 DSH 侧一组 HTTP API 工具：搜索、建文档、块级读写与只读 SQL，且不依赖思源插件或 Python。若你要在 Harness 里接本地思源，可按 README 打 tarball 安装、配好 apiUrl 与 Token，用 siyuan_status 或诊断路由做自检。

• 目录页：https://www.skillhub.cn/plugins/SherinG-official/dsh-siyuan-api
• 源码与文档：https://github.com/SherinG-official/dsh-siyuan-api