Plugin Specification For AI Implementers

This document is the compact contract for generating YMhut Box plugins with another AI agent.

Build A Minimal Local Package

Create exactly the files needed for a runnable local package:

ymhut.plugin.json
README.md
index.html
style.css
main.js

Keep UI code and core logic local. Do not load remote scripts as runtime dependencies. Remote HTTP APIs are allowed only through declared permissions and graceful failure states.

Manifest Rules

Use a stable id with letters, numbers, ., -, or _.
Do not prefix the id with plugin:.
Include at least one ToolboxTool or NavPage surface.
Include every local file in resources, including README.md.
Request only permissions the plugin actually uses.
Explain every requested permission in README.md.

Runtime Bridge

Use window.ymhut for host abilities:

output.* for reports and summaries.
storage.* for plugin-private state.
http.fetch for http/https requests.
network.* for host network diagnostics.
clipboard.* and file.* only when clearly user initiated.
openExternal(url) for links, which opens the YMhut safe browser by default.
openExternal(url, { target: "system" }) only for an explicit system-browser action.

UI And Window Boundaries

The plugin page owns only its WebView content area. Do not mimic system title bars, cover host controls, or create invisible click layers. Avoid full-screen fixed overlays; if a modal is necessary, provide a visible close control and restore focus.

Design for both embedded and independent-window use. Use responsive grids, readable card density, clear loading states, empty states, and error states. The host output area should not be used as the primary UI.

Security Constraints

Do not modify or override:

server/
built-in app assets
developer/about identity
built-in tool IDs
paths outside the plugin directory

All plugin resources must resolve inside the plugin folder. File access must go through host file pickers; never assume arbitrary filesystem access.

Acceptance Checklist

Plugin scans without validation errors.
README explains features, permissions, boundaries, and known failures.
Main UI runs without network and shows a useful degraded state.
Output writes do not hide the main UI.
Links open in the safe browser by default.
No remote scripts, no unbounded z-index overlays, no hidden click blockers.

2.4 KiB Raw Blame History