# TODO

## 当前活跃待办

### Python 一键安装与发布（设计定稿，代码待启动）

设计文档：`doc/develop_doc/20_专题记录/05_Python一键安装与发布设计.md`
（2026-09-04 定稿，已同步专题索引、文档地图与路线图 3.4）。

代码实施步骤：

P-a 打包地基：

- [x] OrderedConcurrentPool 增加 FetchContent 回退（sibling 优先，缺失自动拉取）。
- [x] 新增 `pyproject.toml`（scikit-build-core）与 CMake 安装规则，产出
      `spiceunion` Python 模块。
- [x] 本机干净 venv 中 `pip install .` + `import spiceunion` 通过（无 sibling
      源码目录 + 全新 venv，wheel 构建成功，default 102/102 回归通过）。

P-b 一键体验：

- [x] 绑定 `spiceunion.doctor()` / `spiceunion doctor` console（复用 toolchain
      探测）；干净 venv 安装后实跑通过。
- [x] CI 云 runner 构建 wheel 并做 import + doctor 冒烟（`wheel-smoke` job
      云端跑绿，2026-09-05）。
- [x] 根 README 增加“Python 用户 3 分钟上手”（中英）。

P-c 发布：

- [x] 打 `v0.1.0` tag，PyPI 发布 sdist + manylinux wheel（TestPyPI 试跑 →
      正式 PyPI 安装验收通过，2026-09-05）。
- [ ] conda-forge feedstock 候选与 `ngspice` 联合安装验证
      （配方草稿在 `packaging/conda-forge/`）。
- [x] 版本号同步三处 + CHANGELOG（v0.1.0 发布时已同步，策略写入专题 05）。
- [ ] 发布后回归 `pypi-smoke`（手动/定时安装线上 PyPI 包跑测试）云端跑绿后收口。

## 暂缓池

- [ ] **方案二：仿真器原生测量直出**（Ngspice `.meas` / Spectre `measure`、
      `mdl*`；设计见 `doc/develop_doc/20_专题记录/06_产物生命周期与指标提取设计.md`
      第 4 节）。它是独立的产物生成方式改造，不属于方案一；启动前需另立实现设计。
- [ ] legacy sensitivity fixture、可信参考值与读取实现。
- [ ] Spectre 23.1 PSFXL transient 的解析或转换路径评估。
- [ ] C++ helper 与 Python helper 在失败语义上的有意差异集中记录。
- [ ] 原生 PSF parser。
- [ ] MOS I-V / gm/Id 多曲线 DC 结果与 `DcSweep` 扩展评估。
- [ ] `EvaluatorOptions` 扩展或 netlist template / DSL。
- [ ] Ngspice `.op` operating point。
- [ ] Spectre Python workflow smoke。
- [ ] C ABI 正式实现（M4 第一版暂缓，仅保留 ownership 草案）。
- [ ] libpsf backend 产品化分发与 license notice。
- [ ] spectre / ngspice 外部测试门控拆分（让 ngspice 上云）——阶段 2 任务 3，
      用户决定放弃，暂缓。
- [ ] Xyce / Hspice 多仿真器扩展。
- [ ] Ngspice 常驻/服务模式 backend 评估（触发条件与验证步骤见
      `doc/develop_doc/30_归档备注/02_仿真器常驻模式评估备注.md`）。

## 监控项

- [ ] `spectre_materials` 行为基线变化时，同步审视 SPICEUnion 当前事实文档与契约测试。
- [ ] 性能数字未实测前，只能作为目标值，不得写成已完成结果。
- [ ] 云 CI 偶发失败观察：阶段 1 曾出现一次重跑即恢复的失败，若复现再深挖日志。
- [ ] 自托管 external CI 再触发前，需先在 GitHub Secrets 把旧名称的 external 材料
      secret 改名为 `SPECTRE_MATERIALS_DIR`（值不变）；改名完成前 external job
      会配置失败。

## 归档

