Docs
文档目录

2.12.0 API 文档迭代记录

master 已合入的历史增量与验证记录

以下为 PR #32 合并时的历史记录,反映当时的源码、测试与截图证据;不代表本次整合后的候选已经完成验证。

版本2.12.0
source_repositorygit@code.alipay.com:obai/appbase.git
source_tagv2.12.0
source_commit1b75b0e57db3b46dce1a04d48f75aa695c4eb6a6
previous_source_tag / previous_source_commitv2.10.0 / 0a5d23f9349028496286572fd43117aa6f8fce0a
docs_base_commitcaddb6c90d76246e760238f4150701315a359b14
生成日期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:未产出。历史版本记录不回写。

证据缺口与范围排除

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 变更记录字节不变,原文留在所链接的固定提交;其中的历史候选、截图和验证结论不代表本次重新验收。