vite-plugin-siyuan 0.3.0 → 0.3.1

package/README.md

@@ -94,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
@@ -117,7 +125,7 @@ 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` 仍然兼容。
 

package/dist/artifact/assets.js

@@ -24,7 +24,8 @@ const README_PATTERN = /^README.*\.md$/;
 /** 把 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))
@@ -47,14 +48,15 @@ export function copyReadmes({ root, publicDir, outDir, manifestName, watch, 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 兜底`, 'warn');
+        log(`读不到或无法解析清单 ${manifestPath}；README 按 README*.md 兜底`, 'debug');
     const names = [];
     if (declared?.length) {
         names.push(...declared);
     }
     else {
-        log(`清单 ${manifestPath} 没声明 readme，按 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));

package/dist/index.js

@@ -53,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

@@ -6,7 +6,7 @@
 import { relative, resolve } from 'node:path';
 import { activate, reloadUI } from './siyuan/activate.js';
 import { copyReadmes, watchPublicFiles } from './artifact/assets.js';
-import { checkLinkedFiles, ensureLink } from './siyuan/link.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,6 +32,9 @@ 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();
@@ -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;
             // 元数据搬运先做：校验时文件必须已经就位。
-            copyReadmes({
-                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,7 +159,12 @@ export function createBuildSession(facts, options) {
         /** 一轮结束：校验 + 打包。 */
         onFinished() {
             const current = facts;
-            buildCount += 1;
+            // 构建在 writeBundle 之前就失败，或 writeBundle 已经失败：跳过校验/打包，
+            // 否则「产物目录不存在」会盖住真正的构建错误。
+            if (!wrote || failed) {
+                failed = true;
+                return;
+            }
             const result = verifyTarget(kind, {
                 root: current.root,
                 publicDir: current.publicDir,
@@ -155,6 +174,7 @@ export function createBuildSession(facts, options) {
                 const text = formatIssues(result.issues);
                 if (current.watch) {
                     // 开发中中断会让 watch 退出，得手动重开，代价太大。
+                    failed = true;
                     log(`产物校验未通过，开发模式仅提示：\n${text}`, 'warn');
                 }
                 else {
@@ -170,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/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/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.3.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",