插件开发指南

插件架构

品应用 插件系统采用微前端架构，每个插件是一个独立的、可热插拔的功能模块。插件运行在沙箱环境中，通过标准化的 Plugin API 与主平台交互。

插件类型

技术栈

• 前端：React / Vue / 原生 JS，支持任意前端框架
• 后端：Node.js / Python / Go，提供 Serverless 函数支持
• 样式：CSS Modules / Tailwind CSS，自动隔离样式
• 通信：基于 postMessage 的安全通信通道

快速开始

1. 安装 CLI 工具

npm install -g @pwmapp/cli
# 或
yarn global add @pwmapp/cli

2. 创建插件项目

pwmapp plugin create my-first-plugin
cd my-first-plugin

CLI 会交互式询问插件名称、描述、类型、模板等信息，生成项目骨架。

3. 项目结构

my-first-plugin/
├── manifest.json        # 插件清单（必填）
├── package.json
├── src/
│   ├── index.js         # 插件入口
│   ├── App.jsx          # 主组件
│   └── styles.css       # 样式
├── server/
│   └── functions/       # Serverless 函数（可选）
│       └── hello.js
├── assets/              # 静态资源
│   └── icon.png
└── README.md

4. 本地开发调试

pwmapp plugin dev

启动本地开发服务器，在 品应用 管理后台「设置 - 插件 - 开发者模式」中输入本地地址（默认 http://localhost:3000），即可实时预览插件效果。

5. 构建与打包

pwmapp plugin build
pwmapp plugin package

构建产物为 .tcplugin 格式，可直接上传到插件市场或私有部署环境。

插件清单（manifest.json）

manifest.json 是插件的核心配置文件，定义了插件的基本信息、权限、扩展点等。

{
  "manifest_version": "1.0",
  "id": "com.example.order-sync",
  "name": "订单同步插件",
  "version": "1.2.0",
  "description": "将 品应用 商机同步到 ERP 系统，自动创建订单",
  "author": {
    "name": "Example Inc.",
    "email": "dev@example.com",
    "url": "https://example.com"
  },
  "type": "integration",
  "permissions": [
    "opportunity:read",
    "opportunity:write",
    "customer:read",
    "webhook:subscribe",
    "external_api:call"
  ],
  "entry": {
    "main": "src/index.js",
    "settings": "src/Settings.jsx"
  },
  "extension_points": [
    {
      "point": "opportunity.detail.tab",
      "title": "订单同步",
      "component": "OrderSyncTab"
    },
    {
      "point": "global.command",
      "title": "同步订单到ERP",
      "command": "sync-to-erp"
    }
  ],
  "webhooks": [
    "opportunity.stage_changed",
    "opportunity.won"
  ],
  "serverless": {
    "functions": [
      {
        "name": "syncOrder",
        "path": "server/functions/syncOrder.js",
        "trigger": "webhook"
      }
    ]
  },
  "icon": "assets/icon.png",
  "homepage_url": "https://example.com/order-sync",
  "support_url": "https://example.com/support"
}

插件生命周期

插件有以下生命周期状态：

1. 已安装：用户安装插件，但未启用
2. 已启用：插件正常运行，扩展点已注册
3. 已禁用：插件被暂停，扩展点临时移除
4. 已卸载：插件被移除，数据按策略清理

插件可通过生命周期钩子执行初始化和清理逻辑：

import { registerPlugin } from '@pwmapp/sdk';

registerPlugin({
  async onInstall(context) {
    // 插件安装时执行，初始化数据
    console.log('Plugin installed', context);
  },
  async onEnable(context) {
    // 插件启用时执行
  },
  async onDisable(context) {
    // 插件禁用时执行
  },
  async onUninstall(context) {
    // 插件卸载时执行，清理数据
  }
});

UI 扩展点

插件可以在以下位置注入 UI 组件：

注册扩展点示例：

import { registerExtension } from '@pwmapp/sdk';
import OrderSyncTab from './OrderSyncTab';

registerExtension('opportunity.detail.tab', {
  id: 'order-sync-tab',
  title: '订单同步',
  icon: 'sync',
  component: OrderSyncTab,
  // 控制是否显示
  shouldShow: (context) => context.opportunity.stage === 'won'
});

数据访问

插件通过 SDK 访问 品应用 数据，权限由 manifest.json 中声明的 permissions 控制。

import { api } from '@pwmapp/sdk';

