storyforge-studio 0.1.0__tar.gz

storyforge_studio-0.1.0/.githooks/pre-commit

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# StoryForge 本地端門口哨兵 (Pre-commit Hook)
+# 只檢查本次暫存 (staged) 的 Python 檔案
+
+set -e
+
+# 取得本次 git add 暫存的新增、複製、修改之 Python 檔案
+STAGED_PY_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$' || true)
+
+if [ -z "$STAGED_PY_FILES" ]; then
+    exit 0
+fi
+
+echo "🔍 [本地哨兵] 正在檢查本次暫存的 Python 檔案..."
+
+LINT_ERR=0
+FORMAT_ERR=0
+
+# 1. 程式碼品質與錯誤檢查
+if ! uv run ruff check $STAGED_PY_FILES; then
+    LINT_ERR=1
+fi
+
+# 2. 程式碼排版風格檢查
+if ! uv run ruff format --check $STAGED_PY_FILES; then
+    FORMAT_ERR=1
+fi
+
+if [ $LINT_ERR -ne 0 ] || [ $FORMAT_ERR -ne 0 ]; then
+    echo ""
+    echo "❌ [本地哨兵] 發現本次存檔的程式積木有瑕疵或沒排整齊！"
+    echo "💡 請執行下列指令快速整理修正，並重新 git add 後再次存檔："
+    echo "   uv run ruff check --fix $STAGED_PY_FILES"
+    echo "   uv run ruff format $STAGED_PY_FILES"
+    echo ""
+    exit 1
+fi
+
+echo "✅ [本地哨兵] 檢查全數通過，放行存檔！"
+exit 0

