# wp-theme

**Repository Path**: sliver-ring_admin/wp-theme

## Basic Information

- **Project Name**: wp-theme
- **Description**: WordPress快速启动架构模版。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-07-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WordPress Bootstrap 主题快速启动模板

这是给没有技术背景的用户准备的 WordPress 独立主题模板。

它的目标不是从零重写 WordPress，也不是把所有东西塞进 `functions.php`，而是先给 AI 一套清楚、稳定、符合 WordPress 规矩的主题工程骨架：模板层级、Bootstrap 5、Composer、provider 架构、CMB2 后台选项、内容模型、接口、查询、数据表边界、初始化向导和静态门禁都已经放好。

本仓库定位为 Git 管理、自托管 WordPress 项目的 AI 开发启动模板，不宣称已经满足 WordPress.org 官方主题目录的全部审核要求。若要提交官方目录，必须针对当时生效的目录规则单独审计主题功能边界、依赖、隐私、许可、可访问性和打包内容。

## 加入交流群

如果你在模板初始化、WordPress 安装或 AI 开发规则方面遇到问题，可以扫码加入交流群。

![甲壳虫 Agent-vibe coding 编程交流 3 群二维码](./docs/assets/wechat-group-qr.jpg)

二维码在 2026 年 7 月 26 日前有效。过期后请回到项目发布页获取最新入口，或联系项目维护者。

## 怎么用

1. 先把完整仓库文件夹交给 AI，发送下方的初始指令。用户只回答站点、内容和风格问题，不需要自己判断 PHP、Composer、REST、SQL 或 Git。
2. 仓库是 AI 开发源模板；`dist/wp-bootstrap-theme-template.zip` 是已排除 AI 文档和开发工具的最小 WordPress 运行时安装包。
3. 安装环境需要 WordPress 7.0+、PHP 8.3+ 和可用数据库，正式站必须使用当前 WordPress 和仍接收安全更新的 PHP 补丁版本。准备和验收由 AI 或技术执行者按 `dev-docs/首次启动与验收.md` 完成。
4. 在 WordPress 后台上传运行时 ZIP，进入“外观 -> 主题”启用 `WP Bootstrap Theme Template`。
5. 把这个目录交给 AI 时，先让 AI 阅读：

```text
请先阅读 AGENTS.md、AI_TEMPLATE_INIT.md 和 dev-docs/ 下的全部真源文档。我不懂技术，请只问我能用业务语言回答的问题，技术方案、安全、Git、打包和验收由你负责判断并给出证据。

如果 AI_TEMPLATE_INIT.md 还存在，说明这是首次初始化。请按向导问我站点、用户、风格、内容、业务操作和验收结果，再由你映射内容模型、后台、接口、数据表和插件边界。必须填完并让我确认 dev-docs/项目定义.md 和 dev-docs/设计规范.md，替换所有初始化占位页面，通过静态和真实 WordPress 验收后才能删除向导。

不得要求我在聊天中粘贴真实密码、API key、token、私钥、数据库备份或未脱敏生产日志。未经我明确同意，不得 commit、push、发布或对生产数据执行任何写操作。
```

## 已包含

