MonkeyCode 开发者入门指南：从零开始搭建你的第一个 AI 编程项目
想体验 AI 编程的强大能力却不知从何入手？本指南将手把手带你完成 MonkeyCode 的安装、配置和第一个 AI 编程项目，即使你是完全的新手也能在 30 分钟内跑通全流程。
🚀 准备工作：5 分钟快速检查
环境要求
┌─────────────────────────────────────────────────────┐
│ MonkeyCode 运行环境要求 │
│ │
│ 💻 硬件要求（最低配置）： │
│ ├── CPU: 2 核及以上 │
│ ├── 内存: 4 GB 及以上 │
│ ├── 硬盘: 10 GB 可用空间 │
│ └── 网络: 首次安装需要联网 │
│ │
│ 🖥️ 推荐配置（流畅体验）： │
│ ├── CPU: 4 核及以上 │
│ ├── 内存: 8 GB 及以上 │
│ ├── 硬盘: 20 GB SSD │
│ └── 网络: 宽带连接 │
│ │
│ 🐧 操作系统支持： │
│ ├── ✅ Windows 10/11 (64位) │
│ ├── ✅ macOS 12+ (Intel / Apple Silicon) │
│ ├── ✅ Ubuntu 20.04+ / Debian 11+ │
│ ├── ✅ CentOS 8+ / RHEL 8+ │
│ └── ✅ 麒麟 V10 / 统信 UOS (信创环境) │
│ │
│ 🔧 前置依赖： │
│ ├── Node.js >= 18.x（可选，CLI 工具需要） │
│ ├── Git >= 2.x │
│ ├── Docker >= 20.x（可选，容器化部署需要） │
│ └── Python >= 3.9（可选，SDK 需要） │
│ │
└─────────────────────────────────────────────────────┘
快速检查清单
# 在终端中依次执行以下命令，确认环境就绪
# 1. 检查 Node.js 版本（如需使用 CLI）
node --version
# 期望输出: v18.x.x 或更高
# 2. 检查 Git 版本
git --version
# 期望输出: git version 2.x.x 或更高
# 3. 检查 Docker 版本（如需容器化部署）
docker --version
# 期望输出: Docker version 20.x.x 或更高
# 4. 检查磁盘空间
# Windows:
wmic logicaldisk get size,freespace,caption
# macOS/Linux:
df -h .
# 期望: 至少 10GB 可用空间
# 5. 检查网络连接
ping api.monkeycode.cn
# 期望: 能连通（如果使用云端版）
# ✅ 如果以上全部通过，恭喜！可以开始安装了！
📦 第一步：安装 MonkeyCode
方式一：VS Code 插件（推荐新手）
# Step 1: 打开 VS Code
# Step 2: 点击左侧扩展图标（或 Ctrl+Shift+X）
# Step 3: 搜索 "MonkeyCode"
# 找到由 chaitin 发布的官方插件
# Step 4: 点击"安装"
# Step 5: 安装完成后，VS Code 左侧会出现
# MonkeyCode 的图标（🐵 猴子头像）
# Step 6: 点击图标，选择登录方式：
# ├── 微信扫码登录（推荐国内用户）
# ├── GitHub OAuth 登录（推荐开发者）
# └── 邮箱注册登录
# ✅ 完成！你现在可以在 VS Code 中使用 MonkeyCode 了
方式二：CLI 命令行工具（推荐进阶用户）
# Step 1: 使用 npm 全局安装
npm install -g @chaitin/monkeycode
# 或者使用 Homebrew（macOS/Linux）
brew install monkeycode/tap/monkeycode
# Step 2: 验证安装
monkeycode --version
# 期望输出: monkeycode v1.x.x
# Step 3: 登录
monkeycode login
# 会自动打开浏览器进行授权登录
# Step 4: 查看可用命令
monkeycode --help
# 输出所有可用命令和选项
# ✅ CLI 工具安装完成！
方式三：Docker 部署（推荐团队/企业）
# Step 1: 拉取镜像
docker pull chaitin/monkeycode:latest
# Step 2: 创建数据持久化目录
mkdir -p ~/.monkeycode/data
mkdir -p ~/.monkeycode/config
# Step 3: 启动服务
docker run -d \
--name monkeycode \
-p 8080:8080 \
-p 8443:8443 \
-v ~/.monkeycode/data:/app/data \
-v ~/.monkeycode/config:/app/config \
-e MONKEYCODE_API_KEY="your-api-key" \
--restart unless-stopped \
chaitin/monkeycode:latest
# Step 4: 访问 Web UI
open http://localhost:8080
# Step 5: 初始化管理员账户
docker exec -it monkeycode admin-setup
# ✅ Docker 部署完成！访问 http://localhost:8080 开始使用
方式四：源码编译（推荐贡献者）
# Step 1: 克隆仓库
git clone https://github.com/chaitin/monkeycode.git
cd monkeycode
# Step 2: 安装依赖
npm install
# Step 3: 编译
npm run build
# Step 4: 运行开发模式
npm run dev
# Step 5: 访问本地开发服务器
open http://localhost:3000
# ✅ 源码编译运行成功！
# 现在你可以修改代码并实时看到效果了
⚙️ 第二步：初始化你的第一个项目
创建新项目
# 方式 A: 从头创建新项目
mkdir my-first-ai-project
cd my-first-ai-project
git init
monkeycode init
# 方式 B: 在已有项目中启用
cd your-existing-project
monkeycode init
# monkeycode init 会做什么？
# ┌─────────────────────────────────────┐
# │ ✅ 创建 .monkeycode/ 配置目录 │
# │ ✅ 创建 .monkeycode/config.yaml │
# │ ✅ 创建 .sdd/ 规范目录 │
# │ ✅ 创建 .monkeycodeignore 文件 │
# │ ✅ 生成 SDD 规范模板 │
# │ ✅ 配置 Git Hook（可选） │
# └─────────────────────────────────────┘
项目配置文件详解
# .monkeycode/config.yaml — 核心配置文件
# AI 模型配置
model:
# 默认模型（用于代码生成）
default: "claude-3.5-sonnet"
# 备选模型列表
available:
- name: "gpt-4o"
provider: "openai"
use_case: ["general", "analysis"]
- name: "claude-3.5-sonnet"
provider: "anthropic"
use_case: ["code-generation", "review"]
- name: "deepseek-v3"
provider: "deepseek"
use_case: ["cost-effective", "chinese"]
# 智能路由开关
smart_routing: true # 自动根据任务类型选择最优模型
# 安全扫描配置
security_scan:
enabled: true
# 扫描级别
level: "standard" # standard | strict | custom
# 自动修复策略
auto_fix:
enabled: true
severity: ["low", "medium"] # 自动修复低危和中危问题
# 忽略规则（可选）
ignore_rules:
- "unused-variable-in-test" # 测试代码中的未使用变量
# SDD 规范配置
sdd:
# 规范格式
format: "yaml" # yaml | json | markdown
# 强制规范检查
enforce: true # 不符合规范的代码不允许提交
# 规范模板路径
template_path: ".sdd/templates/"
# Git 工作流配置
git_workflow:
async_mode: true # 启用异步工作流
# 自动触发的任务
auto_trigger:
on_commit: true # 每次 commit 自动触发
on_pr: true # PR 创建时自动触发
# 通知设置
notification:
on_start: true # 任务开始时通知
on_complete: true # 任务完成时通知
channels: ["pr_comment"] # 通知渠道
# 编辑器集成
editor:
# VS Code
vscode:
inline_suggest: true # 行内代码建议
auto_completion: true # 自动补全
chat_panel: true # 聊天面板
# JetBrains（如安装了插件）
jetbrains:
inline_chat: true
code_actions: true
🎯 第三步：编写你的第一个 SDD 规范
什么是 SDD 规范？
SDD = Spec-Driven Development（规范驱动开发）
在写代码之前，先写一份"需求规范文档"，告诉 AI 你想要什么。
AI 基于这份规范来生成代码，确保输出的代码完全符合预期。
创建第一个 SDD 规范
# .sdd/todo-app-spec.yaml
# 这是一个简单的待办事项(Todo)应用的 SDD 规范
metadata:
name: "Todo App"
version: "1.0.0"
author: "your-name"
date: "2026-07-06"
overview: |
一个简洁美观的 Todo 应用，
支持添加、删除、标记完成任务。
requirements:
functional:
- id: "REQ-001"
title: "添加任务"
description: "用户可以输入文字添加新的待办事项"
priority: "high"
acceptance_criteria:
- "输入框支持最多 200 字符"
- "按 Enter 键或点击按钮添加"
- "添加后清空输入框"
- id: "REQ-002"
title: "完成任务"
description: "点击任务可切换完成状态"
priority: "high"
acceptance_criteria:
- "完成的任务显示删除线样式"
- "状态保存在浏览器本地存储"
- id: "REQ-003"
title: "删除任务"
description: "可以删除不需要的任务"
priority: "medium"
acceptance_criteria:
- "每个任务右侧有删除按钮"
- "删除前弹出确认提示"
- id: "REQ-004"
title: "数据持久化"
description: "刷新页面后数据不丢失"
priority: "high"
acceptance_criteria:
- "使用 localStorage 存储"
- "数据以 JSON 格式存储"
non_functional:
- id: "NFR-001"
title: "性能"
description: "页面加载时间 < 1 秒"
- id: "NFR-002"
title: "响应式设计"
description: "适配手机和桌面端"
- id: "NFR-003"
title: "安全"
description: "无 XSS 风险，输入内容需转义"
tech_stack:
frontend: "HTML + CSS + JavaScript (原生)"
build_tool: "无需构建工具，直接运行"
package_manager: "无依赖"
security_requirements:
- "所有用户输入必须经过 HTML 转义（防 XSS）"
- "不使用 eval() 或 innerHTML 直接插入用户输入"
- "localStorage 数据不做敏感信息存储"
testing_requirements:
coverage_target: "> 80%"
test_types:
- "单元测试（函数级别）"
- "集成测试（交互流程）"
test_framework: "Vitest + Testing Library"
🤖 第四步：让 AI 生成代码
使用 VS Code 插件生成
操作步骤：
1️⃣ 打开 SDD 规范文件
→ 在 VS Code 中打开 .sdd/todo-app-spec.yaml
2️⃣ 打开 MonkeyCode 面板
→ 点击左侧猴子图标
→ 或按快捷键 Ctrl+Shift+M
3️⃣ 选择"基于 SDD 生成代码"
→ 面板中选择 "Generate from SDD"
→ 选择刚才创建的 spec 文件
4️⃣ 等待 AI 生成
→ 进度条显示生成进度
→ 通常 30-60 秒完成
5️⃣ Review 生成的代码
→ AI 会生成以下文件：
│
├── index.html # 主页面
├── css/style.css # 样式文件
├── js/app.js # 主逻辑
├── js/storage.js # 数据持久化
├── tests/app.test.js # 单元测试
└── README.md # 使用说明
6️⃣ 一键运行预览
→ 右键 index.html → "Open with Live Server"
→ 或使用 monkeycode preview 命令
使用 CLI 生成
# 基于 SDD 规范生成代码
monkeycode generate --spec=.sdd/todo-app-spec.yaml --output=./src
# 只生成特定模块
monkeycode generate --spec=.sdd/todo-app-spec.yaml --module=REQ-001 --output=./src
# 生成的同时运行安全扫描
monkeycode generate --spec=.sdd/todo-app-spec.yaml --scan --output=./src
# 生成测试用例
monkeycode generate-tests --spec=.sdd/todo-app-spec.yaml --output=./tests
# 生成 API 文档
monkeycode generate-docs --spec=.sdd/todo-app-spec.yaml --output=./docs
使用 Web UI 生成
1. 打开 http://localhost:8080（Docker 部署）
或 https://cloud.monkeycode.cn（云端版）
2. 创建新项目
→ 点击 "New Project"
→ 上传 SDD 规范文件或在在线编辑器中编写
3. 点击 "Generate Code"
→ 选择技术栈和输出格式
→ 点击确认开始生成
4. 查看结果
→ 在线预览生成的代码
→ 直接下载 ZIP 包
→ 或推送到 GitHub/GitLab
🔍 第五步：运行安全扫描
第一次扫描体验
# 对整个项目进行安全扫描
monkeycode scan ./src
# 输出示例：
╔══════════════════════════════════════════════════╗
║ MonkeyScan 安全扫描报告 ║
║ ║
║ 📊 扫描概览 ║
║ ├── 扫描文件数: 12 ║
║ ├── 代码总行数: 850 ║
║ ├── 扫描耗时: 3.2s ║
║ └── 规则库版本: v2.0 (3800+ rules) ║
║ ║
║ 🔍 发现的问题 ║
║ ┌────────┬──────────┬─────────┬────────────────┐ ║
║ │ 严重度 │ 数量 │ 状态 │ 说明 │ ║
║ ├────────┼──────────┼─────────┼────────────────┤ ║
║ │ 🔴 高 │ 1 │ 🔧 已修复 │ XSS 风险 │ ║
║ │ 🟡 中 │ 2 │ 🔧 已修复 │ 未使用的变量 │ ║
║ │ 🟢 低 │ 3 │ ℹ️ 建议 │ 缺少注释 │ ║
║ └────────┴──────────┴─────────┴────────────────┘ ║
║ ║
║ ✅ 安全评分: 92/100 ║
║ ✅ 无高危漏洞 ║
║ ✅ 项目通过安全门禁！ ║
╚══════════════════════════════════════════════════╝
在 VS Code 中查看扫描结果
扫描完成后：
1️⃣ 问题面板自动展示
→ VS Code 的"问题"面板（Problems Panel）
→ 显示每个问题的详细信息
2️⃣ 代码中高亮标注
→ 有问题的代码行会有波浪线下划线
→ 悬停可查看详细描述和修复建议
3️⃣ 一键修复
→ 对于支持自动修复的问题
→ 点击灯泡图标 → 选择 "Quick Fix"
→ AI 自动生成修复代码
4️⃣ 重新扫描验证
→ 修复后再次运行扫描
→ 确认问题已解决
🧪 第六步：运行测试
执行生成的测试
# 安装测试依赖（首次运行）
npm install
# 运行所有测试
npm test
# 输出示例：
✓ src/js/app.test.js (5 tests)
✓ REQ-001: should add a new task (23ms)
✓ REQ-002: should toggle task completion (12ms)
✓ REQ-003: should delete a task with confirmation (18ms)
✓ REQ-004: should persist data to localStorage (8ms)
✓ Security: should escape HTML in user input (15ms)
✓ src/js/storage.test.js (3 tests)
✓ should save tasks to localStorage
✓ should load tasks from localStorage
✓ should handle empty storage
Test Files 2 passed (2)
Tests 8 passed (8)
Start time 500ms
Duration 1.2s
Coverage 87% (目标 > 80%) ✅
🔄 第七步：Git 异步工作流（可选但推荐）
提交代码并派发 AI 任务
# 添加所有文件
git add .
# 提交代码（包含 @MonkeyCode 指令）
git commit -m "feat: 实现 Todo App 基础功能
完成了以下功能：
- 添加/删除/完成任务
- 本地数据持久化
- 响应式设计
- XSS 防护
@MonkeyCode 请执行以下任务：
1. 补充边界条件测试
2. 进行完整的安全扫描
3. 生成 CHANGELOG.md
4. 检查代码风格一致性"
# ✅ 提交成功！
# 如果启用了异步工作流，MonkeyCode 会自动：
# → 在隔离环境中拉取最新代码
# → 执行你要求的任务
# → 完成后创建 PR 或发送通知
🎉 恭喜！你完成了第一个项目！
下一步学习路径
┌─────────────────────────────────────────────────────┐
│ MonkeyCode 学习路线图 │
│ │
│ 🌱 新手（当前阶段） │
│ ├── ✅ 安装和配置 │
│ ├── ✅ 第一个 SDD 规范 │
│ ├── ✅ AI 代码生成 │
│ ├── ✅ 安全扫描初体验 │
│ └── 📍 下一步：深入学习 SDD 规范 │
│ │
│ 🌿 初级 │
│ ├── SDD 规范高级语法 │
│ ├── 自定义安全扫描规则 │
│ ├── CI/CD 流水线集成 │
│ └── 团队协作最佳实践 │
│ │
│ 🌳 中级 │
│ ├── 多模型智能路由配置 │
│ ├── 插件开发入门 │
│ ├── 性能优化与调优 │
│ └── 企业级私有化部署 │
│ │
│ 🌲 高级 │
│ ├── 贡献开源代码 │
│ ├── 开发自定义插件 │
│ ├── 参与社区治理 │
│ └── 成为 MonkeyCode 专家/Certified Developer │
│ │
└─────────────────────────────────────────────────────┘
推荐学习资源
| 资源类型 | 链接 | 说明 |
|---|---|---|
| 官方文档 | https://docs.monkeycode.cn | 最权威的学习资料 |
| 视频教程 | B站搜索"MonkeyCode" | 中文视频教程 |
| SDD 规范指南 | https://docs.monkeycode.cn/sdd | 规范驱动开发详解 |
| 安全扫描手册 | https://docs.monkeycode.cn/monkeyscan | 深入了解安全能力 |
| API 参考 | https://docs.monkeycode.cn/api | SDK/API 完整文档 |
| GitHub Discussions | https://github.com/chaitin/monkeycode/discussions | 社区问答 |
| 示例项目集合 | https://github.com/chaitin/monkeycode/examples | 各种场景的示例 |
❓ 新手常见问题 FAQ
Q1: MonkeyCode 真的免费吗？
A: 是的！核心功能完全免费：
- 开源版本永久免费（AGPL-3.0 协议）
- 注册送 200 元算力额度
- 每天签到领 30M Token
- 个人使用完全够用
Q2: 我的代码会被泄露吗？
A: 不会！
- 云端版：代码仅用于 AI 生成，不会被存储或用于训练
- 开源版：完全在本地运行，数据不出你的电脑
- 企业版：私有化部署，数据在内网
Q3: 支持哪些编程语言？
A: 目前主流语言全部支持：
- 前端: JavaScript, TypeScript, HTML, CSS, Vue, React, Angular
- 后端: Python, Java, Go, Rust, Node.js, PHP, Ruby, C#
- 移动端: Swift, Kotlin, Dart (Flutter), React Native
- 其他: C, C++, SQL, Shell, YAML, Markdown ...
Q4: AI 生成的代码质量怎么样？
A: 基于 SDD 规范驱动的代码质量很高：
- 平均首次成功率约 90%（传统方式仅 30%）
- 自动包含单元测试（覆盖率通常 >80%）
- 内置安全扫描，高危漏洞拦截率 >98%
- 代码风格统一，符合团队规范
Q5: 遇到问题怎么办？
A: 多种渠道获取帮助：
- 文档: https://docs.monkeycode.cn（最详细）
- 社区: GitHub Discussions（活跃社区）
- Issue: https://github.com/chaitin/monkeycode/issues（Bug 反馈）
- 邮件: support@chaitin.cn（企业客户专属）
- 微信群: 关注公众号"MonkeyCode"获取入群二维码
Q6: 如何参与开源贡献？
A: 欢迎贡献！
# Fork 项目
git clone https://github.com/YOUR_USERNAME/monkeycode.git
# 创建分支
git checkout -b feature/amazing-feature
# 开发 + 提交
git commit -m "Add amazing feature"
# 推送 + 创建 PR
git push origin feature/amazing-feature
# 然后在 GitHub 上创建 Pull Request
贡献者福利：T恤、证书、算力额度、甚至面试机会！
🔗 相关链接
- 🏠 MonkeyCode 官网: https://monkeycode.cn
- ☁️ 云端控制台: https://cloud.monkeycode.cn
- 📦 GitHub 开源仓库: https://github.com/chaitin/monkeycode ⭐ Star！
- 📖 官方文档: https://docs.monkeycode.cn
- 🎮 交互式教程: https://try.monkeycode.cn
- 💬 社区讨论: https://github.com/chaitin/monkeycode/discussions
- 🐛 问题反馈: https://github.com/chaitin/monkeycode/issues
- 📧 联系邮箱: support@chaitin.cn
本文由 MonkeyCode 团队原创，欢迎转载但请注明出处。
🚀 MonkeyCode —— 你的第一个 AI 编程项目从这里开始！
每一个专家都曾是新手。现在就开始你的 AI 编程之旅吧！
👉 https://monkeycode.cn | 📦 https://github.com/chaitin/monkeycode ⭐
浙公网安备 33010602011771号