Codeex 插件工坊 · Codeex Plugin Studio
Deliver one self-contained Codeex runtime plugin whose source, permissions, hooks, desired install state, active runtime state, and rollback path are all auditable. Keep every plugin independently installable and uninstallable; never patch another plugin to make the new one work.
Triggers
Activate when
- 用户说“开发一个 Codeex 插件”“把这个能力做成 Codeex plugin”或“原子安装/卸载这个插件”。
- 用户要新增或修改
plugins/<plugin-id>/plugin.json、transformWebview、beforeLaunch、handleControlRequest或 Codeex 插件权限。 - The user asks to “create a Codeex plugin”, “add a Codeex runtime hook”, or “make this Codeex feature independently installable”.
Do not activate when
- 用户要创建 Codex marketplace 的
.codex-plugin/plugin.json、Skill、MCP 或 App;使用 Codexplugin-creator,不要套用 Codeex 运行时契约。 - 用户只要把 Lovinsp 接入普通前端项目;使用
lov-integrate-lovinsp。 - 用户只要修复 Electron/Tauri 的通用 relaunch 行为,而没有 Codeex 插件交付物;使用
lov-electron-app-relaunch。 - 用户只要求启用或停用一个已经存在的插件,且不涉及开发或验证;直接使用 Codeex 插件中心或项目 CLI。
Runtime Context and Profile
Read skill.yaml and resolve the Codeex repository in this order:
- The current request or an explicit
--project-root. - Current project context when it satisfies the Codeex contract.
CODEEX_PROJECT_ROOT.workspace.codeex_rootorskills.lov-codeex-creator.records.codeex_rootfrom the shared Profile.- The current directory when it passes the contract check.
Do not save an inferred path. If the user explicitly says a Codeex root should
be reused in future sessions, persist it with scripts/profile_store.py record --skill-id lov-codeex-creator --path records.codeex_root --value <json-string> --confirm and report the canonical Profile path without echoing private data.
Read references/skill-composition.md before invoking adjacent capabilities.
External Skills are optional artifact handoffs, never runtime dependencies.
Proceed without a question when the repository, plugin boundary, and safe verification path are discoverable. Use AskUserQuestion at most once when a material choice cannot be recovered locally, especially authorization to restart the active Codeex instance or a destructive source-removal request.
Codeex Plugin Contract
Before editing, read these references completely:
references/plugin-contract.mdfor manifests, hooks, and authoritative Codeex files.references/atomic-lifecycle.mdfor source, desired-state, runtime, and rollback semantics.references/verification.mdfor the risk-based evidence matrix.references/development-loop.mdfor native UI reuse, reload boundaries, and packaged-runtime readback.
Re-audit the target repository when its contract files differ from the reference. Current source code is authoritative; this Skill must not freeze a stale private API.
Workflow (MANDATORY)
Step 1: Define the plugin boundary
Record:
- one plugin ID in lower-case kebab-case;
- the user-visible outcome and one independently removable capability;
- whether it needs
transformWebview,beforeLaunch,handleControlRequest, or a combination; - every permission and why it is necessary;
- whether activation requires a renderer rebuild, a managed runtime restart, a launcher/control-service reload, or a combination;
- a rollback that leaves the currently running Codeex usable.
Reject a design that reaches into another plugin directory, mutates shared state outside declared hooks, or requires deleting user data during uninstall.
Step 2: Inspect the live contract
Verify the repository contains:
plugins/catalog.mjs
plugins/state.mjs
scripts/plugins-cli.mjs
scripts/build-webview.mjs
scripts/start.mjs
scripts/control-server.mjs
scripts/launcher-server.mjs
scripts/verify.mjs
Inspect the current hook call sites and context objects. Search existing plugins for the closest contract example, but do not copy feature-specific permissions, ports, paths, or lifecycle behavior.
Step 3: Scaffold or update the source
For a new plugin, use the staged creator:
python3 "$SKILL_DIR/scripts/codeex_plugin.py" scaffold <plugin-id> \
--project-root "$CODEEX_ROOT" \
--name "<display name>" \
--description "<concrete user-visible outcome>" \
--hook webview \
--control-route
Infer --hook webview, before-launch, or both from the requested behavior.
Use --hook control for a control-only plugin, or add --control-route when a
webview or launch plugin also owns authenticated local API routes.
Use repeated --permission "Label:Detail" only for capabilities the plugin
actually exercises. The scaffold is created beside the final target and
renamed into place only after validation; an occupied target is rejected.
For an existing plugin, edit only its own directory plus focused shared tests or contract code that is genuinely required. Never overwrite its directory with the scaffold command.
Step 4: Implement through declared hooks
transformWebview(context)may change only the staged renderer tree passed by Codeex. It must return small diagnostics and must not edit the prepared upstream source or a running app bundle directly.beforeLaunch(context)may return anenvoverlay. Preserve the input environment, keep secrets out of logs, and make external process ownership explicit.handleControlRequest(context)receives an already authenticated local request, URL, Codex home, and official CLI path. Returnnullfor routes the plugin does not own; bound request bodies and return{ status, body }for handled routes.- Validate entry paths remain inside the plugin directory.
- Put user-facing permissions in
plugin.json; absence from the UI is not permission minimization. - Keep install/uninstall free of source deletion. Source removal is a separate, explicit destructive maintenance action.
- For official composer or sidebar UI, inspect the adjacent native DOM first. Reuse the real trigger classes, icons, elevated surface, and spacing when available; do not approximate an existing icon by eye. Mount idempotently, remove owned nodes on dispose, and anchor to stable semantic attributes.
Step 5: Select the reload boundary
Classify every changed file before live verification:
- renderer transform or injected runtime: staged webview rebuild plus runtime restart, or an isolated smoke instance;
beforeLaunch: a new managed runtime process;handleControlRequestor a transitive module it imports: launcher/control service reload before API readback; restarting only Electron is insufficient;- launcher or host contract code: full wrapper/service reload followed by the relevant runtime verification.
Use references/development-loop.md for the exact loop. Resolve the current
owner PID and port before stopping anything; an EADDRINUSE error is evidence
of an existing service, not permission to launch duplicates.
Step 6: Validate before changing desired state
python3 "$SKILL_DIR/scripts/codeex_plugin.py" validate <plugin-id> \
--project-root "$CODEEX_ROOT"
pnpm check
Add focused tests for plugin logic. A webview transform needs a staged-bundle assertion; a launch hook needs environment/process tests. Do not treat manifest strings or a successful TypeScript parse as runtime proof.
Before handoff, prove the plugin is discoverable in the Codeex management UI. Its card must render from the authoritative catalog with the correct desired and active states, and the UI install/uninstall actions must round-trip through the authenticated control API. A working CLI alone is not a manageable plugin.
Step 7: Install or uninstall atomically
Use the wrapper, which delegates desired-state mutation to Codeex instead of hand-editing JSON:
python3 "$SKILL_DIR/scripts/codeex_plugin.py" install <plugin-id> \
--project-root "$CODEEX_ROOT"
python3 "$SKILL_DIR/scripts/codeex_plugin.py" uninstall <plugin-id> \
--project-root "$CODEEX_ROOT"
The state transition is idempotent and file-atomic, but it is only the desired
state. Report restart required until the rebuilt runtime confirms the same
active plugin set. Do not restart the user's active Codeex instance unless the
request authorizes it; prefer pnpm smoke for isolated verification.
If activation fails, keep the old running runtime, reverse the desired-state transition, and verify the state file again. Do not delete the plugin source as rollback.
Step 8: Verify the full lifecycle
For deterministic contract evidence:
python3 "$SKILL_DIR/scripts/codeex_plugin.py" exercise <plugin-id> \
--project-root "$CODEEX_ROOT"
Then verify in proportion to risk:
- Desired installed/uninstalled state is correct.
- Rebuild is staged and the existing runtime remains usable on failure.
- An authorized restart or isolated smoke reports the expected active set.
- The plugin's visible behavior appears when installed and disappears when uninstalled without damaging official tabs, tasks, Skills, or MCP.
- The Codeex management page lists the plugin and its install/uninstall action updates desired state, restart disclosure, and the card state correctly.
- Existing plugins still pass their focused checks.
- A native UI integration matches the adjacent control's icon geometry, computed color, placement, and one-mount invariant in the packaged runtime.
- A control-route plugin was read back only after its launcher service loaded the changed handler and transitive modules.
Step 9: Hand off
Report the plugin source, hooks, declared permissions, tests, desired state,
active state, runtime-restart state, launcher/control reload state, rollback
result, and any evidence not yet collected. Use installed, active, and
verified as separate states.
Dependencies
- Python 3.8+ standard library for the portable lifecycle CLI.
- Node.js 24+ and the target Codeex repository for authoritative plugin loading.
- PyYAML 6+ only for
scripts/validate_skill.py. - No credentials, remote service, marketplace, or sibling Skill is required.
Validation
Validate this Skill itself with:
python3 scripts/validate_skill.py .
