edu-solid-geometry

Solid geometry problem solving → interactive webpage

What this skill produces

A single-page HTML file that can be opened directly in a browser: on the left, the problem statement/answer/step-by-step explanation (formulas using MathJax), on the right is the 3D model corresponding to the problem (Three.js, rotatable and zoomable, highlighting key elements step by step and switching cameras). The form is consistent with template/lesson.html .

Dependencies (important)

The computation core lib/geometry_kernel.py depends on sympy. Before running the script, first confirm there is one that can import sympy python3: run python3 -c "import sympy"。

Handling when libraries are missing (important): if import reports an error (the same applies to sympy or any library used later),first ask the user whether to install, and only after getting consent help install it (python3 -m pip install <库名>), or switch to an interpreter that already has the library installed;do not install directly without asking. In the commands below, python3 all refer to this interpreter that can run the dependencies.

Workflow

Step 1: Obtain the problem spec (unify the three entry points)

Organize the problem into a structured spec (format see references/problem-schema.md): geometry type and dimensions, known constructed points/conditions, the requested type and object,language。

• Text problem: extract directly.
• Image: extract by visual reading, andecho the recognized problem back to the user for confirmation(problem statement/geometry/dimensions/requested/language) before continuing.
• Random problem generation: choose the geometry and problem type, use the kernel to solve with random parameters, and redraw if the answer is not neat.

Output language follows the prompt language: English prompt → English webpage, Chinese → Chinese. Record in the spec language。

Step 2: Use the kernel for exact computation (do not do mental math)

According to references/conventions.md 's coordinate system conventions and solution recipes, call lib/geometry_kernel.py: obtain exact coordinates, key vectors, normal vectors, the final answer, and the intermediate quantities to display at each step (all as LaTeX strings). Use kernel.to_three(points, scale) to obtain the three.js coordinates of the vertices.

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

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

Step 3: Assemble the lesson data and inject it into the template

📍 Output location (important): the finished HTML must always be written tothe user's current working directory (Path.cwd()）, unless the user explicitly specifies a path. Neverwrite into the skill's own directory (skills/edu-solid-geometry/output/ etc.)—that is the skill's internal development sample directory. Temporary build scripts should also be placed in cwd or a temporary directory (such as /tmp), and can be deleted after use.

Write atemporary build script, import kernel, bodies, generate, assemble the lesson / steps / model data (schema see references/problem-schema.md), then call generate.render_html(data, out) to inject the template and produce HTML. out Use an absolute path under cwd：

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

• steps[*].content all numerical values indirectly reference the computation results of the kernel, and the model is only responsible for organizing the explanatory text (written in the target language).
• model.points use kernel.to_three(...) results;model.spheres/edges use lib/bodies.py topology (quad_pyramid / tri_pyramid / cuboid / cube / prism), and for rare geometric bodies, edges can be written by hand.
• For each step, pair highlight(the absolute set of visible elements for that step) with cameraPos。
• When the problem statement gives segment lengths: add measure elements for the corresponding edges (label use LaTeX, e.g. 2\sqrt{2}), and put it into the highlightof the "set up coordinates / list known conditions" step, and mark the length at the point in the 3D figure (see problem-schema).
• For English output, fill in lesson.ui English copy and set lesson.language="en"。

Examples that can be directly referenced：scripts/generate.py the build_data()(regular square pyramid · line-plane angle), build_cube_data()(cube · line-plane angle),build_box_volume_data()(cuboid · volume) are all complete templates; just modify them accordingly.

generate.py can directly produce registered problems;when no path is passed, it defaults to writing to the current working directory (cwd), or you can explicitly give a filename under cwd (using the scripts/generate.pyin the skill directory, with output landing in cwd):

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

Random problem generation：generate.py random <seed> [输出.html], internally using kernel.is_clean(...) to check whether the answer is clean and redraw if not:

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

When extending random problem types, follow "random parameters → solve → redraw if is_clean fails".

Step 4: Self-check (corresponding to the correctness plan)

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

⚠️ You must close any ports/services you opened: stop the local service immediately once the preview check is finished,never leave behind a process occupying a port。

• Opened with the preview tool: immediately after checking, preview_stop(pass the corresponding serverId).
• Started directly with http.server: when done, kill it, or check lsof -nP -iTCP:<port> -sTCP:LISTEN to confirm it has been released.
• Before delivery, confirm the port has been released, then tell the user the result. Opening without closing = self-check not completed.

Step 5: Delivery

The finished product is written inthe user's current working directory (cwd), named like solution-<题目简述>.html, tell the user the (cwd-relative) path, and it can be opened directly in a browser. Before delivery, confirm:(1) the finished product is in cwd, not in the skill directory;(2) no local service/port opened by this preview remains.

Extension

• Add problem type: in geometry_kernel.py add a solving function (see the conventions recipe table), in generate.py add a build_*。
• Add geometric body: in geometry_kernel.py add a coordinate construction function, in bodies.py add edge topology.

Table of Contents

• template/lesson.html — Data-driven templates (general 3D renderer + data island __LESSON_DATA__）
• lib/geometry_kernel.py — sympy exact computation core
• lib/bodies.py — Geometric solid edge topology library
• scripts/generate.py — Injection templates + example construction functions
• references/problem-schema.md — Data format
• references/conventions.md — Coordinate system conventions, solution recipes, self-checks