LUDE Plugin SDK

为 LiquidUnifiedDebugEngine 开发调试器适配插件。

插件是什么

一个插件目录包含 3 类文件，描述如何将调试语义命令翻译为特定调试器协议：

my-adapter/
├── Config.json               # 插件元信息 + 变量 + 环境检测 + 命令序列
├── CommandTransform.json     # 语义命令 → 调试器协议模板映射
└── scripts/                  # Lua 数据转换脚本
    ├── execution.lua         # 执行控制响应处理
    ├── events.lua            # 调试器事件处理
    ├── stack.lua             # 堆栈查询响应
    └── inspect.lua           # 变量/表达式查询响应

5 分钟上手

# 1. 复制模板工程
cp -r examples/template-adapter examples/my-adapter

# 2. 打开 REPL 离线测试
python3 tools/plugin_sim.py --plugin examples/echo-adapter

# 3. 查看其他示例（参考实现）
ls examples/echo-adapter      # 测试用，最小完备
ls examples/c-cpp-adapter     # GDB MI3 适配
ls examples/python-adapter    # pdb 适配

配置文件

Config.json

{
  "meta": {
    "name": "echo-adapter",
    "version": "1.0.0",
    "language": []
  },
  "variables": {                  // 可展开模板变量
    "echo_prefix": "echo"
  },
  "prepare": [                    // 插件加载时执行的环境检测
    { "command": "echo ready", "required": true }
  ],
  "launch": {                     // 自定义动作段（可被 pre_action 引用）
    "command": "{$VAR:echo_prefix} setup"
  },
  "sequences": []                 // 预定义命令序列
}

CommandTransform.json

将引擎语义命令映射为调试器协议命令：

{
  "commands": {
    "run": {
      "template": "{$VAR:echo_prefix} run",          // 原生命令模板
      "response_handler": "scripts/execution.lua",   // 响应处理脚本
      "pre_action": "launch",                        // 前置动作（可选）
      "timeout_ms": 3000
    },
    "locals": {
      "template": "{$VAR:echo_prefix} locals",
      "response_handler": "scripts/inspect.lua"
    }
  },
  "events": {
    "stopped": "scripts/events.lua"
  }
}

支持的语义命令

引擎提供以下标准语义命令，插件必须映射：

语义命令	说明
run	启动调试
continue	继续执行
next	单步跳过
step	单步进入
finish	跳出当前函数
pause	暂停执行
stop	停止调试
break	设置断点 (变量: location)
delete_breakpoint	删除断点 (变量: location)
locals	查询局部变量
threads	查询线程列表
backtrace	查询调用栈
print	表达式求值 (变量: expr)

模板变量

模板中的 {$VAR:name} 由引擎在运行时统一展开。变量来源于两个渠道：

渠道 1: Config.json 全局变量 — 所有命令共享

{
  "variables": {
    "debugger_bin": "gdb",           // 调试器命令
    "debugger_type": "gdb/mi",       // 调试器协议
    "target": "/tmp/a.out"           // 目标程序路径
  },
  "prepare": [
    { "command": "{$VAR:debugger_bin} --version", "required": true }
  ]
}

Config.json 的 variables 节定义所有全局可展开变量。prepare 命令和 CommandTransform.json 模板中均可使用 {$VAR:name} 引用。

渠道 2: API 调用参数 — 单次调用传入

// 引擎调用 engine_core_set_breakpoint("main.c:10")
// 模板中自动获得 {$VAR:location} = "main.c:10"
"break": {
  "template": "-break-insert {$VAR:location}"
}

以下变量由 API 调用自动注入：

命令	注入变量	示例值
break	{$VAR:location}	"main.c:10"
delete_breakpoint	{$VAR:location}	"main.c:10"
print	{$VAR:expr}	"i+j"

条件展开: {$VAR:name=val?then/else} 实现多调试器适配

// 根据 debugger_type 选择不同调试器命令
"template": "{$VAR:debugger_type=gdb/mi?-exec-run/run}"
// debugger_type=gdb/mi → -exec-run
// debugger_type=pdb    → run

运算符: =, !=, >, <, >=, <=。数值优先比较，回退字符串。

Lua 脚本

插件脚本用 Lua 编写，负责将调试器原始输出转换为结构化 JSON。

输入

引擎传入 JSON 字符串（脚本从 ... 读取）：

{
  "raw_data": "echo run",
  "current_state": "IDLE",
  "is_response": true,
  "pending_seq": 42
}

解析示例:

local input = require("input")
local parsed = input.parse(...)

输出

脚本返回 JSON 字符串：

{
  "structured_json": { "type": "execution_result", "data": {"status": "ok"} },
  "has_state_change": false,
  "proposed_state": null,
  "stop_reason": null
}

共享模块

local json = require("json")    -- JSON 编解码
local input = require("input")  -- 引擎输入解析

调试与打包

# 列出所有命令模板
python3 tools/plugin_pack.py expand examples/echo-adapter list

# 测试单条命令展开
python3 tools/plugin_pack.py expand examples/echo-adapter run
python3 tools/plugin_pack.py expand examples/c-cpp-adapter run -s debugger_type=lldb

# 校验并打包
python3 tools/plugin_pack.py pack examples/echo-adapter --validate

# 离线 REPL（交互式开发）
python3 tools/plugin_sim.py --plugin examples/echo-adapter

插件发布

# 打包为 .zip 分发包
python3 tools/plugin_pack.py pack examples/my-adapter --validate -o plugins/my-adapter.zip

示例插件

插件	适配调试器	协议
echo-adapter	echo 命令	- (测试/学习)
c-cpp-adapter	GDB	MI3
python-adapter	Python pdb	pdb
template-adapter	(模板)	- (开发起点)