@lmzhen/dsh-evolution-learning-graph 0.1.0-rc.8 → 0.1.0

package/lib/index.js

@@ -1,10 +1,45 @@
+import { SKILL_NAME_RE, SkillLibrary, evolutionIoAdapter, relatedSkillNames } from "@lmzhen/dsh-evolution-core";
 //#region lib/types/index.js
 /**
-* Learning graph over skills and memory.
+* Learning graph over skills and memory, plus node-level commands
+* (`/evolution graph [detail|edit|delete] <nodeId>`) aligned with the Hermes
+* journey surface: a skill node is its name, a memory node is
+* `memory:<source>:<index>` (source = memory|user, index = position in that
+* file's entries).
 * @module @lmzhen/dsh-evolution-learning-graph
 */
-/** Build a small deterministic graph from usage records and memory entries. */
-function buildLearningGraph(usage, memoryEntries) {
+function graphDensity(graph) {
+	const linked = /* @__PURE__ */ new Set();
+	let relatedEdges = 0;
+	for (const edge of graph.edges) {
+		if (edge.type !== "related") continue;
+		relatedEdges += 1;
+		linked.add(edge.from);
+		linked.add(edge.to);
+	}
+	const skillNodes = graph.nodes.filter((node) => node.kind === "skill").length;
+	const isolated = graph.nodes.filter((node) => node.kind === "skill" && !linked.has(node.id)).length;
+	return {
+		skillNodes,
+		relatedEdges,
+		edgesPerNode: skillNodes === 0 ? 0 : Math.round(relatedEdges / skillNodes * 100) / 100,
+		isolatedPct: skillNodes === 0 ? 0 : Math.round(isolated / skillNodes * 100)
+	};
+}
+/**
+* Build a small deterministic graph from usage records and memory entries.
+* Memory node ids follow `memory:<source>:<index>` (source = memory|user,
+* index = position in that file's entries) — the SAME rule the parser
+* `parseGraphNodeId` accepts, so graph detail/edit/delete round-trips.
+*
+* Skill-skill edges are semantic only (B-line G3): each entry of `related`
+* (skill name -> names its frontmatter references, from
+* `relatedSkillNames`) becomes an edge when BOTH endpoints exist in the
+* usage set, self-edges are dropped and undirected duplicates collapse. An
+* omitted `related` yields no skill-skill edges — the former alphabet-order
+* chain was a placeholder that connected unrelated neighbors.
+*/
+function buildLearningGraph(usage, memoryEntries, userEntries = [], related) {
 	const nodes = [...usage.keys()].map((name) => ({
 		id: name,
 		kind: "skill",
@@ -12,52 +47,183 @@ function buildLearningGraph(usage, memoryEntries) {
 	}));
 	const edges = [];
 	const sorted = [...usage.keys()].sort();
-	for (let i = 1; i < sorted.length; i += 1) {
-		const from = sorted[i - 1];
-		const to = sorted[i];
-		if (from && to) edges.push({
-			from,
-			to,
-			type: "related"
-		});
+	const seenPairs = /* @__PURE__ */ new Set();
+	for (const [from, targets] of related ?? []) {
+		if (!usage.has(from)) continue;
+		for (const to of targets) {
+			if (to === from || !usage.has(to)) continue;
+			const pairKey = [from, to].sort().join("->");
+			if (seenPairs.has(pairKey)) continue;
+			seenPairs.add(pairKey);
+			edges.push({
+				from,
+				to,
+				type: "related"
+			});
+		}
 	}
-	memoryEntries.forEach((entry, index) => {
-		const id = `memory:${index}`;
-		nodes.push({
-			id,
-			kind: "memory",
-			label: entry.split("\n")[0]?.slice(0, 80) ?? id
+	const appendMemory = (source, entries) => {
+		entries.forEach((entry, index) => {
+			const id = `memory:${source}:${index}`;
+			nodes.push({
+				id,
+				kind: "memory",
+				label: entry.split("\n")[0]?.slice(0, 80) ?? id
+			});
+			const token = entry.toLowerCase();
+			for (const name of sorted) if (name && token.includes(name.toLowerCase())) edges.push({
+				from: id,
+				to: name,
+				type: "memory_skill"
+			});
 		});
-		const token = entry.toLowerCase();
-		for (const name of sorted) if (name && token.includes(name.toLowerCase())) edges.push({
-			from: id,
-			to: name,
-			type: "memory_skill"
-		});
-	});
+	};
+	appendMemory("memory", memoryEntries);
+	appendMemory("user", userEntries);
 	return {
 		nodes,
 		edges
 	};
 }
+/** Parse a graph node id: skill names pass through; `memory:<source>:<index>` becomes a memory node. */
+function parseGraphNodeId(id) {
+	const memory = /^memory:(memory|user):(\d+)$/.exec(id);
+	if (memory) return {
+		kind: "memory",
+		source: memory[1],
+		index: Number(memory[2])
+	};
+	if (SKILL_NAME_RE.test(id)) return {
+		kind: "skill",
+		name: id
+	};
+	return null;
+}
+/** Resolve a parsed node to its current content (read-only). */
+async function resolveGraphNode(parsed, repository) {
+	if (parsed.kind === "skill") {
+		const content = await repository.readSkill(parsed.name);
+		return content === null ? {
+			ok: false,
+			message: `Skill "${parsed.name}" not found.`
+		} : {
+			ok: true,
+			message: content
+		};
+	}
+	const entries = await repository.readMemory(parsed.source);
+	const entry = entries[parsed.index];
+	return entry === void 0 ? {
+		ok: false,
+		message: `Memory ${parsed.source}[${parsed.index}] does not exist (${entries.length} entries).`
+	} : {
+		ok: true,
+		message: entry
+	};
+}
 const name = "evolution-learning-graph";
 function apply(ctx) {
 	ctx.inject(["commands"], (commandCtx) => {
-		commandCtx.commands.register({
-			name: "evolution graph",
-			description: "Show the current learning graph",
+		const commands = commandCtx.commands;
+		commandCtx.effect(() => commands.register({
+			name: "graph",
+			description: "Show the learning graph, or act on a node: graph [detail|edit|delete] <nodeId>",
 			recordInput: false,
-			handler: async () => {
-				const usage = ctx.get("skillUsage");
-				const memory = ctx.get("memory");
-				if (!usage || !memory) return { text: "skill-usage or memory service is not mounted." };
-				const graph = buildLearningGraph(await usage.report(), await memory.read("memory"));
-				const lines = graph.nodes.map((node) => (node.kind === "memory" ? "◆" : "●") + " " + node.label);
-				const edges = graph.edges.map((edge) => edge.from + " --" + edge.type + "--> " + edge.to);
-				return { text: lines.join("\n") + "\n\n" + edges.join("\n") };
+			handler: async (invocation) => {
+				const ok = (text) => ({
+					kind: "success",
+					text
+				});
+				const err = (text) => ({
+					kind: "error",
+					text
+				});
+				const usageService = ctx.get("skillUsage");
+				const memoryService = ctx.get("memory");
+				const ioService = ctx.get("evolutionIo");
+				if (!usageService || !memoryService || !ioService) return err("skill-usage, memory or evolution-io service is not mounted.");
+				const usage = usageService;
+				const memory = memoryService;
+				const io = ioService;
+				const input = (invocation.rawInput ?? "").trim();
+				const detail = /^detail\s+(\S+)$/.exec(input);
+				if (detail && detail[1]) return await nodeDetail(detail[1]);
+				const edit = /^edit\s+(\S+)\s+([\s\S]+)$/.exec(input);
+				if (edit && edit[1] && edit[2] !== void 0) return await nodeEdit(edit[1], edit[2]);
+				const remove = /^delete\s+(\S+)$/.exec(input);
+				if (remove && remove[1]) return await nodeDelete(remove[1]);
+				const directory = await renderGraph();
+				if (input !== "") return err(`Unknown graph subcommand "${input.split(" ")[0]}". ${directory}`);
+				return ok(directory);
+				async function renderGraph() {
+					const usageMap = await usage.report();
+					const memoryEntries = await memory.read("memory");
+					const userEntries = await memory.read("user");
+					const skills = withSkills();
+					const related = /* @__PURE__ */ new Map();
+					for (const name of usageMap.keys()) {
+						const content = await skills.read(name);
+						if (content === null) continue;
+						related.set(name, relatedSkillNames(content, name));
+					}
+					const graph = buildLearningGraph(usageMap, memoryEntries, userEntries, related);
+					const lines = graph.nodes.map((node) => (node.kind === "memory" ? "◆" : "●") + " " + node.label);
+					const edges = graph.edges.map((edge) => edge.from + " --" + edge.type + "--> " + edge.to);
+					const density = graphDensity(graph);
+					const densityLine = `\n\nSkills: ${density.skillNodes} · related edges: ${density.relatedEdges} (${density.edgesPerNode}/node) · isolated: ${density.isolatedPct}%`;
+					return lines.join("\n") + "\n\n" + edges.join("\n") + densityLine;
+				}
+				function withSkills() {
+					return new SkillLibrary(void 0, evolutionIoAdapter(() => io.provider()), void 0, (event) => {
+						ctx.emit("evolution/skill-mutated", event);
+					});
+				}
+				async function nodeDetail(id) {
+					const parsed = parseGraphNodeId(id);
+					if (parsed === null) return err(`Invalid node id "${id}". Skill names or memory:<source>:<index> expected.`);
+					const resolved = await resolveGraphNode(parsed, {
+						readSkill: (name) => withSkills().read(name),
+						readMemory: (target) => memory.read(target)
+					});
+					return resolved.ok ? ok(resolved.message) : err(resolved.message);
+				}
+				async function nodeEdit(id, content) {
+					const parsed = parseGraphNodeId(id);
+					if (parsed === null) return err(`Invalid node id "${id}". Skill names or memory:<source>:<index> expected.`);
+					if (parsed.kind === "skill") {
+						const result = await withSkills().update(parsed.name, content, "foreground");
+						return result.ok ? ok(result.message) : err(result.message);
+					}
+					const entries = await memory.read(parsed.source);
+					const entry = entries[parsed.index];
+					if (entry === void 0) return err(`Memory ${parsed.source}[${parsed.index}] does not exist (${entries.length} entries).`);
+					const result = await memory.applyBatch(parsed.source, [{
+						action: "replace",
+						old_text: entry,
+						facts: content
+					}]);
+					return result.ok ? ok(result.message) : err(result.message);
+				}
+				async function nodeDelete(id) {
+					const parsed = parseGraphNodeId(id);
+					if (parsed === null) return err(`Invalid node id "${id}". Skill names or memory:<source>:<index> expected.`);
+					if (parsed.kind === "skill") {
+						const result = await withSkills().archive(parsed.name);
+						if (result.ok) await usageService?.markArchived?.(parsed.name);
+						return result.ok ? ok(result.message) : err(result.message);
+					}
+					const entries = await memory.read(parsed.source);
+					const entry = entries[parsed.index];
+					if (entry === void 0) return err(`Memory ${parsed.source}[${parsed.index}] does not exist (${entries.length} entries).`);
+					const result = await memory.applyBatch(parsed.source, [{
+						action: "remove",
+						old_text: entry
+					}]);
+					return result.ok ? ok(result.message) : err(result.message);
+				}
 			}
-		});
+		}), "evolution-learning-graph.command");
 	});
 }
 //#endregion
-export { apply, buildLearningGraph, name };
+export { apply, buildLearningGraph, graphDensity, name, parseGraphNodeId, resolveGraphNode };

package/lib/types/index.d.ts

@@ -1,5 +1,9 @@
 /**
- * Learning graph over skills and memory.
+ * Learning graph over skills and memory, plus node-level commands
+ * (`/evolution graph [detail|edit|delete] <nodeId>`) aligned with the Hermes
+ * journey surface: a skill node is its name, a memory node is
+ * `memory:<source>:<index>` (source = memory|user, index = position in that
+ * file's entries).
  * @module @deepseek-ai/dsh-evolution-learning-graph
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -17,11 +21,54 @@ export interface LearningGraph {
     nodes: GraphNode[];
     edges: GraphEdge[];
 }
-/** Build a small deterministic graph from usage records and memory entries. */
+/**
+ * Structural summary of the skill subgraph (Hermes `learning_graph` density
+ * parity): edges per skill node and the share of skills no edge touches.
+ * Memory nodes are excluded — they carry token-matched edges by construction,
+ * which would dilute the isolation signal the statistic exists to expose.
+ */
+export interface GraphDensity {
+    skillNodes: number;
+    relatedEdges: number;
+    edgesPerNode: number;
+    isolatedPct: number;
+}
+export declare function graphDensity(graph: LearningGraph): GraphDensity;
+/**
+ * Build a small deterministic graph from usage records and memory entries.
+ * Memory node ids follow `memory:<source>:<index>` (source = memory|user,
+ * index = position in that file's entries) — the SAME rule the parser
+ * `parseGraphNodeId` accepts, so graph detail/edit/delete round-trips.
+ *
+ * Skill-skill edges are semantic only (B-line G3): each entry of `related`
+ * (skill name -> names its frontmatter references, from
+ * `relatedSkillNames`) becomes an edge when BOTH endpoints exist in the
+ * usage set, self-edges are dropped and undirected duplicates collapse. An
+ * omitted `related` yields no skill-skill edges — the former alphabet-order
+ * chain was a placeholder that connected unrelated neighbors.
+ */
 export declare function buildLearningGraph(usage: ReadonlyMap<string, {
     use_count?: number;
     pinned?: boolean;
-}>, memoryEntries: readonly string[]): LearningGraph;
+}>, memoryEntries: readonly string[], userEntries?: readonly string[], related?: ReadonlyMap<string, readonly string[]>): LearningGraph;
+export type GraphNodeId = {
+    kind: 'skill';
+    name: string;
+} | {
+    kind: 'memory';
+    source: 'memory' | 'user';
+    index: number;
+};
+/** Parse a graph node id: skill names pass through; `memory:<source>:<index>` becomes a memory node. */
+export declare function parseGraphNodeId(id: string): GraphNodeId | null;
+/** Resolve a parsed node to its current content (read-only). */
+export declare function resolveGraphNode(parsed: GraphNodeId, repository: {
+    readSkill(name: string): Promise<string | null>;
+    readMemory(target: 'memory' | 'user'): Promise<string[]>;
+}): Promise<{
+    ok: boolean;
+    message: string;
+}>;
 export declare const name = "evolution-learning-graph";
 export declare function apply(ctx: Context): void;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-learning-graph",
   "description": "Learning graph over skills and memory (community build)",
-  "version": "0.1.0-rc.8",
+  "version": "0.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -32,13 +32,14 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@lmzhen/dsh-evolution-core": "^0.1.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2"
   }
 }