Writing A Succinix Plugin

简体中文

What It Is

This guide is for Cordis plugin authors. Your plugin can use Succinix file, terminal, and session-persistence services without building another browser terminal.

How To Start

Declare only the services you actually need:

export const inject = ['fs', 'sandbox', 'terminals', 'sessionPersistence']

For an optional service, use ctx.get('fs', false). If Succinix is absent, disable that feature or handle the absence explicitly.

Choose The Right Service

Need	Do this	Do not do this
Work with project files	Use ctx.fs targets, versions, and read/write methods	Assume the browser has a second filesystem
Constrain a Lifo command	Use ctx.sandbox.confine(argv, policy)	Treat it as Node subprocess isolation
Build an interactive tool	Use ctx.terminals with a registered Agent	Maintain browser-only shell, editor, or TUI state
Keep plugin session data	Append events with ctx.sessionPersistence	Store recoverable state only in temporary browser memory
Start services or inspect ports	Let the host use ctx.get('succinix', false)	Treat a port as a public inbound service

WebContainer is Succinix's execution world. Extend commands, files, processes, services, and interactive applications there; browser code only renders, forwards input, and exposes unavoidable Web APIs.

Minimal Example

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-succinix-plugin'
export const inject = ['fs']

export async function apply(ctx: Context) {
  const file = await ctx.fs.resolve('/workspace/hello.txt')
  await ctx.fs.writeText(file, 'hello')
}

The exported @succinix/engine types define parameters, errors, and terminal ownership. File writes must use versions and sandbox policies as required; terminal operations require a registered Agent.

Verify It

The Cordis app example consumes only the packed engine, not repository source. After changing a public service, lifecycle, asset, or type, run:

npm run build:engine-package
node scripts/cordis-app-e2e.mjs

For embedding steps see Integration; for old code see Migration; for transport detail see Protocol.