@shgroup/dsh-serenity-hooks 1.56.1 → 1.56.3

package/lib/invariant.d.ts

@@ -10,6 +10,29 @@
  * 返回不一致项列表（空 = 通过）。
  */
 export declare function verifyToolConsistency(manifestPath: string, registeredTools: readonly string[]): string[];
+/**
+ * 把「声明面散文」钉成可判（v1.56.2，2026-10-12）。
+ *
+ * 🔴 **为什么需要它**：同一形状的漏改本仓已经犯过**三次** ——
+ *  - v1.31.0 加 `im-bridge`：两个包的 `description` 仍写「10 个工具」且不含它；
+ *  - v1.52.0 加 `ontology`：`package.json` 的 description 仍写「12 个工具」、`dsh.plugin.json`
+ *    的收尾用**位置指代**（"后三个按条件出现"）而被追加项**当场改指**、`README.md` 缺行；
+ *  - **v1.54.0 加 `serenity-skill-creator`**：`package.json` 的 description 仍写「13 个工具」
+ *    （且清单里没有它）、**两份 `README.md` 的 §3.1 标题**仍写「十二个工具」。
+ * v1.52.1 当时写下的判据是「后三处只能靠纪律」—— **本版起改为机械钉**：纪律已被三次证伪。
+ *
+ * 被判的三处（都是**装包的人最先看到的**，也都没有别的钉子）：
+ *  ① `contributes.tools.length === REGISTERED_TOOLS.length`；
+ *  ② **两份** `description` 都含正确的**总数**（`N 个工具`）—— 防"数错"；
+ *  ③ **两份** `description` 都含**每一个**工具名 —— 防"数对了、名单漏了"（v1.54.0 的形态）。
+ * ⚠️ 判据刻意**不要求**工具名出现在特定的逗号分隔段里（散文的排布是人的事，一钉就碎）；
+ *    「后三个按条件出现」这句话由 `CONDITIONAL_TOOL_COUNT` ＋ **顺序约定**保证**永远为真**
+ *    （见 `REGISTERED_TOOLS` 的注释），**不需要**逐句解析。
+ *
+ * @param manifestPath dsh.plugin.json 路径
+ * @param readmePaths   需要一并被判的 README 路径（仓库根 ＋ 包内两份；缺文件即报）
+ */
+export declare function assertManifestProse(manifestPath: string, readmePaths: readonly string[]): string[];
 /**
  * 包级不变量：本插件注册的工具集合（与 dsh.plugin.json contributes.tools 一致）。
  *
@@ -35,4 +58,6 @@ export declare function verifyToolConsistency(manifestPath: string, registeredTo
  * `review`（C 档，调引擎 `compliance`）／`index`（调 P1 的生成器）／`status` ⇒ **14**。
  * 同规格：**条件可见与否不影响这里列它**（本常量 = "插件**具备**的工具面"）。
  */
-export declare const REGISTERED_TOOLS: readonly ["container_fs", "container_trajectory", "dashboard", "container_git", "msm", "praxis", "handyman", "localstore", "container_admin", "im-bridge", "acc-diag", "diagram", "ontology", "serenity-skill-creator"];
+export declare const REGISTERED_TOOLS: readonly ["container_fs", "container_trajectory", "dashboard", "container_git", "msm", "praxis", "ontology", "serenity-skill-creator", "handyman", "localstore", "container_admin", "im-bridge", "acc-diag", "diagram"];
+/** 条件出现的工具数（`REGISTERED_TOOLS` 的**末段**；`assertManifestProse` 用） */
+export declare const CONDITIONAL_TOOL_COUNT = 3;

package/lib/invariant.js

