@kedge-agentic/ontology

kedge-ccaas 的 schema + 治理契约层 — 框架无关。

类型: 框架无关库 · 状态: public · v0.1.0

用途

定义 ccaas 平台的 ontology 原语 — 让 agent 知道"世界上有什么 / 此刻能动什么 / 谁能做什么":

• ObjectTypeDef — 业务对象的语义层 (Lesson, Student, ClassroomSession ...)
• ManifestDef — 此时此刻的运行时操作空间 (slots / state / streams / boundaries)
• ActionDef — Agent 可调用的工具,带 Zod schema + 治理标签
• AccessBoundary — 谁(role)能读/写/调什么
• OntologyRegistry — 注册 + 校验 + 封存
• 语义投影 — 给 LLM agent 看 (Anthropic Tools / MCP Tools / System Prompt 三种格式)

Zod-first: 字段形状住在 Zod schema 里 (source of truth), PropertyMeta 旁车只载 Zod 表达不了的治理 + 展示 hints。

零 NestJS 耦合。 NestJS 适配在 @kedge-agentic/ontology-nest。 完整规格: docs/ontology/kedge-ontology-design.md。

主要导出

// 推荐 subpath import
import { ObjectTypeDef } from '@kedge-agentic/ontology/schema'
import { ManifestDef, defineManifest, defineStateField } from '@kedge-agentic/ontology/manifest'
import { OntologyRegistry } from '@kedge-agentic/ontology/registry'
import { defineObjectType, defineAction } from '@kedge-agentic/ontology/helpers'
import { projectManifest } from '@kedge-agentic/ontology/semantic'

也可从根入口 from '@kedge-agentic/ontology' 一并 import (历史 barrel)。

用法

const LessonType = defineObjectType({
  apiName: 'Lesson',
  displayName: '课程',
  semantic: '一个完整的课时计划',
  schema: z.object({
    id: z.string(),
    title: z.string(),
  }),
  links: [],
  actions: [],
})

const LessonSessionManifest = defineManifest({
  name: 'LessonSession',
  slots: [
    { apiName: 'plan', target: { kind: 'objectType', apiName: 'Lesson' } },
  ],
  state: [
    defineStateField({
      apiName: 'phase',
      schema: z.enum(['waiting', 'active', 'ended']),
      initial: 'waiting',
    }),
  ],
  boundaries: [
    { role: 'agent', readable: ['plan', 'phase'], writable: ['phase'], actions: [] },
  ],
})

const registry = new OntologyRegistry()
registry.registerObjectType(LessonType)
registry.registerManifest(LessonSessionManifest)
registry.seal()

依赖

• 运行时: zod, zod-to-json-schema
• 无 peerDeps,无框架依赖

关联包

• @kedge-agentic/ontology-nest — NestJS 适配 (Module + Controller + ManifestAccessor)
• @kedge-agentic/workflow — workflow 引擎,通过 ontology 描述 trigger

构建 / 测试

npm run build:ontology
npm test -w @kedge-agentic/ontology

现状参考

实施进度: docs/ontology/PROGRESS.md — Phase 1-5 已落地,Phase 5b Tier 3 延后 (per-item gating)。