@ai-zen/agents-sdk 0.2.0-alpha.2

package/dist/runtime/createModel.js

@@ -0,0 +1,28 @@
+import { OpenAI, ChatGPT } from "@ai-zen/agents-core";
+/**
+ * 模型工厂 — 根据 modelId 和 config 构建 Core ChatCompletionModel。
+ *
+ * 属于独立的 runtime 子层，不依赖 capabilities/ 或其他模块。
+ * 通过 Provider 实例获取 AppConfig 后调用。
+ *
+ * 改为同步版本，使用 endp​oint.chatCompletionSync() 避免不必要的 async。
+ */
+export function createModel(config, modelId) {
+    const modelConfig = config.models.find((m) => m.id === modelId);
+    if (!modelConfig)
+        throw new Error(`模型 "${modelId}" 不存在`);
+    const endpointConfig = config.endpoints.find((e) => e.id === modelConfig.endpointId);
+    if (!endpointConfig)
+        throw new Error(`端点 "${modelConfig.endpointId}" 未配置`);
+    const endpoint = new OpenAI({
+        openai_endpoint: endpointConfig.baseUrl,
+        api_key: endpointConfig.apiKey,
+    });
+    // 发送给 API 的模型名：modelName > id
+    const apiModelName = modelConfig.modelName || modelConfig.id;
+    const model = new ChatGPT({
+        model_config: modelConfig.defaultParams,
+        request_config: endpoint.chatCompletionSync(apiModelName),
+    });
+    return model;
+}

package/dist/shared/EntityRepository.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 通用实体仓储 — 对磁盘 JSON 文件的 CRUD 操作。
+ *
+ * 约定：
+ *   - 每个实体一个 JSON 文件，文件名 = `${id}.json`
+ *   - 目录不存在时自动创建
+ *   - 解析失败的文件会被跳过（list 时）
+ */
+export declare class EntityRepository<T extends {
+    id: string;
+}> {
+    private dir;
+    constructor(dir: string);
+    /** 获取实体的文件路径 */
+    protected path(id: string): string;
+    /** 列出目录下所有实体（跳过解析失败的文件） */
+    list(): T[];
+    /** 读取单个实体，不存在返回 null */
+    read(id: string): T | null;
+    /** 写入实体（创建或更新） */
+    write(entity: T): void;
+    /** 删除实体，不存在时不抛异常 */
+    delete(id: string): void;
+}

package/dist/shared/EntityRepository.js

@@ -0,0 +1,62 @@
+import { readFileSync, writeFileSync, existsSync, unlinkSync, readdirSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * 通用实体仓储 — 对磁盘 JSON 文件的 CRUD 操作。
+ *
+ * 约定：
+ *   - 每个实体一个 JSON 文件，文件名 = `${id}.json`
+ *   - 目录不存在时自动创建
+ *   - 解析失败的文件会被跳过（list 时）
+ */
+export class EntityRepository {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    /** 获取实体的文件路径 */
+    path(id) {
+        return join(this.dir, `${id}.json`);
+    }
+    /** 列出目录下所有实体（跳过解析失败的文件） */
+    list() {
+        if (!existsSync(this.dir))
+            return [];
+        const ids = readdirSync(this.dir)
+            .filter((f) => f.endsWith(".json"))
+            .map((f) => f.replace(/\.json$/, ""));
+        const entities = [];
+        for (const id of ids) {
+            const entity = this.read(id);
+            if (entity)
+                entities.push(entity);
+        }
+        return entities;
+    }
+    /** 读取单个实体，不存在返回 null */
+    read(id) {
+        const p = this.path(id);
+        if (!existsSync(p))
+            return null;
+        try {
+            const raw = readFileSync(p, "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 写入实体（创建或更新） */
+    write(entity) {
+        if (!existsSync(this.dir)) {
+            mkdirSync(this.dir, { recursive: true });
+        }
+        writeFileSync(this.path(entity.id), JSON.stringify(entity, null, 2), "utf-8");
+    }
+    /** 删除实体，不存在时不抛异常 */
+    delete(id) {
+        const p = this.path(id);
+        if (existsSync(p)) {
+            unlinkSync(p);
+        }
+    }
+}

package/dist/shared/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SDK 统一错误模型。
+ * code 为机器可读错误码（如 "CONFIG_READ_FAILED"），message 为人可读描述。
+ */
+export declare class SdkError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, cause?: Error);
+}

package/dist/shared/errors.js

@@ -0,0 +1,15 @@
+/**
+ * SDK 统一错误模型。
+ * code 为机器可读错误码（如 "CONFIG_READ_FAILED"），message 为人可读描述。
+ */
+export class SdkError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message);
+        this.name = "SdkError";
+        this.code = code;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}

package/dist/shared/logger.d.ts

