←首页影像百科
2026年06月25日

2026-06-25 文章系统整合与案例迁移

影像百科文章系统格式修复、层级重构、高通 RAW 案例迁移、跨项目卡片联动的完整记录，含踩坑和解决方案。

背景

今天的目标：将零散的知识系统（/knowledge/ 下的等效光圈、传感器尺寸、视场角独立页面）整合到统一的 Articles 系统中，同时将一篇高通 RAW 调试案例从飞书文档迁移到网站上。

时间线

阶段一：新增文章和工具（增量）

在 Articles 系统中新增 3 篇光学原理文章和 3 个交互工具：

  • equivalent-aperture（等效光圈原理）+ aperture-simulator（光圈散景模拟器）
  • equivalent-sensor（传感器尺寸原理）+ sensor-visualizer（传感器可视化）
  • fov-focal-length（视场角与焦段）+ fov-visualizer（视场角模拟器）

每篇文章通过 related_tools 和 related_notes 互相链接，右侧边栏可双向跳转。工具页面通过新建 SimulatorPageClient 包装组件实现了右侧"相关文章"导航。

遇到的问题：

工具页面最初只是直接渲染模拟器组件，缺少右侧栏。后来参考 ColorAnalysisPageClient 的模式，创建了通用 SimulatorPageClient 包装组件，统一处理文章关联数据加载和侧边栏渲染。

阶段二：格式修复

标题重复问题：ArticlePage 头部已从 frontmatter 渲染 H1 标题，但 Markdown 正文又以 # 标题 开头，导致标题出现两次。修复方式：删除 11 篇文章的正文 H1，正文从 H2 开始。

代码块语言标注：8 篇文章的 13 处公式/流程代码块缺少语言标注（``` 后面没写 text），批量补上。

标题层级错误：color-analysis-imatest-comparison-log.md 中，3 个日期标题和它们下方的子段落（修改结论、问题现象、排查过程）全部是 H3，实际应为 H3 → H4 的层级关系。修复后层级变为：## 开发日志 → ### 日期标题 → #### 修改结论。

阶段三：层级重构

行尾符问题：已有文章（从飞书导出）使用 Windows CRLF 行尾，新建文章（Kilo Write 工具）使用 LF 行尾。parseFrontmatter 函数只检查 ---\n（LF），导致 CRLF 文章的前置元数据无法解析，标题显示为 slug、父级分组丢失。

修复：在 lib/articles.ts 的 getArticle 函数中加 .replace(/\r\n/g, '\n') 统一换行符。

BOM 问题：Kilo 的 Write 工具创建文件时会在头部加 UTF-8 BOM（\uFEFF），导致文件以 BOM 开头而非 ---，frontmatter 同样解析失败。

修复：在 getArticle 中追加 .replace(/^\uFEFF/, '') 去除 BOM。

效果：修复后侧边栏层级正常——文章按 parent 字段正确归入父级文件夹，标题显示真实标题。

阶段四：高通 RAW 案例迁移

挑战一：图片迁移。原始文档在飞书上，图片链接为内部 API，无法直接下载。尝试方案：

  1. 导出为 .docx，用 mammoth 库转换为 Markdown，同时提取内嵌图片 ✅
  2. 飞书公开链接 → 仅展示部分内容，无法批量抓图 ❌
  3. pandoc 直接转换 → 系统未安装 ❌

mammoth 成功按文档顺序提取了 15 张图片并生成 Markdown。但产生的 Markdown 有两个问题：

  • 方括号内的文本被错误转义（\[raw转换脚本\.py\] 变成了文字乱码）
  • 图片引用名为 img-undefined（image.index 在特定 mammoth 版本中不可用）

解决：改用递增计数器命名图片（1.png 到 15.png），确保文件名一致。

挑战二：格式保真。mammoth 转换丢了原文档的段落间距和标题层级——原文用加粗文字做章节标题，mammoth 只保留了 **文字** 格式。

解决：以 mammoth 的正确图片位置为骨架，对照原文 Markdown 文件逐段恢复空行、缩进和层级。最终将 10 余处加粗章节标记转换为了 H2/H3 标题。

挑战三：脱敏处理。项目代号（SCZ0102）、传感器型号（OV50H）、通信协议名称（MAVLink）、内部服务名（gst-camera-app）需要移除或泛化。

阶段五：侧边栏优化

右栏 TOC 空白：文章章节用加粗而非 Markdown 标题标记，导致右侧目录无法生成。将章节标记转为 H2/H3 后目录自动生成。

滚动固定：长文章滚动时右栏不固定。在 ArticlePage.tsx 右侧栏加 sticky top-[calc(2.75rem+2rem)]。

阶段六：个人网站卡片

在 hanswebsite 首页 "Imaging Analysis Cases" 区域新增/更新 3 张卡片：

  1. Phone Camera Hardware Quantitative Comparison Platform
  2. Online Color Analysis Tool
  3. Qualcomm Platform RAW Pipeline Debug & Analysis

每张卡片通过 detailUrl 链接到 phonecameradata 对应文章。

关键教训

  1. 行尾符一致性：跨平台（Windows/Linux/Web）文本处理，必须统一行尾符后再解析。
  2. BOM 副作用：工具链自动加 BOM 会导致 frontmatter 静默失败（无报错，只是解析为空），排查耗时。
  3. 格式转换有损：mammoth 保住文字和图片位置，但段落间距、缩进、标题层级需要人工恢复。
  4. 分批确认＞批量执行：对11篇文章批量删除 H1 时未先确认，后来标题层级错误又需要二次修正。

待办

  • Phase 2：替换首页入口，将旧 /knowledge/ 链接改为 Articles 系统
  • Phase 3：删除旧知识系统代码（/app/*/knowledge/、KnowledgeView.tsx、lib/knowledge.ts）
  • 英文版高通 RAW 案例文章
  • 中英文不对等补齐（灰阶、锐度文章缺少英文版）