micro-agent

一个微小而完备、可以方便嵌入到任何地方帮您干活的 AI Agent。

特性

• 统一会话 API — createSession 推荐入口，一行代码创建 / 多轮对话 / 流式输出 / 自动释放
• 中间件管道 — Express/Koa 风格洋葱模型，7 个预置中间件（日志/限流/超时/重试/转换/条件）
• 虚拟终端架构 — 基于 CliCommand 的可扩展命令系统，Agent 通过 bash 工具调用命令
• 50+ 内置命令 — 文件操作、文本处理、数据处理、网络请求、Shell 执行，支持管道组合
• Skill 系统 — 可扩展的技能配置，每个 Skill 包含命令集 + 系统提示词 + 摘要生成器
• 上下文管理 — 智能压缩长对话历史，命令感知截断策略，自动清理冗余工具结果
• 流式输出 — 完整的 AsyncIterable 流式事件系统（text / thinking / tool_call / tool_result / phase）
• 序列化/反序列化 — 会话状态可 JSON 持久化，支持断点恢复和多实例同步
• 自动恢复执行 — executeWithRecovery 内置指数退避重试，自动识别限流/网络/超时错误
• RPC 远程执行 — 跨设备命令注册与 HTTP 调用，Agent 和 Bash 可运行在不同机器上
• SubAgent 并行 — 主 Agent 可启动独立子 Agent 处理任务，节省上下文不被污染
• 异步任务调度 — 后台任务管理，FIFO 队列 + 并发控制 + 自动淘汰
• 双端运行 — 浏览器和 Node.js 同一套代码
• 零依赖核心 — Agent 核心不依赖任何框架，可直接嵌入任意 JS 环境

快速开始

浏览器（Web Component）

<!-- 最简用法 — 一行代码嵌入 AI 对话 -->
<micro-agent api-key="sk-xxx"></micro-agent>

<!-- 完整配置 -->
<micro-agent
  api-key="sk-xxx"
  model="gpt-4o"
  theme="dark"
  placeholder="输入问题..."
  height="500px"
></micro-agent>

<!-- 自定义 slot 插槽 -->
<micro-agent api-key="sk-xxx">
  <div slot="header">智能助手</div>
  <div slot="footer">Powered by micro-agent</div>
</micro-agent>

<!-- 只读模式 -->
<micro-agent api-key="sk-xxx" disabled></micro-agent>

<script type="module">
  import 'micro-agent/web-component';
  const el = document.querySelector('micro-agent');

  // JS API — 发送消息并获取回复
  const reply = await el.ask('你好');

  // JS API — 监听事件
  el.addEventListener('message', (e) => {
    console.log(e.detail.type, e.detail.content);
  });

  // JS API — 批量配置
  el.configure({ apiKey: 'sk-xxx', theme: 'dark', height: '600px' });
</script>

Web Component 属性：

| 属性 | 说明 | 默认值 | |------|------|--------| | api-key | API 密钥 | — | | base-url | API 地址 | OpenAI | | model | 模型名称 | gpt-4o | | theme | 主题 (light/dark/auto) | auto | | placeholder | 输入框占位符 | 输入消息... | | height | 组件高度 | 400px | | system-prompt | 自定义系统提示词 | — | | disabled | 禁用交互（只读） | — | | auto-focus | 自动聚焦输入框 | 开启 | | stream-mode | 流式输出模式 | — |

Slot 插槽：

| 名称 | 位置 | 用途 | |------|------|------| | header | 顶部 | 自定义标题栏 | | empty | 消息区空状态 | 自定义空状态提示 | | status-extra | 状态栏右侧 | 额外状态信息 | | input-prefix | 输入框左侧 | 前置按钮/图标 | | input-suffix | 输入框右侧 | 后置按钮/图标 | | footer | 底部 | 页脚内容 |

Node.js CLI

# 单条消息
OPENAI_API_KEY=sk-xxx pnpm cli "1+1等于几"

# 交互式对话
OPENAI_API_KEY=sk-xxx pnpm cli

# JSON 结构化输出
OPENAI_API_KEY=sk-xxx pnpm cli --json "你好"

# 自定义提示词 + 温度
SYSTEM_PROMPT="你只用法语回复" TEMPERATURE=1.2 pnpm cli "自我介绍"

# 指定工作目录 + 限制可执行的系统命令
OPENAI_API_KEY=sk-xxx pnpm cli --work-dir /path/to/project --allowed-exec "git,node,cat"

