Agent-Skills.md

Agent Skills: 初始化 `shadcn-docs-nuxt` 组件库文档

>-

UncategorizedID: ruan-cat/monorepo/init-shadcn-docs-nuxt

Repository

ruan-cat/monorepo
ruan-catLicense: MIT
41

Install this agent skill to your local

pnpm dlx add-skill https://github.com/ruan-cat/monorepo/tree/HEAD/ai-plugins/dev-skills/skills/init-shadcn-docs-nuxt

Skill Files

Browse the full folder contents for init-shadcn-docs-nuxt.

Download Skill

Loading file tree…

ai-plugins/dev-skills/skills/init-shadcn-docs-nuxt/SKILL.md

Skill Metadata

Name
init-shadcn-docs-nuxt
Description
>-

初始化 shadcn-docs-nuxt 组件库文档

以"最小可用 + 快速稳定"为目标，给任意项目建立可长期维护的 shadcn-docs-nuxt 文档站。

本技能拆分为三层：

  • SKILL.md — 导航与流程
  • references/ — 排错手册与配置说明
  • templates/ — 可直接复制的代码模板（含完整注释，注释即文档）

执行时按流程推进，遇到配置细节查 reference，需要代码直接读 template。

模板文件索引（templates/）

代码模板包含完整的注释说明，注释中记录了每个配置项的根因、不配置的后果、以及历史事故。使用时直接读取模板文件，不要跳过注释。

| 模板文件 | 对应文档站文件 | 说明 | | ------------------------------------------------------------------------ | ------------------------- | -------------------------------- | | templates/nuxt.config.minimal.ts | nuxt.config.ts | 最小启动骨架 | | templates/nuxt.config.full.ts | nuxt.config.ts | 生产基线（默认保留 Nitro trace） | | templates/app.config.ts | app.config.ts | 站点元信息与 UI 配置 | | templates/tailwind.config.js | tailwind.config.js | 完整 Tailwind + shadcn-vue 主题 | | templates/assets/css/tailwind.css | assets/css/tailwind.css | CSS 入口 + 亮/暗主题变量 | | templates/assets/css/main.css | assets/css/main.css | 自定义样式示例 | | templates/shims/debug.ts | shims/debug.ts | debug ESM 兼容 shim | | templates/workspace-aliases.ts | workspace-aliases.ts | 组件库源码别名函数 | | templates/plugins/ui-lib.ts | plugins/xxx.ts | Nuxt Plugin 注册模式 | | templates/package.json | package.json | 依赖与脚本基线 | | templates/prettierrc.json | .prettierrc | MDC 防护（兜底方案） | | templates/prettierignore | .prettierignore | MDC 防护（主方案） |

参考文档索引（references/）

| 文件 | 内容 | | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | references/nuxt-config.md | 按需补丁策略、禁改项清单 | | references/compat.md | ESM/CJS 兼容速查表、排查顺序、常见误判表 | | references/tailwind-css.md | content 扫描规则、CSS 变量格式、常见样式问题排查 | | references/mdc-prettier.md | MDC 标准语法、5 种错误写法对照、hydration mismatch 因果链 | | references/windows.md | 构建假卡死、子进程链清理、EPERM 文件锁、单进程复现法 | | references/workspace.md | 别名顺序陷阱、依赖矩阵、plugin 注册、i18n 单语、OG Image、目录结构 | | references/incident-repair.md | Nuxt Content/H3 版本漂移、prerender 钩子历史与构建故障分层排查 | | references/dependency-triage.md | 依赖提升层排查、packageExtensions/overrides/patch 决策、optimizeDeps 盲区、fork 治理、平台二进制追踪 | | references/ssr-hydration.md | 水合诊断工具链、非 SSR-safe 包隔离手法、hoisted 组件解析陷阱、HTTP 200 假象、SSR 验收清单 | | references/production-graph-and-runtime-closure.md | production graph、final Nitro OOM、standalone MODULE_NOT_FOUND、Turbo cache 与 artifact 验收 | | references/README.md | 九份现行参考的信号导航与迁移台账 |

