Ferret 调试器架构深度解析：基于保留式 VM 执行的源码级调试编排层

• 网页爬虫
• 后端
• 开发工具

Ferret 是面向结构化抽取工作流的声明式数据自动化语言与 Go 运行时。本文以维护者架构文档 debugger.md 为主线，结合pkg/debugger、pkg/vm、pkg/engine等核心源码，全面剖析其调试器如何在不改变正常执行语义、且在调试关闭时几乎零开销的前提下，实现断点、单步、求值与实况断点替换等源码级调试能力。读完本文，你将掌握 Ferret 调试器的分层边界、会话状态机、并发模型与底层实现原理。

一、总体设计：源码级编排层与保留式 VM 执行

Ferret 调试器的定位是"源码级编排层"（source-level orchestration layer），它叠加在一套保留状态的 VM 执行（retained VM execution）之上。两个硬性约束贯穿整个设计：

• 保持正常执行语义：调试器的存在不能改变普通 VM 执行的语义；
• 调试关闭时开销足够低：正常执行路径上的调试器旁路必须"显式、可度量、可立即绕过"。

也就是说，调试能力不是以修改字节码、插入探针或改变调度循环为代价实现的，而是把"什么时候停、停在哪个源码位置、如何呈现暂停状态"这些源码级策略全部上收到调试器层，VM 只暴露最小化的调试执行面。

从整体执行管线看（见 overview.md 的 Execution pipeline），源文件依次经过 ANTLR 词法/语法解析、编译器前端与诊断、lowering 与优化、生成bytecode.Program，最后由 VM 执行。调试器正是插入在bytecode.Program与 VM 执行之间的能力层。

二、编译与调试元数据：CompileDebug 与 OptimizationNone

调试会话的前提是程序携带调试信息。Engine.CompileDebug负责产出这种程序：

// pkg/engine/engine.go // CompileDebug compiles a reusable plan with debug metadata and no optimization. func (e *Engine) CompileDebug(ctx context.Context, src source.Source, opts ...PlanOption) (*Plan, error) { return e.compile(ctx, src, true, opts) }

与普通Compile相比，CompileDebug有两个关键差异：

1. 编译出的程序包含调试元数据：编译器记录源码区间（source spans）、逻辑调试点（logical debug points）、函数身份（function identities）、程序计数器（program counters）以及当前可见的绑定（visible bindings），统一存放在bytecode.Program.Metadata中。
2. 使用OptimizationNone编译：源可见的执行顺序不会被优化器的 pass 重排。引擎层有专门测试 engine_optimization_test.go（TestCompileDebugUsesOptimizationNone）与 plan_options_test.go（TestCompileDebugRejectsOptimizationBeforeHooks）验证这一点——调试编译禁止在 before-run 钩子之前指定优化级别。

一个值得注意的设计原则：这些调试记录（source spans、debug points、函数身份、PC、可见绑定）的所有权在共享的source与bytecode包中，调试器代码是消费方，而不是重建编译语义。调试器拿到的debugpoint.Index正是基于编译器产出的DebugPoint列表构建的（见 session.go）。

调试会话的创建前提

Plan.NewDebugSession要求程序必须包含调试点：

// pkg/engine/plan_session.go func (p *Plan) NewDebugSession(ctx context.Context, setters ...SessionOption) (*debugger.Session, error) {

引擎测试 debug_session_test.go 的TestPlanNewDebugSessionRequiresDebugCompilation明确验证：通过普通编译（无调试信息）或加载（Load）得到的程序无法创建调试会话。因此正确的使用路径永远是：

Engine.CompileDebug → Plan → Plan.NewDebugSession → Session.Start

三、分层边界：vm / debugger / engine 各司其职

调试器架构把职责切分在三个包中，这是整个设计的骨架：

从 VM 侧看，调试执行面的核心契约定义在 pkg/vm/debug.go：

• DebugExecution接口：Start、按模式Resume、RequestPause、Status、Locals、Params、Frames、Close；
• DebugResumeMode：DebugResumeContinue/DebugResumeStepIn/DebugResumeStepOver/DebugResumeStepOut四种模式；
• DebugStopReason：DebugStopEntry/DebugStopBreakpoint/DebugStopStep/DebugStopPause/DebugStopRuntimeError/DebugStopCompleted/DebugStopTerminated；
• DebugExecutionStatus：New / Paused / Running / Completed / Terminated / Closed 六态；
• DebugBreakpointPredicate func(pc int) bool：VM 在源码点同步调用的断点谓词，必须廉价、不得窥探或重入执行，返回 true 即提交一次断点停止，nil 谓词禁用断点检查。

