Neovate Code 学习教程

一、环境准备

前置知识

学习 Neovate Code 需要以下基础：

安装步骤

1. 确保 Node.js 环境

# 检查 Node.js 版本（需要 18+）
node -v

# 如果未安装，使用 nvm 安装
nvm install 22
nvm use 22

2. 安装 Neovate Code

# 全局安装（推荐）
npm install -g @neovate/code

# 或使用 yarn
yarn global add @neovate/code

# 或使用 pnpm
pnpm add -g @neovate/code

3. 验证安装

# 检查版本
neovate --version
# 输出: 0.28.5

# 查看帮助
neovate --help

4. 配置 API Key

选择你偏好的 LLM 提供商，设置环境变量：

# Anthropic (Claude)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI (GPT)
export OPENAI_API_KEY="sk-..."

# DeepSeek
export DEEPSEEK_API_KEY="sk-..."

# Google (Gemini)
export GOOGLE_API_KEY="..."

# 建议写入 shell 配置文件
echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.zshrc
source ~/.zshrc

环境验证

# 在任意项目目录中启动
cd your-project
neovate

# 首次启动会提示登录和选择模型
# 输入 /login 登录
# 输入 /model 选择模型

二、快速开始

Hello World

第一步: 启动 Neovate Code

cd your-project
neovate

你会看到交互式终端界面，显示当前模型和工作目录。

第二步: 基础对话

> 帮我看看这个项目的结构

> 这个文件有什么问题？

> 帮我写一个工具函数，格式化日期为 YYYY-MM-DD 格式

第三步: 文件操作

> 在 src/utils/ 下创建一个 format.ts 文件，包含日期格式化函数

> 修改 src/index.ts，导入并使用新的格式化函数

> 为 format.ts 编写单元测试

第四步: 代码审查

# 先暂存你的变更
git add .

# 使用 Neovate Code 审查
neovate /review

# 或者直接用管道方式
git diff --cached | neovate /review

核心交互模式

三、核心概念

概念图谱

Neovate Code 核心概念
├── 会话管理
│   ├── 新会话 (neovate)
│   ├── 继续会话 (neovate -c)
│   ├── 恢复会话 (neovate -r <id>)
│   └── 会话压缩 (autoCompact)
│
├── 模型系统
│   ├── 11+ 内置提供商
│   ├── OpenAI 兼容自定义
│   ├── 模型别名 (deepseek, gpt-4, ...)
│   └── Plan 模型独立配置
│
├── 规则系统
│   ├── AGENTS.md (项目级)
│   ├── AGENTS.md (全局级 ~/.neovate/)
│   └── /init 自动生成
│
├── 工具系统
│   ├── 内置工具 (文件读写、Shell、Git)
│   ├── MCP 服务器 (外部工具)
│   └── 插件 (自定义扩展)
│
├── 工作模式
│   ├── Interactive (终端交互)
│   ├── Headless (CI/CD)
│   └── Yolo (全自动)
│
└── 工作区
    ├── 主工作区
    ├── Git Worktree 隔离
    └── 并行 Agent

核心概念详解

1. 审批模式（Approval Mode）

Neovate Code 的安全机制，控制 AI 操作的审批级别：

# 启动时指定
neovate --approval-mode autoEdit

# 或在会话中切换
> /approval autoEdit

# 或在配置文件中设置
# .neovate/settings.json
{ "approvalMode": "autoEdit" }

2. AGENTS.md 规则文件

项目级 AGENTS.md (./AGENTS.md):

# 项目规则

## 技术栈
- 前端: React 19 + TypeScript
- 状态管理: Zustand
- 测试: Vitest

## 编码规范
- 使用函数式组件，禁止 class 组件
- 所有函数必须添加 TypeScript 类型
- 文件命名使用 kebab-case
- 组件命名使用 PascalCase

## 测试要求
- 每个新功能必须编写单元测试
- 测试文件放在同目录 __tests__/ 下

