更新文档，完成 Driver 接口的实现指南，添加自定义驱动的构建步骤和示例

Author: hotlong

QUICK_START_IMPLEMENTATION.md

@@ -12,7 +12,7 @@
 |----------|----------|--------|--------|------|
 | **Field Widget Contract** | ⚠️ CRITICAL | 1-2 days | 🔴 Not Started | `packages/spec/src/ui/widget.zod.ts` |
 | **Plugin Lifecycle** | ⚠️ CRITICAL | 2-3 days | 🔴 Not Started | `packages/spec/src/system/plugin.zod.ts` |
-| **Driver Interface** | ⚠️ CRITICAL | 3-4 days | 🔴 Not Started | `packages/spec/src/system/driver.zod.ts` |
+| **Driver Interface** | ⚠️ CRITICAL | 3-4 days | ✅ Done | `packages/spec/src/system/driver.zod.ts` |
 | **Trigger Context** | 🟡 HIGH | 1-2 days | 🔴 Not Started | `packages/spec/src/data/trigger.zod.ts` |
 
 **Total Estimated Effort**: 7-11 days (1 developer) or 2-3 days (4 developers in parallel)

content/docs/guides/custom-driver.cn.mdx

@@ -0,0 +1,119 @@
+---
+title: 构建自定义驱动
+description: 学习如何使用驱动接口为 ObjectStack 实现自定义数据库驱动。
+---
+
+# 构建自定义驱动
+
+驱动程序（Driver）是 **ObjectQL** 引擎与底层数据存储（SQL、NoSQL、API 等）之间的桥梁。通过实现 `DriverInterface`，您可以将 ObjectStack 连接到任何数据源。
+
+本指南将以创建一个简单的 **内存驱动（In-Memory Driver）** 为例进行讲解。
+
+## 先决条件
+
+- 现有的 ObjectStack 工作区或插件包。
+- 依赖 `@objectstack/objectql` 和 `@objectstack/spec`。
+
+## 1. 驱动接口 (Driver Interface)
+
+所有驱动程序必须实现规范中定义的 `DriverInterface`。
+
+```typescript
+import { DriverInterface, DriverOptions } from '@objectstack/spec';
+import { QueryAST, QueryResult } from '@objectstack/objectql';
+
+export class MyCustomDriver implements DriverInterface {
+    name = 'MyCustomDriver';
+
+    async connect() {
+        // 初始化连接
+    }
+
+    async disconnect() {
+        // 关闭连接
+    }
+    
+    // ... CRUD 方法
+}
+```
+
+## 2. 实现 CRUD 操作
+
+您需要实现 `find`（查询）、`insert`（插入）、`update`（更新）和 `delete`（删除）方法。
+
+### Find (查询)
+
+`find` 方法接收一个 `QueryAST` 对象，其中包含结构化的查询信息（过滤、排序、分页）。
+
+```typescript
+async find(object: string, query: QueryAST, options?: DriverOptions): Promise<QueryResult> {
+    // 1. 将 QueryAST 转换为数据库的查询语言（例如 SQL）
+    // 2. 执行查询
+    // 3. 返回对象数组结果
+    return []; 
+}
+```
+
+### Insert (插入)
+
+```typescript
+async insert(object: string, data: Record<string, any>, options?: DriverOptions) {
+    // 将数据插入存储
+    return data;
+}
+```
+
+### Update (更新)
+
+```typescript
+async update(object: string, id: string, data: Record<string, any>, options?: DriverOptions) {
+    // 更新由 `id` 标识的记录
+    return { id, ...data };
+}
+```
+
+### Delete (删除)
+
+```typescript
+async delete(object: string, id: string, options?: DriverOptions) {
+    // 删除记录
+}
+```
+
+## 3. 类型处理
+
+使用 `@objectstack/objectql` 提供的类型以确保兼容性。
+
+- `QueryAST`: 通用的查询抽象语法树。
+- `QueryResult`: `Record<string, any>[]`.
+
+## 4. 注册驱动
+
+在插件的运行时入口点（例如 `index.ts`）导出驱动程序，以便引擎使用。
+
+```typescript
+import { MyCustomDriver } from './my-driver';
+
+export default {
+    drivers: [new MyCustomDriver()]
+};
+```
+
+## 示例：内存驱动
+
+请参考 `examples/plugin-driver-memory` 中的参考实现。
+
+```typescript
+// examples/plugin-driver-memory/src/memory-driver.ts
+export class InMemoryDriver implements DriverInterface {
+  name = 'InMemory';
+  private store = new Map<string, Map<string, any>>();
+
+  async find(object: string, query: QueryAST) {
+    const table = this.store.get(object) || new Map();
+    // 简单的过滤实现...
+    return Array.from(table.values());
+  }
+  // ...
+}
+```

