① 一分钟看懂:这事错在哪、对在哪
✗ 反面:一表一对象(最常见的错)
- 13 张表 → 出 13 个对象,客户一看 60 个对象,直接不用了
- 字典表「客户等级表」被建成对象,AI 答不出「这个客户什么级别」
- 日志表、统计表、中间表全变成对象,噪音挤满语义层
- 外键列既当属性又当关系,同一事实两处表达,改一处漏一处
create_time、is_deleted、tenant_id进了属性,AI 的注意力被技术列带走
✓ 正面:先归类,再定对象
- 逐张表判类型(主表 / 明细 / 中间 / 字典 / 日志 / 统计…),按类型决定处置
- 该合的合(客户 + 客户扩展表 → 一个对象),该拆的拆,该丢的丢
- 字典 → 枚举属性;外键列 → 关系 + 挂钩列;技术列 → 全部排除
- 13 张表压到 8 个对象,客户一看就懂
- 每个对象都能答出三问:谁问它 / 谁写它 / 参与什么判断
判断口诀
② 包文件结构:每个文件是干什么的
解压你收到的那个 zip 之后,得到的是下面这一个文件夹。整体只有 13 个文件,其中真正要动手的只有 3 个(下表标 ⭐ 的)。
DB2Ontology-Kangkai\
├─ ⭐ table-to-ontology.zip ← 导入 WorkBuddy 就选它(20 秒装好)
├─ ⭐ templates\ontology-4tables-blank.xlsx ← 填四表用这个空白模板
├─ ⭐ tools\check_ontology.py ← 四表自检脚本(跑出 PASS/FAIL)
│
├─ 表结构转本体_使用说明与示例_v1.0.html ← 本页(离线可开,也是给客户的说明页)
├─ README.md ← 同一份说明的 Markdown 版
├─ install-to-workbuddy.bat ← 备用:双击即装,不用界面导入时用
│
├─ skills\table-to-ontology\ ← 技能源文件(导入包就是从这里打的)
│ ├─ SKILL.md ← 技能主文件:三条铁律 + 五步流程 + 常见错误
│ └─ references\
│ ├─ 01-input-and-mapping.md ← 12 种表类型→本体映射表、列排除清单、合并/拆分判据
│ ├─ 02-checklist.md ← 交付前自检清单(机械 A 类 + 判据 B 类)
│ └─ 03-example.md ← 13 表→8 对象的完整走查
│
├─ templates\input-schema-template.csv ← 表结构输入模板(让客户/开发按这个填)
├─ example\example-4tables.xlsx ← 填好的示例四表(对着看格式)
└─ tools\build_templates.py ← 重新生成模板/示例(改了数据重跑用)
| 文件 / 文件夹 | 是什么 | 什么时候用 |
|---|---|---|
| table-to-ontology.zip ⭐ | 打好的技能包:根层就是 SKILL.md + references/,符合 WorkBuddy 导入窗口「需包含 SKILL.md」的要求 | 装技能时选它。⛔ 不要选外层总包 |
| templates\ontology-4tables-blank.xlsx ⭐ | 四表空白模板:对象 / 属性 / 关系 / 动作,带下拉校验、枚举白名单、填表说明页 | 每做一次建模就复制一份来填 |
| tools\check_ontology.py ⭐ | 四表机械自检脚本:查列是否齐、枚举是否合法、有没有悬空引用、关系有没有挂钩列 | 四表填完必跑:python tools\check_ontology.py 你的四表.xlsx |
| 表结构转本体_使用说明与示例_v1.0.html | 本页。单文件自包含,断网能开,也能直接发给客户看(不含客户数据) | 给人看流程与示例时 |
| README.md | 同一份说明的 Markdown 版 | 想在编辑器/仓库里看,或要改说明文字 |
| install-to-workbuddy.bat | 一键安装脚本:把技能拷到 %USERPROFILE%\.workbuddy\skills\ | WorkBuddy 里找不到导入入口时的备用路径 |
| skills\table-to-ontology\ | 技能源文件目录(导入包就是从这儿打的);SKILL.md 是主文件,references\ 是三条细则 | 导入失败要排查、或要改技能内容时 |
| references\01-input-and-mapping.md | 核心规则:12 种表类型怎么判怎么处置、哪些列必须排除、什么时候该合并/拆分、关系怎么命名和挂列 | 遇到「这张表该建成什么」拿不准时查 |
| references\02-checklist.md | 自检清单:A 类机械项 12 条 + B 类判据项 15 条 + 对外红线 3 条 | 交付前人工过一遍(脚本查不出的部分) |
| references\03-example.md | 完整示例:13 张表 → 8 个对象、12 条关系、6 个动作,含处理账与待确认清单 | 第一次做时对照着看;也可直接给客户看效果 |
| templates\input-schema-template.csv | 表结构输入模板(兜底用):表名/字段/类型/主键/外键/取值说明/样本值 | 只在拿不到 DDL 时用;能拿到建表语句就直接给 DDL |
| example\example-4tables.xlsx | 填好的示例四表(带数据,可直接看格式对不对) | 不确定某一格该怎么填时打开对照 |
| tools\build_templates.py | 模板/示例的生成脚本(模板和示例都是它产出的) | 要改类目或加字段时改脚本重跑,别手改 xlsx 当唯一真源 |
table-to-ontology.zip;填表用 templates\ontology-4tables-blank.xlsx;出表后跑 tools\check_ontology.py。
其余 6 个是说明与参考(SKILL.md + 3 个 references 已经装在技能里了,平时不用单独打开)。
③ 装进 WorkBuddy,然后三步跑通
先把技能装进 WorkBuddy(用自带的「导入技能」,30 秒)
技能页 → 导入技能 → 弹窗里点「选择 ZIP 文件」→ 选包根目录的:
DB2Ontology-Kangkai\table-to-ontology.zip
这个 zip 是专门做好的技能包:根层直接就是 SKILL.md + references/,正好满足弹窗要求的「文件夹或 zip 需要包含 SKILL.md」。
⛔ 不要选外层那个 DB2Ontology-Kangkai.zip(它根是 README,容易被判成缺少 SKILL.md)。
弹窗里那个「非高风险自动安装」勾上,能省一次确认。
它不认 zip 就拖文件夹:把解压出来的 skills\table-to-ontology 文件夹直接拖进弹窗的虚线框,效果一样。
备用:不经界面,直接放目录
| 位置 | 路径 | 效果 |
|---|---|---|
| 用户级(推荐) | %USERPROFILE%\.workbuddy\skills\table-to-ontology\ | 装一次,所有项目都能用 |
| 项目级 | <项目文件夹>\.workbuddy\skills\table-to-ontology\ | 只在这个项目里可用 |
最终结构:…\skills\table-to-ontology\SKILL.md + 同目录 references\ 三个 md(要一起在)。
也可先完整解压,再双击 install-to-workbuddy.bat,自动装到用户级目录(已实测可用)。
怎么知道装上了:技能列表出现 table-to-ontology,描述以「Use when 拿到客户业务系统的表结构…」开头;再说一句「表结构转本体」,它先输出表归类处理账(而不是一表一对象往下建)就是命中了。
⛔ 四种装不上 / 装不对:① 上传被拒「缺少 SKILL.md」=选了外层总包;② 列表里没有=选错层级(进到 references 里);③ 提示已存在=同名重复导入,覆盖或先删;④ 说找不到规则文件=references 没跟着一起进。
最后一招:把 SKILL.md 全文 + references/01-input-and-mapping.md 贴给它当上下文,再说你的表结构——缺点是每次都得贴。
收表结构(这一步决定成败,别跳)
三种形态都行,优先直接要 DDL(建表语句 / schema.sql) —— 主键、外键、中文注释都在里面,不用来回问:
| 形态 | 里面有什么 | 缺什么 |
|---|---|---|
| DDL / schema.sql ⭐ | 表名、字段、类型、长度、主键、外键、COMMENT 注释 | 样本值、哪些表在用 |
| 数据字典 Excel | 字段清单(表名/字段/类型/注释) | 外键关系常缺、样本值 |
| 按模板的 CSV | 行列统一、口径干净 | —(没有 DDL 时的兜底) |
让客户的 DBA / 开发导出 DDL,一般 5 分钟:
MySQL SHOW CREATE TABLE 表名; 或 mysqldump -u用户 -p --no-data 库名 > schema.sql
SQL Server SSMS → 右键数据库 → 任务 → 生成脚本 → 选「仅架构」
Oracle SELECT DBMS_METADATA.GET_DDL('TABLE','表名') FROM DUAL;
PostgreSQL pg_dump -s -t 表名 库名
⛔ DDL 也补不出来的两样,必须另外要:① 每表 3~5 行样本数据(脱敏)——唯一能验证字段真实含义和取值的东西,没有它枚举值域只能靠猜;② 哪些表还在用、哪些是历史遗留——建了没人问的对象纯属噪音。
⛔ 不要一次丢 80 张表。先挑核心单据链上的 10~15 张(客户 → 商机 → 合同 这类主链路),出第一版,人对齐后再扩。
让它出四表 —— 先要「处理账」,再要四表
把下面这段丢给 AI(或 WorkBuddy 里说「表结构转本体」):
按 table-to-ontology 技能,从下面这批表结构推企业本体,
出 对象/属性/关系/动作 四表。
第一步先只给我「表归类处理账」:
每张表 → 判成什么类型 → 处置(建对象 / 合并 / 拆 / 多值属性 / 关系 / 枚举 / 不建)→ 一句理由。
我确认处理账之后,你再填四表。
先要处理账,能提前抓出「字典表当对象建了」「日志表也建了」这类错,比四表出来再推倒省一天。
跑自检 + 人工过判据
python tools/check_ontology.py 你的四表.xlsx
python tools/check_ontology.py 你的四表.xlsx --total-fields 115 # 有源字段总数时做对账
- PASS 结构没问题 → 接着人工过
02-checklist.md的 B 类判据项(机器查不出) - FAIL ERROR 必须清零再交付;WARN 逐条复核
机器能查:列是否齐、枚举是否在白名单、有没有悬空引用、关系有没有挂钩列。 机器查不出:这个对象该不该建、这条关系方向对不对、动作是不是只是查询。
没有 DDL 时:按这个模板整理
这是兜底方案。能拿到 DDL 就不用填这个表。
| 表名 | 字段名 | 字段中文名 | 类型 | 主键 | 外键→ | 取值说明 | 样本值 |
|---|---|---|---|---|---|---|---|
crm_customer | cust_name | 客户名称 | varchar(200) | 苏州某某精密制造 | |||
crm_customer | cust_level | 客户等级 | char(2) | A=战略/B=重点/C=普通 | A | ||
crm_customer | industry_code | 所属行业 | varchar(20) | dict_industry.code | C35 |
完整版见包内 templates/input-schema-template.csv;不论用哪种形态,每张表再另存一个「样本_表名」Sheet 放 3~5 行真实数据。
④ 示例走查:13 张表 → 8 个对象
t_ / d_ / s_ / rpt_)。
共 13 张表、115 个字段。示例只用于演示方法,不含任何真实客户数据。
拿到手的 13 张表
| # | 表名 | 中文 | 量级 | 类型初判 |
|---|---|---|---|---|
| 1 | t_customer | 客户 | 3 万 | 业务主表 |
| 2 | t_customer_ext | 客户扩展 | 3 万 | 1:1 扩展表 |
| 3 | t_customer_contact | 客户联系人 | 8 万 | 子表(1:N) |
| 4 | t_opportunity | 商机 | 12 万 | 业务主表 |
| 5 | t_opp_product | 商机产品明细 | 30 万 | 明细子表 |
| 6 | t_contract | 合同 | 5 万 | 业务主表 |
| 7 | t_contract_item | 合同条款明细 | 18 万 | 明细子表 |
| 8 | t_customer_advisor | 客户-顾问指派 | 6 万 | 中间表 |
| 9 | d_industry | 行业字典 | 600 | 字典(被引用、有层级) |
| 10 | d_customer_level | 客户等级字典 | 4 | 字典(纯取值) |
| 11 | s_user | 系统用户 | 800 | 权限层 |
| 12 | t_follow_log | 跟进记录 | 90 万 | 日志(业务要看历史) |
| 13 | rpt_customer_month | 客户月度统计 | 40 万 | 统计快照 |
表归类处理账(这张表先给人看,确认后再填四表)
| 表 | 处置 | 判据(为什么) |
|---|---|---|
t_customer + t_customer_ext | 合并 → 对象「客户」 | 同一主体、同一生命周期、1:1 主键对齐;扩展表只是字段太多拆出去 |
t_customer_contact | → 对象「联系人」 | 一家客户多个联系人,各自有独立在职/离职状态,会被单独问到("这家客户谁是对接人") |
t_opportunity | → 对象「商机」 | 独立生命周期(阶段推进),被合同引用 |
t_opp_product | → 商机的多值属性「产品明细」 | 行只用于展示与求和,不被任何其他表引用;无独立状态 |
t_contract | → 对象「合同」 | 独立生命周期(签订/履行/归档),有业务编号 |
t_contract_item | → 合同的多值属性「条款明细」 | 纯从属,随合同删除 |
t_customer_advisor | → 对象「客户指派记录」 | ⚠️ 不是关系:中间行带「是否主责」「分配时间」「解除时间」,关系承载不了,必须对象化 |
d_industry | → 对象「行业」 | 被客户引用、有层级(上级行业)、有启停生命周期;AI 要按行业筛客户 |
d_customer_level | → 客户.客户等级(枚举) | 只有 4 行纯取值,没有任何表引用它的 id,业务上不会被单独问"有哪些等级" |
s_user | 不建账号对象 | 账号密码属平台权限层;但"谁负责这个客户"要能答 → 另建「业务人员」对象,来源 s_user |
t_follow_log | → 对象「跟进记录」 | 表面是日志,但业务必须能查"上次谁跟这个客户聊了什么"——是业务过程记录,不是运维日志 |
rpt_customer_month | 不建 | 统计快照,指标可由商机/合同算出;建了会和源数据打架 |
对账这一行是硬指标:三个数加不出总数,说明有字段被悄悄丢掉了。
⑤ 四表样例(节选)
完整版见包内 example/example-4tables.xlsx;这里节选对象全量 + 其他抽样。
| 对象 | 编码 | 一句话(AI 语义) | 主键 | 通用性 |
|---|---|---|---|---|
| 客户 | customer | 与我们发生采购关系的企业或组织,是所有业务的发生主体。一家公司只能有一条客户记录,同集团不同法人算不同客户。 | cust_id | 行业通用 |
| 联系人 | contact | 客户内部的具体对接人,可以多人,各自可能有不同在职状态。联系人不是客户。 | contact_id | 行业通用 |
| 商机 | opportunity | 一个有成交可能的销售机会,从初步接触到赢单/输单的完整过程。一个客户可同时有多个商机。 | opp_id | 行业通用 |
| 合同 | contract | 与客户签订的正式销售合同,是收入确认依据。金额不可改,只可作废重签。 | contract_id | 行业通用 |
| 客户指派记录 | customer_assignment | 某客户在一段时间内由谁负责的记录,含主责与协办。换人不改字段,而是结束旧记录开新记录。 | assign_id | 客户特有 |
| 行业 | industry | 客户所属的行业分类,有上下级层级。用于筛选客户、分配行业顾问、统计占比。 | industry_code | 行业通用 |
| 业务人员 | staff | 公司内负责客户与商机的销售/顾问,与登录账号一一对应。只保留业务属性,不含账号密码。 | staff_id | 行业通用 |
| 跟进记录 | follow_record | 业务人员与客户的一次沟通记录,含内容与下次计划。销售过程的真实轨迹。 | follow_id | 行业通用 |
| 所属对象 | 属性 | 类型 | 必填 | AI 语义说明 | 来源 | 密级 |
|---|---|---|---|---|---|---|
| 客户 | 客户名称 | 普通 | 是 | 客户公司全称,与营业执照一致。用于所有对外单据。 | t_customer.cust_name | 公开 |
| 客户 | 客户等级 | 枚举 | 是 | 客户分级,决定跟进频次与折扣权限:A=年框战略客户(月度拜访)、B=重点客户(双周拜访)、C=普通客户(季度拜访)。D 已停用,遇到按 C 处理。 | t_customer.cust_level | 公开 |
| 客户 | 客户来源 | 枚举 | 否 | 客户最初从哪里来:展会/官网/转介绍/电话开发/老客户复购。用于评估获客渠道效果。 | t_customer.source_type | 公开 |
| 客户 | 合作状态 | 枚举 | 是 | 潜客=还没成交、在合作=有未关闭合同、暂停=有合同但暂停供货、流失=连续12个月无新单。流失客户不再进商机推荐。 | t_customer.coop_status | 公开 |
| 客户 | 统一社会信用代码 | 普通 | 否 | 营业执照上的 18 位信用代码,工商维度唯一标识。与客户编号是两套编码,不要混用。 | t_customer.credit_code | 公开 |
| 客户 | 年采购规模 | 普通 | 否 | 客户上一年度在我方的采购总额(元),由统计回填,不手工填。 | t_customer_ext.annual_amt | 机密 |
| 商机 | 商机阶段 | 枚举 | 是 | 10=初步接触、20=需求确认、30=方案报价、40=商务谈判、90=赢单、99=输单。90/99 为终态,不再变更。 | t_opportunity.stage | 公开 |
| 商机 | 产品明细 | JSON Array | 否 | 本商机涉及的产品行:名称/型号/数量/单价/折扣。行只用于展示与报价汇总,不单独跟踪。 | t_opp_product | 机密 |
| 合同 | 合同编号 | 普通 | 是 | 业务唯一编号,格式 HT-年份-流水,纸质合同与系统必须一致。 | t_contract.contract_no | 公开 |
| 合同 | 合同状态 | 枚举 | 是 | 10=草稿、20=待审、30=生效、60=履行完毕、90=作废。只有 30 生效才计入收入。 | t_contract.status | 公开 |
| 联系人 | 姓名 | 普通 | 是 | 客户方对接人姓名。只记真名,不记"张总"这类称呼。 | t_customer_contact.name | 机密 |
| 联系人 | 手机号 | 普通 | 否 | 对接人手机号,用于拜访预约与回访。属个人信息,仅负责该客户的顾问可见。 | t_customer_contact.mobile | 绝密 |
| 跟进记录 | 跟进方式 | 枚举 | 是 | 电话=电话沟通、微信=微信沟通、拜访=上门拜访(需填地址)、邮件=邮件往来、其他=其他方式。 | t_follow_log.type | 公开 |
| 跟进记录 | 跟进内容 | 普通 | 是 | 这次沟通谈了什么(客户原话优先)。是判断客户意向的主要依据。 | t_follow_log.content | 机密 |
| 客户指派记录 | 是否主责 | 枚举 | 是 | 是=主责顾问(业绩归属、第一联系人)、否=协办。同一客户同一时间只能有一个主责。 | t_customer_advisor.is_primary | 公开 |
| 行业 | 行业名称 | 普通 | 是 | 行业分类名称,如"汽车零部件制造"。与代码一一对应,代码为准。 | d_industry.industry_name | 公开 |
| 行业 | 行业代码 | 普通 | 是 | 分类代码(GB/T 4754 口径),客户与统计报表都按此归集。层级见「上级行业」关系。 | d_industry.industry_code | 公开 |
| 业务人员 | 姓名 | 普通 | 是 | 真实姓名,用于合同签单人、商机归属人显示。 | s_user.real_name | 机密 |
| 业务人员 | 在职状态 | 枚举 | 是 | 在职=可分配新客户、离职=不可分配但历史业绩保留、停用=长期不在岗。离职人员历史商机不自动转移。 | s_user.status | 公开 |
| 源对象 | 关系 | 目标对象 | 基数 | 必需 | 挂钩列(源 → 目标) |
|---|---|---|---|---|---|
| 客户 | 归属 | 行业 | N:1 | 是 | t_customer.industry_code → d_industry.industry_code |
| 客户 | 有 | 联系人 | 1:N | 否 | t_customer_contact.customer_id → t_customer.cust_id |
| 客户 | 拥有 | 商机 | 1:N | 否 | t_opportunity.customer_id → t_customer.cust_id |
| 客户 | 签订 | 合同 | 1:N | 否 | t_contract.customer_id → t_customer.cust_id |
| 商机 | 成交为 | 合同 | 1:N | 否 | t_contract.opp_id → t_opportunity.opp_id |
| 客户指派记录 | 针对 | 客户 | N:1 | 是 | t_customer_advisor.customer_id → t_customer.cust_id |
| 客户指派记录 | 指派给 | 业务人员 | N:1 | 是 | t_customer_advisor.user_id → s_user.user_id |
| 商机 | 由…负责 | 业务人员 | N:1 | 是 | t_opportunity.owner_id → s_user.user_id |
| 合同 | 由…负责 | 业务人员 | N:1 | 是 | t_contract.owner_id → s_user.user_id |
| 跟进记录 | 关于 | 客户 | N:1 | 是 | t_follow_log.customer_id → t_customer.cust_id |
| 跟进记录 | 由…发起 | 业务人员 | N:1 | 是 | t_follow_log.user_id → s_user.user_id |
| 行业 | 上级行业 | 行业 | N:1 | 否 | d_industry.parent_code → d_industry.industry_code |
关系方向是业务语义方向(客户 →有→ 商机),不是外键物理方向;关系名用业务动词,不写「关联」「链接」。
| 所属对象 | 动作 | 角色权限 | 审批 | 执行逻辑(AI 语义) | 参数(必填/归属人) |
|---|---|---|---|---|---|
| 客户 | 新建客户 | 销售、销售助理 | 无需审批,留痕 | 「客户第一次接触并确认是真实企业」时用。必填名称+等级+行业;同名客户已存在时不要新建,改用「新增联系人」。 | 客户名称(是/否)、客户等级(是/否)、行业(是/否) |
| 客户 | 调整客户等级 | 销售主管 | 按角色审批 | 「客户年度评估或战略合作变化」时用。必须写原因,A→C 降级要主管确认。 | 客户(是/是)、新等级(是/否)、原因(是/否) |
| 客户 | 指派顾问 | 销售主管 | 按角色审批 | 「新客户分配」或「人员离职/调动需交接」时用。系统结束旧指派记录并开新记录,不改历史。主责同时只能有一个。 | 客户(是/是)、业务人员(是/是)、是否主责(是/否) |
| 跟进记录 | 录入跟进记录 | 销售、顾问 | 无需审批,留痕 | 「每次与客户沟通完」随手记。必须写清谈了什么和下次计划;只写"已联系"没有业务价值。 | 客户(是/否)、跟进方式(是/否)、跟进内容(是/否) |
| 商机 | 推进商机阶段 | 销售 | 按数据归属审批 | 「商机有实质进展」时用。只能向前推进或转输单;90 赢单会自动要求关联合同号。 | 商机(是/是)、目标阶段(是/否) |
| 合同 | 归档合同 | 销售主管 | 按数据归属审批 | 「合同履行完毕或确认作废」时用。作废不影响已发生收入但要注明原因。 | 合同(是/是)、归档类型(是/否) |
⛔ 查询列表、看详情、导出 Excel、接口调用 —— 都不是动作。动作只取会改变数据的业务操作。
⑥ 验收与红线
判断产出好不好的三个硬指标
红线
| 红线 | 做法 |
|---|---|
| AI 只出草稿 | 建模表、需求基线、验收标准这几类关键工件必须真人逐条终审——AI 98% 正确也要人读完 100% |
| 推断必须标记 | AI 推断的条目一律标 🤖推断-待确认,不进对外材料 |
| 客户数据不出客户环境 | 人名、手机号、身份证、公司名 ⛔ 不写进本体属性值;本体沉淀的是行业理解,不是客户数据 |
| 业务判断不自己定 | 哪个状态算流失、谁能改价格 —— 列进「待确认问题清单」问客户,不替客户做决定 |
常见错误清单(逐条都是踩过的)
| 错 | 正确做法 |
|---|---|
| 一表一对象,出 60 个对象 | 先归类再定对象,通常压到 8~15 个 |
| 字典表建成对象(如「客户等级表」) | 建成枚举属性,值域写进语义说明 |
| 外键列既建属性又建关系 | 只建关系 + 挂钩列;要显示名字的另留可读名称属性 |
把 create_time/is_deleted/tenant_id 当属性 | 全部排除 |
直接拿表名当对象名(crm_customer_info) | 用业务名词:客户、人才、岗位需求 |
| 基数全填 1:N 不核对 | 回到数据核对,一对一还是多对多靠样本值验 |
| 动作全是「查询/导出」 | 查询不是动作,只取改变数据的业务操作 |
| 关系名写「关联」「链接」 | 写业务动词:负责、投递、签订、归属 |
| 没样本数据就定枚举取值 | 先标待确认,拿到样本值再定值域 |