在此页面上
连接应用程序只是保持其信息有用的开始。授权、首次导入、持续更改和删除是不同的检查点。空的提供商响应也需要与授权失败区分开来。
我们的连接器将云端和本地源观察转换为类型化事件。事件日志保留了它们的修订历史，而派生投影可以从该记录中重建。传输方式因提供商而异；证据合同保持一致。
这 ZortexHQ/try-indra 代码实现了这些同步契约。支持的来源和权限因操作系统和连接器而异。
进入一个事件日志的几种方式
Google Drive 连接器使用提供商 API。其 实施 描述了通过文件列表进行的首次快照，通过修订、评论和权限丰富文件，然后是提供商的更改提要以进行增量工作。连接器还将删除观察映射到事件。分页和可恢复位置很重要，因为大型账户不能被视为一个不间断的请求。
Apple Notes 是一个不同的问题。它是一个本地 macOS 应用程序，并且 笔记源接口 支持单独列出笔记的身份和修改日期，而不是获取其正文。面向生产的实现通过osascript源使用macOS脚本；测试使用确定性源夹具。这种分离允许例程扫描查找已更改的笔记，而无需再次读取每个正文的成本。
对于没有实用 API 的网站，我们还构建了 zortex-miner，一个受控浏览器，具有所有者授权的登录会话。它在网页上操作，而不是假装每个网站都提供稳定的数据 API。浏览器操作和连接器同步是代码库的独立部分；浏览器任务不自动证明其结果已摄取到保管库中。
共同的摄取原则比共同的传输更重要：连接器必须描述它观察到的内容以及提供它的权限。
同步路径
API / change feed ---+
|
Local application ---+--> Connector: discover / pull / normalize
| |
Browser-assisted ----+ typed events
|
append-only event log
|
projections / index / coverage
|
next scheduled refresh
不同的源传输汇聚到事件日志和可重建的投影。
在 Apple Notes 连接器，这些操作具有不同的职责。发现提供计数或普查。拉取枚举上游身份并获取所需字段。规范化将源记录映射到ProtoEvents。连接器不会通过保留自己隐藏的已查看对象集来决定哪个修订版本获胜；事件日志拥有修订链。
这种划分在恢复中很有用。如果投影仪出现故障，从保留的事件中重建它与要求提供商重新交付所有内容不同。如果上游 API 丢失了光标，连接器需要恢复遍历；它绝不能猜测缺失的页面意味着账户为空。
快速刷新需要慢速备用
增量光标是一种性能优化，而不是完整知识的证明。
Notes 代码说明了原因。正常通过会枚举笔记标识符和修改日期，然后检索似乎已更改的记录的正文。但在另一台设备上离线创建的编辑可能会携带较早的修改日期。简单的“比水印新”比较会错过它。因此，连接器还指定了定期全身遍历。它在水印处处理平局，而不是假设每个源时间戳都是唯一的。
API 连接器中也出现了相同的模式：更改提要可以减少重复工作，但工程师仍然必须指定它如何启动、恢复、检测漂移和识别删除。
缺席需要特别注意。最近删除中的备注可以表示为观察到的已删除项目。在 完成 列表不同：连接器知道它何时观察到缺失，而不一定是用户何时删除了笔记。如果列表被截断，缺失不能作为删除的证据。源接口和连接器代码保留了这种差异。
刷新失败不能看起来像空账户
我们的类型化结果边界将有效的空结果与错误区分开来。Notes 源明确将 macOS 自动化权限拒绝视为权限错误，而不是成功的零笔记扫描。
覆盖率核对提出了另一个问题：源文件说存在多少项，我们已统计了多少个不同的身份？这两个计数都不能单独证明记录可用，但不匹配可以指导调查。
这不仅仅是一种理论上的故障模式。一个 2026年9月调查 发现了几个不相关的更新遗漏原因。调度程序测量的是已逝的清醒进程时间，而不是上次同步的时间。重复重启不断延迟工作。驱动器运行时，当保管库保留了源不再计数的身份时，遇到了不匹配。Chrome 历史记录有其自己的保留行为。记录将观察到的原因与关于两个驱动器文件身份的未解决猜测分开。
重要的区别在于日志证明发生了什么以及团队怀疑是什么原因造成的。续签授权后出现的过时失败消息并不能证明授权仍然失效。
在不改变合同的情况下进行批处理
提供商延迟造成了重叠或合并请求的压力。我们 记录了 Gmail 批处理更改 其中获取单个消息涉及重复的远程调用。
批处理暴露了三个共同的义务。请求字节必须在现有重放机制中是确定性的；新的批处理端点需要自己的显式允许列表条目；HTTP响应解析器必须区分外部响应头和多部分主体中嵌套的HTTP形文本。每个项目响应还需要通过其Content-ID进行关联，而不是假设响应按请求顺序到达。
只有当这些属性得以保留时，优化才值得。更少的网络请求并不能证明默默地丢弃错误或将一个记录的响应归因于另一个记录是合理的。
连接器如何报告其状态
这些存储库包含连接器行为背后的源适配器、类型化错误处理、同步路径和事件调查。9 月的刷新事件表明，仅凭连接器数量并不能说明记录的新鲜程度。
OAuth 同意屏幕可能需要一个人，本地操作系统可能拒绝权限，并且源可能返回截断的页面或丢失的光标。每个条件都有单独的错误或恢复路径；不应将任何条件静默报告为空帐户。
每个连接器的操作问题仍然具体： 哪个账户，哪个来源，哪个读取范围，哪个上次成功刷新，以及什么证据表明观察到了预期的记录？ 这些字段随记录一起传输，以便下游检索可以区分当前证据与不完整或失败的刷新。
视觉来源： 代码生成的封面研究.
