{"skill":{"slug":"siyuan-note-enhanced","displayName":"思源笔记增强版","summary":"思源笔记读写技能，提供与思源笔记（SiYuan Note）进行交互的能力，包括读取和写入笔记内容","description":"---\nname: siyuan-note\ndescription: 思源笔记读写技能，提供与思源笔记（SiYuan Note）进行交互的能力，包括读取和写入笔记内容\nmetadata:\n  {\n    \"openclaw\": {\n      \"emoji\": \"📝\",\n      \"requires\": { \"bins\": [\"python3\"] },\n      \"primaryEnv\": \"SIYUAN_API_TOKEN\"\n    }\n  }\n---\n\n# 思源笔记技能 📝\n\n## 描述\n这个技能提供了与思源笔记（SiYuan Note）进行交互的能力，包括读取和写入笔记内容。基于思源笔记Chrome扩展最佳实践优化，支持真正的独立文档创建、文章剪藏、模板渲染等高级功能。\n\n当用户提到\"查询思源笔记\"、\"写入思源笔记\"、\"创建思源笔记\"或类似请求时，使用此技能。\n\n## 激活条件\n当用户提到以下关键词时激活此技能：\n- 思源笔记\n- 查询思源笔记\n- 写入思源笔记\n- 同步到思源笔记\n- 从思源笔记读取\n- 搜索思源笔记\n- 思源笔记查询\n- 思源笔记搜索\n\n## 前置要求\n1. 思源笔记必须正在运行，并且API已启用\n2. 需要有效的API token\n3. Python环境需要安装requests库\n\n## 🆕 增强功能（v2.0）\n\n基于思源笔记Chrome扩展（[siyuan-note/siyuan-chrome](https://github.com/siyuan-note/siyuan-chrome)）的实践，增加了以下高级功能：\n\n### 1. 真正的独立文档创建 ✨\n使用`createDocWithMd` API创建真正的独立文档，不再依赖在现有文档中追加内容：\n\n```python\nfrom siyuan_note_enhanced import create_enhanced_client\n\nclient = create_enhanced_client()\ndoc_id = client.create_document(\n    \"其他\",\n    \"我的文档\",\n    \"# 标题\\n\\n文档内容\",\n    tags=[\"标签1\", \"标签2\"]\n)\n# 返回: 独立文档ID，如 \"20260217205120-3wcoxib\"\n# 文件: myDocument.sy\n```\n\n**优势**：\n- ✅ 创建独立的.sy文档文件\n- ✅ 在思源笔记文档列表中可见\n- ✅ 支持完整的内容和格式\n\n### 2. 文章剪藏功能 📰\n类似Chrome扩展的剪藏功能，支持完整的文章剪藏：\n\n```python\nclient.clip_article(\n    notebook_name=\"其他\",\n    title=\"文章标题\",\n    url=\"https://example.com/article\",\n    content=\"文章的Markdown内容\",\n    excerpt=\"文章摘要\",\n    site_name=\"网站名称\",\n    tags=[\"技术\", \"笔记\"]\n)\n```\n\n**特性**：\n- ✅ 自动格式化和模板渲染\n- ✅ 保留原始URL和元数据\n- ✅ 支持自定义剪藏模板\n- ✅ 自动处理网站名称和摘要\n\n### 3. 强大的模板系统 🎨\n基于Chrome扩展的模板渲染引擎：\n\n```python\n# 基本变量替换\ntemplate = \"标题: ${title}\\n时间: ${date}\"\ndata = {'title': '测试', 'date': '2026-02-17'}\nresult = client.render_template(template, data)\n# 结果: \"标题: 测试\\n时间: 2026-02-17\"\n\n# 条件表达式\ntemplate = \"${show ? '显示' : '隐藏'}\"\nresult = client.render_template(template, {'show': True})\n# 结果: \"显示\"\n\n# 嵌套属性\ntemplate = \"用户: ${user.name}\"\ndata = {'user': {'name': '张三'}}\nresult = client.render_template(template, data)\n# 结果: \"用户: 张三\"\n```\n\n**支持的功能**：\n- ✅ 变量替换：`${variable}`\n- ✅ 条件表达式：`${condition ? true : false}`\n- ✅ 嵌套属性访问：`${user.name}`\n- ✅ 字符串拼接：`${firstName + lastName}`\n\n### 4. 增强的错误处理 🛡️\n- ✅ API调用失败时自动回退到兼容方法\n- ✅ 详细的错误信息和调试输出\n- ✅ 智能验证和文档确认\n- ✅ 连接状态监控\n\n### 5. 改进的整体架构 🏗️\n- ✅ 基于思源笔记Chrome扩展的最佳实践\n- ✅ 更清晰的代码结构和分离关注点\n- ✅ 更好的可维护性和可扩展性\n- ✅ 完整的测试覆盖\n\n## 配置\n\n### 环境变量（推荐）\n配置通过环境变量读取：\n- `SIYUAN_API_URL` - 思源笔记API地址，例如：`http://localhost:6806`\n- `SIYUAN_API_TOKEN` - 你的API token（从思源笔记设置中获取）\n\n### 配置文件\n也可以使用配置文件，默认位置：`~/.openclaw/workspace/siyuan-openchat-sync/config.json`\n```json\n{\n  \"siyuan\": {\n    \"api_url\": \"http://localhost:6806\",\n    \"token\": \"your-api-token-here\"\n  },\n  \"sync\": {\n    \"notebook_name\": \"其他\",\n    \"document_name\": \"openchat\",\n    \"auto_sync\": true\n  }\n}\n```\n\n## 使用方法\n\n### 基础版（向后兼容）\n```python\nfrom siyuan_note import SiYuanNote\n\nsiyuan = SiYuanNote()\n```\n\n### 增强版（推荐）🚀\n```python\nfrom siyuan_note_enhanced import create_enhanced_client\n\nclient = create_enhanced_client()\n```\n\n### 版本对比\n\n| 功能 | 基础版 | 增强版 |\n|------|--------|--------|\n| 独立文档创建 | ❌ 在现有文档中追加 | ✅ 创建真正的.sy文件 |\n| 文章剪藏 | ❌ 不支持 | ✅ 完整的剪藏功能 |\n| 模板渲染 | ❌ 基础格式化 | ✅ 强大的模板系统 |\n| 错误处理 | ✅ 基础处理 | ✅ 增强的错误处理 |\n| Chrome扩展兼容 | ❌ 不兼容 | ✅ 基于最佳实践 |\n| 向后兼容 | ✅ 完全兼容 | ✅ 包含所有功能 |\n\n### 1. 测试连接\n```python\nfrom siyuan_note import SiYuanNote\n\nsiyuan = SiYuanNote()\nif siyuan.test_connection():\n    print(\"连接成功\")\nelse:\n    print(\"连接失败\")\n```\n\n### 2. 查询思源笔记\n```python\n# 获取所有笔记本\nnotebooks = siyuan.get_notebooks()\nprint(f\"找到 {len(notebooks)} 个笔记本\")\n\n# 获取指定笔记本的文档\nnotebook_id = siyuan.get_notebook_id(\"其他\")\ndocuments = siyuan.get_documents(notebook_id)\n\n# 搜索特定内容\nresults = siyuan.search_content(\"关键词\")\n```\n\n### 3. 写入思源笔记\n```python\n# 同步对话到思源笔记\nconversation_data = {\n    'summary': '对话摘要',\n    'messages': [\n        {'role': 'user', 'content': '用户消息'},\n        {'role': 'assistant', 'content': '助手回复'}\n    ],\n    'conclusion': '对话总结'\n}\n\nsuccess = siyuan.sync_conversation(conversation_data)\nif success:\n    print(\"同步成功\")\nelse:\n    print(\"同步失败\")\n```\n\n### 4. 创建新笔记\n```python\n# 创建新文档\nnew_doc_id = siyuan.create_document(\n    notebook_name=\"其他\",\n    document_name=\"新文档\",\n    content=\"# 新文档\\n\\n这是新创建的文档内容。\"\n)\n```\n\n## 核心类：SiYuanNote\n\n### 初始化\n```python\n# 从环境变量自动读取（推荐）\nfrom siyuan_note import SiYuanNote\nsiyuan = SiYuanNote()\n\n# 或手动指定\nsiyuan = SiYuanNote(\n    api_url=\"http://localhost:6806\",\n    token=\"your-api-token-here\"\n)\n```\n\n### 主要方法\n\n#### 连接相关\n- `test_connection()` - 测试API连接\n- `get_notebooks()` - 获取所有笔记本\n- `get_notebook_id(notebook_name)` - 获取笔记本ID\n\n#### 读取操作\n- `get_documents(notebook_id)` - 获取笔记本中的文档\n- `get_document_content(document_id)` - 获取文档内容\n- `search_content(query, notebook_name=None)` - 搜索内容\n\n#### 写入操作\n- `create_document(notebook_name, document_name, content)` - 创建新文档\n- `append_to_document(document_id, content)` - 向文档追加内容\n- `sync_conversation(conversation_data, notebook_name=\"其他\", document_name=\"openchat\")` - 同步对话\n\n#### 配置管理\n- `load_config()` - 加载配置\n- `save_config()` - 保存配置\n- `update_config(new_config)` - 更新配置\n\n## 对话数据格式\n```python\nconversation_data = {\n    'summary': '对话摘要',\n    'messages': [\n        {\n            'role': 'user',  # 或 'assistant'\n            'content': '消息内容',\n            'timestamp': '可选时间戳'\n        }\n    ],\n    'conclusion': '对话总结',\n    'metadata': {\n        'source': 'OpenChat',\n        'version': '1.0'\n    }\n}\n```\n\n## 示例脚本\n\n### 快速同步当前对话\n```python\n#!/usr/bin/env python3\n\"\"\"\n快速同步当前OpenChat对话到思源笔记\n\"\"\"\n\nimport sys\nimport json\nfrom siyuan_note import SiYuanNote\n\ndef main():\n    # 从命令行参数获取对话数据\n    if len(sys.argv) < 2:\n        print(\"用法: python sync_now.py '对话JSON数据'\")\n        return\n    \n    try:\n        conversation_data = json.loads(sys.argv[1])\n    except:\n        print(\"错误: 无效的JSON数据\")\n        return\n    \n    # 同步到思源笔记\n    siyuan = SiYuanNote()\n    success = siyuan.sync_conversation(conversation_data)\n    \n    if success:\n        print(\"✅ 对话已同步到思源笔记\")\n    else:\n        print(\"❌ 同步失败\")\n\nif __name__ == \"__main__\":\n    main()\n```\n\n### 批量同步历史对话\n```python\n#!/usr/bin/env python3\n\"\"\"\n批量同步历史对话到思源笔记\n\"\"\"\n\nimport os\nimport json\nfrom siyuan_note import SiYuanNote\n\ndef sync_history_conversations(history_dir=\"./conversations\"):\n    siyuan = SiYuanNote()\n    \n    if not os.path.exists(history_dir):\n        print(f\"目录不存在: {history_dir}\")\n        return\n    \n    # 遍历所有JSON文件\n    for filename in os.listdir(history_dir):\n        if filename.endswith('.json'):\n            filepath = os.path.join(history_dir, filename)\n            \n            try:\n                with open(filepath, 'r', encoding='utf-8') as f:\n                    data = json.load(f)\n                \n                # 提取对话数据\n                conversation_data = data.get('conversation', data)\n                \n                print(f\"同步: {filename}\")\n                success = siyuan.sync_conversation(conversation_data)\n                \n                if success:\n                    print(f\"✅ {filename} 同步成功\")\n                else:\n                    print(f\"❌ {filename} 同步失败\")\n                    \n            except Exception as e:\n                print(f\"❌ 处理 {filename} 时出错: {e}\")\n\nif __name__ == \"__main__\":\n    sync_history_conversations()\n```\n\n## 故障排除\n\n### 常见问题\n\n1. **连接失败**\n   - 检查思源笔记是否正在运行\n   - 确认API地址和端口正确\n   - 验证token是否有效\n\n2. **权限问题**\n   - 确保token有读写权限\n   - 检查笔记本是否存在\n\n3. **同步失败**\n   - 检查网络连接\n   - 查看思源笔记日志\n   - 验证对话数据格式\n\n### 调试模式\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\nsiyuan = SiYuanNote()\nsiyuan.test_connection()\n```\n\n## 集成到OpenClaw\n\n### 作为工具使用\n将此技能集成到OpenClaw的tools中，可以通过以下方式调用：\n\n```python\n# 在OpenClaw会话中\nfrom skills.siyuan_note.siyuan_note import SiYuanNote\n\n# 初始化\nsiyuan = SiYuanNote()\n\n# 查询思源笔记\nif user_request == \"查询思源笔记\":\n    notebooks = siyuan.get_notebooks()\n    response = f\"找到 {len(notebooks)} 个笔记本\"\n    \n# 写入思源笔记\nelif user_request == \"写入思源笔记\":\n    success = siyuan.sync_conversation(current_conversation)\n    response = \"已同步到思源笔记\" if success else \"同步失败\"\n```\n\n### 自动同步功能\n可以设置定时任务，自动将OpenClaw对话同步到思源笔记：\n\n```python\n# 在heartbeat或cron任务中\ndef auto_sync_to_siyuan():\n    siyuan = SiYuanNote()\n    \n    # 获取未同步的对话\n    unsynced_conversations = get_unsynced_conversations()\n    \n    for conv in unsynced_conversations:\n        siyuan.sync_conversation(conv)\n        mark_as_synced(conv)\n```\n\n## 更新日志\n\n### v1.0.0 (初始版本)\n- 基本的思源笔记API连接\n- 对话同步功能\n- 配置管理\n- 错误处理\n\n## 注意事项\n1. API token是敏感信息，请妥善保管，永远不要提交到版本控制系统\n2. 建议定期备份思源笔记数据\n3. 大量同步时注意API频率限制\n4. 确保思源笔记版本兼容性\n\n## 相关文件\n- `.env.example` - 环境变量配置示例\n- `README.md` - 完整文档\n- `CHANGELOG.md` - 更新日志","tags":{"latest":"2.0.0"},"stats":{"comments":0,"downloads":378,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1778078514576,"updatedAt":1779076219869},"latestVersion":{"version":"2.0.0","createdAt":1778078514576,"changelog":"清理隐私信息，支持环境变量配置，增加增强版功能：独立文档创建、文章剪藏、完整模板系统，基于思源笔记Chrome扩展最佳实践","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"jueduilunhui","userId":"s17csn8swwre4g8hh4tyn82c2x83jktg","displayName":"jueduilunhui","image":"https://avatars.githubusercontent.com/u/130271951?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780090754313}}