T1-SD0102-01/2026Technology-Competition

Files

T

lhl 2e11720a2d feat(impact): Impact Agent MVP —— 变更点定位 + 影响调查书（追加改修场景）

- 门控：用户提供 existing_system 路径 → 进入影响调查；未提供 → 原流程不变
- CodeParser 解析 Java（@RestController/@Service/@Entity/@TableName）+ ExistingSystemExplorer 组装
- ImpactAgent 变更点定位（变更区分×既存対応 确定性比对，无 LLM）→ ImpactReport（JSON 可下载）
- 影响调查结果作为 Writer 生成概要设计书的主上下文（{{impact}}，无专用影响章）
- source_aggregator 解除 existing_system=None 硬编码
- 既有系统样本 sunOnly/stock-trade-system（无 LICENSE，仅测试输入，保留来源标注）
- 新造股票交易域追加改修样本 要件定義_追加改修_股票.xlsx（对齐 sunOnly 真实类名）
- 全量 351 passed / 99.27% 覆盖；门禁 PASS（16 要素：新规5/変更8/削除3/未受影响50）

2026-08-23 17:59:08 +08:00

8.3 KiB

Raw Blame History

Impact Agent MVP 设计（2026-08-23）

背景

用户指出：写概要设计书需要「根据要件定义书 + 既有系统的设计与代码做影响调查 → 确定修改范围」。当前 source_aggregator.py 硬编码 existing_system=None，无 Impact Agent 实现。本次实现 MVP 变更点定位 + 影响书。

关键用户决策（brainstorming 确认）：

场景 = 追加改修（需影响调查）
既有系统输入形态 = Java 项目源码
既有系统样本 = samples/existing-system/（sunOnly/stock-trade-system，股票量化交易系统，无 LICENSE，仅作测试输入，保留来源标注）
里程碑范围 = MVP：解析既有系统 → 变更点定位 → 影响书（JSON）；不做 LLM 要素抽取/关联推理
样本同域化：新造 samples/要件定義_追加改修_股票.xlsx（股票交易域，对齐 sunOnly 真实模块）
门控：是否提供 existing_system 路径决定是否进入影响调查阶段（非章节级）
范围确认：进入影响调查前与用户确认调查范围（模块/深度）
消费模型：ImpactReport 是生成概要设计书的主上下文——整本概要设计书基于影响调查结果生成， 无专用影响章、无 {{section:impact}} 锚点门控；ImpactReport 同时作为可下载独立产物

架构与数据流

要件定義_追加改修_股票.xlsx（新造）      samples/existing-system/（sunOnly 源码）
        │ 现有 ExcelParser                        │ 新增 CodeParser（Java 解析）
        ▼                                          ▼
   StructuredSource.tables               CodeStructure → ExistingSystemInfo
        │                                          │
        └──────────────┬───────────────────────────┘
                       ▼
        ImpactAgent（变更点定位，确定性比对）
             - 取 変更区分 + 既存対応 列
             - 与 ExistingSystemInfo 连接比对（存在性校验）
                       ▼
                ImpactReport（JSON 中间产物，可下载）
                       ▼
        WriteOrchestrator.generate(impact_report)
             - ImpactReport 作为主上下文喂给 WriterAgent
             - 整本概要设计书基于影响结果生成

门控与范围确认

门控（流水线级）：SourceParser.parse(existing_system_path=...) 提供路径 ⇒ StructuredSource.existing_system 非 None ⇒ 进入影响调查；WriteOrchestrator.generate 检测到 existing_system 非 None 且未显式传 impact_report 时，自动运行 ImpactAgent 生成影响书。
范围确认（human-in-loop）：MVP 默认范围 = 提供的整个目录树（全模块、Controller/Service/Entity/Endpoint 全层）；可按参数收窄（modules/depth）。完整 UI 确认留后续。
门控降级：CodeParser 失败（非 Java/无源码）⇒ 跳过影响调查并告警，生成照常（无 ImpactReport）。

变更点定位规则（确定性，无 LLM）

要件情况	判定
新規 + 既存対応空	`new`（确认新增）
新規 + 既存対応指定	`conflict` 告警（自相矛盾）
変更 + 既存対応命中且类存在	`modified`（受影响既有类 = 映射清单）
変更 + 既存対応缺失/类不存在	`warning`（无法定位修改对象）
削除 + 既存対応命中	`deleted`（确认删除）
削除 + 既存対応缺失/类不存在	`warning`
既有类未被任何要件引用	`unchanged`（summary 计数）

既存対応 列值 = Controller/Service/Entity 类名（逗号分隔）；命中判定为类名出现在 ExistingSystemInfo 三层清单中（不区分大小写，后缀 Controller/Service/Entity 可选）。

