@lmzhen/dsh-evolution-core 0.26.15 → 0.27.0

package/lib/types/session-projection.js

@@ -0,0 +1,295 @@
+/**
+ * The family's session projections: the per-session facts the family used to re-read the log for.
+ *
+ * 0.2.x deprecates the synchronous log reads (`Session.snapshotEvents` — "existing logic may
+ * remain unmigrated for now, but new calls are prohibited",
+ * `core/session/src/index.ts:639-658`) and drives DOMAIN-OWNED units instead: a registered unit
+ * folds every committed event once, the registry owns the subscription and the per-session
+ * watermark, and a reader asks for the current state
+ * (`session/session-projection/src/index.ts` — `register`/`stateOf`). Each unit here carries
+ * exactly what one pure family reader derives from a log, so that reader keeps its pure form and
+ * gains a projection-backed one beside it.
+ *
+ * State stays bounded. The evidence unit keeps the SPARSE boundary seqs and answers the dense
+ * question by complement: a content-seq set grows with every session event, while a turn/step
+ * boundary set grows four entries per turn.
+ *
+ * The registry is part of the platform's BASE bundle (`packages/bundle/base/cordis.patch.yml:158`),
+ * so a real host always has it; a composition without it keeps loading (`ctx.inject` probe) and
+ * its readers report "cannot classify" instead of guessing — the same posture the pure readers
+ * document for a log with no seq.
+ * @module @lmzhen/dsh-evolution-core
+ */
+import { z } from 'zod';
+import { isBookkeepingFrame } from "./evidence.js";
+import { dispatchStepOf, isSkillReadToolName, skillReadNameOf } from "./tool-dispatch.js";
+import { foldTurnEvent, initialTurnFold } from "./signals.js";
+// Bounds are the persisted-row validation bounds (a millisecond timestamp): the clamp guard
+// requires every `z.number()` field to carry one on the same line.
+const MAX_TIMESTAMP_MS = 8_640_000_000_000_000;
+const activityStateSchema = z.object({ lastEventTime: z.number().nonnegative().max(MAX_TIMESTAMP_MS) }).strict();
+const evidenceStateSchema = z.object({
+    sequenced: z.number().int().nonnegative(),
+    through: z.number().int().min(-1).max(Number.MAX_SAFE_INTEGER),
+    bookkeeping: z.array(z.number().int().nonnegative()),
+}).strict();
+/** The `evolutionActivity` unit (host-only: no client view is registered for it). */
+export const evolutionActivityProjection = {
+    key: 'evolutionActivity',
+    stateVersion: 1,
+    stateSchema: activityStateSchema,
+    init: () => ({ lastEventTime: 0 }),
+    apply: (state, event) => {
+        const time = typeof event.time === 'number' ? event.time : state.lastEventTime;
+        // Same reference when the event repeats the previous millisecond: the change feed keys on
+        // `Object.is`, and an unchanged reference produces zero downstream work.
+        return time === state.lastEventTime ? state : { lastEventTime: time };
+    },
+};
+/** The `evolutionEvidence` unit (host-only: no client view is registered for it). */
+export const evolutionEvidenceProjection = {
+    key: 'evolutionEvidence',
+    stateVersion: 1,
+    stateSchema: evidenceStateSchema,
+    init: () => ({ sequenced: 0, through: -1, bookkeeping: [] }),
+    apply: (state, event) => {
+        const seq = event.seq;
+        // Only an integer seq is citable, so only an integer seq is classifiable (the same test the
+        // pure reader makes).
+        if (typeof seq !== 'number' || !Number.isInteger(seq))
+            return state;
+        const sequenced = state.sequenced + 1;
+        const through = seq > state.through ? seq : state.through;
+        if (typeof event.type !== 'string' || !isBookkeepingFrame(event.type)) {
+            return { sequenced, through, bookkeeping: state.bookkeeping };
+        }
+        return { sequenced, through, bookkeeping: [...state.bookkeeping, seq] };
+    },
+};
+/**
+ * Whether one session object can be projected at all.
+ *
+ * The family's readers also take STRUCTURAL session views — `skill-reads.ts` documents the tool
+ * path's bare stub — while the registry folds a session's own log (`snapshotEvents(from, to)`,
+ * `eventAt(seq)`, `seq`, `inheritedEventCount`) whenever it has to build or advance a cell. A
+ * view without those members has no projection state to read, and asking for one would fold a
+ * log the unit cannot index.
+ * @param session - the value a caller holds as its session.
+ * @returns true when the registry can fold this object.
+ */
+function isProjectableSession(session) {
+    if (session === null || typeof session !== 'object')
+        return false;
+    const candidate = session;
+    // The two accessors are named on purpose: they ARE the fold contract the registry needs, and
+    // this probe only answers whether the object carries them — it reads no session history.
+    // oxlint-disable-next-line typescript/no-deprecated -- capability probe, not a history read
+    const folds = typeof candidate.eventAt === 'function';
+    // oxlint-disable-next-line typescript/no-deprecated -- capability probe, not a history read
+    const logs = typeof candidate.snapshotEvents === 'function';
+    return folds && logs && typeof candidate.seq === 'number';
+}
+const readsStateSchema = z.object({
+    reads: z.array(z.object({
+        key: z.string(),
+        skill: z.string().nullable(),
+        failed: z.boolean(),
+    }).strict()),
+}).strict();
+const signalsStateSchema = z.object({
+    through: z.number().int().min(-1).max(Number.MAX_SAFE_INTEGER),
+    lastEventTime: z.number().nonnegative().max(MAX_TIMESTAMP_MS),
+    turnStartSeq: z.number().int().min(-1).max(Number.MAX_SAFE_INTEGER),
+    turn: z.object({
+        substantive: z.boolean(),
+        toolCalls: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+        userChars: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+        assistantChars: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+        memorySignal: z.boolean(),
+        skillSignal: z.boolean(),
+        opened: z.array(z.string()),
+    }).strict(),
+}).strict();
+/** The `evolutionReads` unit (host-only: no client view is registered for it). */
+export const evolutionReadsProjection = {
+    key: 'evolutionReads',
+    stateVersion: 1,
+    stateSchema: readsStateSchema,
+    init: () => ({ reads: [] }),
+    apply: (state, event) => {
+        const frame = event;
+        const step = dispatchStepOf(frame);
+        if (step === null)
+            return state;
+        const at = state.reads.findIndex(entry => entry.key === step.key);
+        // An event with no name only SETTLES a dispatch: it can flip the failure flag of one already
+        // tracked, and a dispatch this fold never saw open has nothing to record.
+        // One settle-or-replay transition, shared by both branches below: only a tracked dispatch with
+        // a carried outcome moves, and only when the flag actually changes.
+        const settled = () => {
+            const entry = at < 0 ? undefined : state.reads[at];
+            if (entry === undefined || step.outcome === undefined)
+                return state;
+            const failed = !step.outcome.ok;
+            if (entry.failed === failed)
+                return state;
+            const reads = [...state.reads];
+            reads[at] = { key: entry.key, skill: entry.skill, failed };
+            return { reads };
+        };
+        // An event with no name only SETTLES a dispatch: it can flip the failure flag of one already
+        // tracked, and a dispatch this fold never saw open has nothing to record.
+        if (step.name === '')
+            return settled();
+        // A replayed open of a tracked dispatch: keep the first entry, still honour its outcome.
+        if (at >= 0)
+            return settled();
+        // Only a read-capable tool is worth a state entry: the reader answers skill names, and a
+        // state that tracked every dispatch would grow with the session.
+        if (!isSkillReadToolName(step.name))
+            return state;
+        const skill = skillReadNameOf({
+            kind: step.kind,
+            callId: step.callId,
+            rootCallId: step.rootCallId,
+            name: step.name,
+            arguments: step.arguments,
+            ok: step.outcome?.ok,
+        }) ?? null;
+        return { reads: [...state.reads, { key: step.key, skill, failed: step.outcome?.ok === false }] };
+    },
+};
+/** The `evolutionSignals` unit (host-only: no client view is registered for it). */
+export const evolutionSignalsProjection = {
+    key: 'evolutionSignals',
+    stateVersion: 1,
+    stateSchema: signalsStateSchema,
+    init: () => ({ through: -1, lastEventTime: 0, turnStartSeq: -1, turn: initialTurnFold() }),
+    apply: (state, event) => {
+        const start = event.type === 'turn/start';
+        const turn = foldTurnEvent(start ? initialTurnFold() : state.turn, event);
+        const seq = typeof event.seq === 'number' && Number.isInteger(event.seq) ? event.seq : state.through;
+        const time = typeof event.time === 'number' ? event.time : state.lastEventTime;
+        const turnStartSeq = start ? seq : state.turnStartSeq;
+        if (turn === state.turn && seq === state.through && time === state.lastEventTime && turnStartSeq === state.turnStartSeq)
+            return state;
+        return { through: seq, lastEventTime: time, turnStartSeq, turn };
+    },
+};
+/**
+ * Register the family's units on the calling context's fiber.
+ *
+ * Called by the READERS (not by a plugin's mount) and idempotent by the registry's own reference
+ * count: the first read of a foldable session installs the definitions, later reads count as
+ * co-owners, and the keys survive until the last registrant unloads
+ * (`session-projection/src/index.ts:273-292`). Registering at the read is what keeps a session
+ * view the registry cannot fold (`isProjectableSession`) from ever reaching its drive — the
+ * registry folds the in-memory log on first touch, so a unit that appears mid-session is still
+ * correct (`:602-630`).
+ *
+ * Idempotent by design, so a plugin mounting later does not need its own call.
+ * @param ctx - the mounting plugin's context.
+ */
+export function installEvolutionProjections(ctx) {
+    const register = (registry) => {
+        registry.register(evolutionActivityProjection);
+        registry.register(evolutionEvidenceProjection);
+        registry.register(evolutionReadsProjection);
+        registry.register(evolutionSignalsProjection);
+    };
+    // Already-mounted registry first: a reader that runs in the same tick as its own mount
+    // (a unit spec, an assembly-time probe) must see its units registered, and the injected
+    // callback of a not-yet-available service is not guaranteed to have run by then.
+    // platform-declaration anchor: the platform’s `sessionProjections` service (optional; undefined ⇒ no measurement)
+    const mounted = ctx.get('sessionProjections');
+    if (mounted !== undefined) {
+        register(mounted);
+        return;
+    }
+    ctx.inject(['sessionProjections'], (injected) => { register(injected.sessionProjections); });
+}
+/**
+ * Time of one session's newest event, or `undefined` when the unit is not installed.
+ *
+ * The curator's idleness gate reads this instead of folding the session log; `undefined` is a
+ * measurement that did not happen, which the gate answers with the deployment's fail-open policy.
+ * @param ctx - a context of the runtime (the service is read from the global store).
+ * @param session - the session to ask about.
+ * @returns the newest event's milliseconds, or undefined with no unit or no event.
+ */
+export function sessionLastEventTime(ctx, session) {
+    if (!isProjectableSession(session))
+        return undefined;
+    installEvolutionProjections(ctx);
+    const state = ctx.get('sessionProjections')?.stateOf(session, 'evolutionActivity');
+    if (state === undefined || state.lastEventTime === 0)
+        return undefined;
+    return state.lastEventTime;
+}
+/**
+ * The skill names one session read through a non-failed dispatch, or `undefined` when the session
+ * cannot be projected (a structural view, or a host without the registry).
+ *
+ * `undefined` is NOT an empty set: the tool path's read-before-write gate keeps its previous
+ * behavior rather than refusing every write in a composition whose session object is a bare stub
+ * (`skill-reads.ts` documents that three-state posture).
+ * @param ctx - a context of the runtime.
+ * @param session - the session whose reads are wanted.
+ * @returns the names read, or undefined when the log cannot be folded.
+ */
+export function sessionReadNames(ctx, session) {
+    if (!isProjectableSession(session))
+        return undefined;
+    installEvolutionProjections(ctx);
+    const state = ctx.get('sessionProjections')?.stateOf(session, 'evolutionReads');
+    if (state === undefined)
+        return undefined;
+    const names = new Set();
+    for (const entry of state.reads) {
+        if (!entry.failed && entry.skill !== null)
+            names.add(entry.skill);
+    }
+    return names;
+}
+/**
+ * The open turn's window signals, or `undefined` when the session cannot be projected.
+ *
+ * The window is the events since the newest `turn/start`, folded by the same `foldTurnEvent`
+ * `observeEvent` uses; `undefined` means the caller has no measurement (a structural view), not
+ * that the turn was empty.
+ * @param ctx - a context of the runtime.
+ * @param session - the session whose open turn is being judged.
+ * @returns the window signals, or undefined when the log cannot be folded.
+ */
+export function sessionTurnSignals(ctx, session) {
+    if (!isProjectableSession(session))
+        return undefined;
+    installEvolutionProjections(ctx);
+    const state = ctx.get('sessionProjections')?.stateOf(session, 'evolutionSignals');
+    if (state === undefined)
+        return undefined;
+    const { substantive, toolCalls, userChars, assistantChars, memorySignal, skillSignal } = state.turn;
+    return { substantive, toolCalls, userChars, assistantChars, memorySignal, skillSignal };
+}
+/**
+ * The evidence index of one session, or `undefined` when the log cannot be classified.
+ *
+ * `undefined` covers both the missing unit and a log whose frames carry no seq: the plan path's
+ * `EVIDENCE_CLASS` row is report-only and must stay silent rather than report every op.
+ * @param ctx - a context of the runtime.
+ * @param session - the session the review plan is authored against.
+ * @returns an index answering "does this seq carry content?".
+ */
+export function sessionEvidenceIndex(ctx, session) {
+    if (!isProjectableSession(session))
+        return undefined;
+    installEvolutionProjections(ctx);
+    const state = ctx.get('sessionProjections')?.stateOf(session, 'evolutionEvidence');
+    if (state === undefined || state.sequenced === 0)
+        return undefined;
+    const { through, bookkeeping } = state;
+    return {
+        has: (seq) => Number.isInteger(seq) && seq >= 0 && seq <= through && !bookkeeping.includes(seq),
+    };
+}
+//# sourceMappingURL=session-projection.js.map

