# mini-agent

**Repository Path**: dazhuang/mini-agent

## Basic Information

- **Project Name**: mini-agent
- **Description**: mini-agent
系列「AI Agent 从原理到实战」的主线项目。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mini-agent

系列「AI Agent 从原理到实战」的主线项目。

**新手请先读**：[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)（目录说明、一次对话流程、设计模式白话解释）

## Tag 与篇目对照

**实战篇** 使用 `article-00` … `article-10`；**进阶篇** 使用 `advance-01` …（与实战 tag 序列分开，便于 checkout 跟读）。

| Tag | 篇目 | 能力 |
|-----|------|------|
| `article-00` | 实战 0 | Brain 封装 + CLI 多轮对话 |
| `article-01` | 实战 1 | ContextManager + token 预算与滑动截断 |
| `article-02` | 实战 2 | ToolRegistry + 时间/计算/JSON 解析工具 |
| `article-03` | 实战 3 | ReActOrchestrator + max_steps + 重试/防循环 |
| `article-04` | 实战 4 | PlanExecuteOrchestrator + get_weather + Done 检查 |
| `article-05` | 实战 5 | MemoryManager + profile / session 摘要 / working |
| `article-06` | 实战 6 | KnowledgeRetriever + search_knowledge + 离线索引 CLI |
| `article-07` | 实战 7 | TraceRecorder + EvalRunner + trace/eval CLI |
| `article-08` | 实战 8 | FastAPI HTTP 服务 + SQLite 会话 + Docker |
| `article-09` | 实战 9 | MultiAgent Supervisor + Blackboard + Critic |
| `article-10` | 实战 10 | SSE `/v1/chat/stream` + `web/` 对话页 + 打字机 UX |
| `advance-01` | 进阶 01 | MCP Client 桥 + demo Server + 对话/trace 验证 |
| `advance-02` | 进阶 02 | HITL 写操作审批 + checkpoint resume + Web 审批卡 |
| `advance-03` | 进阶 03 | 结构化输出 Plan / DoneCheck / Finalize + Pydantic 修复 |
| `advance-04` | 进阶 04 | Plan 进度 SSE（`plan_ready` / `plan_step`）+ Finalize 伪流式 |

当前 `config/agent.yaml` 中 `agent.version` 为 **`advance-04`**（与最新进阶篇 tag 对齐）。

## 项目结构（简要）

```text
mini-agent/
├── main.py                  # 入口：chat / serve / trace / eval / index / mcp
├── config/agent.yaml        # 行为配置（非密钥；.env 可覆盖）
├── mini_agent/              # 业务代码包
│   ├── factory.py           # 组装 ChatApplication（DI 入口）
│   ├── app.py               # turn() / resume_hitl() 外观
│   ├── config/              # Settings + YAML 加载
│   ├── core/                # 类型与异常
│   ├── brain/               # OpenAIBrain · chat / chat_stream / chat_structured
│   ├── context/             # ContextManager · 截断与 compact
│   ├── tools/               # ToolRegistry · Executor · tier(T0–T2)
│   ├── planning/            # Router · Planner · DoneCheck · Finalize
│   ├── structured/          # Pydantic 契约 · StructuredParser · JSON 提取
│   ├── orchestrator/        # ReActOrchestrator · PlanExecuteOrchestrator
│   ├── memory/              # profile / session 摘要 / working
│   ├── knowledge/           # 文档 RAG · 索引与检索
│   ├── trace/               # TraceRecorder · JsonTraceStore
│   ├── eval/                # golden case 评测
│   ├── session/             # SQLite 会话持久化（HTTP）
│   ├── api/                 # FastAPI · SSE · HITL resume 路由
│   ├── streaming/           # TurnEventEmitter · SSE 事件类型
│   ├── multi_agent/         # Supervisor · Expert · Blackboard · Critic
│   ├── mcp/                 # McpSessionManager · register_mcp_tools
│   ├── hitl/                # HitlStore · 审批策略 · checkpoint
│   └── cli/                 # 终端 / serve / trace / eval 子命令
├── web/                     # 静态对话页（SSE + Plan 卡 + HITL 卡）
├── scripts/                 # MCP demo server 等
└── docs/ARCHITECTURE.md     # 详细架构说明
```

## 环境

- Python 3.10+
- 复制 `.env.example` 为 `.env` 并填写 `OPENAI_API_KEY`

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
python main.py              # CLI 对话
python main.py serve        # HTTP + Web 对话页 → http://127.0.0.1:8000/
```

## 常用命令

| 命令 | 说明 |
|------|------|
| `python main.py` | CLI 多轮对话（含 HITL y/N 提示） |
| `python main.py serve` | 启动 FastAPI + 挂载 `web/` |
| `python main.py trace [id]` | 查看 trace |
| `python main.py eval` | 运行 golden case |
| `python main.py index` | 重建 RAG 文档索引 |
| `curl -s http://127.0.0.1:8000/ready \| jq` | 就绪检查（含 mcp / hitl / structured / stream） |

## 技术路线

**已选型：LangGraph（文章附录对照）；主线代码为自研编排。**

| 阶段 | 实现 |
|------|------|
| 实战 0–2 | 纯 OpenAI SDK + 自研 `Brain` / `ContextManager` / `ToolRegistry` |
| 实战 3 起 | **`ReActOrchestrator`** 主循环；LangGraph 对照见文章附录 |
| 实战 4 起 | **`PlanExecuteOrchestrator`** + Plan / Done 检查 |
| 实战 5 起 | **`MemoryManager`** 注入 profile / 摘要 / working |
| 实战 6 起 | **`KnowledgeRetriever`** + `search_knowledge` |
| 实战 7 起 | **`TraceRecorder`** + **`EvalRunner`** |
| 实战 8 起 | **FastAPI** + **`SqliteSessionStore`** + Docker |
| 实战 9 起 | **`MultiAgentOrchestrator`**（Supervisor + 黑板 + Critic） |
| 实战 10 起 | **`POST /v1/chat/stream`**（SSE）+ **`web/`** 打字机 |
| 进阶 01 起 | **`McpSessionManager`** + MCP 工具前缀 `mcp_*` |
| 进阶 02 起 | **HITL**：T2 写工具挂起 · `waiting_hitl` · `/v1/hitl/resume` |
| 进阶 03 起 | **结构化**：`structured/` · Plan/Done/Finalize Pydantic + repair |
| 进阶 04 起 | **流式 UX**：`plan_ready` / `plan_step` · Finalize pseudo-stream |

## 配置要点（`config/agent.yaml`）

| 段 | 作用 |
|----|------|
| `agent` | 版本号、max_steps、plan_mode |
| `multi_agent` | Supervisor 开关与路由 mode |
| `stream` | SSE、Brain 流式、Plan 进度卡、伪流式切片 |
| `mcp` | MCP server 列表（stdio） |
| `hitl` | 写操作审批 TTL |
| `structured` | JSON schema 模式与 repair 次数 |

环境变量与 YAML 同名项可覆盖；密钥仅走 `.env`（如 `OPENAI_API_KEY`）。

## 文档

Obsidian 系列文章位于仓库上级目录：`实战00-*.md` … `实战10-*.md`，`进阶01-*.md` … `进阶04-*.md`。