BIGboss248/nextjs-wordpress

通用仓库设置与环境技能 (setup-repository)

此技能为任何软件仓库建立、配置并验证标准开发环境。它处理项目元数据发现、Git 卫生、集成 codebase-memory-mcp 的代码智能（在工作空间和全局配置，仅限 Google Antigravity / AGY）、使用 Husky & Commitlint 实现提交标准化、生产级 Docker 容器化以及自动化 Release Please 与多架构 GHCR CI/CD 部署。

---

工作流概览

flowchart TD
    A["1. 自动化发现与零中断扫描"] --> B["2. 项目元数据事实源 (docs/project.json)"]
    B --> C["3. 代码库内存 MCP 设置 (工作空间与 AGY 全局)"]
    C --> D["4. Git 钩子与 Commitlint 配置"]
    D --> E["5. 生产级 Docker 与 Compose 堆栈"]
    E --> F["6. Release Please 与多架构 GHCR CI/CD"]
    F --> G["7. 环境健全性验证"]
    G --> H["8. 标准化执行报告与 Git 指导"]

---

步骤 1：自动化发现与仓库扫描（零中断规则）

[!IMPORTANT] 如果仓库文件中已有信息，请勿提示用户。 首先扫描仓库文件、配置和 docs/ 中的文档。自动推断运行时、工具和约定。仅在缺少或模糊的配置时提示用户。

1.1. 自动化检查（零中断规则）

1. 检测框架与运行时：
   • 检查包清单：package.json (Node/Bun)、pyproject.toml / requirements.txt (Python)、Cargo.toml (Rust)、go.mod (Go) 等。
   • 从锁文件检测包管理器：
     • pnpm-lock.yaml → pnpm
     • bun.lockb / bun.lock → bun
     • yarn.lock → yarn
     • package-lock.json → npm
