claw/docs/superpowers/specs/2026-04-18-g3-paginated-enrichment-design.md

# G3 Paginated Enrichment Design

> **Status:** Draft
> **Date:** 2026-04-18
> **Author:** Codex
> **Upstream Inputs:**
> [2026-04-17-scene-skill-60-to-90-roadmap-design.md](D:/data/ideaSpace/rust/sgClaw/claw-new/docs/superpowers/specs/2026-04-17-scene-skill-60-to-90-roadmap-design.md)
> [2026-04-17-scene-skill-60-to-90-roadmap-plan.md](D:/data/ideaSpace/rust/sgClaw/claw-new/docs/superpowers/plans/2026-04-17-scene-skill-60-to-90-roadmap-plan.md)
> [2026-04-18-first-real-scene-migration-execution-sheet.md](D:/data/ideaSpace/rust/sgClaw/claw-new/docs/superpowers/reports/2026-04-18-first-real-scene-migration-execution-sheet.md)

## Problem Statement

`60 -> 90` 主路线在 `G2` 多模式报表家族与 `G1-E` 轻量补查子型上已经取得阶段性收敛：

1. `G2` 已经从“主样本不可成型”推进到“主样本与多个变体进入候选验证阶段”
2. `G1` 已经完成边界收紧，`G1-E` 的首个 `P0` 样板已通过验证

但主路线中的 `P0-3` 仍然缺位：

1. `paginated_enrichment` 还没有形成正式的 `spec / plan / canonical` 三件套
2. `95598工单明细表` 虽已被明确指定为 `P0-3` 主样板，但尚未建立统一证据层、最小合同和失败 taxonomy
3. 当前系统仍缺少一条“面对复杂分页、补数、导出和宿主桥接混合 workflow 时，能先正确拆解，再决定生成或阻断”的正式路径

因此，当前问题已不再是“是否继续补更多 `G2` 变体”，而是：

> 必须把 `G3` 分页补数家族从“概念上知道它复杂”推进到“结构上可拆解、合同上可裁决、证据不足时稳定 fail-closed”。

## Goal

在不推翻现有 `Scene IR + compiler + readiness` 框架的前提下，把 `G3` 从“分页补数场景的宽泛标签”升级为“可建模、可编译、可阻断的复杂 workflow archetype”。

本设计的直接目标如下：

1. 正确识别 `G3` 的主请求链、分页链、补数链、导出链
2. 区分业务 workflow 与宿主桥接行为，不再让 `localhost:*`、BrowserAction 或宿主注入抢占业务主链
3. 建立 `paginated_enrichment` 的最小可编译证据集
4. 建立 `G3` 最小业务合同与 gate
5. 让 `95598工单明细表` 成为 `P0-3` 的第一版 canonical answer 与失败基线
6. 在证据不足时稳定 `fail-closed`，不再产出伪可运行 skill

## Success Criteria

`G3` 首轮设计完成后，最低成功口径固定为：

1. `95598工单明细表` 不再被当成“普通分页表”或“模糊 workflow”
2. 系统能够显式拆出：
   - `main request chain`
   - `pagination chain`
   - `enrichment chain`
   - `export chain`
3. 系统能够显式区分：
   - `business workflow evidence`
   - `host bridge / localhost dependency evidence`
4. `paginated_enrichment` 具备最小合同，不再只是一个兜底 archetype 名称
5. 证据不足时，结果能够按固定 taxonomy `fail-closed`
6. `G3` 首轮回归结果要么达到候选验证门槛，要么给出准确阻断理由

## Non-Goals

本轮 `G3` 设计不处理以下事项：

1. 不扩展到全部 `102` 个场景同步整改
2. 不并行展开 `G6/G7/G8`
3. 不在本轮解决统一平台登录、隐藏域登录恢复或宿主 transport 重构
4. 不要求第一轮就还原所有工单类复杂业务语义细节
5. 不把本轮工作扩散为“全部 95598 家族一次性打通”
6. 不为了先生成 skill 而放松 gate

## Scope

本轮 `G3` 设计范围严格限定为：

1. `G3` 家族边界定义
2. `G3` 证据层建模
3. `G3` 最小合同与 gate 设计
4. `G3` 的 `P0-3` canonical baseline 设计
5. `95598工单明细表` 与一个 `G3` 扩展样板的首轮回归口径

本轮不进入：

1. 大规模 `95598` 场景扩展
2. 工单类全部子家族重排
3. 运行时协议改造
4. 导出后处理、落库分析、文档生产等更高层产物链路重构

## Fixed Samples

本设计冻结如下样板：

### P0 Main Sample

1. `95598工单明细表`

定位：

1. `paginated_enrichment.list_detail_filter_export`
2. `P0-3` 主样板
3. 第一版 `G3 canonical` 唯一校准源

### P1 Expansion Sample

1. `95598、12398、流程超期风险工单明细`

定位：

1. `G3` 第一扩展样板
2. 用于验证 `P0-3` 的合同与证据层是否具备复用性

在本设计完成前，不新增第三个 `G3` 首轮样板。

## Family Definition

`G3` 的正式定义固定为：

> 以分页明细拉全为主链，并伴随详情补查、关联补数、过滤去重、导出动作或阶段性聚合的复杂 workflow 报表场景。

该定义下，`G3` 至少具备以下一个或多个显著特征：

1. 存在明确主查询接口，但最终结果不是单页即得
2. 需要显式分页拉全或滚动时间窗口
3. 需要对列表行做二次补查或关联详情查询
4. 存在主链、补链、导出链并存的情况
5. 最终产物依赖分页明细完整性，而不是单请求返回结果

## Inclusion Rules

`G3` 进入条件固定如下：