根级ferret（仓库根目录下的公共 API，如 debug_types.go）只是把受支持的调试器类型通过精选的嵌入 API（curated embedding API）做别名导出；源码级调试策略始终留在pkg/debugger，不向上层泄漏。

四、内部会话组装：Session 由三个私有组件构成

公开的Session组合了pkg/debugger中三个私有具体组件（见 session.go 的结构体定义与 types.go 的Config）：

type Session struct { breakpoints breakpointSet inspector inspector pointIndex debugpoint.Index source source.Source lifecycle sessionLifecycle }

sessionLifecycle：生命周期与并发锁

拥有保留式执行、嵌入服务、命令锁与生命周期锁、取消上下文、终止状态、钩子配对、输出物化与一次性清理。会话构造时校验四个必需依赖（Execution、Values、Services、Source），并检查调试点索引的合法性（session.go）。

breakpointSet：断点所有权

拥有绑定、身份（identity）、不可变快照、写者门（writer gate）、VM 谓词与捕获的命中 ID。它借用生命周期的准入与发布守卫，确保发布与原生终止保持有序。

inspector：检视所有权

借用执行与值访问，拥有帧、局部变量、表达式求值、有界呈现与可展开引用。所有检视与引用失效操作都运行在生命周期命令锁之下。

Session：事件投影与状态协调

Session自身保留源码事件投影，并协调这三个所有者之间的转换：

• 运行准备成功之后才使检视引用失效并进入 VM（resume中先prepareResume、再resetValueReferences/resetHit，见 session.go）；
• Close 先拒绝新工作并取消执行，然后获取命令锁；Session 在生命周期清理释放执行与嵌入资源之前清除检视引用与捕获的命中。

设计上还有几条铁律：源码元数据属于 Session；断点与检视通过指针借用同一份 source 与 debug-point 索引，索引用后从不复制；各组件不互相保留 Session、也不关闭对方的资源；上下文校验只在 Session 门面与生命周期准入守卫中发生；inspector 没有独立的命令锁或取消状态。

五、会话状态与并发模型

一个调试会话在多次命令之间保留一次执行。状态机如下：

优先级规则：断点与暂停请求优先于单步（包括更深调用中的中断）；三种单步操作在步进条件达成时统一上报共享的ReasonStep。

并发与取消语义

• 执行命令与检视命令被命令锁串行化；而Pause、断点变更、断点列表可在命令运行期间并发进行。
• 除Close外的所有命令都要求非 nil context。检视类命令（含Evaluate/EvaluateFrame）在等待命令互斥锁之前与获取之后都要检查取消，且取消不会打断锁等待、也不会引入新的检视锁。
• 被取消的Pause会在请求停止之前直接返回。
• 增量断点增删使用请求 context 做写者准入、构造与发布检查：发布前取消阻止变更与 ID 消耗；发布后取消保留成功结果且绝不取消调试对象（debuggee）。
• 恢复调用默认使用保留执行上下文；若调用方额外提供 context，则两个生命周期同时被观察。
• 启动或恢复会使上一次暂停期创建的可展开值引用失效。

断点同时保留请求位置与编译器产出的绑定点。绑定模式区分"精确解析"与"支持的 next-executable 策略"；文档明确要求：不得在程序调试元数据之外合成可执行位置。具体实现中（breakpoint_set.go）：

• 行号必须为正、列号不得为负；
• 绑定模式必须在BreakpointBindNextExecutableInSource与BreakpointBindNextExecutableInFunction范围内，未知模式直接拒绝（unknown breakpoint binding mode）；
• 其他源码名的断点只保留未绑定记录，不影响启动源断点。

六、实况断点替换：不停止、不重建的执行期更新

ReplaceBreakpoints(ctx, sourceName, requests)是这套调试器最精巧的部分：在运行前、暂停中、甚至运行中替换某个源的完整断点请求集，无需暂停或重建 VM。

替换语义

