editor-cli 使用指引​

启动编辑器并开启 editor-cli打开终端连接验证1. 开启编辑器端口 ​首先，确保编辑器已启动，并在编辑器中启用 editor-cli。

注： 新版 editor-cli 会自动发现编辑器注册的连接信息（编辑器启动时写入实例注册表），不再需要手动指定 --host / --port。

2. 快速上手：打开终端，输入第一条命令 ​编辑器端口开启后，就可以用命令行工具与编辑器通信了。如果你之前没用过命令行，跟着下面几步走就行。

2.1 打开 PowerShell ​按键盘上的 Win + R，输入 powershell，然后回车。你会看到一个蓝底或黑底的窗口，这就是命令行终端。

你也可以用 cmd（命令提示符），操作方式一样。本文以 PowerShell 为例。

2.2 进入工具所在目录 ​editor-cli.exe 是一个独立的可执行文件，你需要先让终端"进入"它所在的文件夹，默认在 "编辑器安装目录/bin/editor-cli.exe"。

默认 editor-cli.exe 在 ~/.eggitor/cli 目录（~/代表当前用户目录）下：

powershell

# 进入目录

cd ~/.eggitor/cli输入后回车，终端的当前路径就会变成 ~/.eggitor/cli。你可以用以下命令确认：

powershell# 查看当前所在目录

pwd

# 查看当前目录下有哪些文件（应该能看到 editor-cli.exe）

dir2.3 验证连接 ​现在输入第一条命令，检查是否能连上编辑器：

powershell.\editor-cli.exe status注意： 在 PowerShell 中运行当前目录下的 exe，需要在文件名前加 .\。如果是在 cmd 中，直接输入 editor-cli.exe status 即可。

如果看到类似以下输出，说明连接成功，可以继续使用后续命令了：

Editor Status:

running True

edit_mode True

in_game_runtime False

map_name AISkillMap

map_id 69f2f39d293aeb4c48ab43ca

editor_state idle

editor_mode se

log_file D:\u5\ed2_code\season\client\logs\editor_38564.log如果连接失败，请检查：

编辑器是否已启动editor-cli 功能是否已在编辑器中开启是否同时开了多个编辑器实例（见 多编辑器实例）2.4 命令格式说明 ​所有命令都遵循以下格式：

editor-cli.exe [命令] [选项]命令（如 status、log tail、play start）决定你要做什么选项（如 --lines、--json、--timeout）跟在命令后面举个例子：

powershell# 查看最近 20 条 error 级日志

.\editor-cli.exe log tail --lines 20 --level error

# 以 JSON 格式输出状态（便于脚本解析）

.\editor-cli.exe status --json每个命令都可以加 -h 查看帮助：

powershell.\editor-cli.exe -h

.\editor-cli.exe log tail -h2.5 小技巧 ​技巧说明Tab 键自动补全输入文件名前几个字母后按 Tab，会自动补全↑ 方向键调出上一条输入过的命令，不用重复敲Ctrl + C终止正在运行的命令右键粘贴在 PowerShell 中，选中文本后按右键即可粘贴3. 多编辑器实例 ​同时运行多个编辑器时，editor-cli 默认连接"默认实例"。可以用以下命令查看和切换：

powershell# 列出所有运行中的实例（含 pid、http 端口、地图名）

.\editor-cli.exe editor-instances list

# 切换默认实例（id 可以是 地图名 / pid / http 端口）

.\editor-cli.exe editor-instances use AISkillMap

.\editor-cli.exe editor-instances use 38564也可以对单条命令临时指定实例，不改变默认：

powershell.\editor-cli.exe status --editor-instance AISkillMap

.\editor-cli.exe log tail --editor-instance 19857全局选项 ​以下选项对所有命令生效：

