| name | tokenkey-upstream-merge |
| description | TokenKey upstream merge workflow for importing Wei-Shaw/sub2api upstream/main. Use when merging or reviewing upstream drift, preparing an upstream merge PR, or maintaining recurring upstream update discipline. |
TokenKey upstream merge SOP
适用于 merge/upstream-* 分支。权威纪律仍以根目录 CLAUDE.md 与 docs/global/tokenkey-opc-transformation-plan.md 为准。
确定性基线（机械化 vs 真判断）
按 dev-rules rules/dev-rules-convention.mdc §「skill / command 确定性基线」自审。本 skill 绝大多数是真判断（commit 形状、决策清单、red flags 都是架构 / 风险判断），机械化部分主要在「准备」和「完成后摘要」。
| 步骤 | 类型 | 承载 |
|---|
| upstream drift / fetch / merge-tree dry-run | 机械 | bash scripts/upstream/check-drift.sh + git merge-tree upstream/main HEAD |
| 生成代码（Ent / Wire / frontend dist） | 机械 | go generate ./ent / go generate ./cmd/server / pnpm build |
| sentinel 一致性 + upstream-touch marker 强制 | 机械 | bash scripts/preflight.sh（含 sentinel registry + upstream-override-marker） |
| 完成后摘要（upstream brought-in + TK ahead + backend diff stat for PR body §5.y） | 机械 | bash scripts/release-rollout-summary.sh --mode upstream --fetch |
| Commit 形状（Harness / Invariant / OPC 三类） | 判断 | prompt（架构区分） |
| §3 决策清单 7 项 | 判断 | prompt（每条都需爆炸半径 + 兼容度判断） |
| §7 Red flags | 判断 + 机械门禁 | prompt + sentinel workflow upstream-merge-pr-shape.yml |
0. 流程心智（单入口）
upstream 融合采用单入口自动化：周期任务统一由 upstream-merge-agent-daily.yml 驱动；
已同步（up-to-date）与需合并（need-merge）都属于同一执行流结果，不再拆分独立 drift-only 模式。
人工仅在 PR review 门禁做判断，技术门禁由 upstream-merge-pr-shape.yml 强制执行。
1. 不可逾越原则
每次 upstream merge 都必须同时保持：
- 一个产品：对外仍是 TokenKey；
newapi、bridge、compat、projection 等内部词不外显成产品心智。
- 一个控制面：TokenKey 控制面留在本仓库；不在 sibling
new-api 打私有补丁。
- 最小 Engine Spine：新增 endpoint / provider / capability 必须进入 Engine owner 或 companion，不在热点 service 里复制 truth。
- Evidence Spine：QA/tool 调用、参数、返回、错误、stream terminal 必须无感完整记录；先脱敏再持久化；capture fail-open 但不 silent-loss。
- 最小 upstream 冲突面：TokenKey-only 逻辑向 companion / facade / component 收敛；不得 silent-delete upstream feature。
上游更新可能是几十到数百 commits；合并成功不是目标，冲突面下降才是目标。
1. 准备
- 工作区必须干净；若已有用户改动，先确认归属，不覆盖。
- 同步远端：
git fetch origin --tags && git fetch upstream --tags。
- 确认 main 与 upstream 状态：
bash scripts/upstream/check-drift.sh。
- Dry-run：
git merge-tree upstream/main HEAD，先识别热点冲突。
- 创建分支：
merge/upstream-YYYYMMDD。
2. Commit 形状
每个 upstream merge PR 使用三类 commit，不混杂：
A. Merge Harness Commit
只做：
git merge --no-ff upstream/main。- 解决冲突，保留 upstream 能力与审计链。
- 生成代码：Ent / Wire / frontend dist（按实际触达）。
- 把新增入口接入已有 canonical hooks。
- 保证基础编译与 preflight 能运行。
不得：借机清历史债务、重构无关模块、删除 upstream feature。
B. Invariant Commit
只修不可退让项：
- TokenKey 品牌回退。
- raw secret 持久化或结构化日志泄漏。
- route canonical 破坏。
- QA/trajectory capture hook 缺失。
- redaction contract 漂移。
- newapi / engine / brand / terminal sentinel 漏洞（包括
engine-facade-sentinels.json 门禁：dispatch 路径须经 engine.BuildDispatchPlan，Gemini 思考块过滤器须保持 shouldDropGeminiInternalText / normalizeGeminiFunctionArgs 调用链）。
- release workflow ARM/tag/skip-ci 纪律回退。
C. OPC Refactor Commit
只收敛本次 merge 新增或显著增厚的分叉面：
- 热点 Go 文件新增 TokenKey 分支 → companion / facade / owner。
- 平行 truth table → Engine / openai_compat / newapi owner。
- 大型 Vue view 新增策略块 → component / composable。
- 新 owner 必须配 focused test 或 semantic sentinel。
如果确实无法同 PR 收敛，PR body 必须写阻塞原因，并补机械门禁防止继续扩张。
3. 决策清单
遇到冲突或 upstream 新能力，按顺序决策：
- 是否 upstream feature？ 默认保留；不要 silent-delete。
- 是否影响产品心智？ 展示层用 TokenKey / Extension Engine；协议 identity 不改名。
- 是否新增 endpoint/provider/capability？ 必须进入 Engine owner 或 companion。
- 是否新增 QA/tool payload 或 terminal path？ 必须接入无感 capture，先脱敏再持久化。
- 是否触碰热点文件？ 只允许薄调用点；本 PR 新增分叉必须收敛。
- 是否新增人工操作？ 必须脚本化或 CI 化。
- 是否改变 schema/interface？ Ent/schema-first；生成代码与所有 stubs 同步。
4. 标准检查清单
PR 前必须完成：
git diff --diff-filter=D upstream/main..HEAD -- backend/：确认没有未说明的 upstream 文件删除。git log --oneline upstream/main..HEAD | wc -l：写入 PR body。git diff --stat upstream/main..HEAD -- backend/ | head -5：写入 PR body。go -C backend generate ./ent（如 Ent schema 或 migrations 触达）。go -C backend generate ./cmd/server（如 Wire graph 触达）。go -C backend test -tags=unit ./...。go -C backend test -tags=integration ./...（若 schema/repository/gateway path 高风险触达）。pnpm --dir frontend lint:check && pnpm --dir frontend typecheck（如 frontend 触达）。pnpm --dir frontend run build（如 frontend dist 或 embedded web 触达）。python3 scripts/export_agent_contract.py --check（如 agent contract 相关触达）。./scripts/preflight.sh（覆盖所有 sub2api sentinel 检查；upstream-merge-pr-shape.yml 对 merge/upstream-* PR 在 CI 中复跑与 preflight 对齐的门禁，含 newapi、brand、frontend-tk、gateway-tk、redaction、trajectory、terminal、engine、QA 数据集、pricing-availability 与 sentinel 注册表更新门闸（覆写防护）；完整清单见该 workflow 文件头注释。）
不得跳过 hook 或用 --no-verify。
5. PR body 模板
## Summary
- Merge upstream/main into TokenKey with a merge commit while preserving TokenKey OPC invariants.
- Keep upstream features compiled in; TokenKey-specific behavior stays behind companion/facade/component boundaries.
## Risk
- Large upstream merge across: <hotspots>.
- Human-reviewed decisions: <decision list>.
## Validation
- <commands run>
## Upstream Audit
- Required audit range: upstream/main..HEAD
- TK ahead count: `<git log --oneline upstream/main..HEAD | wc -l>`
- Backend stat top files: `<git diff --stat upstream/main..HEAD -- backend/ | head -5>`
6. 完成后：本次 upstream merge 变更摘要（机械化）
PR 全部检查通过、准备合并（或刚完成合并）后，调用与 release-rollout / local-deploy 共享的摘要脚本（--mode upstream 启用 upstream 专属段，含 TK ahead 计数 + backend diff stat 满足 §5.y 审计需求）：
bash scripts/release-rollout-summary.sh --mode upstream --fetch
基于输出，向用户呈现以下结构：
upstream merge 范围：<merge_base_short> → upstream/main（N 个上游提交）
上游带入：按影响维度分类（handler / service / frontend / schema / CI），每类列 1–3 行关键提交。
TK invariant 修复（B 类 commit）：列出修复的不可退让项及改动文件。
TK OPC 收敛（C 类 commit，如有）：列出从热点文件抽取到 companion 的内容。
需要在 prod smoke / 本地测试中重点验证（根据实际变更填写）：
| 触达路径 | 验证方式 |
|---|
| Gemini 路径 | 统一 smoke key + TK_SMOKE_GEMINI_MODELS 的 Gemini tool-schema 探针；HTTP 400=硬失败需回查 |
| OpenAI-compat / Responses | 统一 smoke key + TK_SMOKE_OPENAI_OAUTH_MODELS 的 OpenAI OAuth 探针；reasoning_tokens 是否透传 |
| pricing / model-list | /v1/models 数量与可用性标记 |
| frontend 组件 | frontend release asset 探针 + 浏览器关键页 |
新增/合入 admin 视图（frontend/src/views/admin/**） | TK 持久壳不可退让：上游新 admin 视图自带 <AppLayout> 包裹，必须①剥掉 <AppLayout>（布局由 AdminShellView.vue 持久壳统一提供）②把路由注册进 frontend/src/router/admin.tk.ts 的 AdminShellView children（不要在 router/index.ts 内联）。scripts/checks/admin-shell-layout.py（preflight 内）会机械拦截漏剥的 <AppLayout> |
router/index.ts 冲突 | admin 路由子树已隔离到 frontend/src/router/admin.tk.ts；冲突应只发生在非 admin 路由，admin 路由变更解析到 admin.tk.ts |
| 新增 sentinel | 列出 scripts/sentinels/*.json 文件名，说明守卫的回归场景 |
| upstream 删除文件（如有） | 逐一确认 PR description 有 (a)/(b)/(c) 回归说明 |
后续建议：是否需要立即 bump VERSION 发版，或等待下一批 TK 功能合入。
7. Red flags
Stop and fix before PR if any is true:
- TokenKey-only code got added directly to
openai_gateway_service.go, openai_account_scheduler.go, gateway_bridge_dispatch.go, gateway.go, or large admin Vue views without companion/facade/component extraction.
- A merged-in admin view under
frontend/src/views/admin/** still wraps <AppLayout> (layout must come from the AdminShellView persistent shell), or an admin route was added inline in router/index.ts instead of frontend/src/router/admin.tk.ts — scripts/checks/admin-shell-layout.py (in preflight) flags the <AppLayout> regression mechanically.
- New endpoint lacks QA/trajectory capture or terminal semantics.
- Sensitive payload persists without redaction version contract.
- New upstream file/route/service was deleted or disabled without explicit regression justification.
- PR shape check would fail: no upstream merge commit, missing
upstream/main..HEAD, or first-parent commit contains skip-ci markers.
- Direct
bridge.Dispatch* call added outside the approved service boundary files (gateway_bridge_dispatch.go / openai_gateway_bridge_dispatch*.go) — engine dispatch eligibility must route through engine.BuildDispatchPlan; engine-facade-sentinels.json will flag this mechanically.
- New Gemini response path processes
internalThought/executableCode blocks without calling shouldDropGeminiInternalText / normalizeGeminiFunctionArgs — thinking-block filter or tool-arg normalizer has drifted; engine-facade-sentinels.json gemini_thinking_filter_* entries will fail.
