diff --git a/AGENTS.md b/AGENTS.md
index 31d8fc9..f5e17fd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,8 @@
 
 - 后端: Python（FastAPI）
 - 前端: TypeScript + esbuild（原生 DOM，无框架；打包为单文件 ESM）
-- 前端构建: Node + esbuild / tsc（产物入库：`src/genesis/server/static/chat.js`）
+- 前端构建: Node + esbuild / tsc（产物入库：`src/genesis/server/static/chat.js`、`chat.css`）
+- 前端开发: Vite dev server（HMR，仅开发期；代理 /api、/static 到后端）
 - LLM: DeepSeek / Qwen等
 - 文档处理: python-docx, docxtpl, openpyxl
 - Agent 架构: 多 Agent 协作（Parser / Impact / Writer / QA）
@@ -50,6 +51,43 @@ npm test         # 纯逻辑单测（node --test）
 > **每次改动 `frontend/` 后必须运行 `npm run verify`（typecheck → test → build）**，确保入库产物 `src/genesis/server/static/chat.js` 与源码一致；提交时一并包含重建后的 `chat.js`。
 > 开发期可用 `npm run watch` + `npm run typecheck:watch` 实现保存即重建/检查。
 
+## 服务启动（前后端同一服务）
+
+前端由后端 FastAPI 直接提供（`/` 页面 + `/static` 资源，产物 `chat.js`/`chat.css` 已入库），
+**无需单独启动前端服务**。
+
+```powershell
+# 离线 Fake 引擎（无需 API key，适合演示/评审）
+python scripts/serve.py --fake
+
+# 真实 LLM 模式（需 .env 配置 GENESIS_INFERENCE__API_KEY）
+python scripts/serve.py
+
+# 可选参数
+python scripts/serve.py --host 0.0.0.0 --port 8000 --fake --data-root data/server
+```
+
+- 访问 `http://127.0.0.1:8000/`；API 文档 `http://127.0.0.1:8000/docs`
+- 会话/上传快照/结果存于 `data/server/`（SQLite，不入库）
+
+### 前端热更新（开发时，可选）
+
+想要保存即热更新（HMR），开发期开两个终端：
+
+```powershell
+# 终端 1：后端（API + 生产页面）
+python scripts/serve.py --fake
+
+# 终端 2：Vite dev server（HMR；/api、/static 代理到 :8000）
+cd frontend
+npm run dev        # 打开 http://127.0.0.1:5173/
+```
+
+- 开发访问 `http://127.0.0.1:5173/`；改 `frontend/src/*.ts`、`frontend/src/chat.css` 即时热更新。
+- `npm run dev` 先由 `scripts/gen-dev-html.mjs` 从 `src/genesis/server/static/chat.html` 生成开发入口
+  `frontend/index.html`（不入库，勿手改）。
+- 发布/交付仍以 `npm run verify` 产出并入库 `chat.js`/`chat.css` 为准。
+
 ## 开发范式
 
 本项目的开发遵循以下步骤，每一步骤名称对应 `_AI_USAGE_LOG.md` 中的"范式步骤"列：
diff --git a/README.md b/README.md
index 2ce4541..a3dd529 100644
--- a/README.md
+++ b/README.md
@@ -151,6 +151,10 @@ npm test               # 纯逻辑单测（node --test，Node >= 23.6）
 
 > 仅运行 Web 服务无需 Node：`chat.js` 已入库，`python scripts/serve.py` 可直接使用。
 
+### 前端热更新（开发时）
+
+开两个终端：终端 1 `python scripts/serve.py --fake`（后端 API），终端 2 `cd frontend && npm run dev`（Vite dev server），浏览器打开 `http://127.0.0.1:5173/`——改 `frontend/src/*.ts` / `chat.css` 保存即热更新；`/api`、`/static` 自动代理到 `:8000`。开发入口 `frontend/index.html` 由脚本自动生成，勿手改。
+
 - 访问 `http://127.0.0.1:8000/` 进入聊天页面；API 文档 `http://127.0.0.1:8000/docs`
 - 聊天页面支持：📎 上传要件定义/模板/规则/既有系统 zip、自然语言指令（`生成概要设计书` / `用中文生成` /
   `现在什么状态？` / `做影响调查` / `运行QA校验`）、影响确认反问（`确认，继续` / `打回`）、结果下载与预览
diff --git a/_AI_USAGE_LOG.md b/_AI_USAGE_LOG.md
index 0f347d2..79ce758 100644
--- a/_AI_USAGE_LOG.md
+++ b/_AI_USAGE_LOG.md
@@ -162,3 +162,5 @@
 | 2026-09-12 18:37 | 架构设计 | 更新 AGENTS.md：技术栈(前端 TS+esbuild)、项目结构(补 frontend/scripts/tests)、新增前端构建说明、文档规则明确 specs/plans 路径 | AGENTS.md | deepseek-chat |
 | 2026-09-12 18:40 | 架构设计 | 前端自动化：新增 npm run verify(typecheck+test+build)/typecheck:watch/test:watch；AGENTS.md 规定改 frontend/ 后必须 npm run verify 保产物同步 | frontend/package.json; AGENTS.md | deepseek-chat |
 | 2026-09-12 18:40 | 架构设计 | 前端自动化：新增 npm run verify(typecheck+test+build)/typecheck:watch/test:watch；AGENTS.md 规定改 frontend/ 后必须 npm run verify 保产物同步 | frontend/package.json; AGENTS.md | deepseek-chat |
+| 2026-09-12 18:59 | 架构设计 | 前端热更新：新增 Vite dev server(HMR,代理 /api+/static 到 :8000)+vite.config.ts+gen-dev-html.mjs(由 chat.html 生成 dev 入口,不入库)；chat.css 迁入 frontend/src 由 main.ts 引入；esbuild 改 outdir 产出 chat.js/chat.css | frontend/vite.config.ts; frontend/scripts/gen-dev-html.mjs; frontend/src/chat.css; frontend/src/main.ts; frontend/esbuild.config.mjs; frontend/package.json; frontend/tsconfig.json; frontend/src/vite-env.d.ts; .gitignore; src/genesis/server/static/chat.css | deepseek-chat |
+| 2026-09-12 18:59 | 架构设计 | AGENTS.md 增服务启动(前后端同一服务)与前端热更新说明；README 增 HMR 开发说明 | AGENTS.md; README.md | deepseek-chat |