T1-SD0102-01/2026Technology-Competition
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
2026Technology-Competition/docs/implementation-plan.md
T
lhl 3decdfc31c feat(rag): v1 rerank 精排 + bge-m3 多语言切换（T6/T11 架构审查整改） 
- T6 (Issue6): RerankConfig（enabled/model=BAAI/bge-reranker-v2-m3/device）
  - rag-layer-design §6.3 Rerank 精排：窗口=RRF top-10、候选≤top_k 跳过、
    故障降级 RRF 原序；原 §6.3-6.6 顺延 6.4-6.7
  - config-design §5 新增 rerank 段；design §5.5 检索策略加 rerank
- T11 (OV2): EmbeddingConfig.model 默认 bge-small-zh-v1.5 → BAAI/bge-m3（日文语料）
  - rag-layer-design 选型表/依赖表/manifest/流程图同步 + 新增 §2.3 日文样本验证
  - design.md / implementation-plan 4.3 / config-design embedding 同步
- 新增 test_rag_design_consistency.py 一致性门禁（6 用例防文档漂移）
- TDD: RED（默认模型仍旧 + rerank 字段不存在）→ GREEN → 全量 198 passed / 100.00%（996 stmts/252 br）
2026-08-12 11:32:28 +08:00

382 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 概要设计书自动生成 Agent 实现计划
> 版本: v1.0 | 日期: 2026-07-21 | 状态: 初版
>
> 术语对照：本文件中「書き方ルール」= 设计文档中的「写入规则」，「設計ルール」=「设计规则」，「参考設計文書」=「参考文档」。
---
## 阶段总览
| 阶段 | 名称 | 预计工作量 | 核心产出 |
|------|------|-----------|---------|
| 1 | プロジェクト基盤・共通ツール | 大 | FileReader, CodeParser, ImageAnalyzer + プロジェクト構造 |
| 2 | Parser Agent - Excel解析 | 大 | ExcelParser（Table/FreeText/Formatting） |
| 3 | Parser Agent - Word/PPT解析 + 現行システム探索 | 中 | WordParser, PPTXParser, ExistingSystemExplorer |
| 4 | RAG Infrastructure | 中 | ルールハンドブック構築・検索・バージョン管理 |
| 5 | Impact Agent | 大 | 要素抽出・関連推論・影響調査書生成 |
| 6 | Web UI | 大 | ファイルアップロード・確認画面・生成実行画面 |
| 7 | Writer Agent | 大 | 章構成生成・テンプレート埋め込み・RAG連携 |
| 8 | QA Agent | 中 | フォーマット検証・内容検証・規則遵守検証 |
| 9 | 統合テスト・調整 | 大 | エンドツーエンド試験・エラー処理・性能調整 |
| 10 | 成果物整備 | 中 | README・実験レポート・デモ動画・最終調整 |
> 凡例: 大（3-5日） / 中（1-3日） / 小（0.5-1日）
---
## フェーズ 1: プロジェクト基盤・共通ツール
### 目標
プロジェクト構造の確立、全Agentが依存する共通ツールの実装。
### タスク一覧
| # | タスク | 詳細 |
|---|-------|------|
| 1.1 | プロジェクト構造作成 | `src/` 下のディレクトリ構成、`pyproject.toml`、依存関係定義（詳細: docs/config-design.md の統一構成スキーマ） |
| 1.2 | 共通データモデル定義 | Provenance, CellValue, StructuredSource 等のデータクラス（data_models.py）。設計 §9.4 のモデルは章間で相互参照するため、**ファイル先頭で `from __future__ import annotations` を有効化**し、定義順序に依存しないこと |
| 1.3 | FileReader 実装 | ファイル読み取り統一インターフェース（.xlsx / .docx / .pptx / .java / .xml / .yml） |
| 1.4 | CodeParser 実装（Phase 1） | Java/Spring Boot のディレクトリ走査・Controller/Service/Entity 抽出 |
| 1.5 | ImageAnalyzer 実装 | Vision LLM 接続・画像認識・結果構造化（LLM依存の抽象化） |
| 1.6 | InferenceEngine 実装 | 統一推理引擎：LLMプロバイダー抽象化（DeepSeek/Qwen）、chat/chat_structured、モデル管理、リトライ・タイムアウト・フォールバック、Token管理（詳細: docs/agent-runtime-design.md §2） |
| 1.7 | Prompt テンプレートライブラリ | PromptRegistry 実装（テンプレート登録・バージョン管理） |
| 1.8 | ToolExecutor 実装 | 統一ツール実行器＋ToolCallEvent 打点（詳細: docs/agent-runtime-design.md §5） |
| 1.9 | セッション状態機械実装 | 会话级状态机（8状態）＋状態遷移白名单＋確認イベント永続化（詳細: docs/agent-runtime-design.md §3） |
| 1.10 | MemoryService 実装 | 3層メモリ（長期/作業/短期）＋AgentState 受け渡し（詳細: docs/agent-runtime-design.md §4） |
| 1.11 | 可観測性イベント基盤 | LLMCallEvent / ToolCallEvent イベントストリーム＋SQLite イベント表 |
| 1.12 | AI使用ログ基盤 | `_AI_USAGE_LOG.md` 自動追記機構 |
### 検収基準
- FileReader が .xlsx / .docx / .pptx を読み取り UnifiedDocument を返せる
- CodeParser が Java Spring Boot プロジェクトの Controller/Service/Entity を抽出できる
- ImageAnalyzer が Vision LLM を呼び出し画像説明を返せる
- InferenceEngine がモデル切替・構造化出力・リトライ/フォールバックを正しく動作させる
- セッション状態機械が 8 状態の合法/非法遷移を正しく判定し、確認イベントを永続化する
- 単体テストが通る
---
## フェーズ 2: Parser Agent - Excel解析
### 目標
要件定義Excelを解析し、StructuredSource に変換する。
### タスク一覧
| # | タスク | 詳細 |
|---|-------|------|
| 2.1 | ExcelParser 基本構造 | Sheet 読み取り・セル値取得・データ型変換 |
| 2.2 | SheetDetector 実装 | Sheet 名 + 表頭からのタイプ自動判定（FUNCTION/SCREEN/REPORT/DATABASE/INTERFACE/BATCH/MASTER/GENERIC） |
| 2.3 | Sheet性質判定 | テーブル型/自由記述型/混合型 の自動判別 |
| 2.4 | TableExtractor（構造化テーブル型） | 行列解析・ヘッダー行検出・データ行抽出 |
| 2.5 | MergeHandler 実装 | 結合セルの検出・下行填充（forward_fill） |
| 2.6 | FreeTextParser（自由記述型） | 全セルテキスト結合 → LLMに渡して構造化 |
| 2.7 | FormattingDetector 実装 | 取消線検出・非表示行/列検出・コメント抽出 |
| 2.8 | ProvenanceAnnotator | 全セルに source_uri を付与 |
| 2.9 | ExcelParser 統合テスト | 各種Excelパターンに対するテスト（テーブル型/自由記述型/混合型/取消線あり/結合セルあり） |
### 検収基準
- 3種類のExcelパターン（テーブル型/自由記述型/混合型）を正しく解析できる
- 結合セルの下行填充が正しい
- 取消線行が検出・除外マークできる
- 各セルに source_uri が付与されている
- 単体テストカバレッジ > 80%
---
## フェーズ 3: Parser Agent - Word/PPT解析 + 現行システム探索
### 目標
Wordテンプレート・ルール文書・PPTルール文書・現行システムの解析。
### タスク一覧
| # | タスク | 詳細 |
|---|-------|------|
| 3.1 | WordTemplateParser 実装 | 章構成（Heading階層）抽出、占位符（{{section:xxx}}）検出、スタイル抽出 |
| 3.2 | RuleDocParser（Word） 実装 | ルール文書のMarkdown化、ルール分類（書き方ルール / 設計ルール） |
| 3.3 | PPTXParser 実装 | PPTからのテキスト抽出、スライド構成の保持 |
| 3.4 | ExistingSystemExplorer - コード探索 | CodeParser を利用して現行コードから Controller/Entity/API 抽出 |
| 3.5 | ExistingSystemExplorer - 設計書探索 | 既存Word/Excel設計書の解析 → 現行構成データ生成 |
| 3.6 | SourceAggregator 実装 | 全パーサーの出力を統一的 StructuredSource にまとめる |
| 3.7 | Parser Agent 統合テスト | 全入力パターンに対する統合テスト |
### 検収基準
- Wordテンプレートの章構成が正しく抽出できる
- ルール文書がMarkdown化され「写入规则」「设计规则」に分類される
- PPTからテキストが抽出できる
- 現行システムのコードと設計書から構成データが生成できる
- 統合テストが通る
---
## フェーズ 4: RAG Infrastructure
### 目標
ルール文書からルールハンドブックを構築・検索・バージョン管理する仕組み。
### タスク一覧
| # | タスク | 詳細 |
|---|-------|------|
| 4.1 | ルール文書のインデックス化 | 分類済みルールの分割（Word/Excel/PPT フォーマット適応）→ Embedding → ベクトルストア構築（詳細: docs/rag-layer-design.md §3, §4） |
| 4.2 | StorageAdapter 実装 | VectorStoreAdapter 抽象＋ChromaAdapter＋MockAdapter（詳細: docs/rag-layer-design.md §9） |
| 4.3 | ハイブリッド検索API | ベクトル（bge-m3，日文対応）＋BM25 双チャネル＋RRF 融合＋rerank 精排（bge-reranker-v2-m3）の実装（詳細: docs/rag-layer-design.md §6） |
| 4.4 | ルールハンドブックのバージョン管理 | ドキュメント級インクリメンタル更新（hash比較）＋manifest＋セッションロックバージョン（詳細: docs/rag-layer-design.md §5） |
| 4.5 | ルール衝突検出・ユーザー確認 | ConflictDetector＋ユーザー確認フロー＋意思決定記録（詳細: docs/rag-layer-design.md §7） |
| 4.6 | 「ルールを更新」UI連携 | Web UI からの更新トリガー → 再インデックス化 |
| 4.7 | 設計ルールの Impact Agent 連携 | 設計ルールを Impact Agent の関連推論に渡す仕組み |
### 検収基準
- 書き方ルールを章単位で検索できる（例：「機能一覧のルール」で検索→該当ルール返却）
- ハイブリッド検索（ベクトル+BM25+RRF）が正しく融合結果を返す
- ルールハンドブックのバージョン管理が正しく動作する（ドキュメント級インクリメンタル更新含む）
- ルール更新→再インデックス化のフローが通る
- ルール衝突が検出され、ユーザー確認フローが動作する
---
## フェーズ 5: Impact Agent
### 目標
StructuredSource から影響調査書を生成する。
### タスク一覧
| # | タスク | 詳細 |
|---|-------|------|
| 5.1 | Step 0: 変更箇所特定 | 新規/追加/変更/削除の自動識別（追加改修シナリオ） |
| 5.2 | Step 1: 要素抽出（LLM呼出） | StructuredSource → 構成要素抽出のプロンプト設計・実装 |
| 5.3 | Step 2: コメント分析 | コメントのLLM分析・分類・重要度判定（先分析、不明なら質問） |
| 5.4 | Step 3: 関連推論（LLM呼出） | 要素間関連推論のプロンプト設計・証拠抽出・置信度判定 |
| 5.5 | クロスチェック・矛盾検出 | 複数証拠による置信度補正・循環参照検出・孤立要素検出 |
| 5.6 | Step 4: 影響マトリックス構築 | Relations → 双方向マトリックス変換 |
| 5.7 | Step 5: 影響調査書出力 | 中間成果物（JSON）の構造定義と出力 |
| 5.8 | 品質指標計算 | provenance_chain, coverage_markers, orphan_warnings, risk_flags |
| 5.9 | Impact Agent 統合テスト | 新規開発・追加改修・自由記述型Excel の各シナリオテスト |
### 検収基準
- 新規開発シナリオで正しい要素抽出と関連推論ができる
- 追加改修シナリオで変更箇所特定と影響分析ができる
- 影響調査書が設計通りの構造で出力される
- 矛盾検出・孤立要素警告が機能する
- 各関連に証拠（evidence）と置信度が付与されている
---
## フェーズ 6: Web UI
### 目標
ユーザーとの対話インターフェース。
### 画面構成
```
Web UI
├── ファイルアップロード画面
│ ├── 要件定義Excel (必須)
│ ├── 设计书模板 (必須)
│ ├── 规则文档 (任意, 複数)
│ ├── 現行システムファイル (任意)
│ └── アップロード進捗表示
│
├── Probe 確認画面
│ ├── Sheet タイプ判定結果 (修正可能)
│ ├── テンプレート章構成プレビュー
│ ├── 現行システム探索結果 (あれば)
│ └── [確認して次へ]
│
├── Impact 確認画面
│ ├── 要素一覧 (展開/折畳み)
│ ├── 関連一覧（逐条修正可能）
│ │ ├── 追加/削除/種類変更/証拠修正
│ │ ├── 確信度フィルタリング
│ │ └── 修正履歴表示
│ ├── 不確かさ一覧（ユーザー回答入力）
│ ├── 品質指標（孤立要素・リスク警告）
│ └── [確認完了 → Writerへ進む]
│
├── 生成実行画面
│ ├── 生成進捗表示（何章目を生成中…）
│ ├── エラー発生時の選択肢（リトライ/続行/中断）
│ └── 完了通知
│
├── 結果プレビュー画面
│ ├── 生成設計書のプレビュー
│ ├── ダウンロード（Word形式）
│ └── ルールハンドブック管理（更新ボタン）
│
├── ルール管理画面
│ ├── 現在のルールハンドブックバージョン表示
│ ├── 「ルールを更新」ボタン
│ └── バージョン履歴
│
└── 共通: エラーダイアログ / 進行状態表示 / ヘルプ
```
### タスク一覧
| # | タスク | 詳細 |
|---|-------|------|
| 6.1 | フロントエンドプロジェクト設定 | React + TypeScript + ルーティング |
| 6.2 | ファイルアップロード画面 | ドラッグ&ドロップ・複数ファイル対応・進捗表示 |
| 6.3 | Probe 確認画面 | Sheet タイプ確認・修正・テンプレートプレビュー |
| 6.4 | Impact 確認画面 | 要素一覧・関連一覧（逐条修正UI）・不確かさ入力・品質指標表示 |
| 6.5 | 生成実行画面 | 進捗表示・エラー対話・途中再開 |
| 6.6 | 結果プレビュー画面 | Wordプレビュー・ダウンロード |
| 6.7 | ルール管理画面 | バージョン表示・更新トリガー・履歴 |
| 6.8 | バックエンドAPI実装 | Orchestrator + REST API（FastAPI）＋WebSocket イベント（詳細: docs/api-design.md の端点リスト・状態遷移・TaskQueue 抽象） |
| 6.9 | Web UI 統合テスト | 全画面遷移テスト・エラーシナリオテスト |
### 検収基準
- 全画面遷移が正常動作
- ファイルアップロードからダウンロードまでエンドツーエンドで動作
- 異常系（ファイル不正・LLM失敗）でエラーダイアログが表示されユーザー選択可能
- 影響調査の逐条修正が反映される
---
## フェーズ 7: Writer Agent
### 目標
影響調査書 + StructuredSource + RAGルール から設計書を生成する。
### タスク一覧
| # | タスク | 詳細 |
|---|-------|------|
| 7.1 | 章構成管理 | テンプレートから抽出した章構成の管理と生成順序制御 |
| 7.2 | ルール検索連携 | 各章生成時に RAG から関連ルールを取得 |
| 7.3 | 設計ルール連携 | Impact Agent から設計ルールの制約を受けて生成 |
| 7.4 | データ抽出 | StructuredSource から当該章に必要なデータを抽出 |
| 7.5 | 関連情報連携 | ImpactReport から当該要素の関連関係を抽出 |
| 7.6 | プロンプト設計（章ごと） | 各章（機能一覧/画面一覧/DB設計/…）の生成プロンプト設計 |
| 7.7 | テンプレート注入 | docxtpl による Word テンプレート充填 |
| 7.8 | 記入規則プロンプト設計 | 書き方ルールをプロンプトに組み込む戦略 |
| 7.9 | Writer Agent 統合テスト | 全章生成テスト・ルール遵守テスト |
### 検収基準
- テンプレートの各章に正しい内容が注入される
- 書き方ルールに沿った生成がされる
- 設計ルールの制約が反映される
- 生成内容に source_uri の Provenance が付与されている
- ルール遵守の単体テストが通る
---
## フェーズ 8: QA Agent
### 目標
生成された設計書の品質を検証する。
### タスク一覧
| # | タスク | 詳細 |
|---|-------|------|
| 8.1 | フォーマット検証 | テンプレートとのスタイル一致性チェック（フォント・サイズ・色・表書式）＝10項目中 #1 |
| 8.2 | 内容検証 | 要件定義のデータが正しく反映されているか（LLM検証）＝10項目中 #2,#3,#4 |
| 8.3 | ルール遵守検証 | RAG から取得したルールと生成内容の一致性チェック＝10項目中 #5,#6,#7,#9 |
| 8.4 | 可追溯性検証 | 各生成内容に source_uri が付与されているか＝10項目中 #8 |
| 8.5 | 章構成完整性検証 | テンプレート章構造との対比（欠章検出）＝10項目中 #10 |
| 8.6 | QAレポート出力＋Writerフィードバック | 検証結果レポート生成＋エラー章のみ Writer へフィードバック（再生成ループ）|
| 8.7 | QA Agent 統合テスト | 各種不備パターンの検出テスト |
> 詳細: docs/design.md §7（QA 10項目チェックリスト・二重検証方針・フィードバックループ）
### 検収基準
- フォーマット不備（フォント違い・サイズ違い）を検出できる
- 要件定義にない内容を hallucination として検出できる
- ルール違反を検出できる
- 検証レポートが正しく出力される
- エラー章のみ Writer へフィードバックされ再生成される
---
## フェーズ 9: 統合テスト・調整
### 目標
全 Agent の連携動作確認、エラーシナリオの網羅、性能調整。
### タスク一覧
| # | タスク | 詳細 |
|---|-------|------|
| 9.1 | エンドツーエンドテスト | ファイルアップロード→設計書ダウンロード の全フローテスト（サンプルデータ: docs/sample-spec.md に基づく `samples/` の 7 ファイル） |
| 9.2 | 異常系テスト | ファイル不正・LLM失敗・ネットワーク切断・途中中断→再開 |
| 9.3 | 性能テスト | 大規模Excel（1000行以上）・多数ルール文書・大規模現行コード |
| 9.4 | プロンプト調整 | 各種シナリオでプロンプトの精度検証・改善 |
| 9.5 | エラーメッセージ調整 | 全エラーケースのメッセージ確認・ユーザーフレンドリーな表現 |
### 検収基準
- 3つの実サンプルデータ（新規/追加改修/自由記述型）で正常動作
- 異常系シナリオで正しいエラー処理とユーザー選択肢表示
- 10MB以上のExcelでも性能問題なく動作
---
## フェーズ 10: 成果物整備
### 目標
大会提出用成果物の完成。
### タスク一覧
| # | タスク | 詳細 |
|---|-------|------|
| 10.1 | README 作成 | インストール手順・実行方法・環境要件・API Key設定・依存関係 |
| 10.2 | 実験レポート | テストケース一覧・実行結果・成功率・エラー率・改善点 |
| 10.3 | AI使用ログ整理 | 全開発過程の AI 使用ログ確認、范式步骤の最終調整 |
| 10.4 | デモ動画作成 | 動作デモ（15分以内）・正常フロー + 例外処理 |
| 10.5 | 最終動作確認 | クリーン環境でのインストール→動作→アンインストール確認 |
### 検収基準
- README 通りに進めてクリーンインストール・動作可能
- 実験レポートに全テスト結果と評価データが記載されている
- AI使用ログが全過程をカバーしている
- デモ動画が正常フローと例外処理を含む
---
## 依存関係グラフ
```
Phase 1 (基盤: 共通ツール + 运行时层)
│ FileReader/CodeParser/ImageAnalyzer
│ InferenceEngine / ToolExecutor / 状态機械 / MemoryService / 可観測性
▼
Phase 2 (Excel解析) ──────────────────┐
│ │
▼ │
Phase 3 (Word/PPT/現行探索) │
│ │
├────────────────────────────────────┘
│ │
Phase 4 (RAG) ────────────────────────┤
│ │
▼ │
Phase 5 (Impact Agent) ────────────────┤
│ │
▼ │
Phase 6 (Web UI) ←─────────────────────┘
│
▼
Phase 7 (Writer Agent) ─── Phase 8 (QA Agent)
│
▼
Phase 9 (統合テスト)
│
▼
Phase 10 (成果物整備)
```
## リスクと注意点
| リスク | 影響 | 対策 |
|-------|------|------|
| LLM のプロンプト結果が不安定 | 各Agentの出力品質に直結 | プロンプトは早期にプロトタイプ作成、大量テスト |
| ルール文書のバリエーションが未知 | RAGの精度に影響 | 複数パターンのルール文書で早期テスト |
| 現行システムのコード解析が不完全 | 追加改修シナリオの品質低下 | 設計書ベースの現行把握で補完、コード解析は段階的 |
| Web UI の開発工数が大きい | 全体スケジュールに影響 | バックエンド先行開発、UIは後追いでOK |
| 大会期限（11月） | 時間制約 | MVP（最小機能）を早期確立し、段階的に拡張 |
Reference in New Issue View Git Blame Copy Permalink