main-router
Intelligent skill router that analyzes user requests and automatically dispatches to the most appropriate skill(s) or zen-mcp tools. Routes
Open source Repository Open in the app JSON README (API)
About
Intelligent skill router that analyzes user requests and automatically dispatches to the most appropriate skill(s) or zen-mcp tools. Routes to zen-chat for Q&A, zen-thinkdeep for deep problem investig
Details
- Kind
- Agent skills
- Topic
- No topic detected
- Publisher
- vcnoc
- Origin
- majiayu
- Category
- ferramentas
- Stars
- 105
- Forks
- 10
- Last push
- 2025-12-21T08:51:53Z
- Repository state
- ativo
- Language
- Python
- License
- Apache-2.0
- Added
- 2026-08-30 15:40:14
- Updated
- 2026-08-30 15:40:14
- Origin id
vcnoc/claude-code-zen-mcp-skill-work/development/main-router@main
README
# Claude Code Zen MCP Skill Work
[](LICENSE)
[](https://github.com/VCnoC/Claude-Code-Zen-mcp-Skill-Work)
> 🚀 **一个为 AI 编程智能体设计的、开箱即用的规则体系与技能包。**
本项目不仅仅是工具的集合，更是一套标准化的工作流程和质量保障机制。它通过智能路由、多阶段工作流和自动化代码审查，赋能 AI 智能体以更高效、更可靠的方式完成复杂的编程任务。
---
## ✨ 核心特性
- 🔗 **CLI 桥接能力**: 使 AI 智能体能通过 Zen MCP 自主调用外部命令行工具（如 Codex CLI, Gemini CLI），实现跨工具协作。
- 🧠 **智能路由 (`main-router`)**: 根据用户意图自动选择最合适的技能，是整个系统的“大脑”。
- 📊 **结构化工作流 (P1-P4)**: 将复杂的开发任务分解为分析、方案、执行、修复四个标准阶段，确保流程清晰可控。
- 📝 **自动化规划 (`plan-down`)**: 告别手动任务分解，自动生成结构化的 `plan.md`，并支持多模型验证。
- 🔍 **5维代码审查 (`codex-code-reviewer`)**: 从质量、安全、性能、架构和文档五个维度对代码进行全面审查和打分。
- 📄 **专业文档生成 (`simple-gemini` & `deep-gemini`)**: 自动生成和维护项目知识库 (`PROJECTWIKI.md`)、变更日志 (`CHANGELOG.md`) 和深度技术分析报告。
- 🤖 **全自动模式**: 支持“一句话需求，全自动开发”模式，AI 可自主完成从规划到代码实现、审查、测试和文档更新的全过程。
## 🏗️ 工作原理
系统通过一个四阶段（P1-P4）的工作流来处理用户请求，由 `main-router` 统一调度。这个流程确保了每个任务都经过充分的分析、严谨的规划和严格的质量验证。
```mermaid
flowchart LR
A[用户请求] --> B(main-router<br/>意图识别与路由)
B --> C[P1: 分析问题<br/>理解需求，定位根因]
C --> D[P2: 制定方案<br/>调用 plan-down 生成 plan.md]
D --> E[P3: 执行方案<br/>编码、测试、文档更新]
E --> F{成功?}
F -->|是| G[✅ 完成]
F -->|否| H[P4: 错误处理<br/>修复问题并通过回归闸门验证]
H --> G
```
> 深入了解架构设计、状态机和数据模型，请查阅 **[PROJECTWIKI.md](./PROJECTWIKI.md)**。
## 🎯 核心技能包
本项目提供了一套即插即用的核心技能，每个技能都为 AI 智能体赋予一项专业能力。
| 技能 | 核心职责 | 主要产出 |
|-----------------------|------------------------------------|--------------------------------|
| `main-router` | **智能路由与任务调度** | 路由决策、全局状态管理 |
| `plan-down` | **任务分解与计划生成** | `plan.md` 文件 |
| `codex-code-reviewer` | **5维度代码质量审查与自动修复** | 质量报告、修复后的代码 |
| `simple-gemini` | **标准文档与测试代码生成** | `README`, `PROJECTWIKI`, 测试文件 |
| `deep-gemini` | **深度技术分析与报告生成** | 架构/性能分析报告 |
## 🚀 快速开始
### 1. 环境要求
- **[Python](https://www.python.org/)** >= 3.8**
- **[Git](https://git-scm.com/downloads)**
### 2. 安装步骤
本仓库包含了 **Zen MCP Server** 和 **核心技能包**，只需三步即可完成安装。
**第一步：克隆仓库**
```bash
git clone https://github.com/VCnoC/Claude-Code-Zen-mcp-Skill-Work.git
cd Claude-Code-Zen-mcp-Skill-Work
```
**第二步：运行一键安装脚本**
脚本将自动完成 Zen MCP Server 的安装、技能包的复制和全局规则的配置。
- **Linux / macOS**:
```bash
chmod +x install.sh && ./install.sh
```
- **Windows**:
```powershell
.\install.ps1
```
> **💡 提示**: 如果一键脚本不可用（例如从 GitHub 克隆的版本），请使用下面的手动安装步骤。
#### Linux / macOS 手动安装
```bash
# 1. 复制并安装 Zen MCP Server
cp -r zen-mcp-server ~/zen-mcp-server
cd ~/zen-mcp-server
pip3 install -r requirements.txt
cd ..
# 2. 复制技能包、共享资源和全局规则
mkdir -p ~/.claude/skills
cp -r skills/* ~/.claude/skills/
cp -r references ~/.claude/references
cp CLAUDE.md ~/.claude/CLAUDE.md
```
#### Windows 手动安装
```powershell
# 1. 复制并安装 Zen MCP Server
Copy-Item -Path ".\zen-mcp-server" -Destination "$env:USERPROFILE\zen-mcp-server" -Recurse
cd "$env:USERPROFILE\zen-mcp-server"
pip install -r requirements.txt
cd $OLDPWD
# 2. 复制技能包、共享资源和全局规则
New-Item -ItemType Directory -Path "$env:USERPROFILE\.claude\skills" -Force
Copy-Item -Path ".\skills\*" -Destination "$env:USERPROFILE\.claude\skills\" -Recurse
Copy-Item -Path ".\references" -Destination "$env:USERPROFILE\.claude\references" -Recurse
Copy-Item -Path ".\CLAUDE.md" -Destination "$env:USERPROFILE\.claude\CLAUDE.md"
```
**手动安装核心步骤总结**：
1. 复制 `zen-mcp-server/` 到用户目录并安装依赖
2. 创建 `~/.claude/` 目录结构（如不存在）
3. 复制 `skills/` 下的所有技能文件到 `~/.claude/skills/`
4. 复制 `references/` 文件夹到 `~/.claude/references/`
5. 复制 `CLAUDE.md` 到 `~/.claude/CLAUDE.md`
> **📁 最终目录结构**：`~/.claude/` 包含 `skills/`、`references/` 和 `CLAUDE.md` 三个核心组件
### 3. 配置与启动
**第一步：配置 API Keys**
编辑位于 `~/zen-mcp-server/.env` (或 `%USERPROFILE%\zen-mcp-server\.env`) 的配置文件，填入您的 API Keys。
```dotenv
# OpenAI API Key (用于代码审查等)
OPENAI_API_KEY=sk-your-openai-api-key-here
# Google Gemini API Key (支持原生格式和 OpenAI 兼容格式)
GEMINI_API_KEY=your-gemini-api-key-here
# ⚠️ 强烈建议：指定允许的模型，避免意外高额费用
OPENAI_ALLOWED_MODELS=gpt-4-turbo,gpt-4o
# 可选：使用自定义 API 端点（Ollama、vLLM、LM Studio 等本地模型）
# CUSTOM_API_URL=http://localhost:11434/v1 # API 端点（必须以 /v1 结尾）
# CUSTOM_API_KEY= # API 密钥（Ollama 留空）
# CUSTOM_MODEL_NAME=llama3.2 # 默认模型名称
```
> **💡 使用本地模型**：如需使用 Ollama、vLLM 或 LM Studio 等本地推理服务，配置上述 `CUSTOM_API_*` 参数即可。若需自定义模型能力（扩展推理、视觉等），可在 `zen-mcp-server/conf/custom_models.json` 中添加模型配置。
**第二步：启动 Zen MCP Server**
```bash
cd ~/zen-mcp-server
# 推荐：使用启动脚本（自动配置环境）
# Linux/Mac 用户
chmod +x run-server.sh
./run-server.sh
# Windows 用户
.\run-server.ps1
# 或直接运行
python3 server.py # Linux/Mac
python server.py # Windows
启动脚本会提供交互式配置选项，根据实际情况选择后，会自动将 MCP 配置写入 .claude.json 文件
```
### 4. 重启 Claude code
完全关闭 Claude code，然后重新启动。
---
## ✅ 验证安装
启动 Claude code，输入：
```
请使用 main-router 帮我分析当前可用的技能
```
如果能看到 `main-router`, `plan-down` 等5个技能的详细说明，则表示安装成功！
---
## 📖 使用示例
### 交互模式 (默认)
在默认模式下，AI 会在关键决策点寻求您的确认，确保您对开发过程有完全的控制。
**示例：**
> `帮我重构一下 auth.py 文件，提高其可读性。`
**AI 的响应流程：**
1. **P1 分析**: AI 分析 `auth.py`，识别出可重构的关键区域（如复杂的函数、重复的代码块）。
2. **P2 方案**: AI 提出一个重构计划（`plan.md`），例如：“将 `authenticate_user` 函数拆分为三个独立的私有函数”，并等待您的批准。
3. **P3 执行**: 在您确认后，AI 执行重构，并通过 `codex-code-reviewer` 验证代码质量。
### 全自动模式
对于信任度高的任务，您可以授权 AI 全自动完成，无需人工干预。
**示例：**
> `全程自动化，为我的 Flask 应用增加一个使用 SQLite 的用户注册功能，测试覆盖率不低于85%。`
**AI 的响应流程：**
1. **自动规划**: AI 调用 `plan-down` 制定详细的开发步骤。
2. **自动执行**: 创建数据库模型、编写后端路由、生成前端模板。
3. **自动审查与测试**: 每一步代码都由 `codex-code-reviewer` 自动审查。AI 还会调用 `simple-gemini` 编写测试用例，确保覆盖率达到85%。
4. **自动记录**: 所有决策和操作都会被记录在 `auto_log.md` 中，供您随时审计。
---
## 💡 核心理念
本项目的规则和技能设计遵循以下核心理念，这些理念定义在全局配置文件 `CLAUDE.md` 中。
- **G1: 文档一等公民**: 代码的任何变更都必须同步更新到 `PROJECTWIKI.md` 和 `CHANGELOG.md`，确保文档与代码的绝对一致。
- **G8: 强制技能使用 (反偷懒原则)**: 关键任务（如规划、代码审查、文档生成）必须由最专业的技能执行，杜绝“主模型”直接处理，以保证输出质量。
- **G9: 可量化的质量目标**: 所有开发活动都应围绕明确的质量指标进行，例如，测试覆盖率目标 (`coverage_target`) 必须在任务开始时设定。
---
## 📚 文档中心
| 文档 | 内容描述 |
|----------------------------------------------------------------|----------------------------------------------------------|
| **[PROJECTWIKI.md](./PROJECTWIKI.md)** | **项目知识库 (核心)**：架构设计、决策记录、模块文档。 |
| **[CLAUDE.md](./CLAUDE.md)** | **全局规则**: 定义了 G1-G11 全局规则和 P1-P4 工作流。 |
| **[CHANGELOG.md](./CHANGELOG.md)** | **变更日志**: 记录了项目的所有版本变更历史。 |
| **[skills/shared/tool_parameter_contract.md](./skills/shared/tool_parameter_contract.md)** | **工具参数契约**: Zen MCP Server 中所有工具的详细参数说明。 |
---
## 🙏 致谢
本项目的实现离不开以下优秀开源项目的启发和支持：
- **[HelloAgents](https://github.com/hellowind777/helloagents)**: 提供了 `AGENTS.md` 规范和多阶段工作流的初始设计理念。
- **[Zen MCP Server](https://github.com/BeehiveInnovations/zen-mcp-server)**: 提供了稳定可靠的 MCP 服务器实现。
---
## 📄 许可证
本项目采用 [Apache 2.0 License](LICENSE)。