Easy Agent

一个从零开始、以开源方式完整复刻 Claude Code 体验的终端 Agent 工程项目。

Easy Agent 是一个长期演进的工程项目，目标是用 TypeScript 和 Node.js 逐步重建一个完整的本地 Agentic Coding System。它不是几个零散 Demo 的集合，而是一个面向真实工程能力的开源复刻项目：具备清晰架构、安全边界、多轮编排、本地工具执行能力，以及进一步走向完整 Claude Code 级开发体验所需的扩展能力。

这个仓库是该目标的开源实现主线。后续会逐步补充更完整的文档，当前 README 重点说明项目本身：它想做成什么、采用什么架构、目前推进到哪里。

English version: see README.md

项目愿景

Easy Agent 的目标，是成为一个严肃的、可持续演进的、本地 Coding Agent 开源复刻项目。

核心目标：

• 以开源方式完整复刻 Claude Code 风格工作流
• 保持架构清晰、职责明确、便于扩展
• 优先实现真实工程系统，而不是玩具示例
• 逐步演进为完整的本地 Agent CLI
• 为持久化、上下文压缩、MCP、Skills、Sandbox、Sub-Agent、多 Agent 协作、多模态输入、插件生态与打包发布保留稳定的扩展路径

当前状态

当前阶段： 阶段 34 —— Extended Thinking，下一阶段

当前实现主线已经完成到阶段 33，包括 CLI、流式通信、工具执行、终端 UI、会话编排、上下文管理、MCP、Skills、Sandbox、Sub-Agent、后台执行、Agent Teams、Hooks、Output Styles、用户命令、渲染体验升级、统一配置、文件历史、错误韧性、管道模式、AI 分类器 Auto Mode、多 Provider 流式适配，Web、MultiEdit、MCP Resources、PowerShell 等核心工具补全，图片多模态输入，以及更完整的内置命令集。阶段 34 是下一块重点：Extended Thinking 控制与展示。

单文件 step/ 快照现在已经覆盖阶段 1–33，因此已完成章节既可以从主源码阅读，也可以从聚焦的独立快照文件中对照学习。

因此，当前的 Easy Agent 更适合被理解为一个正在稳步推进的开源复刻工程，而不是已经面向终端用户完全交付的成品。

架构设计

Easy Agent 按照五层架构推进：

+---------------------------------------------------+
| 1. 交互层                                          |
|    终端 UI、输入处理、渲染输出                        |
+---------------------------------------------------+
| 2. 编排层                                          |
|    多轮会话流转、usage、命令控制                      |
+---------------------------------------------------+
| 3. 核心 Agentic Loop                               |
|    推理 -> 调工具 -> 观察结果 -> 继续推理              |
+---------------------------------------------------+
| 4. 工具层                                          |
|    文件、Shell、搜索、Web、MCP 等本地行动能力            |
+---------------------------------------------------+
| 5. 通信层                                          |
|    Provider Profile 与多模型流式通信                   |
+---------------------------------------------------+

这种分层方式让系统更容易持续演进：

• 通信层 负责 Provider 选择、请求格式转换与模型流式输入输出
• 工具层 负责向模型暴露行动能力
• 核心循环层 负责单轮自主执行闭环
• 编排层 负责多轮状态与控制流
• 交互层 负责把整个运行时变成可用的终端产品

仓库结构

easy-agent/
├── src/
│   ├── entrypoint/      # CLI 启动入口
│   ├── ui/              # React/Ink 终端界面
│   ├── core/            # agentic loop 与 query orchestration
│   ├── agents/          # 子 Agent 定义、注册表与运行器
│   ├── tools/           # 本地工具与工具注册系统
│   ├── services/        # Provider API、MCP 与 Skills 服务
│   ├── permissions/     # 权限与安全控制
│   ├── context/         # system prompt 与上下文管理
│   ├── sandbox/         # Bash 沙箱 profile 与命令包装
│   ├── session/         # 会话持久化与历史
│   ├── state/           # Todo、Task、Agent 等运行时状态
│   ├── types/           # 共享领域类型
│   └── utils/           # env、config、log、辅助函数
├── package.json
├── tsconfig.json
├── README.md
└── README.zh-CN.md

