Git 同步
已弃用
Git Sync 已在当前版本中弃用，不再对外开放。插件已切换为 WebDAV Durable Bundle Sync 方案，通过 WebDAV 协议交换 Synthesis 持久化状态快照（而非 Git 仓库），实现更轻量的跨设备同步。
请使用 WebDAV 同步 替代。
Git Sync 仅作为隐式内部传输通道保留（用于历史诊断和后续清理）。以下文档保留供历史参考。
Git 同步是 Synthesis Workbench 的可选功能，将 Canonical Store 中的知识图谱数据同步到 Git 仓库，实现版本管理、备份和协作。
用途
- 版本管理：追踪所有标签词表、主题综合、概念知识库的变更历史
- 备份：将结构化知识数据备份到远程 Git 仓库
- 协作：多个研究人员共享同一套标签体系和分析结果
配置方式
在 Zotero 偏好设置中配置 Git 同步：
Zotero → 设置 → Zotero Agents → Synthesis Git Sync
| 设置项 | 说明 |
|---|---|
| 启用 Git 同步 | 开启/关闭同步功能 |
| 远程仓库 URL | Git 远程仓库地址（支持 HTTPS 和 SSH） |
| 分支名 | 同步使用的 Git 分支 |
前置条件
- 已安装 Git（在系统 PATH 中可用）
- 有可访问的 Git 远程仓库（GitHub、Gitee、自托管等）
- 如果使用 HTTPS 仓库，需要配置 Git 凭据
同步范围
Git 同步只同步 规范域资产（Canonical Store 中的结构化知识数据），不包含运行时数据。
同步的内容
| 域 | 内容 |
|---|---|
tags/ | 受控标签词表（vocabulary） |
topics/ | 主题综合的结构化产物 |
concepts/ | 概念知识库（概念、义项、别名、关系） |
topic-graph/ | 主题图谱的节点和边 |
citation-graph/ | 引文图谱的快照 |
不同步的内容
| 不同步 | 原因 |
|---|---|
state/ 数据库 | SQLite 运行时状态，可从规范资产重建 |
| 运行时日志 | 临时诊断数据 |
| 工作区文件 | 执行过程中的临时数据 |
| 队列和锁状态 | 内部调度状态 |
同步状态机
同步系统使用队列驱动的状态机确保一致性：
idle → queued → syncing → idle
↓
blocked_conflict
↓
failed_retryable / failed_permanent / disabled
| 状态 | 说明 |
|---|---|
idle | 空闲，无待处理任务 |
queued | 有变更待同步 |
syncing | 正在执行同步操作 |
blocked_conflict | 同步失败，存在需要手动解决的冲突 |
failed_retryable | 临时失败（如网络问题），可重试 |
failed_permanent | 永久失败（如配置错误） |
disabled | Git 同步已关闭 |
冲突处理
当本地和远程同时有未合并的变更时，会产生冲突。
冲突报告
冲突报告中会列出：
- 冲突的文件路径
- 本地版本哈希
- 远程版本哈希
- 冲突原因（如：双方同时修改了同一个标签）
解决方式
- 在 Home 页面的 Git 同步面板中查看冲突报告
- 分析冲突内容（文件级粒度）
- 决定保留本地版本、远程版本，或手动编辑合并
- 完成合并后，提交变更
最佳实践
定期同步
Git 同步不是实时同步。建议：
- 在完成一批标签管理或主题修改后手动触发起同步
- 或在 Home 页面观察同步状态，确保队列不会积压
团队协作
多人共享同一标签词表时：
- 建议指定专人负责词表管理
- 标签变更通过 Git 同步传播后，其他成员执行同步拉取
- 冲突时以协商方式解决
备份策略
- Git 同步是对 Canonical Store 的补充备份，不替代 Zotero 数据本身的备份
- 建议定期将 Git 仓库推送到远程（已内置支持）
- 首次同步可能时间较长，后续为增量同步