Communitygithub.com

spatial-geometry-explainer

为数学、物理、力学、电磁学、机器人、车辆、航海导航、计算机图形学、工程及其他领域制作连续、可追溯的矢量/坐标/运动/几何推导。用户想用 HTML、2D/3D 图解、动画或交互课件看清 V 等原始量、角度定义、分量来源、复制平移、旋转、投影、合成和符号正负时使用;尤其适用于“步骤之间没有联系”“箭头突然出现”“图看不清”“公式中的 sin/cos 从何而来”等反馈。根据问题选择二维、三维或联动视图,优先离线单文件,要求步骤不跳跃、对象身份稳定、数学与画面一致并进行桌面/手机测试。

spatial-geometry-explainer 是什麼?

spatial-geometry-explainer is a Claude Code agent skill that 为数学、物理、力学、电磁学、机器人、车辆、航海导航、计算机图形学、工程及其他领域制作连续、可追溯的矢量/坐标/运动/几何推导。用户想用 HTML、2D/3D 图解、动画或交互课件看清 V 等原始量、角度定义、分量来源、复制平移、旋转、投影、合成和符号正负时使用;尤其适用于“步骤之间没有联系”“箭头突然出现”“图看不清”“公式中的 sin/cos 从何而来”等反馈。根据问题选择二维、三维或联动视图,优先离线单文件,要求步骤不跳跃、对象身份稳定、数学与画面一致并进行桌面/手机测试。.

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/g413164351/spatial-geometry-explainer3/tree/HEAD/spatial-geometry-explainer3

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

连贯式空间与矢量讲解器

使命:让学习者亲眼跟随同一个量,从定义、变换、分量到结果,而不是观看几张各自正确、彼此断开的图。它适用于需要说明对象、量、坐标系、转换及因果过程的多种教学场景。

0. 启动先证实、交付先验收(新增硬门槛)

使用这个 Skill 的第一件事不是画图,而是证实本次确实读到了它。

  • 若用户给的是 ZIP:先检查并解包到工作目录,读取 SKILL.md,同时按本题读取所需 references。只列文件名、看到压缩包存在或沿用历史记忆,不算已应用 Skill。至少记录本次读取文件及应用的规则;不可声称读过实际上未读的文档。
  • HTML / 3D 必读 references/continuity-protocol.md、references/quality-checks.md、references/angle-evidence.md、references/verification-workflow.md;含相机拖动时还读 references/camera-controls.md。
  • 先建角度身份证:角的顶点、第一条真实射线、第二条真实射线、测角平面、世界中角弧、公式数值、标注如何对应主体上的测点。α 数值标签不是角的两条边。角度不可只在远离主体的说明框里“表示”。
  • 先写相邻步骤的保留 / 新增 / 动作表:下一步不得只在文案里保留上一步,而把旧证据从场景里隐藏。特别是双对象对照,第二对象加入时,第一对象的局部测点、参考射线和分解证据仍必须可追认。
  • 真正用账本驱动画面:const LEDGER = {...} 但绘图公式各自重复计算、不引用账本,不能算“同一来源”;量、标注、角度与物理计算应由同一份几何状态生成。
  • 不允许假 PASS:原理/脚本静态检查、浏览器没有报错、视觉截图检查和学生阅读测试是四种不同结果。必须分别报告;未运行就写 NOT RUN。有阻断项 FAIL/NOT RUN,不能声称“所有验收已通过”。

最优先的验收顺序:G0 实际加载 → G1 几何/数值 → G2 步骤连续性 → G3 真实浏览器/关键帧/多视角 → G4 不读旁白指出两条角边 → G5 证据与局限。完整方法见 references/verification-workflow.md。

对于“还是看不到这个角”:停止加颜色框和重复文字。先核对角度身份证,确保两条真实世界射线从同一原位测点出发;再解决透视/遮挡、必要时添加与原位连接的局部剖面。不能只把一个角度数值贴在模型旁就宣称角已画好。

对于“相邻步骤不相连”:后一步的第一帧必须保留前一步的关键对象,再以可追踪的动画引入新内容。检查程序内部索引与可见标题编号的映射:若 UI 步骤从 1 开始而状态从 0 开始,则 UI 第 n 步应对应 stage===n-1。

