AgentbaseDocs
文档目录

sdks/ — SDK 使用文档(单份全量,就地增量)

文档类型:面向使用者的 SDK 文档——如何把 Agentbase SDK 接入代码仓库、如何使用。与 skills/ob-agentbase/references/ 的分工:那侧是给 AI 代理消费的 canonical 指引(含 evals),本侧是给人读的 SDK 使用文档。

生成框架

维度约定
驱动事件agentbase-sdks 完成一版发布(tag vX.Y.Z + Release 附件 + npm 六坐标)
产物形态单份全量 × 按文档语言分树:master 上只有一份、永远指向最新一版,每迭代就地增量刷新(不按版本建目录);正文按文档语言分树 sdks/<lang>/(zh-CN 源语言首产,en-US/ja-JP 跟进,骨架态 = 目录不存在),树间文件集一一同名对应
接入方式两条路径分开写:npm 面(web / node / console)从远程 registry 下载;Java / Python / Go 未发布到 registry,交付为 Release 的 ZIP 附件,需在源码仓库中引用。两条路径的获取与校验形态不同,故独立成一份接入文档
功能点每个功能点一份文档,描述语言无关的使用骨架(同一棵语言树内不按 SDK 编程语言重复写)
分组两个正交轴:功能轴的功能点文件平铺语言树一级目录(资源层级——账号级 / 组织级 / 项目级——只是分类口径,不建子目录),承载全部功能点正文;SDK 轴 client-sdk/ / console-sdk/ / server-sdk/ 只写各类 SDK 的初始化与调用差异(**按语言一文件 <language>.md**)
使用示例每种 SDK 编程语言一份:<lang>/examples/<language>.md(javascript / java / python / go …)
每迭代动作就地上刷各语言树正文与示例(各语言同批或逐语言推进) → 在 changelogs/ 新增本迭代增量说明(含逐语言产出状态)
历史历史迭代留在 Git 提交与已存在的 tag 中;已合并的 changelogs/<X.Y.Z>.md 只增不改

当前状态:迭代 2.9.0 已就地上刷 zh-CN 正文(functions.md 补执行路径查询与 Web SDK 拦截边界、models-ai-gateway/llm-gateway.md 补厂商预置目录与 listProviderPresets、moderation.md 补 post/hybrid 与 requireManualReviewOnViolation、observability/overview.md 补 2.9.0 增量小节、knowledge-base/overview.md 补 embeddingDimension / tracingEnabled / answer;坐标钉 npm 三包 agentbase-*-sdk@2.9.0、Java/Python/Go ZIP 钉 v2.9.0 release 终态(release id 1300 实查),随迭代分支 v2.9.0 的 PR 交付);en-US / ja-JP 为骨架态(目录不存在)。版本事实与交付坐标见 [changelogs/2.9.0.md](changelogs/2.9.0.md)。

目录结构

sdks/
├── README.md                本文件:入口、框架、功能分组索引
├── AGENTS.md                生成与更新规则(含功能点清单与归属判据)
├── zh-CN/                   源语言树(首产、全量承载);en-US/、ja-JP/ 跟进(骨架态 = 目录不存在)
│   (每棵语言树内结构完全同构:)
│   ├── integration.md       接入代码仓库:npm(远程 registry)与非 npm(源码引用)
│   ├── environment.md       endpoint / region、托管与自托管实例差异
│   ├── troubleshooting.md   常见错误速查与排查路径
│   │   ── 功能轴(正文只在这里:功能点文件平铺一级目录,资源层级仅是分类口径)──
│   ├── <功能点>.md          账号级:authentication、profile;
│   │                          组织级:organization、project-governance;
│   │                          项目级及项目内各功能:overview(项目)、databases(含 sql-proxy)、
│   │                          storage、functions、users、teams、messaging、sites、
│   │                          realtime、memory、knowledge-bases、llm-gateway、
│   │                          ai-gateway、observability、moderation、agent-runtime、limits、
│   │                          usage、deployment、misc(webhooks、graphql、avatars、locale、health)
│   │   ── SDK 轴(只写「这一类怎么调」,按语言一文件)──
│   ├── client-sdk/web.md  ① 客户端 SDK(Web,用户 Session)
│   ├── console-sdk/{nodejs,java,python,go}.md  ② Console SDK(管理面 Session / 短期 JWT)
│   ├── server-sdk/{nodejs,java,python,go}.md   ③ Server SDK(API Key)
│   └── examples/<language>.md   每种 SDK 编程语言一份使用示例
└── changelogs/              每迭代一个 <X.Y.Z>.md(语言无关:SDK 侧增量 + 逐语言产出状态)

