# agent-appforge

**Repository Path**: codeWhh/agent-appforge

## Basic Information

- **Project Name**: agent-appforge
- **Description**: AI 编排自动化生成 app
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent-Appforge

AI Agent 驱动的多端自动开发系统。输入一句话描述 → Agent 自动生成需求文档、契约、脚手架、代码、集成验证，直到所有端构建通过。

```
用户输入 "一个待办事项 CRUD 应用"
  ↓
① 环境自检 → ② 引导采集 → ③ 需求文档 [GATE] → ④ 设计系统 [GATE] → ⑤ 契约定义 + codegen [GATE]
  ↓
⑥ 工程骨架 → ⑦ 并行编码(Claude Code) → ⑧ 集成验收 [GATE] → ⑨ 生产报告
```
## 支持的端

| 端 | 技术栈 | 说明 |
|----|--------|------|
| API | NestJS(TS) / FastAPI(Python) / Spring Boot(Java) / Gin(Go) | OpenAPI 语言无关先行，按 `apiStack` 路由，env_check 按栈检查工具链 |
| Web | React+Zustand(默认) / Next.js / Vue+Pinia / Nuxt / Astro+Svelte | 前台，按 `webStack` 路由到对应确定性生成器 |
| Admin | React+AntD Pro(默认) / React+shadcn/ui / Vue+Element Plus / Vue+Naive UI | 后台管理，按 `adminStack` 路由到对应确定性生成器 |
| uni-app x | UTS / uni-app x | 微信小程序 / Android / iOS / 鸿蒙 |

> Web/Admin 的每个技术栈在 scaffold 阶段生成对应的确定性骨架（package.json + 构建配置 + 框架入口），verify 阶段按框架产物目录校验（如 Next.js 查 `.next/BUILD_ID`，Nuxt 查 `.output/`）。详见 [设计规格 §5.1](docs/multi-platform-auto-builder-spec.md)。

## 快速开始

```bash
git clone <repo> && cd agent-appforge
pnpm install
pnpm start          # 启动（检查依赖 → 构建 → dev 模式 web-ui）
```

开发/测试常用命令：

```bash
pnpm test           # 运行单测（vitest，编排层纯函数 + safePath 等）
pnpm typecheck      # 全量 TypeScript 类型检查
pnpm build          # 全量构建
```

`pnpm start` 自动检查依赖 → 构建 → 以 dev 模式启动 web-ui（Fastify 后端 5181 + Vite 前端 5180 带 HMR）。浏览器打开 `http://localhost:5180`，填项目信息、选端和技术栈、开始生产。

### web-ui 开发（组件 / 样式调试）

web-ui 拆分为 props 驱动的展示组件（`GateWorkbench` / `VerifyResults` / `RecordDashboard` / `DirTree` 等），配合三套工具做 UI 开发：

```bash
# 组件级隔离预览（Ladle）—— 单个组件的多种状态，专注调样式细节
pnpm --filter @agent-appforge/web-ui ladle

# 页面级场景预览（Playground）—— 无需后端/API key，22 个场景覆盖全部 UI 状态
pnpm --filter @agent-appforge/web-ui dev:vite
# 浏览器打开 http://localhost:5180/?preview=1

# 真实管线完整体验（需要 Claude Code CLI + provider 配置）
pnpm start
# 浏览器打开 http://localhost:5180
```

web-ui 技术栈：React 18 + Vite + Tailwind v4 + Zustand + Ladle。样式用 Tailwind 设计令牌（`src/index.css` 的 `@theme` 块定义语义色），组件代码在 `src/components/`，Playground 场景在 `src/preview/`。

**前置条件**：Node 22、pnpm、git、Python 3、Claude Code CLI（`npm i -g @anthropic-ai/claude-code`）。生成含 UI 的端（web/admin/uni-app）还需在 `~/.claude/skills/` 安装 `ui-ux-pro-max`（设计系统数据库查询）与 `frontend-design`（反模板化哲学）两个 Claude Code 技能——环境自检节点（①）会按所选端验证。详见 [安装指南](docs/setup-guide.md)。

## 核心特性

**九阶段全自动管线** — 从一句话描述到可构建的多端 monorepo，四个 GATE 供人工确认/打回。④ 设计系统节点用 ui-ux-pro-max 数据库 + frontend-design 反模板化哲学产出 MASTER.md / tokens.json，作为各端 UI 的单一事实来源，并通过 verify 节点的静态设计 lint（token 消费率 / 禁用 emoji 图标 / 单色系检测）兜底。

