convez.ai
AgenteDesenvolvimento WebAvançado
icyxianyu

Mini Agent - Framework Educacional de Arquitetura de Agentes IA

icyxianyu/mini-agent

Framework educacional para entender arquitetura de agentes com TypeScript

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework TypeScript minimalista para aprender arquitetura de agentes IA, inspirado no Claude Code. Implementa loop de agent com suporte a 13 ferramentas (arquivos, shell, busca, web), delegação de sub-agents, sistema de skills e múltiplos padrões de execução (síncrono, Plan mode, streaming).

Instalação

$npx convez-ai icyxianyu/mini-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
—
Issues abertas
1
Contribuidores
1

Casos de uso

  • Aprender padrões de agent loops e tool calling
  • Prototipar sistemas multi-agent com delegação de tarefas
  • Implementar automação com acesso a arquivos e comandos shell

Veredito

Projeto bem estruturado para fins educacionais com arquitetura clara de 5 camadas e suporte robusto a sub-agents. Recomendado para desenvolvedores que querem entender internals de sistemas agentic, mas requer conhecimento sólido de TypeScript e padrões de IA.

README

A tradução para o português deste README ainda está na fila.

Mini Claude Code

简易版 Claude Code — 一个用于学习 AI Agent 架构 的 TypeScript 项目。

核心能力:对话、文件操作、终端命令、内容搜索、子 Agent 委托、Skill 系统。13 个工具 + 流式输出 + 日志 + 全局 CLI。

📋 开发计划 TODO · 📝 问题记录 RECORD


目录


快速开始

# 1. 安装依赖
pnpm install

# 2. 配置 API Key
cp .env.example .env
# 编辑 .env,填入 LLM_API_KEY

# 3. 启动 REPL
pnpm dev

# 4. 或全局安装为 CLI 命令
pnpm link --global
mini-agent

支持所有兼容 OpenAI API 接口的模型(OpenAI / DeepSeek / 通义千问 等)。


项目结构

agent/
├── src/
│   ├── index.ts              # 入口:REPL 交互循环
│   ├── config.ts             # 配置管理(含 System Prompt)
│   ├── context.ts            # 上下文注入(项目类型检测)
│   ├── logger.ts             # 日志模块
│   ├── llm.ts                # LLM 客户端(流式 + 非流式)
│   ├── core.ts               # ★ Agent 核心循环 + Agent.forked()
│   ├── plan.ts               # Plan 模式(步骤分解 + 并行执行)
│   ├── session.ts            # 会话管理
│   ├── tools/
│   │   ├── base.ts           # 工具基类 + ToolResult
│   │   ├── file-tools.ts     # 8 个文件操作工具
│   │   ├── shell-tools.ts    # Shell 命令 + 危险检测
│   │   ├── search-tools.ts   # ripgrep/纯 JS 搜索
│   │   ├── web-tools.ts      # HTTP GET 抓取
│   │   ├── task-tool.ts      # ★ 子 Agent 委托工具
│   │   ├── skill-tool.ts     # ★ Skill 激活工具
│   │   └── index.ts          # 工具注册表 (13 个工具)
│   ├── agents/
│   │   ├── types.ts          # SubAgentConfig / SubAgentResult
│   │   ├── builtin.ts        # 3 个内置 Agent 定义
│   │   ├── runner.ts         # SubAgentRunner 运行时引擎
│   │   └── index.ts          # 模块导出
│   └── skill/
│       ├── types.ts          # SkillMeta / SkillDefinition
│       ├── loader.ts         # 扫描 + YAML frontmatter 解析
│       ├── manager.ts        # 注册/查询/匹配/注入
│       └── index.ts          # 模块导出
├── bin/
│   └── mini-agent.ts         # 全局 CLI 入口
├── test/
│   ├── prompts.md            # 测试用例
│   └── runner.ts             # 测试运行器
├── .env.example
├── package.json
└── tsconfig.json

架构设计(核心)

五层架构

┌─────────────────────────────────────────────────────────┐
│                   交互层 (index.ts)                      │
│              REPL:读用户输入 → 调用 Agent → 输出回复      │
├─────────────────────────────────────────────────────────┤
│                 Agent 核心循环 (core.ts)                  │
│        维护对话历史,编排 LLM 思考 ↔ 工具执行的循环        │
│        提供 Agent.forked() 创建独立子 Agent               │
├──────────────────────┬──────────────────────────────────┤
│   LLM 客户端 (llm.ts) │       工具层 (tools/)            │
│   流式/非流式 API     │   13 个工具,含 task 子 Agent     │
├──────────────────────┴──────────────────────────────────┤
│                   配置层 (config.ts)                      │
│                     .env → 全局配置                       │
└─────────────────────────────────────────────────────────┘

子 Agent 委托

核心概念 — Tool-as-Agent 模式:

将子 Agent 封装为标准的 Function Calling 工具(task),LLM 通过工具调用自主 spawn 子 Agent:

主 Agent Loop:
  LLM → tool_calls: [{name:"task", args:{subagent_type, prompt}}]
       │
       ▼
  TaskTool.execute()
       │
       ▼
  SubAgentRunner.run(type, prompt)
       │
       ├─ inherit 路径: 共享父 Prompt + 工具池(过滤)
       ├─ independent 路径: 自己的 Prompt + 受限工具集
       │
       ├─ Agent.forked() → 独立 messages + 独立 Loop
       │
       └─ SubAgentResult → 注入主 Agent messages

三条委托路径:

类型委托方式工具用途
general-purpose继承全部(禁递归task)重构、多文件操作
explore继承+过滤只读项目分析、代码搜索
plan独立只读+规划Prompt制定实施计划

并行执行:同一 LLM 轮次中的多个 task 调用自动 Promise.allSettled 并发。

上下文隔离:子 Agent 拥有独立的 messages 历史,不污染主 Agent;不注入过期/重复的上下文。

安全:禁止嵌套 task(防无限递归);子 Agent 内的 sudo/rm -rf 等危险命令自动拦截。

Skill 系统

SKILL.md 格式 — YAML frontmatter + Markdown body:

---
name: 技能名称
description: 触发条件描述,LLM 用于语义匹配
---

# 技能指令正文...

渐进式披露:启动时只加载 name + description 注入 System Prompt(~100 tokens/skill),LLM 匹配后通过 skill 工具激活,完整 body 按需加载。

三种使用方式:

  • /skill list — 查看所有已加载 skill
  • /skill <name> — 手动激活
  • LLM 自动匹配 — 当用户需求命中 skill 的 description 时,LLM 通过 skill 工具自主激活

支持可执行脚本:skill 目录下 scripts/ 放可执行脚本,skill 指令中引用执行。

.mini-agent/skills/<name>/
├── SKILL.md
└── scripts/
    └── setup.sh

可用工具列表

工具分类说明
read_file只读读文件,支持 offset/limit
write_file写入创建/覆盖文件
edit_file写入精确字符串替换
delete_file删除删除文件
copy_file写入复制文件
move_file写入移动/重命名文件
create_directory写入递归创建目录
list_directory只读列出目录内容
search_content只读ripgrep 内容搜索
execute_command执行终端命令
fetch_url只读HTTP GET 获取网页
task委托★ 启动子 Agent
skill委托★ 激活 Skill 获取指令

全局 CLI

# 安装
cd <项目目录> && pnpm link --global

# 使用
mini-agent                        # 启动 REPL(默认 cwd 为工作区)
mini-agent -w /path/to/project    # 指定工作区
mini-agent -m deepseek            # 临时覆盖模型
mini-agent "一句话任务"            # 单次执行后退出
Ver o original no GitHub

Bom para

Relacionados