把五个工具的历史数据搬进一个工作台:导入、权限与版本记录的隐藏工时

原创2026-10-28 21:35:521,990 阅读
文章标签:企业应用协同办公后端前端即时通讯AI Agent人工智能CRM桌面应用MCP Clients

把五个工具的历史数据搬进一个工作台:导入、权限与版本记录的隐藏工时

Macro 被讨论得最多的,是它把 Email、Chat、Docs、Tasks、CRM 塞进同一个工作台,用双向引用和共享 AI 记忆去终结工具碎片化。社区里最常出现的疑问也很一致:这类“统一工作台”真的能把旧系统里的东西干净地搬过来吗?

功能清单回答不了这个问题。真正决定迁移周期的是三件不体面的事:导入顺序、权限映射、版本与审计的边界。本文基于该仓库的真实源码,把 crates/import 的账本、规划、写入、共享与租约机制拆开来看,给出可执行的迁移次序与验收点,也明确指出哪些历史数据在架构上就无法完整保留。

一、先认清一件事:五个“导入”其实不是同一种操作

打开导入面板,你看到的是四类并列的入口:文件、任务、CRM、渠道(apps/web/src/features/connector-import/core/catalog.ts)。它们看起来对称,底层却分属两条完全不同的路径。

第一条路径是 规划-审核-写入。Notion 工作区、Linear、Jira 走这条:读全量清单、由决策模型逐对象给出结论、把结论写成账本行、在评审卡上等人批准,然后才真正写入。这类导入有 plan / write 两个阶段和独立的 run 生命周期。

第二条路径是 代理对话式搬运。Google Drive、Dropbox、Asana、GitHub、HubSpot 等走这条:agentImportHandoff 生成一段给代理的私有指令,例如文件类要求“用 CreateDocument 逐篇创建并转成 markdown,保留原标题”,任务类要求“用 CreateDocument 且 isTask 为 true,再用 SetEntityProperty 设置状态、负责人和截止日期”,CRM 则要求先 ListCompanies 查重再建(apps/web/src/features/connector-import/core/agent-handoff.ts)。它不是批处理,而是让代理在会话里一条条搬。

第三条路径最容易被忽略:邮箱根本不是“导入”。Macro 的 Email 是 Gmail 上的客户端,账号一接上,历史邮件由 backfill 任务在后台按线程拉取(crates/models_email/src/email/service/backfill.rs)。所以你不需要为邮件排迁移窗口,但需要为它准备配额、失败重试与附件存储。

第四条是 聊天归档:Slack 支持上传导出包,也支持“只建频道不同步历史”的轻量模式(docs/runbooks/media/slack-import/README.md)。

这四条路径共享同一份账本。迁移计划表里 import_entity 的注释写得很直白:它记录的是正在被复制进 Macro 的条目,而 foreign_entity 记录的是永远留在外部的活引用(crates/macro_db_client/migrations/20260720221050_import_entities.sql)。状态机只有四态:staged → importing → imported,旁路是 discarded(crates/import/src/domain/models.rs)。initiator 只表示来源(chat、archive、manual),源码注释明确写了它“只是出处,永远不是可见性过滤器”——这一点后面会变成权限设计的关键约束。

导入面板中的文件类连接器卡片,展示 Notion、Google Drive、Dropbox、OneDrive、Box、Confluence 的并列入口

顺序上最省工的做法,是先把“人”对齐,再搬“结构”,最后搬“流水”:

  1. 先接邮箱(它自己会跑,不占迁移窗口),同时确认团队成员邮箱与外部联系人域名;
  2. 再搬文档与文件夹骨架,因为任务、聊天里的引用需要落点;
  3. 然后是任务/项目,负责人靠邮箱匹配,越早对齐越少返工;
  4. 最后才是聊天历史与归档包,它体量最大、对权限最敏感、也最不该反复重跑。

二、真正吃掉工时的是“先规划、后写入”

Notion 工作区导入不是把 API 拉下来就写。ImportFromNotion 会先读整个工作区的清单,再让决策模型对每一个页面、每一个 data source 给出四选一的结论:copy、tasks、skip、hand(提示词全文见 crates/import/src/domain/service/notion_workspace/triage_system.md)。

这几个选项的边界定得很克制,也很“工程”:

  • tasks 只给那些“每一行都是一件要做的事”的 data source——任务跟踪、待办、backlog、sprint 板、bug 列表。联系人、会议记录、库存、CRM 记录即使有状态列,也必须走 copy;
  • skip 只用于空白的 “Untitled” 页、Notion 自带 onboarding 模板、明显重复项,原则是“拿不准就复制”;
  • hand 极少用,典型是混合了多种无关记录类型的表,或者一个只有嵌入和仪表盘、本身没有内容的页面。

