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

60 lines
8.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# New API 文档学习与工作台兼容复核
2026-11-06容量纠正:已取得Anthropic官方Models overview,claude-opus-5-5同步最大输出128000/上下文1000000公开已知;此前“未取得最大值”仅为当时调查状态,并非官方没有公布。精确型号官方规格已作为目录缺项的后备来源,源码2bd7b24a、独立67/67与网页4组通过,未部署。见[官方容量纠正](QA-CLAUDE-OFFICIAL-CAPACITY.md);下方正式旧程序与原研究状态保留为原时点。
来源固定于2026-11-06,中文目录305篇正文及201份嵌入OpenAPI定义已逐项审读;API与Plugins均在覆盖范围。公开文档仓库提交d254f1842dc3d08d60f2269e2c9d4c9876a3dfbc。来源与SHA见[newapi-documentation-sources-2026-11-06.json](newapi-documentation-sources-2026-11-06.json),逐篇阅读批次/笔记见[newapi-documentation-review-2026-11-06.json](newapi-documentation-review-2026-11-06.json),计划见[NEWAPI-DOCUMENTATION-REVIEW-PLAN.md](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、序列化请求、用量与回归结果见[兼容复核验收](QA-NEWAPI-COMPATIBILITY-REVIEW.md)。Gemini原生/媒体、服务端工具和插件宿主是独立功能差距;真实供应商兼容、角色收益、普遍重复读取改善与Purge收益仍需新实验。
研究尚未操作正式服务、真实Key或模型请求;原400缺max_tokens、网络异常、重复读取、unknown用量与Purge收益unknown保持。仅学习不自动打包或重启。