52 lines
2.3 KiB
Markdown
52 lines
2.3 KiB
Markdown
# plugin-template · 插件脚手架
|
||
|
||
复制本目录到插件位置（改目录名 = 改前先改 manifest.id），改掉 `id`/`name`/`description` 即完成最小定制。
|
||
|
||
## 目录
|
||
|
||
```
|
||
manifest.json 清单（id/name/version/minContract 必改）
|
||
main.mjs 主进程侧：Agent 能力 + 设置声明 + 日志埋点（范例齐备）
|
||
src/renderer.tsx 宿主内 React 组件源码（JSX；公共组件库 + 三态示范）
|
||
renderer.mjs 预构建产物（开箱即用；改了源码需重新构建）
|
||
shims/ 构建期把 react 别名到宿主单例（勿改）
|
||
```
|
||
|
||
## 构建渲染层组件
|
||
|
||
```sh
|
||
esbuild src/renderer.tsx --bundle --format=esm --outfile=renderer.mjs \
|
||
--jsx=automatic \
|
||
--alias:react=./shims/react.js --alias:react/jsx-runtime=./shims/jsx-runtime.js \
|
||
--alias:@aso/plugin-sdk=../../packages/plugin-sdk/src/index.ts \
|
||
--alias:@aso/plugin-sdk/ui=../../packages/plugin-sdk/src/ui.tsx
|
||
```
|
||
|
||
（esbuild 可用 `pnpm dlx esbuild@<版本>` 或任意 ≥0.17 版本；`--alias` 需 ≥0.17。
|
||
两条 sdk alias 指向仓库内源码——本目录复制到别处后，改成 sdk 源码的实际路径即可。）
|
||
不需要 UI 时：删除 `entry.renderer` 与 `src/`、`shims/`、`renderer.mjs`，只保留 main.mjs。
|
||
|
||
## 放置位置（三选一，按优先级）
|
||
|
||
1. `userData/plugins/<id>/`（应用托管目录）
|
||
2. `<工作区>/.pi/extensions/<id>/`（项目级）
|
||
3. `~/.pi/agent/extensions/<id>/`（全局）
|
||
|
||
第三方装载仅开发版开启（`ASO_EXTERNAL_PLUGINS=1` 豁免）。
|
||
|
||
## 验证
|
||
|
||
1. `pnpm plugin:check <本目录>` → 0 error（性能与样式机器关卡，见 L7）
|
||
2. 重启或开关重载 → 设置 → 插件 → 对应作用域出现插件
|
||
3. 日志 `userData/logs/main-*.log` 有 `plugin activated pluginId=my-plugin`
|
||
4. 对 Agent 说"ping 一下我的插件" → 触发 `my_plugin_ping`
|
||
5. 面板/侧栏出现 React 组件：等待/数据/开关/重载齐全（三态示范，hooks 生效）
|
||
|
||
## 下一步
|
||
|
||
- 教程索引：`docs/plugins/README.md`（L0→L7）
|
||
- 公共组件库与三态铁律：`docs/plugins/07-ui-components.md`（renderer.tsx 即示范）
|
||
- 性能与检验器：`docs/plugins/08-performance.md`
|
||
- 视觉规范：`docs/plugins/DESIGN.md`（提发布前过一遍自检清单）
|
||
- 契约全集：`docs/plugins.md`
|