任务跟踪器(Linear/Jira)的提示词则是另一套:对象是 team、project、initiative、epic,子 issue 变成 Macro 任务,保留描述、评论和任务属性,分组本身变成项目;并且明确禁止 tasks 这个选项,因为“那个决定是给 Notion 数据库用的”(crates/import/src/domain/service/notion_workspace/triage_tracker.md)。

规划阶段还有一个容易被低估的体验成本。工具侧只等 5 秒就返回(crates/import/src/inbound/toolset/import_from_notion.rs 中的 PLAN_WAIT),此时 run 通常仍是 running,但评审卡已经可以先弹出来。账本行的注释解释了这套配合:规划一读完清单就把整棵树按“未决定”落成行,之后每批决策模型的结论陆续写回行上,报告把尚未决定的计入 deciding,写入必须等 run 变成 ready 才能开始(crates/import/src/AGENTS.md)。

这就是“隐藏工时”的第一块:你等待的不是网络传输,而是模型逐条判断。一个几千页的工作区,规划时间和人工复核时间往往超过实际写入时间。实践建议是把评审卡当成真正的关口:先看 hand 与 skip 的清单,再决定是否放行——因为报告最多列出 50 条失败与待人工项(crates/import/src/domain/service/notion_workspace/report.rs),超出的部分只能靠计数变化发现。

三、断点续传:为什么这套导入敢让你点半途而废

迁移中最贵的不是慢,是重跑。这套实现的答案是让“重跑”变成“续跑”。

写入阶段的所有身份都是推导出来的,不是随机生成的:文档 id 由账本行的 UUIDv5 派生(document_id(import_id)),数据库列与选项的 id 由数据库 id 加属性名派生,行列同理(crates/import/src/domain/service/notion_workspace/write.rs、values.rs)。Macro 侧对已存在的 id 直接拒绝创建,于是“再写一次”天然等价于“什么都不做”。

其余无法用 id 表达的东西,被记进 import_entity_written:文件夹、文档、数据库、行批次、行正文、任务、关系列,各占一行 (import_id, kind, object, macro_id)(crates/macro_db_client/migrations/20261020233827_notion_import_run_lease.sql)。写入恢复时先查这张表,已经建过的直接复用。

跨进程续跑靠租约:import_run 上有 lease_owner、lease_expires_at、scope、review_id、adoptions。进程心跳续租;崩溃或发版后租约过期,另一个进程用 FOR UPDATE SKIP LOCKED 领养这次 run——规划重新开始,写入从仍是 importing 的行继续。连续被领养五次就判定失败,防止“每次跑到一半就把进程搞死”的毒任务无限循环。

取消也不是立即生效的硬中断,而是在批次、行、任务之间检查的检查点(Cancel::ensure_running),所以停止会在秒级落到下一个检查点,已提交的部分不丢。

Gmail 那边用了另一种一致性模型,但目标相同。insert_backfilled_thread 在一个事务里写入整条线程和全部消息;单条消息若被 is_unstorable 判为不可存储,则退到自己的 savepoint 里被跳过,其余照常提交;如果线程已存在(包括并发插入抢先),直接回滚返回 None,一个字节都不写(crates/email_db_client/src/threads/insert.rs)。线程行的 upsert 还有一条细节:当入站的 latest_inbound_message_ts 为空或未变化时整段更新被跳过,避免重复投递的 backfill 把已填好的时间戳清成 NULL。

源码里也诚实列出了未闭合的窗口:文件夹/数据库/行批次“创建成功但尚未记账”之间崩溃,会重复这一个对象或这一批;schema 操作已应用但未记账,恢复时该数据库会失败(Macro 拒绝重复的列 id)。这类残留就是你需要预留的人工核对工时,而不是文档里不存在的“零风险”。

四、权限映射:冲突不在映射表,而在“谁能改、谁先到”

跨系统合并权限,最天真的做法是做一张角色对照表。这个仓库没这么做,它把权限拆成两个正交问题:这份东西给谁看,以及同一个对象被两个队友同时导入时算谁的。

4.1 共享粒度按“对象”而不是按“工作区”

Notion 导入在规划时要求用户先选 team、personal 或 ai 三选一(crates/import/src/domain/models/notion_sharing.rs)。选 ai 时,决策模型要为每个对象额外回答 shared 与一句 sharedReason。判定原则写得很实用:团队 wiki、手册、流程、项目与产品文档、规格、路线图、团队会议纪要、共享任务板应当共享;个人笔记、日记、草稿、私人待办、一对一记录、薪酬/招聘/绩效/健康相关信息、凭据,以及位于个人页面之下的内容应当保持私有;拿不准就私有,因为“以后再共享很容易,把已经被读过的东西收回很难”(crates/import/src/domain/service/notion_workspace/triage_sharing.md)。

