strapi-product-builder

Strapi 产品构建器

一种结构化、以访谈为驱动的流程，可将产品创意转化为可直接构建的规格说明，适用于由 Strapi 提供支持的项目。输出为项目文件夹中的 6 个 Markdown 文件——最后一个文件详细到足以让任何编码 Agent（Claude Code、Cursor 等）立即开始构建 POC，并搭建好 Strapi 内容类型、API 路由和种子数据。

核心理念

商业价值驱动产品。产品驱动需求。需求驱动技术。

绝不要让技术选择走在前面。用户兴奋地说“我想用 Next.js 和 Supabase”，并不意味着他们已经决定要构建什么，也不意味着他们知道为什么有人会使用它。在讨论任何框架之前，要温和地引导他们回到价值和用户上。

如果用户试图直接跳到技术问题（“我的创意应该使用什么技术栈？”），先回应这个问题，并说明你会在第 4 阶段讨论——但首先需要了解产品、用户和需求，这样给出的技术建议才真正合适。然后从第 1 阶段开始。

此技能默认假定后端 / CMS 使用 Strapi v5。前端、托管和辅助服务仍是第 4 阶段需要解答的问题。如果用户有无法使用 Strapi 的硬性要求（例如，他们需要完全无服务器 / 仅边缘架构，或已确定使用另一个无头 CMS），应尽早指出这一点，然后调整方案，或建议他们改用更通用的产品设计技能。

使用 Strapi 文档

在推荐 Strapi API、插件模式、内容类型配置或迁移步骤之前，请以当前文档为依据——Strapi 的 API 和惯例会不断演进。

优先顺序：

1. Strapi Docs MCP——如果已连接名为 strapi-docs（或类似名称，例如 mcp__strapi-docs__*）的 MCP 服务，查询事实时优先使用它。每当用户询问“如何在 Strapi 中执行 X”，或你准备编写涉及 Strapi 内部机制的代码（生命周期、控制器、服务、策略、中间件、插件 SDK、内容类型架构、Document Service API 等）时，都应使用它。
2. 官方文档——如果没有可用的 MCP 服务，则访问 https://docs.strapi.io（v5 是当前主要版本）。使用 WebFetch 获取具体页面。
3. 此技能自身的 references/——对于会影响构建的具体细节，请查阅 references/strapi-build-cookbook.md（Strapi v5 中不太明显的陷阱）和其他参考文件，然后再参考官方文档。此技能是自包含的：仅引用官方 Strapi 来源（文档、官方博客文章、strapi/LaunchPad 等官方 starter），绝不依赖安装任何其他技能。第 6 阶段的规格说明必须始终能够独立使用——仅凭它和官方文档即可完成构建。

何时在输出文件中引用文档：只要第 5 或第 6 阶段提及不太明显的 Strapi 功能（生命周期、组件与动态区域、草稿与发布、i18n、RBAC、自定义字段、文档服务查询），就应添加相关文档页面的链接，以便之后的构建会话（无论由哪个编码 Agent 执行）在生成代码前核实 API 范围。经过筛选并标注功能标签的来源（官方文档、Strapi 博客教程、参考代码库）列于 references/resources.md 中——引用相应条目，并先依据当前文档重新核实任何博客教程中的具体命令 / 版本（教程内容可能已经过时）。

如果针对某个具体问题，MCP 和文档都无法访问，应在文件中明确说明（“实现前请对照 docs.strapi.io 验证”），而不是猜测。

Skill 文件夹结构

这个 Skill 以文件夹形式存在，而非单个文件。添加新的上下文（观点、代码参考、脚本、示例）时，请放入相应的子文件夹，而不要让 SKILL.md 变得臃肿。SKILL.md 应始终作为入口文件，保持足够简短，以便完整加载，并提供指向子文件夹的链接。

strapi-product-builder/
├── SKILL.md                    # this file — entry point, instructions, stage flow
├── references/                 # opinions, defaults, deeper guidance Claude reads on demand
│   ├── strapi-defaults.md      # the opinionated default stack and why
│   ├── strapi-cloud-deploy.md  # step-by-step Strapi Cloud deployment
│   ├── content-modeling.md     # collection vs single vs component vs dynamic zone, populate strategy
│   ├── frontend-frameworks.md  # the four first-class frontends + how to parameterize stages 5-6
│   ├── auth-better-auth.md     # plugin install + config + frontend wiring (beta — confirm first)
│   ├── docs-lookup.md          # how to use the strapi-docs MCP and docs.strapi.io
│   ├── strapi-build-cookbook.md # non-obvious Strapi v5 build traps (controllers, ownership, seeding) + doc links
│   ├── resources.md            # curated external refs (docs, Strapi blog tutorials, repos), capability-tagged
│   └── strapi-mcp-server.md    # built-in Strapi MCP server (v5.47+, GA since 5.49) — optional product capability
├── templates/                  # one .md per stage — the file templates the skill writes
│   ├── 01-product.template.md
│   ├── 02-users.template.md
│   ├── 03-requirements.template.md
│   ├── 04-tech-decisions.template.md
│   ├── 05-tech-requirements.template.md
│   └── 06-build-spec.template.md
├── examples/                   # filled-in example outputs from real or sample products
│   └── README.md
└── scripts/                    # optional helpers (e.g., scaffold the six output files)
    └── README.md

约定：

