Files
make-cad/docs/skill/references/domains/addon-development.md
T
NiJingzhe eb2f2c08d3 feat(addon): runtime state outside the payload + 'sca addon check'
- per-addon runtime dirs (~/.sca/runtimes/<name>), created at install,
  untouched by update, removed with the addon; {runtime_dir} placeholder
  in command_prefix and check_cmd alongside {addon_dir}
- 'sca addon check [name]': re-probe the installed runtime NOW and
  refresh the cached registry record (install-time probe is a cache,
  not truth); list shows cached state with its timestamp
- sca addon use exports SCA_RUNTIME_DIR for self-locating provisioning
- update replaces the payload wholesale but preserves a legacy in-payload
  .venv (pre-runtime_dir addons keep working)
- remove: records without runtime_dir delete nothing extra — never
  interpret the missing field as Path('') == CWD (regression test pins
  the exact failure that motivated this guard)
- docs: Payload vs runtime state section, check verb, updated examples
- version 2.1.3b4
2026-09-17 05:18:43 +08:00

266 lines
12 KiB
Markdown

# Task Domain: Addon Development
Author, install, and manage SimpleCADAPI addons: third-party packages that
add non-modeling capabilities — simulation, analysis, downstream tooling —
by consuming `.scadpkg` product packages.
## Use when
- Creating or publishing an addon (a repository with `sca-addon.toml` and
a skill directory).
- Installing, updating, or removing an addon with the `sca` CLI.
- Deciding whether a capability belongs in an addon or in the SDK.
## Boundary: addon vs SDK contribution
| Capability | Belongs in |
| --- | --- |
| Geometry modeling, domain modeling operations, anything that must build BRep inside a session | SimpleCADAPI core (optionally as an extra, e.g. `simplecadapi[fem]`) |
| Verification, analysis, simulation, rendering, export to foreign ecosystems, anything that *consumes* finished geometry | An addon |
An addon has two legal integration modes with the SDK.
**Recommended default — process boundary.** The addon consumes
`.scadpkg` files (members, tags channel, occurrence graph, scene
projection; units are millimeters) and whatever host tooling it needs,
in any language. Dependency conflicts are structurally impossible and
non-Python addons are first-class.
**Allowed — in-process SDK use.** A Python addon may install
`simplecadapi` inside its own environment and import it: the builtin
exporters (STEP/STL/OBJ/MJCF, gmsh meshing) and the package readers
(`read_product_package`, `load_product_package`) exist for exactly this
kind of downstream consumer. The descriptor's `[compat] sca` range
governs which SDK releases that dependency may resolve to — declare
the SDK as a dependency of the addon environment and keep the range
honest.
What holds in both modes: the addon runs in its own environment and is
not installed into the environment that models the geometry — mixing
plugin dependencies into the modeling SDK environment is what the
separation exists to prevent.
## Repository layout
```text
<repo root>/
sca-addon.toml descriptor: machine-checked facts only, no prose
skill/
SKILL.md everything an agent reads; installed as sca-<name>
<supporting assets: scripts, references, templates...>
<runtime code, binaries, docs — addon-owned>
```
One document per audience: the descriptor is read by the `sca` CLI, the
SKILL.md is read by agents. Never duplicate prose into the descriptor.
## Payload vs runtime state
An installed addon lives in two places:
- **Payload** — `<addon home>/<name>`: the repository contents, replaced
wholesale on every install/update. Treat it as a pure function of the
source; nothing provisioned by the user should live here.
- **Runtime state** — `<addon home>/../runtimes/<name>` (`~/.sca/runtimes/<name>`
by default; a redirected `SCA_ADDON_HOME=/x/addons` keeps all state under
`/x/runtimes`): created at install, addressed as `{runtime_dir}` in the
descriptor, never touched by updates, removed with the addon.
Provision virtualenvs and caches here.
The split is what makes `sca addon update` safe to run blindly: the
payload is re-fetched and swapped while provisioned runtime state (a
multi-hundred-MB venv, downloaded models) survives. As a legacy
compatibility shim, an update also preserves a pre-`{runtime_dir}`
`.venv` provisioned inside the payload itself.
## Descriptor reference (`sca-addon.toml`)
Validation is strict: unknown tables and keys are rejected, every
failure names the field and file.
| Field | Rule |
| --- | --- |
| `[addon] name` | lowercase slug `[a-z0-9][a-z0-9-]{0,63}`; becomes the install directory and skill prefix |
| `[addon] version` | dotted numeric with optional pre-release suffix (e.g. `0.3.1`, `2.0.4b2`) |
| `[addon] license` | non-empty; must be accurate — addons are redistributed |
| `[addon] skill_path` | relative POSIX-style directory containing `SKILL.md` |
| `[compat] sca` | version range, comma-separated clauses with `== != >= <= > <`; a bare version means exact match. Ranges, never pins: SDK releases within a range must not break addons. Pre-release suffixes sort before their release (`2.0.4b2 < 2.0.4`); missing trailing components pad with zero (`2.1` == `2.1.0`) |
| `[runtime] kind` | `binary` \| `python-env` \| `docker` \| `none` |
| `[runtime] platforms` | non-empty list, required for `binary`/`python-env`, forbidden for `none`/`docker` |
| `[runtime] check_cmd` | required for `binary`/`python-env`, optional for `docker`, forbidden for `none` |
| `[runtime] command_prefix` | optional shell prelude joined in front of every command the addon runs (see below); `{addon_dir}` resolves to the installed payload, `{runtime_dir}` to the addon's runtime-state directory; no other `{placeholder}` is allowed |
| `[runtime.check_overrides]` | optional per-platform command overrides; keys must be declared platforms |
Closed platform enum (additive across spec versions):
```text
macos-arm64 | macos-x86_64 | linux-x86_64 | linux-aarch64
| windows-x86_64 | windows-arm64
```
## Naming standard: one name everywhere
The addon name is a single identity enforced at install time:
- `[addon].name` == the repo name (the `repo` segment of an
`owner/repo` GitHub source; for a local path, the basename of the git
`origin` URL, falling back to the directory name);
- `[addon].name` == the SKILL.md frontmatter `name:`.
A mismatch is a hard install failure that names both sides. Skill
directories install as `sca-<name>` (no doubling when the name already
starts with `sca-`).
## Command prefix and `sca addon use`
An addon owns its runtime environment. `[runtime].command_prefix` is a
shell prelude — env assignments, `PATH` edits, a `cd` — prepended to
every command the addon runs:
```toml
[runtime]
kind = "python-env"
command_prefix = "PATH=\"{runtime_dir}/.venv/bin:$PATH\""
check_cmd = "{runtime_dir}/.venv/bin/python -c 'import mytool'"
```
- Two placeholders resolve in the prefix and in `check_cmd`:
`{addon_dir}` (the installed payload) and `{runtime_dir}` (the addon's
runtime-state directory — provision venvs there, never inside the
payload; see "Payload vs runtime state").
- `sca addon use <name> <cmd...>` resolves the installed addon by name,
joins prefix + command, and executes it via the shell with
`SCA_ADDON_DIR` and `SCA_RUNTIME_DIR` exported (provisioning scripts
can self-locate); the exit code propagates. `--capture` returns output
in the report instead of streaming it. Without a command, `sca addon
use <name>` reports the prefix and both directories.
- `check_cmd` runs through the same prefix, so a probe like
`python -c 'import mytool'` automatically tests the addon's own
interpreter. The probe executes after the payload is committed, in
the final installed layout; a failing probe stays a loud warning,
never an install blocker.
## `check_cmd` contract
A runtime probe must be fast but meaningful:
1. Exit code `0` means usable; any other exit or a missing command means
not usable.
2. Execution shell is pinned by the spec: `sh -c` on Unix, `cmd /c` on
Windows — write the command accordingly.
3. Completes in about two seconds; no network access, no license
checkout, no GUI launch.
4. A failing probe warns loudly at install time but never blocks the
install — the runtime can be installed afterwards. Re-run it before
first use.
The install/update-time probe is a **cache, not truth**: it records the
state of the machine at that moment, which is usually *before* the
runtime was provisioned. `sca addon list` shows the cached state with
its timestamp (`ok (cached ...)`); `sca addon check <name>` (or
`sca addon check` for every installed addon) re-probes the installed
layout NOW, refreshes the registry record, and is the answer to "is the
runtime usable right now?".
## Addon SKILL.md requirements
The skill is the addon's single agent-facing document:
- **Frontmatter `description` is the routing card.** Hosts surface it to
agents verbatim; state the trigger condition, what the addon consumes
from `.scadpkg` (which members, which tag patterns such as
`interface.*`), and what it produces.
- **Pre-check the runtime.** Run the probe (the descriptor's
`check_cmd`) before first use; on failure, name the missing runtime
and stop — never silently skip the analysis.
- **Declare the consumption contract.** Units are millimeters; state
coordinate-system assumptions and required tags explicitly.
- **Never modify geometry.** An addon analyzes, verifies, or transforms
finished packages; when a task needs geometry changes, return to the
SimpleCADAPI modeling workflows and re-capture.
- **Reference the main skill.** Describe the pipeline end to end:
model with SimpleCADAPI → `capture` a `.scadpkg` → this addon
consumes it.
## Reading a `.scadpkg`
The complete consumer-facing format spec — member layout, manifest
fields, the `interface.*` tag channel, and two verified minimal
readers (in-process SDK and pure ZIP+JSON for any language) — lives in
`references/scadpkg-format.md`. Point your addon's agent at that page:
it is written so that an agent given the document alone can produce a
correct parser or exporter for the inputs your addon declares. Mirror
this pointer in your addon's SKILL.md (the page ships inside the
SimpleCADAPI skill; the normative JSON Schemas also ship inside the
`simplecadapi` wheel at `simplecadapi/contracts/` for environments
without the skill).
Consumer rules that hold regardless of path:
- resolve members through the manifest by `sha256`, never by guessing
names or extensions;
- treat missing `interface.*` names as loud failures naming the exact
name — never approximate by geometry;
- verify `schema_version` major before parsing anything else.
## Installing and managing addons
```bash
sca init # once per machine: home + registry + config
sca addon add owner/repo # install from GitHub (default branch)
sca addon add owner/repo@v1.2.0 # pin a tag or commit for reproducibility
sca addon add ./my-addon # install a local checkout (test before publishing)
sca addon update [name] # re-fetch one addon or all (payload swapped; runtime state survives)
sca addon check [name] # re-probe the runtime NOW and refresh the cached state
sca addon remove name
sca addon list # registry contents + on-disk drift + cached runtime state
```
- Locations resolve as flag > environment variable (`SCA_ADDON_HOME`,
`SCA_SKILLS_DIR`) > `~/.sca/config.toml` > defaults
(`~/.sca/addons`, `~/.agents/skills`).
- Skills install as `sca-<name>` inside the skills directory — copied,
never symlinked. A non-registry directory of that name is never
overwritten.
- GitHub sources fetch as tarballs (no git binary needed, byte-exact
files); `--method clone` is the escape hatch for private
repositories.
### Shell integration (`sca init`)
`sca` is the single CLI for the whole SDK (`sca addon …`, `sca cache …`,
`sca export …`), and `sca init` makes it resolve in any new shell —
interactive or scripted, on any of the supported platforms:
- a shim `~/.sca/bin/sca` (Windows: `sca.cmd`) execs the real console
script of the install that ran `sca init`; the venv's own `bin` is
never put on PATH;
- that directory lands on PATH via a marked, removable
`# >>> sca shell integration >>>` block: `~/.zshenv` for zsh (read by
non-interactive shells too, so agents see the command), `~/.bashrc`
for bash, `~/.config/fish/conf.d/sca-path.fish` for fish; on Windows
the user-scope `PATH` registry value is updated and refreshed.
- rc files are only created for the login shell or when they already
exist — no dotfiles are planted for shells that are not in use;
`--no-shell` skips the step; re-running `sca init` refreshes the shim
after the install moves. Removing the block(s) and `~/.sca/bin`
uninstalls the wiring.
### Hard failures vs warnings
| Outcome | Behavior |
| --- | --- |
| Descriptor invalid, `[compat] sca` mismatch, platform unsupported, name collision, foreign skill directory | install aborts, naming the exact cause |
| `check_cmd` fails, update downgrades | loud warning; install/update proceeds |
| Registry vs disk drift (missing directories) | surfaced by `sca addon list` as `DRIFT` lines |
## Publishing checklist
1. `sca addon add ./repo` from a local checkout; confirm the summary
and that the skill lands under `sca-<name>`.
2. `sca addon list` shows no drift; the runtime probe passes on every
declared platform you can test.
3. Tag the release; users pin with `owner/repo@<tag>`.
4. Bump `[addon] version` for every published change; widen
`[compat] sca` only after testing against the new SDK release.