一行启动（quickStart）

最简嵌入式用法 — 自动管理 Agent 生命周期：

import { quickStart } from 'micro-agent/quick-start';

// 最简用法（自动读取 OPENAI_API_KEY）
const reply = await quickStart('1+1=?');
console.log(reply); // 2

// 带自定义配置
const reply = await quickStart('分析这个项目', {
  model: 'gpt-4o-mini',
  workDir: './my-project',
  onProgress: (e) => {
    if (e.type === 'text') process.stdout.write(e.content);
  },
});

Builder 链式 API

流式配置接口，支持预设和链式调用：

import { AgentBuilder } from 'micro-agent/builder';

// 使用预设一键创建
const agent = AgentBuilder.preset('coder')
  .apiKey('sk-xxx')
  .workDir('./my-project')
  .build();

// 完全自定义链式配置
const agent = AgentBuilder.create()
  .apiKey('sk-xxx')
  .baseUrl('https://api.example.com/v1')
  .model('gpt-4o')
  .temperature(0.7)
  .maxRounds(20)
  .systemPrompt('你是专业助手')
  .onEvent((e) => { if (e.type === 'text') console.log(e.content) })
  .build();

// 一行问答（自动管理生命周期）
const reply = await AgentBuilder.ask('你好', { apiKey: 'sk-xxx' });

内置预设：

| 预设 | 模型 | 温度 | 适用场景 | |------|------|------|----------| | coder | gpt-4o | 0.1 | 编程助手（文件操作工作流） | | chatbot | gpt-4o-mini | 0.7 | 友好对话 | | analyst | gpt-4o | 0.3 | 数据分析（启用深度思考） | | translator | gpt-4o-mini | 0.3 | 专业翻译 | | writer | gpt-4o | 0.8 | 写作助手 | | tutor | gpt-4o | 0.4 | 学习导师（启用深度思考） |

纯对话模式（零配置，无需终端）

最轻量嵌入方式——只需 API Key，自动使用 NoopTerminal（无文件系统访问）：

import { createSession } from 'micro-agent';

// 一行问答（自动创建 + 自动释放）
const reply = await createSession({ apiKey: 'sk-xxx' }).ask('1+1=?');
console.log(reply); // 2

// 翻译服务
const translator = createSession({
  apiKey: 'sk-xxx',
  model: 'gpt-4o-mini',
  systemPrompt: '你是一个专业翻译。只返回翻译结果，不要解释。',
});
const result = await translator.ask('Translate "Hello World" to Chinese');
console.log(result); // 你好世界
translator.dispose();

// 文本分类/情感分析
const classifier = createSession({ apiKey: 'sk-xxx' });
const sentiment = await classifier.ask('这段话的情感是正面还是负面：太棒了！');
classifier.dispose();

纯对话模式的特性：

• 无需 terminal 参数（自动注入 NoopTerminal）
• 无需 workDir / allowedExec（不执行任何命令）
• 完整的多轮对话、流式输出、中间件管道、序列化全部可用
• 内存占用最小化（无虚拟 bash 引擎开销）

嵌入式 API（createSession — 推荐入口）

createSession 是推荐的嵌入式入口，统一了生命周期管理和多模式访问：

import { createSession } from 'micro-agent';

// 单次问答（最简，自动管理生命周期）
const reply = await createSession({ apiKey: 'sk-xxx' }).ask('你好');
console.log(reply);

// 多轮对话（上下文保持）
const chat = createSession({ apiKey: 'sk-xxx' });
await chat.ask('我叫小明');
await chat.ask('我叫什么？'); // 记住上下文
chat.dispose(); // 用完释放

// 流式输出
const session = createSession({ apiKey: 'sk-xxx' });
for await (const event of session.chat('写一首诗')) {
  if (event.type === 'text') process.stdout.write(event.content);
}
session.dispose();

// 完整结果（含思考过程和统计）
const { text, thinking, stats, toolCalls, durationMs } =
  await session.sendFull('解释量子计算');
session.dispose();

// 序列化 / 反序列化（断点恢复）
const snapshot = session.serialize();
fs.writeFileSync('session.json', JSON.stringify(snapshot));
// ... 后续请求恢复 ...
const raw = JSON.parse(fs.readFileSync('session.json', 'utf-8'));
const restored = AgentSession.deserialize(raw, { llm: myLLM });
await restored.ask('继续之前的话题');

SessionOptions 配置项：

