dsh-visualkit 0.0.0-stage → 0.0.1

package/icon.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 256 256" fill="none" role="img" aria-label="视觉设计工具箱">
+  <defs>
+    <linearGradient id="dsh-pk" x1="28" y1="28" x2="228" y2="228" gradientUnits="userSpaceOnUse"><stop stop-color="#F43F5E"/><stop offset="1" stop-color="#DB2777"/></linearGradient>
+    <linearGradient id="dsh-fu" x1="48" y1="88" x2="136" y2="128" gradientUnits="userSpaceOnUse"><stop stop-color="#D946EF"/><stop offset="1" stop-color="#C026D3"/></linearGradient>
+    <linearGradient id="dsh-vi" x1="142" y1="70" x2="208" y2="158" gradientUnits="userSpaceOnUse"><stop stop-color="#A855F7"/><stop offset="1" stop-color="#7C3AED"/></linearGradient>
+  </defs>
+  <rect x="28" y="28" width="200" height="200" rx="46" fill="none" stroke="url(#dsh-pk)" stroke-width="12"/>
+  <rect x="48" y="48" width="106" height="14" rx="7" fill="url(#dsh-pk)"/>
+  <rect x="48" y="70" width="62" height="7" rx="3.5" fill="#EC4899"/>
+  <rect x="48" y="88" width="78" height="6" rx="3" fill="url(#dsh-fu)"/>
+  <rect x="48" y="104" width="66" height="6" rx="3" fill="url(#dsh-fu)"/>
+  <rect x="48" y="120" width="52" height="6" rx="3" fill="url(#dsh-fu)"/>
+  <rect x="142" y="70" width="66" height="88" rx="10" fill="url(#dsh-vi)"/>
+  <circle cx="167" cy="93" r="6.5" fill="#FDE68A"/>
+  <path d="M158 140l11-15 7 9 5-6 8 12z" fill="#EDE9FE"/>
+  <g fill="#F5F3FF">
+    <rect x="148" y="76" width="8" height="8" rx="2"/>
+    <rect x="194" y="76" width="8" height="8" rx="2"/>
+    <rect x="148" y="144" width="8" height="8" rx="2"/>
+    <rect x="194" y="144" width="8" height="8" rx="2"/>
+  </g>
+  <rect x="48" y="168" width="22" height="22" rx="7" fill="#EC4899"/>
+  <rect x="76" y="168" width="22" height="22" rx="7" fill="#D946EF"/>
+  <rect x="104" y="168" width="22" height="22" rx="7" fill="#A855F7"/>
+  <rect x="132" y="168" width="22" height="22" rx="7" fill="#D97706"/>
+</svg>

package/lib/assets.js

