DSH 集成思源笔记

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

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

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

一、这是什么

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

• 二者都通过思源官方原生内核 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 处「系统/用户特定」路径需要改，其余代码通用。

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

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

为什么 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/<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> 包目录。

六、分系统复原步骤

通用前置

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 步：安装依赖

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 验收（见第七节）。

七、功能清单与验收

八、踩坑记录（避坑）

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:<port>/assets/...。
8. serve 重启竞态：stop 后不等待端口释放就 start 会 EADDRINUSE / 锁冲突，必须精确按 PID 杀 + 等端口释放再启。
9. 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 创建过程（三步，跨系统通用）

1. 建目录（DSH 约定位置）：

   # 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 约定（注册关键）

---
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 但互不依赖、互不冲突：一个在 profiles 下、一个在 skills 下，DSH 分别加载。