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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LZQCN
+
+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,100 @@
+# @ai-zen/agents-sdk
+
+AI-Zen SDK — 共享业务逻辑层，为 CLI 和 Desktop 提供统一的 Agent 运行时。开箱即用，包含预置厂商配置、默认 Agent 和 SubAgent。
+
+## 真相源
+
+**[`docs/sdk-design.md`](./docs/sdk-design.md)** 是本包的唯一设计真相源。所有实现必须与文档一致。
+## 架构
+
+```
+CLI ──┐
+      ├── @ai-zen/sdk ──┐
+Desktop ──┘              │
+                    LLM API
+```
+
+## 模块分层
+
+```
+types        ← 纯类型，零业务依赖
+config       ← 读写 config.json + 迁移 + 内存缓存 + 原子写入
+crud         ← 实体 CRUD（Endpoints / Models / Agents / Conversations / Draft）
+capabilities ← 能力发现与装配（内置 + 用户 + MCP + Skill + SubAgent）
+runtime      ← Provider + 模型工厂 + Agent 组装 + MCP 连接管理 + 任务迁移
+plugin       ← Agent 插件（autoMigrate、autoDraft、autoRefreshTools）
+shared       ← 日志、错误
+```
+
+依赖方向：`plugin → runtime → capabilities → crud → config → types`，上层依赖下层，反之不行。
+
+## 核心概念
+
+| 实体 | 说明 |
+|------|------|
+| **Provider** | 全局上下文，持有配置、路径、模型工厂、MCP 管理器 |
+| **Capabilities** | 全局能力注册表（发现 → 过滤 → 实例化） |
+| **SdkAgent** | 继承 Core Agent，携带 SDK 元数据，支持 `use()` 插件注册 |
+| **AgentPlugin** | 插件接口（`onInit`, `onBeforeSend`, `onAfterSend`, `onInnerLoopStart`, `onInnerLoopEnd`） |
+| **Endpoint** | API 端点（baseUrl + apiKey） |
+| **Model** | 模型配置，绑定 Endpoint |
+| **SubAgent** | 有 `function` 字段的 Agent，可被其他 Agent 作为工具调用 |
+| **Conversation** | 对话记录 |
+| **Draft** | 当前会话自动保存 |
+
+## 权限模型
+
+四维度各自独立，allow/deny 互斥，无命中即拒绝，权限即披露（deny 掉的项对 LLM 完全不可见）。
+
+```
+Agent.permissions
+  ├── tools:      { allow: string[] } | { deny: string[] }
+  ├── skills:     { allow: string[] } | { deny: string[] }
+  ├── mcps:       { allow: string[] } | { deny: string[] }
+  └── subagents:  { allow: string[] } | { deny: string[] }
+```
+
+## 消费模式
+
+```typescript
+const provider = new Provider({ config, ...paths });
+const agent = createAgent(provider, "my-agent");
+agent.use(new AutoMigratePlugin({ maxTokens, migrationAgent, onHandoff }));
+agent.use(new AutoDraftPlugin({ draftsDir, agentId, modelId }));
+agent.use(new AutoRefreshToolsPlugin());
+await agent.init();
+await agent.send("你好");
+```
+
+## 开发状态
+
+| 模块 | 状态 |
+|------|------|
+| `types` | ✅ 已实现 — 核心实体、权限模型、MCP 类型完整 |
+| `config` | ✅ 已实现 — ConfigManager + 出厂默认配置 + 一键 bootstrap |
+| `crud` | ✅ 已实现 — Agent / Conversation / Draft 完整 CRUD |
+| `capabilities` | ✅ 已实现 — 发现 + 权限过滤 + 安全预过滤 + 枚举披露 |
+| `runtime` | ✅ 已实现 — Provider、Capabilities、createAgent、MCP 连接管理、任务迁移 |
+| `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoDraftPlugin / AutoRefreshToolsPlugin |
+| `shared` | ✅ 已实现 — SdkError + 可注入 Logger |
+| 测试 | ✅ 378 个测试，46 个文件，全通过（含真实 API 聊天 e2e） |
+
+## 内置插件
+
+| 插件 | 说明 |
+|------|------|
+| `AutoMigratePlugin` | 上下文超限时自动触发任务迁移，生成交接文档，透明替换 Agent |
+| `AutoDraftPlugin` | 每次 `send()` 后自动保存当前消息历史到 draft 文件 |
+| `AutoRefreshToolsPlugin` | 每次 `send()` 前重新扫描文件系统，刷新工具列表 |
+
+## 设计原则
+
+参见项目根 [`GOAL.md`](../../GOAL.md)：
+
+1. 逻辑自洽
+2. 设计为先，文档为准
+3. 对称、统一
+4. 去除过度设计
+5. 奥卡姆剃刀
+6. 即时重构，保持分层
+7. 测试是基石

package/dist/capabilities/Capabilities.d.ts

@@ -0,0 +1,71 @@
+import type { Tool } from "@ai-zen/agents-core";
+import type { AgentDefinition, AgentPermissions, McpServerConfig } from "../types/index.js";
+import type { SkillInfo } from "./discovery/skills.js";
+import type { Provider } from "../runtime/Provider.js";
+/**
+ * 能力过滤系统的公共类型。
+ * FilterOutput 由 Capabilities.filter() 产出，由 Capabilities.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[];
+}
+/**
+ * Capabilities — 全局能力注册表。
+ *
+ * 职责：
+ *   1. 全局发现一次（扫描文件系统，收集所有完整候选）
+ *   2. 提供 filter(permissions) 按权限过滤
+ *   3. 提供 instantiate(filterOutput) 将过滤后的名称实例化为 Tool[]
+ *
+ * 设计原则：
+ *   - 发现结果全局共享，SubAgent 复用同一份候选集
+ *   - filter 是纯函数（名称匹配），可被任意 Agent 独立调用
+ *   - instantiate 是纯映射（名称→实例），不含业务逻辑
+ *   - 通过持有的 Provider 实例获取配置、路径、模型工厂等全局服务
+ */
+export declare class Capabilities {
+    /** Provider 全局上下文 */
+    readonly provider: Provider;
+    builtinInstances: Tool[];
+    userInstances: Tool[];
+    subagentDefs: AgentDefinition[];
+    /** 完整 SkillInfo，含 subAgent 标记，可据此区分枚举 */
+    skills: SkillInfo[];
+    /** 完整 MCP 服务器配置 */
+    mcps: McpServerConfig[];
+    constructor(provider: Provider);
+    /**
+     * 按权限过滤候选集，返回过滤后的名称列表。
+     * 纯名称操作（安全预过滤 + 权限过滤），不涉及 Tool 实例化。
+     */
+    filter(permissions: AgentPermissions, options?: {
+        exclude?: ExcludeOptions;
+    }): FilterOutput;
+    /**
+     * 快捷方法：filter + instantiate 一步完成。
+     */
+    buildTools(permissions: AgentPermissions, options?: {
+        exclude?: ExcludeOptions;
+    }): Tool[];
+    /**
+     * 将过滤后的名称列表实例化为 Tool 数组。
+     */
+    instantiate(filtered: FilterOutput): Tool[];
+    /**
+     * 重新执行全局发现（重新扫描文件系统）。
+     */
+    refresh(): void;
+}

package/dist/capabilities/Capabilities.js

@@ -0,0 +1,161 @@
+import { PermissionEvaluator } from "./PermissionEvaluator.js";
+import { createLoadSkillTool, createCallSkillSubAgentTool } from "./implements/skillTools.js";
+import { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from "./implements/mcpTools.js";
+import { createSubAgentTool } from "./implements/subAgentTools.js";
+import { discoverBuiltinTools } from "./discovery/builtin.js";
+import { discoverSubAgents } from "./discovery/subagents.js";
+import { discoverSkills } from "./discovery/skills.js";
+import { discoverMcpServers } from "./discovery/mcp.js";
+import { discoverUserTools } from "./discovery/usertools.js";
+/**
+ * Capabilities — 全局能力注册表。
+ *
+ * 职责：
+ *   1. 全局发现一次（扫描文件系统，收集所有完整候选）
+ *   2. 提供 filter(permissions) 按权限过滤
+ *   3. 提供 instantiate(filterOutput) 将过滤后的名称实例化为 Tool[]
+ *
+ * 设计原则：
+ *   - 发现结果全局共享，SubAgent 复用同一份候选集
+ *   - filter 是纯函数（名称匹配），可被任意 Agent 独立调用
+ *   - instantiate 是纯映射（名称→实例），不含业务逻辑
+ *   - 通过持有的 Provider 实例获取配置、路径、模型工厂等全局服务
+ */
+export class Capabilities {
+    /** Provider 全局上下文 */
+    provider;
+    // ---- 全局候选集（发现一次，全局复用）----
+    builtinInstances;
+    userInstances;
+    subagentDefs;
+    /** 完整 SkillInfo，含 subAgent 标记，可据此区分枚举 */
+    skills;
+    /** 完整 MCP 服务器配置 */
+    mcps;
+    constructor(provider) {
+        this.provider = provider;
+        this.builtinInstances = discoverBuiltinTools(provider.config);
+        this.userInstances = discoverUserTools(provider.toolsPaths);
+        this.subagentDefs = discoverSubAgents(provider.subAgentsPaths);
+        this.skills = discoverSkills(provider.skillsPaths);
+        this.mcps = discoverMcpServers(provider.mcpPaths);
+    }
+    /**
+     * 按权限过滤候选集，返回过滤后的名称列表。
+     * 纯名称操作（安全预过滤 + 权限过滤），不涉及 Tool 实例化。
+     */
+    filter(permissions, 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.subagentDefs
+            : this.subagentDefs.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.builtinInstances.map((t) => t.function.name),
+            ...this.userInstances.map((t) => t.function.name),
+            ...DYNAMIC_TOOL_NAMES,
+        ].filter((name) => !excludeTools.has(name));
+        const evaluator = new PermissionEvaluator(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(permissions, options) {
+        return this.instantiate(this.filter(permissions, options));
+    }
+    /**
+     * 将过滤后的名称列表实例化为 Tool 数组。
+     */
+    instantiate(filtered) {
+        const result = [];
+        const allowedToolNames = new Set(filtered.tools);
+        const provider = this.provider;
+        // 1. 内置 + 用户工具
+        for (const t of [...this.builtinInstances, ...this.userInstances]) {
+            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(provider.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(provider.skillsPaths, filteredSkills, this));
+        }
+        if (allowedToolNames.has("load_mcp") && provider.mcpManager && provider.mcpConfigs && filteredMcps.length > 0) {
+            result.push(createLoadMcpTool(provider.mcpManager, provider.mcpConfigs, filteredMcps));
+        }
+        if (allowedToolNames.has("call_mcp_tool") && provider.mcpManager) {
+            result.push(createCallMcpTool(provider.mcpManager));
+        }
+        if (allowedToolNames.has("read_mcp_resource") && provider.mcpManager) {
+            result.push(createReadMcpResourceTool(provider.mcpManager));
+        }
+        // 4. SubAgent
+        const allowedSubagentSet = new Set(filtered.subagents);
+        for (const def of this.subagentDefs) {
+            if (!def.function || !allowedSubagentSet.has(def.function.name))
+                continue;
+            result.push(createSubAgentTool(def, this.provider, this));
+        }
+        // 5. 去重
+        return dedupTools(result);
+    }
+    /**
+     * 重新执行全局发现（重新扫描文件系统）。
+     */
+    refresh() {
+        const provider = this.provider;
+        this.builtinInstances = discoverBuiltinTools(provider.config);
+        this.userInstances = discoverUserTools(provider.toolsPaths);
+        this.subagentDefs = discoverSubAgents(provider.subAgentsPaths);
+        this.skills = discoverSkills(provider.skillsPaths);
+        this.mcps = discoverMcpServers(provider.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;
+}

package/dist/capabilities/PermissionEvaluator.d.ts

@@ -0,0 +1,19 @@
+import type { AgentPermissions, PermissionPolicy } from "../types/index.js";
+export interface CandidateSets {
+    tools: string[];
+    skills: string[];
+    mcps: string[];
+    subagents: string[];
+}
+/**
+ * 权限评估器 — 按四维度权限过滤候选集。
+ */
+export declare class PermissionEvaluator {
+    private permissions?;
+    constructor(permissions?: AgentPermissions);
+    filter(candidates: CandidateSets): CandidateSets;
+    isAllowed(name: string, dimension: keyof CandidateSets): boolean;
+    static match(name: string, policy: PermissionPolicy): boolean;
+    private filterDimension;
+    private validatePolicy;
+}

package/dist/capabilities/PermissionEvaluator.js

@@ -0,0 +1,50 @@
+const DENY_ALL = { deny: ["*"] };
+function matchPermission(name, policy) {
+    if ("allow" in policy) {
+        return policy.allow.some((p) => p === "*" || p === name);
+    }
+    return !policy.deny.some((p) => p === "*" || p === name);
+}
+/**
+ * 权限评估器 — 按四维度权限过滤候选集。
+ */
+export class PermissionEvaluator {
+    permissions;
+    constructor(permissions) {
+        this.permissions = permissions;
+    }
+    filter(candidates) {
+        if (!this.permissions) {
+            return { tools: [], skills: [], mcps: [], subagents: [] };
+        }
+        return {
+            tools: this.filterDimension(candidates.tools, this.permissions.tools),
+            skills: this.filterDimension(candidates.skills, this.permissions.skills),
+            mcps: this.filterDimension(candidates.mcps, this.permissions.mcps),
+            subagents: this.filterDimension(candidates.subagents, this.permissions.subagents),
+        };
+    }
+    isAllowed(name, dimension) {
+        if (!this.permissions)
+            return false;
+        const policy = this.permissions[dimension];
+        if (!policy)
+            return false;
+        return matchPermission(name, policy);
+    }
+    static match(name, policy) {
+        return matchPermission(name, policy);
+    }
+    filterDimension(names, policy) {
+        if (!policy) {
+            policy = DENY_ALL;
+        }
+        this.validatePolicy(policy);
+        return names.filter((name) => matchPermission(name, policy));
+    }
+    validatePolicy(policy) {
+        if ("allow" in policy && "deny" in policy) {
+            throw new Error("权限维度不能同时配置 allow 和 deny");
+        }
+    }
+}

package/dist/capabilities/disclosure.d.ts

@@ -0,0 +1,10 @@
+export interface DisclosureParam {
+    type: "string";
+    description: string;
+    enum?: string[];
+}
+/**
+ * 创建 load_skill / load_mcp 的参数 schema。
+ * 有候选项时生成枚举，无候选项时退化为自由文本并在描述中追加提示。
+ */
+export declare function createDisclosureParam(ids: string[], baseDescription: string, emptyHint: string): DisclosureParam;

package/dist/capabilities/disclosure.js

@@ -0,0 +1,17 @@
+/**
+ * 创建 load_skill / load_mcp 的参数 schema。
+ * 有候选项时生成枚举，无候选项时退化为自由文本并在描述中追加提示。
+ */
+export function createDisclosureParam(ids, baseDescription, emptyHint) {
+    if (ids.length === 0) {
+        return {
+            type: "string",
+            description: `${baseDescription} ${emptyHint}`,
+        };
+    }
+    return {
+        type: "string",
+        description: baseDescription,
+        enum: ids,
+    };
+}

package/dist/capabilities/discovery/builtin.d.ts

@@ -0,0 +1,8 @@
+import { Tool } from "@ai-zen/agents-core";
+import type { AppConfig } from "../../types/index.js";
+/**
+ * 发现内置工具。直接返回 BUILTIN_TOOLS 实例。
+ * 如果配置了 defaultImageModel，额外包含 generateImage 工具。
+ * 与 discoverUserTools 保持对称：都返回 Tool[]。
+ */
+export declare function discoverBuiltinTools(config: AppConfig): Tool[];

package/dist/capabilities/discovery/builtin.js

@@ -0,0 +1,17 @@
+import { BUILTIN_TOOLS } from "../implements/builtin/index.js";
+import { createGenerateImageTool } from "../implements/builtin/generateImage.js";
+/**
+ * 发现内置工具。直接返回 BUILTIN_TOOLS 实例。
+ * 如果配置了 defaultImageModel，额外包含 generateImage 工具。
+ * 与 discoverUserTools 保持对称：都返回 Tool[]。
+ */
+export function discoverBuiltinTools(config) {
+    const tools = [...BUILTIN_TOOLS];
+    if (config.defaultImageModel) {
+        const existingNames = new Set(tools.map((t) => t.function.name));
+        if (!existingNames.has("generateImage")) {
+            tools.push(createGenerateImageTool(config));
+        }
+    }
+    return tools;
+}

package/dist/capabilities/discovery/mcp.d.ts

@@ -0,0 +1,7 @@
+import type { McpServerConfig } from "../../types/index.js";
+/**
+ * 从 mcp.json 文件列表中发现所有 MCP server 配置。
+ * 按优先级从高到低传入路径列表，同名 server 靠前的文件优先（先到先得）。
+ * 返回完整配置，不再丢失信息。
+ */
+export declare function discoverMcpServers(paths: string[]): McpServerConfig[];

package/dist/capabilities/discovery/mcp.js

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync } from "node:fs";
+/**
+ * 从 mcp.json 文件列表中发现所有 MCP server 配置。
+ * 按优先级从高到低传入路径列表，同名 server 靠前的文件优先（先到先得）。
+ * 返回完整配置，不再丢失信息。
+ */
+export function discoverMcpServers(paths) {
+    const seen = new Set();
+    const items = [];
+    for (const path of paths) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const raw = readFileSync(path, "utf-8");
+            const config = JSON.parse(raw);
+            const servers = config.servers ?? {};
+            for (const id of Object.keys(servers)) {
+                if (!seen.has(id)) {
+                    seen.add(id);
+                    items.push({ id, ...servers[id] });
+                }
+            }
+        }
+        catch {
+            // 跳过解析失败
+        }
+    }
+    return items;
+}

package/dist/capabilities/discovery/skills.d.ts

@@ -0,0 +1,43 @@
+export interface Frontmatter {
+    name?: string;
+    description?: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    allowedTools?: string[];
+    /** @extension Claude Code 启发：声明此 Skill 可作为子 Agent 运行 */
+    subAgent?: boolean;
+}
+export interface SkillValidationError {
+    skillId: string;
+    field: string;
+    message: string;
+}
+/** Skill 完整信息。id = 目录名 = SKILL.md 的 name 字段 */
+export interface SkillInfo {
+    id: string;
+    name: string;
+    description: string;
+    subAgent: boolean;
+    content: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    allowedTools?: string[];
+}
+/**
+ * 扫描多个目录中发现的所有 Skill（含 SKILL.md 的子目录）。
+ * 按优先级从高到低传入路径列表，同名 skill 靠前的路径优先（先到先得）。
+ * 解析 YAML frontmatter 中的 name 和 description，同时校验合规。
+ */
+export declare function discoverSkills(paths: string[]): SkillInfo[];
+/**
+ * 读取单个 Skill 的完整内容与元数据。
+ * 按优先级从高到低传入路径列表，靠前的路径优先（先到先得）。
+ * 返回 null 如果 skill 在所有目录中都不存在或 SKILL.md 不可读。
+ */
+export declare function readSkill(skillDirs: string[], skillId: string): SkillInfo | null;
+/** @internal */
+export declare function parseFrontmatter(content: string): Frontmatter;
+/** @internal */
+export declare function validateSkill(skillId: string, fm: Frontmatter): SkillValidationError[];