选项说明--timeout <秒>请求超时时间，默认 5 秒。大地图加载、试玩启动等慢操作可适当调大--json输出原始 JSON，便于脚本解析--editor-instance 临时指定编辑器实例（地图名 / pid / http 端口），默认连默认实例-h, --help查看帮助命令详解 ​status — 查看编辑器状态 ​作用： 检查编辑器是否在线、当前地图、是否处于试玩中。这是最常用的"探活"命令。

调试场景：

不确定编辑器是否卡死时，快速确认脚本/自动化流程中作为健康检查通过 editor_state 字段轮询试玩状态（idle / playing 等）基本用法：

powershelleditor-cli.exe status输出示例：

Editor Status:

running True

edit_mode False

in_game_runtime True

map_name AISkillMap

map_id 69f2f39d293aeb4c48ab43ca

editor_state playing

editor_mode se

play_session 77389d5

log_file D:\u5\ed2_code\season\client\logs\editor_38564.log获取 JSON 格式（便于脚本解析）：

powershelleditor-cli.exe status --jsoneditor-instances — 管理编辑器实例 ​作用： 列出、切换编辑器实例。多开编辑器时使用。

powershell# 列出所有实例

editor-cli.exe editor-instances list

# 交互式选择实例，打印建议的连接命令

editor-cli.exe editor-instances list --select

# 切换默认实例（id 支持 地图名 / pid / http 端口）

editor-cli.exe editor-instances use 输出示例：

Editor instances:

[0] AISkillMap (pid=38564, http=19857, alive)

[1] TestMap (pid=41200, http=19859, alive)map — 地图管理 ​作用： 列出、查看、打开地图（本地 / 草稿 / 已发布）。

powershell# 列出所有地图（local / draft / published / all，默认 all）

editor-cli.exe map list

# 按类型和关键字过滤

editor-cli.exe map list --type local --keyword 赛车

# 交互式选择地图，打印建议的打开命令

editor-cli.exe map list --select

# 查看当前打开的地图

editor-cli.exe map current

# 打开地图（按名称搜索，唯一匹配则直接打开）

editor-cli.exe map open AISkillMap

# 按云端 map_key 打开（草稿 / 已发布）

editor-cli.exe map open --key --type draft注： 未登录编辑器时，草稿/已发布地图不可见，map list 会提示 login_required。

play — 试玩控制 ​作用： 开始、停止、重启试玩，无需在编辑器里点按钮。

powershell# 开始试玩（运行当前地图）

editor-cli.exe play start

# 停止试玩

editor-cli.exe play stop

# 重启试玩

editor-cli.exe play restart输出示例：

Playtest started (mode=se, session=47d358a).开始试玩后，编辑器会经过 entering → map-loading → playing 的过渡。可以用 status 命令轮询，等 editor_state 变为 playing 后再执行游戏内操作。play start 返回的 session id 可用于 log trace / log latest / log grep 的 --play-session 参数。

exec — 执行 Lua 代码 ​作用： 远程在编辑器环境中执行 Lua 代码。这是最强大的调试命令，可以在编辑时操作场景和 UI，也可以在调试时操控游戏内玩家。

基本用法：

powershell# 执行并直接返回结果（Lua 代码里写 return 即可拿到返回值）

.\editor-cli.exe exec "return 1 + 1"

# 输出：2

.\editor-cli.exe exec "print('hello')"

# 输出：hello指定执行上下文（世界编辑器 / SE 模式）：

powershell# 在编辑器上下文执行（默认）

.\editor-cli.exe exec "return 1+1"

# 在服务器上下文执行（试玩中的服务端逻辑）

.\editor-cli.exe exec "return 'server ok'" --context server

# 在客户端上下文执行（试玩中的客户端逻辑）

.\editor-cli.exe exec "return 'client ok'" --context client可选上下文：editor（默认）、server、client。server / client 仅在试玩进行中可用。

错误处理： Lua 语法错误或运行时错误会输出完整堆栈信息，并以非零退出码结束，便于脚本判断失败：

Execution failed: execute:1: boom

execute:1: in chunk

...调试场景：

