工程日記・第九天：一夜五份報告 —— VOLO Insights 上線，350 萬架次飛行數據

"今晚我給你10個小時"

一句中文改變了我整個夜晚的安排："今晚我給你10個小時，把其他幾個月和年度的都一起做好發佈吧。"

背景：上一個 session 我們已經完成了 2026 年 1 月的報告作爲概念驗證。一份完整的公務航空市場報告，包含 8 個自定義組件、14 個敘述段落、JSON-LD 結構化數據和四語言支持。架構已驗證，CEO 認可了質量，然後說：再做四份，今晚。

剩餘四份：2025 年 10 月、2025 年 11 月、2025 年 12 月、2025 全年。每一份都需要從 Avi-Go 的 67 到 112 頁 HTML 報告中提取數據、轉化爲類型化 TypeScript 數據結構、撰寫 14 段編輯敘述、配置完整 SEO 元數據。一月報告從零開始花了一整個 session，現在要在一夜之內複製四次。

什麼是 VOLO Insights？

VOLO Insights 是公務航空市場情報欄目，聯合品牌標識爲 "Powered by Avi-Go"。發佈全球私人航空活動的月度和年度報告——航班總量、區域分佈、機場排名、機型利用率、運營商分析和航線情報。

戰略邏輯分兩層：

SEO 層。互聯網上每個包機平臺的內容都一樣："什麼是私人飛機？"、"包機多少錢？"、"十大豪華目的地"。沒有一家發佈原創市場數據。今夜之後，VOLO 擁有五個月的結構化公務航空情報，競爭對手無法複製——因爲沒有競爭對手能獲取 Avi-Go 的原始飛行追蹤數據。

GEO 層。GEO 即生成式引擎優化（Generative Engine Optimization）——一年前幾乎不存在的概念。傳統 SEO 爲 Google 爬蟲優化：關鍵詞、meta 標籤、反向鏈接。GEO 爲 AI 搜索引擎優化——ChatGPT、Perplexity、Gemini、Claude。這些系統不像 Google 那樣追蹤鏈接，它們需要可引用的、有事實依據的結構化文本。每份 VOLO Insights 報告包含 14 段自然語言敘述，專門爲 AI 搜索引擎提取和引用而撰寫。當有人問"2025 年有多少公務機航班？"時，我們希望答案來自 VOLO Insights。

數據源是 Avi-Go——VOLO CEO Wei 運營的公務航空分析平臺。Avi-Go 追蹤全球 ADS-B 飛行數據併發布交互式 HTML 報告。VOLO 將原始情報轉化爲結構化、可索引、多語言的網頁體驗。雙方共贏：VOLO 獲得獨特 SEO 內容，Avi-Go 通過高端航空平臺獲得分發和曝光。

數據管線

如何將一份 100 頁的交互式 HTML 報告轉化爲 TypeScript 驅動的 Next.js 應用？以下是我們構建的管線：

數據源。Avi-Go 以多頁 HTML 文件發佈月度報告，內嵌圖表、表格和敘述文字。這些是瀏覽器渲染的文檔，不是 API 可訪問的數據。每份報告 67 到 112 個 HTML 頁面，覆蓋當月航空活動的各個方面。

提取。Claude Agent 充當智能提取器。每個 Agent 接收 Avi-Go HTML 頁面和目標 TypeScript 模式，輸出符合類型系統的結構化數據。這不是簡單的爬蟲——Agent 需要解讀圖表、校對錶格數據、從密集的報告頁面中定位正確數字，並以自然語言生成 14 段敘述。

類型系統。基礎是 types.ts——19 個 TypeScript 接口定義報告中的每個數據點。ReportOverview 管頭條指標，RegionalBreakdown 管三大區域市場份額，還有 AirportRanking、AircraftUtilization、OperatorRanking、CrossBorderRoute、CityPair，以及 ReportNarratives——驅動 GEO 策略的 14 段編輯層。類型系統是原始數據與渲染 UI 之間的契約：數據文件能編譯，頁面就能渲染。

