writing-assistance-apis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Assistance APIs

Procedures

操作流程

Step 1: Identify the browser integration surface

Inspect the workspace for browser entry points, UI handlers, and any existing AI abstraction layer.
Execute
```
node scripts/find-writing-assistance-targets.mjs .
```
to inventory likely frontend files and existing Summarizer, Writer, or Rewriter usage 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 route, component, or user-requested feature surface.
If the inventory still leaves multiple plausible frontend targets, stop and ask which app should receive the Writing Assistance 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 choose the right surface

Read

references/writing-assistance-reference.md

before writing code.

Read
```
references/examples.md
```
when the feature needs a session shape for monitoring downloads, batch output, streaming output, or cancellation.
Read
```
references/compatibility.md
```
when preview flags, browser channels, hardware requirements, or iframe constraints matter.
Read
```
references/troubleshooting.md
```
when availability checks, creation, streaming, or session cleanup fail.
Verify that the feature runs in a secure
```
Window
```
context and that the relevant permissions-policy feature allows access from the current frame.
Choose the narrowest surface that matches the task:
- ```
Summarizer
```
  for article, document, or conversation summaries.
- ```
Writer
```
  for generating new text from a short prompt or writing task.
- ```
Rewriter
```
  for transforming existing text while preserving its intent.
If the feature must run in a worker, on the server, or against a remote model provider, stop and explain the platform mismatch.
If the project uses TypeScript, add or preserve typings that cover the specific browser APIs used by the feature.

Step 3: Implement a guarded session wrapper

Read
```
assets/writing-assistance-session.template.ts
```
and adapt it to the framework, state model, and file layout in the workspace.
Gate session creation behind the API's
```
availability()
```
method using the same create options that will be used at runtime.
Treat
```
availability()
```
as a capability check, not a guarantee that creation will succeed without user interaction or download time.
Create sessions only after user activation when creation may initiate a download.
Use the
```
monitor
```
option during
```
create()
```
when the UI needs download progress.
Use
```
AbortController
```
for cancelable create and run calls, and call
```
destroy()
```
when the session is no longer needed.
Recreate the session instead of mutating options after creation; session options are fixed per instance.
If the feature lives in a cross-origin iframe, require explicit delegation for each API that the frame needs.

Step 4: Wire UX and fallback behavior

Surface distinct states for missing APIs, unavailable devices, downloadable or downloading models, ready sessions, in-flight generation, and aborted work.
Keep a non-AI fallback for unsupported browsers, blocked frames, or devices that do not meet the current preview requirements.
Strip or normalize HTML before summarization or rewriting when the source text comes from rendered page content.
Use the batch methods when the feature needs the full result before continuing, and use the streaming methods when the UI should reveal output incrementally.
Pass
```
sharedContext
```
only for persistent session-wide guidance, and pass per-call
```
context
```
only for request-specific background detail.
Keep language options explicit when the feature depends on supported input, context, or output languages.
Do not route generic chatbot, tool-calling, or open-ended assistant tasks through these APIs; switch to the Prompt API or another approved capability when the task is not summarization, writing, or rewriting.

Step 5: Validate behavior

