Community编程与开发github.com

new-page

在任意 Django + Wagtail 项目中构建新的 Wagtail 页面类型(详情页面及可选的索引/列表页面)。了解项目设置,向用户提问,展示计划等待确认,然后构建并对照性能与质量清单进行验证。当用户要求构建或添加页面类型时使用,例如“new-page events”、“让我们构建一个活动页面”或“添加一个新闻页面”。

new-page 是什么?

该技能旨在为 Wagtail 开发者提供一个自动化流程,用于在 Django + Wagtail 项目中创建新的页面类型。它会先检查 Wagtail 是否已安装并配置正确,然后通过分析项目结构(包括命令运行方式、设置文件、应用布局、模板和测试框架等)来学习项目配置。接着,它会向用户提出一系列关于页面字段、内容主体(富文本或 StreamField)、分类/标签、图片和文件等需求的定制化问题,并推荐最佳实践选项。在获得用户确认后,技能会生成完整的模型、模板、迁移和测试代码,并严格遵循一系列规则,如为每个字段设置 `verbose_name`、优化列表查询(使用 `select_related` 和 `prefetch_related`)、确保模板中无数据库查询,并生成包含固定查询计数验证的测试。整个过程包含五个阶段:检查 Wagtail、学习项目、提问、展示计划确认、构建与验证,最后还提供代码提交建议。该技能适用于 Claude Code、Cursor、Codex 等支持自定义技能的 AI 智能体平台。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MohammedAlrowais/wagtail-new-page-skill/tree/main/new-page

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

新的 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 — 提问

以用户能够快速回答的方式提问。如果你的环境有选择题工具(可点击选项),请使用它;否则以简短的编号消息提问。根据页面类型(活动需要日期和地点;新闻文章需要作者)和项目概况(例如,提议复用现有的代码片段)调整每个问题和选项。

需要涵盖的主题,每个都有建议的默认值:

  1. 字段 — 一项内容包含什么?(标题始终包含)
  2. 内容主体 — 简单的 RichTextField 或 StreamField
  3. 结构 — 根页面下的索引/列表页面,还是仅有页面
  4. 列表 — 过滤器(日期范围、分类、即将到来/过去、年份等)、搜索框。除非用户另有说明,否则每页显示 9 条。
  5. 分类/标签 — 代码片段(ForeignKey)或标签(ManyToMany)
  6. 图片和文件 — 主图?可下载的文档?
  7. 语言 — 用 _() 包装的标签(如果项目这样做,则为默认值)
  8. 应用 — 新应用(建议一个名称)或现有应用

提问风格:

  • 每次最多问 4 个问题,每个问题有 2–4 个选项。用户总可以用自己的话回答,因此不要添加“其他”选项。
  • 把推荐的选项放在第一位并标记为“(推荐)”。
  • 说明何时可以同时选择多个选项(字段、过滤器、块、额外功能)。

第一轮:默认值与否

首先编写一条简短消息,包含项目概况和你对全部 8 个主题的建议默认值。然后问一个问题:“对 <名称> 页面使用这些默认值?”并提供选项 使用默认值(推荐) 和 逐项回答。如果用户选择使用默认值,则直接进入阶段 3。

第二轮和第三轮

如果用户选择“逐项回答”:

  • 第二轮:主题 1–4(字段、内容主体、结构、列表)。
  • 第三轮:主题 5–8,以及依赖于第二轮回答的后续问题。例如:他们选择了 StreamField → 询问包含哪些块;他们选择了分类过滤器 → 询问是代码片段还是标签;他们选择了标签 → 询问是否按标签过滤。

如果一个主题需要比适配的更多选项(例如多于 4 个字段),则将它们分组为 2–3 个相关字段的选项(“日期和位置”、“图片 + 摘要”),而不是丢弃任何一个。

阶段 3 — 展示计划,等待确认

显示一个简短的计划:

  • 模型,包含每个字段:名称、类型、verbose_name、是否必填。
  • 管理面板及其分组。
  • 列表查询(select_related / prefetch_related 行)。
  • 需要创建或修改的文件。

在编写任何代码之前等待“是”(或修改意见)。

阶段 4 — 构建

按以下顺序创建或修改:

  1. 应用骨架(如果是新的),遵循项目的应用布局;按照现有本地应用的注册方式在 INSTALLED_APPS 中注册它。
  2. 代码片段、块、过滤器辅助函数、模型(规则如下)。
  3. 模板:详情页面、索引页面以及卡片局部模板,位于应用的 templates/<app_label>/ 文件夹中,扩展项目的基础模板并使用其 CSS 框架。
  4. 迁移:makemigrations <app_label>,然后 migrate。
  5. 测试(如果项目使用工厂,则包括工厂)。

模型规则

  • 每个字段都有一个 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 加上一个 alt CharBlock。
  • {% 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、未预取的相关查找)
8save() 副作用安全,或没有 save() 覆盖读取模型
9查询数量不随项目数量增长测试(如下)
10测试通过运行应用的测试,然后运行整个测试套件
11Lint 通过项目自己的 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
```

相关技能