内容与公告管理

开放平台的文档不只承载 API 参数，还需要让开发者知道平台最近发布了什么、哪些能力值得关注，以及不同场景应该从哪里开始接入。

内容定位

内容模块用于承载平台运营团队发布的公告、文章、案例和能力更新。它应当和开发者文档保持同一套导航体验，但在信息表达上更偏向场景、变化和决策参考。

在开放平台里，内容模块承担的是“持续沟通”的角色。能力市场解决“有什么能力”，API Reference 解决“怎么调用”，内容与公告则解决“为什么现在要看这个能力、这次更新影响谁、上线前应该注意什么”。这三类信息需要互相链接，但不应该互相替代。

建议早期先把内容系统做轻，使用 MDX 管理文章主体，用 frontmatter 管理标题、摘要、分类、标签、发布时间等元信息。这样既能快速上线，又能保留后续迁移到运营后台的字段基础。

适合发布的内容

• 平台版本公告，例如新能力上线、接口字段调整、控制台功能更新。
• 接入教程，例如从教育 OCR 到智能批改的组合调用实践。
• 场景案例，例如拍照搜题、口语练习、作文批改和课堂反馈。
• 迁移说明，例如旧接口下线、签名规则调整、回调格式升级。

这类内容的共同点是可以帮助开发者完成一次明确判断：是否需要关注、是否需要修改代码、是否可以马上接入、是否存在兼容风险。文章里应尽量提供可执行信息，例如接口路径、字段变化、示例请求、上线时间、灰度范围和排障入口。

对于能力更新，建议配套给出“新增能力”和“已有能力变化”的区分。新增能力更适合放场景说明和试用入口；已有能力变化更需要强调兼容性、影响范围和迁移建议。

对于解决方案类内容，建议从业务链路展开，而不是从单个接口展开。例如“拍照搜题”可以包含图片上传、题目识别、答案解析、结果回调和调用日志；每个环节再链接到对应能力或 API。

不适合发布的内容

纯营销口号、没有接入细节的能力宣传、未确认发布时间的路线图，以及无法被开发者复现的内部实验内容，都不建议放入开发者文档体系。

开发者文档里的内容需要有稳定性。还没有明确上线计划的功能，可以放在内部规划或产品介绍里，不建议进入公开文档；否则开发者会基于不稳定信息做方案设计，后续变更成本会变高。

如果一篇文章无法回答“谁需要看、看完能做什么、相关页面在哪里”，通常就不适合进入文档站。可以先把它沉淀为内部材料，等内容变成明确公告、教程或案例后再发布。

同样，不建议把所有运营活动都塞进文档站。优惠活动、商务合作、品牌宣传可以留在官网或控制台消息中心，文档站只保留与接入和平台能力强相关的内容。

内容模型

内容模型应当先保证稳定，然后再接入后台发布流程。早期可以通过 MDX 文件维护，等到内容量上来后再把同一套字段迁移到 CMS 或运营后台。

内容模型的核心不是字段越多越好，而是让文章可以被导航、搜索、筛选、推荐和归档。早期字段建议服务于四件事：列表展示、详情渲染、目录生成、关联推荐。

在 MDX 阶段，frontmatter 可以承担最小元信息，正文负责展示结构化内容。进入后台阶段后，这些字段可以迁移成数据库列或 JSON 字段，保持前台展示逻辑不变。

文章基础字段

建议把 slug 也作为显式字段维护，避免中文标题变更后影响访问地址。路径一旦公开，就应该尽量稳定，尤其是被官网、控制台、能力市场和外部客户文档引用的文章。

对于公告类文章，可以增加 effectiveDate 表示生效时间；对于迁移类文章，可以增加 deprecatedAt 和 migrationDeadline。这些字段后续可以用于列表提醒、控制台消息和上线前校验。

如果文章需要绑定具体能力，可以增加 relatedAbilities 字段，例如 education-ocr、realtime-en-evaluate。如果文章需要绑定解决方案，可以增加 relatedSolutions 字段，例如 photo-search、oral-practice。

