@openlearn/plugin-sdk 3.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @openlearn/plugin-sdk
+
+OpenLearn 平台插件开发的类型定义包。
+
+## 安装
+
+```bash
+npm install --save-dev @openlearn/plugin-sdk
+```
+
+## 使用
+
+```typescript
+import type { PluginContext, Manifest } from '@openlearn/plugin-sdk';
+import { ICommandBusServiceToken } from '@openlearn/plugin-sdk';
+
+export default {
+  manifest: {
+    id: 'ext-my-plugin',
+    name: 'My Plugin',
+    version: '1.0.0',
+    main: 'index.js',
+    engines: { openlearn: '^2.5.0' },
+    capabilitiesProposed: ['lesson:read'],
+  } satisfies Manifest,
+
+  async activate(ctx: PluginContext) {
+    ctx.log.info('Plugin activated');
+    // ...
+  },
+};
+```
+
+## 提供的内容
+
+| 类别 | 导出 |
+|------|------|
+| 上下文 | `PluginContext`, `PluginDatabaseAPI`, `PluginInfo`, `IPluginLogger` |
+| Manifest | `Manifest`, `ManifestV3` |
+| 服务接口 | `ICommandBusService`, `IEventBusService`, `IActionRegistryService`, `ICapabilityService`, `IProcessService`, `IStorageService`, `IAIService` |
+| Token | `ICommandBusServiceToken`, `IEventBusServiceToken`, ... (10 个 Token) |
+| 命令/事件 | `PlatformCommand`, `PlatformEvent`, `CommandHandler`, `EventSubscriber` |
+| 动作注册 | `ActionDescriptor` |

package/dist/index.d.ts

