Lynx Core Inspector 接口层剖析：运行时检查协调、Observer 契约与样式表数据结构

Lynx Core Inspector 接口层剖析：运行时检查协调、Observer 契约与样式表数据结构

【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx

本文以 core/inspector/AGENTS.md 为核心，结合该目录下的头文件与 构建脚本，系统讲解 Lynx 框架中 core inspector 模块的定位与边界：它如何作为“接口与协调层”统一管理 JS 运行时（QuickJS / RTS）与 Lepus 运行时（MTS）的检查能力、通过 Observer 契约向 Devtool 转发 DOM/CSS 事件，以及修改该层代码时需要遵循的编辑规则、常见回归症状与验证方式。读完后你将能够理解 Lynx Devtool 背后的 inspector 架构，并知道在改动这些共享契约时如何避免典型故障。

1. 模块定位：一个纯粹的接口与协调层

core/inspector/AGENTS.md 在 Scope 一节明确给出该目录的职责边界：

This directory contains core inspector-facing interfaces: runtime inspector management, inspector observers, console-message plumbing, and stylesheet-facing inspection data.

即core/inspector只包含面向 inspector 的接口，涵盖四块内容：运行时检查管理（runtime inspector management）、检查观察者（inspector observers）、console 消息转发（console-message plumbing）以及面向检查的样式表数据（stylesheet-facing inspection data）。

从源码结构看，这一“纯接口”定位是真实成立的：整个目录除两个单测文件外全部是头文件，没有任何重逻辑实现。AGENTS.md 的 Edit Rules 一节进一步强化了这一约束，共三条编辑规则：

1. 保持接口与协调层属性：“Keep this directory as an interface and coordination layer. Heavy renderer or runtime logic should stay in the owning module.”——重量级的 renderer 或 runtime 逻辑必须留在各自所属的模块中（例如devtool/下的 LynxDevtool 实现），不能下沉到本目录；
2. 谨慎变更 Observer 契约：这里的 observer 接口是共享契约（shared contracts），修改方法签名（method shapes）或事件顺序（event ordering）要格外小心；
3. 实现侧变更应留在目录外：如果某个改动只涉及某个具体运行时的实现，优先修改本目录之外的实现侧代码，保持 inspector 接口稳定。

这一设计让core/inspector成为 Lynx 内核与 Devtool 之间的稳定 ABI 边界：运行时实现（QuickJS、RTS/QuickJS-NG）与渲染树（Lepus/TASM）可以独立演进，而 inspector 契约保持稳定。

2. 模块地图（Module Map）逐一对照源码

AGENTS.md 的 Module Map 列出了 4 个核心组成部分。下面逐一结合源码展开。

2.1 runtime_inspector_manager.h：顶层运行时检查协调

core/inspector/runtime_inspector_manager.h 定义了RuntimeInspectorManager（位于lynx::runtime::js命名空间），是 JS 运行时检查的顶层协调接口：

class RuntimeInspectorManager { public: virtual ~RuntimeInspectorManager() = default; virtual void InitInspector( Runtime* runtime, const std::shared_ptr<InspectorRuntimeObserverNG>& observer) = 0; virtual void DestroyInspector() = 0; std::string BuildInspectorUrl(const std::string& filename); virtual void PrepareForScriptEval() = 0; protected: int instance_id_{-1}; };

三个纯虚方法构成完整的生命周期契约：

• InitInspector(Runtime*, shared_ptr<InspectorRuntimeObserverNG>)：为指定Runtime实例挂载 observer，开启检查；
• DestroyInspector()：拆除检查能力；
• PrepareForScriptEval()：在脚本求值前的准备钩子，保证后续执行的脚本可被断点等检查手段捕获。

值得注意的是BuildInspectorUrl()——它是基类中唯一的具体实现，负责把脚本文件名规范化为 inspector 可识别的 URL。其规则是：

• 文件名包含lynx_core时，统一加file://shared前缀（框架核心脚本，各实例共享）；
• 其他业务脚本加file://view<instance_id>前缀，instance_id_用于区分同一进程内的多个 Lynx 实例（view0、view1…）；
• 相对路径自动补/前缀。

该行为有对应的单测 runtime_inspector_manager_unittest.cc 验证：

EXPECT_TRUE(manager->BuildInspectorUrl("/app-service.js") == "file://view1/app-service.js"); EXPECT_TRUE(manager->BuildInspectorUrl("lynx_core.js") == "file://shared/lynx_core.js");

这个按 view 隔离 URL 空间的机制正是 AGENTS.md 提到的“shared inspector contracts”的一部分——契约必须与具体运行时无关，否则就会出现“Runtime inspection works for one backend but not another”的回归（见第 5 节）。

2.2 observer/：四路观察者契约

