# @broberg/lens-client 中文文档

规范地址：https://npmcn.com/package/%40broberg/lens-client/

版本：0\.2\.0
npm 元数据更新时间：2026-10-31T14:40:06.266Z
中文译文更新时间：2026-10-31T17:35:32.331Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40broberg/lens-client
原文对照：https://npmcn.com/package/%40broberg/lens-client/?lang=original
项目主页：https://github.com/broberg-ai/lens#readme
源码仓库：https://github.com/broberg-ai/lens

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：135 kB，28 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：hono \>=4
- 首次发布：2026-07-03T21:51:41.063Z
- 最新版本发布：2026-10-31T14:40:06.098Z
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

瘦客户端为HOSTED Lens (lens.cardmem.com) - createLensClient({baseUrl,token}).capture()/.runFlow（）与冷启动重试+自修复LocateSpec，和一个可选的挂载Hono代理（createLensProxy），所以一个产品前端点击/api/ Lens /\* same

## 安装

```sh
npm install @broberg/lens-client
```

也可以使用：`pnpm add @broberg/lens-client`、`yarn add @broberg/lens-client`、`bun add @broberg/lens-client`

## README

# @broberg / lens-client

一、 **用于托管Lens的瘦客户端** （`lens.cardmem.com`）. 截图页面和 通过HTTP驱动自修复流 **没有剧作家，没有浏览器** 站在你这边。

```bash
npm i @broberg/lens-client
```

## 三包分割

| 你需要…… | 使用 |
| --- | --- |
| 调用 **主持** 镜头通过HTTP（无浏览器） | **`@broberg/lens-client`** |
| 自己运行一个真正的浏览器（capture + flow） | `@broberg/lens-engine` (剧作家) |
| 创建/验证Lens会话（auth/compliance） | `@broberg/lens` (dep-free) |

## 使用(服务器端)

```ts
import { createLensClient } from "@broberg/lens-client";

const lens = createLensClient({
  baseUrl: process.env.LENS_CLOUD_URL,   // default https://lens.cardmem.com
  token: process.env.LENS_CLOUD_TOKEN,   // Bearer service token — server-side only
});

const shot = await lens.capture({ url: "https://example.com", mode: "fullPage" });
// → { run_id, screenshot_url, dom_hash, status: "ok", width, height, final_url, title }
const png = shot.screenshot_url ? await lens.fetchArtifact(shot.screenshot_url) : null;

const run = await lens.runFlow({
  base_url: "https://appstoreconnect.apple.com",
  steps: [
    { action: "goto", url: "/apps" },
    { action: "click", target: { role: "button", name: "New Version" } },  // self-healing LocateSpec
    { action: "fill",  target: { label: "Version Number" }, value: "1.2.0" },
  ],
});
```

`baseUrl`/`token` 默认为 `LENS_CLOUD_URL` / `LENS_CLOUD_TOKEN`.

## 自愈定位器

一个步骤 `target` 是一个纯字符串(CSS选择器/裸 `data-testid`)或 `LocateSpec` - - - - - - `{ testid?, css?, role?, name?, label?, placeholder?, text?, exact?, nth?, vision? }` - - - - - - 尝试固定优先级： `testid → css → role → label → placeholder → text → vision`.

每一步的结果 **`resolved_via`** （哪一层匹配）所以log a _degraded-match_ 当水流飘过时发出警报 `testid` 放到一个更模糊的图层上。

## 错误——失败的流是数据，而不是异常

一、 **失败的步骤将停止流程并固定截图**;流回来作为一个 正常结果 `status: "failed"` ——读 `steps` 看到 _哪一个_ 步骤失败 _为什么_ （永远不会抛出丢失上下文的异常）：

```ts
const run = await lens.runFlow(manuscript);
if (run.status === "failed") {
  const bad = run.steps.find((s) => s.status === "failed");
  // bad.index, bad.action, bad.error, bad.screenshot_url
}
```

只有 **传输/认证失败抛出** 一个 `LensClientError` （`.kind` ＝ `auth` 在401年, `unavailable` 在503年, `network` 后重试, `http` 否则)。

## 冷启动

托管Lens在空闲时自动停止。客户端 **预热** 与 `GET /health` 然后重试 `502` /网络错误（1-2次尝试，退出）。它 **从来没有** 重试一 `401` （坏记号）或 `503` （船暗）-那些是终端。与 `{ retries, retryBackoffMs, prewarm }`.

## 工件令牌gotcha

`screenshot_url` 点 `/artifact?key=…` 并且需要 **同样持票人** 去拿。 `fetchArtifact(url)` 连接它 **只有** 当URL为同源时 `baseUrl` - - - - - - 永远不会将令牌泄露给外国主机。

## 浏览器代理 `@broberg/lens-client/hono`

所以一个产品 **前端** 可以在没有看到代币的情况下调用Lens，安装 您自己的服务器上的代理（同源） `/api/lens/*`，令牌留在服务器端)：

```ts
import { createLensProxy } from "@broberg/lens-client/hono";

app.route("/api/lens", createLensProxy());   // token from LENS_CLOUD_TOKEN

// browser:
const lens = createLensClient({ baseUrl: "/api/lens" });   // no token in the browser
```

`hono` 是一个 **可选的对等** -仅用于代理。核心客户(`.`) **零运行时依赖项**.

## API

```ts
function createLensClient(opts?: LensClientOptions): LensClient;
//   .capture(body) → CaptureResult   .runFlow(body) → FlowResult
//   .health() → boolean              .fetchArtifact(url) → Uint8Array
function createLensProxy(opts?: LensProxyOptions): Hono;   // "@broberg/lens-client/hono"
class LensClientError extends Error;   // .kind, .status
```

麻省理工学院·一部分 [`@broberg/*`](https://github.com/broberg-ai/components) 共享库的家庭。

## 常见问题

### @broberg/lens-client 是什么？

瘦客户端为HOSTED Lens \(lens\.cardmem\.com\) - createLensClient\(\{baseUrl,token\}\)\.capture\(\)/\.runFlow（）与冷启动重试\+自修复LocateSpec，和一个可选的挂载Hono代理（createLensProxy），所以一个产品前端点击/api/ Lens /\* same

### 如何安装 @broberg/lens-client？

在项目目录运行 npm install @broberg/lens-client，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 lens-mcp，可以用 npx lens-mcp 直接运行。

### @broberg/lens-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @broberg/lens-client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @broberg/lens-client 可以商用吗？

@broberg/lens-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @broberg/lens-client 还在维护吗？

最新版本 0\.2\.0 发布于 2026/10/31（2 天前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/07/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。