运行要求： Node.js >= 14.0.0，思源笔记 >= 3.6.0

安装： 从 ClawHub 下载，详见 安装配置指南

环境变量： 参考 环境变量文档

快速开始

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

快速决策表

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

笔记本与文档操作

块操作

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

块操作决策流程

操作前必须执行：

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

重名检测

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

手动检查文档是否存在：

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 命令

📋 详细用法见 create 命令文档

内容修改

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

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

属性设置

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

图标设置

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

📋 完整 emoji 编码表见 图标命令文档

文档格式

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

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

常见错误预防

书写规范

内部链接

((docId '标题'))

SQL 嵌入块

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

📋 完整规范见 书写指南 和 最佳实践

高级功能

向量搜索（可选）

需配置 QDRANT_URL + OLLAMA_BASE_URL。

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

相关度分数参考：

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

📋 详细配置见 向量搜索文档

NLP 分析

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

📋 详细用法见 NLP 文档

安全要点

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

📋 详细安全配置见 配置文档

安全声明

配置只读保护

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

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

Token 处理

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

可选功能

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

参考文档

• 安装配置指南
• 环境变量配置
• 命令详细文档
• 高级功能
• 书写指南（内容格式规范）
• 最佳实践
• 使用指南（故障排除）
• 思源笔记 API