核心用法
siyuan-skill 是思源笔记的 API 转 CLI 工具，封装了思源笔记的 RESTful API，提供笔记本管理、文档 CRUD、块级操作、内容搜索等完整功能。通过 node siyuan.js <command> 调用，支持 20+ 子命令，涵盖 create/update/delete/move/rename 等文档操作，block-insert/update/delete/move 等块级操作，以及 search 多模式检索（精确/关键词/语义/混合搜索）。
显著优点
1. 功能完整：覆盖思源笔记 90% 以上的 API 能力，从宏观的笔记本管理到微观的块级编辑均可实现
2. 多模式搜索：支持传统 SQL LIKE、BM25、语义向量及混合搜索，满足从精确匹配到概念检索的多样需求
3. 安全设计：采用配置只读原则，敏感信息仅通过环境变量注入，技能本身不提供配置写入 API
4. 删除保护：默认禁用删除功能，需用户手动开启，配合文档级保护标记形成多层防护
5. NLP 扩展：可选集成 Ollama 与 Qdrant，支持实体提取、关键词分析、向量索引等 AI 能力
潜在缺点
1. 环境依赖重：必须同时运行 Node.js >=14 和思源笔记 >=3.6.0 服务端，且需手动配置 SIYUAN_TOKEN 等环境变量
2. 学习成本：需区分文档 ID 与块 ID 的使用场景，命令参数较多，新手易混淆 update 与 block-update
3. 向量搜索配置复杂：语义搜索需额外部署 Qdrant 和 Ollama，配置 10+ 个环境变量，非技术用户门槛高
4. 仅支持本地实例：官方推荐仅使用 http://localhost:6806，远程部署存在安全隐患
适合人群
- 思源笔记重度用户，希望通过脚本自动化笔记管理
- 开发者需要与思源笔记集成的第三方工具链
- 对本地优先、隐私敏感的知识管理有要求的用户
- 愿意投入时间配置向量搜索等高级功能的技术爱好者
常规风险
- Token 泄露：SIYUAN_TOKEN 拥有完整 API 权限，需妥善保管环境变量
- 误删除数据：虽有多层删除保护，但开启安全模式后仍需谨慎操作
- 向量搜索成本：语义索引会占用额外存储与计算资源，大规模笔记库需评估性能
- 版本兼容性：需严格匹配 Node.js 14+ 与思源笔记 3.6.0+，升级时需同步验证