支持supportsDisassembleRequest (53/54/55)

Author: actboy168

CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 构建系统
+
+使用 [luamake](https://github.com/actboy168/luamake) 作为构建工具（基于 Lua）。
+
+```bash
+# 先安装 luamake（见 README），然后：
+luamake lua compile/download_deps.lua   # 下载依赖
+luamake -mode release                    # 构建
+luamake test                             # 仅构建测试
+```
+
+## 架构
+
+这是一个 VS Code 调试器扩展，支持调试 Lua 5.1–5.5 和 LuaJIT。扩展入口是 `extension/js/extension.js`，但大部分逻辑在 `extension/script/` 下的 Lua 脚本中。
+
+### 三进程调试模型
+
+```
+VS Code (JS)  ──DAP──>  Frontend (Lua proxy)  ──socket──>  Master (Lua 线程)
+                    extension/script/frontend/          extension/script/backend/master/
+
+                   Master  ──bee.channel──>  Worker (Lua 线程，在目标进程内运行)
+                                            extension/script/backend/worker/
+```
+
+- **Frontend (`frontend/proxy.lua`)**：桥接 DAP 协议（Content-Length 头 + JSON）和 Master。负责 launch/attach 编排、进程管理、WSL 路径转换。
+- **Master (`backend/master/mgr.lua`)**：会话生命周期管理，将 DAP 请求路由到 Worker，管理线程状态，捕获 stdout/stderr。
+- **Worker (`backend/worker.lua`)**：在独立 Lua VM 中运行。处理断点、单步、调用栈、变量查看、表达式求值。通过命名 `bee.channel` 通道与 Master 通信。
+
+### 调试器与调试目标的隔离
+
+**Worker 和被调试的 Lua VM 是两个完全独立的 Lua 虚拟机。** 调试器的 Lua 脚本运行在 `luadbg`（内嵌的 Lua 解释器变体）中，被调试的目标程序运行在另一个 Lua VM（可能是不同的 Lua 版本）。两者不能直接传递 Lua 对象（function、userdata 等）。
+
+跨 VM 通信通过原生 C++ 模块桥接：
+
+- **`rdebug_debughost.cpp`** — Worker VM 的入口。`luaopen_luadebug` 在目标进程中创建 Worker VM（`luadbg_State`），将目标 VM 的 `lua_State*` 注册到 Worker 的注册表中。
+- **`util/refvalue.h`** — 引用值系统。Worker 中的变量（function、table、userdata 等）实际存储为 **refvalue**（tagged union 的 userdata），描述*如何*在目标 VM 中定位该值（如"第 N 帧的第 M 个局部变量"、"table 数组的第 K 个元素"）。通过 `refvalue::eval(v, hL)` 解析引用，将实际值推入目标 VM 的栈上。
+- **`rdebug_visitor.cpp`** — 导出给 Worker Lua 的函数表（`luadebug.visitor` 模块）。每个函数通过 `debughost::get(L)` 获取目标 `lua_State*`，然后操作目标 VM。`copy_to_dbg`/`copy_from_dbg` 在两个 VM 之间传递简单类型（nil、bool、number、string、lightuserdata）的值。
+- **`rdebug_hookmgr.cpp`** — Hook 管理。直接操作目标 VM 的 hook 机制。
+
+**这意味着**：Worker Lua 脚本中不能对目标 VM 的值直接调用 `string.dump()`、`pairs()` 等 Lua 标准函数。必须通过 `rdebug` 原生模块提供的函数来间接操作。
+
+### 原生 C++ 库 (`src/luadebug/`)
+
+编译为动态库（`luadebug.dll`/`.so`）。Worker 将其加载到目标进程中以 hook Lua VM：
+- `rdebug_init.cpp` — DLL 入口，在目标进程中定位 Lua DLL
+- `rdebug_hookmgr.cpp` — Hook 管理（单步/断点 hook）
+- `rdebug_visitor.cpp` — 栈帧/变量查看
+- `rdebug_debughost.cpp` — Worker VM 生命周期管理，双 VM 绑定
+- `compat/` — Lua 版本抽象层（5.x 通过 `5x/`，LuaJIT 通过 `jit/`）
+- `thunk/` — 各架构的 hook 跳板代码（x86、x64、ARM64，Windows/macOS/Linux）
+- `luadbg/` — 内嵌的 Lua 解释器变体（Worker 的运行时）
+- `util/refvalue.h` — 引用值系统，跨 VM 值的懒解析
+
+### 启动器 (`src/launcher/`)
+
+一个小型可执行文件，用于启动目标 Lua 进程或附加到运行中的进程，然后注入调试器 DLL。
+
+### 扩展 Lua 脚本 (`extension/script/`)
+
+| 目录 | 用途 |
+|---|---|
+| `frontend/` | VS Code DAP 代理、进程创建、平台检测 |
+| `backend/master/` | 请求路由、线程管理、事件处理 |
+| `backend/worker/` | 断点、表达式求值、变量、序列化、源码映射 |
+| `common/` | 共享：协议组帧、JSON、IPC、网络、base64 |
+
+## 关键文件
+
+- `make.lua` — 根构建入口
+- `extension/package.json` — VS Code 扩展清单
+- `extension/script/debugger.lua` — 调试器入口，由目标进程通过 `dofile` 加载
+- `extension/script/launch.lua` / `attach.lua` — 注入目标进程的启动脚本
+- `extension/script/backend/bootstrap.lua` — 创建 Master 线程，然后在当前线程初始化 Worker
+- `extension/script/common/protocol.lua` — DAP 线协议（Content-Length 头 + JSON）
+- `extension/script/backend/worker/hookmgr.lua` — Lua hook 管理器，以 `luadebug.hookmgr` 加载
+- `compile/common/config.lua` — 默认构建配置（C11、C++17、debug 模式）
+
+## 代码风格
+
+- Lua：4 空格缩进，数学运算符两侧加空格，函数调用括号前不加空格，保留尾部表分隔符
+- C/C++：clang-format，配置文件在 `.clang-format` 和 `.clang-format-ignore`
+- `.editorconfig` 中有完整的 Lua 格式化规则
+
+## Git 子模块
+
+本仓库使用 git submodule。克隆或切换分支后若检测到子模块变更，请始终运行 `git submodule update --init`。

docs/capabilities.md

@@ -31,7 +31,7 @@
 | supportsDataBreakpoints               |    🟨    |
 | supportsReadMemoryRequest             |    🟩    |
 | supportsWriteMemoryRequest            |    🟩    |
-| supportsDisassembleRequest            |    🟨    |
+| supportsDisassembleRequest            |    🟩    |
 | supportsCancelRequest                 |    🟨    |
 | supportsBreakpointLocationsRequest    |    🟨    |
 | supportsClipboardContext              |    🟩    |

extension/script/backend/master/request.lua

@@ -633,6 +633,35 @@ function request.writeMemory(req)
     })
 end
 