• 按需阅读 references/*，不要提前全部读取。当某个阶段涉及参考资料涵盖的主题时（例如，第 5 阶段需要制定内容填充策略），再打开 references/content-modeling.md。
• 模板是各阶段文件格式的唯一准则。SKILL.md 中的内嵌模板只是摘要；如果与 templates/ 中的模板冲突，以 templates/ 为准。
• 示例仅供参考，切勿逐字照搬。
• 要添加新观点？ 将其放入 references/，并从 SKILL.md 中相关阶段的章节链接到它。保持 SKILL.md 易于浏览。

如何运行此 Skill

这是一个高度依赖访谈的 Skill。每次只询问一个阶段的重点问题，等待回答，起草该阶段的 Markdown 文件，征得用户确认后再进入下一阶段。用户可以随时跳回修改任何先前的阶段；遇到这种情况时，请询问是否需要更新后续阶段以保持一致。

开始时，询问用户的产品名称（或暂定名称）。

界面适配——Claude Code、Claude Desktop、claude.ai 网页版

此 Skill 可在任何 Claude 界面中运行。检测当前可用的功能并调整输出方式，绝不要假设特定环境。

在第 1 阶段开始时、创建任何文件之前，选择输出模式：

界面	检测信号	输出模式
Claude Code	可使用 Write/Edit/Bash 工具	在 <cwd>/<product-name-kebab-case>/ 下创建实际文件夹（或询问用户希望放在哪里），并在其中写入六个 .md 文件。
Claude Desktop（带文件系统 MCP）	已连接文件系统 MCP 服务（例如 mcp__filesystem__*）	通过 MCP 将文件写入用户指定的文件夹。首次使用时，请用户确认路径。
Claude Desktop（不带文件系统 MCP）或claude.ai 网页版	仅有 artifacts / present_files / 内嵌显示功能	将每个阶段的内容作为 text/markdown 工件提供，供用户打开、编辑、复制或下载。告知用户如何在本地保存。共六个工件，每个阶段一个。

第 6 阶段规格说明的呈现——无论使用哪种界面，最终的 06-build-spec.md 都必须足够完整，让用户能够将其粘贴到任意编码 Agent（Claude Code、Cursor 等）的新会话中，并直接根据该文件和 Strapi 官方文档进行构建。

自包含的构建规格说明——此规格说明不得依赖安装任何其他 Skill。请具体描述每个构建步骤（命令、架构、配置），确保后续的编码 Agent 会话仅凭规格说明和 Strapi 官方文档即可执行。

查询 Strapi 文档适用于所有界面：

• 如果已连接 strapi-docs MCP，则使用它（Desktop 和 Code 均支持 MCP）。
• 否则，使用 WebFetch 访问 https://docs.strapi.io （Code 可用；Desktop 和网页版可使用同类的抓取工具或 web_search）。

语气：不要将这些分支选择暴露为需要用户配置的步骤，直接选择合适的模式并继续。只有在确实无法判断时才提问（例如：“我可以将这些内容写成当前文件夹中的文件，也可以将其作为工件呈现，供你复制——你更喜欢哪种方式？”）。

六个阶段

每个阶段在项目文件夹中都有一个固定文件名。默认情况下按顺序执行，但用户可以随时返回任一阶段。

#	Filename	Purpose
1	01-product.md	产品是什么，以及它带来的价值
2	02-users.md	谁在使用、如何使用，以及他们能获得什么成果
3	03-requirements.md	根据阶段 1 和 2 得出的功能需求
4	04-tech-decisions.md	根据需求展开的技术栈讨论
5	05-tech-requirements.md	详细技术规格——数据模型、API、组件
6	06-build-spec.md	可供任何编码 Agent 直接执行的 Markdown 文档

每个阶段结束后，使用上文选择的输出模式编写或呈现文件，向用户展示所记录内容的摘要，并询问：“这样看起来对吗？进入阶段 [下一阶段] 前，有什么需要修改的吗？”

用户确认后，通过适合当前界面的方式向他们提供文件：

• Claude Code / filesystem MCP：告知文件路径，他们可以打开。
• Artifacts 模式：制品已直接呈现在他们面前。
• 如果有 present_files，也可以使用。

然后开始下一阶段。

---

阶段 1——产品是什么？

目标：清晰定义产品及其价值，让任何阅读 01-product.md 的人都能立即理解它是什么，以及它为何重要。

本阶段不要讨论技术。 如果用户提到框架或托管方式，先记录下来留到阶段 4 讨论，并引导话题回到产品本身。

留意两类可能悄悄影响后续阶段的问题——现在就解决，不要拖到阶段 5：

• 范围矛盾——尤其是单用户与多租户/SaaS 之间的矛盾。“只是我自己用的工具”和“多个团队/组织/健身房使用，并采用白标形式”是不同的产品：多租户会要求阶段 5 中的每个实体都按租户隔离。如果用户的描述有所摇摆，要明确指出并确定 MVP 的范围。
• Strapi 适配性警示。 如果用户提出 Strapi v5 无法满足的硬性要求——例如使用文档型/NoSQL 数据库，如 MongoDB（Strapi 仅支持 SQL），或要求离线优先/仅限边缘运行——请在这里坦诚说明：要么调整约束，要么建议改用更通用的产品设计技能。不要将无法实现的假设带到阶段 4。

访谈问题（不要一次全部提问——每次问 2–3 个，等待回答后再继续追问）：

• 用一句话描述，这是什么产品？
• 它解决什么问题？解决谁的问题？
• 客户（或用户）能从中获得什么，而这是他们现在无法获得的？
• “前后对比”是什么——使用前后，某人的生活/工作会有什么变化？
• 这是工具、服务、市场、平台还是内容产品？（有助于明确其价值。）
• 一年后，怎样才算成功？（不是看指标，而是描述那时的情景。）

文件模板：根据 templates/01-product.template.md（权威来源）编写 01-product.md。章节：一句话描述 · 问题 · 价值 · 产品类别 · 成功的样子。

---

阶段 2 — 用户会如何使用它？

目标：梳理人的一面——用户是谁、他们想要完成什么（待办任务）、他们使用产品的历程，以及反复执行的核心操作（“循环”）。

**仍然不讨论技术。**本阶段关注人和成果。

梳理全部四个层面：**用户画像、用户历程、待办任务和核心循环。**通过提问来完善每个层面：

用户画像（MVP 有 1～3 个就足够了）：

• 主要用户是谁？为每个人提供姓名、角色和背景。
• 他们目前会用什么方式代替你的产品？
• 他们的技术熟练程度如何？

待办任务（针对每个用户画像）：

• 每个用户画像“雇用”这个产品来帮他们做什么？
• 这项任务会在他们一天或一周中的什么时候出现？

主要用户历程：

• 从用户发现产品到获得价值，会经历哪些步骤？请用户讲述整个过程。
• 他们首先会做什么？接下来呢？“顿悟”时刻是什么？

核心循环（让用户不断回来的重复操作）：

• 用户会反复执行什么操作？（例如，对于 Twitter：发布、浏览、回应。对于习惯追踪器：每天打卡。）
• 是什么让他们第二天再次回来？

文件模板：根据 templates/02-users.template.md 编写 02-users.md。章节：用户画像 · 待办任务 · 主要用户历程 · 核心循环。

---

阶段 3 — 功能需求

目标：将对产品和用户的理解转化为具体需求。产品需要做什么？

**仍然不涉及技术。**需求描述的是能力，而非实现方案。“系统必须允许用户通过电子邮件邀请团队成员”是一项需求。“使用 SendGrid 发送电子邮件”则是技术决策（阶段 4）。

直接根据阶段 1 和阶段 2 制定需求。针对用户旅程和核心循环中的每一项，思考：产品必须做什么才能实现这一点？

需要涵盖的类别：

• 核心功能 — 产品必须具备哪些功能才能让核心循环正常运作
• 账户/身份验证 — 注册、登录、身份（能力层面：“用户必须能够登录”，而非“使用 OAuth”）。注意：Strapi 内置了供终端用户使用的 Users & Permissions，以及独立的 Admin 身份验证 — 在此标明产品需要终端用户账户、仅限管理员编辑内容，还是两者都需要
• 产品管理的内容 — 从概念层面描述（例如“文章”“产品”“团队成员”）。区分编辑内容（由管理员在 Strapi 的 CMS 中管理）和用户生成内容（由终端用户通过 Strapi REST/GraphQL API 创建）。如果不清楚由谁编辑（简介只写了“编辑人员”），请依据 references/content-modeling.md 中的团队 → 管理面板，终端用户 → API规则来确定。暂时不要编写架构
• 可复用的内容模式 — 标注不同实体中重复出现的相同结构（英雄区块、SEO 区块、地址）——这些会成为 Strapi 组件。标注需要在同一位置容纳多种结构的情况（页面构建器、灵活布局）——这些会成为动态区域。目前仍只需描述能力层面
• 本地化与草稿 — 产品是否需要多语言内容（Strapi i18n）或草稿/发布工作流？在此记录是/否需求
• 所需集成 — 产品必须对接的第三方服务（在能力层面命名：“发送电子邮件”“处理付款”）
• AI / Agent 访问（MCP） — 产品是否需要 AI Agent 或 AI 驱动的功能来读取/写入其内容（助手、副驾驶、内容自动化）？Strapi 专门为此提供内置的 MCP 服务（自 v5.49 起正式发布）。在此记录是/否能力需求；技术决策留到阶段 4。参见 references/strapi-mcp-server.md
• 非功能需求 — 性能预期、规模假设、安全需求、合规要求（GDPR、HIPAA 等）
• 范围之外（MVP） — 明确列出 v1 不会实现的内容，以防范围蔓延

访谈问题：

• 对于 MVP，产品至少需要具备哪些功能才能让用户获得价值？
• 哪些内容可以等到 v2？
• 是否有合规或监管要求（数据驻留、医疗保健、金融）？
• 预计前 6 个月和第一年分别会有多少用户？

文件模板：根据 templates/03-requirements.template.md 编写 03-requirements.md（完整版 — 将编辑内容与用户生成内容分开，并标注可复用结构/动态区域以及 i18n/草稿-发布）。章节：核心功能 · 账户与身份验证 · 产品管理的内容 · 本地化与草稿 · 集成 · AI / Agent 访问（MCP）· 非功能需求 · 范围之外。

---

阶段 4 — 技术决策

目标：选择技术栈。现在才开始讨论技术 — 并且应根据需求选择技术，而不是反过来。

本技能倾向采用的默认选项（用户可以覆盖任何选项，但要事先说明）：

领域	默认选项	原因
后端 / CMS	Strapi v5	无头 CMS，提供管理界面，开箱即用地支持 REST + GraphQL；内容类型可从第 3 阶段顺畅映射
数据库	PostgreSQL	Strapi 推荐的生产环境数据库；可在 Strapi Cloud 和大多数托管平台上使用
托管（后端）	Strapi Cloud	托管式 Strapi：无需基础设施、自动升级、内置 CDN / 媒体功能，并包含 Postgres。参见 references/strapi-cloud-deploy.md
API 风格	使用带路由中间件的 Strapi REST 进行填充（如果前端需要，则使用 GraphQL 插件）	符合 Strapi 的默认设置
前端	由用户选择 — 务必询问（一流支持：Next.js、TanStack Start、Astro、Vue/Nuxt）	Strapi 是无头 CMS；任何前端都能使用。不要擅自设定默认选项。参见 references/frontend-frameworks.md
身份验证	内置 Users & Permissions（Better Auth 插件为可选项）	U&P 随 Strapi 一同提供，可用于生产环境，且符合默认的 Cloud 部署路径。strapi-community/plugin-better-auth 插件（社交登录 / 2FA / 通行密钥）是可选升级方案 — ⚠️ 目前处于 Beta 阶段；据其维护者称，不适用于生产环境；需要 Strapi ≥ 5.45，并会移除 U&P。仅在用户需要这些功能且接受 POC 风险时才提供。参见 references/auth-better-auth.md

流程：

1. 陈述上述默认设置并询问：“后端将使用 Strapi v5，部署到 Strapi Cloud，除非你有理由选择其他方案。对于前端，我对 Next.js、TanStack Start、Astro 或 Vue/Nuxt 都很熟悉（也可以选你偏好的其他框架）。你已经有想法了吗？”
2. 前端——始终询问，绝不自行假设。 不设静默默认值。选定后，该选择将作为第 5–6 阶段的参数（脚手架命令、路由树、环境变量前缀、身份验证接入），详见 references/frontend-frameworks.md。 2b. 参考仓库 → 必须遵循的约定。 用户提供仓库或以前的项目（“按 X 的架构来”“以 Y 为灵感”）时，明确区分两件事：代码复用（通常禁止——全新开发）和约定（通常必须遵循）。从每个参考中提取具体约定（插件结构、文件夹布局、模式——例如“本地插件：遵循 <repo> 的 sdk-plugin TS 结构”），并将其记录到 04-tech-decisions.md 中，标记为必须遵循，并作为约束带入第 5–6 阶段。绝不要只把参考记录为“仅供参考”——这等同于允许偏离。
3. 身份验证——默认使用内置 Users & Permissions；将 Better Auth 作为可选方案。 U&P 已内置且已可用于生产环境，符合默认的 Strapi Cloud 部署目标。只有在需求涉及社交登录、双重身份验证、魔法链接或通行密钥时，才提供 Better Auth 插件，并明确说明其状态：“身份验证默认使用 Strapi 内置的 Users & Permissions——已可用于生产环境，无需额外设置。如果你需要社交登录／双重身份验证／通行密钥，可以使用 Better Auth 插件，但它目前仍处于 Beta 阶段（维护者表示不适用于生产环境），因此适合概念验证，不适合正式发布。哪种方案更符合你的需求？” 记录所选方案及其影响（权限模型有所不同——见下文）。
4. MCP 服务——询问产品是否需要 AI Agent 管理内容。 如果第 3 阶段标记了 AI／Agent 读取或写入内容的需求（通过 CMS 使用助手／副驾驶／自动化），直接询问：“你想开放 Strapi 内置的 MCP 服务，让 AI Agent 读取和写入内容吗？该服务自 Strapi 5.49 起已正式发布并可用于生产环境——主要限制是不能上传新媒体，且动态区域没有类型信息。” 默认关闭——只有明确答复同意后才启用（这是攻击面决策，不是成熟度决策）。如果启用，将 Strapi 最低版本提升至 ≥ 5.49，并记录令牌范围方案。详见 references/strapi-mcp-server.md。

   如果答复是肯定的，请追问真正重要的问题：Agent 会在这里开展实际工作，还是只浏览内容？ 如果要开展实际工作，应设计专用领域工具，并仅向这些工具授予令牌权限——自动生成的 CRUD 工具在更新时要求提供完整记录（在一次真实会话中，重新发送被截断的内容会悄无声息地删除一篇 1,200 字的文章），会拒绝 $null／枚举筛选条件，并将关联项作为普通 ID 返回。只要部分更新工具不暴露不可变字段，就能避免这类数据丢失。详情及结果大小保护措施见 references/strapi-mcp-server.md。

5. 倾听用户偏好。如果用户不接受 Strapi Cloud（出于成本、区域或本地部署要求），记录这一点，并改用可自托管的 Strapi 方案（在第 6 阶段编写 Dockerfile 和带 Postgres 的 docker-compose 配置——参见 https://docs.strapi.io 上的 Strapi Docker 指南）。
6. 对于以下每个方面，要么确认用户的选择（并简要核对其是否符合需求），要么在用户尚未决定时提供选项。提供建议时，列出 2–3 个方案及其取舍——不要直接替用户选定方案。
7. 对每项决策，都要记录原因——是哪项需求或偏好促成了该选择。

需要讨论的方面：

• 后端 / CMS — 默认使用 Strapi v5。注明 Strapi 版本、目标 Node 版本，以及是否预计使用任何插件（i18n、Users & Permissions、GraphQL、自定义字段）
• 模块组织 — 当产品“由多个模块构建”时，默认使用 src/api/<name> 文件夹（Strapi 原生功能单元；内容类型可选——仅路由和仅服务的 API 都有效，自定义 MCP 工具在应用级注册）。只有当模块需要管理面板 UI、跨项目复用或分发时，才选择本地插件——它们会增加一个构建步骤，而 strapi develop 不会监视该步骤。明确作出决定并记录原因；参见 references/strapi-build-cookbook.md 中的 modules 条目
• 数据库 — 默认使用 Strapi Cloud 上的 Postgres。SQLite 仅适用于本地开发。Strapi v5 仅支持 SQL（PostgreSQL/MySQL/MariaDB/SQLite）；不支持 MongoDB / 文档数据库——如果用户想用 Mongo，这是第 1 阶段的产品适配问题（Strapi 并非合适的后端），而不是第 4 阶段的小调整
• 托管 — 后端 — 默认使用 Strapi Cloud。其他选择：Render、Railway、Fly.io、AWS、可自托管的 Docker
• 托管 — 前端 — Vercel、Netlify、Cloudflare Pages 等（这四种一等框架都可部署到其中任何平台）
• 前端框架 — 没有默认选项；请询问。首选框架：Next.js（生态广泛，适合应用型产品）、TanStack Start（类型安全的全栈 React）、Astro（内容密集型 / 静态网站）、Vue/Nuxt（Vue 团队）。也支持其他框架（SvelteKit、SolidStart、Remix、纯 React）。参见 references/frontend-frameworks.md
• 身份验证 — 默认使用 Strapi 内置的 Users & Permissions 进行终端用户身份验证，并使用 Strapi 管理员身份验证供编辑使用（适用于生产环境，无需额外设置）。可选启用：当用户需要社交登录 / 2FA / 通行密钥且接受 POC 风险时，使用 better-auth 插件（测试版，需要 Strapi ≥ 5.45，并会移除 U&P）。仅当 SSO / 企业需求足以支持时，才使用外部服务提供商（Clerk、Auth0）。参见 references/auth-better-auth.md
• 媒体 / 文件存储 — Strapi Cloud 默认捆绑媒体存储 + CDN。自托管时：通过上传服务提供商使用 S3、R2、Cloudinary
• CI/CD — 前端使用 GitHub Actions；Strapi Cloud 内置推送即部署功能
• 电子邮件 / 通知 — Strapi 电子邮件服务提供商（Sendmail、SendGrid、Mailgun、Resend）
• 支付 — 如适用，使用 Stripe / Lemon Squeezy / Paddle，并通过自定义 Strapi 控制器或前端调用
• 分析与监控 — PostHog、Plausible、Sentry
• MCP 服务（AI Agent 访问） — 默认关闭。 如果第 3 阶段标记了 AI / Agent 内容访问需求，则启用 Strapi 内置 MCP 服务（自 v5.49 起正式可用）：在 config/server 中设置 mcp.enabled，通过 POST /mcp 暴露，并使用限定范围的 Admin API 令牌进行身份验证。通过插件（strapi.ai.mcp）扩展自定义工具。不要在未确认需求时启用。参见 references/strapi-mcp-server.md
• 可选依赖与降级处理 — 对于每项外部服务（AI 服务提供商、电子邮件、支付、搜索等）：它是必需的还是可选的？如果缺少密钥 / 配置，功能是会正常禁用（功能标记 + 隐藏 UI + 503，核心流程不受影响），还是会导致应用崩溃？请逐项依赖作出决定并记录——构建完成后再补做优雅降级，成本远高于一开始就设计好
• 样式 — 默认使用 Tailwind

如果第 3 阶段的需求让某项选择显得可疑（例如，用户需要 Strapi 原生不支持的离线优先同步），请委婉指出并讨论权衡。建议不使用 Strapi 之前，请使用 strapi-docs MCP 或通过 WebFetch 访问 https://docs.strapi.io，核实其功能支持情况。

文件模板：根据 templates/04-tech-decisions.template.md 编写 04-tech-decisions.md。对每项决定记录 选择 · 考虑过的方案 · 原因。明确记录前端框架（它会影响第 5–6 阶段）和身份验证选择及其影响（标准 U&P → Public/Authenticated 角色（默认）；或 Better Auth → 测试版 + 移除 U&P + 需要 api-permissions）。

---

第 5 阶段 — 技术需求（详细规格）

目标：将需求（阶段 3）和技术决策（阶段 4）转化为具体的技术产物：Strapi 内容类型、REST/GraphQL 端点、自定义控制器和前端路由。

这是工程蓝图。内容仍便于人类阅读，但也会将抽象的“用户可以登录”转化为受身份验证保护的路由和 Strapi 中的 User 集合。

询问用户：

• 关于内容：你希望我根据已识别的实体起草 Strapi 架构（集合类型、单一类型、组件、动态区域），然后由你审阅吗？
• 关于 API：Strapi 自动生成的 REST 端点是否足够，还是需要自定义控制器（例如聚合、第三方调用、webhook）？我们需要 GraphQL 吗？
• 关于前端：使用阶段 4 中选定的框架（参见 references/frontend-frameworks.md），路由/页面树应该如何组织？请遵循该框架的约定——app/（Next.js）、src/routes/（TanStack Start）、src/pages/（Astro）、pages/（Nuxt）。

如果不确定 Strapi 某项功能的工作方式（生命周期钩子、动态区域查询、Document Service 与 Entity Service、v5 中的 populate 语法），请先通过 strapi-docs MCP 查找，否则使用 WebFetch https://docs.strapi.io。在文件中引用具体页面。

需编写的章节：

• Strapi 内容类型 — stage 3 中每个实体都需说明：
  • 类型：集合类型、单一类型或组件（以及所属类别）
  • 字段及其 Strapi 字段类型（string、text、blocks（现代富文本编辑器——独立类型）、richtext（旧版 Markdown）、media、relation、enumeration、json、uid、datetime、boolean、integer、decimal、email、password、component、dynamiczone）
  • 关联的目标与基数（oneToOne、oneToMany、manyToOne、manyToMany）
  • 草稿与发布：是/否
  • 本地化：是/否（必要时按字段说明）
  • 验证规则 / 唯一性约束
• Strapi 组件 — 被多个内容类型或动态区域使用的可复用结构（例如，shared.seo、shared.cta、blocks.hero）
• Strapi 动态区域 — 可接受组件列表的插槽（页面构建器中常见）
• API 表面：
  • 将使用的 Strapi 自动生成 REST 端点（以及会通过权限禁用的端点）
  • 默认填充策略 — 通过路由中间件说明（参见 https://docs.strapi.io/cms/api/rest/populate-select），不要在每次调用时都使用查询参数
  • 自定义控制器 / 路由 — 列出方法、路径、身份验证（是否需要 better-auth 会话或公开）、请求/响应结构及说明
  • GraphQL — 仅在已安装时列出。列出前端所依赖的查询/变更
• MCP 服务 — 仅在 stage 4 中启用时适用。 说明 config/server 中的 mcp.enabled、开放的内容类型/操作、遵循最小权限原则且按用例限定范围的 Admin API 令牌策略、通过插件添加的任何自定义工具（strapi.ai.mcp），以及已知限制（不支持媒体上传、动态区域无类型、仅支持无状态的 POST /mcp）。参见 references/strapi-mcp-server.md
• 身份验证流程 — 注册、登录、登出、密码重置、社交服务提供商（如有，注明具体项）、会话/JWT 存储方式，以及前端获取会话的方式 — 按照 stage 4 的选择编写（默认使用内置的 U&P；Better Auth 路径参见 https://github.com/strapi-community/plugin-better-auth 和 https://better-auth.com）
• 权限与角色 — 取决于 stage 4 的身份验证选择。 内置 Users & Permissions：列出角色（Public、Authenticated、自定义）以及各角色对每种内容类型的读/写权限。Better Auth 路径：内容 API 权限由 @strapi-community/plugin-api-permissions 管理（U&P 已移除）——按该插件的规则说明权限。无论选择哪种方式，都需说明编辑端的 Admin 角色。参见 references/auth-better-auth.md
• 生命周期 / 策略 / 中间件 — 根据上下文选择层级：依赖请求/身份验证的逻辑（将 owner/author 设为当前用户）放在控制器中；不依赖请求的文档级逻辑（slug 生成、派生字段、通知）放在Document Service 中间件中（在 register() 中使用 strapi.documents.use()）；生命周期钩子不再是 v5 的默认选项（没有请求上下文；发布时会触发两次）。对于由服务端设置的字段、is-owner 策略和所有者范围内的读取，请遵循 references/strapi-build-cookbook.md — 直接采用常见的简单做法在 v5 中会返回 400
• 页面与关键组件（前端） — 按照所选框架的约定组织路由/页面树（app/、src/routes/、src/pages/ 或 pages/）。对于每条路由，说明 Strapi 数据的获取位置（loader/Server Component/useFetch/frontmatter）、组件以及任何客户端交互。参见 references/frontend-frameworks.md
• 状态管理 — 服务器状态通过框架的数据层管理（loaders / Server Components / useFetch），并在需要时使用 TanStack Query 进行客户端重新获取；筛选器状态放在 URL 中；尽量减少客户端状态
• 后台任务 / 计划任务 — Strapi cron 任务（config/cron-tasks.ts，并在 config/server 中设置 cron.enabled）或外部任务（例如，Strapi Cloud 不提供长期运行的工作进程——如有需要请注明）
• 媒体与上传 — Strapi Cloud 媒体（默认）或外部服务提供商；图像格式和响应式变体
• 环境变量 / 密钥 — 分别列出 Strapi 后端和前端所需的变量。浏览器安全的值使用所选框架的公开前缀（NEXT_PUBLIC_/VITE_/PUBLIC_/NUXT_PUBLIC_）；仅供服务端使用的密钥则不要添加公开前缀（例如，用于 SSR 获取数据的 Strapi API 令牌绝不能添加公开前缀，否则会泄露到客户端 bundle） 文件模板：根据 templates/05-tech-requirements.template.md（权威来源）编写 05-tech-requirements.md。内容涵盖：内容类型（含字段表）、组件、动态区域、API 接口（REST／填充／自定义路由／GraphQL）、身份验证流程、权限与角色、生命周期／策略／中间件、前端路由树、状态管理、后台任务、媒体和环境变量。根据第 4 阶段的选择调整身份验证和前端部分（参见 references/auth-better-auth.md 和 references/frontend-frameworks.md）——如果用户选择了其他方案，就不要默认采用 Better Auth 或 TanStack Start。

**稳健性检查——第 5 阶段结束后、第 6 阶段开始前，与用户一起进行。**功能访谈总会漏掉运行层面的强化措施；不要等用户来问“还缺什么？”。逐项检查此清单，并将用户接受的内容纳入 05（每项都很容易写入规格，事后补做的成本却很高）：

• 静默故障模式——管道／Webhook 错误：死信存储（绝不丢弃数据）、运维告警渠道、“工具绝不能静默失败”。还要规定重放路径：无法重新运行的死信存储，只是一个只写不读的坟场
• 并发情况下的唯一性——对于产品视为外部身份键的每个字段（externalId、slug、key）：schema 中的 unique: true 仅作用于验证层，因此 Document-Service／采集／cron 写入可以随意创建重复项，之后重复项还会导致行死锁。需规定真正的 DB 唯一索引，以及采用 create-catch-refetch 的写入器（参考手册：“unique: true 是一条 VALIDATION 规则”）
• 定时任务的可重入性——任何会逐项执行网络调用的 cron：加入重叠保护、重试上限和单次挂起告警。Strapi 的调度器不会串行执行异步任务，因此“每分钟”加上耗时工作就会导致重复并发处理
• 事务化工作流步骤——任何会写入 2 条或更多记录的操作（状态 + 审计行 + 通知）：使用一个事务，在事务内重新检查守卫条件，并将副作用放在事务外。将这些逻辑放在服务中，这样自定义路由、Agent 工具和任务就能共用同一套规则实现
• 会话时长——明确规定预期的登录时长，并检查身份验证配置是否确实能实现该时长（U&P 的 jwtManagement: 'refresh' 默认会签发有效期为 10 分钟的访问令牌；若前端没有轮换循环，用户就会频繁掉线）
• 用户数据暴露——仅通过 /api/users/me 获取当前用户；绝不要预置 user.find（以免枚举账户）；其他记录中的用户身份信息仅允许使用 id／username（参见手册条目）
• 指标定义——产品报告的任何分数／KPI：都要有一个有文档记录的公式（时间窗口、加权方式、时区），否则仪表板上的数字就会引发争议
• 人工纠正循环——在 AI／自动化给数据打标签的任何环节：能否由人工覆盖？重新处理后，覆盖是否仍然有效？是否标记为人工设置？
• 可复现性／版本管理——为计算结果标记模型／提示词／配置版本，避免工具变更被误认为数据变化
• 成本控制——外部 API 预算计数器，设置警告／停止阈值
• 时效性／SLA 可见性——队列需要过期标记和摘要，否则旧项目会在无人察觉时积压
• 审计跟踪——记录每条记录的操作人、操作内容和时间——如果产品的价值包括“完整的数据轨迹”，就要明确建模
• 搜索——任何以“过往 X 资料库”为价值主张的功能，都需要全文搜索，而不只是筛选
• 空状态——从零开始的数据意味着首日仪表板内容稀少；要针对这种情况进行设计

---

第 6 阶段——构建规格

目标：产出一个 Markdown 文件（06-build-spec.md），任何编码 Agent（Claude Code、Cursor 等）都能阅读并立即开始构建一个采用第 4 阶段所选前端的 Strapi v5 POC。此文件是第 1 至第 5 阶段内容的综合整理，格式面向 AI 编码 Agent。

此文件必须自成一体——构建 Agent 无需阅读其他五个文件，也能了解要构建什么。可将它们作为背景资料引用，但必须包含 Agent 执行任务所需的全部内容。 需要预先写入构建会话规范的说明：

• 偏离处理协议（将这句话以原意逐字写入规范）： “本规范中的命令、结构和引用约定均由用户决定。如果你想替换其中任何一项——无论是为了减少构建阻力、采用更新的 API，还是选择‘更简单’的替代方案——都要停下来询问用户；不要擅自权衡取舍。” 构建 Agent 往往会在推进势头最强时为捷径找理由；这句话正是用来阻止他们的。
• 如已安装，请针对任何 Strapi API 问题使用 strapi-docs MCP；否则使用 WebFetch https://docs.strapi.io。
• 在规范的文档查询标题中加入所选前端框架的当前文档（Next https://nextjs.org/docs · Astro https://docs.astro.build · Nuxt https://nuxt.com/docs · TanStack Start https://tanstack.com/start/latest/docs），并要求构建会话根据这些文档核实与版本相关的约定（文件名、配置键、异步 API）——框架会在不同主版本间更改约定，而旧版兼容功能会掩盖这些变化（例如 Next 16 使用 proxy.ts，而非 middleware.ts）。只列出 Strapi 文档的规范会让构建者只核实技术栈的一侧，另一侧则凭经验自行处理。
• 规范必须自成一体——不得假设已安装其他技能。每个构建步骤都要具体说明（命令、架构、配置），确保构建会话仅凭规范和 Strapi 官方文档即可执行。
• 将相关的 references/strapi-build-cookbook.md 注意事项直接写入规范——在全新的 Agent 会话中粘贴 06-build-spec.md 后，Agent 无法读取此技能的文件，因此指向 references/… 的内容毫无用处。请将适用模式复制到相应里程碑：通过控制器中的 Document Service 为 owner／author 等服务端设置字段赋值；使用 is-owner 策略；通过 Document Service 中间件为每种按 uid 筛选的类型生成 slug；读取时限定所有者范围；以及为两个角色创建可登录的 U&P 用户并进行播种。（trailhead 示例的 M4／M7 展示了内嵌形式——这是必须遵循的规则，而非可选项。）
• 对于 Better Auth 方案，请将安装和配置步骤直接写入规范，并链接到 Strapi 官方教程 URL（https://strapi.io/blog/strapi-better-auth-tutorial-setup-guide-for-strapi-v5-and-next-js-16）——同样，不要在规范中引用 references/auth-better-auth.md。

必需章节：

1. 项目概览 — 阶段 1 的 2–3 句摘要，加上一句话简介
2. 技术栈 — 阶段 4 中已确认的选择（Strapi v5、Postgres、Strapi Cloud、选定的前端框架、选定的身份验证方案，以及其他技术）
3. 仓库布局 — 常见形式：单体仓库或两个文件夹（apps/cms 中放 Strapi，apps/web 中放前端），或两个独立仓库
4. 设置命令 — 后端和前端的具体命令。使用选定框架的脚手架命令（参见 references/frontend-frameworks.md）
5. 构建顺序（里程碑） — 构建 Agent 可逐项完成的独立任务块。每个里程碑都应有明确的“满足……时即完成”标准。默认里程碑结构：
   • M1 — 搭建 Strapi 脚手架 + Postgres + 关联 Strapi Cloud 项目
   • M2 — 内容类型、组件、动态区域、草稿/发布、i18n、权限
   • M3 — 身份验证：采用 U&P 默认方案 → 配置 Public/Authenticated 角色；或采用 Better Auth 方案 → 安装 3 个插件，移除 U&P，配置提供商（将 references/auth-better-auth.md 中的步骤和官方教程 URL 写入规范）
   • M4 — 自定义控制器、生命周期、路由中间件（默认填充）
   • M5 — 搭建前端脚手架 + 路由/页面 + 调用 Strapi 的数据获取（选定框架）
   • M6 — 将身份验证 UI 接入身份验证客户端；受保护路由正常工作
   • M7 — 种子数据 + 媒体上传
   • M8 — 自动化端到端测试套件 + 部署 + 冒烟测试：将 POC 验收标准转化为 Playwright 测试套件（测试通过应用的真实入口注入自己的数据，例如 Webhook，因此不依赖种子数据），然后部署到 Strapi Cloud + 部署前端 + 对核心流程进行冒烟测试
6. Strapi 模式 — 从阶段 5 复制，并按照文档中的 Content-Type Builder 格式整理为 Strapi v5 内容类型 schema.json
7. API 范围 — 从阶段 5 复制：启用的 REST 端点、默认填充中间件、自定义路由/控制器、GraphQL（如有）
8. 身份验证 — 所选方案（Better Auth 或 U&P）的安装步骤、配置、提供商、前端客户端接入
9. 前端路由/页面树 — 遵循所选框架约定的文件路径（app/、src/routes/、src/pages/ 或 pages/）、数据获取、组件
10. 环境变量 — 完整列表（后端 + 前端），附说明和示例值（不得填写真实密钥）。仅对可在浏览器安全使用的值使用框架的公开前缀；密钥不要加前缀
11. 部署：
    • Strapi 后端 → Strapi Cloud（默认）。步骤：在 https://cloud.strapi.io 创建项目，关联 Git 仓库，设置环境变量，设置 Node 版本，推送以触发部署。参考：references/strapi-cloud-deploy.md 和 https://docs.strapi.io/cloud/getting-started/intro
    • 前端 → Vercel/Netlify/Cloudflare Pages（用户在阶段 4 中选择）
    • 如果使用 Better Auth：此处必须配置跨站 Cookie（前端和 Strapi Cloud 位于不同域名）——设置 trustedOrigins 和生产环境的 defaultCookieAttributes。参见 references/auth-better-auth.md
12. POC 验收标准 — 根据阶段 2 的核心流程制定。POC 的完成标准是：针对已部署的 Strapi Cloud 后端，整个流程端到端正常运行。
13. 待解决问题 / 暂缓事项 — 用户决定暂缓的任何事项

文件模板：根据 templates/06-build-spec.template.md（权威来源）编写 06-build-spec.md。该模板包含完整且自包含的构建规范：项目概览、技术栈、仓库布局、设置命令、M1-M8 里程碑、模式、API 范围、身份验证、前端路由树、环境变量、部署和验收标准。根据阶段 4 的选择填写框架和身份验证相关部分——模板为每种框架都提供了完整示例；不要粘贴错误的示例。 填写时有两个正确性方面的提醒（很容易出错）：

• Strapi 脚手架：默认使用 TypeScript，且 --quickstart 已弃用，并且与 --dbclient 冲突——请勿使用。自动化构建请使用 npx create-strapi-app@latest apps/cms --non-interactive --skip-cloud --dbclient=postgres --dbhost=... --dbport=... --dbname=... --dbusername=... --dbpassword=...（如果不同时使用 --non-interactive 和 --db* 标志，CLI 会提示输入）。
• 前端环境变量：只有适用于浏览器的值才使用框架的公开前缀（NEXT_PUBLIC_/VITE_/PUBLIC_/NUXT_PUBLIC_）。仅供服务端使用的 Strapi API 令牌必须不带前缀（STRAPI_API_TOKEN），否则会泄漏到客户端包中。

---

用户想修改前一阶段内容时

本技能具有灵活性——用户可以随时说“其实，我想更改用户画像”或“我们把 Postgres 换成 SQLite 吧”。遇到这种情况时：

1. 打开相关文件并进行修改。
2. 逐一检查后续阶段，并询问：“此更改会影响[阶段 X]吗？”——例如，更换数据库可能会影响阶段 5 中的数据模型，也可能不会。
3. 更新所有受影响的下游文件。
4. 重新提供修改后的文件。

不要悄悄更新下游阶段——务必先与用户确认。他们可能希望只在当前阶段修改，也可能希望更改逐步影响后续阶段。

---

语气与节奏

• 每次只进行一个阶段。 不要一次性抛出全部六个阶段的问题。
• 每轮提出 2-3 个问题，不要问 10 个。等待回答后再深入。
• 维护未解决问题清单。 实际利益相关者可能会不按顺序回答、只回答一部分，或完全不回答。明确记录每个尚未回答或回答不完整的问题；在下一个合适的时机再问一次；仍未解决的问题必须作为标记的假设写入阶段文件（“⚠️ 假设 — 尚未确认：……”），绝不能默默猜测。持续更新清单——阶段 6 应在“开放问题”下列出仍未解决的假设。
• 起草文件前，先复述你听到的内容——这样能以较低成本发现误解。
• 流程上要有主见，选项上保持中立。 阶段顺序固定（先价值，后技术）；但在每个阶段内，应以用户偏好为准。
• 留意过早转向技术的话题。 如果用户在阶段 1-3 期间不断尝试讨论框架，委婉地将技术想法记到阶段 4 的备注中，并引导讨论回到当前阶段。