@@ -0,0 +1,299 @@
+/**
+ * @openlearn/plugin-sdk — standalone type declarations (V3.1).
+ *
+ * Self-contained `.d.ts` for npm publishing. No re-exports from monorepo internals.
+ * This is the public API contract for OpenLearn plugin development.
+ *
+ * Generated from packages/core/ source types. Update when core types change.
+ */
+
+// ── Token ────────────────────────────────────────────────────────────────
+
+declare class Token<T> {
+  readonly name: string;
+  readonly version: string;
+  constructor(name: string, version?: string);
+}
+
+// ── Plugin State & Lifecycle ─────────────────────────────────────────────
+
+declare enum PluginState {
+  INSTALLED = 'installed',
+  ACTIVATING = 'activating',
+  ACTIVE = 'active',
+  DEACTIVATING = 'deactivating',
+  INACTIVE = 'inactive',
+  ERROR = 'error',
+  UNINSTALLED = 'uninstalled',
+}
+
+interface Disposable {
+  dispose(): void;
+}
+
+// ── Manifest ─────────────────────────────────────────────────────────────
+
+interface Manifest {
+  id: string;
+  name: string;
+  version: string;
+  main: string;
+  requires?: string[];
+  optional?: string[];
+  capabilitiesProposed?: string[];
+  engines?: { openlearn: string };
+  pluginDependencies?: string[];
+  provides?: string[];
+  configuration?: {
+    properties?: Record<string, {
+      type: 'string' | 'number' | 'boolean' | 'integer';
+      default?: unknown;
+      description?: string;
+      enum?: unknown[];
+      minimum?: number;
+      maximum?: number;
+    }>;
+  };
+  contributes?: Record<string, Array<{ id: string; [key: string]: unknown }>>;
+  [key: string]: unknown;
+}
+
+// ── Command & Event ──────────────────────────────────────────────────────
+
+interface PlatformCommand<T = unknown> {
+  id: string;
+  type: string;
+  actorId: string;
+  payload: T;
+  timestamp: number;
+  metadata?: Record<string, unknown>;
+}
+
+interface CommandHandler {
+  execute(command: PlatformCommand): Promise<unknown>;
+}
+
+interface CommandMetadata {
+  approved?: boolean;
+  [key: string]: unknown;
+}
+
+interface PlatformEvent<T = unknown> {
+  id: string;
+  type: string;
+  source: string;
+  payload: T;
+  timestamp: number;
+  correlationId?: string;
+}
+
+type EventSubscriber = (event: PlatformEvent) => void | Promise<void>;
+
+// ── Action Registry ──────────────────────────────────────────────────────
+
+interface ActionDescriptor {
+  readonly id: string;
+  readonly commandType: string;
+  readonly description: string;
+  readonly inputSchema: unknown;
+  readonly capabilityRequired: string;
+  readonly isHighRisk?: boolean;
+}
+
+// ── Service Interfaces ───────────────────────────────────────────────────
+
+interface ICommandBusService {
+  execute<T extends PlatformCommand>(command: T): Promise<unknown>;
+  registerHandler(commandType: string, handler: CommandHandler): Promise<void>;
+  unregisterHandler(commandType: string): Promise<void>;
+  createCommand<T>(type: string, payload: T, actorId: string, metadata?: CommandMetadata): Promise<PlatformCommand<T>>;
+  setInterceptor(interceptor: (command: PlatformCommand) => Promise<void>): Promise<void>;
+}
+
+interface IEventBusService {
+  publish(event: PlatformEvent): Promise<void>;
+  subscribe(eventType: string, subscriber: EventSubscriber): Promise<void>;
+  unsubscribe(eventType: string, subscriber: EventSubscriber): Promise<void>;
+}
+
+interface IActionRegistryService {
+  register(descriptor: ActionDescriptor): Promise<void>;
+  unregister(id: string): Promise<void>;
+  getAllActions(): Promise<ActionDescriptor[]>;
+  getAgentTools(): Promise<unknown[]>;
+  getActionByToolName(toolName: string): Promise<ActionDescriptor | undefined>;
+  getActionByCommandType(commandType: string): Promise<ActionDescriptor | undefined>;
+}
+
+interface ICapabilityService {
+  grant(actorId: string, cap: string): Promise<void>;
+  revokeAll(actorId: string): Promise<void>;
+  check(actorId: string, requiredCap: string): Promise<boolean>;
+}
+
+interface IProcessService {
+  spawn(name: string, taskType: string, payload: unknown): Promise<string>;
+  kill(processId: string): Promise<void>;
+  registerHandler(taskType: string, handler: ProcessHandler): Promise<void>;
+  unregisterHandler(taskType: string): Promise<void>;
+  registerInterval(name: string, intervalMs: number, tickFn: (log: (msg: string) => void) => void): Promise<string>;
+  restore(): Promise<void>;
+}
+
+type ProcessHandler = (
+  processId: string,
+  payload: unknown,
+  state: unknown,
+  log: (msg: string) => void,
+  updateState: (newState: unknown) => void,
+) => Promise<void>;
+
+interface IStorageService {
+  get(key: string): Promise<unknown>;
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+interface IAIService {
+  generateText(prompt: string, options?: { systemInstruction?: string; temperature?: number }): Promise<string>;
+}
+
+// ── Logger ───────────────────────────────────────────────────────────────
+
+interface IPluginLogger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+
+// ── Config Service ───────────────────────────────────────────────────────
+
+interface IConfigService {
+  get<T = unknown>(key: string): T;
+  getAll(): Record<string, unknown>;
+  set(key: string, value: unknown): Promise<void>;
+  onChange(callback: (key: string, newValue: unknown, oldValue: unknown) => void): () => void;
+}
+
+interface ConfigProperty {
+  type: 'string' | 'number' | 'boolean' | 'integer';
+  default?: unknown;
+  description?: string;
+  enum?: unknown[];
+  minimum?: number;
+  maximum?: number;
+}
+
+interface ConfigDeclaration {
+  properties?: Record<string, ConfigProperty>;
+}
+
+// ── Plugin Database API ──────────────────────────────────────────────────
+
+interface PluginDatabaseAPI {
+  ensureTable(tableName: string, schema: string): Promise<void>;
+  table(tableName: string): string;
+  dropAllTables(): Promise<void>;
+  migrate(targetVersion: number, upgradeFn: (db: unknown) => Promise<void> | void): Promise<void>;
+}
+
+// ── Contribution Registry ────────────────────────────────────────────────
+
+interface ContributionSummary {
+  slot: string;
+  count: number;
+  items: Array<{ id: string; label: string }>;
+}
+
+interface ContributionAccessor {
+  list(): ContributionSummary[];
+}
+
+interface ClassroomToolConfig {
+  id: string;
+  name: string;
+  icon?: string;
+  description?: string;
+  commandType: string;
+  payload?: Record<string, unknown>;
+}
+
+interface TeacherTabConfig {
+  id: string;
+  label: string;
+  icon?: string;
+  position?: number;
+}
+
+interface DashboardWidgetConfig {
+  id: string;
+  label: string;
+  icon?: string;
+  position?: number;
+}
+
+interface StudentViewConfig {
+  id: string;
+  label: string;
+  icon?: string;
+  route?: string;
+}
+
+interface StudentLessonToolConfig {
+  id: string;
+  label: string;
+  icon?: string;
+}
+
+type ContributionConfig =
+  | ClassroomToolConfig
+  | TeacherTabConfig
+  | DashboardWidgetConfig
+  | StudentViewConfig
+  | StudentLessonToolConfig;
+
+// ── Plugin Context ───────────────────────────────────────────────────────
+
+interface PluginContext {
+  services: {
+    commandBus: ICommandBusService;
+    eventBus: IEventBusService;
+    actionRegistry: IActionRegistryService;
+    capability: ICapabilityService;
+    processManager: IProcessService;
+    storage: IStorageService;
+    ai: IAIService;
+  };
+  pluginId: string;
+  manifest: Manifest;
+  resolve<T>(token: Token<T>): Promise<T>;
+  provide(tokenName: string, instance: unknown): Promise<void>;
+  db: PluginDatabaseAPI;
+  log: IPluginLogger;
+  config: IConfigService;
+  contributions: ContributionAccessor;
+  require(moduleName: string): unknown;
+}
+
+interface PluginInfo {
+  id: string;
+  name: string;
+  version: string;
+  state: PluginState;
+  status?: string;
+  execution_mode?: string;
+}
+
+// ── Token Constants ──────────────────────────────────────────────────────
+
+declare const ICommandBusServiceToken: Token<ICommandBusService>;
+declare const IEventBusServiceToken: Token<IEventBusService>;
+declare const IActionRegistryServiceToken: Token<IActionRegistryService>;
+declare const ICapabilityServiceToken: Token<ICapabilityService>;
+declare const IProcessServiceToken: Token<IProcessService>;
+declare const IStorageServiceToken: Token<IStorageService>;
+declare const IAIServiceToken: Token<IAIService>;
+declare const IDatabaseToken: Token<unknown>;
+declare const IPluginHostToken: Token<unknown>;
+declare const ISemesterGradeServiceToken: Token<unknown>;

package/dist/index.js

@@ -0,0 +1,70 @@
+// ../core/di/errors.ts
+var TokenError = class extends Error {
+  constructor(message) {
+    super(`[Token] ${message}`);
+    this.name = "TokenError";
+  }
+};
+
+// ../core/di/token.ts
+var TOKEN_NAME_RE = /^@[a-zA-Z0-9_-]+\/[a-zA-Z0-9_-]+:[a-zA-Z0-9_]+$/;
+var Token = class {
+  constructor(name, version = "1.0.0") {
+    if (!name || typeof name !== "string") {
+      throw new TokenError(
+        `Token name must be a non-empty string, got: ${String(name)}`
+      );
+    }
+    if (!TOKEN_NAME_RE.test(name)) {
+      throw new TokenError(
+        `Invalid Token name format: "${name}". Expected: @scope/domain:ServiceName`
+      );
+    }
+    this.name = name;
+    this.version = version;
+  }
+};
+
+// ../core/di/interfaces.ts
+var ICommandBusServiceToken = new Token(
+  "@openlearn/core:ICommandBusService"
+);
+var IEventBusServiceToken = new Token(
+  "@openlearn/core:IEventBusService"
+);
+var IActionRegistryServiceToken = new Token(
+  "@openlearn/core:IActionRegistryService"
+);
+var ICapabilityServiceToken = new Token(
+  "@openlearn/core:ICapabilityService"
+);
+var IProcessServiceToken = new Token(
+  "@openlearn/core:IProcessService"
+);
+var IStorageServiceToken = new Token(
+  "@openlearn/core:IStorageService"
+);
+var IAIServiceToken = new Token(
+  "@openlearn/core:IAIService"
+);
+var IDatabaseToken = new Token(
+  "@openlearn/core:IDatabase"
+);
+var IPluginHostToken = new Token(
+  "@openlearn/core:IPluginHost"
+);
+var ISemesterGradeServiceToken = new Token(
+  "@openlearn/core:ISemesterGradeService"
+);
+export {
+  IAIServiceToken,
+  IActionRegistryServiceToken,
+  ICapabilityServiceToken,
+  ICommandBusServiceToken,
+  IDatabaseToken,
+  IEventBusServiceToken,
+  IPluginHostToken,
+  IProcessServiceToken,
+  ISemesterGradeServiceToken,
+  IStorageServiceToken
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@openlearn/plugin-sdk",
+  "version": "3.1.0",
+  "description": "TypeScript type definitions and DI tokens for OpenLearn plugin development",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "prepublishOnly": "node build.mjs"
+  },
+  "peerDependencies": {
+    "zod": ">=4"
+  },
+  "keywords": [
+    "openlearn",
+    "plugin",
+    "sdk",
+    "types",
+    "educational",
+    "lms"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openlearn/openlearnv2",
+    "directory": "packages/plugin-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}