Siyuan Agent

Interact with SiYuan notes via direct HTTP API. Use when reading, writing, searching, or managing SiYuan blocks, documents, notebooks, attributes, assets, or...

Security Scan

The skill's behavior matches its stated SiYuan purpose, but registry metadata omits the required SIYUAN_TOKEN and there is a configurable network endpoint (SIYUAN_BASE) that could be pointed off-host — these mismatches warrant caution before installing.

Purpose & Capability

Name/description (SiYuan HTTP API client) matches the code and SKILL.md: the tool needs a SiYuan API token and optionally a base URL. However the registry metadata lists no required env vars while SKILL.md and lib/api.js require SIYUAN_TOKEN (primaryCredential). This metadata omission is an incoherence that could mislead users about credential requirements.

Instruction Scope

SKILL.md instructions are specific and align with the implemented commands. The skill enforces SELECT-only for sql, requires write=true for write operations, and hard-blocks certain notebook-management paths. The runtime instructions do not request unrelated files or credentials.

Install Mechanism

No install spec (instruction-only plus small JS files included). There are no external downloads or package installs — low install risk.

Credentials

The only credential used is SIYUAN_TOKEN (appropriate for a SiYuan API client). But the registry metadata failing to declare this required env var is a red flag. Additionally SIYUAN_BASE (default localhost) is user-configurable; if set to a remote host it would cause the skill to send the token and data to that host, enabling token exfiltration if misconfigured or maliciously set.

Persistence & Privilege

Skill does not request always:true and does not modify other skills or system configs. Autonomous invocation is allowed (platform default) but not combined with elevated privileges in this package.

What to consider before installing

This skill appears to implement exactly what it claims (a SiYuan HTTP API CLI) and enforces reasonable write and SQL restrictions, but the package metadata omitted the required SIYUAN_TOKEN. Before installing: (1) Confirm you set SIYUAN_TOKEN — the tool will exit without it; (2) Keep SIYUAN_BASE at the default localhost unless you intentionally want to point it elsewhere (setting it to a remote URL will send your token and data to that host); (3) Inspect the small JS files (they're included and readable) to verify no unexpected network targets; (4) Prefer minimizing agent autonomy or restricting the skill's use until you trust the publisher; and (5) Verify the publisher/slug/source — the registry metadata inconsistency could be a packaging error, but treat it as a warning.

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
2. Set the token:

export SIYUAN_TOKEN=your_token_here
export SIYUAN_BASE=http://127.0.0.1:6806   # optional, default shown

(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
search query=<kw>	Full-text search
searchByNotebook query=<kw> notebook=<id>	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
insertBlock parentID=<id> data="<content>" write=true	Insert block
updateBlock id=<id> data="<content>" write=true	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:

• /api/notebook/createNotebook
• /api/notebook/removeNotebook
• /api/notebook/renameNotebook
• /api/notebook/closeNotebook
• /api/notebook/saveNotebookConf

Usage Examples

# Search
node siyuan.js search query=keyword

# Read a block
node siyuan.js getBlock id=20260321111240-o5xe15o

# Get document
node siyuan.js getDoc id=20260321111240-o5xe15o

# Get child blocks
node siyuan.js getChildren id=20260321111240-o5xe15o

# SQL query
node siyuan.js sql "SELECT id, type, content FROM blocks WHERE content LIKE '%keyword%' LIMIT 5"

# Write operation
node siyuan.js updateBlock id=20260321111240-o5xe15o data="New content" write=true

# Direct API call
node siyuan.js call path=/api/notebook/lsNotebooks '{}'

Files

siyuan.js   — CLI entry point (native fetch, no deps)
lib/api.js  — HTTP API caller