Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

20.9 KB
Raw Blame

供应商分享:受邀者与执行电脑直连

2026-10-27 用户确认的方向:能直连就尝试直连,连不上走 device-link;组所在电脑负责分配和授权, 任务内容直接在受邀者与执行电脑之间传输。本文记录本次实现及上线前仍需验证的边界。

路由

受邀者电脑为 G,分享与组所在电脑为 O,本次执行电脑为 M。G 的任务仍记录为 share:<shareId>。

  1. G 在任务启动前向 O 发 remote-agent/allocate,只传 Agent、模型和任务 ID。O 用现有组策略选电脑。 历史任务先发 direct-locate {sessionId}:O 按当前账号、分享、已批准成员、G 设备和任务查询持久位置, 返回 {deviceId} 或表示旧 O 路径的 null。位置不授予执行权限;G 必须指定该 M 重新 allocate, 确认返回同一 M 后才能发送原生会话 ID。O 即使在 30 分钟回执过期并重启后,也只为原 M 重新授权; M 不可达、被撤权或不支持所需能力时失败,不按新任务策略改选 M2。已在 O 托管的旧任务没有直连位置,继续旧路径。 重新授权后,G 经该分享原有区域的 relay 确认与原 M 的链路,再探测能力和发送历史;不凭本机缓存的 ready 状态判断 M 重启后的链路仍有效。只重开该 peer,不重连共享 WebSocket;授权等待期间用户 主动断开该链路时,本次恢复取消,不替用户重新连接。
  2. 选到同账号、支持访客隔离与短期授权的 M 时,O 先向 device-link 服务端登记 30 分钟的 委托路由,再把临时分配写入本地账本,然后经已认证的同账号链路给 M 安装内存许可。M 在安装前 向服务端核对 O 身份、授权代次和期限。O 同时把组的 Fast 策略绑定到 M 上的实际任务,最后 把分配标记为已提交;全部成功后才把本次 M 的设备 ID 回给 G。O 重启后会重试撤销未完成的分配。
  3. G 与 M 用已有 providerShare 链路建链。双方声明 provider-share-direct-v1,通过 device-link 转发 WebRTC 信令,只尝试 host ICE candidate;WebRTC 成功后,远程 Agent 的请求、事件、 文件和反向请求都经 G↔M。直连未建成或中途断开时,可靠传输层走 device-link G↔M relay, 沿用同一个运行实例和幂等序号,不把内容改送 O。 需要重新分配时,先确认 O 的分享链路;新授权提交后再确认 M 链路和能力,避免重启或重新批准后 误用旧 ready 状态、等满请求超时才回退。仍有效的缓存路由不额外等待 O,恢复只作用于当前 peer。
  4. 选中 O、第三方分享来的组成员、旧客户端、旧服务端或授权失败时,沿用现有 G↔O↔M 路径。 G 对委托的 M 在任务打开前做能力探测;探测失败或探测后打开失败时也走旧路径,避免把任务交给不可达的 M。 已返回给 G 的分配若在探测时失败,G 以授权代次向 O 尽力发送释放通知;若 M 已返回启动结果、 随后的本机准备失败,G 先关闭 M 上的 run,再等待 O 的释放回执,才打开旧路径。O 只退役匹配该代的 分配,迟到通知不得撤销同一任务的新授权。释放回执不清除历史位置;O 接受不带原生续接 ID 的 新会话回退时,才持久清除直连位置并退役旧许可。清除落盘失败时拒绝本次打开,避免重启后回到旧 M。 旧路径中的 G↔O 这一段也可能使用已有 WebRTC,但任务正文仍经过 O;它不等于 G↔M 直连。
  5. O 只收分配、续权和运行状态;G 每 30 秒向 O 报运行状态。O 重启后按持久分配恢复组负载, 超过 150 秒未报告的任务不再计作忙碌。O 每分钟检查许可有效期与访问权限。原 M 移出新任务分配组后, 已有任务仍尽力回原 M,且每次续权仍受分享审批、模型、远控开关、设备撤权和 M 本机授权约束。
  6. M 每轮只把模型和 token/金额计数作为用量回执送 O;回执有唯一 ID,O 落盘去重。 O 短暂断线时 M 在内存中重试;若 M 重启或 O 连续 30 分钟不可达,尚未送达的计数会丢失, 因此不能把该用量统计用于精确计费。M 对许可到期或撤销后才到达的已完成轮次保留最多 5 分钟 的仅计费依据;若执行器在关闭运行时未发出完成事件,或 O 的新授权已到 M、分配账本尚未提交 就发生回滚,这段用量仍可能漏记。
  7. 直连运行中的 M 故障触发既有供应商组交接时,G 向 O 请求短期换机凭证。O 只为当前有效的 G/任务/分配签发,并按组策略选下一台;同一物理 M 的所有组成员在这一轮均被排除。G 重新打开 后才把后续正文发往新执行电脑。凭证绑定受邀者和任务,失败重开可在有效期内重用;G 成功打开 后释放本机凭证。O 不因 G 的故障报告冷却 M,且请求有短期限频。受邀者可主动 请求自己任务的换机,故该请求不是 M 故障的可信证明;组健康度必须由 O 的独立信号决定。 O 接受仍有效且绑定该受邀者任务的换机凭证后,按授权代次持久清除旧 M 的任务位置并退役直连分配,避免以后重开时按旧账本 又选回故障机;新电脑尚未打开成功时,同一凭证在有效期内仍可重试。

