校对器 API

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 时，下载校对器模型：

断言：这些步骤正在并行运行。
启动下载进程，以下载用户代理按 options 校对文本所需的一切内容。这可以包括基础 AI 模型、针对特定语言或选项值的微调，或其他资源。
如果下载进程因任何原因无法启动，则返回 false。
返回 true。

要在给定 ProofreaderCreateOptions options 时，初始化校对器模型：

断言：这些步骤正在并行运行。
对支持用户代理校对能力的 AI 模型执行任何必要的初始化操作。

这可以包括将模型加载到内存中，或加载支持 options 所表达的其他选项所必需的任何微调。
如果初始化因任何其他原因失败，则返回一个 DOMException 错误信息，其 name 为 "OperationError"，且其 details 包含适当的细节。
返回 null。

要在给定 realm realm 和 ProofreaderCreateOptions options 时，创建校对器对象：

断言：这些步骤正在 realm 的周围 agent 的事件循环上运行。
返回一个新的 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 » 时的最低可用性。

校对器非语言选项可用性，在给定 boolean includeCorrectionTypes 和 boolean includeCorrectionExplanations 时，由以下步骤给出。它们会返回一个 Availability 值或 null。

断言：此算法正在并行运行。
如果尝试确定用户代理是否能够支持校对文本时发生某种错误，并且用户代理认为该错误是暂时性的（使得重新查询可能不再产生这种错误），则返回 null。
如果用户代理当前支持按 includeCorrectionTypes 描述的是否包含纠正类型，以及按 includeCorrectionExplanations 描述的是否包含纠正解释来校对文本，则返回 "available"。
如果用户代理认为它将能够按 includeCorrectionTypes 和 includeCorrectionExplanations 支持校对文本，但只能在完成一个已经进行中的下载后支持，则返回 "downloading"。
如果用户代理认为它将能够按 includeCorrectionTypes 和 includeCorrectionExplanations 支持校对文本，但只能在执行一个当前尚未进行的下载后支持，则返回 "downloadable"。
否则，返回 "unavailable"。

校对器语言可用性二元组由以下步骤给出。它们会返回一个语言可用性二元组或 null。

断言：此算法正在并行运行。
如果尝试确定用户代理是否能够支持校对文本时发生某种错误，并且用户代理认为该错误是暂时性的（使得重新查询可能不再产生这种错误），则返回 null。
返回一个具有以下内容的语言可用性二元组：

输入语言

在给定用于校对以该语言编写的文本这一目的时，获取语言可用性分区的结果

纠正解释语言

在给定用该语言生成校对纠正的文本解释这一目的时，获取语言可用性分区的结果

当今软件中常见的一种设置是支持两种书面中文："traditional Chinese" 和 "simplified Chinese"。假设用户代理无需下载即可支持校对繁体中文文本，并在下载后支持简体中文。

实现这一点的一种方式可以是让校对器语言可用性二元组返回："zh-Hant" 位于输入语言["available"] 集合中，而 "zh" 和 "zh-Hans" 位于输入语言["downloadable"] 集合中。该返回值符合语言标签集合完备性规则的要求，因为它确保了存在 "zh"。按照 "should" 级别的指导，该实现已确定 "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 will best-fit to zh-Hant
await a("zh-HK") === "available";      // zh-HK will best-fit to zh-Hant
await a("zh-CN") === "downloadable";   // zh-CN will best-fit to zh-Hans

await a("zh-BR") === "downloadable";   // zh-BR will best-fit to zh
await a("zh-Kana") === "downloadable"; // zh-Kana will best-fit to zh

3.3. 语言可用性

语言可用性分区是一个映射，其键为 "downloading"、 "downloadable" 或 "available"，其值为由字符串组成的集合，这些字符串表示 Unicode 规范化的 locale 标识符。 [ECMA-402]

语言可用性二元组是一个结构体，具有以下项：

输入语言，一个语言可用性分区
纠正解释语言，一个语言可用性分区

要在给定用于检查语言可用性的目的描述 purpose 时，获取语言可用性分区：

