73 lines
4.2 KiB
Markdown
73 lines
4.2 KiB
Markdown
---
|
||
description: How to CLI-ify and automate any Electron Desktop Application via CDP
|
||
---
|
||
|
||
# CLI-ifying Electron Applications (Skill Guide)
|
||
|
||
Based on the successful extraction and automation of **Antigravity** and **OpenAI Codex** desktop apps, this guide serves as the standard operating procedure (SOP) for adapting ANY Electron-based application into an OpenCLI adapter.
|
||
|
||
## 核心原理 (Core Concept)
|
||
Electron 应用本质上是运行在本地的 Chromium 浏览器实例。只要在启动应用时暴露了调试端口（CDP，Chrome DevTools Protocol），我们就可以利用 Playwright MCP 直接穿透其 UI 层，获取并操控包括 React/Vue 组件、Shadow DOM 等在内的所有底层状态，实现“从应用外挂入自动化脚本”。
|
||
|
||
### 启动 Target App
|
||
要在本地操作任何 Electron 应用，必须先要求用户使用以下参数注入调试端点：
|
||
```bash
|
||
/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=9222
|
||
```
|
||
|
||
## 标准适配模式：The 5-Command Pattern
|
||
|
||
适配一个新的 App，必须在 `src/clis/<app_name>/` 下实现这 5 个标准化指令：
|
||
|
||
### 1. `status.ts` (连接测试)
|
||
负责确认应用监听正确。
|
||
- **机制**: 直接 `export const statusCommand = cli({...})`
|
||
- **核心代码**: 获取 `window.location.href` 与 `document.title`。
|
||
- **注意**: 必须指明 `domain: 'localhost'` 和 `browser: true`。
|
||
|
||
### 2. `dump.ts` (逆向工程核心)
|
||
很多现代 App DOM 极其庞大且混淆。**千万不要直接猜选择器**。
|
||
首先编写 dump 脚本，将当前页面的 DOM 与 Accessibility Tree 导出到 `/tmp/`，方便用 AI (或者 `grep`) 提取精确的容器名称和 Class。
|
||
```typescript
|
||
const dom = await page.evaluate('document.body.innerHTML');
|
||
fs.writeFileSync('/tmp/app-dom.html', dom);
|
||
const snap = await page.snapshot({ interactive: false });
|
||
fs.writeFileSync('/tmp/app-snapshot.json', JSON.stringify(snap, null, 2));
|
||
```
|
||
|
||
### 3. `send.ts` (高级注入技巧)
|
||
Electron 应用常常使用极端复杂的富文本编辑器（如 Monaco, Lexical, ProseMirror）。直接修改元素的 `value` 常常会被 React 状态机忽略。
|
||
- **最佳实践**: 使用 `document.execCommand('insertText')` 完美模拟真实的人类复制粘贴输入流，完全穿透 React state。
|
||
```javascript
|
||
// 寻路机制：优先尝试寻找 contenteditable
|
||
let composer = document.querySelector('[contenteditable="true"]');
|
||
composer.focus();
|
||
document.execCommand('insertText', false, "你好");
|
||
```
|
||
- **提交快捷键**: `await page.pressKey('Enter')`。
|
||
|
||
### 4. `read.ts` (上下文解析)
|
||
不要提取整个页面的文本。应该利用 `dump.ts` 抓取出来的特征寻找真正的“对话容器”。
|
||
- **技巧**: 检查带有语义化结构的数据，例如 `[role="log"]`、`[data-testid="conversation"]` 或是 `[data-content-search-turn-key]`。
|
||
- **格式化**: 拼接抓取出的文本转粗暴渲染成 Markdown 返回，这样不仅你和人类能读懂，LLM 后续作为 Agent 也能精准切分。
|
||
|
||
### 5. `new.ts` / Action Macros (底层事件模拟)
|
||
许多图形界面操作难以找到按钮实例，但它们通常响应原生快捷键。
|
||
- **最佳实践**: 模拟系统级快捷键直接驱动 `(Meta+N / Control+N)`。
|
||
```typescript
|
||
const isMac = process.platform === 'darwin';
|
||
await page.pressKey(isMac ? 'Meta+N' : 'Control+N');
|
||
await page.wait(1); // 等待重渲染
|
||
```
|
||
|
||
## 全局环境变量
|
||
为了让 Core Framework 挂载到我们指定的端口，必须在执行指令前（或在 README 中指导用户）注入目标环境端口：
|
||
```bash
|
||
export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
|
||
```
|
||
|
||
## 踩坑避雷 (Pitfalls & Gotchas)
|
||
1. **端口占用 (EADDRINUSE)**: 确保同一时间只能有一个 App 占据一个端口。如果同时测试 Antigravity (9224) 且你要测试别的 App (9222)，要将 CDP Endpoint 分配开来。
|
||
2. **TypeScript 抽象**: OpenCLI 内部封装了 `IPage` 类型（`src/types.ts`），不是原生的 Playwright Page。要用 `page.pressKey()` 和 `page.evaluate()`，而非 `page.keyboard.press()`。
|
||
3. **延时等待**: DOM 发生剧烈变化后，一定要加上 `await page.wait(0.5)` 到 `1.0` 给框架反应的时间。不要立刻 return 导致连接 prematurely 阻断。
|