1. 为什么 Codex 读 Typer 会“迷路”：从 AGENTS.md 说起
Typer 是一个用 Python 类型标注快速构建命令行工具（CLI）的框架，它把普通函数变成带--help、参数校验和补全的终端命令。适合谁？适合已经会写一点 Python 脚本、想把脚本整理成正式 CLI 工具的人，也适合想借一个真实开源项目练手 Codex 的开发者。但很多人第一次把 Codex 丢进 Typer 仓库，得到的回答要么是泛泛而谈，要么一口气列出十几个文件，看完更晕。问题不在 Codex，而在于我们没给它一份稳定的“项目阅读规则”。
我试过直接问“解释一下这个项目”，Codex 会从 README 里摘一段，再补几句源码路径，信息密度忽高忽低。真正让体验变稳的，是在仓库根目录放一份AGENTS.md。它不是什么魔法文件，本质是一份写给 Codex 的项目说明：你希望它先读哪些文件、回答时引用什么路径、一次最多列几个文件、改代码前要不要先说计划。把这些重复性要求固定下来，后面每次进入项目就不用再重复一大段前置提示。
这篇就围绕 Typer 这个开源 Python CLI 项目，走一条可复制的路径：先克隆仓库、在项目目录里启动 Codex，用提问模板让它画出项目地图；再写一份可复制的AGENTS.md配置片段；最后做一次从仓库到命令清单的验证动作，确认 Codex 真的读懂了命令注册与参数解析链路。全程不改核心源码，重点是把“读项目”这件事拆成能跟做的步骤。
需要说明的是，Codex 只是阅读和解释代码的助手，Typer 本身的运行、测试还是靠本地 Python 环境。如果你在接入模型服务时想统一管理密钥和调用入口，可以用 TaoToken 这类平台做中转配置，后面第三节会给可复制的配置片段。先把项目读明白，再谈改代码，这个顺序对新手最友好。
2. 前置准备：克隆 Typer 并在项目目录启动 Codex
2.1 把 Typer 拉到本地
先找一个平时放代码的目录，执行下面几行。git clone就是把 Typer 这个开源项目下载到本地，执行完就进入了typer目录。
mkdir -p ~/codex-practice cd ~/codex-practice git clone https://github.com/fastapi/typer.git cd typer看一眼当前目录里有什么：
ls想看得更清楚，列出前两层目录：
find . -maxdepth 2 -type d | sort | head -40这一步不用马上看懂每个目录，只要先建立一个印象：这是一个真实项目，里面有源码、文档、测试和配置文件。Typer 的源码主要在typer/下，测试在tests/，文档在docs/，项目元信息在pyproject.toml。
2.2 在正确的目录里启动 Codex
关键点来了：一定要在typer这个项目目录里启动 Codex。
codex我们在哪个目录启动 Codex，它就会优先把这个目录当作当前项目。普通网页聊天要把代码、报错、目录结构复制给 AI；而在 Codex CLI 里，它可以直接围绕本地项目目录工作。Codex App 或 IDE 插件也是同样的逻辑，只是入口从“在哪个目录启动命令”变成了“选择哪个项目文件夹”。核心都是：先把 Codex 放进正确的项目上下文，再让它读代码。
2.3 用提问模板让 Codex 画项目地图
启动后先别让它改代码，只让它读。把下面这段提示词复制给 Codex：
先不要修改任何文件。 请你阅读当前这个项目，然后用适合新手的方式回答： 1. 这个项目是做什么的？ 2. 它主要解决什么问题？ 3. 项目里最重要的几个目录分别是干什么的？ 4. 源码大概放在哪里？ 5. 测试大概放在哪里？ 6. 文档大概放在哪里？ 回答时请尽量引用具体文件路径。这一步的目的很简单：先让 Codex 给我们画一张项目地图。第一次打开新项目容易卡在“不知道从哪看起”，Codex 先帮我们把项目拆开——哪些是入口，哪些是源码，哪些是测试，哪些是文档。
如果它讲得偏工程，可以追问一次，让它用更通俗的方式解释 Typer：CLI 工具是什么、Typer 能把普通 Python 脚本变成什么、为什么用到类型标注、用户执行--help时 Typer 大概做了什么。这样一轮下来，你对 Typer 的定位就清楚了。
2.4 让 Codex 找核心入口，控制信息量
知道 Typer 是做什么的之后，下一步是找入口。继续输入：
现在请你继续阅读项目。 我想知道：如果我要理解 Typer 的核心代码，应该从哪些文件开始看？ 请你按下面格式回答： - 第一个应该看的文件： - 这个文件解决什么问题： - 它和其他文件有什么关系： 最多列 5 个文件，不要列太多。 还是不要修改任何文件。这里故意加了“最多列 5 个文件”。对刚接触项目的人来说，一口气列十几个文件信息量太大，先控制在少量关键文件里，更容易看清入口。Codex 通常会建议先看typer/__init__.py，它是对外暴露 API 的入口，typer.Typer、typer.Option、typer.Argument、typer.run基本都从这里暴露。接着是typer/main.py，核心主流程，处理typer.Typer()、@app.command()、typer.run()这些常见用法。然后是typer/params.py，定义Option()和Argument()，告诉 Typer 某个函数参数在 CLI 里是选项还是位置参数。再往下是typer/models.py，保存内部数据结构；最后是typer/core.py，负责更底层的命令执行、帮助信息和错误格式化，并和底层 Click 兼容代码配合。这样核心代码就有了一条清楚的阅读路线。
3. 可复制配置：给 Typer 写一份 AGENTS.md
3.1 为什么需要 AGENTS.md
前面每一步我们都在提醒 Codex：先不要改代码、回答要引用路径、解释要适合新手、一次别列太多文件、修改前先说计划。这些重复性要求如果每次人肉提醒，很麻烦。AGENTS.md就是把这些规则固定下来的地方，Codex 进入项目时会先读它。
先退出当前会话，按Ctrl + C。确认自己还在typer目录：
pwd3.2 可复制的 AGENTS.md 片段
创建文件：
nano AGENTS.md把下面这段内容复制进去。这是一份可直接用的配置片段，路径和项目结构一致：
# AGENTS.md ## 阅读项目时 - 先阅读 README.md、pyproject.toml、docs/ 和 tests/。 - 回答项目结构问题时，请引用具体文件路径。 - 面向新手解释时，少用术语，多说“这个文件解决什么问题”。 - 一次最多列 5 个关键文件，避免信息过载。 ## 修改代码时 - 修改前先说明计划。 - 优先做小范围改动。 - 不要一次性重构多个模块。 - 修改后说明改了哪些文件，以及建议运行什么命令验证。 ## 本文实践要求 - 这次主要目标是读懂项目。 - 除非我明确要求，否则不要修改源码。保存并退出：Ctrl + O保存，Enter确认文件名，Ctrl + X退出。回到终端后确认内容：
cat AGENTS.md能看到刚才写入的内容，就说明创建成功。
3.3 如果你用 TaoToken 统一管理模型调用
Codex 本身是客户端，真正跑推理的是背后的模型服务。如果你想把密钥和调用入口统一管理，可以用 TaoToken 做中转配置。下面给一份可复制的配置思路，具体字段以你使用的客户端为准。
在项目里或用户目录下放一份配置，Base URL 指向 TaoToken 的 API 地址，Key 用你在控制台创建的密钥，Model ID 填你要用的模型标识。三件套缺一不可：Base URL、Key、Model ID。
{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的密钥", "model": "你的模型ID" }如果你用的是支持settings.json或auth.json的客户端，把对应字段填进去即可。密钥建议放在环境变量或本地配置文件里，不要提交到 Git。创建密钥的入口在控制台的 API Keys 页面，接入细节可以对照官方文档。这样配置好之后，Codex 的请求就走统一入口，换模型或换项目时不用到处改。
3.4 重启 Codex 并确认它读到了规则
重新在typer目录启动：
codex进入后先问它：
请你先告诉我：你现在能看到哪些项目说明或规则？ 如果你读取到了 AGENTS.md，请总结里面最重要的规则。 不要修改任何文件。这一步是为了确认 Codex 已经知道项目里的协作规则。有了AGENTS.md之后，再让它做一次项目阅读任务：
请你根据当前项目和 AGENTS.md 的规则，重新整理一份项目地图。 请按下面结构回答： 1. 这个项目一句话介绍 2. 新手最先应该看的 3 个文件或目录 3. 源码、测试、文档分别在哪里 4. 如果要理解 --help 功能，推荐阅读路线是什么 5. 这个项目里哪些地方暂时不建议新手一开始就深入 不要修改任何文件。这一次回答应该会更符合要求：路径更明确，解释更偏新手，一次列出的文件也不会太多。AGENTS.md的价值就在这里——它把反复强调的规则固定下来，之后每次进入项目都不用重复说一大段。
4. 验证请求：从仓库到命令清单的完整动作
4.1 追一条--help的运行路线
读项目不能只看目录，要沿着一个具体功能追下去。--help是 CLI 最常见的用户入口，很适合当观察点。继续输入：
请你帮我追一条使用路线。 假设用户写了一个最简单的 Typer 应用，然后在终端里运行： python main.py --help 请你结合当前项目代码解释： 1. 用户执行命令后，Typer 大概接管了哪些事情？ 2. 参数和 --help 信息大概由哪些模块处理？ 3. 测试里有没有类似场景？ 4. 如果我要理解 --help 是怎么生成的，应该看哪些文件？ 请用新手能看懂的方式解释。 不要修改任何文件。README 告诉我们项目对外怎么介绍自己，源码告诉我们功能怎么实现，测试告诉我们项目希望哪些行为保持稳定。把这三块连起来，才算真的开始理解项目。对 Typer 来说，--help这条线会牵出命令注册、参数解析和帮助信息格式化，正好覆盖 CLI 的核心链路。
4.2 用测试反推项目行为
源码一开始可能比较绕，但测试通常更接近真实使用场景。继续输入：
请你在 tests/ 目录里找一个适合新手理解的测试用例。 要求： 1. 只选一个测试文件 2. 解释这个测试文件在验证什么 3. 选其中一个测试函数，逐行解释它的大概意思 4. 说明这个测试和 Typer 的用户使用体验有什么关系 不要修改任何文件。Codex 通常会建议看tests/test_cli/test_help.py，它主要验证 Typer 生成的--help信息是否正常。对 CLI 工具来说，--help往往是用户第一次接触程序时看到的入口，显示结果、排版、命令列表、错误信息都很重要。它可能选test_short_help来解释：创建一个简单 Typer 应用，注册几个命令，模拟运行--help，然后检查命令是否执行成功、帮助信息里是否出现对应命令、过长文本是否被正确截断。这样看测试，就不只是看“代码有没有通过”，也能看到 Typer 在保证什么用户体验。
4.3 一次从仓库到命令清单的验证动作
现在做一次完整的验证：让 Codex 基于读到的内容，输出一份命令清单，并说明每个命令对应的源码位置。输入：
请你基于当前项目，整理一份 Typer 常用命令清单。 要求： 1. 列出 typer.Typer()、@app.command()、typer.run()、typer.Option()、typer.Argument() 这几个用法 2. 每个用法说明它解决什么问题 3. 每个用法给出对应的源码文件路径 4. 给出一个最小可运行示例 不要修改任何文件。这一步就是“从仓库到命令清单”的验证动作。如果 Codex 能准确给出typer/main.py、typer/params.py这些路径，并配上最小示例，说明它确实读懂了命令注册与参数解析链路。你可以把这份清单存下来，作为后续读代码的索引。
4.4 让 Codex 提出一个低风险练习
读完之后，可以做一个轻量任务，但先别改核心源码。输入：
现在请你不要真的修改文件。 请你基于刚才阅读的测试文件，提出一个适合新手练习的小改动。 要求： 1. 改动范围尽量小 2. 最好只涉及一个测试文件 3. 不改核心源码 4. 说明为什么这个改动适合练习 5. 给出你预计会修改的文件路径 6. 给出修改后应该运行的测试命令Codex 可能建议在tests/test_cli/test_help.py里新增一个测试函数，验证命令的 docstring 会不会出现在--help输出里。这个改动只涉及一个测试文件，不碰核心源码。它还会给出验证命令：
pytest tests/test_cli/test_help.py -k command_docstring_help或者跑整个相关文件：
pytest tests/test_cli/test_help.py改代码前先确认仓库状态：
git status除了新增的AGENTS.md，源码本身还没被修改。这样后面 Codex 改了测试文件，就能清楚看到变化。如果让它执行修改，记得要求它先确认文件路径、只做小改动、改完说明改了什么、能跑测试就跑、跑不起来先判断是环境问题还是代码问题。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
5.1 401 Unauthorized
这是最常见的报错，通常是 Key 没填对、过期，或者 Base URL 和 Key 不匹配。排查顺序：先确认配置文件里的api_key是不是完整复制，没有多余空格；再确认base_url指向的是https://taotoken.net/api，不要多加路径；最后去控制台的 API Keys 页面确认这个 Key 还在有效期内。如果换了模型，也要确认 Model ID 拼写正确。三件套 Base URL、Key、Model ID 任意一个错，都可能返回 401。
5.2 local proxy failed
这个报错一般出现在客户端尝试走本地代理但连不上时。先检查你的客户端配置里有没有多余的代理设置，把它清掉，让请求直连你配置的 Base URL。如果你在settings.json或环境变量里设了代理相关字段，确认它们和当前网络环境一致。多数情况下，把代理配置删掉、只保留 Base URL 和 Key，问题就消失了。
5.3 reading choices 相关报错
这类报错通常出现在解析模型返回结构时，比如返回体里没有预期的choices字段。常见原因是 Base URL 指向了不兼容的接口，或者 Model ID 填成了不支持对话的模型。排查时先确认你用的接口是对话补全接口，再确认 Model ID 和接口匹配。如果刚换过模型，回退到之前能用的配置试一次，能快速定位是不是模型标识的问题。
5.4 OAuth 相关报错
如果你用的是需要 OAuth 登录的客户端，报错通常和令牌过期或回调地址不匹配有关。先确认登录状态是否还有效，必要时重新走一次授权流程。回调地址要和客户端配置里填的一致，端口不要被占用。如果同时配了 API Key 和 OAuth，确认客户端当前用的是哪一种认证方式，避免两套凭证互相干扰。
5.5 Codex 读不到 AGENTS.md
如果 Codex 说看不到项目规则，先确认你是在typer目录里启动的 Codex，AGENTS.md就在这个目录下。用cat AGENTS.md确认文件存在且内容完整。文件名大小写要一致，别写成agents.md。如果还是读不到，重启一次 Codex 会话再问。
5.6 pytest 跑不起来
前面演示里测试没继续跑，原因是当前python3环境没装pytest。这属于环境问题，不是新增测试用例的问题。可以先确认 Python 版本：
python3 --version再装依赖：
python3 -m pip install pytest装完再跑pytest tests/test_cli/test_help.py。如果还报依赖缺失，按提示补装即可。记住：验证失败时先判断是环境问题、依赖问题还是代码问题，别急着改代码。
6. 把 Codex 变成项目阅读助手：接入与后续
6.1 接入入口按用途分流
如果你还没配好模型服务，按用途选入口：排障和接入相关的问题，先看 API Keys 页面创建密钥，再对照接入文档把 Base URL、Key、Model ID 填进客户端；想先验证模型能不能正常对话，用模型对话页面发一条消息试试；如果是长期编码或跑 Agent 任务，考虑 Coding Plan，把调用额度固定下来。这三个入口分别对应“配好”“验证”“长期用”三个阶段，按需选就行。
6.2 把 AGENTS.md 用到其他项目
这套方法不只适用于 Typer。换一个开源项目，把AGENTS.md里的路径改成对应项目的README.md、pyproject.toml、src/、tests/，规则部分基本可以复用。核心思路是：先让 Codex 读目录、找入口、解释核心文件，再沿一个具体功能追下去，最后通过测试理解项目如何验证行为。这样做的好处是，你能一步一步看见 Codex 在读什么、怎么理解、准备从哪里下手。
6.3 下一步可以练什么
读项目只是第一步。接下来可以练：让 Codex 基于AGENTS.md提出小范围改动方案，你审核后再让它执行；或者让它对比两个相似模块的实现差异，训练它引用具体路径回答。等你对 Typer 的命令注册和参数解析链路熟悉了，再尝试改核心源码也不迟。对新手来说，先建立整体认知，再动手改，返工最少。
最后留一个实用技巧：每次让 Codex 改代码前，先跑git status确认工作区干净，改完再跑一次，对比它到底动了哪些文件。配合AGENTS.md里的“修改前先说明计划”，你能把 Codex 的每一步都看得清清楚楚。
