QWQLwToo
64 lines
2.4 KiB
Markdown
64 lines
2.4 KiB
Markdown
# 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.
|