Siyuan Skill

> **安装：** 从 [ClawHub](https://clawhub.ai/dazexcl/siyuan-skill) 下载，详见 [安装配置指南](references/config/setup.md)
> 
> **环境变量：** 参考 [环境变量文档](references/config/environment.md)

---


# 快速开始

```bash
cd skills/siyuan-skill
node siyuan.js <command> [options]
node siyuan.js help <command>  # 查看命令帮助
node siyuan.js --version       # 显示版本信息
```

---

# 快速决策表

根据用户需求快速选择正确的命令：

## 笔记本与文档操作

| 用户需求 | 使用命令 | 关键参数 | 示例 |
|----------|----------|----------|------|
| 查看笔记本列表 | `notebooks` / `nb` | 无 | `siyuan nb` |
| 查看文档结构 | `structure` / `ls` | `--depth` | `siyuan ls <notebookId>` |
| 查看文档内容 | `content` / `cat` | 无 | `siyuan cat <docId>` |
| 获取文档信息 | `info` | 文档ID | `siyuan info <docId>` |
| 创建新文档 | `create` / `new` | `--parent-id` 或 `--path` | `siyuan create "标题" --parent-id xxx` |
| 修改整个文档 | `update` / `edit` | 文档ID | `siyuan update <docId> "完整内容"` |
| 删除文档 | `delete` / `rm` | 文档ID | `siyuan rm <docId>` |
| 移动文档 | `move` / `mv` | `--new-title`（可选） | `siyuan mv <docId> <targetId>` |
| 重命名文档 | `rename` | 新标题 | `siyuan rename <docId> "新标题"` |
| 保护/取消保护 | `protect` | `--on` / `--off` | `siyuan protect <docId> --on` |
| 检查文档存在 | `exists` / `check` | `--title` 或 `--path` | `siyuan exists --title "标题"` |
| 转换ID和路径 | `convert` / `path` | `--to-id` 或 `--to-path` | `siyuan path "/笔记本/文档" --to-id` |
| 设置文档图标 | `icon` / `set-icon` | `--emoji` / `--get` / `--remove` | `siyuan icon <docId> --emoji 1f4c4` |
| 设置文档属性 | `block-attrs` / `ba` | `--set` / `--get` / `--remove` | `siyuan ba <docId> --set "status=done"` |
| 设置标签 | `tags` / `st` | `--tags` | `siyuan st <docId> --tags "A,B"` |
| 搜索内容 | `search` / `find` | `--mode` / `--threshold` | `siyuan search "关键词" --mode semantic` |

## 块操作

| 用户需求 | 使用命令 | 关键参数 | 示例 |
|----------|----------|----------|------|
| 获取块信息 | `block-get` / `bg` | `--mode` | `siyuan bg <blockId> --mode kramdown` |
| 修改单个块 | `block-update` / `bu` | 块ID（非文档ID） | `siyuan bu <blockId> "块内容"` |
| 插入新块 | `block-insert` / `bi` | `--parent-id` / `--next-id` | `siyuan bi "内容" --parent-id xxx` |
| 删除单个块 | `block-delete` / `bd` | 块ID | `siyuan bd <blockId>` |
| 移动块 | `block-move` / `bm` | `--parent-id` / `--next-id` | `siyuan bm <blockId> --parent-id xxx` |
| 折叠/展开块 | `block-fold` / `bf` | `--fold` / `--unfold` | `siyuan bf <blockId> --fold` |
| 转移块引用 | `block-transfer-ref` / `btr` | 源块ID、目标块ID | `siyuan btr <srcId> <tgtId>` |

> **重要区分**：`update` 只接受文档ID，`block-update` 只接受块ID

---

## 块操作决策流程

**操作前必须执行**：
1. 先用 `bg <blockId> --mode kramdown` 查看块结构
2. 分析哪些块是多余的、哪些需要修改
3. 根据目标选择正确的命令

| 目标 | 命令 | 说明 |
|------|------|------|
| 删除不需要的块 | `bd <blockId>` | 整个块删除 |
| 修改块内容 | `bu <blockId> "新内容"` | 保留块 ID，更新内容 |
| 查看块结构 | `bg <blockId> --mode kramdown` | 查看 kramdown 格式 |
| 查看文档内容 | `content <docId>` | 查看完整文档 |

---

# 重名检测

以下命令在执行前会自动检测目标位置是否存在同名文档：

| 命令 | 检测时机 | 冲突处理 |
|------|----------|----------|
| `create` | 创建前 | 返回错误，使用 `--force` 强制创建 |
| `move` | 移动前 | 返回错误，使用 `--new-title` 指定新标题 |
| `rename` | 重命名前 | 返回错误，需更换新标题 |

**手动检查文档是否存在：**

```bash
siyuan exists --title "文档标题" [--parent-id <父文档ID>]
siyuan exists --path "/目录/文档标题"
```

---

# 删除保护

**默认禁止删除文档**。如需启用删除功能，**必须由用户手动**在 `config.json` 中配置。

> ⚠️ **Agent 禁止自动修改此配置**


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

> 💡 **提示**：如删除被阻止，应告知用户修改配置或使用 `protect` 命令移除文档保护标记

---

# 最佳实践

## 标准工作流

### 创建文档

```
1. 检查文档是否存在
   └─ siyuan exists --title "标题" [--parent-id <父ID>]
   
2a. 如不存在 → 直接创建
    └─ siyuan create "标题" "内容" --parent-id <id>
    
2b. 如存在 → 询问用户
    ├─ 覆盖？ → siyuan update <docId> "新内容"
    └─ 新建同名？ → siyuan create "标题" "内容" --force
```

### 修改文档

```
1. 获取当前内容
   └─ siyuan content <docId>
   
2. 判断修改范围
   ├─ 全文替换 → siyuan update <docId> "完整新内容"
   └─ 仅修改部分块 → 先 siyuan bg <docId> --mode kramdown
```

## create 命令

| 模式 | 场景 | 示例 |
|------|------|------|
| 传统模式 | 已知父ID | `siyuan create "标题" "内容" --parent-id <id>` |
| 路径指定 | 创建多级目录 | `siyuan create --path "笔记本/A/B/C" "内容"` |
| 目录下创建 | 批量创建 | `siyuan create --path "笔记本/目录/" "标题" "内容"` |

> 📋 详细用法见 [create 命令文档](references/commands/create.md)

## 内容修改

```bash
# ✅ 推荐
siyuan update <docId> "新内容"        # 全文更新：必须传入完整的文档内容
siyuan bu <blockId> "新内容"          # 块更新：只需传入需要修改的块内容

# ❌ 错误：混用命令
siyuan bu <docId> "内容"              # 错误：block-update 不接受文档ID
siyuan update <blockId> "内容"        # 错误：update 不接受块ID
```

## 属性设置

```bash
siyuan ba <docId> --set "status=published"
siyuan ba <docId> --get
siyuan ba <docId> --remove "status"
siyuan st <docId> --tags "重要,待审核"
```

## 图标设置

```bash
siyuan icon <docId> --emoji 📄       # 直接传入 emoji
siyuan icon <docId> --emoji 1f4c4    # 或使用编码
siyuan icon <docId> --get            # 获取图标
siyuan icon <docId> --remove         # 移除图标
```

> 📋 完整 emoji 编码表见 [图标命令文档](references/commands/icon.md)

## 文档格式

```bash
# ✅ 正确：使用 \n 换行
siyuan create "标题" "第一段\n\n## 二级标题\n内容"

# ❌ 错误：所有内容在一行
siyuan create "标题" "第一段## 二级标题 内容"
```

## 常见错误预防

| 错误场景 | 错误做法 | 正确做法 |
|----------|----------|----------|
| 文档已存在 | 直接 create | 先 `exists` 检查，再用 `--force` |
| 删除被阻止 | 反复尝试 | 告知用户修改配置或使用 `protect` |
| ID 类型混淆 | `update` 用块ID | `update` 只用文档ID，`bu` 只用块ID |
| 修改部分内容 | 删了重建 | 用 `bu` 或 `bd` 进行块级操作 |

## 书写规范

### 内部链接

```markdown
((docId '标题'))
```

### SQL 嵌入块

```markdown
{{ SELECT * FROM blocks WHERE type = 'd' ORDER BY updated DESC LIMIT 5 }}
```

> 📋 完整规范见 [书写指南](references/advanced/writing-guide.md) 和 [最佳实践](references/advanced/best-practices.md)

---

# 高级功能

## 向量搜索（可选）

需配置 `QDRANT_URL` + `OLLAMA_BASE_URL`。

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

```bash
siyuan index                        # 增量索引
siyuan search "关键词" --mode semantic
```

**相关度分数参考：**

| 分数范围 | 相关性 | 说明 |
|----------|--------|------|
| 0.9-1.0 | 极高 | 几乎相同内容 |
| 0.7-0.9 | 高度 | 语义非常接近 |
| 0.5-0.7 | 中等 | 语义有交集 |
| <0.5 | 弱 | 参考价值低 |

```bash
siyuan search "关键词" --mode semantic --threshold 0.7
```

> 📋 详细配置见 [向量搜索文档](references/advanced/vector-search.md)

## NLP 分析

```bash
siyuan nlp "文本" --tasks tokenize,keywords
```

> 📋 详细用法见 [NLP 文档](references/commands/nlp.md)

---

# 安全要点

- 仅使用本地实例 (`http://localhost:6806`)
- 推荐使用 `whitelist` 权限模式
- 删除功能默认禁用，需用户手动配置
- **配置只读保护**：CLI 命令集不暴露任何配置修改 API，敏感配置（token 等）仅通过环境变量注入，不会持久化到配置文件
- **Token 安全**：SIYUAN_TOKEN 仅从环境变量或 config.json 读取，技能本身绝不会修改或写入 token
- **可选功能**：QDRANT_URL、OLLAMA_BASE_URL 为可选配置，如不需要向量搜索/NLP 功能，无需配置这些变量

> 📋 详细安全配置见 [配置文档](references/config/advanced.md)

## 安全声明

### 配置只读保护

**重要**：本技能采用**配置只读**设计原则。

- 所有敏感配置（token、API 密钥等）**仅通过环境变量或 config.json 读取**
- 技能本身**不提供任何配置写入能力**
- 配置变更需要用户**手动修改**环境变量或配置文件

### Token 处理

- `SIYUAN_TOKEN` **仅从环境变量或 config.json 读取**
- 技能本身**绝不修改或写入 token**
- Token 变更需要用户手动操作

### 可选功能

- `QDRANT_URL`、`OLLAMA_BASE_URL` 为**可选配置**
- 如不需要向量搜索/NLP 功能，**无需配置**这些变量
- 不配置时，技能将使用基础的 SQL 搜索模式

---

# 参考文档

- [安装配置指南](references/config/setup.md)
- [环境变量配置](references/config/environment.md)
- [命令详细文档](references/commands/)
- [高级功能](references/advanced/)
- [书写指南（内容格式规范）](references/advanced/writing-guide.md)
- [最佳实践](references/advanced/best-practices.md)
- [使用指南（故障排除）](references/advanced/usage-guide.md)
- [思源笔记 API](https://github.com/siyuan-note/siyuan/blob/master/API_zh_CN.md)

---