本体知识库说明书

版本：v3.0 · 2026-09-07 · 本版新增第六章《可判定与编译》并将工作流程改为三期。历次版本、每版改了什么见文末附录 · 修订记录；每版定稿同时导出一份带版本号与日期的 HTML 存于 docs/。

本书的用途：这是信贷业务本体知识库的完整说明。第一至四章是架构说明——知识库由哪些构件组成、每个构件是什么、存成什么样、最终呈现为什么；第五章是执行纪律——供 LLM 在处理知识分类时遵照执行：按照该章的判定流程与纪律，对全部业务知识做一轮完整分类，归入本书定义的架构；第六章是可判定与编译规范——定义知识如何从"可引用"升到"可判定"，如何编译成生产只读的产物，以及动作执行与数据写回的契约。 理论基础：Palantir 本体论（Ontology）。 本书的边界：平台四层架构中，本书只覆盖本体层（语义定义与登记）及两个伸出去的钩子——接地规范（第三章）与 LLM 分类纪律（第五章）；数据加工、应用与自动化、权限治理由协作平台与行方系统承担（见 1.1 架构图）。

第一章 · 架构总览

1.1 理论基础：Palantir 本体论

Palantir Foundry 的 Ontology 是把企业业务世界建成"数字孪生"的方法论：不直接面对成百上千张数据表，而是先用少数几类构建块（Building Blocks）把业务世界描述清楚——对象类型（世界上有什么）、属性（它们处于什么状态）、链接类型（它们如何关联）、动作类型（我们能对它们做什么）、函数（如何从已知算出未知）——再把每个构建块逐一"接地"到真实数据。这样，业务语言和数据语言之间有了一层稳定的语义层：业务同事用业务词汇讨论和沉淀知识，数据自动跟随；数仓改表改字段，只动接地层，知识本身不失效。

从平台整体看，Foundry 的完整技术栈分四层：数据层把数据接进来、清洗加工成数据集（银行场景即核心、信贷、征信、押品等源系统与数仓管道）；本体层把表变成业务概念——行变对象、列变属性、关联变链接，本书的六构件就活在这一层；应用与自动化层让语义产生行动（操作型应用、分析、事件驱动的自动化、LLM）；安全与治理贯穿所有层。本书只覆盖本体层，外加两个伸出去的钩子：向下伸进数据层的接地规范（第三章），向上伸进应用层的 LLM 分类纪律（第五章）。其余的层由协作平台与行方现有系统承担：

1.2 两张总图与关系矩阵

图一 · 本体构件分类——顶部是 DOC 原文档输入层：知识的源头，每条构件的 source 都指向原文档的段落锚，任何知识都可溯源到它来自哪份文件；中部是六类构件与它们的关系（实线＝结构与读写，橙虚线＝挂载：规则型函数指向宿主）；底部虚线框是第二阶段 · 数据字段匹配层【二期】：

图二 · 细分构件框架——每类构件的内部细分：

构件关系矩阵——任意两类构件之间是什么关系、靠哪个字段落地。读法：先行后列，取右上三角（矩阵对称，左下省略）；"无直接关系"也是结论，不许私搭关系。

这张矩阵连同 4.2 的图谱约束，属于框架层约束：管构件之间的结构，由平台校验、违反即数据错误——与函数表里管业务的"规则"是两个层面（四个术语的分工见 1.7）。

1.3 一句话总纲

对象是骨架，属性是状态，动作和函数推动状态变化，规则给变化划界，接口把同形归并。（规则是函数的一个类型，与计算并列，同住一张函数表。）

四个核心判定题贯穿全书：执行主体是谁（机构操作者＝动作，客户＝事件对象）、改不改状态（改＝动作，只出数只判定＝函数）、存着的还是算出来的（属性 vs 计算型函数）、带不带 if（规则型函数）。

1.4 工作流程：三期

三期不是串行的三道工序，而是每条知识各自要走完的三级台阶：一条规则可以在支用段已到 L1，而在催收段还停在一期。use case 是推动条目走完三级的组织单位（见 6.1 与辅助登记 U）。

后续 · 衍生与治理（本说明暂不涉及）：在原始字段之上做衍生（衍生指标、衍生模型）时再引入的内容——关系真理强度标定（derived / causal）、计算型函数的完整治理（细分六型、输入清单、版本与边界红线）、接口归并等。

1.5 总览导航表

辅助登记（服务知识、本身不是知识）：C 对照词典（属性↔数仓列，【二期】）、DOC 文档登记（出处锚，一期起用）、S 切片（工作分区）、U use case（一个决策的闭环链路：成员清单 + 四步叙事 + Agent 查阅点，【三期】，见 6.10）、X 冲突登记、G 缺口清单。区分判据：删掉它，对世界的描述会不会少一块——会＝构件，不会＝辅助。

1.6 三条全表通用约定

1. 引用一律用 ID：宿主、写入方、两端等跨表引用一律填构件 ID（如 host: A-042），不填名字——改名不断链。给人读的文档处采用"名字（ID）"双写。
2. 双名：每张表都有 zh（中文名）与 en（英文名）；规则型函数的 en 填语句短名（如 accept-within-24h）。
3. 三态填写：有值＝知道；none＝确认无/不适用（合法记录，本身是知识）；留白＝尚未梳理（缺口，审核打回）。"必填"的含义是必须表态：不许沉默，允许说没有。

1.7 常用术语速查

本书反复出现的几个词，先在这里说清楚：

1.8 建模守则与核心原则（源自 Palantir Best Practices）

以下守则与原则取自 Palantir 官方的 Ontology design best practices，是生成语义层内容时要遵守的规矩——即把业务知识整理成对象、属性、链接、动作、函数、接口这六类构件的时候（无论是业务同事手工登记，还是 LLM 按第五章批量分类），都按这些守则做。它们属于 1.7 定义的建模原则层：靠人判断与审核执行，机器拦不住。每条标注它在本书的落点：已内建的照做即可，标"新增纪律"的是本节新立的要求。

七条设计守则：

四条核心原则：

第二章 · 构件详解

本章逐一说明六类构件。每节的结构：局部关联图 → 定义与判定 → 细分类别 → 相连关系 → 存储表（字段词典＋样例）。局部关联图中的编号 ❶❷❸… 与"相连关系"表的行号一一对应——看图找线，对号读表。

2.1 对象（N · 紫色）

定义与判定

按 Palantir 的定义，对象类型是真实世界中某一类实体或事件的模式定义（"the schema definition of a real-world entity or event"）；对象是对象类型的一个实例，对应一个具体的真实世界实体或事件。官方给的类比最直观：对象类型相当于一张数据集，对象相当于其中的一行——"客户"是对象类型，某一位具体客户是一个对象；"支用事件"是对象类型，某一笔具体支用是一个对象。

由此推出对象的两个特征：每个实例有唯一身份标识（Palantir 中即主键属性，我们登记为 identity 列），因此能被逐个指认、清点数量；每个实例有自己的生命周期，产生、变化、终止都可追踪。判定时问一句：它能不能落成"一行"——有没有一个标识把这一个和那一个分开？"支用事件"能，一笔一行，是对象；"风险"不能，它是程度描述，落不成行，不是对象。

来自数据侧的辅助判据：身份标识列揭示对象。数据里每出现一种起标识作用的列（ref_nbr、merchantName、agentcode），背后就站着一个对象类型。判断对象看标识，不要被表名迷惑。

对象是一切构件的宿主锚点：属性描述对象、链接连接对象、动作作用于对象、函数读写对象的属性、规则经它们间接挂到对象。

细分类别（二分，即 type 字段的取值——沿用 Palantir 的实体 / 事件）

Palantir 对对象类型的定义是"真实世界实体或事件的模式定义"，本书沿用这一刀，不再细分：

最重要的分界：客户发起的行为（支用/还款/申请）归"事件"——动作类型只收录机构侧的操作。Palantir 原文对此的支撑：对象类型是 "schema definition of a real-world entity or event"，且官方例子直接列出 "customer orders or financial transactions"——客户做的事在官方口径里就是对象；而动作类型 "capture data from operators in your organization"，客户不在其列（三段原文与推理见 2.4）。

