AgentHub 开发者文档

Appearance

四阶段核查清单（S1~S4） ​

使用规则：

  • 主档 = Step 2 阶段判定结果；向前全覆盖（S4 项目要过 S1~S3 全部条目）。
  • 每条核查项三态记录：✅ 匹配 / ⚠️ 有差异（进 Step 5 研判定级）/ ❓ 证据不足（进 Owner 决策点——找不到证据本身就是发现）。
  • 查证入口见 base-surface-map.md；SaaS 侧「实际用了什么」以代码与配置为准，不以文档自称为准。

S1 产品设计阶段 —— 功能衔接 ​

检查对象：PRD / 功能清单 / 用户故事 / 原型。本阶段产出全是文档修订，零代码。

  1. 能力存在性：设计假设的每项基座能力，是否落在 platform-status「现在就能用」表内；落在「待开闸 / 后移」的要逐条标注风险（不可对用户承诺，例：支付真收款、Google IdP、护栏 enforce、BA2 博客品牌呈现、IM5 私信、全租户公告、微信线整体后移）。
  2. 能力语义漂移：设计假设的能力语义与当前文档口径是否一致。易漂移点举例：钱包域内合一（非双层）、终端用户余额/流水读权限已随 saas_user 下发（旧文档「403」口径过期）、多模态按发布快照开关（非全局）、一产品线 = 一品牌域 + 一 realm。
  3. 重复自建检测：设计中计划自建的功能，是否已被基座新版本原生覆盖。命中则建议设计改为「用基座 + 差异化」（定级 🔵 起步，但省钱量级可能很大）。基座先例：CB6 原案三处（条幅存储/上传/管理 UI）被 BA 波次交付覆盖。
  4. 收窄/冻结线：设计若依赖代码级垂直通道（verticals，ADR-0058 已冻结）或被 MVP 收窄的面，改走 API + 模式 B；解冻条件见 ADR 原文，不要赌解冻。
  5. 拓扑假设：多租户 / realm / 品牌域假设是否符合 ADR-0063；toB 一套品牌授权多租户的口径是否符合 ADR-0067（per-realm 锚定、同 realm 全租户可读仅运营租户可写）。
  6. 计价/配额假设：点数计价、配额护栏、双重信任模型（ADR-0044/0050）与设计的商业模型是否兼容；设计中的免费/试用形态要对应到平台的赠点/配额机制，不要发明平台没有的计费形态。

产出：功能差异清单 → PRD/设计文档修订建议（含「用基座替代自建」重设计建议）。

S2 技术设计阶段 —— 技术衔接细则 ​

检查对象：技术方案 / API 契约设计 / 数据模型文档 / 原型代码中的接口封装层。

  1. API 契约逐端点对照：SaaS 设计中出现的每个 endpoint × 基座 openapi 当前态——路径、方法、请求/响应形状、scope、错误码。有封装层代码的以代码实际调用为准。注意 openapi 部分路径超前于实装，关键端点以 how-to/实装行为复核。
  2. 鉴权拓扑：模式 A/B 选择仍有效（ADR-0058：自营/孵化只走模式 B；模式 A 留给存量用户体系的外部二开）；realm / JWKS / multi-realm R1 不变式（token realm ≠ 租户 realm → 403）；JIT 加入与多归属切换；scope 集合存在性与最新名（scope catalog 有更名/新增史）。
  3. 流与事件协议：SSE 通道与帧形状（会话帧族、收件箱帧族、balance/inbox 独立通道）、断连重拉语义、freeze→settle 计费语义、事件订阅面（如 content_guard.appeal_resolved）——SaaS 设计若假设了不存在的帧/事件即错配。
  4. 数据边界：哪些数据落基座库、哪些 SaaS 自管。基座库有 per-tenant RLS + 首例 per-realm RLS 族 + GUC 注入语义；SaaS 直连基座库属红线级错配（ADR-0042 二开接入模型只允许 API 触点）。
  5. 部署拓扑：品牌自托管边缘反代（ADR-0063 D10：/api/ /auth/ 同源反代进基座 VPC）、网关路径约定（/api/ /auth/ /fs/）、回调/webhook URL 形态、CSP 约束（历史坑：img-src 缺 https: 拦外链 logo）。
  6. 错误处理设计：三码结构（HTTP 状态/机器码/中文映射）与 SaaS 侧错误处理、用户提示设计是否对齐；核对 SaaS 引用的机器码在当前版本仍存在且语义未变。
  7. 直引代码的版本边界（仅 fork 型/引用基座代码时）：tech_stack FROZEN 版本边界、迁移链影响。

