autosnippet 3.2.16 → 3.2.17

package/dist/lib/{service/agent → agent}/AgentRuntime.d.ts

@@ -35,55 +35,23 @@ import { Capability } from './capabilities.js';
 import { PolicyEngine } from './policies.js';
 export type { AgentResult, AiError, FileCacheEntry, FunctionCall, LLMResult, ProgressEvent, ReactLoopOpts, RuntimeConfig, ToolCallEntry, ToolCallHook, ToolMetadata, } from './AgentRuntimeTypes.js';
 export { MAX_TOOL_CALLS_PER_ITER } from './AgentRuntimeTypes.js';
-/**
- * @typedef {Object} RuntimeConfig
- * @property {string} [id] 运行时唯一 ID
- * @property {string} [presetName] 使用的 Preset 名称 (仅标识)
- * @property {import('../../external/ai/AiProvider.js').AiProvider} aiProvider - LLM 提供商
- * @property {import('./tools/ToolRegistry.js').ToolRegistry} toolRegistry 工具注册表
- * @property {Object} [container] - DI 容器
- * @property {Capability[]} capabilities 已实例化的 Capability 列表
- * @property {import('./strategies.js').Strategy} strategy 执行策略
- * @property {PolicyEngine} policies 策略引擎
- * @property {Object} [persona] 人格配置
- * @property {Object} [memory] 记忆配置
- * @property {Function} [onProgress] 进度回调
- * @property {Function} [onToolCall] 工具调用通知钩子 (name, args, result, iteration)
- * @property {string} [lang] 语言偏好
- * @property {string} [projectRoot] 项目根目录 (传入工具上下文)
- */
 export declare class AgentRuntime {
     #private;
     onToolCall: ToolCallHook | null;
-    /** @type {string} */
     id: string;
-    /** @type {string} */
     presetName: string;
-    /** @type {AgentState} */
     state: AgentState;
-    /** @type {AgentEventBus} */
     bus: AgentEventBus;
-    /** @type {import('../../external/ai/AiProvider.js').AiProvider} */
-    aiProvider: import("../../external/ai/AiProvider.js").AiProvider;
-    /** @type {import('./tools/ToolRegistry.js').ToolRegistry} */
+    aiProvider: import("../external/ai/AiProvider.js").AiProvider;
     toolRegistry: import("./tools/ToolRegistry.js").ToolRegistry;
-    /** @type {Object} */
     container: Record<string, unknown> | null;
-    /** @type {Capability[]} */
     capabilities: Capability[];
-    /** @type {import('./strategies.js').Strategy} */
     strategy: import("./strategies.js").Strategy;
-    /** @type {PolicyEngine} */
     policies: PolicyEngine;
-    /** @type {Object} */
     persona: Record<string, unknown>;
-    /** @type {Object} */
     memoryConfig: Record<string, unknown>;
-    /** @type {Function|null} */
     onProgress: ((event: ProgressEvent) => void) | null;
-    /** @type {string|null} */
     lang: string | null;
-    /** @type {import('winston').Logger} */
     logger: import("winston").Logger;
     iterationCount: number;
     toolCallHistory: ToolCallEntry[];
@@ -92,25 +60,12 @@ export declare class AgentRuntime {
         output: number;
     };
     startTime: number;
-    /**
-     * @param {RuntimeConfig} config
-     */
     constructor(config: RuntimeConfig);
     /**
      * 执行 Agent — 入口
      *
-     * @param {import('./AgentMessage.js').AgentMessage} message 统一消息
-     * @param {Object} [opts] 策略特定选项 (如 FanOut 的 items)
-     * @returns {Promise<AgentResult>}
-     *
-     * @typedef {Object} AgentResult
-     * @property {string} reply 最终文本回复
-     * @property {Array} toolCalls 工具调用记录
-     * @property {Object} tokenUsage - Token 用量
-     * @property {number} iterations 循环次数
-     * @property {number} durationMs 执行耗时
-     * @property {Object} [phases] - Pipeline/FanOut 阶段详情
-     * @property {Object} state 状态快照
+     * @param message 统一消息
+     * @param [opts] 策略特定选项 (如 FanOut 的 items)
      */
     execute(message: AgentMessage, opts?: Record<string, unknown>): Promise<AgentResult>;
     /**
@@ -126,25 +81,23 @@ export declare class AgentRuntime {
      *
      * 向后兼容: 以上参数均为可选。不提供时退化为原始裸循环。
      *
-     * @param {string} prompt 用户/系统提示
-     * @param {Object} [opts]
-     * @param {Array} [opts.history] 对话历史
-     * @param {Object} [opts.context] 额外上下文
-     * @param {string[]} [opts.capabilityOverride] 临时覆盖 capability (Pipeline 阶段用)
-     * @param {Object} [opts.budgetOverride] 临时覆盖 budget
-     * @param {string} [opts.systemPromptOverride] 完全覆盖系统提示词 (Bootstrap 阶段专用)
-     * @param {Function} [opts.onToolCall] 本轮独立的工具调用钩子，优先于 runtime 级
-     * @param {import('./context/ContextWindow.js').ContextWindow} [opts.contextWindow] 上下文窗口管理器
-     * @param {Object} [opts.tracker] - ExplorationTracker 实例
-     * @param {Object} [opts.trace] - ActiveContext 实例
-     * @param {Object} [opts.memoryCoordinator] - MemoryCoordinator 实例
-     * @param {Object} [opts.sharedState] 共享状态 { submittedTitles, submittedPatterns }
-     * @param {string} [opts.source] - 'user' | 'system'
-     * @param {string} [opts.toolChoiceOverride] 首轮 toolChoice 覆盖 ('required'/'auto'/'none')
+     * @param prompt 用户/系统提示
+     * @param [opts.history] 对话历史
+     * @param [opts.context] 额外上下文
+     * @param [opts.capabilityOverride] 临时覆盖 capability (Pipeline 阶段用)
+     * @param [opts.budgetOverride] 临时覆盖 budget
+     * @param [opts.systemPromptOverride] 完全覆盖系统提示词 (Bootstrap 阶段专用)
+     * @param [opts.onToolCall] 本轮独立的工具调用钩子，优先于 runtime 级
+     * @param [opts.contextWindow] 上下文窗口管理器
+     * @param [opts.tracker] ExplorationTracker 实例
+     * @param [opts.trace] ActiveContext 实例
+     * @param [opts.memoryCoordinator] MemoryCoordinator 实例
+     * @param [opts.sharedState] 共享状态 { submittedTitles, submittedPatterns }
+     * @param [opts.source] 'user' | 'system'
+     * @param [opts.toolChoiceOverride] 首轮 toolChoice 覆盖 ('required'/'auto'/'none')
      *   首轮强制 LLM 生成 tool call（LLM 自行决定调哪个工具、传什么参数）。
      *   这不是替 LLM 做决定，而是告诉 LLM "你必须调用某个工具"。
      *   仅在第一轮生效，后续轮次恢复正常 toolChoice 逻辑。
-     * @returns {Promise<AgentResult>}
      */
     reactLoop(prompt: string, opts?: ReactLoopOpts): Promise<{
         reply: string;
@@ -155,23 +108,18 @@ export declare class AgentRuntime {
         };
         iterations: number;
     }>;
-    /**
-     * 中止执行
-     */
+    /** 中止执行 */
     abort(reason?: string): void;
     /**
      * 注入内存文件缓存（bootstrap 场景: allFiles 已在内存中，避免重复磁盘读取）
-     * @param {Array|null} files - [{ relativePath, content, name }]
+     * @param files [{ relativePath, content, name }]
      */
     setFileCache(files: FileCacheEntry[] | null): void;
     /** 项目根目录 (供 ToolExecutionPipeline 等访问) */
     get projectRoot(): string;
     /** 文件缓存 (供 ToolExecutionPipeline 等访问) */
     get fileCache(): FileCacheEntry[] | null;
-    /**
-     * 发送进度事件 (公开方法，供 ToolExecutionPipeline 中间件调用)
-     */
+    /** 发送进度事件 (公开方法，供 ToolExecutionPipeline 中间件调用) */
     emitProgress(type: string, data?: Record<string, unknown>): void;
 }
 export default AgentRuntime;
