docs/UPGRADE_v0.8.0.md

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

# 长任务与附件空间：配套升级指南

本指南从 Core 0.7.0 / SDK 0.5.0 / DSH 0.5.0 升级到 Core 0.8.0 / SDK 0.6.0 / DSH 0.6.0。按部署方式使用正式版本，保留原配置和持久记录。

## 先确定需要哪部分

| 需求 | Core | SDK / DSH 与宿主 | 业务后端 |
| --- | --- | --- | --- |
| 调整中枢工具限额 | 新 Core、061；后台设置策略 | 配套版本可展示准确等待与原调用恢复 | 原 API/声明可沿用；业务自有限流不由中枢关闭 |
| 生成或指定图片后用于业务 | 新 Core、060、存储及工作空间开关 | 新 SDK；DSH 宿主接文件目录和持久上传记录 | 已接收 URL 的能力可沿用；素材 ID/转存由业务系统提供 |
| 一轮内来回切换工具 | 配套版本用于完整发现反馈 | 新 DSH 自动合并仍有效工具 | 无新增要求 |
| 跨用户消息复用工具声明 | 沿用现有每轮准备和权限检查 | 新 DSH；宿主显式 `toolLifecycle: 'session'` 并处理准备结果 | 无新增要求 |
| 重开后恢复原调用及只读面板 | 新 Core 的只读 receipt | 新 SDK/DSH、持久 invocationStore、正式面板接口 | 原调用/审批规则保持 |
| 任务累计预算、并发和暂停 | 新 Core、062；管理端按需创建任务 | 新 SDK/DSH、taskStore、完整原范围核验与绑定 | 计量为调用次数；不新增商品数/金额保护承诺 |

新包不会自动让其他 MCP 客户端、生态适配器或业务后端取得这些宿主能力。普通未纳入任务的授权可继续原流程；新接口不支持时要明确报告，不能扩大授权或换默认连接。

## 第一步：保留原状态

中枢备份数据库、运行配置与密钥、存储配置和文件对象。限流恢复的原参数快照由实例 `server.token` 派生密钥加密：不要在同一次普通升级中无计划地轮换它。令牌轮换后，旧快照不能解密时应阻断恢复，不能重新猜参数。

客户端保留安全凭据、连接实例标识、真实 Session、固定范围、原事件、归档 outbox/ACK/CAS、上传和原调用账本，以及已有任务关联。保护原私有存储位置，不把这些内容提交源码或当作示例数据；升级不应重新授权或重建全部会话。

## 第二步：升级中枢并迁移

使用最终正式发行制品，按部署方式准备代码和回滚材料。确认目标数据库后，用正式迁移器（源码安装入口为 `npm run db:init`）应用全部未执行迁移，再启动新版本。启动本身不隐式迁移。

| 相对 Core 0.7.0 的迁移 | 保存内容 |
| --- | --- |
| `060_agent_artifacts.sql` | 图片上传回执与原上传关联；二进制在部署方存储中 |
| `061_tool_rate_limit_policies.sql` | 工具源默认及单工具覆盖策略；历史空值继承原声明 |
| `062_agent_task_control.sql` | 六张任务关联、强制标记、调用及额度/许可记录表 |

检查迁移账本与就绪状态。已经应用的文件不要手工重跑；从更旧版本升级时还要应用其缺少的前序迁移。已有候选部署应按账本和文件摘要核对，不重复建表。

当前任务持久控制需要相应 MySQL 仓储。缺少可选接口的嵌入式 Host 应报告不支持；一旦配置为受管模式，缺表或数据库故障必须阻断，不能静默回到无限制执行。

## 第三步：升级实际 SDK / DSH 和宿主

DSH 正式依赖必须精确指向同批 SDK，lock 也应匹配。仅改工程 `package.json` 不足以证明桌面客户端、用户 Profile 或打包产物已升级：核对实际解析来源，检查是否存在嵌套旧 SDK。早期同版本候选按哈希识别，不能把候选 0.5.0 当成公开 0.5.0。

宿主按需接入：

- 跨轮复用：开启 `toolLifecycle: 'session'`，保留真实 Session/runtime，使用当前 schema 并处理“尚未准备”。默认 `active_turn` 保持。工具缓存重启后为空，不影响另一份原调用账本的持久恢复。
- 恢复与面板：持久 `invocationStore`；使用正式 `inspectSessionInvocation` / `resumeSessionInvocation`，传原 Session、原 ID 和取消信号。读取不会调用 resume。空结果保持未确认，存储错误或历史缺口不能显示旧成功。
- 任务：持久 `taskStore`，通过 `getSessionTaskCoordinates` 提交原坐标，再绑定管理端返回的任务，恢复时保留原范围、task 和 journal。任务 ID 不交给模型选择。
- 图片：受控 `artifactSource`、持久 `artifactStore`，只登记当前会话获准用于业务的文件。普通聊天附件不自动同步，模型不选择桶或本机任意路径。

旧记录缺少可信原绑定或参数时，不从正文补齐。旧 SDK/Core 明确不支持只读回执时，界面显示 unsupported，不用 resume 代替查询。

## 第四步：按需启用，先小范围验证

存储：先在“媒体存储”配置，再到“智能体客户端 → 配置接入 → 工具与审批 → 生成图片上传”启用指定存储。首期公开读取；准备一张可公开的测试图片即可。

限额：在“工具源 → 编辑 → 治理”设置工具源总闸、单工具默认与覆盖策略。总闸的 `0` 只关闭该层，不会关闭单工具、接入方或业务系统自有限流。相同工具源/工具的不同会话共享计数。

任务：用专用测试授权，通过管理端创建任务并绑定。**纳入任务会为原 Agent Session 保存持续强制标记，影响它的其他会话及旧入口；取消任务不会删除标记。** 先确认所有相关宿主兼容，再决定是否纳入日常授权。任务写额度 `0` 表示只读，`null` 表示没有累计写上限，不能混淆。

## 如何确认成功

1. 只聊天时不因恢复缓存或面板而创建业务 run；未选授权不接收请求。
2. 查询商品、查看库存，再回到商品查询，目标正确，旧有效工具可复用；需要准备时能取得完整参数说明。
3. 上传公开用途测试图片后得到 ready URL，恢复时仍是原上传；业务侧使用 URL 的成功、审批或失败单独显示。
4. 在专用合成任务中核对累计调用数；切换轮次不重置，暂停后不授予新派发许可，原结果仍可查询。
5. 关闭并重开有可信原调用记录的会话，核对不派发；明确继续仍是同一原调用。结果未知不产生替代写，取消等待不被显示为“已撤回业务”。

合成与自动化通过不能替代各部署方的实际客户端验收。无需为了每次升级重新执行无关场景；重点检查本次启用的能力与最终安装包。

## 回退与限制

尚未启用任务时，仍需根据新增持久记录和接口评估回退，保留新增表与账本，不能简单删表降级。**一旦存在任务强制标记，不应回到不理解它的旧 Core/宿主，也不通过删标记解除控制。** 出现问题先暂停受管派发并核对原在途调用，优先修复前进；完整恢复备份需要单独核对备份后已发生的业务效果，不能把数据库恢复当成业务回滚。

任务不包含本地工具、模型推理、图片上传或聊天归档的资源额度，不自动度量商品数、金额或字段影响；没有跨 Hub、整项计划自动恢复或自动补偿。附件列表的某些宿主源错误仍可能显示 `unknown_failure`，宿主不能将其展示为空目录；上传逐项错误和已成功 URL 保持独立。