content/docs/guides/custom-driver.mdx

@@ -0,0 +1,119 @@
+---
+title: Building a Custom Driver
+description: Learn how to implement a custom database driver for ObjectStack using the Driver Interface.
+---
+
+# Building a Custom Driver
+
+Drivers are the bridge between the **ObjectQL** engine and the underlying data storage (SQL, NoSQL, APIs, etc.). By implementing the `DriverInterface`, you can connect ObjectStack to any data source.
+
+In this guide, we will walk through creating a simple **In-Memory Driver** as an example.
+
+## Prerequisites
+
+- Existing ObjectStack workspace or plugin package.
+- Dependency on `@objectstack/objectql` and `@objectstack/spec`.
+
+## 1. The Driver Interface
+
+All drivers must implement the `DriverInterface` defined in the specification.
+
+```typescript
+import { DriverInterface, DriverOptions } from '@objectstack/spec';
+import { QueryAST, QueryResult } from '@objectstack/objectql';
+
+export class MyCustomDriver implements DriverInterface {
+    name = 'MyCustomDriver';
+
+    async connect() {
+        // Initialize connection
+    }
+
+    async disconnect() {
+        // Close connection
+    }
+    
+    // ... CRUD Methods
+}
+```
+
+## 2. Implementing CRUD Operations
+
+You need to implement `find`, `insert`, `update`, and `delete` methods.
+
+### Find (Query)
+
+The `find` method receives a `QueryAST` object, which contains structured query information (filters, sorting, pagination).
+
+```typescript
+async find(object: string, query: QueryAST, options?: DriverOptions): Promise<QueryResult> {
+    // 1. Convert QueryAST to your database's query language (e.g., SQL)
+    // 2. Execute query
+    // 3. Return results as an array of objects
+    return []; 
+}
+```
+
+### Insert (Create)
+
+```typescript
+async insert(object: string, data: Record<string, any>, options?: DriverOptions) {
+    // Insert data into the storage
+    return data;
+}
+```
+
+### Update
+
+```typescript
+async update(object: string, id: string, data: Record<string, any>, options?: DriverOptions) {
+    // Update the record identified by `id`
+    return { id, ...data };
+}
+```
+
+### Delete
+
+```typescript
+async delete(object: string, id: string, options?: DriverOptions) {
+    // Remove the record
+}
+```
+
+## 3. Handling Types
+
+Use the types provided by `@objectstack/objectql` to ensure compatibility.
+
+- `QueryAST`: The universal abstract syntax tree for queries.
+- `QueryResult`: `Record<string, any>[]`.
+
+## 4. Registering the Driver
+
+In your plugin's runtime entry point (e.g., `index.ts`), export the driver so it can be used by the engine.
+
+```typescript
+import { MyCustomDriver } from './my-driver';
+
+export default {
+    drivers: [new MyCustomDriver()]
+};
+```
+
+## Example: In-Memory Driver
+
+See the reference implementation in `examples/plugin-driver-memory`.
+
+```typescript
+// examples/plugin-driver-memory/src/memory-driver.ts
+export class InMemoryDriver implements DriverInterface {
+  name = 'InMemory';
+  private store = new Map<string, Map<string, any>>();
+
+  async find(object: string, query: QueryAST) {
+    const table = this.store.get(object) || new Map();
+    // Simple filter implementation...
+    return Array.from(table.values());
+  }
+  // ...
+}
+```

content/docs/guides/meta.cn.json

@@ -4,6 +4,7 @@
   "pages": [
     "getting-started",
     "installation",
-    "project-structure"
+    "project-structure",
+    "custom-driver"
   ]
 }

content/docs/guides/meta.json

@@ -4,6 +4,7 @@
   "pages": [
     "getting-started",
     "installation",
-    "project-structure"
+    "project-structure",
+    "custom-driver"
   ]
 }