全链路与 Harness:把十站讲成一个系统
现在不再增加一串陌生术语,而是重新从一次用户输入走到结果返回。你要能指出每层的责任、每次交接的数据、每种完成的边界,再把这张地图迁移到 GEODYNA。
第一轮收束站:Harness 是对运行支撑系统的架构归纳,不是声称仓库存在一个包办全部功能的同名类。第四轮仍将重新深入运行机制。 讲义已备好 ≠ 已掌握;本页不会改动你的通关状态。
本站必背 · 走路复习
第 10 站:把模型、循环和运行系统分清
先理解,再背这一个完整段落。日常复述约 1–2 分钟;点标题可遮住正文,按下面的顺序提示试着复述。
核心背诵段 · 点击展开或遮住
第十站把整条链重新连起来:客户端整理输入,App Server 校验和转换,Core 决定新开还是追加,RegularTask 包装执行,run_turn 协调模型与工具循环;过程事件经 App Server 转成通知,再由客户端显示。模型负责推理与生成,Agentic Loop 负责根据结果继续行动或停止;本课所说的 Harness,是围绕模型组织上下文、工具、权限、生命周期和可观察过程的运行支撑系统,Loop 只是其中一部分。做 GEODYNA 智能体,不只是接模型和聊天框,还要接正式命令、保留安全与恢复边界,并用真实软件状态验收。记住:流畅回答不等于任务成功,可靠智能体必须有受控行动和可核实的结果。
复述顺序:输入到执行 → 事件回界面 → 区分 Model/Loop/Harness → 领域接入 → 证据验收。
背诵用于抓牢主线。理解自测:为什么仅接上模型和聊天框,还不足以交付一个可靠的 GEODYNA 智能体? 仍需通过源码阅读和练习验证掌握,不会因背诵自动标记通关。
核对依据:路由进入普通任务 · 执行包装与循环 · 外层收尾事件。Harness 是本课的架构归纳,不是上述某个函数的别名;GEODYNA 部分是设计与验收要求。
先听一遍,再对照源码
普通话讲解,保留关键代码语义、实际操作情境和 GEODYNA 对照。最后一章可用于脱稿复述;这份课不是通关证明。
点击开始;页面不会自动播放,也不会自动标记课程通关。
点击任一章,从对应位置开始。
展开音频文字稿 · 听不清时对照看
声音中的术语,对应代码里的哪个词?
AI 合成语音;收听位置仅保存在当前浏览器,不跨设备同步。代码以固定快照为准。可下载后用手机播放器离线收听。
先定位:这一站到底在讲哪一层?
第 1~6 站走完整主链:输入提交 → App Server 受理 → Core 路由 → 执行包装 → 模型工具循环 → 事件通知返回。第 7~9 站则打开这条链内部的工具、安全和上下文分支。第 10 站重新把它们组合起来。
这是一次架构视角的归纳。Model 提供推理与生成能力;Agentic Loop 是观察结果、决定下一步、调用工具并继续的循环机制;本课所说 Harness,是让模型在真实任务中运行的一组支撑与约束,包括上下文、工具、权限、生命周期和可观察过程等。它们不是三个可以互换的函数名。
- 1客户端收集并提交输入
- 2App Server 校验与转换
- 3Core 收件与状态路由
- 4RegularTask 包装,run_turn 循环
- 5工具、权限与上下文共同支撑
- 6事件转换、界面展示与业务验收
| 粒度 | 负责什么 | 不要误认为 |
|---|---|---|
| 模型 Model | 根据收到的材料推理、生成文字与调用建议 | 不是实际工程状态的数据库 |
| 循环 Agentic Loop | 决定何时再次请求模型、处理工具和停止 | 不是一个长期 Thread |
| Harness(课程架构定义) | 组织输入、工具、安全、上下文、生命周期与观测等运行支撑 | 不是仅靠一个巨大提示词,也不等于某个同名元数据结构 |
| 产品与领域系统 | 定义用户目标、真实动作、验收标准和恢复机制 | 不是模型给出一段流畅回答就验收完成 |
从你的“补测试”重新开始
场景:你发送“给这段逻辑补测试,并运行验证”。客户端先组织输入;在本课所学的 TUI 路径中,ChatWidget 经内部提交机制交给 TUI 应用协调层,再调用 App Server。桌面客户端并不因此被断言使用同一套 TUI 类。
App Server 的 turn_start_inner 载入目标 Thread、检查与整理参数、映射输入并交给 Core,返回受理状态。Core 的公开提交门面和 Session 收件/路由逻辑要分开说:对外承诺可以启动或追加,不代表全部状态判断写在门面函数体。
| 站点 | 你应说出的交接 | 可以拿什么证据解释 |
|---|---|---|
| 1 输入提交 | 可见内容 → 结构化输入 → TUI 内部交接 | 输入不是只有 text;提交不等于完成。 |
| 2 App Server | 协议参数 → Core 输入与提交回执 | InProgress 是非终态;别拿回执当最终结果。 |
| 3 Core 路由 | 提交门面 → 收件处理 → Started / Steered / NotSubmitted | 启动、追加、未提交由实际路径与活动状态决定。 |
| 4 执行包装 | RegularTask::run → run_turn → 外层收尾 | 开始事件、预热与外层重入不等于真正的模型工具循环。 |
| 5 模型工具循环 | 历史 → 模型请求 → 工具/消息 → 是否继续 | 一个 Turn 可以有多次模型请求。 |
| 6 返回界面 | Core Event → ServerNotification → TUI 消费 | delta、Item 完成和 Turn 完成是不同粒度。 |
| 7 工具 | 定义 → 调用单 → invocation → 实现 → 结果 | 模型提出调用不等于已经发生副作用。 |
| 8 安全 | 授权/审批 → 执行限制 → 领域校验 | 不询问不等于无限权限;取消不等于撤销。 |
| 9 上下文 | 运行历史 → 规范化 → Prompt → 必要的压缩 | 模型工作视图不等于界面全部历史。 |
| 10 综合 | 把边界落实成产品设计和验收证据 | 用真实结果证明完成,而不是只复述术语。 |
重新读三处接缝,不把系统说成一个函数
1. 实际路由中的启动任务交接
真实源码 · codex-rs/core/src/session/turn_input.rs:314–325
代码较长时可左右滑动;下方按语句和术语拆解。
let mut task_input = merge_additional_context_input(session, additional_context).await;
if has_explicit_input {
task_input.push(pending_turn_input(session, input).await);
}
session
.spawn_task(turn_context, task_input, RegularTask::new())
.await;
Ok(TurnInputSubmission::Started {
turn_id: submission_id,
})
}
Err(reason) => Ok(TurnInputSubmission::NotSubmitted { reason }),| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| task_input = merge_additional_context_input(...) | 整理交给执行任务的输入,而不是直接调用模型。 |
| if has_explicit_input ...push(...) | 在对应条件下补进显式输入;这是该路由位置的具体行为。 |
| spawn_task(turn_context, task_input, RegularTask::new()) | 把准备好的上下文、输入和普通任务实现交给任务启动路径。 |
| Started { turn_id: submission_id } | 返回本轮已启动的提交结果,不是等待模型全部做完。 |
| Err(reason) → NotSubmitted | 邻近分支说明有未提交结果;不能把整个 API 契约简化成永远新建 Turn。 |
边界提醒:这是已经进入 Session 路由分支后的片段,不是把 Started/Steered 判断强加给上游公开门面函数。
2. RegularTask 与 run_turn 的真实接缝
真实源码 · codex-rs/core/src/tasks/regular.rs:75–98
代码较长时可左右滑动;下方按语句和术语拆解。
let mut next_input = input;
let mut prewarmed_client_session = prewarmed_client_session;
let mut mcp_startup_requirements = McpStartupRequirements::default();
loop {
let last_agent_message = run_turn(
Arc::clone(&sess),
Arc::clone(&ctx),
next_input,
&mut mcp_startup_requirements,
prewarmed_client_session.take(),
cancellation_token.child_token(),
)
.instrument(run_turn_span.clone())
.await?;
// Terminal errors are already reported. Let task completion preserve pending
// input instead of restarting the failed turn for that same input.
if ctx.terminal_error.lock().await.is_some() {
return Ok(last_agent_message);
}
if !sess.input_queue.has_pending_input(&sess.active_turn).await {
return Ok(last_agent_message);
}
next_input = Vec::new();
}| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| next_input / prewarmed_client_session | 保留可交给下游的输入与可能复用的模型连接。 |
| loop { run_turn(...).await?; ... } | 这是执行包装层的重入循环;模型—工具循环在 run_turn 内部,不能混为一谈。 |
| prewarmed_client_session.take() | 只把已预热连接从 Option 中取走一次,原处变为 None。 |
| terminal_error 检查 | 已发生终止错误就返回,不用同一批待处理输入反复重启失败工作。 |
| 没有 pending input 就返回 | 执行结束边界没有新输入时,让外层统一收尾。 |
| next_input = Vec::new() | 有待处理队列时,避免重复显式首次输入;空形参不等于 Session 队列没内容。 |
3. 最后统一产生生命周期事件
真实源码 · codex-rs/core/src/tasks/mod.rs:808–839
代码较长时可左右滑动;下方按语句和术语拆解。
let event = if let Some(reason) = abort_reason {
if reason == TurnAbortReason::Interrupted {
run_turn_interrupt_hooks(self, &turn_context, &turn_state).await;
}
self.emit_turn_abort_lifecycle(reason.clone(), turn_context.extension_data.as_ref())
.await;
EventMsg::TurnAborted(TurnAbortedEvent {
turn_id: Some(turn_context.sub_id.clone()),
reason,
started_at,
completed_at,
duration_ms,
})
} else {
let time_to_first_token_ms = turn_context
.turn_timing_state
.time_to_first_token_ms()
.await;
let error = turn_context.terminal_error.lock().await.clone();
self.emit_turn_stop_lifecycle(turn_context.extension_data.as_ref())
.await;
EventMsg::TurnComplete(TurnCompleteEvent {
turn_id: turn_context.sub_id.clone(),
last_agent_message,
error,
started_at,
completed_at,
duration_ms,
time_to_first_token_ms,
})
};
self.send_event(turn_context.as_ref(), event).await;| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| if let Some(reason) = abort_reason | 有中止原因,构造相应中止事件;不是假装普通成功。 |
| EventMsg::TurnAborted / TurnComplete | 两条 Core 生命周期结果路径;之后还需要 App Server 做协议适配。 |
| terminal_error.lock().await.clone() | 正常收口路径也携带终止错误信息,不能从事件名称直接判定业务成功。 |
| last_agent_message / started_at / duration_ms | 带出结果与时序证据;它们不是全都塞在一段最终文字里。 |
| self.send_event(...).await | 真正把本轮事件发入返回链,后续通知和 UI 消费仍有各自职责。 |
用组件地图理解 Harness,不神化一个名词
这不是仓库里一个统一类的字段清单,而是根据已读源码归纳的架构视图。Loop 是其中的运行机制;Harness 还需要让输入可管理、工具可控、结果可追踪、失败可收口。
你可以把同一个模型接进不同 Harness,得到不同工具能力、权限边界和产品体验;也可以在保持运行边界的前提下更换模型。因此评估智能体产品,不能只比较模型名字或最终回答措辞。
| 支撑能力 | 本轮见过的实现位置 | 移植到 GEODYNA 的问题 |
|---|---|---|
| 请求与生命周期 | App Server、Session 路由、任务包装和收尾 | 对话与工作轮次怎样识别?何时受理、结束? |
| 上下文供给 | ContextManager、build_prompt | 模型是否看到相关且新鲜的工程事实? |
| 实际能力 | ToolCallRuntime、Router、Registry、工具实现 | 哪些正式命令可以暴露,参数与结果怎样约束? |
| 安全边界 | 审批路径、沙箱协调、领域命令 | 谁能批准什么?拒绝、过期和取消怎样处理? |
| 可观察过程 | Core Event、ServerNotification、TUI 消费 | 用户和开发者能否知道卡在哪一步、证据是什么? |
| 质量验证(产品要求) | 不能只由某个 Loop 函数承担 | 任务成功率、风险行为、耗时和成本如何测试? |
一个可执行的产品练习,而不是立刻重写软件
本课练习先选择“只读检查当前算例为何不能运行”,它能覆盖模型、工具、上下文、事件和失败解释,又不需要先开放危险写入。这是缩小教学练习,不是改动并行产品线的范围或排期。
先定义用户目标和验收,再反推最少组件:可信工程摘要 → 校验工具 → 结果解释 → 来源与状态展示。有证据说明必须改动时,也先给出建议;实施修改要有单独明确授权与正式命令边界。
具体输入,逐层拆开
产品契约草案,不是现有 GEODYNA 接口或可直接运行代码。
用户目标:知道当前算例不能运行的原因
输入:目标工程身份、当前算例身份、用户问题
允许能力:读取当前状态、读取正式校验结果
禁止能力:本练习不修改工程,不启动求解
成功:指出有证据支持的缺项,附对象与来源
信息不足:明确缺什么,再按允许范围查询
失败:报告发生阶段,不编造运行结果
停止:结束后续读取,保留已得到的事实你能把这份契约写清,再配正常、信息不足、权限拒绝、取消和工具失败的评测样例,就比“做一个聊天机器人”更接近可交付的专业产品能力。
把同一个场景换一种条件
同一个用户目标,分别观察受理、执行和业务完成。
仅为本地教学演示,不调用模型或 GEODYNA,不执行任何真实操作。
先预测会走哪条分支,再点击按钮查看。
结果有事实支撑的闭环
- 客户端提交,App Server 受理。
- Core 启动执行,模型请求只读工具。
- 工具返回当前校验问题,模型据证据解释。
- 执行收尾,通知终态;产品验收确认解释有来源且无写入。
运行层 Completed 与业务验收一起,才能支持本练习成功。
受理不是成功保证
- turn/start 已经返回 InProgress。
- 工具读取失败,运行时得到真实错误。
- 根据错误类型停止或安全补救,向用户说明阶段。
- 最终不把“已受理”包装成“已经检查成功”。
区分提交层、工具层、Turn 层和业务层。
同一轮可能吸收新内容
- 已有活动 Turn。
- 用户追加材料经提交路径处理。
- 运行循环在允许的边界获取新内容,继续调用模型。
- 仍要通过本轮最终收口与结果验证。
不能简单按屏幕消息条数计算 Turn 数。
Harness 与领域边界必须拦住
- 本练习只授权读取与解释。
- 模型建议调用写工具。
- 执行边界拒绝越界能力或要求适当的新授权流程。
- 保留只读结果,明确说明没有实施修改。
强推理能力不等于自动获得更大行动权限。
最容易说错的边界
| 常见说法 | 准确表述 |
|---|---|
| Harness 就是 run_turn 的另一个名字 | 本课 Harness 是运行支撑系统的架构归纳,Loop 只是其中一部分。 |
| 做智能体就是接模型再画聊天框 | 还要接真实能力、管理状态、安全、失败与证据。 |
| 能说出函数名就能完成产品验收 | 需要可运行场景和测试证据;术语是沟通工具,不是结果。 |
| 今天备好十站,就说明第一轮已通关 | 材料准备与实际掌握分开;仍以复述、场景判断和练习为准。 |
迁移到你的 GEODYNA 智能体
以下是设计练习,不代表并行产品线已经实现或通过验收;本次只制作课程,不修改 GEODAMNEW。
这一站的产出是一页“只读算例检查助手”设计:用户问题、允许和禁止动作、输入来源、工具契约、事件序列、失败分支、验收样例。不要在这一页上同时扩展到所有工程功能。
腾讯岗位讨论中,可以用这份作品说明你如何从用户任务出发,定义技术边界、可控能力和质量证据。具体岗位要求以后仍需核对当期招聘信息;学习不能保证录用。
| 你要设计的点 | 可验证的证据 |
|---|---|
| 架构图 | 每个箭头都注明交接的数据或事件,不用一个“AI”方框掩盖所有职责。 |
| 评测样例 | 至少覆盖正常、信息不足、工具失败、权限拒绝和取消。 |
| 质量指标 | 先定义正确且有证据的任务完成,再分别测工具成功率、耗时与模型调用成本。 |
| 风险边界 | 证明只读场景没有工程写入;写入扩展另设授权与事务验收。 |
产品经理练习:完成这一页设计,并用 3 分钟脱稿说明一条成功路径和一条失败路径;讲义提供参考,不自动替你判定通关。
先答小测,再看解析
每题即时反馈,可反复尝试;答对这些题也不会替代你的源码复述。
1. Core 公开提交门面与实际状态路由是否总是同一个函数体?
2. RegularTask 外层 loop 与 run_turn 内部循环分别是什么?
3. Harness 最准确的本课理解是什么?
4. 只读任务里模型提出写入,应如何处理?
5. 哪个最能证明“检查为何不能运行”任务成功?
6. 下一轮应该怎么开始?
最后一句话交作业
请用 3 分钟解释:一次输入怎样经过 TUI、App Server、Core 循环和工具,再把结果返回?其中哪些属于 Loop,哪些是 Harness 的其他支撑?最后给出 GEODYNA 场景的成功标准。
展开参考答案(先自己说一遍)
客户端组织并提交输入;App Server 校验、映射和受理;Core 通过提交与路由进入普通执行任务;RegularTask 包装执行,run_turn 用历史请求模型并处理工具反馈和继续条件;权限、上下文与工具运行时共同约束过程;外层收尾产生事件,经 App Server 转成通知,客户端分别更新项目和终态。
Loop 是内部持续观察、行动与继续的机制;Harness 还组织上下文供给、工具执行、权限、生命周期与可观察过程。GEODYNA 的只读检查要基于当前软件证据解释缺项、提供来源、遵守不写入约束,并明确处理信息不足和失败。
下一轮再回来时:第一轮实际通关后,重新打开第 1 站,用一份具体的文字+附件输入追数据变化;原定第二轮与第四轮安排不因新增材料而跳过。