思源笔记技能 📝

描述

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

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

激活条件

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

思源笔记
查询思源笔记
写入思源笔记
同步到思源笔记
从思源笔记读取
搜索思源笔记
思源笔记查询
思源笔记搜索

前置要求

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

🆕 增强功能（v2.0）

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

1. 真正的独立文档创建 ✨

使用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文档文件
✅ 在思源笔记文档列表中可见
✅ 支持完整的内容和格式

2. 文章剪藏功能 📰

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

client.clip_article(
    notebook_name="其他",
    title="文章标题",
    url="https://example.com/article",
    content="文章的Markdown内容",
    excerpt="文章摘要",
    site_name="网站名称",
    tags=["技术", "笔记"]
)

特性：

✅ 自动格式化和模板渲染
✅ 保留原始URL和元数据
✅ 支持自定义剪藏模板
✅ 自动处理网站名称和摘要

3. 强大的模板系统 🎨

基于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}

4. 增强的错误处理 🛡️

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

5. 改进的整体架构 🏗️

✅ 基于思源笔记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扩展兼容	❌ 不兼容	✅ 基于最佳实践
向后兼容	✅ 完全兼容	✅ 包含所有功能

1. 测试连接

from siyuan_note import SiYuanNote

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

2. 查询思源笔记

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

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

# 搜索特定内容
results = siyuan.search_content("关键词")

3. 写入思源笔记

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

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

4. 创建新笔记

# 创建新文档
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():
    # 从命令行参数获取对话数据
    if len(sys.argv) < 2:
        print("用法: python sync_now.py '对话JSON数据'")
        return
    
    try:
        conversation_data = json.loads(sys.argv[1])
    except:
        print("错误: 无效的JSON数据")
        return
    
    # 同步到思源笔记
    siyuan = SiYuanNote()
    success = siyuan.sync_conversation(conversation_data)
    
    if success:
        print("✅ 对话已同步到思源笔记")
    else:
        print("❌ 同步失败")

if __name__ == "__main__":
    main()

批量同步历史对话

#!/usr/bin/env python3
"""
批量同步历史对话到思源笔记
"""

import os
import json
from siyuan_note import SiYuanNote

def sync_history_conversations(history_dir="./conversations"):
    siyuan = SiYuanNote()
    
    if not os.path.exists(history_dir):
        print(f"目录不存在: {history_dir}")
        return
    
    # 遍历所有JSON文件
    for filename in os.listdir(history_dir):
        if filename.endswith('.json'):
            filepath = os.path.join(history_dir, filename)
            
            try:
                with open(filepath, 'r', encoding='utf-8') as f:
                    data = json.load(f)
                
                # 提取对话数据
                conversation_data = data.get('conversation', data)
                
                print(f"同步: {filename}")
                success = siyuan.sync_conversation(conversation_data)
                
                if success:
                    print(f"✅ {filename} 同步成功")
                else:
                    print(f"❌ {filename} 同步失败")
                    
            except Exception as e:
                print(f"❌ 处理 {filename} 时出错: {e}")

if __name__ == "__main__":
    sync_history_conversations()

故障排除

常见问题

连接失败
- 检查思源笔记是否正在运行
- 确认API地址和端口正确
- 验证token是否有效
权限问题
- 确保token有读写权限
- 检查笔记本是否存在
同步失败
- 检查网络连接
- 查看思源笔记日志
- 验证对话数据格式

调试模式

import logging
logging.basicConfig(level=logging.DEBUG)

siyuan = SiYuanNote()
siyuan.test_connection()

集成到OpenClaw

作为工具使用

将此技能集成到OpenClaw的tools中，可以通过以下方式调用：

# 在OpenClaw会话中
from skills.siyuan_note.siyuan_note import SiYuanNote

# 初始化
siyuan = SiYuanNote()

# 查询思源笔记
if user_request == "查询思源笔记":
    notebooks = siyuan.get_notebooks()
    response = f"找到 {len(notebooks)} 个笔记本"
    
# 写入思源笔记
elif user_request == "写入思源笔记":
    success = siyuan.sync_conversation(current_conversation)
    response = "已同步到思源笔记" if success else "同步失败"

自动同步功能

可以设置定时任务，自动将OpenClaw对话同步到思源笔记：

# 在heartbeat或cron任务中
def auto_sync_to_siyuan():
    siyuan = SiYuanNote()
    
    # 获取未同步的对话
    unsynced_conversations = get_unsynced_conversations()
    
    for conv in unsynced_conversations:
        siyuan.sync_conversation(conv)
        mark_as_synced(conv)

更新日志

v1.0.0 (初始版本)

基本的思源笔记API连接
对话同步功能
配置管理
错误处理

注意事项

API token是敏感信息，请妥善保管，永远不要提交到版本控制系统
建议定期备份思源笔记数据
大量同步时注意API频率限制
确保思源笔记版本兼容性