Repository navigation
Releases
Foliohaven 1.1.0
2026-11-09（Asia/Taipei）
Foliohaven 1.1.0 統一系統識別、改善驗證與 Docker 工具鏈，並提供作者與 AI Agent 共用的品質及 SEO 指南。既有文章、頁面、SEO 與媒體功能延續原有契約。
識別命名與舊版相容
- 新專案使用
.foliohaven/；只有.alfred/的既有專案繼續沿用舊根，不必搬移。兩者同時存在時只使用.foliohaven/，舊根不讀寫、不合併、不刪除；選定根不合法或資料損壞時報錯，不回退另一套資料。工作執行中偵測到根目錄切換會停止，保留既有紀錄。 - 呈現資料、輸出位置、快照雜湊及容器版本的環境變數改用
FOLIOHAVEN_*，本機服務標頭改用x-foliohaven-*，保留對應舊名稱的讀取。這些環境變數的新名稱存在即優先，包含空字串；新值不合法不回退舊值。新舊標頭衝突或同名重複會拒絕，保留原驗證與來源檢查。 - Cloudflare 新操作使用
foliohaven deploy <UUID>／foliohaven restore <UUID>及foliohaven-*R2 metadata，仍辨識完整舊格式。雙組 metadata 必須完整一致，不混搭或回退掩蓋壞資料；既有物件不因改名批次重傳。舊部署紀錄、備份與指紋維持原樣，受控還原保留備份的原始 metadata。 - 編譯快取、工作紀錄、Docker 啟動與公開來源排除沿用同一套私有根選擇規則；兩種私有根及實際部署設定不進來源包或公開網站。
驗證與 Docker
- 新增
pnpm verify:quick：在隔離副本完成格式、lint、型別、完整單元、必要整合及兩個 Chromium 操作案例，供日常修改使用，不更新目前網站。quick 成功不等於完整pnpm verify或正式發行資格。 - 完整
pnpm verify保留全部整合與三瀏覽器測試，先處理品質及固定埠案例，再使用獨立副本分片執行。依 CPU、Linux 實際剩餘記憶體與 cgroup 限額控制併行，預設最多兩組重工作；不把 swap 算成可用記憶體，也不以放寬 timeout 或增加重試換取通過。報告保存在選定私有根的reports/verification/。 - 日常 GitHub Check 與手動完整發行驗收分開。正式發布仍要求最終公開來源、版本、檔案權限、工具鏈及同次完整驗收證據一致，不能沿用 quick、舊成功或其他來源。
- Docker 在建立相依套件及瀏覽器前對齊 UID／GID，避免晚期遞迴修改整個檔案樹的擁有者；保留非 root、離線啟動與資料保存流程。CI 重用固定的工具鏈層，不將作者私有資料或成功網站放入快取。
共通開發與 SEO 指南
- 新增網站開發與品質標準，集中說明媒體載入、布局穩定、語意、可及性、閱讀互動、代表頁及交付紀錄。PageSpeed 分數為另行手動量測的開發目標，不是 Build、verify 或 CI 自動評分項目，也不代表隨附網站已達標。
- 新增SEO 設定與繼承，集中說明原有的逐欄繼承、摘要與描述、分享圖、覆寫與恢復操作，區分 Studio 設定提示、正式輸出及人工確認。README、AGENTS 與任務文件連到同一份指南，來源包收錄兩份完整文件。
升級與回復
本版沒有文章或網站設定資料模型轉換。由 1.0.0 升級時，先依版本更新與備份保留自己的程式、文章、媒體、私有根、成功網站及部署設定，再在副本驗證。不要為了新名稱自行建立第二套私有根；若 .env 設有 RELEASE_VERSION，更新為 1.1.0，並依新版 Dockerfile 重建 image、保留自己的 UID／GID。
相容方向為新版讀取舊資料及識別。降版須還原配對的程式與完整備份，不能只切回舊程式或手工改寫 journal、快照及遠端歸屬標記；雲端發布與還原仍需明確操作及驗證。
下載與使用入口
下載後先校驗 SHA256 並解壓到新目錄。原生 Linux 與 Docker 維持同一套使用流程；公開網站仍只交付完整 dist/，不需要 Studio、管理 API、資料庫或 Node.js 服務。
Foliohaven 1.0.0
Foliohaven 1.0.0 是首個正式版本，提供可直接修改原始碼的靜態網站與部落格系統。你可以自行或透過 AI Agent 製作首頁、About、FAQ 等固定頁面與共用文章版型，再用 Studio 或 IDE 管理文章、圖片、影片與網站設定。新增文章只需 HTML 正文與 JSON 資料，不必逐篇建立 React 或 Astro 元件。
本版完整收錄預覽階段已具備的系統能力。v0.x.x 定位為預覽版本，既有公開預覽版的來源與附件繼續保留；第一次使用請從本版與下列指南開始。
完整功能
- 固定頁面與共用版型：React 製作主要頁面與展示元件，Astro 產生完整 HTML；可調整字型、排版、導覽、Header／Footer，文章共用一套版型。
- Studio 與 IDE 工作流程：管理文章、草稿、發布與更新時間、分類、Tag、精選圖片、網站設定與媒體；支援桌機／平板／手機文章預覽。也能切換 IDE 模式，由編輯器或 AI 修改來源。
- 文章與內容組織：HTML 正文、JSON 屬性、獨立摘要、目錄、分頁、可排序的延伸閱讀，以及首頁精選文章設定；提供分類／Tag 總覽與個別頁面。
- 搜尋與 SEO：關鍵字正規化與空格分詞、分類／Tag 組合篩選及 URL 狀態；提供逐欄 SEO 繼承、Meta／OG 分享資訊、canonical、索引設定、RSS、Sitemap 與完整網站圖示。
- 圖片與影片：媒體庫管理、圖片尺寸選擇、替代文字、影片封面與處理流程，支援安全的 SVG／ICO、1200×630 分享圖與裁切／留白。
- 保存、預覽與建置：來源驗證、版本、衝突與復原機制；完整建置通過內容、HTML、SEO、路由、連結與資源檢查後才更新成功網站，失敗保留上次成功產物。
- Cloudflare 選用部署：提供 Workers Static Assets＋R2 發布、dry-run、狀態查詢、覆寫備份、受控還原與正式網址驗證，支援大影片及 Range。
- 完整可修改來源：隨附 Dockerfile／Compose、選用的 Dev Container、AI Agent 指引、使用文件、單元／整合／三瀏覽器測試，以及一個中性首頁與五篇教學文章。
下載與啟動
請下載同一版本的兩個正式附件：
完成 SHA256 校驗並解壓到新目錄，再選擇 Docker 或自行配置原生 Linux。詳細校驗與解壓步驟見版本取得與打包指南；來源包包含完整程式、範例、文件與測試。
Docker：主機備妥 Docker 與 Compose，在專案根目錄執行：
docker compose up -d --build --wait --wait-timeout 600首次會在本機建置 image 並準備工具與依賴；沒有預設的外部 image registry。Linux 使用者的 UID／GID 如非1000，先依 README 設定 .env。不需要 VS Code 或特定 AI 服務。
原生 Linux：使用 Node.js 26.12.1、pnpm 12.15.0，並依 README 準備 FFmpeg／ffprobe、編譯工具與 Playwright。原生方式與 Docker 使用同一套來源、操作及檢查；其他主機系統建議使用 Docker。
| 網址 | 用途 |
|---|---|
http://localhost:5173/ |
Studio：文章、媒體與網站設定 |
http://localhost:4321/ |
目前保存內容與程式的來源預覽 |
http://localhost:4322/ |
最近一次成功建立的完整網站 |
第一次架站的順序
- 依 README 完成環境安裝並開啟範例。
- 修改首頁，建立 About、FAQ 等固定頁面，再決定所有文章共用的版型與樣式。
- 在 Studio「全站設定」填寫網站、作者、導覽、圖示及正式網站網址；範例設定可替換。
- 使用 Studio 或 IDE／AI 新增文章、整理分類與 Tag、上傳媒體及設定 SEO。透過 IDE／AI 修改資料前先切換 IDE 模式。
- 在4321檢查來源預覽；執行 Studio「更新網站」成功後，再到4322檢查完整產物。
- 交付完整
dist/至靜態網站服務。使用 Cloudflare 時，依部署指南填妥自己的設定、建立 R2 bucket，並完成首次網域分流；日常以pnpm deploy:cloudflare發布更新。
公開網站只需靜態檔案，不需要資料庫、Studio、管理 API 或 Node.js 服務。保存文章、更新本機網站與部署到公開網址是不同操作。
原始碼與 AI Agent 使用
固定頁面、文章共用版型與 Studio 未涵蓋的修改，都可以直接編輯原始碼，再重新檢查與建置。文章內容與網站設定以檔案保存，方便自行備份及版本管理。
使用 AI Agent 時，請先讓它閱讀 AGENTS.md 與 README，再描述要修改的頁面、樣式或內容。人與 AI 使用相同檔案與規則，不要求特定 AI 平台；測試與隔離 fixture 也隨來源提供。
使用範圍與授權
- Studio 是單人本機管理工具，同一工作區只啟動一組作者服務；公開部署僅交付
dist/。 - 首頁、固定頁與共用文章版型以原始碼客製；日常文章及網站設定可透過 Studio 管理。
- Cloudflare 為選用部署方式，帳號、憑證、R2 bucket 與首次網域設定由使用者準備。上傳成功後仍需核對正式網址。
- 網站圖示與 Manifest 支援不包含 Service Worker 或離線 PWA 能力。
- 自有程式、文件與示範內容採 MIT License；第三方資源維持各自授權。使用者自己的獨立文章與素材可自行決定授權。
從預覽版升級
本次從0.3.1升至1.0.0沒有功能行為、依賴或資料格式變更。既有文章、媒體、網站設定、自訂版型及 Cloudflare 設定可沿用；請先備份完整專案，在副本整合版本差異並驗證，再採用新版。若 .env 有 RELEASE_VERSION，需改為 1.0.0。
從更早的預覽版升級，請同時閱讀版本更新與備份中的歷史相容性說明，不能用新版本範例覆蓋自己的網站。
文件與問題回報
Foliohaven 0.3.1
- 整理操作文件與來源包說明，更新版本取得、解壓及打包範例。
- SVG 驗證測試改用中性示例文字，保留既有 XML、格式安全與圖片輸出檢查。