Add portable Mentor schematic batch exporter

This commit is contained in:
阿白叔 committed 2026-11-06 14:51:19 +08:00
commit 40fbb1893a
26 files changed
+3622

No files matched your search

@@ -0,0 +1,57 @@
# Mentor Batch Export Implementation Plan
> For agentic workers: use superpowers:subagent-driven-development. Steps use checkbox syntax.
Goal: ship an offline portable, interactive Windows folder exporter for saved Mentor schematics, with tool provenance and recoverable results.
Architecture: a standalone Python package, bundled embedded Python and pywin32, vendor tools discovered locally. The CLI owns batching and reports; the exporter owns stable clones, isolated tool execution, validation and shared library reads.
Tech Stack: Python 3.12 x64, pywin32 312, x86 native library helper, 32-bit Windows cscript, stdlib HTML/JSON.
Spec: ../specs/2026-11-06-batch-export.md, approved by the user in chat.
## Global Constraints
- No Designer launch, no mutation of source projects/libraries or permanent environment/COM registration changes.
- Detailed schematic exports by default. Tool and mode provenance never merged away.
- Portable Python with preset dependencies; no user-side pip.
- Source copies exclude server address files. Owned native process cleanup is mandatory.
- Failure/partial/unavailable/cancelled must be visible; output validation required even with exit code zero.
- Retrying a changed source starts a complete new project attempt, never mixes source generations.
## Interfaces shared by tasks
core.read_project(path) returns a dict with string path, name, database, root_block, snapshot, library (str or None).
core.sha256(path), core.read_text(path), core.write_json(path, value) are stdlib utilities.
environment.discover_installations(explicit=None, cached=None) returns root/version/tools/native_compatible/com dicts.
tools keys are ascii, csv, keyin, rinf, edif, wir, pxr, constraints_xml; values are absolute EXE paths.
installation.com maps cms and central to dicts containing registered_path and matches.
exports.export_project(project, installation, project_dir, shared_dir, *, previous=None, stop_event=None, timeout=45, progress=print) returns a JSON-serializable record containing status, source_fingerprint, items, and source_hashes.
Each item has key, status (success/failed/unavailable/cancelled), reason, outputs (absolute file paths), and provenance.
previous is an earlier exporter result; project_dir is always a new attempt directory. Successful prior items are reused only when hashes, snapshot and tool identity still match.
exports.list_snapshots(project, installation, work_dir) may return names, without changing default selection.
## Task 1: export backend and helpers
- [x] Write behavioral tests for exit-zero/no-output, stable clones, cancellation, tool provenance and changed-input retries; run red.
- [x] Implement exports.py, helpers, and private process boundary by reusing verified research code; no fixed sample root/path.
- [x] Preserve ASCII flat/hier, CSV tables, WIR/OAT, KYN/RINF/PXR, EDIF net/schematic, CMS constraints with level identity.
- [x] Export associated library data for used parts/cells once per matching library fingerprint; native ABI guard and clear partial coverage.
- [x] Run tests green and report touched files and limitations.
## Task 2: environment, scanning, CLI, reporting
- [x] Write failing filesystem/behavior tests before implementation.
- [x] Implement core.py with project options, recursive discovery, collision-safe names, bounded identity and stable capture utilities.
- [x] Implement environment.py with explicit/cache/env/registry/limited conventional paths; same-install tools and COM matching.
- [x] Implement export.py interactive/noninteractive CLI, settings, per-batch and per-project manifests, cancellation, retries and HTML summaries.
- [x] Verify output-root recursion exclusion, duplicate names, invalid sources, changed sources and late interruption records.
## Task 3: portable package and acceptance
- [x] Build embedded Python 3.12.10 x64 from official distributable, preset locked pywin32 wheel, include runtime/third-party licenses.
- [x] Compile custom helper x86 with static CRT; include source, no Mentor binaries.
- [x] Create CMD entry using only relative bundled runtime; integrity validation and offline smoke check.
- [x] Run a real two-project export, compare source hashes, inspect provenance and required artifacts, retry selected failed/unavailable items.
- [x] Test moved folder with Python/PATH environment stripped; timeout/cancel/error tests; independent review.
- [x] Deliver folder and ZIP with README, dependency/compatibility manifest and validation report.
@@ -0,0 +1,154 @@
# Mentor 批量原理图导出工具设计草案
日期:2026-11-06。状态:已获用户确认并实施;最终验收见 ../../validation-2026-11-06.md。
## 已确认要求
- 独立、可复制的工具文件夹,以命令行启动,中文问答式交互。
- 递归扫描用户指定目录中的 Mentor 工程。
- 默认 A「工程详细包」,默认读取工程配置指定的原理图快照,通常是 DxD。
- 不同工具、同一工具的不同模式分别保存,不能把同名字段直接合并为同一事实。
- 导出集中到一个结果根目录,按批次、工程名称及重要内容分类。
- 自动发现 Mentor 环境。
- Python 环境及必要依赖预置好,用户端无需 pip 安装。
- 注重重复运行、结果核实、失败说明及重试。
以下为建议细则,不将其标记为用户已经逐项确认。
## 交付和运行环境
交付 ZIP,解压为工具文件夹:
MentorExport/
导出.cmd
export.py
runtime/ 便携 Python 3.12 x64 及预装依赖
helpers/ 自有 x86 库读取 EXE、VBS 和进程隔离模块
licenses/
使用说明.md
第一版以 Windows 10/11 x64 为目标,脚本可读、可维护。命令入口始终调用随包 runtime/python.exe,不依赖系统 Python、PATH 或 Python Launcher。必要的 pywin32 模块及原生 DLL 一起预置并固定版本;不引入界面框架。自有库读取程序按 x86 构建,CMS 和 CentralLib 的 VBS 使用 Windows 自带 32 位 cscript。
构建时形成依赖版本、文件和 SHA256 清单;启动验证运行环境,缺失/损坏时给出具体文件和恢复方法,不在用户端自动联网安装。发布包不携带 Mentor 厂商 EXE/DLL;目标机器必须已有可用 Mentor 安装及相应许可。必要运行时依赖在预检中实际检查。
保留一个用户配置文件,记住上次输入/输出路径及已选择的 Mentor 安装。优先保存到可写的工具目录;工具目录不可写时使用 LOCALAPPDATA/MentorExport。复制到另一电脑后,安装路径必须重新验证。设置仅限本工具,不永久修改用户环境变量或系统 COM 注册。
## Mentor 环境自动发现
按以下来源收集候选,规范化路径后去重:
1. 本次命令指定路径、上次选定且仍有效的路径。
2. 当前进程的 SDD_HOME。
3. 32/64 位注册表中的相关安装项、卸载信息和已注册组件路径。
4. 常见安装根目录下的有限层级目录查找,不默认递归扫描所有磁盘。
5. 自动发现失败时,提示用户输入安装目录。
每个候选核验安装根、工具文件、版本、必要依赖和导出参数能力。单个 EXE 存在不代表该安装完整。工具和依赖必须来自同一套安装,不能拼凑多个版本的 PATH。
只找到一套可用安装时默认选用;多套时展示版本、路径和可用导出项,让用户选一次并记住。只有本机已验证的 EE7.9.5 接口能够默认使用原生库读取 helper;其他版本需通过明确的兼容准入,未验证项展示为不可用,不盲调本机 ABI。
CMS/CentralLib 的 32 位 COM 注册路径要与选定安装匹配。发现其他版本注册时,不自动重新注册,相关导出项返回可解释的不可用状态;其他独立导出继续。
环境预检只调用已有帮助/能力接口,不启动 Designer;不因探测而打开用户工程。
## 交互流程
1. 启动自检,显示本工具、运行环境与 Mentor 版本,以及缺失能力。
2. 输入扫描根目录,可回车沿用上次路径。
3. 递归发现 .prj,验证其数据库、根块及原理图快照;展示发现数、可导出数和问题工程。
4. 输入输出根目录,默认给出独立的导出结果目录;避免将输出放进源数据库。
5. 显示摘要:工程数、输出位置、原理图快照策略、可用/缺失导出项。用户确认后开始。
6. 按工程、按导出项顺序执行,持续显示当前工程、步骤和已完成数量。
7. 完成后显示成功、部分成功、失败、取消数量、汇总报告路径和下一步菜单:打开结果目录、查看失败、仅重试失败项、退出。
命令行同时支持指定输入、输出和 Mentor 安装路径,以减少重复输入;未提供的必要参数继续问答。完整脚本重跑与失败项重试是明确区分的操作。暂不增加无人值守调度、任务数据库或界面。
## 工程发现与命名
以规范化后的 .prj 路径识别工程,不把 .dxp 与旁边 .prj 重复计数。只发现 .dxp 时提示未找到对应可用 .prj,不自动启动 Designer 做转换。
同名工程保留原工程名并追加源相对路径摘要,避免覆盖或混淆。扫描不进入本工具已有导出目录、私有临时目录、.git 或目录联接/符号链接;其他目录不按宽泛名称随意排除。访问失败单独列出,不静默漏掉子目录。
默认从工程配置取得原理图快照及根块;其他快照仅记录名称。一个 .prj 下存在多个根块/配置时要显式枚举和区分,无法确定原理图上下文时列为需选择/不支持,不能静默挑第一个。快照不能称为装配变体。
## 结果目录
导出结果/
批次_日期时间_短标识/
导出汇总.html
批次记录.json
环境信息.json
工程A/
工程说明.html
工程记录.json
01_连接网表/
KeyinNetlist/
RinfNetlist/
EDIF_Netlist/
PXR/
02_器件与引脚属性/
icdb2ascii_平铺有效值/
icdb2ascii_分层值/
icdb2csv/
WIR_OAT/
03_位置与显示/
EDIF_Schematic/
04_电气约束/
CMS/
05_关联库件与封装/
工程引用与数据索引.json
90_运行日志/
_共享库数据/
库指纹/
目录示意是完整能力集;某一项不可用时,在记录及工程说明中明确写原因,不生成会误导用户的空成功文件。
所有原始输出按工具和模式保留;同一字段来自工程平铺、分层、网表身份列或中央库时,分别标注。报告可以引用和并列展示,不能自动覆盖差异或把旧网表身份列改写成当前料号。
工程记录保存:源路径、捕获时间、输入哈希、根块/快照/配置、工具版本与指纹、参数、退出码、耗时、产物路径/大小/哈希、完整性检查、覆盖限制和错误。
默认结果使用已验证、可读的导出路线。编码的 HKP/约束 XML、CCZ 等研究产物不默认加入,避免用文件存在冒充字段已覆盖。
## 工程详细包的范围
连接:KYN、RINF、EDIF Netlist、PXR。属性:平铺/分层 ASCII、CSV 关联表、WIR/OAT。显示:EDIF Schematic 的实际导出内容。约束:CMS 原始记录、列约束定义、单位及默认/覆盖标记。
关联库以本批工程实际使用的料号和封装为范围;同一库按指纹共享读取与结果,避免每工程保存整套中央库。缺库、库件重名、关联不明确或不支持的脚号映射分别记为未取得/无法确认。不能将未验证的多 gate、多 slot、可交换脚或历史库版本映射标为通过。
脚本只执行导出与覆盖检查,输出不等于换料前后比较,也不等于 ERC/制造正确性认证。第一版不加入自动修图、换料或 PCB 同步。
## 隔离、重复运行和失败闭环
- 每工程先捕获稳定的已保存输入,工具只访问短路径私有副本;不复制数据库服务器地址文件。所有导出项使用同一捕获输入,必要时每工具再建运行副本。
- 校验源文件读取前后摘要与副本摘要。数据库不可读或捕获期间变化时,该工程失败并给出保存后重试提示,不强行读取编辑中的不一致状态。
- 子进程环境临时设置 SDD_HOME、SDD_PLATFORM、同安装 DLL 路径。私有桌面和 Job 管理自有进程,保留超时、退出及资源收尾证据。
- 一个导出项失败,独立项继续;一个工程失败,其他工程继续。停止时先收尾当前工具,未执行项显示取消。
- 新运行创建新批次,旧结果不覆盖。重试建立独立尝试目录,旧失败证据保留;未变的成功输出可以引用,不能冒充重新导出。
- 仅当工程和所需库指纹仍匹配,才允许只重试失败项;输入已变时创建该工程的新完整尝试,避免混合前后状态。
- 启动时识别未完成尝试并显示中断状态;确认旧自有进程已退出后,允许重试,不默认自动续跑。
- 临时目录只清理本工具确认为自有、且进程已收尾的路径;日志和已发布产物保留。
## 结果判定
导出项:成功、失败、不可用、取消。成功必须同时满足可接受退出码、预期产物存在、非空/格式要求、对应快照和最小完整性检查;不能只看退出码为 0。
工程:全部请求项成功才为成功;有成功也有失败/不可用为部分成功;没有可用结果为失败;被停止且未执行完为取消。覆盖限制始终单独展示。
进程退出码建议:0 全部请求成功;1 已完成但含部分成功/失败;2 启动配置或必需环境错误;130 用户取消。HTML 和 JSON 结果始终与退出码一致。
## 实施顺序草案
1. 搭好独立交付目录和预置运行环境;完成可从任意工作目录启动的命令入口、离线依赖自检及 Mentor 发现。
2. 完成问答、目录扫描、工程身份/配置解析和稳定输入副本。
3. 按来源接入现有可读导出路线;补齐工程根块、快照和路径参数,移除研究脚本的固定样例路径。
4. 完成工程所用库件/封装读取与共享指纹索引、来源标注及覆盖报告。
5. 完成汇总页、状态、取消/超时、失败重试和中断识别。
6. 打包并在清理 Python/PATH 环境的子进程中验收便携启动;使用真实工程副本完成端到端验证。
正式实施计划将在本草案定稿后细化到文件、接口、测试与验收步骤。
## 验收重点
干净环境启动(无系统 Python/pip/PATH 依赖)、中文/空格/长路径、单套/多套/失效 Mentor 路径、32 位 COM 路径不匹配、无工程、重名工程、不可访问目录、源输入变化、缺库、非零退出、退出 0 无产物、超时、取消、中断、仅重试失败、输入变更后的重试。
真实导出验收须逐项核对报告、原始产物、来源标识与输入哈希,确认没有启动 Designer,没有修改源工程/源库,并证明复制整个交付文件夹到另一目录后仍能运行。