1. 存在主查询链候选
2. 存在分页控制证据
3. 存在补查、明细详情或二次链路证据
4. 最终目标是明细拉全、补齐、筛选、导出或汇总
5. 业务链可以与宿主桥接链做分层

## Exclusion Rules

出现以下特征之一时，不再归入当前 `G3`：

1. 只存在单次请求表格返回，无分页与补数闭环
2. 只有页面点击链，没有可恢复的业务主链
3. 主体价值在本地落库、SQL 分析或 Word 产物流水线，且业务主链无法恢复
4. `localhost:*` 或宿主桥接动作压倒业务请求证据
5. 主要问题不是分页补数，而是宿主多步桥接或文档生产

## Root Cause Framing

当前 `G3` 迟迟未进入正式落地，不是因为它“太复杂无法做”，而是因为存在三个基础缺口：

### 1. Workflow Signals Are Still Flattened

当前生成链更擅长提取：

1. endpoint 名称
2. 参数片段
3. 导出调用痕迹
4. BrowserAction 或页面控制痕迹

但缺少把这些信号重建成分层 workflow 的机制，因此：

1. 主链与补链混杂
2. 导出链容易被误当成主业务链
3. 宿主桥接与业务链混杂

### 2. Paginated Contract Is Missing

当前系统还没有 `G3` 专属的最小合同，因此无法明确回答：

1. 什么算“分页链已恢复”
2. 什么算“补数链已恢复”
3. 什么算“join key 已成立”
4. 什么算“导出链只是附属动作而不是主链”

### 3. Fail-Closed Taxonomy Is Missing

即使系统意识到结果不能放行，也缺少固定的失败类型表，因此容易出现：

1. 阻断理由模糊
2. readiness 不可解释
3. 结果无法用于后续回归

## Design Principles

`G3` 设计阶段遵循以下原则：

1. 先拆 workflow，再讨论生成
2. 先建证据层，再建合同
3. 先把宿主链隔离，再恢复业务主链
4. 优先保证 `fail-closed` 的准确性，而不是优先追求高通过率
5. 所有规则必须可落到 `fixture / test / report`

## Required Evidence Types

在通用证据层之上，`G3` 首轮最小证据类型集合固定为：

1. `main_request_candidate`
2. `pagination_candidate`
3. `enrichment_request_candidate`
4. `join_key_candidate`
5. `export_candidate`
6. `workflow_step_candidate`
7. `dedupe_or_merge_rule_candidate`
8. `host_bridge_candidate`
9. `localhost_dependency_candidate`
10. `browser_action_candidate`

## Evidence Layer Requirements

`G3` 证据层最少必须回答以下问题：

1. 主查询链是什么
2. 分页控制来自哪里
3. 补数链有哪些候选
4. 主链和补链靠什么字段关联
5. 导出动作属于业务链还是结果产物链
6. 哪些行为属于宿主桥接或本地依赖

## Minimal Business Contract

`G3` 的最小可编译合同至少包括：

1. `main_request`
2. `pagination_plan`
3. `enrichment_requests[]`
4. `join_keys[]`
5. `export_plan`
6. `merge_or_dedupe_rules`

只有这些对象闭合时，`G3` 才允许进入可编译状态。

## Required Gates

`G3` 统一 gate 名称最少包括：

1. `g3_main_request_resolved`
2. `g3_pagination_contract_complete`
3. `g3_enrichment_contract_complete`
4. `g3_join_key_resolved`
5. `g3_export_path_identified`
6. `g3_runtime_scope_compatible`

## Fail-Closed Policy

以下情况必须明确 `fail-closed`：

1. 主请求链缺失
2. 分页链存在但终止条件不明
3. 补数链存在但 join key 不明
4. 只有导出动作，没有业务主链
5. 宿主桥接证据明显多于业务证据
6. 运行时依赖明显超出当前 `G3` 合同边界

## P0 Canonical Target

`95598工单明细表` 的 canonical baseline 完成后，至少应冻结以下资产：

1. canonical `Scene IR`
2. 关键证据清单
3. 最小合同表
4. 验收检查表
5. 失败 taxonomy

## Failure Taxonomy

`G3` 第一版失败 taxonomy 最少包括：

1. `main_chain_missing`
2. `pagination_incomplete`
3. `enrichment_incomplete`
4. `join_key_missing`
5. `export_only_without_business_chain`
6. `host_bridge_pollution`
7. `runtime_dependency_unresolved`

## Validation Baseline

`G3` 回归时，必须按统一口径检查：

1. archetype 是否正确
2. bootstrap 是否合理
3. 主请求链是否恢复
4. 分页链是否恢复
5. 补数链是否恢复
6. join key 是否恢复
7. 导出链是否恢复
8. 宿主链是否被隔离
9. readiness / blocker 是否可解释

## Required Deliverables

本设计落地时至少产出：

1. `G3` 设计稿
2. `G3` 实施计划
3. `G3` 首轮 `fixture / test` 扩展目标
4. `95598工单明细表` 的 canonical 设计目标
5. `G3` 首轮验证报告模板

## Acceptance

本设计完成的标志是：

1. `G3` 已从宽泛标签进入正式 archetype 设计
2. `95598工单明细表` 被固定为 `P0-3` 主样板
3. `G3` 证据层、最小合同、gate 和 fail-closed 口径被明确定义
4. 后续实现不再把 `G3` 当成“遇到复杂就兜底”的模糊类型

## Next Step

基于本设计，下一步应直接落地：

- `docs/superpowers/plans/2026-04-18-g3-paginated-enrichment-plan.md`

该 `plan` 只围绕 `G3 / P0-3` 实施，不扩展到 `G6/G7/G8` 或全量场景铺开。