神经元元数据
声明字段、筛选，以及为何元数据不是访问控制。
元数据不是访问控制。元数据字段（包括company_ids或privacy_level这类字段）只是用于筛选和展示的描述性标签，不会对任何人隐藏神经元：凡是对该Brain拥有读取权限的用户，都能看到全部神经元，与元数据无关；任何调用方也都可以直接省略筛选条件。如需限制谁能读取某个神经元，请使用神经元类型安全（高级安全），这才是强制生效的机制。
神经元元数据是一小组可附加到神经元上的声明式标签—例如产品、客户列表、隐私分级或审核标记。它的用途是筛选：将搜索或列表范围缩小到Brain中真正相关的部分，让智能体拿到最准确的十个神经元，而不是两百个似是而非的神经元。
元数据永远不会作为文本被搜索，也不会生成向量嵌入。编辑元数据不会影响神经元的向量嵌入、分块和内容哈希，因此为上千个神经元添加标签也无需重新索引。
注册表：先声明，后写入
每个Brain都有独立的元数据字段注册表。未声明的键既不能写入，也不能用于筛选—这是有意为之。自由格式的键容易混乱（这个神经元用“customer”，下一个用“customer_id”），而AI智能体也无从得知可以使用哪些键。注册表就是约定。
在Brain页面的元数据字段下进行管理，只有Brain所有者能看到该选项卡。如果Brain未声明任何字段，该功能只是处于休眠状态：没有可写入的内容，也没有可筛选的内容。
| 属性 | 含义 |
|---|---|
| 键 | 小写，以字母开头，可包含字母、数字、_和-，最多64个字符—例如product_id。以_开头的键为保留键。 |
| 值类型 | string、number或boolean。日期和版本号声明为string，并在描述中注明格式（例如“ISO日期，YYYY-MM-DD”）。 |
| 多值 | 开启后，存储的值是该类型的列表—例如company_ids: ["acme", "globex"]。对多值字段进行筛选的含义是“列表中包含该值”。 |
| 允许值 | 可选枚举值。留空则不限取值。写入时会按枚举校验，筛选时不会，因此缩小枚举范围不会导致现有数据无法访问。 |
| 描述 | 这是AI读取的内容。它由aiqbee_list_metadata_fields返回，并在aiqbee_get_brain_info中汇总呈现，模型正是通过它来理解字段含义以及哪些值是合理的。请写给模型看，而不是写给自己：“此笔记涉及的产品；值为产品标识，例如hive-server”远胜于“product”。 |
编辑和删除字段
- 编辑描述或允许值不会改变任何已存储的数据。
- 更改类型或多值标记也是允许的，同样不会改写已存储的值。现有值保持原样，并仍按存储时的形式参与筛选匹配；只有新写入的值才会按新定义校验。不再符合定义的值最多只会无法匹配筛选条件—绝不会造成任何破坏。
- 删除字段不会删除数据。神经元上已有的值会被保留，但不再生效：指定已删除键的筛选会被拒绝，一旦重新声明该键，这些值就会重新出现。
写入值
在神经元页面，元数据卡片为每个已声明字段提供一个输入框。将输入框留空即可移除该值；清除所有元数据会清空整个对象。智能体通过aiqbee_create_neuron和aiqbee_update_neuron实现相同操作，其中metadata是合并补丁：发送的键会覆盖已存储的值，JSON null会删除对应的键，字符串clear会清空全部内容。
限制：每个神经元最多20个键，序列化后的JSON不超过8 KB。值为扁平结构—标量，或多值字段使用标量列表。不支持嵌套对象。
筛选
在Brain页面，在神经元列表下方选择字段和值，即可添加筛选标签。筛选标签是链接，因此可以收藏或分享筛选后的视图。通过MCP时，对应的是aiqbee_search和aiqbee_list_neurons上的metadata_filter参数。
| 写法 | 含义 |
|---|---|
{"product_id": "hive-server"} |
等值匹配。标量值须与该值完全一致。对于多值字段，表示“存储的列表包含此值”。 |
{"privacy_level": ["internal", "public"]} |
任一匹配。列表中任意一个值匹配即视为匹配。 |
{"reviewed": {"exists": true}} |
存在匹配。匹配所有带有该键的神经元，无论其值为何。在Web界面中，将值输入框留空即可。 |
{"product_id": "phoenix", "privacy_level": "internal"} |
不同键之间为“与”关系。每个指定的键都必须匹配。再加上同一键内的“任一匹配”，这就是全部的筛选语法：不支持范围，也不支持or/not嵌套。 |
筛选条件可与其他所有条件组合使用—文本搜索、神经元类型和访问控制。无论是否使用元数据筛选，您无权查看的神经元始终保持隐藏。
值会被转换为声明的类型，因此在number字段中筛选"5"可以找到5。按Brain未声明的键进行筛选会被拒绝，并返回已声明的键列表—正因如此，智能体只需一次往返即可自行纠正，而不会悄无声息地得到空结果。
许可证：付费功能及许可证失效后的影响
神经元元数据与审计历史、高级安全一样，是付费功能—详见许可证&版本。这一限制刻意设计为不对称，正是这种不对称让降级后数据不受影响。
| 操作 | 免费版 / 无权益许可证 |
|---|---|
| 读取神经元上的元数据 | 始终允许 |
| 按元数据筛选搜索结果和列表 | 始终允许 |
| 列出已声明的字段 | 始终允许 |
| 删除值、清空神经元的元数据 | 始终允许 |
| 删除已声明的字段 | 始终允许 |
| 添加或修改值 | 已拒绝—需要付费许可证 |
| 声明或编辑字段 | 已拒绝—需要付费许可证 |
因此，如果许可证过期或降级：不会删除任何内容，也不会隐藏任何内容。在许可证有效期间写入的每个值都会保留在对应神经元上，在界面和工具结果中依然可见，并且仍可用于筛选。只有写入会被阻止。删除操作特意保持开放，确保您不会陷入无法退出的状态。重新获得许可证后即可立即恢复写入—无需恢复或重新导入任何数据。元数据也会随OKF导出一并带走；在没有该权益的Hive上导入此包时，会存储这些值，但不会创建字段注册表。
控件置灰只是一种提示；检查在服务器端进行，对Web界面和MCP工具同样适用。许可证过期是另一种更广泛的情况：整个Hive都会变为只读，包括元数据。
元数据不是什么
这一点值得再强调一次，因为字段名很容易让人误解。名为company_ids或privacy_level的字段看起来像权限控制，但它并不是，Hive也不会将其视为权限。
- 对Brain有读取权限的用户都能看到每个神经元及其全部元数据，与标签内容无关。
- 任何调用方都可以直接省略该筛选条件。
- 搜索、列表和获取操作都不会依据元数据来决定可见性。
如需真正限制谁可以读取某个神经元，请使用神经元类型安全（高级安全）：将该神经元标记为受类型保护，并将其神经元类型授予应当能够查看的用户、用户组或服务账号。这才是强制执行的机制，作用于每一条读取路径。元数据与之并存，仅用于描述，绝不能作为防护手段。