• 空请求集清除该源的所有断点；空源名选择"启动源"；
• 其他源名的未绑定记录被保留，不影响启动源断点；
• 非法位置或非法绑定模式使整个操作失败；合法但未解析的位置按请求顺序返回普通 unbound 结果。

无锁快照与原子发布

断点集合持有请求/解析记录的不可变快照和一个PC → 命中 ID 索引。可取消的写者门（write chan struct{}，容量 1）独立于commandMu串行化变更。流程如下（breakpoint_set.go）：

1. 取得写者门（lockBreakpoints），构造期始终持有门；
2. 基于旧快照计算新快照：未变化的请求保留 ID，重复请求按升序匹配既有 ID，移除的 ID 永不复用（nextID单调递增，耗尽即报错）；
3. 解析与构造完成后，一次原子指针发布（atomic.Pointer[breakpointSnapshot]+data.Store）——任何时刻都不会看到部分替换的集合；
4. 发布阶段短暂进入lifecycleMu临界区，与原生完成、终止、关闭排序；发布先成功则替换成功，终止先提交则替换被拒；
5. 发布前观察到的取消中止操作；发布后的取消不撤销成功。

锁顺序严格固定：命令锁或写者门 → 生命周期锁，绝不允许反向。

同步谓词取代固定 PC 映射

VM 恢复时接收的是同步断点谓词而不是固定 PC 映射。在既有调试源码点处，谓词加载当前快照，判定命中时捕获匹配的 ID；事件转换时复制这些 ID——因此移除断点不会使已判定的停止失效或触发自动恢复，新增断点只影响后续检查、绝不作用于已执行过的指令。命中 ID 的读取由命令锁保护（hasBreakpoint→hitBreakpointIDs，见 breakpoint_set.go）。

文档特别指出历史设计的三个缺陷，正是被这一整套机制共同解决的：

1. 变更/列表与命令锁共享、且锁在整个恢复期间持有；
2. VM 引用"恢复时构建"的 PC 映射；
3. 命中 ID 从最新可变映射重建。

仅靠"解锁命令"无法安全发布实况变更或保留命中 ID——这三项依赖必须一起替换。实况断点的并发与取消行为有专门的测试覆盖，见 live_breakpoints_test.go 与 breakpoint_replacement_test.go。

七、值检视与表达式求值

运行时值的检视契约

运行时值可以通过运行时自有的契约（runtime-owned contracts）选择接入调试器检视。VM 暴露通用检视视图（vm.DebugValueAccess），pkg/debugger负责有界格式化，并将其翻译为调试器值（Value）与子引用（ValueReference）。设计红线：调试器代码不应为运行时自有的语义积累具体类型 switch——新运行时类型只需实现契约即可获得检视能力，无需改动调试器。

保守求值器

求值是刻意保守且无副作用的（见 session.go 的文档注释）：

• 读取暂停帧绑定，支持文档化的表达式子集：字面量、局部变量、参数、受支持的成员读取、标量算术/比较、布尔逻辑与条件表达式；
• 明确拒绝：调用、变更（mutation）、查询、async/event 行为以及完整集合执行——这些都不属于调试求值器范畴。

格式化界限

格式化界限约束深度、条目数与渲染字节数，默认值见 types.go：

func DefaultFormatOptions() FormatOptions { return FormatOptions{MaxDepth: 3, MaxItems: 8, MaxBytes: 1024} }

若构造时传入的MaxDepth/MaxItems/MaxBytes任一非正，则回退到默认值。展开必须是确定性的，且不得修改活着的暂停值。对应的基准测试见 format_bench_test.go。

八、完成与清理：生命周期服务的复用

调试会话服务复用普通会话的完整钩子行为：before-run、after-run、编码、文件系统、网络、日志与 close 钩子。完成时通过嵌入层物化输出（Materialize）。

关键语义（对应 types.go 的SessionServices接口）：

• 嵌入服务持有自己的宿主资源管理器：借用 Engine 服务、持有（若配置了）会话文件系统覆盖；服务关闭时执行 close 钩子、关闭自有的宿主资源、释放 limiter 许可。保留式 VM 执行仍由调试器会话所有与关闭，不由该管理器负责。
• 原生调试服务通过构造器绑定具体的 limiter 与资源管理器并保持私有；绝不接收普通session.Execution、池化 VM 或 VM-return 回调。内部获取所有者（acquisition owner）在构造成功前保留回滚能力；调试器串行化服务使用并只调用一次服务关闭。

