yoursc/dsh-siyuan

dsh-siyuan

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

- 模型侧：17 个 siyuan_ 工具，逐个工具开关（设置页里按只读 / 写入 / 日记 / 危险四组
展示，组标题上的开关可以整组开合）；默认只开只读与日记两组。
- 设置页：设置 → 思源笔记，四张卡——连接、API token、默认笔记本、工具开关。
每张卡各自保存（只提交本卡字段），改完地址不保存也能直接「测试连接」。
- 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

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

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

配置

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

1. 连接 · 思源地址：默认 http://127.0.0.1:6806。注意这是以 dsh 进程所在机器的视角
去访问的——思源和 dsh 不在同一台机器时，要填对方能访问到的地址。改完点「保存地址」。
旁边的「测试连接」直接用你正在编辑的地址（不必先保存），逐项探测系统版本、笔记本列表、
SQL 查询，并显示实际探测的地址。
2. API token：在思源 → 设置 → 关于 → API token 里复制，粘贴后点「保存 token」。
保存后写入宿主凭据库。卡片标题上的徽标说明它的状态，例如
token 已配置 · 存在 dsh 凭据库 · 可在页面修改、token 已配置 · 来自环境变量 · 页面不可改、
token 未配置——徽标只报告状态，永不回显 token 的值。当 token 来自只读来源
（例如启动 dsh web 时设的环境变量 SIYUAN_TOKEN），输入框和保存/清除按钮会置灰，
想改成在页面里管理就去掉那个环境变量并重启 dsh web。「测试连接」也会用你刚填进来、
还没保存的 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；语句中间出现分号会被拒绝（包括字符串字面量里的分号）。
- 设置里的「思源笔记」导航图标是插件在外壳 DOM 上替换出来的（DSH 目前没有自定义导航图标
的接口，第三方分区默认都是齿轮）。上游哪天提供接口、或改了设置面板结构，这个替换会静默失效——
表现只是退回齿轮，不影响设置页任何功能。

免责声明

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

License

MIT