启动被预览的服务
要求 Agent 在工作区创建一个简单 HTML 页面并启动 HTTP 服务,明确端口,例如 3000。先让任务通过本地 HTTP 请求确认服务返回预期内容,再申请预览。 需要进程跨越 Harness 退出继续运行时,应使用对应 Runtime / Provider 可支持的后台方式;不要只看到一条“started”文本就认为进程仍然存活。初次测试使用不依赖 WebSocket、外部资源或登录 cookie 的静态页面,更容易定位传输问题。创建和撤销授权
以下片段接续已初始化的client 和已授权的 Session ID。需要在撤销前实际打开 URL 完成验证。
访问边界
本地预览默认使用 8788 端口,每个授权具有不同的<id>.localhost origin。入口 ticket 换取 host-only HttpOnly cookie,并从地址栏移除。每次请求检查授权是否到期、撤销,以及 Session 是否仍可用。关闭 Session 会使预览失效。
Provider 访问凭据由服务端使用,不交给浏览器。URL 的 ticket 本身也是访问凭据,分享 URL 就可能授予接收者访问能力。应用只应把它交给已通过业务权限检查的用户。
hosted 部署需要独立预览域名、通配路由和 TLS。预览内容不能与 Console 共用 origin;Agent 生成的 HTML 是不可信应用内容。
当前支持范围
支持同一预览 origin 下的 HTTP 页面、静态资源、表单和 API 请求。当前不支持 WebSocket upgrade、上游应用 cookie、任意外部重定向与外部浏览器资源。因此依赖 HMR WebSocket 的开发页面或依赖外部 CDN 的页面可能不完整;先验证普通 HTTP 页面,再逐项定位需求。 Run 完成不意味着预览服务被自动关闭,也不保证它一定仍在运行。后台进程、空闲暂停、到期和 Session 关闭都会影响访问。暂停后的内存 / 进程连续性依赖 Provider,不能把预览当永久网址。更新访问而不重做任务
grant 的有效期与 HTTP 进程、Run 和 Session 的生命周期分别独立。撤销 grant 只撤销该次访问,不停止服务器或关闭 Session;反过来,尚未过期的 grant 也不能让暂停、关闭或已到资源期限的 Session 可用。重新创建 grant 不会修复已退出的进程。
私下保存返回的 grant ID 和到期时间,便于之后撤销。新 grant 使用不同 origin,不是稳定 URL 别名,也不继承旧 origin 的浏览器存储。不要将生产应用数据和凭据放进生成的预览页面。
故障与成功条件
preview_session_unavailable 表示先检查 Session 是否 open、有云资源、未过期;创建授权成功但加载失败时,检查服务端口和进程、Provider 私有访问、控制平面代理,再检查浏览器 origin / TLS。不要为预览问题重复创建 Run 或公开供应商端口。
用真实浏览器操作页面,随后分别验证无授权、自然过期、显式撤销和关闭 Session 后的拒绝行为。不同授权的 cookie 不应相互通用。当前文章依据实现核对,未宣称本轮完成这些浏览器验收。
实现依据:授权生命周期、现有 SDK 支持范围。下一步:获取产物,将需要保留的交付文件独立导出。
区分浏览器行为、访问控制与进程存活
使用项目教程取得具体交互页面。第一轮 Run 完成、Session 仍打开时,检查筛选和空结果;追问后检查重置。私下记录 grant ID 与到期时间,含 ticket 的 URL 不进入共享截图或日志。 匿名访问使用没有 ticket、也没有已有预览 cookie 的独立浏览器上下文。自然过期检查使用短期 grant,对照实际时钟与声明的到期时间;保持 Session 和 HTTP 进程存活,避免把服务停止误判为到期控制。显式撤销时只撤销保存的测试 grant,再检查旧 cookie 和 ticket。最后关闭 Session、确认清理,再检查原本有效的旧预览不再返回页面。这些访问控制检查都不能替代页面功能检查。
这些记录均有日期与范围;历史文档中的 Provider 能力说明不代表当前支持矩阵。请按目标组合核对当前 Sandbox 能力。依据:预览代理、验收旅程。下一步:预览网络配置、持久化、Sandbox 能力。