@@ -0,0 +1,228 @@
+/**
+ * assets.js — design_render action=asset 的实现：内置素材库检索 / 内联 / 改色。
+ *
+ * 素材在插件包内（data/assets，5.8MB / 221 项，已去掉缩略图）。
+ * 不依赖外部素材工作区的绝对路径——这是「独立插件」的关键一步。
+ *
+ * 安全：所有路径都经 resolve 后校验是否仍在素材目录内，挡目录穿越。
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync, statSync } from "node:fs";
+import { dirname, extname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ASSETS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "data", "assets");
+const MANIFEST = join(ASSETS_DIR, "manifest.json");
+
+let cache = null;
+
+async function loadManifest() {
+	if (cache !== null) return cache;
+	let raw;
+	try {
+		raw = await readFile(MANIFEST, "utf8");
+	} catch (error) {
+		throw new Error(`素材 manifest 不可读：${MANIFEST}（${error?.message ?? error}）`);
+	}
+	const parsed = JSON.parse(raw);
+	cache = Array.isArray(parsed.items) ? parsed.items : [];
+	return cache;
+}
+
+/** 关键词检索：name / category / desc / file 四处子串匹配，名字命中优先。 */
+async function find(keyword, limit = 20) {
+	const items = await loadManifest();
+	const query = String(keyword ?? "").trim().toLowerCase();
+	if (query === "") return { total: items.length, items: items.slice(0, limit) };
+	// 中文检索词的口语同义词：用户说「模式」指图案、「底纹」指纹理，「模式」直搜 total:0
+	// 会让人以为素材库里没有图案。只做小范围、无歧义的设计词汇映射。
+	const SYNONYMS = {
+		模式: ["图案"],
+		纹样: ["图案"],
+		花纹: ["图案"],
+		底纹: ["纹理"],
+		标志: ["品牌图标"],
+		logo: ["品牌图标"],
+		avatar: ["角色部件"],
+		插图: ["插画"]
+	};
+	const variants = [...new Set([query, ...(SYNONYMS[query] ?? []).map((v) => String(v).toLowerCase())])];
+	const scored = [];
+	for (const item of items) {
+		const name = String(item.name ?? "").toLowerCase();
+		const category = String(item.category ?? "").toLowerCase();
+		const desc = String(item.desc ?? "").toLowerCase();
+		const file = String(item.file ?? "").toLowerCase();
+		let score = Infinity;
+		for (const q of variants) {
+			let s = Infinity;
+			if (name === q) s = 0;
+			else if (name.startsWith(q)) s = 1;
+			else if (name.includes(q)) s = 2;
+			else if (category.includes(q)) s = 3;
+			else if (desc.includes(q)) s = 4;
+			else if (file.includes(q)) s = 5;
+			if (s < score) score = s;
+			if (score === 0) break;
+		}
+		if (score !== Infinity) scored.push({ score, item });
+	}
+	scored.sort((a, b) => a.score - b.score || String(a.item.name).localeCompare(String(b.item.name)));
+	return { total: scored.length, items: scored.slice(0, limit).map((s) => s.item) };
+}
+
+/** 把素材库相对路径解析成绝对路径，越界即拒。 */
+function resolveInside(rel) {
+	const wanted = String(rel ?? "").trim();
+	if (wanted === "") throw new Error("rel is required（素材库相对路径，如 icons/brands/github.svg）");
+	const full = resolve(ASSETS_DIR, wanted);
+	if (full !== ASSETS_DIR && !full.startsWith(ASSETS_DIR + sep)) {
+		throw new Error(`路径越界：${wanted} 不在素材库内`);
+	}
+	if (!existsSync(full)) throw new Error(`素材不存在：${wanted}（用 action=asset mode=find 检索）`);
+	return full;
+}
+
+/** inline/save 只对矢量素材有意义：位图（.png）读成 utf8 是乱码，
+ * 还会伪造一个 viewBox 冒充 SVG（实测 48 个 png 素材都会中招）。 */
+function resolveSvg(rel) {
+	const file = resolveInside(rel);
+	let isDir = false;
+	try {
+		isDir = statSync(file).isDirectory();
+	} catch {
+		isDir = false;
+	}
+	if (isDir) throw new Error(`${rel} 是一个目录：inline/save 需要具体文件路径（先 mode=find 检索）`);
+	if (extname(file).toLowerCase() !== ".svg") {
+		throw new Error(`${rel} 不是 SVG（${extname(file) || "无扩展名"}）：inline/save 只处理矢量素材；位图请直接引用素材库路径`);
+	}
+	return file;
+}
+
+/**
+ * 改色：三层处理，覆盖素材库里实际存在的三种写法。
+ *   1. currentColor → 直接替换（我们自己的图标都走这个）
+ *   2. fill/stroke 具体色值 → 替换值，不动结构（不误伤 <path d> 里的坐标）
+ *   3. 图形根本没有 fill/stroke（simple-icons 的 12 个品牌图就这么写，靠浏览器默认黑填充）
+ *      → 必须把颜色下推到每个图形元素；只给根 <svg> 加 fill 会在 inline 剥壳后丢失
+ */
+const COLOR_RE = /^[\w#(),.%+\- ]+$/;
+
+function recolor(svg, color) {
+	if (color === undefined || color === null || String(color).trim() === "") return svg;
+	const wanted = String(color).trim();
+	// 颜色会被拼进 SVG 属性：不校验就只能任由 `red"/><script>` 注入新标签
+	// （inline 结果会内联进页面，save 产物会被直接打开）。
+	if (!COLOR_RE.test(wanted)) {
+		throw new Error(`color 含不允许的字符（收到 "${wanted}"）——仅接受 #hex / rgb() / 命名色等颜色写法`);
+	}
+	let out = svg;
+	if (out.includes("currentColor")) {
+		out = out.split("currentColor").join(wanted);
+	}
+	out = out.replace(/(fill|stroke)\s*=\s*"([^"]*)"/gi, (whole, attr, value) => {
+		const v = String(value).trim().toLowerCase();
+		if (v === "none" || v === "transparent" || v === "" || v.startsWith("url(")) return whole;
+		return `${attr}="${wanted}"`;
+	});
+	const SHAPE = /<(path|circle|rect|ellipse|polygon|polyline)\b((?:"[^"]*"|[^>"])*)>/g;
+	const hasPaint = /<(path|circle|rect|ellipse|polygon|polyline)\b[^>]*\b(fill|stroke)\s*=/.test(out);
+	if (!hasPaint) {
+		out = out.replace(SHAPE, (whole, tag, attrs) => (/(^|\s)(fill|stroke)\s*=/.test(attrs) ? whole : `<${tag}${attrs} fill="${wanted}">`));
+	}
+	return out;
+}
+
+/** 剥掉 <svg> 外壳，取内部内容并计算 viewBox。
+ * 同时去掉 <title>/<desc>：inline 的用途是嵌进外层 SVG，外层通常自带可达性标签，
+ * 留着会在最终页面里出现重复标题。 */
+function innerOf(svg) {
+	const open = svg.match(/<svg\b[^>]*>/i);
+	if (open === null) return { inner: svg.trim(), viewBox: undefined };
+	const close = svg.toLowerCase().lastIndexOf("</svg>");
+	const start = svg.indexOf(open[0]) + open[0].length;
+	const end = close === -1 ? svg.length : close;
+	const vb = open[0].match(/viewBox\s*=\s*"([^"]*)"/i);
+	const inner = svg
+		.slice(start, end)
+		.replace(/<title\b[^>]*>[\s\S]*?<\/title>/gi, "")
+		.replace(/<desc\b[^>]*>[\s\S]*?<\/desc>/gi, "")
+		.trim();
+	return { inner, viewBox: vb ? vb[1] : undefined };
+}
+
+/**
+ * action=asset：
+ *   mode=find   检索（默认）
+ *   mode=inline 返回内联内容（可改色），用于嵌进外层 SVG —— 不嵌 <svg> 壳
+ *   mode=save   整篇改色后落盘，返回输出路径
+ */
+async function asset({ mode = "find", keyword, rel, color, saveTo, limit }) {
+	if (mode === "find") {
+		const result = await find(keyword, limit ?? 20);
+		return { mode, keyword: keyword ?? "", total: result.total, items: result.items };
+	}
+	if (mode === "inline") {
+		const file = resolveSvg(rel);
+		const svg = recolor(await readFile(file, "utf8"), color);
+		const { inner, viewBox } = innerOf(svg);
+		const item = (await loadManifest()).find((entry) => entry.file === String(rel).split(sep).join("/"));
+		// 内联内容直接进模型上下文：大图（如 openpeeps 插画 65KB）会吃掉上万 token。
+		// 截断必须在元素边界切（lastIndexOf "/>"），否则返回半截标签根本不能用；
+		// 同时 note 必须如实说「已截断」——旧实现只置 truncated 标记却返回全文，是谎报。
+		const INLINE_LIMIT = 20000;
+		let shown = inner;
+		let truncated = false;
+		if (inner.length > INLINE_LIMIT) {
+			// 优先切在自闭合元素结束处（"/>"）；openpeeps 那种 `<path …></path>` 写法
+			// 前两万字符里一个 "/>" 都没有，再退到任意标签结束的 ">" 上——总之不能切在
+			// 属性值中间（否则返回半截 path 数据，note 声称“到元素边界”就是谎报）。
+			const slash = inner.lastIndexOf("/>", INLINE_LIMIT - 2);
+			let cutEnd = slash > 0 ? slash + 2 : -1;
+			if (cutEnd < 0) {
+				const gt = inner.lastIndexOf(">", INLINE_LIMIT - 1);
+				cutEnd = gt > 0 ? gt + 1 : -1;
+			}
+			shown = cutEnd > 0 ? inner.slice(0, cutEnd) : inner.slice(0, INLINE_LIMIT);
+			truncated = true;
+		}
+		return {
+			mode,
+			rel,
+			...(item !== undefined ? { name: item.name, license: item.license, category: item.category } : {}),
+			viewBox: viewBox ?? "0 0 24 24",
+			inner: shown,
+			truncated,
+			bytes: Buffer.byteLength(svg, "utf8"),
+			...(truncated
+				? { note: `内联内容 ${inner.length} 字符超过 ${INLINE_LIMIT}，已截断到标签边界（可能是部分元素树，仅供预览）；需要完整文件请用 mode=save 落盘` }
+				: {})
+		};
+	}
+	if (mode === "save") {
+		if (typeof saveTo !== "string" || saveTo.trim() === "") throw new Error("mode=save 需要 saveTo");
+		const file = resolveSvg(rel);
+		const svg = recolor(await readFile(file, "utf8"), color);
+		await mkdir(dirname(saveTo), { recursive: true });
+		await writeFile(saveTo, svg, "utf8");
+		return { mode, rel, path: saveTo, bytes: Buffer.byteLength(svg, "utf8"), color: color ?? null };
+	}
+	throw new Error(`unknown mode "${mode}"（find / inline / save）`);
+}
+
+/** 素材库概况（供工具描述与自检用）。 */
+async function summary() {
+	const items = await loadManifest();
+	const categories = new Map();
+	for (const item of items) {
+		const key = item.category ?? "未分类";
+		categories.set(key, (categories.get(key) ?? 0) + 1);
+	}
+	return {
+		count: items.length,
+		categories: [...categories.entries()].map(([name, count]) => ({ name, count }))
+	};
+}
+
+export { asset, find, innerOf, recolor, summary };

