@digital-gravy/etch-connector

中文文档

0.5.3发布于 2026/11/10SEE LICENSE IN LICENSEES Module近 30 天下载 2328

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

文档目录14 节

状态
安装运行( R)
使用
1. 启动守护进程(一次)
2. 连接标签
3. 开车
产出合同(代理人)
对于人工智能特工
国际
资产
HTTP 控制 API
建筑
晚点去MCP
警卫

切换连接器

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

一个小的局部桥梁,让人工智能操纵——克洛德代码,合作,或者任何工具可以运行 shell 命令的.. 驱动一个活的 Etch 构建器标签 通过评价脚本与 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。。。 .

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

安装运行( R)

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

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

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

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

使用连接器需要有效且活跃的 Etch 许可证——见 LICENSE。。。 .

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

使用

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

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

2. 连接标签

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

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

etch.connectAs('homepage');

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

3. 开车

# 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 (没有) 实例:

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 页面存档备份,存于互联网档案馆)和各项公约用于构建页面(如区/集装箱布局图)。公众API 可能还暴露出执行共同任务的现成技能——在即兴表演。从事这项还款工作的项目惯例 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字节.

# 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 ——线条格式,从" 侧面 bridge.ts保持两者同步.
src/bridge-server.ts —— 说 BridgeServer,则运输不可知核心: 拥有套接字、音轨标签名称、关联请求、处理超时和断开. 这是可重复使用的部件 .
src/control-server.ts —— HTTP 控制 API 覆盖那个核心.
src/guidance.ts - 转出标签 etch.environment 写在作者的指令中.
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 共发布 15 个版本，首次发布于 2026/06/18；过去 12 个月发布了 15 个版本。

版本	发布日期	距今
`0.5.3`latest	2026/11/10	2 天前
`0.5.2`	2026/11/10	3 天前
`0.5.1`	2026/10/29	15 天前
`0.5.0`	2026/10/28	16 天前
`0.4.0`	2026/10/23	21 天前
`0.3.0`	2026/10/14	30 天前

关于 @digital-gravy/etch-connector 的常见问题

@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（2 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/06/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @digital-gravy/etch-connector

pnpmpnpm add @digital-gravy/etch-connector
yarnyarn add @digital-gravy/etch-connector
bunbun add @digital-gravy/etch-connector

命令行npx etch-connector

在你的项目目录中运行此命令。

近 30 天下载

2,328

约 2328 次日均 78 次

统计周期 2026/10/12 – 2026/11/10
数据来自 npm 官方下载统计，1 天前更新

最新版本0.5.3发布于 2 天前

开源许可SEE LICENSE IN LICENSE自定义许可

包体积102 kB11 个文件 · 解压后

运行依赖2 个

模块格式ES Module

TypeScript未声明类型可查找 @types/digital-gravy__etch-connector

Node.js>=18

发布版本15 个近 12 个月 15 个

首次发布2026/06/184 个月前

元数据更新2026/11/10

每一个软件包背后，
都有分享与创造的人。