edu-solid-geometry

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

立体几何解题 → 交互网页

Solid Geometry Problem Solving → Interactive Web Page

这个技能产出什么

What This Skill Produces

一个可直接用浏览器打开的单页 HTML：左侧题面/答案/分步解析（公式用 MathJax），右侧是题目对应的 3D 模型（Three.js，可旋转缩放，分步高亮关键元素并切换镜头）。形态与

template/lesson.html

一致。

A single-page HTML file that can be directly opened in a browser: problem statement/answers/step-by-step explanations (formulas rendered with MathJax) on the left, and a 3D model corresponding to the problem (Three.js, rotatable and scalable, with step-by-step highlighting of key elements and camera switching) on the right. The format is consistent with

template/lesson.html

依赖（重要）

Dependencies (Important)

计算核心

lib/geometry_kernel.py

依赖 sympy。运行脚本前先确认有一个能 import sympy 的

python3

：跑

python3 -c "import sympy"

。

缺库时的处理（重要）：若 import 报错（sympy 或后续用到的任何库都同理），先询问用户是否安装，得到同意后再帮忙安装（

python3 -m pip install <库名>

），或换一个已装该库的解释器；不要未经询问直接装。下文命令里的

python3

均指这个能跑通依赖的解释器。

The calculation core

lib/geometry_kernel.py

depends on sympy. Before running the script, ensure you have a

python3

environment that can import sympy: run

python3 -c "import sympy"

Handling Missing Libraries (Important): If an import error occurs (the same applies to sympy or any other library used later), first ask the user for permission to install before helping with installation (

python3 -m pip install <library-name>

), or switch to an interpreter that already has the library installed; do not install without asking first. The

python3

in the commands below refers to this interpreter that can run the dependencies properly.

工作流程

Workflow

第 1 步：得到 problem spec（三入口归一）

Step 1: Obtain Problem Spec (Unify Three Entries)

把题目整理成结构化 spec（格式见

references/problem-schema.md

）：几何体类型与尺寸、已知构造点/条件、所求类型与对象、语言。

文字题目：直接抽取。
图片：用视觉读图抽取，并把识别到的题目回显给用户确认（题面/几何体/尺寸/所求/语言）后再继续。
随机出题：选定几何体与题型，用 kernel 随机参数求解，答案不规整就重抽。

输出语言跟随提示词语言：英文提示 → 英文网页，中文 → 中文。spec 里记下
language
。

Organize the problem into a structured spec (see

references/problem-schema.md

for format): geometry type and dimensions, known construction points/conditions, type and object of the required solution, language.

Text Problems: Extract directly.
Images: Extract using visual image recognition, and echo the recognized problem to the user for confirmation (problem statement/geometry/dimensions/required solution/language) before proceeding.
Random Problem Generation: Select the geometry type and problem type, use the kernel to solve with random parameters, and reselect if the answer is not regular.

Output Language Follows Prompt Language: English prompts → English web pages, Chinese prompts → Chinese web pages. Record
language
in the spec.

第 2 步：用 kernel 精确计算（不要心算）

Step 2: Perform Precise Calculations with the Kernel (Do Not Calculate Manually)

按

references/conventions.md

的建系约定与解法配方，调用

lib/geometry_kernel.py

：得到精确坐标、关键向量、法向量、最终答案，以及各步骤要展示的中间量（均为 LaTeX 字符串）。顶点的 three.js 坐标用

kernel.to_three(points, scale)

得到。

可先在命令行跑 kernel 验证答案，例如：

bash

python3 lib/geometry_kernel.py    # 内置样例自检

Follow the coordinate system conventions and solution recipes in

references/conventions.md

, call

lib/geometry_kernel.py

: Obtain precise coordinates, key vectors, normal vectors, final answers, and intermediate quantities to be displayed in each step (all as LaTeX strings). Use

kernel.to_three(points, scale)

to get the three.js coordinates of vertices.

You can first run the kernel in the command line to verify the answer, for example:

bash

python3 lib/geometry_kernel.py    # Built-in sample self-check

第 3 步：组装 lesson data 并注入模板

Step 3: Assemble Lesson Data and Inject into Template

📍 输出位置（重要）：成品 HTML 一律写到用户当前工作目录（
Path.cwd()
），除非用户显式指定路径。 绝不要写进技能自身目录（
skills/edu-solid-geometry/output/
等）——那是技能内部的开发样例目录。临时构建脚本也放到 cwd 或临时目录（如
/tmp
），用完可删。

