@ai-zen/agents-sdk 1.0.0-alpha.20 → 1.0.0-alpha.22

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [1.0.0-alpha.22] - 2026-10-28
+
+> 中断策略（`abortedMessageStrategy` / `abortedToolRoundStrategy`）从「调用方各自传参」
+> 升级为**配置项**：写进 `config.json`，`createAgent()` 自动读取。
+
+### ✨ 新增
+
+- **`AppConfig` 新增两个策略字段**（`types/index.ts`）：
+  - `abortedMessageStrategy?: "keep" | "drop"` —— 被中断的 assistant 已输出的思考 / 正文是否保留。`keep` 让模型下一轮能接着半截往下说，不再「失忆重来」。
+  - `abortedToolRoundStrategy?: "fill" | "drop"` —— 被中断 / 结果不完整的工具轮次如何归一。`fill` 整轮保留并给未完成结果补原因，保证 `tool_calls` 与结果一一配对。
+- **出厂默认写 `keep` + `fill`**（`DEFAULT_APP_CONFIG`）：`keep` 是产品层结论（core 的库级默认仍是 `drop`），`fill` 与 core 默认一致、无行为变化。
+- **`createAgent()` 从 `scope.config` 取策略**：优先级为「显式参数 > `scope.config` > core 默认值」。上游（CLI / Desktop）不必自己读配置再转一道参数，子 Agent 创建时也自然继承同一份策略。
+- **配置迁移补齐策略字段**（`migrateConfig`）：缺失或非法的 `abortedMessageStrategy` / `abortedToolRoundStrategy` 一律写回出厂默认（`changed` 置真，`ensureDefaultConfig()` 会落盘一次）。于是「配置文件里写着的就是运行时用的」，各端不再需要 `?? "keep"` 式兜底。
+
+### ✅ 测试
+
+- 全量 **57 文件 / 612 例通过**（6 skipped，alpha.21 时 608 例）。
+- `migrate.test.ts` 20 → 22 例：补齐缺失策略、非法值改写、合法值原样保留且 `changed=false`；原「无需迁移返回原对象」用例补上策略字段。
+- `createAgent.test.ts` 6 → 8 例：策略取自 `scope.config`、显式参数覆盖配置、config 未写时回落 core 默认（`drop` / `fill`）。
+
+## [1.0.0-alpha.21] - 2026-10-28
+
+### ✨ 新增
+
+- **交接/迁移支持取消（`AbortSignal`）** —— 此前 `handoff()` / `migrate()` 一旦开始就没有任何中止手段，宿主按 Ctrl+C 也停不下来：
+  - `summary` 模式的独立模型请求根本没有任何取消点；
+  - `self` 模式能被 `agent.abort()` 打断，但中止后被误判成「模型没写出文档」，于是重试一轮、再降级 `summary` 再跑一轮——用户以为取消了，实际多烧两轮全量输入。
+
+  现在 `HandoffParams` 新增 `signal?: AbortSignal`，两个执行者都认它：
+
+  - `summary`：`signal` 作为 **RequestOptions（第二参数）** 传给 `chat.completions.create`，请求会真的被中断；
+  - `self`：每个 `agent.send()` 之后**主动检查** `aborted`（因为 `abort()` 不抛错），取消即抛 `HandoffAbortedError`，**不重试、不降级**；
+  - `runHandoff()` 在阶段之间加取消点；`migrate()` 被取消时**不改动会话历史**（不会留下「已迁移」的假象）。
+
+- **导出 `HandoffAbortedError`** —— 取消单独成类型，调用方才能把「用户按了 Ctrl+C」与「交接真的失败」分开处理：前者静默收尾，后者才该报错。
+
+### 🐛 修复
+
+- **取消后清掉写了一半的交接文档** —— 只删本次新建的（同名旧文件不碰）。半成品比没有更糟：下一轮接手方会把它当成真实交接读进去。
+
+### ✅ 测试
+
+- 全量 **57 文件 / 608 例通过**（6 skipped）。
+- `HandoffService.test.ts` **24 → 30 例**：signal 透传 RequestOptions、summary 取消不落盘、self 取消不重试不降级、半成品清理、migrate 取消不改历史、未取消时不误伤正常路径。
+- 破坏性验证：删掉 `self` 的取消检查 → 「不重试、不降级」用例红。
+
 ## [1.0.0-alpha.20] - 2026-10-27
 
 ### ✨ 新增

