前言¶
在 DeepSeek Harness（DSH）里做智能体时，知识往往落在本地笔记里，而对话界面和笔记窗口通常是两套应用。你只能自己复制粘贴，或者让 Agent 去碰工作区里的 .sy 文件和 siyuan.db，风险和权限都不好控。
@yogemow/dsh-siyuan（仓库 YOGEMOW/dsh-siyuan）走另一条路：全部通过思源桌面内核的公开 HTTP API 与笔记本交互，不读写工作区文件。Agent 侧提供 9 个工具用于检索与读写；客户端侧提供左栏文档树、右栏边聊边读的笔记视图，以及把助手回答确认后写入思源。维护者为 YOGEMOW，在社区目录 skillhub.cn 中归类为客户端插件。
下面按定位、能力、安装配置、用法与注意点说明如何在 DSH 0.2.x 环境下使用（思源侧需 3.8.x 桌面端在运行）。
这是什么¶
包名 @yogemow/dsh-siyuan，当前版本 0.3.5，许可证 MIT。入口分为 Host 侧 index.js（Agent 工具与 /siyuan/* 路由）和 Client 侧 client.js（侧栏、设置、回答动作）。设计细节见仓库内 docs/DESIGN.md、docs/KERNEL-NOTES.md、docs/CONTRACT.md。
一句话定位：把思源笔记接入 DSH，让 Agent 能搜读写作业记，并在界面里按文档树浏览、在右栏预览，回答可二次确认后存入思源。
核心功能¶
Agent 工具（9 个，默认只读）¶
写入能力受插件「写入开关」约束；关闭时写工具与写路由返回 SIYUAN_WRITE_DISABLED。
| 工具 | 作用 | 读/写 |
|---|---|---|
siyuan_status |
连通性、版本、Token 状态、写入开关、笔记本清单 | 读 |
siyuan_notebooks |
笔记本列表（id/名称/文档数） | 读 |
siyuan_search |
全库检索（正文/标题/别名/备注子串） | 读 |
siyuan_read_doc |
读文档 Markdown，行分页（工具默认约 400 行） | 读 |
siyuan_recent |
最近更新的文档 | 读 |
siyuan_sql |
只读 SQL（单条 SELECT，内核 mode:'readonly'） |
读 |
siyuan_create_doc |
新建文档（可指定父文档） | 写 |
siyuan_append |
追加或前后插入；id="daily" 写今日日记 |
写 |
siyuan_open |
生成 siyuan:// 深链 / Web 链接 / 块引用 |
读 |
界面与交互¶
- 左栏「思源笔记」：笔记本下拉、可折叠文档树（顺序与思源一致，默认展开 8 层，更深层懒加载）、关键词搜索（有词时切平铺结果）、新建文档、设置抽屉。点笔记默认在右栏打开。
- 右栏「思源笔记」标签（Agentero 风格）：笔记本、文档树、正文预览，以及「在思源打开」「复制块链接」「追加内容」「新建文档」。左栏点笔记会直接在右栏展示；右栏不可用则退回左栏内联预览。
- 输入框工具行「思源」按钮：随时打开右栏笔记视图。
- 每条助手回答下方「存入思源」：选笔记本、标题（缺省取首行）、可追加到已有文档，仅在你点「确认存入」后写入。
正文预览默认一次读 1500 行，超过可「加载更多」按 offset 续读。文档树会记住展开、选中与滚动（左右栏、按笔记本分开）；顶栏「重置」可折叠回顶部。
安装与启用¶
前提：思源 3.8.x 桌面端保持运行（最小化到托盘亦可），DSH 0.2.x。
插件以当前 DSH 进程所在用户的权限访问本机思源内核；安装前请自行审阅 源码与 MIT 许可证。DSH 生态强调「一切皆插件」；skillhub.cn 为社区目录，与 DeepSeek / 幻方无官方从属关系。
web / headless / 自建 profile¶
在对应 profile 下执行（命令出自项目 README）：
dsh plugin --profile web add github:YOGEMOW/dsh-siyuan
将 web 换成你的实际 profile 名称。
desktop profile¶
桌面端 profile 由 Electron 独占，CLI 会拒绝 dsh plugin --profile desktop。需先把仓库放到本地目录，再在 DSH 会话里用插件管理安装 bundle：
git clone https://github.com/YOGEMOW/dsh-siyuan "<本地目录>"
# 然后在 DSH 会话里：
plugin_manager install_bundle target=<本地目录>
安装或卸载 bundle 后，Host 侧需重启对应 profile 才会重新装载；Client 侧半刷新页面后生效。
卸载：
plugin_manager remove_bundle target=@yogemow/dsh-siyuan
运行时无需额外 npm 依赖：fetch 用 Node 内置，React 由宿主提供。
配置¶
思源侧¶
- 桌面端保持运行。
- 内核默认
http://127.0.0.1:6806；若改过端口，使用实际地址。 - 本机
127.0.0.1且未设访问码/锁屏时可免 Token；否则在思源「设置 → 关于 → API token」复制，填入插件设置。
插件侧¶
在 DSH「设置 → 思源笔记」或面板齿轮中配置。非 Token 项落在 $DSH_HOME/storages/siyuan/config.json。
| 项 | 默认 | 说明 |
|---|---|---|
| 内核地址 | http://127.0.0.1:6806 |
以 dsh 进程所在机器视角访问 |
| API Token | 空 | 写入 DSH 凭据库（CredentialKey=siyuan），页面不回显；留空保存表示不修改 |
| 默认笔记本 | 空 | 写入、日记、回答动作未指定笔记本时使用 |
| 默认打开文档 | 空 | 22 位文档 id 或精确路径；首次打开且无当前笔记时自动打开 |
| 显示对话区页签 | 开 | 关则对话区不再出现「思源笔记」页签 |
| 显示输入框按钮 | 开 | 关则输入框工具行不显示「思源」按钮 |
| 写入开关 | 关 | 关则所有写工具与写路由禁用 |
配置好后可在设置页使用「测试连接」验证。
典型用法¶
直接对 Agent 发自然语言即可，例如（示例来自 README）：
- 「搜一下我记的 XX」
- 「把这篇笔记读给我听」
- 「把刚才的结论存到 00-收件箱」
- 「今天日记里追加一条：…」
侧栏流程：搜索 → 预览 → 在思源打开 / 追加 / 新建，可减少在 DSH 与思源窗口间来回切换。回答旁的「存入思源」只有你确认后才会落库。
安全模型与适用注意¶
- 仅使用内核公开 HTTP API；一期不做删除、移动、重命名；不写工作区文件。
- 写入默认关闭；开启后也只允许新建与追加，且回答写入需二次确认。
siyuan_sql在插件侧做单条 SELECT 预检，并配合内核只读 mode。- Token 只在 Host 进程内使用；
/siyuan/*路由不返回 Token；写路由要求头x-dsh-siyuan: 1。
适合谁： 已在用思源 3.8.x 做个人知识库、希望在 DSH 里让 Agent 检索与（在显式开启写入时）更新笔记的开发者或重度用户。
已知限制（节选）： 新建文档后约 1 秒内索引未完成时读取可能 404，可稍后重试；siyuan_read_doc 与面板预览的行数上限策略不同；右栏「当前笔记」全局共享、不按会话隔离；左栏树按单笔记本展示，无合并全库树。完整列表见 GitHub README「已知限制」。
结尾¶
dsh-siyuan 把思源留在内核 API 边界之内，同时把检索、阅读、有条件的写入和 Agentero 式右栏预览放进同一会话。若你要在 DSH 里以插件方式接本地笔记，可从社区目录了解条目信息，并以 GitHub 仓库 的安装说明与 docs/ 文档为准部署与排错。
