English | 中文

@easbot/agent

EASBot Agent — 多 Agent 协作生态系统的核心运行时。提供 CLI 入口（easbot）、ACP 协议服务、TUI 交互、会话管理、命令注册、Hook 插件、技能系统、创造 + 进化引擎、MCP 集成、Gateway 通信、代码知识图谱、WikiChat、Scheduler 调度等全栈 Agent 能力。

版本

v0.3.13

模块结构

src/
├── adapter/          # Agent 通信适配器 (EasBotAgent / AdapterBootstrap / connection / event / server / types)
├── agent/            # Agent 核心 + prompt 生成
├── api/              # 业务逻辑 API 层（23 个 namespace：AgentAPI / SessionAPI / ModelAPI / MessageAPI / ToolAPI / ConfigAPI / ProviderAPI / CommandAPI / McpAPI / LspAPI / EventAPI / SkillAPI / AuthAPI / ProjectAPI / PtyAPI / ExperimentalAPI / QuestionAPI / FileAPI / InstanceAPI / PermissionAPI / ContextAPI / SchedulerAPI / types + openapi）
├── auth/             # OAuth / API Key / Well Known 等认证
├── bus/              # 事件总线 (Bus)
├── cli/              # 命令行接口 (commands / program / tui / debug / resources / security / i18n / config / util / bootstrap)
├── command/          # 内置命令系统 (define 注册 / execute / types)；17 个 builtin
├── compaction/       # 会话上下文压缩 (缓存 / 溢出检测 / 修剪)
├── config/           # 配置加载 (gateway loader / EASBOT JSON 主配置)
├── context/          # 上下文构建引擎 (动态 / 静态提示、token 估算、workspace 文件状态缓存)
├── creation/         # 创造 + 进化引擎（Skill 模式：tool-wrapper / generator / reviewer / inversion / pipeline）
├── env/              # 环境变量管理 (Env namespace)
├── file/             # 文件操作 (File namespace: info / nodes / content / protection / watcher)
├── flag/             # EASBOT 功能开关 (EASBOT_DISABLE_*)
├── format/           # 代码格式化器 (Format namespace)
├── gateway/          # 跨会话 Gateway 客户端（HTTP/WebSocket/HTTPS/oauth2/token auth）
├── global/           # 全局配置 (Global namespace: paths / version / init / adapt)
├── hook/             # Hook 插件系统 (HookRegistry / Hook / ExecutorRegistry / Matcher)；11 个 builtin hook
├── i18n/              # 国际化 (zh-CN / en-US)
├── ide/              # IDE 集成 (Ide namespace: detection / installation / events)
├── installation/      # 安装管理 (Installation namespace: version check / update)
├── knowledge/         # 知识库集成 (Memory / Note / Codebase 三个 singleton)
├── lsp/              # 语言服务器协议 (LSP namespace)
├── mcp/              # Model Context Protocol (MCP namespace: auth / oauth-callback / oauth-provider)
├── model/            # 模型管理 (EmbeddingProvider / SummaryProvider / RerankProvider / GraphProvider)
├── patch/            # 代码补丁 (Patch namespace: parse / apply)
├── permission/        # 权限管理 (Permission namespace: request / approve / deny / bash-arity)
├── plugin/           # 插件系统 (define / metadata / load / runtime types)
├── project/          # 项目实例 (Instance: directory / worktree / state / VCS / boot)
├── provider/         # 多模型提供方（Provider namespace：19+ `@ai-sdk/*` 适配 + 自定义 + Copilot SDK + GitLab / OpenRouter / ai-gateway）
├── pty/              # 伪终端 (Pty namespace: creation / management / WebSocket)
├── question/         # 问题交互 (Question namespace: ask user / collect choice or input)
├── scheduler/        # 任务调度 (Scheduler / TaskStorage / TaskStore / Cron 解析)
├── server/           # HTTP / WebSocket 服务器 (路由 / 事件 / mDNS / bonjour)
├── session/          # 会话管理 (Session / Task namespaces)
├── skill/            # 技能系统 (Skill: discovery / skill namespace)
├── snapshot/         # Git 快照管理 (Snapshot namespace)
├── tool/             # 工具系统 (Tool namespace: define / execute / builtins)
├── worktree/         # Git worktree 操作 (Worktree namespace)

CLI 命令

核心命令（21 个，注册自 src/cli/program/command-registry.ts）

