Chuyển tới nội dung chính

{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

Siyuan

API SiYuan Note để tìm kiếm, đọc, tạo và quản lý các khối cũng như tài liệu trong cơ sở kiến thức tự lưu trữ thông qua tính năng cuộn tròn.

Siêu dữ liệu kỹ năng​

NguồnTùy chọn — cài đặt với
`Hermes skills install official/productivity/siyuan
`
Đường dẫn

optional-skills/productivity/siyuan ` | | Phiên bản |

1.0.0 ` | | Tác giả | FEUAZUR | | Giấy phép | MIT | | Nền tảng | Linux, macOS, Windows | | Thẻ |

SiYuan

, `Notes

, `Knowledge Base

, `PKM

, API | | Kỹ năng liên quan | XPROTECTX28XPROTECTX, XPROTECTX29XPROTECTX |

Tham khảo: đầy đủ SKILL.md​

thông tin

Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

API ghi chú SiYuan

Sử dụng API hạt nhân SiYuan thông qua tính năng cuộn tròn để tìm kiếm, đọc, tạo, cập nhật và xóa các khối cũng như tài liệu trong cơ sở kiến thức tự lưu trữ. Không cần thêm công cụ nào -- chỉ cần cuộn tròn và mã thông báo API.

Điều kiện tiên quyết​

  1. Cài đặt và chạy SiYuan (máy tính để bàn hoặc Docker)
  2. Nhận mã thông báo API của bạn: Cài đặt > Giới thiệu > Mã thông báo API
  3. Lưu trữ trong

~/.Hermes/.env

:

` SIYUAN_TOKEN=your_token_here SIYUAN_URL=http://127.0.0.1:6806

` mặc định là 
`http://127.0.0.1:6806
` nếu không được đặt.

## API cơ bản

Tất cả lệnh gọi API SiYuan đều **POST với nội dung JSON**. Mọi yêu cầu đều tuân theo mẫu này:

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

`
``Phản hồi là JSON với cấu trúc này:

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

`

`code: 0
` có nghĩa là thành công. Bất kỳ giá trị nào khác đều là lỗi -- hãy kiểm tra 
`msg
` để biết chi tiết.

**Định dạng ID:** ID SiYuan trông giống 
`20210808180117-6v0mkxr
` (dấu thời gian 14 chữ số + 7 ký tự chữ và số).

## Tham khảo nhanh

| Hoạt động | Điểm cuối |
|----------||----------|
| Tìm kiếm toàn văn |

/API/search/fullTextSearchBlock
` |
| Truy vấn SQL |

/API/query/sql
` |
| Khối đọc |

/API/block/getBlockKramdown
` |
| Đọc trẻ em |

/API/block/getChildBlocks
` |
| Nhận đường dẫn |

/API/filetree/getHPathByID
` |
| Nhận thuộc tính |

/API/attr/getBlockAttrs
` |
| Liệt kê sổ ghi chép |

/API/notebook/lsNotebooks
` |
| Liệt kê tài liệu |

/API/filetree/listDocsByPath
` |
| Tạo sổ ghi chép |

/API/notebook/createNotebook
` |
| Tạo tài liệu |

/API/filetree/createDocWithMd
` |
| Nối khối |

/API/block/appendBlock
` |
| Khối cập nhật |

/API/block/updateBlock
` |
| Đổi tên tài liệu |

/API/filetree/renameDocByID
` |
| Đặt thuộc tính |

/API/attr/setBlockAttrs
` |
| Xóa khối |

/API/block/deleteBlock
` |
| Xóa tài liệu |

/API/filetree/removeDocByID
` |
| Xuất dưới dạng Markdown |

/API/export/exportMdContent
` |

## Hoạt động chung

### Tìm kiếm (Toàn văn)

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

`

### Tìm kiếm (SQL)

Truy vấn cơ sở dữ liệu khối trực tiếp. Chỉ có câu lệnh SELECT là an toàn.

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

`
``Các cột hữu ích: 
`id

, 
`parent_id

, 
`root_id

, 
`box
` (ID sổ tay), 
`path

, 
`content

, 
`type

, 
`subtype

, 
`created

, 
`updated

.

### Đọc nội dung chặn

Trả về nội dung khối ở định dạng Kramdown (giống Markdown).

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

`

### Đọc khối con

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

`

### Nhận đường dẫn mà con người có thể đọc được

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

`

### Nhận thuộc tính khối

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

`

### Liệt kê sổ tay

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

`

### Liệt kê tài liệu vào sổ tay

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

`

### Tạo tài liệu

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

`

### Tạo sổ tay

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

`

### Nối khối vào tài liệu

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

`
``Cũng có sẵn: 

/API/block/prependBlock
` (cùng thông số, chèn ở đầu) và 

/API/block/insertBlock
` (sử dụng 
`previousID
` thay vì 
`parentID
` để chèn sau một khối cụ thể).

### Cập nhật nội dung chặn

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

`

### Đổi tên tài liệu

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

`

### Đặt thuộc tính khối

Các thuộc tính tùy chỉnh phải có tiền tố 
`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"
    }
  }'

`

### Xóa một khối

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

`
``Để xóa toàn bộ tài liệu: sử dụng 

/API/filetree/removeDocByID
` với 

\{"id": "DOC_ID"}

.
Để xóa sổ ghi chép: sử dụng 

/API/notebook/removeNotebook
` với 

\{"notebook": "NOTEBOOK_ID"}

.

### Xuất tài liệu dưới dạng 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'

`

## Các loại khối

Các giá trị 
`type
` phổ biến trong truy vấn SQL:| Loại | Mô tả |
|------|-------------|
| 
`d
` | Tài liệu (khối gốc) |
| 
`p
` | Đoạn |
| 
`h
` | Tiêu đề |
| 
`l
` | Danh sách |
| 
`i
` | Mục danh sách |
| 
`c
` | Khối mã |
| 
`m
` | Khối toán |
| 
`t
` | Bảng |
| 
`b
` | Trích dẫn |
| 
`s
` | Siêu khối |
| 
``` html
` | Khối HTML |

## cạm bẫy
- **Tất cả các điểm cuối đều là POST** -- thậm chí cả các hoạt động chỉ đọc. Không sử dụng NHẬN.

- **An toàn SQL**: chỉ sử dụng truy vấn SELECT. CHÈN/CẬP NHẬT/XÓA/DROP rất nguy hiểm và không bao giờ được gửi.
- **Xác thực ID**: ID khớp với mẫu 
`YYYYMMDDHHmmss-xxxxxxx

. Từ chối bất cứ điều gì khác.
- **Phản hồi lỗi**: luôn kiểm tra 
`code != 0
` trong các phản hồi trước khi xử lý 
`data

.
- **Tài liệu lớn**: nội dung khối và kết quả xuất có thể rất lớn. Sử dụng 
`LIMIT
` trong SQL và chuyển qua 
`jq
` để chỉ trích xuất những gì bạn cần.
- **ID sổ tay**: khi làm việc với một sổ tay cụ thể, trước tiên hãy lấy ID của sổ tay đó thông qua 
`lsNotebooks

.

## Thay thế: Máy chủ MCP

Nếu bạn thích tích hợp gốc thay vì cuộn tròn, hãy cài đặt máy chủ SiYuan MCP:

``` 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"

`
`