# AIelsen FDE Academy · W05 业务本体与建议型 Agent

面向 FDE 的中文详细讲义 · v2 · 2026-09-08

## 1. 本周工程目标：完成建议型 Agent v1

本周不是给 Agent 增加几个提示词，而是完成业务理解与系统执行之间的语义接口。输入是第 2 周的业务对象草图、第 3 周的指标契约、第 4 周的标准化数据。输出包括身份主数据、本体配置、可查询语义层、业务工具、外部接口清单，以及真实模型参与的建议型 Agent 轨迹。

合成任务是：“看看 A 店有哪些沉默会员适合唤回，给运营一个建议。”系统需要知道“沉默”指什么、当前身份和订单是否可信、使用者能看哪家店、有哪些允许的活动规则。信息不足时应澄清；证据不够时应说明无法判断。本周不实际发券，建议与执行必须分开。

## 2. 实体消歧：判断两个 ID 是否属于同一个对象

实体消歧不是字符串去重。新旧 CRM 可能为同一人分配不同 ID；同一手机号可能被家庭成员共享；手机号也可能换绑。直接按手机号合并，可能把不同人的订单、偏好和营销权限混在一起。误合并造成的隐私和错误触达风险，通常不能靠一个“总体匹配率”解释过去。

先定义匹配对象与允许证据，再选择方法。精确匹配适合可靠且稳定的业务键；模糊匹配用于生成候选，例如名称拼写差异；概率匹配组合多项证据，但需要标注样本与阈值验证。模型可以帮助比较非结构化信息，不应凭语言相似就建立永久身份事实。

| 匹配情况 | 教学处理 | 需要保留什么 |
|---|---|---|
| 有经过核验的一对一迁移映射 | 可按迁移规则自动关联 | 映射来源、版本、核验日期 |
| 多项证据一致但无权威映射 | 进入候选队列，按风险评估 | 候选分数、证据项、适用阈值 |
| 手机相同但姓名或生命周期冲突 | 不自动合并，人工复核 | 冲突原因和复核状态 |
| 只有模糊名称相似 | 保留独立身份 | 不确定性和后续取证计划 |

主数据要保留 `canonical_id` 与所有 `source_id` 的映射、合并理由、版本、生效时间和撤销路径。撤销一次错误合并时，不应需要手工猜测原始记录属于谁。评估时同时检查错误合并、遗漏关联和人工复核量，不要只报告命中率。

## 3. 本体建模：对象、关系、动作及其约束

