从一个需求到参数化布置次梁插件 | PKPM Agent开发手记一

做框架结构施工图，次梁布置是躲不开的工作：一块板一块板量尺寸、定方向、算间距，再一根根画，板的形式稍微一变，前面做的全得重来。画多了人会麻，改急了心会烦。不止一次想：这部分能不能让程序干？结构工程师只负责判断，计算和绘图交给工具。这个想法变成了参数化布置次梁插件，下面分享用 PKPM Agent 做插件开发的经验。

视频1：参数化布置次梁插件操作演示

次梁布置看着简单，实际很碎。范围有单块板、指定区域、整层楼；形式有单次梁、十字梁、井字梁、无梁大板；策略有统一设置、按跨度分组。每一种组合，都要重新量、重新算、重新画。以往这类需求要么人工硬扛，要么走传统二次开发，前者累人，后者周期长、门槛高，普通结构设计师很难参与。PKPM Agent 出现后，事情有了另一种可能：用对话把需求讲清楚，让 Agent 理解意图，再把规则固化成插件。目的是把结构设计师从重复劳动里拉出来。工具去画图，人做判断。

“会画图”和“会造工具”是两回事。先画了一条研发路径：对话澄清需求 → 翻译成数据模型 → 算法先行 → 预览确认 → 接入 PKPM 写入 → 真实模型验证 → 插件固化 → 持续迭代。听起来像流程，其实是踩坑之后总结出来的。这条路径里，定了三条规矩。

第一条，先算法，后接口。PKPM 接口只能活在特定运行环境里，算法却应该能独立测试。把纯几何计算拆出来，输入板宽高与布置参数，输出每根梁的坐标。后来每一轮迭代，八组断言自测几秒钟跑完，改错了立刻知道。

第二条，先预览，后写入。预览给出文本汇总表和布置示意图，人工确认无误，再写入模型。写入前，每一根梁的位置都看得见。

第三条，先规则，后智能。统一模式是所有板共用一套参数；按跨度自动匹配模式则内置三组区间：小跨（<3m）不设梁，中跨（3~6m）单次梁三等分，大跨（≥6m）井字梁推荐间距 2.5m。主控跨度取板包围盒长边，与工程师判断跨度的习惯一致。不同板自动得到不同方案，背后其实是“小跨省材料、大跨双向受力”的常规经验。

插件最终由三个文件分工：算法库只做纯几何计算，预览模块只管画图，入口脚本负责与 PKPM 交互。切分之后，算法可以独立测试，接口可以单独调试，问题定位快了很多。

与 PKPM 的链路是：取板 → 提取边界 → 计算定位 → 建网格线 → 布置次梁 → 重生成楼板。两个接口常识值得记下：次梁必须落在网格线上，先建线后布梁；布梁之后必须重新生成楼板，且原板编号全部失效，二次操作必须重新取板。真实工程是最好的测试场。插件化之后，接连暴露三个问题。

一是选择集崩溃。用户点选的板直接传给提取接口，服务端报 NoneType 错误。原因是选择集返回的构件信息不完整。解法是按编号从整层板列表换回完整对象，再参与计算。

二是类型标记丢失。这个更隐蔽：用户在界面里框选的板，读出的类型标记竟是“Unknow”，插件按类型过滤后全部漏掉，反而误报“未选中楼板”。解法是不信任类型标记，拿选择集与当前层板列表按编号求交集。一个交集，顺手把布梁前的失效旧编号、梁柱节点等非板构件一并过滤，解决三个坑。

三是模块缓存。开发会话里加载过旧版算法库，改完代码再试跑仍是旧行为，报错让人摸不着头脑。教训固化成规矩：改了模块必须清缓存，最终验证以插件页点运行为准。

功能也是被用户“用”出来的。井字梁要能“X 向 2 道、Y 向 4 道”逐向指定；十字梁也要能多道；单次梁等分不该只有二、三等分，要任意 n 等分；自定义间距要能逐段输入“1500,1000,2000”这种不等间距。每一条都很快变成新的参数与算法分支，且都遵守同一条铁律：段间距之和必须约等于板宽，偏差超限的板明确提示并跳过，绝不静默错布。

表单交互上也撞到过框架边界：插件表单不支持“选 A 灰化 B”的联动。替代方案是分组聚合加运行时把控——凡是当前方案下填了不生效的参数，运行输出逐项列出并附修正建议，相当于给每一项输入配了一道校验闸门。

回头看，最耗时间的不是写算法，而是把工程师的口头表达翻译成边界清晰的数据结构。什么是“分别设置”，什么是“推荐跨度”，都要一层层问清楚。每一次报错，都让工具更稳；每一次新需求，都让工具更像工程师的手。

图1：参数化布置次梁插件页面

这个插件只有几百行代码，却完整走过了“对话澄清需求 → 算法先行 → 真实模型验证 → 插件固化 → 持续迭代”的路。

它带来的不只是效率。以前，经验在个人手里；现在，经验可以写进插件，被更多人调用。以前，结构工程师的竞争力是熟练操作软件；以后，可能还要看能不能把经验编码成工具。

AI 时代，工具会越来越聪明，但判断仍然来自工程师。次梁布置如此，那些重复的设计动作亦当如此。不必等一个完美的开始，从一句需求出发，让 PKPM-Agent 帮你把经验装进工具。至少对我们来说，这是一条能走通的路。

欢迎扫码下载PKPM Agent智能体

中英文版