terwer/dsh-siyuan-note

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：

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

2. package.json 的 dsh 字段：
{
"dsh": {
"bundle": { "patch": "./cordis.patch.yml" },
"client": { "platform": "web", "inject": [] }
}
}

3. 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/", { POST }) 调 host。
- client 用 window.__ModuleLoader__.load({ id, factory }) 注册，factory 内 require("react") 拿 React，React.createElement 写 UI（无 JSX/构建转换）。

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

DSH 当前版本尚未开放插件自定义配置暴露到设置页（源码注释明确标注 "deferred work"）。要让本插件的「工作空间/只读」出现在 设置 → 插件 → 思源笔记，需改一处 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 → 其软链指向 /lib/bin.js，向上两级即  包目录。

六、分系统复原步骤

通用前置
1. 已装 DSH（dsh web 用默认端口 3080）。
2. 已装思源笔记桌面版（含内核 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 步：安装依赖
bash
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 端口）bash
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 |

八、踩坑记录（避坑）

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

九、附：思源官方 CLI 常用命令
bash
siyuan --help                    # 查看全部子命令
siyuan serve -w  --port 6806 --readonly true   # 只读启动内核
siyuan serve -w  --port 6806                    # 可写启动

核心 API（供扩展参考，全部 POST，header Authorization: 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 创建过程（三步，跨系统通用）

1. 建目录（DSH 约定位置）：
bash
macOS / Linux
mkdir -p ~/.dsh/skills/siyuan-note
Windows（PowerShell）
mkdir $env:USERPROFILE\.dsh\skills\siyuan-note

2. 放 SKILL.md：把本包 skill/siyuan-note/SKILL.md 复制到上述目录。
- 文件名必须叫 SKILL.md，目录名即 skill 名（siyuan-note）。

3. 重启 DSH：DSH 启动时扫描 ~/.dsh/skills/*/SKILL.md，读取 YAML frontmatter 的 name + description 完成注册。重启后 Agent 即可按 description 触发该 skill。

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

name: siyuan-note

description: 当用户想要通过官方原生 siyuan 内核 CLI 在思源笔记（SiYuan）中搜索、阅读、创建或整理笔记作为知识库时使用。...

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

10.4 skill 完整内容（正文）

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

- 基本信息：可执行文件 siyuan；每个命令必须显式 -w ；给机器解析一律 -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  --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 分别加载。