@lmzhen/dsh-evolution-skill-catalog 0.3.62 → 0.3.64

package/README.md

@@ -23,5 +23,8 @@ Independent of request-prefix construction. This package does not alter the asse
 
 
 - Read-only native `ctx.skills` catalog. Skill mutations still happen through `tool-skill-manage`.
-- **Out-of-band edits need a refresh (0.3.18, E-71).** The catalog invalidates on the in-band `evolution/skill-mutated` event (all writes through SkillLibrary). Edits made outside the family — manual file edit, a git pull, another process — bypass that event and cannot be auto-detected (decision C: no filesystem watcher). A root-mtime probe re-stamps the summaries cache when the provider is re-queried after a structural change (directory add/remove/rename), but any out-of-band change is only guaranteed to be visible after `/evolution skills refresh` runs (or the process restarts).
+- **Out-of-band edits need a refresh (0.3.18, E-71).** The catalog invalidates on the in-band `evolution/skill-mutated` event (all writes through SkillLibrary). Edits made outside the family — manual file edit, a git pull, another process — bypass that event and cannot be auto-detected (decision C: no filesystem watcher). A root-mtime probe re-stamps the summaries cache when the provider is re-queried after a structural change (directory add/remove/rename), but the probe only runs when the upstream skill registry actually consults this provider — between refreshes the registry's collect cache answers `list`/`snapshot` without calling providers (the real reason E-71's out-of-band skill stays invisible), while `get` of an already-indexed name still reaches the provider, so an out-of-band CONTENT edit of an existing skill shows fresh content there (description stays stale until refresh). Any out-of-band change is only guaranteed to be visible after `/evolution skills refresh` runs (or the process restarts).
+- **Upstream-invalid entries are filtered, not published (P1-1, v18).** `SkillLibrary.list()` reports an empty description for a 0-byte/malformed SKILL.md (C-14 keeps it visible to the curator), and a tree entry created before the 0.3.64 name tightening can still carry a trailing/consecutive hyphen. Upstream `validateCandidate` throws on either shape, and that throw aborts the whole `ctx.skills` collection (breaking `agent/pre-step` and the `skill` tool for the session). This provider therefore skips (and warns once about) any candidate whose name is not upstream `SKILL_NAME` or whose description is empty. The entry stays visible to the curator/lifecycle; fix the SKILL.md frontmatter (or the directory name) to publish it.
+- **`whenToUse` is published, `metadata` is not (E-11, v18).** A non-empty single-line `whenToUse` from the frontmatter is forwarded to the platform catalog (the upstream filesystem provider does the same, and the host/UI read it for routing hints). `metadata` needs a real YAML parse and stays unpublished by this provider.
+- **Protection markers are best-effort per entry (A1-17, v18).** When the directory listing AND the per-marker probes fail, `SkillSummary.protectionUnknown` is true and consumers (curator, maintenance) treat the entry as protected rather than unprotected.
 

package/lib/index.js

@@ -1,5 +1,5 @@
 import z from "@deepseek-ai/schemastery";
-import { SkillLibrary, evolutionIoAdapter, resolveSkillsRoot } from "@lmzhen/dsh-evolution-core";
+import { SKILL_NAME_RE, SkillLibrary, evolutionIoAdapter, resolveSkillsRoot } from "@lmzhen/dsh-evolution-core";
 import { join } from "node:path";
 //#region lib/types/index.js
 /**
@@ -39,6 +39,22 @@ const Config = z.object({
 *   pins the "lower rank wins" resolution on the registry side.
 */
 const EVOLUTION_SKILL_RANK = 390;
