Siyuan Skill

核心价值

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

适用场景

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

不适用场景

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

环境变量要求

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

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

重要约束

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

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

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

问题导向文档导航

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

快速开始

# 方式 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>

命令列表

常用命令：

块控制命令：

删除保护

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

{
  "deleteProtection": {
    "safeMode": false,
    "requireConfirmation": true
  }
}

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

更新方式选择

注意：文档本身也是一种块，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: published\n---\n内容"

原因：

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

文档内容规范

文档格式说明

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

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

⚠️ 换行符使用说明

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

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

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

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

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

常见格式对应的换行符：

# 创建文档 - 使用 Markdown 格式
siyuan create "标题" "正文内容\n\n**粗体** *斜体*\n\n- 列表项1\n- 列表项2"

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

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

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. 无内容，无下级文档 → 空文档

原因：

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

文档属性

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

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

重要说明：

• 默认情况下，属性会自动添加 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 设置为本地实例

权限控制

推荐使用 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）在日志中自动脱敏
• 错误信息中不包含服务器地址等上下文信息