package/README.md

@@ -21,7 +21,7 @@ Desktop ──┘                    │
 types         ← pure types, zero business dependencies (incl. ToolEnv)
 config        ← ConfigManager + constants: config.json read/write + directory setup + factory defaults
 crud          ← capability-entity CRUD (Agent definitions; conversations/drafts are persisted by each consumer)
-runtime       ← model factory + Agent assembly + task handoff/migration (createModel / createAgent / SdkAgent / HandoffService / HandoffGuardPlugin)
+runtime       ← model factory + Agent assembly + task handoff/migration (cancellable via `AbortSignal`; createModel / createAgent / SdkAgent / HandoffService / HandoffGuardPlugin)
 scope         ← Scope orchestration container + ScopePlugin contract + PermissionEvaluator / disclosure + plugins/ (5 self-contained capability sources: discovery + tools + plugin)
 agent-plugins ← Agent plugins (autoMigrate, autoRefreshTools, contextGuard, unknownToolHint)
 shared        ← logging, errors
@@ -125,6 +125,8 @@ Conditionally injected based on the active model / config:
 
 Tool output protection: `AppConfig.maxToolOutput` (in characters, default 32768) is the unified ceiling for tool output. Each tool handles overflow itself — `exec` dumps `stdout.log` / `stderr.log` separately (returning head/tail previews per stream), `find_text` / `glob` / `ls` dump `result.json` (returning a head preview), and `read` only warns and suggests batched reads via `range`. Dumps go to `<tmpdir>/ai-zen/tool-output/<tool>-<timestamp>-<random>/`, one directory per call, with no self-cleanup. See [`docs/sdk-design-v1.md` §12](docs/sdk-design-v1.md).
 
+Interrupt strategies live in the config: `AppConfig.abortedMessageStrategy` (`keep` / `drop`, factory `keep` — the model can continue the half-sentence after an interrupt) and `AppConfig.abortedToolRoundStrategy` (`fill` / `drop`, factory `fill` — whole rounds go in or out, because `tool_calls` must pair with results). `createAgent()` reads them from `scope.config` when no explicit option is passed, keeping a single source of truth.
+
 ## Built-in Plugins
 
 | Plugin | Description |

package/README.zh.md

@@ -20,7 +20,7 @@ Desktop ──┘                    │
 types         ← 纯类型，零业务依赖（含 ToolEnv 工具环境）
 config        ← ConfigManager + constants：读写 config.json + 目录初始化 + 出厂默认
 crud          ← 能力实体 CRUD（Agent 定义等；会话/草稿已下放给各端自行持久化）
-runtime       ← 模型工厂 + Agent 组装 + 任务交接/迁移（createModel / createAgent / SdkAgent / HandoffService / HandoffGuardPlugin）
+runtime       ← 模型工厂 + Agent 组装 + 任务交接/迁移（可 `AbortSignal` 取消；createModel / createAgent / SdkAgent / HandoffService / HandoffGuardPlugin）
 scope         ← Scope 编排容器 + ScopePlugin 契约 + PermissionEvaluator / disclosure + plugins/（5 个自包含能力来源：发现 + 工具 + 插件）
 agent-plugins ← Agent 插件（autoMigrate、autoRefreshTools、contextGuard、unknownToolHint）
 shared        ← 日志、错误
@@ -124,6 +124,8 @@ await scope.dispose(); // 断开 MCP、释放插件资源
 
 工具输出保护：`AppConfig.maxToolOutput`（字符数，缺省 32768）是工具输出的统一上限，超限时由各工具自行处置——`exec` 分文件落盘 `stdout.log` / `stderr.log`（返回各流头尾预览），`find_text` / `glob` / `ls` 落盘 `result.json`（返回头部预览），`read` 仅警告并提示用 `range` 分批读取。落盘目录为 `<tmpdir>/ai-zen/tool-output/<工具名>-<时间戳>-<随机串>/`，每次调用独立、不自清理。详见 [`docs/sdk-design-v1.md` §12](docs/sdk-design-v1.md)。
 
