Maintainer of this skill?
by aa1143
零基础入门 AI Agent 的基础教程。不只是教程，也是一个能在本地跑起来的 Agent：读写文件、执行命令、MCP、长期记忆，自带网页端看清每一步。从 100 行最小循环开始，一课加一个能力，最后拆解 Claude Code、Codex 等主流 Agent
# Add to your Claude Code skills
git clone https://github.com/aa1143/NamiAgentSee how NamiAgent compares with popular alternatives.
NamiAgent is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by aa1143. 零基础入门 AI Agent 的基础教程。不只是教程，也是一个能在本地跑起来的 Agent：读写文件、执行命令、MCP、长期记忆，自带网页端看清每一步。从 100 行最小循环开始，一课加一个能力，最后拆解 Claude Code、Codex 等主流 Agent. It has 64 GitHub stars.
NamiAgent's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/aa1143/NamiAgent" and add it to your Claude Code skills directory (see the Installation section above).
NamiAgent is primarily written in Python. It is open-source under aa1143 on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh NamiAgent against similar tools.
No comments yet. Be the first to share your thoughts!
Available after the catalog security scan passes.
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
零基础入门 AI Agent 的基础教程 不只是教程，也是一个能在本地跑起来的 Agent，自带网页端，每一步都看得见
Agent 没有什么神秘的，核心就是一个 while 循环：调模型、执行工具、把结果写回上下文，再调模型。
它是教程：从 100 行的最小循环开始，一课加一个能力：工具、权限、上下文管理、Skills、MCP、子 Agent、计划、记忆。最后拆解 Claude Code、Codex 等主流 Agent 是怎么做的。内容是我自己一步步学习、动手实践后整理出来的。
它也是一个能用的本地 Agent：在你指定的工作区里读写文件、执行命令、接入 MCP、记住你是谁；写文件、跑命令前都会先问你。python web/app.py 打开网页端，左边看它每一步怎么想、调了什么工具，右边看每次发给模型的完整上下文。
lessons/lesson-01 到 lesson-11，每个目录都是学完这一课时的完整代码，可以直接运行，也可以对比相邻两课的差异openai 一个包：没有任何 Agent 框架先学 NamiGPT 搞懂模型本身，再学 NamiAgent 搞懂模型外面那一圈。
| 课 | 文章 | 代码 | 这一课新增 |
|---|---|---|---|
| 01 | 最小循环 | lesson-01 | agent.py：三个工具 + 一个 while 循环 |
| 02 | 工具系统 | lesson-02 | tools.py：注册表、统一执行器 |
| 03 | 权限 | lesson-03 | permissions.py：硬规则 → 风险分级 → 人工确认 |
| 04 | 上下文管理 | lesson-04 | context.py：截断 → 清理 → 摘要，会话持久化 |
| 05 | Skills | lesson-05 | skills.py：AGENTS.md 常驻，技能按需加载 |
| 06 | 接入聊天软件 | lesson-06 | telegram.py、bot.py：常驻、聊天确认、白名单 |
| 07 | 定时任务与心跳 | lesson-07 | scheduler.py：无人值守的预授权、心跳 |
| 课 | 文章 | 代码 | 这一课新增 |
|---|---|---|---|
| 08 | MCP | lesson-08 | mcp_client.py：stdio MCP 客户端 |
| 09 | 子 Agent 与多 Agent | lesson-09 | subagent.py：独立上下文，并行只读 |
| 10 | 计划 | lesson-10 | planning.py：待办清单、由代码强制只读的计划模式 |
| 11 | 记忆 | lesson-11 | memory.py：长期记忆（每条确认）、会话检索 |
| 课 | 文章 |
|---|---|
| 12 | 拆解 Claude Code |
| 13 | 拆解 Codex |
| 14 | 拆解 Pi |
| 15 | 拆解 Grok Bot |
| 16 | 拆解 DeepSeek Harness |
| 17 | 拆解 OpenClaw 与 Hermes |
| 18 | 总对照表 |
第三部分写的是截至 2026 年 10 月的情况。这些产品更新很快，细节请以各自官方文档为准。
Agent 是怎么工作的：10 章逐格播放，看上下文每转一圈怎么变长、在哪里出问题，以及各种 Agent 技巧到底在上下文里做了什么。下面是其中第 3 章，配合第 1 课看效果最好：
需要 Python 3.10+。
git clone https://github.com/aa1143/NamiAgent.git
cd NamiAgent
pip install -r requirements.txt
export API_KEY=你的模型密钥
# 默认用 DeepSeek；换其他 OpenAI 兼容模型：
# export BASE_URL=https://... MODEL=模型名
export NAMI_WORKSPACE=~/agent-workspace # 第 3 课起，Agent 只能操作这个目录
mkdir -p $NAMI_WORKSPACE
cd lessons/lesson-05
python agent.py
跑测试（不需要 API Key）：
cd lessons/lesson-11 && pytest -q
页首的两张动图就是网页端的真实运行录屏。
python web/app.py --demo # 演示模式：脚本化的假模型，不需要 API Key，先看看效果
python web/app.py # 用真实模型，和命令行版一样读 API_KEY / BASE_URL / MODEL
macOS 也可以直接双击 web/start.command：自动建虚拟环境、装依赖、让你粘贴 API Key（直接回车就是演示模式），然后打开浏览器。Agent 的工作区默认是 ~/agent-workspace。
然后打开 http://localhost:8765 ：
/plan 让它先出计划，批准后再动手（第 10 课）网页端直接导入 lessons/lesson-11 的 Agent，没有改课程代码，只换了三个接口：模型客户端（把每次发出去的上下文推给浏览器）、handle_call（把工具调用推给浏览器）、权限确认的 ask（终端 input() 换成弹窗）。只用 Python 标准库，不需要装 Web 框架。
DeepSeek 默认开启思考模式，模型返回的思考过程（reasoning_content）会单独显示。带工具调用时，这段思考要原样放回上下文再发给 API，右边的上下文面板里也能看到它。界面里展示的思考只是模型写出来的文字，不等于模型内部真实的计算过程。
| 变量 | 作用 | 默认值 |
|---|---|---|
API_KEY |
模型密钥 | 必填 |
BASE_URL |
OpenAI 兼容接口地址 | https://api.deepseek.com |
MODEL |
模型名 | deepseek-flash |
NAMI_WORKSPACE |
Agent 的工作区（第 3 课起） | 启动时所在的目录 |
NAMI_STATE_DIR |
会话记录、定时任务等状态（第 4 课起），放在工作区之外 | ~/.nami-agent |
第 6 课起的 bot.py 还需要 TG_BOT_TOKEN 和 TG_ALLOWED_USERS，见第 6 课。第 8 课起可以接入 MCP 服务器，配置放在 ~/.nami-agent/mcp.json，格式见第 8 课。
这是教学代码，Agent 会真的执行命令、读写文件。第 3 课的权限机制能挡住误操作和低成本的越界，挡不住有意的攻击（第 3 课第八节专门讲了它防不住什么）。
请在专门的工作区目录里运行，不要把工作区指向你的主目录。
NamiAgent 是一个看得懂的最小 Agent，不是生产级框架，也不打算和 Claude Code、Codex 比功能。目标是让你读完之后，再看任何 Agent 产品，都知道它在上下文里做了什么。
代码采用 MIT，docs/ 下的文章采用 CC BY-NC 4.0。