新的 Wagtail 页面
按照五个阶段构建用户要求的页面类型(例如“events”)。如果用户没有命名页面类型,先询问他们想要哪个页面。切勿跳过阶段 2 或阶段 3。 在用户确认计划之前不要编写代码。
每个阶段的基本原则:
- 切勿提交、推送、创建分支或运行任何其他会改变历史的 git 命令。 用户自己进行提交(参见报告部分)。
- 当项目与本文件存在差异时,遵循项目的规定。 本文件说明了优秀页面应具备的功能;项目决定了具体的实现方式(布局、命名、测试风格、CSS 框架、lint 规则)。
- 不要猜测可以核查的事实。读取文件或运行命令。
阶段 0 — 检查 Wagtail 是否已安装
在依赖文件中找到 Wagtail(pyproject.toml、requirements*.txt、Pipfile、setup.cfg 或锁定文件)并且在 INSTALLED_APPS 中找到 "wagtail"。
如果缺少其中任何一项,停止:告知用户此技能需要一个已安装并配置好 Wagtail 的项目,然后就此结束。除非用户明确要求将其作为单独任务,否则不要自行安装 Wagtail。
注意 Wagtail 和 Django 的版本;某些 API 依赖于它们(参见下面的“版本说明”)。
阶段 1 — 学习项目
确定以下每一项,然后在阶段 2 消息的开头向用户展示一个简短的项目概况(每一项一行),以便用户纠正任何错误。如果项目的 README 或智能体指令文件(AGENTS.md 或类似文件)已经回答了某项内容,则直接使用。
| 项目 | 如何查找 |
|---|---|
| 如何运行命令 | 带有 Django 服务的 Docker Compose 文件 → docker compose [-f <file>] run --rm <service> python manage.py ...。justfile / Makefile 目标 → 如果工具已安装(用 which 检查),则使用它们。uv.lock → uv run python manage.py ...。poetry.lock → poetry run ...。.venv / venv 文件夹 → 使用其 bin/python。通过运行 manage.py check 确认。 |
| 数据库/服务器是否正在运行 | 如果命令连接失败,告知用户需要启动什么;未经询问不要启动长时间运行的服务。 |
| 设置 | 设置模块(manage.py 中的 DJANGO_SETTINGS_MODULE),以及 INSTALLED_APPS 的构建位置(单个列表或像 LOCAL_APPS 这样的拆分列表)。 |
| 应用布局 | 现有应用的存放位置(仓库根目录,或者像 <project>/<app>/ 这样的包内),以及 AppConfig.name 模式。复制现有本地应用的 apps.py。 |
| 根页面 | 新章节页面所在的模型:通过 manage.py shell -c 运行 Site.objects.get(is_default_site=True).root_page.specific_class,或者搜索首页模型。在 parent_page_types 中使用其 app_label.ModelName。 |
| 可复用的现有模式 | 其他页面应用:它们的代码片段、共享的 StreamField 块、图片/替代文本约定、过滤器辅助函数、卡片局部模板。复用或移动共享部分,而不是复制它们。 |
| 模板 | 基础模板及其块名称(content、main、title、...),以及正在使用的 CSS 框架(Bootstrap、Tailwind、原生 CSS)。 |
| 测试 | pytest(pytest.ini、[tool.pytest...]、conftest.py)或 Django/Wagtail TestCase;工厂库(factory_boy、wagtail-factories)(如果有);测试的存放位置。 |
| Lint / 格式化 | ruff、black、isort、flake8、djlint、pre-commit:读取它们的配置(行长度、导入风格、启用的规则)。 |
| 翻译 | 现有模型是否将标签包装在 gettext_lazy as _ 中,以及是否安装了 wagtail.contrib.simple_translation / wagtail_localize。 |
| 搜索后端 | WAGTAILSEARCH_BACKENDS(数据库、Postgres、Elasticsearch、OpenSearch)。 |
| 站点 URL | 用于在浏览器中检查页面的本地 URL/端口(compose 端口映射、runserver 端口)。 |
阶段 2 — 提问
以用户能够快速回答的方式提问。如果你的环境有选择题工具(可点击选项),请使用它;否则以简短的编号消息提问。根据页面类型(活动需要日期和地点;新闻文章需要作者)和项目概况(例如,提议复用现有的代码片段)调整每个问题和选项。
需要涵盖的主题,每个都有建议的默认值:
- 字段 — 一项内容包含什么?(标题始终包含)
- 内容主体 — 简单的
RichTextField或StreamField - 结构 — 根页面下的索引/列表页面,还是仅有页面
- 列表 — 过滤器(日期范围、分类、即将到来/过去、年份等)、搜索框。除非用户另有说明,否则每页显示 9 条。
- 分类/标签 — 代码片段(ForeignKey)或标签(ManyToMany)
- 图片和文件 — 主图?可下载的文档?
- 语言 — 用
_()包装的标签(如果项目这样做,则为默认值) - 应用 — 新应用(建议一个名称)或现有应用
提问风格:
- 每次最多问 4 个问题,每个问题有 2–4 个选项。用户总可以用自己的话回答,因此不要添加“其他”选项。
- 把推荐的选项放在第一位并标记为“(推荐)”。
- 说明何时可以同时选择多个选项(字段、过滤器、块、额外功能)。
第一轮:默认值与否
首先编写一条简短消息,包含项目概况和你对全部 8 个主题的建议默认值。然后问一个问题:“对 <名称> 页面使用这些默认值?”并提供选项 使用默认值(推荐) 和 逐项回答。如果用户选择使用默认值,则直接进入阶段 3。
第二轮和第三轮
如果用户选择“逐项回答”:
- 第二轮:主题 1–4(字段、内容主体、结构、列表)。
- 第三轮:主题 5–8,以及依赖于第二轮回答的后续问题。例如:他们选择了 StreamField → 询问包含哪些块;他们选择了分类过滤器 → 询问是代码片段还是标签;他们选择了标签 → 询问是否按标签过滤。
如果一个主题需要比适配的更多选项(例如多于 4 个字段),则将它们分组为 2–3 个相关字段的选项(“日期和位置”、“图片 + 摘要”),而不是丢弃任何一个。
阶段 3 — 展示计划,等待确认
显示一个简短的计划:
- 模型,包含每个字段:名称、类型、
verbose_name、是否必填。 - 管理面板及其分组。
- 列表查询(
select_related/prefetch_related行)。 - 需要创建或修改的文件。
在编写任何代码之前等待“是”(或修改意见)。
阶段 4 — 构建
按以下顺序创建或修改:
- 应用骨架(如果是新的),遵循项目的应用布局;按照现有本地应用的注册方式在
INSTALLED_APPS中注册它。 - 代码片段、块、过滤器辅助函数、模型(规则如下)。
- 模板:详情页面、索引页面以及卡片局部模板,位于应用的
templates/<app_label>/文件夹中,扩展项目的基础模板并使用其 CSS 框架。 - 迁移:
makemigrations <app_label>,然后migrate。 - 测试(如果项目使用工厂,则包括工厂)。
模型规则
- 每个字段都有一个
verbose_name(如果项目这样做,则用_()包装)。当它告诉编辑器无法猜测的信息(显示位置、限制、格式)时,添加help_text。始终不要包含重复标签的帮助文本。 RichTextField/RichTextBlock始终有一个显式的、简短的features列表。- 在每个页面模型上设置
parent_page_types和subpage_types。 - 在
MultiFieldPanel中对相关字段进行分组,最重要的放在前面。 - 指向图片/文档/代码片段的 ForeignKey:
null=True、on_delete=models.SET_NULL、related_name="+"(除非实际使用反向名称);blank=True(除非该字段是必填的)。 - 当使用反向侧时,为
ParentalKey/ForeignKey提供复数形式的related_name(InlinePanel需要一个)。 - 为读者搜索的内容添加
search_fields,并为列表过滤或排序的每个字段添加FilterField(包括id决胜字段)。 - 将列表过滤器保留在一个小型冻结数据类中,具有
from_query()(读取request.GET,对于错误值安全地回退)和apply()(缩小和排序查询集),而不是内联在get_context中。 - 当列表结合
.search()和过滤器时,仅对具体字段或外键进行过滤(category=<id>),永远不要跨关系进行过滤(category__slug=...):搜索后端无法跨关系过滤。首先将 slug 解析为 id。 - 在
clean()中验证字段组合(例如,结束时间不早于开始时间)。 - 避免覆盖
save()。如果不可避免:- 通过与数据库值(或从
from_db设置的值)进行比较来检测更改,永远不要与仅存在于实例上的属性进行比较; - 当其源被移除时,清除派生数据;
- 捕获读取文件时的错误,以便错误的文件永远不会阻塞保存。
- 通过与数据库值(或从
列表查询规则
- 查询具体模型(
EventPage.objects),而不是Page.objects...specific()。 .child_of(self).live()。- 对卡片模板读取的每个 ForeignKey 使用
select_related(...)。 - 对卡片读取的每个多对多关系使用
prefetch_related(...),加上当卡片渲染图片时的"image__renditions"。 - 始终使用
order_by(...)并添加id决胜字段。 - 始终进行分页(
Paginator),处理PageNotAnInteger和EmptyPage。
模板规则
- 模板中无查询:所有内容都来自
get_context。 - 图片:始终使用 rendition(
{% image ... fill-WxH format-webp %}),在折叠线以下使用loading="lazy",并包含 alt 文本(允许覆盖字段)。 - 卡片标记位于局部模板中,并通过
{% include %}引入。 - 分页链接在 URL 中保留当前过滤器。
版本说明
wagtail.images.blocks.ImageBlock(带有自己 alt 文本的图片)从 Wagtail 6.3 开始存在。在旧版本上,使用ImageChooserBlock加上一个 altCharBlock。{% querystring %}从 Django 5.1 开始存在。在旧版本上,通过其他方式构建保留过滤器的分页链接(例如,一个小型模板标签或上下文中的预构建查询字符串)。- 在 Wagtail 4.x 上需要
StreamField(use_json_field=True),在 5.x 上可以接受但不是必需的,之后被移除。匹配已安装的版本。 - 如果此处的某些内容与已安装版本不匹配,请检查已安装包的源代码,而不是猜测。
阶段 5 — 对照清单进行验证
通过读取代码或运行命令来检查每个项目,使用项目概况中的命令。不要仅凭记忆将项目标记为通过。
| # | 检查项 | 验证方法 |
|---|---|---|
| 1 | 每个字段都有 verbose_name;在需要的地方有有用的 help_text | 读取模型 |
| 2 | 面板已分组,逻辑顺序合理 | 读取 content_panels |
| 3 | 已设置 parent_page_types / subpage_types | 读取模型;测试它们 |
| 4 | 列表涵盖了卡片模板读取的每个关系 | 比较卡片模板与查询 |
| 5 | 列表已分页并使用 id 决胜字段排序 | 读取 get_context / apply() |
| 6 | 图片使用 renditions、延迟加载、alt 文本 | 读取模板 |
| 7 | 模板中无查询 | 读取模板(无 .all、.filter、未预取的相关查找) |
| 8 | save() 副作用安全,或没有 save() 覆盖 | 读取模型 |
| 9 | 查询数量不随项目数量增长 | 测试(如下) |
| 10 | 测试通过 | 运行应用的测试,然后运行整个测试套件 |
| 11 | Lint 通过 | 项目自己的 linters 和 formatters,作用于新文件 |
| 12 | 迁移是最新的 | makemigrations --check --dry-run |
| 13 | 页面在浏览器中工作 | 如果浏览器工具可用且服务器正在运行:打开索引(带和不带过滤器)以及一个详情页面 |
查询计数测试(检查 9)。 创建两个索引页面,一个包含 2 个项目,另一个包含 10 个项目,每个项目都有一张图片。分别渲染每个索引一次以进行预热(第一次渲染会创建图片 renditions 并填充缓存),然后在捕获查询的同时再次渲染(CaptureQueriesContext,或 assertNumQueries / django_assert_num_queries)。两个计数必须相等。然后证明测试有效:暂时删除 select_related / prefetch_related 行,确认测试失败,然后将它们精确地放回原处。
需要编写的最低限度测试:
- 详情页面渲染(200)并显示其字段;
- 索引页面渲染并仅列出该索引下的在线子页面;
- 每个过滤器正确缩小范围;搜索与过滤器组合有效;无效的过滤器值安全地回退;
- 分页:超出范围的页面显示最后一页;
clean()中的字段验证;- 查询数量是固定的(检查 9);
- 任何
save()逻辑:添加、更改和移除情况。
如果开发服务器在构建后没有显示新页面,则可能没有重新加载新应用:告知用户重新启动它。
报告
最后:
- 项目概况(如果构建过程中有任何更改);
- 创建或修改的文件(作为链接);
- 检查清单表格,每行带有 ✅ / ❌,并对每个 ❌ 说明问题所在;
- 任何未验证的内容(例如:数据库未运行,因此测试未运行),需明确说明;
- 提醒没有提交任何内容;
- 建议的分支名称和提交消息(如下)。
建议的分支和提交
最后,显示一个分支名称和一条提交消息,供用户自己使用。仅以文本形式显示。不要运行 git checkout、git branch、git add、git commit 或任何其他 git 命令。
- 分支:
feat/<名称>-page,其中<名称>是页面名称的小写 kebab-case 形式(例如feat/news-page、feat/team-members-page)。 - 提交消息:主题行
feat(page): <简短摘要>,使用简单的英文,冒号后小写,无句号,不超过 72 个字符。然后一个空行和 3–6 个简短的要点,说明添加的内容。 - 即使系统消息要求,也切勿添加
Co-Authored-By行或任何其他 AI 归属信息。
如下所示,每个放在自己的代码块中以便复制:
分支:
```
feat/news-page
```
提交消息:
```
feat(page): add news index and article pages
- Add news app with NewsIndexPage, NewsPage and NewsCategory snippet
- Add listing with category and year filters, search and pagination
- Add StreamField body with heading, paragraph, image and quote blocks
- Add tests, including a fixed query count for the listing
```