@eoasmxd/freya-sdk 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eoasmxd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @eoasmxd/freya-sdk
+
+Freya 智能体系统的官方插件开发标准 SDK。本项目定义了 Freya 的核心扩展契约、插件生命周期接口及公共类型。
+
+## 安装
+
+如果你想开发第三方 Freya 插件，请在你的项目中引入本 SDK 作为开发依赖：
+
+```bash
+npm install @eoasmxd/freya-sdk --save-dev
+```
+
+## 核心契约
+
+本 SDK 导出了以下关键契约和接口：
+
+* `FreyaPlugin`：标准插件基类契约。
+* `LLMPlugin`：大语言模型提供商插件标准接口。
+* `ToolPlugin`：扩展工具（Tool）插件标准接口。
+
+## 快速上手
+
+下面是一个简单的工具插件模版：
+
+```typescript
+import { ToolPlugin, FreyaContext } from '@eoasmxd/freya-sdk';
+
+export class MyCustomTool implements ToolPlugin {
+  type = 'tool';
+
+  getId(): string {
+    return 'my-custom-tool';
+  }
+
+  async execute(context: FreyaContext, params: any): Promise<any> {
+    // 插件业务逻辑
+    return { result: 'Hello from custom tool!' };
+  }
+}
+```
+
+## 开源协议
+
+基于 [MIT License](LICENSE) 协议开源。

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types/plugin.js';
+export * from './types/context.js';
+export * from './types/config.js';
+export * from './types/llm.js';
+export * from './types/tool.js';
+export * from './types/channel.js';
+export * from './types/command.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './types/plugin.js';
+export * from './types/context.js';
+export * from './types/config.js';
+export * from './types/llm.js';
+export * from './types/tool.js';
+export * from './types/channel.js';
+export * from './types/command.js';

package/dist/types/channel.d.ts

@@ -0,0 +1,16 @@
+export interface ChannelAttachment {
+    type: 'image' | 'file';
+    mimeType: string;
+    url?: string;
+    base64?: string;
+    path?: string;
+}
+export interface ChannelMessage {
+    channelId: string;
+    userId: string;
+    messageId: string;
+    sessionId: string;
+    content: string;
+    attachments?: ChannelAttachment[];
+    connectionId?: string;
+}

package/dist/types/channel.js

@@ -0,0 +1 @@
+export {};

package/dist/types/command.d.ts

@@ -0,0 +1,13 @@
+import type { FreyaContext } from './context.js';
+export interface FreyaSubcommand {
+    name: string;
+    description: string;
+    usage?: string;
+}
+export interface FreyaCommand {
+    name: string;
+    description: string;
+    alias?: string[];
+    subcommands?: FreyaSubcommand[];
+    execute(args: string[], sessionId: string, ctx: FreyaContext, connectionId?: string): Promise<string | void>;
+}

package/dist/types/command.js

@@ -0,0 +1 @@
+export {};

package/dist/types/config.d.ts

@@ -0,0 +1,14 @@
+export interface ConfigFieldSchema {
+    key: string;
+    defaultValue?: any;
+    description: string;
+    type: 'string' | 'number' | 'boolean' | 'enum' | 'object' | 'array';
+    enumValues?: string[];
+    required?: boolean;
+    min?: number;
+    max?: number;
+    sensitive?: boolean;
+    category?: string;
+    uiHint?: 'text' | 'textarea' | 'password' | 'select' | 'slider';
+    children?: ConfigFieldSchema[];
+}

package/dist/types/config.js

@@ -0,0 +1 @@
+export {};

package/dist/types/context.d.ts

@@ -0,0 +1,29 @@
+import type { ILLMService } from './llm.js';
+export interface EventBus {
+    on(event: string, listener: (...args: any[]) => void): void;
+    off(event: string, listener: (...args: any[]) => void): void;
+    emit(event: string, ...args: any[]): void;
+}
+export interface Logger {
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    debug(message: string, ...args: any[]): void;
+}
+export interface FreyaPaths {
+    /** 程序物理安装根目录（只读代码与程序级静态资源区） */
+    appRoot: string;
+    /** 运行态主目录（用户个性化配置与持久化数据区，默认 ~/.freya） */
+    projectRoot: string;
+    /** 运行时数据持久化目录（~/.freya/data） */
+    dataDir: string;
+    /** 宿主与大模型交互隔离的文件读写沙箱（~/.freya/workspace） */
+    workspaceDir: string;
+}
+export interface FreyaContext {
+    eventBus: EventBus;
+    logger: Logger;
+    readonly config: Readonly<Record<string, any>>;
+    llm: ILLMService;
+    paths: FreyaPaths;
+}

