@yoursc/dsh-siyuan

Readme

# dsh-siyuan

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

- **模型侧**：17 个 `siyuan_*` 工具，按只读 / 写入 / 日记 / 危险四组开关控制，默认只开安全的两组。
- **设置页**：**设置 → 思源笔记**，填写思源地址与 API token、选择默认笔记本、按需打开工具分组。
- API token 存在宿主的凭据库里，**设置页永不回显它的值**。

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

## 安装

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

安装后**必须重启 dsh web** 才会加载插件：

```bash
docker restart deepseek-harness     # 或在 1Panel 里重启对应容器
```

插件是在 profile 组合树装载时注册的，新增/删除插件条目后重启是必需的。

## 配置

打开 **设置 → 思源笔记**，依次完成：

1. **思源地址**：默认 `http://127.0.0.1:6806`。注意这是**以 dsh 进程所在机器的视角**去访问的——
   思源和 dsh 不在同一台机器时，要填对方能访问到的地址。
2. **API token**：在**思源 → 设置 → 关于 → API token** 里复制，粘贴保存即可。保存后写入宿主凭据库；
   页面只显示「已配置 / 来源 / 可写」。如果 token 来自只读来源（例如启动 dsh 时设的环境变量），
   输入框会置灰并标注"只读"，需要去掉那个环境变量后重启才能在页面里改。
3. **默认笔记本**：点「加载笔记本」拉取列表后选择。写入、日记、按路径列文档默认用它；
   工具调用里也可以显式传 `notebook` 覆盖。
4. **工具分组**：按需勾选，点「保存设置」即时生效（**不需要重启**）。
5. **测试连接**：逐项探测系统版本、笔记本列表、SQL 查询，逐条显示成功或思源返回的错误原因。

## 工具分组

| 分组 | 默认 | 工具 |
|---|---|---|
| `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_*`**：如果同时装了另一个也用这个前缀的思源插件，同名工具会互相遮蔽。

## 已知限制

- 一次工具调用只处理一个文档/块；批量操作由模型多次调用完成。
- 读取类工具的输出没有额外大小上限，长文档会占用模型上下文。
- 删除没有二次回收确认：思源回收站能找回被删文档，插件不再拦截一次。
- SQL 工具只接受**单条 SELECT**；语句中间出现分号会被拒绝（包括字符串字面量里的分号）。

## 免责声明

非官方插件，与思源笔记（SiYuan）项目无隶属关系。写入与删除类工具会真实修改笔记库，
因此默认关闭；请在设置页按需开启，并留意你笔记库自身的整理规范。

## License

MIT