cli-anything-lldb 深度指南用 LLDB Python API 打造 Agent 原生调试 CLI、持久会话与 DAP 服务【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anythingcli-anything-lldb 是 CLI-Anything 项目为 LLDB 调试器提供的 Agent 化接入层它绕开脆弱的lldb -b -o ...子进程文本解析直接通过 LLDB 官方 Python APIimport lldb驱动真实调试器。本文将以 LLDB 接入包 README 为骨架系统讲解其 JSON CLI 工作流、跨进程持久会话守护进程、以及面向编辑器和 AI 调试客户端的 stdio Debug Adapter ProtocolDAP服务并对照仓库源码解释底层实现。读完本文你将掌握如何让 Agent 用一条条独立命令驱动同一个活的 LLDB 会话完成建目标、起进程、下断点、观察变量与表达式求值也能在复杂 GUI 调试场景中配置停止规则自动跳过内部陷阱断点。一、包概览两个面向 Agent 的入口该包对外暴露两个可执行入口二者由 setup.py 中的console_scripts注册包名cli-anything-lldb版本1.0.0要求 Python 3.10依赖click8.0与prompt-toolkit3.0入口定位cli-anything-lldbJSON CLI / REPL 工作流配合一个常驻的持久会话守护进程daemoncli-anything-lldb-dap标准 stdio Debug Adapter Protocol 服务面向编辑器与 AI 调试客户端在设计上二者共享同一个核心会话封装 core/session.pyLLDBSession因此无论是命令行的逐步操作还是 DAP 的协议化请求最终都收敛到同一套 LLDB Python API 调用。1.1 安装cd lldb/agent-harness pip install -e .1.2 LLDB 前置条件与 Python 绑定自动发现本包要求系统里存在可用的 LLDB 及其 Python 绑定# macOS xcode-select --install # Ubuntu sudo apt install lldb python3-lldb # Windows winget install LLVM.LLVM安装后需确保lldb位于PATH。harness 会通过lldb -P自动发现 LLDB 的 Python 绑定目录。这一机制的具体实现见 utils/lldb_backend.py先尝试直接import lldb失败时运行lldb -P拿到 LLDB Python 模块目录把发现的目录插入sys.path头部重试导入。若lldb不在 PATH代码会抛出包含安装提示macOS/Ubuntu/Windows 三套命令的RuntimeError若绑定目录存在但导入仍失败则提示检查 LLDB 与当前 Python 版本的兼容性。二、快速上手JSON CLI 工作流--json是 Agent 工作流的标配开关。所有核心操作都会返回结构化字典可直接被 Agent 消费# Show help cli-anything-lldb --help # Create a target cli-anything-lldb --json target create --exe /path/to/executable # Launch process cli-anything-lldb --json process launch --arg foo --arg bar # Stop at process entry before user code cli-anything-lldb --json process launch --stop-at-entry # Set breakpoint by function cli-anything-lldb --json breakpoint set --function main # Pending breakpoints are explicit cli-anything-lldb --json breakpoint set --function PluginEntry --allow-pending # Continue and inspect cli-anything-lldb --json process continue cli-anything-lldb --json process interrupt cli-anything-lldb --json thread backtrace cli-anything-lldb --json frame locals # Evaluate expression cli-anything-lldb --json expr argc # Close the persistent session when you are done cli-anything-lldb --json session close # Start REPL (default mode) cli-anything-lldb在根命令层面还支持另外两个全局开关见 lldb_cli.py--debug在出错时展示完整 traceback--session-file用于指定持久会话状态文件路径。--json模式下错误会以{error: ..., type: ...}的 JSON 结构输出并以退出码 1 结束非 JSON 模式则抛出ClickException。三、命令组全景与参数细节README 归纳了完整的命令组。结合 lldb_cli.py 中的 Click 参数定义各命令组的可用参数如下命令组子命令关键参数来自源码targetcreate,infocreate --exe 路径必填与可选--archprocesslaunch,attach,continue,interrupt,detach,infolaunch支持--arg可重复、--env KEYVALUE可重复、--cwd、--stop-at-entryattach支持--pid、--name、--wait-for按名挂接并等待进程出现breakpointset,list,delete,enable,disableset支持--file/--line或--function、--condition、--allow-pendingdelete/enable/disable均需--idthreadlist,select,backtrace,infoselect --idbacktrace --limit默认 50frameselect,info,localsselect --indexstepover,into,out—exprexpression直接传入要求值的表达式memoryread,findread --address --size地址支持0x十六进制find needle --start addr --size 字节coreloadload --path 核心转储sessioninfo,close会话生命周期管理dap—运行 DAP 服务见下文支持--log-file与--profilerepl—交互式 REPL无子命令时默认进入值得注意的底层细节来自 core/session.pyprocess launch实际通过SBLaunchInfo设置工作目录缺省为os.getcwd()、环境变量与eLaunchFlagStopAtEntry启动标志每个命令组都有前置守卫target系列要求已有 targetprocess、thread、frame、step、expr、memory系列则要求已有 process否则返回明确的引导性错误例如 No target. Run: target create --exe所有返回值都是纯字典进程信息含pid/state/num_threads/selected_thread_id/stop/exit_status停驻信息含reason/description/hit_breakpoint_ids/frame变量含name/type/value/summary/num_children表达式结果含type/value/summary/error——与 LLDB 后端笔记 LLDB.md 描述的数据模型完全对应可直接映射为--json输出。四、持久会话让多条独立命令共享同一个调试器状态非 REPL 命令会自动共享一个持久 LLDB 会话因此target create、breakpoint set、process launch及后续检查命令可以在多次独立 CLI 调用之间作用于同一个活着的调试器状态这正是 Agent 以一条命令一步操作方式驱动调试的关键。4.1 会话状态文件与发现顺序默认会话状态文件存放在按用户划分的应用目录而非全局临时目录。文件路径解析逻辑见 utils/session_client.py优先级为--session-file显式参数环境变量CLI_ANYTHING_LLDB_SESSION_FILE自动生成以会话作用域CLI_ANYTHING_LLDB_SESSION_SCOPE或当前工作目录的绝对路径做 SHA-256取前 12 位作为文件名session-digest.json根目录为默认会话目录。默认会话根目录在不同平台不同default_session_root()优先CLI_ANYTHING_LLDB_SESSION_DIRWindows 使用LOCALAPPDATA/APPDATA下的cli-anything-lldb/sessions类 Unix 系统优先XDG_RUNTIME_DIR/cli-anything-lldb否则退回~/.cache/cli-anything-lldb/sessions。当 Agent 需要显式、确定的会话路径时应使用--session-file或CLI_ANYTHING_LLDB_SESSION_FILE任务结束时执行session close。4.2 守护进程协议与安全模型从源码可以看到会话由后台 RPC 守护进程承载utils/session_server.py客户端RemoteLLDBSessionProxy按需自动拉起python -m cli_anything.lldb.utils.session_server --state-file path随后通过localhost JSON socket 协议通信帧格式为 4 字节大端长度前缀 JSON 载荷单条消息上限 1 MiB安全措施到位32 字节随机 token 做 HMAC 常量时间比对hmac.compare_digest状态文件以0600权限、原子写入临时文件 os.replace目录以0700创建读取前校验文件属主为当前用户且无过宽权限服务器端维护一张方法白名单_ALLOWED_SESSION_METHODS只允许target_*、launch/attach/detach、breakpoint_*、step_*、continue_exec/interrupt*、threads/thread_select、frame_*、evaluate、read_memory/find_memory、load_core等调试器原语杜绝任意方法反射调用空闲超时默认 300 秒可用环境变量CLI_ANYTHING_LLDB_IDLE_TIMEOUT调整超时或收到shutdown后守护进程销毁 LLDB debugger 并清理状态文件。4.3 Pending 断点必须显式声明默认情况下若 LLDB 创建的断点没有任何已解析位置pendingbreakpoint set会直接失败。只有目标或符号预期稍后才加载时才应通过--allow-pending放行。对应的强制逻辑在 core/session.py当breakpoint_set检测到resolved False且未传allow_pending时会先删除该断点再抛出错误提示Pass allow_pendingTrue or use the CLI --allow-pending flag if a pending breakpoint is intended。断点载荷包含id/hits/locations/resolved/location_details/enabled/condition其中location_details逐条给出断点位置的address/file/line/column/function/enabled/hit_count——这样 Agent 就能判断某个停驻是否真的可到达。五、Debug Adapter Protocol编辑器与 AI 调试客户端的正式协议入口DAP 服务让客户端获得真正的调试适配器生命周期而非一条条 shell 命令。启动方式有两种等价形式cli-anything-lldb-dap cli-anything-lldb-dap --profile /path/to/stop-rules.json或通过 CLI 便捷子命令cli-anything-lldb dap cli-anything-lldb dap --profile /path/to/stop-rules.jsondap子命令还接受--log-file path将适配器诊断写入文件见 lldb_cli.py。5.1 协议纪律与单会话模型实现位于 dap.py。要点包括DAP 服务器只拥有一个进程内的LLDBSessionstdout 上只写 DAP 帧Content-Length头 JSON body见encode_messageDAPlaunch时对被调试进程的 stdout/stderr 做抑制AddSuppressFileAction确保调试器子进程的输出不会污染协议流。5.2 支持的请求生命周期initialize,launch,attach,configurationDone,disconnect断点setBreakpoints,setFunctionBreakpoints检查threads,stackTrace,scopes,variables,setVariable,evaluate执行控制continue,pause,next,stepIn,stepOut进阶source,loadedSources,readMemory,modules,exceptionInfo,disassembleinitialize响应中声明的能力包括supportsConfigurationDoneRequest、supportsFunctionBreakpoints、supportsSetVariable、supportsDisassembleRequest、supportsLoadedSourcesRequest、supportsReadMemoryRequest、supportsModulesRequest、supportsExceptionInfoRequest等。这些能力的每一条都能在 core/session.py 找到对应实现如read_memory返回十六进制数据、disassemble用target.ReadInstructions反汇编、loaded_sources遍历模块的编译单元去重、modules报告模块加载地址与符号状态。断点语义上launch 时期未解析的断点会以verified: false返回并在 launch 之后若 LLDB 成功解析则通过breakpoint事件更新。variables对结构体/类/数组返回可展开的子引用variablesReferencesetVariable在 LLDB 允许赋值时能够更新已停驻栈帧的局部变量或子成员值set_local_variable/set_child_value。5.3 长时间运行 GUI 目标的并发模型针对长时间运行的 GUI 调试目标DAP 层做了专门的并发处理continue请求在阻塞式SBProcess.Continue()完成前就先行应答随后在后台线程中等待下一次 stop_continue_until_stoppause使用SBProcess.SendAsyncInterrupt()让适配器在 debuggee 运行期间保持响应若continue进行中收到setBreakpoints/setFunctionBreakpoints适配器会先请求异步中断并等待 continue 线程观察到 stopped 状态之后才修改 LLDB 断点_ensure_stopped_for_target_mutation若进程未在超时窗口内停住超时 10 秒请求会明确失败而不是挂死 DAP 主循环。5.4 停止规则Stop Rules驯服嘈杂的 GUI 调试目标launch和attach接受非标准的停止规则控制项用于过滤 GUI 程序启动过程中的内部噪音autoContinueInternalBreakpoints兼容开关启用后会自动内置 NVIDIA__jit_debug_register_code/jit-debug-register以及 Windowsntdll.dllDbgBreakPointException 0x80000003的跳过规则内置规则定义见 dap.pystopRules内联结构化规则可选字段为name、actionstop或continue、origin、reason、module、function、regex。每条规则必须至少包含一个匹配器reason/module/function/regex 四者其一防止一个配置文件意外把每次 stop 都归类掉stopRuleProfile/stopProfile/profile为该次 launch/attach 请求加载的外部 JSON profile 路径。DAP 进程本身也接受--profile在启动时加载一个基础 profile。profile 是如下形式的 JSON 对象{ autoContinueInternalBreakpoints: true, stopRules: [ { name: c4d-nvidia-jit, action: continue, origin: internalTrap, module: nvgpucomp64.dll, function: __jit_debug_register_code } ] }规则解析StopRule.from_mapping会做防御性校验action只能是stop/continueregex必须能编译且必须提供 reason/module/function/regex 至少一个。匹配时支持模块名的 basename 比对、函数符号后缀::func或func容错与忽略大小写的正则扫描。基础 profile 与每次 launch/attach 的 profile、内联规则按序叠加合并。每个 DAPstopped事件都会携带body.cliAnythingStop字段其中包含originmanualPause用户主动暂停、internalTrap被规则识别为内部陷阱并归因或debuggee正常调试事件LLDB stop reasonlldbReasonmodule / modulePath / function / frame 元数据命中规则时附上matchedRule含 name/action/origin/source。注意运行中的cli-anything-lldb-dap进程不会热加载代码或 profile 变更——要让新规则生效需重启适配器并重新 attach/launch 目标。5.5 内存扫描的工程约束memory find以64 KiB 为分块执行分段扫描每次调用最多扫描1 MiB常量见 core/session.py校验见find_memory实现。分块时通过保留len(needle)-1字节的尾随重叠区来防止 needle 跨块漏检一旦命中即返回found: true与命中地址。六、会话生命周期与资源清理语义LLDBSession构造时会完成SBDebugger.Initialize()、SBDebugger.Create()并设置SetAsync(False)——同步模式保证每条命令的确定性行为这也是 LLDB.md 记录的既定会话生命周期策略。会话还跟踪_process_originlaunched/attached/core销毁时据此选择正确收尾方式见 core/session.pyattached来源 → 先Detach()launched来源且进程仍处于非 detached/exited 状态 →Kill()最后SBDebugger.Destroy()SBDebugger.Terminate()。REPL 模式无子命令时的默认入口会启动一个带 banner/help/上下文提示显示当前是 active 还是 target 状态的prompt-toolkit交互环境内部把每行输入shlex.split后重新路由回同一套 Click CLI保证 REPL 与命令行行为完全一致。七、测试与验证仓库测试位于 lldb/agent-harness/cli_anything/lldb/testscd lldb/agent-harness pytest cli_anything/lldb/tests/test_core.py -v pytest cli_anything/lldb/tests/test_full_e2e.py -v pytest cli_anything/lldb/tests -q其中test_core.py 是基于 mock 的单元测试无需真实安装 LLDB覆盖 JSON 输出工具、错误处理--debug开关下才返回 traceback、会话客户端 RPC 等模块测试内通过CLI_ANYTHING_FORCE_INSTALLED1可强制使用已安装的命令而非python -m模块调用E2E 测试需要可用的 C 编译器clang、gcc或cc以便现场构建一个小型调试辅助程序默认测试套件无需额外环境变量LLDB_TEST_CORE可选用于把 core-load 的负路径检查指向一个特定的本地文件memory find的扫描行为分块、1 MiB 上限同样有测试约束。八、配套资源与延伸阅读skills/SKILL.md技能定义文件随包发布列出能力清单与快速命令是 Agent 直接消费的入口描述LLDB.md后端设计笔记解释了为何采用import lldb原生集成避免解析lldb -b -o ...子进程输出的脆弱文本并记录了当前限制暂无高级 watchpoint、内存搜索为范围抓取后的分块扫描、单活动 target/会话模式包级可发布技能汇总可参考 skills/cli-anything-lldb/SKILL.md。结语cli-anything-lldb 展示了Agent 原生调试接入的完整形态纯字典 JSON 的结构化输出让机器可解析跨进程持久会话守护进程让独立命令共享一个真实调试器状态stdio DAP 服务则让现有编辑器生态和 AI 调试客户端能以标准协议直接复用 LLDB 的全部能力。配合显式化的 pending 断点策略与可编程的停止规则它既适合脚本化/Agent 化调试也足以应对 GUI 程序等嘈杂目标的复杂停驻场景。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考