| 选项 | 类型 | 说明 | |------|------|------| | apiKey | string | API Key（不传则读 OPENAI_API_KEY 环境变量） | | model | string | 模型名称 | | baseUrl | string | API 基础地址 | | llm | LLMCaller | 自定义 LLM 调用函数（传入后忽略 apiKey/model/baseUrl） | | maxRounds | number | 最大循环轮数 | | systemPrompt | string | 自定义系统提示词 | | temperature | number | LLM 温度 [0, 2] | | terminal | ITerminalInstance | 终端实例（不传自动使用 NoopTerminal） | | skills | SkillConfig[] | 自定义技能 | | memoryStore | MemoryStore | 记忆存储 | | contextTransform | (msgs) => msgs | 上下文转换钩子 |

核心方法：

| 方法 | 说明 | |------|------| | session.ask(msg) | 简单问答，返回文本 | | session.run(msg) | 完整执行，返回 RunResult（含 thinking/stats/toolCalls） | | session.chat(msg) | 流式对话，返回 AsyncIterable<ChatEvent> | | session.streamText(msg) | 纯文本流式输出（自动拼接 text 事件） | | session.streamEvents(msg) | 分类收集流式事件（按 text/thinking/toolCalls/errors 分组） | | session.chatSingle(msg) | 单轮无状态对话（不影响多轮上下文） | | session.batch(tasks) | 批量并行执行多个独立任务 | | session.serialize() | 序列化会话状态（可 JSON 持久化） | | AgentSession.deserialize(data, opts) | 从快照恢复会话（静态方法） | | session.reset() | 重置会话（清空上下文） | | session.dispose() | 释放资源（多次调用安全） |

中间件管道

Session 支持类似 Express/Koa 的中间件模式，可在请求处理链中注入自定义逻辑：

import { createSession, loggingMiddleware, rateLimitMiddleware } from 'micro-agent';

const session = createSession({ apiKey: 'sk-xxx' })
  // 日志中间件：记录每次请求和响应
  .use(loggingMiddleware({ prefix: '[MY-APP]' }))
  // 限流中间件：每分钟最多 10 次
  .use(rateLimitMiddleware({ maxRequests: 10, windowMs: 60_000 }))
  // 自定义中间件：修改消息或转换输出
  .use(async (ctx, next) => {
    console.log('before:', ctx.message);
    const result = await next();
    console.log('after:', result.text);
    return { ...result, text: result.text.toUpperCase() };
  });

const reply = await session.ask('hello'); // 经过所有中间件处理
session.dispose();

内置中间件：

| 中间件 | 说明 | |--------|------| | loggingMiddleware | 记录请求/响应日志 | | rateLimitMiddleware | 滑动窗口限流 | | timeoutMiddleware | 单次请求超时控制 | | retryMiddleware | 自动重试失败请求 | | transformMiddleware | 输入消息转换 | | conditionalMiddleware | 条件执行目标中间件 | | compose(mws) | 组合多个中间件为一个 |

嵌入式 API（createMicroAgent）

底层工厂函数，需要完全自定义时使用：

import { createMicroAgent } from 'micro-agent';

const agent = createMicroAgent({
  apiKey: 'sk-...',
  model: 'gpt-4o',
});

for await (const event of agent.chat('今天天气怎么样')) {
  if (event.type === 'text') process.stdout.write(event.content);
}

const answer = await agent.ask('1+1等于几？');

agent.reset();
agent.destroy();

HTTP Server

零依赖 HTTP 服务端，提供 SSE 流式和 REST API：

import { createAgentServer } from 'micro-agent/server';

const server = createAgentServer({
  port: 3000,
  apiKey: 'sk-xxx',
  model: 'gpt-4o',
});

// POST /chat — 发送消息（SSE 流式响应）
// POST /ask  — 简单问答（JSON 响应）
// GET  /status — 获取状态
// POST /reset — 重置会话
// GET  /messages — 获取历史消息

核心 API

createMicroAgent(config)

一站式创建 Agent（推荐），自动创建 LLM 适配器和默认技能。

const agent = createMicroAgent({
  apiKey: 'sk-...',          // API Key（必须）
  baseUrl: '...',            // API 地址（默认 OpenAI）
  model: 'gpt-4o',           // 模型名称
  workDir: '/path/to/dir',   // 工作目录（Node.js 环境下文件操作的基础路径）
  allowedExec: 'git,ls,cat', // exec 命令白名单（逗号分隔，为空则允许全部）
  systemPrompt: '...',       // 追加到默认系统提示词之后
  temperature: 0.7,          // LLM 温度
  maxTokens: 4096,           // 最大输出 token
  maxRounds: 80,             // 最大循环轮数
  extraCommands: [...],      // 额外的自定义命令
  rpcCommands: [...],        // RPC 远程命令
});

