prompt-api

Prompt API

流程

第 1 步：确定集成入口

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

第 2 步：确认 Prompt API 的可行性

1. 编写代码前，先阅读 references/prompt-api-reference.md。
2. 如果该功能需要符合规范的文本、多模态、前缀或启用工具的会话消息结构，请阅读 references/examples.md。
3. 如果该功能必须支持多个浏览器代际，或需要在原生支持与 polyfill 之间做出选择，请阅读 references/compatibility.md。
4. 如果该功能需要 Prompt API 或 Task API polyfill 的具体软件包安装或后端配置示例，请阅读 references/polyfills.md。
5. 确认该功能运行在安全的窗口上下文中，并且 language-model 权限策略允许从当前框架访问。
6. 如果集成必须在 Web Worker 或其他非窗口上下文中运行，请暂停并说明平台限制。
7. 选择该功能所需的会话形式：prompt()、promptStreaming()、initialPrompts、append()、measureContextUsage() 或 responseConstraint。如果该功能需要调用工具，请注意，规范将 tools 标记为 EXPERIMENTAL（仅限实验性上下文），必须通过功能检测进行限制，或仅用于源试用或扩展上下文。
8. 如果项目使用 TypeScript，请添加或保留涵盖项目所用 Prompt API 接口的类型定义。

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

1. 阅读 assets/language-model-service.template.ts，并根据工作区的框架、状态模型和文件布局进行调整。
2. 使用与功能运行时相同的创建选项（包括预期模态），通过 LanguageModel.availability() 限制会话创建。便携式页面代码不得将 tools 传递给 availability()，因为 tools 属于 EXPERIMENTAL。
3. 仅在用户激活后创建会话，因为此时可能会开始模型下载或实例化。
4. 对可取消的提示词使用 AbortController，并在不再需要会话时调用 destroy()。
5. 如果该功能运行在跨源 iframe 中，嵌入用的 iframe 必须设置 allow="language-model"。
6. 不要依赖 params()、topK 或 temperature；规范现将 topK 和 temperature 标记为 DEPRECATED（仅限扩展上下文），因此便携式网页集成不得依赖这些参数。
7. 将 availability() 视为被动的能力检查：如果它在用户激活前报告 downloading，不要据此断定当前页面启动了下载，也不要将 UI 锁定在应用已启动的忙碌状态。 步骤 4：接入 UX 和回退行为
8. 展示设备不可用、模型下载中、会话就绪和提示词处理中等不同状态。
9. 如果下载进度对该功能很重要，请在 LanguageModel.create() 期间附加 monitor 监听器，并在 UI 中显示进度。
10. 对于不受支持的浏览器、不受支持的设备或被阻止的 iframe 上下文，请保留非 AI 回退方案。
11. 如果该功能需要结构化输出，请通过 responseConstraint 传入 JSON Schema；仅当提示词已包含所需的格式说明时才使用 omitResponseConstraintInput，并在使用返回的字符串前对其进行解析。
12. 遵循提示词形态验证规则：system 消息应放在 initialPrompts 中，prefix: true 仅适用于最后一条 assistant 消息，且 assistant 消息内容必须始终为纯文本。
13. 如果应用调用 create() 之前 availability() 报告 downloading，应将其呈现为浏览器的信息状态，而非由页面发起的活动下载；除非应用自身正忙，否则应保持控件可用。

步骤 5：验证行为

1. 在适用时，使用 prompt() 测试短响应，并使用 promptStreaming() 测试长响应。
2. 验证重复提示词是否按预期复用上下文、已销毁的会话是否不会被复用，以及应用是否使用兼容性检查来处理不同浏览器版本中的上下文测量和溢出。
3. 如果集成抛出 NotSupportedError，或在不同 frame 或执行上下文中的行为有所不同，请阅读 references/troubleshooting.md。
4. 编辑后运行工作区构建、类型检查或测试。

错误处理

• 如果缺少 LanguageModel，优先采用渐进式增强，使用有维护的 Prompt API polyfill 或非 AI 回退方案，而不是自行设计兼容层。
• 如果应用调用 create() 之前 availability() 返回 downloading，请将其视为被动的浏览器状态。只有当应用自身已启动 LanguageModel.create() 时，才显示实时进度并阻止提示词提交。
• 如果 availability() 或 prompt() 抛出 NotSupportedError，请根据该功能实际使用的模态、语言和消息角色调整创建选项和提示词选项。如果向 availability() 或 create() 传入了 tools，请注意 tools 处于实验阶段，当前浏览器上下文可能不支持。
• 如果该功能必须在 Web Workers 中运行，请将集成改为在 window 上下文中运行，因为 workers 不支持 Prompt API。
• 如果该功能位于跨源 iframe 中，请先要求嵌入页面提供 allow="language-model"，再继续。
• 如果无法运行 node scripts/find-frontend-targets.mjs .，请手动确定浏览器应用边界，并仅在明确只有一个目标应用后继续。