SiYuan API

核心用法

SiYuan API Skill 是面向思源笔记（SiYuan）用户的本地接口集成方案，通过 HTTP 端点实现笔记库的全生命周期管理。该技能采用环境变量配置模式，仅需 SIYUAN_API_TOKEN 即可建立安全连接，支持笔记本创建重命名、Markdown 文档生成、块级内容操作、资源上传及 SQL 语义检索等核心功能。

显著优点

1. 本地化架构：严格限定 127.0.0.1/localhost 访问，杜绝外泄风险
2. 无依赖设计：纯 HTTP 调用规范，无需安装额外运行时或第三方库
3. 细粒度操作：支持块级增删改查，配合 SQL 查询可实现精准内容检索
4. 双向兼容：同时提供中英文 API 文档，覆盖思源笔记完整接口能力

潜在局限

• 环境绑定强：必须保持思源笔记桌面端运行，无法离线操作
• 重复创建不覆盖：同名文档创建不会自动覆盖，需手动处理冲突
• Token 管理负担：用户需自行从「设置 > 关于」获取并配置 API Token
• 无可视化界面：纯代码调用，对非技术用户存在学习门槛

适合人群

• 思源笔记重度用户，需要自动化笔记工作流
• 开发者/技术写作者，希望将笔记系统接入个人知识管理体系
• 需要批量处理文档、执行复杂查询的数据整理场景

常规风险

• Token 泄露风险：虽限定本地访问，但 .env 文件仍需妥善保管
• 误操作覆盖：写权限包含删除操作，测试时建议先用沙盒笔记本
• 版本兼容性：需关注思源笔记升级后的 API 变更

核心用法

SiYuan API Skill 是一款专为思源笔记（SiYuan Note）设计的本地 API 集成工具。用户只需配置环境变量 SIYUAN_API_TOKEN 和 SIYUAN_API_URL，即可通过 HTTP 请求与本地运行的思源笔记服务进行交互。该技能提供了完整的 API 调用规范和 JavaScript 代码示例，涵盖笔记本管理（创建、重命名、删除）、文档操作（Markdown 创建、导出）、块级编辑（插入、追加、更新、移动、删除）、资源上传以及基于 SQL 的高级查询等核心功能。

显著优点

安全性极高：该技能来自知名开源项目 SiYuan Note 官方维护，采用纯文档设计，无可执行脚本、无第三方依赖、无外部网络请求，仅访问本地 127.0.0.1:6806 端点。代码示例严格遵循安全最佳实践，使用环境变量获取 API Token，避免敏感信息硬编码。

功能覆盖全面：支持思源笔记的完整数据操作能力，从宏观的笔记本管理到微观的块级编辑，再到强大的 SQL 检索，满足从简单记录到复杂知识管理的多样化需求。

使用零门槛：无需安装额外依赖，直接引用示例代码即可调用。清晰的文档结构和双语 API 参考降低了学习和集成成本。

潜在缺点与局限性

本地运行依赖：必须先在本地启动思源笔记服务才能使用，无法直接操作云端数据或远程服务器上的思源实例。

无实时同步机制：该技能仅为 API 调用文档，不包含自动同步、冲突解决等高级功能，复杂场景需用户自行开发逻辑。

SQL 查询门槛：虽然 SQL 检索功能强大，但需要用户熟悉思源底层数据表结构，对非技术用户有一定学习曲线。

适合的目标群体

该技能主要面向：使用思源笔记作为主力知识管理工具的技术用户；需要自动化处理笔记数据、构建个人工作流的效率爱好者；开发思源插件或集成方案的开发者；以及希望将 AI 能力与本地笔记系统结合的研究人员和知识工作者。

使用风险

Token 管理风险：API Token 具有完整读写权限，需妥善保管环境变量文件，避免泄露导致笔记数据被篡改。

操作不可逆性：部分 API（如删除块）执行后无法撤销，建议在大规模操作前备份数据。

版本兼容性：随着思源笔记迭代，API 可能存在变更，建议关注官方更新并及时调整调用代码。

本地服务稳定性：依赖本地思源服务的正常运行，服务未启动或端口冲突会导致 API 调用失败。