Files
LN-Code-Editor/LSP_DEBUG_GUIDE.md
2026-09-17 16:32:27 +08:00

7.4 KiB
Raw Permalink Blame History

LSP 服务启用与全链路 Debug 打点排查手册

为了彻底排查后台 clangd 等语言服务器为何未启用、未响应或未触发补全,我们在整个 LSP 的生命周期、配置匹配、进程拉起、通信协议与补全调度推流各个核心节点注入了全套 [LSP-DEBUG] 追踪日志。


1. Debug 打点分布位置一览表

序号 链路阶段 文件路径 方法 / 代码行位置 关键调试内容
1 编辑区生命周期 lib/widgets/code_editor_widget.dart _loadFileContent
_onTextChanged
打印当前打开文件绝对路径、工程根目录、文件内容长度,及文件修改事件
2 协调器分发 lib/widgets/editor/editor_lsp_coordinator.dart onFileOpened
onFileChanged
打印协调器分发状态、查询是否存在存活会话、是否进入本地词法诊断兜底
3 配置匹配与进程拉起 lib/services/lsp/lsp_manager.dart getOrCreateSession
_startSession
getExistingSession
onFileOpened
1. 打印扩展名与配置匹配结果
2. 打印 Ubuntu 引擎安装检测结果
3. 打印命令(clangd)安装检测结果
4. 打印拼装的 PRoot 容器完整命令行
5. 打印子进程 PID 或拉起异常
6. 打印 session.initialize() 握手结果
4 会话与协议层 lib/services/lsp/lsp_session.dart initialize
didOpen
didChange
getCompletions
1. 打印 initialize 请求入参与回包类型
2. 打印 textDocument/didOpen 映射的容器内部 guestUri
3. 打印 textDocument/didChange 防抖触发与版本号
4. 打印 textDocument/completion 耗时与回包条数
5 Stdio 底层通讯 lib/services/lsp/lsp_client.dart sendRequest
sendNotification
_dispatchMessage
_handleStderrData
1. 打印发往 clangd 的 Request/Notification 方法名与 ID
2. 打印收到的 Response 结果或 JSON-RPC 错误码
3. 打印 clangd 进程输出的所有 stderr 原始日志
6 补全提供者 lib/services/code_completion/providers/lsp_completion_provider.dart provideCompletions 打印收到的补全触发字符、光标行列号、当前 session 存活与初始化状态、后端返回的语义补全条数
7 补全调度流水线 lib/services/code_completion/core/completion_engine.dart requestCompletions 打印当前激活的 Providers 列表、同步候选数、异步 Provider 调用耗时、聚合条数与向 UI 推流事件

2. 日志前缀说明与标准排查轨迹

所有调试日志均统一带有 [LSP-DEBUG] 前缀,方便通过关键字高亮或过滤:

# 在终端中仅查看 LSP 调试信息(Windows PowerShell)
flutter run | Select-String "\[LSP-DEBUG\]"

# 或在 Android 设备上使用 adb logcat 过滤
adb logcat | grep -E "\[LSP-DEBUG\]|flutter"

正常工作时的完整日志时序:

