Claude Code Zen MCP Skill Work

📋 项目概述

Claude Code Zen MCP Skill Work 是一个专为 AI 编程智能体设计的增强框架，它通过标准化的工作流程、智能路由和自动化代码审查，让 AI 能够更高效、更可靠地处理复杂的编程任务。

核心特性

• 轻量路由 + 多阶段 + 知识库驱动 的架构设计
• 意图驱动授权：根据用户意图自动选择工作模式
• 全自动化模式：支持零等待的完全自主执行
• 多模型协同：支持 Gemini、OpenAI、Claude、Grok 等多种模型
• CLI 桥接：可连接外部 AI CLI 作为子智能体使用

🏗️ 架构设计

项目采用分层架构，由规则系统、技能包、MCP 服务器三大核心组件构成：

目录结构

Claude-Code-Zen-mcp-Skill-Work/
├── .claude/                    # Claude 配置目录
│   └── skills/                 # 技能存放位置
├── skills/                     # 核心技能实现
│   ├── main-router/           # 主路由技能
│   ├── plan-down/             # 任务规划技能
│   ├── codex-code-reviewer/   # 代码审查技能
│   ├── simple-gemini/         # 简单文档生成
│   ├── deep-gemini/           # 深度分析报告
│   ├── gemini-frontend/       # 前端专用技能
│   └── shared/                # 共享资源
├── zen-mcp-server/            # MCP 服务器
├── references/                # 参考文档
├── CLAUDE.md                  # 全局规则配置
├── AGENTS.md                  # 智能体规范
├── install.sh                 # Linux/Mac 安装脚本
├── install.ps1                # Windows 安装脚本
└── install.js                 # Node.js 安装脚本

🛠️ 核心技能详解

路由main-router - 智能任务路由

作为整个系统的中枢调度器，main-router 负责理解用户意图并将任务分发到对应的专业技能模块。

• 意图识别：区分执行指令、咨询求助、模糊意图三种类型
• 模式切换：管理交互模式与全自动化模式的切换
• 阶段调度：控制 P1-P4 工作流的执行顺序
• 强制路由：确保关键节点调用正确的专用技能

规划plan-down - 自动任务分解

负责将复杂任务自动分解为结构化的执行计划，生成标准的 plan.md 文件。

• 需求分析：深入理解任务背景与目标
• 任务拆解：将大任务分解为可执行的小步骤
• 依赖梳理：识别任务间的依赖关系
• 风险评估：预判潜在问题与解决方案

审查codex-code-reviewer - 代码审查

五维度代码质量评估系统，在代码完成后进行双轮强制检查。

生成simple-gemini - 标准文档生成

快速生成标准化的文档和测试代码，适用于常规文档需求。

• API 文档自动生成
• 单元测试代码生成
• 使用示例编写
• README 模板填充

分析deep-gemini - 深度技术分析

生成深度技术分析报告，适用于复杂系统的架构评估与技术决策。

• 架构设计分析
• 技术选型建议
• 性能瓶颈识别
• 重构方案制定

🔄 四阶段工作流程

系统采用 P1-P4 四阶段执行模式，确保任务从分析到完成的全流程可控：

关键规则 (G1-G11)

📦 安装指南

环境要求

• Python：3.8 或更高版本
• Node.js：16 或更高版本（可选，用于 JS 安装脚本）
• Git：用于克隆仓库
• API 密钥：OpenAI / Google Gemini / 其他支持的模型

方式一：自动安装（推荐）

Linux / macOS

# 1. 克隆仓库
git clone https://github.com/VCnoC/Claude-Code-Zen-mcp-Skill-Work.git

# 2. 进入目录
cd Claude-Code-Zen-mcp-Skill-Work

# 3. 运行安装脚本
chmod +x install.sh
./install.sh

Windows

# 1. 克隆仓库
git clone https://github.com/VCnoC/Claude-Code-Zen-mcp-Skill-Work.git

# 2. 进入目录
cd Claude-Code-Zen-mcp-Skill-Work

# 3. 运行 PowerShell 安装脚本
.\install.ps1

方式二：手动安装

