@plumeai/plugin-sdk 0.0.0-stage → 0.1.3

package/lib/check.mjs

@@ -0,0 +1,23 @@
+/**
+ * 检查一个插件：先用 SDK 自带的 TypeScript 做类型检查（插件作者的机器上不用另装），再跑插件规则（lint/）。
+ */
+
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { formatProblem, lintPlugin } from "./lint/index.mjs";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * @param {string} target 插件目录（有 tsconfig.json）
+ * @returns {Promise<boolean>} 通过没有；报错直接打到终端
+ */
+export async function checkPlugin(target) {
+	const dir = resolve(target);
+	const tsc = join(dirname(require.resolve("typescript/package.json")), "bin/tsc");
+	const result = spawnSync(process.execPath, [tsc, "-p", join(dir, "tsconfig.json")], { stdio: "inherit" });
+	const problems = await lintPlugin(dir);
+	if (problems.length > 0) console.error(`插件规则没通过：\n\n${problems.map((problem) => `  ${formatProblem(problem, dir)}`).join("\n")}\n`);
+	return result.status === 0 && problems.length === 0;
+}

package/lib/dev.mjs

@@ -0,0 +1,52 @@
+/**
+ * 开发一个插件：构建、装进 Plume，然后盯着源码，一改就重新构建、重新装。Plume 开着的话每次都当场换上新的。
+ */
+
+import { watch } from "node:fs";
+import { join, resolve } from "node:path";
+import { buildPlugin } from "./build.mjs";
+import { installPlugin } from "./install.mjs";
+
+/** 连续保存（编辑器、agent 一次改几个文件）只算一次。 */
+const SETTLE_MS = 200;
+
+/**
+ * @param {string} target 插件目录
+ * @param {{ root?: string, log?: (line: string) => void }} [options] root：装到哪个目录下
+ * @returns {() => void} 停止监视
+ */
+export function devPlugin(target, options = {}) {
+	const dir = resolve(target);
+	const log = options.log ?? console.log;
+	let timer;
+	let running = Promise.resolve();
+
+	const round = () => {
+		running = running.then(async () => {
+			try {
+				const built = await buildPlugin(dir);
+				const installed = installPlugin(dir, options.root);
+				log(`✓ ${built} → ${installed}`);
+			} catch (error) {
+				// esbuild 的报错它自己已经打过了；没构建成功就不装，Plume 里还是上一份能用的。
+				if (!error?.errors) log(`✗ ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+	};
+
+	round();
+	const watchers = [
+		watch(join(dir, "src"), { recursive: true }, schedule),
+		watch(dir, (_event, name) => {
+			if (name === "package.json" || name === "README.md") schedule();
+		}),
+	];
+	function schedule() {
+		clearTimeout(timer);
+		timer = setTimeout(round, SETTLE_MS);
+	}
+	return () => {
+		clearTimeout(timer);
+		for (const watcher of watchers) watcher.close();
+	};
+}

package/lib/icons.mjs

@@ -0,0 +1,2 @@
+// 插件里的 `@plume/ui/icons` 构建时指到这里：和产品用同一套图标（lucide），打进插件，只打用到的。
+export * from "lucide-react";

package/lib/init.mjs

@@ -0,0 +1,109 @@
+/**
+ * 从 template/ 生成一个新插件。
+ *
+ * 两种情况：
+ * - 独立项目（SDK 随 Plume 应用发来，或者目标不在 Plume 仓库里）：不经 npm，node_modules 里链到这份 SDK（见 link.mjs）；
+ *   另外带上 skill、AGENTS.md、CLAUDE.md、.gitignore，让接手的 agent 一打开项目就知道怎么写。
+ * - 目标在一个 pnpm workspace 里（Plume 本体仓库，或插件仓库 plume-plugins 这样的插件集合）：本体仓库里 SDK 依赖写
+ *   `workspace:*`，别的 workspace 里写 npm 上的版本 `^<这份 SDK 的版本>`；skill 和 AGENTS.md 用仓库根目录的，不另带；
+ *   构建交给仓库的 `pnpm build:plugins`。
+ */
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { linkSdk } from "./link.mjs";
+import { DIR_NAME } from "./manifest.mjs";
+
+const sdk = resolve(import.meta.dirname, "..");
+const manifest = JSON.parse(readFileSync(join(sdk, "package.json"), "utf8"));
+
+/** 插件名：小写，点分段，段里可以有连字符。 */
+export const PLUGIN_NAME = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/;
+
+/** 只给独立项目的文件。 */
+const STANDALONE_ONLY = new Set(["AGENTS.md", "CLAUDE.md", "gitignore"]);
+
+/** `start` 所在的 pnpm workspace 根目录（往上找 pnpm-workspace.yaml）。 */
+function workspaceOf(start) {
+	for (let dir = start; dir !== dirname(dir); dir = dirname(dir)) {
+		if (existsSync(join(dir, "pnpm-workspace.yaml"))) return dir;
+	}
+	return undefined;
+}
+
+/** 这份 SDK 是从 npm 装进某个项目的（在 node_modules 里）。 */
+const installed = sdk.split(sep).includes("node_modules");
+
+/** SDK 源码所在的 pnpm workspace 根目录（Plume 本体仓库）；随应用发的、从 npm 装的那份没有。 */
+function workspaceRoot() {
+	return installed ? undefined : workspaceOf(sdk);
+}
+
+/** skill 的来源：随应用发的那份里是 skill/（打包时复制进去），仓库里是根目录的 skills/plume-plugin。 */
+export function skillDir() {
+	const packed = join(sdk, "skill");
+	if (existsSync(join(packed, "SKILL.md"))) return packed;
+	const root = workspaceRoot();
+	const repo = root && join(root, "skills/plume-plugin");
+	if (repo && existsSync(join(repo, "SKILL.md"))) return repo;
+	throw new Error("找不到 skill plume-plugin");
+}
+
+function copyTemplate(from, to, replace, skip) {
+	mkdirSync(to, { recursive: true });
+	for (const name of readdirSync(from)) {
+		if (skip(name)) continue;
+		const source = join(from, name);
+		const target = join(to, name === "gitignore" ? ".gitignore" : name);
+		if (statSync(source).isDirectory()) copyTemplate(source, target, replace, () => false);
+		else writeFileSync(target, replace(readFileSync(source, "utf8")));
+	}
+}
+
+/**
+ * @param {string} target 新插件的目录，不能已经存在
+ * @param {{ name?: string, displayName?: string }} [options]
+ * @returns {{ dir: string, name: string, workspace: boolean }}
+ */
+export function initPlugin(target, options = {}) {
+	const dir = resolve(target);
+	const key = basename(dir);
+	if (!DIR_NAME.test(key)) throw new Error(`目录名 ${key} 不行：只能用小写字母、数字和连字符`);
+	if (existsSync(dir)) throw new Error(`${dir} 已经存在`);
+	const root = workspaceRoot();
+	// 目标所在的 workspace：SDK 源码所在的本体仓库，或者从 npm 装了 SDK 的仓库（比如插件仓库）。随应用发的 SDK 总是建独立项目。
+	const home = root !== undefined || installed ? workspaceOf(dirname(dir)) : undefined;
+	const workspace = home !== undefined;
+	const sdkDep = home !== undefined && home === root ? "workspace:*" : `^${manifest.version}`;
+	const name = options.name ?? (workspace ? `plume.${key}` : key);
+	if (!PLUGIN_NAME.test(name)) throw new Error(`插件名 ${name} 不行：小写字母、数字、连字符，用点分段`);
+	const displayName = options.displayName ?? key;
+	const tool = `${key.replaceAll("-", "_")}_greet`;
+
+	const replace = (text) => text.replaceAll("__NAME__", name).replaceAll("__TOOL__", tool).replaceAll("__DISPLAY__", displayName);
+	copyTemplate(join(sdk, "template"), dir, replace, (file) => workspace && STANDALONE_ONLY.has(file));
+
+	const deps = manifest.dependencies;
+	const pkg = {
+		name: `@plume-plugins/${key}`,
+		version: "0.1.0",
+		description: "",
+		keywords: [],
+		plume: { displayName, category: "" },
+		private: true,
+		type: "module",
+		// 仓库里照 workspace 的规矩写依赖、由 pnpm 装；独立项目不经 npm，靠 link.mjs 建的链接。
+		...(workspace
+			? {
+					scripts: { typecheck: "tsc -p tsconfig.json" },
+					devDependencies: { "@plumeai/plugin-sdk": sdkDep, "@types/node": deps["@types/node"], "@types/react": deps["@types/react"] },
+				}
+			: {}),
+	};
+	writeFileSync(join(dir, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
+	if (!workspace) {
+		cpSync(skillDir(), join(dir, ".claude/skills/plume-plugin"), { recursive: true, dereference: true });
+		linkSdk(dir);
+	}
+	return { dir, name, workspace };
+}

package/lib/install.mjs

@@ -0,0 +1,80 @@
+/**
+ * 把构建好的插件装进本机的 Plume：复制 package.json、README.md、images/、icon.png、dist/、随包的 skills/、.mcp.json 和 LICENSE 到 `~/.plume/plugins/<目录名>/`，
+ * 和插件市场装的放在同一个地方。Plume 监视这个目录，开着的话当场加载（已经装过的就换成新的）。
+ *
+ * 先复制进旁边的暂存目录再整个换上去：Plume 看到的要么是旧的一份，要么是新的一份，不会是复制到一半的。
+ *
+ * 换的时候先把旧目录挪开、再把新目录挪进来，最后才删旧的；不先 `rm -r`：Windows 上旧版本里还有开着的文件
+ * （插件起的 `.exe`、编辑器打开着的文件）时删不掉，`rm -r` 会把它周围的删光、卡在它上面，留下一个删了一半的插件。
+ * 挪开整个目录在这时是整个被拒的，什么都不动，旧的那份照常能用。和应用里市场的装法（apps/desktop 的 plugin-swap.ts）一样。
+ */
+
+import { cpSync, existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { DIR_NAME, PLUGIN_ENTRY, SHIPPED } from "./manifest.mjs";
+
+/**
+ * @param {string} source 插件目录
+ * @param {string} [root] 装到哪个目录下，缺省 Plume 数据目录（`PLUME_HOME`，没设是 ~/.plume）下的 plugins
+ * @returns {string} 装到的目录
+ */
+export function installPlugin(source, root = join(process.env.PLUME_HOME || join(homedir(), ".plume"), "plugins")) {
+	const dir = resolve(source);
+	const key = basename(dir);
+	if (!DIR_NAME.test(key)) throw new Error(`目录名 ${key} 不行：只能用小写字母、数字和连字符`);
+	if (!existsSync(join(dir, PLUGIN_ENTRY))) throw new Error(`没有 ${PLUGIN_ENTRY}，先构建`);
+	const target = join(root, key);
+	// 暂存目录不在 root 里面：Plume 只认 root 下一层的目录，暂存的不会被当成插件。
+	const staging = join(root, "..", ".plugins-staging", key);
+	rmSync(staging, { recursive: true, force: true });
+	mkdirSync(staging, { recursive: true });
+	for (const name of SHIPPED) {
+		if (existsSync(join(dir, name))) cpSync(join(dir, name), join(staging, name), { recursive: true });
+	}
+	mkdirSync(root, { recursive: true });
+	const retired = join(root, "..", ".plugins-retired", `${Date.now()}-${randomUUID().slice(0, 8)}-${key}`);
+	if (existsSync(target)) {
+		mkdirSync(dirname(retired), { recursive: true });
+		try {
+			renameWithRetry(target, retired);
+		} catch (error) {
+			rmSync(staging, { recursive: true, force: true });
+			throw busy(error);
+		}
+	}
+	try {
+		renameWithRetry(staging, target);
+	} catch (error) {
+		if (existsSync(retired)) renameSync(retired, target);
+		rmSync(staging, { recursive: true, force: true });
+		throw busy(error);
+	}
+	// 尽力删：还有文件开着的留在 .plugins-retired 里，Plume 下次换插件时清掉。
+	rmSync(retired, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+	return target;
+}
+
+/** Windows 上别的进程开着文件（或目录里的文件）时改名报的错。 */
+const HELD_OPEN = new Set(["EPERM", "EBUSY", "EACCES"]);
+const heldOpen = (error) => process.platform === "win32" && HELD_OPEN.has(error?.code);
+
+/** 改名；Windows 上被占用时等一等再试（杀毒软件、索引会去读刚写完的文件），每次多等 50ms，一共 8 次。 */
+function renameWithRetry(from, to) {
+	for (let attempt = 1; ; attempt++) {
+		try {
+			renameSync(from, to);
+			return;
+		} catch (error) {
+			if (attempt >= 8 || !heldOpen(error)) throw error;
+			Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * attempt);
+		}
+	}
+}
+
+function busy(error) {
+	return heldOpen(error)
+		? new Error("插件的文件正被占用（多半是它启动的程序，或打开着它的编辑器），什么都没有改动。关掉占用它的程序后再试。", { cause: error })
+		: error;
+}

package/lib/link.mjs

@@ -0,0 +1,44 @@
+/**
+ * 让插件项目找到 SDK：在它的 node_modules 里建几个链接，指到这份 SDK（随 Plume 应用发的那份，或仓库里这份）。
+ *
+ * 不经 npm：插件的 tsconfig 写 `"extends": "@plumeai/plugin-sdk/tsconfig.json"`，`types` 写 `["node"]`，
+ * 这几个名字靠链接解析到 SDK 自带的副本上，插件的写法和仓库里的一样。
+ * Plume 挪了位置，或者用 npm 装了别的包（npm 会删掉它不认识的链接），重新跑一次 `plume-plugin link`。
+ */
+
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+
+const sdk = resolve(import.meta.dirname, "..");
+const require = createRequire(join(sdk, "package.json"));
+
+/** 链进插件 node_modules 的包 → 它在 SDK 这边的目录。 */
+function targets() {
+	return {
+		"@plumeai/plugin-sdk": sdk,
+		"@types/node": dirname(require.resolve("@types/node/package.json")),
+		"@types/react": dirname(require.resolve("@types/react/package.json")),
+	};
+}
+
+/** @param {string} target 插件目录 */
+export function linkSdk(target) {
+	const dir = resolve(target);
+	for (const [name, source] of Object.entries(targets())) {
+		const path = join(dir, "node_modules", name);
+		// 已有的（旧链接，或者 npm 装的真目录）换掉：用的必须是这份 SDK。
+		if (existsSync(path) || isLink(path)) rmSync(path, { recursive: true, force: true });
+		mkdirSync(dirname(path), { recursive: true });
+		// Windows 上建目录链接要管理员权限，junction 不用。
+		symlinkSync(source, path, process.platform === "win32" ? "junction" : "dir");
+	}
+}
+
+function isLink(path) {
+	try {
+		return lstatSync(path).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}

package/lib/lint/i18n.mjs

@@ -0,0 +1,149 @@
+/**
+ * 硬编码中文：界面上给人读的文字要走 i18n，不能直接写在代码里。插件检查（`plume-plugin check`）和 Plume 自己的
+ * `pnpm check:i18n` 用的是这同一份。
+ *
+ * 算一条的：字符串字面量或 JSX 文本里有汉字或中文标点。不算的：注释（注释本来就用中文写）、
+ * 日志调用的参数（`console.*` 和 Plume 的 log，写给调试的人看的）、紧跟在 `i18n-exempt` 注释后面、到下一个空行为止的几行
+ * （给人读但不能翻译的字：发给模型的提示词、和存量数据比对的固定字符串……注释里写明原因）。
+ *
+ * 中文标点单独算：词都翻译完以后剩下的就是 `parts.join("、")`、`${name}：${message}` 这种，
+ * 只查汉字会放过它们，而它们在英文界面里会夹出中文标点。
+ *
+ * 插件的文案：自带中英两份，放在 src/messages.ts（不查）；界面入口用 `@plume/ui` 的 useI18n() 取当前语言，逻辑入口用 ctx.locale()。
+ */
+
+/** 汉字，和中文句子用的标点（分隔、括号、句读；不是全部全角字符）。 */
+const CHINESE = /[一-鿿、，：；（）「」『』。！？]/;
+
+/**
+ * 去掉注释，换行保留（块注释里的也一个换一个），行号才对得上，`i18n-exempt` 也按行认。
+ * 认得字符串：示例 URL 里的 `//` 不是注释，当成注释会把那一行后面的文字都跳过去。
+ * 模板字符串会嵌套，`${…}` 里又可以有字符串和注释，所以用一个栈。
+ */
+function stripComments(src) {
+	let out = "";
+	const stack = [];
+	const inside = () => stack[stack.length - 1];
+
+	for (let i = 0; i < src.length;) {
+		const char = src[i];
+		const two = src.slice(i, i + 2);
+		const state = inside();
+
+		if (state === "'" || state === '"' || state === "`") {
+			if (char === "\\") {
+				out += two;
+				i += 2;
+				continue;
+			}
+			if (char === state) stack.pop();
+			else if (state === "`" && two === "${") {
+				stack.push("{");
+				out += two;
+				i += 2;
+				continue;
+			}
+			out += char;
+			i += 1;
+			continue;
+		}
+
+		// 代码，或者 `${…}` 里面：这里的注释都是注释。
+		if (two === "//") {
+			// 停在换行前，让循环自己把换行抄过去；这里再补一个，后面的行号都会错一行。
+			const end = src.indexOf("\n", i);
+			i = end === -1 ? src.length : end;
+			continue;
+		}
+		if (two === "/*") {
+			const end = src.indexOf("*/", i + 2);
+			const body = src.slice(i, end === -1 ? src.length : end + 2);
+			i = end === -1 ? src.length : end + 2;
+			out += body.replace(/[^\n]/g, "");
+			continue;
+		}
+		if (char === "'" || char === '"' || char === "`") stack.push(char);
+		else if (char === "{") stack.push("{");
+		else if (char === "}" && state === "{") stack.pop();
+		out += char;
+		i += 1;
+	}
+	return out;
+}
+
+/** 只进日志的调用：`console.*`，和 Plume 自己的日志函数（`log(…)`、`this.options.log(…)`、`ctx.log.warn(…)`）。 */
+const LOG_CALL = /\b(?:console\s*\.\s*(?:log|info|warn|error|debug|trace)|(?:\w+\s*\.\s*)*log(?:\s*\.\s*(?:info|warn|error))?)\s*\(/g;
+
+/**
+ * 把日志调用的参数整段抹掉（换行保留）：只进日志的不算。
+ * 找调用时先把字符串内容遮住，字符串里恰好有 `console.log(` 不会被当成调用，日志字符串里的括号也不会提前结束它。
+ */
+function stripLogs(stripped) {
+	const masked = stripped.replace(
+		/"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|`(?:[^`\\]|\\.)*`/g,
+		(literal) => literal[0] + literal.slice(1, -1).replace(/[^\n]/g, " ") + literal.at(-1),
+	);
+	let out = stripped;
+	for (const call of masked.matchAll(LOG_CALL)) {
+		const open = call.index + call[0].length - 1;
+		let close = masked.length;
+		for (let i = open, depth = 0; i < masked.length; i++) {
+			if (masked[i] === "(") depth += 1;
+			else if (masked[i] === ")" && --depth === 0) {
+				close = i;
+				break;
+			}
+		}
+		out = out.slice(0, open + 1) + out.slice(open + 1, close).replace(/[^\n]/g, " ") + out.slice(close);
+	}
+	return out;
+}
+
+/**
+ * `i18n-exempt` 注释管到的行：从下一行到第一个空行。
+ *
+ * 给有这样一种字留的：人读不到、也不能跟着语言变的固定字符串（发给模型的提示词、和存量数据比对的词）。
+ * 整个文件豁免太宽（同一个文件里往往还有真正的界面文案），所以豁免写在它管的那几行上面，原因写在注释里。
+ * 一条注释管到空行为止，一张表只要写一次。
+ */
+function exemptLines(source) {
+	const lines = source.split("\n");
+	const exempt = new Set();
+	for (let i = 0; i < lines.length; i++) {
+		if (!/i18n-exempt\b/.test(lines[i])) continue;
+		for (let j = i + 1; j < lines.length && lines[j].trim() !== ""; j++) exempt.add(j + 1);
+	}
+	return exempt;
+}
+
+/**
+ * 一个文件里所有给人读的中文，`{ line, text }`。
+ *
+ * 先认字符串字面量，再把它们的内容遮住：剩下还有中文的，只能是 JSX 文本（`.tsx` 里标签之间的字，
+ * 包括写在 `{cond && <p>…</p>}` 这种表达式里的）。不去配对标签和花括号：配对的写法会被箭头函数的 `>`
+ * 和表达式里的 `n > 1` 带偏，整段跳过真正的文字。
+ *
+ * @param {string} source
+ * @returns {{ line: number, text: string }[]}
+ */
+export function chineseFindings(source) {
+	const stripped = stripLogs(stripComments(source));
+	const spared = exemptLines(source);
+	const found = [];
+	const at = (index) => stripped.slice(0, index).split("\n").length;
+	const keep = (line, text) => {
+		if (!spared.has(line)) found.push({ line, text });
+	};
+	// 认得转义，`"他说 \"好\""` 是一条，不是两条。
+	const literal = /"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|`(?:[^`\\]|\\.)*`/g;
+	for (const match of stripped.matchAll(literal)) {
+		if (CHINESE.test(match[0])) keep(at(match.index), match[0].trim().slice(0, 80));
+	}
+	const masked = stripped.replace(literal, (text) => text.replace(/[^\n]/g, " "));
+	masked.split("\n").forEach((line, index) => {
+		// 字符串已经遮住，剩下的 `//` 是注释（正则字面量里的引号可能让前面没认出它）。
+		const code = line.replace(/\/\/.*$/, "");
+		if (CHINESE.test(code)) keep(index + 1, code.trim().replace(/\s+/g, " ").slice(0, 80));
+	});
+	return found;
+}

package/lib/lint/imports.mjs

@@ -0,0 +1,83 @@
+/**
+ * 插件只引用公开接口（插件检查 `plume-plugin check` 和 Plume 自己的 `pnpm check:plugins` 用的是这同一份）。
+ * 插件 src 里的 import / export from / import() / require() 只能是
+ * - 相对路径，且不出插件自己的目录；
+ * - `node:*`；
+ * - `@plume/contract`、`@plume/contract/ui`，而且只能 `import type` / `export type`（它只有类型，运行时从 ctx / ui 上拿）；
+ * - 界面入口共享的 `react`、`react/jsx-runtime`、`@plume/ui`、`@plume/ui/icons`、`@plume/styles`；
+ * - 插件自己 package.json 里声明的第三方包（及其子路径）。
+ * `@plume/` 下的其他包是宿主的实现，声明了也不行。
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+
+const CONTRACT = new Set(["@plume/contract", "@plume/contract/ui"]);
+const SHARED = new Set(["react", "react/jsx-runtime", "@plume/ui", "@plume/ui/icons", "@plume/styles"]);
+
+/** 去掉注释。行注释只认行首或空白后的 `//`，字符串里的 URL 不受影响。 */
+export const stripComments = (text) => text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|\s)\/\/.*$/gm, "$1");
+
+/** 包名：`@scope/name/sub` → `@scope/name`，`name/sub` → `name`。 */
+const packageOf = (specifier) =>
+	specifier
+		.split("/")
+		.slice(0, specifier.startsWith("@") ? 2 : 1)
+		.join("/");
+
+/** 一个文件里的引用：{ specifier, typeOnly }。import 子句只由标识符、花括号、逗号、星号、空白组成，不会跨进代码里。 */
+function imports(text) {
+	const code = stripComments(text);
+	const found = [];
+	for (const match of code.matchAll(/\bimport\s+(type\s+)?(?:[\w$*{},\s]+?\s+from\s*)?["']([^"']+)["']/g))
+		found.push({ specifier: match[2], typeOnly: Boolean(match[1]) });
+	for (const match of code.matchAll(/\bexport\s+(type\s+)?(?:\*(?:\s+as\s+[\w$]+)?|\{[\w$,\s]*\})\s*from\s*["']([^"']+)["']/g))
+		found.push({ specifier: match[2], typeOnly: Boolean(match[1]) });
+	// `typeof import("x")` 只是类型，但和运行时的 import() 一样要在白名单里，按非纯类型算更严。
+	for (const match of code.matchAll(/\b(?:import|require)\s*\(\s*["']([^"']+)["']\s*\)/g)) found.push({ specifier: match[1], typeOnly: false });
+	return found;
+}
+
+/** dir 下的 .ts、.tsx，跳过 node_modules、dist。 */
+function sourceFiles(dir, out = []) {
+	if (!existsSync(dir)) return out;
+	for (const name of readdirSync(dir)) {
+		if (["node_modules", "dist"].includes(name)) continue;
+		const path = join(dir, name);
+		if (statSync(path).isDirectory()) sourceFiles(path, out);
+		else if (/\.tsx?$/.test(name)) out.push(path);
+	}
+	return out;
+}
+
+/**
+ * 一个插件的越界引用。返回 `{ file, message }`。
+ * @param {string} pluginDir 插件目录（有 package.json 和 src/）
+ * @param {{ allow?: Set<string> }} [options] allow：额外允许、声明了就能用的 `@plume/` 包（Plume 仓库里的内置插件用 packages/infra 下的通用库）
+ */
+export function importProblems(pluginDir, options = {}) {
+	const allow = options.allow ?? new Set();
+	const manifest = JSON.parse(readFileSync(join(pluginDir, "package.json"), "utf8"));
+	const declared = new Set(
+		Object.keys({ ...manifest.dependencies, ...manifest.devDependencies }).filter((dep) => !dep.startsWith("@plume/") || allow.has(dep)),
+	);
+	const found = [];
+	for (const file of sourceFiles(join(pluginDir, "src"))) {
+		const report = (message) => found.push({ file, message });
+		for (const { specifier, typeOnly } of imports(readFileSync(file, "utf8"))) {
+			if (specifier.startsWith(".")) {
+				const target = resolve(dirname(file), specifier);
+				if (target !== pluginDir && !target.startsWith(pluginDir + sep)) report(`${specifier}：出了插件自己的目录`);
+			} else if (specifier.startsWith("node:") || SHARED.has(specifier)) {
+				// 公开的运行时模块。
+			} else if (CONTRACT.has(specifier)) {
+				if (!typeOnly) report(`${specifier}：只能 import type / export type，运行时的东西从 ctx / ui 上拿`);
+			} else if (specifier.startsWith("@plume/") && !allow.has(packageOf(specifier))) {
+				report(`${specifier}：不是公开接口，插件只能用 @plume/contract（类型）、@plume/ui、@plume/ui/icons、@plume/styles`);
+			} else if (!declared.has(packageOf(specifier))) {
+				report(`${specifier}：没在插件的 package.json 里声明`);
+			}
+		}
+	}
+	return found;
+}

package/lib/lint/index.mjs

@@ -0,0 +1,54 @@
+/**
+ * 插件检查里类型检查之外的规则：只引用公开接口（imports.mjs）、样式（styles.mjs）、不写死中文（i18n.mjs）。
+ * `plume-plugin check` 和插件仓库的检查用 lintPlugin；Plume 自己的检查脚本按规则分别引用这几个模块。
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { chineseFindings } from "./i18n.mjs";
+import { importProblems } from "./imports.mjs";
+import { pluginStyleProblems, pluginTailwind } from "./styles.mjs";
+
+// 一次查很多个插件时先编译一次 Tailwind，作为 isTailwind 传给每次 lintPlugin。
+export { pluginTailwind };
+
+/** dir 下扩展名在 exts 里的文件，跳过 node_modules、dist、out 和 skip 里的目录名。 */
+function files(dir, exts, skip = [], out = []) {
+	if (!existsSync(dir)) return out;
+	for (const name of readdirSync(dir)) {
+		if (["node_modules", "dist", "out", ...skip].includes(name)) continue;
+		const path = join(dir, name);
+		if (statSync(path).isDirectory()) files(path, exts, skip, out);
+		else if (exts.some((ext) => name.endsWith(ext))) out.push(path);
+	}
+	return out;
+}
+
+const lineAt = (text, index) => text.slice(0, index).split("\n").length;
+
+/**
+ * @typedef {{ file: string, line?: number, rule: string, message: string }} Problem
+ * @param {string} pluginDir
+ * @param {{ isTailwind?: (candidate: string) => boolean }} [options] isTailwind 缺省用 SDK 带的 Tailwind 和 theme.css
+ * @returns {Promise<Problem[]>}
+ */
+export async function lintPlugin(pluginDir, options = {}) {
+	const isTailwind = options.isTailwind ?? (await pluginTailwind());
+	const problems = importProblems(pluginDir).map(({ file, message }) => ({ file, rule: "引用", message }));
+	for (const file of files(pluginDir, [".ts", ".tsx", ".css"])) {
+		const text = readFileSync(file, "utf8");
+		for (const { index, rule, message } of pluginStyleProblems(file, text, isTailwind)) problems.push({ file, line: lineAt(text, index), rule, message });
+	}
+	// 测试写给开发者看，文案在 src/messages.ts 里本来就是两种语言：都不查中文。
+	for (const file of files(pluginDir, [".ts", ".tsx"], ["test"])) {
+		if (relative(pluginDir, file).replaceAll("\\", "/") === "src/messages.ts") continue;
+		for (const { line, text } of chineseFindings(readFileSync(file, "utf8")))
+			problems.push({ file, line, rule: "中文", message: `${text}：界面文案放进 src/messages.ts，按语言取（useI18n()、ctx.locale()）` });
+	}
+	return problems;
+}
+
+/** 一条问题写成一行，路径相对 base。 */
+export function formatProblem({ file, line, rule, message }, base) {
+	return `${relative(base, file)}${line ? `:${line}` : ""}  [${rule}] ${message}`;
+}