docs: rewrite project structure and architecture sections for clarity

Mingchengkkk · Mingchengkkk · commit 67c7ff161bf0 · 2026-04-19T00:25:54.000+08:00
diff --git a/README.md b/README.md
@@ -82,21 +82,54 @@ Then open:
 - UI: [http://127.0.0.1:5174](http://127.0.0.1:5174)
 - Health check: [http://127.0.0.1:3101/api/health](http://127.0.0.1:3101/api/health)
 
-## Repo Layout
+## Project Structure
 
-- [`ui/`](ui/) React + Vite workbench UI
-- [`server/`](server/) Express server and Studio generation engine
-- [`tests/`](tests/) stability and workspace evaluation harnesses
-- [`scripts/`](scripts/) local dev orchestration
+&#36825;&#26159;&#19968;&#20010; monorepo&#65292;&#21069;&#21518;&#31471;&#20998;&#25104;&#20004;&#20010;&#21253;&#65292;&#29992; pnpm workspace &#31649;&#29702;&#65306;
 
-## Architecture
+```
+claw-design/
+&#9500;&#9472;&#9472; ui/                    # &#21069;&#31471;&#65306;React + Vite &#24037;&#20316;&#21488;
+&#9474;   &#9500;&#9472;&#9472; src/features/studio/   # &#26680;&#24515;&#21151;&#33021;&#65306;&#29983;&#25104;&#12289;&#32534;&#36753;&#12289;&#39044;&#35272;&#12289;&#23548;&#20986;
+&#9474;   &#9500;&#9472;&#9472; src/api/               # &#21518;&#31471; API &#35843;&#29992;
+&#9474;   &#9492;&#9472;&#9472; src/components/        # &#36890;&#29992; UI &#32452;&#20214;
+&#9474;
+&#9500;&#9472;&#9472; server/                # &#21518;&#31471;&#65306;Express + Studio &#29983;&#25104;&#24341;&#25806;
+&#9474;   &#9500;&#9472;&#9472; src/lib/studio-engine/ # AI &#29983;&#25104;&#26680;&#24515;&#65288;&#32534;&#25490;&#12289;&#28210;&#26579;&#12289;&#39044;&#26816;&#12289;&#20462;&#22797;&#65289;
+&#9474;   &#9500;&#9472;&#9472; src/routes/            # REST API &#36335;&#30001;
+&#9474;   &#9500;&#9472;&#9472; src/middleware/        # &#26085;&#24535;&#12289;&#26657;&#39564;&#20013;&#38388;&#20214;
+&#9474;   &#9492;&#9472;&#9472; skills/                # AI Skill &#25991;&#20214;&#65288;&#24067;&#23616;&#20462;&#22797;&#12289;3D &#26631;&#39064;&#31561;&#65289;
+&#9474;
+&#9500;&#9472;&#9472; vendor/html-ppt-skill/ # &#20869;&#32622;&#27169;&#26495;&#19982;&#20027;&#39064;&#24211;
+&#9474;   &#9500;&#9472;&#9472; assets/themes/         # 8 &#22871;&#37197;&#33394;&#20027;&#39064;
+&#9474;   &#9500;&#9472;&#9472; assets/animations/     # PPT &#21160;&#30011; CSS
+&#9474;   &#9492;&#9472;&#9472; templates/             # &#23436;&#25972; deck &#27169;&#26495; + &#21333;&#39029;&#32452;&#20214;
+&#9474;
+&#9500;&#9472;&#9472; tests/                 # &#33258;&#21160;&#21270;&#27979;&#35797;
+&#9474;   &#9500;&#9472;&#9472; stability/             # Playwright &#31283;&#23450;&#24615;&#27979;&#35797;
+&#9474;   &#9492;&#9472;&#9472; workspace-eval/        # &#29983;&#25104;&#36136;&#37327;&#35780;&#20272;
+&#9474;
+&#9500;&#9472;&#9472; docs/                  # &#25991;&#26723;&#19982;&#28436;&#31034;&#32032;&#26448;
+&#9492;&#9472;&#9472; scripts/               # &#26412;&#22320;&#24320;&#21457;&#33050;&#26412;
+```
+
+### &#25968;&#25454;&#27969;&#65288;&#19968;&#21477;&#35805;&#65289;
+
+&#29992;&#25143;&#22312; **UI** &#36755;&#20837;&#38656;&#27714; &rarr; **Server** &#32452;&#35013; prompt &rarr; &#35843;&#29992; **&#26412;&#22320; AI Agent** &#29983;&#25104; HTML &rarr; **Server** &#39044;&#26816;/&#20462;&#22797; &rarr; &#36820;&#22238; **UI** &#28210;&#26579;&#39044;&#35272; &rarr; &#23548;&#20986; PPT/HTML
+
+### &#20851;&#38190;&#27169;&#22359;&#36895;&#26597;
 
-The app is split into four main layers:
+| &#27169;&#22359; | &#20301;&#32622; | &#20316;&#29992; |
+|------|------|------|
+| &#29983;&#25104;&#24341;&#25806; | `server/src/lib/studio-engine/core.ts` | &#32534;&#25490;&#25972;&#20010; AI &#29983;&#25104;/&#20462;&#22797;&#27969;&#31243; |
+| &#39044;&#26816;&#20462;&#22797; | `server/src/lib/studio-engine/preflight.ts` | &#26816;&#26597;&#39029;&#38754;&#24067;&#23616;&#12289;&#26631;&#39064;&#28322;&#20986;&#12289;&#23494;&#24230;&#38382;&#39064; |
+| &#28210;&#26579;&#22120; | `server/src/lib/studio-engine/render.ts` | &#25226; AI &#36820;&#22238;&#30340;&#29255;&#27573;&#32452;&#35013;&#25104;&#23436;&#25972; deck |
+| AI &#25191;&#34892;&#22120; | `server/src/lib/studio-engine/agent.ts` | &#35843;&#29992;&#26412;&#22320; AI&#65292;&#22788;&#29702;&#27969;&#24335;&#36755;&#20986; |
+| &#36816;&#34892;&#26102;&#39318;&#39029; | `ui/src/features/studio/runtime/StudioHomePage.tsx` | &#29992;&#25143;&#21019;&#24314;/&#31649;&#29702;&#39033;&#30446;&#30340;&#39318;&#39029; |
+| &#29983;&#25104;&#27969;&#31243; Hook | `ui/src/features/studio/runtime/hooks/useStudioGenerationFlow.ts` | &#21069;&#31471;&#29983;&#25104;&#27969;&#31243;&#30340;&#29366;&#24577;&#31649;&#29702; |
+| &#27169;&#26495;&#24211; | `ui/src/features/studio/starter-packs/` | &#20869;&#32622;&#27169;&#26495;&#27880;&#20876;&#19982;&#21152;&#36733; |
+| &#20027;&#39064;/&#21160;&#30011; | `vendor/html-ppt-skill/assets/` | 8 &#22871;&#20027;&#39064; + &#21160;&#30011;&#31995;&#32479; |
 
-1. `UI`: Studio runtime, template workbench, and export surfaces
-2. `Server`: request validation, streaming APIs, prompt/workspace assembly, repair flow
-3. `Local AI agent`: invoked by the server for generation and revision
-4. `Local persistence`: browser IndexedDB and local storage for workspaces and projects
+> &#24819;&#30475;&#26368;&#35814;&#32454;&#30340;&#25991;&#20214;&#32423;&#26144;&#23556;&#65311;&#21487;&#20197;&#26597; [`STUDIO_FILE_MAP.md`](STUDIO_FILE_MAP.md)&#65288;&#22242;&#38431;&#20869;&#37096;&#20132;&#25509;&#29992;&#65289;&#12290;
 
 ## API
 

-Original file line number
+Diff line change
 - UI: [http://127.0.0.1:5174](http://127.0.0.1:5174)
 - Health check: [http://127.0.0.1:3101/api/health](http://127.0.0.1:3101/api/health)
 -## Repo Layout
 +## Project Structure
 -- [`ui/`](ui/) React + Vite workbench UI
 -- [`server/`](server/) Express server and Studio generation engine
 -- [`tests/`](tests/) stability and workspace evaluation harnesses
 -- [`scripts/`](scripts/) local dev orchestration
 +这是一个 monorepo，前后端分成两个包，用 pnpm workspace 管理：
 -## Architecture
 +```
 +claw-design/
 +├── ui/                    # 前端：React + Vite 工作台
 +│   ├── src/features/studio/   # 核心功能：生成、编辑、预览、导出
 +│   ├── src/api/               # 后端 API 调用
 +│   └── src/components/        # 通用 UI 组件
 +│
 +├── server/                # 后端：Express + Studio 生成引擎
 +│   ├── src/lib/studio-engine/ # AI 生成核心（编排、渲染、预检、修复）
 +│   ├── src/routes/            # REST API 路由
 +│   ├── src/middleware/        # 日志、校验中间件
 +│   └── skills/                # AI Skill 文件（布局修复、3D 标题等）
 +│
 +├── vendor/html-ppt-skill/ # 内置模板与主题库
 +│   ├── assets/themes/         # 8 套配色主题
 +│   ├── assets/animations/     # PPT 动画 CSS
 +│   └── templates/             # 完整 deck 模板 + 单页组件
 +│
 +├── tests/                 # 自动化测试
 +│   ├── stability/             # Playwright 稳定性测试
 +│   └── workspace-eval/        # 生成质量评估
 +│
 +├── docs/                  # 文档与演示素材
 +└── scripts/               # 本地开发脚本
 +```
++
 +### 数据流（一句话）
++
 +用户在 **UI** 输入需求 → **Server** 组装 prompt → 调用 **本地 AI Agent** 生成 HTML → **Server** 预检/修复 → 返回 **UI** 渲染预览 → 导出 PPT/HTML
++
 +### 关键模块速查
 -The app is split into four main layers:
 +| 模块 | 位置 | 作用 |
 +|------|------|------|
 +| 生成引擎 | `server/src/lib/studio-engine/core.ts` | 编排整个 AI 生成/修复流程 |
 +| 预检修复 | `server/src/lib/studio-engine/preflight.ts` | 检查页面布局、标题溢出、密度问题 |
 +| 渲染器 | `server/src/lib/studio-engine/render.ts` | 把 AI 返回的片段组装成完整 deck |
 +| AI 执行器 | `server/src/lib/studio-engine/agent.ts` | 调用本地 AI，处理流式输出 |
 +| 运行时首页 | `ui/src/features/studio/runtime/StudioHomePage.tsx` | 用户创建/管理项目的首页 |
 +| 生成流程 Hook | `ui/src/features/studio/runtime/hooks/useStudioGenerationFlow.ts` | 前端生成流程的状态管理 |
 +| 模板库 | `ui/src/features/studio/starter-packs/` | 内置模板注册与加载 |
 +| 主题/动画 | `vendor/html-ppt-skill/assets/` | 8 套主题 + 动画系统 |
 -1. `UI`: Studio runtime, template workbench, and export surfaces
 -2. `Server`: request validation, streaming APIs, prompt/workspace assembly, repair flow
 -3. `Local AI agent`: invoked by the server for generation and revision
 -4. `Local persistence`: browser IndexedDB and local storage for workspaces and projects
 +> 想看最详细的文件级映射？可以查 [`STUDIO_FILE_MAP.md`](STUDIO_FILE_MAP.md)（团队内部交接用）。
 ## API