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：
LEXIANG_UPLOADER_HOME- 本 Skill 所在 skills 根目录的同级
upload-markdown-to-lexiang - 当前 Agent 暴露的已安装 Skill
- 当前平台 Skill 管理器默认位置
缺失时安装到本 Skill 所在的同一个 skills 根目录。
python3 "<uploader-root>/scripts/lexiang_upload.py" --version
# cli_api == "1"
python3 "<uploader-root>/scripts/lexiang_upload.py" auth status --check
首次凭证配置：
python3 "<uploader-root>/scripts/lexiang_upload.py" auth login
个人凭证从 <https://lexiangla.com/ai/claw> 获取。
默认情况下，目录、探活和独立附件仍复用 Agent 乐享连接器。显式选择
--lexiang-profile 或 --lexiang-credential-file 后，Markdown、目录、
探活和独立附件统一使用该 ai/claw 个人凭证。Markdown 内容不会进入对话上下文。
标准使用
首次建议 dry-run：
python3 scripts/sync.py \
--mode full \
--target-space-id <SPACE_ID> \
--target-folder-id <FOLDER_ID> \
--vault-path "<VAULT>" \
--dry-run
正式同步：
python3 scripts/sync.py \
--mode incremental \
--target-space-id <SPACE_ID> \
--target-folder-id <FOLDER_ID> \
--vault-path "<VAULT>"
大批量后台执行：
python3 scripts/sync.py ... --lexiang-profile obsidian-sync --background
python3 scripts/sync.py --status --vault-path "<VAULT>"
命名 profile 位于 ~/.config/lexiang-upload/profiles/<name>.json；
default 对应 ~/.config/lexiang-upload/credentials.json。也可直接传
--lexiang-credential-file <PATH>，两者不能同时使用。命令行选择会写入
vault 的 config（只保存 profile 名或路径，不保存 token），后续定时任务可复用。
若 config 未设置，则考虑 LEXIANG_UPLOAD_CREDENTIALS /
LEXIANG_UPLOAD_PROFILE；都未设置时保持原连接器默认行为。
stdout 只输出 JSON 摘要和报告路径；进度写 stderr 或 progress.json。
参数
| 参数 | 说明 | 默认 |
|---|---|---|
--mode |
full / incremental |
首次 full，之后 incremental |
--target-space-id |
目标知识库 | 必填 |
--target-folder-id |
目标目录 | 知识库根目录 |
--vault-path |
Obsidian vault | 自动检测 |
--source-dirs |
指定同步目录 | 全部 |
--conflict-strategy |
lexiang_wins / obsidian_wins |
lexiang_wins |
--respect-move |
尊重乐享侧移动 | true |
--lexiang-profile |
命名个人凭证 profile | config / 环境 / 未设置 |
--lexiang-credential-file |
个人凭证 JSON 路径，与 profile 互斥 | config / 环境 / 未设置 |
--dry-run |
仅预览 | false |
同步规则
Markdown
- 将 wikilink 和 Obsidian 图片引用转换为标准 Markdown。
- 本地图片复制到一次性临时工作包。
- 创建时调用公共 CLI 的
--parent-id。 - 更新时调用公共 CLI 的
--entry-id。 - 只有
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/
代码边界
| 文件 | 职责 |
|---|---|
scripts/sync.py |
扫描、调度、临时 Markdown 工作包、调用公共 CLI |
scripts/lexiang_api.py |
目录、探活和独立附件，不含 Markdown page 上传 |
scripts/converter.py |
Obsidian 语法和附件解析 |
scripts/manifest.py |
配置与 manifest |
scripts/report.py |
同步报告 |
scripts/progress.py |
后台进度 |
scripts/test_sync.py |
离线回归测试 |
测试
python3 scripts/test_sync.py
默认测试必须离线，不得在真实知识库创建目录或文档。
公共上传行为有问题时，只修改 upload-markdown-to-lexiang 并补它的测试；
本 Skill 只测试临时工作包、CLI 调用、manifest 和同步调度。