AGENTS.md 写道：“observer interfaces for common, element, Lepus, and runtime inspection hooks”，对应 core/inspector/observer/ 目录下的四个核心头文件。

（1）inspector_runtime_observer_ng.h —— JS 运行时侧的核心契约

InspectorRuntimeObserverNG（注释注明“Only works for js runtime”）是 JS 运行时与 LynxDevtool 之间的双向枢纽，分为两类方法：

工厂方法——由核心侧调用，让 Devtool 实现创建所需实例：

virtual std::unique_ptr<runtime::RuntimeManagerDelegate> CreateRuntimeManagerDelegate() { return nullptr; } virtual std::unique_ptr<RuntimeInspectorManager> CreateRuntimeInspectorManager(const std::string& vm_type) { return nullptr; } virtual std::shared_ptr<ConsoleMessagePostMan> CreateConsoleMessagePostMan() { return nullptr; } virtual std::shared_ptr<NativeModuleRecordObserver> CreateNativeModuleRecordObserver() { return nullptr; } virtual void InitWhiteBoardInspector( const std::shared_ptr<tasm::WhiteBoardDelegate>& delegate) = 0;

注意CreateRuntimeInspectorManager接收vm_type参数——这正是“一个契约、多个运行时后端”的体现：不同 VM 类型由 Devtool 侧返回对应的 manager 实现，core 层不关心具体后端。

事件通知方法——由运行时侧回调，把运行时生命周期事件推给 Devtool：

virtual void OnInspectorInited( const std::string& vm_type, int64_t runtime_id, const std::string& group_id, bool single_group, const std::shared_ptr<devtool::InspectorClientNG>& client) = 0; virtual void OnRuntimeCreated(JSRuntimeType type) = 0; virtual void OnRuntimeDestroyed(int64_t runtime_id) = 0; virtual void PrepareForScriptEval() = 0;

其中OnInspectorInited携带vm_type、runtime_id、group_id与single_group，支持运行时分组（多 runtime 场景下 Devtool 可据此区分检查会话）；InspectorClientNG则是 Devtool 侧的连接句柄，初始化完成后反向交给观察者，形成闭环。

（2）inspector_element_observer.h —— 元素/DOM 与 CSS 事件

InspectorElementObserver（lynx::tasm命名空间）承接渲染树侧的变更通知，关键方法包括：

• OnDocumentUpdated()：文档更新；
• OnElementNodeAdded(Element*)/OnElementNodeRemoved(Element*)：头文件注释特意说明了两点设计意图——新增节点可以逐个通知，也可以只通知“新子树根节点”一次以避免逐节点刷爆 Devtool；而页根节点通知时会在 Devtool 侧设置element_root_，供 Devtool 按nodeId查找节点。这解释了 AGENTS.md 中“event ordering”为何重要——根节点必须先到达，后续nodeId解析才有锚点；
• OnCharacterDataModified、OnElementDataModelSet、OnElementManagerWillDestroy：文本与数据模型变更、元素管理器销毁；
• OnCSSStyleSheetAdded(Element*)、OnCSSMediaQueryResultChanged()：样式表挂载与媒体查询结果变化（后者与 Devtool 中媒体查询切换面板直接相关）；
• OnComponentUselessUpdate、OnSetNativeProps、OnAddInlineStyle：组件无效更新、原生属性设置、内联样式添加等细粒度钩子（部分方法如OnAddInlineStyle、OnFiberFlushElementTree提供空默认实现，属于可选钩子）；
• GetDevToolFunction()：返回DevToolFunction -> std::function<void(const base::any &)>的映射，让 Devtool 反向调用引擎能力（见 2.4 节DevToolFunction枚举）。

（3）inspector_lepus_observer.h —— Lepus（MTS）运行时侧

InspectorLepusObserver是 Lepus 脚本运行时的检查契约，与 JS 侧的InspectorRuntimeObserverNG结构对称但独立：

• CreateLepusInspectorManager(runtime::ContextType)：按上下文类型创建 LepusInspectorManager；
• ShouldFetchDebugInfo()/GetDebugInfo(url)/SetDebugInfoUrl(url, file_name)：调试信息（如 source map / 反混淆源码）的拉取与登记；
• OnInspectorInited(vm_type, name, client)/OnContextDestroyed(name)：按 context 名（而非 runtime_id）管理生命周期，体现 MTS 以“上下文”为中心的组织方式；
• TakeOver(shared_ptr<InspectorLepusObserver>)：把一个 observer 的会话“接管”给另一个 observer，用于 Devtool 重连/切换场景；
• OnConsoleEvent(func_name, args)、PrepareForScriptEval(name)：console 事件与脚本求值前准备。

