@icen.ai/ui 0.8.0 → 0.9.0

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

@@ -0,0 +1,16 @@
+import { KbSpan } from './kb-core.js';
+import './ai-core.js';
+
+/**
+ * 渲染 trace span 树（快照：整体替换 el 内容）。返回挂载容器 el。
+ * spans 建议先经 kb-core normalizeSpans；本函数内部会再归一一次以保证父先子后与 kind/status 合法。
+ */
+declare function renderKbTrace(el: HTMLElement, spans: KbSpan[]): HTMLElement;
+/**
+ * 初始化 trace 树交互：document 级委托（click 选中+折叠；Enter/Space 展开聚焦行）。
+ * 幂等（重复调用安全）；返回销毁函数（解绑委托并复位幂等标记，销毁后可重新 init）。
+ * 委托挂 document 级：动态插入的 .kb-trace 自动接管，无需重跑 init（root 参数仅保持 kb 族 API 对称）。
+ */
+declare function initKbTrace(root?: ParentNode): () => void;
+
+export { initKbTrace, renderKbTrace };

package/dist/behaviors/kb-trace.mjs

@@ -0,0 +1,414 @@
+// 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;
+}
+
+// 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));
+var LOWER_IS_BETTER = /* @__PURE__ */ new Set(["l2"]);
+function scoreHigherIsBetter(kind) {
+  return kind != null && LOWER_IS_BETTER.has(kind) ? false : true;
+}
+function formatScore(v, digits = 3) {
+  if (v == null || !Number.isFinite(v)) return "\u2014";
+  return v.toFixed(digits).replace(/\.?0+$/, (s) => s.includes(".") ? "" : s);
+}
+function scorePercent(v, kind, max = 1) {
+  if (v == null || !Number.isFinite(v)) return null;
+  const pct = scoreHigherIsBetter(kind) ? v / max * 100 : (1 - v / max) * 100;
+  return Math.max(0, Math.min(100, pct));
+}
+function normalizeHit(raw) {
+  const score = typeof raw.score === "number" && Number.isFinite(raw.score) ? raw.score : null;
+  return {
+    chunkId: String(raw.chunkId ?? raw.id ?? ""),
+    documentId: typeof raw.documentId === "string" ? raw.documentId : void 0,
+    title: typeof raw.title === "string" ? raw.title : void 0,
+    snippet: String(raw.snippet ?? raw.content ?? ""),
+    score,
+    scoreKind: raw.scoreKind,
+    vectorPart: typeof raw.vectorPart === "number" ? raw.vectorPart : void 0,
+    keywordPart: typeof raw.keywordPart === "number" ? raw.keywordPart : void 0,
+    explain: typeof raw.explain === "string" ? raw.explain : void 0,
+    page: typeof raw.page === "number" ? raw.page : void 0,
+    meta: raw.meta && typeof raw.meta === "object" ? raw.meta : void 0
+  };
+}
+var KB_SPAN_KINDS = [
+  "retrieval",
+  "generation",
+  "rerank",
+  "embed",
+  "tool",
+  "guard",
+  "chunk",
+  "query",
+  "agent"
+];
+var SPAN_LABELS = {
+  retrieval: "\u68C0\u7D22",
+  generation: "\u751F\u6210",
+  rerank: "\u91CD\u6392",
+  embed: "\u5411\u91CF\u5316",
+  tool: "\u5DE5\u5177",
+  guard: "\u62A4\u680F",
+  chunk: "\u5207\u7247",
+  query: "\u67E5\u8BE2",
+  agent: "\u4EE3\u7406"
+};
+function kbSpanKindLabel(k) {
+  return SPAN_LABELS[k] ?? k;
+}
+function toSpanStatus(v) {
+  return v === "running" || v === "error" || v === "cancel" ? v : "done";
+}
+function normalizeSpans(raw) {
+  const spans = raw.map((r) => ({
+    id: String(r.id ?? ""),
+    parentId: typeof r.parentId === "string" ? r.parentId : void 0,
+    kind: KB_SPAN_KINDS.includes(r.kind) ? r.kind : "tool",
+    name: String(r.name ?? ""),
+    status: toSpanStatus(r.status),
+    startedAt: typeof r.startedAt === "number" || typeof r.startedAt === "string" ? r.startedAt : void 0,
+    elapsedMs: typeof r.elapsedMs === "number" ? r.elapsedMs : void 0,
+    detail: typeof r.detail === "string" ? r.detail : void 0,
+    usage: r.usage && typeof r.usage === "object" ? r.usage : void 0,
+    hits: Array.isArray(r.hits) ? r.hits.map((h2) => normalizeHit(h2)) : void 0,
+    error: typeof r.error === "string" ? r.error : void 0
+  })).filter((s) => s.id);
+  const byId = new Map(spans.map((s) => [s.id, s]));
+  return [...spans].sort((a, b) => {
+    const da = depthOf(a, byId, 0);
+    const db = depthOf(b, byId, 0);
+    return da === db ? indexIn(spans, a) - indexIn(spans, b) : da - db;
+  });
+}
+function depthOf(span, byId, guard) {
+  if (guard > 32 || !span.parentId) return 0;
+  const parent = byId.get(span.parentId);
+  return parent ? depthOf(parent, byId, guard + 1) + 1 : 0;
+}
+function indexIn(spans, target) {
+  const i = spans.findIndex((s) => s.id === target.id);
+  return i === -1 ? spans.length : i;
+}
+
+// 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-trace.ts
+var ROOT_KEY = "\0root";
+function fmtElapsed(ms) {
+  if (ms == null || !Number.isFinite(ms)) return "\u2014";
+  return ms < 1e3 ? `${Math.round(ms)}ms` : `${(ms / 1e3).toFixed(1)}s`;
+}
+function depthOfSpan(span, byId, guard = 0) {
+  if (guard > 32 || !span.parentId) return 0;
+  const parent = byId.get(span.parentId);
+  return parent ? depthOfSpan(parent, byId, guard + 1) + 1 : 0;
+}
+function buildHitRow(hit, rank) {
+  const row = h("div", "kb-trace-hit");
+  row.append(h("span", "kb-trace-hit-rank kb-num", String(rank)));
+  row.append(h("span", "kb-trace-hit-title", hit.title || hit.snippet || hit.chunkId));
+  const score = h("span", "kb-score");
+  const bar = h("span", "kb-score-bar");
+  const fill = h("i");
+  const pct = scorePercent(hit.score, hit.scoreKind);
+  fill.style.width = pct != null ? `${pct}%` : "0%";
+  bar.append(fill);
+  score.append(bar, h("span", "kb-score-value", formatScore(hit.score)));
+  row.append(score);
+  return row;
+}
+function buildSpanBody(span) {
+  const usage = span.usage;
+  const hasUsage = !!(usage && (usage.inputTokens != null || usage.outputTokens != null || usage.costUsd != null));
+  const hasHits = span.kind === "retrieval" && !!span.hits && span.hits.length > 0;
+  if (!span.detail && !hasUsage && !hasHits && !span.error) return null;
+  const body = h("div", "kb-trace-body kb-fold-body");
+  if (span.detail) body.append(h("div", "kb-trace-detail", span.detail));
+  if (hasUsage && usage) {
+    const u = h("div", "kb-trace-usage");
+    if (usage.inputTokens != null) u.append(h("span", "kb-num", `\u2191 ${usage.inputTokens} tok`));
+    if (usage.outputTokens != null) u.append(h("span", "kb-num", `\u2193 ${usage.outputTokens} tok`));
+    if (usage.costUsd != null) u.append(h("span", "kb-num", `$${formatScore(usage.costUsd, 4)}`));
+    body.append(u);
+  }
+  if (hasHits && span.hits) {
+    const wrap = h("div", "kb-trace-hits");
+    wrap.append(h("div", "kb-trace-hits-label kb-meta", `\u547D\u4E2D ${span.hits.length}`));
+    span.hits.forEach((hit, i) => wrap.append(buildHitRow(hit, i + 1)));
+    body.append(wrap);
+  }
+  if (span.error) body.append(h("div", "kb-trace-error", span.error));
+  return body;
+}
+function applyTraceVisibility(trace) {
+  const rows = Array.from(trace.querySelectorAll(":scope > .kb-span"));
+  const byId = new Map(rows.map((r) => [r.dataset.spanId ?? "", r]));
+  for (const row of rows) {
+    const parent = row.dataset.parentId ? byId.get(row.dataset.parentId) : void 0;
+    row.hidden = parent ? parent.hidden || parent.getAttribute("aria-expanded") === "false" : false;
+    const next = row.nextElementSibling;
+    if (next instanceof HTMLElement && next.classList.contains("kb-trace-body")) {
+      next.hidden = row.hidden || row.getAttribute("aria-expanded") === "false";
+    }
+  }
+}
+function toggleSpanRow(trace, row) {
+  if (row.getAttribute("aria-expanded") == null) return;
+  const open = row.getAttribute("aria-expanded") !== "true";
+  row.setAttribute("aria-expanded", String(open));
+  row.classList.toggle("is-open", open);
+  applyTraceVisibility(trace);
+  emitIcen(trace, "icen:kb-trace-toggle", { spanId: row.dataset.spanId ?? "", open });
+}
+var bodyUid = 0;
+function renderKbTrace(el, spans) {
+  if (typeof document === "undefined") return el;
+  const list = normalizeSpans(spans);
+  el.className = "kb-trace";
+  el.replaceChildren();
+  if (!list.length) {
+    el.append(h("div", "kb-empty", "\u6682\u65E0\u8C03\u7528\u94FE\u6570\u636E"));
+    return el;
+  }
+  const byId = new Map(list.map((s) => [s.id, s]));
+  const childIds = new Set(list.filter((s) => s.parentId && byId.has(s.parentId)).map((s) => s.parentId));
+  const maxByParent = /* @__PURE__ */ new Map();
+  for (const s of list) {
+    const key = s.parentId && byId.has(s.parentId) ? s.parentId : ROOT_KEY;
+    const v = typeof s.elapsedMs === "number" && s.elapsedMs > 0 ? s.elapsedMs : 0;
+    if (v > (maxByParent.get(key) ?? 0)) maxByParent.set(key, v);
+  }
+  for (const span of list) {
+    const depth = depthOfSpan(span, byId);
+    const key = span.parentId && byId.has(span.parentId) ? span.parentId : ROOT_KEY;
+    const max = maxByParent.get(key) ?? 0;
+    const ms = typeof span.elapsedMs === "number" && span.elapsedMs > 0 ? span.elapsedMs : 0;
+    const width = max > 0 && ms > 0 ? Math.max(2, ms / max * 100) : 0;
+    const hasKids = childIds.has(span.id);
+    const body = buildSpanBody(span);
+    const expandable = hasKids || body != null;
+    const open = expandable && (span.status === "error" || span.status === "running");
+    const row = h("div", `kb-span kb-span--${depth > 0 ? "child" : "root"} is-${span.kind} is-${span.status}`);
+    if (open) row.classList.add("is-open");
+    row.dataset.spanId = span.id;
+    if (span.parentId) row.dataset.parentId = span.parentId;
+    row.style.setProperty("--depth", String(depth));
+    row.tabIndex = 0;
+    row.setAttribute("role", "button");
+    if (expandable) row.setAttribute("aria-expanded", String(open));
+    const caret = h("span", "kb-span-caret");
+    caret.setAttribute("aria-hidden", "true");
+    caret.hidden = !hasKids;
+    row.append(
+      caret,
+      h("span", "kb-span-kind", kbSpanKindLabel(span.kind)),
+      h("span", "kb-span-name", span.name)
+    );
+    const bar = h("i", "kb-span-bar");
+    bar.style.width = `${width}%`;
+    row.append(bar, h("span", "kb-num", fmtElapsed(span.elapsedMs)));
+    el.append(row);
+    if (body) {
+      body.dataset.for = span.id;
+      body.style.setProperty("--depth", String(depth));
+      if (expandable) {
+        body.id = `kb-trace-body-${++bodyUid}`;
+        row.setAttribute("aria-controls", body.id);
+      }
+      body.hidden = !open;
+      el.append(body);
+    }
+  }
+  applyTraceVisibility(el);
+  return el;
+}
+var traceInit = false;
+var traceTeardown = null;
+function initKbTrace(root) {
+  if (typeof document === "undefined" || traceInit) return () => {
+  };
+  traceInit = true;
+  const rowOf = (e) => {
+    const target = e.target;
+    if (!(target instanceof Element)) return null;
+    const row = target.closest(".kb-span");
+    if (!row) return null;
+    const trace = row.closest(".kb-trace");
+    return trace ? { row, trace } : null;
+  };
+  const onClick = (e) => {
+    const hit = rowOf(e);
+    if (!hit) return;
+    emitIcen(hit.trace, "icen:kb-trace-select", { spanId: hit.row.dataset.spanId ?? "" });
+    toggleSpanRow(hit.trace, hit.row);
+  };
+  const onKey = (e) => {
+    if (e.key !== "Enter" && e.key !== " ") return;
+    const hit = rowOf(e);
+    if (!hit || hit.row !== e.target) return;
+    e.preventDefault();
+    toggleSpanRow(hit.trace, hit.row);
+  };
+  document.addEventListener("click", onClick);
+  document.addEventListener("keydown", onKey);
+  traceTeardown = () => {
+    document.removeEventListener("click", onClick);
+    document.removeEventListener("keydown", onKey);
+    traceInit = false;
+    traceTeardown = null;
+  };
+  return traceTeardown;
+}
+export {
+  initKbTrace,
+  renderKbTrace
+};

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

