echo-npm-flutter
v0.3.5
Published
Echo 窗口编排插件:工位独立步骤编排、转发任务消息,并支持 OCR 触发词自动按钮、执行记录与日志。
Readme
窗口编排插件(echo-npm-flutter)
Echo 桌面端的 npm 插件,替代旧的 echo_flutter:
- OCR 触发词自动点击:在窗口里框一块区域,识别到触发词(如
Continue)就执行按钮的编排。 - 动作编排:点击、发送文本、输入文字、回车、调用本窗口/其他窗口的按钮;支持延迟、"每 N 次执行一次"、跳过时照常执行、循环调用保护。
- 通用发送:点击输入框 → 粘贴 → 回车。编排步骤、远程消息、测试发送共用这一套。
- Echo 窗口工位:本机的窗口执行器。窗口下的每个工位有独立步骤:收到任务后激活窗口、执行编排,在「转发消息」步骤点击输入栏、粘贴本次任务并回车;停止时点击窗口的停止按钮。
- 本机消息:测试表单和插件命令投递的消息按到达顺序逐条发送,可先切到指定标签页。
- 按钮模板:把窗口配置存为模板,一键新建;支持导入/导出 JSON。
- 执行记录与日志:每次执行都有逐步记录,失败时能看到卡在哪一步、为什么。
窗口标定、工位步骤、执行记录和日志保存在本机(插件存储);Echo 工位通过接口保存在后端,与终端工位共用工位列表和任务派发。
目录
src/
domain/ 数据模型、默认值、导入校验(坐标全部是相对窗口的 0–1 比例)
store/ 可观察状态、防抖持久化、环形记录(日志/执行记录/消息)
engine/ 与 React 无关的执行引擎
runtime.ts 组装入口,UI 只和它打交道
scheduler.ts 识别循环(轮次不重叠)
detector.ts 一次截图 + 多区域 OCR,画面未变跳过识别
matcher.ts 触发词匹配(按词匹配 + OCR 易混字符容错 + 相似二次确认)
executor.ts 编排执行(门控、延迟去重、循环保护、逐步记录)
actions.ts 点击/发送/输入/回车,串行输入队列,窗口失效自动重找
messages.ts 消息收件箱与传输层(LocalTransport / 预留的 RelayTransport)
windows.ts 按应用 + 标题找回窗口
ui/ React 页面:概览、窗口、消息、执行记录、日志、模板、设置
index.tsx 插件入口
scripts/smoke.mjs 引擎冒烟测试(假桌面,不操作真实窗口)依赖宿主能力
原生能力在宿主 App(toc_task / echo_web 的 Electron)里,插件只通过 ctx.core.desktop 调用:
| 权限 | 用途 |
|------|------|
| desktop:observe | 列出窗口、截图、OCR |
| desktop:control | 点击、粘贴、按键 |
| storage:plugin | 本地保存配置和记录 |
| notifications:publish | 执行失败时发系统通知 |
| api:user | 以当前登录用户创建工位、连接设备和接收任务 |
macOS 需要给 Echo 授予「屏幕录制」和「辅助功能」,插件概览页会提示并提供授权入口。
开发
npm install
npm run typecheck
npm run smoke # 引擎冒烟测试
npm run build # 输出 dist/renderer.js + dist/renderer.css
npm run validate # 校验 package.json 里的 tocPlugin 清单
npm run dev # 监听构建@toc-starter/plugin-sdk 目前通过 file:../../script/toc_task/packages/plugin-sdk 引用,SDK 发布到私有 registry 后改成版本号。
本地调试:在 Echo 桌面端打开开发者模式,在插件中心「从本地目录加载」选择本仓库根目录,改代码后 npm run build 再重新加载插件。
发布
npm version patch
npm publish # prepack 会自动 build + validate插件命令
| 命令 | 说明 |
|------|------|
| orchestrator.start | 开始自动执行 |
| orchestrator.stop | 停止自动执行 |
| orchestrator.inject | 投递一条消息,payload:{ id?, workstation, tab?, content },workstation/tab 可用 id 或名称 |
Echo 窗口工位
一台电脑是 Echo 里的一台设备,有两个执行器:终端(toc-ocra 设备代理)和窗口(本插件)。
插件页分「本机 / 其他设备」两个页签:
- 本机:在插件中心启用插件即接入 Echo(「接收 Echo 窗口工位任务」默认开启)。顶部状态条显示本机设备、是否已在 Echo 停用(可一键重新启用),按电脑名匹配错了可「更换设备」。
- 其他设备:列出你的其他电脑的窗口执行器状态(在线 / 离线 / 已停用、窗口数、窗口工位数),可切换「接收任务」(整台设备停用 / 启用,不用动那台电脑)。窗口执行器需要那台电脑的屏幕,所以接入方式是在那台电脑上安装 Echo 桌面端并启用本插件;Linux 服务器不支持窗口控制。
- 启用插件后自动接入:按电脑名找到(或创建)这台设备,与终端代理绑定的是同一台。
- 在「窗口」页添加窗口、绑定应用窗口,标定输入栏、停止按钮。
- 在窗口的「工位(Echo)」区域点击「新建工位」,填写工位名称并选择类型。名称仅用于显示和选择,不用于 OCR。创建后可在 Echo 的 AI 输入设备/工位选择器中选择。
- 点击工位配置编排:点击、发送固定文本、输入、回车、调用按钮、等待和次数门禁,与自动按钮共用编辑器和执行引擎;也可以复制已有按钮的步骤。
- 在需要发送任务的位置添加「转发消息」。该步骤点击窗口输入栏(或步骤单独标定的位置)、粘贴本次任务内容并回车。只执行配置的步骤,不再在末尾隐式发送;旧配置读取时会保留切换步骤并追加转发步骤。
- 任务到达时先激活目标窗口,再执行工位编排。整个编排独占鼠标与键盘输入,避免自动按钮或其他任务插入;不会等待 GPT 完成上一轮回答。执行记录显示每一步,失败时后端收到失败回报。
重启与更新后的配置
桌面宿主把插件配置、窗口 ID、工位步骤及启用状态保存在固定的 userData/plugin-data 目录,独立于随机页面端口和 npm 包版本。首次使用会迁移当前页面可读取的旧配置。配置每次修改同步保存,升级或重新安装包不会清理这些数据;只有主动清理插件数据才清空。需要更新包含此存储桥接的 Echo 桌面端,旧宿主的 localStorage 仍按端口隔离。
接口(用户登录态,需 api:user):POST /api/devices/:id/workstations(新建窗口工位,与终端工位共用)、POST /api/window-agent/attach、POST /api/window-agent/heartbeat、GET /api/window-agent/devices、PUT /api/devices/:id/enabled、GET /api/window-agent/commands、POST /api/window-agent/commands/:id/result、POST /api/window-agent/runs/:id/started|finished。
