SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsgenie-editor-workflow

genie-editor-workflow

Coding & development

View repository

Updated 10-16 17:00

About this skill

Genie Editor Quick Edit Workflow

Inject the editor via the Chrome extension → CLI reads to-dos → modify code → set final status → review.

Prerequisites

1. CLI Environment

Requires @axhub/genie ≥ 0.2.4：

# 安装
npm install -g @axhub/genie

# 启动服务并指定项目目录
npx @axhub/genie --cwd /path/to/project
Confirm the service is online

npx @axhub/genie status --json


确认 `running: true` 后继续。

### 2. Chrome 扩展

用户需要安装 Axhub AI Extension。安装地址：[https://axhub.im/chrome/](https://axhub.im/chrome/)

扩展安装后，用户在浏览器中打开目标网页，扩展会自动注入 Genie Editor。

### 3. 连接检测

通过 CLI 验证扩展是否已成功连接到后端服务：

```bash
npx @axhub/genie editor clients list

Check the returned result:

  • total > 0 → at least one client is online
  • View the source field to confirm whether it comes from the Chrome extension (source: "chrome-extension"）
  • View capabilities to confirm it includes editor.snapshot、editor.nodes.list , etc.

If the list is empty, guide the user:

  1. Confirm the extension is installed and enabled
  2. Open Genie Editor on the target page (click the extension icon → launch the editor)
  3. Confirm the backend service is running (npx @axhub/genie status --json）

For the detailed extension installation and detection workflow, see references/extension-setup.md

Quick Triage

  • Need specific CLI command templates and field descriptions → open references/cli-reference.md
  • Need to understand extension installation and connection detection → open references/extension-setup.md
  • Handle editor to-dos directly → follow the main workflow below

Main Workflow

1. Confirm Service and Extension Connection

npx @axhub/genie status --json
npx @axhub/genie editor clients list

Confirm running: true, and that there is an online client. Record the channel and targetClientId。

  • Only one client → use it directly
  • Multiple clients → use pageUrl、sessionId、source to narrow the scope
  • Cannot determine safely → ask the user a brief follow-up question

Reuse the same channel + targetClientId。

2. Global Scan

Obtain at least these two sets of data:

npx @axhub/genie editor snapshot --channel <ch> --target-client-id <id>
npx @axhub/genie editor nodes list --channel <ch> --target-client-id <id> --status pending-dispatch,dirty

Process nodes by this priority:pending-dispatch → dirty → error → suspected stuck editing。

When the scan result is empty, tell the user there are currently no consumable editor to-dos, and do not force-create to-dos.

3. Claim a Node

Before starting to process a node, mark it as editing：

npx @axhub/genie editor editing set \
  --channel <ch> --target-client-id <id> \
  --element-key <key> --state editing \
  --provider codex --task-request-id <unique-id>

Requirements:

  • Generate a unique taskRequestId
  • provider fixed to codex
  • Modification succeeded → --state completed(the frontend shows a green check ✓, which is automatically cleared after 1.8s)
  • Modification failed → --state error(the frontend shows a red cross ✕, which remains on the overlay)
  • Abnormal exit → --state idle(fallback release)
  • After setting editing , the task status is persisted to localStorage and can be restored after the page is refreshed

The CLI has automatic retry capability: if it encounters CONNECTION_ERROR、CONNECTION_CLOSED or REQUEST_TIMEOUT errors, it will automatically retry once after 1 second, with no manual intervention required.

4. Collect Context

For each node, at least look at elementKey、label、changeState、taskState、hasNote、hasImages、changeKinds。

Supplement as needed:

  1. Has context images → editor context-images export --output-dir <dir>
  2. Node position unclear → editor node screenshot --element-key <key> --output-dir <dir>
  3. The screenshot returns absolutePath, directly use view_file to view

Note that context-images is page-level shared context and may not map precisely to a single node. A cross-comparison strategy is recommended:

  • First read nodes list to get annotated nodes (hasNote=true or hasImages=true）
  • Export context-images, using createdAt timestamp with node's dirtySince association
  • When uncertain, pull node screenshot for visual comparison
  • If still unable to match, use all context images as global reference

5. Implement code changes

After obtaining node information, complete the edits in the current project.

Principles:

  • Prioritize nodes explicitly requested by the user or with the greatest impact
  • Multiple nodes belonging to the same UI block → merge into one implementation batch
  • Multiple nodes are mutually independent → can be split to sub-agents (only responsible for implementation, not for client discovery and state write-back)
  • Cannot safely locate node → take screenshot first → then cross-check → if still not possible, tell the user the blocking point

6. Verification

Do at least one round of read-back:

npx @axhub/genie editor snapshot --channel <ch> --target-client-id <id>
npx @axhub/genie editor nodes list --channel <ch> --target-client-id <id> --status pending-dispatch,dirty,error,editing

If the node code has been changed but the backlog still shows dirty/pending-dispatch, do not pretend it is completed. Clearly state:

  • Page implementation is complete
  • Editor backlog still shows unconsumed
  • Mark the node as --state completed to indicate AI has finished processing

7. Set final state

Set the final state for each claimed node:

Modification successful:

npx @axhub/genie editor editing set \
  --channel <ch> --target-client-id <id> \
  --element-key <key> --state completed \
  --provider codex --task-request-id <unique-id>

Modification failed or skipped:

npx @axhub/genie editor editing set \
  --channel <ch> --target-client-id <id> \
  --element-key <key> --state error \
  --provider codex --task-request-id <unique-id>

Fallback release on abnormal exit (idle）：

npx @axhub/genie editor editing set \
  --channel <ch> --target-client-id <id> \
  --element-key <key> --state idle \
  --provider codex

Even if the task is not completed, the final state must be set, and the reason for non-completion must be clearly stated in the summary.

Communication stability

Connection status

The editor frontend tracks the WebSocket connection status in real time (connected / disconnected / reconnecting), and displays it in the UI:

  • Disconnected: yellow pulsing dot + "Reconnecting…"
  • Reconnection failed: red badge + "Connection failed"
  • Reconnection successful: automatically disappears

The frontend usesexponential backoffreconnection strategy (3s → 6s → 12s → ... → 48s, up to 10 times) to avoid instant flooding when the server restarts.

When the userswitches back to the tab, the frontend immediately checks the connection; if disconnected, it immediately initiates reconnection and resets the counter.

CLI retry

CLI has built-in automatic retry:CONNECTION_ERROR / CONNECTION_CLOSED / REQUEST_TIMEOUT will automatically retry once after 1s. Transparent and imperceptible to the AI Agent.

Task persistence

Via editing.set --state editing The external editing tasks set are synchronously persisted to localStorage:

  • After page refreshthe task state is automatically restored (overlay retains "AI editing")
  • error final state persisted for 30 minutes, still visible after refresh
  • completed final state automatically disappears after 1.8s

Stage-aware overlay

When the AI Agent executes through the built-in Genie Bridge, the editor overlay displays different text based on the AI's processing stage:

Stage Display text
thinking AI is analyzing
coding Modifying code
reviewing Checking modifications
running Genie is executing
waiting Waiting for AI response
completed Modification complete ✓
error AI modification failed ✕

For those via CLI editing.set For external tasks initiated, the overlay displays the fixed "AI editing" text (a custom message can be carried via taskRef).

Efficiency optimization suggestions

When using an AI Agent to handle editor todos, the following strategies are recommended to speed up responses:

  1. Set editing early: after reading the snapshot, immediately mark editing, so the user can see right away that the AI has claimed it
  2. Scan in one batch, process in batches: read all todos at once first, then process them one by one, avoiding repeated round-trips
  3. Small nodes first: process nodes with small change scopes first, so the user can quickly see results
  4. Parallel screenshots: if screenshots of multiple nodes are needed, multiple node screenshot requests can be initiated in parallel
  5. Throttle context-images: export global context images only once, and reuse them for subsequent nodes

Multi-node parallel strategy

Suitable for parallelism: different page sections, non-overlapping modified files, and sufficiently clear context.

Not suitable for parallelism: deeply coupled within the same component tree, depending on the same refactor, or when the positions of the nodes are not yet clear.

Retained by the main agent: client selection, node claiming/releasing, and final review.

Failure handling

In the following situations, explain the problem first; do not fake completion:

  • Service offline → guide the user to start npx @axhub/genie --cwd <path>
  • Client not found → guide the user to check the extension connection (see references/extension-setup.md）
  • Node does not exist / screenshot failed / unable to locate node → report the blocker truthfully
  • Extension WS disconnected and reconnecting → wait a few seconds and then check again clients list

When partially complete, clearly list the completed/incomplete nodes and the reasons.

Delivery requirements

The final reply must contain at least:

  • The used channel + targetClientId
  • Processed in this round elementKey
  • Which files were modified
  • The final state of each node (completed / error / idle）
  • What validations were done
  • Which nodes are still unprocessed or in an abnormal state

Reference