@ai-zen/agents-sdk 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/config/factory-skills.js

@@ -0,0 +1,126 @@
+/**
+ * 出厂 Skill 资产 —— 随 SDK 版本释放到 `<basePath>/skills/<id>/SKILL.md`。
+ *
+ * 为什么以 TS 字符串常量内联、而不是独立 .md 文件：
+ * SDK 用 `tsc` 直接编译，不拷贝非 TS 资源；内容内联后 `dist/` 天然携带，
+ * 无需额外打包步骤，也不依赖包内相对资源路径。
+ *
+ * 覆盖策略（与 `syncManagedModels` 同构）：
+ *   - 磁盘上的 SKILL.md frontmatter 里写了 `custom: "true"` → 视为用户自有，永不被覆盖；
+ *   - 否则每次 `ConfigManager.bootstrap()` 同步为当前版本内容（模板属于产品行为，
+ *     改进了就要让老用户吃到）。
+ */
+/** 交接 Skill 的 id（目录名 = frontmatter name） */
+export const HANDOFF_SKILL_ID = "handoff";
+/**
+ * 交接文档兜底模板。
+ *
+ * 仅在磁盘上读不到 `handoff` Skill 时使用（用户删除 / 目录不可读）。
+ * 它是**保险丝**，不是第二真相源：正常路径下模板一律来自 SKILL.md。
+ */
+export const FALLBACK_HANDOFF_TEMPLATE = [
+    "# 交接文档",
+    "",
+    "立即停工：不再实现任何功能、不继续未完成任务、不向用户提问。",
+    "唯一任务是：核实当前真实状态 → 把交接文档写到「本次交接参数」给出的路径。",
+    "",
+    "## 💬 对话断点",
+    "## 🎯 任务目标",
+    "## 📊 当前状态",
+    "## ✅ 已完成",
+    "## 📋 未完成",
+    "## 🧠 关键决策",
+    "## ⚠️ 约束与偏好",
+    "## 📁 文件索引",
+    "## 🔔 接手第一步",
+    "",
+    "无法核实的信息写「⚠️ 未核实」，禁止推测。",
+].join("\n");
+/** 出厂 Skill：交接（handoff） */
+const HANDOFF_SKILL = `---
+name: handoff
+description: 编写任务交接文档——对话停手离场时，把任务目标、当前真实状态、关键决策与下一步写成一份可被他人直接接手的文档。
+metadata:
+  custom: "false"
+---
+
+# 交接文档书写规范
+
+## 何时适用
+
+上下文即将超限触发任务迁移、用户明确要求「写交接文档」、或你被要求「交班」时。
+
+## 铁律（违反即视为失败）
+
+1. **立即停工**：不再实现任何功能、不继续未完成的任务、不顺手修 bug、不做重构。
+2. **不向用户提问**，不做方案讨论，不征求确认。
+3. 只做两件事：**核实当前真实状态** → **写文档**。
+4. 允许读取类操作（read / ls / glob / find_text / inspect_file / cwd，以及 git status、git diff、git log 等只读命令）。
+   禁止修改工作区：不改源码、不 npm install、不 commit、不 push。唯一允许写入的文件是交接文档本身。
+5. **一次性写完**，不要反复重写；不要读大文件；不要把长代码贴进文档。
+
+## 落盘
+
+路径由「本次交接参数」给出，**原样使用**，不得改名、不得换目录、不得省略。
+用 write 工具写入后，用 read 回读一次，确认内容完整（无 read 能力时跳过此步）。
+
+## 文档结构（按序书写，标题保持原样）
+
+## 💬 对话断点
+用户最后要求了什么、你最后回复/交付了什么。各一段，不要复述整段对话。
+
+## 🎯 任务目标
+用户到底想要什么（意图与验收标准），而不是你执行过的步骤清单。
+
+## 📊 当前状态
+分支与 commit、未提交改动、测试是否通过、有无进程/端口在跑、依赖是否装好。
+
+## ✅ 已完成
+每项写：做了什么 + 产出路径（文件/目录） + 怎么验证它确实生效。
+
+## 📋 未完成
+按优先级排列；每项写「下一步最小动作」，具体到文件或可执行命令。
+
+## 🧠 关键决策
+为什么这样做（取舍理由）；以及走过的死路——防止接手者重蹈覆辙。
+
+## ⚠️ 约束与偏好
+用户强调过的规矩、项目约定、不可改动的部分、必须遵守的风格。
+
+## 📁 文件索引
+路径 + 作用 + 本次是否改动（新增 / 修改 / 仅阅读）。
+
+## 🔔 接手第一步
+3 条以内可直接执行的命令或动作，让接手者立刻能开工。
+
+## 状态核实清单
+
+- \`git status\` / \`git diff --stat\`：当前分支、是否有未提交改动
+- 最近一次测试结果：跑过就写结果摘要；没跑就写「未运行」，**不要写「应该能过」**
+- 交接涉及的关键文件：用 ls / read 确认确实存在于磁盘
+- 正在运行的服务与端口：\`ps\` / \`lsof -i\` 或项目自带的启动脚本
+
+> ⚠️ 若「本次交接参数」声明工具不可用：以上每一项都写「⚠️ 未核实」，**禁止推测**具体路径、进度与测试状态。
+
+## 写作要求
+
+- 每句话都要让接手者能「立刻开始干活」；禁止「继续开发」「完善功能」「优化一下」这类空话。
+- 已无法在当前上下文中确定的信息，写「需向用户确认 XXX」，不要编造。
+- 全文控制在 300 行以内。
+`;
+/** 全部出厂 Skill（顺序无意义，按 id 去重） */
+export const FACTORY_SKILLS = [
+    { id: HANDOFF_SKILL_ID, content: HANDOFF_SKILL },
+];
+/**
+ * 判断一份 SKILL.md 是否被用户声明为自有。
+ *
+ * 只检查 frontmatter 区块内的 `custom: true`（允许带引号），
+ * 正文里出现同样的字样不生效——避免误判导致模板停止更新。
+ */
+export function isCustomSkill(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return false;
+    return /^\s*custom:\s*["']?true["']?\s*$/m.test(match[1]);
+}

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { SubAgentsScopePlugin } from "./scope/plugins/subagents/SubAgentsScopePl
 export { allInOne } from "./scope/plugins/allInOne.js";
 export type { AllInOneOptions } from "./scope/plugins/allInOne.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 { FACTORY_SKILLS, HANDOFF_SKILL_ID, FALLBACK_HANDOFF_TEMPLATE, isCustomSkill, } from "./config/factory-skills.js";
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
 export { createModel } from "./runtime/createModel.js";
@@ -30,16 +31,17 @@ 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 { TaskMigrationService } from "./runtime/TaskMigrationService.js";
-export type { MigrationContext, MigrationStrategy, TaskMigrationServiceOptions, } from "./runtime/TaskMigrationService.js";
+export { 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";
-export type { AutoMigrateOptions } from "./agent-plugins/AutoMigratePlugin.js";
+export type { AutoMigrateOptions, AutoMigrateTriggerInfo, AutoMigrateModeResolver, } from "./agent-plugins/AutoMigratePlugin.js";
 export { AutoRefreshToolsPlugin } from "./agent-plugins/AutoRefreshToolsPlugin.js";
 export { ContextGuardPlugin } from "./agent-plugins/ContextGuardPlugin.js";
 export type { ContextGuardOptions } 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/index.js

@@ -17,6 +17,8 @@ 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";
 // CRUD — 实体仓储（仅 Agent 定义等能力实体）
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
@@ -26,7 +28,8 @@ 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 { 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 +37,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,199 @@
+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";
+/**
+ * 一次交接的完整上下文 —— 贯穿「交接前 → 写文档 → 迁移后」，供钩子与调用方使用。
+ */
+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;
+    /** 上下文阈值（自动迁移时由插件提供；手动触发可省略） */
+    maxTokens?: 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;
+    /** 上下文阈值（可选，仅透传给钩子） */
+    maxTokens?: number;
+    /** 会话 id（可选，用于交接文件名，便于回溯） */
+    conversationId?: string;
+}
+/** `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;
+    private runHandoff;
+    /** 自交接是否可用：需要 `write` 工具 + `send` 能力 */
+    private supportsSelfHandoff;
+    /**
+     * 自交接回合：让原 agent 停工、核实、写文档，并校验文件确实落盘。
+     *
+     * 失败判定（任一成立即视为失败，交由上层单向降级 summary）：
+     *   - 文件不存在 / 小于阈值；
+     *   - 模型/工具链抛错（例如没有权限、被护栏中断）。
+     */
+    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;
+}