dsh-siyuan

dsh-siyuan

把 思源笔记（SiYuan）接入 DeepSeek Harness：让模型能检索、读取、 写入你的笔记库，并提供一个独立设置页管理连接与权限。

• 模型侧：17 个 siyuan_* 工具，逐个工具开关（设置页里按只读 / 写入 / 日记 / 危险四组 展示，组标题上的开关可以整组开合）；默认只开只读与日记两组。
• 设置页：设置 → 思源笔记，四张卡——连接、API token、默认笔记本、工具开关。 每张卡各自保存（只提交本卡字段），改完地址不保存也能直接「测试地址」。
• API token 存在宿主的凭据库里，设置页永不回显它的值。

设置页长这样（整页截图：连接 / API token / 默认笔记本 / 工具开关；开关按只读、写入、 日记、危险四组排列，组标题上的大开关管整组，下面每个工具还有自己的小开关）：

想改这个插件、或了解它是怎么实现的，请读 docs/DEV.md。 各版本改了什么见 CHANGELOG.md。

安装

dsh plugin --profile web add @yoursc/dsh-siyuan

安装后必须重启 dsh web 才会加载插件——重启你启动 dsh web 的那个进程：

# 容器部署示例，容器名换成你自己的
docker restart <container>

插件是在 profile 组合树装载时注册的，新增/删除插件条目后重启是必需的。 从 0.0.x 升级到带逐工具开关的版本也要重启一次（宿主侧的配置形状变了）， 之后改设置页里的任何内容都只用刷新页面。

DSH 0.1.7 用户请用 0.0.3 及以上；DSH 0.2.1-rc.3 用户请用 0.0.4 及以上：0.1.7-alpha.1 起宿主内置的 undici 升级后，经代理 dispatcher 的响应不再自动解压（content-encoding 还会被丢掉），0.0.2 会因此报 「返回了非 JSON 响应（HTTP 200）」、所有工具都不可用；0.0.3 起改成自适应解码，新旧宿主 都能正常工作，0.0.4 另补充了 DSH 0.2.1-rc.3 的兼容声明。

配置

打开 设置 → 思源笔记，四张卡各管一件事，各自保存（按钮只提交本卡字段， 没有改动时是禁用的，改过会出现「撤销」）：

1. 连接 · 思源地址：默认 http://127.0.0.1:6806。注意这是以 dsh 进程所在机器的视角 去访问的——思源和 dsh 不在同一台机器时，要填对方能访问到的地址。改完点「保存地址」。 旁边的「测试地址」直接用你正在编辑的地址（不必先保存），并且只测地址：它不带 token 去问思源一个公开接口，所以结论只有三种——地址可用（附思源版本）、地址可达但思源要求 API token（琥珀色，不是地址错）、地址不通（附具体原因）。token 配没配对不去问它。
2. API token：在思源 → 设置 → 关于 → API token 里复制，粘贴后点「保存 token」。 保存后写入宿主凭据库。卡片标题上的徽标说明它的状态，例如 token 已配置 · 存在 dsh 凭据库 · 可在页面修改、token 已配置 · 来自环境变量 · 页面不可改、 token 未配置——徽标只报告状态，永不回显 token 的值。当 token 来自只读来源 （例如启动 dsh web 时设的环境变量 SIYUAN_TOKEN），输入框和保存/清除按钮会置灰， 想改成在页面里管理就去掉那个环境变量并重启 dsh web；「测试 token」在这种情况下仍然可用。 「测试 token」先试你刚填进来、还没保存的值（没填就用已保存的），结论分四种： 有效、思源拒绝了这个 token、连不上思源（token 未被验证）、其它错误。 测不通过也照常保存——你可能只是思源没启动，token 该存还得存。
3. 默认笔记本：打开这一页会自动拉一次笔记本列表（同样用正在编辑的地址），所以配置过 默认笔记本的话，再进来直接就能看到它的名字；拉不到时不会弹错误打扰你（列表还没回来时， 下拉里显示的是已保存的 id），可以点「刷新笔记本」重试。选好后点「保存笔记本」。 写入、日记、按路径列文档默认用它；工具调用里也可以显式传 notebook 覆盖。
4. 工具开关：每个工具一个椭圆开关，按只读 / 写入 / 日记 / 危险四组排列；整行都能点切换 （不必瞄准 34×20 的小圆钮，选中时按空格/回车也行；在行内拖选文字不会误切换）。组标题上的开关 可以整组开合（组内只开一部分时显示为"半开"），底部「全部停用」一键收回所有权限。 点「保存开关」即时生效（不需要重启 dsh）。
5. 底部「重新读取」从宿主重新拉一遍配置——会丢弃还没保存的改动（页脚会提示）。