// 获取客户列表
const customers = await api.customers.list({
  page: 1,
  page_size: 20,
  filter: { level: 'A' }
});

// 创建商机
const opportunity = await api.opportunities.create({
  customer_id: 'cus_001',
  name: '年度采购合作',
  amount: 500000,
  stage: 'needs_analysis'
});

// 调用自定义 Serverless 函数
const result = await api.functions.call('syncOrder', {
  opportunity_id: 'opp_001'
});

AI 能力集成

插件可以调用 品应用 的 AI 能力，也可以注册自定义 AI 命令。

调用 AI 能力

import { ai } from '@pwmapp/sdk';

// AI 对话
const response = await ai.chat({
  query: '分析这个客户的跟进情况',
  context: { customer_id: 'cus_001' }
});

// 智能摘要
const summary = await ai.summarize({
  text: '大量的跟进记录文本...',
  format: 'bullet_points'
});

// 商机评分
const score = await ai.scoreOpportunity({
  opportunity_id: 'opp_001'
});

注册 AI 命令

插件可以注册自定义命令，让用户通过 AI 助手自然语言调用插件功能：

import { registerAICommand } from '@pwmapp/sdk';

registerAICommand({
  command: 'sync-to-erp',
  description: '将当前商机同步到 ERP 系统创建订单',
  examples: ['同步这个订单到ERP', '把商机推送到ERP'],
  handler: async (context) => {
    const { opportunity } = context;
    const result = await syncToERP(opportunity);
    return {
      type: 'card',
      title: '订单同步成功',
      content: `订单号：${result.order_no}`,
      actions: [{ label: '查看订单', url: result.url }]
    };
  }
});

事件订阅

插件可以订阅 品应用 的业务事件，在事件发生时触发 Serverless 函数执行。

// server/functions/onOpportunityWon.js
export default async function handler(event, context) {
  const { type, data } = event;
  
  if (type === 'opportunity.won') {
    // 商机赢单时，自动同步到 ERP
    const order = await syncToERP(data.opportunity);
    
    // 在 品应用 中创建跟进记录
    await context.api.activities.create({
      customer_id: data.opportunity.customer_id,
      type: 'system',
      content: `商机已赢单，ERP 订单号：${order.order_no}`
    });
  }
  
  return { success: true };
}

插件设置页

插件可以提供设置页面，让用户配置插件参数。设置页组件接收 settings 和 onChange 两个 props：

import React from 'react';

export default function Settings({ settings, onChange }) {
  return (
    

      
订单同步设置
      
        ERP 系统地址
         onChange({ erp_url: e.target.value })}
        />
      
      
        API Key
         onChange({ api_key: e.target.value })}
        />
      
      
         onChange({ auto_sync: e.target.checked })}
        />
        赢单时自动同步
      
    
  );
}

测试与调试

本地调试

使用 pwmapp plugin dev 启动开发服务器，支持热更新。在浏览器开发者工具中可以查看插件的 console 输出和网络请求。

单元测试

SDK 提供测试工具包，支持 Mock API 调用：

import { mockApi } from '@pwmapp/sdk/testing';

mockApi.customers.list.mockResolvedValue({
  items: [{ id: 'cus_001', name: '测试客户' }]
});

// 运行测试...

审核前检查清单

• manifest.json 信息完整，权限声明最小化
• 插件图标符合规范（512×512 PNG，圆角）
• 所有外部请求使用 HTTPS
• 不收集用户隐私数据（如需收集需明确告知）
• 错误处理完善，不影响主平台稳定性
• 提供完整的 README 和使用说明

上架流程

1. 提交审核：使用 pwmapp plugin submit 提交插件到插件市场
2. 审核中：品应用 团队进行安全审核和功能测试，通常 3-5 个工作日
3. 审核通过：插件上架到插件市场，所有用户可安装
4. 发布更新：新版本同样需要审核，但流程更快（通常 1-2 个工作日）

示例插件

我们提供多个开源示例插件，帮助您快速上手：

• 订单同步插件：商机赢单后自动同步到 ERP 创建订单
• 合同管理插件：在商机详情页添加合同管理 Tab，支持电子签章
• 营销自动化插件：基于客户行为触发自动化营销流程
• 快消陈列检查插件：拍照 AI 识别门店陈列问题，生成整改建议
• 企业微信集成插件：双向同步客户、跟进记录，支持消息通知

所有示例插件源码：https://github.com/pwmapp/plugin-examples