核心用法
siyuan-skill 是将思源笔记（Siyuan Note）REST API 封装为命令行界面的桥接工具，面向开发者和高级用户实现程序化笔记管理。核心工作流围绕笔记本-文档-块三级结构展开：
- 笔记本层：
notebooks/nb列出现有笔记本，structure/ls递归查看目录树 - 文档层：
create/new支持传统模式（指定parent-id）或路径模式（--path "笔记本/A/B"）；update/edit做全文替换；move/rename/delete完成生命周期管理 - 块层：
block-get/bg查看Kramdown源码结构，block-update/bu精确修改单个块，block-insert/bi、block-delete/bd实现细粒度内容操作 - 搜索层：
search/find支持 legacy/keyword/semantic/hybrid 四种模式，需额外配置 Qdrant + Ollama 以启用向量检索
显著优点
1. API 完整覆盖：思源官方API的超集封装，包含文档图标、属性标记、标签系统、折叠状态等细节功能
2. 多模态搜索：从 SQL LIKE 到稠密向量+稀疏向量混合检索，兼顾精确匹配与语义理解
3. 安全设计：删除功能默认禁用，需用户手动在 config.json 开启；Token 仅读取、不写入；配置只读保护
4. NLP 扩展：支持分词、实体抽取、关键词提取，可与搜索链路打通
潜在局限
- 本地依赖强：必须运行本地思源实例（推荐
http://localhost:6806），无法直接操作云端同步仓库 - 向量搜索门槛高：需独立部署 Qdrant 和 Ollama，配置复杂，且对硬件有一定要求
- ID 混淆风险：
update（文档级）与block-update（块级）命令参数极易误用，文档强调需先执行bg --mode kramdown确认结构 - Node.js 版本锁：要求 >=14.0.0，旧环境需升级
适合人群
- 需要批量导入/导出笔记的开发者
- 希望用脚本自动化知识库维护的重度思源用户
- 搭建个人知识管理 pipeline（结合 CI/CD、定时任务）的技术爱好者
常规风险
- 误删数据：尽管有多层删除保护（全局安全模式→文档保护标记→确认机制），强制开启后仍存在不可逆操作风险
- Token 泄露：
SIYUAN_TOKEN需通过环境变量注入，若硬编码到脚本或日志中可能导致未授权访问 - 搜索阈值误设：语义搜索
--threshold过低会引入大量噪声结果，过高则漏检，需根据业务场景调优 - TLS 自签名证书：若启用
SIYUAN_TLS_ALLOW_SELF_SIGNED，需配合SIYUAN_TLS_ALLOWED_HOSTS严格限定域名，防止中间人攻击