1. 克隆仓库

   git clone https://github.com/VCnoC/Claude-Code-Zen-mcp-Skill-Work.git
   cd Claude-Code-Zen-mcp-Skill-Work

2. 复制技能到 Claude 配置目录

   # 创建目录（如果不存在）
   mkdir -p ~/.claude/skills
   
   # 复制技能文件
   cp -r skills/* ~/.claude/skills/

3. 复制全局规则

   cp CLAUDE.md ~/.claude/

4. 安装 Zen MCP Server

   # 复制服务器目录
   cp -r zen-mcp-server ~/zen-mcp-server
   
   # 进入目录并安装依赖
   cd ~/zen-mcp-server
   pip install -r requirements.txt

5. 配置环境变量

   # 复制环境变量模板
   cp .env.example .env
   
   # 编辑配置文件，填入 API 密钥
   nano .env

⚙️ 配置说明

API 密钥配置

在 ~/zen-mcp-server/.env 文件中配置以下密钥：

# OpenAI API 密钥
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# Google Gemini API 密钥
GEMINI_API_KEY=AIzaxxxxxxxxxxxxxxxxxxxxxxxx

# OpenRouter API 密钥（可选）
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxx

# Azure OpenAI（可选）
AZURE_OPENAI_API_KEY=xxxxxxxxxxxxxxxx
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/

# 本地模型配置（Ollama/vLLM/LM Studio）
LOCAL_MODEL_ENDPOINT=http://localhost:11434

MCP 服务器配置

在 Claude Code 的 MCP 配置中添加 Zen MCP Server：

{
  "mcpServers": {
    "zen-mcp": {
      "command": "python",
      "args": ["~/zen-mcp-server/server.py"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

Zen MCP Server 核心工具

启动服务器

# 进入服务器目录
cd ~/zen-mcp-server

# 启动服务器
./run-server.sh

# 或者直接使用 Python
python server.py

验证安装

启动 Claude Code 并执行以下命令验证安装：

# 在 Claude Code 中输入
使用 main-router 分析可用的技能列表

📚 完整案例：开发一个 Todo 应用

以下是一个完整的案例，展示如何使用 Claude Code Zen 框架开发一个功能完整的 Todo 应用。

步骤 1：启动任务并触发智能路由

# 在 Claude Code 中输入任务描述
帮我开发一个 React + TypeScript 的 Todo 应用，
需要包含添加、删除、编辑、完成状态切换和筛选功能，
使用 localStorage 进行数据持久化。
全程自动化执行。

步骤 2：自动生成执行计划 (P1-P2 阶段)

plan-down 技能会自动生成 plan.md：

# Todo 应用开发计划

## 1. 项目初始化
- 使用 Vite 创建 React + TypeScript 项目
- 配置 ESLint 和 Prettier
- 安装必要依赖

## 2. 数据模型设计
- 定义 Todo 接口类型
- 设计状态管理结构

## 3. 核心组件开发
- TodoItem：单个待办事项展示与操作
- TodoList：待办列表渲染
- TodoInput：新增待办输入框
- TodoFilter：筛选器组件

## 4. 功能实现
- CRUD 操作逻辑
- 状态切换功能
- 筛选逻辑

## 5. 数据持久化
- localStorage 存储封装
- 数据同步机制

## 6. 样式与优化
- 响应式布局
- 交互动画

步骤 3：执行开发任务 (P3 阶段)

系统按照计划自动执行，以下是关键代码生成示例：

3.1 定义 Todo 类型

// src/types/todo.ts
export interface Todo {
  id: string;
  text: string;
  completed: boolean;
  createdAt: number;
}

export type FilterType = 'all' | 'active' | 'completed';

3.2 创建 localStorage Hook

// src/hooks/useLocalStorage.ts
import { useState, useEffect } from 'react';

export function useLocalStorage<T>(key: string, initialValue: T) {
  const [storedValue, setStoredValue] = useState<T>(() => {
    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch (error) {
      console.error(error);
      return initialValue;
    }
  });

  useEffect(() => {
    try {
      window.localStorage.setItem(key, JSON.stringify(storedValue));
    } catch (error) {
      console.error(error);
    }
  }, [key, storedValue]);

  return [storedValue, setStoredValue] as const;
}

3.3 主应用组件

// src/App.tsx
import { useState, useMemo } from 'react';
import { useLocalStorage } from './hooks/useLocalStorage';
import { Todo, FilterType } from './types/todo';
import TodoInput from './components/TodoInput';
import TodoList from './components/TodoList';
import TodoFilter from './components/TodoFilter';

function App() {
  const [todos, setTodos] = useLocalStorage<Todo[]>('todos', []);
  const [filter, setFilter] = useState<FilterType>('all');

  const addTodo = (text: string) => {
    const newTodo: Todo = {
      id: crypto.randomUUID(),
      text,
      completed: false,
      createdAt: Date.now(),
    };
    setTodos([...todos, newTodo]);
  };

  const toggleTodo = (id: string) => {
    setTodos(todos.map(todo =>
      todo.id === id ? { ...todo, completed: !todo.completed } : todo
    ));
  };

  const deleteTodo = (id: string) => {
    setTodos(todos.filter(todo => todo.id !== id));
  };

  const editTodo = (id: string, text: string) => {
    setTodos(todos.map(todo =>
      todo.id === id ? { ...todo, text } : todo
    ));
  };

  const filteredTodos = useMemo(() => {
    switch (filter) {
      case 'active':
        return todos.filter(todo => !todo.completed);
      case 'completed':
        return todos.filter(todo => todo.completed);
      default:
        return todos;
    }
  }, [todos, filter]);

  return (
    <div className="app">
      <h1>Todo App</h1>
      <TodoInput onAdd={addTodo} />
      <TodoFilter current={filter} onChange={setFilter} />
      <TodoList
        todos={filteredTodos}
        onToggle={toggleTodo}
        onDelete={deleteTodo}
        onEdit={editTodo}
      />
    </div>
  );
}

export default App;

步骤 4：代码审查 (强制触发 codex-code-reviewer)

代码完成后，系统强制调用 codex-code-reviewer 进行双轮审查：

步骤 5：生成文档 (simple-gemini)

系统自动调用 simple-gemini 生成项目文档和测试代码：

# PROJECTWIKI.md (自动生成)

## 概述
Todo 应用是一个基于 React + TypeScript 的待办事项管理工具。

## 架构
- 采用函数式组件 + Hooks 架构
- 使用 localStorage 进行数据持久化
- 组件采用受控模式

## 模块说明
| 模块 | 职责 |
|------|------|
| App | 主应用，状态管理中心 |
| TodoInput | 新增待办输入 |
| TodoList | 列表渲染 |
| TodoItem | 单项展示与操作 |
| TodoFilter | 筛选控制 |

## API
### useLocalStorage<T>(key: string, initialValue: T)
自定义 Hook，提供持久化状态管理。
...

步骤 6：错误处理与回归验证 (P4 阶段)

如果在执行过程中遇到错误，系统会自动进入 P4 阶段：

1. 分析错误原因
2. 生成修复方案
3. 执行修复
4. 运行回归测试验证

❓ 常见问题

Q1: 如何切换到交互模式？

默认情况下系统处于交互模式，会在关键节点请求用户确认。如果之前启用了全自动化模式，重新启动会话即可恢复交互模式。

Q2: 支持哪些本地模型？

支持通过以下方式运行的本地模型：

• Ollama：直接配置 endpoint 即可
• vLLM：兼容 OpenAI API 格式
• LM Studio：通过本地服务器访问

Q3: 如何自定义技能？

在 ~/.claude/skills/ 目录下创建新的技能文件夹，包含 SKILL.md 文件定义技能描述和规则，可参考现有技能的结构。

Q4: 代码审查可以跳过吗？

根据 G8 规则，代码完成后的 codex 双轮检查是强制执行的，这是质量保障的核心机制，不建议跳过。

Q5: 知识库文件必须要维护吗？

根据"文档一等公民"原则，PROJECTWIKI.md 和 CHANGELOG.md 的维护是代码变更的必要组成部分，系统会自动同步更新这些文件。

Q6: 如何查看可用的 MCP 工具？

# 在 Claude Code 中询问
列出 Zen MCP Server 的所有可用工具