过去两年我们团队落地 AI 应用时反复遇到同一个问题业务部门维护的领域规则和 AI 系统实际使用的 Prompt、工具定义、RAG 知识文档常常各写各的。业务同学说“订单已支付”指某个状态AI 助手却把“已发货但未完成”也当成已支付开发同学改了一张表结构AI 侧的 JSON Schema 和 Function Calling 参数又忘了同步。表面上是沟通问题本质是缺少单一事实源。本文要讨论的就是标题里这句话“Model your business once – for humans and AI alike”。它不是一句抽象口号而是一套可落地的工程方法把业务模型用一种结构化、语义化、可版本化的方式建模一次让人类团队用同一份模型做开发和评审让 AI Agent 用同一份模型做上下文注入、工具调用和规则校验。本文会从一个电商订单场景出发完整演示术语表、实体 Schema、状态机、OpenAPI 契约以及 AI 消费脚本的编写方法并提供可复制的代码示例。1. 为什么业务模型要先“建模一次”再给人和 AI 共用很多团队对“业务建模”的印象还停留在传统开发阶段画 UML 图、写 PRD、设计数据库表、维护接口文档。这些资料确实承载了业务知识但问题是它们形态各异既有 Word 又有 PDF既有流程图又有表格计算机很难稳定解析。当 AI 进场之后这个矛盾被放大了。AI Agent 要执行任务通常依赖三种输入Prompt 中的业务规则描述工具定义的参数 SchemaRAG 检索到的知识片段。如果这些内容来自不同渠道且由不同人手工维护最终必然出现同一个业务对象在多个地方定义不一致。AI 的理解就会漂移甚至产生看似合理但违背业务规则的输出。所谓“Model your business once”核心理念是建立一份单一事实源Single Source of Truth。这份模型需要做到面向人类面向 AI业务人员可以阅读术语和状态流转LLM 可以读取结构化上下文开发人员可以基于 Schema 开发接口Agent 可以根据工具定义调用服务测试人员可以按规则编写用例校验程序可以验证输入输出合法性这背后的工程价值很直接模型只维护一份任何消费方都从同一份模型派生、校验或同步。业务变了只改模型文件然后重新生成 AI 上下文和 API Schema人为复制粘贴造成的不一致会大幅减少。这里需要区分一个容易混淆的概念业务模型不是数据库表结构。数据表描述存储结构关注列、主键、索引业务模型描述领域语义关注术语、状态、规则、约束。数据库表结构是实现细节业务模型是稳定契约。AI 不应该被要求直接理解表结构而应该理解业务模型。2. 一个可复用的业务模型包含哪些要素要让模型既服务人类又服务 AI单一文件通常不够最佳实践是“按关注点拆分按目录组织”。一个较完整的业务模型通常包含以下五类要素。2.1 领域术语表术语表解决命名一致性问题。比如“订单”“订货单”“Order”到底是不是同一个概念“已支付”和“支付成功”是否等价。AI Agent 在回答业务问题时最容易在这些地方出错。术语表推荐用 YAML 或 Markdown 维护每条术语包含定义、别名、关联实体、以及面向 AI 的提示词说明。2.2 实体与关系 Schema实体描述业务对象的结构包括必填字段、类型、取值范围、业务含义。推荐使用JSON Schema或OpenAPI Schema保存因为这两个格式既能做程序化校验也能被多种 AI 工具链识别。实体 Schema 里最关键的不是类型约束而是description字段。很多团队写 Schema 只写类型不写业务语义AI 拿到之后还是不知道某个字段到底代表什么。后续实战中我会反复强调这一点。2.3 状态机与业务规则状态机是约束业务对象生命周期最直接的方式。哪些状态之间存在合法流转路径触发事件是什么前置条件是什么这些都要显式建模。业务规则适合用 YAML 声明式描述。既方便人类阅读也方便在 AI 调用工具前做二次校验避免 AI 生成一个不合法的状态变更。2.4 对外服务契约当 AI Agent 需要操作业务对象时它需要知道系统暴露了哪些方法、每个方法接收什么参数、返回什么结果。这就是 OpenAPI 或 Function Calling Schema 的作用。服务契约是业务模型与 AI 工具调用之间的桥梁。理想情况下服务契约里的字段引用和实体 Schema 保持一致而不是各自独立维护。2.5 元数据与描述信息最后也是最重要的是元数据。每个文件都应该有版本号、领域名、维护人、变更说明。AI 消费模型时版本信息能帮助它判断知识时效人类消费模型时版本信息能帮助评审变更影响。3. 环境准备与项目结构本文的实战示例使用 Python 编写不依赖任何重量级框架重点在于演示建模方法和 AI 消费方式。示例环境如下操作系统Linux / macOS / Windows 均可Python3.9 及以上依赖库jsonschema、PyYAML编辑器VS Code 或任意支持 YAML、JSON 的 IDE。如果你的机器上没有安装依赖可以执行pip install jsonschema PyYAML版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。示例项目最终会形成这样的目录结构business-model-demo/ ├── business/ │ ├── glossary.yaml │ ├── entities/ │ │ └── order.schema.json │ └── rules/ │ └── order-rules.yaml ├── api/ │ └── order-service.yaml ├── scripts/ │ ├── validate_order.py │ └── ai_assistant.py ├── data/ │ ├── order.example.json │ └── order.invalid.json └── README.md下面按照这个结构逐步实现。4. 完整实战订单业务模型建模与 AI 消费这一节用电商订单场景完整演示“建模一次双端复用”。场景设定为业务团队需要一套订单领域模型开发团队基于模型开发接口AI 助手基于同一套模型回答订单问题、执行查询与创建操作。4.1 创建项目结构首先创建目录和基础文件mkdir -p business/entities business/rules api scripts data创建项目后我们按“先术语、再实体、后规则、最后契约”的顺序建模。这个顺序很重要先统一语言再定义结构然后约束行为最后暴露能力。4.2 编写领域术语表在business/glossary.yaml中定义订单域核心术语# 文件路径business/glossary.yaml domain: ecommerce version: 1.0.0 maintainer: order-domain-team terms: - term: Order aliases: [订单, sales order] definition: 客户在一次购买行为中创建的一组商品明细、价格与履约信息。 一个 Order 至少包含一个 OrderItem。 related_entities: [OrderItem, Customer, Shipment] ai_prompt_hint: 当用户提到“下单 / 订单 / 购买记录”时对应本实体。 - term: OrderItem aliases: [订单明细, 明细行] definition: 订单中的单一商品行包含 SKU、购买数量和成交单价。 同一订单内不允许出现重复 SKU。 related_entities: [Order, Product] - term: CREATED aliases: [已创建, 待支付] definition: 订单刚创建尚未支付。这是订单的初始状态。 ai_prompt_hint: 如果用户询问“未支付订单”通常指 status CREATED。你可以看到每条术语除了基本定义还增加了ai_prompt_hint字段。这非常关键它直接告诉 AI 模型在什么场景下应该关联该术语比单纯定义更贴近 Agent 使用习惯。4.3 定义订单实体 Schema在business/entities/order.schema.json中定义订单实体{ $schema: https://json-schema.org/draft/2020-12/schema, $id: https://example.com/business/order.schema.json, title: Order, description: 订单聚合根。创建订单时必须至少包含一个商品明细状态必须从 CREATED 开始。, type: object, required: [orderId, customer, status, items, totalAmount], properties: { orderId: { type: string, description: 订单唯一标识由订单中心生成格式如 SO20250501001 }, customer: { type: object, description: 客户概要信息, required: [customerId], properties: { customerId: { type: string, description: 客户唯一标识 }, name: { type: string, description: 客户显示名称可省略 } } }, status: { type: string, enum: [CREATED, PAID, SHIPPED, COMPLETED, CANCELLED, REFUNDED], description: 订单生命周期状态状态流转规则见 rules/order-rules.yaml }, items: { type: array, description: 订单明细行至少一项, minItems: 1, items: { type: object, required: [sku, quantity, unitPrice], properties: { sku: { type: string, description: 商品 SKU 编码 }, quantity: { type: integer, minimum: 1, description: 购买数量必须大于 0 }, unitPrice: { type: number, exclusiveMinimum: 0, description: 成交单价单位元必须大于 0 } } } }, totalAmount: { type: number, description: 订单总金额由服务端计算客户端和 AI 调用方禁止直接传值覆盖 } } }这里有几个设计点需要说明第一required字段显式声明必填项。AI 在 Function Calling 场景中如果缺少required模型很可能漏传参数。第二每个字段都写了description。这不是冗余而是给 AI 的关键提示。比如totalAmount描述中明确“禁止直接传值覆盖”AI 在生成参数时就会知道这个字段不应该由它生成。第三status的枚举值同状态机文件保持一致。后面我们会通过校验脚本保证一致性避免人工维护导致偏差。4.4 定义订单状态机与业务规则在business/rules/order-rules.yaml中描述订单状态流转# 文件路径business/rules/order-rules.yaml name: OrderStateMachine version: 1.0.0 description: 订单状态流转规则业务团队与 AI Agent 均以本文件为准。 states: [CREATED, PAID, SHIPPED, COMPLETED, CANCELLED, REFUNDED] transitions: - from: CREATED to: PAID event: PAYMENT_SUCCESS condition: 订单金额与支付金额一致 - from: CREATED to: CANCELLED event: USER_CANCEL condition: 支付前用户取消或超时未支付自动取消 - from: PAID to: SHIPPED event: SHIP condition: 库存可用 - from: SHIPPED to: COMPLETED event: CONFIRM_RECEIPT condition: 用户确认收货或系统超时自动确认 - from: PAID to: REFUNDED event: REFUND condition: 售后退款通过原路退回状态机文件的消费方有两个人类业务人员可以评审每个流转是否合理AI 助手可以把这些规则折叠进 Prompt回答“订单能不能取消”“取消条件是什么”这类问题后端代码也可以读取该文件在状态变更接口中做前置校验。一个实际项目里的状态机可能更复杂可能包含状态层级、并行状态、超时事件但建模思路是一致的把规则显式化而不是藏在代码if/else里。4.5 定义 AI 可消费的 API 工具业务模型最终需要通过 API 暴露给 AI。在api/order-service.yaml中定义 OpenAPI 契约# 文件路径api/order-service.yaml openapi: 3.0.0 info: title: Order Service Business API version: 1.0.0 description: 电商订单业务 API供人类开发者和 AI Agent 统一调用。 paths: /orders: get: summary: 查询订单列表 operationId: listOrders description: 可按订单状态或客户 ID 过滤订单适合处理“有哪些待发货订单”等查询场景。 parameters: - name: status in: query required: false schema: type: string enum: [CREATED, PAID, SHIPPED, COMPLETED, CANCELLED, REFUNDED] description: 按订单状态过滤 - name: customerId in: query required: false schema: type: string description: 按客户 ID 过滤 responses: 200: description: 订单列表 content: application/json: schema: type: array items: $ref: https://example.com/business/order.schema.json post: summary: 创建订单 operationId: createOrder description: 创建一笔新订单订单状态必须为 CREATED且至少包含一个明细行。 requestBody: required: true content: application/json: schema: $ref: https://example.com/business/order.schema.json responses: 201: description: 创建成功这份 OpenAPI 既可以直接提供给人类前端团队联调也可以导入到支持 OpenAPI 的 Agent 平台自动生成 AI 可调用的工具。$ref引用同一份实体 Schema是实现“单一事实源”的关键手法。4.6 编写 AI 消费示例下面编写两个脚本。第一个负责校验订单数据是否符合实体 Schema# 文件路径scripts/validate_order.py import json import sys from pathlib import Path from jsonschema import Draft202012Validator def load_json(path: Path): return json.loads(path.read_text(encodingutf-8)) def main(): if len(sys.argv) ! 5: print(用法python validate_order.py --order 订单json --schema schema.json) sys.exit(1) args sys.argv[1:] order_path Path(args[args.index(--order) 1]) schema_path Path(args[args.index(--schema) 1]) if not order_path.exists() or not schema_path.exists(): print(文件不存在请检查路径) sys.exit(1) order load_json(order_path) schema load_json(schema_path) validator Draft202012Validator(schema) errors sorted(validator.iter_errors(order), keylambda e: list(e.path) if e.path else []) if errors: print(校验失败) for err in errors: path_str ..join(str(p) for p in err.path) or root print(f - {path_str}: {err.message}) sys.exit(1) print(订单数据通过业务模型校验) if __name__ __main__: main()第二个脚本演示如何把业务模型转化为 AI 可读上下文和工具描述# 文件路径scripts/ai_assistant.py import json from pathlib import Path import yaml def load_business_context( base_dir: str business, glossary_path: str business/glossary.yaml, rules_path: str business/rules/order-rules.yaml, ) - str: 把术语表、状态机汇总为 AI 可读的上下文文本。 glossary yaml.safe_load(Path(glossary_path).read_text(encodingutf-8)) order_rules yaml.safe_load(Path(rules_path).read_text(encodingutf-8)) lines [] lines.append(你是订单业务域 AI 助手。请严格遵循以下业务模型) lines.append(\n 领域术语 ) for item in glossary[terms]: aliases 、.join(item.get(aliases, [])) definition item[definition].strip().replace(\n, ) lines.append(f- {item[term]}{aliases}{definition}) lines.append(\n 订单状态机 ) for t in order_rules[transitions]: lines.append( f- {t[from]} - {t[to]}事件{t[event]}条件{t[condition]} ) return \n.join(lines) def build_order_tool_schema(): 把业务 API 转换为 Function Calling Schema供 LLM 平台使用。 return [ { type: function, function: { name: list_orders, description: 查询符合条件的订单列表适合回答“有哪些待发货订单”之类的问题。, parameters: { type: object, properties: { status: { type: string, enum: [CREATED, PAID, SHIPPED, COMPLETED, CANCELLED, REFUNDED], description: 按订单状态过滤, }, customerId: { type: string, description: 按客户 ID 过滤, }, }, }, }, }, { type: function, function: { name: create_order, description: 创建一笔新订单。使用前必须确认至少存在一个明细行状态固定为 CREATED。, parameters: { type: object, properties: { customerId: {type: string}, items: { type: array, items: { type: object, properties: { sku: {type: string}, quantity: {type: integer, minimum: 1}, }, }, }, }, required: [customerId, items], }, }, }, ] if __name__ __main__: print( AI 可读业务上下文 ) print(load_business_context()) print(\n Function Tool Schema ) print(json.dumps(build_order_tool_schema(), ensure_asciiFalse, indent2))真实项目中build_order_tool_schema可以由 OpenAPI 文件自动生成不需要手写。这里手写是为了让读者直观看到 AI 最终拿到的结构长什么样。4.7 运行与验证准备一份合法订单数据data/order.example.json{ orderId: SO20250501001, customer: { customerId: C10001, name: 张三 }, status: CREATED, items: [ { sku: SKU-001, quantity: 2, unitPrice: 199.0 } ], totalAmount: 398.0 }再准备一份非法订单数据data/order.invalid.json{ orderId: SO20250501002, customer: { customerId: C10001 }, status: PAID, items: [], totalAmount: -50.0 }非法数据缺少客户名称、明细为空、总金额为负数同时状态直接是 PAID属于典型的不符合业务模型的数据。运行校验脚本cd business-model-demo python scripts/validate_order.py \ --order data/order.example.json \ --schema business/entities/order.schema.json python scripts/validate_order.py \ --order data/order.invalid.json \ --schema business/entities/order.schema.json预期第一次校验输出订单数据通过业务模型校验预期第二次校验输出类似校验失败 - totalAmount: -50.0 小于最小值 0 - items: [] 短于最小长度 1 - status: PAID 不是枚举 [CREATED, PAID, ...] 中的值运行 AI 消费脚本python scripts/ai_assistant.py输出会展示 AI 拿到的业务上下文和工具定义。你可以在支持 Function Calling 的 LLM 平台中直接使用build_order_tool_schema()返回的列表也可以把load_business_context()的结果拼进 system prompt。5. 常见问题与排查思路在给团队和客户落地这套方案的过程中以下问题出现频率最高。问题现象常见原因解决思路AI 调用工具时经常漏参数Schema 中缺少required声明或description太模糊在实体 Schema 中显式声明必填字段并为每个字段补充业务语义描述订单状态判断经常出错状态枚举在多个文件中手写维护出现不一致以业务模型和状态机文件为唯一来源通过脚本校验一致性模型更新后 AI 行为未生效Prompt 或工具定义被缓存没有随模型版本重新加载模型文件版本化发布流水线中强制刷新 AI 上下文AI 生成了业务规则不允许的请求只有 Schema 校验没有做状态机规则校验在工具调用前增加规则引擎校验不符合规则直接拒绝人类文档和 AI 上下文说法不一致文档市场和 AI Prompt 由不同团队维护从同一份业务模型自动生成文档与上下文片段JSON Schema 校验报“无此 draft”使用了不常见的 $schema 值或旧版本 jsonschema统一使用 2020-12 版本并确认jsonschema版本支持一个常见的误区是只把业务模型当成“给 AI 读的说明书”。实际上同一份模型可以同时驱动前端表单校验、后端参数校验、接口文档生成和 AI 工具定义。如果你发现某个消费方和模型不同步第一件事不是改消费方的临时代码而是检查为什么模型变更没有自动传播。排查这类问题我一般按下面的顺序来检查模型文件是否已正确更新且通过版本管理检查消费脚本是否重新生成或重新加载了模型用校验脚本跑一遍样例数据确认 Schema 本身没问题检查 AI 平台是否使用了旧的工具定义或缓存。6. 最佳实践与工程建议把“一次建模双端复用”落到生产环境需要从工程上建立一套可持续的机制而不只是写几个 YAML 文件。6.1 把业务模型当成代码来管理业务模型文件应该进入 Git 仓库走代码评审流程。术语表、实体 Schema、状态机文件都应当有版本号。模型变更时关联的 API 文档、AI Prompt、数据库映射脚本要同步评估影响面。每次变更建议写清晰的 changelog例如version: 1.1.0 changes: - 新增 REFUNDED 状态允许已支付订单在售后审核通过后退款 - 新增字段 totalAmount 只读约束6.2 为 AI 消费场景设计描述信息JSON Schema 本身并不要求写description但面向 AI 消费时description几乎是模型里最重要的字段。它直接影响 LLM 对字段语义的理解进而影响工具参数生成的正确性。写description有几个技巧说明业务含义而不是重复字段名说明取值边界或生成约束说明与其他字段的关系对 AI 特别容易混淆的状态、别名给出判断提示。6.3 用工具保证模型一致性人工同步多个文件总会有纰漏。建议在 CI 中增加一条检查读取实体 Schema 中的status枚举与状态机文件中的states做比对读取 OpenAPI 中的enum与实体 Schema 比对。任何不一致直接让流水线失败。更进一步的方案是从实体 Schema 自动生成部分 OpenAPI 定义而不是手写两遍。这样“单点定义多点引用”才能落到实处。6.4 给 AI 工具调用设置安全边界这是生产环境中优先级最高的一点。AI Agent 能够调用业务 API不代表它拥有无限制的操作权限。需要明确AI 工具在执行写操作前必须经过身份认证和权限校验状态类变更必须经过业务规则引擎校验不能只靠 Prompt 约束所有 AI 触发的操作都应该有审计日志记录调用来源、参数和结果涉及退款、取消、删除、金额变更等敏感操作建议加入人工审批环节。“让 AI 更智能”和“让 AI 更安全”不矛盾。模型的语义越清晰安全校验越容易做。6.5 设计模型演进机制业务会变模型也会变。建议在早期就考虑模型演进机制。比较保守且实用的做法是兼容性变更新增可选字段、新增枚举值直接升级小版本破坏性变更改字段名、改必填项、删除枚举值必须走专项评审并在模型文件中标注迁移逻辑为 AI 消费方提供“模型生效时间”元数据避免线上 Agent 还在使用旧模型。6.6 让业务同学参与模型评审业务建模不是纯技术工作。术语表的准确性、状态条件的合理性都需要业务同学确认。建议在每次模型变更后把 YAML 文件渲染成人类可读的 Markdown 或表格发给业务方走读确认。让业务同学看到“这份模型能被 AI 理解”他们才会愿意持续维护。7. 总结与下一步学习建议本文围绕“Model your business once – for humans and AI alike”展开介绍了业务模型作为人与 AI 共同消费的单一事实源这一核心思路。我们完成了电商订单领域的术语表、实体 Schema、状态机和 OpenAPI 契约的定义并用 Python 脚本演示了模型校验和 AI 上下文生成两个典型消费场景。如果你现在开始在自己的项目里实践这套方法我建议按以下节奏推进先从一个小领域开始比如订单、支付或用户只定义术语表和实体 Schema接入一个 AI 消费场景比如让 Agent 基于 Schema 做工具调用逐步加入状态机、规则校验和 CI 一致性检查当模型稳定后再把文档生成、前端校验等消费方接入同一份模型。下一步可以学习的方向包括领域驱动设计DDD中的聚合与事件风暴、知识图谱与本体建模、OpenAPI 工具的自动生成方案以及主流 LLM 平台的 Function Calling 和 Tool Use 机制。这些内容都会加深你对“人和 AI 共用模型”的理解。如果你也在搭建类似的企业级业务模型建议从最小闭环开始一份术语表、一个实体 Schema、一个 AI 工具定义。跑通之后再逐步扩展。模型的价值不在于一次性设计得多完美而在于后续每次业务变化时能让所有“读者”保持一致。