思源笔记文档导出 (siyuan-export)
通过思源笔记原生 API 将文档导出为 Word(.docx)，返回结构化 JSON 结果。支持单文档和批量子文档导出。
核心特性
| 特性 | 说明 |
|---|---|
| 双定位 | 支持文档 ID 或人类可读路径 |
| 批量导出 | --children 一键导出文档下所有子文档（含嵌套） |
| 单文件输出 | 图片资源自动内嵌（removeAssets=true），不产生外挂目录 |
| JSON 输出 | 结构化结果，方便大模型解析 |
| 零依赖 | 仅使用 Python 标准库 |
前置条件
- 思源笔记正在运行
- 配置 Token
方式 A：环境变量（推荐）
bash
# Windows PowerShell
$env:SIYUAN_TOKEN = "你的token"
$env:SIYUAN_BASE_URL = "http://127.0.0.1:6806"
$env:SIYUAN_TIMEOUT = "10000" # 可选，超时 ms
方式 B：config.json（在技能目录下创建）
json
{
"baseURL": "http://127.0.0.1:6806",
"token": "你的token",
"timeout": 10000
}
方式 C：复制 config.example.json 重命名为 config.json
config.example.json → config.json
然后填入 token
Token 获取：思源笔记 → 设置 → 关于 → 复制 Token
使用方法
# 按文档名搜索导出（推荐）
python scripts/siyuan_export.py -s "关键词" -o C:/Desktop
# 按 ID 导出单个文档
python scripts/siyuan_export.py --doc-id <ID>
# 按路径导出
python scripts/siyuan_export.py --path "/AI/Test" --output C:/output
# 导出所有子文档
python scripts/siyuan_export.py --doc-id <ID> --children --output C:/Desktop/Midjourney
参数说明
| 参数 | 缩写 | 必选 | 说明 |
|---|---|---|---|
--doc-id |
-i |
二选一 | 文档 ID |
--path |
-p |
二选一 | 文档路径 |
--search |
-s |
二选一 | 按文档名搜索 |
--children |
-c |
否 | 批量模式：导出所有子文档 |
--include-self |
否 | 批量模式时同时导出父文档 | |
--output |
-o |
否 | 输出目录（默认：桌面） |
返回值
单文档导出
成功：
{
"success": true,
"data": {
"path": "C:/Users/10941/Desktop/P02：设置解析.docx",
"size_bytes": 3544783,
"size_kb": 3461.7
}
}
批量子文档导出
成功：
{
"success": true,
"data": {
"total": 16,
"success_count": 16,
"fail_count": 0,
"output_dir": "C:/Users/10941/Desktop/Midjourney教程",
"details": [
{"id": "...", "title": "P01：认识界面", "result": {"success": true, "data": {"path": "...", "size_kb": 1234.5}}},
...
]
}
}
失败：
{
"success": false,
"error": "api_error",
"message": "具体错误信息"
}
API 接口
| 本脚本 | 思源 API | 参数 |
|---|---|---|
| 单文档导出 | POST /api/export/exportDocx |
id + savePath（目录）+ removeAssets=true |
| 获取子文档列表 | POST /api/query/sql |
SQL 查询 hpath LIKE 匹配子路径 |
文件结构
siyuan-export/
├── SKILL.md
├── config.example.json # 配置模板（含 timeout 字段）
└── scripts/
└── siyuan_export.py
