EpoCanvas 工程標準總綱：指標定義、資料鏈路與核驗邊界

完整說明 EpoCanvas 的指標、內容撰寫、文件生命週期、版本、服務邊界與需要獨立驗證的工程品質。

版本 v2.7.1 发表于 10/17/26 更新于 10/20/26

EpoCanvas 工程標準總綱

EES-001 規則說明 非即時審計報告

本規範說明站點指標如何定義、資料從哪裡來、哪些結論能夠直接計算，以及哪些結論仍需測試。指標應幫助讀者理解站點，而不是用漂亮的數字替代證據。

[!IMPORTANT] 本文是規則文件，不是一份即時監控報告。 文中閾值依據當前原始碼配置；當前篇數、字數和等級應檢視對應部署的指標介面，並同時檢查資料生成時間。

1. 標準的目標與適用範圍

EpoCanvas Engineering Standards（簡稱 EES）是本站對內容指標、資料鏈路及其對外解釋方式的專案級工程約定。

它主要回答三個核心問題：

  1. 站點近期是否在持續穩定地釋出或維護公開技術內容？
  2. 已公開文章的平均物理篇幅處於什麼區間，呈現怎樣的體量分佈？
  3. 所有對外展示的統計數值與等級，能否根據明確的輸入、演算法與時間條件被完整獨立復算？

EES 拒絕把多維度的複雜工程質量壓縮為一個單一的分數。發文數量、文章篇幅、頁面效能、服務可用性和認證安全分別屬於完全不同的工程領域，必須由不同型別的真實證據進行獨立支撐。

例如：

  • 近 30 天內沒有釋出新文章，只代表釋出視窗計數為零，絕不代表全站評論系統、邊緣函式或部署鏈路發生故障；
  • 全站平均篇幅較長，只代表文本規模達到特定字元區間，絕不自動證明每篇文章都具備高質量、原創性、邏輯嚴密性或易讀性；
  • 服務端響應正常，只能證明 API 路由處理邏輯可執行，不能反向證明歷史快照中的統計規則已經消除所有邊界差異。

1.1 文件體系結構

EES 規範體系由一個總綱與六個專項子規範構成，各文件分工如下：

規範編號規範領域核心職責與系統邊界權威資料來源
EES-001工程標準總綱頂層指標體系組織、資料鏈路流向、核驗邊界與一致性原則src/config/standards.ts
EES-002活躍等級模型近 30 天滑動視窗釋出頻次計算、五級離散閾值與時間邊界部落格文章集合與時序釋出流
EES-003內容密度模型正文字數精算演算法、全站平均篇幅、四級閾值與閱讀耗時文章純文本內容長度特徵
EES-004版本協議規範語義化版本控制、不可變 Git SHA 追溯、架構分層與授權邊界Git 倉庫提交元資訊與環境變數
EES-005系統狀態與服務邊界靜態建置、邊緣函式、資料儲存、支付/通知邊界、失敗模式與證據等級docs/standards/status.md、functions/ 與部署設定
EES-006文件生命週期官方文件權威層級、狀態機、版本、審閱、棄用與歸檔docs/standards/document-lifecycle.md、Git 提交與文件入口
EES-007內容撰寫規範Markdown/MDX、front matter、連結、程式碼、敏感資料與可及性要求docs/standards/content-authoring.md、src/content.config.ts

當前配置檔案標識與基線版本：

配置專案原始碼對映 / 當前取值說明與約束
標準標識EES-2026.4當前執行的標準代號
配置版本2.6.0配置檔案中宣告的版本標識
核心配置檔案src/config/standards.ts閾值、狀態碼、文案與顏色權威源
站點執行起點2024-01-01用於計算累計執行天數的固定基準點

配置版本不等於部署版本。複核系統狀態時，應同時記錄當前 Git 提交的 Commit Hash、建置輸出與 Cloudflare Pages 部署識別。

1.2 規範用語約定

