@ai-zen/agents-sdk 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.5.4] - 2026-08-05
+
+### 🚀 新功能
+
+- **`ExecAsyncTool`（exec_async）统一走 shell 解析** — 移除 Unix 平台手动分词逻辑，所有平台均经 `spawn(command, [], { shell: true })` 执行。工具描述明确告知 agent：其本身不捕获输出，如需留存/查看输出可在命令中使用 shell 重定向写入文件（`>` / `>>`），并支持管道（`|`）等 shell 语法
+
+### 🎯 优化
+
+- **`ExecTool`（exec）的 `timeout` 改为必填** — schema `required` 由 `["command"]` 扩为 `["command", "timeout"]`，`call()` 类型签名 `timeout: number`（必填），并在运行时双校验（缺失/非正数/非有限数即抛错）。`timeout` 必填后，命令始终受超时保护，避免无超时长跑
+- **超时原因明确告知 agent** — `exec` 超时被终止（`error.killed` 为 true）时返回结构新增 `terminated: "timeout"` 字段。弥补 Node 不会自动在 stderr 写入超时提示的限制，使 agent 能明确判断命令因超时被终止，从而灵活应对
+
+## [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/builtin/ExecAsyncTool.js

@@ -5,7 +5,7 @@ export class ExecAsyncTool extends SdkCallbackTool {
         super({
             function: {
                 name: "exec_async",
-                description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具不会捕获命令的输出，如果需要获取输出请使用 exec。",
+                description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具本身不捕获命令的输出；若需获取/留存输出，可在命令中使用 shell 重定向写入文件（如 `> /path/file`，支持 `>>` 追加、`|` 管道）。命令经 shell 解析执行。",
                 parameters: {
                     type: "object",
                     properties: {
@@ -33,62 +33,15 @@ export class ExecAsyncTool extends SdkCallbackTool {
         const command = input.command;
         const cwd = input.cwd ? this.resolve(input.cwd) : this.env.cwd;
         const detached = input.detached ?? false;
-        // Windows 用 shell 模式，其他平台直接 spawn 避免 shell 安全问题
-        const useShell = process.platform === "win32";
+        // 统一走 shell：允许 shell 语法（重定向 > / >>、管道 | 等）
         return new Promise((resolve) => {
-            let child;
-            if (useShell) {
-                child = spawn(command, [], {
-                    cwd,
-                    detached,
-                    stdio: "ignore",
-                    shell: true,
-                    windowsHide: true,
-                });
-            }
-            else {
-                // Unix: 解析命令和参数，直接 spawn
-                const args = [];
-                let current = "";
-                let inQuote = null;
-                for (const ch of command) {
-                    if (inQuote) {
-                        if (ch === "\\") {
-                            current += command[command.indexOf(ch) + 1] ?? "";
-                            continue;
-                        }
-                        if (ch === inQuote) {
-                            inQuote = null;
-                            if (current)
-                                args.push(current);
-                            current = "";
-                            continue;
-                        }
-                        current += ch;
-                    }
-                    else {
-                        if (ch === '"' || ch === "'") {
-                            inQuote = ch;
-                        }
-                        else if (ch === " ") {
-                            if (current) {
-                                args.push(current);
-                                current = "";
-                            }
-                        }
-                        else {
-                            current += ch;
-                        }
-                    }
-                }
-                if (current)
-                    args.push(current);
-                child = spawn(args[0], args.slice(1), {
-                    cwd,
-                    detached,
-                    stdio: "ignore",
-                });
-            }
+            const child = spawn(command, [], {
+                cwd,
+                detached,
+                stdio: "ignore",
+                shell: true,
+                windowsHide: true,
+            });
             let resolved = false;
             child.on("error", (err) => {
                 if (resolved)

package/dist/capabilities/implements/builtin/ExecTool.d.ts

@@ -4,6 +4,6 @@ export declare class ExecTool extends SdkCallbackTool {
     constructor(env: ToolEnv);
     call(input: {
         command: string;
-        timeout?: number;
+        timeout: number;
     }): Promise<string>;
 }

package/dist/capabilities/implements/builtin/ExecTool.js

@@ -15,10 +15,10 @@ export class ExecTool extends SdkCallbackTool {
                         },
                         timeout: {
                             type: "number",
-                            description: "超时时间（毫秒），超时后会终止进程。默认无超时。建议长时间运行的命令使用 exec_async 异步执行。",
+                            description: "超时时间（毫秒），必填。超时后会终止进程；超过该时长仍未完成即视为超时并终止。建议长时间运行的命令使用 exec_async 异步执行。",
                         },
                     },
-                    required: ["command"],
+                    required: ["command", "timeout"],
                     additionalProperties: false,
                 },
             },
@@ -27,17 +27,24 @@ export class ExecTool extends SdkCallbackTool {
     }
     async call(input) {
         const command = input.command;
-        const timeout = input.timeout;
+        const { timeout } = input;
+        // 运行时双校验：timeout 必填且必须为正数
+        if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
+            throw new Error(`exec: 参数 timeout 为必填项，且必须是正数（毫秒），当前值: ${JSON.stringify(timeout)}`);
+        }
         const result = await new Promise((resolve) => {
             const child = exec(command, {
                 cwd: this.env.cwd,
-                timeout: timeout && timeout > 0 ? timeout : undefined,
+                timeout,
             }, (error, stdout, stderr) => {
+                const killed = error?.killed ?? false;
                 resolve({
                     stdout,
                     stderr,
                     exitCode: error?.code ?? (error ? 1 : null),
-                    killed: error?.killed ?? false,
+                    killed,
+                    // 明确告知 agent 命令是因超时被终止（Node 不会自动在 stderr 写入该提示）
+                    terminated: killed ? "timeout" : undefined,
                 });
             });
         });

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.4",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",