📦 思源笔记增强版

思源笔记技能 📝 描述

这个技能提供了与思源笔记（SiYuan Note）进行交互的能力，包括读取和写入笔记内容。基于思源笔记Chrome扩展最佳实践优化，支持真正的独立文档创建、文章剪藏、模板渲染等高级功能。

当用户提到"查询思源笔记"、"写入思源笔记"、"创建思源笔记"或类似请求时，使用此技能。

激活条件

当用户提到以下关键词时激活此技能：

思源笔记 查询思源笔记 写入思源笔记 同步到思源笔记 从思源笔记读取 搜索思源笔记 思源笔记查询 思源笔记搜索 前置要求 思源笔记必须正在运行，并且API已启用 需要有效的API 令牌 Python环境需要安装请求s库 🆕 增强功能（v2.0）

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

• 真正的独立文档创建 ✨

使用创建DocWithMd API创建真正的独立文档，不再依赖在现有文档中追加内容：

from siyuan_note_enhanced 导入 创建_enhanced_命令行工具ent

命令行工具ent = 创建_enhanced_命令行工具ent() doc_id = 命令行工具ent.创建_document( "其他", "我的文档", "# 标题\n\n文档内容", tags=["标签1", "标签2"] ) # 返回: 独立文档ID，如 "20260217205120-3wcoxib" # 文件: myDocument.sy

优势：

✅ 创建独立的.sy文档文件 ✅ 在思源笔记文档列表中可见 ✅ 支持完整的内容和格式

• 文章剪藏功能 📰

类似Chrome扩展的剪藏功能，支持完整的文章剪藏：

命令行工具ent.命令行工具p_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'} 结果 = 命令行工具ent.render_template(template, data) # 结果: "标题: 测试\n时间: 2026-02-17"

# 条件表达式 template = "${show ? '显示' : '隐藏'}" 结果 = 命令行工具ent.render_template(template, {'show': True}) # 结果: "显示"

# 嵌套属性 template = "用户: ${user.name}" data = {'user': {'name': '张三'}} 结果 = 命令行工具ent.render_template(template, data) # 结果: "用户: 张三"

支持的功能：

✅ 变量替换：${variable} ✅ 条件表达式：${condition ? true : false} ✅ 嵌套属性访问：${user.name} ✅ 字符串拼接：${firstName + lastName}

• 增强的错误处理 🛡️

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

• 改进的整体架构 🏗️

✅ 基于思源笔记Chrome扩展的最佳实践 ✅ 更清晰的代码结构和分离关注点 ✅ 更好的可维护性和可扩展性 ✅ 完整的测试覆盖 配置 环境变量（推荐）

配置通过环境变量读取：

SIYUAN_API_URL - 思源笔记API地址，例如：http://localhost:6806 SIYUAN_API_令牌 - 你的API 令牌（从思源笔记设置中获取） 配置文件

也可以使用配置文件，默认位置：~/.OpenClaw/workspace/siyuan-openchat-同步/config.json

{ "siyuan": { "API_url": "http://localhost:6806", "令牌": "your-API-令牌-here" }, "同步": { "notebook_name": "其他", "document_name": "openchat", "auto_同步": true } }

使用方法 基础版（向后兼容） from siyuan_note 导入 SiYuanNote

siyuan = SiYuanNote()

增强版（推荐）🚀 from siyuan_note_enhanced 导入 创建_enhanced_命令行工具ent

命令行工具ent = 创建_enhanced_命令行工具ent()

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

• 测试连接

from siyuan_note 导入 SiYuanNote

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

• 查询思源笔记

# 获取所有笔记本 notebooks = siyuan.获取_notebooks() print(f"找到 {len(notebooks)} 个笔记本")

# 获取指定笔记本的文档 notebook_id = siyuan.获取_notebook_id("其他") documents = siyuan.获取_documents(notebook_id)

# 搜索特定内容 结果s = siyuan.搜索_content("关键词")

• 写入思源笔记

# 同步对话到思源笔记 conversation_data = { 'summary': '对话摘要', 'messages': [ {'角色': 'user', 'content': '用户消息'}, {'角色': '助手', 'content': '助手回复'} ], 'conclusion': '对话总结' }

成功 = siyuan.同步_conversation(conversation_data) if 成功: print("同步成功") else: print("同步失败")

• 创建新笔记

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

核心类：SiYuanNote 初始化 # 从环境变量自动读取（推荐） from siyuan_note 导入 SiYuanNote siyuan = SiYuanNote()

# 或手动指定 siyuan = SiYuanNote( API_url="http://localhost:6806", 令牌="your-API-令牌-here" )

主要方法 连接相关 test_connection() - 测试API连接 获取_notebooks() - 获取所有笔记本 获取_notebook_id(notebook_name) - 获取笔记本ID 读取操作 获取_documents(notebook_id) - 获取笔记本中的文档 获取_document_content(document_id) - 获取文档内容 搜索_content(查询, notebook_name=None) - 搜索内容 写入操作 创建_document(notebook_name, document_name, content) - 创建新文档 应用end_to_document(document_id, content) - 向文档追加内容 同步_conversation(conversation_data, notebook_name="其他", document_name="openchat") - 同步对话 配置管理 load_config() - 加载配置 save_config() - 保存配置 更新_config(new_config) - 更新配置 对话数据格式 conversation_data = { 'summary': '对话摘要', 'messages': [ { '角色': 'user', # 或 '助手' 'content': '消息内容', 'timestamp': '可选时间戳' } ], 'conclusion': '对话总结', 'metadata': { 'source': 'OpenChat', 'version': '1.0' } }

示例脚本 快速同步当前对话 #!/usr/bin/env python3 """ 快速同步当前OpenChat对话到思源笔记 """

导入 sys 导入 json from siyuan_note 导入 SiYuanNote

def mAIn(): # 从命令行参数获取对话数据 if len(sys.argv) < 2: print("用法: python 同步_now.py '对话JSON数据'") return try: conversation_data = json.loads(sys.argv[1]) except: print("错误: 无效的JSON数据") return # 同步到思源笔记 siyuan = SiYuanNote() 成功 = siyuan.同步_conversation(conversation_data) if 成功: print("✅ 对话已同步到思源笔记") else: print("❌ 同步失败")

if __name__ == "__mAIn__": mAIn()

批量同步历史对话 #!/usr/bin/env pyt