FunASR 文档与产品网站重构指南：从仓库 Markdown 到双语静态文档中心-平芜编程栈

FunASR 文档与产品网站重构指南：从仓库 Markdown 到双语静态文档中心

【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR

导读

本文基于 FunASR 仓库中的docs/superpowers/specs/2026-09-06-docs-product-redesign.md规格文档，系统梳理 FunASR 文档与产品官网（www.funasr.com）的重构方案：它如何在保留既有 URL 与技术范围的前提下，把散落在仓库各处的 Markdown 源文档，经 Jinja 静态站点生成器渲染为带共享侧边栏、分区导航、源链接与本地搜索索引的双语/docs/文档中心，并配套部署手册、博客与捐赠页。读完本文，你将掌握这套"文档目录 + 静态渲染 + 部署注册表 + 静态验证 + 原子发布"的完整架构、视觉与无障碍规范、技术完整性约束，以及从构建、验证到上线回滚的可复现操作流程。

重构目标与设计意图（Intent）

规格文档开篇明确了这次重构的意图：围绕"模型选择、首次推理、部署、运维"四个核心任务重建公开文档体验，而不是继续堆叠按目录平铺的静态页面。用户已授权实现与可逆部署，无需重复审批，但有两个硬性前提：

保留现有 URL：历史文章正文、锚点、demo 与媒体资源全部保留，只在其外层套上统一的"壳"（shell）；
保留技术范围：不借重构之名扩大或改动既有技术边界。

这一意图在仓库中的落点是 web-pages/product-site/README.md 所声明的"内容所有权"划分：data/documentation.json只负责登记"任务分组、双语标题与 Markdown 源"，而文档正文始终来自仓库的docs/、model_zoo/、runtime/、examples/openai_api/目录——单一事实来源（single source of truth），GitHub 读者看到的与网站渲染的是同一份内容，杜绝复制粘贴造成的漂移。

架构：文档目录驱动的静态站点

整体设计

规格中的 Architecture 部分给出了顶层方案：

保留现有的Jinja 模板 + 静态站点生成器与部署注册表（deployment registry）；
新增文档目录（catalogue），条目指向现有 Markdown 源而非复制文章；
将这些源渲染为双语/docs/路由，共享侧边栏、分区导航、源链接与本地搜索索引；
未登记的仓库相对链接继续指向其在 GitHub 上的源文件；
源文档的 README 与 Sphinx 索引遵循同一任务顺序；
首页是简洁的产品/工作流入口；模型、部署、文档、生态、评测、博客、捐赠者共享排版、导航与移动端行为，捐赠者固定放在最后。

文档目录：data/documentation.json

目录文件 web-pages/product-site/data/documentation.json 是整套系统的中枢，包含三类数据：

任务分组（groups）：七个分组按用户旅程组织——开始使用（Get started）、模型与能力（Models & capabilities）、训练与扩展（Train & extend）、部署与接口（Deploy & integrate）、评测与运维（Evaluate & operate）、应用与生态（Applications & ecosystem）、协议与参考（Protocols & reference）；
页面条目（pages）：每个条目含唯一 slug、所属分组、双语标题以及source_zh/source_en两个源文件路径，例如quickstart对应docs/tutorial/README_zh.md与docs/tutorial/README.md；
本地化页面（localized_pages）：用于日文、韩文这类未覆盖全站的语言，路由限定为ja/、ko/前缀，例如ja/agent.html、ko/benchmark.html。

目录的约束由 web-pages/product-site/documentation.py 中的load_catalogue()强制校验：分组与 slug 必须唯一、slug 必须匹配[a-z0-9]+(-[a-z0-9]+)*、每个源文件必须真实存在且不得逃逸仓库根目录（is_relative_to(REPO_ROOT)检查），否则构建直接失败。

渲染管线：documentation.py

render_source() 是 Markdown 源到 HTML 的核心转换：

使用 Python-Markdown 的extra、toc、sane_lists扩展，其中toc扩展通过source_slug()保留 Unicode 字符与重复空格生成的锚点名，避免中文标题锚点在 URL 中失效；
用 BeautifulSoup 重写a[href]与img[src]：已登记的指南映射到本地双语路由，未登记的相对链接映射回 GitHub 源路径；任何../逃逸仓库的行为都会被显式报错；
把正文中的h1改写为div.source-title-anchor并清空，因为文档标题已移入页面外壳，但保留源码锚点名称以兼容旧链接；
为每个<pre>代码块生成稳定 id（code-0、code-1…），供复制控件使用；
返回content_html（正文）、toc_html（页内目录）、source_url（源文档链接）与source_english_only（中文页暂用英文源时提示）。

共享外壳模板：docs.html

双语文档页由 web-pages/product-site/templates/docs.html 渲染，它基于base.html提供完整的阅读环境：