M 重启后,已有 G 任务先经 O 为原 M重新授权,再打开同一原生会话;恢复探测不能用 O 的 在线状态替代 M。断链期间许可暂未恢复时沿用有界重试,首次直接撤权仍立即结束。授权与本机租约 到期、Stop/关闭取消之间的迟到结果不能继续派发;已经到期的句柄只结束本机资源,不自动复活。

授权

  • 启用成员模型用量比例限制时,新任务继续走 O 中转,由上游既有机制逐请求核对实时用量; 离线直连许可不具备该能力。O 上修改此策略会退役该成员已有直连许可,仍保留原 M 的历史位置, 不把原生历史迁往另一台电脑。该历史任务在策略关闭前不能重新直连;O 离线时撤权仍受原许可期限约束。 O 在提交分配后、向 G 回传前重新核对当前审批与预算等权限;提交期间限制变更时,撤销本代分配, 不沿用最初快照继续放行。
  • device-link 服务端继续负责分享与成员身份、新 G 设备登记,以及 G↔M 的 relay 路由准入。 服务端仅接受分享所在的 O 签发委托;每一跳重新验证分享、成员、G 设备、O、M 和 30 分钟许可。 同账号登录只证明 O↔M 的账号关系,不能代替分享审批或访客隔离。
  • M 本机也持有最多 30 分钟的内存许可,绑定分享、成员、G 物理设备、O 与 M 本机供应商。 授权还按 G 的具体任务 ID 与模型隔离,另一任务的模型许可不能借用。M 在建链和每次调用时复核 远控开关、供应商开放状态、成员模型范围和账号作用域;只开放 maker:remote-agent:v1,不把 G 提升成同账号主人,也不开放管理、目录和统计通道。
  • G↔M 已建立的 WebRTC 路径在中继 WebSocket 的 1012、1013 或普通重连期间保留。许可不从磁盘恢复, 客户端同时用本地绝对时间和单调时间限制直连 30 分钟,离线不能自行延长。中继和 O 可用时, 运行中的任务约每 20 分钟重新授权并经 relay 重开链路续期;续权失败后每分钟重试。G 在分配请求 发出后的 25 分钟内可复用缓存路由,29 分钟处保守停止未续权的新请求,留出约 1 分钟的时钟与网络余量。 已打开任务即使 O 暂时不可达,也不会在缓存的 25 分钟界限处提前停止。 O 的分配响应同时报告已批准许可的剩余时间;G 按单调时钟计时,续权成功才更新期限。 期限耗尽时立即结束该任务在 G 的本地工具和命令,不等待已失权的 M 回复 close,也不延长为 普通断链的两分钟恢复窗口。新建与原机恢复使用同一规则;其余任务和普通 device-link 不受影响。 G 从分配或历史授权请求发出时开始计入许可预算;能力探测、MCP 与本机执行器准备、等待 M 启动 回执都包含在内。删除或归档在这些准备阶段也会取消本次启动;已发出的上传不能撤回,但不得 继续发下一片或改走 O 重开。迟到结果只清理本次资源及对应授权代次,不得关闭同一任务的后续 启动或其他任务。回归见 roundtrip.test.ts。 旧 O 缺少剩余时间字段时沿用原 30 分钟期限;M 始终独立核对实际许可。
  • 正常切模先由 O 对原 M重新授权新模型,再让 M 切换;失败时重新确认旧模型授权。进行中的一轮 不切模。O 对分享成员模型许可、组成员配置的本机修改会立即撤销失效路由;O 不可达或刚重启且 尚无原路由内存状态时,本地策略变更对已发 M 许可的传播仍以原 30 分钟到期为上限。
  • O 收到成员暂停、删除、退出或设备撤权时,撤销服务端路由、通知 M 删除本地许可并停止运行。 O 或 M 不可达时,已建立直连的撤权最多延迟到许可到期,最长约 30 分钟。新 G 设备在此期间 不能获得许可;首次授权和续期都需要重新到达 O、M 与服务端。
  • O 的回执去重记录和 M 的待发队列各最多 20,000 条。达到上限时可能延迟或丢失用量回执, 不影响权限到期与任务正文的路由;用量页只用于观察,不能直接作为结算账本。

