dsh-geogebra 0.0.0-stage → 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/NOTICE.md +92 -0
- package/README.md +346 -2
- package/README.zh.md +307 -0
- package/cordis.patch.yml +9 -0
- package/dist/client.js +54 -0
- package/docs/DETAIL.md +145 -0
- package/docs/DETAIL.zh.md +136 -0
- package/icon.svg +12 -0
- package/lib/acting.js +1 -0
- package/lib/announce.js +3 -0
- package/lib/atomic.js +1 -0
- package/lib/bundle.js +1 -0
- package/lib/construction.js +1 -0
- package/lib/drawings.js +2 -0
- package/lib/engine.js +1 -0
- package/lib/export.js +1 -0
- package/lib/index.js +2 -0
- package/lib/install.js +2 -0
- package/lib/json.js +1 -0
- package/lib/page.js +1 -0
- package/lib/routes.js +5 -0
- package/lib/server.js +1 -0
- package/lib/settings.js +1 -0
- package/lib/status.js +1 -0
- package/lib/zip.js +1 -0
- package/locale/en.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +74 -4
- package/runtime/runtime.mjs +147 -0
- package/runtime/viewer/index.html +30 -0
- package/scripts/check-node.cjs +37 -0
- package/scripts/install-deps.mjs +28 -0
- package/skills/geogebra2d/SKILL.md +197 -0
- package/skills/geogebra3d/SKILL.md +204 -0
- package/skills/reference/README.md +17 -0
- package/skills/reference/animation.md +113 -0
- package/skills/reference/api.md +158 -0
- package/skills/reference/applet/Common_XML_tags_and_types.adoc +1244 -0
- package/skills/reference/applet/File_Format.adoc +74 -0
- package/skills/reference/applet/GeoGebra_App_Parameters.adoc +222 -0
- package/skills/reference/applet/GeoGebra_Apps_API.adoc +759 -0
- package/skills/reference/applet/GeoGebra_Apps_Embedding.adoc +158 -0
- package/skills/reference/applet/SOURCE.md +42 -0
- package/skills/reference/applet/Toolbar.adoc +362 -0
- package/skills/reference/applet/XML.adoc +13 -0
- package/skills/reference/applet/XML_Glossary.adoc +84 -0
- package/skills/reference/applet/XML_tags_in_geogebra_xml.adoc +757 -0
- package/skills/reference/applet/basic-embedding-options.html +69 -0
- package/skills/reference/applet/example-api-listeners.html +127 -0
- package/skills/reference/applet/example-api-save-state.html +60 -0
- package/skills/reference/applet/example-api-sync.html +114 -0
- package/skills/reference/applet/example-api.html +68 -0
- package/skills/reference/commands-syntax.md +906 -0
- package/skills/reference/commands.md +124 -0
- package/skills/reference/mechanisms.md +103 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 LZHD
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/NOTICE.md
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Notices
|
|
2
|
+
|
|
3
|
+
## The skill text
|
|
4
|
+
|
|
5
|
+
`skills/geogebra2d/SKILL.md`, `skills/geogebra3d/SKILL.md` and the notes under `skills/reference/` —
|
|
6
|
+
`commands.md`, `mechanisms.md`, `animation.md` and `api.md` — are adapted from the
|
|
7
|
+
`geogebra-master` skill of the **GeoGebra MCP** project (<https://github.com/123pc/Geogebra_mcp>,
|
|
8
|
+
`skills/geogebra-master/SKILL.md`), which is distributed under the MIT License:
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
MIT © 2026 GeoGebra MCP contributors
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
The wording, the task modes, the mechanism recipes and the self-verification rule come from that project.
|
|
15
|
+
This plugin re-points them from the MCP tool names to the native `geogebra_*` tools, splits the long notes
|
|
16
|
+
into the reference files the two skills share, and adds the offline bundle and the live viewer.
|
|
17
|
+
|
|
18
|
+
Two things under `skills/reference/` are not from that project: `commands-syntax.md` is generated by this
|
|
19
|
+
plugin (`tools/cmd-syntax.mjs`) from the build it runs, and `applet/` is GeoGebra's own documentation — see
|
|
20
|
+
below.
|
|
21
|
+
|
|
22
|
+
Everything else in this package — `lib/`, `client/`, `dist/`, `cordis.patch.yml`, `locale/`, `icon.svg`,
|
|
23
|
+
`docs/` and the runtime — is original work under the MIT License in `LICENSE`.
|
|
24
|
+
|
|
25
|
+
## The way a drawing is registered
|
|
26
|
+
|
|
27
|
+
The model behind `lib/drawings.js`, `lib/acting.js`, `lib/atomic.js` and the conflict rule in `lib/engine.js`
|
|
28
|
+
comes from the **Open Artifact** plugin (`dsh-open-artifact`, Apache-2.0, Copyright 2026 Jim Liu 宝玉,
|
|
29
|
+
<https://github.com/JimLiu/open-artifact>):
|
|
30
|
+
|
|
31
|
+
- a document of its own has an id, a folder and a file, and the session is only its owner;
|
|
32
|
+
- a file is written through a temporary one and renamed over it, so a reader sees either the old file or the new one;
|
|
33
|
+
- while the agent is writing, a write that arrives in that moment is the agent's own echo and not the person's change;
|
|
34
|
+
- a change the person made while a command ran is never written over: nothing is written, and the agent reads the
|
|
35
|
+
file again and merges.
|
|
36
|
+
|
|
37
|
+
This plugin re-points those rules at a GeoGebra construction and writes its own code for them. No code of that
|
|
38
|
+
project is vendored here.
|
|
39
|
+
|
|
40
|
+
## GeoGebra itself
|
|
41
|
+
|
|
42
|
+
The plugin does **not** ship GeoGebra. At runtime it loads the GeoGebra web app from `geogebra.org`, or from
|
|
43
|
+
an offline **GeoGebra Math Apps Bundle** that the user installs separately. Both are GeoGebra's own software
|
|
44
|
+
and are covered by GeoGebra's licence:
|
|
45
|
+
|
|
46
|
+
<https://www.geogebra.org/license>
|
|
47
|
+
|
|
48
|
+
The bundle is never redistributed in this package. Redistributing a package that contains the bundle would
|
|
49
|
+
need GeoGebra's permission: GeoGebra's own terms say that GeoGebra may be copied, distributed and transmitted
|
|
50
|
+
for **non-commercial purposes** only (<https://www.geogebra.org/license>). The plugin therefore downloads the
|
|
51
|
+
bundle at the user's request instead of shipping it, and the user is the one who decides what to do with it.
|
|
52
|
+
|
|
53
|
+
What the package does ship is GeoGebra's **documentation** — the notice for that is in the next section.
|
|
54
|
+
|
|
55
|
+
## GeoGebra's own documentation
|
|
56
|
+
|
|
57
|
+
`skills/reference/applet/` is a copy of the sources of the pages at
|
|
58
|
+
<https://geogebra.github.io/docs/reference/en/> — the applet's JavaScript API, the embedding options, the file
|
|
59
|
+
format and the XML reference. They are copied so that the agent can read them on a machine that cannot reach
|
|
60
|
+
geogebra.github.io, which is the normal case. `skills/reference/applet/SOURCE.md` says which file answers
|
|
61
|
+
what.
|
|
62
|
+
|
|
63
|
+
They come from the [geogebra/integration](https://github.com/geogebra/integration) repository
|
|
64
|
+
(`reference/modules/ROOT/pages`), copied on 2026-11-10, and they carry GeoGebra's own notice, which is kept
|
|
65
|
+
here:
|
|
66
|
+
|
|
67
|
+
> You are free to copy, distribute and transmit GeoGebra for non-commercial purposes.
|
|
68
|
+
> For details see <https://www.geogebra.org/license>
|
|
69
|
+
|
|
70
|
+
The files are shipped unchanged.
|
|
71
|
+
|
|
72
|
+
## Third-party code
|
|
73
|
+
|
|
74
|
+
The runtime speaks the Chrome DevTools Protocol over Node's built-in `WebSocket`, and unpacks zip files with
|
|
75
|
+
Node's built-in `zlib`.
|
|
76
|
+
|
|
77
|
+
The browser half (`client/client.js`) is built into `dist/client.js` with **esbuild** (MIT, © the esbuild
|
|
78
|
+
authors, <https://github.com/evanw/esbuild>). esbuild is a development dependency: it builds the file, it is
|
|
79
|
+
not part of it, and no esbuild code is shipped here.
|
|
80
|
+
|
|
81
|
+
The plugin has one peer dependency, `@deepseek-ai/schemastery`, and the host provides it: the configuration
|
|
82
|
+
schema is a schemastery schema, because the host's configuration loader calls `Config['~standard'].validate()`
|
|
83
|
+
on it. The application resolves a plugin's peer dependencies for it — a plugin in a profile gets the host's own
|
|
84
|
+
copy, whether it was installed from npm or linked as a folder — so an installed plugin needs nothing of its own.
|
|
85
|
+
|
|
86
|
+
`lib/install.js` is the fallback for the one case the host is not there: the plugin's code running under plain
|
|
87
|
+
Node, which is what the unit tests do. It installs the peer dependency into the plugin's own `node_modules` when
|
|
88
|
+
the import fails, and `npm run setup` does the same by hand.
|
|
89
|
+
|
|
90
|
+
The library stays under its own MIT licence; none of it is vendored in this package any more.
|
|
91
|
+
|
|
92
|
+
`lib/vendor/` is gone; the copies it held are not part of this package any more.
|
package/README.md
CHANGED
|
@@ -1,3 +1,347 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-geogebra
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that lets the agent draw in
|
|
4
|
+
GeoGebra: plane geometry, function graphs, 3D objects and animated mechanisms, saved as `.ggb` files,
|
|
5
|
+
exported as `.png` images, and shown to you in a live page you can drive yourself.
|
|
6
|
+
|
|
7
|
+
一个 DeepSeek Harness 插件:让 Agent 直接在 GeoGebra 里作图 —— 几何构造、函数图像、3D 物体、可播放的机构运动简图,
|
|
8
|
+
能存成 `.ggb`、导出 `.png`,还会给你一个可以自己拖滑块的实时查看页面。
|
|
9
|
+
|
|
10
|
+
The whole documentation in Chinese: [README.zh.md](README.zh.md). Only the install and the use:
|
|
11
|
+
[docs/DETAIL.md](docs/DETAIL.md), [docs/DETAIL.zh.md](docs/DETAIL.zh.md).
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
In the DeepSeek Harness desktop app: **Plugins** → **Add plugin** → enter `dsh-geogebra` in **Package name or
|
|
16
|
+
address** → **Install**, and turn the plugin on.
|
|
17
|
+
|
|
18
|
+
Then start a new session and ask for a drawing, or type `/geogebra`.
|
|
19
|
+
|
|
20
|
+
## Requirements
|
|
21
|
+
|
|
22
|
+
- **Google Chrome or Microsoft Edge** on the machine. The plugin starts one of them itself, in the background.
|
|
23
|
+
- **Node.js 22 or newer**. The desktop app ships one and the plugin finds it; nothing to install.
|
|
24
|
+
- Internet access the first time, so GeoGebra's web app can load. After that the drawing works offline, and an
|
|
25
|
+
offline bundle is supported for machines without internet access (see below).
|
|
26
|
+
|
|
27
|
+
No Python, no GeoGebra desktop app.
|
|
28
|
+
|
|
29
|
+
The plugin has one peer dependency, `@deepseek-ai/schemastery`, which the host provides. Installed from npm it
|
|
30
|
+
comes with the host; installed as a folder the plugin fetches it into its own `node_modules` the first time it
|
|
31
|
+
starts, so `npm install` is not something you have to do.
|
|
32
|
+
|
|
33
|
+
## What is inside
|
|
34
|
+
|
|
35
|
+
- `skills/geogebra2d/` and `skills/geogebra3d/`: the two skills the agent reads — the drawing workflow, the
|
|
36
|
+
GeoGebra command idioms, the mechanism recipes, and the self-verification rule. The first one draws in the
|
|
37
|
+
plane, the second one in space.
|
|
38
|
+
- `skills/reference/`: the references both skills read — the command syntax, the mechanism and animation notes,
|
|
39
|
+
and GeoGebra's own manual. The two skills differ in which app they draw in, not in what they read, so there
|
|
40
|
+
is one set of references and both skills take their base directory from the skills folder.
|
|
41
|
+
- `lib/index.js`: the plugin. It registers the skill with the Harness skill registry and the `geogebra_*` tools,
|
|
42
|
+
and it supervises the local GeoGebra runtime.
|
|
43
|
+
- `lib/engine.js`: the bookkeeping between the compiler and the construction file: what the compiler holds, and
|
|
44
|
+
what happens when it is replaced under a command.
|
|
45
|
+
- `client/client.js`: the browser half — the configuration form on the Plugins page, and the open channel that
|
|
46
|
+
opens a drawing in the right sidebar. The application sends it to the page on every reload, so it is
|
|
47
|
+
built into one minified file: `dist/client.js`, with `dist/client.js.map` beside it. `npm run build`
|
|
48
|
+
makes that file, and it is committed, so the plugin works from a folder without a build step. The map is
|
|
49
|
+
for whoever works on the plugin: the published package carries the code alone.
|
|
50
|
+
- `lib/settings.js`: the field list behind the form.
|
|
51
|
+
- `lib/page.js`: the bridge to the viewer page: what it shows, and what the user changes there.
|
|
52
|
+
- `lib/drawings.js`: the drawings: every one has an id, a folder and a file of its own, and this is the list of them.
|
|
53
|
+
- `lib/acting.js`: which drawing the agent is acting on right now, so a change that arrives in that moment is judged right.
|
|
54
|
+
- `lib/announce.js`: telling the person that a drawing is there, so the plugin's own browser stays in the background.
|
|
55
|
+
- `lib/atomic.js`: writing a file through a temporary one, so a reader never sees half of it.
|
|
56
|
+
- `lib/export.js`: copying the drawings into the working directory, one folder each.
|
|
57
|
+
- `lib/routes.js`: the routes of the viewer page: the page, the construction file, and the report of the page.
|
|
58
|
+
- `lib/construction.js`: what a construction is: its structure, its content and its labels.
|
|
59
|
+
- `lib/bundle.js`, `lib/zip.js`: the offline bundle installer, including a small ZIP reader.
|
|
60
|
+
- `lib/server.js`: the small web server of the plugin's own, which serves the viewer page on a fixed port.
|
|
61
|
+
- `lib/status.js`: the one status the agent reads: the compiler, the page, and where to look.
|
|
62
|
+
- `lib/install.js`: the peer dependency installer — the fallback for the plugin running outside the Harness,
|
|
63
|
+
where nobody else resolves the peer. The application resolves it for a plugin in a profile.
|
|
64
|
+
- `lib/json.js`: the lossless-JSON helper the tools use.
|
|
65
|
+
- `runtime/runtime.mjs`: the runtime. It launches the browser, loads the GeoGebra web app in
|
|
66
|
+
it, drives it over the Chrome DevTools Protocol, and serves a small HTTP API on `127.0.0.1`.
|
|
67
|
+
- `runtime/viewer/`: the live viewer page.
|
|
68
|
+
- `scripts/`: `npm run setup` and `npm run dev` for working on the plugin in place. The published package carries
|
|
69
|
+
`setup` alone — the one a user may want — and leaves the rest in the repository.
|
|
70
|
+
- `tools/`: the debugging scripts of this plugin: look into the host's `app.asar`, drive the browser the runtime
|
|
71
|
+
owns, and rebuild the command syntax tables. They are not part of the published package; they live in the
|
|
72
|
+
repository: [https://github.com/LZHD/dsh-plugins/tree/main/dsh-geogebra/tools](https://github.com/LZHD/dsh-plugins/tree/main/dsh-geogebra/tools).
|
|
73
|
+
- `tests/`: the unit tests (`npm test`) and the browser-based checks (`npm run test:e2e`).
|
|
74
|
+
- `docs/`: the short version of this documentation — how to install the plugin and how to use it.
|
|
75
|
+
|
|
76
|
+
## The tools
|
|
77
|
+
|
|
78
|
+
| Tool | What it does |
|
|
79
|
+
|---|---|
|
|
80
|
+
| `geogebra_status` | Everything at once: is the compiler running, is a viewer page connected, how many objects, both viewer URLs |
|
|
81
|
+
| `geogebra_exec` | Run one GeoGebra command, and read back the number it leaves behind |
|
|
82
|
+
| `geogebra_run_commands` | Run an ordered list of commands |
|
|
83
|
+
| `geogebra_create_construction` | A whole drawing in one call: commands, styles, animation, `.ggb` and `.png` |
|
|
84
|
+
| `geogebra_new_construction` | Empty the construction |
|
|
85
|
+
| `geogebra_set_view` | Geometry, algebra, 3D or spreadsheet view, and the visible range |
|
|
86
|
+
| `geogebra_set_appearance` | Colour, line width, point size, visibility — every object in one call |
|
|
87
|
+
| `geogebra_animate` | Start or stop a slider, and its speed |
|
|
88
|
+
| `geogebra_get_objects` | The objects, their number and the range they cover |
|
|
89
|
+
| `geogebra_save` | Write a `.ggb` file |
|
|
90
|
+
| `geogebra_export_png` | Write a `.png` image |
|
|
91
|
+
| `geogebra_viewer` | The URL of the live page of the drawing in use |
|
|
92
|
+
| `geogebra_drawing` | The drawings: list them, start a new one, or go on with one |
|
|
93
|
+
| `geogebra_export` | Copy the drawings of this task into the working directory |
|
|
94
|
+
| `geogebra_load` | Load an existing `.ggb` or `.xml` |
|
|
95
|
+
| `geogebra_bundle` | Install or check the offline GeoGebra bundle |
|
|
96
|
+
| `geogebra_construction` | What the construction holds; the XML only with `xml: true` |
|
|
97
|
+
| `geogebra_write_construction` | Write a construction as GeoGebra XML, without running a command |
|
|
98
|
+
|
|
99
|
+
The tools are written to keep the conversation small: the answers are short, the XML comes only when it is
|
|
100
|
+
asked for, and a drawing is built and styled in as few calls as possible. A round trip carries the whole
|
|
101
|
+
conversation so far, so every call that is avoided is a call that is not paid for twice.
|
|
102
|
+
|
|
103
|
+
## The drawings in your own directory
|
|
104
|
+
|
|
105
|
+
`geogebra_export` copies the drawings of the task into the working directory of the session — the folder the built-in
|
|
106
|
+
file and shell tools use — one folder each:
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
<working directory>/geogebra/
|
|
110
|
+
circle/
|
|
111
|
+
construction.xml ← the construction, as the viewer page reads it
|
|
112
|
+
meta.json ← its id, its name, its owner
|
|
113
|
+
circle.ggb ← only with ggb: true; GeoGebra opens this
|
|
114
|
+
main/
|
|
115
|
+
construction.xml
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The files are copies: the drawings keep living in the plugin's own folder, and the exported ones are yours to edit,
|
|
119
|
+
to commit, or to delete. A drawing whose name another one already took gets the tail of its id, so an export never
|
|
120
|
+
writes over another drawing's files.
|
|
121
|
+
|
|
122
|
+
## The live viewer
|
|
123
|
+
|
|
124
|
+
Every answer carries a `viewerUrl` on `127.0.0.1`. Open it and the drawing appears in your browser: you can
|
|
125
|
+
drag the sliders, run a command yourself, and save the construction from there. A second button shows the
|
|
126
|
+
exact frame the agent sees, animation included.
|
|
127
|
+
|
|
128
|
+
**You do not have to open it.** The plugin's own browser stays in the background — it never shows a window —
|
|
129
|
+
and when a drawing gets its first content, its page opens by itself in the right sidebar of the app, next to
|
|
130
|
+
the conversation. The canvas can be dragged with the mouse right away. Going on with a figure that is already
|
|
131
|
+
there opens its page again, so a tab you closed comes back.
|
|
132
|
+
|
|
133
|
+
The command bar is a row of its own above the canvas, so it never covers GeoGebra's own toolbar; the `☰` button
|
|
134
|
+
folds it away. The viewer frames the same part of the construction the agent did.
|
|
135
|
+
|
|
136
|
+
## One figure is one drawing
|
|
137
|
+
|
|
138
|
+
A figure is a task of its own, and a task has a drawing of its own — a folder, a file and an address:
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
%LOCALAPPDATA%\dsh-geogebra\drawings\<drawingId>\construction.xml
|
|
142
|
+
%LOCALAPPDATA%\dsh-geogebra\drawings\<drawingId>\meta.json
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
The id is new every time (`drw_…`), so nothing can be written over by accident. The session is only the owner:
|
|
146
|
+
one session may ask for three figures in a row, and it gets three drawings, each with its own file and its own
|
|
147
|
+
address.
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
http://127.0.0.1:52711/dsh-geogebra/viewer?id=<drawingId>
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The plugin cannot tell a new figure from a changed one — only the agent knows what the user asked for. So when a
|
|
154
|
+
message comes in and the drawing in use already holds something, the plugin asks the agent to choose, and lays the
|
|
155
|
+
drawing out for it: the id, the name, what it holds, and its address are in every answer, together with a
|
|
156
|
+
`reminder` that names the two calls that make the choice.
|
|
157
|
+
|
|
158
|
+
- `geogebra_drawing { action: "create", name: "circle" }` — a new figure gets a drawing of its own. The answer
|
|
159
|
+
lists the drawings that were already there (`related`), so the agent looks before it makes another.
|
|
160
|
+
- `geogebra_drawing { action: "use", id: "drw_…" }` — a figure that is changed goes on with the one it has, and
|
|
161
|
+
keeps its file and its address.
|
|
162
|
+
- `geogebra_drawing { action: "list" }` — the drawings of the session, and the one in use.
|
|
163
|
+
|
|
164
|
+
A drawing the user changed in the viewer page is marked `changed`: the agent is told to read it again before it
|
|
165
|
+
works on it.
|
|
166
|
+
|
|
167
|
+
The compiler holds the drawing in use — the tools work on one at a time. Switching to another one pushes its
|
|
168
|
+
file into the compiler, so the next command works on it.
|
|
169
|
+
|
|
170
|
+
## The compiler and the page
|
|
171
|
+
|
|
172
|
+
The plugin has two halves, and they never swap roles:
|
|
173
|
+
|
|
174
|
+
| | The compiler | The viewer page |
|
|
175
|
+
|---|---|---|
|
|
176
|
+
| What it does | Runs the agent's commands in a headless Chrome | Shows the construction file and lets the user change it |
|
|
177
|
+
| While nobody looks | It still draws | It waits: the file keeps the drawing |
|
|
178
|
+
| Where the construction lives | In the runtime process | **In a file**: `%LOCALAPPDATA%\dsh-geogebra\drawings\<drawingId>\construction.xml` |
|
|
179
|
+
| Good for | Unattended drawing | Watching the drawing, editing it, dragging the sliders |
|
|
180
|
+
|
|
181
|
+
The file is the truth in between: the compiler writes it after every command, the page loads it and writes back
|
|
182
|
+
what the user changed, and the next command works on what the user made.
|
|
183
|
+
|
|
184
|
+
Two rules keep that truth whole. **One command at a time**: the compiler holds one construction at a time, so every
|
|
185
|
+
command waits for the one before it — two drawings made at the same moment would otherwise publish each other's
|
|
186
|
+
construction. **Whole files only**: every file is written through a temporary one and renamed over it, so a reader
|
|
187
|
+
sees either the old file or the new one, never half of the new one.
|
|
188
|
+
|
|
189
|
+
A compiler that is replaced under a command — it died, or the runtime restarted it — holds the empty construction of a
|
|
190
|
+
fresh applet. The plugin notices, puts the file into the new applet and runs the command again on it, so a drawing is
|
|
191
|
+
never overwritten with an empty construction.
|
|
192
|
+
|
|
193
|
+
`geogebra_status` says all of this in one call: `connected` is whether the compiler runs, `page.connected` is
|
|
194
|
+
whether a page is there, `pageViewerUrl` and `runtimeViewerUrl` are the two addresses, and `pageHint` says what
|
|
195
|
+
to do when no page is connected.
|
|
196
|
+
|
|
197
|
+
## The two skills
|
|
198
|
+
|
|
199
|
+
The 3D view is **not** in the classic GeoGebra app — it is a different app, the Graphing 3D calculator. So the
|
|
200
|
+
plugin has two skills, and the skill you use picks the app:
|
|
201
|
+
|
|
202
|
+
| Skill | App | What it draws |
|
|
203
|
+
|---|---|---|
|
|
204
|
+
| `/geogebra2d` | the classic GeoGebra app | plane geometry, function graphs, animated mechanisms |
|
|
205
|
+
| `/geogebra3d` | the Graphing 3D calculator | surfaces, solids, points in space |
|
|
206
|
+
|
|
207
|
+
The skill that is read decides which app the compiler loads; the viewer page loads the same one. A running
|
|
208
|
+
compiler switches when the drawing asks for the other app — no restart, and the construction goes with it.
|
|
209
|
+
|
|
210
|
+
## The offline bundle
|
|
211
|
+
|
|
212
|
+
For a machine without internet access, GeoGebra's Math Apps Bundle can be used instead of the web app. The
|
|
213
|
+
plugin never ships the bundle; it fetches it, or unpacks it from a zip you already have.
|
|
214
|
+
|
|
215
|
+
The **离线包 zip** setting (the `bundlePath` config) names that zip: an absolute path to a GeoGebra Math Apps
|
|
216
|
+
Bundle. The plugin unpacks it into the folder beside it — the name of the zip without its extension — and serves
|
|
217
|
+
the files from there, so a bundle on another drive or a network share stays where you put it. A folder is not
|
|
218
|
+
accepted: the source is always the archive.
|
|
219
|
+
|
|
220
|
+
**Leave the setting empty and the plugin fetches the bundle itself**, into the cache folder of this machine
|
|
221
|
+
(`%LOCALAPPDATA%\dsh-geogebra\web_bundle` on Windows, `~/Library/Caches/dsh-geogebra/web_bundle` on macOS,
|
|
222
|
+
`~/.cache/dsh-geogebra/web_bundle` on Linux). The download runs in the background: **the web app serves the
|
|
223
|
+
drawing until the bundle is there, and the plugin uses the bundle from the next command on**. Nothing waits for
|
|
224
|
+
the download, and nothing depends on a folder that happens to be on the machine of the person who wrote the
|
|
225
|
+
plugin.
|
|
226
|
+
|
|
227
|
+
```powershell
|
|
228
|
+
# fetch it now (it resumes, and it is slow on some networks)
|
|
229
|
+
geogebra_bundle { action: "install" }
|
|
230
|
+
|
|
231
|
+
# or unpack a zip you already downloaded
|
|
232
|
+
geogebra_bundle { action: "install", zipPath: "F:/geogebra-math.zip" }
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
Both unpack into the folder the plugin serves the bundle from: the one beside the zip of the setting, or the
|
|
236
|
+
cache folder when the setting is empty. `geogebra_bundle { action: "status" }` says which folder that is, and
|
|
237
|
+
whether the bundle is ready.
|
|
238
|
+
|
|
239
|
+
The `bundle` config decides where the GeoGebra app comes from:
|
|
240
|
+
|
|
241
|
+
- `auto` (the default): the web app now, the offline bundle fetched in the background and used from the next
|
|
242
|
+
command on. Nothing waits for the download.
|
|
243
|
+
- `cdn`: always the web app from geogebra.org; the bundle is never fetched.
|
|
244
|
+
- `local`: the offline bundle, and nothing else. When it is not there yet, the plugin fetches it and the drawing
|
|
245
|
+
waits for it — the offline bundle is the point of this setting.
|
|
246
|
+
|
|
247
|
+
Redistributing GeoGebra's bundle needs GeoGebra's own licence terms:
|
|
248
|
+
<https://www.geogebra.org/license>. This plugin does not redistribute it.
|
|
249
|
+
|
|
250
|
+
## Configuration
|
|
251
|
+
|
|
252
|
+
These live in the plugin row's config, and the **Plugins page renders a form for them**: open the sidebar's
|
|
253
|
+
**Plugins** panel, find **dsh-geogebra** under the installed ones, and use the configure control on its row
|
|
254
|
+
(the bundle page shows the same card). Change a value, press **Save**, and the plugin restarts with it. The
|
|
255
|
+
raw values can still be edited in the profile's patch file.
|
|
256
|
+
|
|
257
|
+
| Key | Default | Meaning |
|
|
258
|
+
|---|---|---|
|
|
259
|
+
| `engine` | `auto` | A leftover from the old design, kept so that an older profile still loads. **Not in the form**: the commands always run in the background browser |
|
|
260
|
+
| `backend` | `web` | `web` starts a browser; `desktop` uses GeoGebra Classic 6, starting it if it is not running yet. **Not in the form** — set it in the profile's patch file when you need it |
|
|
261
|
+
| `headless` | `true` | A leftover, no longer used: the browser always runs in the background and never shows a window. **Not in the form** |
|
|
262
|
+
| `bundle` | `auto` | `auto`: the web app now, the offline bundle fetched in the background and used from the next command on; `cdn` always loads from geogebra.org; `local` insists on the offline bundle and waits for it |
|
|
263
|
+
| `browser` | found automatically | Absolute path of a Chrome or Edge executable |
|
|
264
|
+
| `geogebraPath` | found automatically | Absolute path of the GeoGebra Classic 6 executable for the `desktop` backend. **Not in the form** |
|
|
265
|
+
| `bundlePath` | the cache directory | The zip of a GeoGebra Math Apps Bundle (an absolute path). The plugin unpacks it into the folder beside it. Empty uses the cache folder |
|
|
266
|
+
| `dataDir` | the cache directory | Where the drawings live. Every drawing has a folder of its own there |
|
|
267
|
+
| `cdpPort` | `9222` | The debugging port of a desktop GeoGebra. **Not in the form** |
|
|
268
|
+
| `idleTimeoutMs` | `1800000` | When the unused runtime shuts itself down (30 minutes) |
|
|
269
|
+
| `launchTimeoutMs` | `120000` | How long the GeoGebra web app may take to load (120 seconds) |
|
|
270
|
+
| `width` | `1200` | The width of the graphics view in the background browser, and the width of an exported PNG |
|
|
271
|
+
| `height` | `800` | The height of the graphics view in the background browser |
|
|
272
|
+
| `node` | found automatically | Absolute path of the Node.js executable that runs the runtime. **Not in the form** — the plugin finds one by itself |
|
|
273
|
+
| `pagePort` | `52711` | The fixed port the plugin serves the viewer page on. The address stays the same when the app restarts, and the app's own embedded browser opens it |
|
|
274
|
+
|
|
275
|
+
## Working on the plugin
|
|
276
|
+
|
|
277
|
+
The plugin is a folder: edit it in place and the desktop app picks the changes up. Node.js 22 or newer has to
|
|
278
|
+
be on the path for these commands.
|
|
279
|
+
|
|
280
|
+
```powershell
|
|
281
|
+
npm run setup # install the peer dependency into the plugin folder
|
|
282
|
+
npm run dev # the same, and watch package.json for dependency changes
|
|
283
|
+
npm run build # build the browser half: one minified file with a source map
|
|
284
|
+
npm test # the unit tests: no browser, no network, a second or two
|
|
285
|
+
npm run test:e2e # the browser-based checks: needs the runtime to be running
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
`npm run build` builds `client/client.js` into `dist/client.js`. It needs esbuild, which is a development
|
|
289
|
+
dependency: run `npm install` in the plugin folder once. The built file is committed, and the tests say when it
|
|
290
|
+
is older than its source — so a change to the browser half cannot be forgotten at the built file.
|
|
291
|
+
|
|
292
|
+
The build also says what the browser half asks the application for. The React it uses is the application's,
|
|
293
|
+
asked for through the module table the factory is handed, and a module the application does not have is a
|
|
294
|
+
bundle that fails in the browser — where it is much harder to see than at build time. So the build stops
|
|
295
|
+
instead.
|
|
296
|
+
|
|
297
|
+
The published package is not this folder. The workspace stages it in `dist/npm/dsh-geogebra/`: the code under
|
|
298
|
+
`lib/` and `runtime/` is minified there, the manifest is rewritten for the registry (the author's scripts and
|
|
299
|
+
dev dependencies stay out of it), and the source map stays behind. The staged folder keeps the layout of this
|
|
300
|
+
one, because the plugin finds its own files by their place — `new URL('../', import.meta.url)` is the package
|
|
301
|
+
root. `npm run check` in the workspace looks at that staged folder and runs the tests against the minified code,
|
|
302
|
+
so what a user gets is what the check looked at.
|
|
303
|
+
|
|
304
|
+
`npm test` runs the tests in `tests/unit/`: the configuration schema against the form, the page-mode bridge,
|
|
305
|
+
the zip reader, the installer and the documentation. The documentation test is the interesting one — it reads
|
|
306
|
+
the configuration table above and fails when it does not match the schema, so the table cannot go stale.
|
|
307
|
+
|
|
308
|
+
The browser-based checks in `tests/e2e/` need a Chromium browser and the GeoGebra runtime. The runtime is
|
|
309
|
+
started by the plugin on the first tool call, so run one before `npm run test:e2e`. Their output lands in
|
|
310
|
+
`tests/e2e/out/`.
|
|
311
|
+
|
|
312
|
+
## Troubleshooting
|
|
313
|
+
|
|
314
|
+
**`connected: false`.** The compiler is a browser in the background and it sleeps when nothing happens; the
|
|
315
|
+
first command starts it. If that fails, the status names the browser paths it looked at. Install Chrome or
|
|
316
|
+
Edge, or set `browser`.
|
|
317
|
+
|
|
318
|
+
**A blank drawing.** GeoGebra rejects a command it cannot parse and answers `false`. Check the object list
|
|
319
|
+
with `geogebra_get_objects`, and the command syntax in the skill's `reference/commands.md`.
|
|
320
|
+
|
|
321
|
+
**The drawing is off-screen.** `geogebra_get_objects` returns the `bounds` of the construction. Pass an
|
|
322
|
+
explicit `range` to `geogebra_set_view` to frame it.
|
|
323
|
+
|
|
324
|
+
**The desktop backend cannot find GeoGebra.** With `backend: "desktop"` the runtime looks for GeoGebra Classic 6
|
|
325
|
+
in the usual install folders and starts it with `--remote-debugging-port`. If the error names the paths it
|
|
326
|
+
tried, install Classic 6 or point `geogebraPath` at the executable. A GeoGebra that is already running on
|
|
327
|
+
`cdpPort` is used as it is and never restarted.
|
|
328
|
+
|
|
329
|
+
## The documentation
|
|
330
|
+
|
|
331
|
+
| File | What it holds |
|
|
332
|
+
|---|---|
|
|
333
|
+
| `README.md` | this file: the full documentation, English |
|
|
334
|
+
| `README.zh.md` | the same, in Chinese — not a summary, the same text |
|
|
335
|
+
| `docs/DETAIL.md` | the short version: how to install the plugin and how to use it |
|
|
336
|
+
| `docs/DETAIL.zh.md` | the same, in Chinese |
|
|
337
|
+
| `skills/reference/` | the references both skills read: the command syntax, the mechanism and animation notes, GeoGebra's own manual |
|
|
338
|
+
| [`tools/`](https://github.com/LZHD/dsh-plugins/tree/main/dsh-geogebra/tools) | the debugging scripts (in the repository, not in the package) |
|
|
339
|
+
|
|
340
|
+
## License
|
|
341
|
+
|
|
342
|
+
MIT, see `LICENSE`. `NOTICE.md` credits the parts that come from elsewhere: the workflow text in the skill is
|
|
343
|
+
adapted from the GeoGebra MCP project (MIT, © GeoGebra MCP contributors), and the way a drawing is registered,
|
|
344
|
+
versioned and protected against a conflicting write comes from the Open Artifact plugin (Apache-2.0, © Jim Liu).
|
|
345
|
+
|
|
346
|
+
The GeoGebra web app itself is loaded from geogebra.org at runtime and is GeoGebra's own software, under its
|
|
347
|
+
own licence.
|