AgentHub 开发者文档

Appearance

AgentHub 对外指南总索引（SaaS 开发者入口） ​

你是谁，从哪篇读起——本页是所有「基于 AgentHub 孵化 / 集成 AI SaaS」的开发者（人类工程师或 AI coding agent）的唯一入口。 契约事实源：本树所有端点 / 字段以 openapi.yaml（SSOT）为准；冲突时以 openapi 为准并回报本文档树勘误。 状态基准：2026-08-30（SM 波次收官：口语搭子试点真栈全链验收；ADR-0058 API + 模式 B 唯一使能路线）。 机器可读入口（AI agent 优先消费）：llms.txt

30 秒分流 ​

你有自己的用户体系 / 后端服务端？ ──是──► 模式 A：API-Key + 影子用户
                                          └─ saas-integration-cookbook.md（§0→§12 逐条 curl）

你要新起一个自营 / 孵化 SaaS，只想写前端？ ──是──► 模式 B：浏览器直连（平台 JWT）
                                          └─ saas-mode-b-integration-guide.md（模板 + ≤15 步）

你是 AI coding agent？ ──► 先读 ai-agent-integration-guide.md（导航 + 已知坑），再按上面两条分流

你要把一条产品线整体上线（域名 / 服务器 / realm / 边缘）？ ──► brand-self-hosted-deployment-guide.md（默认部署形态）

通道仲裁（ADR-0058）：自营 / 孵化站点一律走模式 B；模式 A（API-Key 通道）面向自带存量用户体系的外部二开方。代码级垂直通道已冻结。

指南目录（按用途分类） ​

教程（Tutorial）——从头走一遍 ​

文档内容读者
tutorial/hello-agent.mdHello Agent：平台全貌 + 首个会话 Agent 从建到用（含多模态 / 界面化章节）所有新开发者
tutorial/first-saas.md从零发布你的第一个 SaaS（worked example：口语搭子试点全链 15 步）自营 SaaS 建设者

操作指南（How-to）——带着任务来查 ​

文档内容读者
saas-integration-cookbook.md模式 A 服务端集成完整配方：入驻 → 影子用户三件套 → 会话 → 计费（411 行逐条可复制）外部二开方
saas-mode-b-integration-guide.md模式 B 薄壳接入：OIDC + 模板包 web-saas-template + bootstrap 脚本 + ≤15 步 checklist自营 / 孵化 SaaS
brand-self-hosted-deployment-guide.md品牌自托管接入标准（默认部署形态）：一个品牌域名 + 一个 realm + 一台自己的服务器；边缘 nginx 同源反代 /api/ /auth/ 到基座；上线一条产品线八步 / 加产品三步 / 数据边界 / 安全纪律（真实案例 4 域名 + 5 仓库）产品线开发者 + 运营
ai-agent-integration-guide.mdAI coding agent 接入指引：心智模型 + 能力面导航 + 已知坑（带实证编号）AI coding agent

参考（Reference）——精确查阅 ​

文档内容
conversation-runtime-protocol.md会话运行时协议：SSE 帧 / 轮次状态机 / 冻结-划扣计费时序
../design/2.technical/api-spec/openapi.yamlAPI 契约 SSOT（唯一权威）
llms.txt机器可读索引（agent 程序化发现能力面）

概念（Explanation）——建立心智模型 ​

文档内容
../readme/architecture.md模块化单体 / 7 能力场域 / 5 技术分层
../readme/getting-started.md本地环境从零跑通（平台内部开发视角）
../ops/README.md自托管运维 runbook 索引（部署 / 租户开通 / 计费 / CI）

约定 ​

  • 单源双消费（ADR-0059）：本树 markdown 是唯一源——人类直接读，AI agent 读源 + llms.txt；未来静态站只是渲染层。
  • 新鲜度：每篇头部「状态基准」行标注对齐的波次；改 openapi.yaml 的 PR 应评估本树是否需要联动（CI 软校验会提示）。
  • 命名约定：API 响应键一律 snake_case（与 openapi SSOT 一致）；camelCase 仅存在于前端类型层（生成器负责转换），文档中引用响应字段时以 snake_case 为准。
  • 对外边界：本树 + docs/readme/ + docs/ops/ 精选 + openapi.yaml 属对外交付面；docs/design/3.task/、docs/seminar/ 等过程资产结构性不对外。