+/**
+* The mirror's `SKILL_NAME_RE` now carries the same shape (计划 B-4, v18), but
+* this provider still filters: an EXISTING tree entry created before the
+* tightening (trailing/consecutive hyphen) must not be forwarded, because
+* upstream `validateCandidate` throws on it and that throw aborts the WHOLE
+* `ctx.skills` collection (the caller is outside the provider try/catch),
+* taking down `agent/pre-step` and the `skill` tool for the session.
+*/
+const UPSTREAM_SKILL_NAME_RE = SKILL_NAME_RE;
+/** Upstream `validateCandidate` also refuses an empty description; the
+* mirror's `SkillLibrary.list()` legitimately reports `''` for a 0-byte or
+* malformed SKILL.md (C-14 keeps it visible to the curator). Such an entry
+* must not reach the platform registry. */
+function publishableSkill(name, description) {
+	return UPSTREAM_SKILL_NAME_RE.test(name) && description.trim().length > 0;
+}
 function apply(ctx, rawConfig = {}) {
 	const invocation = {
 		modelInvocable: rawConfig.modelInvocable ?? true,
@@ -49,6 +65,12 @@ function apply(ctx, rawConfig = {}) {
 	const included = new Set(rawConfig.includeSkillNames ?? []);
 	const excluded = new Set(rawConfig.excludeSkillNames ?? []);
 	const visible = (name) => (included.size === 0 || included.has(name)) && !excluded.has(name);
+	const warnedUnpublishable = /* @__PURE__ */ new Set();
+	const warnUnpublishable = (name, description) => {
+		if (warnedUnpublishable.has(name)) return;
+		warnedUnpublishable.add(name);
+		ctx.logger.warn(`evolution-skill-catalog: not publishing "${name}" — ${description.trim().length === 0 ? "empty description" : "name is not accepted by the upstream skill registry"} (fix the SKILL.md frontmatter; the curator still sees the entry)`);
+	};
 	let control;
 	let summariesCache = null;
 	let summariesStamp = null;
@@ -66,10 +88,21 @@ function apply(ctx, rawConfig = {}) {
 	};
 	const provider = {
 		name: "dsh-evolution",
-		async list(_options) {
-			return (await summaries()).filter((summary) => visible(summary.name)).map((summary) => ({
+		async list(options) {
+			options.signal?.throwIfAborted();
+			const all = await summaries();
+			options.signal?.throwIfAborted();
+			return all.filter((summary) => {
+				if (!visible(summary.name)) return false;
+				if (!publishableSkill(summary.name, summary.description)) {
+					warnUnpublishable(summary.name, summary.description);
+					return false;
+				}
+				return true;
+			}).map((summary) => ({
 				name: summary.name,
 				description: summary.description,
+				...summary.whenToUse !== void 0 ? { whenToUse: summary.whenToUse } : {},
 				invocation,
 				source: "user-dsh",
 				provider: "dsh-evolution",
@@ -82,16 +115,22 @@ function apply(ctx, rawConfig = {}) {
 				}
 			}));
 		},
-		async get(candidate) {
+		async get(candidate, options) {
+			options?.signal?.throwIfAborted();
 			const name = candidate.name;
 			if (!visible(name)) return void 0;
 			const summary = (await summaries()).find((item) => item.name === name);
 			if (!summary) return void 0;
+			if (!publishableSkill(summary.name, summary.description)) {
+				warnUnpublishable(summary.name, summary.description);
+				return;
+			}
 			const content = await library.read(name);
 			if (content === null) return void 0;
 			return {
 				name,
 				description: summary.description,
+				...summary.whenToUse !== void 0 ? { whenToUse: summary.whenToUse } : {},
 				invocation,
 				source: "user-dsh",
 				provider: "dsh-evolution",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-skill-catalog",
   "description": "Native ctx.skills provider for the evolution-managed skill tree (community build)",
-  "version": "0.3.62",
+  "version": "0.3.64",
   "publishConfig": {
     "access": "public"
   },
@@ -31,18 +31,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-core": "^0.3.62"
+    "@lmzhen/dsh-evolution-core": "^0.3.64"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-skill": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.3.62"
+    "@lmzhen/dsh-evolution-io": "^0.3.64"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
     "@deepseek-ai/dsh-skill": "^0.1.1-rc.2",
-    "@lmzhen/dsh-evolution-core": "^0.3.62",
-    "@lmzhen/dsh-evolution-io": "^0.3.62"
+    "@lmzhen/dsh-evolution-core": "^0.3.64",
+    "@lmzhen/dsh-evolution-io": "^0.3.64"
   }
 }