vite-plugin-siyuan 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 svchord
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# vite-plugin-siyuan
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+思源主题/插件开发的 Vite 插件：注入构建配置、链接到工作区、热重载、校验产物、打包。
+
+## 安装
+
+要求 Node.js >= 22.18、Vite >= 6。
+
+```bash
+pnpm add -D vite-plugin-siyuan
+```
+
+## 使用
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import siyuan from 'vite-plugin-siyuan';
+
+export default defineConfig({
+  // entry 必填：主题指向 CSS，插件指向 TS/JS
+  plugins: [siyuan({ entry: 'src/main.css' })],
+});
+```
+
+```bash
+pnpm vite build --watch
+```
+
+`vite dev` 不适用：思源从磁盘读产物，而 dev server 只在内存里编译。插件的 `apply` 固定为 `'build'`。
+
+## 选项
+
+| 选项 | 说明 |
+|---|---|
+| `entry` | **必填**。构建入口，相对项目根。主题指向 CSS，插件指向 TS/JS |
+| `kind` | `'theme'` / `'plugin'`；缺省时在 `public/`、项目根依次查找 `theme.json` / `plugin.json` 推断 |
+| `outDir` | 产物目录；缺省 `./dev`（watch）/ `./dist`（生产） |
+
+> `entry` 必填是因为产物名是固定契约（主题 `theme.css`、插件 `index.js`）。
+> 入口猜错不会报错，只会静默产出思源加载不到的东西——所以宁可要求显式指定。
+
+## 做什么
+
+两种模式行为差别很大。
+
+### watch（`vite build --watch`）
+
+1. **注入构建配置**：主题产出 `theme.css`；插件走 `lib` CJS 单文件产出 `index.js`。`base: './'` 保证宿主下资源不 404。用 `mergeConfig` 合并，**用户已写的值优先**。
+2. **链接产物**：把 `dev/` 链接到 `{workspace}/data/themes|plugins/{name}`。插件目录必须是真 symlink（思源 Go 运行时按 `ModeSymlink` 判定），主题可用 junction 兜底。
+3. **激活**：主题调 `setAppearance` 选中它；插件调 `setPetalEnabled` 启用。
+4. **热重载**：产物变化后合并 250ms 广播 `reloadUI`，思源整页刷新。
+
+### 生产（`vite build`）
+
+只做 **校验 + 打包**：检查清单字段、版本一致性、必需产物、主题的 `@layer` 与双重包装颜色；通过后在**项目根目录**写出 `package.zip`。
+
+生产构建**不会**链接目录、不会切换主题/插件；校验不通过会直接抛错中止。
+
+## 输出
+
+每轮构建结束时打印一行，供 agent 判断「可以测量了」：
+
+```
+[vite-plugin-siyuan] build #12 ready · theme · watch
+```
+
+生产构建对应的是：
+
+```
+[vite-plugin-siyuan] build #1 ready · theme · package.zip
+```
+
+watch 模式首次就绪后还会打印桌面端 / 移动端两个稳定预览入口。
+
+## 环境变量
+
+| 变量 | 说明 |
+|---|---|
+| `SIYUAN_PORT` | kernel 端口；缺省用 kernel 进程 PID 匹配 `port.json`，再探测记录端口与 6806–6809 |
+| `SIYUAN_THEME_DIR` | 主题安装父目录（`{workspace}/data/themes`），实际装到 `{该目录}/{name}` |
+| `SIYUAN_PLUGIN_DIR` | 插件安装父目录（`{workspace}/data/plugins`），同上 |
+| `SIYUAN_TOKEN` | 开了 API token 时使用 |
+| `SIYUAN_NO_ELEVATION=1` | 不弹 UAC 提权（CI 环境自动不弹） |
+| `SIYUAN_DEBUG=1` | 输出 debug 级日志 |
+
+> 旧名 `SYD_NO_ELEVATION` / `SYD_DEBUG` 仍然兼容。
+
+## 配套 CLI
+
+测量真实渲染用 [siyuan-devtools](https://github.com/svchord/siyuan-devtools)。
+
+## 参与开发
+
+### 提 PR
+
+1. 先开 issue 对齐需求，避免白做。
+2. PR 标题必须符合 [Conventional Commits](https://www.conventionalcommits.org/)——CI 会检查：
+   - `feat: ...` → 次版本（0.2.0）
+   - `fix: ...` → 补丁版本（0.1.1）
+   - `feat!: ...` → 1.0 之前只升次版本
+   - `docs:` / `chore:` / `ci:` / `test:` / `refactor:` → 不发版
+3. 合并方式固定为 **Squash and merge**，PR 标题会成为最终 commit。
+
+### 发布流程
+
+用 [release-please](https://github.com/googleapis/release-please) 自动管理版本，仓库里不手写版本号：
+
+```
+普通 PR 合入 main
+  └─ release-please 开/更新 Release PR「chore(main): release x.y.z」
+       └─ 合并该 PR
+            ├─ 自动打 tag、建 GitHub Release、生成 CHANGELOG.md
+            └─ 自动发布到 npm（OIDC trusted publishing）
+```
+
+`package.json` 的 `version` 由 Release PR 更新，不要手动改。

package/dist/artifact/assets.d.ts

@@ -0,0 +1,17 @@
+import type { Logger } from '../support/log.ts';
+/** 把 `public/**` 逐个交给构建器登记监听。 */
+export declare function watchPublicFiles(publicDir: string, registerWatchFile: (file: string) => void, log: Logger): void;
+/**
+ * 把清单声明的元数据文件搬进产物目录；已由构建器搬过的（public/ 下）跳过。
+ *
+ * watch 下复制失败只报错继续（一次文件锁不该停掉开发服务器）；
+ * 生产构建必须失败——否则 package.zip 会缺清单声明的 readme/icon/preview。
+ */
+export declare function copyMetadata({ root, publicDir, outDir, manifestName, watch, log, }: {
+    root: string;
+    publicDir: string;
+    outDir: string;
+    manifestName: string;
+    watch: boolean;
+    log: Logger;
+}): void;