## 架构约束
- 不允许在组件中直接调用 API
- 使用自定义 hook 封装数据获取逻辑

全局 AGENTS.md (~/.neovate/AGENTS.md):

# 个人偏好

- 使用中文回复
- 代码注释使用英文
- 优先使用 ES Module 语法
- 偏好函数式编程风格

自动生成:

# 在项目根目录运行
neovate

# 输入
> /init

# Neovate Code 会扫描项目并生成 AGENTS.md

3. 会话管理

# 新建会话
neovate

# 继续最近的会话
neovate -c

# 恢复指定会话
neovate -r <session-id>

# 查看会话列表
> /sessions

4. Slash 命令

术语表

四、功能详解

4.1 MCP 服务器管理

Model Context Protocol 允许 Neovate Code 连接外部工具服务器：

# 添加 MCP 服务器
neovate mcp add my-server -t stdio -c "npx my-mcp-server"

# 添加 HTTP 类型的 MCP 服务器
neovate mcp add remote-server -t http -u http://localhost:3000

# 列出所有服务器
neovate mcp ls

# 查看详情
neovate mcp get my-server

# 启用/禁用
neovate mcp enable my-server
neovate mcp disable my-server

# 删除
neovate mcp rm my-server

# 全局操作（-g 标志）
neovate mcp add global-server -g -t stdio -c "npx global-tool"

