Back to Details

skos-taxonomy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SKOS Taxonomist

SKOS分类专家

Design operational taxonomies with SKOS so Panda and all sub-agents classify work consistently, retrieve better context, and avoid tag soup.
This skill is for execution, not theory: define concepts, classify agent data, validate constraints, and wire taxonomy fields into Typesense.
使用SKOS设计可落地的分类体系，让Panda及所有子Agent能够统一分类工作内容、获取更优质的上下文信息，并避免标签混乱。
本技能聚焦落地执行而非理论：定义概念、分类Agent数据、验证约束条件，并将分类字段接入Typesense。

When to Use

适用场景

Use this skill when any request involves:
  • "taxonomy", "SKOS", "controlled vocabulary", "concept scheme"
  • classifying agent interactions, runs, docs, memory, events, or tasks
  • designing or revising 
    concept_ids
    / 
    primary_concept_id
    contracts
  • mapping joelclaw concepts to another vocabulary
  • deciding whether SKOS is needed or a simpler tag model is enough
当需求涉及以下内容时，使用本技能：
  • "分类体系"、"SKOS"、"受控词汇表"、"概念方案"
  • 对Agent交互、运行记录、文档、记忆、事件或任务进行分类
  • 设计或修订
    concept_ids
    / 
    primary_concept_id
    规范
  • 将joelclaw概念映射至其他词汇表
  • 判断是否需要SKOS，或是更简单的标签模型已足够

Primary Outcomes

核心产出

  1. A versioned SKOS concept scheme with stable concept URIs.
  2. Agent-classification rules that produce deterministic concept metadata.
  3. Typesense field mappings that support lexical, faceted, and hybrid retrieval.
  4. Governance rules for candidate concepts, alias drift, deprecation, and mappings.
  1. 带有稳定概念URI的版本化SKOS概念方案。
  2. 可生成确定性概念元数据的Agent分类规则。
  3. 支持词法检索、分面检索和混合检索的Typesense字段映射。
  4. 针对候选概念、别名漂移、废弃处理及映射的治理规则。

Non-Negotiable SKOS Rules (Normative)

SKOS必守规则（规范性要求）

Follow these in every scheme:
  1. skos:Concept
    and 
    skos:ConceptScheme
    are distinct classes.
  2. skos:broader
    is not transitive; use transitive super-property semantics (
    skos:broaderTransitive
    ) for closure queries.
  3. skos:prefLabel
    max one value per language tag for a resource.
  4. skos:prefLabel
    , 
    skos:altLabel
    , and 
    skos:hiddenLabel
    are pairwise disjoint for the same resource+language form.
  5. skos:related
    is disjoint with 
    skos:broaderTransitive
    .
  6. Mapping relations are for cross-scheme linking. 
    skos:exactMatch
    is transitive and should be used sparingly.
  7. skos:closeMatch
    is intentionally non-transitive.
  8. skos:Collection
    / 
    skos:OrderedCollection
    are for grouping; they are disjoint with 
    skos:Concept
    .
If any of these fail, stop and fix data before rollout.
所有方案均需遵循以下规则：
  1. skos:Concept
    和
    skos:ConceptScheme
    为不同的类。
  2. skos:broader
    不具备传递性；如需闭合查询，使用传递性超属性语义（
    skos:broaderTransitive
    ）。
  3. 每个资源的每种语言标签仅能有一个
    skos:prefLabel
    值。
  4. 同一资源的同一语言形式下，
    skos:prefLabel
    、
    skos:altLabel
    和
    skos:hiddenLabel
    两两互不重叠。
  5. skos:related
    与
    skos:broaderTransitive
    互不相交。
  6. 映射关系用于跨方案链接。
    skos:exactMatch
    具备传递性，应谨慎使用。
  7. skos:closeMatch
    明确不具备传递性。
  8. skos:Collection
    / 
    skos:OrderedCollection
    用于分组；它们与
    skos:Concept
    互不相交。
若上述任何规则未被满足，需先修复数据再推进上线。

