Sync Obsidian to Lexiang

Sync Obsidian to Lexiang

将 Obsidian vault 单向同步到腾讯乐享，支持全量、增量、中断恢复和冲突保护。

能力边界

本 Skill 负责：

• 扫描 vault 和目录树
• content hash 增量判断
• manifest、文件锁和中断恢复
• 冲突策略和目的端移动检测
• 独立附件上传
• 把 Obsidian wikilink 转为临时标准 Markdown 包

upload-markdown-to-lexiang 负责：

• Markdown page 创建和覆盖
• 本地内嵌图片
• 公式、表格和图文顺序
• 上传前预检和上传后对账
• 乐享个人凭证

禁止在本 Skill 的 lexiang_api.py 中恢复 Markdown page 上传实现。

依赖定位

不得写死 WorkBuddy、OpenClaw 或其他 Agent 路径。按以下顺序定位公共 Skill：

1. LEXIANG_UPLOADER_HOME
2. 本 Skill 所在 skills 根目录的同级 upload-markdown-to-lexiang
3. 当前 Agent 暴露的已安装 Skill
4. 当前平台 Skill 管理器默认位置

缺失时安装到本 Skill 所在的同一个 skills 根目录。

python3 "/scripts/lexiang_upload.py" --version
# cli_api == "1"
python3 "/scripts/lexiang_upload.py" auth status --check

首次凭证配置：

python3 "/scripts/lexiang_upload.py" auth login

个人凭证从 获取。

默认情况下，目录、探活和独立附件仍复用 Agent 乐享连接器。显式选择 --lexiang-profile 或 --lexiang-credential-file 后，Markdown、目录、 探活和独立附件统一使用该 ai/claw 个人凭证。Markdown 内容不会进入对话上下文。

标准使用

首次建议 dry-run：

python3 scripts/sync.py \
  --mode full \
  --target-space-id  \
  --target-folder-id  \
  --vault-path "" \
  --dry-run

正式同步：

python3 scripts/sync.py \
  --mode incremental \
  --target-space-id  \
  --target-folder-id  \
  --vault-path ""

大批量后台执行：

python3 scripts/sync.py ... --lexiang-profile obsidian-sync --background
python3 scripts/sync.py --status --vault-path ""

命名 profile 位于 ~/.config/lexiang-upload/profiles/.json； default 对应 ~/.config/lexiang-upload/credentials.json。也可直接传 --lexiang-credential-file ，两者不能同时使用。命令行选择会写入 vault 的 config（只保存 profile 名或路径，不保存 token），后续定时任务可复用。 若 config 未设置，则考虑 LEXIANG_UPLOAD_CREDENTIALS / LEXIANG_UPLOAD_PROFILE；都未设置时保持原连接器默认行为。

stdout 只输出 JSON 摘要和报告路径；进度写 stderr 或 progress.json。

参数

同步规则

Markdown

1. 将 wikilink 和 Obsidian 图片引用转换为标准 Markdown。
2. 本地图片复制到一次性临时工作包。
3. 创建时调用公共 CLI 的 --parent-id。
4. 更新时调用公共 CLI 的 --entry-id。
5. 只有 verified=true 后才写入 manifest。

临时工作包在单篇完成后自动删除，不是第二份上传源码。

独立文件

PDF、Office、独立图片、音视频等作为 file entry 上传。它们不调用公共 Markdown 上传器。

增量和中断恢复

• 每项成功后立即保存 manifest。
• 内容 hash 未变化则跳过。
• entry 探活失败时保留映射，下次重试。
• manifest 丢失时先查询同名同类型 entry，避免重复创建。
• 两个进程同时同步时由 .sync.lock 阻止并发。

冲突

• lexiang_wins：乐享在上次同步后被独立编辑则跳过覆盖。
• obsidian_wins：Obsidian 变更始终覆盖。
• respect_move=true：目的端移动后继续更新原 entry。

状态文件

{vault}/.obsidian/plugins/sync-obsidian-to-lexiang/
├── config.json
├── manifest.json
├── .sync.lock
├── progress.json
└── reports/

代码边界

测试

python3 scripts/test_sync.py

默认测试必须离线，不得在真实知识库创建目录或文档。

公共上传行为有问题时，只修改 upload-markdown-to-lexiang 并补它的测试； 本 Skill 只测试临时工作包、CLI 调用、manifest 和同步调度。