动作产物标记（product_of，机器推导）：有一类对象不是客户做出来的，而是机构动作留下的产物——机构查征信是一个动作（A 号），返回并留存的征信快照就是这个动作的产物；外呼是动作，通话记录是产物；受理支付是动作，借据是产物。产物对象不限二分：事件（征信快照、通话记录）和实体（借据、账户、券）都可以是动作的产物；多个动作产同一类对象时 product_of 多值（借据←受理支付/放款/重组/转分期）。产物对象在 product_of 字段写产出它的动作号，与动作卡的 product 字段互指（同一条边的两个视角，如同 writer ↔ side_effects）。判据不靠人猜"谁触发"：出现在某张动作卡 product 里的对象，就是它的产物——机器可推导、可校验。客户自己做出的事件（支用、还款、申请、登录、定位）没有 product_of，是常态。

这是 2.4"观测与干预分离"红线在对象侧的落点，审查义务只落在事件对象上：product_of 非空的事件是机构干预留下的痕迹，进模型特征前须显式审查，否则模型学到的是"机构何时出手"而不是客户风险。实体的 product_of 只是来源溯源（记录哪个动作造出它），不带审查义务。（本段口径由 X-046 收口：原「事件专用」放宽为实体、事件都可填。）

相连关系（对应图中编号）

标识语义示例（易错点）：mpc_uid 标识的是客户（人），acct_no 标识的是贷款账户——两个标识符就是两个对象；记录它们对应关系的映射表，是"客户-持有→贷款账户"这条链接的实例清单。用 acct_no 的表记录的是账户的事，用 mpc_uid 的表记录的是人的事——属性归宿主时按此判断。

存储表：对象表 objects.yaml

grounding 子字段（【二期】数据团队回填）：

四个子字段各回答一个问题（沿用"对象类型≈一张表、对象≈一行"的类比）：

样例（覆盖实体 / 事件、动作产物与 grounding 三种状态）：