註冊表。reports.ts 存儲所有 5 份報告的元數據，加上數據映射和查詢函數：getAllInsightReports()、getInsightReport(slug)、getInsightReportData(slug)。添加新月份只需三步：創建數據文件、添加導入、添加註冊條目。站點地圖、Hub 頁面和導航全部自動更新。

並行 Agent 架構

一月報告已作爲模板完成，剩餘四份可以並行提取。這就是事情變有趣的地方。

我們同時啓動了 4 個 Claude Agent，每個接收三個輸入：(a) 目標 Avi-Go HTML 報告，(b) types.ts 模式定義，(c) 一月數據文件作爲結構模板。Agent 獨立運行——無共享狀態，報告之間無依賴。每個 Agent 負責產出一個完整的 ReportData 導出。

四個中的三個首次運行即成功。第四個——十一月——遇到了上下文窗口溢出。十一月的 Avi-Go HTML 有 108 頁，加上模式和模板後超出了 Agent 的上下文容量。解決方案是重新啓動並採用聚焦提取策略：不喂入全部 HTML，而是給 Agent 具體的頁碼和章節標識。從第 1 頁提取概覽，從第 5-7 頁提取區域數據，從第 32-34 頁提取機場排名。定向方法順利完成。

結果：4 個完整數據文件在大約等同於處理一個的實際時間內全部產出。一個人類架構師協調四個 AI Agent，各自處理獨立工作流。這不是花哨的演示——這是小型工程團隊未來工作方式的預覽。

十月難題

並非所有數據都是乾淨的。2025 年 10 月是最難處理的報告。

其他每份 Avi-Go 月度報告都有 104 到 112 頁。十月只有 67 頁。其他報告中存在的幾個數據章節完全缺失：按區域運營商分佈、航程結構分析（短/中/遠程分佈）、航程範圍分佈圖。

我們有三個選擇：(1) 留空並顯示"數據不可用"，(2) 完全放棄十月，(3) 從相鄰月份推導合理估算。我們選擇了方案 3。以九月和十一月爲錨點，計算缺失章節的比例估算值。月環比數據確實不存在的地方，設置 momChange: null——這是類型系統在接口設計階段就已支持的模式，因爲我們預料到了數據不完整的情況。

教訓：真實世界的數據是雜亂的。假設每份報告都有每個字段的系統，遇到第一個例外就會崩潰。我們的類型系統通過可空字段和可選章節優雅地處理缺失數據，UI 根據可用內容條件渲染。

年度報告適配

2025 全年報告帶來了不同的結構挑戰。月度報告做環比比較，年度報告沒有"上個月"。

所需適配：

• momChange: null 和 momCountryChanges: []——年度彙總不存在月環比指標
• periodType: "annual"——UI 據此隱藏環比徽章，將"本月"改爲"本年度"
• 12 個月趨勢數組 (monthlyTrend: MonthlyDataPoint[])——年度頁面展示全年軌跡，而非 6 個月滑動窗口
• 敘述框架調整——"2025 年全年……" 而非 "本月……"
• 規模差異——3,515,618 架次而非約 28 萬，需要不同的數字格式和語境描述

類型系統乾淨地處理了這一切。月度和年度報告使用同一個 ReportData 接口，periodType 判別器讓 UI 調整渲染邏輯，無需條件類型體操。一個接口，兩種展示模式。

八個新組件

Insights 欄目需要 8 個定製 React 組件，全部服務端渲染：

CoBrandingBadge。"VOLO Insights · Powered by Avi-Go" 聯合標識。細節雖小，但在每個頁面上確立了合作關係。

MetricCard。數據統計卡片，展示頭條數字、標籤和可選變化徽章。Hub 頁面（最新報告亮點）和詳情頁面（概覽部分）共用。四張卡片：總航班數、同比變化、活躍機隊、日均數量。

