Enso Cdp

EnsoCode CDP

Dev (!app.isPackaged) already opens 9222 in src/main/index.ts. Do not inject TEMP-DEBUG. Packaged builds stay closed.

Scripts first

免依赖脚本在 scripts/（相对本 skill 目录），优先用它们，不要重写 connect 样板：

node scripts/cdp.mjs pages                          # 列出 page 目标
node scripts/cdp.mjs eval '(async()=>{...})()'      # 主窗口执行 JS（支持 await）
node scripts/cdp.mjs eval '...' --page settings.html # 设置窗口
node scripts/cdp.mjs shot /tmp/x.png                # 截图
node scripts/cdp.mjs keys ArrowDown Enter           # 受信任按键（真实输入管线）
node scripts/cdp.mjs type '@rev'                    # 受信任文本输入
node scripts/cdp.mjs drag '<fromJS>' '<toJS>'       # 受信任鼠标拖拽（from/to 为返回 {x,y} 的 JS）

合成事件（eval 里 dispatchEvent）isTrusted=false 且不过 IME/焦点管线；排查“真实键盘行为”用 keys/type。

keys Enter 只发 rawKeyDown/keyUp，不产生字符事件，不会触发 <form> 的隐式提交；验表单回车要手发 Input.dispatchKeyEvent {type:'keyDown', text:'\r', key:'Enter', windowsVirtualKeyCode:13}，或直接点提交按钮。

鼠标拖拽 / 点击（Input.dispatchMouseEvent）

窗口必须可见：document.visibilityState === 'hidden'（窗口被遮挡/后台/另一 Space）时， Chromium 会静默丢弃 CDP 的 mousePressed/mouseReleased（mouseMoved 照常送达）—— 表现为拖拽/点击“时好时坏”，极易误判为产品 bug。Page.bringToFront 无效，要 OS 级激活：

osascript -e 'tell application "System Events" to set frontmost of (first process whose name contains "Electron") to true'

cdp.mjs drag 已内置这个检查与自动激活；手写鼠标序列时先 eval document.visibilityState 确认。

其它要点：

• dnd-kit 等 PointerSensor 库必须走真实指针管线；eval 里合成 PointerEvent/HTML5 drag 事件无效。
• 拖拽需要 press 后分段 move（越过 activation 距离阈值），落点前悬停 ~150ms 让 droppable 识别。
• 拖到“拖动中才出现的落点”（如临时 drop bar）：先 press+小幅 move 激活拖拽，再 query 落点坐标继续 move。
• 验证断言别用 class 子串（如 border-ring）：Tailwind 的 focus-within:border-ring 会让 className.includes() 永真。

隔离验证环境（不碰真实 userData）：

node scripts/mk-env.mjs /tmp/enso-x 2      # 2 个 fake provider（凭证尾号可区分）
node <repo>/scripts/fake-provider-issue-27.mjs &   # 8899；支持 [[tool:name {json}]] 指令
ENSO_USER_DATA_DIR=/tmp/enso-x ENSO_CDP_PORT=9333 pnpm dev
ENSO_CDP_PORT=9333 node scripts/cdp.mjs pages
curl -s http://127.0.0.1:8899/__requests   # 每个请求实际带的凭证尾号

隔离验证必须错开 CDP 端口：用户自己的 dev 实例（真实 userData）常驻 9222，第二个实例绑不上端口也不报错，cdp.mjs 会静默连到用户实例，写操作直接落进真实数据。动手前先 lsof -nP -iTCP:<port> -sTCP:LISTEN 确认 PID 属于隔离实例（ps -E -p <pid> 能看到 ENSO_USER_DATA_DIR）。

常用 store 入口（eval 里）：window.__stores.sessions.getState() / window.__stores.settings.getState()；window.electronAPI.* 是 preload API。

Connect（手写时才看）

1. pnpm dev is running.
2. curl -s http://127.0.0.1:9222/json/version — if this fails, restart dev (port is not HMR).
3. Pick type === "page", not json/list[0] (a browser target may come first). Main window is http://localhost:5173/index.html.

curl -s http://127.0.0.1:9222/json/list \
  | python3 -c "import json,sys; d=json.load(sys.stdin); p=next(x for x in d if x.get('type')=='page'); print(p['webSocketDebuggerUrl'])"

Node ≥ 22 has global WebSocket. Enable CDP, then evaluate with monotonic ids:

await send('Runtime.enable');
async function evalExpr(expression) {
  const res = await send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true });
  if (res.result?.exceptionDetails) throw new Error(JSON.stringify(res.result.exceptionDetails));
  return res.result?.result?.value;
}

send must map replies by id. Renderer vite root is src/renderer: dynamic import /stores/..., never /src/renderer/stores/....

Read

• Live chat: document.body.innerText (tail slice(-1200) for the latest turn). Messages are not in localStorage.
• Metadata only: localStorage['enso-conversations'] — messages is always [].
• Composer: document.querySelector('textarea').
• Diff widgets: read el.shadowRoot, not light DOM.
• Viewport: chat scroller is [data-slot=scroll-area-viewport], not window.
• Screenshot: Page.captureScreenshot { format: 'png' }.

Send (composer)

Controlled React textarea: assigning .value does not update state. Native setter + input + Enter (no Shift):

await evalExpr(`(() => {
  const ta = document.querySelector('textarea');
  const proto = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value');
  proto.set.call(ta, 'YOUR_PROMPT');
  ta.dispatchEvent(new Event('input', { bubbles: true }));
  ta.focus();
  ta.dispatchEvent(new KeyboardEvent('keydown', {
    key: 'Enter', code: 'Enter', which: 13, keyCode: 13, bubbles: true,
  }));
  return ta.value;
})()`);

Wait 5–25s for the turn, then read the text tail. Do not assert immediately.

Failed assistant text stays in the transcript. Judge “no error” on new timestamps or the tail, not the whole innerText.

After code changes

• Renderer: HMR.
• src/main / src/agent / src/preload: restart pnpm dev or CDP is still the old worker.

Do not leave test sessions, scratch scripts, or mutated settings.json / userData behind. Backup real user files before touching them; restore and checksum after.