+function request.disassemble(req)
+    local args = req.arguments
+    local memoryReference = args.memoryReference
+    -- inst_<threadId>x<rest> (from instructionPointerReference)
+    local threadId, refId = memoryReference:match("inst_(%d+)x(.+)$")
+    if not refId then
+        -- memory_<threadId>x<refId> (from variable with memoryReference)
+        threadId, refId = memoryReference:match("memory_(%d+)x(%d+)")
+    end
+    threadId = tonumber(threadId)
+    if not threadId or not refId then
+        response.error(req, "Invalid memoryReference")
+        return
+    end
+    if not checkThreadId(req, threadId) then
+        return
+    end
+    mgr.workerSend(threadId, {
+        cmd = 'disassemble',
+        command = req.command,
+        seq = req.seq,
+        refId = refId,
+        offset = args.offset,
+        instructionOffset = args.instructionOffset,
+        instructionCount = args.instructionCount,
+        resolveSymbols = args.resolveSymbols,
+    })
+end
+
 function request.customRequestShowIntegerAsDec(req)
     response.success(req)
     mgr.workerBroadcast {

extension/script/backend/master/threads.lua

@@ -60,6 +60,9 @@ function CMD.stackTrace(w, req)
         if frame.source and frame.source.sourceReference then
             frame.source.sourceReference = (w << 32) | frame.source.sourceReference
         end
+        if frame.instructionPointerReference then
+            frame.instructionPointerReference = ("inst_%dx%s"):format(w, frame.instructionPointerReference:match("^inst_(.+)$"))
+        end
     end
     response.success(req, req.body)
 end
@@ -151,6 +154,14 @@ function CMD.writeMemory(_, req)
     response.success(req, req.body)
 end
 
+function CMD.disassemble(_, req)
+    if not req.success then
+        response.error(req, req.message)
+        return
+    end
+    response.success(req, req.body)
+end
+
 function CMD.eventMemory(w, req)
     req.memoryReference = "memory_" .. w .. "x" .. req.memoryReference
     event.memory(req)

extension/script/backend/worker.lua

@@ -13,6 +13,7 @@ local thread = require 'bee.thread'
 local fs = require 'backend.worker.filesystem'
 local log = require 'common.log'
 local channel = require "bee.channel"
+local disassemble = require 'backend.worker.disassemble'
 local initialized = false
 local suspend = false
 local info = {}
@@ -197,6 +198,12 @@ local function stackTrace(res, coid, start, levels)
         }
         if info.what ~= 'C' then
             r.column = 1
