第一轮 · 第 10 站 · 架构总览 · 第一轮综合练习

全链路与 Harness:把十站讲成一个系统

现在不再增加一串陌生术语,而是重新从一次用户输入走到结果返回。你要能指出每层的责任、每次交接的数据、每种完成的边界,再把这张地图迁移到 GEODYNA。

本站必背:走路时复述这一段

不混粒度地复述六站主链与四站扩展
区分 Model、Agentic Loop 和 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 部分是设计与验收要求。

配套音频 · AI 合成语音

先听一遍,再对照源码

普通话讲解,保留关键代码语义、实际操作情境和 GEODYNA 对照。最后一章可用于脱稿复述;这份课不是通关证明。

全长 6:30 · 6 章MP3 · 3.0 MB普通话女声 · 稍慢语速
下载 MP3

点击开始;页面不会自动播放,也不会自动标记课程通关。

点击任一章,从对应位置开始。

    展开音频文字稿 · 听不清时对照看
    声音中的术语,对应代码里的哪个词?

    AI 合成语音;收听位置仅保存在当前浏览器,不跨设备同步。代码以固定快照为准。可下载后用手机播放器离线收听。

    先定位:这一站到底在讲哪一层?

    第 1~6 站走完整主链:输入提交 → App Server 受理 → Core 路由 → 执行包装 → 模型工具循环 → 事件通知返回。第 7~9 站则打开这条链内部的工具、安全和上下文分支。第 10 站重新把它们组合起来。

    这是一次架构视角的归纳。Model 提供推理与生成能力;Agentic Loop 是观察结果、决定下一步、调用工具并继续的循环机制;本课所说 Harness,是让模型在真实任务中运行的一组支撑与约束,包括上下文、工具、权限、生命周期和可观察过程等。它们不是三个可以互换的函数名。

    1. 1客户端收集并提交输入
    2. 2App Server 校验与转换
    3. 3Core 收件与状态路由
    4. 4RegularTask 包装,run_turn 循环
    5. 5工具、权限与上下文共同支撑
    6. 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,不执行任何真实操作。

    先预测会走哪条分支,再点击按钮查看。

    最容易说错的边界

    常见说法准确表述
    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 站,用一份具体的文字+附件输入追数据变化;原定第二轮与第四轮安排不因新增材料而跳过。