Codex零基础学习手册

一、手册定位与整体架构

本手册是一本面向零基础学习者的系统性入门指南，共40章（400页），旨在帮助读者从完全不会使用Codex到能够独立完成企业级项目的开发、调试、测试、审查和交付。全书以"目标→探索→计划→修改→验证→保存"为核心工作闭环，逐步建立读者对Codex的完整理解与实操能力。

手册分为四篇，每篇约10章，难度递进：

二、第一篇：Codex基础入门与第一个项目（第1-12章）

第1-4章：认识、安装与首次使用

• Codex是什么：OpenAI的编码智能体，能够进入被授权的工作环境，围绕真实项目连续执行读取、搜索、修改、运行命令和检查结果等操作。它不只是生成回答，而是交付可检查的实际成果（修改后的文件、运行结果、测试记录、代码差异等）。

• 与普通AI对话的区别：普通AI擅长解释概念和生成片段代码，Codex擅长在真实项目中推进任务并交付实际变化。

• 使用入口：ChatGPT桌面应用（图形界面，零基础首选）、Codex CLI（终端）、IDE扩展（编辑器旁）、Codex云端（远程隔离环境）。本书从桌面应用开始。

• 首次使用路线：下载安装ChatGPT桌面应用→登录→建立专用学习目录→只打开空白项目文件夹→完成只读检查→创建第一个"AI学习导航页"→在浏览器中验收→提出有限修改→完成人工验收。

第5-8章：理解文件、终端、项目与版本控制

• 文件与路径：理解项目根目录、目录树、扩展名（.html/.css/.js/.md等）、绝对路径与相对路径的区别。文件移动后，相关引用必须同步更新。

• 终端与工作目录：命令总是在当前工作目录中执行。Get-Location（pwd）查看当前位置，Get-ChildItem（ls）查看内容，Set-Location（cd）进入目标目录，Ctrl+C停止持续命令。

• HTML/CSS/JavaScript职责：HTML负责内容和结构，CSS负责外观和布局，JavaScript负责交互行为。第三方依赖是需要额外使用的外部代码包或工具。

• Git版本控制：git status查看文件状态，git diff查看未暂存修改，git add加入暂存区，git commit保存版本，git restore放弃未提交修改。Git≠GitHub，前者是本地版本管理，后者是远程协作平台。

第9-12章：任务设计、探索、执行与验证

• 模糊想法→可执行任务：使用六要素任务卡——目标、背景、范围、非目标、输出、验收。例如"帮我加个搜索"需要明确搜索对象、与现有筛选的关系、无结果时的行为等。

• 先探索再修改：涉及多个关联文件时，先让Codex只读探索项目结构，形成实施计划，人工批准后再执行。

• 四类基础动作：读取文件、搜索内容、修改文件、运行命令。

• 验收不等于完成说明：验收需要组合多种证据——Codex完成说明、Git状态与差异、静态检查、浏览器测试、回归检查、执行边界核对。只有真实测试通过后，才能创建验证文档和Git提交。

三、第二篇：从零完成个人项目（第13-16章）

第13章：需求定义与范围

从真实问题出发（个人资料和任务分散），确定：

• 核心使用者：单机环境中的个人用户

• 数据字段：id、type、title、category、status、note、createdAt

• 固定选项：类型（资料/任务）、分类（工作/学习/行业研究/AI工具/内容创作/其他）、状态（待处理/进行中/已完成）

• MVP范围（第14章）：新增、展示、localStorage保存、基础统计、空状态

• 迭代范围（第15章）：搜索、分类筛选、状态更新

• 明确不做：删除、账号、数据库、云端同步、提醒通知、自定义分类、团队协作

• localStorage边界：数据绑定当前浏览器配置和项目位置，不适合敏感信息

第14章：创建MVP

• 最小闭环：打开页面→填写记录→写入localStorage→更新列表和统计→刷新后恢复

• 安全原则：用户输入必须用textContent或createElement安全渲染，不得直接拼入innerHTML

• 读写失败处理：读取失败时显示错误并暂停新增；写入成功后才更新页面状态，避免虚假成功

