inkreach-agent/packages/plugin-template

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 别名到宿主单例（勿改）

构建渲染层组件

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