使用 OpenCLI 通过 CDP 控制 Qoder IDE 桌面端完整命令手册与源码原理解析【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI导读本文围绕 OpenCLI 仓库中的 Qoder 桌面适配器docs/adapters/desktop/qoder.md展开讲解如何让 AI Agent 通过 Chrome DevTools ProtocolCDP直接操作本机已登录的 Qoder IDE从带调试端口启动应用、设置环境变量到用 20 条命令完成新建会话、收发消息、读取回复、切换侧边栏与 Composer 增强等完整操作。读完后你将掌握一套可直接复制的桌面 AI IDE 自动化方案并理解其以可见 UI 为唯一事实来源的底层设计。一、背景为什么需要为 Qoder 单独做一个桌面适配器Qoder 是阿里巴巴出品的、基于 Electron / VS Code 技术栈衍生的 AI IDEbundleId: com.qoder.ide。它没有开放的 HTTP API 供外部程序调用聊天能力但作为 Electron 应用它的渲染进程本身就是一个浏览器页面天然可以通过Chrome DevTools ProtocolCDP被外部驱动。OpenCLI 正是利用这一点把 Qoder 当作一个本地网站来操控Agent 不需要任何 API Key直接复用你已在 Qoder 中登录的账号、工作区与知识库。相关的端口与进程元数据注册在 src/electron-apps.tsqoder: { port: 9237, processName: Qoder, executableNames: [Electron], bundleId: com.qoder.ide, displayName: Qoder, },从源码结构看OpenCLI 对 Qoder、ChatGPT、Trae Solo 等桌面应用采用了同一套 Electron 适配模式Qoder 的专用端口是9237。二、前置条件以调试模式启动 Qoder1. 安装 Qoder首先安装 Qoder 桌面应用macOS / Windows / Linux 均可下文命令以 macOS 路径为例。2. 带 CDP 启动Qoder 必须先以远程调试模式启动OpenCLI 才能连接。官方文档给出的启动命令为/Applications/Qoder.app/Contents/MacOS/Electron \ --remote-debugging-port9237 \ --remote-allow-origins*两点说明--remote-debugging-port9237必须与 src/electron-apps.ts 中注册的port: 9237保持一致这是 OpenCLI 发现端口的依据--remote-allow-origins*用于放开 CDP 的跨源限制否则来自非 DevTools 来源的连接请求会被 Chromium 拒绝。仓库中同样存在配套的启动脚本约定qoder-launch-with-cdp.sh见 clis/qoder/_utils.js 注释目的都是把上述命令固化下来。三、环境配置告诉 OpenCLI 去哪里连启动 Qoder 后在终端导出 CDP 端点环境变量export OPENCLI_CDP_ENDPOINThttp://127.0.0.1:9237该变量是所有桌面适配器Qoder、ChatGPT App、Trae 等通用的连接配置。设置后opencli qoder ...系列命令就会自动连接到当前 Qoder 渲染进程。四、命令全景适配器共注册 20 条命令按功能分为四组。下表来自命令注册清单见 clis/qoder/qoder.test.js 的断言标注了每条命令的读/写访问级别分组命令访问级别作用诊断qoder statusread检查 CDP 连接输出渲染进程 URL 与标题Quest 生命周期qoder newwrite新建一个 Quest会话qoder history [--limit]read列出侧边栏可见的 Questqoder read [--limit]read读取当前 Quest 中可见的对话轮次qoder send messagewrite向当前 Quest 发送消息即发即走qoder ask prompt [--timeout]write发送提示词并等待可见回复侧边栏与视图qoder sidebar-togglewrite折叠/展开 Quest 侧边栏qoder open-panelwrite开关底部面板qoder search queryread打开搜索面板并列出结果qoder settingswrite打开设置qoder knowledgewrite打开知识库视图qoder marketplacewrite打开插件市场qoder creditsread打开 Credits 用量并读取弹层qoder view-allwrite点击 Quest 列表中的 View allqoder add-workspacewrite打开添加工作区目录选择器qoder account [--username]read打开账号菜单并列出条目qoder more-actionsread打开 More Actions 并列出菜单项Composerqoder prompt-enhancewrite对当前草稿执行 Prompt Enhanceqoder open-editorwrite在编辑器视图中打开当前草稿下面按分组逐条展开用法与实现细节。五、诊断命令opencli qoder status检查当前与 Qoder 渲染进程的 CDP 连接是否正常并报告两个关键信息当前页面 URL 与页面标题。输出列为Status / Url / Title。其实现clis/qoder/status.js非常直白——通过page.evaluate读取window.location.href与document.titleUrl: await evaluateQoder(page, window.location.href), Title: await evaluateQoder(page, document.title),建议在任何自动化流程开始时先执行status确认 Qoder 已带调试端口启动、且当前处于预期的视图例如已打开某个 Quest再做后续操作。六、Quest 生命周期命令Qoder 中一次对话被称为Quest对应 VS Code 系的聊天线程围绕它有一组核心命令实现集中在 clis/qoder/quest.js。opencli qoder new新建一个 Quest。实现上不是发快捷键而是通过文本匹配点击侧边栏的New Quest按钮clis/qoder/quest.jsconst res await evaluateQoder(page, clickByTextScript([New Quest])); if (!res?.ok) throw new CommandExecutionError(res?.reason || New Quest button not found, );若按钮当前不可见命令会抛出带原因的CommandExecutionErrortyped error而不会静默失败。opencli qoder history --limit 20列出侧边栏中可见的 Quest返回Index / Title两列。--limit为可选参数默认50必须是正整数非法值抛出ArgumentError见 clis/qoder/_utils.js 的parsePositiveInt。实现要点clis/qoder/history.js在侧边栏区域[class*sidebar], [class*quest-list], [class*quest]内查找可见的可点击行通过正则过滤掉New Quest / Search / Settings / View all / Knowledge / Marketplace / Credits Usage等固定控件与包含⌘的快捷键标签对标题去重、限制长度2200 字符后返回若侧边栏太窄导致没有任何 Quest 可见会抛出EmptyResultError错误信息提示尝试拉宽侧边栏或先选择工作区。opencli qoder read --limit 30读取当前 Quest 中可见的所有对话轮次返回Index / Role / Text。--limit默认30。角色判定由 clis/qoder/_utils.js 中的QODER_TURNS_JS完成它先在聊天面板中按高度选出最大的可见面板再遍历其中的消息候选元素按 CSS 类名启发式识别Useruser/me-/right模式与Assistantassistant/ai/bot/response模式其余归为Turn同时过滤掉过短5 字符、过长4000 字符与嵌套过深children ≥ 20的干扰元素并做文本去重。每条消息文本截取前 1200 字符返回。opencli qoder read --limit 30opencli qoder send message向当前 Quest 发送一条消息fire-and-forget返回Status / Length。它的执行链路体现了以可见 UI 为事实来源的核心设计clis/qoder/quest.js先统计发送前的可见消息条数beforeCount用buildQoderInjectTextScript(text)在高置信度的 Composer 输入框中注入文本见下文Composer 识别依次尝试button[aria-labelSend message]、button[titleSend message]兜底再用文本匹配Send message / Send / 发送轮询等待消息条数增长waitForMessageCountGrowth最多 5 秒——只有确实出现了新的可见消息行命令才返回成功否则抛出CommandExecutionError。这一点也被测试显式覆盖clis/qoder/qoder.test.js点击发送后没有新增可见消息行会被断言为失败。opencli qoder ask prompt --timeout 120ask是 Agent 最常用的提问并等待回答命令返回两行结果User提示词与Assistant回复各含WaitedSeconds等待秒数。参数text位置参数提示词正文必填--timeout可选整数最大等待秒数默认120。实现上先完整复用send的注入发送逻辑然后进入轮询循环clis/qoder/quest.js每 1.5 秒统计一次可见消息条数以消息条数是否变化作为是否仍在生成的判据条数变化则重置稳定计数连续 6 次无变化约 9 秒静止且消息数确有增长时判定回复稳定稳定后调用qoderResponseAfterScript取出发送时间点之后的最新回复若超时仍未拿到回复抛出带指引的TimeoutError错误信息建议确认 Qoder 已发出提示词并完成生成再调大--timeout重试。opencli qoder ask 请帮我 review 当前工作区的代码结构 --timeout 180七、侧边栏与视图命令这组命令全部位于 clis/qoder/ui.js大部分是点击某个可见按钮 读取结果非常轻量。侧边栏与面板开关opencli qoder sidebar-toggle # 折叠/展开 Quest 列表等价 ⌘B opencli qoder open-panel # 开关底部面板Output/Terminal/Debug Console等价 ⌥⌘B两者均按可见文本匹配Collapse Quest List / Expand Quest List与Open Panel / Close Panel并返回实际命中的文本。搜索opencli qoder search query --limit 20search是少数读性质的交互命令流程分三步clis/qoder/ui.js点击Search⌘P打开搜索面板向最近挂载的可见输入框注入查询词并派发input/change事件驱动前端过滤收集[roleoption] / [rolemenuitem]中的可见选项文本截取 200 字符、去重最后按 Escape 关闭面板。--limit默认 20无匹配结果时抛出EmptyResultError。视图导航类以下命令都是点击对应按钮opencli qoder settings # 打开设置文本匹配失败时兜底按 aria-label 匹配 opencli qoder knowledge # 打开知识库视图个人/团队知识库 opencli qoder marketplace # 打开插件/技能市场 opencli qoder view-all # 点击 Quest 列表中的 View all opencli qoder add-workspace # 打开添加工作区目录选择器需要特别注意的是add-workspace它只会点开系统的目录选择对话框实际的文件夹选择必须由用户在 Qoder 界面中手动完成系统文件选择器不受 CDP 控制命令返回状态为clicked — folder picker opened (manual selection required)。信息读取类opencli qoder credits # 点击 Credits Usage读取弹层文本 opencli qoder account [--username name] # 打开账号菜单并列出菜单项 opencli qoder more-actions # 打开 More Actions 并列出菜单项credits点击后从最近出现的可见弹层[roledialog] / popover / popup提取最多 600 字符的用量文本随后按 Escape 关闭account账号按钮的标签就是当前用户名。优先使用--username显式指定未指定时通过启发式在可见按钮中排除已知控件New Quest / Search / Settings / Knowledge / Marketplace等与New/Open/Add/...开头动词反推出用户名按钮点击后读取[rolemenu] / dropdown弹层中的菜单项最多列 20 条more-actions点击后读取[rolemenuitem] / button中的菜单项并列出菜单已打开但无条目时抛EmptyResultError。八、Composer 增强命令位于 clis/qoder/composer.jsopencli qoder prompt-enhance # 点击 Prompt EnhanceQoder 会重写当前草稿以适配 LLM opencli qoder open-editor # 点击 Open Editor把聊天草稿在完整编辑器窗格中打开两者均为简单的文本匹配点击prompt-enhance成功后会提示enhanced (check composer)建议回到read确认重写后的内容。九、底层原理这些命令是如何操作真实 UI 的1. 可见性判定所有点击与读取都先经过IS_VISIBLE_JSclis/qoder/_utils.js过滤它从三个维度判定元素可见const r el.getBoundingClientRect(); if (r.width 1 || r.height 1) return false; if (cs.visibility hidden || cs.display none || cs.opacity 0) return false;因此侧边栏折叠导致按钮不可见、弹层未弹出等情况都会导致命令以 typed error 失败而不是点错元素——这正是文档 Notes 部分以可见 UI 为唯一事实来源的落地实现。2. 两种点击策略选择器点击clickFirstScript(selectors)遍历候选 CSS 选择器点击第一个可见匹配元素文本点击clickByTextScript(patterns)在button / [rolebutton] / a / [roletab]中按可见文本子串或全等匹配文本长度上限默认 60定位适合 Qoder 中大量缺少aria-label的按钮。两者都会派发完整的指针事件链pointerdown → mousedown → pointerup → mouseup → click以兼容 radix 等头部菜单库对事件序列的严格要求见 clis/qoder/_utils.js 注释。3. Composer 高置信度识别buildQoderInjectTextScriptclis/qoder/_utils.js给每个可见的contenteditabletrue编辑器打分roletextbox25包含message/prompt/ask关键词 120包含composer/input60包含optional description / user context document / knowledge则-240明确排除可选描述等干扰输入框距视口底部越近加分越多模拟输入框在屏幕下方的直觉只接受总分 ≥ 40 的最高分候选找不到时返回No high-confidence Qoder composer found.注入文本时优先用document.execCommand(insertText)走真实输入链路失败则直接写textContent并派发InputEvent。对应的选择器测试见 clis/qoder/qoder.test.js——测试明确验证高置信度主输入框被注入而 Optional description 干扰框保持不变。4. 回复获取与稳定性判定QODER_TURNS_JS负责提取对话轮次ask用消息条数增长 连续约 9 秒无变化双重条件判断回复生成完成再通过qoderResponseAfterScript(previousCount, userText)精确取出发送时间点之后、且不等于用户原文的最新回复clis/qoder/_utils.js。5. 桌面命令的公共底座status/new等命令与 ChatGPT App、Cursor 等适配器共享同一套工厂函数clis/_shared/desktop-commands.js例如makeStatusCommand与makeNewCommand后者按平台发送MetaN/ControlN而 Qoder 因 UI 特殊性改用文本匹配点击这从侧面说明各桌面适配器在统一框架下保留了各自 UI 的定制逻辑。十、测试验证与可靠性保障适配器自带完整的单元测试clis/qoder/qoder.test.js覆盖四类关键行为命令注册面断言 20 条qoder/*命令全部注册且读写访问级别与预期一致read8 条 /write12 条见上文表格工具函数unwrapEvaluateResult能解包 Browser Bridge 的{ session, data }信封parsePositiveInt对 0、非数字抛ArgumentErrorComposer 注入验证高置信度选择逻辑确保注入到正确输入框send 的证据要求只有消息条数确实增长才返回成功否则 typed-fail。这套测试与命令失败必须是 typed error的约定共同保证了Agent 调用qoder/*命令时能可靠地把失败原因反馈给上层决策而不是拿到模棱两可的返回。十一、注意事项与使用限制必须先启动后连接Qoder 未以--remote-debugging-port9237启动时status会失败请先完成第二节的启动步骤再设置OPENCLI_CDP_ENDPOINT可见性是硬约束侧边栏折叠、面板未打开、按钮在滚动区之外时点击类命令会抛 typed error。执行view-all、sidebar-toggle等命令前建议先status确认当前视图send/ask要求可见证据若 Qoder 处于生成中且界面未渲染出新消息行send可能报未出现新消息行ask则可能超时——此时应调大--timeout或确认 Quest 已打开add-workspace需要人工配合系统目录选择器无法被 CDP 驱动平台差异启动路径以 macOS 为例/Applications/Qoder.app/...Windows / Linux 请替换为对应安装路径与可执行文件名。十二、进一步阅读官方适配器文档docs/adapters/desktop/qoder.mdQoder 应用元数据端口 / bundleIdsrc/electron-apps.ts核心工具函数与页面脚本clis/qoder/_utils.jsQuest 生命周期实现new/send/askclis/qoder/quest.js侧边栏与视图命令clis/qoder/ui.jsComposer 命令clis/qoder/composer.js适配器测试clis/qoder/qoder.test.js桌面应用公共命令底座clis/_shared/desktop-commands.js【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考