思源笔记技能 📝#

描述#

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

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

激活条件#

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

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

前置要求#

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

🆕 增强功能（v2.0）#

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

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

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

python

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扩展的剪藏功能，支持完整的文章剪藏：

python

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

特性：

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

3. 强大的模板系统 🎨#

基于Chrome扩展的模板渲染引擎：

python

# 基本变量替换
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

json

{
  "siyuan": {
    "api_url": "http://localhost:6806",
    "token": "your-api-token-here"
  },
  "sync": {
    "notebook_name": "其他",
    "document_name": "openchat",
    "auto_sync": true
  }
}

使用方法#

基础版（向后兼容）#

python

from siyuan_note import SiYuanNote

siyuan = SiYuanNote()

增强版（推荐）🚀#

python

from siyuan_note_enhanced import create_enhanced_client

client = create_enhanced_client()

版本对比#

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

1. 测试连接#

python

from siyuan_note import SiYuanNote

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

2. 查询思源笔记#

python

# 获取所有笔记本
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. 写入思源笔记#

python

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

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

4. 创建新笔记#

python

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

核心类：SiYuanNote#

初始化#

python

# 从环境变量自动读取（推荐）
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) - 更新配置

对话数据格式#

python

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

示例脚本#

快速同步当前对话#

python

#!/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()

批量同步历史对话#

python

#!/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()

故障排除#

常见问题#

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

调试模式#

python

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

siyuan = SiYuanNote()
siyuan.test_connection()

集成到OpenClaw#

作为工具使用#

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

python

# 在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对话同步到思源笔记：

python

# 在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连接
• 对话同步功能
• 配置管理
• 错误处理

注意事项#

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

相关文件#

• .env.example - 环境变量配置示例
• README.md - 完整文档
• CHANGELOG.md - 更新日志