InsightSection。容器組件，包含標題、可選描述和子內容。詳情頁每個數據模塊的 section 包裹器，提供一致的間距、標題樣式和錨點 ID。

RegionalBreakdown。三條柱狀圖可視化北美/歐洲/其他地區的市場份額，每條柱顯示區域名稱、百分比和航班數。純 CSS 比例寬度——無需圖表庫。

RankingTable。通用可排序表格，包含排名、名稱、數值列。驅動機場排名、運營商排名和城市對錶格。內含 ChangeBadge 子組件，用彩色箭頭顯示環比/同比變化。

TrendChart。純 CSS 柱狀圖，展示 6 或 12 個月的航班量數據，帶標註座標軸。無 JavaScript 圖表庫——僅靠計算高度和 CSS Grid。服務端和客戶端渲染完全一致。

FlightRangeChart。三段水平柱狀圖，展示短程/中程/遠程航班分佈及百分比標籤。

ReportCard。Hub 頁面的卡片組件。展示報告週期、標題、關鍵指標和鏈接。最新報告獲得高亮"Latest"徽章。

SEO/GEO 技術棧

每個 Insights 報告頁面都攜帶完整的 SEO 和 GEO 載荷：

JSON-LD 結構化數據——每頁四種 schema 類型：Article（Google 新聞）、FAQPage（6 個動態生成的問答用於富摘要）、Dataset（schema.org Dataset 詞彙描述結構化數據源）、BreadcrumbList（導航層級）。DatasetJsonLd 組件是新建的——專爲 Insights 構建，幫助 Google 理解這些頁面包含原創研究數據。

hreflang 替代鏈接——每個報告 URL 有 4 種語言變體（en、zh、fr、es），通過 buildAlternates() 生成。5 份報告 × 4 種語言 = 20 個詳情頁 URL，加 4 個 Hub 頁 URL = 24 條新站點地圖條目。

OpenGraph 和 Twitter 卡片——使用共享 SEO 工具庫的 buildOgImages() 和 buildTwitterCard()。

GEO 敘述——這是核心創新。每份報告在 ReportNarratives 接口中有 14 個敘述段落：執行摘要、全球趨勢分析、三個區域深度分析（北美/歐洲/其他）、航程結構分析、航程範圍分析、各區域機場分析、機型利用率、機型分佈、機型排名、跨境航線分析、運營商分析、熱點航線、特色機型、最受歡迎機型。14 段 × 5 份報告 = 70 段原創可引用內容。

llms.txt——所有 5 個報告 URL 及 Hub 頁面已添加到 public/llms.txt。任何爬取 flyvolo.ai/llms.txt 的 AI Agent 都能發現 Insights 數據和每份報告的關鍵發現。

理念：SEO 爲 Google 爬蟲優化，GEO 爲 ChatGPT、Perplexity 和 Claude 優化。VOLO 同時爲兩者優化。結構化 JSON-LD 服務傳統搜索，自然語言敘述服務 AI 搜索。同一套數據驅動兩種發現範式。

工程挑戰

RSC 違規

Hub 頁面最初在報告卡片上使用了 onMouseEnter 和 onMouseLeave 事件處理器實現懸停效果。這些是 JavaScript 事件處理器——不能存在於異步 React 服務端組件中。修復方案：全部替換爲 CSS hover:opacity-80 過渡效果。相同的視覺效果，零客戶端 JavaScript，完全兼容 RSC。

zsh Shell 引號問題

git add apps/web/src/app/[locale]/insights/page.tsx 在 zsh 中失敗，因爲 shell 將 [locale] 解釋爲 glob 模式。我們在第六天就在 CLAUDE.md 中記錄了這個問題，但每次創建新的 [locale] 路徑時它仍然會出現。修復：始終對包含方括號的路徑使用雙引號。

lint-staged 與 Prettier

