dsh-skill-folder 0.3.0

package/lib/bm25.js

@@ -0,0 +1,115 @@
+/**
+ * bm25.js — zero-dependency BM25 lexical search for tool retrieval.
+ *
+ * Design (ported from the xiaowan agent's ToolBM25Index idea; the algorithm is
+ * the reference, this code is a clean-room JS implementation):
+ *   - BM25 with standard k1=1.2, b=0.75 (RAG-MCP / BoR validated the
+ *     retrieval-first approach; BM25 is the cheap lexical leg).
+ *   - Tokenizer handles mixed CN/EN: ASCII words + CJK bigrams. No jieba, no
+ *     network, no dependencies — must run inside the DSH plugin runtime.
+ *   - Synchronous and fast: indexing ~50 tools is <1ms, a query <1ms.
+ *
+ * Cordis sandbox note: this module only does string/number math. It never
+ * touches fs/net/process, so it is safe in any host or sandbox context.
+ *
+ * Vendored verbatim from dsh-tool-folder/lib/bm25.js (same file, same exports)
+ * so the skill-folder retrieval leg behaves byte-identically to tool-folder.
+ */
+
+const K1 = 1.2;
+const B = 0.75;
+
+const EN_STOP = new Set([
+  "the", "a", "an", "and", "or", "of", "to", "in", "on", "for", "with",
+  "at", "by", "from", "as", "is", "are", "was", "were", "be", "been",
+  "it", "this", "that", "these", "those", "i", "you", "he", "she", "we",
+  "they", "do", "does", "did", "have", "has", "had", "not", "no", "yes",
+  "will", "would", "can", "could", "should", "may", "might", "must",
+  "your", "my", "our", "their", "its", "all", "any", "some", "each",
+]);
+
+/** Tokenize mixed CN/EN text into lowercase tokens. */
+function tokenize(text) {
+  const out = [];
+  const s = String(text || "").toLowerCase();
+  for (const m of s.matchAll(/[a-z0-9][a-z0-9_+-]{1,}/g)) {
+    const t = m[0];
+    if (!EN_STOP.has(t)) out.push(t);
+  }
+  // CJK bigrams: "开源框架" -> "开源","源框","框架". Bigrams beat single
+  // chars for short tool descriptions and are dependency-free.
+  const cjk = s.replace(/[^\u4e00-\u9fff]/g, "");
+  if (cjk.length >= 2) {
+    for (let i = 0; i + 2 <= cjk.length; i++) out.push(cjk.slice(i, i + 2));
+  }
+  return out;
+}
+
+/** Build a BM25 index over an array of docs. Each doc: {id, text, ...}. */
+function buildIndex(docs) {
+  const n = docs.length;
+  const docTokens = [];
+  const df = new Map(); // term -> #docs containing it
+  let totalLen = 0;
+
+  for (const doc of docs) {
+    const tokens = tokenize(doc.text);
+    docTokens.push(tokens);
+    totalLen += tokens.length;
+    const seen = new Set();
+    for (const t of tokens) {
+      if (!seen.has(t)) {
+        seen.add(t);
+        df.set(t, (df.get(t) || 0) + 1);
+      }
+    }
+  }
+  const avgdl = n > 0 ? totalLen / n : 1;
+
+  return { n, docTokens, df, avgdl };
+}
+
+/** Score one doc's token list against the query's IDF map. */
+function score(tokens, queryIdf, n, avgdl) {
+  const tf = new Map();
+  for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
+  let acc = 0;
+  const dl = tokens.length;
+  for (const [term, idf] of queryIdf) {
+    const f = tf.get(term);
+    if (!f) continue;
+    acc += idf * ((f * (K1 + 1)) / (f + K1 * (1 - B + (B * dl) / avgdl)));
+  }
+  return acc;
+}
+
+/**
+ * Search an index. Returns up to topK doc ids sorted by BM25 score desc.
+ * @param index   result of buildIndex
+ * @param query   raw query string (mixed CN/EN ok)
+ * @param topK    max results (default 10)
+ * @param opts    {filter: (docId) => boolean}
+ */
+function search(index, query, topK = 10, opts = {}) {
+  const { n, docTokens, df, avgdl } = index;
+  if (!n || !query) return [];
+  const qTerms = tokenize(query);
+  if (qTerms.length === 0) return [];
+
+  const queryIdf = new Map();
+  for (const t of qTerms) {
+    const d = df.get(t) || 0;
+    // BM25+ style: add 1 inside the log to keep IDF positive for unseen terms.
+    queryIdf.set(t, Math.log((n - d + 0.5) / (d + 0.5) + 1));
+  }
+
+  const scored = [];
+  for (let i = 0; i < n; i++) {
+    const s = score(docTokens[i], queryIdf, n, avgdl);
+    if (s > 0 && (!opts.filter || opts.filter(i))) scored.push([i, s]);
+  }
+  scored.sort((a, b) => b[1] - a[1]);
+  return scored.slice(0, topK).map(([i]) => i);
+}
+
+export { tokenize, buildIndex, search, score };