2. 扫描现有文档：
   • 读取 CONTEXT.md、docs/plan.md、docs/adr/*.md 和 README.md，提取架构标准、测试套件和语言约定。
3. 验证 Git 工作树：
   • 检查 Git 状态和分支。所有检查与命令步骤必须作为离散的单个操作执行，不进行链接。

1.2. 交互式澄清（AI 辅助搭建）

如果任何关键参数缺失、模糊或无法从现有文件中确定，请使用清晰的选项向用户提出有针对性的问题：

### 📋 仓库设置与 CI/CD 配置

要为此仓库配置标准 CI/CD 工作流，请确认或指定以下内容：

1. **主要语言与运行时**：（例如，Node.js / TypeScript、Python、Go、Rust、Java、C++）
2. **测试命令**：（例如，`pnpm test`、`pytest`、`cargo test`、`go test ./...`）
3. **构建命令**：（例如，`pnpm run build`、`cargo build --release`、`go build`、`none`）
4. **发布/发布目标**：
   - [ ] Docker 容器镜像 (GHCR / Docker Hub)
   - [ ] 包注册表 (npm、PyPI、Crates.io、Maven)
   - [ ] 二进制发布资产 (GitHub Releases)
   - [ ] 静态站点 / 文档 (GitHub Pages)
   - [ ] 无（仅 CI 测试与 SemVer Git 标签）

---

步骤 2：项目元数据事实源 (docs/project.json)

维护一个中心化的机器可读配置文件 docs/project.json，使所有 AI 代理和专业技能共享相同的上下文。

标准 docs/project.json 模板：

{
  "project_context_and_metadata": {
    "project_name": "my-project",
    "runtime": "node",
    "package_manager": "pnpm",
    "source_dir": "src",
    "test_command": "pnpm test",
    "build_command": "pnpm run build",
    "testing_library": ["jest", "playwright"],
    "containerization": "docker-standalone",
    "ci_cd_provider": "github-actions",
    "release_automation": "release-please",
    "publish_target": "container"
  }
}

1. 确保 docs/ 目录存在。
2. 使用已发现或已确认的配置值写入或更新 docs/project.json。

---

步骤 3：设置 codebase-memory-mcp 代码智能服务器

为仓库配备 codebase-memory-mcp 持久知识图谱服务器（支持 162 种语言、Tree-sitter AST、混合 LSP 语义类型解析以及 100% 本地向量搜索）。

3.1. 安装二进制文件

选择平台方法：

• Windows (PowerShell)：

  Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
  Unblock-File .\install.ps1
  .\install.ps1
  Remove-Item .\install.ps1
  

• macOS / Linux (Bash)：

  curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
  

• 全局 npm 包替代方案：

  npm install -g codebase-memory-mcp@latest
  

3.2. 注册 MCP 服务器（仅工作空间与 AGY 全局）

[!IMPORTANT] 全局 MCP 注册仅适用于 Antigravity (AGY)。 Antigravity 发现并加载主机系统上全局配置的 MCP 服务器。切勿为其他编码代理（例如 Claude Desktop、Cursor、VS Code、Cline）全局配置或注册 MCP 服务器。在以下位置注册 MCP 服务器：

1. 工作空间根目录下的 mcp.json：

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

2. 工作空间代理配置 (.agents/mcp_config.json)（如果仓库使用 .agents/）：

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

3. 全局主机配置（仅 Google Antigravity / AGY）： 严格将 codebase-memory 添加到 AGY 主机配置中：
   • ~/.gemini/antigravity/mcp_config.json
   • ~/.gemini/config/mcp_config.json （请勿在 Claude Desktop、Cursor 或其他编码代理中注册）：

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

3.3. 配置 .cbmignore 排除规则（防止编辑器卡顿与发现波动）

• 仅本地（默认）：将 .codebase-memory/ 添加到 .gitignore。

[!IMPORTANT] 卡顿预防与高波动排除 (.cbmignore)： codebase-memory-mcp 会读取一个严格位于仓库根目录 (<repo>/.cbmignore) 的 .cbmignore 文件，使用 .gitignore 语法。没有 .cbmignore，非代码文件（如规划文档、代理记忆、测试产物和构建缓存）会在每次编辑时触发持续的 AST 发现、类型解析和磁盘写入。 始终在仓库根目录生成 <repo>/.cbmignore：

# codebase-memory-mcp 忽略规则 (.cbmignore)
# 防止非代码和高波动文件触发图索引或膨胀 AST 图。

# 代理日志、元数据和规划文档（活跃会话期间高波动）
.agents/
docs/
*.md

# 构建产物与编译缓存
dist/
build/
out/
.next/
.swc/

# 测试、报告和覆盖率
coverage/
test-results/
playwright-report/
blob-report/
.playwright-mcp/
storybook-static/
*storybook.log

# 代码库内存本地产物（防止自触发循环）
.codebase-memory/

# 系统和日志
*.log
*.tsbuildinfo
.DS_Store

# 静态资产和媒体（零代码符号）
public/
assets/
*.png
*.jpg
*.jpeg
*.gif
*.svg
*.ico
*.webp
*.mp4
*.mp3
*.pdf

# 环境变量与锁文件
.env*
*.pem
*.lock
pnpm-lock.yaml
package-lock.json
yarn.lock
bun.lockb

3.4. 禁用自动会话文件监视 (auto_watch = false)

[!CAUTION] 系统卡顿预防： 默认情况下，codebase-memory-mcp 会自动将已连接的项目注册到其后台 Git 监视器 (auto_watch = true)。在 Windows 和多任务系统上，监视器会检测文件保存，生成一个 index.supervisor 工作进程，并在每次按键/保存时通过 zstd 压缩 .codebase-memory/graph.db.zst，导致严重的编辑器 UI 和窗口管理器微卡顿。 始终在全局禁用自动会话监视：

codebase-memory-mcp config set auto_watch false

禁用后，会话不会注册到后台监视器，从而完全消除编辑器冻结。图通过 MCP 工具查询，并根据需要显式按需刷新。

3.5. Git 卫生与持久化

• 仅本地（默认）：将 .codebase-memory/ 添加到 .gitignore。切勿在每次保存时提交二进制产物。
• 团队快照共享：如果打算为团队提交预索引的图快照，请在根目录的 .gitattributes 中使用 Git LFS 跟踪 .codebase-memory/graph.db.zst：

  .codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text
  

3.6. 初始按需索引与节奏脚本

1. 按需运行初始索引（使用 moderate 或 fast 模式以跳过繁重的语义嵌入计算）：

   codebase-memory-mcp cli index_repository --repo-path "<规范仓库路径>" --mode moderate
   

2. 在 package.json 中添加一个节奏脚本，用于在主要里程碑/提交时刷新索引：

   {
     "scripts": {
       "cbm:update": "codebase-memory-mcp cli index_repository --repo-path . --mode moderate --persistence true"
     }
   }
   

---

步骤 4：使用 Husky 与 Commitlint 设置 Git 钩子

强制约定式提交，确保测试套件在代码推送到远程分支之前执行。

1. 安装开发依赖：

   pnpm add -D husky @commitlint/cli @commitlint/config-conventional
   

2. 配置 commitlint.config.mjs：

   export default {
     extends: ["@commitlint/config-conventional"],
   };
   

3. 初始化 Husky：

   pnpm exec husky init
   

4. 配置 commit-msg 钩子：

   echo "pnpm exec commitlint --edit \$1" > .husky/commit-msg
   

5. 配置 pre-push 钩子： 在允许任何 git push 之前强制执行测试套件：

   echo "pnpm run test:all" > .husky/pre-push
   

   [!NOTE] 确保 package.json 中的测试脚本包含优雅的标志（例如 --passWithNoTests），以便没有测试文件的仓库以退出代码 0 退出，而不是破坏推送。切勿在工作空间中创建示例/虚拟测试文件。

---

步骤 5：设置多阶段生产级 Docker 容器化

配置容器化严格用于独立生产构建和部署。本地开发使用项目本机包管理器在主机上运行。

5.1. 配置 .dockerignore

排除本地产物、Git 历史和机密：

node_modules/
.pnp/
.pnpm-store/
dist/
build/
coverage/
test-results/
.env*
*.log
.git/
.dockerignore
Dockerfile*
docker-compose*.yml
.codebase-memory/

5.2. 多阶段 Dockerfile

创建一个 3 阶段的多阶段构建（dependencies → builder → runner），在安全的非 root 用户下运行：

ARG NODE_VERSION=22-slim

FROM node:${NODE_VERSION} AS dependencies
WORKDIR /app
ENV CI=true
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
  if [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm install --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  else yarn install --frozen-lockfile; fi

FROM node:${NODE_VERSION} AS builder
WORKDIR /app
COPY --from=dependencies /app/node_modules ./node_modules
COPY . .
ENV NODE_ENV=production
RUN if [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; else npm run build; fi

FROM node:${NODE_VERSION} AS runner
WORKDIR /app
ENV NODE_ENV=production
ARG PORT=3000
ENV PORT=${PORT}
ENV HOSTNAME="0.0.0.0"
COPY --from=builder --chown=node:node /app/dist ./dist
USER node
EXPOSE ${PORT}
CMD ["node", "dist/index.js"]

5.3. Docker Compose 堆栈

1. 本地构建与测试 (docker-compose.yml)：

   services:
     app:
       build:
         context: .
         dockerfile: Dockerfile
       container_name: app-production
       restart: unless-stopped
       ports:
         - "${PORT:-3000}:${PORT:-3000}"
       environment:
         - NODE_ENV=production
   

2. 生产级预构建堆栈 (docker-compose.prod.yml)： 直接从 GHCR 拉取预构建的多架构镜像，无需源代码：

   services:
     app:
       image: ghcr.io/<小写所有者>/<小写仓库>:${IMAGE_TAG:-latest}
       container_name: app-production
       restart: always
       ports:
         - "${PORT:-3000}:${PORT:-3000}"
       environment:
         - NODE_ENV=production
   

---

步骤 6：设置信用优化的 CI/CD 与 Release Please 自动化

通过 .github/workflows/release-please.yml 自动化语义发布、变更日志和多架构（AMD64 和 ARM64）GitHub 容器注册表发布：

核心 DevOps 设计规则：

1. 自动化测试门禁：在拉取请求和提交到 main 分支时运行项目测试。
2. Release Please 自动化：自动化版本提升、变更日志和发布拉取请求。
3. concurrency.cancel-in-progress: false：切勿取消正在进行的发布工作流或主分支部署。
4. 两阶段多架构矩阵构建器：在原生运行器机器（ubuntu-latest 和 ubuntu-24.04-arm）上构建 AMD64 和 ARM64，无需 QEMU 模拟。按摘要推送镜像。
5. 摘要清单合并：下游的 merge-manifest 作业将 AMD64 和 ARM64 摘要缝合到统一的多架构标签中。
6. 小写仓库名称：始终通过 lowercase(repository_owner) + "/" + lowercase(repository_name) 在 Workflow 级别将 github.repository 转换为小写。

6.1. 工作流文件配置

name: Release Please & Multi-Arch Container

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository_owner && format('{0}/{1}', lower(github.repository_owner), lower(github.event.repository.name)) || 'local/dev' }}
  # 未设置时使用 "dev" 作为默认标签，避免 "latest" 污染
  TAG: ${{ github.ref_type == 'tag' && github.ref_name || (github.event_name == 'pull_request' && format('pr-{0}', github.event.number) || 'dev') }}
  GIT_SHA: ${{ github.sha }}

jobs:
  test:
    name: "测试门禁"
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
          cache: pnpm

      - name: 安装依赖
        run: |
          corepack enable pnpm
          pnpm install --frozen-lockfile

      - name: 运行测试
        run: pnpm run test:all || echo "警告：无测试脚本或测试失败，详细信息见上文"

  release-please:
    name: "Release Please"
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    outputs:
      release_created: ${{ steps.release.outputs.release_created }}
      tag_name: ${{ steps.release.outputs.tag_name }}
    needs: [test]
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

    steps:
      - id: release
        uses: googleapis/release-please-action@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          release-type: node

  build:
    name: "构建与推送 - ${{ matrix.arch }}"
    runs-on: ${{ matrix.os }}
    permissions:
      contents: read
      packages: write
    needs: [release-please, test]
    if: |
      (github.ref == 'refs/heads/main' && github.event_name == 'push') ||
      (github.event_name == 'pull_request')
    strategy:
      fail-fast: false
      matrix:
        include:
          - arch: amd64
            os: ubuntu-latest
          - arch: arm64
            os: ubuntu-24.04-arm

    steps:
      - uses: actions/checkout@v4

      - name: 登录到 GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: 设置 Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: 提取 Docker 元数据
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha,prefix=,suffix=-${{ matrix.arch }},format=short
            type=raw,value=${{ env.TAG }}-${{ matrix.arch }}

      - name: 保存摘要
        run: |
          echo "${{ steps.meta.outputs.tags }}" | tr ',' '\n' | head -1 | cut -d: -f2 > /tmp/digest.txt
          echo "摘要标签：$(cat /tmp/digest.txt)"

      - name: 构建并导出
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: 上传摘要
        uses: actions/upload-artifact@v4
        if: github.event_name != 'pull_request'
        with:
          name: manifest-digest-${{ matrix.arch }}
          path: /tmp/digest.txt

  merge-manifest:
    name: "合并多架构清单"
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    needs: [build]
    if: github.event_name != 'pull_request'

    steps:
      - uses: actions/checkout@v4

      - name: 下载摘要
        uses: actions/download-artifact@v4
        with:
          pattern: manifest-digest-*
          merge-multiple: true

      - name: 登录到 GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: 设置 Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: 创建并推送多架构清单
        run: |
          # 读取摘要
          AMD64_DIGEST=$(cat digest-amd64.txt 2>/dev/null || echo "")
          ARM64_DIGEST=$(cat digest-arm64.txt 2>/dev/null || echo "")

          # 创建……

---

步骤 7：环境健全性验证

确保所有已配置的工具和设置正常运行。

1. 依赖检查：验证所有 npm 包正确安装。
2. Docker 构建测试：运行 docker build 确保镜像成功构建。
3. Git 钩子验证：测试 commit-msg 和 pre-push 钩子按预期触发。
4. MCP 服务器连接测试：如果适用，验证 codebase-memory-mcp 服务器成功启动。

---

步骤 8：标准化执行报告与 Git 指导

生成一份总结性报告，详细说明所有已执行的步骤及其状态。

1. 报告格式：一份清晰的 Markdown 摘要，列出已成功配置的步骤和任何仍需手动干预的步骤。
2. Git 指导：提供清晰的操作说明，指导用户如何进行初始提交、推送以及后续如何利用 Release Please 工作流。

[!TIP] 完整报告应包括指向 .github/workflows/release-please.yml 和 docs/project.json 的链接，以便用户轻松访问关键配置。

---

故障排除与常见问题

问：我在 Windows 上遇到权限错误。

答：以管理员身份运行 PowerShell 或使用 WSL 2 以获得最佳兼容性。

问：为什么使用 codebase-memory-mcp？

答：它提供本地、私有的代码库智能，无需外部 API 调用，支持 162 种语言，并通过 Tree-sitter 和 LSP 集成实现精确的语义理解。

问：Release Please 发布失败。

答：验证 GitHub 令牌具有 contents: write 和 pull-requests: write 权限，并且仓库已启用 GitHub Actions。

问：如何自定义 Dockerfile？

答：您可以直接编辑 Dockerfile 以更改基础镜像、添加更多阶段或修改环境变量。

---

技能版本：1.0.0 | 作者：BIGboss248 | 许可证：MIT