Produce a single-page HTML that can be opened directly in a browser: problem statement/answer/step-by-step analysis on the left (MathJax), the corresponding 3D model on the right (Three.js, rotatable and zoomable, step-by-step highlighting + camera switching).
Only read these two files
references/api.md— spec format, query problem types, placeholders, commands.Read it before starting work.references/problem-schema.md— the fields and element types of lesson.json. Read it when writing the explanation.
Do not read template/lesson.html(51KB)、lib/*.py、scripts/*.py— everything inside is
api.md all clearly written out; reading the source code is a pure waste of context. English UI text is injected automatically, no need to go digging through templates.
Process (2 tool calls: write one JSON, run one command)
problem.json Four top-level keys:spec(problem structure) + lesson / steps / model(explanation content).
1a. spec — turn the problem into a structure (format see api.md)
Solid + dimensions + constructed points + what is asked + language. Built-in solids cover rectangular prisms/cubes, regular n-gonal prisms and regular n-gonal pyramids,
right prisms (arbitrary base), regular tetrahedra, cylinders, cones;For more obscure polyhedra use body: "custom" to directly give vertex coordinates,
don't write Python just because "there's no built-in". All three entry points normalize to here:
- Text problem: extract directly.
- Image: after visually reading the image,echo the recognized problem statement/solid/dimensions/what is asked to the user for confirmationthen continue.
- Random problem generation: directly use
scripts/generate.py random <seed> ./random.html, one command produces the figure, and the process ends here.
Output language follows the prompt language: English prompt → English webpage. Just write
"language": "en"in the spec, the UI text switches automatically, you only need to writetitle/stepsin English.
1b. lesson / steps / model — explanation content
lesson(problem statement) + steps(about 4 steps: set up coordinates → key vectors → normal vector → substitute into formula) + model.elements。
- All numerical values must use placeholders(
{{answer}}/{{vals.sin}}/{{mp.A}}), don't do mental math, don't hand-copy. points/spheres/edges/target/initialCamera/answerValueNo need to write, it will be filled in automatically.- Multi-part problems(problem statement has
(1)(2)(3)): separate sub-questions with<br>on separate lines, list answers withlesson.answersfor each sub-question, do notstring multiple answers together with;intoanswerValue— that will deform the answer card, and validation will also block it. - When the problem statement gives segment lengths, declare them in the spec's
lengths, then add ameasureelement, and put it into the "set up coordinates" step'shighlight。
2. Generate figure + self-check
python3 <技能目录>/scripts/build.py problem.json "$(pwd)/solution-<题目简述>.html"
One command completes solving, placeholder substitution, default value completion, rendering, and static self-check.
Printing PASS means it passed (answer consistency, highlight keys, point references, and formula delimiters have all been validated);
printing FAIL Then fix problem.json according to the issues it lists and rerun,do nottroubleshoot by starting the service and taking screenshots.
📍 Write both the final output and intermediate files to the user's current working directory (cwd), and never write them into the skill's own directory. Only start a local service preview when the user explicitly asks to "see the result"; stop it immediately after viewing, and do not leave behind a process occupying a port.
3. Delivery
Tell the user the HTML path under cwd, which can be opened directly in a browser.
When dependencies cannot be installed
requires sympy. When an import fails,first ask the user whether to install, and after they agree then
python3 -m pip install sympy, or switch to an interpreter that already has the library installed;do not install directly without asking。
Extension and Maintenance
- Add a question type/geometry: in
lib/geometry_kernel.pyadd the function, inscripts/solve.py'sBODIES/QUERIESregister it, and updatereferences/api.md's table. - Run regression after changes:
python3 <技能目录>/scripts/selftest.py(only for maintaining the skill, do not run it in the problem-solving workflow).
Directory
references/api.md— spec format / question types / placeholders / commands ← read oftenreferences/problem-schema.md— lesson.json fields ← read oftenscripts/build.py— solve + render + self-check in one commandscripts/solve.py— spec → exact solution (can be run separately to see the answer)scripts/validate.py— final output static self-checkscripts/generate.py— built-in problems and random problem generationscripts/selftest.py— the skill's own regression testslib/geometry_kernel.py·lib/bodies.py·template/lesson.html— internal implementation, no need to read