package/lib/catalog.js

@@ -0,0 +1,133 @@
+/**
+ * catalog.js — CatalogStabilizer (the core fold, KV-cache-stable).
+ *
+ * v0.2.0: the rendered catalog is a STATIC function of the skill set only.
+ * It never varies with the per-step query, so the message stays byte-identical
+ * across turns and the prompt-cache prefix never invalidates.
+ *
+ * Red line (spec B3 / Shared Knowledge #1): the catalog message's
+ * `source.entries` is the FULL snapshot and is NEVER trimmed — only
+ * `content[0].text` (the rendered model-facing text) is replaced. The host's
+ * digest (dsh-tool-skill :279-282) and catalogHistory (:309-326) are computed
+ * from source.entries, so keeping entries untouched keeps the digest feedback
+ * loop stable and prevents the "republish full catalog every turn" death loop.
+ *
+ * Fail-safe: any abnormal shape (kind !== "enter", no catalog, unreadable
+ * entries, no text block, identical text) returns the SAME decision reference
+ * unchanged. All rewrites build NEW objects (spread) — frozen host messages
+ * are never mutated.
+ */
+import { selectEntries } from "./select.js";
+import { renderCatalogText } from "./render.js";
+
+/**
+ * Validate a catalog source exactly like the host's readCatalogEntries
+ * (dsh-tool-skill :294-308): entries must be an array of {name, description}
+ * with non-empty string name and string description; otherwise undefined.
+ * @param {object|undefined} source
+ * @returns {Array<{name: string, description: string}>|undefined}
+ */
+export function readCatalogEntries(source) {
+  const entries = source && source.entries;
+  if (!Array.isArray(entries)) return undefined;
+  const readable = [];
+  for (const entry of entries) {
+    if (typeof entry !== "object" || entry === null) return undefined;
+    const { name, description } = entry;
+    if (typeof name !== "string" || name === "" || typeof description !== "string") return undefined;
+    readable.push({ name, description });
+  }
+  return readable;
+}
+
+/** Whether a message is one of this plugin's durable catalogs. */
+function isCatalogMessage(message) {
+  return Boolean(
+    message &&
+      message.source &&
+      message.source.kind === "skill-catalog" &&
+      readCatalogEntries(message.source) !== undefined,
+  );
+}
+
+/**
+ * Find the first readable skill-catalog message in a message batch.
+ * @param {Array} messages
+ * @returns {{message: object, entries: Array}|undefined}
+ */
+export function findCatalogMessage(messages) {
+  if (!Array.isArray(messages)) return undefined;
+  for (const message of messages) {
+    if (!isCatalogMessage(message)) continue;
+    return { message, entries: readCatalogEntries(message.source) };
+  }
+  return undefined;
+}
+
+/**
+ * Build a NEW catalog message with the same identity (id/role/source, entries
+ * untouched) but a replaced content[0].text block. Never mutates the input.
+ * @param {object} cat - the original catalog message (frozen or not).
+ * @param {string} text - the trimmed rendered text.
+ * @returns {object} a new frozen message.
+ */
+export function rewriteContent(cat, text) {
+  const content = Object.freeze([Object.freeze({ type: "text", text })]);
+  return Object.freeze({ ...cat, content });
+}
+
+/**
+ * Stabilize every readable catalog message in the decision's message batch.
+ * Rendering is a pure function of the entries + config — no query input.
+ * @param {object} decision - pre-step decision ({kind, messages}).
+ * @param {object} cfg - merged config (core/deny/maxDescLength).
+ * @param {object} [logger] - optional cordis logger (used for diagnostics only).
+ * @returns {object} same reference when nothing changed; otherwise a new decision.
+ */
+export function trimDecision(decision, cfg, logger) {
+  if (!decision || decision.kind !== "enter") return decision;
+  if (!Array.isArray(decision.messages)) return decision;
+  if (!decision.messages.some(isCatalogMessage)) return decision;
+
+  const maxDescLength = Number.isFinite(Number(cfg.maxDescLength))
+    ? Math.max(0, Math.floor(Number(cfg.maxDescLength)))
+    : 100;
+  const coreList = Array.isArray(cfg.core) ? cfg.core : [];
+
+  let changed = false;
+  const messages = decision.messages.map((message) => {
+    if (!isCatalogMessage(message)) return message;
+    const entries = readCatalogEntries(message.source);
+    // Empty catalog: nothing to fold — keep the host's exact "no skills"
+    // wording untouched (fail-safe).
+    if (!entries || entries.length === 0) return message;
+
+    const blocks = Array.isArray(message.content) ? message.content : [];
+    const first = blocks[0];
+    if (!first || first.type !== "text" || typeof first.text !== "string") return message;
+    const originalText = first.text;
+
+    const selected = selectEntries(entries, cfg);
+    // All entries denied (e.g. deny:["*"] + empty core) → render nothing.
+    // Keep the host's exact wording untouched (fail-safe): an empty
+    // <available_skills> would make the model believe no skills exist.
+    if (!selected.length) return message;
+    const text = renderCatalogText(selected, [], {
+      update: message.source.update === true,
+      maxDescLength,
+      core: coreList,
+    });
+
+    if (text === originalText) return message;
+    changed = true;
+    return rewriteContent(message, text);
+  });
+
+  if (!changed) return decision;
+  logger?.info?.(
+    "skill-folder: stabilized %d catalog message(s) in %d-entry decision",
+    decision.messages.filter(isCatalogMessage).length,
+    decision.messages.length,
+  );
+  return { ...decision, messages };
+}