写一个临时构建脚本，导入 kernel、bodies、generate，拼出

lesson

steps

model

数据（schema 见

references/problem-schema.md

），再调用

generate.render_html(data, out)

注入模板产出 HTML。

out

用 cwd 下的绝对路径：

python

from pathlib import Path
out = Path.cwd() / "solution-<题目简述>.html"   # 落在用户当前目录，而非技能目录
generate.render_html(data, out)

```
steps[*].content
```
里的所有数值直接引用 kernel 的计算结果，模型只负责组织讲解文字（按目标语言书写）。

model.points

用

kernel.to_three(...)

的结果；

model.spheres

edges

用

lib/bodies.py

的拓扑（

quad_pyramid

tri_pyramid

cuboid

cube

prism

），罕见几何体可手写 edges。

每步配
```
highlight
```
（该步可见元素的绝对集合）与
```
cameraPos
```
。
题面给出线段长度时：为对应棱加
```
measure
```
元素（
```
label
```
用 LaTeX，如
```
2\sqrt{2}
```
），并把它放进"建系/列已知条件"那步的
```
highlight
```
，在 3D 图中点处标出长度（见 problem-schema）。
英文输出时填
```
lesson.ui
```
英文文案并设
```
lesson.language="en"
```
。

可直接参考的范例：

scripts/generate.py

里的

build_data()

（正四棱锥·线面角）、

build_cube_data()

（正方体·线面角）、

build_box_volume_data()

（长方体·体积）都是完整范本，照着改即可。

generate.py

可直接出已注册的题；不传路径时默认写到当前工作目录（cwd），也可显式给 cwd 下的文件名（用技能目录里的

scripts/generate.py

，输出落在 cwd）：

bash

python3 <技能目录>/scripts/generate.py cube ./cube.html
python3 <技能目录>/scripts/generate.py box  ./box.html

随机出题：

generate.py random <seed> [输出.html]

，内部用

kernel.is_clean(...)

判答案规整、不过重抽：

bash

python3 <技能目录>/scripts/generate.py random 7 ./random.html   # 不给路径则默认 ./random.html(cwd)

扩展随机题型时沿用"随机参数 → 求解 → is_clean 不过就重抽"。

📍 Output Location (Important): The finished HTML file must be written to the user's current working directory (
Path.cwd()
), unless the user explicitly specifies a path. Never write to the skill's own directory (such as
skills/edu-solid-geometry/output/
) — that is the internal development sample directory of the skill. Temporary build scripts should also be placed in the cwd or a temporary directory (such as
/tmp
) and can be deleted after use.

Write a temporary build script, import kernel, bodies, generate, assemble

lesson

steps

model

data (schema see

references/problem-schema.md

), then call

generate.render_html(data, out)

to inject into the template and generate HTML. Use an absolute path under cwd for

out

python

from pathlib import Path
out = Path.cwd() / "solution-<brief-problem-description>.html"   # Saved in user's current directory, not the skill directory
generate.render_html(data, out)

All numerical values in
```
steps[*].content
```
directly reference the calculation results of the kernel; the model only needs to organize the explanatory text (written in the target language).

Use the results of

kernel.to_three(...)

for

model.points

; use the topology from

lib/bodies.py

for

model.spheres

edges

(

quad_pyramid

tri_pyramid

cuboid

cube

prism

), and manually write edges for rare geometries.

Configure
```
highlight
```
(absolute set of visible elements for this step) and
```
cameraPos
```
for each step.
When line segment lengths are given in the problem statement: Add a
```
measure
```
element to the corresponding edge (use LaTeX for
```
label
```
, such as
```
2\sqrt{2}
```
), and include it in the
```
highlight
```
of the "Establish Coordinate System/List Known Conditions" step to mark the length at the point in the 3D diagram (see problem-schema).
For English output, fill in English copy for
```
lesson.ui
```
and set
```
lesson.language="en"
```
.

Directly Referable Examples:

build_data()

(regular square pyramid · line-plane angle),

build_cube_data()

(cube · line-plane angle),

build_box_volume_data()

(cuboid · volume) in

scripts/generate.py

are complete templates; you can modify them accordingly.

generate.py

can directly generate registered problems; if no path is passed, it defaults to writing to the current working directory (cwd), or you can explicitly specify a file name under cwd (use

scripts/generate.py

in the skill directory, output will be in cwd):

bash

python3 <skill-directory>/scripts/generate.py cube ./cube.html
python3 <skill-directory>/scripts/generate.py box  ./box.html

