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 一节进一步强化了这一约束共三条编辑规则保持接口与协调层属性“Keep this directory as an interface and coordination layer. Heavy renderer or runtime logic should stay in the owning module.”——重量级的 renderer 或 runtime 逻辑必须留在各自所属的模块中例如devtool/下的 LynxDevtool 实现不能下沉到本目录谨慎变更 Observer 契约这里的 observer 接口是共享契约shared contracts修改方法签名method shapes或事件顺序event ordering要格外小心实现侧变更应留在目录外如果某个改动只涉及某个具体运行时的实现优先修改本目录之外的实现侧代码保持 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_ptrInspectorRuntimeObserverNG 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_ptrInspectorRuntimeObserverNG)为指定Runtime实例挂载 observer开启检查DestroyInspector()拆除检查能力PrepareForScriptEval()在脚本求值前的准备钩子保证后续执行的脚本可被断点等检查手段捕获。值得注意的是BuildInspectorUrl()——它是基类中唯一的具体实现负责把脚本文件名规范化为 inspector 可识别的 URL。其规则是文件名包含lynx_core时统一加file://shared前缀框架核心脚本各实例共享其他业务脚本加file://viewinstance_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/ 目录下的四个核心头文件。1inspector_runtime_observer_ng.h —— JS 运行时侧的核心契约InspectorRuntimeObserverNG注释注明“Only works for js runtime”是 JS 运行时与 LynxDevtool 之间的双向枢纽分为两类方法工厂方法——由核心侧调用让 Devtool 实现创建所需实例virtual std::unique_ptrruntime::RuntimeManagerDelegate CreateRuntimeManagerDelegate() { return nullptr; } virtual std::unique_ptrRuntimeInspectorManager CreateRuntimeInspectorManager(const std::string vm_type) { return nullptr; } virtual std::shared_ptrConsoleMessagePostMan CreateConsoleMessagePostMan() { return nullptr; } virtual std::shared_ptrNativeModuleRecordObserver CreateNativeModuleRecordObserver() { return nullptr; } virtual void InitWhiteBoardInspector( const std::shared_ptrtasm::WhiteBoardDelegate delegate) 0;注意CreateRuntimeInspectorManager接收vm_type参数——这正是“一个契约、多个运行时后端”的体现不同 VM 类型由 Devtool 侧返回对应的 manager 实现core 层不关心具体后端。事件通知方法——由运行时侧回调把运行时生命周期事件推给 Devtoolvirtual void OnInspectorInited( const std::string vm_type, int64_t runtime_id, const std::string group_id, bool single_group, const std::shared_ptrdevtool::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 侧的连接句柄初始化完成后反向交给观察者形成闭环。2inspector_element_observer.h —— 元素/DOM 与 CSS 事件InspectorElementObserverlynx::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::functionvoid(const base::any )的映射让 Devtool 反向调用引擎能力见 2.4 节DevToolFunction枚举。3inspector_lepus_observer.h —— LepusMTS运行时侧InspectorLepusObserver是 Lepus 脚本运行时的检查契约与 JS 侧的InspectorRuntimeObserverNG结构对称但独立CreateLepusInspectorManager(runtime::ContextType)按上下文类型创建 LepusInspectorManagerShouldFetchDebugInfo()/GetDebugInfo(url)/SetDebugInfoUrl(url, file_name)调试信息如 source map / 反混淆源码的拉取与登记OnInspectorInited(vm_type, name, client)/OnContextDestroyed(name)按 context 名而非 runtime_id管理生命周期体现 MTS 以“上下文”为中心的组织方式TakeOver(shared_ptrInspectorLepusObserver)把一个 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_mapstd::string, std::string GetSource( RNIEnv* env, const std::string url) 0; };LoadScriptWithSource让 Devtool 在注入检查时替换/附加脚本源码GetSource支持按 URL 回查源码——这是 RTS 后端能独立支持检查的关键能力面。4inspector_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::functionvoid() callback) 0; virtual void OnGlobalPropsUpdated() {} };SendLayoutTree向 Devtool 推送布局树EndReplayTest/FlushLayoutTreeForReplayEnd用于回放测试结束时的收尾回放测试是 Lynx 集成测试体系中常用的截图/行为比对手段OnGlobalPropsUpdated提供空默认实现属于可选通知。2.3 console_message_postman.hconsole 消息转发契约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_ptrInspectorRuntimeObserverNG 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.hlynx::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_、supportssupports_text_supports_range_、cascadelayers_、css_properties_按名称多值映射对应多条同名规则、shorthand_entries_简写展开、property_order_属性顺序保证面板展示顺序稳定以及style_value_range_/style_name_range_源码定位InspectorKeyframe/InspectorSelectorList/InspectorCSSRulekeyframes 规则、选择器列表含selectors_order_保序与 CSS 规则的组装关系枚举面InspectorElementTypeDOCUMENT/STYLEVALUE/ELEMENT/COMPONENT、InspectorNodeTypeElementNode/TextNode/DocumentNode描述检查节点的层级类型DevToolFunctionInitForInspector、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 ] }两点值得注意能力开关enable_inspector控制是否包含 observer/native_module_record_observer.hnative module 调用记录服务 Devtool 的模块调用追踪disable_rts_devtool则裁剪 RTS 检查管理器。也就是说 inspector 契约面可以随构建配置收缩而基础八件套始终在场——这与“接口层保持稳定”的编辑规则相呼应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每一条都对应本目录中一条具体契约链回归症状对应契约链自查点Inspector 会话连上但收不到任何更新Observer 契约漂移common / element / runtime observer检查 observer 回调是否仍按约定触发尤其是OnInspectorInited、OnElementNodeAdded的时序与参数Console 消息消失或重复ConsoleMessagePostMan消息投递接口核对OnMessagePosted的投递路径与InsertRuntimeObserver的会话挂接是否一一对应避免同一消息进入两个 postman检查功能在一个后端正常、另一个后端失效共享契约被写成运行时特定确认契约中没有泄漏具体 VM 类型如硬编码QuickJS*新后端能力应通过CreateRuntimeInspectorManager(vm_type)这类工厂点注入6. 验证方式从 inspector_test_exec 入手AGENTS.md 的 Validate 一节给出验证入口本目录的 C 单元测试优先使用lynx-cpp-test技能从inspector_test_exec开始。对照 BUILD.gnunittest_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 运行时的检查生命周期四路 observercommon、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 一节进一步强化了这一约束共三条编辑规则保持接口与协调层属性“Keep this directory as an interface and coordination layer. Heavy renderer or runtime logic should stay in the owning module.”——重量级的 renderer 或 runtime 逻辑必须留在各自所属的模块中例如devtool/下的 LynxDevtool 实现不能下沉到本目录谨慎变更 Observer 契约这里的 observer 接口是共享契约shared contracts修改方法签名method shapes或事件顺序event ordering要格外小心实现侧变更应留在目录外如果某个改动只涉及某个具体运行时的实现优先修改本目录之外的实现侧代码保持 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_ptrInspectorRuntimeObserverNG 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_ptrInspectorRuntimeObserverNG)为指定Runtime实例挂载 observer开启检查DestroyInspector()拆除检查能力PrepareForScriptEval()在脚本求值前的准备钩子保证后续执行的脚本可被断点等检查手段捕获。值得注意的是BuildInspectorUrl()——它是基类中唯一的具体实现负责把脚本文件名规范化为 inspector 可识别的 URL。其规则是文件名包含lynx_core时统一加file://shared前缀框架核心脚本各实例共享其他业务脚本加file://viewinstance_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/ 目录下的四个核心头文件。1inspector_runtime_observer_ng.h —— JS 运行时侧的核心契约InspectorRuntimeObserverNG注释注明“Only works for js runtime”是 JS 运行时与 LynxDevtool 之间的双向枢纽分为两类方法工厂方法——由核心侧调用让 Devtool 实现创建所需实例virtual std::unique_ptrruntime::RuntimeManagerDelegate CreateRuntimeManagerDelegate() { return nullptr; } virtual std::unique_ptrRuntimeInspectorManager CreateRuntimeInspectorManager(const std::string vm_type) { return nullptr; } virtual std::shared_ptrConsoleMessagePostMan CreateConsoleMessagePostMan() { return nullptr; } virtual std::shared_ptrNativeModuleRecordObserver CreateNativeModuleRecordObserver() { return nullptr; } virtual void InitWhiteBoardInspector( const std::shared_ptrtasm::WhiteBoardDelegate delegate) 0;注意CreateRuntimeInspectorManager接收vm_type参数——这正是“一个契约、多个运行时后端”的体现不同 VM 类型由 Devtool 侧返回对应的 manager 实现core 层不关心具体后端。事件通知方法——由运行时侧回调把运行时生命周期事件推给 Devtoolvirtual void OnInspectorInited( const std::string vm_type, int64_t runtime_id, const std::string group_id, bool single_group, const std::shared_ptrdevtool::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 侧的连接句柄初始化完成后反向交给观察者形成闭环。2inspector_element_observer.h —— 元素/DOM 与 CSS 事件InspectorElementObserverlynx::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::functionvoid(const base::any )的映射让 Devtool 反向调用引擎能力见 2.4 节DevToolFunction枚举。3inspector_lepus_observer.h —— LepusMTS运行时侧InspectorLepusObserver是 Lepus 脚本运行时的检查契约与 JS 侧的InspectorRuntimeObserverNG结构对称但独立CreateLepusInspectorManager(runtime::ContextType)按上下文类型创建 LepusInspectorManagerShouldFetchDebugInfo()/GetDebugInfo(url)/SetDebugInfoUrl(url, file_name)调试信息如 source map / 反混淆源码的拉取与登记OnInspectorInited(vm_type, name, client)/OnContextDestroyed(name)按 context 名而非 runtime_id管理生命周期体现 MTS 以“上下文”为中心的组织方式TakeOver(shared_ptrInspectorLepusObserver)把一个 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_mapstd::string, std::string GetSource( RNIEnv* env, const std::string url) 0; };LoadScriptWithSource让 Devtool 在注入检查时替换/附加脚本源码GetSource支持按 URL 回查源码——这是 RTS 后端能独立支持检查的关键能力面。4inspector_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::functionvoid() callback) 0; virtual void OnGlobalPropsUpdated() {} };SendLayoutTree向 Devtool 推送布局树EndReplayTest/FlushLayoutTreeForReplayEnd用于回放测试结束时的收尾回放测试是 Lynx 集成测试体系中常用的截图/行为比对手段OnGlobalPropsUpdated提供空默认实现属于可选通知。2.3 console_message_postman.hconsole 消息转发契约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_ptrInspectorRuntimeObserverNG 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.hlynx::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_、supportssupports_text_supports_range_、cascadelayers_、css_properties_按名称多值映射对应多条同名规则、shorthand_entries_简写展开、property_order_属性顺序保证面板展示顺序稳定以及style_value_range_/style_name_range_源码定位InspectorKeyframe/InspectorSelectorList/InspectorCSSRulekeyframes 规则、选择器列表含selectors_order_保序与 CSS 规则的组装关系枚举面InspectorElementTypeDOCUMENT/STYLEVALUE/ELEMENT/COMPONENT、InspectorNodeTypeElementNode/TextNode/DocumentNode描述检查节点的层级类型DevToolFunctionInitForInspector、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 ] }两点值得注意能力开关enable_inspector控制是否包含 observer/native_module_record_observer.hnative module 调用记录服务 Devtool 的模块调用追踪disable_rts_devtool则裁剪 RTS 检查管理器。也就是说 inspector 契约面可以随构建配置收缩而基础八件套始终在场——这与“接口层保持稳定”的编辑规则相呼应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每一条都对应本目录中一条具体契约链回归症状对应契约链自查点Inspector 会话连上但收不到任何更新Observer 契约漂移common / element / runtime observer检查 observer 回调是否仍按约定触发尤其是OnInspectorInited、OnElementNodeAdded的时序与参数Console 消息消失或重复ConsoleMessagePostMan消息投递接口核对OnMessagePosted的投递路径与InsertRuntimeObserver的会话挂接是否一一对应避免同一消息进入两个 postman检查功能在一个后端正常、另一个后端失效共享契约被写成运行时特定确认契约中没有泄漏具体 VM 类型如硬编码QuickJS*新后端能力应通过CreateRuntimeInspectorManager(vm_type)这类工厂点注入6. 验证方式从 inspector_test_exec 入手AGENTS.md 的 Validate 一节给出验证入口本目录的 C 单元测试优先使用lynx-cpp-test技能从inspector_test_exec开始。对照 BUILD.gnunittest_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 运行时的检查生命周期四路 observercommon、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考