企业官网建设流程全解析

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 3007（rfcs/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_scope=auto|window|desktop与escalate_session表达。

这种耦合产生了三类可复现的故障：

1. 显式启动依赖：Agent 可能忘记调用start_session，导致彩色光标从未初始化，后续动作附着到另一个会话；
2. 不可逆的升级：auto会话一旦调用escalate_session就永久失去窗口级工具，调用方必须结束会话并换新 ID 才能恢复窗口行为（这一限制此前由 PR #2857 固化在文档中）；而若添加反向过渡，状态机只会更大，捕获与生命周期仍然纠缠；
3. 授权边界缺失：旧捕获门控只在能解析到会话时才执行，未携带公开会话的调用可以绕过 capture-scope 状态——尽管它仍然通过硬性不变量、托管策略、用户策略、所选权限档案与资源适配器。因此会话捕获状态不适合作为授权边界。

RFC 3007 的结论是：会话应当给调用方提供稳定的运行身份与可靠的清理；捕获形态属于"正在执行的动作"，而权限属于"接纳该动作的可信运行时或已认证连接"。

术语体系：构建新模型的最小词汇表

RFC 精确定义了以下概念，后续所有设计均建立在其上：

现状盘点：旧公开契约与既有实现

RFC 3007 明确记录了当前（旧）公开会话契约包含四个工具：

RFC 指出，该契约把升级描述为永久行为，并要求调用方"结束会话、用新 ID 重启"才能恢复窗口作用域。实现位于 session_tools.rs（libs/cua-driver/rust/crates/cua-driver-core/src/session_tools.rs），公开定义在 session.rs（libs/cua-driver/rust/crates/cua-driver-contract/src/session.rs），捕获门控在 capture_scope.rs（libs/cua-driver/rust/crates/cua-driver-core/src/capture_scope.rs）。

在仓库现有实现中可逐条印证旧模型的痕迹：

• session_tools.rs中的EscalateSessionTool仍要求公开sessionID 与reason，escalate_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 session

• MCP over stdio：租约通常持续到 MCP 进程或 stdio 连接结束；
• 直接 SDK：租约持续到宿主暴露的可信会话或连接对象结束；
• 守护进程或可重连 HTTP 服务：可信宿主认证返回调用方后，可让租约跨 socket 重连存活；
• 裸 socket 断开：仅当该 socket 是租约所有者时才结束会话；底层重连不得在可信租约仍存活时意外创建新的 Agent 运行。

租约关闭、过期、被撤销或收到显式结束请求时，运行时结束隐式会话；运行时代拆除会结束该代内所有会话。这正是 RFC 2549 确立的"运行时代、可信宿主租约、已认证动作连接"信任架构向生命周期层的延伸（参见 rfcs/2549-cua-driver-sdk-owned-runtime.md）。

3. 自动创建并复用隐式会话

在首次没有公开会话名的会话必需调用上，运行时按顺序执行：

1. 解析已认证传输租约；
2. 在其可信命名空间内创建不透明的内部会话身份；
3. 初始化该调用所需的全部会话所属子系统；
4. 以已绑定到连接的授权上下文分发调用；
5. 同一租约上的后续调用复用该身份。

同一租约上的并发首调用必须收敛到恰好一个隐式会话；创建与清理必须幂等。光标空闲隐藏超时只改变可见性，不创建新会话、不结束会话、不改变身份，后续带光标的活动唤醒同一个覆盖层与光标身份。

4. 一次性 CLI 会话可丢弃

一次性 CLI 命令没有持久的已认证传输租约，因此每个没有显式会话的会话必需命令获得一个可丢弃隐式会话：

1. 分发前创建会话；
2. 执行命令；
3. 完成后同步执行常规会话清理；
4. 保留空闲 TTL 回收作为崩溃兜底。

