docs: review all New API articles and embedded API contracts

This commit is contained in:
Agent Workbench Dev
2026-11-06 20:13:03 +08:00
parent 234b76cc33
commit 6917603d21
6 changed files with 3958 additions and 2 deletions
+37
View File
@@ -0,0 +1,37 @@
# 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保持。仅学习不自动打包或重启。
+4 -2
View File
@@ -3,8 +3,8 @@
用户要求阅读 https://docs.newapi.pro/zh/docs 内全部文章,并用于纠正工作台的供应商兼容设计。以网站中文目录、站点地图和其公开 Markdown 导出建立文章清单;其它语言和站外材料只按引用需要补读,不混算中文文章覆盖。
1. [complete] 固定当前目录和原文:中文目录与站点地图305/305一致;305篇正文796445字节、201份嵌入接口387113字节,SHA与接口Git blob逐份通过。清单见newapi-documentation-sources-2026-11-06.json,原文在.qa/newapi-documentation-2026-11-06。
2. [in_progress] 逐篇阅读并形成主题笔记:产品/部署/管理、模型/渠道/映射/能力、三种核心模型协议、流式/工具/推理/缓存/用量、错误/限流、其它媒体与服务端接口。
3. [pending] 对照工作台现有实现,按文档条款定位已实现、缺陷、待验证及不属于本工作台的网关运营能力。上游示例和管理功能不自动成为本产品默认限制。
2. [complete] 逐篇阅读305/305正文、201/201接口定义并形成主题笔记;逐页批次独立于抓取,正文SHA/接口SHA与Git blob再次全部通过。见NEWAPI-DOCUMENTATION-LEARNING.md及newapi-documentation-review-2026-11-06.json。
3. [in_progress] 对照工作台现有实现,按文档条款定位已实现、缺陷、待验证及不属于本工作台的网关运营能力。上游示例和管理功能不自动成为本产品默认限制。
4. [pending] 对确定缺陷做独立修复,使用本机HTTP/原始请求响应/界面和回归验证;必要改动才构建发行,不用研究阅读触发正式安装。
5. [pending] 记录完整覆盖与缺项、主要纠正、原异常和后续工作;阶段回顾、本地提交及已授权的普通增量推送。
@@ -13,3 +13,5 @@
已知入口:`.pro` 页面实际可读,HTML canonical/robots/sitemap 指向 `.ai`,根 llms.txt 指向其公开 `docs2.newapi.pro` Markdown导出。`/zh/docs.md`为404,改按站点提供的LLM来源核对,不能把下载成功当阅读完成。
阶段一回顾:全文导出797053字节,省去了201篇API组件正文,不能单凭全文导出宣称全量学习。另取文档页面引用的接口定义,固定文档仓库d254f1842dc3d08d60f2269e2c9d4c9876a3dfbc。公开静态接口路径404、raw.githubusercontent连接中断保留,改用GitHub blob及固定提交的公开CDN并逐Git blob核对。研究0真实模型请求、不读Key、不操作正式服务。
阶段二回顾:正文/API/插件/新旧更新日志全部逐项读过;略去重复下载HTML和编辑器扩展,图片未逐像素读图。文档存在旧功能清单与新日志、示例与schema、管理未解析引用等差异,已单列,不能把生成schema当所有原厂能力的完整规范。305/201阅读覆盖与全部来源原字节复核通过;源码调查输出过量/猜测路径缺失仅只读,改用真实路径分段读取;一次计划patch因上下文不符未应用,已纠正。确认已有目录apply跳过元数据刷新、Messages截断说明不符实际wire,准备独立切片修复。
File diff suppressed because it is too large Load Diff
+2
View File
@@ -1351,3 +1351,5 @@ Messages原错误已定位anthropic-messages.mjs透传分支省略协议必填ma
F发行复核:大文件原240/300秒仅超时,原33文件/超过2MB断言独立459183ms通过;评测原20秒等待并发超时、同断言独立15389ms通过,不擅自改产品额度或认证根因。核心38/39和5/6原结果保持。随包协议、两端角色、基础文件编辑保存和核心流程通过;旧文件按钮入口验收器重复失败说明必须复用已实看的Orven文件搜索,不凭旧DOM假设。源码795输入/29编译字节与实际旧版跨版均精确,候选来源6867cd5a不随后续QA文档提交变化。恢复过程只读路径缺失、输出截断和一次未匹配文档patch均纠正,未产生正式数据改变。
F正式回顾:异步模型卡片必须等待真实字段再断言count,首失败保留而不重复安装。实际Claude连接没有同步最大容量,其旧声明2048会成为Messages必填输出值;修复缺失字段并不等同移除该协议输出参数,也不等同知道上游上限。须公开这个限制并独立调查容量来源,不能猜模型能力、改旧配置或声称真实线路已修。正式两端和最终原数据已再次exact,150份原证据封存,后续只提交记录/普通增量推送。
New API学习:305正文/201嵌入定义已分别审读;来源清单与逐篇批次独立保存。三原生协议/推理/工具/缓存语义不能混用,网关额度/计费不是工作台默认限制;插件指南与rc.40/43/47、旧账户接口与rc.34存在版本差异。生成API schema还含简化枚举、Responses用量示例与未解析管理引用。结论/差距见docs/NEWAPI-DOCUMENTATION-LEARNING.md。确认目录apply已有项continue未刷新、透传截断说明无视Messages/显式输出字段,独立修复后本机验证,不改正式配置。
+2
View File
@@ -2015,3 +2015,5 @@ F验证记录已提交2af369cd。正式before成功:1.25.11/PID71628、102项
F正式交付收口:唯一安装239133ms保留PID71628/Provider/原instance;正式网页首轮在卡片加载前count失败,原0写入和DOM保留,第二独立4组/实际Electron5组通过。DOM确认原Claude2048声明目前仍用于Messages必填字段,未获得上游最大值;不能用本地不限掩盖此边界,已明确单列,未更改用户配置。正式回看后严格final全部原行/导出/工件/模型中心再次exact,150份58198224字节索引和发行身份已生成。源码6867cd5a不变,本轮0真实模型;下一最终提交/增量推送,再独立容量来源调查。
F源码与交付记录828208a7已增量推送,GitAtlas同分支逐SHA一致。继续只读容量调查:匿名模型详情401、公开文档未取得具体型号容量;无凭据请求或真实模型。发现已有连接目录apply跳过元数据更新,及Messages截断沿旧“未附加输出额度”通用说明,均作为下一独立切片保留,未倒改F已冻结源码或已封存150份原件。最后提交回执/接续并再推送核对。
New API研究阶段一234b76cc已提交;阶段二逐篇305正文/201接口全部审读,来源SHA与接口Git blob再校验通过。阅读覆盖JSON含批次/实际笔记,图片不冒称逐像素验收。输出截断/猜测只读路径不存在和一次未匹配计划patch保持为调查失误,无正式写入。准备提交阶段二,随后独立修确认缺陷;0真实模型请求,不读Key,不操作正式进程。
+2
View File
@@ -1067,3 +1067,5 @@ F收尾:57d075e修正独立编译QA路径,6d09ac8封存差异;202610302320
## New API 中文文档全量复核(2026-11-06)
用户要求完整学习 https://docs.newapi.pro/zh/docs。按docs/NEWAPI-DOCUMENTATION-REVIEW-PLAN.md建立逐篇清单与阅读笔记,再对照协议/模型同步/推理/缓存/错误/用量实现修复;先确认中文文章总量与公开Markdown实际覆盖,不以下载量冒充阅读量。当前正式仍1.25.12,研究不操作真实模型/Key/用户工程,不委派。
来源冻结234b76cc后,305正文/201接口已逐项读完并重核SHA/Git blob,API与Plugins覆盖完整;学习笔记和逐篇批次已保存。下一只修确认的已有连接目录刷新和实际wire截断说明,保持用户配置和原证据;Gemini原生/媒体不是仅靠目录条目就已经实现,作为差距记录。