数据模型（data_models.py 新增）

class ChangeType(Enum):
    NEW = "新規"; MODIFIED = "変更"; DELETED = "削除"; UNCHANGED = "不变"

@dataclass
class ChangeElement:
    element_id: str; element_type: str; name: str
    change_type: ChangeType
    existing_mapping: list[str]          # 既存対応 声明值
    impacted_existing: list[str]         # 确认命中的既有类
    evidence: str                        # 既有类 source_uri / 空
    status: str                          # "ok" | "conflict" | "warning"

@dataclass
class ImpactWarning:
    element_id: str; issue: str

@dataclass
class ChangeAnalysis:
    project_type: str                    # "enhancement"
    new_elements: list[ChangeElement]
    modified_elements: list[ChangeElement]
    deleted_elements: list[ChangeElement]
    unchanged_elements: list[ChangeElement]
    warnings: list[ImpactWarning]

@dataclass
class ImpactReport:
    metadata: dict
    change_analysis: ChangeAnalysis
    summary: dict

组件

`src/genesis/impact/code_parser.py`（新）

CodeParser.parse(root_path) -> CodeStructure：扫描 **/*.java，按注解识别：
- @RestController|@Controller → ControllerInfo（base_path 取 @RequestMapping，endpoints 取方法级映射）
- @Service → ServiceInfo（methods）
- @Entity|@Table(name=...) → EntityInfo（table_name、fields）
- 方法映射 → EndpointInfo
顶层目录 → modules；失败（无 Java/路径无效）→ 抛 CodeParseError

`src/genesis/impact/existing_system_explorer.py`（新）

ExistingSystemExplorer.explore(code: CodeStructure) -> ExistingSystemInfo

`src/genesis/impact/impact_agent.py`（新）

ImpactAgent.run(structured_source, scope=None) -> ImpactReport
从 tables 提取带 変更区分/既存対応 列的表行 → 按上表规则分类 → summary

`src/genesis/parsers/source_aggregator.py`（改）

parse(..., existing_system_path=None)：提供路径时解析并填充 existing_system

`src/genesis/writer/`（改）

GenerationContext 新增 impact_report: object | None = None；to_vars() 增加 "impact" 变量
WRITER_PROMPT_TEMPLATE 增加 影响调查上下文:\n{{impact}}\n（在参考资料前）
context_builder.build_contexts 从 structured_source.impact_report 透传
WriteOrchestrator.generate(..., impact_report=None)：门控自动跑 ImpactAgent；上下文携带影响书
StructuredSource 新增 impact_report: ImpactReport | None = None（生成后回填，便于 QA/日志）

错误处理

CodeParseError（非 Java/无源码/路径无效）→ 门控降级跳过 + 告警
既存対応 引用不存在 → warning，不阻断
新規 却映射既有 → conflict warning

测试策略（TDD，全量 ≥99%）

tests/test_data_models.py：新增 ImpactReport 模型默认值/构造
tests/test_code_parser.py：用 samples/existing-system 真实文件断言提取（类名/数量/路径）
tests/test_existing_system_explorer.py：组装 ExistingSystemInfo 分层
tests/test_impact_agent.py：给定要件定義（新造样本）+ ExistingSystemInfo → 断言分类
tests/test_source_aggregator.py：existing_system_path 加载；无效路径降级/报错
tests/test_phase5_models.py：更新 test_generation_context_no_impact_field → 断言 impact 变量存在且为空
tests/test_phase5_writer_agent.py：断言模板含影响上下文变量
tests/test_phase5_writer_orchestrator.py：传 impact_report → 断言 variables["impact"] 含影响信息
门禁（fake 模式）：sunOnly + 新造样本端到端产出 ImpactReport + 概要设计书

新造样本规格

samples/要件定義_追加改修_股票.xlsx（股票交易域，对齐 sunOnly 真实模块）：

機能一覧：F001 止损风控机能(新規,无既存対応) / F002 订单状态查询扩展(変更→OrderController,OrderQueryService) / F003 实时行情显示扩展(変更→RealtimeMarketDataController) / F004 旧回测机能(削除→StrategyBacktestController)
画面一覧（对应画面 + 変更区分）／DB定義（新規止损设定表/変更订单表/削除旧回测表）／IF定義（新規风控告警连携IF）
各表新增 既存対応 列（类名或留空）＋ 変更区分 列
改修ポイント 自由文本（改修概要）

里程碑外（后续）

LLM 要素抽取 / 关联推理 / 影响矩阵
v1→用户逐条修正→v2 生命周期 UI
范围确认 UI / API 化

8.3 KiB Raw Blame History Unescape Escape