Cua Driver 会话生命周期重构从隐式 Session 到按调用捕获的 RFC 3007 深度解读【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua本文基于仓库内已接受的 RFC 3007rfcs/3007-cua-driver-lifecycle-sessions.md 展开。该 RFC 将 Cua Driver 的会话session从生命周期 永久捕获模式耦合的旧模型重构为生命周期归会话、捕获模式归单次调用、权限归可信运行时的新模型普通调用无需显式start_session即可获得稳定的隐式会话move_cursor首次即唤醒彩色光标escalate_session与会话级capture_scope被逐步淘汰。读完本文你将掌握新会话 API 的语义start_session/get_session/list_sessions/end_session、隐式会话的创建与归属模型、单次调用捕获目标的授权路径以及分两阶段的兼容迁移策略并能对照仓库源码逐条验证设计落地。背景与动机旧会话模型的两类职责耦合在 RFC 3007 之前Cua Driver 用一个会话对象同时承担两类彼此无关的职责生命周期状态光标身份cursor identity、录制recording、每次运行的配置、清理cleanup、遥测永久性的窗口 → 桌面捕获过渡通过capture_scopeauto|window|desktop与escalate_session表达。这种耦合产生了三类可复现的故障显式启动依赖Agent 可能忘记调用start_session导致彩色光标从未初始化后续动作附着到另一个会话不可逆的升级auto会话一旦调用escalate_session就永久失去窗口级工具调用方必须结束会话并换新 ID 才能恢复窗口行为这一限制此前由 PR #2857 固化在文档中而若添加反向过渡状态机只会更大捕获与生命周期仍然纠缠授权边界缺失旧捕获门控只在能解析到会话时才执行未携带公开会话的调用可以绕过 capture-scope 状态——尽管它仍然通过硬性不变量、托管策略、用户策略、所选权限档案与资源适配器。因此会话捕获状态不适合作为授权边界。RFC 3007 的结论是会话应当给调用方提供稳定的运行身份与可靠的清理捕获形态属于正在执行的动作而权限属于接纳该动作的可信运行时或已认证连接。术语体系构建新模型的最小词汇表RFC 精确定义了以下概念后续所有设计均建立在其上术语含义生命周期会话Lifecycle session单次 Agent 运行的运行时状态拥有光标身份与呈现、录制、按运行配置、清理、遥测与空闲过期。可信所有权命名空间Trusted ownership namespace会话身份在其中唯一、可解析的运行时代或宿主租约同一操作系统用户账户范围太宽不足以充当命名空间。已认证传输租约Authenticated transport lease宿主证实的连接生命周期获得一个默认隐式会话可匹配单个 socket 或 stdio 进程也可在可信宿主认证并维持租约时跨 socket 重连存活。隐式会话Implicit session会话必需调用未提供公开会话名时运行时为传输租约生成的会话。显式会话Explicit session携带调用方提供的公开名称的会话公开名只是某一可信命名空间内的映射键与标签。授权上下文Authorization context用于授权动作的不可变权限档案、策略绑定、授权grants等可信输入由当前运行时或已认证动作连接提供生命周期会话不选择它。捕获形态Capture modality单次观察或动作所选用的窗口定向或桌面定向适配器及坐标系。会话必需调用Session-requiring call使用光标呈现、录制、可变按运行配置或其他会话所属资源的调用纯管理或无内容健康读取无需创建会话。现状盘点旧公开契约与既有实现RFC 3007 明确记录了当前旧公开会话契约包含四个工具工具当前行为start_session需要公开 ID存储capture_scopeauto|window|desktop。escalate_session将auto会话永久移动到桌面作用域。get_session_state返回某 ID 的捕获策略与有效捕获作用域。end_session结束会话并执行清理。RFC 指出该契约把升级描述为永久行为并要求调用方结束会话、用新 ID 重启才能恢复窗口作用域。实现位于 session_tools.rslibs/cua-driver/rust/crates/cua-driver-core/src/session_tools.rs公开定义在 session.rslibs/cua-driver/rust/crates/cua-driver-contract/src/session.rs捕获门控在 capture_scope.rslibs/cua-driver/rust/crates/cua-driver-core/src/capture_scope.rs。在仓库现有实现中可逐条印证旧模型的痕迹session_tools.rs中的EscalateSessionTool仍要求公开sessionID 与reasonescalate_session失败会返回desktop_scope_disabled、desktop_already_active等结构化错误码其契约描述已明确标注 Deprecated compatibility tool for legacy capture-scope sessions见 contract/src/session.rs 的escalate()capture_scope.rs的SessionCaptureScope::effective_scope()仍实现auto → desktop_unlocked ? Desktop : Window的旧有效作用域推导同时session_tools.rs已经包含GetSessionTool与ListSessionsTool的实现——说明仓库当前正处于向新契约过渡的中间态get_session、list_sessions已在实现层就位get_session_state仍作为兼容别名存在。RFC 还回顾了历史演进PR #1798 引入调用方声明的会话身份、start_session/end_session与空闲 TTL 清理PR #2329 把捕获作用域从持久全局设置改为不可变的按会话策略并引入单向升级PR #2857 固化结束会话换新 ID的恢复方式PR #2550 落地 RFC 2549 的信任边界PR #2616 简化权限档案并增加脱敏会话名徽章PR #2677 将光标上下文移入独立渐隐的会话徽章。RFC 3007 正是把这些分散决策收敛为一套完整的目标契约。新模型九大设计支柱1. 生命周期选择与授权彻底分离每条被接纳的动作解析两个相互独立的输入authenticated action connection - authorization context call or transport default - lifecycle session随后运行时通过规范授权栈评估该动作。选择、命名、重连、省略、列出或结束生命周期会话都不能改变授权上下文。实现可以为诊断存储授权来源的无内容引用但绝不允许通过公开会话名反查 grants、审批状态、权限档案或能力清单。2. 用宿主与传输租约作为所有权模型隐式会话所有权分两层trusted runtime generation or host lease └── authenticated transport lease └── implicit lifecycle sessionMCP over stdio租约通常持续到 MCP 进程或 stdio 连接结束直接 SDK租约持续到宿主暴露的可信会话或连接对象结束守护进程或可重连 HTTP 服务可信宿主认证返回调用方后可让租约跨 socket 重连存活裸 socket 断开仅当该 socket 是租约所有者时才结束会话底层重连不得在可信租约仍存活时意外创建新的 Agent 运行。租约关闭、过期、被撤销或收到显式结束请求时运行时结束隐式会话运行时代拆除会结束该代内所有会话。这正是 RFC 2549 确立的运行时代、可信宿主租约、已认证动作连接信任架构向生命周期层的延伸参见 rfcs/2549-cua-driver-sdk-owned-runtime.md。3. 自动创建并复用隐式会话在首次没有公开会话名的会话必需调用上运行时按顺序执行解析已认证传输租约在其可信命名空间内创建不透明的内部会话身份初始化该调用所需的全部会话所属子系统以已绑定到连接的授权上下文分发调用同一租约上的后续调用复用该身份。同一租约上的并发首调用必须收敛到恰好一个隐式会话创建与清理必须幂等。光标空闲隐藏超时只改变可见性不创建新会话、不结束会话、不改变身份后续带光标的活动唤醒同一个覆盖层与光标身份。4. 一次性 CLI 会话可丢弃一次性 CLI 命令没有持久的已认证传输租约因此每个没有显式会话的会话必需命令获得一个可丢弃隐式会话分发前创建会话执行命令完成后同步执行常规会话清理保留空闲 TTL 回收作为崩溃兜底。守护进程绝不在无关的一次性调用之间共享短生命周期兼容会话——否则会把不同 shell、脚本或同一 OS 用户下不同 Agent 的状态混在一起。需要跨 CLI 命令保持光标、录制或配置连续性的调用方应使用显式会话 受支持的宿主持有重连流程。迁移期间--no-session兼容选项可为依赖匿名无光标行为的脚本保留该行为。5. 保持小巧的公开会话 API工具目标契约start_session可选声明命名生命周期会话并幂等返回存活会话普通调用不再要求它。get_session返回一个可见会话的生命周期、光标、录制、配置与无敏感状态。list_sessions返回调用方可信范围内可见会话的无内容摘要。end_session结束一个可见会话并恰好运行一次全部清理钩子。get_session_state降级为get_session的兼容别名其响应不得在平台覆盖层拒绝或丢弃命令时谎称光标已渲染。escalate_session从目标 API 中消失不新增deescalate_session。仓库中的契约定义与此完全对齐libs/cua-driver/rust/crates/cua-driver-contract/src/session.rsstart_session标注idempotent: true说明omitted value uses the authenticated transport leases implicit sessionget_session、list_sessions标注read_onlyend_session标注destructive且幂等escalate_session的 capability 为session.capture_scope.escalate并声明 No deescalate_session tool exists。实现侧session_tools.rs同样遵循这些语义session_id_of优先采用显式公开名其次采用运行时注入的_session_id并过滤空串与defaultend_session在清理钩子未完成时返回session_cleanup_pending或session_cleanup_partial且钩子错误被脱敏为稳定的cleanup failed类别避免泄漏本地路径等实现细节。6. 约束命名会话的重连显式公开名只能在同一可信所有权命名空间内选择既有生命周期状态公开名从不提供所有权证明。当会话从新传输租约附加时宿主必须验证已认证调用方属于原始可信所有权命名空间会话仍存活且可重连宿主持有不透明、不可猜测的恢复凭据或等价宿主私有证明先前附加已结束或显式协调策略允许多附加。恢复凭据由宿主持有绝不通过模型可见的工具参数接收也不被视为权限令牌。成功重连恢复光标身份、录制所有权与清理责任等生命周期状态但新连接提供全新的授权上下文——重连不继承旧连接的权限模式、grants、审批、托管/用户策略快照或能力清单。公开名不能跨运行时代、宿主租约、已认证主体或远端租户边界重连同一 OS 用户身份不足为凭。显式重启已结束的公开名通过start_session会创建新的生命周期篇章可以保留由名字派生的面向用户颜色但核心状态、光标注册表状态、录制、配置与平台覆盖层必须一起复活。issue #2976 覆盖了实现该行为所需的跨平台覆盖层墓碑缺陷修复。7. 按调用方角色限定list_sessions可见性可见性跟随可信所有权而非字符串知识调用方可见会话普通 Agent 传输当前附加到其已认证传输租约的会话。可信宿主或编排器其运行时代或宿主租约命名空间内的会话。本地操作员界面其管理下的本地守护进程中全部存活会话。普通摘要可包含脱敏公开标签若有、会话是隐式还是显式命名、闭枚举客户端类型、生命周期状态、光标可见与录制活跃布尔值、粗略空闲与过期状态。可信操作员视图可额外暴露不透明属主短 ID、传输类型、开始时间与结构化结束原因但不得暴露运行时密钥或恢复凭据、调用方自由文本、录制路径或内容、权限授权/能力清单内容/策略细节、精确动作历史、捕获或键入内容。分页、稳定排序与脱敏在序列化前完成一个调用方提供的会话名绝不能被另一个普通调用方枚举。仓库中list_sessions的实现正是传输作用域的session_tools.rs它要求_transport_session_id已认证传输租约limit限制在 1100cursor仅接受o:offset格式操作员视图则独立于 Agent 工具通过cua-driver sessions list --json提供见 serve.rslibs/cua-driver/rust/crates/cua-driver/src/serve.rs 中run_sessions_list_cmd的实现输出列含STATE TRANSPORT CLIENT SESSION OWNER IDLE属主以短相关 ID 呈现。8. 捕获形态按调用选择目标契约从生命周期会话身份中移除capture_scopeauto|window|desktop窗口定向的观察或动作使用窗口适配器与精确窗口身份桌面定向的观察或动作使用桌面适配器与显式显示作用域由硬性不变量、托管策略、用户策略、所选权限档案、可选能力清单与实时资源检查共同决定是否允许生命周期会话仅为无内容遥测与资源清理记录所选形态。动作专属生成契约可通过类型化目标变体或公共按调用字段表达形态并必须在平台分发前拒绝模糊坐标系。产品级窗口优先偏好属于规划器指导或单次调用回退逻辑回退必须针对其实际选择的目标重新走授权且不得改变会话状态。9. 统一光标初始化与清理首个光标动作在报告成功前创建或解析生命周期会话并初始化平台覆盖层move_cursor必须像坐标点击一样可靠地初始化并显示覆盖层。所有终止路径调用同一个幂等清理操作显式end_session、已认证传输租约关闭、空闲过期、撤销、运行时代关闭。清理对每个注册的会话所属钩子恰好执行一次部分清理作为结构化错误报告并允许有界重试状态检查报告平台已确认的状态而非仅报告已接受的命令或注册表意图。仓库核心 session.rslibs/cua-driver/rust/crates/cua-driver-core/src/session.rs 提供了落地这些保证的机制SessionDispatchGuard是 RAII 保护在动作分发期间阻止空闲驱逐Drop时刷新空闲时钟并完成任何与之竞争结束请求SessionEndReason区分Explicit / IdleTimeout / ProcessExit / UnknownSessionObserver遥测边界只允许SessionStartObservation、on_tool_completed含CaptureModality与on_session_ended三类有界观察会话 ID 只用于进程内查找、绝不序列化导出。测试覆盖了并发首调用收敛、跨属主访问被拒session_not_started/session_unavailable、清理钩子失败脱敏session_cleanup_partial且不含/Users/private/...路径等关键行为。固定实现选择RFC 定稿的工程参数RFC 明确以下固定选择使实现无需再走一轮设计空闲 TTL隐式与显式会话默认5 分钟仓库实现确认pub const DEFAULT_SESSION_IDLE_TTL: Duration Duration::from_secs(5 * 60);见 session.rs 第 30 行。可信宿主可在文档化边界内配置更短或更长的值。在途动作不会过期只有到达分发的已接纳会话必需调用才刷新 TTL健康读取、被拒调用、传输保活与光标空闲隐藏不刷新。活跃录制不暂停空闲过期——空闲清理会作为常规会话清理的一部分停止并定稿录制。传输关闭与撤销仍立即清理。可选公开名start_session接受可选公开名无名时创建或返回传输的隐式会话get_session/end_session在未提供可见会话引用时同样默认作用于调用方附加的隐式会话。按调用目标类型化联合target window { application identity, window_id } | desktop { display_id }旧平面目标字段仍由兼容解码器接受并在授权前归一化为该联合。恢复凭据随机、宿主持有、一次性绑定运行时代、宿主租约、主体与生命周期篇章成功附加即轮换运行时重启后不持久化也绝不通过 Agent 工具参数接收。列表作用域Agent 面list_sessions为传输作用域可信 SDK 宿主获得宿主作用域列表方法本地管理员用cua-driver sessions list --json操作员视图不注册为 Agent 工具。遗留标记提供已弃用capture_scope会将显式会话在兼容窗口内标记为 legacy纯生命周期隐式会话与新类型化按调用目标不携带捕获状态。上一受支持 SDK 版本的兼容 fixtures 必须在该规则上线前通过。核心实现形态与规范分发顺序核心拥有唯一生命周期注册表适配器不得创建私有回退会话或独立清理会话所属资源trusted runtime generation └── host lease namespace ├── authorization bindings by authenticated action connection ├── implicit session index by transport lease └── lifecycle sessions ├── attachments ├── cursor and overlay state ├── recording and per-run configuration ├── idle and absolute deadlines └── cleanup state: live - ending - ended在规范分发边界运行时按此顺序执行认证动作连接并解析其不可变授权上下文在连接的可信命名空间内解析或创建生命周期会话归一化类型化或遗留动作目标通过既有策略栈授权精确工具与被证实的attested目标初始化所需会话所属资源并分发一次仅为已接纳调用提交生命周期活动与遥测报告平台已确认状态。分发前失败不得刷新租约、创建外部可见光标或扩大授权平台部分交付后失败必须报告已知或未知影响并保持清理可恢复。会话注册表、清理钩子、遥测观察器与光标状态读取器在 session.rs 中为平台可插拔平台注册Fn(str)清理回调与有界光标状态读取器核心向所有注册钩子扇出结束事件无反向耦合。兼容性与两阶段迁移加性发布Release N为会话必需调用创建隐式会话新增get_session与list_sessionsget_session_state成为弃用别名新增按调用捕获形态在 Rust 契约、生成 SDK、MCP 描述、CLI 帮助与文档中将escalate_session与会话级capture_scope标记弃用调用方显式使用弃用字段或工具时保留遗留捕获行为发出结构化迁移指导且不把调用方内容写入日志或遥测。加性发布必须保持当前线上兼容新 SDK 应优先生命周期 API 与类型化按调用目标。声明破坏性发布在至少两个小版本与至少 90 天后声明破坏性发布可以从广告的 MCP 与生成 SDK 表面移除escalate_session从start_session与会话状态移除会话级capture_scope停止创建遗留捕获状态会话。分发器在受支持兼容期内为escalate_session保留结构化tool_removed墓碑指明替代的按调用契约且不执行动作。get_session_state作为低风险只读别名可保留更久最早移除需单独发布说明与 SDK 使用证据。加性阶段回滚只需禁用隐式创建与新的按调用表面破坏性发布后回滚走常规组件版本路径无需会话数据迁移——会话本就是临时运行时状态。安全、隐私与遥测边界核心不变量trusted namespace proves lifecycle ownership public session identity selects lifecycle state within that namespace current authenticated connection supplies all authority任何会话生命周期操作或省略的会话参数都不能扩大硬性不变量、托管策略、用户策略、权限档案行为、能力清单或实时资源检查。运行时必须在返回命名会话是否存在之前拒绝跨命名空间的查找、附加、列出与结束操作错误响应避免形成会话名枚举预言机。遥测可包含生成的事件 ID、闭枚举客户端类型、开始与结束原因、粗略时长、聚合动作计数、所选捕获形态。不得包含公开会话名、恢复凭据、自由形式调用方文本、捕获内容、键入输入、录制路径或授权秘密。彩色光标向用户传达 Agent 活动但它不是动作已被授权、已交付或由特定远端主体执行的证明。测试与验收计划摘要RFC 给出可执行的验收矩阵核心类别如下生命周期与光标首次光标动作无需start_session运行时创建一个隐式会话同一租约后续动作复用并发首动作恰好创建一个隐式会话move_cursor在全新隐式/显式会话上初始化并显示彩色覆盖层光标空闲渐隐不改变会话身份连接/租约关闭、空闲 TTL、撤销、运行时关闭与显式结束调用同一清理钩子恰好一次在途动作不可过期仅到达分发的已接纳会话必需调用刷新空闲一次性 CLI 命令使用一个可丢弃会话观察不到无关调用的状态复用已结束公开 ID 时核心、光标、录制、配置与平台覆盖层一起复活检查绝不把被平台拒绝/丢弃的命令报告为已渲染光标。所有权与隐私公开会话名不能越界附加、列出、结束或探测重放、过期、撤销、跨代、跨主体、跨宿主租约的恢复证明失败关闭fail closed重连恢复生命周期状态但只用新连接的授权上下文普通list_sessions只返回附加到调用方租约的会话可信宿主与操作员列表遵循文档化作用域并先脱敏再序列化。授权与捕获启动、结束、省略、重连或重命名会话不能改变同一连接与动作的授权结果窗口定向调用使用精确窗口身份与窗口坐标桌面定向调用使用显式显示目标与桌面坐标按调用回退对实际目标重新授权且不改变生命周期状态遗留捕获字段仅在迁移窗口内保留文档化行为。此外需添加针对主安全不变量的属性测试Given the same authenticated connection and action, changing only lifecycle-session selection cannot change Deny or RequireGrant into Allow.契约与平台对齐生成 MCP schema 与全部受支持 SDK 暴露一致的契约CLI 帮助、环境变量、状态输出、弃用警告与文档和生成契约一致完整规范 Windows、Linux X11、macOS 桌面 E2E 矩阵在精确稳定候选 SHA 上通过受支持 Wayland 行为匹配契约或返回具体合成器/门户限制合入后主分支与发布路径冒烟通过。实施计划与合入门槛RFC 要求单一实现 PR 承载加性迁移采用发布型标题feat(cua-driver): add implicit lifecycle sessionsPR 以 draft 开始并链接本 RFC不包含#2996 能力清单工作在宣布的支持窗口结束前不删除弃用工具或字段。工作提交按依赖顺序推进契约与 fixtures冻结 0.19.2 兼容 fixtures 并添加失败目标 schema→ 所有权地基运行时命名空间、传输租约、生命周期键、分离授权/生命周期引用的分发上下文→ 生命周期与清理隐式创建、5 分钟空闲过期、可丢弃 CLI 会话、附加、复活、幂等清理协调器→ 光标正确性跨 macOS/Windows/X11/受支持 Wayland 完成 #2976move初始化覆盖层、渲染确认可观测→ 公开会话 API → 按调用捕获类型化目标联合、归一化、规范授权、遗留会话捕获适配器、弃用→ 生成表面与文档 → 候选认证重点套件 常规 PR CI 稳定 SHA 上规范桌面矩阵。PR 就绪门槛包括最终 diff 只含生命周期会话实现及其生成契约/测试/文档上一受支持 SDK 与裸 MCP 兼容 fixtures 通过生成契约与每个检入 SDK 表面与 Rust 源一致生命周期选择属性测试证明仅改会话不能把Deny/RequireGrant变成Allow并发结束/过期/撤销/断开/关闭下清理恰好一次光标复活与首移动在 macOS/Windows/X11/受支持 Wayland 有聚焦覆盖完整规范桌面 E2E 矩阵在最终候选 SHA 全绿。合入后运行短主分支生命周期冒烟并核对组件发布路径记录最早允许的遗留移除日期与发布号。决策记录与未决问题RFC 记录了使用 Claude Code Fable 的两轮对抗性架构评审结论支持传输绑定隐式会话、窄作用域会话枚举、可丢弃一次性 CLI 会话与分阶段弃用拒绝了会话生命周期桌面授权 shim的中间方案它会让生命周期状态影响有效动作权威正是本 RFC 要消除的耦合。评审期间将默认空闲 TTL 从 30 分钟缩短为 5 分钟并修正了哪些事件刷新 TTL、保护在途动作不过期、活跃录制仍受常规空闲清理约束。RFC 明确没有阻塞实施的未决设计问题。小结给集成方的三条行动要点普通 Agent 集成无需再显式start_session首个光标/录制/配置相关调用会自动获得租约绑定的隐式会话move_cursor即唤醒彩色光标end_session幂等且清理恰好一次。需要命名协调的场景使用可选公开名 宿主持有的恢复凭据做跨调用/跨租约重连公开名只是命名空间内的标签永远不是凭据。捕获行为迁移新代码应在每个动作上选择window { application identity, window_id }或desktop { display_id }目标停止使用escalate_session与capture_scopeget_session_state可继续作为只读别名使用。【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考