对象类型：一类业务对象

对象类型、对象、对象集

上一门课把示例工厂的 13 个对象类型画在了同一张图上。这一节先挑「工单」，把它写成一份能提交的定义。

对象类型（Object Type）是对一类真实事物或事件的定义，比如工单。一张具体的工单是一个对象，「所有正在运行的工单」是一个对象集。它们和你熟悉的数据表一一对应：

对象大多来自数据源里的行，也可以完全由 Action 的 createObject 规则新建。数据源接入只读。普通 Action 规则只改语义层。配置 writeback webhook 的 Action 还能修改外部系统。

两把钥匙：主键和标题键

每个对象类型都要指定两个属性。主键让每个对象唯一，标题键是给人看的名字。WorkOrder 用 workOrderNo 做主键；Customer 的主键是 customerId，标题键是 name，因为人认的是公司名，不是编号。

• 每个对象类型都必须有主键；新建的类型只写一个主键属性。存量复合主键原样保留时给警告。新建类型或修改主键时，平台拒收复合主键。
• 主键值不能重复，也不能变。编辑和关系都挂在主键值上，主键一变，人改过的值和已有的关系就对不上了。
• 改主键属于破坏性改动，要走分支和提案，不能悄悄改。
• 标题键只管显示，不要求唯一；不写就用主键。

有了主键，取回一个对象只要「类型 + 主键」。读回的每个对象都带着 __primaryKey、__apiName 和 __title，最后一个就是标题键的值。

const client = semantic.ontology();
const order = await client.objects("WorkOrder").fetchOne("WO-20260901-017");
// order.__primaryKey, order.__apiName === "WorkOrder", order.__title

名字与元数据

对象类型有两套名字：写给代码的，和写给人的。

同义词值得认真写。业务里有人说「生产单」，有人说「作业单」，把它们都写成 WorkOrder 的同义词，智能体按哪种说法问都能找到。每个类型最多写 12 个，每个不超过 40 个字符。

下面是 WorkOrder 的一份最小定义（省略了 sku、orderNo 两个外键）。columns 里每一项是一个属性，titleColumn 指定标题键，references 是外键，下一门课会把它变成关系。外键指向的类型（这里是 ProductionLine）要么已经存在，要么在同一批里一起提交。

{
  "kind": "objectType",
  "apiName": "WorkOrder",
  "title": "Work order",
  "description": "One production run of one product on one line.",
  "schema": {
    "pluralDisplayName": "Work orders",
    "visibility": "PROMINENT",
    "synonyms": ["job", "production order"],
    "groups": ["production"],
    "titleColumn": "workOrderNo",
    "columns": [
      { "name": "workOrderNo", "type": "string", "primaryKey": true, "title": "Work order no." },
      { "name": "status", "type": "string", "title": "Status" },
      { "name": "plannedQty", "type": "integer", "title": "Planned quantity", "unit": "pcs" },
      { "name": "goodQty", "type": "integer", "title": "Good quantity", "unit": "pcs" },
      { "name": "scrapQty", "type": "integer", "title": "Scrap quantity", "unit": "pcs" },
      { "name": "startAt", "type": "timestamp", "title": "Start" },
      { "name": "dueAt", "type": "timestamp", "title": "Due" },
      { "name": "lineCode", "type": "string", "title": "Line", "references": { "entity": "ProductionLine", "column": "lineCode" } }
    ]
  }
}

提交前先只检查：--dry-run 会告诉你引用是否闭合、相对上一个语义版本有哪些破坏性改动。智能体不直接改 main，要先开分支。

# check only: do the references close? any breaking changes?
aidc semantic define ontology/ --dry-run

# an agent works on a branch instead of main
aidc semantic branch create add-work-order
aidc semantic branch modify add-work-order ontology/ --dry-run

# read the definition back
aidc semantic object-types WorkOrder

下一节讲属性：每个属性该选什么类型，哪些类型能做主键和标题键。