• MVP验收：表单完整、统计正确、刷新后数据保留、空状态和错误提示清晰

第15章：搜索、分类筛选与状态交互

• 第一次迭代：关键词搜索（title和note）+ 分类筛选，组合逻辑为"并且"关系。顶部统计基于全部记录，不随筛选变化。

• 第二次迭代：状态更新（待处理/进行中/已完成）在当前页面中联动统计变化。受控缺陷：状态变化后未调用保存函数写回localStorage——用于下一章调试训练。

第16章：调试、测试、优化与交付

• 稳定复现故障：状态改为"已完成"→页面变化→刷新→恢复原状态

• 证据定位根因：追踪状态变化事件→发现更新了内存records但未调用保存函数

• 最小修复：状态变化后复用已有保存函数写入localStorage，写入失败时保留原状态

• 回归测试：输入边界、新增任务、搜索筛选、状态持久化、原有功能

• 交付文档：docs/requirements.md（需求）、README.md（使用说明）、docs/validation.md（验证记录）

• v1提交：通过Git提交保存完整交付成果

四、第三篇：接手陌生项目与长任务管理（第17-24章）

第17章：让Codex读懂陌生项目

• 建立导入基线：git init + git add + git commit，标记接手时刻

• 区分仓库基线（分支、提交、文件）与运行时基线（浏览器、localStorage、示例数据初始化条件）

• 按层次阅读：README→入口HTML→模块职责表→数据流→三条核心流程（页面加载、新增任务、更新状态）

• 项目地图：记录模块职责、脚本加载顺序、任务字段、核心流程、高影响文件

第18章：增加新功能并控制范围

• 功能分支：git switch -c feature/task-due-date

• 截止日期业务规则：dueDate为可选字段（YYYY-MM-DD），缺失或无效日期不逾期，过去日期且未完成才逾期，逾期是派生结果而非新状态

• 日期处理原则：使用本地日历日期（getFullYear()+getMonth()+getDate()），避免new Date(dueDate)将纯日期误解释为UTC时间

• 影响分析：预计修改index.html、app.js、render.js、styles.css、README、测试清单；不修改constants.js、storage.js、filters.js、seed-data.js

第19章：证据型调试

• 稳定复现步骤：前置条件→操作→实际结果→预期结果→影响范围

• 六层调试证据：用户行为证据、数据证据、控制台证据、Git差异证据、代码路径证据、回归证据

• 根因示例：const dateValue = task.dueDate || "1970-01-01"导致无日期任务被错误标记为逾期

• 最小修复：前置判断缺失/无效日期，只有有效日期且早于今天且未完成才逾期

第20章：提交与合并请求

• 聚焦提交：一个功能一个提交，提交信息清晰描述成果

• PR说明四部分：背景、修改内容、验证结果、风险与限制

• 合并方式：使用"Create a merge commit"保留清晰合并关系

• 同步与清理：git pull --ff-only同步本地main，删除本地和远程功能分支

第21-24章：项目规则、知识包、计划文件、工作树与验证

• AGENTS.md：保存每次工作都必须遵守的稳定规则（数据不变量、修改边界、验证要求、Git操作边界），由Codex自动读取

• 最小知识包：

• docs/project-context.md：稳定的系统事实

• docs/decision-log.md：关键决策及原因（如"逾期是派生结果""使用本地日历日"）

• docs/current-state.md：当前基线、已完成能力、已知限制、下一项任务

• 计划文件（PLANS.md）：长任务的活文档，记录目标、阶段、进度、发现、决策、待验证事项，支持中断后恢复

• 工作树（Worktree）：在隔离目录中推进候选实现，不影响本地main，通过Handoff移回本地

• 浏览器验证：使用ChatGPT桌面应用内置浏览器（独立配置，不共享普通浏览器的localStorage），通过截图、控制台检查、运行时证据形成验证报告

五、第四篇：多入口协作、自动化、质量链与企业交付（第25-40章）

第25-28章：跨入口协作

