1. 简介
目前，请参见解释文档。
2. 依赖项
这些 API 属于一组预期由机器学习模型驱动的 API，它们共享通用的 API 表面惯用法和规范模式。目前，这些共享部分的规范文本位于 Writing Assistance APIs § 5 Shared infrastructure，通用的隐私和安全 考量在 Writing Assistance APIs § 6 Privacy considerations 和 Writing Assistance APIs § 7 Security considerations 中讨论。实现这些 API 需要实现该 共享基础设施，并遵循这些隐私和安全考量。但这并不要求 实现或暴露实际的写作辅助 API。 [WRITING-ASSISTANCE-APIS]
3. 校对器 API
[Exposed =Window ,SecureContext ]interface {Proofreader static Promise <Proofreader >create (optional ProofreaderCreateOptions = {});options static Promise <Availability >availability (optional ProofreaderCreateCoreOptions = {});options Promise <ProofreadResult >proofread (DOMString ,input optional ProofreaderProofreadOptions = {} );options readonly attribute boolean includeCorrectionTypes ;readonly attribute boolean ;includeCorrectionExplanations readonly attribute FrozenArray <DOMString >?expectedInputLanguages ;readonly attribute DOMString ?correctionExplanationLanguage ; };dictionary {ProofreaderCreateCoreOptions boolean =includeCorrectionTypes false ;boolean =includeCorrectionExplanations false ;sequence <DOMString >;expectedInputLanguages DOMString ; };correctionExplanationLanguage dictionary :ProofreaderCreateOptions ProofreaderCreateCoreOptions {AbortSignal ;signal CreateMonitorCallback ; };monitor dictionary {ProofreaderProofreadOptions AbortSignal ; };signal dictionary {ProofreadResult DOMString ;correctedInput sequence <ProofreadCorrection >; };corrections dictionary {ProofreadCorrection unsigned long long ;startIndex unsigned long long ;endIndex DOMString ;correction sequence <CorrectionType >;types DOMString ; };explanation enum {CorrectionType ,"spelling" ,"punctuation" ,"capitalization" };"grammar"
3.1. 创建
create(options) 方法的步骤为：
-
返回在给定 options、"
Proofreader"、 验证并规范化 校对器选项、计算校对器选项 可用性、下载校对器模型、初始化校对器模型、创建校对器对象以及 false 时，创建 AI 模型对象的结果。
ProofreaderCreateCoreOptions
options 时，验证并规范化校对器选项，
执行以下步骤。它们会就地改变 options，以规范化并去重语言标签，
并在其中任何一个无效时抛出异常。
-
在给定 options 和 "
expectedInputLanguages" 时，验证并规范化语言 标签。 -
在给定 options 和 "
correctionExplanationLanguage" 时，验证并规范化语言 标签。
ProofreaderCreateCoreOptions
options 时，下载
校对器模型：
ProofreaderCreateOptions
options 时，初始化校对器模型：
-
对支持用户代理校对能力的 AI 模型执行任何必要的初始化操作。
这可以包括将模型加载到内存中，或加载支持 options 所表达的其他选项 所必需的任何微调。
-
如果初始化因任何其他原因失败，则返回一个 DOMException 错误信息，其 name 为 "
OperationError"， 且其 details 包含适当的细节。 -
返回 null。
ProofreaderCreateOptions
options 时，创建
校对器对象：
-
返回一个新的
Proofreader对象，它在 realm 中创建，并具有- include correction types
-
options["
includeCorrectionTypes"] 默认值为 false - include correction explanations
-
options["
includeCorrectionExplanations"] 默认值为 false - expected input languages
-
在 options["
expectedInputLanguages"] 不为空时，是在给定该值时创建冻结数组的结果；否则为 null - correction explanation language
-
如果 options["
correctionExplanationLanguage"] 存在，则为该值；否则为 null
3.2. 可用性
availability(options) 方法的步骤为：
-
返回在给定 options、"
Proofreader"、 验证并规范化 校对器选项以及 计算校对器选项 可用性时，计算 AI 模型可用性的结果。
ProofreaderCreateCoreOptions
options 时，计算校对器选项可用性，执行以下步骤。它们会返回一个 Availability
值或 null，并会就地改变 options，以将语言标签更新为其最佳匹配。
-
令 availability 为给定 options["
includeCorrectionTypes"]、 options["includeCorrectionExplanations"] 时的校对器非语言选项 可用性。 -
令 double 为校对器语言可用性 二元组。
-
如果 double 为 null，则返回 null。
-
令 inputLanguageAvailability 为给定 options["
expectedInputLanguages"] 和 double 的输入语言时，计算语言可用性的结果。 -
令 correctionExplanationLanguagesList 为 « options["
correctionExplanationLanguage"] »。 -
令 correctionExplanationLanguageAvailability 为给定 correctionExplanationLanguagesList 和 double 的更正 说明语言时，计算语言可用性的结果。
-
将 options["
correctionExplanationLanguage"] 设置为 correctionExplanationLanguagesList[0]。 -
返回给定 « availability、inputLanguageAvailability、 correctionExplanationLanguageAvailability » 时的最低可用性。
Availability
值或 null。
-
如果尝试确定用户代理是否能够支持校对文本时发生某种错误，并且 用户代理认为该错误是暂时性的（使得重新查询可能不再产生这种 错误），则返回 null。
-
如果用户代理当前支持按 includeCorrectionTypes 描述的 是否包含纠正类型，以及按 includeCorrectionExplanations 描述的是否包含 纠正解释来校对文本，则返回 "
available"。 -
如果用户代理认为它将能够按 includeCorrectionTypes 和 includeCorrectionExplanations 支持校对文本，但只能在完成一个已经进行中的下载后支持， 则返回 "
downloading"。 -
如果用户代理认为它将能够按 includeCorrectionTypes 和 includeCorrectionExplanations 支持校对文本，但只能在执行一个当前尚未进行的下载后支持， 则返回 "
downloadable"。 -
否则，返回 "
unavailable"。
-
如果尝试确定用户代理是否能够支持文本校对时出现某种错误，并且 用户代理认为该错误是暂时的（因此重新查询可能不再产生此类 错误），则返回 null。
-
返回一个具有以下内容的语言可用性二元组：
- 输入语言
-
给定校对以该语言编写的文本这一目的时，获取语言 可用性分区的结果
- 更正 说明语言
-
给定以该语言生成校对更正的文本说明这一目的时，获取语言 可用性分区的结果
一种可能的实现方式是让校对器语言可用性
二元组返回 "zh-Hant" 位于输入语言["available"]
集合中，而 "zh" 和 "zh-Hans" 位于输入语言["downloadable"]
集合中。此返回值符合语言标签集完整性规则的要求，因为它
确保了 "zh" 存在。根据获取语言可用性
分区算法的步骤，实现确定了 "zh" 应与 "zh-Hans" 一起属于
可下载输入语言集合，而不是与 "zh-Hant" 一起属于可用
输入语言集合。
结合使用LookupMatchingLocaleByBestFit，这意味着 availability()
将给出以下答案：
function a( languageTag) { return Proofreader. availability({ expectedInputLanguages: [ languageTag] }); } await a( "zh" ) === "downloadable" ; await a( "zh-Hant" ) === "available" ; await a( "zh-Hans" ) === "downloadable" ; await a( "zh-TW" ) === "available" ; // zh-TW 将最佳适配到 zh-Hant await a( "zh-HK" ) === "available" ; // zh-HK 将最佳适配到 zh-Hant await a( "zh-CN" ) === "downloadable" ; // zh-CN 将最佳适配到 zh-Hans await a( "zh-BR" ) === "downloadable" ; // zh-BR 将最佳适配到 zh await a( "zh-Kana" ) === "downloadable" ; // zh-Kana 将最佳适配到 zh
3.3. 语言可用性
3.4. Proofreader
类
每个 Proofreader
都有一个 include correction type，它是一个 boolean，或默认值为 false，在创建期间设置。
每个 Proofreader
都有一个 include correction explanations，它是一个 boolean，或
默认值为 false，在创建期间设置。
每个 Proofreader
都有一个 expected input languages，它是一个
FrozenArray<DOMString>
每个 Proofreader
都有一个 correction explanation language，它是一个 字符串或
null，在创建期间设置。
includeCorrectionTypes getter 步骤是
返回 this 的
include correction types。
type getter 步骤是返回 this 的 include correction explanations。
expectedInputLanguages getter 步骤是
返回 this 的
expected input languages。
correctionExplanationLanguage
getter 步骤是返回 this
的 correction explanation language。
proofread(input, options) 方法的
步骤为：
-
令 operation 为一个算法步骤，它接受参数 chunkProduced、 done、error 和 stopProducing，并在给定 this 的 include correction types、this 的 include correction explanations、this 的 correction explanation language、chunkProduced、done、error 和 stopProducing 时，校对 input。
-
返回在给定 this、options 和 operation 时，获取聚合的 AI 模型结果的结果。
measureInputUsage(input, options)
方法的步骤为：
-
令 measureUsage 为一个算法步骤，它接受参数 stopMeasuring， 并返回在给定 input、this 的 include correction types、this 的 include correction explanations、this 的 correction explanation language 和 stopMeasuring 时，测量校对器输入使用量的结果。
-
返回在给定 this、options 和 measureUsage 时，测量 AI 模型输入使用量的结果。
3.5. 校对
3.5.1. 算法
-
一个 字符串 input，
-
一个 boolean includeCorrectionTypes，
-
一个 boolean includeCorrectionExplanations，
-
一个 字符串或 null correctionExplanationLanguage，
-
一个算法 chunkProduced，它接受一个 字符串且不返回 任何内容，
-
一个算法 done，它不接受参数且不返回任何内容，
-
一个算法 error，它接受 错误信息且不返回任何内容，以及
-
一个算法 stopProducing，它不接受参数并返回一个 boolean，
执行以下步骤：
-
令 requested 为给定 input、includeCorrectionTypes、correctionExplanationLanguage、 correctionExplanationLanguage 和 stopProducing 时，测量校对器输入使用量的结果。
-
如果 requested 为 null，则返回。
-
如果 requested 是错误信息，则：
-
给定 requested，执行 error。
-
返回。
-
-
断言：requested 是一个数。
-
以由实现定义的方式，在遵循 以下指导原则的前提下，开始将 input 校对为一个
ProofreadResult， 其中以字符串 correctedInput 作为校对后的文本，并以ProofreadCorrection更正项详细说明为形成 correctedInput 而对 input 作出的所有更正。如果 input 是空字符串，或不包含任何可校对的内容（例如， 仅包含空白或控制字符），则所得的校对文本应为 空字符串。在这种情况下，应忽略 includeCorrectionTypes、 includeCorrectionExplanations 和 correctionExplanationLanguage。
校对应遵循 includeCorrectionTypes 和 includeCorrectionExplanations 给出的指导。
校对过程必须遵循§ 4 隐私 考量和§ 5 安全考量中给出的指导，尤其 包括（但不限于）写作 辅助 API § 6.4 用户输入和写作 辅助 API § 7.2 运行时共享资源。
如果 correctionExplanationLanguage 不为 null，则更正说明应使用该 语言。否则，应使用 input 的语言。如果 input 包含多种语言，或无法检测 input 的语言，则更正说明语言可以是由实现定义的，或者实现可以 按照§ 3.5.4 错误中的指导，将其视为错误。
实现者应尽最大努力确保结果确实是 input 的校对结果，而不是由 input 提示产生的任意输出。
例如，如果 input 是 “
what is capital of France”，则回答此问题是不正确的， 例如输出“Paris is the capital of France.”。更正确的输出 例如应为“What is the capital of France?”。
3.5.2. 使用量
-
一个 字符串 input，
-
一个 boolean includeCorrectionTypes，
-
一个 boolean includeCorrectionExplanations，
-
一个 字符串或 null correctionExplanationLanguage，以及
-
一个算法 stopMeasuring，它不接受参数并返回一个 boolean，
执行以下步骤：
-
令 inputToModel 为给定 input、 includeCorrectionTypes、includeCorrectionExplanations 和 correctionExplanationLanguage 以进行校对时，将发送至 底层模型的由实现定义的字符串。
如果在此过程中 stopMeasuring 开始返回 true，则返回 null。
如果在此过程中发生错误，则按照 § 3.5.4 错误中的指导，返回适当的DOMException 错误信息。
-
返回将 inputToModel 提供给 底层模型时表示它所需的输入使用量。确切的计算过程是由实现定义的，但须遵守以下 约束。
返回的输入使用量必须是非负且有限的。如果校对过程没有使用量 配额，则它必须为 0。否则，它必须为正，并且应与 inputToModel 的长度大致 成正比。
这可能是按照某种语言模型 分词方案表示 input 所需的词元数量，也可能是 input 的长度。 它也可以是这些方式的某种变体，同时计算提供给模型所需的任何前缀或后缀的 使用量。
如果在此过程中 stopMeasuring 开始返回 true，则改为返回 null。
如果在此过程中发生错误，则改为按照 § 3.5.4 错误中的指导，返回适当的DOMException 错误信息。
3.5.3. 选项
校对算法的细节是 由实现定义的，因为它们预计由 AI 模型驱动。然而，它预期可由 Web 开发者通过 includeCorrectionTypes 和 includeCorrectionExplanations 标志来控制。
本节给出规范性指导，说明 校对的实现应如何使用每个 boolean 标志来指导校对过程。
| 值 | 含义 |
|---|---|
| "true" |
校对结果应包含一个纠正列表，其中每个由 startIndex 到 endIndex 的范围定义的 |
| "false" |
校对结果应包含一个纠正列表，其中每个由 startIndex 到 endIndex 的范围定义的 |
| 值 | 含义 |
|---|---|
| "true" |
校对结果应包含一个纠正列表，其中每个由 startIndex 到 endIndex 的范围定义的 |
| "false" |
校对结果应包含一个纠正列表，其中每个由 startIndex 到 endIndex 的范围定义的 |
与所有 "should" 级别的指导一样，用户代理 可能不会完全符合这些要求。特别是在为所有 纠正提供纠正类型的情况下，可以预期语言模型可能无法完全符合。
3.5.4. 错误
当校对失败时，以下可能的原因可以暴露给 Web 开发者。此表
列出了可能的 DOMException
name，以及实现应使用它们的情形：
DOMException
name
| 场景 |
|---|---|
"NotAllowedError"
|
校对因用户选择或用户代理策略而被禁用。 |
"NotSupportedError"
|
要校对的输入，或要提供的上下文，使用的是用户
代理不支持的语言，或者在调用 校对纠正解释语言最终使用了用户
代理不支持的语言（例如，因为用户代理尚未对该输出语言执行足够的质量
控制测试），或者在调用 includeCorrectionExplanations 被设置为 true， |
"UnknownError"
|
所有其他场景，包括用户代理认为它无法校对并同时满足 § 4 隐私考量或 § 5 安全考量中给出的要求的情况。或者，如果用户代理倾向于不 披露失败原因。 |
此表没有给出校对器 API 可能暴露的完整异常列表。 它只包含那些可能来自某些由实现定义的步骤的异常。
3.6. 权限策略集成
对校对器 API 的访问受 策略控制特性 "proofreader"
限制，该特性的默认允许列表为
'self'。
4. 隐私考量
关于 translator 和 language detector API 的隐私考量讨论，请参见 Writing Assistance APIs § 6 Privacy considerations。如 § 2 依赖项中所述， 该文本被编写为适用于所有共享相同 基础设施的 API。
5. 安全考量
关于 translator 和 language detector API 的安全考量讨论，请参见 Writing Assistance APIs § 7 Security considerations。如 § 2 依赖项中所述， 该文本被编写为适用于所有共享相同 基础设施的 API。