HTRI二次开发教程20收官——企业级换热器批量核算平台完整项目版本与事实声明版本锚点当前Xchanger Suite 9.4官方文章日期 2026-02-09Automation Server 为随软件安装的 OLE 自动化服务器Edgeview 并行比逐个跑快八倍以上为官方表述。本项目是把第 01~19 篇能力组装成完整工具包不引入新 API所有 ProgID/类名/方法名仍为...占位符必须由本机探测替换铁律 1。数值均为示例性建模不代表任何标准规定不对应任何真实装置许可与价格以 HTRI 官方渠道为准。一句话结论一个可交付的 HTRI 批量核算平台 五层架构探测层 / 连接层 / 数据层 / 批处理层 / 报表层 一套 CLI 命令 一份配置契约 一组回归测试它的成败不取决于能算多少案例而取决于两条所有标识符都来自本机探测不猜 API以及每一份结果都能凭账本、模板哈希与软件版本追溯到复现。〇、本篇要解决的认知问题Q1一个企业级 HTRI 批量核算平台应该分成哪几层每层的职责与依赖边界是什么Q2为什么配置驱动 CLI比一堆脚本更适合作为交付形态Q3平台的哪些部分是与 HTRI 强耦合的哪些是可跨项目复用的Q4回归测试在这个平台里测什么怎么测在没有测试许可的情况下Q5整个 20 篇系列沉淀下来的工程纪律到底是哪几条一、机制解析1.1 五层架构┌──────────────────────────────────────────────────────────┐ │ L5 报表层 report/ → delivery_report.xlsx汇总/逐案例/结论/落款│ ├──────────────────────────────────────────────────────────┤ │ L4 批处理层 scheduler/ → 分片、并发、账本、断点续扫、守护 │ ├──────────────────────────────────────────────────────────┤ │ L3 数据层 data/ → 案例矩阵 / 结果长表 / 账本 / 元数据 │ ├──────────────────────────────────────────────────────────┤ │ L2 连接层 htri/ → OLE 会话、load/change/run/retrieve/save │ ├──────────────────────────────────────────────────────────┤ │ L1 探测层 probe/ → 注册表枚举、类型库、对象树、探测清单 │ └──────────────────────────────────────────────────────────┘ 依赖方向上层依赖下层L1/L2 与 HTRI 强耦合每层职责L1 探测层产出probe_registry.json、object_tree.json、映射表——唯一合法标识符来源第 05/06 篇L2 连接层封装 OLE 生命周期第 07 篇的 load/change/run/retrieve/save 释放三步L3 数据层三张契约表 元数据 幂等 IO第 09/10 篇L4 批处理层分片、并发、守护、断点续扫、调度第 08/16/19 篇L5 报表层阈值判定与四段式交付第 15 篇。关键设计依赖只向下。L5 不直接碰 OLEL2 不关心业务阈值——这样上层可独立测试、下层可独立替换。1.2 配置驱动 CLI一个平台如果只是一堆脚本换个人就不知道怎么跑。配置驱动 CLI解决三件事可发现htri-devkit --help列出所有命令可复现一次运行 一个配置文件 一条命令可交接配置即文档。CLI 命令建议最小集htri-devkit probe # L1探测类型库生成/更新探测清单 htri-devkit contract-check # L3校验案例契约模式—字段可写性 htri-devkit make-cases # L3由契约生成案例矩阵 htri-devkit run --shard 003 # L4执行一片进程内串行 htri-devkit resume # L4按账本续扫未完成案例 htri-devkit report # L5生成交付工作簿 htri-devkit selftest # 无 HTRI 依赖的自检与回归1.3 强耦合 vs 可复用层与 HTRI 耦合度能否跨项目复用L1 探测层强注册表/类型库低换软件就换探测L2 连接层强OLE 生命周期低L3 数据层弱只是表结构高任何批量工程都用得上L4 批处理层弱分片/并发/账本高L5 报表层弱阈值/交付格式高这个划分的价值将来若从 HTRI 换成另一款换热器软件你只需要重写 L1、L2探测与连接L3/L4/L5 几乎原样复用。把软件会变这件事隔离在最薄的两层里——这是平台化设计的核心洞见。1.4 回归测试测什么没有测试许可的团队也能做回归测试——测不依赖 HTRI 的部分L1注册表枚举脚本在无 HTRI 机器上应未命中而非崩溃占位符守卫应阻止运行L2会话上下文管理器应保证 finally 释放用假对象L3账本幂等重跑不重复、长表去重、单位换算表正确Pa→kPa 0.001L4分片不丢案例、should_skip跳过已完成、自适应并发在失败率升高时降级L5结论阈值判定、落款字段齐全、衍生指标标注。最佳实践把这些做成htri-devkit selftest每次改动后一键跑——它是平台没被改坏的守门员。1.5 平台的知识地图把 20 篇串成一张依赖图01 全景/通道 → 02 环境/许可 → 03 第一个案例 → 04 数据模型 ↓ 05/06 探测标识符唯一来源 ↓ 07 生命周期 → 08 参数扫描实战 ↓ 09 取数 → 10 落盘 → 11 板式 → 12 空冷/振动 ↓ 13/14 流程模拟器集成 → 15 报表交付 → 16 许可/并发治理 ↓ 17 空冷端到端 → 18 加热炉/网络 → 19 规模化 ↓ 20 平台收官本篇1.6 平台的验收标准与交付门禁平台交付前用一张验收表自问——答不上任何一项就不算可交付维度验收问题不合格的表现真实平台里有没有任何一个 ProgID/方法名是猜的有硬编码的Dispatch(HTRI.xxx)可复现换台机器、同一个配置能不能跑出同一个结果结果依赖上次留下的状态可追溯任一数值能否追到案例 模板哈希 软件版本 单位交付件只有数字没有落款可续跑中途断电后能否从断点继续必须从头重跑可诊断失败时能否说出哪一层、哪个案例、什么原因只有一句跑失败了可复用换一款换热器软件要改多少代码全平台推倒重来说明分层失败交付门禁硬性datadict.csv的real_identifier全部非空无空 全部探测确认selftest在无 HTRI 机器上全绿delivery_manifest.json中五层产物齐全交付件四段式汇总/逐案例/结论/落款完整。为什么把验收做成表平台的好是抽象的但不合格的表现是具体的。用六个可观察的坏现象来定义好比用十个形容词描述架构优雅有用得多——这也是本系列一路的方法把判断标准变成可执行的检查。二、完整代码与逐行剖析代码 20-1平台 CLI 入口可运行骨架# -*- coding: utf-8 -*- htri_devkit.py —— HTRI 批量核算平台 CLI 入口 用法 python htri_devkit.py --help python htri_devkit.py selftest # 无 HTRI 依赖的自检 python htri_devkit.py probe # 需真实环境 python htri_devkit.py make-cases # 需 cases 契约 python htri_devkit.py report # 需已落盘结果 说明本入口只做命令分发各命令实现分别在 probe/ htri/ data/ report/ 下。 importargparseimportimportlibimportsys# 命令 - (模块, 函数, 是否依赖 HTRI)COMMANDS{probe:(probe.probe_registry,main,True),tree:(probe.probe_object_tree,main,True),make-cases:(data.make_cases,main,False),run:(batch.run_shard,main,True),resume:(batch.resume,main,True),report:(report.make_delivery,main,False),selftest:(tests.selftest,main,False),}defbuild_parser():pargparse.ArgumentParser(proghtri-devkit,descriptionHTRI 批量核算平台教程第 20 篇收官项目)p.add_argument(command,choicessorted(COMMANDS),help要执行的命令)p.add_argument(--shard,defaultNone,helprun 命令指定分片文件如 shard_003.csv)p.add_argument(--config,defaultplatform.json,help配置契约路径默认 platform.json)returnpdefdispatch(args):mod_name,fn_name,needs_htriCOMMANDS[args.command]try:modimportlib.import_module(mod_name)fngetattr(mod,fn_name)except(ImportError,AttributeError)ase:print(f[未实现/不可用]{args.command}:{e})print(提示本入口为骨架各层实现见对应目录教程第 05~19 篇给出组件代码。)return2# 依赖 HTRI 的命令先做占位符与探测清单守卫ifneeds_htri:try:importjson rowsjson.load(open(probe_registry.json,encodingutf-8))ifnotrows:print([停止] 探测清单为空请先执行 htri-devkit probe。)return3exceptFileNotFoundError:print([停止] 未找到 probe_registry.json请先执行 htri-devkit probe。)print( 本平台绝不使用未探测的 ProgID/方法名铁律 1。)return3returnfn(args)defmain():argsbuild_parser().parse_args()rcdispatch(args)sys.exit(rcifisinstance(rc,int)else0)if__name____main__:main()逐行剖析COMMANDS表把命令、模块路径、是否依赖 HTRI三者绑定平台一启动就显式区分要不要 HTRI——这让selftest/report能在无 HTRI 机器上运行1.4 节回归测试的前提。依赖 HTRI 的命令在执行前校验探测清单没有probe_registry.json就停止并打印铁律 1。把不猜 API做成平台的入口守卫而不是靠人自觉——这是本系列方法学的最终落地。模块未实现时返回码 2可用性缺失、探测缺失返回码 3前置不满足退出码分层便于 CI 判定失败原因。--config platform.json配置驱动1.2 节一次运行 配置 命令。入口只做分发、不做业务各层职责单一1.1 节。代码 20-2平台配置契约与交付清单# -*- coding: utf-8 -*- platform_config.py —— 平台配置契约与交付清单生成 用法python platform_config.py 输出platform.json配置契约、delivery_manifest.json交付清单 importjsonimportdatetime# 配置契约把一次运行的全部决定固化示例性建模CONFIG{meta:{software_version:9.4,disclaimer:示例性建模不代表任何标准规定不对应任何真实装置,},module:Xist,mode:rating,template:template.htri,cases_file:cases.csv,targets:{outputs.summary.overall_u:W/(m2·K),outputs.summary.shell_dP:kPa,},limits:{# 结论阈值示例outputs.summary.shell_dP:30.0,},batch:{per_shard:20,max_per_process:5,# 单进程案例上限第 16 篇concurrency_start:1,# 并发从 1 起步第 16/19 篇fail_rate_limit:0.2,# 自适应降级阈值经验值},report:{sheets:[汇总,逐案例,结论,落款],footer_fields:[software_version,template_sha256,created_at,unit_set_note,disclaimer],},}# 交付清单平台对外交付的物证MANIFEST{layer_L1_probe:[probe_registry.json,object_tree.json,mapping_suggest.csv],layer_L2_conn:[datadict.csv],# real_identifier 已确认layer_L3_data:[cases.csv,results_merged_long.csv,ledger.csv,run_meta.json],layer_L4_batch:[shards/,batch_log.txt],layer_L5_report:[delivery_report.xlsx,delivery_checklist.csv],docs:[platform.json,_调研素材参考.md,README-系列总览.md],}defmain():withopen(platform.json,w,encodingutf-8)asf:json.dump(CONFIG,f,ensure_asciiFalse,indent2)manifest{generated_at:datetime.datetime.now().isoformat(timespecseconds),software_version:CONFIG[meta][software_version],items:MANIFEST,}withopen(delivery_manifest.json,w,encodingutf-8)asf:json.dump(manifest,f,ensure_asciiFalse,indent2)print(已写出 platform.json 与 delivery_manifest.json)print(交付清单分层L1 探测 / L2 连接 / L3 数据 / L4 批处理 / L5 报表 / 文档)print(核对要点L2 的 datadict.csv 必须 real_identifier 全部非空方可交付。)if__name____main__:main()逐行剖析CONFIG把第 16/19 篇的关键运行参数max_per_process、concurrency_start1、fail_rate_limit纳入配置契约平台行为由配置决定可审计、可交接。batch.concurrency_start 1默认从 1 起绝不写死高并发铁律 7 与实测标定的统一。report.footer_fields显式列出落款字段第 15 篇交付可信度是配置项不是可选项。MANIFEST按五层文档组织交付物交付清单本身就是架构的镜像——能按层核对说明架构清晰。输出提示L2 的 datadict.csv 必须 real_identifier 全部非空方可交付把不猜标识符作为交付门禁。三、常见报错与排查报错 3-1平台迁移到新机器后所有命令报未找到 probe_registry.json。现象命令被入口守卫拦下。根因这是设计如此——探测清单是机器相关的换机器必须重探测。解法在新机执行htri-devkit probe重建清单确认datadict.csv的real_identifier与探测结果一致。报错 3-2selftest 在无 HTRI 机器上失败。现象回归测试报错。根因selftest 被误写成依赖 HTRI。解法确保 L3/L4/L5 的测试用假对象与纯 IO1.4 节L1/L2 只测占位符守卫与释放逻辑。报错 3-3交付时发现 datadict.csv 有空的 real_identifier。现象交付门禁不过。根因某些字段未探测确认。解法补齐探测或从契约中移除该字段宁可少交付不可猜空标识符字段不得进入编码铁律 1。报错 3-4升级版本后平台结果整体偏移。现象同配置、不同版本结果不同。根因方法随版本更新9.3 改 RPM 冷凝、9.4 改超临界传热、高翅片 inline 管束修正。解法platform.json显式记录software_version升级后重跑selftest与关键案例把差异归因到方法更新交付件落款随版本更新。报错 3-5多人协作时各自改了不同的脚本合并冲突。现象合并后平台跑不起来。根因无统一入口与配置契约各自为政。解法所有运行走htri-devkitCLI platform.json层间依赖只向下每次改动跑selftest。四、动手练习练习 1搭骨架按五层架构建目录probe/ htri/ data/ batch/ report/ tests/实现代码 20-1 的 CLI 入口。判定--help列出七个命令run在无probe_registry.json时返回码 3。练习 2配置契约运行代码 20-2 生成platform.json与delivery_manifest.json。判定配置含max_per_process、concurrency_start1、fail_rate_limit交付清单覆盖五层文档。练习 3无 HTRI 回归实现selftest测账本幂等、分片不丢案例、单位换算Pa→kPa0.001、占位符守卫。判定在无 HTRI 机器上全部通过。练习 4端到端收官串起 “probe → make-cases → run分片→ resume → report”。判定产出一份四段式delivery_report.xlsx落款含software_version与template_sha256delivery_manifest.json中各层产物齐全。五、小结与下一篇预告本篇收官把 20 篇装进一个五层架构探测/连接/数据/批处理/报表 CLI 配置契约 回归测试的平台。三条总纪律贯穿全系列探测优先铁律 1任何 ProgID/方法名的唯一合法来源是本机探测平台入口即守卫契约驱动第 04/08/10 篇模式—字段、变量—目标、三张表、配置让运行可复现、可交接可追溯第 10/15 篇账本 模板哈希 软件版本 单位让每个结论都能回答从哪来、能不能复现。以及一条产品边界纪律加热炉是 Xfh / Xfh Ultra不是 Xjoule官方 API 是 HTRI Automation ServerOLE官方演示为 .NET/C# 与 Excel能借官方并行Edgeview 快八倍以上就别重造轮子。本系列到此结束。若你是第一次读到这里建议回到第 01 篇按顺序重读一遍——你会发现第 20 篇的每一层都能在前 19 篇里找到出处。本篇认知问题回显FAQQ1企业级 HTRI 批量核算平台应分成哪几层A五层L1 探测层注册表枚举、类型库、对象树、探测清单产出唯一合法标识符来源L2 连接层封装 OLE 生命周期 load/change/run/retrieve/save 与释放三步L3 数据层案例矩阵、结果长表、账本、元数据与幂等 IOL4 批处理层分片、并发、守护、断点续扫、调度L5 报表层阈值判定与四段式交付。依赖方向严格向下上层不直接碰 OLE。Q2为什么配置驱动 CLI更适合作为交付形态A因为它让平台可发现--help列出命令、可复现一次运行 一个配置文件 一条命令、可交接配置即文档。相比一堆脚本CLI 配置契约把怎么跑从人的记忆里搬到文件里并让 CI 能按退出码判定失败原因如 2 命令未实现、3 探测缺失。Q3平台的哪些部分与 HTRI 强耦合哪些可复用AL1 探测层与 L2 连接层与 HTRI 强耦合注册表/类型库/OLE 生命周期复用性低L3 数据层、L4 批处理层、L5 报表层耦合弱只是表结构、分片并发账本、阈值与交付格式可跨项目高度复用。价值在于将来换软件只需重写最薄的两层把软件会变隔离起来。Q4回归测试测什么怎么在没有测试许可时测A测不依赖 HTRI 的部分L1 注册表枚举在无 HTRI 机器上应未命中而非崩溃、占位符守卫生效L2 会话上下文的 finally 释放用假对象L3 账本幂等、长表去重、单位换算L4 分片不丢案例、should_skip 跳过、并发自适应降级L5 阈值判定、落款字段、衍生指标标注。做成htri-devkit selftest一键跑作为平台没被改坏的守门员。Q5整个系列沉淀的核心工程纪律是哪几条A三条总纪律一是探测优先ProgID/方法名唯一合法来源是本机探测平台入口即守卫禁止猜 API二是契约驱动模式—字段可写性、变量—目标、三张表、配置契约使运行可复现可交接三是可追溯账本追加取最新、模板 SHA-256 哈希、软件版本与单位让结论可复现。外加产品边界加热炉是 Xfh / Xfh Ultra 而非 Xjoule官方 API 是 HTRI Automation ServerOLE能借官方并行Edgeview 快八倍以上就别重造轮子。