HHostingByteSoftware
Ctrl K
ComunidadGuías…

docs/RELEASE_NOTES_v0.1.16.md

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

Archivo original ↗Preguntar a KiBot
# BailingHub v0.1.16：工具运行时收敛与语义检索韧性

`v0.1.16` 让带业务工具的 Agent 更可靠地收敛：运行时遵守每条路由自己的工具调用预算，在接近或达到上限时主动要求模型形成最终回答；模型误把内部工具协议写进正文时，中枢会阻止展示和执行。可选的工具语义检索也改为有界等待和安全降级，不再因索引或向量服务异常长期阻塞整个会话。

本版本同时修正官方 Widget 的最小化控件语义，并收录 RuoYi-Vue-Pro 与 JeecgBoot 的独立社区治理接入配方。

## 用户可见结果

- 每条路由既有的 `tools.max_calls` 继续作为本任务的业务工具调用上限。模型会在每轮业务工具执行后获知已使用和剩余次数，并在只剩一次时优先判断是否已经可以回答。
- 达到调用上限后，中枢停止提供工具，要求模型只根据已取得的事实形成自然语言最终回答；信息不足时必须明确说明，不能返回半成品控制文本。
- 模型若把 DSML 等内部工具协议标记写入普通正文，中枢会清除本轮临时流式内容，并在不提供工具的情况下要求模型安全重写一次。连续违规会失败关闭，内部协议不会被当作正文展示，也不会被解析执行。
- 工具语义检索异常时，会退回既有的渐进式工具发现，不再让可选检索链路长期阻塞会话。
- 官方 Widget 右上角原本实际执行“隐藏面板”的关闭按钮改为明确的最小化图标、标题和无障碍标签；交互功能不变。

## 工具运行时收敛

业务工具预算仍由路由独立配置，默认值和允许范围不变。运行时新增以下收敛行为：

- 模型轮次上限根据路由的业务工具预算、追加工具检索、图片查看和消息发送等各自的有界预算推导，不再由隐藏的固定 12 轮提前截断较大的路由配置。
- 每轮业务工具执行后向模型注入可信预算状态。
- 剩余一次时提示模型只在缺少必要信息时使用最后一次调用。
- 预算耗尽后移除全部工具并强制进入最终回答阶段。
- trace 增加工具预算接近上限、预算耗尽、内部协议拦截和安全重写结果，便于定位未收敛会话。

`max_calls` 仍只限制业务工具；`search_tools`、`see_image` 和 `send_message` 继续使用各自独立的既有上限。

## 最终输出安全闸

流式和非流式回答都会检查已知的内部工具协议标记：

1. 流式输出遇到可疑控制标记时，先停止继续发送，并通过 `reset` 清除本轮临时文本；
2. 中枢不会把文本协议转换为工具调用，也不会执行其中的参数；
3. 模型只获得一次不带工具的自然语言重写机会；
4. 重写后再次出现内部协议时，任务失败关闭，不向用户伪装成成功回答。

流式协议版本仍为 `bailing.chat.stream.v1`。自建聊天客户端应继续遵守既有规则：收到任何 `reset` 都丢弃当前临时文本，并以 `done.reply` 作为唯一权威最终回答。本版本新增的 `reset.reason` 值为 `protocol_violation`。

## 工具语义检索韧性

工具语义检索仍是白名单内的可选上下文增强，不参与身份、审批或最终业务授权。本版本增加：

- 服务 HTTP 就绪后在后台顺序预热已有工具索引，预热失败不阻塞启动；
- 内存缓存过期时继续服务旧快照，并以单飞方式在后台刷新；
- 只有真正的冷缓存才在配置的索引时限内等待；
- 索引和 embedding 凭证读取设置数据库查询时限；
- 查询向量请求使用可中止的 HTTP 时限；
- 索引、凭证或向量服务不可用时，安全降级到渐进式工具发现；
- 新增缓存状态、索引读取、凭证读取、向量请求和总耗时诊断，不记录用户查询、服务地址或凭证；
- 检索前复核已存向量的模型、维度和字节长度，并校验上游返回向量的实际长度；旧扩展未回传行级坐标时直接安全降级，避免用另一次可变快照猜测坐标；
- 同一工具源的重建串行执行，取得锁后重新读取权威配置；embedding 模型或维度变化时原子切换整源索引，失败时保留旧数据，不暴露部分新坐标。

两个部署级可选环境变量为：

| 变量 | 默认值 | 允许范围 |
|---|---:|---:|
| `BAILING_TOOL_INDEX_LOAD_TIMEOUT_MS` | 5000 ms | 100–60000 ms |
| `BAILING_TOOL_QUERY_EMBEDDING_TIMEOUT_MS` | 15000 ms | 250–120000 ms |

不配置时自动使用默认值。

## 独立社区接入配方

本版本收录两项可复核的治理接入配方：

- **RuoYi-Vue-Pro**：展示如何通过薄适配层开放售后详情查询和退款动作，同时保留原权限、租户、审批、幂等与业务系统最终授权。
- **JeecgBoot**：展示如何开放单个用户查询及冻结/解冻，同时复核操作人和目标用户的租户成员关系、原 Shiro 权限、审批与幂等边界。

每项配方均提供 Agent-facing OpenAPI、机器可读适配契约和本地验证脚本。它们是独立社区配方，不是上游官方集成、认证或认可，也不包含可绕过原业务权限的直连适配器。

## 兼容性与升级

- 无数据库迁移。
- 不修改 ACC、Client API 版本、执行器协议、工具签名、审批语义或业务系统最终授权。
- 既有路由无需修改 `tools.max_calls`。
- 两个检索超时环境变量都是可选项。
- 既有自建聊天客户端如已正确处理 `reset` 和 `done.reply`，无需修改。
- 自定义 `ToolEmbeddingRepository` 继续保持源码兼容；但当 embedding 模型或维度变化时，仓储必须实现原子的 `replaceProvider`。未实现时重建会明确失败并保留旧索引，不再执行非原子的先删后写。

## 验证

```bash
npm run release:check
node docs/integrations/ruoyi-vue-pro/verify_recipe.mjs
node docs/integrations/jeecgboot/verify_recipe.mjs
```

重点覆盖：

- 大于旧固定轮次的路由预算仍能按自身 `max_calls` 运行；
- 工具预算接近上限和耗尽后的最终回答收敛；
- 流式与非流式内部协议拦截、重置、单次重写和连续违规失败关闭；
- 索引预热、旧缓存服务、单飞刷新、数据库与向量请求超时、渐进式降级；
- 同源重建串行化及坐标系原子切换；
- Widget 最小化控件语义和原有交互；
- 两项社区配方的签名、主体、权限、审批、幂等及最终授权边界。

## 相关文档

- [工具治理设计](TOOLS_DESIGN.md)
- [运维指南](OPERATIONS.md)
- [流式聊天契约](STREAMING.md)
- [RuoYi-Vue-Pro 接入配方](integrations/ruoyi-vue-pro/README.md)
- [JeecgBoot 接入配方](integrations/jeecgboot/README.md)
- [兼容性与升级](兼容性与升级.md)
- [English release notes](RELEASE_NOTES_v0.1.16.en.md)