**三层防 529/429** — 高峰期 provider 过载时自动退避重试（全异步，不阻塞 web-ui 事件循环），不丢状态：
- L0 模型降级（glm-4.7 → 4.6 → 5.1 → 5v-turbo → 4.7-flash → 4.5-air）
- L1 退避重试（指数退避，4 轮/模型）
- L2 自动恢复探测（等 3 分钟定时探测，3 轮后才暂停）

**日志持久化** — 节点日志 + 生产报告持久化到 SQLite（与 LangGraph checkpoint 同库），server 重启不丢。详细事件处理（Claude assistant 文本 + tool_use 工具调用摘要），前端实时展示 + 按节点归档。

**MemoryStore 经验复用** — 五个节点全覆盖，跨项目积累经验：
- 系统层：9 条已验证的坑点（prisma 顺序、esbuild 冲突、claude CLI 参数等）
- 项目层：record 节点自动把失败平台的 errorMessage 写成 pitfall，下次自动避坑

**契约治理** — OpenAPI 作为单一事实来源，冻结后变更检测（D8），gate 处 Codex 交叉评审（D5）。

**断点恢复** — 每个节点 git checkpoint（G4），失败计数 + 自动重试。中断卡死检测（3 分钟无活动提示恢复）+ `POST /api/resume` 从 checkpoint 续跑。

## 项目结构

```
agent-appforge/
├── apps/
│   ├── orchestrator/        # LangGraph.js 编排器（9 节点 + 4 GATE + 熔断器）
│   └── web-ui/              # React + Vite + Tailwind v4 + Ladle 组件预览 + Playground 场景回放
├── packages/
│   ├── claude-runner/       # Claude Code headless 封装（L0 降级 + L1 退避）
│   ├── scaffold-templates/  # 确定性脚手架（api 4 栈 + web 5 栈 + admin 4 栈 + uni-app/root）
│   └── memory-store/        # 三层 skill 库（system/user/project）
├── skills/                  # 系统层经验（9 条，随仓库分发）
├── docs/                    # 设计文档 + 阶段报告 + 安装指南（生成项目的 docs/design/MASTER.md 在此体系下产出）
├── bin/agent-appforge.mjs     # CLI 入口
└── scripts/start.sh         # 一键启动
```

> 生成的项目写到用户选择的 `targetDir`，不落在本仓库。

## 技术栈

- 编排器：LangGraph.js（TypeScript）
- 编码执行体：Claude Code CLI（headless）
- 交叉评审：Codex CLI（可选，gate 处调用）
- Provider：智谱 glm-5.2（默认，支持多模型降级链）
- 记忆后端：FileMemoryStore（三层文件系统）
- web-ui：React 18 + Tailwind v4 + Zustand + Ladle（组件级预览）

## 配置

编辑 `~/.claude/settings.json`：

```json
{
  "model": "glm-4.7",
  "apiKeyHelper": "echo YOUR_API_KEY",
  "apiBaseUrl": "https://open.bigmodel.cn/api/anthropic"
}
```

可选配降级模型（不配则用内置默认链）：

```json
{
  "model": "glm-4.7",
  "fallbackModels": ["glm-4.6", "glm-5.1", "glm-4.7-flash"]
}
```

环境变量覆盖（优先级最高，换 provider 不改代码）：

```bash
export AGENT_APPFORGE_MODELS=glm-4.7,glm-4.6,glm-5.1,glm-4.7-flash
```

详见 [Provider 配置 + FAQ](docs/setup-guide.md#10-claude-provider-配置)。

## 文档

- [架构规格](docs/multi-platform-auto-builder-spec.md) — 完整规格（§0-§15）
- [实现细节](docs/design-details.md) — DD-1 ~ DD-7
- [安装指南](docs/setup-guide.md) — 环境配置 + Provider + FAQ
- [构建集成踩坑](docs/build-integration-pitfalls.md) — M1 真实集成记录
- [历史里程碑报告](docs/archive/) — M1/M2/M3 验证 + 完整版进度（已归档，内容为对应时间点的快照）

## 验证状态

| 里程碑 | 范围 | 状态 |
|--------|------|:----:|
| M0 | Todo POC 端到端 | ✅ |
| M1 | api+web+admin 骨架 + 真实构建 | ✅ |
| M2 | uni-app x mp-weixin 可靠度 | ✅ |
| M3 | 全四端 + App handoff + verify/record | ✅ |
| 完整版 | L0 降级 + MemoryStore + D5/D8/G4 + 多语言后端 | ✅ |
| E2E | 16/16 端到端验证全绿 | ✅ |

## License

MIT