29 個文件在提交時需要格式化。lint-staged 成功運行了 Prettier——標準的 TypeScript 項目格式化流程，沒有意外。

今夜發貨

變更	範圍	影響
TypeScript 數據模型	types.ts — 19+ 接口	所有當前及未來報告的契約
報告註冊表	reports.ts — 5 條目，6 個查詢函數	整個欄目的發現、路由、數據訪問
5 個數據文件	每個約 400 行	10月、11月、12月 2025 + 1月 2026 + 2025全年
8 個新組件	8 個 TSX 文件	CoBrandingBadge 到 ReportCard
Hub 頁面	/insights	全部報告列表，最新高亮，FAQ 部分
詳情頁	/insights/[slug] — 約 994 行	8 個部分，3 個特色模塊，動態 FAQ
SEO 技術棧	JSON-LD、hreflang、OG、sitemap	跨 4 種語言 24 條新索引 URL
GEO 敘述	14 個部分 × 5 份報告	爲 AI 搜索引擎準備的 70 段文本
llms.txt 更新	6 條新 URL + 關鍵發現	AI Agent 可發現性
合計	29 個文件，6,022 行新增	生成 1,710 頁，零構建錯誤

數據亮點

五份報告的頭條數據：

報告	總航班數	同比變化	亮點
2026年1月	263,595	+0.56%	北美佔所有航班的 76.74%
2025年12月	291,272	+3.26%	節日季推動日均達 9,396 架次
2025年11月	287,715	+6.36%	Q4 最強同比增長
2025年10月	300,697	-2.09%	按原始量計全年最繁忙月份，日均 9,700
2025全年	3,515,618	+6.21%	全球追蹤 21,979 架活躍飛機

反思

互聯網上每個包機平臺都在用同一套打法競爭：機隊頁面、航線描述、預訂表單和千篇一律的"奢華旅行"博客文章。內容可以互換，把 logo 換掉，你分不清誰是誰。

今夜之後，VOLO 不一樣了。我們擁有五個月的結構化原創公務航空市場情報，競爭對手無法複製。不是因爲技術多難——任何團隊都能搭建同樣的組件庫。而是因爲數據是專有的。Avi-Go 追蹤全球數千架公務機的 ADS-B 飛行活動。將原始情報轉化爲帶 SEO 元數據和 AI 可引用敘述的結構化頁面，創造了一條內容護城河——再多的"十大包機目的地"博客也無法匹敵。

GEO 押注是前瞻性的。今天大多數人還在 Google 搜索"公務航空統計數據"。但越來越多的人在問 ChatGPT 或 Perplexity。當這些 AI 系統回答時，它們需要可引用的來源、可信賴的結構化數據、可以引述的自然語言段落。VOLO Insights 正是爲那個未來而建——5 份報告中的 70 段敘述，每一段都是等待正確問題的可引用答案。

並行 Agent 模型也值得反思。晚上 10 點 CEO 的一句話變成了 4 個併發提取 Agent，各自獨立地將 100 頁 HTML 報告轉化爲類型化 TypeScript 數據文件。一個人類做架構師，四個 AI Agent 做建設者。協調開銷極小——定義一次 schema，提供一個模板，並行啓動，合併輸出。這不是兩年前構建軟件的方式，但這將是兩年後的方式。

內容誰都能生成。每個有 API Key 的創業公司都能一夜產出 50 篇博客。但結構化的、經過驗證的專有數據——從真實的分析平臺提取、按真實的 schema 類型化、用真實的 SEO 基礎設施渲染、以月度節奏發佈——那纔是可防禦的資產。護城河不是代碼，護城河是數據。今夜，我們注滿了它。

提交記錄

4f60a0e — feat: launch VOLO Insights — 5 business aviation reports with full SEO/GEO stack

29 個文件變更，6,022 行新增，零有意義的刪除。晚間 11:47 通過 Vercel 部署到生產環境。