Codex 实战资料包使用手册
工具箱式参考：Prompt 模板、文件检查清单、故障排查流程、练习题和配套资料包说明。配合前两本反复查用。
本版定位
这一版不是正文教程，而是工具箱。适合你在实际使用 Codex 时反复查：怎么写 Prompt、怎么检查文件、怎么排查问题、怎么做练习、怎么使用配套资料包。
出版版处理原则：附录 D 和 G 可以进入正文；附录 F/H/I/J/K/L 只适合作为课后资料、社群资料或下载包，不应继续挤在正文末尾增加页数。凡是 FAQ 能回到具体章节末尾的，就回迁到对应章节；凡是只重复“检查、复盘、资料清单”的内容，优先压缩成一页。
适合读者：
- 已经读过入门教程，准备动手练的人。
- 带课、带社群、做训练营的人。
- 想把 Codex 使用流程沉淀成模板和资料包的人。
本版目录
- 附录D 常用 Prompt 模板库
- 附录E 配图与截图补充清单
- 附录F 发布前检查清单
- 附录G 官方资料与延伸阅读
- 附录H 读者常见问题 FAQ
- 附录I 课后练习与项目作业
- 附录J 任务速查地图
- 附录K 故障排查索引
- 附录L 配套资料包清单
附录D 常用 Prompt 模板库
这一附录不是用来背的。
它更像一本小抄：当你不知道怎么开口时，直接复制一个模板，把里面的占位内容换成自己的任务，就可以开始和 Codex 协作。
很多新手用不好 AI，不是因为问题太难，而是因为第一句话太空。
比如：
帮我做一个网页。这句话不是不能用，但它缺少太多信息：给谁看、做什么内容、要什么风格、有没有已有文件、完成后怎么验证。
更好的方式是：
我想做一个个人介绍网页。
受众是第一次了解我的合作伙伴。
请先阅读当前文件夹，再问我 3 个关键问题。
等我回答后，生成一个可以直接打开的 HTML 页面。
要求页面简洁、移动端可用，并在完成后帮我检查有没有明显排版问题。你会发现，第二种说法并没有更复杂，只是把“任务边界”说清楚了。
下面这些模板都可以直接复制。
D.1 万能起手式
适合：你有一个模糊想法，但还不知道怎么拆。
我想完成一个任务：
【在这里写你的目标】
我的背景是：
【说明你是谁、要给谁用、目前有什么材料】
请你先不要直接开始做。
先帮我判断这个任务是否清楚。
如果不清楚，请只问我 3 个最关键的问题。
等我回答后，再帮我拆成可执行步骤。这个模板的重点是“先不要直接开始做”。
当目标还模糊时，让 Codex 立刻动手，往往会生成一堆看起来很完整、实际不一定符合你想法的东西。
D.2 让 Codex 检查一个文件
适合：检查文章、代码、配置、README、教程草稿。
请检查这个文件：
【文件名或路径】
重点看这几类问题：
1. 内容是否完整；
2. 结构是否清楚；
3. 有没有明显错误、重复、过时说法；
4. 对新手是否友好；
5. 有哪些地方值得继续补充。
请先给我检查结论。
如果需要修改，先列出修改建议，不要直接改文件。如果你已经确定要它直接改，可以把最后一句换成：
如果发现问题，请直接修改文件，并在完成后告诉我改了哪些地方。D.3 让 Codex 继续补充文档
适合：你已经写了一部分文章、教程、说明书，希望继续扩写。
请继续补充当前文档。
补充原则：
1. 保持原来的语气和结构；
2. 不要推翻已经写好的内容；
3. 优先补缺失章节、案例、步骤和新手提醒；
4. 每次补充后，检查目录、标题层级和代码块是否正常；
5. 如果遇到过时信息，请标注并改成更稳妥的表达。
请先阅读文件结尾和目录，再继续写下一段最该补的内容。这个模板非常适合长文档。
如果你只说“继续”，Codex 可能知道大方向，但不知道你更在意内容、结构还是校验。这个模板能把“继续”的含义说得更稳。
D.4 让 Codex 改写一段文字
适合：把生硬文字改成教程、公众号、小红书、汇报稿。
请改写下面这段文字：
【粘贴原文】
改写目标：
1. 读者是【填写读者类型】；
2. 语气要【通俗 / 专业 / 温柔 / 干练 / 适合演讲】；
3. 保留核心信息，不要编造事实；
4. 结构更清楚，每段只讲一个重点；
5. 重要概念用例子解释。
请先给出改写版，再列出你主要改动了哪些地方。如果你要做短视频口播，可以追加：
请同时给我一版 60 秒口播稿，句子短一点，适合真人朗读。D.5 从一句话生成页面
适合：零基础做一个本地 HTML 页面。
我想做一个网页：
【描述页面主题】
使用场景：
【谁会看这个页面，为什么要看】
页面需要包含：
1. 【模块一】
2. 【模块二】
3. 【模块三】
要求：
1. 生成一个可以直接打开的 HTML 文件；
2. CSS 写在同一个文件里；
3. 手机和电脑上都要能看；
4. 不要使用复杂依赖；
5. 完成后帮我检查排版是否有明显问题。
请先给出页面结构，再开始写文件。如果你希望页面更像正式产品，可以补一句：
视觉风格要克制、清爽、适合真实业务使用，不要做成夸张的营销页。D.6 让 Codex 修改已有页面
适合：你已经有 HTML、React、Vue 或其他前端项目。
请修改当前页面。
目标：
【说明想改成什么效果】
请先阅读相关文件，找出页面入口、样式文件和主要组件。
修改要求：
1. 尽量沿用当前项目的写法；
2. 不要做无关重构；
3. 保持移动端可用；
4. 修改后启动本地服务检查页面；
5. 如果发现文字溢出、按钮错位、内容重叠，请一并修复。
完成后告诉我：
1. 改了哪些文件；
2. 页面现在怎么访问；
3. 还有哪些风险或未验证项。这个模板的核心是：先读项目，再动手。
前端项目经常有自己的组件、样式、路由和构建方式。直接让 AI 重写页面，容易破坏原有结构。
D.7 数据分析模板
适合：分析 CSV、Excel、运营数据、销售数据。
请分析这个数据文件：
【文件名或路径】
业务背景：
【这份数据从哪里来，用来回答什么问题】
我想知道：
1. 【问题一】
2. 【问题二】
3. 【问题三】
请按这个流程做：
1. 先检查字段含义、缺失值、异常值；
2. 再判断这些问题能不能被当前数据回答；
3. 能回答的，请给出计算过程和结论；
4. 不能回答的，请说明缺少什么字段；
5. 最后输出一份适合汇报的摘要。
请不要只给结论，要说明结论来自哪些数据。如果需要图表，可以追加：
请生成一个 HTML 图表报告，图表要有标题、坐标含义和简短解读。D.8 报错排查模板
适合：命令失败、页面打不开、依赖安装报错、测试失败。
我遇到了一个报错。
我执行的命令是：
【粘贴命令】
报错内容是：
【粘贴完整报错】
我的目标是：
【说明本来想完成什么】
请按排查流程来：
1. 先解释这个报错大概是什么意思；
2. 判断最可能的 3 个原因；
3. 告诉我先验证哪一个；
4. 如果需要运行命令，请说明它要检查什么；
5. 修复后请重新运行原命令确认。报错时，不要只截最后一行。
很多真正有用的信息在报错上方，比如文件路径、行号、缺失依赖、权限提示。
D.9 让 Codex 重构代码
适合：代码能跑，但越来越乱。
请帮我重构这部分代码：
【文件名或范围】
重构目标：
1. 保持现有功能不变；
2. 提高可读性；
3. 减少重复逻辑；
4. 拆分过长函数；
5. 不引入不必要的新依赖。
请先阅读相关代码，并告诉我：
1. 当前主要问题是什么；
2. 你准备怎么改；
3. 哪些行为需要用测试或命令验证。
我确认后，再开始修改。如果你已经信任它直接执行，可以把最后一句改成：
如果改动范围清楚，请直接修改，并在完成后运行现有测试。D.10 生成 README
适合：项目快完成了，但没有说明书。
请为当前项目生成 README.md。
请先阅读项目结构和主要入口文件。
README 需要包含：
1. 项目简介；
2. 功能列表；
3. 安装方式；
4. 启动方式；
5. 使用流程；
6. 目录结构说明；
7. 常见问题；
8. 后续可扩展方向。
要求：
1. 面向第一次打开项目的人；
2. 命令必须和当前项目实际情况一致；
3. 不要写无法确认的内容；
4. 如果有不确定项，请标出来。README 不是装饰品。
它是你一个月后还能看懂自己项目的保险。
D.11 生成 PRD
适合：你有想法，但还没变成需求文档。
请帮我把下面的想法整理成 PRD。
我的想法：
【描述你的产品或功能想法】
请输出：
1. 背景与问题；
2. 目标用户；
3. 核心使用场景；
4. 本次版本要做什么；
5. 本次版本不做什么；
6. 用户流程；
7. 功能清单；
8. 验收标准；
9. 风险与待确认问题。
要求：
1. 先做最小可用版本；
2. 不要把功能写得过大；
3. 每个功能都要能被验收；
4. 不确定的地方请用问题列出来。PRD 最重要的是帮你克制范围。
如果一个 PRD 看起来什么都想做，通常意味着第一版很难真的做完。
D.12 生成 DESIGN
适合：准备开始写代码前，先想清楚结构。
请根据当前 PRD 生成 DESIGN.md。
请先阅读：
1. README.md；
2. PRD.md；
3. 当前项目结构。
DESIGN 需要包含：
1. 技术选型；
2. 模块划分；
3. 数据结构；
4. 主要流程；
5. 错误处理；
6. 测试策略；
7. 可能的风险；
8. 暂不实现的内容。
要求：
1. 方案要适合当前项目，不要过度设计；
2. 每个模块说明输入、输出和职责；
3. 如果有多个方案，请先比较再推荐一个。DESIGN 的价值不是写得高级，而是让后面的实现少走弯路。
D.13 生成 PLAN
适合：已经有需求和方案，准备拆任务。
请根据 README、PRD 和 DESIGN 生成 PLAN.md。
PLAN 需要把任务拆成多个小步骤。
每一步请包含：
1. 要做什么；
2. 会修改哪些文件；
3. 完成后如何验证；
4. 如果失败，应该先检查什么。
要求：
1. 每一步都要足够小；
2. 优先跑通核心流程；
3. 不要一开始就做装饰性功能；
4. 把测试和验证写进计划里。好的 PLAN 会让你每次只处理一个小问题。
对新手来说，这比“我要做一个完整项目”更容易开始。
D.14 生成 AGENTS.md
适合：你希望 Codex 以后在这个项目里更懂规矩。
请为当前项目生成 AGENTS.md。
请先阅读项目结构、README、现有脚本和技术栈。
AGENTS.md 需要说明：
1. 项目是什么；
2. 常用命令；
3. 代码风格；
4. 目录约定；
5. 修改文件时的注意事项；
6. 测试和验证方式；
7. 不要做的事情；
8. 适合新 Agent 快速接手的背景信息。
要求：
1. 只写当前项目真实存在的命令和约定；
2. 不要编造不存在的脚本；
3. 内容简洁，但要足够可执行。AGENTS.md 可以理解成“给未来 AI 同事看的项目说明”。
写得越清楚，后续协作越省心。
D.15 创建 Skill 草稿
适合：把重复流程沉淀成可复用能力。
我想创建一个 Skill，用来处理这个重复任务：
【描述任务】
这个任务的输入通常是：
【文件、文本、链接、表格、指令等】
期望输出是：
【文档、报告、代码、表格、消息草稿等】
请先帮我设计 Skill：
1. Skill 名称；
2. 适用场景；
3. 不适用场景；
4. 执行流程；
5. 需要的命令或工具；
6. 失败时如何处理；
7. 示例提示词。
先不要创建文件，先给我设计草案。等设计确认后，再让 Codex 写 Skill 文件：
请根据刚才确认的设计，创建这个 Skill 的目录和 SKILL.md。
完成后检查是否有缺失步骤或模糊描述。D.16 会议纪要模板
适合：整理会议录音转写、聊天记录、会议笔记。
请把下面的会议内容整理成会议纪要：
【粘贴会议内容】
请输出：
1. 会议主题；
2. 参会角色；
3. 关键结论；
4. 讨论要点；
5. 待办事项；
6. 每个待办的负责人、截止时间、依赖条件；
7. 仍未明确的问题；
8. 适合发到群里的简短版本。
要求：
1. 不要编造没有出现的信息；
2. 如果负责人或截止时间不明确，请标注“待确认”；
3. 待办事项要可执行，不要写成空泛口号。会议纪要最怕“看起来很完整，但任务没人能执行”。
所以一定要让 Codex 明确负责人、时间和待确认项。
D.17 周报模板
适合：把零散工作整理成周报。
请把下面的工作记录整理成周报：
【粘贴本周工作记录】
周报结构：
1. 本周完成；
2. 关键成果；
3. 遇到的问题；
4. 下周计划；
5. 需要协助的事项；
6. 一句话总结。
要求：
1. 语气专业但不要浮夸；
2. 结果尽量量化；
3. 不要把过程写得太碎；
4. 如果信息不足，请列出需要我补充的问题。如果是给领导看的周报，可以追加：
请把重点放在结果、影响和下周风险上，减少流水账。D.18 客户跟进模板
适合：销售、运营、客户成功。
请根据下面的客户沟通记录，整理跟进建议：
【粘贴沟通记录】
请输出：
1. 客户当前需求；
2. 客户关心的问题；
3. 明确表达过的异议；
4. 可能的成交阻力；
5. 下一步跟进动作；
6. 建议发送给客户的消息草稿；
7. 内部备注。
要求：
1. 不要过度推销；
2. 先回应客户真实关切；
3. 消息草稿要自然、简短、可直接发送前再人工确认；
4. 不要编造客户没说过的信息。这类模板尤其要注意边界。
AI 可以帮你整理和起草，但最终发送前一定要由人确认。
D.19 多 Agent 协作模板
适合：任务很多，可以并行分析或实现。
这个任务比较大：
【描述任务】
请先判断哪些部分可以并行，哪些部分必须串行。
请输出：
1. 总目标；
2. 可以并行的子任务；
3. 每个子任务的输入、输出和文件范围；
4. 哪些任务不能同时改同一批文件；
5. 主线任务应该先做什么；
6. 最后如何合并和验证。
在拆清楚之前，不要直接开始实现。多 Agent 不是越多越好。
如果任务边界没拆清楚，多开几个 Agent 只会让冲突变多。
D.20 最终交付检查模板
适合：准备收尾前，让 Codex 做最后检查。
请对当前项目做最终交付检查。
重点检查：
1. 需求是否都完成；
2. 文件结构是否清楚；
3. README 是否能指导新用户运行；
4. 测试或验证命令是否通过；
5. 页面或输出结果是否符合预期；
6. 是否还有 TODO、占位内容、空链接、坏路径；
7. 是否有明显安全风险或隐私风险；
8. 是否有我应该知道但还没处理的遗留问题。
请先列出检查项和结论。
如果发现问题，请按严重程度排序，并说明建议修复方式。交付前多问这一句，往往能省掉很多返工。
D.21 提示词自检清单
写 Prompt 时，可以快速检查这 7 件事：
- 我有没有说清楚目标？
- 我有没有说明背景和受众？
- 我有没有给出输入材料？
- 我有没有写清楚输出格式？
- 我有没有说明不要做什么？
- 我有没有要求验证方式？
- 我有没有让 Codex 先问问题，而不是盲目开工？
如果你懒得记，就记住这一句话：
请先判断我的需求是否清楚；如果不清楚，先问问题；如果清楚，再分步骤执行，并在完成后验证。这句话几乎可以放在所有任务后面。
它会让 Codex 从“直接生成答案”，变成“先理解任务，再完成任务”。
这就是从会用到用顺手的分界线。
附录E 配图与截图补充清单
这一附录专门用来管理文档里的配图。
当前 Markdown 正文已经保留了全部文字内容，并用本地 SVG 示意图替换了原来的图片缺失占位。
后续如果要替换成真实产品截图，不建议随便找几张图塞进去。更好的做法是：每一张图都服务于一个教学目的，让读者看完图以后更容易理解当前小节。
E.1 补图基本规范
建议把图片统一放在这个目录：
assets/images/建议命名方式：
p01-cover.svg
p02-reader-note.svg
p03-chapter-1-overview.svg图片尺寸建议：
- 截图：宽度 1400px 左右，保留清晰文字。
- 示意图：优先使用 16:9，适合文章阅读和课程投屏。
- 手机截图：可用 9:16，但要避免过长。
- 文件格式：当前占位示意图使用 SVG；真实截图建议用 PNG，照片或大图用 JPG。
- 隐私处理：账号、邮箱、路径、API Key、公司内部信息必须打码。
插入 Markdown 时建议使用：
不要只写“图片”两个字。
好的图片说明应该让读者即使看不到图片，也知道它大概表达什么。
E.2 P01-P02：开头区域
#### P01 封面或课程主视觉
对应位置：标题下方第一处配图。
建议文件名：
assets/images/p01-cover.svg建议画面：
- 左侧是标题“Codex 入门与实战指南”。
- 右侧可以是 Codex 桌面 App、终端窗口、项目文件夹的组合截图。
- 画面重点突出“从一句话到可交付结果”。
用途：
让读者第一眼知道这不是纯理论文章，而是一套实战教程。
推荐说明：
#### P02 读者互动或课程说明图
对应位置：开头“欢迎点赞、评论、纠错”附近。
建议文件名：
assets/images/p02-reader-note.svg建议画面：
- 可以是文章评论区、批注区或学习社群截图。
- 也可以是“发现错误 - 评论指出 - 作者更新”的简单流程图。
用途：
告诉读者这篇教程会持续更新，也鼓励他们参与纠错。
推荐说明：
E.3 P03-P10：第1章配图
#### P03 第1章开篇图
对应位置：第1章标题下方。
建议文件名：
assets/images/p03-chapter-1-overview.svg建议画面：
- 一张“三件事”概览图：Codex 是什么、和普通 AI 的区别、为什么适合真实任务。
- 可以做成简洁的三栏卡片。
用途：
帮助新手建立本章学习地图。
推荐说明：
#### P04 Codex 一句话解释图
对应位置：1.1 一句话解释 Codex。
建议文件名：
assets/images/p04-codex-one-sentence.svg建议画面：
- 左边是“普通对话 AI：回答问题”。
- 右边是“Codex：读取文件、执行命令、修改项目、持续推进”。
- 用箭头串起“需求 - 文件 - 执行 - 验证 - 修改”。
用途：
把“数字员工”的抽象概念变成可视化流程。
推荐说明：
#### P05 普通聊天式 AI 与 Codex 对比图
对应位置：1.2 和普通聊天式 AI 有什么区别。
建议文件名：
assets/images/p05-chat-ai-vs-codex.svg建议画面：
对比表格即可：
- 普通聊天式 AI：解释概念、生成文本、给建议。
- Codex：理解项目、修改文件、运行命令、做验证、持续协作。
用途：
让读者快速明白两者不是同一种工作方式。
推荐说明：
#### P06 真实任务推进链路图
对应位置：1.3 为什么更适合做真实任务。
建议文件名：
assets/images/p06-real-task-flow.svg建议画面：
一个横向流程：
看资料 -> 拆任务 -> 改文件 -> 运行检查 -> 修问题 -> 输出结果每一步下面加一个很短的例子。
用途：
说明真实任务不是一次问答，而是一串连续动作。
推荐说明：
#### P07 小白理解 Codex 的类比图
对应位置：1.4 小白第一次应该怎么理解 Codex。
建议文件名：
assets/images/p07-digital-assistant-metaphor.svg建议画面：
- 中间写“数字助手”。
- 周围四个能力：看文件、听需求、动手改、继续验证。
- 风格保持清爽，不要做成科幻机器人。
用途：
用低门槛类比降低新手压力。
推荐说明：
#### P08 误区一：高级搜索框
对应位置：1.5 新手常见误区之“把 Codex 当成高级搜索框”。
建议文件名：
assets/images/p08-misunderstanding-search-box.svg建议画面：
左侧是零散提问：
什么是 HTML？
怎么写按钮？
怎么改颜色？右侧是任务式表达：
请帮我做一个个人介绍页，并完成检查。用途：
告诉读者要从“问问题”转向“交付任务”。
推荐说明：
#### P09 误区二：不会编程不能用
对应位置：1.5 新手常见误区之“不会编程就不能用 Codex”。
建议文件名：
assets/images/p09-non-programmer-can-use.svg建议画面：
列出非程序员也能做的任务：
- 整理会议纪要。
- 分析 CSV。
- 生成 HTML 报告。
- 改写教程。
- 做小工具原型。
用途：
缓解零基础读者的门槛焦虑。
推荐说明：
#### P10 误区三：一上来研究所有配置
对应位置：1.5 新手常见误区之“一上来就研究所有配置”。
建议文件名：
assets/images/p10-config-overload.svg建议画面：
一个简单阶梯：
先会用 -> 再会改 -> 再理解配置 -> 再做自动化用途：
提醒读者学习顺序，不要被 config、model、provider 这些词吓住。
推荐说明：
E.4 P11-P17：第2章配图
#### P11 “能帮我省什么事”场景图
对应位置：2.1 先问“能帮我省什么事”。
建议文件名：
assets/images/p11-save-time-scenarios.svg建议画面：
用四象限呈现：
- 文档整理。
- 数据分析。
- 页面生成。
- 项目推进。
用途：
把 Codex 的价值从“厉不厉害”转成“省哪些重复劳动”。
推荐说明：
#### P12 文档和资料整理图
对应位置：2.2 整理文档和资料。
建议文件名：
assets/images/p12-document-processing.svg建议画面：
零散资料 -> Codex 归类整理 -> 结构化文档可以展示 Markdown、会议记录、网页资料、笔记的组合。
用途：
说明内容整理是最适合新手上手的场景之一。
推荐说明：
#### P13 项目文件理解图
对应位置：2.3 处理文件和理解项目。
建议文件名：
assets/images/p13-project-folder-understanding.svg建议画面：
左边是一棵项目目录树，右边是 Codex 生成的“项目结构说明”。
用途：
帮助读者理解“让 Codex 先读文件夹”这件事。
推荐说明：
#### P14 数据分析结果图
对应位置：2.4 分析数据和生成结果。
建议文件名：
assets/images/p14-data-analysis-report.svg建议画面：
一张 CSV 表格加一份图表报告的对照：
原始 CSV -> 清洗 -> 图表 -> 结论摘要用途：
让不会代码的读者看到数据文件也能变成可读报告。
推荐说明：
#### P15 网页、原型和小工具图
对应位置：2.5 生成网页、原型和小工具。
建议文件名：
assets/images/p15-web-prototype-tool.svg建议画面：
展示一个简单页面从提示词到浏览器预览的过程。
用途：
强化“结果能直接看见”的体验。
推荐说明：
#### P16 代码开发协作图
对应位置：2.6 代码开发。
建议文件名：
assets/images/p16-code-development.svg建议画面：
可以是真实编辑器截图，展示：
- 左侧文件树。
- 中间代码。
- 右侧 Codex 对话或变更说明。
用途：
说明 Codex 的核心能力之一是和代码项目一起工作。
推荐说明：
#### P17 任务推进闭环图
对应位置：2.7 把任务“往前推进”。
建议文件名：
assets/images/p17-task-progress-loop.svg建议画面：
一个闭环：
提出目标 -> 拆步骤 -> 执行 -> 检查 -> 继续补充用途：
承接第2章总结：Codex 的价值在于持续推进，而不是单次回答。
推荐说明：
E.5 P18-P22：第3章配图
#### P18 Codex 三种形态总览
对应位置：3.1 为什么 Codex 会有不同形态。
建议文件名：
assets/images/p18-three-forms-overview.svg建议画面：
三列对比：
- 桌面版 App：适合新手。
- 命令行 CLI：适合自动化和进阶任务。
- IDE 插件：适合代码编辑场景。
用途：
让读者先建立整体地图，再分别理解每种入口。
推荐说明：
#### P19 桌面版 App 截图
对应位置：3.2 桌面版 APP：最适合新手的入口。
建议文件名：
assets/images/p19-codex-desktop-app.svg建议画面：
真实桌面版 App 截图，重点保留：
- 对话输入区。
- 当前工作区。
- 文件或任务状态。
- Codex 的执行反馈。
用途：
给新手一个直观入口，降低“我不知道打开后长什么样”的不确定感。
推荐说明：
#### P20 CLI 终端截图
对应位置：3.3 命令行 CLI：更适合进阶用户和自动化场景。
建议文件名：
assets/images/p20-codex-cli-terminal.svg建议画面：
终端里运行 Codex 的截图，保留一段简短对话即可。
不要放太复杂的命令。
用途：
让读者知道 CLI 不是神秘黑盒，本质也是通过文字和 Codex 协作。
推荐说明：
#### P21 IDE 插件入口截图
对应位置：3.4 IDE 插件：适合已经在写代码的人，第一处配图。
建议文件名：
assets/images/p21-ide-plugin-entry.svg建议画面：
IDE 左侧或右侧打开 Codex 插件面板的截图。
用途：
展示 Codex 如何嵌入写代码的软件里。
推荐说明：
#### P22 IDE 插件协作截图
对应位置：3.4 IDE 插件：适合已经在写代码的人，第二处配图。
建议文件名：
assets/images/p22-ide-plugin-code-change.svg建议画面：
展示插件根据指令修改代码，旁边有变更 diff 或文件高亮。
用途：
补充说明插件版最适合“边写代码边让 AI 帮忙修改”的场景。
推荐说明：
E.6 补图完成后的检查模板
图片补完后，可以把下面这段话复制给 Codex：
请检查当前 Markdown 文档的图片引用。
检查内容：
1. 所有图片路径是否存在；
2. 图片说明是否清楚；
3. 是否还有“配图待补”占位；
4. 图片是否放在合适的小节；
5. 是否有敏感信息没有打码；
6. Markdown 是否能正常预览。
如果发现问题，请列出图片编号、问题原因和建议修复方式。等这一步完成，文档就会从“文字完整”进一步变成“图文完整”。
附录F 发布前检查清单
这一附录适合在真正发布前使用。
长教程最容易出现的问题，不一定是内容不够，而是细节不一致：目录写了但正文没有、图片路径错了、代码块没闭合、旧版说明没删干净、某些命令已经过时、读者跟着做却不知道下一步。
发布前不需要把文章改得完美，但至少要做到：读者能读、能跟、能复现，遇到问题知道去哪里看。
F.1 目录与结构检查
先看大结构。
检查项：
- 目录里的章节是否都能在正文中找到。
- 正文里是否有目录没有列出的章节。
- 章节编号是否连续。
- 附录编号是否连续。
- 标题层级是否稳定，是否出现了不该有的一级标题。
- “第一部分、第二部分”这类分组是否和正文一致。
- 更新日志里是否还保留旧结构说法。
可以让 Codex 这样检查：
请检查当前 Markdown 文档的目录和标题结构。
重点看：
1. 目录章节是否和正文标题一致；
2. 章节编号是否连续；
3. 附录编号是否连续；
4. 是否存在旧版章节名、旧版部分名、错误跳转说明；
5. 是否有多余的一级标题。
请输出问题清单和建议修复方式。F.2 图片与附件检查
图片最容易在迁移时丢失。
检查项：
- 所有图片路径是否存在。
- 图片文件名是否清楚。
- 图片说明是否能解释图片内容。
- 是否还有旧的 Obsidian 图片语法。
- 是否还有空图片链接。
- 是否有账号、邮箱、API Key、内部路径没有打码。
- 是否有图片太大，影响加载。
当前整理版已经把 22 张缺失图片替换成本地 SVG 示意图。
如果后续替换成真实截图，请先检查截图里是否包含敏感信息。
可以让 Codex 这样检查：
请检查当前 Markdown 文档中的所有图片引用。
请确认：
1. 引用路径是否存在；
2. 是否有空图片链接；
3. 是否有 Obsidian 图片语法；
4. 图片说明是否清楚；
5. 是否有疑似敏感信息需要打码。
请按图片路径列出检查结果。F.3 代码块与命令检查
教程里只要有代码块，就要特别小心。
检查项：
- 所有代码块是否成对闭合。
- 命令是否适合目标系统。
- 危险命令是否有提醒。
- 示例路径是否和文章上下文一致。
- 配置示例是否明确“仅供参考”。
- 是否把真实 token、密钥、账号写进示例。
- 是否有命令已经过时，需要提醒读者以官方文档为准。
可以让 Codex 这样检查：
请检查当前 Markdown 文档里的代码块和命令。
重点看：
1. 代码块是否全部闭合；
2. 命令是否可能对新手造成误导；
3. 是否存在危险命令但没有提醒；
4. 是否出现真实密钥、账号、token；
5. 哪些命令可能需要以官方文档为准。
请按严重程度排序输出。F.4 新手可读性检查
这篇教程的目标读者是零基础新手，所以可读性很重要。
检查项：
- 每一章开头是否说明读者会学到什么。
- 专业术语是否有解释。
- 步骤之间是否有过渡。
- 示例是否足够具体。
- 是否有“懂的人自然懂”的跳步。
- 是否有长段落可以拆短。
- 是否告诉读者遇到问题时怎么继续。
可以让 Codex 这样检查：
请从零基础读者角度检查这篇教程。
重点看：
1. 哪些地方可能看不懂；
2. 哪些术语第一次出现时缺少解释；
3. 哪些步骤跳得太快；
4. 哪些例子可以更具体；
5. 哪些段落太长，建议拆分。
请给出修改建议，不要直接改正文。F.5 事实与时效性检查
AI 工具变化很快。
凡是涉及安装方式、模型名称、产品入口、账号权限、价格、系统支持、API、官方命令的内容，都可能随着时间变化。
检查项：
- 是否写死了可能变化的安装命令。
- 是否把某个模型名称写成永久推荐。
- 是否引用了可能变更的产品入口。
- 是否写了价格、套餐、权限，但没有说明时效。
- 是否把第三方工具能力说得过满。
- 是否提醒读者以官方文档和当前界面为准。
比较稳妥的写法是：
具体命令可能随版本变化，请以官方文档和当前安装页面为准。不太稳妥的写法是：
永远只需要执行这个命令。可以让 Codex 这样检查：
请检查当前文档中可能过时的内容。
重点找：
1. 安装命令；
2. 模型名称；
3. 产品入口；
4. 账号权限；
5. 第三方工具；
6. API 或 CLI 参数。
请标出原文位置，并建议更稳妥的表述。F.6 安全与隐私检查
发布教程前，一定要检查隐私。
检查项：
- 是否出现真实姓名、手机号、邮箱、地址。
- 是否出现 API Key、token、cookie、登录凭证。
- 是否出现公司内部项目名、客户名、合同信息。
- 是否出现本地绝对路径，暴露用户名或目录结构。
- 截图里是否有浏览器书签、聊天记录、账号头像。
- 示例数据是否能反推出真实个人或业务信息。
可以让 Codex 这样检查：
请从安全和隐私角度检查这篇教程。
重点看：
1. 是否有真实账号、邮箱、手机号；
2. 是否有 token、API Key、cookie；
3. 是否有公司、客户、项目敏感信息；
4. 是否有本地绝对路径；
5. 是否有截图说明需要打码。
请只列出风险位置和处理建议，不要复述敏感内容。F.7 发布平台适配检查
不同平台对 Markdown 的支持不一样。
发布前最好按平台单独检查一次。
#### 发到公众号
重点检查：
- 图片是否能上传。
- 代码块是否会丢样式。
- 表格是否太宽。
- 小标题是否层级清楚。
- 超链接是否需要改成文字说明。
#### 发到飞书文档
重点检查：
- 标题层级是否保留。
- 代码块是否正常。
- 图片是否能随文档保存。
- 表格是否能横向滚动。
- 是否需要添加目录块。
#### 发到 GitHub 或知识库
重点检查：
- 相对图片路径是否正确。
- README 或入口说明是否清楚。
- 文件名是否有空格导致链接不稳定。
- 是否需要把图片压缩。
- 是否需要添加许可证或引用说明。
F.8 最后一轮人工通读
机器检查很有用，但不能代替人工通读。
最后建议按这三个问题读一遍：
- 一个完全没接触过 Codex 的人，能不能知道从哪里开始？
- 一个已经会用一点 Codex 的人，能不能找到进阶路线？
- 一个想照着做项目的人，能不能拿到模板、Prompt 和检查清单？
如果这三个问题答案都是“能”，这篇教程就已经具备发布价值。
F.9 一键发布前检查 Prompt
发布前，可以直接把下面这段话发给 Codex：
请对当前 Markdown 教程做发布前总检查。
检查范围：
1. 目录和标题结构；
2. 图片和附件路径；
3. 代码块和命令；
4. 新手可读性；
5. 事实时效性；
6. 安全与隐私；
7. 发布平台适配；
8. 是否还有旧版说明、占位内容、空链接和不一致表述。
请输出：
1. 总体结论；
2. 必须修复的问题；
3. 建议优化的问题；
4. 可以保留不处理的问题；
5. 发布前最后建议。
先不要直接修改正文。如果检查结果里没有必须修复的问题，再让 Codex 执行：
请根据刚才的检查结果，只修复必须修复的问题。
不要做无关改写。
修改后再次运行结构、图片、代码块和链接检查。这就是发布前最稳的一步。
附录G 官方资料与延伸阅读
这一附录不是让你一次性读完所有官方文档。
它的作用更像一张地图：当教程里的某个工具、命令、模型、套餐、入口发生变化时，你知道应该去哪里确认最新信息。
AI 工具变化很快，尤其是 Codex、Agents、MCP、Skills、模型和 API。教程可以帮你建立方法，但最终细节一定要回到官方页面确认。
本附录链接检查日期：2026-05-21。
引用规范：正文里凡是出现“官方文档”“官方说明”“官方推荐”这类表述，都必须能回到本附录中的具体链接；如果没有对应链接，就改成“截至本教程整理时”或删掉“官方”二字。
G.1 Codex 入门和产品入口
如果你只想确认 Codex 当前有哪些形态、怎么开始、官方推荐入口在哪里，先看这些页面。
| 资料 | 适合什么时候看 | 访问日期 |
|---|---|---|
| OpenAI Developers | 找 OpenAI API、Codex、Apps SDK、示例、博客和社区入口。 | 2026-05-21 |
| Codex 官方文档首页 | 了解 Codex 文档总目录、使用场景、配置、插件、自动化和发布信息。 | 2026-05-21 |
| Codex App 文档 | 使用桌面版 App 时，看界面、功能、设置、浏览器、自动化等说明。 | 2026-05-21 |
| Codex CLI 文档 | 使用命令行版 Codex 时，看安装、命令、参数和终端工作流。 | 2026-05-21 |
| Using Codex with your ChatGPT plan | 确认 Codex 和 ChatGPT 套餐、登录、使用限制、数据控制相关说明。 | 2026-05-21 |
建议读法：
- 新手先看 Codex 官方文档首页。
- 用桌面版，就看 App 文档。
- 用终端，就看 CLI 文档。
- 账号、套餐、额度、数据控制问题，优先看 Help Center。
不要把某个截图里的按钮位置当成永久不变。
界面会改，入口会挪，官方页面才是当前版本的准绳。
G.2 项目协作、配置和扩展能力
教程里多次提到 AGENTS.md、MCP、Skills。它们是把 Codex 从“单次问答”升级成“项目协作”的关键。
| 资料 | 适合什么时候看 | 访问日期 |
|---|---|---|
| AGENTS.md 官方说明 | 想让 Codex 长期记住项目规则、代码风格、验证方式时看。 | 2026-05-21 |
| Codex 配置文档 | 核对 ~/.codex/config.toml、项目级 .codex/config.toml、配置优先级和常用字段时看。 | 2026-05-21 |
| Codex MCP 文档 | 想让 Codex 连接外部工具、服务、资料源时看。 | 2026-05-21 |
| Codex Skills 文档 | 想把重复流程沉淀成可复用 Skill 时看。 | 2026-05-21 |
建议读法：
- 先读 AGENTS.md，因为它最贴近普通项目。
- 再读 Skills，因为它适合把个人经验沉淀下来。
- 最后读 MCP，因为它涉及外部系统连接，权限和安全边界更重要。
如果你只是刚入门，不需要一上来就配置 MCP。
先学会把任务说清楚、把项目文档写清楚，再考虑连接更多工具。
G.3 API、Agents 和应用开发
当你不只是使用 Codex，而是想自己开发 AI 应用、智能体平台、自动化工作流时，再看这一组资料。
| 资料 | 适合什么时候看 | 访问日期 |
|---|---|---|
| Agents SDK 文档 | 想构建有工具、上下文、交接、追踪能力的 Agent 应用时看。 | 2026-05-21 |
| Responses API 迁移指南 | 从旧接口或 Chat Completions 思路迁移到 Responses API 时看。 | 2026-05-21 |
| Responses API Reference | 需要查具体接口参数、响应字段、请求格式时看。 | 2026-05-21 |
建议读法：
- 做应用前，先确认当前推荐 API。
- 做 Agent 前，先判断是用 Codex 完成项目，还是用 API 自己开发一个 Agent 产品。
- 写代码时，不要凭记忆写参数，让 Codex 先查当前官方文档。
一个稳妥的提示词是：
请先查 OpenAI 当前官方文档，确认这个功能推荐使用哪个 API、SDK 和模型。
只引用官方来源。
确认后再给我设计实现方案。G.4 怎么让 Codex 帮你查官方资料
很多新手会直接问：
现在怎么安装 Codex？更稳的问法是：
请查 OpenAI 官方文档，确认当前 Codex CLI 的安装方式。
请给出官方链接、更新时间或页面名称。
如果教程里的命令和官方页面不一致，以官方页面为准。如果是 API 问题，可以这样问：
请查 OpenAI 官方文档，确认当前是否推荐使用 Responses API。
请说明它和旧的 Chat Completions 思路有什么差别。
不要引用非官方博客作为主要依据。如果是模型问题，可以这样问：
请查 OpenAI 官方文档，确认当前适合这个任务的模型选择。
任务背景是：【填写任务】
输出要求是：【填写速度、成本、质量、上下文、工具调用等要求】
请不要只给模型名，也说明选择理由和替代方案。G.5 资料更新记录怎么维护
如果你打算长期维护这篇教程，建议每次更新都记录三件事：
- 检查日期。
- 检查了哪些官方页面。
- 哪些正文内容因为官方变化做了调整。
可以在文档末尾保留一个简单记录：
### 官方资料复查记录
- 2026-05-21：复查 OpenAI Developers、Codex 文档首页、Codex App、Codex CLI、AGENTS.md、MCP、Skills、Agents SDK、Responses API 相关页面。这样做的好处是：读者能知道哪些内容是近期核过的，哪些内容需要自己再确认。
G.6 官方资料复查记录
- 2026-05-21：复查 OpenAI Developers、Codex 文档首页、Codex App、Codex CLI、AGENTS.md、MCP、Skills、Agents SDK、Responses API 迁移指南和 ChatGPT plan 下的 Codex Help Center 页面。
附录H 读者常见问题 FAQ
这一附录用来回答新手最常见的问题。
如果你读完整篇教程后还是有点乱，先别急着回头重读 47 章。很多时候，你缺的不是更多内容，而是几个关键问题的答案。
H.1 我完全不会编程，可以学 Codex 吗？
可以。
但不要一上来就从“写复杂程序”开始。
更适合你的顺序是：
- 先让 Codex 整理文档。
- 再让它生成一个简单网页。
- 再让它分析一份 CSV。
- 再学习怎么写 README、PRD、DESIGN、PLAN。
- 最后再进入代码项目。
不会编程并不妨碍你使用 Codex。
真正重要的是：你能不能把目标说清楚，能不能判断结果有没有满足目标。
H.2 我应该先用桌面 App，还是先用 CLI？
新手优先用桌面 App。
原因很简单：界面更直观，操作压力小，也更容易看到文件、对话和任务状态。
CLI 更适合这些情况：
- 你已经习惯终端。
- 你想把 Codex 放进自动化流程。
- 你经常处理代码仓库。
- 你需要更明确地控制命令和参数。
如果你不确定选哪个，就先从桌面 App 开始。
能做出结果，比一开始选对“高级入口”更重要。
H.3 Codex 和 ChatGPT 到底有什么区别？
可以先这样理解：
ChatGPT 更像一个对话助手，适合解释、讨论、生成内容。
Codex 更像一个项目助手，适合进入文件夹、读取项目、修改文件、执行命令、检查结果。
当然，这不是绝对边界。
ChatGPT 也可以帮你写代码，Codex 也可以和你讨论想法。区别在于：Codex 更强调“在工作现场推进任务”。
H.4 使用 Codex 一定需要 API Key 吗？
不一定。
具体取决于你使用的入口、账号方式和当前产品规则。
对新手来说，不要先纠结 API Key。你应该先确认：
- 当前使用的是 Codex App、CLI、IDE 插件还是 Web。
- 是否可以用 ChatGPT 账号登录。
- 当前官方文档对登录方式怎么说。
- 你的账号套餐是否支持对应入口。
凡是账号、套餐、额度、登录方式相关问题，都建议以当前官方说明为准。
H.5 我为什么要写 README、PRD、DESIGN、PLAN？
因为大任务最怕“边做边猜”。
这四份文档各自解决一个问题：
| 文档 | 解决什么问题 |
|---|---|
| README | 这个项目是什么，怎么运行。 |
| PRD | 做什么，不做什么，给谁用。 |
| DESIGN | 准备怎么实现，模块怎么分。 |
| PLAN | 分几步做，每步怎么验证。 |
没有这些文档，Codex 很容易在长任务里越做越偏。
写文档不是为了显得专业，而是为了减少误解。
H.6 AGENTS.md 和这四份文档有什么区别？
四份文档是项目材料。
AGENTS.md 是给 Codex 的协作规则。
比如：
- README 告诉人和 AI：项目是什么。
- PRD 告诉人和 AI：需求是什么。
- DESIGN 告诉人和 AI：方案是什么。
- PLAN 告诉人和 AI：下一步怎么做。
- AGENTS.md 告诉 AI：在这个项目里应该遵守什么规则。
可以把 AGENTS.md 理解成“给未来 AI 同事看的项目工作守则”。
H.7 什么时候需要 MCP？
当你需要 Codex 连接外部系统时，才需要认真考虑 MCP。
比如：
- 查公司内部文档。
- 访问知识库。
- 操作项目管理系统。
- 连接数据库或业务工具。
- 调用某个服务里的数据。
如果你只是做本地文档、简单网页、CSV 分析、小工具项目，通常不需要一开始就配置 MCP。
先把基础协作跑顺，再接外部系统。
H.8 什么时候需要 Skill？
当你发现自己反复做同一种任务时，就可以考虑 Skill。
比如你经常让 Codex：
- 检查 Markdown。
- 整理会议纪要。
- 改写教程。
- 分析表格。
- 生成周报。
- 做发布前检查。
如果一件事你已经重复说过三次以上，就可以考虑把它沉淀成 Skill。
Skill 的价值不是“看起来高级”，而是让好流程可以复用。
H.9 我可以让 Codex 直接改文件吗？
可以，但要看场景。
适合直接改的情况：
- 修改范围很小。
- 文件不重要，或已经有备份。
- 你知道自己想要什么。
- 可以通过测试或预览验证。
不适合直接改的情况：
- 需求还很模糊。
- 文件很重要，没有备份。
- 涉及大量删除、迁移、重构。
- 你自己也不知道结果应该长什么样。
一个稳妥说法是：
请先阅读相关文件，给出修改计划。
我确认后再开始改。H.10 Codex 改错了怎么办？
先不要慌，也不要连续让它“再试试”。
建议按这个顺序处理：
- 停止继续扩展功能。
- 让 Codex 总结刚才改了哪些文件。
- 查看具体 diff 或文件变化。
- 如果项目有 git，优先用 git 找回。
- 如果没有 git，让 Codex 根据原需求反向修复。
- 修复后立刻补一个验证步骤。
更重要的是：以后做项目时尽早使用 git。
没有版本记录，任何 AI 协作都会更危险。
H.11 为什么 Codex 有时候会越改越乱？
常见原因有四个：
- 需求太模糊。
- 一次让它改太多。
- 没有项目文档。
- 没有每一步验证。
解决办法也很朴素：
- 把任务拆小。
- 每次只改一个目标。
- 改前先让它读文件。
- 改后马上验证。
- 长任务写 PLAN。
Codex 很强，但它不是读心术。
你给它的边界越清楚，它越稳定。
H.12 输出结果不满意，应该怎么让它改？
不要只说：
不对，重写。更好的说法是：
这版有三个问题：
1. 语气太正式；
2. 示例不够具体；
3. 第三部分和前文重复。
请只修改这三个问题，保留其他内容。修改反馈要尽量具体。
Codex 不怕你提要求，怕的是你只表达情绪，不指出问题。
H.13 做项目时，我应该一次说完整需求吗？
不用。
一开始只要说清楚最小目标。
比如：
我想做一个本地记账网页。
第一版只需要添加收入、支出，并显示余额。
先不要做登录、云同步、图表和导出。
请先帮我写 PRD。这比“做一个完整记账系统”稳定得多。
先做最小可用版本，再一点点加功能。
H.14 Codex 生成的代码能直接上线吗？
不建议。
至少要先做这些检查：
- 本地能不能运行。
- 核心流程能不能走通。
- 错误输入会不会崩。
- 是否有敏感信息泄露。
- 是否有基本测试。
- 是否有 README。
- 是否有人类 review 过关键逻辑。
Codex 可以大幅加速开发，但上线仍然需要工程检查。
尤其是支付、账号、权限、数据删除、隐私、安全相关功能，不能只靠生成结果。
H.15 我应该怎么保护隐私？
记住一个原则：不要把不能公开的信息交给不确定的工具链。
尤其注意：
- API Key。
- token。
- cookie。
- 登录凭证。
- 客户名单。
- 合同和报价。
- 内部代码。
- 未公开数据。
- 带账号信息的截图。
如果必须让 Codex 处理敏感材料，先做脱敏。
比如把真实姓名换成“客户A”，把真实邮箱换成“[email protected]”。
H.16 我只会说“继续”，可以吗？
可以，但不建议长期只说“继续”。
当任务已经很明确时，“继续”很高效。
但如果你发现方向开始偏，最好补一句具体要求：
继续，但优先补案例，不要再讲概念。或者：
继续，先检查结构，再补下一章。“继续”适合推进，“具体继续什么”适合控方向。
H.17 我怎么判断自己已经入门？
你不需要背下所有术语。
只要能完成下面这些事，就算真正入门：
- 能让 Codex 阅读一个文件夹。
- 能清楚描述一个小任务。
- 能让它修改一个文件。
- 能看懂它改了什么。
- 能让它运行检查。
- 能把结果继续改到能用。
- 能在任务变大时写 PLAN。
入门不是“什么都懂”，而是“能把一个小任务做完”。
H.18 我怎么判断自己正在进阶？
进阶的标志不是会背更多命令。
进阶的标志是你开始有流程意识：
- 做任务前先定范围。
- 改文件前先读上下文。
- 长任务先写 PLAN。
- 项目里维护 AGENTS.md。
- 常见流程沉淀成 Skill。
- 外部工具谨慎接入 MCP。
- 完成前主动验证。
当你开始这样使用 Codex，它就不再只是“帮你生成内容的工具”，而是进入你的工作流。
H.19 遇到官方文档和教程不一致怎么办？
以官方文档为准。
这篇教程更重视方法和学习路径，但具体命令、入口、模型、套餐、按钮位置都会变化。
遇到不一致时，你可以这样问 Codex：
教程里是这样写的：【粘贴教程片段】
请查当前官方文档，判断这段是否过时。
如果过时，请给我一版更稳妥的改写。这也是维护长教程最重要的习惯。
H.20 读完这篇教程后，我下一步做什么？
最好的下一步不是继续读更多文章，而是做一个小项目。
建议选一个 1 小时内能完成的任务：
- 个人介绍页。
- 本地记账页。
- CSV 分析报告。
- 会议纪要整理器。
- Markdown 检查器。
- 小红书选题生成器。
要求很简单：
- 写 README。
- 写 PRD。
- 写 PLAN。
- 让 Codex 实现第一版。
- 运行检查。
- 写下你遇到的三个问题。
能完成这一轮，你就已经从“看教程的人”变成“会和 Codex 协作的人”。
附录I 课后练习与项目作业
这一附录是给读者“动手练”的。
不要一次做完。最好的节奏是：读完一部分，选一个练习做；做完后，把过程里的问题记下来，再回到对应章节复盘。
每个练习都包含四件事：
- 练习目标。
- 建议耗时。
- 起手 Prompt。
- 验收标准。
建议新建一个专门的练习目录：
codex-practice/每个练习单独一个子文件夹，避免互相污染。
I.1 练习一：让 Codex 认识一个空文件夹
适合阶段：刚安装完 Codex。
建议耗时：15 分钟。
练习目标：
- 学会让 Codex 观察当前目录。
- 学会让 Codex 说明它准备怎么做。
- 学会在还没写文件前先确认计划。
起手 Prompt：
这是一个新的练习文件夹。
请先查看当前目录，不要创建文件。
然后告诉我：
1. 当前目录里有什么；
2. 如果我要做一个练习项目，建议先建哪些文件；
3. 每个文件的作用是什么。验收标准：
- Codex 能正确说明当前目录状态。
- Codex 没有在你要求前直接创建文件。
- 你能说出 README、PRD、PLAN 至少三个文件的作用。
进阶要求：
让 Codex 生成一个最小项目结构，但不要写代码。
I.2 练习二：做一个个人介绍网页
适合阶段：读完第 7 章。
建议耗时：30-45 分钟。
练习目标：
- 从一句需求生成一个可打开网页。
- 学会提出修改意见。
- 学会检查移动端基本排版。
起手 Prompt：
请帮我做一个个人介绍网页。
目标读者：第一次认识我的合作伙伴。
页面包含：
1. 我的名字和一句话介绍；
2. 我能提供的 3 项帮助；
3. 过往经历或作品列表；
4. 联系方式区域。
要求：
1. 生成一个可以直接打开的 HTML 文件；
2. CSS 写在同一个文件里；
3. 页面简洁，手机和电脑都能看；
4. 完成后帮我检查是否有文字溢出、排版错位和明显问题。验收标准：
- 本地能打开 HTML。
- 页面有完整的四个区域。
- 手机宽度下内容不重叠。
- 你能提出至少 3 条修改意见，并让 Codex 改好。
进阶要求：
让 Codex 增加一个“作品筛选”或“常见问题”区域。
I.3 练习三：把一段杂乱笔记整理成教程
适合阶段：读完第 9-10 章。
建议耗时：30 分钟。
练习目标：
- 学会提供原始素材。
- 学会指定读者、语气和结构。
- 学会检查是否乱加内容。
起手 Prompt：
请把下面这段杂乱笔记整理成一篇新手教程。
目标读者：完全没接触过这个主题的人。
要求：
1. 保留原始信息，不要编造事实；
2. 按“背景、步骤、注意事项、常见错误、下一步”组织；
3. 语言通俗，每段不要太长；
4. 最后列出你不确定、需要我确认的信息。
原始笔记：
【粘贴你的笔记】验收标准：
- 输出结构清楚。
- 没有明显编造。
- 有“不确定信息”列表。
- 你能指出至少一处需要补充的素材。
进阶要求：
让 Codex 把教程再改成 60 秒口播稿。
I.4 练习四：分析一份 CSV 并生成结论
适合阶段：读完第 8 章和第 31 章。
建议耗时：45-60 分钟。
练习目标：
- 学会让 Codex 先理解字段。
- 学会让结论绑定数据依据。
- 学会区分“能回答”和“不能回答”的问题。
起手 Prompt：
请分析这个 CSV 文件：
【文件路径】
业务背景：
【说明这份数据是什么】
我想知道：
1. 数据里最明显的趋势是什么；
2. 是否存在异常值或缺失值；
3. 哪些结论可以用当前数据支持；
4. 哪些问题当前数据回答不了。
请先解释字段，再做分析。
所有结论都要说明来自哪些字段或计算。验收标准：
- Codex 能解释主要字段。
- 能指出缺失值或异常值。
- 结论有数据依据。
- 至少列出一个“当前数据回答不了”的问题。
进阶要求：
生成一个 HTML 图表报告，并要求图表有标题和解释。
I.5 练习五：为小项目补齐四文档
适合阶段：读完第 13-16 章。
建议耗时：60 分钟。
练习目标：
- 理解 README、PRD、DESIGN、PLAN 的分工。
- 学会先写文档，再写代码。
- 学会把需求缩小到最小可用版本。
起手 Prompt：
我想做一个小项目：
【一句话描述项目】
请先不要写代码。
请帮我生成四份文档：
1. README.md；
2. PRD.md；
3. DESIGN.md；
4. PLAN.md。
要求：
1. 第一版控制在 1 小时内能做出雏形；
2. 明确写出本版本不做什么；
3. PLAN 里的每一步都要有验证方式；
4. 如果需求不清楚，先问我 3 个问题。验收标准：
- 四份文档都生成。
- PRD 有“不做什么”。
- PLAN 每一步有验证方式。
- 你能指出第一版的核心流程。
进阶要求：
再让 Codex 生成 AGENTS.md。
I.6 练习六：用 PLAN 推进一次小修改
适合阶段：读完第 14 章。
建议耗时：30-45 分钟。
练习目标：
- 学会按计划执行，而不是让 Codex 随意发挥。
- 学会每完成一步就验证。
- 学会让 Codex 汇报修改范围。
起手 Prompt：
请根据当前 PLAN.md 执行第一步。
要求：
1. 只做第一步；
2. 不要提前做后续步骤；
3. 修改前告诉我会改哪些文件；
4. 修改后运行对应验证；
5. 最后汇报修改内容和验证结果。验收标准：
- Codex 没有越界做后续步骤。
- 修改文件范围清楚。
- 有验证结果。
- 你能判断下一步是否可以继续。
进阶要求：
故意在 PLAN 里写一个模糊步骤，让 Codex 先指出问题再执行。
I.7 练习七：整理一次会议纪要
适合阶段：读完第 29 章。
建议耗时：30 分钟。
练习目标：
- 学会从长文本提取结论和待办。
- 学会标注待确认项。
- 学会生成适合群发的简短版本。
起手 Prompt：
请把下面的会议记录整理成会议纪要。
输出：
1. 会议主题；
2. 关键结论；
3. 讨论要点；
4. 待办事项；
5. 每个待办的负责人、截止时间、状态；
6. 待确认问题；
7. 适合发到群里的 100 字摘要。
要求：
1. 不要编造负责人和截止时间；
2. 不明确的信息写“待确认”；
3. 待办事项要可执行。
会议记录：
【粘贴会议内容】验收标准：
- 有结论、要点、待办三类信息。
- 不明确内容被标成待确认。
- 群发摘要简洁可读。
- 待办不是空泛描述。
进阶要求：
让 Codex 把待办整理成任务清单表格。
I.8 练习八：创建一个自己的 Skill 草稿
适合阶段：读完第 18-20 章。
建议耗时：60 分钟。
练习目标：
- 学会识别重复任务。
- 学会把流程写成可复用说明。
- 学会区分 Skill 和普通 Prompt。
起手 Prompt：
我想创建一个 Skill 草稿，用来处理这个重复任务：
【描述任务】
请先不要创建文件。
请帮我设计：
1. Skill 名称；
2. 适用场景；
3. 不适用场景；
4. 输入材料；
5. 输出结果；
6. 执行步骤；
7. 失败处理；
8. 示例 Prompt。验收标准：
- Skill 有明确适用场景。
- 有“不适用场景”。
- 执行步骤不是一句话带过。
- 示例 Prompt 可以直接复制使用。
进阶要求：
让 Codex 生成 SKILL.md 初稿，并检查是否有模糊描述。
I.9 练习九：做一次发布前检查
适合阶段：读完附录 F。
建议耗时：30 分钟。
练习目标：
- 学会从交付角度检查文档或项目。
- 学会区分必须修复和建议优化。
- 学会控制修改范围。
起手 Prompt：
请对当前项目做发布前检查。
重点检查：
1. 目录和文件结构；
2. README 是否清楚；
3. 图片和链接是否有效；
4. 代码块和命令是否可信；
5. 是否有隐私或安全风险；
6. 是否有旧版说明、占位内容、空链接；
7. 是否有必须修复的问题。
请先只输出检查报告，不要直接修改。验收标准：
- 检查报告分出严重程度。
- 必须修复和建议优化分开。
- 没有直接乱改文件。
- 你能决定先修哪一项。
进阶要求：
让 Codex 只修复“必须修复”的问题，并再次检查。
I.10 练习十：从 0 到 1 做一个本地小工具
适合阶段：读完整篇教程后。
建议耗时：2-4 小时。
练习目标：
- 完整经历一次需求、设计、计划、实现、验证、总结。
- 学会把 Codex 当作协作伙伴，而不是一次性生成器。
- 学会在项目中留下文档和复盘。
推荐题目任选一个：
- Markdown 空链接检查器。
- CSV 字段解释和质量检查器。
- 本地记账网页。
- 会议纪要整理器。
- 公众号标题生成器。
- 图片素材命名整理器。
起手 Prompt：
我想做一个 2 小时内能完成的本地小工具：
【填写题目】
请先不要写代码。
请先完成：
1. 问我 3 个关键问题；
2. 生成 README.md；
3. 生成 PRD.md；
4. 生成 DESIGN.md；
5. 生成 PLAN.md；
6. 生成 AGENTS.md。
要求第一版只做最小可用功能。
等我确认 PLAN 后，再开始实现。验收标准：
- 有完整项目文档。
- 有一个能运行的最小版本。
- 有验证命令或手动检查步骤。
- README 能指导别人运行。
- 最后有一段复盘：做对了什么、卡在哪里、下次怎么改进。
进阶要求：
把这次项目沉淀成一个可复用模板。
I.11 练习复盘模板
每做完一个练习，都建议写 5 分钟复盘。
可以直接复制这个模板：
## 练习复盘
练习名称：
完成时间：
我让 Codex 做了什么：
最终产出是什么：
最顺利的地方：
最卡的地方：
我给 Codex 的哪句话最有效：
我下次会怎么改 Prompt：
是否需要沉淀成 Skill：复盘不是为了写总结给别人看。
它是为了让你逐渐形成自己的 Codex 工作方法。
I.12 自我评分表
做完练习后，可以按 1-5 分给自己打分。
| 维度 | 1 分 | 3 分 | 5 分 |
|---|---|---|---|
| 需求表达 | 只说大概想法 | 能说明目标和输出 | 能说明目标、背景、限制和验收标准 |
| 任务拆解 | 一次让 Codex 做完 | 能拆成几步 | 每一步都有验证方式 |
| 文件协作 | 不知道改了什么 | 能看懂主要文件 | 能控制修改范围和回滚方式 |
| 结果检查 | 看起来差不多就结束 | 能做基本检查 | 能发现边界问题和风险 |
| 复盘沉淀 | 做完就忘 | 记录问题 | 能改进 Prompt 或沉淀 Skill |
如果平均分达到 3 分，你已经可以稳定完成小任务。
如果平均分达到 4 分以上，就可以开始尝试更复杂的项目协作。
附录J 任务速查地图
这一附录适合在你“想做一件具体事，但不知道该翻哪一章”时使用。
正文是按学习顺序写的，适合从零到进阶慢慢读。
这一附录是按任务场景写的，适合临时查。
你可以先找到自己的任务，再看对应章节、提示词模板和验收标准。
J.1 我刚开始，不知道从哪里入门
| 你想做什么 | 先看哪里 | 可直接用什么 | 成功标志 |
|---|---|---|---|
| 了解 Codex 是什么 | 第 1 章 | 附录 H.3 | 能说出 Codex 和普通聊天 AI 的区别。 |
| 判断 Codex 能做什么 | 第 2 章 | 附录 J.2 | 能列出 3 个自己工作里可用的场景。 |
| 选择 App、CLI、IDE | 第 3 章 | 附录 H.2 | 能决定自己先用哪个入口。 |
| 安装并第一次登录 | 第 4-5 章 | 附录 G.1 | 能打开 Codex 并开始一个任务。 |
| 理解本地文件目录 | 第 6 章 | 附录 I.1 | 能让 Codex 解释当前文件夹。 |
推荐第一句：
我是第一次使用 Codex。
请先用新手能听懂的话解释当前界面和当前文件夹。
不要直接修改文件。J.2 我想先做一个看得见的结果
| 你想做什么 | 先看哪里 | 可直接用什么 | 成功标志 |
|---|---|---|---|
| 生成一个 HTML 页面 | 第 7 章 | 附录 D.5、I.2 | 本地能打开页面，手机上不乱。 |
| 修改已有页面 | 第 10 章 | 附录 D.6 | 能说清改了哪些文件。 |
| 检查页面效果 | 第 21 章 | 附录 F.2 | 页面显示、交互和截图都能确认。 |
| 做一个小工具雏形 | 第 36-37 章 | 附录 I.10 | 有 README、能运行、有验证步骤。 |
推荐第一句：
我想先做一个能看见结果的小页面。
请先帮我把需求缩小到 1 小时内能完成的版本，再生成文件。J.3 我想整理文档、笔记或教程
| 你想做什么 | 先看哪里 | 可直接用什么 | 成功标志 |
|---|---|---|---|
| 检查一个 Markdown 文件 | 第 10 章、第 26 章 | 附录 D.2 | 能得到结构、错漏、改进建议。 |
| 继续补充长文档 | 第 10 章、第 43 章 | 附录 D.3 | 文风一致，目录和标题不乱。 |
| 把笔记改成教程 | 第 30 章 | 附录 I.3 | 新手能按顺序读懂。 |
| 做知识库整理 | 第 30 章 | 附录 D.4 | 有标题、分类、标签、相关链接。 |
| 发布前总检查 | 附录 F | 附录 F.9 | 必须修复和建议优化分开。 |
推荐第一句：
请先阅读这份文档的目录、开头和结尾。
然后判断最需要补的是结构、案例、术语解释还是发布检查。
先给建议，不要直接改。J.4 我想分析数据或做报告
| 你想做什么 | 先看哪里 | 可直接用什么 | 成功标志 |
|---|---|---|---|
| 分析 CSV | 第 8 章 | 附录 D.7、I.4 | 字段解释清楚，结论有数据来源。 |
| 生成图表报告 | 第 31 章 | 附录 D.7 | 图表有标题、坐标含义和解读。 |
| 做行业研究 | 第 35 章 | 附录 G.4 | 先有研究问题，再有证据来源。 |
| 做汇报材料 | 第 25 章、第 31 章 | 附录 F.7 | 内容能进入文档、PPT 或 HTML 报告。 |
推荐第一句：
请先理解这个数据文件的字段和数据质量。
在分析前，先告诉我哪些问题能回答，哪些问题当前数据回答不了。J.5 我想做项目文档和开发计划
| 你想做什么 | 先看哪里 | 可直接用什么 | 成功标志 |
|---|---|---|---|
| 写 README | 第 15 章 | 附录 D.10 | 新人能照着安装、启动、使用。 |
| 写 PRD | 第 16 章 | 附录 D.11 | 有目标用户、范围、不做什么、验收标准。 |
| 写 DESIGN | 第 15-16 章 | 附录 D.12 | 模块、数据、流程和风险说清楚。 |
| 写 PLAN | 第 14 章 | 附录 D.13 | 每一步都有修改范围和验证方式。 |
| 写 AGENTS.md | 第 13 章 | 附录 D.14 | Codex 知道项目规则和不要做什么。 |
推荐第一句：
我想把这个想法变成一个可执行的小项目。
请先不要写代码，先帮我生成 README、PRD、DESIGN、PLAN 和 AGENTS.md。
第一版只做最小可用功能。J.6 我想让 Codex 改代码或排查报错
| 你想做什么 | 先看哪里 | 可直接用什么 | 成功标志 |
|---|---|---|---|
| 让 Codex 修改代码 | 第 10 章 | 附录 D.9 | 功能不变或按目标改变，测试能过。 |
| 排查报错 | 第 11 章 | 附录 D.8 | 能解释原因、复现、修复、重新验证。 |
| 重构一段代码 | 第 10 章、第 46 章 | 附录 D.9 | 修改范围清楚，不引入无关依赖。 |
| 检查上线风险 | 第 47 章、附录 F | 附录 H.14 | 安全、隐私、测试和 README 都检查过。 |
推荐第一句：
请先阅读报错和相关文件，定位根因。
不要先改代码。
先告诉我问题发生在哪一层，以及你准备如何验证修复。J.7 我想做办公自动化
| 你想做什么 | 先看哪里 | 可直接用什么 | 成功标志 |
|---|---|---|---|
| 整理会议纪要 | 第 29 章 | 附录 D.16、I.7 | 结论、待办、负责人、待确认项清楚。 |
| 生成周报 | 第 34 章 | 附录 D.17 | 结果和风险清楚，不像流水账。 |
| 客户跟进 | 第 33 章 | 附录 D.18 | 需求、异议、下一步动作分清。 |
| 飞书协同 | 第 22 章、第 34 章 | 附录 G.2 | 先确认权限和身份，再操作。 |
| Office 文件 | 第 25 章 | 附录 F.7 | 可编辑、可发送、格式不乱。 |
推荐第一句：
请先把这份材料整理成可执行的办公输出。
如果涉及发送消息、创建文档或修改正式数据，请先给草稿和计划，不要直接执行。J.8 我想做内容创作
| 你想做什么 | 先看哪里 | 可直接用什么 | 成功标志 |
|---|---|---|---|
| 改写长文 | 第 26 章、第 30 章 | 附录 D.4 | 保留事实，结构更清楚。 |
| 做自媒体选题 | 第 32 章 | 附录 D.4、D.17 | 有标题、角度、受众和发布形式。 |
| 做配图建议 | 第 23 章 | 附录 E | 图服务内容，不只是装饰。 |
| 做口播稿 | 第 24 章 | 附录 D.4 | 适合朗读，句子不绕。 |
| 多 Agent 写作 | 第 43 章 | 附录 D.19 | 分工清楚，最后有人统一口径。 |
推荐第一句：
请把这份内容改成适合【平台/受众】的版本。
保留事实，不要编造案例。
先给结构方案，再输出正文。J.9 我想做 Skill、MCP 或更进阶扩展
| 你想做什么 | 先看哪里 | 可直接用什么 | 成功标志 |
|---|---|---|---|
| 理解 MCP | 第 17 章 | 附录 G.2 | 知道它是连接外部工具的方式。 |
| 理解 Skill | 第 18-19 章 | 附录 H.8 | 知道它和普通 Prompt 的区别。 |
| 设计自己的 Skill | 第 20 章 | 附录 D.15、I.8 | 有适用场景、步骤、失败处理。 |
| 浏览器自动化 | 第 21 章 | 附录 F.2 | 能打开、点击、检查、截图。 |
| 工具组合工作流 | 第 27-28 章 | 附录 J.10 | 输入、输出、边界和验证都明确。 |
推荐第一句：
我有一个重复任务，想判断它适不适合做成 Skill。
请先帮我分析：输入是什么、输出是什么、步骤是否稳定、失败时怎么处理。J.10 我想做完整项目
| 你想做什么 | 先看哪里 | 可直接用什么 | 成功标志 |
|---|---|---|---|
| 从零搭建项目 | 第 36 章 | 附录 I.10 | 文档齐、能运行、能验证。 |
| 做文件清洗工具 | 第 37 章 | 附录 D.13 | 输入输出明确，有错误处理。 |
| 做智能体对话平台 | 第 38 章 | 附录 G.3 | 先查官方文档，再定架构。 |
| 做数字人口播工具 | 第 39 章 | 附录 D.4、D.16 | 稿件、声音、画面、导出流程清楚。 |
| 做小程序或 iOS App | 第 40-41 章 | 附录 G.4 | 先确认平台规则，再开发。 |
| 做硬件功能 | 第 42 章 | 附录 F.6 | 明确硬件、固件、测试和安全边界。 |
推荐第一句：
我想做一个完整项目，但先只做第一版。
请帮我把目标缩小到最小可用版本，并生成 README、PRD、DESIGN、PLAN、AGENTS.md。
先不要写代码。J.11 我想提高协作稳定性
| 你遇到的问题 | 先看哪里 | 推荐动作 | 成功标志 |
|---|---|---|---|
| Codex 老是跑偏 | 第 9 章、第 14 章 | 写清目标、限制和验收标准。 | 输出和目标一致。 |
| 长任务越做越乱 | 第 14 章、第 43 章 | 写 PLAN，分步执行。 | 每一步都能独立检查。 |
| 多人或多 Agent 冲突 | 第 44 章 | 用 Worktree 或明确文件范围。 | 不互相覆盖修改。 |
| 结果看似对但不敢用 | 第 47 章、附录 F | 做发布前检查。 | 风险和遗留项清楚。 |
| 工具信息可能过时 | 附录 G | 查官方资料。 | 有官方链接和复查日期。 |
推荐第一句：
这个任务有点复杂。
请先帮我拆成可以验证的小步骤，并标出哪些步骤可以并行，哪些必须串行。J.12 三种最常用的万能路径
如果你还是不知道怎么选，就用下面三条路径。
#### 路径一：做内容
素材 -> 结构整理 -> 改写润色 -> 检查事实 -> 发布检查对应章节：
- 第 9-10 章。
- 第 26、30、32 章。
- 附录 D、F、H。
#### 路径二：做数据
字段理解 -> 数据质量 -> 业务问题 -> 图表报告 -> 结论复查对应章节：
- 第 8、31、35 章。
- 附录 D.7、I.4。
#### 路径三：做项目
README -> PRD -> DESIGN -> PLAN -> AGENTS.md -> 实现 -> 验证 -> 复盘对应章节：
- 第 13-16 章。
- 第 36-42 章。
- 附录 D.10-D.14、I.10。
这三条路径背后的共同点是一样的：
先定目标，再拆步骤，然后执行，最后验证。
这是使用 Codex 最稳的基本功。
附录K 故障排查索引
这一附录适合在你已经遇到问题时使用。
不要一出错就让 Codex “随便修一下”。更稳的方式是：先判断问题属于哪一层，再收集证据，最后只修最可能的原因。
故障排查的通用顺序：
- 复述你本来想做什么。
- 粘贴完整报错或异常现象。
- 说明刚才执行了什么命令或操作。
- 让 Codex 先判断问题层级。
- 先做最小验证，再修改。
- 修改后重新运行原来的验证步骤。
通用 Prompt：
我遇到了一个问题。
我的目标是：
【写目标】
我刚才执行的操作是：
【写命令或操作】
现在的现象或报错是：
【粘贴完整内容】
请先不要直接修改文件。
请先判断问题属于：环境、权限、依赖、路径、配置、代码、数据、网络、工具调用、需求误解中的哪一类。
然后给出第一步最小验证方式。K.1 安装或启动问题
| 现象 | 可能原因 | 先做什么 | 参考位置 |
|---|---|---|---|
找不到 codex 命令 | CLI 没装好，或 PATH 没生效 | 重新打开终端，检查安装命令和 PATH | 第 4 章、附录 G.1 |
| 安装命令和教程不一致 | 官方安装方式更新 | 先查官方 CLI 文档 | 附录 G.1 |
| App 打不开 | 系统权限、版本不兼容、安装包异常 | 检查系统版本和安全设置 | 第 4-5 章 |
| 登录失败 | 账号、网络、套餐、浏览器授权问题 | 查 Help Center 和当前客户端提示 | 附录 G.1 |
| 终端提示权限不足 | 系统权限或文件夹权限 | 换练习目录，避免系统保护目录 | 第 6 章、第 11 章 |
建议 Prompt：
Codex 安装或启动失败。
请先判断是安装路径、PATH、系统权限、账号登录还是网络问题。
请告诉我需要运行哪些只读检查命令，不要直接改系统配置。K.2 文件和路径问题
| 现象 | 可能原因 | 先做什么 | 参考位置 |
|---|---|---|---|
| Codex 找不到文件 | 当前工作目录不对 | 让 Codex 先列当前目录 | 第 6 章、附录 I.1 |
| 改错了文件 | 文件名相似，需求没说清 | 先让 Codex 汇报刚才改了哪些文件 | 第 10 章 |
| 图片不显示 | 图片路径错，文件没同步 | 检查 Markdown 引用和本地文件 | 附录 E、附录 F.2 |
| 文件乱码 | 编码不一致 | 先判断文件编码，不要直接覆盖保存 | 第 26 章 |
| 删除了不该删的内容 | 没有版本管理或修改范围过大 | 查看 diff，用 git 或备份找回 | 第 10 章、附录 H.10 |
建议 Prompt：
请先检查当前文件夹结构和相关文件路径。
不要修改文件。
请告诉我目标文件是否存在、图片路径是否存在、当前工作目录是否正确。K.3 命令执行失败
| 现象 | 可能原因 | 先做什么 | 参考位置 |
|---|---|---|---|
npm 或 node 不存在 | Node.js 未安装或 PATH 未生效 | 检查 node -v 和 npm -v | 第 4 章、第 11 章 |
pip 或 python 不存在 | Python 环境未准备好 | 检查 Python 版本 | 第 11 章 |
command not found | 命令没安装或拼写错 | 让 Codex 解释命令来源 | 第 11 章 |
permission denied | 权限不足或脚本不可执行 | 先看路径和权限，不要盲目加权限 | 第 11 章 |
| 命令卡住不动 | 服务在前台运行，或等待输入 | 判断是正常运行还是阻塞 | 第 21 章、附录 F.3 |
建议 Prompt：
这条命令执行失败：
【粘贴命令】
报错是：
【粘贴完整输出】
请先解释报错含义，并判断是命令不存在、依赖缺失、权限问题、路径问题还是命令本身用法错误。K.4 依赖和环境问题
| 现象 | 可能原因 | 先做什么 | 参考位置 |
|---|---|---|---|
| 页面项目启动失败 | 依赖没装或版本冲突 | 看 package.json，再安装依赖 | 第 36-38 章 |
| Python 脚本缺包 | 依赖未安装 | 从报错里找缺失模块名 | 第 11 章 |
| 旧项目跑不起来 | Node/Python 版本不匹配 | 先读 README 和锁文件 | 第 37 章、附录 F.3 |
| 安装依赖很慢 | 网络或镜像源问题 | 判断是网络问题还是包不存在 | 第 11 章 |
| 安装后仍报错 | 装错目录或虚拟环境不一致 | 检查当前目录和解释器环境 | 第 11 章 |
建议 Prompt：
请检查这个项目的依赖环境。
先阅读 README、package.json、requirements.txt 或类似文件。
告诉我应该使用什么安装命令，以及如何确认依赖安装到了正确环境。K.5 网页和前端问题
| 现象 | 可能原因 | 先做什么 | 参考位置 |
|---|---|---|---|
| HTML 打不开 | 文件路径不对或浏览器没打开目标文件 | 先确认文件存在 | 第 7 章 |
| 页面空白 | JS 报错、入口文件错、构建失败 | 打开控制台或运行构建命令 | 第 21 章 |
| 样式没生效 | CSS 路径错或选择器不对 | 检查样式引用和元素类名 | 第 7 章、第 10 章 |
| 移动端错位 | 响应式样式不足 | 用窄屏检查并定位溢出元素 | 第 7 章 |
| 按钮没反应 | 事件未绑定或脚本报错 | 检查控制台错误和事件处理 | 第 21 章 |
建议 Prompt：
页面显示有问题。
请先打开或检查页面状态，不要直接重写。
请按 HTML、CSS、JS、资源路径、浏览器控制台五层排查，并告诉我第一处异常在哪里。K.6 数据分析问题
| 现象 | 可能原因 | 先做什么 | 参考位置 |
|---|---|---|---|
| CSV 读不出来 | 编码、分隔符、文件路径问题 | 先检查文件前几行和编码 | 第 8 章 |
| 字段解释不准 | 没有业务背景 | 补充数据来源和字段含义 | 第 31 章 |
| 结论很像猜的 | 没有绑定计算依据 | 要求每个结论写字段和计算过程 | 附录 D.7 |
| 图表误导 | 轴含义、单位或聚合方式不清 | 检查图表标题、坐标和口径 | 第 31 章 |
| 问题回答不了 | 数据缺字段 | 让 Codex 标注缺少哪些字段 | 第 8 章 |
建议 Prompt：
请先不要给结论。
请先检查这份数据的字段、样例行、缺失值、异常值和可回答的问题。
每个结论都必须说明依据字段和计算方式。K.7 内容生成问题
| 现象 | 可能原因 | 先做什么 | 参考位置 |
|---|---|---|---|
| 内容太空 | 目标读者和场景不清 | 补充受众、用途、输出格式 | 第 9 章 |
| 风格不一致 | 没给参考样例 | 给 1-2 段目标风格样例 | 第 10 章 |
| 乱编事实 | 没限制“不要编造” | 要求标注不确定信息 | 第 26 章 |
| 长文越写越散 | 没有目录和计划 | 先写大纲，再分章补 | 第 43 章 |
| 改写丢重点 | 没要求保留事实 | 让 Codex 对照原文检查 | 第 30 章 |
建议 Prompt：
这版内容不满意。
请不要整篇重写。
请先按目标读者、结构、事实准确性、风格一致性、重复内容五项检查，再只修改有问题的部分。K.8 Codex 越改越乱
| 现象 | 可能原因 | 先做什么 | 参考位置 |
|---|---|---|---|
| 一轮改很多文件 | 任务范围太大 | 停止扩展，让 Codex 汇报 diff | 第 10 章 |
| 改了 A 又坏了 B | 没有回归验证 | 补验证清单 | 第 47 章、附录 F |
| 连续修三次没修好 | 根因没定位 | 回到报错和复现步骤 | 第 11 章 |
| 输出越来越偏 | 上下文污染或目标漂移 | 重新总结目标和边界 | 第 9 章 |
| 不知道当前做到哪 | 没有 PLAN | 生成或更新 PLAN | 第 14 章 |
建议 Prompt：
现在修改开始变乱了。
请先停止新增功能。
请总结目前已经改了哪些文件、原目标是什么、当前未解决的问题是什么。
然后给我一个最小回正方案。K.9 MCP、Skill 和工具调用问题
| 现象 | 可能原因 | 先做什么 | 参考位置 |
|---|---|---|---|
| MCP 连接不上 | 配置、网络、认证或服务未启动 | 先查配置和服务状态 | 第 17 章、附录 G.2 |
| 工具没权限 | scope 或身份不对 | 判断 user/bot 或账号授权 | 第 22 章 |
| Skill 没触发 | 描述不清或任务不匹配 | 检查 Skill 描述和触发场景 | 第 18-20 章 |
| Skill 做错事 | 步骤写得太模糊 | 补输入、输出、失败处理 | 附录 D.15 |
| 工具返回空结果 | 权限、查询条件或数据本来为空 | 先排查身份和筛选条件 | 第 34 章 |
建议 Prompt：
这个工具或 Skill 没有按预期工作。
请先判断是配置问题、权限问题、触发描述问题、输入不完整，还是工具本身不可用。
请不要直接扩大权限，先说明最小需要的权限和验证方式。K.10 飞书、办公和外部系统问题
| 现象 | 可能原因 | 先做什么 | 参考位置 |
|---|---|---|---|
| 查不到日程或文档 | 身份、权限或搜索条件问题 | 先确认 user/bot 身份 | 第 22 章、第 34 章 |
| 发消息失败 | 机器人权限、群权限或参数不对 | 先生成消息草稿，不直接发送 | 第 22 章 |
| 创建文档失败 | 权限或目标空间不对 | 检查授权和目标位置 | 第 34 章 |
| 任务同步错人 | 成员标识不清 | 先确认人员 ID 和姓名 | 第 33-34 章 |
| 自动化误操作 | 没有人审草稿 | 正式操作前输出计划 | 第 28 章 |
建议 Prompt：
这个办公自动化操作失败了。
请先确认当前身份、目标对象、所需权限和操作风险。
如果涉及发送、创建、删除或修改正式数据，请先给草稿，不要直接执行。K.11 安全、隐私和账号问题
| 现象 | 风险 | 先做什么 | 参考位置 |
|---|---|---|---|
| 文档里出现 API Key | 密钥泄露 | 立即移除，必要时轮换密钥 | 附录 F.6、H.15 |
| 截图里有账号信息 | 隐私泄露 | 打码后再发布 | 附录 E、F.6 |
| Codex 要求更大权限 | 权限过度 | 只给当前任务最小权限 | 第 22 章、第 47 章 |
| 涉及客户数据 | 合规风险 | 脱敏或改用模拟数据 | 附录 H.15 |
| 生产数据要被修改 | 高风险操作 | 先备份、先计划、先人工确认 | 附录 F.6 |
建议 Prompt：
请从安全和隐私角度检查这次操作。
重点看是否涉及 API Key、token、账号信息、客户数据、生产数据和不可逆修改。
请只列风险和处理建议，不要复述敏感内容。K.12 官方信息过时问题
| 现象 | 可能原因 | 先做什么 | 参考位置 |
|---|---|---|---|
| 命令和教程不一致 | 官方更新 | 查当前官方文档 | 附录 G |
| 模型名不可用 | 模型更新或账号不可用 | 查当前模型说明 | 附录 G.3 |
| 界面按钮位置不同 | 产品 UI 更新 | 以当前客户端为准 | 第 5 章 |
| 套餐权限不一致 | 账号规则变化 | 查 Help Center | 附录 G.1 |
| API 参数报错 | 接口版本变化 | 查 API Reference | 附录 G.3 |
建议 Prompt：
教程内容可能过时。
请只查官方资料，判断这段内容是否仍然准确。
如果不准确，请给我一版更稳妥的改写，并附官方链接。K.13 最小复现模板
遇到复杂问题时，最有用的不是贴一堆情绪，而是做最小复现。
可以直接复制这个模板：
## 问题复现
目标：
环境：
我执行的命令或操作：
完整报错或异常现象：
相关文件：
我已经尝试过：
期望结果：
实际结果：
请先判断问题层级，不要直接修改文件。最小复现的价值是：把“它坏了”变成“在这个条件下，这一步失败了”。
Codex 越能看到清楚的复现路径，越容易修对。
K.14 什么时候应该停下来问真人
遇到下面这些情况，不要硬让 Codex 继续猜：
- 同一个问题修了三轮还没定位根因。
- 涉及生产数据、客户隐私、支付、权限、安全。
- 你看不懂它准备执行的命令。
- 它建议删除、覆盖、迁移大量文件。
- 官方文档和当前项目行为明显冲突。
- 硬件、电路、设备安全相关问题。
- 法律、医疗、金融等高风险判断。
这不是 Codex 不行。
这是你在正确地管理风险。
真正成熟的协作方式，不是永远让 AI 往前冲，而是知道什么时候该停、该查、该验证、该请人确认。
附录L 配套资料包清单
这一附录是给教程发布者和带学者准备的。
如果这篇教程只是一篇文章，读者可以照着读。
但如果你希望它变成一套课程、训练营、社群共学材料，最好再配一个资料包。资料包的作用是：让读者不用从空白开始，每个练习都有模板、示例数据、检查清单和复盘表。
当前工作区已经按本附录生成了一版初始资料包：
codex-tutorial-kit/建议资料包目录叫：
codex-tutorial-kit/L.1 推荐目录结构
codex-tutorial-kit/
├── 00-readme/
│ └── 资料包使用说明.md
├── 01-project-doc-templates/
│ ├── README.template.md
│ ├── PRD.template.md
│ ├── DESIGN.template.md
│ ├── PLAN.template.md
│ └── AGENTS.template.md
├── 02-prompt-templates/
│ ├── 文件检查.prompt.md
│ ├── 文档续写.prompt.md
│ ├── 数据分析.prompt.md
│ ├── 报错排查.prompt.md
│ ├── 发布前检查.prompt.md
│ └── Skill设计.prompt.md
├── 03-practice-data/
│ ├── sample-sales.csv
│ ├── sample-feedback.csv
│ └── sample-meeting-notes.md
├── 04-web-starter/
│ ├── index.html
│ └── README.md
├── 05-checklists/
│ ├── 发布前检查清单.md
│ ├── 隐私安全检查清单.md
│ ├── 图片替换检查清单.md
│ └── 故障排查清单.md
├── 06-review-forms/
│ ├── 练习复盘模板.md
│ ├── 自我评分表.md
│ └── 项目结项复盘.md
└── assets/
└── images/这个结构不用一次全部做完。
如果时间有限，先准备：
- 四文档模板。
- Prompt 模板。
- 示例 CSV。
- 练习复盘模板。
这四类资料最能帮助新手起步。
L.2 资料包使用说明模板
文件名建议：
00-readme/资料包使用说明.md内容可以这样写：
# Codex 教程配套资料包
这个资料包配合《Codex 入门与实战指南》使用。
建议使用方式：
1. 先阅读教程第 1-6 章，完成安装和基础认识。
2. 从 `01-project-doc-templates/` 复制项目文档模板。
3. 从 `02-prompt-templates/` 选择对应任务的 Prompt。
4. 用 `03-practice-data/` 里的示例数据做练习。
5. 每次练习后，用 `06-review-forms/` 里的复盘模板记录结果。
注意：
- 不要把真实 API Key、账号、客户数据写进练习文件。
- 如果要发布截图，请先打码。
- 如果教程命令和官方文档不一致，以官方文档为准。这份说明不需要写太长。
它只要告诉读者：先从哪里开始，遇到不同任务去哪个文件夹找。
L.3 四文档模板包
四文档模板是整个资料包里最值得准备的部分。
#### README.template.md
# 项目名称
## 项目简介
一句话说明这个项目是什么。
## 目标用户
这个项目给谁用。
## 核心功能
- 功能一：
- 功能二：
- 功能三：
## 如何运行
填写安装和启动命令。
## 使用方式
1. 第一步：
2. 第二步：
3. 第三步：
## 目录结构
填写主要目录。
## 常见问题
### 问题一
回答。
## 后续计划
- 计划一：
- 计划二：#### PRD.template.md
# PRD
## 背景
为什么要做这个项目。
## 目标用户
谁会使用。
## 要解决的问题
这个项目解决什么具体问题。
## 本版本要做什么
- 功能一：
- 功能二：
- 功能三：
## 本版本不做什么
- 暂不做：
- 暂不做：
## 用户流程
1. 用户进入：
2. 用户操作：
3. 系统反馈：
## 验收标准
- 标准一：
- 标准二：
- 标准三：
## 风险和待确认
- 待确认一：
- 待确认二：#### DESIGN.template.md
# DESIGN
## 技术选型
说明使用什么技术，以及为什么。
## 模块划分
| 模块 | 职责 | 输入 | 输出 |
| --- | --- | --- | --- |
| 模块一 | | | |
| 模块二 | | | |
## 数据结构
说明核心数据字段。
## 核心流程
1. 步骤一：
2. 步骤二：
3. 步骤三：
## 错误处理
- 错误一：
- 错误二：
## 测试策略
- 手动检查：
- 自动测试：
## 暂不实现
- 内容一：
- 内容二：#### PLAN.template.md
# PLAN
## 执行原则
- 每次只做一个小步骤。
- 每一步完成后都要验证。
- 不做计划外功能。
## 步骤列表
### Step 1：准备项目结构
修改范围：
验证方式：
### Step 2：实现核心功能
修改范围：
验证方式：
### Step 3：补充说明和检查
修改范围：
验证方式：
## 完成标准
- 标准一：
- 标准二：#### AGENTS.template.md
# AGENTS.md
## 项目背景
这个项目是什么。
## 协作原则
- 修改前先阅读相关文件。
- 不要做无关重构。
- 不要引入不必要依赖。
- 修改后说明改了哪些文件。
## 常用命令
填写实际存在的命令。
## 文件约定
- `src/`：
- `data/`：
- `docs/`：
## 验证方式
- 手动验证：
- 命令验证：
## 不要做的事
- 不要删除用户数据。
- 不要提交密钥。
- 不要跳过验证。L.4 Prompt 模板包
Prompt 模板可以从附录 D 拆出来，单独放成文件。
建议每个模板文件都包含：
- 适用场景。
- 不适用场景。
- 可复制 Prompt。
- 使用前需要准备的材料。
- 输出验收标准。
示例：
# 报错排查 Prompt
## 适用场景
- 命令失败。
- 页面打不开。
- 依赖安装报错。
- 测试失败。
## 使用前准备
- 原始命令。
- 完整报错。
- 当前目标。
- 相关文件路径。
## Prompt
我遇到了一个报错。
我执行的命令是： 【粘贴命令】
报错内容是： 【粘贴完整报错】
我的目标是： 【说明本来想完成什么】
请先解释报错含义，再判断最可能的原因。 不要直接猜测修改。
## 验收标准
- 能说明问题层级。
- 能给出最小验证步骤。
- 修复后能重新运行原命令。L.5 示例数据包
示例数据要足够真实，但不能包含真实隐私。
建议准备三类：
#### sample-sales.csv
用于练习销售或运营数据分析。
字段建议：
date,region,channel,product,orders,revenue,cost,refunds练习问题：
- 哪个渠道收入最高？
- 哪个地区退款最多？
- 收入和成本趋势是否稳定？
- 当前数据能不能判断利润？
#### sample-feedback.csv
用于练习用户反馈归类。
字段建议：
date,user_type,feedback,source,severity,status练习问题：
- 反馈主要集中在哪些问题类型？
- 哪些反馈需要优先处理？
- 哪些反馈适合沉淀成 FAQ？
#### sample-meeting-notes.md
用于练习会议纪要整理。
内容建议包含：
- 会议背景。
- 讨论分歧。
- 决策结论。
- 待办事项。
- 不明确负责人或截止时间的任务。
这样读者能练到“待确认”标注，而不是只做简单摘要。
L.6 Web Starter 包
Web Starter 用来配合第 7 章和第 37 章。
建议包含：
04-web-starter/
├── index.html
└── README.mdindex.html 不需要复杂，只要包含：
- 标题区。
- 内容区。
- 按钮。
- 列表。
- 简单响应式样式。
README.md 说明：
# Web Starter
这是一个最小 HTML 练习项目。
使用方式：
1. 直接用浏览器打开 `index.html`。
2. 让 Codex 修改页面文案、颜色、布局。
3. 修改后检查手机宽度下是否正常。
练习目标：
- 学会让 Codex 修改 HTML。
- 学会检查页面显示。
- 学会提出具体修改意见。这个 Starter 的重点不是好看，而是让新手敢改。
L.7 检查清单包
检查清单适合放在 05-checklists/。
建议至少准备四份。
#### 发布前检查清单
来自附录 F。
用途：发布文章、项目、页面前最后看一遍。
#### 隐私安全检查清单
来自附录 F.6 和附录 K.11。
用途：检查截图、密钥、账号、客户数据。
#### 图片替换检查清单
来自附录 E。
用途：把 SVG 示意图替换成真实截图时使用。
#### 故障排查清单
来自附录 K。
用途：遇到安装、路径、依赖、权限、页面、数据问题时使用。
L.8 复盘表单包
复盘表单适合放在 06-review-forms/。
建议包含：
- 练习复盘模板。
- 自我评分表。
- 项目结项复盘。
项目结项复盘可以这样写：
# 项目结项复盘
## 项目名称
## 原始目标
## 最终产出
## 完成了哪些功能
## 没完成哪些功能
## Codex 帮上忙的地方
## Codex 出错或跑偏的地方
## 我最有效的 Prompt
## 下次要提前写清楚的规则
## 是否需要沉淀成模板或 Skill复盘表单的价值在于让学习成果沉淀下来。
只要认真复盘 3 次，你自己的 Prompt 水平会明显提升。
L.9 资料包生成 Prompt
如果你想让 Codex 按本附录生成真实资料包，可以复制下面这段：
请根据《Codex 入门与实战指南》的资料包说明，生成一个配套资料包目录。
要求：
1. 创建 `../codex-tutorial-kit/` 目录；
2. 按附录 L 的结构创建子目录；
3. 生成四文档模板、Prompt 模板、检查清单和复盘表单；
4. 示例数据使用虚构内容，不要包含真实个人信息；
5. 生成后列出文件清单；
6. 检查是否有空文件、空链接和敏感信息。
先给我计划，确认后再创建文件。如果你已经确认要直接生成，可以把最后一句改成：
请直接创建文件，并在完成后运行文件清单检查。L.10 资料包发布前检查
资料包发布前，至少检查：
- 文件能不能正常打开。
- 模板里有没有未解释的占位符。
- CSV 是否能被正常读取。
- 示例数据是否全部虚构。
- 图片路径是否存在。
- Prompt 是否能直接复制使用。
- 是否包含真实账号、密钥、客户信息。
- 文件名在 Windows 和 macOS 上是否都容易识别。
可以让 Codex 这样检查：
请检查这个配套资料包。
重点看：
1. 目录结构是否完整；
2. 是否有空文件；
3. 模板是否可直接使用；
4. 示例数据是否包含敏感信息；
5. Markdown 链接和图片路径是否有效；
6. 是否有不适合发布的本地路径或账号信息。
请输出必须修复、建议优化和可以保留三类问题。一个好的资料包，会让读者少掉很多“我该新建什么文件”的犹豫。
这也是教程从“文章”升级成“课程资产”的关键一步。
真实资料包文件清单
当前工作区已经生成初版 ../codex-tutorial-kit/，包含以下文件：
../codex-tutorial-kit/00-readme/资料包使用说明.md../codex-tutorial-kit/01-project-doc-templates/AGENTS.template.md../codex-tutorial-kit/01-project-doc-templates/DESIGN.template.md../codex-tutorial-kit/01-project-doc-templates/PLAN.template.md../codex-tutorial-kit/01-project-doc-templates/PRD.template.md../codex-tutorial-kit/01-project-doc-templates/README.template.md../codex-tutorial-kit/02-prompt-templates/Skill设计.prompt.md../codex-tutorial-kit/02-prompt-templates/发布前检查.prompt.md../codex-tutorial-kit/02-prompt-templates/报错排查.prompt.md../codex-tutorial-kit/02-prompt-templates/数据分析.prompt.md../codex-tutorial-kit/02-prompt-templates/文件检查.prompt.md../codex-tutorial-kit/02-prompt-templates/文档续写.prompt.md../codex-tutorial-kit/03-practice-data/sample-feedback.csv../codex-tutorial-kit/03-practice-data/sample-meeting-notes.md../codex-tutorial-kit/03-practice-data/sample-sales.csv../codex-tutorial-kit/04-web-starter/README.md../codex-tutorial-kit/04-web-starter/index.html../codex-tutorial-kit/05-checklists/发布前检查清单.md../codex-tutorial-kit/05-checklists/图片替换检查清单.md../codex-tutorial-kit/05-checklists/故障排查清单.md../codex-tutorial-kit/05-checklists/隐私安全检查清单.md../codex-tutorial-kit/06-review-forms/练习复盘模板.md../codex-tutorial-kit/06-review-forms/自我评分表.md../codex-tutorial-kit/06-review-forms/项目结项复盘.md../codex-tutorial-kit/assets/images/README.md
资料包使用顺序
- 先打开
../codex-tutorial-kit/00-readme/资料包使用说明.md。 - 做项目时复制
01-project-doc-templates/中的模板。 - 不知道怎么开口时，从
02-prompt-templates/复制对应 Prompt。 - 做数据练习时使用
03-practice-data/。 - 做网页练习时打开
04-web-starter/index.html。 - 发布前用
05-checklists/。 - 每次练习后填写
06-review-forms/。