如果用户在团队里却没做这个选择,规划会直接报 NotionSharingRequired,工具把错误翻译成一句给代理的指令:“用户在团队中,请问是共享给团队、全部私有,还是让 AI 逐组决定”(crates/import/src/domain/service/ports.rs、crates/import/src/inbound/toolset/import_from_tracker.rs)。没有团队的用户不追问,直接按 personal 规划,报告里的 onTeam 会说明这一点。

4.2 文件夹是最容易翻车的一层

共享一个文件夹等于共享它里面的全部内容。所以 shared_folders 的规则是:只有当文件夹内写入的每一个对象(包括这个文件夹自身的页面)都共享时,这个文件夹才共享;只要有一个私有页面或私有数据库落在里面,整个文件夹留在个人空间(crates/import/src/domain/service/notion_workspace/sharing.rs)。

这条规则解释了为什么“先搬结构、再搬内容”会踩坑:你在 Notion 里那种“团队空间下面塞了一个私人子页”的结构,导入后会导致整棵子树无法整体共享,需要人工在评审卡上逐项翻转。评审卡支持这种翻转(NotionWriteChoices 里的 shared / personal 列表),但只对 shareable 的行生效——没有团队的用户所有行都不可改。

4.3 团队去重:唯一索引 + 等待链

import_entity_team_object_key 是一个部分唯一索引:(source, team_id, foreign_id),只覆盖 notion 和 linear,且只覆盖 importing / imported 两个状态(crates/macro_db_client/migrations/20261017002500_import_entity_team_object_key.sql)。语义是“一个团队对一个外部对象只有一份 Macro 副本”,第一个认领的人拥有它,后来者链接到这份副本。

注意 team_id 的定义:它表示“团队的副本”,只有共享对象在 claim_importing(staged → importing)时才写入,而且是在写任何内容之前写入。个人副本永远不带 team_id,所以队友既看不到也不会链接到它,各自导入各自的副本。规划阶段如果发现某个对象已被队友导入并共享,会标记为 alreadyImported,跳过决策模型调用、不计入副本数,写入时直接链接。

写入时 claim_team_object 对每个共享对象做四选一:拿到认领就自己写;已有完成的副本就链接;持有者的 run 没有有效租约就接管;否则等待。等待的行在其余内容写完后复查一次,仍未就绪就以 waiting_on 指向持有者的行挂起。mark_imported 用第二条语句回链等待者——等待者当时对持有者行持有 FOR SHARE,所以两边不会互相漏掉;持有者退回 staged 时,等待者也会被释放回 staged。源码同样标注了未闭合的竞态:接管与原始持有者自己的恢复同时发生,可能留下两份副本。

4.4 Slack:源绑定与“别把人塞进私聊”

Slack 的权限映射比 Notion 更硬,因为它有真正的会话边界。归档导入的契约文档规定(docs/runbooks/slack-archive-import-contract.md、docs/runbooks/slack-archive-import.md):

  • 公开频道变成 Team 频道,且 auto_join_team=false,成员按源显式写入;
  • 私有频道与群组私聊变成 Private;
  • 一个 DM 必须恰好有两个映射到邮箱的身份,不允许把执行导入的管理员作为第三名成员加进去;
  • 无权限复用的私有/DM 目标会被跳过,且不暴露其 ID;
  • 历史写入不得产生实时通知、机器人调用、联系人邀请或逐消息的活动扇出。

源身份也必须唯一且有据:bind_source 保证一个团队绑定一个 Slack workspace,已知绑定不可变,未知绑定可以精化为已知,但不匹配直接 SourceMismatch;完全无法确认身份时,每一次创建都要显式带上 confirmed_unknown,“省略不等于确认”(crates/import/src/source_binding.rs)。

Slack 导入的两种模式选择:推荐的历史导入与仅建频道

把这些映射到工时上:真正的冲突几乎都出在“边界对象”——跨团队共享的子页、DM 里的第三个人、私有频道里的外部成员、重名频道。这些没有算法能替你决定,只能在评审阶段逐条确认。

五、版本与审计:能保留的是“导入过程”,不是“源系统的历史”

这是本文最需要泼冷水的一节。

文档正文只保当前快照。 写入阶段并不在本仓库解析 Notion 的页面块,页面正文以 Notion markdown 加一张 NotionLinks 映射表交给 lexical-service 的 POST /snapshot/notion;Rust 侧只保留两个守卫:工具结果包装器与“只有数据库、没有正文”的页面(crates/import/src/AGENTS.md)。创建文档时确实可以带一份 initial_snapshot(crates/documents/src/domain/create.rs),但那只是导入那一刻的初始内容。