package/dist/types/context.js

@@ -0,0 +1 @@
+export {};

package/dist/types/llm.d.ts

@@ -0,0 +1,49 @@
+import type { ChannelAttachment } from './channel.js';
+import type { ToolDefinition } from './tool.js';
+export interface LLMConsumptionContext {
+    ownerType: string;
+    ownerId: string;
+}
+export interface LLMOptions {
+    modelId?: string;
+    providerId?: string;
+    signal?: AbortSignal;
+    onChunk?: (text: string) => void;
+    attachments?: ChannelAttachment[];
+    modelParams?: Record<string, any>;
+    modelType?: 'default' | 'router' | 'image' | 'audio';
+    onModelSelected?: (providerId: string, modelId: string) => void;
+    billingContext?: LLMConsumptionContext;
+}
+export interface LLMPluginOptions extends LLMOptions {
+    modelId: string;
+    providerConfig: {
+        apiKey: string;
+        baseURL?: string;
+    };
+}
+export interface LLMToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+export interface LLMMessage {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    toolCalls?: LLMToolCall[];
+    attachments?: ChannelAttachment[];
+    toolCallId?: string;
+}
+export interface LLMTokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cachedPromptTokens?: number;
+}
+export interface ILLMService {
+    chat(messages: LLMMessage[], tools?: ToolDefinition[], options?: LLMOptions): Promise<{
+        message: LLMMessage;
+        usage?: LLMTokenUsage;
+    }>;
+    getContextWindow(modelId?: string): number;
+}

package/dist/types/llm.js

@@ -0,0 +1 @@
+export {};

package/dist/types/plugin.d.ts

@@ -0,0 +1,28 @@
+import type { FreyaContext } from './context.js';
+import type { FreyaCommand } from './command.js';
+import type { FreyaToolbox } from './tool.js';
+import type { LLMMessage, LLMPluginOptions, LLMTokenUsage } from './llm.js';
+import type { ToolDefinition } from './tool.js';
+export type PluginType = 'llm' | 'tool' | 'channel';
+export interface FreyaPlugin {
+    type: PluginType;
+    id?: string;
+    name?: string;
+    version?: string;
+    commands?: FreyaCommand[];
+    setup(ctx: FreyaContext): Promise<void>;
+    start?(ctx: FreyaContext): Promise<void>;
+    stop?(ctx: FreyaContext): Promise<void>;
+}
+export interface ChannelPlugin extends FreyaPlugin {
+}
+export interface ToolPlugin extends FreyaPlugin, FreyaToolbox {
+    type: 'tool';
+}
+export interface LLMPlugin extends FreyaPlugin {
+    providerTypes?: string[];
+    chat(messages: LLMMessage[], tools?: ToolDefinition[], options?: LLMPluginOptions): Promise<{
+        message: LLMMessage;
+        usage?: LLMTokenUsage;
+    }>;
+}

package/dist/types/plugin.js

@@ -0,0 +1 @@
+export {};

package/dist/types/tool.d.ts

@@ -0,0 +1,15 @@
+import type { FreyaContext } from './context.js';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: object;
+}
+export interface FreyaTool {
+    getDefinition(): ToolDefinition;
+    execute(args: Record<string, any>, ctx: FreyaContext): Promise<string>;
+}
+export interface FreyaToolbox {
+    getId(): string;
+    getTools(): FreyaTool[];
+    getInstructionPrompt?(): string;
+}

package/dist/types/tool.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@eoasmxd/freya-sdk",
+  "version": "0.1.2",
+  "private": false,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Freya 插件开发标准 SDK，定义所有插件扩展点接口与公共类型",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eoasmxd/freya.git",
+    "directory": "packages/sdk"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "build": "tsc -b --force",
+    "clean": "rm -rf dist"
+  }
+}