@xihan-ui/cli 0.0.0-stage → 4.2.0

package/dist/index.js

@@ -0,0 +1,1540 @@
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+//#region src/knowledge.ts
+const FRAMEWORKS = [
+	"vue",
+	"react",
+	"web-components"
+];
+/** 包内 data/ 目录：src/ 与 dist/ 同在包根下一层。 */
+function defaultDataDir() {
+	return join(dirname(fileURLToPath(import.meta.url)), "..", "data");
+}
+function lazy(load) {
+	let cached;
+	return () => {
+		cached ??= { value: load() };
+		return cached.value;
+	};
+}
+/** 从数据目录读出全部知识；大文件在首次用到时才读。 */
+function loadKnowledge(dataDir = defaultDataDir()) {
+	const text = (file) => readFileSync(join(dataDir, file), "utf8");
+	const json = (file) => JSON.parse(text(file));
+	let meta;
+	try {
+		meta = json("meta.json");
+	} catch (error) {
+		throw new Error(`读不到 @xihan-ui/cli 的离线数据（${dataDir}）：${error.message}`);
+	}
+	const { categories, components } = json("components.json");
+	return {
+		meta,
+		categories,
+		components,
+		pages: lazy(() => json("pages.json")),
+		demos: lazy(() => json("demos.json")),
+		tokens: lazy(() => json("tokens.json")),
+		designMd: lazy(() => text("design.md")),
+		changelog: lazy(() => text("changelog.md"))
+	};
+}
+/** kebab-case 或带 Xh 前缀的 PascalCase 名字统一成组件标识。 */
+function normalize(name) {
+	return name.trim().replace(/^<|\/?>$/g, "").replace(/^xh-/i, "").replace(/^Xh(?=[A-Z])/, "").replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+}
+/** 按标识、PascalCase 名、自定义元素标签、部件组件名或中文名找组件。 */
+function findComponent(knowledge, name) {
+	const raw = name.trim();
+	if (!raw) return void 0;
+	const id = normalize(raw);
+	const exact = knowledge.components.find((c) => c.id === id || c.name === raw);
+	if (exact) return exact;
+	const exported = /^Xh[A-Z]/.test(raw) ? raw : `Xh${raw}`;
+	return knowledge.components.find((c) => c.artifacts.components.includes(exported));
+}
+/** 两个字符串的编辑距离。 */
+function distance(a, b) {
+	const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+	for (let i = 1; i <= a.length; i++) {
+		let previous = row[0];
+		row[0] = i;
+		for (let j = 1; j <= b.length; j++) {
+			const current = row[j];
+			row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+			previous = current;
+		}
+	}
+	return row[b.length];
+}
+/** 找不到组件时的候选：名字互相包含或编辑距离不超过 2。 */
+function suggestComponents(knowledge, name, limit = 5) {
+	const id = normalize(name);
+	if (!id) return [];
+	return knowledge.components.map((c) => ({
+		c,
+		score: c.id.includes(id) || id.includes(c.id) || c.name.includes(name.trim()) ? 0 : distance(c.id, id)
+	})).filter((x) => x.score <= 2).sort((a, b) => a.score - b.score || a.c.id.localeCompare(b.c.id)).slice(0, limit).map((x) => x.c);
+}
+/** 按站内路径找文档页：完整路径优先，其次末段同名的唯一一页。 */
+function findPage(knowledge, path) {
+	const key = path.trim().replace(/^\/+|\/+$/g, "").replace(/\.md$/, "").replace(/\/index$/, "");
+	const pages = knowledge.pages();
+	const exact = pages.find((p) => p.path === key);
+	if (exact) return exact;
+	const tail = pages.filter((p) => p.path.split("/").pop() === key);
+	return tail.length === 1 ? tail[0] : void 0;
+}
+/** 把 vue / react / wc / web-components 等写法统一成框架标识。 */
+function parseFramework(value) {
+	if (value === void 0) return void 0;
+	const v = value.trim().toLowerCase();
+	if (v === "vue") return "vue";
+	if (v === "react" || v === "tsx") return "react";
+	if (v === "wc" || v === "web-components" || v === "webcomponents" || v === "html") return "web-components";
+}
+//#endregion
+//#region src/query.ts
+/** 查询失败：带上可直接展示给使用者的说明与候选。 */
+var QueryError = class extends Error {
+	suggestions;
+	constructor(message, suggestions = []) {
+		super(message);
+		this.name = "QueryError";
+		this.suggestions = suggestions;
+	}
+};
+/** 找组件，找不到时抛出带候选的 QueryError。 */
+function requireComponent(knowledge, name) {
+	const entry = findComponent(knowledge, name);
+	if (entry) return entry;
+	const near = suggestComponents(knowledge, name).map((c) => `${c.title}（${c.id}）`);
+	throw new QueryError(`没有名为「${name}」的组件。用 list 查看全部组件。`, near);
+}
+/** 按分类列组件，可按分类标识 / 名称与关键字过滤。 */
+function listComponents(knowledge, options = {}) {
+	const category = options.category?.trim();
+	const query = options.query?.trim().toLowerCase();
+	if (category && !knowledge.categories.some((c) => c.id === category || c.label === category)) throw new QueryError(`没有名为「${category}」的分类。`, knowledge.categories.map((c) => `${c.id}（${c.label}）`));
+	return knowledge.categories.filter((c) => !category || c.id === category || c.label === category).map((c) => ({
+		...c,
+		components: knowledge.components.filter((entry) => entry.category === c.id && (!query || entry.id.includes(query) || entry.title.toLowerCase().includes(query) || entry.name.includes(query) || (entry.overview ?? "").toLowerCase().includes(query)))
+	})).filter((c) => c.components.length > 0);
+}
+const FENCE_LANG = {
+	"vue": "vue",
+	"react": "tsx",
+	"web-components": "html"
+};
+const FRAMEWORK_LABEL$1 = {
+	"vue": "Vue",
+	"react": "React",
+	"web-components": "Web Components"
+};
+/** 把页面里的 <XhDemo src="…" /> 换成所选写法的示例源码。 */
+function inlineDemos(knowledge, markdown, framework) {
+	return markdown.replace(/<XhDemo\s+src="([^"]+)"\s*\/>/g, (_, src) => {
+		const source = knowledge.demos()[src]?.[framework];
+		if (source === void 0) return `> 示例 \`${src}\` 没有 ${FRAMEWORK_LABEL$1[framework]} 写法。`;
+		return `\`\`\`${FENCE_LANG[framework]}\n${source}\n\`\`\``;
+	});
+}
+/** 组件或文档页的完整 Markdown，示例按所选写法内联。 */
+function resolveDoc(knowledge, name, framework) {
+	const entry = findComponent(knowledge, name);
+	const page = entry ? findPage(knowledge, `components/${entry.id}`) : findPage(knowledge, name);
+	if (!page) {
+		const near = [...suggestComponents(knowledge, name).map((c) => c.id), ...knowledge.pages().filter((p) => p.path.includes(name.trim().toLowerCase())).map((p) => p.path)].slice(0, 8);
+		throw new QueryError(`没有名为「${name}」的组件或文档页。组件写标识（如 select），文档页写站内路径（如 guide/theme）。`, near);
+	}
+	return {
+		path: page.path,
+		title: page.title,
+		framework,
+		markdown: inlineDemos(knowledge, page.markdown, framework)
+	};
+}
+/** 除组件页外的全部文档页，按路径排序。 */
+function listPages(knowledge) {
+	return knowledge.pages().filter((p) => !p.path.startsWith("components/")).sort((a, b) => a.path.localeCompare(b.path));
+}
+/** 按序号、文件基名或标题找组件的某个示例。 */
+function findDemo(entry, name) {
+	const key = name.trim();
+	if (/^\d+$/.test(key)) return entry.demos[Number(key) - 1];
+	return entry.demos.find((demo) => {
+		const base = demo.src.slice(demo.src.indexOf("/") + 1);
+		return base === key || base.replace(/^\d+-/, "") === key || demo.title === key;
+	});
+}
+/** 一个示例在所选写法下的源码。 */
+function demoSource(knowledge, entry, name, framework) {
+	const demo = findDemo(entry, name);
+	if (!demo) throw new QueryError(`${entry.title} 没有名为「${name}」的示例。`, entry.demos.map((d, i) => `${i + 1}. ${d.src.slice(d.src.indexOf("/") + 1)}（${d.title}）`));
+	const source = knowledge.demos()[demo.src]?.[framework];
+	if (source === void 0) {
+		const available = Object.keys(knowledge.demos()[demo.src] ?? {});
+		throw new QueryError(`示例 ${demo.src} 没有 ${FRAMEWORK_LABEL$1[framework]} 写法。`, available);
+	}
+	return {
+		component: entry,
+		framework,
+		demo,
+		source
+	};
+}
+/** 令牌族：`--xh-<族>-…` 的第一段。 */
+function tokenFamily(name) {
+	return name.replace(/^--xh-/, "").split("-")[0] ?? "";
+}
+/**
+* 查令牌：给组件时列它的覆盖槽，给关键字时按名字匹配全局令牌，都不给时列令牌族。
+* 关键字可写完整名、前缀或片段，如 `bg-brand`、`--xh-shape`。
+*/
+function queryTokens(knowledge, options = {}) {
+	if (options.component) {
+		const entry = requireComponent(knowledge, options.component);
+		return {
+			kind: "component",
+			component: entry,
+			tokens: entry.componentTokens
+		};
+	}
+	const data = knowledge.tokens();
+	const query = options.query?.trim();
+	if (!query) {
+		const counts = /* @__PURE__ */ new Map();
+		for (const token of data.tokens) counts.set(tokenFamily(token.name), (counts.get(tokenFamily(token.name)) ?? 0) + 1);
+		return {
+			kind: "families",
+			families: [...counts].map(([family, count]) => ({
+				family,
+				count
+			})).sort((a, b) => a.family.localeCompare(b.family))
+		};
+	}
+	const needle = query.replace(/^--xh-/, "").replace(/^--/, "").toLowerCase();
+	const tokens = data.tokens.filter((t) => t.name.slice(5).toLowerCase().includes(needle));
+	const tone = data.tone.filter((name) => name.slice(5).includes(needle));
+	if (tokens.length === 0 && tone.length === 0) throw new QueryError(`没有名字含「${query}」的令牌。不带关键字查询可列出全部令牌族。`);
+	return {
+		kind: "global",
+		query,
+		tokens,
+		tone
+	};
+}
+/** 组件的样式钩子：部件选择器、数据属性、状态取值与覆盖槽。 */
+function componentParts(knowledge, name) {
+	return { component: requireComponent(knowledge, name) };
+}
+/** 把更新日志切成按版本的段。 */
+function parseChangelog(markdown) {
+	const out = [];
+	const parts = markdown.split(/^## /m).slice(1);
+	for (const part of parts) {
+		const newline = part.indexOf("\n");
+		const [version = "", ...rest] = (newline === -1 ? part : part.slice(0, newline)).trim().split(/\s+/);
+		if (!version) continue;
+		out.push({
+			version: version.replace(/^v/, ""),
+			date: rest.join(" ").replace(/^\(|\)$/g, ""),
+			body: newline === -1 ? "" : part.slice(newline + 1).trim()
+		});
+	}
+	return out;
+}
+/** 语义化版本比较：预发布排在同号正式版之前。 */
+function compareVersions(a, b) {
+	const split = (v) => {
+		const [core = "", pre = ""] = v.replace(/^v/, "").split("-", 2);
+		return [core.split(".").map((n) => Number(n) || 0), pre];
+	};
+	const [ca, pa] = split(a);
+	const [cb, pb] = split(b);
+	for (let i = 0; i < Math.max(ca.length, cb.length); i++) {
+		const diff = (ca[i] ?? 0) - (cb[i] ?? 0);
+		if (diff !== 0) return diff;
+	}
+	if (pa === pb) return 0;
+	if (!pa) return 1;
+	if (!pb) return -1;
+	return pa.localeCompare(pb, "en", { numeric: true });
+}
+/**
+* 取更新日志：只给 from 时取这一版，给 from 与 to 时取 (from, to] 区间，
+* 都不给时取最近一版；keyword 只保留含该词的条目。
+*/
+function queryChangelog(knowledge, options = {}) {
+	const sections = parseChangelog(knowledge.changelog());
+	if (sections.length === 0) throw new QueryError("更新日志为空。");
+	let picked;
+	if (options.from && options.to) {
+		const [low, high] = compareVersions(options.from, options.to) <= 0 ? [options.from, options.to] : [options.to, options.from];
+		picked = sections.filter((s) => compareVersions(s.version, low) > 0 && compareVersions(s.version, high) <= 0);
+	} else if (options.from) {
+		const version = options.from.replace(/^v/, "");
+		picked = sections.filter((s) => s.version === version);
+		if (picked.length === 0) throw new QueryError(`更新日志里没有 ${options.from}。`, sections.slice(0, 8).map((s) => s.version));
+	} else picked = sections.slice(0, 1);
+	const keyword = options.keyword?.trim();
+	if (!keyword) return picked;
+	const needles = keywordVariants(knowledge, keyword);
+	return picked.map((s) => ({
+		...s,
+		body: s.body.split("\n").filter((line) => /^\s*[-*]\s/.test(line) && needles.some((n) => line.toLowerCase().includes(n))).join("\n")
+	})).filter((s) => s.body);
+}
+/** 关键字是组件名时，连同它的 PascalCase 名与中文名一起匹配。 */
+function keywordVariants(knowledge, keyword) {
+	const entry = findComponent(knowledge, keyword);
+	const words = entry ? [
+		entry.id,
+		entry.title,
+		entry.name,
+		keyword
+	] : [keyword];
+	return [...new Set(words.map((w) => w.toLowerCase()))];
+}
+//#endregion
+//#region src/render.ts
+const code = (s) => `\`${s.replace(/`/g, "")}\``;
+const cell = (s) => s.replace(/\r?\n/g, " ").replace(/\|/g, "\\|");
+const codeCell = (s) => cell(code(s));
+function table(head, rows) {
+	return [
+		`| ${head.join(" | ")} |`,
+		`| ${head.map(() => "---").join(" | ")} |`,
+		...rows.map((row) => `| ${row.join(" | ")} |`)
+	];
+}
+/** Vue / React 的根组件名：Root 优先，其次同名组件。 */
+function rootComponent(entry) {
+	const names = entry.artifacts.components;
+	return names.find((n) => n === `Xh${entry.title}Root`) ?? names.find((n) => n === `Xh${entry.title}`) ?? names[0];
+}
+function renderList(knowledge, groups) {
+	const total = groups.reduce((sum, g) => sum + g.components.length, 0);
+	const L = [
+		`# XiHan.UI 组件 · v${knowledge.meta.version}`,
+		"",
+		`共 ${total} 个。查看某个组件用 info，完整文档用 doc。`,
+		""
+	];
+	for (const group of groups) {
+		L.push(`## ${group.label}（${group.id}）`, "");
+		if (group.description) L.push(group.description, "");
+		L.push(...table([
+			"组件",
+			"名称",
+			"Vue / React 根组件",
+			"自定义元素",
+			"状态"
+		], group.components.map((c) => [
+			`${c.title}（${code(c.id)}）`,
+			cell(c.name),
+			rootComponent(c) ? code(rootComponent(c)) : "—",
+			c.artifacts.tag ? code(`<${c.artifacts.tag}>`) : "—",
+			c.status ?? ""
+		])), "");
+	}
+	return L.join("\n");
+}
+function fieldTable(rows) {
+	return table([
+		"属性",
+		"类型",
+		"必填",
+		"说明"
+	], rows.map((r) => [
+		codeCell(r.name),
+		codeCell(r.type),
+		r.optional ? "" : "是",
+		cell(r.doc)
+	]));
+}
+function renderInfo(knowledge, entry) {
+	const a = entry.artifacts;
+	const L = [`# ${entry.title} ${entry.name}`, ""];
+	if (entry.status) L.push(`状态：${code(entry.status)}`, "");
+	if (entry.overview) L.push(entry.overview, "");
+	L.push(`分类：${entry.categoryLabel}（${entry.category}）· 文档：${knowledge.meta.site}/components/${entry.id}`, "");
+	L.push("## 产物", "");
+	const artifactRows = [];
+	if (a.components.length) artifactRows.push(["Vue / React 组件", a.components.map(code).join(" ")]);
+	if (a.composable) artifactRows.push(["Vue 组合式函数", code(a.composable)]);
+	if (a.tag) artifactRows.push(["自定义元素", code(`<${a.tag}>`)]);
+	artifactRows.push(["状态机", a.machine ? code(a.machine) : "无"]);
+	if (a.skin) artifactRows.push(["皮肤", code(a.skin)]);
+	L.push(...table(["层", "值"], artifactRows), "");
+	const required = new Set(entry.requiredParts);
+	L.push("## 部件", "", `${code(`data-scope="${entry.id}"`)}：${entry.parts.map((p) => required.has(p) ? `**${code(p)}**` : code(p)).join(" · ")}（加粗为必需部件）`, "");
+	if (entry.props.length) L.push("## Props", "", ...fieldTable(entry.props), "");
+	for (const node of entry.nodes) L.push(`### ${node.name}`, "", `${code(node.via)} 的元素。`, "", ...fieldTable(node.fields), "");
+	if (entry.events.length) {
+		L.push("## 事件", "", "自定义元素的载荷在 `detail`；Vue 为同名 emit。", "");
+		L.push(...table([
+			"事件",
+			"载荷",
+			"说明"
+		], entry.events.map((e) => [
+			codeCell(e.name),
+			e.type ? codeCell(e.type) : "",
+			cell(e.description)
+		])), "");
+	}
+	if (entry.slots.length) {
+		L.push("## Vue 插槽（带载荷）", "");
+		L.push(...table([
+			"组件",
+			"插槽",
+			"载荷",
+			"说明"
+		], entry.slots.map((s) => [
+			code(s.component),
+			code(s.name),
+			s.payload ? codeCell(s.payload) : "—",
+			cell(s.doc)
+		])), "");
+	}
+	if (entry.reactProps.length) {
+		L.push("## React 适配器 props", "", "只列 React 组件自己声明的属性，DOM 属性与上面 Props 表里同名的不重复列。", "");
+		L.push(...table([
+			"组件",
+			"属性",
+			"类型",
+			"必填",
+			"说明"
+		], entry.reactProps.map((r) => [
+			code(r.component),
+			codeCell(r.name),
+			codeCell(r.type),
+			r.optional ? "" : "是",
+			cell(r.doc)
+		])), "");
+	}
+	const states = entry.dataAttributes.filter((d) => d.attr === "data-state");
+	if (states.length) L.push("## 状态", "", ...table(["部件", "data-state"], states.map((s) => [code(s.part), cell(s.value)])), "");
+	if (entry.api.length) {
+		L.push("## connect API", "", "`getXxxProps()` 返回对应部件的宿主属性，组合式函数与自定义布局用它。", "");
+		L.push(...table([
+			"成员",
+			"类型",
+			"说明"
+		], entry.api.map((x) => [
+			codeCell(x.name),
+			codeCell(x.type),
+			cell(x.doc)
+		])), "");
+	}
+	L.push("## 键盘", "");
+	if (entry.keyboard.rows.length) L.push(...table([
+		"按键",
+		"生效条件",
+		"行为"
+	], entry.keyboard.rows.map((r) => [
+		r.keys.map(code).join(" / "),
+		cell(r.when),
+		cell(r.does)
+	])), "");
+	else L.push("无键盘交互。", "");
+	for (const title of [
+		"何时使用",
+		"何时不用",
+		"反模式"
+	]) {
+		const text = entry.guidance[title];
+		if (text) L.push(`## ${title}`, "", text, "");
+	}
+	if (entry.demos.length) L.push("## 示例", "", ...entry.demos.map((d, i) => `${i + 1}. ${d.title}${d.description ? `：${d.description}` : ""}（${code(d.src)}）`), "");
+	return L.join("\n");
+}
+function renderParts(entry) {
+	const L = [`# ${entry.title} 的样式钩子`, ""];
+	L.push("皮肤按部件选择器书写；覆盖样式写进 `@layer xihan.overrides`（无层皮肤时用不低于 `[data-scope][data-part]` 的特异性），", "颜色、间距、圆角等只取语义令牌或下面的组件覆盖槽，不写散值。", "");
+	L.push("## 部件选择器", "");
+	const required = new Set(entry.requiredParts);
+	L.push(...table([
+		"部件",
+		"选择器",
+		"必需"
+	], entry.parts.map((p) => [
+		code(p),
+		code(`[data-scope="${entry.id}"][data-part="${p}"]`),
+		required.has(p) ? "是" : ""
+	])), "");
+	if (entry.dataAttributes.length) {
+		L.push("## 数据属性", "", "由 connect 写入；条件不成立时不输出。", "");
+		L.push(...table([
+			"部件",
+			"属性",
+			"值"
+		], entry.dataAttributes.map((d) => [
+			code(d.part),
+			code(d.attr),
+			cell(d.value)
+		])), "");
+	}
+	if (entry.aria.length) {
+		L.push("## ARIA", "", "由 connect 写入，不要手写。", "");
+		L.push(...table([
+			"部件",
+			"属性",
+			"值"
+		], entry.aria.map((d) => [
+			code(d.part),
+			code(d.attr),
+			cell(d.value)
+		])), "");
+	}
+	if (entry.componentTokens.length) {
+		L.push("## 组件覆盖槽", "", "在组件根或任意祖先上设置即可覆盖，缺省值取后面的令牌。", "");
+		L.push(...table([
+			"变量",
+			"部件",
+			"属性",
+			"状态",
+			"缺省"
+		], entry.componentTokens.map((t) => [
+			code(t.name),
+			t.part.map(code).join(" "),
+			t.property.map(code).join(" "),
+			t.state.map(code).join(" "),
+			t.defaultToken.map(code).join(" ")
+		])), "");
+	} else L.push("## 组件覆盖槽", "", "本组件没有专属覆盖槽，外观由语义令牌决定。", "");
+	return L.join("\n");
+}
+function renderDoc(doc) {
+	return doc.markdown;
+}
+function renderPages(knowledge, pages) {
+	const L = [
+		`# XiHan.UI 文档页 · v${knowledge.meta.version}`,
+		"",
+		"组件页用组件标识读取（如 `select`），其余页面用下列路径读取。",
+		""
+	];
+	L.push(...table([
+		"路径",
+		"标题",
+		"摘要"
+	], pages.map((p) => [
+		code(p.path),
+		cell(p.title),
+		cell(p.summary)
+	])), "");
+	return L.join("\n");
+}
+const FRAMEWORK_LABEL = {
+	"vue": "Vue",
+	"react": "React",
+	"web-components": "Web Components"
+};
+function renderDemoList(entry) {
+	if (entry.demos.length === 0) return `# ${entry.title} 的示例\n\n本组件还没有示例。`;
+	const L = [
+		`# ${entry.title} 的示例`,
+		"",
+		"按序号或文件基名取源码，写法可选 Vue、React、Web Components。",
+		""
+	];
+	L.push(...table([
+		"#",
+		"示例",
+		"标题",
+		"说明"
+	], entry.demos.map((d, i) => [
+		String(i + 1),
+		code(d.src.slice(d.src.indexOf("/") + 1)),
+		cell(d.title),
+		cell(d.description)
+	])), "");
+	return L.join("\n");
+}
+function renderDemo(result) {
+	const lang = result.framework === "vue" ? "vue" : result.framework === "react" ? "tsx" : "html";
+	const L = [`# ${result.component.title} · ${result.demo.title}（${FRAMEWORK_LABEL[result.framework]}）`, ""];
+	if (result.demo.description) L.push(result.demo.description, "");
+	L.push(`\`\`\`${lang}`, result.source, "```", "");
+	return L.join("\n");
+}
+function renderTokens(result) {
+	if (result.kind === "families") {
+		const L = [
+			"# 设计令牌族",
+			"",
+			"用关键字查具体令牌（如 `bg-brand`、`shape`、`control-h`），用 component 查某个组件的覆盖槽。",
+			""
+		];
+		L.push(...table([
+			"族",
+			"令牌数",
+			"示例前缀"
+		], result.families.map((f) => [
+			code(f.family),
+			String(f.count),
+			code(`--xh-${f.family}-*`)
+		])), "");
+		return L.join("\n");
+	}
+	if (result.kind === "component") {
+		const entry = result.component;
+		if (result.tokens.length === 0) return `# ${entry.title} 的覆盖槽\n\n本组件没有专属覆盖槽，外观由语义令牌决定。`;
+		const L = [`# ${entry.title} 的覆盖槽`, ""];
+		L.push(...table([
+			"变量",
+			"部件",
+			"属性",
+			"状态",
+			"缺省",
+			"说明"
+		], result.tokens.map((t) => [
+			code(t.name),
+			t.part.map(code).join(" "),
+			t.property.map(code).join(" "),
+			t.state.map(code).join(" "),
+			t.defaultToken.map(code).join(" "),
+			cell(t.description)
+		])), "");
+		return L.join("\n");
+	}
+	const L = [
+		`# 令牌 · ${result.query}`,
+		"",
+		"取值是缺省档（浅色 · 舒适 · 基础对比度）下的值；「改写档」是还重新给过它的令牌源（深色、紧凑、高对比度、减弱动效、打印等）。",
+		""
+	];
+	if (result.tokens.length) L.push(...table([
+		"令牌",
+		"类型",
+		"取值",
+		"展开后",
+		"改写档"
+	], result.tokens.map((t) => [
+		code(t.name),
+		t.type,
+		codeCell(t.value),
+		t.resolved === t.value ? "" : codeCell(t.resolved),
+		t.layers.join(" / ") || "—"
+	])), "");
+	if (result.tone.length) {
+		L.push("## 语气族", "", "只在写了 `data-tone` 的节点及其后代里有取值。", "");
+		L.push(...result.tone.map((name) => `- ${code(name)}`), "");
+	}
+	return L.join("\n");
+}
+function renderChangelog(sections) {
+	if (sections.length === 0) return "没有匹配的更新条目。";
+	return sections.map((s) => `## v${s.version}${s.date ? ` (${s.date})` : ""}\n\n${s.body}`).join("\n\n");
+}
+//#endregion
+//#region src/tools.ts
+/** 参数校验失败。 */
+var ArgumentError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ArgumentError";
+	}
+};
+function optionalString(args, key) {
+	const value = args[key];
+	if (value === void 0 || value === null || value === "") return void 0;
+	if (typeof value !== "string") throw new ArgumentError(`参数 ${key} 必须是字符串`);
+	return value;
+}
+function requiredString(args, key) {
+	const value = optionalString(args, key);
+	if (value === void 0) throw new ArgumentError(`缺少参数 ${key}`);
+	return value;
+}
+function frameworkArg(args, context) {
+	const raw = optionalString(args, "framework");
+	if (raw === void 0) return context.framework;
+	const framework = parseFramework(raw);
+	if (!framework) throw new ArgumentError(`framework 只能是 ${FRAMEWORKS.join(" / ")}，收到 ${raw}`);
+	return framework;
+}
+const frameworkProperty = {
+	type: "string",
+	enum: [...FRAMEWORKS],
+	description: "示例写法：vue、react 或 web-components。缺省取项目里装的适配器，识别不到时为 vue。"
+};
+const componentProperty = {
+	type: "string",
+	description: "组件名：标识（date-picker）、PascalCase（DatePicker）、导出名（XhDatePickerRoot）、标签（xh-date-picker）或中文名均可。"
+};
+const TOOLS = [
+	{
+		name: "xihan_ui_list",
+		title: "列出组件",
+		description: "按分类列出 XiHan.UI 的全部组件：标识、中文名、Vue / React 根组件名、自定义元素标签与状态。不确定该用哪个组件时先调它。",
+		inputSchema: {
+			type: "object",
+			properties: {
+				category: {
+					type: "string",
+					description: "只列某个分类，写分类标识或中文名，如 form、数据录入。"
+				},
+				query: {
+					type: "string",
+					description: "按名称或概述里的关键字过滤。"
+				}
+			},
+			additionalProperties: false
+		},
+		run: (args, { knowledge }) => renderList(knowledge, listComponents(knowledge, {
+			category: optionalString(args, "category"),
+			query: optionalString(args, "query")
+		}))
+	},
+	{
+		name: "xihan_ui_info",
+		title: "组件 API",
+		description: "取一个组件的完整 API：产物（导出名、标签、皮肤）、部件、Props 与条目数据结构、事件、插槽、React 专有属性、状态、connect API 与键盘规格。写组件代码前必须先查，不要凭记忆写属性名。",
+		inputSchema: {
+			type: "object",
+			properties: { component: componentProperty },
+			required: ["component"],
+			additionalProperties: false
+		},
+		run: (args, { knowledge }) => renderInfo(knowledge, requireComponent(knowledge, requiredString(args, "component")))
+	},
+	{
+		name: "xihan_ui_doc",
+		title: "完整文档",
+		description: "取组件页或指南页的完整 Markdown，示例按所选写法内联为源码。组件写标识（select），指南写站内路径（guide/theme、installation、adapters/react）；不传 name 时列出全部指南页。",
+		inputSchema: {
+			type: "object",
+			properties: {
+				name: {
+					type: "string",
+					description: "组件名或文档页路径。"
+				},
+				framework: frameworkProperty
+			},
+			additionalProperties: false
+		},
+		run: (args, context) => {
+			const name = optionalString(args, "name");
+			if (!name) return renderPages(context.knowledge, listPages(context.knowledge));
+			return renderDoc(resolveDoc(context.knowledge, name, frameworkArg(args, context)));
+		}
+	},
+	{
+		name: "xihan_ui_demo",
+		title: "示例源码",
+		description: "取组件的可运行示例。不传 name 时列出该组件的全部示例；传序号、文件基名或标题时返回所选写法的完整源码。",
+		inputSchema: {
+			type: "object",
+			properties: {
+				component: componentProperty,
+				name: {
+					type: "string",
+					description: "示例序号（1 起）、文件基名（01-basic 或 basic）或标题。"
+				},
+				framework: frameworkProperty
+			},
+			required: ["component"],
+			additionalProperties: false
+		},
+		run: (args, context) => {
+			const entry = requireComponent(context.knowledge, requiredString(args, "component"));
+			const name = optionalString(args, "name");
+			if (!name) return renderDemoList(entry);
+			return renderDemo(demoSource(context.knowledge, entry, name, frameworkArg(args, context)));
+		}
+	},
+	{
+		name: "xihan_ui_token",
+		title: "设计令牌",
+		description: "查设计令牌。传 query 按名字片段查全局令牌（如 bg-brand、shape、control-h、motion-duration）及其缺省取值；传 component 列该组件的覆盖槽；都不传时列出令牌族。写样式时只用这里查得到的令牌，不写散值。",
+		inputSchema: {
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					description: "令牌名或名字片段，可带 --xh- 前缀。"
+				},
+				component: componentProperty
+			},
+			additionalProperties: false
+		},
+		run: (args, { knowledge }) => renderTokens(queryTokens(knowledge, {
+			query: optionalString(args, "query"),
+			component: optionalString(args, "component")
+		}))
+	},
+	{
+		name: "xihan_ui_parts",
+		title: "样式钩子",
+		description: "取组件的样式钩子：每个部件的 [data-scope][data-part] 选择器、connect 写入的数据属性与状态取值、ARIA、组件覆盖槽及其缺省令牌。改组件外观前先查它。",
+		inputSchema: {
+			type: "object",
+			properties: { component: componentProperty },
+			required: ["component"],
+			additionalProperties: false
+		},
+		run: (args, { knowledge }) => renderParts(componentParts(knowledge, requiredString(args, "component")).component)
+	},
+	{
+		name: "xihan_ui_design_md",
+		title: "设计语言",
+		description: "取 XiHan.UI 的 design.md：缺省主题的颜色、排版、间距、圆角与组件样式令牌，以及视觉规则与禁忌。生成整页界面或判断视觉取舍时读它。",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			additionalProperties: false
+		},
+		run: (_, { knowledge }) => knowledge.designMd()
+	},
+	{
+		name: "xihan_ui_changelog",
+		title: "更新日志",
+		description: "查更新日志。只传 from 取这一版；传 from 与 to 取两版之间（不含 from、含 to）的全部变更，用于升级迁移；keyword 只保留提到它的条目（可写组件名）。都不传时取最近一版。",
+		inputSchema: {
+			type: "object",
+			properties: {
+				from: {
+					type: "string",
+					description: "版本号，如 4.0.0。"
+				},
+				to: {
+					type: "string",
+					description: "版本号，如 4.1.0。"
+				},
+				keyword: {
+					type: "string",
+					description: "关键字或组件名。"
+				}
+			},
+			additionalProperties: false
+		},
+		run: (args, { knowledge }) => renderChangelog(queryChangelog(knowledge, {
+			from: optionalString(args, "from"),
+			to: optionalString(args, "to"),
+			keyword: optionalString(args, "keyword")
+		}))
+	}
+];
+/** 包内 skills/xihan-ui/SKILL.md 的正文，去掉 frontmatter。 */
+function skillBody() {
+	return readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "skills", "xihan-ui", "SKILL.md"), "utf8").replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim();
+}
+const PROMPTS = [{
+	name: "xihan-ui-expert",
+	title: "XiHan.UI 专家",
+	description: "以 XiHan.UI 专家身份工作：先查 API 再写代码，样式只走部件选择器与令牌。",
+	arguments: [],
+	render: (_, { framework }) => [
+		`你是 XiHan.UI 的专家。当前项目的写法是 ${framework}。以下是使用规范，回答与写代码都按它执行；`,
+		"涉及具体组件时先调 xihan_ui_info / xihan_ui_doc / xihan_ui_demo 查证，不要凭记忆写组件名、属性或部件。",
+		"",
+		skillBody()
+	].join("\n")
+}, {
+	name: "xihan-ui-page-generator",
+	title: "用 XiHan.UI 搭页面",
+	description: "按描述用 XiHan.UI 组件搭一整页界面。",
+	arguments: [{
+		name: "description",
+		description: "页面要做什么：用途、区块、数据与交互。",
+		required: true
+	}, {
+		name: "framework",
+		description: "写法：vue、react 或 web-components，缺省取项目里的适配器。",
+		required: false
+	}],
+	render: (args, context) => {
+		return [
+			`用 XiHan.UI 的 ${parseFramework(args.framework) ?? context.framework} 写法实现下面这个页面：`,
+			"",
+			args.description ?? "",
+			"",
+			"步骤：",
+			"1. 调 xihan_ui_design_md 了解视觉规则，调 xihan_ui_list 选定要用的组件；",
+			"2. 对每个选定的组件调 xihan_ui_info 核对导出名、部件与 Props，需要时调 xihan_ui_demo 参考示例；",
+			"3. 页面布局用 Layout / Flex / Grid 等布局组件与间距令牌，颜色、间距、圆角只取 xihan_ui_token 查得到的令牌；",
+			"4. 交付完整可运行的代码，并列出用到的组件与需要额外安装的包。"
+		].join("\n");
+	}
+}];
+//#endregion
+//#region src/mcp.ts
+/** 按新到旧排列的受支持协议版本。 */
+const PROTOCOL_VERSIONS = [
+	"2025-11-25",
+	"2025-06-18",
+	"2025-03-26",
+	"2024-11-05"
+];
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+var RpcError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+function asRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+/** 处理一条请求；通知（不带 id）返回 undefined。 */
+function handleMessage(message, options) {
+	const record = asRecord(message);
+	const id = record.id;
+	const validId = typeof id === "string" || typeof id === "number";
+	if (record.jsonrpc !== "2.0" || typeof record.method !== "string") return {
+		jsonrpc: "2.0",
+		id: validId ? id : null,
+		error: {
+			code: INVALID_REQUEST,
+			message: "不是合法的 JSON-RPC 2.0 请求"
+		}
+	};
+	const request = record;
+	const isNotification = !("id" in record);
+	try {
+		const result = dispatch(request, options);
+		if (isNotification) return void 0;
+		return {
+			jsonrpc: "2.0",
+			id: validId ? id : null,
+			result: result ?? {}
+		};
+	} catch (error) {
+		if (isNotification) return void 0;
+		const code = error instanceof RpcError ? error.code : -32603;
+		return {
+			jsonrpc: "2.0",
+			id: validId ? id : null,
+			error: {
+				code,
+				message: error.message
+			}
+		};
+	}
+}
+function dispatch(request, options) {
+	const params = asRecord(request.params);
+	switch (request.method) {
+		case "initialize": {
+			const requested = params.protocolVersion;
+			return {
+				protocolVersion: PROTOCOL_VERSIONS.find((v) => v === requested) ?? PROTOCOL_VERSIONS[0],
+				capabilities: {
+					tools: { listChanged: false },
+					prompts: { listChanged: false }
+				},
+				serverInfo: {
+					name: "xihan-ui",
+					title: "XiHan.UI",
+					version: options.version
+				},
+				instructions: options.instructions
+			};
+		}
+		case "notifications/initialized":
+		case "notifications/cancelled": return;
+		case "ping": return {};
+		case "tools/list": return { tools: TOOLS.map((tool) => ({
+			name: tool.name,
+			title: tool.title,
+			description: tool.description,
+			inputSchema: tool.inputSchema,
+			annotations: {
+				readOnlyHint: true,
+				openWorldHint: false
+			}
+		})) };
+		case "tools/call": return callTool(params, options.context);
+		case "prompts/list": return { prompts: PROMPTS.map((prompt) => ({
+			name: prompt.name,
+			title: prompt.title,
+			description: prompt.description,
+			arguments: prompt.arguments
+		})) };
+		case "prompts/get": return getPrompt(params, options.context);
+		default: throw new RpcError(METHOD_NOT_FOUND, `不支持的方法：${request.method}`);
+	}
+}
+function callTool(params, context) {
+	const tool = TOOLS.find((t) => t.name === params.name);
+	if (!tool) throw new RpcError(INVALID_PARAMS, `没有名为 ${String(params.name)} 的工具`);
+	try {
+		return { content: [{
+			type: "text",
+			text: tool.run(asRecord(params.arguments), context)
+		}] };
+	} catch (error) {
+		if (error instanceof QueryError || error instanceof ArgumentError) {
+			const near = error instanceof QueryError && error.suggestions.length ? `\n\n候选：\n${error.suggestions.map((s) => `- ${s}`).join("\n")}` : "";
+			return {
+				content: [{
+					type: "text",
+					text: `${error.message}${near}`
+				}],
+				isError: true
+			};
+		}
+		throw error;
+	}
+}
+function getPrompt(params, context) {
+	const prompt = PROMPTS.find((p) => p.name === params.name);
+	if (!prompt) throw new RpcError(INVALID_PARAMS, `没有名为 ${String(params.name)} 的提示词`);
+	const raw = asRecord(params.arguments);
+	const args = {};
+	for (const [key, value] of Object.entries(raw)) if (typeof value === "string") args[key] = value;
+	const missing = prompt.arguments.filter((a) => a.required && !args[a.name]);
+	if (missing.length) throw new RpcError(INVALID_PARAMS, `缺少参数：${missing.map((a) => a.name).join("、")}`);
+	return {
+		description: prompt.description,
+		messages: [{
+			role: "user",
+			content: {
+				type: "text",
+				text: prompt.render(args, context)
+			}
+		}]
+	};
+}
+/** 处理一行输入：单条请求或批量数组，返回要写出的那一行（没有响应时为 undefined）。 */
+function handleLine(line, options) {
+	let message;
+	try {
+		message = JSON.parse(line);
+	} catch {
+		return JSON.stringify({
+			jsonrpc: "2.0",
+			id: null,
+			error: {
+				code: PARSE_ERROR,
+				message: "无法解析的 JSON"
+			}
+		});
+	}
+	if (Array.isArray(message)) {
+		const responses = message.map((m) => handleMessage(m, options)).filter((r) => r !== void 0);
+		return responses.length ? JSON.stringify(responses) : void 0;
+	}
+	const response = handleMessage(message, options);
+	return response ? JSON.stringify(response) : void 0;
+}
+/** 在给定的输入输出流上运行服务端，输入结束时返回。 */
+function serveStdio(options, input = process.stdin, output = process.stdout) {
+	const reader = createInterface({
+		input,
+		crlfDelay: Infinity
+	});
+	reader.on("line", (line) => {
+		if (!line.trim()) return;
+		const reply = handleLine(line, options);
+		if (reply !== void 0) output.write(`${reply}\n`);
+	});
+	return new Promise((resolve) => reader.once("close", () => resolve()));
+}
+//#endregion
+//#region src/project.ts
+const ADAPTER_PACKAGES = [
+	["vue", "@xihan-ui/vue"],
+	["react", "@xihan-ui/react"],
+	["web-components", "@xihan-ui/web-components"]
+];
+function readJson(path) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return;
+	}
+}
+/** 向上找第一个含 .git 的目录。 */
+function gitRoot(start) {
+	let dir = start;
+	for (;;) {
+		if (existsSync(join(dir, ".git"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+}
+/** 向上找最近的 package.json 所在目录，不越过 stop。 */
+function nearestPackageDir(start, stop) {
+	let dir = start;
+	for (;;) {
+		if (existsSync(join(dir, "package.json"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir || dir === stop) return void 0;
+		dir = parent;
+	}
+}
+function declaredDependencies(dir) {
+	const manifest = readJson(join(dir, "package.json")) ?? {};
+	return {
+		...manifest.dependencies,
+		...manifest.devDependencies
+	};
+}
+function declaresXihanUi(dir) {
+	return Object.keys(declaredDependencies(dir)).some((name) => name.startsWith("@xihan-ui/"));
+}
+/** 仓库根的一级子目录里第一个依赖 XiHan.UI 的，如前后端分仓结构里的 frontend/。 */
+function xihanUiChild(repo) {
+	return readdirSync(repo, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules").map((entry) => entry.name).sort().map((name) => join(repo, name)).find((dir) => existsSync(join(dir, "package.json")) && declaresXihanUi(dir));
+}
+/** 从 start 向上逐级找 node_modules/<name>/package.json 里的版本。 */
+function installedVersionOf(start, name) {
+	let dir = start;
+	for (;;) {
+		const manifest = readJson(join(dir, "node_modules", name, "package.json"));
+		if (typeof manifest?.version === "string") return manifest.version;
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+}
+function detectProject(cwd = process.cwd()) {
+	const repo = gitRoot(cwd);
+	let packageDir = nearestPackageDir(cwd, repo);
+	if (repo && (!packageDir || !declaresXihanUi(packageDir))) packageDir = xihanUiChild(repo) ?? packageDir;
+	const root = repo ?? packageDir;
+	if (!packageDir) return {
+		root,
+		packageDir: void 0,
+		framework: void 0,
+		installedVersion: void 0
+	};
+	const declared = declaredDependencies(packageDir);
+	const adapter = ADAPTER_PACKAGES.find(([, name]) => name in declared);
+	const probe = adapter?.[1] ?? "@xihan-ui/core";
+	return {
+		root,
+		packageDir,
+		framework: adapter?.[0],
+		installedVersion: installedVersionOf(packageDir, probe)
+	};
+}
+/** 项目装的版本与 CLI 数据版本不一致时的提示；一致或未安装时返回 undefined。 */
+function versionNotice(project, dataVersion) {
+	if (!project.installedVersion || project.installedVersion === dataVersion) return void 0;
+	return `当前项目装的是 XiHan.UI ${project.installedVersion}，这份 CLI 的数据对应 ${dataVersion}。要按项目版本查询，改用 npx -y @xihan-ui/cli@${project.installedVersion}。`;
+}
+//#endregion
+//#region src/setup.ts
+const CLIENTS = [
+	"claude",
+	"cursor",
+	"vscode",
+	"codex"
+];
+const SETUP_MODES = [
+	"mcp",
+	"skill",
+	"both"
+];
+/** MCP 配置里的服务名。 */
+const SERVER_NAME = "xihan-ui";
+/** 启动服务端的命令；Windows 上 Claude Code 需要经 cmd /c 调 npx。 */
+function serverCommand(client, version, platform) {
+	const args = [
+		"-y",
+		`@xihan-ui/cli@${version}`,
+		"mcp"
+	];
+	if (client === "claude" && platform === "win32") return {
+		command: "cmd",
+		args: [
+			"/c",
+			"npx",
+			...args
+		]
+	};
+	return {
+		command: "npx",
+		args
+	};
+}
+function skillSource() {
+	return readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "skills", "xihan-ui", "SKILL.md"), "utf8");
+}
+/** 按客户端与模式算出要做的事，不碰磁盘。 */
+function planSetup(options) {
+	const actions = [];
+	const { command, args } = serverCommand(options.client, options.version, options.platform);
+	if (options.mode !== "skill") switch (options.client) {
+		case "claude":
+			actions.push({
+				kind: "json",
+				path: join(options.root, ".mcp.json"),
+				key: "mcpServers",
+				entry: {
+					command,
+					args
+				}
+			});
+			break;
+		case "cursor":
+			actions.push({
+				kind: "json",
+				path: join(options.root, ".cursor", "mcp.json"),
+				key: "mcpServers",
+				entry: {
+					command,
+					args
+				}
+			});
+			break;
+		case "vscode":
+			actions.push({
+				kind: "json",
+				path: join(options.root, ".vscode", "mcp.json"),
+				key: "servers",
+				entry: {
+					type: "stdio",
+					command,
+					args
+				}
+			});
+			break;
+		case "codex":
+			actions.push({
+				kind: "print",
+				target: "~/.codex/config.toml",
+				content: [
+					`[mcp_servers.${SERVER_NAME}]`,
+					`command = "${command}"`,
+					`args = [${args.map((a) => `"${a}"`).join(", ")}]`
+				].join("\n")
+			});
+			break;
+	}
+	if (options.mode !== "mcp") {
+		const dir = options.client === "claude" ? join(".claude", "skills") : join(".agents", "skills");
+		actions.push({
+			kind: "file",
+			path: join(options.root, dir, SERVER_NAME, "SKILL.md"),
+			content: skillSource()
+		});
+	}
+	return actions;
+}
+function readConfig(path) {
+	if (!existsSync(path)) return {};
+	const text = readFileSync(path, "utf8");
+	if (!text.trim()) return {};
+	try {
+		const value = JSON.parse(text);
+		if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("顶层不是对象");
+		return value;
+	} catch (error) {
+		throw new Error(`无法解析 ${path}（${error.message}），文件未改动；请按 --dry-run 打印的片段手动合并`);
+	}
+}
+/** 一条动作的说明，--dry-run 与执行后都打印它。 */
+function describeAction(action) {
+	if (action.kind === "json") return `在 ${action.path} 的 ${action.key} 里写入 ${SERVER_NAME}：\n${JSON.stringify({ [action.key]: { [SERVER_NAME]: action.entry } }, null, 2)}`;
+	if (action.kind === "file") return `写入 ${action.path}`;
+	return `把下面这段加进 ${action.target}：\n${action.content}`;
+}
+/** 执行动作：JSON 配置只改 xihan-ui 一项，其余内容原样保留。 */
+function applyAction(action) {
+	if (action.kind === "print") return;
+	mkdirSync(dirname(action.path), { recursive: true });
+	if (action.kind === "file") {
+		writeFileSync(action.path, action.content);
+		return;
+	}
+	const config = readConfig(action.path);
+	const servers = config[action.key] !== null && typeof config[action.key] === "object" ? config[action.key] : {};
+	config[action.key] = {
+		...servers,
+		[SERVER_NAME]: action.entry
+	};
+	writeFileSync(action.path, `${JSON.stringify(config, null, 2)}\n`);
+}
+/** 核对动作是否已经生效；返回未生效的说明。 */
+function checkAction(action) {
+	if (action.kind === "print") return void 0;
+	if (!existsSync(action.path)) return `缺少 ${action.path}`;
+	if (action.kind === "file") return readFileSync(action.path, "utf8") === action.content ? void 0 : `${action.path} 与当前版本的技能不一致`;
+	const current = readConfig(action.path)[action.key]?.[SERVER_NAME];
+	if (!current) return `${action.path} 里没有 ${SERVER_NAME}`;
+	return JSON.stringify(current) === JSON.stringify(action.entry) ? void 0 : `${action.path} 里的 ${SERVER_NAME} 与期望不一致`;
+}
+//#endregion
+//#region src/cli.ts
+const HELP = `xihan-ui —— XiHan.UI 的离线知识库与 MCP 服务端
+
+用法：xihan-ui <命令> [参数] [选项]
+
+查询
+  list [--category <分类>] [--query <关键字>]   按分类列出组件
+  info <组件>                                    组件 API：产物、部件、Props、事件、插槽、状态、键盘
+  doc [<组件|页面>]                              完整文档，示例按写法内联；不带参数列出指南页
+  demo <组件> [<示例>]                           列出示例或输出示例源码
+  token [<关键字>] [--component <组件>]          设计令牌与组件覆盖槽
+  parts <组件>                                   部件选择器、数据属性与覆盖槽
+  design.md                                      设计语言文档
+  changelog [<版本> [<版本>]] [--keyword <词>]   更新日志，两个版本时取区间
+
+集成
+  mcp                                            以 stdio 启动 MCP 服务端
+  setup --client <${CLIENTS.join("|")}>   写入 MCP 配置与技能
+        [--mode <${SETUP_MODES.join("|")}>] [--pin <版本>] [--dry-run] [--check]
+
+选项
+  --framework <vue|react|web-components>   示例写法，缺省取项目里装的适配器
+  --format <markdown|json>                 输出格式，缺省 markdown
+  -v, --version                            打印版本
+  -h, --help                               打印本帮助
+
+组件名可写标识（date-picker）、PascalCase（DatePicker）、导出名（XhDatePickerRoot）、标签（xh-date-picker）或中文名。`;
+var UsageError = class extends Error {};
+const defaultEnvironment = {
+	stdout: (text) => process.stdout.write(`${text}\n`),
+	stderr: (text) => process.stderr.write(`${text}\n`)
+};
+function requireArg(value, usage) {
+	if (!value) throw new UsageError(`缺少参数。用法：xihan-ui ${usage}`);
+	return value;
+}
+function pickFramework(value, fallback) {
+	if (value === void 0) return fallback;
+	const framework = parseFramework(value);
+	if (!framework) throw new UsageError(`--framework 只能是 ${FRAMEWORKS.join(" / ")}，收到 ${value}`);
+	return framework;
+}
+function query(command, positionals, values, knowledge, framework) {
+	const str = (key) => typeof values[key] === "string" ? values[key] : void 0;
+	switch (command) {
+		case "list": {
+			const groups = listComponents(knowledge, {
+				category: str("category"),
+				query: str("query")
+			});
+			return {
+				markdown: renderList(knowledge, groups),
+				json: groups
+			};
+		}
+		case "info": {
+			const entry = requireComponent(knowledge, requireArg(positionals[0], "info <组件>"));
+			return {
+				markdown: renderInfo(knowledge, entry),
+				json: entry
+			};
+		}
+		case "doc": {
+			if (!positionals[0]) {
+				const pages = listPages(knowledge).map(({ markdown: _, ...page }) => page);
+				return {
+					markdown: renderPages(knowledge, listPages(knowledge)),
+					json: pages
+				};
+			}
+			const doc = resolveDoc(knowledge, positionals[0], framework);
+			return {
+				markdown: renderDoc(doc),
+				json: doc
+			};
+		}
+		case "demo": {
+			const entry = requireComponent(knowledge, requireArg(positionals[0], "demo <组件> [<示例>]"));
+			if (!positionals[1]) return {
+				markdown: renderDemoList(entry),
+				json: entry.demos
+			};
+			const demo = demoSource(knowledge, entry, positionals[1], framework);
+			return {
+				markdown: renderDemo(demo),
+				json: {
+					component: entry.id,
+					framework: demo.framework,
+					...demo.demo,
+					source: demo.source
+				}
+			};
+		}
+		case "token": {
+			const result = queryTokens(knowledge, {
+				query: positionals[0],
+				component: str("component")
+			});
+			return {
+				markdown: renderTokens(result),
+				json: result.kind === "component" ? {
+					kind: result.kind,
+					component: result.component.id,
+					tokens: result.tokens
+				} : result
+			};
+		}
+		case "parts": {
+			const { component } = componentParts(knowledge, requireArg(positionals[0], "parts <组件>"));
+			const { id, parts, requiredParts, dataAttributes, aria, componentTokens } = component;
+			return {
+				markdown: renderParts(component),
+				json: {
+					id,
+					parts,
+					requiredParts,
+					dataAttributes,
+					aria,
+					componentTokens
+				}
+			};
+		}
+		case "design.md":
+		case "design-md": {
+			const markdown = knowledge.designMd();
+			return {
+				markdown,
+				json: { markdown }
+			};
+		}
+		case "changelog": {
+			const sections = queryChangelog(knowledge, {
+				from: positionals[0],
+				to: positionals[1],
+				keyword: str("keyword")
+			});
+			return {
+				markdown: renderChangelog(sections),
+				json: sections
+			};
+		}
+		default: throw new UsageError(`未知命令：${command}。xihan-ui --help 查看全部命令`);
+	}
+}
+function runSetup(values, knowledge, out) {
+	const client = values.client;
+	if (typeof client !== "string" || !CLIENTS.includes(client)) throw new UsageError(`--client 只能是 ${CLIENTS.join(" / ")}`);
+	const mode = typeof values.mode === "string" ? values.mode : "both";
+	if (!SETUP_MODES.includes(mode)) throw new UsageError(`--mode 只能是 ${SETUP_MODES.join(" / ")}`);
+	const project = detectProject(out.cwd);
+	if (!project.root) throw new UsageError("当前目录不在 git 仓库里，向上也找不到 package.json，在项目根目录里运行 setup");
+	const version = typeof values.pin === "string" ? values.pin : project.installedVersion ?? knowledge.meta.version;
+	const actions = planSetup({
+		client,
+		mode,
+		root: project.root,
+		version,
+		platform: process.platform
+	});
+	if (values.check) {
+		const problems = actions.map(checkAction).filter((p) => p !== void 0);
+		if (problems.length) {
+			for (const problem of problems) out.stderr(`✗ ${problem}`);
+			return 1;
+		}
+		out.stdout(`✓ ${client} 的 XiHan.UI 配置已就绪（@xihan-ui/cli@${version}）`);
+		return 0;
+	}
+	for (const action of actions) {
+		if (!values["dry-run"]) applyAction(action);
+		out.stdout(`${values["dry-run"] || action.kind === "print" ? "" : "✓ "}${describeAction(action)}`);
+	}
+	return 0;
+}
+/** 运行一次命令行，返回退出码；mcp 命令在输入流结束后返回。 */
+async function runCli(argv, environment = {}) {
+	const out = {
+		...defaultEnvironment,
+		...environment
+	};
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: [...argv],
+			allowPositionals: true,
+			strict: true,
+			options: {
+				"category": { type: "string" },
+				"query": { type: "string" },
+				"component": { type: "string" },
+				"keyword": { type: "string" },
+				"framework": { type: "string" },
+				"format": { type: "string" },
+				"client": { type: "string" },
+				"mode": { type: "string" },
+				"pin": { type: "string" },
+				"dry-run": { type: "boolean" },
+				"check": { type: "boolean" },
+				"version": {
+					type: "boolean",
+					short: "v"
+				},
+				"help": {
+					type: "boolean",
+					short: "h"
+				}
+			}
+		});
+	} catch (error) {
+		out.stderr(`${error.message}\n\n${HELP}`);
+		return 2;
+	}
+	const { values, positionals } = parsed;
+	const [command, ...rest] = positionals;
+	if (values.help || !command && !values.version) {
+		out.stdout(HELP);
+		return 0;
+	}
+	try {
+		const knowledge = loadKnowledge(out.dataDir);
+		if (values.version) {
+			out.stdout(knowledge.meta.version);
+			return 0;
+		}
+		const project = detectProject(out.cwd);
+		const framework = pickFramework(values.framework, project.framework ?? "vue");
+		const notice = versionNotice(project, knowledge.meta.version);
+		if (command === "mcp") {
+			const instructions = [
+				`XiHan.UI ${knowledge.meta.version} 的离线知识库。写 XiHan.UI 代码前先用 xihan_ui_info 核对组件 API，用 xihan_ui_doc / xihan_ui_demo 取文档与示例，样式只用 xihan_ui_parts 与 xihan_ui_token 查得到的部件选择器与令牌。`,
+				`缺省示例写法：${framework}。`,
+				...notice ? [notice] : []
+			].join("\n");
+			if (notice) out.stderr(notice);
+			await serveStdio({
+				context: {
+					knowledge,
+					framework
+				},
+				version: knowledge.meta.version,
+				instructions
+			});
+			return 0;
+		}
+		if (command === "setup") return runSetup(values, knowledge, out);
+		const format = values.format ?? "markdown";
+		if (format !== "markdown" && format !== "json") throw new UsageError(`--format 只能是 markdown / json，收到 ${format}`);
+		const result = query(command, rest, values, knowledge, framework);
+		if (notice) out.stderr(notice);
+		out.stdout(format === "json" ? JSON.stringify(result.json, null, 2) : result.markdown);
+		return 0;
+	} catch (error) {
+		if (error instanceof QueryError) {
+			out.stderr(error.message);
+			if (error.suggestions.length) out.stderr(`候选：\n${error.suggestions.map((s) => `  ${s}`).join("\n")}`);
+			return 1;
+		}
+		if (error instanceof UsageError || error instanceof ArgumentError) {
+			out.stderr(error.message);
+			return 2;
+		}
+		out.stderr(error.message);
+		return 1;
+	}
+}
+//#endregion
+export { PROMPTS, PROTOCOL_VERSIONS, TOOLS, handleMessage, loadKnowledge, runCli, serveStdio };
+
+//# sourceMappingURL=index.js.map