JoelClaw Operational Scheme (Workload v1)

JoelClaw可落地方案（工作负载v1）

Define a dedicated scheme for workload classification:
  • Scheme URI: 
    joelclaw:scheme:workload:v1
  • Taxonomy version string: 
    workload-v1
  • Concept URI pattern: 
    joelclaw:concept:<top-level>[:<subconcept>]
  • Notation style: upper snake or dotted operational codes (stable and immutable)
为工作负载分类定义专属方案：
  • 方案URI：
    joelclaw:scheme:workload:v1
  • 分类版本字符串：
    workload-v1
  • 概念URI格式：
    joelclaw:concept:<top-level>[:<subconcept>]
  • 标识风格：大写蛇形命名或点分隔的可执行代码（稳定且不可变）

Top-Level Concepts (Required)

顶层概念（必填）

NotationURIPurpose
PLATFORM
joelclaw:concept:platform
Runtime/platform infrastructure and hosting substrate
INTEGRATION
joelclaw:concept:integration
External system connections, APIs, webhooks, adapters
TOOLING
joelclaw:concept:tooling
CLI/dev tooling, operator commands, local automation
PIPELINE
joelclaw:concept:pipeline
Inngest/event workflows, ingestion and processing chains
BUILD
joelclaw:concept:build
Code implementation, tests, CI/CD, packaging
KNOWLEDGE
joelclaw:concept:knowledge
Docs, memory, taxonomy, retrieval context
COMMS
joelclaw:concept:comms
Messaging channels, notifications, agent/user communication
OBSERVE
joelclaw:concept:observe
OTEL/logging/metrics/diagnostics/reliability telemetry
META
joelclaw:concept:meta
Governance, ADRs, policies, lifecycle and process controls
标识URI用途
PLATFORM
joelclaw:concept:platform
运行时/平台基础设施及托管底层
INTEGRATION
joelclaw:concept:integration
外部系统连接、API、Webhook、适配器
TOOLING
joelclaw:concept:tooling
CLI/开发工具、操作员命令、本地自动化
PIPELINE
joelclaw:concept:pipeline
事件摄入/处理工作流、数据链
BUILD
joelclaw:concept:build
代码实现、测试、CI/CD、打包
KNOWLEDGE
joelclaw:concept:knowledge
文档、记忆、分类体系、检索上下文
COMMS
joelclaw:concept:comms
消息渠道、通知、Agent/用户通信
OBSERVE
joelclaw:concept:observe
OTEL/日志/指标/诊断/可靠性遥测
META
joelclaw:concept:meta
治理、ADR、政策、生命周期及流程管控

Core Turtle Skeleton

核心Turtle框架

turtle
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .

jcw:scheme:workload:v1 a skos:ConceptScheme ;
  skos:prefLabel "JoelClaw Workload Taxonomy v1"@en ;
  skos:definition "Operational workload taxonomy for Panda and sub-agents."@en ;
  skos:hasTopConcept
    jcw:concept:platform,
    jcw:concept:integration,
    jcw:concept:tooling,
    jcw:concept:pipeline,
    jcw:concept:build,
    jcw:concept:knowledge,
    jcw:concept:comms,
    jcw:concept:observe,
    jcw:concept:meta .

jcw:concept:pipeline a skos:Concept ;
  skos:inScheme jcw:scheme:workload:v1 ;
  skos:topConceptOf jcw:scheme:workload:v1 ;
  skos:notation "PIPELINE" ;
  skos:prefLabel "Pipeline"@en ;
  skos:altLabel "workflow"@en, "event flow"@en ;
  skos:definition "Durable event-driven processing sequences."@en ;
  skos:scopeNote "Use for Inngest functions, ingest chains, and orchestration logic."@en ;
  skos:narrower jcw:concept:pipeline:ingest, jcw:concept:pipeline:enrichment ;
  skos:related jcw:concept:observe, jcw:concept:build .
turtle
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .

