Folio
在撰寫 HTML 之前,先閱讀請求與任何現有的作品。每個外部依賴和發佈 URL 都必須記錄在清單中。作品是靜態文件——它們不呼叫 API。
何時使用 folio——以及何時不使用
Folio 是為可持久保存、可開啟、可分享的網頁交付物而設計——使用者會保留、再次開啟或轉交給他人的東西。
在以下情況使用 folio:
- 使用者要求一份文件、儀表板、試算表、簡報或頁面,他們會保存或發送出去
- 輸出是一項交付物,而非快速預覽(「幫我製作一份報告」、「為團隊建立一個儀表板」、「把這個放到網路上」、「我想要一個頁面,可以……」)
- 使用者明確使用了動詞(
folio publish、folio audit、folio remix、folio describe)
在以下情況不要使用 folio:
- 使用者只想要快速預覽,而非交付物(「展示給我看」、「這看起來像什麼」、「只是檢查一下」、「你能顯示嗎」)
- 此對話結束後輸出不會再被開啟——請直接回覆或寫一個暫存檔案,不要蓋章、記錄或設置關卡
- 請求的是程式碼片段、設定檔、單一函式——這些不是瀏覽器作品
進入關卡。 在進入作品流程之前,問:使用者在這次對話結束後還會再次開啟這個檔案嗎? 如果不會,folio 就不是正確的工具——直接回答即可。如果是,則繼續。
獨立是預設值。 最輕量的 folio 路徑是單一資料夾內含一個 index.html——沒有網站根目錄、沒有 site.json、沒有索引頁。只有在有第二個作品或使用者要求發佈集合時,才出現網站根目錄。不要為單一檔案建立網站儀式。
詞彙表
僅在 Folio 輸出中使用這些術語。
| 術語 | 意義 |
|---|---|
| artifact(作品) | 一個自包含的靜態網頁交付物:包含 CSS/JS 的 HTML,可在瀏覽器中執行 |
| bundle(打包方式) | single-file(內嵌 CSS/JS)或 multi-file(同一目錄中連結的資源) |
| artifact kind(作品類型) | 可以是文件(doc)、試算表(sheet)、儀表板(dashboard)、解說頁(explainer)、簡報(slides)、工具(tool)、登陸頁(landing) |
| host profile(主機設定檔) | 網站持久存在的位置:local、surge、gh-pages、cf-pages、cf-worker |
| share(分享/隧道) | 一個臨時的公開 URL,指向正在執行的本地伺服器,透過 localhost.run(預設)或 ngrok。短暫存在,機器仍是主機——不是發佈 |
| site root(網站根目錄) | 一個包含 index.html 和 artifacts/ 樹狀結構的目錄,作為一個網域發佈。作品是其下的路徑,而非獨立的子網域。 |
| site manifest(網站清單) | .folio/site.json——權威的真相來源。包含網域 + 每個作品的註冊資訊(slug、類型、打包方式、清單、來源、發佈狀態)。蓋章、索引和稽核都由此衍生。 |
| standalone artifact(獨立作品) | 沒有網站根目錄的作品。HTML 的戳章是其唯一的清單。當出現第二個作品時,會升級為網站條目。 |
| provenance(來源) | 在混合作品上的 source 欄位:{ slug, site, url }。原創作品為 null。會被 describe、audit 和 remix 讀取。 |
| manifest(清單) | 入口 HTML、檔案列表、外部依賴,以及可選的發佈元資料 |
| ledger(記錄) | 清單記錄——建構前的依賴、資料檔案、URL 和證據等級 |
| gate(關卡) | 在交付前必須通過的二進位檢查 |
| evidence level(證據等級) | 可以是 observed(觀察到)、derived(推導出)、stated(陳述)、absent(不存在) |
如何使用此技能
- 預設:建立或更新一個作品。遵循作品流程。單一作品預設為獨立——不需要網站根目錄。
folio audit <path|url>:唯讀稽核。不要編輯。請參閱references/verbs/audit.md。folio describe <path|url|slug>:讀取作品的清單條目(類型、記錄、來源、發佈狀態)。請參閱references/verbs/describe.md。folio share <site-root>:透過隧道(預設為 localhost.run——無需安裝、無需帳戶;可使用--ngrok替代)為本地執行的網站開啟一個臨時公開連結。機器仍然是主機;URL 會隨著程序終止而失效。用於「讓某人現在就看到」,而不是發佈。請參閱references/verbs/share.md。folio publish <site-root>:將網站根目錄(所有作品)部署到所選的主機設定檔,以進行持久託管。首先重新生成索引(scripts/gen-index.js),然後部署。請參閱references/verbs/publish.md。folio remix <path|url>:複製一個作品並修改它,同時保持清單誠實並記錄來源譜系。請參閱references/verbs/remix.md。
一次執行 = 一個作品,除非使用者指定多個。優先選擇能滿足請求的最小打包方式。單一作品是獨立的;多個作品則位於一個網站根目錄下,並作為一個網域發佈。請參閱 references/site-index.md 以了解網站根目錄模型和從獨立升級到網站的流程。
不可協商的紀律
- 先能執行,再談美觀。 作品必須能在瀏覽器中開啟,且核心互動在進行打磨或發佈之前就已能運作。
- 僅限靜態文件。 沒有對外部 API 的
fetch()、沒有 WebSocket 連接、沒有對即時端點的XMLHttpRequest。數據是內嵌的、透過fetch('./data/…')從本地檔案載入的,或在建構時生成的。作品進行的唯一網路請求是針對已記錄的 CDN 腳本、樣式和字型。 - 清單誠實。 CDN 腳本、字型、圖片和資料檔案都是記錄列,而不是驚喜。
- 本地優先,然後分享,最後發佈。 預設主機設定檔是
local。以動態方式執行——node <folio-skill>/scripts/serve.js <site-root>確保artifacts/資料夾存在、根據記錄重新生成索引/搜尋頁面、選取一個可用埠,並透過 HTTP 提供服務(對於完全內嵌的單一檔案,使用file://是可以接受的,但會破壞fetch和模組匯入)。請參閱references/local-server.md。若要立即展示給某人看,請開啟一個臨時隧道——node <folio-skill>/scripts/share.js <site-root>(預設 localhost.run,無需安裝/帳戶);該連結是短暫的,機器仍然是主機。持久託管是publish——僅在使用者要求或呼叫folio publish時才執行。切勿主動宣傳分享或發佈功能。 - 靜態檔案中沒有機密。 API 金鑰、令牌和私有 URL 不應存在於被提交或發佈的 HTML/JS 中。
- 不要醜。 作品應遵循視覺基準。請在開始建構前參閱
references/visual-baseline.md。
黃金決策軌跡
請求:從這個 CSV 為同事建立一個互動式延遲直方圖。
庫存檢查:
· 目標:新作品 `latency-hist`
· 現有:無
· 數據:使用者附加了 `runs.csv`(觀察到,840 行)
· 限制:本地資料夾,不發佈
選擇:類型=解說頁 · 打包方式=多檔案 · 主機=本地 · 受眾=同事交付
記錄:
dep | 類型 | 證據 | 作品中的位置
d3@7 (cdn.jsdelivr) | 腳本 | 陳述,使用者未指定版本 | index.html 腳本標籤 + README 中的備註
runs.csv | 數據 | 觀察到 | ./data/runs.csv,透過 fetch('./data/runs.csv') 載入
檔案計劃:
建立:artifacts/latency-hist/index.html, style.css, app.js, data/runs.csv, README.md
無刪除。
驗證:npx serve artifacts/latency-hist;圖表渲染;控制台乾淨
關卡:可本地開啟=是 · 控制台乾淨=是 · 記錄完整=是 · 無機密=是 · 模擬已標記=不適用 · 視覺基準=是
交付:路徑、開啟方式、記錄摘要、延遲項目:無
範圍分流
在討論廣泛的設計問題之前,先確定範圍。
| 請求形式 | 打包方式 | 主機 | 跳過 |
|---|---|---|---|
| 快速的一次性展示 | single-file | local | README、發佈、多頁面 |
| 書面文件或報告 | single-file 或 multi-file | local | 圖表、繁重的 JS |
| 數據表格或試算表 | single-file 或 multi-file | local | 敘述性散文、裝飾 |
| 指標儀表板 | multi-file | local | 完整的 CRUD、即時資料饋送 |
| 概念解說頁 | multi-file | local | 密集的原始數據傾倒 |
| 簡報投影片 | multi-file | local | 滾動佈局、小組件 |
| 共享給同事的作品 | multi-file | local | 框架建構步驟 |
| 現在就展示給某人看 | single-file 或 multi-file | share(隧道) | 部署儀式、持久主機 |
| 持久的公開連結 | multi-file | surge 或 cf-pages | 認證、伺服器邏輯 |
| Agent 交付預覽 | single-file 優先 | local | 除非要求,否則不分享/發佈 |
不明確的請求:問一次,簡潔地。例如:「單一自包含檔案,還是一個包含分離 CSS/JS 的小資料夾?」如果未回答,選擇能運作的最小打包方式。
作品流程
0. 庫存檢查
閱讀請求以及任何現有的作品樹。請參閱 references/evidence.md 和 references/artifact-types.md。
收集:
- 主題: 作品應展示什麼或讓使用者能做什麼
- 輸入: 檔案、JSON、CSV、文字、設計限制(附帶證據等級)
- 現有作品: 路徑、入口 HTML、清單、上次發佈 URL(如有)
- 主機設定檔: 預設
local;當發佈在範圍內時,請參閱references/host-profiles.md - 慣例來源: 如果存在,則為
folio.md
在繼續之前,先輸出一個附帶引用的緊湊庫存。
1. 選擇
在進行建構前輸出:Picks: kind=<x> · bundle=<y> · host=<z> · audience=<a>。
當類型不明確時,請參閱 references/artifact-types.md。當主機不是 local 時,請參閱 references/host-profiles.md。
2. 清單記錄
在撰寫 HTML 之前建立記錄。請參閱 references/manifest-ledger.md。
欄位:
dep | kind | evidence | in artifact as
類型:script(腳本)、style(樣式)、font(字型)、image(圖片)、data(數據)、mock(模擬)、publish-target(發佈目標)。
資料檔案和模擬資料必須明確列出。外部 API 呼叫不在範圍內——請參閱紀律 #2。
3. 檔案計劃和建構
在編輯之前聲明檔案計劃:
Create: artifacts/<slug>/index.html, app.js, data/sample.json
Modify: none
No deletes.
從範本開始。 載入 references/templates/<kind>.html 並調整它——將 {{placeholder}} 內容和 <!-- Replace: ... --> 標記替換為真實內容。範本本身就是通過關卡的 folio 作品;它們包含令牌區塊、淺色/深色切換、網站圖示和特定類型的結構。請參閱 references/templates/ 索引以了解每個範本提供的內容。
在撰寫 CSS 之前,請參閱 references/visual-baseline.md。
除非使用者指定了特定的技術堆疊,否則使用純 HTML/CSS/JS 進行建構。偏好:
- 語義化 HTML,一個明顯的入口檔案(
index.html) - CSS 自訂屬性用於所有視覺令牌(顏色、字型、間距、圓角、陰影)
- 顏色使用 OKLCH;不要在
:root令牌區塊之外使用內聯 hex/rgb - 純 JS 或一個已記錄的命名 CDN 函式庫
multi-file:保持所有資源路徑相對;沒有絕對的機器路徑- 無斜體標題;可讀的行寬(
max-width: 60–70ch);在html和body上設定overflow-x: clip
當作品接受使用者輸入、嵌入第三方內容或公開發佈時,請參閱 references/security.md。
戳章(HTML 註解,位於入口檔案頂部):
<!-- Folio · slug: latency-hist · kind: explainer · bundle: multi-file · host: local -->
<!-- deps: d3@7 · data: runs.csv · publish: none -->
對於 single-file,保持戳章最小化(一行)。
4. 驗證
請參閱 references/verification.md。執行適合主機設定檔的檢查。
最小矩陣:
check | command/evidence | result | notes
範例:靜態伺服器 + 載入入口 URL、DevTools 控制台乾淨、點擊主要互動、檢查損毀連結、file:// 與伺服器用於 fetch 的備註、視覺基準抽查。
5. 關卡
在交付前應用。任何 no 都會觸發修正循環。
| 關卡 | 檢查 |
|---|---|
opens-locally | 入口 HTML 透過靜態伺服器載入(或記錄了誠實的 file:// 注意事項);伺服器設定請參閱 references/local-server.md(scripts/serve.js 是單指令路徑) |
console-clean | 主要路徑上沒有未捕獲的錯誤 |
ledger-complete | 每個外部依賴和資料來源都出現在記錄中 |
no-secrets | 原始碼中沒有金鑰、令牌或私有 URL |
mock-labeled | 當真實數據不存在時,模擬/樣本數據已標記 |
static-only | 沒有對外部 API 的 fetch()、沒有 WebSocket、沒有對即時端點的 XHR |
visual-baseline | 令牌區塊存在,:root 之外沒有內聯顏色,無斜體標題,對比度足夠 |
publish-ready | 發佈時:主機設定檔步驟已記錄並驗證,或明確延遲 |
manifest-derivation | 建議性。 HTML 戳章(slug、類型、打包方式)與此作品的 site.json 條目相符。標記漂移;請參閱 references/verification.md#manifest-derivation-check。 |
建構後請參閱 references/slop-test.md。在交付前修復 P0/P1。
6. 發佈(可選)
僅在使用者要求發佈或呼叫 folio publish 時執行。請參閱 references/verbs/publish.md 和主機設定檔的詳細文件。
將發佈 URL 記錄在清單和交付摘要中。未經發佈命令輸出的證據,切勿聲稱 URL。
7. 交付
包含:
- 作品路徑和入口檔案
- 如何在本地開啟(確切指令)
- 發佈 URL(如果已發佈),附帶證據
- 清單記錄摘要
- 驗證指令和結果
- 延遲項目(例如,
fetch需要伺服器、正在使用模擬數據)
不要將清單或發佈事實埋沒在實作細節之下。
錯誤/良好對比
錯誤: 因為儀表板通常從 API 載入使用者,所以寫入 fetch('/api/users')。
良好: 嵌入 data/users.json 並帶有可見的「樣本數據」標籤。沒有 API 呼叫。
錯誤: 貼上 Google Analytics、字型和三個 CDN 函式庫而不列出它們。 良好: 每個依賴都是一個記錄列,包含 URL 和用途。
錯誤: 沒有執行發佈命令就說「已部署在 https://demo.example.com」。 良好: 從命令輸出複製發佈 URL,或標記為延遲。
錯誤: oklch() 值散落在 CSS 各處,三個不同的 font-family 宣告。
良好: 所有視覺值都在 :root 令牌區塊中,透過 var() 引用。
慣例作品
folio.md(輸出目錄、預設主機、CDN 允許清單、命名):選擇性加入。請參閱 references/folio-md.md。一旦存在,專案預設值將獲勝。
可選的每個專案佈局:
…