Back to Details

paperclip-create-plugin

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create a Paperclip Plugin

创建Paperclip插件

Use this skill when the task is to create, scaffold, or document a Paperclip plugin.
当任务为创建、搭建脚手架或编写Paperclip插件文档时使用本指南。

1. Ground rules

1. 基本规则

Read these first when needed:
  1. doc/plugins/PLUGIN_AUTHORING_GUIDE.md
  2. packages/plugins/sdk/README.md
  3. doc/plugins/PLUGIN_SPEC.md
    only for future-looking context
Current runtime assumptions:
  • plugin workers are trusted code
  • plugin UI is trusted same-origin host code
  • worker APIs are capability-gated
  • plugin UI is not sandboxed by manifest capabilities
  • no host-provided shared plugin UI component kit yet
  • ctx.assets
    is not supported in the current runtime
需要时请优先阅读以下文档：
  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

2. Preferred workflow

2. 推荐工作流

Use the scaffold package instead of hand-writing the boilerplate:
bash
pnpm --filter @paperclipai/create-paperclip-plugin build
node packages/plugins/create-paperclip-plugin/dist/index.js <npm-package-name> --output <target-dir>
For a plugin that lives outside the Paperclip repo, pass 
--sdk-path
and let the scaffold snapshot the local SDK/shared packages into 
.paperclip-sdk/
:
bash
pnpm --filter @paperclipai/create-paperclip-plugin build
node packages/plugins/create-paperclip-plugin/dist/index.js @acme/plugin-name \
  --output /absolute/path/to/plugin-repos \
  --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
Recommended target inside this repo:
  • packages/plugins/examples/
    for example plugins
  • another 
    packages/plugins/<name>/
    folder if it is becoming a real package
建议使用脚手架包生成代码，无需手写样板文件：
bash
pnpm --filter @paperclipai/create-paperclip-plugin build
node packages/plugins/create-paperclip-plugin/dist/index.js <npm-package-name> --output <target-dir>
如果插件存放在Paperclip仓库之外，传入
--sdk-path
参数，脚手架会将本地SDK/共享包快照存放到
.paperclip-sdk/
目录下：
bash
pnpm --filter @paperclipai/create-paperclip-plugin build
node packages/plugins/create-paperclip-plugin/dist/index.js @acme/plugin-name \
  --output /absolute/path/to/plugin-repos \
  --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
本仓库内的推荐存放路径：
  • 示例插件存放在
    packages/plugins/examples/
    目录
  • 如果是正式插件包，存放在
    packages/plugins/<name>/
    目录

3. After scaffolding

3. 脚手架生成后操作

Check and adjust:
  • src/manifest.ts
  • src/worker.ts
  • src/ui/index.tsx
  • tests/plugin.spec.ts
  • package.json
Make sure the plugin:
  • declares only supported capabilities
  • does not use 
    ctx.assets
  • does not import host UI component stubs
  • keeps UI self-contained
  • uses 
    routePath
    only on 
    page
    slots
  • is installed into Paperclip from an absolute local path during development
检查并调整以下文件：
  • src/manifest.ts
  • src/worker.ts
  • src/ui/index.tsx
  • tests/plugin.spec.ts
  • package.json
确保插件满足以下要求：
  • 仅声明支持的能力
  • 不使用
    ctx.assets
  • 不导入宿主UI组件桩代码
  • 保持UI自包含
  • 仅在
    page
    槽位使用
    routePath
  • 开发阶段从本地绝对路径安装到Paperclip中

4. If the plugin should appear in the app

4. 如需插件在应用中显示

For bundled example/discoverable behavior, update the relevant host wiring:
  • bundled example list in 
    server/src/routes/plugins.ts
  • any docs that list in-repo examples
Only do this if the user wants the plugin surfaced as a bundled example.
如果要将插件作为捆绑示例/可发现功能，更新对应的宿主配置：
  • 更新
    server/src/routes/plugins.ts
    中的捆绑示例列表
  • 更新所有列出仓库内示例的相关文档
仅当用户需要将插件作为捆绑示例展示时才执行上述操作。

5. Verification

5. 验证

Always run:
bash
pnpm --filter <plugin-package> typecheck
pnpm --filter <plugin-package> test
pnpm --filter <plugin-package> build
If you changed SDK/host/plugin runtime code too, also run broader repo checks as appropriate.
始终运行以下命令：
bash
pnpm --filter <plugin-package> typecheck
pnpm --filter <plugin-package> test
pnpm --filter <plugin-package> build
如果你同时修改了SDK/宿主/插件运行时代码，也请酌情运行更全面的仓库检查。

6. Documentation expectations

6. 文档编写要求

When authoring or updating plugin docs:
  • distinguish current implementation from future spec ideas
  • be explicit about the trusted-code model
  • do not promise host UI components or asset APIs
  • prefer npm-package deployment guidance over repo-local workflows for production
编写或更新插件文档时：
  • 区分当前实现与未来的规范构想
  • 明确说明可信代码模型
  • 不要承诺会提供宿主UI组件或资产API
  • 生产环境优先推荐npm包部署指南，而非仓库本地工作流