dsh-plugin-siyuan
思源笔记的 DSH 插件：检索笔记、创建与修改内容，多核心连接配置、逐端点授权和会话活动记录。提供五个业务工具及一个核心目录工具，并可将 697 条 HTTP 契约按用途整理为 663 个工具，与发现的 MCP 工具一起注册到工具箱，按会话选择开启。
0.6.0 配合 context-care 0.11.0，加入会话/预设接收范围、跨会话共享提醒次数、文本与可读 reasoning 触发。新增 siyuan_kernels 列出配置核心和当前选择；连接支持 PID 退出后的重新发现、多实例选择、远程故障恢复与明确的访问拒绝暂停。连接和活动界面重新整理，详情见 更新日志。
0.3.3 常规 HTTP 扩展工具收到标准 {code,msg,data} JSON 响应时，成功直接返回 data，失败返回 isError、HTTP status、内核 code、msg 和 data。文件、代理、SSE、直接 JSON 等特殊接口保持各自的原始响应；通用 siyuan_rpc 继续提供完整 HTTP 结果。
0.3.2 修复 .well-known 等路径分组的 ID 含非法字符而导致整批注册失败的问题，分组标题保留原始路径名称。HTTP 工具按路径末段命名，例如 siyuan_sql、siyuan_getBlockInfo；父路径用于分组，只有重名时才进入工具名。同路径、同处理函数的多种方法合并，优先 POST；不同用途的处理函数分别保留。工具名移除摘要 ID 与 HTTP 方法前缀。升级后需在工具箱重新开启新名字及分组，已有思源端点授权保持不变。
连接与凭据
插件加载后，从插件市场附近的思源图标进入主面板。核心连接页支持添加、编辑、停用和删除核心，设置默认核心，检查连接。右侧「思源活动」页可以为当前会话选择核心。调用时的目标顺序为工具参数 kernelId、会话选择、明确配置的默认核心；找不到目标或目标失效时拒绝，不挑另一核心。
每个核心可以配置本机 auto 或明确的 HTTP(S) 地址、超时、可选端口登记文件与 PID。远程地址支持代理路径前缀，禁止 URL 凭据、查询和片段。自动模式读取思源维护的账户主目录 .config/siyuan/port.json，不扫描端口。进入思源连接管理界面、工具调用、授权或提醒重连时都会核对实例。已绑定 PID 仍可用时保持连接；退出后如果只有一个可用实例，自动保存新的 PID 绑定。没有实例时保留配置，思源启动后可重新发现；多个候选时，在核心卡片点「刷新实例列表」再直接选择连接，无需手填 PID。首次绑定或切换 PID 会撤去旧授权与 MCP 发现目录；更换地址或登记文件同样重新授权。进行中的调用固定目标，不在故障后迁移或重放。
远程核心使用明确的 HTTP(S) 地址，支持代理路径前缀。无请求体的 GET/HEAD 在连接重置、临时 DNS 故障或 502/503/504 时最多重试一次，共用原请求的总超时与取消信号；Retry-After 不超过 1 秒时遵循该等待时间，更长等待直接返回原响应。401、403、429 直接交回调用方，保留限流响应与 Retry-After。POST 等业务请求与已开始消费的响应流不自动重放。网络错误显示具体错误码和处理提示，认证或证书错误交由修正配置处理。服务恢复后下一次主动调用即可重新连接；WS 默认每 30 秒发送协议 ping，下一轮仍未收到 pong 时关闭失联连接。普通网络断线按 1–30 秒退避重连，恢复后重新校准规则。
连接检查读取公开版本和只读笔记本接口，分别显示访问是否可用、是否发送了配置凭据。成功响应说明接口可访问；代理是否透传凭据需要核对代理配置。401 表示认证未通过，有配置 token 且响应为思源固定认证错误时提示 token 可能不匹配；403 表示身份权限或访问策略拒绝；429 表示限流。WS 使用独立的访问认证；握手拒绝、标准 unauthenticated 关闭和无效关闭帧分别显示对应原因。无效关闭帧归为协议错误，不据此判断 token 失效。
提醒读取或连接检查收到 401/403/429，以及 WS 明确访问拒绝或无效关闭帧时，暂停该核心的提醒读取和自动重连，管理页显示原因。刷新、重订阅、重命名、调整超时、停用再启用或保存同一个 token 都保留暂停。实际更新 token、地址、端口文件或 PID 且配置成功保存后恢复对应核心；只更新 token 保留端点授权，其他核心的暂停不变。管理页跳过暂停核心的自动检查，仍可人工点击「重新检查连接」核对访问。
API token 只由人工在密码框写入 DSH 的本机 credentials 服务，持久配置与活动记录不保存 token 值。凭据的存储与保护由 DSH 负责；本插件负责人工只写、宿主取用及模型输出过滤，不另建凭据存储层。编辑时只显示已配置状态，不回填原值；留空保留，填写新值替换，也可明确清除。工具参数不接受 token 或认证头，宿主向固定核心注入 Authorization: Token ...，不转发到重定向地址。
所有核心的已配置凭据共用输出过滤：CRUD、HTTP、插件 RPC、MCP、WS、管理返回和错误都经过安全投影，覆盖原值、JSON 字符串、URL 编码、base64/hex 及含凭据的整体编码响应。过滤依据是凭据服务登记的实际值，字段名不决定是否遮罩，审批数组、token 计数和凭据状态保持原有类型。MCP tools/call 的 content 与 prompts/get 的消息内容中，图片和音频字节只保留说明；structuredContent 等业务对象按普通数据处理。错误不转发原始异常对象、stack、cause 或请求配置。过滤作用于本插件的返回接口；本机文件访问和浏览器权限由宿主管理。
DSH 需要提供 tools、storageDomain 和 credentials 服务；两种询问策略使用 sandboxPolicy 读取会话模式，并在普通权限下使用 approval 请求批准。管理路由通过 connection.requestRejection 统一校验来源和身份，兼容 Web 与桌面端；变更请求使用 JSON。持久化或凭据服务不可用时失败关闭，不降级为允许。旧组合里的非空 token 在首次初始化时导入 credentials；应由人工清除旧组合中的明文配置，不要将其内容发送到会话。
端点授权
端点页提供 697 条来自思源 v3.8.6 的 HTTP 契约，支持按核心、协议、方法、授权状态筛选，搜索路径、方法、工具名和说明，并分页。MCP 工具通过人工点击「发现 MCP 工具」获取，仅进入该核心目录，不获得权限。扩展 HTTP、插件 RPC、MCP 方法和 WS 操作可人工声明入目录。
每个端点可单独设置以下四种权限，并确认具体核心与端点：
| 配置 | 普通权限下 | 完全权限下 |
|---|
每次询问，完全权限下拒绝（默认，ask） | 请求宿主批准 | 自动拒绝 |
每次询问，完全权限下授权（ask-full-access） | 请求宿主批准 | 自动通过 |
拒绝（deny） | 拒绝 | 拒绝 |
允许（allow） | 直接通过 | 直接通过 |
未配置、首次发现、重新绑定或声明的新端点默认使用 ask。升级保留已经显式保存的 deny、ask 和 allow。完全权限按宿主 sandboxPolicy 返回的实际会话模式判断；询问通过 approval.request() 请求一次性批准。无会话、无法取得模式或需要询问但审批不可用时停止执行；宿主 never 策略自动拒绝询问。批准期间配置改变也会停止派发。活动栏记录选定的端点配置，并区分完全权限自动拒绝、完全权限自动通过、直接允许、宿主批准、拒绝、取消和审批不可用。
授权键分别为：
- HTTP：方法与契约路径；未知路径使用具体路径。四个 CRUD 与同路径的原始 HTTP 共用授权。
- MCP：方法；
tools/call 还需具体工具名的独立授权。
- 插件 RPC：插件名与方法；批量调用另需
$batch，且先检查所有内部方法。
- WS：连接路径的
connect，发送操作另需该路径与具体 JSON cmd 的 send 权限。
- 连接状态：
connection/status。失效 PID 可自动恢复到唯一候选；多候选在连接管理页选择。
原始 HTTP 的 MCP、插件 RPC 和 WS 包裹路径不能代替具体方法授权。代理、事务等尚未解析内部效果的委托接口本阶段不开放。WS 二进制发送和无 cmd 的不透明消息不开放。编码或折叠等有歧义的端点路径拒绝执行。
本阶段是端点授权：允许覆盖该端点的全部可操作资源。文档、笔记本、文件路径等资源范围授权，以及内容来源、差异追踪和思源侧徽标尚未实现。
思源 callout 规则提醒
详细步骤见 规则编写教程：从创建原生 callout、编写触发条件，到正则与路径、优先级与互斥、去重、插件扩展和排错。思源 0.6.0 配合 context-care 0.11.0，支持指定会话/预设范围、多个会话共享持久额度、普通文本及可读 reasoning 模式触发，以及工具超时专属提醒。原有 v1/v2 声明继续可用。
思源可向公共 reminderRules 服务贡献规则。当前由 context-care 的已有 /requests Host 行提供服务，思源通过可选注入连接。开发时从 dsh-context-care/reminders 导入实际服务和规则类型，构建后运行时通过 Cordis 获取服务；没有该服务时，思源工具继续独立工作。
使用专属 callout 标记 [!DSH-REMINDER]，内部放一个 dsh-rule 代码块，其余正文就是提醒内容。标记归属公共提醒服务，其他插件的规则使用各自标记；单独出现 dsh-rule 不会注册为提醒。下面的声明在成功读取 .ts 或 .d.ts 后，于下一次自然模型请求前提醒：
> [!DSH-REMINDER] TypeScript 类型约定
>
> 禁止使用 `any`。类型暂不明确时使用 `unknown`，再缩小类型范围。
>
> ```dsh-rule
> format: reminder/v1
> id: typescript-no-any
> on: tool.succeeded
> when:
> tool: read
> arguments:
> file_path:
> regex: '\.ts$'
> flags: i
> deliver:
> model:
> once: surface
> ```
规则可以放在任意文档中，无需配置文档或块 ID。插件在现有已启用核心中自动执行以下检索，一次读取全部匹配块，并按会话现有的核心选择贡献规则。显式 LIMIT -1 避开思源在省略 LIMIT 时采用的默认返回条数：
SELECT id,root_id,type,subtype,markdown FROM blocks
WHERE type='callout' AND subtype='DSH-REMINDER'
ORDER BY id LIMIT -1
连接建立和重连时全量校准；平时按 WebSocket 通知刷新相关文档，空闲时不读 SQL。reminders.refreshMs 默认30秒，用于失败读取和容量候选重试。规则数量默认不限；在“会话规则 → 提醒容量”中可保存所有来源共用的总量上限（0表示不限），查看已注册数量及最近拒绝来源的数量和原因。设置持久保留；降低上限保留已有规则，只限制后续增长。超限更新保留该来源上一批已接受的规则，提高上限后在下次重试时直接注册已缓存候选，不重复读取和解析。示例 TypeScript 类型约定 已通过真实内核回读确认自定义 subtype。
提醒来源通过管理器的内部专用能力订阅推送并读取固定范围的提醒块，沿用已启用核心、实例绑定、凭据和配置生命周期；不需要为这些内部请求设置模型端点授权。模型工具和公共 invoke 调用仍执行原有逐端点审批。管理器每核心共享一条只读推送连接，普通网络断线后按1、2、4秒递增至30秒重连；认证、权限、限流和关闭帧协议错误按“连接与凭据”一节暂停，连接配置成功更新后恢复。每批读取前等待事务和索引队列完成；事务按 context.rootIDs 局部查询并合并快照，已知规则文档的子块编辑和新提醒标记都触发更新。范围不明、同步、移动及笔记本挂卸载做全量校准，无关状态通知不读取。扫描期间的新事件保留到下一批。未变块复用解析和校验结果，包括错误结果；一个坏块只暂停自己的规则。离线立即撤销来源，恢复后全量校准；读取或连接失败记入插件日志。
同一提醒仍在模型可见上下文时只投递一次；追加普通消息、再次读取文件或只修改正文都不会重复。提醒被压缩移除后，新读取事件可以再次触发。身份包含核心、块 ID 和规则 ID，移动到其他文档不改变身份。正文和标题可以修改，id 用于保持身份，省略时为 reminder。YAML 使用 1.2，拒绝重复键和 aliases，规则字段由服务统一校验。
when.condition 可以追加引擎 v2 条件树，读取插件分析器产出的 facts.<ref>；judge 可以引用插件注册的异步判定器。笔记中声明条件和引用，分析器/判定器的代码由插件注册。
会话记录
右侧「思源活动」显示当前会话的实际调用：时间、核心、具体端点、callId、operationId、解析出的文档或块 ID、耗时与结果。可过滤当前页、分页和刷新，核心选择与记录由宿主持久化。点击会话中的思源工具卡片打开右侧「思源活动」，参数与结果通过卡片上的独立按钮展开。侧栏「定位工具调用」切回聊天视图，自动加载目标历史、从外向内展开折叠组，并滚动到精确的工具调用卡片；PTC 子调用会连同根调用一起加载。定位期间显示等待状态；切换会话、发起新定位或卸载会取消旧定位。点击「思源连接管理界面」打开管理面板。
操作意图先持久化，再派发业务请求；不保存笔记正文或凭据。成功、失败、拒绝、已发送与结果不确定分别显示。通知和 WS 发送完成不等于内容效果已确认；网络中断后的写入不自动重发。已执行但结算记录失败时，工具结果明确提示勿重复写入。重载打断的运行记录标为结果不确定。旧版将审批明细错误替换为 [redacted] 的活动记录在加载时恢复为可读取结构，并标明明细已丢失；原调用结果和已有错误说明保留。
只有本机明确目标的资源 ID 才提供 siyuan://blocks/... 快速打开；远程核心只显示 ID，避免在本机打开另一个库的同名资源。没有解析出位置时如实显示未知，不推断完整影响范围。
工具箱协同
安装 dsh-tool-gateway v0.3.0 或更新版，在思源管理界面点击「注册全部 HTTP / MCP 工具」。管理界面显示可注册的 HTTP 工具数、MCP 工具数和实际注册数；HTTP 按父路径分为「思源 · block」「思源 · notebook」「思源 · query」等组，MCP 按核心分组。新组默认关闭，到右侧工具箱选择要在当前会话开启的工具或工具组。
工具箱开关决定当前会话能否使用工具；思源端点授权决定具体核心是否允许执行。注册与开启都不会自动授予端点权限。MCP 调用仍分别检查 tools/call 与具体工具名。697 条 HTTP 契约按路径与处理函数合并为 663 个工具：同用途方法优先 POST，其次 GET；rpc 等不同处理函数分别保留。其他方法仍可通过基础工具 siyuan_rpc 调用，执行原有端点授权与调用限制。
- HTTP 工具以
siyuan_ 加路径末段命名，例如 siyuan_sql；重名才增加父路径，例如 siyuan_setting_setSnippet 和 siyuan_snippet_setSnippet。动态路径及同路径的不同用途用处理函数名区分。说明保留实际方法与完整路径，可按接口路径搜索。参数 body 使用原始请求 schema 及完整 $defs，支持 query、动态路由的 pathParams 和业务 headers。kernelId 可显式指定核心，省略时使用会话选择或默认核心。
- MCP 工具直接使用发现的完整
inputSchema，参数就是该工具的原参数，固定调用发现它的核心。名称为 siyuan_mcp_<核心ID>_<工具名>，使不同核心的同名工具可区分；旧版目录缺少 schema 的记录会提示重新发现。
- 新目录注册后，重新发现 MCP 会新增、更新或撤回对应工具。核心改名更新组标题，更换地址或删除核心会撤回该核心的 MCP 目录。注册选择保存到本机，重启后自动恢复；网关卸载时撤回扩展工具，重新连接后恢复。
- 「撤回扩展工具」撤回 HTTP / MCP 注册并保存这一选择，五个基础工具继续可用。网关缺席时也可使用基础工具。
例如，搜索 /api/query/sql 的 HTTP 工具后，参数为：
{"body":{"stmt":"SELECT id, content FROM blocks WHERE type = 'd' LIMIT 10"},"kernelId":"local"}
HTTP 原始字节请求的 body 使用 base64。表单文件的名称填入 body 的对应契约字段，内容放入 files；/api/file/putFile 示例：
{"body":{"path":"/data/example.txt","file":"example.txt"},"files":[{"field":"file","name":"example.txt","base64":"aGk=","mimeType":"text/plain"}]}
工具名保持稳定，普通授权修改和再次同步不会重建未变化的工具，也不会覆盖工具箱保存的会话开关。HTTP / MCP 扩展调用同样在「思源活动」中记录实际生成工具名，可通过 callId 定位来源调用。
核心目录与五个业务工具
先调用 siyuan_kernels，参数为 {}，即可获得全部已配置核心的 id、name、enabled、apiUrl 和可选的绑定 kernelPid，以及 defaultKernelId、sessionKernelId、selectedKernelId。会话未指定时 sessionKernelId 为 null，有效选择采用默认核心；没有任何选择时为 null。停用核心仍在目录中，enabled 只表示配置开关。目录读取不探测在线状态，不扫描本机实例；即使没有默认核心或配置列表为空也可调用。返回的 ID 可用于业务工具的 kernelId。
| 工具 | action / channel | 用途 |
|---|
siyuan_kernels | 无参数 | 已配置核心目录、默认核心与当前会话选择 |
siyuan_query | notebooks、docs、search、sql、read、children | 笔记本、文档、全文搜索、SQL、块内容与子块 |
siyuan_create | doc、block、append | 创建 Markdown 文档、插块、追加 |
siyuan_update | block、rename_doc | 整块替换、改文档标题 |
siyuan_delete | block、doc | 删除块或文档 |
siyuan_rpc | http、contract、plugin、mcp、ws、connection | 通用连接操作与离线契约发现 |
五个业务工具可附带 kernelId；目录工具只接受空参数。contract 可离线发现契约和配置核心 ID，不连接内核，也不获得执行授权。示例中的 ID 需要替换为真实目标。
{"action":"notebooks","kernelId":"local"}
{"action":"docs","notebook":"20261011180000-abcdefg","limit":64,"offset":0}
{"action":"read","id":"20261011180001-abcdefg"}
{"action":"doc","notebook":"20261011180000-abcdefg","path":"/验收","markdown":"# 验收\n"}
{"action":"append","parentID":"20261011180001-abcdefg","data":"正文\n"}
{"action":"block","id":"20261011180002-abcdefg","data":"替换内容\n"}
{"action":"rename_doc","id":"20261011180001-abcdefg","title":"新标题"}
创建文档返回 docId，插块、追加和更新返回 blockIds，并以 blockIdScope: "transaction-operations" 标明这些是内核事务操作 ID。一段 Markdown 可生成多个块而只返回一个操作 ID；ID 数量不是写入块数。写入成功与否依据内核响应。内容空白保留，更新接受空字符串。插块至少需要 nextID、previousID 或 parentID；追加需要 parentID。CRUD 检查 HTTP 与内核 {code,msg,data} 信封，索引或同步可能稍后更新，不因查询暂时无结果重发写入。
{"channel":"contract","path":"/api/block/","limit":20,"includeSchema":true}
{"channel":"http","path":"/api/block/getBlockKramdown","method":"POST","body":{"id":"20261011180001-abcdefg"},"validate":true}
{"channel":"plugin","plugin":"my-plugin","method":"example.echo","params":{"text":"你好"}}
{"channel":"mcp","method":"tools/list"}
{"channel":"mcp","method":"tools/call","params":{"name":"实际发现的工具名","arguments":{}}}
{"channel":"ws","path":"/ws?app=my-app&id=my-session&type=main","messages":[],"durationMs":1000,"maxMessages":20}
{"channel":"connection","action":"status"}
HTTP 支持 JSON、text、base64、form、multipart 请求与文件上传，保留状态、响应头和信封，默认响应上限16MiB。validate 仅校验已知契约；未收录路径按具体方法与路径请求批准，也可在管理界面声明后设置权限。MCP 使用官方 SDK 1.32.1，协议上限2025-11-25。每个调用结束后释放临时 WS、RPC、MCP 连接。
公共服务与独立连接库
共享服务 siyuan 只提供经过授权和凭据投影的 invoke(toolName, arguments, execution?)：
export const inject = ["siyuan"];
export async function apply(ctx) {
const service = ctx.get("siyuan");
const result = await service.invoke("siyuan_query", { action: "notebooks", kernelId: "local" });
// 公共服务调用也需要端点授权；无 agent 时两种询问策略均拒绝执行。
}
execution 来自真实 DSH 工具执行上下文，用于关联会话、callId、取消与批准；模型工具不接收自填会话身份。公共服务不发布带 token 的 config、裸 HTTP/WS/RPC、SDK client 或流。
import { SiYuanConnection } from "dsh-plugin-siyuan/connection" 仍可用于独立传输库：完整 HTTP、WS、JSON-RPC、MCP 和流由调用者管理，最终 await connection.dispose()。独立库的权限策略和原始响应过滤由调用者负责；需要宿主端点授权与凭据过滤时，使用共享受控服务。
安装与开发
需要 Node.js >=22.19.0，包管理器 pnpm。宿主安装补丁不包含 token：
- id: dsh-plugin-siyuan
name: dsh-plugin-siyuan
config:
apiUrl: auto
timeoutMs: 15000
在 DSH 插件市场中使用以下 GitHub 来源安装或升级：
https://github.com/leolee9086/dsh-plugin-siyuan#v0.6.0
客户端通过 ./client 和 dsh.client 声明加载。构建将官方思源 SVG 嵌入客户端，与宿主 JS、类型声明、契约一起放入 lib/。Host 接线从正式 DSH 包导入开发类型，提醒接口使用 context-care v0.11.0 的公开类型，均以 import type 消除运行时依赖。
本地进度、交接与调查笔记统一放在 .local/notes/，临时命令日志放在 .local/logs/；预览与验证输出放在 artifacts/，安装包及独立消费者放在 releases/。这些目录由 Git 忽略。教程等可维护说明放在 docs/，发行所需的 lib/ 继续跟踪。
pnpm install
pnpm run check
node scripts/gen-contract.mjs /path/to/siyuan/kernel/apicontract/schema.json 3.8.6
test:behavior 执行严格 TypeScript 测试编译、独立行为与 React 组件测试；test:protocol 使用隔离 HTTP/WS/MCP 服务，覆盖扩展工具调用、连接恢复、鉴权限流暂停、凭据保存补偿和活动记录。运行版思源与真实 Host 的验收单独记录。详细范围见 测试说明。release:pack 执行检查并生成安装包；开发代码见 main 分支。
许可证与来源
Copyright (c) 2026 leolee9086。GNU AGPL 第 3 版或任何后续版本，AGPL-3.0-or-later，条款见 LICENSE。接口契约源自 SiYuan v3.8.6 的 kernel/apicontract/schema.json，由 生成脚本 提取转换。官方图标从思源 app/stage/icon.svg 原样复制，来源和版权见 NOTICE。
