Files
Agent-Workbench/docs/NEWAPI-DOCUMENTATION-LEARNING.md

8.8 KiB
Raw Permalink Blame History

New API 文档学习与工作台兼容复核

2026-11-06容量纠正:已取得Anthropic官方Models overview,claude-opus-5-5同步最大输出128000/上下文1000000公开已知;此前“未取得最大值”仅为当时调查状态,并非官方没有公布。精确型号官方规格已作为目录缺项的后备来源,源码2bd7b24a、独立67/67与网页4组通过,未部署。见官方容量纠正;下方正式旧程序与原研究状态保留为原时点。

来源固定于2026-11-06,中文目录305篇正文及201份嵌入OpenAPI定义已逐项审读;API与Plugins均在覆盖范围。公开文档仓库提交d254f1842dc3d08d60f2269e2c9d4c9876a3dfbc。来源与SHA见newapi-documentation-sources-2026-11-06.json,逐篇阅读批次/笔记见newapi-documentation-review-2026-11-06.json,计划见NEWAPI-DOCUMENTATION-REVIEW-PLAN.md。抓取和实际审读分别记录;更新日志略去重复下载文件HTML列表、缩短归属链接,保留实质条目;API阅读略去x-apifox编辑器排序扩展,保留全部语义字段。文中图片未逐像素验收,空页和未解析引用不补造内容。

已读理解

  • 协议分别处理:Claude Messages要求anthropic-version、model/messages/max_tokens,system独立,工具为tool_use/tool_result内容块。文档中的1024/2000只是例子,不是统一默认或最大值。Chat、Responses、Gemini各有字段、流事件和用量定义。
  • 模型目录有多种格式;/v1/models可按认证头切换OpenAI/Anthropic/Gemini,Gemini分页。目录可预览新增/变更/移除;已有连接不能只跳过不刷新。独立模型元数据库不等于具体代理的实测能力。
  • 管理Access Token、模型API Key、Session是不同凭据;管理接口可能还要求New-Api-User匹配。账户/分组额度、限流、倍率和预扣是网关运营能力,不成为本工作台的默认本地额度。
  • New API负责网关路由/协议转换,不等于自主工程Harness。Redis/Session缓存不等于模型prompt cache。前缀、工具顺序和原生缓存参数应稳定,用实际usage验证,不能保证永不掉缓存。
  • 实际usage的0、缺失和unknown分别保留,估算不补造计费;断连/超时不代表未执行,不能盲目重放。请求名、映射名、返回名和物理型号不能混同。
  • 插件由宿主负责HTTP/认证/持久化/计费,插件报告用量事实;key/version/SHA/generation与在途兼容相关。Responses sync/stream/background、native、image/video能力分别声明。unknown不能默认in_progress,public task ID与upstream ID分开,fixture不等于真实上游验收。
  • Skills的管理凭据与模型Key分开,文档newapi-admin仍未发布。页面安装命令只读,不执行。
  • 旧日志与当前日志已读完实质条目(下载资产重复列表不计功能契约)。原生推理参数应按用户请求保持,不因型号后缀误改真实模型ID;显式0、纯缓存请求、工具图片、参数JSON字段顺序和流末帧工具都可能影响兼容。New API的网关估算结算不转作工作台的真实账单。
  • 全部模型API正文/定义已读:音频含multipart/二进制、Gemini媒体含URI权限、图片/视频有各自结构和异步状态;Realtime需WebSocket101。文件/微调明确501未实现,有目录条目不代表功能可用。
  • 管理API已读:渠道/标签/多Key/模型元数据/供应商/用户/令牌/日志/验证/支付/系统选项分别有User/Admin/Root权限。GET也可能产生测试、轮换、余额更新等副作用;无需登录的回调仍有流程验证。管理接口大量响应仅写200或有Unresolved引用,不能据此生成完整SDK。旧Telegram/Access Token接口与新日志明确迁移,版本差异保持。

文档内部版本差异