| 命令 | 说明 | 子命令 | |--------|-------------|------| | easbot | 启动 TUI 交互模式（默认） | — | | easbot tui | 启动 TUI 交互模式（显式） | — | | easbot run | 运行单次对话（--task "..." / --prompt "..."） | — | | easbot generate | 生成 OpenAPI 规范（从 @easbot/api 类型 + SDK client） | — | | easbot agent | Agent 管理 | list / info <agent-id> / create | | easbot session | 会话管理 | list / info <session-id> / delete <session-id> | | easbot mcp | MCP 服务器管理 | list / info <name> / add / remove <name> | | easbot acp | ACP Agent 通信适配器 | — | | easbot debug | 调试和诊断工具 | 多子命令（agent / config / file / lsp / skill / snapshot / scrap） | | easbot gateway | Gateway 服务管理 | start / stop / restart / status / config show | | easbot weixin | WeChat iLink channel 管理 | login [clear] / user / access pair <code> / access ensure-user / access remove-user / access serve | | easbot auth | Provider 凭据管理 | 多子命令 | | easbot config | 配置管理 | init（走轻量 bootstrap） | | easbot export | 导出会话数据 | — | | easbot import | 导入会话数据 | — | | easbot github | GitHub Agent 管理 | 多子命令 | | easbot pr | PR 检出和会话导入 | — | | easbot stats | Token 使用量和成本统计 | — | | easbot update | 检查并更新 | — | | easbot skills | 技能管理（委派到 @easbot/skills） | add / remove / list / find / update / init / doctor / store {list \| clean \| update \| remove} | | easbot codebase | 代码知识图谱 | init / status / doctor / index / sync / recreate / clear / mcp | | easbot plugins | 插件管理 | list / info <id> / install <source> / enable <id> / disable <id> / uninstall <id> |

全局选项（注册自 parseGlobalOptions）

| 选项 | 说明 | |--------|-------------| | --cwd <path> | 工作目录（覆盖 process.cwd()） | | --config <path> | 自定义配置文件路径 | | --log-level <level> | 日志级别（DEBUG / INFO / WARN / ERROR） | | --print-logs | 打印日志到终端 | | --debug | 开启调试模式 |

运行模式

TUI 交互模式（默认）

easbot           # 从 cwd 启动 TUI
easbot tui       # 显式 TUI

ACP 服务（Agent Client Protocol）

easbot acp

HTTP 服务模式

easbot serve

Gateway 模式

easbot gateway start
easbot gateway stop
easbot gateway restart
easbot gateway status
easbot gateway config show

核心 API 模块

所有 API 通过顶层入口 @easbot/agent 导出，按主题分组。

Context 上下文构建

分层式动态上下文构建（按模型 anthropic / gemini / openai / kimi / qwen 等选不同模板），支持静态 / 动态 3 段式组装 + workspace 文件状态缓存 + Memory/Note 知识库召回。

import {
  ContextEngine, StaticPrompt, DynamicPrompt,
  ContextWindowExhaustedError,
  searchMemory, searchKnowledge,
  FileStateCache, getFileStateCache, resetFileStateCache,
} from '@easbot/agent';

const engine = new ContextEngine(config);
const ctx = await engine.build({
  mode: 'coder',
  userMessage: '帮我重构这个函数',
});

Session 会话管理

Session 命名空间包含会话创建、读取、更新、dispose。Task 子模块提供任务调度封装。自动上下文压缩由 Compaction 模块管理。

Tool / Command 定义

import { Tool, Command, define, CommandRegistry } from '@easbot/agent';

// Tool（注册到 Tool.execute 调度链）
const myTool = Tool.define('hello-tool', {
  parameters: z.object({ message: z.string() }),
  execute: async ({ session, abort }) => {
    return { title: 'Greeting', output: `Hello: ${message}` };
  },
});

// Command（用户通过 `easbot <name>` 触发的内置命令）
define('hello', {
  description: '打印问候',
  execute: async ({ session }) => {
    await session.send('你好！');
  },
});

Hook 系统

import { HookRegistry, Hook, ExecutorRegistry, Matcher } from '@easbot/agent';

const hooks = new HookRegistry();
hooks.register('before:tool-call', async (ctx) => {
  console.log('Tool called:', ctx.name);
});

11 个内置 hook（src/hook/builtin/）：coder / command / compaction / context / creation / gateway / heartbeat / loop / memory / scheduler / task。