+中断策略进配置：`AppConfig.abortedMessageStrategy`（`keep` / `drop`，出厂 `keep`——中断后模型能接着半截往下说）与 `AppConfig.abortedToolRoundStrategy`（`fill` / `drop`，出厂 `fill`——整轮进出，`tool_calls` 必须与结果配对）。`createAgent()` 不传参数时直接取 `scope.config`，于是策略只有一个真相源。
+
 ## 内置插件
 
 | 插件 | 说明 |

package/dist/config/constants.js

@@ -237,6 +237,11 @@ export const DEFAULT_APP_CONFIG = {
     defaultMigrationModel: "deepseek-flash",
     // 工具输出上限（字符数），与 DEFAULT_MAX_TOOL_OUTPUT 保持一致
     maxToolOutput: 32_768,
+    // 中断策略：出厂取「保留已输出的内容」—— 中断后模型能接着半截往下说，
+    // 而不是「失忆重来」（core 的库级默认是 drop，产品层认为那是坑）；
+    // 工具轮次保持整轮进出（fill），服务端要求 tool_calls 与结果一一配对。
+    abortedMessageStrategy: "keep",
+    abortedToolRoundStrategy: "fill",
 };
 // ---------------------------------------------------------------------------
 // 默认 MCP 配置（socket-pty 终端 MCP + chrome-devtools 浏览器调试 MCP）

package/dist/config/migrate.d.ts

