结果交付、诊断与运行维护

返回开发指南 · Core API · Support API

每次运行的边界

启动期清单与每请求状态分开。为每次请求建立身份、允许资料视图、AbortSignal、模型／工具预算、来源与输出状态。连接 Provider 的凭据、端点、模型特性和错误映射由 App 服务端管理，不让用户材料或模型参数覆盖这些配置。

分别考虑轮次、模型调用次数、超时、消息与输出字符、schema 大小和业务工具配额。修正、复核和 fallback 也消耗预算；不能因为一个步骤叫“恢复”就无限重试。Core 的模型调用预算只覆盖实际经该 runner 的调用，外部 HTTP、后台作业及 App 自行调用模型要自行限制。

取消必须传到实际模型和业务 I/O；对已开始的写操作，取消不表示回滚。App 应能凭幂等键／真实回执判断是否已执行，重试前查询状态。同步 ToolRegistry 不会等待任意 Promise，异步业务应放在适合的异步 handler／节点中，不伪装同步成功。

先验证事实，再形成可展示输出

已解析的模型提议
  → 授权和真实执行
  → 输入输出合同及来源检查
  → 生成候选答复
  → 完整性／业务事实检查
  → 程序绑定来源、动作状态与链接
  → 按 App 选择的形式交付

Knowledge Snapshot 是来源引用，工具事件是执行记录，模型文字是候选解释，三者不互相替代。Answering 的任务、checks 和有界修正帮助组织该链；具体事实检查由 App 提供。相关局部合同见知识回答 API。

Presentation／Interaction 是可选 Kit。InteractionProtocol／CommandCatalog 不决定 App 前后端数据交换方式；使用时由 App 登记命令、解析与展示实现，仍需对端实际回执。App 也可以直接采用自己的 HTTP／SSE／事件协议。

错误出口

实际原因	程序处理	面向用户的表达方向
未提供或不允许读取来源	不扩大权限，不生成假事实	说明缺少哪类可用资料
参数或输出不符合合同	记录具体阶段和代码；按预算修正或结束	说明本次未完成的实际动作
供应商断流／超时	保存已知执行状态，有界重试	回复未完成，可重试
预算不足／读取超限	缩小合法范围或分次任务	说明范围限制，不静默裁剪
用户取消	终止可取消工作，核对已执行操作	明确停止及已确认状态

错误信息不要把内部 schema、token、调用协议或堆栈原样展示。日志保留机器可定位字段，用户文案保留准确原因；不能将任何失败都说成连接问题。

观察与持久化各自负责什么

Core 的运行记录／诊断和 Support 的 Provider observer 提供观察边界；它们不自动建立日志数据库。App 决定是否输出到控制台、文件、遥测系统或持久仓库，以及如何授权查询、脱敏和保留。breakWhile 的 tags 是中断分类线索，不是权限或规则筛选开关；遵循 Support 参考。

建议关联 request/run、阶段、模型或工具调用 ID、业务错误码、资料 revision／快照 id 与真实耗时。默认不收集凭据、完整提示词、用户材料或模型正文；需要正文诊断时由产品明确启用并限制范围。观察回调不应改变业务返回或把记录失败升级成重复执行。

发布与恢复

代码清单、资料、任务引用和配置作为一个可核对的版本交付。发布前校验引用，准备可回退的旧版本；新请求切换到新目录，已有请求持有旧快照。多文件或数据库发布是否原子，由 App 实现，Knowledge 内存目录本身不提供存储事务。

App 发布时同时说明已启用能力、资料版本、配置和对外行为的变化；新版本仍须保留原有权限、预算、取消和交付保证。