clarity-theme 0.1.3 → 0.2.0

package/src/modules/clarity-config/index.ts

@@ -1,8 +1,9 @@
 import type { Nuxt } from '@nuxt/schema'
 import type { ClarityConfig } from '../../config/schema'
 import type { ClarityServerConfig } from '../../config/server'
-import { existsSync } from 'node:fs'
-import { dirname, relative, resolve } from 'node:path'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { platform } from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { createJiti } from 'jiti'
 import {
@@ -12,21 +13,19 @@ import {
 	updateAppConfig,
 	useLogger,
 } from 'nuxt/kit'
-import nuxtPkg from 'nuxt/package.json'
-import { minify } from 'oxc-minify'
-import vuePkg from 'vue/package.json'
-import { toPublicClarityConfig } from '../../config/public'
+import { parse as parseYaml } from 'yaml'
+import { fallbackPnpmWorkspace } from '../../config/pnpm-workspace'
 import { clarityConfigSchema } from '../../config/schema'
 import { toServerClarityConfig } from '../../config/server'
-import handleMirror from './anti-mirror-client'
+import uiDefaults from '../../config/ui'
 
 const moduleDir = dirname(fileURLToPath(import.meta.url))
 /** Theme 运行时源码根（src/）：模块位于 src/modules/clarity-config */
 const themeSrcDir = resolve(moduleDir, '../..')
-/** Theme npm 包根（nuxt.config.ts / package.json 所在层） */
-const themePkgDir = resolve(moduleDir, '../../..')
+/** Windows 路径比较需要大小写不敏感（vite 解析产物盘符大小写不定） */
+const IS_WINDOWS = platform === 'win32'
 
-/** app/app.config.ts 的 clarity 键只允许 UI 覆盖（站点级字段属于 clarity.config.ts） */
+/** app/app.config.ts 中允许作为 UI 覆盖的顶层键（站点级字段属于 clarity.config.ts） */
 const uiConfigKeys = new Set(['component', 'footer', 'header', 'link', 'nav', 'pagination', 'themes'])
 
 export interface ModuleOptions {
@@ -34,6 +33,15 @@ export interface ModuleOptions {
 	configFile?: string
 }
 
+/** 构建数据重定向插件的最小结构化形状（vite resolveId 子集） */
+interface RedirectPlugin {
+	name: string
+	resolveId: {
+		order: 'pre'
+		handler: (source: string) => { id: string } | undefined
+	}
+}
+
 export default defineNuxtModule<ModuleOptions>({
 	meta: {
 		name: 'clarity-config',
@@ -46,17 +54,29 @@ export default defineNuxtModule<ModuleOptions>({
 
 		const configPath = resolve(rootDir, options.configFile ?? findConfigFile(rootDir))
 		const feedsPath = findFeedsFile(rootDir, themeSrcDir)
+		const consumerBlogConfigPath = findExisting(rootDir, ['blog.config.ts', 'blog.config.mjs', 'blog.config.js'])
+		const consumerSrcFeedsPath = findExisting(nuxt.options.srcDir, ['feeds.ts', 'feeds.mjs', 'feeds.js'])
 
 		// ---- 依赖注入层：Theme 内部不感知消费项目的文件布局 ----
-		Object.assign(nuxt.options.alias, {
+		// 上游文件通过 `~~/blog.config` / `~/feeds` 读取站点数据；消费项目使用
+		// clarity.config.ts（或根目录 feeds.ts），这里以前缀更长的别名承接，
+		// 使上游同步文件无需改写即可在 Layer 中解析。
+		// 新键必须置于 '~' / '~~' 之前，保证 Vite / Nitro 前缀匹配优先命中。
+		nuxt.options.alias = {
+			...(consumerBlogConfigPath ? {} : { '~~/blog.config': resolve(themeSrcDir, 'blog.config.ts') }),
+			// 上游 server 路由通过 ~~/shared/utils/time 引用工具；消费项目没有
+			// shared 目录时指向 Theme 内置实现。
+			...(existsSync(resolve(rootDir, 'shared')) ? {} : { '~~/shared': resolve(themeSrcDir, 'shared') }),
+			...(consumerSrcFeedsPath ? {} : { '~/feeds': feedsPath.resolved }),
 			'#clarity/config': configPath,
 			'#clarity/feeds': feedsPath.resolved,
-		})
+			...nuxt.options.alias,
+		}
 
 		// @pinia/nuxt 不会自动扫描 Layer 的 stores 目录，需显式注册
 		addImportsDir(resolve(themeSrcDir, 'stores'))
 
-		// ---- AppConfig 类型化：消费者 defineAppConfig({ clarity: ... }) 获得完整类型提示 ----
+		// ---- AppConfig 类型化：上游扁平键获得类型提示 ----
 		// 注意：类型文件生成于 buildDir/types/ 下，相对路径必须以其为基准计算，
 		// 否则导入解析失败会因 skipLibCheck 静默退化为 any（审计发现 #9）。
 		const appConfigTypeDir = resolve(nuxt.options.buildDir, 'types')
@@ -68,16 +88,20 @@ export default defineNuxtModule<ModuleOptions>({
 				// app/types/index.ts 的 Window.twikoo 等环境声明在 node_modules Layer 中
 				// 不会被 tsconfig include 命中（被 node_modules exclude 过滤），需显式导入
 				`import '${globalsTypePath}'`,
-				`import type { ClarityAppConfig, ClarityUiConfigInput } from '${appConfigTypePath}'`,
+				`import type { ClarityAppConfigArticle, ClarityUiConfig } from '${appConfigTypePath}'`,
 				'',
 				'declare module \'@nuxt/schema\' {',
-				'  // 读取侧：unknown 使 MergedAppConfig 回落到 Theme 注入的完整 Resolved 类型',
+				'  // 读取侧：UI 扁平键补充完整类型（0.2.0 起不再提供 clarity 嵌套键），',
+				'  // 使上游组件在 JSON 字面量（空数组 / 宽化字符串）下仍获得正确类型。',
+				'  // article 只声明 categories（Record 索引），order / types 保留 Resolved 字面量。',
 				'  interface CustomAppConfig {',
-				'    clarity?: unknown',
-				'  }',
-				'  // 输入侧：完整配置（Theme 内部）或 UI 部分覆盖（消费项目 app/app.config.ts）',
-				'  interface AppConfigInput {',
-				'    clarity?: ClarityAppConfig | ClarityUiConfigInput',
+				'    article?: ClarityAppConfigArticle',
+				'    component?: ClarityUiConfig[\'component\']',
+				'    footer?: ClarityUiConfig[\'footer\']',
+				'    header?: ClarityUiConfig[\'header\']',
+				'    link?: ClarityUiConfig[\'link\']',
+				'    nav?: ClarityUiConfig[\'nav\']',
+				'    themes?: ClarityUiConfig[\'themes\']',
 				'  }',
 				'}',
 				'',
@@ -110,32 +134,214 @@ export default defineNuxtModule<ModuleOptions>({
 		const config = parseClarityConfig((configModule as { default?: unknown })?.default ?? configModule, configPath)
 		const { site, article, integrations, features } = config
 
-		// ---- 边界审计：app/app.config.ts 中不应出现站点级字段（其优先级更高，会覆盖站点配置注入） ----
-		await warnNonUiAppConfigOverrides(nuxt, jiti, logger)
+		// ---- 上游构建期数据模块：~~/package.json 与 ~~/pnpm-workspace.yaml ----
+		// 上游 BlogTech / atom.xml 通过这两个说明符读取消费项目数据；直接把别名
+		// 指到真实 JSON/YAML 文件时，Nitro prerenderer 会将其外部化（Node 无法
+		// 以 ESM 导入 JSON/YAML），导致含 BlogTech 的页面（首页）在预渲染时崩溃。
+		// 因此在 buildDir 生成等价 ES 模块，运行时别名与 TS 声明都指向生成物。
+		const consumerPkg = (await loadJson(resolve(rootDir, 'package.json'), jiti)) ?? {}
+		const missingPkgFields = ['name', 'version'].filter(field => !consumerPkg[field])
+		if (missingPkgFields.length) {
+			logger.warn(
+				`package.json 缺少 [${missingPkgFields.join(', ')}] 字段，BlogTech 等组件将显示空值`
+				+ '（数据经生成模块归一化，构建不会因此失败）。',
+			)
+		}
+		const pnpmWorkspace = loadPnpmWorkspace(rootDir)
+		// 写入消费项目 buildDir（<buildDir>/clarity/）：生成物是 consumer 私有
+		// 构建数据，写入安装包内部（src/generated）会穿透 pnpm 硬链接污染
+		// store——并发构建共享同一 store 条目时互相覆盖、读取方拿到半写状态
+		// （repair phase 2 定位的静默故障源）。写入必须幂等重入：模块 setup 时
+		// 写一次（供 prepare / jiti 加载的 Layer 模块读取），并在 build:before
+		// 再写一次——Nuxt build 会在模块运行后清理 buildDir，把 setup 阶段的
+		// 生成物删掉，vite 打包前必须重写。
+		const buildInfoDir = resolve(nuxt.options.buildDir, 'clarity')
+		const packageJsonModulePath = join(buildInfoDir, 'package-json.mjs').replaceAll('\\', '/')
+		const pnpmWorkspaceModulePath = join(buildInfoDir, 'pnpm-workspace.mjs').replaceAll('\\', '/')
+		const blogConfigData = toUpstreamBlogConfig(config)
+		const blogConfigModulePath = join(buildInfoDir, 'blog.config.mjs').replaceAll('\\', '/')
+		const writeBuildInfoModules = () => {
+			mkdirSync(buildInfoDir, { recursive: true })
+			writeFileSync(packageJsonModulePath, [
+				`const packageJson = ${JSON.stringify({
+					name: String(consumerPkg.name ?? ''),
+					version: String(consumerPkg.version ?? ''),
+					packageManager: String(consumerPkg.packageManager ?? ''),
+				})}`,
+				'export default packageJson',
+				`export const packageManager = ${JSON.stringify(String(consumerPkg.packageManager ?? ''))}`,
+				`export const version = ${JSON.stringify(String(consumerPkg.version ?? ''))}`,
+				'',
+			].join('\n'))
+			writeFileSync(pnpmWorkspaceModulePath, `export default ${JSON.stringify(pnpmWorkspace)}\n`)
+			writeFileSync(blogConfigModulePath, [
+				`const blogConfig = ${JSON.stringify(blogConfigData)}`,
+				'export default blogConfig',
+				`export const myFeed = ${JSON.stringify(toMyFeedEntry(blogConfigData))}`,
+				'',
+			].join('\n'))
+		}
+		writeBuildInfoModules()
+		nuxt.hook('build:before', writeBuildInfoModules)
+		nuxt.options.alias = {
+			'~~/package.json': packageJsonModulePath,
+			'~~/pnpm-workspace.yaml': pnpmWorkspaceModulePath,
+			...nuxt.options.alias,
+		}
+
+		// 上游形状的 blog.config 数据模块（<buildDir>/clarity/blog.config.mjs）：
+		// anti-mirror 等 jiti 加载的 Layer 模块无法解析 #clarity/* 别名
+		// （src/blog.config.ts 运行时适配层仅适用于 App / Nitro 构建上下文），
+		// 因此把映射结果内联成真实模块，供其以 file URL 动态导入。
 
-		// ---- Site Config → App Config 桥梁 ----
-		// 注意 Nuxt appConfig 合并优先级：消费项目 app.config > Theme app.config > 模块注入，
-		// 因此站点派生默认值（header.logo 等）不放入 Theme 的 app.config.ts，
-		// 由这里注入后仍可被消费项目覆盖。
-		updateAppConfig({
-			clarity: {
-				...toPublicClarityConfig(config),
-				header: {
-					logo: site.author.avatar ?? '',
-					subtitle: site.subtitle ?? '',
-				},
-				footer: {
-					copyright: site.copyright?.name
-						? `© ${new Date().getFullYear()} ${site.author.name} · ${site.copyright.name}`
-						: `© ${new Date().getFullYear()} ${site.author.name}`,
+		// 两个说明符的 TS 侧声明（app / server 类型工程的路径重定向目标）
+		const yamlDecl = addTypeTemplate({
+			filename: 'types/clarity-yaml-workspace.d.ts',
+			getContents: () => [
+				'declare const value: Record<string, unknown>',
+				'export default value',
+				'',
+			].join('\n'),
+		})
+		const packageJsonDecl = addTypeTemplate({
+			filename: 'types/clarity-package-json.d.ts',
+			getContents: () => [
+				'declare const value: { name: string, version: string, packageManager: string }',
+				'export default value',
+				'export const packageManager: string',
+				'export const version: string',
+				'',
+			].join('\n'),
+		})
+
+		// 上游类型兼容垫片（post.author 可选字段、*.yaml 导入声明）
+		// 需要在 app / shared / server 三个类型工程中同样生效。
+		const compatTypesPath = resolve(themeSrcDir, 'types/upstream-compat.d.ts')
+		const withLeadingDot = (path: string) => path.startsWith('.') ? path : `./${path}`
+		nuxt.hook('prepare:types', ({ references, sharedReferences, nodeReferences, tsConfig }) => {
+			references.push({ path: compatTypesPath })
+			sharedReferences.push({ path: compatTypesPath })
+			nodeReferences.push({ path: compatTypesPath })
+			// TS 的别名路径替换会去掉 .json/.yaml 扩展名导致解析失败，
+			// 重定向到上方声明模块。
+			if (tsConfig.compilerOptions?.paths) {
+				const packageJsonDeclPath = relative(nuxt.options.buildDir, resolve(nuxt.options.buildDir, packageJsonDecl.filename)).replaceAll('\\', '/')
+				tsConfig.compilerOptions.paths['~~/package.json'] = [withLeadingDot(packageJsonDeclPath)]
+				const yamlDeclPath = relative(nuxt.options.buildDir, resolve(nuxt.options.buildDir, yamlDecl.filename)).replaceAll('\\', '/')
+				tsConfig.compilerOptions.paths['~~/pnpm-workspace.yaml'] = [withLeadingDot(yamlDeclPath)]
+			}
+		})
+		nuxt.hook('nitro:prepare:types', ({ declarations }) => {
+			declarations.push(`/// <reference types="${compatTypesPath.replaceAll('\\', '/')}" />`)
+		})
+
+		// prerenderer 是独立的 Nitro 子构建（nitro:config 不会对其生效），
+		// 生成模块在其中必须内联：外部化为绝对 Windows 路径后 Node 无法
+		// 以 ESM 导入，含 BlogTech 的首页会在预渲染时挂起。
+		;(nuxt.hook as unknown as (event: string, cb: (config: Record<string, any>) => void) => void)('prerender:config', (prerendererConfig) => {
+			prerendererConfig.externals ??= {}
+			prerendererConfig.externals.inline ??= []
+			prerendererConfig.externals.inline.push(packageJsonModulePath, pnpmWorkspaceModulePath)
+		})
+		nuxt.hook('nitro:config', (nitroConfig) => {
+			nitroConfig.typescript ??= {}
+			nitroConfig.typescript.tsConfig ??= {}
+			nitroConfig.typescript.tsConfig.compilerOptions ??= {}
+			nitroConfig.typescript.tsConfig.compilerOptions.paths ??= {}
+			nitroConfig.typescript.tsConfig.compilerOptions.paths['~~/package.json'] = [withLeadingDot(packageJsonDecl.filename)]
+			nitroConfig.typescript.tsConfig.compilerOptions.paths['~~/pnpm-workspace.yaml'] = [withLeadingDot(yamlDecl.filename)]
+		})
+
+		// ---- Vite 打包上下文的重定向契约 ----
+		// 上方为 `~~/package.json` / `~~/pnpm-workspace.yaml` 设置的精确别名，
+		// 在 dev（JS 版 alias 插件，首个匹配生效）中按预期指向生成模块；
+		// 但生产构建的 bundled 环境使用 rolldown 原生 alias 插件，其匹配
+		// 语义让更短的 `~~` → rootDir 前缀别名抢先，导入被改写为消费项目的
+		// 真实文件路径（consumer package.json 缺 version 时即 MISSING_EXPORT）。
+		// 消费项目的真实文件是数据源而非打包目标，这里以显式 resolveId 契约
+		// 把两个绝对路径重定向到生成模块：client / SSR 打包语义一致，且不再
+		// 依赖跨上下文的隐式别名匹配顺序。
+		const rootPackageJsonId = resolve(rootDir, 'package.json').replaceAll('\\', '/')
+		const rootWorkspaceYamlId = resolve(rootDir, 'pnpm-workspace.yaml').replaceAll('\\', '/')
+		const idEquals = (a: string, b: string) => IS_WINDOWS
+			? a.toLowerCase() === b.toLowerCase()
+			: a === b
+		nuxt.hook('vite:extendConfig', (config) => {
+			// InlineConfig.plugins 是 readonly 声明，但 hook 语义允许就地追加；
+			// 插件形状用本地结构化类型，避免对 vite 类型的直接依赖
+			const plugins = (config as { plugins: Array<RedirectPlugin> }).plugins ??= []
+			plugins.unshift({
+				name: 'clarity:build-data-redirect',
+				resolveId: {
+					order: 'pre',
+					handler(source) {
+						if (idEquals(source, rootPackageJsonId)) {
+							return { id: packageJsonModulePath }
+						}
+						if (idEquals(source, rootWorkspaceYamlId)) {
+							return { id: pnpmWorkspaceModulePath }
+						}
+						return undefined
+					},
 				},
+			})
+		})
+
+		// ---- 消费项目 app/app.config.ts：站点级字段的迁移警告 ----
+		const consumerAppConfig = await loadConsumerAppConfig(nuxt, jiti)
+		await warnSiteLevelAppConfigOverrides(consumerAppConfig, logger)
+
+		// ---- 上游形状的扁平 AppConfig 注入（upstream parity 的关键）----
+		// blog-v3 组件一律通过 useAppConfig() 读取扁平键（title / nav / component.*）。
+		// 这里将 clarity.config.ts + UI 默认值注入为同一形状；
+		// 消费项目仍可在自己的 app.config.ts 中按上游习惯直接覆盖任意扁平键。
+		updateAppConfig({
+			// 站点数据（上游来自 blog.config.ts 展开进 app.config.ts）
+			title: site.title,
+			subtitle: site.subtitle ?? '',
+			description: site.description,
+			author: {
+				name: site.author.name,
+				avatar: site.author.avatar ?? '',
+				email: site.author.email ?? '',
+				homepage: site.author.homepage ?? '/',
+			},
+			copyright: site.copyright ?? { abbr: '', name: '', url: '' },
+			favicon: site.favicon,
+			language: site.language,
+			timeEstablished: site.established ?? '',
+			timeZone: site.timezone,
+			url: site.url,
+			defaultCategory: article.defaultCategory,
+			article: {
+				categories: article.categories,
+				types: article.types,
+				order: article.order,
+				useRandomPremalat: false,
+				hidePostPrefix: article.hidePostPrefix,
+				robotsNotIndex: article.robotsNotIndex,
+			},
+			feed: config.feed,
+			scripts: integrations.scripts,
+			stats: config.stats,
+			twikoo: integrations.twikoo ?? { envId: '', preload: '' },
+
+			// UI 配置：站点派生值覆盖结构默认值
+			...uiDefaults,
+			header: {
+				...uiDefaults.header,
+				logo: site.author.avatar ?? site.favicon,
+				subtitle: site.subtitle ?? site.description,
+			},
+			footer: {
+				...uiDefaults.footer,
+				copyright: `© ${new Date().getFullYear()} ${site.author.name}`,
 			},
 		})
 
 		// ---- 服务端专用配置：注入 Nitro 私有 runtimeConfig（不进入客户端 bundle）----
-		// Atom/OPML/stats 处理器与 feature 路由守卫从这里读取完整配置。
-		// 注意：Nuxt 会按消费者实际值推导 runtimeConfig 类型（可选字段可能被推断为必填），
-		// 此处以 Theme 声明的 ClarityServerConfig 为准，避免与消费者无关的推断形状冲突。
+		// 保留 0.1.x 的 useClarityServerConfig() 兼容；上游 server 路由已恢复为
+		// 直接读取 `~~/blog.config`，不再依赖该通道。
 		;(nuxt.options.runtimeConfig as { clarity?: ClarityServerConfig }).clarity = toServerClarityConfig(config)
 
 		// ---- SEO / site / robots / llms ----
@@ -177,19 +383,6 @@ export default defineNuxtModule<ModuleOptions>({
 		head.script.push(...integrations.scripts as any[])
 		head.titleTemplate = `%s %separator ${site.title}`
 
-		// ---- 构建信息（供 BlogTech 等 Widget 使用） ----
-		const consumerPkg = await loadJson(resolve(rootDir, 'package.json'), jiti)
-		const themePkg = await loadJson(resolve(themePkgDir, 'package.json'), jiti)
-		nuxt.options.runtimeConfig.public.clarity = {
-			theme: 'Clarity',
-			themeVersion: String(themePkg?.version ?? ''),
-			themeHomepage: String(themePkg?.homepage ?? ''),
-			siteVersion: String(consumerPkg?.version ?? ''),
-			sitePackageManager: String(consumerPkg?.packageManager ?? ''),
-			nuxtVersion: nuxtPkg.version,
-			vueVersion: vuePkg.version,
-		}
-
 		// ---- 路由规则 ----
 		const routeRules = nuxt.options.routeRules ??= {}
 		if (features.stats) {
@@ -214,16 +407,11 @@ export default defineNuxtModule<ModuleOptions>({
 			}
 		})
 
-		// ---- 可选功能：anti-mirror ----
-		// 黑名单完全由站点配置提供；Theme 不携带任何上游默认域名（审计发现 #5）。
+		// ---- features.antiMirror 已废弃 ----
+		// 上游 modules/anti-mirror 由 Nuxt 自动加载（Layer 的 src/modules 同样生效），
+		// 黑名单与跳转目标与上游保持一致；配置项仅为 0.1.x 兼容保留。
 		if (features.antiMirror !== false) {
-			const blacklist = typeof features.antiMirror === 'boolean' ? [] : features.antiMirror.blacklist
-			if (blacklist.length === 0) {
-				logger.warn('features.antiMirror 已启用，但未配置 blacklist，已跳过反镜像脚本注入。')
-			}
-			else {
-				await injectAntiMirror(nuxt, blacklist, site.url)
-			}
+			logger.warn('features.antiMirror 已废弃：上游 anti-mirror 模块始终启用，黑名单与上游保持一致。')
 		}
 	},
 })
@@ -251,8 +439,8 @@ function parseClarityConfig(raw: unknown, configPath: string): ClarityConfig {
 	return result.data
 }
 
-/** 消费项目 app/app.config.ts 若覆盖站点级字段，会在 defu 合并中压过 clarity.config.ts 注入，需要提示迁移 */
-async function warnNonUiAppConfigOverrides(nuxt: Nuxt, jiti: ReturnType<typeof createJiti>, logger: ReturnType<typeof useLogger>) {
+/** 从消费项目 app/app.config.ts 读取导出对象（失败时交给 Nuxt 自身报错） */
+async function loadConsumerAppConfig(nuxt: Nuxt, jiti: ReturnType<typeof createJiti>) {
 	const candidates = [
 		resolve(nuxt.options.srcDir, 'app.config.ts'),
 		resolve(nuxt.options.rootDir, 'app.config.ts'),
@@ -267,20 +455,10 @@ async function warnNonUiAppConfigOverrides(nuxt: Nuxt, jiti: ReturnType<typeof c
 		globalScope.defineAppConfig ??= (config: unknown) => config
 		try {
 			const mod = await jiti.import(appConfigPath) as unknown
-			const clarity = ((mod as { default?: unknown })?.default ?? mod) as { clarity?: Record<string, unknown> } | undefined
-			if (!clarity?.clarity || typeof clarity.clarity !== 'object') {
-				continue
-			}
-			const offenders = Object.keys(clarity.clarity).filter(key => !uiConfigKeys.has(key))
-			if (offenders.length) {
-				logger.warn(
-					`app/app.config.ts 的 clarity 中出现站点级字段 [${offenders.join(', ')}]，`
-					+ '它们会覆盖 clarity.config.ts 的注入结果；请将站点配置迁移到 clarity.config.ts。',
-				)
-			}
+			return ((mod as { default?: unknown })?.default ?? mod) as Record<string, unknown> | undefined
 		}
 		catch {
-			// 尽力而为的边界提示：app.config 加载失败时交给 Nuxt 自身报错
+			return undefined
 		}
 		finally {
 			if (previousDefine === undefined) {
@@ -291,33 +469,89 @@ async function warnNonUiAppConfigOverrides(nuxt: Nuxt, jiti: ReturnType<typeof c
 			}
 		}
 	}
+	return undefined
 }
 
-async function injectAntiMirror(nuxt: Nuxt, blacklist: string[], target: string) {
-	const source = `(${handleMirror.toString()})(${JSON.stringify(blacklist.map(btoa))},${JSON.stringify(btoa(target))})`
-	const { code, errors } = await minify('clarity-anti-mirror.iife.js', source)
-	if (errors.length > 0) {
-		throw new Error(`[clarity-config] anti-mirror 脚本压缩失败：\n${errors.map(error => error.message ?? String(error)).join('\n')}`)
+/** 站点级字段出现在 app.config.ts 会压过 clarity.config.ts 注入，需要提示迁移 */
+async function warnSiteLevelAppConfigOverrides(appConfig: Record<string, unknown> | undefined, logger: ReturnType<typeof useLogger>) {
+	if (!appConfig) {
+		return
+	}
+	const offenders = Object.keys(appConfig).filter(key => !uiConfigKeys.has(key))
+	if (offenders.length) {
+		logger.warn(
+			`app/app.config.ts 中出现站点级字段 [${offenders.join(', ')}]，`
+			+ '它们会覆盖 clarity.config.ts 的注入结果；请将站点配置迁移到 clarity.config.ts。',
+		)
 	}
-	;(nuxt.options.app.head.script ??= []).push({ innerHTML: code })
 }
 
-function findConfigFile(rootDir: string) {
-	for (const name of ['clarity.config.ts', 'clarity.config.mjs', 'clarity.config.js']) {
-		if (existsSync(resolve(rootDir, name))) {
-			return name
-		}
+/** clarity.config → 上游 blog.config 扁平形状（与 src/blog.config.ts 适配层保持一致） */
+function toUpstreamBlogConfig(config: ClarityConfig) {
+	const { site, article, feed, stats, integrations } = config
+	return {
+		title: site.title,
+		subtitle: site.subtitle ?? '',
+		description: site.description,
+		author: {
+			name: site.author.name,
+			avatar: site.author.avatar ?? '',
+			email: site.author.email ?? '',
+			homepage: site.author.homepage ?? '/',
+		},
+		copyright: site.copyright ?? { abbr: '', name: '', url: '' },
+		favicon: site.favicon,
+		language: site.language,
+		timeEstablished: site.established ?? '',
+		timeZone: site.timezone,
+		url: site.url,
+		defaultCategory: article.defaultCategory,
+		article: {
+			categories: article.categories,
+			types: article.types,
+			order: article.order,
+			useRandomPremalat: false,
+			hidePostPrefix: article.hidePostPrefix,
+			robotsNotIndex: article.robotsNotIndex,
+		},
+		feed,
+		scripts: integrations.scripts,
+		stats,
+		twikoo: integrations.twikoo ?? { envId: '', preload: '' },
 	}
-	return 'clarity.config.ts'
 }
 
-function findFeedsFile(rootDir: string, themeSrcDir: string) {
-	for (const name of ['feeds.ts', 'feeds.mjs', 'feeds.js']) {
-		if (existsSync(resolve(rootDir, name))) {
-			return { found: true, resolved: resolve(rootDir, name) }
+function toMyFeedEntry(blogConfig: ReturnType<typeof toUpstreamBlogConfig>) {
+	return {
+		author: blogConfig.author.name,
+		sitenick: blogConfig.title,
+		title: blogConfig.title,
+		desc: blogConfig.subtitle || blogConfig.description,
+		link: blogConfig.url,
+		feed: new URL('/atom.xml', blogConfig.url).toString(),
+		icon: blogConfig.favicon,
+		avatar: blogConfig.author.avatar,
+		archs: ['Nuxt'],
+		date: blogConfig.timeEstablished,
+		comment: '这是我自己',
+	}
+}
+
+/** 读取消费项目 pnpm-workspace.yaml 的 catalogs；缺失或无 catalogs 时回退到 Theme 内置版本数据 */
+function loadPnpmWorkspace(rootDir: string) {
+	const yamlPath = resolve(rootDir, 'pnpm-workspace.yaml')
+	if (existsSync(yamlPath)) {
+		try {
+			const parsed = parseYaml(readFileSync(yamlPath, 'utf8')) as Record<string, unknown>
+			if (parsed?.catalogs && typeof parsed.catalogs === 'object') {
+				return { catalogs: parsed.catalogs as Record<string, Record<string, string>> }
+			}
+		}
+		catch {
+			// 解析失败时回退到 Theme 内置数据
 		}
 	}
-	return { found: false, resolved: resolve(themeSrcDir, 'config/feeds.empty.ts') }
+	return { catalogs: fallbackPnpmWorkspace.catalogs as Record<string, Record<string, string>> }
 }
 
 async function loadJson(path: string, jiti: ReturnType<typeof createJiti>) {
@@ -328,3 +562,30 @@ async function loadJson(path: string, jiti: ReturnType<typeof createJiti>) {
 		return undefined
 	}
 }
+
+function findConfigFile(rootDir: string) {
+	for (const name of ['clarity.config.ts', 'clarity.config.mjs', 'clarity.config.js']) {
+		if (existsSync(resolve(rootDir, name))) {
+			return name
+		}
+	}
+	return 'clarity.config.ts'
+}
+
+function findExisting(dir: string, names: string[]) {
+	for (const name of names) {
+		const path = resolve(dir, name)
+		if (existsSync(path)) {
+			return path
+		}
+	}
+	return undefined
+}
+
+function findFeedsFile(rootDir: string, themeSrcDir: string) {
+	const found = findExisting(rootDir, ['feeds.ts', 'feeds.mjs', 'feeds.js'])
+	if (found) {
+		return { found: true, resolved: found }
+	}
+	return { found: false, resolved: resolve(themeSrcDir, 'config/feeds.empty.ts') }
+}

package/src/modules/clarity-source-layout/index.ts

@@ -45,6 +45,19 @@ export default defineNuxtModule({
 			shared: directories.shared,
 		}
 
+		// Nuxt 的 LayerAliasingPlugin 会把 Layer 源码内的 ~ / ~~ 前缀按
+		// layer 自身目录改写（node_modules Layer 默认指向 Theme 包根）。
+		// 上游组件中的 ~~ 语义是「站点根目录」（~~/package.json、~/feeds 等），
+		// 这里把本 Layer 的别名显式指向消费项目目录；消费项目不存在的文件
+		// （blog.config、shared/、feeds）由 clarity-config 的精确别名兜底。
+		layer.config.alias = {
+			...layer.config.alias,
+			'~': nuxt.options.srcDir,
+			'@': nuxt.options.srcDir,
+			'~~': nuxt.options.rootDir,
+			'@@': nuxt.options.rootDir,
+		}
+
 		// `getLayerDirectories()` caches a plain metadata object per layer before
 		// modules are installed. Nuxt exposes no invalidation API, so update the
 		// cached paths in place as well as `layer.config`.

package/src/pages/archive.vue

@@ -4,12 +4,12 @@ import { groupBy } from 'es-toolkit/array'
 import { sumBy } from 'es-toolkit/math'
 import { mapValues } from 'es-toolkit/object'
 
-const clarity = useClarityConfig()
+const appConfig = useAppConfig()
 useSeoMeta({
 	title: '归档',
-	description: `${clarity.site.title}的所有文章归档。`,
+	description: `${appConfig.title}的所有文章归档。`,
 })
-const birthYear = computed(() => clarity.component.stats.birthYear)
+const birthYear = computed(() => appConfig.component.stats.birthYear)
 const showTuning = ref(false)
 const spacing = ref(0)
 const column = ref(1)
@@ -36,7 +36,7 @@ const yearlyWordCount = computed(() =>
 
 function getArticleYear(article: ArticleProps) {
 	try {
-		return toZonedTemporal((article as any)[sortOrder.value] as string, clarity.site.timezone).year.toString()
+		return toZonedTemporal(article[sortOrder.value] as string).year.toString()
 	}
 	catch {
 		return ''

package/src/pages/index.vue

@@ -1,10 +1,10 @@
 <script setup lang="ts">
 import { orderBy } from 'es-toolkit/array'
 
-const clarity = useClarityConfig()
+const appConfig = useAppConfig()
 useSeoMeta({
-	description: clarity.site.description,
-	ogImage: clarity.site.author.avatar,
+	description: appConfig.description,
+	ogImage: appConfig.author.avatar,
 })
 
 const { data: listRaw } = await useAsyncData('posts:index', () => getArticleIndexOptions(), { default: () => [] })
@@ -34,6 +34,7 @@ const { data: previewCount } = useAsyncData(
 <template #aside>
 	<WidgetBlogStats />
 	<WidgetBlogTech />
+	<WidgetCommGroup />
 </template>
 
 <BlogHeader class="mobile-only" to="/" tag="h1" />

package/src/pages/link.vue

@@ -1,8 +1,8 @@
 <script setup lang="ts">
-import feeds from '#clarity/feeds'
+import { myFeed } from '~~/blog.config'
+import feeds from '~/feeds'
 
-const clarity = useClarityConfig()
-const myFeed = useClaritySiteFeedEntry()
+const appConfig = useAppConfig()
 
 const { data: postLink } = await useAsyncData(
 	'content:/link',
@@ -12,7 +12,7 @@ const { data: postLink } = await useAsyncData(
 useSeoMeta({
 	title: '友链',
 	ogType: 'profile',
-	description: `${clarity.site.title}的友链页面，收集了添加他为友链的网站和他订阅的网站列表。`,
+	description: `${appConfig.title}的友链页面，收集了添加他为友链的网站和他订阅的网站列表。`,
 })
 
 const copyFields = {
@@ -33,7 +33,7 @@ const copyFields = {
 	v-for="group in feeds"
 	:key="group.name"
 	v-bind="group"
-	:shuffle="clarity.link.randomInGroup"
+	:shuffle="appConfig.link.randomInGroup"
 />
 
 <Tab :tabs="['我的博客信息', '申请友链']" center>