技术文档

Xenkey 规范 v1.0

Xenkey 的权威、可读规范 spec=1.0. 包含结构、意义模型、生命周期规则、索引与技术行为。

第 1 节

什么是 Xenkey？

Xenkey 是关于现实对象的原子级意义单元——企业、产品、服务、地点、人物、流程或事件。它为 AI 理解而写，而非为营销说服。

每个 Xenkey 表达一个单一、最小、可证伪的观点。规范版本会在每个文档中声明：

Schema 标题
{ "spec": "1.0" }
第 2 节

设计目标

真相高于说服

描述现实，而不是宣传。

语境性

捕捉何时、何地、为谁适用。

可组合性

多个 Xenkey 描述一个对象。

AI 可读性

为检索与索引提供严格结构。

第 3 节

身份标识

字段类型说明
idstring主标识符。格式：xk_ + ULID
ulidstring可选。从 id 后缀派生（存在时必须匹配）
spec"1.0"规范版本
第 4 节

生命周期与可变性

Xenkey 遵循严格的生命周期，确保数据完整性与可信度。

状态:
draftunpublishedpublishedarchived

可变性规则

  • •草稿 — 可自由编辑
  • •已发布 — 不可变更。修改需创建新的 Xenkey
  • •如果 published_at 已设置，状态不能是 draft
字段类型说明
statusenumdraft | unpublished | published | archived
created_atdatetime创建时间戳（RFC 3339）
published_atdatetimeXenkey 发布时间
updated_atdatetime内部/只读，由 API 设置
etagstring内部/只读，用于并发控制
第 5 节

意义核心

每个 Xenkey 的核心。四个必填字段捕捉结构化真理单元。

字段类型说明
titlestring对体验的简短描述性标识
factstring关于现实的事实性、可验证陈述
meaningstring该事实对人类为何重要
contextstring适用的时间、地点与人群
constraintsstring结构字段未覆盖的自由语境
第 6 节

范围与锚点

锚点将 Xenkey 绑定到现实实体。每个 Xenkey 必须至少有一个锚点。多锚点支持让单个 Xenkey 描述多个对象的交集。

字段类型说明
organization_idstring所属组织
base_idstring逻辑分组（workspace/project）
unit_idstring可选的结构化数据条目引用
anchors[]array锚点对象数组（至少 1 个）
锚点对象
{
  "anchor_id": "anchor_001",
  "anchor_type": "product",
  "role": "primary"
}
锚点类型:
productservicepersonlocationeventprocessresource
第 7 节

标签、情绪与氛围

字段类型说明
tagsstring[]分类标签（如 booking_required, wifi）
emotionsstring[]情绪上下文代码（来自 emotion-codes.json）
vibestring氛围/情绪描述
seasonsstring[]适用季节
time_of_daystring[]适用时段
mealstring[]适用餐段
季节:
springsummerautumnwinterall_yearholidaynew_yearchristmasorient_new_year
一天中的时间:
all_dayearly_morningmorningnoonafternooneveningnightlate_night
餐段:
breakfastbrunchlunchdinnersuppertea_timecoffee_timesnack_time
第 8 节

人群特征

字段类型说明
age_mininteger建议最小年龄
age_maxinteger建议最大年龄（需 >= age_min）
genderstring目标性别（如适用）
第 9 节

地理

Xenkey 可以是全球性的或地理限定的。 geo_scope 字段决定哪些地理字段为必填。

地理范围:
globalcountryregionpoint
字段类型说明
geo_scopeenum地理精度级别
countrystringISO 3166-1 alpha-2 国家代码
regionstring地区/州/省
citystring城市名称
timezonestringIANA 时区名称（如 Europe/Rome）
geo[lng, lat]坐标 [经度, 纬度]
availability_countriesstring[]可用国家（非地点）

范围规则： 如果 geo_scope=country 那么 country 为必填。 如果 geo_scope=region 那么 country 与 region (or city) 为必填。 如果 geo_scope=point 那么 geo 为必填。

第 10 节

本地化

字段类型说明
localestring语言标签（如 en-US, ja-JP）
source_localestring内容的源语言
translation_groupstring将翻译分组。格式：tg_ + ULID
is_source_localeboolean若为源语言版本则为 true

规则： 如果 is_source_locale = true, 那么 locale 必须等于 source_locale. 翻译复用相同的 translation_group。

第 11 节

完整性

已发布的 Xenkey 会在发布时计算加密哈希，确保内容完整性。

字段类型说明
hash_alg"sha256"使用的哈希算法
hash_idstring唯一哈希标识。格式：hash_ + ULID
hashstring规范载荷的 SHA-256 哈希
第 12 节

索引与隐私

Xenkey 可发布到多个通道。每个通道启用不同的检索能力。

