核心用法
siyuan-api 技能为思源笔记(SiYuan)提供完整的本地HTTP API集成能力，通过标准REST端点实现笔记数据的程序化操作。用户需配置SIYUAN_API_TOKEN（必填）和可选的SIYUAN_API_URL（默认http://127.0.0.1:6806）即可调用。
主要功能模块：
- 笔记本管理：创建、重命名、删除笔记本，列出所有工作空间
- 文档操作：基于Markdown创建文档、导出为Markdown、管理文档树结构
- 块级编辑：插入、追加、更新、移动、删除内容块，支持自定义属性（需
custom-前缀） - 资源管理：上传图片等资源文件至思源资产库
- SQL查询：直接查询底层SQLite数据库，实现高级内容检索
- 文件系统：通过思源API读写工作区文件
技术规范：
- 所有端点使用
POST方法，返回标准格式{ code, msg, data } - 认证头格式为
Authorization: token <token>（注意小写token） - 同一路径重复调用
createDocWithMd不会覆盖已有文档
显著优点
1. 本地化优先：完全基于本地HTTP服务，无需云服务，数据完全自主可控
2. 功能全面：覆盖思源笔记绝大多数核心功能，从宏观笔记本到微观块操作
3. SQL直连：开放底层数据库查询能力，突破GUI限制实现复杂检索
4. Markdown原生：创建文档直接支持Markdown语法，符合开发者习惯
5. 环境配置灵活：支持shell环境变量或~/.openclaw/.env文件双模式配置
潜在缺点与局限性
1. 网络依赖：必须保持思源笔记本地服务运行（默认6806端口）
2. 无覆盖保护：重复创建文档不会覆盖，需额外逻辑处理更新场景
3. 令牌管理：API token需手动从Settings > About获取，轮换不便
4. 无批量优化：大量操作时需逐条HTTP请求，无原生批量接口
5. 平台绑定：专为思源笔记设计，无法迁移至其他笔记系统
适合人群
- 思源笔记重度用户，希望自动化笔记工作流
- 需要将外部数据（RSS、爬虫、API）自动导入思源的知识管理者
- 习惯Markdown写作、偏好本地化存储的开发者和技术写作者
- 需要自定义查询和数据分析的高级用户
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 令牌泄露 | `SIYUAN_API_TOKEN`若泄露可导致笔记数据被完全读写 | 使用`.env`文件存储，确保`~/.openclaw/`目录权限受限；避免提交至版本控制 |
| 误操作数据丢失 | 删除/更新操作不可逆，脚本bug可能批量破坏笔记 | 操作前备份工作空间；关键操作添加确认逻辑 |
| 本地服务不可用 | 思源未启动或端口冲突导致API调用失败 | 调用前检查服务健康状态；实现重试和降级机制 |
| SQL注入（自查） | 拼接SQL语句时若引入外部输入存在风险 | 严格参数校验；优先使用官方封装接口而非原生SQL |
| 网络暴露风险 | 若错误配置`SIYUAN_API_URL`为公网地址 | 强制校验URL为本地地址（127.0.0.1/localhost）；部署网络隔离 |
该技能已通过明确的本地端点限制和令牌安全规范，将风险控制在可信本地环境范围内。