1. 不可妥协的「连续性契约」

  1. 先定义,再动手。 首次出现 v / F / E / r / θ 等符号时,同屏交代它是什么(物理或数学意义)、标量还是矢量、单位、方向/正号、坐标系、箭头起止点;画角必须画两条边、角弧与所在平面。不能先给 |v|sinθ 再补说 v 和 θ 的几何定义。
  2. 为每个量登记来源。 用唯一 ID 记录 来源量 → 运算(分解、平移复制、投影、旋转、合成)→ 结果量,以及数值/方向/锚点/坐标系。公式、场景、动画共享这份数据。没有来源的箭头不可突然出现。参见 references/continuity-protocol.md。
  3. 不准无桥接地跳视图/跳步骤。 前一步产生的关键箭头须在下一步继续出现或从原位可见地过渡;必要时加入独立的「复制并平移到目标」「局部放大但原位相连」步骤。若学员无法回答“新的这根箭头原来是哪根”,必须补桥接动画,不能靠段落文字代替。
  4. 数学运算必须画成相应动作。 分解:共享原向量与带直角符号的闭合三角形;投影:画出轴/面/法线/垂足以及带正负的结果;平移复制:只移动箭头位置,保留长度、方向、身份;旋转:标明旋转的是物体、坐标轴还是相机,不能混为一谈;合成:让箭头首尾相接。
  5. 同一个世界里讲完。 始终保留完整主体及部件 ID,不用孤立局部图取代原模型;可用随原位锚点移动的放大窗,但必须显示两者连接、视向与倍率。画面过挤时淡化非重点而非替换世界。不同观察视角用连续镜头/示意旋转衔接。
  6. 数学不冒充视觉。 教学放大的箭头或角度必须标“示意/放大”;同一自由矢量平移到多个位置,计算用相同分量,只有它与各自局部轴/法线的投影不同。不要因为复制到两侧就擅自改变原向量方向。所有带符号分量用方向与点积判定。
  7. 严禁只验证公式、忽略画面。 桌面与手机都要截图看实际大小和遮挡;对含动画的步骤至少检查 0%、25%、50%、75%、100%,检验每一步源与目标是否始终可认。看不清即未通过,不以“理论正确”代替验收。

2. 工作分流

  • 只问概念:先用一句通俗话解释符号,再给最短的连续图解/语言推导;不要把高级公式和整个 3D 程序强加给学习者。
  • 要 HTML/动画/交互:交付能真正运行的自包含页面;用户指定 3D 时必须有真实可交互的三维对象/视角。三维仅为了“炫”而让投影角度看不清时,用同一状态源的局部二维截面辅助,和 3D 原位连接。
  • 修改现有 HTML:先检查旧源,保留已有 1–N 步中验证过的连贯逻辑,针对反馈补上缺失的运算,而不是每次另起一套演示。不得声称已经修改无法读取的文件。
  • 只要课程方案:交付“量的来源图 + 各步新增/保留的量 + 过渡动作 + 公式 + 自测”的故事板,而非伪造 HTML。
  • 非矢量的状态/信息流任务:沿用「来源→变换→结果→检验」与一致身份,但不要强行使用点积、方向箭头或物理单位。

3. 制作流程(顺序强制)

  1. 理解学习缺口:先定一个学习者真正想明白的因果问题,拆出每个先决概念。先画对象、原始量与角度的几何定义,保证初心者能指出它们。默认不要引入非必要的次级角度和变量。
  2. 制作量与坐标账本:记录来源量、单位、所在参考系、世界/局部坐标、正向、锚点、目标部件。数学细节见 references/geometry-math.md。
  3. 绘制来源图(provenance graph):写出 q0 → q1 → q2 ... → result,标注每个边的操作;两个分支合并时,展示两条分支从同一祖先走来。先写过渡,再写步骤。使用 references/continuity-protocol.md 与 references/transition-patterns.md。
  4. 设计故事板:逐步写“保留什么 → 新增什么 → 如何从前者变来 → 这一步看懂什么 → 数学含义”。若某步骤引入未出现过的对象,插入桥接步骤而非跳过去;步数随内容增加,不人为限制在 4、6 或 7 步。见 references/teaching-sequence.md。
  5. 先做单一画面的清晰静态原型:保证主体占画面大部分、两侧均有边距,箭头文字不盖住主体,符号与角弧可读。相机看向主体并可复位;文字布局考虑空间,避免三维标签堆叠。先验收最小原型,才加复杂动画。
  6. 实现同源参数和连续动画:一个 state 控制几何、公式、数值、图形、相机、步骤。允许任意时刻拖动进度条往返;复制动画的每帧必须与原量保持同方向同长度。公式项与世界对应量可互相高亮。
  7. 做对抗性测试与修复:原值、零值、反号、边界、桌面/手机、旋转视角、截图帧检查;使用独立向量点积/几何计算交叉核验。对每个真实小角在模型上指出两根世界射线,检查每对相邻步骤的真实画面与关键帧序列。详见 references/quality-checks.md、references/angle-evidence.md 与 references/verification-workflow.md。如有浏览器,则运行真实浏览器;不可运行时如实说明,不能虚构。
  8. 交付:给实际存在的 HTML 和简短“从哪里看起、哪一步新增了什么、拖哪个参数验证什么”。不要靠读长说明才能看懂网页。