Execute
```
node scripts/find-writing-assistance-targets.mjs .
```
to confirm that the intended app boundary and API markers still resolve to the edited integration surface.
Verify feature detection, secure-context checks, and
```
availability()
```
behavior before debugging deeper runtime failures.
Test at least one batch call and one streaming call when the feature exposes both modes.
Confirm that cancellation stops generation cleanly and that destroyed sessions are not reused.
If the target environment depends on preview browser flags 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-writing-assistance-targets.mjs .
```
来清点所有可能的前端文件，以及现有Summarizer、Writer或Rewriter的使用情况。
若没有Node运行时环境，手动检查就近的
```
package.json
```
、HTML入口文件以及框架启动文件，确定浏览器应用的边界。
如果工作区包含多个前端应用，优先选择包含活跃路由、组件或者用户需求功能模块的应用。
如果清点后仍然存在多个可能的前端目标，暂停操作并询问需要将Writing Assistance API集成到哪个应用中。
如果项目不是浏览器Web应用，暂停操作并说明本指南不适用于该场景。

步骤2：确认API可行性并选择合适的功能模块

编写代码前请先阅读

references/writing-assistance-reference.md

。

如果功能需要监控下载、批量输出、流式输出或者取消功能的会话形态，请阅读
```
references/examples.md
```
。
如果涉及预览标志、浏览器渠道、硬件要求或者iframe约束相关问题，请阅读
```
references/compatibility.md
```
。
如果遇到可用性检查、创建、流式输出或者会话清理失败的问题，请阅读
```
references/troubleshooting.md
```
。
确认功能运行在安全的
```
Window
```
上下文中，且相关权限策略功能允许当前框架访问API。
选择匹配任务的最小范围功能模块：
- 针对文章、文档或者对话总结场景使用
```
Summarizer
```
- 针对通过短提示或写作任务生成新文本的场景使用
```
Writer
```
- 针对保留原意改写现有文本的场景使用
```
Rewriter
```
如果功能必须运行在Worker、服务端或者对接远程模型提供商，暂停操作并说明平台不匹配。
如果项目使用TypeScript，添加或保留覆盖功能所用特定浏览器API的类型定义。

步骤3：实现带防护的会话封装

阅读
```
assets/writing-assistance-session.template.ts
```
，并根据工作区的框架、状态模型和文件布局进行适配。
使用运行时相同的创建参数，通过API的
```
availability()
```
方法对会话创建进行前置校验。
将
```
availability()
```
视为能力检查，不能保证后续创建一定成功，可能需要用户交互或等待模型下载时间。
当创建会话可能触发下载时，仅在用户激活后再执行创建操作。
如果UI需要展示下载进度，在
```
create()
```
时传入
```
monitor
```
参数。
对可取消的创建和执行调用使用
```
AbortController
```
，不再需要会话时调用
```
destroy()
```
方法。
会话创建后选项不可修改，需要修改选项时请重新创建会话，不要直接修改现有会话的参数。
如果功能位于跨域iframe中，需要为框架所需的每个API申请显式权限委托。

步骤4：对接UX和降级逻辑

为不同场景展示对应的状态：API缺失、设备不可用、模型可下载/下载中、会话就绪、生成中、任务已终止。
为不支持的浏览器、被拦截的框架或者不满足当前预览要求的设备提供非AI降级方案。
当源文本来自渲染后的页面内容时，在总结或改写前对HTML进行清理或标准化处理。
如果功能需要获取完整结果后再继续执行，使用批量方法；如果UI需要逐步展示输出，使用流式方法。
```
sharedContext
```
仅用于传递会话级的持久指引，单请求专属的背景信息仅通过单次调用的
```
context
```
参数传递。
如果功能依赖特定的输入、上下文或输出语言，请显式设置语言选项。
不要通过这些API处理通用聊天机器人、工具调用或者开放式助手任务；如果任务不属于总结、写作或改写场景，请切换到Prompt API或其他获批的能力。

步骤5：验证功能行为

执行
```
node scripts/find-writing-assistance-targets.mjs .
```
，确认目标应用边界和API标记仍然匹配修改后的集成范围。
在调试深层运行时故障前，先验证特征检测、安全上下文检查和
```
availability()
```
的行为是否符合预期。
如果功能同时支持两种模式，至少测试一次批量调用和一次流式调用。
确认取消操作可以正常终止生成，已销毁的会话不会被复用。
如果目标环境依赖预览浏览器标志或特定渠道的行为，在将故障判定为应用bug前，先参考
```
references/compatibility.md
```
确认所需的浏览器状态。
修改完成后运行工作区的构建、类型检查或测试流程。

Error Handling

错误处理

If
```
Summarizer
```
,
```
Writer
```
, or
```
Rewriter
```
is missing, keep a non-AI fallback and confirm that the environment satisfies the browser and preview requirements before changing product logic.
If
```
availability()
```
returns
```
downloadable
```
or
```
downloading
```
, require user-driven session creation before promising that generation is ready.
If
```
create()
```
throws
```
NotAllowedError
```
, check permissions-policy constraints, missing user activation for downloads, browser policy restrictions, or user rejection.
If
```
create()
```
or a run call throws
```
NotSupportedError
```
, align the requested languages, output format, summary type, tone, or length with the browser's supported combinations.
If a call throws
```
QuotaExceededError
```
, shrink
```
sharedContext
```
, per-call
```
context
```
, or the user input before retrying.
If the feature must run in a worker or server context, stop and explain that the Writing Assistance APIs are window-only browser APIs.

如果
```
Summarizer
```
、
```
Writer
```
或
```
Rewriter
```
缺失，请保留非AI降级方案，在修改产品逻辑前先确认环境满足浏览器和预览要求。
如果
```
availability()
```
返回
```
downloadable
```
或
```
downloading
```
，在承诺生成功能可用前，需要引导用户主动触发会话创建。
如果
```
create()
```
抛出
```
NotAllowedError
```
，请检查权限策略约束、下载缺少用户激活、浏览器策略限制或者用户拒绝授权等情况。
如果
```
create()
```
或执行调用抛出
```
NotSupportedError
```
，请将请求的语言、输出格式、摘要类型、语气或长度调整为浏览器支持的组合。
如果调用抛出
```
QuotaExceededError
```
，请在重试前缩小
```
sharedContext
```
、单次调用
```
context
```
或者用户输入的大小。
如果功能必须运行在Worker或服务端上下文，暂停操作并说明Writing Assistance APIs是仅适用于Window上下文的浏览器API。