writing-assistance-apis

写作辅助 API

流程

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

1. 检查工作区，寻找浏览器入口、UI 处理程序以及现有的 AI 抽象层。
2. 如果有可用的 Node 运行时，执行 node scripts/find-writing-assistance-targets.mjs .，盘点可能的前端文件以及现有的 Summarizer、Writer 或 Rewriter 用法。
3. 如果没有可用的 Node 运行时，手动检查最近的 package.json、HTML 入口文件和框架引导文件，以确定浏览器应用的边界。
4. 如果工作区包含多个前端应用，优先选择包含当前路由、组件或用户所请求功能界面的应用。
5. 如果盘点后仍有多个可能的前端目标，请暂停并询问应将 Writing Assistance API 集成到哪个应用中。
6. 如果项目不是浏览器 Web 应用，请暂停并说明此技能不适用。

步骤 2：确认 API 是否可用，并选择合适的界面

1. 编写代码前，阅读 references/writing-assistance-reference.md。
2. 如果功能需要用于监控下载、批量输出、流式输出或取消操作的会话结构，请阅读 references/examples.md。
3. 如果涉及预览版标志、浏览器渠道、硬件要求或 iframe 限制，请阅读 references/compatibility.md。
4. 如果可用性检查、创建、流式处理或会话清理失败，请阅读 references/troubleshooting.md。
5. 确认功能在安全的 Window 上下文中运行，并且相关的 permissions-policy 功能允许当前框架访问。
6. 选择与任务相符的最精简界面：
   • Summarizer 用于总结文章、文档或对话。
   • Writer 用于根据简短提示词或写作任务生成新文本。
   • Rewriter 用于转换现有文本，同时保留其原意。
7. 如果功能必须在 worker 中、服务器上或通过远程模型提供商运行，请暂停并说明平台不匹配。
8. 如果项目使用 TypeScript，请添加或保留涵盖功能所用特定浏览器 API 的类型定义。

步骤 3：实现带保护措施的会话封装

1. 阅读 assets/writing-assistance-session.template.ts，并根据工作区的框架、状态模型和文件布局进行调整。
2. 使用运行时将采用的相同创建选项，通过 API 的 availability() 方法控制会话创建。
3. 将 availability() 视为功能检查，而非保证创建一定能成功；创建过程可能需要用户交互或下载时间。
4. 如果创建可能启动下载，只在用户激活后创建会话。
5. 如果 UI 需要显示下载进度，请在 create() 时使用 monitor 选项。
6. 对可取消的创建和运行调用使用 AbortController，并在不再需要会话时调用 destroy()。
7. 创建后不要更改选项；会话选项在每个实例中都是固定的，需要更改时应重新创建会话。
8. 如果功能位于跨源 iframe 中，请求为该框架所需的每个 API 显式授权。 步骤 4：接入 UX 和回退行为
9. 明确展示各种状态：API 缺失、设备不可用、模型可下载或正在下载、会话就绪、生成进行中，以及工作已中止。
10. 对于不受支持的浏览器、被阻止的框架，或不符合当前预览版要求的设备，保留非 AI 回退方案。
11. 如果源文本来自渲染后的页面内容，请在总结或改写前剥离或规范化 HTML。
12. 如果功能需要完整结果才能继续，请使用批处理方法；如果 UI 应逐步显示输出，请使用流式方法。
13. 仅在需要持久化的会话级指导时传递 sharedContext；仅在请求需要特定背景信息时传递每次调用的 context。
14. 如果功能依赖受支持的输入语言、上下文语言或输出语言，请明确指定语言选项。
15. 不要通过这些 API 处理通用聊天机器人、工具调用或开放式助手任务；如果任务不是总结、撰写或改写，请切换到 Prompt API 或其他获准的功能。

步骤 5：验证行为

1. 执行 node scripts/find-writing-assistance-targets.mjs .，确认预期的应用边界和 API 标记仍能解析到已编辑的集成范围。
2. 在排查更深层的运行时故障前，验证功能检测、安全上下文检查和 availability() 行为。
3. 如果功能同时提供两种模式，请至少测试一次批处理调用和一次流式调用。
4. 确认取消操作能干净地停止生成，且已销毁的会话不会被重复使用。
5. 如果目标环境依赖预览版浏览器标志或特定渠道行为，请先根据 references/compatibility.md 确认所需的浏览器状态，再将故障视为应用 bug。
6. 编辑后运行工作区构建、类型检查或测试。

错误处理

• 如果缺少 Summarizer、Writer 或 Rewriter，请保留非 AI 回退方案，并在更改产品逻辑前确认环境符合浏览器和预览版要求。
• 如果 availability() 返回 downloadable 或 downloading，在承诺生成已就绪前，要求用户主动创建会话。
• 如果 create() 抛出 NotAllowedError，请检查权限策略限制、下载操作缺少用户激活、浏览器策略限制或用户拒绝。
• 如果 create() 或运行调用抛出 NotSupportedError，请确保请求的语言、输出格式、摘要类型、语气或长度符合浏览器支持的组合。
• 如果调用抛出 QuotaExceededError，请缩减 sharedContext、每次调用的 context 或用户输入，然后重试。
• 如果功能必须在 worker 或服务器上下文中运行，请停止并说明 Writing Assistance API 是仅限 window 的浏览器 API。