术语与源码概念
每个术语解释它解决什么问题、在本实现中的位置，并给出具体例子。源码链接固定到本课程版本；示例用于推演，不能代替实际执行证据。
- Harness 运行框架
是什么
Harness 是包在模型服务外面的运行系统。它接受用户输入，持有任务状态，把当前可用指令、历史和工具组织成请求；收到工具意图后，再由真实程序完成操作并记入结果。它没有一个固定的同名类，本文用这个词描述多个模块的协作。
为什么需要
把模型生成、历史、工具与执行权限组织成一个可持续运行的系统。没有这些机制，模型的请求意图无法变成可核验的实际结果。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
你要求查找测试入口，框架先形成请求，再执行读取工具，把读取结果记入历史，随后发起第二次生成；这整条路径才是本课讨论的运行框架。
- CLI 命令行界面
是什么
通过终端输入命令和运行程序的界面。公开仓库首页明确介绍的是 Codex CLI。
为什么需要
让用户以命令、参数和终端输入启动任务，便于脚本化使用。
在本实现中
本课固定一个完整 Git 提交，源码链接按该提交建立。公开 CLI 和集成组件不构成闭源桌面或服务端全部实现的证明。
例子
运行 codex 是交互入口；codex exec 是面向非交互任务的另一入口。入口方式不同，不能据此推断核心策略完全不同。
- TUI 终端交互界面
是什么
在终端中显示输入框、消息、菜单等交互组件的界面。
为什么需要
在终端里管理输入、显示事件和收集交互决定。它是界面层，实际执行还要追到核心和执行器。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
终端中出现“等待批准”的界面，是显示并接收决定；限制文件访问的机制并不在这个文字组件里。
- 模型 内容生成系统
是什么
根据输入生成文本或结构化工具调用的系统。模型给出调用意图，实际执行由外部程序完成。
为什么需要
根据已收到的材料生成后续文字或结构化请求。读取文件、启动程序和保存记录需要外部实现。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
模型输出读取 config 文件的请求后，必须等待工具实际返回。文件不存在时，后续判断应该依据错误，而不是把先前猜测当成读取结果。
- 工具调用 结构化执行请求
是什么
包含工具名称、参数和调用标识的请求。它需要框架验证、分派并返回结果。
为什么需要
用结构化名称、参数和关联标识把生成结果交给执行系统，避免将自然语言计划直接当作已执行操作。
在本实现中
工具计划把可见规格和执行实现关联起来，按名称及命名空间分派。工具执行使用原请求的 StepContext，而不是随时读取一个不受约束的全局列表。
例子
一项调用可包含工具名、JSON 参数和 call_id。它被拒绝或取消时，需要返回相应状态，才能让后续请求知道实际发生了什么。
- 上下文 本次可见输入
是什么
上下文是模型本次生成能够看到的材料。通常包含指令、活跃历史、环境信息及工具规格，逻辑上并不只是一段提示词。磁盘里保存了某份原文、框架记得某个状态、模型这次真正收到了某段内容，是三个需要分别证明的事实。
为什么需要
限定当前请求能够据以判断的输入集合，使指令、历史、工具与容量可以管理。
在本实现中
core 的活跃历史管理器接纳协议项、截断单项输出，再在请求前做结构与媒体能力检查。磁盘记录有独立的持久化路径。
例子
一份日志在磁盘有一万行，活跃历史里可能只留下首尾摘要。磁盘上有资料，不代表这次请求带了所有内容。
- 回合 一次输入的处理过程
是什么
从接受用户输入到完成或中止的一段处理过程，可以包含多次模型请求与多次工具执行。
为什么需要
为一条已接受的用户输入建立处理生命周期，关联取消、事件与最后的完成状态。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
一次“定位错误并修复”回合可能先查文件、运行测试、修改，再多次生成；它不是一次网络请求的同义词。
- 会话 持续保存的运行状态
是什么
承载历史、配置、服务和运行状态的容器。一次会话可处理多个回合；代码中还有 thread（线程）等不同层级。
为什么需要
使多次用户输入可以沿用历史、服务和配置，不用每次重新建立所有状态。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
你先问结构，随后要求改测试，两条输入可能属于同一会话中的不同回合。回合结束不意味着历史容器被销毁。
- 采样 一次生成请求
是什么
向模型发起一次生成请求；这里并非统计抽样。一次回合可能重复采样。
为什么需要
向模型服务发起一次生成请求，并处理这一请求到达的输出。这里强调请求次数，不是统计抽样。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
第一轮生成提出工具请求，工具完成后第二轮生成解释结果；一个用户回合已经发生两次采样。
- 路由 请求或流量分派
是什么
工具路由根据名称匹配执行实现；网络路由根据地址与配置确定流量路径。二者在本课程分别解释。
为什么需要
按明确身份选择下一处理目标，避免把请求交给错误实现。工具路由和网络路由分别有自己的判断依据。
在本实现中
工具计划把可见规格和执行实现关联起来，按名称及命名空间分派。工具执行使用原请求的 StepContext，而不是随时读取一个不受约束的全局列表。
例子
名称相同但命名空间不同的两个查询工具，可以交给不同执行器；IP 流量的路由则依据网络目标与配置。
- 注册表 工具实现的索引
是什么
保存工具身份、暴露方式与执行实现之间关系的结构。
为什么需要
保存工具身份到执行实现的映射，供计划构造、查找和分派使用。
在本实现中
工具计划把可见规格和执行实现关联起来，按名称及命名空间分派。工具执行使用原请求的 StepContext，而不是随时读取一个不受约束的全局列表。
例子
只有一份“参数说明”而没有注册的执行器，模型即使提出名称正确的请求，也不能据此产生真实文件结果。
- 命名空间 独立名称或资源域
是什么
工具命名空间用于给名称分组；Linux 内核命名空间用于隔离资源视图。具体机制要看本处是工具名称、挂载、网络、IPC 还是 PID。
为什么需要
给名称分组或给资源划分独立视图，含义需要由所在领域确定。
在本实现中
工具计划把可见规格和执行实现关联起来，按名称及命名空间分派。工具执行使用原请求的 StepContext，而不是随时读取一个不受约束的全局列表。
例子
工具 namespace 可区分两个来源的同名工具；Linux 的 PID namespace 则改变进程编号视图。两者不能互相替代。
- 沙箱 执行权限边界
是什么
沙箱是限制执行进程能访问什么资源的机制集合。权限先用逻辑数据描述，实际启动命令时才由目标平台实施。它可以限制文件路径、网络或系统调用，但允许的写入仍然会修改文件；审批、回滚和沙箱是不同的问题。
为什么需要
在真实执行时限制可访问的资源，减小错误操作或受诱导命令能够影响的范围。
在本实现中
执行协调器确定要求后，平台转换器把逻辑权限落实到目标执行器。不同操作系统使用不同机制；远程任务要以目标执行器为准。
例子
工作根可写而 .git 为只读子路径时，正常产物可以写入，修改受保护配置则应在平台执行层被限制。
- 审批 执行前的授权判断
是什么
按策略决定操作是否允许、拒绝或需要请求批准。授权判断与操作系统限制是不同机制。
为什么需要
在执行前决定是否允许、拒绝或需要请求授权，留下该决定对应的操作范围。
在本实现中
命令先解析和评估规则，再把结果转成执行协调器可消费的授权要求。规则允许和解除平台限制并不是同一个条件。
例子
对一次受限执行的批准，不一定覆盖后续扩大权限的重试；严格审核分支要求重新审核更大的范围。
- Skill 按需加载的工作指南
是什么
以 SKILL.md 为入口的任务指导，可包含脚本和参考资料；它本身不自动授予执行权限。
为什么需要
保存对某类任务有用的工作步骤、判断条件和参考资源，让模型按需读取，不必将所有手册放入每次请求。
在本实现中
指南目录提供名称与说明，任务需要时才读取相应正文或资源。它指导选择与工作方法，执行权限仍由工具和环境决定。
例子
一个测试阅读指南可以要求先核对构建配置。读取指南不等于自动运行其中的脚本，更不等于扩大目录权限。
- MCP 外部工具连接协议
是什么
MCP 是客户端与能力服务交互的一套协议。服务可以提供工具清单、工具结果或可读取资源；Codex 再决定这些能力怎样进入本步计划。把一个服务配置进来，只说明有接入意图，认证、连接、可见性与执行授权仍是不同步骤。
为什么需要
统一连接外部提供的工具和资源，让客户端不必为每个服务重新定义全部接入方式。
在本实现中
外部工具先取得目录与规格，再经过有效配置、预算和暴露策略，形成当前请求可用的表面。连接、认证和授权分别检查。
例子
问题追踪服务返回一个查询工具。还要确认认证有效、工具规格通过筛选、当前步骤有入口，以及这次查询被允许。
- crate Rust 编译单元
是什么
Rust 的库或可执行程序组织单元，通常由 Cargo.toml 描述。
为什么需要
把 Rust 代码划成可以编译、测试或依赖的单元，明确组件边界。
在本实现中
仓库用 Rust/Cargo 构建，提供按 crate 运行的测试入口。本课程只核对这些源文件，不声称已编译或运行整套上游测试。
例子
codex-core 是包名，codex_core 是库名，目录是 core。三种名称不必字面一致，应以 Cargo.toml 的声明为准。
- Cargo Rust 构建工具
是什么
Rust 的包管理、构建和测试工具；工作区可以统一管理多个 crate。
为什么需要
读取包和工作区配置，解析依赖并执行构建、检查和测试。
在本实现中
仓库用 Rust/Cargo 构建，提供按 crate 运行的测试入口。本课程只核对这些源文件，不声称已编译或运行整套上游测试。
例子
cargo test -p codex-core 选择一个包；它不是只在任意当前目录搜几个文件名就能完成的操作。
- Rust 实现语言
是什么
注重内存安全的系统编程语言，本仓库核心实现主要使用它。
为什么需要
提供核心程序的实现语言及类型和并发约束。读 Rust 类型有助于辨认状态是否共享、能否变化。
在本实现中
仓库用 Rust/Cargo 构建，提供按 crate 运行的测试入口。本课程只核对这些源文件，不声称已编译或运行整套上游测试。
例子
Arc<StepContext> 表示多个执行路径可以共享这个对象；这与每个路径随时读取可变全局配置的设计不同。
- 异步 等待时让出执行
是什么
任务在等待网络或工具结果时可以让其他任务运行；不等于所有操作都同时执行。
为什么需要
等待网络或工具就绪时让出执行机会，减少一个等待动作阻塞所有工作。
在本实现中
工具调度检查并发能力：支持者取得共享门，不支持者取得独占门。等待、取消和结果收集仍要维持当前回合的关系。
例子
一个工具等待服务连接时，其他独立任务可能继续推进；但这个等待仍可以被取消。
- 并发 多个任务交错推进
是什么
多个任务在重叠时间段内推进。是否适合并发取决于依赖和执行限制。
为什么需要
让没有必要互相等待的任务在重叠时间内推进，提高利用率。
在本实现中
工具调度检查并发能力：支持者取得共享门，不支持者取得独占门。等待、取消和结果收集仍要维持当前回合的关系。
例子
读取两个独立文件可能共同推进，依据它们内容做修改则有数据依赖，需要等待相关结果。
- JSONL 逐行 JSON 文件
是什么
每行一个 JSON 对象的文本格式，适合追加事件和逐行读取。
为什么需要
每行独立记录一个对象，适合按事件追加和分段检查。
在本实现中
记录格式、来源元数据和运行状态各有用途。持久化可供复查，不保证每一份记录都会原样成为下一次请求。
例子
查看历史文件时可以逐行读取某次工具调用；单行记录出现，不证明整个外部操作能自动回滚或重新执行。
- JSON 结构化数据格式
是什么
用对象、数组等表达数据的文本格式。
为什么需要
用对象、数组和数值表示结构化请求与结果，便于程序验证和解析。
在本实现中
工具计划把可见规格和执行实现关联起来，按名称及命名空间分派。工具执行使用原请求的 StepContext，而不是随时读取一个不受约束的全局列表。
例子
工具参数可写成包含 path 和 limit 字段的对象；无效字段或错误类型要由解析与验证处理，不能靠文字猜测。
- 压缩 缩减活跃历史
是什么
本课的压缩是重新整理活跃请求窗口。它不等于压缩文件，也不保证所有信息都无损保留。普通摘要让模型生成交接说明，远程分支返回协议压缩项，TokenBudget 则可以直接建立新窗口；客户端还决定保留哪些原文与重新注入哪些当前事实。
为什么需要
减少活跃窗口需要携带的历史，同时尽量延续任务状态。具体分支可能摘要、保留原文或直接重建窗口。
在本实现中
运行循环先看 TokenBudget，再按 provider 能力选择 Remote V2 或普通摘要。选定原文、压缩结果与重新注入的指令分别装配。
例子
本地分支保留一定预算的近期用户原文并加交接摘要；TokenBudget 分支则不调用模型生成这份摘要。
- token 模型计量单位
是什么
模型处理文本等输入时使用的计量单位，不能简单等同于一个汉字或一个单词。
为什么需要
计量模型输入/输出容量，但它与字数不是一一对应。客户端预算还可能使用近似值。
在本实现中
core 的活跃历史管理器接纳协议项、截断单项输出，再在请求前做结构与媒体能力检查。磁盘记录有独立的持久化路径。
例子
此版本的一种文本估算把 UTF-8 字节数除以 4 向上取整；同样字符数的中文和 ASCII 文本，字节数可能不同。
- API 程序交互接口
是什么
程序之间约定的请求和响应接口。本文涉及模型服务接口与本地程序接口。
为什么需要
约定程序之间如何请求能力和返回结果，使调用方与实现方可以独立维护。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
模型接口返回生成事件，执行器接口接受启动请求。接口名字出现，并不能说明远端内部使用了哪一种算法。
- 流式响应 分批到达的输出
是什么
输出以事件或片段持续到达，文字片段、工具请求和完成事件需要分别处理。
为什么需要
让输出逐步到达并及时处理，而不是等待整个回答作为一条字符串返回。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
文字增量已经显示时，工具项可能还未完成；必须继续处理输出项和完成事件才能判断当前请求状态。
- 锁 共享状态访问门
是什么
锁用来协调多个执行路径对资源或顺序的共享。读锁通常允许多个持有者同时通过，写锁让一个持有者独占。在工具调度中，这个锁充当执行门；锁的名称描述共享方式，不能用来推断工具只读还是会写文件。
为什么需要
协调共享资源访问或执行顺序，防止需要独占的动作与其他动作互相干扰。
在本实现中
工具调度检查并发能力：支持者取得共享门，不支持者取得独占门。等待、取消和结果收集仍要维持当前回合的关系。
例子
并发执行门用共享读锁放行支持并发的工具，用写锁让不支持的工具独占；读锁名称不表示该工具只能读取文件。
- 单元测试 小范围行为检查
是什么
针对函数或模块行为的自动检查，常用固定输入验证边界。
为什么需要
用小范围固定输入检验函数或模块的具体边界。
在本实现中
仓库用 Rust/Cargo 构建，提供按 crate 运行的测试入口。本课程只核对这些源文件，不声称已编译或运行整套上游测试。
例子
给历史规范化输入一个有调用但无结果的集合，检查是否补了 aborted 输出，比只检查函数是否被调用更有意义。
- 集成测试 跨组件行为检查
是什么
验证多个组件组合起来的行为，可用模拟服务检查一整条请求链。
为什么需要
把多个组件组合起来，检查接口和状态转换是否一致。
在本实现中
仓库用 Rust/Cargo 构建，提供按 crate 运行的测试入口。本课程只核对这些源文件，不声称已编译或运行整套上游测试。
例子
模拟模型事件与工具响应，检查下一次请求是否真的带上对应结果；这仍只覆盖测试所设置的条件。
- commit Git 固定版本
是什么
一次代码提交的标识；完整 SHA 能让源码链接不随主分支移动。
为什么需要
给一次代码状态一个可追溯的版本身份，避免文章随主分支变化而失去定位。
在本实现中
本课固定一个完整 Git 提交，源码链接按该提交建立。公开 CLI 和集成组件不构成闭源桌面或服务端全部实现的证明。
例子
本课链接含完整提交标识；几个月后仍可以对照相同版本的行和类型，而不是自动转到新的 main。
- SHA 版本哈希标识
是什么
Git 提交的固定哈希值，本课程用完整的 40 位值固定源码。
为什么需要
标识 Git 提交内容及其历史位置，本课用完整值固定证据。
在本实现中
本课固定一个完整 Git 提交，源码链接按该提交建立。公开 CLI 和集成组件不构成闭源桌面或服务端全部实现的证明。
例子
本课固定 f82e36592278a0a782fb0d0fc97e5fa10e832ac2。短值便于显示，完整链接使用完整值避免歧义。
- TOML 配置文本格式
是什么
用键值和区段表达配置的格式，Codex 的 config.toml 使用这种格式。
为什么需要
用区段和键值保存人可编辑的配置。解析出来的值还要经历合并与约束。
在本实现中
配置读取、合并、信任和管理要求共同决定有效设置；不能只读单个文本文件就推断运行值。
例子
config.toml 中某个设置写了 true，管理要求可能仍将其固定关闭；文件内容和有效配置要分别核对。
- YAML 元数据文本格式
是什么
常用于描述名称、说明等字段。SKILL.md 顶部的元数据块采用这种格式。
为什么需要
保存指南名称、说明等元数据，便于低成本发现能力。
在本实现中
指南目录提供名称与说明，任务需要时才读取相应正文或资源。它指导选择与工作方法，执行权限仍由工具和环境决定。
例子
SKILL.md 顶部 name 和 description 让系统先看概要；实际任务匹配后才读取更长正文。
- handler 具体处理实现
是什么
接收参数并执行具体能力的处理实现。
为什么需要
承接某一工具的参数处理和能力执行，使路由无需知道每个工具的全部内部逻辑。
在本实现中
工具计划把可见规格和执行实现关联起来，按名称及命名空间分派。工具执行使用原请求的 StepContext，而不是随时读取一个不受约束的全局列表。
例子
文件读取 handler 解析路径并获得内容；它仍处于框架的取消、权限与结果记录链中。
- runtime 执行期实现
是什么
运行某项能力的状态和逻辑。在工具体系中，它承接工具的实际执行。
为什么需要
保存能力在执行时需要的逻辑和状态。不同层的 runtime 指代不同能力，不能只看名字。
在本实现中
工具计划把可见规格和执行实现关联起来，按名称及命名空间分派。工具执行使用原请求的 StepContext，而不是随时读取一个不受约束的全局列表。
例子
某 MCP handler 缓存不可变规格，不缓存一次授权快照；“执行实现可复用”不等于“批准可复用”。
- fixture 固定测试样本
是什么
用于复现测试的预设输入或响应，例如模拟模型返回的事件。
为什么需要
提供可复现的预设输入或响应，使失败不依赖随机服务状态。
在本实现中
仓库用 Rust/Cargo 构建，提供按 crate 运行的测试入口。本课程只核对这些源文件，不声称已编译或运行整套上游测试。
例子
测试固定返回一个工具请求和一个完成事件，就能检查历史如何变动，避免每次连接真实模型得到不同输出。
- feature flag 功能开关
是什么
控制某项功能是否启用的配置或编译设置。代码存在不意味着每个客户端默认启用。
为什么需要
按设置、模型能力或实验范围启用一条实现路径。代码存在和当前功能启用是两种事实。
在本实现中
配置读取、合并、信任和管理要求共同决定有效设置；不能只读单个文本文件就推断运行值。
例子
TokenBudget 通用默认关闭，模型激活默认值却可能请求开启；还要看管理要求是否允许。
- Cloudflare Pages 静态网站托管服务
是什么
可托管本课程的 HTML、CSS、JavaScript 和 SVG。部署由你在自己的账户中完成。
为什么需要
托管本网站的静态文件，不需要给这个课程配置模型 API 或数据库。
在本实现中
这一项描述本课程网站的实现或部署工具，而不是 Codex 核心的一个运行模块。
例子
直接上传提供的 Pages ZIP，其根层级是 index.html 与 assets；持续更新也可使用自己的 Git 集成项目。
- Git 代码版本管理工具
是什么
保存提交历史、固定版本并同步仓库的工具。
为什么需要
保存代码历史并获取指定提交，让阅读和复查基于相同代码状态。
在本实现中
本课固定一个完整 Git 提交，源码链接按该提交建立。公开 CLI 和集成组件不构成闭源桌面或服务端全部实现的证明。
例子
先克隆再 checkout 本课完整 SHA。安装的最新二进制不一定对应这一提交的构建产物。
- SVG 可缩放矢量图
是什么
使用文本描述图形和文字的图像格式，适合清晰的架构图。
为什么需要
用矢量图形和文本绘制架构，在放大时仍能保持文字与连线清晰。
在本实现中
这一项描述本课程网站的实现或部署工具，而不是 Codex 核心的一个运行模块。
例子
首页总图可以放大并滚动查看；图中的职责关系是教学组织，不声称每条箭头都等于一次函数调用。
- AGENTS.md 项目工作约定文件
是什么
提供当前项目或目录的工作指令；读取范围、信任和大小限制由实现控制。
为什么需要
保存当前项目或目录的工作约定，让运行系统有明确的项目指令来源。
在本实现中
环境与指令按分区形成当前状态和快照。完整注入与差量更新还检查模型历史中是否真正保留了对应片段。
例子
本版本按项目根到当前目录组合约定；进入子目录可能出现更具体指令，但不会无边界扫描所有个人目录。
- shell 命令解释器
是什么
解析并运行命令的程序；工具发起请求后才由执行环境运行。
为什么需要
解析命令语法、展开和组合，再启动程序。shell 包装不能只按外层程序名审查。
在本实现中
命令先解析和评估规则，再把结果转成执行协调器可消费的授权要求。规则允许和解除平台限制并不是同一个条件。
例子
bash -lc 后的内容可能含多条程序调用；规则解析支持范围决定能否把它拆成多条普通命令。
- Code Mode 用代码组织工具调用
是什么
把工具编排写成代码的执行方式；仍需匹配可用工具和执行边界。
为什么需要
用代码组织多个工具调用，降低逐项往返的编排成本。可见入口和嵌套工具仍由计划决定。
在本实现中
工具计划把可见规格和执行实现关联起来，按名称及命名空间分派。工具执行使用原请求的 StepContext，而不是随时读取一个不受约束的全局列表。
例子
DirectModelOnly 工具能直接提供给模型，却不作为嵌套代码工具开放；两个表面并不相同。
- app-server 客户端集成服务
是什么
公开仓库中的应用服务组件，用协议连接客户端与核心；不代表闭源桌面端全部实现。
为什么需要
提供公开的客户端集成服务与协议能力，连接界面操作和核心运行状态。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
客户端可以通过服务操作线程或接收事件，但看到这个组件并不能推出闭源桌面端所有界面和托管逻辑。
- SDK 程序开发工具包
是什么
供其他程序调用某项能力的开发接口与配套代码。
为什么需要
提供其他程序使用能力的开发接口和辅助类型，减少重复封装协议。
在本实现中
本课固定一个完整 Git 提交，源码链接按该提交建立。公开 CLI 和集成组件不构成闭源桌面或服务端全部实现的证明。
例子
一个程序可以通过 SDK 使用相关接口；SDK 是集成层，不是模型本体或独立的权限系统。
- JavaScript 网页脚本语言
是什么
本课程用它实现搜索、词典与学习记录；浏览器内执行，无需后端。
为什么需要
为本网站实现搜索、词典弹窗、图示放大和学习记录。
在本实现中
这一项描述本课程网站的实现或部署工具，而不是 Codex 核心的一个运行模块。
例子
术语按钮读取本地打包的词典数据，没有在你点击时向模型服务请求解释。
- HTML 网页内容标记
是什么
组织网页标题、段落、链接与表单的标记语言。
为什么需要
组织标题、正文、链接和表格等内容与语义，支持浏览器和辅助技术读取。
在本实现中
这一项描述本课程网站的实现或部署工具，而不是 Codex 核心的一个运行模块。
例子
每课有一个主标题，节标题有锚点；关闭脚本时正文及普通链接仍可阅读。
- CSS 网页样式规则
是什么
控制网页布局、颜色、字号和响应式适配的样式语言。
为什么需要
控制布局、字体、对比度和屏幕尺寸适配，不承担教程的业务逻辑。
在本实现中
这一项描述本课程网站的实现或部署工具，而不是 Codex 核心的一个运行模块。
例子
手机上主页面不横向溢出，宽表格在自己的容器中滚动，是布局规则提供的行为。
- Seatbelt macOS 限制机制
是什么
通过平台规则限制进程的资源访问；本版本在对应平台分支使用。
为什么需要
让 macOS 依据进程策略检查文件、网络及其他访问，不依赖模型遵守自然语言。
在本实现中
macOS 分支合成基础、文件和网络策略，追加保护规则，再使用固定路径的 sandbox-exec 包装原命令。
例子
框架生成策略字符串，把命令交给 /usr/bin/sandbox-exec；子进程继承相应限制。
- seccomp Linux 系统调用限制
是什么
限制进程能够发起的系统调用的机制；具体规则由平台实现设置。
为什么需要
在 Linux 进程执行系统调用时按过滤规则允许或拒绝，限制调用或参数范围。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
网络受限分支可以拒绝特定 socket family 和连接调用。它不是本版本文件路径边界唯一的实施机制。
- Landlock Linux 文件访问限制
是什么
Linux 内核提供的访问控制机制，仓库包含对应限制实现。
为什么需要
Linux 的一种文件访问控制机制，本仓库保留兼容实现。选择兼容代码需要核对当前入口条件。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
此提交文件受限执行要求 bubblewrap，不能因为还能找到 Landlock 源码，就假定它是失败时的自动降级路径。
- bwrap Linux 隔离执行工具
是什么
bubblewrap 的命令名称；通过命名空间等机制隔离进程环境。
为什么需要
bubblewrap 的命令名称，负责建立受限的挂载和资源视图。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
启动参数先建立只读根，再恢复可写目录，最后遮罩或恢复受保护子路径；顺序影响最终可见性。
- 受限令牌 Windows 权限限制
是什么
通过限制访问令牌降低进程权限的 Windows 机制。
为什么需要
把 Windows 进程的权限和可用于访问对象的身份限制下来，再由对象规则检查访问。
在本实现中
Windows 对应分支创建带限制身份和权限标志的令牌；文件控制还结合 ACL。不同后端和配置需要分别核对。
例子
CreateRestrictedToken 生成限制令牌；目录权限还要结合 ACL，不能单靠一个令牌名称证明所有路径都不可写。
- 钩子 特定时点的扩展逻辑
是什么
在开始、停止或工具使用前后等时点运行的扩展逻辑，可能影响继续或拒绝行为。
为什么需要
在明确的生命周期时点接入额外处理，可以补充输入、检查行为或阻止继续。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
压缩前钩子可以停止流程；停止回合的钩子也可能改变完成行为，所以文字输出完不总是最后一步。
- call_id 调用关联标识
是什么
把一次工具请求和它的结果对应起来的标识。
为什么需要
把一次请求与它的输出关联，避免多个相似调用的结果被混淆。
在本实现中
工具计划把可见规格和执行实现关联起来，按名称及命名空间分派。工具执行使用原请求的 StepContext，而不是随时读取一个不受约束的全局列表。
例子
两个工具同时完成时，结果应该按各自标识进入历史；有调用却没有结果时，请求前规范化会补相应状态。
- nextest Rust 测试运行器
是什么
提供测试运行和配置能力的工具；根 justfile 使用它运行测试。
为什么需要
按测试配置运行 Rust 测试并汇报结果，是仓库任务配方选用的测试运行器。
在本实现中
仓库用 Rust/Cargo 构建，提供按 crate 运行的测试入口。本课程只核对这些源文件，不声称已编译或运行整套上游测试。
例子
just test -p codex-core 进入对应配方后使用 nextest；本网站本身无需安装它。
- justfile 任务配方文件
是什么
just 工具读取的命令配方，根目录配方默认在 codex-rs 工作目录执行。
为什么需要
保存命令配方，统一构建、检查与测试入口的工作目录和参数。
在本实现中
仓库用 Rust/Cargo 构建，提供按 crate 运行的测试入口。本课程只核对这些源文件，不声称已编译或运行整套上游测试。
例子
根 justfile 默认切到 codex-rs。复制配方执行时必须知道它的工作目录，而不是只复制内部命令。
- bubblewrap Linux 进程隔离工具
是什么
通过挂载视图和内核命名空间建立受限进程环境，命令通常叫 bwrap。本版本 Linux 主路径先使用它，再进入 seccomp 阶段。
为什么需要
给 Linux 子进程建立受限资源视图，把路径可见性和可写挂载变成实际内核机制。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
如果可写工作目录是 bind mount，命令写入仍影响原始宿主文件；建立隔离视图不等于提供事务回滚。
- 挂载命名空间 独立挂载视图
是什么
Linux 内核机制：同一个路径在不同进程环境中可以指向不同的挂载；不等于复制所有文件。
为什么需要
让不同进程看到独立挂载表，在同样路径下可以显示不同资源，实施路径可见性。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
宿主能看到一个目录，受限视图可用空挂载遮罩它；这一操作不需要把宿主所有文件先复制一遍。
- 网络命名空间 独立网络栈
是什么
Linux 内核机制：隔离网络接口、路由和套接字所属网络环境。代理路由模式还需要专门的桥接逻辑。
为什么需要
隔离网络接口和路由状态，使受限进程不能自然沿用宿主网络栈的全部能力。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
托管代理分支需要在隔离网络里准备代理路由；“有网卡”不等于允许向任意互联网地址直连。
- bind mount 重映射目录挂载
是什么
把现有文件或目录挂载到某个路径。只读挂载限制写入，可写挂载仍会写到原来的文件。
为什么需要
把已有文件或目录挂载到另一条路径，控制它在某个视图中的访问方式。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
--ro-bind 保持只读，--bind 可重开允许目录的写权限；后者写到原对象，不是自动生成副本。
- tmpfs 内存文件系统
是什么
可用于建立空的文件系统视图或覆盖路径。它改变路径可见性，不是语义上的文件权限规则。
为什么需要
以空的内存文件系统建立基础视图或遮罩路径，用于收敛可见范围。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
局部可读策略可从 tmpfs 根开始，只把明确的可读目录挂回去，而不是默认露出整棵宿主根。
- no_new_privs 禁止获得新权限
是什么
Linux PR_SET_NO_NEW_PRIVS 标志，使后续 exec 不因 setuid 等机制提升权限，并支持安全安装 seccomp 过滤器。
为什么需要
防止后续 exec 因可执行文件的特权属性获得新权限，并为安装相应系统调用过滤提供安全条件。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
进入内层限制后，执行带特权属性的程序不应因此自动扩大权限；该标志不独立决定文件路径白名单。
- ACL 访问控制列表
是什么
给对象列出主体及其允许或拒绝权限。Windows 沙箱的文件边界需要与令牌机制配合。
为什么需要
给文件等对象列出身份及允许/拒绝规则，让受限身份访问时能够被对象层判断。
在本实现中
Windows 对应分支创建带限制身份和权限标志的令牌；文件控制还结合 ACL。不同后端和配置需要分别核对。
例子
工作根允许某限制 SID 写，而敏感子路径另有拒绝规则；实际访问要结合进程令牌和对象规则。
- SID Windows 身份标识
是什么
Windows 安全主体的标识；令牌与 ACL 利用它决定对象访问。
为什么需要
作为 Windows 身份与权限检查的稳定标识，用在令牌和 ACL 里。
在本实现中
Windows 对应分支创建带限制身份和权限标志的令牌；文件控制还结合 ACL。不同后端和配置需要分别核对。
例子
限制 SID 不表示一个普通用户名字符串；它参与对象访问检查，不能靠修改显示名称替代。
- URI 资源地址表示
是什么
用于描述路径或资源的位置。此处 PathUri 能保留执行环境的路径含义，到执行边界再转本机绝对路径。
为什么需要
保留资源位置及所属环境的含义，避免控制端过早把远程路径当成本机路径。
在本实现中
执行协调器确定要求后，平台转换器把逻辑权限落实到目标执行器。不同操作系统使用不同机制；远程任务要以目标执行器为准。
例子
远程工作目录可能不是 Mac 的 /Users 路径；PathUri 到目标执行边界才验证并转换为本地绝对路径。
- provenance 来源证明元数据
是什么
provenance 是随数据保存的来源证明：谁产生了它、是否是客户端内容、是否是框架配置等。它通常放在结构化元数据里，不是正文自己说“我是开发者指令”就能获得同等身份。若缺少这一层，保留或授权策略容易把不同来源的文本混为一类。
为什么需要
保存内容由谁产生和承担何种用途的证据，供接纳、保留或审核判断。
在本实现中
core 的活跃历史管理器接纳协议项、截断单项输出，再在请求前做结构与媒体能力检查。磁盘记录有独立的持久化路径。
例子
只有 role=developer 文本并不制造 client_authored 标记。Remote V2 的特定保留规则会同时检查来源。
- sidecar 伴随元数据
是什么
sidecar 在这里不是独立服务进程，而是正文旁边的一份结构化元数据。正文用于表达消息或结果，元数据保存来源、关联与额度等事实。两者一起在框架里传递，但元数据不一定作为可见文字发送给模型。
为什么需要
用伴随结构保存正文之外的来源、预算或状态，减少只靠文字标记推断安全语义。
在本实现中
core 的活跃历史管理器接纳协议项、截断单项输出，再在请求前做结构与媒体能力检查。磁盘记录有独立的持久化路径。
例子
ResponseItemEnvelope 的 metadata 可以保存来源和截断覆盖值；它未必以同样文字成为模型的输入正文。
- prefill 窗口初始输入
是什么
prefill 指当前窗口开始时模型已经处理的输入。在 BodyAfterPrefix 计量模式里，框架用它作为增长量的基线：总量减去基线，得到本窗口后来增加的量。即使正文增长尚未到额度，总输入仍不能超过模型可用完整窗口。
为什么需要
记录当前窗口开始时已接收的输入规模，作为某些正文增长额度的基线。
在本实现中
运行循环先看 TokenBudget，再按 provider 能力选择 Remote V2 或普通摘要。选定原文、压缩结果与重新注入的指令分别装配。
例子
BodyAfterPrefix 模式用活跃总量减 prefill 基线计算增长量；完整窗口上限仍独立检查。
- WorldState 当前环境与指令状态
是什么
WorldState 是把当前环境与指令分区组织的源码结构，包括模型、权限、工具、项目约定等。分区保存可比较的快照，并负责产生完整内容或变化片段。它不是整个磁盘或网络的实时镜像，也不会自动把所有文件内容装入上下文。
为什么需要
将当前模型指令、环境、权限和项目约定按分区组织，支持有基线的更新。
在本实现中
环境与指令按分区形成当前状态和快照。完整注入与差量更新还检查模型历史中是否真正保留了对应片段。
例子
权限设置变化时，相应分区产生更新；如果历史里丢失了旧片段，即使本地有快照，也可能需要重新注入。
- Responses Lite 增量请求协议模式
是什么
本版本模型能力中的一种协议模式，可以把工具定义和基本指令放入历史的前缀/更新项；是否使用由本步能力与设置决定。
为什么需要
支持把某些请求信息通过历史前缀或更新项表达的增量协议模式，具体使用还受本步设置约束。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
build_prompt 在增量工具模式中可以不重复填 tools/base_instructions 字段，因为对应信息已在历史中提供。
- copy-on-write 写时复制
是什么
写时复制先让多个读取者共享同一份内容。某条路径真的需要修改时，才给它独立的可写数据；这样既减少无意义深复制，又能让其他快照保持稳定。这里说明的是数据结构共享策略，不是文件系统写权限。
为什么需要
多个快照共享内容，发生写入时再获得可修改副本，兼顾稳定读取与复制成本。
在本实现中
core 的活跃历史管理器接纳协议项、截断单项输出，再在请求前做结构与媒体能力检查。磁盘记录有独立的持久化路径。
例子
一个请求规范化历史时，不应该把另一个请求正在使用的快照直接改坏；Arc 与 make_mut 等提供相应结构。
- RAG 检索增强生成
是什么
先从外部资料检索相关内容，再把结果加入生成请求。本课核对的活跃历史装配路径不等于一个统一的语义检索器。
为什么需要
先从资料库检索相关内容，再加入生成请求，用于让回答取得外部证据。
在本实现中
core 的活跃历史管理器接纳协议项、截断单项输出，再在请求前做结构与媒体能力检查。磁盘记录有独立的持久化路径。
例子
一个查询工具先搜出相关代码并将结果入历史，才属于检索增强的一种过程；for_prompt 的配对修复不等于语义检索。
- invariant 必须保持的约束
是什么
系统每次转换后都应成立的条件，例如工具请求与输出之间的对应关系。
为什么需要
在每次状态转换后必须仍成立的约束，保证下游按约定理解数据。
在本实现中
core 的活跃历史管理器接纳协议项、截断单项输出，再在请求前做结构与媒体能力检查。磁盘记录有独立的持久化路径。
例子
调用和结果应对齐，不支持的媒体不能留在对应请求里；规范化先恢复这些约束，而不是给消息排名。
- TokenBudget 窗口重置功能分支
是什么
本版本的功能开关。启用后 compaction 路径可以直接安装新窗口，跳过模型/服务端摘要；实际启用还受模型默认值和管理要求影响。
为什么需要
切换到显式窗口重建的实现路径。它是有效功能状态，不只是一个文本额度数字。
在本实现中
运行循环先看 TokenBudget，再按 provider 能力选择 Remote V2 或普通摘要。选定原文、压缩结果与重新注入的指令分别装配。
例子
启用时 compaction 直接安装新上下文，不先生成交接摘要；一些客户端来源项可按开关保留。
- Remote V2 远程压缩协议分支
是什么
本版本由 provider capability 选择的远程压缩流程。公开客户端可核对输入、输出校验和本地保留策略，但看不到服务端压缩内部。
为什么需要
使用提供方声明的远程压缩协议，客户端负责请求准备、结果校验和原文保留。
在本实现中
运行循环先看 TokenBudget，再按 provider 能力选择 Remote V2 或普通摘要。选定原文、压缩结果与重新注入的指令分别装配。
例子
客户端要求 completed 和恰好一个 Compaction 输出，再加入按白名单选中的原文；服务端内部算法不在这段代码里。
- Compaction 压缩结果协议项
是什么
ResponseItem 的一种结构化结果类型。Remote V2 将恰好一个该类型结果加入重建历史，不能直接当作普通可读摘要。
为什么需要
在协议中表示压缩结果或相关状态，和普通助手摘要文本是不同的形状。
在本实现中
运行循环先看 TokenBudget，再按 provider 能力选择 Remote V2 或普通摘要。选定原文、压缩结果与重新注入的指令分别装配。
例子
Remote V2 将一个该类型输出装入替换历史；不能仅凭它的类型推断哪些过程细节已被无损保存。
- 截断 按容量删减内容
是什么
确定性地缩减内容，例如保留字符串首尾、用标记替换工具输出。与由模型生成摘要是不同操作。
为什么需要
用确定性容量规则删减文本或输出，使单项或集合符合某阶段的预算。
在本实现中
core 的活跃历史管理器接纳协议项、截断单项输出，再在请求前做结构与媒体能力检查。磁盘记录有独立的持久化路径。
例子
保留首尾时，中间某条报错可能被删去。它不检查语义重要性；需要关键细节时应重新读取原文。
- 用户命名空间 Linux 用户身份视图
是什么
Linux 中隔离用户和组 ID 的机制，允许在受控视图里进行特定配置。不能与工具名称的命名空间混为一谈。
为什么需要
为 Linux 进程提供独立的用户/组身份映射，支撑受控环境中的某些资源操作。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
命名空间里的用户编号与宿主的权限身份不是简单同义关系；不能与工具名的 namespace 前缀混用。
- IPC 命名空间 独立 IPC 资源视图
是什么
Linux 中隔离部分进程间通信资源的机制；Unix socket 控制通道另有文件与网络访问保护。
为什么需要
隔离部分内核进程间通信资源，减少跨执行环境直接访问。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
IPC namespace 不能概括所有 Unix socket 保护；有权限的 daemon 控制 socket 还需路径与连接规则约束。
- PID 命名空间 独立进程编号视图
是什么
Linux 中隔离可见进程和进程编号的机制；是否使用新视图由启动模式决定。
为什么需要
让进程看见独立的进程编号和进程集合，隔离进程视图。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
是否继承 PID 视图由启动模式决定；看见独立编号不等于网络或文件也已按要求受限。
- 网络路由 网络流量路径规则
是什么
根据目标地址和网络配置决定流量的传输路径；本版本托管代理分支还建立隔离网络中的代理通道。
为什么需要
决定网络流量经过哪些接口和目的路径，配合隔离网络把访问限定到预期通道。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
代理允许访问一个目标，不表示进程可以沿宿主默认路由绕过代理；路由准备和 socket 规则需一起看。
- SBPL macOS 沙箱策略语言
是什么
Seatbelt 使用的策略表达语言，包含 allow、deny、路径和操作匹配规则。
为什么需要
用 allow、deny、操作和路径条件描述 macOS 进程访问策略。
在本实现中
macOS 分支合成基础、文件和网络策略，追加保护规则，再使用固定路径的 sandbox-exec 包装原命令。
例子
策略先 deny default，再补运行需要与明确权限。只有生成该文本还不够，必须由系统包装程序实施。
- RPC 远程过程调用协议
是什么
进程之间用协议请求另一端执行操作。这里即使在本机，也可能通过 Unix socket 访问应用服务。
为什么需要
让一个进程通过协议请求另一个进程执行操作，本机也可以使用这种调用形式。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
受限命令如果能连到更高权限的执行服务，就可能借服务能力扩大影响，所以控制通道需要独立保护。
- IPC 进程间通信
是什么
不同进程之间的数据与控制通信。Linux 的 IPC 命名空间和本地 socket 保护针对不同机制。
为什么需要
描述进程之间交换数据或控制信息的机制，不只一种传输方式。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
管道、共享内存和 Unix socket 的限制机制可能不同；“有 IPC 隔离”不能替代具体通道核对。
- PID 进程标识
是什么
操作系统为进程分配的标识。独立 PID 命名空间改变进程可见的标识视图。
为什么需要
识别操作系统中的具体进程，方便生命周期、信号和等待管理。
在本实现中
Linux 主路径先用 bubblewrap 形成文件系统与命名空间视图，再进入内层 helper 验证状态并安装进程限制。
例子
取消一个任务可能需要处理其子进程树，而不只给界面显示的一个编号发信号。
- capability 细分能力/权限
是什么
capability 有两个常见含义。Linux 内核里，它把传统超级用户权限拆成细分权限；接口设计里，它表示模型、provider 或 executor 声明自己支持某项能力。读代码时先看所属类型，否则会把权限和功能支持混读。
为什么需要
把某种允许能力显式表达出来，含义由层次决定：内核权限与接口能力声明不是同一数据。
在本实现中
执行协调器确定要求后，平台转换器把逻辑权限落实到目标执行器。不同操作系统使用不同机制；远程任务要以目标执行器为准。
例子
Linux 内层检查残余 capability；远程 executor 另声明能否安全保持 denied reads。这两种检查不可混读。
- TOCTOU 检查与使用之间的竞态
是什么
检查某路径后到实际使用它之前，路径可能被替换。沙箱路径和挂载实现必须考虑这种时间差。
为什么需要
处理检查资源到实际使用资源之间的变化窗口，防止过时路径判断造成绕过。
在本实现中
执行协调器确定要求后，平台转换器把逻辑权限落实到目标执行器。不同操作系统使用不同机制；远程任务要以目标执行器为准。
例子
先检查某路径是普通目录，之后它被换成符号链接，使用阶段看到的对象可能不同；需结合规范化、描述符与平台约束审查。
- ToolExposure 工具暴露方式
是什么
规定工具在初始列表、搜索和代码调用中如何出现的枚举；执行授权另外判断。
为什么需要
分开工具直接显示、延迟发现与嵌套代码调用，避免每次请求携带所有完整规格。
在本实现中
外部工具先取得目录与规格，再经过有效配置、预算和暴露策略，形成当前请求可用的表面。连接、认证和授权分别检查。
例子
Deferred 省略初始规格但允许搜索；DirectModelOnly 初始可见但不提供嵌套调用。
- ExecApprovalRequirement 执行授权要求
是什么
规则评估后产生的 Skip、NeedsApproval 或 Forbidden，交给执行协调器处理。
为什么需要
把复杂的规则决定整理为执行协调器可以处理的要求，保留是否允许绕过沙箱等信息。
在本实现中
命令先解析和评估规则，再把结果转成执行协调器可消费的授权要求。规则允许和解除平台限制并不是同一个条件。
例子
Skip 表示这层不要求普通提示，但 strict_auto_review 或有效权限仍可能影响后续执行。
- prefix rule 命令词序列前缀规则
是什么
按解析后的程序和参数词序列匹配，不能等同于对 shell 文本做字符串 startsWith。
为什么需要
限定一种可复用的程序/参数范围，避免把授权退化成任意 shell 内容的通行证。
在本实现中
命令先解析和评估规则，再把结果转成执行协调器可消费的授权要求。规则允许和解除平台限制并不是同一个条件。
例子
一段 git 查询被允许，不意味着 shell 中后接的另一个程序也被覆盖；解析后的各段都要评估。
- Retry-After 服务端重试时间建议
是什么
告诉客户端什么时候可以再次请求；时间建议不会自动增加重试次数。
为什么需要
让客户端遵守服务端指定的恢复时间，避免过早再发请求。
在本实现中
请求恢复分开处理可重试错误、等待截止时间、次数额度与传输回退；它不是工具副作用的通用重放器。
例子
收到未来 10 秒的 deadline，通知 UI 已耗 4 秒时，只等剩余时间；不会重新从通知结束开始等满 10 秒。
- WebSocket 持续双向传输连接
是什么
在一条持续连接上交换请求与响应事件，可以保留请求的增量基线。
为什么需要
保留持续传输和请求状态，支持事件到达与某些增量发送。
在本实现中
请求恢复分开处理可重试错误、等待截止时间、次数额度与传输回退；它不是工具副作用的通用重放器。
例子
当前请求必须延续前一个已知输入和输出基线；输入被压缩或改写后，不应盲目只追加新的一段。
- HTTPS 加密 HTTP 传输
是什么
通过 TLS 加密的 HTTP 请求，本版本支持从 WebSocket 回退到此传输。
为什么需要
以另一种传输路径继续模型请求，降低单一路径失败时的不可用性。
在本实现中
请求恢复分开处理可重试错误、等待截止时间、次数额度与传输回退；它不是工具副作用的通用重放器。
例子
符合条件的 WebSocket 回退会重置其会话状态，仍尊重服务端原 deadline；不是免除所有错误的办法。
- 退避 延长重试等待
是什么
在恢复失败后按规则延长等待，减少重复请求对故障系统的压力。
为什么需要
限制故障期间请求频率，给网络和服务恢复留出时间。
在本实现中
请求恢复分开处理可重试错误、等待截止时间、次数额度与传输回退；它不是工具副作用的通用重放器。
例子
特定 ConnectionFailed 分支从 5 秒倍增到 60 秒；这不是所有错误的统一固定时间表。
- 幂等性 重复操作保持相同效果
是什么
同一操作执行多次不会比一次多产生副作用的性质；重试网络请求不能自动赋予工具这种性质。
为什么需要
为重复执行提供明确的副作用边界，降低超时后“是否执行过”的不确定性。
在本实现中
请求恢复分开处理可重试错误、等待截止时间、次数额度与传输回退；它不是工具副作用的通用重放器。
例子
创建外部记录时可使用目标服务的幂等键或查询状态。模型请求重试本身没有证明所有工具都做了这件事。
- Session 核心会话对象
是什么
core 中持有历史、服务和运行状态的会话对象，与 UI 任务的映射需看集成协议。
为什么需要
让历史、配置与服务沿多回合工作持续存在。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
新用户输入进入同一 Session 时产生新回合；已经捕获的旧 StepContext 不应随着新设置被原地替换。
- TurnContext 回合状态对象
是什么
关联一次用户输入处理过程的状态，可能经历多次模型请求。
为什么需要
关联一回合的输入、取消和承诺过的运行要求，供各步骤沿用。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
一次回合里模型选择可能以受限方式更新；老的审核消费者仍可能读取回合初始状态，所以代码有兼容限制。
- StepContext 请求级执行快照
是什么
本次请求已捕获的设置、环境、连接与工具计划，后续工具仍使用这一版。
为什么需要
固定一轮请求的有效设置、工具和环境，使晚执行的调用不会绑定错误的新版本。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
请求展示的是工具目录 A，随后收到新配置 B；该请求已经产生的工具调用仍持有 A 所对应的 StepContext。
- ContextManager 活跃历史管理器
是什么
管理带元数据的历史项，维护模型请求使用的类型和结构约束。
为什么需要
将协议项和来源元数据变成受约束的活跃历史，并提供请求侧快照。
在本实现中
core 的活跃历史管理器接纳协议项、截断单项输出，再在请求前做结构与媒体能力检查。磁盘记录有独立的持久化路径。
例子
历史收到超限工具输出时截断副本；for_prompt 再修复配对并去掉不支持的媒体。
- Prompt 逻辑请求材料
是什么
组合 input、工具规格、基础指令等字段的结构，不只是一个文本字符串。
为什么需要
把逻辑请求的不同部分分开表达，使工具规格、基础指令和输入历史不必混成一段文本。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
常规模式分别填 input/tools/base_instructions；增量工具模式可能把后两者放在历史前缀里。
- ResponseItem 协议数据项
是什么
消息、调用、结果和压缩等数据形状的枚举。
为什么需要
区分不同数据的结构和处理规则，让调用、结果、消息与压缩项不会被当成相同文本。
在本实现中
core 的活跃历史管理器接纳协议项、截断单项输出，再在请求前做结构与媒体能力检查。磁盘记录有独立的持久化路径。
例子
ConfigurationUpdate 需要来源标记才入库；CompactionTrigger 只用于触发，不成为普通活跃历史项。
- ResponseEvent 流式过程事件
是什么
表示文字增量、项完成和响应完成等到达过程。
为什么需要
表达一个请求进行到了哪一步，而不是只表达最终内容。
在本实现中
核心把长期会话、一次回合和一次模型请求分开。请求准备时捕获有效状态，输出事件再推动工具和历史继续变化。
例子
OutputTextDelta 到达时可以显示文字；OutputItemDone 才确认一个项结束；Completed 是整次响应的完成事件。
- ToolRouter 本步工具分派对象
是什么
保存本步注册表和可见规格，解析工具身份并分派执行。
为什么需要
把本步可用工具的规格与执行身份关联起来，再将请求转成 ToolInvocation。
在本实现中
工具计划把可见规格和执行实现关联起来，按名称及命名空间分派。工具执行使用原请求的 StepContext，而不是随时读取一个不受约束的全局列表。
例子
两条同名但不同 namespace 的调用应定位到各自注册实现，而不是只按短名称猜测来源。
- ToolOrchestrator 受限执行协调器
是什么
把授权要求、环境权限、首次尝试和条件重试串起来。
为什么需要
协调授权、平台选择、首次执行与受条件约束的第二次尝试。
在本实现中
命令先解析和评估规则，再把结果转成执行协调器可消费的授权要求。规则允许和解除平台限制并不是同一个条件。
例子
SandboxErr::Denied 才进入特定升级检查；普通程序退出失败不等于可以扩大权限重试。
- PermissionProfile 逻辑权限描述
是什么
描述文件、网络和限制实施方式，到目标执行器转换成平台机制。
为什么需要
把文件、网络及限制方式从平台启动细节中抽离，供本机或远程环境转换。
在本实现中
执行协调器确定要求后，平台转换器把逻辑权限落实到目标执行器。不同操作系统使用不同机制；远程任务要以目标执行器为准。
例子
允许一个工作根写入并保留 .git 只读 carveout，最后可能被转换成 Seatbelt 条件或 Linux 挂载层叠。