Feishu → Obsidian PARA Sync

> 模式：Pipeline | 数据源和目标路径从 SYNC-RULES.md 读取

核心设计

内容获取由 Agent 的 feishu_fetch_doc 工具完成，Python 脚本只做路径构建和文件写入。

这样无需在脚本里管理 Access Token，也不需要在 clawhub 发布时携带敏感权限。

硬性规则

禁止跳过步骤。禁止在用户确认前进入下一步。

Step 1 — 前置检查 + 获取 Wiki 节点（并行遍历）

触发：用户要求同步飞书文档

1a. 前置检查

1. 检查 vault 根目录是否存在 SYNC-RULES.md
• 不存在 → 触发初始化流程
2. 读取 SYNC-RULES.md 中的「数据源」表格

1b. 获取 Wiki 根节点

使用 feishu_wiki_space_node 工具获取每个 Wiki 的根节点。

1c. 并行遍历子节点

对于 has_child: true 的节点，并行获取子节点：

• 每个 has_child 节点分配一个并行任务
• 各分支同时请求，不等待串行
• 递归直到所有分支都没有子节点

个人成长 (root)
├── 2026-03 (has_child) ──────┐
│   └── 7个子节点              │ 并行遍历
├── 软考笔记 (has_child) ──────┼
│   └── 4个课程文件夹          │ 并行遍历
├── Obsidian 整理报告
└── 辞职决策记录

openclaw知识库 (root)
├── 11个文档节点（部分有子节点）  并行遍历

1d. 生成同步计划

将完整节点列表传给 sync.py --plan，获取待写入文件清单：

echo '[节点JSON]' | python3 sync.py --stdin --plan

输出：

• need_fetch：需要 Agent fetch 内容的 docx 文档
• no_fetch_needed：只写占位符的非 docx 类型

Gate：显示节点总数、来源 Wiki、待写入文件数，问用户确认是否继续。

Step 2 — 确认同步路径

触发：Step 1 确认后

执行：

sync.py --plan 已输出每个文件的 relative_path 和 filename，显示路径映射表。

Gate：显示写入路径映射表，确认是否继续。

Step 3 — 获取文档内容并写入 Obsidian

触发：Step 2 确认后

3a. Agent fetch 内容

对 need_fetch 中的每个文档，调用 feishu_fetch_doc 获取正文。

3b. 批量写入

将「文档信息 + fetch 到的内容」传给 sync.py --write：

echo '[{"title":"...","obj_token":"...","content":"...",...}]' \
  | python3 sync.py --stdin --write [--dry-run]

frontmatter 生成规则

• 基础字段：date、lastmod、draft、categories、tags
• 飞书扩展字段：无条件追加：feishu_doc_token、feishu_wiki、feishu_node_token
• feishu_doc_token 用于去重，已存在则跳过

目录自动创建

relative_path 目录不存在时，自动创建。

Gate：显示将写入的文件列表，确认后执行。

Step 4 — 质量检查

触发：Step 3 执行完成后

执行

1. 加载 references/review-checklist.md
2. 对照检查清单验证同步结果
3. 报告检查结果

输出格式：

【同步报告】
- 写入：X 个文档
- 跳过：X 个（已存在）
- 失败：X 个（错误信息）

初始化流程

触发：vault 缺少 SYNC-RULES.md

执行：

1. 向用户说明缺少文件
2. 生成默认版本（SYNC-RULES.md 模板）
3. 展示给用户确认
4. 用户确认后写入 vault 根目录
5. 继续 Step 1

模板文件：assets/sync-rules-template.md

参考文件

已知限制

• 电子表格（sheet）、多维表格（bitable）、思维导图（mindnote）只写链接占位符，不拉内容
• 并行遍历依赖 subagent 能力，每个 has_child 分支可同时请求
• Space ID 和目标路径从 SYNC-RULES.md 读取，修改配置后重新同步即可生效