MonkeyCode 开发者入门指南：从零开始搭建你的第一个 AI 编程项目

MonkeyCode 开发者入门指南：从零开始搭建你的第一个 AI 编程项目

🚀 欢迎来到 MonkeyCode 的世界！

本指南将带你从零基础开始，一步步完成 MonkeyCode 的安装、配置和第一个 AI 编程项目的搭建。

---

📋 前置要求

在开始之前，请确保你的环境满足以下要求：

组件	最低版本	推荐版本
操作系统	Windows 10 / macOS 12 / Ubuntu 20.04	最新稳定版
Python	3.10+	3.11+ 或 3.12
Docker（可选）	24.0+	最新版
Git	2.30+	最新版
内存	8 GB RAM	16 GB+
磁盘空间	2 GB 可用	10 GB+

---

🔧 安装方式一：pip 安装（推荐新手）

Step 1：创建虚拟环境

# 创建项目目录
mkdir my-first-monkeyCode-project
cd my-first-monkeyCode-project

# 创建 Python 虚拟环境
python -m venv .venv

# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

Step 2：安装 MonkeyCode

# 使用 pip 安装（稳定版）
pip install monkeycode

# 或者安装最新开发版
pip install git+https://github.com/chaitin/MonkeyCode.git@main

Step 3：验证安装

monkeyCode --version
# 输出: MonkeyCode v1.0.0 (Open Source, AGPL-3.0)

monkeyCode doctor
# 运行环境检查，确认所有依赖正常

---

🐳 安装方式二：Docker 部署（推荐企业用户）

Step 1：克隆仓库

git clone https://github.com/chaitin/MonkeyCode.git
cd MonkeyCode/deploy/docker

Step 2：配置环境变量

cp .env.example .env

编辑 .env 文件：

# 核心配置
MONKEYCODE_HOST=0.0.0.0
MONKEYCODE_PORT=8080
MONKEYCODE_SECRET_KEY=your-random-secret-key-here

# 数据库配置
POSTGRES_HOST=postgres
POSTGRES_USER=monkeyCode
POSTGRES_PASSWORD=your-strong-password-here
POSTGRES_DB=monkeyCode_db

# AI 模型配置（使用 Ollama 本地模型）
AI_PROVIDER=ollama
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_MODEL=qwen2.5-coder:32b

Step 3：启动服务

docker compose up -d

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f monkeycode

Step 4：访问验证

浏览器打开：http://localhost:8080

默认管理员账户需通过命令行创建：

docker exec -it monkeycode-app python manage.py create_admin \
  --username admin \
  --email admin@example.com \
  --password your-admin-password

---

🎯 第一个项目：Hello MonkeyCode！

Step 1：初始化项目

cd your-project-directory

# 初始化 MonkeyCode 项目
monkeyCode init

# 这将创建以下目录结构：
# .
# ├── .monkeyCode/          # 配置目录
# │   ├── config.yaml      # 主配置文件
# │   └── specs/            # SDD 规范文件目录
# ├── src/                 # 源代码目录
# └── tests/               # 测试目录

Step 2：编写第一个 Spec 文件

创建 specs/hello-api.spec.yaml：

project: Hello API
version: 1.0.0
author: Your Name

description: 我的第一个 MonkeyCode AI 编程项目

apis:
  - name: hello_world
    method: GET
    path: /api/hello
    description: 返回问候语
    params:
      - name: name
        type: string
        required: false
        default: World
    response:
      type: object
      fields:
        message: string
        timestamp: datetime
    security:
      rate_limit: 100/min
      
  - name: health_check
    method: GET
    path: /api/health
    description: 健康检查接口
    response:
      type: object
      fields:
        status: string
        version: string
        uptime: number

Step 3：生成代码

# 基于 Spec 文件生成代码
monkeyCode generate --spec specs/hello-api.spec.yaml --output ./src

# 输出示例：
# ✅ 生成 API 路由文件: src/routes/hello.py
# ✅ 生成数据模型: src/models/hello.py
# ✅ 生成单元测试: tests/test_hello.py
# ✅ 生成安全加固代码: src/security/hello_security.py
# ✅ 通过安全扫描: 0 个漏洞发现

Step 4：查看生成的代码

src/routes/hello.py:

"""
自动生成的 Hello API 路由
由 MonkeyCode SDD 引擎基于 spec 文件生成
"""

from fastapi import APIRouter, Query
from pydantic import BaseModel
from datetime import datetime
from typing import Optional

router = APIRouter(prefix="/api", tags=["hello"])


class HelloResponse(BaseModel):
    message: str
    timestamp: datetime


class HealthResponse(BaseModel):
    status: str
    version: str
    uptime: float


@router.get("/hello", response_model=HelloResponse)
async def hello_world(
    name: Optional[str] = Query(default="World", description="姓名")
):
    """返回个性化问候语"""
    return HelloResponse(
        message=f"Hello, {name}! Welcome to MonkeyCode! 🎉",
        timestamp=datetime.now()
    )