package/lib/index.js

@@ -0,0 +1,215 @@
+/**
+ * dsh-skill-folder — fold the DSH skill catalog prompt surface.
+ *
+ * v0.2.0 — KV-cache-stable rewrite (fixes the net-negative dynamic trim):
+ *   - The catalog message is rendered STATICALLY (core full + all others
+ *     truncated). It depends only on the skill set, never on the per-step
+ *     query → the prompt-cache prefix stays byte-identical across turns.
+ *   - A `skill_search(intent)` tool provides on-demand retrieval (BM25 over
+ *     name + description + aliases). Tool definitions live in the static
+ *     prefix; search RESULTS append to the message tail → nothing invalidates.
+ *   - Selection quality: model searches by intent, gets top-K relevant
+ *     skills, loads the winner via the native `skill` tool. (Deferred+search
+ *     pattern; Anthropic measured 74% vs 49% accuracy over all-loaded.)
+ *
+ * Mechanism (verified against DSH host sources, see docs/system_design.md):
+ *   - @deepseek-ai/dsh-tool-skill owns the `skill` tool and the catalog
+ *     L2 publish/update/digest/history machinery. We register on
+ *     "agent/pre-step" with prepend:true → OUTERMOST in the waterfall; we
+ *     await next() → L1/L2 complete → we stabilize content[0].text while
+ *     source.entries (digest input) stays untouched.
+ *   - We never veto, never throw: any error/timeout falls back to the
+ *     untouched decision (fail-safe).
+ */
+import z from "@deepseek-ai/schemastery";
+import { trimDecision, readCatalogEntries, findCatalogMessage } from "./catalog.js";
+import { buildSkillSearchTool } from "./tool-skill-search.js";
+import { configureSemantic, buildSemanticIndex } from "./semantic.js";
+import { filterPool, routeHint } from "./skill-search.js";
+
+export const name = "skill-folder";
+export const inject = ["agents", "tools", "skills"]; // skills for skill_search snapshot
+
+/**
+ * Schemastery configuration schema — renders the plugin's settings form in the
+ * DSH settings UI. Mirrors DEFAULTS below (same pattern as dsh-tool-folder).
+ */
+export const Config = z.object({
+  enabled: z.boolean().default(true).description("总开关：启用技能折叠"),
+  core: z.array(z.string()).default(["dsh-injection-guard", "dsh-verifier"])
+    .description("P0 常驻：每轮全量描述可见（安全底线）"),
+  deny: z.array(z.string()).default(["autotelic-evolution", "dsh-team-orchestra"])
+    .description("P3 彻底封杀：精确名或 prefix*；目录不渲染 + skill_search 不可搜到"),
+  aliases: z.dict(z.array(z.string())).default({
+    "viking-memory-guide": ["记忆", "回忆", "记住", "memory", "remember"],
+    "dsh-grilling": ["访谈", "对齐", "先问我", "grilling", "问清楚", "开工前"],
+    "dsh-delegation-checklist": ["委派", "子智能体", "subagent", "delegate", "openhands"],
+    "dsh-context-language": ["术语", "词汇表", "领域语言", "context", "语言"],
+    "dsh-injection-guard": ["注入", "安全", "不可信", "injection", "外部内容"],
+    "dsh-verifier": ["验证", "检查完成", "防假完成", "verify", "验证器"],
+    "dsh-bug-diagnosis": ["排查", "诊断", "bug", "崩溃", "报错", "异常", "debug", "变慢"],
+    "dsh-two-axis-review": ["审查", "评审", "code review", "规范", "spec"],
+    "cordis-plugin-development": ["插件", "cordis", "plugin", "动态插件", "开发插件", "扩展插件"],
+    "editing-cordis-compositions": ["编排", "composition", "compose", "cordis.yml", "插件配置", "组合"],
+  }).description("意图词→技能：用于 skill_search 检索索引（BM25 加分项），中文意图可命中英文技能；别名关键词≥2 字（CJK bigram）"),
+  toolSearchEnabled: z.boolean().default(true).description("注册 skill_search 检索工具（静态前缀，结果追加消息尾部，不破坏缓存）"),
+  maxDescLength: z.number().min(0).max(500).default(100)
+    .description("动态条目描述最大长度；core 不受限"),
+  maxFoldMs: z.number().min(0).max(1000).default(5)
+    .description("裁剪耗时上限（ms），超时仅告警，结果仍放行"),
+  semanticEnabled: z.boolean().default(true).description("语义检索腿（本地 Ollama bge-m3）：skill_search 用 BM25+语义 RRF 混合，中文意图可命中英文技能"),
+  ollamaBase: z.string().default("http://127.0.0.1:11434").description("Ollama 地址（semanticEnabled 时使用）"),
+  embedModel: z.string().default("bge-m3").description("embedding 模型（semanticEnabled 时使用）"),
+  autoRoute: z.boolean().default(true).description("自动路由提示：用户消息明显指向某技能时，在消息尾部追加一行提示（不碰 catalog 前缀，不破坏 KV 缓存）"),
+});
+
+export const DEFAULTS = {
+  enabled: true,
+  core: ["dsh-injection-guard", "dsh-verifier"],
+  deny: ["autotelic-evolution", "dsh-team-orchestra"],
+  aliases: {
+    "viking-memory-guide": ["记忆", "回忆", "记住", "memory", "remember"],
+    "dsh-grilling": ["访谈", "对齐", "先问我", "grilling", "问清楚", "开工前"],
+    "dsh-delegation-checklist": ["委派", "子智能体", "subagent", "delegate", "openhands"],
+    "dsh-context-language": ["术语", "词汇表", "领域语言", "context", "语言"],
+    "dsh-injection-guard": ["注入", "安全", "不可信", "injection", "外部内容"],
+    "dsh-verifier": ["验证", "检查完成", "防假完成", "verify", "验证器"],
+    "dsh-bug-diagnosis": ["排查", "诊断", "bug", "崩溃", "报错", "异常", "debug", "变慢"],
+    "dsh-two-axis-review": ["审查", "评审", "code review", "规范", "spec"],
+    "cordis-plugin-development": ["插件", "cordis", "plugin", "动态插件", "开发插件", "扩展插件"],
+    "editing-cordis-compositions": ["编排", "composition", "compose", "cordis.yml", "插件配置", "组合"],
+  },
+  maxDescLength: 100,
+  maxFoldMs: 5,
+  toolSearchEnabled: true,
+  semanticEnabled: true, // P0-1: bge-m3 semantic leg (RRF hybrid)
+  ollamaBase: "http://127.0.0.1:11434",
+  embedModel: "bge-m3",
+  autoRoute: true, // P1: tail-appended skill routing hint (KV-safe)
+};
+
+/**
+ * @param {object} ctx - cordis context.
+ * @param {object} [config] - user config (merged over DEFAULTS).
+ * @returns {(() => void)|void} disposer (no-op when disabled).
+ */
+export function apply(ctx, config = {}) {
+  const cfg = { ...DEFAULTS, ...(config || {}) };
+  const logger = ctx.logger("skill-folder");
+  if (!cfg.enabled) {
+    logger.info("disabled by config");
+    return;
+  }
+
+  // Register the `skill_search` retrieval tool (static prefix — never
+  // invalidates the cache; results append to the message tail).
+  configureSemantic({ ollamaBase: cfg.ollamaBase, embedModel: cfg.embedModel });
+  const semIndexCache = new Map(); // pool fingerprint → Promise<semantic index>
+  const getSemIndex = (docs) => {
+    const fp = docs.map((d) => `${d.id}\u0000${d.text}`).join("\u0001");
+    if (!semIndexCache.has(fp)) {
+      semIndexCache.set(fp, buildSemanticIndex(docs));
+    }
+    return semIndexCache.get(fp);
+  };
+  const searchTool = cfg.toolSearchEnabled
+    ? buildSkillSearchTool(ctx, cfg, logger, cfg.semanticEnabled !== false ? getSemIndex : null)
+    : null;
+  if (searchTool) {
+    try {
+      ctx.tools.register(searchTool);
+      logger.info("registered skill_search tool");
+    } catch (e) {
+      logger.warn("skill_search register failed (%s) — catalog still stabilized", e?.message);
+    }
+  }
+
+  // prepend:true → outermost in the pre-step waterfall (B2). We run AFTER
+  // dsh-tool-skill L1/L2, stabilize the final decision, and pass it back.
+  const disposer = ctx.on(
+    "agent/pre-step",
+    async ({ messages, signal }, next) => {
+      // Run the rest of the waterfall (L1 /name, L2 catalog, inner).
+      const decision = await next();
+      const t0 = Date.now();
+      try {
+        let out = trimDecision(decision, cfg, logger);
+        // P1 auto-route: a user message that clearly points at one skill gets
+        // a one-line hint appended to the USER message tail (dynamic region —
+        // the catalog prefix stays byte-identical, KV cache untouched).
+        if (cfg.autoRoute !== false && out && out.kind === "enter" && Array.isArray(out.messages)) {
+          const routed = appendRouteHint(out, cfg);
+          if (routed !== out) out = routed;
+        }
+        const dt = Date.now() - t0;
+        if (dt > cfg.maxFoldMs) {
+          logger.warn("fold took %dms (> %dms) — result still applied", dt, cfg.maxFoldMs);
+        }
+        return out;
+      } catch (e) {
+        // Never throw out of a pre-step listener: fail-safe passthrough.
+        logger.warn("trim failed (%s) — passthrough", e?.message);
+        return decision;
+      }
+    },
+    true,
+  );
+
+  return () => {
+    try {
+      disposer();
+    } catch {
+      /* already disposed */
+    }
+  };
+}
+
+/**
+ * P1 auto-route (2026-08-30): append a one-line skill hint to the LAST user
+ * message when the message clearly points at one skill (alias hit or name
+ * token hit — see routeHint). Appending to the USER message tail is KV-safe:
+ * the user region is already dynamic per turn; the catalog message (prefix)
+ * is never touched. Fail-safe: any shape oddity returns the same reference.
+ * @param {object} decision - pre-step decision ({kind, messages}).
+ * @param {object} cfg - merged config (aliases/deny/autoRoute).
+ * @returns {object} same reference when nothing to add; otherwise new decision.
+ */
+export function appendRouteHint(decision, cfg) {
+  try {
+    if (!decision || decision.kind !== "enter" || !Array.isArray(decision.messages)) return decision;
+    const cat = findCatalogMessage(decision.messages);
+    if (!cat) return decision;
+    const entries = cat.entries;
+
+    let lastUser = -1;
+    for (let i = decision.messages.length - 1; i >= 0; i--) {
+      const m = decision.messages[i];
+      if (m && m.role === "user") {
+        lastUser = i;
+        break;
+      }
+    }
+    if (lastUser < 0) return decision;
+    const msg = decision.messages[lastUser];
+    const blocks = Array.isArray(msg.content) ? msg.content : [];
+    const first = blocks[0];
+    if (!first || first.type !== "text" || typeof first.text !== "string") return decision;
+    if (first.text.includes("<skill-route>")) return decision; // idempotent
+
+    const pool = filterPool(entries, cfg);
+    const hit = routeHint(pool, first.text, cfg);
+    if (!hit) return decision;
+
+    const desc = (entries.find((e) => e.name === hit) || {}).description || "";
+    const hint =
+      `\n\n<skill-route>📌 任务明显指向技能「${hit}」——可直接用 skill 工具加载：` +
+      `${desc.slice(0, 80)}${desc.length > 80 ? "…" : ""}</skill-route>`;
+    const newBlocks = Object.freeze([Object.freeze({ ...first, text: first.text + hint }), ...blocks.slice(1)]);
+    const newMsg = Object.freeze({ ...msg, content: newBlocks });
+    const messages = [...decision.messages];
+    messages[lastUser] = newMsg;
+    return { ...decision, messages };
+  } catch {
+    return decision; // never throw out of pre-step
+  }
+}

