lhl
215c605650
参赛成果物 03「交互界面 + 数据存储」落地：
- src/genesis/server/: store.py（SQLite 会话持久化）、service.py（会话化服务层：
上传→解析→确认→影响→确认→生成→QA）、app.py（api-design §2 核心端点 9 组）、
static/index.html（内嵌单页，零构建无 node_modules 依赖）
- scripts/serve.py 启动入口（--fake 离线引擎 / 默认真实 LLM）
- pyproject 加 fastapi/uvicorn/python-multipart
- 修复 qa_loop._build meta={} 导致真实模板 {{doc_title}} 等占位符残留 DocxInjectError
- README Web 服务说明 + service_url 登记指引；design.md §12.5 记录（含同步执行/
zip 既有系统/无 WebSocket 的诚实偏差标注）
- 测试：test_server_store/service/api 共 34 用例（TestClient 全链路 + zip 影响流程 + 错误分支）
全量 pytest 473 passed / 99.20%
154 lines
7.2 KiB
Markdown
154 lines
7.2 KiB
Markdown
# Genesis — 概要设计书自动生成 Agent
|
||
|
||
**项目性质：新规**（从零开发的新作品，非存量系统改造）
|
||
|
||
读取 Excel 版要件定义、概要设计做成说明书、概要设计模板、概要设计书记入规则和图表规则等输入资料，自动生成符合规范的 Word 版概要设计书（追加/改修场景会结合既有系统源码做影响调查）。
|
||
|
||
## 项目概述
|
||
|
||
Genesis 是一款 **Agent 开发实战赛赛道一作品**：以多 Agent 协作方式，将「要件定义 → 概要设计书」这一文档密集型工程流程自动化。用户只需上传要件定义 Excel、概要设计模板、记入/图表规则与既有系统源码，系统即自动完成解析、影响调查、分章撰写、QA 校验，最终产出符合规范的 Word 概要设计书与影响调查书 JSON。
|
||
|
||
## 整体功能说明
|
||
|
||
| 功能 | 说明 |
|
||
|---|---|
|
||
| 多 Agent 架构 | Parser（解析）→ Impact（影响调查）→ Writer（撰写）→ QA（校验），四 Agent 协作闭环 |
|
||
| 输入解析 | Excel 要件定义（表格/自由记述/混合型）、Word 模板（7 章锚点）、记入规则/图表规则、Java 既有系统源码 |
|
||
| 影响调查 | 对追加/改修场景分析既有系统，输出「新增/变更/删除/未变化」变更清单与影响关系（total=16 基线样本） |
|
||
| 分章撰写 | 按模板章节（前言/功能一览/画面一览/报表一览/DB设计/接口定义/批处理一览）逐章生成，章节级数据定向注入 |
|
||
| 语言一致性 | `--output-language auto/zh/ja` 可选输出语言；程序化检测正文语言违规，重试/硬失败兜底（2026-08 新增） |
|
||
| QA 校验 | 11 项校验清单（格式/内容准确/幻觉/关联/规则/矛盾/可追溯/术语/章节完整/语言一致性） |
|
||
| 输出 | Word 概要设计书（docx）+ 影响调查书（JSON） |
|
||
|
||
## 效果总结（核心指标摘要）
|
||
|
||
- **测试**：431 个单元/集成测试全绿，代码覆盖率 **99.15%**（红线 ≥99%）
|
||
- **端到端**：真实 LLM 双语试运行通过（中文模板 + `--output-language zh` → 7 章；日文模板 → 7 章），程序化扫描确认正文无中日混杂
|
||
- **真实样本**：7 个脱敏样本（新规/追加改修/混合/自由记述等）驱动解析与生成验证
|
||
- **影响调查基线**：追加改修样本 total=16（new=5 / modified=8 / deleted=3 / unchanged=50 / warnings=0）
|
||
|
||
## 团队分工
|
||
|
||
- **AI 辅助开发**：本项目的需求分析、架构设计、编码实现、测试验证均由 AI（DeepSeek 系列模型 + OpenCode 工具链）与开发者协作完成，全部过程记录于根目录 `_AI_USAGE_LOG.md`（含范式步骤、修改摘要、涉及文件、使用模型）
|
||
- **人工门禁**：设计评审（CEO/架构/QA 视角）、需求确认、提交决策由团队成员人工把关
|
||
|
||
## 规模与技术难度自我评估
|
||
|
||
- **代码规模**：约 2300 行可执行语句（src + tests），覆盖 Parser / Impact / Writer / QA / RAG / 推理引擎六大子系统
|
||
- **技术栈**：Python 3.11+、python-docx / openpyxl / docxtpl、pydantic-settings、DeepSeek/Qwen LLM API
|
||
- **技术难点**：
|
||
1. Excel 表格/自由记述/混合段落的稳健解析（两阶段策略 + 混合判定）
|
||
2. 模板章节 ↔ 数据定向映射（7 章锚点 id 与 Sheet 类型精确对应）
|
||
3. 影响调查（Java 源码解析 + 变更点定位 + 关联推理）
|
||
4. 输出语言一致性（脚本检测 + 重试/硬失败 + QA 第 11 维度）
|
||
5. 覆盖率红线 99% 下的全链路 TDD
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
```powershell
|
||
# 1. 创建虚拟环境并安装依赖（Python >= 3.11）
|
||
python -m venv .venv
|
||
.\.venv\Scripts\Activate.ps1
|
||
pip install -e ".[dev]"
|
||
|
||
# 2. 配置 LLM API Key（真实模式必需；离线 --fake 模式可跳过）
|
||
# 编辑 .env（已被 .gitignore 忽略，密钥不入库）：
|
||
# GENESIS_INFERENCE__API_KEY=sk-xxx
|
||
# 可选：
|
||
# GENESIS_INFERENCE__BASE_URL=https://api.deepseek.com
|
||
# GENESIS_INFERENCE__MODEL=deepseek-chat
|
||
```
|
||
|
||
## 试运行
|
||
|
||
默认输入为 `sample/` 下既有样本（追加改修·股票场景 + sunOnly 既有系统 + 真实概要设计书模板）。
|
||
|
||
### 离线 Fake 模式（无需 API key，验证整条管线）
|
||
|
||
```powershell
|
||
python scripts/run_trial.py --fake
|
||
```
|
||
|
||
### 真实 LLM 模式（需先在 .env 配置 API Key）
|
||
|
||
```powershell
|
||
python scripts/run_trial.py
|
||
```
|
||
|
||
### 输出
|
||
|
||
- `output/output.docx` — 概要设计书
|
||
- `output/impact-report.json` — 影响调查书（JSON，独立可下载）
|
||
|
||
`output/` 已加入 `.gitignore`，试运行产物不入库。
|
||
|
||
### 自定义输入
|
||
|
||
```powershell
|
||
python scripts/run_trial.py `
|
||
--requirement sample\requirements_enhancement_stock.xlsx `
|
||
--template sample\template_design_ja.docx `
|
||
--rules sample\rules_design_ja.docx sample\rules_entry_ja.docx `
|
||
--existing-system sample\existing-system `
|
||
--language java `
|
||
--output output\output.docx
|
||
```
|
||
|
||
### 输出语言（--output-language）
|
||
|
||
生成概要设计书正文的自然语言由 `--output-language` 控制，取值：
|
||
|
||
| 取值 | 行为 |
|
||
|---|---|
|
||
| `auto`（默认） | 跟随章节标题：标题含日文假名 → 日文；否则看规则文档主导脚本（作成说明书/记入规则为日文 → 日文） |
|
||
| `zh` | 强制简体中文（正文程序化校验：混入日文假名会被重试/硬失败） |
|
||
| `ja` | 强制日文（正文程序化校验：纯汉字段落疑似中文会被重试/硬失败） |
|
||
|
||
表格数据始终照抄源 Excel 原文（不翻译），见 design.md §7.2。
|
||
|
||
**生成中文概要设计书**需配合中文模板：
|
||
|
||
```powershell
|
||
python scripts/run_trial.py `
|
||
--template sample\template_design_zh.docx `
|
||
--output-language zh `
|
||
--output output\output.docx
|
||
```
|
||
|
||
`sample\template_design_zh.docx` 为日文模板的完整镜像（7 章锚点 `section:*` 原样保留），由
|
||
`scripts/make_zh_template.py` 生成，可随时用该脚本重新生成。
|
||
|
||
**中文场景注意**：若规则文档（作成说明书/记入规则）仍为日文，`auto` 推导会倾向日文——请显式
|
||
`--output-language zh`，不要依赖 auto。
|
||
|
||
## Web 服务（交互界面，成果物 03）
|
||
|
||
Genesis 提供 **FastAPI Web 服务 + 内嵌零构建前端**（上传 → 解析确认 → 影响确认 → 生成 → QA → 预览/下载），
|
||
会话/文件/结果持久化到 SQLite（`data/server/`）。
|
||
|
||
```powershell
|
||
# 离线 Fake 引擎（无需 API key，适合演示）
|
||
python scripts/serve.py --fake
|
||
|
||
# 真实 LLM 模式（需 .env 配置 GENESIS_INFERENCE__API_KEY）
|
||
python scripts/serve.py
|
||
```
|
||
|
||
- 访问 `http://127.0.0.1:8000/` 使用页面；API 文档 `http://127.0.0.1:8000/docs`
|
||
- 主要端点：`POST /api/sessions`、`POST /api/sessions/{id}/files`（multipart）、
|
||
`POST .../start-parse`、`POST .../confirm-parse`、`POST .../start-impact`、`POST .../confirm-impact`、
|
||
`POST .../generate`（body `{"output_language":"auto|zh|ja"}`）、`POST .../run-qa`、
|
||
`GET .../result/preview|download|impact-report|qa-report`
|
||
- **既有系统**以 `.zip` 上传（追加/改修场景）；不传则影响调查跳过
|
||
- 部署到公网后登记 `service_url`（格式 `http://<域名或公网IP>:<端口>`）供评审系统 B 阶段黑盒冒烟
|
||
|
||
## 测试
|
||
|
||
```powershell
|
||
python -m pytest
|
||
```
|
||
|
||
全量单测 + 覆盖率检查（红线 `fail_under = 99`）。
|