---
title: 实时英文语音评测接入说明
description: 介绍实时英文语音评测的接入流程、音频要求和评分结果。
date: 2026-09-03
author: ThinkWheel Open Platform
category: 接入教程
tags: [语音评测, WebSocket, 英语口语]
relatedAbilities: [realtime-en-evaluate]
---

分类建议

内容分类不宜过细，建议先控制在四类以内：产品公告、接入教程、解决方案、版本更新。分类用于帮助开发者快速判断文章价值，标签再承担更细粒度的检索。

分类要表达文章的主要用途，而不是表达组织架构。比如“算法团队”“平台团队”“运营团队”不适合作为公开分类，因为开发者并不关心内部归属；他们更关心这篇内容能否帮助自己接入、排障或评估能力。

建议第一阶段使用这些分类：

标签则可以更细，例如 OCR、语音评测、作文批改、回调、错误码、签名。同一篇文章可以有多个标签，但只建议有一个主分类。

状态流转

文章可以从 draft 进入 review，审核通过后进入 published。已发布内容如果需要修改，应保留最近更新时间，涉及接口兼容性的内容还应补充变更说明。

状态流转需要服务于团队协作。草稿阶段允许频繁调整，审核阶段应锁定主要结构，发布阶段则需要保证链接稳定、标题层级完整、代码示例可复制。

推荐状态如下：

对外公开后，文章不建议直接删除。更稳妥的方式是标记为归档，并在顶部提示新文档地址，避免搜索结果或客户收藏链接变成 404。

写作结构

开放平台内容应该让开发者尽快判断“和我有没有关系”。每篇文章开头先说明适用对象，再进入接入路径、参数变化或业务价值。

一篇好的开放平台文章通常有明显的节奏：先说结论，再说影响范围，然后给步骤、示例和注意事项。读者不一定会从头读到尾，所以每个二级标题都应该能独立表达该段价值。

右侧目录会放大标题质量。如果标题太抽象，例如“介绍”“说明”“其他”，目录看起来就没有帮助；如果标题直接表达任务，例如“配置回调地址”“处理限流错误”“关联能力详情”，开发者就能快速跳转。

公告类文章

公告类文章建议按“变化摘要、影响范围、上线时间、处理建议、相关链接”组织。涉及破坏性变更时，必须把旧逻辑、兼容窗口和迁移步骤写清楚。

公告类内容最怕信息不完整。开发者看到公告后，第一反应通常是判断自己是否受影响，所以影响范围应该放在靠前位置，例如影响哪些能力、哪些接口、哪些环境、哪些应用状态。

建议公告模板包含这些章节：

• 变化摘要：一句话说明发生了什么。
• 影响范围：列出受影响能力、接口、环境和时间。
• 处理建议：告诉开发者需要改配置、改代码，还是无需处理。
• 验证方式：提供控制台入口、日志字段或 API 调用方式。
• 相关链接：跳转到能力详情、API Reference 或迁移指南。

如果公告涉及接口字段调整，应提供新旧字段对照表。只写“接口已升级”不够，必须让开发者知道自己的请求和响应处理是否要变。

教程类文章

教程类文章建议从最小可运行链路开始，先给出调用前提，再给出请求示例、响应示例和常见错误。不要把多条无关能力堆在同一篇教程里。

教程类内容要尽量降低首次接入成本。读者通常希望复制示例、替换密钥、完成一次请求，然后再深入理解字段和错误处理。

推荐教程结构：

1. 准备工作：账号、应用、能力授权、环境地址。
2. 请求示例：最小可运行参数和请求头。
3. 响应说明：成功响应、失败响应、异步回调。
4. 常见问题：签名失败、能力未授权、参数格式错误。
5. 下一步：链接到完整 API Reference 或能力详情。

教程里的代码示例要保持短小。复杂业务逻辑可以拆到后续章节，不要让第一段示例承担所有功能。

案例类文章

案例类文章更适合按业务流程组织，例如“上传图片、识别题目、返回答案、记录调用日志”。案例中出现的接口参数应链接到 API Reference，而不是重复维护两份定义。

