Typer 是什么

这次我们选的开源项目叫 Typer。它是一个 Python 命令行工具开发框架。如果你写了一个 Python 函数，Typer 可以帮你把它变成一个可以在终端里运行的命令行工具。

比如你写了这样一个函数：

def main(name: str):
    print(f"Hello {name}")

Typer 可以帮你把它变成类似这样的终端命令：

python3 main.py Q

此外，它还能自动生成 --help、参数说明、错误提示和命令补全。如果我们想把平时写的小脚本整理成更正式的 CLI 工具，Typer 是一个很适合入门的项目。

Type 地址：github.com/fastapi/typer

Typer 很适合今天这篇文章。我们用 Codex CLI，去读一个 CLI 框架项目，逻辑就很顺。

先把项目下载下来

先找一个你平时放代码的目录，然后执行下面这几行命令：

mkdir -p ~/codex-practice
cd ~/codex-practice
git clone https://github.com/fastapi/typer.git
cd typer

上面的 git clone 就是把 Typer 这个开源项目下载到本地。执行完之后，我们已经进入了 typer 这个项目目录。

可以先看一眼当前目录里有什么：

ls

如果想看得更清楚一点，也可以执行：

find . -maxdepth 2 -type d | sort | head -40

这行命令会列出当前项目里前两层目录。我们不需要马上看懂每一个目录，只要先知道：这是一个真实项目，里面有源码、文档、测试、配置文件。

启动 Codex

接下来，在 typer 目录里启动 Codex：

codex

这里有一个关键点，就是在 typer 这个项目目录里启动 Codex。

普通网页聊天，我们要把代码、报错、目录结构复制给 AI；而在 Codex CLI 里启动它，就可以直接围绕本地项目目录工作。我们在哪个目录里启动 Codex，它就会优先把这个目录当作当前项目。

类似的逻辑在 Codex App 里也存在，只是入口从“在哪个目录启动命令”变成了“在 App 里选择哪个项目文件夹”。无论是 CLI、App，还是 IDE 插件，关键点都一样：先把 Codex 放到正确的项目上下文里，再让它读代码、解释结构、执行任务。

Codex 启动之后，我们先不要让它改代码，只让它读项目。来，把下面这段提示词复制给 Codex：

先不要修改任何文件。

请你阅读当前这个项目，然后用适合新手的方式回答：

1. 这个项目是做什么的？
2. 它主要解决什么问题？
3. 项目里最重要的几个目录分别是干什么的？
4. 源码大概放在哪里？
5. 测试大概放在哪里？
6. 文档大概放在哪里？

回答时请尽量引用具体文件路径。

这一步的目的很简单：先让 Codex 给我们画一张项目地图。

我们第一次打开一个新项目，容易卡在不知道从哪里看起。Codex 这一步做的事情，就是先帮我们把项目拆开：哪些文件是入口，哪些目录是源码，哪些地方是测试，哪些地方是文档。

Codex 解释项目

上面 Codex 读了 README 给我们介绍 Typer，它是一个 Python 库，用来快速构建命令行工具，也就是 CLI 应用。

如果你觉得它讲得还是有点偏工程，可以继续追问一次：

请你再用更通俗的方式解释 Typer。

假设读者只会写一点 Python 脚本，但没写过 CLI 工具。请你说明：

1. CLI 工具是什么？
2. Typer 能把普通 Python 脚本变成什么？
3. 为什么它会用到 Python 类型标注？
4. 用户执行 --help 时，Typer 大概帮我们做了什么？
5. 请用一个非常小的例子解释。

现在你大概清楚 Typer 是怎么样的一个项目。我们开始今天的主菜，让 Codex 带我们读这个项目，添加一个测试和小修改。

Codex 找项目入口

在知道 Typer 是做什么的之后，我们的下一步是找入口。继续给 Codex 输入：

现在请你继续阅读项目。

我想知道：如果我要理解 Typer 的核心代码，应该从哪些文件开始看？

请你按下面格式回答：

- 第一个应该看的文件：
- 这个文件解决什么问题：
- 它和其他文件有什么关系：

最多列 5 个文件，不要列太多。
还是不要修改任何文件。

这里故意加了一句“最多列 5 个文件”。对刚接触一个项目的人来说，Codex 一口气列出十几个文件，信息量反而会太大。先控制在少量关键文件里，我们更容易看清项目入口，也更容易跟着它继续往下读。

读项目的时候，我们不用一开始就理解所有东西。比较稳妥的方式是：先知道最值得看的几个文件，然后一层一层往下追。

这一步里，Codex 建议先看 typer/__init__.py。这个文件是 Typer 对外暴露 API 的入口，用户平时写 import typer 后能用到的 typer.Typer、typer.Option、typer.Argument、typer.run 等，基本都是从这里暴露出来的。

接着是 typer/main.py。它是核心主流程，负责处理 typer.Typer()、@app.command()、typer.run() 这些常见用法，并把 Python 函数转换成命令行命令。然后是 typer/params.py，它定义了 typer.Option() 和 typer.Argument()，也就是告诉 Typer：这个函数参数在 CLI 里应该表现成选项，还是位置参数。

再往下，Codex 推荐看 typer/models.py。这个文件主要保存 Typer 内部用到的数据结构，比如命令信息、参数信息、默认值、文件类型、上下文对象等。最后是 typer/core.py，它负责更底层的命令行行为，比如命令执行、参数展示、帮助信息和错误格式化，也会和底层的 Click 兼容代码配合。

这样一来，Typer 的核心代码就有了一条比较清楚的阅读路线：先看对外入口，再看主流程，然后看参数定义和内部数据结构，最后再进入底层命令行为。

