乌托邦（Utopia）— AI 原生工程框架

一套面向 AI 原生工程团队的公共工程框架 · v0.3.0

代码库：http://75.101.196.174/base/utopia.git

乌托邦把 Agent 工作规则、Monorepo 目录、项目 Overlay、契约优先、架构能力门禁、测试门禁、红蓝对抗 Review、日志沉淀和框架升级流程放进同一个可版本化仓库。它的目标不是替代业务项目，而是给每个业务项目提供一套可复制、可升级、可审计的工程底座。

乌托邦的 Core 是 Agent-neutral 的：Codex、Claude Code 等工具通过 Adapter 接入，不能把某个工具的使用习惯写成公共框架底线。

核心价值

1. 让 AI Agent 在统一规则下工作，而不是每次靠提示词临场发挥。
2. 让 PRD 需求 ID、OpenAPI、测试、日志、ADR 和验收证据成为可追踪的交付闭环。
3. 让新项目通过 .ai-framework 子仓库继承公共能力，并用 docs/project/** 保留项目自由度。
4. 让框架升级通过 devtools/framework plan/apply 可预览、可追踪、可回滚。
5. 让执行规则和学习资料分层：Core 承载 AI 可执行规则，Handbook 承载团队学习材料。
6. 让复杂业务不能被简单 CRUD、同步接口、本地资源或无观测方案糊弄过去；MVP 可以分阶段做，但必须有架构判断。
7. 让团队成员也按规则使用 AI：任务必须有需求 ID、目录边界、owner review、验收证据和明确合入判断。

核心裁决原则

AI Agent 只有完成申请权，没有完成裁决权。Agent Claim 只能是 implemented、verified、blocked；只有 Project Decision 才能裁决 accepted、rejected 或 released。

框架分层

framework/
  core/           # 所有项目必须具备的最小工程规则和工具
  adapters/       # Codex、Claude Code 等 Agent runtime 适配器模板
  profiles/       # mobile-app、go-gin-api、laravel-app、nuxt-web、fullstack-monorepo、custom
  quality-gates/  # 架构能力、UI 视觉验收、性能/SLO 等按需门禁
  examples/       # 参考样例，不作为项目运行时代码

apps/
  mobile/         # 移动 App
  web/            # 官网、下载页、PC/H5/Public Web，默认 Nuxt 4 + Tailwind CSS v4
  admin/          # 统一后台管理前端，可对接 Go Gin 或 Laravel Admin API

services/
  go-app/         # Go Gin 核心应用服务：Public API、Admin API、领域逻辑
  laravel-app/    # Laravel 完整应用：Web/API/Filament/Console/Jobs
  realtime/       # WebSocket、IM、在线状态、事件
  worker/         # 异步任务、回调、定时任务

packages/
  contracts/      # OpenAPI、事件、错误码、DTO
  ts/             # 前端/Node TypeScript 公共包
  go/             # Go 公共包
  php/            # PHP/Laravel 公共包
  ui/             # mobile/web/admin 分层 UI 资产

Core 与 Handbook 分离

本仓库是乌托邦 Core，负责 AI 执行规则、模板、validator、同步机制、质量门禁和项目初始化能力。它会作为业务项目的 .ai-framework 子仓库接入，因此必须保持短、硬、可验证，不把长篇教程和文档站实现带进业务项目执行上下文。完整团队学习手册、HTML 概览和文档站迁出到独立的 utopia-handbook 项目。

团队阅读路线

第一次接触本框架时，不要从零散规则文件开始读，按角色顺序走：

角色	先读	目的
项目负责人 / Tech Lead	README.md、architecture/utopia-architecture-and-usage.md、architecture/handbook-separation.md、project/presets.md	判断项目选择哪种 preset、启用哪些目录、哪些规则可项目化扩展。
后端负责人	architecture/backend-stack-go-gin-laravel.md、architecture/database-design-standards.md、architecture/capability-gates.md	明确 Go Gin、Laravel、Realtime、Worker、数据库表设计、架构能力门禁和迁移边界。
前端负责人	architecture/web-surface-strategy.md、architecture/web-stack-nuxt-tailwind.md、architecture/admin-platform.md	明确官网、下载页、PC/H5、后台前端和移动端的边界。
AI Agent / 开发者	AGENTS.md、agents/core/completion-protocol.md、quality/code-standards.md、quality/ai-completion-gates.md、quality/release-testing-gates.md	明确每次任务先读什么、改什么、测什么、记录什么，如何追踪回需求 ID。
测试 / QA	project/acceptance.md、qa/、quality/release-testing-gates.md	明确项目闭环、接口验收、UI 验收和证据沉淀方式。
运维 / 发布负责人	operations/git-workflow.md、operations/ops-readiness.md、operations/deployment-strategy.md、operations/framework-release.md	明确 Git、CI/CD、部署、回滚、密钥、备份恢复、故障处理和框架升级。

推荐使用方式

业务项目不要手动复制整个框架目录。正式流程是把乌托邦作为项目仓库里的 .ai-framework 子仓库接入：

mkdir your-new-project
cd your-new-project
git init
git submodule add http://75.101.196.174/base/utopia.git .ai-framework

OWNER_PROJECT=@your-org/project \
OWNER_TECH_LEAD=@your-org/tech \
OWNER_BACKEND=@your-org/backend \
OWNER_FRONTEND=@your-org/frontend \
OWNER_QA=@your-org/qa \
OWNER_DEVOPS=@your-org/devops \
bash .ai-framework/scripts/init-project.sh --target "$PWD" --type fullstack-monorepo "Your Project Name" your-project-slug

devtools/framework status
devtools/framework plan
npm run check

初始化时下列占位符会被替换为真实项目名称、slug 和团队 owner：

{{PROJECT_NAME}}   {{PROJECT_SLUG}}   {{OWNER_*}}