PDMS-AVEVA-E3D二次开发教程20收官——PDMS/E3D 二次开发工具箱与交付体系版本与事实声明产品锚点AVEVA E3D Design 为官方现名发布锚点 3.1.4.0 / 3.1.5.0当前版本以官方发布说明为准AVEVA PDMS自 2024 年 4 月 1 日起停止销售与技术支持。官方专设 “Minimising Problems for Future Upgrades” 与 “Serious Warning About Software Customisation” 两节——软件定制会影响未来升级这是本篇架构设计的根本约束而非免责声明。本篇不引入任何新语法全部代码是前 19 篇已给出来源的标准 PowerShell / PML 组织方式。示例目录名、版本号、清单条目均为示例性数据。一句话结论一个可维护的 E3D 二次开发工具箱由五层构成——环境探测层先说清我在哪跑、数据访问层只读优先、规则层规则是数据不是代码、批处理层幂等与账本、交付层产出物必须自证判断一套工具箱好不好不看功能多少只看三件事能不能整体卸载、能不能一键回归、能不能交给第二个人维护。〇、认知问题Q119 篇写下来的函数与脚本凭什么能组成为一个工具箱而不是一堆文件Q2五层架构里为什么环境探测层必须排在最下面而不是最上面Q3PDMS 已停售停支持迁移期为什么还要做双轨双轨怎么做才不失控Q4回归测试要测什么测多少才够Q5一份交付清单到底要交什么才能让接手的人不骂人一、机制解析1.1 五层架构每一层解决一类会变化的东西工具箱的本质不是功能集合而是把会变化的东西分层隔离。五层的划法如下┌─────────────────────────────────────────────────────────────────┐ │ ⑤ 交付层 Delivery │ │ 图纸目录/快照发布/DQ 报告/交接报告/产出物核验 │ │ 会变的交付格式、命名规则、接收方要求 │ ├─────────────────────────────────────────────────────────────────┤ │ ④ 批处理层 Batch │ │ 作业编排/幂等/账本/重试/环境检查/进度与中断 │ │ 会变的调度方式、运行时段、并发策略 │ ├─────────────────────────────────────────────────────────────────┤ │ ③ 规则层 Rules │ │ 规则表(CSV/JSON)/数据字典/契约表/清单 │ │ 会变的业务规定、阈值、依据文件 │ ├─────────────────────────────────────────────────────────────────┤ │ ② 数据访问层 Access │ │ 只读校验器/范围裁剪/属性读写/三态契约/现场保护 │ │ 会变的产品版本、属性名、导航语法、模块差异 │ ├─────────────────────────────────────────────────────────────────┤ │ ① 环境探测层 Probe │ │ 产品与版本/PMLLIB/程序集清点/权限与会话/能力清单 │ │ 会变的安装位置、部署方式、升级节奏 │ └─────────────────────────────────────────────────────────────────┘ ▲ 全部层都向上依赖这一层的事实为什么环境探测层排在最下面而不是最上面因为上面四层的一切判断都建立在它提供的事实上——数据访问层要问这个属性名在这个版本上存在吗第 02、06 篇的ATTLIS规则层要问这条规则的依据文件在哪个版本有效第 17 篇的basis列批处理层要问我连的是哪个库、有没有 Claim 权限第 09 篇的四段结构第一段交付层要问产出物对应的产品版本是多少第 18、19 篇的元数据文件。排在最下面是对依赖方向的物理表达越靠下越稳定、越靠上越易变。第 02 篇的e3d_env_inventory.csv、第 13 篇的dotnet_inventory.csv就是这个地基。1.2 判断工具箱好坏的三条标准前面 19 篇给了一堆最佳实践但它们都是局部的。用全局视角看一套工具箱只有三条硬标准标准判据可操作对应篇章能不能整体卸载每一处加都有对应的减菜单项可移除、工具条 gadget 可移除、命令可 Killing、表单可隐藏、字段可释放第 08 篇官方 Removing/Killing 类机制能不能一键回归有一条命令跑完全部自检与验收输出通过/未通过清单第 08、17 篇MYCO_LibSelfTest、acceptance.ps1能不能交给第二个人维护规则在 CSV 里、字典在 JSON 里、依据有列、版本有函数、卸载有说明第 16、17、19 篇为什么是这三条而不是功能多不多因为工具箱的寿命取决于这三条。功能多但不可卸载的定制产品升级一次就废不可回归的定制第二次改动就没人敢动不可交接的定制作者离职即失传。官方那句Minimising Problems for Future Upgrades想说的就是这件事。1.3 迁移期双轨PDMS 与 E3D Design官方事实AVEVA PDMS 已被 AVEVA E3D Design 取代并自 2024 年 4 月 1 日起停止销售与技术支持“AVEVA Everything3D is now AVEVA E3D Design”。为什么还要做双轨因为设计院里的存量项目不会因为产品停售而消失——老项目仍要在原环境上维护新项目按 E3D Design 建设。工具箱必须同时服务两者否则会出现老项目没人管或新项目从零重写。双轨的三条控制原则控制的是不要让它失控而不是不要做原则做法失控的表现要避免差异显式化代码里凡涉及两代差异处用统一注释标记如-- VER-DIFF: PDMS 12.x / E3D Design并在自检里输出当前判定靠人记差异 → 每次都在猜公共部分最大化规则层、字典层、交付层完全共用它们不依赖产品版本仅数据访问层与探测层分叉上下都复制两份 → 维护量翻倍单点分叉数据访问层里凡有差异的能力导航、写属性、文件 I/O收敛到少数几个函数做版本判定差异散落各处 → 无法说清支持哪些版本关键洞察五层里只有 ①② 两层是产品相关的③④⑤ 三层是工程相关的。所以双轨的实际成本远低于直觉——只要 ③④⑤ 不复制双轨就是可承受的。最佳实践在工具箱自检里输出一行当前环境判定例如env: familyE3DDesign / version实际版本 / runtimedetected让这套工具箱在某台机器上以哪条轨运行成为可见事实。1.4 回归测试测三层不测全部回归测试不是把每个函数都测一遍成本太高、维护不了。只需要测三层层次测什么为什么只测这些冒烟层能否加载、版本函数能否返回、PMLLIB 是否含本工具箱目录加载失败是最常见故障且一秒可判契约层核心函数的返回契约是否符合三态前缀、字段数量与位置契约变化会静默破坏所有下游解析器端到端层一条最小完整流程选一个小范围 → 跑检查 → 产出报告 → 核验报告它覆盖了 90% 的集成问题且能自动判定不测的部分单个内部函数的细节逻辑、UI 的视觉效果、极端输入组合。理由这些测试的维护成本高于其收益把有限精力放在契约与端到端上回归才跑得起来、才会有人跑。回归的触发时机三条工具箱自身改动后产品升级前后各一次这是最重要的一次用于评估影响面交付前作为交付清单的一个必过项。1.5 交付清单交给接手人的东西第 02 篇讲了环境清单、第 08 篇讲了升级自查、第 19 篇讲了数据发布。交付清单是把这些清单合并成一份交接包类别交付内容为什么必须交环境事实环境探测清单产品/版本/路径/权限/程序集没有它接手人不知道在哪跑能力边界支持的产品代际与版本范围、明确不支持的场景没有它接手人会以为什么都能干代码资产五层目录、生成物、构建脚本、版本函数代码本身配置资产规则表、数据字典、契约表、图纸清单这是业务可维护的部分最容易被漏交纪律资产铁律清单、代码评审要点、卸载说明没有它接手人会把工具箱改坏验证资产回归脚本、验收脚本、最近一次回归结果没有它接手人不敢动运行资产运行账本、模型/数据台账、最近发布记录用于追溯上次跑到哪最容易被漏交的是配置资产与纪律资产——因为代码看得见规则与规矩看不见。但恰恰是这两类决定接手人能不能在三个月后还不骂人。1.6 团队规范与评审要点浓缩成一张表20 篇下来团队规范其实就这些。把它做成评审时的检查表#评审提问不通过的表现1这段逻辑会被调用第二次吗是就写成函数业务逻辑写在宏里2这段代码改了!!ce吗改了就在两个出口都还原只还原正常出口3属性名从哪来核对过ATTLIS吗凭记忆写属性名4数值带单位吗裸数值参与比较5判存在用的是Defined()还是值判空用取值判空0 被误判6批量脚本报了几个计数加起来自洽吗只返回Success7失败信息里有没有该怎么办只有失败三个字8这个动作在离线副本上验证过吗直接在生产库首次运行9有没有对应的卸载路径只加不减10规则/阈值/依据写在哪业务能改吗埋在代码里11这一段是 PML 该做的吗第 13 篇五条判据用 .NET 做界面12用了官方还是臆测的语法网上抄来未核对的写法第 12 条是元规则它是前 11 条之所以可靠的保证。官方文档查不到就标注以官方文档为准并给出章节定位——这条纪律比任何一条语法规则都重要因为语法会变、会被记错而知道去哪查的能力不会。1.7 八条铁律收官回顾全系列确立的八条铁律全系列不超过 10 条其余为最佳实践与经验法则#铁律一句话记法1语法只写官方手册记载的形态查不到就指向官方章节宁缺毋编2单位与属性必显式数值必带单位3先探测环境再运行先说清在哪跑4破坏性操作先离线验证副本先行5对接必声明边界与版本写清谁算哪段6PDMS 与 E3D Design 差异必须显式标注代际差异不许含糊7不混写产品能力无PML 内嵌 Python不把 APS 能力安到 E3D 上不张冠李戴8示例数据必标注示例不等于规定二、完整代码与逐行剖析代码 20-1工具箱目录骨架结构即架构e3d_devkit/ ├── README.md # 工具箱总览能力边界 / 支持版本 / 安装步骤 / 卸载步骤 ├── CHANGELOG.md # 每个版本改了什么含规则表变更 ├── 00_env/ # ① 环境探测层 │ ├── probe_install.ps1 # 安装与运行时盘点第 01/02 篇 │ ├── pml_lib_census.ps1 # PMLLIB 内容与命名冲突普查第 02 篇 │ ├── asm_identity.ps1 # .NET 程序集身份清点第 13 篇 │ ├── type_census.ps1 # 公开类型清点第 13 篇 │ └── out/ # 探测产物CSV随交付一起交 ├── 10_pml/ # ② 数据访问层PML │ ├── lib_version.pmlf # 版本函数第 08 篇 │ ├── lib_selftest.pmlf # 依赖自检第 08 篇 │ ├── nav_helpers.pmlf # 导航辅助按官方 DBRM2.03.x 实现第 05 篇 │ ├── lint_core.pmlf # 只读检查内核第 06/17 篇 │ ├── ifc_export.pmlf # IFC 导出封装第 12 篇 │ ├── draw_batch.pmlf # 批量导出作业第 18 篇 │ └── rules.pmlf # 【生成物】由 30_rules 构建勿手改 ├── 20_ui/ # ② 层的界面部分 │ ├── lint_ui.pmlfrm # 表单第 07 篇 │ └── commands.pmlf # 命令定义与装配/卸载第 08 篇 ├── 30_rules/ # ③ 规则层业务可维护 │ ├── rules.csv # 检查规则表第 17 篇 │ ├── data_dictionary.json # 数据字典第 19 篇 │ ├── dq_rules.csv # 数据质量规则第 19 篇 │ ├── draw_manifest.csv # 图纸清单第 18 篇 │ ├── contract.csv # 跨专业数据契约第 16 篇 │ ├── gen_rules.ps1 # 构建脚本CSV - rules.pmlf第 17 篇 │ └── apply_pml.ps1 # 构建物落盘到 PMLLIB 目录 提示索引重建 ├── 40_run/ # ④ 批处理层 │ ├── run_lint.ps1 # 检查作业入口第 09/17 篇 │ ├── run_draw.ps1 # 出图作业入口第 18 篇 │ ├── run_snapshot.ps1 # 快照作业入口第 19 篇 │ ├── job_ledger.ps1 # 作业账本第 09 篇 │ └── verify_outputs.ps1 # 产出物核验第 09/12/18 篇 ├── 50_deliver/ # ⑤ 交付层 │ ├── gen_index.ps1 # 图纸目录生成第 18 篇 │ ├── dq_check.ps1 # 数据质量检查第 19 篇 │ ├── snapshot_diff.ps1 # 快照差分与变更集第 19 篇 │ └── release.ps1 # 打包一次发布字典快照元数据DQ ├── test/ │ ├── smoke.ps1 # 冒烟层回归第 20 篇 1.4 节 │ ├── contract.ps1 # 契约层回归 │ ├── e2e.ps1 # 端到端回归 │ └── acceptance.ps1 # 项目级验收第 17 篇 └── docs/ ├── 交付清单.md # 本篇 1.5 节的落地交接包索引 ├── 铁律与评审要点.md # 本篇 1.6 节的落地 └── 卸载说明.md # 本篇 1.2 节第 1 条的落地逐行剖析目录编号00_/10_/20_…直接对应五层顺序编号让依赖方向在文件管理器的排序里就可读——排在上面的层依赖排在下层的事实。这是结构即架构的最省事表达方式。00_env/out/的探测产物随交付一起交这是 1.5 节环境事实必须是交付物的落地。很多团队把探测脚本交了、产物留在自己机器上接手人得先跑一遍才知道情况——而这恰恰是最容易卡住的地方。10_pml/rules.pmlf明确标注为生成物且构建脚本在30_rules/生成物与它的源放在不同层源在规则层产物在数据访问层。这个安排逼着人思考我改的是源还是产物从目录结构上防止手改生成物第 17 篇报错 3-2。docs/卸载说明.md是独立文件卸载路径不能只写在代码注释里。它是能不能整体卸载这条标准的物理载体1.2 节。一个没有卸载说明的定制在产品升级时的处理方式通常是不管它——然后升级出问题。test/分四个脚本对应四个层级冒烟/契约/端到端/验收分层让回归可以只跑需要的部分改了一个 PML 函数跑冒烟契约改了端到端流程跑全部。一次要跑十分钟的回归很快就不会有人跑。代码 20-2一键回归PowerShell可运行# -*- coding: utf-8 -*-# regress.ps1 —— 工具箱一键回归冒烟 / 契约 / 端到端 / 验收 设计要点 * 分层执行失败即汇总不中断最后给出总判定 * 每一层都有可自动判定的成功标准不允许看起来正常 * 结果同时输出给人看屏幕与给机器看regress_result.csv 用法 .\regress.ps1 -KitRoot . -Level all #param([Parameter(Mandatory$true)][string]$KitRoot,[ValidateSet(smoke,contract,e2e,all)][string]$Levelall,[string]$OutDir.\test\out)$ErrorActionPreferenceSilentlyContinueif(-not(Test-Path-LiteralPath$OutDir)){New-Item-ItemType Directory-Path$OutDir|Out-Null}$resultsNew-ObjectSystem.Collections.Generic.List[object]functionRun-Layer{param([string]$Name,[string]$Script,[int]$ExpectedExit)$rec[pscustomobject]{layer $Name;script $Script;ran $falseexit_code ;verdict ;detail ;seconds 0}$pJoin-Path$KitRoot$Scriptif(-not(Test-Path-LiteralPath$p)){$rec.verdict SKIP_NO_SCRIPT;$rec.detail 未提供$Script$results.Add($rec)|Out-NullWrite-Host([{0}] 跳过脚本不存在-f$Name)return}$sw[System.Diagnostics.Stopwatch]::StartNew()$p-KitRoot$KitRoot-OutDir$OutDir|Out-Host$code$LASTEXITCODE$sw.Stop()$rec.ran $true$rec.exit_code $code$rec.seconds [math]::Round($sw.Elapsed.TotalSeconds,1)$rec.verdict if($code-eq$ExpectedExit){PASS}else{FAIL}$rec.detail if($code-eq$ExpectedExit){}else{(期望退出码 {0}实际 {1}-f$ExpectedExit,$code)}$results.Add($rec)|Out-NullWrite-Host([{0}] {1}退出码 {2}耗时 {3}s-f$Name,$rec.verdict,$code,$rec.seconds)}# ---- 冒烟层0 表示工具箱可加载且环境可判定 ----if($Level-in(smoke,all)){Run-Layersmoketest\smoke.ps10}# ---- 契约层0 表示全部返回契约符合 ----if($Level-in(contract,all)){Run-Layercontracttest\contract.ps10}# ---- 端到端层0 表示最小完整流程产出且核验通过 ----if($Level-in(e2e,all)){Run-Layere2etest\e2e.ps10}# ---- 验收层0 表示项目验收标准全部满足 ----if($Level-eqall){Run-Layeracceptancetest\acceptance.ps10}$results|Export-Csv-LiteralPath(Join-Path$OutDirregress_result.csv)-NoTypeInformation-Encoding UTF8$failed ($results|Where-Object{$_.verdict-eqFAIL})$skipped ($results|Where-Object{$_.verdict-eqSKIP_NO_SCRIPT})Write-HostWrite-Host(回归结果通过 {0} / 失败 {1} / 跳过 {2}-f (($results|Where-Object{$_.verdict-eqPASS}).Count),$failed.Count,$skipped.Count)if($failed.Count-gt0){Write-Host失败项$failed|ForEach-Object{Write-Host( - {0}: {1}-f$_.layer,$_.detail)}Write-Host★ 回归未通过禁止交付也禁止在原环境做进一步修改。exit1}if($skipped.Count-gt0){Write-Host★ 有层被跳过脚本缺失当前结果不能作为交付依据。exit3}Write-Host回归全部通过。请把 regress_result.csv 连同交付包一起交接。exit0逐行剖析“失败即汇总、不中断”Run-Layer不抛异常也不 return所有层都跑完再汇总。理由回归的价值在于一次看到全部问题如果第一层失败就中断你修完再跑再发现第二层也坏了——迭代次数翻倍。每层都有一个显式的期望退出码$ExpectedExit把什么叫成功写成参数。这是本系列从头到尾的纪律在回归层的体现——看起来正常不是判定标准。SKIP_NO_SCRIPT是一个独立结论而不是 PASS脚本缺失时绝不能算通过。并且专门打印一句当前结果不能作为交付依据退出码 3。这是没测与测过没问题的区分——这个区分在本系列里出现了至少四次第 09 篇 STALE、第 11 篇假空碰撞、第 18 篇 STALE、第 19 篇无变更它是全系列最一致的一条思维习惯。耗时被记录进结果表seconds列用于监控回归是否在变得太慢。当端到端从 30 秒涨到 10 分钟时就是该拆分的时候了——否则回归会先被跳过然后被遗忘。regress_result.csv随交付包交接1.5 节验证资产它是这套工具箱在某台机器上是好的这一论断的证据。结尾那句禁止交付也禁止在原环境做进一步修改第二条同样重要——回归失败时继续改代码会让下次回归也说不清是新改动引入的还是原本就坏的。代码 20-3交付清单Markdown交接包的索引# 交付清单 · e3d_devkit 版本号 ## A 环境事实必须交 - [ ] 00_env/out/probe_install.csv安装与运行时 - [ ] 00_env/out/pml_lib_census.csvPMLLIB 与命名冲突 - [ ] 00_env/out/asm_identity.csv.NET 程序集身份如启用 .NET 通道 - [ ] 一行结论产品代际与版本 / 模块 / 权限范围 ## B 能力边界必须交 - [ ] 支持的产品与版本范围填写 - [ ] 明确不支持逐条填写 - [ ] 已确认的官方章节引用清单PML/DBRM/DRAW/IFC 等 ## C 代码资产 - [ ] 五层目录10_pml / 20_ui / 30_rules / 40_run / 50_deliver - [ ] 生成物清单及其源rules.pmlf ← rules.csv - [ ] 版本函数输出!!MYCO_LibVersion() 实际返回值 ## D 配置资产最易漏交 - [ ] rules.csv / dq_rules.csv / draw_manifest.csv / contract.csv / data_dictionary.json - [ ] 每份配置的负责人 依据文件 最近变更日期 ## E 纪律资产最易漏交 - [ ] 铁律与评审要点12 条提问 - [ ] 卸载说明每一处加对应的减 - [ ] 代际差异标注约定-- VER-DIFF: ## F 验证资产 - [ ] test/regress_result.csv最近一次回归 - [ ] test/acceptance 结果 - [ ] 已知未通过项及其原因与计划 ## G 运行资产 - [ ] jobs_ledger.csv作业账本 - [ ] model_ledger.csv模型/数据台账如启用模型 - [ ] 最近一次发布记录发布版本号 时间 内容逐项剖析A、B 两组放在最前因为它们是接手人第一天最需要的东西先知道在哪跑、能跑到什么程度代码才有意义。D、E 两组标注最易漏交1.5 节。这是把经验写成流程的形态——漏交这两组的原因不是疏忽而是代码看得见、规则看不见的认知偏差。标注出来评审时就会被专门检查。B 组第 2 条明确不支持是刻意的一份只写支持什么的说明会诱导过度期待。写明不支持什么是专业交付姿态的一部分。F 组第 3 条已知未通过项及其原因与计划允许交付有未通过项但不允许未记录的未通过项。这条让交付可以推进现实项目里很难全绿同时保留诚实。G 组的最近一次发布记录把第 19 篇的发布版本概念延伸到整个工具箱——接手人应该能一眼看到这个工具最近产出了什么、什么时候。三、常见报错与排查报错 3-1产品升级后工具箱部分功能不好使但不知道影响面。现象升级后故障。根因没有升级前后的可比基线第 08、13 篇的清单没有留存。解法升级前后各跑一次环境探测与回归用asm_identity.csv程序集身份、type_census.csv公开类型、pml_lib_census.csvPMLLIB 内容做差分把升级评估作为一条固定流程——对应官方 “Minimising Problems for Future Upgrades” 一节的立场。报错 3-2想停用某个功能但菜单里删不掉、命令还在跑。现象卸不干净。根因只写了加没写减——官方为此专门提供了 Removing Menu Items、Removing Gadgets from a Toolbar、Killing a Command、Hiding Forms when Exiting Applications 等机制第 08 篇但实现时容易只做一半。解法在开发阶段就把卸载路径作为该功能的一部分实现并在docs/卸载说明.md里逐项列出回归里加一项卸载后重装能正常的检查。报错 3-3接手人说看不懂这个规则为什么这么定。现象无法维护。根因规则缺basis依据列或依据文件没有被交接。解法规则表强制basis与owner非空第 17 篇构建脚本已强制交付时把依据文件设计规定、等级管理规定等的编号与版本一起交不必交全文但必须可追溯评审时把依据能不能查到作为检查项。报错 3-4双轨维护变成两份代码各改一遍。现象维护量翻倍。根因把 ③④⑤ 层也复制成了两份1.3 节。解法规则层、字典层、批处理层、交付层完全共用只在数据访问层做单点分叉版本判定收敛到少数函数差异用统一标记-- VER-DIFF:显式化自检里输出当前以哪条轨运行。报错 3-5回归越来越慢最后被跳过。现象回归失效。根因端到端层把全量模型当测试范围或者把 UI 相关的检查都塞了进来。解法端到端用一个极小范围几十个元素做冒烟式的全流程验证只测三层1.4 节记录每层耗时代码 20-2 的seconds列并在超过阈值时告警把回归必须能在几分钟内跑完作为架构约束而不是愿望。四、动手练习练习 1骨架落地按代码 20-1 建立目录骨架把前 19 篇你实际完成的脚本按层归位。判定标准五层目录都存在且非空30_rules/rules.pmlf被明确标注为生成物docs/下三个文件存在哪怕是初稿。归位过程中若发现某个脚本不知道该放哪层把它记下来——这正是你架构还没想清的地方。练习 2一键回归实现test/smoke.ps1、test/contract.ps1、test/e2e.ps1三个最小版本每个只要 5~20 行能做出一项可自动判定的检查即可然后用代码 20-2 跑一次。判定标准三层都执行且退出码符合预期regress_result.csv含layer / exit_code / verdict / seconds四列故意让契约层失败改掉一个契约前缀总判定必须为失败且退出码为 1。练习 3卸载演练按docs/卸载说明.md完整卸载工具箱移除菜单项、移除工具条 gadget、Killing 命令、隐藏表单然后重新安装。判定标准卸载后产品原有功能不受影响用任一原有菜单命令验证重新安装后工具箱功能全部恢复正常跑一次回归。两次操作都要在笔记里记录实际步骤——卸载说明写不下去的地方就是卸载实现不完整的地方。练习 4交付清单按代码 20-3 填一份完整清单A~G 七组。判定标准七组全部有勾选项D、E 组逐项填写不许写见代码F 组注明最近一次回归的时间与结果G 组包含最近一次发布记录。填完后请一名未参与开发的同事按清单在另一台机器上只看清单复现一次工具箱的安装与运行记录他卡住的每一步。思考题无标准答案为什么能不能交给第二个人维护是判断工具箱好坏的最终标准而不是功能是否强大验证要点① 一个功能强大但只有作者能改的工具在作者调岗后的实际处境② 规则在 CSV、依据有列、版本有函数、卸载有说明这四件事分别降低了接手人的哪一类成本③ 如果你现在要交接自己写的工具最可能被漏交的是哪一类资产对照 20-3 清单自检。五、小结与全系列收束工具箱的本质是把会变化的东西分层隔离环境探测层越稳定越靠下、数据访问层、规则层、批处理层、交付层。判断它好不好只看三条——能不能整体卸载、能不能一键回归、能不能交给第二个人维护。PDMS 已于 2024 年 4 月 1 日停售停支持双轨的现实成本远低于直觉因为五层里只有数据访问与探测两层是产品相关的控制双轨失控靠三条差异显式化、公共部分最大化、单点分叉。回归只测三层冒烟、契约、端到端并坚持没测 ≠ 测过没问题。交付清单七组里配置资产与纪律资产最容易漏交也最决定接手人三个月后是否骂人。全系列回顾三十句三维工厂设计的交付物全部源自模型所以模型侧的规范化会被交付物放大第 01 篇PML 只有两条官方通道PML 与 .NET APIPML 的能被找到由搜索路径与索引决定第 02 篇代码形态三层递进、判据是会不会被调用第二次第 03 篇表达式有类型、单位是语言层面的事、数组可稀疏且无负下标第 04 篇数据是以 WORLD 为根的树!!CE是会话状态必须保护现场第 05 篇属性分标准/UDA/伪属性ATTLIS 是区分没填与写错的唯一手段第 06 篇gadget 不支持自定义成员所以界面必须与逻辑分层第 07 篇每一处加都要有减第 08 篇幂等判据要放模型里产出物核验要能识别 STALE第 09 篇目录数据只存一份所以对账只做待核对清单第 10 篇碰撞判定取决于 OBST 与容差规则类代码的头号陷阱是 RESULT 默认值写反第 11 篇IFC 导出有完全可编程的官方 PML 对象第 12 篇.NET 通道的正确起点是反射清点而非猜测第 13 篇PMLNETCALLABLE 让特征契约成为接口第 14 篇接口成功不等于数据正确日志里的假设才是真凭据第 15 篇双向同步必须先定主属侧第 16 篇只读内核加外部规则表是检查工具的正确形态第 17 篇图纸目录必须由核验结果生成第 18 篇数据字典先行、快照不可变、变更集必须能重建第 19 篇而最后的最后——查不到就标注以官方文档为准绝不编造。本篇认知问题回显FAQQ1一堆脚本凭什么能组成工具箱A靠分层。把会变化的东西按稳定性分层隔离环境探测层安装位置、部署方式、升级节奏会变、数据访问层产品版本、属性名、导航语法会变、规则层业务规定与阈值会变、批处理层调度与并发策略会变、交付层格式与接收方要求会变。越靠下越稳定上层依赖下层提供的事实因此结构本身表达了依赖方向。Q2为什么环境探测层排在最下面A因为上面四层的一切判断都建立在它提供的事实上数据访问层要确认属性名是否存在、规则层要确认依据文件的版本、批处理层要知道连接了哪个库与权限范围、交付层要记录产出物对应的产品版本。环境探测清单如 probe_install.csv、pml_lib_census.csv、asm_identity.csv是工具箱的地基而且必须作为交付物随包交接不能只交脚本。Q3PDMS 已停售停支持为什么还要做双轨A因为存量项目不会因产品停售而消失老项目仍在原环境维护、新项目按 E3D Design 建设。双轨的实际成本远低于直觉五层里只有环境探测层与数据访问层是产品相关的规则层、批处理层与交付层完全共用。控制双轨失控靠三条原则差异显式化统一标记并让自检输出当前判定、公共部分最大化上下三层不复制、单点分叉差异收敛到少数函数。Q4回归测试要测什么、测多少A只测三层冒烟层能否加载、版本函数能否返回、PMLLIB 是否含本工具箱目录、契约层核心函数的返回契约是否符合三态前缀与字段位置、端到端层一条最小完整流程选小范围、跑检查、产出报告、核验报告。不测内部函数细节逻辑、UI 视觉效果与极端输入组合因为维护成本高于收益。回归触发时机是工具箱改动后、产品升级前后各一次、以及交付前。Q5交付清单要交什么才让接手人不骂人A七组环境事实、能力边界含明确的不支持清单、代码资产、配置资产规则表、字典、清单、契约——最易漏交、纪律资产铁律与评审要点、卸载说明——最易漏交、验证资产最近一次回归结果与已知未通过项、运行资产作业账本、模型台账、最近发布记录。判断标准是接手人能否只看清单在另一台机器上完成安装与运行。 PDMS-AVEVA-E3D二次开发教程（20）：收官——PDMS/E3D 二次开发工具箱与交付体系
PDMS-AVEVA-E3D二次开发教程20收官——PDMS/E3D 二次开发工具箱与交付体系版本与事实声明产品锚点AVEVA E3D Design 为官方现名发布锚点 3.1.4.0 / 3.1.5.0当前版本以官方发布说明为准AVEVA PDMS自 2024 年 4 月 1 日起停止销售与技术支持。官方专设 “Minimising Problems for Future Upgrades” 与 “Serious Warning About Software Customisation” 两节——软件定制会影响未来升级这是本篇架构设计的根本约束而非免责声明。本篇不引入任何新语法全部代码是前 19 篇已给出来源的标准 PowerShell / PML 组织方式。示例目录名、版本号、清单条目均为示例性数据。一句话结论一个可维护的 E3D 二次开发工具箱由五层构成——环境探测层先说清我在哪跑、数据访问层只读优先、规则层规则是数据不是代码、批处理层幂等与账本、交付层产出物必须自证判断一套工具箱好不好不看功能多少只看三件事能不能整体卸载、能不能一键回归、能不能交给第二个人维护。〇、认知问题Q119 篇写下来的函数与脚本凭什么能组成为一个工具箱而不是一堆文件Q2五层架构里为什么环境探测层必须排在最下面而不是最上面Q3PDMS 已停售停支持迁移期为什么还要做双轨双轨怎么做才不失控Q4回归测试要测什么测多少才够Q5一份交付清单到底要交什么才能让接手的人不骂人一、机制解析1.1 五层架构每一层解决一类会变化的东西工具箱的本质不是功能集合而是把会变化的东西分层隔离。五层的划法如下┌─────────────────────────────────────────────────────────────────┐ │ ⑤ 交付层 Delivery │ │ 图纸目录/快照发布/DQ 报告/交接报告/产出物核验 │ │ 会变的交付格式、命名规则、接收方要求 │ ├─────────────────────────────────────────────────────────────────┤ │ ④ 批处理层 Batch │ │ 作业编排/幂等/账本/重试/环境检查/进度与中断 │ │ 会变的调度方式、运行时段、并发策略 │ ├─────────────────────────────────────────────────────────────────┤ │ ③ 规则层 Rules │ │ 规则表(CSV/JSON)/数据字典/契约表/清单 │ │ 会变的业务规定、阈值、依据文件 │ ├─────────────────────────────────────────────────────────────────┤ │ ② 数据访问层 Access │ │ 只读校验器/范围裁剪/属性读写/三态契约/现场保护 │ │ 会变的产品版本、属性名、导航语法、模块差异 │ ├─────────────────────────────────────────────────────────────────┤ │ ① 环境探测层 Probe │ │ 产品与版本/PMLLIB/程序集清点/权限与会话/能力清单 │ │ 会变的安装位置、部署方式、升级节奏 │ └─────────────────────────────────────────────────────────────────┘ ▲ 全部层都向上依赖这一层的事实为什么环境探测层排在最下面而不是最上面因为上面四层的一切判断都建立在它提供的事实上——数据访问层要问这个属性名在这个版本上存在吗第 02、06 篇的ATTLIS规则层要问这条规则的依据文件在哪个版本有效第 17 篇的basis列批处理层要问我连的是哪个库、有没有 Claim 权限第 09 篇的四段结构第一段交付层要问产出物对应的产品版本是多少第 18、19 篇的元数据文件。排在最下面是对依赖方向的物理表达越靠下越稳定、越靠上越易变。第 02 篇的e3d_env_inventory.csv、第 13 篇的dotnet_inventory.csv就是这个地基。1.2 判断工具箱好坏的三条标准前面 19 篇给了一堆最佳实践但它们都是局部的。用全局视角看一套工具箱只有三条硬标准标准判据可操作对应篇章能不能整体卸载每一处加都有对应的减菜单项可移除、工具条 gadget 可移除、命令可 Killing、表单可隐藏、字段可释放第 08 篇官方 Removing/Killing 类机制能不能一键回归有一条命令跑完全部自检与验收输出通过/未通过清单第 08、17 篇MYCO_LibSelfTest、acceptance.ps1能不能交给第二个人维护规则在 CSV 里、字典在 JSON 里、依据有列、版本有函数、卸载有说明第 16、17、19 篇为什么是这三条而不是功能多不多因为工具箱的寿命取决于这三条。功能多但不可卸载的定制产品升级一次就废不可回归的定制第二次改动就没人敢动不可交接的定制作者离职即失传。官方那句Minimising Problems for Future Upgrades想说的就是这件事。1.3 迁移期双轨PDMS 与 E3D Design官方事实AVEVA PDMS 已被 AVEVA E3D Design 取代并自 2024 年 4 月 1 日起停止销售与技术支持“AVEVA Everything3D is now AVEVA E3D Design”。为什么还要做双轨因为设计院里的存量项目不会因为产品停售而消失——老项目仍要在原环境上维护新项目按 E3D Design 建设。工具箱必须同时服务两者否则会出现老项目没人管或新项目从零重写。双轨的三条控制原则控制的是不要让它失控而不是不要做原则做法失控的表现要避免差异显式化代码里凡涉及两代差异处用统一注释标记如-- VER-DIFF: PDMS 12.x / E3D Design并在自检里输出当前判定靠人记差异 → 每次都在猜公共部分最大化规则层、字典层、交付层完全共用它们不依赖产品版本仅数据访问层与探测层分叉上下都复制两份 → 维护量翻倍单点分叉数据访问层里凡有差异的能力导航、写属性、文件 I/O收敛到少数几个函数做版本判定差异散落各处 → 无法说清支持哪些版本关键洞察五层里只有 ①② 两层是产品相关的③④⑤ 三层是工程相关的。所以双轨的实际成本远低于直觉——只要 ③④⑤ 不复制双轨就是可承受的。最佳实践在工具箱自检里输出一行当前环境判定例如env: familyE3DDesign / version实际版本 / runtimedetected让这套工具箱在某台机器上以哪条轨运行成为可见事实。1.4 回归测试测三层不测全部回归测试不是把每个函数都测一遍成本太高、维护不了。只需要测三层层次测什么为什么只测这些冒烟层能否加载、版本函数能否返回、PMLLIB 是否含本工具箱目录加载失败是最常见故障且一秒可判契约层核心函数的返回契约是否符合三态前缀、字段数量与位置契约变化会静默破坏所有下游解析器端到端层一条最小完整流程选一个小范围 → 跑检查 → 产出报告 → 核验报告它覆盖了 90% 的集成问题且能自动判定不测的部分单个内部函数的细节逻辑、UI 的视觉效果、极端输入组合。理由这些测试的维护成本高于其收益把有限精力放在契约与端到端上回归才跑得起来、才会有人跑。回归的触发时机三条工具箱自身改动后产品升级前后各一次这是最重要的一次用于评估影响面交付前作为交付清单的一个必过项。1.5 交付清单交给接手人的东西第 02 篇讲了环境清单、第 08 篇讲了升级自查、第 19 篇讲了数据发布。交付清单是把这些清单合并成一份交接包类别交付内容为什么必须交环境事实环境探测清单产品/版本/路径/权限/程序集没有它接手人不知道在哪跑能力边界支持的产品代际与版本范围、明确不支持的场景没有它接手人会以为什么都能干代码资产五层目录、生成物、构建脚本、版本函数代码本身配置资产规则表、数据字典、契约表、图纸清单这是业务可维护的部分最容易被漏交纪律资产铁律清单、代码评审要点、卸载说明没有它接手人会把工具箱改坏验证资产回归脚本、验收脚本、最近一次回归结果没有它接手人不敢动运行资产运行账本、模型/数据台账、最近发布记录用于追溯上次跑到哪最容易被漏交的是配置资产与纪律资产——因为代码看得见规则与规矩看不见。但恰恰是这两类决定接手人能不能在三个月后还不骂人。1.6 团队规范与评审要点浓缩成一张表20 篇下来团队规范其实就这些。把它做成评审时的检查表#评审提问不通过的表现1这段逻辑会被调用第二次吗是就写成函数业务逻辑写在宏里2这段代码改了!!ce吗改了就在两个出口都还原只还原正常出口3属性名从哪来核对过ATTLIS吗凭记忆写属性名4数值带单位吗裸数值参与比较5判存在用的是Defined()还是值判空用取值判空0 被误判6批量脚本报了几个计数加起来自洽吗只返回Success7失败信息里有没有该怎么办只有失败三个字8这个动作在离线副本上验证过吗直接在生产库首次运行9有没有对应的卸载路径只加不减10规则/阈值/依据写在哪业务能改吗埋在代码里11这一段是 PML 该做的吗第 13 篇五条判据用 .NET 做界面12用了官方还是臆测的语法网上抄来未核对的写法第 12 条是元规则它是前 11 条之所以可靠的保证。官方文档查不到就标注以官方文档为准并给出章节定位——这条纪律比任何一条语法规则都重要因为语法会变、会被记错而知道去哪查的能力不会。1.7 八条铁律收官回顾全系列确立的八条铁律全系列不超过 10 条其余为最佳实践与经验法则#铁律一句话记法1语法只写官方手册记载的形态查不到就指向官方章节宁缺毋编2单位与属性必显式数值必带单位3先探测环境再运行先说清在哪跑4破坏性操作先离线验证副本先行5对接必声明边界与版本写清谁算哪段6PDMS 与 E3D Design 差异必须显式标注代际差异不许含糊7不混写产品能力无PML 内嵌 Python不把 APS 能力安到 E3D 上不张冠李戴8示例数据必标注示例不等于规定二、完整代码与逐行剖析代码 20-1工具箱目录骨架结构即架构e3d_devkit/ ├── README.md # 工具箱总览能力边界 / 支持版本 / 安装步骤 / 卸载步骤 ├── CHANGELOG.md # 每个版本改了什么含规则表变更 ├── 00_env/ # ① 环境探测层 │ ├── probe_install.ps1 # 安装与运行时盘点第 01/02 篇 │ ├── pml_lib_census.ps1 # PMLLIB 内容与命名冲突普查第 02 篇 │ ├── asm_identity.ps1 # .NET 程序集身份清点第 13 篇 │ ├── type_census.ps1 # 公开类型清点第 13 篇 │ └── out/ # 探测产物CSV随交付一起交 ├── 10_pml/ # ② 数据访问层PML │ ├── lib_version.pmlf # 版本函数第 08 篇 │ ├── lib_selftest.pmlf # 依赖自检第 08 篇 │ ├── nav_helpers.pmlf # 导航辅助按官方 DBRM2.03.x 实现第 05 篇 │ ├── lint_core.pmlf # 只读检查内核第 06/17 篇 │ ├── ifc_export.pmlf # IFC 导出封装第 12 篇 │ ├── draw_batch.pmlf # 批量导出作业第 18 篇 │ └── rules.pmlf # 【生成物】由 30_rules 构建勿手改 ├── 20_ui/ # ② 层的界面部分 │ ├── lint_ui.pmlfrm # 表单第 07 篇 │ └── commands.pmlf # 命令定义与装配/卸载第 08 篇 ├── 30_rules/ # ③ 规则层业务可维护 │ ├── rules.csv # 检查规则表第 17 篇 │ ├── data_dictionary.json # 数据字典第 19 篇 │ ├── dq_rules.csv # 数据质量规则第 19 篇 │ ├── draw_manifest.csv # 图纸清单第 18 篇 │ ├── contract.csv # 跨专业数据契约第 16 篇 │ ├── gen_rules.ps1 # 构建脚本CSV - rules.pmlf第 17 篇 │ └── apply_pml.ps1 # 构建物落盘到 PMLLIB 目录 提示索引重建 ├── 40_run/ # ④ 批处理层 │ ├── run_lint.ps1 # 检查作业入口第 09/17 篇 │ ├── run_draw.ps1 # 出图作业入口第 18 篇 │ ├── run_snapshot.ps1 # 快照作业入口第 19 篇 │ ├── job_ledger.ps1 # 作业账本第 09 篇 │ └── verify_outputs.ps1 # 产出物核验第 09/12/18 篇 ├── 50_deliver/ # ⑤ 交付层 │ ├── gen_index.ps1 # 图纸目录生成第 18 篇 │ ├── dq_check.ps1 # 数据质量检查第 19 篇 │ ├── snapshot_diff.ps1 # 快照差分与变更集第 19 篇 │ └── release.ps1 # 打包一次发布字典快照元数据DQ ├── test/ │ ├── smoke.ps1 # 冒烟层回归第 20 篇 1.4 节 │ ├── contract.ps1 # 契约层回归 │ ├── e2e.ps1 # 端到端回归 │ └── acceptance.ps1 # 项目级验收第 17 篇 └── docs/ ├── 交付清单.md # 本篇 1.5 节的落地交接包索引 ├── 铁律与评审要点.md # 本篇 1.6 节的落地 └── 卸载说明.md # 本篇 1.2 节第 1 条的落地逐行剖析目录编号00_/10_/20_…直接对应五层顺序编号让依赖方向在文件管理器的排序里就可读——排在上面的层依赖排在下层的事实。这是结构即架构的最省事表达方式。00_env/out/的探测产物随交付一起交这是 1.5 节环境事实必须是交付物的落地。很多团队把探测脚本交了、产物留在自己机器上接手人得先跑一遍才知道情况——而这恰恰是最容易卡住的地方。10_pml/rules.pmlf明确标注为生成物且构建脚本在30_rules/生成物与它的源放在不同层源在规则层产物在数据访问层。这个安排逼着人思考我改的是源还是产物从目录结构上防止手改生成物第 17 篇报错 3-2。docs/卸载说明.md是独立文件卸载路径不能只写在代码注释里。它是能不能整体卸载这条标准的物理载体1.2 节。一个没有卸载说明的定制在产品升级时的处理方式通常是不管它——然后升级出问题。test/分四个脚本对应四个层级冒烟/契约/端到端/验收分层让回归可以只跑需要的部分改了一个 PML 函数跑冒烟契约改了端到端流程跑全部。一次要跑十分钟的回归很快就不会有人跑。代码 20-2一键回归PowerShell可运行# -*- coding: utf-8 -*-# regress.ps1 —— 工具箱一键回归冒烟 / 契约 / 端到端 / 验收 设计要点 * 分层执行失败即汇总不中断最后给出总判定 * 每一层都有可自动判定的成功标准不允许看起来正常 * 结果同时输出给人看屏幕与给机器看regress_result.csv 用法 .\regress.ps1 -KitRoot . -Level all #param([Parameter(Mandatory$true)][string]$KitRoot,[ValidateSet(smoke,contract,e2e,all)][string]$Levelall,[string]$OutDir.\test\out)$ErrorActionPreferenceSilentlyContinueif(-not(Test-Path-LiteralPath$OutDir)){New-Item-ItemType Directory-Path$OutDir|Out-Null}$resultsNew-ObjectSystem.Collections.Generic.List[object]functionRun-Layer{param([string]$Name,[string]$Script,[int]$ExpectedExit)$rec[pscustomobject]{layer $Name;script $Script;ran $falseexit_code ;verdict ;detail ;seconds 0}$pJoin-Path$KitRoot$Scriptif(-not(Test-Path-LiteralPath$p)){$rec.verdict SKIP_NO_SCRIPT;$rec.detail 未提供$Script$results.Add($rec)|Out-NullWrite-Host([{0}] 跳过脚本不存在-f$Name)return}$sw[System.Diagnostics.Stopwatch]::StartNew()$p-KitRoot$KitRoot-OutDir$OutDir|Out-Host$code$LASTEXITCODE$sw.Stop()$rec.ran $true$rec.exit_code $code$rec.seconds [math]::Round($sw.Elapsed.TotalSeconds,1)$rec.verdict if($code-eq$ExpectedExit){PASS}else{FAIL}$rec.detail if($code-eq$ExpectedExit){}else{(期望退出码 {0}实际 {1}-f$ExpectedExit,$code)}$results.Add($rec)|Out-NullWrite-Host([{0}] {1}退出码 {2}耗时 {3}s-f$Name,$rec.verdict,$code,$rec.seconds)}# ---- 冒烟层0 表示工具箱可加载且环境可判定 ----if($Level-in(smoke,all)){Run-Layersmoketest\smoke.ps10}# ---- 契约层0 表示全部返回契约符合 ----if($Level-in(contract,all)){Run-Layercontracttest\contract.ps10}# ---- 端到端层0 表示最小完整流程产出且核验通过 ----if($Level-in(e2e,all)){Run-Layere2etest\e2e.ps10}# ---- 验收层0 表示项目验收标准全部满足 ----if($Level-eqall){Run-Layeracceptancetest\acceptance.ps10}$results|Export-Csv-LiteralPath(Join-Path$OutDirregress_result.csv)-NoTypeInformation-Encoding UTF8$failed ($results|Where-Object{$_.verdict-eqFAIL})$skipped ($results|Where-Object{$_.verdict-eqSKIP_NO_SCRIPT})Write-HostWrite-Host(回归结果通过 {0} / 失败 {1} / 跳过 {2}-f (($results|Where-Object{$_.verdict-eqPASS}).Count),$failed.Count,$skipped.Count)if($failed.Count-gt0){Write-Host失败项$failed|ForEach-Object{Write-Host( - {0}: {1}-f$_.layer,$_.detail)}Write-Host★ 回归未通过禁止交付也禁止在原环境做进一步修改。exit1}if($skipped.Count-gt0){Write-Host★ 有层被跳过脚本缺失当前结果不能作为交付依据。exit3}Write-Host回归全部通过。请把 regress_result.csv 连同交付包一起交接。exit0逐行剖析“失败即汇总、不中断”Run-Layer不抛异常也不 return所有层都跑完再汇总。理由回归的价值在于一次看到全部问题如果第一层失败就中断你修完再跑再发现第二层也坏了——迭代次数翻倍。每层都有一个显式的期望退出码$ExpectedExit把什么叫成功写成参数。这是本系列从头到尾的纪律在回归层的体现——看起来正常不是判定标准。SKIP_NO_SCRIPT是一个独立结论而不是 PASS脚本缺失时绝不能算通过。并且专门打印一句当前结果不能作为交付依据退出码 3。这是没测与测过没问题的区分——这个区分在本系列里出现了至少四次第 09 篇 STALE、第 11 篇假空碰撞、第 18 篇 STALE、第 19 篇无变更它是全系列最一致的一条思维习惯。耗时被记录进结果表seconds列用于监控回归是否在变得太慢。当端到端从 30 秒涨到 10 分钟时就是该拆分的时候了——否则回归会先被跳过然后被遗忘。regress_result.csv随交付包交接1.5 节验证资产它是这套工具箱在某台机器上是好的这一论断的证据。结尾那句禁止交付也禁止在原环境做进一步修改第二条同样重要——回归失败时继续改代码会让下次回归也说不清是新改动引入的还是原本就坏的。代码 20-3交付清单Markdown交接包的索引# 交付清单 · e3d_devkit 版本号 ## A 环境事实必须交 - [ ] 00_env/out/probe_install.csv安装与运行时 - [ ] 00_env/out/pml_lib_census.csvPMLLIB 与命名冲突 - [ ] 00_env/out/asm_identity.csv.NET 程序集身份如启用 .NET 通道 - [ ] 一行结论产品代际与版本 / 模块 / 权限范围 ## B 能力边界必须交 - [ ] 支持的产品与版本范围填写 - [ ] 明确不支持逐条填写 - [ ] 已确认的官方章节引用清单PML/DBRM/DRAW/IFC 等 ## C 代码资产 - [ ] 五层目录10_pml / 20_ui / 30_rules / 40_run / 50_deliver - [ ] 生成物清单及其源rules.pmlf ← rules.csv - [ ] 版本函数输出!!MYCO_LibVersion() 实际返回值 ## D 配置资产最易漏交 - [ ] rules.csv / dq_rules.csv / draw_manifest.csv / contract.csv / data_dictionary.json - [ ] 每份配置的负责人 依据文件 最近变更日期 ## E 纪律资产最易漏交 - [ ] 铁律与评审要点12 条提问 - [ ] 卸载说明每一处加对应的减 - [ ] 代际差异标注约定-- VER-DIFF: ## F 验证资产 - [ ] test/regress_result.csv最近一次回归 - [ ] test/acceptance 结果 - [ ] 已知未通过项及其原因与计划 ## G 运行资产 - [ ] jobs_ledger.csv作业账本 - [ ] model_ledger.csv模型/数据台账如启用模型 - [ ] 最近一次发布记录发布版本号 时间 内容逐项剖析A、B 两组放在最前因为它们是接手人第一天最需要的东西先知道在哪跑、能跑到什么程度代码才有意义。D、E 两组标注最易漏交1.5 节。这是把经验写成流程的形态——漏交这两组的原因不是疏忽而是代码看得见、规则看不见的认知偏差。标注出来评审时就会被专门检查。B 组第 2 条明确不支持是刻意的一份只写支持什么的说明会诱导过度期待。写明不支持什么是专业交付姿态的一部分。F 组第 3 条已知未通过项及其原因与计划允许交付有未通过项但不允许未记录的未通过项。这条让交付可以推进现实项目里很难全绿同时保留诚实。G 组的最近一次发布记录把第 19 篇的发布版本概念延伸到整个工具箱——接手人应该能一眼看到这个工具最近产出了什么、什么时候。三、常见报错与排查报错 3-1产品升级后工具箱部分功能不好使但不知道影响面。现象升级后故障。根因没有升级前后的可比基线第 08、13 篇的清单没有留存。解法升级前后各跑一次环境探测与回归用asm_identity.csv程序集身份、type_census.csv公开类型、pml_lib_census.csvPMLLIB 内容做差分把升级评估作为一条固定流程——对应官方 “Minimising Problems for Future Upgrades” 一节的立场。报错 3-2想停用某个功能但菜单里删不掉、命令还在跑。现象卸不干净。根因只写了加没写减——官方为此专门提供了 Removing Menu Items、Removing Gadgets from a Toolbar、Killing a Command、Hiding Forms when Exiting Applications 等机制第 08 篇但实现时容易只做一半。解法在开发阶段就把卸载路径作为该功能的一部分实现并在docs/卸载说明.md里逐项列出回归里加一项卸载后重装能正常的检查。报错 3-3接手人说看不懂这个规则为什么这么定。现象无法维护。根因规则缺basis依据列或依据文件没有被交接。解法规则表强制basis与owner非空第 17 篇构建脚本已强制交付时把依据文件设计规定、等级管理规定等的编号与版本一起交不必交全文但必须可追溯评审时把依据能不能查到作为检查项。报错 3-4双轨维护变成两份代码各改一遍。现象维护量翻倍。根因把 ③④⑤ 层也复制成了两份1.3 节。解法规则层、字典层、批处理层、交付层完全共用只在数据访问层做单点分叉版本判定收敛到少数函数差异用统一标记-- VER-DIFF:显式化自检里输出当前以哪条轨运行。报错 3-5回归越来越慢最后被跳过。现象回归失效。根因端到端层把全量模型当测试范围或者把 UI 相关的检查都塞了进来。解法端到端用一个极小范围几十个元素做冒烟式的全流程验证只测三层1.4 节记录每层耗时代码 20-2 的seconds列并在超过阈值时告警把回归必须能在几分钟内跑完作为架构约束而不是愿望。四、动手练习练习 1骨架落地按代码 20-1 建立目录骨架把前 19 篇你实际完成的脚本按层归位。判定标准五层目录都存在且非空30_rules/rules.pmlf被明确标注为生成物docs/下三个文件存在哪怕是初稿。归位过程中若发现某个脚本不知道该放哪层把它记下来——这正是你架构还没想清的地方。练习 2一键回归实现test/smoke.ps1、test/contract.ps1、test/e2e.ps1三个最小版本每个只要 5~20 行能做出一项可自动判定的检查即可然后用代码 20-2 跑一次。判定标准三层都执行且退出码符合预期regress_result.csv含layer / exit_code / verdict / seconds四列故意让契约层失败改掉一个契约前缀总判定必须为失败且退出码为 1。练习 3卸载演练按docs/卸载说明.md完整卸载工具箱移除菜单项、移除工具条 gadget、Killing 命令、隐藏表单然后重新安装。判定标准卸载后产品原有功能不受影响用任一原有菜单命令验证重新安装后工具箱功能全部恢复正常跑一次回归。两次操作都要在笔记里记录实际步骤——卸载说明写不下去的地方就是卸载实现不完整的地方。练习 4交付清单按代码 20-3 填一份完整清单A~G 七组。判定标准七组全部有勾选项D、E 组逐项填写不许写见代码F 组注明最近一次回归的时间与结果G 组包含最近一次发布记录。填完后请一名未参与开发的同事按清单在另一台机器上只看清单复现一次工具箱的安装与运行记录他卡住的每一步。思考题无标准答案为什么能不能交给第二个人维护是判断工具箱好坏的最终标准而不是功能是否强大验证要点① 一个功能强大但只有作者能改的工具在作者调岗后的实际处境② 规则在 CSV、依据有列、版本有函数、卸载有说明这四件事分别降低了接手人的哪一类成本③ 如果你现在要交接自己写的工具最可能被漏交的是哪一类资产对照 20-3 清单自检。五、小结与全系列收束工具箱的本质是把会变化的东西分层隔离环境探测层越稳定越靠下、数据访问层、规则层、批处理层、交付层。判断它好不好只看三条——能不能整体卸载、能不能一键回归、能不能交给第二个人维护。PDMS 已于 2024 年 4 月 1 日停售停支持双轨的现实成本远低于直觉因为五层里只有数据访问与探测两层是产品相关的控制双轨失控靠三条差异显式化、公共部分最大化、单点分叉。回归只测三层冒烟、契约、端到端并坚持没测 ≠ 测过没问题。交付清单七组里配置资产与纪律资产最容易漏交也最决定接手人三个月后是否骂人。全系列回顾三十句三维工厂设计的交付物全部源自模型所以模型侧的规范化会被交付物放大第 01 篇PML 只有两条官方通道PML 与 .NET APIPML 的能被找到由搜索路径与索引决定第 02 篇代码形态三层递进、判据是会不会被调用第二次第 03 篇表达式有类型、单位是语言层面的事、数组可稀疏且无负下标第 04 篇数据是以 WORLD 为根的树!!CE是会话状态必须保护现场第 05 篇属性分标准/UDA/伪属性ATTLIS 是区分没填与写错的唯一手段第 06 篇gadget 不支持自定义成员所以界面必须与逻辑分层第 07 篇每一处加都要有减第 08 篇幂等判据要放模型里产出物核验要能识别 STALE第 09 篇目录数据只存一份所以对账只做待核对清单第 10 篇碰撞判定取决于 OBST 与容差规则类代码的头号陷阱是 RESULT 默认值写反第 11 篇IFC 导出有完全可编程的官方 PML 对象第 12 篇.NET 通道的正确起点是反射清点而非猜测第 13 篇PMLNETCALLABLE 让特征契约成为接口第 14 篇接口成功不等于数据正确日志里的假设才是真凭据第 15 篇双向同步必须先定主属侧第 16 篇只读内核加外部规则表是检查工具的正确形态第 17 篇图纸目录必须由核验结果生成第 18 篇数据字典先行、快照不可变、变更集必须能重建第 19 篇而最后的最后——查不到就标注以官方文档为准绝不编造。本篇认知问题回显FAQQ1一堆脚本凭什么能组成工具箱A靠分层。把会变化的东西按稳定性分层隔离环境探测层安装位置、部署方式、升级节奏会变、数据访问层产品版本、属性名、导航语法会变、规则层业务规定与阈值会变、批处理层调度与并发策略会变、交付层格式与接收方要求会变。越靠下越稳定上层依赖下层提供的事实因此结构本身表达了依赖方向。Q2为什么环境探测层排在最下面A因为上面四层的一切判断都建立在它提供的事实上数据访问层要确认属性名是否存在、规则层要确认依据文件的版本、批处理层要知道连接了哪个库与权限范围、交付层要记录产出物对应的产品版本。环境探测清单如 probe_install.csv、pml_lib_census.csv、asm_identity.csv是工具箱的地基而且必须作为交付物随包交接不能只交脚本。Q3PDMS 已停售停支持为什么还要做双轨A因为存量项目不会因产品停售而消失老项目仍在原环境维护、新项目按 E3D Design 建设。双轨的实际成本远低于直觉五层里只有环境探测层与数据访问层是产品相关的规则层、批处理层与交付层完全共用。控制双轨失控靠三条原则差异显式化统一标记并让自检输出当前判定、公共部分最大化上下三层不复制、单点分叉差异收敛到少数函数。Q4回归测试要测什么、测多少A只测三层冒烟层能否加载、版本函数能否返回、PMLLIB 是否含本工具箱目录、契约层核心函数的返回契约是否符合三态前缀与字段位置、端到端层一条最小完整流程选小范围、跑检查、产出报告、核验报告。不测内部函数细节逻辑、UI 视觉效果与极端输入组合因为维护成本高于收益。回归触发时机是工具箱改动后、产品升级前后各一次、以及交付前。Q5交付清单要交什么才让接手人不骂人A七组环境事实、能力边界含明确的不支持清单、代码资产、配置资产规则表、字典、清单、契约——最易漏交、纪律资产铁律与评审要点、卸载说明——最易漏交、验证资产最近一次回归结果与已知未通过项、运行资产作业账本、模型台账、最近发布记录。判断标准是接手人能否只看清单在另一台机器上完成安装与运行。