用途:在本地 Paperclip 实例上创建、脚手架化或迭代 Paperclip 插件。默认做法是把插件作为独立包建在 Paperclip 仓库之外(如 ~/dev/paperclip-plugins/<name>),再以本地绝对路径安装进运行中的实例;只有用户明确要求内置示例时才改动核心仓库。
主要能力与用法:使用 paperclipai plugin init 脚手架,例如 paperclipai plugin init @acme/my-plugin --output ~/dev/paperclip-plugins。可选参数包括 --output、--template(default|connector|workspace|environment)、--category(connector|workspace|automation|ui|environment)、--display-name、--description、--author、--sdk-path。命令成功后按提示依次执行 cd、pnpm install、pnpm dev、paperclipai plugin install <abs-path>。若 paperclipai 不在 PATH,可回退到 pnpm --filter @paperclipai/create-paperclip-plugin build 与 node packages/plugins/create-paperclip-plugin/dist/index.js。
本地安装与重建:在插件目录运行 pnpm install、pnpm dev(esbuild --watch 重建 dist/manifest.js、dist/worker.js、dist/ui/)、paperclipai plugin install /absolute/path/to/my-plugin。install 会自动识别本地路径并传 isLocalPath: true,可用 --local 强制;路径会解析为绝对路径;服务器监听 dist/ 并在重建后重启 worker,无需每次重装。--version 仅适用于 npm 包安装,与本地路径同用会报错。安装后用 paperclipai plugin list 和 paperclipai plugin inspect <plugin-key> 检查。
脚手架后检查:src/manifest.ts、src/worker.ts、src/ui/index.tsx、tests/plugin.spec.ts、package.json 的 paperclipPlugin 块;确保只声明受支持能力、不使用 ctx.assets、不导入宿主 UI 组件桩、UI 自包含、routePath 仅用于 page 槽位。
验证:在插件目录运行 pnpm typecheck、pnpm test、pnpm build;若同时改了 SDK/宿主/运行时,还需运行相关 Paperclip 工作区检查。完成后报告脚手架绝对路径、执行的命令、安装状态(plugin key、版本、状态,非 ready 时附 lastError)、测试与构建结果、以及未热重载的限制。
限制:当前运行时假设插件 worker 与插件 UI 均为受信任代码,worker API 受能力门控,插件 UI 不受 manifest 能力沙箱限制,暂无宿主提供的共享插件 UI 组件套件,ctx.assets 在当前运行时不受支持。UI 热重载(pnpm dev:ui,端口 4177)可选且依赖模板,仅在模板配置了 devUiUrl 并验证可用时提及。参考文档:doc/plugins/PLUGIN_AUTHORING_GUIDE.md、packages/plugins/sdk/README.md、doc/plugins/PLUGIN_SPEC.md(仅前瞻性上下文)。