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

package/dist/index.js

@@ -17,16 +17,24 @@ export { SubAgentsScopePlugin } from "./scope/plugins/subagents/SubAgentsScopePl
 export { allInOne } from "./scope/plugins/allInOne.js";
 // 配置 — ConfigManager
 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";
+// 出厂资产 — 出厂 Skill（随版本释放到 <basePath>/skills/）
+export { FACTORY_SKILLS, HANDOFF_SKILL_ID, FALLBACK_HANDOFF_TEMPLATE, isCustomSkill, } from "./config/factory-skills.js";
+// 出厂资产 — 思考策略表（随版本释放到 <basePath>/reasoning-presets.json）
+// 表是跨客户端共享的「定义 + 出厂默认」，SDK 不拿它生成请求参数
+export { FACTORY_REASONING_PRESETS, REASONING_PRESETS_FILE, } from "./config/reasoning-presets.js";
 // CRUD — 实体仓储（仅 Agent 定义等能力实体）
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
+// 文件 → 内容块（统一入口）— 上层应用构造媒体消息时请走这里，不要自己判断上传还是内联
+export { fileToContentSection, resolveModelAndEndpoint, supportsFilesApi, mimeOf, toDataUrl, base64ByteLength, contentHash, clearUploadCache, MIME_BY_EXT, DEFAULT_MAX_INLINE_BYTES, } from "./shared/content-blocks.js";
 // 运行时
 export { createModel } from "./runtime/createModel.js";
 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 { TaskMigrationService } from "./runtime/TaskMigrationService.js";
+export { HandoffAbortedError, HandoffService } from "./runtime/HandoffService.js";
+export { HandoffGuardPlugin } from "./runtime/HandoffGuardPlugin.js";
 // 插件
 export { AutoMigratePlugin } from "./agent-plugins/AutoMigratePlugin.js";
 export { AutoRefreshToolsPlugin } from "./agent-plugins/AutoRefreshToolsPlugin.js";
@@ -34,7 +42,7 @@ export { ContextGuardPlugin } from "./agent-plugins/ContextGuardPlugin.js";
 export { UnknownToolHintPlugin } from "./agent-plugins/UnknownToolHintPlugin.js";
 // 工具 — 内置工具类 + 动态工具工厂
 export { BUILTIN_TOOL_CLASSES } from "./scope/plugins/builtin/index.js";
-export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./scope/plugins/builtin/index.js";
+export { CwdTool, ReadTool, InspectFileTool, WriteTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, SpawnTool, SleepTool, } from "./scope/plugins/builtin/index.js";
 export { GenerateImageTool } from "./scope/plugins/builtin/GenerateImageTool.js";
 export { ViewImageTool } from "./scope/plugins/builtin/ViewImageTool.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./scope/plugins/skills/skillTools.js";

package/dist/runtime/HandoffGuardPlugin.d.ts

@@ -0,0 +1,35 @@
+import type { AgentPlugin, ToolCallContext } from "@ai-zen/agents-core";
+/**
+ * 交接回合的工具守卫 —— 保证「原 agent 停下手头一切工作」不只是提示词约定。
+ *
+ * 交接由**同一个 agent** 在自己的会话里完成，它天然有继续干活的动力。
+ * 本插件在交接回合期间拦截写入类工具，只放行对交接文档那一份文件的写入：
+ *   - `write`：仅当目标路径（按交接时给定的 cwd 归一后）等于交接文档路径时放行；
+ *   - `edit` / `batch_edit` / `rm` / `rename` / `mkdir` / `copy`：一律拒绝；
+ *   - 读取类工具与其他工具：放行。
+ *
+ * 拒绝方式是**软拒绝**（返回字符串）：core 的 `onToolCall` 语义会把该字符串作为
+ * 工具结果回给模型并继续下一轮，因此模型能读到引导（「只允许写交接文档」）并转回正题。
+ * 反例：抛错会让该工具结果标记为 Error 且 `isPreventDefault`，整轮交接直接中断。
+ *
+ * 边界（必须如实记录，不要误以为是安全边界）：
+ *   - **挡不住 `exec`**：`echo > file`、`cat > file <<EOF` 永远能绕过。本插件降低的是
+ *     「顺手改代码」的误操作概率，不是沙箱。
+ *   - 一次性：`arm()` 后生效，`disarm()` 后完全让行。`Agent.use()` 没有移除 API，
+ *     故用「同一实例 + 开关」而非反复注册，避免插件数组无限增长。
+ */
+export declare class HandoffGuardPlugin implements AgentPlugin {
+    /** 写入类工具（除白名单的 write 外一律拒绝） */
+    private static readonly WRITE_TOOLS;
+    /** 当前交接文档绝对路径；undefined 表示未处于交接回合（完全让行） */
+    private handoffPath?;
+    /** 相对路径解析基准（交接时 agent 的 cwd） */
+    private cwd;
+    /** 进入交接回合：仅允许写入 handoffPath（相对路径按 cwd 归一） */
+    arm(handoffPath: string, cwd?: string): void;
+    /** 离开交接回合：恢复为完全让行 */
+    disarm(): void;
+    /** 是否处于交接回合（供上层/测试观察） */
+    get armed(): boolean;
+    onToolCall(ctx: ToolCallContext): string | undefined;
+}

