proofreader-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Proofreader API

Procedures

操作流程

Step 1: Identify the browser integration surface

Inspect the workspace for browser entry points, editor or form UI handlers, and any existing built-in AI abstraction layer.
Execute
```
node scripts/find-proofreader-targets.mjs .
```
to inventory likely frontend files and existing Proofreader API markers when a Node runtime is available.
If a Node runtime is unavailable, inspect the nearest
```
package.json
```
, HTML entry point, and framework bootstrap files manually to identify the browser app boundary.
If the workspace contains multiple frontend apps, prefer the app that contains the active text-entry route, editor component, or user-requested proofreading surface.
If the inventory still leaves multiple plausible frontend targets, stop and ask which app should receive the Proofreader API integration.
If the project is not a browser web app, stop and explain that this skill does not apply.

Step 2: Confirm API viability and option shape

Read
```
references/proofreader-reference.md
```
before writing code.
Read
```
references/examples.md
```
when the feature needs session creation, download monitoring, result rendering, or quota-aware preflight.
Read
```
references/compatibility.md
```
when preview flags, browser channels, hardware requirements, iframe constraints, or browser-specific option gaps matter.
Read
```
references/troubleshooting.md
```
when feature detection, availability, creation, or proofreading fails.
Verify that the feature runs in a secure
```
Window
```
context and that the current frame is allowed to use the
```
proofreader
```
permissions-policy feature.

Match

availability()

and

create()

option shapes exactly, especially for

expectedInputLanguages

includeCorrectionTypes

includeCorrectionExplanations

, and

correctionExplanationLanguage

when the target browser supports them.

If the feature must run in a worker, on the server, or through a generic text-generation interface, stop and explain the platform mismatch.
If the project uses TypeScript, add or preserve typings that cover only the Proofreader API surface actually used by the feature.

Step 3: Implement a guarded proofreader wrapper

Read
```
assets/proofreader-session.template.ts
```
and adapt it to the framework, state model, and file layout in the workspace.
Gate session creation behind
```
Proofreader.availability()
```
using the same non-transient create options that the runtime session will use.
Treat
```
availability()
```
as a capability check, not a guarantee that creation will succeed without user activation, download time, or policy approval.
Create sessions only after user activation when the target browser may need to start a model download.
Use the
```
monitor
```
option during
```
create()
```
when the UI needs download progress.
Use
```
AbortController
```
for cancelable create or proofread calls, and call
```
destroy()
```
when the proofreading UI no longer needs the session.
Recreate the session instead of mutating option-dependent behavior after creation; session options are fixed per instance.
If the task requires correction labels or explanations, keep browser-specific fallbacks explicit instead of assuming every preview implements the full specification option set.

Step 4: Wire UX and result handling

Surface distinct states for missing APIs, unavailable devices, downloadable or downloading models, ready sessions, in-flight proofreading, canceled work, and hard failures.
Keep a non-AI fallback for unsupported browsers, blocked frames, or devices that do not meet the current preview requirements.
Render both
```
correctedInput
```
and the structured
```
corrections
```
array when the product needs visible diffs or selective acceptance.
Use
```
measureInputUsage()
```
before expensive proofreading only when the feature needs quota-aware behavior or large-input preflight.
Keep expected input languages explicit when the feature depends on supported language routing.
Do not use Proofreader as a general chat, summarization, or rewriting surface; switch to the correct built-in API when the task is not proofreading.

Step 5: Validate behavior

Execute
```
node scripts/find-proofreader-targets.mjs .
```
to confirm that the intended app boundary and Proofreader markers still resolve to the edited integration surface.
Verify feature detection, secure-context checks, permissions-policy access, and
```
availability()
```
behavior before debugging deeper runtime failures.
Test session creation with the exact options used in production, including download progress handling when the environment needs an initial model download.
Confirm that
```
proofread()
```
returns the expected
```
correctedInput
```
and correction ranges for representative user text.
If the integration uses
```
measureInputUsage()
```
, confirm that large inputs are rejected or trimmed before the browser throws quota-related failures.
Confirm that cancellation stops work cleanly and that destroyed sessions are not reused.
If the target environment depends on preview flags, origin trials, or channel-specific behavior, confirm the required browser state from
```
references/compatibility.md
```
before treating failures as application bugs.
Run the workspace build, typecheck, or tests after editing.

步骤1：识别浏览器集成边界

检查工作区中的浏览器入口点、编辑器或表单UI处理程序，以及任何现有的内置AI抽象层。
当有可用Node运行时环境时，执行
```
node scripts/find-proofreader-targets.mjs .
```
来统计可能的前端文件和现有Proofreader API标记。
若没有可用Node运行时环境，手动检查最近的
```
package.json
```
、HTML入口文件、框架启动文件，确定浏览器应用的边界。
如果工作区包含多个前端应用，优先选择包含活跃文本输入路由、编辑器组件或用户指定校对界面的应用。
如果统计后仍存在多个可能的前端目标，停止操作并询问需要为哪个应用集成Proofreader API。
如果项目不是浏览器Web应用，停止操作并说明该技能不适用。

步骤2：确认API可行性与选项结构

编写代码前先阅读
```
references/proofreader-reference.md
```
。
如果功能需要创建会话、下载监控、结果渲染或配额感知预检，请阅读
```
references/examples.md
```
。
如果需要考虑预览标识、浏览器渠道、硬件要求、iframe约束或浏览器特有的选项差异，请阅读
```
references/compatibility.md
```
。
如果遇到功能检测、可用性、创建或校对失败的问题，请阅读
```
references/troubleshooting.md
```
。
验证功能运行在安全的
```
Window
```
上下文内，且当前框架被允许使用
```
proofreader
```
权限策略特性。

