把「老师傅改 BOM」做成 Skill：玄砚客制DIYBOM自动生成开发全历程#

行业：制造业 AI 应用　岗位：AI 应用开发（FDE） 工具：WorkBuddy · 用户级 Skill · Python 标准库（零第三方依赖） 周期：2026-09-24 立项 → 09-25 大版本重构 → 10-20 改名上架，三步走完 话题：#WorkBuddy #Skill开发 #制造业BOM

先说结论#

甲方业务是按单定制：每来一个客制需求，工程师要拿着客户的清单，在几百行的标准 BOM 里逐条找到要换的物料，手工改编码、改名称、改单价。重复、慢、易错，且改完没人复核波及范围。

这个 Skill 把整件事变成一句话：「这批客户的定制件清单在这，出一份定制BOM。」

开发走了三步，每一步都有一个值得记的点：

1. 1.0.0（09-24）：一天做完首版并装进 WorkBuddy。真实 demo BOM（195 行物料清单、7 张子表）端到端跑通，实测撞出 2 个只有动手才会知道的坑（表格单元格取值、写值必须带类型），手写体形近编码 PD-0l-0009 被自动拦下。
2. 1.1.0（09-25）：甲方一句澄清——层级关系写在物料编码本身——推翻了 1.0.0「一层平铺」的核心假设。连夜重构出编码层级树 + 组件级段映射替换，并用「回归测试与 1.0.0 完全一致」证明重构没有破坏老功能。
3. 改名上架（10-20）：两轮开放平台报错，沉淀出一套 frontmatter 提交规范。

两个版本的 11 维制作质量评分都是 96 分、平均 8.7；两版自检结论也相同：唯一未闭环项都是触发测试——这是诚实的报告，比全绿更有用。

一、业务起点：改一张 BOM 到底难在哪#

客户发来一份客制需求（PDF、扫描件甚至手机拍照），上面列着要换的物料；工程师对照标准 BOM 逐条定位、替换。难点不在「改」，在判定：

• 需求上的编码是手写体，0 和 l、O 长得一样，看错了就改错行；
• 换的是零件还是部件？换部件要不要连带子件？没人说得清，全凭经验；
• 改完之后，哪些需求没匹配上、哪些拿不准，靠脑子记。

所以这个 Skill 的核心设计不是「AI 改表」，而是三条铁律：

只认物料编码、逐字符精确命中才替换、拿不准的一律进待确认清单等人拍板。

AI 负责读需求、解析 PDF、跑匹配脚本、组织交付话术；真正的替换判定在一个纯标准库的 Python 脚本里，规则可复核、结果可复现。

二、1.0.0：一天做完并装进 WorkBuddy（09-24）#

包结构#

bls-bom-diy/
├── SKILL.md                     # 7 步工作流 + 6 条硬边界
├── skill-dependencies.json      # 2 个依赖，各带降级方案
├── scripts/
│   ├── check_environment.py     # 环境四态检查（ready/partial/needs_setup/unavailable）
│   ├── extract_pdf.py           # PDF 文本层提取 + 扫描件导图
│   └── plan_replacement.py      # 编码匹配、形近比对、清单生成
├── references/                  # 4 份规范：规则库 / BOM 结构 / PDF 提取 / 配置指南
└── assets/rule-library-template.csv

设计取向很明确：脚本只用 Python 标准库，零第三方依赖、零网络——客户环境再干净也能跑，BOM 内容全程不出本机。

实测撞出来的两个坑#

这两个坑文档里不会写，只有对着真实工作簿跑一遍才会暴露：

真实 BOM 端到端（锂电无刷冲击钻 demo）#

• 7 张子表识别、表头自动定位第 4 行、物料清单 195 行；
• 8 处改动一次写入，另存新文件，与原表逐格比对：仅 8 个目标单元格 + 2 个金额公式重算，其余全部一致，原文件 SHA-256 未变；
• 最有说服力的一幕：手写体 PD-0l-0009（字母 l）与 BOM 编码不精确相等，被形近比对自动拦下，进了待确认清单而不是被改掉。

自检揪出的文档错误#

五阶段自检里，第二阶段抓到一处文档与实测相反：rule-library.md 原来写「金额列不会被自动重算」，实测金额是公式、会随单价重算。已修正为「脚本不写金额列；金额若为公式会随之自动重算」——交付话术如果说错这个，客户会把正常的公式重算当成异常改动。

三、1.1.0：一次假设被甲方推翻的重构（09-25）#

推翻的是什么#

