AgentbaseDocs
文档目录

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

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

生成框架(完整规则见 [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.10.0 已就地上刷 zh-CN 手册(62 个正文文件:新增智能体域 agent-runtime/ 5 篇独立专题,完整覆盖项目级智能体工作台概览与启用、模型/提示词/上下文精简与词库拦截配置、多轮会话与可恢复 SSE 事件流、挂载知识库/长期记忆/PowerContext 协同,以及绑定 AI Gateway/Client Tool/Skill 技能包;知识库域 knowledge-base/ 扩充至 10 篇独立专题,完整覆盖概览、文档分块、外部数据源与语雀同步、GraphRAG/RAPTOR 索引构建、知识图谱可视化、LLM Wiki 百科与冲突提案、混合检索、多版本工作副本、项目词库与多模态设置;记忆域 memory/ 统一归口并扩充至 12 篇独立专题,完整覆盖概览、三层时效 × L0–L3 多层认知架构、记忆读写与多模态、用户画像、经验与技能知识蒸馏、自进化二次确认与回滚、分层上下文 Dreaming 治理、艾宾浩斯遗忘与保留治理、模型路由与稀疏向量、四类 Pipeline 配置中心、请求审计及链路追踪;台账见 [changelogs/2.10.0.md](changelogs/2.10.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/ 功能轴——通用主题落根文件,账号级功能点在 account/、组织级在 organization/;项目功能点与根文件同级平铺在语言树一级目录(完整路径和导航顺序见 [AGENTS.md](AGENTS.md) 基线表,不建 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(其每版本一条版本分支、顶层按语言分树)。

迭代索引(按实际目标分支登记)

版本源 tag / 源 commit迭代分支(已合并)说明
2.6.0v2.6.0 / 8c9beb4713496d051a477f03fd843365145d3b86v2.6.0中文首版;历史版本记录见 changelog
2.7.0release-2.7.0 / 34b7c8633813a8fe75cc58e8348bd4a9efdd0e21v2.7.0中文正文增量,已合入 master
2.8.0v2.8.0 / ea835e462085decbbf49ab7fd6a0e99928be72a9v2.8.0中文正文增量,已合入 master
2.9.0v2.9.0 / ebae954094883b847bf582cfbe9fbe58ae0a7499v2.9.0中文正文增量,已合入 master;英文/日文未产出
2.10.0v2.10.0 / 0a5d23f9349028496286572fd43117aa6f8fce0av2.10.0中文正文增量,非 Memory 更新已进入本迭代分支,Memory 专项 PR14 与规范 PR15 已合入 v2.10.0;master 尚未同步;英文/日文未产出

同一迭代的增量说明另记 [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」。

历史与版本记录

截图按正文页面同构存放在语言树的 assets/,各页面独立引用;当前路径调整见当迭代追加记录。