genie-editor-workflow（精灵编辑器工作流程）

Genie Editor 快速编辑工作流

通过 Chrome 扩展注入编辑器 → CLI 读取待办 → 修改代码 → 设置终态 → 复核。

前置条件

1. CLI 环境

需要 @axhub/genie ≥ 0.2.4：

# 安装
npm install -g @axhub/genie

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

# 确认服务在线
npx @axhub/genie status --json

确认 running: true 后继续。

2. Chrome 扩展

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

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

3. 连接检测

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

npx @axhub/genie editor clients list

检查返回结果：

• total > 0 → 至少有一个客户端在线
• 查看 source 字段确认是否来自 Chrome 扩展（source: "chrome-extension"）
• 查看 capabilities 确认包含 editor.snapshot、editor.nodes.list 等

如果列表为空，引导用户：

1. 确认扩展已安装并启用
2. 在目标页面上打开 Genie Editor（点击扩展图标 → 启动编辑器）
3. 确认后端服务正在运行（npx @axhub/genie status --json）

详细的扩展安装与检测流程见 references/extension-setup.md

快速分流

• 需要具体 CLI 命令模板和字段说明 → 打开 references/cli-reference.md
• 需要了解扩展安装与连接检测 → 打开 references/extension-setup.md
• 直接处理编辑器待办 → 按下方主流程执行

主流程

1. 确认服务与扩展连接

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

确认 running: true，且有在线客户端。记录本次任务使用的 channel 和 targetClientId。

• 只有一个客户端 → 直接使用
• 多个客户端 → 用 pageUrl、sessionId、source 缩小范围
• 无法安全判断 → 向用户补一个简短问题

整个任务复用同一个 channel + targetClientId。

2. 全局扫描

至少拿这两份数据：

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

按此优先级处理节点：pending-dispatch → dirty → error → 疑似卡住的 editing。

扫描结果为空时，告诉用户当前没有可消费的编辑器待办，不要硬编待办。

3. 领取节点

开始处理某节点前将其标记为 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>

要求：

• 每个节点生成唯一 taskRequestId
• provider 固定用 codex
• 修改成功 → --state completed（前端显示绿色勾 ✓，1.8s 后自动消除）
• 修改失败 → --state error（前端显示红色叉 ✕，保留在 overlay 上）
• 异常退出 → --state idle（兜底释放）
• 设置 editing 后，任务状态会持久化到 localStorage，页面刷新后可恢复

CLI 具备自动重试能力：如果遇到 CONNECTION_ERROR、CONNECTION_CLOSED 或 REQUEST_TIMEOUT 错误，会在 1 秒后自动重试一次，无需手动干预。

4. 收集上下文

每个节点至少看 elementKey、label、changeState、taskState、hasNote、hasImages、changeKinds。

按需补充：

1. 有上下文图片 → editor context-images export --output-dir <dir>
2. 节点位置不明确 → editor node screenshot --element-key <key> --output-dir <dir>
3. 截图返回的是 absolutePath，直接用 view_file 查看

注意 context-images 是页面级共享上下文，不一定能精确映射到单个节点。推荐交叉对比策略：

• 先读 nodes list 获取有标注的节点（hasNote=true 或 hasImages=true）
• 导出 context-images，用 createdAt 时间戳与节点的 dirtySince 关联
• 不确定时拉 node screenshot 进行视觉比对
• 仍无法对应时，将所有上下文图片作为全局参考

5. 实施代码修改

拿到节点信息后，在当前项目里完成编辑。

原则：

• 优先处理用户明确要求或影响最大的节点
• 多个节点属于同一块 UI → 合并为一个实现批次
• 多个节点互相独立 → 可拆给子代理（仅负责实现，不负责客户端发现和状态回写）
• 无法安全定位节点 → 先截图 → 再交叉判断 → 仍不行就告诉用户阻塞点

6. 验证

至少做一轮回读：

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

如果节点代码已改但 backlog 仍显示 dirty/pending-dispatch，不要假装已完成。明确说明：

• 页面实现已完成
• 编辑器 backlog 仍显示未消费
• 将节点标记为 --state completed 表示 AI 已处理完毕

7. 设置终态

对每个已领取节点设置终态：

修改成功：

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

修改失败或跳过：

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

异常退出时兜底释放（idle）：

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

任务未完成也要设置终态，同时在总结里写清未完成原因。

通信稳定性

连接状态

编辑器前端会实时跟踪 WebSocket 连接状态（connected / disconnected / reconnecting），并在 UI 上展示：

• 断线时：黄色脉搏点 + "重连中…"
• 重连失败：红色 badge + "连接失败"
• 重连成功：自动消失

前端采用指数退避重连策略（3s → 6s → 12s →... → 48s，最多 10 次），避免服务端重启时被瞬间洪泛。

当用户切换回标签页时，前端会立即检查连接，已断线则立刻发起重连并重置计数器。

CLI 重试

CLI 内置自动重试：CONNECTION_ERROR / CONNECTION_CLOSED / REQUEST_TIMEOUT 会在 1s 后自动重试一次。对 AI Agent 透明无感。

任务持久化

通过 editing.set --state editing 设置的外部编辑任务会同步持久化到 localStorage：

• 页面刷新后任务状态自动恢复（overlay 保留 "AI 编辑中"）
• error 终态 持久化 30 分钟，刷新后仍可见
• completed 终态 1.8s 后自动消除

阶段感知 overlay

当 AI Agent 通过内置 Genie Bridge 执行时，编辑器 overlay 会根据 AI 的处理阶段显示不同文案：

对于通过 CLI editing.set 发起的外部任务，overlay 显示固定的 "AI 编辑中" 文案（可通过 taskRef 携带自定义 message）。

效率优化建议

当使用 AI Agent 处理编辑器待办时，推荐以下策略加速响应：

1. 尽早 editing.set：在读取 snapshot 后立即标记 editing，让用户第一时间看到 AI 已领取
2. 批量扫描一次，分批处理：先一次性读完所有待办，再逐个处理，避免反复 round-trip
3. 小节点优先：先处理改动范围小的节点，让用户快速看到成果
4. 并行截图：如果需要多个节点的截图，可以并行发起多个 node screenshot 请求
5. 节流 context-images：全局上下文图片只导出一次，后续节点复用

多节点并行策略

适合并行：不同页面区块、改动文件不重叠、上下文已足够清楚。

不适合并行：同一组件树深度耦合、依赖同一套重构、还没搞清各节点位置。

主代理保留：客户端选择、节点领取/释放、最终复核。

失败处理

遇到以下情况，优先说明问题，不要伪造完成：

• 服务离线 → 引导用户启动 npx @axhub/genie --cwd <path>
• 找不到客户端 → 引导用户检查扩展连接（见 references/extension-setup.md）
• 节点不存在 / 截图失败 / 无法定位节点 → 如实报告阻塞点
• 扩展 WS 断开重连 → 等待几秒后重新检查 clients list

部分完成时，清楚列出已完成/未完成节点及原因。

交付要求

最终回复至少包含：

• 使用的 channel + targetClientId
• 本轮处理过的 elementKey
• 修改了哪些文件
• 各节点的终态（completed / error / idle）
• 做了哪些验证
• 还有哪些节点仍未处理或状态异常

参考