package/lib/audit.js

@@ -0,0 +1,284 @@
+/**
+ * audit.js — ui_audit 的实现核心：按项目预设巡检图标规范。
+ *
+ * echo 预设（规则出处 frontend/STYLE_GUIDE.md §3）：
+ *   E1 emoji 禁用：src 下 vue/js/ts/html 文本扫描 pictographic 区段，违例即报
+ *   E2 静态图标误用 MorphIcon：<MorphIcon :icon=...> 绑定里没有条件表达式的报 review
+ * colibri 预设（规则出处 界面设计规范 §12.5 + js/ui.js）：
+ *   C1 ICONS 字典自检：每条 inner 必须能被 parseIconNodes 解析
+ *   C2 引用核对：模板 data-morph="x" / JS morphTo(el,'x') / UI.svg('x') /
+ *      UI.morphIcon('x') 的字面量引用必须存在于字典
+ *   C3 动态引用（变量传名）报 info，提示人工核对
+ */
+import { open, readFile, readdir, stat } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { parseIconNodes } from "./svg.js";
+
+// 测试/样本目录不参与巡检：硬规则（"图标一律 SVG"）不能因为仓库里放了带 emoji 的
+// fixture 就报错——实测把本包自己扫出 55 个 error，全是 test/ 里故意写的样本。
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "vendor", ".uilab-previews", "coverage", "test", "tests", "__tests__", "fixtures", "spec"]);
+const PER_FILE_CAP = 2 * 1024 * 1024;
+// 审查修复 #278：逐文件串行读盘 → 按批并发读取（各文件相互独立；批内逐文件
+// 处理、截断与 break 语义不变——最多多读一小批文件，readCapped 无副作用）
+const READ_CHUNK = 16;
+
+/** pictographic emoji + 符号区段（含变体选择符），排除普通箭头/中文标点。
+ * codereview #480：区域指示符区段 \u{1F1E6}-\u{1F1FF} 已被 \u{1F000}-\u{1FAFF}
+ * 完全覆盖（1F1E6 ≥ 1F000 且 1F1FF ≤ 1FAFF），原并列写出是冗余残留，已删。 */
+const EMOJI_RE = /[\u{1F000}-\u{1FAFF}\u{2600}-\u{27BF}\u{2B00}-\u{2BFF}\u{FE0F}]/u;
+
+async function walk(root, { maxFiles = 4000, exts, subdirs }) {
+	const out = [];
+	// 单文件 root：taste_check 的参数描述是「File or directory」，旧实现直接 readdir
+	// 一个文件 → ENOTDIR 被 catch 吞掉 → 返回 0 个文件（巡检静默失效）。
+	try {
+		const info = await stat(root);
+		if (info.isFile()) {
+			const okExt = exts.some((x) => root.endsWith(x)) && !root.endsWith(".min.js") && !root.endsWith(".map");
+			return okExt ? [root] : [];
+		}
+	} catch {
+		return out;
+	}
+	const queue = [];
+	const roots = subdirs ? subdirs.map((d) => join(root, d)) : [root];
+	for (const r of roots) if (existsSync(r)) queue.push(r);
+	while (queue.length > 0 && out.length < maxFiles) {
+		const dir = queue.shift();
+		let entries;
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const e of entries) {
+			const full = join(dir, e.name);
+			if (e.isDirectory()) {
+				if (!SKIP_DIRS.has(e.name) && !e.name.startsWith(".")) queue.push(full);
+			} else if (e.isFile() && exts.some((x) => e.name.endsWith(x)) && !e.name.endsWith(".min.js") && !e.name.endsWith(".map")) {
+				out.push(full);
+				if (out.length >= maxFiles) break;
+			}
+		}
+	}
+	return out;
+}
+
+async function readCapped(file) {
+	try {
+		const s = await stat(file);
+		if (!s.isFile()) return null;
+		if (s.size <= PER_FILE_CAP) return await readFile(file, "utf8");
+		// 超过上限的文件不能直接跳过：它仍会被算进 filesScanned，跳过等于“报了扫描数却没真扫”。
+		// 读前 PER_FILE_CAP 字节继续扫（构建产物/压缩包常是大文件，前面的 emoji 同样违规）。
+		const handle = await open(file, "r");
+		try {
+			const buf = Buffer.alloc(PER_FILE_CAP);
+			const { bytesRead } = await handle.read(buf, 0, PER_FILE_CAP, 0);
+			return buf.subarray(0, bytesRead).toString("utf8");
+		} finally {
+			await handle.close();
+		}
+	} catch {
+		return null;
+	}
+}
+
+function lineOf(text, index) {
+	return text.slice(0, index).split("\n").length;
+}
+
+/** root 本身就是被扫文件时，relative(root, root) 是空串——报告里会变成 "U1 :1"。
+ * 退回文件名，单文件巡检才能看出是哪个文件。 */
+function relOf(root, file) {
+	const rel = relative(root, file);
+	return rel === "" ? basename(root) : rel;
+}
+
+async function auditEcho(root, limits) {
+	const findings = [];
+	// Echo 项目根可能是仓库根（frontend/ 子目录）或前端根（直接含 src/）
+	const base = existsSync(join(root, "frontend")) ? join(root, "frontend") : root;
+	const files = await walk(base, { maxFiles: limits.maxFiles, exts: [".vue", ".js", ".ts", ".html"], subdirs: ["src"] });
+	if (files.length === 0) findings.push({ severity: "warn", rule: "E0", file: relative(root, base) || ".", line: 0, message: "src/ 下没有扫到 vue/js/ts/html 文件——确认 root 是否为 Echo 项目根目录（frontend 之下应含 src/）" });
+	for (let i = 0; i < files.length; i += READ_CHUNK) {
+		const batch = files.slice(i, i + READ_CHUNK);
+		const texts = await Promise.all(batch.map((f) => readCapped(f)));
+		for (let k = 0; k < batch.length; k += 1) {
+			const text = texts[k];
+			if (text === null) continue;
+			const rel = relOf(root, batch[k]);
+			// E1 emoji 禁用
+			for (const m of text.matchAll(new RegExp(EMOJI_RE.source, "gu"))) {
+				const idx = m.index ?? 0;
+				findings.push({ severity: "error", rule: "E1", file: rel, line: lineOf(text, idx), message: `emoji "${m[0]}" —— STYLE_GUIDE §3 全面禁用（图标全部 SVG）` });
+				if (findings.length > limits.maxFindings) break;
+			}
+			// E2 MorphIcon 静态装载（review 级：绑定是否两态由人判断）
+			// 审查修复 #276：标签匹配跳过引号段（绑定表达式含 > 的箭头函数不再
+			// 提前截断标签）；:icon 兼容单/双引号；两态判定收紧为成对三元（? … :）
+			// ——可选链 a?.b、取反 !x 不再被当作两态条件而漏报
+			for (const m of text.matchAll(/<MorphIcon\b(?:"[^"]*"|'[^']*'|[^>"'])*>/gs)) {
+				const tag = m[0].replace(/\s+/g, " ");
+				const icon = tag.match(/:icon\s*=\s*(["'])((?:(?!\1)[\s\S])*)\1/);
+				// 先剔除可选链 `?.` 与空值合并 `??`，再要求“? … :”成对出现：
+				// 否则 :icon="props?.icon" 这类静态绑定会被错误当成两态（E2 误报）。
+				const iconExpr = icon ? icon[2].replace(/\?\./g, "").replace(/\?\?/g, "") : "";
+				if (icon && !/[^?]\?[^?:]*:/.test(iconExpr)) {
+					findings.push({ severity: "warn", rule: "E2", file: rel, line: lineOf(text, m.index ?? 0), message: `<MorphIcon :icon="${icon[2]}"> 绑定无两态条件——静态图标不得用 MorphIcon 装载（走 n-icon + vicons）` });
+				}
+			}
+		}
+		if (findings.length > limits.maxFindings * 2) break;
+	}
+	return { preset: "echo", root, filesScanned: files.length, findings };
+}
+
+function extractColibriDict(uiJsPath) {
+	// 审查修复 #277：readFileSync 兜底——existsSync 与读取之间的竞态、EACCES、
+	// EMFILE 不再裸抛出 audit()（与 readCapped/walk 的防御口径一致，失败走 C0 路径）
+	let text;
+	try {
+		text = readFileSync(uiJsPath, "utf8");
+	} catch {
+		return { dict: null };
+	}
+	const block = text.match(/const ICONS = \{([\s\S]*?)\n\s*\};/);
+	if (block === null) return { dict: null };
+	const dict = {};
+	// 审查修复 #279：条目值兼容单/双引号（双引号条目原先被静默丢弃，其引用会
+	// 成串误报 C2「不在字典」）；键锚定行首（允许缩进）——降低匹配到值内部
+	// xxx:'yyy' 片段注入假条目的风险
+	const re = /^[ \t]*(\w+)\s*:\s*(["'])((?:\\.|(?!\2)[^\\])*)\2/gm;
+	for (const m of block[1].matchAll(re)) dict[m[1]] = m[3];
+	return { dict };
+}
+
+async function auditColibri(root, limits) {
+	const findings = [];
+	const uiJsPath = join(root, "js", "ui.js");
+	if (!existsSync(uiJsPath)) {
+		return { preset: "colibri", root, filesScanned: 0, findings: [{ severity: "error", rule: "C0", file: "js/ui.js", line: 0, message: "js/ui.js 不存在——确认 root 是否为 Colibri 项目根目录" }] };
+	}
+	const { dict } = extractColibriDict(uiJsPath);
+	if (dict === null) {
+		return { preset: "colibri", root, filesScanned: 0, findings: [{ severity: "error", rule: "C0", file: "js/ui.js", line: 0, message: "ICONS 字典解析失败（读取失败或结构变化？）" }] };
+	}
+	// C1 字典自检
+	for (const [name, inner] of Object.entries(dict)) {
+		if (parseIconNodes(inner) === null) {
+			findings.push({ severity: "error", rule: "C1", file: "js/ui.js", line: 0, message: `ICONS.${name} 无法解析为 morphicons IconNode（含 g/transform/未识别标签或为空）——该图标运行时会降级静态换图` });
+		}
+	}
+	// C2/C3 引用核对：html 模板 + js（ui.js 本身只扫 morphTo 字面量以外的实现无关引用，跳过）
+	const files = await walk(root, { maxFiles: limits.maxFiles, exts: [".html", ".js"] });
+	let scanned = 0;
+	for (let i = 0; i < files.length; i += READ_CHUNK) {
+		const batch = files.slice(i, i + READ_CHUNK);
+		const texts = await Promise.all(batch.map((f) => readCapped(f)));
+		for (let k = 0; k < batch.length; k += 1) {
+			const file = batch[k];
+			const rel = relOf(root, file);
+			if (rel === join("js", "ui.js")) continue;
+			const text = texts[k];
+			if (text === null) continue;
+			scanned += 1;
+			// 审查修复 #279：data-morph 兼容单/双引号属性；
+			// 审查修复 #275：morphTo 首参允许一层嵌套括号（querySelector(...)
+			// 形态原先整条静默漏检，C2/C3 两个模式同步修改）
+			const patterns = [
+				{ re: /data-morph=["'](\w+)["']/g, how: "data-morph" },
+				{ re: /\bmorphTo\(\s*[^,()]*(?:\([^()]*\)[^,()]*)*,\s*['"](\w+)['"]/g, how: "morphTo" },
+				{ re: /\bsvg\(\s*['"](\w+)['"]/g, how: "UI.svg" },
+				{ re: /\bmorphIcon\(\s*['"](\w+)['"]/g, how: "UI.morphIcon" }
+			];
+			for (const { re, how } of patterns) {
+				for (const m of text.matchAll(re)) {
+					const name = m[1];
+					if (name === "true" || name === "false") continue;
+					// 不要用 `name in dict`：dict 是普通对象字面量，'constructor'/'toString'/'__proto__'
+					// 这类原型键会误判为“图标存在”，把真实的悬空引用吞掉。
+					if (!Object.prototype.hasOwnProperty.call(dict, name)) {
+						findings.push({ severity: "error", rule: "C2", file: rel, line: lineOf(text, m.index ?? 0), message: `${how} 引用 "${name}" 不在 ICONS 字典——运行时图标为空（svg）或降级换图（morphTo）` });
+					}
+				}
+			}
+			// C3 动态引用提示
+			// codereview #479：捕获组 [A-Za-z_$][\w$]* 只可能匹配标识符字符、永不含引号，
+			// 原先的 /['"]/.test(m[1]) 守卫恒为 false（死代码，误导读者以为存在引号路径），已删。
+			for (const m of text.matchAll(/\bmorphTo\(\s*[^,()]*(?:\([^()]*\)[^,()]*)*,\s*([A-Za-z_$][\w$]*)\s*\)/g)) {
+				findings.push({ severity: "info", rule: "C3", file: rel, line: lineOf(text, m.index ?? 0), message: `morphTo 第二参为变量 "${m[1]}"——静态核对不可达，请人工确认取值都在字典内` });
+			}
+		}
+		if (findings.length > limits.maxFindings * 3) break;
+	}
+	return { preset: "colibri", root, filesScanned: scanned + 1, dictSize: Object.keys(dict).length, findings };
+}
+
+function detectPreset(root) {
+	if (existsSync(join(root, "frontend", "STYLE_GUIDE.md")) || existsSync(join(root, "STYLE_GUIDE.md"))) return "echo";
+	if (existsSync(join(root, "js", "ui.js"))) return "colibri";
+	return undefined;
+}
+
+/**
+ * universal 预设（2026-10-01 新增）：任意项目的 emoji 图标扫描。
+ * 背景：AI 开发时习惯性用 emoji 做图标（owner 级禁令：图标一律 SVG）。
+ * 规则 U1：代码/模板文件中的 emoji 全部报 error（与 echo 预设同严格度，
+ * 扫描面更宽——不限 src/，覆盖首次开发项目的任意目录结构）。
+ */
+const UNIVERSAL_EXTS = [".vue", ".js", ".mjs", ".ts", ".html", ".htm", ".jsx", ".tsx", ".svelte"];
+
+async function auditUniversal(root, limits) {
+	const findings = [];
+	const files = await walk(root, { maxFiles: limits.maxFiles, exts: UNIVERSAL_EXTS });
+	let emojiTotal = 0;
+	for (let i = 0; i < files.length; i += READ_CHUNK) {
+		const batch = files.slice(i, i + READ_CHUNK);
+		const texts = await Promise.all(batch.map((f) => readCapped(f)));
+		for (let k = 0; k < batch.length; k += 1) {
+			const text = texts[k];
+			if (text === null) continue;
+			const rel = relOf(root, batch[k]);
+			for (const m of text.matchAll(new RegExp(EMOJI_RE.source, "gu"))) {
+				emojiTotal += 1;
+				if (findings.length < limits.maxFindings) {
+					findings.push({
+						severity: "error",
+						rule: "U1",
+						file: rel,
+						line: lineOf(text, m.index ?? 0),
+						message: `emoji "${m[0]}" —— 图标一律用 SVG（icon action=find 选型 + action=emit 出码），emoji 做图标全面禁止`
+					});
+				}
+			}
+		}
+	}
+	// 审查修复 #273：预截断使 findings 永不超上限——截断标记改按 emojiTotal 声明，
+	// audit() 优先取 runner 给出的标记（否则 universal 分支 truncated 恒为 false）
+	return { preset: "universal", root, filesScanned: files.length, emojiTotal, truncated: emojiTotal > limits.maxFindings, findings };
+}
+
+/**
+ * 巡检入口。preset: 'echo' | 'colibri' | 'universal' | 'auto'（默认）。
+ * auto 按标记文件判定 echo/colibri；判定不出（如首次开发的新项目）时
+ * 自动落到 universal——emoji 禁令是全局规则，不依赖项目标记。
+ */
+async function audit(root, preset, limits = {}) {
+	const abs = resolve(root);
+	const lim = { maxFiles: limits.maxFiles ?? 4000, maxFindings: limits.maxFindings ?? 60 };
+	if (!existsSync(abs)) throw new Error(`root 不存在：${abs}`);
+	const chosen = preset === "auto" || preset === undefined ? (detectPreset(abs) ?? "universal") : preset;
+	const runner = chosen === "echo" ? auditEcho : chosen === "colibri" ? auditColibri : auditUniversal;
+	const result = await runner(abs, lim);
+	// 审查修复 #274：先截断再统计——counts 与返回的 findings 口径一致
+	//（echo/colibri 内部可积累到上限的 2~3 倍才中断，旧写法按未截断全量统计，
+	// 会出现 counts.error=119 而返回 findings 只有 60 条的自相矛盾）
+	const shown = result.findings.slice(0, lim.maxFindings);
+	const counts = { error: 0, warn: 0, info: 0 };
+	for (const f of shown) counts[f.severity] = (counts[f.severity] ?? 0) + 1;
+	return { ...result, counts, truncated: result.truncated ?? result.findings.length > lim.maxFindings, findings: shown };
+}
+
+export { audit, detectPreset };