# zcode_use_aiagent2mcps

**Repository Path**: CHN_ZC/zcode_use_aiagent2mcps

## Basic Information

- **Project Name**: zcode_use_aiagent2mcps
- **Description**: https://github.com/qadzhang/zcode_use_aiagent2mcps/
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zcode_use_acpormcps

> 一个**本地 Python wrapper + ZCode Skill**，让 ZCode 通过 **MCP 客户端** 同时驱动 **Claude Code / OpenCode / MiniMax Code CLI**，并获得原生 ACP UX（流式输出、Diff 投影、会话续接）。
>
> 本项目由 **GLM-5.3** 主导开发，**MiniMax M3**、**DeepSeek V4 Flash**、**腾讯 HY3** 协助完成。

## 这是什么

ZCode 当前是 **MCP 客户端**，但**不是 ACP 客户端**——不能在 ZCode 里直接配 `agent_servers` 把外部 Agent 当成线程接管者。

本仓库交付一个 **ZCode Skill**（在 `skills/zcode-use-cli-bridge/`），它带一个本地 Python wrapper，把三个 CLI 的能力包装成 9 个 MCP tool 暴露给 ZCode Agent：

| MCP tool | 底层 | 职责 |
|---|---|---|
| `mcp__cli-bridge__call_claude` | Claude Code | Headless spawn + `--output-format stream-json` |
| `mcp__cli-bridge__call_opencode` | OpenCode | **原生 `opencode acp`** stdio NDJSON |
| `mcp__cli-bridge__call_mmx` | MiniMax Code CLI (`mcode`) | **原生 `mcode acp`** stdio NDJSON |
| `mcp__cli-bridge__task_status` | 任务状态文件 | 查状态/结果（`wait_sec ≤25` 有界等待；未知 task_id 返回任务清单） |
| `mcp__cli-bridge__task_list` | 任务状态文件 | 列全部任务（含排队位置） |
| `mcp__cli-bridge__task_cancel` | 各路径 | 协作式取消 |
| `mcp__cli-bridge__alias` | 项目目录状态文件 | 固定「程序+模型+思考」组合 + 粘性 session |
| `mcp__cli-bridge__model_probe` | `opencode models --verbose` | 探测真实可用模型/思考档、校验模型串（问 CLI 自己，不碰其配置） |
| `mcp__cli-bridge__list_sessions` | 项目目录会话状态文件 | 读当前项目目录的 `.zcode-cli-bridge.json` |

> 三个 `call_*` 一律 **dispatch-poll 调度**（对齐 MCP Tasks 扩展与 Claude Code 后台任务模式）：后台派发 + `wait_sec`（0~25s）有界等待，窗口耗尽**不是失败**——返回 `running + task_id`，任务继续后台跑，永不超时杀，`task_status` 轮询接管。完成只认权威信号（ACP `stopReason` / claude `result` 事件 + 退出码），杜绝假完成 / 半截输出；同一 session 严格串行，并行靠多 session / 多别名。详见 `doc/需求文档.md §5`。

wrapper 是**双角色**：

- 对 **ZCode** 暴露 **MCP stdio server**（ZCode 唯一支持的协议）。
- 对 **mcode / opencode** 是 **ACP v1 client**（拿到原生 UX）。
- 对 **claude** 用 **subprocess + NDJSON 解析**（Claude Code 无 ACP）。

```
ZCode Agent
    │  MCP
    ▼
zcode_cli_bridge（skill 内的 Python wrapper）
    │  ACP     ─── mcode acp        (MiniMax Code CLI)
    │  ACP     ─── opencode acp     (OpenCode)
    │  spawn   ─── claude -p ...    (Claude Code)
```

## 三个 Agent 的协议路径（关键差异）

| Agent | 命令 | 接入方式 | ACP? |
|---|---|---|---|
| **Claude Code** | `claude` | Headless spawn + `--output-format stream-json` 解析 | ✗ 无 |
| **OpenCode** | `opencode` | **原生 `opencode acp`** stdio NDJSON | ✓ |
| **MiniMax Code CLI** | `mcode` | **原生 `mcode acp`** stdio NDJSON | ✓ |

> mcode / opencode 走原生 ACP，wrapper 实现 ACP client 拿到原生 UX；claude 没有 ACP，走 Headless spawn 解析结构化输出。

---

## 快速开始（5 步）

### 1. 装三个 Agent CLI（按需）

