guzhujushi
97a2f95066
现象：编辑器 / 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。
文档索引
本目录是 MCM/ICM Toolkit 的需求、架构、方案与开发规范的唯一落盘处。
| 文档 | 内容 |
|---|---|
| 01-suggestion-review.md | 对 ChatGPT 建库建议的审查与精简：留什么、砍什么、补什么 |
| 02-architecture.md | 精简后的包结构、边界划分、统一接口约定 |
| 03-roadmap.md | 功能清单分级（L0 / L1 / L2 / 不做）与开发纪律 |
| 04-environment.md | conda / venv 环境配置、镜像、离线约束 |
| dev/function-card-template.md | S 档算法的「函数卡片」模板 |
| 05-git-workflow.md | Git 工作流、Gitea 远程（SSH 走 Tailscale）、行尾策略 |
| dev/personal-pitfalls.md | 个人易错点清单：只追加，追加前不通读 |
阅读顺序
- 先读
01-suggestion-review.md—— 它决定后面所有事。 - 再读
02-architecture.md—— 它决定代码往哪写。 - 开工前读
03-roadmap.md的对应条目 —— 它决定这次做什么、做到什么程度。 - 环境出问题看
04-environment.md。
项目级进度看根目录的
STATUS.md；本目录只放不会频繁变的内容。