qzgu2-web-gen

面向 AI 网页设计、素材治理、前端生成和交付审查的命令行 Runtime。它让 Codex、Claude Code、WorkBuddy 或普通 API 模型围绕同一套 Brief、Design DNA、 素材清单、构建证据和质量门禁工作，而不是只生成一份无法持续维护的页面代码。

核心能力

• 支持 static-html 与 vue-vite 两种交付栈；
• 支持 guided、hybrid、generative 三种代码所有权模式；
• 内置 3 套原生主题和 67 套可离线装配的 Design Skill，共 70 套主题；
• 原生主题包括 iflytek、jun_green（军绿）和 zheng_red（正红）；
• 内置 12 套布局参考种子、1290 套 Refero 风格摘要和 40 套布局基因；
• 图片支持用户提供、独立生图 Provider、授权图库搜索和正式提示词任务卡；
• 自动生成桌面端与移动端 WebP 裁切，并要求正式素材审批；
• 提供代码检查、浏览器多视口截图、可选独立视觉模型审查和最终交付凭证；
• 为 Codex、Claude Code、WorkBuddy 和 Generic Agent 生成统一工作流说明。

安全的图片与截图协议

主 Coding Agent 的图片输入固定关闭。Agent 不读取截图、不调用宿主看图工具，也不把 PNG、JPEG、WebP、Base64、data URL 或 image_url 提交给主模型。

浏览器截图由 Runtime 独立保存；主模型只读取 JSON、文本问题和路径。需要视觉语义判断 时使用独立 visionReview Provider。缺少生图接口时，图片需求仍会保留为正式素材任务， 不会因为当前模型不能生图而静默降级成纯文字页面。

环境要求

• Node.js 20 或更高版本
• 可选 Chrome、Edge 或 Chromium，用于正式浏览器截图审查

安装

全局安装：

npm install --global qzgu2-web-gen
qzgu2-web-gen --version

也可以使用 npx 临时运行：

npx --yes qzgu2-web-gen --help

快速开始

创建项目：

mkdir my-web-project
cd my-web-project
qzgu2-web-gen init . --name "我的网页项目"

初始化后，把业务目标告诉 Coding Agent。Agent 应先读取当前工作流，再按阶段完成需求、 设计方向、素材、开发和验证：

qzgu2-web-gen command-log --limit 20
qzgu2-web-gen workflow

常用检查命令：

qzgu2-web-gen inspect
qzgu2-web-gen themes
qzgu2-web-gen layouts
qzgu2-web-gen validate

生成模式

Hybrid：推荐默认模式

AI 持有真实业务源码和布局，Runtime 负责协议、素材、质量门禁和交付证据。

qzgu2-web-gen init . --name "品牌官网" --mode hybrid --layout ai

Guided：稳定生成

Runtime 管理页面结构，适合标准化页面和可重复构建。

qzgu2-web-gen init . --name "标准页面" --mode guided --layout auto

Generative：开放创意

AI 可以重组章节、创建项目专属布局和组件语言，仍需通过相同质量门禁。

qzgu2-web-gen init . --name "创意专题" --mode generative --layout ai --creative-level open

主题

查看完整目录或生成离线中文预览图册：

qzgu2-web-gen themes
qzgu2-web-gen themes --json
qzgu2-web-gen themes --gallery

切换原生主题或装配式主题：

qzgu2-web-gen theme-use zheng_red
qzgu2-web-gen theme-use editorial

主题只定义视觉语言，不锁死 DOM、章节顺序或布局。AI 必须结合业务、内容、素材和场景 完成独立设计方向，再编译为项目 Design DNA。

图片素材

默认素材策略依次尝试用户文件、生图 Provider、授权图库和提示词任务卡：

qzgu2-web-gen assets
qzgu2-web-gen assets --strategy prompt-placeholder

配置 OpenAI-compatible 生图接口时使用环境变量：

export OPENAI_API_KEY="..."
export OPENAI_BASE_URL="https://your-provider.example/v1"
export OPENAI_IMAGE_MODEL="your-image-model"

生成或提供真实图片后重新运行 assets 和 build，并由用户批准正式素材：

qzgu2-web-gen asset-approve <素材ID>

构建与审查

qzgu2-web-gen design
qzgu2-web-gen validate
qzgu2-web-gen build
qzgu2-web-gen code-review
qzgu2-web-gen review
qzgu2-web-gen finalize

Vue 项目先在 site/ 中启动开发服务器，再把本机地址交给审查：

cd site
npm install
npm run dev

qzgu2-web-gen review --url http://localhost:5173

配置独立视觉审查 Provider：

export VISION_API_KEY="..."
export VISION_BASE_URL="https://your-provider.example/v1"
export VISION_MODEL="your-vision-model"

finalize 是唯一正式完成门禁。它会核对当前构建、代码审查、截图或服务器限制、素材 审批、交付目录和内容哈希，避免把预览占位页面误报为正式成品。

Workspace 结构

site/                 真实前端项目，也是唯一交付目录
public/assets/        用户提供或待处理的正式素材
design.md             当前项目视觉基线
.web-harness/         Brief、Design DNA、素材、构建和审查协议
AGENTS.md             Codex 工作流说明
CLAUDE.md             Claude Code 工作流说明
WORKBUDDY.md          WorkBuddy 工作流说明
WEB_HARNESS.md        通用 Agent 工作流说明

常用命令

qzgu2-web-gen --help
qzgu2-web-gen workflow --json
qzgu2-web-gen interaction-modes
qzgu2-web-gen scene-modes
qzgu2-web-gen composition-status
qzgu2-web-gen materials-status
qzgu2-web-gen iterate

许可证

qzgu2-web-gen 自有代码与内置设计资产采用专有许可证，版权所有 qzgu2。 第三方内容按随包附带的 THIRD_PARTY_NOTICES.md 及对应许可证使用。

许可咨询：[email protected]