jcw:scheme:workload:v1 a skos:ConceptScheme ;
  skos:prefLabel "JoelClaw Workload Taxonomy v1"@en ;
  skos:definition "Operational workload taxonomy for Panda and sub-agents."@en ;
  skos:hasTopConcept
    jcw:concept:platform,
    jcw:concept:integration,
    jcw:concept:tooling,
    jcw:concept:pipeline,
    jcw:concept:build,
    jcw:concept:knowledge,
    jcw:concept:comms,
    jcw:concept:observe,
    jcw:concept:meta .

jcw:concept:pipeline a skos:Concept ;
  skos:inScheme jcw:scheme:workload:v1 ;
  skos:topConceptOf jcw:scheme:workload:v1 ;
  skos:notation "PIPELINE" ;
  skos:prefLabel "Pipeline"@en ;
  skos:altLabel "workflow"@en, "event flow"@en ;
  skos:definition "Durable event-driven processing sequences."@en ;
  skos:scopeNote "Use for Inngest functions, ingest chains, and orchestration logic."@en ;
  skos:narrower jcw:concept:pipeline:ingest, jcw:concept:pipeline:enrichment ;
  skos:related jcw:concept:observe, jcw:concept:build .

Agent Classification Contract

Agent分类规范

Every sub-agent output that can be stored/retrieved must emit:
  • primary_concept_id
    (single canonical concept URI)
  • concept_ids
    (ordered list: primary first, then secondary)
  • taxonomy_version
  • concept_source
    (
    rules|llm|backfill|manual|fallback
    )
  • classification_confidence
    (0-1 float, optional but recommended)
Recommended envelope:
json
{
  "primary_concept_id": "joelclaw:concept:pipeline:ingest",
  "concept_ids": [
    "joelclaw:concept:pipeline:ingest",
    "joelclaw:concept:knowledge",
    "joelclaw:concept:observe"
  ],
  "taxonomy_version": "workload-v1",
  "concept_source": "rules",
  "classification_confidence": 0.88
}
所有可存储/检索的子Agent输出必须包含：
  • primary_concept_id
    （单个标准概念URI）
  • concept_ids
    （有序列表：主概念在前，次概念在后）
  • taxonomy_version
  • concept_source
    （
    rules|llm|backfill|manual|fallback
    ）
  • classification_confidence
    （0-1浮点数，可选但推荐）
推荐结构：
json
{
  "primary_concept_id": "joelclaw:concept:pipeline:ingest",
  "concept_ids": [
    "joelclaw:concept:pipeline:ingest",
    "joelclaw:concept:knowledge",
    "joelclaw:concept:observe"
  ],
  "taxonomy_version": "workload-v1",
  "concept_source": "rules",
  "classification_confidence": 0.88
}

Classification Procedure

分类流程

  1. Normalize candidate labels (
    trim
    , lowercase, slugify, punctuation collapse).
  2. Match against 
    prefLabel
    , then 
    altLabel
    , then 
    hiddenLabel
    alias tables.
  3. Disambiguate using 
    scopeNote
    and neighboring concepts (
    broader
    , 
    related
    ).
  4. Emit one primary concept plus optional secondary concepts.
  5. If unresolved, map to a controlled fallback concept and log unmapped labels.
  6. Emit OTEL metadata for mapping diagnostics (
    mapped_count
    , 
    unmapped_count
    , 
    taxonomy_version
    ).
  1. 标准化候选标签（去除首尾空格、转为小写、生成短标识、合并标点）。
  2. 依次匹配
    prefLabel
    、
    altLabel
    、
    hiddenLabel
    别名表。
  3. 使用
    scopeNote
    及相邻概念（
    broader
    、
    related
    ）消除歧义。
  4. 输出一个主概念及可选的次概念。
  5. 若无法匹配，映射至受控的备用概念并记录未匹配标签。
  6. 输出OTEL元数据用于映射诊断（
    mapped_count
    、
    unmapped_count
    、
    taxonomy_version
    ）。

SKOS-XL (When Labels Need First-Class Metadata)

SKOS-XL（当标签需要一等元数据时）

