@lmzhen/dsh-evolution-skill-catalog 0.32.3 → 0.32.5

package/README.md

@@ -1,46 +1,25 @@
 # @lmzhen/dsh-evolution-skill-catalog
 
-Native `ctx.skills` provider for the evolution-managed skill tree — read-only; mutations go
-through `tool-skill-manage`.
+> 让 Agent 能在技能目录里看到家族技能。
 
-## Model surface
+## 你会看到
 
-- **Model-visible:** nothing of its own: no prompt and no tool schema; it supplies the read-only native `ctx.skills` catalog, and consumers own the model-visible effects.
-- **Prompt prefix / KV cache:** independent of request-prefix construction; it does not alter the assembled prompt or tool list; family-level rules: `packages/README.md` §"Model-visible prompt prefix and the KV cache".
-- **Mount it?** yes — the `evolution-skill-catalog` row, carried by the `evolution-all` and one-click `evolution-preset` bundles and by the Evolution agent preset delta.
+Agent 能像用普通技能一样发现/使用它们；用户不用直接操作。
 
-## Known limitations
+## 什么时候会用到
 
-- **Out-of-band edits need a refresh.** 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 **entry-name** probe re-stamps the summaries cache when the provider is re-queried after a structural change (directory add/remove/rename) — the stamp is the set of non-dot entry names, not the root's mtime, so the family's own sidecar flushes in the root no longer invalidate the cache, 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.** `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.
-- **Invocation frontmatter: canonical keys first, legacy keys honored conservatively.** The per-skill `disable-model-invocation` / `user-invocable` keys are parsed from the same frontmatter the platform reads and take priority; a file that sets neither falls back to the ROW default (`modelInvocable: true`). Upstream THROWS on the legacy camelCase keys (`disableModelInvocation` / `modelInvocable` / `userInvocable`) and drops the whole file; this shadow warns once and keeps the entry, in the AUTHOR's direction: the mere PRESENCE of `disableModelInvocation` publishes `modelInvocable: false` whatever its value (a misspelled value no longer falls back to the row default and re-enables the skill), and a legacy `modelInvocable` / `userInvocable` is honored as written when it parses (`false` stays `false`) and falls back to the conservative `false` when it does not. Both legacy directions are pinned in `tests/catalog.spec.ts`.
-- **`whenToUse` is published, `metadata` is not.** 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.
-- **`content` is the BODY, not the file.** The published `SkillDefinition.content` is the SKILL.md text AFTER the frontmatter block, matching the upstream filesystem provider (`skill-filesystem`: `content: parsed.body.trim()`). This provider shadows that provider for the same skills, so publishing the whole file made the model load a different skill depending on which provider served it. A file whose frontmatter block cannot be read keeps its raw text (the entry stays visible; the audit reports the file through `frontmatterCatalogInvalid`).
-- **Protection markers are best-effort per entry.** 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.
+每次 Agent 查技能时。
 
-**Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).
+## 默认 / 前提
 
-## Notes and history
+随 all/分层安装自动工作。
 
-- **Out-of-band edits need a refresh (0.3.18, E-71).**
-- **Upstream-invalid entries are filtered, not published (P1-1, v18).**
-- **Invocation frontmatter: canonical keys first, legacy keys honored conservatively (OPT-10; P2-30 / P2-9, 0.3.83).**
-- **`whenToUse` is published, `metadata` is not (E-11, v18).**
-- **`content` is the BODY, not the file (V27 G5.3).**
-- **Protection markers are best-effort per entry (A1-17, v18).**
+## 边界
 
-## Skill names (the family's口径)
+手工改技能目录后，可能需要 `/evolution skills refresh`。
 
-The family's canonical name for a skill is its **directory name**. `SKILL.md`'s frontmatter must
-carry the same `name`: `validateFrontmatter(..., expectedName)` refuses a mismatch ("Frontmatter
-name … does not match target …"), and this provider publishes `summary.name` — the scanned name the
-library derives from the directory.
+## 维护者参考（用户可跳过）
 
-The platform's own `skill-filesystem` provider publishes the frontmatter `name` instead, so an entry
-whose frontmatter name differs from its directory can surface under two names: the family's catalog
-under one, the platform's under the other.
-
-**Decision 1 is open**: keep not publishing name-mismatched entries (conservative), or publish under
-the frontmatter name (thorough, and it moves the read path). Until it is decided this document
-states the behaviour that ships: the directory name wins.
+The family's canonical name for a skill is its **directory name**.
 
+**Decision 1 is open**：frontmatter 名是否作为发布名仍未决；当前按目录名发布。

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.32.3",
+  "version": "0.32.5",
   "publishConfig": {
     "access": "public"
   },
@@ -27,17 +27,17 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.5",
-    "@lmzhen/dsh-evolution-core": "^0.32.3"
+    "@lmzhen/dsh-evolution-core": "^0.32.5"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",
     "@deepseek-ai/dsh-skill": "^0.2.1-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.32.3"
+    "@lmzhen/dsh-evolution-io": "^0.32.5"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-skill": "^0.2.1-rc.2",
-    "@lmzhen/dsh-evolution-core": "^0.32.3",
-    "@lmzhen/dsh-evolution-io": "^0.32.3"
+    "@lmzhen/dsh-evolution-core": "^0.32.5",
+    "@lmzhen/dsh-evolution-io": "^0.32.5"
   },
   "engines": {
     "dsh": ">=0.2.1-rc.2 <0.2.2-0"