knight-agent 1.2.0 → 1.2.2

package/docs/architecture-manual.md

@@ -0,0 +1,978 @@
+# Knight Agent 2.0 — 架构使用手册
+
+## 目录
+
+- [1. 项目概述](#1-项目概述)
+- [2. 核心架构](#2-核心架构)
+- [3. 快速开始](#3-快速开始)
+- [4. Host 宿主容器](#4-host-宿主容器)
+- [5. LLM 模块](#5-llm-模块)
+- [6. Tool 工具模块](#6-tool-工具模块)
+- [7. Skill 技能模块](#7-skill-技能模块)
+- [8. Agent 代理模块](#8-agent-代理模块)
+- [9. 快照与恢复](#9-快照与恢复)
+- [10. 流式响应](#10-流式响应)
+- [11. 工具调用循环](#11-工具调用循环)
+- [12. 扩展自定义 LLM](#12-扩展自定义-llm)
+- [13. 类型参考](#13-类型参考)
+
+---
+
+## 1. 项目概述
+
+Knight Agent 2.0（包名 `knight-agent`）是一个 **TypeScript 多 LLM Agent 编排框架**。它提供统一的抽象层，封装了多个大模型平台（Claude、DeepSeek、OpenAI、Gemini、QWen），并内置工具调用（Tool Calling）、流式响应（Streaming）、基于意图匹配的技能路由（Skill Routing）、Agent 对话管理以及快照持久化能力。
+
+### 核心能力
+
+- **多平台统一接口**：一套 API 调用 5 个 LLM 平台，自动处理请求体/响应体格式差异
+- **工具调用循环**：自动执行 LLM 返回的 tool_calls，将结果回传，循环直到 LLM 产出最终文本
+- **技能意图匹配**：根据用户输入自动匹配最合适的 Skill，组装提示词和工具集
+- **消息缓存管理**：自动 Trim 历史消息、Compact 工具输出，防止超出上下文窗口
+- **快照/恢复**：Agent 和 LLM 的完整状态可序列化、可恢复
+- **流式响应**：所有平台均支持 SSE 流式解析
+
+---
+
+## 2. 核心架构
+
+```
+┌──────────────────────────────────────────────────┐
+│                    User Code                      │
+└──────────────────────┬───────────────────────────┘
+                       │
+                       ▼
+              ┌─────────────────┐
+              │  Host (Singleton) │
+              │  ┌─────────────┐ │
+              │  │  LLMModule   │ │  ← LLM 工厂 + 注册表
+              │  │  ToolModule  │ │  ← 工具注册表 + 执行器
+              │  │  SkillModule │ │  ← 技能注册表 + 意图匹配
+              │  │  AgentModule │ │  ← Agent 工厂 + 注册表
+              │  └─────────────┘ │
+              └─────────────────┘
+                       │
+                       ▼
+              ┌─────────────────┐
+              │   Agent.send()   │
+              │  ┌─────────────┐ │
+              │  │ 意图匹配      │ │  ← SkillModule.matchBest()
+              │  │ 提示词组装   │ │  ← SkillModule.buildPrompt()
+              │  │ 工具解析      │ │  ← ToolModule.resolve()
+              │  │ LLM 调用      │ │  ← AbstractLLM.send()
+              │  │ 对话记录      │ │  ← Agent.record()
+              │  └─────────────┘ │
+              └─────────────────┘
+```
+
+### 类继承体系
+
+```
+AbstractObject        ← 全局 ID + 注册表 + OnDestroy
+  ├── AbstractModule  ← 模块基类（LLMModule / ToolModule / SkillModule / AgentModule）
+  ├── AbstractLLM     ← LLM 基类：消息缓存、send()、工具循环、快照
+  │     ├── ClaudeLLM
+  │     ├── DeepSeekLLM
+  │     ├── OpenAILLM
+  │     ├── GeminiLLM
+  │     └── QWenLLM
+  └── AbstractAgent   ← Agent 基类：包装 LLM、turn 记录、快照
+        └── Agent     ← 默认实现：意图匹配 → 提示词组装 → 工具解析 → LLM 调用
+```
+
+---
+
+## 3. 快速开始
+
+### 安装
+
+```bash
+npm install knight-agent
+```
+
+### 最简示例
+
+```typescript
+import { Host } from "knight-agent";
+
+// 1. 注册工具
+Host.Instance.toolModule.register({
+    name: "get_weather",
+    description: "获取指定城市的天气",
+    inputSchema: {
+        type: "object",
+        properties: {
+            city: { type: "string", description: "城市名称" }
+        },
+        required: ["city"]
+    },
+    handler: async (args) => {
+        return `城市 ${args.city} 的天气：晴，25°C`;
+    }
+});
+
+// 2. 注册技能
+Host.Instance.skillModule.register({
+    key: "weather_skill",
+    name: "天气查询",
+    description: "查询城市天气信息",
+    trigger: {
+        type: "intent_match",
+        patterns: ["天气", "气温", "下雨"]
+    },
+    toolKeys: ["get_weather"],
+    examples: [
+        { input: "北京今天天气怎么样", output: "北京今天晴，25°C" }
+    ]
+});
+
+// 3. 创建 Agent
+const agent = await Host.Instance.agentModule.create({
+    type: "DeepSeek",
+    model: "deepseek-chat",
+    apiKey: "sk-xxxxxxxx"
+});
+
+// 4. 发送消息
+const response = await agent.send("北京今天天气怎么样");
+console.log(response.content);
+```
+
+---
+
+## 4. Host 宿主容器
+
+`Host` 是单例组合根，持有四个子模块的引用。所有模块通过 `Host.Instance` 访问，不需要手动创建。
+
+```typescript
+import { Host } from "knight-agent";
+
+// 访问四个子模块
+const llmModule    = Host.Instance.llmModule;     // LLMModule
+const toolModule   = Host.Instance.toolModule;     // ToolModule
+const skillModule  = Host.Instance.skillModule;    // SkillModule
+const agentModule  = Host.Instance.agentModule;    // AgentModule
+```
+
+---
+
+## 5. LLM 模块
+
+### 5.1 支持的平台
+
+| 平台     | type 值     | 类名          |
+| -------- | ----------- | ------------- |
+| Claude   | `"Claude"`  | `ClaudeLLM`   |
+| DeepSeek | `"DeepSeek"`| `DeepSeekLLM` |
+| OpenAI   | `"OpenAI"`  | `OpenAILLM`   |
+| Gemini   | `"Gemini"`  | `GeminiLLM`   |
+| QWen     | `"QWen"`    | `QWenLLM`     |
+
+### 5.2 创建 LLM 实例
+
+```typescript
+import { LLMUtility } from "knight-agent";
+
+// 基础配置（适用于所有平台）
+const config: LLMUtility.Config = {
+    type: "DeepSeek",
+    model: "deepseek-chat",
+    apiKey: "sk-xxxxxxxx",
+    systemPrompt: "你是一个有用的助手",
+    temperature: 0.7,
+    maxTokens: 4096,
+    timeout: 60000,          // 毫秒
+    stream: true,            // 是否启用流式
+    maxMessageCache: 50,     // 最大缓存消息数
+    maxToolOutput: 2000      // 工具输出最大字符数
+};
+
+const llm = await Host.Instance.llmModule.add(config);
+```
+
+### 5.3 平台特有配置
+
+```typescript
+// Claude — 支持 thinking 模式
+const claudeConfig: LLMUtility.Claude.Config = {
+    type: "Claude",
+    model: "claude-sonnet-4-6",
+    apiKey: "sk-ant-xxx",
+    thinking: true,
+    speed: "fast",          // "fast" | "default"
+    outputConfig: {
+        thinking: { budgetTokens: 4000 }
+    }
+};
+
+// OpenAI — 支持 reasoning_effort 和 web_search
+const openaiConfig: LLMUtility.OpenAI.Config = {
+    type: "OpenAI",
+    model: "o4-mini",
+    apiKey: "sk-xxx",
+    reasoningEffort: "medium",   // "low" | "medium" | "high"
+    webSearchOptions: {
+        search_context_size: "medium"
+    }
+};
+
+// Gemini — 支持 safetySettings 和 thinkingConfig
+const geminiConfig: LLMUtility.Gemini.Config = {
+    type: "Gemini",
+    model: "gemini-2.5-flash",
+    apiKey: "xxx",
+    topK: 40,
+    thinkingConfig: {
+        thinkingBudget: 1024
+    }
+};
+
+// DeepSeek — 支持 thinking 模式
+const deepSeekConfig: LLMUtility.DeepSeek.Config = {
+    type: "DeepSeek",
+    model: "deepseek-reasoner",
+    apiKey: "sk-xxx",
+    thinking: true
+};
+
+// QWen — 支持联网搜索
+const qwenConfig: LLMUtility.QWen.Config = {
+    type: "QWen",
+    model: "qwen-max",
+    apiKey: "sk-xxx",
+    enableSearch: true
+};
+```
+
+### 5.4 直接使用 LLM
+
+```typescript
+const llm = await Host.Instance.llmModule.add({
+    type: "DeepSeek",
+    model: "deepseek-chat",
+    apiKey: "sk-xxx"
+});
+
+// 发送消息（带工具）
+const response = await llm.send(
+    "北京今天天气怎么样？",
+    [weatherTool],             // ToolDefinition[]，可选
+    (usage) => {               // onUsage 回调
+        console.log("输入:", usage.input, "输出:", usage.output);
+    },
+    (chunk) => {               // onChunk 回调（流式）
+        process.stdout.write(chunk.content || "");
+    }
+);
+
+console.log("完整回复:", response.content);
+console.log("Token 用量:", response.usage);
+
+// 获取 / 移除
+const same = Host.Instance.llmModule.get(llm.id);
+Host.Instance.llmModule.remove(llm.id);
+Host.Instance.llmModule.removeAll();
+```
+
+---
+
+## 6. Tool 工具模块
+
+### 6.1 定义工具
+
+```typescript
+import { LLMUtility } from "knight-agent";
+
+const databaseTool: LLMUtility.ToolDefinition = {
+    name: "query_database",
+    description: "执行 SQL 查询并返回结果",
+    inputSchema: {
+        type: "object",
+        properties: {
+            sql: { type: "string", description: "要执行的 SQL 语句" }
+        },
+        required: ["sql"]
+    },
+    handler: async (args: Record<string, any>) => {
+        // 在这里实现实际的数据库查询逻辑
+        const result = await db.query(args.sql);
+        return JSON.stringify(result);
+    }
+};
+```
+
+### 6.2 注册与管理工具
+
+```typescript
+const tm = Host.Instance.toolModule;
+
+// 注册单个
+tm.register(databaseTool);
+
+// 批量注册
+tm.registerAll([toolA, toolB, toolC]);
+
+// 查询
+const tool = tm.get("query_database");
+const allTools = tm.getAll();
+const exists = tm.has("query_database");
+
+// 按名称批量解析（用于 Skills）
+const resolved = tm.resolve(["tool_a", "tool_b"]);
+// → ToolDefinition[]
+
+// 注销
+tm.unregister("query_database");
+```
+
+### 6.3 工具执行
+
+```typescript
+// 模拟 LLM 返回的工具调用
+const toolCalls: LLMUtility.ToolCall[] = [
+    {
+        id: "call_001",
+        type: "function",
+        function: {
+            name: "query_database",
+            arguments: JSON.stringify({ sql: "SELECT * FROM users" })
+        }
+    }
+];
+
+// 执行工具
+const results: LLMUtility.ToolResult[] = await tm.execute(toolCalls);
+// → [{ tool_call_id: "call_001", role: "tool", content: "..." }]
+```
+
+---
+
+## 7. Skill 技能模块
+
+Skill 是工具 + 提示词 + 触发规则的组合。它定义了一个领域能力，当用户输入匹配到某个 Skill 时，Agent 会自动组装相关工具和提示词。
+
+### 7.1 定义技能
+
+```typescript
+import { LLMUtility } from "knight-agent";
+
+const weatherSkill: LLMUtility.SkillData = {
+    key: "weather_skill",
+    name: "天气查询",
+    description: "你可以查询城市的天气信息。回复时请使用友好的语气。",
+    tags: ["weather", "utility"],
+    trigger: {
+        type: "intent_match",     // 基于关键词的意图匹配
+        patterns: ["天气", "气温", "下雨", "下雪", "台风"]
+    },
+    toolKeys: ["get_weather", "get_forecast"],
+    dependencies: ["location_skill"],
+    examples: [
+        { input: "北京天气怎么样", output: "北京今天晴，25°C" },
+        { input: "明天上海会下雨吗", output: "明天上海有小雨，记得带伞" }
+    ]
+};
+```
+
+### 7.2 注册与查询技能
+
+```typescript
+const sm = Host.Instance.skillModule;
+
+// 注册
+sm.register(weatherSkill);
+sm.registerAll([skillA, skillB]);
+
+// 按条件查询
+sm.findByCategory("utility");
+sm.findByTag("weather");
+sm.findByIntent("天气");
+sm.findByTriggerType("intent_match");
+
+// 解析技能的依赖
+const deps = sm.resolveDependencies("weather_skill");   // → SkillData[]
+const tools = sm.resolveTools("weather_skill");          // → ToolDefinition[]
+```
+
+### 7.3 意图匹配原理
+
+`SkillModule.matchBest(prompt)` 遍历所有 `trigger.type === "intent_match"` 的技能，计算每个技能的 `patterns` 中与用户输入最长子串匹配的字符数，返回得分最高的技能。
+
+```typescript
+// 内部机制演示
+const skill = sm.matchBest("我想查一下北京今天天气");
+// → weatherSkill（因为 "天气" pattern 匹配成功）
+```
+
+---
+
+## 8. Agent 代理模块
+
+Agent 是用户交互的顶层入口，它将 Skill 路由、Tool 装配、LLM 调用串联起来。
+
+### 8.1 创建 Agent
+
+```typescript
+const am = Host.Instance.agentModule;
+
+const agent = await am.create({
+    type: "DeepSeek",
+    model: "deepseek-chat",
+    apiKey: "sk-xxx",
+    systemPrompt: "你是一个专业的助手"
+});
+
+// 或注入已有 LLM
+const existingLLM = Host.Instance.llmModule.add(config);
+const agent2 = await am.create({
+    type: "DeepSeek",
+    model: "deepseek-chat",
+    apiKey: "sk-xxx"
+}, existingLLM);  // 第二个参数可选
+```
+
+### 8.2 Agent.send() 完整流程
+
+```typescript
+// agent.send() 内部执行以下步骤：
+//
+// 1. SkillModule.matchBest(prompt)      → 意图匹配
+// 2. SkillModule.buildPrompt(skill, p)  → 组装提示词
+// 3. ToolModule.resolve(skill.toolKeys) → 解析工具
+// 4. LLM.send(fullPrompt, tools, ...)   → 调用大模型
+// 5. Agent.record(input, output, usage) → 记录上下文
+
+const response = await agent.send("北京今天天气怎么样？", (chunk) => {
+    // 可选：流式回调
+    console.log(chunk.content);
+});
+```
+
+### 8.3 查询与管理 Agent
+
+```typescript
+const agent = am.get(agentId);   // 按 ID 获取
+const all = am.list();           // 列出所有 Agent
+
+am.remove(agentId);              // 移除单个（同时销毁其 LLM）
+am.removeAll();                  // 移除全部
+```
+
+### 8.4 Agent 上下文记录
+
+每个 Agent 内部维护一个 `turns: SessionData[]` 数组，记录每次对话的输入/输出/用量/时间戳：
+
+```typescript
+// AgentUtility.SessionData 结构
+{
+    input: "用户原始输入",
+    output: { id: "resp_01", model: "deepseek-chat", content: "...", usage: {...} },
+    usage: { input: 120, output: 80, total: 200 },
+    timestamp: "2026-06-28T12:00:00.000Z"
+}
+```
+
+---
+
+## 9. 快照与恢复
+
+框架支持完整的 Agent/LLM 状态序列化与恢复，适用于跨会话持久化。
+
+### 9.1 导出快照
+
+```typescript
+const agent = await am.create(config);
+
+// 发送一些消息...
+await agent.send("你好");
+
+// 导出快照
+const snapshot = agent.exportSnapshot();
+// → AgentUtility.AgentSnapshot {
+//     id: "agent-uuid",
+//     llmSnapshot: { id, config, messages, timestamp },
+//     turns: [...],
+//     createdAt: "...",
+//     exportAt: "..."
+//   }
+
+// 序列化为 JSON 存储
+const json = JSON.stringify(snapshot);
+fs.writeFileSync("agent-state.json", json);
+```
+
+### 9.2 从快照恢复
+
+```typescript
+const json = fs.readFileSync("agent-state.json", "utf-8");
+const snapshot = JSON.parse(json);
+
+// 恢复 Agent（包含 LLM 状态 + 对话历史）
+const restoredAgent = await am.restore(snapshot);
+
+// 继续之前的对话
+await restoredAgent.send("继续刚才的话题");
+```
+
+### 9.3 仅 LLM 快照
+
+```typescript
+// 导出 LLM 快照
+const llmSnapshot = llm.exportSnapshot();
+
+// 从快照恢复 LLM
+const restoredLLM = Host.Instance.llmModule.restore(llmSnapshot);
+```
+
+---
+
+## 10. 流式响应
+
+所有平台均支持 SSE（Server-Sent Events）流式响应，通过 `onChunk` 回调接收增量数据。
+
+### 10.1 LLM 层流式调用
+
+```typescript
+const llm = await Host.Instance.llmModule.add({
+    type: "Claude",
+    model: "claude-sonnet-4-6",
+    apiKey: "sk-ant-xxx",
+    stream: true   // 启用流式
+});
+
+const response = await llm.send(
+    "写一首关于夏天的诗",
+    undefined,
+    (usage) => console.log("用量:", usage),
+    (chunk: LLMUtility.StreamChunk) => {
+        // chunk 结构: { content, delta, toolCalls, finishReason, usage, raw }
+        if (chunk.content) {
+            process.stdout.write(chunk.content);
+        }
+    }
+);
+
+// response 包含完整聚合结果
+console.log("\n\n完整:", response.content);
+```
+
+### 10.2 Agent 层流式调用
+
+```typescript
+const agent = await Host.Instance.agentModule.create({
+    type: "DeepSeek",
+    model: "deepseek-chat",
+    apiKey: "sk-xxx"
+});
+
+await agent.send("写一首诗", (chunk) => {
+    if (chunk.content) {
+        process.stdout.write(chunk.content);
+    }
+});
+```
+
+### 10.3 各平台 SSE 事件差异
+
+框架内部处理了不同平台的 SSE 格式：
+
+| 平台     | SSE 事件格式                                                                 |
+| -------- | --------------------------------------------------------------------------- |
+| Claude   | `message_start` / `content_block_start` / `content_block_delta` / `message_delta` |
+| Gemini   | `candidates` 数组 + `parts` 增量                                            |
+| DeepSeek | OpenAI 兼容 delta 格式                                                      |
+| OpenAI   | OpenAI 兼容 delta 格式                                                      |
+| QWen     | OpenAI 兼容 delta 格式                                                      |
+
+---
+
+## 11. 工具调用循环
+
+当 LLM 返回 `finishReason === "tool_calls"` 时，框架自动进入工具调用循环：
+
+```
+用户提示词
+  │
+  ▼
+LLM.send() ──→ LLM 返回 tool_calls
+  │                │
+  │                ▼
+  │         executeTools()   ← 调用 handler
+  │                │
+  │                ▼
+  │         将 ToolResult 传回 LLM
+  │                │
+  │                ▼
+  │         LLM 再次返回...
+  │         ├── tool_calls → 继续循环（最多 100 轮）
+  │         └── stop → 返回最终 Response
+  │
+  ▼
+返回给调用方
+```
+
+### 关键配置
+
+```typescript
+const config: LLMUtility.Config = {
+    // ...
+    maxToolOutput: 2000,   // 单次工具输出被截断的最大字符数，防止超出上下文
+    maxMessageCache: 50    // 消息缓存上限，超出后按 turn 裁剪
+};
+```
+
+`compactMessages()` 会在每次 `send()` 前执行，将消息缓存中的工具结果截断到 `maxToolOutput`。`messages.Trim()` 按 turn 数裁剪，保留 system 消息。
+
+---
+
+## 12. 扩展自定义 LLM
+
+要接入新的 LLM 平台，继承 `AbstractLLM` 并实现 7 个抽象方法：
+
+```typescript
+import { AbstractLLM, LLMUtility } from "knight-agent";
+
+interface MyPlatformConfig extends LLMUtility.Config {
+    type: "MyPlatform";
+    customOption: string;
+}
+
+interface MyMessageData extends LLMUtility.MessageData {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+}
+
+class MyPlatformLLM extends AbstractLLM<MyPlatformConfig, MyMessageData> {
+
+    addSystemMessage(config: MyPlatformConfig): void {
+        this.messages.Add({ role: "system", content: config.systemPrompt, preserve: true });
+    }
+
+    addUserMessage(prompt: string): void {
+        this.messages.Add({ role: "user", content: prompt, preserve: false });
+    }
+
+    addAssistantMessage(response: LLMUtility.Response): void {
+        // 需要同时记录工具调用和文本内容
+        this.messages.Add({
+            role: "assistant",
+            content: response.content,
+            preserve: false
+        });
+    }
+
+    addToolMessage(result: LLMUtility.ToolResult): void {
+        this.messages.Add({
+            role: "tool",
+            content: result.content,
+            preserve: false
+        });
+    }
+
+    compactMessages(maxOutput: number): void {
+        // 遍历消息，截断超长工具输出
+        for (const msg of this.messages.All()) {
+            if (msg.role === "tool" && msg.content.length > maxOutput) {
+                msg.content = msg.content.substring(0, maxOutput) + "...[截断]";
+            }
+        }
+    }
+
+    stopReason(reason: string): boolean {
+        return reason === "stop" || reason === "end_turn";
+    }
+
+    async request(
+        tools: LLMUtility.ToolDefinition[] | undefined,
+        onUsage: (usage: LLMUtility.Usage) => void,
+        onChunk: (chunk: LLMUtility.StreamChunk) => void
+    ): Promise<LLMUtility.Response> {
+        if (this.config.stream) {
+            return this.requestStream(tools, onUsage, onChunk);
+        }
+        return this.requestSync(tools, onUsage);
+    }
+
+    private async requestSync(tools: any[], onUsage: any): Promise<LLMUtility.Response> {
+        // 1. 构建请求体（平台特有格式）
+        // 2. 发送 HTTP POST
+        // 3. 解析响应 → LLMUtility.Response
+        // 4. 调用 onUsage(usage)
+        // 5. 返回 Response
+        throw new Error("未实现");
+    }
+
+    private async requestStream(tools: any[], onUsage: any, onChunk: any): Promise<LLMUtility.Response> {
+        // 1. 构建请求体
+        // 2. 使用 HTTP.onStreamRequest() 发起 SSE 连接
+        // 3. 逐块解析 → 调用 onChunk(chunk)
+        // 4. 聚合完整响应
+        // 5. 调用 onUsage(usage)
+        // 6. 返回聚合 Response
+        throw new Error("未实现");
+    }
+}
+```
+
+然后在 `LLMModule.add()` 的 switch 语句中注册新平台即可。
+
+---
+
+## 13. 类型参考
+
+### AgentUtility
+
+```typescript
+// Token 用量
+interface Usage {
+    input: number;    // 输入 token
+    output: number;   // 输出 token
+    total: number;    // 总计 token
+}
+
+// 会话回合
+interface SessionData {
+    input: string;
+    output: LLMUtility.Response;
+    usage: Usage;
+    timestamp: string;
+}
+
+// Agent 快照
+interface AgentSnapshot {
+    id: string;
+    llmSnapshot: LLMUtility.Snapshot;
+    turns: SessionData[];
+    createdAt: string;
+    exportAt: string;
+}
+```
+
+### LLMUtility 核心类型
+
+```typescript
+// 工具定义
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+    handler: (args: Record<string, any>) => Promise<string>;
+}
+
+// 工具调用
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;  // JSON 字符串
+    };
+}
+
+// 工具结果
+interface ToolResult {
+    tool_call_id: string;
+    role: "tool";
+    content: string;
+}
+
+// 统一响应
+interface Response {
+    id: string;
+    model: string;
+    content: string | null;
+    toolCalls: ToolCall[];
+    finishReason: string;
+    usage: Usage;
+    raw: any;  // 平台原始响应
+}
+
+// 流式块
+interface StreamChunk {
+    content: string | null;
+    delta: any;
+    toolCalls: ToolCall[];
+    finishReason: string | null;
+    usage: Usage | null;
+    raw: any;
+}
+
+// 技能定义
+interface SkillData {
+    key: string;
+    name: string;
+    description: string;
+    tags?: string[];
+    trigger: SkillTrigger;
+    toolKeys?: string[];
+    dependencies?: string[];
+    examples?: SkillExample[];
+}
+
+interface SkillTrigger {
+    type: "intent_match" | "event" | "manual";
+    patterns?: string[];
+    event?: string;
+}
+
+interface SkillExample {
+    input: string;
+    output: string;
+}
+
+// 快照
+interface Snapshot {
+    id: string;
+    config: Config;
+    messages: MessageData[];
+    timestamp: string;
+}
+```
+
+### 工具类
+
+```typescript
+// ObjectUtility 中的数据结构
+class ArrayPool<T>    // 基于数组的对象池：Get / Add / Remove / Exist
+class MapPool<T>      // 基于 Map 的对象池：Get / Add / Set / Remove / KeysToArray / ValuesToArray
+class QueuePool<T>    // 队列：Enqueue / Dequeue / Peek / IsEmpty / Size / Clear / Clone
+
+// LogUtility
+function LogTip(msg: string): void;       // 灰色
+function LogInfo(msg: string): void;      // 白色
+function LogWarning(msg: string): void;   // 黄色
+function LogError(msg: string): void;     // 红色
+
+// NetworkUtility
+async function HTTP.OnRequest(req: Request): Promise<Response>;         // 标准 HTTP
+async function HTTP.onStreamRequest(req: Request): AsyncGenerator<any>;  // SSE 流
+
+// 其他工具
+function StringUtility.empty(str: string | null | undefined): boolean;
+function StringUtility.GetHash(str: string): number;
+function StringUtility.GetGUID(): string;
+function TimeUtility.Now(): number;
+function TimeUtility.NowString(): string;
+function TimeUtility.NowHEX(): string;
+function PromiseUtility.Wait(ms: number): Promise<void>;
+```
+
+---
+
+## 附录：完整示例 — 构建一个数据库查询 Agent
+
+```typescript
+import { Host, LLMUtility } from "knight-agent";
+
+async function main() {
+    // === 注册工具 ===
+    const tm = Host.Instance.toolModule;
+
+    tm.register({
+        name: "execute_sql",
+        description: "执行 SQL 查询。仅支持 SELECT 语句。",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sql: { type: "string", description: "SQL SELECT 语句" }
+            },
+            required: ["sql"]
+        },
+        handler: async (args) => {
+            // 安全校验
+            const sql: string = args.sql.trim().toUpperCase();
+            if (!sql.startsWith("SELECT")) {
+                return "错误：仅允许 SELECT 查询";
+            }
+            // 模拟数据库查询
+            const mockData = [
+                { id: 1, name: "Alice", role: "工程师" },
+                { id: 2, name: "Bob", role: "设计师" },
+                { id: 3, name: "Carol", role: "产品经理" }
+            ];
+            return JSON.stringify(mockData, null, 2);
+        }
+    });
+
+    tm.register({
+        name: "get_schema",
+        description: "获取数据库表结构信息",
+        inputSchema: {
+            type: "object",
+            properties: {
+                table: { type: "string", description: "表名，留空返回所有表" }
+            },
+            required: []
+        },
+        handler: async (args) => {
+            const schemas: Record<string, any> = {
+                "users": {
+                    columns: [
+                        { name: "id", type: "INTEGER", primaryKey: true },
+                        { name: "name", type: "VARCHAR(100)" },
+                        { name: "role", type: "VARCHAR(50)" },
+                        { name: "created_at", type: "DATETIME" }
+                    ],
+                    rowCount: 1024
+                },
+                "orders": {
+                    columns: [
+                        { name: "id", type: "INTEGER", primaryKey: true },
+                        { name: "user_id", type: "INTEGER" },
+                        { name: "amount", type: "DECIMAL(10,2)" },
+                        { name: "status", type: "VARCHAR(20)" }
+                    ],
+                    rowCount: 5120
+                }
+            };
+
+            if (args.table && schemas[args.table]) {
+                return JSON.stringify(schemas[args.table], null, 2);
+            }
+            return JSON.stringify(Object.keys(schemas), null, 2);
+        }
+    });
+
+    // === 注册技能 ===
+    Host.Instance.skillModule.register({
+        key: "db_skill",
+        name: "数据库查询助手",
+        description: "你是一个数据库查询助手。在查询前，先使用 get_schema 了解表结构，再用 execute_sql 执行查询。回复时请将结果格式化输出。",
+        trigger: {
+            type: "intent_match",
+            patterns: ["查询", "数据", "SQL", "数据库", "表", "统计"]
+        },
+        toolKeys: ["get_schema", "execute_sql"],
+        examples: [
+            {
+                input: "查询所有用户",
+                output: "我先查看 users 表结构，然后执行查询。结果如下：\n1. Alice - 工程师\n2. Bob - 设计师\n3. Carol - 产品经理"
+            }
+        ]
+    });
+
+    // === 创建 Agent ===
+    const agent = await Host.Instance.agentModule.create({
+        type: "DeepSeek",
+        model: "deepseek-chat",
+        apiKey: process.env.DEEPSEEK_API_KEY!,
+        systemPrompt: "你是一个数据库查询助手。请使用提供的工具来帮助用户查询数据。",
+        temperature: 0.3,
+        maxTokens: 4096
+    });
+
+    // === 交互 ===
+    const response = await agent.send("查询 users 表中所有用户的姓名和角色");
+    console.log(response.content);
+
+    // === 导出快照 ===
+    const snapshot = agent.exportSnapshot();
+    console.log("快照已生成，turns 数:", snapshot.turns.length);
+
+    // === 清理 ===
+    Host.Instance.agentModule.removeAll();
+    Host.Instance.toolModule.unregister("execute_sql");
+    Host.Instance.toolModule.unregister("get_schema");
+}
+
+main().catch(console.error);
+```