Use SKOS-XL only when label objects need metadata or relationships:
  • acronym/abbreviation management with provenance
  • per-label source attribution
  • multilingual/transliteration workflows with label-level auditing
  • label-to-label relationships (deprecated term -> replacement term)
If labels are plain synonyms only, stay with core SKOS labels.
仅当标签对象需要元数据或关联关系时使用SKOS-XL：
  • 带溯源的首字母缩写/简称管理
  • 按标签归属的来源归因
  • 带标签级审计的多语言/音译工作流
  • 标签间关联关系（废弃术语 -> 替代术语）
若标签仅为普通同义词，使用核心SKOS标签即可。

SKOS-XL Example

SKOS-XL示例

turtle
@prefix skosxl: <http://www.w3.org/2008/05/skos-xl#> .
@prefix jcw: <joelclaw:> .

jcw:label:comms:imessage a skosxl:Label ;
  skosxl:literalForm "iMessage"@en .

jcw:concept:comms:imessage skosxl:altLabel jcw:label:comms:imessage .
turtle
@prefix skosxl: <http://www.w3.org/2008/05/skos-xl#> .
@prefix jcw: <joelclaw:> .

jcw:label:comms:imessage a skosxl:Label ;
  skosxl:literalForm "iMessage"@en .

jcw:concept:comms:imessage skosxl:altLabel jcw:label:comms:imessage .

Mapping to External Vocabularies

映射至外部词汇表

Use mapping properties across schemes, not inside one scheme:
  • skos:exactMatch
    : interchangeable meaning (rare, high bar)
  • skos:closeMatch
    : near-equivalent, safe default for most interop
  • skos:broadMatch
    / 
    skos:narrowMatch
    : granularity mismatch
  • skos:relatedMatch
    : associative cross-scheme link
仅在跨方案时使用映射属性，同一方案内不使用：
  • skos:exactMatch
    ：语义完全等价（罕见，要求严格）
  • skos:closeMatch
    ：语义近似，为大多数互操作场景的安全默认
  • skos:broadMatch
    / 
    skos:narrowMatch
    ：粒度不匹配
  • skos:relatedMatch
    ：跨方案关联链接

Internal Cross-Scheme Example (Workload -> Existing Docs Scheme)

内部跨方案示例（工作负载 -> 现有文档方案）

turtle
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .
@prefix jcd: <jc:> .

jcw:concept:build skos:closeMatch jcd:docs:programming .
jcw:concept:observe skos:broadMatch jcd:docs:operations .
jcw:concept:knowledge skos:relatedMatch jcd:docs:education .
Mapping guardrails:
  1. Start with 
    closeMatch
    ; escalate to 
    exactMatch
    only with explicit review.
  2. Do not chain 
    exactMatch
    blindly across multiple schemes.
  3. Review inferred collisions caused by transitive/symmetric mapping behavior.
turtle
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .
@prefix jcd: <jc:> .

jcw:concept:build skos:closeMatch jcd:docs:programming .
jcw:concept:observe skos:broadMatch jcd:docs:operations .
jcw:concept:knowledge skos:relatedMatch jcd:docs:education .
映射准则：
  1. 从
    closeMatch
    开始；仅在经过明确评审后升级为
    exactMatch
    。
  2. 不要盲目地在多个方案间链式使用
    exactMatch
    。
  3. 评审由传递/对称映射行为导致的推断冲突。

Collections and Ordered Collections

集合与有序集合

Use collections for non-hierarchical grouping:
  • skos:Collection
    for thematic bundles (example: all communication channels)
  • skos:OrderedCollection
    for deterministic sequences (example: escalation stages)
Do not encode hierarchy with collections. Use 
broader
/
narrower
for taxonomy structure.
turtle
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .

jcw:collection:comms-channels a skos:Collection ;
  skos:prefLabel "Comms channels"@en ;
  skos:member
    jcw:concept:comms:telegram,
    jcw:concept:comms:slack,
    jcw:concept:comms:imessage .
