运行要求: Node.js >= 14.0.0, 思源笔记 >= 3.6.0 安装: 从 ClawHub 下载
快速开始
node {baseDir}/scripts/<command>.js [options]
node {baseDir}/scripts/<command>.js --help # 查看命令帮助
场景化快速开始
💡 根据你的任务场景，快速找到对应的命令和工作流
我要...
📋 更多场景：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 | 格式规范 | 写入内容前查阅 |
🔧 配置与权限
🚀 进阶功能
📖 示例文档
🎯 快速导航
🔧 遇到问题？
如果在使用过程中遇到任何问题，请按以下步骤排查：
1. 查看错误信息
错误信息中通常会包含：
2. 查阅问题解决索引
📋 troubleshooting.md - 按错误信息和任务场景组织的完整问题索引
3. 查看快速参考
📋 quick-reference.md - 命令决策表和常见错误预防
4. 查看详细文档
5. 查看示例
💡 快速链接：规范索引 | 问题解决索引
