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 2026-04-17-scene-skill-60-to-90-roadmap-plan.md 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 或全量场景铺开。