侧边栏（docs-sidebar）：按七个分组折叠列出全部指南，当前页以aria-current="page"高亮，并附"部署手册"入口；
面包屑：FunASR → Docs → 当前文档，保证层级感知；
页眉：双语标题 + "查看 / 编辑源文档" 链接（data-source-link）；
正文：.docs-article容器承载渲染后的 Markdown；
相邻文档导航：上/下篇切换；
页内目录（docs-toc）：仅文档详情页展示。

本地搜索：无需账号、无需远程分析

规格要求"搜索在本地工作、能处理无结果场景、无需账号或远程分析"。实现分两层：

构建期由 write_search_indexes() 遍历输出目录，剔除script/style/nav与页眉页脚后，为每页生成{title, url, text}三元组，按语言输出search-zh.json与search-en.json（正文截断 24000 字符）；
运行期由 web-pages/product-site/templates/search.html 提供data-doc-search表单与#search-results容器，aria-live="polite"保证结果区对屏幕阅读器可感知，无需任何后端。

保持既有 GitHub Pages 路由：export_docs.py

web-pages/product-site/export_docs.py 负责在既有 GitHub Pages 路径上发布渲染后的指南：通过ALIASES映射（如quickstart→tutorial.html、benchmark→benchmark.html、agent-integration→agent.html），把指纹化资源随文档一起本地拷贝，使发布不依赖跨主机时序；同时通过insert_legacy_anchors()把旧文档的锚点片段以span[data-legacy-doc-anchor]形式插入当前章节旁，实现旧锚点全部存活的承诺。仓库根目录的gh-pages-output/（含index.html与zh/index.html）即该流程产出的 GitHub Pages 入口。

视觉方向（Visual Direction）

规格对视觉给出了明确、克制的规范，核心是"技术阅读体验优先、拒绝装饰性设计"：

配色：白色/浅灰阅读面、近黑文字与代码面、翡翠绿（emerald）命令与小面积珊瑚色（coral）点缀；
字体：系统无衬线字体 + CJK 无衬线回退（中文阅读不依赖 WebFont 加载）；
禁例：不引入"服务器配图"式的库存大图、不承诺人工性能数字、不使用渐变装饰与浮动卡片；
几何与无障碍：固定字号、8px 及以下圆角、可见的 focus 态、prefers-reduced-motion支持、窄屏下表格与代码仍可读；
资产：仅使用已获授权的 Lucide 图标与真实的项目/音频资产。

仓库中 web-pages/product-site/templates/base.html 与assets/css/experience.css（README 中声明其为"共享的产品与 legacy 阅读体验"样式）共同承载这套视觉，测试 test_legacy_articles_and_new_pages_share_versioned_design 进一步验证新旧页面共享同一版本化样式与主导航，且导航末项恒为捐赠页。

桌面端与移动端的实际渲染效果如下（来自仓库浏览器测试截图）：

技术完整性约束（Technical Integrity）

规格专门列出四条"不可妥协"的事实边界，防止重构过程中以营销话术污染技术事实：

MOSS 归因：MOSS 转写/说话人分离能力必须明确归因 OpenMOSS，相关文档见 docs/moss_transcribe_diarize.md；
匿名说话人：离线转写与说话人分离产出的是匿名说话人标签，不是身份识别；
概念不混淆：不得把原生 vLLM 支持、split-engine 包装、实时 ASR、CPU/GPU 验证覆盖范围混为一谈——web-pages/product-site/registry.py 用MATURITY_VALUES（production-verified/community-verified/experimental）约束部署条目的成熟度表述，production-verified条目强制要求 evidence、verified 字段与 smoke 命令；测试 test_official_native_record_has_local_language_links_and_search 还专门校验部署页只引用官方模型名而非第三方 fork；
许可证：工具包许可证来自仓库根目录 LICENSE（Apache-2.0），模型许可证因模型而异（见 MODEL_LICENSE），不允许笼统宣称。

此外规格要求"从一手证据修复发现的过期文案，绝不为了凑合设计而夸大测试声明"。README 也强调：历史评测证据必须保留其当时确切的模型/运行时/硬件，新上游支持不构成旧测试覆盖新 checkpoint 的证据。对应测试 test_historical_benchmark_does_not_advertise_missing_scripts_as_runnable 会拦截任何把历史脚本当作可运行命令来宣传的文案。

验收标准与验证体系（Acceptance）

规格给出 7 条验收标准，每一条在仓库中都有可执行的验证实现：

验收标准	仓库中的验证落点
1. 双语首页、部署中心/详情、模型列表、文档、博客与捐赠者可用	`build.py`+ test_bilingual_docs_have_navigation_and_real_source_content
2. 文档源自仓库 Markdown；链接、图片、围栏代码、表格正常渲染	documentation.py 的链接重写 + 各`test_*_docs.py`
3. 搜索本地可用、能处理无结果、无需账号与远程分析	search.html +`search-{language}.json`
4. 移动导航、语言对等页、锚点链接、复制控件支持键盘操作	`tests/browser/*.spec.ts`（Playwright）
5. 既有公开路由与文章内容全部存活，无内部坏链	validate.py 的`_validate_page`
6. 静态测试、全站验证器与 320/390/768/1440/1920 五种视口浏览器检查通过	`pytest web-pages/product-site/tests`+`tests/browser`的 npm 测试
7. 上线前记录源 commit、构建校验和、上次部署与回滚步骤；部署后验证公开路由	docs/operations/funasr-com-site-release.md