结构与 appwrite.io/docs(Products 按功能 × Platforms 按 SDK × 多文档语言)、supabase.com/docs(Guides 按功能 + Reference 按语言)同构:功能轴承载正文、SDK 轴是平台参考、SDK 编程语言差异进 examples、文档语言差异 = 整树对应。products/ 手册的功能轴(根文件 + 平铺一级目录的功能点文件)与本文同一套口径。

归属判据(决定正文落在哪一份):功能点正文一律落平铺语言树一级目录的功能点文件;「资源挂在哪一层」(账号 / 组织 / 项目)只是分类口径,不再以 account/ / organization/ / project/ 子目录表达。SDK 轴目录不承载功能点正文,只以功能面映射表逐项链接。不属于任何资源层级的通用主题(接入、endpoint/region、错误速查)落根文件。完整清单与逐项 references/ 映射见 [AGENTS.md](AGENTS.md)。

语言面与获取方式

语言面分发形态获取方式文档
JavaScript — web(浏览器)/ node(服务端)/ console(管理面)npm 包,双面发布(public agentbase-*-sdk / 内部 @alipay/agentbase-*-sdk)从远程 registry 下载安装(写精确版本号,不写 latest/范围)integration.md
Java — server / consoleRelease ZIP 附件(内层为 Java 生态制品,双层 SHA-256 校验)未发布到 registry,需在源码仓库中引用(放 JAR / 本地安装,按实际附件内容选用)integration.md
Python — server / consoleRelease ZIP 附件(内层为 Python 生态制品)未发布到 registry,需在源码仓库中引用(本地 wheel 路径 / 离线安装)integration.md
Go — server / consoleRelease ZIP 附件(内层为 Go 模块源码)未发布到 registry,需在源码仓库中引用(本地模块路径 / vendored 源码)integration.md

各语言面的精确坐标、附件名、内层制品与校验模板以 agentbase-sdks 对应版本 Release 的实际内容为事实源(本文不预设;生成时按实际附件写)。本目录只写获取与使用方式,不复制 skills/ob-agentbase/references/ 的契约细节。

索引(功能分组)

组位置内容状态
通用integration.md、environment.md、troubleshooting.md接入两条路径;endpoint / region;错误速查已产出(zh-CN,2.6.0)
账号级authentication.md、profile.md登录认证与账号自身已产出(zh-CN,2.6.0)
组织级organization.md、project-governance.md组织管理、组织项目治理已产出(zh-CN,2.6.0)
项目级overview/、databases/(含 sql-proxy)、storage.md、functions.md、users.md、teams.md、agent-runtime.md……(清单见 [AGENTS.md](AGENTS.md))项目本身 + 项目内各功能(库表、存储、函数、用户、团队、网关、RAG、观测、Agent Runtime……)已产出(zh-CN,2.6.0)
SDK 轴client-sdk/、console-sdk/、server-sdk/各类 SDK 按语言一文件的初始化、认证装载、功能面映射已产出(zh-CN,2.6.0:client 1 + console 4 + server 4)
语言示例<lang>/examples/<language>.md每种 SDK 编程语言一份(各文档语言树内),含真实调用写法已产出 javascript / java / python / go(zh-CN,2.6.0;python、go 按当前发布面 v2.7.0 坐标书写,2.6.0 无可证产物/无交付,见 changelogs/2.6.0.md 证据缺口)
迭代增量changelogs/<X.Y.Z>.md每迭代一个,入口 changelogs/README.md已登记 2.6.0

索引是唯一登记处——未经登记的正文文件不构成交付。各目录内的功能点清单与归属判据见 [AGENTS.md](AGENTS.md),首次生成按该迭代实际发布面裁剪。

硬边界

只放文本,绝不落二进制:SDK 制品(ZIP/JAR/wheel/二进制)一律不进本仓,只以 Release 链接与校验模板引用。校验器对非文本制品直接判失败。历史教训:早期版本的 ZIP 曾直接落本目录,之后迁出到 agentbase-sdks 的 Release 附件(本仓提交 48bb513),git 历史可考古但不重演。

一个能力只有一份正文:功能点正文只落平铺语言树一级目录的功能点文件,SDK 轴只做映射与调用差异;语言差异只进 examples/。

完整生成与更新规则见 [AGENTS.md](AGENTS.md),迭代增量索引见 [changelogs/README.md](changelogs/README.md),总迭代节奏见仓库根 [AGENTS.md](../AGENTS.md)(本目录属步骤③,SDK 发布驱动)。