思源笔记增强版 — Siyuan Note 增强版

思源笔记技能 📝 描述 这个技能提供了与思源笔记（SiYuan Note）进行交互的能力，包括读取和写入笔记内容。基于思源笔记Chrome扩展最佳实践优化，支持真正的独立文档创建、文章剪藏、模板渲染等高级功能。 当用户提到"查询思源笔记"、"写入思源笔记"、"创建思源笔记"或类似请求时，使用此技能。

激活条件 当用户提到以下关键词时激活此技能： 思源笔记 查询思源笔记 写入思源笔记 同步到思源笔记 从思源笔记读取 搜索思源笔记 思源笔记查询 思源笔记搜索

前置要求 思源笔记必须正在运行，并且API已启用 需要有效的API token Python环境需要安装requests库

🆕 增强功能（v2.0） 基于思源笔记Chrome扩展（siyuan-note/siyuan-chrome）的实践，增加了以下高级功能：

• 真正的独立文档创建 ✨

使用createDocWithMd API创建真正的独立文档，不再依赖在现有文档中追加内容： from siyuan_note_enhanced import create_enhanced_client client = create_enhanced_client() doc_id = client.create_document( "其他", "我的文档", "# 标题\n\n文档内容", tags=["标签1", "标签2"] ) # 返回: 独立文档ID，如 "20260217205120-3wcoxib" # 文件: myDocument.sy 优势： ✅ 创建独立的.sy文档文件 ✅ 在思源笔记文档列表中可见 ✅ 支持完整的内容和格式

• 文章剪藏功能 📰

类似Chrome扩展的剪藏功能，支持完整的文章剪藏： client.clip_article( notebook_name="其他", title="文章标题", url="https://example.com/article", content="文章的Markdown内容", excerpt="文章摘要", site_name="网站名称", tags=["技术", "笔记"] ) 特性： ✅ 自动格式化和模板渲染 ✅ 保留原始URL和元数据 ✅ 支持自定义剪藏模板 ✅ 自动处理网站名称和摘要

• 强大的模板系统 🎨

基于Chrome扩展的模板渲染引擎： # 基本变量替换 template = "标题: ${title}\n时间: ${date}" data = {'title': '测试', 'date': '2026-02-17'} result = client.render_template(template, data) # 结果: "标题: 测试\n时间: 2026-02-17" # 条件表达式 template = "${show ? '显示' : '隐藏'}" result = client.render_template(template, {'show': True}) # 结果: "显示" # 嵌套属性 template = "用户: ${user.name}" data = {'user': {'name': '张三'}} result = client.render_template(template, data) # 结果: "用户: 张三" 支持的功能： ✅ 变量替换：${variable} ✅ 条件表达式：${condition ? true : false} ✅ 嵌套属性访问：${user.name} ✅ 字符串拼接：${firstName + lastName}

• 增强的错误处理 🛡️

✅ API调用失败时自动回退到兼容方法 ✅ 详细的错误信息和调试输出 ✅ 智能验证和文档确认 ✅ 连接状态监控

• 改进的整体架构 🏗️

✅ 基于思源笔记Chrome扩展的最佳实践 ✅ 更清晰的代码结构和分离关注点 ✅ 更好的可维护性和可扩展性 ✅ 完整的测试覆盖

配置 环境变量（推荐） 配置通过环境变量读取： SIYUAN_API_URL - 思源笔记API地址，例如：http://localhost:6806 SIYUAN_API_TOKEN - 你的API token（从思源笔记设置中获取）

配置文件 也可以使用配置文件，默认位置：~/.openclaw/workspace/siyuan-openchat-sync/config.json { "siyuan": { "api_url": "http://localhost:6806", "token": "your-api-token-here" }, "sync": { "notebook_name": "其他", "document_name": "openchat", "auto_sync": true } }

使用方法 基础版（向后兼容） from siyuan_note import SiYuanNote siyuan = SiYuanNote()

增强版（推荐）🚀 from siyuan_note_enhanced import create_enhanced_client client = create_enhanced_client()

版本对比 功能 基础版 增强版 独立文档创建 ❌ 在现有文档中追加 ✅ 创建真正的.sy文件 文章剪藏 ❌ 不支持 ✅ 完整的剪藏功能 模板渲染 ❌ 基础格式化 ✅ 强大的模板系统 错误处理 ✅ 基础处理 ✅ 增强的错误处理 Chrome扩展兼容 ❌ 不兼容 ✅ 基于最佳实践 向后兼容 ✅ 完全兼容 ✅ 包含所有功能

• 测试连接

from siyuan_note import SiYuanNote siyuan = SiYuanNote() if siyuan.test_connection(): print("连接成功") else: print("连接失败")

• 查询思源笔记

# 获取所有笔记本 notebooks = siyuan.get_notebooks() print(f"找到 {len(notebooks)} 个笔记本") # 获取指定笔记本的文档 notebook_id = siyuan.get_notebook_id("其他") documents = siyuan.get_documents(notebook_id) # 搜索特定内容 results = siyuan.search_content("关键词")

• 写入思源笔记

# 同步对话到思源笔记 conversation_data = { 'summary': '对话摘要', 'messages': [ {'role': 'user', 'content': '用户消息'}, {'role': 'assistant', 'content': '助手回复'} ], 'conclusion': '对话总结' } success = siyuan.sync_conversation(conversation_data) if success: print("同步成功") else: print("同步失败")

• 创建新笔记

# 创建新文档 new_doc_id = siyuan.create_document( notebook_name="其他", document_name="新文档", content="# 新文档\n\n这是新创建的文档内容。" )

核心类：SiYuanNote 初始化 # 从环境变量自动读取（推荐） from siyuan_note import SiYuanNote siyuan = SiYuanNote() # 或手动指定 siyuan = SiYuanNote( api_url="http://localhost:6806", token="your-api-token-here" )

主要方法 连接相关 test_connection() - 测试API连接 get_notebooks() - 获取所有笔记本 get_notebook_id(notebook_name) - 获取笔记本ID 读取操作 get_documents(notebook_id) - 获取笔记本中的文档 get_document_content(document_id) - 获取文档内容 search_content(query, notebook_name=None) - 搜索内容 写入操作 create_document(notebook_name, document_name, content) - 创建新文档 append_to_document(document_id, content) - 向文档追加内容 sync_conversation(conversation_data, notebook_name="其他", document_name="openchat") - 同步对话 配置管理 load_config() - 加载配置 save_config() - 保存配置 update_config(new_config) - 更新配置

对话数据格式 conversation_data = { 'summary': '对话摘要', 'messages': [ { 'role': 'user', # 或 'assistant' 'content': '消息内容', 'timestamp': '可选时间戳' } ], 'conclusion': '对话总结', 'metadata': { 'source': 'OpenChat', 'version': '1.0' } }

示例脚本 快速同步当前对话 #!/usr/bin/env python3 """ 快速同步当前OpenChat对话到思源笔记 """ import sys import json from siyuan_note import SiYuanNote def main(): # 从命令行参数获取对话数据