AI TOOLS RADAR
Tous les Skills / NOUSRESEARCH
nousresearch/hermes-agent

siyuan

Query and edit a SiYuan knowledge base via its API.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/nousresearch/hermes-agent --skill siyuan

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

SiYuan Note API

Use the SiYuan kernel API via curl to search, read, create, update, and delete blocks and documents in a self-hosted knowledge base. No extra tools needed -- just curl and an API token.

Prerequisites

  1. Install and run SiYuan (desktop or Docker)
  2. Get your API token: Settings > About > API token
  3. Store it in ${HERMES_HOME:-~/.hermes}/.env:
   SIYUAN_TOKEN=your_token_here
   SIYUAN_URL=http://127.0.0.1:6806

SIYUAN_URL defaults to http://127.0.0.1:6806 if not set.

API Basics

All SiYuan API calls are POST with JSON body. Every request follows this pattern:

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/..." \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"param": "value"}'

Responses are JSON with this structure:

json
{"code": 0, "msg": "", "data": { ... }}

code: 0 means success. Any other value is an error -- check msg for details.

ID format: SiYuan IDs look like 20210808180117-6v0mkxr (14-digit timestamp + 7 alphanumeric chars).

Quick Reference

OperationEndpoint
Full-text search/api/search/fullTextSearchBlock
SQL query/api/query/sql
Read block/api/block/getBlockKramdown
Read children/api/block/getChildBlocks
Get path/api/filetree/getHPathByID
Get attributes/api/attr/getBlockAttrs
List notebooks/api/notebook/lsNotebooks
List documents/api/filetree/listDocsByPath
Create notebook/api/notebook/createNotebook
Create document/api/filetree/createDocWithMd
Append block/api/block/appendBlock
Update block/api/block/updateBlock
Rename document/api/filetree/renameDocByID
Set attributes/api/attr/setBlockAttrs
Delete block/api/block/deleteBlock
Delete document/api/filetree/removeDocByID
Export as Markdown/api/export/exportMdContent

Common Operations

Search (Full-Text)

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/search/fullTextSearchBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "meeting notes", "page": 0}' | jq '.data.blocks[:5]'

Search (SQL)

Query the blocks database directly. Only SELECT statements are safe.

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/query/sql" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stmt": "SELECT id, content, type, box FROM blocks WHERE content LIKE '\''%keyword%'\'' AND type='\''p'\'' LIMIT 20"}' | jq '.data'

Useful columns: id, parent_id, root_id, box (notebook ID), path, content, type, subtype, created, updated.

Read Block Content

Returns block content in Kramdown (Markdown-like) format.

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getBlockKramdown" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data.kramdown'

Read Child Blocks

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getChildBlocks" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'

Get Human-Readable Path

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/getHPathByID" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'

Get Block Attributes

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/getBlockAttrs" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'

List Notebooks

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/lsNotebooks" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.data.notebooks[] | {id, name, closed}'

List Documents in a Notebook

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/listDocsByPath" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notebook": "NOTEBOOK_ID", "path": "/"}' | jq '.data.files[] | {id, name}'

Create a Document

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/createDocWithMd" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notebook": "NOTEBOOK_ID",
    "path": "/Meeting Notes/2026-03-22",
    "markdown": "# Meeting Notes\n\n- Discussed project timeline\n- Assigned tasks"
  }' | jq '.data'

Create a Notebook

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/createNotebook" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Notebook"}' | jq '.data.notebook.id'

Append Block to Document

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/appendBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parentID": "DOCUMENT_OR_BLOCK_ID",
    "data": "New paragraph added at the end.",
    "dataType": "markdown"
  }' | jq '.data'

Also available: /api/block/prependBlock (same params, inserts at the beginning) and /api/block/insertBlock (uses previousID instead of parentID to insert after a specific block).

Update Block Content

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/updateBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "BLOCK_ID",
    "data": "Updated content here.",
    "dataType": "markdown"
  }' | jq '.data'

Rename a Document

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/renameDocByID" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "DOCUMENT_ID", "title": "New Title"}'

Set Block Attributes