核心原则（6 条铁律）

  1. 保持精简：nuxt.config.ts 和 app.config.ts 先最小化，不先堆功能。
  2. 先跑通再美化：优先确保 dev / build 稳定，再做样式和内容扩展。
  3. 先修运行链再修样式：交互异常（暗黑模式、侧边栏折叠失效）先查 hydration 和模块导入报错，不要先改 CSS。
  4. 避免错误扩展：不要第一时间折腾 i18n / icon 自定义方案，先使用模板默认可用路径。
  5. 内容语法严格：MDC 容器语法要标准化，参见 references/mdc-prettier.md。
  6. 生产闭包先证据后配置：Vercel READY 只代表部署编排完成，不代表 Function runtime 可用；必须把部署包 manifest、最终 artifact、远端请求和运行日志串成证据链。

历史事故强约束（22 条记忆）

执行本技能时，必须默认带着这些"已发生过"的事故记忆：

  1. 不要假设 workspace 组件库已经先构建完成；文档站需要能直接从源码启动。→ 见 references/workspace.md
  2. 不要把交互失效先归因到样式；先排除 hydration 被模块导入错误打断。→ 见 references/compat.md
  3. 不要让 prettier 改写 content/**/\*.md 的 MDC 结构。→ 见 references/mdc-prettier.md
  4. 不要在 Windows 下把"日志停住"直接判定为"进程卡死"，先排查残留子进程。→ 见 references/windows.md
  5. 不要一开始就重写 i18n / icon 体系；先拿模板默认链路跑通。→ 见 references/nuxt-config.md
  6. 不要直接启用 ogImage 模块；会触发 vue.runtime.mjs does not provide an export named toValue 的 500 错误。→ 见 references/nuxt-config.md
  7. 核心运行时包要按兼容矩阵固定：至少同时审查 shadcn-docs-nuxt、@ztl-uwu/nuxt-content、nuxt、h3，不能只看主题的传递依赖范围。
  8. prerender:routes 不是无条件禁用项，而是历史 workaround：它曾用于缓解 Windows 构建长尾，但对 document-driven Nuxt Content 会导致内容数据库为空；只有确认项目不依赖 Content prerender 且完成等价验证时才可讨论。→ 见 references/incident-repair.md
  9. final Nitro OOM 与 standalone MODULE_NOT_FOUND 必须回到首个失败门：前者需要测量堆与产物阶段，后者需要区分 Vite SSR transform、Nitro inline、trace 与 manifest，不能用宽配置掩盖。→ 见 references/production-graph-and-runtime-closure.md
  10. Turbo cache 命中不等于 runtime closure 可信：只有诊断 cache 可信度或 cache/artifact 证据冲突时，才执行 turbo run <task> --force；常规生产验收不执行该命令，但必须启动 .output server 并完成 HTTP smoke。→ 见 references/production-graph-and-runtime-closure.md
  11. nuxt-og-image 也属于 Nuxt 世代边界：Nuxt 3 保守基线必须将 nuxt-og-image 固定为 5.1.9；5.1.10+ 可能解析 Nuxt 4 的 @nuxt/kit/H3 v2。仅固定 h3: 1.15.11 不足以约束这个传递模块，必须在根 package.json 使用 pnpm.overrides，并用 pnpm why nuxt-og-image @nuxt/kit h3 复核实际树。→ 见 references/incident-repair.md
  12. Vercel READY 不等于 runtime 通过：READY 后必须请求部署 URL 的页面与 Content cache/search API，并读取 Function runtime 日志；没有 HTTP/日志证据时只能标记 candidate 或 needs_check，不能写“生产通过”。→ 见 references/production-graph-and-runtime-closure.md
  13. 修改前后保护 dirty tree：先记录 git status --short --untracked-files=all 与目标 diff；禁止在时间压力下无授权 git add .、覆盖、reset 或把用户脏改动混入验证/提交。→ 见 references/production-graph-and-runtime-closure.md
  14. 构建工具 override 必须按包和 registry 证据收窄：tsdown@0.3.1>rolldown 仅用于复现 rolldown@nightly registry 解析阻断；禁止用 root 全局 rolldown override 掩盖 peer/API 不兼容，必须先检查 pnpm why/list、manifest、lockfile 与 clean fresh install。→ 见 references/production-graph-and-runtime-closure.md
  15. 依赖提升层污染（2026-09-05 ai-vue-doc 实证）：monorepo 中任一包引入新版传递依赖（如 h3 v2）会翻转 pnpm 提升层，所有「未声明该依赖却裸导入」的包同时中招；pnpm why 显示单版本 ≠ 运行时单实例。修复用 packageExtensions 逐包注入，禁用全局 override。→ 见 references/dependency-triage.md
  16. optimizeDeps 预构建盲区（2026-09-05 实证）：.client 插件导入与插件内动态导入的包不在扫描入口，CJS 传递依赖无 interop → 整站不水合且 console 常无错。修复用 vite.optimizeDeps.include 显式纳入（嵌套 > 语法）。→ 见 references/dependency-triage.md
  17. HTTP 200 ≠ 内容正常（catch-all 假象）：pages/[...slug].vue 会把 404 UI 以 200 返回；验证必须断言 <title> 或正文内容。→ 见 references/ssr-hydration.md
  18. 模块执行失败不一定走 console（水合诊断工具链）：判定水合用 __vue_app__；抓真实错误用动态 import(entry + '?v=diag')；定位导入链用 CDP Network.requestWillBeSent 的 initiator.url；Chrome 152 自动启动失败时走手动 CDP 降级路径。→ 见 references/ssr-hydration.md
  19. 客户端/服务端组件注册不对称（hoisted 解析陷阱）：Vue 把组件解析 hoist 到 render 开头，v-if 为假也执行；client-only 注册的组件被 SSR 引用必警告，静态 import 修复会把非 SSR-safe 包拉进 SSR 图致 500，标准解法是 defineAsyncComponent。→ 见 references/ssr-hydration.md
  20. fork 包改名的硬编码自引用残留（2026-09-05 实证）：fork 的 dist 内可能硬编码旧包名前缀的 optimizeDeps.include 条目，vite 必然解析失败；用 pnpm patch 修正前缀（先确认依赖链物理完整）。引入 fork 后先 grep 其 dist 自引用字符串。→ 见 references/dependency-triage.md
  21. 非 SSR-safe 包的隔离与 UI 配置陷阱：非 SSR-safe 包（顶层 DOM API、dist 内 CSS 导入）一律走 .client 边界；UI 配置（logo 等）修改必须过桌面视口浏览器验收，源码 v-if 分支推断不可靠。→ 见 references/ssr-hydration.md
  22. 构建期平台二进制警告先验证再定性，且禁用 traceInclude：sharp binaries cannot be found 不一定是缺依赖——nitro trace: false 下追踪目录必然为空；先验证 sharp 可加载性再定性。任何平台都勿配置 traceInclude: ["sharp"]（Vercel linux 生产实机证伪：nft emitDependency 对 resolve 出的伪路径抛硬错误，构建失败）。→ 见 references/dependency-triage.md

