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

有意图地设计。有纪律地工程化。默认安全。
WebCraft Pro 是一个开源、框架无关的集合,包含 43 个可复用的 Agent Skills、共享工程标准、实用示例和验证工作流,用于构建独具特色、可访问、高性能且安全的 Web 应用。
它为 AI 编码 Agent 提供了一套结构化的工程流程,覆盖完整的网站交付生命周期——从初始设计方向,到实现、可访问性、安全、性能、浏览器 QA 和发布。
1. 八阶段架构
WebCraft Pro 将工程生命周期组织为八个阶段:
| 阶段 | 领域 | 目的 |
|---|---|---|
| 01 | 基础与 Agent 互操作性 | 建立仓库约定、可移植技能、安装方式和共享 Agent 指令。 |
| 02 | 设计智能 | 定义视觉方向、设计系统、层级结构和产品专属界面。 |
| 03 | 前端工程 | 构建可维护组件、响应式布局、表单和前端架构。 |
| 04 | 动效与 GSAP | 创建有目的的动画、滚动体验和可访问的动效系统。 |
| 05 | 可访问性工程 | 应用语义化 HTML、键盘导航、屏幕阅读器测试和面向 WCAG 的审查。 |
| 06 | Web 与 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/ 中选择合适的审计、测试矩阵、发现项、调查或报告模板。
- 检查实际应用。根据现有框架、架构、用户旅程和约束调整指南。
- 实施并验证。使用适当的测试、浏览器检查、无障碍审查,以及安全或性能证据。
- 如实报告。记录变更内容、已测试内容、通过项、剩余风险以及未执行的检查。
安装
安装器支持三种代理环境:
预览安装:
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。
作者身份与原创性免责声明