convez.ai
SkillAutomaçãoAvançado
mcdowell8023

ZCode CDP Control

mcdowell8023/zcode-cdp-ctl

Controle ZCode desktop via CDP — agent de coding programável

Ver no GitHub
InicialPluginScore · de 0 a 100

Ferramenta 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-ctl

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 升级可能需要更新选择器。              │
     └─────────────────────────────────────────────────────────┘

环境要求

依赖版本说明
macOS12+ZCode 桌面版仅支持 macOS / Windows
ZCode3.0+下载地址,需注册智谱账号并开通 Coding Plan 或使用免费试用
Python3.10+脚本运行时
websockets12.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 9225ZCode 没带 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: falseZCode 页面未完全加载等几秒重试,或 stop + start
端口冲突9225 被占用--port 9226 使用其他端口

已知限制

  • macOS only — ZCode 桌面版的 Electron 框架依赖。Windows 理论可行但未测试
  • 单实例 — 同一端口只能控制一个 ZCode 实例
  • DOM 耦合 — 选择器绑定 ZCode 3.0.x,版本升级可能需要更新
  • --cwd 通过 prompt 实现 — 告知 ZCode agent cd 到指定目录,非原生工作区切换,个别情况 ZCode 可能忽略指令

License

MIT

Ver o original no GitHub

Bom para

Relacionados