运行要求： Node.js >= 14.0.0，思源笔记 >= 3.6.0

安装： 从 ClawHub 下载，详见安装配置指南

环境变量： 参考环境变量文档

快速开始

cd skills/siyuan-skill
node siyuan.js <command> [options]
node siyuan.js help <command>  # 查看命令帮助
node siyuan.js --version       # 显示版本信息

快速决策表

根据用户需求快速选择正确的命令：

笔记本与文档操作

| 用户需求 | 使用命令 | 关键参数 | 示例 | |----------|----------|----------|------| | 查看笔记本列表 | notebooks / nb | 无 | siyuan nb | | 查看文档结构 | structure / ls | --depth | siyuan ls <notebookId> | | 查看文档内容 | content / cat | 无 | siyuan cat <docId> | | 获取文档信息 | info | 文档ID | siyuan info <docId> | | 创建新文档 | create / new | --parent-id 或 --path | siyuan create "标题" --parent-id xxx | | 修改整个文档 | update / edit | 文档ID | siyuan update <docId> "完整内容" | | 删除文档 | delete / rm | 文档ID | siyuan rm <docId> | | 移动文档 | move / mv | --new-title（可选） | siyuan mv <docId> <targetId> | | 重命名文档 | rename | 新标题 | siyuan rename <docId> "新标题" | | 保护/取消保护 | protect | --on / --off | siyuan protect <docId> --on | | 检查文档存在 | exists / check | --title 或 --path | siyuan exists --title "标题" | | 转换ID和路径 | convert / path | --to-id 或 --to-path | siyuan path "/笔记本/文档" --to-id | | 设置文档图标 | icon / set-icon | --emoji / --get / --remove | siyuan icon <docId> --emoji 1f4c4 | | 设置文档属性 | block-attrs / ba | --set / --get / --remove | siyuan ba <docId> --set "status=done" | | 设置标签 | tags / st | --tags | siyuan st <docId> --tags "A,B" | | 搜索内容 | search / find | --mode / --threshold | siyuan search "关键词" --mode semantic |

块操作

| 用户需求 | 使用命令 | 关键参数 | 示例 | |----------|----------|----------|------| | 获取块信息 | block-get / bg | --mode | siyuan bg <blockId> --mode kramdown | | 修改单个块 | block-update / bu | 块ID（非文档ID） | siyuan bu <blockId> "块内容" | | 插入新块 | block-insert / bi | --parent-id / --next-id | siyuan bi "内容" --parent-id xxx | | 删除单个块 | block-delete / bd | 块ID | siyuan bd <blockId> | | 移动块 | block-move / bm | --parent-id / --next-id | siyuan bm <blockId> --parent-id xxx | | 折叠/展开块 | block-fold / bf | --fold / --unfold | siyuan bf <blockId> --fold | | 转移块引用 | block-transfer-ref / btr | 源块ID、目标块ID | siyuan btr <srcId> <tgtId> |

重要区分：update 只接受文档ID，block-update 只接受块ID

块操作决策流程

操作前必须执行：

先用 bg <blockId> --mode kramdown 查看块结构
分析哪些块是多余的、哪些需要修改
根据目标选择正确的命令

| 目标 | 命令 | 说明 | |------|------|------| | 删除不需要的块 | bd <blockId> | 整个块删除 | | 修改块内容 | bu <blockId> "新内容" | 保留块 ID，更新内容 | | 查看块结构 | bg <blockId> --mode kramdown | 查看 kramdown 格式 | | 查看文档内容 | content <docId> | 查看完整文档 |

重名检测

以下命令在执行前会自动检测目标位置是否存在同名文档：

| 命令 | 检测时机 | 冲突处理 | |------|----------|----------| | create | 创建前 | 返回错误，使用 --force 强制创建 | | move | 移动前 | 返回错误，使用 --new-title 指定新标题 | | rename | 重命名前 | 返回错误，需更换新标题 |

手动检查文档是否存在：

siyuan exists --title "文档标题" [--parent-id <父文档ID>]
siyuan exists --path "/目录/文档标题"

删除保护

默认禁止删除文档。如需启用删除功能，必须由用户手动在 config.json 中配置。

⚠️ Agent 禁止自动修改此配置

保护层级：全局安全模式 → 文档保护标记 → 删除确认机制

💡 提示：如删除被阻止，应告知用户修改配置或使用 protect 命令移除文档保护标记

最佳实践

标准工作流

创建文档

1. 检查文档是否存在
   └─ siyuan exists --title "标题" [--parent-id <父ID>]
   
2a. 如不存在 → 直接创建
    └─ siyuan create "标题" "内容" --parent-id <id>
    