守护进程绝不在无关的一次性调用之间共享短生命周期兼容会话——否则会把不同 shell、脚本或同一 OS 用户下不同 Agent 的状态混在一起。需要跨 CLI 命令保持光标、录制或配置连续性的调用方，应使用显式会话 + 受支持的宿主持有重连流程。迁移期间，--no-session兼容选项可为依赖匿名无光标行为的脚本保留该行为。

5. 保持小巧的公开会话 API

get_session_state降级为get_session的兼容别名，其响应不得在平台覆盖层拒绝或丢弃命令时谎称光标已渲染。escalate_session从目标 API 中消失，不新增deescalate_session。

仓库中的契约定义与此完全对齐（libs/cua-driver/rust/crates/cua-driver-contract/src/session.rs）：start_session标注idempotent: true，说明"omitted value uses the authenticated transport lease's implicit session"；get_session、list_sessions标注read_only；end_session标注destructive且幂等；escalate_session的 capability 为session.capture_scope.escalate并声明 "No deescalate_session tool exists"。实现侧（session_tools.rs）同样遵循这些语义：session_id_of优先采用显式公开名，其次采用运行时注入的_session_id，并过滤空串与"default"；end_session在清理钩子未完成时返回session_cleanup_pending或session_cleanup_partial，且钩子错误被脱敏为稳定的"cleanup failed"类别，避免泄漏本地路径等实现细节。

6. 约束命名会话的重连

显式公开名只能在同一可信所有权命名空间内选择既有生命周期状态；公开名从不提供所有权证明。当会话从新传输租约附加时，宿主必须验证：

• 已认证调用方属于原始可信所有权命名空间；
• 会话仍存活且可重连；
• 宿主持有不透明、不可猜测的恢复凭据（或等价宿主私有证明）；
• 先前附加已结束，或显式协调策略允许多附加。

恢复凭据由宿主持有，绝不通过模型可见的工具参数接收，也不被视为权限令牌。成功重连恢复光标身份、录制所有权与清理责任等生命周期状态，但新连接提供全新的授权上下文——重连不继承旧连接的权限模式、grants、审批、托管/用户策略快照或能力清单。公开名不能跨运行时代、宿主租约、已认证主体或远端租户边界重连，同一 OS 用户身份不足为凭。

显式重启已结束的公开名（通过start_session）会创建新的生命周期篇章：可以保留由名字派生的面向用户颜色，但核心状态、光标注册表状态、录制、配置与平台覆盖层必须一起复活。issue #2976 覆盖了实现该行为所需的跨平台覆盖层墓碑缺陷修复。

7. 按调用方角色限定list_sessions可见性

可见性跟随可信所有权而非字符串知识：

普通摘要可包含：脱敏公开标签（若有）、会话是隐式还是显式命名、闭枚举客户端类型、生命周期状态、光标可见与录制活跃布尔值、粗略空闲与过期状态。可信操作员视图可额外暴露不透明属主短 ID、传输类型、开始时间与结构化结束原因，但不得暴露：运行时密钥或恢复凭据、调用方自由文本、录制路径或内容、权限授权/能力清单内容/策略细节、精确动作历史、捕获或键入内容。分页、稳定排序与脱敏在序列化前完成；一个调用方提供的会话名绝不能被另一个普通调用方枚举。

仓库中list_sessions的实现正是传输作用域的（session_tools.rs）：它要求_transport_session_id（已认证传输租约），limit限制在 1～100，cursor仅接受o:<offset>格式；操作员视图则独立于 Agent 工具，通过cua-driver sessions list --json提供（见 serve.rs（libs/cua-driver/rust/crates/cua-driver/src/serve.rs） 中run_sessions_list_cmd的实现，输出列含STATE TRANSPORT CLIENT SESSION OWNER IDLE，属主以短相关 ID 呈现）。

8. 捕获形态按调用选择

目标契约从生命周期会话身份中移除capture_scope=auto|window|desktop：