@@ -0,0 +1,44 @@
+import { KbVisibility, KbIdentity } from './kb-core.js';
+import './ai-core.js';
+
+/** 对照命中的最小数据单元（标题必有；snippet=原文摘录 / summary=AI 摘要，二者权限语义不同） */
+interface KbVisibilityHit {
+    id: string;
+    title: string;
+    /** 原文摘录（visibility=full 时呈现） */
+    snippet?: string;
+    /** AI 摘要（visibility=summary 时呈现；摘要权限 ≠ 原文权限） */
+    summary?: string;
+    documentId?: string;
+}
+/** renderKbVisibility 配置项 */
+interface KbVisibilityOpts {
+    /** 查询回显（只读展示，不提供输入） */
+    query: string;
+    /** 对照身份集（固定身份集，spec §9.0-8：来自服务端验证 token，不接受自由输入） */
+    identities: KbIdentity[];
+    /** 对照命集（各身份列共享同一批行，行的去留由 evaluateHit 决定） */
+    hits: KbVisibilityHit[];
+    /** 命中×身份 → 可见性五级；缺省全部 'full'（演示语义，真实求值由宿主注入） */
+    evaluateHit?: (hit: KbVisibilityHit, identity: KbIdentity) => KbVisibility;
+    /** 过滤层徽标初值（缺省 'pre'；点击循环 pre→post→none） */
+    layer?: 'pre' | 'post' | 'none';
+    /** 「申请访问」文字钮回调（宿主接 kb-access 申请流；展示件不派申请事件） */
+    onRequest?: (hit: KbVisibilityHit, identity: KbIdentity) => void;
+}
+/** renderKbVisibility 返回的可操作句柄 */
+interface KbVisibilityHandle {
+    /** 设置过滤层（重绘徽标并派 icen:kb-visibility-layer {layer}） */
+    setFilterLayer(l: 'pre' | 'post' | 'none'): void;
+    /** 查询某身份×命中的可见性（查无身份/命中返回 'hidden'——fail-closed，spec §9.0-4） */
+    getVisibility(identityUser: string, hitId: string): KbVisibility;
+    /** 销毁：摘除监听、清空装配内容、复位幂等标记 */
+    destroy(): void;
+}
+/**
+ * 渲染检索可见性对照器（admin 审计专用；每身份一列 + 安全计数 + 五级命中行 + 教学段）。
+ * 幂等（同元素重复 render 先销毁既有装配）；SSR 返回静态 stub；destroy 摘监听并清空。
+ */
+declare function renderKbVisibility(el: HTMLElement, opts: KbVisibilityOpts): KbVisibilityHandle;
+
+export { type KbVisibilityHandle, type KbVisibilityHit, type KbVisibilityOpts, renderKbVisibility };