• 桌面端：组织项目（一个项目一个主入口）、聊天（一项成果一条聊天）、运行环境（Local/Worktree/Cloud）

• CLI：适合目录、搜索和差异驱动的小型维护任务，从项目根目录启动codex

• IDE扩展：利用打开文件、选区、Markdown预览和源文件旁差异完成局部审查

• Codex云端：在隔离云环境中完成远程GitHub任务（纯文档任务示例：创建贡献者快速开始文档），通过PR合并后将结果同步回本地

第29-32章：可复用能力与自动化

• Skill：仓库级可复用工作流（.agents/skills/），比提示词更稳定。示例：project-change-review——只读审查项目变化，输出阻断/重要/建议三类问题，每条问题带文件证据

• MCP：连接外部工具和数据。示例：连接Context7公开文档MCP查询Codex Skill官方配置，区分文档支持与模型推断，未找到资料时明确报告

• 子智能体：将只读任务拆分为多个并行角色（如代码与数据流审查、输入与运行风险审查、文档与验证一致性审查），主智能体负责去重、复核冲突、形成最终结论

• 定时任务：只安排已人工验证的只读检查，使用最小权限，Run now试跑后主动暂停，不立即长期运行

第33-34章：非交互模式与SDK

• codex exec：一次性脚本任务，有明确输入、输出和退出状态。使用--sandbox read-only和--ask-for-approval never，结果保存到项目外部，失败时删除旧输出防止冒充

• Codex SDK（选修）：程序化控制Codex任务。核心对象：Codex客户端、Thread（持续上下文）、Turn（一次运行）。示例：第一轮读取项目状态，第二轮基于第一轮结果给出维护建议

第35章：GitHub质量链

• 三种质量信号职责分开：

• 确定性CI：检查可重复计算的规则（语法、文件存在、差异格式）

• Codex Review：检查高影响行为和仓库约束（数据不变量、回归风险、文档一致性），使用@codex review触发

• 人工批准：判断业务意图、风险接受、是否允许合并

• 三者缺一不可。CI失败不请求Review，Codex无发现不等于业务验收完成，模型审查不能替代人工批准

第36章：沙箱、审批、密钥、发布与团队规范

五条团队安全规则：

1. 只在可信工作区执行明确任务

2. 按任务选择最低权限（read-only → workspace-write → danger-full-access逐级评估）

3. 所有副作用（外部写入、推送、合并、发布）必须有明确审批

4. 密钥不进入代码、提示和日志

5. 发布必须人工授权，异常必须停止

四类任务分级：

• A｜只读：只读沙箱，可无人值守

• B｜项目内可恢复写入：工作区写入，保留Git差异

• C｜外部写入：明确审批，记录对象和结果

• D｜发布或高影响操作：人工授权、回退方案、双重确认

六、企业工单系统综合案例（第37-40章）

全书最后四章通过一个完整的企业工单管理系统案例，将所有前序能力整合为一条连续、可审查的工作链：

第37章：建立可信基线

• 检查数据和权限边界（不运行含真实客户数据的项目）

• 建立Git、依赖、数据库和测试基线

• 用页面、API和数据库证据稳定复现Bug（关闭工单后待处理数量未减少）

• 将模糊需求"工单转派"改写为具体业务规则（状态限制、目标坐席验证、原因必填、事务保证、操作人由服务端提供）

第38章：开发转派功能（跨层修改）

• 创建隔离Worktree和功能分支

• 新增转派历史表（ticket_assignment_history）

• 服务层集中业务规则，使用数据库事务保证更新负责人和写入历史原子性

• 前端对话框、错误处理和状态更新

• 测试覆盖成功、拒绝和事务回滚

• 形成聚焦提交：feat: add auditable ticket reassignment

第39章：修复统计Bug并补回归测试

• 先编写修复前失败的回归测试（closed工单不计入待处理）

• 发现根因：旧代码使用status !== 'resolved'，而当前状态体系已改为open/processing/closed

• 最小修复：明确待处理状态集合为['open', 'processing']

• 增加保护性测试：转派不改变状态汇总