1. 窗口定向的观察或动作使用窗口适配器与精确窗口身份；
2. 桌面定向的观察或动作使用桌面适配器与显式显示作用域；
3. 由硬性不变量、托管策略、用户策略、所选权限档案、可选能力清单与实时资源检查共同决定是否允许；
4. 生命周期会话仅为无内容遥测与资源清理记录所选形态。

动作专属生成契约可通过类型化目标变体或公共按调用字段表达形态，并必须在平台分发前拒绝模糊坐标系。产品级"窗口优先"偏好属于规划器指导或单次调用回退逻辑；回退必须针对其实际选择的目标重新走授权，且不得改变会话状态。

9. 统一光标初始化与清理

首个光标动作在报告成功前创建或解析生命周期会话并初始化平台覆盖层；move_cursor必须像坐标点击一样可靠地初始化并显示覆盖层。所有终止路径调用同一个幂等清理操作：显式end_session、已认证传输租约关闭、空闲过期、撤销、运行时代关闭。清理对每个注册的会话所属钩子恰好执行一次；部分清理作为结构化错误报告并允许有界重试；状态检查报告平台已确认的状态，而非仅报告已接受的命令或注册表意图。

仓库核心 session.rs（libs/cua-driver/rust/crates/cua-driver-core/src/session.rs） 提供了落地这些保证的机制：SessionDispatchGuard是 RAII 保护，在动作分发期间阻止空闲驱逐，Drop时刷新空闲时钟并完成任何与之竞争结束请求；SessionEndReason区分Explicit / IdleTimeout / ProcessExit / Unknown；SessionObserver遥测边界只允许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

在规范分发边界，运行时按此顺序执行：

1. 认证动作连接并解析其不可变授权上下文；
2. 在连接的可信命名空间内解析或创建生命周期会话；
3. 归一化类型化或遗留动作目标；
4. 通过既有策略栈授权精确工具与被证实的（attested）目标；
5. 初始化所需会话所属资源并分发一次；
6. 仅为已接纳调用提交生命周期活动与遥测；
7. 报告平台已确认状态。

分发前失败不得刷新租约、创建外部可见光标或扩大授权；平台部分交付后失败必须报告已知或未知影响并保持清理可恢复。会话注册表、清理钩子、遥测观察器与光标状态读取器在 session.rs 中为平台可插拔：平台注册Fn(&str)清理回调与有界光标状态读取器，核心向所有注册钩子扇出结束事件，无反向耦合。

兼容性与两阶段迁移

加性发布（Release N）

• 为会话必需调用创建隐式会话；
• 新增get_session与list_sessions；
• get_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 sessions

PR 以 draft 开始并链接本 RFC；不包含#2996 能力清单工作；在宣布的支持窗口结束前不删除弃用工具或字段。工作提交按依赖顺序推进：契约与 fixtures（冻结 0.19.2 兼容 fixtures 并添加失败目标 schema）→ 所有权地基（运行时命名空间、传输租约、生命周期键、分离授权/生命周期引用的分发上下文）→ 生命周期与清理（隐式创建、5 分钟空闲过期、可丢弃 CLI 会话、附加、复活、幂等清理协调器）→ 光标正确性（跨 macOS/Windows/X11/受支持 Wayland 完成 #2976，move初始化覆盖层、渲染确认可观测）→ 公开会话 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 明确没有阻塞实施的未决设计问题。

小结：给集成方的三条行动要点

1. 普通 Agent 集成：无需再显式start_session；首个光标/录制/配置相关调用会自动获得租约绑定的隐式会话，move_cursor即唤醒彩色光标，end_session幂等且清理恰好一次。
2. 需要命名协调的场景：使用可选公开名 + 宿主持有的恢复凭据做跨调用/跨租约重连；公开名只是命名空间内的标签，永远不是凭据。
3. 捕获行为迁移：新代码应在每个动作上选择window { application identity, window_id }或desktop { display_id }目标，停止使用escalate_session与capture_scope；get_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