@ai-zen/agents-sdk 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.5.3] - 2026-08-05
+
+### 🚀 新功能
+
+- **初始化时默认释放含 socket-pty 的 mcp.json** — `ConfigManager.bootstrap()` 新增 `ensureDefaultMcpConfig()`，首启在 `~/.ai-zen/mcp.json` 写入默认 MCP 配置（含 socket-pty 终端 server，`command: npx -y @ai-zen/socket-pty mcp`），文件已存在则幂等不覆盖；新增 `readMcpConfig()` / `writeMcpConfig()` 读写方法；新增并导出 `DEFAULT_MCP_CONFIG` 常量
+- **`load_mcp` 透传 server description** — `McpServerConfig` 新增 `description?` 字段，`discoverMcpServers` 解析不再丢弃；`load_mcp` 的 `server` 参数枚举按 `- {id}: {description}` 拼接各 server 说明供 LLM 参考（与 `load_skill` 同构）
+- **新增 `ContextGuardPlugin` 上下文安全护栏** — 在每次内循环**发请求前**（`onInnerLoopStart`，Core 中位于 try 块外）检测上一轮 `usage.prompt_tokens`，超过 `maxTokens × ratio`（默认 1.2，即超阈 20%）时抛出 `ContextOverflowError` 中断对话，防止读入超大文件导致上下文失控。与 `AutoMigratePlugin` 职责分离、区间互补；无需改动 Core
+
+### 🆕 新增导出
+
+- `DEFAULT_MCP_CONFIG`（constants）、`ContextGuardPlugin`、`ContextOverflowError`
+
 ## [0.5.2] - 2026-08-03
 
 ### 🚀 新功能

package/dist/capabilities/discovery/mcp.js