工具分组

工具可以逐个开关；下表的分组只决定设置页里的排列与「新建时的默认值」：

分组	新建时默认	工具
read 只读	开	siyuan_list_notebooks、siyuan_search、siyuan_sql、siyuan_read_doc、siyuan_list_docs、siyuan_get_child_blocks、siyuan_get_block_attrs
write 写入	关	siyuan_create_doc、siyuan_append_block、siyuan_insert_block、siyuan_update_block、siyuan_set_block_attrs、siyuan_move_doc、siyuan_rename_doc
daily 日记	开	siyuan_daily_note（读写指定日期的日记，不存在时按笔记本的 dailyNoteSavePath 创建）
danger 危险	关	siyuan_delete_block（内容块）、siyuan_remove_doc（整篇文档）——都必须显式传 confirm=true

写入与危险组默认关闭，是因为这两组会真实修改你的笔记库。建议先只开 read 用一段时间， 确认模型检索/读取的表现符合预期，再逐个打开。

使用时的几个注意点

• 删除可以先放心试：siyuan_remove_doc 删掉的文档能在思源自己的回收站里找回。
• 改块内容一次只能一段：工具在传入多段 Markdown 时会明确提示"只写入了第一段"， 需要多段请让模型改用 siyuan_insert_block 逐段插入。
• 删除与更新都会复核：思源有时会"返回成功但没真的生效"（例如删除是异步落库）。 本插件会复查并在确实没生效时报错，不会给你一个假的成功。删除复核最长约 6 秒， 慢的时候成功信息里会注明实际耗时。
• 笔记本必须在思源里打开：往已关闭的笔记本写入会直接被拒绝并提示先打开它。
• 工具名固定为 siyuan_*：如果同时装了另一个也用这个前缀的思源插件，同名工具会互相遮蔽。
• 工具开关按工具名存：$DSH_HOME/storages/siyuan/config.json 里的 tools 是 { "siyuan_search": false, ... } 这样的逐工具记录。旧版本按组存的配置 （{ "read": true, ... }）继续生效，在新版设置页保存一次开关后会自动升级成逐工具记录。

已知限制

• 一次工具调用只处理一个文档/块；批量操作由模型多次调用完成。
• 读取类工具的输出没有额外大小上限，长文档会占用模型上下文。
• 删除没有二次回收确认：思源回收站能找回被删文档，插件不再拦截一次。
• SQL 工具只接受单条 SELECT；语句中间出现分号会被拒绝（包括字符串字面量里的分号）。
• 「测试地址」依赖思源 /api/system/version 是公开接口（实测 3.8.3 如此，替身也照此复刻）。 万一某个部署连它都要鉴权，页面会显示琥珀色的「地址可达但思源要求 API token」——不是 报地址错；这正是这个按钮只对"地址通不通"下结论、token 另设一个测试按钮的原因。
• 设置里的「思源笔记」导航图标是插件在外壳 DOM 上替换出来的（DSH 目前没有自定义导航图标 的接口，第三方分区默认都是齿轮）。上游哪天提供接口、或改了设置面板结构，这个替换会静默失效—— 表现只是退回齿轮，不影响设置页任何功能。

免责声明

非官方插件，与思源笔记（SiYuan）项目无隶属关系。写入与删除类工具会真实修改笔记库， 因此默认关闭；请在设置页按需开启，并留意你笔记库自身的整理规范。 设置导航使用的思源图标取自思源官方仓库（app/src/assets/icon.svg）， 仅用于标识本插件对接的对象。

License

MIT