marcozhou26/one-slide

OneSlide

一次只處理一頁 PPT，並以諮詢報告級標準組織邏輯、資訊和版式。使用者只接觸這一個入口；內部先完成內容設計與來源標註，需要 PPTX 時再呼叫隨包附帶的 Builder 引擎。

每次執行先讀

完整讀取：

• references/input-contract.md
• references/suite-contract.md
• producer/references/single-slide-contract.md
• producer/references/provenance-contract.md
• producer/references/output-contract.md

進入繪製階段時，再讀取 builder/ENGINE.md 和路由回傳的唯一模組 reference。不要預讀全部 Builder 模組。

首次互動

自然說明本輪只製作一頁，然後根據目前對話、附件和已確認決定預填：

• 這一頁要說明什麼；
• 誰會看，以及他看完要理解或決定什麼；
• 一個主要問題、一個主要關係和一個中心結論；
• 哪些內容由使用者提供且必須保留；
• 哪些缺口會被定向補全並標記。

只有兩個同樣合理的頁面方向會改變中心結論或主圖時，才問一個阻塞問題。不得要求使用者填寫內部欄位、模組編號、座標、卡片數量或裝飾偏好。

兩種輸出

從使用者原話推導：

• PROMPT_ONLY：使用者要求提示詞、Brief、交接包或生成指令。
• PPT_DRAFT：使用者要求直接建立、繪製、生成或交付 PowerPoint。

未說明載體時預設 PROMPT_ONLY，並簡短說明。使用者隨後改為 PPT_DRAFT 時，複用已經鎖定的來源和頁面方向，不要求重述材料。

三種內容模式

• SOURCE_ONLY：現有資訊足以支援這一頁，不新增事實。
• SYNTHETIC_AUGMENTATION：只補頁面必要缺口，不改變使用者事實和主邏輯。
• EVIDENCE_BLOCKED：目標要求真實事實，但缺少證據且不能誠實補全。

樣式、措辭、版式和圖表選擇不是事實缺口，可以從主要關係推導。

工作流

1. 鎖定單頁邊界

保留使用者原始請求，給使用的附件建立來源記錄和雜湊。每次只能有：

1 個受眾任務
1 個主要問題
1 個主要關係
1 個中心結論
1 個主圖
0-3 個支援證據主題
0-1 個行動或條件區

出現競爭性主圖或超過三個證據主題時，回傳 SINGLE_SLIDE_SCOPE_OVERLOAD，推薦最強的單頁焦點；不得暗中刪掉必需內容或生成第二頁。

2. 建立來源基線

對使用者提供、穩定推導、計算、外部核驗和模型補全分別設定穩定 source_id。保持使用者數字、定義、結論強度、必含項和排除項不變。

使用者附件是「使用者提供的證據」，不自動等於獨立核驗事實。權威值衝突時停止受影響的計算，不能暗自選邊。

3. 定向補全

內容不足時只補主圖和已宣告證據主題所需的最少內容：

• 合成資料必須定義物件、粒度、期間、單位、分母和計算規則；
• 合計、佔比、漏斗、橋接、重複值和標題結論必須能對上；
• 合成定性內容按「假設」「範例」或「待確認」處理；
• 不得編造來源、客戶原話、行業基準、法律結論或真實公司業績。

真實組織缺少真實資料時，不得把虛構指標寫在該組織名下。可以改成匿名範例，或回傳 EVIDENCE_BLOCKED。

4. 生成內容包

按 producer/ENGINE.md 執行，輸出版本化執行目錄。每個可見事實、標題、圖表資料、洞察和行動項都要有 source_ids。

合成數字或資料集必須在頁面上顯示：

合成範例資料，非真實客戶資料

合成定性內容在相鄰位置顯示「待確認」，或使用能逐項映射的頁面圖例。使用者確認採用某個情境後，它仍是情境假設，不會變成真實事實。

執行：

python3 producer/scripts/validate_package.py <run-directory> --stage handoff --write-report

結構驗證通過後仍要完整閱讀 Brief、Prompt、交接文件和內容確認清單。腳本不能證明諮詢邏輯或 PPT 視覺品質。