@@ -58,10 +58,18 @@ export declare function migrateModelReasoning(model: Model): {
  * 迁移整个配置。只处理对话模型（`models`）——
  * 图片模型（`imageModels`）既没有上下文阈值、也没有思考概念。
  *
- * 同时清除已废弃的 `defaultModel`：模型的真相源已改为 `AgentDefinition.modelId`，
- * 配置级默认值连同字段一起消失（旧值先由 `ConfigManager.bootstrap()` 搬到默认 Agent 上）。
+ * 同时做两件字段级收敛：
+ * - 清除已废弃的 `defaultModel`（模型真相源已改为 `AgentDefinition.modelId`）；
+ * - 补齐中断策略（`abortedMessageStrategy` / `abortedToolRoundStrategy`）：把缺失或
+ *   非法值写成出厂默认。这样「配置即事实」——文件里写着的就是运行时用的，不再需要
+ *   使用方各自 `?? "keep"` 地兵分两路兜底。
  */
 export declare function migrateConfig(config: AppConfig): {
     config: AppConfig;
     changed: boolean;
 };
+/** 合法的中断策略取值（与 core 的枚举一致） */
+export declare const ABORTED_MESSAGE_STRATEGIES: readonly ["keep", "drop"];
+export declare const ABORTED_TOOL_ROUND_STRATEGIES: readonly ["fill", "drop"];
+/** 缺失 / 非法 → 出厂默认；返回是否有改动（直接改写传入对象） */
+export declare function normalizeAbortStrategies(config: AppConfig): boolean;

package/dist/config/migrate.js

@@ -103,8 +103,11 @@ export function migrateModelReasoning(model) {
  * 迁移整个配置。只处理对话模型（`models`）——
  * 图片模型（`imageModels`）既没有上下文阈值、也没有思考概念。
  *
- * 同时清除已废弃的 `defaultModel`：模型的真相源已改为 `AgentDefinition.modelId`，
- * 配置级默认值连同字段一起消失（旧值先由 `ConfigManager.bootstrap()` 搬到默认 Agent 上）。
+ * 同时做两件字段级收敛：
+ * - 清除已废弃的 `defaultModel`（模型真相源已改为 `AgentDefinition.modelId`）；
+ * - 补齐中断策略（`abortedMessageStrategy` / `abortedToolRoundStrategy`）：把缺失或
+ *   非法值写成出厂默认。这样「配置即事实」——文件里写着的就是运行时用的，不再需要
+ *   使用方各自 `?? "keep"` 地兵分两路兜底。
  */
 export function migrateConfig(config) {
     let changed = false;
@@ -121,7 +124,25 @@ export function migrateConfig(config) {
         delete next.defaultModel;
         changed = true;
     }
+    if (normalizeAbortStrategies(next))
+        changed = true;
     if (!changed)
         return { config, changed };
     return { config: next, changed };
 }
+/** 合法的中断策略取值（与 core 的枚举一致） */
+export const ABORTED_MESSAGE_STRATEGIES = ["keep", "drop"];
+export const ABORTED_TOOL_ROUND_STRATEGIES = ["fill", "drop"];
+/** 缺失 / 非法 → 出厂默认；返回是否有改动（直接改写传入对象） */
+export function normalizeAbortStrategies(config) {
+    let changed = false;
+    if (!ABORTED_MESSAGE_STRATEGIES.includes(config.abortedMessageStrategy)) {
+        config.abortedMessageStrategy = DEFAULT_APP_CONFIG.abortedMessageStrategy;
+        changed = true;
+    }
+    if (!ABORTED_TOOL_ROUND_STRATEGIES.includes(config.abortedToolRoundStrategy)) {
+        config.abortedToolRoundStrategy = DEFAULT_APP_CONFIG.abortedToolRoundStrategy;
+        changed = true;
+    }
+    return changed;
+}

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export { McpConnectionManager } from "./scope/plugins/mcp/McpConnectionManager.j
 export type { McpConnectOptions } from "./scope/plugins/mcp/McpConnectionManager.js";
 export { SdkCallbackTool } from "./scope/plugins/builtin/SdkCallbackTool.js";
 export type { SdkCallbackToolOptions } from "./scope/plugins/builtin/SdkCallbackTool.js";
-export { HandoffService } from "./runtime/HandoffService.js";
+export { HandoffAbortedError, HandoffService } from "./runtime/HandoffService.js";
 export type { HandoffContext, HandoffMode, HandoffParams, HandoffServiceOptions, MigrateParams, MigrationStrategy, } from "./runtime/HandoffService.js";
 export { HandoffGuardPlugin } from "./runtime/HandoffGuardPlugin.js";
 export { AutoMigratePlugin } from "./agent-plugins/AutoMigratePlugin.js";

package/dist/index.js

@@ -33,7 +33,7 @@ export { SdkAgent } from "./runtime/SdkAgent.js";
 export { createAgent } from "./runtime/createAgent.js";
 export { McpConnectionManager } from "./scope/plugins/mcp/McpConnectionManager.js";
 export { SdkCallbackTool } from "./scope/plugins/builtin/SdkCallbackTool.js";
-export { HandoffService } from "./runtime/HandoffService.js";
+export { HandoffAbortedError, HandoffService } from "./runtime/HandoffService.js";
 export { HandoffGuardPlugin } from "./runtime/HandoffGuardPlugin.js";
 // 插件
 export { AutoMigratePlugin } from "./agent-plugins/AutoMigratePlugin.js";

package/dist/runtime/HandoffService.d.ts

@@ -18,6 +18,18 @@ export type HandoffMode = "self" | "summary";
  * - `prune`：物理剔除历史，只保留 `definition.messages`（系统提示等模板）+ 交接断点。
  */
 export type MigrationStrategy = "omit" | "prune";
+/**
+ * 交接被调用方取消（`AbortSignal` 触发）。
+ *
+ * 单独成类型而不是复用 `Error`，原因有两个：
+ *   - 调用方（如 TUI）要把「用户按了 Ctrl+C」与「交接真的失败了」区分开 ——
+ *     前者应静默收尾并提示「已取消」，后者才该报错；
+ *   - 它**不可降级**：`self` 被取消后绝不能退到 `summary` 再跑一遍。
+ *     把「用户中止」当成「模型没写出文档」，会白白多烧一轮全量输入。
+ */
+export declare class HandoffAbortedError extends Error {
+    constructor();
+}
 /**
  * 一次交接的完整上下文 —— 贯穿「交接前 → 写文档 → 迁移后」，供钩子与调用方使用。
  */
@@ -86,6 +98,15 @@ export interface HandoffParams {
     handoffTokens?: number;
     /** 会话 id（可选，用于交接文件名，便于回溯） */
     conversationId?: string;
+    /**
+     * 取消信号（可选）。触发后交接**立即停止且不降级**，抛 {@link HandoffAbortedError}。
+     *
+     * 两种执行者都要认它：
+     *   - `summary`：直接作为 `chat.completions.create` 的 RequestOptions 传下去，
+     *     请求会真的被中断（否则该请求根本无从取消）；
+     *   - `self`：`agent.abort()` 不抛错，所以每个 `send()` 之后要主动检查 `aborted`。
+     */
+    signal?: AbortSignal;
 }
 /** `migrate()` 参数 */
 export interface MigrateParams extends HandoffParams {
@@ -174,6 +195,25 @@ export declare class HandoffService {
     migrate(params: MigrateParams): Promise<HandoffContext>;
     /** 串行化 + 防重入：交接与迁移共用同一把锁 */
     private withBusy;
+    /**
+     * 把底层各种「取消」形态统一成 {@link HandoffAbortedError}。
+     *
+     * 取消可能从三处冒上来：`self` 回合后的主动检查（已是 HandoffAbortedError）、
+     * `summary` 请求被 abort 时 OpenAI SDK 抛的 `APIUserAbortError`、以及
+     * `readSkillContent` 这类前置 await 期间被取消。调用方只需要认一个类型。
+     */
+    private runCatchingAbort;
+    /** 取消点检查：每跨过一个阶段就确认一次，避免取消后继续往下一步冲 */
+    private throwIfAborted;
+    private fileExists;
+    /**
+     * 取消后清掉半成品文档。
+     *
+     * 只删「本次新建」的文件：交接文件名含时间戳，正常不会撞已有文件，但调用方也
+     * 可以把 `handoffDir` 指向人工目录；不管怎样都不该删掉别人的文件。
+     * 留着半成品更糟 —— 下一轮接手方会把不完整的内容当成真实交接读进去。
+     */
+    private discardPartialFile;
     private runHandoff;
     /** 自交接是否可用：需要 `write` 工具 + `send` 能力 */
     private supportsSelfHandoff;
@@ -183,6 +223,12 @@ export declare class HandoffService {
      * 失败判定（任一成立即视为失败，交由上层单向降级 summary）：
      *   - 文件不存在 / 小于阈值；
      *   - 模型/工具链抛错（例如没有权限、被护栏中断）。
+     *
+     * **取消不算失败**：`signal` 已触发时抛 {@link HandoffAbortedError}，既不走
+     * 「文件没写好→重试一次」也不降级 summary。 这条分支必须显式写：
+     * `agent.abort()` 不抛错（core 把消息标记为 Aborted 后正常返回），否则「用户
+     * 按了 Ctrl+C」会被下面的文件校验误判成「模型没写出文档」，于是重试一轮、再降级
+     * 一轮 —— 用户以为取消了，实际多烧了两轮全量输入。
      */
     private runSelfHandoff;
     /** 独立摘要：一次模型调用，用同一份 Skill 正文作为规范 */

package/dist/runtime/HandoffService.js

@@ -5,6 +5,35 @@ 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";
+}
 /**
  * 任务交接服务。
  *
@@ -145,7 +174,7 @@ export class HandoffService {
      * 用户可继续让 agent 打磨这份文档（重写同一路径即可）。
      */
     async handoff(params) {
-        return this.withBusy(() => this.runHandoff(params, false));
+        return this.withBusy(() => this.runCatchingAbort(params, false));
     }
     /**
      * 交接 + 开新会话（`/migrate`、自动迁移）。
@@ -156,7 +185,7 @@ export class HandoffService {
      */
     async migrate(params) {
         return this.withBusy(async () => {
-            const ctx = await this.runHandoff(params, true);
+            const ctx = await this.runCatchingAbort(params, true);
             const { agent } = ctx;
             const strategy = params.strategy ?? this.defaultStrategy;
             const breakpointMessages = HandoffService.createPostMessages(ctx.handoffPath);
@@ -193,8 +222,58 @@ export class HandoffService {
             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 } = params;
+        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;
@@ -213,6 +292,7 @@ export class HandoffService {
             historyText: "",
         };
         await this.safeHook(this.onBeforeHandoff, beforeCtx);
+        this.throwIfAborted(signal);
         // ---- 执行者：self 优先，失败/不可用则单向降级 summary ----
         let mode = requestedMode;
         let handoffDoc;
@@ -222,7 +302,7 @@ export class HandoffService {
             mode = "summary";
         }
         if (mode === "self") {
-            const ok = await this.runSelfHandoff(agent, handoffPath);
+            const ok = await this.runSelfHandoff(agent, handoffPath, signal);
             if (!ok) {
                 this.logger.warn("[handoff] 自交接失败，降级为独立摘要模式");
                 mode = "summary";
@@ -230,9 +310,11 @@ export class HandoffService {
         }
         if (mode === "summary") {
             historyText = HandoffService.serializeMessages(agent.messages.filter((m) => !m.omit));
-            handoffDoc = await this.generateSummary(agent, historyText, handoffPath);
+            handoffDoc = await this.generateSummary(agent, historyText, handoffPath, signal);
             await this.writeHandoffFile(handoffPath, handoffDoc);
         }
+        // 最后一道取消点：即使两步都跑完，只要期间被取消就不能算成功
+        this.throwIfAborted(signal);
         const ctx = {
             agent,
             mode,
@@ -261,11 +343,19 @@ export class HandoffService {
      * 失败判定（任一成立即视为失败，交由上层单向降级 summary）：
      *   - 文件不存在 / 小于阈值；
      *   - 模型/工具链抛错（例如没有权限、被护栏中断）。
+     *
+     * **取消不算失败**：`signal` 已触发时抛 {@link HandoffAbortedError}，既不走
+     * 「文件没写好→重试一次」也不降级 summary。 这条分支必须显式写：
+     * `agent.abort()` 不抛错（core 把消息标记为 Aborted 后正常返回），否则「用户
+     * 按了 Ctrl+C」会被下面的文件校验误判成「模型没写出文档」，于是重试一轮、再降级
+     * 一轮 —— 用户以为取消了，实际多烧了两轮全量输入。
      */
-    async runSelfHandoff(agent, handoffPath) {
+    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 判定严重超限，
@@ -281,6 +371,8 @@ export class HandoffService {
                 handoffPath,
                 toolsAvailable: true,
             }));
+            // `agent.abort()` 不抛错，必须主动检查（见方法注释）
+            this.throwIfAborted(signal);
             if (await this.isHandoffFileReady(handoffPath))
                 return true;
             this.logger.warn(`[handoff] 交接文档缺失或过小，重试一次：${handoffPath}`);
@@ -288,9 +380,14 @@ export class HandoffService {
                 `交接文档不存在或内容过少，无法交付：${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;
         }
@@ -299,11 +396,14 @@ export class HandoffService {
         }
     }
     /** 独立摘要：一次模型调用，用同一份 Skill 正文作为规范 */
-    async generateSummary(agent, historyText, handoffPath) {
+    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 ?? {}),
@@ -318,7 +418,7 @@ export class HandoffService {
                 },
                 { role: "user", content: historyText },
             ],
-        });
+        }, signal ? { signal } : undefined);
         const handoffDoc = response.choices[0]?.message?.content;
         if (!handoffDoc || !handoffDoc.trim()) {
             throw new Error("未能生成任务交接文档");

package/dist/runtime/createAgent.d.ts

@@ -2,7 +2,10 @@ import { SdkAgent } from "./SdkAgent.js";
 import type { Scope } from "../scope/Scope.js";
 import type { AbortedMessageStrategy, AbortedToolRoundStrategy } from "@ai-zen/agents-core";
 /**
- * `createAgent` 的可选行为开关（不传则全部沿用 core 默认值）。
+ * `createAgent` 的可选行为开关。
+ *
+ * 不传时先取 `scope.config`（`config.json`）里的同名配置，再往下才是 core 默认值：
+ * 中断策略属于**产品配置**，调用方不该自己读配置再转一道参数。
  */
 export interface CreateAgentOptions {
     /** 工具轮次被中断（或结果不完整）时的归一策略（core 默认 `fill`） */
@@ -10,8 +13,9 @@ export interface CreateAgentOptions {
     /** `fill` 策略下，未完成工具结果的填充原因 */
     abortedToolRoundReason?: string;
     /**
-     * 被中断的 assistant 消息（已输出的内容 / 思考）如何处置（core 默认 `drop`）。
-     * 传 `keep` 可让模型在下一轮接着半截往下说，而不是忘掉自己说过什么。
+     * 被中断的 assistant 消息（已输出的内容 / 思考）如何处置（未传时取 `scope.config`，
+     * 再缺则用 core 默认 `drop`）。
+     * `keep` 可让模型在下一轮接着半截往下说，而不是忘掉自己说过什么。
      */
     abortedMessageStrategy?: AbortedMessageStrategy;
 }

package/dist/runtime/createAgent.js

@@ -40,10 +40,12 @@ export async function createAgent(scope, agentId, options = {}) {
         // 快照后，运行时改动只作用于会话副本，模板保持纯净。
         messages: [...(definition.messages ?? [])],
         tools,
-        // 中断相关策略：不传则由 core 取默认值（工具轮次 fill / 消息保留 drop）
-        abortedToolRoundStrategy: options.abortedToolRoundStrategy,
+        // 中断相关策略：**显式参数 > `scope.config` > core 默认值**。
+        // 中间那一层是「配置即事实」：策略写在 `config.json` 里，各端（CLI / Desktop）
+        // 不必自己读配置再转成参数，子 Agent 创建时也能自然继承同一份策略。
+        abortedToolRoundStrategy: options.abortedToolRoundStrategy ?? scope.config?.abortedToolRoundStrategy,
         abortedToolRoundReason: options.abortedToolRoundReason,
-        abortedMessageStrategy: options.abortedMessageStrategy,
+        abortedMessageStrategy: options.abortedMessageStrategy ?? scope.config?.abortedMessageStrategy,
     });
     return agent;
 }

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-import type { AgentNS } from "@ai-zen/agents-core";
+import type { AgentNS, AbortedMessageStrategy, AbortedToolRoundStrategy } from "@ai-zen/agents-core";
 /** 单维度权限策略：allow 或 deny 互斥 */
 export type PermissionPolicy = {
     allow: string[];
@@ -200,6 +200,27 @@ export interface AppConfig {
      * （如 read/find_text 对 300KB 文件的读取上限）。
      */
     maxToolOutput?: number;
+    /**
+     * 被中断的 assistant 消息（已输出的思考 / 正文）如何处置。
+     *
+     * - `keep`：保留已输出的部分（恢复为 `Completed`）—— 模型下一轮能接着半截往下说，
+     *   不会「失忆重来」。**出厂默认**。
+     * - `drop`：丢弃（保持 `Aborted`，不进下一轮上下文）。core 的库级默认。
+     *
+     * 只管**不带工具调用**的消息；工具轮次由 {@link abortedToolRoundStrategy} 决定。
+     * 缺省时由 `createAgent()` 回落 core 默认值（`drop`），出厂配置已写 `keep`。
+     */
+    abortedMessageStrategy?: AbortedMessageStrategy;
+    /**
+     * 被中断 / 结果不完整的工具轮次如何归一。
+     *
+     * - `fill`：保留整轮（assistant 恢复为 `Completed`，未完成的结果补原因）——**出厂默认**，
+     *   服务端要求「N 个 tool_calls 对 N 条结果」，整轮进出才不会报错。
+     * - `drop`：整轮出列（assistant 与其结果都不发给模型）。
+     *
+     * 缺省时由 `createAgent()` 回落 core 默认值（`fill`）。
+     */
+    abortedToolRoundStrategy?: AbortedToolRoundStrategy;
 }
 /**
  * 工具环境 — Scope 的能力插件在实例化内置工具时注入的环境信息。

package/package.json

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