research-engineering

name	research-engineering
description	用于本仓库及类似研究型 Python 项目中的数据处理、回归、诊断、测试与绘图任务。涉及 Python 脚本、回归分析、结果表、诊断脚本、数据读取、matplotlib 绘图时使用。提供路径规范、测试先行、轻量预览、结果输出和环境选择约定。

Research Engineering

用于研究型 Python 工作流，尤其是数据处理、回归、诊断脚本、结果导出与绘图。

何时使用

• 需要新建或修改 Python 脚本
• 需要写 _test_*.py 诊断或验证脚本
• 需要读取 CSV/Excel/DTA/JSON/JSONL 等数据
• 需要产出图表、结果表、诊断文件
• 需要决定运行环境、依赖和输出路径

核心流程

1. 默认先写 _test_*.py 或最小诊断脚本，再决定是否改核心代码。
2. 先做轻量预览，再整表读取大文件。
3. 首次实现默认走单一、显式、可审计的主流程，禁止预埋静默 fallback。
4. 只有当小概率异常会阻断大规模批处理时，才讨论是否引入 fallback。
5. fallback 方案需要先和使用者确认，再落地到代码与数据结构中。
6. 只做最小必要改动，并保留可验证的回归证据。
7. 输出文件沿代码文件目录或其父目录拼接，禁止依赖 cwd。

路径规范

• 一律优先使用 pathlib.Path 和 __file__。
• 禁止直接依赖 os.getcwd() 或裸相对路径做项目内资源定位。
• 文本读写默认 utf-8，并做清晰异常处理。
• 在 notebook/REPL 中若 __file__ 不可用，显式回退到 Path.cwd()，并在注释里说明。

推荐模板：

from pathlib import Path

current_dir = Path(__file__).parent.resolve()
parent_dir = current_dir.parent.resolve()
data_path = current_dir / "your_file.csv"

测试先行

• 测试文件统一命名为 _test_<能力>.py。
• 优先放在被测模块同级目录。
• 如果测试会产出 CSV、图或摘要，这些产物也加 _test_ 前缀。
• 只有当测试明确暴露问题时，再改核心代码。

Fallback 原则

• 默认禁止静默 fallback，尤其禁止在第一次写代码时为了“稳妥”预先加入默认分支、兜底值或自动降级逻辑。
• 首次实现应优先暴露真实问题；如果主流程有缺陷，应先通过 _test_*.py、最小复现脚本或抽样诊断定位原因，而不是直接吞掉异常。
• 只有当以下条件同时成立时，才考虑引入 fallback：
  • 主流程已经验证过，且失败属于小比例、间歇性或脏数据问题。
  • 这些问题会中断大批量任务，导致整体流程不可接受地失败。
  • fallback 能被清楚定义其适用边界、风险与后果。
• fallback 方案不是代理自行决定的默认工程手法；在实现前，应先与使用者确认 fallback 策略，例如：
  • 记为失败并继续后续批处理；
  • 采用更简单但次优的替代处理；
  • 暂存到待人工复核队列。
• 任何 fallback 都必须显式、可审计、可汇报，禁止伪装成正常主流程结果。至少应满足：
  • 日志中明确记录触发原因、触发次数和样本；
  • 输出数据中明确标记该行/该条记录是否走了 fallback；
  • 如有必要，增加 status、fallback_used、fallback_reason、fallback_method 等字段；
  • 汇总输出中单独报告 fallback 占比，禁止把 fallback 结果与主流程结果混为一谈。
• 如果 fallback 的设计会影响研究口径、样本定义、统计含义或下游回归解释，必须先停下来确认，不得自行拍板。
• 若只是为了“避免报错”而加入 except: ... continue、默认空值、默认成功状态或隐式替代路径，通常应视为违规实现。

大文件读取

• 对体量未知的数据，禁止直接整表载入。
• 先用 pandas 的 nrows=5、chunksize，或命令行 head / sed -n '1,5p' 预览。
• 检查列名、编码、分隔符、缺失值和日期格式后，再决定正式读取参数。
• 对大 CSV 优先考虑 usecols、dtype、parse_dates、chunksize。

绘图规范

• 图例和轴标签原则上优先用英文。
• 若 matplotlib 需要中文字体：
  • macOS 可用 Arial Unicode MS
  • Windows 可用 SimHei

环境选择

• 优先使用项目内 uv + venv。
• 如果项目内没有可用虚拟环境，使用当前 shell 中已经可用的 Python 环境，或先和使用者确认项目应采用的环境。
• 禁止把个人本机绝对路径、私有虚拟环境路径或账号信息写进仓库代码、模板或公共文档。

输出与命名

• 所有中间结果、日志、缓存、图表、表格都应基于 current_dir / parent_dir 拼接。
• 禁止把输出写到不确定的当前工作目录。
• 诊断性输出尽量与脚本同目录，或写到脚本对应的 results/ 子目录。