Siyuan

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

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


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

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

к сведению

Ниже приведено полное определение навыка, которое VibeOS загружает при его активации. Это те инструкции, которые видит агент, когда навык активен.

API SiYuan Note

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

Предварительные требования

Установите и запустите SiYuan (десктопная версия или Docker)
Получите токен API: Настройки > О программе > Токен API
Сохраните его в ${VIBEOS_HOME:-~/.vibeos}/.env:
```
SIYUAN_TOKEN=ваш_токен_здесь
SIYUAN_URL=http://127.0.0.1:6806
```
Если SIYUAN_URL не задан, по умолчанию используется http://127.0.0.1:6806.

Основы API

Все вызовы API SiYuan выполняются методом 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: 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": "заметки с встречи", "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": "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": "ID_БЛОКНОТА",
    "path": "/Заметки с встреч/2026-03-22",
    "markdown": "# Заметки с встречи\n\n- Обсудили план проекта\n- Назначили задачи"
  }' | 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": "Мой новый блокнот"}' | 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": "ID_ДОКУМЕНТА_ИЛИ_БЛОКА",
    "data": "Новый абзац, добавленный в конец.",
    "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": "ID_БЛОКА",
    "data": "Обновлённое содержимое здесь.",
    "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": "ID_ДОКУМЕНТА", "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": "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": "ID_БЛОКА"}'

Для удаления целого документа: используйте /api/filetree/removeDocByID с {"id": "ID_ДОК"}. Для удаления блокнота: используйте /api/notebook/removeNotebook с {"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": "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:

# В ~/.vibeos/config.yaml в разделе mcp_servers:
mcp_servers:
  siyuan:
    command: npx
    args: ["-y", "@porkll/siyuan-mcp"]
    env:
      SIYUAN_TOKEN: "ваш_токен"
      SIYUAN_URL: "http://127.0.0.1:6806"

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

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

API SiYuan Note

Предварительные требования​

Основы API​

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

Часто используемые операции​

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

Поиск (SQL)​

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

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

Получение человекочитаемого пути​

Получение атрибутов блока​

Список блокнотов​

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

Создание документа​

Создание блокнота​

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

Обновление содержимого блока​

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

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

Удаление блока​

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

Типы блоков​

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

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