[LSP-DEBUG][Editor] 磁盘冷加载读取文件成功,通知 LSP 打开: path=/sdcard/.../main.c, rootPath=/sdcard/...
[LSP-DEBUG][Coordinator] onFileOpened 被触发: filePath=/sdcard/.../main.c
[LSP-DEBUG][Manager] onFileOpened 被触发: filePath=/sdcard/.../main.c
[LSP-DEBUG][Manager] getOrCreateSession 触发: filePath=/sdcard/.../main.c, ext=.c
[LSP-DEBUG][Manager] 匹配配置结果: config=c_cpp, name=C / C++, enabled=true, serverCommand=clangd
[LSP-DEBUG][Manager] 开始创建并拉起新会话: configId=c_cpp
[LSP-DEBUG][Manager] 检查 Ubuntu 引擎安装状态: isEngineInstalled=true
[LSP-DEBUG][Manager] 检查命令安装状态 (clangd): isCommandInstalled=true
[LSP-DEBUG][Manager] 准备执行拉起命令: /data/user/0/.../libproot.so ... clangd --background-index
[LSP-DEBUG][Manager] 语言服务子进程已启动, PID: 12345
[LSP-DEBUG][Manager] 正在进行 session.initialize() 握手...
[LSP-DEBUG][Client] 发送 Request: id=1, method=initialize, timeout=10s
[LSP-DEBUG][Client] 收到 Request 响应: id=1, hasError=false
[LSP-DEBUG][Session] 语言服务初始化成功并发送 initialized 通知: C / C++ (clangd)
[LSP-DEBUG][Manager] session.initialize() 结果: success=true
[LSP-DEBUG][Manager] 会话拉起成功并缓存: configId=c_cpp
[LSP-DEBUG][Manager] onFileOpened 正在调用 session.didOpen
[LSP-DEBUG][Session] 发送 textDocument/didOpen: filePath=/sdcard/.../main.c -> uri=file:///...
[LSP-DEBUG][Client] 发送 Notification: method=textDocument/didOpen

# 当你在编辑器中键入字符(如 pri)时:
[LSP-DEBUG][Engine] requestCompletions 触发: input="pri", providers=[lsp(async=true)]
[LSP-DEBUG][Engine] 启动异步请求: requestId=1, asyncProviders=[lsp]
[LSP-DEBUG][Engine] 正在调用异步 Provider: lsp
[LSP-DEBUG][Provider] 收到 LSP 补全请求: input="pri", line=3, col=4
[LSP-DEBUG][Provider] 查询会话结果: session=true, isInitialized=true, isClosed=false
[LSP-DEBUG][Session] getCompletions: ... line=3, col=4
[LSP-DEBUG][Client] 发送 Request: id=2, method=textDocument/completion
[LSP-DEBUG][Client] 收到 Request 响应: id=2, hasError=false
[LSP-DEBUG][Session] 解析 CompletionList items 成功, 条数: 15
[LSP-DEBUG][Provider] session.getCompletions 耗时: 38ms, 返回条数: 15
[LSP-DEBUG][Engine] 聚合所有异步结果数: 15
[LSP-DEBUG][Engine] 合并后过滤展示条数: 15, 准备推流至 ValueNotifier
[LSP-DEBUG][Engine] ValueNotifier 推流成功!

3. 常见断点排查指南

现象 / 日志断点 发生点 真正原因与对策
[Manager] 未找到匹配配置或配置已被禁用 LspManager.getOrCreateSession 检查配置管理中该语言扩展名(如 .c)是否已配置并处于启用状态。
[Manager] 阻断: Ubuntu 引擎未安装 LspManager._startSession InternalEngineService.isEngineInstalled() 为 false。说明 App 尚未解压容器运行环境。
[Manager] 阻断: 服务命令未在引擎中检测到: clangd LspManager._startSession isCommandInstalled('clangd') 判定失败。说明容器环境中 command -v clangd 未输出 CE_OK,需确认容器中 clangd 是否已配置在 PATH 路径下。
[Manager] 语言服务子进程已启动, PID: xxx 紧接着进程退出 LspClient 进程退出: xxx 关注 [LSP-DEBUG][Stderr] 打印的原始错误(如缺失共享库 libc++.so、权限被拒、参数不支持等)。
[Client] Request 超时失败: method=initialize LspClient.sendRequest clangd 启动后挂起,未能在 10 秒内应答 initialize 请求。通常是 PRoot 路径映射或 stdin 管道堵塞。
[Provider] 会话不存在或未完成初始化 LspCompletionProvider.provideCompletions 说明输入时,前面的文件打开握手尚未完成,或拉起失败导致 session 为 null。