SuperAPI AI 工具集

isometric-explainer

设计与创作

查看项目

更新于 10-20 21:15

技能介绍

等距机器讲解技能用于制作单页交互图:在工作台上呈现一台实体等距机器,每个工位对应流程中的一步,例如请求卡随车架移动、探针下降、压机给卡盖章。纯状态模型决定每个动作,使画面、数值与文字保持一致。templates 提供可运行起点,kit 提供几何库。

适用情况:概念是带工位、顺序和失败模式的流程,例如循环、流水线、缓存、队列、重试策略;读者能禁用一个部件并观察故障;图表是页面主体。

使用其他方式的情况:静态图即可解释,或概念没有顺序和状态变化,制作平面静态 SVG;课程或 README 中的小图,使用 blueprint-figure;无法写出确定性行为模型时,先查明行为,不动画猜测;超过 150 个部件且未获用户批准时,先确认规模。

方法:先构思机器,写一句“X 经过 Y 移动,这个运动表示 Z”,写不清就换机器(见 references/concept.md)。绘图前按清单统计部件并选择规模:40 至 80 个部件无需确认,80 至 150 个部件无需确认,超过 150 个需先获得用户批准。接着先写纯确定性 model.mjs,无 DOM、无时钟,simulate(config) 返回事件和汇总,几何前先测试(见 references/state-model.md)。将每个概念映射到工位,表中写工位、铭牌概念名、作用、缺少时的故障。写部件清单,含装配组、世界尺寸、色调、是否运动,再写几何。设定统一等距相机,世界单位,仰角 30 度,方位角让工作面朝向读者,投影同时容纳装配与展开姿态。静态几何只构建一次,每部件一个有深度键的 SVG 组,运动部件加 data-live(见 references/geometry.md)。通过 transform 平移部件,只有形状改变才重建路径。按深度键加当前偏移深度,从后往前绘制,顺序变化时才重排 DOM。只用一个强调色标出活动部件与铭牌,其他部分用四级灰度和四种线调。控件改变真实 simulate 运行,运行、单步、禁用、修复、重置与开关都生效,配置写入 URL(见 references/live.md)。在真实浏览器验证桌面和手机、明暗主题,补四倍近景、线端检查、零控制台错误的场景遍历与接触表(见 references/verify.md)。

规则。真实性:状态模型是唯一真相,运动、读数、轨迹、结果文字都来自事件;同配置 simulate 返回同样事件,测试覆盖全部配置组合;不伪装真实模型、服务或指标,脚本部分明确标为固定脚本;有模拟时间时,页面必须以“这是模拟。”开头说明时间为固定成本而非实测;使用真实算术,测试断言页面打印的精确数值。几何:坐标使用世界单位,只有投影出现像素;仰角 30 度,全页一个固定方位角,参考页为 60 度;实体用四级阴影和轮廓,线使用 hi、mid、lo、faint;线端接到实体或另一条线,有意悬空时标 data-free=start、end 或空值;每工位有概念铭牌,如 CACHE、VERIFIER,中文页面对应翻译;放在其他部件上的部件加深度偏置,绘制在支撑物之后。运动:运动部件只改 transform,变形路径尽量复用缓存结果;单节拍 0.1 至 1.3 秒,位移越远用时越长;展开弹簧刚度 64、阻尼 14.2,装配组错开 0.04 秒;单帧步长限制为 1/20 秒,慢帧不会跳过节拍;减少动态效果时运行加速 40 倍,展开立即到终态;舞台离屏或没有运动时停止动画循环。页面:桌面工作台一屏显示工具栏、舞台、读数放在 100svh 中;手机纵向堆叠,不横向滚动;按钮至少高 44px;舞台可聚焦,支持运行、单步、展开、禁用、修复键;SVG 有 role=img,aria-label 说明全部工位;aria-live=polite 在运行结束时播报结果。

完成前检查包括:页面或构建笔记写出一句话机器说明;部件数符合已确认规模;模型测试通过并覆盖所有配置;重建页面没有差异;每个配置控件调用 simulate 并更新 URL;查询参数恢复同一配置;任一时刻只有一个强调色并跟随活动部件;手机明暗主题中铭牌都可读;线端检查零悬空端点;所有配置运行到底且控制台零错误;桌面与手机明暗截图无裁剪、无横向滚动;展开姿态不超舞台;页面有模拟说明。

文件:references/concept.md 涵盖构思、一句话检查、概念映射、规模;references/state-model.md 涵盖模型契约、事件、测试、URL 状态;references/geometry.md 涵盖单位、相机、部件、工具函数、阴影、深度、铭牌;references/live.md 涵盖节拍、绘制循环、排序、强调色、控件、无障碍、布局;references/verify.md 涵盖浏览器验证循环与脚本。templates/model.mjs、templates/model.test.mjs、templates/build.mjs、templates/live.js 为可运行的缓存机器,node templates/build.mjs 生成 templates/out.html,node --test templates/model.test.mjs 运行测试。kit/iso-kit.mjs、kit/lathe.mjs、kit/tube.mjs 提供投影、实体、旋转体、管道、基础 CSS,保留 kit/LICENSE。仓库内 scripts/agent-machine/ 与 site/test_agent_machine.js 提供完整主图,包含 57 个按深度排序的绘制项。