<div align="center">

🚀 Easy Code

AI 驱动的智能编程助手

赋能开发者，加速创新

ℹ️ 品牌升级提示：本项目原名 Easy Code，现已统一更名为 Easy Code。 包名、命令名、配置目录在过渡期内保留旧名（easycode-ai / easycode / .easycode/ 等）以保证向后兼容；后续新文档与界面均使用新品牌名。

<br>

<br>

English | 简体中文

<br> <!-- 如果有演示 GIF，取消下面这行注释 --> <!-- <img src="docs/assets/demo.gif" alt="Easy Code Demo" width="800"> --> </div>

---

📖 目录

• 项目简介
• 为什么选择 Easy Code
• 核心特性
• 快速安装
• 快速开始
• CLI 命令参考
• 交互式斜杠命令
• 项目架构
• VS Code 扩展
• 内置工具系统
• MCP 协议支持
• Hooks 钩子机制
• 配置文件
• 开发指南
• 常见问题
• 贡献指南
• 路线图
• 许可证
• 相关链接

---

✨ 项目简介

Easy Code 是一款革命性的 AI 驱动智能编程助手，通过深度整合人工智能技术，全面提升软件开发的效率、质量和创新能力。

不同于传统的代码补全工具，Easy Code 是一个能够理解整个项目上下文、自主编排工具完成复杂任务的智能代理（Agent）。它将开发者从繁琐重复的工作中解放出来，让你专注于更高层次的创新和问题解决。

💡 Easy Code 能做什么？

👤 你：帮我分析这个项目的架构，找出性能瓶颈，并给出优化方案

🤖 Easy Code：
   ├── 📂 扫描项目结构，理解模块依赖
   ├── 🔍 分析代码热点和复杂度
   ├── 📊 识别潜在的性能问题
   ├── 💡 生成优化建议和重构方案
   └── ✏️ 自动应用修改（经你确认后）

---

🌟 为什么选择 Easy Code

<table> <tr> <td width="50%">

🎯 与传统 AI 编码助手的区别

| 特性 | 传统工具 | Easy Code | |:---:|:---:|:---:| | 上下文范围 | 单文件 | 整个项目 | | 交互方式 | 被动补全 | 主动代理 | | 任务复杂度 | 简单补全 | 复杂工作流 | | 工具调用 | 无 | Shell/文件/Web | | 会话管理 | 无 | 持久化会话 | | 可扩展性 | 受限 | MCP/Hooks/Skills |

</td> <td width="50%">

🚀 核心优势

• 🧠 深度理解 - 通过 MCP 协议构建完整项目认知
• 🛠️ 自主执行 - AI 可调用工具完成实际操作
• 🔄 持续对话 - 会话保存/恢复，上下文不丢失
• 🎨 多端支持 - CLI + VS Code 插件
• 🔌 高度可扩展 - Hooks、Skills、MCP 服务器
• 🔒 安全可控 - 敏感操作需用户确认

</td> </tr> </table>

---

🎯 核心特性

🧠 AI 驱动的代码生成与重构

• 智能代码生成 - 根据自然语言描述生成完整的函数、类、模块甚至整个应用
• 代码重构建议 - 识别代码异味，提供优化方案，自动统一代码风格
• Bug 智能修复 - 分析错误堆栈，定位问题根源，生成修复代码
• 多语言支持 - TypeScript、JavaScript、Python、Go、Rust、Java 等主流语言

🔍 智能调试与问题解决

• 错误日志分析 - 深入解析错误信息，快速定位问题
• 堆栈追踪诊断 - 理解调用链路，找出异常根因
• 自动修复执行 - 生成修复方案，一键应用（需确认）
• 增强调试控制台 - Ctrl+O 三状态循环：全部日志 → 仅错误 → 关闭，智能过滤错误信息

📦 高级上下文管理 (MCP)

Model Context Protocol (MCP) 是 Easy Code 的核心创新：

• 全局项目视图 - 理解文件结构、模块依赖、代码语义
• 跨文件分析 - 追踪函数调用链、类型引用、导入导出
• 智能上下文选择 - 自动识别与任务相关的文件和代码段
• 第三方 MCP 服务器 - 接入外部数据源和工具

