BIGboss248/nextjs-wordpress

Next.js 开发环境设置 (nextjs-dev-setup)

一个结构化、端到端的编排手册，用于发现、配置和验证 Next.js App Router 开发环境、反向代理路由（Traefik / Nginx）以及以 docs/project.json 作为单一事实来源。

---

前置条件与发现

• 零干扰扫描：在提出问题之前，先扫描现有仓库文件（package.json、锁文件、样式表、docs/adr/*.md、docs/plan.md、CONTEXT.md）。
• 查阅 project-json-schema.md 以了解元数据结构和自动推导规则。

---

阶段 0：多轮设置面试（刨根问底）与计划生成

以渐进式、适应性轮次（每轮后等待用户响应）进行交互式面试，以定制设置：

1. 第 1 轮（范围与工具链）：探查目标测试套件（Jest、Playwright、Storybook）、MCP 服务器以及 @shadcn/lint 强制规则。
2. 第 2 轮（反向代理与生产托管）：探查域名、端口和反向代理策略：
   • 通过 Docker Compose 使用 Traefik：利用 Compose 标签自动发现容器，这些标签读取自环境变量（${DOMAIN_NAME}、${TRAEFIK_ENTRYPOINT}、${TRAEFIK_CERTRESOLVER}），并具有反缓冲功能。
   • 通过主机系统使用 Nginx：在 /etc/nginx/sites-available/<domain> 中使用 Certbot SSL 证书的独立配置。
3. 第 3 轮（CI/CD、Git Hooks 与仓库）：探查 Husky pre-push 测试套件、Commitlint 以及 GitHub Actions Release Please / GHCR 工作流。
4. 查阅 setup-interview-rounds.md 以获取完整问题集和分支逻辑。
5. 计划与执行：生成并呈现一个 implementation_plan.md 工件，详细说明所有计划创建的文件、配置和包，然后直接执行，无需等待手动确认。

---

逐步执行流程

阶段 1：项目元数据与开发者工具（docs/project.json）

1. 使用 project.template.json 根据用户面试选择初始化 docs/project.json。
2. 使用 vscode-launch.json.template 配置 .vscode/launch.json。
3. 使用 providers.tsx.template 和复合 <Link>（使用 Link.tsx.template）搭建 app/providers.tsx，其中包含 <ProgressBarProvider>。
4. 使用 env.example.template 搭建生产环境的 .env.example，使用 env.local.template 搭建本地开发的 .env.local。
5. 应用图标、Apple 图标与 PWA 清单：将 manifest.ts.template 部署到 app/manifest.ts。在根目录 app/favicon.ico、app/icon.png 和 app/apple-icon.png（或动态 ImageResponse 图标）中配置用户提供的 favicon。查阅 app-icons-and-pwa-guide.md。

阶段 2：测试套件（Jest、Playwright 与即时导航）

[!IMPORTANT] 无虚拟测试文件（规则 3）： 请勿在工作区中创建占位符/示例测试文件。仅配置框架文件和脚本。示例模式可在 sample-component.test.tsx、sample-navigation.spec.ts 和 sample-component.stories.tsx 中找到。

1. Jest 单元测试：配置 jest.config.ts.template 和 jest.setup.ts.template。
2. Playwright E2E 与即时导航：安装 @playwright/test 和 @next/playwright（pnpm add -D @playwright/test @next/playwright），配置 playwright.config.ts.template，并安装浏览器。
3. Next.js 即时配置：在 next.config.ts 中配置 cacheComponents: true、partialPrefetching: true 和即时分析。
4. Storybook 工作坊：配置 .storybook/main.ts 和 .storybook/preview.tsx。
5. 查阅 testing-guide.md 和 storybook-guide.md 中的架构。

阶段 3：双 MCP 服务器配置

[!IMPORTANT] 反重力全局 MCP 加载规则： AG 仅加载在主机系统上全局配置的 MCP 服务器（~/.gemini/antigravity/mcp_config.json 和 ~/.gemini/config/mcp_config.json）。工作区 mcp.json 为可移植性而维护。两者都必须配置。

1. 配置 next-devtools、playwright、storybook 和 codebase-memory-mcp。
2. 防卡顿：通过 codebase-memory-mcp config set auto_watch false 设置 auto_watch = false，并部署根目录 .cbmignore。
3. 查阅 mcp-configuration-guide.md 中的完整规范。

阶段 4：Agent 优先的设计系统 Linting（@shadcn/lint）

1. 安装 @shadcn/lint，并使用 eslint.config.mjs.template 配置 ESLint 扁平配置。
2. 查阅 styling-and-linting-guide.md 中的机制。

阶段 5：独立生产 Docker 与反向代理（Traefik / Nginx）

1. 在 next.config.ts 中：解析 Git 提交哈希（getGitCommitHash() 带 CI 回退）和包版本，在 env 下注入 NEXT_PUBLIC_APP_VERSION 和 NEXT_PUBLIC_GIT_COMMIT_HASH，启用 output: "standalone"，设置 deploymentId 用于版本偏差保护（${pkg.version}-${gitHash}），配置带有 X-Accel-Buffering: no 的 headers，并设置 experimental.serverActions.allowedOrigins。
2. 在 .env.example 中记录 NEXT_SERVER_ACTIONS_ENCRYPTION_KEY，并将其传递给运行时环境。
3. 部署 Dockerfile.template（使用 STOPSIGNAL SIGTERM）和 docker-compose.yml.template（使用 stop_grace_period: 30s）。
4. 反向代理配置：
   • Traefik：部署 docker-compose.prod.yml.template，其中包含动态环境变量标签（${DOMAIN_NAME}、${TRAEFIK_ENTRYPOINT}、${TRAEFIK_CERTRESOLVER}）和反缓冲中间件。
   • Nginx：部署或输出 nginx-site.conf.template 到 /etc/nginx/sites-available/<domain>，并附带 Certbot SSL 证书。
5. 查阅 docker-containerization-guide.md 中的架构和多容器缓存漂移提醒。

阶段 6：Git Hooks 与额度优化的 CI/CD

1. 安装 husky、@commitlint/cli、@commitlint/config-conventional。
2. 配置 commitlint.config.mjs.template、.husky/commit-msg 和 .husky/pre-push（pnpm run test:all）。
3. 部署 .github/workflows/release-please.yml，其中包含 .next/cache 构建缓存和多架构矩阵发布。
4. 查阅 cicd-and-release-automation-guide.md 中的缓存说明。

阶段 7：最终执行报告与验证

1. 执行配置验证脚本，确保所有检查通过。
2. 根据规则 36，暂存所有创建/修改的文件（git add .）。
3. 强制性最终输出：呈现完整且结构化的 Next.js 开发设置执行报告 markdown 表格，总结所有已实现的文件、验证检查结果以及后续开发步骤。

---

验证与健全性检查

• 执行配置验证脚本：
  • Windows (PowerShell)：powershell -ExecutionPolicy Bypass -File .agents/skills/nextjs-dev-setup/scripts/verify-project-config.ps1
  • Linux / macOS (Bash)：bash .agents/skills/nextjs-dev-setup/scripts/verify-project-config.sh
• 修复所有报告的错误，并重新验证，直至所有检查通过。

---

边缘情况与已知 AI 陷阱

• 链式命令：切勿在终端执行的单行中使用 && 或 ; 链式命令。
• MCP 禁用：在 AG 全局配置中，agy.exe 会忽略 mcpServers 内的 "disabled": true。将禁用的服务器移到 mcpServers 之外。
• Docker 镜像名称：Docker OCI 命名严格需要小写仓库名称（IMAGE_NAME=$(echo ... | tr '[:upper:]' '[:lower:]')）。
• Storybook Intl Context：始终在渲染 Link 或 useTranslations 的 Storybook 故事外部包裹 NextIntlClientProvider。

---

强制性最终输出：执行报告模板

在完成技能工作流后，始终输出此报告：

## 🛠️ Next.js Dev Setup Execution Report

| Step / Component                     | Target File(s) / Resource                                                                              | Status                          | Notes / Details                                                                  |
| :----------------------------------- | :----------------------------------------------------------------------------------------------------- | :------------------------------ | :------------------------------------------------------------------------------- |
| **1. Project Metadata**              | `docs/project.json`                                                                                    | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured package manager, directories, animation & i18n metadata.              |
| **2. App Icons & PWA Manifest**      | `app/manifest.ts`, `app/favicon.ico`, `app/apple-icon.png`, `app/icon.png`                             | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured root favicon, Apple touch icon, and Web App Manifest using user favicon. |
| **3. Core Dependencies**             | `package.json`, Lockfile                                                                               | `[IMPLEMENTED]` / `[UNTOUCHED]` | Verified React, Next.js, styling, and motion libraries.                          |
| **4. Next.js Dev Server MCP**        | `~/.gemini/antigravity/mcp_config.json`, `mcp.json`, `.agents/plugins/workspace-tools/mcp_config.json` | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured Next.js Dev Server (`next-devtools`) globally for AG & in workspace.  |
| **5. Playwright & Instant Testing** | `playwright.config.ts`, `@next/playwright`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json` | `[IMPLEMENTED]` / `[UNTOUCHED]` | Verified runner, browsers, Playwright MCP & `@next/playwright` instant navigation helper. |
| **6. Codebase Memory & Stutter Fix** | `.cbmignore`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`, `auto_watch=false`                  | `[IMPLEMENTED]` / `[UNTOUCHED]` | Registered MCP, configured .cbmignore exclusions, and disabled session watcher.  |
| **7. Jest Unit Testing**             | `jest.config.ts`, `jest.setup.ts`                                                                      | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured Next.js Jest transformer, jsdom environment & test-dom.               |
| **8. Storybook & Storybook MCP**     | `.storybook/main.ts`, `.storybook/preview.tsx`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`    | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured Storybook Vite, a11y, themes & Storybook AI MCP globally & workspace. |
| **9. Agent-First Tailwind Linter**   | `eslint.config.mjs`, `package.json`                                                                    | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured `@shadcn/lint` for agent verification of design tokens and contracts. |
| **10. Docker & Reverse Proxy**       | `Dockerfile`, `docker-compose.prod.yml`, `nginx-site.conf`, `.dockerignore`                            | `[IMPLEMENTED]` / `[UNTOUCHED]` | Standalone container, Traefik labels / Nginx HTTPS with Certbot SSL.             |
| **11. Husky Git Hooks**              | `.husky/commit-msg`, `.husky/pre-push`                                                                 | `[IMPLEMENTED]` / `[UNTOUCHED]` | Enforces dual pre-push test suite (Jest + Playwright) & commitlint.              |
| **12. Commitlint Config**            | `commitlint.config.mjs`                                                                                | `[IMPLEMENTED]` / `[UNTOUCHED]` | Configured `@commitlint/config-conventional`.                                    |
| **13. Release & CI Build Caching**   | `.github/workflows/release-please.yml`                                                                 | `[IMPLEMENTED]` / `[UNTOUCHED]` | Next.js build cache (.next/cache), SemVer release PRs & GHCR multi-arch pkg.     |
| **14. Environment Verification**     | `scripts/verify-project-config.ps1` / `.sh`                                                            | `[PASSED]`                      | Sanity check passed with zero errors.                                            |

#### Status Definitions:
- **`[IMPLEMENTED]`**: Freshly created, installed, or modified during this setup run.
- **`[UNTOUCHED]`**: Already properly configured prior to running the skill; preserved as-is.
- **`[SKIPPED]`**: Intentionally omitted based on user preference.