package/dist/runtime/HandoffGuardPlugin.js

@@ -0,0 +1,65 @@
+import { resolve as resolvePath } from "node:path";
+/**
+ * 交接回合的工具守卫 —— 保证「原 agent 停下手头一切工作」不只是提示词约定。
+ *
+ * 交接由**同一个 agent** 在自己的会话里完成，它天然有继续干活的动力。
+ * 本插件在交接回合期间拦截写入类工具，只放行对交接文档那一份文件的写入：
+ *   - `write`：仅当目标路径（按交接时给定的 cwd 归一后）等于交接文档路径时放行；
+ *   - `edit` / `batch_edit` / `rm` / `rename` / `mkdir` / `copy`：一律拒绝；
+ *   - 读取类工具与其他工具：放行。
+ *
+ * 拒绝方式是**软拒绝**（返回字符串）：core 的 `onToolCall` 语义会把该字符串作为
+ * 工具结果回给模型并继续下一轮，因此模型能读到引导（「只允许写交接文档」）并转回正题。
+ * 反例：抛错会让该工具结果标记为 Error 且 `isPreventDefault`，整轮交接直接中断。
+ *
+ * 边界（必须如实记录，不要误以为是安全边界）：
+ *   - **挡不住 `exec`**：`echo > file`、`cat > file <<EOF` 永远能绕过。本插件降低的是
+ *     「顺手改代码」的误操作概率，不是沙箱。
+ *   - 一次性：`arm()` 后生效，`disarm()` 后完全让行。`Agent.use()` 没有移除 API，
+ *     故用「同一实例 + 开关」而非反复注册，避免插件数组无限增长。
+ */
+export class HandoffGuardPlugin {
+    /** 写入类工具（除白名单的 write 外一律拒绝） */
+    static WRITE_TOOLS = new Set([
+        "edit",
+        "batch_edit",
+        "rm",
+        "rename",
+        "mkdir",
+        "copy",
+    ]);
+    /** 当前交接文档绝对路径；undefined 表示未处于交接回合（完全让行） */
+    handoffPath;
+    /** 相对路径解析基准（交接时 agent 的 cwd） */
+    cwd = process.cwd();
+    /** 进入交接回合：仅允许写入 handoffPath（相对路径按 cwd 归一） */
+    arm(handoffPath, cwd) {
+        this.cwd = cwd ? resolvePath(cwd) : process.cwd();
+        this.handoffPath = resolvePath(this.cwd, handoffPath);
+    }
+    /** 离开交接回合：恢复为完全让行 */
+    disarm() {
+        this.handoffPath = undefined;
+    }
+    /** 是否处于交接回合（供上层/测试观察） */
+    get armed() {
+        return this.handoffPath !== undefined;
+    }
+    onToolCall(ctx) {
+        const handoffPath = this.handoffPath;
+        if (handoffPath == null)
+            return;
+        const name = ctx.tool_call?.function?.name ?? "";
+        if (name === "write") {
+            const raw = ctx.parsedArgs?.path;
+            if (typeof raw === "string" && resolvePath(this.cwd, raw) === handoffPath) {
+                return;
+            }
+            return `交接回合只允许写交接文档：${handoffPath}（write 的 path 请原样使用该路径），请立即开始撰写。`;
+        }
+        if (HandoffGuardPlugin.WRITE_TOOLS.has(name)) {
+            return `交接回合禁止修改工作区（${name}）：你的唯一任务是把交接文档写入 ${handoffPath}。`;
+        }
+        return;
+    }
+}