🛠️ 可扩展工具系统

AI 通过工具与外部环境交互，内置丰富工具集：

📁 文件操作    → read_file, write_file, replace, delete_file, glob
🔍 代码搜索    → grep (ripgrep), read_many_files
💻 命令执行    → shell (bash/powershell)
🌐 网络访问    → web_fetch, web_search (Google)
🧩 MCP 工具    → 调用任意 MCP 服务器提供的工具
📊 代码分析    → task (启动分析子 Agent)
📝 任务管理    → todo_write
💾 记忆系统    → memory (长期记忆)

🪝 Hooks 钩子机制

在关键工作流节点注入自定义逻辑：

• PreToolExecution - 工具执行前触发
• PostToolExecution - 工具执行后触发
• OnSessionStart - 会话开始时触发
• OnSessionEnd - 会话结束时触发

支持自动化代码检查、格式化、提交前验证等场景。

🔄 会话管理

• 会话持久化 - 自动保存对话历史和上下文
• 会话恢复 - 随时继续之前的工作
• 历史压缩 - 智能压缩对话历史，节省 Token
• 检查点恢复 - 文件修改可回滚到之前状态

---

📦 快速安装

系统要求

• Node.js 20.0.0 或更高版本
• 操作系统 Windows / macOS / Linux
• 终端 支持 ANSI 颜色的终端模拟器

方式一：npm 全局安装（推荐）

# 使用 npm
npm install -g easycode-ai

# 使用 yarn
yarn global add easycode-ai

# 使用 pnpm
pnpm add -g easycode-ai

安装完成后，验证安装：

easycode --version

方式二：从源码构建

# 1. 克隆仓库
git clone https://github.com/OrionStarAI/EasyCodeCode.git
cd EasyCode

# 2. 安装依赖
npm install

# 3. 构建项目
npm run build

# 4. 本地开发运行
npm run dev

# 5. (可选) 生产环境打包
npm run pack:prod

---

🚀 快速开始

第一步：启动 Easy Code

在任意项目目录中运行：

easycode

首次启动会引导你完成身份认证。

第二步：开始对话

┌─────────────────────────────────────────────────────────────┐
│  🚀 Easy Code - AI 驱动的智能编程助手                    │
│─────────────────────────────────────────────────────────────│
│                                                             │
│  👋 你好！我是 Easy Code，你的 AI 编程助手。                  │
│                                                             │
│  💡 试试这些命令开始：                                        │
│     • "分析这个项目的架构"                                    │
│     • "帮我写一个用户登录的 API"                              │
│     • "这段代码有什么问题？"                                  │
│     • /help 查看帮助                                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

> 你想做什么？

第三步：与 AI 协作

# 示例对话
> 帮我创建一个 Express REST API，包含用户的 CRUD 操作

🤖 好的，我来帮你创建。首先让我了解一下项目结构...

[调用工具: glob] 扫描项目文件...
[调用工具: read_file] 读取 package.json...
[调用工具: write_file] 创建 src/routes/users.js...
[调用工具: write_file] 创建 src/controllers/userController.js...
[调用工具: shell] 安装依赖 express...

✅ 已创建用户 CRUD API，包含以下文件：
   - src/routes/users.js
   - src/controllers/userController.js
   - src/models/User.js

启动服务器：npm run dev

---

📋 CLI 命令参考

全局选项

easycode [options]

| 选项 | 简写 | 说明 | |:---|:---:|:---| | --model <name> | -m | 指定 AI 模型 | | --prompt <text> | -p | 非交互模式，执行单次提示 | | --prompt-interactive <text> | -i | 执行提示后进入交互模式 | | --sandbox | -s | 在沙箱环境中运行（增强安全性） | | --debug | -d | 启用调试模式，输出详细日志 | | --all-files | -a | 在上下文中包含所有项目文件 | | --yolo | -y | YOLO 模式：自动执行所有操作，无需确认 | | --continue | -c | 继续上次会话 | | --session <id> | | 恢复指定 ID 的会话 | | --list-sessions | | 列出所有可用会话 | | --workdir <path> | | 指定工作目录 | | --version | -v | 显示版本号 | | --help | -h | 显示帮助信息 |

