@icen.ai/ui 0.8.1 → 0.9.0

package/dist/behaviors/kb-hittest.mjs

@@ -0,0 +1,409 @@
+// src/behaviors/ai-core.ts
+var svg = (body) => `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
+var ICON_TERMINAL = svg('<path d="m4 17 6-6-6-6"/><path d="M12 19h8"/>');
+var ICON_FILE = svg(
+  '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/>'
+);
+var ICON_FILE_PEN = svg(
+  '<path d="M12.5 22H6a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8l5 5v3.5"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M19 6.5 16.5 4"/><path d="M21.378 16.626a1 1 0 0 0-3.004-3.004l-4.01 4.012a2 2 0 0 0-.506.854l-.837 2.87a.5.5 0 0 0 .62.62l2.87-.837a2 2 0 0 0 .854-.506z"/>'
+);
+var ICON_FILE_PLUS = svg(
+  '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M9 15h6"/><path d="M12 12v6"/>'
+);
+var ICON_TRASH = svg(
+  '<path d="M3 6h18"/><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><path d="M10 11v6"/><path d="M14 11v6"/>'
+);
+var ICON_SEARCH = svg('<circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>');
+var ICON_FOLDER_SEARCH = svg(
+  '<path d="M11 20H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h3.9a2 2 0 0 1 1.69.9l.81 1.2a2 2 0 0 0 1.67.9H20a2 2 0 0 1 2 2v4"/><circle cx="17" cy="17" r="3"/><path d="m21 21-1.9-1.9"/>'
+);
+var ICON_SCAN_SEARCH = svg(
+  '<path d="M3 7V5a2 2 0 0 1 2-2h2"/><path d="M17 3h2a2 2 0 0 1 2 2v2"/><path d="M21 17v2a2 2 0 0 1-2 2h-2"/><path d="M7 21H5a2 2 0 0 1-2-2v-2"/><circle cx="12" cy="12" r="3"/><path d="m16 16-1.9-1.9"/>'
+);
+var ICON_GLOBE = svg(
+  '<circle cx="12" cy="12" r="10"/><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20"/><path d="M2 12h20"/>'
+);
+var ICON_DOWNLOAD = svg(
+  '<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="m7 10 5 5 5-5"/><path d="M12 15V3"/>'
+);
+var ICON_BLOCKS = svg(
+  '<rect width="7" height="7" x="4" y="4" rx="1"/><rect width="7" height="7" x="13" y="4" rx="1"/><rect width="7" height="7" x="4" y="13" rx="1"/><rect width="7" height="7" x="13" y="13" rx="1"/>'
+);
+var ICON_ZAP = svg(
+  '<path d="M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z"/>'
+);
+var ICON_LIST = svg(
+  '<path d="M3 12h.01"/><path d="M3 18h.01"/><path d="M3 6h.01"/><path d="M8 12h13"/><path d="M8 18h13"/><path d="M8 6h13"/>'
+);
+var ICON_LIST_CHECKS = svg(
+  '<path d="m3 17 2 2 4-4"/><path d="m3 7 2 2 4-4"/><path d="M13 6h8"/><path d="M13 12h8"/><path d="M13 18h8"/>'
+);
+var ICON_BOT = svg(
+  '<path d="M12 8V4H8"/><rect width="16" height="12" x="4" y="8" rx="2"/><path d="M2 14h2"/><path d="M20 14h2"/><path d="M15 13v2"/><path d="M9 13v2"/>'
+);
+var ICON_CHART = svg(
+  '<path d="M3 3v18h18"/><path d="M7 15l4-6 3 4 5-8"/>'
+);
+var ICON_FILE_TEXT = svg(
+  '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M10 9H8"/><path d="M16 13H8"/><path d="M16 17H8"/>'
+);
+function isObj(v) {
+  return typeof v === "object" && v !== null;
+}
+function pickStr(input, keys) {
+  if (!isObj(input)) return void 0;
+  for (const k of keys) {
+    const v = input[k];
+    if (typeof v === "string" && v) return v;
+  }
+  return void 0;
+}
+function pickNum(src, keys) {
+  if (!isObj(src)) return void 0;
+  for (const k of keys) {
+    const v = src[k];
+    if (typeof v === "number" && Number.isFinite(v)) return v;
+  }
+  return void 0;
+}
+function firstLine(s, max = 80) {
+  const line = s.split("\n", 1)[0]?.trim() ?? "";
+  return line.length > max ? `${line.slice(0, max)}\u2026` : line;
+}
+function filePathOf(input) {
+  return pickStr(input, ["file_path", "path", "file", "filename"]);
+}
+var summarizePath = (input) => filePathOf(input);
+function summarizeRead(input) {
+  const p = filePathOf(input);
+  if (!p) return void 0;
+  const offset = pickNum(input, ["offset", "start_line"]);
+  if (offset == null) return p;
+  const limit = pickNum(input, ["limit", "end_line"]);
+  return limit != null ? `${p}:${offset}-${offset + limit}` : `${p}:${offset}`;
+}
+function summarizeShell(input) {
+  const cmd = typeof input === "string" ? input : pickStr(input, ["command", "cmd", "script"]);
+  return cmd ? firstLine(cmd) : void 0;
+}
+function summarizeGrep(input) {
+  const pattern = pickStr(input, ["pattern", "regex", "query"]);
+  const p = filePathOf(input);
+  if (pattern) return p ? `${firstLine(pattern, 40)} \xB7 ${p}` : firstLine(pattern);
+  return p;
+}
+var sum = (fn) => {
+  return (input) => fn(input) ?? "";
+};
+var BUILTIN_KINDS = {
+  shell: { label: "\u547D\u4EE4", icon: ICON_TERMINAL, tint: "accent", summarize: sum(summarizeShell) },
+  read: { label: "\u8BFB\u53D6", icon: ICON_FILE, tint: "info", summarize: sum(summarizeRead) },
+  edit: { label: "\u7F16\u8F91", icon: ICON_FILE_PEN, tint: "warning", summarize: sum(summarizePath) },
+  write: { label: "\u5199\u5165", icon: ICON_FILE_PLUS, tint: "warning", summarize: sum(summarizePath) },
+  rm: { label: "\u5220\u9664", icon: ICON_TRASH, tint: "error", summarize: sum(summarizePath) },
+  grep: { label: "\u641C\u7D22", icon: ICON_SEARCH, tint: "info", summarize: sum(summarizeGrep) },
+  glob: { label: "\u5339\u914D", icon: ICON_FOLDER_SEARCH, tint: "info", summarize: sum((i) => pickStr(i, ["pattern", "glob", "path"])) },
+  browser: { label: "\u6D4F\u89C8", icon: ICON_GLOBE, tint: "accent", summarize: sum((i) => pickStr(i, ["url", "uri", "target"])) },
+  search: { label: "\u68C0\u7D22", icon: ICON_SCAN_SEARCH, tint: "accent", summarize: sum((i) => pickStr(i, ["query", "q", "pattern"])) },
+  fetch: { label: "\u8BF7\u6C42", icon: ICON_DOWNLOAD, tint: "info", summarize: sum((i) => pickStr(i, ["url", "uri", "endpoint"])) },
+  mcp: { label: "MCP", icon: ICON_BLOCKS, tint: "muted", summarize: sum((i) => pickStr(i, ["tool", "method", "name"])) },
+  skill: { label: "\u6280\u80FD", icon: ICON_ZAP, tint: "accent", summarize: sum((i) => pickStr(i, ["skill", "name", "command"])) },
+  todo: {
+    label: "\u5F85\u529E",
+    icon: ICON_LIST,
+    tint: "info",
+    summarize: sum((input) => {
+      const items = input && typeof input === "object" && Array.isArray(input.items) ? input.items : Array.isArray(input) ? input : [];
+      const done = items.filter((it) => it?.status === "done").length;
+      return items.length > 0 ? `${done}/${items.length} \u5B8C\u6210` : "";
+    })
+  },
+  plan: { label: "\u8BA1\u5212", icon: ICON_LIST_CHECKS, tint: "info" },
+  subagent: { label: "\u5B50\u4EE3\u7406", icon: ICON_BOT, tint: "accent", summarize: sum((i) => pickStr(i, ["task", "description", "prompt", "message", "subagent_type"])) },
+  note: { label: "\u7B14\u8BB0", icon: ICON_FILE_TEXT, tint: "muted" },
+  chart: { label: "\u56FE\u8868", icon: ICON_CHART, tint: "info", summarize: sum((i) => pickStr(i, ["title", "name"])) }
+};
+var kindRegistry = new Map(Object.entries(BUILTIN_KINDS));
+function h(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+function svgIcon(svg2) {
+  if (typeof document === "undefined" || typeof DOMParser === "undefined") return null;
+  let parsed;
+  try {
+    parsed = new DOMParser().parseFromString(svg2, "image/svg+xml");
+  } catch {
+    return null;
+  }
+  const root = parsed.documentElement;
+  if (!root || root.tagName.toLowerCase() !== "svg" || parsed.querySelector("parsererror")) {
+    return null;
+  }
+  const sanitize = (el) => {
+    for (const attr of Array.from(el.attributes)) {
+      const name = attr.name.toLowerCase();
+      if (name.startsWith("on")) el.removeAttribute(attr.name);
+      if ((name === "href" || name === "xlink:href") && attr.value.trim().toLowerCase().startsWith("javascript:")) {
+        el.removeAttribute(attr.name);
+      }
+    }
+    for (const child of Array.from(el.children)) {
+      const tag = child.tagName.toLowerCase();
+      if (tag === "script" || tag === "foreignobject") {
+        child.remove();
+        continue;
+      }
+      sanitize(child);
+    }
+  };
+  sanitize(root);
+  return document.importNode(root, true);
+}
+
+// src/behaviors/kb-core.ts
+var ic = (label, d) => ({ label, icon: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">${d}</svg>` });
+var BUILTIN_SOURCE_TYPES = {
+  doc: ic("\u6587\u6863", '<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/>'),
+  web: ic("\u7F51\u9875", '<circle cx="12" cy="12" r="10"/><path d="M2 12h20"/><path d="M12 2a15 15 0 0 1 0 20 15 15 0 0 1 0-20z"/>'),
+  wiki: ic("\u77E5\u8BC6\u5E93", '<path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20"/><path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z"/>'),
+  sheet: ic("\u8868\u683C", '<rect x="3" y="3" width="18" height="18" rx="2"/><path d="M3 9h18M3 15h18M9 3v18M15 3v18"/>'),
+  db: ic("\u6570\u636E\u5E93", '<ellipse cx="12" cy="5" rx="9" ry="3"/><path d="M3 5v14c0 1.7 4 3 9 3s9-1.3 9-3V5"/><path d="M3 12c0 1.7 4 3 9 3s9-1.3 9-3"/>'),
+  ticket: ic("\u5DE5\u5355", '<path d="M3 9V7a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2v2a2 2 0 0 0 0 6v2a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-2a2 2 0 0 0 0-6z"/><path d="M13 5v14"/>'),
+  code: ic("\u4EE3\u7801", '<path d="m16 18 6-6-6-6"/><path d="m8 6-6 6 6 6"/>'),
+  api: ic("\u63A5\u53E3", '<path d="M4 7a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v3a2 2 0 0 0 0 4v3a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2v-3a2 2 0 0 0 0-4z"/>'),
+  image: ic("\u56FE\u7247", '<rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-4.6-4.6a2 2 0 0 0-2.8 0L3 21"/>'),
+  mail: ic("\u90AE\u4EF6", '<rect x="2" y="4" width="20" height="16" rx="2"/><path d="m22 7-10 7L2 7"/>')
+};
+var sourceTypeRegistry = new Map(Object.entries(BUILTIN_SOURCE_TYPES));
+function formatScore(v, digits = 3) {
+  if (v == null || !Number.isFinite(v)) return "\u2014";
+  return v.toFixed(digits).replace(/\.?0+$/, (s) => s.includes(".") ? "" : s);
+}
+function hitTestStats(cases) {
+  const ran = cases.filter((c) => c.passed !== void 0);
+  const passed = ran.filter((c) => c.passed === true);
+  const scores = ran.flatMap((c) => (c.lastHits ?? []).map((h2) => h2.score)).filter((s) => typeof s === "number");
+  return {
+    total: cases.length,
+    passed: passed.length,
+    hitRate: ran.length ? passed.length / ran.length : null,
+    avgScore: scores.length ? scores.reduce((a, b) => a + b, 0) / scores.length : null
+  };
+}
+function formatPercent(v, digits = 1) {
+  if (v == null || !Number.isFinite(v)) return "\u2014";
+  return `${(v * 100).toFixed(digits)}%`;
+}
+
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
+// src/behaviors/kb-hittest.ts
+var EXPECTED_CHIP_LIMIT = 3;
+var ICON_PIN = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 17v5"/><path d="M9 10.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V6h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1z"/></svg>';
+var ICON_RUN = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 4 14 8-14 8z"/></svg>';
+var caseSeq = 0;
+function derivePassed(c) {
+  if (!c.lastHits?.length) return void 0;
+  if (!c.expectedChunkIds?.length) return void 0;
+  const expected = new Set(c.expectedChunkIds);
+  return c.lastHits.some((hh) => expected.has(hh.chunkId));
+}
+function cloneCase(c) {
+  return {
+    ...c,
+    expectedChunkIds: c.expectedChunkIds ? [...c.expectedChunkIds] : void 0,
+    lastHits: c.lastHits?.map((hh) => ({ ...hh }))
+  };
+}
+function newCaseId() {
+  return `kbht-${++caseSeq}-${Date.now().toString(36)}`;
+}
+function renderKbHitStats(el, stats) {
+  if (typeof document === "undefined" || !el) return el;
+  el.textContent = "";
+  const box = h("div", "kb-hittest-stats");
+  const rate = h("div", "kb-hittest-stat kb-hittest-stat--rate");
+  rate.append(
+    h("span", "kb-hittest-stat-label", "\u547D\u4E2D\u7387"),
+    h("span", "kb-num kb-hittest-hitrate", formatPercent(stats.hitRate))
+  );
+  const avg = h("div", "kb-hittest-stat");
+  avg.append(
+    h("span", "kb-hittest-stat-label", "\u5747\u5206"),
+    h("span", "kb-num", formatScore(stats.avgScore))
+  );
+  const pass = h("div", "kb-hittest-stat");
+  pass.append(
+    h("span", "kb-hittest-stat-label", "\u901A\u8FC7"),
+    h("span", "kb-num", `${stats.passed}/${stats.total}`)
+  );
+  const badge = h("span", "kb-badge", "\u53C2\u6570\u4EC5\u672C\u6B21\u4F1A\u8BDD\u751F\u6548");
+  badge.title = "\u6D4B\u8BD5\u8FD0\u884C\u7684\u68C0\u7D22\u53C2\u6570\uFF08topK/\u9608\u503C/\u91CD\u6392\uFF09\u4E0D\u843D\u5E93\uFF0C\u4EC5\u672C\u6B21\u4F1A\u8BDD\u751F\u6548";
+  box.append(rate, avg, pass, badge);
+  el.appendChild(box);
+  return box;
+}
+function createKbHitTest(el, opts = {}) {
+  if (typeof document === "undefined" || !el) {
+    const stub = {
+      getCases: () => [],
+      setCases: () => {
+      },
+      run: () => {
+      },
+      destroy: () => {
+      }
+    };
+    return stub;
+  }
+  const marked = el;
+  if (marked.__icenKbHitTest) return marked.__icenKbHitTest;
+  const ctrl = new AbortController();
+  const listen = (target, type, fn) => {
+    target.addEventListener(type, fn, { signal: ctrl.signal });
+  };
+  let cases = (opts.cases ?? []).map(cloneCase);
+  let destroyed = false;
+  el.classList.add("kb-hittest");
+  el.dataset.kbHitTest = "";
+  el.textContent = "";
+  const statsBox = h("div", "kb-hittest-stats-slot");
+  const listBox = h("div", "kb-hittest-list");
+  const input = h("input", "kb-hittest-input");
+  input.type = "text";
+  input.placeholder = "\u65B0\u589E\u95EE\u9898\uFF0CEnter \u6DFB\u52A0";
+  input.setAttribute("aria-label", "\u65B0\u589E\u6D4B\u8BD5\u95EE\u9898");
+  const addBtn = h("button", "kb-hittest-add-btn", "\u6DFB\u52A0");
+  addBtn.type = "button";
+  const addRow = h("div", "kb-hittest-add");
+  addRow.append(input, addBtn);
+  const runBtn = h("button", "kb-run", "\u8FD0\u884C\u5168\u90E8");
+  runBtn.type = "button";
+  const runIcon = svgIcon(ICON_RUN);
+  if (runIcon) runBtn.prepend(runIcon);
+  el.append(statsBox, listBox, addRow, runBtn);
+  function orderedCases() {
+    return cases.map((c, i) => ({ c, i })).sort((a, b) => a.c.pinned === b.c.pinned ? a.i - b.i : a.c.pinned ? -1 : 1).map((x) => x.c);
+  }
+  function renderList() {
+    listBox.textContent = "";
+    if (!cases.length) {
+      listBox.appendChild(h("div", "kb-empty", "\u6682\u65E0\u6D4B\u8BD5\u95EE\u9898\u2014\u2014\u6DFB\u52A0\u7B2C\u4E00\u6761\uFF0C\u5F00\u59CB\u53EC\u56DE\u56DE\u5F52"));
+      return;
+    }
+    for (const c of orderedCases()) {
+      const passed = derivePassed(c);
+      const row = h("div", "kb-hittest-row");
+      if (passed === true) row.classList.add("is-pass");
+      if (passed === false) row.classList.add("is-fail");
+      const pin = h("button", "kb-hittest-pin");
+      pin.type = "button";
+      pin.title = c.pinned ? "\u53D6\u6D88\u7F6E\u9876" : "\u7F6E\u9876\u56FA\u5B9A";
+      pin.setAttribute("aria-label", pin.title);
+      pin.setAttribute("aria-pressed", c.pinned ? "true" : "false");
+      if (c.pinned) pin.classList.add("is-pinned");
+      const pinIcon = svgIcon(ICON_PIN);
+      if (pinIcon) pin.appendChild(pinIcon);
+      pin.dataset.id = c.id;
+      const q = h("span", "kb-hittest-q", c.question);
+      const expected = h("span", "kb-hittest-expected");
+      const ids = c.expectedChunkIds ?? [];
+      for (const id of ids.slice(0, EXPECTED_CHIP_LIMIT)) {
+        expected.appendChild(h("span", "kb-chip", id));
+      }
+      if (ids.length > EXPECTED_CHIP_LIMIT) {
+        expected.appendChild(h("span", "kb-chip", `+${ids.length - EXPECTED_CHIP_LIMIT}`));
+      }
+      if (!ids.length) expected.appendChild(h("span", "kb-chip", "\u672A\u8BBE\u671F\u671B"));
+      const result = h("span", "kb-hittest-result kb-num", passed === true ? "\u2713" : passed === false ? "\u2717" : "\u2014");
+      result.title = passed === void 0 ? "\u672A\u8FD0\u884C" : passed ? "\u671F\u671B\u547D\u4E2D\u5728\u524D\u6392\u547D\u4E2D\u4E2D" : "\u671F\u671B\u672A\u547D\u4E2D";
+      const remove = h("button", "kb-hittest-remove", "\xD7");
+      remove.type = "button";
+      remove.title = "\u5220\u9664\u95EE\u9898";
+      remove.setAttribute("aria-label", "\u5220\u9664\u95EE\u9898");
+      remove.dataset.id = c.id;
+      row.append(pin, q, expected, result, remove);
+      listBox.appendChild(row);
+    }
+  }
+  function renderStats() {
+    renderKbHitStats(statsBox, hitTestStats(cases.map((c) => ({ ...c, passed: derivePassed(c) }))));
+  }
+  function refresh() {
+    renderList();
+    renderStats();
+  }
+  function addQuestion() {
+    const question = input.value.trim();
+    if (!question || destroyed) return;
+    cases = [...cases, { id: newCaseId(), question }];
+    input.value = "";
+    refresh();
+    emitIcen(el, "icen:kb-hittest-add", { question });
+  }
+  listen(listBox, "click", (ev) => {
+    const target = ev.target;
+    if (!(target instanceof Element)) return;
+    const pin = target.closest(".kb-hittest-pin");
+    if (pin instanceof HTMLButtonElement) {
+      const c = cases.find((x) => x.id === pin.dataset.id);
+      if (c) {
+        c.pinned = !c.pinned;
+        refresh();
+      }
+      return;
+    }
+    const remove = target.closest(".kb-hittest-remove");
+    if (remove instanceof HTMLButtonElement) {
+      cases = cases.filter((x) => x.id !== remove.dataset.id);
+      refresh();
+    }
+  });
+  listen(input, "keydown", (ev) => {
+    const e = ev;
+    if (e.key === "Enter" && !e.isComposing) {
+      e.preventDefault();
+      addQuestion();
+    }
+  });
+  listen(addBtn, "click", () => addQuestion());
+  listen(runBtn, "click", () => handle.run());
+  refresh();
+  const handle = {
+    getCases() {
+      return cases.map((c) => cloneCase({ ...c, passed: derivePassed(c) }));
+    },
+    setCases(next) {
+      cases = (next ?? []).map(cloneCase);
+      refresh();
+    },
+    run() {
+      if (destroyed) return;
+      emitIcen(el, "icen:kb-hittest-run", {});
+      opts.onRun?.(cases.map((c) => cloneCase({ ...c, passed: derivePassed(c) })));
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      ctrl.abort();
+      el.classList.remove("kb-hittest");
+      delete el.dataset.kbHitTest;
+      el.textContent = "";
+      delete el.__icenKbHitTest;
+    }
+  };
+  marked.__icenKbHitTest = handle;
+  return handle;
+}
+export {
+  createKbHitTest,
+  renderKbHitStats
+};