@@ -1,3 +1,4 @@
+import { dirname, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 //#region src/invariant.ts
 /**
@@ -32,6 +33,84 @@ function verifyToolConsistency(manifestPath, registeredTools) {
 	return issues;
 }
 /**
+* 把「声明面散文」钉成可判（v1.56.2，2026-10-12）。
+*
+* 🔴 **为什么需要它**：同一形状的漏改本仓已经犯过**三次** ——
+*  - v1.31.0 加 `im-bridge`：两个包的 `description` 仍写「10 个工具」且不含它；
+*  - v1.52.0 加 `ontology`：`package.json` 的 description 仍写「12 个工具」、`dsh.plugin.json`
+*    的收尾用**位置指代**（"后三个按条件出现"）而被追加项**当场改指**、`README.md` 缺行；
+*  - **v1.54.0 加 `serenity-skill-creator`**：`package.json` 的 description 仍写「13 个工具」
+*    （且清单里没有它）、**两份 `README.md` 的 §3.1 标题**仍写「十二个工具」。
+* v1.52.1 当时写下的判据是「后三处只能靠纪律」—— **本版起改为机械钉**：纪律已被三次证伪。
+*
+* 被判的三处（都是**装包的人最先看到的**，也都没有别的钉子）：
+*  ① `contributes.tools.length === REGISTERED_TOOLS.length`；
+*  ② **两份** `description` 都含正确的**总数**（`N 个工具`）—— 防"数错"；
+*  ③ **两份** `description` 都含**每一个**工具名 —— 防"数对了、名单漏了"（v1.54.0 的形态）。
+* ⚠️ 判据刻意**不要求**工具名出现在特定的逗号分隔段里（散文的排布是人的事，一钉就碎）；
+*    「后三个按条件出现」这句话由 `CONDITIONAL_TOOL_COUNT` ＋ **顺序约定**保证**永远为真**
+*    （见 `REGISTERED_TOOLS` 的注释），**不需要**逐句解析。
+*
+* @param manifestPath dsh.plugin.json 路径
+* @param readmePaths   需要一并被判的 README 路径（仓库根 ＋ 包内两份；缺文件即报）
+*/
+function assertManifestProse(manifestPath, readmePaths) {
+	const manifest = readPluginManifest(manifestPath);
+	if (!manifest) return [`manifest not found or invalid: ${manifestPath}`];
+	const tools = manifest.contributes?.tools ?? [];
+	const n = tools.length;
+	const issues = [];
+	if (n !== REGISTERED_TOOLS.length) issues.push(`contributes.tools 有 ${n} 项，而 REGISTERED_TOOLS 有 ${REGISTERED_TOOLS.length} 项（两侧必须同长）`);
+	const pkgPath = resolve(dirname(manifestPath), "package.json");
+	const surfaces = [];
+	if (existsSync(pkgPath)) try {
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+		surfaces.push({
+			where: "package.json description",
+			text: pkg.description ?? ""
+		});
+	} catch {
+		issues.push(`package.json 无法解析：${pkgPath}`);
+	}
+	else issues.push(`package.json 不存在：${pkgPath}`);
+	surfaces.push({
+		where: "dsh.plugin.json description",
+		text: manifest.description ?? ""
+	});
+	for (const s of surfaces) {
+		if (!s.text.includes(`${n} 个工具`)) issues.push(`${s.where} 未声明工具总数「${n} 个工具」（防"数错"）`);
+		const absent = tools.filter((t) => !s.text.includes(t));
+		if (absent.length) issues.push(`${s.where} 的名单缺 ${absent.length} 项：${absent.join(", ")}（防"数对了、名单漏了"）`);
+	}
+	const cn = [
+		"零",
+		"一",
+		"二",
+		"三",
+		"四",
+		"五",
+		"六",
+		"七",
+		"八",
+		"九",
+		"十"
+	];
+	const countCn = n <= 10 ? cn[n] : n < 20 ? `十${cn[n - 10]}` : `二十${n === 20 ? "" : cn[n - 20]}`;
+	for (const p of readmePaths) {
+		if (!existsSync(p)) {
+			issues.push(`README 不存在：${p}`);
+			continue;
+		}
+		const m = readFileSync(p, "utf-8").match(/^###\s*3\.1\s*(\S+?)个工具/m);
+		if (!m) {
+			issues.push(`${p} 里找不到 §3.1 的「…个工具」标题（形态已变 ⇒ 钉子也要跟着改）`);
+			continue;
+		}
+		if (m[1] !== countCn) issues.push(`${p} 的 §3.1 标题写「${m[1]}个工具」，应为「${countCn}个工具」（工具数已 ${n}）`);
+	}
+	return issues;
+}
+/**
 * 包级不变量：本插件注册的工具集合（与 dsh.plugin.json contributes.tools 一致）。
 *
 * v1.31.1 修正：v1.31.0 新增 `im-bridge`（条件可见）时**漏改此处与清单**——两侧同错 →
@@ -63,14 +142,16 @@ const REGISTERED_TOOLS = [
 	"container_git",
 	"msm",
 	"praxis",
+	"ontology",
+	"serenity-skill-creator",
 	"handyman",
 	"localstore",
 	"container_admin",
 	"im-bridge",
 	"acc-diag",
-	"diagram",
-	"ontology",
-	"serenity-skill-creator"
+	"diagram"
 ];
+/** 条件出现的工具数（`REGISTERED_TOOLS` 的**末段**；`assertManifestProse` 用） */
+const CONDITIONAL_TOOL_COUNT = 3;
 //#endregion
-export { REGISTERED_TOOLS, verifyToolConsistency };
+export { CONDITIONAL_TOOL_COUNT, REGISTERED_TOOLS, assertManifestProse, verifyToolConsistency };

package/lib/ontology/engine.d.ts

@@ -56,6 +56,8 @@ interface PropertyDef {
 }
 interface TypeDef {
     description?: string;
+    label?: string;
+    comment?: string;
     superTypes?: string[];
     rigidity?: "rigid" | "anti-rigid" | "semi-rigid";
     identity?: string[];
@@ -64,6 +66,8 @@ interface TypeDef {
     axioms?: string[];
 }
 interface RelationDef {
+    label?: string;
+    comment?: string;
     domain?: string;
     range?: string;
     cardinality?: string;
@@ -76,6 +80,10 @@ interface RelationDef {
 }
 interface AxiomDef {
     description?: string;
+    /** `rdfs:label`（与 `description` 分开存；description 仍以 `sr:description` 优先） */
+    label?: string;
+    /** `rdfs:comment` */
+    comment?: string;
     rule: string;
     type?: string;
 }
@@ -86,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";
@@ -137,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";
@@ -165,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,7 +1,7 @@
 {
   "name": "@shgroup/dsh-serenity-hooks",
-  "version": "1.56.1",
-  "description": "宁静号 ACC harness（Native Cordis 插件）——给 DeepSeek Harness 装一个「AI 工作区」：13 个工具（container_fs/container_trajectory/dashboard/container_git/msm/praxis/ontology/handyman/localstore/container_admin；另三个 im-bridge/acc-diag/diagram 按配置条件出现）+ 机械约束（安全模式/工作区围墙/密钥守卫/对外输出守卫）+ 工作日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/trajectory 唤醒注册表。适配 DSH 0.1.7-rc.1。",
+  "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": {
     "type": "git",