createAgent(config)

高级用法，需要自定义 LLM 适配器时使用。

import { createAgent, createOpenAILLMCaller, createDefaultSkill } from 'micro-agent';

const agent = createAgent({
  llm: createOpenAILLMCaller({ apiKey, baseUrl, model }),
  skills: [createDefaultSkill()],
  systemPrompt: '...',
  initialEnv: { WORK_DIR: '/path' },  // 注入虚拟环境变量
});

返回值方法：

| 方法 | 说明 | |------|------| | agent.chat(msg) | 流式对话，返回 AsyncIterable<ChatEvent> | | agent.ask(msg) | 简单问答，返回完整文本（自动处理工具调用） | | agent.stop() | 停止当前运行 | | agent.pause() / agent.resume() | 暂停 / 恢复 | | agent.reset() | 重置会话（清空上下文） | | agent.sendUserMessage(msg) | 向运行中的 Agent 发送插话 | | agent.getStats() | 获取会话统计 | | agent.getMessages() | 获取上下文消息 | | agent.exportMarkdown() | 导出对话为 Markdown |

ChatEvent 类型：

type ChatEvent =
  | { type: 'text'; content: string }
  | { type: 'thinking'; content: string }
  | { type: 'tool_call'; name: string; args: string }
  | { type: 'tool_result'; name: string; result: string; success: boolean; duration?: number }
  | { type: 'status'; status: 'idle' | 'running' | 'paused' | 'done' | 'error' }
  | { type: 'usage'; usage: LLMUsage }
  | { type: 'log'; entry: LogEntry }
  | { type: 'done' };

自定义 Skill

const mySkill = {
  name: 'database',
  description: '数据库操作技能',
  commands: [
    {
      name: 'query',
      help: '查询数据库\n用法: query <SQL>',
      exec: (args) => db.execute(args.join(' ')),
    },
  ],
  systemPrompt: '你是一个数据库助手，使用 query 命令执行 SQL 查询。',
  buildSummary: ({ toolCount, successCount }) =>
    `已执行 ${toolCount} 次查询（成功 ${successCount}）`,
  initialMessage: '我可以用 query 命令帮你查询数据库。',
};

const agent = createAgent({
  llm: createOpenAILLMCaller({ apiKey: 'sk-...' }),
  skills: [mySkill],
});

内置命令

核心

| 命令 | 说明 | 示例 | |------|------|------| | eval | 执行 JavaScript（支持 async/await） | eval await fetch('url').then(r=>r.json()) | | fetch | HTTP 请求（支持 GET/POST/PUT） | fetch https://api.github.com/repos/vuejs/core | | calc | 数学计算 | calc Math.sin(Math.PI / 2) | | json | JSON 格式化 | json {"a":1} | | jq | JSON 路径提取 | jq .name data.json | | time | 获取当前时间 | time | | help | 查看所有可用命令 | help 或 help grep |

系统（仅 Node.js）

| 命令 | 说明 | 示例 | |------|------|------| | exec | 执行系统 shell 命令 | exec git status | | read | 读取文件内容 | read ./package.json | | write | 写入文件 | write ./out.txt "Hello" | | ls | 列出目录 | ls src/ | | glob | 文件模式匹配 | glob "**/*.ts" |

文本处理

grep sed awk sort head tail wc tr cut uniq nl reverse trim replace split join map xargs yes

数据转换

base64 urlencode urldecode md5 sha len seq sum

支持管道 | 和链式 && / || 组合：eval JSON.stringify({a:1}) | cat

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | OPENAI_API_KEY | API 密钥 | — | | OPENAI_BASE_URL | API 地址 | https://api.openai.com/v1 | | OPENAI_MODEL | 默认模型 | gpt-4o | | SYSTEM_PROMPT | 自定义系统提示词 | — | | TEMPERATURE | LLM 温度参数 | 0.7 |

架构

