ONE-OS/axhub-make/skills/genie-editor-cli-workflow/references/cli-reference.md

CLI 命令参考

所有命令通过 npx @axhub/genie 调用，要求版本 ≥ 0.2.1。

建议在 shell 中定义变量减少重复输入：

CHANNEL="project-a"
TARGET_CLIENT_ID=""

1. 服务检查

npx @axhub/genie status --json

确认 running: true，记录 endpoint.apiBaseUrl。

2. 列出在线客户端

npx @axhub/genie editor clients list \
  --channel "$CHANNEL"

重点关注：clientId、sessionId、pageUrl、capabilities。

只有目标客户端在线且具备 editor.* 能力时，后续命令才有意义。

3. 获取编辑器快照

npx @axhub/genie editor snapshot \
  --channel "$CHANNEL" \
  --target-client-id "$TARGET_CLIENT_ID"

关注字段：resource、selectedElement、modifiedElements、textChanges、styleChanges、statusSummary。

4. 列出待处理节点

处理待办

npx @axhub/genie editor nodes list \
  --channel "$CHANNEL" \
  --target-client-id "$TARGET_CLIENT_ID" \
  --status pending-dispatch,dirty

排查卡住节点

npx @axhub/genie editor nodes list \
  --channel "$CHANNEL" \
  --target-client-id "$TARGET_CLIENT_ID" \
  --status editing,error,completed

精确查询

npx @axhub/genie editor nodes list \
  --channel "$CHANNEL" \
  --target-client-id "$TARGET_CLIENT_ID" \
  --element-key "hero-card"

每个节点的关键字段：

字段	说明
elementKey	节点唯一标识
label	CSS 选择器路径
changeState	clean / dirty / handled
taskState	idle / editing / completed / error
hasNote	是否有标注文字
hasImages	是否附带图片
changeKinds	修改类型：text / style / class
dirtySince	变脏时间戳
lastHandledAt	上次处理时间

状态别名：

• pending-dispatch = changeState=dirty && taskState=idle
• dirty / handled / editing / completed / error 直接匹配对应字段

5. 节点截图

npx @axhub/genie editor node screenshot \
  --channel "$CHANNEL" \
  --target-client-id "$TARGET_CLIENT_ID" \
  --element-key "hero-card" \
  --output-dir /tmp/axhub-genie-shot

返回 absolutePath（本地文件路径）、mimeType、width、height、size。

用途：仅靠 label 无法定位节点时，通过截图视觉确认。

6. 导出上下文图片

npx @axhub/genie editor context-images export \
  --channel "$CHANNEL" \
  --target-client-id "$TARGET_CLIENT_ID" \
  --output-dir /tmp/axhub-genie-context

返回每张图片的 absolutePath、mimeType、size。

注意：这是页面级共享上下文，未必能精准映射到单个 elementKey，需结合 note、label、截图交叉判断。

7. 设置节点编辑状态

开始处理

npx @axhub/genie editor editing set \
  --channel "$CHANNEL" \
  --target-client-id "$TARGET_CLIENT_ID" \
  --element-key "hero-card" \
  --state editing \
  --provider codex \
  --task-request-id "codex_hero-card_$(date +%s)"

处理结束

npx @axhub/genie editor editing set \
  --channel "$CHANNEL" \
  --target-client-id "$TARGET_CLIENT_ID" \
  --element-key "hero-card" \
  --state idle \
  --provider codex \
  --task-request-id "codex_hero-card_done_$(date +%s)"

说明：

• --state 只允许 editing 或 idle
• editing.set 控制 taskState，不直接改变 changeState
• 结束后仍需重新读 nodes list 确认节点最终状态

8. 推荐执行顺序

npx @axhub/genie status --json
npx @axhub/genie editor clients list --channel "$CHANNEL"
npx @axhub/genie editor snapshot --channel "$CHANNEL" --target-client-id "$TARGET_CLIENT_ID"
npx @axhub/genie editor nodes list --channel "$CHANNEL" --target-client-id "$TARGET_CLIENT_ID" --status pending-dispatch,dirty

然后按节点循环：

1. editor editing set --state editing
2. 如有需要，拉 context-images export
3. 如仍难定位，拉 node screenshot
4. 修改代码
5. 重新拉 snapshot 与 nodes list
6. editor editing set --state idle

9. 最终复核

结束前至少再跑一次：

npx @axhub/genie editor nodes list \
  --channel "$CHANNEL" \
  --target-client-id "$TARGET_CLIENT_ID" \
  --status pending-dispatch,dirty,error,editing

如果列表仍有项，区分说明：

• 页面改动是否已完成
• 编辑器 backlog 是否仍残留
• 哪些节点只是退出了 editing，但仍是 dirty

10. CLI 通用参数

参数	说明
--api-base <url>	显式指定 API Base，默认自动发现
--api-key <key>	API Key（如开启鉴权）
--channel <name>	目标业务通道
--target-client-id <id>	目标前端页面实例
--timeout-ms <ms>	请求超时
--json	显式声明 JSON 输出（editor 命令默认 JSON）
--output-dir <path>	截图/图片导出目录

统一成功返回格式：

{
  "ok": true,
  "requestId": "editor_001",
  "channel": "project-a",
  "targetClientId": "figma-123",
  "data": { ... }
}

失败时 ok: false + error.code + error.message，CLI 以非 0 退出码结束。