从入门到精通，手把手做一个"能执行任务的 Agent"——每个概念都对账 opencode 真实源码。
这是一个边学边跑的教学工程。你会用不到 200 行 Python 亲手搭出一个能调用工具、能拆解任务的 AI agent；同时，每一个概念都标注了它在 opencode 生产级源码里的确切位置（文件 + 行号），让你既能"照着做出来"，也能"对着大厂代码核对"。
面向对象：会一点编程（任意语言）、知道什么是大模型/API、用过命令行的初学者。不需要懂 TypeScript 或函数式编程。
无需 API key 也能跑（内置离线 mock 模式，让你先看清循环怎么转）：
git clone https://github.com/darinouyang/opencode-agent-course.git
cd opencode-agent-course/agent
python3 step1_loop.py "算一下 2*(3+4) 等于多少"想接真实模型？设三个环境变量即可（兼容 OpenAI / 通义千问 DashScope / DeepSeek / 本地 Ollama 等任何 OpenAI 兼容接口）：
export OPENAI_API_KEY="你的key"
export OPENAI_BASE_URL="https://api.openai.com/v1" # 换成你的服务地址
export OPENAI_MODEL="gpt-4o-mini" # 换成你的模型名
python3 step1_loop.py "读一下上级目录的 README.md 并总结"只用 Python 标准库，零第三方依赖，Python 3.9+ 即可。
建议按顺序：先读一章文档，再跑对应的 step*.py，最后翻 对账表 去 opencode 源码里核对。
| 阶段 | 文档 | 可运行代码 | 你会学到 |
|---|---|---|---|
| 入门 | 01 · Agent 是什么 | step1_loop.py |
agent 的本质是一个 while 循环（心跳） |
| 入门 | 02 · 工具 | tools.py |
工具的四要素 + function calling |
| 进阶 | 03 · 提示词与记忆 | 各 step 的 SYSTEM_PROMPT/messages |
系统提示词 + 模型无状态 + 消息历史 |
| 进阶 | 04 · 权限/技能/子Agent | step2 / step3 / step4 |
权限闸门、技能注入、子 agent 拆解 |
每个 step 文件都是独立可跑的，从 step1 到 step4 逐步加料：
step1_loop.py 最小心跳循环（模型 + 工具 + 循环）
step2_permission.py + 权限闸门（危险操作先征求许可）
step3_skill.py + 技能（把领域工作流注入对话）
step4_subagent.py + 子 agent（把大任务拆给独立分身去做）
市面上讲 agent 的教程很多，但大多停在"玩具 demo"，你学完不知道"真实产品是不是也这么干的"。
本工程的核心是 docs/MAPPING.md 对账表：把每个概念三方对齐——
概念（心跳循环） → opencode 源码（prompt.ts L1088-L1096） → 本课程代码（step1_loop.py 的 for 循环）
对账基线锁定在 opencode 的 commit 518772c，行号以此为准。你可以逐条点开源码核对，确认"我学的这套，就是生产级 agent 真实在用的那套"。
opencode-agent-course/
├── README.md
├── agent/ # 可运行的极简 agent（Python，零依赖）
│ ├── tools.py # 工具集 + 注册表 + 路由
│ ├── llm.py # 模型调用（含离线 mock）
│ ├── step1_loop.py # 入门：心跳循环
│ ├── step2_permission.py # 进阶：权限
│ ├── step3_skill.py # 进阶：技能
│ └── step4_subagent.py # 精通：子 agent
├── docs/ # 分章学习文档
│ ├── 01-what-is-an-agent.md
│ ├── 02-tools.md
│ ├── 03-prompt-and-memory.md
│ ├── 04-permission-skill-subagent.md
│ └── MAPPING.md # ⭐ 概念↔源码↔代码 对账表
└── web/
└── tutorial.html # 交互式 HTML 学习手册（浏览器打开即可）
本教程的对账对象是开源项目 opencode（anomalyco/opencode）。文中所有源码片段均为教学引用，版权归原作者所有；本仓库不复制其源码，只标注文件路径与行号供读者对照学习。
本仓库代码以 MIT 协议开源，仅供学习。run_bash 等工具为教学演示，生产环境请务必加沙箱与权限控制。