This commit is contained in:
QWQLwToo
@@ -0,0 +1,19 @@
|
||||
# Architecture
|
||||
|
||||
YMhut Box is split into a WinUI app and a reusable Core library.
|
||||
|
||||
## Layers
|
||||
|
||||
- `YMhut.Box.WinUI`: window shell, navigation, pages, App Installer update trigger and Windows integration.
|
||||
- `YMhut.Box.Core`: settings, log, HTTP/API, local data, system snapshots, tool catalog and tool execution.
|
||||
- `YMhut.Box.Tests`: MSTest coverage for migration-critical services and tool behavior.
|
||||
|
||||
## Services
|
||||
|
||||
The WinUI app builds a DI container in `AppServices.Configure()` and registers settings, logging, HTTP/API, update, data, system metrics, startup, window state and tool worker services.
|
||||
|
||||
Tool pages call `IToolWorkerService` and `ToolExecutor`; API-backed tools go through `IApiManager`, which owns endpoint resolution, timeout behavior, logging and cache boundaries.
|
||||
|
||||
## Tool Contract
|
||||
|
||||
Every tool is registered as an `IToolModule` with stable metadata. `ToolCatalog` is a static C# registry and no longer reads a runtime tool registry from another project.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Contributing
|
||||
|
||||
## Add A Tool
|
||||
|
||||
1. Add metadata to `ToolCatalog`.
|
||||
2. Add core execution logic to `ToolExecutor` or a dedicated service.
|
||||
3. Add tests in `YMhut.Box.Tests`.
|
||||
4. Verify the tool appears in `ToolboxPage`, opens in `ToolDetailPage`, and writes recent-tool history.
|
||||
|
||||
Use `IApiManager` for remote tools and keep parsing logic unit-testable.
|
||||
@@ -0,0 +1,7 @@
|
||||
# Migration Notes
|
||||
|
||||
YMhut Box 2.x migrates user settings into `%LOCALAPPDATA%\YMhut Box\WinUI\settings.json` on first launch.
|
||||
|
||||
The current release line runs as a native WinUI 3 app. Tool metadata, navigation, recent-tool records, settings, logs and update checks are handled by C#/.NET services.
|
||||
|
||||
Older app data is imported as a compatibility step and is not required for new installs.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,90 @@
|
||||
# YMhut Box 插件开发说明
|
||||
|
||||
YMhut Box 插件是本地 WebView 插件包，用来扩展工具箱工具或插件页。插件运行在宿主隔离的 WebView 中，通过 `window.ymhut` Bridge 请求能力；插件不能直接访问应用核心资源、任意文件路径或系统浏览器。
|
||||
|
||||
## 最小插件包
|
||||
|
||||
```text
|
||||
my-plugin/
|
||||
ymhut.plugin.json
|
||||
README.md
|
||||
index.html
|
||||
style.css
|
||||
main.js
|
||||
```
|
||||
|
||||
`README.md`、`README.txt` 或 `说明.md` 必须存在。`entry`、`resources` 和 surface 入口都必须留在插件目录内，不能使用 `../` 逃逸。
|
||||
|
||||
## manifest 核心字段
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "hello-tools",
|
||||
"name": "Hello Tools",
|
||||
"version": "1.0.0",
|
||||
"author": "you",
|
||||
"description": "A local YMhut Box plugin",
|
||||
"entry": "index.html",
|
||||
"permissions": ["Output", "Log", "Storage", "OpenExternal"],
|
||||
"surfaces": [
|
||||
{
|
||||
"kind": "ToolboxTool",
|
||||
"id": "hello",
|
||||
"name": "Hello",
|
||||
"description": "Toolbox entry",
|
||||
"entry": "index.html",
|
||||
"category": "plugin"
|
||||
}
|
||||
],
|
||||
"resources": ["index.html", "style.css", "main.js", "README.md"]
|
||||
}
|
||||
```
|
||||
|
||||
`id` 只允许字母、数字、点、短横线和下划线，不能以 `plugin:` 开头。工具箱挂载后的工具 ID 由宿主生成，格式是 `plugin:<pluginId>:<surfaceId>`。
|
||||
|
||||
## 权限
|
||||
|
||||
权限默认关闭。manifest 只声明插件需要什么，用户仍要在插件页启用插件并授予权限。
|
||||
|
||||
- `Input`：读取或写入插件输入。
|
||||
- `Output`：写入宿主输出区。
|
||||
- `Log`：写入 `plugin:<pluginId>` 日志。
|
||||
- `Storage`：访问插件私有 key-value 状态。
|
||||
- `Http`：通过宿主请求 http/https。
|
||||
- `Clipboard`：读写剪贴板文本。
|
||||
- `FilePicker`：通过系统选择器打开或保存文件。
|
||||
- `RunTool`：调用允许的内置工具。
|
||||
- `OpenExternal`：打开 http/https 外链，默认进入安全浏览器。
|
||||
- `NetworkDiagnostics`：请求本机网络诊断能力。
|
||||
|
||||
## Bridge
|
||||
|
||||
```js
|
||||
await window.ymhut.output.set("report");
|
||||
await window.ymhut.storage.set("lastRun", JSON.stringify(data));
|
||||
await window.ymhut.http.fetch({ url: "https://example.com/api" });
|
||||
await window.ymhut.openExternal("https://example.com");
|
||||
await window.ymhut.openExternal("https://example.com", { target: "system" });
|
||||
```
|
||||
|
||||
普通外链默认进入 YMhut Box 安全浏览器。系统浏览器只作为显式动作使用，并继续受 `OpenExternal` 权限控制。
|
||||
|
||||
## 窗口与输出
|
||||
|
||||
插件内容区承载主 UI；宿主输出区用于报告、日志摘要、复制结果和调试信息。不要用输出区做主交互，也不要在插件页面使用全屏 fixed 遮罩、透明点击层或超高 z-index 覆盖宿主控件。
|
||||
|
||||
插件需要适配主窗口内嵌和独立窗口内容区。建议使用响应式网格、可滚动表格和清晰空态；不要假设窗口固定尺寸。
|
||||
|
||||
## 安全边界
|
||||
|
||||
插件 WebView 只允许加载插件目录内本地资源。非本地导航会被拦截并交给安全浏览器。插件不能覆盖内置工具 ID、应用图标、开发者信息、关于页核心身份或内置 `Assets` 路径。
|
||||
|
||||
网络结果、排行榜和第三方数据都应标明不确定性，并在失败时显示降级状态。
|
||||
|
||||
## 常见问题
|
||||
|
||||
- 加载失败：检查 manifest、README、entry 和 resources 是否存在且路径合法。
|
||||
- 权限拒绝：检查 manifest 是否声明权限，以及插件页是否已授权。
|
||||
- 外链打不开：只支持绝对 http/https URL，默认安全浏览器。
|
||||
- 输出区遮挡：将输出区用于报告，不要用它承载主 UI。
|
||||
- 独立窗口异常：不要调用浏览器弹窗 API 创建系统浏览器窗口。
|
||||
@@ -0,0 +1,10 @@
|
||||
# Release Process
|
||||
|
||||
1. Update `version.json`.
|
||||
2. Run `dotnet restore YMhut.Box.Native.sln --configfile NuGet.Config --ignore-failed-sources`.
|
||||
3. Run `dotnet test src\YMhut.Box.Tests\YMhut.Box.Tests.csproj -c Release --no-restore`.
|
||||
4. Run `build.bat --target=both`.
|
||||
5. Verify `installer_output/*.msix`, `installer_output/*.appinstaller`, and the Inno Setup EXE.
|
||||
6. Install, launch, upgrade and uninstall both MSIX and EXE packages.
|
||||
|
||||
The default signing path uses a self-signed certificate for sideload validation. Replace the certificate before public distribution if a commercial signing certificate is available.
|
||||
Reference in New Issue
Block a user