[!WARNING]

v1.0.4 正式版发布继续阻断请更新至v1.0.4-preview.5

正式发布前进一步核查发现，Claude Messages、OpenAI Responses、Gemini、Realtime、OpenAI 音频和 MiniMax TTS 的 usage 归一化与最终结算存在多类同源缺陷，可能导致输出 token、缓存、图片、音频或精确字符用量未进入日志、普通倍率计费或 tiered_expr 结算。由于这些问题直接影响账务准确性，v1.0.4 暂不进入正式版，先发布 v1.0.4-preview.5 完成验证。

本预览版同时合并原计划进入 v1.0.5-preview.1 的 Dashboard、统一表格、移动导航、系统设置、渠道编辑、Tiered Billing、Ollama 模型管理、Playground、多语言和 README 更新，避免已确认修复继续滞留在下一版本分支。

升级前请在测试环境重点核对 Claude/Anthropic 流式输出、Responses 多模态 usage、Gemini 图片/音频生成、Realtime 音频表达式、TTS/STT、MiniMax 字符计费，以及移动端表格、Dashboard、系统设置、渠道编辑和 Playground 自动分组。

[!IMPORTANT]
修复前已经产生的异常日志无法始终仅凭本地记录恢复精确用量。Claude completion_tokens=0、丢失的 Responses modality 明细或异常 Gemini fallback 应优先结合上游 usage、供应商账单和原始响应进行对账；根据响应文本或媒体数量重新估算只能作为辅助依据。

[!NOTE]
v1.0.4-preview.5 是正式版前的计费阻断修复与前端体验集中验证版本。该版本没有新增数据库迁移，但会改变部分模型在异常 usage、音频路由和分阶段计费下的最终结算结果；发布前请以最终 tag、构建产物、上游官方价格和实际部署验证结果为准。

Release Notes

GitHub 地址

https://github.com/MAX-API-Next/MAX-API/releases/tag/v1.0.4-preview.5

Highlights

