如何快速把 EditHere 接入 AI:edithere-cli 与 skill 完整配置指南
如何快速把 EditHere 接入 AI:edithere-cli 与 skill 完整配置指南
EditHere 是一款「截图、写下意见、直接调整布局,把修改意图一次交给 AI」的本地标注工具。本文带你用 3 个步骤把 EditHere 接入 AI:先准备好 edithere-cli 命令行,再安装配套的 edithere skill 技能,最后发起第一次标注。配置完成后,AI 可以打开你的截图或视频,等你圈画、写下意见并点击「完成并返回 AI」,它就能拿到一份带坐标的结构化反馈,直接照着改代码——比文字描述「右上角那个按钮往左挪一点」精确得多。
一、接入后你能得到什么
配置完成后,整个协作流程只有 3 步:
- AI 发起标注:你在项目里说一句「用 EditHere 让我标注这张界面」,AI 通过
edithere-cli annotate把画面打开到 EditHere。 - 你来批注:点、框、写全局意见,或者用「大爆炸」直接拖动、缩放组件;视频可以暂停到某一帧再批注。
- AI 读取反馈:你点击顶部「完成并返回 AI」后,AI 收到一份反馈 JSON——每条意见都带编号、坐标甚至移动前后的真实区域,随后开始修改。
取消或超时不会把未完成的编辑当成要求,AI 也不会替你点「完成」。
「大爆炸」功能把画面拆成可移动组件,拖动即记录布局变化,是向 AI 表达「挪到这儿、放大一点」最直观的方式:
二、第 1 步:找到 edithere-cli
edithere-cli 是 EditHere 的本地命令行入口,是 AI 与桌面程序通信的桥梁。它随程序一起发布,不需要单独安装。
安装版与免安装版的默认位置
| 环境 | edithere-cli 位置 |
|---|---|
| Windows 安装版 | %LOCALAPPDATA%\Programs\EditHere\edithere-cli.exe |
| Windows 免安装版 | 完整解压目录内(与 EditHere.exe、DLL 同目录) |
| macOS 应用包 | EditHere.app/Contents/MacOS/edithere-cli |
💡 免安装版完全可以配合 skill 使用:不必运行安装器、不必加入 PATH,只要完整解压并记住
edithere-cli的绝对路径即可。
验证 CLI 可用
用完整路径跑两个参数即可完成验证(--help、--version 不依赖桌面程序运行):
edithere-cli --version
edithere-cli --help
- Windows 安装器默认勾选「加入 PATH」,但安装完成后需要重新打开终端和 AI 工具才能读到新环境。
- macOS 的 CLI 随
.app部署,不要把 CLI 单独拷出来,保留完整应用包。 - 若
--version与status返回的版本不一致,以较低的一方判断能力——通常说明 PATH 或默认目录里还残留一份旧程序。
三、第 2 步:安装 edithere skill
程序和 skill 各干各的活:程序负责打开画面,skill 负责指导 AI 如何定位 CLI、等待你提交、再正确读取反馈。仓库内的 skills/edithere 是一个可复制的技能目录,把它放进当前 AI 工具的技能目录即可。
| AI 工具 | 技能目录(用户主目录下) |
|---|---|
| Codex | ~/.agents/skills/edithere(或已有的 ~/.codex/skills/edithere) |
| Claude Code | ~/.claude/skills/edithere |
| 其他 Agent | 使用其工具支持的 skill 目录,否则可参照 docs/AGENT-CLI.md 手动调用 CLI |
获取 skill 目录
方式一:直接复制本仓库里的目录(免安装压缩包内也附带 skills/edithere):
git clone https://gitcode.com/gh_mirrors/ed/EditHere
方式二:把配置提示词直接交给能操作本机的 AI,让它按 docs/AI-SETUP.md 自动完成「检查环境 → 下载校验 → 安装 skill → 验证」全套动作:
请按 docs/AI-SETUP.md 帮我配置 EditHere 和当前 AI 工具的 edithere skill。
先复用本机已有的程序;没有时再下载安装。不要打断我正在编辑的内容。
完成后验证命令行与 skill,告诉我怎么开始使用。
记录本机路径(免安装版必做)
在已安装的 skill 目录里保存一份 references/local-installation.md,写清 CLI 绝对路径、程序目录、版本与使用方式。AI 每次使用 skill 时先读这份记录,因此免安装版无需依赖 PATH。注意:这是本机配置,不要提交回项目仓库。
⚠️ 不要把不同版本的文件混装,也不要同时向多个目录装同名 skill;已有本地修改时先比较再更新。
四、第 3 步:验证并发起第一次标注
配置完成后,逐项确认三个状态(它们互相独立):
- CLI 可执行:
--version与--help均正常退出。 - skill 文件已就位:技能目录内容完整(含
SKILL.md)。 - 当前会话可触发:工具需重载或开新会话才能发现新 skill,复制成功 ≠ 已加载。
然后在你的项目里说:
用 EditHere 让我标注这张界面,完成后按反馈修改。
AI 会执行类似这样的命令(每轮使用唯一的新输出路径,输出文件必须尚不存在):
edithere-cli annotate 'C:\absolute\page.png' --output '.\feedback-001.json' --timeout 1800
接下来你在 EditHere 里批注,完成后点击 「完成并返回 AI」。命令在 stdout 输出一行 JSON 回执,例如:
{"ok":true,"command":"annotate","schemaVersion":"feedback-minimal-4","output":"C:/work/feedback-001.json","annotations":2,"imageIncluded":true}
annotations 是批注数量,正文在 output 指向的文件中。常见退出码速查:
| 退出码 | 含义 | 建议 |
|---|---|---|
| 0 | 成功(open/capture 仅表示受理) |
继续 |
| 4 | 当前状态忙 busy |
先处理未保存文档或进行中的会话 |
| 6 | 用户取消 | 本轮无反馈,不要沿用上次结果 |
| 7 | 等待提交超时 | 未确认前不盲目重试新一轮标注 |
| 8 | 当前环境无权访问桌面接口 | 通过工具的受控桌面入口重试 |
命令一览
| 命令 | 作用 | 是否等待你提交 |
|---|---|---|
status |
查询运行与文档状态,不启动 GUI | 否 |
open <图片/视频/项目> |
打开文件,仅请求受理 | 否 |
capture |
唤起截图 | 否 |
export <文件> --output <new.json> |
把已保存项目、图片或反馈 JSON 转为反馈 JSON(离线,不等待用户) | 否 |
annotate <文件> --output <new.json> |
打开标注会话并等待你点击完成 | 是 |
export 与 annotate 默认把原图存为 JSON 同目录的同名 PNG;--embed-image 改为内嵌,--no-image 只保留原图描述,--preview 另存带编号的 JPEG。完整参数与响应字段说明见 docs/AGENT-CLI.md。
视频同样支持:在 EditHere 中暂停到目标画面批注,导出的 video-feedback-1 每条意见都带时间戳与帧截图。视频能力要求程序版本 ≥ 0.10.0,用 --version 先确认。
五、进阶:用 MCP 连接器免 CLI 接入
如果你的 AI 工具支持 MCP(Model Context Protocol),可以直接用仓库内置的 connector/ 服务,它把 CLI 封装成 edithere_open、edithere_annotate、edithere_export 等工具,AI 无需手写命令:
node connector/mcp-server.mjs
连接器按 EDITHERE_CLI 环境变量 → PATH → 默认安装目录的顺序定位 CLI,零依赖,仅需 Node.js ≥ 18。细节见 connector/README.md。
六、常见问题速查
status返回running:false但桌面程序明明在跑:核对 CLI 与桌面程序版本,旧版本(0.9.6/0.9.7)存在端点名不一致问题,升级到 0.9.8 及以上即可。- Agent 沙箱里命令连不上桌面:
status/open/capture/annotate需要访问当前登录用户的桌面,应通过工具提供的受控桌面入口执行;--help、--version和离线export不受限。 - 输出路径报错
io_error:JSON 与配套图片必须尚不存在、父目录必须已存在;每次新会话换一个新路径,不要覆盖原文件。 - 只想手动交付:不配置 skill 也行——在 EditHere 里复制 JSON 内容与图片粘贴给任意 AI 即可,反馈不绑定任何模型服务。
小结
三步即可完成接入:定位 edithere-cli → 安装 edithere skill → 发起第一次 annotate。更多细节可以按图索骥:
- 命令行与反馈格式:docs/AGENT-CLI.md
- AI 自动安装指南:docs/AI-SETUP.md
- skill 完整说明:skills/edithere/SKILL.md
- 反馈 JSON 结构:schema/feedback-minimal-v4.schema.json
- MCP 连接器:connector/README.md



