跳转到内容

第 9 章 源码阅读、DAG、Worker 与 Handler

来自《AI Agent 学习》 · 原稿更新 2026-11-09 · 服务器只读阅读视图

9.1 请求路径与代码定位

先画请求路径再读实现:流程/DAG(在哪一步)→ 派工 Queue(交给谁)→ Worker 注册(哪个 Handler)→ Handler(真正干了什么)。

DAG、队列、Worker、Handler 定位图

我踩过的坑

  • 原来读 DAG 时,我把流程位置、派工关系和真实的业务实现混成了一件事。拆成四层之后,搜索结果更容易归类。

正确理解

  • 先认识工作区,再动代码。 读适用的 AGENTS.md、代码导航、Git 分支和未提交的更改,再确定入口和可修改的范围。扫描文件树和 Git 状态只是提供上下文,不是安全沙箱,更不会自动给你删除或改写 .git 的权限。旧稿提出的“固定四线程探针、秒级扫描”,没有在本项目实测过。

  • 浏览器和桌面自动化要选不同的可验证定位方式。 网页优先用语义的可访问性节点或 DOM 定位,并核对元素是否仍有效、点击后是否达到预期;桌面 App 可能只能用截图、OCR 或系统辅助功能定位,屏幕坐标和视觉识别都有误点风险。控制桌面前明确当前窗口焦点和任务边界,危险动作不能因为截图“看上去对”就自动放行。旧稿里“Web 一定精准、桌面闭环能接管任意程序”属于夸大。

  • 读旧框架源码笔记,先标“证据版本”。 参数默认值、工具名称、Hook 顺序或会话隔离模式,可能来自某次反编译、教程伪代码、旧 CLI 配置或作者推测。引用时至少区分源码可定位、文档说明、旧实测、我的方案、尚未核实,并注明日期或版本。能迁入主书的是可以独立验证的机制,不把“我以前看到 CC 这么做”改写成“现在所有 Agent 都这么做”。

  • 自动讲解流程,要核拓扑和运行时。 源码说明实现可能怎样做,实际生效的流程定义和配置说明本轮会走哪里,需求说明应该怎样做。把重复显示的“通用”节点误当第三条并行分支,或只按标题推父子关系,都会把讲解编错。拓扑能解析不等于业务讲对;换项目复用解析机制,也要重新适配知识来源和大纲。依据:流程讲解错误与通用化边界 · 数据首个错误边界。

9.2 判断函数所在的层

同一个名称可能出现在流程声明、注册路由、业务实现或测试里;搜索命中不等于找到了真实的执行位置。

我踩过的坑

  • 练习题(不是线上故障):“打招呼正常,查物流一直转圈。”我先逐一怀疑通用的请求格式和入口,没有优先比较两种请求多出来的步骤。
  • Codegraph 报“3 个调用方”,我差点按这个数字去改 3 个地方,见附录 A.9.1。

正确理解

  • 从入口出发,沿输入、过滤条件、状态读写和返回一路追下去。动态注册和反射可能让静态调用图漏边,要用 Trace 或实际调用验证。
  • 物流那题应先查物流任务特有的工具调用、等待和超时,再用 Trace 验证。普通聊天成功,只能降低共同路径出错的嫌疑,不能彻底排除由输入触发的路由或校验问题。
  • 找代码先查业务入口、函数级调用边、脚本和测试边,以及是不是故意分离了两套逻辑,不能按图谱上的数字直接决定改几个文件。

动手前检查

  • 我给自己提过的练习:用自己写的 PR,靠 Cmd+Click 看懂一条真实请求,而不是从仓库第一行开始读。沿“路由入口 → 请求 DTO → Endpoint → 依赖注入 → Service 编排 → 外部实现 → 返回 DTO → 测试”追,每层只讲清输入、职责和输出。
  • HTTP 字段或 422 先看 DTO 和 Endpoint;业务结果不对看 Service;模型超时或降级看路由和 Provider;只有日志和 Trace 异常时才看观测层。最后用测试断言核对自己的理解。
  • 这是练习路线,目前没有记录证明我已经独立走通。
来源

旧库 90-归档/需要学习的.md 第 690—692 行;这是 692 行旧稿,不是辅助材料中的同名长稿。

9.3 读懂的标准

关掉笔记,能讲出一次请求经过哪些层,再到真实仓库里指出入口、Agent Loop、工具注册、Handler、落库和结果返回。

正确理解

  • 读不通的地方才回去查旧资料。不要为了“系统学习”把同一个仓库从头重读一遍。

9.4 DAG 实验要复用调度语义,不能只复用函数(待学习)

图里的 id 标识节点实例,slug 匹配注册处理器;DAG JSON 描述组合,不是业务源码。连线也未必列出全部依赖,节点可能读共享 context。

原 Step 能单跑,只证明局部可测:同请求 TaskGroup 与分布式派发时的上下文快照不同,兄弟分支、聚合等待、回调和主动重投会改变可见结果。局部规则用局部评测;改拓扑则隔离复用真实引擎,锁定流程、代码与实际输入。生产引擎能否注入候选版本仍待确认。

来源与当时边界

原始记录 2026-10-29 · 原始记录 2026-10-29

9.5 可组合模块先声明阶段、依赖和副作用(待学习)

合法 slug 和连线只够保存图。模块契约还要说明输入输出类型、数据阶段、真实依赖、副作用、重试与降级;原始召回与过滤后结果不能混用。先从小流程验证旁路、启停和切换已有实现,再隔离跑完整上下游;不必把每个函数拆成服务。AI 自由改拓扑仍是待验证方案。

来源与当时边界

原始记录 2026-10-29