AGENT SKILL

isometric-explainer

构建交互式等距机器页面,机器每个工位对应流程一步。 纯函数且经过测试的状态模型驱动运动、读数与文案,页面提供控件和验证循环。 触发短语:“等距讲解”“机器讲解”“用机器解释”“等距交互图”“可探索讲解”“展示内部工作方式”。

License 许可
MIT
最近更新
2026-11-12
Stars
★ 1.3k
Forks
195

01 前言 Front Matter

name
isometric-explainer
tags
[ "isometric", "svg", "interactive", "explainer", "simulation" ]
version
1.0.0
description
构建交互式等距机器页面,机器每个工位对应流程一步。 纯函数且经过测试的状态模型驱动运动、读数与文案,页面提供控件和验证循环。 触发短语:“等距讲解”“机器讲解”“用机器解释”“等距交互图”“可探索讲解”“展示内部工作方式”。

02 资源文件 15

03 SKILL.md 正文

等距机器讲解

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

适用情况

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

使用其他方式的情况

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

方法

  1. 构思机器,写一句“X 经过 Y 移动,这个运动表示 Z”。写不清就换机器,见 references/concept.md。

  2. 绘图前按清单统计部件,选择规模。

    规模 部件数 确认
    图表 40 至 80 无需
    主图 80 至 150 无需
    更大 超过 150 先获得用户批准
  3. 先写纯确定性 model.mjs,无 DOM、无时钟。simulate(config) 返回事件和汇总。几何前先测试,见 references/state-model.md。

  4. 每个概念映射到工位,表中写工位、铭牌概念名、作用、缺少时的故障。

  5. 写部件清单,含装配组、世界尺寸、色调、是否运动,再写几何。

  6. 设定统一等距相机,世界单位,仰角 30 度,方位角让工作面朝向读者。投影同时容纳装配与展开姿态。

  7. 静态几何只构建一次,每部件一个有深度键的 SVG 组,运动部件加 data-live,见 references/geometry.md。

  8. 通过 transform 平移部件。只有形状改变(例如伸长杆)才重建路径。

  9. 按深度键加当前偏移深度,从后往前绘制。顺序变化时才重排 DOM。

  10. 按 色彩与墨线 绘制:每种材质用三种平涂色,主要实体加墨线外轮廓和硬边投影,玻璃罩用浅色高光,状态灯反映模型结果。活动部件只用一种强调色。

  11. 控件改变真实 simulate 运行,运行、单步、禁用、修复、重置与开关都生效,配置写入 URL。见 references/live.md。

  12. 在真实浏览器验证桌面和手机、明暗主题,补 4 倍近景、线端检查、零控制台错误的场景遍历与接触表。见 references/verify.md。

规则

真实性:

  • 状态模型是唯一真相。运动、读数、轨迹、结果文字都来自事件。
  • 同配置 simulate 返回同样事件,测试覆盖全部配置组合。
  • 不伪装真实模型、服务或指标。脚本部分明确标为固定脚本。
  • 有模拟时间时,页面必须以“这是模拟。”开头说明时间为固定成本,不是实测。
  • 使用真实算术,测试断言页面打印的精确数值。

几何:

  • 坐标使用世界单位,只有投影出现像素。
  • 仰角 30 度,全页一个固定方位角,参考页为 60 度。
  • 使用 kit/ink.mjs 的材质色、实体轮廓和投影;线使用 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/colour-and-ink.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/ink.mjs、kit/lathe.mjs、kit/tube.mjs:投影、材质与墨线、旋转体、管道、基础 CSS,保留 kit/LICENSE。

仓库内 scripts/agent-machine/ 与 site/test_agent_machine.js 提供完整主图,包含 57 个按深度排序的绘制项。

04 同仓库更多 Skills

fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

write-manual

为一个固定版本的技术主题编写长篇手册,从用途讲到每个请求与响应。 每个示例来自离线运行记录,每个断言追溯到按权威排序的来源,审计必须达到 TOTAL 0。 用于“编写手册”“为某主题写入门手册”“manual.json”“增加手册章节” “构建运行记录工具”“审计手册”“固定规范版本并文档化”。

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

start-learning

AI Engineering from Scratch 课程的一次性入门流程(523 节课、20 个阶段)。访谈学习者、 运行分级测验,并写入由 learn skill 驱动的持久学习计划 LEARNING.md。触发短语: “开始学习”、“设置课程”、“开始课程”、“带我入门”、“创建学习计划”,或 "start learning", "set up the course", "begin the curriculum", "onboard me", "create my learning plan"

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

mcpa-certification

AI Engineering from Scratch 中文版中的 MCPA(Model Context Protocol Associate)AI 原生导师与入门流程。学习者需要备考 MCPA、继续认证路线、 交互式学习下一课、运行并验证实践实验、参加诊断或全真模拟、根据薄弱领域 补弱时使用。适用于 Claude Code、Codex、ChatGPT、Cursor 或其他 agent。

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

lesson-screen

课程导师在终端教学时,在旁边打开浏览器学习屏幕。展示课程已注册的图表、带真实数值的 代码执行过程和可点击的预测题。也可结合课程与宿主已安装的图表技能,为当前课程制作 蓝图、机制图、等距机器或 3D 模型。点击以事件形式返回导师。 触发短语:“打开学习屏幕”、“用图展示”、“用 3D 展示”、“画出架构”、“为这节课制作图表”, 或 "open the lesson screen", "show me this visually", "show this in 3D", "draw the architecture", "visualize this lesson", "build a figure for this lesson", "lesson screen"。

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

learn

AI Engineering from Scratch 课程的交互式课程 tutor。读取 LEARNING.md,获取下一课, 在终端按章节教学,结尾测验并记录进度。可在克隆仓库中或完全通过 raw.githubusercontent.com 工作—— 无需设置。触发短语:“下一课”、“教我”、“继续课程”、“我们来学习”、“继续学习”,或 "next lesson", "teach me", "continue the course", "let's learn", "resume learning"

★ 1.3k
fancyboi999
fancyboi999/ai-engineering-from-scratch-zh

learn-reverse-engineering

从零开始学 AI 工程中逆向工程专项路径的交互导师。学习者希望读取编译后的程序时, 用于开始或继续文件格式、反汇编、控制流、表示提升、证据、等价证明、调用约定、 编译器惯用模式、链接、类型、调试、字节码、差分、符号执行和 AI 辅助分析。 每次调用讲授一课,并将证据记录到 REVERSE-ENGINEERING-LEARNING.md。

★ 1.3k