Appearance
AgentHub 对外指南总索引（SaaS 开发者入口）
你是谁，从哪篇读起——本页是所有「基于 AgentHub 孵化 / 集成 AI SaaS」的开发者（人类工程师或 AI coding agent）的唯一入口。 契约事实源：端点 / 字段以
openapi.yaml为仓库契约；部分路径仍是设计意向、可能滞后实装。冲突时：照各 how-to / cookbook 的 curl 形状（对齐活 FastAPI），并回报本文档树或 openapi 勘误。 状态基准：2026-09-15（PE 波次代码面收官；内容专栏 CB / 站内信 IM / 品牌资产 BA 三波已验收合入：知识库 Tier B、支付双通道代码、多 realm + 品牌自托管、博客公共阅读面、平台→用户通知、品牌资料自助；Google / PayPal / 微信真收款仍待开闸。详见 platform-status.md）。 机器可读入口（AI agent 优先消费）：llms.txt
30 秒分流
先确认「现在能承诺什么」──► platform-status.md
你要从零把一条产品线接到基座（拍板 → S0 演练 → 正式上线）？ ──► platform-onboarding-guide.md（接入总纲：三阶段 + 四角色分工 + 七步清单 + 坑）
你有自己的用户体系 / 后端服务端？ ──是──► 模式 A：API-Key + 影子用户
└─ saas-integration-cookbook.md（§0→§12 逐条 curl）
你要新起一个自营 / 孵化 SaaS，只想写前端？ ──是──► 模式 B：浏览器直连（平台 JWT）
└─ saas-mode-b-integration-guide.md（模板 + ≤15 步）
你要把一条产品线整体上线（域名 / 服务器 / realm / 边缘）？ ──► brand-self-hosted-deployment-guide.md
你是 AI coding agent？ ──► llms.txt → platform-status.md → ai-agent-integration-guide.md，再按上面分流通道仲裁：自营 / 孵化站点一律走模式 B；模式 A 面向自带存量用户体系的外部二开方。代码级垂直通道已冻结。
指南目录（按用途分类）
教程（Tutorial）——从头走一遍
| 文档 | 内容 | 读者 |
|---|---|---|
tutorial/hello-agent.md | Hello Agent：平台全貌 + 首个会话 Agent 从建到用（含多模态 / 界面化章节） | 所有新开发者 |
tutorial/first-saas.md | 从零发布你的第一个 SaaS（worked example：口语搭子试点全链 15 步） | 自营 SaaS 建设者 |
操作指南（How-to）——带着任务来查
| 文档 | 内容 | 读者 |
|---|---|---|
platform-onboarding-guide.md | 基座接入总纲：三阶段（拍板 → S0 演练 → 品牌 realm 正式上线）+ 四角色人机分工 + S0 七步清单 + 坑清单 | 所有接入方（入口） |
saas-integration-cookbook.md | 模式 A 服务端集成完整配方：入驻 → 影子用户三件套 → 会话 → 计费 | 外部二开方 |
saas-mode-b-integration-guide.md | 模式 B 薄壳接入：OIDC + 模板包 + bootstrap + ≤15 步 checklist | 自营 / 孵化 SaaS |
brand-self-hosted-deployment-guide.md | 品牌自托管接入标准（默认部署形态）：一品牌域 + 一 realm + 一台自己的服务器 | 产品线开发者 + 运营 |
how-to/brand-server-initialization.md | 品牌边缘服务器机器面初始化：可直接粘贴给 AI agent 的部署提示词（系统底座 + ACME + 边缘 nginx + 占位页 + 验收断言） | 产品线负责人 + 其 agent |
how-to/email-auth-spf-dkim-dmarc.md | 邮件防伪三记录（SPF/DKIM/DMARC）+ 品牌 realm SMTP 回填——验证邮件不进垃圾箱 | 品牌运营者 |
how-to/blog-seo-verification.md | 内容专栏对外收录：GSC/Bing 验证（DNS 权在租户侧）、sitemap 提交、AI 爬虫（GEO）观察与 llms.txt 入口 | 租户 / 品牌运营 |
knowledge-base-retrieval.md | 知识库 Tier B：结构感知分块、父子检索、hybrid、chapter_path、绑到会话 Agent | 建设者 / agent |
payment-and-recharge.md | 支付双通道目录、下单、回调幂等、开闸前手动入账 | 前端 / 二开方 |
ai-agent-integration-guide.md | AI coding agent 接入指引：心智模型 + 能力面导航 + 已知坑 | AI coding agent |
参考（Reference）——精确查阅
| 文档 | 内容 |
|---|---|
platform-status.md | 已落地 / 待开闸 / 大陆回迁后移 / 已知产品缺口 |
conversation-runtime-protocol.md | 会话运行时协议：SSE 帧 / 轮次状态机 / 冻结-划扣计费时序 |
../design/2.technical/api-spec/openapi.yaml | API 契约（仓库内 SSOT；部分 schema 可能滞后实装） |
llms.txt | 机器可读索引（agent 程序化发现能力面） |
skills/saas-base-compat/SKILL.md | 适配核查 Skill（可下载装进开发 agent）：SaaS ↔ 基座版本衔接匹配度核查 + 按项目阶段差异化适配落地；整目录（含 references/）下载 |
概念（Explanation）——建立心智模型
| 文档 | 内容 |
|---|---|
brand-line-binding-model.md | 品牌线绑定模型：品牌·realm·用户·租户·项目·URL 六条关系（谁建立 / 记录在哪 / 靠什么生效）+ 角色三档 + 误区速查 |
../readme/architecture.md | 模块化单体 / 7 能力场域 / 5 技术分层 |
../readme/getting-started.md | 本地环境从零跑通（平台内部开发视角） |
../ops/README.md | 自托管运维 runbook 索引（部署 / 租户开通 / 计费 / CI） |
约定
- 单源双消费：本树 markdown 是唯一源——人类直接读，AI agent 读源 +
llms.txt；静态站只是渲染层。 - 新鲜度：每篇头部「状态基准」行标注对齐日期；改
openapi.yaml的 PR 应评估本树是否需要联动（CI 软校验会提示）。 - 命名约定：API 响应键一律 snake_case（与 openapi 一致）；camelCase 仅存在于前端类型层（生成器负责转换）。文档引用响应字段时以 snake_case 为准。
- 响应信封：建设态与多数 JSON 成功路径为
Envelope{code,message,data}（会话 create/get/end 亦然）。SSE 流无信封。openapi 里部分路径写成裸 schema，属设计意向滞后，解析时以实装 / 本文 curl 为准。 - 对外边界：本树 +
docs/readme/+docs/ops/精选 + openapi.yaml 属对外交付面；任务包、研讨、进度、agent 入口文件等过程资产结构性不对外。