\documentclass[a4paper]{article}

% Basic packages
\usepackage[fontset=fandol]{ctex}
\usepackage{amsmath, amssymb}
\usepackage{graphicx}
\usepackage[margin=2.5cm]{geometry}
\usepackage[most]{tcolorbox}
\usepackage{etoolbox}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{booktabs}
\usepackage{subcaption}
\usepackage{float}

% Highlight boxes
\newtcolorbox{knowledgebox}[1]{
    enhanced, colback=blue!5!white, colframe=blue!75!black, colbacktitle=blue!75!black,
    coltitle=white, fonttitle=\bfseries, title=#1, attach boxed title to top left={yshift=-2mm, xshift=2mm},
    boxrule=1pt, sharp corners
}

\newtcolorbox{importantbox}[1]{
    enhanced, colback=yellow!10!white, colframe=yellow!80!black, colbacktitle=yellow!80!black,
    coltitle=black, fonttitle=\bfseries, title=#1, sharp corners
}

\newtcolorbox{warningbox}[1]{
    enhanced, colback=red!5!white, colframe=red!75!black, colbacktitle=red!75!black,
    coltitle=white, fonttitle=\bfseries, title=#1, sharp corners
}

% Listings
\lstset{
    language=Python,
    basicstyle=\ttfamily\small,
    keywordstyle=\color{blue},
    stringstyle=\color{red!60!black},
    commentstyle=\color{green!60!black},
    breaklines=true,
    frame=single,
    numbers=left,
    numberstyle=\tiny\color{gray},
    captionpos=b,
    extendedchars=false
}

% Front-page metadata
\newcommand{\notetitle}{Codex Skills 与 Tools 加载、Agent Runtime 全景}
\newcommand{\noteauthors}{基于公开课程资料整理}
\newcommand{\notedate}{2025}
\newcommand{\videochannel}{五道口纳什}
\newcommand{\videopublishdate}{2025}
\newcommand{\videoduration}{约 11 分钟}
\newcommand{\videourl}{}
\newcommand{\videocoverpath}{cover.jpg}
\newcommand{\repourl}{https://github.com/hqhq1025/ai-course-notes}


% Footer with repo info
\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhf{}
\fancyfoot[C]{\thepage}
\fancyfoot[R]{\footnotesize\color{gray}\href{\repourl}{AI Course Notes}}
\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0pt}

\begin{document}

\begin{titlepage}
\centering
{\Large 课程笔记\par}
\vspace{1.2cm}
{\huge\bfseries \notetitle\par}
\vspace{0.8cm}
{\large \noteauthors\par}
\vspace{0.3cm}
{\large \notedate\par}
\vspace{1.2cm}

\ifdefempty{\videocoverpath}{
{\small 请在生成笔记时填入视频封面图的本地路径。\par}
}{
\includegraphics[width=0.82\textwidth,height=0.45\textheight,keepaspectratio]{\videocoverpath}\par
}

\vfill
\begin{tcolorbox}[width=0.9\textwidth, colback=black!2!white, colframe=black!60, sharp corners]
\textbf{视频作者/频道}：\videochannel\par
\textbf{发布日期}：\videopublishdate\par
\textbf{视频时长}：\videoduration\par
\ifdefempty{\videourl}{}{
\textbf{视频链接}：\href{\videourl}{\nolinkurl{\videourl}}\par
}
\par
\textbf{项目主页}：\href{\repourl}{\nolinkurl{\repourl}}\par
\end{tcolorbox}
\end{titlepage}

\tableofcontents
\newpage

%% --- 正文内容开始 --- %%

\section{Modern AI Agents 的定义与特征}

\subsection{什么是 Modern AI Agent}

Codex、Claude Code、Gemini CLI、OpenAI Codex 等工具都属于 Modern AI Agent。与早期的 Agent 框架相比，它们具有三个显著特征：

\begin{importantbox}{Modern AI Agent 的三大特征}
\begin{enumerate}
    \item \textbf{更强的基础模型}：底层使用 GPT-4.5、Opus 4.6 等前沿模型，具备强大的推理和代码生成能力
    \item \textbf{更长程的 Agentic 多轮能力}：用户发出一个 Query 后，Agent 可以进行漫长的多轮长程交互，自主调用工具、读写文件、执行命令，最终完成复杂任务
    \item \textbf{精心设计的 Agent Runtime}：大量的提示词注入（agents.md、src.md、memory.md）、丰富的内置 Tools、Skills 系统、Spawn Agent / Multi-Agent 设计、完善的调度编排系统
\end{enumerate}
\end{importantbox}

\subsection{Context Engineering 的核心地位}

\begin{importantbox}{所有 Modern AI Agent 的本质}
所有 Modern AI Agent 本质上都在做同一件事——\textbf{Context Engineering}。它们维护一个消息列表（Message List），通过精心设计消息的内容、位置和加载时机，构建远端或本地大模型推理所需的完整上下文。

关键原则：不管是 Skills 还是 MCP 工具，如果它们不暴露在 Context（API 的 Message List）中，模型就\textbf{不可能}感知到这些 Skills 和 Tools 的存在，也就无从调用。
\end{importantbox}