故障检修入口（命中信号后必须执行）

当出现 Content cache/search API 500、ERR_INVALID_URL、H3 sendError 导出缺失、 entities/decode 或 @vueuse/core 缺包、registerMessageResolver、Nitro prerender 失败、 page._id 为空、Windows 构建长时间无输出等信号时，先读取 references/incident-repair.md，再修改配置或内容。

出现依赖解析类信号——Failed to resolve dependency、整批包同时报同一依赖的导出缺失、 sharp binaries ... cannot be found、fork 包升级后批量 WARN、pnpm why 与实际行为矛盾—— 先读取 references/dependency-triage.md。

出现 SSR/水合类信号——页面 200 但交互全死、console 干净却不水合、 Failed to resolve component: X、SSR 渲染非 SSR-safe 包致 500、 暗黑模式/侧栏失效且组件注册在 .client 插件——先读取 references/ssr-hydration.md。

出现 final Nitro OOM、standalone MODULE_NOT_FOUND、production graph 被 alias 或宽 externalization 放大、 Turbo cache 与 .output 不一致、artifact 无法启动或 HTTP smoke 失败时，先读取 references/production-graph-and-runtime-closure.md。

修改任何 nuxt.config.ts、manifest 或 lockfile 前，先读取当前工作树状态；部署验证时必须区分本地、CI、Vercel 和浏览器四类证据。

检修时必须先回答四件事：

  1. 实际安装的 shadcn-docs-nuxt、@ztl-uwu/nuxt-content、nuxt、h3、nuxt-og-image、@nuxt/kit 是否属于同一兼容世代；提升层 .pnpm/node_modules 的版本与裸导入的解析目标是否与 pnpm why 一致；
  2. 当前错误属于 Content/H3 运行时失配、依赖提升层/预构建盲区（→ dependency-triage.md）、SSR/水合边界（→ ssr-hydration.md）、Windows OOM/NFT 构建长尾，还是 production graph 的 Vite SSR transform、Nitro inline、trace/manifest 闭包；
  3. 当前配置是否误用了历史 prerender:routes / routes.clear()、无条件 trace: false 或全量 inline；
  4. 验证口径是否包含内容断言、水合判定、浏览器桌面视口截图与交互闭环（状态码 200 与 console 干净都不足为证）。