+            if rdebug.currentpc then
+                local pc = rdebug.currentpc(depth)
+                if pc >= 0 then
+                    r.instructionPointerReference = ("inst_%dx%dx%d"):format(coid, depth, pc)
+                end
+            end
             local src = source.create(info.source)
             if source.valid(src) then
                 r.line = source.line(src, info.currentline)
@@ -572,6 +579,95 @@ function CMD.customRequestShowIntegerAsHex()
     }
 end
 
+function CMD.disassemble(pkg)
+    if not rdebug.dumpproto then
+        sendToMaster 'disassemble' {
+            command = pkg.command,
+            seq = pkg.seq,
+            success = false,
+            message = "Disassemble not supported for this Lua version",
+        }
+        return
+    end
+    local proto
+    local defaultOffset = 0
+    local refId = pkg.refId
+    if type(refId) == "string" and refId:match("^%d+x%d+x%d+$") then
+        local coid, depth, pc = refId:match("^(%d+)x(%d+)x(%d+)$")
+        -- navigate to the correct coroutine
+        local L = baseL
+        for _ = 0, tonumber(coid) - 1 do
+            L = coroutineFrom(L)
+            if not L then break end
+        end
+        if L then
+            hookmgr.sethost(L)
+            proto = rdebug.dumpproto(tonumber(depth))
+            hookmgr.sethost(baseL)
+        end
+        defaultOffset = tonumber(pc)
+    end
+    if not proto then
+        local rtype, ref = variables.resolveMemoryRef(tonumber(refId))
+        if ref and rtype == "function" then
+            proto = rdebug.dumpproto(ref)
+        end
+    end
+    if not proto or not proto.code or #proto.code == 0 then
+        sendToMaster 'disassemble' {
+            command = pkg.command,
+            seq = pkg.seq,
+            success = false,
+            message = "Cannot dump function",
+        }
+        return
+    end
+    local instructions = disassemble.disassemble_function(proto, luaver.LUAVERSION)
+    local byteOffset = math.floor((pkg.offset or 0) / 4)
+    local instOffset = defaultOffset + byteOffset + (pkg.instructionOffset or 0)
+    local instCount = pkg.instructionCount or #instructions
+    local result = {}
+    local firstLocation = nil
+    if proto.source then
+        local src = source.create(proto.source)
+        if source.valid(src) then
+            firstLocation = source.output(src)
+        end
+    end
+    local start = math.max(1, instOffset + 1)
+    for i = start, math.min(start + instCount - 1, #instructions) do
+        local inst = instructions[i]
+        local r = {
+            address = inst.address,
+            instructionBytes = inst.instructionBytes,
+            instruction = inst.opName .. "  " .. inst.operands,
+        }
+        if inst.line then
+            r.line = inst.line
+            r.column = 1
+        end
+        if inst.symbol then
+            r.symbol = inst.symbol
+        end
+        if inst.presentationHint then
+            r.presentationHint = inst.presentationHint
+        end
+        if firstLocation then
+            r.location = firstLocation
+            firstLocation = nil
+        end
+        result[#result + 1] = r
+    end
+    sendToMaster 'disassemble' {
+        command = pkg.command,
+        seq = pkg.seq,
+        success = true,
+        body = {
+            instructions = result,
+        },
+    }
+end
+
 local function runLoop(reason, level)
     baseL = hookmgr.gethost()
     --TODO: 只在lua栈帧时需要text？

extension/script/backend/worker/disassemble.lua

@@ -0,0 +1,116 @@
+-- shared disassembly logic, version dispatch
+-- version is always 53/54/55 (luaver.LUAVERSION format)
+
+local modules = {}
+
+-- Lua 5.3: lineinfo stores direct line numbers
+local function get_source_line_53(func, pc)
+    if not func.lineinfo or #func.lineinfo == 0 then return nil end
+    local idx = pc + 1
+    if idx <= #func.lineinfo then return func.lineinfo[idx] end
+end
+
+-- Lua 5.4+: lineinfo stores signed byte deltas with abslineinfo anchors
+local function get_source_line_54plus(func, pc)
+    if not func.lineinfo or #func.lineinfo == 0 then return nil end
+    local basepc = -1
+    local baseline = func.linedefined or 0
+    if func.abslineinfo and #func.abslineinfo > 0 then
+        if pc < func.abslineinfo[1].pc then
+            basepc = -1
+            baseline = func.linedefined
+        else
+            local i = math.floor(pc / 128) - 1
+            if i < 1 then i = 1 end
+            while i + 1 <= #func.abslineinfo and pc >= func.abslineinfo[i + 1].pc do
+                i = i + 1
+            end
+            basepc = func.abslineinfo[i].pc
+            baseline = func.abslineinfo[i].line
+        end
+    end
+    local line = baseline
+    local cur = basepc
+    while cur < pc do
+        cur = cur + 1
+        if cur > #func.lineinfo then break end
+        local li = func.lineinfo[cur + 1]
+        if li == -128 and func.abslineinfo then
+            for j = 1, #func.abslineinfo do
+                if func.abslineinfo[j].pc > cur then
+                    cur = func.abslineinfo[j].pc
+                    line = func.abslineinfo[j].line
+                    break
+                end
+            end
+        else
+            line = line + li
+        end
+    end
+    return line
+end
+
+local function get_module(version)
+    local v = version
+    if not modules[v] then
+        if v == 53 then
+            modules[v] = require "backend.worker.disassemble.lua53"
+        elseif v == 54 then
+            modules[v] = require "backend.worker.disassemble.lua54"
+        elseif v == 55 then
+            modules[v] = require "backend.worker.disassemble.lua55"
+        end
+    end
+    return modules[v]
+end
+
+local function disassemble_function(func, version)
+    local mod = get_module(version)
+    if not mod then
+        return {}
+    end
+    local instructions = {}
+    if not func.code or #func.code == 0 then
+        return instructions
+    end
+
+    local get_line = version == 53 and get_source_line_53 or get_source_line_54plus
+    local extra_arg = mod.precompute(func)
+
+    for i = 1, #func.code do
+        local inst = func.code[i]
+        local d = mod.decode(inst)
+        local pc = i - 1
+        local opName = mod.OPCODES[d.op + 1] or ("UNKNOWN_%d"):format(d.op)
+        local operands = mod.format(d)
+        local cmt = mod.comment(opName, d, func, pc, extra_arg[pc])
+        local line = get_line(func, pc)
+        local hint = nil
+        if opName == "EXTRAARG" or opName == "VARARGPREP" then
+            hint = "invalid"
+        end
+        local r = {
+            pc = pc,
+            opName = opName,
+            operands = operands,
+            comment = cmt,
+            line = line,
+            address = ("0x%08X"):format(pc),
+            instructionBytes = ("%08X"):format(inst & 0xFFFFFFFF),
+        }
+        if hint then
+            r.presentationHint = hint
+        end
+        if mod.symbol then
+            local s = mod.symbol(func, pc, d)
+            if s then r.symbol = s end
+        end
+        instructions[#instructions + 1] = r
+    end
+    return instructions
+end
+
+return {
+    disassemble_function = disassemble_function,
+    get_source_line = get_source_line,
+}