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 / console | Release ZIP 附件(内层为 Java 生态制品,双层 SHA-256 校验) | 未发布到 registry,需在源码仓库中引用(放 JAR / 本地安装,按实际附件内容选用) | integration.md |
| Python — server / console | Release ZIP 附件(内层为 Python 生态制品) | 未发布到 registry,需在源码仓库中引用(本地 wheel 路径 / 离线安装) | integration.md |
| Go — server / console | Release 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 发布驱动)。