令 partition 为 «[ "available" → 一个空集合，"downloading" → 一个空集合，"downloadable" → 一个空集合 ]»。
对于用户代理当前支持 purpose 的每一种人类语言 languageTag（表示为 Unicode 规范化的 locale 标识符），对每个执行：
1. 将 languageTag 追加到 partition["available"]。
对于用户代理认为它将能够支持 purpose，但只能在完成一个已经进行中的下载后支持的每一种人类语言 languageTag（表示为 Unicode 规范化的 locale 标识符），对每个执行：
1. 将 languageTag 追加到 partition["downloading"]。
对于用户代理认为它将能够支持 purpose，但只能在执行一个当前尚未进行的下载后支持的每一种人类语言 languageTag（表示为 Unicode 规范化的 locale 标识符），对每个执行：
1. 将 languageTag 追加到 partition["downloadable"]。
断言：partition["available"]、 partition["downloading"] 和 partition["downloadable"] 互不相交。
如果 partition["available"]、 partition["downloading"] 和 partition["downloadable"] 的并集不满足语言标签集合完备性规则，则：
1. 令 missingLanguageTags 为使该并集满足语言标签集合完备性规则所必需的缺失语言标签集合。
2. 对于每个 missingLanguageTags 中的 languageTag：
3. 将 languageTag 追加到三个集合之一。追加到哪个集合是由实现定义的，并且应当由类似于 LookupMatchingLocaleByBestFit 的考量来指导，以保持“最佳回退语言”在一起。
4. 返回 partition。

要在给定由字符串组成的有序集合 requestedLanguages 和一个语言可用性分区 partition 时，计算语言可用性，执行以下步骤。它们会返回一个 Availability 值，并会就地改变 requestedLanguages，以将语言标签更新为其最佳匹配。

令 availability 为 "available"。
对于每个 requestedLanguages 中的 language：
1. 令 unavailable 为 true。
2. 对于每个 « "available"、 "downloading"、 "downloadable" » 中的 availabilityToCheck：
3. 令 languagesWithThisAvailability 为 partition[availabilityToCheck]。
4. 令 bestMatch 为 LookupMatchingLocaleByBestFit(languagesWithThisAvailability, « language »)。
5. 如果 bestMatch 不是 undefined，则：
  1. 用 bestMatch.[[locale]] 替换 requestedLanguages 中的 language。
  2. 将 availability 设置为在给定 availability 和 availabilityToCheck 时的最低可用性。
  3. 将 unavailable 设置为 false。
  4. 中断。
6. 如果 unavailable 为 true，则返回 "unavailable"。
返回 availability。

3.4. `Proofreader` 类

每个 Proofreader 都有一个 include correction type，它是一个 boolean，或默认值为 false，在创建期间设置。

每个 Proofreader 都有一个 include correction explanations，它是一个 boolean，或默认值为 false，在创建期间设置。

每个 Proofreader 都有一个 expected input languages，它是一个 FrozenArray<DOMString> 或 null，在创建期间设置。

每个 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 是一个错误信息，则：
1. 用 requested 执行 error。
2. 返回。
断言：requested 是一个数字。
以由实现定义的方式，在遵守以下指南的前提下，开始将 input 校对为一个 ProofreadResult 的过程，其中包含作为已校对文本的字符串 correctedInput，以及一个 ProofreadCorrection corrections，用于详细说明为形成 correctedInput 而对 input 所作的所有纠正。

如果 input 是空字符串，或以其他方式不包含可校对内容（例如，只包含空白，或控制字符），则生成的校对文本应为空字符串。在这种情况下，includeCorrectionTypes、 includeCorrectionExplanations 和 correctionExplanationLanguage 应被忽略。

校对应符合由 includeCorrectionTypes 和 includeCorrectionExplanations 给出的指导。

校对过程必须符合 § 4 隐私考量和 § 5 安全考量中给出的指导，特别是包括（但不限于）Writing Assistance APIs § 6.4 User input 和 Writing Assistance APIs § 7.2 Runtime shared resources。

