运行要求： Node.js >= 14.0.0，思源笔记 >= 3.6.0
安装： 从 ClawHub 下载，详见 安装配置指南
环境变量： 参考 环境变量文档
快速开始
CODEBLOCK0
快速决策表
根据用户需求快速选择正确的命令：
笔记本与文档操作
| 用户需求 | 使用命令 | 关键参数 | 示例 |
|---|
| 查看笔记本列表 | INLINECODE0 / INLINECODE1 | 无 | INLINECODE2 |
| 查看文档结构 |
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 |
块操作
| 用户需求 | 使用命令 | 关键参数 | 示例 |
|---|
| 获取块信息 | INLINECODE64 / INLINECODE65 | INLINECODE66 | INLINECODE67 |
| 修改单个块 |
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
块操作决策流程
操作前必须执行：
- 1. 先用
bg <blockId> --mode kramdown 查看块结构 - 分析哪些块是多余的、哪些需要修改
- 根据目标选择正确的命令
| 目标 | 命令 | 说明 |
|---|
| 删除不需要的块 | INLINECODE95 | 整个块删除 |
| 修改块内容 |
bu <blockId> "新内容" | 保留块 ID，更新内容 |
| 查看块结构 |
bg <blockId> --mode kramdown | 查看 kramdown 格式 |
| 查看文档内容 |
content <docId> | 查看完整文档 |
重名检测
以下命令在执行前会自动检测目标位置是否存在同名文档：
| 命令 | 检测时机 | 冲突处理 |
|---|
| INLINECODE99 | 创建前 | 返回错误，使用 --force 强制创建 |
| INLINECODE101 |
移动前 | 返回错误，使用
--new-title 指定新标题 |
|
rename | 重命名前 | 返回错误，需更换新标题 |
手动检查文档是否存在：
CODEBLOCK1
删除保护
默认禁止删除文档。如需启用删除功能，必须由用户手动在 config.json 中配置。
⚠️ Agent 禁止自动修改此配置
保护层级：全局安全模式 → 文档保护标记 → 删除确认机制
💡 提示：如删除被阻止，应告知用户修改配置或使用 protect 命令移除文档保护标记
最佳实践
标准工作流
创建文档
CODEBLOCK2
修改文档
CODEBLOCK3
create 命令
| 模式 | 场景 | 示例 |
|---|
| 传统模式 | 已知父ID | INLINECODE106 |
| 路径指定 |
创建多级目录 |
siyuan create --path "笔记本/A/B/C" "内容" |
| 目录下创建 | 批量创建 |
siyuan create --path "笔记本/目录/" "标题" "内容" |
📋 详细用法见 create 命令文档
内容修改
CODEBLOCK4
属性设置
CODEBLOCK5
图标设置
CODEBLOCK6
📋 完整 emoji 编码表见 图标命令文档
文档格式
CODEBLOCK7
常见错误预防
| 错误场景 | 错误做法 | 正确做法 |
|---|
| 文档已存在 | 直接 create | 先 exists 检查，再用 INLINECODE110 |
| 删除被阻止 |
反复尝试 | 告知用户修改配置或使用
protect |
| ID 类型混淆 |
update 用块ID |
update 只用文档ID，
bu 只用块ID |
| 修改部分内容 | 删了重建 | 用
bu 或
bd 进行块级操作 |
书写规范
内部链接
CODEBLOCK8
SQL 嵌入块
CODEBLOCK9
📋 完整规范见 书写指南 和 最佳实践
高级功能
向量搜索（可选）
需配置 QDRANT_URL + OLLAMA_BASE_URL。
| 模式 | 说明 | 适用场景 |
|---|
| INLINECODE119 | SQL LIKE 精确匹配 | 精确关键词 |
| INLINECODE120 |
BM25 + N-gram | 关键词匹配 |
|
semantic | 语义向量 | 同义词、概念 |
|
hybrid | 稠密 + 稀疏 | 综合搜索 |
CODEBLOCK10
相关度分数参考：
| 分数范围 | 相关性 | 说明 |
|---|
| 0.9-1.0 | 极高 | 几乎相同内容 |
| 0.7-0.9 |
高度 | 语义非常接近 |
| 0.5-0.7 | 中等 | 语义有交集 |
| <0.5 | 弱 | 参考价值低 |
CODEBLOCK11
📋 详细配置见 向量搜索文档
NLP 分析
CODEBLOCK12
📋 详细用法见 NLP 文档
安全要点
- - 仅使用本地实例 (
http://localhost:6806) - 推荐使用
whitelist 权限模式 - 删除功能默认禁用，需用户手动配置
- 配置只读保护：CLI 命令集不暴露任何配置修改 API，敏感配置（token 等）仅通过环境变量注入，不会持久化到配置文件
- Token 安全：SIYUANTOKEN 仅从环境变量或 config.json 读取，技能本身绝不会修改或写入 token
- 可选功能：QDRANTURL、OLLAMABASEURL 为可选配置，如不需要向量搜索/NLP 功能，无需配置这些变量
📋 详细安全配置见 配置文档
安全声明
配置只读保护
重要：本技能采用配置只读设计原则。
- - 所有敏感配置（token、API 密钥等）仅通过环境变量或 config.json 读取
- 技能本身不提供任何配置写入能力
- 配置变更需要用户手动修改环境变量或配置文件
Token 处理
- -
SIYUAN_TOKEN 仅从环境变量或 config.json 读取 - 技能本身绝不修改或写入 token
- Token 变更需要用户手动操作
可选功能
- -
QDRANT_URL、OLLAMA_BASE_URL 为可选配置 - 如不需要向量搜索/NLP 功能，无需配置这些变量
- 不配置时，技能将使用基础的 SQL 搜索模式
参考文档
运行要求： Node.js >= 14.0.0，思源笔记 >= 3.6.0
安装： 从 ClawHub 下载，详见 安装配置指南
环境变量： 参考 环境变量文档
快速开始
bash
cd skills/siyuan-skill
node siyuan.js [options]
node siyuan.js help # 查看命令帮助
node siyuan.js --version # 显示版本信息
快速决策表
根据用户需求快速选择正确的命令：
笔记本与文档操作
| 用户需求 | 使用命令 | 关键参数 | 示例 |
|---|
| 查看笔记本列表 | notebooks / nb | 无 | siyuan nb |
| 查看文档结构 |
structure / ls | --depth | siyuan ls
|
| 查看文档内容 | content / cat | 无 | siyuan cat |
| 获取文档信息 | info | 文档ID | siyuan info |
| 创建新文档 | create / new | --parent-id 或 --path | siyuan create 标题 --parent-id xxx |
| 修改整个文档 | update / edit | 文档ID | siyuan update 完整内容 |
| 删除文档 | delete / rm | 文档ID | siyuan rm |
| 移动文档 | move / mv | --new-title（可选） | siyuan mv |
| 重命名文档 | rename | 新标题 | siyuan rename 新标题 |
| 保护/取消保护 | protect | --on / --off | siyuan protect --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 --emoji 1f4c4 |
| 设置文档属性 | block-attrs / ba | --set / --get / --remove | siyuan ba --set status=done |
| 设置标签 | tags / st | --tags | siyuan st --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 块内容 |
| 插入新块 | block-insert / bi | --parent-id / --next-id | siyuan bi 内容 --parent-id xxx |
| 删除单个块 | block-delete / bd | 块ID | siyuan bd |
| 移动块 | block-move / bm | --parent-id / --next-id | siyuan bm --parent-id xxx |
| 折叠/展开块 | block-fold / bf | --fold / --unfold | siyuan bf --fold |
| 转移块引用 | block-transfer-ref / btr | 源块ID、目标块ID | siyuan btr |
重要区分：update 只接受文档ID，block-update 只接受块ID
块操作决策流程
操作前必须执行：
- 1. 先用 bg --mode kramdown 查看块结构
- 分析哪些块是多余的、哪些需要修改
- 根据目标选择正确的命令
| 目标 | 命令 | 说明 |
|---|
| 删除不需要的块 | bd <blockId> | 整个块删除 |
| 修改块内容 |
bu 新内容 | 保留块 ID，更新内容 |
| 查看块结构 | bg --mode kramdown | 查看 kramdown 格式 |
| 查看文档内容 | content | 查看完整文档 |
重名检测
以下命令在执行前会自动检测目标位置是否存在同名文档：
| 命令 | 检测时机 | 冲突处理 |
|---|
| create | 创建前 | 返回错误，使用 --force 强制创建 |
| move |
移动前 | 返回错误，使用 --new-title 指定新标题 |
| rename | 重命名前 | 返回错误，需更换新标题 |
手动检查文档是否存在：
bash
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
2b. 如存在 → 询问用户
├─ 覆盖？ → siyuan update 新内容
└─ 新建同名？ → siyuan create 标题 内容 --force
修改文档
- 1. 获取当前内容
└─ siyuan content
- 2. 判断修改范围
├─ 全文替换 → siyuan update 完整新内容
└─ 仅修改部分块 → 先 siyuan bg --mode kramdown
create 命令
| 模式 | 场景 | 示例 |
|---|
| 传统模式 | 已知父ID | siyuan create 标题 内容 --parent-id <id> |
| 路径指定 |
创建多级目录 | siyuan create --path 笔记本/A/B/C 内容 |
| 目录下创建 | 批量创建 | siyuan create --path 笔记本/目录/ 标题 内容 |
📋 详细用法见 create 命令文档
内容修改
bash
✅ 推荐
siyuan update 新内容 # 全文更新：必须传入完整的文档内容
siyuan bu 新内容 # 块更新：只需传入需要修改的块内容
❌ 错误：混用命令
siyuan bu 内容 # 错误：block-update 不接受文档ID
siyuan update 内容 # 错误：update 不接受块ID
属性设置
bash
siyuan ba --set status=published
siyuan ba --get
siyuan ba --remove status
siyuan st --tags 重要,待审核
图标设置
bash
siyuan icon --emoji 📄 # 直接传入