package/lib/types/signals.js

@@ -0,0 +1,209 @@
+/**
+ * Deterministic review signal gate.
+ *
+ * Scans a DSH session event log for durable learning signals before any LLM
+ * is spent. `turn/end` calls `observeEvent`; the returned review kind is
+ * accumulated until a configured interval fires.
+ */
+import { dispatchStepOf, isSkillToolName } from "./tool-dispatch.js";
+const CORRECTION_PATTERNS = [
+    /(?:don'?t|do not|stop|never)\s+(?:do|use|format|explain|write|say)/i,
+    /(?:too|very|way\s+too)\s+(?:verbose|long|detailed|short|brief)/i,
+    /(?:I|we)\s+(?:prefer|like|want|need)\b/i,
+    /remember\s+(?:this|that|to)/i,
+];
+const FIX_PATTERNS = [
+    /worked after|fixed by|the fix was|root cause/i,
+    /retry(?:ing)? worked|workaround/i,
+];
+/** Text of one persisted content block, or `''` for any other shape.
+ *
+ * Content blocks cross the durable session-log boundary, so their runtime
+ * shape is `unknown` even where the static event type promises
+ * `{ type, text }`: a persisted `content: [null]` (A2-7, v18) used to throw a
+ * TypeError here and the review catch swallowed the whole turn's remaining
+ * signals. Keeping the guard in one helper also keeps the branches free of
+ * conditions the static type already excludes.
+ * @param block - one element of a persisted message `content` array.
+ * @returns the block's text when it is a text block, otherwise an empty string.
+ */
+function textOfBlock(block) {
+    if (block === null || typeof block !== 'object')
+        return '';
+    const candidate = block;
+    return candidate.type === 'text' && typeof candidate.text === 'string' ? candidate.text : '';
+}
+/** The empty turn-window fold state. */
+export function initialTurnFold() {
+    return {
+        substantive: false,
+        toolCalls: 0,
+        userChars: 0,
+        assistantChars: 0,
+        memorySignal: false,
+        skillSignal: false,
+        opened: [],
+    };
+}
+/**
+ * Fold ONE session event into a turn-window state, purely.
+ *
+ * The one fold behind all three readers: `observeEvent` (the mutating face the live `turn/end`
+ * path uses), `foldTurn` (a whole-log window fold, kept for structural test sessions) and the
+ * family's `evolutionSignals` projection unit. P1-1/N4 guards stay: events arrive from disk, so
+ * a persisted `data: null` / non-object or a malformed `content` skips instead of throwing.
+ * @param state - the window so far.
+ * @param event - the next committed session event.
+ * @returns the next state; the same reference when the event carries nothing this fold reads.
+ */
+export function foldTurnEvent(state, event) {
+    const data = event.data;
+    if (data === null || typeof data !== 'object' || Array.isArray(data))
+        return state;
+    if (event.type === 'user/message') {
+        // 0.3.16 (E-49): a malformed content (not an array) used to throw here and
+        // break the whole signal pipeline — guard and skip instead.
+        const content = data.content;
+        if (!Array.isArray(content))
+            return state;
+        const text = content.map(textOfBlock).join(' ');
+        return {
+            ...state,
+            userChars: state.userChars + text.length,
+            memorySignal: state.memorySignal || CORRECTION_PATTERNS.some(pattern => pattern.test(text)),
+            skillSignal: state.skillSignal || FIX_PATTERNS.some(pattern => pattern.test(text)),
+        };
+    }
+    if (event.type === 'assistant/message') {
+        // V6-21/V7-09: the same content guard the user branch got in E-49, extended to `message`
+        // itself missing — `.content` on an absent message is the same TypeError one level up.
+        const message = data.message;
+        if (!message || !Array.isArray(message.content))
+            return state;
+        const text = message.content.map(textOfBlock).join(' ');
+        return { ...state, assistantChars: state.assistantChars + text.length };
+    }
+    // Tool evidence (v37 P7a): the dispatch vocabulary lives in `tool-dispatch.ts` — the ONE reader
+    // of the platform's dispatch event types — and `dispatchStepOf` is its pure half, so this fold
+    // counts one tool call per dispatch whatever the runtime mode (native or PTC).
+    // One widening assignment instead of a conditional spread: `SessionEvent`'s own type keeps `data`
+    // required, while events arriving from disk may omit it — the vocabulary takes it optional.
+    const frame = event;
+    const dispatch = dispatchStepOf(frame);
+    if (dispatch === null || dispatch.name === '' || state.opened.includes(dispatch.key))
+        return state;
+    // `toolCalls` is the model-facing call count the cadence weights by: a program's sub-dispatches
+    // are not model calls (the `run_code` call that owns them is logged natively and counted by its
+    // own `tool/call`), so only native dispatches advance it — which, since the vocabulary's dead
+    // 'program-root' value was removed (S1-E6), is simply `kind !== 'program'`. This is the ONE
+    // modality split the family's N17 guard table registers; do not add a second copy.
+    let toolCalls = state.toolCalls;
+    if (dispatch.kind !== 'program')
+        toolCalls += 1;
+    return {
+        ...state,
+        opened: [...state.opened, dispatch.key],
+        toolCalls,
+        skillSignal: state.skillSignal || isSkillToolName(dispatch.name),
+    };
+}
+/**
+ * Per-turn dispatch ledgers, keyed by the signal object they feed.
+ *
+ * `observeEvent` folds ONE event at a time, so the ledger has to outlive the call. One WeakMap
+ * entry per `TurnSignals`, so a finished fold's ledger is collectable with the fold itself and two
+ * concurrent turns never share one.
+ */
+const dispatchLedgers = new WeakMap();
+/** The ledger of the turn this signal is folding; empty before its first dispatch. */
+function ledgerForSignal(signal) {
+    return dispatchLedgers.get(signal) ?? [];
+}
+/**
+ * Fold one session event into the current turn observation (the mutating face of
+ * {@link foldTurnEvent}: every reader shares the one fold, this one copies the result back onto
+ * the caller's signal object and keeps its ledger for the next event).
+ * @param signal - the turn observation to advance.
+ * @param event - the next committed session event.
+ */
+export function observeEvent(signal, event) {
+    const next = foldTurnEvent({ ...signal, opened: [...ledgerForSignal(signal)] }, event);
+    signal.substantive = next.substantive;
+    signal.toolCalls = next.toolCalls;
+    signal.userChars = next.userChars;
+    signal.assistantChars = next.assistantChars;
+    signal.memorySignal = next.memorySignal;
+    signal.skillSignal = next.skillSignal;
+    dispatchLedgers.set(signal, next.opened);
+}
+/** Compute review cadence after `turn/end`. */
+export function advanceReview(state, turn, signal, config) {
+    if (turn === state.lastTurn)
+        return null;
+    state.lastTurn = turn;
+    signal.substantive = signal.toolCalls >= config.substantiveMinToolCalls
+        || signal.userChars >= config.substantiveMinUserChars
+        || signal.assistantChars >= config.substantiveMinAgentChars;
+    if (!signal.substantive)
+        return null;
+    // Decision point 2 (0.3.24 G4.6): turnsSinceMemory is now ACTIVITY-weighted,
+    // symmetric with turnsSinceSkill below — a turn without a memory signal
+    // advances by the turn's tool-call count, so memory fires on accumulated
+    // work rather than raw turn count. The field name is kept for on-disk
+    // record compatibility; the semantic is documented here.
+    state.turnsSinceMemory += signal.memorySignal ? 1 : Math.max(1, signal.toolCalls);
+    // P3 (v3 audit): turnsSinceSkill is an ACTIVITY-weighted counter — a turn
+    // without a skill signal advances by the turn's tool-call count (so skills
+    // fire on accumulated work, not turn count). The field name is kept for
+    // on-disk record compatibility; the semantic is documented here.
+    state.turnsSinceSkill += signal.skillSignal ? 1 : Math.max(1, signal.toolCalls);
+    const memoryDue = state.turnsSinceMemory >= config.memoryInterval;
+    const skillDue = state.turnsSinceSkill >= config.skillInterval;
+    // 0.3.40: with resetOnFire=false the counters stay monotonic — the caller
+    // resets them at its injection point (the counting window is inject→inject).
+    const zero = () => {
+        state.turnsSinceMemory = 0;
+        state.turnsSinceSkill = 0;
+    };
+    if (memoryDue && skillDue) {
+        if (config.resetOnFire !== false)
+            zero();
+        return 'combined';
+    }
+    if (memoryDue) {
+        if (config.resetOnFire !== false)
+            state.turnsSinceMemory = 0;
+        return 'memory';
+    }
+    if (skillDue) {
+        if (config.resetOnFire !== false)
+            state.turnsSinceSkill = 0;
+        return 'skill';
+    }
+    return null;
+}
+/**
+ * Fold a log slice into one turn window, purely.
+ *
+ * The whole-log reference for {@link foldTurnEvent}: a caller that holds events (a fixture, a
+ * structural view, a replay) reads a window without touching a platform Session. Production reads
+ * the same window live from the family's `evolutionSignals` projection (`sessionTurnSignals`),
+ * which folds `foldTurnEvent` once per committed event.
+ * @param events - the log, oldest first. Pass an array, not a live iterator, when it can grow.
+ * @param fromSeq - index of the first event of the window (0 for the whole log).
+ * @returns the window's signals.
+ */
+export function foldTurnEvents(events, fromSeq = 0) {
+    // Materialize once: a live iterator must not be re-entered, and `Array.isArray` on an
+    // `Iterable` would narrow to `any[]`.
+    const list = [...events];
+    let state = initialTurnFold();
+    for (let index = Math.max(0, fromSeq); index < list.length; index += 1) {
+        const event = list[index];
+        if (event)
+            state = foldTurnEvent(state, event);
+    }
+    const { substantive, toolCalls, userChars, assistantChars, memorySignal, skillSignal } = state;
+    return { substantive, toolCalls, userChars, assistantChars, memorySignal, skillSignal };
+}
+//# sourceMappingURL=signals.js.map

package/lib/types/skill-discovery.js

@@ -0,0 +1,66 @@
+/**
+ * 技能发现形状 —— 家族里**唯一**的实现，门禁（`packages/scripts/verify-graph-edges.mjs`）
+ * 与图谱/边解析必须都调用它（R21/R69：两处各自实现＝68/63 并存那类症状的根源）。
+ *
+ * 平台判定见 skill-filesystem/src/index.ts (`isPotentialSkillPath`：`<root>/<name>.md`
+ * 或 `<root>/<name>/SKILL.md`，即 depth<=2) 与 parseSkillFile:816-819 (`isSkillName`：kebab-case)；
+ * 排除机制是三条而非一条前缀规则：`.archive/`、`.backups/` 靠**深度**（3 段 > 2），
+ * `._x/` 靠**名字文法**，`.system` 才是真前缀排除(:666/:680)。
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** 技能名文法（与平台 `isSkillName` 等价：kebab-case，点前缀与下划线一律不是技能名）。 */
+export const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+/** 名字是否是技能名 —— `._x`、`Bad_Name`、`.archive` 都返回 false。 */
+export function isSkillName(name) {
+    return SKILL_NAME_RE.test(name);
+}
+/** 相对技能根的路径是否落在平台会发现的位置（depth<=2 且最后一段是 SKILL.md 或 `<name>.md`）。 */
+export function isPotentialSkillPath(relPath) {
+    const parts = relPath.split(/[\\/]+/).filter(p => p.length > 0);
+    if (parts.length < 1 || parts.length > 2)
+        return false;
+    // `noUncheckedIndexedAccess` is on: an empty part list cannot happen (length >= 1 above), but the
+    // index expression still types as `string | undefined` -- an empty fallback fails both tests below.
+    const last = parts[parts.length - 1] ?? '';
+    if (parts.length === 2)
+        return last === 'SKILL.md' && isSkillName(parts[0] ?? '');
+    return last.endsWith('.md') && isSkillName(last.slice(0, -3));
+}
+/**
+ * 扫描一个技能根，返回平台**真正会发现**的技能（非递归、depth<=2、含 `SKILL.md` 的目录、
+ * 名字过 kebab-case、跳过点前缀目录）。忽略目录里的边不得计入，也不得算悬空。
+ *
+ * @param root - 技能根目录。
+ * @returns 按名字排序的技能列表（根缺失时返回空数组）。
+ */
+export function discoverSkillFiles(root) {
+    if (!existsSync(root))
+        return [];
+    const found = [];
+    let entries = [];
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (!isSkillName(entry))
+            continue;
+        const dir = join(root, entry);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const md = join(dir, 'SKILL.md');
+        if (!existsSync(md))
+            continue;
+        found.push({ name: entry, path: md });
+    }
+    return found.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+//# sourceMappingURL=skill-discovery.js.map