storyforge_studio-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '**/*.py'
+      - 'ui/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/ci.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - '**/*.py'
+      - 'ui/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/ci.yml'
+
+jobs:
+  test-and-lint:
+    name: Lint & Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Check code quality (Ruff lint)
+        run: uv run ruff check .
+
+      - name: Check code formatting (Ruff format)
+        run: uv run ruff format --check .
+
+      - name: Run unit tests (pytest)
+        run: uv run pytest

storyforge_studio-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release & Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  quality-gate:
+    name: Lint & Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Check code quality (Ruff lint)
+        run: uv run ruff check .
+
+      - name: Check code formatting (Ruff format)
+        run: uv run ruff format --check .
+
+      - name: Run unit tests (pytest)
+        run: uv run pytest
+
+  build-and-publish:
+    name: Build & Publish to PyPI
+    needs: quality-gate
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/storyforge-studio
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build package distributions
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

storyforge_studio-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+storyforge_config.json
+
+*.pyc
+__pycache__/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+.DS_Store

storyforge_studio-0.1.0/AGENTS.md

@@ -0,0 +1,31 @@
+# 專案說明書
+
+## 專案與角色
+- **目標**：文字交由 AI 導演（情緒、角色、聲音表演）轉為生動有聲書。
+- **用戶**：非工程師。絕不要求用戶改程式碼。需操作時提供步驟化引導。付費服務事先報價確認。
+
+## 溝通原則
+- **語言**：全程繁體中文。
+- **表達**：禁工程術語，技術概念用五歲小孩比喻。
+- **回報**：每步完成以白話說明「做了什麼」與「原因」。
+- **決策**：白話列出選項並附推薦建議。
+
+## 開發規範
+- **架構**：Clean Architecture（核心邏輯、UI、外部服務分層解耦）。
+- **流程**：嚴格 TDD（先寫測試驗收條件，實作後驗證全過）。
+
+## Agent skills
+
+### Issue tracker
+
+GitHub Issues via `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Canonical five-role vocabulary (`needs-triage`, `ready-for-agent`, etc.). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout (`CONTEXT.md` and `docs/adr/`). See `docs/agents/domain.md`.
+
+

storyforge_studio-0.1.0/CONTEXT.md

@@ -0,0 +1,116 @@
+# StoryForge
+
+將文字故事轉換為具備情緒、角色演繹與生動聲音的有聲書電腦軟體。
+
+## Language
+
+**StoryForge**:
+本專案的名稱，一個在電腦上執行的有聲書產生工具。
+_Avoid_: 小工具、App
+
+**AI 導演 (AI Director)**:
+負責理解文字故事中的情緒與角色，並決定如何發聲的核心大腦。目前使用的是 Gemini 3.8 Flash。
+_Avoid_: 語音合成器、文字轉語音、TTS 模型
+
+**故事原稿 (Source Text)**:
+使用者直接貼上的原始文字，這是 AI 導演的輸入。
+_Avoid_: 腳本、輸入檔
+
+**劇本拆解 (Script Breakdown)**:
+AI 導演將原稿自動分析並拆解成一段段「旁白」與「不同角色的對話」，並加上情緒標記的過程。
+_Avoid_: 文字分析、前處理
+
+**有聲書成品 (Audio Output)**:
+最後產生出來並存檔的 MP3 聲音檔，可以直接播放或分享。
+_Avoid_: 輸出檔、結果
+
+**劇本編輯區 (Script Editor)**:
+讓你在 AI 拆解完劇本後，可以手動修改角色、情緒或台詞的畫面。
+_Avoid_: 修改介面
+
+**API 通行證 (API Key)**:
+用來證明你有權限使用 Gemini 大腦的專屬密碼，只要設定一次就會自動記住。
+_Avoid_: 金鑰、憑證
+
+**場景 (Scene)**:
+AI 導演將劇本自動分割成的段落，每個場景代表一個情節單元（時間地點或情緒基調相對一致）。每個場景有 AI 自動取的標題，包含若干台詞行，並對應一個獨立的音檔。場景是重新生成語音的最小單位。
+_Avoid_: 段落、片段、chunk
+
+**聲音導演備註 (Voice Direction Note)**:
+AI 導演在劇本拆解時為每一行台詞附加的聲音指示文字（例如 `[excited, fast-paced]` 或「用顫抖的聲音輕聲說」），直接作為語音生成時的情緒提示。
+_Avoid_: 情緒標記、TTS prompt
+
+**角色聲音對應表 (Voice Map)**:
+記錄每個角色對應哪個語音聲線的設定，由 AI 導演初步建議，使用者可修改。每個故事有自己的對應表，存放於故事資料夾中。
+_Avoid_: 聲音設定、語音配置
+
+**聲音演員庫 (Voice Actor Catalog)**:
+內建 30 位具備不同聲音特質（如活潑、成熟、溫柔、粗獷等）的 AI 配音演員名冊，供 AI 導演依據故事角色個性挑選最合適的聲線。
+_Avoid_: TTS 清單、模型列表、聲線清單
+
+**聲音性別 (Voice Gender)**:
+聲音演員庫中每位演員專屬的性別屬性（分為男性、女性、中性）。中性保留給非人類角色（如怪獸、精靈）或旁白使用，以避免 AI 盲選造成爸爸配女聲等性別錯置。
+_Avoid_: 男女標籤
+
+**說書人 (Narrator)**:
+故事中的旁白角色，擁有專屬且穩定的平穩聲線（預設為 Kore），與一般故事角色分開，不互相共用。
+_Avoid_: 旁白語音、主述者
+
+
+**故事資料夾 (Story Folder)**:
+每個故事專屬的存放位置（預設為 `~/Documents/StoryForge/<故事名稱>/`，亦可為使用者自選的電腦資料夾），內含各場景的音檔、角色聲音對應表，以及最終的有聲書成品。
+_Avoid_: 輸出目錄、資料夾
+
+**故事選單視窗 (Story Selector)**:
+點擊載入舊劇本時彈出的視窗，列出所有既有故事名稱、場景數量與修改時間，並提供直接挑選電腦資料夾的按鈕。
+_Avoid_: 檔案總管、dialog、選單彈窗
+
+
+**聲音拼接 (Audio Mixing)**:
+將各場景的獨立音檔依序合併成最終有聲書成品的過程。在所有場景都生成完畢後執行。
+_Avoid_: 合併、concatenate
+
+**場景背景音樂 (Scene BGM)**:
+故事共用的配樂主題（如日常、緊張、戰鬥）。AI 導演在劇本拆解前建立「BGM 主題對應表」，拆解場景時僅從表中挑選（存於 `bgm_theme_id`）。聲音拼接時，每主題僅生成一次音檔並跨場景共用。以 -18 dB 恆定墊底混入對白，首尾 2 秒淡入/淡出，超長無縫循環。
+_Avoid_: 獨立配樂、環境音效
+
+**BGM 主題對應表 (BGM Theme Map)**:
+記錄故事所有 BGM 主題設定（ID、中文名稱、英文 prompt）的檔案（`bgm_map.json`），存於故事資料夾。使用者修改主題會連動所有套用該主題之場景。
+_Avoid_: 總表、配樂清單
+
+**思考深度 (Thinking Level)**:
+AI 導演在拆解劇本與生成聲音導演備註時的思考深淺程度（分為 MEDIUM 與 LOW）。
+_Avoid_: model parameter, reasoning level
+
+**劇本進度檔 (Screenplay Progress)**:
+記錄了 AI 拆解完並經過使用者修改的場景與台詞資料，自動存檔於故事資料夾中的檔案，可隨時載入恢復進度。
+_Avoid_: cache file, save state
+
+**合奏朗讀 (Multi-speaker Recording)**:
+AI 導演在一個場景中，將最多兩位角色（含說書人）的台詞或對白打包在一起同時演繹出聲音的方式，能大幅縮短錄音時間並提升演繹的自然度。
+_Avoid_: 多人語音合成、批次 TTS
+
+**朗讀對話組 (Dialogue Group)**:
+在合奏朗讀時，由相鄰台詞且角色不超過兩位所組合而成的小段落，為單次交由 AI 導演演繹的單位（若只有一人自白或連續旁白，則為單人朗讀組，同樣整組合併錄音）。
+_Avoid_: batch, chunk, 對話批次
+
+**故事設定檔 (StoryForge Config)**:
+記錄 API 通行證與思考深度設定的秘密筆記本，自動儲存於個人的 `~/Documents/StoryForge/storyforge_config.json`，不管在電腦哪個角落開啟都能記住。
+_Avoid_: 設定檔、環境變數、.env
+
+**本地哨兵 (Pre-commit Hook)**:
+在電腦本機每次要把改好的故事程式積木存檔打包前，在門口快檢檔案有沒有排整齊的小幫手。
+_Avoid_: pre-commit script, hook
+
+**雲端守門員 (GitHub CI)**:
+當把寫好的故事程式送到 GitHub 雲端時，自動在雲端乾淨電腦裡替我們把所有積木全部重新檢查與跑測試的自動化機器人。
+_Avoid_: CI/CD, pipeline, Actions runner
+
+**官方世界超市 (PyPI)**:
+全球 Python 軟體的公開大貨架。使用者電腦只要輸入 `uvx storyforge-studio`，跑腿小幫手就會直接到這座超市把軟體拿下來執行。
+_Avoid_: package index, 包倉庫
+
+**免密鑰安全授權 (Trusted Publishing)**:
+GitHub 雲端守門員與 PyPI 超市之間彼此相認的免密碼身分證。替故事軟體貼上新版本貼紙時，自動把軟體安全送上超市，不需在電腦留下任何密碼。
+_Avoid_: PyPI token, API key, OIDC
+

storyforge_studio-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# 開發者與協作者貢獻指南 (Contributing Guide)
+
+感謝你對 StoryForge 的關注！本專案旨在打造將文字故事轉換為生動有聲書的高品質工具。
+
+為了確保軟體核心邏輯清晰、穩定可維護，本專案嚴格遵守 **整潔架構 (Clean Architecture)** 與 **測試驅動開發 (Strict TDD)** 規範。請在參與貢獻前詳閱以下原則。
+
+---
+
+## 🛠️ 開發環境設定
+
+本專案使用現代化 Python 依賴管理工具 [`uv`](https://github.com/astral-sh/uv)。
+
+1. **複製專案**：
+   ```bash
+   git clone https://github.com/jonascheng/storyforge-studio.git
+   cd storyforge-studio
+   ```
+
+
+2. **同步依賴環境**：
+   ```bash
+   uv sync
+   ```
+
+3. **啟用本機門口哨兵 (Git Hooks)**：
+   ```bash
+   git config core.hooksPath .githooks
+   ```
+
+4. **啟動本機開發介面**：
+   ```bash
+   uv run storyforge
+   # 或
+   uv run python main.py
+   ```
+
+5. **執行程式碼風格檢查與自動排版**：
+   ```bash
+   # 檢查品質與瑕疵
+   uv run ruff check .
+
+   # 檢查排版風格
+   uv run ruff format --check .
+
+   # 自動修復可修正之問題
+   uv run ruff check --fix .
+   uv run ruff format .
+   ```
+
+6. **驗證所有自動化測試**：
+   ```bash
+   uv run pytest
+   ```
+
+---
+
+## 🏛️ 架構原則：整潔架構 (Clean Architecture)
+
+專案分層解耦，單向依賴，核心業務邏輯絕不受外部框架或技術細節干擾：
+
+```
+[ UI 介面層 ] (ui/ + pywebview)
+      ↓
+[ 核心業務層 ] (core/entities.py & core/use_cases.py)
+      ↑
+[ 外部基礎層 ] (infrastructure/ - Gemini API, Storage, AudioMixer)
+```
+
+- **`core/`（核心邏輯層）**：
+  - `entities.py`：定義場景（Scene）、劇本台詞（ScriptLine）、劇本（Screenplay）等純資料物件。
+  - `use_cases.py`：定義劇本拆解、語音生成工作流，以及 `IDirector`、`IStorage` 抽象介面。
+  - ⚠️ **禁令**：本層絕不可直接引用任何外部函式庫（如 `google-genai`、`pydub`、`webview`）。
+- **`infrastructure/`（外部實作層）**：
+  - 實作 `core` 所定義的介面，例如 `GeminiDirector` 串接 Google Gemini API、`StoryFolderStorage` 管理硬碟檔案、`AudioMixer` 處理音訊拼接。
+- **`ui/`（使用者介面層）**：
+  - HTML5、Vanilla CSS、Vanilla JavaScript 前端，透過 `pywebview` 的 JS API 與後端溝通。
+
+---
+
+## 🧪 開發流程：嚴格測試驅動開發 (Strict TDD)
+
+所有新功能開發或錯誤修復，**必須遵循紅燈-綠燈-重構（Red-Green-Refactor）流程**：
+
+1. **先寫測試（Red）**：在 `tests/` 新增測試案例，描述預期行為與驗收條件，確認測試失敗。
+2. **編寫實作（Green）**：編寫最少必要程式碼，使測試通過。
+3. **重構優化（Refactor）**：在測試保護傘下重構程式碼，維持高可讀性與架構純潔性。
+4. **全測試驗證**：送出前必須確認 `uv run pytest` 全數通過（目前共有 49 項測試）。
+
+---
+
+## 📋 Issue 與 Pull Request 流程
+
+本專案使用 GitHub Issues 與 Pull Requests 管理工作。
+
+### Triage 標籤分類
+專案遵循 `docs/agents/triage-labels.md` 定義之五大標準標籤：
+- `needs-triage`：新建立的議題，待審查其問題完整性。
+- `ready-for-agent`：需求明確、驗收條件清楚，可立即指派開發。
+- `agent-working`：目前正在進行開發。
+- `needs-human-review`：實作完成，等待人工驗收審查。
+- `done`：已驗收並合併完成。
+
+### 送出 Pull Request (PR) 檢核清單
+在提交 PR 之前，請確認：
+- [ ] 遵循 Clean Architecture 架構分層。
+- [ ] 執行 `uv run ruff check .` 與 `uv run ruff format --check .` 確認排版與品質檢查全數通過。
+- [ ] 執行 `uv run pytest` 確認所有測試 100% 通過。
+- [ ] 新增或修改的功能具備對應的單元或整合測試。
+- [ ] 若涉及重要決策，已撰寫或更新對應的 [ADR (Architecture Decision Record)](docs/adr/)。
+- [ ] PR 描述清晰說明修改動機與驗證成果。
+
+---
+
+## 📦 發布新版本至 PyPI (Release Process)
+
+本專案透過 GitHub Actions 與 PyPI **免密鑰安全授權 (Trusted Publishing)** 進行自動發布：
+
+1. **更新版本號**：在 `pyproject.toml` 更新 `version = "x.y.z"`。
+2. **建立 GitHub Release**：
+   - 建立並發布新 Release，Tag 名稱標註為 `vx.y.z`（例如 `v0.1.0`）。
+3. **自動上架**：
+   - 雲端工作流（`release.yml`）會自動觸發品質安檢（Ruff + pytest）。
+   - 安檢全數通過後自動執行 `uv build` 打包，並透過 OIDC 安全上傳至 PyPI 官方貨架。
+   - 使用者即可直接以 `uvx storyforge-studio` 取得最新版本。
+

storyforge_studio-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.5
+Name: storyforge-studio
+Version: 0.1.0
+Summary: 將文字故事轉換為具備情緒、角色演繹與生動聲音的有聲書電腦軟體
+Author: Jonas Cheng
+Requires-Python: >=3.11
+Requires-Dist: audioop-lts>=0.2.1; python_version >= '3.13'
+Requires-Dist: google-genai>=0.1.0
+Requires-Dist: pydub>=0.25.1
+Requires-Dist: pyobjc-framework-webkit>=10.0; sys_platform == 'darwin'
+Requires-Dist: pythonnet>=3.0.0; sys_platform == 'win32'
+Requires-Dist: pywebview>=5.0.0
+Requires-Dist: static-ffmpeg>=2.5
+Description-Content-Type: text/markdown
+
+# StoryForge 🎙️✨
+
+> **將文字故事轉換為具備情緒、角色演繹與生動聲音的有聲書電腦軟體。**
+
+StoryForge 就像一位住在你電腦裡的 **AI 總導演**。只要把心中的故事靈感或文字交給他，他就會從劇本編寫、角色設定、情緒指導到配樂聲音演繹一手包辦，為你錄製出一部生動好聽的完整廣播劇/有聲書 MP3！
+
+不需要懂寫程式，不論你是用 **Windows** 還是 **Mac**，只要跟著以下三個簡單步驟，就能一鍵召喚 StoryForge 開始創作！
+
+---
+
+## 🚀 三分鐘快速上手
+
+### 第一步：召喚小助手（安裝 uv 工具）
+
+`uv` 就像是電腦裡的超級快遞員，能幫你免安裝、自動把軟體所有零件準備好。
+
+- **🪟 Windows 使用者**：
+  1. 在鍵盤上同時按下 `Win + X` 鍵，點選 **「終端機」** 或 **「PowerShell」**。
+  2. 複製以下指令貼進黑視窗中，並按 `Enter` 執行：
+     ```powershell
+     powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+     ```
+
+- **🍎 Mac 使用者**：
+  1. 在鍵盤上同時按下 `Command + 空白鍵`，輸入 `Terminal` 並打開 **「終端機」**。
+  2. 複製以下指令貼進終端機中，並按 `Enter` 執行：
+     ```bash
+     curl -LsSf https://astral.sh/uv/install.sh | sh
+     ```
+
+### 第二步：一鍵啟動 StoryForge（免安裝！）
+
+在剛剛打開的黑色終端機小視窗中，貼上以下這行指令並按 `Enter`：
+
+```bash
+uvx storyforge-studio
+```
+
+> 💡 **小秘訣**：
+> 電腦會自動準備好所有環境與音訊小工具，只要幾秒鐘，美麗的 **StoryForge 操作視窗** 就會自動彈出來囉！
+> *(若欲測試開發中未發布版本，亦可使用 `uvx --from git+https://github.com/jonascheng/storyforge-studio storyforge`)*
+
+---
+
+### 第三步：領取並設定免費通關鑰匙（Gemini API 通行證）
+
+首次啟動或尚未設定通行證時，畫面會自動跳出提醒視窗，指引您前往右上角的 **「⚙️ 設定」** 完成設定：
+
+1. 點擊設定畫面中 `Gemini API Key` 欄位旁的超連結，前往 [Google AI Studio](https://aistudio.google.com/) 網頁並登入您的 Google 帳號。
+2. 點擊畫面上的 **「Get API key」**，接著 **「Create API key」**，建立並複製那串英文數字密碼。
+3. 回到 StoryForge 貼上密碼並點擊 **「儲存」**。（只要設定一次，下次打開不用再輸入！）
+
+> 💡 **進階設定**：在「⚙️ 設定」視窗中，您也可以依需求自由調整 **「思考深度 (Thinking Level)」**（預設 MEDIUM）與 **「場景間隔停頓 (秒)」**（預設 1 秒）。
+
+---
+
+## 📖 製作第一本有聲書（操作指引）
+
+當 StoryForge 視窗跳出來後，照著以下清晰步驟就能輕鬆完成作品：
+
+```
+ [1. 通行證設定] ⚙️
+        ↓
+ [2. 輸入故事想法] 💡（或 📂 載入舊劇本）
+        ↓
+ [3. 故事劇本確認與微調] 📝（角色卡片、世界觀、✨ 讓 AI 重寫 / ↩️ 復原）
+        ↓
+ [4. 廣播劇本拆解與錄音] 🎬（BGM 配樂、台詞情緒、🎙 生成語音 / ▶️ 試聽）
+        ↓
+ [5. 產出完整有聲書] 🔊
+```
+
+### 1. ⚙️ 確認通行證設定
+- 確保已依照快速上手第三步，在右上角 **「⚙️ 設定」** 中填寫 Gemini API 通行證。
+- （首次啟動未設定時，系統會自動跳出提醒視窗引導您。）
+
+### 2. 💡 輸入故事想法（或載入舊進度）
+- 在「1. 輸入故事想法」文字框中貼上您的故事點子或大綱（例如：*一個關於會說話的貓和失憶魔法師的冒險故事...*）。
+- 點擊 **「✍️ AI 撰寫劇本」**，AI 編劇會自動生成故事標題、完整情節、角色設定與世界觀規則。
+- *(若是過去製作過的故事，可點擊 **「📂 載入舊劇本」** 從清單中點選，或點擊「📁 從電腦資料夾瀏覽...」直接開啟舊進度)*。
+
+### 3. 📝 故事劇本確認與微調
+- 進入「2. 故事劇本確認」畫面，您可以檢視並自訂所有故事設定：
+  - **故事內容**：可直接修改內文，亦可點擊 **「🔍 放大」** 開啟全螢幕專注編輯。
+  - **角色設定**：檢視各角色卡片，包含角色名稱、聲音類型（例如：童趣活潑[男]）與個性背景；可點擊 **「➕ 新增角色」** 或刪除角色。
+  - **世界觀規則**：檢視故事的世界背景，同樣支援 **「🔍 放大」** 編輯。
+- **AI 靈感微調**：想改變劇情走向？在下方輸入修改需求（例如：*「讓結局更感人」、「加入一個反派角色」*），點擊 **「✨ 讓 AI 重寫」**；若不滿意重寫結果，點擊 **「↩️ 復原」** 即可隨時回到上一版。
+- 確認滿意後，點擊下方 **「🎬 確認劇本，產生廣播劇」**。
+
+### 4. 🎬 廣播劇本拆解、配樂與錄音
+- 進入「3. 廣播劇本編輯區」，AI 導演已將故事切分成一個個精彩場景：
+  - **🎵 場景背景音樂 BGM 主題**：每個場景可透過下拉選單挑選 AI 規劃的專屬配樂主題（亦可選「無」）。
+  - **台詞與情緒**：每一行清楚標註【角色】、【情緒指導】與【台詞內容】，隨時可自由編輯（修改後該場景會貼心標記 `● 內容已修改`）。
+  - **🎙 單幕錄製**：點擊場景右上角的 **「🎙 生成語音」**（或 **「🎙 重新生成」**），AI 演員就會為該場景配音演繹。
+  - **▶️ 當場試聽**：錄音完成後，點擊 **「▶️」** 按鈕即可立即播放試聽該場景的聲音與配樂！
+  - **✨ 安全審查小幫手**：若台詞觸發敏感安全審查，點擊 **「✨ 讓 AI 幫我想安全的台詞」**，AI 會立即提供安全的替代台詞並支援一鍵替換。
+
+### 5. 🔊 產出完整有聲書
+- 所有場景確認完畢後，點擊最下方的 **「🔊 產出完整有聲書」**。
+- 若有尚未生成的場景，系統會貼心詢問是否自動依序補齊錄音。
+- 合併完成後，一部具備情緒演繹與背景音樂的完整有聲書就熱騰騰出爐了！
+
+---
+
+## 📂 我的有聲書存放在哪裡？
+
+你的所有故事、角色設定與錄音成果，都整整齊齊收納在電腦的專屬保險箱中：
+
+- **Windows**：`C:\Users\你的使用者名稱\Documents\StoryForge\<故事名稱>\`
+- **Mac**：`~/Documents/StoryForge/<故事名稱>/`
+
+進入該資料夾，你會看到一個名為 **`final_output.mp3`** 的檔案，這就是最終的高音質有聲書成品！你可以直接點開播放、傳到手機或分享給朋友聆聽。
+
+---
+
+## ❓ 常見問題 Q&A
+
+**Q1：需要自己安裝 ffmpeg 或其他剪輯工具嗎？**  
+不需要！StoryForge 已經貼心內建了「自動剪刀小幫手」（`static-ffmpeg`），在後台全自動處理音訊拼接，完全不需要手動設定。
+
+**Q2：換到不同資料夾打開，設定需要重打嗎？**  
+不需要！通行證與設定統一儲存在電腦的「文件/StoryForge」專屬位置，不管從哪裡啟動都能自動讀取。
+
+**Q3：我想修改某個角色的台詞或聲音，需要全部重跑嗎？**  
+不用！StoryForge 是「以場景為單位」錄音的。如果你只想改某一幕的台詞、情緒或配樂，只要單獨重新產生該場景即可，省時又節省額度。
+
+**Q4：錄音時如果遇到台詞被安全審查阻擋怎麼辦？**  
+別擔心！遇到阻擋時，該場景會出現「✨ 讓 AI 幫我想安全的台詞」按鈕。點擊後 AI 導演會為您構思既符合劇情的安全替代台詞，點選即可一鍵自動替換！
+
+---
+
+## 🤝 開發與參與貢獻
+
+想了解專案架構、參與程式碼開發、或是送出 PR 協助改進嗎？  
+歡迎閱讀 [開發者與協作者貢獻指南 (CONTRIBUTING.md)](CONTRIBUTING.md)。