案例类内容的重点是把多个能力串成业务流程。它不一定要覆盖每个字段，但应该明确每一步输入来自哪里、输出给谁、失败后怎么处理。

以“拍照搜题”为例，可以拆成：

• 用户上传题目图片。
• 调用教育 OCR 识别题干和选项。
• 调用题目解析能力生成答案和讲解。
• 将结果写入学习记录。
• 异常时进入人工兜底或提示重新拍照。

案例中可以加入流程图、时序说明或伪代码，但字段定义仍应链接到 API Reference。这样后续接口字段变化时，只需要维护一份权威定义。

右侧目录效果

右侧目录由当前页面的标题层级自动生成。正文中保持稳定的 ## 和 ### 结构后，Fumadocs 会自动在右侧展示可点击目录。

要让右侧目录的 active 状态明显，正文不仅要有标题，还要让每个标题下面有足够的阅读高度。否则滚动时多个标题会在很短距离内连续越过视窗阈值，active 状态看起来就像没有稳定停留。

本页面刻意增加了每个目录项下的说明、列表和表格，就是为了让右侧目录在滚动时能形成更清楚的高亮变化。后续真实文档接入时，也应该用内容本身自然撑开，而不是用空白高度模拟效果。

标题层级

页面标题由 frontmatter 的 title 提供，正文从 ## 开始。二级标题承担章节，三级标题承担章节内的关键步骤或概念。

建议页面只使用一个语义主标题，也就是 frontmatter 的 title。正文不要再写一个重复的 # 标题，否则目录层级会显得混乱，也不利于页面 SEO。

推荐层级：

---
title: 能力调用
---

## 请求说明

### 请求头

### 请求体

## 响应说明

### 成功响应

### 失败响应

如果某个三级标题下面只有一句话，说明这个标题可能不需要单独存在。可以把它合并到上一个章节，或者补充示例和注意事项。

内容长度

如果页面只有一两个二级标题，右侧目录会显得很空。真实接入文档通常需要覆盖前提、流程、参数、示例、错误处理和下一步，因此应该自然形成多个目录项。

内容长度不是为了堆字数，而是为了让读者在每个章节获得完整上下文。比如“签名规则”至少应该包含参与签名字段、排序方式、摘要算法、示例字符串和错误排查，否则开发者仍然需要到处询问。

对于短页面，可以优先补充这些内容：

• 适用场景：告诉读者什么时候用这个能力。
• 前置条件：说明账号、权限、环境和密钥要求。
• 示例：给出可以复制的请求或配置。
• 注意事项：列出常见错误和限制。
• 相关链接：跳转到下一步文档。

这些内容会自然形成滚动距离，也能让右侧目录的 active 状态有足够展示空间。

锚点跳转

右侧目录点击后会跳转到对应标题位置。标题文本应保持稳定，避免频繁改名导致外部分享链接失效。

如果标题必须修改，建议同时检查站内链接、控制台入口和客户文档中是否引用了旧锚点。对外文档一旦被分享，锚点其实也会成为公开契约的一部分。

标题命名建议使用动宾结构或明确名词，例如“配置回调地址”“处理失败响应”“能力详情关联”。这类标题比“配置”“错误”“关联”更适合出现在右侧目录里。

和能力市场的关系

内容模块不替代能力市场。能力市场负责展示能力本身，内容模块负责解释能力如何被组合、如何上线、如何排障。

能力市场是入口，文档内容是解释层。开发者在能力市场完成初步选型后，应该能跳到对应教程；开发者在教程中遇到字段细节时，应该能跳到 API Reference；开发者在排障时，应该能回到错误码和调用日志说明。

因此，内容系统需要预留跨模块关联字段。哪怕第一阶段只是 MDX，也应该在写作时形成稳定的链接习惯，避免后续迁移后台时重新整理关系。

能力详情关联

能力详情页可以关联教程和公告，例如“实时英文语音评测”关联音频格式、实时事件、评分维度和错误处理文档。

