# 撰寫指引及大綱生成

此功能用於根據已解析完成的報告模板，自動生成結構化的「撰寫指引」。系統會根據 Template Extractor 輸出的 Jinja template 框架與各 slot 的範例內容，分析報告的整體用途、章節結構、欄位意義與撰寫規則，並輸出可供後續確認與報告生成使用的 JSON 格式資料。

此撰寫指引主要用於以下兩個情境：

- **Checkpoint 2**：讓使用者確認章節架構與各章節撰寫規範，確認後模板正式建立完成。

- **Phase 2 輸入**：作為 Report Generation Agent 的輸入依據，讓 Agent 後續可以依照章節逐步執行 RAG 查詢與內容生成。

---

### 功能說明

報告生成 Workflow Phase 1 中，當 **Template Extractor** 完成模板解析後，系統會取得：

- 模板的固定框架，也就是 Jinja template

- 模板中的可變欄位，也就是 slots

- 每個 slot 的範例內容

Outline Generator 會根據上述資料，自動判斷報告的章節結構、撰寫規範、資料需求與 slot 使用方式，並產生一份結構化的撰寫指引。

此撰寫指引後續可提供給使用者確認，也可作為 Report Generation Agent 執行報告生成時的規格依據。

---

### 整體流程

```text
Template Extractor 完成模板解析
  ↓
取得 Jinja template 框架與 slots 範例內容
  ↓
Outline Generator 分析模板結構
  ↓
產生 global 全局撰寫指引
  ↓
產生 chapters 章節級撰寫指引
  ↓
產生各章節 slot_map
  ↓
進入 Checkpoint 2，等待使用者確認
  ↓
確認後模板正式建立完成
```

---

### 輸入資料

Outline Generator 的輸入來自 Template Extractor 的輸出結果。

| **Input** | **Type** | **Description** |
| --- | --- | --- |
| jinja_template | string | Template Extractor 輸出的 Jinja template 框架，代表報告模板中的固定結構 |
| slots | object | 模板中各 slot 的範例內容，代表報告中可被替換或填入的變動欄位 |
| template_context | object | 模板解析過程中可取得的補充資訊，例如章節順序、標題、段落結構等 |

---

### 輸入範例

```text
{
"jinja_template":"<h1>{{ report_title }}</h1><h2>Executive Summary</h2><p>{{ executive_summary }}</p><h2>Financial Performance</h2><p>{{ financial_performance }}</p>",
"slots": {
"report_title":"2025 Q1 Financial Report",
"executive_summary":"This quarter showed stable revenue growth...",
"financial_performance":"Revenue increased by 12% compared to the previous quarter..."
  }
}
```

---

### 輸出格式

Outline Generator 會輸出一個 JSON 物件，包含兩個頂層欄位：

- `global`：整份報告共用的全局撰寫指引

- `chapters`：依照模板章節順序產生的章節級撰寫指引

```text
{
"global":"<全局撰寫指引（自由文字）>",
"chapters": [
    {
"guide":"<章節撰寫指引（自由文字）>",
"slot_map": [
        {
"name":"<slot 名稱，對應 Jinja template>",
"description":"<此 slot 應填入的內容說明>"
        }
      ]
    }
  ]
}
```

---

### Field Explanation

| **Field** | **Type** | **Detail** |
| --- | --- | --- |
| global | string | 全局撰寫指引，用於描述整份報告的定位、語氣、規則與整體撰寫要求 |
| chapters | array | 章節撰寫指引陣列，順序應對應原始模板中的章節順序 |
| chapters[].guide | string | 單一章節的撰寫指引，用於描述該章節目的、內容重點、資料需求與撰寫方式 |
| chapters[].slot_map | array | 該章節包含的 slot 對應說明 |
| chapters[].slot_map[].name | string | slot 名稱，需對應 Jinja template 中的變數名稱 |
| chapters[].slot_map[].description | string | 該 slot 應填入的內容說明 |

---

## global 全局撰寫指引

`global` 為自由文字欄位，由 LLM 根據模板內容自動分析並產生。

此欄位主要描述整份報告共用的撰寫規範，可能包含但不限於以下內容：

| **項目** | **說明** |
| --- | --- |
| 報告類型與整體定位 | 判斷此模板屬於財務報告、研究報告、專案報告、審查報告或其他類型 |
| 目標受眾 | 說明報告主要閱讀者，例如主管、客戶、審查委員、投資人或內部團隊 |
| 語氣與立場 | 定義整份報告的語氣，例如正式、客觀、中立、精簡或分析導向 |
| 負面約束 | 說明禁止事項，例如不得推測、不得加入未提供的資料、不得使用過度主觀語句 |
| 資料時效性要求 | 說明資料應以最新資訊為準，或需明確標示資料期間 |
| 跨章節一致性規則 | 定義術語、格式、單位、日期、公司名稱與數值呈現方式需保持一致 |

