docs: AGENTS/README 增服务启动与前端热更新说明 + AI 使用日志
This commit is contained in:
@@ -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` 中的"范式步骤"列：
|
||||
|
||||
@@ -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校验`）、影响确认反问（`确认，继续` / `打回`）、结果下载与预览
|
||||
|
||||
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user