能力详情页更适合放能力边界、输入输出摘要、价格或额度、申请入口；教程则负责解释如何接入。二者关联后，用户可以从“了解能力”顺滑进入“开始调用”。

建议能力详情页关联这些内容：

• 快速开始教程。
• 常见错误说明。
• 最近版本公告。
• 典型解决方案。
• API Reference 中的具体接口。

如果某个能力进入灰度或发生兼容调整，能力详情页也应该显示相关公告，避免开发者只看到旧教程。

解决方案关联

解决方案页可以关联案例文章，例如“拍照搜题”关联教育 OCR、题目解析、答案生成和回调通知的组合流程。

解决方案页面对的是更完整的业务问题。它往往不止使用一个能力，所以内容关联需要支持一对多关系：一个解决方案关联多篇教程、多项能力和多个 API。

例如“中文口语表达”解决方案可以关联：

• 实时语音评测能力。
• 口语表达评分维度说明。
• 音频采集和上传教程。
• 课堂反馈数据回传接口。

这类关联能帮助产品、售前和研发使用同一套资料，减少“官网说法”和“开发文档说法”不一致的问题。

后续接入后台

当 MDX 内容超过人工维护阈值后，可以把内容模型迁移到后台系统，并通过构建时同步或运行时接口展示。

迁移后台不意味着前台展示要重写。更好的方式是先稳定 URL、字段模型和页面结构，再把内容来源从文件切换为接口或构建产物。这样对用户来说，文档站体验保持一致。

后台接入可以分两阶段：第一阶段只做内容录入和发布，第二阶段再做权限、审核流、搜索索引和多语言。避免一开始就把 CMS 做得过重。

后台编辑

后台应支持草稿、预览、审核、发布和撤回。开发者文档类内容还需要支持代码块、表格、提示块和内部链接校验。

编辑器不一定一开始就做成完整富文本。对于技术文档，MDX 或 Markdown 编辑体验往往更稳定，尤其适合维护代码块、表格和内部链接。

后台编辑建议优先支持：

• frontmatter 字段编辑。
• Markdown 正文编辑。
• 右侧目录预览。
• 站内链接校验。
• 草稿预览地址。

如果后续接入多角色审核，需要明确谁能编辑、谁能审核、谁能发布。公开文档的发布权限应收紧，避免未审核内容误上线。

搜索索引

发布后应同步搜索索引，让开发者可以通过能力名称、错误码、接口字段和场景关键词找到内容。

搜索索引的质量很大程度取决于标题、摘要、标签和正文结构。文章如果缺少摘要或标题过于抽象，搜索结果会变得难以判断。

建议索引字段包括：

搜索结果应尽量跳转到具体章节锚点，而不是只跳到页面顶部。对于长文档，这一点会明显提升效率。

发布校验

发布前至少校验标题层级、内部链接、代码块语法和 frontmatter 字段，避免文档上线后右侧目录缺失或页面构建失败。

发布校验可以从构建期开始做。MDX 编译失败、frontmatter 缺少必填字段、站内链接无法解析，都应该阻止上线。

建议校验项：

• 页面必须有 title 和 description。
• 正文必须从 ## 开始组织章节。
• 代码块必须声明语言。
• 站内链接必须存在。
• 关联的能力或解决方案必须存在。

这些校验能保证右侧目录、搜索索引和跨页面推荐都能稳定工作。

下一步

当前阶段建议继续用 MDX 管理内容，把文章结构、目录层级和跨页面链接先跑顺。等开放平台进入运营期，再把内容发布、权限审核和搜索索引接入控制台。

短期建议先补齐三类内容：能力公告、接入教程、解决方案案例。每类各准备 2 到 3 篇示例，就能验证导航、右侧目录、搜索和跨页面链接是否顺畅。

中期可以把内容模型同步到 fe-admin，让运营团队在后台维护草稿和发布状态。前台 fe-docs 仍然保持 Fumadocs 的阅读体验，避免后台复杂度影响开发者阅读。

长期再接入 OpenAPI 自动生成、SDK 示例、版本差异和多语言能力。这样文档站会从“静态内容站”逐步变成开放平台的开发者知识中心。