Macro 自己的版本历史是完整的。 产品文档写得很清楚:文档支持 time-travel,按用户与时间浏览历史状态,还能把任意历史版本 fork 成新文档(apps/docs/product/docs.mdx)。但这条时间线的起点是导入完成那一刻。Notion 页面过去的编辑历史、页面级评论、块级评论不会随导入过来;同理,Jira/Linear 的 issue changelog 也不在计划快照里——计划保留的是 issue/group 的完整快照,写入时不再重新扫描源,以保证评审卡就是最终结果。

任务侧的映射是有损的,而且是有意为之。 评论追加到正文末尾,标签变成个人标签,项目与父任务属性只链接 Macro 中存在的目标,负责人按团队邮箱匹配,源系统里没有对应 Macro 属性的值一律留在正文里(crates/import/src/AGENTS.md、crates/import/src/domain/service/tracker_workspace/values.rs)。Notion 任务列表同理:被用作 status/priority/due/assignee 的列会被剔除,其余属性渲染进正文(crates/import/src/domain/service/notion_workspace/values.rs)。这保住了信息,但丢掉了结构——它们不再是可筛选的字段。

聊天历史是“按时间戳去重”,不是“同步”。 契约明确写着:重复与重叠/按日期切分的导出会去重,但不会同步后续的编辑与删除,也不会修复更早的孤儿线程,现有的频道名、角色、离职者、创建时间与更晚的实时活动必须存活(docs/runbooks/slack-archive-import.md)。也就是说,Slack 侧一旦有人在你导出后改了消息,Macro 里看到的就是导出时的那一版。

那审计记录呢? 这里有三层账本,但它们审计的是“导入”本身,不是“源系统”:

表 / 字段 记录了什么 能回答的问题
import_entity 每个被搬对象的 source、foreign_id、状态、entity_id/entity_type、last_error 这条东西搬没搬?搬到哪?失败原因是什么?
import_run 每次运行的 status、error、scanned 计数、sharing、租约与领养次数 这次跑了多久、被谁接管、为什么停?
import_entity_written 每次写入实际创建了哪些 Macro 对象 续跑时哪些能复用?哪一步崩了?

再叠加报告里的 warnings 与最多 50 条失败/待人工项,你得到的是可追溯的迁移过程。如果合规要求你保留“源系统里某条记录在 2024 年被谁改过”,那它不在这个方案的能力范围内,需要在迁移前单独导出源系统的审计日志存档。

顺带一个反向的例子说明“历史”这件事有多贵:仓库里有一份已退役的注释与 CRM 导入器说明,它的前提是迁移已经完成、源表已被 schema drop 删除,并明确警告“不要在 drop 之后用旧 checkout 跑 importer”(docs/runbooks/legacy-comment-import.md)。迁移代码是有寿命的,过期后连回滚路径都会消失。

六、把隐藏工时折算成一张执行清单

综合源码,可以把“搬五个工具”拆成下面这些必须被排期的动作。它不是产品功能的复述,而是工程与运营的真实成本项:

  1. 身份先行:统一成员邮箱、确认外部联系人域、清理离职账号。任务负责人匹配、Notion 人员列映射、Slack 成员映射全部依赖它;匹配不上的一律降级为正文文本或系统机器人加来源标签。
  2. 结构次之:先导入文件夹与文档骨架,再导内容。对“团队空间里挂私人子页”的结构提前拆分,否则整棵子树无法共享(shared_folders 的全共享规则)。
  3. 给规划留出人工复核窗口:PLAN_WAIT 只有 5 秒,评审卡会在 run 还是 running 时就出现;把 hand、skip、alreadyImported 三类清单当成必读项。
  4. 为断点续传设计运维动作:理解租约与 adoptions,知道“五次领养后失败”意味着要人工介入;接受“文件夹/数据库/行批次创建后未记账会重复一次”的极小概率,并准备去重核对脚本。
  5. 权限按对象决策,而不是按空间:team / personal / ai 三选一之后,仍要逐项确认边界对象;拿不准就私有。
  6. 接受版本历史的断点:目标系统从导入那刻起有完整 time-travel,源系统的编辑历史、评论历史、changelog 需要单独归档。
  7. 聊天历史只跑一次:归档导入按时间戳去重、不同步编辑与删除,所以导出包应当在冻结窗口内生成;不要在迁移后再指望它追平。
  8. 最后校验三张表:import_entity 里是否还有长期停在 importing 的行、import_run 是否还有 failed/dismissed、import_entity_written 与目标对象数量是否能对上。这三张表就是你的迁移验收报告。

回到开头那个问题:统一工作台能不能终结工具碎片化?在数据层面,它确实把五类对象放进了一套账本、一套状态机和一套共享语义里,import_entity 的注释甚至把“复制进来”和“保留外部引用”明确区分成两张表——这是很清醒的设计。但“搬进来”的工时从来不在 API 调用上,而在逐对象的决策、边界权限的确认、以及你愿意放弃多少源系统历史这三件事上。这三件事,任何工作台都替你做不了。

登录后查看全文
macro