mcpField
P
paperclip-create-plugin

paperclip-create-plugin

github.com/paperclipai开发108.3k3.1k 次安装今天更新
代码仓库

关于 paperclip-create-plugin

paperclip-create-plugin 用于为本地 Paperclip 实例搭建和开发插件，侧重独立插件包，并提供 CLI 初始化、本地安装、重建及验证流程。

主要功能

  1. 01通过 CLI 搭建插件
  2. 02独立插件包开发流程
  3. 03本地路径安装指引
  4. 04重建与 Worker 重启流程
  5. 05类型检查、测试和构建验证

适用场景

  1. 01在 Paperclip 代码库外搭建插件
  2. 02安装并迭代本地插件
  3. 03报告完成前验证插件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/paperclipai/paperclip --skill paperclip-create-plugin

安装后在 Claude Code 中输入/paperclip-create-plugin确认已加载。

详细介绍

创建和开发 Paperclip 插件

在需要针对本地 Paperclip 实例创建、搭建或迭代 Paperclip 插件时使用此技能。

1. 默认情况下：在 Paperclip 核心之外构建插件

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

  • 将插件搭建在 Paperclip 检出目录之外（例如 ~/dev/paperclip-plugins/<name>）。
  • 使用本地绝对路径将其安装到正在运行的 Paperclip 实例。
  • 在外部软件包中编辑代码；让 Paperclip 使用重新构建的输出。

只有在用户要求将插件作为内置示例展示时，才编辑 Paperclip 核心本身（server/src/routes/plugins.ts、仓库内示例列表、文档）。

2. 基本规则

需要详细信息时，请参考文档：

  1. doc/plugins/PLUGIN_AUTHORING_GUIDE.md
  2. packages/plugins/sdk/README.md
  3. doc/plugins/PLUGIN_SPEC.md——仅用于了解未来规划

当前运行时假设：

  • 插件 worker 是受信任代码
  • 插件 UI 是受信任的同源宿主代码
  • worker API 受能力控制
  • 插件 UI 不受清单能力沙箱隔离
  • 宿主目前尚未提供共享插件 UI 组件套件
  • 当前运行时不支持 ctx.assets

3. 以 CLI 为先的搭建工作流

使用 paperclipai plugin init。除非环境中无法使用 CLI 命令，否则不要手动调用搭建软件包的 node 入口点。

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

实用标志（均为可选）：

  • --output <dir> — 父目录；命令会创建 <dir>/<unscoped-name>/。默认为当前目录。
  • --template <default|connector|workspace|environment> — 起始模板。
  • --category <connector|workspace|automation|ui|environment> — 清单类别。
  • --display-name <name>、--description <text>、--author <name> — 清单元数据。
  • --sdk-path <path> — 将 Paperclip 检出目录中的本地 SDK 快照保存到 .paperclip-sdk/（适用于基于尚未发布的 SDK 进行开发）。

成功后，命令会打印准确的后续命令（cd、pnpm install、pnpm dev、paperclipai plugin install <abs-path>）。请按顺序运行。

如果环境中的 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: rebuilds 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 — 声明的能力和插槽
  • src/worker.ts — worker 入口
  • src/ui/index.tsx — UI 入口（如适用）
  • tests/plugin.spec.ts — 占位测试
  • package.json — paperclipPlugin 配置块指向 dist/manifest.js、dist/worker.js、dist/ui/

确保插件：

  • 仅声明受支持的能力
  • 不使用 ctx.assets
  • 不导入宿主 UI 组件存根
  • 保持 UI 自包含
  • 仅在 page 插槽上使用 routePath

6. 验证（声明成功前运行）

在插件文件夹中：

pnpm typecheck
pnpm test
pnpm build

如果插件已通过 pnpm dev 运行，可以让监视进程继续运行，并在另一个终端中执行 pnpm typecheck 和 pnpm test。

如果除了插件之外，你还修改了 Paperclip SDK／主机／插件运行时代码，请一并运行相关的 Paperclip 工作区检查。

7. 成功检查清单（请在完成后反馈）

完成本地插件任务后，请反馈：

  • 脚手架路径 — 创建的插件文件夹的绝对路径。
  • 运行的命令 — 准确列出 paperclipai plugin init、pnpm install、pnpm dev、paperclipai plugin install <path> 的调用，以及任何验证命令。
  • 安装状态 — paperclipai plugin list／plugin inspect 的输出（插件键、版本、状态）。如果 status 不是 ready，请注明并附上 lastError。
  • 测试／构建结果 — pnpm typecheck、pnpm test、pnpm build 的通过／失败情况；如有失败，请附上失败输出。
  • 重新加载限制 — 说明任何未能热重载的内容（例如清单更改需要重新安装、UI 开发服务器未接入等）。

如果缺少任何一项，请明确标出，不要悄然跳过。

8. 何时不要修改 Paperclip 核心

除非用户明确要求提供打包示例，否则不要将插件添加到 packages/plugins/ 下，也不要更新捆绑示例接线代码。本地路径安装是受支持的开发模式；npm 包则是生产部署路径。

如果用户确实要求提供打包示例，还需更新：

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

9. 文档要求

编写或更新插件文档时：

  • 区分当前实现与未来规范构想
  • 明确说明可信代码模型
  • 不要承诺提供主机 UI 组件或资源 API
  • 优先介绍本地路径开发和 npm 包部署，而不是仓库内工作流

评论

支持 Markdown