---
name: siyuan
description: 操作思源笔记（SiYuan Notes），包括搜索、文档 CRUD、SQL 查询等。
metadata: {"echobot":{"emoji":"📒","requires":{"env":["SIYUAN_TOKEN"]}}}
---

# SiYuan Notes Skill

用于在 echobot 中通过 `run_skill_script` 访问思源 API。

## 配置

优先使用环境变量：

```bash
export SIYUAN_HOST="192.168.10.103"   # 默认 localhost
export SIYUAN_PORT="6806"             # 默认 6806
export SIYUAN_TOKEN="your_api_token"  # 必填
```

## 在 echobot 中如何调用

本技能的可执行入口是 `scripts/runner.py`。  
必须通过 `run_skill_script` 调用，不要直接写伪函数调用。

获取笔记本：

```json
{
  "tool": "run_skill_script",
  "arguments": {
    "skill_name": "siyuan",
    "script": "runner.py",
    "args": ["siyuan_get_notebooks"]
  }
}
```

创建文档：

```json
{
  "tool": "run_skill_script",
  "arguments": {
    "skill_name": "siyuan",
    "script": "runner.py",
    "args": [
      "siyuan_create_document",
      "{\"notebook_id\":\"20260210020051-9ybvigj\",\"path\":\"/\",\"title\":\"test\",\"content\":\"hello\"}"
    ]
  }
}
```

## 工具列表

- `siyuan_search`
  - 参数：`query`(必填), `limit`(默认 20), `type`(默认 `blocks`)
- `siyuan_query_blocks`
  - 参数：`hsql`(必填), `limit`(默认 100)
- `siyuan_get_document`
  - 参数：`doc_id`(必填)
- `siyuan_create_document`
  - 参数：`notebook_id`(必填), `path`(必填), `title`(必填), `content`
- `siyuan_update_document`
  - 参数：`doc_id`(必填), `content`(必填)
- `siyuan_get_notebooks`
  - 参数：无
- `siyuan_get_recent_docs`
  - 参数：`limit`(默认 10)
- `siyuan_get_dailies`
  - 参数：`start_date`(YYYY-MM-DD), `end_date`(YYYY-MM-DD)
- `siyuan_query_sql`
  - 参数：`sql`(必填)

## runner.py 用法

```bash
python scripts/runner.py <tool_name> [json_arguments]
```

示例：

```bash
python scripts/runner.py siyuan_get_notebooks
python scripts/runner.py siyuan_search '{"query":"AI","limit":10}'
```

## 常见问题

- `404 page not found`  
  你可能用了错误接口。请使用思源当前接口，例如：
  - `POST /api/notebook/lsNotebooks`
  - `POST /api/filetree/createDocWithMd`
- `SIYUAN_TOKEN is required`  
  未设置 `SIYUAN_TOKEN`。
- `Invalid JSON response ...`  
  通常是地址/端口不对，或请求到了非思源服务。

## 文件结构

```text
siyuan/
├── SKILL.md
└── scripts/
    ├── __init__.py
    ├── client.py
    ├── tools.py
    └── runner.py
```
