SuperAPI AI 工具集

explain-with-code-walkthrough

编程与开发

查看项目

更新于 10-24 16:17

技能介绍

用途

该技能用于在用户要求“以代码走查的方式进行可视化解释”时,生成一种滚动讲解页面。它由编排器(orchestrator)调用,用来可视化地解释代码变更。

页面结构

页面采用左右分栏:左侧是简短的步骤,随页面滚动;右侧是固定在视口垂直居中位置的代码面板(粘性定位)。对于每一步,面板都会显示对应的文件,并高亮该步骤所涉及的代码行。读者可以看到“今天的代码”逐渐变成“提议的代码”。

步骤设计

  • 共 4–8 个步骤,按读者理解代码的顺序排列,通常为:今天的代码 → 改动位置 → 新代码 → 谁在使用。
  • 每步包含一句加粗句子说明本步展示的内容,随后最多 1–2 行短文本。
  • 当前步骤带有温和的标记(ev-step.is-active:强调边和淡淡的底色),其他步骤从不变暗。
  • 更深入的解释、表格和追踪(trace)放在每步一个 ev-more 折叠开关中,开关标题说明里面有什么(如“为什么 5 行就够了 · 刻度追踪”),让读者不点开也知道能获得什么。
  • 折叠内容要可视化:高亮代码、分组、状态标签、紧凑表格,避免大段文字。

代码面板

  • 展示代码库中的真实代码(或提议的代码),面板标题显示文件路径。3–4 个片段、每段不超过 15 行即可。
  • 用高亮而非内容增减来做动画:淡化非焦点行、将焦点带滑到新的范围、文件切换时交叉淡入淡出;不要在读者注视时让行增减。
  • 面板的初始状态(文件和初始高亮行)属于第 1 步,在第 1 步为当前步骤期间不得改变;首次变化发生在第 2 步成为当前步骤时。
  • 向上滚动会精确恢复之前步骤的文件和高亮:面板状态仅由步骤编号决定,绝不依赖上一状态。
  • 新增行用绿色 + 边栏标记,删除行用 − 标记。
  • 按稳定 ID 选择行(在代码数据中标记行),而不是手工数行号(会漂移)。
  • 片段只保留相关行和少量上下文,跳过部分用“⋯ 隐藏 12 行”标注,而不是展示整个文件;尽量避免需要横向滚动的行。

手机端

  • 在手机上给代码面板添加 ev-side--pin,将代码面板固定在步骤上方;保持行短(不超过 70 个字符),避免横向滚动。

构建方式

  • 使用 explainer-kit 技能构建为 fragment(其 SCRIPTS-AND-TABS.md 涵盖 EV.steps)。代码块使用 kit 的 ev-code(含 data-add、data-hl、data-groups、data-marks),用于内联和折叠中的代码。
  • 布局使用 kit 的 ev-side(步骤在左)和 ev-stick(代码面板在右,粘性定位并在顶栏下方垂直居中)。第 1 步从其列顶部开始,与代码面板齐平(无顶部内边距或间隔);添加底部内边距使最后一步能到达中间。
  • 将步骤设为 ev-step 盒子,并用 EV.steps(steps, function (i) { … }) 驱动面板(不要用 IntersectionObserver,它在反向滚动时会出错)。在 EV.onShow 中初始化,并在尺寸变化时重新测量焦点带。
  • 为每个步骤提供 id + data-toc,使其出现在章节列表中。

适用场景

需要在代码走查中向读者可视化解释代码变更的场景,例如向团队说明一项改动如何影响现有代码、新代码落在哪里、以及谁在使用它。

限制

资料未提供该技能的收费、平台兼容范围等其它信息。