使用示例

# 基本启动
easycode

# 使用 Gemini 2.0 Flash 模型
easycode -m gemini-2.0-flash

# 执行单次任务（非交互）
easycode -p "为 src/utils.ts 添加单元测试"

# 继续上次会话
easycode -c

# YOLO 模式（危险：自动执行所有操作）
easycode -y

# 调试模式
easycode -d

# 指定工作目录
easycode --workdir /path/to/project

# 列出所有会话
easycode --list-sessions

# 恢复特定会话
easycode --session abc123

---

⚡ 交互式斜杠命令

在交互模式下，使用以 / 开头的命令快速执行操作：

核心命令

| 命令 | 说明 | |:---|:---| | /help | 显示帮助信息和快速入门指南 | | /help-ask | AI 智能帮助助手，解答使用问题 | | /issue <描述> | 提交 GitHub Issue（自动附带错误日志） | | /quit 或 /exit | 退出应用，显示会话统计 |

会话与模型

| 命令 | 说明 | |:---|:---| | /session | 会话管理：list / new / select <id> / rebuild | | /model [name] | 切换 AI 模型，不带参数显示选择对话框 | | /compress | 压缩对话历史，减少 Token 消耗 | | /stats | 显示会话统计信息 |

工具与扩展

| 命令 | 说明 | |:---|:---| | /tools [nodesc] | 查看可用工具列表 | | /mcp [subcommand] | MCP 服务器管理：add / auth / refresh | | /memory | 长期记忆管理：show / add / refresh |

工作模式

| 命令 | 说明 | |:---|:---| | /plan [on\|off] | 计划模式：只讨论不修改代码 | | /yolo [on\|off] | YOLO 模式：自动执行所有操作 | | /vim | 切换 Vim 编辑模式 |

文件与编辑

| 命令 | 说明 | |:---|:---| | /restore [id] | 恢复文件到检查点状态 | | /refine <text> | 文本润色，支持 --tone / --lang / --level | | /trim-spaces [on\|off] | 配置是否自动删除行末空格 | | /copy | 复制最后一条 AI 回复到剪贴板 |

界面与设置

| 命令 | 说明 | |:---|:---| | /clear | 清空终端屏幕 | | /theme | 主题选择对话框 | | /editor | 编辑器配置对话框 | | /about | 显示系统和应用信息 |

调试控制台

Easy Code 提供增强的调试控制台功能，通过 Ctrl+O 快捷键实现三状态循环：

| 快捷键 | 状态 | 说明 | |:---|:---|:---| | Ctrl+O (第1次) | 📊 全部日志 | 打开调试控制台，显示所有日志信息 | | Ctrl+O (第2次) | ⚠️ 仅错误 | 过滤显示错误日志，显示黄色 [ERRORS ONLY] 标识 | | Ctrl+O (第3次) | 🚫 关闭 | 关闭调试控制台 |

功能特点：

• 🎯 智能过滤：自动识别错误、异常、堆栈跟踪等关键信息
• 🎨 视觉提示：错误模式显示醒目的黄色标识
• ⚡ 快速切换：一键在全部日志和错误过滤间切换
• 🔍 错误高亮：自动检测并显示错误关键词和堆栈信息

账户与认证

| 命令 | 说明 | |:---|:---| | /auth | 身份认证管理 | | /account | 账户信息和余额查看 |

项目配置

| 命令 | 说明 | |:---|:---| | /init | 初始化项目配置文件 EASYCODE.md | | /hooks | 查看 Hooks 钩子机制帮助文档 | | /ide | IDE 集成管理（VS Code 模式下可用） |

---

🏗️ 项目架构

Easy Code 采用现代化的 Monorepo 架构，确保代码一致性和高效协作。

目录结构