- { id: N001, zh: 客户, en: Customer, type: 实体,
    definition: 在体系内开户的个体（人）,
    grounding: { dw_table: mpc_user_profile, identity: mpc_uid, verify: verified },
    source: DOC-2026-001#p3, status: verified, asOf: '2026-08-07', by: trista }

- { id: N009, zh: 贷款账户, en: LoanAccount, type: 实体,
    definition: 客户名下的授信账户，额度/管控/账期的宿主,
    grounding: { dw_table: icpmms_cust_info, identity: acct_no, verify: verified },
    status: verified }

- { id: N015, zh: 商户, en: Merchant, type: 实体,
    definition: 消费订单的交易对手方,
    grounding: { dw_table: fact_order, identity: merchantName, no_master: true, verify: judged },
    status: draft }                              # 无主档表：从订单表 DISTINCT 扫出

- { id: N021, zh: 提额申请, en: LimitIncreaseRequest, type: 事件,
    definition: 客户主动发起的提升授信额度请求，一次提交为一个实例,
    grounding: null,                             # 第一阶段留空，二期回填
    source: DOC-2026-031#p4, status: draft, by: leo }

- { id: N025, zh: 登录足迹, en: LoginTrace, type: 事件,                # 客户触发，无需标记
    grounding: { dw_table: fact_login, identity: login_id, verify: judged } }

- { id: N027, zh: 征信快照, en: CreditBureauSnapshot, type: 事件, product_of: A-063,   # 查征信动作的产物
    definition: 机构向征信机构查询后返回并留存的报告快照,
    grounding: null, status: draft }

- { id: N030, zh: 账单, en: Statement, type: 实体,             # 制度物，仍是实体
    definition: 按账期对账户未清项归集生成的应还清单,
    grounding: { dw_table: fact_statement, identity: stmt_id, verify: verified } }

2.2 属性（P · 粉色）

定义与判定

按 Palantir 的定义，属性是某类实体或事件的一个特征的模式定义（"the schema definition of a characteristic of a real-world entity or event"）；属性值是该属性在某个具体对象上的值。沿用"对象类型≈一张表、对象≈一行"的类比：属性≈这张表的一列，属性值≈这一行在这一列上的取值——"授信额度"是贷款账户表的一列，某个账户的授信额度 500 万是一个属性值。

由此推出属性的两个特征：必有宿主——列不能脱离表存在，属性必须挂在某个对象类型上；只存单值——一个对象在一个属性上只有一个当前值（"a conventional object property contains a single value"），历史不塞进属性（见下文约束）。判定时问："它描述的是谁的什么？"——答不出"谁"，说明宿主对象还没建档，先回去立对象。

属性与函数的分界只有一句话：存下来的是属性，算出来的是函数。计算得到的值一旦落库，就取得属性身份、照常登记，只是要在"写入方"字段指回产出它的那个函数——这样任何人看到这个字段，都知道它不是原始事实，而是计算结果。

细分类别（五轴——不是子类，是每条属性同时取值的五个维度）

结构轴速判（按顺序问，命中即停）：

1. 值内部还分段吗？→ 结构组
2. 能同时有多个值吗？→ 集合
3. 取值是有限清单吗？→ 枚举
4. 都不是 → 标量

枚举：什么算枚举

• 定义：取值来自一个有限且封闭的清单——任一时刻值必然是清单中的某一个，清单之外出现任何值即为数据错误
• 登记要求：清单里每个取值的业务含义逐个登进取值字典（states.yaml）——"每个取值是什么意思"本身就是一条知识
• 判别口诀：能一口气把所有可能的值列完的，就是枚举

共享池：口径正本库

属性只有当前值（约束）

• 约束：属性不承载历史。一个值的变化轨迹由事件对象承载（只追加，如还款记录、征信快照）；禁止用数组属性硬塞历史
• 判定问句：需要历史时先问——"记录这段历史的事件或快照对象立了没有？"

Palantir 原文支撑：属性值是单数——"a property value refers to the value of a property on an object"；"a conventional object property contains a single value"。普通属性里没有历史；Palantir 要保留历史时，用的是下面三个机制，没有一个是普通属性：

结论：普通属性只有当前值；要历史，Palantir 三条路都在属性之外——换特殊类型、开审计日志、或建成对象。

完整例子 · 额度四件套：

要看"额度怎么一步步变到今天"：沿"账户→调整记录"链接按时间排，不翻当前额度的历史值。

相连关系（对应图中编号）

存储表：属性表 attributes.yaml ＋ 取值字典 states.yaml

样例（覆盖：事实枚举 / 推断脱敏 / 建议值与核定值对照）：

- id: P003
  zh: 受理状态
  en: AcceptStatus
  host: N021
  origin: 事实
  structure: 枚举
  writer: A-042                    # 只有受理动作能写它
  ownership: 共享                   # 各类申请同款口径
  sensitive: 明文
  definition: 申请当前的受理进度
  enum_ref: states.yaml#accept_status
  crosswalk: [C011]                # 【二期】
  source: DOC-2026-031#p4
  status: draft

- id: P002
  zh: 内部行为评分
  en: BehaviorScore
  host: N001
  origin: 推断                      # → 推断值，不得当原始特征回流
  structure: 标量
  writer: F001
  ownership: 专有
  sensitive: 脱敏
  status: draft

# 建议值 vs 核定值——两个属性、两个写入方（见第五章易混边界）
- { id: P004, zh: 建议额度, en: SuggestedLimit, host: N009,
    origin: 推断, writer: F001 }    # 模型吐的建议，版本一换就变
- { id: P010, zh: 初始额度, en: InitialLimit, host: N009,
    origin: 事实, writer: A-001 }   # 审批核定的决策事实，永不再变

取值字典 states.yaml（枚举型属性的取值明细——每个取值本身是一条知识）：

- dim: accept_status
  attr: P003                       # 挂回属性
  values:
    - { value: P, zh: 待受理, source: DOC-2026-031#p4 }
    - { value: A, zh: 已受理, source: DOC-2026-031#p4 }
    - { value: R, zh: 已拒绝, source: DOC-2026-031#p4 }

落点说明：states.yaml 是取值字典的逻辑名；当前实现把取值直接登在属性条目的 values 字段上（每个取值一条 { value, label }，结构组的位段取值登在 sub_fields），不另建文件。第六章的状态轴字段（when / transitions）同样挂在属性上——状态的宿主、取值、写入方本来就在属性条目里，不再新建状态表。

2.3 链接（R · 灰色）

定义与判定

按 Palantir 的定义，链接类型是两个对象类型之间一种关系的模式定义（"the schema definition of a relationship between two object types"）；链接是这种关系在两个具体对象之间的一个实例。沿用表/行的类比：链接类型≈两张表之间的一个 join（官方原话 "analogous to that of a join between two datasets"），一条链接≈join 结果里的一行——"客户持有贷款账户"是链接类型，某位客户与其名下某个账户的对应关系是一条链接。

由此推出链接的三个特征：两端必须都是对象——join 只能连表，属性、动作、函数都不能作为链接端点（自连也允许：员工↔上级，两端是同一对象类型）；天然双向——一个链接类型两个方向都可遍历，不必为"客户→账户"和"账户→客户"各建一条；有基数——一对一、一对多、多对多；多对多的链接由独立的映射表支撑，其他由外键列支撑（这正是二期接地的落点）。判定时问："它连接的是哪两个对象？"链接用业务动词命名，标明方向与基数。

边不承载属性与历史（建模原则）：链接本身不带属性、不带时间区间。当一段关系需要携带金额、时点、状态时，把它升格为对象——客户与商户的"消费"关系带金额，所以订单是对象而不是一条边。判据：想给边加字段的那一刻，就是该立对象的那一刻。

细分类别（kind——真理强度，衍生分析阶段标定，业务输入不填）

相连关系（对应图中编号）

存储表：关系表 relations.yaml

样例（映射表接地 / 外键接地各一）：

- id: R001
  zh: 持有
  en: holds
  kind: structural
  from: N001                       # 客户（mpc_uid）
  to: N009                         # 贷款账户（acct_no）
  cardinality: '1:1'
  grounding: { dw_table: _cohort_map, columns: [mpc_uid, acct_no], verify: verified }   # 【二期】
  status: verified

- id: R012
  zh: 发生于
  en: occursOn
  kind: structural
  from: N009
  to: N021
  cardinality: '1:N'
  grounding: { dw_table: fact_limit_req, columns: [acct_no], verify: judged }           # 【二期】
  status: draft

2.4 动作（A · 青色）

定义与判定

按 Palantir 的定义，动作类型是"用户可以一次采取的一组对象、属性或链接编辑"的模式定义（"the definition of a set of changes or edits to objects, properties, or links that a user can take at once"）；动作是该定义的一次具体执行（一次提交）。它是本体的"动能"（kinetics）：在遵守机构管控与治理的前提下让数据发生变化——因此动作采集的是机构操作者（operator，机构内有权执行操作的人员或系统：坐席、审批员、策略引擎）的输入，是机构一侧改变业务状态的唯一受治理入口。

类比：动作类型≈一张带权限校验的业务表单＋一次事务性写入——表单规定谁能填、填什么、提交前查什么；提交即一次写入，写完留一条日志。"受理提额申请"是动作类型，策略系统在某时刻对某笔申请做出的那一次受理是一个动作。

由此推出动作的五个特征（每一条都对应 Palantir 动作类型的一个组成部分，也对应动作卡上的一处）：

判定时问两个问题：

• ① 执行主体是谁？ 机构操作者的（审批、调额、冻结、核销）是动作；客户的（支用、还款、提交申请）不是动作，是"事件"类对象（2.1）。
• ② 它是否改变世界？ 只读值、只出数、只给裁决而不改任何状态的，是函数（2.5）；真正把状态改掉的才是动作。因此"审批""风控决策"这类大词要拆开：模型算分＝计算型函数，阈值裁决＝规则型函数，核准落地＝动作。
• ③ 作用对象收敛到"真被编辑的"——target 只登动作改写或处置的对象，且 target 里的每个对象都必须能在同一张卡的 product（产出它）或 side_effects（写它的属性）中找到对应写入——这正是上表"编辑范围事先声明"的闭环：声明了要编辑谁，就必须真的编辑谁。动作发生的落点/上下文（核销在哪笔交易上、放款进哪个钱包、出码绑哪个账户）不进 target，由链接（2.3）表达——否则同一条知识登两处，动作的语义也被撑歪。写不出对应写入时二选一：落点混入 → 移出 target 改登链接；写入漏登 → 补 side_effects 并与属性 writer 互指。（2026-08-20 平台增补，源自 A-38 核销优惠券收口案例；机器检查见纲要合规页同名条目。）

判定①在 Palantir 原文中的依据（三段定义合起来推出，逐条可引）：

三段合起来：客户的行为是真实世界的事件→对象；动作的执行者限定为机构内操作者→客户行为不构成动作；动作是"可采取的编辑"而非"已发生的记录"→形状也对不上。除原文依据外，只收录机构侧操作在业务上还有三条理由：

细分类别（category＝职能域：谁的手，就是谁的类）

动作按职能域分类——执行主体隶属的业务职能。纪律"一个执行主体一张卡"保证了每张卡只属于一个职能：分类天然互斥且完备，业务同学判定零成本（"这是谁的地盘"）。

职能域是开放清单，由业务增补：清单不是本书定死的，而是从各机构的操作清单盘点归纳出来的枚举字典（与 states.yaml 同类维护）。业务同学建卡时找不到合适职能即可新增，审核只做去重归并。下表按信贷生命周期列出常见职能域作为起点，供对照，不是上限：

增补规矩三条：① 按执行主体归属命名（"这个操作是哪个团队 / 哪个系统的职责"），不按动作效果命名（"冻结类"不是职能域，冻结属于交易管控）；② 新增前先查同义（"贷中管理"与"额度管理"取其一）；③ 同一执行主体的动作只能落在一个职能域——若一个团队的动作横跨两域，说明域切得不对，交审核归并。

规矩 ③ 的两个例子——催收坐席做外呼、分案、记录还款承诺三件事，若有人把"记录还款承诺"填成"客服"，催收坐席就横跨了两域：改回"催收"即可（域看执行者归属，不看动作长相）。若卡上执行者写"风控策略团队"，而它既核准额度（授信审批）又调额（贷中管理），有两条修法：把执行者写细——实际执行的是"授信决策引擎"与"额度策略系统"两个系统，各归各域；或承认这两个域在本机构就是同一团队的地盘，合并为一个域。哪条都行，交审核定，但不允许留着"一个执行者、两个域"——那会让下一张卡不知该填哪个域。

其余维度不占分类轴，各归其位：

拆卡与并卡——业务大词先在时间线上走一遍：数几个执行主体、停几站。

走一遍时间线的例子——业务说"提额审批"。沿时间线数站：客户提交 → 系统受理 → 模型算分 → 审批员核准 → 系统生效写额度。逐条对表：执行主体换了（系统→审批员→系统）；条件检查时点不同（受理查"还款正常、开关打开"，核准查"模型分≥阈值、不超上限"）；中间能停（受理后停在"待审"，客服可查）；撤法不同（受理拒了可重提，额度生效了要走调额回退）；产物不同（受理结论 / 审批结论 / 当前额度）。五条全中，拆成三张：受理提额申请（系统）／核准提额（审批员）／调额生效（系统）——每张恰好一个执行主体、一个检查时点、一种撤销方式。反例：受理提额申请 / 受理分期申请 / 受理提现申请，形状完全相同、只差申请类型——"同形状 × N"，并成一张卡，事件类型进 params。

口诀：一张卡＝一个执行主体＋一个检查时点＋一种撤销方式。 拆错不要紧，审核会复核。 纪律：一个执行主体一张卡，动作须唯一（审核按名称＋三要素——执行主体、作用目标、产物——组合查重）。

相连关系（对应图中编号）

存储表：动作表 actions.yaml（每条记录即一张"动作卡"）

与其他五张表同为 YAML 列表，一条记录＝一张动作卡。整卡在第一阶段填齐——正在描述动作的人最清楚它的参数、副作用、可逆性；空腔显式写 none（"无参数""不可逆"是知识，沉默空白是缺口）。六要素＝executor · target · product · params · side_effects · reversibility；骨架卡＝六要素暂空的记录（盘点时批量生成、随后补齐）。

样例（一张整卡：受理提额申请——参数化受理、系统隐式执行）：

- id: A-042
  zh: 受理提额申请
  en: accept-limit-increase
  category: 贷中管理
  facing: 对客
  executor: 额度策略系统
  target: N021                     # 提额申请（事件）
  product: 受理结论
  params: [事件类型, 渠道]
  side_effects: [P003]             # 受理状态：该属性 writer = A-042（互指）
  reversibility: 拒绝可重试
  implicit: true
  conditions: [F110, F112]         # F110 还款状态=Normal 才收单 · F112 提额总开关=ON；语句与出处在函数表
  refs: [N021, P003]
  feedback: 受理时效分布（提交→结论）；月度拒绝率按渠道
  grounding: null                  # 【二期】数据团队回填，如 { table: fact_limit_req, columns: [acpt_sts] }
  source: DOC-2026-031#p5
  status: draft
  asOf: '2026-08-06'
  by: trista

2.5 函数（F · 计算蓝 / 规则橙）

定义与判定

按 Palantir 的定义，函数是运行在本体之上的自定义逻辑单元（custom logic on the Ontology）：读取对象、属性与链接，返回一个结果——一个计算值，或一组"打算怎么改"的编辑意图；函数本身不落库，要改变本体，只能把编辑意图交给动作提交。本框架据此把函数定义为：由确定的输入得出确定的输出、且不改变世界的逻辑单元。

类比：函数≈一台只出结果、不改数据的计算器——喂进去值，出来一个值或一个"行 / 不行"；对数仓同学来说，它≈一段加工逻辑（视图、存储过程、模型脚本），知识库只登记它的进出口，不登记内部实现。"额度评估模型"是一个函数（类型），某日对某客户跑出的那次评分是它的一次执行。

由此推出函数的三个特征：

按输出的性质，函数分为两个类型（ftype），判定各有一问：

两类共享同一骨架——都有输入面（读什么值、查什么条件）和输出面（吐出什么值、给出什么裁决）——因此同住一张函数表，靠 ftype 区分。它们与动作的分界始终不变：函数只出数、只判定，不改变世界；改变世界的只有动作。

规则并入函数的依据：Palantir 没有独立的"规则"构件——条件式约束散落在几处：动作的提交准则（submission criteria）、动作参数校验（parameter validation）、自动化的触发条件（Automate conditions）、函数内部的判断逻辑。它们的共同形状都是"给定条件→给出裁决"，与计算型函数同为"输入→输出"，只是输出是布尔裁决而非数值。本框架把这些并为函数的规则型，用 host 记录 Palantir 会把它挂在哪：

与 Palantir 的对应（防误读）：Palantir 中属性取值有三条路径——管道产出（backing datasource，不经动作）、动作写回（Action writeback）、派生属性（运行时现算）；其"编辑函数"只产出编辑意图，必须经动作提交才落库。我们的 writer=F 对应的是管道产出与派生属性这两条路（模型分 T+1 批量落库），不是"函数绕过动作直接编辑本体"。

计算在数据里是隐形的：数仓里只有它的脚印（落库的输出字段），而这些字段与原始事实字段外观无异——所以必须由知识层补记"这一列是算出来的"（属性来源＝推断、writer 指回函数），防泄漏审查才有抓手。

细分类别

第一层：类型（ftype，第一阶段必填）

计算型的细分（subtype 六型，沿用 Palantir 的函数分类，数据应用治理阶段标注）：

规则型的细分（host 四类宿主）——选宿主判据："这条规则想在哪一刻被检查"：

refs——条件引用的其余构件：一条规则往往连着不止一个构件："还款状态非 Normal 不得提额"读的是属性 P011、拦的是受理动作 A-042。

• host 登记检查落点（A-042），refs 登记条件里引用的其余构件（P011），不含宿主；
• 有了 refs，"哪些规则引用了 DPD""改 P003 口径波及哪些规则"是一次结构化检索，不再靠全文搜字符串；
• 引用未建档的构件先立档再引用，禁止裸名字。

特例的写法（不设例外机制）：

• 一条规则对特定范围需要不同结论时，写成另一条独立规则，两条的适用范围都明确写进条件、使条件互斥——"非大额申请 24 小时内受理"与"大额申请（≥5000 万）48 小时内受理"是并列的两条，不是一条通则加一条例外；
• 写规则的人对条件边界负责：范围划清是登记合格的一部分；
• 两条规则条件范围重叠且结论不同＝冲突：按纪律登记冲突条目、交人裁决，不做默认优先级、不静默覆盖。

函数表是规则的唯一全集：宿主为单个动作的条件同样在此登记发号，动作表 conditions 字段按编号引用渲染——全局检索规则只需扫一处。

相连关系（对应图中编号）

存储表：函数表 functions.yaml

分期义务：计算型第一阶段只立壳（id＋名＋outputs——发现"算出来的字段"时顺手立一行，让属性的 writer 有合法指向），其余在数据应用治理阶段补齐；规则型第一阶段就要填齐（语句＋宿主）——写规则的人最清楚它约束谁。

样例（计算型壳与完整各一 ＋ 规则型四类宿主各一）：

# —— 计算型 · 壳（第一阶段）——
- { id: F013, zh: 催收评分, en: CollectionScore, ftype: 计算, outputs: [P021], status: draft }

# —— 计算型 · 完整（治理阶段）——
- id: F001
  zh: 额度评估模型
  en: LimitEvalModel
  ftype: 计算
  subtype: 模型集成
  inputs: [N009, P002]
  outputs: [P004]                  # P004 的 writer 指回 F001（互指）
  caliber: 输出建议额度与风险分层，T+1 批量
  versions:
    - { ver: v2, metrics: { ks: 0.41 }, asOf: '2026-08-01' }
  status: draft

# —— 规则型（第一阶段填齐；四类宿主各一）——
- { id: F110, en: no-increase-unless-normal, ftype: 规则,
    statement: 还款状态非 Normal 不得提额,
    host: A-042, gate: 状态门, refs: [P011] }   # P011=还款状态：条件读它，闸门在受理动作
- { id: F115, en: limit-cap-20m, ftype: 规则,
    statement: 授信额度不得超过 2000 万 IDR, host: P001 }   # 约束的就是宿主本身，refs 无
- { id: F130, en: no-bill-amount-in-model, ftype: 规则,
    statement: 账单金额不得作为因子进入逾期预测模型,
    host: F010, refs: [P030] }               # P030=账单金额：禁它进入宿主函数的输入

# 特例＝并列的独立规则，条件互斥（不设例外机制）
- { id: F120, en: accept-within-24h, ftype: 规则,
    statement: 非大额申请事件提交后 24 小时内必须给出受理结论, host: IF01 }
- { id: F121, en: large-withdraw-48h, ftype: 规则,
    statement: 大额提现申请（≥5000 万）提交后 48 小时内必须给出受理结论, host: IF01 }

2.6 接口（IF · 虚线框）

定义与判定

按 Palantir 的定义，接口（Interface）是"描述对象类型的形状与能力的本体类型"（"an Ontology type that describes the shape of an object type and its capabilities"）。它是抽象的：不背数据集、不能直接实例化——对象类型是具体的，接口只声明"实现（implement）它的对象类型必须具备什么形状"；一个对象类型可以实现多个接口。面向接口写的规则、动作和工作流，对所有实现者一次生效——这就是官方所说的多态（polymorphism）。

类比：接口≈体检标准表，对象类型≈体检报告——标准表规定"必须查这几项"，数值永远在报告上；也≈数仓里一份只有列名、没有数据的模板表结构。Palantir 官方例子：Facility（设施）接口声明"设施名称、位置"两条属性；机场、工厂、维修机库三个对象类型都实现它，各自再带专有属性；工作流面向 Facility 写一次就能处理三者，日后新增第四种设施只要实现该接口，现有工作流零改动兼容。对应到我们：可受理接口声明"提交时间、受理状态、受理动作"，提额申请、分期申请、提现申请都实现它。

由此推出接口的三个特征：

在本框架中，接口用作同形对象的归并机制，判定分三步：

• 何时立：三个以上对象类型呈现相同的状态机或能力集，且同一句规则要抄第二遍——没有规则可挂的接口不要建，不预先设计；
• 谁来立：业务输入时不填，它是后续归并阶段的审核产物；LLM 只提示"此处或可归并接口"，不创建；
• 怎么命名：动词是动作，"可＋动词"是该动作的作用域（接口）——冲抵是动作，可冲抵是接口；
• 怎么归并：优先合并属性，绑定是折中——归并时先把各实现者同口径的属性合成一条共享属性（一个 P 号、多个宿主，见 2.2 共享池），接口的形状直接引用该 P 号；暂时合不了的（口径微差、写入方不同）才在实现者上用 bindings 绑到各自的 P 号，并登缺口待合并。

名称辨析：本书的"接口"专指 Palantir Ontology 的 Interface（对象形状的抽象类型），与 API / SDK 接口无关——后者在本书一律写作"API""SDK 字段"。

细分类别（已知与候选）

相连关系（对应图中编号）

存储表：接口表 interfaces.yaml

样例（可受理：一个槽位已有共享属性、一个槽位靠绑定）：

- id: IF01
  zh: 可受理
  en: Acceptable
  definition: 客户发起的申请类事件都经同一套三态受理（待受理 / 已受理 / 已拒绝）
  shape:
    properties:
      - { slot: 受理状态, ref: P003, state_axis: true }   # P003 已是共享属性（多宿主），实现者无需绑定
      - { slot: 提交时间, ref: null }                       # 尚无共享属性：各实现者 bindings 指到自己的 P 号，登缺口待合并
    actions: [A-042]
  implementers:
    - { id: N021, bindings: { 提交时间: P0xx }, verify: judged }
    - { id: N022, bindings: { 提交时间: P0yy }, verify: judged }
    - { id: N023, bindings: { 提交时间: P0zz }, verify: candidate }
  note: 客户行为的准入规则挂受理动作或本接口
  source: 归并审核 2026-xx-xx
  status: draft

接口进不了 L1 的常见原因是接地不齐而非接口本身：三个实现者里有一个的"提交时间"没有 verified 的词典行，整条接口规则就不能编译（6.3.5 不允许一族里一半能判一半不能判）。因此接口归并的工作清单，实际上等于"把这一族的共享属性接齐"。

第三章 · 数据字段匹配（第二阶段）

第一阶段产出的知识是"纸面"的：定义清楚、结构完整，但尚未与真实数据钉在一起。第二阶段由数据团队完成四类接地——即前文各表中标 【二期】 的字段。

3.1 四类接地一览

3.2 C 对照词典 crosswalk.yaml

定义与判定

C 对照词典是属性的接地登记：一个词条＝一条属性在三个世界里的名字对齐记录——知识侧的业务名（"受理状态"）、产品 / SDK 侧的字段名（acceptStatus）、数仓侧的库.表.列（fact_limit_req.acpt_sts）——并带一个"经数据核实"的进度章（verify）。它是辅助登记，不是构件（删掉它，对世界的描述不会少一块，只是知识暂时验证不了）。

用数仓的话说，它是属性语义层与字段物理层之间的桥接表：attributes.yaml 回答"这个属性是什么"（口径、来源、敏感……与数仓无关），crosswalk 回答"这个属性在哪"——一条属性可对多列（实时 / 日切 / 快照各一列），一列也可服务多条属性，典型的多对多，所以拆成独立的中间表：一行一个对应关系，各带样例与核实进度。修改、查找、分工都落在这张表上——数仓改名只动它，机筛提名只往它追加行，数据角色只有它的写权限。对象、链接、动作的接地是"一次定、少变"的结构事实，嵌在自身表的 grounding 字段里即可，不经此表。

类比：在 Palantir 中，对象类型背后有 backing datasource，每条属性都映射到该数据集的一列——属性与列的映射是本体接地的基本单位。C 词典就是这张"属性 → 列"映射表，只多了两样：中间夹一层产品 / SDK 名（三方对齐，因为行方文档与数仓命名不同），以及一个核实进度。对数仓同学它≈数据字典（data dictionary）里"业务名 ↔ 物理列"那一页，附加脱敏样例作证据。

由此推出词典的三个特征：

判定——什么进词典、什么不进：

• 属性的接地进词典（ref 只指 P 号）；对象、链接、动作的接地各在自己登记表的 grounding 字段内，不经此表（3.1）；
• 一条属性可有多个词条：同一口径落在多张表多列时，各立一行；
• 空词典＝该属性暂不可用数据验证——不是错误，是缺口；
• 词典第一阶段建空表，第二阶段由数据团队逐行填入。

为什么要这本词典，而不直接把表名写进知识里：

相连关系（对应图中编号）

字段词典

verify 四态逐个说（只许数据角色推进）：

样例（一个已收录词条 ＋ 一个刚提名词条）

- { id: C011, ref: P003, sdk_field: acceptStatus,
    dw_column: fact_limit_req.acpt_sts, sample: "P / A / R",
    verify: verified, asOf: '2026-08-07', by: 数据同学 }

- { id: C012, ref: P002, sdk_field: behaviorScore,
    dw_column: cust_info.cscore, sample: none,
    verify: candidate }                     # 机筛刚提名，待人工确认

3.3 verify 核实状态机（全体接地记录通用）

所有接地记录——对象与链接的 grounding、词典行——共用同一套核实进度，且只许数据角色推进：

candidate（机筛提名）→ judged（人工确认）→ sampled（样例核对，词典专有）→ verified（三方一致）

它与知识条目自身的 status（draft/verified）相互独立：定义核实了不等于接地核实了，两个进度条各自推进——一个对象可以定义已 verified 而 grounding 还是 candidate，反之亦然。

3.4 DOC 文档登记 registry.yaml

出处锚的登记处（第一阶段起即使用）。文档上传即登记：DOC 编号、sha256 去重、上传人、关联切片；解析后切成带锚点的段落（如 DOC-2026-031#p5），全库构件的 source 指向这些锚——每条知识都能一键回到原文。

- { id: DOC-2026-031, title: 额度调整管理办法, sha256: 9f2a…,
    uploader: leo, date: '2026-08-07', slices: [额度成长], status: 已抽取 }

第四章 · 知识图谱

4.1 建成后长什么样

定义与判定

知识图谱是六张登记表的可视化编译产物：节点＝对象、属性、动作、函数、接口的登记行，边＝链接以及各表里互指的字段（宿主、写入方、target、host……）。它不另存数据——从登记表实时编译，改表即改图；点击任何节点应能回到它的登记行、出处锚与接地状态。

类比：登记表≈账本，图谱≈按账本自动画出的地图；Palantir 里对应的是 Ontology Manager 的对象类型关系图与 Vertex 的图探索视图——同样是从本体定义现算出来的，不是另一份数据。

由此推出图谱的三个特征：

判定："这张图上的东西能否在某张登记表里找到那一行？"找不到的不该出现在图上；反过来，登记表里已互指的关系（属性 writer 指向动作、动作 side_effects 指向属性）在图上只画一条边。

样例：提额业务线

下图是"提额"业务线建成后的样例（节点编号与第二章样例一致）：

读图路径（按颜色）：

4.2 建造标准

颜色（六色定案，全平台一致）：

同一构件按类型分色：计算型与规则型同属函数，但在图上必须一眼可辨"这是算值的"还是"这是划界的"，故保留两色。

线样式：

图谱约束（自动校验，违反即数据有错）：

1. 灰实线只出现在 紫↔紫（链接两端必须是对象）；粉实线只出现在 粉→紫（属性必有宿主对象）；
2. 青节点的边只有 作用于 / 写入 / 产出 三种；蓝节点的边只有 读 / 写产物 两种；青蓝之间无直接边（分工经属性中转，2.4 ❺）；
3. 橙节点必有一条挂载边，不允许悬空；挂载边终点只能是 青 / 粉 / 蓝 / 接口框；
4. 灰虚线只出现在 紫⇢接口框；接口框本身不带粉线（接口不拥有属性值）。

第五章 · 执行纪律（供 LLM 遵照）

本章目的：LLM 处理知识分类时，遵照本章的判定流程与纪律，对输入的全部业务知识做一轮完整分类，归入第一至四章定义的架构。本章可独立作为系统提示词使用。

5.0 总纲

对象是骨架，属性是状态，动作和函数推动状态变化，规则给变化划界，接口把同形归并。任何一条业务知识拆开后只会是这六类构件之一（规则是函数的一个类型）。判定的目标不是贴标签，而是逼出这条知识缺失的部分（宿主、执行者、出处、条件边界）。你只做整理和追问，不做裁决、不编造出处。

5.1 六问判定流（按顺序，命中即停）

P1 带条件吗？（如果 / 当 / 超过 / 不得 / 必须 / 除非）
   → 是规则：登函数表，ftype=规则。追问：
     a. 宿主是谁？（约束哪个动作/属性/函数/接口）——答不出=知识未完成，禁止挂未建档的名字
     b. 条件里还引用了哪些构件？→ 登 refs（不含宿主）；引用未建档的先立档
     c. 它是不是某条已有规则的特例？→ 不设例外机制：写成独立条目，把适用范围写进条件里，
        并回改被特化的那条，使两条条件互斥；范围重叠而结论不同=冲突，登记不裁决

P2 说的是一个操作吗？执行主体是谁？
   → 机构操作者（审批/调额/催收/冻结/核销）= 动作。按六要素建卡。
     ⚠️ category 填职能域——执行主体隶属的业务职能（授信审批 / 贷中管理 / 交易管控 / 催收 / 账务 / 客服 …，开放清单：
        找不到合适的可新增，按执行主体归属命名、先查同义）；对客/对内选标 facing；系统自动执行标 implicit
     ⚠️ 与函数的分界：只出数、只判定、不改状态的不是动作（转 P1/P3）；真正改状态的才是动作
   → 客户（支用/还款/申请）= 对象（事件），转 P5 建档。
     ⚠️ 客户行为的准入校验是规则，宿主=机构对应的受理动作（参数化；系统自动执行也建档，标隐式）
   → 大词（审批/重组/开户）先拆：模型算分=计算型函数、阈值裁决=规则型函数、核准落地=动作；
     客户申请=事件对象、新造之物=产物对象

P3 它是算出来的吗？（评分 / 分群 / 比率 / 窗口聚合 / 模型输出）
   → 是函数：登函数表，ftype=计算。只立壳（id+名+outputs）。追问：产物落到哪个字段？
     ⚠️ 函数输出落库后是属性：来源=推断，写入方指回函数——防泄漏的字段级根源
     ⚠️ KS/精度/提前量是函数版本元数据，不单独成条
     ⚠️ 函数只出数不做主：见到"模型直接决定"，追问阈值（规则）与生效动作在哪

P4 它描述某个东西的状态或口径吗？
   → 是属性。先答宿主（答不出先回 P5 立对象），再打五轴：
     来源（事实|推断|构造）/ 结构（标量|枚举|结构组|集合）/
     写入方（客户提交|A号|F号|时间驱动|null）/ 归属（专有|共享）/ 敏感（明文|脱敏|禁展示）
     ⚠️ 结构=枚举 → 取值逐个登进取值字典；=结构组 → 整组登记，禁止逐位散登
     ⚠️ 建议值与核定值是两个属性：模型吐的（推断/写入方=F）≠ 动作核定的（事实/写入方=A）
     ⚠️ 快照日期（ds / rpt_date 等）是数据机制元数据，不是业务属性
     ⚠️ 属性只登当前值：一段会变化的历史（额度调整、状态变更）不塞进属性，立事件对象（product_of=写它的动作）

P5 它有自己的身份标识吗？（有主键 / 编号，能逐个指认；有生命周期）
   → 是对象。定二分（实体|事件），记身份标识；若是某个动作的产物（查征信→征信快照、重组→新借据），填 product_of=该动作号。
     ⚠️ 标识字段揭示对象：出现新标识符=存在新对象（人的标识与账户的标识是两个对象）
     ⚠️ 别被表结构骗：对象可能藏在别的表的某一列里

P6 它连接两个对象吗？
   → 是链接。记动词、方向、基数。kind 不填（默认 structural）。
     ⚠️ 两端必须都是已建档对象；属性/动作/函数不能当端点

5.2 动作拆并纪律

大词先走时间线：数几个执行主体、停几站，逐条对表——

口诀：一张卡＝一个执行主体＋一个检查时点＋一种撤销方式。动作须唯一：一个执行主体一张卡（按名称＋执行主体、作用目标、产物查重）。拆错不要紧，审核复核。

5.3 填写纪律

1. 三态：知道→填值；确认无→填 none（合法知识）；不知道→留白（缺口）。禁止为凑格式编造。
2. 动作卡整卡填齐：六要素＋conditions 全填，空腔显式 none；只有 grounding 留给第二阶段。
3. 函数分型填写：计算型只立壳（id＋名＋outputs），六型、inputs、versions 不追问；规则型第一阶段填齐（语句＋宿主），条件边界写进语句。
4. kind 与接口不生产：链接不填 kind；永远不主动创建接口——发现同一条规则要写第二遍时，仅提示"此处或可归并接口，交审核"。
5. 每条知识必须锚出处：能命中原文→ DOC-ID#pN；口述→记录原话并标手填。无出处只能存草稿。
6. 引用用 ID：宿主、写入方、两端一律填已建档构件 ID；找不到→先立档（对象或骨架卡）再引用，禁止裸名字。
7. 发现矛盾不改写：与已有知识冲突时引导登记冲突条目，禁止静默覆盖任何一方。规则条件范围重叠且结论不同，同样按冲突登记，不做默认裁决。
8. 【二期】【三期】字段不填：grounding、crosswalk 留空（六张表一致），那是数据团队的职责；expr、allowed_states、when / transitions 等可判定字段也不填——它们只补在 verified 条目上，由 use case 小组按第六章完成，LLM 分类阶段不写。

5.4 输出模板（七节，对应存储路由）

## 1. 对象表（按实体 / 事件分节）
| 对象 | en | type | 产物于（动作号） | 定义 | 身份标识 | 出处 |
## 2. 属性表
| 属性 | en | 宿主 | 口径 | 来源 | 结构 | 写入方 | 归属 | 敏感 | 出处 |
## 3. 关系表
| 链接 | en | 源对象 → 目标对象 | 基数 | 出处 |
## 4. 动作表（整卡：六要素＋条件；含受理模式与隐式动作）
| 动作 | en | 职能域 | 对客/对内 | 隐式 | 执行者 | 作用对象 | 产物 | 参数 | 副作用 | 可逆性 | 出处 |
  每个动作附条件行：| 门类 | 条件语句 | 出处 |
  （每行入函数表规则型：host=本动作、gate=门类；动作表 conditions 只引用其编号）
## 5. 函数表 · 计算型（壳）
| 函数 | en | 产物落到哪个字段/属性 | 出处 |
## 6. 函数表 · 规则型
| 规则 | en 短名 | 条件语句（含完整适用范围） | 宿主（已建档构件 ID） | 门类（宿主为动作时） | 引用构件（refs） | 出处 |
## 7. 接口表——不填（后续归并阶段归并）

5.5 易混边界速查（13 条）

5.6 完整性校验（提交前逐条过）

• 每个属性指认了宿主并完成五轴（写入方可为 null，但须知这是缺口）
• 每条规则声明了宿主且宿主是已建档 ID；条件引用的其余构件已登 refs；条件语句含完整适用范围，与同宿主其他规则不重叠（重叠且结论不同→登记冲突）
• 每个动作六要素齐全，空腔显式 none；conditions 每条是已建档 F 号，该规则带出处与门类
• 动作 target 只含真被编辑的对象：每个 target 对象在 product 或 side_effects 中有对应写入；落点/上下文对象走链接不进 target（2026-08-20 增补）
• 每个推断字段标了来源＝推断并指向产出函数（壳亦可）
• 位段编码按结构组整组登记；枚举取值进取值字典
• 敏感属性已标档位
• 每条知识锚定出处
• 属性只登当前值；会变化的历史已立事件对象并填 product_of
• 图谱约束：灰边只连对象；青只有作用于/写入/产出、蓝只有读/写产物、青蓝无直接边；橙必挂载不悬空；接口框无粉线

第六章 · 可判定与编译（第三阶段）

本章目的：前两期把知识登记清楚并钉到数据上，产出 L2（可引用）；本章定义第三期——把已核实的知识补成机器可执行的形式、过闸门、编译成生产只读的产物，产出 L1（可判定）。本章同时规定动作执行的契约（6.8）与数据写回的规范（6.9）。 本章的边界：本章只定义"知识如何变成可执行、产物长什么样、生产怎么依赖它"；判定服务与调度服务的工程实现、各业务系统的接入代码不在本书内，以 6.7 / 6.8 的契约为接口与科技对接。 参照：Palantir 的 Action 定义（Parameters · Submission criteria · Rules · Side effects）、资源状态（experimental / active / deprecated）、Ontology 元数据 → OSDK 代码生成、AIP Agent 工具配置。本章把这几样机制落成登记表字段与产物；与 Palantir 的差异在 6.7 说明。

6.1 三级状态与三层产出

定义与判定

每条登记条目的 status 从两态扩为三态（退役另计）：

active 是一个承诺，不是一个计算结果。 机器可以算出"这条已满足 L1 全部条件"（6.4），但把它切成 active 意味着向生产承诺：编号与名称冻结、口径不再静默变更、下游可以 pin 版本依赖它。承诺由人做，所以 active 只能由本体管理员切换；平台把"具备条件"作为派生标记（level = L1-ready）展示，不替人切。

由此推出 active 条目的三条保护（对应 Palantir 对 active 资源的保护：不能删除、API name 不能改）：

三层产出与谁读什么

① 知识域（人写、审批合入）      登记表 YAML · 唯一事实源 · 三态 status
        │ 合入 master 触发
② 编译域（CI 自动、人不介入）   只读 active 条目 → 6.4 闸门 → 6.5 产物（带版本号 + 校验和）
        │ 按 pin 住的版本号分发
③ 生产域（只读产物，永不反写登记表）
        评分管线 · 数仓视图 · 判定/调度服务 · Agent 工具 · 速查卡
        │ 发现口径错 → 回到 ①（改登记册，不改代码）

生产读的是产物，不是登记表；登记表可以每天改，产物按版本发布。这条分离是三期的核心纪律。

6.2 条件树规范（受限表达式）

定义与判定

条件树是本书规定的唯一可判定表达形态：一棵由 all / any / none 嵌套的结构化条件树，叶子只做"已接地属性 / 动作参数 / 常量"之间的比较。它不是代码、不是自由表达式字符串——沿用 Palantir submission criteria 的形态（条件按 all / any / none 组合，每个根条件配失败提示），原因有三：机器校验"变量是否接地"只需查字段不必解析语法；同一棵树可确定性地翻译成 SQL、JSON、Python 等目标方言；业务同事能在表单里逐条填，不必写代码。

规则的人话语句 statement 仍是正本；expr 是它的可执行翻译。两者不一致时以 statement 为准并登记冲突（X），不许改 statement 去迁就 expr。

结构

expr:
  all:                                   # all | any | none，可嵌套
    - { var: P014, op: ">=", value: 30 }
    - { var: P014, op: "<=", value: 90 }
    - any:
        - { var: P063, op: "=", value: true }
        - { var: P063, op: "is_null" }
fail_msg: 账户逾期天数须在 30–90 天内才可进入逾期重组       # 每个根条件必填，人话

叶子字段：

不允许：自定义函数、跨对象遍历（条件只看宿主对象及其属性；跨对象条件先立计算型函数把值落成属性）、任何有副作用的操作、引用实例数据以外的上下文（时间用 days_since 相对表达，不写绝对日期）。

三态填写沿用 1.6：expr 留白＝尚未翻译（缺口，停留 L2）；expr: none＝确认此规则不可机器判定（如"催收话术不得含威胁性措辞"），标 manual: true，编译时进 card.md 不进 ontology.json。

样例（L089 逾期重组窗口，宿主 A-10）

- id: L089
  statement: 逾期分支须账户 OVERDUE_DAYS ∈ [30, 90] 双闭区间才展示/受理逾期重组入口与预付；OVERDUE_DAYS 缺失→fail-closed
  host: A-10
  refs: P014·P063
  expr:
    all:
      - { var: P014, op: "not_null" }            # 缺失即 fail-closed：not_null 放第一条
      - { var: P014, op: "between", value: [30, 90] }
  fail_msg: 逾期天数不在 30–90 天窗口内（或缺失），不可受理逾期重组
  severity: block
  status: active

编译器由 expr 自动抽取 expr_vars: [P014]，不手填；refs 里有而 expr 未引用的属性（P063）提示"条件未覆盖"，作 warn。

6.3 各表可判定字段

本节字段全部标 【三期】；一期、二期字段不动。

6.3.1 规则型函数（rules.yaml）

6.3.2 动作（actions.yaml）

样例（A-48 上传重组名单与方案，三期字段；一期字段略）：

- id: A-48
  zh: 上传重组名单与方案
  target: N050·N051·N052·N005
  side_effects: P143·P138·P140·P141·P139
  conditions: L286
  reversible: 可逆(重新上传覆盖)
  # —— 三期 ——
  allowed_states:
    - { axis: P007, values: [O] }                      # 账户账单状态 = 已逾期
    - { axis: P011, values: [NONE, LOCK_PART] }        # 冻结态：未锁定或部分冻结
  params_schema:
    - { name: 名单账户, type: object_set, ref: N002, required: true }
    - { name: 本金减免比例, type: number, range: [0, 0.5], required: true }
    - { name: 可选期数, type: enum, values: [3, 6, 12], required: true }
    - { name: prepayRequired, type: boolean, default: false }
    - { name: prepayAmount, type: number, range: [0, null] }
  writes:
    - { op: create, target: N050, from: param:名单账户 }
    - { op: modify, target: P143, from: const:true }
    - { op: modify, target: P139, from: const:UNACTIVE_PLAN }
  dispatch:
    system: 重组配置后台
    entry: file_manual                                 # 现阶段只能人工上传：产出校验过的文件 + 执行记录号
    payload_map: { 名单账户: acct_no, 本金减免比例: principal_waive_pct, 可选期数: tenor_options }
    human_gate: required
    ack: 上传成功回执(人工登记)
    callback: A-10 受理结果回流(客户确认/拒绝/超时)
  metrics:
    - { name: 名单确认率, definition: 客户确认方案户数 / 名单户数, window: 14d, columns: [C0xx], direction: higher_better }
    - { name: 确认后30天再逾期率, definition: 确认后 30 天内再次逾期户数 / 确认户数, window: 30d, columns: [C0xx], direction: lower_better }
    - { name: 减免让利额 vs 实际回收, definition: 累计减免金额与确认后实际回收金额, window: 60d, columns: [C0xx], direction: higher_better }
  status: verified                                     # 待 metrics 的 columns 接地后可切 active

6.3.3 状态轴（attributes.yaml 的三期字段）

本书不新建状态表：状态就是某个枚举型属性的取值，宿主、取值字典、写入方都已经在属性上，状态机字段直接挂在该属性上。

判定纪律：每个取值至少出现在一条迁移的 from 或 to 中（否则是孤儿状态）；不可逆的 irreversible 必须显式标；动作发起了但对方尚未响应的那段时间必须是一个登记的取值（"名单已上传·未确认"这类中间态不许隐含在别的状态里——这是运营最该跟进的窗口）。

样例（P007 账户账单状态，示意值，登记时以实际编号为准）：

- id: P007
  zh: 账户账单状态
  host: N002
  structure: 枚举
  values: [{value: U, label: 未出账}, {value: N, label: 已出账}, {value: F, label: 已还清}, {value: O, label: 已逾期}]
  # —— 三期 ——
  state_axis: true
  when: none                                           # 事实型：由账务系统写入，不推断
  transitions:
    - { from: U, to: N, via: N045 }                    # 账单出票事件
    - { from: N, to: F, via: A-63 }                    # 还款冲抵
    - { from: N, to: O, via: "time: days_since(P0xx 到期日) >= 1 且未还清" }
    - { from: O, to: F, via: A-63 }
    - { from: F, to: U, via: "time: 下一账期开始" }

6.3.4 对象、链接、计算型函数

这三类没有自己的可判定字段，但有进 L1 的前提：

6.3.5 接口（interfaces.yaml）

接口没有自己的可判定字段，但挂在接口上的东西要在编译时展开到每个实现者，因此有三条规定：

现状说明：登记表目前尚无 interfaces.yaml（1.5：一期不填、归并阶段产生），缺口表中的"接口候选"仍为 open。接口的三期规定在归并完成前不产生编译产物，但条件树的写法从现在起就按本节执行，避免归并后返工。

6.4 编译闸门（条文编号供合规检查引用）

编译只读 active 条目；下列闸门任一不过，整批挡回，不出产物。编号 6.4.x 与合规检查页的 clause 一一对应。

6.5 编译产物与 manifest

产物清单

每件产物都是从 active 条目的特定字段确定性生成——同一份登记表编译两次得到字节相同的产物；产物里没有任何手写内容（禁止手改，改了下次编译即被覆盖）。

产物落在 dist/ontology/v<major>.<minor>.<patch>/，一版一目录，旧版不删。

与 Palantir 的对应

ontology.json ≈ Ontology Full Metadata（唯一源的机器可读版）；agent_tools.json ≈ AIP Agent 的工具配置（Object query 的对象 / 属性范围、Action 工具的确认开关）；manifest 版本 ≈ OSDK 包版本。states.sql 与 dispatch_map.json 是 Palantir 没有的——因为它有常驻运行层，状态与去向在运行时算；我们是只读产物，必须提前编译（6.7）。

6.6 版本与发布纪律

纪律：

1. 发布＝合入 master 触发 CI 编译；cloud-migration 等工作分支只做草稿与预览编译（产物标 -preview，生产不得使用）。
2. 生产按 manifest 里的版本号 pin，不拉 latest；每条信号、每条写回都带 ontology_version（6.8 / 6.9）。
3. 回滚＝把 pin 指回旧版本号，不回退登记表；登记表只前进。
4. major 变更须在发布说明里列出受影响的消费端与迁移指引；6.4.8 闸门强制。

6.7 运行层演进：A 编译产物 → B 判定与调度服务 → C 全量运行层

Palantir 的 Ontology 是一个常驻运行层：应用的读走它（对象由 backing dataset 支撑）、写走它（Action 提交时现场评估 submission criteria 并写回）、变化被它感知（Automate 监控属性变化触发效果）。因此 Palantir 不登记状态迁移——迁移在运行中"涌现"。

我们的知识层与 Palantir 同构，运行方式分三档演进；三档读的是同一份登记表与同一套产物，区别只在谁来执行判定：

状态迁移在三档里都显式登记（6.3.3）。A 档把迁移表编译成 SQL 与 tools_by_state；B 档在线读同一张表现场判；C 档也不例外——涌现式的代价是中间态会被整个漏掉（"名单已上传·未确认"曾经就是这样漏的），显式闭世界才能做孤儿状态闸门与非法迁移探测。Palantir 自己也把"状态=X 才允许"写在每个 Action 的 submission criteria 里，只是散在各动作上；本书把它收拢成状态轴上的一张迁移表，再编译回各动作的 allowed_states。

B 档的判定服务不是 C 档的替代，而是它的内核：先接收调用方递来的值做判定，等实时数据通道与写回机制建好，再让它自己取数、自己执行编辑，即升级为 C 档。

6.8 动作执行契约

B 档下每个受管动作的完整生命周期，以及各环节 Ontology 提供什么、要求什么：

① 意图     调用方（策略 / 模型 / 人）递交：动作号 · 参数 · 目标户清单（含各户状态相关属性的当前值）· 调用方标识
② 判状态   按状态轴 when 算每户当前取值（事实型状态直接取递来的值）
③ 判合法   allowed_states → precondition（含 conditions 各规则的 expr）→ params_schema；任一不过 = deny + fail_msg
④ 定去向   按 dispatch 得到目标系统、入口、载荷映射
⑤ 人工闸门 human_gate=required 的动作：审批人看到"合法清单 + 被拦清单及原因"，批准后才进 ⑥
⑥ 发信号   向目标系统发指令（api / webhook / 生成待上传文件）；entry=file_manual 时产出校验过的文件 + 执行记录号，由人上传
⑦ 回执     目标系统 ack（成功 / 失败 + 原因）
⑧ 结果     目标系统 / 客户侧结果按 callback 回流；按 metrics 口径观测

信号与记录的字段

纪律

1. fail-closed：判定服务不可用、产物版本缺失、任一必需属性值缺失时不发——宁可延迟，不错发。
2. 不可逆动作强制人工闸门（6.3.2 dispatch.human_gate=required）；Agent 发起的写操作按 agent_tools.json 的确认要求执行，与 Palantir Action 工具的"执行前需用户确认"同义。
3. 执行记录是本体里的事件对象（product_of＝该动作），有自己的状态轴：已提交 → 已批准 → 已发送 → 已回执 → 已观测（失败 / 拒绝为分支终态）。所有动作的中间态都落在执行记录上，不再散落。
4. 影子模式：一个 use case 首次接入时，判定与路由照做、信号只记不发，与现行流程比对被拦清单，口径核对无误后再切真发。
5. 每条判定（allow 与 deny）都写审计日志：instance_id、户、命中规则、fail_msg、版本号。

6.9 写回规范

定义与判定

写回是本体产物落入数据世界的过程：执行记录、判定结果、策略取值、执行回执、观测指标写入本体自有的写回库，再物化进数仓供分析与下一轮使用——对应 Palantir 的 Action 编辑进 writeback dataset 并物化回数据底座。

一条线必须划清：写回 ≠ 反写业务系统的库。写回的目标只有本体自己拥有的存储；评分、审批、触达、账务系统的表，本体一行不碰。这样"业务系统不改造"与"数据可写回"同时成立。

三条原则

1. 先登记，后写回：任何写回的字段都必须先是登记表里的构件——执行记录、拦截记录、名单、回执结果各立对象或属性，writer 指回执行它的动作 / 函数，origin 标清事实还是推断，带出处。没登记的东西不许写回；这是本体写回与"随便落一张表"的本质区别，也是回流数据能进下一轮分析而不污染模型的保证。
2. 两层落点：本体写回库（服务实时写，含全部中间态）→ 每日物化到数仓的本体专属命名空间（如 ontology_wb.*），数仓侧只读。
3. 每条写回带 ontology_version 与 instance_id，任何一条回流数据都能回答"按哪一版口径、哪次动作产生的"。

四类写回场景

执行记录对象模板

- id: N0xx                                   # 编号由发号器发放
  zh: 动作执行记录
  en: ActionInstance
  type: 事件
  product_of: A-48·A-39·…                     # 凡走 6.8 契约的动作都产它
  identity: instance_id
  definition: 一次受管动作的提交、判定、发送与回执的完整记录
  grounding: { dw_table: ontology_wb.action_instance, identity_col: instance_id, verify: judged }
# 其属性：执行状态（状态轴，取值 已提交/已批准/已发送/已回执/已观测/失败/拒绝）、动作号、参数快照、
# 目标户数、被拦户数、ontology_version、approved_by、sent_at、ack_at —— 各自 writer 指回调度 / 审批 / 回执动作

6.10 use case 辅助登记（usecases.yaml）

use case 是推动条目走完三级的组织单位（1.4）：一个真实决策 + 它闭环所需的构件清单 + Agent 在链路上的查阅点。它是辅助登记（删掉它，对世界的描述不会少一块），不是第七类构件；结构沿用切片 / 业务段的"成员清单 + 叙事"，多四个字段。

6.11 第三阶段填写纪律与完整性校验

填写纪律：

1. 可判定字段只补在 verified 条目上；draft 条目先走一期二期。
2. 人话正本优先：expr 与 statement、writes 与 side_effects、metrics 与 feedback 不一致时，以人话为准登冲突，不改人话迁就机器字段。
3. 变量必须接地：写 expr / when / metrics 之前先确认引用属性的词典行已 verified；未接地的登缺口，不硬写。
4. 中间态必须登记：写 transitions 时逐条问"动作发起了但对方没响应，这段时间它算什么"。
5. 不可逆必须显式：irreversible 与 human_gate=required 成对出现。
6. 切 active 是管理员的动作：机器报"具备条件"，人切；切换记入 audit（谁、何时、依据哪次闸门报告）。

完整性校验（切 active 前逐条过）：

• 规则：expr 非空或 none+manual；fail_msg 非空；expr_vars 全部接地；severity 已定
• 动作：allowed_states 的 axis 是状态轴、values 在字典内；params_schema 每个参数有 type 与范围来源；writes 与 side_effects / product 互指；dispatch 齐且不可逆动作 human_gate=required；metrics 非空或 none（登 G）
• 状态轴：when 有 default（推断型）；transitions 无孤儿取值、irreversible 显式、终态标记；中间态已登
• 对象 / 链接 / 计算型函数：grounding verified；函数版本 pin
• 涉及本条目的 X 冲突全部 resolved；本条目 source 锚可命中
• 与上一版比对：若为破坏性变更，版本号 major 递增并附迁移指引

附录 · 修订记录

约定：每次向线上推送新版说明书，在下表顶部加一行——版本号、日期、是否已上线、这一版改了什么（写给读者看的一段话，不是提交信息）。本表是版本记录的正本；docs/handbook-CHANGELOG.md 只指向这里。版本号规则：major＝架构性变化（分期、新章节、构件分类），minor＝条文口径增补或裁决收口，-draft 后缀＝评审中、未合入 master。