MiniAgent AGENTS.md

AGENTS.md — MiniAgent 项目指南

项目定位

MiniAgent 是一个极简、透明、强大的 CLI Agent 框架。

一句话描述：用 ~400 行核心函数，实现 Claude Code 的编程能力 + Manus 的系统操控能力。

核心原则

1. 极简即力量

• 核心 Agent 逻辑控制在 ~400 行，初学者 30 分钟可读完
• 不追求工具数量，追求 bash + LLM 智能 的无限组合能力
• 每一行代码都应该有存在的理由

2. 透明可控

• 工具调用过程完全可见（TOOL: xxx ARGS: {...}）
• 没有黑盒抽象，没有魔法
• 初学者可以清楚看到 AI Agent 是怎么工作的

3. bash 是万能工具

• MiniAgent 不内置 100 个专用工具，而是依赖 bash + LLM 的组合
• 要截图？LLM 会通过 bash 调用 python -c "from mss import mss; mss().shot()"
• 要控制鼠标？LLM 会通过 bash 调用 pyautogui
• 要爬网页？LLM 会通过 bash 编写并运行 Python 脚本
• 这种设计让框架保持极简，同时能力无上限

4. 教学优先

• 这是"最好的 AI Agent 教科书"
• 代码结构清晰：agent.py（核心循环）→ tools/（工具集）→ cli.py（交互界面）
• 支持文本解析和原生 Function Calling 两种模式，便于对比学习

5. 不做大杂烩

• 不引入重型依赖（pyautogui/playwright/mss 等不作为内置依赖）
• 不增加不必要的抽象层
• 如果一个功能可以通过 bash 实现，就不为它单独建工具

架构概览

miniagent/
├── agent.py        # 核心 Agent 循环（~400行核心函数）
│                   # - LLM 客户端初始化
│                   # - 工具调用解析（文本模式 + 原生 FC 模式）
│                   # - 流式输出 (_call_llm_stream)
│                   # - 上下文管理 (_summarize_messages)
│                   # - 危险命令检测 (_check_dangerous)
│                   # - 工具执行循环
│                   # - 消息历史管理
├── cli.py          # 交互式命令行界面
│                   # - Rich 美化输出
│                   # - 流式 token 输出
│                   # - 工具执行回调显示
│                   # - 危险命令 Rich 确认弹窗
│                   # - 会话记忆集成
├── config.py       # 配置管理（.env / JSON / 环境变量）
├── logger.py       # 日志配置
├── memory.py       # 轻量会话记忆（~/.miniagent/memory.json）
├── mcp_client.py   # MCP 客户端 re-export（→ extensions/）
├── orchestrator.py # Agent 编排器 re-export（→ extensions/）
├── skills.py       # Skill 系统（可复用的 Agent 配置）
│                   # - name + prompt + tool whitelist + temperature
│                   # - 内置: coder/researcher/reviewer/tester
├── extensions/
│   ├── mcp_client.py   # MCP 协议客户端实现
│   │                   # - stdio JSON-RPC 传输
│   │                   # - 工具发现 + 调用
│   │                   # - 自动转为 MiniAgent 工具格式
│   └── orchestrator.py # Agent 编排器实现
│                       # - 任务分解（planner agent）
│                       # - 角色分配（基于 Skill 系统）
│                       # - 上下文传递
├── tools/
│   ├── __init__.py     # 工具注册系统（@register_tool 装饰器）
│   ├── code_tools.py   # 代码工具：read/write/edit/grep/glob/bash
│   └── basic_tools.py  # 基础工具：calculator/time/system/browser/clipboard/docx
└── utils/
    ├── json_utils.py   # 健壮的 JSON 解析（处理 LLM 输出的各种格式问题）
    ├── text_utils.py   # 共享文本工具（smart_truncate）
    └── reflector.py    # 反思机制（可选，用于改善推理质量）