fix(env): 钉死 pyright 的分析目标，修掉"无法解析导入 numpy/pandas"

0 Fork 0

现象：编辑器 / pyright 满屏 reportMissingImports，但 .venv 与 conda 环境里
import numpy, pandas 都正常，pytest 也全过。

根因两层：

1. pyright 没配 venvPath / pythonPath 时会去 PATH 上找 python。本机 PATH 上
   唯一的 python 是 agent-tools 的 shim（Codex 运行时，Python 3.14），没有科学栈。
   pyright --verbose 显示它选了 3.14.6，Search paths 里一个 Anaconda 路径都没有。
   注意持久化的 User/Machine PATH 并没有这一项，是 Codex 进程临时注入的——所以
   "我的终端没问题"和"工具有问题"可以同时成立。
2. .venv 是 --system-site-packages 建的，三方包在 D:\anaconda\Lib\site-packages，
   而 pyright / Pylance 不认 pyvenv.cfg 的 include-system-site-packages，
   只去 .venv\Lib\site-packages 找（那里只有 pip）。
   pyright 不读 pyvenv.cfg，但**认 .pth**。

改动：
- pyproject.toml [tool.pyright]：venvPath = "." / venv = ".venv" /
  pythonVersion = "3.13"，并注释了为什么必须写
- scripts/setup-venv.ps1：新增第 [2/4] 步，自动往 .venv 写
  _mcm_base_site_packages.pth 指向该机 base 的 site-packages，换机重建即可
- tests/test_data.py：3 处 isna().all() 断言外面套 bool()（它的类型是
  Series | bool，直接当条件 pyright 报"条件操作数无效"）；
  2 处故意传错类型的用例加 type: ignore[arg-type]

结果：pyright 17 errors -> 0 errors / 0 warnings；pytest 两套环境均
40 passed, 44 skipped；ruff All checks passed；setup-venv.ps1 通过 AST 解析
（纯 ASCII + LF）。

文档：docs/04-environment.md 新增坑 7（含 pyright --verbose 诊断口诀与
VS Code / PyCharm 的操作步骤）、STATUS 决策 29、CHANGELOG。

This commit is contained in:

guzhujushi committed 2026-10-02 13:36:16 +08:00

1 parent 6758e81c9d

commit 97a2f95066

6 files changed

+107 -9

No files matched your search

									
										pyproject.toml
									
		+7
		
												View File
												
				@@ -62,3 +62,10 @@ filterwarnings = ["error::RuntimeWarning"]

				[tool.pyright]

				include = ["src", "tests"]

				typeCheckingMode = "basic"

				# 不写 venvPath/venv 的话，pyright 会去 PATH 上找 python；本机 PATH 上的

				# python 是 agent-tools 的 shim（Codex 运行时，Python 3.14，没有 numpy/pandas），

				# 于是全部报 "无法解析导入 numpy/pandas"。指到工作区的 .venv 才稳定。

				venvPath = "."

				venv = ".venv"

				# 与两套环境一致（venv 3.13.9 / conda 3.13.15）；不写会跟着 PATH 上那个 3.14 走。

				pythonVersion = "3.13"