# agent-appforge

**Repository Path**: libokang/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-06-26
- **Last Updated**: 2026-07-14

## 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 图标 / 单色系检测）兜底。

**多项目并行管理** — 同时启动多个项目，每个 run 独立 targetDir，真并行推进（互不阻塞）。项目总览页（卡片网格）展示所有 run 的实时进度，点击切换面板，后台 WS 保持连接不中断。页面刷新后从 run_meta 表恢复历史 run 列表。

**run 生命周期与 HTTP 解耦** — run 执行器独立于 HTTP handler（fire-and-forget），handler 异常不 kill run。进程崩溃遗留的 run 自动标记为 interrupted，启动时可手动 /api/resume 续跑。runId 以 ULID 风格生成（防碰撞）。

**三层防 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 续跑。进程崩溃后 run 被标记为 interrupted，启动时自动扫描恢复。

**显式 runId 日志路由** — orchestator 的 `log()` 通过 AsyncLocalStorage 注入 LogSink，server 端直接 broadcast + appendLog（显式 runId 关联），淘汰了全局 console.log monkey-patch 和 lastActiveRunId 单变量（后者在并发时会导致日志串流）。多 run 并行时日志精确路由到各自的 run。

**第三方 Provider 兼容加固** — Claude Code CLI 自动注入的 ToolSearch/TaskCreate 等内置 agentic 工具（Anthropic 格式），在转发到智谱 GLM 等第三方 provider 时会触发 `400 [1210]`。ClaudeRunner 默认传 `--disallowed-tools` 禁用这些工具。

**重跑失败端闭环** — smoke_gate revise 重跑时，build 节点注入上次 verify 失败的可操作诊断（哪些文件、多少硬编码色值），doneCriteria 追加 design lint 完成标准（色值使用 var(--token) 变量、无 emoji 图标），Claude 自循环验证时纳入目标。designLint 排除 JS 对象属性色值（colorPrimary: "#xxx" 为合法的 AntD/MUI 主题配置）。

## 项目结构

```
	agent-appforge/
	├── apps/
	│   ├── orchestrator/        # LangGraph.js 编排器（9 节点 + 4 GATE + 熔断器）
	│   └── web-ui/              # React + Vite + Tailwind v4 + Ladle + Playground
	│       ├── server/          # Fastify 后端（按模块组织）
	│       │   ├── db/          # SQLite 仓储：run-logs / run-reports / run-meta
	│       │   ├── ws/          # WS 订阅管理 + broadcast（消息带 runId）
	│       │   ├── run/         # RunExecutor（stream 与 HTTP 解耦）+ graph-helpers + lifecycle
	│       │   └── fs/          # safe-path + 目录树遍历
	│       └── src/
	│           ├── store.ts     # Zustand（多 run：runs map + selector 层 + WS 共享路由）
	│           ├── components/  # Step1Form / OverviewPage / 14+ 共享组件
	│           └── preview/     # Playground 场景回放
	├── packages/
	│   ├── claude-runner/       # Claude Code headless（L0 降级 + L1 退避 + disallowedTools）
	│   ├── 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 端到端验证全绿 | ✅ |
	| V2 | 多项目并行 + 架构治本 + 重跑闭环 | ✅ |

	## 更新日志

	### V2（Multi-Run Architecture）

	- **多项目并行管理**：项目总览页（OverviewPage），卡片网格展示所有 run 的实时进度，点击切换面板，后台 WS 保持连接不中断。`startRun`/`switchRun`/`patchRun` 等多 run actions，store 重构为 `runs: Record<runId, RunSlice>` + selector 层。
	- **run 生命周期与 HTTP 解耦**：RunExecutor（stream 驱动独立于 HTTP handler），fire-and-forget，handler 异常不 kill run。run_meta 持久化表（重启后 /api/runs 不丢）。崩溃恢复（interrupted 状态自动扫描）。
	- **显式 runId 日志路由**：LogSink 替代全局 console.log monkey-patch，淘汰 lastActiveRunId 单变量。并发多 run 时日志精确路由到各自的 run，不再串流。
	- **重跑失败端闭环**：designLint 返回可操作诊断（命中文件、色值数量），doneCriteria 追加 design lint 完成标准。AntD/MUI 主题配置的 JS 属性色值不再误判（排除 camelCase: "#xxx" 模式）。
	- **第三方 Provider 兼容加固**：ClaudeRunner 默认 `--disallowed-tools "ToolSearch,TaskCreate,TaskUpdate,TaskList,TodoWrite"`，避免 GLM 等第三方 provider 收到 Anthropic 格式的内置工具 schema 时 400 错误。
	- **NODE_ORDER 单一来源**：前端 3 处重复定义统一到 labels.ts，加节点只需改一处。
	- **139+ 测试**：全部 5 包 typecheck 通过 + 145 个测试全绿。

	## License

MIT