Vibe Scaffold

Vibe Scaffold 是一个基于 Next.js 的开源工具，旨在解决当前 AI 编码助手常见的痛点：“接近但不完全正确” 的输出。它通过结构化的四步向导流程，引导用户逐步表达产品愿景，并生成可被 AI 智能体准确理解、迭代执行的技术文档。

这不是一个聊天机器人，而是一个需求工程工具——帮助你把模糊的想法，转化为清晰、连贯、可交付的技术规格。

核心价值

• 结构化输入：避免自由聊天导致的遗漏或歧义
• 上下文继承：每一步都基于前序文档，确保整体一致性
• 智能体就绪输出：最终生成 AGENTS.md，可直接用于 Claude Code、Kilo Code 等编码智能体
• 本地运行、数据自主：所有状态保存在浏览器 localStorage，无第三方数据上传

四步工作流

Vibe Scaffold 强制按顺序完成以下步骤，确保文档质量与逻辑完整性：

步骤 1：一页纸（One-Pager）

定义产品核心：

• 愿景与目标
• 目标用户画像
• MVP 功能清单

步骤 2：开发规范（Dev Spec）

细化技术实现：

• 系统架构图（文字描述）
• API 接口设计
• 数据模型（如数据库表结构）
• 关键实现细节与约束

步骤 3：提示计划（Prompt Plan）

拆解为 LLM 友好的任务单元：

• 分阶段开发计划
• 每阶段对应的 AI 提示模板
• 验收检查清单（Checklist）

步骤 4：AGENTS.md

生成智能体执行指南：

• 自动化流程说明
• 工具调用顺序
• 可复制的命令行指令（如 cline --config agents.yaml）
• 错误恢复与重试策略

每个步骤完成后需手动“批准”，才能进入下一步，防止跳步导致文档断裂。

关键功能

• ✅ AI 驱动聊天：内置 “Vibe Scaffold Assistant”，基于 OpenAI（默认 gpt-4o）进行上下文感知提问
• ✅ 实时流式生成：文档生成过程实时更新，避免长时间等待
• ✅ Markdown 预览：支持渲染视图与原始文本切换
• ✅ 文档导出：单文件下载（ALL_CAPS_UNDERSCORES.md）或一键打包 ZIP
• ✅ 示例预览：每个步骤提供格式示例，降低理解门槛
• ✅ 进度持久化：自动保存至 localStorage，刷新/重启不丢失
• ✅ 开发模式快捷加载：点击 LOAD_SAMPLES 可一键加载“照片字幕生成器”完整示例（仅限开发环境）

技术栈

• 框架：Next.js 14（App Router + Edge Runtime）
• 语言：TypeScript
• 样式：Tailwind CSS v3.4
• AI 集成：Vercel AI SDK + OpenAI API
• 状态管理：Zustand（支持 localStorage 持久化）
• 文档渲染：React Markdown
• 打包下载：JSZip

快速开始

1. 安装依赖

npm install

2. 配置环境变量

cp .env.example .env.local

编辑 .env.local：

# 必填
OPENAI_API_KEY=sk-...

# 可选
OPENAI_MODEL=gpt-4o        # 默认值
NEXT_PUBLIC_GA_ID=G-XXXXXX # Google Analytics（生产环境）

API 密钥请在 OpenAI 平台 获取。

3. 启动开发服务器

npm run dev

访问 http://localhost:3000，点击 Start Building Now 开始向导。

使用场景

• 个人开发者：将产品想法快速转化为可执行计划
• 初创团队：对齐技术方案，生成共享文档
• AI 智能体用户：为 Claude Code、Roo Code 等工具提供高质量输入
• 教学演示：展示如何结构化表达技术需求

数据与隐私

• 所有聊天记录、生成文档仅保存在本地浏览器（localStorage，键为 wizard-storage）
• 无任何数据上传至服务器（除非您主动集成 GA）
• 可完全离线使用（除 AI 生成需网络调用 OpenAI）