Codex 教程
用 Codex 生成 README
用 Codex 生成 README 的完整指南，覆盖项目扫描、信息架构、可复制 Goal Prompt、README 模板、环境变量、密钥安全、验证方法和常见误区。
用 Codex 生成 README，不是套一个“项目介绍模板”，而是把真实仓库整理成新 人能理解、能安装、能运行、能排错、能继续维护的入口文档。好的 README 应 该来自项目文件、脚本、环境变量样例、测试命令和部署事实；缺信息时要标注 待确认，而不是替项目编故事。
| 项目 | 内容 |
|---|---|
| 阅读时间 | 约 7 分钟 |
| 更新时间 | 2026-07-03 |
| 适合人群 | 开源项目作者、内部工具维护者、独立开发者、学生、产品经理和需要整理项目文档的人 |
| 你会得到 | README 质量模型、生成流程图、项目扫描清单、可复制 Goal Prompt、README 模板、验证清单、密钥安全规则和 FAQ |
README 解决什么问题
Section titled “README 解决什么问题”README 是项目的入口，不是全部文档。它要让第一次打开仓库的人快速回答几
个问题：这是什么、为什么有用、怎么跑起来、遇到问题去哪看、由谁维护。更
深入的架构设计、接口参考、部署细节和贡献规范，可以放到 docs/、Wiki 或
独立文档站，再从 README 链过去。
| 读者 | 想知道什么 | README 应给出的信息 |
|---|---|---|
| 新开发者 | 怎么装、怎么跑、怎么测试 | 环境要求、安装命令、运行命令、测试命令 |
| 使用者 | 这个项目能做什么 | 一句话说明、核心功能、最小使用示例 |
| 维护者 | 改动前要注意什么 | 目录结构、脚本说明、发布流程、风险边界 |
| AI 代理 | 先读哪些文件、遵守哪些规则 | AGENTS.md、脚本、环境变量、验证命令和禁区 |
| 审阅者 | 这份文档是否可信 | 命令来源、事实来源、待确认事项和更新日期 |
Codex 生成 README 流程图
Section titled “Codex 生成 README 流程图”什么时候适合交给 Codex
Section titled “什么时候适合交给 Codex”| 场景 | 适合程度 | 关键条件 |
|---|---|---|
| 新项目第一次补 README | 适合 | 仓库里已有脚本、入口文件或最小运行方式 |
| 老项目 README 过期 | 很适合 | Codex 能对照 package.json、CI 和实际目录修正 |
| 内部工具交接 | 适合 | 要写清权限、环境变量、运行命令和排错入口 |
| SDK 或 API 示例项目 | 适合 | 要包含最小请求、变量名、错误排查和版本说明 |
| 多包仓库 | 可做但要拆分 | 先写根 README，再写子包 README |
| 还没确定产品定位 | 先别急 | 先让 Codex 提问题和信息架构，不要直接成稿 |
推荐目录结构
Section titled “推荐目录结构”project/ README.md AGENTS.md .env.example package.json src/ tests/ docs/README.md 面向人和 AI 代理；AGENTS.md 面向 Codex 等编码代理；docs/ 放
更长的专题说明；.env.example 只放变量名、占位值和用途说明。OpenAI Codex
手册建议把目标、上下文、约束和完成条件写清楚；长期有效的仓库规则适合沉
淀到 AGENTS.md，例如构建命令、测试命令、代码风格、禁区文件和安全边界。
让 Codex 先读什么
Section titled “让 Codex 先读什么”| 文件或信息 | 为什么要读 | README 中可能体现为 |
|---|---|---|
package.json、pyproject.toml、go.mod |
确认语言、脚本和运行方式 | 安装、运行、测试、构建命令 |
| 锁文件 | 判断包管理器和依赖可复现方式 | npm ci、pnpm install --frozen-lockfile 等命令 |
| 入口文件 | 确认服务、CLI 或页面入口 | 使用示例、端口、启动方式 |
.env.example |
确认变量名和外部服务 | 环境变量表，不写真实值 |
| 现有 README 或 docs | 继承已有事实，删除过期内容 | 链接、迁移说明、待确认项 |
| CI 配置 | 找到项目真正跑的检查 | 测试、lint、构建和发布流程 |
AGENTS.md |
读取仓库规则 | 维护约定和 AI 协作说明 |
README 信息架构
Section titled “README 信息架构”| 模块 | 目的 | 写作要求 |
|---|---|---|
| 项目一句话说明 | 让读者立刻知道项目是什么 | 不写口号，写对象、动作、结果 |
| 适用场景 | 帮读者判断是否继续看 | 写真实用途，不扩大能力 |
| 快速开始 | 让新环境跑起来 | 命令可复制，前置条件明确 |
| 环境变量 | 避免配置失败和泄露 | 只写变量名、用途和占位值 |
| 常用脚本 | 降低维护成本 | 来源来自项目脚本或 CI |
| 目录结构 | 帮新同事定位文件 | 只列关键目录，不堆树形图 |
| 测试与构建 | 建立可信度 | 写清验证命令和期望结果 |
| 部署或发布 | 给交付路径 | 不确定的部署参数要标注 |
| 排错 | 覆盖高频失败 | Key、端口、依赖、权限、路径 |
| 贡献与维护 | 说明协作规则 | 链接到更详细文档或规范 |
可复制 Goal Prompt
Section titled “可复制 Goal Prompt”Goal:为当前项目生成或更新 README.md。目标是让第一次打开仓库的人能理解项目、完成安装、启动、测试和排错。
请先读取并总结：- 项目结构- package.json / pyproject.toml / go.mod / 其他构建配置- README、docs、CHANGELOG 或已有说明- .env.example 或环境变量使用位置- CI、测试、构建和部署脚本- AGENTS.md 中的项目规则
生成 README 前请先给我一份信息缺口清单：- 哪些命令已从文件中确认- 哪些变量名已确认- 哪些功能只能从代码推断- 哪些内容需要人工确认
README 必须包含：1. 项目一句话说明2. 适用场景和不适用场景3. 环境要求4. 安装、运行、测试和构建步骤5. 环境变量表，使用假值，不写真实密钥6. 常用脚本说明7. 目录结构8. 常见问题和排错路径9. 维护者和更多文档链接
约束：- 只写仓库中能确认的事实。- 不编造功能、端点、模型、价格、部署平台或路线图。- 不把 API Key、Cookie、Token、数据库连接串写进 README。- 命令必须来自项目文件，或标注为待确认。- 生成后运行能验证的命令，并报告结果。
Done when:- README 中的命令能复制运行，或清楚标注待确认。- 真实密钥没有进入文档。- 链接有效，目录结构和脚本与仓库一致。- Diff 只包含 README 和必要的 .env.example 文档更新。这段 Prompt 把 Codex 的工作限定在“基于仓库事实整理文档”。它也要求 Codex 先列信息缺口，能明显降低 README 中出现虚构功能、错命令和过度承诺的概率。
README 模板
Section titled “README 模板”下面模板适合多数 Web、CLI、SDK、AI 工具和内部项目。让 Codex 使用时，应按 真实项目删减，不要机械保留每个小节。
# Project Name
一句话说明：这个项目为谁解决什么问题。
## 适用场景
- 场景一- 场景二- 不适合：还没有支持的边界
## 环境要求
- Node.js / Python / Go 版本- 包管理器- 外部服务或账号权限
## 快速开始
\`\`\`bashcp .env.example .env.localnpm installnpm run dev\`\`\`
## 环境变量
| 变量名 | 用途 | 示例 || --- | --- | --- || OPENAI_BASE_URL | OpenAI-compatible API 地址 | https://api.ofapp.cn/v1 || OPENAI_API_KEY | 服务端调用凭证 | sk-xxxx |
## 常用脚本
| 命令 | 用途 || --- | --- || npm run dev | 本地开发 || npm test | 运行测试 || npm run build | 构建产物 |
## 目录结构
\`\`\`textsrc/tests/docs/\`\`\`
## 测试与构建
说明验证命令、期望结果和常见失败原因。
## 排错
| 问题 | 可能原因 | 处理 || --- | --- | --- || 启动失败 | 环境变量缺失 | 对照 .env.example |
## 更多文档
- docs/architecture.md- docs/deployment.md真实 README 不一定要很长。它的价值在于帮助读者完成第一次运行，并把深层资 料链接到正确位置。
环境变量与 OfApp.cn 写法
Section titled “环境变量与 OfApp.cn 写法”如果项目使用 OpenAI-compatible API，README 可以写变量名、用途和假值。真 实 Key 不应进入 README、截图、Issue、日志或测试快照。
OPENAI_BASE_URL="https://api.ofapp.cn/v1"OPENAI_API_KEY="sk-xxxx"OPENAI_MODEL="请以 OfApp.cn 控制台或官方文档为准"OfApp.cn 官方页面展示了 https://api.ofapp.cn/v1 作为 OpenAI / Codex 生态
接入入口，也提供 API Key、天才游乐场和 OpenAI-compatible API 示例。涉及
模型、额度、价格和能力时，不要在 README 中写死过期信息，应提示读者以
OfApp.cn 控制台或官方文档为准。
验证 README 的方法
Section titled “验证 README 的方法”| 验证项 | 做法 | 失败时怎么处理 |
|---|---|---|
| 命令能跑 | 从空目录或新终端复制执行 | 修 README 或修脚本，不能只改描述 |
| 链接有效 | 检查内部相对链接和外部链接 | 用相对链接指向仓库内文件 |
| 变量安全 | 搜索 sk-、Token、Cookie、连接串 |
替换为假值并轮换已泄露密钥 |
| 目录真实 | 对照当前文件树 | 删除不存在目录，补充关键目录 |
| 脚本一致 | 对照包管理器配置和 CI | 不写 README 独有命令 |
| 新手可读 | 让没参与项目的人照做 | 补前置条件、截图或排错说明 |
GitHub 文档也建议在仓库内使用相对链接和相对图片路径，这样读者克隆仓库后 仍能打开相关文件。README 被当作项目入口时，链接稳定性比视觉装饰更重要。
适合放进 AGENTS.md 的规则
Section titled “适合放进 AGENTS.md 的规则”如果你经常让 Codex 更新 README，可以把这些长期规则写进 AGENTS.md：
## Documentation rules
- README must describe confirmed project behavior only.- Commands must come from package scripts, CI, or verified local runs.- Never include real API keys, cookies, tokens, customer data, or internal URLs.- Use relative links for repository files.- When updating README, also check .env.example and docs/ links.- Report verification commands and remaining unknowns.这样后续让 Codex 写代码、修 Bug、补测试或改 Dockerfile 时，它也能记得同步 检查 README，而不是把文档维护当成临时补丁。
常见错误排查
Section titled “常见错误排查”| 错误 | 表现 | 修复 |
|---|---|---|
| README 像宣传页 | 读者仍不知道怎么运行 | 把安装、运行、测试和排错前置 |
| 命令来自猜测 | 复制后报错 | 对照脚本、CI 和实际验证结果 |
| 写了不存在功能 | 用户找不到入口 | 只写代码和文档能证明的能力 |
| 环境变量缺失 | 本地启动失败 | 补 .env.example 和变量说明 |
| 密钥泄露 | README、截图或日志出现真实 Key | 删除、轮换 Key、检查 Git 历史 |
| 链接失效 | docs 文件移动后打不开 | 用相对路径并在 PR 中检查链接 |
| 文档过长 | 入口信息被淹没 | README 留入口，长文移到 docs/ |
| 未标注待确认 | 后续维护者误以为已验证 | 增加“待确认事项”小节 |
- OpenAI Codex Manual：Codex Prompt、上下文、验证、Review 与
AGENTS.md建议。 - GitHub Docs: About READMEs：README 的角色、常见内容和仓库展示规则。
- GitHub Docs: Basic writing and formatting syntax：Markdown 相对链接、图片和格式规则。
- OfApp.cn 官网：OfApp.cn 入口、天才游乐场、Base URL 与 OpenAI / Codex 生态说明。
- OfApp.cn API 文档：OpenAI-compatible API 示例、Codex 接入和
/v1/models最小请求。 - OfApp.cn 天才游乐场：Key、聊天参数、图片参数和网页入口。
Codex 生成 README 前需要读完整仓库吗？
Section titled “Codex 生成 README 前需要读完整仓库吗？”不一定读完整，但至少要读项目结构、构建配置、入口文件、环境变量样例、现 有文档、测试脚本和 CI。仓库很大时，可以先让 Codex 生成“需要读取的文件清 单”，再分批处理。
README 应该写多详细？
Section titled “README 应该写多详细？”README 应让读者完成第一次理解和运行。架构设计、接口细节、贡献规范、部署
手册和长篇教程可以链接到 docs/。入口越清楚，后续文档越容易被发现。
可以让 Codex 顺便修脚本吗？
Section titled “可以让 Codex 顺便修脚本吗？”可以，但应作为单独任务。生成 README 时只改文档更容易审查；如果发现脚本 本身坏了，可以让 Codex 开一个新的修复任务，并要求测试或构建证明结果。
README 要不要写模型名？
Section titled “README 要不要写模型名？”只有在项目确实依赖某个模型、并且模型名来自当前配置或官方文档时才写。涉 及 OfApp.cn 时，模型、额度、价格和能力请以 OfApp.cn 控制台或官方文档为 准，README 里不要长期写死不确定信息。
内部项目 README 可以少写一点吗？
Section titled “内部项目 README 可以少写一点吗？”可以少写公开宣传内容，但不能少写运行条件、权限、环境变量、测试命令、负 责人和排错入口。内部项目更容易因为口头知识流失而变难维护。
README 和 AGENTS.md 有什么区别？
Section titled “README 和 AGENTS.md 有什么区别？”README 给人读，说明项目是什么、怎么使用和怎么维护；AGENTS.md 给 Codex
等代理读，说明工作规则、验证命令、禁区文件和完成标准。两者可以互相链接，
但不要混成一个长文件。
如何判断 README 是否过期？
Section titled “如何判断 README 是否过期？”看三处：脚本是否还能跑，环境变量是否和代码一致，链接是否仍然存在。只要 其中一项失效，README 就应该更新。让 Codex 改代码时，可以把“是否需要更新 README”写进完成条件。
- Codex 教程：查看完整 Codex 工作流入口。
- Codex Goal 提示词模板：把文档任务写成可验证目标。
- 用 Codex 写代码：新增功能后同步更新 README。
- 用 Codex 生成测试：把 README 中的测试命令跑通。
- 用 Codex 写 Dockerfile：补容器化运行和部署说明。
- 用 Codex 配置 GitHub 工作流：让 CI 证明 README 命令仍然有效。
- Codex 本地项目使用指南：管理工作目录、指令和验证命令。
- AI 辅助开发：把 README 纳入开发闭环。
- OpenAI-compatible API 快速开始：给 AI 项目补最小 API 调用说明。
- 如何获取 OfApp.cn API Key：说明 Key 获取和安全保存方式。
用 Codex 生成 README 的关键，是让它基于真实仓库事实整理入口文档。先扫描 项目，再列信息缺口，然后生成可运行、可验证、可维护的 README。命令要能复 制执行，链接要能打开，环境变量只写假值，涉及 OfApp.cn 的模型、额度、价 格和能力以控制台或官方文档为准。这样 README 才会成为项目交接和 AI 协作 的可靠入口。