MAX API 2.0 SmartOps pre2：订阅策略、异步任务结算、跨协议计费与认证授权可靠性

[!WARNING] v2.0.0-smartops.pre2 是一次面向订阅策略、异步任务结算、跨协议工具计费和认证授权可靠性的 Preview 增量。升级前请备份数据库，并在目标环境完成迁移、回滚和账务核对。

本版的账本化工具计费只结算可稳定识别且已完成的 custom/Responses 内置工具调用；流式中途失败、未终止或身份冲突的调用会失败关闭，不按声明或不完整片段收费。Claude 等供应商自报的 server-tool usage 仍走各自的 usage metadata 路径。涉及真实支付、订阅并发、跨节点迁移和上游供应商协议的场景，应在目标环境独立验收。

[!NOTE] 本版本聚焦订阅与结算策略、异步任务用量与终态结算、MiniMax-H3/Doubao 任务协议、跨协议工具计费、SmartOps 人工结算以及认证与授权安全边界。

MAX API 2.0 SmartOps pre2：订阅策略、异步任务结算、跨协议计费与认证授权可靠性

GitHub 地址

正式发布：https://github.com/MAX-API-Next/MAX-API/releases/tag/v2.0.0-smartops.pre2

Highlights

• 订阅套餐支持钱包溢出和到期降级策略：管理员可以决定订阅额度耗尽后是否允许回退钱包，并为到期/取消指定目标分组；购买时将策略快照写入用户订阅，后续编辑套餐不会改变已购买实例。（证据：model/subscription.go 的 SubscriptionPlan、UserSubscription、CreateUserSubscriptionFromPlanTx；关键逻辑：allow_wallet_overflow、downgrade_group 在购买时冻结。）
• 异步任务用量和结算形成完整闭环：任务提交阶段保存不可变的参数化计费计划并预留额度，轮询阶段只接受经过版本化契约校验的供应商用量，终态阶段执行一次性差额结算；缺失、无效或不一致的终态证据会进入可恢复的人工对账，而不会静默按错误用量扣费。（证据：types/task_billing_plan.go、types/task_usage.go、service/task_billing.go、service/task_polling.go；关键逻辑：TaskBillingPlan、TaskUsageEnvelope、ApplyBillingSettlementOnce。）
• MiniMax-H3 与 Doubao Video 支持官方及中转站任务结果形态：H3 兼容官方 task.id/task.status/task.content.url、MiniMax 视频中转站根级 id/status/data[0].url 和成功包装 data.data，并在结果 URL 真正可取前保持轮询；Doubao 同时兼容官方响应、配置化包装响应、结果 URL 和 usage 提取。（证据：relay/channel/task/hailuo/h3.go、relay/channel/task/doubao/adaptor.go、relay/channel/task/taskcommon/protocol_config.go；关键逻辑：parseH3TaskResult、parseGenericMiniMaxTaskResult、ParseConfiguredTaskResult。）
• SmartOps 提供可审计的任务结算处置：Root 管理员可以对符合条件的 MiniMax-H3 任务批量确认最终额度为 0，也可以逐任务输入 0..预留额度 的精确最终额度；普通告警仍可独立审核关闭，避免把告警关闭误当成资金已结算。（证据：service/smart_ops_alert.go、controller/smart_ops_alert.go、web/default/src/features/smart-ops/components/billing-settlement-evidence.tsx；关键逻辑：revision/CAS、幂等 operation key、失败明细和重试恢复。）
• 工具计费从散落计数升级为请求级、重试感知的账本：OpenAI Chat/Responses、Claude Messages custom tool 和 Gemini function call 统一记录稳定身份、去重别名、调用阶段和价格版本；只有获胜尝试在终态提交后进入结算。（证据：relay/common/tool_usage.go 的 ToolUsageLedger；关键逻辑：BeginAttempt、CommitAttempt、ToolCallIdentity 和冲突失败关闭。）
• Responses 与多协议转换更符合上游终态语义：支持 custom_tool_call 输入、Responses 标准 error/failed/cancelled 事件、内置 Web/File Search 去重和 OpenAI/Claude/Gemini 流式工具终态识别。（证据：dto/openai_response.go、relay/channel/openai/relay_responses.go、relay/channel/openai/chat_via_responses.go、relay/channel/claude/relay-claude.go、relay/channel/gemini/relay-gemini.go。）
• 部署和来源说明更安全、可复现：Compose、README 和宝塔文档将本地端口绑定到 127.0.0.1，固定镜像 digest，并在 Preview clone 后对 commit 不匹配直接失败。（证据：docker-compose.yml、README*.md、docs/installation/BT.md、NOTICE；关键逻辑：actual_commit 校验、loopback 端口。）
• 认证与管理员授权边界得到加固：OAuth/Telegram 状态绑定浏览器会话并一次性消费，身份变更与状态消费在同一事务内完成；新增只读权限目录、用户级授权覆盖和 shadow 评估，为后续逐路启用细粒度授权提供稳定契约。（证据：model/auth_flow.go、controller/oauth.go、controller/telegram.go、service/authz/*.go、middleware/authz_shadow.go；关键逻辑：SessionId、ConsumeAuthFlowWithActionTx、ClaimExternalAuthAssertionWithTx、GET /api/authz/catalog。）

New Features

• 管理端订阅套餐表单新增 Allow wallet fallback after quota exhaustion、Downgrade Group 字段和列表展示；套餐购买卡片会显示降级分组与钱包回退状态，六种前端语言同步新增文案。（证据：web/default/src/features/subscriptions/components/subscriptions-mutate-drawer.tsx、subscriptions-columns.tsx、lib/plan-form.ts、types.ts、web/default/src/features/wallet/components/subscription-plans-card.tsx、web/default/src/i18n/locales/*.json。）
• 新增 provider-neutral 的 TaskBillingPlan 和 TaskUsageEnvelope：计划冻结来源、规则、组件单价、请求/预留/最终阶段语义；用量信封冻结 producer、schema、contract digest、presence/completeness 和 evidence digest，区分缺失、显式零值、部分、无效与歧义用量。（证据：types/task_billing_plan.go、types/task_usage.go、pkg/taskusage/taskusage.go；关键逻辑：ContractDigest、BuildEnvelope、ValidateEnvelope。）
• MiniMax-H3 参数化计费支持输出时长、输入视频/音频时长、输入图片数、分辨率和视频输入附加费，并以同一请求快照计算 estimate/reserve/final；官方 H3 v2 content 支持文字、首尾帧、参考图/视频/音频及 callback 参数校验。（证据：setting/task_billing_setting/h3.go、relay/channel/task/hailuo/h3.go、relay/channel/task/hailuo/models.go。）
• 异步任务轮询支持配置化查询路径、任务 ID、状态映射、进度和多候选结果 URL；成功 MAX 包装会有界展开 data.data，官方 MiniMax task 和兼容网关根级 video.generation 也有显式解析分支。（证据：relay/channel/task/taskcommon/protocol_config.go；关键逻辑：MaxWrappedTaskUnwrapDepth、stripWrappedTaskPath、ExtractConfiguredResultURL。）
• 新增 SmartOps 任务人工结算和批量处置接口：精确额度输入、显式 0 值、revision 校验、按任务失败明细、普通告警关闭与财务结算分离，并同步前端多选、对话框、刷新失效和六种语言文案。（证据：controller/smart_ops_alert.go、service/smart_ops_alert.go、web/default/src/features/smart-ops/{api.ts,components, hooks}、web/default/src/i18n/locales/*.json。）
• 模型广场和任务计费设置页展示结构化 MiniMax 组件价格、单位和参数默认值；价格组件不再回退到普通模型单价，覆盖输出视频、输入视频、输入图片和输入音频等明细。（证据：web/default/src/features/pricing/components/model-details.tsx、web/default/src/features/pricing/lib/task-rate-card.ts、web/default/src/features/system-settings/models/task-rate-card-settings.tsx。）
• 新增请求级 ToolUsageLedger：支持 custom/built-in 两类工具、Call ID/位置双别名合并、稳定身份要求、别名冲突 tombstone、并发重复观察去重、重试尝试隔离和价格版本快照。（证据：relay/common/tool_usage.go；关键逻辑：observe、invalidateAmbiguousLocked、Snapshot。）
• Responses DTO 现在保留 custom tool 的字符串 input，并补齐 Web Search、File Search、Google Search、Image Generation 及多种 Responses output 类型常量；Chat↔Responses 转换可继续传递 custom-tool 输入。（证据：dto/openai_response.go、relay/channel/openai/chat_via_responses.go、relay/channel/openai/responses_via_chat.go。）
• 订阅策略迁移增加跨数据库列补齐与历史默认值修复：subscription_plans、user_subscriptions 增加钱包回退和降级字段，旧行默认允许钱包溢出、降级目标为空。（证据：model/main.go 的 ensure*SubscriptionPolicyColumns、migrate*SubscriptionPolicyDefaults、ensureSubscriptionPlanTableSQLite。）
• 新增细粒度权限能力目录和用户覆盖存储：管理员可读取 /api/authz/catalog 获取资源、动作和内置角色基线；authz_user_overrides 保存显式允许/拒绝，GetSelf 返回 admin_permissions。本版仍处于 shadow rollout，目录为只读，尚未把覆盖策略作为所有管理路由的强制门禁。（证据：router/api-router.go、controller/authz.go、model/authz.go、service/authz/catalog.go、service/authz/override.go、controller/user.go。）

Improvements

• 订阅扣费路径现在在订阅额度不足时读取所有 active 订阅的快照策略；只要存在一个显式禁止钱包溢出的订阅，就保持失败关闭，不再悄悄切换到钱包。（证据：service/billing_session.go 的 NewBillingSession、model/subscription.go 的 UserActiveSubscriptionsAllowWalletOverflow。）
• 购买上限、升级/降级分组和订阅到期处理增加行锁及事务边界；到期批次只使用当前事务锁定的快照，并在仍有其他订阅授予同一分组时保留该分组，避免多节点过期任务交叉覆盖。（证据：model/subscription.go 的 CreateUserSubscriptionFromPlanTx、downgradeUserGroupForSubscriptionTx、ExpireDueSubscriptions；关键逻辑：withRowLock、按 end_time/id 排序和 active upgrade 检查。）
• 订阅策略 DDL 按 common.UsingSQLite、common.UsingMySQL、common.UsingPostgreSQL 选择列定义；并发节点已先执行 ALTER TABLE、再用 GORM HasColumn 复核，仅抑制“另一节点已经成功加列”的竞态，其他错误继续返回。（证据：model/main.go 的 addSubscriptionPolicyColumn、execSubscriptionPolicyColumnDDL；model/main_migration_test.go 的并发和数据库旗标测试。）
• 自定义工具调用按 price_per_1k × call_count × group_ratio × QuotaPerUnit 使用 Decimal 计算附加额度；即使上游 token 为零，已完成且有价的工具调用仍会结算，并写入 tool_calls、tool_price_version 和 tool_billing_model 账单元数据。（证据：service/text_quota.go 的 customToolItemQuota、calculateCustomToolCallSurcharge、PostTextConsumeQuota；service/quota.go 的 PostAudioConsumeQuota。）
• 内置工具计数改为由账本投影到 ResponsesUsageInfo，Web/File Search 在 item.done、response.completed 或重复输出中只计一次；custom 工具与保留的内置名称分离，避免同一调用重复收费。（证据：relay/common/tool_usage.go 的 ObserveBuiltInToolCall；relay/channel/openai/relay_responses.go 的 observeResponsesToolOutput。）
• 工具价格索引改为原子发布、最长模型前缀匹配并带单调递增版本；请求开始时捕获不可变快照，预扣和结算均使用同一价格，运行中管理员 reload 不会改变在途请求的价格；custom tool 用量 metadata 会携带价格版本。（证据：setting/operation_setting/tools.go 的 RebuildToolPriceIndex、CaptureToolPriceSnapshot；relay/common/tool_usage.go 的 FrozenToolPrice；service/alpha_search_billing.go、service/text_quota.go。）
• 异步任务计费将估算额度、预留额度和最终额度分开记录；实际用量不足、超出预留、配置禁用差额结算或供应商证据不完整时分别走退款、封顶或人工对账路径，不把任务提交成功直接等同于最终完成。（证据：service/task_billing.go 的 resolveTaskBillingQuotas、prepareTaskTerminalBillingDecision；setting/task_billing_setting/h3.go 的 QuoteH3Estimate/QuoteH3Reserve/QuoteH3Final。）
• 任务轮询在 provider 终态与资金结算之间增加协调：提交结算仍 pending/manual 时保持任务可轮询；结算意图先持久化后应用，进程重启或 effect 失败可恢复，CAS 丢失不会覆盖并发发布的终态证据。（证据：service/task_polling.go 的 taskTerminalSettlementState、persistPendingTaskTerminalEvidence、recoverAppliedTaskTerminalEvidence；model/task.go 的 pending terminal 字段。）
• 用量生产和结算按来源、阶段、producer、版本和摘要审计；MiniMax-H3 的秒数转毫秒、输入媒体数量及显式零值保持指针语义，Doubao 的无效/部分 token 不再污染旧 token 结算字段。（证据：pkg/taskusage/taskusage.go、relay/channel/task/hailuo/h3.go、relay/channel/task/doubao/adaptor.go；关键逻辑：ValidateEnvelope、normalizeH3Usage、buildDoubaoUsageEnvelope。）
• 结算存储对 SQLite 串行化完整写入生命周期；MySQL/PostgreSQL 继续使用 GORM 事务和行锁，operation key、revision/CAS 和 effect 状态共同提供重试幂等与失败恢复边界。（证据：model/billing_settlement.go 的 billingSettlementSQLiteWriteMu、withRowLock、ApplyBillingSettlementOnce。）
• SmartOps 对账投影现在同时包含 request-finalize 正向资金记录和 task-finalize 人工记录，但只有未解决的正向 request-finalize 记录影响新请求准入；人工结算支持选择刷新后 revision 失效、逐项失败而不影响其他项。（证据：model/billing_settlement.go、service/smart_ops_alert.go、web/default/src/features/smart-ops/hooks/use-billing-settlement-selection.ts。）
• 批量结算 API 对响应 schema、数量、任务 ID、显式 0 和 actual_quota 范围做边界校验；前端输入兼容 Base UI/React Hook Form 事件形态，避免额度字段无法编辑或零值提交被吞掉。（证据：web/default/src/features/smart-ops/api.ts、web/default/src/features/smart-ops/hooks/use-manual-task-batch-settlement.ts、web/default/src/features/smart-ops/components/manual-task-settlement*.tsx。）
• 任务协议配置允许上游路径和包装层独立演进，同时限制展开深度、URL 候选和状态映射；显式零值请求参数使用指针包装，保留 false、0 等客户端意图。（证据：relay/channel/task/taskcommon/protocol_config.go、relay/channel/task/doubao/adaptor.go 的 request DTO；dto.BoolValue/dto.IntValue。）
• OpenAI Chat 流式观察器先缓存碎片，只有 finish_reason=tool_calls 才提交工具调用；Claude 只有 message_delta.stop_reason=tool_use 才提交；Gemini 会把 willContinue=true 的身份带到最终片段，缺少终态的调用不会进入账本。（证据：relay/channel/openai/relay-openai.go、relay/channel/claude/relay-claude.go、relay/channel/gemini/relay-gemini.go 及对应 *_test.go。）
• Responses 流在尚未向下游发送可见内容时允许重试；已经转发内容后标记 skip-retry，避免重复输出。标准 error 事件保留 code/message/param，response.failed、cancelled、canceled 及 response.completed 携带失败状态时统一走终态错误路径。（证据：relay/channel/openai/relay_responses.go 的 responsesTerminalError、responsesStreamTerminalError；relay/channel/openai/chat_via_responses.go 的 SendResponseCount。）
• 异步任务提交重试会把 retry index 传入 RelayInfo，从而清空失败尝试的工具观察并只结算获胜尝试。（证据：controller/relay.go 的 relayTaskSubmitAttempt；controller/relay_retry_test.go。）
• 认证流程统一使用会话绑定、事务化消费和提交后缓存失效；管理员权限解析在数据库不可用时保持 fail-closed，shadow 评估记录策略拒绝但不改变现有管理路由行为。（证据：model/auth_flow.go、model/user.go、model/cache_invalidation_task.go、service/authz/resolver.go、middleware/authz_shadow.go。）
• Preview 部署文档删除过时的根目录 README_preview_v2.md，对 clone 后 commit 不匹配改为输出实际 commit 并退出；Compose/README/宝塔示例统一 loopback 端口，外部访问改由 HTTPS 反向代理承担。（证据：066f5326、49248ed0、5aee7d59、README*.md、docker-compose.yml、docs/installation/BT.md。）
• 多语言 README 的发布入口统一指向稳定版发布页，部署示例固定正式稳定版本；Preview 说明不再作为默认部署指令。（证据：README.md、README.en.md、README.fr.md、README.ja.md、README.zh_CN.md、README.zh_TW.md。）

Bug Fixes

• 修复订阅套餐更新 map 漏写钱包回退字段、降级分组未校验的问题；更新请求现在保留显式 false，并拒绝不存在的降级分组。（证据：controller/subscription.go 的 subscriptionPlanUpdateMap、创建/更新校验；model/subscription_policy_test.go。）
• 修复旧订阅表新增非空/布尔列时可能把历史行误置为零值的问题，并修复 SQLite/MySQL/PostgreSQL 分支对运行时 Dialector 推断不一致的问题。（证据：model/main.go 的历史默认回填和 flags 分支；model/main_migration_test.go 的 legacy/default/flags 测试。）
• 修复多节点同时启动时订阅策略列 DDL 的 already exists 竞态；只有复核确认列已存在时才视为成功，其他迁移错误仍会阻断启动。（证据：model/main.go 的 addSubscriptionPolicyColumn；TestSubscriptionPolicyColumnAddToleratesConcurrentCreate。）
• 修复 Responses 非流式/流式失败状态被当作成功、标准 SSE error 丢失上游错误详情以及已输出后仍重试的问题。（证据：relay/channel/openai/relay_responses.go、chat_via_responses.go、responses_usage_test.go。）
• 修复 Responses function_call / custom_tool_call 在 item.done 与 response.completed 重复写出、文本和工具同时出现时错误返回 stop、以及 custom-tool input 丢失的问题。（证据：relay/channel/openai/chat_via_responses.go、dto/openai_response.go、tool_billing_test.go。）
• 修复 OpenAI Chat、Claude、Gemini 流式响应在工具调用尚未完整终止、终态为 length/content_filter/max_tokens/refusal 或身份冲突时提前收费的问题。（证据：relay/channel/openai/relay-openai.go、relay/channel/claude/relay-claude.go、relay/channel/gemini/relay-gemini.go、对应回归测试。）
• 修复 Responses 内置 Web/File Search 在多个事件投影时重复计数，以及未知/进行中的 tool status 被误认为可计费的问题；现在只接受空 status 或 completed。（证据：relay/channel/openai/relay_responses.go 的 isBillableResponsesToolStatus、relay/common/tool_usage.go。）
• 修复工具调用仅有零 token 用量时整笔结算被跳过的问题；有价 custom tool 仍会独立结算，未完成或无价调用仍不会收费。（证据：service/quota.go、service/text_quota.go、service/tool_usage_billing_test.go。）
• 修复 Alpha Search 预扣与最终结算在价格热更新期间可能使用不同价格的问题；两者现在读取同一个请求级冻结快照。（证据：service/alpha_search_billing.go、service/text_quota.go、service/text_quota_test.go。）
• 修复 OAuth/Telegram 绑定在状态已消费但身份写入失败时留下不可重试状态的问题；状态消费、内置身份更新或自定义绑定、Telegram assertion claim 和会话代际更新现在在同一事务中提交或回滚。（证据：model/auth_flow.go、model/user.go、model/user_oauth_binding.go、controller/oauth.go、controller/telegram.go；回归：model/auth_flow_test.go、controller/oauth_test.go。）
• 修复 OAuth 身份绑定的 TOCTOU 竞争和重复身份覆盖：内置 provider 在事务/身份突变锁内复核现有用户（含软删除记录），自定义 binding 使用调用方事务，并将冲突映射为 ErrOAuthIdentityAlreadyTaken。（证据：model/user.go 的 IsOAuthIdentityTakenWithTx、withUserOAuthIdentityMutationLock，model/user_oauth_binding.go、controller/oauth.go。）
• 修复 Telegram assertion 哈希大小写/空白差异绕过跨状态重放保护的问题；登录和绑定共用规范化 key，并在接受的授权时间窗内原子 claim。认证流程错误现在区分无效/过期/已消费状态与数据库等基础设施错误，避免把服务故障伪装成用户状态错误。（证据：controller/telegram.go 的 normalizeTelegramAssertionHash、telegramAssertionExpiry，model/auth_flow.go、controller/oauth.go；回归：controller/secure_verification_test.go、controller/oauth_test.go。）
• 修复 MySQL AuthFlow 外部 assertion 冲突处理可能触发自增主键 no-op 错误或误判插入成功的问题；改用不改写主键的冲突表达式，并以随机 payload 验证当前尝试是否真正持有 claim。（证据：model/auth_flow.go 的 authFlowAssertionConflictClause、ownsExternalAuthAssertionClaim；回归：model/auth_flow_test.go。）
• 修复用户删除后遗留细粒度授权覆盖的孤儿记录；授权覆盖现在加入用户删除事务，避免后续复用用户标识或审计查询读到失效策略。（证据：model/user.go 的 deleteWithCacheInvalidation、model/authz.go 的 DeleteAuthzUserOverridesTx。）
• 修复 MiniMax-H3 任务被中转站包装为 code=success 且外层仍是 IN_PROGRESS 时无法进入终态的问题；轮询现在优先展开受限的 data.data provider payload，并兼容根级 video.generation 的 id/status/data[0].url。（证据：relay/channel/task/taskcommon/protocol_config.go 的 WrappedTaskProviderPayload/ParseConfiguredTaskResult、service/task_polling.go。）
• 修复官方 MiniMax H3 查询返回 task.status=succeeded 但 task.content.url 尚未出现时过早标记成功和结算的问题；任务保持可轮询状态，直到结果 URL 可取，随后才写入代理结果地址并执行最终结算。（证据：relay/channel/task/hailuo/h3.go 的 parseH3TaskResult、taskcommon.ConvertConfiguredTaskToOpenAIVideo、service/task_polling.go。）
• 修复 H3/Doubao 供应商 usage 的负值、越界、token 总量小于 completion、错误阶段和 envelope 摘要漂移可能进入计费的问题；无效或不完整证据现在失败关闭并进入人工对账/恢复流程。（证据：pkg/taskusage/taskusage.go、service/task_billing.go、service/task_polling.go；回归：pkg/taskusage/taskusage_test.go、service/task_billing_h3_test.go、relay/channel/task/doubao/adaptor_usage_test.go。）
• 修复异步任务在结算 effect 应用前崩溃、重启或并发 CAS 后丢失终态的问题；新增 pending terminal evidence、settlement intent 恢复和 effect 重放，避免重复扣费或把已扣费任务永久留在 IN_PROGRESS。（证据：model/task.go、model/billing_settlement.go、service/task_polling.go；回归：service/task_billing_h3_test.go、model/task_billing_contract_test.go。）
• 修复 MiniMax-H3 人工结算默认额度、精确额度和批量输入的边界问题：显式 0 不再被当作缺省值，批量请求不重复校验，SQLite 结算写入不再因并发 writer 竞态失败，失败项保留稳定错误码供重试。（证据：service/smart_ops_alert.go、model/billing_settlement.go、web/default/src/features/smart-ops/api.ts、hooks/use-manual-task-batch-settlement.ts；提交：254d3151、ad20d135、c643c413、4a1fa605、08d94562。）
• 修复 SmartOps 普通告警关闭与任务资金结算混用的问题；现在仅允许合资格的 MiniMax-H3 任务走 0/精确额度结算，普通告警可以独立审核关闭，刷新后 revision 变化会清除过期选择。（证据：model/billing_settlement.go、service/smart_ops_alert.go、web/default/src/features/smart-ops/components/billing-settlement-evidence.tsx。）
• 修复任务参数计费和模型广场结构化价格显示不一致的问题；MiniMax 组件价格、单位和无上限输入视频字段现在按 task rate card 渲染，不再错误回退到普通模型价格或附加错误单位。（证据：web/default/src/features/pricing/components/model-details.tsx、web/default/src/features/pricing/lib/task-rate-card.ts、web/default/src/features/system-settings/models/task-rate-card-settings.tsx；回归：对应 *.runtime.test.tsx/task-rate-card.test.ts。）

Compatibility Notes

• 数据库结构变化：新增 subscription_plans.allow_wallet_overflow、subscription_plans.downgrade_group、user_subscriptions.allow_wallet_overflow、user_subscriptions.downgrade_group。应用启动会按项目迁移流程补列并回填历史值；SQLite 使用 ADD COLUMN，MySQL/PostgreSQL 使用各自引用和布尔字面量。部署方应在真实 MySQL/PostgreSQL 环境完成升级与回滚验证。（证据：model/main.go、model/main_migration_test.go。）
• 结算表结构变化：billing_settlements 增加任务结算所需的 task_id、task_quota、task_quota_target、revision/effect/reconciliation 字段及相关索引，用于区分预扣、任务终态和人工对账。应用启动通过 GORM 迁移补齐，现有 operation key 保持幂等边界；部署方应在真实数据库完成旧表升级、索引创建和回滚验证。（证据：model/billing_settlement.go、model/main.go、model/billing_settlement_regression_test.go。）
• 认证与授权数据库结构变化：auth_flows 增加可索引的 session_id，并新增 authz_user_overrides 表及用户/资源/动作唯一索引；GORM 启动迁移负责补齐，旧 AuthFlow 行的空会话值保持兼容，只有新建且带会话绑定的流程强制校验。部署方应在真实数据库完成旧表升级和并发迁移验证。（证据：model/auth_flow.go、model/auth_flow_test.go、model/authz.go、model/main.go、controller/oauth.go。）
• 异步任务计费契约：新任务保存的计费计划和 usage contract 是请求级快照；后续价格 reload、协议配置变更或 producer schema 更新不会重解释在途任务。H3 缺失/无效/歧义终态用量默认进入人工对账，Root 可选择 0 或不超过预留额度的精确值；这不是“所有异步任务都自动按最终 usage 扣费”的兼容承诺。（证据：types/task_billing_plan.go、types/task_usage.go、service/task_billing.go、service/smart_ops_alert.go。）
• 任务协议兼容范围：配置化查询默认路径仍兼容历史 MAX envelope；新增官方 MiniMax task、中转站 video.generation 和 code=success/data.data 识别仅在明确的任务协议/形状下启用，并限制包装展开深度。若自定义渠道返回其他字段路径，必须配置 TaskProtocolConfig 的 query/status/result URL 映射并用脱敏样例验证。（证据：relay/channel/task/taskcommon/protocol_config.go、relay/channel/task/hailuo/h3.go。）
• 订阅策略快照：套餐修改只影响新购买；已存在的 UserSubscription 保留购买时的 allow_wallet_overflow/downgrade_group。省略新 JSON 字段保持历史默认“允许钱包回退”；显式 false 会禁止订阅额度不足时切钱包。（证据：model/subscription.go、controller/subscription.go、web/default/src/features/subscriptions/lib/plan-form.ts。）
• 工具计费语义收紧：账本化的 custom/Responses built-in 调用只有在有价、可稳定关联到 Call ID 或位置、并在成功终态确认时才计费；声明但未输出、流中断、终态失败、身份冲突和未知 status 不计费。Claude server-tool usage 仍按其 usage metadata 计数。这可能使部分旧版本“按声明计费”的账单变少，但属于财务安全修正。（证据：relay/common/tool_usage.go、各协议 relay handler、service/text_quota.go。）
• 价格热更新边界：工具价格 reload 对新请求生效；在途请求继续使用创建 ToolUsageLedger 时的 PriceVersion，包含 custom tool 明细的账单 metadata 会记录该版本。（证据：setting/operation_setting/tools.go、relay/common/tool_usage.go、service/text_quota.go。）
• Responses 重试边界：首个错误事件或尚未产生可见输出的失败仍可进入既有渠道重试；一旦 OpenAI 格式或转换格式已经向客户端发送内容，后续错误会标记 skip-retry，调用方应能处理已输出后收到的错误终态。（证据：relay/channel/openai/relay_responses.go、relay/channel/openai/chat_via_responses.go。）
• 部署入口变化：默认容器端口只绑定 127.0.0.1:3000，不再直接暴露公网；需要通过 HTTPS 反向代理访问。继续使用旧 3000:3000 的自定义 Compose/脚本不会自动继承该安全边界。（证据：docker-compose.yml、README*.md、docs/installation/BT.md。）
• 许可证与归属：NOTICE 汇总 MAX API 及相关上游的保留署名/链接要求；二次开发和带 UI 分发必须按 NOTICE、LICENSE 及适用许可执行。多语言 README 提供法律文件入口；带 UI 分发时仍需确认实际页脚、关于页或归属入口满足可见要求。（证据：NOTICE:9-50、README*.md。）
• 稳定部署入口与正式发布版本分离：多语言 README 的可复制部署片段固定为稳定版入口；本版本应使用上方 SmartOps pre2 Release 地址和对应发布产物。

状态分类

Verification

• 已完成异步任务计费、工具账本、Responses/Chat、Claude、Gemini、认证授权、SmartOps 和模型/结算模型的相关回归验证。
• 已完成前端类型检查、结构化任务价格/设置和 SmartOps 结算相关测试，以及测试镜像一致性检查。
• 真实上游服务、生产数据库、支付回调、浏览器人工 E2E 和大规模压力场景，应由部署方根据自身环境单独验收。

Full Changelog（本版本）：https://github.com/MAX-API-Next/MAX-API/compare/6194145f4e9980472a9ebd6411ce6b28abce0bef…08d945627d91714168ca0841978ac3ac29d920d3