feat: 添加插件架构文档，更新 Manifest 和元数据结构，支持平台扩展注册

Author: hotlong

.cursorrules

@@ -14,6 +14,7 @@ You define what a "Package" looks like in ObjectStack.
    * type: app | plugin | driver | module.
    * permissions: Array of permission strings requested (e.g., ["system.user.read"]).
    * navigation: Structured navigation menu tree (for apps).
+   * contributes: Register platform extensions (kind, etc).
    * entities: Glob patterns for ObjectQL files (e.g., ["./src/schema/*.gql"]).
    * extensions: Extension points (e.g., contributions to the UI).
 2. Directory Conventions (Law of Location)

.cursorrules.d/objectstack.prompt.md

@@ -53,7 +53,8 @@ File: objectstack.config.ts (or strict JSON inside package.json)
 Schema Location: packages/protocol/schemas/manifest.schema.json
 Key Fields:
  * type: app | plugin | driver
- * menus: Array of navigation items to inject into the OS sidebar.
+ * navigation: Structured navigation menu tree.
+ * contributes: Register platform extensions (e.g., custom kinds).
  * permissions: Array of requested capabilities (e.g., finance.read).
  * entities: Path patterns to auto-load Schema files (e.g., ./src/schemas/*.gql).
  * lifecycle: Hooks for onInstall, onEnable.

content/docs/concepts/meta.json

@@ -5,6 +5,7 @@
     "manifesto",
     "core-values",
     "architecture",
+    "plugin-architecture",
     "security_architecture",
     "enterprise-patterns",
     "ai-codex",

content/docs/concepts/plugin-architecture.mdx

@@ -0,0 +1,91 @@
+---
+title: Plugin Architecture
+description: The Extension Model and Microkernel Philosophy of ObjectStack.
+---
+
+# Plugin Architecture
+
+ObjectStack follows a strict **Microkernel Architecture**. The core platform provides only the minimal runtime environment (Kernel), while all business capabilities, including standard ones like CRM or Project Management, are delivered as **Packages** (Apps or Plugins).
+
+## 1. Philosophy: "Kernel + Plugins"
+
+*   **The Kernel**: Responsible for booting, identity, permission enforcement, and loading the manifest. It knows *nothing* about "Leads", "Tasks", or even "Kanban Boards" initially.
+*   **The Plugins**: Teach the Kernel new tricks.
+    *   **Apps**: Combinations of data and UI for end-users (e.g., "Sales App").
+    *   **Plugins**: Extensions to the system capabilities (e.g., "BI Engine", "SAML Auth", "Stripe Payment").
+
+This separation ensures the platform remains lightweight and un-opinionated, allowing it to evolve indefinitely.
+
+## 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.
+
+### The `contributes` Protocol
+
+Inspired by VS Code, we use a declarative approach to register capabilities.
+
+```typescript
+// objectstack.config.ts
+export default {
+  id: 'com.vendor.bi',
+  type: 'plugin',
+  
+  // DECLARATIVE: "I bring these new capabilities"
+  contributes: {
+    // 1. Define new Metadata Kinds (File Types)
+    kinds: [
+      { 
+        id: 'bi.dataset', 
+        globs: ['**/*.dataset.json'],
+        description: 'BI Dataset Definition'
+      }
+    ],
+    // 2. Define new UI Locations
+    views: [
+      {
+        id: 'bi.chart_renderer',
+        location: 'dashboard.widget'
+      }
+    ]
+  },
+  
+  // IMPERATIVE: "Here is the code to handle them"
+  lifecycle: './src/index.ts' 
+}
+```
+
+## 3. Extension Capabilities
+
+### A. New Metadata Kinds (CRDs)
+
+This is the most powerful feature. A plugin can introduce entirely new concepts to the platform.
+
+*   **Example**: A "BI Plugin" introduces `*.dataset.json` and `*.report.json`.
+*   **Mechanism**: The Kernel uses the `contributes.kinds` registry to map file extensions to the plugin's parser.
+*   **Result**: The IDE (cursor/vscode) and Runtime automatically recognize these files.
+
+### B. Service Providers
+
+Plugins can implement standard interfaces defined by the system.
+
+*   **Auth Providers**: `plugin extends AuthProvider` (SAML, OAuth).
+*   **Storage Drivers**: `plugin extends StorageDriver` (S3, MinIO).
+*   **Notification Channels**: `plugin extends NotificationChannel` (Slack, SMS).
+
+## 4. Plugin Lifecycle
+
+The runtime manages the plugin states:
+
+1.  **Resolve**: Read Manifest, validate dependencies.
+2.  **Install (`onInstall`)**: Run migration scripts, setup initial data.
+3.  **Boot (`onBoot`)**: Register generic services (before App load).
+4.  **Enable (`onEnable`)**: Active and serving traffic.
+
+```typescript
+export class BiPlugin implements PluginLifecycle {
+  async onEnable(context: PluginContext) {
+    // Register the heavy engine only when enabled
+    context.services.register('bi.engine', new BiAnalysisEngine());
+  }
+}
+```

content/docs/references/system/config/Manifest.mdx

@@ -13,6 +13,6 @@ description: Manifest Schema Reference
 | **name** | `string` | ✅ | Human-readable package name |
 | **description** | `string` | optional | Package description |
 | **permissions** | `string[]` | optional | Array of required permission strings |
-| **menus** | `object[]` | optional | Navigation menu structure |
 | **objects** | `string[]` | optional | Glob patterns for ObjectQL schemas files |
+| **contributes** | `object` | optional | Platform contributions (e.g. kinds) |
 | **extensions** | `Record<string, any>` | optional | Extension points and contributions |

content/prompts/index.mdx

@@ -39,7 +39,7 @@ title: Documentation
 * **[ ] 4. 插件清单协议 (`ManifestSchema`)**
 * **定义目标**: 描述一个软件包（插件/应用）。
 * **文件对应**: `objectstack.config.ts` 或 `package.json > objectstack`。
-* **关键字段**: `id`, `version`, `type` (app/plugin/driver), `permissions` (申请权限), `menus` (导航注入)。
+* **关键字段**: `id`, `version`, `type`, `contributes` (注册能力), `permissions` (权限)。
 * **用途**: CLI 打包校验，应用商店展示。
 
 

content/prompts/objectstack.prompt.md

@@ -54,6 +54,7 @@ Schema Location: packages/protocol/schemas/manifest.schema.json
 Key Fields:
  * type: app | plugin | driver
  * navigation: Structured navigation menu tree.
+ * contributes: Register platform extensions (e.g., custom kinds).
  * permissions: Array of requested capabilities (e.g., finance.read).
  * entities: Path patterns to auto-load Schema files (e.g., ./src/schemas/*.gql).
  * lifecycle: Hooks for onInstall, onEnable.

packages/spec/src/system/manifest.test.ts

@@ -196,6 +196,29 @@ describe('ManifestSchema', () => {
       expect(() => ManifestSchema.parse(crmManifest)).not.toThrow();
     });
 
+    it('should accept bi plugin with custom kinds', () => {
+      const biPlugin: ObjectStackManifest = {
+        id: 'com.objectstack.bi',
+        version: '1.0.0',
+        type: 'plugin',
+        name: 'Business Intelligence',
+        contributes: {
+            kinds: [
+                {
+                    id: 'bi.dataset',
+                    globs: ['**/*.dataset.json']
+                },
+                {
+                    id: 'bi.dashboard',
+                    globs: ['**/*.bi-dash.json']
+                }
+            ]
+        }
+      };
+      
+      expect(() => ManifestSchema.parse(biPlugin)).not.toThrow();
+    });
+
     it('should accept authentication plugin manifest', () => {
       const authPlugin: ObjectStackManifest = {
         id: 'com.objectstack.auth.saml',

packages/spec/src/system/manifest.zod.ts

@@ -49,6 +49,22 @@ export const ManifestSchema = z.object({
    */
   objects: z.array(z.string()).optional().describe('Glob patterns for ObjectQL schemas files'),
 
+  /**
+   * Contribution Points (VS Code Style).
+   * formalized way to extend the platform capabilities.
+   */
+  contributes: z.object({
+    /**
+     * Register new Metadata Kinds (CRDs).
+     * Enables the system to parse and validate new file types.
+     * Example: Registering a BI plugin to handle *.report.ts
+     */
+    kinds: z.array(z.object({
+      id: z.string().describe('The generic identifier of the kind (e.g., "sys.bi.report")'),
+      globs: z.array(z.string()).describe('File patterns to watch (e.g., ["**/*.report.ts"])'),
+    })).optional(),
+  }).optional().describe('Platform contributions'),
+
   /** 
    * Extension points contributed by this package.
    * Allows packages to extend UI components, add functionality, etc.