EasyCode/
│
├── 📁 packages/                     # 核心包目录
│   │
│   ├── 📁 cli/                      # 命令行界面包
│   │   ├── src/
│   │   │   ├── commands/            # 斜杠命令实现
│   │   │   ├── ui/                  # 终端 UI 组件 (React Ink)
│   │   │   │   ├── components/      # 可复用 UI 组件
│   │   │   │   ├── dialogs/         # 对话框组件
│   │   │   │   └── themes/          # 主题配置
│   │   │   ├── services/            # 服务层
│   │   │   ├── auth/                # 客户端认证
│   │   │   └── utils/               # 工具函数
│   │   └── package.json
│   │
│   ├── 📁 core/                     # 核心功能库
│   │   ├── src/
│   │   │   ├── tools/               # AI 工具集
│   │   │   │   ├── shell.ts         # Shell 命令执行
│   │   │   │   ├── read-file.ts     # 文件读取
│   │   │   │   ├── write-file.ts    # 文件写入
│   │   │   │   ├── edit.ts          # 文件编辑 (replace)
│   │   │   │   ├── glob.ts          # 文件搜索
│   │   │   │   ├── grep.ts          # 内容搜索
│   │   │   │   ├── web-fetch.ts     # 网页抓取
│   │   │   │   ├── web-search.ts    # Google 搜索
│   │   │   │   ├── task.ts          # 子 Agent 任务
│   │   │   │   └── ...
│   │   │   ├── mcp/                 # MCP 引擎
│   │   │   ├── prompts/             # Prompt 模板
│   │   │   ├── auth/                # 认证模块
│   │   │   ├── hooks/               # Hooks 系统
│   │   │   ├── skills/              # Skills 扩展
│   │   │   ├── services/            # 核心服务
│   │   │   ├── config/              # 配置管理
│   │   │   └── utils/               # 工具函数
│   │   └── package.json
│   │
│   ├── 📁 vscode-ide-companion/     # VS Code CLI 伴侣扩展
│   │   ├── src/
│   │   │   └── extension.ts         # 扩展入口
│   │   └── package.json
│   │
│   └── 📁 vscode-ui-plugin/         # VS Code 完整 UI 插件
│       ├── src/                     # 扩展源码
│       ├── webview/                 # React Webview 前端
│       └── package.json
│
├── 📁 docs/                         # 文档目录
│   ├── architecture.md              # 架构设计
│   ├── hooks-user-guide.md          # Hooks 使用指南
│   ├── mcp-improvements-summary.md  # MCP 集成说明
│   └── ...
│
├── 📁 scripts/                      # 构建和工具脚本
│   ├── build.js                     # 主构建脚本
│   ├── build_package.js             # 包构建
│   ├── clean.js                     # 清理脚本
│   └── ...
│
├── 📄 package.json                  # 根配置 (Workspaces)
├── 📄 tsconfig.json                 # TypeScript 配置
├── 📄 eslint.config.js              # ESLint 配置
├── 📄 esbuild.config.js             # esbuild 打包配置
├── 📄 EasyCode_Code_Whitepaper.md      # 产品白皮书
├── 📄 EASYCODE.md                      # 项目 AI 开发规范
└── 📄 LICENSE                       # Apache 2.0 许可证

技术栈详解

| 类别 | 技术 | 说明 | |:---:|:---|:---| | 语言 | TypeScript 5.x | 强类型，提升代码质量 | | 运行时 | Node.js 20+ | 现代 JavaScript 运行时 | | CLI UI | React + Ink | 声明式终端 UI 框架 | | 构建 | esbuild | 极速打包，毫秒级构建 | | 测试 | Vitest | 现代化单元测试框架 | | 代码规范 | ESLint + Prettier | 统一代码风格 | | 包管理 | npm Workspaces | Monorepo 管理 | | AI SDK | @google/genai | Google Gemini API | | MCP | @modelcontextprotocol/sdk | MCP 协议实现 |

交互流程

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   用户输入   │────▶│  CLI 包     │────▶│  Core 包    │
│  (终端)     │     │  (UI/交互)   │     │  (业务逻辑)  │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │                          │                          │
                    ▼                          ▼                          ▼
            ┌─────────────┐           ┌─────────────┐            ┌─────────────┐
            │  AI Model   │           │   Tools     │            │    MCP      │
            │  (Gemini)   │           │ (Shell/File)│            │  Servers    │
            └─────────────┘           └─────────────┘            └───