@southwind-ai/server-sdk 0.1.1 → 0.1.3

package/index.ts

@@ -1,5 +1,58 @@
+export type { ModuleActor } from "./src/actor.js";
 export type {
+  ModuleAuditEmitter,
+  ModuleAuditEmitInput,
+  ModuleAuditTarget,
+} from "./src/audit-port.js";
+export type {
+  ModuleJobSubmitter,
+  ModuleJobSubmitInput,
+  ModuleJobSubmitResult,
+} from "./src/jobs-port.js";
+export type {
+  InstallableServerModule,
   ModuleHost,
   ModuleInitializer,
   ModuleUploadPolicy,
 } from "./src/module-host.js";
+export { requireModuleNamespace } from "./src/namespace.js";
+export type { ModuleRequestContext } from "./src/request-context.js";
+export type { ModuleRolePreset } from "./src/role-preset.js";
+export type {
+  ModuleRouteDefinition,
+  ModuleRouteHandler,
+  ModuleRouteMethod,
+} from "./src/route-definition.js";
+export type {
+  ModuleSearchContext,
+  ModuleSearchHealth,
+  ModuleSearchHit,
+  ModuleSearchPage,
+  ModuleSearchProvider,
+  ModuleSearchQuery,
+} from "./src/search-provider-port.js";
+export type {
+  ModuleStoragePort,
+  ModuleUploadSessionInput,
+} from "./src/storage-port.js";
+export type {
+  ModuleTaskHandler,
+  ModuleTaskHandlerRegistration,
+  ModuleTaskResult,
+} from "./src/task-registration.js";
+export type {
+  ModuleAgentToolHostPort,
+  ModuleAgentToolInvocation,
+  ModuleAgentToolResult,
+} from "./src/tool-host-port.js";
+export type {
+  ModuleToolContext,
+  ModuleToolHandlerRegistration,
+  ModuleToolResult,
+} from "./src/tool-registration.js";
+export type {
+  ModuleAiJsonValue,
+  ModuleAiOperationContext,
+  ModuleAiOperationHandlerRegistration,
+  ModuleAiOperationPlan,
+} from "./src/ai-operation-registration.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/server-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -8,13 +8,28 @@
   },
   "files": [
     "index.ts",
-    "src/module-host.ts"
+    "src/actor.ts",
+    "src/ai-operation-registration.ts",
+    "src/audit-port.ts",
+    "src/jobs-port.ts",
+    "src/module-host.ts",
+    "src/namespace.ts",
+    "src/request-context.ts",
+    "src/role-preset.ts",
+    "src/route-definition.ts",
+    "src/search-provider-port.ts",
+    "src/storage-port.ts",
+    "src/task-registration.ts",
+    "src/tool-registration.ts",
+    "src/tool-host-port.ts"
   ],
   "scripts": {
+    "test": "bun test",
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "dependencies": {
-    "@southwind-ai/jobs": "0.1.1"
+    "@southwind-ai/jobs": "0.1.2",
+    "@southwind-ai/storage": "0.1.1"
   },
   "exports": {
     ".": "./index.ts"

package/src/actor.ts

@@ -0,0 +1,15 @@
+/**
+ * 当前操作者的只读视图，与 Server 现有 Actor 模型对齐。
+ *
+ * 视图只暴露身份、角色与权限；凭据状态、数据范围令牌等宿主内部字段不下发。
+ * 运行时对象由宿主颁发，模块不得自行构造或修改。
+ */
+export interface ModuleActor {
+  readonly id: string;
+  readonly type: "anonymous" | "user" | "service";
+  readonly name: string;
+  readonly username?: string;
+  readonly displayName?: string;
+  readonly roleCodes: readonly string[];
+  readonly permissionKeys: readonly string[];
+}

package/src/ai-operation-registration.ts

@@ -0,0 +1,31 @@
+import type { ModuleActor } from "./actor.js";
+
+export type ModuleAiJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | ModuleAiJsonValue[]
+  | { [key: string]: ModuleAiJsonValue };
+
+export interface ModuleAiOperationContext {
+  readonly actor: ModuleActor;
+  readonly requestId: string;
+}
+
+/**
+ * 业务模块只负责把类型化输入收敛为模型无关的指令和用户消息。
+ * Provider、Deployment、Secret、Execution Grant 与 Tool 授权均由宿主持有。
+ */
+export interface ModuleAiOperationPlan {
+  readonly instructions: string;
+  readonly userPrompt: string;
+}
+
+export interface ModuleAiOperationHandlerRegistration {
+  readonly operationKey: string;
+  prepare(
+    input: ModuleAiJsonValue,
+    context: ModuleAiOperationContext,
+  ): Promise<ModuleAiOperationPlan> | ModuleAiOperationPlan;
+}

package/src/audit-port.ts

@@ -0,0 +1,22 @@
+/**
+ * 模块审计事件的受控写入入口。
+ *
+ * 只允许 emit 本模块 Manifest `auditActions` 已注册的动作；越权动作在调用时抛错。
+ * 事件由宿主补齐 Actor、RequestId 与时间戳并写入统一 Audit Sink。
+ */
+export interface ModuleAuditTarget {
+  readonly type: string;
+  readonly id?: string;
+  readonly label?: string;
+}
+
+export interface ModuleAuditEmitInput {
+  readonly target?: ModuleAuditTarget;
+  readonly metadata?: Record<string, unknown>;
+  /** 关键事件走宿主 Critical 写入策略（写入失败会抛出）。 */
+  readonly critical?: boolean;
+}
+
+export interface ModuleAuditEmitter {
+  emit(action: string, input?: ModuleAuditEmitInput): Promise<void>;
+}

package/src/jobs-port.ts

@@ -0,0 +1,24 @@
+/**
+ * 模块提交 Durable Job 的窄接口。
+ *
+ * 只能提交到本模块命名空间的 Handler；Queue 由宿主强制为模块命名空间，
+ * 提交人由宿主以当前 Actor 身份补齐，模块无法伪造。
+ */
+export interface ModuleJobSubmitInput {
+  readonly handlerKey: string;
+  readonly idempotencyKey: string;
+  readonly payload: Record<string, unknown>;
+  readonly priority?: number;
+  readonly maxAttempts?: number;
+  readonly timeoutSeconds?: number;
+  readonly availableAt?: Date;
+}
+
+export interface ModuleJobSubmitResult {
+  readonly jobId: string;
+  readonly created: boolean;
+}
+
+export interface ModuleJobSubmitter {
+  submit(input: ModuleJobSubmitInput): Promise<ModuleJobSubmitResult>;
+}

package/src/module-host.ts

@@ -1,4 +1,10 @@
 import type { DurableHandlerDefinition } from "@southwind-ai/jobs";
+import type { ModuleAiOperationHandlerRegistration } from "./ai-operation-registration.js";
+import type { ModuleRolePreset } from "./role-preset.js";
+import type { ModuleRouteDefinition } from "./route-definition.js";
+import type { ModuleSearchProvider } from "./search-provider-port.js";
+import type { ModuleTaskHandlerRegistration } from "./task-registration.js";
+import type { ModuleToolHandlerRegistration } from "./tool-registration.js";
 
 export interface ModuleUploadPolicy {
   purpose: string;
@@ -10,20 +16,54 @@ export interface ModuleUploadPolicy {
 }
 
 /**
- * 模块作用域 Host。注册的任务 Key 与上传用途必须使用初始化器模块名作为命名空间。
+ * 模块作用域 Host。注册的所有 Key（上传用途、任务、工具、角色预设、Provider）
+ * 必须使用初始化器模块名作为命名空间，越界或重复注册在 Server 监听前抛错。
+ *
+ * 模块只获得受限 Port（Guarded Route、Actor 视图、Audit、Durable Submit、
+ * 受限 Upload/BlobRead）；Worker 与 Repository 始终由宿主持有。
  */
 export interface ModuleHost {
   readonly moduleName: string;
   registerUploadPolicy(policy: ModuleUploadPolicy): void;
   registerDurableHandler<T>(definition: DurableHandlerDefinition<T>): void;
+  /** 注册 Guarded API 路由；须与 Manifest `apiPermissions` 声明一致。 */
+  registerRoutes(routes: readonly ModuleRouteDefinition[]): void;
+  /** 注册 Manifest `tasks` 已声明定时任务的执行体。 */
+  registerTaskHandlers(
+    registrations: readonly ModuleTaskHandlerRegistration[],
+  ): void;
+  /** 注册 Manifest `tools` 已声明 Agent Tool 的执行体。 */
+  registerToolHandlers(
+    registrations: readonly ModuleToolHandlerRegistration[],
+  ): void;
+  /** 注册 Manifest `aiOperations` 已声明的模型无关 Operation 执行计划。 */
+  registerAiOperationHandlers(
+    registrations: readonly ModuleAiOperationHandlerRegistration[],
+  ): void;
+  /** 注册角色预设；permissionKeys 须属于本模块 Manifest 权限声明。 */
+  registerRolePresets(presets: readonly ModuleRolePreset[]): void;
+  /** 注册 Manifest `providers` 已声明的搜索 Provider。 */
+  registerSearchProviders(providers: readonly ModuleSearchProvider[]): void;
 }
 
 /**
  * 已安装模块的 Server 初始化入口。
  *
  * 初始化器在 Storage 与 Durable Job 运行时创建前顺序执行；这里只注册定义，不启动 Worker。
+ * 路由、任务、工具与 Provider 的实现体可延迟绑定宿主运行时创建的服务。
  */
 export interface ModuleInitializer {
   readonly moduleName: string;
   initialize(host: ModuleHost): Promise<void> | void;
 }
+
+/**
+ * 可安装业务模块的完整 Server 契约。
+ *
+ * Manifest 与 setup 必须由同一安装单元贡献，避免宿主分别维护声明工厂和初始化器。
+ * TManifest 由能力目录包提供，SDK 因而不依赖具体 Manifest 实现。
+ */
+export interface InstallableServerModule<TManifest> {
+  readonly manifest: TManifest;
+  setup(host: ModuleHost): Promise<void> | void;
+}

package/src/namespace.ts

@@ -0,0 +1,13 @@
+/**
+ * 模块命名空间约束：注册的 Key 必须等于模块名，或以 `<moduleName>.` 开头。
+ * 宿主在所有注册入口统一调用，越界注册在 Server 监听前抛错。
+ */
+export function requireModuleNamespace(
+  kind: string,
+  value: string,
+  moduleName: string,
+): void {
+  if (value !== moduleName && !value.startsWith(`${moduleName}.`)) {
+    throw new Error(`${kind}不属于模块 ${moduleName}：${value}`);
+  }
+}

package/src/request-context.ts

@@ -0,0 +1,21 @@
+import type { ModuleActor } from "./actor.js";
+import type { ModuleAuditEmitter } from "./audit-port.js";
+import type { ModuleJobSubmitter } from "./jobs-port.js";
+import type { ModuleStoragePort } from "./storage-port.js";
+
+/**
+ * 模块路由 Handler 的受限请求上下文。
+ *
+ * 不暴露 Elysia 内部对象、数据库连接或任何 Repository；
+ * 模块只能经由 Actor 视图与受限 Port（Audit / Jobs / Storage）与平台交互。
+ */
+export interface ModuleRequestContext {
+  readonly requestId: string;
+  readonly actor: ModuleActor;
+  readonly params: Record<string, string | undefined>;
+  readonly query: Record<string, string | undefined>;
+  readonly body?: unknown;
+  readonly audit: ModuleAuditEmitter;
+  readonly jobs: ModuleJobSubmitter;
+  readonly storage: ModuleStoragePort;
+}

package/src/role-preset.ts

@@ -0,0 +1,18 @@
+/**
+ * 模块贡献的角色预设。
+ *
+ * `key` 作为角色 Code，必须使用模块命名空间；`permissionKeys` 必须全部属于
+ * 本模块 Manifest `permissions` 声明（宿主在启动时校验）。预设随内置角色一起
+ * 同步入库：不存在则创建，权限或菜单漂移则收敛，不改变 4 个内置角色语义。
+ */
+export interface ModuleRolePreset {
+  readonly key: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly dataScope?:
+    | "all"
+    | "department"
+    | "department-and-children"
+    | "self";
+  readonly permissionKeys: readonly string[];
+}

package/src/route-definition.ts

@@ -0,0 +1,26 @@
+import type { ModuleRequestContext } from "./request-context.js";
+
+export type ModuleRouteMethod = "GET" | "POST" | "PUT" | "DELETE";
+
+export type ModuleRouteHandler = (
+  context: ModuleRequestContext,
+) => Promise<unknown> | unknown;
+
+/**
+ * 模块贡献的 API 路由定义。
+ *
+ * `method` + `path` 必须与本模块 Manifest `apiPermissions` 中的声明一致
+ * （path 含 `/api` 前缀）；宿主据此绑定 Guard（权限 / Feature / License），
+ * 无需模块手工接线。`permissionKey` 必须与 Manifest 绑定一致并属于本模块命名空间。
+ *
+ * 声明 `auditAction` 时，宿主在 Handler 成功返回后自动写入一条该动作的审计事件；
+ * 动作必须是本模块 Manifest `auditActions` 已注册的动作。
+ */
+export interface ModuleRouteDefinition {
+  readonly method: ModuleRouteMethod;
+  readonly path: string;
+  readonly permissionKey: string;
+  readonly featureKey?: string;
+  readonly auditAction?: string;
+  readonly handler: ModuleRouteHandler;
+}

package/src/search-provider-port.ts

@@ -0,0 +1,48 @@
+import type { ModuleActor } from "./actor.js";
+
+export interface ModuleSearchQuery {
+  readonly text: string;
+  readonly limit: number;
+  readonly cursor?: string;
+  readonly signal: AbortSignal;
+}
+
+export interface ModuleSearchContext {
+  readonly actor: ModuleActor;
+  readonly requestId: string;
+}
+
+export interface ModuleSearchHit {
+  readonly id: string;
+  readonly resourceType: string;
+  readonly maskedTitle: string;
+  readonly maskedExcerpt?: string;
+  readonly score?: number;
+}
+
+export interface ModuleSearchPage {
+  readonly hits: ModuleSearchHit[];
+  readonly nextCursor?: string;
+}
+
+export interface ModuleSearchHealth {
+  readonly status: "healthy" | "degraded" | "unavailable";
+  readonly checkedAt: string;
+  readonly message?: string;
+}
+
+/**
+ * 模块搜索 Provider。
+ *
+ * `key` 必须在本模块 Manifest `providers` 中声明；返回的标题与摘要必须是
+ * 已脱敏文本，明文访问与导出由目标资源与治理导出走各自 Guard。
+ */
+export interface ModuleSearchProvider {
+  readonly key: string;
+  readonly providerVersion: string;
+  search(
+    query: ModuleSearchQuery,
+    context: ModuleSearchContext,
+  ): Promise<ModuleSearchPage>;
+  health(signal: AbortSignal): Promise<ModuleSearchHealth>;
+}

package/src/storage-port.ts

@@ -0,0 +1,25 @@
+import type { OpenedFile, UploadSession } from "@southwind-ai/storage";
+
+export interface ModuleUploadSessionInput {
+  readonly purpose: string;
+  readonly filename: string;
+  readonly mimeType: string;
+  readonly expectedByteSize: number;
+  readonly expectedSha256?: string;
+  readonly fileExpiresAt?: Date;
+}
+
+/**
+ * 模块受限 Upload / BlobRead Port。
+ *
+ * - `createUploadSession` 的 purpose 必须是本模块经 Host 注册的 Upload Policy，
+ *   跨模块或平台用途一律拒绝；Owner 由宿主以当前 Actor 身份补齐。
+ * - `openFile` 走 FileService 的 Owner 约束，且文件用途必须属于本模块。
+ * - `openPublicFile` 走 FileService 的 Purpose 约束，用途同样必须属于本模块。
+ * - 模块不允许直接接触 BlobStore 或 Upload Repository。
+ */
+export interface ModuleStoragePort {
+  createUploadSession(input: ModuleUploadSessionInput): Promise<UploadSession>;
+  openFile(fileId: string): Promise<OpenedFile>;
+  openPublicFile(fileId: string, purpose: string): Promise<OpenedFile>;
+}

package/src/task-registration.ts

@@ -0,0 +1,18 @@
+export type ModuleTaskResult = Record<string, unknown> | void;
+
+export type ModuleTaskHandler = () =>
+  | Promise<ModuleTaskResult>
+  | ModuleTaskResult;
+
+/**
+ * 模块定时任务的 Handler 注册。
+ *
+ * `taskKey` 必须在本模块 Manifest `tasks` 中声明；调度元数据（间隔、重试、
+ * Feature、权限）一律以 Manifest 为准，这里只提供执行体。
+ */
+export interface ModuleTaskHandlerRegistration {
+  readonly taskKey: string;
+  readonly handler: ModuleTaskHandler;
+  /** 判断执行结果是否为空转（用于调度指标统计），与平台任务语义一致。 */
+  readonly isIdleResult?: (value: ModuleTaskResult) => boolean;
+}

package/src/tool-host-port.ts

@@ -0,0 +1,22 @@
+import type { ModuleAiJsonValue } from "./ai-operation-registration.js";
+
+export interface ModuleAgentToolInvocation {
+  readonly runId: string;
+  readonly toolCallId: string;
+  readonly toolKey: string;
+  readonly arguments: Readonly<Record<string, ModuleAiJsonValue>>;
+}
+
+export interface ModuleAgentToolResult {
+  readonly value: ModuleAiJsonValue;
+}
+
+/**
+ * 宿主创建并绑定 Operation、Actor 与 Scope 的受限 Tool Host Port。
+ * 调用方不能传 Permission、Feature、License 或数据范围作为授权事实。
+ */
+export interface ModuleAgentToolHostPort {
+  execute(
+    invocation: ModuleAgentToolInvocation,
+  ): Promise<ModuleAgentToolResult>;
+}

package/src/tool-registration.ts

@@ -0,0 +1,29 @@
+import type { ModuleActor } from "./actor.js";
+
+export interface ModuleToolContext {
+  readonly actor: ModuleActor;
+  readonly requestId: string;
+}
+
+export interface ModuleToolResult {
+  readonly items: unknown[];
+  readonly total: number;
+  readonly page: number;
+  readonly pageSize: number;
+}
+
+/**
+ * 模块 Agent Tool 的 Handler 注册。
+ *
+ * `toolKey` 必须在本模块 Manifest `tools` 中声明；Guard（权限 / Feature /
+ * 数据范围）由宿主在 Agent 路由层统一执行。`scopeMode: "request"` 的 Handler
+ * 只会在持有服务端数据范围上下文的 Actor 下执行。
+ */
+export interface ModuleToolHandlerRegistration {
+  readonly toolKey: string;
+  readonly scopeMode: "platform" | "request";
+  execute(
+    query: Record<string, string | undefined>,
+    context: ModuleToolContext,
+  ): Promise<ModuleToolResult> | ModuleToolResult;
+}