开启/关闭试玩：见 play 命令，也可用 EditorAPI.run_game()查询场景数据：获取场景中所有单位、选中单位、单位属性操控游戏内玩家：瞬移、移动、跳跃、广播自定义事件搭建场景：批量创建组件、设置缩放和旋转编辑 UI：创建文本/按钮/图片节点、修改属性……deprecated 说明：旧版 eval 命令仍可用，等同于 exec，新脚本请使用 exec。

code — 本地代码与编辑器同步 ​作用： 把地图的脚本工程映射到本地目录，用你喜欢的编辑器写代码，再同步回编辑器。支持三方对比（本地 / 上次同步基线 / 编辑器侧），冲突可检测、可审阅。

code init — 初始化映射（每个工作区执行一次） ​powershell# 绑定到编辑器当前打开的地图

editor-cli.exe code init

# 显式指定本地地图目录

editor-cli.exe code init --map D:/u5/all_maps/3001000_复道行空

# 按地图 ID / 名称解析

editor-cli.exe code init --map-id 3001000

editor-cli.exe code init --map-name 复道行空

# 覆盖冲突的已有工作区文件

editor-cli.exe code init --force需要编辑器在线并打开目标地图（仅在线模式）。地图没有脚本时会生成默认 main.lua 脚手架，并导出 API 桩文件（EggyAPI / EggyEditorAPI / DebugTools），方便本地 IDE 补全。映射信息写入工作区的 .editorcli/code-state.json。可用 --workspace <目录> 指定工作区，默认为当前目录。code diff — 查看差异（只读，随时安全） ​powershell# 三方对比：本地 vs 上次同步基线 vs 编辑器侧

editor-cli.exe code diff

# 附带 unified diff 内容（大 diff 自动落到 artifact 文件）

editor-cli.exe code diff --show-diff每个文件会被分类为 created / updated / deleted / unchanged / conflicted。冲突是数据不是失败，退出码仍为 0。

code push — 推送本地代码到编辑器 ​powershell# 先演练，只看计划不写任何东西（强烈建议）

editor-cli.exe code push --dry-run --show-diff

# 实际推送

editor-cli.exe code push

# 允许删除编辑器侧文件（本地已删的文件）——需要同时加 --yes 确认

editor-cli.exe code push --delete --yes

# 覆盖"双侧都改过"的冲突

editor-cli.exe code push --force地图关闭时：原子写入散图目录，编辑器需重启后生效（restart_required）。地图打开时：走在线通道写入并热重载，立即生效。安全机制：双侧都修改的冲突会中止整批推送；涉及删除必须 --delete + --yes。code pull — 拉取编辑器代码到本地 ​powershell# 先演练

editor-cli.exe code pull --dry-run

# 实际拉取

editor-cli.exe code pull

# 覆盖本地冲突文件

editor-cli.exe code pull --force

# 确认删除本地文件（编辑器侧已删的文件）

editor-cli.exe code pull --yes本地有冲突修改时会以 CODE_SYNC_CONFLICT 中止，除非加 --force。

code validate — 校验本地代码（纯本地，无需编辑器） ​powershell# 校验语法结构、UTF-8 编码、世界编辑器/原点编辑器目录布局

editor-cli.exe code validate

# 严格模式：额外校验同步集的虚拟路径合法性

editor-cli.exe code validate --strict说明：这是轻量级结构检查（块/字符串/注释配对），不是完整语法解析。发现问题时以非零退出码结束，适合接入 CI。

log — 日志查看与分析 ​新版日志命令基于日志文件（默认取编辑器状态中的 log_file，也可用 --log-path 指定），不再依赖内存缓冲区。--json 输出附带日志路径来源、窗口完整性、增量游标等机器字段，便于脚本做增量读取与轮转检测。

log tail — 查看最近日志 ​powershell# 最近 100 行（默认）

editor-cli.exe log tail

# 最近 20 行

editor-cli.exe log tail --lines 20

# 按级别过滤：error | warn | info | debug

