AgentbaseDocs
文档目录

products/ — 全量用户手册(固定路径,按语言分树)

文档类型:产品全量用户手册——master 上只有一份、永远是最新一版,路径固定为 products/,不按版本建目录;正文结构**镜像 sdks/ 功能轴(通用主题根文件 + 功能点文件一律平铺语言树一级目录,不设层级子目录),无章节编号**。

生成框架(完整规则见 [AGENTS.md](AGENTS.md),总迭代节奏见仓库根 [AGENTS.md](../AGENTS.md)):

维度约定
驱动事件appbase 出现 release-X.Y.Z 迭代分支
产物形态单份全量、就地增量修改;按语言整棵分树 products/<lang>/(lang ∈ zh-CN, en-US, ja-JP——三语集合与 sdks/、apis/ 全仓一致)
语言入口本文件(products/README.md)——目录里没有 SOURCE.md/SUMMARY.md
版本事实版本号 / 源 tag / 源 commit / previous commit / 冻结的 docs 基线 SHA / 生成日期 / 逐语言状态 / 截图台账,全部记在当迭代的 [changelogs/<X.Y.Z>.md](changelogs/README.md)(框架文件本身不写版本号)
截图按语言、按功能点就地存放 products/<lang>/assets/<功能点>/fig-<编号>-<slug>.png(<功能点> = 文档文件名去 .md),取自 SIT 环境(https://appbuild-sit.oceanbase.com/);不跨语言、不跨功能点引用
每迭代动作语言树正文与其 assets/ 就地增量刷新 → 在 changelogs/ 新增本迭代增量与版本记录页 → 索引表登记
历史历史版本留在 Git 提交与已存在的 tag 中,不在本目录堆叠

当前状态:迭代 2.9.0 已就地上刷 zh-CN 手册(23 个功能点文档,无新增/删除;moderation.md 补异步后置审核与人工复核、models-ai-gateway/llm-gateway.md 补厂商预置目录、observability 各页补 Observation 列表与评估解析任务类型、knowledge-base 补答案合成 / 层级标签 / 索引操作控制、functions.md 补执行路径查询、routes.md 路由表同步;SIT 实拍 32 张截图,本迭代新增 4 张——LLM Gateway 预设模型导入、Observation 列表、解析评估任务类型、文档标签视图,台账见 [changelogs/2.9.0.md](changelogs/2.9.0.md));en-US / ja-JP 为骨架态(目录不存在),已产出功能点的事实源为中文同名文件。

products/
├── README.md        语言入口与框架说明(本文件,目录唯一入口)
├── AGENTS.md        目录政策 + 功能点骨架基线(功能点目录的唯一登记处)
├── changelogs/      每迭代一个 <X.Y.Z>.md:产品侧与手册侧增量 + **版本记录**(语言无关,入口 changelogs/README.md)
├── zh-CN/           中文正文(源语言:首产、全量承载)+ en-US/、ja-JP/(骨架态 = 目录不存在);
│                    (每棵语言树同构——与 sdks/ 功能轴一致,功能点全部平铺一级目录:)
│                    根文件(what-is-agentbase、core-concepts、getting-started、faq、routes……)
│                    + 功能点文件(register-login、org-account、overview、auth、databases、storage、
│                    functions、models-ai-gateway、knowledge-base、memory、observability……)
│                    + assets/<功能点>/fig-*.png;无 SUMMARY.md

目录白名单:products/ 根只允许 README.md、AGENTS.md 两个固定文件与语言树、changelogs/——**没有 SOURCE.md/SUMMARY.md**(根或语言树内都不建);校验器拒绝其他任何顶层条目(含散落的 assets/ 或版本目录),防止产物逃逸到语言树之外。

多语约定:同一功能点文件路径在各语言中指同一主题,路径跨迭代稳定;语言集合 = zh-CN(源语言)、en-US、ja-JP。截图按语言、按功能点随身存放,正文只引用本语言、本功能点目录内的图。en-US/ja-JP 未产出的功能点,事实源是中文同名文件——不得用中文已就绪暗示其他语言已完成。功能点目录见 [AGENTS.md](AGENTS.md)「功能点骨架基线」。

功能轴分组:正文镜像 sdks/ 功能轴——通用主题落根文件,账号级 / 组织级 / 项目级功能点与根文件同级平铺在语言树一级目录(资源层级只是分类口径,登记在 [AGENTS.md](AGENTS.md) 基线表的层级列,不再以 account/ / organization/ / project/ 子目录表达;能力集合参考 appwrite.io/docs 与 supabase.com/docs 的平铺方式)。无章节编号:一个功能点一个文件,导航顺序即 [AGENTS.md](AGENTS.md) 基线表顺序;分组规则与演化约定见该文件(语言树内无 SUMMARY.md)。

定位:面向用户 Console 使用的产品介绍手册——写 Console 各功能是什么、在哪、怎么用。部署运维、版本迁移、SDK/API 接入、Agent Runtime/Skill、商业订单等主题不设章(SDK 接入见 [../sdks/](../sdks/README.md),迭代增量见 [changelogs/](changelogs/README.md))。

功能点组织:一个功能点一个文件(多页内容折入正文小节),文件路径跨迭代、跨语言一一同名对应;无编号,导航顺序即基线表顺序。**功能点清单、数量与顺序只在 [AGENTS.md](AGENTS.md)「功能点骨架基线」一处登记**——本文件与仓库根文档只引用不重复(避免多处同步漂移);增删在当迭代 [changelogs/<X.Y.Z>.md](changelogs/README.md) 留档并随 PR 评审同步基线表,退役功能点路径不复用。

对外发布:手册正文给外部用户看,products/<lang>/ 整棵树直接上传产品文档站点。每棵语言树是自包含上传单元——正文链接与截图只落在本语言树、本功能点目录内(不引另一语言树、changelogs 或仓库工程文件),外链只写对外稳定地址,截图按 assets/<功能点>/fig-<序号>-<slug>.png 稳定命名、归其正文页所有、换图不改正文;站点上传时按「<lang>/ → 语言空间、<功能点>.md → 功能点页、assets/ → 图片资源」一条规则机械替换。工程事实(commit、SIT、迭代记录)只进 changelogs/,不进正文。

交付方式(迭代分支 + PR,人工合并)

每迭代从**最新 master 冻结 SHA** 建出本迭代的迭代分支 v<X.Y.Z>(同名分支已存在则续做该分支,不另起平行分支),生成结果提 PR 到 master,由人工评审合并。协调入口:

python3 automation/prepare_docs.py --repo <repo> --version X.Y.Z --destination <new-worktree>
# 输出 JSON:docs_base_commit / branch=vX.Y.Z / target_branch=master / worktree
# 之后在新 worktree 内生成、校验、commit,只推送迭代分支,再提 PR(目标 master,人工合并):
#   git push -u origin vX.Y.Z
#   antcode pr create vX.Y.Z master "docs(products): X.Y.Z 用户手册" \
#     -P obai/agentbase-docs --no-auto-merge --review-required

本流程不自动 commit / push 到 master / merge / 打 tag / 建 release。主题组织与分支贡献方式参考 oceanbase/oceanbase-doc(其每版本一条版本分支、顶层按语言分树)。

迭代索引(master 已合入的迭代)

版本源 tag / 源 commit迭代分支(已合并)说明
2.6.0v2.6.0 / 8c9beb4713496d051a477f03fd843365145d3b86v2.6.0首次迭代;分支基线 675d1b0(新框架线,与 origin/master 尖端 08f1d0d… 待人工合并);已产出语言 zh-CN(en-US / ja-JP 未产出);合并日期待 PR 评审后确认

同一迭代的增量说明另记 [changelogs/<X.Y.Z>.md](changelogs/README.md)——产品侧(Console / API / 配置行为变化)与手册侧(章节增删改、逐语言状态、截图台账变化)合成一页,迭代分支在 PR 内同步新增并在 [changelogs/README.md](changelogs/README.md) 索引表登记。

登记约定:迭代分支在 PR 内补一行(版本 / 源 tag / 40 位源 commit / 冻结的 docs 基线 SHA / 迭代分支 / 合并日期 / 已产出语言)。只登记实际发生的事实:未打 tag 就写「未打 tag」,未建 release 就写「未建 release」。

历史与版本记录