不要用单次首页 200 或本地 Windows 构建成功替代 Content API、fresh 依赖树和 Linux/Vercel 验证。

推荐参考仓库优先级

按以下顺序学习并抽取配置（从高到低）：

  1. nuxt-umami-docs（真实项目的稳定配置范式）
  2. shadcn-docs-nuxt-starter（最小骨架）
  3. shadcn-docs-nuxt（框架源码，仅用于查默认行为）
  4. shadcn-docs-ui-thing（组件库扩展思路，谨慎吸收）

每个仓库重点优先阅读这 6 个文件：package.json → nuxt.config.ts → app.config.ts → tailwind.config.* → assets/css/* → content/index.md

标准落地流程

第 1 步：建立最小骨架

docs-site/
├─ package.json
├─ nuxt.config.ts
├─ app.config.ts
├─ tailwind.config.js
├─ assets/css/
│  ├─ tailwind.css
│  └─ main.css
├─ content/
│  └─ index.md
├─ shims/                  ← 按需，仅当 debug 兼容问题出现时
│  └─ debug.ts
├─ components/content/     ← 按需，自定义 MDC 组件
└─ plugins/                ← 按需，注册 workspace 组件库

如果是重构已有文档站，先保留现有 content/ 层级，不要和"底座重建"混在一次改动里。

第 2 步：依赖与脚本

详见 references/workspace.md § package.json 基线。

核心要点：

  • 依赖：nuxt、shadcn-docs-nuxt、vue、vue-router、tailwindcss、tailwindcss-animate
  • Nuxt 3 文档站还必须固定 nuxt-og-image: 5.1.9；若主题传递依赖声明了更宽范围，在根 package.json 增加 pnpm.overrides.nuxt-og-image: 5.1.9
  • 如需消费 workspace 组件库，补 workspace:* 依赖
  • devDependencies：@iconify-json/lucide（Nuxt Icon 必需）
  • 脚本必须包含 predev / prebuild / postinstall 三处 nuxt prepare
  • fresh install 后必须检查实际解析树，并提交 lockfile；不要让 ^2.13.9 之类的传递范围决定 Content 版本

第 3 步：Nuxt 配置

详见 references/nuxt-config.md。

先用最小骨架启动，遇到客户端报错再按"按需补丁"策略逐项补兼容。

第 4 步：Tailwind + CSS

详见 references/tailwind-css.md。

硬性检查：content 扫描必须覆盖 node_modules/shadcn-docs-nuxt，否则主题类缺失、暗黑样式异常。

第 5 步：MDC 内容

详见 references/mdc-prettier.md。

第 6 步：验证

执行后至少提供以下证据：

| 验证项 | 方法 | | -------------- | ------------------------------------------------------------------------------------------------------------------- | | 启动 | pnpm --filter <pkg> dev → 首页 HTTP 200 | | 依赖 | pnpm list / pnpm why h3 → 核心包实际版本可解释 | | Nuxt 世代 | pnpm why nuxt-og-image @nuxt/kit h3 → nuxt-og-image@5.1.9 且不出现 Nuxt 4/H3 v2 混入 | | Content | fresh dev 请求 cache/search API → HTTP 200 且索引非空 | | 构建 | pnpm --filter <pkg> build → 有 .output 产物 | | 生产图 | 以首个失败门检查 alias、externalization、inline、trace 与实际部署包 manifest | | 产物 | 必须启动 .output server → 关键页面与 Content API HTTP smoke 通过 | | 缓存诊断 | 只有诊断 cache 可信度或 cache/artifact 证据冲突时，才执行 turbo run <task> --force；常规生产验收不执行该命令 | | 交互 | 暗黑模式切换、侧边栏折叠可用 | | 内容 | 抽查至少 1 个 ::demo-playground 页面，无裸 marker 文本 | | console | 无阻断 hydration 的 error | | Vercel runtime | READY 后记录部署 URL、Function 日志、页面与 Content API 响应；未实测不得标记完成 | | 浏览器 | 使用可见浏览器走首页/组件 demo 用户路径，记录 console、hydration 与至少一个交互结果；没有浏览器工具时明确标记未完成 |

生产闭包硬门（必须执行）

按以下顺序推进，不得跳过或把后一个阶段的绿灯当成前一个阶段的修复：

  1. 保护写集：保存 dirty-tree 快照，确认目标文件和用户改动边界。
  2. 锁定解析树：fresh install 后运行 pnpm why/list，核对文档包 manifest、root trace 入口与 lockfile。
  3. 定位首错阶段：将错误归属到 Vite SSR transform、Nitro Rollup、NFT trace、Function manifest 或 runtime startup。
  4. 最小变更：优先修 manifest/入口；只有 exact error 证实所属阶段需要时才加窄 noExternal、inline 或 alias；生产默认不添加 nitro.externals。
  5. 本地产物：启动 .output/server/index.mjs，请求页面与 Content cache/search，记录 PID、响应体和日志。
  6. 远端闭环：Linux/Vercel 构建、Function artifact、部署 URL、HTTP smoke、运行日志和可见浏览器证据必须分别记录。
  7. 状态口径：缺任何外部门时写 candidate/needs_check；只有所有可运行门通过后才写 verified，并保留 deployment ID/SHA。

compatibilityDate 必须与 nitro-api-development 技能保持同一对象契约：同时列出 Cloudflare 与 Vercel 两个平台、各自的官方说明链接，并固定为 2024-09-19。它只代表目标 Nitro provider 的兼容基线，不是 entities/decode 或其他 runtime closure 的修复；不要退化为单字符串或从另一个项目盲抄日期。

文档站 runtime verified 与 npm/插件发布是两条独立链路；本技能不把 changeset、registry、tarball 或 GitHub Release 的成功当作文档站运行时通过。任务同时要求发布时，另按项目发布技能建立独立证据链。

常见故障排查顺序

交互失效（暗黑模式切换失败、侧栏按钮无效）时，严格按此顺序：

  1. 先看浏览器 console 是否有模块导入错误 → references/compat.md
  2. 再按首个错误修依赖入口兼容（alias / optimizeDeps / dedupe / ssr.noExternal）；Vite SSR transform、Nitro inline 与 trace/manifest 不能互相替代。→ references/production-graph-and-runtime-closure.md
  3. 最后再做 Tailwind / 主题样式检查 → references/tailwind-css.md

Content API 500、H3 导出错误或版本漂移时 → references/incident-repair.md

final Nitro OOM、standalone MODULE_NOT_FOUND、artifact 启动失败或 Turbo cache 不可信时 → references/production-graph-and-runtime-closure.md

构建卡住时 → references/windows.md

MDC 裸文本 / hydration mismatch → references/mdc-prettier.md

禁改项（无明确证据前不动）

  1. extends: ["shadcn-docs-nuxt"]（它通常不是根因）
  2. 内容目录层级（底座改造阶段避免和内容重排耦合）
  3. i18n 多语言路线（单语文档站先保持最小配置）
  4. icon 体系大改（先沿用模板可用默认方案）
  5. ogImage: { enabled: false }（直接启用会触发 500）
  6. 生产模板不得默认配置 nitro.externals；Windows trace workaround 只能按 references/windows.md 作为本地、可回滚的诊断开关使用。
  7. 不得把 tsdown 的 registry 解析 workaround 扩大成 root 全局 rolldown override。

反模式清单

  1. 先写大量"自定义配置"，最后才验证能否启动。
  2. 用样式改动掩盖运行时导入错误。
  3. 批量格式化 content/**/*.md 后不做页面与 console 回归。
  4. 在同一轮同时重排内容架构 + 重构底座，导致回归不可定位。
  5. 只报"看起来好了"，不附任何可重复验证证据。
  6. 把 ::demo-playground 写成 ## ::demo-playground。
  7. 在 Windows 下把"日志停住"直接判定为"进程卡死"而不先清理旧进程。
  8. 把历史上的 prerender:routes 清空钩子当成所有 shadcn-docs-nuxt 项目的默认配置；应先判断是否使用 document-driven Content。
  9. 把 Vercel READY、单次页面 200 或本地 build 结果写成生产 runtime 通过。
  10. 未检查 dirty tree 就覆盖配置、执行 git add . 或把用户改动带入 release/验证。
  11. 用 root 全局 rolldown override 让 pnpm install 暂时成功，却没有验证 tsdown 的 peer/range/API 兼容性。

输出要求

执行本技能时，最终至少给出：

  1. 关键改动文件列表（配置、样式、内容）
  2. 运行与构建验证结果
  3. 若有风险项，给出下一步最小补救建议
  4. 明确状态是 verified、candidate 还是 needs_check，并列出未完成的 provider/浏览器证据门