wi-site

Wonder Site（基于 new-site）

概览

在 wonder-image/new-site 或任何基于它搭建的项目中使用此技能。当前仓库负责运行时。框架位于 vendor/wonder-image/app（Composer；对其中的修改请参阅 wi-app），JS/CSS 设计系统位于 assets/lib/wonder-image/dist/（从 npm 包 wonder-image/lib 复制而来）。请将两者都视为上游内容，切勿直接修改。

术语表

wi-app 和 wi-site 使用的共享术语（两项技能中的表述完全相同）：

• 框架 — wonder-image/app（Composer 包，github.com/wonder-image/app）。启用 wi-app 时位于仓库根目录；在站点中位于 vendor/wonder-image/app/。
• lib — wonder-image/lib（npm 包，github.com/wonder-image/lib）。JS/CSS 设计系统。源码位于 node_modules/wonder-image/src/；编译后的副本位于 assets/lib/wonder-image/dist/。
• 脚手架 — wonder-image/new-site（github.com/wonder-image/new-site）。站点模板。脚手架本身也是一个有效的站点。
• 站点 — 任何依赖 wonder-image/app（即在 vendor/wonder-image/app 下安装框架）的项目。通常是脚手架本身或基于它衍生的项目。规范术语 — 优先使用“站点”，避免沿用“使用方项目”/“使用方应用”等混用说法。
• 模块 — 通过 Composer（或文件系统回退机制）发现的外部 Composer 包 wonder-image/<slug>。它通过 module.json 和 ModuleInterface 入口点提供自己的模型/资源/路由。
• custom/ — 仅供站点使用的目录，用于存放项目页面、组件、布局、路由、配置和辅助函数。框架中绝不会包含此目录。
• app/Models / app/Resources — 站点 PSR-4 根目录（App\Models\... / App\Resources\...）。与框架的 class/App/Models / class/App/Resources（Wonder\App\Models\... / Wonder\App\Resources\...）不同。

何时切换到 wi-app

出现以下任一迹象时，请停止并切换到 wi-app——这项工作属于框架，而非当前站点（frontmatter 中的 SKIP 块已包含路由侧检查；此处是工作期间的判断方式）：

