superagent-ai-agent 0.1.0

package/.env.example

@@ -0,0 +1,27 @@
+# ═══════════════════════════════════════════════════
+# SuperAgent Configuration
+# ═══════════════════════════════════════════════════
+
+# API gateway URL (required)
+# Supports: Anthropic official, AWS Bedrock, Alibaba Cloud, Zhipu AI, etc.
+# Anthropic 兼容网关地址（必填）
+ANTHROPIC_BASE_URL=https://api.anthropic.com
+
+# API auth token (required)
+# 网关认证 token（必填）
+ANTHROPIC_AUTH_TOKEN=
+
+# Optional: server port (default: 3000)
+# PORT=3000
+
+# Optional: text model name (default: claude-sonnet-4-6)
+# ANTHROPIC_MODEL=claude-sonnet-4-6
+
+# Optional: vision model (for image inputs, default: same as text model)
+# ANTHROPIC_MODEL_VISION=
+
+# Optional: fallback model for content moderation triggers
+# ANTHROPIC_MODEL_FALLBACK=
+
+# Optional: set to 0 to disable Plan-Execute pipeline (emergency escape hatch)
+# LUNA_PLAN=0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 SuperAgent Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# SuperAgent
+
+[中文文档](./README.zh-CN.md)
+
+A local AI Agent powered by Claude SDK with **Plan-Execute-Reflect** architecture. Zero-build, browser-ready.
+
+## Features
+
+- **Plan-Execute-Reflect** — Structured 3-phase pipeline: Planner outputs structured plan → Executor runs each step independently (prevents context avalanche) → Reflector auto-diagnoses and fixes failures
+- **Multimodal Input** — Supports image uploads (up to 8 images per message)
+- **Tool Calling** — File read/write, shell execution, web search & fetch
+- **Skills System** — Dynamically extensible via `.claude/skills/` directory
+- **SSE Streaming** — Real-time streaming output to browser
+- **Session Archive** — Automatic conversation history persistence
+- **Content Safety Fallback** — Auto-switches to fallback model on content moderation triggers
+- **Customizable Persona** — Edit `agent-persona.md` to change personality (hot-reload, no restart needed)
+
+## Quick Start
+
+### Install via npm
+
+```bash
+# Global install
+npm install -g superagent-ai-agent
+
+# Initialize config in a new directory
+mkdir my-agent && cd my-agent
+superagent init
+
+# Edit .env with your API credentials
+# Then start
+superagent
+```
+
+### Install via curl
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nodermachine/superagent/main/install.sh | bash
+```
+
+### Install via npx (no global install)
+
+```bash
+npx superagent-ai-agent init
+npx superagent-ai-agent
+```
+
+### Run from source
+
+```bash
+git clone git@github.com:nodermachine/superagent.git
+cd superagent
+npm install
+cp .env.example .env
+# Edit .env with your credentials
+npm start
+```
+
+## Configuration
+
+### Environment Variables (`.env`)
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ANTHROPIC_BASE_URL` | Yes | API gateway URL (supports Anthropic, AWS Bedrock, Alibaba Cloud, Zhipu AI, etc.) |
+| `ANTHROPIC_AUTH_TOKEN` | Yes | API authentication token |
+| `PORT` | No | Server port (default: 3000) |
+| `ANTHROPIC_MODEL` | No | Text model name (default: claude-sonnet-4-6) |
+| `ANTHROPIC_MODEL_VISION` | No | Vision model name (default: same as text model) |
+| `ANTHROPIC_MODEL_FALLBACK` | No | Fallback model for content moderation |
+| `LUNA_PLAN` | No | Set to `0` to disable Plan-Execute pipeline |
+
+### Agent Config (`agent-config.json`)
+
+```json
+{
+  "agentName": "SuperAgent",
+  "userName": "User",
+  "avatar": "avatar.png"
+}
+```
+
+### Persona (`agent-persona.md`)
+
+Customize your agent's personality, tone, and behavior rules. Changes take effect immediately without server restart.
+
+## CLI Usage
+
+```bash
+superagent [options]
+
+Commands:
+  superagent              Start the agent server
+  superagent init         Initialize config files in current directory
+
+Options:
+  --port, -p <port>       Server port (default: 3000)
+  --help, -h              Show help
+  --version, -v           Show version
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│              Browser (Web UI)            │
+│         http://localhost:3000            │
+└───────────────┬─────────────────────────┘
+                │ SSE
+┌───────────────▼─────────────────────────┐
+│            Express Server                │
+│         (src/server.js)                  │
+└───────────────┬─────────────────────────┘
+                │
+┌───────────────▼─────────────────────────┐
+│         Plan-Execute-Reflect            │
+│           (src/agent.js)                │
+│                                         │
+│  ┌─────────┐ ┌──────────┐ ┌─────────┐  │
+│  │ Planner │→│ Executor │→│Reflector│  │
+│  └─────────┘ └──────────┘ └─────────┘  │
+└───────────────┬─────────────────────────┘
+                │
+┌───────────────▼─────────────────────────┐
+│        Claude Agent SDK                  │
+│   Tools: Read/Write/Edit/Bash/Web        │
+└──────────────────────────────────────────┘
+```
+
+## Skills
+
+SuperAgent supports a dynamic skills system. Place skill definitions in `.claude/skills/<name>/`:
+
+```
+.claude/skills/<name>/
+├── SKILL.md          ← Required: frontmatter + instructions
+└── helpers/          ← Optional: helper scripts/templates
+```
+
+## Requirements
+
+- Node.js >= 20
+- An API key for a Claude-compatible endpoint
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,147 @@
+# SuperAgent
+
+[English](./README.md)
+
+基于 Claude SDK 的本地 AI Agent，采用 **Plan-Execute-Reflect** 三段式架构。零构建，浏览器打开即用。
+
+## 特性
+
+- **Plan-Execute-Reflect** — 结构化三段式管线：Planner 输出结构化计划 → Executor 分步独立执行（防上下文雪崩）→ Reflector 失败时自动诊断修复
+- **多模态输入** — 支持图片上传（每条消息最多 8 张图片）
+- **工具调用** — 文件读写、Shell 执行、Web 搜索与抓取
+- **技能系统** — 通过 `.claude/skills/` 目录动态扩展能力
+- **SSE 流式输出** — 实时流式推送到浏览器
+- **会话归档** — 对话历史自动持久化
+- **内容安全降级** — 触发内容审查时自动切换备用模型
+- **可定制人设** — 编辑 `agent-persona.md` 即时生效，无需重启
+
+## 快速开始
+
+### 通过 npm 安装
+
+```bash
+# 全局安装
+npm install -g superagent-ai-agent
+
+# 在新目录中初始化配置
+mkdir my-agent && cd my-agent
+superagent init
+
+# 编辑 .env 填入 API 凭证
+# 然后启动
+superagent
+```
+
+### 通过 curl 安装
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nodermachine/superagent/main/install.sh | bash
+```
+
+### 通过 npx 使用（无需全局安装）
+
+```bash
+npx superagent-ai-agent init
+npx superagent-ai-agent
+```
+
+### 从源码运行
+
+```bash
+git clone git@github.com:nodermachine/superagent.git
+cd superagent
+npm install
+cp .env.example .env
+# 编辑 .env 填入凭证
+npm start
+```
+
+## 配置说明
+
+### 环境变量（`.env`）
+
+| 变量名 | 必填 | 说明 |
+|--------|------|------|
+| `ANTHROPIC_BASE_URL` | 是 | API 网关地址（支持 Anthropic 官方、AWS Bedrock、阿里云百炼、智谱 AI 等） |
+| `ANTHROPIC_AUTH_TOKEN` | 是 | API 认证令牌 |
+| `PORT` | 否 | 服务端口（默认 3000） |
+| `ANTHROPIC_MODEL` | 否 | 文本模型名称（默认 claude-sonnet-4-6） |
+| `ANTHROPIC_MODEL_VISION` | 否 | 多模态模型名称（默认与文本模型相同） |
+| `ANTHROPIC_MODEL_FALLBACK` | 否 | 内容审查触发时的备用模型 |
+| `LUNA_PLAN` | 否 | 设为 `0` 关闭 Plan-Execute 管线 |
+
+### Agent 配置（`agent-config.json`）
+
+```json
+{
+  "agentName": "SuperAgent",
+  "userName": "User",
+  "avatar": "avatar.png"
+}
+```
+
+### 人设（`agent-persona.md`）
+
+自定义 Agent 的性格、语气和行为规则。修改后立即生效，无需重启服务。
+
+## CLI 使用
+
+```bash
+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