- WordPress 独立主题必需入口：`style.css`、`functions.php`。
- WordPress 主题预览图：`1200x900` 的 `screenshot.png`。
- Composer 工程元数据：`composer.json`，PSR-4 命名空间为 `Sliver\WpBootstrapTheme\`，源码映射到 `inc/src/`。
- CMB2 后台字段库：通过 Composer 引入 `cmb2/cmb2`，安装到 `inc/vendor/cmb2/cmb2/`。
- 已生成 Composer autoload：`inc/vendor/autoload.php`，直接复制到 WordPress 也能加载主题类。
- 常用模板层级：首页、文章列表、文章页、页面、归档、搜索、404、兜底模板。
- Bootstrap 5.3.8：已下载到 `assets/vendor/bootstrap/`，通过 WordPress enqueue 加载本地文件，并通过 SHA-256 门禁防止静默替换。
- 轻量主题样式：`assets/css/theme.css`。
- 轻量交互入口：`assets/js/theme.js`。
- 面向对象主题启动：`inc/src/Theme.php` 作为 provider kernel，`inc/src/Support/HookRegistry.php` 统一封装 WordPress hook，功能模块通过 `ServiceProvider` 扩展。
- 产品级扩展目录：`Admin`、`ContentTypes`、`Taxonomies`、`Meta`、`Rest`、`Queries`、`Database`。
- 可复用模板片段：`template-parts/`。
- AI 开发规则：`AGENTS.md`、`AI_TEMPLATE_INIT.md`、`dev-docs/`。
- 静态门禁：`scripts/check-template-guardrails.mjs`。
- WordPress Coding Standards：`phpcs.xml.dist` + Composer `require-dev`。
- 可上传的最小运行时 ZIP：`composer package` 生成 `dist/wp-bootstrap-theme-template.zip` 和同名 `.sha256` 校验文件，不包含 AI 真源和开发工具。
- GPL 许可和第三方依赖说明：`LICENSE`、`THIRD_PARTY_NOTICES.md`。

## 目录说明

```text
wp-theme/
├── AGENTS.md
├── AI_TEMPLATE_INIT.md
├── README.md
├── dev-docs/
├── assets/
│   └── vendor/bootstrap/
├── inc/
│   ├── src/
│   │   ├── Contracts/
│   │   ├── Support/
│   │   ├── Setup/
│   │   ├── Assets/
│   │   ├── Admin/
│   │   ├── ContentTypes/
│   │   ├── Taxonomies/
│   │   ├── Meta/
│   │   ├── Rest/
│   │   ├── Queries/
│   │   ├── Database/
│   │   └── View/
│   └── vendor/
├── template-parts/
├── scripts/
├── composer.json
├── style.css
├── functions.php
├── header.php
├── footer.php
├── front-page.php
├── home.php
├── single.php
├── page.php
├── archive.php
├── search.php
├── 404.php
└── index.php
```

`wp-theme/` 本身就是主题根目录，不要再套一层 `theme/` 或 `wp-theme-template/`。

## 验收

在 `wp-theme/` 目录下运行：

```sh
composer check
```

如果后续新增或移动 `inc/src/` 下的类，再运行：

```sh
composer dump-autoload
```

本模板只使用 Composer autoload，不保留第二套 `inc/src/autoload.php`。

## 怎么让 AI 长功能还不乱

新增功能时不要改 `functions.php`，不要在模板文件里写 hook、REST route、SQL，也不要把逻辑塞进 `header.php`、`single.php` 这类模板。

正确方式是：

1. 在 `inc/src/` 下按功能建目录。
2. 新建一个 `XxxServiceProvider`，实现 `Sliver\WpBootstrapTheme\Contracts\ServiceProvider`。
3. 在 provider 里通过 `HookRegistry` 注册需要的 action/filter。
4. 把 provider 加到 `inc/src/Theme.php` 的 provider 列表。
5. 新增或移动 PHP 类后运行 `composer dump-autoload`，然后运行 `composer check`。

常见 owner：

- CPT：`inc/src/ContentTypes/`
- 后台选项/CMB2：`inc/src/Admin/`
- taxonomy：`inc/src/Taxonomies/`
- 字段：`inc/src/Meta/`
- REST API：`inc/src/Rest/`
- 复杂查询：`inc/src/Queries/`
- 自定义表和 repository：`inc/src/Database/`

通过时会看到：

```text
WordPress Bootstrap theme template guardrails passed.
```

生成 WordPress 后台可直接上传的最小运行时包：

```sh
composer package
```

准备 commit、push 或对外发布时，按 `dev-docs/版本与发布规范.md` 由 AI 执行 `composer audit:security`、`composer check`、真实 WordPress 验收和 `composer release`。用户只确认业务效果和是否同意发布。

`composer release` 最后会把源码中的 `inc/vendor/` 收敛为可直接运行的生产依赖，避免提交本机 PHPCS/WPCS 工具链。再次开发前运行 `composer install` 即可恢复开发依赖；改完后必须重新走完整发布流程。

静态检查不能替代真实 WordPress 后台启用和前台预览，真实验收按 `dev-docs/首次启动与验收.md` 执行。