SuperAPI AI 工具集

repair-opencode-kilo-python-lsp-diagnostics

编程与开发

查看项目

更新于 10-16 04:55

技能介绍

用途:仅针对 Kilo 与 opencode(两者共用同一内核),解决编辑工具在读写 Python 文件时内置 LSP 报出第三方库无法解析的问题,例如 Import "fastapi" could not be resolved from source、Import "pytest" could not be resolved。这些报错来自代理运行框架的 LSP,而非代码本身,代码可能完全正常。不适用于 Claude Code、Codex 等其它代理。

根因:Kilo/opencode 把 venv 解释器作为顶层 initialization.pythonPath 传入,但 pyright 只从 python.pythonPath 或 [tool.pyright] 配置段读取 venv,于是回退到系统 Python,无法解析仅存在于项目 venv 中的第三方导入;内置模块与本地导入仍可解析。

配置段规则:pyright 与 basedpyright 都读取 [tool.pyright],basedpyright 还额外读取 [tool.basedpyright]。同一配置文件只允许存在二者之一,同时存在不被支持,故 [tool.pyright] 是通用规范段。

修复步骤:先安装依赖使 venv 含第三方包,执行 uv sync --all-groups;再用命令行校验以排除代码问题,执行 uv run basedpyright(或 uv run pyright)。若 CLI 干净而编辑工具 LSP 仍报未解析,则问题在 LSP 配置。随后修改 pyproject.toml,最终只保留单个 [tool.pyright] 段:若存在 [tool.basedpyright],将其改名为 [tool.pyright],键值保持不变;若两者都不存在,则添加 [tool.pyright] 并写入 venvPath = "." 与 venv = ".venv"。相对路径相对配置文件(项目根)解析,因此对全体开发者通用。不需要等待会话重载,正常完成任务即可;该修复仅在会话重启后于 LSP 生效,最终消息里说明已修复 LSP 配置并建议用户重启会话或聊天。

注意:切勿在同一配置文件中同时保留 [tool.pyright] 与 [tool.basedpyright],应改名而非新增第二段。若项目已存在正确的单一 [tool.pyright] 段且处于新会话,编辑工具 LSP 的“未解析”报告属已知误报,可忽略。修复位于仓库内且与机器无关,不要把机器相关的绝对路径写进仓库。

验证:干净的命令行 uv run basedpyright 结果加编辑工具 LSP 未解析导入,即判定为 LSP 配置问题并应用修复;修复后重跑 uv run basedpyright 确认仍然干净,因两个工具都读取 [tool.pyright] 段;LSP 只有在用户重启会话后才会干净,需在最终消息中说明。