删除成员后的数据清理

  • O 在持久账本中记录每个成员的服务端 joinedAt,包括只使用旧中转的成员;只比较原值相等, 不比较两台电脑的时钟。暂停/恢复不改变它。删除/退出后重新批准即使复用同一 memberId, 新 joinedAt 也代表新的加入代次。O 重启或离线错过中间删除时,在发布新快照之前比较持久代次, 同一次原子写入清除旧任务位置、退役旧回执路由并排入全部旧 M 清理目标。
  • 加入代次变化或已观察到成员消失后,同成员的直连定位、分配和旧中转准入全部阻断,直到本机 受邀者索引、目录及旧中转 forgetPending 清理完成,且所有直连 M 确认 forget。M 离线时 不能通过改走旧中转绕过此门。目录清理作用域先落盘,索引删除后目录清理失败也能重启续清; 旧代次的迟到清理回执不能放行新代次。位置及加入代次均不授予执行权限,放行后每次直连仍需 新服务端许可和 M 本机验证。服务端许可也须绑定加入代次,拒绝删除后旧许可因重新批准而复活。
  • 旧账本没有成员代次时,以升级后首次权威快照建立基线,以保留未删除任务的历史;无法追溯 首次记录之前已在 O 离线期间完成的删除和重批准。成员代次不随许可过期淘汰;达到容量上限 时拒绝新增记录,不逐出仍可能有旧数据的成员。
  • 只有账本文件确实不存在(ENOENT)才建立全新账本。读取失败(含 Windows 文件占用)、JSON 或安全字段损坏时,拒绝安全查询、准入与账本写入,保留原文件;同一进程在存储恢复后可重新 完整加载,不缓存空白或部分状态。有效旧版 v1 缺少可选字段仍可迁移,但已存在的非法安全 条目或重复身份不能静默丢弃;读取超过当前容量的旧数组时保留完整清理屏障,只拒绝新增。
  • M 的受邀者会话索引同样只在 ENOENT 时初始化。其他读取错误、JSON 或已有安全字段损坏时, 拒绝依赖该索引的新委托并保留原文件;恢复后可在同一实例重试。新的直连归属与对应原生历史 索引只在落盘成功后发布,落盘失败保留既有索引。回归见 groupRelay.test.ts。
  • O 在每次直连分配前,把 (账号、分享、成员、G 设备、M 设备) 写进本地用量账本的长期清理目标。 它不随 30 分钟委托或回执宽限期过期;删除、退出成员时,O 把同成员的目标标为持久待通知, 包括曾执行任务、后来退出组的 M。原有 G→O→M 中转任务仍由 O 的受邀者会话索引向组成员发清理通知。 两类目标合起来覆盖 O 本机、旧中转 M 和直连 M。
  • O 通过已认证的同账号设备链路向每台直连 M 发送不含任务正文的 forget,失败保留队列,启动时和 此后定期重试;只有 M 确认完成后才持久划掉待通知。M 按原委托时持久保存的 O、G、分享和成员 精确匹配,先撤掉该受邀者的旧任务许可并停止运行,再删除直连 guest-home、影子工作区、 上传附件与本机托管会话记录;同一受邀者的旧中转任务目录按各自记录保留。 清理失败不会回成功。若 M 从未收到委托且没有该受邀者的直连任务或目录,空清理可幂等确认。
  • 同一成员重加入时,O 在新服务端授权和新 delegate grant 之前先完成所有旧目的地 的待清理;M 离线或清理失败时该成员暂不能运行。每个长期目标还有持久递增的 cleanupEpoch:旧通知晚于新授权到达时,M 不得清除更高代的许可或新任务;旧通知的丢失回执 可幂等重试。O 收到旧通知的迟到 ACK 也不得删掉新一轮待清理。
  • 清理目标和待通知共用账号作用域并限制为 20,000 个目标;达到上限时拒绝新的直连分配,避免 接受无法追踪清理目的地的任务。升级读取旧用量文件时,从仍在回执宽限期内的直连路由补出目标; 更早、旧版本没有记录的直连目的地不能追溯。旧 M 不识别新 forget 时,O 保留待通知并继续重试。

