SkillHub

siyuan-skill

v1.6.3

思源笔记命令行工具，提供便捷的命令行操作方式，支持笔记本管理、文档操作、内容搜索、块控制等功能

Sourced from ClawHub, Authored by daze

Installation

Please help me install the skill `siyuan-skill` from SkillHub official store. npx skills add dazexcl/siyuan-skill

核心价值

提供 AI Agent 可快速接入思源笔记的 skill 方案

适用场景

✅ 团队规范、项目知识、可复用技能 ✅ 需要多 Agent 共享的知识 ✅ 需要长期存储和检索的内容

不适用场景

❌ 日常互动记录、个人学习反思 ❌ 临时笔记、代码版本管理 ❌ 实时协作编辑

环境变量要求

⚠️ 必须配置的环境变量（缺少将无法正常使用）

环境变量 说明 示例
SIYUAN_BASE_URL 思源笔记 API 地址（建议使用 localhost） http://127.0.0.1:6806
SIYUAN_TOKEN API 认证令牌 从思源设置中获取
SIYUAN_DEFAULT_NOTEBOOK 默认笔记本 ID 20260227231831-yq1lxq2

🔒 安全建议：仅将 SIYUAN_BASE_URL 设置为受信任的本地实例（如 http://127.0.0.1:6806）

重要约束

必须使用 CLI 命令来操作思源笔记

💡 说明：本技能通过 CLI 命令与思源笔记 HTTP API 通信。用户/AI Agent 应使用 CLI 命令（如 siyuan create、siyuan search），而非直接调用思源笔记 API。

禁止agent自动修改配置文件与本技能相关环境变量配置，避免导致意外的权限泄露

问题导向文档导航

💡 提示：遇到以下问题时，建议先查阅对应文档以获取详细说明。如需深入理解实现细节，可以查阅源码（本技能完全开源，欢迎审计）。

问题类型 查阅文档 说明
如何获取笔记本列表 doc/commands/notebooks.md 笔记本列表命令
如何获取文档结构 doc/commands/structure.md 文档结构命令
如何获取文档内容 doc/commands/content.md 文档内容命令
如何创建文档 doc/commands/create.md 创建命令详解
如何更新文档 doc/commands/update.md 更新命令详解
如何删除文档 doc/commands/delete.md 删除命令详解
删除被阻止 doc/advanced/delete-protection.md 删除保护机制
如何保护文档 doc/commands/protect.md 文档保护命令
如何移动文档 doc/commands/move.md 移动文档命令
如何重命名文档 doc/commands/rename.md 重命名文档命令
如何搜索内容 doc/commands/search.md 搜索命令详解
搜索结果不准确 doc/advanced/vector-search.md 向量搜索配置
如何设置标签 doc/commands/tags.md 标签命令详解
块操作问题 doc/commands/block-control.md 块控制命令详解
如何转换ID和路径 doc/commands/convert.md ID/路径转换命令
如何索引文档 doc/commands/index.md 索引命令详解
如何使用NLP分析 doc/commands/nlp.md NLP分析命令
配置环境变量 doc/config/environment.md 环境变量配置
高级配置 doc/config/advanced.md 详细配置选项
使用最佳实践 doc/advanced/best-practices.md 最佳实践指南
命令参数说明 siyuan help <command> CLI 帮助命令

快速开始

# 方式 1：进入技能目录运行
cd <skills-directory>/siyuan-skill
node siyuan.js <command>

# 方式 2：使用 npm link 全局安装（推荐）
npm link -g
siyuan <command>

# 方式 3：直接指定路径运行
node <skills-directory>/siyuan-skill/siyuan.js <command>

查看帮助

# 查看所有可用命令
siyuan help

# 查看特定命令帮助
siyuan help <command>

命令列表

常用命令： | 命令 | 别名 | 说明 | |------|------|------| | notebooks | nb | 获取笔记本列表 | | structure | ls | 获取文档结构 | | content | cat | 获取文档内容 | | create | new | 创建文档 | | update | edit, bu | 更新文档/块内容 | | delete | rm | 删除文档（受保护） | | protect | - | 设置/移除文档保护 | | move | mv | 移动文档 | | rename | - | 重命名文档 | | search | find | 搜索内容 | | convert | path | 转换 ID 和路径 | | index | - | 索引到向量数据库 | | nlp | - | NLP 文本分析 [实验性] | | block-attrs | ba, attrs | 设置块/文档属性 | | tags | st | 设置块/文档标签 |

