核心价值

---

name: "siyuan-skill"

version: "1.6.3"

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

skillType: "cli"

runtime: "node"

runtimeVersion: ">=14.0.0"

installType: "executable"

required_env_vars:

- name: "SIYUAN_BASE_URL"

description: "思源笔记 API 地址"

required: true

example: "http://127.0.0.1:6806"

- name: "SIYUAN_TOKEN"

description: "API 认证令牌"

required: true

example: "your-api-token"

- name: "SIYUAN_DEFAULT_NOTEBOOK"

description: "默认笔记本 ID"

required: true

example: "20260227231831-yq1lxq2"

- name: "SIYUAN_PERMISSION_MODE"

description: "权限模式 (all/whitelist/blacklist)"

required: false

default: "all"

- name: "SIYUAN_NOTEBOOK_LIST"

description: "白名单/黑名单笔记本 ID 列表"

required: false

- name: "QDRANT_URL"

description: "Qdrant 向量数据库地址（语义搜索需要）"

required: false

- name: "OLLAMA_BASE_URL"

description: "Ollama 服务地址（语义搜索需要）"

required: false

- name: "OLLAMA_EMBED_MODEL"

description: "Embedding 模型名称"

required: false

default: "nomic-embed-text"

- name: "SIYUAN_TLS_ALLOW_SELF_SIGNED"

description: "是否允许自签名证书（生产环境建议 false）"

required: false

default: "false"

- name: "SIYUAN_TLS_ALLOWED_HOSTS"

description: "允许自签名证书的主机列表（逗号分隔）"

required: false

default: "localhost,127.0.0.1,::1"

---

# 核心价值

**提供 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/notebooks.md) | 笔记本列表命令 |

| 如何获取文档结构 | [doc/commands/structure.md](doc/commands/structure.md) | 文档结构命令 |

| 如何获取文档内容 | [doc/commands/content.md](doc/commands/content.md) | 文档内容命令 |

| 如何创建文档 | [doc/commands/create.md](doc/commands/create.md) | 创建命令详解 |

| 如何更新文档 | [doc/commands/update.md](doc/commands/update.md) | 更新命令详解 |

| 如何删除文档 | [doc/commands/delete.md](doc/commands/delete.md) | 删除命令详解 |

| 删除被阻止 | [doc/advanced/delete-protection.md](doc/advanced/delete-protection.md) | 删除保护机制 |

| 如何保护文档 | [doc/commands/protect.md](doc/commands/protect.md) | 文档保护命令 |

| 如何移动文档 | [doc/commands/move.md](doc/commands/move.md) | 移动文档命令 |

| 如何重命名文档 | [doc/commands/rename.md](doc/commands/rename.md) | 重命名文档命令 |

| 如何搜索内容 | [doc/commands/search.md](doc/commands/search.md) | 搜索命令详解 |

| 搜索结果不准确 | [doc/advanced/vector-search.md](doc/advanced/vector-search.md) | 向量搜索配置 |

| 如何设置标签 | [doc/commands/tags.md](doc/commands/tags.md) | 标签命令详解 |

| 块操作问题 | [doc/commands/block-control.md](doc/commands/block-control.md) | 块控制命令详解 |

| 如何转换ID和路径 | [doc/commands/convert.md](doc/commands/convert.md) | ID/路径转换命令 |

| 如何索引文档 | [doc/commands/index.md](doc/commands/index.md) | 索引命令详解 |

| 如何使用NLP分析 | [doc/commands/nlp.md](doc/commands/nlp.md) | NLP分析命令 |

| 配置环境变量 | [doc/config/environment.md](doc/config/environment.md) | 环境变量配置 |

| 高级配置 | [doc/config/advanced.md](doc/config/advanced.md) | 详细配置选项 |

| 使用最佳实践 | [doc/advanced/best-practices.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: published\n---\n内容"

**原因**：

文档内容规范

文档格式说明

**写入格式**：创建/更新文档使用 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小节内容。"

**常见格式对应的换行符**：

| 格式 | 换行符 | 示例 |

|------|--------|------|

| 段落分隔 | `\n\n` | `段落1\n\n段落2` |

| 二级标题 | `\n\n## ` | `内容\n\n## 标题\n内容` |

| 三级标题 | `\n\n### ` | `内容\n\n### 标题\n内容` |

| 列表项 | `\n- ` | `列表项1\n- 列表项2` |

# 创建文档 - 使用 Markdown 格式
siyuan create "标题" "正文内容\n\n**粗体** *斜体*\n\n- 列表项1\n- 列表项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"}

特点：

**在 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正文内容"

**原因**：

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

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

# 获取文档结构
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- 前缀）
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 搜索

---

# 参考文档

---

# 安全最佳实践

网络安全

> 🔒 **重要**：建议仅将 `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

可选功能

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

程序化 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 命令。

日志安全