SiYuan 技能

本技能用于调用本地运行的 SiYuan HTTP API，支持笔记本、文档、块、资源、SQL 查询等常见操作。
它只描述调用规范和示例，不包含可执行安装脚本或第三方依赖。

安全范围

• - 仅调用本地 SiYuan 端点（127.0.0.1、localhost 或用户提供的本地 URL）。
• 不向第三方互联网端点发送请求。
• 切勿在日志中硬编码或打印 SIYUANAPITOKEN。
• 本技能对您的 SiYuan 笔记具有读写权限。仅在受信任的本地环境中使用。

配置

配置可通过 shell 中的环境变量提供，例如：

bash
export SIYUANAPITOKEN=yourtokenhere
export SIYUANAPIURL=http://127.0.0.1:6806

• - SIYUANAPITOKEN（必需）：来自 SiYuan 设置 > 关于。
• SIYUANAPIURL（可选）：默认为 http://127.0.0.1:6806。

典型用例

• - 创建、重命名和删除笔记本
• 从 Markdown 创建文档
• 插入、追加、更新、移动和删除块
• 上传资源
• 通过 SQL 查询笔记
• 将文档导出为 Markdown
• 通过 SiYuan 文件 API 读写工作区文件

API 参考

• - references/api-zh.md（中文）
• references/api.md（英文）

常见示例

列出笔记本

javascript const SIYUANAPITOKEN = process.env.SIYUANAPITOKEN; const SIYUANAPIURL = process.env.SIYUANAPIURL || http://127.0.0.1:6806;

fetch(${SIYUANAPIURL}/api/notebook/lsNotebooks, {
method: POST,
headers: {
Authorization: token + SIYUANAPITOKEN,
Content-Type: application/json
},
body: JSON.stringify({})
})

使用 Markdown 创建文档

javascript const SIYUANAPITOKEN = process.env.SIYUANAPITOKEN; const SIYUANAPIURL = process.env.SIYUANAPIURL || http://127.0.0.1:6806;

fetch(${SIYUANAPIURL}/api/filetree/createDocWithMd, {
method: POST,
headers: {
Authorization: token + SIYUANAPITOKEN,
Content-Type: application/json
},
body: JSON.stringify({
notebook: 笔记本ID,
path: /文档路径,
markdown: # 文档标题\n\n正文内容...
})
})

追加块

javascript const SIYUANAPITOKEN = process.env.SIYUANAPITOKEN; const SIYUANAPIURL = process.env.SIYUANAPIURL || http://127.0.0.1:6806;

fetch(${SIYUANAPIURL}/api/block/appendBlock, {
method: POST,
headers: {
Authorization: token + SIYUANAPITOKEN,
Content-Type: application/json
},
body: JSON.stringify({
parentID: 父块ID,
dataType: markdown,
data: 追加的内容
})
})

SQL 查询

javascript const SIYUANAPITOKEN = process.env.SIYUANAPITOKEN; const SIYUANAPIURL = process.env.SIYUANAPIURL || http://127.0.0.1:6806;

fetch(${SIYUANAPIURL}/api/query/sql, {
method: POST,
headers: {
Authorization: token + SIYUANAPITOKEN,
Content-Type: application/json
},
body: JSON.stringify({
stmt: SELECT id, content FROM blocks WHERE content LIKE %关键词% LIMIT 10
})
})

注意事项

• - 在同一路径上重复调用 createDocWithMd 不会覆盖已有文档。
• 自定义块属性必须以 custom- 为前缀。
• 所有端点使用 POST 方法，返回 { code, msg, data } 格式。
• 请求头格式为 Authorization: token （token 为小写）。