yizhiyanhua-ai/fireworks-open-eli5

Fireworks Open ELI5

將一個困難的系統轉化為誠實的視覺故事。首先產生一個可攜帶的 JSON 規格，然後產生一個確定性的、自我完備的 HTML 解釋器。

不可妥協的邊界

• 證據優先於視覺修飾。每個證據項目必須標記為 verified、inferred 或 analogy。
• 絕不讓類比看起來像是實作真相。
• 產生的本機 HTML 檔案僅是 generated。它不是 published、上傳、傳送或目的地驗證過的。
• 未經使用者明確要求及目的地工作流程本身的驗證，不得發布、上傳、傳送或變更存取權。
• 渲染不執行任何網路呼叫。被引用的 URL 是面向讀者的連結，而非執行時期依賴。選用的原生 Pages 動作只能呼叫同一來源（same-origin）的輔助程式，且僅限於 127.0.0.1；絕不能聯絡遠端服務。
• 瀏覽器本機的歷史記錄、書籤和註解在讀者選擇加入前是停用的。它們是便利性狀態，非證據，也絕不修改原始規格或產生的成品。
• 準確描述「歷史記錄」為同一來源中之前在此瀏覽器開啟過的解釋器。絕不能聲稱它列出了所有產生的檔案。
• PDF 匯出會呼叫瀏覽器的列印對話框。PNG 匯出一個場景；PPTX 和 Pages 相容的 DOCX 每個場景或頁面匯出為一張投影片或一頁。僅在已安裝的 Pages 應用程式確實儲存後，才允許輸出原生的 .pages 格式；絕不能將 DOCX 重新命名為 .pages。產生的下載檔案僅為本機成品。

工作流程

1. 確認觀眾、問題、語言，以及一個應貫穿故事的核心元素：請求、封包、決策、事件或使用者動作。

2. 精確選擇一個故事文法：

   • concept：直覺 → 機制 → 邊界。
   • module：入口點 → 轉換 → 輸出/依賴。
   • tradeoff：共同目標 → 競爭選項 → 後果/決策規則。
   • incident：正常路徑 → 中斷與傳播 → 偵測/復原。

3. 收集證據。對於儲存庫工作，檢查實際檔案並使用本機路徑。對於外部主張，盡可能使用權威來源。明確記錄不確定性。

4. 依照 references/spec-contract.md 建立版本 1 的 JSON 規格。使用 3–7 個場景，每個場景 2–6 個節點，包含完整的真相階梯（truth ladder）、追蹤、詞彙表、教導式回饋、證據地圖以及所需的模式特定 modeData。將失敗資訊加入到關鍵節點。

5. 在渲染前進行驗證：

   node scripts/validate.mjs path/to/spec.json
   

6. 渲染到一個新的本機檔案：

   node scripts/render.mjs path/to/spec.json path/to/explainer.html
   

   渲染器會拒絕已存在的路徑。僅當使用者明確想要取代一個已知的普通檔案時，附加 --force。強制渲染使用原子性取代，且仍然拒絕符號連結和非檔案路徑。

7. 同時驗證規格與成品：

   node scripts/validate.mjs path/to/spec.json path/to/explainer.html
   

8. 當瀏覽器可存取時，在桌面寬度和 390px 下檢視本機成品。確認有一個 h1、可讀的標籤、無水平溢出、鍵盤焦點、獨立的頁籤列表、全域及場景本機播放、視口跟隨、活躍的邊緣（real-edge）與證據卡同步、進入/按住/退出動畫階段、故障透鏡（failure lens）、答案揭示，以及零遠端資源請求。每個場景證據卡必須揭露其狀態、簡潔的核心基礎、支援範圍，以及一個 URL 或明確的無定位器邊界（no-locator boundary）。

9. 練習讀者工作區：透過滑鼠和鍵盤開啟並關閉模態抽屜；確認焦點返回；有意識地啟用資料庫（library）；重新載入並驗證書籤與純文字註解；確認歷史記錄只包含實際開啟過的同一來源解釋器。使用形似標記（markup-shaped）的註解來驗證它維持為靜態文字。

