superagent-ai-agent 0.1.0

package/bin/superagent.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+
+/**
+ * bin/superagent.js — CLI 入口
+ *
+ * 用法:
+ *   superagent              # 启动 Agent 服务
+ *   superagent init         # 在当前目录初始化配置文件
+ *   superagent config       # 交互式配置 API 密钥和网关
+ *   superagent --port 8080  # 指定端口
+ *   superagent --help       # 显示帮助
+ */
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+const VERSION = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version;
+
+// ─── 帮助信息 ───
+const HELP = `
+SuperAgent v${VERSION}
+A local AI Agent with Plan-Execute-Reflect architecture.
+
+Usage:
+  superagent [options]       Start the agent server
+  superagent init            Initialize config files in current directory
+  superagent config          Configure API credentials interactively
+  superagent config --url <url> --token <token>  Configure via flags
+
+Options:
+  --port, -p <port>          Server port (default: 3000, or PORT env)
+  --url <url>                Set ANTHROPIC_BASE_URL
+  --token <token>            Set ANTHROPIC_AUTH_TOKEN
+  --model <model>            Set ANTHROPIC_MODEL
+  --help, -h                 Show this help message
+  --version, -v              Show version number
+
+Environment Variables:
+  ANTHROPIC_BASE_URL         API gateway URL (required)
+  ANTHROPIC_AUTH_TOKEN       API auth token (required)
+  ANTHROPIC_MODEL            Text model name
+  ANTHROPIC_MODEL_VISION     Vision model name
+  PORT                       Server port (default: 3000)
+
+Examples:
+  superagent                 Start with default settings
+  superagent --port 8080     Start on port 8080
+  superagent init            Create .env and config files
+  superagent config          Interactive API setup
+  superagent config --url https://api.anthropic.com --token sk-xxx
+`.trim();
+
+// ─── 解析参数 ───
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (args.includes('--version') || args.includes('-v')) {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+// ─── 工具函数：获取 flag 值 ───
+function getFlag(arr, flag) {
+  const idx = arr.indexOf(flag);
+  return idx !== -1 && arr[idx + 1] ? arr[idx + 1] : null;
+}
+
+// ─── 工具函数：读取 .env 为对象 ───
+function readEnv(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  const content = fs.readFileSync(filePath, 'utf8');
+  const env = {};
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    const val = trimmed.slice(eqIdx + 1).trim();
+    env[key] = val;
+  }
+  return env;
+}
+
+// ─── 工具函数：写入 .env ───
+function writeEnv(filePath, envObj) {
+  // 如果已有文件，就在原文件基础上更新
+  if (fs.existsSync(filePath)) {
+    let content = fs.readFileSync(filePath, 'utf8');
+    for (const [key, val] of Object.entries(envObj)) {
+      // 匹配 KEY=value 或 # KEY=value 形式
+      const re = new RegExp(`^(#\\s*)?${key}\\s*=.*$`, 'm');
+      if (re.test(content)) {
+        content = content.replace(re, `${key}=${val}`);
+      } else {
+        content += `\n${key}=${val}`;
+      }
+    }
+    fs.writeFileSync(filePath, content, 'utf8');
+  } else {
+    const lines = Object.entries(envObj).map(([k, v]) => `${k}=${v}`);
+    fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf8');
+  }
+}
+
+// ─── 工具函数：交互式询问 ───
+function ask(question, defaultVal = '') {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const suffix = defaultVal ? ` [${defaultVal}]` : '';
+  return new Promise((resolve) => {
+    rl.question(`${question}${suffix}: `, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultVal);
+    });
+  });
+}
+
+// ─── config 子命令 ───
+if (args[0] === 'config') {
+  const cwd = process.cwd();
+  const envPath = path.join(cwd, '.env');
+
+  // 解析 --url / --token / --model 标志位
+  const flagUrl = getFlag(args, '--url');
+  const flagToken = getFlag(args, '--token');
+  const flagModel = getFlag(args, '--model');
+
+  if (flagUrl || flagToken || flagModel) {
+    // 非交互模式：通过命令行参数直接设置
+    const updates = {};
+    if (flagUrl) updates.ANTHROPIC_BASE_URL = flagUrl;
+    if (flagToken) updates.ANTHROPIC_AUTH_TOKEN = flagToken;
+    if (flagModel) updates.ANTHROPIC_MODEL = flagModel;
+
+    // 如果 .env 不存在，先从模板复制
+    if (!fs.existsSync(envPath)) {
+      const src = path.join(PKG_ROOT, '.env.example');
+      if (fs.existsSync(src)) fs.copyFileSync(src, envPath);
+    }
+    writeEnv(envPath, updates);
+    console.log('✅ Configuration saved to .env');
+    for (const [k, v] of Object.entries(updates)) {
+      const display = k.includes('TOKEN') ? v.slice(0, 8) + '...' : v;
+      console.log(`   ${k}=${display}`);
+    }
+    process.exit(0);
+  }
+
+  // 交互模式
+  console.log('\n🔧 SuperAgent Configuration\n');
+  const currentEnv = readEnv(envPath);
+
+  const url = await ask(
+    '  API Gateway URL (ANTHROPIC_BASE_URL)',
+    currentEnv.ANTHROPIC_BASE_URL || 'https://api.anthropic.com'
+  );
+  const token = await ask(
+    '  API Token (ANTHROPIC_AUTH_TOKEN)',
+    currentEnv.ANTHROPIC_AUTH_TOKEN || ''
+  );
+  const model = await ask(
+    '  Model name (ANTHROPIC_MODEL, press Enter to skip)',
+    currentEnv.ANTHROPIC_MODEL || ''
+  );
+  const portInput = await ask(
+    '  Server port (PORT)',
+    currentEnv.PORT || '3000'
+  );
+
+  if (!url || !token) {
+    console.error('\n❌ URL and Token are required.');
+    process.exit(1);
+  }
+
+  const updates = {
+    ANTHROPIC_BASE_URL: url,
+    ANTHROPIC_AUTH_TOKEN: token,
+  };
+  if (model) updates.ANTHROPIC_MODEL = model;
+  if (portInput && portInput !== '3000') updates.PORT = portInput;
+
+  // 如果 .env 不存在，先从模板复制
+  if (!fs.existsSync(envPath)) {
+    const src = path.join(PKG_ROOT, '.env.example');
+    if (fs.existsSync(src)) fs.copyFileSync(src, envPath);
+  }
+  writeEnv(envPath, updates);
+
+  console.log('\n✅ Configuration saved to .env');
+  console.log(`   ANTHROPIC_BASE_URL=${url}`);
+  console.log(`   ANTHROPIC_AUTH_TOKEN=${token.slice(0, 8)}...`);
+  if (model) console.log(`   ANTHROPIC_MODEL=${model}`);
+  console.log('\n  Run "superagent" to start the server.\n');
+  process.exit(0);
+}
+
+// ─── init 子命令 ───
+if (args[0] === 'init') {
+  const cwd = process.cwd();
+  const files = [
+    { name: '.env', source: '.env.example' },
+    { name: 'agent-config.json', source: 'agent-config.json' },
+    { name: 'agent-persona.md', source: 'agent-persona.md' },
+  ];
+
+  console.log('🚀 Initializing SuperAgent config files...\n');
+
+  for (const { name, source } of files) {
+    const dest = path.join(cwd, name);
+    if (fs.existsSync(dest)) {
+      console.log(`  ⏭  ${name} (already exists, skipped)`);
+    } else {
+      const src = path.join(PKG_ROOT, source);
+      fs.copyFileSync(src, dest);
+      console.log(`  ✅ ${name} (created)`);
+    }
+  }
+
+  console.log(`
+Done! Next steps:
+  1. Run "superagent config" to set up API credentials
+  2. (Optional) Edit agent-config.json to customize agent name
+  3. (Optional) Edit agent-persona.md to customize personality
+  4. Run: superagent
+`);
+  process.exit(0);
+}
+
+// ─── 解析 --port ───
+let port = process.env.PORT || '3000';
+const portIdx = args.indexOf('--port') !== -1 ? args.indexOf('--port') : args.indexOf('-p');
+if (portIdx !== -1 && args[portIdx + 1]) {
+  port = args[portIdx + 1];
+}
+
+// ─── 查找 .env 文件 ───
+const envFile = path.resolve(process.cwd(), '.env');
+const envArgs = fs.existsSync(envFile) ? ['--env-file', envFile] : [];
+
+if (!fs.existsSync(envFile)) {
+  // 检查环境变量是否已设置
+  if (!process.env.ANTHROPIC_BASE_URL || !process.env.ANTHROPIC_AUTH_TOKEN) {
+    console.error(`
+❌ Missing configuration!
+
+Either create a .env file or set environment variables:
+  ANTHROPIC_BASE_URL=<your-api-url>
+  ANTHROPIC_AUTH_TOKEN=<your-token>
+
+Run 'superagent init' to create config files.
+`);
+    process.exit(1);
+  }
+}
+
+// ─── 启动服务 ───
+const serverPath = path.join(PKG_ROOT, 'src', 'server.js');
+
+const child = spawn(process.execPath, [...envArgs, serverPath], {
+  cwd: process.cwd(),
+  stdio: 'inherit',
+  env: { ...process.env, PORT: port },
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0);
+});
+
+// 转发信号
+for (const sig of ['SIGINT', 'SIGTERM']) {
+  process.on(sig, () => child.kill(sig));
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "superagent-ai-agent",
+  "version": "0.1.0",
+  "description": "A local AI Agent powered by Claude SDK with Plan-Execute-Reflect architecture. Zero-build, browser-ready.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "superagent": "bin/superagent.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "agent-config.json",
+    "agent-persona.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "node --env-file=.env src/server.js",
+    "postinstall": "node bin/postinstall.js"
+  },
+  "keywords": [
+    "ai-agent",
+    "claude",
+    "local-agent",
+    "plan-execute-reflect",
+    "ai-assistant",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/nodermachine/superagent.git"
+  },
+  "homepage": "https://github.com/nodermachine/superagent",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.159",
+    "express": "^4.19.2",
+    "marked": "^18.0.4",
+    "playwright": "^1.60.0"
+  }
+}

