cat-class-ingestors-schema

name	cat-class-ingestors-schema
description	解释、生成和修改 Cat 项目的 `priv/config/class_ingestors_schema.yaml`。当任务涉及 class ingestor 的概念、YAML 语法，或 `steam`、`wikidata` 的 provider 配置时使用。手动调用触发。
disable-model-invocation	true

Cat Class Ingestors Schema

这个 skill 只服务一个目标：正确理解和生成 priv/config/class_ingestors_schema.yaml。

它是一份 class -> provider 配置文件，描述某个 class 是否开放某个抓取型导入入口，以及该入口的 provider 配置。

生成这份 YAML 时，必须以 priv/config/catalog_schema.yaml 为前置输入。class_ingestors_schema 不能脱离 catalog_schema 单独设计。

开始生成前，先阅读 priv/config/catalog_schema.yaml。只有先读这份文件，才能知道当前系统里：

• 有哪些 class
• 有哪些 property
• 每个 class 绑定了哪些 property
• 这些 property 的 datatype 是什么

这个 schema 负责什么

• 声明某个 class 是否开启 steam
• 声明某个 class 是否开启 wikidata
• 为 wikidata 提供语言回退和 claim mapping 配置

这个 schema 不负责什么

• 不创建 class
• 不创建 property
• 不绑定 class_property
• 不管理 form 手动表单入口

如果 YAML 里需要引用的 class 或 property 还不存在，应该先处理 priv/config/catalog_schema.yaml，再生成 class_ingestors_schema。

核心概念

class_ingestors

• 表示“某个 class 开启了哪个抓取型 provider，以及该 provider 在这个 class 上的配置”
• 当前只支持抓取型 provider：steam、wikidata
• 用户端手动表单 form 不在这个 schema 里

与 catalog_schema 的关系

class_ingestors_schema 依赖 priv/config/catalog_schema.yaml 中已经定义好的：

• classes
• properties
• classes[].properties 绑定关系

也就是说，ingestors 的生成不是“从 provider 倒推 schema”，而是“在既有 catalog schema 之上补充 provider 配置”。

原因：

• class_idname 必须能命中已有 class
• wikidata 配置里的 property 必须已经绑定到当前 class
• steam 也会检查当前 class 是否满足最小约束

生成时应先看 priv/config/catalog_schema.yaml，再决定某个 class 能不能写 steam / wikidata。不先读这份文件，就无法知道当前系统中到底有什么属性可用。

priv/config/catalog_schema.yaml 基础语法

这份文件本身也是一份 YAML object，当前最重要的根字段是：

• classes
• properties

可以先把它理解成两层信息：

• classes 负责定义“系统里有哪些 class，以及每个 class 绑定了哪些 property”
• properties 负责定义“这些 property 自己的全局数据结构和 datatype”

基础结构示意：

classes:
  - idname: 游戏
    label: 游戏
    properties:
      - idname: SteamAppID
        correction_mode: disabled
        vote_threshold: 3
      - idname: 官网URL
        correction_mode: report
        vote_threshold: 3
    subject_explore_config:
      filter_rows: []
      show_keyword_search: false
    subject_page_layout:
      main_extra_modules: []
      version: 1

properties:
  - idname: SteamAppID
    label: SteamAppID
    datatype: identifier
  - idname: 官网URL
    label: 官网URL
    datatype: string

classes

• classes 是 list
• 每个元素代表一个 class 定义
• 生成 ingestor 时，最先关注的是 classes[].idname

例如：

• classes[].idname=游戏 表示当前系统里存在 游戏 这个 class
• 只有 class 已存在，class_ingestors_schema 里才可以写 class_idname: 游戏

classes[].properties

• classes[].properties 也是 list
• 每个元素表示“这个 class 绑定了哪个 property”
• 这里最关键的是 classes[].properties[].idname

例如：

• 如果 游戏 的 properties 里有 SteamAppID
• 才能认为 SteamAppID 已经绑定到 游戏
• 这会直接影响 steam 或 wikidata 的配置能不能成立

这里要注意：classes[].properties 说的是“绑定关系”，不是 property 的完整定义。

根级 properties

• 根级 properties 是全局 property 定义列表
• 每个元素代表一个 property 自己的 schema
• 生成 ingestor 时，最关键的是 properties[].idname 和 properties[].datatype

例如：

• properties[].idname=官网URL
• properties[].datatype=string

这才说明 官网URL 这个 property 存在，并且它的 datatype 是 string。

哪些字段和 ingestor 生成直接相关

生成 class_ingestors_schema 时，至少要先从 catalog_schema 读出这几类信息：

• classes[].idname
• classes[].properties[].idname
• properties[].idname
• properties[].datatype

其他字段如：

• label
• description
• subject_explore_config
• subject_page_layout
• mark_config

它们属于 catalog 自身的展示或行为配置，通常不是生成 ingestor YAML 的核心判断依据。

YAML 顶层语法

顶层必须是 object，并且只允许一个根字段：

class_ingestors:
  - class_idname: 游戏
    provider: steam
    enabled: true
    config: {}

每个条目必须是 object，允许字段只有：

• class_idname
• provider
• enabled
• config

字段规则：

字段	类型	必填	说明
class_idname	string	是	必须命中已有 class
provider	string	是	当前只允许 steam、wikidata
enabled	boolean	是	是否开放该入口
config	object	是	provider 专属配置；可以为空对象

补充规则：

• 同一个 {class_idname, provider} 不能重复

Provider 语法

steam

最小写法：

class_ingestors:
  - class_idname: 游戏
    provider: steam
    enabled: true
    config: {}