5. 按輸出模式交付

PROMPT_ONLY 交付：

• handoff/builder-prompt.md
• handoff/builder-handoff.json
• review/content-review.md

PPT_DRAFT 在內容包通過後讀取 builder/ENGINE.md，將 handoff/builder-handoff.json 交給內建 Builder。Builder 負責模組選擇、精確幾何、PowerPoint 物件、渲染和 PPTX QA；不得再次改寫頁面目標或來源事實。

Builder 交付後再次執行：

python3 producer/scripts/validate_package.py <run-directory> --stage final --write-report

Builder 不可用、執行依賴缺失或回傳 MODULE_COVERAGE_GAP 時，保留可用提示詞包並回傳 PPT_RENDERING_BLOCKED。不得偷偷換用普通渲染器後宣稱生成了諮詢級 PPT。

Producer 只有在一個已產品化模組能覆蓋全部必含內容時，才同時寫入 requested_module 和完整、可通過該模組 validator 的 module_payload。只有模組名沒有可執行載荷時不得強制命中；混合頁面使用具 layout 門禁的直接編排。

6. 檢查 PPTX

PPT_DRAFT 必須滿足：

• 恰好一頁、16:9；
• 文字、形狀、表格和圖表為 PowerPoint 原生可編輯物件；
• 通過語意審計、整頁渲染檢查和可讀性檢查；
• layout JSON 通過短標籤單行、孤字、英文 token、數字單位、兩行標題與副標題互斥、標題安全區、縱向空間平衡、跨區塊邊緣對齊、畫布利用率和越界門禁；
• 組織架構圖額外檢查同層節點水平對齊、一對一直屬線垂直對齊、職能虛線方向與無穿越路由；出現 ORG_PEER_ROW_MISALIGNMENT、ORG_DIRECT_REPORT_DOGLEG 或 ORG_FUNCTIONAL_ROUTE_AMBIGUOUS 時不得交付；
• 目前環境能使用 Microsoft PowerPoint 時，實際開啟檢查；
• 對外交付目錄只放版本化 PPTX，來源、提示詞、預覽和 QA 留在內部目錄。

硬邊界

• 不生成多頁報告、隱藏溢位頁或第二個候選頁。
• 不為湊滿頁面增加裝飾性卡片、建議、指標或基準。
• 不為了裝下一頁而刪必需內容、縮成不可讀字號或改變中心思想。
• 不把模型補全內容偽裝成使用者提供或外部核驗。
• 不暴露本機路徑、提示詞歷史、被否決方案、內部 QA 或製作說明。
• 不把檔案生成、驗證腳本通過或 ZIP 完整冒充產品價值或使用者驗收。

發布包自檢

python3 scripts/validate_suite.py .
python3 -m unittest discover -s tests -v
python3 scripts/check_environment.py

狀態

分別報告：

BASIC_OUTPUT_PASS | fail
TECHNICAL_CHAIN_PASS | not_tested | fail
INPUT_CONTRACT_PASS | not_tested | fail
SOURCE_BASELINE_PASS | fail
SINGLE_SLIDE_SCOPE_PASS | fail
PROVENANCE_COVERAGE_PASS | fail
SYNTHETIC_DISCLOSURE_PASS | not_applicable | fail
DATA_RECONCILIATION_PASS | not_applicable | not_tested | fail
HANDOFF_PACKAGE_PASS | fail
BUILDER_HANDOFF_READY | not_applicable | fail
RENDERED_READABILITY_PASS | not_applicable | not_tested | fail
POWERPOINT_OPEN_CHECK | not_applicable | not_tested | fail
REQUIREMENT_COVERAGE_PASS | not_tested | fail
PRODUCT_VALUE_PASS | not_tested | fail
USER_REQUIREMENT_PASS | not_tested
PUBLIC_LICENSE_READY | pass

只有真實使用者可見結果滿足本 Skill 的單頁、來源和可編輯性要求時，才能標記 PRODUCT_VALUE_PASS。只有使用者看過具體結果後，才能標記 USER_REQUIREMENT_PASS。