---

### global 範例

```text
{
"global":"本報告應以正式、客觀且資料導向的語氣撰寫，主要面向企業內部主管與決策者。內容應避免未經資料支持的推測，所有財務數據與趨勢描述皆需以可查證資料為依據。跨章節需保持公司名稱、財務指標、時間區間與單位格式一致。若資料來源不足，應明確標示限制，不得自行補足不存在的資訊。"
}
```

---

## chapters 章節撰寫指引

`chapters` 是一個陣列，應依照原始模板中的章節順序排列。

每一個 chapter 代表報告中的一個主要章節，包含：

- `guide`：該章節的撰寫規範

- `slot_map`：該章節使用到的 slot 與欄位說明

---

### guide 章節撰寫指引

`guide` 為自由文字欄位，由 LLM 根據該章節的標題、內容結構與 slot 範例自動生成。

可能包含但不限於以下內容：

| **項目** | **說明** |
| --- | --- |
| 章節目的與定位 | 說明此章節在整份報告中的功能，例如摘要、背景說明、數據分析或結論建議 |
| 內部子結構 | 說明章節內建議的段落或小節順序 |
| 必要與可選內容 | 定義此章節必須包含哪些資訊，哪些內容可依資料狀況補充 |
| RAG 查詢提示 | 說明後續生成此章節時，應搜尋哪些類型的資料 |
| 章節特殊語氣 | 若此章節需要不同於全局規範的語氣，可在此說明 |
| 章節間依賴關係 | 若此章節需要引用前面章節的分析結果，可在此說明 |

---

### slot_map 欄位對應說明

`slot_map` 用於描述該章節中每個 slot 應填入的內容。

每一筆 slot_map 需包含：

| **Field** | **Type** | **Detail** |
| --- | --- | --- |
| name | string | slot 名稱，需對應 Jinja template 中的變數名稱 |
| description | string | 此 slot 應填入的內容說明，可作為後續 Report Generation Agent 的生成依據 |

---

### chapters 範例

```text
{
"chapters": [
    {
"guide":"本章節作為整份報告的摘要，應簡要說明報告期間、核心發現、主要指標變化與管理層需要關注的重點。內容應避免過度細節，重點在於提供快速理解報告結論的入口。若後續章節包含詳細數據分析，本章僅需摘要呈現，不需重複完整推導過程。",
"slot_map": [
        {
"name":"executive_summary",
"description":"填入本期報告的整體摘要，應包含主要結論、關鍵數據變化與需要管理層關注的重點。"
        }
      ]
    },
    {
"guide":"本章節應聚焦於財務表現分析，說明收入、成本、毛利、營業利益或其他關鍵財務指標的變化。撰寫時應優先引用具體數據與比較基準，例如與前一季、去年同期或預算目標相比。若資料來源允許，應補充造成變化的可能原因，但不得超出資料可支持的範圍。",
"slot_map": [
        {
"name":"financial_performance",
"description":"填入財務表現分析內容，包含主要財務指標、變化幅度、比較基準與合理的資料支持說明。"
        }
      ]
    }
  ]
}
```

---

## 完整輸出範例

```text
{
"global":"本報告應以正式、客觀且資料導向的語氣撰寫，主要面向企業內部主管與決策者。內容應避免未經資料支持的推測，所有財務數據與趨勢描述皆需以可查證資料為依據。跨章節需保持公司名稱、財務指標、時間區間與單位格式一致。若資料來源不足，應明確標示限制，不得自行補足不存在的資訊。",
"chapters": [
    {
"guide":"本章節作為整份報告的摘要，應簡要說明報告期間、核心發現、主要指標變化與管理層需要關注的重點。內容應避免過度細節，重點在於提供快速理解報告結論的入口。若後續章節包含詳細數據分析，本章僅需摘要呈現，不需重複完整推導過程。",
"slot_map": [
        {
"name":"executive_summary",
"description":"填入本期報告的整體摘要，應包含主要結論、關鍵數據變化與需要管理層關注的重點。"
        }
      ]
    },
    {
"guide":"本章節應聚焦於財務表現分析，說明收入、成本、毛利、營業利益或其他關鍵財務指標的變化。撰寫時應優先引用具體數據與比較基準，例如與前一季、去年同期或預算目標相比。若資料來源允許，應補充造成變化的可能原因，但不得超出資料可支持的範圍。",
"slot_map": [
        {
"name":"financial_performance",
"description":"填入財務表現分析內容，包含主要財務指標、變化幅度、比較基準與合理的資料支持說明。"
        }
      ]
    },
    {
"guide":"本章節應整理主要風險、限制與後續建議。撰寫時應清楚區分已發生的事實、根據資料推導出的風險，以及建議採取的行動。若建議涉及資源投入或決策變更，應說明其依據與預期影響。",
"slot_map": [
        {
"name":"risk_and_recommendations",
"description":"填入本期報告中的主要風險、限制、管理建議與後續行動方向。"
        }
      ]
    }
  ]
}
```

