Friend 项目 JIT First-Open 运行时解析从全量 eager 处理到按需派发的架构与实现【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend导读本篇技术指南以 backend/docs/jit-first-open-runtime.md 为核心骨架系统讲解 Friend 开源仓库中“对话捕获后处理”的 Just-In-TimeJITfirst-open 运行时设计包括后端权威的 rollout 准入决策、token 栅栏租约token-fenced lease的事务化状态机、first-open 派生效果的延迟派发以及 macOS 主动proactivity激活边界上的触发器快照与单次 agent 轮询机制。读者读完后将掌握这套系统的准入判定矩阵、幂等派发协议、失败回退路径以及代码中对应的实现文件与关键调用链可直接用于理解或复现同类“把昂贵派生工作从捕获路径剥离到按需执行”的服务端设计。一、设计动机为什么捕获路径需要“按需处理”Friend 的核心产品能力是“AI 看见你的屏幕、听见你的对话并给出建议”。每一次对话捕获之后传统的全量 eager全急切处理会在捕获瞬间完成所有派生工作生成摘要、建立检索索引、分配文件夹、向 App 生态 fan-out、自动更新目标进度。这对每一次捕获都意味着大量昂贵的 LLM 调用与写放大。JIT first-open 运行时的核心思路是把最昂贵的派生工作从捕获路径上剥离延迟到“用户第一次打开这条对话”时再按需派发。文档明确给出的准入边界是Conversation capture remains legacy full-eager unless the authenticated backend rollout authority returns a known enabled decision and the persisted source is supported. Clients cannot supply a cohort or enrollment flag.这句话包含三个关键约束准入权只在后端只有经过认证的后端 rollout authority 返回“明确启用enabled”的决策捕获路径才进入 JIT 模式来源必须受支持持久化的对话来源source必须在受支持集合内客户端无权自报客户端不能携带任何 cohort 或 enrollment 标志来参与准入——这从根本上杜绝了客户端配置污染服务端优化路径。从源码看受支持的来源集合定义在 backend/utils/jit_first_open_policy.pySUPPORTED_SOURCES frozenset({desktop, mobile, phone, omi, web, windows})客户端来源会被归一化到两种 tierdesktop含desktop、windows、web或mobile其余定义于 backend/utils/jit_first_open_policy.py 的FirstOpenClientTier枚举。二、后端权威准入三态决策、kill switch 与 allowlistJIT 模式的“开关”由后端独立模块 backend/utils/jit_rollout.py 全权持有。它是一个“只读控制面决策”不接收除 Firebase 认证 UID 之外的任何客户端输入见该模块开头的 docstring。2.1 三态语义所有标志评估结果收敛为TriStatebackend/utils/jit_rollout.py状态含义enabled明确启用允许 JIT 工作disabled明确关闭unknown提供方超时、配置缺失、响应畸形等不确定状态2.2 标志与决策优先级源码中定义了三个关键标志键backend/utils/jit_rollout.pyjit-processing-v1暴露exposure标志决定非 allowlist 用户是否进入 JITjit-processing-kill-switch-v1运维级 kill switch唯一能撤销所有人包括 allowlist准入的标志两个已退役的准入键jit-processing-ledger-migration-v1与daily-memory-sweep-v1仅保留名称供测试证明其不再授权工作。决策优先级在_effective_decisionbackend/utils/jit_rollout.py中实现规则可归纳为kill switch 为enabled→ 一律disabledkill switch 只能移除权威永远不能授予权威allowlist 用户 →enabled允许名单JIT_ADMISSION_ALLOWLIST两个 UID 的代码级白名单绕过暴露标志且在 PostHog 宕机时依然放行唯一的例外是上述“明确启用的 kill switch”普通用户暴露标志enabled→ 启用disabled/缺失 → 关闭unknown→ 保持未知并 fail-closed。关键设计点是unknown状态永远不能授权工作因此提供方故障只会延长“保守关闭”的行为而不会放大授权。2.3 缓存与超时JITRolloutAuthoritybackend/utils/jit_rollout.py为每个 UID 维护带 TTL 的 LRU 缓存完整已知的决策按默认 20 秒 TTL 缓存上限 30 秒unknown快照只缓存 5 秒UNKNOWN_JIT_ROLLOUT_CACHE_SECONDS——足够让“标志缺失的暗态集群”不为每条对话定稿都付一次未缓存调用也足够在提供方恢复后数秒内观察到结果单次 PostHog 决策调用超时 2 秒DEFAULT_JIT_ROLLOUT_TIMEOUT_SECONDS。PostHogJITFlagProviderbackend/utils/jit_rollout.py通过一次get_feature_variants调用同时解析暴露标志与 kill switch同一响应、无第二次网络往返并做了同 UID 在途请求合并in-flight coalescing防止冷缓存扇出放大调用。同步调用方对话定稿线程、first-open worker通过resolve_jit_rollout_syncbackend/utils/jit_rollout.py路由到专用控制循环线程避免跨事件循环共享 asyncio 原语。2.4 准入的计划形态backend/utils/jit_first_open_policy.py 的resolve_authorized_first_open_plan/resolve_first_open_plan把决策收敛为一个全有或全无的FirstOpenPlansummary_eagerTrue, # 摘要仍在捕获时生成 retrieval_index_eagerTrue, # 检索索引仍在捕获时写入 folder_assignment_on_first_openTrue, # 文件夹分配延迟到首次打开 app_fanout_on_first_openTrue, # App fan-out 延迟到首次打开这里体现了“既不是全 eager、也不是全 lazy”的精确取舍摘要创建与检索索引仍然保留在捕获路径上保持列表与轻量检索的即时可用性只有昂贵的派生效果文件夹分配、App fan-out被推迟。同时策略模块刻意设计为纯策略缝pure policy seam不直接读 PostHog/Firebase/客户端状态便于测试且防止陈旧客户端配置演变成数据丢失路径。三、事务化 first-open 状态机pending / in_flight / complete当准入计划defer_derived_work为真时捕获路径不再立即执行派生效果而是事务性地在对话文档上写入jit_first_open.statepending把工作“欠下”。这一持久化义务durable obligation由 backend/database/first_open_obligations.py 实现。3.1 状态与效果模型状态枚举为pending/in_flight/completebackend/utils/jit_first_open_policy.py效果集合为两个folder_assignment与app_fanoutbackend/database/first_open_obligations.pyFIRST_OPEN_EFFECTS (folder_assignment, app_fanout)每个效果在文档内独立记录状态pending/in_flight/complete与app_receipts回执义务记录包含version、attempt尝试次数、account_generation与source_generation来源代数栅栏、lease_token与lease_expires_at租约到期时间。3.2 初始化写入initialize_first_open_workbackend/database/first_open_obligations.py在 Firestore 事务内完成读取对话文档与控制状态若已存在义务则校验 generation 是否匹配否则写入jit_first_open: { version: 1, state: pending, attempt: 0, account_generation: control.account_generation, source_generation: control.source_generation, effects: {effect: {state: pending} for effect in FIRST_OPEN_EFFECTS}, updated_at: firestore.SERVER_TIMESTAMP, }其中_authoritybackend/database/first_open_obligations.py在同一事务内读取用户文档、账户删除标记与memory_state/apply_control控制文档任何一项缺失或删除状态阻断访问都会让 authority 返回None从而 fail-closed。3.3 Token 栅栏租约claim_first_open_workbackend/database/first_open_obligations.py实现“token 栅栏租约”每次成功 claim 生成一个全新 UUID 作为lease_token并设置lease_expires_at now max(30, lease_seconds)默认 300 秒并发/重复打开不会重复认领活动中的 claim若状态为in_flight且租约未过期claim 直接返回None失败返回 pendingfinish_first_open_work(succeededFalse)时状态回落pending除非所有效果已完成则置complete并清空租约字段过期租约可被回收in_flight但租约已过期的记录允许新的 claim 抢占完成complete_first_open_effect/finish_first_open_work只接受当前 token旧 token 无法篡改他人持有中的工作。finish_first_open_workbackend/database/first_open_obligations.py在事务内把所有效果都 complete 才把整体状态置complete否则回落pending保证“部分完成可续跑”。四、派发执行detail read 认领并派发效果文档描述的派发模型是“A detail read claims a token-fenced lease and dispatches those effects.”——即当用户真正打开detail read某条 JIT 对话时读取路径会去认领一个 token 栅栏租约并派发此前欠下的效果。实际执行体在 backend/utils/conversations/jit_first_open_worker.py 的run_first_open_derived_work(uid, conversation_data, token)4.1 每次提交前的重授权worker 的关键特征是每一步写提交前都重新检查活体权威live authority。模块内定义了两个闭包backend/utils/conversations/jit_first_open_worker.pyauthorize(effect)调用resolve_authorized_first_open_plan(..., force_refreshTrue)强制刷新 paid-boundary 决策再通过conversations_db.first_open_effect_is_authorized(uid, conversation.id, token, effect)校验“效果尚未完成 持有当前 token generation 匹配”任何一环失败即抛RuntimeError(first-open authority suspended before ...)complete(effect)先 authorize再complete_first_open_effect成功后记录record_jit_first_open(eventcomplete, effecteffect)失败则记录fail并重抛。这正对应文档中的“Outstanding work re-reads uncached paid-boundary rollout/kill authority before each provider call and again before every result, usage, folder, or receipt commit.”——即每次 provider 调用前、以及每次结果/用量/文件夹/回执提交前都要重新读取未缓存的 paid-boundary rollout/kill 权威。4.2 效果一文件夹分配对应 backend/utils/conversations/jit_first_open_worker.py若效果未完成先授权然后读取用户文件夹缺失则初始化系统文件夹若对话已有结构化数据基于 title/overview/category 调用assign_conversation_to_folder计算目标文件夹受CONVERSATION_FOLDERusage 追踪保护通过commit_first_open_conversation_patch持久化folder_id通过commit_first_open_folder_count刷新该文件夹的conversation_count基于索引注册表FIRST_OPEN_FOLDER_CONVERSATION_COUNT_QUERY的 count 查询最后complete(folder_assignment)。4.3 效果二App fan-out对应 backend/utils/conversations/jit_first_open_worker.py。核心逻辑是调用 backend/utils/conversations/process_conversation.py 的trigger_conversation_apps并注入三个“可续跑”回调resumable_result_commit每个 App 结果生成后立即持久化commit_first_open_app_result写入app_receipts[app_id].result_persistedTrue崩溃后可从中断处续跑而不是重新付一次 LLM 调用resumable_usage_commit结果持久化后记录 usagecommit_first_open_app_usage写入usage_persistedTrue补全“结果已落库但用量未记”的崩溃尾部worker 开头专门有一段“repair that suffix”的修复循环见 backend/utils/conversations/jit_first_open_worker.pyresumable_effect_authorizer每次执行 App 前重新authorize(app_fanout)。complete_first_open_effect对app_fanout有额外的完整性校验backend/database/first_open_obligations.py只有apps_results中每个 app 的 receipt 同时具备result_persistedTrue与usage_persistedTrue效果才被允许标记 complete。4.4 已删除对话若对话被判为 discardedworker 直接跳过所有派生效果仅把所有未完成效果标记 completebackend/utils/conversations/jit_first_open_worker.py避免对噪音捕获浪费任何付费调用。4.5 目标自动更新被移出 JIT 特性集文档明确强调“automatic goal updates are removed from the JIT featureset entirely; goals change only through manual or explicit actions”。源码中有两处印证backend/database/first_open_obligations.py 注释自动目标进度更新被排除在 JIT 特性集之外目标只通过显式用户行为改变历史上持久化的goal_progress效果行会被_effects归一化掉完成永远不等候该退役效果backend/utils/jit_first_open_policy.py 注释同样声明“自动目标进度更新不属于 JIT 特性集”。对照 backend/utils/conversations/process_conversation.py 的update_goal_progresslegacy eager 路径使用有界 Redis 锁做幂等而 first-open 工作路径改用持久化 per-goal 事件TTL 过期不会重复提交目标变更——两种机制并存但职责分离。五、失败语义与兼容回退5.1 在途付费请求的处理文档给出一个非常精确的语义A kill that changes while a provider request is already in flight cannot retract that paid request, but its result is suspended and no mutation commits.即已发出的付费请求无法撤回但其结果被悬挂suspended且任何变更都不会提交。这正是 4.1 节“每次提交前重新授权”机制的价值——authority 一旦在请求期间变化后续的 commit 事务会因为_live_effect校验失败而返回Falseworker 随即抛错效果保持 pending 可重试。5.2 Kill/off/unknown 从不排空持久化工作文档声明 “Kill/off/unknown never drain persisted work.”——当权威为 kill/off/unknown 时持久化的欠账不会被排空执行而是停留在 pending 等待权威恢复。代码侧claim_authorized_first_open_workbackend/database/first_open_obligations.py先调用outstanding_first_open_work_permitted内部强制刷新 paid-boundary 决策只有defer_derived_work为真才允许认领天然实现“未授权不排空”。5.3 回退路径权威/来源/持久化初始化未知或不可用→ 捕获路径运行既有的 eager pipelinebackend/utils/jit_first_open_policy.py 的异常兜底feature_enabledFalse以及 backend/utils/jit_first_open_policy.py 的kill_switch/rollout_disabled/unsupported_tier/unsupported_source分支全部返回全禁用计划legacy desktop 延迟路径保持不变作为兼容回退文档原文”The legacy desktop deferred path is unchanged and remains the compatibility fallback“。相关兜底逻辑可在 backend/utils/conversations/process_conversation.py 的should_defer_desktop_processing导入处看到端倪说明桌面端存在既有的延迟处理机制JIT 不与它冲突。状态机转换本身由纯函数transition_first_openbackend/utils/jit_first_open_policy.py定义并单测覆盖open只认领pendingfailed使in_flight回到pendingsucceeded使in_flight进入complete。六、macOS proactivity 激活边界文档第二部分聚焦 macOS 桌面客户端的“上下文进入”运行时。核心链路是先读 rollout 决策再读触发器快照本地镜像替换后进行计划planned评估与单次 agent 轮询无计划匹配时才允许环境ambient通道介入。6.1 入口一GET /v1/jit/rollout-decision路由定义在 backend/routers/jit_rollout.pyrouter.get(_DECISION_PATH, response_modelJITRolloutDecisionEnvelope) # _DECISION_PATH /v1/jit/rollout-decision async def get_jit_rollout_decision(uid: str Depends(get_current_user_uid)) - JITRolloutDecisionEnvelope: decision await resolve_jit_rollout(uid, stageJITDecisionStage.READ_ONLY) return JITRolloutDecisionEnvelope.from_decision(decision)响应封装为JITRolloutDecisionEnvelopebackend/routers/jit_rollout.py字段包括rollout、kill_switch、effective、reason、error_class、cache_hit、cache_ttl_seconds以及可选的budget_contract_version由环境变量OMI_JIT_PROACTIVITY_BUDGET_CONTRACTjit-cloud-qa-v1控制。该端点只读、需要认证get_current_user_uid依赖。文档规定off、unknown 与 kill 状态保持 legacy context-bucket 评估器不变即不进入 JIT proactivity。6.2 入口二GET /v1/jit/trigger-snapshot路由在 backend/routers/jit_rollout.py。特性只读且不可缓存显式设置response.headers[Cache-Control] no-store只在被 admit 的 owner 上返回完整快照先按READ_ONLY阶段解析决策permits_work为假时返回_disabled_trigger_snapshot内容无关、completeFalse、failure_reasonrollout_not_enabled尾部权威栅栏阻塞式全量扫描完成后用force_refreshTrue重新解析未缓存决策若在扫描期间 flag/kill 翻转则同样返回禁用快照对应文档“The backend reads the trusted ledger head again after exhausting the query”。6.3 穷举式快照与不可复用回执快照读取实现于 backend/utils/memory/jit_trigger_snapshot.py 的read_authoritative_trigger_snapshot以 memory-v3 可信账户代trusted account generation作为栅栏先行读取 state head查询全部kind trigger的 memory item上限MAX_AUTHORITATIVE_TRIGGERS 500逐行校验 uid、memory_id、account_generation 与身份一致性任何畸形行、混合代、查询失败、行数超限、action 缺失都会让整个快照completeFalserow_invalid、query_failed、trigger_limit_exceeded、trigger_limit_exceeded、generation_unavailable、authority_changed等 failure_reason使环境通道无法基于不完整视图抢先工作查询耗尽后重读可信 ledger head若 generation/head/sequence 任一变化回执标记不完整快照携带snapshot_revision由_revisionbackend/utils/memory/jit_trigger_snapshot.py对规范行序、身份、condition、action、wakeup budget 与完整 policy 做 SHA-256 绑定——内容变化后旧回执不可复用已证明空的状态头owner 从未初始化 memory v3会返回completeTrue的空 watchlist 及确定性 revision_empty_watchlist_revision但空必须是“经证明”的头部读取失败或畸形仍保持 incomplete。快照还携带budget_day与budget_timezone来自用户档案的 IANA 时区backend/utils/memory/jit_trigger_snapshot.py让客户端在预留事务同一时区窗口内做预算而不是悄悄用宿主时区。6.4 本地镜像替换与计划触发器评估文档描述 macOS 侧行为事务性整体替换macOS 用完整快照原子替换本地镜像空快照删除全部镜像触发器陈旧/冲突回执无法胜出stale/conflicting receipts cannot win计划触发器本地评估从有界的当前事实与元数据中评估 planned triggers确定性的胜出者先获取 token 栅栏 wakeup 租约再执行恰好一次、纯文本、全 agent 轮exactly one text-only full agent turn展示成功或失败都会结算持久化回执过期 claim 可重试无连续视觉、无历史关键词召回该轮不执行 continuous vision pass也不做 historical keyword recall。6.5 ask 模式与内核硬拒绝It submits the immutable owner authorization to every agent-runtime boundary inaskmode; the kernel hard-denies non-read-only tools on the JIT service surface.即每次 agent-runtime 边界都携带不可变的 owner 授权并以ask只读询问模式提交JIT 服务面上的内核硬拒绝非只读工具。这保证了 JIT 主动行为永远是只读、无副作用的。6.6 环境ambient通道与 nano triage计划通道让位给 ambient 通道的前提是“Only after a complete snapshot proves there is no planned match or ambiguous planned selector may the ambient lane proceed.”——只有完整快照证明了没有计划匹配或没有歧义的计划选择器时ambient 通道才能推进。ambient 的预算语义文档与源码交叉印证材料变化对稳定 bucket 身份做规范化事实的持久化比较才算 material change事实顺序、截图 ID、捕获时间、仅 revisit 的版本抖动version churn不会再消耗一次 nano 尝试既有权威保留legacy context-bucket 的 notify-worthiness、验证证据、投递预算、workstream 上下文与 CandidateSink 仍是 ambient 的权威模型无关门控先行先跑一个 model-free gate最多再跑一次 nano triage每日八次硬上限nano 尝试有持久化的一天八次上限包括畸形/失败尝试。代码侧可见 backend/utils/memory/jit_trigger_contract.py 的JIT_AMBIGUOUS_NANO_TRIAGES_PER_DAY常量与ambiguous_nano_triages_per_day运行时策略字段同时 backend/utils/llm/model_config.py 显示desktop_proactive_extraction、conv_folder、conv_discard等轻量任务默认映射到gpt-5-nano印证“nano 级廉价分类通道”的实现形态审批后可购买一次纯文本全轮approval 通过同一投递账本delivery ledger购买一次 text-only full turn并持有一次每上下文one-per-context的 ambient wakeup claim共享观察连续性键planned 与 ambient 的 claim 共享 observation continuity key对同一证据二者不能同时投递结果约束ambient 的task_candidate输出必须引用 CandidateSink 毕业graduate的已验证可操作事实后才可展示planned 输出只接受 insight 或 silence边界约束两条通道都不匹配历史意图词汇、都不创建被动永久触发器、都不启动连续模型/视觉循环。七、路由契约与启动校验JIT 的 HTTP 面由 backend/routers/jit_rollout.py 承载共四个端点方法与路径响应模型说明GET /v1/jit/rollout-decisionJITRolloutDecisionEnvelope只读准入决策GET /v1/jit/trigger-snapshotJITTriggerSnapshotEnvelope穷举触发器快照no-storePOST /v1/jit/trigger-feedbackJITTriggerFeedbackEnvelope显式、内容无关的用户反馈snooze 等在 rollout 关闭/被杀时依然可用不做任何匹配/模型工作POST /v1/jit/proactivity/reservationsJITProactivityReservationEnvelope工作前立刻做跨设备预算预留以PAID_BOUNDARY阶段强制刷新决策validate_jit_rollout_contractbackend/routers/jit_rollout.py在应用启动时断言这些路径恰好暴露一个、必须携带get_current_user_uid认证依赖、方法集合与响应模型必须精确匹配——防止工厂装配时遗漏、去认证或改动只读契约。这一契约在 backend/route_policy_manifest.yaml 中亦有登记。八、测试与验证证据仓库为这套运行时提供了密集的测试覆盖可作为实现事实的验证入口backend/tests/unit/test_jit_first_open_policy.py策略缝的全禁用/启用/来源与 tier 判定矩阵backend/tests/unit/test_jit_rollout.py三态决策、kill switch 优先级、allowlist 韧性、缓存 TTLbackend/tests/unit/test_conversation_jit_processing.py 与 backend/tests/unit/test_conversation_first_open_work.pyfirst-open 派发与效果执行backend/tests/unit/test_first_open_effect_resume.py崩溃后效果续跑resume语义backend/tests/unit/test_jit_trigger_snapshot.py触发器快照的穷举性、revision 绑定与失败模式backend/tests/unit/test_jit_rollout_metrics.py决策遥测固定字段、无内容负载backend/tests/routers/test_conversation_first_open_dispatch.py路由派发链路。遥测方面决策事件通过record_jit_rollout_decision见 backend/utils/metrics.py 中对应的 JIT 记录函数与record_jit_first_open上报日志明确约束“只含固定字段、有界绝不携带 UID、prompt、memory、transcript、OCR、图片、URL 或异常文本”backend/utils/jit_rollout.py与整个 JIT 表面“内容无关content-free”的隐私基调一致。九、总结Friend 的 JIT first-open 运行时是一个典型的“后端权威 持久化义务 可重入派发”架构准入收敛客户端永远不能自报 cohort三态决策 kill switch 双 UID allowlist 由后端独占unknown一律 fail-closed成本精确分层摘要与检索索引保持 eager文件夹分配与 App fan-out 延迟到 first-open目标自动更新整体移出 JIT 特性集可恢复的派发token 栅栏租约 事务化效果回执result_persisted/usage_persisted 每次提交前重授权崩溃、并发打开、过期租约都能安全续跑或回收在途付费请求的结果只会被悬挂而不会误提交macOS 主动边界穷举快照 revision 绑定 不可缓存 尾部权威栅栏保证本地镜像只能从完整快照整体替换planned 通道持有 token 栅栏 wakeup 租约且只做单次纯文本全轮ambient 通道受 model-free gate、单次 nano triage、每日八次硬上限与共享观察连续性键约束双方共享“内容无关、只读、无连续模型/视觉循环”的硬边界。对需要为高成本后处理设计“捕获时轻量、打开时按需”架构的开发者而言本仓库的 backend/database/first_open_obligations.py、backend/utils/conversations/jit_first_open_worker.py、backend/utils/jit_rollout.py 与 backend/utils/memory/jit_trigger_snapshot.py 四份文件构成了一个可以直接研读的完整参考实现。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考