当前实现约束：

• steam 只允许配置到 class_idname=游戏
• 当前 class 必须已绑定 SteamAppID
• config 允许为空对象

如果用户要求把 steam 开到别的 class，不要硬写 YAML；先说明当前代码不支持。

wikidata

最小推荐写法：

class_ingestors:
  - class_idname: 疾病
    provider: wikidata
    enabled: true
    config:
      identifier_property_idname: WikidataID
      label_languages: [zh-hans, zh, en]
      description_languages: [zh-hans, zh, en]
      claim_mappings: []

config 允许字段：

• identifier_property_idname
• label_languages
• description_languages
• required_sitelink_site_keys
• claim_mappings
• acceptance

默认语义：

• identifier_property_idname 缺省时回落到 WikidataID
• label_languages 缺省时回落到 [zh-hans, zh, en]
• description_languages 缺省时回落到 [zh-hans, zh, en]
• required_sitelink_site_keys 缺省时表示不额外要求 sitelink
• claim_mappings 必须是 list
• acceptance 缺省时表示不做条目准入过滤

required_sitelink_site_keys 语法

用于限制“条目必须具备哪些 sitelink site key 才允许导入”。

基础写法：

required_sitelink_site_keys: [zhwiki]

语义：

• 必须是 string list
• list 中的每个 site key 都必须在 Wikidata sitelinks 中存在
• 例如 [zhwiki] 表示“只接受带 zhwiki sitelink 的条目”

acceptance 语法

用于限制“哪些 Wikidata Item 允许导入到当前 class”。

基础写法：

acceptance:
  mode: any
  rules:
    - wikidata_property_id: P279
      operator: has_entity_id
      entity_id: Q11422
    - wikidata_property_id: P571
      operator: year_between
      min_year: 1980
      max_year: 1999

允许字段：

• mode
• rules

mode 允许值：

• all
• any

rules 必须是非空 list，每个条目允许字段：

• wikidata_property_id
• operator
• entity_id
• min_year
• max_year

当前支持的 operator：

• has_entity_id
• year_between

校验规则：

• wikidata_property_id 必须是合法 PID
• operator=has_entity_id 时必须提供合法 entity_id
• operator=year_between 时必须提供整数 min_year / max_year
• operator=year_between 时 max_year >= min_year
• mode=all 表示所有规则都要命中
• mode=any 表示任一规则命中即可导入

claim_mappings 语法

基础写法：

claim_mappings:
  - wikidata_property_id: P856
    target_property_idname: 官网URL
    transform: url

允许字段：

• wikidata_property_id
• target_property_idname
• target_subject_field
• transform
• related_class_idname
• related_identifier_property_idname

当前支持的 transform：

• url
• time
• commons_media
• entity_to_related_subject

datatype 约束

• url -> target_property_idname 必须绑定 string
• time -> target_property_idname 必须绑定 string
• commons_media -> target_property_idname 必须绑定 image，或 target_subject_field: cover_file_id
• entity_to_related_subject -> target_property_idname 必须绑定 subject

target_property_idname 与 target_subject_field 只能填写一个。 target_subject_field 当前只支持 cover_file_id，用于把 Wikidata Commons 图片下载后写入 Subject 固有字段 subjects.cover_file_id，不会生成 claim。YAML 推荐写规范值 cover_file_id；subject.cover_file_id / subjects.cover_file_id 会被规范化为 cover_file_id。

claim_mappings:
  - wikidata_property_id: P18
    target_subject_field: cover_file_id
    transform: commons_media

wikidata_property_id 必须是合法 PID，例如 P856。

entity_to_related_subject

这种 transform 需要额外字段：

claim_mappings:
  - wikidata_property_id: P50
    target_property_idname: 作者
    transform: entity_to_related_subject
    related_class_idname: 人物
    related_identifier_property_idname: WikidataID

额外校验点：

• related_class_idname 必须存在
• related_identifier_property_idname 必须是该 related class 已绑定的 identifier property
• target_property_idname 的 subject.allowed_class_idnames 必须包含 related_class_idname
• target_property_idname 的 subject.allowed_value_types 必须包含 id

生成时的判断

生成 class_ingestors_schema 前，先从 priv/config/catalog_schema.yaml 提取三件事：

1. 目标 class 是否存在
2. 目标 class 已绑定了哪些 property
3. 这些 property 的 datatype 是什么

只有这三件事明确后，才开始写 ingestor 条目。

以下情况属于改 class_ingestors_schema：

• 给某个 class 开启或关闭 steam
• 给某个 class 开启或关闭 wikidata
• 修改 Wikidata 的语言回退顺序
• 修改 Wikidata 的条目准入规则（acceptance）
• 增删 Wikidata 的 claim_mappings

以下情况不属于改 class_ingestors_schema：

• 新增 WikidataID、SteamAppID 这类 property
• 把 property 绑定到某个 class
• 修改 subject/property 数据模型

这些应先处理 catalog_schema。

使用要求

• 生成时先参考 priv/config/catalog_schema.yaml，不要跳过它直接写 provider 配置
• 如果还没阅读 priv/config/catalog_schema.yaml，不要开始写 class_ingestors_schema
• 生成或修改 YAML 时，不要虚构不存在的 class 或 property
• 未确认 catalog 侧依赖存在前，不要盲写 wikidata 的 mapping
• 如果用户只说“开启 Wikidata”，默认至少补全：
  • identifier_property_idname
  • label_languages
  • description_languages
  • claim_mappings: []
• 如果用户只是在问语法或概念，只输出 YAML 和说明，不延伸到其他操作