@shgroup/dsh-serenity-hooks 1.56.2 → 1.56.3

package/lib/ontology/engine.d.ts

@@ -94,7 +94,53 @@ interface OntologyDefinition {
     types?: Record<string, TypeDef>;
     relations?: Record<string, RelationDef>;
     axioms?: AxiomDef[];
+    /** 个体（`a <本文件已声明的类>`）。图要画它们，故收进模型（2026-10-13 S142）。 */
+    instances?: InstanceDef[];
 }
+/**
+ * 一个个体：`:trapFalseGreen a :KnownTrap ; sr:trapName "…"`。
+ *
+ * 🔴 **判据刻意是"`a` 指向的类是【本文件已声明的类】**"，不是"任何非 owl:* 的东西" ——
+ *    后者会把 `rdfs:domain :A`、`sr:imports`、甚至**外部实体**全误认成个体
+ *    （viz 侧实测：`dsh-serenity-plugin-development/skill.ttl` 有 13 个真个体，
+ *    而宽松判据会捞回一堆假货）。
+ *
+ * 标签取用顺序（`label` 一个字段，兼容既有 `description`）：
+ * `rdfs:label` → `sr:trapName` / `sr:name` → **第一条字面量谓语**（如 `sr:signature`）。
+ * 最后那条是 2026-10-13 加的：实测 `:KnownTrap` 的 7 个个体**既无 `rdfs:label` 也无 `sr:name`**，
+ * 只有 `sr:trapName`／`sr:signature` ⇒ 不兜底的话图上 7 个方块全是裸 id。
+ */
+interface InstanceDef {
+    id: string;
+    ofClass: string;
+    label?: string;
+}
+type TkKind = "qname" | "iri" | "a" | "literal" | "number" | "boolean" | "prefix" | "base" | "dot" | "semi" | "comma" | "lbracket" | "rbracket" | "lparen" | "rparen" | "eof";
+interface Tk {
+    kind: TkKind;
+    value: string;
+    pos: number;
+    datatype?: string;
+    lang?: string;
+}
+declare function tokenizeTurtle(input: string): {
+    tokens: Tk[];
+    errors: string[];
+};
+interface Triple {
+    subject: string;
+    predicate: string;
+    object: string | number | boolean;
+    objectType: "iri" | "literal" | "blank";
+    objectDatatype?: string;
+}
+interface TurtleParseResult {
+    prefixes: Map<string, string>;
+    triples: Triple[];
+    errors: string[];
+}
+declare function parseTurtle(raw: string): TurtleParseResult;
+declare function turtleToOnto(r: TurtleParseResult): OntologyDefinition;
 type ExprNode = PropAccessNode | LiteralNode | FuncCallNode | QuantifierNode | BinaryOpNode | UnaryOpNode | ImplicationNode | ParensNode;
 interface PropAccessNode {
     kind: "propAccess";
@@ -145,6 +191,11 @@ interface ParensNode {
     expr: ExprNode;
     pos: number;
 }
+declare function loadOntoFile(filePath: string): {
+    onto: OntologyDefinition;
+    raw: string;
+};
+declare function loadOntoFileWithImports(filePath: string, visited?: Set<string>): OntologyDefinition;
 interface CheckIssue {
     check: string;
     severity: "error" | "warning";
@@ -173,4 +224,4 @@ export interface OntologyRunResult {
  * 以及把 `code !== 0` 翻成响亮的回执（引擎的 stderr 文案**逐字保留**，不重写）。
  */
 export declare function runOntologyCli(argv: string[], opts?: OntologyRunOptions): OntologyRunResult;
-export { MsmError, validateOnto, type OntologyDefinition, type CheckIssue, type ExprNode };
+export { MsmError, validateOnto, tokenizeTurtle, parseTurtle, turtleToOnto, loadOntoFile, loadOntoFileWithImports, type OntologyDefinition, type CheckIssue, type ExprNode, type TypeDef, type RelationDef, type AxiomDef, type InstanceDef, type PropertyDef };

package/lib/ontology/viz.d.ts

@@ -0,0 +1,138 @@
+interface OntoModel {
+    file: string;
+    prefixes: Map<string, string>;
+    base: string | null;
+    /** 本体自身元信息 */
+    meta: {
+        label?: string;
+        comment?: string;
+        version?: string;
+        imports: string[];
+    };
+    classes: ClassDef[];
+    relations: RelationDef[];
+    axioms: AxiomDef[];
+    instances: InstanceDef[];
+    /** 没认出来的主语 a 类型（fail-loud 计数） */
+    unknownTypes: string[];
+}
+interface ClassDef {
+    id: string;
+    label: string;
+    comment: string;
+    rigidity: "rigid" | "anti-rigid" | "semi-rigid" | null;
+    identity: string[];
+    properties: {
+        name: string;
+        type: string;
+        cardinality: string;
+    }[];
+    parents: string[];
+}
+interface RelationDef {
+    id: string;
+    label: string;
+    comment: string;
+    domain: string | null;
+    range: string | null;
+    cardinality: string;
+    isObject: boolean;
+}
+interface AxiomDef {
+    id: string;
+    rule: string;
+    type: string;
+    comment: string;
+    /** 规则文本里提到、且**本文件确实声明了**的类型名（用于连边） */
+    mentions: string[];
+}
+interface InstanceDef {
+    id: string;
+    ofClass: string | null;
+    label: string;
+}
+/**
+ * `OntoModel` 的**唯一来源 = 引擎的解析器**（2026-10-13 S142）。
+ *
+ * 🔴 这里**不解析任何 Turtle** —— 只把引擎的 `OntologyDefinition` **翻译**成本文件的
+ *    渲染模型。原 viz 自带的手写解析器已整块删除：它实测错三类
+ *    （只认具名式公理 ⇒ 8/16 文件公理数归零；`sr:identity` 只认括号形 ⇒ 18 处假阳；
+ *     从不读 `sr:description` ⇒ 公理正文丢失）。引擎两种写法都认 ⇒ 三类**自动消失**。
+ *
+ * 需引擎侧先满足两件事（已随 82e740f 落地）：导出 `loadOntoFile`／类型；模型收 `instances`。
+ */
+declare function fromEngine(file: string, absPath: string): OntoModel;
+interface Box {
+    id: string;
+    kind: "class" | "relation" | "axiom" | "import" | "instance" | "self";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    title: string;
+    lines: string[];
+    fill: string;
+}
+interface Edge {
+    from: string;
+    to: string;
+    label: string;
+    kind: "relation" | "axiom" | "instance" | "import";
+    /** 该边**竖直通道**的 x（由布局分配，逐条错开 —— 否则同源多边会叠在一条线上） */
+    channelX?: number;
+    /** 标签落点（放在**进入目标的那段水平线**上方 ⇒ 每条边落点不同，不互相压） */
+    labelAt?: [number, number];
+    /** 该边是否绕行（右→左或跨多列）：发射器据此走上方弧线 */
+    detour?: boolean;
+}
+interface Layout {
+    boxes: Box[];
+    edges: Edge[];
+    width: number;
+    height: number;
+    notes: string[];
+}
+declare function layout(model: OntoModel, opts: {
+    axioms: boolean;
+    instances: boolean;
+    imports: boolean;
+}): Layout;
+/**
+ * 纯文本版（**任何通道都能看** —— 不依赖图像输入、不依赖浏览器）。
+ *
+ * 🔴 为什么必要：本模型的当前路由**未声明图像输入**，`diagram` 出的 PNG 贴不进对话
+ * （工具会降级落盘）。没有这个视图，我就只能让 owner 去开文件 —— 那等于没"给他看效果"。
+ * 形态 = **按带分组的方框清单 ＋ 关系列表**（XML 树状），保留结构信息、丢掉空间信息。
+ */
+declare function toText(model: OntoModel, L: Layout, opts: {
+    axioms: boolean;
+}): string;
+/**
+ * **DOT（Graphviz）** —— 机械生成的**严谨**通路（推荐）。
+ *
+ * ## 为什么把布局交给 Graphviz
+ * 手写的分层布局能满足"不重叠"，但**边绕行 / 标签避让 / 交叉最小化**是图布局的成熟难题，
+ * Graphviz 的 `dot` 引擎专做这件事（分层 DAG、`splines=ortho` 正交走线、自动避让节点）。
+ * 我们的职责于是收缩成一件事：**把本体忠实地翻译成 DOT**（节点/边/分组/样式），
+ * 布局交给引擎 —— 这正是"机械生成 + 可读性好"的正解。
+ *
+ * ## 输出约束（**只出确定性的东西**）
+ * - 节点 id 用**下标**（`n0`/`n1`…）而不是本体名 —— 本体名里有 `:`、`.`、`/`，
+ *   直接当 DOT id 需要转义且容易踩坑；真实名字放进 `label`。
+ * - 每条语句顺序固定 ⇒ 同一份 `.ttl` **永远出同一份 DOT**（判据 S↑）。
+ * - 不写 `pos=`（那是引擎的输出，不是输入）⇒ 可重复生成。
+ */
+declare function toDot(model: OntoModel, opts: {
+    axioms: boolean;
+    instances: boolean;
+    imports: boolean;
+}): string;
+declare function toDiagramSource(model: OntoModel, L: Layout, opts: {
+    axioms?: boolean;
+    instances?: boolean;
+}): string;
+declare function toSvg(model: OntoModel, L: Layout, opts: {
+    axioms: boolean;
+}): string;
+declare function toHtml(model: OntoModel, L: Layout, svg: string): string;
+export { fromEngine, layout, toSvg, toHtml, toText, toDot, toDiagramSource, type OntoModel };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shgroup/dsh-serenity-hooks",
-  "version": "1.56.2",
+  "version": "1.56.3",
   "description": "宁静号 ACC harness（Native Cordis 插件）——给 DeepSeek Harness 装一个「AI 工作区」：14 个工具（container_fs/container_trajectory/dashboard/container_git/msm/praxis/ontology/serenity-skill-creator/handyman/localstore/container_admin；另三个 im-bridge/acc-diag/diagram 按配置条件出现）+ 机械约束（安全模式/工作区围墙/密钥守卫/对外输出守卫）+ 工作日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/trajectory 唤醒注册表。适配 DSH 0.1.7-rc.1 与 0.2.0-rc.1（双档）。",
   "license": "MIT",
   "repository": {