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 编程语言重复写)
分组两个正交轴:功能轴的功能点文件平铺语言树一级目录(账号级在 account/、组织级在 organization/;项目功能不建 project/ 包裹目录),承载全部功能点正文;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 只增不改

当前状态:通用接入、语言示例与已更新功能页采用 SDK 2.10.0 发布坐标;Java 与 JavaScript 的 TablesDB 建表示例均明确给索引配置非空列键,Java Functions 示例明确异步执行参数与返回 ID 轮询方式,Storage/Functions 代码块列出所用 SDK 类型导入。Console Java 认证改用当前制品的 setCookie,并校准项目创建、配额和用量方法;相关 20 个 Java 片段已通过官方 2.10.0 JAR 离线编译,在线调用另行验收。Memory 专项完整 Node.js 流程仍保留 SDK 2.9.0 的模拟传输验证记录;该记录不代表与服务 2.10.0 的完整在线兼容验证,边界见本目录 changelogs/2.10.0.md 的兼容补充(Skill 对应文件为 skills/ob-agentbase/references/compatibility.md)。en-US / ja-JP 保持骨架态。迭代来源与验证边界见产品维护记录。

目录结构

sdks/
├── README.md                本文件:入口、框架、功能分组索引
├── AGENTS.md                生成与更新规则(含功能点清单与归属判据)
├── zh-CN/                   源语言树(首产、全量承载);en-US/、ja-JP/ 跟进(骨架态 = 目录不存在)
│   (每棵语言树内结构完全同构:)
│   ├── integration.md       接入代码仓库:npm(远程 registry)与非 npm(源码引用)
│   ├── environment.md       endpoint / region、托管与自托管实例差异
│   ├── troubleshooting.md   常见错误速查与排查路径
│   │   ── 功能轴(正文只在这里:功能点文件平铺一级目录,资源层级仅是分类口径)──
│   ├── account/ organization/   账号级与组织级功能子页
│   ├── <功能点>.md          单页项目功能:storage、functions、messaging、sites、
│   │                          realtime、moderation、agent-runtime、usage、deployment
│   ├── <功能点>/            多话题项目功能:overview、auth、databases、knowledge-base、
│   │                          models-ai-gateway、memory、observability、misc
│   │   ── 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.9.0 并含 2.10.0 增量)
账号级account/authentication.md、account/profile.md登录认证与账号自身已产出(zh-CN,基于 2.9.0 并含 2.10.0 增量)
组织级organization/organization.md、organization/project-governance.md组织管理、组织项目治理已产出(zh-CN,基于 2.9.0 并含 2.10.0 增量)
项目级overview/、databases/、auth/、storage.md、functions.md、agent-runtime.md 等(清单见 [AGENTS.md](AGENTS.md))项目及其库表、存储、函数、用户/团队、网关、知识库、观测与 Runtime已产出(zh-CN,基于 2.9.0 并含 2.10.0 增量)
SDK 轴client-sdk/、console-sdk/、server-sdk/各类 SDK 的初始化、认证与功能面映射已产出(zh-CN:client 1 + console 4 + server 4)
语言示例<lang>/examples/<language>.md每种 SDK 编程语言一份调用示例已产出 JavaScript / Java / Python / Go(zh-CN,示例坐标为 2.10.0;内容含 2.9.0 基线与 2.10.0 增量,历史交付缺口见 changelog)
迭代增量changelogs/<X.Y.Z>.md每迭代一个,入口 changelogs/README.md已登记 2.6.0 / 2.7.0 / 2.8.0 / 2.9.0 / 2.10.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 发布驱动)。