@ai-zen/agents-sdk 0.12.0 → 1.0.0-alpha.1

package/dist/types/index.d.ts

@@ -26,13 +26,27 @@ export interface Model {
     name: string;
     endpointId: string;
     modelName?: string;
+    /**
+     * 任务迁移（交接）触发阈值 —— **不是**模型的真实上下文窗口。
+     *
+     * AutoMigratePlugin 不估算、不学习：只在 API 响应返回后，用 `usage.prompt_tokens`
+     * 与该值比较，超过即触发交接迁移。建议取模型真实窗口的约 25%，为 response 留出空间。
+     */
     maxContextTokens: number;
+    /** 旧版字符数阈值（兼容迁移） */
     maxContextChars?: number;
     defaultParams?: Record<string, unknown>;
     /** 是否支持图片输入（视觉模型）。看图工具（viewImage）仅对视觉模型启用；generateImage 是否返回图片内容块也据此判断 */
     vision?: boolean;
     description?: string;
     version?: number;
+    /**
+     * 是否用户自定义。
+     *
+     * 为 true 时 SDK 初始化不会用出厂定义替换该模型；缺省（或 false）视为出厂托管，
+     * 初始化时会与 DEFAULT_APP_CONFIG.models 同步（出厂清单为准）。
+     */
+    custom?: boolean;
 }
 /** Agent 定义，有 function 字段时为 SubAgent */
 export interface AgentDefinition {
@@ -64,6 +78,13 @@ export interface ImageModel {
     defaultSize?: string;
     defaultQuality?: string;
     version?: number;
+    /**
+     * 是否用户自定义。
+     *
+     * 为 true 时 SDK 初始化不会用出厂定义替换该模型；缺省（或 false）视为出厂托管，
+     * 初始化时会与 DEFAULT_APP_CONFIG.imageModels 同步（出厂清单为准）。
+     */
+    custom?: boolean;
 }
 /** config.json 结构 */
 export interface AppConfig {
@@ -88,9 +109,9 @@ export interface AppConfig {
     maxToolOutput?: number;
 }
 /**
- * 工具环境 — Provider 在实例化内置工具时注入的环境信息。
+ * 工具环境 — Scope 的能力插件在实例化内置工具时注入的环境信息。
  *
- * cwd 是相对路径解析的基准（每个 Provider 对应一个工作目录）；
+ * cwd 是相对路径解析的基准（每个 Scope 对应一个工作目录）；
  * config 供需要模型/端点配置的工具（如 generateImage）使用。
  */
 export interface ToolEnv {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.12.0",
+  "version": "1.0.0-alpha.1",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,10 +16,10 @@
   "author": "LZQCN",
   "license": "MIT",
   "dependencies": {
-    "@ai-zen/agents-core": "^4.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
-    "openai": "^7.5.0"
+    "openai": "^7.5.0",
+    "@ai-zen/agents-core": "^4.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",

package/dist/runtime/Provider.d.ts

@@ -1,119 +0,0 @@
-import type { Tool } from "@ai-zen/agents-core";
-import type { AppConfig, AgentDefinition, McpServerConfig, ToolEnv } from "../types/index.js";
-import type { SkillInfo } from "../capabilities/discovery/skills.js";
-import { McpConnectionManager } from "./McpConnectionManager.js";
-/**
- * 能力过滤系统的公共类型。
- * FilterOutput 由 filter() 产出，由 instantiate() 消费。
- */
-export interface FilterOutput {
-    tools: string[];
-    subagents: string[];
-    skills: string[];
-    mcps: string[];
-}
-/**
- * 排除项黑名单（优先级高于 permissions）。
- * 与 permissions 四维对称，用于安全预过滤。
- */
-export interface ExcludeOptions {
-    tools?: string[];
-    skills?: string[];
-    mcps?: string[];
-    subagents?: string[];
-}
-/** filter / buildTools 的过滤选项 */
-export interface FilterOptions {
-    /** 排除项黑名单（优先级高于 permissions） */
-    exclude?: ExcludeOptions;
-}
-/**
- * Provider — 全局上下文实例 + 能力注册表。
- *
- * Provider 是 SDK 的全局单例（按需创建），持有：
- *   - 应用配置（端点、模型等）
- *   - 文件系统路径（Agent 目录、Skill 目录等）
- *   - 全局能力注册表（内置工具、用户工具、SubAgent、Skill、MCP）
- *   - MCP 连接管理器
- *
- * 创建方式：
- * ```ts
- * // 推荐：一步完成构造 + 能力发现
- * const provider = await Provider.create({ ... });
- *
- * // 仅构造（能力需后续加载）
- * const provider = new Provider({ ... });
- * await provider.init();
- * ```
- *
- * 设计原则：
- *   - Provider 实例一旦创建不可变（路径、配置等不变），refresh 时重新发现能力
- *   - 各层不直接 import 散装函数，而是通过 Provider 实例获取
- */
-export declare class Provider {
-    /** 应用配置（端点、模型等） */
-    readonly config: AppConfig;
-    /** 当前工作目录 — 相对路径解析基准，也是 ToolEnv.cwd 的来源 */
-    readonly cwd: string;
-    /** 工具环境 — 实例化内置工具时注入 */
-    readonly env: ToolEnv;
-    readonly agentsDir: string;
-    readonly subAgentsPaths: string[];
-    readonly skillsPaths: string[];
-    readonly toolsPaths: string[];
-    readonly mcpPaths: string[];
-    builtinTools: Tool[];
-    userTools: Tool[];
-    subagents: AgentDefinition[];
-    /** 完整 SkillInfo，含 subAgent 标记，可据此区分枚举 */
-    skills: SkillInfo[];
-    /** 完整 MCP 服务器配置 */
-    mcps: McpServerConfig[];
-    readonly mcpManager: McpConnectionManager | undefined;
-    constructor(options: {
-        config: AppConfig;
-        agentsDir: string;
-        subAgentsPaths?: string[];
-        skillsPaths?: string[];
-        toolsPaths?: string[];
-        mcpPaths?: string[];
-        /** 当前工作目录，默认 process.cwd() */
-        cwd?: string;
-    });
-    /**
-     * 异步创建 Provider，一步完成构造 + 全局能力发现。
-     */
-    static create(options: {
-        config: AppConfig;
-        agentsDir: string;
-        subAgentsPaths?: string[];
-        skillsPaths?: string[];
-        toolsPaths?: string[];
-        mcpPaths?: string[];
-        /** 当前工作目录，默认 process.cwd() */
-        cwd?: string;
-    }): Promise<Provider>;
-    /**
-     * 初始化：执行全局能力发现。
-     */
-    init(): Promise<void>;
-    /**
-     * 按权限过滤候选集，返回过滤后的名称列表。
-     * 纯名称操作（安全预过滤 + 权限过滤），不涉及 Tool 实例化。
-     */
-    filter(definition: AgentDefinition, options?: FilterOptions): FilterOutput;
-    /**
-     * 快捷方法：filter + instantiate 一步完成。
-     */
-    buildTools(definition: AgentDefinition, options?: FilterOptions): Tool[];
-    /**
-     * 将过滤后的名称列表实例化为 Tool 数组。
-     */
-    instantiate(filtered: FilterOutput): Tool[];
-    /**
-     * 重新执行全局发现（重新扫描文件系统）。
-     */
-    refresh(options?: {
-        silent?: boolean;
-    }): Promise<void>;
-}

package/dist/runtime/Provider.js

@@ -1,218 +0,0 @@
-import { McpConnectionManager } from "./McpConnectionManager.js";
-import { PermissionEvaluator } from "../capabilities/PermissionEvaluator.js";
-import { createLoadSkillTool, createCallSkillSubAgentTool } from "../capabilities/implements/skillTools.js";
-import { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from "../capabilities/implements/mcpTools.js";
-import { createSubAgentTool } from "../capabilities/implements/subAgentTools.js";
-import { discoverBuiltinTools } from "../capabilities/discovery/builtin.js";
-import { discoverSubAgents } from "../capabilities/discovery/subagents.js";
-import { discoverSkills } from "../capabilities/discovery/skills.js";
-import { discoverMcpServers } from "../capabilities/discovery/mcp.js";
-import { discoverUserTools } from "../capabilities/discovery/usertools.js";
-/**
- * Provider — 全局上下文实例 + 能力注册表。
- *
- * Provider 是 SDK 的全局单例（按需创建），持有：
- *   - 应用配置（端点、模型等）
- *   - 文件系统路径（Agent 目录、Skill 目录等）
- *   - 全局能力注册表（内置工具、用户工具、SubAgent、Skill、MCP）
- *   - MCP 连接管理器
- *
- * 创建方式：
- * ```ts
- * // 推荐：一步完成构造 + 能力发现
- * const provider = await Provider.create({ ... });
- *
- * // 仅构造（能力需后续加载）
- * const provider = new Provider({ ... });
- * await provider.init();
- * ```
- *
- * 设计原则：
- *   - Provider 实例一旦创建不可变（路径、配置等不变），refresh 时重新发现能力
- *   - 各层不直接 import 散装函数，而是通过 Provider 实例获取
- */
-export class Provider {
-    /** 应用配置（端点、模型等） */
-    config;
-    /** 当前工作目录 — 相对路径解析基准，也是 ToolEnv.cwd 的来源 */
-    cwd;
-    /** 工具环境 — 实例化内置工具时注入 */
-    env;
-    // ---- 路径 ----
-    agentsDir;
-    subAgentsPaths;
-    skillsPaths;
-    toolsPaths;
-    mcpPaths;
-    // ---- 全局候选集（发现一次，全局复用）----
-    builtinTools;
-    userTools;
-    subagents;
-    /** 完整 SkillInfo，含 subAgent 标记，可据此区分枚举 */
-    skills;
-    /** 完整 MCP 服务器配置 */
-    mcps;
-    // ---- MCP ----
-    mcpManager;
-    constructor(options) {
-        this.config = options.config;
-        this.cwd = options.cwd ?? process.cwd();
-        this.env = { cwd: this.cwd, config: this.config };
-        this.agentsDir = options.agentsDir;
-        this.subAgentsPaths = options.subAgentsPaths ?? [];
-        this.skillsPaths = options.skillsPaths ?? [];
-        this.toolsPaths = options.toolsPaths ?? [];
-        this.mcpPaths = options.mcpPaths ?? [];
-        this.builtinTools = [];
-        this.userTools = [];
-        this.subagents = [];
-        this.skills = [];
-        this.mcps = [];
-        this.mcpManager = this.mcpPaths.length > 0 ? new McpConnectionManager() : undefined;
-    }
-    /**
-     * 异步创建 Provider，一步完成构造 + 全局能力发现。
-     */
-    static async create(options) {
-        const provider = new Provider(options);
-        await provider.init();
-        return provider;
-    }
-    /**
-     * 初始化：执行全局能力发现。
-     */
-    async init() {
-        await this.refresh();
-    }
-    // ==================================================================
-    // 能力过滤与实例化
-    // ==================================================================
-    /**
-     * 按权限过滤候选集，返回过滤后的名称列表。
-     * 纯名称操作（安全预过滤 + 权限过滤），不涉及 Tool 实例化。
-     */
-    filter(definition, options) {
-        const exclude = options?.exclude ?? {};
-        const excludeTools = new Set(exclude.tools ?? []);
-        const excludeSkills = new Set(exclude.skills ?? []);
-        const excludeMcps = new Set(exclude.mcps ?? []);
-        const excludeSubAgents = new Set(exclude.subagents ?? []);
-        const safeSubagents = excludeSubAgents.size === 0
-            ? this.subagents
-            : this.subagents.filter((def) => !excludeSubAgents.has(def.function?.name ?? ""));
-        const DYNAMIC_TOOL_NAMES = [
-            "load_skill",
-            "call_skill_sub_agent",
-            "load_mcp",
-            "call_mcp_tool",
-            "read_mcp_resource",
-        ];
-        const toolNames = [
-            ...this.builtinTools.map((t) => t.function.name),
-            ...this.userTools.map((t) => t.function.name),
-            ...DYNAMIC_TOOL_NAMES,
-        ].filter((name) => !excludeTools.has(name));
-        // 工具可用性过滤：调用候选工具的 isAvailable（直接透传完整 app config + agent definition）。
-        // 工具自行声明可用条件（如依赖图片模型配置、仅视觉模型可用），返回 false 则剔除。
-        const candidates = [...this.builtinTools, ...this.userTools];
-        for (let i = toolNames.length - 1; i >= 0; i--) {
-            const tool = candidates.find((t) => t.function.name === toolNames[i]);
-            const isAvailable = tool?.isAvailable;
-            if (isAvailable && !isAvailable(this.config, definition)) {
-                toolNames.splice(i, 1);
-            }
-        }
-        const evaluator = new PermissionEvaluator(definition.permissions);
-        const filtered = evaluator.filter({
-            tools: toolNames,
-            skills: this.skills
-                .filter((s) => !excludeSkills.has(s.id))
-                .map((s) => s.id),
-            mcps: this.mcps
-                .filter((m) => !excludeMcps.has(m.id))
-                .map((m) => m.id),
-            subagents: safeSubagents.map((d) => d.function.name),
-        });
-        return {
-            tools: filtered.tools,
-            subagents: filtered.subagents,
-            skills: filtered.skills,
-            mcps: filtered.mcps,
-        };
-    }
-    /**
-     * 快捷方法：filter + instantiate 一步完成。
-     */
-    buildTools(definition, options) {
-        return this.instantiate(this.filter(definition, options));
-    }
-    /**
-     * 将过滤后的名称列表实例化为 Tool 数组。
-     */
-    instantiate(filtered) {
-        const result = [];
-        const allowedToolNames = new Set(filtered.tools);
-        // 1. 内置 + 用户工具
-        for (const t of [...this.builtinTools, ...this.userTools]) {
-            if (allowedToolNames.has(t.function.name)) {
-                result.push(t);
-            }
-        }
-        // 2. 筛选候选项（保留完整信息，传给工具函数自行决定如何构建枚举）
-        const allowedSkillSet = new Set(filtered.skills);
-        const allowedMcpSet = new Set(filtered.mcps);
-        const filteredSkills = this.skills.filter((s) => allowedSkillSet.has(s.id));
-        const filteredMcps = this.mcps.filter((m) => allowedMcpSet.has(m.id));
-        // 3. 动态工具
-        if (allowedToolNames.has("load_skill") && filteredSkills.length > 0) {
-            result.push(createLoadSkillTool(this.skillsPaths, filteredSkills));
-        }
-        // call_skill_sub_agent：只要有支持子 Agent 的 skill 就注册
-        const hasSubAgentSkills = filteredSkills.some((s) => s.subAgent);
-        if (allowedToolNames.has("call_skill_sub_agent") && hasSubAgentSkills) {
-            result.push(createCallSkillSubAgentTool(this.skillsPaths, filteredSkills));
-        }
-        const mcpManager = this.mcpManager;
-        if (allowedToolNames.has("load_mcp") && mcpManager && filteredMcps.length > 0) {
-            result.push(createLoadMcpTool(mcpManager, filteredMcps));
-        }
-        if (allowedToolNames.has("call_mcp_tool") && mcpManager) {
-            result.push(createCallMcpTool(mcpManager));
-        }
-        if (allowedToolNames.has("read_mcp_resource") && mcpManager) {
-            result.push(createReadMcpResourceTool(mcpManager));
-        }
-        // 4. SubAgent
-        const allowedSubagentSet = new Set(filtered.subagents);
-        for (const def of this.subagents) {
-            if (!def.function || !allowedSubagentSet.has(def.function.name))
-                continue;
-            result.push(createSubAgentTool(def, this));
-        }
-        // 5. 去重
-        return dedupTools(result);
-    }
-    /**
-     * 重新执行全局发现（重新扫描文件系统）。
-     */
-    async refresh(options) {
-        const silent = options?.silent ?? false;
-        this.builtinTools = discoverBuiltinTools(this.env);
-        this.userTools = await discoverUserTools(this.toolsPaths, { silent });
-        this.subagents = await discoverSubAgents(this.subAgentsPaths);
-        this.skills = await discoverSkills(this.skillsPaths, { silent });
-        this.mcps = await discoverMcpServers(this.mcpPaths);
-    }
-}
-function dedupTools(tools) {
-    const seen = new Set();
-    const result = [];
-    for (let i = tools.length - 1; i >= 0; i--) {
-        const name = tools[i].function.name;
-        if (!seen.has(name)) {
-            seen.add(name);
-            result.unshift(tools[i]);
-        }
-    }
-    return result;
-}