vite-plugin-siyuan 0.2.0 → 0.3.1

package/README.md

@@ -18,7 +18,6 @@ import { defineConfig } from 'vite';
 import siyuan from 'vite-plugin-siyuan';
 
 export default defineConfig({
-  // entry 必填：主题指向 CSS，插件指向 TS/JS
   plugins: [siyuan({ entry: 'src/main.css' })],
 });
 ```
@@ -29,16 +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 选项显式指定类型
+```
+
 ## 选项
 
 | 选项 | 说明 |
 |---|---|
 | `entry` | **必填**。构建入口，相对项目根。主题指向 CSS，插件指向 TS/JS |
-| `kind` | `'theme'` / `'plugin'`；缺省时在 `public/`、项目根依次查找 `theme.json` / `plugin.json` 推断 |
+| `kind` | `'theme'` / `'plugin'`；缺省时按 `publicDir` 下的清单推断 |
 | `outDir` | 产物目录；缺省 `./dev`（watch）/ `./dist`（生产） |
 
-> `entry` 必填是因为产物名是固定契约（主题 `theme.css`、插件 `index.js`）。
-> 入口猜错不会报错，只会静默产出思源加载不到的东西——所以宁可要求显式指定。
+`entry` 必填是因为产物名是固定契约（主题 `theme.css`、插件 `index.js`）。入口猜错不会报错，只会静默产出思源加载不到的东西。
 
 ## 做什么
 
@@ -59,13 +94,21 @@ pnpm vite build --watch
 
 ## 输出
 
-每轮构建结束时打印一行，供 agent 判断「可以测量了」：
+默认只打印用户需要知道的结果与需要处理的问题：链接/启用状态、校验失败、README 复制失败、打包结果与预览入口；端口探测、跳过监听这类内部过程只在 `SIYUAN_DEBUG=1` 时输出。
+
+watch 首轮构建不打印 `build #N` 信号（此时「会话就绪 + 预览入口」已经说明可以开始了）；之后每次热重载打印一行，供 agent 判断「可以测量了」：
 
 ```
 [vite-plugin-siyuan] build #12 ready · theme · watch
 ```
 
-生产构建对应的是：
+watch 构建失败（含校验未通过）对应的是：
+
+```
+[vite-plugin-siyuan] build #12 failed · theme · watch
+```
+
+生产构建成功时：
 
 ```
 [vite-plugin-siyuan] build #1 ready · theme · package.zip
@@ -82,9 +125,9 @@ watch 模式首次就绪后还会打印桌面端 / 移动端两个稳定预览
 | `SIYUAN_PLUGIN_DIR` | 插件安装父目录（`{workspace}/data/plugins`），同上 |
 | `SIYUAN_TOKEN` | 开了 API token 时使用 |
 | `SIYUAN_NO_ELEVATION=1` | 不弹 UAC 提权（CI 环境自动不弹） |
-| `SIYUAN_DEBUG=1` | 输出 debug 级日志 |
+| `SIYUAN_DEBUG=1` | 输出内部调试日志（端口探测、跳过监听、README 兜底等） |
 
-> 旧名 `SYD_NO_ELEVATION` / `SYD_DEBUG` 仍然兼容。
+旧名 `SYD_NO_ELEVATION` / `SYD_DEBUG` 仍然兼容。
 
 ## 配套 CLI
 
@@ -95,10 +138,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。
 
@@ -111,7 +153,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,76 +1,74 @@
 /**
- * 思源产物契约：让 `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');
+        // 清单缺失会在校验阶段报错；这里只是内部流程信息，不该默认打扰用户。
+        log(`publicDir 不存在，跳过监听：${publicDir}`, 'debug');
         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/ 下）跳过。
+ * 把 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;
+    // 清单问题由构建收尾的校验统一报；这里只是 README 搬运的内部兜底过程。
+    if (!isRecord(parsed))
+        log(`读不到或无法解析清单 ${manifestPath}；README 按 README*.md 兜底`, 'debug');
     const names = [];