-//# sourceMappingURL=AgentRuntime.d.ts.map

package/dist/lib/{service/agent → agent}/AgentRuntime.js

@@ -28,7 +28,7 @@
  * @module AgentRuntime
  */
 import { randomUUID } from 'node:crypto';
-import Logger from '../../infrastructure/logging/Logger.js';
+import Logger from '#infra/logging/Logger.js';
 import { AgentEventBus, AgentEvents } from './AgentEventBus.js';
 import { MAX_TOOL_CALLS_PER_ITER, } from './AgentRuntimeTypes.js';
 import { AgentState } from './AgentState.js';
@@ -42,73 +42,35 @@ import { createToolPipeline } from './core/ToolExecutionPipeline.js';
 import { produceForcedSummary } from './forced-summary.js';
 import { PolicyEngine } from './policies.js';
 export { MAX_TOOL_CALLS_PER_ITER } from './AgentRuntimeTypes.js';
-/**
- * @typedef {Object} RuntimeConfig
- * @property {string} [id] 运行时唯一 ID
- * @property {string} [presetName] 使用的 Preset 名称 (仅标识)
- * @property {import('../../external/ai/AiProvider.js').AiProvider} aiProvider - LLM 提供商
- * @property {import('./tools/ToolRegistry.js').ToolRegistry} toolRegistry 工具注册表
- * @property {Object} [container] - DI 容器
- * @property {Capability[]} capabilities 已实例化的 Capability 列表
- * @property {import('./strategies.js').Strategy} strategy 执行策略
- * @property {PolicyEngine} policies 策略引擎
- * @property {Object} [persona] 人格配置
- * @property {Object} [memory] 记忆配置
- * @property {Function} [onProgress] 进度回调
- * @property {Function} [onToolCall] 工具调用通知钩子 (name, args, result, iteration)
- * @property {string} [lang] 语言偏好
- * @property {string} [projectRoot] 项目根目录 (传入工具上下文)
- */
 export class AgentRuntime {
     onToolCall;
-    /** @type {string} */
     id;
-    /** @type {string} */
     presetName;
-    /** @type {AgentState} */
     state;
-    /** @type {AgentEventBus} */
     bus;
-    /** @type {import('../../external/ai/AiProvider.js').AiProvider} */
     aiProvider;
-    /** @type {import('./tools/ToolRegistry.js').ToolRegistry} */
     toolRegistry;
-    /** @type {Object} */
     container;
-    /** @type {Capability[]} */
     capabilities;
-    /** @type {import('./strategies.js').Strategy} */
     strategy;
-    /** @type {PolicyEngine} */
     policies;
-    /** @type {Object} */
     persona;
-    /** @type {Object} */
     memoryConfig;
-    /** @type {Function|null} */
     onProgress;
-    /** @type {string|null} */
     lang;
-    /** @type {import('winston').Logger} */
     logger;
-    /** @type {string} */
     #projectRoot;
     /** @type {Array|null} 文件缓存 (bootstrap 场景注入) */
     #fileCache = null;
     /** @type {string[]} 额外工具白名单 (调用方按需注入，不经 Capability) */
     #additionalTools = [];
-    /** @type {import('./core/ToolExecutionPipeline.js').ToolExecutionPipeline} */
     #toolPipeline;
-    /** @type {SystemPromptBuilder} */
     #promptBuilder;
     // ── 执行统计 ──
     iterationCount = 0;
     toolCallHistory = [];
     tokenUsage = { input: 0, output: 0 };
     startTime = 0;
-    /**
-     * @param {RuntimeConfig} config
-     */
     constructor(config) {
         this.id = config.id || `runtime_${randomUUID().slice(0, 8)}`;
         this.presetName = config.presetName || 'custom';
@@ -148,18 +110,8 @@ export class AgentRuntime {
     /**
      * 执行 Agent — 入口
      *
-     * @param {import('./AgentMessage.js').AgentMessage} message 统一消息
-     * @param {Object} [opts] 策略特定选项 (如 FanOut 的 items)
-     * @returns {Promise<AgentResult>}
-     *
-     * @typedef {Object} AgentResult
-     * @property {string} reply 最终文本回复
-     * @property {Array} toolCalls 工具调用记录
-     * @property {Object} tokenUsage - Token 用量
-     * @property {number} iterations 循环次数
-     * @property {number} durationMs 执行耗时
-     * @property {Object} [phases] - Pipeline/FanOut 阶段详情
-     * @property {Object} state 状态快照
+     * @param message 统一消息
+     * @param [opts] 策略特定选项 (如 FanOut 的 items)
      */
     async execute(message, opts = {}) {
         this.startTime = Date.now();
@@ -237,25 +189,23 @@ export class AgentRuntime {
      *
      * 向后兼容: 以上参数均为可选。不提供时退化为原始裸循环。
      *
-     * @param {string} prompt 用户/系统提示
-     * @param {Object} [opts]
-     * @param {Array} [opts.history] 对话历史
-     * @param {Object} [opts.context] 额外上下文
-     * @param {string[]} [opts.capabilityOverride] 临时覆盖 capability (Pipeline 阶段用)
-     * @param {Object} [opts.budgetOverride] 临时覆盖 budget
-     * @param {string} [opts.systemPromptOverride] 完全覆盖系统提示词 (Bootstrap 阶段专用)
-     * @param {Function} [opts.onToolCall] 本轮独立的工具调用钩子，优先于 runtime 级
-     * @param {import('./context/ContextWindow.js').ContextWindow} [opts.contextWindow] 上下文窗口管理器
-     * @param {Object} [opts.tracker] - ExplorationTracker 实例
-     * @param {Object} [opts.trace] - ActiveContext 实例
-     * @param {Object} [opts.memoryCoordinator] - MemoryCoordinator 实例
-     * @param {Object} [opts.sharedState] 共享状态 { submittedTitles, submittedPatterns }
-     * @param {string} [opts.source] - 'user' | 'system'
-     * @param {string} [opts.toolChoiceOverride] 首轮 toolChoice 覆盖 ('required'/'auto'/'none')
+     * @param prompt 用户/系统提示
+     * @param [opts.history] 对话历史
+     * @param [opts.context] 额外上下文
+     * @param [opts.capabilityOverride] 临时覆盖 capability (Pipeline 阶段用)
+     * @param [opts.budgetOverride] 临时覆盖 budget
+     * @param [opts.systemPromptOverride] 完全覆盖系统提示词 (Bootstrap 阶段专用)
+     * @param [opts.onToolCall] 本轮独立的工具调用钩子，优先于 runtime 级
+     * @param [opts.contextWindow] 上下文窗口管理器
+     * @param [opts.tracker] ExplorationTracker 实例
+     * @param [opts.trace] ActiveContext 实例
+     * @param [opts.memoryCoordinator] MemoryCoordinator 实例
+     * @param [opts.sharedState] 共享状态 { submittedTitles, submittedPatterns }
+     * @param [opts.source] 'user' | 'system'
+     * @param [opts.toolChoiceOverride] 首轮 toolChoice 覆盖 ('required'/'auto'/'none')
      *   首轮强制 LLM 生成 tool call（LLM 自行决定调哪个工具、传什么参数）。
      *   这不是替 LLM 做决定，而是告诉 LLM "你必须调用某个工具"。
      *   仅在第一轮生效，后续轮次恢复正常 toolChoice 逻辑。
-     * @returns {Promise<AgentResult>}
      */
     async reactLoop(prompt, opts = {}) {
         const ctx = this.#initLoop(prompt, opts);
@@ -300,12 +250,7 @@ export class AgentRuntime {
         return this.#finalize(ctx);
     }
     // ─── 提取方法: reactLoop 内部阶段 ────────────
-    /**
-     * 初始化循环上下文 — 封装 reactLoop 前 ~60 行初始化逻辑
-     * @param {string} prompt
-     * @param {Object} opts
-     * @returns {LoopContext}
-     */
+    /** 初始化循环上下文 — 封装 reactLoop 前 ~60 行初始化逻辑 */
     #initLoop(prompt, opts) {
         const { history = [], context = {}, capabilityOverride, budgetOverride, systemPromptOverride, onToolCall, contextWindow, tracker, trace, memoryCoordinator, sharedState, source, toolChoiceOverride, } = opts;
         // 解析 capabilities
@@ -373,8 +318,7 @@ export class AgentRuntime {
     }
     /**
      * 退出判定 — 合并 tracker/policy 退出检查
-     * @param {LoopContext} ctx
-     * @returns {boolean} true = 应退出循环
+     * @returns true = 应退出循环
      */
     #shouldExit(ctx) {
         // ExplorationTracker: tick + 退出检查
@@ -419,8 +363,7 @@ export class AgentRuntime {
     }
     /**
      * 迭代准备 — 合并 nudge/压缩/提示词增强/toolChoice
-     * @param {LoopContext} ctx
-     * @returns {{ toolChoice: string, effectiveSystemPrompt: string, effectivePrompt: string }}
+     * @returns }
      */
     #prepareIteration(ctx) {
         const { tracker, trace, capabilities: _capabilities, messages, prompt } = ctx;
@@ -485,11 +428,7 @@ export class AgentRuntime {
     /**
      * LLM 调用 — 含错误恢复 + 空响应重试
      *
-     * @param {LoopContext} ctx
-     * @param {string} toolChoice
-     * @param {string} effectiveSystemPrompt
-     * @param {string} effectivePrompt
-     * @returns {Promise<Object|null>} llmResult 或 null (表示应退出)
+     * @returns llmResult 或 null (表示应退出)
      */
     async #callLLM(ctx, toolChoice, effectiveSystemPrompt, effectivePrompt) {
         this.bus.publish(AgentEvents.LLM_CALL_START, {
@@ -576,7 +515,7 @@ export class AgentRuntime {
     }
     /**
      * AI 错误处理 — 熔断器感知 + 2-strike 策略
-     * @returns {Promise<Object|null>} - continueResult() 或 null (退出)
+     * @returns continueResult() 或 null (退出)
      */
     async #handleAiError(ctx, aiErr) {
         ctx.consecutiveAiErrors++;
@@ -605,10 +544,8 @@ export class AgentRuntime {
     /**
      * 工具调用处理 — 执行 + 记录 + 去重 + 阶段转换
      *
-     * @param {LoopContext} ctx
-     * @param {Object} llmResult
-     * @param {string} effectiveSystemPrompt 用于 budget 耗尽时的摘要调用
-     * @returns {Promise<boolean>} true = 应退出循环
+     * @param effectiveSystemPrompt 用于 budget 耗尽时的摘要调用
+     * @returns true = 应退出循环
      */
     async #processToolCalls(ctx, llmResult, effectiveSystemPrompt) {
         const { tracker, trace, messages } = ctx;
@@ -750,9 +687,7 @@ export class AgentRuntime {
     /**
      * 文本响应处理 — tracker 阶段路由 + 非 tracker 直接终止
      *
-     * @param {LoopContext} ctx
-     * @param {Object} llmResult
-     * @returns {boolean} true = 应退出循环
+     * @returns true = 应退出循环
      */
     #processTextResponse(ctx, llmResult) {
         const { tracker, trace, messages } = ctx;
@@ -796,11 +731,7 @@ export class AgentRuntime {
         trace?.endRound?.();
         return true;
     }
-    /**
-     * 循环退出后处理 — 强制摘要 + 构建返回值
-     * @param {LoopContext} ctx
-     * @returns {Promise<Object>}
-     */
+    /** 循环退出后处理 — 强制摘要 + 构建返回值 */
     async #finalize(ctx) {
         // Scan 管线: 所有结果在 toolCalls 中 (collect_scan_recipe)，不需要文本回复
         // 直接跳过 forced summary，避免浪费一次 LLM 调用
@@ -832,9 +763,7 @@ export class AgentRuntime {
         return ctx.buildResult();
     }
     // ─── 公共工具方法 ────────────────────────────
-    /**
-     * 中止执行
-     */
+    /** 中止执行 */
     abort(reason = 'User aborted') {
         this.#safeTransition('abort', { reason });
         this.bus.publish(AgentEvents.AGENT_ABORTED, {
@@ -844,7 +773,7 @@ export class AgentRuntime {
     }
     /**
      * 注入内存文件缓存（bootstrap 场景: allFiles 已在内存中，避免重复磁盘读取）
-     * @param {Array|null} files - [{ relativePath, content, name }]
+     * @param files [{ relativePath, content, name }]
      */
     setFileCache(files) {
         this.#fileCache = files;
@@ -858,9 +787,7 @@ export class AgentRuntime {
     get fileCache() {
         return this.#fileCache;
     }
-    /**
-     * 发送进度事件 (公开方法，供 ToolExecutionPipeline 中间件调用)
-     */
+    /** 发送进度事件 (公开方法，供 ToolExecutionPipeline 中间件调用) */
     emitProgress(type, data = {}) {
         this.#emitProgress(type, data);
     }
@@ -903,9 +830,7 @@ export class AgentRuntime {
         }
         return hasUnlimited ? [] : [...toolSet];
     }
-    /**
-     * 解析 capability 名称为实例 (Pipeline 阶段覆盖时调用)
-     */
+    /** 解析 capability 名称为实例 (Pipeline 阶段覆盖时调用) */
     #resolveCapabilities(capNames) {
         if (capNames == null) {
             return this.capabilities;
@@ -926,9 +851,7 @@ export class AgentRuntime {
             return CapabilityRegistry.create(name);
         });
     }
-    /**
-     * 发送进度事件
-     */
+    /** 发送进度事件 */
     #emitProgress(type, data = {}) {
         const event = {
             type,
@@ -944,4 +867,3 @@ export class AgentRuntime {
     }
 }
 export default AgentRuntime;
-//# sourceMappingURL=AgentRuntime.js.map

package/dist/lib/{service/agent → agent}/AgentRuntimeTypes.d.ts

@@ -60,7 +60,7 @@ export interface FileCacheEntry {
 export interface RuntimeConfig {
     id?: string;
     presetName?: string;
-    aiProvider: import('../../external/ai/AiProvider.js').AiProvider;
+    aiProvider: import('#external/ai/AiProvider.js').AiProvider;
     toolRegistry: import('./tools/ToolRegistry.js').ToolRegistry;
     container?: Record<string, unknown> | null;
     capabilities?: import('./capabilities.js').Capability[];
@@ -110,4 +110,3 @@ export interface ReactLoopOpts {
 }
 /** 单次迭代允许的最大工具调用数 */
 export declare const MAX_TOOL_CALLS_PER_ITER = 8;
-//# sourceMappingURL=AgentRuntimeTypes.d.ts.map

package/dist/lib/{service/agent → agent}/AgentRuntimeTypes.js

@@ -8,4 +8,3 @@
  */
 /** 单次迭代允许的最大工具调用数 */
 export const MAX_TOOL_CALLS_PER_ITER = 8;
-//# sourceMappingURL=AgentRuntimeTypes.js.map

package/dist/lib/{service/agent → agent}/AgentState.d.ts

@@ -41,9 +41,7 @@ interface AgentStateSnapshot {
     data?: Record<string, unknown>;
     history?: HistoryEntry[];
 }
-/**
- * Agent 执行阶段枚举
- */
+/** Agent 执行阶段枚举 */
 export declare const AgentPhase: Readonly<{
     IDLE: "idle";
     PLANNING: "planning";
@@ -58,11 +56,10 @@ export declare const AgentPhase: Readonly<{
 export declare class AgentState extends EventEmitter {
     #private;
     /**
-     * @param {Object} [opts]
-     * @param {Object} [opts.initialData={}] 初始状态数据
-     * @param {string} [opts.initialPhase='idle'] 初始阶段
-     * @param {Transition[]} [opts.transitions] 自定义转移定义（合并到默认转移上）
-     * @param {boolean} [opts.keepHistory=true] 是否保留状态历史
+     * @param [opts.initialData={}] 初始状态数据
+     * @param [opts.initialPhase='idle'] 初始阶段
+     * @param [opts.transitions] 自定义转移定义（合并到默认转移上）
+     * @param [opts.keepHistory=true] 是否保留状态历史
      */
     constructor({ initialData, initialPhase, transitions, keepHistory, }?: {
         initialData?: {} | undefined;
@@ -82,39 +79,28 @@ export declare class AgentState extends EventEmitter {
     get isTerminal(): boolean;
     /**
      * 触发事件，尝试状态转移
-     * @param {string} event 事件名
-     * @param {Object} [payload={}] 附加数据（合并到 state.data）
-     * @returns {boolean} 是否成功转移
+     * @param event 事件名
+     * @param [payload={}] 附加数据（合并到 state.data）
+     * @returns 是否成功转移
      */
     send(event: string, payload?: Record<string, unknown>): boolean;
     /**
      * 直接更新状态数据（不触发阶段转移）
-     * @param {Object} patch 要合并的数据
+     * @param patch 要合并的数据
      */
     update(patch: Record<string, unknown>): void;
-    /**
-     * 获取当前阶段可用的事件列表
-     * @returns {string[]}
-     */
+    /** 获取当前阶段可用的事件列表 */
     availableEvents(): string[];
-    /**
-     * 导出为可序列化对象
-     * @returns {Object}
-     */
+    /** 导出为可序列化对象 */
     toJSON(): {
         phase: string;
         data: Record<string, unknown>;
         history: HistoryEntry[];
     };
-    /**
-     * 从序列化数据恢复
-     * @param {Object} snapshot
-     * @returns {AgentState}
-     */
+    /** 从序列化数据恢复 */
     static fromJSON(snapshot: AgentStateSnapshot, opts?: {
         transitions?: Transition[];
         keepHistory?: boolean;
     }): AgentState;
 }
 export default AgentState;
-//# sourceMappingURL=AgentState.d.ts.map

package/dist/lib/{service/agent → agent}/AgentState.js

@@ -15,9 +15,7 @@
  * @module AgentState
  */
 import { EventEmitter } from 'node:events';
-/**
- * Agent 执行阶段枚举
- */
+/** Agent 执行阶段枚举 */
 export const AgentPhase = Object.freeze({
     IDLE: 'idle',
     PLANNING: 'planning',
@@ -29,18 +27,8 @@ export const AgentPhase = Object.freeze({
     FAILED: 'failed',
     ABORTED: 'aborted',
 });
-/**
- * 状态转移定义
- * @typedef {Object} Transition
- * @property {string} from  起始阶段
- * @property {string} to    目标阶段
- * @property {string} event 触发事件名
- * @property {Function} [guard] 守卫条件 (state) => boolean
- * @property {Function} [action] 副作用 (state, payload) => void
- */
-/**
- * 默认状态转移图（适用于所有 Agent 模式，可在子类中扩展）
- */
+/** 状态转移定义 */
+/** 默认状态转移图（适用于所有 Agent 模式，可在子类中扩展） */
 const DEFAULT_TRANSITIONS = [
     { from: AgentPhase.IDLE, to: AgentPhase.PLANNING, event: 'start' },
     { from: AgentPhase.PLANNING, to: AgentPhase.EXECUTING, event: 'plan_ready' },
@@ -61,18 +49,16 @@ export class AgentState extends EventEmitter {
     #phase;
     /** @type {Object} 用户自定义状态数据 */
     #data;
-    /** @type {Transition[]} */
     #transitions;
     /** @type {Array<{phase: string, data: Object, timestamp: number}>} */
     #history;
     /** @type {boolean} 是否保留历史 */
     #keepHistory;
     /**
-     * @param {Object} [opts]
-     * @param {Object} [opts.initialData={}] 初始状态数据
-     * @param {string} [opts.initialPhase='idle'] 初始阶段
-     * @param {Transition[]} [opts.transitions] 自定义转移定义（合并到默认转移上）
-     * @param {boolean} [opts.keepHistory=true] 是否保留状态历史
+     * @param [opts.initialData={}] 初始状态数据
+     * @param [opts.initialPhase='idle'] 初始阶段
+     * @param [opts.transitions] 自定义转移定义（合并到默认转移上）
+     * @param [opts.keepHistory=true] 是否保留状态历史
      */
     constructor({ initialData = {}, initialPhase = AgentPhase.IDLE, transitions = [], keepHistory = true, } = {}) {
         super();
@@ -103,9 +89,9 @@ export class AgentState extends EventEmitter {
     }
     /**
      * 触发事件，尝试状态转移
-     * @param {string} event 事件名
-     * @param {Object} [payload={}] 附加数据（合并到 state.data）
-     * @returns {boolean} 是否成功转移
+     * @param event 事件名
+     * @param [payload={}] 附加数据（合并到 state.data）
+     * @returns 是否成功转移
      */
     send(event, payload = {}) {
         const transition = this.#findTransition(event);
@@ -140,25 +126,19 @@ export class AgentState extends EventEmitter {
     }
     /**
      * 直接更新状态数据（不触发阶段转移）
-     * @param {Object} patch 要合并的数据
+     * @param patch 要合并的数据
      */
     update(patch) {
         this.#data = { ...this.#data, ...patch };
         this.emit('update', { phase: this.#phase, patch });
     }
-    /**
-     * 获取当前阶段可用的事件列表
-     * @returns {string[]}
-     */
+    /** 获取当前阶段可用的事件列表 */
     availableEvents() {
         return this.#transitions
             .filter((t) => t.from === this.#phase || t.from === '*')
             .map((t) => t.event);
     }
-    /**
-     * 导出为可序列化对象
-     * @returns {Object}
-     */
+    /** 导出为可序列化对象 */
     toJSON() {
         return {
             phase: this.#phase,
@@ -166,11 +146,7 @@ export class AgentState extends EventEmitter {
             history: this.#history,
         };
     }
-    /**
-     * 从序列化数据恢复
-     * @param {Object} snapshot
-     * @returns {AgentState}
-     */
+    /** 从序列化数据恢复 */
     static fromJSON(snapshot, opts = {}) {
         const state = new AgentState({
             initialData: snapshot.data || {},
@@ -195,4 +171,3 @@ export class AgentState extends EventEmitter {
     }
 }
 export default AgentState;
-//# sourceMappingURL=AgentState.js.map