```bash
# Claude Code
npm install -g @anthropic-ai/claude-code

# OpenCode
npm install -g opencode-ai
# 或一键脚本：curl -fsSL https://opencode.ai/install | bash

# MiniMax Code CLI (mcode)
# Windows PowerShell
irm https://filecdn.minimax.chat/public/install.ps1 | iex
# Linux / macOS
curl -fsSL https://filecdn.minimax.chat/public/install.sh | bash
```

### 2. 装 Skill 到本机

```bash
# Linux / macOS（项目根目录下）
bash skills/zcode-use-cli-bridge/scripts/install.sh

# Windows：原生 cmd / 双击（免执行策略；也可用 Git Bash 跑 install.sh）
skills\zcode-use-cli-bridge\scripts\install.bat
```

脚本会：

1. 把 `skills/zcode-use-cli-bridge/` 复制到 `~/.agents/skills/zcode-use-cli-bridge/`。
2. 检查 Python 依赖（`mcp` / `pydantic`），缺失时给出安装提示。
3. 在 `~/.zcode/cli/config.json` 里追加 `cli-bridge` 服务配置（用 wrapper 入口的绝对路径）。
4. 探测三个 CLI 可用性，给出提示。

### 3. 重启 ZCode

让 MCP 配置生效。

### 4. 验证

启动 ZCode 新会话，在输入框打 `@`，应该能看到 9 个 tool：

- `mcp__cli-bridge__call_claude`
- `mcp__cli-bridge__call_opencode`
- `mcp__cli-bridge__call_mmx`
- `mcp__cli-bridge__task_status`
- `mcp__cli-bridge__task_list`
- `mcp__cli-bridge__task_cancel`
- `mcp__cli-bridge__alias`
- `mcp__cli-bridge__model_probe`
- `mcp__cli-bridge__list_sessions`

让 Agent 调一次试试：

> 帮我用 `call_opencode`（model=`anthropic/claude-sonnet-4-5`）检查当前项目的测试覆盖率。

### 5. 切换模型 / 多后端模型

OpenCode 的核心价值是**模型中立**——同一 CLI 里可切任意模型。在 ZCode 对话里直接传 `model` 参数：

```
> 用 call_opencode（model=z.ai/glm-4.7）补全单元测试。
> 用 call_opencode（model=anthropic/claude-opus-4-5）做架构审阅。
> 用 call_opencode（model=minimax/MiniMax-M2.7）跑回归测试。
> 用 call_opencode（model=deepseek/deepseek-reasoner）推一下这个证明。
```

模型名格式：`<provider>/<model>`，不确定就先 `model_probe` 探测校验。**思考控制默认自动取最高**（`variant` 不传 = auto：档位型取最高 / 开关型置开 / 不支持不传）、**权限默认最大**（`full`，防"读不了写不了"；跑完 `git diff` 审查改动）。多 provider / 多模型的具体配置见 OpenCode 官方文档（opencode.ai/docs）——**各 CLI 的配置是其内部事务，本 skill 不读不写不解析（黑盒）**。

### 6. 卸载

```bash
bash ~/.agents/skills/zcode-use-cli-bridge/scripts/install.sh --uninstall
```

---

## 仓库结构

```
zcode_use_acpormcps/
├── README.md                              # 本文件：项目入口
├── AGENTS.md                              # 项目专属规范
├── doc/                                   # 需求文档（人类读）
│   ├── 需求文档.md                        # 总纲（含 §5 调度与可靠性核心设计）
│   ├── 需求文档-acp.md                   # ACP v1 协议基准（opencode / mcode 共用）
│   ├── 需求文档-claude.md
│   ├── 需求文档-opencode.md
│   └── 需求文档-minimax-mmx.md
├── examples/
│   ├── USAGE.md                           # 人类使用指南（详细）
│   └── config.zcode.json                  # ZCode MCP 配置示例
└── skills/
    └── zcode-use-cli-bridge/              # ★ ZCode Skill 包
        ├── SKILL.md                       # 入口：触发条件 + 4 要素
        ├── scripts/                       # wrapper Python 代码 + 安装脚本
        │   ├── __main__.py                # 入口：python <skill根>/scripts/__main__.py
        │   ├── cli_discovery.py
        │   ├── session_manager.py
        │   ├── task_manager.py            # 任务状态机（dispatch-poll）
        │   ├── subprocess_runner.py       # claude 专用（异步 spawn + 解析）
        │   ├── output_parser.py
        │   ├── mcp_server.py
        │   ├── config.py
        │   ├── exceptions.py
        │   ├── acp_client/
        │   │   ├── __init__.py
        │   │   ├── transport.py
        │   │   ├── protocol.py
        │   │   ├── session.py
        │   │   └── events.py
        │   └── install.sh                 # 一键安装 / 卸载
        ├── references/                    # 按需加载
        │   ├── agent-selection.md
        │   ├── session-patterns.md
        │   ├── long-tasks.md
        │   ├── cross-review.md
        │   └── troubleshooting.md
        └── templates/                     # 任务模板（审查 / 商议 / 续接恢复）
            ├── audit-task.md
            ├── review-proposal.md
            └── continue-task.md
```

