核心用法
SiYuan API 技能通过本地 HTTP 端点与思源笔记进行交互，提供完整的笔记管理能力。用户需配置 SIYUAN_API_TOKEN（从思源设置中获取）和可选的 SIYUAN_API_URL（默认 http://127.0.0.1:6806）。
主要功能模块：
- 笔记本管理：创建、重命名、删除笔记本
- 文档操作：基于 Markdown 创建文档、导出为 Markdown
- 块级编辑：插入、追加、更新、移动、删除内容块
- 资源管理：上传图片等附件资源
- 高级查询：通过 SQL 直接检索笔记内容（支持
blocks表查询） - 文件操作：读写工作区文件
调用规范：所有端点使用 POST 方法，返回统一格式 { code, msg, data }，认证头为 Authorization: token <token>（注意小写 token）。
显著优点
1. 本地优先设计：仅限 127.0.0.1、localhost 或用户指定的本地 URL，杜绝外泄风险
2. 细粒度控制：支持块级操作，可实现精准的内容插入与修改
3. SQL 查询能力：直接访问底层数据库，灵活检索复杂条件的内容
4. Markdown 原生支持：文档创建与导出均以 Markdown 为媒介，便于与其他工具协作
5. 无第三方依赖：纯 HTTP API 调用，不引入额外软件包
潜在缺点与局限性
- 需手动配置令牌：用户必须主动从思源界面复制 API Token，入门有门槛
- 无覆盖保护：重复
createDocWithMd不会覆盖现有文档，可能导致预期外的行为 - 属性前缀限制：自定义块属性必须加
custom-前缀，增加记忆成本 - 仅支持本地实例：无法连接远程思源服务或云同步版本
- SQL 查询无抽象层：需用户自行编写 SQL，对非技术用户不够友好
适合人群
- 需要将思源笔记与其他本地工具链集成的开发者
- 习惯 Markdown 工作流、追求自动化笔记管理的效率用户
- 希望通过脚本批量处理笔记内容的高级用户
- 注重数据隐私、偏好本地优先方案的隐私敏感型用户
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 令牌泄露 | Token 具有读写权限，泄露可导致笔记被篡改 | 不硬编码、不打印日志、仅环境变量注入 |
| 误操作覆盖 | 块级删除/更新不可逆 | 操作前备份、先用只读查询验证 |
| SQL 注入 | 自定义 SQL 查询可能语法错误 | 参数化输入、限制查询范围 |
| 服务未启动 | 思源未运行时 API 调用失败 | 调用前检查端口可用性 |
来源评估
该技能描述的是思源笔记官方公开的本地 API 规范，源码仓库为官方 GitHub 组织，API 文档与软件版本同步维护，属于可信的第一方集成方案。