\subsection{本章小结}

Modern AI Agent 的核心是 Context Engineering——维护和管理 Agent Loop 执行过程中的上下文，包括预注入指令、Skills 暴露、Tools 注册、对话历史管理等。


\section{Skills 与 MCP/Tools 的正交关系}

\subsection{两种不同的 Context 位置}

Skills 和 MCP/Tools 在技术架构上是\textbf{正交独立}的，它们占据 API 请求中完全不同的位置：

\begin{importantbox}{Skills vs. Tools 的位置差异}
\begin{itemize}
    \item \textbf{Skills}：出现在 \texttt{message} 的 \texttt{content} 字段中，具体是注入的第三条 User 消息，与 agents.md 放在一起
    \item \textbf{MCP / 内置 Tools}：出现在 API 的 \texttt{tools} 字段中，以 Tools Schema 的形式暴露给模型
\end{itemize}
两者处于完全不同的位置，\textbf{不存在} Skills 出现后简化了 MCP/Tools 所占 Context 的情况（除非显式设计）。
\end{importantbox}

\subsection{Skills 的渐进式加载回顾}

以 Codex 为例，Skills 的加载流程：

\begin{enumerate}
    \item 预注入的 User 消息中包含 Skills 的索引——每个 Skill 的名称和简短描述
    \item 用户发出第一个 Query 后，远端模型根据 Query 匹配最合适的 Skill
    \item 如果决定使用某个 Skill，模型通过 Function Call 执行一个 Shell 命令（如 \texttt{cat}），将该 Skill 对应的 skills.md 完整加载
    \item 完整的 Skill 内容作为 Function Output 消息加入 Context
\end{enumerate}

\begin{knowledgebox}{Skills 可以引用 Tools}
Skills 的文档中可以提及具体的 Tools——说明什么时候应该使用什么工具。但这只是指引性的文本，实际的 Tool 定义仍然需要通过 API 的 \texttt{tools} 字段以 Schema 形式暴露给模型。Skills 是"说明书"，Tools 是"工具箱"，两者配合使用。
\end{knowledgebox}

\subsection{本章小结}

Skills 和 MCP/Tools 在 API 层面占据不同位置——Skills 在消息内容中，Tools 在工具字段中。两者技术上正交独立，但在实际使用中协同配合。


\section{Agent Runtime 与 Agent Loop}

\subsection{Agent Runtime：Agent 的运行时环境}

Agent Runtime 是 Agent 执行的"舞台"，它提供 Agent 运行所需的一切环境支持：

\begin{itemize}
    \item \textbf{Workspace}：如 OpenAI Codex 的工作空间
    \item \textbf{启动文件注入}：系统级的提示词（System Prompt）
    \item \textbf{内置 Tools 和 Skills}：预定义的工具集和技能文档
    \item \textbf{配置文件}：agents.md、src.md、tools.md 等 Markdown 配置文件
    \item \textbf{Memory 系统}：记忆和持久化机制
\end{itemize}

\subsection{Agent Loop：消息驱动的执行循环}

Agent Loop 描述了当一条消息真正进入系统后，如何被处理并最终生成响应或动作：

\begin{importantbox}{Agent Loop 的标准流程}
\begin{enumerate}
    \item \textbf{Intake}：接收用户消息（可能需要排队）
    \item \textbf{Prompt Injection}：大量的提示词注入（系统指令、Skills、环境信息等）
    \item \textbf{Model Inference}：调用远端或本地大模型进行推理
    \item \textbf{Function Call}（可选）：如果模型决定调用工具，执行对应的 Function
    \item \textbf{Streaming Response}：流式输出回复
    \item \textbf{Persistence}：持久化到本地（保存对话历史）
\end{enumerate}
这是以 OpenAI Codex 官方文档描述的 Agent Loop 为基础的标准流程。
\end{importantbox}

\begin{knowledgebox}{Agent Runtime vs. Agent Loop}
\begin{itemize}
    \item \textbf{Agent Runtime}：静态的运行时环境，在 Agent 启动时准备好，提供执行所需的一切资源
    \item \textbf{Agent Loop}：动态的执行循环，当消息进入后驱动 Agent 执行动作和生成回复
\end{itemize}
Runtime 是舞台，Loop 是舞台上演出的过程。
\end{knowledgebox}

\subsection{本章小结}

Agent Runtime 提供运行时环境（workspace、配置文件、内置工具），Agent Loop 是消息驱动的执行循环（接收→注入→推理→调用→响应→持久化）。两者共同构成 Modern Agent 的完整架构。


\section{Codex 内置 Tools 全景}

\subsection{Tools Schema 的获取方法}

默认情况下，Codex 的 API 层面 Tools Schema 不会持久化到本地。如果需要查看完整的请求体（包括 Tools 定义），需要设置特定的环境变量来启用日志记录：

\begin{warningbox}{日志落盘方法}
设置环境变量后，Codex 会将完整的 API 请求体保存到本地的 \texttt{logs-1.sqlite} 数据库中。通过查询数据库记录，可以获取到包含 \texttt{instructions}（System Prompt）、\texttt{input}（Message List）和 \texttt{tools}（Tools Schema）的完整请求体。
\end{warningbox}

