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 并在项目目录启动 Codex2.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 先帮我们把项目拆开——哪些是入口哪些是源码哪些是测试哪些是文档。如果它讲得偏工程可以追问一次让它用更通俗的方式解释 TyperCLI 工具是什么、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.md3.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、OAuth5.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目录里启动的 CodexAGENTS.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 的每一步都看得清清楚楚。
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 并在项目目录启动 Codex2.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 先帮我们把项目拆开——哪些是入口哪些是源码哪些是测试哪些是文档。如果它讲得偏工程可以追问一次让它用更通俗的方式解释 TyperCLI 工具是什么、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.md3.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、OAuth5.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目录里启动的 CodexAGENTS.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 的每一步都看得清清楚楚。
