docs/RELEASE_NOTES_v0.10.0.md

Rama main · réplica de lectura del repositorio original.

# Core v0.10.0：先找能力，再按需读取相关知识

[English](RELEASE_NOTES_v0.10.0.en.md)

一个本地智能体只是查库存，却同时收到多篇业务文档；另一个正在提交较大的页面设计，尚未派发就触及小参数限额。Core 0.10.0 相对公开 0.9.4 增加按需知识与工具指导，统一有界参数容量，并让管理员更清楚地配置模型预算、接入和排障。

配套为 **Core 0.10.0、MCP / Agent Client SDK 0.8.0、DSH 0.8.0**。它们分别发行：原有工具调用、旧客户端和自带聊天可继续使用；只有采用新宿主能力或修复客户端独立小上限时才需要对应升级。相对 0.9.4 没有新增 SQL，不宣告 1.0 稳定承诺。

## 更新了什么

### 智能体可以先看提示，再读需要的知识

新增 Agent Session 专用知识 `capabilities / search / read`。宿主先确认协议，显式使用 `knowledge_delivery: "on_demand"` 后，准备结果提供有界提示，正文由受授权、带修订的引用按需读取。搜索与分页都有大小、数量和有效期限制；引用过期或授权变化需重新发现，不能绕过主体、路由或审批边界。

旧客户端不传该选项时仍收到 inline 知识。**自带聊天、embed 和 widget 继续原有服务端检索与正文装配**。知识和执行摘要始终是参考材料，不授予权限，也不是完整用户长期记忆。

### 工具说明不再被短摘要截断后悄悄丢失

工具目录继续使用简短说明，并明确详细指导是否可读、短说明是否被截断。按名读取指导会重新检查当前授权和能力修订；标准 summary、description、ACC 指导及首个示例有界保留。发现回执区分授权候选数、实际返回数与未知匹配总数；不把凑满结果解释为精确匹配。

发现修订与冻结执行指纹分开。仅指导文字变化不会要求重做已经批准的业务调用，旧 invocation 仍按原身份与参数核对。

### 大参数保持完整，超限说明发生在哪里

工具 arguments 统一按实际 `JSON.stringify(arguments)` 的 UTF-8 字节数检查，允许最多 **1 MiB**；工具调用 HTTP 信封最多 **2 MiB**。Core 与 MCP/SDK 的独立限额配套更新。对象继续是对象，原能力字段、签名、授权、审批、幂等和业务系统自己的限额仍独立生效。

超限保留 `arguments_too_large`、`not_dispatched` 与允许/实际或已观察字节数，不回显正文。完整审批参数与摘要保持对应；通知只携带有界预览，控制台在完整参数读取完成前不能批准。升级 Core 不会自动修复旧客户端自己较小的限额。

### 默认输出预算与服务上限分开

可选显式模型策略分别描述默认预算、服务上限、实际输出参数及 `completion_total / final_answer` 范围。管理员按实际模型路由核实语义；Core 不按模型名猜测，也不统一放大预算。旧服务保持原配置和行为，图片工具不使用对话输出预算。

错误参数得到明确的派发前拒绝，不静默把 `max_tokens` 改成 `max_completion_tokens`。原 operation 和摘要保持不变；单次生成被截断不等于网络执行未知，下一段由宿主在任务授权内决定。**本版不在中枢自动重试模型，也不替客户端实现长任务续跑循环。**

### 后台与升级排障更连贯

首次接入引导、调用示例和权限文案更加一致；路由、接入方和工具源支持未保存保护。审批续办与新任务重跑区分，诊断跳转保留筛选、页签和返回位置；迟到响应不能覆盖当前对象。编辑抽屉的常规说明收敛到问号，风险和错误保持可见，并防止登录密码自动填入配置表单。

新增只读 `doctor --upgrade-plan`，比较明确提供的制品与脱敏迁移快照，不连接数据库或执行迁移。Kernel 启动恢复参与关闭排空；readiness 核对实际 state/configuration 资源及完整迁移摘要。自定义 MySQL store 须提供 `schemaReadinessDb`，否则失败关闭，详见升级指南。

## 谁需要调整

| 使用者 | 升级影响 |
| --- | --- |
| 中枢管理员 | 更新完整制品，备份并排空；核对真实存储 readiness。模型显式策略按需启用，不自动修改现有预算。 |
| 业务后端 | 原 HTTP/HMAC/ACC 身份和权限契约保持；本版不要求重写接口。继续执行业务字段、正文和存储上限。 |
| MCP/SDK 或 DSH 宿主开发者 | 采用 0.8.0 获取大参数修复、知识按需入口、预算帮助函数及披露确认。旧请求不可改写，客户端仍负责最终模型请求、工具注册与任务循环。 |
| Kernel Host 开发者 | 默认 store 已支持真实资源 readiness；自定义 MySQL store 应暴露实际只读资源。独立 Host 的 pin、制品和部署另行核对。 |

## 如何升级与确认

按 [0.10.0 升级指南](UPGRADE_v0.10.0.md)保留配置、数据、原调用和回滚材料。0.9.4 到本版没有新 SQL；更早版本仍需原升级链中的迁移。

核对精确 Tag/提交、包版本与迁移账本；检查 `/health/ready`、首次接入、保存/取消、原审批及只读回执。仅在独立测试数据中验证大参数和新知识协议；无需为基础验收调用付费模型或修改真实业务页面。

公开回归覆盖合成供应商、权限/修订变化、大小边界、原 operation 恢复、持久化与生命周期；不代表所有供应商、客户端产品或外部业务副作用已验收。知识正文可能分页或截断；超时、上下文、输入大小、模型供应商硬限制与账户额度仍有界。非作者接入和长期稳定性不能由这些合成测试替代。

[知识协议](AGENT_KNOWLEDGE_API.md) · [Runtime API](AGENT_CLIENT_RUNTIME_API.md) · [模型预算](MODEL_OUTPUT_BUDGET.md) · [宿主续段与恢复](MODEL_CONTINUATION.md) · [CHANGELOG](CHANGELOG.md)