HHostingByteSoftware
Ctrl K
ComunidadGuías…

docs/UPGRADE_v0.9.0.md

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

Archivo original ↗Preguntar a KiBot
# v0.9.0 模型计费：配套升级指南

从公开 Core 0.8.0 / SDK 0.6.0 / DSH 0.6.0 升级到 Core 0.9.0 / SDK 0.7.0 / DSH 0.7.0。下载与部署时核对版本、Tag 和制品摘要，保留原配置与持久记录。

## 选择需要启用的能力

| 需求 | 管理端与 Core | 宿主或业务后端 |
| --- | --- | --- |
| 保持原业务工具、审批与长任务 | 升级 Core，保留原配置与状态 | 原流程继续使用，无需开启模型计费 |
| 提供统一模型套餐 | 配置模型连接、参考计价映射、USD 套餐并开通账户 | 宿主接入能力发现、模型目录与额度摘要；可信后端按需提供套餐范围身份 |
| 让本地助手生成图片 | 配置已支持的图片适配、参考价格并加入套餐 | 接入工具目录、原请求持久记录与异步查询；业务使用图片仍单独调用业务接口 |
| 自动开通业务套餐 | 配置来源所有权与权限 | 可信后端使用外部计费接口，保留幂等开通标识；支付、汇率和退款仍由业务侧处理 |
| 移除、恢复账户或手动重置额度 | 管理员按账户状态与权限操作 | 使用已有摘要；这些管理功能不单独要求 SDK/DSH 或业务后端改造 |

## 备份与迁移

保留数据库、实例配置和密钥、对象存储、原制品及客户端的安全凭据、会话和持久记录。升级时协调所有共用状态库的 Core 与写入方；已经派发的请求保留原 ID 和证据，不以重发替代恢复。

从公开 0.8.0 升级，通过正式迁移器（源码安装入口为 `npm run db:init`）应用全部未执行文件，再启动新 Core。运行时启动不自动迁移。

| 新增文件 | 作用 |
| --- | --- |
| `063_usage_model_billing.sql` | 新建模型计费所需身份、账户、模型服务、USD 套餐、原请求账本及参考价格缓存，共 14 张表 |
| `064_period_plan_allowance.sql` | 为已存在且缺字段的周期配置和快照补入各自原额度；新安装的空计费表无数据回填 |

迁移保留原业务与真实客户数据。公开 0.8.0 没有这一计费模块，无需先清退旧结构或清空表。早期未公开测试实例如有不兼容废弃结构，属于独立维护问题，不能把其清理步骤用于客户升级或混入公共迁移。

已部署过 063 计费预览的实例，先看[周期售价与额度拆分](PERIOD_ALLOWANCE_UPGRADE.md)：停止旧版本写入，再应用 064，核对原快照与账本后启动新版本。已记账文件由迁移器跳过；不手工改写账本或重跑已应用 SQL。更早公开版本还需应用缺少的前序迁移。

## 配置与宿主接入

1. **模型服务**：配置实际凭据、地址及型号，选择 `chat` 或 `tool` 用途。显式绑定 OpenRouter 参考模型与端点，核对价格计量与真实服务能否对应。参考报价不是供应商实付成本。
2. **套餐**：统一 USD 与一个倍率。周期套餐同时填写售价和周期额度；额度包只填写一次性额度。确定有效期、日/周/月周期和服务集合，再为测试账户开通。
3. **能力发现**：读取 `GET /usage/v1/capabilities` 中 `model_gateway`。宿主使用当前目录的 ready `items`，对 `unavailable_items` 显示配置原因；缺少支持时明确不可用，不自动换模型。
4. **身份与持久化**：需要整个套餐范围时，可信后端显式交换 `model_access: token_gateway` 身份；单模型 `service` 范围仍保持。每个模型或工具请求在本地持久保存原 `operation_id`，重开后查询原请求。不要将服务端凭据传给浏览器或模型。
5. **结果与额度**：分别处理 `result_state`、`billing_state` 与摘要的 `presentation`。结果 complete 即可使用；缺少实际计量保持待结算。Credits 与百分比使用摘要，不从 Token 数猜余额。控制台可能向下取整显示百分比，精确数值与显示字符串分别提供。

配套 SDK/DSH 应核对实际安装与解析版本，包括打包宿主内的依赖。仅修改版本声明不会自动完成宿主 UI、持久化或工具执行接入；不启用模型网关的宿主继续遵循原业务契约。

## 启用后的验收

- 一个测试账户能看到套餐中已就绪的模型与工具，未就绪项有可理解的原因，供应商凭据不进入目录。
- 采用明确的售价、周期额度和倍率，核对一次受控请求的实际用量、参考费用、扣费及客户展示。图片服务没有 Token 时保持为空。
- 原 ID 查询和同内容重试不会再次派发；已知失败、未知结果、取消和待结算分开展示。结果过期不触发自动重发。
- 套餐编辑不改写原开通额度。归档后阻止新使用，恢复不补发额度；重置维持原有效期，已派发请求向原池结算。只检查本次启用的管理动作。
- 验证新制品、迁移账本和客户端版本，同时保留既有审批、原调用与长任务约束。

视频、语音声明不作为执行验收；当前图片适配不提供供应商任务 ID 的异步任务恢复，原 ID 查询读取中枢保存的结果。

## 回退

新结构与新快照落库后，不能假定旧版本能读取或正确约束它们。出现问题先停止新增派发，核对原在途请求及结算，保留账本与回滚材料。恢复旧备份必须同时处理备份后的请求和业务效果，不能通过删表、丢弃账本或重发原操作回退。已启用的 0.8.0 任务强制标记仍须由兼容版本执行。

[版本说明](RELEASE_NOTES_v0.9.0.md) · [完整计费契约](MODEL_BILLING.md) · [English](UPGRADE_v0.9.0.en.md)