全站静态验证器 validate.py

web-pages/product-site/validate.py 在构建产物上执行确定性校验：检查deployment-manifest.json存在且其声明的路由与资产哈希（SHA-256）全部匹配、逐页扫描内部链接与hreflang对等页、校验 JSON-LD 合法性、确认 sitemap.xml 与 canonical 路由集合一致、校验 robots.txt 含规范 sitemap 声明、并为产品页强制img[alt]与本地脚本/样式依赖。/deploy/与/en/deploy/详情页还被要求具备fit、commands、smoke-test、security、limitations、operations、evidence七个data-section与验证日期字段。

部署注册表的数据契约

web-pages/product-site/registry.py 的validate_registry()定义了部署条目的完整数据契约：每条部署须有唯一 id、双语路由、成对出现的中英文翻译字段（且字段集合必须一致）、evidence 链接必须为 https、下载项必须含操作系统/架构/后端/压缩包/URL/64 位小写十六进制 SHA-256，基准项必须覆盖 model/runtime/hardware/workload/audio/settings/timing_scope/result/qualification/source/verified 等字段。

浏览器端验收

web-pages/product-site/tests/browser/下是 Playwright 测试套件（product-site.spec.ts、documentation.spec.ts、copy-controls.spec.ts等），它自带本地 HTTP 服务器并拒绝复用被占用的端口，针对 320/390/768/1440/1920 五种视口执行交互检查；screenshots/目录中保存了桌面、平板与移动端渲染截图作为回归基线。

构建、发布与回滚

本地构建与验证

按 web-pages/product-site/README.md 中的流程即可在本地完整复现：

python -m pip install -r web-pages/product-site/requirements-site.txt python -m pytest web-pages/product-site/tests -q python web-pages/product-site/build.py --output /tmp/funasr-site python web-pages/product-site/validate.py /tmp/funasr-site python scripts/gen_api_docs.py python web-pages/product-site/export_docs.py --site /tmp/funasr-site --output gh-pages-output

其中 scripts/gen_api_docs.py 负责从 Python 源码提取独立的 API 参考（其响应式布局由gh-pages-output/api-reference.css承载），export_docs.py再把渲染好的指南发布到既有 GitHub Pages 路径。

生产发布与回滚

生产发布走web-pages/scripts/deploy-product-site.sh，完整流程记录在 docs/operations/funasr-com-site-release.md：发布前须记录源 commit、构建与清单 SHA-256、上次部署时间，并对旧站点与 Nginx 配置做带 SHA-256 的备份，随后原子切换web-pages/current软链；回滚通过rollback-product-site.sh执行。文档还给出监控做法：对首页、部署页与博客路由执行 HEAD 检查，检查 Nginx 错误日志与转换日志，出现 5xx 上升、索引路由缺失、移动端溢出、资产缺失或静态校验失败即触发回滚。整个流程的要点是"只发布经过测试的产物，绝不发布部分构建的输出"。

如何新增一篇指南

README 给出向目录新增指南的约定，这也是文档体系可持续扩展的关键：

在 web-pages/product-site/data/documentation.json 中同时登记中英两个源路径、唯一 slug 与已知分组（slug 必须是小写字母数字与连字符）；
在正文中使用仓库相对链接，渲染器会把已登记指南映射到本地语言路由；
保持既有 legacy 锚点唯一；
保留协议区分（如 WebSocket 与 HTTP、vLLM 与 split-engine），历史证据明确标注为历史；
不要手工编辑gh-pages-output/中生成的文章正文——发布工作流会在 API 生成器之后重新渲染它们；
专业配方与历史笔记从策展指南链接，而不是当作当前普遍支持的部署路径呈现。

小结

FunASR 的这次文档与产品网站重构，本质上是把"文档"从静态产物升级为可治理的资产管线：目录（catalogue）保证单一事实来源，渲染器负责链接映射与锚点兼容，注册表约束部署表述的事实边界，静态验证器与浏览器测试守住验收标准，发布与回滚脚本保证可逆上线。对读者而言，这套架构既是一份可直接复用的"Markdown 仓库 → 双语静态文档中心"工程样板，也展示了如何在内容工程中把事实准确性与可访问性作为一等公民来设计。

相关参考文件：规格源文档 docs/superpowers/specs/2026-09-06-docs-product-redesign.md · 站点 README web-pages/product-site/README.md · 渲染管线 web-pages/product-site/documentation.py · 目录数据 web-pages/product-site/data/documentation.json · 验证器 web-pages/product-site/validate.py · 发布记录 docs/operations/funasr-com-site-release.md。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考