Siyuan

SiYuan Note API для поиска, чтения, создания и управления блоками и документами в самохостируемой базе знаний через curl.

Метаданные навыка


Источник	Опциональный — установите командой `hermes skills install official/productivity/siyuan`
Путь	`optional-skills/productivity/siyuan`
Версия	`1.0.0`
Автор	FEUAZUR
Лицензия	MIT
Платформы	linux, macos, windows
Теги	`SiYuan`, `Notes`, `Knowledge Base`, `PKM`, `API`
Связанные навыки	`obsidian`, `notion`

Справочник: полный SKILL.md

инфо

Ниже приведено полное определение навыка, которое Hermes Agent загружает при его активации. Это инструкции, которые агент получает, когда навык включён.

SiYuan Note API

Работайте с SiYuan через kernel API и curl: ищите, читайте, создавайте, обновляйте и удаляйте блоки и документы в самохостируемой базе знаний. Никаких дополнительных инструментов — только curl и API-токен.

Требования

Установите и запустите SiYuan (десктоп или Docker)
Получите API-токен: Settings > About > API token
Сохраните его в ~/.hermes/.env:
```
SIYUAN_TOKEN=your_token_here
SIYUAN_URL=http://127.0.0.1:6806
```
Если SIYUAN_URL не задан, по умолчанию используется http://127.0.0.1:6806.

Основы API

Все вызовы SiYuan API — это POST с JSON-телом. Каждый запрос строится по одному шаблону:

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"}'

Ответы возвращаются в JSON такой структуры:

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

code: 0 означает успех. Любое другое значение — ошибка; подробности смотрите в msg.

Формат ID: идентификаторы SiYuan выглядят как 20210808180117-6v0mkxr (14-значная метка времени + 7 буквенно-цифровых символов).

Краткий справочник

Операция	Эндпоинт
Полнотекстовый поиск	`/api/search/fullTextSearchBlock`
SQL-запрос	`/api/query/sql`
Чтение блока	`/api/block/getBlockKramdown`
Чтение дочерних блоков	`/api/block/getChildBlocks`
Получить путь	`/api/filetree/getHPathByID`
Получить атрибуты	`/api/attr/getBlockAttrs`
Список ноутбуков	`/api/notebook/lsNotebooks`
Список документов	`/api/filetree/listDocsByPath`
Создать ноутбук	`/api/notebook/createNotebook`
Создать документ	`/api/filetree/createDocWithMd`
Добавить блок	`/api/block/appendBlock`
Обновить блок	`/api/block/updateBlock`
Переименовать документ	`/api/filetree/renameDocByID`
Установить атрибуты	`/api/attr/setBlockAttrs`
Удалить блок	`/api/block/deleteBlock`
Удалить документ	`/api/filetree/removeDocByID`
Экспорт в Markdown	`/api/export/exportMdContent`

Основные операции

Поиск (полнотекстовый)

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]'

Поиск (SQL)

Прямой запрос к базе блоков. Безопасны только SELECT-запросы.

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'

Полезные столбцы: id, parent_id, root_id, box (ID ноутбука), path, content, type, subtype, created, updated.

Чтение содержимого блока

Возвращает содержимое блока в формате Kramdown (разновидность Markdown).

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'

Чтение дочерних блоков

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'

Получить читаемый путь

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'

Получить атрибуты блока

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'

Список ноутбуков

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}'

Список документов в ноутбуке

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}'

Создать документ

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'

Создать ноутбук

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'

Добавить блок в документ

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'

Также доступны: /api/block/prependBlock (те же параметры, вставляет в начало) и /api/block/insertBlock (использует previousID вместо parentID — вставка после конкретного блока).

Обновить содержимое блока

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'

Переименовать документ

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"}'

Установить атрибуты блока

Пользовательские атрибуты должны начинаться с префикса custom-:

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"
    }
  }'

Удалить блок

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"}'

Чтобы удалить весь документ — /api/filetree/removeDocByID с {"id": "DOC_ID"}. Чтобы удалить ноутбук — /api/notebook/removeNotebook с {"notebook": "NOTEBOOK_ID"}.

Экспортировать документ в Markdown

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'

Типы блоков

Распространённые значения type в SQL-запросах:

Тип	Описание
`d`	Документ (корневой блок)
`p`	Абзац
`h`	Заголовок
`l`	Список
`i`	Элемент списка
`c`	Блок кода
`m`	Математический блок
`t`	Таблица
`b`	Цитата
`s`	Суперблок
`html`	HTML-блок

Подводные камни

Все эндпоинты — POST — даже операции только на чтение. GET не использовать.
Безопасность SQL: только SELECT-запросы. INSERT/UPDATE/DELETE/DROP недопустимы.
Проверка ID: ID соответствуют шаблону YYYYMMDDHHmmss-xxxxxxx. Всё остальное следует отклонять.
Ошибки в ответах: всегда проверяйте code != 0 перед обработкой data.
Большие документы: содержимое блоков и результаты экспорта могут быть очень объёмными. Используйте LIMIT в SQL и пропускайте вывод через jq, чтобы извлечь только нужное.
ID ноутбуков: при работе с конкретным ноутбуком сначала получите его ID через lsNotebooks.

Альтернатива: MCP-сервер

Если вы предпочитаете нативную интеграцию вместо curl, установите MCP-сервер SiYuan:

# В ~/.hermes/config.yaml в секции 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"