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）

效果总结（核心指标摘要）

• 测试：522 个单元/集成测试全绿，代码覆盖率 99.0%+（红线 ≥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

---

安装

# 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，验证整条管线）

python scripts/run_trial.py --fake

真实 LLM 模式（需先在 .env 配置 API Key）

python scripts/run_trial.py

输出

• output/output.docx — 概要设计书
• output/impact-report.json — 影响调查书（JSON，独立可下载）

output/ 已加入 .gitignore，试运行产物不入库。

自定义输入

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。

生成中文概要设计书需配合中文模板：

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 服务 + 内嵌零构建聊天前端（DeepSeek 式对话页面）：用户用自然语言下达指令， 后台自动驱动「解析 →（影响调查）→ 生成 → QA」整条工作流；影响调查完成时会先反问确认，确认后继续生成。

# 离线 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
• 聊天页面支持：📎 上传要件定义/模板/规则/既有系统 zip、自然语言指令（生成概要设计书 / 用中文生成 / 现在什么状态？ / 做影响调查 / 运行QA校验）、影响确认反问（确认，继续 / 打回）、结果下载与预览
• 左侧会话历史侧边栏：按会话名/项目列出历史会话，点击即可恢复消息；顶部仅显示会话名（自动取要件定义文件名）
• 项目级配置：侧边栏「项目配置」面板可登记模板/做成说明书/规则/既有系统代码库/设计文档目录，绑定项目的会话 只需上传要件定义，其余复用项目配置（POST /api/projects 等）；design_docs_dir 中的设计文档会作为影响调查的 确定性交叉引用证据（无 LLM、纯字符串匹配）写入影响调查书
• 主要 API 端点：
  • 项目配置：POST /api/projects、GET /api/projects、GET /api/projects/{name}、DELETE /api/projects/{name}
  • 会话/文件：POST /api/sessions（body 可含 name/project）、GET /api/sessions（含 name/project）、POST /api/sessions/{id}/files（multipart，type=requirements/template/write_instruction/rules/existing_system）
  • 聊天驱动：POST /api/chat/{id}/messages（body {"content":"..."}）、GET /api/chat/{id}/messages（历史）
  • 分步端点（聊天底层复用）：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
  • 进度流：GET /api/sessions/{id}/ws（WebSocket，实时推送各步骤进度事件；运行依赖 websockets>=12，已包含在 pip install -e ".[dev]" 中）
• 既有系统以代码库目录（项目配置）或 .zip（会话上传）提供（追加/改修场景）；不传则影响调查跳过
• 部署到公网后登记 service_url（格式 http://<域名或公网IP>:<端口>）供评审系统 B 阶段黑盒冒烟

测试

python -m pytest

全量单测 + 覆盖率检查（红线 fail_under = 99）。