vite-plugin-siyuan 0.1.0 → 0.3.0

package/README.md

@@ -18,7 +18,7 @@ import { defineConfig } from 'vite';
 import siyuan from 'vite-plugin-siyuan';
 
 export default defineConfig({
-  plugins: [siyuan()],
+  plugins: [siyuan({ entry: 'src/main.css' })],
 });
 ```
 
@@ -28,13 +28,52 @@ pnpm vite build --watch
 
 `vite dev` 不适用：思源从磁盘读产物，而 dev server 只在内存里编译。插件的 `apply` 固定为 `'build'`。
 
+## 项目结构
+
+**除了 `README.md`，其余文件都放 `public/`。**
+
+```
+你的项目/
+├── README.md             ← 唯一放项目根的（GitHub 只展示仓库根的 README）
+├── public/
+│   ├── theme.json        ← 主题；插件则是 plugin.json
+│   ├── icon.png
+│   ├── preview.png
+│   └── i18n/
+├── src/
+│   └── main.css          ← entry 指向这里
+└── vite.config.ts
+```
+
+思源按固定路径从**产物根**加载清单和资源，而 `public/` 是 Vite 唯一「原样复制到产物根」的机制。放这里，dev 和 build 都自动生效，改清单也会触发重建。
+
+`README.md` 是唯一例外：GitHub 只认仓库根的 README，思源集市要求它在产物根。插件会把它从项目根复制进产物（清单的 `readme` 字段可指定文件名，缺省按 `README*.md` 兜底）；如果你放 `public/README.md`，则以 `public/` 为准。
+
+清单里声明的 `icon` / `preview` 若没出现在产物里，构建会**报错**——这类缺失思源不会报错，只会导致集市缺图。
+
+### 关于 publicDir
+
+默认就是 `public/`。如果改成别的目录（`publicDir: 'static'`），插件会跟着找，无需额外配置。
+
+**不要设成 `false`**：思源要求清单出现在产物根，而没有 `publicDir` 就没有任何机制能把清单复制进去。插件会在 `config` 阶段直接报错。
+
+### 不支持根目录布局
+
+官方 [theme-sample](https://github.com/siyuan-note/theme-sample) 和 [plugin-sample](https://github.com/siyuan-note/plugin-sample) 把清单放项目根，但它们是**无构建步骤或 webpack 项目**，不是 Vite 项目。放到项目根会直接报错：
+
+```
+在 {publicDir} 下找不到 theme.json / plugin.json；请把清单放进该目录，或用 kind 选项显式指定类型
+```
+
 ## 选项
 
 | 选项 | 说明 |
 |---|---|
-| `kind` | `'theme'` / `'plugin'`；缺省时在 `public/`、`dist/`、项目根依次查找 `theme.json` / `plugin.json` 推断 |
+| `entry` | **必填**。构建入口，相对项目根。主题指向 CSS，插件指向 TS/JS |
+| `kind` | `'theme'` / `'plugin'`；缺省时按 `publicDir` 下的清单推断 |
 | `outDir` | 产物目录；缺省 `./dev`（watch）/ `./dist`（生产） |
-| `entry` | 构建入口，相对项目根；缺省保留项目自己的 `input` / `lib` |
+
+`entry` 必填是因为产物名是固定契约（主题 `theme.css`、插件 `index.js`）。入口猜错不会报错，只会静默产出思源加载不到的东西。
 
 ## 做什么
 
@@ -42,8 +81,8 @@ pnpm vite build --watch
 
 ### watch（`vite build --watch`）
 
-1. **注入构建配置**：主题产出 `theme.css`；插件在给了 `entry` 时走 `lib` CJS 单文件产出 `index.js`。`base: './'` 保证宿主下资源不 404。用 `mergeConfig` 合并，**用户已写的值优先**。
-2. **链接产物**：把 `dev/` 链接到 `<workspace>/data/themes|plugins/<name>`。插件目录必须是真 symlink（思源 Go 运行时按 `ModeSymlink` 判定），主题可用 junction 兜底。
+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`，思源整页刷新。
 