条目 已观察的差异 处理
订阅续费 订阅页说自动续费,钱包页说当前不支持 按实际部署版本核实,不推断已具备
Claude缓存 旧特性清单未支持;Messages schema和新日志已有缓存用量/计费修复 区分旧清单和当前契约
分组限流 不同说明有时间窗口/总数成功数语义差异 不据此新增客户端限流
插件requestBody API参考为kind/value联合类型,最小例子直接取prompt 按实际版本契约,不照抄矛盾例子
插件大小 指南1MiB,rc.40提高至8MiB 标明版本
插件网络/能力 旧指南不许fetch且要求能力;rc.43新增utils.fetch,json-clone/SSE-delta可不声明 标明版本
任务保存 旧页24小时,新rc.47默认72小时 不改写旧版行为
API定义完整性 Messages正文体optional却有必填字段、仅旧thinking枚举;Responses用量示例沿用Chat;部分管理定义直接标Unresolved $ref 不把该生成schema当穷尽的原厂规范或完整SDK

与工作台实现逐项对照

下表是源码能力与本机契约的对照,不把网关文档条目当作工作台已经实现的功能,也不认证代理线路的实际模型能力。

文档主题 工作台实现与此次处理 仍需保留的边界
Chat / Responses / Messages 已有三种请求/响应与流式适配;Messages携带anthropic-version和协议必填max_tokens 代理的协议转换、物理型号与实际服务稳定性须另验
模型获取与多选 现有目录预览、多选、共享凭据、手动或自动模型池;此次修复已有连接仅跳过、未刷新upstreamModel的问题 只有ID的目录不能补造最大容量或能力;刷新仍由用户显式应用
目录容量与名字 此次增加displayName、inputTokenLimit、outputTokenLimit声明解析;已有连接只更新目录元数据 这不是Gemini原生请求或分页适配;目录声明与已验证能力分开
在途请求与凭据 刷新替换元数据对象,旧准备快照保持;不改凭据绑定的连接revision,不重加密保存块 用户参数、覆盖、启停、名字不由目录刷新覆盖
输出截断 此次诊断改读实际已序列化请求,分别显示max_tokens / max_completion_tokens / max_output_tokens或确实未携带字段 不根据错误自动扩大参数、重试或改写历史请求;截断工具批次不执行
Responses incomplete 此次补齐HTTP200 / incomplete / max_output_tokens的截断分类;其它原因保留原意 内容过滤、未知原因不能统一归因为输出额度
推理参数与内容状态 已有品牌参数配置、原生参数、thinking签名/不透明状态与DeepSeek reasoning_content绑定 不是所有模型都公布完整能力,不把New API旧枚举当原厂完整范围
工具与图像输入 已有工具定义/参数/返回关联、图片内容和流末帧完整性核对 服务端搜索/执行工具、PDF、全部多模态内容块尚未完整接入
缓存与用量 保留实际上游缓存/推理用量、原始usage、请求前缀依据;unknown与本地估算分列 网关Redis/Session不是prompt cache,缓存命中及Purge收益不能据文档保证
错误、网络与重定向 保存上游原文/状态/请求ID/物理尝试、实际地址;默认透传不自动重发,重定向不转发凭据 网络中断可能已产生上游消费,unknown不补造成功或计费
Gemini原生与媒体 目录可识别部分声明;原生generateContent、音频、视频、Realtime等未完整实现 经兼容Chat接口使用某型号,不等于已实现该品牌所有原生能力
网关插件 已读Wasm ABI、宿主HTTP/认证/持久化/用量、SSE与异步任务约定,版本差异单列 未安装或执行网页插件,也未实现New API Wasm插件宿主
管理/运营与Skills 已读权限、渠道、令牌、额度、计费、日志、支付与Skills说明 不作为模型Key接口,不复制运营额度为工作台本地默认限制;不执行文中安装命令

未完成的真实验证

正式1.25.12 Claude旧声明2048仍被用于Messages必填max_tokens,未取得此型号权威最大值。本次源码刷新修复只在上游确实提供容量、且用户选择应用时使用该声明;缺项仍不能声称同步了最大值,也不能用0表示无限。

此次两处修复的本机HTTP、序列化请求、用量与回归结果见兼容复核验收。Gemini原生/媒体、服务端工具和插件宿主是独立功能差距;真实供应商兼容、角色收益、普遍重复读取改善与Purge收益仍需新实验。

研究尚未操作正式服务、真实Key或模型请求;原400缺max_tokens、网络异常、重复读取、unknown用量与Purge收益unknown保持。仅学习不自动打包或重启。