跳转至

本页内容同步自 Server/schema/PROTOCOL.md,请在该源文件修改后运行 python Tools/gen_docs.py。

UAL 三层数据格式协议 v2.0

本文档是消费者之间的唯一契约。C++ 写入侧(UE 插件)、Python 读取侧(MCP Server / CLI)与 CI 门禁都必须遵守。

0. 角色分工(铁律)

层 格式 消费者 禁止事项
L1 存储 DuckDB .ual/index.duckdb ual-cli、ual_mcp 禁止把整库 JSON 导出给 LLM
L2 精读 YAML *.spec.yaml ual_inspect_asset、Git Diff、Code Review 禁止用于批量候选列表
L3 批量 TOON ual_search_assets 等 3 个批量工具 禁止逐条输出完整 YAML

1. L1:DuckDB

DDL 见 init.sql。要点:

  • fingerprint_vec FLOAT[16] 固定 16 维,缺失值写 NULL(不写全零,全零会导致余弦相似度退化)。
  • content_hash 只用于增量变更检测,不用于查重。.uasset 重存会改变二进制哈希但语义未变。
  • interface_spec / domain_spec 是 MAP(VARCHAR,VARCHAR),数值类型被擦除。约定:标量写纯文本,向量写 [a,b,c],列表/对象写 JSON 字符串。读取方按 key 契约解析。
  • FTS 索引是快照,INSERT 不自动维护;每次批量灌库后必须执行 rebuild_fts.sql。
  • array_cosine_similarity 需要 DuckDB ≥ 1.1;已在 2.0.0 实测通过。

C++ → Python 的 JSONL 交换契约

UE 侧 UALJsonlIndexSink 写入 .ual/staging/*.jsonl,一行一个 JSON 对象。键名严格如下(snake_case,缺字段按默认值补齐):

{
  "asset_path": "/Game/Characters/Knight/Anim/AM_Knight_HeavySlash_02",
  "logical_id": "AnimMontage:AM_Knight_HeavySlash_02",
  "asset_class": "AnimMontage",
  "parent_class": "AnimSequenceBase",
  "taxonomy": ["Asset", "Animation", "Montage"],
  "tokens": "knight heavy slash combat",
  "content_hash": "sha1:...",
  "duration": 1.15,
  "bounds_size": [0.0, 0.0, 0.0],
  "skeleton_path": "/Game/Characters/Knight/SK_Knight",
  "dominant_limb": "hand_r",
  "fingerprint_vec": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
  "interface_spec": {"skeleton": "/Game/Characters/Knight/SK_Knight"},
  "domain_spec": {"duration": "1.15", "phases": "{\"windup\":[0.0,0.35]}"},
  "yaml_cache": "# UEAssetLens AssetSpec v2.0 ...",
  "edges": [{"target_path": "/Game/VFX/NS_Slash_Heavy", "edge_type": "CO_OCCURS", "weight": 0.88}]
}

注意区分两层:staging JSONL 是交换格式(16 个键,不含 updated_at),DuckDB assets 表才是持久化结构。updated_at 由灌库侧的 DEFAULT CURRENT_TIMESTAMP 填充,C++ 侧不写入,以保证 YAML/TOON 输出不含时间戳、Git Diff 稳定。

ual-cli build --from-jsonl <path> 负责 upsert(ON CONFLICT ... DO UPDATE)、写入 asset_edges、重建 FTS 索引。

domain_spec 中约定以下键供检索层直接投影(不新增物理列,保持 DDL 与规格 §3.1 一致):

键 值格式 用途
forward_cm 纯数字字符串,如 "185.0" filters.min_forward_cm / max_forward_cm 硬约束
strike_window "0.35..0.58" TOON strike_window 字段
root_motion_delta "[185.0,0.0,0.0]" YAML 运动学位移
phases JSON 字符串 YAML 三相位区间
notifies JSON 字符串 YAML Notify 列表
hint "Once\|1.2s\|User.SlashColor" TOON hint 字段

init.sql 中的 v_search 视图用 TRY_CAST(domain_spec['forward_cm'] AS DOUBLE) 把这些键投影为可过滤列。

2. L2:YAML 单资产规格

ual_inspect_asset 直接返回 assets.yaml_cache。生成器必须:

  1. 使用 identity / interface_contract / domain_spec / graph_context 四个顶层键。
  2. 每个非显然字段附 # 语义注释(单位、推断依据、建议对齐对象)。
  3. 数组用流式 [a, b] 或块式,浮点固定精度,保证 Git Diff 稳定。
  4. 输出以 # UEAssetLens AssetSpec v2.0 (Auto-generated, Zero-VLM) 开头。
  5. 禁止写入绝对本地磁盘路径、时间戳、随机 ID —— 否则 CI Diff 永远脏。

示例见规格说明书 §3.2。导出文件命名:Content/<...>/<AssetName>.spec.yaml。

3. L3:TOON 批量格式(UAL 自定义方言)

TOON = Token-Oriented Object Notation。头部一次性声明字段 Schema,数据行紧凑排列,避免 JSON 重复的 key 与括弧开销,节省 40%~60% 上下文 Token。

语法

<section_name>[<count>]{<field1>,<field2>,...}:
  <value1>,<value2>,...
  • 每个 section 的 {...} 声明一次字段名;后续每行按同序给值。
  • [N] 声明行数,必须与实际行数一致。
  • 字段值分隔符为半角逗号 ,。值内含逗号、双引号或换行时必须用双引号包裹,内部双引号转义为 \"。冒号不触发转义(logical_id 形如 AnimMontage:AM_... 含冒号但保持裸写)。
  • 区间值用 a..b,列表值用 a|b(例如 Once|1.2s|User.SlashColor)。
  • 缺失值写空串(连续两个逗号),NULL 不写进 TOON。
  • 非表格型元信息用 key: value 放在 section 之前的 query_summary 中。

四个工具的返回契约

工具 section 字段
ual_search_assets candidates logical_id,duration,forward_cm,strike_window,limb,score
ual_search_assets co_occurring_bundle logical_id,asset_class,weight,hint
ual_get_cooccurring_bundle co_occurring_bundle 同上
ual_find_similar_assets similar_assets logical_id,asset_class,similarity,shared_class

所有 TOON 输出首行固定为 # UEAssetLens TOON v1 (Zero-VLM),便于 Agent 端识别格式。

示例

# UEAssetLens TOON v1 (Zero-VLM)
query_summary:
  matched_total: 3
  scope: /Game/Characters/Knight

candidates[3]{logical_id,duration,forward_cm,strike_window,limb,score}:
  AnimMontage:AM_Knight_HeavySlash_02,1.15,185.0,0.35..0.58,hand_r,0.96
  AnimMontage:AM_Knight_DashThrust_01,0.90,320.0,0.25..0.45,hand_r,0.89

4. 兼容性约束

  • TOON 是 UAL 自定义方言,不是社区 TOON 标准;ual_common/toon.py 是唯一编解码实现,禁止在别处手写拼接。
  • YAML 生成器同样唯一:ual_common/yamlspec.py。
  • 任何字段变更必须同步修改本文件、init.sql、C++ UALTypes.h 与 Python db.py,并提交协议版本号递增。