兼容与隐私

  • allocate、direct-locate、delegate、direct-status、direct-release、direct-switch、direct-usage、 forget/directGuest 和 directGuestExecution 是可选远程 Agent 协议扩展; 新任务缺少所需能力时走旧路径。历史任务无法确认位置或重新授权原 M 时失败,不把旧原生 ID 发到猜测的电脑。 旧请求格式与旧中转保持兼容。服务端新增的委托路由是可选 REST 接口与 Redis 短期键,不改变数据库历史迁移。
  • 分享直连信令要由服务端 hello-ack 显式声明支持;旧服务端缺少声明时不尝试新的 WebRTC 协商。 新版节点回传的信令拒绝只按对应 id 处理,不拆已就绪的分享可靠链路。滚动升级期间若跨实例路径仍经过 旧节点,拒绝可能没有错误回传,信令会超时退避;可靠帧也可能在重试超时后拆链。跨实例拒绝的及时回传 要等全部 relay 实例升级后才有保障。 普通 1012/1013 重连期间已建立的 WebRTC 可继续传输。若服务端回滚到不认识委托路由的版本, 随后的中继帧或 M 的定期核权会使该直连任务失败,受邀者需重新打开任务走旧路径;不能承诺它持续到 本地许可到期。回滚前应先让正在使用的委托任务结束,或准备处理这类失败。
  • 受邀者界面继续只显示匿名组状态,不显示 M 的名称、设备 ID 或组名单。但直连技术上会让 参与连接的 G 知道本次 M 的设备 ID 和 WebRTC host candidate 中的局域网地址;不能把界面匿名 误写成网络层匿名。信令、许可与任务正文不写入诊断日志。
  • 组里来自另一账号的 M 仍按既有逐人转分享同意和 O 中转工作。本轮不把 O 的许可扩展成替 第三方主人授权的能力。跨区域分享沿用所在区域的服务端认证与 device-link 连接。
  • G 或 M 的 Cindy 退出会关闭直连。O 退出不关闭已建立的 G↔M 路径,但没有 O 就不能首次分配或续权。

验收与上线门槛

Desktop 跨网段 mDNS 寻址

