aa1143/NamiAgent

项目介绍

NamiAgent 是一套面向零基础读者的 AI Agent 教程，同时本身就是一个能在本地跑起来的 Agent。它从 100 行的最小循环讲起：调模型、执行工具、把结果写回上下文、再调模型，然后每课加一个能力——工具系统、权限、上下文管理、Skills、接入聊天软件、定时任务与心跳、MCP、子 Agent、计划、长期记忆。

前 11 课每一课都有可运行的完整代码快照，放在 lessons/lesson-01 到 lesson-11，既能直接运行，也能对比相邻两课看新增了什么。最后一部分只有文章：拆解 Claude Code、Codex、Pi、Grok Bot、DeepSeek Harness、OpenClaw 与 Hermes 等主流 Agent 的做法，并附一张总对照表（课程目录、总对照表）。

它适合想弄懂 Agent 内部到底发生了什么、而不是直接套框架的人。整个项目只依赖 openai 一个包，走 OpenAI 兼容接口，默认用 DeepSeek；自带网页端，能看见每次模型调用、工具调用和完整上下文。

快速使用

需要 Python 3.10+。克隆仓库、装依赖，再配置模型：

git clone https://github.com/aa1143/NamiAgent.git
cd NamiAgent
pip install -r requirements.txt

export API_KEY=你的模型密钥
# 可选：换成其他 OpenAI 兼容服务
export BASE_URL=https://...
export MODEL=模型名

export NAMI_WORKSPACE=~/agent-workspace   # 第 3 课起，Agent 只能操作这个目录
mkdir -p $NAMI_WORKSPACE

cd lessons/lesson-05
python agent.py

不想填 API Key，可以先跑脚本化假模型的网页演示：

cd NamiAgent
python web/app.py --demo

然后打开 http://localhost:8765。左边显示每次模型调用、模型写出的思考过程和工具输入输出，右边显示这一轮发给模型的完整上下文（网页端说明）。macOS 也可以双击 web/start.command，会自动建虚拟环境、装依赖并提示粘贴 API Key，直接回车则进入演示模式。

从第 3 课起每课都有测试，第 11 课共 49 个，用假模型跑，不需要 API Key：

cd lessons/lesson-11 && pytest -q

使用约束

• 运行前提：真实运行需要 Python 3.10+ 和模型密钥；没有密钥时只能用网页演示模式或第 3 课起的测试。
• 工作区范围：第 3 课起用 NAMI_WORKSPACE 限定 Agent 能操作的目录，应指向专门的工作区，不要指向主目录。
• 权限机制：写文件、执行命令前会请求确认，但资料明确说明它挡得住误操作和低成本的越界，挡不住有意的攻击（安全提醒）。
• 状态与配置：会话记录、定时任务等状态放在工作区之外的 NAMI_STATE_DIR，默认 ~/.nami-agent；第 8 课起的 MCP 配置在 ~/.nami-agent/mcp.json；第 6 课的 Telegram bot 还需要 TG_BOT_TOKEN 和 TG_ALLOWED_USERS。
• 不是生产级框架：这是教学代码，目标不是和 Claude Code、Codex 比功能。
• 许可证：代码采用 MIT，docs/ 下的文章采用 CC BY-NC 4.0。

HotRepo 点评

该仓库没有记录到 GitHub 全部语言日榜名次，目前可用的站内信号是 Python 新项目榜：2026-11-01 04:45 到 09:45（UTC）的统计窗口内新增 11 个 Star，总量达到 113 Star、8 Fork。窗口只有约 5 小时，也没有同期对照，只能说明获得了早期关注，不足以判断趋势。更有辨识度的是它的结构：11 个可运行的课程快照，加上不需要 API Key 的测试，让「真的跑一遍」成本很低；网页端把上下文增长直接摊开，而不是藏在框架后面。