4. 默认教学结构(按需要调整)

  • ① 原始量:展示一个完整主体与一根主要矢量;学生先知道“V 是什么”。
  • ② 角度与参照:保留原矢量,出现参考轴、角弧、角的平面;学生知道“θ 是哪一个角”。
  • ③ 从原量分解:保留前两步,逐段生成两根分量,组成可闭合直角三角形;学生能指出 sin/cos 对应哪条边。
  • ④ 显式桥接:把一个既有分量原样复制/平移到新测量对象,显示运动路径、原位置幽灵箭头和新位置身份;这是最容易被跳过、但不能省略的步骤。
  • 后续逐个对象投影:各自显示局部轴/面、法线、沿面/垂直面分量及闭合三角形,先目标 A 再目标 B;若需放大,放大框由原位连线引出。
  • ⑦ 对比与反证:同源分量方向相同,目标局部几何不同而造成结果不同;反号/设零后结果如何改变,并返回源公式。

这只是操作链模板,不是每门学科强制七步。若需要先做中间投影或坐标变换,必须独立展示对应操作,不要在标题和公式中偷偷切换角度或参考系定义。

5. 视觉与实现默认值

  • 色彩语义稳定:蓝 = 原量/输入;绿 = 第一分量;橙 = 来源分支/横向分量;紫 = 局部投影;青 = 沿面分量;角弧用金/红。但颜色必须辅以 ID、文字和方向,避免单靠颜色识别。
  • 画面清楚优先于对象复杂:主体占主要画面(建议初始可见宽度约 55–80%,视任务调整),不得缩成一团;原位箭头/局部放大可读、标签错位避让;移动端不裁切主体部件、投影箭头或字幕。
  • 默认控制:逐步前后、自动播放/暂停、可拖动 0–100% 进度、速度、重播、视角预设/复位、量的零值和反号实验;实际有意义才展示控件,尊重 prefers-reduced-motion。
  • 平移复制用统一原矢量:p(t)=(1−t)p_source+t p_target,tip(t)=p(t)+v;不是两端分别找一条路径,以免箭头变长/变短。投影在复制完成后显式引入法线和正交三角形。
  • 默认离线单文件,允许 Canvas / SVG / WebGL;不能依赖 CDN 后仍称离线。assets/interactive-starter.html 与 assets/continuous-vector-starter.html 是跨领域连续示范(内容相同,兼容旧入口)。演示模板只提供交互和过渡机制,不应替代对具体题目的独立推导。

6. 索引(按需要加载)

  • references/continuity-protocol.md:最优先,量的来源、步骤交接、复制/投影验证、反馈中遇到的坑。
  • references/transition-patterns.md:源箭头连续分解、复制平移、局部放大、投影与合成的画法、动画伪代码。
  • references/teaching-sequence.md:从提问到每步的故事板与学员自测。
  • references/geometry-math.md:坐标、角度、分量、法线、旋转与定量公式。
  • references/domain-recipes.md:数学、力学、机器人、电磁、图形学和数据流的跨领域实例。
  • references/quality-checks.md:数值、视觉、手机/电脑、动画帧与交付检查。
  • references/angle-evidence.md:新增硬门槛,角度顶点、两条真实参考射线、截面、弧线与原位可辨认性。
  • references/verification-workflow.md:新增硬门槛,Skill 加载真实性、相邻步骤交接、浏览器帧矩阵、截图/阅读测试、交付证据。
  • references/camera-controls.md:新增,正确相机基底、拖动方向、旋转极点、手机触摸与缩放复位。
  • assets/interactive-starter.html / assets/continuous-vector-starter.html:领域无关的同一款连续示范(默认模板),可换向量/换对象/换投影轴。
  • scripts/check_offline_html.py:静态离线依赖筛查;scripts/validate_continuity.py:来源图 JSON 的结构检查。
  • scripts/validate_visual_contract.py:新增,检查角度身份证、相邻步骤交接和视觉验收计划;可用 --require-reviewed 阻断“未实际复核就宣称通过”。
  • scripts/check_vector_math.py:新增,通用向量投影、旋转、重构与符号的独立回归测试。
  • scripts/capture_lesson_frames.py:新增,在页面主动提供 window.lessonTest 测试接口时用真实浏览器截帧,需 Playwright。
  • scripts/verify_skill_package.py:新增,核对 Skill ZIP 解压后的必备文件、结构和随包示例;仅检查包完整,不证明教学画面正确。

相關技能