本页内容同步自
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。生成器必须:
- 使用
identity/interface_contract/domain_spec/graph_context四个顶层键。 - 每个非显然字段附
#语义注释(单位、推断依据、建议对齐对象)。 - 数组用流式
[a, b]或块式,浮点固定精度,保证 Git Diff 稳定。 - 输出以
# UEAssetLens AssetSpec v2.0 (Auto-generated, Zero-VLM)开头。 - 禁止写入绝对本地磁盘路径、时间戳、随机 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与 Pythondb.py,并提交协议版本号递增。