# AgentHub

> AgentHub：面向多类 AI SaaS 快速孵化的 AI Agent 底座平台。本文件是 AI agent 开发者的机器可读入口（llms.txt 约定），索引平台全部对外能力面与文档。使能路线（ADR-0058）：API + 模式 B——自营/孵化 SaaS 走浏览器薄壳直连，外部二开方走服务端 API-Key 通道。

## 快速定位（按你的角色）

- [AI coding agent 接入指引（先读）](ai-agent-integration-guide.md): 心智模型 + 能力面导航 + 已知坑（带实证编号）
- [模式 A 集成 Cookbook（外部二开方）](saas-integration-cookbook.md): 服务端 API-Key + 影子用户，§0→§12 逐条 curl 完整配方
- [模式 B 薄壳指南（自营/孵化 SaaS）](saas-mode-b-integration-guide.md): 浏览器 JWT 直连 + 模板包 bootstrap + ≤15 步 checklist
- [品牌自托管接入标准（默认部署形态）](brand-self-hosted-deployment-guide.md): 一个品牌域名 = 一个 Keycloak realm + 一个运营域租户 + 一台自己的服务器；品牌边缘 nginx 同源反代 /api/ /auth/ 到基座；用户全程留在品牌域；上线八步 / 加产品三步 / 数据边界 / 安全纪律
- [从零发布第一个 SaaS（教程）](tutorial/first-saas.md): 口语搭子试点真栈 worked example，全链含对账
- [Hello Agent 教程](tutorial/hello-agent.md): 平台全貌 + 首个 SOP 任务 curl 级全流程（含多模态/界面化章）

## 契约与协议（事实源）

- [OpenAPI 契约 SSOT](../design/2.technical/api-spec/openapi.yaml): 对外仲裁事实源——任何文档与它冲突时以它为准并回报勘误；内部实装↔契约的漂移治理走 ADR-0039 reconcile 机制（不改变对外仲裁口径）
- [会话运行时协议](conversation-runtime-protocol.md): SSE 帧（turn_started/turn_delta/turn_card/turn_file/turn_completed）、轮次状态机、freeze/settle 计费时序
- [文档总索引](README.md): 人类读者入口（30 秒分流 + 四象限目录）

## 核心能力面速览

- 会话 Agent：多轮流式（POST-SSE）、选项卡片、断连重拉不重复扣费、轮次计费（freeze→settle）
- 多模态：语音转文字 / 语音播报 / 图片理解（vision parts）/ 文生图——同一会话通道
- 身份：Keycloak OIDC；模式 A = API-Key + On-Behalf-Of 影子用户；模式 B = 平台 JWT（仅本人）
- 计费：积分双账户；轮次单价与消费全量 ledger 归因（operation_id 幂等键可对账）；模型成本按项目归因（cost_records）
- 平台边界（ADR-0042）：禁止库嵌入 / fork / 直连 DB；深度定制走 HTTP Tool + Webhook 反向接缝

## 环境与运维

- [本地从零跑通](../readme/getting-started.md): 环境准备 / 数据库引导 / 鉴权配置 / 常见坑
- [运维 runbook 索引](../ops/README.md): 部署 / 租户开通 / 计费免跑模式 / CI / testbed
- [Python SDK](../../sdk/python): 生成式 DX 层（OpenAPI SSOT 派生）