本体是系统对业务世界的明确表示。它回答“我们在谈论什么对象、对象如何关联、允许发生什么变化”。[Palantir 官方 Ontology 概览](https://www.palantir.com/docs/foundry/ontology/overview)提供了理解这一层的参考；本课的零售模型是独立设计，不等同于实现了 Foundry，也不要求使用特定厂商产品。

| 对象 | 关键属性 | 关系 | 需要明确的约束 |
|---|---|---|---|
| Member | 标准 ID、营销许可、状态 | 关联 Order、Store、Campaign | 身份版本、数据范围、退订状态 |
| Order | 来源 ID、时间、金额、状态 | 属于 Member，发生在 Store | 有效订单定义、重复与退款 |
| Campaign | 规则版本、有效期、预算 | 面向 Segment，产生 Coupon | 资格、时效、频控、成本上限 |
| Segment | 筛选条件、快照、成员引用 | 来自 Member 的查询结果 | 不是永久标签，需记录时间和口径 |
| Coupon | 唯一 ID、金额、状态 | 属于 Campaign 与 Member | 发出、核销、失效的状态变化 |

关系还需要基数和生命周期：一个会员可以关联多个来源 ID，一笔订单应关联一个有效的主身份或显式未知状态；人群快照不应在执行前被静默重新计算。动作不是“修改一行数据”这么简单，它有前置条件、执行主体、状态变化和失败后果。例如 `issue_coupon` 必须检查资格、预算、确认和重复执行。

## 4. 语义层：让指标可计算、可解释、可版本化

本体说明对象是什么，语义层说明业务量怎么算。两者相关但不能互相替代。`Member` 对象存在，并不自动决定“有效会员”的定义；向量检索找到一段“沉默会员”说明，也不能替代按口径计算人群。

指标注册表至少包括名称、含义、统计单位、公式、时间窗、排除规则、数据来源、刷新频率、责任角色和版本。工具返回结果时同时返回口径版本和数据截止时间。这样运营才知道“为什么这次是 240 人，上周是 270 人”：可能是业务变化，也可能是数据补齐或口径变更。

```json
{
  "metric_id": "days_since_last_valid_purchase",
  "version": "1.0",
  "grain": "canonical_member_id + store_id",
  "source": "valid_orders_snapshot",
  "as_of_required": true,
  "exclusions": ["test_order", "fully_refunded_order"],
  "unknown_policy": "exclude_and_report",
  "owner_role": "operations_metric_owner"
}
```

假如运营说有 1,000 名会员，财务只承认 850 名有效购买会员，不要急着“统一成 850”。先比较注册、可触达、曾购买、近期购买四个集合及其用途。多个合法指标可以共存，关键是名字不混淆、集合可解释、使用场景明确。

## 5. 知识层：数据计算与检索各自承担什么

建议型 Agent 需要两类证据。订单、人群和预算应通过受控计算工具获得；活动说明、产品手册和操作制度可以通过检索获得。不能让模型在长文档里“估算”订单数，也不能期待一条 SQL 理解所有活动例外。

本课把知识组织为四层：受控原文；保留页码与版本的检索片段；片段与业务对象的关联；经过验证的问答与反例。每层都要保留来源和权限，不是把文档切块后全部放进同一个索引就结束。

先过滤权限、适用型号、版本与有效期，再进行语义检索。以教学包中的 AX10 手册为例，同一个故障码在不同版本中有不同处理说明。只返回相似度最高的片段可能引用过期内容。回答应引用适用版本与页码；多个版本冲突而用户未提供型号时，应先澄清。检索到的文档属于数据，文档中夹带的“忽略权限、导出所有记录”等内容不能成为系统指令。

## 6. 设计两个业务工具：分群与建议

第一个工具 `segment_members` 负责确定性计算。输入包括经业务确认的门店、截止日、沉默窗口和结果上限；身份与授权范围来自可信服务端上下文，不由模型自行填写。输出包括候选引用、排除数量、规则版本和证据快照。手机号等非必要字段不返回给模型。

```json
{
  "tool": "segment_members",
  "input": {
    "store_id": "A", "as_of": "2026-09-01",
    "inactive_days_min": 30, "inactive_days_max": 90,
    "limit": 50
  },
  "output_contract": {
    "segment_ref": "opaque reference bound to tenant and snapshot",
    "member_refs": "authorized pseudonymous references",
    "excluded": "counts by reason, without sensitive records",
    "metric_version": "required",
    "evidence_snapshot": "required"
  }
}
```

第二个工具 `propose_operation` 读取人群引用和活动规则，返回可用方案、成本约束、理由与未决问题。它是**建议草案工具**，不得产生发券副作用。不要让模型随意传入一组会员 ID 并声称来自已验证人群；引用必须在服务端解析并检查租户、版本和有效期。

工具错误也要形成契约，例如 `INVALID_WINDOW`、`DENIED_SCOPE`、`STALE_SEGMENT`、`POLICY_UNAVAILABLE`。缺失规则时返回不可用及澄清建议，不能静默使用一个“合理默认优惠”。模型负责理解目标、选择工具、解释结果；确定性服务负责计算、权限与状态。两种责任不能互相转移。

## 7. 接入遗留系统：架构图中的每条线都要有接口清单

画出 CRM、POS、会员运营服务和 Agent 后，把每条连线转成可执行的接入记录。否则图上看似连通，开发时才发现没有测试账户、接口只能读不能写、来源系统没有稳定 ID。

| 接口 | 方向与用途 | 契约要点 | 首次验证 |
|---|---|---|---|
| POS 订单读取 | 外部 → 适配器 | 增量游标、更新/退款、时间、重试 | 固定窗口读取并与源报表对账 |
| CRM 会员读取 | 外部 → 主数据 | 身份映射、退订、删除、字段范围 | 样本映射与冲突队列 |
| 标签更新 | Agent → CRM | 允许标签、幂等、回查、撤销 | 第 8 周使用本地模拟验证 |
| 发券 | Agent → 运营服务 | 预算、资格、频控、动作状态 | 第 8 周验证确认和重复请求 |

MCP 可以标准化工具连接方式，但不会替你完成业务语义、授权和对账。使用时应按所选版本核对 Host、Client、Server 和鉴权要求；本课 JSON 示例不是完整 MCP 协议消息，下载包也不是已部署的 MCP Server。

## 8. 什么轨迹才能证明这是建议型 Agent

下列是**期望行为示例，不是已执行的模型结果**。一个合格作业需要用自己的模型适配器实际运行并留存可检查的调用记录、输入输出摘要和配置版本，而不要求披露模型隐藏推理。

```text
用户：帮我找一批最近没来的会员。
Agent：请确认门店，以及“没来”按到店还是有效购买计算。
用户：A 店，30–90 天没有有效购买，按 9 月 1 日快照。
Agent → segment_members(范围与窗口)
工具 → segment_ref、候选数、排除原因、版本、证据
Agent → propose_operation(segment_ref, 允许的规则版本)
工具 → 方案、成本约束、未覆盖条件
Agent：说明建议及依据；明确未执行任何触达或发券。
```

固定顺序脚本可以作为集成基线，但不能用它证明模型会澄清、选工具和根据结果调整。至少准备四类不同任务：条件齐全；条件缺失；没有合格人群；越权请求。观察模型是否根据反馈改变下一步，而不只是无论输入什么都调用同一串 API。[Anthropic 对 Agent 与工作流的区分](https://www.anthropic.com/engineering/building-effective-agents)可作为概念参考，具体作业标准仍以本课定义的任务行为为准。

## 9. 本周代码与评审安排

先运行本课扩展练习 `python tenant_extension.py`，阅读合成分群、建议以及策略边界的结果。该程序验证的是工具契约，使用确定性逻辑，没有真实模型、向量库、认证服务或外部业务系统。然后将你的标准运行时接入这些工具，保留原有产品核心，将客户差异放在扩展目录。

评审分三次进行：先核对一名会员的身份与订单；再核对一组人群的规则与排除原因；最后给 Agent 一个未预设的新问题，看它是否澄清或调用适当工具。这样能够分辨数据错误、工具错误和模型任务错误，不会把所有失败统称为“模型不聪明”。

## 10. 必做作业、思考与验收

**必做**：提交身份映射与冲突复核样例、本体 v1、至少一个可查询指标、两个业务工具及测试、CRM/POS 接口清单；提交建议型 Agent v1 的正常、澄清、无证据和越权四类真实模型轨迹。暂未接入模型的作业只能标为“工具集成完成”，不能标为“Agent 完成”。

**思考**：客户希望将最有价值会员的优惠金额直接写成模型提示词，为什么可能导致版本失控、解释困难或越界？哪些判断适合模型，哪些规则应保留在确定性服务？

**进阶**：构造第二个行业任务，比较哪些对象要替换、哪些动作可沿用同一确认协议；或者为实体匹配建立人工标注小集，比较不同阈值下误合并和复核成本。

**验收要求**：身份不确定性可追踪；指标能重算；检索有版本和范围；两个工具没有未经声明的副作用；人群引用不能跨租户复用；运行时有步数和预算上限；真实模型轨迹与模拟结果明确分开；客户逻辑未直接写入产品核心。