配套的 lepus_inspector_manager.h 定义了管理器基类（InitInspector(MTSContext*, observer, context_name)、SetDebugInfo、DestroyInspector、UpdateInspector），而 rts_inspector_manager.h 在其上扩展出 RTS 特有接口：

class RTSInspectorManager : public LepusInspectorManager { public: virtual bool LoadScriptWithSource(RNIEnv* env, const uint8_t* buf, size_t buf_len, const std::string& filename, int* result) = 0; virtual std::unordered_map<std::string, std::string> GetSource( RNIEnv* env, const std::string& url) = 0; };

LoadScriptWithSource让 Devtool 在注入检查时替换/附加脚本源码，GetSource支持按 URL 回查源码——这是 RTS 后端能独立支持检查的关键能力面。

（4）inspector_common_observer.h —— 通用钩子

最精简的契约，聚焦回放测试（replay test）与布局树：

class InspectorCommonObserver { public: virtual void EndReplayTest(const std::string& file_path) = 0; virtual void SendLayoutTree() = 0; virtual void FlushLayoutTreeForReplayEnd(std::function<void()> callback) = 0; virtual void OnGlobalPropsUpdated() {} };

SendLayoutTree向 Devtool 推送布局树；EndReplayTest/FlushLayoutTreeForReplayEnd用于回放测试结束时的收尾（回放测试是 Lynx 集成测试体系中常用的截图/行为比对手段）；OnGlobalPropsUpdated提供空默认实现，属于可选通知。

2.3 console_message_postman.h：console 消息转发契约

core/inspector/console_message_postman.h 定义了两件事：消息结构与转发器接口。

struct ConsoleMessage { ConsoleMessage(const std::string& text, int32_t level, int64_t timestamp) : text_(text), level_(level), timestamp_(timestamp){}; std::string text_; int32_t level_; int64_t timestamp_; }; class ConsoleMessagePostMan { public: virtual void OnMessagePosted(const ConsoleMessage& message) = 0; virtual void InsertRuntimeObserver( const std::shared_ptr<InspectorRuntimeObserverNG>& observer) = 0; };

ConsoleMessage携带文本、级别（level）与时间戳三要素，是 Devtool Console 面板每条消息的数据载体。ConsoleMessagePostMan是“邮差”接口：运行时的 console 输出经OnMessagePosted递交，而InsertRuntimeObserver则把 2.2 节 的 observer 注入进来，使 console 管道能挂接到正确的检查会话上。

这条管道的脆弱性恰是 AGENTS.md “Common Regression Symptoms” 所列之一（“Console messages stop showing up or duplicate after changes to message-posting interfaces”）——一旦投递接口被改动，消息会丢失或重复。

2.4 style_sheet.h：面向检查的样式表数据面

core/inspector/style_sheet.h（lynx::devtool命名空间）是 Devtool Elements 样式面板所需数据的“扁平化数据面”。核心结构包括：

• Range { start_line_, end_line_, start_column_, end_column_ }：源码位置区间，用于 Devtool 中“点击样式跳转源码”；
• CSSPropertyDetail：单条 CSS 属性详情，含name_/value_/text_以及disabled_（被划掉）、implicit_（继承隐式）、important_、looped_、parsed_ok_等状态位与property_range_——这些标志位直接决定了 Devtool 样式面板中属性是否显示删除线、是否标注!important等视觉语义；
• InspectorStyleSheet：一张样式表/一段内联样式的完整描述，含style_sheet_id_、css_text_、媒体查询（media_text_+media_range_）、@supports（supports_text_+supports_range_）、cascadelayers_、css_properties_（按名称多值映射，对应多条同名规则）、shorthand_entries_（简写展开）、property_order_（属性顺序，保证面板展示顺序稳定）以及style_value_range_/style_name_range_（源码定位）；
• InspectorKeyframe/InspectorSelectorList/InspectorCSSRule：keyframes 规则、选择器列表（含selectors_order_保序）与 CSS 规则的组装关系；
• 枚举面：InspectorElementType（DOCUMENT/STYLEVALUE/ELEMENT/COMPONENT）、InspectorNodeType（ElementNode/TextNode/DocumentNode）描述检查节点的层级类型；DevToolFunction（InitForInspector、SetDocElement、SetStyleValueElement、SetStyleRoot等 7 个）对应 Devtool 初始化阶段的调用入口，与InspectorElementObserver::GetDevToolFunction()的函数表机制配合。

头文件中还有一张庞大的Function枚举（Index、Parent、Tag、ClassOrder、InlineStyle、BoxModel、SetAttribute、SetStyle、ProcessCSS 等 34 项），定义了 Devtool 侧对元素节点可发起的“操作命令”语义空间——例如SetAttribute/SetStyle对应 Devtool 中直接编辑节点属性与样式的能力，BoxModel对应盒模型可视化数据。这张枚举是 core 与 Devtool 之间的稳定字典，改动同样受“共享契约谨慎变更”规则约束。