src/agent/
├── session.ts             # 统一会话管理 API（createSession 推荐入口）
├── agent-session.ts       # 请求驱动型 Agent 会话核心引擎
├── agent-api.ts           # 嵌入式 API 工厂（createAgent / createMicroAgent）
├── agent-loop.ts          # Agent 循环引擎（callLLMWithRetry + executeToolCall）
├── agent-state.ts         # AgentPhase 状态机 + 命令循环检测
├── async-utils.ts         # 异步工具（withTimeout / jitterBackoff / isRetryableError）
├── tool-definition.ts     # 工具定义构建 + 内置命令工厂
├── system-prompt.ts       # System Prompt 模块化构建器
├── context-builder.ts     # 上下文构建统一管理层
├── context-compress.ts    # 上下文压缩子系统
├── llm-adapters.ts        # LLM 适配器（OpenAI 兼容 SSE 流式）
├── micro-agent.ts         # 一站式入口（createMicroAgent）
├── quick-start.ts         # 快速启动（quickStart / quickChat）
├── builder.ts             # Builder 链式配置 API
├── middlewares.ts         # 预置中间件工厂（7 个）
├── virtual-bash.ts        # 虚拟终端引擎（词法/语法/执行/管道）
├── rpc-server.ts          # RPC HTTP 服务端（跨设备命令执行）
├── task-scheduler.ts      # 异步任务调度器
├── event-manager.ts       # 事件管理器（on/off/once + 延迟注册）
├── errors.ts              # 统一错误处理（AgentError 工厂函数）
├── types.ts               # 公开类型定义（ChatEvent / RunResult / AgentStats）
├── config-validation.ts   # 配置验证
├── server.ts              # Node.js HTTP 服务端嵌入
├── web-component.ts       # <micro-agent> 自定义元素
├── agent-core.ts          # 核心接口 + CliCommand 类型
├── terminal-types.ts      # ITerminalView 接口（解除 Vue 隐式依赖）
├── file-tracker.ts        # 文件变更追踪
├── memory.ts              # 记忆系统（TTL + 重要性评分）
├── context-debug.ts       # 上下文 Debug 能力
├── exec-result-store.ts   # 执行结果存储与查询
├── multimodal.ts          # 多模态支持（图片/文件）
├── subagent.ts            # SubAgent 并行能力
├── cli/                   # CLI 实现
│   ├── index.ts           # CLI 入口 + REPL 循环
│   └── slash-commands/    # 斜杠命令（4 组 → 27 个功能子模块）
│       ├── code/           # 代码操作（git-core/git-ops/ai-assist/exec/file-ops/search/system/analysis/init）
│       ├── info/           # 信息查看（env-sys/file-dir/info-view/network/data-convert/devtools）
│       ├── session/        # 会话管理（session-mgmt/data-persist/search-history/export-copy/exec-pipe/monitor）
│       ├── conversation/   # 对话控制（conv-control/edit-input/info-view/config/quick）
│       ├── types.ts        # 命令类型定义
│       ├── shared.ts       # ANSI 颜色工具
│       ├── helpers.ts      # chatWithStats 等辅助函数
│       └── index.ts        # 命令注册表聚合入口
└── __tests__/             # 测试套件（1051 用例）

设计理念：

• 依赖倒置 — LLM 通过 LLMCaller 接入注入，不绑定任何 SDK
• 单一工具 — Agent 只有一个 bash 工具，所有命令通过虚拟终端执行
• Skill 扩展 — 新能力通过添加 CliCommand 实现，无需改核心代码
• 中间件管道 — Express/Koa 风格洋葱模型，请求/响应全链路可插拔
• 纯函数优先 — 核心逻辑独立可测试，状态机严格转换验证

开发

pnpm tsc          # 类型检查（vue-tsc）
pnpm test         # 运行测试（1051 用例，vitest）
pnpm dev          # 启动开发服务器
pnpm build        # 构建生产版本
pnpm tse src/xxx  # 执行单个 TypeScript 文件

测试

项目包含 1051+ 个测试用例，覆盖核心模块：

src/agent/__tests__/
├── embedded-e2e.test.ts       # 嵌入式 E2E 集成测试（79 用例）
├── session-wrapper.test.ts    # AgentSession 生命周期测试（31 用例）
├── builder.test.ts            # Builder 链式 API + 预设系统
├── quick-start.test.ts        # quickStart / quickChat
├── llm-adapter.test.ts        # LLM 适配器
├── server.test.ts             # HTTP Server 嵌入测试
├── middlewares.test.ts        # 中间件管道
├── storage.test.ts            # KV 存储系统
├── skills.test.ts             # Skill 技能系统
└── ...                        # 更多测试（35 个文件）