zhuangxiu/README.md

AI 空间风格工作台

这是一个以户型为约束、以布局与风格决策为核心的 Agent 型室内概念设计工作流。

第一阶段不追求施工图、真实商品匹配或精确报价，而是建立三个可持续修改的核心状态：

• Plan State：墙、门窗、房间、比例、图层和置信度。
• Scene State：家具布局、相机、锁定对象和 3D 白模。
• Style State：色板、材质、灯光、造型语言、禁用项和已锁定决策。

仓库结构

apps/web             Next.js 风格工作台
services/api         FastAPI 工作流与集成接口
contracts            前后端共享的数据协议说明
docs                 架构与工作流设计
11-2-104-模型.pdf     真实测试图纸

本地启动

推荐使用 Docker：

1. 在 PowerShell 运行 ./scripts/bootstrap.ps1 -Force，自动生成数据库和 Redis 密码。
2. 运行 docker compose up -d --build。
3. 打开 http://localhost:3000，首次进入会自动显示“系统设置”。
4. 在网页中填写 MinIO、百度 OCR 和模型 API，并逐项点击测试。

日常使用不需要编辑 .env。它只保留应用启动前必须存在的基础参数，模型密钥等运行期配置会在网页中填写并加密保存。

需要单独开发前后端时：安装前端依赖 pnpm install，启动前端 pnpm dev；创建 Python 虚拟环境并运行 pip install -e "services/api[dev]"，随后使用 uvicorn app.main:app --app-dir services/api --reload --port 8000 启动 API。

前端默认访问 http://localhost:3000，API 文档默认位于 http://localhost:8000/docs。

当前可体验产品

• 从网页真实上传 25 MB 以内的 PDF，并把原文件与首页预览保存到 MinIO。
• 判断矢量 PDF / 扫描 PDF，统计矢量元素，并检测同页中的多个候选平面区域。
• 在图纸上直接选择目标户型，选择结果与工作流修订号持久化到 PostgreSQL。
• 调用空间理解模型分析目标户型，输出房间、动线、采光、布局机会和风险；失败时自动建立可编辑草案，不阻塞流程。
• 通过居住者、生活方式、重点空间、风格、颜色、禁用项和保留项完成需求访谈。
• 调用总调度模型生成三套结构化 Style DNA，并支持人工选择设计方向。
• 自动路由模式由总调度模型从候选池选择空间模型或生图模型；手动模式严格使用用户指定模型。
• 调用真实生图模型生成关键空间效果图，结果保存到 MinIO 独立渲染桶。
• 基于任意历史版本继续文字修改，保存父子版本关系，并可导出完整项目记录。
• 右侧设计 Agent 支持多轮对话、追问和需求记录。
• 提供可验证的工作流状态机和命令接口。
• 预留 MinIO、百度 OCR、GPU Worker 和多模型路由适配器。
• 提供分类设置中心、可扩展模型池、逐模型测试、模型路由和工作流就绪门禁。

当前产品定位是布局与风格概念验证，不替代酷家乐等施工设计工具。墙体可拆性、精确尺寸、施工节点和商品匹配仍需专业设计工具或人工复核。

详见 架构设计、工作流定义 与 系统设置。