@terwer

dsh-siyuan-note

Name: dsh-siyuan-note
Availability: InStock
Author: terwer

integrate SiYuan Note as a DSH knowledge base

Stars: 1
Language: JavaScript
Created: Aug 21, 2026
Updated: Aug 21, 2026

Memory Web UI

GitHub repo

Introduction

DSH 集成思源笔记

把思源笔记（SiYuan Note）作为 DSH（DeepSeek Harness）的知识库集成，包含两个组件：

siyuan-note 插件（DSH 静态插件）：侧边栏浏览 / 搜索 / 渲染预览，一键启停内核服务。
siyuan-note skill（Agent skill）：让 Agent 通过思源官方 CLI 直连工作空间，做搜索、读写、快照、同步等操作。

二者都基于思源官方原生内核 CLI（SiYuan-Kernel），不依赖任何第三方库。详见下文各章节。

一、这是什么

把思源笔记（SiYuan Note）作为 DSH 的核心知识库，包含两个组件，各司其职：

组件	形态	作用	触发方式
① siyuan-note 插件	DSH 静态插件	主界面侧边栏「思源笔记」tab：浏览/搜索/渲染预览，一键启停 serve	每次 DSH 启动自动加载
② siyuan-note skill	Agent skill（SKILL.md）	让 Agent 通过官方 CLI 直连工作空间，做搜索/读写/快照/同步等操作	Agent 按需调用

二者都通过思源官方原生内核 CLI（SiYuan-Kernel）集成，不用任何第三方库。
插件：侧边栏 tab 可收起展开、不遮挡主界面，支持「笔记本 → 文档 → 内容」逐层浏览 + 全文搜索；一键启停 serve；配置走 DSH 统一设置（工作空间 / 只读 / 端口）。
skill：Agent 面向知识库的读写能力（全文/语义搜索、文档/块读写、SQL、快照、同步等），走 CLI 直连工作空间，无需 serve。

二、交付物清单（config / plugin / skill 三类并列）

DSH集成思源笔记/
├── README.md                   ← 本文件（复原指南）
├── config/                     ← ① 配置
│   ├── README.md               ←   配置说明 + settings 白名单 patch 步骤
│   └── profile-package.json    ←   DSH profile 主 package.json（声明依赖 + bundles）
├── plugin/                     ← ② 插件（完整、最新、已验证）
│   └── siyuan-note/
│       ├── package.json        ←   插件 manifest（含 exports "./package.json" 关键项）
│       ├── cordis.patch.yml    ←   host 侧 cordis patch（插入插件 id）
│       └── lib/
│           ├── index.js        ←   host half：serve 启停 / /siyuan 路由 / settings 注册
│           └── client.js       ←   client half：侧边栏 tab + 配置表单
└── skill/                      ← ③ skill（Agent 能力）
    └── siyuan-note/
        └── SKILL.md            ←   skill 定义（frontmatter + 用法），完整内容见第十章

三、跨系统路径对照表（★ 复原时必改项）

换系统时，只有下面 4 处「系统/用户特定」路径需要改，其余代码通用。

