skos-taxonomy

Name: skos-taxonomy
Author: joelhooks

github.com/joelhooks数据与数据库6536 次安装1 天前更新

代码仓库

关于 skos-taxonomy

skos-taxonomy 是一项面向 Agent 工作分类与检索的 SKOS 操作规范技能，适用于设计分类体系、制定分类规则并接入 Typesense 的团队。它涵盖概念治理、数据校验和检索字段约定。

主要功能

01设计版本化 SKOS 概念方案
02规定 Agent 分类元数据
03映射概念字段至 Typesense
04校验标签、层级与映射约束
05管理概念候选、弃用和版本

适用场景

01为 Agent 任务建立受控分类体系
02统一不同 Agent 的分类元数据
03将概念字段用于 Typesense 检索
04审查词表映射与概念变更

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/joelhooks/joelclaw --skill skos-taxonomy

安装后在 Claude Code 中输入/skos-taxonomy确认已加载。

详细介绍

SKOS 分类专家

使用 SKOS 设计可执行分类体系，让 Panda 和所有子 Agent 对工作进行一致分类、更好地检索上下文，并避免标签混乱。

这项技能用于执行，而非理论：定义概念、对 Agent 数据分类、验证约束，并将分类体系字段接入 Typesense。

适用场景

在以下请求涉及相关内容时使用这项技能：

“taxonomy”“SKOS”“controlled vocabulary”“concept scheme”
对 Agent 交互、运行、文档、记忆、事件或任务进行分类
设计或修订 concept_ids / primary_concept_id 契约
将 joelclaw 概念映射到其他词表
判断是否需要 SKOS，还是更简单的标签模型就足够

主要成果

具有稳定概念 URI 的版本化 SKOS 概念体系。
可生成确定性概念元数据的 Agent 分类规则。
支持词法、分面和混合检索的 Typesense 字段映射。
管理候选概念、别名漂移、弃用和映射的治理规则。

不可妥协的 SKOS 规则（规范性）

在每个概念体系中遵循以下规则：

skos:Concept 和 skos:ConceptScheme 是不同的类。
skos:broader 不是传递关系；对于闭包查询，请使用传递超属性语义（skos:broaderTransitive）。
对于一个资源，每种语言标签最多只能有一个 skos:prefLabel 值。
对于相同资源和语言形式，skos:prefLabel、skos:altLabel 和 skos:hiddenLabel 两两互斥。
skos:related 与 skos:broaderTransitive 互斥。
映射关系用于跨概念体系链接。skos:exactMatch 具有传递性，应谨慎使用。
skos:closeMatch 有意设为非传递关系。
skos:Collection / skos:OrderedCollection 用于分组；它们与 skos:Concept 互斥。

如果违反任何一条规则，请暂停并在上线前修复数据。

JoelClaw 可执行概念体系（工作负载 v1）

为工作负载分类定义专用概念体系：

概念体系 URI：joelclaw:scheme:workload:v1
分类体系版本字符串：workload-v1
概念 URI 模式：joelclaw:concept:<top-level>[:<subconcept>]
表示法风格：大写蛇形命名或点分隔的操作代码（稳定且不可变）

顶层概念（必需）