使用集合进行非层级分组：
  • skos:Collection
    用于主题分组（示例：所有通信渠道）
  • skos:OrderedCollection
    用于确定性序列（示例：升级阶段）
不要用集合编码层级结构。使用
broader
/
narrower
构建分类体系结构。
turtle
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .

jcw:collection:comms-channels a skos:Collection ;
  skos:prefLabel "Comms channels"@en ;
  skos:member
    jcw:concept:comms:telegram,
    jcw:concept:comms:slack,
    jcw:concept:comms:imessage .

URI and Notation Policy (
joelclaw:
)

URI与标识规范（
joelclaw:
）

  1. URI local parts are lowercase kebab or colon-separated operational paths.
  2. skos:notation
    is immutable once released.
  3. Never repurpose a concept URI. Deprecate old URI and add mappings.
  4. Keep human names in labels, not in IDs.
  5. Encode scheme version in scheme URI and metadata, not in every concept URI unless required.
Recommended patterns:
  • joelclaw:scheme:workload:v1
  • joelclaw:concept:observe:otel
  • joelclaw:collection:agent-lifecycle
  • joelclaw:label:meta:adr
  1. URI本地部分使用小写短横线分隔或冒号分隔的可执行路径。
  2. skos:notation
    一经发布即不可变。
  3. 绝不要复用概念URI。废弃旧URI并添加映射。
  4. 标签中使用人类可读名称，而非ID中。
  5. 将方案版本编码至方案URI及元数据中，除非必要，不要在每个概念URI中添加版本。
推荐格式：
  • joelclaw:scheme:workload:v1
  • joelclaw:concept:observe:otel
  • joelclaw:collection:agent-lifecycle
  • joelclaw:label:meta:adr

Typesense Integration Contract

Typesense集成规范

Treat SKOS as source-of-truth semantics and Typesense as retrieval runtime.
将SKOS视为语义事实来源，将Typesense视为检索运行时。

Field Mapping

字段映射

SKOSTypesense fieldTypeNotes
Concept URI
id
string
Canonical identifier
skos:inScheme
scheme_id
string
facet		Filter by scheme/version
skos:notation
notation
string
facet		Operational code lookups
skos:prefLabel
pref_label
string
Primary lexical form
skos:altLabel
alt_labels
string[]
Alias lookup/query expansion
skos:hiddenLabel
hidden_labels
string[]
Misspelling/legacy term recovery
skos:definition
definition
string
Long-form semantic context
skos:scopeNote
scope_note
string
Disambiguation guidance
skos:broader
broader_ids
string[]
facet		Direct parents
skos:narrower
narrower_ids
string[]
facet		Direct children
skos:related
related_ids
string[]
facet		Lateral associations
Mapping props
exact_match_ids
, 
close_match_ids
, etc.
string[]
Cross-scheme links
Version/governance
taxonomy_version
, 
state
string
facet		Rollout control
For retrievable entities (docs, memory, events), also persist:
  • primary_concept_id
  • concept_ids
    (
    string[]
    , faceted)
  • concept_source
  • taxonomy_version
  • context_prefix
    , 
    source_entity_id
    , 
    evidence_tier
    , 
    parent_evidence_id
    (where applicable)
SKOSTypesense字段类型说明
概念URI
id
string
标准标识符
skos:inScheme
scheme_id
string
分面		按方案/版本过滤
skos:notation
notation
string
分面		可执行代码查询
skos:prefLabel
pref_label
string
主要词法形式
skos:altLabel
alt_labels
string[]
别名查询/扩展
skos:hiddenLabel
hidden_labels
string[]
拼写错误/遗留术语恢复
skos:definition
definition
string
长文本语义上下文
skos:scopeNote
scope_note
string
消歧指南
skos:broader
broader_ids
string[]
分面		直接父概念
skos:narrower
narrower_ids
string[]
分面		直接子概念
skos:related
related_ids
string[]
分面		横向关联
映射属性
exact_match_ids
, 
close_match_ids
等
string[]
跨方案链接
版本/治理
taxonomy_version
, 
state
string
分面		发布管控
对于可检索实体（文档、记忆、事件），还需存储：
  • primary_concept_id
  • concept_ids
    （
    string[]
    ，分面）
  • concept_source
  • taxonomy_version
  • context_prefix
    , 
    source_entity_id
    , 
    evidence_tier
    , 
    parent_evidence_id
    （如有）