• 仓库的 composer.json 声明 "name": "wonder-image/app"（你位于框架仓库中，而非站点）。
• 请求的修改位于 vendor/wonder-image/app/ 下。在站点中切勿修改 vendor。要么调整修改方案，将其放在 custom/ / app/Models / app/Resources 中（仍属于 wi-site），要么针对框架仓库提交修改（此时适用 wi-app）。
• 你需要添加或修改 Model / Resource 基类、FormField 辅助工具、class/Elements/ 下的元素、class/Themes/{Wonder,Bootstrap}/ 下的主题渲染器、app/config/routes/* 中的路由、模块发现流程、引导顺序、app/config/app/permission.php 中的权限构建器注册表，或共享的用户管理资源。
• 任务是“添加新的表单输入类型”“更改框架在 Wonder 与 Bootstrap 中渲染输入项的方式”“扩展权限构建器”“注册新的控制台命令来源”，或任何定义（而非使用）框架行为的工作。
• 在 wonder-image/lib（JS/CSS 设计系统源码）中工作——这是完全不同的仓库；wi-site 和 wi-app 都不适用。

不可妥协的规则

• 绝不编辑 vendor/、node_modules/ 或 assets/lib/wonder-image/dist/。最后一个目录会由 npm install 从 wonder-image/lib 重新生成。
• 绝不要在站点任务中修改 vendor/wonder-image/app。如果更改应在该目录中进行，请切换到 wi-app。
• 绝不要从此技能运行以下 Forge 命令：
  • php forge config
  • php forge credentials
  • php forge provision
  • php forge db:init
  • php forge build
• 所有面向用户的字符串都必须通过 __t(...)，并在 lang/{locale}/*.json 中添加对应条目（JSON 文件不限数量：pages.json、components.json、emails.json、legal.json，以及站点所需的任何新文件）。URL 必须通过 __r(string $name, array $parameters = []) 生成（优先使用——根据命名路由构建 URL，自动采用当前语言区域，且路由重命名后仍然有效）。仅当没有命名路由且必须根据自由路径构建 URL 时，才使用 __u(string $path)（例如 __u('contact')）。不要在 PHP 中硬编码文案或语言前缀。
• 在编写新的 CSS 类、JS 行为或 UI 结构之前，先检查 wonder-image/lib 并复用现有设计系统。完整的 UI 规则手册见 references/style-and-lib.md——任何 UI / 样式 / 设计系统相关任务都要阅读。默认原则是使用 lib，不要修改它。
• <wi-card> 已弃用。 不要在站点后端页面中编写 <wi-card>：请使用 wonder-image/app 中的 Card。现有使用它的页面在 lib 移除它之前仍可正常工作；修改这些页面时请将其替换。
• 绝不要硬编码颜色（HEX / RGB / HSL）、引入 .wi-*（或任何其他）前缀式命名，或构建并行的 CSS 系统。要动态检测 {ASSETS_VERSION}——不要假设其为 0.0/ 或任何其他版本。
• 优先使用外部 Composer 模块 wonder-image/<slug>，而非嵌入项目的模块代码。
• 将 PSR-4 类放在 app/Models 和 app/Resources 下，命名空间分别为 App\Models / App\Resources。将项目页面、组件、布局覆盖、路由、配置和辅助函数放在 custom/ 下。
• 标准的模型 / 表流程为 Model::tableSchema() + Model::dataSchema()。不要在其之外另行创建并行的表定义系统。

启动顺序

0. 先阅读 docs/ai/PRODUCT.md。 它定义了品牌与产品的区分、site_type、目标用户、品牌个性、语气与风格、设计原则。接下来所做的一切都必须与其中的内容保持一致，包括布局选择、文案、模块建议和 UI 方向。每次会话都要对每个站点运行一次 references/external-skills.md 中的站点就绪检查，无论站点是否已迁移，并且要在判断文件缺失或为空之前运行：该检查会将根目录下的 PRODUCT.md 移至 docs/ai/（若已纳入版本控制则使用 git mv，否则使用 mv；也会覆盖尚未修改且章节为空的脚手架模板），添加 .gitignore 和 deploy.yml 中的行，并创建 docs/ai/reports/。只有完成检查后，才能判断 docs/ai/PRODUCT.md 的状态。

   如果 docs/ai/PRODUCT.md 缺失，或其中的必填章节为空，请暂勿开始用户的任务。 按照 references/product-md.md § 编写流程 中的访谈流程，使用 AskUserQuestion 每次提出 2–4 个有针对性的问题，随收到答案随即保存到 docs/ai/PRODUCT.md，并持续访谈，直到对项目的了解程度至少达到 80%。具体标准为：6 个必填章节（Register、Site type、Target users、Brand personality、Voice / tone、Design principles）全部填写，并且至少填写以下两项之一：Anti-references、Asset paths。只有达到此标准后，才能继续原任务。原因：否则产出的内容会过于通用，用户之后还得返工；花 10–15 分钟访谈，可以让本次会话以及后续会话中的每个决策都更加高效。

   访谈应按顺序进行并根据情况灵活调整：如果用户已在对话中提及某些信息（例如“我们有一个时尚品牌”），就先填入相关章节并请用户确认，而不是从头询问。完整架构见 references/product-md.md；可直接复制粘贴的模板见 references/examples.md §6。

   如果任务涉及 UI（页面、组件、样式、设计令牌），则接着阅读 docs/ai/DESIGN.md。框架每次写入 root.css 时都会根据 CSS 令牌生成该文件：阅读即可，切勿编辑。如果文件缺失，请参阅 references/external-skills.md § DESIGN.md 缺失时的备用方案。

1. 对任务分类：

   • 页面或组件工作
   • UI / 样式 / 设计系统工作
   • 模型、资源、repeater 或表格工作
   • 可通过后端编辑的内容
   • 权限、角色或用户区域
   • 翻译、本地化 URL 或内容文本
   • 模块集成
   • 设置、运行时或本地环境

2. 只阅读与任务匹配的参考资料（见下方的任务路由）。对于可复制粘贴的脚手架（Model + Resource 骨架、前端页面、pages.json 条目、permissions.php 扩展、modules.php），请直接查看 references/examples.md。

3. 判断工作应放在 custom/、app/、外部 wonder-image/<slug> 模块中，还是实际上应该修改框架（切换到 wi-app）。

4. 拒绝错误的放置方式：不得直接修改 vendor/，不得手动编辑 node_modules/ 或 assets/lib/wonder-image/dist/，不得创建并行的用户管理页面，也不得在 assets/{ASSETS_VERSION}/css/set-up/ 中编写自定义 CSS。

任务路由

品牌、文案、语气、网站类型

阅读 references/product-md.md。docs/ai/PRODUCT.md 是语体、目标用户、品牌个性、品牌声音/语气、设计原则和 site_type（landing / corporate / blog / ecom / rsvp）的权威来源。文案存放于 lang/{locale}/*.json，必须遵循 docs/ai/PRODUCT.md 中声明的品牌声音。docs/ai/DESIGN.md 由框架根据 color.css + root.css 生成：阅读它，不要编辑；视觉令牌的规则仍以 style-and-lib.md 为准。

页面或组件

阅读 references/implementation-playbook.md 和 references/style-and-lib.md。前端页面的复制粘贴骨架见 references/examples.md。

• 优先使用 Badge::inline()、Wonder\Elements\Frontend\EmptyState、Wonder\Elements\Frontend\Pagination 和 Wonder 的 Text / RichText 渲染器（app ≥ v2.4.0-beta.5），而非手写标记；API 见 wi-app/references/component-catalogue.md § Frontend 列表和文本组件。
• 若要使用一个递归导航树驱动可复用页眉，请阅读 references/header-navigation.md。其中定义了 classic / mega 契约、list 默认样式、可选的 card 展示形式、操作链接、外观选项、桌面端悬停行为和移动端级联行为。
• 页面放在 custom/view/pages/{frontend,backend}/... 下。
• 组件覆盖文件应在 custom/view/components/{frontend,backend}/... 下镜像框架路径。
• 优先复用 \Wonder\View\View::component(...)，不要手动 include。
• 添加新标记前，先检查现有页面组件。
• 公开页面？根据 references/external-skills.md 进行路由：新建公开页面或版块 → design-taste-frontend；改版现有公开页面 → redesign-existing-projects；提供了模型图或截图 → image-to-code。后台页面：不使用外部技能。

UI / 样式 / 设计系统

首先阅读 references/style-and-lib.md。适用于任何涉及按钮、输入框、表单、模态框、卡片、警告、徽章、排版、图片、交互元素、颜色令牌、根变量或自定义 CSS / JS 的任务。

• 默认模式：使用库，不要修改库。修改 wonder-image/lib 需要用户明确提出。
• 编写新内容前，先复用现有库类和令牌。不得使用 .wi-*（或其他）前缀命名。不得建立并行 CSS 系统。不得硬编码颜色。
• 令牌文件：assets/{ASSETS_VERSION}/css/set-up/color.css 和 root.css。自定义 CSS / JS 放在 assets/{ASSETS_VERSION}/css/ 和 assets/{ASSETS_VERSION}/js/ 下，绝不要放在 set-up/ 内。
• 读取或写入令牌文件前，从实际的 assets/ 目录中确定 {ASSETS_VERSION}。
• 结束任何涉及公开 HTML / CSS 的任务前：使用 playwright-cli 在 375 / 768 / 1280 分辨率下截取屏幕截图并检查控制台，然后按 references/external-skills.md 中所述，对涉及的文件运行 web-design-guidelines。仅涉及后台的任务跳过这两项。
• 每项 UI 任务结束时，都要提交 references/style-and-lib.md 中的必需最终报告和提交前检查清单。

外部技能

阅读 references/external-skills.md。路由表（taste、redesign、image-to-code、web-design-guidelines、playwright-cli）、检测和按需使用 --global 安装、docs/ai/PRODUCT.md + docs/ai/DESIGN.md + style-and-lib.md 优先于外部建议的规则、docs/ai/reports/ 中的报告命名，以及网站就绪情况检查，均仅在此文件中说明。请勿在此重复这些规则。

Model、资源、repeater 或表格 — 站点补充说明

阅读 references/implementation-playbook.md 了解放置工作流，然后从 references/examples.md 中的骨架开始。完整的 API 契约（方法签名、生命周期、注册表行为、repeater 详情）请阅读 wi-app/references/model-and-resource.md — 将 wi-app 与 wi-site 一起安装，即可在本地查看。

新建站点 Model + Resource 的步骤：

1. 在 app/Models/<Name>.php 下创建 Model，命名空间为 App\Models，并继承框架的 Model 基类。
2. 在 Model::tableSchema() 中定义 SQL。在 Model::dataSchema() 中定义数据行为。
3. 在 app/Resources/<Name>Resource.php 下创建 Resource，命名空间为 App\Resources，并绑定到 Model。
4. 定义 formSchema() 以配置后台输入项，定义 permissionSchema() 以控制路由访问，定义 navigationSchema() 以配置导航位置。
5. 对于可重复行，使用 FormField::repeater(...) + RepeaterColumn；仅对非 CRUD 页面使用 CustomPageSchema。
6. 运行 composer dump-autoload，然后运行 php forge update --local 以应用运行时生成。

标准流程为 Model::tableSchema() + Model::dataSchema()。不要在此之外另建平行的表定义文件。

访客数据、手写表单、追踪、.htaccess、部署、备份

阅读 references/security-and-deploy.md。其中介绍了在自定义后台页面和邮件中转义访客数据、手写表单和站点路由中的 CSRF、SafeRedirect、downloadAsText() 导出、仅在获得同意后启用 GTM 追踪、.htaccess 中由系统管理的 WONDER 区块、数据库备份和部署排除提案。同一套契约在框架端的说明见 wi-app/references/security.md。

可在后台编辑的内容

阅读 references/implementation-playbook.md。优先采用真正的 Model + Resource 流程。将媒体关联到现有媒体资源。绝不要将可编辑内容存储在静态数组或零散文件中。

权限、角色或用户区域 — 站点补充说明

完整的构建器 API、框架用户资源和运行时 $PERMITS 导出位于 wi-app 的 wi-app/references/permissions-and-users.md 中。在站点中，唯一需要修改的位置是：

• custom/config/permissions.php — 在基础文件（框架中的 app/config/app/permission.php）和模块合并完成后，扩展或覆盖注册表。可复制粘贴的骨架见 references/examples.md。

添加或覆盖站点权限的步骤：

1. 打开 custom/config/permissions.php。
2. 扩展已在 app/config/app/permission.php 中初始化、随后又与模块权限合并的构建器注册表。
3. 在任何项目的 Resource::permissionSchema() 和导航权限控制中引用生成的权限键。
4. 不要另建平行的用户管理页面 — 用户 CRUD 已集中在共享框架资源中。如果站点确实需要不同的用户流程，这属于框架级更改 → 切换到 wi-app。

如果尚未在本地安装 wi-app，请运行 npx skills add wonder-image/skills --skill wi-app，以获取完整参考资料。

翻译、本地化 URL、内容文本

阅读 references/workflows.md。references/examples.md 中有一个 lang/it/pages.json 条目示例。

• 字符串存放在 lang/{locale}/*.json 中——JSON 文件数量不限。网站默认包含 pages.json、components.json、emails.json 和 legal.json；新增文件（例如 lang/{locale}/terms.json）会自动加载。
• 使用 __t("path.to.key") 访问翻译字符串。
• 构建 URL：
  • 优先使用 __r(string $name, array $parameters = [])——根据命名路由生成 URL。适用于在 app/config/routes/ 或 custom/routes/ 中注册的所有路由，包括前端页面、资源 CRUD 路由和自定义后端路由。由于它通过名称解析路由，因此 slug 或路径变更后仍然有效。
  • 仅当不存在命名路由，且必须根据自由路径字符串构建本地化 URL 时，才回退使用 __u(string $path)（例如 <a href="<?= __u('contact') ?>">）。
• 法律页面（隐私、Cookie、条款）通过 wonder-image/app 中的 LegalDocument::make('privacy') 渲染：数据库中的 legal_documents 是唯一来源，lang/{locale}/legal.json 仅用于播种。切勿在页面中通过 __t('legal...') 输出法律文本。
• 网站文本和法律文档由客户端在「设置 → 翻译」中翻译（支持 XLSX/CSV 导出和预览后导入）。对于可翻译的内容字段，让网站 Model 实现 Translatable 并使用 HasTranslations，再用 Model::translated($rows) 读取记录；调度器会自动翻译这些字段。详情见 vendor/wonder-image/app/docs/app/concetti/traduzioni.md。

模块集成

阅读 references/project-structure.md 和 references/workflows.md。

• 优先使用外部 Composer 包 wonder-image/<slug>，而非嵌入代码。
• 在 custom/config/modules.php 中启用模块——可在 references/examples.md 查看复制粘贴即可用的骨架。

设置、运行时或本地环境

阅读 references/workflows.md。在项目根目录中：

• composer install（也会通过 Composer 脚本运行 php forge config）
• npm install（将 wonder-image/lib 复制到 assets/lib/wonder-image/dist/）
• php forge credentials（仅当用户明确要求恢复 Bitwarden dev-shared 时使用；会将密钥写入 .env）
• php forge update --local（应用数据库和运行时生成）
• php forge start（运行本地服务端，可能会补全缺失的 .env）

验证

• 对每个修改过的 PHP 文件运行 php -l。
• 添加、移动或重命名 PSR-4 类时，运行 composer dump-autoload。
• 对集成敏感的更改：先运行 php forge update --local，再运行 php forge start。
• 仅当更改依赖于 wonder-image/lib 中的 assets/lib/wonder-image/dist/ 时，才重新运行 npm install。

输出要求

• 指明实际修改的网站路径（例如 custom/view/pages/frontend/about.php、app/Models/Project.php、lang/it/pages.json）。
• 如果所请求的更改实际应在框架（→ wi-app）或 wonder-image/lib 中完成，请明确说明。
• 相关时，列出翻译文件更新、权限/授权更改以及 Forge/npm 重建步骤。
• 对任何修改 vendor/、node_modules/、assets/lib/wonder-image/dist/ 或任何 Forge 生成文件的请求，说明一行理由并拒绝。