<div align="center">

agent-from-scratch

逐步生长的编程 Agent：从零开始构建一个能干活的 AI Agent

从最小的 agent loop 开始，按 Git tag 和能力阶段逐步加入工具、安全、上下文和可靠执行能力。

English · 中文

</div>

---

适合想用 Python 标准库理解 LLM agent 如何运行的开发者。每课聚焦一个版本相对上一版新增的核心概念，源码、diff 和设计取舍都可追溯。

当前状态：主线已实现 v0.51（第 51 课：重复运行编码基准）。四道纯标准库 Python 题及独立成功标准已冻结，计划每题运行 3 次真实模型 trial；首轮 12 次 live 调用等待用户审阅题目与标准后启动，目前没有编码模型成绩。固定响应和离线 grader 检查只验证评测器，不计入基线。教程以默认分支的 docs/tutorials/ 为准；运行某课时再切换该课声明的代码 tag。

快速入口：运行 · 学习路径 · 学习指南 · 完整手册

学习路径

<table width="100%"> <thead> <tr><th>版本</th><th>主题</th><th>简介</th></tr> </thead> <tbody> <tr><th colspan="3"><a id="stage-1"></a>阶段一 · 理解 Agent Loop</th></tr> <tr><td><strong>v0.01</strong></td><td><a href="./docs/tutorials/01-minimal-loop.md">最简 agent loop</a></td><td>建立最小对话循环，理解请求、回复与结束条件。</td></tr> <tr><th colspan="3"><a id="stage-2"></a>阶段二 · 工具与安全</th></tr> <tr><td><strong>v0.02</strong></td><td><a href="./docs/tutorials/02-first-tool.md">第一个工具</a></td><td>接入 calculate，跑通 function calling 基本协议。</td></tr> <tr><td><strong>v0.03</strong></td><td><a href="./docs/tutorials/03-file-tools.md">文件读写工具</a></td><td>让 Agent 读取和写入真实项目文件。</td></tr> <tr><td><strong>v0.04</strong></td><td><a href="./docs/tutorials/04-permission-gate.md">权限闸门</a></td><td>为有副作用的工具加入 allow、deny、ask 三态授权。</td></tr> <tr><th colspan="3"><a id="stage-3"></a>阶段三 · Mini Agent 里程碑</th></tr> <tr><td><strong>v0.05</strong></td><td><a href="./docs/tutorials/05-streaming.md">流式输出</a></td><td>逐块接收并显示 LLM 回复，改善交互反馈。</td></tr> <tr><td><strong>v0.06</strong>（补丁 <code>v0.06.1</code>）</td><td><a href="./docs/tutorials/06-concurrent-tool-calls.md">并发 tool_calls</a></td><td>并发执行同一轮的多个工具调用，减少等待时间；补丁修正多轮上下文状态契约。</td></tr> <tr><td><strong>v0.07</strong></td><td><a href="./docs/tutorials/07-system-prompt.md">系统提示词工程化</a></td><td>分层组织身份、规则和环境信息，稳定 Agent 行为。</td></tr> <tr><td><strong>v0.08</strong></td><td><a href="./docs/tutorials/08-file-operations.md">文件操作补全</a></td><td>补齐目录列举、精确编辑和正则搜索能力。</td></tr> <tr><td><strong>v0.09</strong></td><td><a href="./docs/tutorials/09-permission-upgrade.md">权限系统升级</a></td><td>按工具和路径或命令模式细粒度匹配权限规则。</td></tr> <tr><td><strong>v0.10</strong></td><td><a href="./docs/tutorials/10-shell-execution.md">shell 执行</a></td><td>执行命令并处理超时、输出截断和命令级授权。</td></tr> <tr><th colspan="3"><a id="stage-4"></a>阶段四 · 上下文管理</th></tr> <tr><td><strong>v0.11</strong></td><td><a href="./docs/tutorials/11-context-architecture.md">上下文架构</a></td><td>将持久执行状态与可裁剪的对话上下文分离。</td></tr> <tr><td><strong>v0.12</strong></td><td><a href="./docs/tutorials/12-token-budget-trimming.md">预算与裁剪</a></td><td>估算 token，并按完整对话轮次安全裁剪历史。</td></tr> <tr><td><strong>v0.13</strong>（补丁 <code>v0.13.1</code>、<code>v0.13.2</code>）</td><td><a href="./docs/tutorials/13-context-compaction.md">上下文压缩</a></td><td>用历史摘要和结构化状态降低长任务遗忘；补丁增加可观测性与任务边界隔离。</td></tr> <tr><th colspan="3"><a id="stage-5"></a>阶段五 · 项目感知与任务编排</th></tr> <tr><td><strong>v0.14</strong></td><td><a href="./docs/tutorials/14-project-instructions.md">项目级指令</a></td><td>自动发现并注入适用的 <code>AGENTS.md</code> 指令。</td></tr> <tr><td><strong>v0.15</strong></td><td><a href="./docs/tutorials/15-task-state.md">任务清单与状态</a></td><td>用结构化任务清单与显式状态跟踪多步任务进度。</td></tr> <tr><td><strong>v0.16</strong>（补丁 <code>v0.16.1</code>）</td><td><a href="./docs/tutorials/16-plan-driven-execution.md">计划驱动执行</a></td><td>通过计划、执行、观察、重排和验证形成闭环；补丁收窄完成提醒的重开规则。</td></tr> <tr><th colspan="3"><a id="stage-6"></a>阶段六 · 可靠执行</th></tr> <tr><td><strong>v0.17</strong></td><td><a href="./docs/tutorials/17-failure-model.md">失败模型</a></td><td>记录 generation、执行尝试与可审计失败事实。</td></tr> <tr><td><strong>v0.18</strong>（补丁 <code>v0.18.1</code>）</td><td><a href="./docs/tutorials/18-recovery-policy.md">受限恢复策略</a></td><td>用受限动作恢复失败并隔离 generation；补丁修正边界一致性。</td></tr> <tr><td><strong>v0.19</strong></td><td><a href="./docs/tutorials/19-checkpoint-rollback.md">单文件检查点与回滚</a></td><td>为单文件写入保存前镜像，在冲突检测下原子恢复，并保持恢复状态可见、可验证。</td></tr> <tr><td><strong>v0.20</strong></td><td><a href="./docs/tutorials/20-repair-loop.md">修复循环</a></td><td>把失败、诊断、受限恢复和独立验证串成有上限的阶段化循环。</td></tr> <tr><td><strong>v0.21</strong></td><td><a href="./docs/tutorials/21-trace-replay.md">任务轨迹回放</a></td><td>按 generation 只读回放 Todo、执行、失败、恢复、验证和终态的因果链。</td></tr> <tr><th colspan="3"><a id="stage-7"></a>阶段七 · 结构化计划</th></tr> <tr><td><strong>v0.22</strong></td><td><a href="./docs/tutorials/22-plan-contract.md">Plan Contract（结构化计划）</a></td><td>用不可变 revision 保存计划结构，用独立 progress event 推进步骤状态，并把计划执行视图注入上下文。</td></tr> <tr><td><strong>v0.23</strong></td><td><a href="./docs/tutorials/23-plan-mode-handoff.md">只读规划与用户交接</a></td><td>复杂任务先只读调查；计划模式提交后等待用户决定，批准仍不绕过工具授权。</td></tr> <tr><td><strong>v0.24</strong></td><td><a href="./docs/tutorials/24-replanning-policy.md">证据驱动重规划与停滞收口</a></td><td>执行中引用真实 failure 或观察修订计划；重复工具回合先提醒，再有界阻塞。</td></tr> <tr><td><strong>v0.25</strong></td><td><a href="./docs/tutorials/25-plan-trace-evaluation.md">计划轨迹回放与验收</a></td><td>按顺序事件连接 generation、revision、触发事实、用户决定、执行与独立验证。</td></tr> <tr><th colspan="3"><a id="stage-8"></a>阶段八 · 后台进程与任务边界</th></tr> <tr><td><strong>v0.26</strong></td><td><a href="./docs/tutorials/26-background-process-boundaries.md">后台进程启动与任务边界</a></td><td>启动长期命令后继续工作，排空有界输出，按任务归属同步退出，并在交接和任务切换时清理进程。</td></tr> <tr><td><strong>v0.27</strong></td><td><a href="./docs/tutorials/27-process-observation.md">观察后台进程</a></td><td>跨轮次查询状态、读取新增输出，并在没有新消息时有界等待和交接。</td></tr> <tr><td><strong>v0.28</strong></td><td><a href="./docs/tutorials/28-process-control.md">控制后台进程</a></td><td>按任务授权终止或强制结束进程，确认退出后重新验证。</td></tr> <tr><td><strong>v0.29</strong></td><td><a href="./docs/tutorials/29-interactive-process.md">驱动等待输入的后台进程</a></td><td>显式开启有界管道 stdin，写入少量 UTF-8 文本并发送 EOF，同时保持授权、脱敏、清理和独立验证边界。</td></tr> <tr><th colspan="3"><a id="stage-9"></a>阶段九 · 会话持久化与安全交接</th></tr> <tr><td><strong>v0.30</strong></td><td><a href="./docs/tutorials/30-session-persistence.md">会话持久化与安全点</a></td><td>通过 /save 显式开启本地保存，在完整安全点原子更新 active 会话，退出或任务切换时在进程清理后提交 clean；本版只能校验文件，不能恢复任务。</td></tr> <tr><td><strong>v0.31</strong></td><td><a href="./docs/tutorials/31-safe-resume.md">从完整安全点恢复会话</a></td><td>用 --resume 检查 schema 2、工作区清单和 clean 交接，在新进程重建运行时；旧验证、进程句柄和 checkpoint 回滚资格不会被继承。</td></tr> <tr><td><strong>v0.32</strong></td><td><a href="./docs/tutorials/32-durable-tool-boundaries.md">持久化工具执行边界</a></td><td>在同一 schema 3 session 文件中按 handler 准入、单 call 结果和整轮 complete 提交 State 与 Context；半轮只用于诊断，暂不续跑。</td></tr> <tr><td><strong>v0.33</strong></td><td><a href="./docs/tutorials/33-crash-recovery.md">崩溃恢复与不确定副作用交接</a></td><td>从 active pending 边界派生新 session，逐项区分未执行与不确定事实；不自动重放，先只读调查并由用户决定继续或阻塞。</td></tr> <tr><th colspan="3"><a id="stage-10"></a>阶段十 · 受控子代理委派</th></tr> <tr><td><strong>v0.34</strong></td><td><a href="./docs/tutorials/34-minimal-delegation.md">最小受控子代理委派</a></td><td>父 Agent 同步委派单个、单层、只读 Subagent；用隔离 Context、能力过滤、scope 和结构化结果合同收集调查材料。</td></tr> <tr><td><strong>v0.35</strong></td><td><a href="./docs/tutorials/35-shared-agent-runtime.md">共享父子运行循环</a></td><td>父 Agent 与只读 Subagent 共用唯一的 AgentRuntime.run() 协议骨架，差异由策略、Context、工具面和预算表达。</td></tr> <tr><td><strong>v0.36</strong></td><td><a href="./docs/tutorials/36-multi-provider.md">多 provider 与统一协议适配</a></td><td>用本地 profile 绑定父子模型，接入 OpenAI-compatible Chat Completions 与 Anthropic Messages，并把 provider 差异收进适配层。</td></tr> <tr><td><strong>v0.37</strong></td><td><a href="./docs/tutorials/37-subagent-lifecycle-budget.md">子代理生命周期与聚合预算</a></td><td>记录委派交付状态，按父任务聚合预算预留与结算，并用协作式取消收束同步子代理。</td></tr> <tr><td><strong>v0.38</strong></td><td><a href="./docs/tutorials/38-parallel-delegation.md">有界并行子代理</a></td><td>在固定并发上限下运行多个只读调查，并按模型 tool-call 顺序提交父结果。</td></tr> <tr><td><strong>v0.39</strong></td><td><a href="./docs/tutorials/39-durable-delegation.md">持久委派交付</a></td><td>先保存已校验的子结果，再按父调用顺序原子交付并支持跨进程恢复。</td></tr> <tr><th colspan="3"><a id="stage-11"></a>阶段十一 · 工作区 Memory &amp; References</th></tr> <tr><td><strong>v0.40</strong></td><td><a href="./docs/tutorials/40-persistent-memory.md">轻量持久 Memory</a></td><td>由父 Agent 显式查看、保存、修订和遗忘工作区记忆，支持分页、工作区外存储和不确定提交核查，并通过权限、revision、原子存储和恢复边界保持可核查。</td></tr> <tr><td><strong>v0.41</strong></td><td><a href="./docs/tutorials/41-memory-retrieval.md">相关记忆检索</a></td><td>用标准库词法检索找回少量相关候选，并把不可信摘要按 Context 预算临时注入父 Agent；显式搜索与自动检索都不改变 Memory、State 或 session。</td></tr> <tr><td><strong>v0.42</strong></td><td><a href="./docs/tutorials/42-local-references.md">具名本地 References</a></td><td>通过稳定 alias 发现、搜索和按行读取工作区外的本地资料；每次访问重新检查权限、符号链接和敏感目录，References 不进入自动 Context 或子代理。</td></tr> <tr><th colspan="3"><a id="stage-12"></a>阶段十二 · MCP &amp; Skills</th></tr> <tr><td><strong>v0.43</strong></td><td><a href="./docs/tutorials/43-stdio-mcp-client.md">最小 stdio MCP 客户端</a></td><td>用独立命令连接本地 MCP Server，完成固定生命周期、分页列工具和逐次确认的手动调用；MCP Tool 仍不进入 Agent。</td></tr> <tr><td><strong>v0.44</strong></td><td><a href="./docs/tutorials/44-mcp-tools-runtime.md">MCP Tool 接入父 Agent Runtime</a></td><td>让显式启用的本地 MCP Tool 经过统一 Registry、权限、计划、持久工具边界和恢复流程；严格校验参数、区分失败结果，并保持 Subagent 隔离。</td></tr> <tr><td><strong>v0.45</strong></td><td><a href="./docs/tutorials/45-local-skills.md">本地 Skills 发现与按需加载</a></td><td>只展示固定目录中的 Skill 元数据，获准后按需读取正文；Skill 只指导现有工具的工作流，不授予权限、不自动执行命令，并保持正文与 State/Trace 隔离。</td></tr> <tr><td><strong>v0.46</strong></td><td><a href="./docs/tutorials/46-mcp-http-resources-prompts.md">受限 HTTP MCP、文本 Resource 与 Prompt</a></td><td>接入仅返回 JSON 的远程 MCP，按分页冻结 Resource/Prompt 目录，并由父 CLI 在权限、预览和不可信内容边界内选择资料或模板。</td></tr> <tr><th colspan="3"><a id="stage-13"></a>阶段十三 · 轻量 Agent 协作</th></tr> <tr><td><strong>v0.47</strong></td><td><a href="./docs/tutorials/47-agent-profiles.md">具名子代理角色</a></td><td>为同步只读委派选择冻结的角色提示、工具子集、模型别名与父侧预授权 Skill；tester 只能分析并建议测试。</td></tr> <tr><td><strong>v0.48</strong></td><td><a href="./docs/tutorials/48-background-subagents.md">进程内后台子代理</a></td><td>父 Agent 启动具名只读调查后继续模型轮次，通过状态查询与显式领取接收结果；整轮持久提交前不启动 worker，活动或未领取任务不能安全保存或完成。</td></tr> <tr><td><strong>v0.49</strong></td><td><a href="./docs/tutorials/49-resumable-child-session.md">可续接子会话</a></td><td>用原 child ID 为已领取成功结果追加完整调查合同；schema 4 安全点原子保存有界子历史，恢复时重核角色、模型和 Skill 身份，并保留累计预算。</td></tr> <tr><th colspan="3"><a id="stage-14"></a>阶段十四 · Agent 任务评测</th></tr> <tr><td><strong>v0.50</strong></td><td><a href="./docs/tutorials/50-evaluation-harness.md">独立评测链路</a></td><td>从固定题目复制干净工作区，运行受限 Agent，再由独立 grader 验收；保存单次结果并分开汇总真实调用与离线自测。</td></tr> <tr><td><strong>v0.51</strong></td><td><a href="./docs/tutorials/51-coding-benchmark.md">重复运行编码基准</a></td><td>冻结四道编码题和独立 grader，按固定顺序计划 12 个 live trial，保留未运行槽位及原始证据；首轮真实结果等待题目审阅。</td></tr> </tbody> </table>

完成 v0.10 后，Agent 已能读取项目、搜索和修改文件、执行命令、运行测试，并通过权限机制控制高风险操作。

快速开始

要求：Python 3.10+；准备一个可访问的 LLM 网关。Bash/zsh：

git clone https://github.com/liiiiiiiiil/agent-from-scratch.git
cd agent-from-scratch
cp src/mini_agent/config_example.py src/mini_agent/config_local.py
# 编辑 config_local.py，填入多 provider 映射；旧 BASE_URL / API_KEY / MODEL 仍兼容，文件不会进 git
python -m pip install -e .
python -m mini_agent "帮我算一下 123 * 456"

可选：python -m pip install -e '.[interactive]' 启用多行终端输入。命令行参数只是首条任务，处理后仍进入交互循环；用空行、exit、quit 或 EOF 退出。PowerShell、免安装运行和配置细节见完整手册。

项目结构

src/mini_agent/   核心运行时、配置、状态、权限、上下文和工具
skills/           项目级本地 Skill 工作流说明
tests/             测试与 smoke test
docs/tutorials/    分阶段、按版本的教程
docs/operation/    最新版运行手册
docs/plans/        路线图与功能计划
d