基于 superpowers 实现复杂前端改造

1. 背景：复杂改造真正难的不是写代码，而是控制跨层一致性

superpower 是开源社区非常出名的 harness 框架， 我们在本文通过数栈产品 easyIndex 的复杂需求实现来探究 superpower 的价值。

在交叉表改造里，业务上的直接诉求其实不复杂：原有“表格”展示更适合看明细，但当用户想同时按多个维度做横纵对比时，比如看“某类指标在不同区域、不同时间段上的分布关系”，普通表格的阅读成本会迅速升高。交叉表的价值，就在于把这种“按行看分组、按列看展开、在交点看结果”的分析方式直接放进查询结果里。

真正的难点并不是把一个新组件写出来，而是让多个链路在同一次改造里稳定协同：

• 配置层要支持结果视图切换，以及行维度、列维度的独立编排
• 参数层要保证组参、历史回填、重置逻辑在双模式下都成立
• 渲染层要把交叉表从原有展示方式升级为 Canvas，并接入已有查询和看板链路

这类需求的风险，通常不在单点实现，而在跨层契约容易断裂。
如果只用传统“问答式 AI Coding”推进，常见结果是某一段代码看起来能运行，但改造一旦跨过多个模块，AI 就容易丢上下文、误扩散修改范围，最后把问题从“实现功能”变成“收拾集成阶段的连锁回归”。

所以这次复盘的重点，不是交叉表本身做了多少业务能力，而是superpowers如何把复杂改造组织成一个可控、可验证、可复用的交付过程。

2. 为什么是 superpowers：从问答式 AI 到工程化协作框架

这次项目里，superpowers承担的不是“多写代码”的角色，而是“组织 AI 参与方式”的角色。它的核心价值，是先把协作过程标准化，再让 AI 进入编码阶段。

相比直接让 AI 对着需求生成代码，superpowers更强调几个前置动作：

• 先固定目标、范围、非目标和验收口径，避免需求在实现中漂移
• 先收敛仓库上下文，只暴露高相关模块，避免 AI 无边界扩散修改
• 先拆成可独立验证的阶段，再逐段交付，而不是一次性大改
• 每轮失败都结构化回灌，让 AI 根据证据修复，而不是反复猜测

这套方法的意义在于，它把 AI 从“代码补全器”提升为“受约束的协作执行者”。
对复杂前端需求来说，真正决定交付效率的，往往不是 AI 能不能写出局部代码，而是它能不能在约束下持续输出可合并结果。

3. superpowers 在这次改造中的三个关键动作

3.1 任务归一化：先统一问题定义，再开始实现

交叉表改造如果直接进入编码，很容易把工作理解成“新增一种展示组件”。但在真正的业务链路里，它实际上是一个跨配置、跨参数、跨渲染的联动改造。

这次在进入实现前，先通过superpowers把任务统一成几个明确结论：

• 目标不是单点替换组件，而是在不破坏原查询链路的前提下支持双模式运行
• 非目标要提前锁死，例如不改后端协议、不新增拖拽依赖、不碰无关业务模块
• 验收口径不是“能看到交叉表”，而是模式切换、参数回填、渲染接入要形成完整闭环

这一步的直接收益，是把后续实现从“边写边补需求”变成“围绕固定边界推进”。
对于 AI 协作来说，这比任何 prompt 技巧都更重要，因为约束清晰之后，输出才会稳定。

3.2 最小上下文投喂：限制 AI 的修改半径

复杂需求的另一个常见问题，是上下文投喂过多，导致 AI 把不该改的地方一起改掉。
这次没有把整条业务链都摊给 AI，而是只围绕高相关模块收敛上下文，例如：

• Filters
• crossConditionBox
• query/help
• crossTable

这种最小上下文策略，核心不是省 token，而是控制​修改半径​。
当 AI 只围绕关键模块做推理时，它更容易理解当前阶段真正的契约，减少跨模块误改和“顺手重构”。

3.3 分段交付与失败回灌：让修复建立在证据上

这次改造没有一次性推进到底，而是按三个阶段逐步落地：

1. 先锁定维度语义模型
2. 再打通参数闭环
3. 最后推进 Canvas 渲染接入

每一段都有独立验证点，出问题时也不是笼统地说“这里不对”，而是把错误类型、位置、复现路径和期望差异结构化回灌给 AI。
这样 AI 的下一轮修复，不再依赖猜测，而是基于明确证据收敛。

这一步直接降低了两类成本：

• 无效往返：避免同一个问题被反复用不同方式试错
• 集成爆炸：避免多个未验证修改堆到最后一起出问题

4. 三个案例：superpowers 如何具体作用到代码行为

为了避免方法论变成空泛总结，这里只保留三个最能说明superpowers价值的技术证据点。

先补一层最小业务语境：这次交叉表并不是单纯把字段换个摆放方式，而是要支持用户把分析维度拆成“行维度”和“列维度”，再在交点上查看聚合结果、汇总和对比关系。也正因为它天然同时牵涉配置、参数和渲染三层，所以非常适合作为superpowers方法是否有效的验证样本。

4.1 语义契约：先锁定dimensions + dimType

在维度模型上，这次没有把行维度和列维度拆成两套独立字段，而是保留统一dimensions，再通过dimType区分行列语义：

• 表格模式下继续使用统一dimensions
• 交叉表模式下通过dimType: 'row' | 'column'补充语义