严格匹配

availability()

和

create()

的选项结构，尤其是目标浏览器支持的

expectedInputLanguages

、

includeCorrectionTypes

、

includeCorrectionExplanations

和

correctionExplanationLanguage

参数。

如果功能必须运行在Worker、服务端或通过通用文本生成接口运行，停止操作并说明平台不匹配。
如果项目使用TypeScript，添加或保留仅覆盖功能实际使用的Proofreader API接口的类型定义。

步骤3：实现带防护的校对器封装

阅读
```
assets/proofreader-session.template.ts
```
，并适配工作区中的框架、状态模型和文件布局。
使用运行时会话会用到的非临时创建参数，通过
```
Proofreader.availability()
```
来控制会话创建逻辑。
将
```
availability()
```
视为能力检查，而不是创建会话的保证，创建仍可能因用户未激活、模型下载耗时、策略未批准等原因失败。
当目标浏览器可能需要启动模型下载时，仅在用户激活后再创建会话。
当UI需要展示下载进度时，在
```
create()
```
调用中使用
```
monitor
```
选项。
使用
```
AbortController
```
实现可取消的创建或校对调用，在校对UI不再需要会话时调用
```
destroy()
```
。
会话创建后不要修改依赖选项的行为，而是重新创建会话；每个实例的会话选项是固定的。
如果任务需要更正标签或说明，请明确添加浏览器特有的降级逻辑，不要假设所有预览版本都实现了完整的规范选项集。

步骤4：对接UX与结果处理逻辑

对外展示不同的状态：API缺失、设备不可用、模型可下载/下载中、会话就绪、校对中、任务已取消、严重故障。
为不支持的浏览器、被阻止的框架或不符合当前预览要求的设备保留非AI降级方案。
当产品需要展示可见差异或选择性接受更正时，同时渲染
```
correctedInput
```
和结构化的
```
corrections
```
数组。
仅当功能需要配额感知行为或大输入预检时，在执行耗时的校对操作前调用
```
measureInputUsage()
```
。
当功能依赖支持的语言路由时，明确指定预期的输入语言。
不要将Proofreader用作通用聊天、摘要或改写工具；如果任务不是校对，请切换到合适的内置API。

步骤5：验证行为

执行
```
node scripts/find-proofreader-targets.mjs .
```
，确认预期的应用边界和Proofreader标记仍能解析到编辑后的集成界面。
在调试更深入的运行时故障前，先验证功能检测、安全上下文检查、权限策略访问和
```
availability()
```
的行为是否正常。
使用生产环境完全相同的选项测试会话创建，包括环境需要首次下载模型时的下载进度处理逻辑。
确认
```
proofread()
```
针对代表性用户文本返回预期的
```
correctedInput
```
和更正范围。
如果集成使用了
```
measureInputUsage()
```
，确认大输入会被拒绝或裁剪，避免浏览器抛出配额相关故障。
确认取消操作可以正常终止任务，已销毁的会话不会被复用。
如果目标环境依赖预览标识、Origin Trials或渠道特定行为，在将故障判定为应用bug前，先从
```
references/compatibility.md
```
确认所需的浏览器状态是否符合要求。
编辑完成后运行工作区的构建、类型检查或测试流程。

Error Handling

错误处理

If
```
Proofreader
```
is missing, keep a non-AI fallback and confirm that the environment satisfies the secure-context, browser, and preview requirements before changing product logic.
If
```
availability()
```
returns
```
downloadable
```
or
```
downloading
```
, require user-driven session creation before promising that proofreading is ready.
If
```
create()
```
or
```
proofread()
```
throws
```
NotAllowedError
```
, check permissions-policy constraints, missing user activation for downloads, browser policy restrictions, or user rejection.
If
```
create()
```
or
```
proofread()
```
throws
```
NotSupportedError
```
, align the requested languages and option set with the browser's supported combinations and remove unsupported preview-only assumptions.
If creation fails with
```
OperationError
```
,
```
UnknownError
```
, or another runtime exception, retry once only after confirming that device eligibility, storage, and browser flags still match
```
references/compatibility.md
```
.
If the feature must run in a worker or server context, stop and explain that the Proofreader API is a window-only browser API.

如果
```
Proofreader
```
不存在，保留非AI降级方案，在修改产品逻辑前先确认环境满足安全上下文、浏览器和预览要求。
如果
```
availability()
```
返回
```
downloadable
```
或
```
downloading
```
，在承诺校对功能就绪前，要求用户主动触发会话创建。
如果
```
create()
```
或
```
proofread()
```
抛出
```
NotAllowedError
```
，检查权限策略约束、下载缺少用户激活、浏览器策略限制或用户拒绝授权的情况。
如果
```
create()
```
或
```
proofread()
```
抛出
```
NotSupportedError
```
，将请求的语言和选项集与浏览器支持的组合对齐，移除仅预览版支持的不合理假设。
如果创建失败并返回
```
OperationError
```
、
```
UnknownError
```
或其他运行时异常，仅在确认设备 eligibility、存储和浏览器标识仍符合
```
references/compatibility.md
```
要求后重试一次。
如果功能必须运行在Worker或服务端上下文，停止操作并说明Proofreader API是仅支持Window上下文的浏览器API。