Easy Agent

一个使用 TypeScript 和 Node.js 构建的开源终端 Coding Agent。

Easy Agent 在一套可阅读、可扩展的代码中提供类 Claude Code 工作流：流式模型对话、本地文件与 Shell 工具、权限模式、会话、MCP、Skills、Sub-Agent、Agent Teams、多模态输入和插件系统。

English documentation: README.md

路线图与当前进度

Easy Agent 采用 37 阶段路线图，从模型通信开始，逐步构建到最终分发。

快速开始

运行要求：Node.js 22 或更高版本、npm，以及至少一个受支持模型服务的凭证。

无需安装即可试用：

export ANTHROPIC_AUTH_TOKEN="your-token"
npx --yes eagent@latest

也可以全局安装：

npm install -g --ignore-scripts eagent
eagent

同时提供长命令名：

easy-agent --help

macOS 和 Linux 可以使用基于 npm 的安装脚本：

curl -fsSL https://raw.githubusercontent.com/ConardLi/easy-agent/main/install.sh | sh

安装脚本只会检查 Node.js、使用 --ignore-scripts 安装同一个 npm 包、确认 eagent 已进入 PATH；它不会替你安装 Node.js，也不会执行包生命周期脚本。

模型配置

使用原始 Anthropic 模型名时，只配置环境变量即可：

export ANTHROPIC_AUTH_TOKEN="your-token"
export ANTHROPIC_MODEL="claude-sonnet-4-20250514" # 可选
eagent

Easy Agent 也支持具名的 Anthropic、OpenAI 兼容、Gemini 和本地模型 Profile。用户级配置放在 ~/.easy-agent/settings.json，项目级配置放在 .easy-agent/settings.json：

{
  "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"
    }
  }
}

通过 eagent --model gpt 启动，或在 REPL 中执行 /model gpt 选择 Profile。

运行 /config list、/model list 或 /doctor 可以检查最终生效的配置。

常用方式

eagent                         # 交互式 REPL
eagent --model gpt             # 选择模型 Profile
eagent --plan                  # 只读计划模式
eagent --auto                  # 分类器辅助的权限模式
eagent --resume                # 恢复最近一次会话
eagent --resume <session-id>   # 恢复指定会话
eagent -p "总结这个仓库"                         # Headless 文本输出
eagent -p "列出可用工具" --output-format json   # 机器可读输出
git diff | eagent -p "审查这个补丁"              # 合并 stdin 与 Prompt

运行 eagent --help 查看全部启动参数。常用 REPL 命令包括：

核心能力

• 文件与代码工具：Read、Write、Edit、MultiEdit、Glob、Grep、Bash、PowerShell
• Web 与外部工具：WebFetch、WebSearch、MCP Tools、MCP Resources
• 安全执行：Allow/Ask/Deny、Plan Mode、Auto Mode、项目可信判断、Hooks 和受支持平台上的 Shell Sandbox
• 长任务：TodoWrite、持久化任务图、Sub-Agent、后台运行、Git Worktree 隔离、Agent Teams
• 上下文与连续性：会话持久化、Resume、Compaction、Token 预算、项目记忆、文件检查点和 Rewind
• 扩展能力：Skills、自定义 Agents、Slash Commands、Output Styles、Hooks、MCP Servers、Plugins 和静态 Marketplace
• 使用接口：Ink 交互界面、Headless text/JSON/NDJSON、图片与截图、多模型协议

升级与卸载

升级全局包，或重新运行安装脚本：

npm install -g --ignore-scripts eagent@latest

卸载：

npm uninstall -g eagent

卸载 npm 包时，~/.easy-agent/ 下的用户配置与会话会被有意保留。

故障排查

1. 运行 eagent --version，并用 node --version 确认 Node.js 版本。
2. 在 Easy Agent 中运行 /doctor，检查凭证、Settings、MCP、Plugins、Sandbox 支持和目录写入权限。
3. 运行 /status 和 /config list，确认当前模型与配置来源。
4. 如果全局安装成功但找不到 eagent，请把 npm prefix -g 对应的全局 bin 目录加入 PATH，然后打开一个新 Shell。
5. 可复现的问题请提交到 GitHub Issues。

提交 Issue 时不要包含 API Key、.env 内容或私密 Prompt。

架构

Easy Agent 将五层运行时职责保持分离：

终端 UI
    ↓
QueryEngine（多轮编排）
    ↓
Agentic Loop（推理 → 工具 → 观察）
    ↓
工具与权限执行
    ↓
Provider API 与流式适配

打包发布是包裹这五层的交付层。npm 包发布为可读的 ESM 单文件 bundle 和 sourcemap，不携带运行时依赖树。

实现主线和教程快照已完成到阶段 35；阶段 36 负责把 CLI 打包分发，并补齐面向用户的公共文档。

本地开发

git clone https://github.com/ConardLi/easy-agent.git
cd easy-agent
npm install
npm run dev

常用检查：

npm run typecheck
npm run build
npm run test:stage36
npm run verify:release
npm publish --dry-run

主代码位于 src/，阶段快照位于 step/。dist/ 是生成且被 Git 忽略的构建目录。

贡献

项目仍在快速演进，目前暂不接收外部 Pull Request。欢迎提交带有明确复现步骤的 Issue。

License

MIT