如果 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?"。
1. 等待下一块校对数据被生成、校对过程完成，或调用 stopProducing 的结果变为 true。
2. 如果成功生成了这样的一个块：
3. 令它表示为一个字符串 chunk。
4. 用 chunk 执行 chunkProduced。
5. 否则，如果校对过程已经完成：
6. 执行 done。
7. 中断。
8. 否则，如果 stopProducing 返回 true，则中断。
9. 否则，如果校对期间发生错误：
10. 令该错误按照 § 3.5.4 错误中的指导表示为错误信息 errorInfo。
11. 用 errorInfo 执行 error。
12. 中断。

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 所需的 token 数量，也可能是 input 的长度。它也可以是这些方案的某种变体，其中还会计算为给予模型而必要的任何前缀或后缀的使用量。

如果在此过程中 stopMeasuring 开始返回 true，则改为返回 null。

如果在此过程中发生错误，则按照 § 3.5.4 错误中的指导，改为返回适当的 DOMException 错误信息。

3.5.3. 选项

校对算法的细节是由实现定义的，因为它们预计由 AI 模型驱动。然而，它预期可由 Web 开发者通过 includeCorrectionTypes 和 includeCorrectionExplanations 标志来控制。

本节给出规范性指导，说明校对的实现应如何使用每个 boolean 标志来指导校对过程。

`includeCorrectionTypes` 值
值	含义
"true"	校对结果应包含一个纠正列表，其中每个由 `startIndex` 到 `endIndex` 的范围定义的 `ProofreadCorrection` 都应按 `CorrectionType` 枚举描述被纠正的错误类型。
"false"	校对结果应包含一个纠正列表，其中每个由 `startIndex` 到 `endIndex` 的范围定义的 `ProofreadCorrection` 不提供被纠正的错误类型。

`includeCorrectionExplanations` 值
值	含义
"true"	校对结果应包含一个纠正列表，其中每个由 `startIndex` 到 `endIndex` 的范围定义的 `ProofreadCorrection` 都应为被纠正的错误提供文本解释。
"false"	校对结果应包含一个纠正列表，其中每个由 `startIndex` 到 `endIndex` 的范围定义的 `ProofreadCorrection` 不提供被纠正错误的文本解释。

与所有 "should" 级别的指导一样，用户代理可能不会完全符合这些要求。特别是在为所有纠正提供纠正类型的情况下，可以预期语言模型可能无法完全符合。

3.5.4. 错误

当校对失败时，以下可能的原因可以暴露给 Web 开发者。此表列出了可能的 DOMException name，以及实现应使用它们的情形：

`DOMException` name	场景
"`NotAllowedError`"	校对因用户选择或用户代理策略而被禁用。
"`NotSupportedError`"	要校对的输入，或要提供的上下文，使用的是用户代理不支持的语言，或者在调用 `create()` 时未被正确提供。校对纠正解释语言最终使用了用户代理不支持的语言（例如，因为用户代理尚未对该输出语言执行足够的质量控制测试），或者在调用 `create()` 时未被正确提供。 `includeCorrectionExplanations` 被设置为 true，`correctionExplanationLanguage` 选项未设置，并且输入文本的语言无法确定，因此用户代理没有可用的良好纠正解释语言默认值。
"`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。

校对器 API

摘要

此文档的状态

1. 简介

2. 依赖项

3. 校对器 API

3.1. 创建

3.2. 可用性

3.3. 语言可用性

3.4. `Proofreader` 类

3.5. 校对

3.5.1. 算法

3.5.2. 使用量

3.5.3. 选项

3.5.4. 错误

3.6. 权限策略集成

4. 隐私考量

5. 安全考量

一致性

文档约定

索引

由本规范定义的术语

由引用定义的术语

参考文献

规范性参考文献

IDL 索引

校对器 API

摘要

此文档的状态

1. 简介

2. 依赖项

3. 校对器 API

3.1. 创建

3.2. 可用性

3.3. 语言可用性

3.4. Proofreader 类

3.5. 校对

3.5.1. 算法

3.5.2. 使用量

3.5.3. 选项

3.5.4. 错误

3.6. 权限策略集成

4. 隐私考量

5. 安全考量

一致性

文档 约定

索引

由本 规范定义的术语

由 引用定义的术语

参考文献

规范性参考文献

IDL 索引

3.4. `Proofreader` 类

文档约定

由本规范定义的术语

由引用定义的术语