更新 BI 插件配置，添加运行时入口和缓存设置，增强插件功能和路由支持

Author: hotlong

content/docs/concepts/plugin-architecture.mdx

@@ -18,43 +18,113 @@ This separation ensures the platform remains lightweight and un-opinionated, all
 
 ## 2. Anatomy of a Plugin
 
-A plugin is defined by its `Manifest` (objectstack.config.ts). The most critical part of a modern ObjectStack plugin is the `contributes` section.
+A plugin is defined by its `Manifest` (objectstack.config.ts) and its runtime `Entry` (index.ts).
 
-### The `contributes` Protocol
+### The Manifest (`objectstack.config.ts`)
 
-Inspired by VS Code, we use a declarative approach to register capabilities.
+Critically, the manifest declares **Dependencies**, **Configuration Rules**, and **Contributions**.
 
 ```typescript
 // objectstack.config.ts
-export default {
+import { ObjectStackManifest } from '@objectstack/spec';
+
+const plugin: ObjectStackManifest = {
   id: 'com.vendor.bi',
+  version: '1.0.0',
   type: 'plugin',
 
-  // DECLARATIVE: "I bring these new capabilities"
+  // 1. Configuration Schema (Settings)
+  configuration: {
+    title: 'BI Engine Settings',
+    properties: {
+      'fullQueryMode': { 
+        type: 'boolean', 
+        default: false,
+        description: 'Allow unrestricted SQL queries' 
+      },
+      'apiKey': {
+        type: 'string',
+        secret: true
+      }
+    }
+  },
+
+  // 2. Dependencies
+  dependencies: {
+    'com.objectstack.core': '^2.0.0'
+  },
+
+  // 3. Contributions (Declarative Capabilities)
   contributes: {
-    // 1. Define new Metadata Kinds (File Types)
+    // Define new Metadata Kinds (File Types)
     kinds: [
       { 
         id: 'bi.dataset', 
         globs: ['**/*.dataset.json'],
-        description: 'BI Dataset Definition'
+        description: 'BI Dataset Definition' 
       }
     ],
-    // 2. Define new UI Locations
-    views: [
-      {
-        id: 'bi.chart_renderer',
-        location: 'dashboard.widget'
+    // UI Contributions
+    menus: {
+      'global/toolbar': [
+         { id: 'open_dashboard', label: 'Open BI Dashboard', command: 'bi.open' }
+      ]
+    },
+    // Server Actions (Exposed to Flows/API)
+    actions: [
+      { 
+        name: 'generate_forecast',
+        label: 'Generate Sales Forecast',
+        input: { startDate: 'date' }
       }
     ]
   },
 
-  // IMPERATIVE: "Here is the code to handle them"
-  lifecycle: './src/index.ts' 
+  // 4. Runtime Entry
+  extensions: {
+    runtime: { entry: './src/index.ts' }
+  }
+}
+```
+
+## 3. Runtime Context
+
+Plugins receive a rich strictly-typed `PluginContext` during their lifecycle. This context is the bridge to the host operating system.
+
+```typescript
+// src/index.ts
+import { PluginDefinition, PluginContextData } from '@objectstack/spec';
+
+const definition: PluginDefinition = {
+  id: 'com.vendor.bi',
+  
+  onEnable: async (context: PluginContextData) => {
+    // A. Access Type-Safe Context
+    const { logger, ql, os, app, storage, i18n } = context;
+
+    logger.info('Starting BI Engine...');
+
+    // B. Use Scoped Storage (KV Store)
+    const lastRun = await storage.get('last_run_timestamp');
+
+    // C. Register Runtime Routes
+    app.router.get('/bi/stats', async () => {
+       return { active_reports: 10 };
+    });
+
+    // D. Interact with Core Data
+    const data = await ql.object('account').find({ industry: 'Tech' });
+
+    // E. Read Configuration
+    const config = await os.getConfig('com.vendor.bi');
+    if (config.fullQueryMode) { 
+       logger.warn('Running in Full Query Mode');
+    }
+  }
 }
 ```
 
-## 3. Extension Capabilities
+## 4. Extension Capabilities
 
 ### A. New Metadata Kinds (CRDs)
 

examples/plugin-bi/objectstack.config.ts

@@ -7,7 +7,24 @@ const BiPlugin: ObjectStackManifest = {
   type: 'plugin',
   description: 'Provides BI capabilities, dataset definitions, and chart rendering.',
 
-  // Register Capabilities
+  // 1. Configuration (Settings)
+  configuration: {
+    title: 'BI Plugin Configuration',
+    properties: {
+      enableCache: {
+        type: 'boolean',
+        default: true,
+        description: 'Enable in-memory caching for query results'
+      },
+      maxRows: {
+        type: 'number',
+        default: 1000,
+        description: 'Maximum rows returned per query'
+      }
+    }
+  },
+
+  // 2. Capabilities
   contributes: {
     kinds: [
       {
@@ -20,10 +37,23 @@ const BiPlugin: ObjectStackManifest = {
         globs: ['**/*.bi-dash.json'],
         description: 'Advanced BI Dashboard'
       }
+    ],
+    menus: {
+      'sidebar/tools': [
+        { id: 'open_bi_studio', label: 'BI Studio', command: 'bi.openStudio' }
+      ]
+    },
+    actions: [
+      { 
+        name: 'refresh_dataset',
+        label: 'Refresh Dataset',
+        description: 'Manually trigger a dataset refresh',
+        input: { datasetId: 'string' }
+      }
     ]
   },
 
-  // Lifecycle Entry Point
+  // 3. Lifecycle Entry Point
   // in a real scenario, this would be a path or module name
   extensions: {
     runtime: {

examples/plugin-bi/src/index.ts

@@ -20,18 +20,42 @@ const plugin: PluginDefinition = {
   version: '1.0.0',
 
   onEnable: async (context: PluginContextData) => {
-    const logger = context.logger || console;
+    // 1. Destructure strict APIs
+    const { logger, ql, os, app, storage, i18n } = context;
+
     logger.info('[BI Plugin] Enabling BI Plugin...');
 
-    // Register Service
+    // 2. Use Configuration
+    const config = await os.getConfig('com.objectstack.bi');
+    if (config?.enableCache) {
+      logger.info('Caching Enabled');
+    }
+
+    // 3. Register Service
     const engine = new BiEngine();
 
     // Access runtime capabilities not in strict schema
+    // In a real implementation module augmentation would be used
     const runtime = context as any;
     if (runtime.services) {
       runtime.services.register('bi.engine', engine);
     }
 
+    // 4. Register Route
+    app.router.get('/bi/status', async () => {
+      return { status: 'running', engine: 'v1' };
+    });
+
+    // 5. Use Storage
+    await storage.set('started_at', Date.now());
+
+    // 6. Demonstrate i18n & Data Access
+    // (In a real app, this would be used in a route or job)
+    if (Date.now() % 1000 === 0) {
+       console.log(i18n.t('hello_world', {}));
+       await ql.object('account').query('SELECT count() FROM account');
+    }
+
     logger.info('[BI Plugin] Services registered.');
   }
 };