ZCode CDP Control
mcdowell8023/zcode-cdp-ctl
Controle ZCode desktop via CDP — agent de coding programável
Ver no GitHubFerramenta Python para controlar programaticamente a IDE ZCode (Zhipu GLM-5.2) via Chrome DevTools Protocol. Transforma a aplicação desktop em um agent de codificação acessível por CLI, scripts e sessões de AI Agent, permitindo automação completa do fluxo de desenvolvimento.
Instalação
npx convez-ai mcdowell8023/zcode-cdp-ctl1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de tarefas de codificação em CI/CD pipelines
- Integração de GLM-5.2 com orquestração de agents
- Processamento em batch de solicitações de geração de código
- Testes automatizados de modelos de coding
Veredito

Skill especializada para quem opera ZCode em escala. A arquitetura com fallback em 3 tiers (DOM → filesystem diff → Shadow DOM) é robusta, mas requer domínio de CDP e monitoramento da compatibilidade com atualizações do Electron. Essencial para pipelines de código que precisam do GLM-5.2 sem GUI.
README
A tradução para o português deste README ainda está na fila.
zcode-cdp-ctl
通过 Chrome DevTools Protocol 程序化控制 ZCode 桌面应用,让 GLM-5.2 可以从命令行、脚本、AI Agent 会话中调用。
它解决什么问题
ZCode 是智谱推出的 AI 编码 IDE(Electron),内置 GLM-5.2 模型 + Coding Plan 月费计费。但 ZCode 只有 GUI,没有 CLI 或 API。
本工具通过 CDP(Chrome DevTools Protocol)把 ZCode 变成可编程的 coding agent:
你的 CLI / Agent 会话 ZCode 桌面应用
┌──────────────────────┐ ┌──────────────────────┐
│ │ CDP (WS) │ │
│ zcode-ctl ask │ ──────────────>│ [contenteditable] │
│ "写个快排" │ 注入文本 │ 输入框 │
│ │ ──────────────>│ [发送] 按钮 │
│ │ 点击发送 │ │
│ │ │ GLM-5.2 推理... │
│ │<──────────────│ .is-assistant 消息 │
│ stdout: 响应文本 │ 读取 DOM │ │
│ stdout: 文件变更列表 │<──────────────│ 磁盘上的代码文件 │
│ │ 扫描文件系统 │ │
└──────────────────────┘ └──────────────────────┘
架构与工作原理
CDP 控制流
┌─────────────────────────────────────────────┐
│ ZCode (Electron 41+) │
│ │
┌─────────┐ │ ┌──────────────┐ ┌───────────────────┐ │
│ │ WS │ │ Renderer │ │ ZCode Agent │ │
│ zcode- │──────>│ │ (Chrome) │───>│ (GLM-5.2) │ │
│ ctl.py │ 9225 │ │ │ │ │ │
│ │<──────│ │ DOM 输入框 │ │ 创建/修改文件 │ │
└─────────┘ │ │ DOM 消息区 │ │ 执行命令 │ │
│ │ └──────────────┘ └───────┬───────────┘ │
│ └──────────────────────────────┼──────────────┘
│ │
│ ┌──────────────────────────────┘
│ ▼
│ ┌─────────────┐
└────>│ 工作目录 │ 文件系统 diff(tier 2)
│ --cwd │
└─────────────┘
输出三级降级策略
ZCode 在"完全访问"模式下是 agent——不只回答问题,还会创建文件、跑测试。所以输出读取分三级:
ask --cwd /project "实现一个 LRU Cache"
│
│ ┌─────────────────────────────────────────────────────────┐
├──│ Tier 1: DOM 纯文本 │
│ │ 总是输出。从 .is-assistant 读取文字段落。 │
│ │ 不涉及 Shadow DOM,最稳定。 │
│ └─────────────────────────────────────────────────────────┘
│
│ ┌─────────────────────────────────────────────────────────┐
├──│ Tier 2: 文件系统 diff │
│ │ 当 --cwd 指定且 ZCode 创建了文件时生效。 │
│ │ 发送前后对比目录 → 列出新增 (+) / 修改 (M) 的文件。 │
│ │ 代码内容直接从磁盘读,最可靠。 │
│ └─────────────────────────────────────────────────────────┘
│
│ ┌─────────────────────────────────────────────────────────┐
└──│ Tier 3: Shadow DOM 代码块提取 │
│ 当 ZCode 没创建文件(只在聊天里贴代码)时 fallback。 │
│ 穿透 <diffs-container> Shadow DOM 提取代码。 │
│ 依赖 DOM 结构,ZCode 升级可能需要更新选择器。 │
└─────────────────────────────────────────────────────────┘
环境要求
| 依赖 | 版本 | 说明 |
|---|---|---|
| macOS | 12+ | ZCode 桌面版仅支持 macOS / Windows |
| ZCode | 3.0+ | 下载地址,需注册智谱账号并开通 Coding Plan 或使用免费试用 |
| Python | 3.10+ | 脚本运行时 |
| websockets | 12.0+ | CDP WebSocket 通信(唯一第三方依赖) |
可选:
- Claude Code / OpenCode — 如果要作为 agent skill 使用
- Paseo — 如果需要跨设备 agent 编排
安装
方式 1: pip 安装(推荐)
git clone https://github.com/mcdowell8023/zcode-cdp-ctl.git
cd zcode-cdp-ctl
pip install .
# 验证
zcode-ctl --help
方式 2: 直接使用(不安装)
git clone https://github.com/mcdowell8023/zcode-cdp-ctl.git
cd zcode-cdp-ctl
pip install websockets
python3 zcode_ctl.py start
python3 zcode_ctl.py ask "hello"
方式 3: 注册为 Agent Skill
# Claude Code
ln -sf $(pwd) ~/.claude/skills/zcode-cdp-ctl
# OpenCode
ln -sf $(pwd) ~/.agents/skills/zcode-cdp-ctl
注册后,agent 会话中提到 zcode、GLM-5.2、智谱 时自动加载 SKILL.md。
快速开始
# 1. 启动 ZCode(自动开启 CDP 端口 9225)
zcode-ctl start
# 2. 纯问答
zcode-ctl ask "用 Rust 写一个 hello world"
# 3. 让 ZCode agent 在指定目录下创建文件
zcode-ctl ask "创建一个 Flask REST API 项目骨架" --cwd ~/my-project
# 4. 分步操作(send + read 分离)
zcode-ctl send "重构这段代码"
# ...等一会儿...
zcode-ctl read --wait
# 5. 查看状态
zcode-ctl status
# {"model": "GLM-5.2", "generating": false, "running": true, ...}
# 6. 关闭
zcode-ctl stop
命令参考
start
启动 ZCode 桌面应用,开启 CDP 远程调试端口。
zcode-ctl start [--port 9225] [--cwd DIR]
- 如果 ZCode 已在运行,跳过启动
--cwd:预创建工作目录(后续 send/ask 仍需单独指定 --cwd)- 等待最多 20 秒直到 ZCode 就绪
send
发送 prompt 到 ZCode,不等待响应(fire-and-forget)。
zcode-ctl send "你的 prompt" [--cwd DIR]
--cwd:自动在 prompt 前加上请在目录 {DIR} 下工作指令
ask
发送 prompt + 等待完成 + 输出响应(一条龙)。
zcode-ctl ask "你的 prompt" [--cwd DIR] [--timeout 180]
--timeout:最大等待秒数,默认 180。复杂任务(编译+测试)建议 300+- 输出按 tier 1/2/3 三级策略自动选择
read
读取最新的 assistant 响应。
zcode-ctl read [--wait] [--timeout 120]
--wait:等待当前生成完成后再读取- 同时输出文本段落和代码块
status
JSON 格式输出 ZCode 当前状态。
zcode-ctl status
{
"model": "GLM-5.2",
"generating": false,
"workspace": "MyProject",
"inputReady": true,
"running": true,
"port": 9225,
"pageId": "ABC123..."
}
stop
关闭 ZCode 进程。
zcode-ctl stop
Agent 集成指南
给其他 AI Agent 会话的安装和使用提示词
如果你需要让一个新的 Claude Code / OpenCode 会话使用本工具,把以下内容粘贴到会话中:
我需要你通过 zcode-ctl 工具把任务委派给 ZCode(智谱 GLM-5.2 模型)。
## 环境检查
1. 确认 zcode-ctl 已安装:`which zcode-ctl || python3 -c "import zcode_ctl"`
2. 如果未安装:`cd ~/Projects/skills/zcode-cdp-ctl && pip install .`
3. 确认 ZCode 桌面版在运行:`zcode-ctl status`
4. 如果没运行:`zcode-ctl start`
## 使用方式
- 发送任务并获取响应:
`zcode-ctl ask "你的任务描述" --timeout 180`
- 需要 ZCode 创建文件时,指定工作目录:
`zcode-ctl ask "创建 xxx" --cwd /path/to/project --timeout 180`
- 查看 ask 输出:
- 文本部分 = ZCode 的解释说明
- "--- File changes ---" 部分 = ZCode 在磁盘上创建/修改的文件列表
- 代码块部分 = ZCode 在聊天中输出的代码(无文件变更时的 fallback)
## 适用场景
- Claude 额度不足时,把编码任务转给 GLM-5.2
- 需要超长上下文(GLM-5.2 支持 1M tokens)
- 多模型交叉验证(用 GLM-5.2 复核 Claude 的输出)
- 需要在独立沙箱中执行代码(ZCode 有自己的执行环境)
## 注意
- ZCode 在"完全访问"模式下会直接创建文件和执行命令
- --cwd 指定的目录要合理,不要指向敏感目录
- 复杂任务超时默认 180 秒,编译/测试场景建议 --timeout 300
Paseo 集成
通过 Paseo 远程管理 ZCode:
# 查看 ZCode 状态
paseo run --provider claude --mode code -- zcode-ctl status
# 把任务委派给 ZCode
paseo run --provider claude --mode code -- zcode-ctl ask "任务" --timeout 180
DOM 选择器参考
所有选择器集中定义在 zcode_ctl.py 顶部,ZCode 升级后只需改这里:
SEL_INPUT = '[contenteditable="true"]' # 聊天输入框
SEL_SEND = 'button[aria-label="发送"]' # 发送按钮
SEL_STOP = 'button[aria-label="停止"]' # 停止按钮(生成中)
SEL_MODEL = 'button[aria-label="选择模型"]' # 模型显示
SEL_PROJECT = 'button[aria-label="选择项目"]' # 项目/工作区
SEL_ASSISTANT = '.is-assistant' # 助手消息容器
SEL_LATEST_MSG = '.latest-message' # 最新消息内容
SEL_CODE_BLOCK = 'div[data-language]' # 代码块容器
选择器基于 ZCode 3.0.x 验证。如果
status命令返回inputReady: false,说明选择器可能过期。
故障排查
| 症状 | 原因 | 解决 |
|---|---|---|
ZCode not found on port 9225 | ZCode 没带 CDP 端口启动 | zcode-ctl stop && zcode-ctl start |
send button disabled | 输入框焦点丢失 | 重试一次,通常第二次成功 |
timed out after Ns | 任务太复杂或 ZCode 在等用户确认 | 加大 --timeout,或到 ZCode GUI 里手动确认 |
| 代码块输出为空 | Shadow DOM 选择器变化 | 检查 zcode_ctl.py 顶部选择器是否匹配当前 ZCode 版本 |
status 显示 inputReady: false | ZCode 页面未完全加载 | 等几秒重试,或 stop + start |
| 端口冲突 | 9225 被占用 | --port 9226 使用其他端口 |
已知限制
- macOS only — ZCode 桌面版的 Electron 框架依赖。Windows 理论可行但未测试
- 单实例 — 同一端口只能控制一个 ZCode 实例
- DOM 耦合 — 选择器绑定 ZCode 3.0.x,版本升级可能需要更新
--cwd通过 prompt 实现 — 告知 ZCode agentcd到指定目录,非原生工作区切换,个别情况 ZCode 可能忽略指令
License
MIT