Appearance
AgentHub 基座查证地图
用途：Step 3 差异采集与 Step 4 分阶段核查时，按「要查什么」到这里找「查哪里」。 漂移自检：基座会持续演进，本图不是契约。下列路径若已移动/不存在，先读基座仓
docs/guides/README.md与docs/guides/platform-status.md找新入口；实在找不到就 git 考古。基座仓库本身永远是一切的事实源。
1. 版本与历史（Step 1/3 必用）
| 要查什么 | 事实源 | 说明 |
|---|---|---|
| 版本历史 / 破坏性变更 / 升级说明 | 基座根 CHANGELOG.md | Keep a Changelog 风格；每版末尾常有「已知遗留与升级说明」节——S4 迁移评估第一输入 |
| 最新发布版 | git tag -l 'v*'（annotated tag 打在 main tip）+ GitHub Releases | 默认对比基准 |
| 开发前沿 | origin/ai_develop tip | 未发布能力在此；SaaS 锚定前沿属显式风险决策 |
| 生产部署态 | docs/guides/platform-status.md 头部「状态基准」日期 + docs/ops/ 各 runbook 的部署/验收证据 | 生产版 ≠ 最新 tag，以部署证据为准 |
| v0.3.0 之前的区间 | git 考古：按日期 git log --since --until、v0.1/v0.2 只读快照分支、PR 编号（#NNN）回查 | CHANGELOG 纪律 v0.3.0 才建立，老区间无日志可查 |
2. 能力面（S1 产品设计阶段主用）
| 要查什么 | 事实源 | 说明 |
|---|---|---|
| 「现在能接什么 / 什么还不能对用户承诺」 | docs/guides/platform-status.md | 三态总表：已落地 / 待开闸 / 后移。设计假设逐条对表的第一依据 |
| 机器可读能力面索引 | docs/guides/llms.txt | 快速盘点能力清单 |
| 接入教程主线 | docs/guides/tutorial/hello-agent.md、docs/guides/tutorial/first-saas.md | 从零到发布的 worked example |
| 已知遗留（不能承诺的能力） | CHANGELOG「已知遗留与升级说明」+ platform-status「待开闸/后移」 | 例：支付真收款未开闸、Google IdP 待凭据、护栏仅影子、BA2 未执行、IM5 延后 |
3. 契约面（S2 技术设计 / S4 运营阶段主用）
| 要查什么 | 事实源 | 说明 |
|---|---|---|
| API 契约 SSOT | docs/design/2.technical/api-spec/openapi.yaml | 注意基座自述：部分路径是设计意向、可能滞后实装——冲突以实装行为为准（platform-status 头部明示），并回报勘误 |
| 会话 / SSE 协议 | docs/guides/conversation-runtime-protocol.md | 帧族、断连重拉、freeze→settle 语义 |
| 接入模式与配方 | docs/guides/saas-mode-b-integration-guide.md（模式 B）、docs/guides/ai-agent-integration-guide.md（模式 A）、docs/guides/saas-integration-cookbook.md（配方集） | 模式选择的有效性以 ADR-0058 为准（自营/孵化只走模式 B；模式 A 留给外部二开） |
| scope 目录演进 | 基座仓 scope catalog / seed（在 backend/ 内 grep scope 名，如 ops:realms:read） | scope 有更名/新增史（如 saas_user 补 billing 读权限），旧文档 scope 集可能过期 |
| 错误码三码结构 | openapi + 基座 shared error-codes（HTTP 状态 / 机器码 / 中文映射） | SaaS 侧错误处理对齐用 |
| 依赖版本边界 | docs/design/2.technical/reference/tech_stack.md（FROZEN） | 仅 fork 型 / 直引基座代码时相关 |
4. 拓扑与架构决策（各阶段都可能用到）
| 要查什么 | 事实源 |
|---|---|
| 架构决策索引 | docs/design/2.technical/adr/（按编号倒查最新） |
| 高频相关 ADR | 0042 二开接入模型 · 0046 单向分支流 · 0058 模式 B 唯一路线 + vertical 冻结 · 0061 登录双轨 · 0063 域名与 realm 拓扑（多签发者/品牌自托管边缘） · 0064 内容护栏 · 0065 内容 Blog · 0066 站内信 · 0067/0068 品牌资料与通用文件前门 |
| 部署拓扑 | docs/ops/production-topology-and-domains.md、docs/guides/brand-self-hosted-deployment-guide.md |
| 数据边界语义 | per-tenant RLS 为主 + 首例 per-realm RLS 族（ADR-0067）；GUC 注入语义——SaaS 设计若假设直连基座库属红线级错配 |
5. 方法论（S3 任务规划阶段主用；继承型项目的同步源）
| 要查什么 | 事实源 |
|---|---|
| 任务包方法论 | docs/design/3.task/README.md + docs/design/3.task/packages/_template/（PROMPT/TASK/TDD 三件套 + 四阶段编排） |
| 波次与任务包状态 | docs/design/3.task/task_package_list.md（判断「SaaS 侧排了的任务是否已被基座原生覆盖」） |
| 基座分支纪律 | .trae/rules/remote-ops.md + ADR-0046（回流建议落基座时的流程依据） |