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

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [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

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        ← 日志、错误

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/package.json

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