本文件遵循嚴格的技術規範表達約定：

  • 必須 (MUST)：表示在生成資料、輸出指標或釋出內容前必須嚴格滿足的硬性約束；
  • 應當 (SHOULD)：表示工程上的推薦最佳實踐，偏離此做法時必須給出明確的技術解釋與上下文；
  • 可以 (MAY)：表示可選功能或未來擴充套件能力；
  • 當前實現 (SOURCE-VERIFIED)：表示已從當前提交版本的原始碼中確認的實際行為；
  • 已知差異 (KNOWN-GAP)：表示已經確認存在但尚未在程式碼中徹底統合的雙軌邏輯差異；
  • 建議方向 (PROPOSED)：表示處於設計或遷移規劃中、尚未實際落地的改進方案。

2. 證據基線與技術宣告分類協議

為杜絕技術文件中常見的過度宣稱與虛假修飾，EES 體系建立嚴格的宣告分類協議。所有面向讀者的技術結論必須能夠歸入以下可驗證類別之一：

標識程式碼分類名稱定義與含義可接受的證據支撐
SOURCE-VERIFIED原始碼已核驗行為已從倉庫現有原始碼中得到確認具體檔案路徑、函式名、分支條件程式碼與 Git 提交 Hash
TEST-VERIFIED測試已核驗邏輯已通過實際執行自動化測試驗證明確的執行命令、程序退出碼 0、具體斷言項與測試日誌
LIVE-VERIFIED線上已核驗功能已在生產線上環境完成端到端驗證生產域名、實測時刻、網路請求抓包或真實瀏覽器渲染證據
KNOWN-GAP已知差異項雙側或歷史遺留實現之間存在已記錄的分歧兩側程式碼實現差異對比、影響範圍與可復現用例
PROPOSED建議演進項經過架構設計的擬定方案，尚未正式合併詳細介面設計說明、預期收益、風險評估與遷移前置條件
BLOCKED外部阻塞項因外部環境、憑證或許可權不足而無法完成具體阻塞原因、依賴的外部團隊或鑑權邊界說明

禁止將僅在原始碼中存在的邏輯描述為已在線上環境驗證（嚴禁將 SOURCE-VERIFIED 混淆為 LIVE-VERIFIED）。

3. 從整體理解指標體系

# EpoCanvas 指標體系
## 內容輸入層
- Markdown 與 MDX 檔案
- Frontmatter 後設資料
- 草稿與訪問控制屬性
- 多語言對映鍵 i18nKey
## 釋出活躍度 (EES-002)
- 近 30 天滑動視窗發文數
- 五級階梯 Lv.0 至 Lv.4
- 僅計首發不計舊文修訂
## 內容篇幅 (EES-003)
- 正文字元與分詞估算
- 全站算術平均篇幅
- 四級階梯 Lv.1 至 Lv.4
- 篇幅不等於質量評分
## 資料鏈路層
- Astro 靜態集合構建
- 快照生成指令碼 sync-metrics
- 邊緣 API 請求期動態校準
- 邊緣 HTTP 快取策略
## 獨立工程核驗
- 真實瀏覽器端到端測試
- 服務可用性與 API 行為觀測（需附時間與環境證據）
- 訪問控制與資料安全審計
- 移動端與無障礙適配

思維導圖呈現系統概念結構。具體判定必須以下文詳述的規則與實際執行程式碼為準，不能從導圖節點直接推導額外的未實現特性。

4. 核心指標字典

EES 規範所涉及的核心指標欄位、資料型別、計量單位與工程含義定義如下：

指標名稱資料模型欄位單位核心工程定義與計算口徑
公開文章總量stats.posts篇當前資料來源中經過去重與過濾後納入統計的代表性公開文章數量
全站估算總字數stats.totalWords字納入統計的全部公開文章通過字數估算演算法得到的分值之和
全站平均篇幅stats.avgWordsPerPost字/篇全站總字數除以公開文章總量後四捨五入（Math.round）所得的算術平均值
預計總閱讀時間stats.readingMinutes分鐘逐篇文章按估算字數除以閱讀速率並向上/取整後的閱讀分鐘數直接累加值
近 30 天發文量stats.recentPostCount30d篇釋出日期（pubDate）落入計算時刻往前滑動 30 天視窗內的文章總數
活躍等級stats.activeLevel等級由近 30 天發文量匹配 activityLevels 階梯表所得的評級物件
內容密度等級stats.densityLevel等級由全站平均篇幅匹配 contentDensityLevels 階梯表所得的評級物件
累計執行天數stats.uptimeDays天從固定起始錨點 2024-01-01T00:00:00Z 到計算時刻之間經過的完整日曆日數
52 周動態熱力圖activity格子陣列包含 364 個日曆格子的矩陣，記錄首次釋出與有效更新事件的日期分佈
快照生成時刻generatedAtISO-8601構建指令碼掃描文章正文生成 JSON 資料資產的具體時間戳
介面處理時刻servedAtISO-8601邊緣函式接收到 HTTP 請求並完成部分欄位重算的時間戳