package/lib/pattern.js

@@ -0,0 +1,23 @@
+/**
+ * pattern.js — shared pattern matching (exact name or "prefix*").
+ * Used by deny / core / aliases across the plugin. Zero dependencies.
+ */
+
+/**
+ * @param {string} name
+ * @param {Array<string>} patterns
+ * @returns {boolean}
+ */
+export function matchesAnyPattern(name, patterns) {
+  if (!name || !Array.isArray(patterns) || patterns.length === 0) return false;
+  const n = String(name);
+  for (const p of patterns) {
+    const pat = String(p);
+    if (pat.endsWith("*")) {
+      if (n.startsWith(pat.slice(0, -1))) return true;
+    } else if (n === pat) {
+      return true;
+    }
+  }
+  return false;
+}

package/lib/quality-scorer.js

@@ -0,0 +1,191 @@
+/**
+ * quality-scorer.js — 技能质量评分器（方案 3）
+ *
+ * 评分维度（基于实测校准）：
+ *   - 结构完整性 (0-10): When to Use(3) + Core Pattern/Workflow(3) + Examples(2) + Overview(2)
+ *   - 示例质量 (0-5): 代码块数量
+ *   - 更新频率 (0-5): 天数
+ *   - 描述本地化 (0-5): 含中文=5, 纯英文=0
+ *
+ * 用法：
+ *   node test/quality-scorer.js              # 评分全部 118 技能并输出报告
+ *   node test/quality-scorer.js --summary    # 仅输出分布汇总
+ *   node test/quality-scorer.js --top 20     # 输出 Top 20
+ *
+ * 作为库使用：
+ *   import { scoreSkill, scoreAll } from '../lib/quality-scorer.js';
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import os from 'node:os';
+
+// Resolve the skills dir from the environment (no hard-coded local paths —
+// this module ships in the npm package).
+const SKILLS_DIR = join(process.env.DSH_HOME || join(os.homedir(), '.dsh'), 'skills');
+
+/**
+ * 对单个技能评分
+ * @param {string} dir - 技能目录路径
+ * @returns {object|null} 评分结果
+ */
+export async function scoreSkill(dir) {
+  const skillFile = join(dir, 'SKILL.md');
+  try {
+    const content = await readFile(skillFile, 'utf-8');
+    const stats = await stat(skillFile);
+    const name = content.match(/^name:\s*(.+)$/m)?.[1]?.trim() || dir.split(/[/\\]/).pop();
+
+    // === 结构完整性 (0-10) ===
+    let structureScore = 0;
+    // When to Use 相关 (3 分)
+    if (/^## When to Use/m.test(content) || /^## 何时使用/m.test(content) || /^## When to use this skill/m.test(content)) {
+      structureScore += 3;
+    }
+    // Core Pattern / Workflow / Process 相关 (3 分)
+    if (/^## Core Pattern/m.test(content) || /^## 核心模式/m.test(content) || /^## Workflow/m.test(content) || /^## 工作流/m.test(content) || /^## Process/m.test(content) || /^## Key Patterns/m.test(content)) {
+      structureScore += 3;
+    }
+    // Examples / 示例 (2 分)
+    if (/^## Examples/m.test(content) || /^## 示例/m.test(content)) {
+      structureScore += 2;
+    }
+    // Overview / 概述 (2 分)
+    if (/^## Overview/m.test(content) || /^## 概述/m.test(content)) {
+      structureScore += 2;
+    }
+
+    // === 示例质量 (0-5) ===
+    const codeBlocks = (content.match(/```[\s\S]*?```/g) || []).length;
+    const exampleScore = codeBlocks === 0 ? 0 : codeBlocks <= 2 ? 3 : codeBlocks <= 5 ? 4 : 5;
+
+    // === 更新频率 (0-5) ===
+    const daysSinceUpdate = Math.floor((Date.now() - stats.mtimeMs) / (1000 * 60 * 60 * 24));
+    const updateScore = daysSinceUpdate < 30 ? 5 : daysSinceUpdate < 90 ? 3 : daysSinceUpdate < 180 ? 2 : daysSinceUpdate < 365 ? 1 : 0;
+
+    // === 描述本地化 (0-5) ===
+    const descMatch = content.match(/^description:\s*(.+)$/m);
+    let descScore = 0;
+    if (descMatch) {
+      const desc = descMatch[1].trim();
+      // 含中文 = 5, 纯英文 = 0
+      descScore = /[一-鿿]/.test(desc) ? 5 : 0;
+    }
+
+    return {
+      name,
+      structureScore,
+      exampleScore,
+      updateScore,
+      descScore,
+      total: structureScore + exampleScore + updateScore + descScore,
+      codeBlocks,
+      daysSinceUpdate,
+      maxScore: 25,
+    };
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 评分全部技能
+ * @returns {object[]} 评分结果数组
+ */
+export async function scoreAll() {
+  const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
+  const skills = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const skill = await scoreSkill(join(SKILLS_DIR, e.name));
+    if (skill) skills.push(skill);
+  }
+  return skills;
+}
+
+// CLI 入口
+const isCLI = process.argv[1] && (
+  import.meta.url === `file://${process.argv[1]}` ||
+  import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` ||
+  import.meta.url === `file:///${process.argv[1].replace(/\\/g, '/')}`
+);
+if (isCLI) {
+  const args = process.argv.slice(2);
+  const isSummary = args.includes('--summary');
+  const topN = args.includes('--top') ? parseInt(args[args.indexOf('--top') + 1]) : null;
+
+  const skills = await scoreAll();
+
+  if (isSummary) {
+    // 仅输出分布
+    const buckets = { '0-5': 0, '6-10': 0, '11-15': 0, '16-20': 0, '21-25': 0 };
+    for (const s of skills) {
+      if (s.total <= 5) buckets['0-5']++;
+      else if (s.total <= 10) buckets['6-10']++;
+      else if (s.total <= 15) buckets['11-15']++;
+      else if (s.total <= 20) buckets['16-20']++;
+      else buckets['21-25']++;
+    }
+    const avg = skills.reduce((a, s) => a + s.total, 0) / skills.length;
+    console.log(JSON.stringify({ average: avg.toFixed(1), distribution: buckets, total: skills.length }));
+  } else if (topN) {
+    // 输出 Top N
+    const sorted = [...skills].sort((a, b) => b.total - a.total).slice(0, topN);
+    console.log(`\n## Top ${topN} 技能质量评分\n`);
+    console.log('| 排名 | 技能名 | 结构 | 示例 | 更新 | 描述 | 总分 |');
+    console.log('|------|--------|------|------|------|------|------|');
+    sorted.forEach((s, i) => {
+      console.log(`| ${i + 1} | ${s.name.slice(0, 30)} | ${s.structureScore} | ${s.exampleScore} | ${s.updateScore} | ${s.descScore} | ${s.total}/25 |`);
+    });
+  } else {
+    // 完整报告
+    const sorted = [...skills].sort((a, b) => a.total - b.total);
+    const avg = skills.reduce((a, s) => a + s.total, 0) / skills.length;
+
+    console.log('\n## 技能质量评分报告（全部 118 技能）\n');
+    console.log(`**平均分**: ${avg.toFixed(1)}/25`);
+    console.log(`**中位数**: ${sorted[Math.floor(sorted.length / 2)].total}/25`);
+
+    // 分数分布
+    const buckets = { '0-5': 0, '6-10': 0, '11-15': 0, '16-20': 0, '21-25': 0 };
+    for (const s of skills) {
+      if (s.total <= 5) buckets['0-5']++;
+      else if (s.total <= 10) buckets['6-10']++;
+      else if (s.total <= 15) buckets['11-15']++;
+      else if (s.total <= 20) buckets['16-20']++;
+      else buckets['21-25']++;
+    }
+    console.log('\n**分数分布**:');
+    for (const [bucket, count] of Object.entries(buckets)) {
+      const bar = '█'.repeat(Math.round(count / 2));
+      console.log(`  ${bucket}: ${count} ${bar}`);
+    }
+
+    // 各维度平均
+    const avgStructure = skills.reduce((a, s) => a + s.structureScore, 0) / skills.length;
+    const avgExample = skills.reduce((a, s) => a + s.exampleScore, 0) / skills.length;
+    const avgUpdate = skills.reduce((a, s) => a + s.updateScore, 0) / skills.length;
+    const avgDesc = skills.reduce((a, s) => a + s.descScore, 0) / skills.length;
+    console.log('\n**各维度平均**:');
+    console.log(`  结构完整性: ${avgStructure.toFixed(1)}/10`);
+    console.log(`  示例质量: ${avgExample.toFixed(1)}/5`);
+    console.log(`  更新频率: ${avgUpdate.toFixed(1)}/5`);
+    console.log(`  描述本地化: ${avgDesc.toFixed(1)}/5`);
+
+    // 最低分技能
+    console.log('\n## 最低分技能（Bottom 10）\n');
+    console.log('| 技能名 | 结构 | 示例 | 更新 | 描述 | 总分 |');
+    console.log('|--------|------|------|------|------|------|');
+    sorted.slice(0, 10).forEach(s => {
+      console.log(`| ${s.name.slice(0, 30)} | ${s.structureScore} | ${s.exampleScore} | ${s.updateScore} | ${s.descScore} | ${s.total}/25 |`);
+    });
+
+    // 最高分技能
+    console.log('\n## 最高分技能（Top 10）\n');
+    console.log('| 技能名 | 结构 | 示例 | 更新 | 描述 | 总分 |');
+    console.log('|--------|------|------|------|------|------|');
+    sorted.slice(-10).reverse().forEach(s => {
+      console.log(`| ${s.name.slice(0, 30)} | ${s.structureScore} | ${s.exampleScore} | ${s.updateScore} | ${s.descScore} | ${s.total}/25 |`);
+    });
+  }
+}