路线图与当前进度

项目遵循一个 37 阶段路线图，以渐进方式完整复刻 Claude Code 风格系统。

easy-agent/step/ 目录中已经补充了教程化的里程碑核心代码，意味着每个已完成章节都可以直接对照学习、逐步复刻。

当前实现进度补充：

• 阶段 32 已在源码、文章主线和 step 快照中完成。
• 阶段 33 已在源码、文章主线和 step 快照中完成。
• 阶段 34 Extended Thinking 是下一阶段，它会补齐请求侧 thinking 控制、预算配置、流式 thinking 事件和终端展示。

Easy Agent 是什么，以及它不是什么

Easy Agent 是： - 一个开源复刻项目 - 一个系统工程实践项目 - 一个面向长期演进的本地 Coding Agent 实现 - 一个持续朝完整 Claude Code 级 CLI 推进的公开代码库

Easy Agent 不是： - 一个单文件 Demo - 一个只包了一层 Prompt 的 API 壳子 - 一个今天就已经完全完成的产品 - 任何私有课程内容的公开镜像

快速开始

环境要求

• Node.js 22+
• npm
• 至少一种受支持模型 Provider 的访问能力：Anthropic、OpenAI 兼容 API、Gemini，或 Ollama 这类本地 OpenAI 兼容端点

模型 Provider

Easy Agent 默认支持多 Provider。原始 Claude/Anthropic 模型名仍可直接使用；OpenAI 兼容 API 与 Gemini 通过 settings.json 中的命名模型 Profile 配置，再用 --model 或 /model 选择。

用户级或项目级 settings 示例：

{
  "defaultModel": "gpt",
  "models": {
    "gpt": {
      "protocol": "openai-chat",
      "model": "gpt-5.1",
      "baseURL": "https://api.openai.com/v1",
      "apiKey": "${OPENAI_API_KEY}"
    },
    "gemini": {
      "protocol": "gemini",
      "model": "gemini-2.5-pro",
      "apiKey": "${GEMINI_API_KEY}"
    },
    "ollama": {
      "protocol": "openai-chat",
      "model": "qwen2.5-coder",
      "baseURL": "http://localhost:11434/v1"
    }
  }
}

常用环境变量：

• ANTHROPIC_AUTH_TOKEN —— 原始 Claude/Anthropic 模型名使用的 API Token
• ANTHROPIC_BASE_URL —— 可选的 Anthropic 兼容 API Base URL
• ANTHROPIC_MODEL —— 旧式/默认原始 Anthropic 模型名
• OPENAI_API_KEY —— ${OPENAI_API_KEY} Profile 使用的 OpenAI 兼容 API Key
• GEMINI_API_KEY —— ${GEMINI_API_KEY} Profile 使用的 Gemini API Key
• WEB_SEARCH_API_KEY —— 可选的 WebSearch Provider Key

安装

npm install

开发运行

npm run dev

构建运行

npm run build
npm start

CLI 示例

agent --help
agent --model claude-sonnet-4-20250514
agent --model gpt
agent --model gemini
echo "summarize this repo" | agent --print --output-format json
agent --plan
agent --auto
agent --dump-system-prompt

近期重点

接下来最重要的几个里程碑是：

1. 在阶段 34 补齐 Extended Thinking 控制与展示
2. 继续推进阶段 35 Plugins 与 Marketplace
3. 在阶段 36 收拢打包发布与文档工作

贡献策略

Easy Agent 当前暂不接受外部贡献。

项目仍处于高频演进阶段，整体实现、目录结构和开发约定都还可能持续变化。等项目进入更稳定、更适合维护协作的状态后，才会正式开放外部贡献。

在此之前，欢迎关注项目进展和公开路线图，但暂时不会接收 Pull Request 或外部代码贡献。

License

MIT