Review Static Site
Goal
验证用户最终编辑、发布或视为完工前的静态网站输出。
此技能是生成的HTML/CSS/JS站点的质量门禁。它不会选择主题、重新创建参考网站、迁移内容或部署站点。它验证生成的文件夹是否像真实的静态站点一样工作。
核心检查项:
- 源文件为有效的UTF-8编码且人类可读。
- 本地链接、脚本、样式表、图片及其他资源可正确解析。
- 站点内部链接和资产默认使用页面相对路径,而非根绝对路径如
/assets/style.css。 - 输出可直接从
index.html打开进行手动预览,除非用户明确接受了仅服务器行为。 - 生成的页面覆盖预期的页面类型。
- 站点在真实浏览器中通过本地HTTP渲染。
- 桌面和移动端布局可用。
- 报告或修复控制台错误、失效交互、残留占位符和来自源站点的特有文本。
Contract
输入:
- 静态站点根目录,如
site/、dist/、out/、public/、docs/或仓库根目录。 - 可选的预期页面范围、本地预览URL、
EDITING.md、参考URL/截图及禁止的源站点特有字符串。
输出:
- 按严重程度排序的发现列表,或当验证作为构建/修复任务一部分时的修复结果。
- 静态审计结果、浏览器页面/视口检查情况及更改的文件列表(如有)。
- 明确的通过/失败状态,以指示是否可发布或交付。
边界:
- 不选择主题、重新创建网站、迁移内容、个性化身份或部署。
- 验证过程中不重新设计网站,除非视觉问题阻碍可用性且用户要求修复。
- 不批准根绝对路径,除非显式使用了
--allow-root-absolute且已说明其局限性。
成功门禁:
- 无阻塞性问题残留:主要导航断链、缺少必需页面类型、源编码不可读、本地资源失效、控制台崩溃、移动端不可用或意外根绝对路径问题。
- 警告要么已修复、已记录,要么被用户接受。
若门禁未通过:
- 在验证作为构建任务一部分时,修复直接的本地问题。
- 根据失败的面将较大问题路由至
make-personal-site、copy-website-style、personalize-site、add-blog-posts或edit-site-part。 - 重新运行确定性审计及相关浏览器检查。
Use With
在以下场景后使用此技能:
make-personal-site创建或重新设计了原始静态个人站点。copy-website-style将目标站点的样式重现为静态文件。- 用户指向一个现有静态输出文件夹并询问其质量是否足够。
- 用户在发布前要求检查、验证、QA、审查、审计或测试静态站点。
如果用户提供的是框架源码项目,尽可能验证已构建的静态输出文件夹。除非用户明确要求,否则不要在此引入框架构建工作流。
Inputs
使用任何可用的输入:
- 静态站点根文件夹,如
site/、dist/、out/或public/。 - 本地预览URL,如果服务器已在运行。
- 预期页面范围:仅首页、完整个人站点、博客、作品集、笔记、链接、样式重现等。
EDITING.md、页面地图或由其他技能产生的交接笔记。- 验证样式重现时的参考URL或截图。
- 已知不得残留的字符串,如原作者名、域名、邮箱、分析ID或旧的占位符文本。
如果站点根目录不明确,检查邻近文件夹并选择包含 index.html 和静态资产的文件夹。
Workflow
- 确定静态站点根目录和预期页面范围。
- 读取
EDITING.md或从HTML文件和导航链接推断页面地图。 - 运行确定性文件审计脚本。
- 启动或复用静态根目录的本地HTTP服务器。
- 在真实浏览器中以桌面和移动宽度验证站点。
- 为每个生成的页面类型打开至少一个代表性页面。
- 测试核心交互,如导航、主题切换、搜索/筛选、复制按钮、移动菜单和分页。
- 检查浏览器控制台错误和缺失的网络资源。
- 审计相对路径兼容性、占位符、UTF-8可读性和源特有残留文本。
- 当用户要求将验证作为构建一部分时,修复直接缺陷;否则先报告发现。
Deterministic File Audit
在浏览器验证前使用捆绑脚本:
python scripts/static_site_check.py <site-root>
对于样式重现或复制站点清理,传递禁止的源特有字符串:
python scripts/static_site_check.py <site-root> --forbid "original-author" --forbid "original-domain.com"
脚本检查:
- HTML、CSS、JS、JSON、Markdown、SVG、XML和文本文件的UTF-8解码。
- 可疑的乱码和替换字符。
- HTML文件中缺失
<meta charset="utf-8">。 - 损坏的本地
href、src、srcset、poster、action和data-src引用。 - 根绝对引用如
/assets/...、/posts/...、/data/...或/images/...,除非显式允许。 - CSS
url(...)资产引用,包括缺失或根绝对的本地URL。 - HTML、JavaScript和JSON数据中的常见根绝对站点本地字符串。
- 链接脱离站点根目录。
- 常见占位符字符串。
- 通过
--forbid提供的禁止字符串。 - 隐私敏感的部署根文件,如
.env、私钥、凭据文件和本地服务账户工件。 - 源文本中的秘密赋值、已知令牌模式、私钥块和本地绝对文件系统路径。
- 不应发布的临时文件、日志、备份和操作系统工件。
- HTML页面数量和推断的页面类型。
- 是否存在
EDITING.md。
文件审计仍应对供应商文件验证UTF-8可读性,但不应将第三方压缩供应商包中的类占位符词视为站点占位符内容。
将脚本错误视为阻塞性问题,除非用户只想进行快速探索性审查。将警告视为需要手动检查的项目。
如果站点有意设计为在自定义域根下使用根相对路径,则运行脚本时加上 --allow-root-absolute,并说明直接 file:// 打开和GitHub项目子路径部署不保证。除非用户明确接受此折衷,否则不要对生成的纯静态个人站点使用此例外。
Path Compatibility
生成的纯静态站点应在三种常见上下文中工作:
- 直接从文件系统打开
index.html进行快速手动预览。 - 通过本地HTTP提供文件夹服务,用于浏览器自动化和控制台/网络检查。
- 部署到可能从域根或子路径提供站点服务的静态主机。
默认规则:
- 使用页面相对路径引用站点内部链接和资产。
- 从根页面使用
assets/style.css、posts/example.html和about.html。 - 从嵌套页面使用
../assets/style.css、../blog.html及同层相对链接。 - 默认不使用
/assets/style.css、/posts/example.html、/data/posts.json、/images/foo.png或/进行内部导航。
还需检查JavaScript生成的链接、搜索结果、标签筛选器、复制按钮、动态卡片、RSS/站点地图引用、图片封面、CSS url(...) 值、favicon、字体及KaTeX/数学供应商资产。仅HTML属性相对是不够的,如果JavaScript后来插入了根绝对路径。
根绝对路径仅在用户明确希望仅服务器根部署(如自定义域根)且理解直接文件打开和GitHub项目Pages子路径可能失效时才可接受。
Browser Validation
在最终交付前使用真实浏览器。通过HTTP而非 file:// 提供本地文件服务:
python -m http.server 8000
然后打开:
http://127.0.0.1:8000/
对于本地HTTP目标,优先使用实际可用的交互式浏览器工具作为首选验证路径。“可用”意味着该工具在当前回合的可调用工具列表中公开,而不仅仅是技能、插件列表或系统描述中提及。在Codex中,这可能是Browser/应用内浏览器插件(当用户或客户端已将其路由到当前回合时);在其他智能体中,它可能是等效的可见浏览器、浏览器使用工具或devtools支持的浏览器。它应打开本地URL、检查桌面/移动视口、执行交互并检查可见的控制台/网络问题。
如果当前回合中没有可用的交互式浏览器工具,则不要假装浏览器验证已进行。如果验证依赖于它,请要求用户启用或调用浏览器工具(使用其客户端的路由方法);对于Codex,这可能意味着发送一个显式提到 @browser 的请求。如果用户未重新路由或客户端没有此类工具,则回退到Playwright、截图、静态审计或shell检查,并说明这是回退而非完整的交互式浏览器验证。
当交互式浏览器工具实际上可调用时,不要默认使用Playwright、仅无头截图脚本、shell打开的浏览器窗口或静态截图生成。截图是有用的证据,但不能替代交互式浏览器验证。仅在以下情况下使用Playwright作为回退:无交互式浏览器工具可调用、用户明确要求使用Playwright或明确需要可重复的脚本化回归测试。
仅在任务需要用户的Chrome配置文件、现有标签页、扩展、经过身份验证的远程页面或Chrome特定行为时使用Chrome自动化。不要依赖Chrome扩展自动化来处理 file:// 页面;应使用本地HTTP。
尽管自动化应使用本地HTTP,但生成的源仍应通过使用相对路径和避免仅服务器假设来保持直接打开兼容性。如果应用/浏览器允许快速 file:// 冒烟检查,则直接打开根 index.html 并验证CSS、图片、导航和代表性子页面未损坏。如果文件自动化不可用,则依赖确定性根绝对路径审计,并说明直接打开是否已手动或自动检查。
浏览器检查:
- 桌面首屏:构图、间距、排版、可见导航及明显溢出。
- 移动首屏:导航行为、文本换行、内容优先级及水平溢出。
- 内部导航:所有主要导航链接能正常渲染。
- 页面类型覆盖:每个生成页面类型至少一次浏览器检查或截图。
- 交互覆盖:主题切换、菜单、筛选器、搜索、复制按钮、分页、手风琴、标签页、悬停/点击状态或其他可见控件。
- 控制台状态:无明显JavaScript错误。
- 网络状态:无缺失的本地CSS、JS、图片或字体资产。
- 可访问性基础:交互控件的焦点可见性、可读对比度、有意义的页面标题及在可行时非空图片alt文本。
对于小型站点,点击每个生成的页面。对于较大站点,对每种页面类型及 EDITING.md 中提到的任何路由进行抽样。
Page-Type Coverage
从文件名、路由、可见导航和 EDITING.md 推断页面类型。
典型页面类型:
- 首页。
- 关于或简介。
- 博客、存档、分类、标签、笔记或列表页。
- 文章或详情页。
- 项目、作品集、出版物或工作页面。
- 链接、好友、资源、现在、使用、花园、搜索、主题/设置或其他特殊页面。
如果生成的站点声称是博客但没有文章/详情页,则报告此问题。如果导航指向不存在的子页面,则将其报告为阻塞性问题。
Encoding And Source Readability
仅浏览器截图是不够的。源文件必须对未来的模型和人类可读。
要求:
- HTML文件包含
<meta charset="utf-8">。 - 非ASCII文本存储为UTF-8。
- HTML、CSS注释、JavaScript字符串、JSON/数据文件、SVG文本和
EDITING.md在源码形式下可读。 - 无乱码、替换字符或意外的浏览器编码恢复。
如果终端显示乱码但浏览器看起来正确,在进行认定为损坏前,使用UTF-8感知读取进行确认。如果文件内容本身包含乱码,则从干净文本重写受影响的字符串,而不是叠加另一层编码转换。
Placeholder And Residue Audit
检查生成的站点是否仍包含:
TODO、FIXME、lorem ipsum、placeholder、replace me、your name、example.com或示例/演示文本。- 虚假邮箱、假社交链接、空按钮或失效行动号召。
- 样式重现中来自原始站点的作者名、域名、文章标题、邮箱、分析ID、社交链接、好友链接或私密URL。
如果用户仍需要这些占位符作为有意编辑标记,不要盲目移除。清楚地报告它们,或仅在用户提供了真实内容时替换。
Privacy And Local Residue
在发布前将以下文件视为阻塞性问题:
.env、.npmrc、.pypirc、私钥文件、凭据JSON文件、服务账户文件或密码保险库/导出文件位于可部署根目录内。- HTML、CSS、JavaScript、JSON、Markdown、SVG或文本文件中类似秘密的赋值、访问令牌、私钥块或API密钥。
- 生成源中的本地绝对文件系统路径,如Windows驱动器路径、
file:///...、/Users/...、/home/...或/mnt/...。
将日志、备份、临时文件和操作系统元数据视为警告,除非它们暴露了私有内容。在打包或发布前从可部署输出中移除它们。
Fix Policy
当用户要求“检查”、“审查”或“告诉我哪里有问题”时,首先报告发现,避免大规模编辑。
当验证是构建任务的一部分且用户预期修复时(例如在 make-personal-site 或 copy-website-style 之后),修复可以从审计结果中确定的明确本地问题。
对于自动修复,安全范围限于:
- 移除尾随空格和空行。
- 从相对路径中移除前导的
/,但仅当它们引用了站点本地资产且站点不是服务器根配置时。 - 修复缺失的
<meta charset="utf-8">。
避免:
- 重写占位符内容,除非用户提供了替换文本。
- 在未要求验证时更改布局、样式或结构。
- 移动文件或重写整个页面。
如果问题跨越多个页面且来源明确,考虑用单个编辑修复所有实例,但仅在修复是确定性且安全的时候。
对于视觉问题、缺失页面或框架级缺陷,路由到适当的技能。