docs: 渐进式插件教程（L0→L5）+ DESIGN.md 视觉规范 + plugin-template 脚手架

docs/plugins/README.md

@@ -0,0 +1,34 @@
+# 插件开发教程（渐进式）
+
+> 面向「写插件的人（含 Agent）」。从零到高级共 6 篇，每篇 10-30 分钟，逐篇递进、可独立验证。
+> 契约细节（类型/字段全集）见 [../plugins.md](../plugins.md)；UI 规范见 [DESIGN.md](./DESIGN.md)。
+
+## 学习路径
+
+| 篇 | 内容 | 产出 |
+|---|---|---|
+| [L0 第一个插件](./01-hello-plugin.md) | manifest + main.mjs，装载/启停/日志 | 侧栏可见、日志可查的最小插件 |
+| [L1 工具与命令](./02-tools-and-commands.md) | 给 Agent 注册工具、斜杠命令、事件 | Agent 能力扩展 |
+| [L2 设置表单](./03-settings.md) | 声明式 schema、13 种标准控件、一级入口 | 用户可配置的插件 |
+| [L3 UI 槽位](./04-ui-slots.md) | 状态胶囊/工具栏按钮/视图/面板 tab/iframe 页 | 界面存在感 |
+| [L4 React 组件](./05-renderer-components.md) | entry.renderer：宿主内 React 组件 + JSX 构建配方 | 一等公民级 UI |
+| [L5 自诊断](./06-self-diagnosis.md) | 日志规范、排障闭环、Agent 自迭代约定 | 可被 Agent 维护的插件 |
+
+## 30 秒总览
+
+```
+<插件目录>/                     三个可选位置（按优先级）：
+  manifest.json                  1. userData/plugins/<id>/     （应用托管）
+  main.mjs        （可选）        2. <工作区>/.pi/extensions/<id>/ （项目级）
+  renderer.mjs    （可选）        3. ~/.pi/agent/extensions/<id>/  （全局）
+  index.html      （可选）
+```
+
+- **main.mjs**：Agent 能力（工具/命令/事件）+ 声明设置表单 + 内联 UI 数据
+- **renderer.mjs**：宿主内 React 组件（需构建，见 L4）
+- **index.html**：iframe 插件页（物理隔离，桥接见 L3）
+
+## 环境要求
+
+- 第三方插件装载默认**仅开发版开启**（打包版关闭，`ASO_EXTERNAL_PLUGINS=1` 可豁免）
+- 日志文件：`userData/logs/main-YYYY-MM-DD.log`（排查问题的第一入口，见 L5）