• 多协议 usage 与实际结算完成系统性补强：修复 Claude、Responses、Gemini、Realtime、TTS/STT 和 MiniMax 在最终 usage、BillingUsage 或细分 token 归一化中的缺口。
• Claude/Anthropic 流式输出恢复完整：message_delta 缺少 output_tokens 时会从累计 CompletionTokens 回填，并同步写回客户端 JSON；上游已有非零值继续优先保留。
• Responses 多模态明细完整保留：非流式、流式和 Compact 统一复制缓存创建、文本、图片、音频及 reasoning 等输入输出明细，并支持官方 output_tokens_details。
• Gemini fallback 支持混合模态：候选总量为零时可同时恢复 reasoning、文本、图片和音频明细，保留上游已有 modality 数据，并避免把流式 audio/* inline data 错算成图片。
• Realtime 与音频计费语义对齐：Realtime tiered_expr 可读取 cr、ai、ao，OpenAI TTS/STT 会归一化音频明细，Responses 音频路由覆盖 gpt-4o-audio*、gpt-4o-mini-audio*、gpt-audio* 和带音频 usage 的模型别名。
• MiniMax TTS 使用精确字符用量：上游 usage_characters 会直接进入输入 token、日志和倍率结算，缺失时才回退本地估算。
• Dashboard 首页由固定装饰横幅升级为真实运营摘要，集中展示请求、额度、模型与密钥状态，让异常和风险更容易在首屏识别。
• 统一 DataTable 改为根据内容容器宽度切换布局，不再只依赖浏览器视口；移动端支持行选择、批量操作和更安全的长内容展示。
• 应用端与公开页面 Header 完善响应式导航，将语言、主题、配置和 GitHub 等低频入口收进紧凑工具菜单，并保留移动端通知入口。
• 全局查询错误策略完成收敛：Dashboard、API Key、模型等普通请求失败时保留当前页面、筛选和操作上下文，通过局部错误状态提供重试，不再因任意 HTTP 500 直接跳转 /500。
• 设置页增加结构化加载骨架、局部错误恢复和更完整的表单语义，Switch 标签、说明、错误信息与禁用状态可被键盘和辅助技术正确识别。
• 修复公开首页 Hero 在窄屏下横向扩展和内容裁切的问题，390px 等移动视口下页面宽度保持在可视区域内。
• 修复 Playground 选择 auto 或 auto:* 模型分组后无法选择模型的问题，自动分组现在会正确加载用户模型集合。
• 渠道编辑、Param Override 和 Tiered Billing 等大型交互模块完成分层整理，并补齐异步状态、表单关联和关键工具函数测试，降低后续维护与回归风险。
• 法语、日语、俄语和越南语翻译继续补齐，修复日语插值与越南语 Tiered Billing 文案，并完善相关屏幕阅读器文本。
• 六种公开 README 语言新增二次开发、社区鸣谢和授权边界说明，进一步明确 AGPLv3、临时商用授权及上游项目许可之间的关系。

Critical Billing Fixes

• P0 — Claude message_delta 输出 token 清零：最终事件或上游快照缺少 OutputTokens 时，从已累计的 CompletionTokens 恢复；修复值同时进入 BillingUsage、日志、结算和客户端 usage.output_tokens。
• P1 — OpenAI Responses 丢失多模态 usage：非流式、流式和 Compact 不再只保留总量与部分缓存字段，输入侧 cached_creation_tokens、text/image/audio 和输出侧 reasoning/text/image/audio 明细均可进入内部结算。
• P1 — Gemini fallback 覆盖或漏算 modality 明细：fallback 改为按候选 token 而非包含 reasoning 的 completion 判断；原始缓存、工具和 modality metadata 会被保留，图片估算写入 ImageTokens。
• P1 — Gemini 混合文本与图片只记录一种输出：文本估算和 imageCount * 1400 可同时进入候选总量与 CandidatesTokensDetails；已有非零 IMAGE/AUDIO/TEXT 明细不会被本地估算覆盖。
• P1 — Gemini 流式音频误判为图片：inline data 仅在 MIME 为 image/* 时计入图片数量，audio/* 不再产生错误的 1400 图片 token。
• P1 — Realtime tiered_expr 缺少音频和缓存变量：结算参数现包含缓存读取、音频输入与音频输出，并继续按表达式实际使用的变量从基础 p/c 中自动排除，避免重复或遗漏计费。
• P1 — OpenAI TTS/STT usage 和音频路由不完整：流式 TTS 与 STT 的 input_tokens_details / output_tokens_details 会映射到统一 usage；Responses 可按模型家族或实际音频明细进入音频结算。
• P2 — MiniMax 精确字符数未参与结算：usage_characters 现在作为 PromptTokens、TotalTokens 和文本明细参与日志及倍率结算；生产代码统一使用项目 JSON wrapper。
• 视频任务核查：未发现 Claude 式最终 usage 快照清零问题；按次任务保留预扣额度，其他任务仍依次使用 adaptor 实际额度、TotalTokens 重算或原预扣额度。

New Features

• 统一表格新增容器宽度响应能力，可在侧栏展开或内容区变窄时自动切换为移动卡片布局。
• 移动表格新增可配置的行选择与批量操作支持，并允许列通过元数据定义移动端标题、内容布局和换行策略。
• 新增 Header 工具菜单，统一承载语言切换、主题切换、界面配置和 GitHub 等入口，减少窄屏顶部空间占用。
• Dashboard 新增运营状态摘要和查询状态工具，支持独立处理加载、成功、空数据与失败重试状态。
• 设置页新增结构化 Skeleton 和局部错误恢复入口，加载或请求失败时仍保持稳定页面几何。
• Param Override 新增专用编辑器工具函数与测试，强化特殊字段类型、空键和同步字段的状态处理。
• Tiered Billing 编辑器补充本地化 token 提示、价格字段辅助组件和计算工具测试。
• README 新增多语言二次开发与社区鸣谢说明，公开自用二开项目适用的显示条件、临时授权范围和上游许可边界。

Improvements

• 统一 Responses usage 复制入口，避免非流式、流式和 Compact 在新增 token 明细时再次发生字段漂移。
• Gemini 候选 token 恢复改为汇总 TEXT、IMAGE、AUDIO 明细，并将 reasoning 独立计入 completion；原始 BillingUsage metadata 在估算过程中保持可追溯。
• Gemini 流式和非流式图片识别共用严格 MIME 判断，减少不同 handler 对同一媒体类型产生不同结算语义。
• Realtime 通过统一 BuildTieredTokenParams 进入分阶段结算，缓存与音频变量遵循和文本请求相同的自动排除规则。
• OpenAI 音频接口通过统一归一化函数映射总量和细分 usage，降低 TTS/STT、流式/非流式之间的分支差异。
• DataTable 的桌面/移动判断从 viewport media query 调整为容器尺寸观察，侧栏、抽屉和中等宽度内容区中的表格更符合实际可用空间。
• 表格单元格不再依赖全局强制不换行；模型名、标签和其他长内容可按列契约换行，减少横向撑宽和内容裁切。
• 移动卡片列表完善选择状态、操作区和字段展示，分页与批量操作在窄屏下保持可用。
• 公开 Header 和应用 Header 统一移动端导航逻辑，语言、主题、配置、GitHub 与通知入口在不同断点下保持一致。
• 移动菜单在切换回桌面布局时会主动清理页面滚动锁，避免响应式切换后页面仍无法滚动。
• Dashboard 概览信息改用当前主题的语义色和现有卡片体系，减少固定深色、装饰网格和静态文案对首屏空间的占用。
• Dashboard 查询状态改由明确的辅助函数描述，替代复杂嵌套条件，加载、失败和局部数据状态更容易维护。
• 系统设置 Switch 行补齐 id、Label 关联、aria-describedby、错误提示和禁用原因，点击标签和键盘操作更加可靠。
• 设置页面在加载、失败和恢复过程中保留主要布局结构，减少内容跳动和整页空白。
• Ollama 模型对话框会取消过期请求、隔离不同渠道的异步响应，并在切换渠道或重新打开时重置删除状态。
• Param Override 专用编辑器拆分为更清晰的字段组件；输入 Label 与控件建立关联，sync_fields 在键为空时仍保留已选类型。
• 渠道编辑抽屉的导航、表单状态和转换逻辑进一步分离，减少大型组件内部的隐式状态耦合。
• Tiered Billing 编辑器将字段、辅助展示和计算逻辑分层，保留原有配置契约并改善后续扩展与测试能力。
• Markdown、分页、对话框、菜单、侧栏、Spinner 等共享组件统一部分可访问性和样式细节。
• 修正多个无效的 text-xsst 样式类和零散的响应式样式问题，避免构建后样式静默失效。
• 多语言同步报告更新，减少法语、日语、俄语和越南语中直接回退英文的新增文案。
• Dashboard 查询工具测试改用 TypeScript 与 CI 均可识别的测试方式，避免 bun:test 类型声明导致 GitHub Frontend checks 失败。
• 六种 README 的项目定位、二次开发说明和授权表述保持同步，明确临时授权只覆盖项目方有权授权的新增与修改部分。

Bug Fixes

• 修复 Claude 流式最终快照和 message_delta JSON 未携带累计输出 token，导致日志、结算或客户端 usage 中 output_tokens=0 的问题。
• 修复 Responses 重新构造 usage 时丢失缓存创建、图片、音频、文本及输出 reasoning 明细的问题。
• 修复 Responses DTO 未接收官方 output_tokens_details，导致部分输出明细在反序列化阶段消失的问题。
• 修复 Gemini 仅因 reasoning 非零就跳过候选 token fallback，以及重建 BillingUsage 时丢失缓存、工具和 modality metadata 的问题。
• 修复 Gemini 图片 fallback 未标记 ImageTokens、混合文本图片漏算图片、已有细分值被估算覆盖和音频 inline data 被误识别为图片的问题。
• 修复 Realtime 分阶段表达式中的 cr、ai、ao 永远为零，音频 token 也无法按表达式变量从 p/c 自动排除的问题。
• 修复 OpenAI 流式 TTS 只复制总 token、STT 未映射输入音频明细，以及 Responses 音频模型家族识别不完整的问题。
• 修复 MiniMax TTS 上游精确字符数只写入 TotalTokens、实际倍率结算仍使用本地估算的问题。
• 修复公开首页 Hero 网格在 320px、390px 等窄屏下被内容撑到视口之外，导致标题、说明和标签被横向裁切的问题。
• 修复任意 React Query 请求返回 HTTP 500 时全局跳转 /500，导致表单、筛选、分页和任务上下文丢失的问题。
• 修复 Dashboard 查询失败时缺少局部错误展示与重试入口的问题。
• 修复应用 Header 在移动端直接隐藏 TopNav，导致已实现的移动导航无法显示的问题。
• 修复移动菜单打开后切换到桌面宽度，body 滚动锁可能残留的问题。
• 修复表格只按视口宽度切换布局，侧栏展开后内容区已经过窄却仍渲染桌面表格的问题。
• 修复表格默认 whitespace-nowrap 使长模型名、标签或描述撑宽容器的问题。
• 修复移动表格统一隐藏选择和批量操作，管理员在手机上无法完成批处理的问题。
• 修复设置 Switch 的可见 Label 未与控件关联，点击标签和辅助技术导航不可靠的问题。
• 修复设置页加载时只显示单行文字，导致页面结构大幅跳动且失败后缺少局部恢复的问题。
• 修复 Playground 将 auto / auto:* 作为真实 group 参数请求模型，导致自动分组下模型列表为空、无法选择模型的问题。
• 修复 Ollama 模型对话框中旧渠道请求晚返回后覆盖当前渠道数据、删除状态未正确复位等异步竞态问题。
• 修复 Param Override 中部分专用字段的 Label 未关联控件，以及 sync_fields 在 key 暂时为空时丢失所选类型的问题。
• 修复 Tiered Billing token 提示未完整本地化、部分状态计算在空值场景下不稳定的问题。
• 修复日语翻译插值格式异常和越南语 Save tiered billing、Tiered Billing、保存成功提示及 JSON 标签仍显示英文的问题。
• 修复 Dashboard 测试直接导入 bun:test，导致 GitHub Actions 执行 tsc -b 时找不到模块类型声明的问题。

Compatibility Notes

• 本预览版会改变部分异常 usage 的最终结算结果：修复后此前为零或被当作普通文本的输出、缓存、图片、音频和字符用量可能产生正确费用，请在升级前核对模型价格与表达式配置。
• Claude/Anthropic 流式客户端现在可能在最终 message_delta.usage.output_tokens 中收到本地累计回填值；已有非零上游值不会被覆盖。
• Responses 内部日志和结算会保留更多 input_tokens_details、output_tokens_details 和 completion_tokens_details；依赖旧零值行为的对账脚本应同步更新。
• Gemini 在上游候选总量为零但存在可见输出时会使用本地估算；图片仍按每张 1400 token 估算。混合文本和图片会分别记录，最终候选总量为各 modality 之和。
• Gemini 上游已提供的非零 TEXT、IMAGE 或 AUDIO 明细优先于本地估算；音频 inline data 不会在缺少音频计量依据时被错误改按图片计费。
• Realtime tiered_expr 现在可使用 cr、ai、ao，引用这些变量时会改变 p/c 的归一化结果；升级前应复核实时音频模型表达式。
• gpt-4o-audio*、gpt-4o-mini-audio*、gpt-audio* 或返回音频 token 明细的 Responses 请求会进入音频结算路径。
• MiniMax TTS 的倍率结算改用上游 usage_characters；上游精确字符数与历史本地 token 估算存在差异时，升级后费用可能变化。
• 本预览版没有新增数据库字段或迁移要求，也没有改变上述前端模块使用的后端 API 数据格式。
• 普通 React Query 请求返回 HTTP 500 时不再自动跳转 /500；页面会保留当前上下文并显示局部错误与重试。依赖旧跳转行为的自动化测试需要更新。
• Playground 选择 auto 或 auto:* 分组时会省略模型列表请求中的 group 参数，这是自动分组的预期行为；显式分组仍按原有参数请求。
• DataTable 的移动布局现在取决于表格容器宽度，而不是只看浏览器视口；侧栏、嵌套页面或窄内容区可能比以前更早切换为卡片列表。
• 移动表格可按页面配置暴露行选择和批量操作；请检查高风险批量操作的确认流程、权限和触控可用性。
• Header 的语言、主题、配置和 GitHub 入口在窄屏下会进入统一工具菜单；通知入口仍保留在应用 Header。
• Ollama 模型请求支持取消过期加载；快速切换渠道时，旧请求结果不会再更新当前对话框。
• Param Override、渠道编辑和 Tiered Billing 的内部组件结构已调整，但现有配置数据格式与后端接口保持不变。
• README 已增加二次开发、社区鸣谢与临时商用授权说明。使用、分发或二次开发前，请同时核对 AGPLv3、显示条件、临时授权适用范围以及 One API、New API 等上游项目的许可要求。
• 正式环境升级前建议重点复核 usage 对账、模型倍率、分阶段计费、Dashboard、系统设置、渠道编辑、Tiered Billing、Ollama、Playground、移动导航以及移动表格的失败重试和批量操作流程。

Verification

本预览版已完成以下针对性验证；正式发布前仍建议在最终 tag 和发布构建上重新执行：

• go test ./relay/channel/gemini -count=1
• go test ./dto ./service -count=1
• go test ./relay/channel/claude ./relay/channel/openai ./relay/channel/minimax ./relay -count=1
• go vet ./relay/channel/claude ./relay/channel/openai ./relay/channel/gemini ./relay/channel/minimax ./dto ./service ./relay
• Claude OutputTokens 缺失回填、上游非零值保留和 message_delta.usage.output_tokens JSON 写回回归测试
• Responses 非流式、流式、Compact 多模态 usage 与官方 output_tokens_details 回归测试
• Gemini reasoning+文本、纯图片、文本+图片、已有图片明细、已有音频明细和流式音频 MIME 分类回归测试
• Realtime cr/ai/ao 参数与 p/c 自动排除回归测试
• OpenAI 流式 TTS、STT 输入明细、Responses 音频模型家族及模型别名回归测试
• MiniMax 上游字符用量与本地估算 fallback 回归测试
• cd web/default && bun run typecheck
• cd web/default && bun run build:check
• Dashboard、Playground、Param Override 与 Tiered Billing 共 17 项针对性前端测试
• cd web/default && bun run i18n:sync
• 相关变更文件的 ESLint 与 Prettier 定向检查
• git diff --check
• 390px 与 1280px 浏览器视口回归检查
• 390px 首页验证 scrollWidth === innerWidth，确认无横向溢出
• 移动菜单打开后切换到桌面宽度，验证页面滚动锁可以正确清理

说明：当前仓库的全量 bun run lint 与全量格式检查仍存在与本版本无关的历史基线问题，因此本稿不将其列为已通过项。正式版发布前仍建议在最终分支执行完整后端、前端和部署回归。

Full Changelog: https://github.com/MAX-API-Next/MAX-API/compare/v1.0.4-preview.4…v1.0.4-preview.5