Easy Agent

一个强大的终端 AI Agent 框架，支持多模型切换、工具调用、权限管理和上下文压缩

特性

• 首次引导配置：第一次启动自动引导选择大模型提供商和 API Key
• 多模型支持：DeepSeek、智谱 GLM、OpenAI、Moonshot、通义千问等无缝切换
• 运行时模型切换：在会话中随时切换模型，无需重启
• 完整工具集：文件读写、Bash 执行、Grep 搜索、Glob 文件查找、内存管理等
• 权限管理系统：精细的权限控制，支持危险操作确认、环境变量保护
• 上下文压缩：智能 Token 预算管理，自动压缩长对话，支持手动压缩
• 记忆系统：持久化会话记忆，支持忽略规则管理
• 终端 UI：基于 React + Ink 的现代化终端界面

安装

全局安装（推荐）

npm install -g @codejing430/easy-agent

本地项目安装

npm install @codejing430/easy-agent

使用 npx（免安装）

npx @codejing430/easy-agent

快速开始

1. 首次启动

首次运行 easy-agent 会自动触发模型配置向导：

easy-agent

向导将引导你：

1. 选择大模型提供商（DeepSeek / 智谱 / OpenAI / Moonshot / 通义千问 / 自定义）
2. 输入 API Key
3. 选择或输入模型名称
4. 确认并保存配置

配置完成后即可开始对话。

2. 日常使用

# 启动交互式 Agent
easy-agent

# 指定初始消息
easy-agent "帮我分析这个项目"

# 指定模型
easy-agent --model deepseek-chat

# 重新配置模型
easy-agent --setup

# 查看帮助
easy-agent --help

# 查看版本
easy-agent --version

# 调试系统提示词
easy-agent --dump-system-prompt

3. 会话中切换模型

在对话过程中，直接用自然语言告诉 Agent 即可：

你: 帮我切换到 deepseek-chat
你: 我想用 GPT-4o
你: 切换模型到 glm-4-flash

Agent 会自动调用 switch_model 工具完成切换，新模型立即生效。

配置

配置文件

模型配置保存在 ~/.easy-agent/model-config.json：

{
  "model": "deepseek-chat",
  "baseURL": "https://api.deepseek.com",
  "apiKey": "sk-xxx",
  "createdAt": "2026-04-30T00:00:00.000Z",
  "updatedAt": "2026-04-30T00:00:00.000Z"
}

环境变量（可选）

也可以通过 .env 文件或环境变量设置，优先级低于配置文件：

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o

权限配置

权限配置保存在 .agent/settings.json：

{
  "mode": "default",
  "allow": ["Read", "Bash(ls)", "Bash(cat *)"],
  "deny": ["Bash(rm *)", "Bash(dd *)"]
}

支持的模型提供商

| 提供商 | Base URL | 可用模型 | |--------|----------|----------| | DeepSeek | https://api.deepseek.com | deepseek-chat, deepseek-reasoner | | 智谱 (GLM) | https://open.bigmodel.cn/api/paas/v4 | glm-4-flash, glm-4-plus, glm-4-long | | OpenAI | https://api.openai.com/v1 | gpt-4o, gpt-4o-mini, gpt-4-turbo | | Moonshot | https://api.moonshot.cn/v1 | moonshot-v1-8k, moonshot-v1-32k, moonshot-v1-128k | | 通义千问 | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen-turbo, qwen-plus, qwen-max | | 自定义 | 自行输入 | 自行输入 |

所有提供商均使用 OpenAI 兼容 API 接口。

功能特性

工具系统

Agent 支持以下工具：

| 工具 | 功能 | 权限级别 | |------|------|----------| | file_reader | 读取文件内容 | 读取 | | file_writer | 写入文件 | 写入（需确认） | | file_editor | 编辑文件（唯一匹配替换） | 写入（需确认） | | bash | 执行 Bash 命令 | 命令执行（需确认） | | grep | 搜索文件内容 | 读取 | | glob | 查找文件 | 读取 | | switch_model | 切换大模型 | 系统 | | memory_* | 管理会话记忆 | 系统 |

权限管理

• 危险操作确认：写入文件、执行命令等操作需要用户确认
• 环境变量保护：敏感环境变量自动隐藏
• 工作目录限制：只能在当前项目目录内操作文件
• 命令白名单：限制可执行的 Bash 命令
• 三种模式：default（默认）、plan（计划模式，只读）、auto（自动模式）

上下文压缩

• 自动压缩：当 Token 使用超过阈值时自动压缩历史对话
• 手动压缩：使用 /compact 命令手动触发压缩
• 智能摘要：保留关键对话信息，丢弃冗余内容
• Token 预算：多级预警机制，防止 API 超限

记忆系统

• 持久化存储：跨会话保存对话记忆
• 忽略规则：可配置忽略特定文件/目录的修改
• 记忆查询：通过 Memory 工具管理记忆

开发

项目结构

src/
├── core/           # 核心逻辑（Agent Loop、Query Engine）
├── tools/          # 工具实现
├── session/        # 会话管理（压缩、Token 预算）
├── permissions/    # 权限系统
├── ui/             # 终端 UI 组件
├── services/       # API 服务（客户端、适配器、模型配置）
└── entrypoint/     # CLI 入口

构建

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 测试
npm test

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request。

支持

如果在使用中遇到问题，请：

1. 查看 easy-agent --help 获取命令行帮助
2. 运行 easy-agent --setup 重新配置模型
3. 使用 easy-agent --dump-system-prompt 调试系统提示词
4. 在 GitHub 仓库中提交 Issue