Omi 桌面端集成不变式 INV-INT-1以 Harness 为核心、以功能探针为证伪的 Connector 架构指南【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend本文是 Omi 开源仓库中锁定不变式invariantINV-INT-1 的深度解读与落地指南。它面向在桌面端维护 Connect dataGmail、Calendar、Notes、Files 等数据源与 Connect your AIClaude、ChatGPT、Codex、OpenClaw、Hermes 等 AI 连接器的工程师与 Agent核心结论是对不归我们所有、无法版本化的外部表面harness感知–行动–验证–探针–恢复的闭环框架才是产品本体自动化脚本只是可丢弃的耗材。读完本文你将掌握连接器的三分类决策规则、五拍闭环、assisted-first 交互形态、功能探针functional probe门禁、Connected 语义的重定义以及驱动这一切的检查清单与云连接器路线图。1. INV-INT-1 是什么一句锁定不变式product/invariants/integrations.md 以INV-INT-1命名这条不变式状态为locked锁定即所有改动必须符合它其完整表述是For connectors and data sources on surfaces we do not own, the harness is the product and the automation is disposable. Code owns contracts; agents only drive what code cannot reach; Connected means verified recently via a functional probe.翻译并拆解为四条支柱Harness 是产品自动化是可丢弃的——外部表面的稳定性不取决于我们写了多聪明的点击脚本而取决于包裹着 Agent 的闭环框架代码拥有契约contracts——凡是格式归我们掌握的配置文件、API、CLI一律用确定性代码完成不派 AgentAgent 只驱动代码够不到的地方——即没有文件、没有 API、只有人类 UI 的第三方网页流程Connected 意味着最近通过功能探针验证过——不是曾经成功过一次。这份文件同时给出了 7 条 MUST NOT红线、覆盖面Surfaces、守护测试Guard tests、路径 globs 与 PR 规则并指向三份权威文档核心哲学 desktop/macos/docs/integrations-philosophy.md、机械式检查清单 desktop/macos/docs/connector-checklist.md、以及最难两块表面的演进计划 desktop/macos/docs/cloud-connectors-roadmap.md。2. 为什么需要这条不变式我们在集成我们不拥有的表面哲学文档的开篇即点明永久性处境integrations-philosophy.md §0我们集成的对象是其他应用的 UI、其他应用的 cookie 加密、其他应用的配置文件格式、其他提供商的网页流程。它们不给契约、不给弃用窗口、不给我们能捕获的错误。它们随时会变而一旦变化我们的集成不会抛异常——只会静默点错按钮或读到过期 cookie。这决定了写更好的启发式heuristics是一条死路唯一正确的存活方式是围绕干活的那个 Agent 搭建正确的 harness。文档原话即不变式本身The harness is the product. The automation is disposable.仓库里最典型的反面教材是 CloudConnectorFormAutomation.swift——约 1,600 行硬编码点击与 OCR 锚定逻辑。按哲学文档 §2 的定性它是我们能造出的最不 agentic 的东西更聪明的模型只会让它被淘汰而非更好因此禁止再向它添加任何硬编码元素锚定启发式MUST NOT 第 1 条。3. 三分类决策规则代码拥有契约integrations-philosophy.md §1 给出新增连接器时的决策规则按可靠性从高到低排列有配置文件可写→ 用代码写完成。category 1有 API 或 CLI→ 用代码调用完成。category 2只有人类 UI→ 才允许 Agent 驱动且必须在闭环内进行。category 3每把一个连接器从第 3 类挪到第 1/2 类它就停止不确定性。这是你能买到的最便宜可靠性先做它再谈别的。3.1 源码佐证MemoryBankConnector 的确定性本地写入MemoryBankConnector.swift 是 category 1/2 的样板实现其文件头注释即契约OpenClaw / Hermes have no setup CLI; the agent doesnt reliably perform the file write. Do it deterministically ourselves (idempotent local write).handles(_:)L23-30声明它负责四个本地目标.claudeCode、.codex、.openclaw、.hermes而.notion、.obsidian、.chatgpt、.claude等走其他路径。具体写法如下Claude Code解析~/.claude.json的mcpServers幂等地写入omi-memory条目type: httpurlAuthorization: Bearer keyL110-166写入前先备份到~/.claude/backups/并保留最近 5 份claudeCodeBackupRetentionLimitCodex调用codex mcp add omi-memory -- npx -y mcp-remote url --header Authorization: Bearer keyL209-236OpenClaw通过 CLImcp set/mcp reload维护mcp.servers并向工作区SOUL.md幂等追加先搜 Omi 记忆标记块L240-284、L569-597Hermes幂等地向~/.hermes/config.yaml顶层mcp_servers:节 upsertomi-memory条目并同样追加SOUL.md提示L601-738。关键细节isInstalled(_:)L38-59用与 connect 路径完全相同的证据做前置探测——例如 Claude Code 检查~/.claude.json、~/.claude/settings.json或 PATH 上的claudeCodex 检查 PATH 上的codex可执行文件。文档注释明确解释其原因onboarding 的前置探测必须与点击后的 connect 结果一致否则会出现行上显示可 Connect、点击后才报 not installed的错位。每次写入后还会调用MemoryExportConnectionDetector.hasExistingConnection(for:matchingKey:)做回读验证验证失败则抛出ConnectError.invalidConfig。4. Agent 驱动面的五拍闭环而不是脚本当确实需要 Agent 时category 3integrations-philosophy.md §2 规定每个 Agent 驱动流程必须跑满五个节拍harness 的职责是把每一拍做成一个干净的原子工具Observe观察——把完整可访问性树/DOM 截图交给 Agent不要预先过滤成去找 Add 按钮。定位目标本来就是模型的工作替它做且做得很差正是CloudConnectorFormAutomation里 Infer Claude Add target from Cancel button 这类提交的由来。Act行动——只提供原子原语click(x,y)、type、key、scroll、navigate。Re-observe再观察——每个动作后重新快照。行动-再观察是最大的可靠性杠杆也是脚本结构性做不到的事。Verify验证——让 Agent 确认状态确实按预期变化。Recover恢复——状态不匹配时把失败反馈给 Agent让它尝试另一种路径限制 N 次尝试后大声失败fail loud。红线如果你发现自己硬编码点哪个元素或它在屏幕哪里立刻停止。该知识是易变的volatile把它编译进 Swift 意味着每次提供商改版都变成一次发布周期。5. 第三条路assisted-first——代码做确定性的 90%把最后一次点击留给人类当代码写不了文件、Agent 驱动 UI 又不可靠时integrations-philosophy.md §2b 提出介于两者之间的第三种形态打开精确的 deep link在可拖动的屏幕卡片上逐字段展示配置值每个字段一个复制按钮屏幕显示掩码复制时给真实值自动展开连接器面板中的分步操作列表——用户负责粘贴并点击最后一个按钮。A 100%-reliable you click once beats a 60%-reliable do it for me that leaves the provider UI in an unknown state. 100% 可靠的你点一次胜过 60% 可靠却把提供商 UI 留在未知状态的替我做完。这就是当前 ChatGPT / Claude 云连接器的主流程也是 cloud-connectors-roadmap.md Phase 1 的实现形态。源码侧由 CloudConnectorGuidanceOverlay.swift 的presentFieldCopyCard(...)L449-463承担字段值来自assistedSetupFields秘密在屏幕上掩码显示、复制时还原。该形态的附带收益是不再需要辅助功能Accessibility或屏幕录制Screen Recording权限也不会把提供商 UI 留在未知状态。6. 永不信任 UI每条流程必须以功能探针收尾integrations-philosophy.md §3 是整条不变式的验证核心界面上显示 Connected 并不证明集成在工作。只有当一次真实的功能调用穿过你刚配置的东西并成功设置才算完成。仓库里探针已经存在实现在 MemoryExportService.swifttestHostedMCPMemoryCount(key:)L1114-1129向宿主 MCP 端点发起一次真实的 JSON-RPCtools/call方法get_memories参数{limit: 5}数出返回的记忆条数testAgentConnections(hostedKey:localToken:)L1078-1089并发执行宿主 MCP 计数与本地 Agent 工具计数把结果汇总为AgentConnectionTestResult。两个信号必须分离Agent 的屏幕读取告诉你点哪里探针告诉你是否真成功了。混在一起就会持续发布虚假的 Connected。6.1 探针必须覆盖整条链路包括我们自己的契约端点哲学文档 §3 记录了 ChatGPT 连接器在生产环境中的失败教训故障不是出在提供商 UI而是出在我们自己的 OAuth 接线——一个未注册的 client id加上无法覆盖每个连接器回调的精确匹配exact-matchredirect 白名单。如果探针只检查 MCP 数据调用这套设置会被判为正常。因此规则是探针要演练提供商实际会执行的认证握手auth handshake。后端侧backend/routers/mcp_sse.py 已支持 public PKCE 客户端与按提供商per-provider回调白名单是这一能力的基础设施。6.2 零条目不等于失败检查清单connector-checklist.md §5特别强调当真实路径确实成功时零条目返回应视为已连接——空数据不是连接器故障。对 Apple Notes 这类文件型本地连接器保留旧的父文件夹选择通过同一套 canonical folder 逻辑解析并把路径/访问失败与 schema/读取失败区分开让 UI 只在新建文件夹确实能解决问题时才重新弹出文件夹选择。7. Connected 意味着最近验证过而不是曾经为真integrations-philosophy.md §4 指出今天的连接状态是一个单向闩锁one-way latch。源码正是如此——MemoryExportService.swift 中// L733: connectedAtKey fileprivate var connectedAtKey: String { memoryExportConnectedAt.\(rawValue) } // L806: 状态判定里的闩锁读取 let hasConnectedTimestamp defaults.double(forKey: destination.connectedAtKey) 0 // L1091-1094: markConnected 一旦写入就永久为真 func markConnected(_ destination: MemoryExportDestination) { defaults.set(Date().timeIntervalSince1970, forKey: destination.connectedAtKey) clearIntegrationNudgeHistory(for: destination) }时间戳一旦写入来源就永远显示 Connected——即使 cookie 过期、密钥轮换、或用户已在提供商侧删除连接器。用户心智模型与现实脱节表现就是随机坏掉。规则状态必须来自最近一次功能探针§6与CredentialHealthManagerCredentialHealthManager.swift一个基于失败记录与指纹做 provider 健康度管理的 ObservableObject绝不要来自闩锁。如果它没有在新鲜度窗口freshness window内被验证它不叫 Connected而叫needs check。仓库里已经出现向这个方向演进的痕迹refreshCloudGrantConnectionStatus(for:)L871-903对 ChatGPT/Claude 这类云 OAuth 连接器会在用户于浏览器授权后调用后端v1/mcp/oauth/grants接口核对授权列表——只有后端的 grant 列表才知道真相本地时间戳只是缓存投影网络失败时宁可保留最后已知状态也不把授权误报为吊销。8. 感知保真度排序永远选最高保真度的感知integrations-philosophy.md §5 把感知手段按可靠性从高到低排列API 响应契约——存在就用DOM通过可控浏览器如 CDP/Playwright——选择器稳定、元素状态真实、有aria标签可访问性树AX tree——结构化但依赖具体应用暴露程度像素级 Vision/OCR——最后手段。OCR 读出来的是 Add 还是 Add-on推理很直接感知保真度就是可靠性。提供商连接器流程本质是网页用原生窗口的 OCR 去驱动它是对最容易改进的表面采用了最差的选项。下次再碰基于网页的流程应把它移到浏览器上下文里让 Agent 感知 DOM 而非像素——同一个用户会话、无需重新认证只是观察信息丰富得多。9. Provider 知识是数据不是二进制integrations-philosophy.md §6 指出大量痛点是延迟提供商移动一个按钮修复需要改 Swift、干净发布构建、公证notarization、用户更新——几天时间就为了按钮挪了位置。这完全颠倒Harness感知/行动/验证/探针/恢复是稳定的 → 编译进二进制Provider 知识如何设置 X、流程长什么样是易变的 → 作为**可远端更新的配置/技能config/skills**由应用获取下发。提供商改版时推送一份新的指令 blob已安装应用下次运行自动自愈无需为易变知识走发布周期。我们自己的后端配置同样是 provider 知识。OAuth client id、redirect 白名单、authorize/token URL 都存在于后端环境变量中dev 与 prod 之间会分叉且变化不经过桌面端发布。把它们编译进 Swift今天chatgptOAuthClientID就是这么做的会让桌面端引导静默偏离后端实际注册内容——这正是 Unknown OAuth client 事故的来源。规则连接器设置值应从桌面端所指向的那个后端下发。10. Eval Flywheel把失败变成离线语料让模型变聪明的赌注兑现integrations-philosophy.md §7 回答了一个根本问题脆弱的表面在 CI 全绿时被用户发现坏掉怎么办答案是把表面变成可测试的每次真实运行记录 trace观察AX 树 / DOM / 截图、动作、结果、是否验证失败运行自动上传脱敏后的 trace——这同时是金丝雀在用户涌入前发现提供商变了和 eval 语料用捕获的 trace 离线回放候选模型/提示词下一个模型还能不能完成全部 N 个提供商设置变成 CI 问题针对真实捕获快照作答而不是上线后才发现。没有这个循环模型升级就是无法度量的掷硬币有了它每次提供商 UI 变更都变成捕获新快照 → 加入 eval 集 → harness 与下一个模型针对它加固。脱敏不可妥协——trace 里有用户的屏幕。必须用sanitize()/sanitize_pii()约定在数据离开机器前剥掉 cookie、token 和消息正文对应 MUST NOT 第 7 条上传连接器 trace 前必须剥离 cookie、token 与 PII。11. 自愈与爆炸半径隔离integrations-philosophy.md §8 提出两条运行时纪律持续验证器 → 自动修复按心跳运行功能探针失败时不只翻转徽标——在用户察觉前于后台派生 Agent 重做设置。这是 Agent 适应能力变得可见的地方集成悄悄自愈。按提供商隔离一个提供商的流程坏掉必须是熔断circuit breaker而不是整列连接器一起宕机。绝不能让连接器共享一个 god-module否则一次 Claude 变更就可能回归 Gmail。文档点名CloudConnectorFormAutomation和超大号的MemoryExportService是应该拆开而非扩展的反模式。12. MUST NOT 红线与反模式总览不变式文件product/invariants/integrations.md的 7 条 MUST NOT与哲学文档的 Anti-patterns 节完全一致是评审任何连接器改动时的硬门槛不得再向CloudConnectorFormAutomation添加硬编码元素锚定启发式该文件的变更史就是证据不得把 Connected 建立在时间戳闩锁或一次性成功之上不得派 Agent 去完成确定性文件写入或 API/CLI 就能完成的活有 DOM 可用时不得通过 Vision/OCR 感知网页流程不得把易变的 provider 知识编译进 Swift 二进制不得发布没有功能探针收尾的设置流程不得在未剥离 cookie、token 与 PII 的情况下上传连接器 trace。13. 实操检查清单从哲学到机械步骤desktop/macos/docs/connector-checklist.md 把哲学文档操作化为一份修复或新增连接器的机械式清单以日历修复CalendarReaderService.swift为工作参照worked reference自顶向下执行不可跳过探针与 fixture 测试。七个步骤完整如下1. 分类表面Classify the surface代码能写配置文件→ 用 Swift 幂等写不要派 Agent哲学 §1有 API/CLI→ 用代码调用只有人类 UI / 浏览器会话→ 继续但以下全部适用。2. 聚合诊断——绝不 last-writer-wins循环遍历候选浏览器、profile、账号时为每个候选收集结构化尝试记录{who, stage, reason}而不是覆盖单个last_error。日历 bug 只暴露 Chrome (Profile 3) 是因为它最后被尝试——其余六个 profile 被静默丢弃了哲学 §2分类最有行动价值的失败而不是最后一个失败优先报 session expired曾有认证、拿到 401/403而不是 not signed in空 profile。参考 Python helper 的classify()。3. 反映现实的错误分类Error taxonomy把失败映射为互斥、诚实的 case——notSignedIn、sessionExpired、noBrowserFound、network……绝不使用 catch-all登录问题不得渲染成 Network error哲学 §3每个 case 的用户消息说清下一步该做什么如 Open calendar.google.com in Chrome and sign in而不只是报失败。4. 纯函数、可测试的解析缝Parsing seam把 raw payload → classified outcome 放进纯函数如CalendarOutcomeParser.parse无 I/O、无 Process、无浏览器为每种真实失败模式各加一个 payload fixture 测试——这些就是 eval flywheel 运行的捕获观察哲学 §7。野外出现新失败形态时把它的 payload 加进来。5. 功能探针——connected 意味着现在验证过添加verifyConnection()在小窗口内走真实路径返回实时状态connected/needsSignIn/error绿色结果必须保证整条链路端到端可用哲学 §3、§4UI 状态与一切 Connected 徽标由探针驱动绝不来自存储的一次性成功闩锁为探针暴露语义化自动化动作例如calendar_read_probe让编码 Agent 能在命名 bundle 里自测成功/失败分类无需点击 UI真实路径成功时 零条目返回 视为已连接探针/读取参数在跨越进程或网络边界前先钳制clamp并测试边界行为文件型本地连接器如 Apple Notes通过同一套 canonical folder 逻辑解析旧父文件夹区分路径/访问失败与 schema/读取失败暴露与 UI 相同稳定分类的语义化探针如apple_notes_read_probe。6. 脱敏诊断进入语料记录一条结构化、非敏感的尝试一行日志名字、阶段、原因绝不含 cookie 值、token 或响应体哲学 §7。7. 发布卫生在desktop/macos/changelog/unreleased/添加 changelog fragment改动范围限定在本连接器内不要伸手进共享 god-module 而回归其他连接器哲学 §8。当前 Google 连接器基线便于新修复复用共享路径Calendar 与 Gmail 共享BrowserGoogleSession浏览器/profile 发现、Safe Storage 访问、Chromium cookie 处理与PipeProcessRunner防死锁的辅助进程执行。新的浏览器-cookie Google 修复应保持在共享路径上。14. 路线图最难的两块表面如何演进desktop/macos/docs/cloud-connectors-roadmap.md 专门覆盖两个既无配置文件也无 API的云连接器——ChatGPTcustom connector / developer mode与 Claudeclaude.ai custom connector即纯粹的 category 3 表面。为什么暂停park了自主设置ChatGPT——曾自动化过最深的流程Settings → Apps → Advanced → 开启 Developer mode需付费计划→ Create app → 8 字段 OAuth 表单 → consentAgent 通过 AppleScript/AX/截图驱动用户默认浏览器经常半途死亡且部分失败根本不是自动化失败——custom connector 需要带 developer mode 的付费计划而我们没有检测这个前置条件Claude——原生路径CloudConnectorFormAutomation约 1,600 行硬编码 AX 锚定只在部分机器上可用AX 暴露因浏览器而异Chrome/Safari/Arc/AtlasClaude 在某些浏览器中把 Add/Connect 从 AX 隐藏还需要辅助功能有时还要屏幕录制授权。结论遵循哲学文档不要在别人拥有的表面上继续调启发式把确定性的 90% 变成自己的把最后一次点击留给用户。Phase 1 —— Assisted-first当前Claude 主路径 ChatGPT fallback打开提供商 deep link → 屏幕卡片逐字段复制CloudConnectorGuidanceOverlay.presentFieldCopyCard值来自assistedSetupFields秘密掩码显示→ 连接器面板自动展开分步操作。无需辅助功能/屏幕录制权限不遗留未知 UI 状态。MCPExecuteKind.browserAutonomous仍存在但已 unmappedMemoryExportExecutor.runBrowserAutonomous/runClaudeNativeCloudSetup保留为 Phase 2 的路由槽。两个值得在 Phase 1 内完成的跟进项① 用功能探针testHostedMCPMemoryCount门禁这两个连接器的 Connected而非markConnected闩锁哲学 §3/§4② ChatGPT 前置条件探针——检测付费计划/developer mode 资格直接告知用户而不是把人送进注定失败的流程。Phase 2 —— DOM 保真度自动化下一步只有具备真实 DOM 感知时才重新引入自主设置哲学 §5不用原生浏览器窗口的 AX/OCR。首选形态是Omi 内嵌 WKWebView在自有 webview 中加载 claude.ai / chatgpt.com用evaluateJavaScript驱动——完整 DOM 保真、零跨浏览器 AX 差异、无 macOS 权限流程代价是独立 cookie jar用户需在内部登录一次Google OAuth 会拦截 webviewemail/验证码登录可行且保持的会话可兼作 §8 的心跳重验证通道。备选是受控真实浏览器Playwright/CDP 于用户 profile会话复用更好但发布更重以原型定夺。构建时必须遵守选择器/流程知识以可远端更新数据下发§6、每次运行捕获脱敏 trace 进 eval 语料§7、完成以功能探针为门禁。此阶段落地时删除CloudConnectorFormAutomation而不是扩展它。Phase 3 —— 彻底离开 category 3真正的修复是分发而非自动化。①Anthropic connector directory让 Omi Memory 被列出Claude 用户在目录里点 Connect 走标准 OAuth 同意流程——无表单、无自动化②OpenAI Apps SDK已上线Omi 已作为 ChatGPT app 被列出桌面端直接打开目录列表用户在返回后核对 OAuth grant。后端已为此成型backend/routers/mcp_sse.py支持 public PKCE 客户端与按提供商回调白名单一旦被收录Phase 1–2 就变成目录外用户的 fallback。如何接手Phase 1 跟进项是小型自包含 PR从这里起步Phase 2 从 WKWebView spike 开始签名会话能否用evaluateJavaScript端到端添加 Claude custom connector先限时验证再投入 harness 建设Phase 3 是每个提供商的清单项准备 OAuth client 元数据、提交、跟踪评审并核对目录要求是否已变化。15. Guard tests、路径覆盖与 PR 规则不变式文件的守护机制product/invariants/integrations.mdGuard tests哲学文档 检查清单就是契约本身新增连接器时优先写 functional-probe 与 harness 类测试。检查清单见 desktop/macos/docs/connector-checklist.mdPath globs触碰即触发 PR 规则desktop/macos/docs/integrations-philosophy.mddesktop/macos/docs/connector-checklist.mddesktop/macos/docs/cloud-connectors-roadmap.mddesktop/macos/Desktop/Sources/**/*Connector*desktop/macos/Desktop/Sources/**/*CloudConnector*desktop/macos/Desktop/Sources/**/MemoryExport*desktop/macos/Desktop/Sources/**/MemoryBank*desktop/macos/Desktop/Sources/**/*ReaderService*PR 规则改动涉及上述 globs 时在 PR body 中署名INV-INT-1。16. 一小时速成两条立竿见影的改动哲学文档末尾给出若你只有一小时的最小动作两条都是纯可靠性收益、零模型风险且会复合再把一个连接器从Agent 来做挪到代码写文件让一个连接器的状态改为由功能探针门禁而不是闩锁。17. 这份文档为什么存在仓库正在押注Agent 会越来越聪明而好的 harness 能让它们创造奇迹。这个赌注只有在一种情况下才是成立的把精力花在我们能控制的部分——harness、感知保真度、验证循环、eval flywheel——停止花在我们控制不了的部分——别人的 UI。一个聪明的 Agent 塞进 fire-and-forget 脚本里依然脆弱一个普通的 Agent 放进 perceive → act → verify → probe → recover 循环、由 eval 语料和可热更新的知识喂养才是稳健的。构建后者。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
到EntityManager)
