siyuan-skill

siyuan-skill

一个以 SKILL.md 为核心的 SiYuan HTTP API skill 仓库。

它的目标不是把仓库做成“只有某个平台能跑的专用实现”，而是让 AI / Agent 真正拿来就能用：

• 先读取 skills/siyuan/SKILL.md
• 再把自然语言需求归一化为结构化请求
• 然后按安全边界直连 SiYuan HTTP API
• 最后把结果统一汇报给用户

仓库定位

这个仓库适合以下场景：

• 你想让任意 AI 助手操作思源
• 你需要一份带 SKILL.md 的可复用 skill 入口
• 你希望 AI 自动完成参数整理、接口调用、结果汇报

这个仓库的核心是 skill 本体，不是某个单一平台的私有实现。

它主要包含：

• skills/siyuan/SKILL.md：主 skill 文档，读它就知道怎么请求 API
• skills/siyuan/scripts/invoke.mjs：本地执行入口
• skills/siyuan/lib/：HTTP client、action router 与 helper
• skills/siyuan/config/：默认配置与示例配置
• .claude-plugin/：面向 Claude Code / 类似插件生态的打包元数据，方便通过 git 安装；不是 skill 本体
• 本 README：扩展参考手册，用于补充完整协议与安全边界

如何使用

通常优先这样使用：

• 先把 skills/siyuan/SKILL.md 当作 skill 主文档
• 再把本 README 当作扩展参考手册
• 若你的环境支持 Claude Code 风格插件安装，可直接使用仓库内 .claude-plugin/
• 若你的环境不识别 .claude-plugin/，可复用 SKILL.md、scripts/invoke.mjs 与 lib/ 中的协议和运行逻辑，但需要自行适配 $ARGUMENTS、${CLAUDE_SKILL_DIR} 等 Claude 风格运行上下文

核心目标是让 AI 先把用户请求整理成统一结构：

{"action":"...","params":{...}}

然后再根据 action 去调用对应的 SiYuan HTTP API。

---

仓库结构

• .claude-plugin/marketplace.json：供 Claude Code / 类似生态识别仓库插件元数据
• .claude-plugin/plugin.json：插件清单
• skills/siyuan/SKILL.md：skill 主入口
• skills/siyuan/scripts/invoke.mjs：执行脚本
• skills/siyuan/lib/*.mjs：请求与 action 实现
• skills/siyuan/config/siyuan.config.example.json：示例配置
• skills/siyuan/config/siyuan.defaults.json：非敏感默认配置
• skills/siyuan/config/siyuan.config.local.json：本机私有配置文件，需自行创建，且已被 .gitignore 忽略

配置约定

为了避免 secret 泄露，建议 AI 运行环境按以下方式提供配置：

• 优先使用环境变量：
  • SIYUAN_BASE_URL 或 SIYUAN_API_URL
  • SIYUAN_TOKEN
  • 可选：SIYUAN_ALLOW_REMOTE
  • 可选：SIYUAN_TIMEOUT_MS
  • 可选：SIYUAN_DEFAULT_LIMIT
  • 可选：SIYUAN_MAX_LIMIT
• 若使用文件配置：
  • 复制 skills/siyuan/config/siyuan.config.example.json
  • 保存为 skills/siyuan/config/siyuan.config.local.json
  • 只在这个 local 文件中填写真实 Token / allowRemote
• skills/siyuan/config/siyuan.defaults.json 只用于非敏感默认值，不应写入真实 Token 或远程放行配置

安全要求

• 不要在提示词、日志、命令行参数中回显 Token
• 不要让 AI 猜测 Token、notebookId、id、path、sql、attrs
• 默认只允许连接本地思源地址
• 如果必须连接远程思源地址，必须由用户显式授权，且必须使用 https://
• 不要把自然语言直接拼接成高风险 SQL 或写操作请求

---

输入协议

方式 1：结构化 JSON（推荐）

{"action":"get_doc_tree","params":{"notebookId":"...","path":"/2026工作日记","maxDepth":2}}

规则：

1. 根节点必须是对象
2. action 必须是非空字符串
3. params 必须是对象
4. 缺参数时先追问，不要猜值
5. 参数齐全后再发起请求

方式 2：自然语言入口

示例：

• 列出所有笔记本
• 检查 /2026工作日记/2026-03 是否存在
• 导出这个文档的 Markdown，id 是 20250317123456-abc123

规则：

1. 先把自然语言归一化为 action + params
2. 只有在语义明确、关键参数齐全时才执行
3. 缺关键参数时先问用户
4. 删除、移动、覆盖、写 SQL 等高风险操作先确认
5. 对有副作用的 action，只有在用户已明确确认后，才可在最终 JSON 中加入 params.confirmed=true
6. 对写 SQL，只有在用户已明确授权时，才可同时加入 params.allowWrite=true 与 params.confirmed=true

---

建议的 HTTP 调用方式

AI 在实际请求 SiYuan API 时，建议遵循以下约定：

• Method: POST
• Header:
  • Content-Type: application/json
  • Authorization: Token <token>
• Body: JSON
• 返回结果需校验：
  • HTTP 状态码成功
  • 响应 JSON 可解析
  • code === 0

如果接口失败：

• 不要把“接口失败”误报成“路径不存在”
• 不要编造成功结果
• 应直接向用户说明失败原因

---

输出约定

建议 AI 在请求完成后向上层返回统一结果结构：

{
  "ok": true,
  "action": "list_notebooks",
  "summary": "已获取 3 个笔记本",
  "text": "1. 工作 (notebook-id) [open]",
  "data": {},
  "warnings": [],
  "meta": {}
}

建议规则：

• ok: true 时优先返回 summary 和关键结果
• warnings 非空时要一并提示用户
• ok: false 时直接说明失败原因
• 仅在用户明确需要时再展开完整 data

---

支持的 action

notebook

• list_notebooks
• create_notebook
• remove_notebook
• rename_notebook
• open_notebook
• close_notebook
• get_notebook_conf

doc / filetree

• create_doc_with_md
• rename_doc
• remove_doc
• move_docs
• get_doc_path
• get_doc_tree
• check_path_exists

export

• export_md_content

block

• insert_block
• prepend_block
• append_block
• update_block
• delete_block
• move_block
• get_block_kramdown
• get_child_blocks

attr

• set_block_attrs
• get_block_attrs

query

• sql_query
• fulltext_search

system / notification

• get_version
• push_msg

---

风险边界

以下 action 默认视为有副作用：

• create_notebook
• remove_notebook
• rename_notebook
• open_notebook
• close_notebook
• create_doc_with_md
• rename_doc
• remove_doc
• move_docs
• insert_block
• prepend_block
• append_block
• update_block
• delete_block
• move_block
• set_block_attrs
• push_msg

执行这些 action 前，AI 应满足：

• 用户意图明确
• 关键参数齐全
• 已获得明确确认
• 最终结构化参数里显式带上 params.confirmed=true

sql_query 额外规则

• 默认只接受明确授权的 SQL
• 若 SQL 涉及 insert/update/delete/replace/alter/drop/create/truncate 等写操作，必须先确认
• 只有在用户已明确授权时，才可同时加入 params.allowWrite=true 与 params.confirmed=true
• 缺少任一字段都应拒绝执行写 SQL
• 不要把自然语言自动扩写成有副作用 SQL

---

action 与 SiYuan API 映射

直接映射

下表区分两层语义：

• action params：AI 内部统一协议使用的字段
• HTTP body：真正发送给 SiYuan HTTP API 的 JSON 字段