---

## 與建立報告模板 API 的關係

Outline Generator 是建立報告模板流程中的其中一個內部模組。

在建立報告模板 API 中，使用者先透過：

```text
POST /v1/report-generation/templates
```

建立模板並觸發 PDF 解析。

當 Template Extractor 完成後，模板狀態會進入：

```text
pending_confirm
```

使用者確認 slot 結構後，透過：

```text
POST /v1/report-generation/templates/{id}/confirm
```

觸發 Outline Generator，並將狀態轉為：

```text
generating_guidelines
```

當撰寫指引生成完成後，模板狀態會轉為：

```text
completed
```

---

### 狀態對應

| **State** | **說明** | **Outline Generator 關係** |
| --- | --- | --- |
| parsing_template | 系統正在執行 PDF 轉換與模板欄位抽取 | 尚未執行 |
| pending_confirm | Template Extractor 已完成，等待使用者確認 slots | 等待使用者確認後執行 |
| generating_guidelines | 系統正在產生撰寫指引 | Outline Generator 執行中 |
| completed | 撰寫指引已產生，模板可用 | 已完成 |
| failed | 任一非同步步驟失敗 | 若 Outline Generator 失敗，會進入此狀態 |

---

## Report Generation Agent 使用方式

完成後的撰寫指引會作為 Phase 2 報告生成流程的輸入。

Report Generation Agent 可依據 `chapters` 的順序逐章節處理：

```text
讀取 global 全局規範
  ↓
依序讀取 chapters[]
  ↓
根據 chapter.guide 判斷章節目標與資料需求
  ↓
根據 slot_map 確認本章節需要生成哪些欄位
  ↓
針對章節需求執行 RAG 查詢
  ↓
生成對應 slot 的內容
  ↓
回填至 Jinja template
```

---

### Agent 使用重點

| **項目** | **說明** |
| --- | --- |
| global | 作為整份報告共用的最高層級規範 |
| chapters[].guide | 作為單一章節的生成任務說明 |
| chapters[].slot_map | 告訴 Agent 該章節需要填入哪些 slot，以及每個 slot 的內容要求 |
| slot name | 必須能對應回 Jinja template 中的變數名稱 |
| description | 可作為 RAG query planning 與內容生成時的重要依據 |

---

## 注意事項

| **Item** | **Description** |
| --- | --- |
| 輸出順序 | `chapters` 順序應與模板中的章節順序一致 |
| Slot 對應 | `slot_map[].name` 必須對應 Jinja template 中存在的 slot |
| 自由文字 | `global` 與 `guide` 為自由文字欄位，允許 LLM 根據模板自行決定撰寫指引內容 |
| 結構化欄位 | `slot_map` 為結構化欄位，需明確列出 slot 名稱與內容說明 |
| 使用者確認 | 生成結果會作為 Checkpoint 2 的確認內容 |
| 後續生成 | 撰寫指引會作為 Phase 2 Report Generation Agent 的輸入 |
| 資料約束 | 指引應避免要求 Agent 生成無資料支持或超出模板用途的內容 |

---

## 不包含範圍

本功能不包含以下項目：

| **Feature** | **Description** |
| --- | --- |
| PDF 轉換 | PDF 轉 HTML 由 Document Converter 負責 |
| Template slot 抽取 | Jinja template 與 slots 抽取由 Template Extractor 負責 |
| 使用者介面 | 不包含 Checkpoint 2 的前端 UI / UX |
| 報告內容生成 | 不包含 Phase 2 的正式報告內容生成 |
| RAG 查詢執行 | 本階段僅產生撰寫指引，不直接執行 RAG |
| 模板儲存 API | 模板建立與狀態管理由建立報告模板 API 負責 |
