# @digital-gravy/etch-connector 中文文档

规范地址：https://npmcn.com/package/%40digital-gravy/etch-connector/

版本：0\.5\.3
npm 元数据更新时间：2026-11-10T15:10:32.034Z
中文译文更新时间：2026-11-13T04:06:41.380Z
软件包许可：SEE LICENSE IN LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40digital-gravy/etch-connector
原文对照：https://npmcn.com/package/%40digital-gravy/etch-connector/?lang=original
项目主页：https://github.com/Digital-Gravy/etch-connector#readme
源码仓库：https://github.com/Digital-Gravy/etch-connector

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

- 包体积（解压后）：102 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：2 个
- 首次发布：2026-06-18T12:30:45.322Z
- 最新版本发布：2026-11-10T15:10:31.733Z
- 近 30 天下载量：2328（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

让AI驾驭的本地桥通过评价脚本与tech-public-api相比.

## 安装

```sh
npm install @digital-gravy/etch-connector
```

也可以使用：`pnpm add @digital-gravy/etch-connector`、`yarn add @digital-gravy/etch-connector`、`bun add @digital-gravy/etch-connector`

## README

# 切换连接器

> **先读这个.** 在以任何方式与 Etch 互动之前, 运行 `etch-connector --help` (或 `npx @digital-gravy/etch-connector --help`和 读取 **整个** 输出。 它记录后端,命令,旗帜 stdout/stderr/exit-code合同,以及如何拉动目前的Etch文件 - 所有需要正确驱动标签的东西 不调用其他命令 直到你读完它.

一个小的局部桥梁,让人工智能操纵——克洛德代码,合作,或者任何工具 可以运行 shell 命令的.. **驱动一个活的 Etch 构建器标签** 通过评价 脚本与 [`etch-public-api`](https://www.npmjs.com/package/@digital-gravy/etch-public-api) 水面 (`window.etch.*`) (中文(简体) ).

Etch 可脚本的 API 只存在 _浏览器内部_。没有服务器 可以直接打电话。 因此这个连接器颠倒了通常的方向: 浏览器 **拨出** 连接到一个 WebSocket 上的连接器( 和 Chrome 遥控器一样) 调试有效, 但反向), 连接器将脚本转发到标签中 将结果流回.

```
Claude Code / Cowork
      │  shell:  etch-connector eval -t homepage "return ..."
      ▼
  etch-connector  (the `serve` daemon)
      │  ▲   WebSocket  (tab dials in via etch.connectAs)
      ▼  │
  Etch builder tab  ──►  window.etch.*
```

## 状态

这个 **eval 中继器**: 绑带发送一个 JavaScript 片段, 页面运行 它作为同位函数,返回值+控制台输出返回。 没错 尚未建立 MCP 服务器- 见 [进入 MCP](https://npmcn.com/package/%40digital-gravy/etch-connector/#readme-going-to-mcp-later)。 。 。 .

脚本运行于 a **页面强制安全模式**: 脚本只看到 `etch` 财务报告和审定财务报表 标准JS内置. `window`, (中文(简体) ), `document`, (中文(简体) ), `fetch`存储, `eval`,是的,这是 扣留.

## 安装运行( R)

不需要安装——按需运行 `npx` (无)或 `bunx` (宾:

```bash
npx @digital-gravy/etch-connector serve
# or
bunx @digital-gravy/etch-connector serve
```

为了得到短 `etch-connector` 命令上 `PATH`,在全球安装:

```bash
npm install -g @digital-gravy/etch-connector   # or: bun install -g …
etch-connector serve
```

> 使用连接器需要有效且活跃的 Etch 许可证——见 [`LICENSE`](https://npmcn.com/package/%40digital-gravy/etch-connector/LICENSE)。 。 。 .

下面的例子使用光线 `etch-connector` 命令; 如果您正在通过 `npx`编号 :`bunx` 相反,用 `npx @digital-gravy/etch-connector` (或 `bunx …`) (中文(简体) ).

## 使用

### 1\. 启动守护进程(一次)

```bash
etch-connector serve
# bridge   ws://127.0.0.1:7331
# control  http://127.0.0.1:7332
```

### 2\. 连接标签

**主要方式——AI按钮.** 启用 **AI 连接器** 输入 Etch 中 设置,然后打开 Etch 构建器页面并单击 **AI 按钮** 左边 侧边栏。 它为您连接了此标签, 在您的站点名下注册( 它 ) 只是打电话 `connectAs` 盖下. 再次点击以断开 .

**二级方式——操纵台.** 您也可以从浏览器手动连接 控制台 :

```js
etch.connectAs('homepage');
```

(单位:千美元)`connectAs` 是公共 API 的一部分; 它打开了 WebSocket 回 守护进程并在给定名称下注册此标签 。 过 `{ port: <n> }` 狦 在非默认的 WebSocket 端口上启动守护进程 。 )

### 3\. 开车

```bash
# list connected tabs
etch-connector tabs

# run a script (value → stdout, console output → stderr).
# reference the API as `etch.*`.
etch-connector eval -t homepage "return etch.apiVersion"

# multi-line / from a file / from stdin
etch-connector eval -t homepage -f ./script.js
echo "return await etch.blocks.getTree()" | etch-connector eval -t homepage
```

脚本体作为一个 **aync 函数**,这样它就可以 `return` 数值和 使用顶级 `await`。将脚本写成 `etch-public-api` 地面通过 页:1 `etch` 装订( a)`window` (没有) 实例:

```js
return etch.apiVersion;
return await etch.blocks.getTree();
etch.blocks.select('block-id-123');
const groups = await etch.fields.listGroupsAsync();
return groups.length;
```

### 产出合同(代理人)

`eval` 保持整洁,这样就能够捕捉到它:

-   **静态** - 剧本的回放值,作为漂亮的JSON.
-   **标准** - 转交 `console.*` 输出, 前缀为关卡, 加 连接符注释没有这样的前缀(运行时横幅,警告) .
-   **退出代码** —— 说 `0` 成功 · `2` 剧本抛出.. `1` 操作失败 (没有这样的标签,模棱两可的目标,超时,守护进程无法到达).

## 对于人工智能特工

`etch-connector tabs` 报告,每个标签,是哪个 Etch 运行时间,是哪个 运行时返回的表面( 已删除) `etch.environment`,然后打印 编写遵循的规则:动态数据模型(数据源对 循环、 路由树、 内容模型、 媒体搜索、 名称空间 `NOT_AVAILABLE`,则 块类型运行时间可以构建。 并不是每次运行时间都会回溯到每个表面 所以 在撰写脚本之前读取 产品名称. `eval` 将目标在 stderr 上的运行时间命名为提醒,以及 `tabs --quiet` 只检查标签是否还在时, 便会丢弃散文稿 连接.

权威代理指令在 **`etch-connector --help`** - 读取 在与 Etch 交互之前的全部输出。 它覆盖后端,命令 和旗帜,stdout/stderr/exit-code合同,如何拉出当前的 Etch 文件(Context7 MCP或 [https://docs.tchwp.com/public-api 页面存档备份,存于互联网档案馆](https://docs.etchwp.com/public-api))和各项公约 用于构建页面(如区/集装箱布局图)。 公众API 可能还暴露出执行共同任务的现成技能——在 即兴表演。 从事这项还款工作的项目惯例 [`AGENTS.md`](https://npmcn.com/package/%40digital-gravy/etch-connector/AGENTS.md)。 。 。 .

## 国 际

```
etch-connector — drive a live Etch tab from the command line

Usage:
  etch-connector serve [--ws-port 7331] [--control-port 7332] [--ws-host 127.0.0.1]
  etch-connector tabs  [--json] [--quiet] [--control-port 7332] [--cdp]
  etch-connector eval  [code] [-t|--tab name] [-f|--file path] [--timeout ms] [--cdp]
  etch-connector upload   <file…> [-t name] [--alt text] [--collection id] [--compress webp:80[:maxWidth]] [--cdp]
  etch-connector download <id…>   [-t name] [-o|--out dir|file] [--force] [--cdp]
  etch-connector shot      [-t name] [-s|--selector css] [--full] [--jpeg] [-o|--out file] [--freeze=false]   (CDP)
  etch-connector html      <selector> [-t name]                                              (CDP)
  etch-connector computed  <selector> [-t name] [--props a,b,c]                               (CDP)

Two backends:
  bridge  (default) the tab dials in via etch.connectAs(); page-sandboxed.
          Scripts see only "etch" + the standard JS built-ins.
  cdp     connect OUT to a Chrome started with --remote-debugging-port=9222.
          No daemon. Runs at DevTools privilege: full "window", plus screenshots,
          rendered HTML, and computed styles. Opt in with --cdp (or --cdp-port /
          --remote-debugging-port / --cdp-host). Target a tab with -t <url|title substring>.

Examples:
  etch-connector serve
  etch-connector tabs
  etch-connector eval -t homepage "return etch.apiVersion"
  echo "return await etch.blocks.getTree()" | etch-connector eval -t homepage
  etch-connector eval -t homepage -f ./script.js
  # CDP backend (Chrome launched with --remote-debugging-port=9222):
  etch-connector tabs --cdp
  etch-connector eval --cdp -t etch "return document.title"
  etch-connector shot --cdp -t etch -s .orbit -o orbit.png
  etch-connector computed --cdp -t etch -s .orbit__chip --props transform,animation-duration
```

当一个标签被连接时, `-t` 是可选的。 您必须用多个标签 一个名字.

### 资产

这个 `assets` 能力表示完整的API(如Etch Studio). 运行时间可能 相反,报告个人能力,包括: `wpMedia`数字 :

-   `assetsRead`数字 : `listAsync` 财务报告和审定财务报表 `getAsync`。 。 。 .
-   `assetsUpload`数字 : `uploadAsync`,不压缩上传.
-   `assetsDownload`数字 : `downloadAsync`。 。 。 .
-   `assetsUpdate`数字 : `updateAsync` 页:1 `alt` 财务报告和审定财务报表 `collectionIds`,而不是文件名.
-   `assetsDelete`数字 : `deleteAsync`。 。 。 .
-   `assetsCollections`:列表,创建,更新并删除收藏.
-   `assetsCompressInPlace`数字 : `compressAsync` 与 `keepOriginal` 缺席或虚假.

所缺之旗为假. 检查 `tabs` 在选择操作之前; `upload` 需求 `assetsUpload` 财务报告和审定财务报表 `download` 需求 `assetsDownload`,除非满 `assets` 实值 备份。 该桥只搭载了JSON,因此连接器基数64-encodes字节.

```sh
# Upload a photo with alt text; prints the stored asset
etch-connector upload ./hero.jpg --alt "Team on the roof"

# Where the full assets capability is backed, optionally compress before upload
etch-connector upload ./hero.jpg --alt "Team on the roof" --compress webp:80:2400

# Write an asset's bytes to a file (or into a directory, under its own name)
etch-connector download 12 --out /tmp/hero.webp
```

`upload` 打印存储的资产(其) `id` 是什么样的 `etch/dynamic-image` `mediaId` 和 `download` 指纹 `{ id, path, bytes }`连接器 拒绝本地超过24.9 MiB 的普通上传; 此 Studio 生成的限制 适用于WordPress,它可以有自己的文件大小和MIME限制. 与 `--compress`,最多60个源的MIB可能会进入支持的运行时间 上传时间压缩. `--alt` 带 每个命令一个文件. `download` 拒绝覆盖已有文件,或拒绝 开始写一个名字 `.`,除非 `--force` 给出( 名称来自 标签。 都默认为4分钟的超时, 因为压缩了大照片在 标签慢; `--timeout` 超过它。 超时上传可能会降落 所以 检查 `etch.assets.listAsync()` 重试之前。 运行时间没有 `etch.assets` 以“ 此运行时间没有tch. assets” (exit 2) 来失败脚本 .

## HTTP 控制 API

守护进程还暴露出回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回——回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回 与未来的MCP服务器所呼叫的相同:

| 方法 | 路径 | 体质 | 回返 |
| --- | --- | --- | --- |
| 获取 | `/health` | —— 说 | `{ ok }` |
| 获取 | `/tabs` | —— 说 | `{ tabs }` |
| 邮政 | `/eval` | `{ tab?, code, timeoutMs?, mode? }` | `EvalResult` |

## 建筑

-   [`src/protocol.ts`](https://npmcn.com/package/%40digital-gravy/etch-connector/src/protocol.ts) ——线条格式,从" 侧面 `bridge.ts`保持两者同步.
-   [`src/bridge-server.ts`](https://npmcn.com/package/%40digital-gravy/etch-connector/src/bridge-server.ts) —— 说 `BridgeServer`,则 运输不可知核心: 拥有套接字、 音轨标签名称、 关联 请求、处理超时和断开. **这是可重复使用的部件 .**
-   [`src/control-server.ts`](https://npmcn.com/package/%40digital-gravy/etch-connector/src/control-server.ts) —— HTTP 控制 API 覆盖 那个核心.
-   [`src/guidance.ts`](https://npmcn.com/package/%40digital-gravy/etch-connector/src/guidance.ts) - 转出标签 `etch.environment` 写在作者的指令中.
-   [`src/cli.ts`](https://npmcn.com/package/%40digital-gravy/etch-connector/src/cli.ts) - 那个 `serve` 编号 : `tabs` 编号 : `eval` 命令.

## 晚点去MCP

今天是CLI eval中继器 未来版本将曝光与 适当的 MCP 服务器,所以 AI 管理器可以调用一等工具( 列表标签, 运行) a 脚本)直接取而代之,而不是轰出-不改变连接方式 选项卡.

## 警卫

两层,两个层都无法替代:

**交通运输.** 万事俱备 `127.0.0.1`,所以任何本地进程都可以达到 守护进程。 只用信任的机器运行, 并且不暴露端口 循环回放. 控制API拒绝任何载有 `Origin` 标题 - 浏览器总是发送一个,本地工具不会——和 `/eval` 仅需要 `application/json`,所以您访问的网页不能通过它驱动标签.

**处决.** 桥接模式将脚本运行在 a `with`\- 绑住代理 仅曝光 `etch` 加上标准的联署材料 `window`, (中文(简体) ), `document`, (中文(简体) ), `fetch`存储, `eval`, (中文(简体) ), `Function`这是.. **护栏,不是 硬化沙盒**:因为剧本分享了该页面的JS域名,a _决 定_ 作者仍然可以通过原型/构造链(例如. `({}).constructor.constructor`) (中文(简体) ). 它可靠地保持随意和AI作者 脚本 `etch` 表面并关闭明显的出逃舱门 **没有** 包含敌对密码。 对于对抗性剧本的真正界限, 只在信任的机器上运行守护进程 .

## 常见问题

### @digital-gravy/etch-connector 是什么？

让AI驾驭的本地桥通过评价脚本与tech-public-api相比\.

### 如何安装 @digital-gravy/etch-connector？

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

### @digital-gravy/etch-connector 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/digital-gravy\_\_etch-connector 是否存在。

### @digital-gravy/etch-connector 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @digital-gravy/etch-connector 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @digital-gravy/etch-connector 可以商用吗？

@digital-gravy/etch-connector 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @digital-gravy/etch-connector 的下载量有多少？

根据 npm 官方下载统计，@digital-gravy/etch-connector 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,328 次，日均约 78 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @digital-gravy/etch-connector 还在维护吗？

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