Query Patterns

查询模式

Classification candidate lookup:
bash
curl -s "http://localhost:8108/collections/taxonomy_concepts/documents/search?q=ingest+pipeline&query_by=pref_label,alt_labels,scope_note,definition&per_page=10" \
  -H "X-TYPESENSE-API-KEY: panda-typesense-key"
Concept-constrained retrieval:
bash
curl -s "http://localhost:8108/collections/documents/documents/search?q=*&query_by=content&filter_by=concept_ids:=[joelclaw:concept:pipeline] && taxonomy_version:=workload-v1&per_page=20" \
  -H "X-TYPESENSE-API-KEY: panda-typesense-key"
Operational notes:
  1. Use 
    q=*
    when filtering/faceting without lexical query terms.
  2. Keep concept fields faceted for fast filters and diagnostics.
  3. Synonyms operate on 
    q
    tokens, not 
    filter_by
    values; concept IDs must be canonical.
  4. For transitive hierarchy retrieval, precompute ancestor closures into a dedicated field (example: 
    ancestor_concept_ids
    ).
分类候选查询：
bash
curl -s "http://localhost:8108/collections/taxonomy_concepts/documents/search?q=ingest+pipeline&query_by=pref_label,alt_labels,scope_note,definition&per_page=10" \
  -H "X-TYPESENSE-API-KEY: panda-typesense-key"
概念约束检索：
bash
curl -s "http://localhost:8108/collections/documents/documents/search?q=*&query_by=content&filter_by=concept_ids:=[joelclaw:concept:pipeline] && taxonomy_version:=workload-v1&per_page=20" \
  -H "X-TYPESENSE-API-KEY: panda-typesense-key"
操作说明：
  1. 当仅需过滤/分面无需词法查询时，使用
    q=*
    。
  2. 将概念字段设为分面以实现快速过滤和诊断。
  3. 同义词仅作用于
    q
    令牌，不作用于
    filter_by
    值；概念ID必须为标准格式。
  4. 对于传递性层级检索，预计算祖先闭包并存储至专用字段（示例：
    ancestor_concept_ids
    ）。

Local Access Troubleshooting

本地访问故障排查

If 
localhost:8108
is unreachable, port-forward first:
bash
kubectl port-forward -n joelclaw svc/typesense 8108:8108
若无法访问
localhost:8108
，请先进行端口转发：
bash
kubectl port-forward -n joelclaw svc/typesense 8108:8108

Quality Gates and Validation

质量门禁与验证

Run these checks before shipping taxonomy changes:
  1. Label integrity:
    • one 
      prefLabel
      per language per concept
    • no overlap among pref/alt/hidden labels
  2. Structural integrity:
    • every concept in exactly one expected scheme (or explicit multi-scheme design)
    • no accidental hierarchy cycles
    • broader
      and 
      narrower
      coherence
  3. Mapping integrity:
    • mapping links only target external scheme concepts
    • exactMatch
      reviewed and justified
  4. Runtime integrity: 
    • concept_ids
      coverage target met (>=95% for new records)
    • unmapped labels observable in OTEL
Recommended operational probes:
  • joelclaw otel search "concept_ids|primary_concept_id|taxonomy_version" --hours 24
  • joelclaw recall "<query>" --category <mapped-category>
  • joelclaw docs search "<query>" --concept <concept-uri>
在发布分类体系变更前，执行以下检查：
  1. 标签完整性：
    • 每个概念每种语言仅一个
      prefLabel
    • pref/alt/hidden标签无重叠
  2. 结构完整性：
    • 每个概念仅属于一个预期方案（或明确的多方案设计）
    • 无意外的层级循环
    • broader
      与
      narrower
      保持一致
  3. 映射完整性：
    • 映射链接仅指向外部方案概念
    • exactMatch
      经过评审并具备合理性
  4. 运行时完整性： 
    • concept_ids
      覆盖率达标（新记录≥95%）
    • 未匹配标签可在OTEL中观测
