一个 Action 的解剖

为什么改数据只有一个入口

上一门课的最后一节用只读 SQL 把数据读了出来。读可以有很多种办法，改只有一个入口：Action。

Action 是一次事务：按事先写好的逻辑，同时改一个或多个对象、属性和关系。它表达的是业务意图，比如「确认订单」「下达工单」，而不是「把 status 字段改成 confirmed」。

谁来调用它都一样：/semantic 里的表单、命令行、SDK、工作流里执行 Action 的一步、智能体，执行的都是同一个 Action，走同一套校验，留下同样的记录。

所以设计 Action 从一个问题开始：这是哪一种业务动作？名字用动词加对象，写成 kebab-case，比如 confirm-order。

一个 Action 的五个部件

「只校验」在第二步之后停下，什么也不写。副作用发生在事务提交之后，它不在事务里，第 5 节和第 7 节会回到这一点。

从零写 confirm-order

示例工厂的销售订单从 draft 开始。「确认订单」只做一件事：把一张草稿订单改成 confirmed。定义是一份 JSON，kind 写 actionType：

{
  "kind": "actionType",
  "apiName": "confirm-order",
  "title": "确认订单",
  "description": "把一张草稿订单确认下来，交给生产。",
  "schema": {
    "parameters": [
      { "name": "order", "type": "object", "objectType": "salesOrder", "title": "订单", "required": true }
    ],
    "rules": [
      { "type": "modifyObject", "objectType": "salesOrder", "object": "$order", "values": { "status": "confirmed" } }
    ],
    "submissionCriteria": [
      {
        "condition": { "type": "comparison", "left": { "param": "order", "property": "status" }, "operator": "is", "right": { "literal": "draft" } },
        "failureMessage": "只有草稿订单可以确认"
      }
    ],
    "summary": "订单 {order} 已确认",
    "actionLog": true,
    "toolDescription": "Confirm a draft sales order so it can go to production."
  }
}

四段各管一件事。parameters 声明输入：只有一个必填的订单对象。rules 里一条 modifyObject 把订单的 status 写成字面量 confirmed。submissionCriteria 要求订单现在必须是 draft，否则返回你写的 failureMessage。actionLog: true 让每次成功执行多写一个 log.confirm-order 对象。summary 是日志里的一句话，toolDescription 是写给智能体看的说明。

先校验，再执行

开发者把定义存成文件后，先用 aidc semantic define ontology/ --dry-run 检查，再去掉 --dry-run 提交；智能体则在分支上改，走提案（第 10 门课讲）。定义就绪后，先只校验、再执行：

aidc semantic apply confirm-order --param order=SO-1001 --validate-only
aidc semantic apply confirm-order --param order=SO-1001 --return-edits

第一条什么也不写，只返回逐个参数、逐条提交条件的结果，不通过时退出码是 2。第二条正式执行，--return-edits 让返回里带上这次新建、修改、删除了哪些对象和关系。SDK 里对应 applyAction(params, { $validateOnly: true }) 和 { $returnEdits: true }。返回的样子（节选）：

{
  "validation": {
    "result": "VALID",
    "submissionCriteria": [{ "result": "VALID" }],
    "parameters": { "order": { "result": "VALID", "required": true } }
  },
  "edits": { "type": "edits", "addedObjectCount": 0, "modifiedObjectsCount": 1, "deletedObjectsCount": 0 }
}

命名照统一的规矩：Action 用 kebab-case，Object Type 用 PascalCase，属性和值类型用 camelCase。已有的小写类型名兼容，但会告警。本课示例沿用已有的 salesOrder；新建类型应写 SalesOrder。

下一节把参数拆开讲：release-work-order 该让调用方填什么，又不该让他填什么。