插件開發指南

插件架构

品應用 插件系统采用微前端架构，每個插件是一個独立的、可熱插拔的功能模塊。插件運行在沙箱环境中，透過标准化的 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