Back to search
Agent-Learning-Hub
SkillGitHub
AI Agent 学习路线与资料库收集
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/kngwyc3--agent-learning-hub)HTML
<a href="/listings/kngwyc3--agent-learning-hub"><img src="/api/listings/kngwyc3--agent-learning-hub/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
git clone https://github.com/kngwyc3/Agent-Learning-Hub.git cd Agent-Learning-Hub chmod +x scripts/check_github_setup.sh scripts/bootstrap.sh scripts/create_good_first_issues.sh ./scripts/check_github_setup.sh python3 scripts/hub_progress.py status
**展示与入口**
| 入口 | 说明 | | --- | --- | | [README.md](README.md) | 主路线图、资源索引、学习原则(本文件) | | [index.html](index.html) | 交互式学习页:Stage 导航、资源卡片、进度勾选 | | [stage-1/](stage-1/) … [stage-9/](stage-9/) | 分阶段可运行代码与分步教程 |
**仓库结构**
Agent-Learning-Hub/ index.html # 交互式学习页 README.md # 主路线图(本文件) stage-1/ # 最小 agent loop(Python,6 步) stage-2/ # RAG + 记忆(Python,7 步) stage-3/claude-code-docs/ # Claude Code 源码 12 章导读 stage-4/ # Multi-agent coordination(pipeline / supervisor) stage-5/ # Skills 能力打包(4 步 + smoke test) stage-6/ # Browser agent(Playwright + 安全边界) stage-7/ # Eval / trace / 安全门禁 stage-8/ # 可部署 CLI Agent(trace / 安全 / 成本上限) stage-9/ # 上下文压缩与记忆(compaction + memory 最小实现) skills/teach/ # AI 导师 skill(本仓库自带,学习时直接使用) docs/learn/ # 专题阅读笔记(A2A、架构对照等) scripts/ # bootstrap, progress CLI, skill scaffold
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 649 lines
- # Agent Learning Hub
- A curated AI Agent learning roadmap for people who want to build useful, reliable agents instead of collecting random links.
- 这个仓库把社区里优秀分享、官方博客、论文、开源项目和真实工程经验,整理成一份可以照着执行的 AI Agent 学习 todo list。
- ## 为什么 Fork 这个仓库
- 1. **可运行代码** — `./scripts/bootstrap.sh` 一键安装依赖并跑通 stage smoke tests
- 2. **学习进度 CLI** — `python3 scripts/hub_progress.py status` 本地追踪 stage-1–7 进度
- 3. **Cursor Skill 脚手架** — `python3 scripts/scaffold_skill.py --name my-skill --description "..."` 生成可安装 skill
- 4. **Eval 基准包** — stage-7 输出 CSV + [HTML 报告](stage-7/evals/report.html)(运行 eval 后生成)
- 欢迎参与 [30 天 Agent 打卡](.github/30_DAY_CHECKIN.md) 和 [新手任务](.github/GOOD_FIRST_ISSUES.md)。
- ## Quick Start
- ```bash
- git clone https://github.com/kngwyc3/Agent-Learning-Hub.git
- cd Agent-Learning-Hub
- chmod +x scripts/check_github_setup.sh scripts/bootstrap.sh scripts/create_good_first_issues.sh
- ./scripts/check_github_setup.sh
- python3 scripts/hub_progress.py status
- ```
- **展示与入口**
- | 入口 | 说明 |
- | --- | --- |
- | [README.md](README.md) | 主路线图、资源索引、学习原则(本文件) |
- | [index.html](index.html) | 交互式学习页:Stage 导航、资源卡片、进度勾选 |
- | [stage-1/](stage-1/) … [stage-9/](stage-9/) | 分阶段可运行代码与分步教程 |
- **仓库结构**
- ```text
- Agent-Learning-Hub/
- index.html # 交互式学习页
- README.md # 主路线图(本文件)
- stage-1/ # 最小 agent loop(Python,6 步)
- stage-2/ # RAG + 记忆(Python,7 步)
- stage-3/claude-code-docs/ # Claude Code 源码 12 章导读
- stage-4/ # Multi-agent coordination(pipeline / supervisor)
- stage-5/ # Skills 能力打包(4 步 + smoke test)
- stage-6/ # Browser agent(Playwright + 安全边界)
- stage-7/ # Eval / trace / 安全门禁
- stage-8/ # 可部署 CLI Agent(trace / 安全 / 成本上限)
- stage-9/ # 上下文压缩与记忆(compaction + memory 最小实现)
- skills/teach/ # AI 导师 skill(本仓库自带,学习时直接使用)
- docs/learn/ # 专题阅读笔记(A2A、架构对照等)
- scripts/ # bootstrap, progress CLI, skill scaffold
- ```
- ## Agent 框架一张图
- Agent 不只是一段「调模型 + 调工具」的脚本。工程化后,通常会拆成几层——本仓库 Stage 1–8 也是按这个顺序递进:
- ```mermaid
- flowchart TB
- subgraph L1["① 应用"]
- APP["单 Agent 任务 / 多 Agent 编排 / 人机协同"]
- end
- subgraph L2["② 运行时"]
- SVC["会话 · 任务 · 权限"]
- ENG["推理循环 · 工具调用 · 重试降级"]
- EVT["事件流 · 人工介入"]
- WS["沙箱 / 本地 / 容器执行环境"]
- end
- subgraph L3["③ 模型与协议"]
- MDL["LLM · 语音 · 多模型路由"]
- PRT["Tool / MCP · A2A · 宿主 UI 协议"]
- end
- subgraph L4["④ 数据"]
- MEM["短期上下文 · 长期记忆 · RAG 检索"]
- STO["DB · 向量库 · 对象存储"]
- end
- subgraph L5["⑤ 工程底座"]
- OBS["Trace · Eval · 日志 · 成本监控"]
- DEP["网关 · 消息 · 配置 · 部署"]
- end
- L1 --> L2 --> L3
- L2 --> L4
- L2 --> L5
- ```
- | 层 | 核心问题 | 本仓库入口 |
- | --- | --- | --- |
- | 应用 | 解决什么任务、几个 Agent 协作 | [stage-6/](stage-6/) Browser · [stage-8/](stage-8/) CLI Agent |
- | 运行时 | 怎么循环推理、在哪执行、谁有权做什么 | [stage-1/](stage-1/) loop · [stage-3/](stage-3/) harness 导读 |
- | 模型与协议 | 接哪家模型、工具怎么标准化 | Stage 1 工具调用 · [stage-5/](stage-5/) Skills / MCP |
- | 数据 | 上下文怎么控、知识从哪来 | [stage-2/](stage-2/) RAG + 记忆 |
- | 工程底座 | 能不能上线、出了问题怎么查 | [stage-7/](stage-7/) Eval · trace · 安全门禁 |
- 先跑通 **② 运行时**(Stage 1),再补 **④ 数据** 和 **⑤ 工程底座**;不要跳步直接堆多 Agent 模板。
- ## Maintainer
- Originally curated by [陈思州](https://github.com/jjyaoao) (Datawhale 成员) <a href="https://www.xiaohongshu.com/user/profile/67b9cc34000000000e013517" target="_blank"><img alt="Static Badge" src="https://img.shields.io/badge/Rednote-小红书-e93c49"></a>
- ## Contributors(我是谁?)
- | Contributor | About | Contribution |
- | --- | --- | --- |
- | [KFC_LLM](https://github.com/kngwyc3) | 小红书同名,Agent 开发分享博主 | [stage-1/](stage-1/)–[stage-8/](stage-8/) 分步代码与实践(agent loop、RAG、Claude Code 导读、Skills、Browser agent、Eval、可部署 CLI Agent) |
- > 本仓库 Fork 自 [datawhalechina/Agent-Learning-Hub](https://github.com/datawhalechina/Agent-Learning-Hub),由 [kngwyc3/Agent-Learning-Hub](https://github.com/kngwyc3/Agent-Learning-Hub) 维护学习代码与实践笔记。
- ## How To Use
- - 打开 [index.html](index.html) 浏览 Stage 导航和资源卡片,或在本地 `python -m http.server` 后访问。
- - 如果你是新手:按「Learning Todo List」从上到下做,每完成一项就打勾;Stage 1–2 有分步代码可直接跑。
- - 如果你已经会 LLM 应用:从 Stage 2 或 Stage 3 开始,重点补 Agent loop、工具调用、评测和工程化。
- - 如果你想做项目:直接看「Project Ladder」,每一档做一个可运行作品。
- - 如果你只想找资料:看「Curated Resources」,优先读官方文档和经典论文。
- ### 使用 AI 协助学习
- 本仓库提供了一个 `teach` skill(位于 [skills/teach/](skills/teach/)),你可以将其加载到你的 AI Agent(如 Claude Code、Cursor、CodeBuddy 等)中,让 AI 充当你的私人导师:
- - **告知 Agent 加载 `skills/teach/SKILL.md`**,它就能按照最佳教学方法,针对你的知识背景和兴趣,提供结构化的课程、交互式练习和即时反馈。
- - 使用方式:告诉你的 AI Agent "请加载 skills/teach/SKILL.md 来教我学习本仓库的内容",Agent 会以知识-技能-智慧的递进方式引导你学习 Agent 开发的每一个阶段。
- - 使用前,你也可以先创建一个 `MISSION.md` 记录学习目标,帮助 Agent 更精准地定制内容。
- **推荐学习路径(有代码的阶段)**
- ```bash
- # Stage 1:最小 agent loop
- cd stage-1 && pip install -r requirements.txt && python step01_chat.py
- # Stage 2:RAG + 记忆
- cd stage-2 && pip install -r requirements.txt && python step01_memory_layers.py
- # Stage 5:Skills
- cd stage-5 && python step01_boundaries.py
- # Stage 6:Browser agent(需 Playwright)
- cd stage-6 && pip install -r requirements.txt && python step01_validate_url.py https://example.com
- # Stage 7:Eval + 安全门禁
- cd stage-7 && python step01_load_tasks.py && python step02_run_eval.py
- ```
- ## What To Learn Now
- Agent 领域变化很快。当前更值得投入的不是老式“角色扮演多 agent 框架”,而是这些更贴近真实生产力的方向:
- | Priority | Learn | Why |
- | --- | --- | --- |
- | 1 | Claude Code / Codex-style coding agents | 真实代码库、shell、文件编辑、测试、权限、上下文压缩,是最好的 agent 工程样本。 |
- | 2 | Agent harness engineering | agent 的能力很大一部分来自 harness:工具协议、权限、状态、反馈、回放、CI、评测。 |
- | 3 | OpenClaw / Hermes-style personal agents | 长运行、本地优先、跨应用、记忆、skills、消息入口,更像“个人操作系统”。 |
- | 4 | Skills / MCP / A2A / ACP | skills 负责能力复用,MCP 连接工具,A2A 连接 agent,ACP 连接宿主应用。 |
- | 5 | Evaluation and safety | 没有 eval、trace、权限边界的 agent 只能算 demo。 |
- 不建议把精力重押在已经泛化成模板的老式 crew/role-play 框架上。它们可以了解,但不应成为主线。
- ## Learning Todo List
- ### Stage 0: Understand What An Agent Is
- - [ ] 区分 chatbot、workflow、agent、multi-agent。
- - [ ] 理解 agent 的基本循环:observe -> think -> act -> observe。
- - [ ] 明白什么时候不该用 agent:任务可预测、流程稳定、普通脚本能解决时,agent 反而增加不确定性。
- - [ ] 读完 [Anthropic: Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)。
- - [ ] 读完 [OpenAI: A practical guide to building agents](https://openai.com/business/guides-and-resources/a-practical-guide-to-building-ai-agents/)。
- 产出:写一页短笔记,回答「我的场景为什么需要 agent,而不是普通 workflow?」
- ### Stage 1: Build A Minimal Agent Loop
- - [ ] 会用一个 LLM API 完成普通对话。
- - [ ] 会让模型输出结构化 JSON。
- - [ ] 会定义一个工具函数,例如 search、calculator、read_file。
- - [ ] 会解析模型的 tool call / function call。
- - [ ] 会执行工具,并把工具结果喂回模型。
- - [ ] 会给 agent loop 加最大步数、超时和错误处理。
- 推荐阅读:
- - [OpenAI Function Calling](https://platform.openai.com/docs/guides/function-calling)
- - [Gemini API Function Calling](https://ai.google.dev/gemini-api/docs/function-calling)
- - [Claude Tool Use](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview)
- 产出:一个 50-150 行的最小 agent,可以选择工具、执行工具、返回最终答案。
- **分步代码教程**:[stage-1/](stage-1/)(Python,6 步递增 + 手写练习标记)
- ### Stage 2: Learn Tool Use, RAG, And Memory
- - [ ] 会做检索增强生成:chunk、embed、retrieve、answer with citations。
- - [ ] 会把搜索、数据库、文件、浏览器、代码执行接成工具。
- - [ ] 会区分短期上下文、会话记忆、长期记忆。
- - [ ] 会处理工具失败、空结果、重复调用、幻觉引用。
- - [ ] 会让 agent 在回答里给出来源或证据。
- 推荐阅读:
- - [LlamaIndex Agents](https://docs.llamaindex.ai/en/stable/use_cases/agents/)
- - [LangChain Docs](https://docs.langchain.com/)
- - [Gemini API Code Execution](https://ai.google.dev/gemini-api/docs/code-execution)
- - [Model Context Protocol](https://modelcontextprotocol.io/)
- 开源项目参考:
- | Project | Why It Fits Stage 2 |
- | --- | --- |
- | [GPT Researcher](https://github.com/assafelovic/gpt-researcher) | 最接近“资料研究助手”的成品:搜索、抓取、筛选、引用、生成长报告。 |
- | [Open Deep Research](https://github.com/langchain-ai/open_deep_research) | LangGraph 写的 deep research 示例,适合学多轮搜索、状态管理和引用输出。 |
- | [STORM](https://github.com/stanford-oval/storm) | Stanford OVAL 的研究写作系统,适合学 outline、question asking、多视角资料综合。 |
- | [Khoj](https://github.com/khoj-ai/khoj) | 个人 second brain,适合学本地文档、网页、语义搜索和长期记忆。 |
- | [Onyx](https://github.com/onyx-dot-app/onyx) | 企业级 RAG/search assistant,适合学 connectors、hybrid search、权限和生产化。 |
- | [AnythingLLM](https://github.com/Mintplex-Labs/anything-llm) | 本地 RAG + agents 产品,适合初学者快速理解完整应用形态。 |
- | [RAGFlow](https://github.com/infiniflow/ragflow) | 文档理解型 RAG 引擎,适合学 ingestion、chunking、retrieval、grounded answer。 |
- | [mem0](https://github.com/mem0ai/mem0) | 记忆层组件,适合学如何给 agent 加长期 memory。 |
- | [Letta](https://github.com/letta-ai/letta) | 面向 stateful agents 的 memory/context 平台,适合学上下文管理。 |
- 产出:一个资料研究助手,输入主题后自动搜索、筛选、总结并输出引用链接。
- **分步代码教程**:[stage-2/](stage-2/)(Python,RAGFlow + mem0 + Letta,7 步递增 + 手写练习标记)
- ### Stage 3: Study One Modern Agent Harness
- 先选一个现代 agent 系统学深。这里的重点不是“框架 API 怎么调”,而是它如何组织工具、上下文、权限、状态、日志、子任务和反馈。
- | System | Best For | Learn This If You Want To |
- | --- | --- | --- |
- | [Claude Code Docs](https://code.claude.com/docs/en/overview) | Coding agent product | 学真实 coding agent 的 CLI、工具、权限、hooks、subagents、MCP。 |
- | [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) | From-scratch agent harness | 从 0 到 1 复刻 Claude Code-like harness。 |
- | [claw0](https://github.com/shareAI-lab/claw0) | From-scratch OpenClaw gateway | 从 agent loop 一路构建 session、channel、gateway、memory、heartbeat、delivery、resilience、concurrency。 |
- | [hello-agents](https://github.com/datawhalechina/hello-agents) | Chinese agent tutorial | 从零开始构建智能体,适合系统补 Agent 原理与实践。 |
- | [OpenClaw](https://github.com/openclaw/openclaw) | Local-first personal agent | 学本地长运行 agent、skills、消息入口、系统工具和安全边界。 |
- | [Hermes Agent](https://github.com/NousResearch/hermes-agent) | Self-hosted growing agent | 学长期记忆、skills、toolsets、多平台消息网关和迁移能力。 |
- | [CyberClaw](https://github.com/ttguy0707/CyberClaw) | Transparent agent architecture | 学全行为审计、两段式安全调用、双水位记忆和心跳任务。 |
- | [LangGraph](https://langchain-ai.github.io/langgraph/) | Stateful graph orchestration | 学状态图、可恢复执行和可控编排。 |
- - [ ] 读懂一个 agent harness 的目录结构。
- - [ ] 找出它的 agent loop、tool registry、permission gate、session store、context compaction。
- - [ ] 跑通它的最小示例,并加一个你自己的工具。
- - [ ] 观察一次完整 trace,解释每一步为什么发生。
- - [ ] 把同一个任务分别用「裸 agent loop」和「harness」实现,对比差异。
- 产出:一个可调试的 agent harness demo,包含 README、运行步骤、示例输入输出和失败记录。
- **Claude Code 架构流程图**:
- 
- **Claude Code 源码导读**:[stage-3/claude-code-docs/](stage-3/claude-code-docs/)(12 章:Tool 系统、Query 引擎、权限、MCP、状态管理、CLI 入口等)
- | 章节 | 重点 |
- | --- | --- |
- | [06-权限系统.md](stage-3/claude-code-docs/06-权限系统.md) | PermissionMode、规则引擎、权限检查链路 |
- | [01-Tool系统.md](stage-3/claude-code-docs/01-Tool系统.md) | Tool 接口、buildTool、BashTool |
- | [03-Agent系统.md](stage-3/claude-code-docs/03-Agent系统.md) | 子 Agent、Fork Worktree、蜂群协作 |
- ### Stage 4: Multi-Agent Is Coordination, Not Magic
- - [ ] 理解 planner / executor / reviewer / critic / router 等常见角色。
- - [ ] 学会用 supervisor 或 graph 管理多 agent,而不是让 agent 随便聊天。
- - [ ] 会定义每个 agent 的职责边界、输入输出 schema、停止条件。
- - [ ] 会处理循环、争论、任务漂移、上下文膨胀。
- - [ ] 会判断什么时候单 agent 更好。
- 推荐阅读:
- - [Claude Code Subagents](https://code.claude.com/docs/en/sub-agents)
- - [Claude Code Hooks](https://code.claude.com/docs/en/hooks)
- - [Google Agent Development Kit](https://google.github.io/adk-docs/)
- - [Agent2Agent Protocol](https://google-a2a.github.io/A2A/specification/)
- - [Agent Client Protocol](https://agentclientprotocol.com/)
- 产出:一个小型多 agent 系统,例如 research -> write -> review -> revise。
- **分步代码教程**:[stage-4/](stage-4/)(Python,角色契约 + supervisor router + trace,5 步递增 + 手写练习标记)
- ### Stage 5: Learn Skills, Protocols, And Capability Packaging
- 现代 agent 的能力不只来自模型和工具,也来自可复用的 skills。一个好的 skill 像一份小型操作手册:告诉 agent 什么时候使用、怎么使用、需要哪些脚本/资源、如何验证结果。
- - [ ] 理解 Skill 和 Tool 的区别:tool 是可调用接口,skill 是可复用流程知识。
- - [ ] 理解 Skill 和 Prompt 的区别:prompt 通常是一次性指令,skill 是可发现、可版本化、可分发的能力包。
- - [ ] 理解 Skill 和 MCP 的区别:MCP 接入外部工具/数据源,skill 告诉 agent 如何完成一类任务。
- - [ ] 阅读 Claude Code Skills 的文件结构和触发机制。
- - [ ] 阅读 OpenClaw Skills 的加载、作用域和安全边界。
- - [ ] 写一个最小 `SKILL.md`,包含 name、description、何时使用、步骤、验收标准。
- - [ ] 给 skill 加一个脚本或模板文件,并说明 agent 什么时候才需要加载它。
- - [ ] 给 skill 写一个 smoke test,验证它是否真的提升任务成功率。
- 推荐阅读:
- - [Claude Code Skills](https://code.claude.com/docs/en/skills)
- - [Claude Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
- - [Claude Code Agent SDK Skills](https://code.claude.com/docs/en/agent-sdk/skills)
- - [OpenClaw Skills](https://github.com/openclaw/openclaw/blob/main/docs/tools/skills.md)
- - [Model Context Protocol](https://modelcontextprotocol.io/)
- - [Agent2Agent Protocol](https://google-a2a.github.io/A2A/specification/)
- - [Agent Client Protocol](https://agentclientprotocol.com/)
- 产出:一个可复用 skill,例如 code-review、research-report、migration-helper、pdf-extraction 或 release-note-writer。
- **分步代码教程**:[stage-5/](stage-5/)(Skills / 协议 / 能力打包,4 步递增 + smoke test)
- ```bash
- cd stage-5
- python step01_boundaries.py # Skill vs Tool / Prompt / MCP
- python step02_load_skill.py # 加载并校验 SKILL.md
- python step03_validate_report.py # 验收报告格式
- python step04_run_smoke_cases.py # smoke test
- ```
- | 产出 | 路径 |
- | --- | --- |
- | 示例 skill | `stage-5/my-skill/SKILL.md` |
- | 报告模板 | `stage-5/my-skill/templates/review_report.md` |
- | smoke 脚本 | `stage-5/my-skill/scripts/smoke_check.py` |
- ### Stage 6: Browser And Computer-Use Agents
- - [ ] 理解 browser agent 和普通 API tool 的区别。
- - [ ] 会用 Playwright 或 browser-use 做网页观察和点击。
- - [ ] 会给浏览器操作加安全限制:不登录敏感账号、不越权、不绕过平台规则。
- - [ ] 会处理页面变化、弹窗、加载失败、元素定位失败。
- - [ ] 会记录截图、DOM、动作日志,方便复盘。
- 推荐阅读:
- - [Claude Computer Use](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/computer-use-tool)
- - [browser-use](https://github.com/browser-use/browser-use)
- - [WebArena](https://arxiv.org/abs/2307.13854)
- - [VisualWebArena](https://arxiv.org/abs/2401.13649)
- 产出:一个只操作公开网页的 browser agent,例如打开网页、提取信息、生成摘要。
- **分步代码教程**:[stage-6/](stage-6/)(Playwright,公开网页操作 + action log + 安全边界)
- ```bash
- cd stage-6
- pip install -r requirements.txt && playwright install chromium
- python step01_validate_url.py https://example.com # URL 安全校验(无需 Playwright)
- python step02_observe_page.py https://example.com # 页面观察
- python step03_run_agent.py https://example.com # 完整 browser agent
- ```
- | 产出 | 路径 |
- | --- | --- |
- | Browser agent | `stage-6/browser-agent/agent.py` |
- | 安全策略 | `stage-6/browser-agent/policies.md` |
- | 公开测试用例 | `stage-6/browser-agent/tests/public_cases.md` |
- ### Stage 7: Evaluation, Observability, And Safety
- - [ ] 为 agent 准备固定测试集,而不是只看 demo。
- - [ ] 记录成功率、失败原因、工具调用次数、成本、延迟。
- - [ ] 会看 trace,知道失败发生在 prompt、工具、检索、模型还是状态管理。
- - [ ] 给危险工具加人工确认,例如发邮件、删文件、付款、发布内容。
- - [ ] 了解 prompt injection、data exfiltration、tool abuse 等风险。
- - [ ] 会用回归测试防止 prompt 或工具改动后能力退化。
- 推荐阅读:
- - [OpenAI Evals](https://platform.openai.com/docs/guides/evals)
- - [OpenAI Agent platform](https://openai.com/agent-platform/)
- - [LangSmith](https://docs.smith.langchain.com/)
- - [AgentBench](https://arxiv.org/abs/2308.03688)
- - [SWE-bench](https://arxiv.org/abs/2310.06770)
- 产出:一个 agent eval 表格,至少包含 20 个任务、期望结果、实际结果、失败分类。
- **分步代码教程**:[stage-7/](stage-7/)(eval 数据集、trace、失败分类、安全门禁和回归测试)
- ```bash
- cd stage-7
- python step01_load_tasks.py # 加载 20 条 eval 任务
- python step02_run_eval.py # 运行 eval,写入 results.csv + trace
- python step03_safety_gate.py # 安全门禁:block / approval / allow
- ```
- | 产出 | 路径 |
- | --- | --- |
- | Eval 任务集(20 条) | `stage-7/evals/tasks.csv` |
- | Eval 结果 | `stage-7/evals/results.csv` |
- | 失败分类 | `stage-7/evals/failure_taxonomy.md` |
- | 安全门禁 | `stage-7/safety_gate.py` |
- | 安全策略 | `stage-7/safety/policy.md` |
- **专题文章**:[Claude Code 权限控制原理与 Stage 7 安全门禁对照](stage-7/docs/claude-code-permissions.md)
- ### Stage 8: Ship A Real Agent
- - [ ] 有明确用户、明确任务、明确成功标准。
- - [ ] 有日志、trace、错误重试、超时、成本上限。
- - [ ] 有权限边界和人工确认机制。
- - [ ] 有部署方式:CLI、Web app、Slack bot、GitHub Action 或后台任务。
- - [ ] 有 README:怎么运行、怎么配置 key、怎么扩展工具、有哪些限制。
- 产出:一个别人能 clone 下来跑的 agent 项目。
- **分步代码教程**:[stage-8/](stage-8/)(CLI agent、安全门禁、trace、成本上限、smoke test)
- ```bash
- cd stage-8
- python3 -m venv .venv && source .venv/bin/activate
- pip install -r requirements.txt
- cp .env.example .env # 填入 OPENAI_API_KEY
- python step01_smoke.py # 无 API key 可先跑
- python cli.py "读取 stage-1/notes.txt 并总结"
- ```
- | 产出 | 路径 |
- | --- | --- |
- | 配置模板 | `stage-8/.env.example` |
- | Agent loop | `stage-8/agent.py` |
- | CLI 入口 | `stage-8/cli.py` |
- | 安全门禁 | `stage-8/safety.py` |
- | Trace 日志 | `stage-8/traces/*.jsonl`(运行后生成) |
- | Smoke test | `stage-8/step01_smoke.py` |
- ### Stage 9: Context Compaction And Memory
- Agent 跑得越久,上下文就是瓶颈。上下文太少会忘事,太多会撑爆 token 上限、变贵、质量下降。这个阶段专攻「让 agent 记住什么、怎么压缩对话」。
- - [ ] 理解 context window 与 token 成本的关系:为什么长会话必须压缩。
- - [ ] 区分短期上下文(当前会话)、会话记忆(本轮任务)、长期记忆(跨任务持久化)。
- - [ ] 理解 compaction 的两种触发:主动(每轮常规压缩)与被动(413 上限时紧急压缩,对照 cc流程图 里的 Reactive Compact 节点)。
- - [ ] 会做滑动窗口 / 摘要式压缩:保留最近 N 轮 + 关键信息摘要。
- - [ ] 会给压缩加「不可丢弃」锚点:系统约束、用户明确要求、工具 schema。
- - [ ] 会评估压缩质量:压缩后任务成功率是否下降、关键信息是否丢失。
- - [ ] 把「裸 agent loop」加上 compaction + memory,对比加之前的长任务表现。
- 产出:一个能跑 50+ 轮不丢关键信息的 agent,带 memory 读写与压缩日志。
- 推荐阅读:
- - [Anthropic: 有效的上下文工程](https://www.anthropic.com/engineering/effective-context-engineering) — 上下文工程的核心原则:该放什么、该丢掉什么。
- - [Claude Code 官方文档(context / memory 机制)](https://code.claude.com/docs/en/overview) — 了解 Claude Code 的上下文管理与记忆设计。
- - [Letta 文档](https://docs.letta.com/) — stateful agent 的 memory / context 管理平台。
- - [mem0 文档](https://docs.mem0.ai/) — 记忆层组件,自动抽取与检索长期记忆。
- - [Reflexion](https://arxiv.org/abs/2303.11366) — 通过语言反馈做自我改进与记忆。
- 开源项目参考:
- | Project | Why It Fits Stage 9 |
- | --- | --- |
- | [mem0](https://github.com/mem0ai/mem0) | 记忆层组件,适合学长期 memory 的抽取、去重与检索。 |
- | [Letta](https://github.com/letta-ai/letta) | 面向 stateful agents 的 memory / context 管理平台。 |
- | [claw0](https://github.com/shareAI-lab/claw0) | 从 agent loop 一路构建 memory、heartbeat 与 context compaction。 |
- | [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) | 从零复刻 Claude Code 的 compaction 与 context 管理机制。 |
- 对照 [Claude Code 架构流程图](stage-3/cc流程图.jpg) 中的 Context Compact / Reactive Compact 节点,可以理解压缩在真实 harness 里的触发时机。
- ## Project Ladder
- | Level | Project | What You Learn |
- | --- | --- | --- |
- | 1 | Calculator Agent | 最小 tool call loop |
- | 2 | Web Research Agent | 搜索、筛选、引用、总结 |
- | 3 | PDF QA Agent | RAG、chunk、retrieval、citation |
- | 4 | Coding Review Agent | 读取 diff、风险排序、测试建议 |
- | 5 | Browser Agent | 页面观察、点击、提取、失败恢复 |
- | 6 | Claude Code-like Nano Agent | shell、文件编辑、权限、session、compact |
- | 7 | OpenClaw-like Gateway | channel、routing、session、memory、heartbeat、delivery |
- | 8 | Reusable Skill Pack | SKILL.md、脚本、模板、触发条件、smoke test |
- | 9 | Multi-Agent Writer | planner、writer、reviewer 协作 |
- | 10 | Personal Agent | OpenClaw/Hermes-style 记忆、skills、消息入口 |
- | 11 | Production Harness | evals、trace、权限、CI、runner、回放 |
- ## Curated Resources
- ### Official Guides And Blogs
- | Resource | Why It Matters |
- | --- | --- |
- | [Anthropic: Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) | Agent 设计入门必读,讲清 workflow 和 agent 的边界。 |
- | [Claude Code Overview](https://code.claude.com/docs/en/overview) | 当前最值得研究的 coding agent 产品文档入口。 |
- | [Claude Code Subagents](https://code.claude.com/docs/en/sub-agents) | 学任务拆分、上下文隔离、专用子代理。 |
- | [Claude Code Hooks](https://code.claude.com/docs/en/hooks) | 学如何拦截、校验和扩展 agent 行为。 |
- | [Claude Code GitHub Actions](https://docs.claude.com/en/docs/claude-code/github-actions) | 学 coding agent 如何进入 PR / issue 工作流。 |
- | [Claude Code Advanced Patterns](https://resources.anthropic.com/hubfs/Claude%20Code%20Advanced%20Patterns_%20Subagents%2C%20MCP%2C%20and%20Scaling%20to%20Real%20Codebases.pdf) | Anthropic 官方材料,覆盖 subagents、MCP 和真实代码库扩展。 |
- | [OpenAI: A practical guide to building agents](https://openai.com/business/guides-and-resources/a-practical-guide-to-building-ai-agents/) | 面向产品和工程团队的 agent 落地指南。 |
- | [OpenAI: New tools for building agents](https://openai.com/index/new-tools-for-building-agents/) | Responses API、Agents SDK、工具和 tracing 的官方介绍。 |
- | [OpenAI Agents SDK](https://platform.openai.com/docs/guides/agents-sdk/) | OpenAI 原生 agent 开发入口。 |
- | [Claude Tool Use](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview) | Claude 工具调用机制。 |
- | [Claude Computer Use](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/computer-use-tool) | 电脑操作类 agent 的官方参考。 |
- | [Gemini Function Calling](https://ai.google.dev/gemini-api/docs/function-calling) | Gemini 工具调用官方文档。 |
- | [Gemini Code Execution](https://ai.google.dev/gemini-api/docs/code-execution) | Gemini 代码执行工具。 |
- | [Google Agent Development Kit](https://google.github.io/adk-docs/) | Google 的 agent 开发框架。 |
- | [Model Context Protocol](https://modelcontextprotocol.io/) | Agent 连接工具和数据源的重要协议。 |
- ### Project Map
- 项目不要按 star 数乱读,建议按学习目的分层:
- | Layer | Study These | Learn |
- | --- | --- | --- |
- | Build From Scratch | [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code), [claw0](https://github.com/shareAI-lab/claw0), [hello-agents](https://github.com/datawhalechina/hello-agents) | agent loop、tool registry、session、context compaction、gateway、trace、subagents。 |
- | Personal / Always-On Agents | [OpenClaw](https://github.com/openclaw/openclaw), [Hermes Agent](https://github.com/NousResearch/hermes-agent), [CyberClaw](https://github.com/ttguy0707/CyberClaw) | 长运行、skills、记忆、消息入口、权限、安全审计。 |
- | Coding Agents | [Claude Code](https://code.claude.com/docs/en/overview), [OpenAI Codex](https://github.com/openai/codex), [OpenCode](https://github.com/opencode-ai/opencode), [OpenHands](https://github.com/All-Hands-AI/OpenHands), [SWE-agent](https://github.com/SWE-agent/SWE-agent), [pi](https://github.com/earendil-works/pi) | 真实代码库编辑、shell、测试、sandbox、PR 工作流。 |
- | Deep Research / RAG Agents | [DeerFlow](https://github.com/bytedance/deer-flow), [LlamaIndex](https://docs.llamaindex.ai/) | 搜索、抓取、检索、rerank、引用、报告生成。 |
- | Tutorial Encyclopedias | [GenAI_Agents](https://github.com/NirDiamant/GenAI_Agents), [hello-agents](https://github.com/datawhalechina/hello-agents), [smolagents](https://github.com/huggingface/smolagents), [agents-towards-production](https://github.com/NirDiamant/agents-towards-production) | 横向看 ReAct、Plan-and-Execute、Multi-Agent、production patterns。 |
- | Browser / Multimodal Agents | [browser-use](https://github.com/browser-use/browser-use), [UI-TARS-desktop](https://github.com/bytedance/UI-TARS-desktop) | 浏览器/桌面操作、视觉理解、动作空间、失败恢复。 |
- ### Skills, Protocols, And Tooling
- | Concept | Learn From | What It Solves |
- | --- | --- | --- |
- | Skills | [Claude Code Skills](https://code.claude.com/docs/en/skills), [OpenClaw Skills](https://github.com/openclaw/openclaw/blob/main/docs/tools/skills.md) | 把一类任务的流程知识、脚本、模板和验收标准打包成可复用能力。 |
- | MCP | [Model Context Protocol](https://modelcontextprotocol.io/) | 让 agent 标准化连接外部工具、数据源和服务。 |
- | A2A | [Agent2Agent Protocol](https://google-a2a.github.io/A2A/specification/) | 让不同 agent 之间发现、通信和协作。 |
- | ACP | [Agent Client Protocol](https://agentclientprotocol.com/) | 让编辑器、终端、IDE、宿主应用和 agent 之间形成统一接口。 |
- | Skill Quality | [SWE-Skills-Bench](https://arxiv.org/abs/2603.15401), [Agent Skills analysis](https://arxiv.org/abs/2602.08004) | 评估 skills 是否真的提升成功率,而不是制造新的 prompt 噪声。 |
- ### Modern Agent Systems
- | System | Why It Is Useful |
- | --- | --- |
- | [Claude Code](https://code.claude.com/docs/en/overview) | 学 coding agent 的产品化形态:shell、文件、权限、hooks、subagents、MCP。 |
- | [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) | 从零构建 Claude Code-like nano agent,适合理解 harness engineering。 |
- | [claw0](https://github.com/shareAI-lab/claw0) | 从零构建 OpenClaw-like agent gateway,覆盖 channel、routing、session、memory、delivery、concurrency。 |
- | [hello-agents](https://github.com/datawhalechina/hello-agents) | 中文智能体系统教程,适合从零开始补齐 Agent 原理与实践。 |
- | [OpenClaw](https://github.com/openclaw/openclaw) | 本地优先的个人 agent,适合研究长运行 agent 和系统级工具调用。 |
- | [Hermes Agent](https://github.com/NousResearch/hermes-agent) | 自托管、长期记忆、skills、消息网关和 toolsets。 |
- | [CyberClaw](https://github.com/ttguy0707/CyberClaw) | 透明可控 agent 架构,适合研究审计、两段式执行和安全边界。 |
- | [DeerFlow](https://github.com/bytedance/deer-flow) | 字节开源 long-horizon SuperAgent harness,适合研究 Deep Research、报告、slides、网页、图像和视频生成。 |
- | [smolagents](https://github.com/huggingface/smolagents) | Hugging Face 轻量 agent 框架,CodeAgent 思路值得研究。 |
- | [LangGraph](https://langchain-ai.github.io/langgraph/) | 状态图和可控 agent 编排,仍然值得作为工程基础学习。 |
- | [Qwen-Agent](https://github.com/QwenLM/Qwen-Agent) | 国产模型生态里的工具调用、RAG、MCP agent 框架。 |
- | [Pydantic AI](https://pydantic.dev/docs/ai/core-concepts/agent/) | 类型安全和结构化输出,适合生产 Python agent。 |
- | [pi](https://github.com/earendil-works/pi) | AI agent toolkit(TypeScript),含 coding agent CLI、agent core、统一多提供商 LLM API 和 TUI 库,支持自扩展。 |
- ### Legacy Or Optional Frameworks
- 这些项目仍有参考价值,但不建议作为当前学习主线。
- | Framework | Note |
- | --- | --- |
- | [CrewAI](https://docs.crewai.com/) | 可了解 role/task/crew 抽象,但很多场景已经被更强的 coding agent / harness 形态覆盖。 |
- | [AutoGen](https://microsoft.github.io/autogen/) | 多 agent 对话框架经典项目,适合了解历史和论文,不必重押。 |
- | [LangChain Agents](https://docs.langchain.com/) | 生态仍重要,但建议重点转向 LangGraph 和具体工程模式。 |
- ### Papers
- | Paper | Topic |
- | --- | --- |
- | [ReAct](https://arxiv.org/abs/2210.03629) | Reasoning + acting 的基础范式。 |
- | [Toolformer](https://arxiv.org/abs/2302.04761) | 模型学习何时调用工具。 |
- | [Reflexion](https://arxiv.org/abs/2303.11366) | 语言反馈和自我改进。 |
- | [Generative Agents](https://arxiv.org/abs/2304.03442) | 记忆、反思、规划驱动的模拟 agent。 |
- | [Voyager](https://arxiv.org/abs/2305.16291) | 开放世界中的长期学习 agent。 |
- | [AutoGen](https://arxiv.org/abs/2308.08155) | 多 agent 对话框架。 |
- | [AgentBench](https://arxiv.org/abs/2308.03688) | Agent 能力评测。 |
- | [WebArena](https://arxiv.org/abs/2307.13854) | 真实网页环境下的 agent benchmark。 |
- | [SWE-bench](https://arxiv.org/abs/2310.06770) | 真实 GitHub issue 修复评测。 |
- | [SWE-agent](https://arxiv.org/abs/2405.15793) | 软件工程 agent 的 agent-computer interface。 |
- | [Dive into Claude Code](https://arxiv.org/abs/2604.14228) | 从系统设计角度分析 Claude Code 这类 coding agent 的 harness、权限、压缩和扩展机制。 |
- | [AI Harness Engineering](https://arxiv.org/abs/2605.13357) | 把 harness 作为 agent 能力来源来研究。 |
- | [Configuring Agentic AI Coding Tools](https://arxiv.org/abs/2602.14690) | 对 Claude Code、Codex、Gemini、Cursor 等 coding tools 的配置机制分析。 |
- | [Your Agent, Their Asset](https://arxiv.org/abs/2604.04759) | OpenClaw 等本地 agent 的真实安全风险分析。 |
- ### GitHub Repositories
- | Repo | Why It Is Useful |
- | --- | --- |
- | [datawhalechina/hello-agents](https://github.com/datawhalechina/hello-agents) | 中文智能体系统教程,从零开始构建智能体。 |
- | [shareAI-lab/learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) | Bash is all you need,从 0 到 1 学 Claude Code-like agent harness。 |
- | [shareAI-lab/claw0](https://github.com/shareAI-lab/claw0) | 从 0 到 1 学 OpenClaw-like gateway,10 个渐进章节覆盖 agent loop 到 concurrency。 |
- | [openclaw/openclaw](https://github.com/openclaw/openclaw) | 研究本地个人 agent、skills、长运行任务、系统工具和权限边界。 |
- | [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) | 研究自托管 agent、长期记忆、skills、toolsets、多平台消息网关。 |
- | [ttguy0707/CyberClaw](https://github.com/ttguy0707/CyberClaw) | 研究透明 agent、安全审计、两段式执行、双水位记忆和心跳任务。 |
- | [bytedance/deer-flow](https://github.com/bytedance/deer-flow) | Deep Research / long-horizon agent,适合学习搜索、报告生成、沙箱、memory、skills、subagents、message gateway。 |
- | [NirDiamant/GenAI_Agents](https://github.com/NirDiamant/GenAI_Agents) | 综合教程库,适合横向比较 ReAct、Plan-and-Execute、Multi-Agent 等实现方式。 |
- | [NirDiamant/agents-towards-production](https://github.com/NirDiamant/agents-towards-production) | production-grade agent 教程库,适合补工程化组件。 |
- | [huggingface/smolagents](https://github.com/huggingface/smolagents) | 轻量 CodeAgent 风格框架,适合研究“让模型写代码执行动作”的范式。 |
- | [openai/codex](https://github.com/openai/codex) | OpenAI 开源 coding agent CLI,适合研究 sandbox、approval、CLI 产品形态。 |
- | [opencode-ai/opencode](https://github.com/opencode-ai/opencode) | 终端优先的开源 coding agent,适合对照 Claude Code / Codex。 |
- | [langchain-ai/langgraph](https://github.com/langchain-ai/langgraph) | 状态图和可控 agent 编排。 |
- | [openai/openai-agents-python](https://github.com/openai/openai-agents-python) | OpenAI Agents SDK Python。 |
- | [QwenLM/Qwen-Agent](https://github.com/QwenLM/Qwen-Agent) | Qwen 生态 agent 框架。 |
- | [browser-use/browser-use](https://github.com/browser-use/browser-use) | 浏览器 agent 实战。 |
- | [bytedance/UI-TARS-desktop](https://github.com/bytedance/UI-TARS-desktop) | 多模态桌面 agent stack,适合研究视觉 UI 操作。 |
- | [SWE-agent/SWE-agent](https://github.com/SWE-agent/SWE-agent) | 软件工程 agent。 |
- | [All-Hands-AI/OpenHands](https://github.com/All-Hands-AI/OpenHands) | 开源 coding agent。 |
- | [microsoft/ai-agents-for-beginners](https://github.com/microsoft/ai-agents-for-beginners) | 系统化入门课程。 |
- | [jjyaoao/HelloAgents](https://github.com/jjyaoao/HelloAgents) | 基于 OpenAI 原生 API 的生产级多智能体框架,覆盖 ToolResponse、上下文工程、会话持久化、子代理、TraceLogger 等。 |
- | [earendil-works/pi](https://github.com/earendil-works/pi) | TypeScript 写的 AI agent toolkit,含 pi-coding-agent CLI、pi-agent-core 运行时、pi-ai(统一多提供商 LLM API)、pi-tui(终端 UI 库),支持 Slack 机器人和 vLLM pods。 |
- ### Thoughtful Blogs
- | Blog | Why It Is Useful |
- | --- | --- |
- | [Lilian Weng: LLM Powered Autonomous Agents](https://lilianweng.github.io/posts/2023-06-23-agent/) | 经典长文,系统整理 agent 架构、记忆、规划和工具使用。 |
- | [Simon Willison: AI/LLM writing](https://simonwillison.net/tags/llms/) | 非常务实的 LLM 工程观察,适合补工程直觉。 |
- | [LangChain Blog](https://blog.langchain.com/) | LangGraph、LangSmith、agent 工程实践。 |
- | [Google Developers Blog: ADK](https://developers.googleblog.com/agent-development-kit-easy-to-build-multi-agent-applications/) | Google ADK 官方发布文章。 |
- ### Claude Code Study Path
- Claude Code 是当前最值得拆解的 coding agent 产品之一。推荐按“官方文档 -> 本仓库源码导读 -> 复刻项目 -> 架构解析 -> 工程对照”的顺序学习:
- - 读官方文档,理解 hooks、subagents、MCP、GitHub Actions、permissions。
- - 读本仓库 [stage-3/claude-code-docs/](stage-3/claude-code-docs/),按模块理解 Tool、Query、权限、MCP、状态管理。
- - 读 [Stage 7 权限对照文章](stage-7/docs/claude-code-permissions.md),把 CC 权限链路与 `safety_gate.py` 对齐。
- - 读公开分析论文,抽象出 agent harness 的设计空间。
- - 跟随 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) 从零复刻核心机制。
- - 对照 [hello-agents](https://github.com/datawhalechina/hello-agents)、[OpenClaw](https://github.com/openclaw/openclaw)、[Hermes Agent](https://github.com/NousResearch/hermes-agent) 这些开源项目,学习工程化实现。
- | Resource | Focus |
- | --- | --- |
- | [Claude Code Common Workflows](https://code.claude.com/docs/en/tutorials) | 官方工作流教程,适合学日常使用和项目协作。 |
- | [Claude Code Overview](https://code.claude.com/docs/en/overview) | 官方入口,理解产品能力和命令行工作方式。 |
- | [stage-3/claude-code-docs/](stage-3/claude-code-docs/) | 本仓库 12 章 Claude Code 源码导读(Tool、权限、MCP、Agent 系统等)。 |
- | [stage-7/docs/claude-code-permissions.md](stage-7/docs/claude-code-permissions.md) | CC 权限原理与 Stage 7 安全门禁对照。 |
- | [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) | 从零复刻 Claude Code-like agent,适合学 harness 最小实现。 |
- | [Claude Code 源码解析](https://claudecoding.dev/) | 中文架构解读,适合按模块理解实现思路。 |
- | [Claude Code 源码分析地图](https://code.claudecn.com/) | 用地图方式拆解 agent loop、工具、命令和多代理协作。 |
- | [Dive into Claude Code](https://arxiv.org/abs/2604.14228) | 从研究视角总结 Claude Code 的设计空间和 agent harness 模式。 |
- | [Agentic Education](https://arxiv.org/abs/2604.17460) | 用 Claude Code 学 Claude Code 的交互式课程思路。 |
- ## Learning Principles
- - Build first, then read deeper.
- - Prefer small reliable agents over impressive demos.
- - Use tools with strict schemas.
- - Add evals before you add more agents.
- - Trace every important run.
- - Treat multi-agent as a coordination problem.
- - Keep humans in the loop for risky actions.
- - Respect platform rules, copyrights, and data access boundaries.
- ## Contributing
- Good contributions are welcome. Please prefer:
- - official docs and official engineering blogs;
- - high-quality papers and benchmarks;
- - open-source repositories with runnable code;
- - serious technical blogs with original insight;
- - small projects that help learners practice one specific skill.
- Please avoid:
- - copied platform posts;
- - course ads without substantial content;
- - private or paywalled material;
- - scraping-oriented content that bypasses platform rules.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.