块控制命令： | 命令 | 别名 | 说明 | |------|------|------| | block-insert | bi | 插入块 | | block-update | bu | 更新块（同 update） | | block-delete | bd | 删除块 | | block-move | bm | 移动块 | | block-get | bg | 获取块信息 | | block-fold | bf, buu | 折叠/展开块 | | block-transfer-ref | btr | 转移块引用 |

删除保护

默认禁止删除，需在 config.json 中配置：

{
  "deleteProtection": {
    "safeMode": false,
    "requireConfirmation": true
  }
}
配置项 默认值 说明
safeMode true 禁止所有删除
requireConfirmation false 删除需确认标题

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

更新方式选择

场景 推荐方式
创建/重写文档 edit 全文档更新
局部修改 bu 块更新 ✅
保留块属性 bu 块更新 ✅

注意：文档本身也是一种块，edit 和 bu 本质调用相同 API。

内容修改最佳实践

修改内容时使用修改命令

推荐做法：使用 update 或 bu 命令直接修改内容

# ✅ 推荐：直接更新文档内容
siyuan update <docId> "新内容"

# ✅ 推荐：更新块内容
siyuan bu <blockId> "新内容"

# ❌ 不推荐：删除再新建（会丢失属性、引用关系等）
siyuan delete <docId>
siyuan create "标题" "内容"

原因： - 删除再新建会丢失文档属性、标签、保护标记 - 删除再新建会破坏其他文档对该文档的引用关系 - 修改命令保留所有元数据

不要在文档中附加 Front Matter

推荐做法：使用 block-attrs 命令设置文档属性

# ✅ 推荐：设置文档属性
siyuan ba <docId> --attrs "status=published,priority=high"

# ✅ 推荐：设置文档标签
siyuan st <docId> --tags "重要,待审核"

# ❌ 不推荐：在内容中添加 Front Matter
siyuan update <docId> "---ntitle: 标题nstatus: publishedn---n内容"

原因： - 思源笔记中的 Front Matter 只是普通文本，不会被解析为属性 - 使用 block-attrs 设置的属性可被搜索、筛选 - 属性与内容分离，更易管理

文档内容规范

文档格式说明

写入格式：创建/更新文档使用 Markdown 格式

API 的 dataType 参数只支持 markdown 和 dom 两种类型，不支持 kramdown 作为写入格式。

⚠️ 换行符使用说明

重要：Markdown 语法要求标题、列表等块级元素前必须有空行才能正确解析。

在命令行中传入多段内容时，必须使用 n 显式换行：

# ❌ 错误 - 所有内容在一行，标题不会被正确解析
siyuan create "标题" "第一段内容。## 二级标题 标题下的内容"

# ✅ 正确 - 使用 n 换行，标题正确解析为独立块
siyuan create "标题" "第一段内容。nn## 二级标题n标题下的内容"

# ✅ 完整示例 - 多段落、多级标题
siyuan create "文档" "概述内容。nn## 第一章n第一章内容。nn## 第二章n第二章内容。nn### 2.1 小节n小节内容。"

常见格式对应的换行符：

格式 换行符 示例
段落分隔 nn 段落1nn段落2
二级标题 nn## 内容nn## 标题n内容
三级标题 nn### 内容nn### 标题n内容
列表项 n- 列表项1n- 列表项2 
# 创建文档 - 使用 Markdown 格式
siyuan create "标题" "正文内容nn**粗体** *斜体*nn- 列表项1n- 列表项2"

# 更新文档 - 使用 Markdown 格式
siyuan update <docId> "更新后的内容"

读取格式：获取文档内容时可选择格式

格式 用途 说明
markdown 写入/读取 标准 Markdown，API dataType 支持此格式
dom 写入/读取 HTML 格式，API dataType 支持此格式
kramdown 仅读取 带 ID 和属性的 Markdown，通过 /api/block/getBlockKramdown API 获取

kramdown 格式说明（仅用于读取）：

kramdown 是思源笔记内部格式，通过专门的 API /api/block/getBlockKramdown 获取，格式示例：

正文内容
{: id="block-id" updated="20260312142019"}

{: id="doc-id" title="文档标题" type="doc" updated="20260312142019"}

特点： - 每个块后面跟着 {: key="value"} 形式的属性 - 最后一行是文档块本身的属性 - kramdown 格式只能读取，不能用于写入

在 Markdown 中使用属性语法（高级用法）：

虽然 dataType 不支持 kramdown，但可以在 Markdown 内容中使用 {: key="value"} 语法设置块样式或自定义属性：

