Add project metadata and docs

2026-06-26 13:26:40 +08:00
parent e43a25ce71
commit f59190251d
32 changed files with 5492 additions and 1 deletions
@@ -0,0 +1,63 @@
+# 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.