10. 練習匯出：確認列印樣式表、PNG 簽名與尺寸、PPTX 和 DOCX 的 ZIP 簽名與必要的 OOXML 部分，以及當自動下載被抑制時的回退下載連結。視覺確認場景圖中包含一個有界線的證據頁尾，內含狀態、核心基礎與來源定位器或邊界。當原生 Pages 在範圍內時，透過 scripts/serve.mjs 執行，驗證 .pages 包裹中包含 Index/Document.iwa，然後在 Pages 中重新開啟。任何變更後，修正規格或範本並重新執行兩個驗證器。

報告語言

• 預設情況下，最終的 QA、狀態、交接和產生成品報告以使用者最新實質請求的語言撰寫。
• 明確的報告語言請求會覆蓋此預設值。
• spec.language 僅控制產生的解釋器介面，不強制對話報告語言。
• 在多語言對話中，選擇報告語言時忽略簡短的確認訊息。保留程式碼、命令、路徑、識別碼、確切錯誤訊息和來源標題，若翻譯會降低精確度。

請參閱 references/reporting.md 以獲得完整的語言選擇與交付報告合約。

故事建構規則

• 標題需是一個具體的承諾，而非分類標籤。
• 摘要維持一句話，每個節點維持一個職責。
• 偏好 3–5 個場景。僅在省略某個階段會扭曲因果關係時才使用 6–7 個場景。
• 邊緣（edges）是關係或動作。標籤使用簡短的動詞。
• 追蹤必須按照有意義的順序訪問真實的節點 ID。
• 僅在衝擊、可見症狀與回退方案已知時才使用失敗資料。
• 保持簡單層精確，足以讓技術層存活。
• 將限制放在 truthLadder.caveat 中，而非使用小字免責聲明。
• 使用場景或節點支援的來源 ID。
• 不要只因來源與主張相鄰就引用它。

在變更渲染器的視覺語言之前，請參閱 references/story-grammars.md 以取得模式模式、references/evidence-rules.md 以取得主張邊界，以及 references/visual-system.md。在變更持久儲存、導航、播放或匯出行為之前，請參閱 references/library-and-export.md。

品質閘門

工作僅在以下條件成立時才視為準備就緒的本機成品：

• 驗證器對規格和渲染後的 HTML 回傳 ok: true；
• 所有 ID 和引用都解析成功；
• 每個必需的互動區段都有內容；
• 選定的故事模式通過其自身的語意合約；
• HTML 是確定性的，並且包含規格的 SHA-256 中繼標籤；
• 成品位元組與提供的規格匹配，並使用可信的 CSP 雜湊；
• 成品沒有外部資源、不安全的執行時期 API 或遠端字型；
• 持久化的讀者狀態是選擇加入、命名空間化、有界線、同一來源，且保持在確定性規格雜湊之外；
• 註解僅作為文字呈現，無法建立可執行的標記；
• 全域與場景本機播放共享一個狀態機，且永不一起執行；
• 每個追蹤步驟啟動真實的對外關係路徑（或接收端的對內路徑），保持標籤和箭頭狀態一致，並僅突顯支援該步驟的證據；
• 場景證據卡保留 verified/inferred/analogy 邊界，並暴露核心文字加上可操作的定位器，無需獲取遠端預覽；
• 場景 PNG、PPTX 和 DOCX 套件具有預期的簽名和結構，並包含其證據頁尾；聲稱的原生 Pages 匯出也已在 Pages 中重新開啟；
• 行動版使用堆疊流程而非縮小桌面 SVG；
• 最終報告遵循使用者當前的互動語言，列出產生的規格和 HTML 路徑，並說明是否執行了桌面、行動、持久儲存、播放、證據和匯出瀏覽器 QA。

如果證據不完整，僅在證據地圖與警示（caveat）使差距顯而易見時才進行生成。否則請停止並回報缺少的證據。