package/src/agent.js

@@ -0,0 +1,114 @@
+/**
+ * src/agent.js — Plan-Execute-Reflect 编排器
+ *
+ * 对外唯一接口：runAgent({ prompt, sessionId, images, abortController })
+ *
+ * 三段式管线：
+ *   1. Planner — 规划（只读探查 + 输出结构化 plan）
+ *   2. Executor — 逐步执行（每步独立 session，防上下文雪崩）
+ *   3. Reflector — 失败反思（诊断 + 修复 + 验证，仅一次机会）
+ *
+ * 快捷路径：
+ *   - LUNA_PLAN=0 → 关闭 plan，退化为单次 query
+ *   - 简单请求（短 prompt + 匹配 SIMPLE_RE）→ 跳过 Planner 直接执行
+ */
+
+import {
+  MODEL_TEXT, EXECUTOR_TOOLS, PLANNER_TOOLS,
+  PLANNER_ROLE, REFLECTOR_ROLE,
+  PLAN_ENABLED, SIMPLE_RE,
+} from './config.js';
+import { withFallback, phaseModel, parsePlan } from './query.js';
+
+export function runAgent({ prompt, sessionId, images = [], abortController }) {
+  // ─── 退化路径：关闭 plan，走原单次行为 ───
+  if (!PLAN_ENABLED) {
+    return (async function* () {
+      yield* withFallback({
+        prompt, images, model: phaseModel(images),
+        sessionId, abortController, tools: EXECUTOR_TOOLS, roleAppend: '',
+      });
+    })();
+  }
+
+  // ─── 主管线 ───
+  return (async function* () {
+    let currentSessionId = sessionId ?? null;
+
+    // ─── 快捷路径：简单请求跳过 Planner ───
+    const isSimple = !images.length && prompt.length < 60 && SIMPLE_RE.test(prompt.trim());
+    if (isSimple) {
+      yield* withFallback({
+        prompt, images, model: MODEL_TEXT,
+        sessionId: currentSessionId, abortController, tools: EXECUTOR_TOOLS, roleAppend: '',
+      });
+      return;
+    }
+
+    // ─── Phase 1: Planner ───
+    const plannerState = yield* withFallback({
+      prompt, images, model: phaseModel(images),
+      sessionId: currentSessionId, abortController,
+      tools: PLANNER_TOOLS, roleAppend: PLANNER_ROLE,
+    });
+    const planText = plannerState.text;
+    currentSessionId = plannerState.sessionId ?? currentSessionId;
+
+    // 解析 plan JSON
+    const plan = parsePlan(planText);
+    const steps = Array.isArray(plan?.steps)
+      ? plan.steps
+          .filter((s) => s && s.goal)
+          .map((s, i) => ({ id: s.id ?? i + 1, goal: String(s.goal), verifyHint: s.verifyHint ? String(s.verifyHint) : '' }))
+      : [];
+    const effectivePlan = plan?.needPlan === true && steps.length > 0;
+
+    // 通知前端 plan 结果
+    yield { type: 'plan', needPlan: effectivePlan, steps, reason: plan?.reason ?? '' };
+
+    // ─── Phase 2a: 无需 plan，单次直接回答 ───
+    if (!effectivePlan) {
+      yield* withFallback({
+        prompt, images, model: phaseModel(images),
+        sessionId: currentSessionId, abortController, tools: EXECUTOR_TOOLS, roleAppend: '',
+      });
+      return;
+    }
+
+    // ─── Phase 2b: 逐步执行（独立 session 防上下文雪崩） ───
+    const total = steps.length;
+    const planSummary = steps.map((s) => `${s.id}. ${s.goal}`).join('\n');
+
+    for (let i = 0; i < total; i++) {
+      const step = steps[i];
+      const stepPrompt = `【执行计划】(${i + 1}/${total})\n${planSummary}\n\n` +
+        `当前执行第 ${step.id} 步:\n目标: ${step.goal}\n` +
+        (step.verifyHint ? `验证: ${step.verifyHint}\n` : '') +
+        `\n只执行这一步。若已在前面顺带完成,直接说明已完成即可。完成后用一句话总结结果。`;
+
+      // 每步独立 session + 固定 TEXT 模型
+      const exState = yield* withFallback({
+        prompt: stepPrompt, images: [], model: MODEL_TEXT,
+        sessionId: null, abortController, tools: EXECUTOR_TOOLS, roleAppend: '',
+      });
+
+      // ─── Phase 3: Reflector（该步失败时触发，最多 1 次） ───
+      if (exState.failures.length > 0) {
+        const failureText = exState.failures.join('\n---\n').slice(0, 4000);
+        yield { type: 'reflection', phase: 'start', step: step.id, goal: step.goal, failure: failureText };
+
+        const refPrompt = `执行计划第 ${step.id} 步「${step.goal}」时出现失败:\n\n${failureText}\n\n` +
+          `诊断根因并修复。` +
+          (step.verifyHint ? `修完后必须执行验证: ${step.verifyHint}，确认通过再结束。` : '') +
+          `这是唯一一次反思机会,修完说明修了什么。`;
+
+        // Reflector 使用 executor 的 sessionId（看到失败的工具调用上下文）
+        yield* withFallback({
+          prompt: refPrompt, images: [], model: MODEL_TEXT,
+          sessionId: exState.sessionId, abortController, tools: EXECUTOR_TOOLS, roleAppend: REFLECTOR_ROLE,
+        });
+        yield { type: 'reflection', phase: 'end', step: step.id };
+      }
+    }
+  })();
+}

