Skip to content

plugins.en.md

Latest commit

 

History

History
127 lines (116 loc) · 7.98 KB

plugins.en.md

File metadata and controls

127 lines (116 loc) · 7.98 KB
Raw

Plugin Development Guide (authoritative text: the TUI Profile)

Documentation index · 简体中文

This document has been merged with the in-repo TUI Profile (tui-profile/): Plugin Admission and Development Guide

The ecosystem entry points and seam stability reference below are kept here for quick reference; the authoritative status and compatibility agreement live in the admission & development guide.

Ecosystem entry points

  • Interface & compatibility agreement / Plugin development guide: Terminal Interactive Ecosystem Plugin Admission and Development Guide (admission spec, seams, contracts, verification checklist).
  • Organization: dsh-tui-ecosystem (home of community plugins and templates).
  • Template repository: plugin-template (start from the template and ship a plugin in minutes).
  • Reference implementation: dsh-working-activity (live working-status line with dual outlets: TUI prompt slot + workingActivity session projection).

Seam stability reference

A maturity grading to help plugin authors gauge investment; the authoritative status and compatibility agreement live in the admission & development guide. The "stable candidate" tier is part of the frozen public surface as of the first published apiVersion (tui.dsh/v1alpha1) — the four commitments are in tui-profile/CHANGELOG.md's freeze entry; the other two tiers stay a maturity reference, not a promise:

Tier Seams
Stable candidate (shape frozen; breaking changes go through a minor-version deprecation warning before removal) VI settings sections · VIII full-screen scenes · X managed dialogs · XI status line · XII keyboard shortcuts · XIII entry renderers
Experimental (may still shift with dsh-std / the TUI Profile) IX decision events · toast notifications (ctx.tuiToast, new) · Side panels (ctx.tuiPanels, full panel + compact row, experimental)
Upstream-tracked (stability owned by the cordis / dsh mechanisms underneath) I session events · II official prompt slots · III bundled skills · IV themes · V system-prompt sections · VII profile composition

Also an experimental public surface:

  • @deepseek-harness-tui/dsh-tui/api (types-only entry).

  • Side panels (experimental, §18): ctx.tuiPanels.register({ apiVersion: 1, id, title, icon?, component | compact }) registers a right-sidebar panel (the host prefixes <pluginId>:; ≤4 panels per plugin, ≤32 globally; open() is rate-limited to once per 5s; 3 consecutive crashes disable the panel for the session). Of the two render slots — the full panel (component) and the compact row (compact, 1–3 lines) — compact is descriptor-validated only this phase and not mounted yet; sendToChat requires the panels.chat.attach grant (a later version) and currently always returns false with a one-time hint. Types live at @deepseek-harness-tui/dsh-tui/panels and ./api.

  • The @deepseek-harness-tui/dsh-tui/test-utils subpath and ctx.tuiPluginHost.grants.corrupt were removed in the adapter layering refactor (#705).

  • The backend contribution family (tui.dsh/v1alpha1 Backend, seam XIV) has its public surface frozen with the first published apiVersion: the type surface (BackendSpec, validateBackendSpec, backendAdmission) and conformance (TUI-BACKEND-001) are usable, and the admission chain (manifest → registry → descriptor) is wired; what is still missing is the step that reads a mounted bundle's declaration into the registry and the kernel picker, so "install a third-party backend, restart, see it in the picker" does not hold end to end yet.

  • Installing a package is available in the terminal itself (C-4): /plugin install <spec> goes through the host's ctx.pluginManager — a pre-install notice, a trust confirmation decided by provenance of the package (the judge is the packaged tui-profile/feed/first-party.json, decided offline; anything it cannot vouch for falls back to the confirmation), and esc to close the pane. During an install, it attempts cancellation and waits for profile writes to settle: the service rolls the profile back on cancellation, or finishes the install if applying has already made cancellation too late. Blocked build scripts can be approved in the pane, and an incompatible version can receive an exact-version exemption. Cancelling during exemption registration waits for the current write and stops subsequent grants and the retry; exemptions already written remain. Known gaps: provenance is only a one-vote-to-veto seam with no online check at all (the host service exposes no such API), and with no service the transcript reports the CLI command and the reason instead of running dsh plugin on the user's behalf (no pane opens: there is no flow to drive).

  • grants is now the narrower HostGrantFacade; see that PR for migration details.

  • On TuiSceneProps.channel (ChannelUi), minimal / setMinimal() were renamed to minimalUi / setMinimalUi(); the old names stay as deprecated aliases reading and writing the same Minimal UI switch, so existing full-screen scene plugins keep working. That switch only trims interface decoration and is unrelated to the kernel minimal agent preset (极简模式). Removal condition (decidable): v0.13 — the rename and deprecated aliases first ship in v0.12.0, leaving one released minor-version deprecation window. At that cut, scan the scene-plugin consumption surface (this repo's src/** re-exports and every plugin on the dsh-tui-ecosystem org that reaches the port through TuiSceneProps.channel) for .minimal / .setMinimal(: zero callers means both aliases and the 'setMinimal': 'mutate' row in ui-policy.ts are deleted in v0.13; any remaining caller is migrated within that same release rather than postponing the removal again.

  • The DSH kernel in the package's own entry (the default since the standalone host, configuration): the screen mounts before the profile composes, so plugin rows activate after the first frame and every ctx.tui* registration reaches an already-mounted screen (themes, panels, status views and the rest join live). A runtime theme the user had chosen is applied once its plugin registers it; until then the first frames use the auto-detected palette. The root-capability guard is the same as under dsh --profile: a row activating after the first TUI row cannot use ctx.root capabilities (root.plugin, root.effect, root.on, …) in its apply. A plugin that waits for something in its apply holds the composition: start long work detached, not awaited. On a scene's TuiSceneProps.channel, ready is false (and status 'starting') while no session stands behind the channel, e.g. after the startup session failed to open (startupFailure).

  • Claude and Codex kernels (light profile; accepted on Claude, not yet on Codex, which takes the same composition path): the entry composes this package's rows and the third-party bundles the profile declares, without @deepseek-ai/dsh-base, after the first frame, on the same terms as above. A row whose inject names a service only DSH's core provides (agents, llm, tools, sessionPersistence, …) stays pending on these kernels; the tui* services are all there.

  • The core repository remains independent; community plugins live in their own repos.

  • The organization only maintains the listing and admission rules — it does not endorse or warrant the functionality, quality, or safety of community plugins.

  • Plugin authors keep full ownership of their repositories and are responsible for their maintenance and security.