项	位置	macOS	Windows	Linux
① 思源内核 CLI	`index.js` 顶部 `const SY = ...`	`/usr/local/bin/siyuan`（或 `/Applications/SiYuan.app/Contents/Resources/kernel/SiYuan-Kernel`）	`C:\Program Files\SiYuan\resources\kernel\SiYuan-Kernel.exe`	`/opt/siyuan/resources/kernel/SiYuan-Kernel`
② PID 文件	`index.js` 顶部 `const PID_FILE = ...`	`/tmp/siyuan-note.pid`	`C:\Users\<你>\AppData\Local\Temp\siyuan-note.pid`	`/tmp/siyuan-note.pid`
③ 默认工作空间	`index.js` 顶部 `const DEFAULT_WORKSPACE = ...`	你的 workspace 绝对路径	你的 workspace 绝对路径	你的 workspace 绝对路径
④ DSH profile 目录	复原时插件拷贝目标	`~/.dsh/profiles/web/`	`%USERPROFILE%\.dsh\profiles\web\`	`~/.dsh/profiles/web/`

说明：③ 也可以通过 DSH 设置页（设置 → 插件 → 思源笔记 → 工作空间）直接改，无需动代码。①② 是代码内常量，换系统必须改。

四、敏感信息标注（★ 安全说明）

信息	是否敏感	位置	处理方式
思源 API token	⚠️ 敏感	每个 workspace 的 `conf/conf.json` → `api.token`	插件自动读取，绝不硬编码、绝不写进本包。换机器后各空间 token 各自不同，无需也不应手动配置
workspace 绝对路径	⚠️ 用户特定	`index.js` 的 `DEFAULT_WORKSPACE` + settings	含当前用户名，换机器必须改；建议直接走设置页配置
思源内核 CLI 路径	系统特定（非敏感）	`index.js` 的 `SY`	换系统改
PID 文件路径	系统特定（非敏感）	`index.js` 的 `PID_FILE`	换系统改

为什么 token 不能写死：思源每个工作空间有独立 token。写死成某个空间的 token 后，切换空间会 Auth failed，只读模式下笔记本被全部筛掉，表现为「数据全没了」（实际数据完好）。因此 token 一律从当前 workspace 的 conf/conf.json 自动读取，切换空间自动跟随，本仓库不包含任何 token。

五、DSH 对接方案（★ 原理与扩展点）

5.1 静态插件机制（核心）

DSH 静态插件 = 本地 npm 包 + 三处声明，DSH 启动时自动加载进 bundle：

cordis.patch.yml（host 侧 patch）：向 host 插件组插入插件 id。
```
- insert:
    - id: siyuan-note
      name: 'siyuan-note'
