dsh-mathmatic-symbol

dsh-mathmatic-symbol

English | 中文

The npm package name is @jaxzhou/dsh-mathmatic-symbol.

A DeepSeek Harness plugin that gives the agent four tools: typeset LaTeX into an image, draw a mathematical figure from a declarative spec, and convert a formula or SVG into an image ready to drop into a document. Every artifact is a font-free SVG — each glyph is an outline <path> — plus an optional PNG, returned together with Markdown / HTML / LaTeX snippets.

The plugin also registers prompt guidance that tells the model when to reach for it — an image or a document file is the deliverable, or the user asks for one — and not to hand-write SVG, LaTeX-rendering, or plotting code instead. In a session with this plugin installed, producing a formula image, a geometric figure, or a document containing them is a tool call, not a coding exercise.

dsh plugin --profile web add @jaxzhou/dsh-mathmatic-symbol
dsh --profile web

A 14-second screen recording of the plugin in a live session — click through for the full-quality video (3358×1480 H.264).

Below, a still the plugin produced — no fonts, no external tools:

math_figure from examples/unit-circle.json — unit circle, $\sin\theta$/$\cos\theta$ projections, angle arc and LaTeX title. Nothing in this image depends on an installed font.

Contents

• Why images instead of text
• Quick start
• When the agent reaches for these tools
• The four tools · math_formula · math_figure · math_convert · math_document
• Figure spec reference
• Coordinate expressions
• Documents with formulas and figures inserted
• Output: paths, naming, layout
• Embedding into documents
• Inline preview
• Configuration · Disable and uninstall
• Requirements and verification
• Privacy and authority
• Known limitations
• Development

Why images instead of text

A formula in a chat message is text; in a report, slide, Word file, or PDF it usually has to be a picture. Producing that picture reliably is the whole point of this plugin:

• No font dependency. MathJax runs with fontCache: 'none', so every glyph becomes an outline path. The SVG contains no <defs>, <use>, id, or font-family: it renders identically in a browser, in Word, in an \includegraphics pipeline, and on a build machine with no math fonts installed.
• Deterministic rasters. PNG output comes from @resvg/resvg-js with system font loading disabled — the same bytes on every machine.
• Content-addressed files. The same input always writes the same file name, so re-running a call overwrites instead of littering the workspace.
• Document-shaped output. Every call returns embed.markdown_svg, embed.html_png, embed.latex_png, and optional base64 data URIs.

The trade-off is deliberate: because text is outlined, labels are not selectable or searchable inside the image.

Quick start

A formula. math_formula takes bare TeX; $…$, $$…$$, \[…\], \(…\), and \begin{equation}…\end{equation} are stripped for you.

math_formula({ latex: "\\int_0^\\infty e^{-x^2}\\,dx = \\frac{\\sqrt{\\pi}}{2}" })

→ writes math/formula-f091edca9660.svg and math/formula-f091edca9660.png, and returns paths, sizes and snippets (the alt text is abbreviated here):

<math kind="formula" display="true" width="148" height="55">
svg: math/formula-f091edca9660.svg (7.4 KiB, 148x55 at 1x)
png: math/formula-f091edca9660.png (8.5 KiB, 592x220)
markdown: ![\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}](math/formula-f091edca9660.svg)
html: <img src="math/formula-f091edca9660.svg" width="148" height="55" alt="…">
latex: \includegraphics[width=3.92cm]{math/formula-f091edca9660.png}
</math>

Snippets place both formats at the 1× display size (148 px), so the 4× PNG is a high-density asset for the same layout box rather than a 4× larger picture.

A figure. math_figure takes a JSON spec in mathematical coordinates, with named points and LaTeX labels:

math_figure({ figure: { …see examples/triangle.json… }, name: "triangle" })

The spec behind the example above lives in examples/triangle.json; a right triangle with a right-angle marker, an angle label, grid and axes:

{
  "width": 420, "height": 320,
  "xRange": [-1, 5], "yRange": [-1, 4],
  "axes": true, "grid": true, "aspect": "equal",
  "vars": { "a": 3, "b": "2 * a" },
  "elements": [
    { "type": "polygon", "points": [[0, 0], [4, 0], [0, "a"]], "fill": "#93c5fd", "fill_opacity": 0.25 },
    { "type": "point", "at": [0, 0], "label": "A", "label_offset": [-14, 12] },
    { "type": "point", "at": [4, 0], "label": "B", "label_offset": [14, 12] },
    { "type": "point", "at": [0, "a"], "label": "C", "label_offset": [-14, -12] },
    { "type": "segment", "from": "A", "to": "B", "label": "c", "label_offset": [0, 14] },
    { "type": "angle", "at": "B", "from": "A", "to": "C", "label": "\\beta" },
    { "type": "angle", "at": "A", "from": "B", "to": "C", "right": true }
  ]
}