# 设置行内样式（API 文档示例）
siyuan update <docId> "foo**bar**{: style="color: var(--b3-font-color8);"}baz"

# 设置自定义属性
siyuan update <docId> "段落内容{: custom-attr="custom-value"}"

文档内容不应包含标题

推荐做法：内容直接从正文开始，标题通过 title 属性或创建命令指定

# ✅ 推荐：创建时指定标题，内容从正文开始
siyuan create "文档标题" "正文内容第一行n正文内容第二行"

# ✅ 推荐：更新时内容不含标题
siyuan update <docId> "正文内容"

# ❌ 不推荐：内容中包含标题
siyuan create "文档标题" "# 文档标题n正文内容"

原因： - 文档标题已通过 title 属性存储，重复写入会造成冗余 - 标题在文档列表、搜索结果中自动显示 - 内容中的标题会与文档标题重复显示

文档包含下级文档时不等于文档为空

注意：判断文档是否为空时，不能仅检查内容长度

# 获取文档结构
siyuan ls <notebookId>

# 文档可能有以下情况：
# 1. 有内容，无下级文档 → 内容文档
# 2. 无内容，有下级文档 → 容器文档（目录）
# 3. 有内容，有下级文档 → 混合文档
# 4. 无内容，无下级文档 → 空文档

原因： - 思源笔记支持树形文档结构，文档可作为容器（目录） - 容器文档本身内容为空，但包含多个下级文档 - 删除容器文档会同时删除所有下级文档

文档属性

系统默认属性（自动维护，只读）

属性名 说明 示例值
id 文档/块ID 20260312142019-fr21e3o
title 文档标题 测试文档
type 类型 doc（文档）
updated 更新时间 20260312142019

常用自定义属性（建议使用）

属性名 说明 示例值
status 文档状态 draft, published, archived
priority 优先级 high, medium, low
tags 标签（用 tags 命令） 重要,待审核
author 作者 张三
version 版本 1.0.0

重要说明： - 默认情况下，属性会自动添加 custom- 前缀（在思源笔记界面可见） - 使用 --hide 标记可以设置隐藏属性（不带 custom- 前缀）

设置示例：

# 设置可见属性（自动添加 custom- 前缀）
siyuan attrs <docId> --set "status=draft,priority=high,author=张三"

# 设置隐藏属性（不带 custom- 前缀）
siyuan attrs <docId> --set "internal=true" --hide

# 获取属性（自动移除 custom- 前缀显示）
siyuan attrs <docId> --get

# 获取指定属性
siyuan attrs <docId> --get "status"

# 获取隐藏属性
siyuan attrs <docId> --get "internal" --hide

注意事项

  1. 权限模式：all / whitelist / blacklist
  2. 缓存：使用 --force-refresh 强制刷新
  3. 向量搜索：需部署 Qdrant + Ollama，否则回退 SQL 搜索

参考文档

  • 思源笔记 API 文档
  • 思源笔记用户指南
  • 命令详细文档
  • 高级功能文档
  • 配置文档

安全最佳实践

网络安全

🔒 重要：建议仅将 SIYUAN_BASE_URL 设置为本地实例

配置项 推荐值 说明
SIYUAN_BASE_URL http://127.0.0.1:6806 仅绑定本地地址
TLS 证书验证 默认启用 仅 localhost 允许自签名证书

权限控制

推荐使用 whitelist 模式限制可访问的笔记本：

# 设置权限模式
SIYUAN_PERMISSION_MODE=whitelist

# 设置白名单笔记本
SIYUAN_NOTEBOOK_LIST=notebook-id-1,notebook-id-2

可选功能

如果不需要向量搜索或外部嵌入服务，请勿配置以下环境变量： - QDRANT_URL - OLLAMA_BASE_URL - OLLAMA_EMBED_MODEL

程序化 API 说明

本 skill 导出了 createSkill 和 executeSingleCommand 函数供高级用户使用：

// 程序化使用示例
const { createSkill } = require('./index.js');
const skill = createSkill({ baseURL: 'http://127.0.0.1:6806', token: 'xxx' });

⚠️ 注意：程序化 API 仅供高级用户在受控环境中使用。普通 AI Agent 应仅使用 CLI 命令。

日志安全

  • 生产环境不要启用 DEBUG 环境变量
  • 敏感信息（token、password、apiKey）在日志中自动脱敏
  • 错误信息中不包含服务器地址等上下文信息