2b. 如存在 → 询问用户
    ├─ 覆盖？ → siyuan update <docId> "新内容"
    └─ 新建同名？ → siyuan create "标题" "内容" --force

修改文档

1. 获取当前内容
   └─ siyuan content <docId>
   
2. 判断修改范围
   ├─ 全文替换 → siyuan update <docId> "完整新内容"
   └─ 仅修改部分块 → 先 siyuan bg <docId> --mode kramdown

create 命令

| 模式 | 场景 | 示例 | |------|------|------| | 传统模式 | 已知父ID | siyuan create "标题" "内容" --parent-id <id> | | 路径指定 | 创建多级目录 | siyuan create --path "笔记本/A/B/C" "内容" | | 目录下创建 | 批量创建 | siyuan create --path "笔记本/目录/" "标题" "内容" |

📋 详细用法见 create 命令文档

内容修改

# ✅ 推荐
siyuan update <docId> "新内容"        # 全文更新：必须传入完整的文档内容
siyuan bu <blockId> "新内容"          # 块更新：只需传入需要修改的块内容

# ❌ 错误：混用命令
siyuan bu <docId> "内容"              # 错误：block-update 不接受文档ID
siyuan update <blockId> "内容"        # 错误：update 不接受块ID

属性设置

siyuan ba <docId> --set "status=published"
siyuan ba <docId> --get
siyuan ba <docId> --remove "status"
siyuan st <docId> --tags "重要,待审核"

图标设置

siyuan icon <docId> --emoji 📄       # 直接传入 emoji
siyuan icon <docId> --emoji 1f4c4    # 或使用编码
siyuan icon <docId> --get            # 获取图标
siyuan icon <docId> --remove         # 移除图标

📋 完整 emoji 编码表见图标命令文档

文档格式

# ✅ 正确：使用 \n 换行
siyuan create "标题" "第一段\n\n## 二级标题\n内容"

# ❌ 错误：所有内容在一行
siyuan create "标题" "第一段## 二级标题 内容"

常见错误预防

| 错误场景 | 错误做法 | 正确做法 | |----------|----------|----------| | 文档已存在 | 直接 create | 先 exists 检查，再用 --force | | 删除被阻止 | 反复尝试 | 告知用户修改配置或使用 protect | | ID 类型混淆 | update 用块ID | update 只用文档ID，bu 只用块ID | | 修改部分内容 | 删了重建 | 用 bu 或 bd 进行块级操作 |

书写规范

内部链接

((docId '标题'))

SQL 嵌入块

{{ SELECT * FROM blocks WHERE type = 'd' ORDER BY updated DESC LIMIT 5 }}

📋 完整规范见书写指南和最佳实践

高级功能

向量搜索（可选）

需配置 QDRANT_URL + OLLAMA_BASE_URL。

| 模式 | 说明 | 适用场景 | |------|------|----------| | legacy | SQL LIKE 精确匹配 | 精确关键词 | | keyword | BM25 + N-gram | 关键词匹配 | | semantic | 语义向量 | 同义词、概念 | | hybrid | 稠密 + 稀疏 | 综合搜索 |

siyuan index                        # 增量索引
siyuan search "关键词" --mode semantic

相关度分数参考：

| 分数范围 | 相关性 | 说明 | |----------|--------|------| | 0.9-1.0 | 极高 | 几乎相同内容 | | 0.7-0.9 | 高度 | 语义非常接近 | | 0.5-0.7 | 中等 | 语义有交集 | | <0.5 | 弱 | 参考价值低 |

siyuan search "关键词" --mode semantic --threshold 0.7

📋 详细配置见向量搜索文档

NLP 分析

siyuan nlp "文本" --tasks tokenize,keywords

📋 详细用法见 NLP 文档

安全要点

仅使用本地实例 (http://localhost:6806)
推荐使用 whitelist 权限模式
删除功能默认禁用，需用户手动配置
配置只读保护：CLI 命令集不暴露任何配置修改 API，敏感配置（token 等）仅通过环境变量注入，不会持久化到配置文件
Token 安全：SIYUAN_TOKEN 仅从环境变量或 config.json 读取，技能本身绝不会修改或写入 token
可选功能：QDRANT_URL、OLLAMA_BASE_URL 为可选配置，如不需要向量搜索/NLP 功能，无需配置这些变量

📋 详细安全配置见配置文档

安全声明

配置只读保护

重要：本技能采用配置只读设计原则。

所有敏感配置（token、API 密钥等）仅通过环境变量或 config.json 读取
技能本身不提供任何配置写入能力
配置变更需要用户手动修改环境变量或配置文件

Siyuan Skill