package/dist/artifact/assets.js

@@ -0,0 +1,92 @@
+/**
+ * 思源产物契约：让 `public/` 的改动也触发重建，并搬运清单声明的元数据文件。
+ *
+ * 主流构建器的 `publicDir` 都只在**启动时**复制进产物，之后不再监听它，
+ * 而思源的清单恰恰在 `public/` 里——改个 `theme.json` 的 frontends 或版本号，
+ * 不重启就永远不生效。所以要把 `public/**` 显式加进监听集合。
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { readJsonFile, walkFiles } from '../support/fs.js';
+import { isRecord } from '../support/guards.js';
+const README_PATTERN = /^README.*\.md$/;
+/** 把 `public/**` 逐个交给构建器登记监听。 */
+export function watchPublicFiles(publicDir, registerWatchFile, log) {
+    if (!publicDir || !existsSync(publicDir)) {
+        log(`publicDir 不存在，跳过监听：${publicDir}`, 'warn');
+        return;
+    }
+    for (const file of walkFiles(publicDir))
+        registerWatchFile(file.path);
+}
+/** 从清单的 readme / icon / preview 收集要搬的文件名。 */
+function declaredFiles(manifestPath, log) {
+    const parsed = readJsonFile(manifestPath);
+    if (!isRecord(parsed)) {
+        log(`读不到或无法解析清单 ${manifestPath}；元数据按 README*.md 兜底`, 'warn');
+        return null;
+    }
+    const files = new Set();
+    const readme = parsed['readme'];
+    if (typeof readme === 'string')
+        files.add(readme);
+    else if (isRecord(readme)) {
+        for (const value of Object.values(readme))
+            if (typeof value === 'string')
+                files.add(value);
+    }
+    for (const key of ['icon', 'preview']) {
+        const value = parsed[key];
+        if (typeof value === 'string')
+            files.add(value);
+    }
+    return files.size ? [...files] : null;
+}
+/**
+ * 把清单声明的元数据文件搬进产物目录；已由构建器搬过的（public/ 下）跳过。
+ *
+ * watch 下复制失败只报错继续（一次文件锁不该停掉开发服务器）；
+ * 生产构建必须失败——否则 package.zip 会缺清单声明的 readme/icon/preview。
+ */
+export function copyMetadata({ root, publicDir, outDir, manifestName, watch, log, }) {
+    const absoluteOutDir = resolve(root, outDir);
+    mkdirSync(absoluteOutDir, { recursive: true });
+    const candidates = [join(root, 'public', manifestName), join(root, manifestName)];
+    const manifestPath = candidates.find((file) => existsSync(file)) ?? candidates[0];
+    const declared = declaredFiles(manifestPath, log);
+    const names = [];
+    if (declared) {
+        names.push(...declared);
+    }
+    else {
+        log(`清单 ${manifestPath} 没声明 readme/icon/preview，按 README*.md 兜底搬运`, 'warn');
+        names.push(...readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && README_PATTERN.test(entry.name))
+            .map((entry) => entry.name));
+    }
+    const failures = [];
+    for (const name of names) {
+        const source = resolve(root, name);
+        if (!existsSync(source)) {
+            if (publicDir && existsSync(join(publicDir, name)))
+                continue;
+            failures.push(`${name}：项目根与 public/ 下都不存在`);
+            continue;
+        }
+        try {
+            const destination = join(absoluteOutDir, name);
+            mkdirSync(dirname(destination), { recursive: true });
+            copyFileSync(source, destination);
+        }
+        catch (cause) {
+            failures.push(`${name}：${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+    }
+    if (!failures.length)
+        return;
+    const detail = failures.join('；');
+    if (watch)
+        log(`资产复制失败 ${detail}`, 'error');
+    else
+        throw new Error(`资产复制失败：${detail}`);
+}

package/dist/artifact/manifest-schema.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+/** 主题清单：modes 决定思源的主题列表。 */
+export declare const themeManifestShape: z.ZodObject<{
+    name: z.ZodString;
+    author: z.ZodString;
+    url: z.ZodString;
+    version: z.ZodString;
+    displayName: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+    description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+    readme: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+    icon: z.ZodOptional<z.ZodString>;
+    preview: z.ZodOptional<z.ZodString>;
+    modes: z.ZodArray<z.ZodEnum<{
+        dark: "dark";
+        light: "light";
+    }>>;
+}, z.core.$strip>;
+/** 插件清单：minAppVersion 决定思源能否安装。 */
+export declare const pluginManifestShape: z.ZodObject<{
+    name: z.ZodString;
+    author: z.ZodString;
+    url: z.ZodString;
+    version: z.ZodString;
+    displayName: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+    description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+    readme: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+    icon: z.ZodOptional<z.ZodString>;
+    preview: z.ZodOptional<z.ZodString>;
+    minAppVersion: z.ZodString;
+}, z.core.$strip>;
+/** 一条 zod 问题转成一句中文（不含字段名前缀，调用方自己拼）。 */
+export declare function manifestIssueMessage(issue: z.core.$ZodIssue): {
+    message: string;
+    hint?: string;
+};

package/dist/artifact/manifest-schema.js

@@ -0,0 +1,81 @@
+/**
+ * 思源清单的 schema：唯一的形状来源。
+ *
+ * 为什么需要：思源的失败模式是**静默的**。`name: 123` 不会被思源报错，
+ * 只是主题不出现在列表里。旧实现只检查字段是否存在，类型错了照样通过。
+ *
+ * 清单允许额外的集市字段（icon / preview / readme 的 i18n 对象等），
+ * 所以这里**不** `.strict()`——未知字段是正常的。真正要拦的是已知字段的类型。
+ */
+import { parse } from 'semver';
+import { z } from 'zod';
+/**
+ * 只认 `x.y.z`（与思源集市一致）：排除前导零、`v` 前缀、prerelease、build。
+ *
+ * 不用正则：正则的 `\d+` 会接受 `01.2.3`，而 semver 规范里这是非法的；
+ * 也会接受超出安全整数范围的 `999999999999999999999.0.0`。
+ * `semver.parse()` 按规范收窄，再按三点确认：可解析、`parsed.version === value`
+ * （排除 `v1.2.3` 与带 build 的 `1.2.3+build`）、无 prerelease（排除 `1.2.3-beta`）。
+ */
+function isSemver(value) {
+    if (typeof value !== 'string')
+        return false;
+    const parsed = parse(value);
+    if (parsed === null)
+        return false;
+    if (parsed.version !== value)
+        return false;
+    return parsed.prerelease.length === 0;
+}
+const semverShape = z.string({ error: '必须是字符串' }).refine(isSemver, {
+    error: '必须是 主.次.修订 形式的 semver，如 1.2.3',
+});
+/** i18n 对象：思源按 default 回退，缺了会显示空白。 */
+const i18nFieldShape = z
+    .union([z.string(), z.record(z.string(), z.string(), { error: 'i18n 对象的值必须是字符串' })], {
+    error: '必须是字符串或 { default: string, ... } 的 i18n 对象',
+})
+    .refine((value) => typeof value === 'string' || 'default' in value, {
+    error: '是 i18n 对象但没有 default 项（思源按 default 回退，缺了会显示空白）',
+});
+/** 主题与插件共有的清单字段。 */
+const baseManifestShape = z.object({
+    name: z.string({ error: '必须是字符串' }).min(1, { error: '不能为空' }),
+    author: z.string({ error: '必须是字符串' }).min(1, { error: '不能为空' }),
+    url: z.string({ error: '必须是字符串' }).min(1, { error: '不能为空' }),
+    version: semverShape,
+    displayName: i18nFieldShape.optional(),
+    description: i18nFieldShape.optional(),
+    readme: i18nFieldShape.optional(),
+    icon: z.string({ error: '必须是字符串' }).optional(),
+    preview: z.string({ error: '必须是字符串' }).optional(),
+});
+/** 主题清单：modes 决定思源的主题列表。 */
+export const themeManifestShape = baseManifestShape.extend({
+    modes: z
+        .array(z.enum(['light', 'dark'], { error: '只接受 light / dark' }), { error: '必须是数组' })
+        .min(1, { error: '必须是非空数组，如 ["light", "dark"]' }),
+});
+/** 插件清单：minAppVersion 决定思源能否安装。 */
+export const pluginManifestShape = baseManifestShape.extend({
+    minAppVersion: semverShape,
+});
+/** 把 zod 的路径转成人能读的位置。 */
+function pathLabel(path) {
+    let label = '';
+    for (const segment of path) {
+        if (typeof segment === 'number')
+            label += `[${segment}]`;
+        else
+            label += label ? `.${String(segment)}` : String(segment);
+    }
+    return label;
+}
+/** 一条 zod 问题转成一句中文（不含字段名前缀，调用方自己拼）。 */
+export function manifestIssueMessage(issue) {
+    const label = pathLabel(issue.path) || '清单';
+    if (issue.code === 'invalid_type' && issue.expected === 'string') {
+        return { message: `${label} 必须是字符串` };
+    }
+    return { message: `${label} ${issue.message}` };
+}

package/dist/artifact/verify.d.ts

@@ -0,0 +1,16 @@
+import type { Kind } from '../siyuan/kinds.ts';
+export interface VerifyIssue {
+    message: string;
+    hint?: string;
+}
+export interface VerifyResult {
+    ok: boolean;
+    issues: VerifyIssue[];
+}
+/** 校验一个目标的清单与产物；返回问题列表，空表示通过。 */
+export declare function verifyTarget(kind: Kind, { root, outDir }: {
+    root: string;
+    outDir: string;
+}): VerifyResult;
+/** 把问题列表排成可读文本。 */
+export declare function formatIssues(issues: VerifyIssue[]): string;

package/dist/artifact/verify.js

@@ -0,0 +1,99 @@
+/**
+ * 产物与清单校验。
+ *
+ * 思源的失败模式是**静默的**：theme.json 缺 modes → 主题不出现在列表里；
+ * 版本号不一致 → 集市判为旧版；产物缺 index.js → 插件加载不到。
+ */
+import { existsSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { readJsonFile, readTextFile, walkFiles } from '../support/fs.js';
+import { isRecord } from '../support/guards.js';
+import { readManifest } from '../siyuan/manifest.js';
+import { kindSpec } from '../siyuan/kinds.js';
+import { manifestIssueMessage, pluginManifestShape, themeManifestShape } from './manifest-schema.js';
+/** 去掉 CSS 注释：watch 产物不压缩，注释里常写着「别写 rgb(var(--b3-*))」。 */
+function stripCssComments(css) {
+    return css.replace(/\/\*[\s\S]*?\*\//g, '');
+}
+/** 统计 `rgb(var(--b3-...))` 这类双重包装（整条声明会被浏览器静默丢弃）。 */
+function findDoubleWrappedColors(css) {
+    const problems = [];
+    const pattern = /\brgba?\(\s*var\(\s*(--b3-[\w-]+)\s*\)\)?/g;
+    for (const match of stripCssComments(css).matchAll(pattern)) {
+        if (match[1] !== undefined)
+            problems.push(`${match[1]} 被 rgb() 双重包装：${match[0]}`);
+    }
+    return problems;
+}
+/** 校验一个目标的清单与产物；返回问题列表，空表示通过。 */
+export function verifyTarget(kind, { root, outDir }) {
+    const spec = kindSpec(kind);
+    const issues = [];
+    // 只校验本次构建的产物目录。不做「产物目录不存在就改扫项目根」的兜底：
+    // 插件永远在真实构建之后校验，那种兜底只会把 node_modules 当成产物扫进来。
+    const absOutDir = isAbsolute(outDir) ? outDir : join(root, outDir);
+    const walked = walkFiles(absOutDir);
+    const files = walked.map((file) => file.name);
+    const byName = new Map(walked.map((file) => [file.name, file.path]));
+    const readOutput = (file) => {
+        const path = byName.get(file);
+        return path ? readTextFile(path) : null;
+    };
+    const manifest = readManifest(root, spec.manifestName, [absOutDir])?.data ?? null;
+    const packageJsonRaw = readJsonFile(join(root, 'package.json'));
+    const packageJson = isRecord(packageJsonRaw) ? packageJsonRaw : null;
+    // ---- 通用：清单存在与形状 ----
+    if (!manifest) {
+        issues.push({
+            message: `读不到清单：${spec.manifestName}（找过 public/、项目根与产物目录）`,
+            hint: '思源按清单识别主题/插件，缺了它不会出现在列表里。',
+        });
+    }
+    else {
+        // 形状交给 schema：字段缺失、类型错误、semver 格式、i18n 缺 default
+        // 都在这里一次报完。思源对这些错误都是静默的（`name: 123` 只是不出现）。
+        const shape = kind === 'theme' ? themeManifestShape : pluginManifestShape;
+        const parsed = shape.safeParse(manifest);
+        if (!parsed.success) {
+            for (const issue of parsed.error.issues)
+                issues.push(manifestIssueMessage(issue));
+        }
+        // 跨文件一致性：集市按清单版本判新旧，不一致会导致更新不推送。
+        if (packageJson && manifest['version'] && packageJson['version'] !== manifest['version']) {
+            issues.push({
+                message: `版本不一致：package.json=${String(packageJson['version'])}，清单=${String(manifest['version'])}`,
+                hint: '集市按清单版本判新旧，不一致会导致更新不推送。',
+            });
+        }
+    }
+    // ---- 通用：产物目录存在与必需文件 ----
+    if (!existsSync(absOutDir)) {
+        issues.push({ message: `产物目录不存在：${absOutDir}`, hint: '先跑一次构建。' });
+    }
+    else {
+        for (const expected of spec.expectedFiles) {
+            if (!files.includes(expected)) {
+                issues.push({ message: `产物缺少 ${expected}`, hint: '思源按固定文件名加载，缺了不会报错、只是加载不到。' });
+            }
+        }
+    }
+    // ---- 类型特有的产物检查（清单形状已由上面的 schema 覆盖） ----
+    if (existsSync(absOutDir) && kind === 'theme') {
+        const scripts = files.filter((file) => file.endsWith('.js'));
+        if (scripts.length) {
+            issues.push({ message: `主题产物里出现 JavaScript：${scripts.join('、')}`, hint: '主题只交付 CSS。检查 rollupOptions.input 与 lib 配置。' });
+        }
+        const css = readOutput('theme.css') ?? '';
+        if (stripCssComments(css).includes('@layer')) {
+            issues.push({ message: 'theme.css 含 @layer，会被未分层的 base.css 压制', hint: '移除 @layer 包装，让主题规则保持 unlayered。' });
+        }
+        for (const problem of findDoubleWrappedColors(css)) {
+            issues.push({ message: problem, hint: '--b3-* 已是完整色值，直接 var() 使用；rgb(var(--rc-*)) 才是正确写法。' });
+        }
+    }
+    return { ok: issues.length === 0, issues };
+}
+/** 把问题列表排成可读文本。 */
+export function formatIssues(issues) {
+    return issues.map((issue) => (issue.hint ? `  ${issue.message}\n    ${issue.hint}` : `  ${issue.message}`)).join('\n');
+}

package/dist/artifact/zip.d.ts

@@ -0,0 +1,6 @@
+/** 思源集市的发布产物名。 */
+export declare const PACKAGE_NAME = "package.zip";
+export declare function writeZip(dir: string, outFile: string): {
+    files: number;
+    bytes: number;
+};

package/dist/artifact/zip.js

@@ -0,0 +1,26 @@
+/**
+ * 打包：把一个目录写成 `package.zip`。
+ *
+ * 用 fflate 的 `zipSync`：纯 JS、同步 API，与「构建结束时同步写盘」的语义一致，
+ * 且与标准 zip 工具双向互通。
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { zipSync } from 'fflate';
+import { walkFiles } from '../support/fs.js';
+/** 思源集市的发布产物名。 */
+export const PACKAGE_NAME = 'package.zip';
+/** 经典 zip 的条目数上限（16 位字段）。 */
+const ZIP_MAX_ENTRIES = 0xffff;
+export function writeZip(dir, outFile) {
+    const files = walkFiles(dir);
+    if (files.length > ZIP_MAX_ENTRIES)
+        throw new Error(`文件数 ${files.length} 超过 zip 格式上限 ${ZIP_MAX_ENTRIES}`);
+    const entries = {};
+    for (const file of files)
+        entries[file.name] = new Uint8Array(readFileSync(file.path));
+    const archive = zipSync(entries, { level: 6 });
+    mkdirSync(dirname(outFile), { recursive: true });
+    writeFileSync(outFile, archive);
+    return { files: files.length, bytes: archive.length };
+}

package/dist/config.d.ts

@@ -0,0 +1,20 @@
+import type { UserConfig } from 'vite';
+import type { Kind } from './siyuan/kinds.ts';
+/** 生成构建片段所需的事实。 */
+export interface BuildSpecInput {
+    kind: Kind;
+    watch: boolean;
+    /** 入口文件绝对路径。必填：产物名是固定契约，入口不能靠猜。 */
+    entry: string;
+    /** 插件选项里显式给的产物目录。 */
+    outDir: string | null;
+}
+/** 生成插件契约配置（不含用户值）。 */
+export declare function buildSpecFor(input: BuildSpecInput): UserConfig;
+/**
+ * 把契约配置与用户配置合并，返回给 `config()` 钩子。
+ *
+ * 用户若已写了旧键名 `rollupOptions` 而当前 Vite 用新键名，先把 spec 里的那一块
+ * 换到旧键名下，再合并——避免出现两个键同时存在、优先级不确定的情况。
+ */
+export declare function applyBuildConfig(userConfig: UserConfig, input: BuildSpecInput): UserConfig;

package/dist/config.js

@@ -0,0 +1,92 @@
+/**
+ * 构建配置注入：把思源的加载机制翻译成 Vite 配置形状。
+ *
+ * `build.lib`、`rollupOptions`、`base` 是**思源加载机制决定的契约**，不是项目口味，
+ * 必须由插件设；但用户显式写的值优先。
+ *
+ * 用 Vite 公共 API `mergeConfig(spec, userConfig)`：**用户放后面**，深度合并后用户胜出。
+ * 直接返回 spec 会覆盖用户值（实测 `user-dist` 被改成 `dev`）；原地 mutate + 手写
+ * 一堆 `??=` 也不是 Vite 推荐写法。函数值 `assetFileNames` 实测能正确合并。
+ */
+import { mergeConfig, version as viteVersion } from 'vite';
+import { kindSpec } from './siyuan/kinds.js';
+const ASSET_DIR = 'assets';
+/** 资源名：CSS 固定名，其余按源目录归到 assets/ 下（避免不同目录的同名文件被去重）。 */
+function assetNamer(cssName) {
+    return (info) => {
+        const name = info.name ?? 'asset';
+        return name.endsWith('.css') ? cssName : `${ASSET_DIR}/${name}`;
+    };
+}
+/** Vite 8 把 build.rollupOptions 改名为 build.rolldownOptions（旧名仍可用）。 */
+function defaultOptionsKey() {
+    return Number.parseInt(viteVersion, 10) >= 8 ? 'rolldownOptions' : 'rollupOptions';
+}
+/** 用户已经写了哪个键就跟着用哪个，避免两个键同时出现；否则按版本选。 */
+function optionsKey(userConfig) {
+    const build = userConfig.build;
+    if (build && 'rollupOptions' in build)
+        return 'rollupOptions';
+    if (build && 'rolldownOptions' in build)
+        return 'rolldownOptions';
+    return defaultOptionsKey();
+}
+/** 生成插件契约配置（不含用户值）。 */
+export function buildSpecFor(input) {
+    const spec = kindSpec(input.kind);
+    const outDir = input.outDir ?? (input.watch ? './dev' : './dist');
+    const options = { input: input.entry };
+    if (input.kind === 'plugin') {
+        options.external = ['siyuan', 'process'];
+        options.output = {
+            entryFileNames: '[name].js',
+            assetFileNames: assetNamer(spec.cssName),
+        };
+    }
+    else {
+        // theme 不能走 lib：lib 隐含 cssCodeSplit:false，与 CSS 入口冲突、Vite 直接报错。
+        options.output = { assetFileNames: assetNamer(spec.cssName) };
+    }
+    const build = {
+        outDir,
+        emptyOutDir: false,
+        // watch 不压缩（便于直接看落盘产物），生产用默认压缩器。
+        minify: !input.watch,
+    };
+    if (input.kind === 'plugin') {
+        // 插件入口是 `export default class ...`，必须走 lib：lib cjs 产出
+        // `module.exports = 类`；普通 input 只得到 `exports.default`，思源报
+        // "plugin xxx has no export"。
+        build.lib = { entry: input.entry, fileName: 'index', cssFileName: 'index', formats: ['cjs'] };
+    }
+    build[defaultOptionsKey()] = options;
+    return {
+        // 思源从 /appearance/themes/<name>/ 提供主题；Vite 默认 base:'/' 会产出
+        // 根绝对 URL，字体/图片在宿主下 404。
+        base: './',
+        build,
+        // 插件 JS 在思源前端 eval 执行，而前端没有 process 对象；React 等依赖会读
+        // process.env.NODE_ENV。
+        define: { 'process.env.NODE_ENV': JSON.stringify(input.watch ? 'development' : 'production') },
+    };
+}
+/**
+ * 把契约配置与用户配置合并，返回给 `config()` 钩子。
+ *
+ * 用户若已写了旧键名 `rollupOptions` 而当前 Vite 用新键名，先把 spec 里的那一块
+ * 换到旧键名下，再合并——避免出现两个键同时存在、优先级不确定的情况。
+ */
+export function applyBuildConfig(userConfig, input) {
+    const spec = buildSpecFor(input);
+    const key = optionsKey(userConfig);
+    const specBuild = spec.build;
+    if (specBuild && key in specBuild === false) {
+        const other = key === 'rollupOptions' ? 'rolldownOptions' : 'rollupOptions';
+        const value = specBuild[other];
+        if (value !== undefined) {
+            specBuild[key] = value;
+            delete specBuild[other];
+        }
+    }
+    return mergeConfig(spec, userConfig);
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { Plugin } from 'vite';
+import type { Kind } from './siyuan/kinds.ts';
+export interface SiYuanOptions {
+    /**
+     * 构建入口，相对项目根。必填：主题要产出固定名 `theme.css`、插件要产出
+     * CJS 单文件 `index.js`，产物名是思源加载机制决定的契约，入口不能靠猜——
+     * 猜错不会报错，只会静默产出思源加载不到的东西。
+     */
+    entry: string;
+    /** 被测类型（theme / plugin）；缺省从清单推断。 */
+    kind?: Kind | null;
+    /** 产物目录；缺省 `./dev`（watch）/ `./dist`（生产）。 */
+    outDir?: string | null;
+}
+export default function siyuan(options: SiYuanOptions): Plugin;