这是一套面向实践的 Codex 学习与开发资料库，包含：
- Codex Harness 22 个功能模块的分阶段学习讲义；
- 完整学习路线、自测答案与解析；
- 一个兼容 Codex 和 Claude Code 的垂直 Agent 定制开发 Skill；
- 可直接下载的学习资料包和 Skill ZIP。
本仓库适合希望完成下面这条路线的学习者：
理解 Codex Harness
→ 掌握运行、上下文、工具、安全、恢复与多 Agent 机制
→ 分析垂直领域需求与业务约束
→ 选择 generic、Codex 或自定义 Harness Profile
→ 定位实际组件、依赖关系与受影响源码
→ 研究并选择 RAG、Memory、Tool、评测等技术
→ 经人工确认后分阶段开发
→ 每阶段独立验收并保留可回滚证据
说明：这是学习与二次开发资料，不是 OpenAI 或 Anthropic 官方教程。Codex 源码和产品能力会持续更新，实施时应以目标仓库中的实际代码与最新官方文档为准。
不想逐个下载文件，可以直接使用两个压缩包：
也可以克隆整个仓库：
git clone https://github.com/fiofio66/codex_learning.git
cd codex_learning| 顺序 | 资料 | 学习重点 |
|---|---|---|
| 1 | 完整学习路线（简洁版） | 建立整体地图，确定学习节奏 |
| 2 | 模块 1–5：核心运行机制 | 启动、配置、会话、Agent Loop 与任务执行 |
| 3 | 模块 6–10：上下文模型与流式通信 | 上下文、模型调用、事件、流式输出与交互 |
| 4 | 模块 11–15：工具执行、安全与持久化 | Tool、Shell、权限、Sandbox 与状态持久化 |
| 5 | 模块 16–22：恢复、记忆、多智能体与产品化 | Resume、Memory、Multi-Agent、评测与产品边界 |
| 6 | 模块 1–22 自测答案与解析 | 核对理解、关键判分点和薄弱环节 |
建议先完成每册中的自测，再打开答案文档。纯文本版顺序说明见 README_学习顺序.txt。
Skill 位于 skills/agent-development-orchestrator/，用于设计和开发生产级垂直领域 Agent，可在 Codex 或 Claude Code 中运行。它默认使用框架中立的 generic Profile；只有真正修改 Codex Harness 时才启用 codex 的 22 模块映射，也支持可校验的内部自定义 Profile。
它不是一个简单的代码生成提示词，而是一套带强制质量门槛的开发总控流程：
- 询问或发现 Git 仓库、目标分支和回滚基线；只有 GitHub/Git URL 时，可克隆到新的隔离开发目录后继续；
- 需求澄清支持
GUIDED、DEEP-GRILL、SKIP三档，允许随时缩短、停止或跳过； - 用两个正交维度识别技术形态与业务领域，并通过可复用 Domain Pack 绑定术语、合规控制、KPI、典型失败和数据来路；
- 在批准前完成领域数据获取、权利/脱敏、标注、分割、gold set 与签字人计划；
- 对实际采用的技术检查当前官方或一手资料，由独立 Research Validator 对逐条声明、来源内容哈希、时效性和场景适配性复核；
- 使用内置索引器建立模块、导入、反向依赖、Git 热点和变更影响图；多仓项目还会为每仓建立不可变基线与显式跨仓契约；
- 为每个阶段锁定允许修改、条件修改和禁止触碰的文件集合；不支持的语言会显式标记
LOW-CONFIDENCE FENCE，不伪装成可信保护集； - 通过 Harness Profile 只映射真正存在或计划中的组件；
codexProfile 才需完整 22 模块表； - 按需生成需求、架构、技术决策、开发计划和验收标准，
LEAN只生成 6 个核心文件； - 开发前强制进行一次明确的人工确认；
- 按
LEAN、STANDARD或ASSURANCE模式分阶段实现，每阶段由新的技术 Validator 验收；非通用、高影响或 ASSURANCE 项目还强制经过具名 Domain Validator； - 最终由新的 Integration Validator 验收，并用
.agent-dev/保存状态、决策、影响范围、结构化证据、Git 检查点和防篡改日志。
详细规则见 SKILL.md。RAG 选型参考见 rag-strategy-guide.md。
| 模式 | 适用场景 | 验收策略 |
|---|---|---|
LEAN |
本地、可逆、低风险的小改动 | 仅一个实现阶段；该阶段的新独立 Delivery Validator 报告可复用为最终交付结论 |
STANDARD |
常规垂直 Agent 开发，默认模式 | 每阶段独立 Validator；另启新的 Integration Validator 做最终集成验收 |
ASSURANCE |
安全、隐私、合规、多仓、生产关键或高不可逆变更 | 在 STANDARD 基础上强化密封测试、真实依赖、安全/恢复验证，并强制独立 Domain Validator |
初始化示例：
python3 skills/agent-development-orchestrator/scripts/init_agent_dev.py \
--root /path/to/project \
--project-name "Customer Support Agent" \
--execution-mode STANDARD \
--harness-profile generic \
--domain general例如保险理赔 Agent 可改用 --execution-mode ASSURANCE --domain insurance --risk-overlay regulated-data，再使用 domain_pack.py materialize 将领域基线绑定到项目。内置 Pack 只是待复核的发现起点，不代替当前法规、医疗/税务等专业意见或具名专家签字。
- 已在本地仓库中运行：Skill 会核验真实 Git 根目录、远端、分支、HEAD 和未提交改动，并优先建立隔离分支或 worktree。
- 只提供 GitHub/Git 地址：Skill 会先确认目标分支和访问方式，再克隆到一个新的专用目录，核验远端与基线后分析和开发。
- 私有仓库：只使用用户环境已有的 Git/SSH 凭据，不应把 Token 写入聊天、URL 或
.agent-dev/。
开发批准不等于允许推送、开 PR、部署或发布；这些操作仍需单独授权。
当前 Codex 源码会从 ~/.agents/skills/ 发现用户级 Skill；~/.codex/skills/ 仍作为兼容路径存在。推荐安装到前者：
mkdir -p ~/.agents/skills
cp -R skills/agent-development-orchestrator ~/.agents/skills/只想在单个仓库中启用时，可以复制到目标项目：
mkdir -p /path/to/project/.codex/skills
cp -R skills/agent-development-orchestrator /path/to/project/.codex/skills/重新打开 Codex 任务后，可以这样发起：
使用 $agent-development-orchestrator，基于当前 Codex Harness 开发一个客服 Agent。
采用深度需求访谈；先研究并推荐适合这个场景的 RAG、Memory、评测、部署和代码图方案；开发前让我确认。
Codex Skill 发现机制可参考 OpenAI Codex 官方源码。
用户级安装：
mkdir -p ~/.claude/skills
cp -R skills/agent-development-orchestrator ~/.claude/skills/项目级安装：
mkdir -p /path/to/project/.claude/skills
cp -R skills/agent-development-orchestrator /path/to/project/.claude/skills/进入项目并启动 Claude Code 后，可让 Claude 根据描述自动使用，也可直接调用：
/agent-development-orchestrator 为当前项目设计并开发一个垂直领域 Agent
Claude Code 的 Skill 目录和发现规则见 Anthropic 官方 Agent Skills 文档。
所有实际采用的技术都必须核对当前官方或一手资料，但不会对每个可逆实现细节都制造冗长的候选方案：高风险决策需要候选比较、推荐和用户选择；常规组件需要当前来源与推荐；低风险细节保留简洁的兼容性或惯例依据。RAG、Memory、模型、Tool、数据层、评测和部署会根据真实场景研究，而不是套用固定技术栈。
对任何 Harness 的处理顺序是：
配置/Profile
→ Tool、MCP、Skill、Plugin 等扩展
→ Adapter 或产品层组合
→ 小范围修改 Core
→ 删除模块或大规模 Fork
产品不暴露某项能力，不等于必须从源码中删除它。这样可以减少安全回退和上游同步风险。
Skill 不只搜索文件名，还会组合多层证据：
工作区/构建依赖
+ import 与符号调用
+ 路由、注册表、DI、事件和任务等运行时关系
+ API、Schema、数据库与消息契约
+ 测试、CI、部署和代码所有权
+ Git 历史信号
→ system_map.md
→ change_impact.md
→ allowed / conditional / protected edit sets
每个 Validator 都必须从实际 Git diff 重建改动文件集合，并与批准过的边界对比。即使测试通过，出现无法解释的越界修改也不能判定通过。
内置索引器不依赖外部 Skill，默认只读运行，并输出机器可读 JSON 或便于审阅的 Markdown：
python3 skills/agent-development-orchestrator/scripts/repository_index.py \
--root /path/to/project \
--target src/changed_module.py \
--baseline origin/main \
--format markdown它会分析 Python、JavaScript/TypeScript、Rust、Java/Kotlin/Scala、C# 和 PHP 的结构导入与反向依赖，并盘点 R、SQL、Apex、ABAP、COBOL 等企业语言。当目标语言没有结构解析器时，输出会显式降级为 LOW-CONFIDENCE FENCE，不会把文本候选边冒充成确定依赖。大型或特殊技术栈仍可按需接入项目原生构建图、LSP 或经研究选定的代码图后端。
Skill 将 Agent 形态与业务领域分开。内置 healthcare、legal、financial-services、insurance、education、supply-chain、tax 和 general 起始 Pack，并支持组织自己的可版本化 Pack。每份 Pack 都需在实际项目中重新核验来源、辖区、控制项、术语版本/许可、KPI、失败模式和数据来路。
领域验收将 RAG 以外的任务也结构化为分类、抽取、决策、生成和工作流指标，要求切片阈值、高代价失败、数据集/指标版本与限制声明。技术 Validator 只能证明工程行为；必要时必须由与开发者分离、具有指定能力范围的 Domain Validator 签字。
需求访谈、项目地图、变更影响和范围护栏都已写入本 Skill 的内置协议；不会在运行时调用 Matt grilling、Maggy、Code Change Impact 等外部 Skill。
对于大仓库，可以在重新调研并得到用户选择后，使用可选的开源代码图后端加速，例如 codebase-memory-mcp、SignatureMap、SCIP、GrepAI，或项目已使用的 Nx/Bazel/Pants/rust-analyzer。没有任何额外安装时，仍可使用项目原生构建图、LSP、Git 和 rg 完成完整流程。选型说明见 open-source-code-intelligence.md。
每个阶段必须由没有参与该阶段实现的 Validator 检查；最终集成验收还要使用另一个新的 Validator。验收报告需要结构化证据、文件哈希和可观察结果。
机器判断只读取 .agent-dev/evidence/*.json；对应 Markdown 报告不承载隐藏语法。可以使用内置 evidence_tool.py 生成、校验 Evidence，默认拒绝覆盖已有证据，减少历史记录被误改的风险。
Skill 会维护：
PROJECT_OVERVIEW.md：给人快速理解项目；.agent-dev/discovery.md：需求访谈模式、设计树、每轮问题与确认/跳过证据；.agent-dev/system_map.md：STANDARD/ASSURANCE 的项目结构、依赖、运行时、契约、数据和测试关系；.agent-dev/change_impact.md：STANDARD/ASSURANCE 的阶段影响与允许/条件/禁止修改边界；.agent-dev/plan.md：LEAN 模式下合并了设计、组件映射、影响边界、验收与回滚的单文件计划；.agent-dev/domain/pack.json：当项目触发领域门时，保存已版本化、哈希绑定并完成项目适用性复核的 Domain Pack；.agent-dev/dataset_plan.json：数据权利、脱敏、标注、分割、gold set、签字与退化方案的权威机器合同；.agent-dev/checkpoint.json：机器可读的流程状态；.agent-dev/status.md：当前进度和下一步；.agent-dev/decisions.md：STANDARD/ASSURANCE 的关键决策；LEAN 将结构化决策存入 checkpoint；.agent-dev/journal.jsonl：带哈希链的步骤日志；.agent-dev/git_checkpoints.md：STANDARD/ASSURANCE 的阶段 Git 记录；LEAN 将它们存入 checkpoint；.agent-dev/rollback.md：经确认的回滚与补偿方案。
需求或架构发生实质变化时，旧批准和旧验收结果会失效，必须重新确认后继续。
codex_learning/
├── README.md
├── docs/ # Word 学习讲义与学习顺序
├── downloads/ # 可直接下载的学习资料包和 Skill ZIP
└── skills/
└── agent-development-orchestrator/
├── SKILL.md
├── agents/
├── references/
├── schemas/
├── scripts/
└── tests/
本次更新完成了以下验证：
- 54 项自动化测试通过，覆盖三种执行模式、真 LEAN 全链路、Harness Profile、Domain Pack/Validator、数据计划、语义研究证据、多仓契约、Checkpoint 状态转换、Evidence 防覆盖和仓库影响分析；
- Skill Creator 结构校验通过；
- 完整 LEAN 交付链、通用 ASSURANCE + Domain Validator 链均可达到
VALID； - 三个独立 Validator 分别完成行为/负向门禁、代码智能/包结构、领域/数据/研究证据验收；
- 最终 ZIP 不包含
__pycache__、.pyc或外部运行时依赖。
Skill ZIP SHA-256：
44b114db5843cd9de14e574382737f19ad93c9b0344c5255b83d205fc53391af
如果在学习资料中发现表述不清、模块变化或源码路径失效，可以提交 Issue。若改动会影响 Skill 的架构、验收标准或安全边界，应按 Skill 自身的变更流程重新研究、确认和验证。