proofreader-api

Proofreader API

流程

步骤 1：确定浏览器集成界面

1. 检查工作区中的浏览器入口、编辑器或表单 UI 处理程序，以及任何现有的内置 AI 抽象层。
2. 如果有 Node 运行时，执行 node scripts/find-proofreader-targets.mjs .，盘点可能的前端文件和现有的 Proofreader API 标记。
3. 如果没有 Node 运行时，手动检查最近的 package.json、HTML 入口点和框架引导文件，以确定浏览器应用边界。
4. 如果工作区包含多个前端应用，优先选择包含当前文本输入路由、编辑器组件或用户指定校对界面的应用。
5. 如果盘点后仍有多个可能的前端目标，请停止并询问应将 Proofreader API 集成到哪个应用中。
6. 如果项目不是浏览器 Web 应用，请停止并说明此技能不适用。

步骤 2：确认 API 是否可用及选项形状

1. 编写代码前，阅读 references/proofreader-reference.md。
2. 如果功能需要创建会话、监控下载、渲染结果或进行配额感知预检，请阅读 references/examples.md。
3. 如果预览标志、浏览器渠道、硬件要求、iframe 限制或特定浏览器的选项缺失会产生影响，请阅读 references/compatibility.md。
4. 如果功能检测、可用性检查、创建会话或校对失败，请阅读 references/troubleshooting.md。
5. 确认功能在安全的 Window 上下文中运行，且当前框架获准使用 proofreader permissions-policy 功能。
6. 严格匹配 availability() 和 create() 的选项形状，尤其是在目标浏览器支持时，匹配 expectedInputLanguages、includeCorrectionTypes、includeCorrectionExplanations 和 correctionExplanationLanguage。
7. 如果功能必须在 worker、服务器或通用文本生成接口中运行，请停止并说明平台不匹配。
8. 如果项目使用 TypeScript，请添加或保留仅涵盖该功能实际使用的 Proofreader API 接口的类型定义。

步骤 3：实现带保护措施的校对器封装

1. 阅读 assets/proofreader-session.template.ts，并根据工作区中的框架、状态模型和文件布局进行调整。
2. 使用与运行时会话相同的非瞬态创建选项，通过 Proofreader.availability() 控制会话创建。
3. 将 availability() 视为能力检查，而非创建一定会成功的保证；创建仍可能需要用户激活、下载时间或策略批准。
4. 如果目标浏览器可能需要启动模型下载，请仅在用户激活后创建会话。
5. 如果 UI 需要显示下载进度，请在调用 create() 时使用 monitor 选项。
6. 对可取消的创建或校对调用使用 AbortController；校对 UI 不再需要会话时，调用 destroy()。
7. 创建后，如果行为取决于选项，请重新创建会话，而不要修改选项；会话选项在每个实例中固定。
8. 如果任务需要更正标签或解释，请明确处理特定浏览器的回退方案，不要假设每个预览版本都实现了完整的规范选项集。 第 4 步：接入 UX 和结果处理
9. 展示不同状态，包括 API 缺失、设备不可用、模型可下载或正在下载、会话就绪、校对进行中、工作已取消以及严重失败。
10. 对于不受支持的浏览器、被阻止的框架或不符合当前预览要求的设备，保留非 AI 回退方案。
11. 如果产品需要展示差异或支持选择性接受，请同时呈现 correctedInput 和结构化的 corrections 数组。
12. 只有在功能需要配额感知行为或大输入预检查时，才在耗时的校对操作前调用 measureInputUsage()。
13. 如果功能依赖受支持的语言路由，请明确指定预期的输入语言。
14. 不要将 Proofreader 用作通用聊天、摘要或改写界面；如果任务不是校对，请改用正确的内置 API。

第 5 步：验证行为

1. 执行 node scripts/find-proofreader-targets.mjs .，确认预期的应用边界和 Proofreader 标记仍指向已编辑的集成界面。
2. 在排查更深层的运行时故障之前，先验证功能检测、安全上下文检查、权限策略访问权限以及 availability() 行为。
3. 使用生产环境中的确切选项测试会话创建；如果环境需要初次下载模型，还要处理下载进度。
4. 确认 proofread() 会针对具有代表性的用户文本返回预期的 correctedInput 和修正范围。
5. 如果集成使用 measureInputUsage()，请确认在浏览器因配额问题报错前，大输入会被拒绝或截短。
6. 确认取消操作能干净地停止工作，并且已销毁的会话不会被重新使用。
7. 如果目标环境依赖预览标志、Origin Trials 或特定通道行为，请先根据 references/compatibility.md 确认所需的浏览器状态，再将故障视为应用程序错误。
8. 编辑后运行工作区构建、类型检查或测试。

错误处理

• 如果缺少 Proofreader，请保留非 AI 回退方案，并确认环境满足安全上下文、浏览器和预览要求，然后再更改产品逻辑。
• 如果 availability() 返回 downloadable 或 downloading，在承诺校对功能已就绪前，必须由用户主动创建会话。
• 如果 create() 或 proofread() 抛出 NotAllowedError，请检查权限策略限制、下载操作缺少用户激活、浏览器策略限制或用户拒绝。
• 如果 create() 或 proofread() 抛出 NotSupportedError，请确保请求的语言和选项组合受浏览器支持，并移除不受支持的仅预览假设。
• 如果创建时出现 OperationError、UnknownError 或其他运行时异常，只有在确认设备资格、存储空间和浏览器标志仍符合 references/compatibility.md 后，才重试一次。
• 如果功能必须在 Worker 或服务器上下文中运行，请停止操作并说明 Proofreader API 仅适用于窗口中的浏览器环境。