配置文件方式 (.neovate/settings.json):

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "your-key"
      }
    },
    "remote-tool": {
      "type": "http",
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

4.2 Git Worktree 工作区

# 创建隔离工作区
neovate workspace create feature-auth
# 创建 .neovate-workspaces/feature-auth/ 目录

# 在工作区中启动 Neovate Code
cd .neovate-workspaces/feature-auth
neovate

# 完成后回到主工作区
cd ../..

# 清理工作区
rm -rf .neovate-workspaces/feature-auth

并行 Agent 模式:

# 终端 1: 处理功能 A
cd .neovate-workspaces/feature-a
neovate

# 终端 2: 处理功能 B
cd .neovate-workspaces/feature-b
neovate

# 两个 Agent 独立工作，互不冲突

4.3 Headless 模式（CI/CD）

# 基本用法
neovate -q "修复 src/utils.ts 中的类型错误"

# 指定输出格式
neovate -q --output-format json "添加单元测试"

# 完全自动模式
neovate -q --approval-mode yolo --output-format stream-json "重构 API 模块"

# 指定模型
neovate -q --model deepseek "优化性能"

# 指定 MCP 配置
neovate -q --mcp-config ./mcp-config.json "执行任务"

GitHub Actions 集成示例:

name: AI Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @neovate/code
      - run: |
          git diff origin/main...HEAD | neovate -q \
            --output-format json \
            --approval-mode yolo \
            "审查这个 PR 的代码质量，输出 JSON 格式的审查结果"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

4.4 自定义输出风格

通过 Markdown 模板文件自定义 AI 输出格式：

# 创建输出风格模板
cat > output-style.md << 'EOF'
---
name: concise
description: 简洁风格输出
---

请以以下格式回复：
- 变更摘要（1-2 句）
- 修改的文件列表
- 关键代码变更说明
EOF

# 使用自定义风格
neovate --output-style ./output-style.md

4.5 插件开发

创建自定义插件：

// my-plugin.ts
import type { Plugin } from '@neovate/code';

export default const plugin: Plugin = {
  name: 'my-company-plugin',

  // 注入上下文信息
  context: () => {
    return {
      'Company API Base URL': 'https://api.mycompany.com',
      'Coding Standard': 'ESLint + Prettier',
      'Team Lead': '张三'
    };
  }
};

在 .neovate/settings.json 中注册：

{
  "plugins": {
    "my-plugin": {
      "path": "./plugins/my-plugin.ts"
    }
  }
}

五、CLI 完整参考

命令行选项

neovate [选项] [初始提示]

# 核心选项
  --approval-mode <mode>     审批模式: default, autoEdit, yolo
  --model <model>            指定模型
  --plan-model <model>       指定规划模型
  -c, --continue             继续最近的会话
  -r, --resume <id>          恢复指定会话
  -q, --quiet                静默/无交互模式
  --output-format <format>   输出格式: stream-json, json, text
  --output-style <file>      自定义输出风格模板
  --mcp-config <config>      MCP 配置（JSON 或文件路径）

# MCP 子命令
neovate mcp add <name>       添加 MCP 服务器
neovate mcp get <name>       查看服务器详情
neovate mcp rm <name>        删除服务器
neovate mcp enable <name>    启用服务器
neovate mcp disable <name>   禁用服务器
neovate mcp ls               列出所有服务器

# 工作区子命令
neovate workspace create     创建隔离工作区

# 全局选项
  --version                  显示版本
  --help                     显示帮助

常用工作流

工作流 1: 日常开发
1. neovate                        启动会话
2. /model                         选择模型
3. 描述需求                       AI 生成代码
4. 审批变更                       确认或修改
5. /review                        审查所有变更
6. 提交代码                       git commit

工作流 2: Spec 驱动开发（推荐）
1. neovate workspace create       创建隔离工作区
2. cd .neovate-workspaces/xxx     进入工作区
3. neovate                        启动
4. Shift+Tab 两次                 进入 Brainstorm 模式
5. 描述需求，AI 生成多选题        讨论设计
6. 确认设计后切回 Normal 模式     实现
7. 合并回主分支

工作流 3: CI/CD 集成
1. 编写 neovate -q 命令           配置自动化任务
2. 指定 --output-format json      结构化输出
3. 指定 --approval-mode yolo      全自动
4. 在 CI pipeline 中执行          自动化

六、进阶主题

6.1 Spec 驱动开发（Sorrycc 推荐的最佳实践）

这是 Neovate Code 核心作者 Sorrycc 推荐的生产级工作流：

步骤一: 创建隔离工作区

neovate workspace create

步骤二: 进入 Brainstorm 模式 - 在 Neovate Code 交互界面中按 Shift+Tab 两次 - 描述问题，AI 会生成 1-10+ 道多选题帮助细化设计

步骤三: 迭代讨论 - 与 AI 反复讨论，直到设计完善 - AI 会根据你的选择逐步深入

步骤四: 归档设计文档 - 将确定的设计方案保存到项目中

步骤五: 实现 - 切回 Normal 模式 - 基于设计文档让 AI 实现代码

6.2 并行 Agent 模式

利用 Git Worktree 实现真正的并行 AI 编码：

# 创建多个工作区
neovate workspace create feature-auth
neovate workspace create feature-api
neovate workspace create feature-ui

# 在不同终端窗口中启动
# Terminal 1
cd .neovate-workspaces/feature-auth && neovate

# Terminal 2
cd .neovate-workspaces/feature-api && neovate

# Terminal 3
cd .neovate-workspaces/feature-ui && neovate

# 每个 Agent 独立工作，互不干扰
# 完成后分别合并

6.3 模型选择策略

# 在配置中设置不同模型用于不同用途
# .neovate/settings.json
{
  "model": "claude-sonnet-4",
  "planModel": "deepseek"
}

6.4 VS Code 扩展集成

安装 VS Code 扩展 neovate-assistant: - 在编辑器中使用 Neovate Code - 内嵌终端 + 编辑器面板 - 快捷键: Ctrl-Alt-B 构建, Ctrl-Alt-V 预览, Ctrl-Alt-P 命令面板

6.5 配置最佳实践

项目配置 (.neovate/settings.json):

{
  "model": "claude-sonnet-4",
  "planModel": "deepseek",
  "approvalMode": "autoEdit",
  "autoCompact": true,
  "commit": {
    "auto": false,
    "message": "feat: {description}"
  },
  "language": "zh-CN"
}

个人覆盖 (.neovate/settings.local.json):

{
  "approvalMode": "default",
  "model": "gpt-4.1"
}

七、常见问题

Q1: Neovate Code 和 Claude Code 有什么关系？

Neovate Code 是独立项目，灵感来自 Claude Code，但定位为"开放的 Claude Code"。主要区别：多模型支持、MIT 开源、插件系统、Worktree 隔离。

Q2: 支持哪些 LLM 模型？

内置支持 11+ 提供商：Anthropic, OpenAI, Google, DeepSeek, xAI, Groq, OpenRouter, ModelScope, Moonshot AI, IFlow 等。还支持任意 OpenAI 兼容 API。

Q3: API Key 怎么管理？

通过环境变量设置（如 export ANTHROPIC_API_KEY=sk-ant-...），建议写入 shell 配置文件（.zshrc 或 .bashrc）。不要将 Key 写入配置文件或提交到 Git。

Q4: Yolo 模式安全吗？

Yolo 模式会自动批准所有文件编辑和 Shell 命令。建议仅在以下场景使用： - CI/CD 自动化环境 - 完全信任的测试环境 - 明确知道 AI 会做什么的场景

Q5: AGENTS.md 和 CLAUDE.md 有什么区别？

功能类似，都是为 AI 提供项目级指令。AGENTS.md 是 Neovate Code 使用的格式，支持项目级 + 全局级双层合并。

Q6: 如何处理大型项目的上下文限制？

• 开启 autoCompact 自动压缩上下文
• 使用 AGENTS.md 精简聚焦关键信息
• 将大任务拆分为小任务
• 使用 Plan Mode 先规划再实现

Q7: 如何在团队中使用？

• 将 .neovate/settings.json 和 AGENTS.md 提交到 Git
• 每个成员用 settings.local.json 覆盖个人偏好
• 利用 Worktree 做并行开发

Q8: Neovate Code 支持中文吗？

支持。在 .neovate/settings.json 中设置 "language": "zh-CN" 即可获得中文交互体验。中文场景推荐使用 Qwen3 Coder、DeepSeek 或 Moonshot 模型。

八、参考资料

官方资源

• GitHub 仓库: https://github.com/neovateai/neovate-code
• 官方文档: https://neovateai.dev
• npm 包: https://www.npmjs.com/package/@neovate/code

社区资源

• 阮一峰周刊自荐: https://github.com/ruanyf/weekly/issues/7805
• 知乎官方公告: https://zhuanlan.zhihu.com/p/1954202059206277079
• Linux.do 社区讨论: https://linux.do/t/topic/993411

学习资源

• Sorrycc 最佳实践博客: https://sorrycc.com/best-practices-with-neovate-code
• Jimmy Song AI 开源全景: https://jimmysong.io/zh/ai/neovate-code/
• AI 编程社区推荐: https://aicoding.csdn.net/6902b54682fbe0098ca66065.html

相关工具

• VS Code 扩展: 搜索 neovate-assistant
• MCP 服务器目录: https://github.com/modelcontextprotocol/servers
• AI SDK (Vercel): https://sdk.vercel.ai

学习路线图

第1天: 基础入门
├── 安装和配置环境
├── 设置 API Key
├── 启动第一个会话
└── 尝试基本对话和代码生成

第2-3天: 核心功能
├── 掌握 AGENTS.md 规则文件
├── 学习 Slash 命令
├── 理解审批模式（default/autoEdit/yolo）
└── 练习代码审查流程

第4-5天: 进阶功能
├── 配置 MCP 服务器
├── 尝试 Git Worktree 隔离
├── 学习 Plan Mode 和 Brainstorm Mode
└── 实践 Spec 驱动开发

第6-7天: 工作流集成
├── 尝试并行 Agent 模式
├── 配置 Headless 模式
├── 编写自定义插件
└── 建立 CI/CD 集成流程