siyuan-agent (Direct HTTP)
Standalone CLI for SiYuan — direct HTTP API access, no npm dependencies.
Setup
- 1. Enable SiYuan API token: SiYuan → Settings → About → API token
- Set the token:
CODEBLOCK0
(Add these to your ~/.bashrc or ~/.zshrc to persist.)
You don't need to use the CLI yourself. Just tell your agent to read this SKILL.md — it will use this tool automatically.
Commands
Read
| Command | Description |
|---|
| INLINECODE2 | Full-text search |
| INLINECODE3 |
Search in specific notebook |
|
getDoc id=<blockID> | Get document |
|
getBlock id=<blockID> | Get single block |
|
getChildren id=<blockID> | Get child blocks |
|
backlinks id=<blockID> | Find backlinks |
|
outline id=<blockID> | Get document outline |
|
sql "SELECT ..." | Execute SELECT-only SQL |
|
exportMd id=<docID> | Export doc to markdown |
|
call path=/api/... '{}' | Any API endpoint directly |
Write (requires write=true)
| Command | Description |
|---|
| INLINECODE12 | Insert block |
| INLINECODE13 |
Update block |
|
deleteBlock id=<id> write=true | Delete block |
SQL Safety
The sql command only allows SELECT statements. Non-SELECT queries are rejected with an error.
Write Protection
Write operations (insertBlock, updateBlock, deleteBlock) require write=true.
The call command requires write=true for non-read paths (export, asset upload are treated as write paths).
Hard-Blocked Paths
These notebook operations are blocked and cannot be called:
- - INLINECODE22
- INLINECODE23
- INLINECODE24
- INLINECODE25
- INLINECODE26
Usage Examples
CODEBLOCK1
Files
CODEBLOCK2
siyuan-agent（直接HTTP）
思源笔记的独立命令行工具 — 直接HTTP API访问，无npm依赖。
设置
- 1. 启用思源API令牌：思源笔记 → 设置 → 关于 → API令牌
- 设置令牌：
bash
export SIYUAN_TOKEN=你的令牌
export SIYUAN_BASE=http://127.0.0.1:6806 # 可选，默认如上所示
（将这些添加到你的~/.bashrc或~/.zshrc中以持久化。）
你不需要自己使用命令行工具。 只需告诉你的智能体阅读此SKILL.md文件——它将自动使用此工具。
命令
读取
| 命令 | 描述 |
|---|
| search query=<关键词> | 全文搜索 |
| searchByNotebook query=<关键词> notebook=<ID> |
在指定笔记本中搜索 |
| getDoc id=<块ID> | 获取文档 |
| getBlock id=<块ID> | 获取单个块 |
| getChildren id=<块ID> | 获取子块 |
| backlinks id=<块ID> | 查找反向链接 |
| outline id=<块ID> | 获取文档大纲 |
| sql SELECT ... | 执行仅SELECT的SQL语句 |
| exportMd id=<文档ID> | 将文档导出为Markdown |
| call path=/api/... {} | 直接调用任意API端点 |
写入（需要write=true）
| 命令 | 描述 |
|---|
| insertBlock parentID=<ID> data=<内容> write=true | 插入块 |
| updateBlock id=<ID> data=<内容> write=true |
更新块 |
| deleteBlock id=
write=true | 删除块 |
SQL安全
sql命令仅允许SELECT语句。非SELECT查询将被拒绝并返回错误。
写入保护
写入操作（insertBlock、updateBlock、deleteBlock）需要write=true。
call命令对于非读取路径（导出、资源上传被视为写入路径）需要write=true。
硬性阻止的路径
以下笔记本操作被阻止，无法调用：
- - /api/notebook/createNotebook
- /api/notebook/removeNotebook
- /api/notebook/renameNotebook
- /api/notebook/closeNotebook
- /api/notebook/saveNotebookConf
使用示例
bash
搜索
node siyuan.js search query=关键词
读取块
node siyuan.js getBlock id=20260321111240-o5xe15o
获取文档
node siyuan.js getDoc id=20260321111240-o5xe15o
获取子块
node siyuan.js getChildren id=20260321111240-o5xe15o
SQL查询
node siyuan.js sql SELECT id, type, content FROM blocks WHERE content LIKE %关键词% LIMIT 5
写入操作
node siyuan.js updateBlock id=20260321111240-o5xe15o data=新内容 write=true
直接API调用
node siyuan.js call path=/api/notebook/lsNotebooks {}
文件
siyuan.js — 命令行入口点（原生fetch，无依赖）
lib/api.js — HTTP API调用器