终止状态的精细规则

• Start 中止钩子结算：当所有 before-run 钩子成功但上下文校验阻止进入 VM 时，Start立即结算该次尝试的 after-run 钩子；会话保持 new 状态，接受之后合法的Start；Close不重复已中止尝试的钩子，也不消耗后续运行的钩子义务。
• 直接执行错误：保留执行从Start/Resume直接返回错误且状态为终止时，生命周期提交终止态并立即用原始执行错误结算AfterRun，钩子失败与该错误 join；之后的Close只释放资源，不重复钩子、也不以取消替换运行失败。
• DebugStopRuntimeError：仍然在停止处结算 after-run 钩子，保留暂停、可检视状态，但不提交终止状态——普通运行时失败保持可检视，直到下一次恢复或关闭释放其保留状态。

Close 的收敛行为

Close请求终止 → 等待活动命令离开保留执行 → 使值引用失效 → 需要时执行 after-run 处理 → 关闭保留 VM 状态 → 释放嵌入资源。清理错误被聚合而不跳过后续清理。

• 终止事件同时携带执行原因与保留态清理失败信息；调试执行会缓存清理失败，供重复与并发Close复用；
• 取消本身不缓存为清理失败，因此干净取消不会让后续Close报错；
• 若Close在 VM 返回暂停或运行时错误停止时赢得竞争，会话会先排空该状态再上报终止，并保留并发失败。

九、测试与性能纪律

文档对测试边界给出明确划分（测试文件均与之一一对应）：

必须覆盖：非法状态转移、并发 pause/close、取消、嵌套帧、断点解析、过期值引用、格式化界限、运行时错误、完成与清理失败。当改动可能影响正常调度或暂停交互成本时，须对调试元数据钩子与重复检视做基准（参考 debug_session_benchmark_test.go 与 format_bench_test.go）。

贯穿性要求：调试器状态不得改变正常 VM 执行；正常执行路径上的调试器专属工作必须显式、可度量、可立即绕过。

十、可移植调试器边界：Universal API 与坐标语义

调试器对外暴露的类型并非pkg/debugger独有，而是别名 Universal API 类型（types.go）：坐标、值、变量、帧、断点、原因与事件全部 aliasgithub.com/MontFerret/api/debugger。原生源码文本/索引与编译器调试表保持原生；表标识符在原生侧校验，仅在构造可移植调试器值时转换。NoFunction（顶层 body）与正数值引用约定由 Universal API 调试器包拥有；引用仅在其暂停状态有效。

坐标语义的精确约定（源位置语义详见 pkg/source）：

• 原生源码位置：行号从 1 开始、字节列号从 1 开始；span 是从 0 开始的半开字节偏移；
• 行号推进以LF为准，CRLF 在原源码中计两个字节；
• 断点请求列号为0表示仅按行请求；
• 畸形 UTF-8 遵循解析器的 Go rune 解码：每个非法字节消耗一个原字节并变成一个 replacement rune；发布的 span 与列号仍然指向原始字节（含畸形序列之后）；
• 协议适配器自行负责 UTF-16 转换，且必须使用编译时的源码快照；
• 源名可以是匿名或非路径身份；
• 编译器把 ANTLR 的 rune 偏移转换为字节 span 后再发布诊断与程序元数据（含调试点与调用参数 span）；分析层已发布字节 span。

此外：断点创建接受源码位置与可选绑定模式，未知模式被拒绝；命令取消在保留取消身份的同时上报终止；普通运行时失败保持为可检视的运行时错误停止；即使 after-run 钩子或后续结果清理失败，完成时仍保留事件与可用输出。

结语

Ferret 调试器的架构精髓在于职责的严格分层与不可变快照驱动的并发设计：VM 只做保留式执行与暂停态暴露，pkg/debugger承载全部源码级策略，pkg/engine负责准入与组装；实况断点通过"写者门串行化构造 + 原子指针发布 + 同步谓词查询"实现运行中无暂停更新；求值器与格式化器以保守、无副作用、有界为原则保护暂停态。想要进一步深入，可继续阅读 架构总览、运行时与生命周期 以及 开发工作流，并结合 pkg/vm/debug.go、pkg/debugger/session.go 与 pkg/debugger/breakpoint_set.go 源码对照验证。

• 网页爬虫
• 后端
• 开发工具