package/src/config.js

@@ -0,0 +1,103 @@
+/**
+ * src/config.js — Luna Agent 配置中心
+ *
+ * 所有可调参数、工具列表、角色提示词模板集中在这里。
+ * 修改模型名称、增减工具、调整 prompt 只需改这一个文件。
+ */
+
+import path from 'node:path';
+
+// ═══════════════════════════════════════════════
+// 模型配置
+// ═══════════════════════════════════════════════
+
+/** 纯文本对话使用的主模型 */
+export const MODEL_TEXT = process.env.ANTHROPIC_MODEL ?? 'glm-5.2';
+
+/** 多模态（带图片）请求使用的模型 */
+export const MODEL_VISION = process.env.ANTHROPIC_MODEL_VISION ?? MODEL_TEXT;
+
+/** 主模型命中内容审查时自动切换的兜底模型 */
+export const MODEL_FALLBACK = process.env.ANTHROPIC_MODEL_FALLBACK ?? 'qwen3.7-plus';
+
+// ═══════════════════════════════════════════════
+// 工具列表
+// ═══════════════════════════════════════════════
+
+/** Executor 拥有的全量工具（读写 + shell + web） */
+export const EXECUTOR_TOOLS = [
+  'Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep',
+  'mcp__web__WebSearch', 'mcp__web__WebFetch',
+];
+
+/** Planner 拥有的工具（与 Executor 相同，但通过 prompt 约束其只做规划） */
+export const PLANNER_TOOLS = [
+  'Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep',
+  'mcp__web__WebSearch', 'mcp__web__WebFetch',
+];
+
+// ═══════════════════════════════════════════════
+// 开关 & 正则
+// ═══════════════════════════════════════════════
+
+/** Plan-Execute 总开关：LUNA_PLAN=0 退化为原单次 query 行为（应急逃生口） */
+export const PLAN_ENABLED = process.env.LUNA_PLAN !== '0';
+
+/** 命中内容安全审查的特征正则（智谱网关会把上游 data_inspection_failed 包成 InvalidParameter） */
+export const INSPECTION_RE = /data_inspection_failed|Input text data may contain inappropriate content/i;
+
+/** 简单请求判定：命中则跳过 Planner 直接执行，减少延迟 */
+export const SIMPLE_RE = /^(你好|hi|hello|hey|谢谢|thanks|帮我|能不能|什么|是什么|怎么).{0,30}$/i;
+
+// ═══════════════════════════════════════════════
+// 路径
+// ═══════════════════════════════════════════════
+
+/** 人设文件路径（每次 query 重新读取，改完即生效） */
+export const PERSONA_PATH = path.resolve(process.cwd(), 'agent-persona.md');
+
+/** 项目级 skills 目录 */
+export const PROJECT_SKILLS_DIR = path.resolve(process.cwd(), '.claude', 'skills');
+
+// ═══════════════════════════════════════════════
+// 角色提示词模板（append 到主 persona 之后）
+// ═══════════════════════════════════════════════
+
+/** Planner 角色约束 — 让模型只输出结构化计划，不执行 */
+export const PLANNER_ROLE = `
+
+---
+## 当前阶段:Planner(规划者)
+
+你现在是 **Planner**,负责把主人的请求拆成可执行计划。**你没有写文件 / 跑命令的权限**,严禁执行任何修改性操作,只能用只读工具探查现状。
+
+先按需 Read/Grep/Glob 了解现状,然后输出**唯一一个**计划块,格式严格如下(\`\`\`plan 包裹):
+
+\`\`\`plan
+{
+  "needPlan": <true|false>,
+  "reason": "<一句话:为什么需要/不需要拆步>",
+  "steps": [
+    {"id": 1, "goal": "<这步达成什么>", "verifyHint": "<如何验证成功,如:跑 xxx 测试 / 检查文件存在 / 编译通过>"}
+  ]
+}
+\`\`\`
+
+判定:
+- 简单问答、纯解释、单步即可完成 → \`needPlan: false\`,steps 留空
+- 多步、有依赖、涉及多文件 / 多次工具调用 → \`needPlan: true\`,steps 写清每步目标和验证方式
+
+输出计划后**立即停止**,不执行步骤,不额外寒暄。`;
+
+/** Reflector 角色约束 — 诊断失败并修复，只有一次机会 */
+export const REFLECTOR_ROLE = `
+
+---
+## 当前阶段:Reflector(反思者)
+
+你现在是 **Reflector**。执行器在某个子任务上失败了,你的职责:
+1. 诊断根因(看 tool_result 的错误)
+2. **优先用客观验证**(跑测试 / 编译 / lint)判断,别凭主观
+3. 给出具体修复并执行
+
+这是**唯一一次**反思机会,修完说明修了什么,不要无限重试。`;