工程日记・第九天：一夜五份报告 —— 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 部署到生产环境。