package/dist/runtime/HandoffService.d.ts

@@ -0,0 +1,245 @@
+import { AgentNS } from "@ai-zen/agents-core";
+import type OpenAI from "openai";
+import { type Logger } from "../shared/logger.js";
+import type { SdkAgent } from "./SdkAgent.js";
+/**
+ * 交接文档的执行者。
+ *
+ * - `self`：**原 agent 在自己的会话里**停工后写（默认）。上下文完整、可用工具核实真实状态，
+ *   产出质量最好；代价是多 1~2 次全量输入。
+ * - `summary`：一次独立的模型调用，把序列化后的历史摘要成交接文档（无工具、无原会话上下文）。
+ *   便宜、确定，但保真度低——它是**逃生模式**，也是 `self` 失败时的单向降级目标。
+ */
+export type HandoffMode = "self" | "summary";
+/**
+ * 迁移后的历史处理策略。
+ *
+ * - `omit`（默认）：历史消息标记 `omit: true`，仍留在 `agent.messages` 可审计/回放，但不再发给模型；
+ * - `prune`：物理剔除历史，只保留 `definition.messages`（系统提示等模板）+ 交接断点。
+ */
+export type MigrationStrategy = "omit" | "prune";
+/**
+ * 交接被调用方取消（`AbortSignal` 触发）。
+ *
+ * 单独成类型而不是复用 `Error`，原因有两个：
+ *   - 调用方（如 TUI）要把「用户按了 Ctrl+C」与「交接真的失败了」区分开 ——
+ *     前者应静默收尾并提示「已取消」，后者才该报错；
+ *   - 它**不可降级**：`self` 被取消后绝不能退到 `summary` 再跑一遍。
+ *     把「用户中止」当成「模型没写出文档」，会白白多烧一轮全量输入。
+ */
+export declare class HandoffAbortedError extends Error {
+    constructor();
+}
+/**
+ * 一次交接的完整上下文 —— 贯穿「交接前 → 写文档 → 迁移后」，供钩子与调用方使用。
+ */
+export interface HandoffContext {
+    /** 当前对话 Agent（引用不变，仅替换消息列表） */
+    agent: SdkAgent;
+    /** **实际**使用的执行者（`self` 失败降级后会是 `summary`） */
+    mode: HandoffMode;
+    /** 调用方请求的执行者 */
+    requestedMode: HandoffMode;
+    /** 交接文档绝对路径 */
+    handoffPath: string;
+    /** 交接文档正文：仅 `summary` 模式由模型返回；`self` 模式不读盘，故为 undefined */
+    handoffDoc?: string;
+    /** 生成文档所用模型名 */
+    model: string;
+    /** 当前 prompt token 用量（自动迁移时由插件提供；手动触发可省略） */
+    promptTokens?: number;
+    /** 上下文阈值（自动迁移时由插件提供；手动触发可省略） */
+    handoffTokens?: number;
+    /** 本次是否会在交接后开新会话（`migrate()` 为 true，`handoff()` 为 false）。钩子据此区分两种语义 */
+    migrating: boolean;
+    /** 交接前消息总数 */
+    messageCountBefore: number;
+    /** 序列化后的历史（仅 `summary` 模式填充；`self` 模式为空串） */
+    historyText: string;
+}
+/** 交接服务构造参数 */
+export interface HandoffServiceOptions {
+    /**
+     * 交接文档目录（绝对路径推荐）。
+     * 默认按进程 cwd 推导为 `<cwd>/.ai-zen/handoffs`；多工作区场景请显式传入，勿依赖默认值。
+     */
+    handoffDir?: string;
+    /** 默认执行者，默认 `self`（可被 `handoff()/migrate()` 的参数覆盖） */
+    mode?: HandoffMode;
+    /** 迁移后历史处理策略，默认 `omit`（可被 `migrate()` 的参数覆盖） */
+    strategy?: MigrationStrategy;
+    /** 查找 `handoff` Skill 的目录列表（优先级从高到低）；为空则直接用兜底模板 */
+    skillDirs?: string[];
+    /** `summary` 模式所用客户端（可选；未传则回退到 agent.client） */
+    client?: OpenAI;
+    /** `summary` 模式所用模型名（可选；未传则回退到 agent.model） */
+    model?: string;
+    /** `summary` 模式所用模型参数（可选；未传则回退到 agent.modelConfig） */
+    modelConfig?: Record<string, unknown>;
+    /** 交接文档有效性阈值（字节），默认 400。低于此值视为「没写出来」 */
+    minHandoffBytes?: number;
+    /** 交接回合开始前触发（此时 `agent.messages` 仍是完整旧历史） */
+    onBeforeHandoff?: (ctx: HandoffContext) => void | Promise<void>;
+    /** 交接文档写好后、迁移（清历史）之前触发 */
+    onHandoff?: (ctx: HandoffContext) => void | Promise<void>;
+    /** 迁移完成后触发（此时交接断点已注入 `agent.messages`） */
+    onMigrated?: (ctx: HandoffContext) => void | Promise<void>;
+    /** 可注入日志（可选，默认使用全局单例） */
+    logger?: Logger;
+}
+/** `handoff()` 参数 */
+export interface HandoffParams {
+    agent: SdkAgent;
+    /** 本次执行者（覆盖构造时的默认值） */
+    mode?: HandoffMode;
+    /** 当前 prompt token 用量（可选，仅透传给钩子） */
+    promptTokens?: number;
+    /** 上下文阈值（可选，仅透传给钩子） */
+    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 {
+    /** 本次迁移的历史处理策略（覆盖构造时的默认值） */
+    strategy?: MigrationStrategy;
+}
+/**
+ * 任务交接服务。
+ *
+ * 职责分层（这是本模块唯一的设计主线）：
+ *   - `handoff()`：**只产出交接文档**（停工 → 写文档 → 校验 → 失败降级），不动会话；
+ *   - `migrate()`：`handoff()` 之后清历史并开新会话（原「任务迁移」语义）。
+ *
+ * 模板的唯一真相源是 `handoff` Skill（`SKILL.md`）；代码只负责
+ * 「读正文 → 注入 → 校验文件 → 读不到时用兜底模板」，不持有第二份章节清单。
+ *
+ * 重入：`handoff()` 与 `migrate()` 共用 `busy` 标志。交接回合本身也是一次 `send()`，
+ * 若不在 busy 期间让 `AutoMigratePlugin` / `ContextGuardPlugin` 让行，就会「交接触发迁移、
+ * 迁移再触发交接」无限递归，或在最满的时刻被护栏直接击杀。
+ */
+export declare class HandoffService {
+    /** 交接文档兜底模板（仅在读不到 Skill 时使用） */
+    static readonly FALLBACK_TEMPLATE: string;
+    private readonly handoffDirPath;
+    private readonly defaultMode;
+    private readonly defaultStrategy;
+    private readonly skillDirs;
+    private readonly client?;
+    private readonly model?;
+    private readonly modelConfig?;
+    private readonly minHandoffBytes;
+    private readonly onBeforeHandoff?;
+    private readonly onHandoff?;
+    private readonly onMigrated?;
+    private readonly logger;
+    /** 交接/迁移进行中标志（插件据此让行） */
+    private _busy;
+    /** 交接回合的工具守卫（同一实例复用 + arm/disarm，避免插件数组无限增长） */
+    private guard?;
+    /** 已注册过守卫的 agent（每个 agent 只 use 一次） */
+    private readonly guardedAgents;
+    constructor(options?: HandoffServiceOptions);
+    /** 是否正在交接/迁移（`AutoMigratePlugin` / `ContextGuardPlugin` 据此让行） */
+    get busy(): boolean;
+    /** 交接文档目录 */
+    get handoffDir(): string;
+    /**
+     * 交接文件名：`<YYYYMMDD-HHmmss>-<会话id前8位>.md`（本地时间，便于人眼归档）。
+     */
+    static createHandoffFileName(date?: Date, conversationId?: string): string;
+    /**
+     * 拼装「本轮交接」指令：`[Skill 正文] + [本次交接参数]`。
+     *
+     * 不在 Skill 正文里发明占位符（本体系没有模板变量引擎），参数一律由代码拼在后面，
+     * 这样 Skill 只讲「怎么写」、代码只讲「写到哪、有什么能力」。
+     */
+    static createHandoffInstruction(params: {
+        skillContent: string;
+        handoffPath: string;
+        /** 执行者是否具备工具能力（`summary` 模式为 false） */
+        toolsAvailable: boolean;
+    }): string;
+    /**
+     * 生成迁移后追加的「交接断点」消息（role=user）：只给路径，让接手方自己 read。
+     *
+     * 为什么不内联全文：接手方第一次真正需要的是「去哪里取交接」，读一次文件的输入成本
+     * 与内联全文相当，但内联会让每条请求都携带全文；路径方案把成本推迟到真正需要时。
+     */
+    static createPostMessages(handoffPath: string): AgentNS.Message[];
+    /** 序列化消息为 `[role]: content` 文本（仅 `summary` 模式使用） */
+    static serializeMessages(messages: AgentNS.Message[]): string;
+    /**
+     * 只产出交接文档，**不改动会话**（`/handoff`）。
+     *
+     * 不清理历史：交接回合（指令 + 工具调用 + 回执）会留在 `agent.messages` 里，
+     * 用户可继续让 agent 打磨这份文档（重写同一路径即可）。
+     */
+    handoff(params: HandoffParams): Promise<HandoffContext>;
+    /**
+     * 交接 + 开新会话（`/migrate`、自动迁移）。
+     *
+     * 策略（`strategy`）：
+     *   - `omit`（默认）：历史标记 `omit: true`（保留可审计），末尾追加交接断点；
+     *   - `prune`：物理剔除历史，只留 `definition.messages` + 交接断点。
+     */
+    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;
+    /**
+     * 自交接回合：让原 agent 停工、核实、写文档，并校验文件确实落盘。
+     *
+     * 失败判定（任一成立即视为失败，交由上层单向降级 summary）：
+     *   - 文件不存在 / 小于阈值；
+     *   - 模型/工具链抛错（例如没有权限、被护栏中断）。
+     *
+     * **取消不算失败**：`signal` 已触发时抛 {@link HandoffAbortedError}，既不走
+     * 「文件没写好→重试一次」也不降级 summary。 这条分支必须显式写：
+     * `agent.abort()` 不抛错（core 把消息标记为 Aborted 后正常返回），否则「用户
+     * 按了 Ctrl+C」会被下面的文件校验误判成「模型没写出文档」，于是重试一轮、再降级
+     * 一轮 —— 用户以为取消了，实际多烧了两轮全量输入。
+     */
+    private runSelfHandoff;
+    /** 独立摘要：一次模型调用，用同一份 Skill 正文作为规范 */
+    private generateSummary;
+    /** 落盘（仅 `summary` 模式需要；`self` 模式由 agent 的 write 工具完成） */
+    private writeHandoffFile;
+    /** 交接文档是否可用：文件存在且不小于阈值（不读内容，避免二次读取） */ private isHandoffFileReady;
+    /** 读取 `handoff` Skill 正文；读不到时回落到兜底模板 */
+    private readSkillContent;
+    /** 守卫按 agent 注册一次（`Agent.use()` 无移除 API，故复用实例 + 开关） */
+    private ensureGuard;
+    /** 钩子容错：抛错只记录，不中断交接（与既有迁移钩子语义一致） */
+    private safeHook;
+}