Custom attributes must be prefixed with custom-:

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/setBlockAttrs" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "BLOCK_ID",
    "attrs": {
      "custom-status": "reviewed",
      "custom-priority": "high"
    }
  }'

Delete a Block

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/deleteBlock" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "BLOCK_ID"}'

To delete a whole document: use /api/filetree/removeDocByID with {"id": "DOC_ID"}. To delete a notebook: use /api/notebook/removeNotebook with {"notebook": "NOTEBOOK_ID"}.

Export Document as Markdown

bash
curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/export/exportMdContent" \
  -H "Authorization: Token $SIYUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "DOCUMENT_ID"}' | jq -r '.data.content'

Block Types

Common type values in SQL queries:

TypeDescription
dDocument (root block)
pParagraph
hHeading
lList
iList item
cCode block
mMath block
tTable
bBlockquote
sSuper block
htmlHTML block

Pitfalls

  • All endpoints are POST -- even read-only operations. Do not use GET.
  • SQL safety: only use SELECT queries. INSERT/UPDATE/DELETE/DROP are dangerous and should never be sent.
  • ID validation: IDs match the pattern YYYYMMDDHHmmss-xxxxxxx. Reject anything else.
  • Error responses: always check code != 0 in responses before processing data.
  • Large documents: block content and export results can be very large. Use LIMIT in SQL and pipe through jq to extract only what you need.
  • Notebook IDs: when working with a specific notebook, get its ID first via lsNotebooks.

Alternative: MCP Server

If you prefer a native integration instead of curl, install the SiYuan MCP server:

yaml
# In ~/.hermes/config.yaml under mcp_servers:
mcp_servers:
  siyuan:
    command: npx
    args: ["-y", "@porkll/siyuan-mcp"]
    env:
      SIYUAN_TOKEN: "your_token"
      SIYUAN_URL: "http://127.0.0.1:6806"

Tâches connexes

affaan-m
Communauté

knowledge-ops

Knowledge base management, ingestion, sync, and retrieval across multiple storage layers (local files, MCP memory, vector stores, Git repos). Use when the user wants to save, organize, sync, deduplicate, or search across their knowledge systems.

installations
3
GitHub Stars
286,1 k
Mis à jour
20 oct.
MIT1 Fichiers
Voir les détails →

Raison de la sélection: Documents

affaan-m
Communauté

docs-governance

Route broad documentation-governance requests to existing ECC skills and run an opt-in, read-only audit of mapped documentation roles, links, ADR indexes, and evidence references. Use when a user asks for documentation governance, project-knowledge organization, documentation integrity, or a deterministic docs audit without naming a narrower skill.

installations
3
GitHub Stars
286,1 k
Mis à jour
20 oct.
MIT4 Fichiers
Voir les détails →

Raison de la sélection: Documents

affaan-m
Communauté

google-workspace-ops

Operate across Google Drive, Docs, Sheets, and Slides as one workflow surface for plans, trackers, decks, and shared documents. Use when the user needs to find, summarize, edit, migrate, or clean up Google Workspace assets without dropping to raw tool calls.

installations
3
GitHub Stars
286,1 k
Mis à jour
20 oct.
MIT1 Fichiers
Voir les détails →

Raison de la sélection: Documents

du même dépôt

Autres Skills

Tous les Skills
nousresearch
Communauté

pixel-art

Pixel art w/ era palettes (NES, Game Boy, PICO-8).

installations
1
GitHub Stars
257,1 k
Mis à jour
26 oct.
MIT7 Fichiers
Voir les détails →
nousresearch
Communauté

inspecting-hermes-desktop-dom

Read the live Hermes desktop DOM/CSS over CDP.

installations
3
GitHub Stars
255,9 k
Mis à jour
22 oct.
MIT1 Fichiers
Voir les détails →
nousresearch
Communauté

github

GitHub via gh CLI: PRs, issues, reviews, repos, auth.

installations
2
GitHub Stars
255,9 k
Mis à jour
22 oct.
MIT17 Fichiers
Voir les détails →
nousresearch
Communauté

hermes-agent

Use, configure, theme, extend, and orchestrate Hermes Agent.

installations
2
GitHub Stars
255,9 k
Mis à jour
22 oct.
MIT22 Fichiers
Voir les détails →