3. 构建视角：接口如何被条件化裁剪

core/inspector/BUILD.gn 展示了该接口层的构建组织方式，也印证了 AGENTS.md 的模块地图：

inspector_shared_sources = [ "console_message_postman.h", "lepus_inspector_manager.h", "observer/inspector_common_observer.h", "observer/inspector_element_observer.h", "observer/inspector_lepus_observer.h", "observer/inspector_runtime_observer_ng.h", "runtime_inspector_manager.h", "style_sheet.h", ] if (enable_inspector) { inspector_shared_sources += [ "observer/native_module_record_observer.h" ] } if (!disable_rts_devtool) { inspector_shared_sources += [ "rts_inspector_manager.h" ] } lynx_core_source_set("inspector") { sources = inspector_shared_sources public_deps = [ "../../third_party/rapidjson" ] }

两点值得注意：

1. 能力开关：enable_inspector控制是否包含 observer/native_module_record_observer.h（native module 调用记录，服务 Devtool 的模块调用追踪）；disable_rts_devtool则裁剪 RTS 检查管理器。也就是说 inspector 契约面可以随构建配置收缩，而基础八件套始终在场——这与“接口层保持稳定”的编辑规则相呼应；
2. rapidjson作为 public 依赖：说明检查数据面在跨模块传递时会用到 JSON 序列化，依赖方向明确暴露给所有消费者。

4. 三条编辑规则的源码级解读

把 AGENTS.md 的 Edit Rules 落到源码证据上：

• “Heavy logic stays in the owning module”：本目录唯一的具体实现是BuildInspectorUrl（纯字符串拼装）与 observer 的空默认方法；真正的检查逻辑位于devtool/（LynxDevtool，如inspector/observer/inspector_runtime_observer_ng.h注释所述“implemented in LynxDevtool”）与各运行时后端目录。core/inspector因此几乎零实现成本，天然可被各平台构建复用；
• “Be careful when changing method shapes or event ordering”：InspectorRuntimeObserverNG的工厂方法 + 事件回调是 core → Devtool 与 Devtool → core 两条调用方向的交汇点；InspectorElementObserver::OnElementNodeAdded的注释明确了“根节点先行”的隐式顺序依赖，任何签名调整都可能破坏 Devtool 侧的节点索引；
• “Keep the inspector interface stable”：LepusInspectorManager/RTSInspectorManager的继承结构、RuntimeInspectorManager的三方法生命周期，都是运行时后端可替换性的基础——更换 VM 只需实现新 manager，无需动 core 侧契约。

5. 常见回归症状与自查对照

AGENTS.md 列出的三条 Common Regression Symptoms，每一条都对应本目录中一条具体契约链：

6. 验证方式：从 inspector_test_exec 入手

AGENTS.md 的 Validate 一节给出验证入口：本目录的 C++ 单元测试优先使用lynx-cpp-test技能，从inspector_test_exec开始。对照 BUILD.gn：

unittest_set("inspector_testset") { public_configs = [ "../:lynx_public_config" ] sources = [ "runtime_inspector_manager_unittest.cc", "runtime_inspector_manager_unittest.h", ] } unittest_exec("inspector_test_exec") { sources = [] deps = [ ":inspector_testset" ] } group("inspector_group") { testonly = true deps = [ ":inspector_test_exec", ":inspector_testset", ] }

目前测试集聚焦BuildInspectorUrl的 URL 归一化行为（见 runtime_inspector_manager_unittest.cc），通过 mock manager 覆盖“相对/绝对路径 × 业务脚本/lynx_core 脚本”四种组合。AGENTS.md 同时提醒：如果改动触及运行时侧契约（如 observer 方法签名、ConsoleMessage结构），还应考虑运行 runtime 层所属的测试，因为契约的另一端实现在运行时与 Devtool 模块中——这与第 4 节“接口稳定、实现侧去改”的规则形成闭环。

7. 小结

core/inspector是 Lynx 内核与 Devtool 之间的契约中枢：RuntimeInspectorManager与LepusInspectorManager/RTSInspectorManager分别托管 JS 运行时与 Lepus/RTS 运行时的检查生命周期；四路 observer（common、element、lepus、runtime NG）定义了 DOM、CSS、运行时事件向 Devtool 的单向通知通道；ConsoleMessagePostMan与style_sheet.h的数据结构则分别承载 Console 消息管道与样式面板数据面。遵循 AGENTS.md 的编辑规则——接口保持轻量、契约变更谨慎、实现留在目录外——并以inspector_test_exec作为回归验证起点，是维护这一层的正确姿势。

【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx