插件开发教程（渐进式）
面向「写插件的人（含 Agent）」。从零到高级共 6 篇，每篇 10-30 分钟，逐篇递进、可独立验证。 契约细节（类型/字段全集）见 ../plugins.md；UI 规范见 DESIGN.md。
学习路径
| 篇 | 内容 | 产出 |
|---|---|---|
| L0 第一个插件 | manifest + main.mjs，装载/启停/日志 | 侧栏可见、日志可查的最小插件 |
| L1 工具与命令 | 给 Agent 注册工具、斜杠命令、事件 | Agent 能力扩展 |
| L2 设置表单 | 声明式 schema、13 种标准控件、一级入口 | 用户可配置的插件 |
| L3 UI 槽位 | 状态胶囊/工具栏按钮/视图/面板 tab/iframe 页 | 界面存在感 |
| L4 React 组件 | entry.renderer：宿主内 React 组件 + JSX 构建配方 | 一等公民级 UI |
| L5 自诊断 | 日志规范、排障闭环、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）