请求体的结构（Response API 格式）：

\begin{itemize}
    \item \texttt{instructions}：独立的顶层指令，相当于 System Prompt
    \item \texttt{input}：完整的消息列表，可包含 Developer、User、Assistant、Function Call Output 等角色
    \item \texttt{tools}：工具定义列表
    \item Response API 特有的特性：可以挂载之前的 Response ID 进行上下文链接
\end{itemize}

\subsection{Codex 的五类内置 Tools}

通过分析 Codex 的 Tools Schema，可以发现至少五种类型的内置 Function：

\begin{importantbox}{Codex 内置 Tools 分类}
\begin{enumerate}
    \item \textbf{Shell 命令执行}：
    \begin{itemize}
        \item \texttt{execute\_command}：执行 Shell 命令
        \item \texttt{send\_input}：向已有命令会话写入标准输入并读取标准输出
    \end{itemize}
    \item \textbf{计划管理}：
    \begin{itemize}
        \item \texttt{update\_plan}：更新执行计划（所有现代 Coding Agent 都内置 Plan Mode）
    \end{itemize}
    \item \textbf{用户交互}：
    \begin{itemize}
        \item \texttt{request\_user\_input} / \texttt{ask\_user\_question}：向用户询问问题
    \end{itemize}
    \item \textbf{代码操作}：
    \begin{itemize}
        \item \texttt{apply\_patch}：编辑和执行代码
        \item \texttt{view\_image}：查看图片
    \end{itemize}
    \item \textbf{网络与搜索}：
    \begin{itemize}
        \item \texttt{websearch}：网络搜索
    \end{itemize}
\end{enumerate}
\end{importantbox}

\subsection{Multi-Agent（子代理）工具}

Codex 还内置了一套完整的 Multi-Agent 系统工具：

\begin{importantbox}{子代理管理工具}
\begin{itemize}
    \item \texttt{spawn\_agent}：启动一个新的子代理
    \item \texttt{send\_input}：给已有子代理继续发送消息或补充上下文
    \item \texttt{resume\_agent}：恢复上一个已关闭或暂停的子代理
    \item \texttt{wait}：等待一个或多个子代理完成
    \item \texttt{close\_agent}：关闭子代理并返回其最后状态
    \item \texttt{spawn\_agents\_on\_csv}：按 CSV 每行批量启动子代理并汇总结果
\end{itemize}
\end{importantbox}

\begin{knowledgebox}{CSV 批量子代理}
\texttt{spawn\_agents\_on\_csv} 是一个较新的功能，可以根据 CSV 文件的每一行批量启动子代理，每个子代理处理一行数据，最终汇总所有结果。这适用于批量处理类任务，是 Multi-Agent 编排的一种实用模式。
\end{knowledgebox}

\subsection{MCP 作为 Dynamic Tools}

除内置 Tools 外，MCP（Model Context Protocol）提供了动态工具机制：

\begin{itemize}
    \item MCP Tools 取决于用户配置了哪些 MCP Server
    \item 每个 MCP Server 会暴露若干 Tools / Functions
    \item MCP 的 Tools 定义同样通过 API 的 \texttt{tools} 字段暴露给模型
    \item MCP 在配置文件中配置，但其暴露的 Tools Schema 不会出现在 Session 文件中
\end{itemize}

\subsection{本章小结}

Codex 内置五类 Tools（Shell 执行、计划管理、用户交互、代码操作、网络搜索），以及完整的 Multi-Agent 子代理管理工具。MCP 提供动态工具扩展能力。所有 Tools 通过 API 的 tools 字段暴露给模型。


\section{总结与延伸}

\subsection{Context Engineering 的全景图}

本期完成了 Codex Context Engineering 的全景分析：

\begin{itemize}
    \item \textbf{Skills}：出现在 User Message 的 content 中，采用渐进式加载
    \item \textbf{Tools}：出现在 API 的 tools 字段中，包括内置 Tools 和 MCP 动态 Tools
    \item \textbf{System 指令}：独立的 instructions 字段
    \item \textbf{消息历史}：多轮交互记录，可通过 compact 压缩
    \item \textbf{Memory}：持久化的记忆系统
\end{itemize}

\begin{importantbox}{三个关键认知}
\begin{enumerate}
    \item 不管是 Skills、MCP 还是预设 Tools，如果不暴露在 Context 中，模型就无法感知和调用
    \item Skills 和 Tools 在技术上正交独立——Skills 在消息内容中，Tools 在工具字段中
    \item 所有 Modern Agent 的核心工作都是 Context Engineering——精心管理送给模型的上下文
\end{enumerate}
\end{importantbox}

\subsection{拓展阅读}

\begin{itemize}
    \item OpenAI Codex 官方文档中的 Agent Loop 设计
    \item Claude Code 的 CLAUDE.md 和 Skills 机制
    \item MCP（Model Context Protocol）规范
    \item OpenAI Response API 文档
\end{itemize}

%% --- 正文内容结束 --- %%

\end{document}
