@ai-zen/agents-sdk 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/runtime/HandoffService.js

@@ -0,0 +1,472 @@
+import { promises as fs } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { Message } from "@ai-zen/agents-core";
+import { getLogger } from "../shared/logger.js";
+import { readSkill } from "../scope/plugins/skills/discover.js";
+import { FALLBACK_HANDOFF_TEMPLATE, HANDOFF_SKILL_ID } from "../config/factory-skills.js";
+import { HandoffGuardPlugin } from "./HandoffGuardPlugin.js";
+/**
+ * 交接被调用方取消（`AbortSignal` 触发）。
+ *
+ * 单独成类型而不是复用 `Error`，原因有两个：
+ *   - 调用方（如 TUI）要把「用户按了 Ctrl+C」与「交接真的失败了」区分开 ——
+ *     前者应静默收尾并提示「已取消」，后者才该报错；
+ *   - 它**不可降级**：`self` 被取消后绝不能退到 `summary` 再跑一遍。
+ *     把「用户中止」当成「模型没写出文档」，会白白多烧一轮全量输入。
+ */
+export class HandoffAbortedError extends Error {
+    constructor() {
+        super("交接已取消");
+        this.name = "HandoffAbortedError";
+    }
+}
+/**
+ * 错误是否来自取消。
+ *
+ * 两条路径都要认：
+ *   - 调用方传了 `signal` 且已 `aborted`（`agent.abort()` 就是这种情况 ——
+ *     它**不抛错**，core 层把消息标记成 Aborted 后正常返回）；
+ *   - OpenAI SDK 在请求被 abort 时抛的 `APIUserAbortError`（`name` 为 `AbortError`）。
+ */
+function isAbortError(err, signal) {
+    if (signal?.aborted)
+        return true;
+    const name = err?.name;
+    return name === "AbortError" || name === "APIUserAbortError";
+}
+/**
+ * 任务交接服务。
+ *
+ * 职责分层（这是本模块唯一的设计主线）：
+ *   - `handoff()`：**只产出交接文档**（停工 → 写文档 → 校验 → 失败降级），不动会话；
+ *   - `migrate()`：`handoff()` 之后清历史并开新会话（原「任务迁移」语义）。
+ *
+ * 模板的唯一真相源是 `handoff` Skill（`SKILL.md`）；代码只负责
+ * 「读正文 → 注入 → 校验文件 → 读不到时用兜底模板」，不持有第二份章节清单。
+ *
+ * 重入：`handoff()` 与 `migrate()` 共用 `busy` 标志。交接回合本身也是一次 `send()`，
+ * 若不在 busy 期间让 `AutoMigratePlugin` / `ContextGuardPlugin` 让行，就会「交接触发迁移、
+ * 迁移再触发交接」无限递归，或在最满的时刻被护栏直接击杀。
+ */
+export class HandoffService {
+    /** 交接文档兜底模板（仅在读不到 Skill 时使用） */
+    static FALLBACK_TEMPLATE = FALLBACK_HANDOFF_TEMPLATE;
+    handoffDirPath;
+    defaultMode;
+    defaultStrategy;
+    skillDirs;
+    client;
+    model;
+    modelConfig;
+    minHandoffBytes;
+    onBeforeHandoff;
+    onHandoff;
+    onMigrated;
+    logger;
+    /** 交接/迁移进行中标志（插件据此让行） */
+    _busy = false;
+    /** 交接回合的工具守卫（同一实例复用 + arm/disarm，避免插件数组无限增长） */
+    guard;
+    /** 已注册过守卫的 agent（每个 agent 只 use 一次） */
+    guardedAgents = new WeakSet();
+    constructor(options = {}) {
+        const { handoffDir, mode, strategy, skillDirs, client, model, modelConfig, minHandoffBytes, onBeforeHandoff, onHandoff, onMigrated, logger, } = options;
+        this.handoffDirPath = resolvePath(handoffDir ?? join(process.cwd(), ".ai-zen", "handoffs"));
+        this.defaultMode = mode ?? "self";
+        this.defaultStrategy = strategy ?? "omit";
+        this.skillDirs = skillDirs ?? [];
+        this.client = client;
+        this.model = model;
+        this.modelConfig = modelConfig;
+        this.minHandoffBytes = minHandoffBytes ?? 400;
+        this.onBeforeHandoff = onBeforeHandoff;
+        this.onHandoff = onHandoff;
+        this.onMigrated = onMigrated;
+        this.logger = logger ?? getLogger();
+    }
+    /** 是否正在交接/迁移（`AutoMigratePlugin` / `ContextGuardPlugin` 据此让行） */
+    get busy() {
+        return this._busy;
+    }
+    /** 交接文档目录 */
+    get handoffDir() {
+        return this.handoffDirPath;
+    }
+    // ==================================================================
+    // 静态纯工具（供上层复用 / 单测）
+    // ==================================================================
+    /**
+     * 交接文件名：`<YYYYMMDD-HHmmss>-<会话id前8位>.md`（本地时间，便于人眼归档）。
+     */
+    static createHandoffFileName(date = new Date(), conversationId) {
+        const p = (n) => String(n).padStart(2, "0");
+        const stamp = `${date.getFullYear()}${p(date.getMonth() + 1)}${p(date.getDate())}` +
+            `-${p(date.getHours())}${p(date.getMinutes())}${p(date.getSeconds())}`;
+        const suffix = conversationId ? `-${conversationId.slice(0, 8)}` : "";
+        return `${stamp}${suffix}.md`;
+    }
+    /**
+     * 拼装「本轮交接」指令：`[Skill 正文] + [本次交接参数]`。
+     *
+     * 不在 Skill 正文里发明占位符（本体系没有模板变量引擎），参数一律由代码拼在后面，
+     * 这样 Skill 只讲「怎么写」、代码只讲「写到哪、有什么能力」。
+     */
+    static createHandoffInstruction(params) {
+        const { skillContent, handoffPath, toolsAvailable } = params;
+        const tail = toolsAvailable
+            ? [
+                "请立即开始撰写，并用 write 工具把完整文档写入上面给出的路径（路径原样使用，不要改名、不要换目录）。",
+                "写完后用 read 回读一次确认完整，然后只回一句不超过 40 字的确认，**不要复述文档内容**。",
+            ]
+            : [
+                "请直接输出完整文档正文：不要任何解释、不要用代码块包裹，调用方会自行落盘。",
+            ];
+        return [
+            "你现在要为本轮对话编写一份任务交接文档。以下是必须遵守的交接规范。",
+            "",
+            "---",
+            "",
+            skillContent.trim(),
+            "",
+            "---",
+            "",
+            "## 本次交接参数",
+            `- 交接文档绝对路径：${handoffPath}`,
+            `- 工具能力：${toolsAvailable
+                ? "可用（read / exec 等，请据此核实真实状态）"
+                : "不可用（你无法核实磁盘，状态类信息一律写「⚠️ 未核实」，禁止推测）"}`,
+            "",
+            ...tail,
+        ].join("\n");
+    }
+    /**
+     * 生成迁移后追加的「交接断点」消息（role=user）：只给路径，让接手方自己 read。
+     *
+     * 为什么不内联全文：接手方第一次真正需要的是「去哪里取交接」，读一次文件的输入成本
+     * 与内联全文相当，但内联会让每条请求都携带全文；路径方案把成本推迟到真正需要时。
+     */
+    static createPostMessages(handoffPath) {
+        const content = [
+            "上一轮对话已交接，交接文档保存在：",
+            handoffPath,
+            "",
+            "请先用 read 工具读取该文件，理解上下文与未完成事项后，再继续协助用户完成任务。",
+        ].join("\n");
+        return [Message.User(content)];
+    }
+    /** 序列化消息为 `[role]: content` 文本（仅 `summary` 模式使用） */
+    static serializeMessages(messages) {
+        return messages
+            .map((m) => {
+            const role = m.role ?? "unknown";
+            const content = typeof m.content === "string" ? m.content : JSON.stringify(m.content);
+            return `[${role}]: ${content}`;
+        })
+            .join("\n\n");
+    }
+    // ==================================================================
+    // 公开流程
+    // ==================================================================
+    /**
+     * 只产出交接文档，**不改动会话**（`/handoff`）。
+     *
+     * 不清理历史：交接回合（指令 + 工具调用 + 回执）会留在 `agent.messages` 里，
+     * 用户可继续让 agent 打磨这份文档（重写同一路径即可）。
+     */
+    async handoff(params) {
+        return this.withBusy(() => this.runCatchingAbort(params, false));
+    }
+    /**
+     * 交接 + 开新会话（`/migrate`、自动迁移）。
+     *
+     * 策略（`strategy`）：
+     *   - `omit`（默认）：历史标记 `omit: true`（保留可审计），末尾追加交接断点；
+     *   - `prune`：物理剔除历史，只留 `definition.messages` + 交接断点。
+     */
+    async migrate(params) {
+        return this.withBusy(async () => {
+            const ctx = await this.runCatchingAbort(params, true);
+            const { agent } = ctx;
+            const strategy = params.strategy ?? this.defaultStrategy;
+            const breakpointMessages = HandoffService.createPostMessages(ctx.handoffPath);
+            if (strategy === "prune") {
+                // 浅拷贝模板消息，避免污染 definition.messages 引用的对象
+                agent.messages = [...agent.definition.messages, ...breakpointMessages];
+            }
+            else {
+                const preserveCount = Math.min(agent.definition.messages.length, agent.messages.length);
+                agent.messages = [
+                    ...agent.messages.map((m, i) => ({
+                        ...m,
+                        omit: i >= preserveCount ? true : m.omit,
+                    })),
+                    ...breakpointMessages,
+                ];
+            }
+            await this.safeHook(this.onMigrated, ctx);
+            return ctx;
+        });
+    }
+    // ==================================================================
+    // 内部
+    // ==================================================================
+    /** 串行化 + 防重入：交接与迁移共用同一把锁 */
+    async withBusy(fn) {
+        if (this._busy)
+            throw new Error("交接流程已在进行中，请等待当前交接完成");
+        this._busy = true;
+        try {
+            return await fn();
+        }
+        finally {
+            this._busy = false;
+        }
+    }
+    /**
+     * 把底层各种「取消」形态统一成 {@link HandoffAbortedError}。
+     *
+     * 取消可能从三处冒上来：`self` 回合后的主动检查（已是 HandoffAbortedError）、
+     * `summary` 请求被 abort 时 OpenAI SDK 抛的 `APIUserAbortError`、以及
+     * `readSkillContent` 这类前置 await 期间被取消。调用方只需要认一个类型。
+     */
+    async runCatchingAbort(params, migrating) {
+        try {
+            return await this.runHandoff(params, migrating);
+        }
+        catch (err) {
+            if (err instanceof HandoffAbortedError)
+                throw err;
+            if (isAbortError(err, params.signal))
+                throw new HandoffAbortedError();
+            throw err;
+        }
+    }
+    /** 取消点检查：每跨过一个阶段就确认一次，避免取消后继续往下一步冲 */
+    throwIfAborted(signal) {
+        if (signal?.aborted)
+            throw new HandoffAbortedError();
+    }
+    async fileExists(path) {
+        try {
+            await fs.access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 取消后清掉半成品文档。
+     *
+     * 只删「本次新建」的文件：交接文件名含时间戳，正常不会撞已有文件，但调用方也
+     * 可以把 `handoffDir` 指向人工目录；不管怎样都不该删掉别人的文件。
+     * 留着半成品更糟 —— 下一轮接手方会把不完整的内容当成真实交接读进去。
+     */
+    async discardPartialFile(path, existedBefore) {
+        if (existedBefore)
+            return;
+        try {
+            await fs.unlink(path);
+        }
+        catch {
+            /* 文件本就没写出来：忽略 */
+        }
+    }
+    async runHandoff(params, migrating) {
+        const { agent, promptTokens, handoffTokens, conversationId, signal } = params;
+        const requestedMode = params.mode ?? this.defaultMode;
+        const handoffPath = join(this.handoffDirPath, HandoffService.createHandoffFileName(new Date(), conversationId));
+        const model = this.model ?? agent.model;
+        const messageCountBefore = agent.messages.length;
+        // 迁移前上下文（不含文档，语义固定）
+        const beforeCtx = {
+            agent,
+            mode: requestedMode,
+            requestedMode,
+            handoffPath,
+            model,
+            promptTokens,
+            handoffTokens,
+            migrating,
+            messageCountBefore,
+            historyText: "",
+        };
+        await this.safeHook(this.onBeforeHandoff, beforeCtx);
+        this.throwIfAborted(signal);
+        // ---- 执行者：self 优先，失败/不可用则单向降级 summary ----
+        let mode = requestedMode;
+        let handoffDoc;
+        let historyText = "";
+        if (mode === "self" && !this.supportsSelfHandoff(agent)) {
+            this.logger.warn("[handoff] agent 不具备 write 工具或 send 能力，降级为独立摘要模式");
+            mode = "summary";
+        }
+        if (mode === "self") {
+            const ok = await this.runSelfHandoff(agent, handoffPath, signal);
+            if (!ok) {
+                this.logger.warn("[handoff] 自交接失败，降级为独立摘要模式");
+                mode = "summary";
+            }
+        }
+        if (mode === "summary") {
+            historyText = HandoffService.serializeMessages(agent.messages.filter((m) => !m.omit));
+            handoffDoc = await this.generateSummary(agent, historyText, handoffPath, signal);
+            await this.writeHandoffFile(handoffPath, handoffDoc);
+        }
+        // 最后一道取消点：即使两步都跑完，只要期间被取消就不能算成功
+        this.throwIfAborted(signal);
+        const ctx = {
+            agent,
+            mode,
+            requestedMode,
+            handoffPath,
+            handoffDoc,
+            model,
+            promptTokens,
+            handoffTokens,
+            migrating,
+            messageCountBefore,
+            historyText,
+        };
+        await this.safeHook(this.onHandoff, ctx);
+        return ctx;
+    }
+    /** 自交接是否可用：需要 `write` 工具 + `send` 能力 */
+    supportsSelfHandoff(agent) {
+        if (typeof agent.send !== "function")
+            return false;
+        return Boolean(agent.tools?.some((tool) => tool.function?.name === "write"));
+    }
+    /**
+     * 自交接回合：让原 agent 停工、核实、写文档，并校验文件确实落盘。
+     *
+     * 失败判定（任一成立即视为失败，交由上层单向降级 summary）：
+     *   - 文件不存在 / 小于阈值；
+     *   - 模型/工具链抛错（例如没有权限、被护栏中断）。
+     *
+     * **取消不算失败**：`signal` 已触发时抛 {@link HandoffAbortedError}，既不走
+     * 「文件没写好→重试一次」也不降级 summary。 这条分支必须显式写：
+     * `agent.abort()` 不抛错（core 把消息标记为 Aborted 后正常返回），否则「用户
+     * 按了 Ctrl+C」会被下面的文件校验误判成「模型没写出文档」，于是重试一轮、再降级
+     * 一轮 —— 用户以为取消了，实际多烧了两轮全量输入。
+     */
+    async runSelfHandoff(agent, handoffPath, signal) {
+        const guard = this.ensureGuard(agent);
+        const skillContent = await this.readSkillContent();
+        const cwd = agent.scope?.cwd ?? process.cwd();
+        // 取消时只删本次新建的文件，不碰本已存在的同名文件
+        const existedBefore = await this.fileExists(handoffPath);
+        /*
+         * 清空 lastUsage 再开跑：
+         *   - 护栏（ContextGuardPlugin）在每轮请求前用 lastUsage 判定严重超限，
+         *     而交接恰好发生在上下文最满的时刻；
+         *   - AutoMigratePlugin 也会读它。busy 已能让两者让行，这里再清一次是纵深防御。
+         * 交接回合结束后 lastUsage 由本轮真实响应用量回填，无需恢复旧值。
+         */
+        agent.lastUsage = undefined;
+        guard.arm(handoffPath, cwd);
+        try {
+            await agent.send(HandoffService.createHandoffInstruction({
+                skillContent,
+                handoffPath,
+                toolsAvailable: true,
+            }));
+            // `agent.abort()` 不抛错，必须主动检查（见方法注释）
+            this.throwIfAborted(signal);
+            if (await this.isHandoffFileReady(handoffPath))
+                return true;
+            this.logger.warn(`[handoff] 交接文档缺失或过小，重试一次：${handoffPath}`);
+            await agent.send([
+                `交接文档不存在或内容过少，无法交付：${handoffPath}`,
+                "请立即用 write 工具把**完整**交接文档写入该路径（路径原样使用），不要做其他任何事。",
+            ].join("\n"));
+            this.throwIfAborted(signal);
+            return await this.isHandoffFileReady(handoffPath);
+        }
+        catch (err) {
+            if (isAbortError(err, signal)) {
+                await this.discardPartialFile(handoffPath, existedBefore);
+                throw new HandoffAbortedError();
+            }
+            this.logger.error(`[handoff] 自交接回合失败：${err?.message ?? err}`);
+            return false;
+        }
+        finally {
+            guard.disarm();
+        }
+    }
+    /** 独立摘要：一次模型调用，用同一份 Skill 正文作为规范 */
+    async generateSummary(agent, historyText, handoffPath, signal) {
+        const client = this.client ?? agent.client;
+        const model = this.model ?? agent.model;
+        const modelConfig = this.modelConfig ?? agent.modelConfig;
+        const skillContent = await this.readSkillContent();
+        this.throwIfAborted(signal);
+        // `signal` 走 RequestOptions（第二参数），与 `core/Agent.ts` 调用模型时一致：
+        // 放在 body 里不会被 OpenAI SDK 当成取消信号。
+        const response = await client.chat.completions.create({
+            model,
+            ...(modelConfig ?? {}),
+            messages: [
+                {
+                    role: "system",
+                    content: HandoffService.createHandoffInstruction({
+                        skillContent,
+                        handoffPath,
+                        toolsAvailable: false,
+                    }),
+                },
+                { role: "user", content: historyText },
+            ],
+        }, signal ? { signal } : undefined);
+        const handoffDoc = response.choices[0]?.message?.content;
+        if (!handoffDoc || !handoffDoc.trim()) {
+            throw new Error("未能生成任务交接文档");
+        }
+        return handoffDoc;
+    }
+    /** 落盘（仅 `summary` 模式需要；`self` 模式由 agent 的 write 工具完成） */
+    async writeHandoffFile(handoffPath, content) {
+        await fs.mkdir(dirname(handoffPath), { recursive: true });
+        await fs.writeFile(handoffPath, content, "utf-8");
+    }
+    /** 交接文档是否可用：文件存在且不小于阈值（不读内容，避免二次读取） */ async isHandoffFileReady(handoffPath) {
+        try {
+            const stat = await fs.stat(handoffPath);
+            return stat.isFile() && stat.size >= this.minHandoffBytes;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** 读取 `handoff` Skill 正文；读不到时回落到兜底模板 */
+    async readSkillContent() {
+        if (this.skillDirs.length > 0) {
+            const skill = await readSkill(this.skillDirs, HANDOFF_SKILL_ID, { silent: true });
+            if (skill?.content?.trim())
+                return skill.content;
+        }
+        this.logger.warn(`[handoff] 未找到 ${HANDOFF_SKILL_ID} Skill，使用内置兜底模板（路径：${this.skillDirs.join(", ") || "未配置"}）`);
+        return FALLBACK_HANDOFF_TEMPLATE;
+    }
+    /** 守卫按 agent 注册一次（`Agent.use()` 无移除 API，故复用实例 + 开关） */
+    ensureGuard(agent) {
+        const guard = (this.guard ??= new HandoffGuardPlugin());
+        if (!this.guardedAgents.has(agent)) {
+            agent.use(guard);
+            this.guardedAgents.add(agent);
+        }
+        return guard;
+    }
+    /** 钩子容错：抛错只记录，不中断交接（与既有迁移钩子语义一致） */
+    async safeHook(hook, ctx) {
+        if (!hook)
+            return;
+        try {
+            await hook(ctx);
+        }
+        catch (err) {
+            this.logger.error(`[handoff] 钩子执行失败: ${err?.message ?? err}`);
+        }
+    }
+}

package/dist/runtime/SdkAgent.d.ts

@@ -1,6 +1,6 @@
 import type OpenAI from "openai";
 import { Agent } from "@ai-zen/agents-core";
-import type { AgentNS, Tool } from "@ai-zen/agents-core";
+import type { AbortedMessageStrategy, AbortedToolRoundStrategy, AgentNS, Tool } from "@ai-zen/agents-core";
 import type { AgentDefinition } from "../types/index.js";
 import type { Scope } from "../scope/Scope.js";
 export type { AgentPlugin, SendContext } from "@ai-zen/agents-core";
@@ -30,5 +30,11 @@ export declare class SdkAgent extends Agent {
         messages?: AgentNS.Message[];
         tools?: Tool[];
         allowJsonParseError?: boolean;
+        /** 工具轮次被中断时的归一策略（core 默认 `fill`） */
+        abortedToolRoundStrategy?: AbortedToolRoundStrategy;
+        /** `fill` 策略下未完成工具结果的填充原因 */
+        abortedToolRoundReason?: string;
+        /** 被中断的 assistant（内容/思考）是否保留（core 默认 `drop`） */
+        abortedMessageStrategy?: AbortedMessageStrategy;
     });
 }

package/dist/runtime/SdkAgent.js

@@ -24,6 +24,9 @@ export class SdkAgent extends Agent {
             messages: params.messages,
             tools: params.tools,
             allowJsonParseError: params.allowJsonParseError,
+            abortedToolRoundStrategy: params.abortedToolRoundStrategy,
+            abortedToolRoundReason: params.abortedToolRoundReason,
+            abortedMessageStrategy: params.abortedMessageStrategy,
         });
         this.scope = params.scope;
         this.definition = params.definition;

package/dist/runtime/createAgent.d.ts

@@ -1,5 +1,20 @@
 import { SdkAgent } from "./SdkAgent.js";
 import type { Scope } from "../scope/Scope.js";
+import type { AbortedMessageStrategy, AbortedToolRoundStrategy } from "@ai-zen/agents-core";
+/**
+ * `createAgent` 的可选行为开关（不传则全部沿用 core 默认值）。
+ */
+export interface CreateAgentOptions {
+    /** 工具轮次被中断（或结果不完整）时的归一策略（core 默认 `fill`） */
+    abortedToolRoundStrategy?: AbortedToolRoundStrategy;
+    /** `fill` 策略下，未完成工具结果的填充原因 */
+    abortedToolRoundReason?: string;
+    /**
+     * 被中断的 assistant 消息（已输出的内容 / 思考）如何处置（core 默认 `drop`）。
+     * 传 `keep` 可让模型在下一轮接着半截往下说，而不是忘掉自己说过什么。
+     */
+    abortedMessageStrategy?: AbortedMessageStrategy;
+}
 /**
  * 从磁盘创建 Agent。
  *
@@ -10,4 +25,4 @@ import type { Scope } from "../scope/Scope.js";
  * // agent 是 SdkAgent，可直接注册插件、发送消息
  * ```
  */
-export declare function createAgent(scope: Scope, agentId: string): Promise<SdkAgent>;
+export declare function createAgent(scope: Scope, agentId: string, options?: CreateAgentOptions): Promise<SdkAgent>;

package/dist/runtime/createAgent.js

@@ -11,14 +11,15 @@ import { createModel } from "./createModel.js";
  * // agent 是 SdkAgent，可直接注册插件、发送消息
  * ```
  */
-export async function createAgent(scope, agentId) {
+export async function createAgent(scope, agentId, options = {}) {
     const definition = await new AgentRepository(scope.agentsDir).read(agentId);
     if (!definition)
         throw new Error(`Agent "${agentId}" 不存在`);
-    const modelId = definition.modelId ?? scope.config.defaultModel;
-    if (!modelId)
-        throw new Error("未指定模型且无默认模型");
-    const { client, model, modelConfig } = createModel(scope, modelId);
+    const modelId = definition.modelId;
+    if (!modelId) {
+        throw new Error(`Agent "${agentId}" 未绑定模型（缺少 modelId）。请在配置里给它指定一个模型。`);
+    }
+    const { client, model, modelConfig } = createModel(scope, modelId, definition.modelParams);
     const tools = scope.buildTools(definition, {
         exclude: {
             subagents: definition.function?.name
@@ -39,6 +40,10 @@ export async function createAgent(scope, agentId) {
         // 快照后，运行时改动只作用于会话副本，模板保持纯净。
         messages: [...(definition.messages ?? [])],
         tools,
+        // 中断相关策略：不传则由 core 取默认值（工具轮次 fill / 消息保留 drop）
+        abortedToolRoundStrategy: options.abortedToolRoundStrategy,
+        abortedToolRoundReason: options.abortedToolRoundReason,
+        abortedMessageStrategy: options.abortedMessageStrategy,
     });
     return agent;
 }

package/dist/runtime/createModel.d.ts

@@ -1,21 +1,25 @@
 import OpenAI from "openai";
 import type { Scope } from "../scope/Scope.js";
+import type { ModelParams } from "../types/index.js";
 /**
  * Agent 模型装配结果：openai SDK client + 模型名 + 模型参数。
  * Agent 构造时直接消费此结构。
  */
 export interface AgentModel {
-    /** openai 官方 SDK 客户端 */
+    /** openai SDK 客户端 */
     client: OpenAI;
     /** 发送给 API 的模型名 */
     model: string;
-    /** 模型参数（defaultParams），透传给 API（可含厂商特有字段，如 DeepSeek thinking） */
-    modelConfig?: Record<string, unknown>;
+    /** 模型参数，透传给 API（可含厂商特有字段，如 DeepSeek thinking） */
+    modelConfig?: ModelParams;
 }
 /**
  * 模型工厂 — 根据 modelId 和 Scope 装配 openai SDK client。
  *
  * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
  * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
+ *
+ * `overrides` 是 **Agent 级参数覆盖**（`AgentDefinition.modelParams`）：
+ * 同一个模型可以给不同 Agent 配不同参数，而模型自身的 `defaultParams` 保持不变。
  */
-export declare function createModel(scope: Scope, modelId: string): AgentModel;
+export declare function createModel(scope: Scope, modelId: string, overrides?: ModelParams): AgentModel;

package/dist/runtime/createModel.js

@@ -1,11 +1,28 @@
 import OpenAI from "openai";
+/**
+ * 参数覆盖 —— 浅合并，一行。
+ *
+ * 这是 SDK 对「模型参数」的唯一处理逻辑：不解释键名、不做档位推导、不知道厂商差异。
+ * 需要多层次语义（如「思考档位」）的应用，应该在**写配置时**就把档位展开成具体参数，
+ * 存进 `Model.defaultParams` / `AgentDefinition.modelParams`，运行期不再查表。
+ *
+ * 没有覆盖时返回原对象（保持 `undefined` 语义，避免凭空塞一个空对象）。
+ */
+function mergeParams(base, overrides) {
+    if (!overrides || Object.keys(overrides).length === 0)
+        return base;
+    return { ...base, ...overrides };
+}
 /**
  * 模型工厂 — 根据 modelId 和 Scope 装配 openai SDK client。
  *
  * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
  * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
+ *
+ * `overrides` 是 **Agent 级参数覆盖**（`AgentDefinition.modelParams`）：
+ * 同一个模型可以给不同 Agent 配不同参数，而模型自身的 `defaultParams` 保持不变。
  */
-export function createModel(scope, modelId) {
+export function createModel(scope, modelId, overrides) {
     const config = scope.config;
     const modelConfig = config.models.find((m) => m.id === modelId);
     if (!modelConfig)
@@ -25,6 +42,6 @@ export function createModel(scope, modelId) {
     return {
         client,
         model: apiModelName,
-        modelConfig: modelConfig.defaultParams,
+        modelConfig: mergeParams(modelConfig.defaultParams, overrides),
     };
 }

package/dist/scope/plugins/builtin/BatchEditTool.js

@@ -2,8 +2,11 @@ import * as fsp from "fs/promises";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class BatchEditTool extends SdkCallbackTool {
     function = {
-        name: "batchEdit",
-        description: "批量编辑文件文本，可以优先使用这个工具对文件进行编辑",
+        name: "batch_edit",
+        description: [
+            "批量编辑文件文本，可以优先使用这个工具对文件进行编辑。",
+            "对同一个文件的多处修改应在一次调用中全部提交（replacements 数组），而不是并行多次调用 edit——并行编辑同一文件会互相覆盖。",
+        ].join("\n"),
         parameters: {
             type: "object",
             properties: {

package/dist/scope/plugins/builtin/DownloadFileTool.js

@@ -3,7 +3,7 @@ import * as path from "path";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class DownloadFileTool extends SdkCallbackTool {
     function = {
-        name: "downloadFile",
+        name: "download_file",
         description: "从 URL 下载文件（图片、PDF 等二进制文件）并保存到本地磁盘。自动从 URL 推断文件名，也可指定保存路径。",
         parameters: {
             type: "object",

package/dist/scope/plugins/builtin/EditTool.js

@@ -15,7 +15,12 @@ function countOccurrences(content, text) {
 export class EditTool extends SdkCallbackTool {
     function = {
         name: "edit",
-        description: "编辑文件中的文本，支持精确替换或替换所有匹配项",
+        description: [
+            "编辑文件中的文本，支持精确替换或替换所有匹配项。",
+            "",
+            "并发限制（重要）：同一个文件禁止并行编辑。不要在同一轮回复中对同一路径发起多个 edit 调用——这些调用会各自读取旧内容再写回，后写者覆盖先写者，导致修改丢失或文件被写坏。",
+            "如需对同一个文件施加多处修改，请改用 batch_edit，在一次调用里提交全部替换。只有编辑不同文件时才可以并行调用 edit。",
+        ].join("\n"),
         parameters: {
             type: "object",
             properties: {