Scripted plugin sdk

[mhbalthasar]

支持使用py/JS/lua作为extension的语言

[LiuYunPlayer]

Thanks for this PR. Let me start with the conclusion: we are not merging the host-side changes, but this is not a rejection of the approach — we want to open an official extension point for it, and we would like you to own the resulting ecosystem. Below is the reasoning and the design direction. We would like your view before we open an issue to pin down the details.

What we read

We went through the design document, the wire specification, the ~4,000 lines on the host side, and all three façades. Three-plane transport, epoch guarding against tail packets, the four lines of defense against orphaned processes, the shared-memory audio plane and the curve result ring, a fake sidecar acting as a protocol seal so CI needs no interpreter, 47 methods cross-checked across three languages — this is substantial work, not a prototype. The hazards you hit (the Windows FileShare mismatch, the create_session / process arrival race, the Lua anchor and reserved-word issues) are honestly recorded in the document as well.

Why it does not go into the host

The reason is boundaries, not implementation quality.

TuneLab wants to maintain exactly two things long-term: the SDK contract (what a plugin implements) and the loading contract (who instantiates a plugin). A scripting host is built on top of those. Merging it would commit us to mirroring every SDK change across three façades, tracking upstream releases in a runtime mirror table, chasing long-tail cross-platform issues in subprocess and shared-memory code, and owning the security and compliance surface of distributing third-party binaries. Those costs belong to whoever owns that ecosystem.

We also seriously considered the other shape — a normal plugin that hosts scripts internally. We rejected it: your scripted plugins would disappear from the extension management surface (sidebar, enable/disable, uninstall, settings buckets, routing, agent visibility). That price is too high for both plugin authors and users. Hence the proposal below.

Proposal: an official loader extension point

This shape already runs in the repository — the legacy compatibility layer is its first user. The main program has zero compile-time dependency on it, loads it reflectively at startup, and hands it the registration delegates. Crucially, the packages it handles remain first-class extension packages discovered by the host itself: they still pass the enable/disable and platform gates, still get bookkeeping, still appear in the sidebar, still participate in routing. The only thing the host delegates is "turn this entry into a live implementation."

We intend to generalize that hardcoded hook into a real capability:

• A loader is a first-class plugin type, alongside format / voice / instrument / effect, installed in the extensions folder, going through the same install, uninstall, enable, platform-gate, sidebar and settings-bucket pipeline. A loader is itself something users need to manage.
• The dependency is declared on the plugin side: an entry declares loader: "tunelab.scripted/1", and a loader package declares loads: "tunelab.scripted/1". That value is a capability identifier, not a package id — so two loaders of the same class are interchangeable and a plugin never has to change its manifest to switch implementations.
• Loading happens in two passes: the first reads every manifest, builds the dependency table, and loads loader packages; the second loads everything else, handing entries that declare a loader to that loader to construct and register; a final phase runs the whole-set bookkeeping and applies persisted settings.
• Registration is separate from initialization: the second pass only requires a loader to register (for you, constructing proxies — no process spawned). Its own heavy initialization stays lazy until first real use. This also sidesteps the "settings must arrive before Init" ordering problem you had to build a deferred-delivery mechanism for in M2a; at this layer it does not arise.
• Dependencies are accounted for: we know which packages depend on which loader, so we can block uninstalling a loader that is in use, and report an accurate reason on every dependent package when a loader fails to load.

The most important consequence for you: scripted plugins stay first-class extension packages. Own manifest, own id, own introduction, own settings bucket, same routing and conflict resolution — indistinguishable from a .NET plugin in the sidebar and to the agent. Nothing on the management surface is lost.

Most of your code moves as-is

We checked the coupling specifically. Across Remote*, ScriptedWire and ShmPlane, the only namespaces used are the SDK, Foundation, and one host-internal namespace — and that last one is genuinely used in exactly one place: host.segment_resize downcasts IAudioSegment to the host's concrete type to read back the sample rate and buffer. A loader can work around that by keeping its own shadow copy of what it wrote.

In other words the protocol layer, the process layer, the data planes and the façades can all live inside a loader unchanged. What needs rewriting is the loading and registration layer — a few hundred lines. The split point you chose inside the load pipeline (known type, after all gates, before the ALC path) is also the right one; that is exactly where a loader should take over.

As a side effect, the five runtime settings (interpreter paths, mirror source, auto-fetch toggle) become the loader's own settings panel and disappear from the host settings registry. That resolves both their current lack of a settings-window UI and the problem of the mirror table being compiled into the host, where every upstream release would otherwise require a host release.

SDK gaps we already know about

Please open an issue per item; we will review them under an additive-only policy:

1. No runtime registration channel for formats — import/export suffixes are declared in the manifest at load time. This does not block the loader model (each plugin package declares its own suffixes), but if you want a loader to add and remove formats dynamically, the surface needs to grow.
2. effect has no catalog concept equivalent to voice's — worth discussing if you want several scripted effects selectable under one loader.
3. IAudioSegment is write-only, with no read-back. That is the source of the one downcast above.

Interfaces are what the official side should provide; implementations are not.

Issues found during review

These survive the move, so they are worth passing on:

• SidecarRegistry keys hosts by package id only, while SidecarHost holds a single runtime and entry. If one package declares two scripted entries, the second entry's script is never spawned; the failure surfaces as a missing entry in the handshake provides check, which is misleading to the author.
• SidecarHost.CallInternal writes frames to stdin while holding the lock. If the sidecar stops draining stdin, pipe backpressure holds that lock indefinitely — and heartbeat death detection, death handling and shutdown all need the same lock.
• GetSettingsConfig is a synchronous blocking RPC on the default two-minute timeout. If the sidecar is not running, spawn and handshake happen on whatever thread opened the settings panel.
• The orphan sweep only kills leftovers whose executable lives under the extensions folder, so sidecars started from a system interpreter on PATH are never covered.
• The runtime feed has Windows cells only: on macOS and Linux the download button can only report that no runtime is available for the platform. Five of the seven cells have no pinned sha256 and are downloaded anyway with a single log warning. The HEAD race establishes reachability, not throughput, and when every candidate times out the fallback is the first table entry rather than the upstream source. Auto-fetch failures are entirely silent.
• Section 11 of the design document still states that the download chain is "fixed GitHub release plus pinned sha256", which contradicts the decision recorded in section 8.6 to fetch upstream artifacts from mirrors — and the security argument lives in section 11.

What we would like to hear from you

1. Does this direction work for you, and would you be willing to maintain this loader and its ecosystem long-term? The format definition, façade releases, runtime distribution policy and version cadence would all be yours to decide.
2. Is the set of registration delegates above sufficient? What else do you need the host to hand over?
3. Does "the plugin declares the loader class" work for how you expect plugins to be distributed?

To be explicit about limits: we will point to your repository from the plugin development documentation, but we will not endorse specific mirror sources and will not take on support for scripting runtimes. The loader contract will be marked experimental at first; we will commit to stability once a real loader has survived an SDK minor release without contract changes, or once a second independent implementation exists.

If the direction looks right, we will open an issue to settle the loader extension point in detail, and you would be welcome to shape the design there.

(Happy to switch back to Chinese for any of this if that is easier — just say the word.)