---

## 文档

### 项目级（人类读）

- [examples/USAGE.md](./examples/USAGE.md) — **怎么用**：切换模型、多后端模型、会话续接、长任务轮询、典型工作流、FAQ
- [doc/需求文档.md](./doc/需求文档.md) — 项目目标、边界、架构、**调度与可靠性核心设计（§5）**、子需求分拆
- [doc/需求文档-acp.md](./doc/需求文档-acp.md) — **ACP v1 协议基准**（opencode / mcode 共用）
- [doc/需求文档-claude.md](./doc/需求文档-claude.md) — Claude Code 子需求（headless 完成语义 / spawn 卫生）
- [doc/需求文档-opencode.md](./doc/需求文档-opencode.md) — OpenCode 子需求
- [doc/需求文档-minimax-mmx.md](./doc/需求文档-minimax-mmx.md) — MiniMax Code CLI 子需求

### Skill 级（Agent 读）

- [skills/zcode-use-cli-bridge/SKILL.md](./skills/zcode-use-cli-bridge/SKILL.md) — Skill 入口（YAML frontmatter + 4 要素）
- `skills/zcode-use-cli-bridge/references/agent-selection.md` — 何时用哪个 Agent
- `skills/zcode-use-cli-bridge/references/session-patterns.md` — 会话续接模式
- `skills/zcode-use-cli-bridge/references/cross-review.md` — 双 AI 交叉审查与商议工作流
- `skills/zcode-use-cli-bridge/references/troubleshooting.md` — FAQ + P1/P2 计划

---

## 关键设计

- **wrapper 不打包不发布**：纯 Python 脚本，`python <路径>/scripts/__main__.py` 直接运行。Python 依赖（`mcp` / `pydantic`）由用户自己在自己的 Python 环境里装，**不随 Skill 分发**。
- **零硬编码**：跨 Windows / macOS / Linux 三平台，所有路径用运行时探测；凭据 / Agent 配置由各 Agent 自己管理（`mcode login` / `opencode auth` / Claude Code 自己的 settings），本 skill 不管配置只管调用。
- **ACP-first UX**：mcode / opencode 走原生 ACP server，wrapper 实现 ACP client——拿到流式、Diff 投影、权限透传。
- **dispatch-poll 调度**：任务一律后台派发、先落盘再返回（状态在文件不在进程）、单次 tool 调用 <25s 必返回、永不超时杀；完成只认权威信号（ACP `stopReason` / claude `result` 事件 + 退出码），同 session 严格串行——解决子 agent"最终状态反馈不正常"与"执行顺序不受控"。
- **OpenCode 多 provider 多模型**：模型**先探测后使用**（`model_probe` 问 CLI 自己拿真实可用表 + 思考档）；各 CLI 配置是黑盒（不读不写不生成）；一个 `opencode acp` 后端承载多个别名各用不同模型（按 session 生效）。
- **会话续接**：`session_id` 由 ZCode 记住并回传（会话管理是 ZCode 的工作，wrapper 无状态）；确需记录时落当前项目目录的 `.zcode-cli-bridge.json`——项目是 git 仓库时自动加入 `.gitignore`，不上传。

---

## 与前置文档的关系

前期调研报告（讲 ZCode / 三个 CLI 各自的能力，本地文档未随仓库分发）。本项目是基于该调研的**实现方案**——以 Skill 形式交付。

## 演进路径

- **P1**：ACP 路径的 `session/request_permission` 透传给 ZCode Agent；OpenCode 多 provider 配置示例完整化；`mcode` 多模态能力扩展。
- **P2**：wrapper 升级 HTTP/SSE，让 ZCode 通过 HTTP MCP 类型接入，支持流式输出。
- **将来**：ZCode 原生支持 ACP 时，wrapper 直接切换为 ACP server（acp_client 反转角色）。

## 许可

本仓库代码采用 MIT License。第三方 CLI（Claude Code / OpenCode / MiniMax Code CLI）遵循各自的许可协议。