clarity-theme 0.1.2 → 0.1.4

package/README.zh-CN.md

@@ -1,51 +1,55 @@
 # Clarity Theme
 
+[![CI](https://github.com/iicemeta/clarity-theme/actions/workflows/ci.yml/badge.svg)](https://github.com/iicemeta/clarity-theme/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/clarity-theme)](https://www.npmjs.com/package/clarity-theme)
+[![License: MIT](https://img.shields.io/npm/l/clarity-theme)](./LICENSE)
+
 [English](./README.md) | **简体中文**
 
 Clarity Theme 是一个从 [L33Z22L11/blog-v3](https://github.com/L33Z22L11/blog-v3) 抽取出来的可复用 **Nuxt 4 Layer 博客主题**。它提供通用的博客 UI、页面结构、Markdown/MDC 渲染、SEO 集成以及 feed/服务端输出；你的项目只需要提供全部站点数据与内容。
 
-## 功能特性
+## 为什么选择 Clarity？
 
-- 通过一条 `extends` 配置即可完成 Nuxt 4 Layer 安装
-- 带默认值校验的站点配置，并严格拒绝未知字段
-- 用于文章元数据与站点地图数据的 Nuxt Content 集合工厂
-- Markdown、MDC 组件、Shiki 代码高亮、KaTeX、Mermaid、ABC 乐谱与富图片
-- 文章列表、归档、分页、目录（TOC）、搜索、主题切换、小部件、预览与 404 路由
-- Atom、OPML、统计、robots、sitemap 与 LLMs 输出
-- 由使用方配置驱动的 Twikoo、head 脚本与反镜像集成
-- UI 默认值、app config 覆盖、自定义 Shiki 主题与同路径组件覆盖
-- 自动化的 workspace、tarball 消费者、SSR、浏览器、水合、纯度、契约、peer 与上游同步检查
+Clarity 取代传统的 sync fork 工作流。你不需要把上游数千行代码合并进博客仓库，而是以 Layer 方式消费主题，只维护自己的文件：
 
-## 环境要求
+- **一条 `extends` 配置**即可安装完整的博客应用骨架
+- **Theme 与 Consumer 分离**：文章、友链、重定向、部署配置、密钥与依赖补丁永远不会进入主题包
+- **配置带校验**：`clarity.config.ts` 由 schema 校验，提供默认值并严格拒绝未知字段
+- **Content 工厂**：Nuxt Content 集合与文章 schema 由你的配置派生
+- **富渲染**：Markdown、MDC 组件、Shiki 代码高亮、KaTeX、Mermaid、ABC 乐谱与富图片
+- **完整输出**：文章列表、归档、分页、目录（TOC）、搜索、主题切换、小部件、Atom、OPML、统计、robots、sitemap 与 LLMs
+- **集成仍归你所有**：Twikoo、head 脚本与反镜像均由消费方配置驱动
+- **覆盖而无需 fork**：UI app config 覆盖、同路径组件覆盖、自定义 Shiki 主题与消费方 CSS
 
-| 运行时 | 版本 |
-| --- | --- |
-| Node.js | `^22.19 \|\| ^24.11 \|\| >=26` |
-| pnpm | 12.4.1，或适用于你项目的兼容包管理器 |
-| Nuxt peer | `^4.5.2` |
-| Vue peer | `^3.5.42` |
+## 核心原则
 
-Clarity 已通过 npm 注册表以 `clarity-theme` 分发。它属于应用运行时的一部分（Nuxt 构建与静态生成会直接加载 Layer），因此请将其安装为常规依赖（dependency），而不是开发依赖（devDependency）；生产环境安装也必须能解析到它。
+- **Clarity 是 blog-v3 的 Layer 化提取**，不是重新实现的独立主题。上游 UI、布局与交互默认是 source of truth，除 `tests/upstream-parity.manifest.json` 中显式记录的机械路径改写外保持 byte-identical。
+- **上游硬编码行为优先保留**：泛化、配置化与清理属于后续路线，不属于本次 parity。
+- **个人站点数据归消费方管理**，边界以上游 `init-project` 重置范围为准。
+- **漂移即缺陷**：同步面内任何未登记差异都会让 `pnpm test:upstream-parity` 失败。
 
-## 安装
+## 选择你的路径
 
-```bash
-pnpm add clarity-theme
-```
+| 起点 | 文档 |
+| --- | --- |
+| 新博客 | [创建项目](./docs/getting-started/new-project.zh-CN.md) |
+| 现有 blog-v3 站点 | [从 blog-v3 迁移](./docs/getting-started/migration-from-blog-v3.zh-CN.md) · Agent Skill：`migrate-blog-v3-to-clarity` |
+| 手动接入现有 Nuxt 应用 | [手动安装](./docs/getting-started/manual-installation.zh-CN.md) |
 
-### Git commit 安装（开发回退方式）
+如需 Agent 协助迁移，直接让你的 Agent 使用 `migrate-blog-v3-to-clarity` Skill。完整 Skill 位于 [`skills/migrate-blog-v3-to-clarity`](./skills/migrate-blog-v3-to-clarity/SKILL.md)。
 
-如需使用未发布的 commit、本地调试，或在发布前审查某个具体变更，可以直接从 GitHub 安装：
+## 快速开始
 
 ```bash
-pnpm add github:iicemeta/clarity-theme#<commit>
+pnpm create clarity-theme my-blog
+cd my-blog
+pnpm dev
 ```
 
-该方式仅用于开发场景。正式站点应使用已发布的 npm 版本，以保证安装可复现并被发布验证矩阵覆盖。
-
-## 快速开始
+创建器会显示可编辑的站点默认值并自动检测系统时区；生成的项目自带
+`pnpm new-blog` 写作命令。
 
-### 1. 继承 Layer
+创建包以独立的 `create-clarity-theme` npm 包分发，稳定版位于 `latest` dist-tag。完整参数见 [`create-clarity-theme/README.md`](./create-clarity-theme/README.md)。手动接入只需四个文件：
 
 ```ts
 // nuxt.config.ts
@@ -54,8 +58,6 @@ export default defineNuxtConfig({
 })
 ```
 
-### 2. 定义站点配置
-
 ```ts
 // clarity.config.ts
 import { defineClarityConfig } from 'clarity-theme/config'
@@ -65,18 +67,11 @@ export default defineClarityConfig({
 		title: 'My Blog',
 		description: 'Notes about technology and life',
 		url: 'https://example.com/',
-		author: {
-			name: 'My Name',
-			avatar: '/avatar.webp',
-		},
+		author: { name: 'My Name', avatar: '/avatar.webp' },
 	},
 })
 ```
 
-`site.title`、`site.description`、`site.url` 与 `site.author.name` 为必填项。article、feed、stats、integration、feature 与 changelog 分组均为可选，并使用文档中记载的默认值。
-
-### 3. 创建 Content schema
-
 ```ts
 // content.config.ts
 import { createClarityContentConfig } from 'clarity-theme/content'
@@ -85,276 +80,47 @@ import clarityConfig from './clarity.config'
 export default createClarityContentConfig(clarityConfig)
 ```
 
-文章放在 `content/posts/` 下，其他 Content 页面放在 `content/` 下。
-
-### 4. 可选：提供友链数据
-
-```ts
-// feeds.ts
-import type { FeedGroup } from 'clarity-theme/config'
-
-const feeds: FeedGroup[] = []
-
-export default feeds
-```
-
-如果没有这个文件，友链页面和 OPML 输出会使用空数据，并且构建时会记录一条警告。
-
-### 5. 生成或开发
-
 ```bash
+pnpm add clarity-theme
 pnpm dev
-pnpm generate
-```
-
-从现有 blog-v3 项目完整迁移的操作流程，见[迁移指南](./docs/MIGRATION.zh-CN.md)。主题数据与用户内容是被刻意分开的：这个包永远不会携带你的文章、友链、重定向、部署配置或包补丁。
-
-## 从 blog-v3 迁移
-
-完整的人工迁移指南见[迁移指南](./docs/MIGRATION.zh-CN.md)。如果你希望让当前 Agent 使用 `migrate-blog-v3-to-clarity` Skill 自动执行迁移，可以直接使用下面的提示词：
-
-```markdown
-请使用 `migrate-blog-v3-to-clarity` Skill，把当前这个 blog-v3 项目迁移到 Clarity Theme。
-
-要求：
-
-1. 先只读扫描项目，不立即修改。
-2. 判断当前项目是否属于支持的 blog-v3 结构。
-3. 检查 blog.config.ts、app/app.config.ts、content.config.ts、nuxt.config.ts、feeds.ts、redirects.json、patches、content、public、custom components、server、modules。
-4. 生成迁移计划，并把所有风险项标出来。
-5. 不修改文章正文和 frontmatter。
-6. 不删除 content、public、redirects、patches 或未知自定义代码。
-7. 能自动迁移的部分自动处理。
-8. 需要人工判断的部分暂停修改并记录原因。
-9. 迁移完成后执行 typecheck、generate 和兼容性验证。
-10. 最后输出完整 migration report，包括修改文件、保留配置、人工处理项和测试结果。
-
-整个过程只使用当前 Agent 串行执行，不启动并行 Agent。
-```
-
-## 基础配置
-
-| 文件 | 职责 |
-| --- | --- |
-| `clarity.config.ts` | 站点身份、文章语义、友链、统计、集成、功能开关、更新日志 |
-| `app/app.config.ts` | 仅限可选的响应式 UI 覆盖 |
-| `content.config.ts` | Nuxt Content 集合/schema |
-| `feeds.ts` | 可选的友链数据 |
-| 使用方 `runtimeConfig` | 环境相关配置，以及唯一合法的密钥存放位置 |
-
-逐字段的默认值、可见性与示例见[配置说明](./docs/CONFIGURATION.zh-CN.md)。
-
-可选分组示例：
-
-```ts
-export default defineClarityConfig({
-	site: {
-		title: 'My Blog',
-		description: 'A Nuxt blog',
-		url: 'https://example.com/',
-		author: { name: 'My Name' },
-	},
-	article: {
-		defaultCategory: 'Uncategorized',
-		categories: {
-			Tech: { icon: 'tabler:code', color: '#7777ff' },
-		},
-		types: { tech: {}, story: {} },
-	},
-	feed: { limit: 50, enableStyle: true },
-	features: {
-		atom: true,
-		opml: true,
-		stats: true,
-		antiMirror: false,
-	},
-})
 ```
 
-绝不要把 token 或私有部署凭据放在 `clarity.config.ts` 或 `app/app.config.ts` 中；这两者都可能影响生成的客户端产物。
+文章放在 `content/posts/` 下，其他 Content 页面放在 `content/` 下。可选的 `feeds.ts` 友链数据与部署说明见[手动安装](./docs/getting-started/manual-installation.zh-CN.md)。
 
-## 公共 API
+## 环境要求
 
-| 入口 | API |
+| 运行时 | 版本 |
 | --- | --- |
-| `clarity-theme` | Nuxt Layer 根入口 |
-| `clarity-theme/config` | `defineClarityConfig()` 与配置/schema 类型 |
-| `clarity-theme/content` | `createClarityContentConfig()` 与 `ArticleSchema` |
-| `clarity-theme/schema` | 全部 `clarity*` Zod schema 及派生类型 |
-| `clarity-theme/img` | 头像/favicon/图片 URL 辅助函数 |
-
-Layer 还暴露了 `useClarityConfig()`、`useClaritySite()`、`useClarityArticle()` 与 `useClaritySiteFeedEntry()` 运行时自动导入，以及 `#clarity/feeds` 注入。它们是 Layer 契约，而不是独立的包子路径。
-
-确切的导出/类型边界记录在 [API 文档](./docs/API.zh-CN.md) 中。
-
-## 自定义
-
-### UI 配置
-
-```ts
-// app/app.config.ts
-export default defineAppConfig({
-	clarity: {
-		header: { emojiTail: ['📝'] },
-		pagination: { perPage: 10 },
-		nav: [
-			{
-				title: '',
-				items: [
-					{ icon: 'tabler:files', text: 'Articles', url: '/' },
-					{ icon: 'tabler:link', text: 'Friends', url: '/link' },
-					{ icon: 'tabler:archive', text: 'Archive', url: '/archive' },
-				],
-			},
-		],
-	},
-})
-```
-
-对象会深度合并；数组会整体替换主题的值。
-
-### 组件
-
-在使用方项目中创建同路径的 Layer 相对组件即可替换，例如：
-
-```text
-app/components/content/Badge.vue
-```
-
-使用方组件优先于 Layer 组件。Nuxt 目前会针对这种有意的覆盖模式输出重名警告。
-
-### Shiki 主题
-
-在使用方项目中提供 `app/shiki.config.ts`。只有当该文件不存在时，才会使用主题的回退配置。
-
-UI 分组、同路径组件覆盖、CSS 覆盖、服务端/路由自定义与 Shiki 归属详见[自定义说明](./docs/CUSTOMIZATION.zh-CN.md)。
-
-## 兼容性与验证
-
-验证套件覆盖：
-
-- Playground 静态生成
-- 独立的 `pnpm pack` 消费者安装
-- Node 与 TypeScript 中的五个包导出
-- 三种配置分支
-- Markdown/MDC/代码/数学公式/Mermaid/乐谱/图片渲染
-- 生产 SSR、真实浏览器渲染与开发水合
-- 搜索、分页、归档、TOC、SEO、robots、sitemap、LLMs、Atom、OPML、统计、固定链接、404、Twikoo 分支、反镜像注入、UI 覆盖与组件覆盖
-- 主题纯度、peer 依赖、同步工具与上游漂移
-
-生成的发布矩阵见[兼容性说明](./docs/COMPATIBILITY.zh-CN.md)。当前的精确数量、已知限制、技术债与发布阻塞项见[项目状态](./docs/PROJECT-STATUS.zh-CN.md)与[路线图](./docs/ROADMAP.zh-CN.md)。发布前必须在确切的 commit 上重新按顺序运行整套验证；早先的结果不能替代。
+| Node.js | `^22.19 \|\| ^24.11 \|\| >=26` |
+| pnpm | 12.4.1，或适用于你项目的兼容包管理器 |
+| Nuxt peer | `^4.5.2` |
+| Vue peer | `^3.5.42` |
 
-站点相关的依赖补丁刻意由使用方持有；见[补丁说明](./docs/PATCHES.zh-CN.md)。
+Clarity 属于应用运行时的一部分（Nuxt 构建与静态生成会直接加载 Layer），因此请将其安装为常规依赖，而不是开发依赖。
 
 ## 文档
 
-| 文档 | 用途 |
-| --- | --- |
-| [项目状态](./docs/PROJECT-STATUS.zh-CN.md) | 当前快照、已验证能力、限制、技术债、缺口与里程碑 |
-| [路线图](./docs/ROADMAP.zh-CN.md) | 按优先级排序的 P0/P1/P2 技术债清单、延后决策与里程碑顺序 |
-| [迁移指南](./docs/MIGRATION.zh-CN.md) | 在采用 Clarity 的同时保留 blog-v3 的内容、配置、重定向、补丁、自定义代码与资源 |
-| [架构](./docs/ARCHITECTURE.zh-CN.md) | 主题/使用方边界与构建/运行时数据流 |
-| [API](./docs/API.zh-CN.md) | 公共包/Layer API 与内部实现的边界 |
-| [配置说明](./docs/CONFIGURATION.zh-CN.md) | 字段级 Clarity 配置契约与示例 |
-| [自定义说明](./docs/CUSTOMIZATION.zh-CN.md) | UI、组件、Shiki、CSS、服务端与路由覆盖 |
-| [兼容性说明](./docs/COMPATIBILITY.zh-CN.md) | 生成的发布兼容性矩阵 |
-| [上游同步](./docs/UPSTREAM.zh-CN.md) | 基线、manifest、命令、冲突与工作流 |
-| [补丁说明](./docs/PATCHES.zh-CN.md) | 使用方补丁归属与当前结论 |
-| [发布审计](./docs/RELEASE-AUDIT.zh-CN.md) | 收尾前工程审计与剩余发布门槛 |
-| [发布清单](./docs/RELEASE-CHECKLIST.zh-CN.md) | 确切的最终检查、剩余阻塞项与验证证据 |
-| [发布指南](./docs/PUBLISHING.zh-CN.md) | 版本管理、tag、GitHub Release、OIDC 发布、provenance 与回滚策略 |
-| [更新日志](./CHANGELOG.md) | 面向使用者的发布历史 |
-| [抽取历史](./docs/history/2026-09-layer-extraction.zh-CN.md) | 历史阶段与一次性差分验证 |
-
-## 仓库结构
-
-仓库根目录是工程管理层；Theme 的全部运行时源码统一放在 `src/`：
+所有文档都有对应的简体中文版本（同名 `*.zh-CN.md` 文件）。入口见[文档索引](./docs/README.zh-CN.md)：
 
-```
-clarity-theme/
-├─ src/                  # Theme 运行时源码（Layer srcDir）
-│  ├─ assets/ components/ composables/ layouts/ middleware/
-│  ├─ pages/ plugins/ stores/ types/ utils/
-│  ├─ app.config.ts app.vue error.vue shiki.config.ts
-│  ├─ config/            # config API 源码（npm ./config ./content ./schema）
-│  ├─ img/               # img API 源码（npm ./img）
-│  ├─ modules/           # source-layout 引导模块 + clarity-config 模块
-│  ├─ public/ server/ shared/ remark-plugins/
-├─ skills/               # Agent 工作流 Skill（不进入 npm 包）
-├─ docs/                 # 人工文档
-├─ playground/           # workspace 链接的开发用消费项目
-├─ scripts/  tests/      # 验证与工具脚本
-└─ nuxt.config.ts、package.json、sync-manifest.json、…
-```
-
-`nuxt.config.ts` 保留在包根目录。它最先加载的
-`src/modules/clarity-source-layout` 只为 Clarity 自身 layer 应用 `src/`
-目录元数据；不静态声明 `srcDir`/`serverDir`/`dir.*`，是因为 c12 会把它们
-合并进未显式覆盖这些键的 consumer root 配置。因此 npm 安装、Git commit
-安装与本地目录安装解析到同一份布局，同时不会覆盖 consumer 自己的
-应用目录。
-
-npm 包、Agent Skill 与文档三者职责分离：
-
-- **`clarity-theme`（npm 包）** — 运行时 Nuxt Layer，通过
-  `extends: ['clarity-theme']` 使用。`files` 只发布 `src/` 与根入口文件，
-  开发资产不会进入 tarball。
-- **`skills/migrate-blog-v3-to-clarity`** — 迁移既有 blog-v3 项目的
-  Agent 工作流 Skill。它与仓库一起版本化，但**刻意不**打进 npm 包。
-- **`docs/`** — 中英双语的人工文档。
-
-### 安装迁移 Skill
-
-```bash
-npx skills add iicemeta/clarity-theme --list   # 发现可用 Skill
-npx skills add iicemeta/clarity-theme --skill migrate-blog-v3-to-clarity
-```
-
-开发环境可用 `npx skills add ./skills --list` 发现本地副本。让 Agent 迁移
-blog-v3 站点时，请让它使用 `migrate-blog-v3-to-clarity` Skill；人工流程
-见[迁移指南](./docs/MIGRATION.zh-CN.md)。
+- **入门** — [创建新项目](./docs/getting-started/new-project.zh-CN.md)、[手动安装](./docs/getting-started/manual-installation.zh-CN.md)、[从 blog-v3 迁移](./docs/getting-started/migration-from-blog-v3.zh-CN.md)
+- **指南** — [配置](./docs/guides/configuration.zh-CN.md)、[内容](./docs/guides/content.zh-CN.md)、[自定义](./docs/guides/customization.zh-CN.md)、[集成](./docs/guides/integrations.zh-CN.md)
+- **参考** — [公共 API](./docs/reference/api.zh-CN.md)、[路由与输出](./docs/reference/routes-and-outputs.zh-CN.md)、[兼容性矩阵](./docs/reference/compatibility.zh-CN.md)
+- **概念** — [架构](./docs/concepts/architecture.zh-CN.md)
+- **维护者** — [开发](./docs/maintainers/development.zh-CN.md)、[测试](./docs/maintainers/testing.zh-CN.md)、[上游同步](./docs/maintainers/upstream-sync.zh-CN.md)、[补丁](./docs/maintainers/patches.zh-CN.md)、[发布](./docs/maintainers/publishing.zh-CN.md)、[发布清单](./docs/maintainers/release-checklist.zh-CN.md)、[项目状态](./docs/maintainers/project-status.zh-CN.md)、[路线图](./docs/maintainers/roadmap.zh-CN.md)、[文档规则](./docs/maintainers/documentation.zh-CN.md)
+- **发布历史** — [CHANGELOG](./CHANGELOG.md)；历史记录位于 [docs/history](./docs/history/)
 
 ## 开发
 
 ```bash
-pnpm install              # 主题 + playground workspace
-pnpm dev                  # Playground 开发服务器
-pnpm generate             # Playground 静态生成
-pnpm lint
+pnpm install        # Theme + playground workspace
+pnpm dev            # Playground dev server
+pnpm generate       # Playground static generation
+pnpm lint           # ESLint + Stylelint
 pnpm typecheck
-pnpm verify               # 纯度/静态泄漏检查
-pnpm peers check
-pnpm test:sync
-pnpm test:migration
-pnpm test:contract
-pnpm test:consumer
-pnpm test:compatibility
-pnpm pack --dry-run       # 不落盘检查 npm tarball
-```
-
-CI 从包元数据推导 Node 与 pnpm 版本。它先在固定的 Node 矩阵上运行 lint/typecheck/verify/sync/migration/contract/peers，再在主 Node 版本上运行 playground 生成、真实消费者验收与渲染兼容性。另有一个每周工作流只检测并报告上游漂移。
-
-确切的 CI 阶段与权限见[项目状态 → CI](./docs/PROJECT-STATUS.zh-CN.md#10-ci)。
-
-## 上游同步
-
-Clarity 从一个上游 Nuxt 博客抽取而来，并在 `sync-manifest.json` 中记录确切的已审查基线。同步工具区分可直接包含的路径、使用方持有的排除项、经过转换的主题契约与人工审查路径；未知的上游变更会阻止 apply。使用：
-
-```bash
-pnpm sync:check   # 比较 manifest 基线与远端
-pnpm sync:diff    # 对上游变更分类
-pnpm sync:apply   # 事务式应用已审查的 include-only 变更
-pnpm sync:verify  # 重新运行主题纯度与基线检查
 ```
 
-每周工作流只检测并报告漂移，绝不会 apply、commit 或 push 变更。见[上游同步](./docs/UPSTREAM.zh-CN.md)。
-
-## 发布状态
-
-Clarity Theme 是一个 **v0.1.2 门禁 npm 发布版本**。Layer/包边界、已校验配置、Content 工厂、渲染管线、服务端输出、playground、真实消费者验收、兼容性矩阵、三层 CI、上游同步基线、发布门禁与 OIDC 发布工作流均已实现。剩余的人工发布步骤见[发布检查清单](./docs/RELEASE-CHECKLIST.zh-CN.md)。
-
-[路线图](./docs/ROADMAP.zh-CN.md)中的 v0.1.0 正确性门禁已解决：服务端/客户端配置已拆分、功能关闭路由在运行时返回 404、反镜像导航已在真实浏览器中验证、no-op 随机固定链接字段已移除，多模式统计已增加回归测试。其余推迟事项记录在路线图与发布说明中。
+完整验证矩阵、上游同步与发布流程见[开发](./docs/maintainers/development.zh-CN.md)与[测试](./docs/maintainers/testing.zh-CN.md)。
 
 ## 许可证
 
-主题代码采用 MIT 许可证。上游博客的文章不包含在本包中。
+主题代码为 MIT。上游博客的文章不包含在本包中。

package/nuxt.config.ts

@@ -3,6 +3,7 @@ import { arch, env, version as nodeVersion, platform } from 'node:process'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { name as ciName, CLOUDFLARE_PAGES, GITHUB_ACTIONS, NETLIFY } from 'ci-info'
 import { Temporal } from 'temporal-polyfill'
+import Yaml from 'unplugin-yaml/vite'
 import { homepage, name as themeName, version as themeVersion } from './package.json'
 
 /** Theme 根目录（Layer 本地路径基准，兼容 npm 包 / git 包 / 本地目录安装） */
@@ -88,6 +89,9 @@ export default defineNuxtConfig({
 		// Layer 配置中的相对 module 路径会以消费项目为基准解析，必须使用绝对路径；
 		// 且 clarity-config 必须先于 nuxt-llms 运行：后者在 setup 时读取注入的 llms 站点配置
 		toThemePath('src/modules/clarity-config'),
+		// 上游通过 Nuxt 的 modules 目录自动加载；Layer 场景下显式注册，且必须在
+		// clarity-config 之后（其导入 clarity-config 生成的 blog.config 数据模块）。
+		toThemePath('src/modules/anti-mirror'),
 		'nuxt-llms',
 	],
 
@@ -112,6 +116,13 @@ export default defineNuxtConfig({
 	},
 
 	typescript: {
+		// Theme 的 server 目录位于 src/ 内（跟随上游布局），会命中 App tsconfig
+		// 对 srcDir 的整体 include，导致 server 路由在 App 上下文被检查
+		// （queryCollection 等 Nitro 自动导入类型错误）。此处从 App tsconfig 排除；
+		// server 代码仍由 tsconfig.server.json 正常覆盖。
+		tsConfig: {
+			exclude: [toThemePath('src/server')],
+		},
 		nodeTsConfig: {
 			// @keep-sorted
 			include: [
@@ -122,6 +133,10 @@ export default defineNuxtConfig({
 	},
 
 	vite: {
+		// 上游 BlogTech 通过 `~~/pnpm-workspace.yaml` 读取技术栈版本，
+		// 需要 YAML 导入支持（上游注册 unplugin-yaml/nuxt；这里直接注册 vite 插件，
+		// 避免其向消费项目 compilerOptions.types 注入 pnpm 严格布局下无法解析的条目）
+		plugins: [Yaml()],
 		css: {
 			preprocessorOptions: {
 				scss: {
@@ -192,7 +207,8 @@ ${homepage}
 
 	icon: {
 		customCollections: [
-			{ prefix: 'clarity', dir: toThemePath('src/assets/icons') },
+			// 上游使用 `zi` 前缀（zhilu icons）与原始 PascalCase 文件名，保持一致
+			{ prefix: 'zi', dir: toThemePath('src/assets/icons') },
 		],
 		clientBundle: {
 			scan: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clarity-theme",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Clarity Theme — 从 blog-v3 提取的可复用 Nuxt 4 Layer 博客主题",
   "license": "MIT",
   "publishConfig": {
@@ -54,6 +54,7 @@
     "@bikariya/modals": "^0.0.8",
     "@bikariya/shiki": "^0.0.8",
     "@iconify-json/catppuccin": "^1.2.17",
+    "@iconify-json/devicon": "^1.2.10",
     "@iconify-json/line-md": "^1.2.16",
     "@iconify-json/ri": "^1.2.10",
     "@iconify-json/simple-icons": "^1.2.94",
@@ -95,8 +96,10 @@
     "temporal-polyfill": "^1.0.4",
     "ufo": "^1.6.0",
     "unist-util-visit": "^5.1.0",
+    "unplugin-yaml": "^4.2.1",
     "vfile": "^6.0.3",
     "vue-tippy": "^6.7.1",
+    "yaml": "^2.9.1",
     "zod": "^4.5.4"
   },
   "devDependencies": {
@@ -129,6 +132,7 @@
     "lint": "eslint && stylelint \"src/**/*.{vue,scss}\" \"playground/app/**/*.vue\"",
     "lint:fix": "eslint --fix && stylelint \"src/**/*.{vue,scss}\" \"playground/app/**/*.vue\" --fix",
     "typecheck": "pnpm --dir playground typecheck",
+    "docs:check": "node scripts/check-docs.mjs",
     "verify": "node scripts/verify-theme.mjs",
     "test:sync": "node --test tests/sync-upstream.test.mjs",
     "test:migration": "node --test tests/migration-skill.test.mjs",
@@ -136,11 +140,15 @@
     "test:release": "pnpm verify && pnpm test:consumer && pnpm test:compatibility",
     "test:consumer": "node scripts/test-consumer.mjs",
     "test:compatibility": "node scripts/test-compatibility.mjs",
+    "test:create": "pnpm --dir create-clarity-theme test",
+    "test:create:e2e": "pnpm --dir create-clarity-theme test:e2e",
+    "test:create:tarball": "pnpm --dir create-clarity-theme test:tarball",
     "test:registry-consumer": "node scripts/test-registry-consumer.mjs",
     "release:check": "node scripts/release-check.mjs",
     "sync:check": "node scripts/sync-upstream.mjs check",
     "sync:diff": "node scripts/sync-upstream.mjs diff",
     "sync:apply": "node scripts/sync-upstream.mjs apply",
-    "sync:verify": "node scripts/sync-upstream.mjs verify"
+    "sync:verify": "node scripts/sync-upstream.mjs verify",
+    "test:upstream-parity": "node scripts/test-upstream-parity.mjs"
   }
 }

package/src/app.config.ts

@@ -1,110 +1,14 @@
 /**
- * Clarity Theme UI 默认配置。
+ * Layer 级 app.config。
  *
- * 站点数据（标题、作者、文章分类等）来自根目录 clarity.config.ts，
- * 由 src/modules/clarity-config 注入到 appConfig.clarity 中。
- *
- * 消费项目可在自己的 app/app.config.ts 中按需覆盖任意键。
+ * UI 默认值由 src/modules/clarity-config 从 src/config/ui.ts 注入（inline 层），
+ * 此处仅提供需要字面量类型的键：pagination.sortOrder 若由模块注入，
+ * JSON 字面量会被宽化为 string，导致上游 useArticle 的
+ * ref<ArticleOrderType>(initialOrder) 类型不匹配。以 Layer cfg 提供
+ * 'date' 字面量（运行时与默认值一致，可被消费项目顶层键覆盖）。
  */
 export default defineAppConfig({
-	clarity: {
-		// @keep-sorted
-		component: {
-			alert: {
-				/** 默认使用卡片风格还是扁平风格 */
-				defaultStyle: 'card' as 'card' | 'flat',
-			},
-
-			codeblock: {
-				/** 代码块触发折叠的行数 */
-				triggerRows: 32,
-				/** 代码块折叠后的行数 */
-				collapsedRows: 16,
-				/** 启用代码块缩进导航会关闭空格渲染 */
-				enableIndentGuide: true,
-				/** 代码块缩进导航竖线匹配空格数 */
-				indent: 4,
-				/** tab 渲染宽度 */
-				tabSize: 3,
-			},
-
-			/** 文章开头摘要 */
-			excerpt: {
-				animation: true,
-				caret: '_',
-			},
-
-			/** 精选文章 Slide */
-			slide: {
-				/** 适合封面图无字时启用 */
-				showTitle: true,
-			},
-
-			stats: {
-				/** 归档页面每年标题对应的年龄，无需展示时可留空 */
-				birthYear: undefined as number | undefined,
-			},
-		},
-
-		// @keep-sorted
-		footer: {
-			/** 侧边栏底部图标导航 */
-			iconNav: [] as { icon: string, text: string, url: string }[],
-			/** 页脚站点地图 */
-			nav: [] as {
-				title: string
-				items: { icon: string, text: string, url: string }[]
-			}[],
-		},
-
-		/** 左侧栏顶部 Logo */
-		header: {
-			/** 展示标题文本，否则展示纯 Logo */
-			showTitle: true,
-			emojiTail: [] as string[],
-		},
-
-		/** 友链页面 */
-		link: {
-			/** 无订阅源展示静音图标 */
-			remindNoFeed: true,
-			/** 友链分组内随机排序 */
-			randomInGroup: true,
-		},
-
-		/** 左侧栏导航 */
-		nav: [
-			{
-				title: '',
-				items: [
-					{ icon: 'tabler:files', text: '文章', url: '/' },
-					{ icon: 'tabler:link', text: '友链', url: '/link' },
-					{ icon: 'tabler:archive', text: '归档', url: '/archive' },
-				],
-			},
-		],
-
-		pagination: {
-			perPage: 10,
-			/** 默认排序方式，需要是 article.order 中的键名 */
-			sortOrder: 'date',
-			/** 允许（普通/预览/归档）文章列表正序，开启后排序方式左侧图标可切换顺序 */
-			allowAscending: false,
-		},
-
-		themes: {
-			light: {
-				icon: 'tabler:sun',
-				tip: '浅色模式',
-			},
-			system: {
-				icon: 'tabler:device-desktop',
-				tip: '跟随系统',
-			},
-			dark: {
-				icon: 'tabler:moon',
-				tip: '深色模式',
-			},
-		},
+	pagination: {
+		sortOrder: 'date' as const,
 	},
 })

package/src/assets/icons/zhilu.svg

@@ -0,0 +1,8 @@
+<svg
+	xmlns="http://www.w3.org/2000/svg" viewBox="0 0 50 64" stroke="currentColor" height="1em" fill="none"
+	stroke-linecap="round" stroke-linejoin="round" stroke-width="8"
+>
+	<!-- © Zhilu https://zhilu.site -->
+	<polyline points="4,4 36,4 5,45 37,45" />
+	<polyline points="43,19 12,60 44,60" />
+</svg>