```

package.json 的 dsh 字段：

{
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": { "platform": "web", "inject": [] }
  }
}

profile 主 package.json 声明依赖 + 加入 bundles：

{
  "dependencies": { "siyuan-note": "file:./siyuan-note" },
  "dsh": { "profile": { "bundles": [ "...", "siyuan-note" ] } }
}

5.2 两个致命细节（缺一不可）

exports 必须含 "./package.json": "./package.json"：host 通过 require.resolve(pkg + "/package.json") 扫描 client 入口，缺这一行 client 不会进 bundle。
pnpm file: 依赖是「复制」不是软链：改源码后必须 rm -rf node_modules/siyuan-note && pnpm install 才同步。

5.3 host ↔ client 通信

host 注册 HTTP 路由：ctx.webServer.register({ kind: "prefix", path: "/siyuan", handler })。
- 前缀不能带尾斜杠（match 用 pathname.startsWith(prefix + "/")）。
- 不能占用 /api/*（那是 DSH 的扁平 RPC 网关，会 415 冲突）。
client 通过 fetch(location.origin + "/siyuan/<action>", { POST }) 调 host。
client 用 window.__ModuleLoader__.load({ id, factory }) 注册，factory 内 require("react") 拿 React，React.createElement 写 UI（无 JSX/构建转换）。

5.4 配置（settings）对接 —— 需改 DSH 核心包（★ 升级会覆盖）

DSH 当前版本尚未开放插件自定义配置暴露到设置页（源码注释明确标注 "deferred work"）。要让本插件的「工作空间/只读」出现在设置 → 插件 → 思源笔记，需改一处 DSH 核心包：

文件：<DSH安装>/node_modules/@deepseek-ai/dsh-host-apiproxy/lib/index.js
位置：const WEB_SETTINGS_NAMESPACES = [...] 白名单数组

改动：追加一行 "siyuan-note"

const WEB_SETTINGS_NAMESPACES = [
  "agent-loop", "shell", "locale", "permission",
  "ui-conversation", "ui-theme", "web-search-deepseek",
  "siyuan-note"   // ← 新增
];

⚠️ DSH 升级会覆盖此文件，升级后需重新加这一行。这是 DSH 当前的已知限制，非本插件缺陷。找不到 DSH 安装路径时：which dsh → 其软链指向 <DSH>/lib/bin.js，向上两级即 <DSH> 包目录。

六、分系统复原步骤

通用前置

已装 DSH（dsh web 用默认端口 3080）。
已装思源笔记桌面版（含内核 CLI）。

第 1 步：放插件源码

把本包 plugin/siyuan-note/ 整个拷贝到 DSH profile 插件目录：

# macOS / Linux
mkdir -p ~/.dsh/profiles/web
cp -R siyuan-note ~/.dsh/profiles/web/

# Windows（PowerShell）
mkdir $env:USERPROFILE\.dsh\profiles\web
Copy-Item -Recurse siyuan-note $env:USERPROFILE\.dsh\profiles\web\

第 2 步：改 3 处系统特定常量

编辑 ~/.dsh/profiles/web/siyuan-note/lib/index.js 顶部：

const SY = ... → 本系统的思源内核 CLI 路径（见第三节表）
const PID_FILE = ... → 本系统临时目录（Windows 不能用 /tmp）
const DEFAULT_WORKSPACE = ... → 你的 workspace 绝对路径（或之后在设置页改）

第 3 步：声明依赖 + bundles

把 config/profile-package.json 的内容合并进 ~/.dsh/profiles/web/package.json（即加 siyuan-note: file:./siyuan-note 到 dependencies，siyuan-note 到 bundles）。

第 4 步：安装依赖

cd ~/.dsh/profiles/web
rm -rf node_modules/siyuan-note && pnpm install   # 每次改源码后都要这样重装

第 5 步：改 settings 白名单（见 5.4）

给 dsh-host-apiproxy/lib/index.js 的 WEB_SETTINGS_NAMESPACES 加 "siyuan-note"。

第 6 步：重启 DSH（默认 3080 端口）

dsh web    # cwd 用 ~，端口默认 3080

重启后浏览器打开 http://127.0.0.1:3080 验收（见第七节）。

七、功能清单与验收

功能	说明	验收
侧边栏 tab 常驻	会话切换自动打开，无需拖动	每个会话侧边栏都有「📔思源笔记」tab
一键启停 serve	真启停后台思源内核进程	点「开启」变绿「已启动」，点「关闭」停止
笔记本→文档→内容	逐层递归展开	有子文档的显示 📁 可展开，叶子 📄 点击看内容
全文搜索	搜正文	输入关键词回车，结果可点击跳转文档
搜索重置	清空搜索结果	结果页有「✕ 清空」按钮
文档渲染	官方 lute 引擎渲染 kramdown→HTML	标题/列表/代码块/表格正常排版
资源文件显示	图片等改写为思源绝对地址	文档内图片正常显示（非 404）
只读模式	只读保护 workspace	默认 true，public 真实空间必须保持 true
token 自动读取	切换 workspace 自动跟随 token	切空间后数据正常，不 Auth failed

八、踩坑记录（避坑）

harness is not defined：动态 cordis 包才用 harness.handle，静态插件用 ctx.webServer.register。
/api/* 冲突：dsh 扁平 RPC 网关占用 /api，插件必须用别的前缀（本插件用 /siyuan）。
前缀尾斜杠：/siyuan/ 匹配不到，必须 /siyuan。
client 不加载：package.json 的 exports 缺 "./package.json" 时 require.resolve 失败。
pnpm 不同步：file: 依赖是复制，改码后必须 rm -rf node_modules/siyuan-note && pnpm install。
token 写死导致「数据全没了」：每个 workspace token 独立，写死某空间 token 后切空间会 Auth failed → 只读模式筛掉全部笔记本 → 显示 0 条。token 必须自动从 workspace conf.json 读。
资源文件 404：md2html 渲染的图片是相对路径 assets/...，浏览器用 DSH origin 解析会 404，必须改写为思源内核绝对地址 http://127.0.0.1:<port>/assets/...。
serve 重启竞态：stop 后不等待端口释放就 start 会 EADDRINUSE / 锁冲突，必须精确按 PID 杀 + 等端口释放再启。
DSH 重启：SIGTERM 对 DSH 无效，需 SIGKILL；pgrep -f "dsh web" 匹配不可靠，用 lsof -iTCP:3080 拿 PID 最稳。

九、附：思源官方 CLI 常用命令

siyuan --help                    # 查看全部子命令
siyuan serve -w <workspace> --port 6806 --readonly true   # 只读启动内核
siyuan serve -w <workspace> --port 6806                    # 可写启动

核心 API（供扩展参考，全部 POST，header Authorization: Token <api.token>）：

notebook/lsNotebooks — 笔记本列表
filetree/listDocsByPath {notebook, path} — 文档树
search/fullTextSearchBlock {query} — 全文搜索
block/getBlockKramdown {id} — 取 kmd（.sy 源码）
lute/md2html {markdown, mode} — 官方渲染 kramdown→HTML

十、siyuan-note skill（Agent 能力）—— 创建过程与完整内容

10.1 skill 是什么

DSH 的 skill = 一个目录 + 一个 SKILL.md，DSH 启动时自动扫描注册，Agent 按需调用。它让 Agent 能通过官方 CLI 直连工作空间，做插件 UI 做不到的事：写笔记、建快照、拉推同步、SQL 查询等。

10.2 创建过程（三步，跨系统通用）

建目录（DSH 约定位置）：

# macOS / Linux
mkdir -p ~/.dsh/skills/siyuan-note
# Windows（PowerShell）
mkdir $env:USERPROFILE\.dsh\skills\siyuan-note

放 SKILL.md：把本包 skill/siyuan-note/SKILL.md 复制到上述目录。
- 文件名必须叫 SKILL.md，目录名即 skill 名（siyuan-note）。
重启 DSH：DSH 启动时扫描 ~/.dsh/skills/*/SKILL.md，读取 YAML frontmatter 的 name + description 完成注册。重启后 Agent 即可按 description 触发该 skill。

10.3 SKILL.md 的 frontmatter 约定（注册关键）

---
name: siyuan-note
description: Use when the user wants to search, read, create, or organize notes in SiYuan (思源笔记) as a knowledge base through the official native `siyuan` kernel CLI. ...
---

name：skill 唯一标识（= 目录名，小写 kebab-case）。
description：触发条件，Agent 据此判断何时调用本 skill，务必写清楚"何时用、干什么"。
正文：给 Agent 的完整操作手册（安全铁律、命令速查、工作流）。

10.4 skill 完整内容（正文）

本包已附带 skill/siyuan-note/SKILL.md 全文（145 行，即第 10.2 步要复制的文件），核心要点如下：

基本信息：可执行文件 siyuan；每个命令必须显式 -w <workspace>；给机器解析一律 -f json；写操作先 --dry-run。
三个工作空间安全等级：
- 🧪 test（测试，可放心读写）
- 🛠 dev（开发，写入谨慎）
- 🔴 public（真实数据，默认只读，写入必须先征得用户同意）
安全铁律（8 条）：最高优先级是"每次写/维护操作后必须立即云端同步（sync pull → sync push）"；破坏性命令先 --dry-run；大改前先 repo create 建快照；CLI 无能力直接报告、禁止蛮干改数据库/配置文件。
十大工作流：全文/语义/资源搜索、列笔记本/文档、读文档全文、按标题定位、新建/追加/修改、日记、SQL 直查、反链/标签/属性、快照/历史、导入导出。
子命令速查：attr/bookmark/database/template/file/asset/sync/inbox/history/repo/serve/workspace 等。
注意事项：内核首跑会写 ~/.config/siyuan/；块 ID 形如 20240110144035-xxn8zfh；内部链接 [文本](siyuan://blocks/<id>)；勿与桌面端同时写同一工作空间；不确定参数先 siyuan <cmd> --help。

10.5 插件 vs skill 的分工（勿混淆）

	插件（siyuan-note）	skill（siyuan-note）
载体	`~/.dsh/profiles/web/siyuan-note/`	`~/.dsh/skills/siyuan-note/SKILL.md`
用户	人（点侧边栏 UI）	Agent（被 description 触发）
能力	浏览/搜索/预览/启停 serve（只读）	读写/快照/同步/SQL 等（可写，受安全铁律约束）
数据通道	HTTP serve + 思源 API	CLI 直连工作空间
是否需要 serve	是	否

二者同名 siyuan-note 但互不依赖、互不冲突：一个在 profiles 下、一个在 skills 下，DSH 分别加载。