快速开始：从想法到应用

学完你能做什么

读完本课，你将：

了解 AI App Factory 如何帮你快速将想法转化为可运行应用
完成第一个 Factory 项目的初始化
启动流水线并跟随 7 个阶段生成你的第一个 MVP 应用

你现在的困境

"有个产品想法，但不知道从哪开始"

你是不是也遇到过这种情况：

有一个产品想法，但不知道如何拆解成可执行的需求
前端、后端、数据库、测试、部署……每一项都要花时间
想快速验证想法，但搭建开发环境就要好几天
写完代码才发现需求理解错了，推倒重来

AI App Factory 就是为解决这些问题而生的。

什么时候用这一招

AI App Factory 适合这些场景：

✅ 快速验证产品想法：想试试这个想法是否可行
✅ 创业项目的 0-1 阶段：需要快速交付可演示的原型
✅ 内部工具和管理系统：不需要复杂权限，简单实用就好
✅ 学习全栈开发最佳实践：看 AI 如何生成生产级代码

不适合这些场景：

❌ 复杂的企业级系统：多租户、权限系统、高并发
❌ 需要高度定制的 UI：有独特设计系统的项目
❌ 实时性要求极高的系统：游戏、视频通话等

🎯 核心思路

AI App Factory 是一个基于检查点的智能应用生成系统，通过多 Agent 协作流水线，自动将你的产品想法转化为包含前后端代码、测试、文档的完整可运行应用。

三个核心价值：

1. 端到端自动化

从想法到代码，全自动完成：

输入：一句话描述你的产品想法
输出：完整的前后端应用（Express + Prisma + React Native）
中间过程：自动完成需求分析、UI 设计、技术架构、代码生成

2. 检查点机制

每个阶段完成后暂停，等待你确认：

✅ 防止错误累积，确保每一步都符合预期
✅ 你可以随时调整方向，避免到最后才发现跑偏了
✅ 失败时自动回滚，不会浪费时间在错误的代码上

3. 生产就绪

生成的不是玩具代码，而是可以直接上线的生产级应用：

✅ 完整的前后端代码
✅ 单元测试和集成测试（>60% 覆盖率）
✅ API 文档（Swagger/OpenAPI）
✅ 数据库种子数据
✅ Docker 部署配置
✅ CI/CD 流水线（GitHub Actions）
✅ 错误处理和日志监控
✅ 性能优化和安全检查

7 阶段流水线：

Bootstrap → PRD → UI → Tech → Code → Validation → Preview
   ↓          ↓    ↓     ↓      ↓         ↓          ↓
结构化   产品   UI   技术    代码      验证      部署
想法      需求  设计  架构    生成      质量      指南

🎒 开始前的准备

必备工具

1. Node.js >= 16.0.0

bash

# 检查 Node.js 版本
node --version

如果未安装或版本过低，从 nodejs.org 下载安装。

2. AI 编程助手（必需） ⚠️ 重要

AI App Factory 的 Agent 定义和 Skill 文件是 Markdown 格式的 AI 指令，必须通过 AI 助手来解读和执行。人工无法直接运行这些流水线。

推荐使用以下工具之一：

