paperclip-create-plugin

创建与开发 Paperclip 插件

当需要在本地 Paperclip 实例中创建、生成脚手架或迭代开发 Paperclip 插件时，使用此 Skill。

1. 默认原则：在 Paperclip 核心之外构建插件

插件是独立的软件包。除非任务明确要求添加内置的仓库示例，否则不要在本仓库的 packages/plugins/ 下添加插件源码。

• 将插件脚手架生成到 Paperclip 源码目录之外的文件夹中（例如 ~/dev/paperclip-plugins/<name>）。
• 通过本地绝对路径将其安装到正在运行的 Paperclip 实例中。
• 在外部软件包中修改代码，由 Paperclip 自动加载重新构建后的产物。

只有在用户明确要求将插件显示为内置示例（涉及 server/src/routes/plugins.ts、仓库内示例列表、文档等）时，才去修改 Paperclip 核心代码本身。

2. 基本规则

需要了解细节时请参考以下文档：

1. doc/plugins/PLUGIN_AUTHORING_GUIDE.md
2. packages/plugins/sdk/README.md
3. doc/plugins/PLUGIN_SPEC.md — 仅作为前瞻性上下文参考

当前的运行时假设：

• 插件 worker 属于受信任的代码
• 插件 UI 属于受信任的同源宿主代码
• worker API 受 Capability 权限管控
• 插件 UI 未受 manifest capability 沙箱限制
• 宿主目前尚未提供共享的插件 UI 组件库
• 当前运行时暂不支持 ctx.assets

3. CLI 优先的脚手架工作流

请优先使用 paperclipai plugin init。除非环境中无法使用该 CLI 命令，否则不要手动调用脚手架包的 Node 入口。

paperclipai plugin init @acme/my-plugin --output ~/dev/paperclip-plugins

常用参数（均为可选）：

• --output <dir> — 父目录；命令会创建 <dir>/<无作用域名称>/。默认为当前工作目录。
• --template <default|connector|workspace|environment> — 起步模板。
• --category <connector|workspace|automation|ui|environment> — manifest 分类。
• --display-name <name>、--description <text>、--author <name> — manifest 元数据。
• --sdk-path <path> — 将 Paperclip 源码中的本地 SDK 关联镜像保存到 .paperclip-sdk/（在针对未发布的 SDK 进行开发时很有用）。

执行成功后，命令会输出接下来需执行的具体命令（cd、pnpm install、pnpm dev、paperclipai plugin install <绝对路径>）。请按顺序运行它们。

如果当前环境的 PATH 中没有 paperclipai 命令，请退而求其次使用以下方式：

pnpm --filter @paperclipai/create-paperclip-plugin build
node packages/plugins/create-paperclip-plugin/dist/index.js @acme/my-plugin \
  --output /absolute/path \
  --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk

4. 本地安装与重新构建循环

在生成的插件项目目录中：

pnpm install
pnpm dev            # esbuild --watch: 重新构建 dist/manifest.js、dist/worker.js、dist/ui/
paperclipai plugin install /absolute/path/to/my-plugin

注意：

• paperclipai plugin install 会自动识别本地路径（绝对路径、./、../、~ 或已存在的相对路径），并向服务端传入 isLocalPath: true。若路径规则存在模糊性，可显式指定 --local 强制启用本地模式。
• 路径在发送到服务端前会被解析为绝对路径。
• 对于本地路径安装的插件，服务端会自动监听构建产物（dist/），并在重新构建时自动重启插件 worker —— 无需在每次修改后重新安装。
• 通过 SDK 开发服务器（pnpm dev:ui，端口 4177）实现的 UI 热更新是可选的，具体取决于所选模板；只有在模板中配置了 devUiUrl 且确认端到端工作正常时才予以提及。
• --version 仅适用于 npm 包安装。与本地路径结合使用会导致错误。

安装完成后，可通过以下命令进行检查：

paperclipai plugin list
paperclipai plugin inspect <plugin-key>

5. 完成脚手架搭建后，核验项目结构

打开并确认以下文件：

• src/manifest.ts — 声明的 capability 与 slot
• src/worker.ts — worker 入口
• src/ui/index.tsx — UI 入口（如适用）
• tests/plugin.spec.ts — 占位测试文件
• package.json — paperclipPlugin 字段正确指向 dist/manifest.js、dist/worker.js 和 dist/ui/

确保插件满足以下条件：

• 仅声明受支持的 capability
• 未使用 ctx.assets
• 未导入宿主 UI 组件存根
• 保证 UI 独立自洽
• 仅在 page 类型 slot 上使用 routePath

6. 校验与验证（在声明任务完成前运行）

在插件目录中运行：

pnpm typecheck
pnpm test
pnpm build

如果插件已在 pnpm dev 监听运行中，可以保持监听不中断，在另一个 Shell 窗口中运行 pnpm typecheck 和 pnpm test。

如果除了插件代码外，还修改了 Paperclip SDK、宿主或插件运行时的代码，还需运行相应的 Paperclip 工作区检查。

7. 完成检查清单（完成后需汇报）

完成本地插件开发任务后，请汇报以下内容：

• 脚手架路径 — 新创建插件目录的绝对路径。
• 运行的命令 — 实际调用的 paperclipai plugin init、pnpm install、pnpm dev、paperclipai plugin install <绝对路径> 命令（以及执行的所有校验命令）。
• 安装状态 — paperclipai plugin list / plugin inspect 的输出结果（插件标识符 plugin key、版本、状态）。如果 status 不是 ready，请明确指出并附带 lastError。
• 测试与构建结果 — pnpm typecheck、pnpm test、pnpm build 的通过/失败情况（若失败请提供报错输出）。
• 热重载限制 — 说明所有未能自动热重载的情形（例如修改 manifest 需要重新安装、UI 开发服务器未接入等）。

如有未完成或缺失的项目，必须明确标注，不得隐瞒跳过。

8. 何时不应修改 Paperclip 核心代码

除非用户明确要求提供内置示例，否则不要在 packages/plugins/ 下添加插件，也不要更新内置示例的相关配置。本地路径安装是推荐的开发模式，而 npm 包则是生产环境的部署方式。

如果用户确实要求提供内置示例，还需同步更新：

• server/src/routes/plugins.ts 示例列表
• 所有列出仓库内示例插件的文档

9. 文档编写规范

在编写或更新插件文档时：

• 区分当前已有实现与未来规范构想
• 明确说明受信任代码模型
• 不要承诺尚不存在的宿主 UI 组件或资源 API
• 优先推荐“本地路径开发 + npm 包部署”流程，而非仓库内自带插件的开发流程