feat: 插件声明式设置体系——registerSettings schema + 标准控件表单 + 一级导航入口开关

docs/plugins.md

@@ -120,6 +120,34 @@ export const { jsx, jsxs, Fragment } = J
 - 装载时机与热重载：插件列表变化（扫描/启停/`plugins:reload`）即按 `?t=` cache-bust 重装；被禁用/移除的插件注册随之清除
 - 门控：仅开发版装载（`import.meta.env.DEV` + 主进程 `EXTERNAL_PLUGINS_ENABLED`）；错误隔离到单插件（装载失败仅 console.error，渲染崩溃由 PluginErrorBoundary 兜底）
 
+## 插件设置（声明式 schema，`api.ui.registerSettings`）
+
+插件在 main.mjs 里声明配置表单，宿主负责渲染/持久化/回推——schema 是**纯数据**（不可含函数/React 元素）：
+
+```js
+// main.mjs
+api.ui.registerSettings({
+  title: '我的插件设置',
+  items: [
+    { type: 'string', key: 'token', label: 'API Token', password: true },
+    { type: 'boolean', key: 'enabled', label: '启用增强', default: true },
+    { type: 'select', key: 'mode', label: '模式', options: [{ value: 'fast', label: '快速' }], default: 'fast' },
+    { type: 'path', key: 'dir', label: '数据目录', mode: 'directory' },
+    { type: 'image', key: 'logo', label: 'Logo' },
+    { type: 'button', key: 'test', label: '测试连接', variant: 'primary' }
+  ]
+})
+
+api.ui.getSettingValues()            // 当前值（schema default 已合并）
+api.ui.onSettingsChange((v) => {})   // 用户修改设置后实时推送
+api.ui.onSettingsAction((key) => {}) // button 条目点击回调（key = 按钮项 key）
+```
+
+- **标准控件**（`PluginSettingItem`，按 `type` 判别）：`string`（含 password）/ `text` 多行 / `number` / `boolean`（switch）/ `select` / `multiSelect` / `slider` / `color` / `path`（file|directory）/ `image`（选择+缩略图）/ `button`（动作）/ `info` / `divider`
+- **持久化**：值存 `userData/aso-plugin-values.json`（按插件隔离）；`getSettingValues` 合并 schema 默认值
+- **一级入口**：有配置项（items 非空）的插件，在插件页行内出现「一级入口」开关；打开后设置页左侧「Agent 能力」组追加以插件名命名的导航项，点击进二级配置页。items 为空/未声明 → 无开关、无导航项
+- 值变更经 `plugins:settingsValues` 广播：设置页与插件主进程两侧同步
+
 ## UI 槽位总览（对位 pi 的 ctx.ui）
 
 | 槽位 | 机制 | 状态 |