表示法	URI	用途
`PLATFORM`	`joelclaw:concept:platform`	运行时/平台基础设施与托管底层
`INTEGRATION`	`joelclaw:concept:integration`	外部系统连接、API、webhook、适配器
`TOOLING`	`joelclaw:concept:tooling`	CLI/开发工具、运维命令、本地自动化
`PIPELINE`	`joelclaw:concept:pipeline`	Inngest/事件工作流、摄取与处理链
`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、政策、生命周期和流程控制

核心 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 分类契约

每个可存储/检索的子 Agent 输出都必须包含：

primary_concept_id（单个规范概念 URI）
concept_ids（有序列表：主概念在前，其次为次级概念）
taxonomy_version
concept_source（rules|llm|backfill|manual|fallback）
classification_confidence（0–1 浮点数，可选但建议提供）

建议的信封格式：

{
  "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
}

分类流程

规范化候选标签（trim、转为小写、生成 slug、合并标点）。
依次匹配 prefLabel、altLabel 和 hiddenLabel 别名表。
使用 scopeNote 和相邻概念（broader、related）进行消歧。
输出一个主要概念，以及可选的次要概念。
如果仍无法确定，则映射到受控的回退概念，并记录未映射标签。
输出用于映射诊断的 OTEL 元数据（mapped_count、unmapped_count、taxonomy_version）。

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

仅当标签对象需要元数据或关系时才使用 SKOS-XL：

带来源信息的首字母缩略词／缩写管理
单个标签的来源归属
带标签级审计的多语言／音译工作流
标签之间的关系（弃用术语 -> 替代术语）

如果标签只是普通同义词，请使用核心 SKOS 标签。

SKOS-XL 示例

@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 .

映射到外部词汇表

跨方案使用映射属性，而不要在单个方案内部使用：

skos:exactMatch：含义可互换（少见，要求严格）
skos:closeMatch：近似等价，是大多数互操作场景的安全默认选择
skos:broadMatch / skos:narrowMatch：粒度不匹配
skos:relatedMatch：跨方案的关联链接

内部跨方案示例（Workload -> Existing Docs Scheme）

@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 .

映射准则：

从 closeMatch 开始；只有经过明确审核后，才升级为 exactMatch。
不要盲目地跨多个方案串联 exactMatch。
审查由传递／对称映射行为导致的推断冲突。

集合与有序集合

使用集合进行非层级分组：

skos:Collection 用于主题分组（例如：所有通信渠道）
skos:OrderedCollection 用于确定性序列（例如：升级阶段）

不要用集合表示层级。请使用 broader／narrower 表示分类体系结构。

@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 和记法策略（`joelclaw:`）

URI 局部部分使用小写 kebab 格式或以冒号分隔的操作路径。
skos:notation 发布后不可更改。
永远不要重新指定概念 URI 的用途。弃用旧 URI 并添加映射。
人类可读的名称应放在标签中，而不是 ID 中。
除非有要求，否则应在方案 URI 和元数据中编码方案版本，而不是在每个概念 URI 中编码。

推荐模式：

joelclaw:scheme:workload:v1
joelclaw:concept:observe:otel
joelclaw:collection:agent-lifecycle
joelclaw:label:meta:adr

Typesense 集成约定

将 SKOS 视为语义的事实来源，将 Typesense 视为检索运行时。

字段映射

SKOS	Typesense 字段	类型	说明
概念 URI	`id`	`string`	规范标识符
`skos:inScheme`	`scheme_id`	`string` facet	按方案／版本筛选
`skos:notation`	`notation`	`string` facet	操作代码查询
`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[]` facet	直接上级
`skos:narrower`	`narrower_ids`	`string[]` facet	直接下级
`skos:related`	`related_ids`	`string[]` facet	横向关联
映射属性	`exact_match_ids`、`close_match_ids` 等	`string[]`	跨方案链接
版本／治理	`taxonomy_version`、`state`	`string` facet	发布控制

对于可检索实体（文档、记忆、事件），还应持久化：

primary_concept_id
concept_ids（string[]，可分面）
concept_source
taxonomy_version
context_prefix、source_entity_id、evidence_tier、parent_evidence_id（如适用）

查询模式

分类候选项查找：

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"

概念约束检索：

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"

运维说明：

不含词法查询词、仅进行筛选或分面查询时，使用 q=*。
保留概念字段的分面功能，以便快速筛选和诊断。
同义词作用于 q 中的词元，而非 filter_by 值；概念 ID 必须规范化。
对于传递层级检索，将祖先闭包预先计算到专用字段中（例如 ancestor_concept_ids）。

本地访问故障排查

如果无法访问 localhost:8108，请先进行端口转发：

kubectl port-forward -n joelclaw svc/typesense 8108:8108

质量门禁与验证

发布分类体系变更前，请运行以下检查：

标签完整性：
- 每个概念的每种语言只有一个 prefLabel
- prefLabel、altLabel 和 hiddenLabel 之间没有重叠
结构完整性：
- 每个概念恰好属于一个预期的方案（或采用明确的多方案设计）
- 没有意外的层级循环
- broader 和 narrower 保持一致
映射完整性：
- 映射链接仅指向外部方案中的概念
- exactMatch 经过审核且有充分依据
运行时完整性：
- 达到 concept_ids 覆盖率目标（新记录 >=95%）
- OTEL 中可观测到未映射的标签

推荐的运维探测：

joelclaw otel search "concept_ids|primary_concept_id|taxonomy_version" --hours 24
对于广泛的 Brain/观察检索，使用 joelclaw recall "<query>"；已弃用的记忆类别分类体系不再筛选 recall 投影
joelclaw docs search "<query>" --concept <concept-uri>

治理工作流

将概念以 candidate 状态提出，并填写 scopeNote，不要将其设为规范概念。
检查与现有标签和别名是否冲突。
验证对分类器规则和检索筛选的影响。
经过审核并观察到实际使用后，才将其提升为 canonical。
弃用时应变更状态并添加映射提示，绝不能重复使用 URI。
明确标注版本变更（workload-v1 -> workload-v2），并附上迁移说明。

反模式

请勿采取以下做法：

让“标签杂烩”不断膨胀：自由格式标签在未映射到概念的情况下影响检索。
为了方便而使用 exactMatch 作为同义词。
将集合成员关系视为层级关系。
在没有检索用例的情况下构建深层树。
跳过 scopeNote，之后再试图只用提示词解决下游歧义。

何时 SKOS 属于过度设计

以下条件全部满足时，使用更简单的标签/枚举模型：

稳定标签少于约 30 个。
没有层级或映射要求。
无需多语言或别名治理。
标签不会在不同系统间复用。
检索质量不依赖概念语义。

如果上述任一条件不再成立，请在扩展之前迁移到 SKOS。

基于研究的运维指南

使用 SKOS 元数据提升 Agent 工作流中的检索质量：

元数据感知型检索工作流可显著提升多跳问答准确率（例如，Multi-Meta-RAG 基准测试中报告的 F1/EM 提升）。
域内 IR 研究通常表明，相比仅进行文本查询，受控词表结合自由文本能提高精确率和召回率。
对 joelclaw 的实际建议：当分类置信度较高时，始终将词法/向量检索与概念筛选或重排序信号结合起来。

参考资料

W3C SKOS 主页：https://www.w3.org/2004/02/skos/
W3C SKOS 参考文档（规范性）：https://www.w3.org/TR/skos-reference/
W3C SKOS 入门指南：https://www.w3.org/TR/skos-primer/
W3C SKOS 用例与需求：https://www.w3.org/TR/skos-ucr/
Typesense 集合 API：https://typesense.org/docs/30.1/api/collections.html
Typesense 搜索 API：https://typesense.org/docs/30.1/api/search.html
Typesense 向量搜索：https://typesense.org/docs/30.1/api/vector-search.html
Typesense 同义词：https://typesense.org/docs/30.1/api/synonyms.html
Multi-Meta-RAG（元数据感知 RAG）：https://arxiv.org/abs/2406.13213
受控词表 + 文本查询扩展研究（PubMed）：https://pubmed.ncbi.nlm.nih.gov/21893678/
受控词表 + 文本混合检索研究（PubMed）：https://pubmed.ncbi.nlm.nih.gov/23459623/

支持 Markdown

登录后评论

基本信息

作者: joelhooks
仓库: joelhooks/joelclaw
分类: 数据与数据库
安装次数: 36
GitHub Stars: 65

报告问题

skos-taxonomy

关于 skos-taxonomy

主要功能

适用场景

安装

详细介绍

SKOS 分类专家

适用场景

主要成果

不可妥协的 SKOS 规则（规范性）

JoelClaw 可执行概念体系（工作负载 v1）

顶层概念（必需）

核心 Turtle 框架

Agent 分类契约

分类流程

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

SKOS-XL 示例

映射到外部词汇表

内部跨方案示例（Workload -> Existing Docs Scheme）

集合与有序集合

URI 和记法策略（joelclaw:）

Typesense 集成约定

字段映射

查询模式

本地访问故障排查

质量门禁与验证

治理工作流

反模式

何时 SKOS 属于过度设计

基于研究的运维指南

参考资料

评论

URI 和记法策略（`joelclaw:`）