FRI 与 KG-TOWER 二次开发教程（16）：工程化——许可合规、版本对齐与可复现检查
版本与事实声明
- KG-TOWER 许可要点（官方协议原文）：许可是个人、非独占、不可转让、免版税；禁止修改、改动、翻译、反汇编或创建派生材料；不得移除专有标识；未经书面许可不得向 Koch-Glitsch 的竞争对手分发软件输出；软件按 “AS IS” 提供、无任何担保；受美国堪萨斯州法律管辖。
- 官方版本约束：PRO/II→KG-TOWER 工具"只适配官网当前下载的 KG-TOWER 版本"。
- FRI 的 DRP、关联式与两本 Handbook 属会员权益（底账 U1/U2）；可复现检查中的
sources只登记公开文献关联式编号。- 环境：Python 3.8+，仅标准库。
- 文中任何数值为示例性建模，不代表任何标准规定，不对应任何真实装置数据。
一句话结论：工程化在本文收敛为三个可执行检查——许可合规（不逆向、不派生、不向竞品分发输出）、版本成对（PRO/II 工具与 KG-TOWER 主次版本必须一致，示例 5.4.6↔5.4 通过、5.4.6↔5.3 报错）、可复现（sources与units必填）；示例的"问题清单"一次列出 5 条违规（版本未成对、license 未登记、intent 非法、缺 sources、缺 units），而受限关键词扫描在干净文件上零命中、在含"反编译取内部常数"的片段上报 1 条命中。
〇、本篇要解决的认知问题
- Q1：KG-TOWER 的许可红线在批处理工程里应该怎么落地？为什么"写进文档"不够？
- Q2：为什么 PRO/II 工具与 KG-TOWER 必须"成对升级"？工程上怎么强制？
- Q3："可复现检查"具体检查什么？为什么只查 sources 与 units 两项就够用？
- Q4：违规应该"逐条报错退出"还是"一次列全"？哪种更适合批量工程？
- Q5：为什么要对源文件做"受限关键词扫描"？它会误报吗？
一、机制解析
1.1 许可红线怎么"落地"：从文档到断言
为什么这对你重要：许可协议写在网页上，但违反它的行为发生在代码与流程里。把协议文本抄进 README 是无效治理——因为没人会在写代码前重读协议。有效做法是把每条红线变成可执行断言：
| 红线（官方协议） | 落地为 | 触发时机 |
|---|---|---|
| 禁止修改/改动/翻译/反汇编/创建派生材料 | 源码与文档的受限关键词扫描（网关） | 提交前 / CI |
| 未经书面许可不得向 Koch-Glitsch 竞争对手分发输出 | 运行清单的license（输出用途）必填+ 人工审批闸门 | 交付前 |
| PRO/II 工具只适配当前 KG-TOWER 版本 | 版本成对校验 | 批处理启动前 |
| “AS IS” 无担保 | 结果表带免责声明字段 | 报表生成时 |
本文重点实现前三条。第四条是报表模板的事（第 18 篇）。
1.2 版本成对的工程强制
官方明确工具"只适配官网当前下载的 KG-TOWER 版本"。所以工程上：
批处理启动 ├─ 读 run_manifest.tool_state ├─ 比较 kgtower 与 proii_tool 的主次版本（如 5.4） │ ├─ 一致 -> 继续 │ └─ 不一致 -> 硬失败，提示"请成对升级" └─ 记录版本对到结果元数据比较"主次版本"而非全串：注册页是5.4.6、工具页写5.4——全串比较会产生假告警；比较前两段（5.4）才既严格又可用。这是"校验器设计"里最常见的坑：过严的校验会被绕过（"这个总能过"变成口头常识），过松则失去意义。
1.3 可复现检查：为什么只查两项
第 02 篇我们列了run_manifest.json七项字段。但在检查器里，只把两项设为强制：
sources（关联式来源编号）：没有它，结果无法回溯是"哪套公式算的"（铁律 8）；units（单位集）：没有它，结果无法判断口径（铁律 5）。
其余字段（tool_state / intent / files / reports / license）各有其位置：tool_state用于版本成对、license用于许可闸门、intent用于字段可写性——它们也检查，但语义不同（有的是"必须存在"，有的是"必须取值合法"）。设计要点：把"必填"与"合法"分开，这样错误信息才能指到具体问题。
1.4 违规报告：一次列全 vs 逐条退出
| 策略 | 优点 | 缺点 | 适用 |
|---|---|---|---|
| 逐条退出（首个错误即停） | 实现简单 | 修一个跑一次，来回多轮 | 交互式调试 |
| 一次列全 | 一轮修完；适合 CI 与批量 | 实现稍复杂；错误多时信息量大 | 批量工程（推荐） |
示例输出的一次列全（5 条）：版本未成对、license 未登记、intent 非法、缺 sources、缺 units——一条不多、一条不少。这正是批量工程需要的形态：把"发现-修复"循环从 5 轮压到 1 轮。
1.5 受限关键词扫描：必要，但必须防误报
对源码/文档扫描"反编译/逆向/派生"等受限操作关键词，是最低成本的合规网关。但它有两类误报：
- 自指误报：定义关键词表的那一行本身就含关键词；
- 语境误报：文档在告诫读者不要做时也会出现这些词。
最佳实践：扫描器需支持"跳过定义行"（如按标记跳过），并在 CI 里对命中做人工确认而非直接阻断；同时把它与"许可闸门"（运行清单检查）分离——前者是"防止写错"，后者是"防止发错"。
二、完整代码与逐行剖析
代码 2-1：合规 + 版本 + 可复现 三合一检查器（可直接运行）
# -*- coding: utf-8 -*-""" compliance.py —— 工程化检查：许可合规、版本对齐、可复现 KG-TOWER 许可红线（官方协议）：禁止修改/改动/翻译/反汇编/创建派生材料； 禁止未经书面许可向 Koch-Glitsch 竞争对手分发软件输出。 官方版本约束：PRO/II 工具只适配官网当前 KG-TOWER 版本。 """importos REQUIRED_MANIFEST=["tool_state","intent","sources","units","license"]BANNED_TOKENS=["disassembl","reverse engineer","反编译","逆向","内存 hook","破解"]defcheck_manifest(m):errs=[]forkinREQUIRED_MANIFEST:ifknotinm:errs.append(f"运行清单缺少字段:{k}")ts=m.get("tool_state",{})kg,tool=ts.get("kgtower",""),ts.get("proii_tool","")ifkgandtoolandkg.split(".")[:2]!=tool.split(".")[:2]:errs.append(f"版本未成对: KG-TOWER={kg}vs PRO/II 工具={tool}")ifnotm.get("license",""):errs.append("license（输出用途）未登记：无法判断是否触碰'不向竞品分发输出'红线")ifm.get("intent")notin("rating","design","revamp"):errs.append(f"intent 非法:{m.get('intent')}")returnerrsdefcheck_reproducibility(m):"""可复现：必须有 sources（关联式来源）与 units（单位集）"""out=[]ifnotm.get("sources"):out.append("缺少 sources：关联式来源未记录（违反铁律 8）")ifnotm.get("units"):out.append("缺少 units：单位集未记录（违反铁律 5/8）")returnoutdefscan_code_for_banned(path,needle_marker="BANNED_TOKENS"):"""扫描源码/文档的受限操作关键词；跳过定义关键词表的那一行以防自指误报"""hits=[]ifnotos.path.exists(path):returnhitsfori,lineinenumerate(open(path,encoding="utf-8",errors="ignore"),1):low=line.lower()ifneedle_marker.lower()inlow:continuefortokinBANNED_TOKENS:iftok.lower()inlow:hits.append((i,tok,line.strip()[:60]))returnhitsif__name__=="__main__":good=dict(tool_state=dict(kgtower="5.4.6",proii_tool="5.4"),intent="rating",sources=["E1","E2","E4"],units={"dP":"Pa/m","Fp":"m^-1"},license="内部使用；未向 Koch-Glitsch 竞争对手分发输出")print("合规良好清单 ->",check_manifest(good),"可复现问题:",check_reproducibility(good)or"无")bad=dict(tool_state=dict(kgtower="5.4.6",proii_tool="5.3"),intent="calc",sources=[],units={},license="")print("问题清单 ->",check_manifest(bad)+check_reproducibility(bad))bad_text="计划："+"反"+"编译"+" KG-TOWER 以提取内部常数\n"# 拆写，避免自指误报open("_bad_snippet.txt","w",encoding="utf-8").write(bad_text)open("_clean_snippet.txt","w",encoding="utf-8").write("计划：用 Perry Ch.14 公开关联式复现并与软件输出对标\n")print("自检（本脚本自身）命中:",scan_code_for_banned(__file__)or"无")print("扫描 _clean_snippet.txt 命中:",scan_code_for_banned("_clean_snippet.txt")or"无")print("扫描 _bad_snippet.txt 命中:",scan_code_for_banned("_bad_snippet.txt")or"无")实测输出（本机 Python 3）：
合规良好清单 -> [] 可复现问题: 无 问题清单 -> ['版本未成对: KG-TOWER=5.4.6 vs PRO/II 工具=5.3', "license（输出用途）未登记：无法判断是否触碰'不向竞品分发输出'红线", 'intent 非法: calc', '缺少 sources：关联式来源未记录（违反铁律 8）', '缺少 units：单位集未记录（违反铁律 5/8）'] 自检（本脚本自身）命中: 无 扫描 _clean_snippet.txt 命中: 无 扫描 _bad_snippet.txt 命中: [(1, '反编译', '计划：反编译 KG-TOWER 以提取内部常数')]逐段剖析：
check_manifest()一次列全所有问题（示例 5 条）而不是遇错即停：这是批量工程的核心设计——把"发现-修复"循环从 5 轮压到 1 轮。- 版本比较
kg.split(".")[:2] != tool.split(".")[:2]：比较主次版本。反直觉点 1：如果直接比全串，5.4.6vs5.4会误报——而这两者恰恰是官方页面的真实写法（注册页 5.4.6、工具页 5.4）。过严的校验会被绕过。 license字段的检查逻辑是非空判定：因为许可红线是"未经书面许可不得向竞争对手分发输出"，所以流程必须能回答"这批输出打算给谁"——空值意味着无法判断，因此必须报错。scan_code_for_banned()用needle_marker跳过定义行：反直觉点 2：如果不跳过，扫描器会命中自己的关键词表定义行，产生"永远报警"的假阳性——一个永远报警的检查器等于没有检查器。- 示例里
_bad_snippet.txt的内容用字符串拼接写（"反" + "编译"），就是为了让本脚本自身不含该关键词——这既是技术手段，也是"合规自检要能自证清白"的示范。 _clean_snippet.txt写的是"用 Perry Ch.14 公开关联式复现并与软件输出对标"——这正是本系列主张的合法路径：复现公开关联式、与软件输出对标。
代码 2-2：把检查器接进批处理（前置门禁）
# -*- coding: utf-8 -*-"""gate.py —— 把合规检查作为批处理前置门禁（不通过则不启动）"""importjson,sysfromcomplianceimportcheck_manifest,check_reproducibility,scan_code_for_banneddefgate(manifest_path,code_paths,out_dir="."):m=json.load(open(manifest_path,encoding="utf-8"))errs=check_manifest(m)+check_reproducibility(m)forpincode_paths:forln,tok,txtinscan_code_for_banned(p):errs.append(f"受限关键词命中{p}:{ln}[{tok}]{txt}")iferrs:print("门禁未通过，禁止启动批处理：")foreinerrs:print(" -",e)return1print("门禁通过：版本成对、输出用途已登记、可复现字段齐全、无受限关键词")return0if__name__=="__main__":# 若未传入清单路径，则生成一份"良好清单"作为演示iflen(sys.argv)>1:man=sys.argv[1]else:man="_manifest_ok.json"open(man,"w",encoding="utf-8").write(json.dumps(dict(tool_state=dict(kgtower="5.4.6",proii_tool="5.4"),intent="rating",sources=["E1","E2","E4"],units={"dP":"Pa/m"},license="内部使用，未向竞品分发输出"),ensure_ascii=False))rc=gate(man,["compliance.py"])print("返回码:",rc)sys.exit(rc)实测输出：
# python gate.py 门禁通过：版本成对、输出用途已登记、可复现字段齐全、无受限关键词 返回码: 0 # 把清单里的 proii_tool 改成 5.3 后再跑： # python gate.py _manifest_bad.json 门禁未通过，禁止启动批处理： - 版本未成对: KG-TOWER=5.4.6 vs PRO/II 工具=5.3 返回码: 1 # 进程退出码 = 1逐段剖析：gate()把三类检查合成一个返回码（0 通过 / 1 阻断），这正是能被计划任务与 CI 直接消费的形态（第 02 篇环境门禁的同款设计）。print时逐条列出问题，让人一次修完。注意它接收code_paths：把"源码扫描"也纳入门禁，意味着任何含受限关键词的新代码都无法进入批处理流程——这是把许可红线从"文档"变成"流程"的最后一步。
反直觉点：脚本在无参数运行时会自己写出一份清单再检查自己写的清单——这在演示时方便，但在真实工程里是反面教材：门禁必须检查"外部传入的清单"（sys.argv[1]），否则它会永远通过。上面第二段实测正是靠传入_manifest_bad.json才暴露出版本未成对。
三、常见报错与排查
报错 3-1：门禁报"版本未成对: KG-TOWER=5.4.6 vs PRO/II 工具=5.3"。
现象：批处理无法启动。根因：工具与 KG-TOWER 未成对，官方明确工具只适配当前 KG-TOWER 版本。这通常是正确行为——它在阻止你用不匹配的组合得出不可信结果。解法：把两者都升到官网当前版；若公司锁版本，则整链一起锁并记录。
报错 3-2：扫描器报自己"命中受限关键词"。
现象：compliance.py自身被命中。根因：自指误报（关键词表定义行）。解法：用needle_marker跳过定义行；或把关键词表放外部配置（这更彻底，因为配置里的词仍会自指）。
报错 3-3：文档里"请勿反编译"这句被误判为违规。
现象：语境误报。根因：扫描只做词面匹配。解法：命中进人工确认队列（不直接阻断），或对"不要/禁止/勿"等否定语境降级为提示；不要为了消误报而删掉合规文档。
报错 3-4：门禁通过但结果表仍被发给了竞品。
现象：合规事故。根因：门禁只管"流程入口"，管不到"交付出口"。解法：在交付前再加一道license审批闸门（人工确认接收方身份），并把输出用途字段写入报表落款。
报错 3-5：把 FRI 内部关联式写进sources后，可复现检查通过但事实违规。
现象：检查器"通过"了不合规内容。根因：sources只校验"非空"，不校验内容合法性。解法：sources只允许登记公开文献编号（E1…E13）；对 FRI/DRP 相关内容在门禁里增加"来源必须属于白名单"的校验（第 09 篇的FRI_ASSETS边界表可作为白名单来源）。
四、动手练习
- 练习 1（跑通）：运行代码 2-1。判定：输出"合规良好清单 -> []"、“可复现问题: 无”，以及恰好 5 条问题（版本未成对/license 未登记/intent 非法/缺 sources/缺 units），并给出三行扫描结果（自身无命中、干净文件无命中、坏片段 1 条命中）。
- 练习 2（门禁）：运行代码 2-2。判定：
python gate.py输出"门禁通过"且返回码 0；随后把清单里proii_tool改为5.3存成另一文件并传入（python gate.py <该文件>），判定输出"门禁未通过"、恰好一条问题（版本未成对）、返回码 1。 - 练习 3（一次列全）：构造一个同时缺
license、units且intent非法的清单，运行检查器。判定：三条问题一次全部报出（不因第一条错误而中断），并说明为什么批量工程偏好"一次列全"。 - 练习 4（白名单强化）：给
check_reproducibility增加"sources必须全部属于公开编号白名单（E1…E13）“的校验。判定：当sources=["FRI-DRP"]时被拒绝，错误信息指向"FRI 资产属会员权益、不得作为公开来源”（第 09 篇边界表）。
五、小结与下一篇预告
本篇把纪律变成了流程：许可红线落成断言（受限关键词网关 +license输出用途必填）、版本成对校验（比较主次版本，避免 5.4.6↔5.4 的假告警）、可复现检查（sources/units必填，且来源须在公开白名单内）、违规一次列全（示例 5 条一轮修完）、以及前置门禁 + 返回码（可被 CI/计划任务消费）。三条要点：写进文档不算治理，落成断言才算；校验要严而不误报；入口门禁与出口闸门要分开。
第 17 篇《实战一：吸收塔端到端水力学核算闭环》：把 01~16 串起来——从工况定义（用第 14 篇的契约）、到核算（第 05/07 篇）、到判据与裕度（第 12 篇）、到不确定度（第 15 篇）、到落盘与合规（第 16 篇），完整走一遍可交付的闭环。
本篇认知问题回显（FAQ）
Q1：KG-TOWER 许可红线在批处理工程里怎么落地？为什么"写进文档"不够？
A：落成可执行断言：禁止修改/改动/翻译/反汇编/创建派生材料 → 用源码与文档的受限关键词扫描作网关；禁止未经书面许可向 Koch-Glitsch 竞争对手分发输出 → 运行清单license（输出用途）必填 + 交付前人工审批闸门；PRO/II 工具只适配当前 KG-TOWER → 版本成对校验。"写进文档"不够，因为违反行为发生在代码与流程里，而没人会在写代码前重读协议。
Q2：为什么 PRO/II 工具与 KG-TOWER 必须成对升级？工程上怎么强制？
A：官方明确该工具"只适配官网当前下载的 KG-TOWER 版本"，两者是一个版本对。工程强制方式是在批处理启动前读取run_manifest.tool_state，比较kgtower与proii_tool的主次版本（如 5.4）；不一致则硬失败并提示成对升级。比较主次版本而非全串，是因为注册页写 5.4.6、工具页写 5.4，全串比较会产生假告警。
Q3："可复现检查"具体检查什么？为什么只查 sources 与 units 就够用？
A：强制两项：sources（关联式来源编号，缺则无法回溯是哪套公式，违反铁律 8）与units（单位集，缺则无法判断口径，违反铁律 5）。其余字段也检查但语义不同——tool_state用于版本成对、license用于许可闸门、intent用于字段可写性。把"必填"与"取值合法"分开，错误信息才能指到具体问题。
Q4：违规应该逐条报错退出还是一次列全？
A：批量工程应一次列全。逐条退出实现简单但"修一个跑一次"，来回多轮；一次列全把发现-修复循环从多轮压到一轮。示例的问题清单一次列出 5 条（版本未成对、license 未登记、intent 非法、缺 sources、缺 units），一条不多一条不少。
Q5：为什么要对源文件做受限关键词扫描？它会误报吗？
A：因为它是最低成本的合规网关，把"不许逆向/派生"从文档变成流程，任何含受限关键词的新代码都无法进入批处理。会误报两类：自指误报（关键词表定义行本身含关键词）与语境误报（文档在告诫读者不要做时也会出现这些词）。应对：扫描器支持跳过定义行；命中进人工确认而非直接阻断；不要把关键词表硬编码进被扫描的文件里。
