inkreach-agent/docs/plugins/README.md

插件开发教程（渐进式）

面向「写插件的人（含 Agent）」。从零到高级共 8 篇，每篇 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 维护的插件
L6 公共组件库	@aso/plugin-sdk/ui：统一三态（等待/失败/空）与基础控件	与宿主零差异的 UI
L7 性能与检验	主线程不阻塞、超时重试、plugin:check 机器关卡	可发布、不卡宿主的插件

排障中？ 直接跳 常见错误速查——症状 → 原因 → 修复三段式速查表。

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）
• 重载是宿主级动作（重扫全部插件源 + 重建运行时）；改了哪个插件都点同一个「重载」