Plan — Criz HTML Publish

產生於 2026-09-15 15:54 CST

目標：只有明確呼叫 criz-html-publish 時，才將指定 HTML 與其必要 assets 發布到 crizchien/criz-html-docs，再由 Cloudflare Pages 產生公開 production URL。其他文件維持本地。

1. 預計操作的步驟

Phase 1 — 權限與現況盤點

  1. read-only檢查 SSH、gh auth、本機 Repo clone 與 Cloudflare 登入狀態。範圍：local credential state、GitHub、Cloudflare
  2. read-only首次進入各 Repo 時讀取 context、settings 與 hooks。範圍：local repo
  3. approval gate列出 hooks 意圖，由 Criz 決定是否 soft-load；不執行 hook 腳本。範圍：agent behavior

Phase 2 — Repo 與發布契約

  1. read-only檢查 criz-html-docs 現況，確認不覆蓋既有內容。範圍：local repo
  2. state-changing定義 public/<slug>/、documents.json、首頁、版本與下架規則。範圍：local files

Phase 3 — criz-html-publish 實作

  1. state-changing新增發布 skill：接收指定 HTML、解析 title/src/href/srcset、收集相對 assets。範圍：criz-html plugin/repo
  2. state-changing加入敏感資訊、絕對路徑、資產缺失與越界檢查。範圍：local files
  3. state-changing產生 slug 建議、更新 metadata、完整重建首頁。範圍：criz-html-docs working tree

Phase 4 — Exact-repo direct-main 例外

  1. state-changing在高優先級 workflow 規則加入只適用於 github.com/crizchien/criz-html-docs 的例外。範圍：shared agent workflow
  2. read-only驗證 skill identity、remote canonical identity、branch 與 working tree；任一不符即停止。範圍：local git state

Phase 5 — criz-html-docs 初始化

  1. state-changing建立 public/、空 metadata 與「Criz Shared Documents」首頁。範圍：local files
  2. read-only以本機瀏覽器確認純靜態首頁。範圍：local browser
  3. approval gate列出檔案與 diff；經確認後 commit、push。範圍：GitHub repo

Phase 6 — Cloudflare Pages

  1. state-changing建立獨立 Pages project，production branch 設 main，output directory 設 public。範圍：Cloudflare account
  2. user action由 Criz 完成 OAuth、帳號選擇與 GitHub App 授權，僅授權指定 Repo。範圍：GitHub、Cloudflare
  3. read-only確認 production deployment 與首頁 URL。範圍：public web

Phase 7 — 第一份正式文件

  1. user inputCriz 提供一份確定可公開的 HTML + assets 路徑。範圍：local files
  2. read-only驗證 assets、敏感內容與 slug。範圍：local files
  3. approval gate顯示 diff，經確認後 commit、push main。範圍：GitHub、Cloudflare deployment
  4. read-only實際開啟 production，檢查首頁、文件、CSS、圖片、附件及固定 URL 更新。範圍：public web

Phase 8 — Cleanup 與交付

  1. state-changing移除暫存 scaffold，保留正式文件與必要設定。範圍：local files
  2. read-only回報 production URL、觸發方式、發布／更新／下架範例與精確驗證結果。範圍：delivery

2. 會執行或建議執行的指令

# read-only：檢查既有登入，不顯示 token
gh auth status
ssh -T git@github.com

# state-changing：執行前確認
git clone git@github.com:crizchien/criz-html-docs.git

# state-changing：只 stage 明確列出的發布檔案
git add public/<slug>/index.html public/<slug>/<asset> public/index.html public/documents.json
git commit -m "docs: publish <document-title>"
git push origin main

# 不執行
# source <local-credential-file>
# git add .
# git push --force
# git reset --hard

3. 安全性原則與注意事項