产出：契约差异表 → 技术设计文档修订 + SaaS 侧契约快照更新建议。

S3 任务规划阶段 —— 技术衔接 + 实现方式衔接 ​

含 S2 全部条目，另加：

  1. 版本锚点选择：任务包以哪个基座版本为开发/验收基准。默认最新发布 tag；确需前沿能力时显式锚 ai_develop commit 并在任务包登记风险（未发布语义可能再变）。
  2. 实现范式对齐（任务含基座侧改动时）：基座现行范式——分层架构与 import-linter 合约、Facade 边界、RLS/GUC 注入范式、审计 WORM、scope catalog + seed 双落流程、openapi generate:check 零漂移门禁。SaaS 侧改动按 SaaS 仓自身规范。
  3. 基座回流边界：任务计划里「直接改基座代码」的项 → 重构为基座任务包（PROMPT/TASK/TDD 三件套 + 四阶段编排 + PR 到 ai_develop），排期计入 owner 评审等待窗口。本 skill 不代改基座。
  4. 新依赖归属判定：落在基座侧的新第三方依赖需 ADR 评审 + tech_stack 升级；SaaS 侧自管依赖不受基座约束，但 fork 型项目要保持与基座可合并性。
  5. 已排任务失效检查：SaaS 任务清单逐包对照基座 task_package_list.md 与 platform-status——基座新版本已原生覆盖的包，作废或收窄为「接入适配」包（防重复交付）。
  6. 方法论同步（继承型）：基座任务包方法论若已演进（模板结构、门禁清单、四阶段定义变化），评估 SaaS 侧继承副本是否同步；不同步要留「有意分叉」记录，避免下次核查误判。

产出：任务包修订 + 排期影响 + 基座回流包建议清单。

S4 运营阶段 —— 接口迁移/升级评估 ​

含 S1~S3 全部条目，另加：

  1. 破坏性变更扫描：依赖锚点 → 最新版的 CHANGELOG 逐条（含每版「升级说明」节；v0.3.0 前区间 git 考古）。判据不是「基座变了什么」，而是 「SaaS 已用面 × 变更面」的交集——没用到的破坏性变更 = 不受影响，留痕即可。
  2. 已用接口盘点：从 SaaS 代码/配置实际提取——封装层调用点、对接配置、webhook/回调注册、scope 申请清单、SSE 消费端。不凭文档自称。
  3. 三分类处置：每条交集差异 → 需迁移（契约已删/已改，不改必坏，🔴）/ 需升级匹配（新增必填、语义收紧、额度/配额变化，🟡）/ 不受影响（⚪ 留痕）。
  4. 回归保障：任何迁移/升级改动配回归冒烟清单，最少覆盖：鉴权登录 → 计费扣点 → 核心业务链路 → 回调/webhook → SSE 实时 → 文件/附件。基座 Alembic 迁移链密集期尤其注意数据侧升级说明（回退成本高的变更提前备份方案）。
  5. 升级协同顺序：SaaS 侧先做向后兼容适配（新旧契约双轨）→ 基座升级窗口 → 冒烟复跑全绿 → 清理双轨兼容层。无法双轨的变更（如删端点、改语义），产出停机/灰度方案交 owner 拍板，不自行切换。
  6. 生产环境核查：确认 SaaS 对接环境（生产 bhsl.cc / 测试 ECS-B）实际部署版本（platform-status 状态基准 + ops 证据），勿以最新 tag 推定生产。生产验证只做只读探针 / 基座白名单脚本，零凭据落盘。

产出：迁移升级方案（含协同顺序与回退要点）+ 回归冒烟清单 + 执行记录（回写报告 §6）。