字段类型说明
publicationstring[]通道：vector, graph, aidex
is_publishedboolean至少发布到一个通道为 true
is_vectorboolean向量索引（Qdrant）
is_graphboolean投影到知识图谱（Neo4j）
is_aidexboolean发布到 Aidex 机器人导向的 wiki
is_privateboolean仅组织范围可见

规则：

  • • aidex 要求 vector （两者都必须出现在 publication 中）
  • • 如果is_published=true publication 必须至少包含一项
  • • Aidex 是面向机器人的 wiki 层，配额要求比向量索引更严格
第 13 节

向量与图检索

已发布的 Xenkey 会自动转化为两种互补的数据表示，以实现 AI 的混合检索。

向量索引（Qdrant）

  • • 文本来源：fact + meaning + context
  • • 转换为高维嵌入向量
  • • 支持语义相似性搜索
  • • 载荷过滤：status, geo, tags, emotions, time
  • • 幂等性：键 (id, version)

知识图谱（Neo4j）

  • • 节点：Xenkey, Organization, Object, Tag, Emotion
  • • 边：OWNS, DESCRIBED_BY, TAGS, EXPRESSES
  • • 揭示关系与结构
  • • 自然键幂等 MERGE
  • • 支持图遍历查询

混合检索 结合向量相似度与图结构过滤，提供可解释且有依据的 AI 响应。 索引管道为异步，带重试与死信队列。

第 14 节

不变规则

  • ✓anchors 必须存在且非空
  • ✓如果同时存在age_min 与 age_max 则 age_max >= age_min
  • ✓如果geo 存在，则必须为 [longitude, latitude]
  • ✓geo_scope=country 要求 country
  • ✓geo_scope=region 要求 country + region (or city)
  • ✓geo_scope=point 要求 geo
  • ✓aidex 在 publication 中意味着 vector 也在 publication 中
  • ✓is_published=true 要求非空 publication[]
第 15 节

示例载荷

草稿 Xenkey（最小）

draft-xenkey.json
{
  "spec": "1.0",
  "id": "xk_01J8Y6S4V9ZQ3M9K2W2M8JQY5C",
  "status": "draft",
  "created_at": "2026-01-21T12:00:00Z",
  "organization_id": "org_123",
  "base_id": "base_123",
  "anchors": [
    { "anchor_id": "anchor_1", "anchor_type": "product", "role": "primary" }
  ],
  "title": "Fresh espresso",
  "fact": "A 30 ml espresso shot made from 100% Arabica beans.",
  "meaning": "Represents the cafe's standard espresso offering.",
  "context": "Default menu item available all day.",
  "locale": "en-US",
  "source_locale": "en-US",
  "translation_group": "tg_01J8Y6S6Q4K8FKJ1PS2H0WQ1B8",
  "is_source_locale": true,
  "hash_alg": "sha256",
  "hash_id": "hash_01J8Y6S6Q4K8FKJ1PS2H0WQ1B9",
  "hash": "6e4f8c9d8b0f7a6d3b3a0f3c1f8e9d6e...",
  "is_vector": false,
  "is_graph": false,
  "is_aidex": false,
  "publication": [],
  "is_published": false,
  "is_private": false
}

已发布 Xenkey（含地理 + 向量索引）

published-xenkey.json
{
  "spec": "1.0",
  "id": "xk_01J8Y6S9QH8P2G8P6X1K3R2H5A",
  "status": "published",
  "created_at": "2026-01-21T12:05:00Z",
  "published_at": "2026-01-21T12:10:00Z",
  "organization_id": "org_123",
  "base_id": "base_123",
  "unit_id": "unit_456",
  "anchors": [
    { "anchor_id": "anchor_1", "anchor_type": "product", "role": "primary" }
  ],
  "title": "Fresh espresso",
  "fact": "A 30 ml espresso shot made from 100% Arabica beans.",
  "meaning": "Represents the cafe's standard espresso offering.",
  "context": "Default menu item available all day.",
  "tags": ["coffee", "espresso", "menu_item"],
  "time_of_day": ["morning", "afternoon"],
  "meal": ["breakfast", "coffee_time"],
  "vibe": "energetic",
  "geo_scope": "point",
  "country": "IT",
  "city": "Milan",
  "timezone": "Europe/Rome",
  "geo": [9.1900, 45.4642],
  "locale": "en-US",
  "source_locale": "en-US",
  "translation_group": "tg_01J8Y6S6Q4K8FKJ1PS2H0WQ1B8",
  "is_source_locale": true,
  "hash_alg": "sha256",
  "hash_id": "hash_01J8Y6S6Q4K8FKJ1PS2H0WQ1B9",
  "hash": "6e4f8c9d8b0f7a6d3b3a0f3c1f8e9d6e...",
  "is_vector": true,
  "is_graph": false,
  "is_aidex": false,
  "publication": ["vector"],
  "is_published": true,
  "is_private": false
}

此规范是 Xenkey 的权威参考 spec=1.0.

规范 JSON Schema： xenkey_schema_v1_0.json