Files
Agent-Workbench/docs/NEWAPI-DOCUMENTATION-LEARNING.md
T
2026-11-06 20:13:03 +08:00

38 lines
5.2 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,中文目录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 |
## 已确认的工作台后续差距
1. 已有连接目录apply直接跳过,未刷新upstreamModel;应只更新目录来源,保留用户原生参数、名字、覆盖、凭据归属和启停。
2. 截断提示通称未附加输出额度,对Messages必填值/用户原生值不准确;应依据实际wire说明。
3. 正式1.25.12 Claude旧声明2048仍被用于Messages必填max_tokens,未取得此型号权威最大值;不能声称同步了最大值,不能用0表示无限。
研究尚未操作正式服务、真实Key或模型请求;原400缺max_tokens、网络异常、重复读取、unknown用量与Purge收益unknown保持。仅学习不自动打包或重启。