1.0.0 按「一层平铺」处理 BOM。升级的导火索是甲方编码规则原文：

编码规则：PD-□□-□□□□（PD=冲击钻；前两位=组件号；后四位=顺序号）

真实 demo BOM 实测 187 个编码节点（14 个 PD-XX-0000 组件 + 173 个零件），与甲方描述的三层模型一致。结论：层级关系写在编码本身，不由行位置或层级列承载。平铺假设意味着部件级替换根本无法正确执行——这是必须重构的主问题。

重构核心：三件事#

1. 编码层级树：按编码分段推导父件（6 级候选推导），层级列降级为「只做相对偏移交叉校验」的只读列，推导与表内不符的行进校验提示；
2. 组件级段映射替换：规则显式写「含子件」才允许连带；整棵子树全有或全无——有一个子件编码段对不上，这次替换整体不执行；
3. 改动去重与冲突拦截：同一单元格被零件级规则和段映射同时命中且目标值相同，只保留一条（19 → 17）；目标值不同则该格整体不写、进待确认。

验证：新能力 + 不回归#

• 三层用例：主机 → 一级部件 → 二级镶套部件 → 零件，9 条需求产出 17 处改动 / 7 行 / 5 处段映射 / 6 条待确认，异常恰好 1 处（第 18 行层级列填错）；
• 异常用例 6 类：形近编码、疑似编码、缺规则、规则冲突、名称多义、未识别——changes: 0，没有一条异常被自动替换；
• 回归用例：对 1.0.0 用过的真实 demo BOM 重跑，改动条数、涉及行数、待确认条数与 1.0.0 基线完全一致，同时新增的层级树在 187 个真实编码上推导与层级列零冲突；
• 边界输入 7 组：空需求、缺规则库、非法编码规则库（UTF-16）、非法作用范围、文件不存在……全部可控，该退出的退出（退出码 2），该兜底的兜底（零自动替换）。

两版共有的短板：触发测试#

11 维评分里唯一低于 8 的是「触发描述质量」（7 分）——description 里写好了 5 句真实话术，但制作会话内无法复现宿主的触发匹配。两版的综合结论都如实写为「需修改：触发测试未执行」，修复清单里 F01 挂着 P2 待装上后补。这个「唯一的黄灯」保留到最后一刻才补测，是流程上的诚实，不是缺陷。

四、改名与上架：从 Skill 到开放平台（10-20）#

版本稳定后做产品化收尾，三处同步改名 + 生成提交包：

开放平台解析出了两轮报错，全部源于 frontmatter 字段名：

最终沉淀的 frontmatter 五件套：

name: xy-bom-diy                              # kebab-case 机器标识
display_name: 玄砚客制DIYBOM自动生成            # 中文展示名（无 _zh 后缀）
display_name_en: XuanYan Custom DIY BOM Generator
description_zh: "功能 + 场景 + 用户会说的原话（触发匹配靠它）"
description_en: "English summary"

第二轮报错只剩一条，恰恰证明报错文案括号里的字段名是唯一权威——照抄原文，不做任何「对称化」加工。

五、开发过程沉淀的五条方法论#

1. 先写死安全边界，再写功能。 「编码不精确命中不落表」「组件级替换必须显式授权」「规则库缺失零自动替换」这三条从 1.0.0 就锁死在硬边界、停止条件、脚本实现三处。后来所有新功能（段映射、去重）都是在这套边界里长出来的，重构才敢放开手脚。

2. 甲方规则原文高于自己的合理推断。 1.1.0 整个重构源于甲方一句编码规则原文——1.0.0 的平铺假设是我自己推的，看起来合理，实际错了一个维度。涉及客户数据结构的设计，拿到原文再动手。

3. 文档也要过测试。 「金额列会不会重算」这类描述性内容，和代码一样会错。实测发现的文档错误（F02）如果流到交付话术，客户会把正常现象当成事故。

4. 重构必须带回归基线。 1.1.0 动了匹配核心，但对 1.0.0 的真实用例做到逐项一致（8 处改动 / 1 条待确认），新能力用新用例单独证明。没有基线的重构，等于把老功能押给了运气。

5. 自检报告要敢留黄灯。 两版唯一未闭环项都是触发测试，报告里如实标注「需修改」而不是凑一个全绿。评分是给自己看的，黄灯是给下次升级排期用的。

附：版本时间线与产物#

各位可以在workbuddy里搜“玄砚客制DIYBOM”来操作你的BOM吧

2026-10-25 成文。