@@ -0,0 +1,10 @@
+export interface LogFunctions {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+export type Logger = LogFunctions;
+/**
+ * 创建可注入的 Logger，默认使用 console。
+ */
+export declare function createLogger(log?: Partial<LogFunctions>): Logger;

package/dist/shared/logger.js

@@ -0,0 +1,10 @@
+/**
+ * 创建可注入的 Logger，默认使用 console。
+ */
+export function createLogger(log) {
+    return {
+        info: log?.info ?? console.log,
+        warn: log?.warn ?? console.warn,
+        error: log?.error ?? console.error,
+    };
+}

package/dist/types/index.d.ts

@@ -0,0 +1,178 @@
+import type { AgentNS } from "@ai-zen/agents-core";
+/** 单维度权限策略：allow 或 deny 互斥 */
+export type PermissionPolicy = {
+    allow: string[];
+} | {
+    deny: string[];
+};
+/** Agent 四维度权限 */
+export interface AgentPermissions {
+    tools?: PermissionPolicy;
+    skills?: PermissionPolicy;
+    mcps?: PermissionPolicy;
+    subagents?: PermissionPolicy;
+}
+/** API 端点 */
+export interface Endpoint {
+    id: string;
+    name: string;
+    baseUrl: string;
+    apiKey: string;
+    description?: string;
+}
+/** 模型配置，绑定一个 Endpoint */
+export interface Model {
+    id: string;
+    name: string;
+    endpointId: string;
+    modelName?: string;
+    maxContextTokens: number;
+    maxContextChars?: number;
+    defaultParams?: Record<string, unknown>;
+    description?: string;
+    version?: number;
+}
+/** Agent 定义，有 function 字段时为 SubAgent */
+export interface AgentDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    messages: AgentNS.Message[];
+    modelId?: string;
+    permissions?: AgentPermissions;
+    function?: AgentNS.FunctionDefine;
+    createdAt: string;
+    updatedAt: string;
+    version?: number;
+}
+/** 对话记录 */
+export interface Conversation {
+    id: string;
+    agentId: string;
+    modelId: string;
+    messages: AgentNS.Message[];
+    lastPromptTokens?: number;
+    cwd?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** 当前会话草稿 */
+export interface Draft {
+    conversationId?: string;
+    agentId: string;
+    modelId: string;
+    messages: AgentNS.Message[];
+    cwd?: string;
+    updatedAt: string;
+}
+/** 图片生成模型配置 */
+export interface ImageModel {
+    id: string;
+    name: string;
+    endpointId: string;
+    modelName: string;
+    description?: string;
+    defaultSize?: string;
+    defaultQuality?: string;
+    version?: number;
+}
+/** config.json 结构 */
+export interface AppConfig {
+    defaultModel?: string;
+    endpoints: Endpoint[];
+    models: Model[];
+    /** 图片生成模型列表 */
+    imageModels?: ImageModel[];
+    /** 默认图片生成模型 ID */
+    defaultImageModel?: string;
+    /** 默认 Agent ID（CLI/Desktop 使用） */
+    defaultAgent?: string;
+    /** 默认迁移模型 ID */
+    defaultMigrationModel?: string;
+}
+/** MCP 连接状态 */
+export type McpConnectionState = "disconnected" | "connecting" | "connected" | "error";
+/** MCP 服务器配置（含 CLI/Desktop 需要的额外字段） */
+export interface McpServerConfig {
+    id: string;
+    name: string;
+    transport: "stdio" | "http" | "sse";
+    /** 是否启用 */
+    enabled?: boolean;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    oauth?: {
+        authorizationUrl: string;
+        tokenUrl: string;
+        clientId: string;
+        clientSecret?: string;
+        scope?: string;
+    };
+}
+/**
+ * MCP 底层传输适配器（已废弃）。
+ *
+ * 现在由 @modelcontextprotocol/sdk 内置的 StdioClientTransport 和
+ * StreamableHTTPClientTransport 实现，不再需要外部注入。
+ *
+ * McpConnectionManager 内部使用官方 SDK 的 Transport 接口，
+ * 上层无需关心 transport 实现细节。
+ *
+ * @deprecated 改用 @modelcontextprotocol/sdk 的 Transport
+ */
+/** 图标（MCP 规范 §Icons） */
+export interface McpIcon {
+    src: string;
+    mimeType?: string;
+    sizes?: string[];
+    theme?: "light" | "dark";
+}
+/** 注解（MCP 规范 §Annotations） */
+export interface McpAnnotations {
+    audience?: ("user" | "assistant")[];
+    priority?: number;
+    lastModified?: string;
+}
+/** load_mcp 成功后返回的工具/资源/提示清单 */
+export interface McpServerManifest {
+    tools: McpToolDef[];
+    resources: McpResourceDef[];
+    prompts?: McpPromptDef[];
+}
+/** 工具定义（MCP 规范 §Tools） */
+export interface McpToolDef {
+    name: string;
+    title?: string;
+    description: string;
+    icons?: McpIcon[];
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: McpAnnotations;
+    execution?: {
+        taskSupport?: "forbidden" | "optional" | "required";
+    };
+}
+/** 资源定义（MCP 规范 §Resources） */
+export interface McpResourceDef {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+    size?: number;
+    icons?: McpIcon[];
+    annotations?: McpAnnotations;
+}
+/** 提示模板定义（MCP 规范 §Prompts） */
+export interface McpPromptDef {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments?: {
+        name: string;
+        description?: string;
+        required?: boolean;
+    }[];
+}

package/dist/types/index.js

@@ -0,0 +1,5 @@
+// ============================================================
+// 以下类型均为暂时约定，以后续实际设计为准。
+// 来源：docs/sdk-design.md §1-§3
+// ============================================================
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@ai-zen/agents-sdk",
+  "version": "0.2.0-alpha.2",
+  "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "keywords": [
+    "ai",
+    "agent",
+    "sdk",
+    "llm",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dayjs": "^1.11.21",
+    "@ai-zen/agents-core": "3.0.0-alpha.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "dotenv": "^17.4.2",
+    "prettier": "^3.9.5",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.1.9"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "clean": "rimraf ./dist",
+    "prebuild": "npm run clean",
+    "build": "tsc",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "pretest": "tsc --noEmit",
+    "test": "vitest run",
+    "test:integration": "npm run pretest && vitest run --config vitest.integration.config.ts",
+    "test:e2e": "npm run pretest && vitest run --config vitest.e2e.config.ts",
+    "test:all": "npm run pretest && vitest run && vitest run --config vitest.integration.config.ts && vitest run --config vitest.e2e.config.ts"
+  }
+}