场景	核心命令	详细文档
创建新文档	`create.js`	文档工作流示例
更新文档内容	`update.js` / `block-update.js`	基础用法示例
搜索内容	`search.js`	向量搜索配置
删除文档	`delete.js`	删除保护文档 ⚠️
批量操作	`search.js` + 其他命令	批量整理文档
使用语义搜索	`search.js --mode semantic`	向量搜索文档
遇到权限问题	-	配置说明
遇到删除问题	-	删除保护文档
遇到搜索问题	-	向量搜索配置
写入内容格式错误	-	格式标准

📋 更多场景：troubleshooting.md

命令列表

笔记本/文档操作

脚本	说明	示例
`notebooks`	列出笔记本	`node {baseDir}/scripts/notebooks.js`
`structure`	查看文档结构	`node {baseDir}/scripts/structure.js <notebookId\|docId>`
`content`	获取文档内容	`node {baseDir}/scripts/content.js <docId>`
`info`	获取文档/块信息	`node {baseDir}/scripts/info.js <docId> [--raw]`
`create`	创建文档	`node {baseDir}/scripts/create.js <title> --parent-id <id>` 或 `--path <path>`
`update`	更新文档	`node {baseDir}/scripts/update.js <docId> --content <md>`
`delete`	删除文档	`node {baseDir}/scripts/delete.js <docId>`
`move`	移动文档	`node {baseDir}/scripts/move.js <docId\|path> --target <notebookId\|path>`
`rename`	重命名文档	`node {baseDir}/scripts/rename.js <docId> <title>`
`protect`	保护/取消保护	`node {baseDir}/scripts/protect.js <docId>`
`exists`	检查文档存在	`node {baseDir}/scripts/exists.js --title <title>`
`convert`	ID与路径转换	`node {baseDir}/scripts/convert.js --id <id>`
`icon`	设置/获取图标	`node {baseDir}/scripts/icon.js <id> [emoji]` 或 `--remove`

块操作

脚本	说明	示例
`block-get`	获取块信息	`node {baseDir}/scripts/block-get.js <blockId>`
`block-insert`	插入块	`node {baseDir}/scripts/block-insert.js "内容" --parent-id <id>`
`block-update`	更新块	`node {baseDir}/scripts/block-update.js <blockId> --content <md>`
`block-delete`	删除块	`node {baseDir}/scripts/block-delete.js <blockId>`
`block-move`	移动块	`node {baseDir}/scripts/block-move.js <blockId> --parent-id <parentId>`
`block-fold`	折叠/展开	`node {baseDir}/scripts/block-fold.js <blockId> --action fold`
`block-transfer`	转移引用	`node {baseDir}/scripts/block-transfer.js <srcId> <tgtId>`
`block-attrs`	块属性	`node {baseDir}/scripts/block-attrs.js <blockId> --set key=value`

搜索/索引

脚本	说明	示例
`search`	搜索内容	`node {baseDir}/scripts/search.js <query> --mode keyword`
`tags`	标签管理	`node {baseDir}/scripts/tags.js <docId\|blockId> --add tag1,tag2`
`index`	索引到向量库	`node {baseDir}/scripts/index.js --notebook <id>`
`nlp`	NLP分析	`node {baseDir}/scripts/nlp.js <text>`

关键规则

ID 区分

文档操作 (update/delete/move/rename) 接受文档 ID（部分命令也支持路径）
块操作 (block-update/block-delete 等) 只接受块 ID
混用会导致错误, 详见快速参考

删除保护

默认禁止删除文档, 需用户手动在 config.json 中启用
保护层级: 全局安全模式 → 文档保护标记 → 删除确认机制
Agent 禁止自动修改删除配置
详见安全文档

权限验证

支持 permissionMode: all(默认) / whitelist / blacklist
写入操作 (create/update/delete/move 等) 会检查笔记本权限
通过 SIYUAN_NOTEBOOK_LIST 环境变量配置笔记本列表

格式规范（重要）

写入思源笔记时必须遵循以下格式：

场景	正确格式	错误格式
内部链接	`((id "锚文本"))`	`[文本](id)` ❌
动态锚文本	`((id '锚文本'))`	`((id 锚文本))` ❌
换行	`\\n`	直接换行
段落分隔	`\\n\\n`	单个 \n

📋 完整规范：format-standard.md | 快速参考：quick-reference.md

搜索模式

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

向量搜索需配置 QDRANT_URL + OLLAMA_BASE_URL

标准工作流

创建: exists 检查 → create (或 --force)
修改: content 获取 → 判断范围 → update (全文) 或 block-update (单块)
搜索: search 查询 → content 查看 → update/block-update 修改
删除: protect 检查 → delete

📋 完整工作流示例见 examples/basic-usage.md

参考文档

📋 必读文档

文档	用途	何时阅读
SKILL.md	本文档，核心入口	首次使用必读
troubleshooting.md	问题解决索引	遇到问题时查阅
quick-reference.md	快速决策表	选择命令时查阅
format-standard.md	格式规范	写入内容前查阅

🔧 配置与权限

文档	用途
配置说明	环境变量和 config.json 配置
高级配置	完整配置选项

🚀 进阶功能

文档	用途
向量搜索	语义搜索配置和使用
删除保护	删除保护机制说明
最佳实践	使用建议和技巧
安全文档	安全最佳实践

📖 示例文档

文档	用途
基础用法	常用命令示例
文档工作流	完整任务场景示例
块操作指南	块级操作详解

🎯 快速导航

遇到问题：troubleshooting.md
查看命令：quick-reference.md
格式规范：format-standard.md
规范索引：spec-index.md

🔧 遇到问题？

如果在使用过程中遇到任何问题，请按以下步骤排查：

1. 查看错误信息

错误信息中通常会包含：

错误原因
解决方案提示
相关文档链接

2. 查阅问题解决索引

📋 troubleshooting.md - 按错误信息和任务场景组织的完整问题索引

3. 查看快速参考

📋 quick-reference.md - 命令决策表和常见错误预防

4. 查看详细文档

问题类型	文档
连接/权限	配置说明
删除问题	删除保护文档
搜索问题	向量搜索文档
格式问题	格式标准

5. 查看示例

💡 快速链接：规范索引 | 问题解决索引

siyuan-skill

快速开始

场景化快速开始

我要...