File 文件操作

import { File } from '@easbot/agent';

const content = await File.read('/path/to/file');
const info = await File.status('/path/to/file');

Knowledge 知识库集成

import { Memory, Note, Codebase } from '@easbot/agent';

const memory = Memory.instance();
const note = Note.instance();
const codebase = Codebase.instance();

// Memory.search(query) / Note.search(query)
// 底层由 @easbot/memory、@easbot/note、@easbot/codebase 提供

MCP 集成

import { MCP } from '@easbot/agent'; // MCP namespace
// MCP.auth / oauth-callback / oauth-provider / OAuth flows

Gateway 客户端

import { GatewayClient } from '@easbot/agent';
// 跨会话 Gateway 客户端（同步消息、消息戳、跨 agent 转发等）

Provider 多模型提供方

import { Provider } from '@easbot/agent';

const all = await Provider.list();
const lang = await Provider.getLanguage(model);
const embed = await Provider.getEmbedding(providerId, modelId);
const small = await Provider.getSmallModel(providerId);

19+ @ai-sdk/* 适配：OpenAI、Anthropic、Google、Azure、Alibaba、Amazon Bedrock、Cerebras、Cohere、DeepInfra、DeepSeek、Gateway、Google Vertex、Groq、Mistral、OpenAI-Compatible、Perplexity、TogetherAI、Vercel、xAI；外加 OpenRouter、ai-gateway-provider、GitLab、自定义 provider。

Question 问询

import { Question } from '@easbot/agent';
// Question.ask / collectChoice / collectInput — 阻塞式与用户交互

Scheduler 调度

import { Scheduler, TaskStorage as TaskStore, TaskStore } from '@easbot/agent';

const scheduler = new Scheduler(config);
await scheduler.start();
// 任务持久化在 `<cwd>/.easbot/tasks/`
// Cron 解析器在 `src/scheduler/cron-parser.ts` 中，支持 5/6 段 cron 语法

创造 + 进化引擎（Creation）

EASBot 的核心差异化能力 —— 让 Agent 自己发现能力缺口、生成新 Skill、记录经验、自我评估、闭环进化。

模块（src/creation/）

creator.ts          # SkillSpec 生成 + 注册
validator.ts        # 深度校验
memory-bridge.ts    # JSONL 持久化经验
assessor.ts         # 自我评估
evolver.ts          # 进化循环（plan / evolve / compatibility / convergence）
memory.ts           # Memory 工厂
store.ts            # 存储管理
errors.ts           # 错误类型（CreationError）
events.ts           # 事件类型（CreationEvents）
types.ts            # 数据类型（SkillSpec / Experience / SelfAssessment / EvolutionPlan / Composition 等）
creation.ts         # Creation namespace（state factory + 15 个方法）
index.ts            # 顶层导出（Creation + SkillModes + createCreator / createSelfAssessor / createEvolver / createMemory + 4 个 types）
spec/               # 6 类规范定义（bundle / gate / portability / review / skill / workflow）
template/           # Skill 模式模板（modes/*.txt + SKILL.md）

Skill 模式（5 种，SkillModes）

• tool-wrapper — 工具包装
• generator — 生成器
• reviewer — 审查器
• inversion — 反转器（基于记忆进化）
• pipeline — 管道组合

Creation namespace API（15 个方法）

import { Creation, SkillModes, CreationError, CreationEvents,
  createCreator, createSelfAssessor, createEvolver, createMemory } from '@easbot/agent';

// 配置
Creation.configure({ storageDir: '/tmp/easbot/created', memoryDir: '/tmp/easbot/memory' });

// 状态
const state = await Creation.state();
const opts = Creation.getOptions();

// 生命周期
await Creation.init();
const mem = await Creation.memory();
await Creation.dispose();

// 创造
const spec = await Creation.create({
  requirement: '把工厂 API 调整为 HTTP 处理',
  hints: [''],
  scope: 'project',
  forceMode: 'tool-wrapper',  // optional
  sessionId: 'session-123',   // optional
});

// 自我评估 + 进化
const assessment = await Creation.assess({ windowDays: 30 });
const plans = await Creation.evolve({ dryRun: false });
await Creation.applyPlan('plan-id', { approvedBy: 'user' });

// CRUD + 配额
const list = await Creation.list({ mode: 'tool-wrapper', limit: 10 });
const one = await Creation.get('skill-name');
const removed = await Creation.remove('skill-name');
await Creation.refresh();    // 从磁盘重载
const quota = await Creation.quota();

内置命令（17 个）

BUILTIN_COMMANDS 注册自 src/command/builtin/：

| 命令 | 文件 | 说明 | |------|------|------| | init | init.ts | 初始化项目 | | review | review.ts | 代码审查 | | vuln | vuln.ts | 漏洞扫描 | | arch | arch.ts | 显示架构信息 | | btw | btw.ts | 打印"By the way"信息 | | shell | shell.ts | 执行 shell 命令 | | loop | loop.ts | 进入自动循环检测模式 | | cleanup | cleanup.ts | 清理残留数据 | | sync | sync.ts | 同步 skills 到 agent 目录 | | backup | backup.ts | 备份当前状态 | | abort | abort.ts | 停止当前执行 | | compact | compact.ts | 手动触发压缩 | | creation-create | creation-create.ts | 创建 Skill | | creation-evolve | creation-evolve.ts | 进化循环 | | creation-assess | creation-assess.ts | 自我评估 | | creation-apply | creation-apply.ts | 应用进化计划 | | creation-list | creation-list.ts | 列出已创建 Skill |

配置与环境

环境变量

默认在 .env.example：

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
LOG_LEVEL=INFO

项目级配置文件

Agent 在启动时扫描 <cwd>/.easbot/ 下的配置文件（通过 easbot.json 主配置加载）：

• easbot.json — 主配置
• AGENTS.md — Agent 定义
• BOOT.md — 启动配置
• SOUL.md — 价值观 / 灵魂
• IDENTITY.md — 身份定义
• USER.md — 用户定义
• CODER.md — Coder 模式配置

模型供应商

依赖 19+ 个 @ai-sdk/* 厂商 + 第三方 SDK：OpenAI、Anthropic、Google、Azure、Alibaba、Amazon Bedrock、Cerebras、Cohere、DeepInfra、DeepSeek、Gateway、Google Vertex、Groq、Mistral、OpenAI-Compatible、Perplexity、TogetherAI、Vercel、xAI；外加 @openrouter/ai-sdk-provider、ai-gateway-provider、gitlab-ai-provider、GitHub Copilot（@easbot/sdk）。

Skills CLI 委派

easbot skills 通过 Commander.js 委派给 @easbot/skills 包，支持以下子命令：

• add / remove / list / find / update / init — 技能全生命周期
• doctor / dr — 检查 + 清理断链符号链接
• store list / clean / update / remove — store 运维（store / cache / index）

详见 src/cli/commands/skills.ts 的 registerSkillsCommand() 函数。

Adapter 模块

@easbot/agent 暴露 ACP 协议的完整适配器栈：

import { EasBotAgent, AdapterBootstrap, AdapterBootstrapConfig, AdapterEnvironmentInitializationError,
  AgentStatus, ChannelType, EasbotAdapter, ServiceMode, EasBotAgentConfig } from '@easbot/agent';

• EasBotAgent — ACP 协议主类
• AdapterBootstrap — 启动器（加载 + 初始化）
• EasbotAdapter — 适配器实现
• Connection / Event / Server / Types — 底层类型

API 业务逻辑层（23 个 namespace）

@easbot/api 暴露 23 个子 namespace + openapi client：

import {
  AgentAPI, SessionAPI, ModelAPI, MessageAPI, ToolAPI, ConfigAPI,
  ProviderAPI, CommandAPI, McpAPI, LspAPI, EventAPI, SkillAPI,
  AuthAPI, ProjectAPI, PtyAPI, ExperimentalAPI, QuestionAPI,
  FileAPI, InstanceAPI, PermissionAPI, ContextAPI, SchedulerAPI,
  openapi,
} from '@easbot/agent';

Development

# 安装依赖
pnpm install

# 构建（基于 tsup，产出 dist/）
pnpm build

# Dev / watch（tsx）
pnpm dev

# Tests
pnpm test
pnpm test:run
pnpm test:ui
pnpm test:coverage

# Code quality
pnpm lint
pnpm lint:fix
pnpm lint:fix:unsafe
pnpm lint:report
pnpm format
pnpm format:fix

# Type-check
pnpm type-check

# Clean
pnpm clean

# Schema & model snapshot
pnpm generate:schema
pnpm build:snapshot

Publishing

# Linux / macOS
bash scripts/publish.sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File scripts/publish.ps1

License

MIT