2.12.0 API 文档迭代记录
文档基线:
v2.11.0@24340922a9c28861bdb26f9971946e0c7039b2c9;目标分支v2.12.0。全量 26 篇 API 文档继承现有内容;本版端点、参数、权限与响应差异按版本证据核对。
语雀数据源创建及仓库、文档枚举示例通过标准输入传递团队令牌;变量示例改用普通配置值,避免将密钥示范为非密文变量。语雀接口尚未在线实测。
按服务发布代码补充记忆流水线版本试运行的创建、详情和列表契约;尚未在 Stress 调用。
按服务发布代码补充切片更新的检索启停及版本参数,修正示例请求与响应不一致;尚未实测。
按服务发布代码补充文档解析产物状态及 Markdown 内容接口;尚未实测。
按发布源码修正语雀团队数据源的必填团队 ID、凭据更新与版本化边界,并校正创建响应、同步状态及统计示例;尚未实测语雀同步。
按发布源码修正知识索引能力配置参数、默认值和示例;尚未实测。
按服务发布源码修正
documentTag的写入及多标签筛选说明;尚未实测。其余新增、行为变化、废弃及迁移条目待核对;中英文均有正文,日文尚未提供。
master 已合入的历史增量与验证记录
以下为 PR #32 合并时的历史记录,反映当时的源码、测试与截图证据;不代表本次整合后的候选已经完成验证。
| 版本 | 2.12.0 |
|---|---|
| source_repository | git@code.alipay.com:obai/appbase.git |
| source_tag | v2.12.0 |
| source_commit | 1b75b0e57db3b46dce1a04d48f75aa695c4eb6a6 |
| previous_source_tag / previous_source_commit | v2.10.0 / 0a5d23f9349028496286572fd43117aa6f8fce0a |
| docs_base_commit | caddb6c90d76246e760238f4150701315a359b14 |
| 生成日期 | 2026-11-18 |
| 分支 / 目标 | v2.12.0 → master,人工评审合并 |
首次生成时三个 master 索引最新登记的是 2.10.0。本分支的 2.11.0 属未冻结服务的发布准备记录,本次不改写该历史;精确差分基准见产品记录。
新增端点
Server spec:590 → 710 paths;归一化比较参数/响应等结构,忽略说明文案与认证说明格式变动,共新增 151 项操作、结构变更 20 项,无删除路径。下表只登记符合项目功能 × 项目 Key 范围的增量;全路径增长不等于所有新增接口均属于本目录。
| HTTP | 功能文档 |
|---|---|
GET /ai-gateway/approval-requests | 对应契约 |
GET /ai-gateway/approval-requests/{id} | 对应契约 |
POST /ai-gateway/approval-requests/{id}/approve | 对应契约 |
POST /ai-gateway/approval-requests/{id}/reject | 对应契约 |
GET /ai-gateway/initialization-status | 对应契约 |
GET /ai-gateway/tool-embeddings | 对应契约 |
POST /ai-gateway/tool-embeddings | 对应契约 |
GET /projects/{projectId}/schedules | 对应契约 |
POST /projects/{projectId}/schedules | 对应契约 |
GET /projects/{projectId}/schedules/{scheduleId} | 对应契约 |
PATCH /projects/{projectId}/schedules/{scheduleId} | 对应契约 |
DELETE /projects/{projectId}/schedules/{scheduleId} | 对应契约 |
POST /knowledgebases/project-scopes | 对应契约 |
GET /knowledgebases/project-scopes/{projectId} | 对应契约 |
PATCH /knowledgebases/project-scopes/{projectId} | 对应契约 |
GET /knowledgebases/{knowledgeBaseId}/document-directories | 对应契约 |
POST /knowledgebases/{knowledgeBaseId}/document-directories/count | 对应契约 |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/content | 对应契约 |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact | 对应契约 |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact/content | 对应契约 |
GET /knowledgebases/{knowledgeBaseId}/enhancement-operations | 对应契约 |
POST /knowledgebases/{knowledgeBaseId}/enhancement-operations | 对应契约 |
GET /knowledgebases/{knowledgeBaseId}/enhancement-operations/{operationId} | 对应契约 |
POST /knowledgebases/{knowledgeBaseId}/enhancement-operations/{operationId}/cancel | 对应契约 |
POST /knowledgebases/{knowledgeBaseId}/graph/search | 对应契约 |
GET /knowledgebases/{knowledgeBaseId}/lexicons | 对应契约 |
PUT /knowledgebases/{knowledgeBaseId}/lexicons | 对应契约 |
POST /knowledgebases/{knowledgeBaseId}/wiki/search | 对应契约 |
GET /lexicons | 对应契约 |
POST /lexicons | 对应契约 |
GET /lexicons/{lexiconId} | 对应契约 |
PATCH /lexicons/{lexiconId} | 对应契约 |
DELETE /lexicons/{lexiconId} | 对应契约 |
GET /lexicons/{lexiconId}/entries | 对应契约 |
POST /lexicons/{lexiconId}/entries | 对应契约 |
GET /lexicons/{lexiconId}/entries/{entryId} | 对应契约 |
PATCH /lexicons/{lexiconId}/entries/{entryId} | 对应契约 |
DELETE /lexicons/{lexiconId}/entries/{entryId} | 对应契约 |
GET /lexicons/{lexiconId}/export | 对应契约 |
POST /lexicons/{lexiconId}/import | 对应契约 |
POST /lexicons/{lexiconId}/preview | 对应契约 |
GET /lexicons/{lexiconId}/references | 对应契约 |
GET /memory/memories/profiles | 对应契约 |
GET /memory/pipeline-runs | 对应契约 |
POST /memory/pipeline-runs | 对应契约 |
GET /memory/pipeline-runs/{runId} | 对应契约 |
POST /observability/reports/agents | 对应契约 |
POST /observability/reports/overview | 对应契约 |
POST /observability/reports/quality | 对应契约 |
GET /observability/trace-analyses | 对应契约 |
POST /observability/trace-analyses | 对应契约 |
GET /observability/trace-analyses/{analysisId} | 对应契约 |
POST /observability/traces/analysis | 对应契约 |
GET /powercontext/subjects/{subjectId} | 对应契约 |
GET /scenarios | 对应契约 |
POST /scenarios | 对应契约 |
GET /scenarios/categories | 对应契约 |
POST /scenarios/categories | 对应契约 |
DELETE /scenarios/categories/{categoryId} | 对应契约 |
GET /scenarios/categories/{categoryId}/deletion | 对应契约 |
PATCH /scenarios/categories/{categoryId}/knowledge-binding | 对应契约 |
PATCH /scenarios/categories/{categoryId}/name | 对应契约 |
POST /scenarios/import | 对应契约 |
POST /scenarios/import/parse | 对应契约 |
POST /scenarios/import/preview | 对应契约 |
GET /scenarios/{scenarioId} | 对应契约 |
PATCH /scenarios/{scenarioId} | 对应契约 |
DELETE /scenarios/{scenarioId} | 对应契约 |
变更端点
| HTTP | 更新 |
|---|---|
GET /avatars/screenshots | 参数与响应 |
POST /functions | 参数与响应 |
PUT /functions/{functionId} | 参数与响应 |
POST /knowledgebases/search | 参数与响应 |
GET /knowledgebases/{knowledgeBaseId}/documents | 参数与响应 |
POST /knowledgebases/{knowledgeBaseId}/documents | 参数与响应 |
POST /knowledgebases/{knowledgeBaseId}/documents/batch | 参数与响应 |
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId} | 参数与响应 |
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId} | 参数与响应 |
GET /knowledgebases/{knowledgeBaseId}/graph | 参数与响应 |
POST /knowledgebases/{knowledgeBaseId}/search | 参数与响应 |
GET /knowledgebases/{knowledgeBaseId}/wiki/graph | 参数与响应 |
GET /knowledgebases/{knowledgeBaseId}/wiki/pages | 参数与响应 |
POST /llm-gateway/rerank | 参数与响应 |
POST /memory/memories | 参数与响应 |
POST /memory/memories/search | 参数与响应 |
POST /memory/pipelines/{pipelineId}/validate | 参数与响应 |
GET /observability/traces/{traceId} | 参数与响应 |
废弃端点
无删除路径。旧单 Cron 视图仅投影 compact 任务;调度响应 schedule 由原文升级为 JSON 规则字符串,请求兼容不代表响应逐字一致。
功能点文档增删改
全量 26 篇 API 文档(中文与英文同名各 26 篇),新增 scenarios.md;其余原路径保持。Functions、知识库、Memory、Agent Runtime/PowerContext、网关、Observability 与 Avatars 增量直接并入原功能页,包含逐参数约束、成功响应模型与字段、Scope 和 SDK 映射。无新增日文目录。
逐语言状态
zh-CN/en-US:对应主题与 HTTP 标识同步;生成 spec 的英文参数描述保留原义。ja-JP:未产出。历史版本记录不回写。
证据缺口与范围排除
spec 固定于 SDK v2.12.0 revision 8f4e7cea6be643da2728cb47c64bc53638320d0a;build.json 绑定首次 appbase 快照
2546f7ed91dc5b93380d3dca02f5f0a938301823;本次重刷的公开接口面未变,详见下文。不是在线逐端点调用验收。账户发码/认证、agent-runtime/agents 的组织管理、个人语雀 Session/JWT 接口排除;Data API 管理无显式项目 Key security,public query 接口依赖自身凭据链,均不扩大为本目录的项目 Key 契约。
生成 spec 的 Functions timezone 枚举发生变化;参数表只展示前 8 个示意项,完整 IANA 名称以实例接受值为准。增强 scope 的 spec 默认值大小写与 enum 有差异,示例显式传 knowledgebase,不依赖该默认。
在线模型质量、所有身份组合及七族 SDK 回归未执行。
继承的维护基线
此前版本分支正文已吸收 appbase release-2.10.2@0983b818445bcf261f54c41984ff0d66832ec201 的词库、项目级 Agent Runtime、Memory 与数据保留等维护修订。本次保留这些正文,不回写 master 已合并 2.10.0 历史页;当前新增变化仍按本页 source_commit 核对。该历史快照不替代 2.12.0 验收。
源码勘误:Scenarios Import/Create 与 Import/Preview 的 entries validator 为 ArrayList(Assoc),实际接受对象数组;生成 spec 写成 array[array]、Node 类型为 any[][]。API 表按服务端真实 JSON 形状修正,SDK 示例使用 JavaScript;这是已记录的上游类型缺口,未在本任务改 SDK 仓库。
首次交付核验(旧源码快照,PR #32)
评审 PR #32,v2.12.0 → master,禁用自动合并。master 冲突整合后 326 项 unittest 全部通过;313 对中英文检查通过;渲染引用检查无悬空文件、图片或片段。13 段新增 Node 原文示例 / 21 次本地 HTTP、42 项 Console 鉴权原文测试、Java 编译及制品摘要校验通过。截图缺口与在线回归边界维持上述记录,未创建文档 tag 或 Release。
未封板同版本重刷(2026-11-18)
当前服务来源为 v2.12.0@1b75b0e57db3b46dce1a04d48f75aa695c4eb6a6,本次差分 2546f7ed91dc5b93380d3dca02f5f0a938301823..1b75b0e57db3b46dce1a04d48f75aa695c4eb6a6;docs 基线 caddb6c90d76246e760238f4150701315a359b14,首次生成基线 7a27c8332dae064128a92a71fd62b65c74f1f279 保留供追溯。
本区间新增端点:无;变更公开端点/参数/响应/schema/scopes:无;废弃端点:无;migration:无。差分 27 个文件均为沙箱诊断、Memory 内部路由及相关测试/说明;API controller、SDK 源码和 Console 目录 Git tree 未变,摘要登记在发布证据的 source_refresh。沿用首次 Release spec,而非声称已重新生成或逐端点在线验收。
Memory 内部签名上下文与连接池登记现在接受合法的含连字符库名,仍检查 namespace、路由身份和登记库名精确匹配;该内部协议不扩展为项目 Key 的公开参数。中文/英文 memory/overview.md 补充客户端边界,端点数与语言主题数不变。沙箱文件采集协议不属于公开 Server API,不新增接口页。
SDK 构建来源与本次服务快照分别登记,见SDK 记录;部署与真实模型/线上回归未验证。首次交付测试与截图不作为当前 commit 的部署证明。
本次文档门禁:326 项 unittest 与 313 对双语校验通过,包含渲染后的文件、图片和锚点检查;本次未新增 HTTP 调用示例。完整验证摘要见产品记录。
上轮重刷评审(已关闭,由迭代分支 PR 接替):PR #33,v2.12.0 → master,reviewer chengyao.cp,排除提交者本人;禁用自动合并,等待人工评审。
保护迭代分支与发布交付(2026-11-18)
按最新交付约定,v2.12.0 从 master@caddb6c90d76246e760238f4150701315a359b14 重新创建并保护:push/merge access level 均为 40,master_can_edit=true,禁止分支强推。现有文档改动保留在 docs/v2.12.0-sync,目标改为 v2.12.0;评审人为派蒙(pm02597234),启用合并后删除来源分支、Squash merge、评审与检查通过后自动合并。原始文档基线与旧 PR 验证记录保留,旧 PR #33 已关闭。
本轮只调整文档交付目标与打包上限;公开 HTTP 契约沿用上文源码差分结论,无新增端点、参数或 API 示例。双制品与截图台账见产品记录,SDK 发布事实见SDK 记录。
本次交付评审:PR #34。已回读确认 source=docs/v2.12.0-sync、target=v2.12.0、reviewer=pm02597234,合并后删源分支、Squash merge、自动合并均为 true。
2.11 分支历史记录汇合
合并 2.11 分支时,保留其关于知识库检索参数与响应、Functions 部署与执行列表以及 2.10.2 源码基线的 API 说明的历史记录。为保持已冻结的 2.10 变更记录字节不变,原文留在所链接的固定提交;其中的历史候选、截图和验证结论不代表本次重新验收。