Appearance
Skill: saas-base-compat
SaaS ↔ 基座适配核查 —— 版本锚定 → 阶段判定 → 分阶段核查 → 适配方案 → 落地
调用方：任何 ZCode / Claude Code / Trae 会话（通用 skill，跨仓库使用；主要在 SaaS 项目工作区触发，也可在基座仓库触发）。
安装：把整个目录（
SKILL.md+references/）复制进你的 agent skills 目录（如~/.agents/skills/、项目.zcode/skills/、.claude/skills/）即用。触发短语：基座适配 / 适配基座 / 基座升级后 SaaS 不匹配 / 版本匹配核查 / 衔接核查 / 基座衔接 / SaaS 和基座对齐 / 接口迁移升级 / 适配方案 / agenthub 版本滞后 / "检查 XX 项目跟最新基座还匹配吗"——哪怕用户没说"核查"或"skill"。
定位：基座（AgentHub）频繁迭代，基于它开发或规划中的 SaaS 项目可能锚在旧版本，接线时才发现不匹配。本 skill 把「核查 → 研判 → 适配 → 落地」全流程标准化：先锚定 SaaS 依赖版本与基座在线版本的差别，再按 SaaS 项目所处阶段选核查深度，最后确定要不要改代码/配置并执行，确保 SaaS 侧与最新基座完美适配。
一. 何时触发 / 不触发
触发：用户想确认某个 SaaS 项目（或规划中的项目）与最新基座是否匹配，或基座升级后需要评估 SaaS 侧影响并落地适配。
不触发：
- 基座仓库自身的版本发布；
- SaaS 项目内部功能开发，与基座衔接无关的改动。
二. 核心概念（先建立，再动手）
2.1 基座仓库的定位与形态
- 基座默认 = AgentHub（GitHub
FelixOmega/agent_hub_20260527；本地克隆路径按机器探测，见 Step 0，也可用环境变量AGENTHUB_BASE_REPO钉死）。若用户明说别的基座，以用户为准。 - 基座三个版本锚点，含义不同，勿混用：
- 最新发布版 =
maintip 上的 annotated tagv<semver>+ GitHub Release（默认对比基准）； - 开发前沿 =
ai_developtip（未发布能力在此）； - 生产部署版 = 线上环境（如
bhsl.cc）实际跑的 commit——与最新 tag 不一定一致，以部署证据为准。
- 最新发布版 =
- AgentHub 的 v0.3.0 起才有 CHANGELOG 纪律；更早区间用 git 考古（日期、tag、
v0.1/v0.2只读快照分支），别指望变更日志。
2.2 SaaS 依赖基座的三种形态（决定版本锚定与核查面）
| 形态 | 特征 | 版本锚点在哪 |
|---|---|---|
| A. 方法论/资产继承型 | 继承任务包方法论、agent 定义、模板、语义样本（文档/ADR 常留「基座语义遗留」痕迹） | 继承时的来源记录 / ADR 留痕 / 继承副本的 git 首提交日期 |
| B. 平台接入型 | 作为基座租户/realm 接 API（模式 A API-Key 或模式 B 浏览器 JWT） | 对接 URL 所在环境的部署版 + SaaS 侧契约封装代码（实际调的端点/字段/scope） |
| C. 代码 fork 型 | 直接 fork 基座仓二开 | git merge-base / fork 点 commit |
一个项目可能多型并存（既继承方法论又接 API），逐型锚定。
2.3 四个阶段档位与核查深度（本 skill 核心设计）
| SaaS 项目阶段 | 核查主题 | 深度 |
|---|---|---|
| S1 产品设计 | 功能衔接 | 设计假设的基座能力还存在吗、语义变了吗、是否已被原生覆盖、是否踩了收窄/冻结线 |
| S2 技术设计 | 技术衔接细则 | 逐端点契约、鉴权拓扑、流与事件、数据边界、部署拓扑、错误码 |
| S3 任务规划 | 技术衔接 + 实现方式衔接 | S2 全部 + 任务包基准版本、实现范式对齐、基座回流边界、失效任务检查 |
| S4 运营中 | 接口迁移/升级 | S1~S3 全部 + 破坏性变更 × 已用面交叉矩阵、迁移方案、回归保障、升级协同 |
阶段只进不漏：主档取项目实际到达的最靠后阶段，核查向前全覆盖（S4 项目要过 S1~S3 所有条目）。
2.4 红线（违反即停手报告）
- 核查段对基座仓库零写入——只读引用；适配执行段只改 SaaS 侧。
- 需要改基座的，不在本 skill 内直接改：产出「基座回流建议」交 owner，由基座仓自己的任务包流程处理（AgentHub 纪律：业务代码改动必须先 PROMPT/TASK/TDD 后实现，PR 到
ai_develop）。 - 生产环境只做只读探针，凭据不入库不入日志；涉及线上验证走基座仓白名单脚本。
- 版本考证不出结果时不猜：列出证据缺口，把「补记基线」列为适配方案第一条，缺口交给 owner 裁定。
三. Step 0 —— 环境定位（双仓）
先弄清自己站在哪、两边仓库在哪：
- 判定当前工作区身份：是 SaaS 项目还是基座仓（基座特征：
backend/FastAPI +docs/design/2.technical/architecture-scaffold.md）。 - 定位另一边：
- 在 SaaS 工作区 → 找基座：① 用户 message 给的路径 → ②
AGENTHUB_BASE_REPO环境变量 → ③ 本机常见克隆名探测（agent_hub*/agenthub*）→ ④ GitHub 在线（WebFetch releases 页；只读最新版信息时够用，做契约 diff 不够用）。 - 在基座工作区 → 找 SaaS 项目：用户指定路径；用户没给就列出基座本地克隆的同级目录候选并问清（不要自选一个开查）。
- 在 SaaS 工作区 → 找基座：① 用户 message 给的路径 → ②
- 确认基座仓库健康度：git remote 正确、
CHANGELOG.md存在、git tag -l 'v*'有输出。基座本地仓可能落后，先git fetch --tags（只 fetch，不 pull 不切分支）。
四. Step 1 —— 版本锚定（SaaS 依赖版 vs 基座在线版）
4.1 SaaS 侧锚点探测（按 2.2 形态，显式证据优先）
按可信度从高到低，取最先命中的：
- 显式声明：grep SaaS 项目文档里「基于 agenthub / 基座 vX / 截至 YYYY-MM-DD / bhsl.cc」类记录。
- fork 型：
git merge-base <saas-default> <base-main>得 fork 点。 - 接入型：对接配置（API base URL → 对应环境部署版）+ 契约封装代码指纹（实际调用的端点集合、scope 集合、错误码集合、SSE 帧类型——拿这些去基座 git 历史里比对首次/末次出现区间）。
- 继承型：继承来源记录、ADR 留痕；无记录则用继承副本的 git 首提交日期 + 内容特征推定。
取证不足 → 标记「版本不确定」，推定一个区间（含依据），进 2.4 红线 4 处置。禁止用「看起来像」直接定版本。
4.2 基座侧锚点
bash
cd <base-repo> && git fetch --tags origin --prune
git tag -l 'v*' | sort -V | tail -3 # 最新发布 tag（默认对比基准）
git log -1 --format='%h %ad %s' origin/ai_develop # 开发前沿生产部署版：读 docs/guides/platform-status.md 头部「状态基准」日期 + docs/ops/ 部署证据。SaaS 已接生产环境时（S4），对比基准改为「生产实际版 → 最新 tag」两段：先保现有功能在当前生产版下正常，再评估升到最新。
4.3 产出
双版本结论 + 差异区间（「v0.2 → v0.3.0」或「2026-08-01 前后 → ai_develop tip」），写入报告 §1。
五. Step 2 —— 阶段判定（证据驱动，不问印象）
| 档 | 判定证据（满足任一即入该档，取最高档） |
|---|---|
| S1 产品设计 | 有 PRD / 功能清单 / 用户故事 / 原型；无 API 层技术方案 |
| S2 技术设计 | 有技术方案 / API 契约设计 / 数据模型文档；代码 ≤ 脚手架 |
| S3 任务规划 | 有任务包 / 迭代排期 / 开发计划；或开发进行中 |
| S4 运营中 | 有部署配置 / 生产域名或环境 / 真实用户流量 / 运维 runbook |
证据不足分不清 S2/S3 或 S3/S4 时，按更高档核查（多查不漏查），并在报告里标注存疑证据，请 owner 确认。
六. Step 3/4 —— 差异采集 + 分阶段核查
先读 references/base-surface-map.md（AgentHub 查证地图：版本/能力面/契约面/拓扑/方法论各查哪里），再按主档读 references/stage-checklists.md 对应节逐条核查。
节奏要求：
- 差异采集以 CHANGELOG 区间逐条 为纲，能力面/契约面文档为证；v0.3.0 之前的区间改用 git log 按日期考古。
- SaaS 侧「实际用了什么」以代码和配置为准，不以文档自称为准（文档可能比代码旧）。
- 每个核查项三态记录：✅ 匹配 / ⚠️ 有差异（进 Step 5 研判）/ ❓ 证据不足（本身就是发现，进 owner 确认清单）。
- 基座文档自身有已知局限（如 openapi 部分路径是设计意向、可能滞后实装），地图里已注明，冲突以实装行为为准。
七. Step 5 —— 研判定级 + 适配报告
每条 ⚠️ 差异定级：
| 定级 | 含义 | 处置 |
|---|---|---|
| 🔴 阻断 | 不修必坏 / 设计前提不成立 | 本轮必修 |
| 🟡 需适配 | 升级窗口前必修 / 契约已变将坏 | 排入适配方案，随升级落地 |
| 🔵 建议跟进 | 可延后的优化（如已被基座原生覆盖的自建项） | 列出供 owner 决策 |
| ⚪ 无影响 | 变更面与 SaaS 已用面无交集 | 留痕即可 |
定级后落到改动位置四分类：SaaS 代码 / SaaS 配置 / SaaS 文档 / 基座回流（回流 = 产出建议，不动基座，见红线 2）。
报告落盘到 SaaS 项目（docs/base-compat/ 或项目惯用 docs 目录），文件名 report-YYYYMMDD.md，格式：
markdown
# SaaS ↔ 基座适配核查报告 —— <项目名>（YYYY-MM-DD）
## 1. 版本锚定
- SaaS 依赖锚点：<证据 + 版本/日期区间，或「不确定」+ 原因 + 推定区间>
- 基座对比基准：<tag vX.Y.Z / ai_develop <sha> / 生产部署版 <证据>>
- SaaS 依赖形态：<A 继承 / B 接入 / C fork（可多选）>；对接环境：<生产 / 测试 / 未对接>
## 2. 阶段判定
- 主档：S? <阶段名>（证据：…）
## 3. 差异 × 影响矩阵
| # | 差异（基座侧事实 + 出处） | SaaS 侧触点 | 定级 | 处置 | 改动位置 |
|---|---|---|---|---|---|
## 4. 适配方案（🔴 → 🟡 → 🔵 排序；每项含：改什么 / 为什么 / 风险 / 验证方式）
## 5. Owner 决策点（❓ 证据不足项 + 🔵 跟进项 + 版本不确定时的基线补记）
## 6. 执行记录（Step 6 回写）报告落盘后、执行前，把 §5 决策点呈给用户——owner 拍板项（尤其涉及停机窗口、排期取舍、基座回流）不在本 skill 代决范围内；其余直接执行项若用户已明确要求「制定方案并执行落地」，可连续推进。
八. Step 6 —— 执行落地 + 验证
- 改动只落 SaaS 侧：按方案 §4 顺序执行；每个逻辑变更一个 commit，循 SaaS 项目自身的规约与测试门禁（先看它的 AGENTS.md/README）。
- S4 运营项目的强制项：
- 迁移/升级改动必须配回归冒烟清单，至少覆盖：鉴权登录 → 计费扣点 → 核心业务链路 → 回调/webhook → SSE 实时 → 文件/附件。
- 升级协同顺序：SaaS 侧先做向后兼容适配（新旧双轨）→ 基座升级窗口 → 冒烟复跑全绿 → 再清理双轨兼容层；无法双轨的变更，产出停机/灰度方案交 owner。
- 生产验证只读探针 / 基座白名单脚本，零凭据落盘。
- 基座回流项：整理成「回流建议」（现象、期望行为、涉及基座模块、建议任务包拆分），写入报告 §6 并单独呈报 owner——不在 SaaS 仓或基座仓直接动手。
- 验证后回写报告 §6：改了什么、测试结果、遗留项。报告是下次核查的基线——下轮 Step 1 可直接锚定本次报告日期。
九. 常见坑
- 三个版本数对不齐：最新 tag ≠ ai_develop tip ≠ 生产部署版。先弄清 SaaS 实际对接的是哪个环境，再选对比基准（见 4.2）。
- 拿设计意向当实装：基座 openapi 部分路径超前于实装，契约核对以实装行为（curl/how-to 实测形状）为准。
- 文档比代码旧：SaaS 侧接口盘点以封装层代码为准；基座侧能力以 platform-status 状态基准日为准，两边都要看「文档声称」与「实际」的落差。
- 老区间无 CHANGELOG：v0.3.0 前的变更用 git 考古（按日期 + tag + 快照分支），不要因「查不到日志」就跳过区间。
- 多型依赖漏查：项目既继承方法论又接 API 时，只查了一型就下「匹配」结论是本 skill 最常见的误判来源。
- 把「基座已原生覆盖」当差异忽略：SaaS 计划自建、但基座新版本已原生提供的功能，是降本机会（🔵 起步），不是「无影响」——参考 AgentHub 先例：CB6 原案三处被 BA 波次交付覆盖。