More specs you can render as-is: examples/unit-circle.json, examples/rose.json (a three-petal polar rose), examples/function-plot.json (a stretch-aspect function plot).

A document. math_document renders the formulas and figures and inserts them for you — no paths to invent, no markup to splice:

math_document({
  path: "docs/report.md",
  body: "# Area of a disc\n\nThe area is $A=\\pi r^2$ for radius $r$.\n\n$$A = \\int_0^1 2\\pi r\\,dr$$\n\n[[figure:triangle]]\n",
  math: "image",
  figures: { triangle: { /* a math_figure spec */ } }
})

→ writes docs/report.md plus docs/report-assets/*.svg|png, referencing each image relative to the document:

<document format="markdown" path="docs/report.md" bytes="262" math="image" self_contained="false">
assets: docs/report-assets (4 images)
  $A=\pi r^2$ → docs/report-assets/formula-83490f278b73.svg (73x32)
  $r$ → docs/report-assets/formula-86965ab96917.svg (32x32)
  $$A = \int_0^1 2\pi r\,dr$$ → docs/report-assets/formula-65e3b2edd39f.svg (118x56)
  [[figure:triangle]] → docs/report-assets/triangle-7f4ecb6f5507.svg (300x240)
</document>

Conversion. math_convert handles what the others do not: an existing SVG string, or an SVG/PNG file already in the workspace.

math_convert({ source: { path: "diagrams/flow.svg" }, format: "png", scale: 3 })

Foreign SVG is sanitized first — scripts, foreign markup, event handlers, DOCTYPE, external references, remote paint servers and fetching styles are removed, and every removal is reported in warnings.

Try it without a Harness

The drawing layer is an ordinary library call, so a spec can be previewed from a source checkout:

npm install
node scripts/render-example.mjs examples/rose.json          # writes .tmp/examples/rose.{svg,png}
node scripts/render-example.mjs examples/triangle.json out --scale=2

When the agent reaches for these tools

Tool descriptions say what a tool can do; they do not stop a model from writing its own SVG, shelling out to a plotting library, or inventing image paths. So the plugin also registers one ordered system-prompt section (tool:math-symbol, at the TOOL_REPORT position) that states the trigger and the boundary:

Math and figures: when a formula or a geometric/function figure is needed as an image, or a document with such images embedded is the deliverable (or the user asks for one), use these tools rather than writing your own rendering code … Every call writes the image files into the session workspace, names them content-addressed, and returns paths plus ready-to-paste Markdown/HTML/LaTeX snippets — use what the tool returns; do not re-derive paths, re-encode images, or re-implement the rendering with SVG, LaTeX tooling, or a plotting library. Ordinary chat answers keep using LaTeX text directly; these tools are for image or document deliverables.

Two properties matter:

• On demand, not always. An answer that merely mentions a formula still uses LaTeX text; the tools appear when an image or a document file is the deliverable.
• Self-collapsing. The section resolves the visible tools on every assembly and returns an empty string when none are in scope, so hiding the tools also hides the instruction to use them.

It is registered through ctx.inject(['systemPrompt'], …): a composition without a system prompt still gets the tools, it just loses the steering text.

The four tools

All four share the common parameters and return a structured result.

math_formula

A TeX error never throws: MathJax's error marker is drawn into the image and the result carries a warning.

math_figure

math_convert

A PNG source is passed through as-is (no re-encode): the result points at the existing file and returns embed snippets for it.

math_document

Common parameters

Unknown arguments are refused with the list of supported ones; a typo is never silently ignored.

Figure spec reference

Top-level fields of the figure object:

Elements

A point is either [x, y] — numbers or expression strings — or a string naming an earlier point element's label, which is how "the median from A" stays readable. Points may only reference points defined before them.

Notes that save a round trip:

• Every label is LaTeX — in math mode. Write A_1, \alpha, \frac{\pi}{2}; use \text{…} for upright words.
• label_offset is in screen pixels, x right and y down.
• angle and arc angles are degrees and positive angles run counter-clockwise in mathematical orientation; polar/parametric ranges are in radians.
• fill expects an opaque or alpha-hex color (#93c5fd33); fill_opacity is the escape hatch when you prefer to keep the color plain.
• Curves are split at the viewport edge instead of being clipped, so a pole like tan(x) breaks the line rather than drawing a fake vertical segment.
• Out-of-domain samples (ln(x) for x ≤ 0) are skipped and counted in a warning.

Coordinate expressions

Every coordinate and every curve definition may be an expression. The evaluator is a hand-written recursive-descent compiler — model-authored text is never eval-ed — with a source-length cap and a 64-level nesting cap.

• Operators: + - * / % ^ (right-associative), parentheses, unary minus.
• Implicit multiplication: 2x, 3sin(x), 2(x+1), x y.
• Constants: pi (or π), tau, e, phi.
• Functions: sin cos tan asin acos atan atan2 sinh cosh tanh asinh acosh atanh sqrt cbrt abs exp ln log log2 log10 floor ceil round trunc sign min max pow hypot mod gcd cot sec csc.
• Backslashes are tolerated: \sin(\pi/2) works.
• Curve variables: x (cartesian), t (parametric), theta/θ (polar).
• Unknown variables, unknown functions, wrong arity, and over-deep nesting are hard errors naming the offender.

Documents with formulas and figures inserted

math_document is the "give me the file" tool. Three things make it more than a concatenation:

• References are relative to the document. An asset written to docs/report-assets/ is referenced as report-assets/… from docs/report.md, so the pair can be moved or committed together.
• Insertion is format-correct. Markdown gets ![alt](path); HTML gets <img … width height alt> with inline math baseline-aligned through vertical-align; LaTeX gets \includegraphics[width=…cm] — wrapped in a centered environment for display math and figures, and raised by its ink depth (\raisebox) for inline math, so formulas sit on the baseline instead of floating.
• Self-contained is one flag. self_contained: true inlines every image as a base64 data URI and writes no asset files: one file you can paste into a ticket or open from anywhere. (LaTeX is refused, because \includegraphics needs a file.)

math: "native" is the default and the lighter choice: formulas stay as markup for the renderer to typeset, and only figures become images. Choose math: "image" when the target cannot typeset math — Word, a plain-text pipeline, PDF conversion — or when the user asks for formula images. For HTML with native math the wrapper includes a MathJax CDN bootstrap (disable with mathjax: false to supply your own).

Nothing is dropped silently: a [[figure:name]] without a matching spec is a hard error listing the names you provided, and a provided-but-unreferenced figure is reported as a warning. Two details about the placeholder: the double-brace spelling shipped in 0.1.1 is still accepted as an input alias (though it never appears in prompt text, where the Harness reserves {{name}} for variable interpolation), and the name may contain letters, digits, _ and - — anything else stays literal.

Output: paths, naming, layout

<session workspace>/
└── math/                             # configurable via outputDir
    ├── formula-1f0c9a2b3c4d.svg      # content hash of the formula + options
    ├── formula-1f0c9a2b3c4d.png
    ├── triangle.svg                  # when a `name` is given
    └── triangle.png

• Relative paths are resolved against the calling session's working directory, and a path that escapes it — including through a symlinked ancestor — is refused.
• Files are written atomically (temporary sibling + rename).
• The result reports both svg_path (workspace-relative, for documents) and svg_host_path (absolute, for other tools), plus byte counts and both CSS and pixel dimensions.

Embedding into documents

Formats that were not produced are empty strings, never stale content.

Inline preview

With preview: true, the PNG is also attached to the tool result as a durable image block, so a Web session can show it inline. This happens only when the active model declares image input and the deployment mounts a durable attachment store; otherwise the call degrades to a warnings entry such as inline preview unavailable: model "…" does not declare image input. It is never an error, and the files are always written regardless.

Configuration

Write it into the profile's cordis.patch.yml (applied after every bundle layer):

- id: jaxzhou-mathmatic-symbol
  config:
    outputDir: math        # asset directory, workspace-relative
    scale: 4               # default PNG zoom
    color: '#000000'       # default formula ink
    background: transparent
    padding: 8
    fontSize: 16           # pixels per em for formulas
    preview: false         # default inline preview
    dataUri: false         # default data-URI output
    # workspaceRoot: /abs/path   # host-side override, mainly for tests

Invalid configuration fails at mount time with the offending field named; nothing is clamped or ignored.

Disable and uninstall

Disable the tools without uninstalling (live profiles pick it up without a restart):

- id: jaxzhou-mathmatic-symbol
  disabled: true

dsh plugin --profile web remove @jaxzhou/dsh-mathmatic-symbol

Requirements and verification

• DeepSeek Harness 0.1.5-rc.2 — Host-only plugin: any profile with the tool registry works, headless, tui, web, or a custom composition. No Web UI is required.
• Node ≥ 22.19 (the range declared by the Harness).
• Runtime dependencies: mathjax-full@^3.2.2 (pure JS) and @resvg/resvg-js@^2.6.2 (native, only for PNG).

What is verified in this repository: