feat(browser): complete camofox BrowserProvider with tabs, interaction, download capture and control lease

Contracts for browser API and browser.* agent capabilities; adapter implements close/list/restore sessions, tabs + reconcile, history, click/type/select/scroll/press, extract, waitForDownload (staged via DownloadSink, sha256), stale-ref guard and automation/human actor check. testkit mock camofox gains an interactive site (login redirect, captcha, click-driven page changes, downloads, PNG screenshots). Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-09-28 20:17:46 +08:00
1 parent 62290d4477
commit c17d4b90bd
@@ -2,6 +2,7 @@ import { z } from "zod";
 import * as agent from "./agent.ts";
 import * as assets from "./assets.ts";
 import * as auth from "./auth.ts";
+import * as browser from "./browser.ts";
 import { CapabilityDescriptor, KnownCapabilityId } from "./capability.ts";
 import { type ApiScope, CursorQuery, cursorPage, HealthStatus, Id, IdParam } from "./common.ts";
 import * as content from "./content.ts";
@@ -2008,6 +2009,167 @@ export const Api = {
    }),
  },

+  // ── 浏览器(C1-E):站点浏览器会话、原站视图、人工接管;写动作需人工持有控制权(接管) ──
+  browser: {
+    providers: ep({
+      method: "get",
+      path: "/browser/providers",
+      scope: "admin",
+      summary: "浏览器服务列表(地址、凭证引用、启用、能力 supported/verified);probe=true 现场探测并写回",
+      query: browser.BrowserProvidersQuery,
+      response: z.object({ items: z.array(browser.BrowserProviderView) }),
+    }),
+    sessions: ep({
+      method: "get",
+      path: "/browser/sessions",
+      scope: "admin",
+      summary: "浏览器会话列表(以数据库为准;默认只列未关闭的)",
+      query: browser.BrowserSessionsQuery,
+      response: z.object({ items: z.array(browser.BrowserSessionView) }),
+    }),
+    open: ep({
+      method: "post",
+      path: "/browser/sessions",
+      scope: "admin",
+      summary: "打开站点浏览器会话(同一站点/账号已有未关闭会话时直接返回它)",
+      body: browser.BrowserSessionOpen,
+      response: browser.BrowserSessionView,
+    }),
+    get: ep({
+      method: "get",
+      path: "/browser/sessions/{id}",
+      scope: "admin",
+      summary: "浏览器会话详情(控制者、标签页、租约、是否需重新读取页面)",
+      params: browser.BrowserSessionParams,
+      response: browser.BrowserSessionView,
+    }),
+    close: ep({
+      method: "delete",
+      path: "/browser/sessions/{id}",
+      scope: "admin",
+      summary: "关闭浏览器会话(关闭上游标签页,撤销租约)",
+      params: browser.BrowserSessionParams,
+      response: browser.BrowserSessionView,
+    }),
+    openTab: ep({
+      method: "post",
+      path: "/browser/sessions/{id}/tabs",
+      scope: "admin",
+      summary: "新建标签页并设为当前(需持有控制权)",
+      params: browser.BrowserSessionParams,
+      body: browser.BrowserTabOpen,
+      response: browser.BrowserSessionView,
+    }),
+    closeTab: ep({
+      method: "delete",
+      path: "/browser/sessions/{id}/tabs/{tabId}",
+      scope: "admin",
+      summary: "关闭标签页(需持有控制权)",
+      params: browser.BrowserTabParams,
+      response: browser.BrowserSessionView,
+    }),
+    navigate: ep({
+      method: "post",
+      path: "/browser/sessions/{id}/navigate",
+      scope: "admin",
+      summary: "地址栏导航或后退/前进/刷新(需持有控制权;限站点域名)",
+      params: browser.BrowserSessionParams,
+      body: browser.BrowserNavigate,
+      response: browser.BrowserNavigation,
+    }),
+    snapshot: ep({
+      method: "get",
+      path: "/browser/sessions/{id}/snapshot",
+      scope: "admin",
+      summary: "结构化页面快照(凭证已遮蔽)",
+      params: browser.BrowserSessionParams,
+      query: browser.BrowserSnapshotQuery,
+      response: browser.BrowserSnapshot,
+    }),
+    screenshot: ep({
+      method: "get",
+      path: "/browser/sessions/{id}/screenshot",
+      scope: "admin",
+      summary: "当前画面截图(base64,只给原站视图,不进模型)",
+      params: browser.BrowserSessionParams,
+      query: browser.BrowserScreenshotQuery,
+      response: browser.BrowserScreenshotView,
+    }),
+    click: ep({
+      method: "post",
+      path: "/browser/sessions/{id}/click",
+      scope: "admin",
+      summary: "点击(快照引用 / 选择器 / 截图坐标;需持有控制权)",
+      params: browser.BrowserSessionParams,
+      body: browser.BrowserClick,
+      response: browser.BrowserActionResult,
+    }),
+    type: ep({
+      method: "post",
+      path: "/browser/sessions/{id}/type",
+      scope: "admin",
+      summary: "输入文本 / 站点账号凭证 / 按键(需持有控制权;凭证由服务端注入)",
+      params: browser.BrowserSessionParams,
+      body: browser.BrowserType,
+      response: browser.BrowserActionResult,
+    }),
+    scroll: ep({
+      method: "post",
+      path: "/browser/sessions/{id}/scroll",
+      scope: "admin",
+      summary: "滚动页面(需持有控制权)",
+      params: browser.BrowserSessionParams,
+      body: browser.BrowserScroll,
+      response: browser.BrowserActionResult,
+    }),
+    select: ep({
+      method: "post",
+      path: "/browser/sessions/{id}/select",
+      scope: "admin",
+      summary: "下拉框选择(需持有控制权)",
+      params: browser.BrowserSessionParams,
+      body: browser.BrowserSelect,
+      response: browser.BrowserActionResult,
+    }),
+    extract: ep({
+      method: "post",
+      path: "/browser/sessions/{id}/extract",
+      scope: "admin",
+      summary: "按 JSON Schema(x-ref)提取页面字段",
+      params: browser.BrowserSessionParams,
+      body: browser.BrowserExtract,
+      response: browser.BrowserExtractResult,
+    }),
+    download: ep({
+      method: "post",
+      path: "/browser/sessions/{id}/download",
+      scope: "organize.execute",
+      summary:
+        "捕获浏览器下载 → 后端暂存并核验 infohash、匹配本地资源;给出 submit 时经 POST /acquisition-plans 同一流程提交",
+      params: browser.BrowserSessionParams,
+      body: browser.BrowserDownload,
+      response: browser.BrowserDownloadResult,
+    }),
+    acquire: ep({
+      method: "post",
+      path: "/browser/sessions/{id}/control/acquire",
+      scope: "admin",
+      summary: "人工接管:先停止该会话新的自动化输入并等进行中的操作收尾,再发放人工租约",
+      params: browser.BrowserSessionParams,
+      body: browser.BrowserControlAcquire,
+      response: browser.BrowserControlResult,
+    }),
+    release: ep({
+      method: "post",
+      path: "/browser/sessions/{id}/control/release",
+      scope: "admin",
+      summary: "交还控制权:Agent 恢复前必须重新读取页面,旧元素引用失效",
+      params: browser.BrowserSessionParams,
+      body: browser.BrowserControlRelease,
+      response: browser.BrowserControlResult,
+    }),
+  },
+
  // ── 定时任务看板(W7-C):统一注册表 + Agent 巡检;全部只接受控制台会话 ──
  schedules: {
    list: ep({