Claude Code (https://claude.ai/code) - 推荐 ⭐
OpenCode 或其他支持 Agent 模式的 AI 助手

为什么必须用 AI 助手？

本项目的核心是 AI Agent 系统，每个阶段都需要 AI 助手：

读取 .agent.md 文件了解自己的任务
加载对应的 Skill 文件获取知识
严格按照指令生成代码和文档

人工无法替代这个过程，就像你不能用记事本运行 Python 代码一样。

3. 全局安装 CLI 工具

bash

npm install -g agent-app-factory

验证安装：

bash

factory --version

你应该看到版本号输出。

准备产品想法

花 5 分钟写下你的产品想法。越详细的描述，生成的应用越符合预期。

好的描述示例：

✅ 一个帮助健身新手记录训练的应用，支持记录运动类型（跑步、游泳、健身房）、时长、消耗卡路里，并查看本周训练统计。不需要多人协作，不做数据分析，聚焦个人记录。

差的描述示例：

❌ 做一个健身应用。

跟我操作

第 1 步：创建项目目录

在任意位置创建一个空目录：

bash

mkdir my-first-app && cd my-first-app

第 2 步：初始化 Factory 项目

运行初始化命令：

bash

factory init

为什么 这会创建 .factory/ 目录，并复制所有必要的 Agent、Skill、Policy 文件，让当前目录成为一个 Factory 项目。

你应该看到：

✓ 已创建 .factory/ 目录
✓ 已复制 agents/, skills/, policies/, pipeline.yaml
✓ 已生成配置文件: config.yaml, state.json
✓ 已生成 Claude Code 权限配置: .claude/settings.local.json
✓ 已尝试安装必需插件 (superpowers, ui-ux-pro-max)

如果看到错误提示，请检查：

目录是否为空（或仅包含配置文件）
Node.js 版本是否 >= 16.0.0
是否已全局安装 agent-app-factory

目录结构

初始化后，你的目录结构应该是：

my-first-app/
├── .factory/
│   ├── agents/              # Agent 定义文件
│   ├── skills/              # 可复用的知识模块
│   ├── policies/            # 策略和规范
│   ├── pipeline.yaml         # 流水线定义
│   ├── config.yaml          # 项目配置
│   └── state.json           # 流水线状态
└── .claude/
    └── settings.local.json  # Claude Code 权限配置

第 3 步：启动流水线

在 AI 助手中（推荐 Claude Code），执行以下指令：

请阅读 pipeline.yaml 和 agents/orchestrator.checkpoint.md，
启动流水线，帮我将这个产品想法转化为可运行的应用：

[粘贴你的产品想法]

为什么 这会让 Sisyphus 调度器启动流水线，从 Bootstrap 阶段开始，将你的想法一步步转化为代码。

你应该看到：

AI 助手会：

读取 pipeline.yaml 和 orchestrator.checkpoint.md
显示当前状态（idle → running）
启动 Bootstrap Agent，开始结构化你的产品想法

第 4 步：跟随 7 个阶段

系统会按以下 7 个阶段执行，每个阶段完成后会暂停并要求你确认：

阶段 1: Bootstrap - 结构化产品想法

输入：你的产品描述输出：input/idea.md（结构化的产品文档）

确认内容：

问题定义：解决什么问题？
目标用户：谁会遇到这个问题？
核心价值：为什么需要这个产品？
关键假设：你的假设是什么？

你应该看到：

AI 助手会询问：

✓ 已完成 Bootstrap 阶段
生成的文档: input/idea.md

请确认：
1. 继续下一阶段
2. 重试当前阶段（提供修改建议）
3. 暂停流水线

仔细阅读 input/idea.md，如果有不符合的地方，选择"重试"并提供修改建议。

阶段 2: PRD - 生成产品需求文档

输入：input/idea.md输出：artifacts/prd/prd.md

确认内容：

用户故事：用户会如何使用这个产品？
功能列表：需要实现哪些核心功能？
非目标：明确不做什么（防止范围蔓延）

阶段 3: UI - 设计 UI 结构和原型

输入：artifacts/prd/prd.md输出：artifacts/ui/ui.schema.yaml + 可预览的 HTML 原型

确认内容：

页面结构：有哪些页面？
交互流程：用户如何操作？
视觉设计：配色方案、字体、布局

特色：集成 ui-ux-pro-max 设计系统（67 种样式、96 种调色板、100 条行业规则）

阶段 4: Tech - 设计技术架构

输入：artifacts/prd/prd.md输出：artifacts/tech/tech.md + artifacts/backend/prisma/schema.prisma

确认内容：

技术栈：使用什么技术？
数据模型：有哪些表？字段是什么？
API 设计：有哪些 API 端点？

阶段 5: Code - 生成完整代码

输入：UI Schema + Tech 设计 + Prisma Schema 输出：artifacts/backend/ + artifacts/client/

确认内容：

后端代码：Express + Prisma + TypeScript
前端代码：React Native + TypeScript
测试：Vitest（后端）+ Jest（前端）
配置文件：package.json, tsconfig.json 等

阶段 6: Validation - 验证代码质量

输入：生成的代码输出：artifacts/validation/report.md

确认内容：

依赖安装：npm install 是否成功？
类型检查：TypeScript 编译是否通过？
Prisma 验证：数据库 Schema 是否正确？

阶段 7: Preview - 生成部署指南

输入：完整的代码输出：artifacts/preview/README.md + GETTING_STARTED.md

确认内容：

本地运行说明：如何在本地启动前后端？
Docker 部署：如何使用 Docker 部署？
CI/CD 配置：如何配置 GitHub Actions？

检查点 ✅

完成所有 7 个阶段后，你应该看到：

✓ 已完成所有流水线阶段
最终产物:
- artifacts/prd/prd.md (产品需求文档)
- artifacts/ui/ui.schema.yaml (UI 设计)
- artifacts/tech/tech.md (技术架构)
- artifacts/backend/ (后端代码)
- artifacts/client/ (前端代码)
- artifacts/validation/report.md (验证报告)
- artifacts/preview/GETTING_STARTED.md (运行指南)

下一步: 查看 artifacts/preview/GETTING_STARTED.md 开始运行应用

恭喜你！你的第一个 AI 生成应用已经完成了。

第 5 步：运行生成的应用

按照生成的指南运行应用：

bash

# 后端
cd artifacts/backend
npm install
npm run dev

# 新开一个终端窗口，运行前端
cd artifacts/client
npm install
npm run web  # Web 版
# 或
npm run ios      # iOS 模拟器
# 或
npm run android  # Android 模拟器

你应该看到：

后端启动在 http://localhost:3000
前端启动在 http://localhost:8081（Web 版）或在模拟器中打开

踩坑提醒

❌ 错误 1：目录非空

错误提示：

✗ 目录非空，请清理后重试

原因：初始化时目录中已有文件

解决方法：

bash

# 方式 1：清理目录（仅保留隐藏配置文件）
ls -a    # 查看所有文件
rm -rf !(.*)

# 方式 2：创建新目录
mkdir new-app && cd new-app
factory init

❌ 错误 2：AI 助手无法理解指令

错误现象：AI 助手报错"无法找到 Agent 定义"

原因：未在 Factory 项目目录中运行

解决方法：

bash

# 确保在包含 .factory/ 目录的项目根目录中
ls -la  # 应该能看到 .factory/
pwd     # 确认当前目录

❌ 错误 3：Claude CLI 未安装

错误提示：

✗ Claude CLI 未安装，请访问 https://claude.ai/code 下载

解决方法：

从 https://claude.ai/code 下载并安装 Claude Code CLI。

本课小结

本课你学会了：

AI App Factory 的核心价值：端到端自动化 + 检查点机制 + 生产就绪
7 阶段流水线：Bootstrap → PRD → UI → Tech → Code → Validation → Preview
如何初始化项目：factory init 命令
如何启动流水线：在 AI 助手中执行指令
如何跟随流水线：每个阶段完成后确认，确保输出符合预期

关键要点：

必须配合 AI 助手使用（Claude Code 推荐）
提供清晰详细的产品描述
在每个检查点仔细确认，避免错误累积
生成的代码是生产级的，可以直接使用

下一课预告

下一课我们学习 安装与配置。
你会学到：
如何全局安装 Agent Factory CLI
如何配置 AI 助手（Claude Code / OpenCode）
如何安装必需的插件（superpowers, ui-ux-pro-max）

附录：源码参考

点击展开查看源码位置

更新时间：2026-01-29

功能	文件路径	行号
CLI 入口	`cli/bin/factory.js`	1-123
init 命令实现	`cli/commands/init.js`	-
run 命令实现	`cli/commands/run.js`	-
continue 命令实现	`cli/commands/continue.js`	-
流水线定义	`pipeline.yaml`	-
调度器定义	`agents/orchestrator.checkpoint.md`	-

关键配置：

pipeline.yaml：定义了 7 个阶段的流水线顺序和每个阶段的输入输出
.factory/state.json：维护流水线的运行状态（idle/running/waiting_for_confirmation/paused/failed）

核心流程：

factory init → 创建 .factory/ 目录，复制 Agent、Skill、Policy 文件
factory run → 读取 state.json，检测 AI 助手类型，生成助手指令
factory continue → 重新生成 Claude Code 权限配置，启动新会话继续执行

快速开始：从想法到应用 ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎯 核心思路 ​

1. 端到端自动化 ​

2. 检查点机制 ​

3. 生产就绪 ​

🎒 开始前的准备 ​

必备工具 ​

准备产品想法 ​

跟我操作 ​

第 1 步：创建项目目录 ​

第 2 步：初始化 Factory 项目 ​

第 3 步：启动流水线 ​

第 4 步：跟随 7 个阶段 ​

阶段 1: Bootstrap - 结构化产品想法 ​

阶段 2: PRD - 生成产品需求文档 ​

阶段 3: UI - 设计 UI 结构和原型 ​

阶段 4: Tech - 设计技术架构 ​

阶段 5: Code - 生成完整代码 ​

阶段 6: Validation - 验证代码质量 ​

阶段 7: Preview - 生成部署指南 ​

检查点 ✅ ​

第 5 步：运行生成的应用 ​

踩坑提醒 ​

❌ 错误 1：目录非空 ​

❌ 错误 2：AI 助手无法理解指令 ​

❌ 错误 3：Claude CLI 未安装 ​

本课小结 ​

下一课预告 ​

附录：源码参考 ​

快速开始：从想法到应用

学完你能做什么

你现在的困境

什么时候用这一招

🎯 核心思路

1. 端到端自动化

2. 检查点机制

3. 生产就绪

🎒 开始前的准备

必备工具

准备产品想法

跟我操作

第 1 步：创建项目目录

第 2 步：初始化 Factory 项目

第 3 步：启动流水线

第 4 步：跟随 7 个阶段

阶段 1: Bootstrap - 结构化产品想法

阶段 2: PRD - 生成产品需求文档

阶段 3: UI - 设计 UI 结构和原型

阶段 4: Tech - 设计技术架构

阶段 5: Code - 生成完整代码

阶段 6: Validation - 验证代码质量

阶段 7: Preview - 生成部署指南

检查点 ✅

第 5 步：运行生成的应用

踩坑提醒

❌ 错误 1：目录非空

❌ 错误 2：AI 助手无法理解指令

❌ 错误 3：Claude CLI 未安装

本课小结

下一课预告

附录：源码参考