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

现象:编辑器 / 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

+7 -5
View File
@@ -47,9 +47,11 @@ def test_load_table_maps_na_like_tokens_to_nan(tmp_path):
p = tmp_path / "na.csv"
p.write_text("a,b,c\n1,NA,\n2,-,#N/A\n", encoding="utf-8")
df = load_table(p)
assert df["b"].isna().all()
assert df["c"].isna().all()
assert df["a"].notna().all()
# 外面套 bool():df["b"] 的类型是 Series | DataFrame,直接当条件用 pyright 会报
# "条件操作数无效";套上 bool() 既满足类型检查,又能在它真返回 Series 时当场炸掉。
assert bool(df["b"].isna().all())
assert bool(df["c"].isna().all())
assert bool(df["a"].notna().all())
def test_load_table_respects_explicit_encoding(tmp_path):
@@ -102,7 +104,7 @@ def test_save_table_rejects_non_dataframe(tmp_path):
from mcm_toolkit.data import save_table
with pytest.raises(TypeError):
save_table([1, 2, 3], tmp_path / "bad.csv")
save_table([1, 2, 3], tmp_path / "bad.csv") # type: ignore[arg-type] # 就是要传错
def test_save_table_validates_before_touching_disk(tmp_path):
@@ -112,7 +114,7 @@ def test_save_table_validates_before_touching_disk(tmp_path):
with pytest.raises(ValueError, match=r"\.txt"):
save_table(pd.DataFrame({"a": [1]}), tmp_path / "d1" / "x.txt")
with pytest.raises(TypeError):
save_table([1, 2, 3], tmp_path / "d2" / "x.csv")
save_table([1, 2, 3], tmp_path / "d2" / "x.csv") # type: ignore[arg-type] # 就是要传错
assert sorted(p.name for p in tmp_path.iterdir()) == []