架构

编译流水线

flowchart LR
    MD["SKILL.md"] --> LLM["Claude"] --> PYD["Pydantic"] --> SEC["Security"] --> RDF["RDF"] --> SHACL["SHACL"]
    SHACL -->|"PASS"| TTL["ontoskill.ttl"] --> EMBED["Embed (opt)"] --> MCP["OntoMCP"] <--> AGENT["Agent"]
    SHACL -->|"FAIL"| FAIL["❌ Block"]

    style MD fill:#6dc9ee,stroke:#2a2a3e,color:#0d0d14
    style LLM fill:#e91e63,stroke:#2a2a3e,color:#f0f0f5
    style PYD fill:#e91e63,stroke:#2a2a3e,color:#f0f0f5
    style SEC fill:#e91e63,stroke:#2a2a3e,color:#f0f0f5
    style RDF fill:#e91e63,stroke:#2a2a3e,color:#f0f0f5
    style EMBED fill:#e91e63,stroke:#2a2a3e,color:#f0f0f5
    style SHACL fill:#e91e63,stroke:#2a2a3e,color:#f0f0f5
    style TTL fill:#9763e1,stroke:#2a2a3e,color:#f0f0f5
    style MCP fill:#92eff4,stroke:#2a2a3e,color:#0d0d14
    style AGENT fill:#6dc9ee,stroke:#2a2a3e,color:#0d0d14
    style FAIL fill:#ff6b6b,stroke:#2a2a3e,color:#f0f0f5

阶段详情

阶段	输入	输出	描述
提取	SKILL.md	ExtractedSkill	LLM 提取结构化知识
安全	ExtractedSkill	ExtractedSkill	正则表达式 + LLM 审查威胁
序列化	ExtractedSkill	RDF Graph	Pydantic → RDF 三元组
验证	RDF Graph	ValidationResult	SHACL 形状检查有效性
写入	RDF Graph	.ttl 文件	带备份的原子写入
嵌入	.ttl 文件	Embeddings	向量嵌入生成（可选，需要 ontocore[embeddings]）

---

内容模型

OntoCore 将 Markdown 转换为三层编译管道。代理消费的最终输出是紧凑的知识节点 — 节树和内容块是提取过程中使用的中间编译产物。

FlatBlock → 节树 → 知识节点

FlatBlock — 每个 Markdown 元素成为类型化块（paragraph、code_block、table 等），带有行范围和内容特定属性。这是解析器的原始平坦提取。

节树 — 块根据标题级别组织为层次结构。每个节有标题、级别、顺序，并包含内容块和子节。树结构使用：

属性	用途
oc:hasSection	将技能链接到其顶级节
oc:hasSubsection	将节链接到其子节
oc:hasContent	将节链接到其内容块
oc:hasChild	将列表条目或步骤链接到嵌套子块
oc:sectionTitle	节标题文本
oc:sectionLevel	标题级别（1-6）
oc:contentOrder	节内的排序

知识节点 — OntoMCP 提供给 LLM 代理的紧凑、即用型输出。编译器不重建原始 Markdown，而是生成结构化的知识节点（启发式、反模式、过程等），代理直接消费这些节点。

在 TTL 输出中，节和内容块表示为带有 rdf:type 断言的空白节点（如 oc:Paragraph、oc:CodeBlock）。这些是中间编译产物 — 代理的主要输出是从内容中提取的知识节点集合。

---

技能类型

flowchart LR
    SKILL["oc:Skill<br/>━━━━━━━━━━<br/>Base class"] --> EXE["oc:ExecutableSkill<br/>━━━━━━━━━━<br/>Has code to run"]
    SKILL --> DEC["oc:DeclarativeSkill<br/>━━━━━━━━━━<br/>Knowledge only"]

    EXE --> PAYLOAD["hasPayload exactly 1<br/>━━━━━━━━━━<br/>oc:code OR oc:executionPath"]
    DEC --> NOPAYLOAD["hasPayload forbidden<br/>━━━━━━━━━━<br/>owl:disjointWith"]

    style SKILL fill:#9763e1,stroke:#2a2a3e,color:#f0f0f5
    style EXE fill:#abf9cc,stroke:#2a2a3e,color:#0d0d14
    style DEC fill:#6dc9ee,stroke:#2a2a3e,color:#0d0d14

分类是自动的 — 你不需要指定它。如果技能有要执行的代码，它就是可执行的。如果它只是知识，它就是声明式的。这些类是互斥的（owl:disjointWith）。

---

OWL 2 属性

flowchart LR
    A["dependsOnSkill<br/>━━━━━━━━━━<br/>AsymmetricProperty<br/>A needs B"] --> UC1["Prerequisites<br/>━━━━━━━━━━<br/>Install before run"]
    B["extends<br/>━━━━━━━━━━<br/>TransitiveProperty<br/>A → B → C"] --> UC2["Inheritance<br/>━━━━━━━━━━<br/>Override behavior"]
    C["contradicts<br/>━━━━━━━━━━<br/>SymmetricProperty<br/>A ↔ B"] --> UC3["Conflicts<br/>━━━━━━━━━━<br/>Mutually exclusive"]
    D["implements<br/>━━━━━━━━━━<br/>Interface<br/>compliance"] --> UC4["Contracts<br/>━━━━━━━━━━<br/>Guaranteed API"]
    E["exemplifies<br/>━━━━━━━━━━<br/>Pattern<br/>demonstration"] --> UC5["Examples<br/>━━━━━━━━━━<br/>Best practices"]

    style A fill:#abf9cc,stroke:#2a2a3e,color:#0d0d14
    style B fill:#abf9cc,stroke:#2a2a3e,color:#0d0d14
    style C fill:#ff6b6b,stroke:#2a2a3e,color:#f0f0f5
    style D fill:#6dc9ee,stroke:#2a2a3e,color:#0d0d14
    style E fill:#92eff4,stroke:#2a2a3e,color:#0d0d14

