knight-agent 1.1.0

package/docs/README.md

@@ -0,0 +1,562 @@
+# Knight Agent 2.0 — 使用手册
+
+基于 DeepSeek API 的模块化 TypeScript AI Agent 框架。提供 6 种内置推理策略、工具管理、技能能力包、对话持久化和多级 Token 优化。
+
+---
+
+## 目录
+
+- [架构概览](#架构概览)
+- [快速开始](#快速开始)
+- [配置](#一配置-agentconfig)
+- [工具 Tool](#二工具-tool)
+- [技能 Skill](#三技能-skill)
+- [对话 Dialog](#四对话-dialog)
+- [推理策略 Reason](#五推理策略-reason)
+- [两个执行路径对比](#六两个执行路径对比)
+- [Token 优化体系](#七token-优化体系)
+- [持久化与快照](#八持久化与快照)
+- [完整示例](#九完整示例多设备控制场景)
+- [Host 模块一览](#十host-模块一览)
+
+---
+
+## 架构概览
+
+```
+┌─────────────────────────────────────────────────┐
+│                    Host (单例)                    │
+│  .toolModule    .skillModule    .reasonModule    │
+│  .agentModule   .dialogModule                    │
+└─────────────────────────────────────────────────┘
+         ↑ 业务层通过 Host.Instance 访问所有模块
+
+┌──────────┐    ┌──────────┐    ┌──────────┐
+│  Tool    │    │  Skill   │    │  Reason  │
+│ 单函数    │───→│ 工具包    │    │ 推理策略  │
+│ 描述符    │    │ +prompt  │    │ 6种模式  │
+└──────────┘    └────┬─────┘    └────┬─────┘
+                     │               │
+                     ▼               ▼
+              ┌──────────────────────────┐
+              │         Dialog           │
+              │  持久化 Agent + 策略绑定   │
+              │  Skill 作用域控制工具可见   │
+              └──────────┬───────────────┘
+                         │
+                         ▼
+              ┌──────────────────────────┐
+              │         Agent            │
+              │  消息缓存 + ReAct 主循环   │
+              │  上下文窗口自动优化        │
+              └──────────────────────────┘
+
+工具选择管线:
+  用户输入
+    → Skill 过滤: resolveTools(dialogId) → 候选工具名
+      → ToolRAG 语义排序: selectTools(query, candidates, topK) → Top-K
+        → Compact Schema: ToAPITools(names, compact=true) → 精简定义
+          → LLM 调用
+```
+
+---
+
+## 快速开始
+
+```typescript
+import Host from "knight-agent";
+
+// 1. 注册工具
+Host.toolModule.register({
+  name: "web/search",
+  description: "Search the web for information",
+  schema: {
+    type: "object",
+    properties: { query: { type: "string" } },
+    required: ["query"],
+  },
+  handler: async (args) => {
+    const res = await fetch(`https://api.search.com?q=${args.query}`);
+    return JSON.stringify(await res.json());
+  },
+  cacheable: true,
+  parallelizable: true,
+});
+
+// 2. 注册技能
+Host.skillModule.register({
+  name: "web-research",
+  description: "Web search and browsing capability",
+  tools: ["web/search"],
+  systemPrompt: "You can use web/search to find up-to-date information.",
+});
+
+// 3. 创建对话
+const dialog = Host.dialogModule.create(
+  "Research Task",
+  {
+    address: "https://api.deepseek.com/v1/chat/completions",
+    apiKey: "sk-xxx",
+    model: "deepseek-chat",
+    temperature: 0.6,
+    maxTurns: 20,
+  },
+  "ChainReason"
+);
+
+// 4. 启用技能
+Host.skillModule.enable(dialog.id, "web-research");
+
+// 5. 发送消息 (自动: Skill过滤→RAG排序→Compact Schema→LLM)
+const result = await dialog.send("What is the latest news about AI?");
+console.log(result.content);
+
+// 6. 切换策略 (不影响消息历史)
+dialog.switchStrategy("ReflectReason");
+await dialog.send("Refine the answer with more details.");
+
+// 7. 销毁
+Host.dialogModule.destroy(dialog.id);
+```
+
+---
+
+## 一、配置 (AgentConfig)
+
+创建 Agent / Dialog 时的统一配置：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `address` | `string` | ✅ | API 端点地址 |
+| `apiKey` | `string` | ✅ | API 密钥 |
+| `model` | `string` | ✅ | 模型名称 |
+| `systemPrompt` | `string` | | 系统提示词 |
+| `enableThinking` | `boolean` | | 思考模式开关，默认 `true` |
+| `reasoningEffort` | `"high" \| "max"` | | 推理强度 |
+| `temperature` | `number` | | 采样温度 (0~2) |
+| `maxTokens` | `number` | | 最大输出 token |
+| `maxTurns` | `number` | | 最大对话轮次 |
+
+---
+
+## 二、工具 (Tool)
+
+### 注册工具
+
+```typescript
+Host.toolModule.register({
+  name: "pc/screenshot",        // 支持命名空间: "namespace/name"
+  description: "Capture a screenshot of the current desktop",
+  schema: {
+    type: "object",
+    properties: {
+      region: { type: "string", enum: ["full", "active", "selection"] }
+    },
+    required: ["region"],
+  },
+  handler: async (args) => { /* 调 MCP / API / 本地逻辑 */ return "..."; },
+
+  // 可选属性
+  cacheable: true,             // 相同参数缓存结果 (默认 60s TTL)
+  retryable: true,             // 失败可重试
+  maxRetries: 3,               // 最大重试次数 (默认 1)
+  parallelizable: true,        // 可与其他工具并行执行
+  requiresApproval: false,     // 需人工审批 (预留)
+  category: "desktop",         // 分类标签
+});
+```
+
+### 管理工具
+
+```typescript
+Host.toolModule.registerAll([tool1, tool2]);     // 批量注册
+Host.toolModule.unregister("toolName");          // 移除 (自动清缓存+去索引)
+Host.toolModule.get("toolName");                 // 获取定义
+Host.toolModule.list();                          // 全部
+Host.toolModule.listByCategory("desktop");       // 按分类
+Host.toolModule.count;                           // 数量
+Host.toolModule.clear();                         // 清空全部
+Host.toolModule.invalidateCache();               // 清空全部缓存
+Host.toolModule.invalidateCache("pc/screenshot"); // 精确清除某个工具缓存
+```
+
+### 语义检索 (ToolRAG)
+
+当候选工具数 > topK 时自动排序，选择最相关的工具发送给 LLM：
+
+```typescript
+// 默认: 内置关键词匹配 (零依赖)
+const names = await Host.toolModule.selectTools(
+  "take a screenshot",
+  ["pc/screenshot", "file/read", "web/search"],
+  5   // topK
+);
+
+// 可选: 接入真实 Embedding API 提升精度
+Host.toolModule.setEmbeddingProvider({
+  dims: 1536,
+  embed: async (text) => fetch("https://api.openai.com/v1/embeddings", {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${key}` },
+    body: JSON.stringify({ model: "text-embedding-3-small", input: text }),
+  }).then(r => r.json()).then(d => d.data[0].embedding),
+});
+```
+
+### 导出为 OpenAI API 格式
+
+```typescript
+const apiTools = Host.toolModule.ToAPITools(["tool1", "tool2"], true);
+// compact=true 时自动裁剪 schema (移除 description/default)
+```
+
+---
+
+## 三、技能 (Skill)
+
+Skill 是工具能力包 + 使用指导的组合体。框架通过 Skill 控制每个对话可见的工具范围。
+
+### 注册技能
+
+```typescript
+Host.skillModule.register({
+  name: "Windows Control",
+  description: "Control Windows desktop: screenshot, clipboard, window management",
+  version: "1.0.0",
+  tools: ["pc/screenshot", "pc/clipboard", "pc/window"],  // 精确匹配
+  systemPrompt: "PC 文件操作前先确认路径是否存在。",
+  category: "desktop",
+  constraints: {
+    maxCallsPerTurn: 5,
+    requireApproval: false,
+  },
+});
+```
+
+### 工具匹配规则
+
+```typescript
+tools: ["pc/screenshot", "pc/clipboard"]   // 精确匹配
+tools: ["pc/*"]                             // 通配: 匹配所有 "pc/" 前缀的工具
+tools: ["pc/screenshot", "android/*"]       // 混合
+```
+
+### 对话级启用/禁用
+
+```typescript
+Host.skillModule.enable(dialogId, "Windows Control");   // 启用
+Host.skillModule.disable(dialogId, "Windows Control");  // 禁用
+Host.skillModule.getEnabled(dialogId);                   // 获取启用的技能列表
+Host.skillModule.resolveTools(dialogId);                 // → ToolDefinition[] (自动展开通配符)
+Host.skillModule.buildPrompt(dialogId);                  // → 聚合的 systemPrompt 文本
+Host.skillModule.clearDialog(dialogId);                  // 清理对话绑定
+```
+
+> **没有启用任何技能时**，`resolveTools` 返回空数组，Agent 无法调用任何工具。
+
+---
+
+## 四、对话 (Dialog)
+
+Dialog = 持久化 Agent + 绑定推理策略 + Skill 作用域。Agent 随对话存在，不随消息销毁。
+
+### 创建
+
+```typescript
+const dialog = Host.dialogModule.create(
+  "标题",                       // 对话标题
+  {                             // AgentConfig (含 apiKey/address)
+    address: "https://api.deepseek.com/v1/chat/completions",
+    apiKey: "sk-xxx",
+    model: "deepseek-chat",
+    systemPrompt: "You are a helpful assistant.",
+  },
+  "ChainReason"                 // 初始策略 (可选，默认 ChainReason)
+);
+```
+
+### 发送消息
+
+```typescript
+const result = await dialog.send("你好");
+
+// DialogResult {
+//   success: boolean;
+//   content: string;          // 助手回复
+//   thinking?: string;        // CoT 思考过程
+//   toolCalls?: ...;          // 工具调用记录
+//   usage?: { prompt_tokens, completion_tokens, total_tokens };
+//   finishReason?: string;
+//   strategy: string;         // 使用的策略名
+//   dialogId: string;         // 对话 ID
+//   trace?: string[];         // 推理追踪日志
+//   reflectionRounds?: number; // 反思轮次 (仅 ReflectReason)
+// }
+```
+
+### 切换策略
+
+```typescript
+dialog.switchStrategy("ReflectReason");   // 返回 true/false
+dialog.strategy;                          // 读取当前策略名
+```
+
+### 生命周期
+
+```typescript
+Host.dialogModule.get(dialogId);         // 获取 Dialog 实例
+Host.dialogModule.list();                // 列出全部 [{dialogId, title, strategy}]
+Host.dialogModule.count;                 // 数量
+Host.dialogModule.destroy(dialogId);     // 销毁 (内部自动销毁 Agent)
+Host.dialogModule.destroyAll();          // 销毁全部
+```
+
+---
+
+## 五、推理策略 (Reason)
+
+6 种内置策略，不创建 Dialog 也可直接使用 (一次性 Agent，用完即毁)。
+
+### 策略列表
+
+| 策略 | 键名 | 适合场景 | Agent 数 |
+|---|---|---|---|
+| **ChainReason** | `"ChainReason"` | 简单问答、事实查询、单步推理 | 1 |
+| **ReflectReason** | `"ReflectReason"` | 代码生成、写作、翻译 (质量敏感) | 1 |
+| **TreeReason** | `"TreeReason"` | 方案设计、多方案对比、开放探索 | 1 |
+| **PlanReason** | `"PlanReason"` | 多步骤任务、开发流程、配置部署 | 1 |
+| **CompetitiveReason** | `"CompetitiveReason"` | 方案决策、多角度分析 | N+1 (裁判) |
+| **CommanderReason** | `"CommanderReason"` | 复杂多模块任务、分工协作 | 1+N (工人) |
+
+### 一次性执行 (不创建 Dialog)
+
+```typescript
+const result = await Host.reasonModule.execute(
+  "Write a debounce function in TypeScript",
+  {
+    baseConfig: {
+      address: "https://api.deepseek.com/v1/chat/completions",
+      apiKey: "sk-xxx",
+      model: "deepseek-chat",
+    },
+    // 策略特定参数 (可选)
+    competitorCount: 3,       // CompetitiveReason: 竞争者数量
+    varyTemperature: true,    // CompetitiveReason: 温度差异化
+    maxWorkers: 3,            // CommanderReason: 最大工人数
+  },
+  "ReflectReason"             // 策略名，默认 ChainReason
+);
+```
+
+### 注册自定义策略
+
+```typescript
+import { AbstractReason, ReasonConfig, ReasonResult } from "knight-agent";
+
+class MyReason extends AbstractReason {
+  public readonly type = "MyReason";
+  async execute(input: string, config: ReasonConfig): Promise<ReasonResult> {
+    // ... 自定义推理逻辑
+  }
+}
+
+Host.reasonModule.register("MyReason", new MyReason());
+```
+
+### 策略管理
+
+```typescript
+Host.reasonModule.register("name", reason);   // 注册
+Host.reasonModule.unregister("name");         // 注销
+Host.reasonModule.has("ChainReason");         // 存在检查
+Host.reasonModule.get("ReflectReason");       // 获取实例
+Host.reasonModule.list();                     // [{name, type}, ...]
+Host.reasonModule.count;                      // 数量
+```
+
+---
+
+## 六、两个执行路径对比
+
+| | **一次性 (ReasonModule)** | **持久化 (Dialog)** |
+|---|---|---|
+| Agent 生命周期 | 创建 → 执行 → 销毁 | 创建 → 常驻 → destroy |
+| 消息历史 | 单次，不保留 | 跨轮次累积 |
+| 工具可见 | 全部注册的工具 | 由启用的 Skill 过滤 |
+| RAG 工具排序 | ❌ 不经过 | ✅ 自动排序 |
+| Skill 作用域 | ❌ 不支持 | ✅ 支持 |
+| 快照持久化 | ❌ | ✅ |
+| 使用 | `reasonModule.execute()` | `dialog.send()` |
+
+---
+
+## 七、Token 优化体系
+
+框架内置 4 级 Token 开销优化，在 `dialog.send()` 路径上自动生效。
+
+### P0 — Compact Tool Schema
+
+`ToolModule.ToAPITools(names, compact=true)` 递归裁剪 JSONSchema，移除 `description` 和 `default` 字段，仅保留 `type/enum/required/properties/items`。Agent 在每次 `OnSendRequest` 中始终传入 `compact=true`。
+
+```
+原始: {"type":"string","description":"Search keywords","default":""}
+精简: {"type":"string"}
+```
+
+### P1 — MemoryPressure 三级阈值
+
+`Memory.checkPressure()` 返回 4 级压力状态，触发分级压缩：
+
+| 级别 | 阈值 | 操作 | LLM 调用 |
+|------|------|------|---------|
+| `None` | < 70% | 无操作 | 0 |
+| `Mild` | 70-85% | 压缩前 30% 消息为摘要 | 1 |
+| `Moderate` | 85-95% | 压缩远期 + 摘要中间轮次 + 提取实体 | 1-2 |
+| `Critical` | > 95% | 激进裁剪，仅保留最近 3 轮 + 纯文本摘要 | 0-1 |
+
+发送请求前自动检测并执行，无需手动干预。
+
+### P2 — tiktoken 精确计数
+
+使用 tiktoken (`cl100k_base`) 进行字节级 Token 估算，兼容 DeepSeek/OpenAI。
+
+```typescript
+import { MemoryPressure } from "knight-agent";
+
+const tokens = agent.memory.estimateTokens();       // 精确 Token 数
+const level = agent.memory.checkPressure();          // MemoryPressure 枚举
+if (level > MemoryPressure.None) {
+  await agent.memory.optimize(level);                // 按级别压缩
+}
+```
+
+### P3 — ToolRAG 语义检索
+
+当候选工具数 > topK 时自动排序选择最相关工具。默认使用零依赖关键词匹配，可接入 Embedding API 提升精度。
+
+**优化效果**: 100 个工具注册 → Skill 过滤至 20 个 → RAG 排序取 Top-10 → Compact 裁剪 → 最终 Token 开销约 3% 原始量。
+
+---
+
+## 八、持久化与快照
+
+框架支持 Dialog 级别的快照导出/恢复 (不含 `apiKey`/`address`)。
+
+### 导出
+
+```typescript
+const snapshot = Host.dialogModule.export(dialogId);
+// DialogSnapshot {
+//   version, createdAt, dialogId, title, strategy,
+//   agentSnapshot: { version, createdAt, agentId, turnCount,
+//     messages, scratchpad, toolResults, config }
+// }
+
+// 保存到数据库
+await db.save("snapshots", snapshot.dialogId, snapshot);
+```
+
+### 恢复
+
+```typescript
+// 需重新提供 apiKey/address (快照中已剥离)
+const config: AgentConfig = {
+  address: "https://api.deepseek.com/v1/chat/completions",
+  apiKey: "sk-xxx",
+  model: "...",
+};
+
+const restored = Host.dialogModule.import(snapshot, config);
+await restored.send("Continue from where we left off.");
+```
+
+---
+
+## 九、完整示例：多设备控制场景
+
+```typescript
+import Host from "knight-agent";
+
+// ---- 注册工具 ----
+Host.toolModule.registerAll([
+  {
+    name: "pc/screenshot",
+    description: "截取 PC 当前屏幕",
+    schema: { type: "object", properties: { region: { type: "string" } } },
+    handler: async (args) => await pcMcp.call("screenshot", args),
+    cacheable: true,
+  },
+  {
+    name: "pc/file_read",
+    description: "读取 PC 上的文件内容",
+    schema: { type: "object", properties: { filePath: { type: "string" } }, required: ["filePath"] },
+    handler: async (args) => await pcMcp.call("file_read", args),
+  },
+  {
+    name: "android/screenshot",
+    description: "截取 Android 当前屏幕",
+    schema: { type: "object", properties: {} },
+    handler: async () => await androidMcp.call("screenshot", {}),
+  },
+  {
+    name: "android/app_install",
+    description: "在 Android 设备上安装应用",
+    schema: { type: "object", properties: { packageName: { type: "string" } }, required: ["packageName"] },
+    handler: async (args) => await androidMcp.call("app_install", args),
+  },
+]);
+
+// ---- 注册技能 (工具能力包) ----
+Host.skillModule.register({
+  name: "PC Control",
+  description: "控制 PC 设备",
+  tools: ["pc/screenshot", "pc/file_read"],
+  systemPrompt: "PC 文件操作前先确认路径是否存在。",
+});
+
+Host.skillModule.register({
+  name: "Android Control",
+  description: "控制 Android 设备",
+  tools: ["android/screenshot", "android/app_install"],
+});
+
+// ---- 创建对话 ----
+const dialog = Host.dialogModule.create("设备管理", {
+  address: "https://api.deepseek.com/v1/chat/completions",
+  apiKey: "sk-xxx",
+  model: "deepseek-chat",
+  systemPrompt: "你是设备管理助手。",
+});
+
+Host.skillModule.enable(dialog.id, "PC Control");
+Host.skillModule.enable(dialog.id, "Android Control");
+
+// ---- 使用 ----
+const r1 = await dialog.send("给 PC 和 Android 都截个屏");
+console.log(r1.content);
+
+dialog.switchStrategy("PlanReason");
+const r2 = await dialog.send("先在 PC 上读取配置文件，根据配置在 Android 上安装对应应用");
+console.log(r2.content);
+console.log(r2.trace);  // 计划执行追踪
+
+// ---- 导出快照 ----
+const snapshot = Host.dialogModule.export(dialog.id);
+await saveToDatabase(snapshot);
+```
+
+---
+
+## 十、Host 模块一览
+
+```typescript
+import Host from "knight-agent";
+
+Host.toolModule       // 工具注册表 + 执行调度 + 缓存 + RAG 检索
+Host.skillModule      // 技能注册 + 对话级启用/禁用
+Host.reasonModule     // 推理策略注册 + 一次性执行
+Host.dialogModule     // 对话池 + 生命周期 + 快照导入导出
+Host.agentModule      // Agent 创建/销毁/查询
+```
+
+每个模块继承 `AbstractModule` → `AbstractObject`，自动分配 `id` 并注册到全局对象池，可通过 `Host.Instance` 直接访问。

package/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./Host";
+export * from "./module";
+export { default } from "./Host";
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC"}

package/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+__exportStar(require("./Host"), exports);
+__exportStar(require("./module"), exports);
+var Host_1 = require("./Host");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(Host_1).default; } });
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA,yCAAuB;AACvB,2CAAyB;AACzB,+BAAiC;AAAxB,gHAAA,OAAO,OAAA"}

package/module/AgentModule/Agent.d.ts

@@ -0,0 +1,55 @@
+import { AbstractAgent, AgentConfig, AgentRunOptions, AgentSnapshot, AgentRunResult, AgentState } from "../../base";
+import { NetworkUtility, OpenAIUtility } from "../../utility";
+import { Memory } from "./Memory";
+/** 智能体类 */
+export declare class Agent extends AbstractAgent {
+    /** 智能体配置 */
+    readonly config: AgentConfig;
+    /** 记忆管理器(消息缓存 + 草稿区 + 上下文优化) */
+    readonly memory: Memory;
+    /** 运行状态 */
+    private _state;
+    /** 对话轮次 */
+    private _turnCount;
+    /** 当前 run() 的执行选项 */
+    private _runOptions?;
+    /** 构造函数 */
+    constructor(config: AgentConfig);
+    /** 当前状态 */
+    get state(): AgentState;
+    /** 对话轮次 */
+    get turnCount(): number;
+    /** 思考模式是否开启 */
+    get thinkingEnabled(): boolean;
+    /** @internal 发送用户消息(缓存→发送→缓存回复) */
+    sendUserMessage(content: string): Promise<NetworkUtility.HTTP.Response<OpenAIUtility.OpenAI.ChatResponse>>;
+    /** @internal 发送当前消息缓存 */
+    sendRequest(): Promise<NetworkUtility.HTTP.Response<OpenAIUtility.OpenAI.ChatResponse>>;
+    /** 发送消息缓存中的消息到LLM */
+    protected OnSendRequest(overrides?: Partial<OpenAIUtility.OpenAI.ChatRequest>): Promise<NetworkUtility.HTTP.Response<OpenAIUtility.OpenAI.ChatResponse>>;
+    /** 发送用户消息(自动缓存用户消息和助手回复) */
+    protected OnSend(content: string): Promise<NetworkUtility.HTTP.Response<OpenAIUtility.OpenAI.ChatResponse>>;
+    /** 模型基础请求(HTTP POST) */
+    OnBaseRequest(apiKey: string, chatRequest: OpenAIUtility.OpenAI.ChatRequest): Promise<NetworkUtility.HTTP.Response<OpenAIUtility.OpenAI.ChatResponse>>;
+    /** @internal 执行工具调用(含缓存+重试) */
+    executeTool(toolCall: OpenAIUtility.OpenAI.ToolResponse): Promise<string>;
+    /** @internal 添加工具结果到消息缓存和记忆 */
+    addToolResult(result: string, toolCallId: string): void;
+    /** @internal 添加助手消息到缓存(含 tool_calls) */
+    addAssistantMessage(content: string, toolCalls?: Array<OpenAIUtility.OpenAI.ToolResponse>): void;
+    /** @internal 设置运行状态 */
+    setState(state: AgentState): void;
+    /**
+     * 运行 Agent 主循环
+     *  1. 发送用户消息
+     *  2. 检查响应
+     *  3. 如果模型要求工具调用 → 执行工具 → 继续发送
+     *  4. 返回最终结果
+     */
+    run(input: string, options?: AgentRunOptions): Promise<AgentRunResult>;
+    /** 导出当前状态为可序列化快照 */
+    snapshot(): AgentSnapshot;
+    /** 从快照恢复状态(需先构造 Agent 再调用此方法) */
+    restore(snapshot: AgentSnapshot): void;
+}
+//# sourceMappingURL=Agent.d.ts.map

package/module/AgentModule/Agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/module/AgentModule/Agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACpH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAiB,MAAM,eAAe,CAAC;AAC7E,OAAO,EAAE,MAAM,EAAkB,MAAM,UAAU,CAAC;AAElD,WAAW;AACX,qBAAa,KAAM,SAAQ,aAAa;IAEpC,YAAY;IACZ,SAAgB,MAAM,EAAE,WAAW,CAAC;IACpC,gCAAgC;IAChC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,WAAW;IACX,OAAO,CAAC,MAAM,CAA+B;IAC7C,WAAW;IACX,OAAO,CAAC,UAAU,CAAa;IAC/B,qBAAqB;IACrB,OAAO,CAAC,WAAW,CAAC,CAAkB;IAEtC,WAAW;gBACQ,MAAM,EAAE,WAAW;IAMtC,WAAW;IACX,IAAW,KAAK,IAAI,UAAU,CAAwB;IACtD,WAAW;IACX,IAAW,SAAS,IAAI,MAAM,CAA4B;IAC1D,eAAe;IACf,IAAW,eAAe,IAAI,OAAO,CAA+C;IAIpF,mCAAmC;IACtB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAIvH,yBAAyB;IACZ,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAIpG,qBAAqB;cACL,aAAa,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAuC9J,4BAA4B;cACZ,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAYjH,wBAAwB;IACX,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAiBnK,+BAA+B;IAClB,WAAW,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAKtF,+BAA+B;IACxB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAM9D,wCAAwC;IACjC,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI;IAKvG,uBAAuB;IAChB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IASxC;;;;;;OAMG;IACU,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IA0EnF,oBAAoB;IACb,QAAQ,IAAI,aAAa;IAuBhC,iCAAiC;IAC1B,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;CAUhD"}