@router.get("/health", response_model=HealthResponse)
async def health_check():
    """健康检查接口"""
    import time
    start_time = time.time()
    
    return HealthResponse(
        status="healthy",
        version="1.0.0",
        uptime=time.time() - start_time
    )

Step 5：运行安全扫描

# 对生成的代码进行安全扫描
monkeyCode scan ./src

# 输出示例：
# ╔══════════════════════════════════════╗
#     MonkeyCode 安全扫描报告             #
# ╠══════════════════════════════════════╣
#                                          #
#  扫描文件数: 5                           #
#  发现问题: 0 ✅                          #
#  安全评分: 100/100 🏆                   #
#                                          #
# ╚══════════════════════════════════════╝

Step 6：运行测试

# 运行自动生成的单元测试
python -m pytest tests/ -v

# 输出示例：
# ========================= test session starts =========================
# collected 4 items
#
# test_hello.py::test_hello_default PASSED ✅
# test_hello.py::test_hello_with_name PASSED ✅
# test_hello.py::test_health_check PASSED ✅
# test_hello.py::test_hello_rate_limit PASSED ✅
#
# ========================== 4 passed in 0.23s ==========================

Step 7：启动服务

# 启动 API 服务
monkeycode serve

# 输出：
# 🚀 MonkeyCode Server starting...
#    → http://localhost:8000
#    → API Docs: http://localhost:8000/docs
#    → Health: http://localhost:8000/api/health

浏览器访问 http://localhost:8000/docs 即可看到自动生成的 API 文档！

---

🔒 启用安全扫描（进阶）

配置安全规则

创建 .monkeyCode/security-rules.yaml：

security_rules:
  # SQL 注入防护
  sql_injection:
    enabled: true
    severity: CRITICAL
    auto_fix: true
    
  # XSS 防护
  xss:
    enabled: true
    severity: HIGH
    auto_fix: true
    
  # 敏感信息检测
  sensitive_data:
    enabled: true
    patterns:
      - regex: "(?i)(api_key|secret|password)\\s*[:=]\\s*['\"][^'\"]+"
        severity: HIGH
        
  # 不安全的加密算法
  insecure_crypto:
    enabled: true
    forbidden:
      - MD5
      - SHA1
      - DES

在每次生成时自动扫描

# 生成 + 扫描一步到位
monkeyCode generate-and-scan --spec specs/my-api.spec.yaml --output ./src

---

🤖 Git 异步工作流（进阶）

配置 GitHub/GitLab 集成

# .monkeyCode/git-config.yaml
git_provider: github
repo: your-username/your-repo
token: YOUR_GITHUB_TOKEN

workflow:
  branch_strategy: "feature/{task_id}-{short_name}"
  base_branch: main
  
  pr_template: |
    ## 📋 任务概述
    {task_description}
    
    ## ✅ 安全扫描结果
    {security_scan_results}
    
    ---
    *此 PR 由 MonkeyCode 自动生成*

派发任务

在 GitHub Issue 中评论：

@MonkeyCode 请实现用户认证模块，基于 spec/auth.spec.yaml

MonkeyCode 将自动：

1. 创建新分支
2. 生成代码
3. 运行测试和安全扫描
4. 创建 PR
5. 通知你 Review

---

❓ 常见问题

Q1: 安装时遇到依赖冲突怎么办？

# 使用 pip 解决冲突
pip install monkeycode --no-deps
pip install -r requirements.txt  # 手动处理冲突

Q2: 如何切换 AI 模型？

编辑 .monkeyCode/config.yaml：

ai_provider: ollama  # 或 openai-compatible / anthropic
model: qwen2.5-coder:32b

Q3: 生成的代码质量不好怎么办？

• 优化 Spec 文件：越详细的规范 = 越好的代码
• 添加示例代码：在 spec 中提供 examples 字段
• 调整安全级别：设置 security_level 为 strict

Q4: 如何参与开源贡献？

👉 GitHub Issues 提交 Issue 或 PR

---

🎁 新人福利

为庆祝 MonkeyCode 正式开源，新人专享：

1. 💰 200 元云端算力赠送
2. 📚 完整入门教程
3. 🤝 社区新人答疑群
4. 🏆 首次贡献者徽章

---

🔗 相关链接

• GitHub: MonkeyCode 开源仓库 （欢迎 Star ⭐）
• 文档: https://docs.monkeyCode.com
• Issue 反馈: GitHub Issues
• Discord 社区: 加入讨论

🎉 恭喜你完成了第一个 MonkeyCode 项目！现在去 GitHub Star 我们吧！

---

作者：MonkeyCode 团队 · 开发者体验组
日期：2026-07-02
许可证：AGPL-3.0