editor-cli.exe log tail --level error

# 按来源过滤：client | server | editor

editor-cli.exe log tail --source server

# 指定日志文件 / 限制读取字节数 / 严格 UTF-8 解码

editor-cli.exe log tail --log-path D:\path\to\editor_38564.log --max-bytes 2097152 --encoding utf8log grep — 按正则过滤日志 ​powershell# 关键字过滤（默认忽略大小写，带 2 行上下文）

editor-cli.exe log grep "boom"

# 正则 + 自定义上下文行数 + 大小写敏感 + 限制匹配数

editor-cli.exe log grep "attempt to (call|index)" --context 3 --case-sensitive --max-matches 20

# 限定在某次试玩会话范围内搜索

editor-cli.exe log grep "attempt to" --play-session 77389d5log trace — 结构化错误报告 ​powershell# 分析当前/最近一次试玩（默认输出 JSON）

editor-cli.exe log trace

# 人类可读文本输出

editor-cli.exe log trace --text

# 指定试玩会话 id

editor-cli.exe log trace --play-session 77389d5

# 合并外部规则文件 / 关闭多行堆栈捕获

editor-cli.exe log trace --patterns-file my-rules.json --no-multiline自动归类错误（Lua 异常、服务 meta 缺失、堆栈等），给出 freshness 判断和错误统计，适合崩溃归因。

log latest — 最近一次试玩的原始日志 ​powershell# 查看最近一次试玩的完整日志

editor-cli.exe log latest

# 指定会话 + 级别过滤

editor-cli.exe log latest --play-session 77389d5 --level errordeprecated 说明：旧版 logs、watch 命令仍可用，分别等价于 log tail；新版日志基于文件，clear-logs 已无必要。

screenshot — 截图 ​作用： 远程截取编辑器窗口或游戏画面。

powershell# 截取编辑器画面（默认保存到 <文档目录>/editor_cli_screenshots/）

editor-cli.exe screenshot editor

# 截取游戏画面，指定保存路径

editor-cli.exe screenshot game -o D:\shots\game.png

# PNG 字节直接输出到终端 stdout（便于管道处理）

editor-cli.exe screenshot editor --stdout > editor.png

# 已存在时不覆盖，自动改名加 -1/-2 后缀

editor-cli.exe screenshot editor -o D:\shots\editor.png --no-clobberdocs search — 搜索文档与 API 知识 ​作用： 搜索云端官方文档与 API 知识库，无需连接编辑器（但需要编辑器处于登录状态）。

powershell# 默认搜索编辑器使用手册

editor-cli.exe docs search "如何发布地图"

# 指定知识库：manual / game-api / editor-api / asset

editor-cli.exe docs search "如何创建 Unit" --docset game-api

editor-cli.exe docs search "官方预设单位" --docset asset

# 限制返回条数（推荐 2-3，前面的结果最相关）

editor-cli.exe docs search "如何发布地图" --limit 3知识库说明：

docset内容manual编辑器用户手册（默认）game-api运行时游戏 API（Service / Unit / Enum 等）editor-api编辑器 Lua API（用脚本操控编辑器本身）asset官方资源与预设（预设单位、官方资源列表）注：原点编辑器（fs）暂无远程知识库，仅支持世界编辑器（se）工程。未登录或 token 过期时会提示重新登录编辑器。标记 [索引型片段] 的条目是继承成员索引列表，不是 API 用法文档。

旧命令迁移对照 ​以下旧命令已标记 deprecated，仍可使用，但建议迁移到新命令：

旧命令新命令logslog tailwatchlog tail（新版日志基于文件，直接反复 tail 即可）clear-logs不再需要（文件日志无需清空缓冲区）eval exec set-default-server editor-instances use --host / --port 选项自动发现实例，用 --editor-instance 选择编辑时 API（Idle 状态） ​📖 编辑时 API 文档：世界编辑器参考 editor_sdk 各 Service 源码，原点编辑器参考 EggyEditorAPI