Random Problem Generation:

generate.py random <seed> [output.html]

, internally uses

kernel.is_clean(...)

to judge if the answer is regular, and reselects if not:

bash

python3 <skill-directory>/scripts/generate.py random 7 ./random.html   # Defaults to ./random.html(cwd) if no path is given

When expanding random problem types, follow the "random parameters → solve → reselect if not passing is_clean" process.

第 4 步：自检（对应正确性方案）

Step 4: Self-Check (Corresponding to Correctness Plan)

kernel 答案 == 答案卡
```
answerValue
```
== 末步骤展示的最终值（generate.py 已有断言示例）。
3D 顶点坐标来自
```
kernel.to_three
```
（与解题同源）。
起本地静态服务（服务输出文件所在目录，即 cwd）用预览检查：无控制台报错、公式渲染正常、分步高亮/镜头符合预期。（技能仓库内开发时可用
```
.claude/launch.json
```
的
```
geom-preview
```
；在别处运行就对 cwd 起一个临时静态服务。）

⚠️ 必须关闭你开过的端口/服务：预览检查一结束就立即停掉本地服务，绝不留下占用端口的进程。
用 preview 工具开的：检查完马上
preview_stop
（传对应 serverId）。
直接起的
http.server
：用完
kill
掉，或核对
lsof -nP -iTCP:<port> -sTCP:LISTEN
确认已释放。
交付前确认端口已释放，再告诉用户结果。开了不关 = 未完成自检。

Kernel answer == answer card
```
answerValue
```
== final value displayed in the last step (generate.py already has assertion examples).
3D vertex coordinates come from
```
kernel.to_three
```
(same source as problem solving).
Start a local static server (serving the directory where the output file is located, i.e., cwd) to preview and check: no console errors, formulas rendered correctly, step-by-step highlighting/camera meets expectations. (When developing in the skill repository, you can use
```
geom-preview
```
in
```
.claude/launch.json
```
; when running elsewhere, start a temporary static server for cwd.)

⚠️ Must Close Any Ports/Services You Opened: Immediately stop the local service after preview and checking, never leave port-occupying processes running.
If opened with a preview tool: Run
preview_stop
(pass the corresponding serverId) immediately after checking.
If using
http.server
directly: Kill it after use, or verify release with
lsof -nP -iTCP:<port> -sTCP:LISTEN
.
Confirm the port is released before delivering, then inform the user of the result. Failing to close the service = incomplete self-check.

第 5 步：交付

Step 5: Delivery

成品写在用户当前工作目录（cwd），命名形如

solution-<题目简述>.html

，把（cwd 下的）路径告诉用户，可直接浏览器打开。交付前确认：(1) 成品在 cwd、不在技能目录；(2) 没有遗留任何由本次预览开启的本地服务/端口。

The finished product is written to the user's current working directory (cwd), named in the format

solution-<brief-problem-description>.html

. Inform the user of the path (under cwd), which can be directly opened in a browser. Before delivery, confirm: (1) The finished product is in cwd, not the skill directory; (2) No local services/ports opened during this preview are left running.

扩展

Expansion

加题型：在
```
geometry_kernel.py
```
加求解函数（见 conventions 配方表），在
```
generate.py
```
加一个
```
build_*
```
。
加几何体：在
```
geometry_kernel.py
```
加坐标构建函数，在
```
bodies.py
```
加棱拓扑。

Add Problem Types: Add solution functions in
```
geometry_kernel.py
```
(see conventions recipe table), and add a
```
build_*
```
function in
```
generate.py
```
.
Add Geometries: Add coordinate construction functions in
```
geometry_kernel.py
```
, and add edge topology in
```
bodies.py
```
.

edu-solid-geometry

Original

Translation

立体几何解题 → 交互网页

Solid Geometry Problem Solving → Interactive Web Page

这个技能产出什么

What This Skill Produces

依赖（重要）

Dependencies (Important)

工作流程

Workflow

第 1 步：得到 problem spec（三入口归一）

Step 1: Obtain Problem Spec (Unify Three Entries)

第 2 步：用 kernel 精确计算（不要心算）

Step 2: Perform Precise Calculations with the Kernel (Do Not Calculate Manually)

第 3 步：组装 lesson data 并注入模板

Step 3: Assemble Lesson Data and Inject into Template

第 4 步：自检（对应正确性方案）

Step 4: Self-Check (Corresponding to Correctness Plan)

第 5 步：交付

Step 5: Delivery

扩展

Expansion

目录

Directory