公共工具模块需规范命名、分文件管理、显式导出接口；类型提示须与运行时校验一致；禁用裸print和basicConfig，统一日志配置；路径操作一律用pathlib.Path；测试覆盖多平台。
模块命名和 __init__.py 暴露逻辑混乱
公共工具模块一旦被多个项目依赖，名字就不是“起得顺口”就行——它会直接决定别人怎么 import、怎么补全、怎么查文档。常见错误是把所有函数塞进 utils.py，再在 __init__.py 里写一堆 from .xxx import *，结果用户一导入就污染命名空间，dir(myutils) 返回二十个看不出来源的函数。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 按职责分文件：比如
str_utils.py、file_utils.py、time_utils.py，不追求“一个模块管所有” -
__init__.py只显式导出稳定接口：from .str_utils import safe_join, truncate，不写import * - 加
__all__ = ["safe_join", "truncate"]控制from myutils import *的行为 - 避免用
utils这种泛名作包名——别人pip install utils会撞上 PyPI 上那个废弃的同名包
类型提示写一半，IDE 和运行时都尴尬
加了 def parse_date(s: str) -> datetime: 却没给 s 加 Optional 或处理 None，调用方传 None 时类型检查器沉默，运行时报 AttributeError；或者反过来，写了 Optional[str] 却没在函数里判空，类型看似严谨，实际一跑就崩。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 类型提示必须和运行时校验对齐：声明了
Optional[str]，开头就得有if s is None:分支 - 别为了“看起来完整”给每个参数硬加
Any或省略提示——没提示比错提示更危险 - 用
typing.TYPE_CHECKING隔离仅用于类型检查的导入，避免循环引用或启动开销 - CI 里跑
mypy --strict，但别让它卡住发布——把error级别降为note的地方，加# type: ignore并附简短注释说明原因
把调试用的 print() 和日志混进生产代码
上线后发现某个工具函数总在控制台打 print(f"DEBUG: got {x}")，或者用 logging.info() 输出本该只在开发阶段看的中间值。这不是“小问题”，而是让下游服务的日志变得不可读，还可能泄露敏感字段。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 删掉所有裸
print()——真要调试，用logging.debug()+ 正确配置 logger 等级 - 工具模块默认不初始化 root logger，也不调
logging.basicConfig()；由主程序统一配 - 需要临时观察行为？加开关参数：
def clean_text(text: str, *, debug: bool = False) -> str:，而不是埋if os.getenv("DEBUG"): - CI 流水线里加检查：
grep -r "print(" myutils/和grep -r "logging.basicConfig" myutils/应该返回空
路径操作硬编码 / 或 os.path.join 导致跨平台失败
Windows 下跑得好好的工具函数，一到 Linux CI 就报 FileNotFoundError: [Errno 2] No such file or directory: 'C:\temp\data.json'——因为有人在拼路径时写了 "C:\temp\" + filename，或者用 os.path.join("C:/temp", filename)，而 os.path.join 在 Windows 上会把斜杠自动转成反斜杠，但在其他系统上又不生效。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 一律用
pathlib.Path：Path("data") / "config.json"，它自动适配平台，且支持链式操作 - 接收路径参数时，优先接受
Union[str, Path]，内部统一转成Path处理 - 避免用
__file__拼资源路径：Path(__file__).parent / "assets"比os.path.dirname(__file__) + "/assets"更可靠 - 测试必须覆盖 Windows + Linux 双环境——GitHub Actions 里用
runs-on: [ubuntu-latest, windows-latest]
最麻烦的不是写错一次，而是改一处，漏十处：路径、类型、日志、导入，四个点只要有一个没对齐，下游项目就会在某个深夜报警。公共模块不是写完就扔，是得盯着它在别人代码里怎么活下来。