@@ -16,6 +16,7 @@ function normalizeConfig(id, raw) {
     const config = {
         id,
         transport,
+        description: raw.description,
         command: raw.command,
         args: raw.args,
         env: raw.env,

package/dist/capabilities/implements/mcpTools.js

@@ -16,6 +16,11 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
     }
     const ids = filteredMcps.map((s) => s.id);
     const param = createDisclosureParam(ids, "选择一个 MCP 服务器", EMPTY_HINT);
+    // 拼接各 MCP 服务器的描述供 LLM 参考（对齐 load_skill 的处理方式）
+    const mcpDescriptions = filteredMcps
+        .map((s) => `  - ${s.id}: ${s.description || "无描述"}`)
+        .join("\n");
+    const serverIdDescription = `${param.description}\n\n各 MCP 服务器说明：\n${mcpDescriptions || "  无可用 MCP 服务器"}`;
     return new CallbackTool({
         function: {
             name: "load_mcp",
@@ -25,7 +30,7 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
                 properties: {
                     server: {
                         type: "string",
-                        description: param.description,
+                        description: serverIdDescription,
                         ...(param.enum ? { enum: param.enum } : {}),
                     },
                 },

package/dist/config/ConfigManager.d.ts

@@ -37,7 +37,7 @@ export declare class ConfigManager {
      */
     ensureDefaultSubAgent(): Promise<AgentDefinition | null>;
     /**
-     * 一键初始化：目录 + config.json + 默认 Agent + 默认 SubAgent。
+     * 一对初始化：目录 + config.json + 默认 Agent + 默认 SubAgent + 默认 MCP。
      * 已有文件不会被覆盖。
      */
     bootstrap(): Promise<{
@@ -45,5 +45,27 @@ export declare class ConfigManager {
         agent: AgentDefinition | null;
         subAgent: AgentDefinition | null;
     }>;
+    /** mcp.json 路径：{basePath}/mcp.json */
+    get mcpPath(): string;
+    /**
+     * 确保 basePath/mcp.json 存在。不存在时写入出厂默认 MCP 配置（含 socket-pty）。
+     * 已有文件不被覆盖，尊重用户已配置的 MCP 服务器。
+     * @returns 返回当前生效的 MCP 配置原始内容
+     */
+    ensureDefaultMcpConfig(): Promise<Record<string, unknown>>;
+    /**
+     * 读取 basePath/mcp.json，不存在时返回空结构。
+     */
+    readMcpConfig(): Promise<{
+        mcpServers: Record<string, unknown>;
+    }>;
+    /**
+     * 原子写入 mcp.json。
+     */
+    writeMcpConfig(config: {
+        mcpServers: Record<string, unknown>;
+    }): Promise<void>;
+    /** 原子写 JSON 文件（先写 .tmp 再 rename，避免半成品）。 */
+    private writeJson;
 }
-export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";
+export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";

package/dist/config/ConfigManager.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import { dirname, join } from "node:path";
-import { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";
+import { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";
 /**
  * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
  */
@@ -143,7 +143,7 @@ export class ConfigManager {
         return definition;
     }
     /**
-     * 一键初始化：目录 + config.json + 默认 Agent + 默认 SubAgent。
+     * 一对初始化：目录 + config.json + 默认 Agent + 默认 SubAgent + 默认 MCP。
      * 已有文件不会被覆盖。
      */
     async bootstrap() {
@@ -151,7 +151,72 @@ export class ConfigManager {
         const config = await this.ensureDefaultConfig();
         const agent = await this.ensureDefaultAgent();
         const subAgent = await this.ensureDefaultSubAgent();
+        await this.ensureDefaultMcpConfig();
         return { config, agent, subAgent };
     }
+    // -----------------------------------------------------------------------
+    // MCP 配置（~/.ai-zen/mcp.json）
+    // -----------------------------------------------------------------------
+    /** mcp.json 路径：{basePath}/mcp.json */
+    get mcpPath() {
+        return join(this.basePath, "mcp.json");
+    }
+    /**
+     * 确保 basePath/mcp.json 存在。不存在时写入出厂默认 MCP 配置（含 socket-pty）。
+     * 已有文件不被覆盖，尊重用户已配置的 MCP 服务器。
+     * @returns 返回当前生效的 MCP 配置原始内容
+     */
+    async ensureDefaultMcpConfig() {
+        const mcpPath = this.mcpPath;
+        try {
+            await fs.access(mcpPath);
+        }
+        catch {
+            // 不存在 → 写入默认
+            await this.ensureDirs();
+            await this.writeJson(mcpPath, DEFAULT_MCP_CONFIG);
+            return { ...DEFAULT_MCP_CONFIG };
+        }
+        // 已存在 → 不覆盖，读取返回
+        return JSON.parse(await fs.readFile(mcpPath, "utf-8"));
+    }
+    /**
+     * 读取 basePath/mcp.json，不存在时返回空结构。
+     */
+    async readMcpConfig() {
+        const mcpPath = this.mcpPath;
+        try {
+            await fs.access(mcpPath);
+        }
+        catch {
+            return { mcpServers: {} };
+        }
+        try {
+            return JSON.parse(await fs.readFile(mcpPath, "utf-8"));
+        }
+        catch {
+            return { mcpServers: {} };
+        }
+    }
+    /**
+     * 原子写入 mcp.json。
+     */
+    async writeMcpConfig(config) {
+        await this.ensureDirs();
+        await this.writeJson(this.mcpPath, config);
+    }
+    /** 原子写 JSON 文件（先写 .tmp 再 rename，避免半成品）。 */
+    async writeJson(path, data) {
+        const dir = dirname(path);
+        try {
+            await fs.access(dir);
+        }
+        catch {
+            await fs.mkdir(dir, { recursive: true });
+        }
+        const tmpPath = path + ".tmp";
+        await fs.writeFile(tmpPath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+        await fs.rename(tmpPath, path);
+    }
 }
-export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";
+export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";

package/dist/config/constants.d.ts

@@ -9,6 +9,15 @@ export declare const DEFAULT_SUBAGENT_ID = "sub-agent-default";
 export declare const DEFAULT_SUBAGENT_DEFINITION: Omit<AgentDefinition, "createdAt" | "updatedAt">;
 /** SDK 出厂默认 AppConfig。CLI/Desktop 首次初始化时使用。 */
 export declare const DEFAULT_APP_CONFIG: AppConfig;
+/**
+ * SDK 出厂默认 MCP 服务器配置（mcp.json 内容，业界标准格式）。
+ * 首次初始化时释放到 ~/.ai-zen/mcp.json，让用户开箱即用 socket-pty 终端能力。
+ *
+ * 若文件已存在则不覆盖（尊重用户已有配置）。
+ */
+export declare const DEFAULT_MCP_CONFIG: {
+    mcpServers: Record<string, unknown>;
+};
 /**
  * 标准共享子目录列表（不包含运行时目录）。
  *

package/dist/config/constants.js

@@ -179,6 +179,25 @@ export const DEFAULT_APP_CONFIG = {
     defaultMigrationModel: "deepseek-v4-flash",
 };
 // ---------------------------------------------------------------------------
+// 默认 MCP 配置（socket-pty 终端 MCP）
+// ---------------------------------------------------------------------------
+/**
+ * SDK 出厂默认 MCP 服务器配置（mcp.json 内容，业界标准格式）。
+ * 首次初始化时释放到 ~/.ai-zen/mcp.json，让用户开箱即用 socket-pty 终端能力。
+ *
+ * 若文件已存在则不覆盖（尊重用户已有配置）。
+ */
+export const DEFAULT_MCP_CONFIG = {
+    mcpServers: {
+        "socket-pty": {
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "@ai-zen/socket-pty", "mcp"],
+            description: "可托管的伪终端（pty）：spawn/read/wait/write/resize/status/kill",
+        },
+    },
+};
+// ---------------------------------------------------------------------------
 // 目录
 // ---------------------------------------------------------------------------
 /**

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { discoverSkills, readSkill } from "./capabilities/discovery/skills.js";
 export type { SkillInfo, Frontmatter } from "./capabilities/discovery/skills.js";
 export { discoverMcpServers } from "./capabilities/discovery/mcp.js";
 export { discoverUserTools } from "./capabilities/discovery/usertools.js";
-export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
+export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
 export { Provider } from "./runtime/Provider.js";
@@ -26,6 +26,8 @@ export type { BuildMigrationAgentOptions } from "./runtime/TaskMigrationService.
 export { AutoMigratePlugin } from "./plugin/AutoMigratePlugin.js";
 export type { AutoMigrateOptions } from "./plugin/AutoMigratePlugin.js";
 export { AutoRefreshToolsPlugin } from "./plugin/AutoRefreshToolsPlugin.js";
+export { ContextGuardPlugin } from "./plugin/ContextGuardPlugin.js";
+export type { ContextGuardOptions } from "./plugin/ContextGuardPlugin.js";
 export { BUILTIN_TOOL_CLASSES } from "./capabilities/implements/builtin/index.js";
 export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./capabilities/implements/builtin/index.js";
 export { GenerateImageTool } from "./capabilities/implements/builtin/GenerateImageTool.js";
@@ -34,4 +36,4 @@ export { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from
 export { createSubAgentTool } from "./capabilities/implements/subAgentTools.js";
 export { getLogger, setLogger } from "./shared/logger.js";
 export type { Logger, LogFunctions } from "./shared/logger.js";
-export { SdkError } from "./shared/errors.js";
+export { SdkError, ContextOverflowError } from "./shared/errors.js";

package/dist/index.js

@@ -8,7 +8,7 @@ export { discoverSkills, readSkill } from "./capabilities/discovery/skills.js";
 export { discoverMcpServers } from "./capabilities/discovery/mcp.js";
 export { discoverUserTools } from "./capabilities/discovery/usertools.js";
 // 配置 — ConfigManager
-export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
+export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
 // CRUD — 实体仓储（仅 Agent 定义等能力实体）
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
@@ -23,6 +23,7 @@ export { TaskMigrationService } from "./runtime/TaskMigrationService.js";
 // 插件
 export { AutoMigratePlugin } from "./plugin/AutoMigratePlugin.js";
 export { AutoRefreshToolsPlugin } from "./plugin/AutoRefreshToolsPlugin.js";
+export { ContextGuardPlugin } from "./plugin/ContextGuardPlugin.js";
 // 工具 — 内置工具类 + 动态工具工厂
 export { BUILTIN_TOOL_CLASSES } from "./capabilities/implements/builtin/index.js";
 export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./capabilities/implements/builtin/index.js";
@@ -32,4 +33,4 @@ export { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from
 export { createSubAgentTool } from "./capabilities/implements/subAgentTools.js";
 // 共享
 export { getLogger, setLogger } from "./shared/logger.js";
-export { SdkError } from "./shared/errors.js";
+export { SdkError, ContextOverflowError } from "./shared/errors.js";

package/dist/plugin/ContextGuardPlugin.d.ts

@@ -0,0 +1,34 @@
+import type { AgentPlugin, SendContext } from "../runtime/SdkAgent.js";
+export interface ContextGuardOptions {
+    /** 上下文告警阈值（token）。用量超过 maxTokens × ratio 即中断。 */
+    maxTokens: number;
+    /**
+     * 超出比例。用量 > maxTokens × ratio 时判定为「严重超限」（如读入超大文件），
+     * 在请求前抛出 ContextOverflowError 中断对话。默认 1.2（即 +20%）。
+     */
+    ratio?: number;
+}
+/**
+ * 上下文安全护栏插件。
+ *
+ * 在每次内循环**发请求前**检测上一轮用量（usage.prompt_tokens）：
+ * - 若用量超过 maxTokens × ratio，说明上下文已严重超限（通常因读入超大文件），
+ *   在请求前抛出 ContextOverflowError，**中断对话**，交由上层向用户报错。
+ *
+ * 与迁移插件职责分离：
+ * - ContextGuardPlugin 只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
+ * - AutoMigratePlugin 在正常范围内（超 maxTokens 但未达硬上限）做交接迁移。
+ *
+ * ```ts
+ * agent.use(new ContextGuardPlugin({ maxTokens: 250_000 }));
+ * agent.use(new AutoMigratePlugin({
+ *   maxTokens: 250_000,
+ *   migrationAgent,
+ * }));
+ * ```
+ */
+export declare class ContextGuardPlugin implements AgentPlugin {
+    private options;
+    constructor(options: ContextGuardOptions);
+    onInnerLoopStart(ctx: SendContext): Promise<void>;
+}

package/dist/plugin/ContextGuardPlugin.js

@@ -0,0 +1,37 @@
+import { ContextOverflowError } from "../shared/errors.js";
+/**
+ * 上下文安全护栏插件。
+ *
+ * 在每次内循环**发请求前**检测上一轮用量（usage.prompt_tokens）：
+ * - 若用量超过 maxTokens × ratio，说明上下文已严重超限（通常因读入超大文件），
+ *   在请求前抛出 ContextOverflowError，**中断对话**，交由上层向用户报错。
+ *
+ * 与迁移插件职责分离：
+ * - ContextGuardPlugin 只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
+ * - AutoMigratePlugin 在正常范围内（超 maxTokens 但未达硬上限）做交接迁移。
+ *
+ * ```ts
+ * agent.use(new ContextGuardPlugin({ maxTokens: 250_000 }));
+ * agent.use(new AutoMigratePlugin({
+ *   maxTokens: 250_000,
+ *   migrationAgent,
+ * }));
+ * ```
+ */
+export class ContextGuardPlugin {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async onInnerLoopStart(ctx) {
+        const { agent } = ctx;
+        const { maxTokens, ratio = 1.2 } = this.options;
+        // 首轮请求前尚无用量数据，跳过（只能在发出首轮请求、拿到 usage 后才有据可查）
+        const promptTokens = agent.lastUsage?.prompt_tokens;
+        if (promptTokens == null)
+            return;
+        if (promptTokens > maxTokens * ratio) {
+            throw new ContextOverflowError(promptTokens, maxTokens, ratio);
+        }
+    }
+}

package/dist/shared/errors.d.ts

@@ -6,3 +6,19 @@ export declare class SdkError extends Error {
     readonly code: string;
     constructor(code: string, message: string, cause?: Error);
 }
+/**
+ * 上下文超限错误。由 ContextGuardPlugin 在请求前抛出，用于中断对话。
+ * 触发条件通常是上下文 token 用量远超阈值（如读入超大文件），
+ * 继续对话已无意义且会持续放大费用/延迟，故由上层捕获后向用户显式报错。
+ */
+export declare class ContextOverflowError extends Error {
+    /** 触发中断时的刚用量（usage.prompt_tokens） */
+    readonly promptTokens: number;
+    /** 配置的告警阈值（maxTokens） */
+    readonly maxTokens: number;
+    /** 实际生效的硬上限（maxTokens × ratio，越界即中断） */
+    readonly threshold: number;
+    /** 超出比例（如 1.2 表示 20%） */
+    readonly ratio: number;
+    constructor(promptTokens: number, maxTokens: number, ratio: number);
+}

package/dist/shared/errors.js

@@ -13,3 +13,28 @@ export class SdkError extends Error {
         }
     }
 }
+/**
+ * 上下文超限错误。由 ContextGuardPlugin 在请求前抛出，用于中断对话。
+ * 触发条件通常是上下文 token 用量远超阈值（如读入超大文件），
+ * 继续对话已无意义且会持续放大费用/延迟，故由上层捕获后向用户显式报错。
+ */
+export class ContextOverflowError extends Error {
+    /** 触发中断时的刚用量（usage.prompt_tokens） */
+    promptTokens;
+    /** 配置的告警阈值（maxTokens） */
+    maxTokens;
+    /** 实际生效的硬上限（maxTokens × ratio，越界即中断） */
+    threshold;
+    /** 超出比例（如 1.2 表示 20%） */
+    ratio;
+    constructor(promptTokens, maxTokens, ratio) {
+        const threshold = maxTokens * ratio;
+        super(`🛑 上下文严重超限：已用 ${promptTokens} token，超过硬上限 ${threshold}（${Math.round((ratio - 1) * 100)}%，配置上限 ${maxTokens}）。` +
+            `当前对话可能因读入超大文件而失控，已中断，请检查并重新开始。`);
+        this.name = "ContextOverflowError";
+        this.promptTokens = promptTokens;
+        this.maxTokens = maxTokens;
+        this.threshold = threshold;
+        this.ratio = ratio;
+    }
+}

package/dist/types/index.d.ts

@@ -91,6 +91,8 @@ export interface McpServerConfig {
     transport: "stdio" | "http" | "sse";
     /** 是否禁用，默认为 false */
     disabled?: boolean;
+    /** 服务器描述（供 load_mcp 呈现给 LLM，非连接必需） */
+    description?: string;
     command?: string;
     args?: string[];
     env?: Record<string, string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",