Codex 解读项目运行原理

现在，我们来加点难度，让 Codex 追一条更具体的路线：当用户写了一个 Typer 应用，并在终端里运行它时，代码大概会经过哪些关键步骤。通过这条路线，我们可以进一步理解 Typer 是如何把一个普通 Python 函数变成命令行工具的。继续输入：

请你帮我追一条使用路线。

假设用户写了一个最简单的 Typer 应用，然后在终端里运行：

python main.py --help

请你结合当前项目代码解释：

1. 用户执行命令后，Typer 大概接管了哪些事情？
2. 参数和 --help 信息大概由哪些模块处理？
3. 测试里有没有类似场景？
4. 如果我要理解 --help 是怎么生成的，应该看哪些文件？

请用新手能看懂的方式解释。
不要修改任何文件。

上面这段话，就是本文的核心：

• README 告诉我们项目对外怎么介绍自己；

• 源码告诉我们功能怎么实现；

• 测试告诉我们项目希望哪些行为保持稳定；

把这三块连起来，我们才算真的开始理解项目。对 Typer 来说，--help 是一个很适合入门的观察点。因为命令行工具最常见的用户入口之一，就是输入 --help 看参数说明。让 Codex 从这个入口往里追，会比抽象地问“请解释源码”更容易得到有用回答。

给 Codex 加一份项目 AGENTS.md

到这里，细心的你可能留意到一件事，前面的每一步项目讲解，我们都在提醒 Codex：

• 先不要改代码

• 回答要引用文件路径

• 解释要适合新手

• 不要一次列太多文件

• 修改前先说明计划

像是这种重复性需求，如果每次都人肉提醒，会有点麻烦。这个时候，我们需要用下 AGENTS.md。

AGENTS.md 是一份写给 Codex 的项目说明。我们可以把项目里的协作规则写进去，让 Codex 以后进入这个项目时先读这份说明。

如何写第一份 AGENTS.md

我们先退出当前 Codex 会话。按 Ctrl + C，或者在 Codex 里输入退出命令。

然后在终端里确认自己还在 typer 项目目录：

pwd

现在，我们来创建一份 AGENTS.md。在终端里输入下面命令：

nano AGENTS.md

执行后，终端会打开一个文本编辑界面。把下面这段内容复制进去：

# AGENTS.md

## 阅读项目时

- 先阅读 README.md、pyproject.toml、docs/ 和 tests/。
- 回答项目结构问题时，请引用具体文件路径。
- 面向新手解释时，少用术语，多说“这个文件解决什么问题”。
- 一次最多列 5 个关键文件，避免信息过载。

## 修改代码时

- 修改前先说明计划。
- 优先做小范围改动。
- 不要一次性重构多个模块。
- 修改后说明改了哪些文件，以及建议运行什么命令验证。

## 本文实践要求

- 这次主要目标是读懂项目。
- 除非我明确要求，否则不要修改源码。

复制粘贴完成后，按下面的顺序执行命令来保存刚才的修改：

Ctrl + O   保存
Enter      确认文件名
Ctrl + X   退出 nano

回到终端后，可以输入命令查看我们文件是否保存成功：

cat AGENTS.md

如果终端里能看到刚才写入的内容，就说明 AGENTS.md 已经创建好了。

现在重新启动 Codex。在当前目录（typer）下执行命令：

codex

进入 Codex 后，先问它：

请你先告诉我：你现在能看到哪些项目说明或规则？

如果你读取到了 AGENTS.md，请总结里面最重要的规则。
不要修改任何文件。

这一步是为了确认：Codex 已经知道这个项目里的协作规则。

AGENTS.md 的神奇之处

有了 AGENTS.md 之后，我们再让 Codex 做一次类似的项目阅读任务：

请你根据当前项目和 AGENTS.md 的规则，重新整理一份项目地图。

请按下面结构回答：

1. 这个项目一句话介绍
2. 新手最先应该看的 3 个文件或目录
3. 源码、测试、文档分别在哪里
4. 如果要理解 --help 功能，推荐阅读路线是什么
5. 这个项目里哪些地方暂时不建议新手一开始就深入

不要修改任何文件。

这一次，Codex 的回答应该会更符合我们的要求：路径更明确，解释更偏新手，一次列出的文件也不会太多。

这就是 AGENTS.md 的价值。它不是让 Codex 变聪明的魔法文件，但它可以把我们反复强调的规则固定下来。之后每次进入这个项目，我们就不用重复说一大段前置要求。

如何做测试

我们读项目不能只看源码，测试也很重要。下面我们来看个测试用例，请继续输入：

请你在 tests/ 目录里找一个适合新手理解的测试用例。

要求：

1. 只选一个测试文件
2. 解释这个测试文件在验证什么
3. 选其中一个测试函数，逐行解释它的大概意思
4. 说明这个测试和 Typer 的用户使用体验有什么关系

不要修改任何文件。

这个方式对新手很友好。源码一开始可能会比较绕，但测试通常更接近真实使用场景：用户输入什么命令，程序应该返回什么结果。通过测试，我们可以反过来理解项目的行为。

这一步里，Codex 建议先看 tests/test_cli/test_help.py。这个测试文件主要验证 Typer 生成的 --help 信息是否正常。对 CLI 工具来说，--help 往往是用户第一次接触程序时看到的入口，所以它的显示结果、排版、命令列表、错误信息都很重要。

Codex 还选了其中一个测试函数 test_short_help 来解释。这个测试会创建一个简单的 Typer 应用，注册几个命令，然后模拟用户运行 --help。接着，它会检查命令是否执行成功、帮助信息里是否出现了对应命令，以及过长的帮助文本是否被正确截断。