属性	类型	语义
dependsOnSkill	非对称	A 需要 B，但 B 不需要 A
extends	传递	如果 A 扩展 B 且 B 扩展 C，则 A 扩展 C
contradicts	对称	如果 A 与 B 矛盾，则 B 与 A 矛盾
implements	非自反	A 不能实现自己
exemplifies	非自反	A 不能示例自己

---

验证守门员

每个技能在写入前必须通过 SHACL 验证。宪法形状强制执行：

约束	规则	错误
resolvesIntent	必需（至少 1 个）	技能必须解决至少一个意图
generatedBy	可选（0 或 1 个）	技能的编译溯源证明
requiresState	必须是 IRI	必须是有效的状态 URI
yieldsState	必须是 IRI	必须是有效的状态 URI
handlesFailure	必须是 IRI	必须是有效的状态 URI

---

安全管道

flowchart LR
    INPUT["User Content"] --> NORM["Unicode NFC"]
    NORM --> PATTERNS["Regex Check"]
    PATTERNS --> LLM["LLM Review"]
    LLM --> DECISION{"Safe?"}

    DECISION -->|"Yes"| PASS["✅ Allow"]
    DECISION -->|"No"| BLOCK["❌ Reject"]

    style INPUT fill:#1a1a2e,stroke:#2a2a3e,color:#f0f0f5
    style NORM fill:#6dc9ee,stroke:#2a2a3e,color:#0d0d14
    style PATTERNS fill:#ff6b6b,stroke:#2a2a3e,color:#f0f0f5
    style LLM fill:#9763e1,stroke:#2a2a3e,color:#f0f0f5
    style DECISION fill:#feca57,stroke:#2a2a3e,color:#0d0d14
    style PASS fill:#abf9cc,stroke:#2a2a3e,color:#0d0d14
    style BLOCK fill:#ff6b6b,stroke:#2a2a3e,color:#f0f0f5

检测到的威胁：

• 提示注入（ignore instructions、system:、you are now）
• 命令注入（; rm、| bash、命令替换）
• 数据泄露（curl -d、wget --data）
• 路径遍历（../、/etc/passwd）
• 凭据暴露（api_key=、password=）

---

项目结构

ontoskills/
├── core/                       # OntoCore — Python 技能编译器
│   ├── src/
│   │   ├── cli/                # Click CLI 命令
│   │   │   ├── compile.py      # 编译命令
│   │   │   ├── query.py        # SPARQL 查询命令
│   │   │   └── ...
│   │   ├── config.py           # 配置常量
│   │   ├── core_ontology.py    # 命名空间和 TBox 本体创建
│   │   ├── differ.py           # 语义漂移检测器
│   │   ├── drift_report.py     # 漂移报告生成器
│   │   ├── embeddings/         # 向量嵌入导出
│   │   ├── env.py              # 环境加载
│   │   ├── exceptions.py       # 带退出码的异常层次结构
│   │   ├── explainer.py        # 技能解释生成器
│   │   ├── extractor.py        # ID 和哈希生成
│   │   ├── graph_export.py     # 图格式导出
│   │   ├── linter.py           # 静态本体检查器
│   │   ├── prompts.py          # LLM 提示模板
│   │   ├── registry/           # 商店/包管理
│   │   ├── schemas.py          # Pydantic 模型
│   │   ├── security.py         # 深度防御安全
│   │   ├── serialization.py    # 带 SHACL 守门员的 RDF 序列化
│   │   ├── snapshot.py         # 本体快照
│   │   ├── sparql.py           # SPARQL 查询引擎
│   │   ├── storage.py          # 文件 I/O、合并、孤立清理
│   │   ├── transformer.py      # LLM 工具使用提取
│   │   └── validator.py        # SHACL 验证守门员
│   ├── specs/                  # SHACL 形状宪法
│   └── tests/                  # 测试套件
├── mcp/                        # OntoMCP — Rust MCP 服务器
│   ├── Cargo.toml              # Rust 包清单
│   └── src/
│       ├── main.rs             # MCP stdio 服务器
│       └── ...
├── skills/                     # 输入：SKILL.md 定义（用户创建）
├── ontoskills/                 # 输出：已编译的 .ttl 文件（gitignored 构建产物）
│   └── */ontoskill.ttl         # 单个技能模块
└── site/public/ontology/
    └── core.ttl                # 核心本体（规范副本，在线服务）

任何源技能目录都可以 — 添加一个 SKILL.md 文件，OntoCore 就会将其编译为已验证的本体模块。

运行时模型

OntoMCP 从 ontoskills/ 读取已编译的本体包。它不直接读取原始 SKILL.md 源文件。

面向用户的 ontoskills CLI 负责：

• 安装 ontomcp
• 安装 ontocore
• 将原始源仓库导入到 skills/author/
• 从 OntoStore 或第三方商店安装已编译的包
• 在技能到达 MCP 运行时之前启用和禁用技能

商店模型

OntoStore 作为静态 GitHub 仓库发布，默认内置。

• 官方包在安装后立即可用
• 第三方商店通过 store add-source 显式添加
• 原始源仓库在安装到 ontoskills/author/ 之前在本地编译