@@ -74,13 +113,13 @@ watch 模式首次就绪后还会打印桌面端 / 移动端两个稳定预览
 | 变量 | 说明 |
 |---|---|
 | `SIYUAN_PORT` | kernel 端口；缺省用 kernel 进程 PID 匹配 `port.json`，再探测记录端口与 6806–6809 |
-| `SIYUAN_THEME_DIR` | 主题安装父目录（`<workspace>/data/themes`），实际装到 `<它>/<name>` |
-| `SIYUAN_PLUGIN_DIR` | 插件安装父目录（`<workspace>/data/plugins`），同上 |
+| `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` 仍然兼容。
+旧名 `SYD_NO_ELEVATION` / `SYD_DEBUG` 仍然兼容。
 
 ## 配套 CLI
 
@@ -91,10 +130,9 @@ watch 模式首次就绪后还会打印桌面端 / 移动端两个稳定预览
 ### 提 PR
 
 1. 先开 issue 对齐需求，避免白做。
-2. PR 标题必须符合 [Conventional Commits](https://www.conventionalcommits.org/)——CI 会检查：
-   - `feat: ...` → 次版本（0.2.0）
-   - `fix: ...` → 补丁版本（0.1.1）
-   - `feat!: ...` → 1.0 之前只升次版本
+2. PR 标题必须符合 [Conventional Commits](https://www.conventionalcommits.org/)，CI 会检查：
+   - `feat:` → 次版本，`fix:` → 补丁版本
+   - `feat!:` → 1.0 之前只升次版本
    - `docs:` / `chore:` / `ci:` / `test:` / `refactor:` → 不发版
 3. 合并方式固定为 **Squash and merge**，PR 标题会成为最终 commit。
 
@@ -107,7 +145,8 @@ watch 模式首次就绪后还会打印桌面端 / 移动端两个稳定预览
   └─ release-please 开/更新 Release PR「chore(main): release x.y.z」
        └─ 合并该 PR
             ├─ 自动打 tag、建 GitHub Release、生成 CHANGELOG.md
-            └─ 自动发布到 npm（OIDC trusted publishing）
+            └─ 自动 stage 到 npm（OIDC trusted publishing）
+                 └─ 你在 npmjs.com 用安全密钥批准后上线
 ```
 
 `package.json` 的 `version` 由 Release PR 更新，不要手动改。

package/dist/artifact/assets.d.ts

@@ -1,13 +1,18 @@
 import type { Logger } from '../support/log.ts';
-/** 把 `public/**` 逐个交给构建器登记监听。 */
+/** 把 publicDir 下的文件逐个交给构建器登记监听。 */
 export declare function watchPublicFiles(publicDir: string, registerWatchFile: (file: string) => void, log: Logger): void;
 /**
- * 把清单声明的元数据文件搬进产物目录；已由构建器搬过的（public/ 下）跳过。
+ * 把 README 从项目根搬进产物目录（GitHub 只认根目录，思源要求产物根）。
+ *
+ * 清单声明的 README 优先；没声明时按 `README*.md` 兜底。
+ *
+ * **publicDir 优先**：若同名文件已经在 publicDir 下，Vite 已经把它复制进产物，
+ * 这里直接跳过——否则项目根那份会静默覆盖用户放在 publicDir 的版本。
  *
  * watch 下复制失败只报错继续（一次文件锁不该停掉开发服务器）；
- * 生产构建必须失败——否则 package.zip 会缺清单声明的 readme/icon/preview。
+ * 生产构建必须失败——否则 package.zip 会缺 README。
  */
-export declare function copyMetadata({ root, publicDir, outDir, manifestName, watch, log, }: {
+export declare function copyReadmes({ root, publicDir, outDir, manifestName, watch, log, }: {
     root: string;
     publicDir: string;
     outDir: string;

package/dist/artifact/assets.js

@@ -1,16 +1,27 @@
 /**
- * 思源产物契约：让 `public/` 的改动也触发重建，并搬运清单声明的元数据文件。
+ * 思源产物契约：让 `public/` 的改动也触发重建，并搬运唯一必须放项目根的文件。
+ *
+ * ## 文件放哪
+ *
+ * **只有 README 必须放项目根**：GitHub 只展示仓库根的 README，而思源集市要求
+ * 它出现在产物根。这一份由本模块搬进产物。
+ *
+ * 其他一切（`theme.json` / `plugin.json` / `icon` / `preview` / `i18n/` / 图片字体
+ * 等静态资源）都放 `public/`，由 Vite 的 `publicDir` 原样复制到产物根，本模块不介入。
+ *
+ * ## 为什么要监听 public/
  *
  * 主流构建器的 `publicDir` 都只在**启动时**复制进产物，之后不再监听它，
- * 而思源的清单恰恰在 `public/` 里——改个 `theme.json` 的 frontends 或版本号，
+ * 而思源的清单恰恰在 `public/` 里——改个 `theme.json` 的 modes 或版本号，
  * 不重启就永远不生效。所以要把 `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';
+import { declaredAssets } from '../siyuan/manifest.js';
 const README_PATTERN = /^README.*\.md$/;
-/** 把 `public/**` 逐个交给构建器登记监听。 */
+/** 把 publicDir 下的文件逐个交给构建器登记监听。 */
 export function watchPublicFiles(publicDir, registerWatchFile, log) {
     if (!publicDir || !existsSync(publicDir)) {
         log(`publicDir 不存在，跳过监听：${publicDir}`, 'warn');
@@ -19,58 +30,43 @@ export function watchPublicFiles(publicDir, registerWatchFile, log) {
     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/ 下）跳过。
+ * 把 README 从项目根搬进产物目录（GitHub 只认根目录，思源要求产物根）。
+ *
+ * 清单声明的 README 优先；没声明时按 `README*.md` 兜底。
+ *
+ * **publicDir 优先**：若同名文件已经在 publicDir 下，Vite 已经把它复制进产物，
+ * 这里直接跳过——否则项目根那份会静默覆盖用户放在 publicDir 的版本。
  *
  * watch 下复制失败只报错继续（一次文件锁不该停掉开发服务器）；
- * 生产构建必须失败——否则 package.zip 会缺清单声明的 readme/icon/preview。
+ * 生产构建必须失败——否则 package.zip 会缺 README。
  */
-export function copyMetadata({ root, publicDir, outDir, manifestName, watch, log, }) {
+export function copyReadmes({ 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 manifestPath = publicDir ? join(publicDir, manifestName) : join(root, 'public', manifestName);
+    const parsed = readJsonFile(manifestPath);
+    const declared = isRecord(parsed) ? declaredAssets(parsed, ['readme']) : null;
+    if (!isRecord(parsed))
+        log(`读不到或无法解析清单 ${manifestPath}；README 按 README*.md 兜底`, 'warn');
     const names = [];
-    if (declared) {
+    if (declared?.length) {
         names.push(...declared);
     }
     else {
-        log(`清单 ${manifestPath} 没声明 readme/icon/preview，按 README*.md 兜底搬运`, 'warn');
+        log(`清单 ${manifestPath} 没声明 readme，按 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) {
+        // publicDir 优先：Vite 已复制过，不再覆盖。
+        if (publicDir && existsSync(join(publicDir, name)))
+            continue;
         const source = resolve(root, name);
         if (!existsSync(source)) {
-            if (publicDir && existsSync(join(publicDir, name)))
-                continue;
-            failures.push(`${name}：项目根与 public/ 下都不存在`);
+            failures.push(`${name}：项目根与 public 目录下都不存在`);
             continue;
         }
         try {
@@ -86,7 +82,7 @@ export function copyMetadata({ root, publicDir, outDir, manifestName, watch, log
         return;
     const detail = failures.join('；');
     if (watch)
-        log(`资产复制失败 ${detail}`, 'error');
+        log(`README 复制失败 ${detail}`, 'error');
     else
-        throw new Error(`资产复制失败：${detail}`);
+        throw new Error(`README 复制失败：${detail}`);
 }

package/dist/artifact/verify.d.ts

@@ -8,8 +8,9 @@ export interface VerifyResult {
     issues: VerifyIssue[];
 }
 /** 校验一个目标的清单与产物；返回问题列表，空表示通过。 */
-export declare function verifyTarget(kind: Kind, { root, outDir }: {
+export declare function verifyTarget(kind: Kind, { root, publicDir, outDir }: {
     root: string;
+    publicDir: string;
     outDir: string;
 }): VerifyResult;
 /** 把问题列表排成可读文本。 */

package/dist/artifact/verify.js

@@ -8,7 +8,7 @@ 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 { declaredAssets, readManifest } from '../siyuan/manifest.js';
 import { kindSpec } from '../siyuan/kinds.js';
 import { manifestIssueMessage, pluginManifestShape, themeManifestShape } from './manifest-schema.js';
 /** 去掉 CSS 注释：watch 产物不压缩，注释里常写着「别写 rgb(var(--b3-*))」。 */
@@ -26,13 +26,12 @@ function findDoubleWrappedColors(css) {
     return problems;
 }
 /** 校验一个目标的清单与产物；返回问题列表，空表示通过。 */
-export function verifyTarget(kind, { root, outDir }) {
+export function verifyTarget(kind, { root, publicDir, outDir }) {
     const spec = kindSpec(kind);
     const issues = [];
-    const declaredOutDir = isAbsolute(outDir) ? outDir : join(root, outDir);
     // 只校验本次构建的产物目录。不做「产物目录不存在就改扫项目根」的兜底：
     // 插件永远在真实构建之后校验，那种兜底只会把 node_modules 当成产物扫进来。
-    const absOutDir = declaredOutDir;
+    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]));
@@ -40,13 +39,13 @@ export function verifyTarget(kind, { root, outDir }) {
         const path = byName.get(file);
         return path ? readTextFile(path) : null;
     };
-    const manifest = readManifest(root, spec.manifestName, [absOutDir])?.data ?? null;
+    const manifest = readManifest(publicDir, 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/、dist/、项目根）`,
+            message: `读不到清单：${spec.manifestName}（应在 public 目录下，或已在产物目录里）`,
             hint: '思源按清单识别主题/插件，缺了它不会出现在列表里。',
         });
     }
@@ -78,6 +77,22 @@ export function verifyTarget(kind, { root, outDir }) {
             }
         }
     }
+    // ---- 清单声明的资源必须真的在产物里 ----
+    // icon / preview / readme 由清单引用，思源集市按这些名字去找。它们只能通过
+    // public/ 进产物（README 额外支持项目根），放错位置不会报错、只是集市缺图。
+    if (manifest && existsSync(absOutDir)) {
+        for (const name of declaredAssets(manifest)) {
+            if (files.includes(name))
+                continue;
+            const inPublic = publicDir !== '' && existsSync(join(publicDir, name));
+            issues.push({
+                message: `清单声明的 ${name} 不在产物里`,
+                hint: inPublic
+                    ? `它在 public 目录下，但没被复制进 ${absOutDir}；确认 publicDir 配置。`
+                    : `把 ${name} 放进 public 目录，它会随构建复制到产物根。`,
+            });
+        }
+    }
     // ---- 类型特有的产物检查（清单形状已由上面的 schema 覆盖） ----
     if (existsSync(absOutDir) && kind === 'theme') {
         const scripts = files.filter((file) => file.endsWith('.js'));

package/dist/config.d.ts

@@ -4,8 +4,8 @@ import type { Kind } from './siyuan/kinds.ts';
 export interface BuildSpecInput {
     kind: Kind;
     watch: boolean;
-    /** 入口文件绝对路径；不给则保留项目自己的 input/lib。 */
-    entry: string | null;
+    /** 入口文件绝对路径。必填：产物名是固定契约，入口不能靠猜。 */
+    entry: string;
     /** 插件选项里显式给的产物目录。 */
     outDir: string | null;
 }

package/dist/config.js

@@ -35,9 +35,7 @@ function optionsKey(userConfig) {
 export function buildSpecFor(input) {
     const spec = kindSpec(input.kind);
     const outDir = input.outDir ?? (input.watch ? './dev' : './dist');
-    const options = {};
-    if (input.entry)
-        options.input = input.entry;
+    const options = { input: input.entry };
     if (input.kind === 'plugin') {
         options.external = ['siyuan', 'process'];
         options.output = {
@@ -55,7 +53,7 @@ export function buildSpecFor(input) {
         // watch 不压缩（便于直接看落盘产物），生产用默认压缩器。
         minify: !input.watch,
     };
-    if (input.entry && input.kind === 'plugin') {
+    if (input.kind === 'plugin') {
         // 插件入口是 `export default class ...`，必须走 lib：lib cjs 产出
         // `module.exports = 类`；普通 input 只得到 `exports.default`，思源报
         // "plugin xxx has no export"。

package/dist/index.d.ts

@@ -1,11 +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;
-    /** 构建入口，相对项目根；缺省保留项目自己写的 input/lib。 */
-    entry?: string | null;
 }
-export default function siyuan(options?: SiYuanOptions): Plugin;
+export default function siyuan(options: SiYuanOptions): Plugin;

package/dist/index.js

@@ -16,14 +16,16 @@
  *   closeBundle    校验 + 打包 + 汇报 + 构建完成日志
  *   closeWatcher   释放定时器
  */
+import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { applyBuildConfig } from './config.js';
 import { detectKind } from './siyuan/kinds.js';
+import { resolvePublicDir } from './siyuan/manifest.js';
 import { createTaggedLogger } from './output/log.js';
 import { createBuildSession } from './session.js';
 import { describeError, UserError } from './support/errors.js';
 const NAME = 'vite-plugin-siyuan';
-export default function siyuan(options = {}) {
+export default function siyuan(options) {
     const log = createTaggedLogger(NAME);
     let session = null;
     let kind = options.kind ?? null;
@@ -32,16 +34,17 @@ export default function siyuan(options = {}) {
         apply: 'build',
         config(userConfig) {
             const root = typeof userConfig.root === 'string' ? resolve(userConfig.root) : process.cwd();
-            try {
-                kind ??= detectKind(root);
-            }
-            catch (cause) {
-                // 没有清单就不知道产物该叫什么；交给项目自己配，不在这里报错。
-                log(`跳过构建配置注入：${describeError(cause)}`, 'warn');
-                return undefined;
+            const entry = resolve(root, options.entry);
+            if (!existsSync(entry)) {
+                throw new UserError(`entry 指向的文件不存在：${entry}（选项值：${options.entry}）`);
             }
+            // entry 必填意味着用户确实在建思源产物，所以识别不到类型是真错误，
+            // 不能像以前那样 warn 后跳过——那会让构建继续跑，最后崩在 Vite 的
+            // "Cannot resolve entry module index.html" 上，完全指错方向。
+            // publicDir 在这里还没解析（configResolved 才给），先按用户配置算一遍。
+            const publicDir = resolvePublicDir(root, userConfig.publicDir);
+            kind ??= detectKind(publicDir);
             const watch = Boolean(userConfig.build?.watch);
-            const entry = options.entry ? resolve(root, options.entry) : null;
             return applyBuildConfig(userConfig, { kind, watch, entry, outDir: options.outDir ?? null });
         },
         configResolved(resolvedConfig) {
@@ -49,7 +52,6 @@ export default function siyuan(options = {}) {
             const outDir = resolvedConfig.build.outDir;
             const publicDir = resolvedConfig.publicDir;
             const watch = resolvedConfig.command === 'build' && Boolean(resolvedConfig.build.watch);
-            kind ??= options.kind ?? null;
             if (!kind) {
                 log('识别不到被测类型，跳过链接与校验', 'warn');
                 return;

package/dist/session.js

@@ -5,7 +5,7 @@
  */
 import { relative, resolve } from 'node:path';
 import { activate, reloadUI } from './siyuan/activate.js';
-import { copyMetadata, watchPublicFiles } from './artifact/assets.js';
+import { copyReadmes, watchPublicFiles } from './artifact/assets.js';
 import { checkLinkedFiles, ensureLink } from './siyuan/link.js';
 import { kindSpec, readName } from './siyuan/kinds.js';
 import { findKernelPort } from './siyuan/port.js';
@@ -38,7 +38,7 @@ export function createBuildSession(facts, options) {
     /** 建会话：找端口 → 解析安装目录 → 链接 → 激活。失败抛可读错误。 */
     async function start() {
         const current = facts;
-        const name = readName(current.root, kind);
+        const name = readName(current.publicDir, kind);
         const port = await findKernelPort();
         const installPath = await resolveInstallDir({
             kind,
@@ -113,7 +113,7 @@ export function createBuildSession(facts, options) {
         async onWritten(files) {
             const current = facts;
             // 元数据搬运先做：校验时文件必须已经就位。
-            copyMetadata({
+            copyReadmes({
                 root: current.root,
                 publicDir: current.publicDir,
                 outDir: relative(current.root, current.outDir) || '.',
@@ -146,7 +146,11 @@ export function createBuildSession(facts, options) {
         onFinished() {
             const current = facts;
             buildCount += 1;
-            const result = verifyTarget(kind, { root: current.root, outDir: current.outDir });
+            const result = verifyTarget(kind, {
+                root: current.root,
+                publicDir: current.publicDir,
+                outDir: current.outDir,
+            });
             if (!result.ok) {
                 const text = formatIssues(result.issues);
                 if (current.watch) {

package/dist/siyuan/kinds.d.ts

@@ -17,9 +17,9 @@ export interface KindSpec {
 }
 export declare function kindSpec(kind: Kind): KindSpec;
 /**
- * 从项目目录推断类型：看 public/、dist/ 或项目根存在哪份清单。
+ * 从项目目录推断类型：看 publicDir 下存在哪份清单。
  * 同时存在多种时必须让人指定——装错类型的产物名会静默加载不到。
  */
-export declare function detectKind(root: string): Kind;
+export declare function detectKind(publicDir: string): Kind;
 /** 读被测对象的名字；读不到抛可读错误，不猜默认值。 */
-export declare function readName(root: string, kind: Kind): string;
+export declare function readName(publicDir: string, kind: Kind): string;

package/dist/siyuan/kinds.js

@@ -33,21 +33,28 @@ export function kindSpec(kind) {
 }
 const KIND_NAMES = ['theme', 'plugin'];
 /**
- * 从项目目录推断类型：看 public/、dist/ 或项目根存在哪份清单。
+ * 从项目目录推断类型：看 publicDir 下存在哪份清单。
  * 同时存在多种时必须让人指定——装错类型的产物名会静默加载不到。
  */
-export function detectKind(root) {
-    const matches = KIND_NAMES.filter((kind) => manifestCandidates(root, SPECS[kind].manifestName).some((file) => existsSync(file)));
+export function detectKind(publicDir) {
+    // publicDir 关掉时清单无处安放：思源要求清单在产物根，而没有 publicDir 就没有
+    // 「原样复制到产物根」的机制。这里直接说清楚，不要让用户去猜「产物缺少」。
+    if (!publicDir) {
+        throw new UserError('publicDir 已关闭，清单（theme.json / plugin.json）无处安放。\n' +
+            '  思源要求清单出现在产物根，而 publicDir 是 Vite 唯一能原样复制到产物根的机制。\n' +
+            '  请移除 publicDir: false，或改成指向存放清单的目录。');
+    }
+    const matches = KIND_NAMES.filter((kind) => manifestCandidates(publicDir, SPECS[kind].manifestName).some((file) => existsSync(file)));
     const [only] = matches;
     if (matches.length === 1 && only !== undefined)
         return only;
     throw new UserError(matches.length === 0
-        ? `在 ${root} 的 public/、dist/ 或项目根下找不到 theme.json / plugin.json；请用 kind 选项显式指定类型`
+        ? `在 ${publicDir} 下找不到 theme.json / plugin.json；请把清单放进该目录，或用 kind 选项显式指定类型`
         : `同时匹配到多种类型：${matches.join('、')}；请用 kind 选项显式指定`);
 }
 /** 读被测对象的名字；读不到抛可读错误，不猜默认值。 */
-export function readName(root, kind) {
-    for (const file of manifestCandidates(root, SPECS[kind].manifestName)) {
+export function readName(publicDir, kind) {
+    for (const file of manifestCandidates(publicDir, SPECS[kind].manifestName)) {
         const data = readJsonFile(file);
         if (isRecord(data)) {
             const name = data['name'];

package/dist/siyuan/manifest.d.ts

@@ -3,7 +3,21 @@ export interface ManifestFile {
     path: string;
     data: Record<string, unknown>;
 }
-/** 清单候选路径，按优先级排列。 */
-export declare function manifestCandidates(root: string, manifest: string, extraDirs?: readonly string[]): string[];
+/**
+ * 解析实际生效的 publicDir 绝对路径；`publicDir: false` 时返回空串。
+ *
+ * Vite 的 `publicDir` 可以指向任意目录（默认 `public`），也可以关掉。
+ * 所有找清单/资源的地方都必须走这里，不能拼死 `'public'`。
+ */
+export declare function resolvePublicDir(root: string, configured: string | false | undefined): string;
+/** 清单候选路径，按优先级排列。publicDir 关闭时只剩显式传入的目录。 */
+export declare function manifestCandidates(publicDir: string, manifest: string, extraDirs?: readonly string[]): string[];
 /** 读一份清单与其路径；都读不到返回 null。 */
-export declare function readManifest(root: string, manifest: string, extraDirs?: readonly string[]): ManifestFile | null;
+export declare function readManifest(publicDir: string, manifest: string, extraDirs?: readonly string[]): ManifestFile | null;
+/**
+ * 从清单里收集引用到的文件名。
+ *
+ * `readme` 可能是字符串，也可能是 `{ default, zh_CN, ... }` 的 i18n 对象；
+ * `icon` / `preview` 只能是字符串。`keys` 用于只取其中一部分（比如只搬 README）。
+ */
+export declare function declaredAssets(manifest: Record<string, unknown>, keys?: readonly string[]): string[];

package/dist/siyuan/manifest.js

@@ -1,23 +1,69 @@
 /**
- * 清单文件的读取。
+ * 清单文件的读取与 publicDir 解析。
  *
- * 清单可能出现在三处：`public/`（源码）、`dist/`（构建产物）、项目根
- * （解包后的 `package.zip` 就是这种布局）。
+ * 清单**只从 publicDir 读**：它是思源要求的产物根文件，而 `publicDir` 是 Vite
+ * 唯一「原样复制到产物根」的机制。项目根那份官方 sample 布局不做支持——
+ * 探测到它却复制不进产物，只会得到「产物缺少 theme.json」这种半截行为。
+ *
+ * 构建产物里的清单由调用方通过 `extraDirs` 显式传入（校验时用），
+ * 不作为默认候选——否则上一次构建留下的旧清单会盖住源码里的新清单。
  */
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { readJsonFile } from '../support/fs.js';
 import { isRecord } from '../support/guards.js';
-/** 清单候选路径，按优先级排列。 */
-export function manifestCandidates(root, manifest, extraDirs = []) {
-    const dirs = [join(root, 'public'), join(root, 'dist'), root, ...extraDirs];
+/**
+ * 解析实际生效的 publicDir 绝对路径；`publicDir: false` 时返回空串。
+ *
+ * Vite 的 `publicDir` 可以指向任意目录（默认 `public`），也可以关掉。
+ * 所有找清单/资源的地方都必须走这里，不能拼死 `'public'`。
+ */
+export function resolvePublicDir(root, configured) {
+    if (configured === false)
+        return '';
+    if (typeof configured === 'string' && configured)
+        return resolve(root, configured);
+    return join(root, 'public');
+}
+/** 清单候选路径，按优先级排列。publicDir 关闭时只剩显式传入的目录。 */
+export function manifestCandidates(publicDir, manifest, extraDirs = []) {
+    const dirs = [...(publicDir ? [publicDir] : []), ...extraDirs];
     return dirs.map((dir) => join(dir, manifest));
 }
 /** 读一份清单与其路径；都读不到返回 null。 */
-export function readManifest(root, manifest, extraDirs = []) {
-    for (const path of manifestCandidates(root, manifest, extraDirs)) {
+export function readManifest(publicDir, manifest, extraDirs = []) {
+    for (const path of manifestCandidates(publicDir, manifest, extraDirs)) {
         const data = readJsonFile(path);
         if (isRecord(data))
             return { path, data };
     }
     return null;
 }
+/** 清单里引用外部文件名的字段名。 */
+const ASSET_KEYS = ['readme', 'icon', 'preview'];
+/**
+ * 从清单里收集引用到的文件名。
+ *
+ * `readme` 可能是字符串，也可能是 `{ default, zh_CN, ... }` 的 i18n 对象；
+ * `icon` / `preview` 只能是字符串。`keys` 用于只取其中一部分（比如只搬 README）。
+ */
+export function declaredAssets(manifest, keys = ASSET_KEYS) {
+    const names = new Set();
+    if (keys.includes('readme')) {
+        const readme = manifest['readme'];
+        if (typeof readme === 'string')
+            names.add(readme);
+        else if (isRecord(readme)) {
+            for (const value of Object.values(readme))
+                if (typeof value === 'string')
+                    names.add(value);
+        }
+    }
+    for (const key of keys) {
+        if (key === 'readme')
+            continue;
+        const value = manifest[key];
+        if (typeof value === 'string')
+            names.add(value);
+    }
+    return [...names];
+}

package/package.json

@@ -1,60 +1,60 @@
-{
-  "name": "vite-plugin-siyuan",
-  "version": "0.1.0",
-  "description": "Vite plugin for SiYuan theme/plugin development: config injection, link to workspace, hot reload, verify and package",
-  "keywords": [
-    "siyuan",
-    "siyuan-theme",
-    "siyuan-plugin",
-    "vite-plugin",
-    "hot-reload"
-  ],
-  "type": "module",
-  "license": "MIT",
-  "engines": {
-    "node": ">=22.18.0"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "clean": "node --input-type=module -e \"import fs from 'node:fs'; fs.rmSync('dist',{recursive:true,force:true})\"",
-    "build": "pnpm run clean && tsc -p tsconfig.build.json",
-    "type-check": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "check": "pnpm run type-check && pnpm run test"
-  },
-  "dependencies": {
-    "consola": "^3.4.2",
-    "fflate": "^0.8.3",
-    "ps-list": "^9.0.0",
-    "semver": "^7.8.6",
-    "zod": "^4.6.7"
-  },
-  "peerDependencies": {
-    "vite": ">=6"
-  },
-  "devDependencies": {
-    "@types/node": "^26.6.6",
-    "@types/semver": "^7.8.0",
-    "typescript": "^7.0.2",
-    "vite": "^8.3.5",
-    "vitest": "^5.0.5"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/svchord/vite-plugin-siyuan.git"
-  },
-  "author": "svchord",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
-}
+{
+  "name": "vite-plugin-siyuan",
+  "version": "0.3.0",
+  "description": "Vite plugin for SiYuan theme/plugin development: config injection, link to workspace, hot reload, verify and package",
+  "keywords": [
+    "siyuan",
+    "siyuan-theme",
+    "siyuan-plugin",
+    "vite-plugin",
+    "hot-reload"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "consola": "^3.4.2",
+    "fflate": "^0.8.3",
+    "ps-list": "^9.0.0",
+    "semver": "^7.8.6",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "vite": ">=6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/semver": "^7.8.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/svchord/vite-plugin-siyuan.git"
+  },
+  "author": "svchord",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "clean": "node --input-type=module -e \"import fs from 'node:fs'; fs.rmSync('dist',{recursive:true,force:true})\"",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "check": "pnpm run type-check && pnpm run test"
+  }
+}