• 形成独立修复提交：fix: exclude closed tickets from pending summary

第40章：正式交付

• PR、CI、Codex Review、人工技术审查、业务验收（UAT矩阵） 依次通过

• 区分缺陷与新增需求，避免PR无限扩张

• 合并后重新验证主分支

• 清理Worktree和远程分支

• 形成最终交接（当前能力、数据结构、运行方式、已知限制、后续建议）

本章关键认知："Codex完成"≠"团队完成"。Codex可以帮助探索、修改、测试、审查，但团队仍然负责确认业务规则、授予权限、执行业务验收、批准合并、承担运行责任。

七、手册核心方法论总结

全书贯穿一套稳定的工作方式：

Codex零基础学习手册.pdf（400页）

2026 AI Agent安全最佳实践.pdf

2026中国人工智能产业发展与商业应用白皮书.pdf（150页）

中国人工智能安全全景报告（2026）.pdf（100页）

2026 AI安全报告.pdf

中国企业级AI Agent发展洞察报告 ( 2026 ).pdf

深入理解 AI Agent.pdf（300页）

智能体交互安全要求.pdf

Claw类企业级智能体能力要求.pdf

2026年AI安全态势报告.pdf

算法备案指南.pdf

2026世界人工智能大会全景深度分析报告.pdf

通用型AI智能体L1–L5分级安全框架白皮书（2026）.pdf

2026人工智能十大趋势报告.pdf

全球人工智能治理趋势：《人工智能全球治理行动计划》以来的观察.pdf

T∕CIIA 068-2026 人工智能大模型生成内容安全评测方法.pdf

2026智能体创新实践汇编.pdf（300页）

2026人工智能发展白皮书.pdf（160页）

Claude Code 从入门到精通.pdf（150页）

Skill 蓝⽪书 2026.pdf（100页）

2026AI安全产业核心洞察.pptx（100页）

人工智能审计工具包应用与实践指南.pdf

Claude Code 学习手册.pdf（300页）

2026美国人工智能产业现状分析报告.pdf

面向 Token（词元）运营的大模型推理优化技术.pdf

欧盟《网络安全与人工智能行动计划》.pdf

AI Skill生态安全报告（2026上半年）.pdf

2026中国具身智能产业发展报告.pdf

中美通用人工智能发展比较研究.pdf

AI安全产业研究报告（2026）.pdf

2026人工智能治理白皮书.pdf

新加坡人工智能安全全景报告（2026）.pdf

人工智能管理系统的实施和审计：基于ISOIEC42001.pdf

2026年全球人工智能技术、政策、产业与投融资趋势全景洞察报告.pdf

人工智能的技术、运营与风险.pdf

AI大模型合规指南.pdf

GB∕Z 185-2026 人工智能 智能体互联 第1~7部分.pdf

2026年人工智能发展十大趋势.pdf

AI大模型安全评估及防护技术应用指南（2026）.pdf

中国AI Agent产业生态全景分析报告.pdf

2026年AI威胁态势报告.pdf

AI安全解决方案白皮书.pdf

AI生成内容安全及风控管理技术应用指南.pdf

智能体安全研究报告.pdf

OpenCode教程.pdf

AI安全：智能体安全新范式.pdf

人工智能实践：网络安全与取证领域的理论与应用.pdf

OWASP MCP Top10（2025）安全风险白皮书.pdf

下一代安全模式的生成式人工智能.pdf

政务领域人工智能大模型统一服务平台成熟度模型.pdf

大模型服务与应用安全评测技术规范.pdf

AI智能体：威胁分类、防御框架与落地实践.pdf

Hermes Agent 从入门到精通.pdf

人工智能 政务大模型系统技术要求.pdf

大模型服务安全白皮书.pdf

大模型面试手册（中文）.pdf

大模型工具大全.pptx

大模型评测幻觉检测.pptx

大模型能力技术培训.pptx

大模型的本地部署和微调.pptx

大模型与智能体安全.pptx

AI大模型评测能力建设及实践.pptx

大模型时代下的产品工程思路.pptx

-