package/agent-config.json

@@ -0,0 +1,4 @@
+{
+  "agentName": "SuperAgent",
+  "userName": "User"
+}

package/agent-persona.md

@@ -0,0 +1,67 @@
+# Agent 人设
+
+> 这段内容会作为 `systemPrompt.append` 注入到 Claude Code 默认 system prompt 之后,
+> 决定 Agent 跟用户对话时的身份、语气、风格、边界。
+>
+> 编辑保存后**下一轮对话立刻生效,不用重启服务**（每次 query 都重新读这个文件）。
+
+---
+
+## 身份
+
+- 你的名字从 `agent-config.json` 的 `agentName` 字段读取
+- 你称呼用户为 `agent-config.json` 的 `userName` 字段
+- 你是一个本地运行的个人助理
+- 你能读写当前目录文件、执行 shell 命令
+
+## 语气与风格
+
+- 全程**中文**回答
+- 简短直接,不寒暄,不要「好的我来帮您」「希望对您有帮助」这类客套
+- 工程问题用专业术语,不展开入门概念,除非用户明确问
+- 不确定就说不确定;不要编造 API、字段、链接
+- 拒绝时直说原因,不绕弯子
+
+## 工作守则
+
+- 修改文件前先 `read` / `grep` 现状,不要凭印象重写
+- **不可逆操作**(rm -rf、git reset --hard、git push --force、覆盖未提交改动)**先停下来跟用户确认**
+- 不要主动新建 README / 设计文档 / summary.md,除非用户明确要求
+- 不要顺手清理 / 重构无关代码
+- 不要 `npm install` 新依赖,除非用户同意
+
+## 执行模式(plan-execute-reflection)
+
+本 agent 已启用三段式执行管线,你会在不同 query 里被分配不同角色:
+
+- **Planner**:接到复杂请求时,先输出结构化 plan(JSON),不要直接动手。简单问答判 `needPlan:false`。
+- **Executor**:按 plan 逐步执行,每步聚焦当前目标,完成后一句话总结。
+- **Reflector**:某步失败时被唤起,诊断根因 → 优先跑客观验证(测试/编译/lint)→ 修复,最多一次。
+
+判定复杂度的直觉(满足任一即 `needPlan:true`):
+1. 涉及 2 个以上文件、需要多轮工具调用、有明确先后依赖
+2. 预期输出超过 300 字且含多个模块
+
+单文件小改、解释性回答、单步查询 → 不需要 plan,直接答。
+
+## Skills 管理
+
+你可以读写文件 + 跑 shell,因此完全可以**自己安装、列出、删除 skills**。
+
+### 唯一路径
+
+| 路径 | 是否生效 |
+|---|---|
+| `<项目根>/.claude/skills/<name>/` | ✅ 唯一允许的安装位置 |
+
+### Skill 的最小结构
+
+```
+.claude/skills/<name>/
+├── SKILL.md          ← 必需,frontmatter + 正文
+└── helpers/          ← 可选,放参考脚本/模板
+```
+
+## ← 自由发挥区
+
+在这里加更多个性化规则。

package/bin/postinstall.js

@@ -0,0 +1,26 @@
+/**
+ * bin/postinstall.js — npm postinstall hook
+ *
+ * 全局安装后提示用户下一步操作
+ */
+
+const isGlobal = process.env.npm_config_global === 'true' ||
+  (process.env.npm_lifecycle_event === 'postinstall' && !process.env.INIT_CWD?.includes('node_modules'));
+
+if (isGlobal) {
+  console.log(`
+┌─────────────────────────────────────────────────┐
+│                                                 │
+│   SuperAgent installed successfully! 🎉         │
+│                                                 │
+│   Quick start:                                  │
+│     1. mkdir my-agent && cd my-agent            │
+│     2. superagent init                          │
+│     3. Edit .env with your API credentials      │
+│     4. superagent                               │
+│                                                 │
+│   Docs: https://github.com/nodermachine/superagent │
+│                                                 │
+└─────────────────────────────────────────────────┘
+`);
+}