推荐操作探针：
  • joelclaw otel search "concept_ids|primary_concept_id|taxonomy_version" --hours 24
  • joelclaw recall "<query>" --category <mapped-category>
  • joelclaw docs search "<query>" --concept <concept-uri>

Governance Workflow

治理工作流

  1. Propose concept as 
    candidate
    with 
    scopeNote
    , not canonical.
  2. Check collisions against existing labels and aliases.
  3. Validate impact on classifier rules and retrieval filters.
  4. Promote to 
    canonical
    only after review and observed usage.
  5. Deprecate by state transition + mapping hints, never by URI reuse.
  6. Version changes explicitly (
    workload-v1
    -> 
    workload-v2
    ) with migration notes.
  1. 以
    candidate
    状态提交概念提案，附带
    scopeNote
    ，暂不设为标准概念。
  2. 检查与现有标签及别名的冲突。
  3. 验证对分类器规则及检索过滤器的影响。
  4. 仅在经过评审并观测使用情况后，升级为
    canonical
    标准概念。
  5. 通过状态转换+映射提示进行废弃，绝不复用URI。
  6. 明确版本变更（
    workload-v1
    -> 
    workload-v2
    ）并附带迁移说明。

Anti-Patterns

反模式

Do not do these:
  1. "Tag soup" growth: free-form tags affecting retrieval without concept mapping.
  2. Using 
    exactMatch
    as a convenience synonym.
  3. Treating collection membership as hierarchy.
  4. Building deep trees without retrieval use-cases.
  5. Skipping 
    scopeNote
    then trying to fix ambiguity downstream with prompts only.
请勿执行以下操作：
  1. "标签混乱"蔓延：使用自由格式标签影响检索却未进行概念映射。
  2. 将
    exactMatch
    作为便捷同义词使用。
  3. 将集合成员关系视为层级结构。
  4. 在无检索场景需求的情况下构建深层树状结构。
  5. 跳过
    scopeNote
    仅通过提示词下游解决歧义。

When SKOS Is Overkill

何时SKOS过于复杂

Use a simpler tagging/enum model when all are true:
  1. Fewer than ~30 stable labels.
  2. No hierarchy/mapping requirements.
  3. No multilingual or alias governance needs.
  4. Labels are not reused across systems.
  5. Retrieval quality does not depend on concept semantics.
If any of those stop being true, migrate to SKOS before scaling.
当以下条件全部满足时，使用更简单的标签/枚举模型：
  1. 稳定标签数量少于约30个。
  2. 无层级/映射需求。
  3. 无需多语言或别名治理。
  4. 标签无需跨系统复用。
  5. 检索质量不依赖概念语义。
若上述任一条件不再满足，在规模扩大前迁移至SKOS。

Research-Derived Operational Guidance

基于研究的操作指南

Use SKOS metadata to improve retrieval quality in agent pipelines:
  1. Metadata-aware retrieval pipelines can materially improve multi-hop QA accuracy (for example, reported F1/EM gains in Multi-Meta-RAG benchmarks).
  2. Controlled vocabularies plus free text generally improve precision/recall versus text-only querying in domain IR studies.
  3. Practical implication for joelclaw: always combine lexical/vector retrieval with concept filtering or re-ranking signals when classification confidence is high.
使用SKOS元数据提升Agent工作流中的检索质量：
  1. 元数据感知的检索流水线可显著提升多跳QA的准确率（例如，Multi-Meta-RAG基准测试中报告的F1/EM指标提升）。
  2. 受控词汇表结合自由文本通常比纯文本查询的精准率/召回率更高（领域信息检索研究结论）。
  3. 对joelclaw的实际指导：当分类置信度较高时，始终将词法/向量检索与概念过滤或重排序信号结合使用。

References

参考资料