4.1 “累計執行天數”的技術邊界澄清

在當前實現中，stats.uptimeDays 由以下程式碼計算：

const START_DATE = '2024-01-01T00:00:00Z';
const uptimeDays = Math.floor(
  (now.getTime() - new Date(START_DATE).getTime()) / (1000 * 60 * 60 * 24)
);

這是一個以固定日期為起點的站點存在時間計數器（Site Age Indicator），絕不是基於高可用叢集探針、心跳監測或 SLA 統計的“零故障無中斷執行時長”。

因此，在對外展示與工程文件中：

  • 不能將執行天數解釋為站點期間從未發生過任何宕機、崩潰或網路中斷；
  • 不能將該數值替代真實的 HTTP 存活探針或雲廠商 SLA 監控報表；
  • 介面展示建議採用“建站天數”或“累計執行天數”，避免產生誤導。

5. 資料實際如何流動：三條並行鏈路

本站指標並不存在“每次客戶端請求都即時查詢 Cloudflare D1 資料庫並全文掃描 Markdown”的邏輯。全站資料通過三條職責明確的鏈路流轉：

【鏈路一：靜態頁面構建鏈路 (SSG Build Pipeline)】
src/content/posts/*.{md,mdx}
  │
  ▼ getCollection('posts')
Astro 內容集合框架
  │
  ▼ getPublicPosts()
排除草稿、排除 access 限制、依據 i18nKey 進行多語言歸組
  │
  ▼ calculateSiteMetrics()
記憶體計算全站總字數、平均字數、近期發文與等級階梯
  │
  ▼ standards/ 頁面靜態渲染
注入頁面初始 HTML（構建時刻的確定性靜態映象）

【鏈路二：構建期快照同步鏈路 (Snapshot Pipeline)】
src/content/posts/*.{md,mdx}
  │
  ▼ scripts/sync-console-metrics.mjs
提取 Frontmatter、正則預清理正文、計算字數與 52 周熱力圖
  │
  ▼ 生成靜態資產
public/data/console-metrics.json（隨靜態資產部署至目標 Pages/CDN 資產層）

【鏈路三：邊緣 API 請求期動態校準鏈路 (Edge Runtime Pipeline)】
客戶端發起 GET /api/console/data
  │
  ▼ Cloudflare Pages Functions
優先從 ASSETS 快取讀取 console-metrics.json 快照
  │
  ▼ 基於當前請求時刻 (now) 重新校準：
  - 累計執行天數 uptimeDays
  - 近 30 天滑動視窗發文數 recentPostCount30d
  - 動態重評 activeLevel 等級與進度條
  - 基於當前日期重新投影 52 周（364 天）熱力圖格子
  │
  ▼ 輸出 HTTP JSON 響應
附帶響應頭 Cache-Control: public, max-age=60, s-maxage=300

[!NOTE] “在邊緣函式中執行”描述的是程式碼執行的物理網路節點，不代表“每一次網路請求都會在邊緣節點上重新將幾百篇 Markdown 正文重算一遍”。 當前架構的標準技術定性是：構建期靜態快照驅動，疊加邊緣請求期時間相關欄位動態校準。

6. 兩個核心等級維度的正交性

活躍等級衡量的是“釋出的時間頻度”。它只以滾動時間視窗內的公開發表文章數量為依據，反映的是作者近期的創作節奏。它不衡量單篇文章的篇幅厚度，不衡量歷史修改頻度，更不代表服務架構的可用性健康度。

內容密度衡量的是“文章的平均篇幅規模”。它以全站全部入選公開文章的算術平均字元數與詞數估算為依據，反映的是全站技術沉澱的篇幅結構。它不代表單篇文章的語義含金量，也不是技術正確性或學術價值的自動認證。

6.1 活躍等級對照速查

等級標識狀態程式碼徽章顯示近 30 天發文量官方命名創作節奏參考描述
Lv.0Status 0Lv.0 Idle0 篇維護休眠視窗內無新文章，處於常規歸檔或底層休整期
Lv.1Status 1Lv.1 Low1–2 篇週期推送保持每月 1 至 2 篇的基礎技術分享節奏
Lv.2Status 2Lv.2 Standard3–4 篇穩定維護保持雙週更或每週一篇的穩定知識沉澱節奏
Lv.3Status 3Lv.3 High5–8 篇高頻迭代保持高密度周更或多專題並行推進
Lv.4Status 4Lv.4 Ultra至少 9 篇極客狂熱保持極高頻技術輸出與系列專欄集中交付

“維護休眠”是針對釋出時間視窗的狀態標記，絕不等於站點已廢棄或維護團隊停止工作。

6.2 內容密度等級對照速查

等級標識狀態程式碼徽章顯示四捨五入後平均篇幅官方命名篇幅結構技術特徵
Lv.1Level 1 (Low)Lv.1 Low0–800 字微動態速記簡明備忘、單點故障修復記錄、短小快速片段
Lv.2Level 2 (Standard)Lv.2 Standard801–1500 字標準技術部落格完整敘事的單點專題、標準架構元件解析
Lv.3Level 3 (High)Lv.3 High1501–3000 字詳實系統專欄包含多模組聯動、配置演練與程式碼實現的深度文章
Lv.4Level 4 (Ultra)Lv.4 Ultra至少 3001 字硬核深度長文體系化全景長文、全鏈路原始碼剖析或重構復盤

所有等級命名均屬於本站內部的篇幅結構分類，不構成外部機構的技術認證。

7. 統計准入與多語言去重準則

在頁面側計算與公共資料流中，文章是否能參與統計遵循嚴格的過濾流水線：

全部文章集合 (All Posts)
  │
  ├── 1. 過濾 draft === true 的草稿 ────────────► 排除草稿
  │
  ├── 2. 過濾包含 access 屬性的加密/受限文章 ───► 排除受限內容
  │
  └── 3. 多語言版本歸組與去重 (Canonical Grouping)
        │
        ├── 提取分組鍵：優先使用 frontmatter.i18nKey
        │   未配置時回退為：移除已識別語言字尾後的 slug 標識
        │
        └── 同一組別存在多個版本時：
            優先選擇無語言字尾的根版本作為唯一的代表性文章；
            無根版本時，選擇按字母序排列的第一個可用版本。

7.1 去重機制不是語義防刷模型

當前的去重與防刷邏輯依賴於顯式的 Frontmatter 後設資料與檔名規範。以下行為無法通過當前演算法自動識別：

  • 正文高度相似但使用完全不同檔名與不同 i18nKey 的文章；
  • 將一個完整技術主題人為拆解為十篇幾百字的碎片文章以刷取發文篇數；
  • 故意篡改 pubDate 為近期日期；
  • 將純外鏈引用包裝為長文。

因此，當前系統提供的是多語言釋出副本與草稿的工程級歸一化，不能聲稱具備自然語言語義分析級的全自動防刷能力。

7.2 已識別的程式碼與架構差異詳錄 (Identified Consistency Gaps)

在對當前倉庫原始碼的完整審計中，確認存在以下雙軌實現差異。在未完成程式碼級統合前，公開文件應如實解釋其技術邊界：

差異編號差異簡述影響範圍與表現推薦統一方向 (PROPOSED)
GAP-01頁面側與快照指令碼的 access 過濾不一致頁面側完全排除 access 文章；快照指令碼未排除，受限文章的標題和日期可能進入公共快照快照指令碼引入與 getPublicPosts() 嚴格一致的過濾邏輯
GAP-02多語言分組鍵實現差異頁面側優先支援顯式 i18nKey；快照指令碼主要依據檔名規則，存在多語言文章在快照中未歸組的風險提取通用的 getCanonicalGroupKey() 共享純函式
GAP-03時間視窗下界計算存在 720h 與零點差異核心指標按前推 30 天當日零點計算；活躍文章明細按嚴格 30 * 24h 計算，導致明細行數與指標偶發不一致統一以自然日零點或嚴格毫秒數為唯一判定標準
GAP-04快照資料丟失具體時分秒精度快照中的釋出日期被截斷為 YYYY-MM-DD 字串，同一日內的先後順序與時間戳精度丟失快照保留完整的 ISO-8601 時間戳字串
GAP-05站點起始日期多處硬編碼並存src/config/standards.ts 定義了起始日期，但部分模組仍存在獨立的區域性硬編碼常量全量引用配置檔案中的統一常量匯出
GAP-06等級升級閾值硬編碼於計算函式中進度條百分比與下一等級提示直接硬編碼了數字，修改配置表無法完全自動聯動重構進度計算器，直接消費配置陣列中的區間範圍

8. 熱力圖的構造原理與解釋限制

全站 52 周動態熱力圖由 364 個日曆格組成，具有固定的排列與著色規則：

52 列 × 7 行 矩陣佈局
行：星期日 (Row 0) 至 星期六 (Row 6)
列：從 52 周前對應的週日至當前周

8.1 事件提取與色階對映

熱力圖記錄兩類有明確後設資料支撐的內容事件：

  1. 首次釋出事件：基於文章的 pubDate 記錄；
  2. 有效修訂事件：當文章存在 updatedDate 且其年月日與 pubDate 不相同時，作為獨立修訂事件記錄。

單日事件數量到顯示色階的對映關係：

當日事件數 EE對應色階介面視覺表現
E=0E = 00 階基礎底色（灰色/低透明度）
E=1E = 11 階淺度主題色
2≤E≤32 \le E \le 32 階中度主題色
4≤E≤64 \le E \le 63 階深度主題色
E≥7E \ge 74 階高飽和高亮主題色

8.2 關鍵解釋邊界

  • 修訂不增加近期發文量：更新舊文章可以在熱力圖中點亮特定日期的格子，但絕不會增加 recentPostCount30d；
  • 歷史修訂覆蓋性：文章模型僅保留單一最新的 updatedDate，若一篇文章修改過十次，也只能體現最初發布日與最後更新日兩個點，無法還原完整的版本控制歷史；
  • 未來佔位格：當前周尚未到來的剩餘天數屬於佔位格子，不顯示任何活動。

9. API 閱讀與資料新鮮度核驗準則

在通過 HTTP 請求讀取 /api/console/data 時，讀者與開發者應遵循嚴格的資料新鮮度驗證流程：

1. 校驗 HTTP 狀態碼為 200，Content-Type 為 application/json；
2. 確認 JSON 頂層 ok 欄位為 true；
3. 檢查 generatedAt 時間戳（明確靜態資料快照的構建時刻）；
4. 檢查 servedAt 時間戳（明確當前邊緣節點的響應時刻）；
5. 明確哪些欄位是請求期重算的（uptimeDays, recentPostCount30d, activeLevel, activity）；
6. 明確哪些欄位是快照固化的（totalPosts, totalWords, avgWordsPerPost, densityLevel）。

9.1 快取策略與失效機制

當前 API 聲明瞭邊緣網路快取：

Cache-Control: public, max-age=60, s-maxage=300

這意味著：

  • 瀏覽器本地可在 60 秒內複用快取；
  • 共享快取可能依 s-maxage=300 在最多 300 秒內複用回應；實際命中、失效與重新驗證仍需在目標環境觀測；
  • 即使釋出了新的文章並完成了部署，在共享快取視窗（最長 5 分鐘）完全失效之前，仍可能獲取到上一週期的回應體；
  • 遇到網路異常或返回非 JSON 響應時，前端介面應當明確展示“資料暫時不可用”，絕不能將異常靜默回退為“0 篇文章”或“Lv.0”，避免向讀者傳遞虛假的歸零資訊。

10. 內容指標不承擔的工程承諾

效能指標必須基於真實環境測試證據

邊緣函式的首包時間（TTFB）、頁面最大內容繪製（LCP）、首屏 JavaScript 資源體積等效能引數，必須在明確的終端裝置、網路頻寬、快取冷熱狀態與取樣批次下由專業工具測定。指標總綱與分級等級不代表任何絕對效能承諾。

靜態架構不自動等同於絕對安全

雖然靜態頁面本身不包含傳統的服務端 SQL 注入面，但站點的互動式功能（如評論系統、支付鏈路、中控臺認證介面等）依然需要嚴格進行輸入清洗、鑑權校驗與防刷攔截。不能將“靜態生成架構”推論為“全站絕對無安全風險”。

字數與篇幅不代表文章質量與實用價值

技術寫作的核心價值在於問題定位的精準度、解決方案的可復現性與架構演進的思考深度。一篇簡明精準的 300 字 Bug 修復記錄，其工程價值完全可能高於一篇堆砌無意義程式碼段的 5000 字長文。篇幅分級僅作為讀者預估閱讀耗時的參考。

11. 資料契約與介面序列化規範

邊緣 API 介面（GET /api/console/data）與靜態快照（console-metrics.json）遵循嚴格的資料模式契約與欄位不變性約束。各消費端（前端中控臺、指標儀表盤、規範頁面）必須基於以下權威 Schema 進行型別對映：

export interface ConsoleMetricsPayload {
  ok: boolean;
  generatedAt: string; // ISO-8601 快照生成時刻
  servedAt?: string;    // ISO-8601 邊緣請求處理時刻
  stats: {
    posts: number;              // 公開有效文章數 (>= 0)
    totalWords: number;         // 全站估算總字數 (>= 0)
    avgWordsPerPost: number;    // 取整後的平均字數
    readingMinutes: number;     // 逐篇累加總閱讀耗時 (分鐘)
    recentPostCount30d: number; // 滑動視窗發文量 (>= 0)
    uptimeDays: number;         // 站點累計執行日數
    activeLevel: ActivityTier;  // 活躍等級完整物件
    densityLevel: DensityTier;  // 內容密度等級完整物件
  };
  standardsConfig: {
    specId: string;             // 如 "EES-2026.4"
    version: string;            // 如 "2.6.0"
    siteStartDate: string;      // 固定基準起點
    activityLevels: ActivityLevelConfig[];
    contentDensityLevels: ContentDensityLevelConfig[];
  };
  activity: Array<{
    date: string;               // "YYYY-MM-DD"
    count: number;              // 當日聚合事件數
    level: 0 | 1 | 2 | 3 | 4;   // 5 級量化色階
  }>;
}

11.1 欄位不變性與邊緣計算約束

  1. 型別檢查：消費端應確認數值欄位是可用的非負整數或浮點數；發生錯誤時，先依 ok 與 HTTP 狀態判斷，不能把缺失欄位靜默當成零；
  2. 時間戳限制：servedAt 是函式處理請求的時間，generatedAt 是快照生成時間。目前程式碼沒有宣告或強制兩者的單調關係，不能僅憑欄位名稱推定部署或系統時鐘一定正確；
  3. 負載體積檢查：activity 目前由程式產生 364 個日曆格，但 JSON 的實際大小會受文章標題、連結與部署資產影響。32 KB、6 KB 或固定執行時間都必須透過指定產物與環境重新測量，不能當成現行保證；
  4. 相容性方向（PROPOSED）：未來若新增欄位，應優先採取增量新增並保留既有核心欄位；這是演進原則，不代表所有歷史客戶端已獲得永久相容承諾。

12. 公開核驗清單

用於對本站當前部署狀態進行公開復核的標準化清單：

  • 已記錄當前核驗的 Git 提交 Hash 與生產部署版本標識；
  • 已拉取當前已釋出的全部 Markdown/MDX 原文，確認草稿與受限文章已剔除；
  • 已核驗多語言文章的分組鍵及代表性版本的選擇結果；
  • 已在固定的時間點基準下復算近 30 天滑動視窗發文數；
  • 已逐篇執行字數估算演算法並計算算術平均值與取整等級；
  • 已核查 /api/console/data 的 generatedAt、servedAt 與 HTTP 快取頭；
  • 已核實受限訪問文章的後設資料沒有意外洩露至公共快照產物中；
  • 已確認所有對外展示文案與當前程式碼實際邏輯嚴格吻合。