这里体现出的superpowers价值，不在于它提出了某个字段名，而在于它推动团队先把“唯一契约”定下来，再进入实现。
一旦契约明确，模式切换、历史回填、别名共存这些后续问题都能沿同一条路径推进，避免出现两套字段并行演进、后期再做状态迁移的额外成本。

4.2 参数闭环：先定义resultDisplayMode分流规则

真正决定功能是否可用的，不是界面能不能切换，而是参数链路是否闭环。
这次在参数层先锁定一条核心规则：由resultDisplayMode决定是否进入交叉表分流组参。

在这个前提下：

• rowDimIds从dimType === 'row' || !dimType的维度里提取
• colDimIds从dimType === 'column'的维度里提取
• 仅在交叉表模式下透出交叉表专属参数

这背后体现的是一种很典型的superpowers工作方式：
先确定模式边界，再让 AI 生成实现细节。这样改造过程里每一段代码都在回答同一个问题，即“当前模式该产生什么参数”，而不是在多个文件里各自理解展示语义。

4.3 渲染分层：先拆职责边界，再做 Canvas 化

渲染层同样不是先写代码，而是先拆边界。交叉表 Canvas 改造在职责上先分成四类：

• 容器与滚动状态
• 单元格绘制
• 可视窗口计算
• 渲染契约定义

运行时再分成corner、header、frozen、body四层画布。
这样处理的价值，不只是性能优化，更是把后续定位问题的成本降下来。冻结区、滚动区、窗口计算各有独立职责，出了问题更容易追到具体层，而不是在一个巨大的渲染文件里混合排查。

从superpowers视角看，这一步体现的是“先拆模块责任，再推进实现”的纪律。
AI 很擅长补结构化代码，但前提是边界已经被定义清楚；一旦边界清晰，AI 在这里的产出就更容易稳定落到可合并区间。

5. 收益：提效不只体现在编码速度，更体现在返工减少

如果只看 AI 参与了多少代码，容易把这次改造理解成“AI 帮忙写了一部分实现”。
但从实际复盘看，superpowers带来的收益主要体现在交付过程，而不只是编码速度。

5.1 更值得关注的是流程指标

这类复杂需求里，更有解释力的指标不是“AI 写了多少行”，而是：

• 一次通过率是否提高
• 平均修复轮次是否下降
• 单需求交付周期是否缩短
• 回归缺陷和返工成本是否下降

这些指标更能直接反映superpowers的作用，因为它真正优化的是协作过程中的不确定性，而不是单点生成能力。

5.2git-ai指标记录

从本次交叉表改造的统计看，AI 参与度本身并不低：

• 统计 commit 数：4
• AI 参与 commit 数：4
• AI 代码占比：11.3%
• AI 留存率：90%

这些数据说明 AI 输出并不是实验性的草稿，而是有相当比例进入了最终结果。
但它们不足以单独证明“提效”，因为代码占比高，并不必然代表交付更稳。

真正更有价值的结论是：当superpowers先完成任务归一化、上下文收敛、分段验证和失败回灌后，AI 输出更容易进入可合并区间，团队把更多精力放在架构判断、边界处理和联调收口，而不是反复修补上下文断裂带来的问题。

5.3 最终形成的是“AI 提速 + 人工控质”的协作分工

在这次改造里，AI 更适合承担：

• 结构化样板代码生成
• 已确定契约下的局部实现补全
• 明确边界内的重构和拼接

而人工仍然聚焦在：

• 关键架构决策
• 模式边界判断
• 集成验证与收口
• 异常路径和质量把关

superpowers的意义，正是在两者之间建立明确分工，让 AI 真的成为提效工具，而不是新的不确定性来源。

6. 一套可以迁移到其他复杂需求的协作模板

这次交叉表改造之后，比较值得沉淀的不是某个具体实现细节，而是一套可以复制到其他复杂前端需求里的协作模板：

1. 先做需求归一化：明确目标、范围、非目标、验收标准
2. 再做上下文收敛：只暴露高相关模块，限制修改半径
3. 先立关键契约：字段、枚举、模式边界先统一
4. 再分段实现：每一段都必须可独立验证
5. 失败结构化回灌：基于证据修复，而不是让 AI 自由猜测

这套模板不只适用于交叉表。
凡是涉及图表、分析卡、复杂表单、低代码配置面板这类跨层联动需求，本质上都在处理相似问题：需求复杂、模块多、上下文容易断、集成阶段风险高。

当团队把superpowers当成工程化协作框架，而不是单纯的 AI 功能集合时，收益通常会体现在三个方面：

• 稳定性更高：跨层契约一致性更强
• 返工更少：无效往返和集成爆炸明显减少
• 可迁移性更强：同一套方法可以复用到下一类复杂改造

7. 结论：AI 能提速，但 superpowers 才负责控制复杂度

这次交叉表改造最值得复盘的地方，不是“AI 参与了多少代码”，而是复杂需求如何被组织成一条可控的交付链路。

如果只有 AI，而没有明确的任务边界、上下文策略、阶段验证和失败回灌，复杂改造依然容易失控。
而superpowers的价值，正是在这些关键环节里建立秩序，让 AI 输出从“可以参考”提升到“可以稳定合并”。

所以更准确的结论应该是：

• AI 负责提速
• superpowers负责控制复杂度
• 两者结合，才更接近复杂需求下真正可复制的工程化提效