Newshot

Show HN: WebCraft Pro – 为 AI 编码代理提供由 CI 强制执行的工程标准

Translation(model translation, not the source's own text)

WebCraft Pro — 面向 AI Agent 的完整 Web 工程工具包

WebCraft Pro Banner
WebCraft Pro Banner

有意图地设计。有纪律地工程化。默认安全。

WebCraft Pro 是一个开源、框架无关的集合,包含 43 个可复用的 Agent Skills、共享工程标准、实用示例和验证工作流,用于构建独具特色、可访问、高性能且安全的 Web 应用。

它为 AI 编码 Agent 提供了一套结构化的工程流程,覆盖完整的网站交付生命周期——从初始设计方向,到实现、可访问性、安全、性能、浏览器 QA 和发布。

1. 八阶段架构

WebCraft Pro 将工程生命周期组织为八个阶段:

阶段领域目的
01基础与 Agent 互操作性建立仓库约定、可移植技能、安装方式和共享 Agent 指令。
02设计智能定义视觉方向、设计系统、层级结构和产品专属界面。
03前端工程构建可维护组件、响应式布局、表单和前端架构。
04动效与 GSAP创建有目的的动画、滚动体验和可访问的动效系统。
05可访问性工程应用语义化 HTML、键盘导航、屏幕阅读器测试和面向 WCAG 的审查。
06Web 与 API 安全处理身份验证、授权、输入处理、API 风险、密钥和安全测试。
07性能工程测量并改进 Core Web Vitals、渲染、JavaScript、图片、字体和网络交付。
08浏览器自动化、QA 与发布验证渲染体验、浏览器行为、可访问性检查、截图和发布就绪状态。

各阶段目录提供路线图、验收标准和支持文档。规范技能保留在 skills/ 中,避免在各阶段和 AI Agent 之间重复技能说明。

2. 自动化质量与 CI 流水线

WebCraft Pro 包含互补的 GitHub Actions 工作流和浏览器验证工具。

仓库验证

Validate Repository 工作流检查:

  • 技能元数据和必需的前置元数据。
  • 技能目录和命名一致性。
  • 八阶段仓库结构。
  • 技能验证器测试。
  • 安装器测试。

零依赖安全模式审计

Security Pattern Audit 工作流运行一个使用 Node.js 标准库模块构建的 Node.js 静态模式扫描器。

它扫描以下内容中的 Markdown 代码围栏:

它检查的模式包括 eval()、new Function()、不安全的 innerHTML 赋值、document.write()、可能不安全的 href 值,以及通配符 postMessage() 来源。

该工作流测试扫描器、生成 JSON 报告、验证报告,并将其作为工件上传。

范围限制:这是对 Markdown 代码示例的静态模式审计——不是完整的应用安全扫描器,也不构成安全证明。

Playwright 可访问性键盘测试

Accessibility Keyboard Tests 工作流安装 Chromium 并执行 Playwright 键盘/焦点测试套件。

当前测试覆盖:

  • 跳转链接的键盘访问和焦点可见性。
  • 表单验证错误和焦点管理。
  • 对话框焦点进入、Escape 键关闭和焦点恢复。

Playwright 与 axe-core 浏览器检查器

该仓库还包含一个使用 Playwright 和 axe-core 的按需浏览器检查器。

它支持:

  • Chromium 浏览器验证。
  • 移动端、平板和桌面视口配置。
  • 标准和减少动效模式。
  • 键盘 Tab 顺序和可见焦点检查。
  • axe-core 可访问性扫描。
  • JavaScript 错误检测。
  • 截图和 JSON 报告。

该检查器可通过 Manual Browser Check 工作流使用。它与推送触发的键盘测试工作流相互独立。

自动化检查补充——而非替代——手动辅助技术测试、安全审查、跨浏览器验证和真实用户性能测量。

3. 技能与工程模板

43 个可复用的 Agent Skills

规范的 skills/ 目录包含 43 个可移植的 SKILL.md 文件,涵盖:

  • 设计智能与视觉质量。
  • 前端架构、组件工程,以及文档 head、SEO 和 meta 标签。
  • 响应式设计与现代 CSS。
  • GSAP、动效系统和交互式叙事。
  • 无障碍、WCAG 审计、键盘焦点和屏幕阅读器。
  • 应用安全、身份验证、授权和 API 安全。
  • Core Web Vitals、渲染、JavaScript、图像、字体和网络性能。

这些技能遵循 Agent Skills 格式,并按任务组织,而不是绑定到某一个前端框架。

13 个工程模板

该仓库包含 13 个实用模板,覆盖三个工程关键领域:

无障碍 — 5 个模板

  • 无障碍审计计划。
  • 语义审查检查清单。
  • 屏幕阅读器测试矩阵。
  • 无障碍审计报告。
  • 无障碍发现模板。

安全 — 3 个模板

  • OWASP 控制映射,包括示例性的 ASVS 5.0.0 和 API Security Top 10 映射。
  • 安全验证矩阵。
  • 安全审查报告。

性能 — 5 个模板

  • 性能审计模板。
  • Core Web Vitals 记录。
  • 性能测试矩阵。
  • 性能调查模板。
  • 性能预算模板。

这些模板帮助智能体和工程师一致地记录范围、测试条件、证据、发现、修复和发布决策。

为什么 WebCraft Pro 与众不同

WebCraft Pro 被设计为一个可重复的 Web 交付系统,而不仅仅是提示词集合或围绕首选前端技术栈的封装。

由 CI 强制执行,而不仅仅是提示词:其他仓库提供大量文本提示词,希望 LLM 遵循它们,而 WebCraft Pro 将工程指导转化为可验证的 CI 检查。它结合了仓库验证、零依赖安全模式审计和 Playwright 键盘/焦点测试。这些检查使已定义的工程要求可在 CI 中度量并强制执行,同时保持其范围明确。

2. 零依赖与框架无关

WebCraft Pro 不会将项目锁定到专有动画引擎,也不要求采用重型 UI 库来采纳其工程方法。它提供可移植的技能、共享标准和验证工作流;团队可以带上现有框架,仅在项目需要时选择实现依赖。

在协调动画足以证明其合理性的地方使用 GSAP,在更简单的效果中使用原生 CSS,并使用项目中已有的框架。可选库仍然是可选的。

3. 完整的 8 阶段生命周期

单一用途的技能对于聚焦任务可能很有价值,但 WebCraft Pro 将更广泛的交付流水线组织为八个相互连接的阶段:基础与智能体互操作、设计智能、前端工程、动效与 GSAP、无障碍、Web 和 API 安全、性能,以及浏览器 QA 和发布。

该架构将设计方向与实现同基于 OWASP 的安全工作、无障碍验证、性能测量和发布就绪连接起来。共享标准、模板和 CI 工作流在这些阶段之间提供连续性,而不是让每个任务成为孤立的提示词。

4. AI 智能体应如何使用 WebCraft Pro

WebCraft Pro 被设计为可复用的工程参考,而不是一套要盲目应用到每个项目的指令集合。

推荐的智能体工作流:

  • 理解仓库。阅读 README.md、AGENTS.md 和 stages/README.md,以理解项目约定和八阶段架构。
  • 识别任务。从 skills/README.md 中选择相关技能,并阅读其完整的 SKILL.md。

Show HN: WebCraft Pro – 面向 AI 编码代理的 CI 强制执行工程标准

  • 阅读工程标准。在做出领域特定决策之前,查阅 standards/ 中的相关文档。
  • 使用配套模板。从 examples/ 中选择合适的审计、测试矩阵、发现项、调查或报告模板。
  • 检查实际应用。根据现有框架、架构、用户旅程和约束调整指南。
  • 实施并验证。使用适当的测试、浏览器检查、无障碍审查,以及安全或性能证据。
  • 如实报告。记录变更内容、已测试内容、通过项、剩余风险以及未执行的检查。

安装

安装器支持三种代理环境:

代理项目本地目标位置
OpenAI Codex.agents/skills/
Claude Code.claude/skills/
GitHub Copilot.github/skills/

预览安装:


        node scripts/install-skills.mjs --agent all --target /path/to/project --dry-run
      

安装所有技能:


        node scripts/install-skills.mjs --agent all --target /path/to/project
      

使用 --agent codex、--agent claude 或 --agent copilot 为单个代理安装。现有技能目录会受到保护以免意外覆盖,除非明确提供 --overwrite。

5. 工程标准与项目理念

WebCraft Pro 维护以下方面的共享标准:

  • 设计质量。
  • 前端工程。
  • 动效工程。
  • 无障碍工程。
  • 安全工程。
  • 性能工程。

其核心原则是:

  • 优先采用经过深思熟虑、针对具体产品的设计,而不是通用界面。
  • 保持可维护的架构和现有项目约定。
  • 使用语义化 HTML 和无障碍交互模式。
  • 将安全视为工程要求,而不是最终检查清单。
  • 使用可复现的证据衡量性能。
  • 在能增加信心的场景使用自动化,同时记录其局限性。
  • 保持可复用技能与框架无关,除非某个技能明确针对某项技术。
  • 没有支持性证据时,绝不声称已完成验证、符合性或安全性。

项目状态

八阶段架构、43 个规范技能、共享标准以及 13 个 Stage 5–7 工程模板维护在仓库中。

最新提交是:

bcc99b078a8f956729c4b2276b921136bf3acf2e

以下工作流在该提交上验证通过:

  • Validate Repository。
  • Security Pattern Audit。
  • Accessibility Keyboard Tests。

WebCraft Pro 为 AI 辅助 Web 工程提供完整的结构化基础。单个应用在发布前仍需要针对项目的实施、测试和人工审查。

WebCraft Pro — 更好的界面。更好的工程。更安全的发布。

许可证

本项目根据 MIT License 授权 - 详情请参阅 LICENSE 文件。

第三方开发依赖许可证列于 THIRD_PARTY_LICENSES.txt。

作者身份与原创性免责声明

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