思源笔记文档导出 (siyuan-export)

通过思源笔记原生 API 将文档导出为 Word(.docx)，返回结构化 JSON 结果。支持单文档和批量子文档导出。

核心特性

| 特性 | 说明 | |------|------| | 双定位 | 支持文档 ID 或人类可读路径 | | 批量导出 | --children 一键导出文档下所有子文档（含嵌套） | | 单文件输出 | 图片资源自动内嵌（removeAssets=true），不产生外挂目录 | | JSON 输出 | 结构化结果，方便大模型解析 | | 零依赖 | 仅使用 Python 标准库 |

前置条件

思源笔记正在运行

配置 Token

方式 A：环境变量（推荐）

# Windows PowerShell
$env:SIYUAN_TOKEN = "你的token"
$env:SIYUAN_BASE_URL = "http://127.0.0.1:6806"
$env:SIYUAN_TIMEOUT = "10000"  # 可选，超时 ms

方式 B：config.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