package/dist/behaviors/kb-metadata.d.mts

@@ -0,0 +1,29 @@
+/** 字段类型（徽标呈现；time = 日期时间口径） */
+type KbMetadataType = 'string' | 'number' | 'time';
+/** 字段定义（builtin = 系统内置字段：值只读、不可移除） */
+interface KbMetadataField {
+    key: string;
+    type: KbMetadataType;
+    builtin?: boolean;
+    /** 展示名（缺省用 key） */
+    label?: string;
+}
+/** renderKbMetadata 数据模型 */
+interface KbMetadataModel {
+    fields: KbMetadataField[];
+    values: Record<string, string | number>;
+}
+/**
+ * 渲染元数据字段定义表 + 新增行（快照：整树重建后返回挂载容器 el）。
+ * builtin 字段值只读；自定义字段值为可编辑 input。SSR（无 document）下原样返回 el。
+ */
+declare function renderKbMetadata(el: HTMLElement, model: KbMetadataModel): HTMLElement;
+/**
+ * 接线元数据编辑（scope 级事件委托，重复调用幂等）。
+ * 值绑定 / 新增字段 / 移除字段统一派 icen:kb-metadata-change { action, key }；
+ * define/remove 同时做本地 DOM 更新（直接操纵纪律），消费方可凭事件重渲染纠偏。
+ * root 缺省 document。返回销毁函数（复位幂等标记，可重新 init）。SSR 下 no-op。
+ */
+declare function initKbMetadata(root?: ParentNode): () => void;
+
+export { type KbMetadataField, type KbMetadataModel, type KbMetadataType, initKbMetadata, renderKbMetadata };