125 lines
5.6 KiB
Markdown
125 lines
5.6 KiB
Markdown
# 概要设计书自动生成 Agent
|
||
|
||
## 项目简介
|
||
|
||
本项目的目标是开发一个 Web 服务形态的 Agent，能够读取 Excel 版要件定义、概要设计做成说明书、概要设计模板、概要设计书记入规则和图表规则等输入资料，自动生成符合规范的 Word 版概要设计书。
|
||
|
||
## 交流语言
|
||
|
||
本项目的所有 AI 交流、文档、注释、代码中的文本，**统一使用中文**。不得使用日文、英文或其他语言进行交流（专有名词、技术术语、代码关键字等不可避免的情况除外）。
|
||
|
||
## 技术栈
|
||
|
||
- 后端: Python（FastAPI）
|
||
- 前端: TypeScript + esbuild（原生 DOM，无框架；打包为单文件 ESM）
|
||
- 前端构建: 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）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
Genesis/
|
||
├── AGENTS.md # 本文件 - OpenCode 指令文件
|
||
├── _AI_USAGE_LOG.md # AI 使用日志（自动生成）
|
||
├── docs/ # 设计文档（规范 specs/ 与计划 plans/ 位于 docs/superpowers/ 下）
|
||
├── frontend/ # 前端源码（TypeScript）：src/ + tests/ + esbuild/tsconfig
|
||
├── src/ # 后端源码；src/genesis/server/static/ 含前端打包产物
|
||
├── scripts/ # 运行脚本（如 scripts/serve.py）
|
||
├── tests/ # 后端测试（pytest）；前端单测在 frontend/tests/
|
||
├── sample/ # 样本输入文件（脱敏）
|
||
└── README.md # 安装与运行说明
|
||
```
|
||
|
||
## 前端构建（修改前端时）
|
||
|
||
前端源码在 `frontend/`（TypeScript），打包产物入库于 `src/genesis/server/static/chat.js`。
|
||
修改前端后须重新构建（仅运行 Web 服务无需 Node，产物已入库）：
|
||
|
||
```powershell
|
||
cd frontend
|
||
npm install # 首次
|
||
npm run build # 打包到 ../src/genesis/server/static/chat.js
|
||
npm run typecheck
|
||
npm test # 纯逻辑单测（node --test）
|
||
```
|
||
|
||
> 前端改动优先改 `frontend/src/*.ts`，再 `npm run build`；`?v=__ASSET_VER__` 依据文件 mtime 自动破缓存。
|
||
>
|
||
> **每次改动 `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` 中的"范式步骤"列：
|
||
|
||
1. **需求理解** — 分析大赛规则，理解概要设计书生成需求
|
||
2. **架构设计** — AI 生成方案，人工审核设计
|
||
3. **Agent 实现** — AI 编码实现各 Agent 模块
|
||
4. **测试验证** — 单元测试与集成测试验证
|
||
5. **反馈迭代** — 基于测试结果反馈修正
|
||
|
||
## 日志规则（自动执行）
|
||
|
||
每次创建或修改代码、文件后，在项目根目录的 `_AI_USAGE_LOG.md` 中追加一条记录，必须包含以下字段：
|
||
|
||
| 日期时间 | 范式步骤 | 修改摘要 | 涉及文件 | 使用模型 |
|
||
|----------|----------|----------|----------|----------|
|
||
| 2026-06-29 14:30 | 架构设计 | 完成Agent协作架构设计 | docs/design.md | deepseek-chat |
|
||
|
||
字段填写说明：
|
||
- **日期时间**：AI 自动获取当前时间填写
|
||
- **范式步骤**：初始写"待补充"，后续替换为上方开发范式中对应的步骤名称
|
||
- **修改摘要**：简述本次修改的内容
|
||
- **涉及文件**：列出被创建或修改的代码文件路径（每行一个）
|
||
- **使用模型**：AI 使用的模型名称，若无法获取则手动填写
|
||
|
||
## 文档生成规则
|
||
|
||
所有会话中生成的设计文档、方案、报告等内容，**必须保存到 `docs/` 目录下**（设计规范放 `docs/superpowers/specs/`，实施计划放 `docs/superpowers/plans/`），不得在项目根目录或其他位置创建文档文件。
|
||
|
||
## 信息安全
|
||
|
||
- 不得将客户数据、公司信息上传至外部公开仓库
|
||
- API Key 配置在环境变量或配置文件中，不得硬编码在源码
|
||
- 确认所有依赖的许可证类型，禁止使用盗版软件
|