mcpField
D
debug-info-remapping

debug-info-remapping

github.com/lynx-community开发2868 次安装1 天前更新
代码仓库

关于 debug-info-remapping

Debug Info Remapping 是一项技能，可借助外部 debug-info.json 映射 Lynx 主线程堆栈位置。它指导定位映射文件并运行脚本，将字节码位置转换为源码位置。

主要功能

  1. 01映射函数 ID 与 PC 索引
  2. 02定位构建产物中的 debug-info.json
  3. 03运行 Node.js 重映射脚本
  4. 04将堆栈位置替换为源码位置

适用场景

  1. 01排查 Lynx 主线程运行时错误
  2. 02将字节码回溯位置转换为源码位置
  3. 03生成重映射后的调试堆栈

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lynx-community/skills --skill debug-info-remapping

安装后在 Claude Code 中输入/debug-info-remapping确认已加载。

附带文件scripts/index.mjs

详细介绍

调试信息重映射

描述

在 Lynx 中，主线程脚本会编码为字节码，并使用外部调试信息方案。根据此方案，运行时错误消息中的行号和列号并非实际行号和列号。需要从外部 debug-info.json 文件中解读行号和列号。

debug-info.json 格式如下：

{
  "lepusNG_debug_info": {
    "function_info": [
      {
        "function_id": 1,
        "function_name": "App",
        "line_col": [
          { "line": 1, "column": 1 },
          { "line": 2, "column": 1 },
          { "line": 3, "column": 1 }
        ]
      }
    ]
  }
}

何时使用

当你想将 function_id:pc_index 重映射到原始源代码位置时，此技能很有用。

当用户遇到运行时错误消息，其中包含 function_id:pc_index，以及错误消息中提到的 main-thread.js 和 debug-info.json 时，例如：

main-thread.js exception: App render failed at main thread backtrace:
    at App (file:///main-thread.js:1356:13)
    at doRender (file:///main-thread.js:1002:12)
    at call (native)
    at render (file:///main-thread.js:466:52)
    at _renderToString (file:///main-thread.js:1001:569)
    at renderToString (file:///main-thread.js:998:191)
    at renderMainThread (file:///main-thread.js:766:45)
    at renderPage (file:///main-thread.js:853:69)

其中，function_id:pc_index 为 1356:13。

工作流

1. 向用户询问 function_id:pc_index

用户应提供错误消息中的 function_id:pc_index，也可以提供完整的回溯信息。

你应检查这是否为主线程回溯信息，因为后台线程回溯信息无需重映射。

2. 在 debug-info.json 中查找对应位置

向用户询问 debug-info.json 的路径。例如，在入口为 main 的 rspeedy 项目中，文件位于：

  • main-thread.js：$PROJECT_DIR/dist/.rspeedy/main/main-thread.js
  • debug-info.json：$PROJECT_DIR/dist/.rspeedy/main/debug-info.json

如果用户使用 rspeedy build，且没有 .rspeedy 文件夹，请提醒他们使用 DEBUG='rspeedy,rsbuild' rspeedy build 构建项目。

3. 运行重映射脚本

对于堆栈跟踪中的每组 function_id:pc_index，运行重映射脚本。

node ${CLAUDE_PLUGIN_ROOT}/skills/debug-info-remapping/scripts/index.mjs $PROJECT_DIR/[dist]/.rspeedy/[main]/debug-info.json $function_id $pc_index
4. 输出重映射后的位置

重映射脚本会以 line:column 格式输出重映射后的位置。

你应输出每组 function_id:pc_index 对应的重映射后位置。

将堆栈跟踪中的 function_id:pc_index 替换为重映射后的位置，并显示重映射后的堆栈跟踪。

5. 显示重映射后的堆栈跟踪

如果你能访问 main-thread.js 文件，请显示带有重映射后位置源代码的堆栈跟踪。

最终输出应类似于：

main-thread.js exception: App render failed at main thread backtrace:
    at App (./dist/.rspeedy/main/main-thread.js:9368:56)
    at doRender (./dist/.rspeedy/main/main-thread.js:7237:44)
    at call (native)
    at render (./dist/.rspeedy/main/main-thread.js:3706:72)
    at _renderToString (./dist/.rspeedy/main/main-thread.js:7177:78)
    at renderToString (./dist/.rspeedy/main/main-thread.js:7067:91)
    at renderMainThread (./dist/.rspeedy/main/main-thread.js:5423:113)
    at renderPage (./dist/.rspeedy/main/main-thread.js:6199:46)

   ╭─[5:55]
 3 │ export function App() {
 4 │   if (__MAIN_THREAD__) {
 5 │     throw new Error('App render failed at main thread');
   ·                                                      ─┬
   ·                                                       ╰── main-thread.js exception: App render failed at main thread backtrace
 6 │   }
 7 │
   ╰────

   ... (the same for other callstacks such as doRender, call, render, _renderToString, renderToString, renderMainThread, renderPage here)

Files used:

  - Debug Info: ./dist/.rspeedy/main/debug-info.json
  - Source File: ./dist/.rspeedy/main/main-thread.js

./dist/.rspeedy/main/main-thread.js:9368:56 可确保该位置能在编辑器／终端中点击。

评论

支持 Markdown