dsh-siyuan

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# dsh-siyuan

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

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

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

![思源笔记设置页：连接、API token、默认笔记本、工具开关](assets/settings-overview.png)

> 想改这个插件、或了解它是怎么实现的，请读 [`docs/DEV.md`](docs/DEV.md)。

## 安装

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

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

```bash
# 容器部署示例，容器名换成你自己的
docker restart
```

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

## 配置

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

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`](https://github.com/siyuan-note/siyuan/blob/master/app/src/assets/icon.svg)），
仅用于标识本插件对接的对象。

## License

MIT