siyuan-export

思源笔记文档导出工具。将思源笔记文档导出为 Word(docx) 格式，支持按文档 ID/路径/名称搜索导出，图片自动打包进文档。支持单个文档导出和批量导出子文档。触发词：导出文档、导出 Word、siyuan export、思源导出、批量导出、导出子文档

Security Scan

The skill appears to implement the advertised SiYuan-to‑Word export functionality, but there are inconsistencies and small risks you should understand before installing (missing declared credentials in registry, raw SQL construction, and reliance on a user-provided API token and base URL).

Purpose & Capability

Name/description match the code and instructions: the script calls SiYuan export and query APIs and writes .docx output. However the registry metadata claims 'required env vars: none' and 'primary credential: none' while both the SKILL.md and the script require an API token (SIYUAN_TOKEN) and may read SIYUAN_BASE_URL / SIYUAN_TIMEOUT. This metadata omission is an inconsistency.

Instruction Scope

SKILL.md stays within the stated purpose (configure token/base URL, call local SiYuan APIs, write docx). The script only reads config.json in the skill directory and environment variables, queries the SiYuan API, and writes export files. A noteworthy point: SQL statements are built by string interpolation with user-supplied values (search keywords, doc IDs), which can allow unexpected/malicious queries against the SiYuan API if untrusted input is provided.

Install Mechanism

No install spec — instruction-only with a Python script relying only on the standard library. Nothing is downloaded or extracted at install time, which lowers installation risk.

Credentials

The skill requires a SiYuan API token and optionally a base URL and timeout (SIYUAN_TOKEN, SIYUAN_BASE_URL, SIYUAN_TIMEOUT), but the registry metadata does not declare these. Requesting an API token is expected for this functionality, but the missing declaration is a transparency issue. Also be aware that if you set SIYUAN_BASE_URL to a remote host (instead of the default localhost), the script will talk to that host using your token — so never point it to an untrusted remote server.

Persistence & Privilege

always:false and the skill does not request persistent platform-level privileges. It does not modify other skills' configuration or system-wide settings.

What to consider before installing

This skill largely does what it promises (export SiYuan notes to .docx) and uses only Python stdlib, but take these precautions before using it: 1) The skill needs your SiYuan API token (SIYUAN_TOKEN) even though the registry metadata doesn't list it — treat that as required and keep the token secret. 2) Prefer keeping SIYUAN_BASE_URL as the default localhost (http://127.0.0.1:6806); do not point it to an unknown remote server (that would let that remote host receive requests authenticated with your token). 3) Review the script yourself or run it in a controlled environment — the script builds SQL queries via string interpolation from user input (search keywords, IDs), which can cause unexpected queries; avoid running it with untrusted or automated inputs unless you sanitize them. 4) Store token via environment variables rather than a plaintext config.json in shared locations. 5) If you need higher assurance, request that the publisher correct the registry metadata to declare required env vars and provide a verified homepage/source, or run the script locally after manual code review.

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

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

核心特性

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

前置条件

1. 思源笔记正在运行

2. 配置 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