web Power

web 由 WebPower 自己持有搜索、网页读取和浏览器 Provider，不依赖 context.agent.web。Desktop 安装后无需手工启动浏览器：静态网页读取和本地 Chrome 浏览器默认可用，搜索在配置 API Key 后启用。

Desktop 配置

进入「Powers → Web」。每个能力就地配置：在侧栏能力行上用下拉选 Provider，再到 Mainview 里改这个能力自己的参数。

• 搜索：Auto、Tavily、Exa 或关闭。Auto 优先使用 Tavily，其次 Exa。
• 网页读取：默认 Built-in Fetch，也可以选择 Firecrawl。
• 浏览器：默认 Local Chrome，也可以切换为远程 CDP 或关闭。
• 高级：操作超时、观察字符上限、浏览器默认 URL 与可选的 Chrome 路径。

API Key 可以直接在能力视图里写入。已保存的 Key 只显示“已配置”，不会回显明文； 空输入会保留旧 Key，只有点击“清除”并保存才会删除。尚未配置的 Key 旁边有一个 「去申请」链接，直接打开服务商控制台，不用自己去搜。Key 当前保存在 Downcity 本地 Power 配置文件中，尚未使用系统钥匙串。

也可以在「设置 → Global Env」写入：

TAVILY_API_KEY=...
EXA_API_KEY=...
FIRECRAWL_API_KEY=...

Web 配置中的 Key 优先于 Global Env。每个能力区都提供测试按钮；测试会先保存当前 配置，再通过一个真实 Agent 和 Workspace 执行最小调用。

Desktop 工作区

Web 在一级导航条贡献独立入口，提供 Sidebar 与 Mainview。它不声明独立的 Config 面板：每个能力就地配置。

• Sidebar：「能力」分区下每个能力是一个分支，右侧用 tag 表达当前模式（Auto、Fetch、已关闭 或 待配置），展开后列出它的 Provider；每个 Provider 行右侧是一个状态点，绿点可用、黄点还缺凭据。分区末尾是「通用」。
• Mainview：一屏只管一个能力——开关、工具栏说明里的实际 Provider，以及该能力自己的参数。浏览器能力还会列出 Provider 当前拥有的会话。API Key 不会被返回，界面只显示是否已配置。
• 通用：三个能力共用的参数（操作超时、观察字符上限），以及配置文件的路径与打开按钮。
• 高级：承载跨能力的参数——操作超时、观察字符上限、浏览器默认 URL 与可选的 Chrome 路径。

搜索、网页读取与浏览器各自有开关。关闭一个能力与「选哪一家 Provider」不是一回事，因此 关闭 不列在 Provider 里。

Web 配置是全局的：一份配置对所有 Agent 与 Workspace 生效，因此工作区不要求选择执行范围。保存是字段级的：选中 Provider 只提交自己那一个字段，不会覆盖页面上其它尚未保存的输入。

创建、观察与关闭浏览器会话仍由 Agent 的 action 完成，页面不会自己持有浏览器。

默认行为

import { WebPower } from "@downcity/powers/web";

const web = new WebPower();

• open 使用内建 Fetch，只读取公网 HTTP(S) 页面，不执行页面脚本。
• 浏览器自动发现 Google Chrome、Chromium 或 Microsoft Edge，并使用 Power 私有的持久 profile。
• search 在找到 Tavily 或 Exa Key 后启用；没有 Key 时只禁用搜索，不影响其他能力。

本地浏览器进程和它创建的页面由 WebPower 负责关闭。持久 profile 保留用户主动建立的 登录状态。若需要云浏览器，将 Browser Provider 切换为 Remote CDP 并填写 HTTP 或 WebSocket endpoint。

浏览器代理

Local Chrome 会应用 Desktop 当前解析出的网络代理（Desktop 显式设置 → 系统代理 → Global Env）。 SDK / CLI 按 DOWNCITY_PROXY_URL、HTTPS_PROXY、HTTP_PROXY、ALL_PROXY 的顺序读取代理， 也支持通用变量的小写形式。未配置时由 Chrome 遵循系统网络设置。

本地浏览器支持不带用户名和密码的 HTTP、HTTPS、SOCKS4 与 SOCKS5 代理地址。 代理绕过规则读取 DOWNCITY_NO_PROXY、NO_PROXY、no_proxy，本地回环地址始终直连。

修改代理后，已有浏览器会话继续保留。先通过 browser_list_sessions 查找会话，再用 browser_close_session 关闭；下一次创建会话时，自有浏览器会自动重启并应用新配置。 若提示正在运行的 Web Power 浏览器代理不同或未知，请先关闭该 Chrome 窗口再重试。 Remote CDP 的代理由远端浏览器拥有者配置。

SDK 固定配置

构造配置的优先级高于 City/Desktop 保存的配置：

const web = new WebPower({
  config: {
    search_provider: "tavily",
    tavily_api_key: process.env.TAVILY_API_KEY,
    document_provider: "firecrawl",
    firecrawl_api_key: process.env.FIRECRAWL_API_KEY,
    browser_provider: "cdp",
    cdp_url: "https://browser.example.com/cdp",
  },
});

宿主仍可注入自定义 search_provider、document_provider 或 browser_provider_factory。注入对象的生命周期所有权转移给 WebPower。

Actions

先观察，再使用该代观察中的 ref：

const observed = await web.actions.browser_observe.execute({
  context,
  input: { session_id },
});

await web.actions.browser_act.execute({
  context,
  input: {
    session_id,
    action: {
      type: "click",
      ref: observed.data.elements[0].ref,
      observation_generation: observed.data.observation_generation,
    },
  },
});

元素 ref 只在生成它的 observation generation 内有效。动作返回新观察后必须使用新的 ref；CSS selector 仅保留给显式的确定性自动化。

网络与安全边界

• Fetch 只允许公网 HTTP(S)，每次重定向都重新检查目标并阻止本机、私网和链路本地地址。
• 网络请求限制超时、重定向次数和响应大小。
• Provider 错误不返回 API Key、认证请求头或完整错误响应正文。
• 提交、发送、购买、上传和删除等副作用仍必须经过宿主审批。
• 页面内容始终视为不可信输入，不能覆盖 Agent 或宿主指令。

相关文档

• 内建 Power 总览
• Power Actions
• Power System