2026-10-28:Desktop 的 DesktopCaptureWindow(mode: direct) 在加载页面之前,仅为这个隐藏的 数据窗口设置 webContents.setWebRTCIPHandlingPolicy('default_public_and_private_interfaces')。 Electron 官方策略 使用操作系统默认路由的接口,并允许暴露该接口的地址。本机隔离实验确认 Electron 42.11.12 / Chromium 148.0.7778.280 的默认策略生成 .local host 候选,该窗口策略生成可直接寻址的 IPv4 UDP host 候选;显式设置 default 仍生成 .local,default_public_interface_only 在本机没有候选。 这解决了路由本身可达、但跨子网不能解析 mDNS 时的寻址缺口,不要求填写 IP。

  • 实现只使用 Chromium 的候选生成,不自行枚举网卡、补造候选、解析或重写本机/远端 SDP; 不改 ICE ufrag/password、DTLS fingerprint、信令身份或短期许可。原有 128 KiB SDP、16 个 peer、 15 秒协商预算继续生效。非法/超限描述仍由现有 bridge 和浏览器拒绝。
  • IP 只提供寻址,不授予访问权限。信令仍只发给已有授权链路中的 peer,分享、账号、成员、 设备和许可检查不变;同账号设备使用同一数据窗口,也受此策略影响。不增加 STUN/TURN、 全局 Chromium 开关、摄像头/麦克风权限或防火墙规则;文件与桌面音视频窗口保持原策略。
  • 对端能够看到默认路由接口的真实地址,即使两端原先只交换 .local;这可能是 VPN、虚拟网卡, 或直接配置在接口上的公网地址。Cindy 不额外公开其它网卡,但默认路由不一定是能到达对端的 那块网卡。多网卡/VPN 下其它接口可达而默认接口不可达时,直连可能退回 relay;本轮没有 用遍历所有网卡的方式扩大地址暴露。SDP 和 IP 不写入应用诊断日志。
  • Mobile 继续使用原有 WebView runtime,没有此 Electron API;桌面一侧更新后,ICE 可能通过 peer-reflexive 候选让另一侧连通,但不能据本机实验承诺所有 Mobile/NAT/VPN 组合都成功。 故障半径仍是单个 peer 的直连尝试:无候选、不可达或超时继续走该 peer 原有 relay,既不重启 共享 WebSocket,也不重放业务命令、重分配 M 或影响其他 peer。
  • 隐藏传输窗口的崩溃由其所属 runtime 清理,按 Main 登记的真实 WebContents 身份隔离; 不进入主界面的全局退出与数据库清理链。共享直连进程崩溃会使该进程承载的全部直连通道 回退中继,但不能关闭共享 WebSocket。主界面 renderer 的致命退出规则保持不变。

可复现命令:node scripts/provider-share-direct-smoke.mjs --electron-mdns。脚本在唯一 TEMP 目录构建最小应用与两套独立 profile,直接运行生产 desktopDirectRuntime → DesktopCaptureWindow → preload → startDirectLinkHost → createDirectRtcRuntime;不启动或读取正在运行的 Cindy。 它只在实验信令中把 .local 名称换为随机不可解析名称,禁止借助同机 mDNS 解析把基线测绿。 脚本仅记录候选数量/类型、ICE 状态和测试字节摘要,不打印 SDP、网卡名或地址。

本机实测:默认策略双端 16 秒后仍为 new;新策略双端 UDP host↔host;只更新 offerer 或只更新 answerer 时均通过 host/peer-reflexive 建链,三个成功组合均双向各校验 256 KiB;强制无候选 时保持未连接;非法和超过 128 KiB 的远端 SDP 被拒绝,已有健康 peer 仍可传输。 窗口单测覆盖加载前设置、只作用于 direct、权限仍拒绝、已有 desktop/files 隔离;真实 relay 回退与授权用下述 Chrome 夹具和现有 device-link 测试验证。多网卡物理路由、两台 Windows 跨 VLAN、macOS、Linux 与 Mobile 的实机行为尚未验证;本机两个独立 Electron 进程的实验不代表 这些环境已经验收。

分享与执行验收

本轮用真实 Chromium WebRTC、生产 DeviceLinkClient 和本地三端夹具做传输烟测;夹具中的 O 模拟分配与鉴权,不等于运行完整的供应商组宿主:1.25 MB UTF-8 任务正文只经 G↔M,O 不收到 正文;1012 中继断开时原直连完成请求;直连断开而 relay 恢复后 G↔M 只执行一次。服务端路由 与授权测试覆盖未登记设备、非 O 签发、许可到期和信令限制。

正式启用前仍须在三台真实电脑及真实账号上验证:分享申请和新设备登记、跨区域、真 Agent 的 附件/工具/长任务、成员暂停与撤权、O 和 M 分别重启、两位受邀者并发、双模式界面匿名呈现。 客户端与服务端需按协议兼容规则先后部署;缺少真实账号 环境的测试不能冒充这项验收。