SuperAgent

English

基于 Claude SDK 的本地 AI Agent，采用 Plan-Execute-Reflect 三段式架构。零构建，浏览器打开即用。

特性

• Plan-Execute-Reflect — 结构化三段式管线：Planner 输出结构化计划 → Executor 分步独立执行（防上下文雪崩）→ Reflector 失败时自动诊断修复
• 多模态输入 — 支持图片上传（每条消息最多 8 张图片）
• 工具调用 — 文件读写、Shell 执行、Web 搜索与抓取
• 技能系统 — 通过 .claude/skills/ 目录动态扩展能力
• SSE 流式输出 — 实时流式推送到浏览器
• 会话归档 — 对话历史自动持久化
• 内容安全降级 — 触发内容审查时自动切换备用模型
• 可定制人设 — 编辑 agent-persona.md 即时生效，无需重启

快速开始

通过 npm 安装

# 全局安装
npm install -g superagent-ai-agent

# 在新目录中初始化配置
mkdir my-agent && cd my-agent
superagent init

# 编辑 .env 填入 API 凭证
# 然后启动
superagent

通过 curl 安装

curl -fsSL https://raw.githubusercontent.com/nodermachine/superagent/main/install.sh | bash

通过 npx 使用（无需全局安装）

npx superagent-ai-agent init
npx superagent-ai-agent

从源码运行

git clone [email protected]:nodermachine/superagent.git
cd superagent
npm install
cp .env.example .env
# 编辑 .env 填入凭证
npm start

配置说明

环境变量（.env）

| 变量名 | 必填 | 说明 | |--------|------|------| | ANTHROPIC_BASE_URL | 是 | API 网关地址（支持 Anthropic 官方、AWS Bedrock、OpenAI 兼容接口等） | | ANTHROPIC_AUTH_TOKEN | 是 | API 认证令牌 | | PORT | 否 | 服务端口（默认 3000） | | ANTHROPIC_MODEL | 否 | 文本模型名称（默认 claude-sonnet-4-6） | | ANTHROPIC_MODEL_VISION | 否 | 多模态模型名称（默认与文本模型相同） | | ANTHROPIC_MODEL_FALLBACK | 否 | 内容审查触发时的备用模型 | | SUPERAGENT_PLAN | 否 | 设为 0 关闭 Plan-Execute 管线 |

Agent 配置（agent-config.json）

{
  "agentName": "SuperAgent",
  "userName": "User",
  "avatar": "avatar.png"
}

人设（agent-persona.md）

自定义 Agent 的性格、语气和行为规则。修改后立即生效，无需重启服务。

CLI 使用

superagent [选项]

命令:
  superagent              启动 Agent 服务
  superagent init         在当前目录初始化配置文件

选项:
  --port, -p <端口>       服务端口（默认 3000）
  --help, -h              显示帮助
  --version, -v           显示版本号

架构

┌─────────────────────────────────────────┐
│           浏览器 (Web UI)                │
│         http://localhost:3000            │
└───────────────┬─────────────────────────┘
                │ SSE
┌───────────────▼─────────────────────────┐
│           Express 服务器                  │
│         (src/server.js)                  │
└───────────────┬─────────────────────────┘
                │
┌───────────────▼─────────────────────────┐
│        Plan-Execute-Reflect             │
│           (src/agent.js)                │
│                                         │
│  ┌─────────┐ ┌──────────┐ ┌─────────┐  │
│  │ Planner │→│ Executor │→│Reflector│  │
│  └─────────┘ └──────────┘ └─────────┘  │
└───────────────┬─────────────────────────┘
                │
┌───────────────▼─────────────────────────┐
│         Claude Agent SDK                 │
│   工具: Read/Write/Edit/Bash/Web         │
└──────────────────────────────────────────┘

技能系统

SuperAgent 支持动态技能扩展。将技能定义放在 .claude/skills/<name>/ 下：

.claude/skills/<name>/
├── SKILL.md          ← 必需：frontmatter + 使用说明
└── helpers/          ← 可选：辅助脚本/模板

系统要求

• Node.js >= 20
• 一个兼容 Claude 的 API 密钥

许可证

MIT