- 产物正确性与指标提取（方案一，2026-10-05 完成）：每 job 独立产物目录
  （Ngspice 直写 + Spectre 快照，修复前序结果被覆盖）；声明式 `metrics=` 在
  worker 归还池子前完成提取（DC / DC sweep / AC 派生 / TRAN 派生）；产物保留
  策略未改、`read_*` 行为不变。验证：default 112/112、python 120/120、
  python-libpsf-pic 139/139。设计见 `doc/develop_doc/20_专题记录/06`、`07`；
  方案二（原生测量直出）在暂缓池。
- tests 目录分层整理（2026-09-04）：新增 `tests/CMakeLists.txt`，根 CMake 只保留
  测试入口；C++ 测试按 `unit/`、`integration/`、`external/{spectre,ngspice}/`
  分层；拆分原 `ngspice_session_test.cpp` 为配置、netlist、wrdata parser、
  session external、evaluator external 测试；补充 `tests/unit/README.md`、
  `tests/integration/README.md`、`tests/external/{spectre,ngspice}/README.md`。
  验证：default 97/97、external 97/97、libpsf 116/116、external-libpsf
  116/116、python 104/104、python-libpsf-pic 123/123。
- 公开化文档与命名契约（2026-09-04）：根 README 中英双语并面向贡献者，新增
  `CONTRIBUTING.md`；CMake / CI / 测试采用新材料语义命名
  （`SPICEUNION_SPECTRE_MATERIALS_DIR` / secret `SPECTRE_MATERIALS_DIR`），
  fixture 目录同步改名；全部历史（含提交信息）已用 filter-repo 清理旧命名并
  force push；本机材料目录以 symlink `../spectre_materials` 装配。验证：
  default 全绿、external-libpsf 116/116。
- 工具链自动适配与诊断 MVP（2026-09-04）：设计见
  `doc/develop_doc/20_专题记录/04_仿真器自动适配与诊断设计.md`；实现
  `simulator_kind.hpp` / `toolchain.hpp` / `src/toolchain/simulator_probe.cpp`；
  spectre 与 ngspice session 接入统一 resolver（spectre 新增
  `SPICEUNION_SPECTRE` env）；`tests/manual/spiceunion_doctor.cpp` 诊断入口
  与样例输出已沉淀。验证：ToolchainTest 5/5、default 102/102、
  external-libpsf spectre/ngspice 子集 10/10。后续：版本→能力门控、Spectre
  安全版本探测策略、Python `doctor()`（均在暂缓/路线图 3.3）。
- M6 Python workflow binding 第一版：已在 `bindings/python/spiceunion_py.cpp` 绑定
  `Simulation` / `SimulationResult`，新增 `test_workflow_api_contract.py`、
  `test_workflow_external.py` 和 `run_workflow.py`；`python` 预设 104/104 通过，
  显式 Ngspice workflow smoke 1/1 通过，`python-libpsf-pic` 预设 123/123 通过
  （2026-09-02）。
- M6 Python workflow binding 文档侧启动完成：已新增阶段记录
  `doc/develop_doc/10_阶段记录/06_M6_Python工作流Binding.md` 和专题草案
  `doc/develop_doc/20_专题记录/03_Python工作流Binding设计.md`；已同步路线图、项目章程、
  当前事实、M4/M5 承接关系和文档索引（2026-09-02）。
- 统一用户工作流 API 第一轮：C++ workflow facade 已落地，公开入口
  `include/su/workflow.hpp`，实现目录 `src/workflow/`，契约测试
  `tests/unit/workflow/workflow_test.cpp`；默认测试 97/97 通过（2026-09-02）。
- 开发文档体系重构：`doc/develop_doc` 已按 `00_项目总览`、`10_阶段记录`、
  `20_专题记录`、`30_归档备注` 编号分层；文档地图与维护规范见
  `doc/develop_doc/README.md`（2026-09-02 落地）。
- 阶段 2：云 CI 补 libpsf 预设 + 缓存与 artifact（2026-08-23 落地并验收，
  云 CI 四预设全绿；学习档案见本地 `doc/study_notes/cicd/`（私有，不入库）；
  工作流 `.github/workflows/ci-eda-free.yml`）。
