Plugin Guide (your first plugin in 1 hour)
Read the frozen contract first: PLUGIN-CONTRACT.md (v1: one-year compatibility, additive-only, breaking changes require apiVersion: 2).
Four tiers — pick by risk
| Tier | Can do | Typical | You write |
|---|---|---|---|
| L0 declarative | Themes / skins / skills / prompts / commands / language packs | New palette, codified workflow, translations | Pure JSON / Markdown, no code |
| U UI component | UI blocks in 8 whitelist slots (iframe sandbox) | Custom panels, card views, avatar drivers | ui.html + manifest |
| L2 MCP | Out-of-process capabilities | Office conversion, external services | MCP server + recipe |
| L1 in-process | New tools / providers / hooks (jiti runs TS directly, same process as kernel) | A custom intranet-ticket tool | TS entry + explicit permissions |
Bias: if L0 works, don't write code; if MCP (L2) works, don't go in-process (L1). The preferred way for Lynn to "learn something new" is a skill (L0), not plugin code.
Manifest skeleton
One directory per plugin: ~/.lynn/plugins/<id>/plugin.json.
{
"id": "lynn.<author>.<name>",
"name": "Display name",
"version": "1.0.0",
"apiVersion": 1,
"tier": "L0",
"engines": { "kernel": ">=0.0.1" },
"source": "local",
"contributes": { }
}
idis reverse-domain (2–4 lowercase segments);apiVersionmust be1;engines.kernelrequired (version gate).- Self-authored / workshop products must set
source: "self-authored"+generatedBy(traceability).
Example 1: L0 theme (~20 min)
Full example: examples/plugins/lynn.theme.dusk/.
lynn.theme.dusk/
├── plugin.json # contributes.theme = "theme.json"
└── theme.json # name + dark/light token overrides (whitelist keys)
Drop into ~/.lynn/plugins/ → restart → Settings → Appearance. L0 takes effect immediately, zero code execution.
Example 2: L0 language pack (~15 min)
A language pack is just an L0 plugin: contributes.langs: ["en.json"], file shape { "lang": "en", "strings": { "nav.model": "Model", ... } }. Packs matching the active language override built-ins; missing keys fall back to Chinese. See the Plugin Index.
Example 3: L1 in-process tool (~30 min)
Full example: examples/plugins/lynn.tool.dice/.
// index.ts — default-export factory; jiti runs TS directly, no build step
export function activate(api: { registerTool: (t: unknown) => void; dataDir: string; log: (m: string) => void }) {
api.registerTool({
name: "roll", // runtime full name: lynn.<id>.roll
description: "Roll a six-sided die",
parameters: { type: "object", properties: {} },
execute: async () => "🎲 " + (1 + Math.floor(Math.random() * 6)),
});
}
Manifest: "tier": "L1", "entry": "index.ts", "permissions": { "fs": [] }. Notes:
- L1 must declare permissions explicitly (fs/net/proc/secrets, at least one);
proc: trueis rejected outright — use L2 for subprocesses. - Third-party L1 is disabled by default; the user enables it per plugin.
- Forbidden-pattern scan:
eval/new Function/child_process/ obfuscation — any hit rejects.
Example 4: U UI component (~20 min)
Example: examples/ui-plugins/lynn.demo.hello/ — ui.html + manifest contributes.slots (8 whitelist slots: stage.view / card.renderer / status.bar / composer.action / …). U plugins run in an iframe sandbox: no network, no Node, zero-border constraint enforced in CI.
Admission pipeline (run before install)
The plugin panel's "probe" runs the plugin once in isolation:
L0 = parse checks; L2 = real MCP initialize handshake; L1 = real activation then de-register.
Safety net: plugin-set fingerprint (crash attribution), safe mode (repeated crashes → official core only), one-click rollback (enabled-state snapshots).
Publishing
- Index: Plugin Index. Community submission gating waits for the signing trust chain — stated as-is, not a technical blocker.
- Self-authored plugins stay private by default; publishing = handing over the source, confirmed by the user.
Next: Plugin Index · Privacy · Release & Signing