Claude Code Zen MCP 技能工作

🚀 专为AI编程代理设计的一套即用型规则系统和技能包。

该项目不仅是一系列工具的集合，还包含了标准化的工作流程和质量保证机制。通过智能路由、多阶段工作流和自动代码审查，使AI代理能够更高效、可靠地完成复杂的编程任务。

---

✨ 核心特性

• 🔗 CLI桥接能力通过Zen MCP，使AI智能体能够自主调用外部命令行工具（如Codex CLI、Gemini CLI），实现跨工具协作。
• 🧠 **智能路由（main-router）**根据用户意图自动选择最合适的技能，是整个系统的“大脑”。
• 📊 **结构性化学工作流（P1-P4）**将复杂开发任务分解为四个标准阶段：分析、解决方案、执行和修复，确保过程清晰可控。
• 📝 **自动化规划（plan-down）**告别手动任务分解，自动生成结构化任务plan.md并支持多模型验证。
• 🔍 **五维代码审查（codex-code-reviewer）**从质量、安全、性能、架构和文档五个维度对代码进行全面评审和评分。
• 📄 **专业文档生成（simple-gemini & deep-gemini）**自动生成和维护项目知识库（PROJECTWIKI.md）、变更日志（CHANGELOG.md）以及深入的技术分析报告。
• 🤖 全自动模式支持“一句话需求，全自动化开发”模式，AI可以独立完成从规划到代码实现、审查、测试和文档更新的全过程。

🏗️ 工作原理

系统通过四阶段（P1-P4）工作流处理用户请求，由main-router统一调度。这一过程确保每个任务都经过彻底分析、严格规划和严格的质量验证。

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**。

🎯 核心技能包

该项目提供了一组即插即用的核心技能，每项技能赋予AI代理一种专业能力。

技能	核心职责	主要输出
main-router	智能路由和任务调度	路由决策、全局状态管理
plan-down	任务分解和计划生成	plan.md 文件
codex-code-reviewer	五维代码质量审查和自动修复	质量报告、修复代码
simple-gemini	标准文档和测试代码生成	README、PROJECTWIKI 测试文件
deep-gemini	深度技术分析和报告生成	架构/性能分析报告

🚀 快速开始

1. 环境要求

• Python >= 3.8**
• Git

2. 安装步骤

此仓库包含Zen MCP Server和核心技能包，只需三步即可完成安装。

步骤1：克隆仓库

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

步骤2：运行一键安装脚本

脚本将自动完成Zen MCP Server的安装、技能包的复制以及全局规则的配置。

• Linux / macOS：

  chmod +x install.sh && ./install.sh
  

• Windows：

  .\install.ps1
  

💡 提示如果无法使用一键脚本（例如从GitHub克隆的版本），请使用以下的手动安装步骤。

Linux/macOS的手动安装

# 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的手动安装

# 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. 配置和启动

步骤1：配置API密钥

编辑位于 ~/zen-mcp-server/.env（或 %USERPROFILE%\zen-mcp-server\.env）的配置文件，填写您的API密钥。

# 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中添加模型配置。

步骤2：启动Zen MCP Server

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代码

完全关闭Claude代码并重新启动。

---

✅ 验证安装

启动Claude代码并输入：

请使用 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	**项目知识库（核心）**架构设计、决策记录、模块文档。
CLAUDE.md	全局规则定义了G1-G11全局规则和P1-P4工作流。
CHANGELOG.md	变更日志记录了项目的全部版本变更历史。
skills/shared/tool_parameter_contract.md	工具参数合同所有Zen MCP Server工具的详细参数规范。

---

🙏 致谢

本项目的实施离不开以下优秀开源项目的启发和支持：

• **HelloAgents**提供了：AGENTS.md标准化和多阶段工作流的初始设计理念。
• **Zen MCP Server**提供了一个稳定可靠的MCP服务器实现。

---

📄 许可证

本项目采用Apache 2.0许可证。