-    if (declared) {
+    if (declared?.length) {
         names.push(...declared);
     }
     else {
-        log(`清单 ${manifestPath} 没声明 readme/icon/preview，按 README*.md 兜底搬运`, 'warn');
+        log(`清单 ${manifestPath} 没声明 readme，按 README*.md 兜底搬运`, 'debug');
         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 +84,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,7 +26,7 @@ function findDoubleWrappedColors(css) {
     return problems;
 }
 /** 校验一个目标的清单与产物；返回问题列表，空表示通过。 */
-export function verifyTarget(kind, { root, outDir }) {
+export function verifyTarget(kind, { root, publicDir, outDir }) {
     const spec = kindSpec(kind);
     const issues = [];
     // 只校验本次构建的产物目录。不做「产物目录不存在就改扫项目根」的兜底：
@@ -39,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/、项目根与产物目录）`,
+            message: `读不到清单：${spec.manifestName}（应在 public 目录下，或已在产物目录里）`,
             hint: '思源按清单识别主题/插件，缺了它不会出现在列表里。',
         });
     }
@@ -77,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/index.js

@@ -20,6 +20,7 @@ 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';
@@ -37,14 +38,12 @@ export default function siyuan(options) {
             if (!existsSync(entry)) {
                 throw new UserError(`entry 指向的文件不存在：${entry}（选项值：${options.entry}）`);
             }
-            try {
-                kind ??= detectKind(root);
-            }
-            catch (cause) {
-                // 没有清单就不知道产物该叫什么；交给项目自己配，不在这里报错。
-                log(`跳过构建配置注入：${describeError(cause)}`, 'warn');
-                return undefined;
-            }
+            // 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);
             return applyBuildConfig(userConfig, { kind, watch, entry, outDir: options.outDir ?? null });
         },
@@ -54,12 +53,14 @@ export default function siyuan(options) {
             const publicDir = resolvedConfig.publicDir;
             const watch = resolvedConfig.command === 'build' && Boolean(resolvedConfig.build.watch);
             if (!kind) {
-                log('识别不到被测类型，跳过链接与校验', 'warn');
-                return;
+                // 正常情况下 config 阶段已确定类型或抛错；走到这里说明状态异常，
+                // 不能只 warn 后跳过校验——静默产出思源加载不到的东西更难排查。
+                throw new UserError('识别不到被测类型：请确认 publicDir 下的 theme.json / plugin.json，或用 kind 选项显式指定');
             }
             session = createBuildSession({ root, outDir: resolve(root, outDir), publicDir, watch }, { kind, log, previewLogger: log });
+            // 生产构建的最终结果由「已打包 + build #N ready」体现，模式说明只对排查有用。
             if (!watch)
-                log('生产构建：不启动热重载会话，只校验产物并打包');
+                log('生产构建：不启动热重载会话，只校验产物并打包', 'debug');
         },
         buildStart() {
             session?.onStart((file) => this.addWatchFile(file));

package/dist/output/log.js

@@ -1,9 +1,11 @@
 /**
  * 日志：consola 带 tag 前缀，保留级别图标与配色。
  *
+ * 默认级别只输出用户需要知道的结果与需要处理的问题；内部过程信息走 debug，
+ * 由 `SIYUAN_DEBUG=1`（旧名 `SYD_DEBUG`）打开。用精确比较而不是 truthiness：
+ * `=0` 在 shell 里很常见，truthiness 会把它读成「开」。
+ *
  * 用 `compact: false` 让多行消息保持原样——预览入口那块靠它维持缩进。
- * `SIYUAN_DEBUG=1`（旧名 `SYD_DEBUG`）时降到 debug 级别；用精确比较而不是
- * truthiness：`=0` 在 shell 里很常见，truthiness 会把它读成「开」。
  */
 import { createConsola } from 'consola';
 import { envFlag } from '../support/env.js';
@@ -14,6 +16,9 @@ export function createTaggedLogger(tag) {
     }).withTag(tag);
     const log = (message, level = 'info') => {
         switch (level) {
+            case 'debug':
+                logger.debug(message);
+                break;
             case 'success':
                 logger.success(message);
                 break;

package/dist/session.js

@@ -5,8 +5,8 @@
  */
 import { relative, resolve } from 'node:path';
 import { activate, reloadUI } from './siyuan/activate.js';
-import { copyMetadata, watchPublicFiles } from './artifact/assets.js';
-import { checkLinkedFiles, ensureLink } from './siyuan/link.js';
+import { copyReadmes, watchPublicFiles } from './artifact/assets.js';
+import { ensureLink } from './siyuan/link.js';
 import { kindSpec, readName } from './siyuan/kinds.js';
 import { findKernelPort } from './siyuan/port.js';
 import { logPreviewLinks } from './output/preview-links.js';
@@ -32,13 +32,16 @@ export function createBuildSession(facts, options) {
     let starting = null;
     let reported = false;
     let buildCount = 0;
+    let failed = false;
+    let wrote = false;
+    let signaled = false;
     let pendingTimer = null;
     let pendingFiles = [];
     let chain = Promise.resolve();
     /** 建会话：找端口 → 解析安装目录 → 链接 → 激活。失败抛可读错误。 */
     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,
@@ -50,25 +53,18 @@ export function createBuildSession(facts, options) {
         const link = ensureLink(current.outDir, installPath, { requireSymlink: spec.requireSymlink });
         if (!link.ok)
             throw new UserError(link.reason ?? '建立链接失败');
-        if (link.changed)
-            log(`已链接：${installPath}`, 'success');
-        const missing = checkLinkedFiles(installPath, spec.expectedFiles);
-        if (missing.length)
-            log(`链接目录缺少 ${missing.join('、')}，构建完成后会补齐`, 'warn');
+        // 首次建链是用户关心的安装结果；链接本来就在时路径只对排查有用，放 debug。
+        log(`已链接：${installPath}`, link.changed ? 'success' : 'debug');
         const activation = await activate(kind, port, name);
         if (!activation.ok)
             throw new UserError(activation.message);
         // 首次启用插件必须补一次刷新：思源配置刚变，不刷新页面不会加载它。
-        const firstReload = activation.changed ? { ok: await reloadUI(port), message: '' } : null;
-        if (firstReload) {
-            firstReload.message = firstReload.ok ? '已广播刷新，思源正在加载' : '刷新广播失败，请手动刷新思源窗口';
-            log(firstReload.message, firstReload.ok ? 'success' : 'warn');
-        }
+        // 成功是预期结果，不单独占一行；失败才需要提醒用户手动刷新。
+        const firstReload = activation.changed
+            ? { ok: await reloadUI(port), message: '刷新广播失败，请手动刷新思源窗口' }
+            : null;
         return {
             port,
-            name,
-            linkedPath: link.ok ? installPath : null,
-            missingFiles: missing,
             activation: { ok: activation.ok, message: activation.message },
             firstReload,
         };
@@ -101,26 +97,39 @@ export function createBuildSession(facts, options) {
             if (!ready)
                 return;
             const ok = await reloadUI(ready.port);
-            log(ok ? `页面已刷新：${matched[0]}` : `刷新未生效：${matched[0]}`, ok ? 'success' : 'warn');
+            // 每次保存都成功刷新是正常工作过程，不刷屏；失败必须让用户看到。
+            log(ok ? `页面已刷新：${matched[0]}` : `刷新未生效：${matched[0]}`, ok ? 'debug' : 'warn');
         });
     }
     return {
         /** 构建开始：把 public/** 逐个交给构建器登记监听。 */
         onStart(registerWatchFile) {
+            // 每轮开始重置状态：上一轮失败不能污染下一轮的成功信号。
+            buildCount += 1;
+            failed = false;
+            wrote = false;
+            signaled = false;
             watchPublicFiles(facts.publicDir, registerWatchFile, log);
         },
         /** 产物写完。 */
         async onWritten(files) {
             const current = facts;
+            wrote = true;
             // 元数据搬运先做：校验时文件必须已经就位。
-            copyMetadata({
-                root: current.root,
-                publicDir: current.publicDir,
-                outDir: relative(current.root, current.outDir) || '.',
-                manifestName: spec.manifestName,
-                watch: current.watch,
-                log,
-            });
+            try {
+                copyReadmes({
+                    root: current.root,
+                    publicDir: current.publicDir,
+                    outDir: relative(current.root, current.outDir) || '.',
+                    manifestName: spec.manifestName,
+                    watch: current.watch,
+                    log,
+                });
+            }
+            catch (cause) {
+                failed = true;
+                throw cause;
+            }
             if (!current.watch)
                 return;
             // 会话还没起来：启动它，本轮不通知重载。
@@ -130,6 +139,11 @@ export function createBuildSession(facts, options) {
                     await ensure();
                 }
                 catch (cause) {
+                    failed = true;
+                    // UserError 已经是可读文案（链接权限、安装目录不存在、多个工作区…），
+                    // 再套一层「思源在运行」会把权限问题误指成思源没启动。
+                    if (cause instanceof UserError)
+                        throw cause;
                     throw new UserError(`watch 模式需要思源在运行：${describeError(cause)}`);
                 }
                 return;
@@ -145,12 +159,22 @@ export function createBuildSession(facts, options) {
         /** 一轮结束：校验 + 打包。 */
         onFinished() {
             const current = facts;
-            buildCount += 1;
-            const result = verifyTarget(kind, { root: current.root, outDir: current.outDir });
+            // 构建在 writeBundle 之前就失败，或 writeBundle 已经失败：跳过校验/打包，
+            // 否则「产物目录不存在」会盖住真正的构建错误。
+            if (!wrote || failed) {
+                failed = true;
+                return;
+            }
+            const result = verifyTarget(kind, {
+                root: current.root,
+                publicDir: current.publicDir,
+                outDir: current.outDir,
+            });
             if (!result.ok) {
                 const text = formatIssues(result.issues);
                 if (current.watch) {
                     // 开发中中断会让 watch 退出，得手动重开，代价太大。
+                    failed = true;
                     log(`产物校验未通过，开发模式仅提示：\n${text}`, 'warn');
                 }
                 else {
@@ -166,20 +190,30 @@ export function createBuildSession(facts, options) {
         /** 本轮最后：打印会话汇报与预览入口（只一次），再打构建完成日志。 */
         onEnd() {
             const current = facts;
-            if (current.watch && ready && !reported) {
+            // Vite 在构建失败时可能多次触发 closeBundle；每轮只发一次完成信号。
+            if (signaled)
+                return;
+            signaled = true;
+            if (current.watch && ready && !reported && !failed) {
                 reported = true;
-                log(`已链接到思源 ${ready.linkedPath}`, 'success');
-                if (ready.missingFiles.length)
-                    log(`链接目录缺少 ${ready.missingFiles.join('、')}`, 'warn');
-                if (ready.activation)
-                    log(ready.activation.message, ready.activation.ok ? 'success' : 'error');
-                if (ready.firstReload)
-                    log(ready.firstReload.message, ready.firstReload.ok ? 'success' : 'warn');
+                // 只汇报「现在处于什么状态」：链接/启用的成功路径已在动作发生时打过，
+                // 这里不再重复；刷新失败才是需要用户处理的问题。
+                log(ready.activation.message, 'success');
+                if (ready.firstReload && !ready.firstReload.ok)
+                    log(ready.firstReload.message, 'warn');
                 log('会话就绪，改源码会自动刷新页面', 'success');
                 logPreviewLinks(previewLogger, ready.port);
             }
             // agent 的构建完成信号：纯文本、序号递增，便于从 stdout 里认。
+            // watch 首轮不打印：此时「会话就绪 + 预览入口」已经说明可以开始了，
+            // 只有后续热重载才需要这个信号。失败仍然要打印。
             const files = current.watch ? 'watch' : PACKAGE_NAME;
+            if (!wrote || failed) {
+                console.log(`[vite-plugin-siyuan] build #${buildCount} failed · ${kind} · ${files}`);
+                return;
+            }
+            if (current.watch && buildCount === 1)
+                return;
             console.log(`[vite-plugin-siyuan] build #${buildCount} ready · ${kind} · ${files}`);
         },
         /** 释放定时器（幂等）。 */

package/dist/siyuan/kinds.d.ts

@@ -17,9 +17,9 @@ export interface KindSpec {
 }
 export declare function kindSpec(kind: Kind): KindSpec;
 /**
- * 从项目目录推断类型：看 public/ 或项目根存在哪份清单。
+ * 从项目目录推断类型：看 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/ 或项目根存在哪份清单。
+ * 从项目目录推断类型：看 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/ 或项目根下找不到 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/link.d.ts

@@ -14,6 +14,4 @@ export interface LinkResult {
 export declare function ensureLink(srcPath: string, targetPath: string, { requireSymlink }?: {
     requireSymlink?: boolean;
 }): LinkResult;
-/** 链接建好后，确认思源该读的文件真的在（防止链到空目录还以为成功）。 */
-export declare function checkLinkedFiles(targetPath: string, expectedFiles: string[]): string[];
 export {};

package/dist/siyuan/link.js

@@ -110,7 +110,10 @@ function elevateSymlink(srcPath, targetPath) {
     }
 }
 function describeFailure(cause, requireSymlink, elevationFailed) {
-    const lines = [`无法建立目录链接：${cause instanceof Error ? cause.message : String(cause)}`];
+    // cause 为 null 只可能出现在「循环没走到 catch」的理论分支；仍给出可读文案，
+    // 绝不能把 `null` 打给用户。
+    const detail = cause instanceof Error ? cause.message : cause === null ? '系统拒绝创建链接（权限不足）' : String(cause);
+    const lines = [`无法建立目录链接：${detail}`];
     if (elevationFailed) {
         lines.push('  UAC 提权被拒绝或超时：请重新运行并在弹窗点「是」，或预先开启 Windows 开发者模式。');
         lines.push('  插件目录必须是真 symlink，不能用 junction 兜底。');
@@ -197,7 +200,3 @@ export function ensureLink(srcPath, targetPath, { requireSymlink = false } = {})
     }
     return { ok: false, changed: false, linkType: null, reason: describeFailure(null, requireSymlink, elevationFailed) };
 }
-/** 链接建好后，确认思源该读的文件真的在（防止链到空目录还以为成功）。 */
-export function checkLinkedFiles(targetPath, expectedFiles) {
-    return expectedFiles.filter((file) => !existsSync(resolve(targetPath, file)));
-}

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,24 +1,69 @@
 /**
- * 清单文件的读取。
+ * 清单文件的读取与 publicDir 解析。
  *
- * 清单可能出现在两处：`public/`（源码）或项目根（官方 sample 的布局）。
- * 构建产物里的清单由调用方通过 `extraDirs` 显式传入，不作为默认候选——
- * 否则上一次构建留下的 `dist/theme.json` 会盖住源码里的新清单。
+ * 清单**只从 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'), 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/dist/support/log.d.ts

@@ -1,5 +1,10 @@
 /** 日志级别与回调契约（不含输出实现，实现在 output/log.ts）。 */
-/** 日志级别。 */
-export type LogLevel = 'info' | 'success' | 'warn' | 'error';
+/**
+ * 日志级别。
+ *
+ * 默认只应使用 info / success / warn / error 输出用户关心的结果与问题；
+ * 探测端口、跳过监听、兜底读取这类过程信息走 debug，仅 `SIYUAN_DEBUG=1` 时可见。
+ */
+export type LogLevel = 'debug' | 'info' | 'success' | 'warn' | 'error';
 /** 日志回调。level 可选，缺省按 info 处理。 */
 export type Logger = (message: string, level?: LogLevel) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-siyuan",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Vite plugin for SiYuan theme/plugin development: config injection, link to workspace, hot reload, verify and package",
   "keywords": [
     "siyuan",