knight-agent 1.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,601 @@
+# Knight Agent 2.0 — 技术架构手册
+
+---
+
+## 目录
+
+- [一、架构全景图](#一架构全景图)
+- [二、分层设计](#二分层设计)
+- [三、模块详细设计](#三模块详细设计)
+- [四、执行路径](#四执行路径)
+- [五、Token 优化管线](#五token-优化管线)
+- [六、设计决策记录](#六设计决策记录)
+- [七、持久化模型](#七持久化模型)
+- [八、扩展点](#八扩展点)
+
+---
+
+## 一、架构全景图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          业务层 (Business Layer)                  │
+│  注册工具/技能 → 创建对话 → 启用技能 → dialog.send("...")           │
+└────────────────────────────────┬────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                        Host (单例 — src/Host.ts)                  │
+│                                                                   │
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐              │
+│  │  AgentModule │ │  ToolModule  │ │ SkillModule  │              │
+│  │  (创建/销毁)  │ │ (注册/执行/   │ │ (能力包/对话  │              │
+│  │   Agent 池    │ │  缓存/RAG)   │ │  级启用禁用)  │              │
+│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘              │
+│         │                │                │                       │
+│  ┌──────┴───────┐        │                │                       │
+│  │ DialogModule │        │                │                       │
+│  │ (对话池/快照) │────────┼────────────────┘                       │
+│  └──────┬───────┘        │                                        │
+│         │                │                                        │
+│  ┌──────┴────────────────┴───────┐                                │
+│  │        ReasonModule           │                                │
+│  │  (6种推理策略池/执行入口)       │                                │
+│  │  Chain → Reflect → Tree       │                                │
+│  │  → Plan → Competitive → Cmd   │                                │
+│  └───────────────────────────────┘                                │
+└─────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    基础设施层 (Base Layer — src/base/)             │
+│                                                                   │
+│  AbstractObject  ←── 全局ID + 对象池 + Host引用                    │
+│       │                                                           │
+│       ├── AbstractModule  ←── 模块基类                             │
+│       ├── AbstractAgent   ←── run()/send()/executeTool/snapshot   │
+│       ├── AbstractReason  ←── execute()/buildRunOptions()         │
+│       ├── AbstractDialog  ←── send()/switchStrategy()/snapshot()  │
+│       ├── AbstractTool    ←── ToolDefinition/ToolContext 接口      │
+│       └── AbstractSkill   ←── Skill/SkillConstraints 接口          │
+└─────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    实现层 (Module Layer — src/module/)            │
+│                                                                   │
+│  AgentModule/Agent.ts     — Agent 实例 + ReAct 循环                │
+│  AgentModule/Memory.ts    — 消息缓存 + Token计数 + 3级压缩         │
+│  ToolModule/ToolModule.ts — 工具注册表 + 缓存+重试+Compact Schema  │
+│  ToolModule/ToolRAG.ts    — 语义检索 (关键词/Embedding)            │
+│  SkillModule/SkillModule.ts — 技能注册 + 通配展开 + Prompt聚合     │
+│  DialogModule/Dialog.ts   — 对话实例 (内部创建Agent)               │
+│  DialogModule/DialogModule.ts — 对话池 + 快照导入导出               │
+│  ReasonModule/ReasonModule.ts — 策略注册 + 一次性执行入口           │
+│  ReasonModule/*.ts        — 6 个推理策略实现                        │
+└─────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    工具层 (Utility — src/utility/)                │
+│  OpenAIUtility  NetworkUtility  LogUtility  ObjectUtility        │
+│  StringUtility  TimeUtility     PromiseUtility  InterfaceUtility  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 文件依赖关系
+
+```
+src/
+├── index.ts                 → 统一导出 (Host + modules)
+├── Host.ts                  → 单例，组装5个模块
+├── base/                    → 抽象层 (6个文件, 仅接口+抽象类)
+│   ├── AbstractObject.ts    → 全局ID + 对象池
+│   ├── AbstractModule.ts    → 模块标识
+│   ├── AbstractAgent.ts     → Agent 抽象 (run/snapshot/restore)
+│   ├── AbstractReason.ts    → 推理抽象 (execute/buildRunOptions)
+│   ├── AbstractDialog.ts    → 对话抽象 (send/switchStrategy)
+│   ├── AbstractTool.ts      → ToolDefinition + ToolContext 接口
+│   └── AbstractSkill.ts     → Skill + SkillConstraints 接口
+├── module/                  → 实现层 (10个文件)
+│   ├── AgentModule/
+│   │   ├── AgentModule.ts   → Agent 池管理
+│   │   ├── Agent.ts         → Agent 实现 (ReAct循环)
+│   │   └── Memory.ts        → 记忆管理 (Token计数+压缩)
+│   ├── ToolModule/
+│   │   ├── ToolModule.ts    → 工具注册表+执行调度
+│   │   └── ToolRAG.ts       → 语义检索
+│   ├── SkillModule/
+│   │   └── SkillModule.ts   → 技能管理
+│   ├── DialogModule/
+│   │   ├── DialogModule.ts  → 对话池+快照
+│   │   └── Dialog.ts        → 对话实例
+│   └── ReasonModule/
+│       ├── ReasonModule.ts  → 策略池+执行入口
+│       ├── ChainReason.ts   → 链式推理
+│       ├── ReflectReason.ts → 反思推理
+│       ├── TreeReason.ts    → 思维树推理
+│       ├── PlanReason.ts    → 计划执行推理
+│       ├── CompetitiveReason.ts → 竞争推理
+│       └── CommanderReason.ts   → 指挥调度推理
+└── utility/                 → 工具函数层 (8个文件)
+```
+
+---
+
+## 二、分层设计
+
+### 2.1 基础抽象层 (src/base/)
+
+所有对外接口和抽象类统一在 `src/base/` 定义。实现层 (src/module/) 负责具体逻辑，业务层仅依赖抽象层。
+
+**设计原则**：
+- **接口优先**: ToolDefinition、Skill、AgentConfig 等均为 interface，业务层无实现依赖
+- **抽象方法**: AbstractAgent/AbstractReason/AbstractDialog 定义核心契约，实现类填充细节
+- **单向依赖**: 实现层引用抽象层，抽象层不可引用实现层
+
+### 2.2 模块体系 (AbstractModule)
+
+所有功能模块继承 `AbstractModule → AbstractObject`：
+
+```
+AbstractObject
+  ├── .id: string          // GUID 自动分配
+  ├── .key: string          // 类名
+  ├── .host: Host           // 向上访问 Host 单例
+  └── static objects: MapPool<AbstractObject>  // 全局对象池
+
+AbstractModule extends AbstractObject
+  // 模块标识，当前无额外成员
+```
+
+任何 `AbstractObject` 子类都可以通过 `this.host` 访问所有模块，无需依赖注入。
+
+### 2.3 单例 Host
+
+`Host` 是唯一的组装点，创建并持有 5 个模块实例。模块之间通过 `this.host` 互相访问，形成星型拓扑：
+
+```
+                ┌───────┐
+                │ Host  │
+                └──┬────┘
+       ┌──────────┼──────────────┐
+       │          │              │
+  AgentModule  ToolModule   SkillModule
+       │          │              │
+       └──────────┼──────────────┘
+                  │
+            ReasonModule
+                  │
+            DialogModule
+```
+
+---
+
+## 三、模块详细设计
+
+### 3.1 AgentModule — 智能体生命周期
+
+```
+AgentModule
+  ├── createAgent(config) → Agent         // 创建 + 注入 systemPrompt
+  ├── destroyAgent(id)                    // 销毁 + 清理 Memory
+  ├── destroyAll()                        // 批量销毁
+  ├── getAgent(id) → Agent?               // 查询
+  └── getAllAgents() → Agent[]            // 全量
+```
+
+**Agent 内部结构**:
+```
+Agent extends AbstractAgent
+  ├── config: AgentConfig                 // 配置副本
+  ├── memory: Memory                      // 消息缓存 + Token管理
+  ├── state: AgentState                   // Idle/Thinking/Running/WaitingTool/Error/Done
+  ├── turnCount: number                   // 对话轮次
+  ├── sendUserMessage(content)            // 缓存用户消息 → 发送 → 缓存回复
+  ├── sendRequest()                       // 直接发送当前缓存
+  ├── executeTool(toolCall) → result      // 委托给 ToolModule.Execute()
+  ├── addToolResult(result, callId)       // 添加工具结果到缓存
+  ├── run(input, options?) → AgentRunResult // ReAct 主循环
+  ├── snapshot() → AgentSnapshot          // 导出
+  └── restore(snapshot)                   // 恢复
+```
+
+**ReAct 主循环 (Agent.run)**:
+```
+1. sendUserMessage(input)          → 发送用户消息
+2. if no response → Error
+3. while finish_reason == "tool_calls":
+   a. for each tool_call: executeTool → addToolResult
+   b. sendRequest()                 → 提交工具结果继续
+   c. addAssistantMessage(...)      → 缓存 assistant 消息
+4. return final result
+```
+
+### 3.2 Memory — 记忆管理
+
+```
+Memory
+  ├── messages: Message                  // OpenAI 格式消息队列
+  ├── scratchpad: string                 // 思维草稿区
+  ├── toolResults: Map<id, result>       // 工具结果缓存
+  ├── estimateTokens() → number          // tiktoken 精确计数
+  ├── checkPressure() → MemoryPressure   // 压力检测
+  ├── optimize(level)                    // 分级压缩
+  ├── summarize(msgs) → string           // LLM 摘要
+  └── extractEntities(msgs) → {}         // LLM 实体提取
+```
+
+**MemoryPressure 压缩策略**:
+
+| 级别 | 算法 | 描述 |
+|------|------|------|
+| Mild | 早期摘要 | 前 30% 非系统消息 → 1 次 LLM 调用生成摘要，替换原文 |
+| Moderate | 5层裁剪 | 系统消息 + 远期实体提取 + 中间摘要 + 保留最近 6 轮 + 工具配对 |
+| Critical | 激进裁剪 | 保留最近 3 轮 + 工具配对 + 其余拼接为纯文本摘要 (无 LLM 调用) |
+
+### 3.3 ToolModule — 工具管理
+
+```
+ToolModule
+  ├── register(tool)                     // 单个注册 + RAG 索引
+  ├── registerAll(tools)                 // 批量注册
+  ├── unregister(name)                   // 移除 + 清缓存 + 去索引
+  ├── get(name) → ToolDefinition?        // 查询
+  ├── list() → ToolDefinition[]          // 全量
+  ├── listByCategory(cat) → []           // 按分类
+  ├── selectTools(query, candidates?, topK) → string[]  // RAG 排序
+  ├── ToAPITools(names?, compact?) → ToolCall[]         // 导出 OpenAI 格式
+  ├── Execute(toolCall, ctx) → string    // 执行 (含缓存+重试)
+  ├── ExecuteBatch(toolCalls, ctx) → Map // 批量 (自动分组并行/串行)
+  ├── invalidateCache(name?)             // 缓存管理
+  ├── clear()                            // 清空
+  └── setEmbeddingProvider(provider)     // 设置 Embedding
+```
+
+**工具执行流程 (ToolModule.Execute)**:
+```
+1. 查找工具定义
+2. 解析 arguments JSON
+3. 如果 cacheable: 检查缓存 → 命中则返回
+4. 执行 handler(args)
+   - 失败 → 如果 retryable: 等待 delay → 重试 (最多 maxRetries 次)
+5. 如果 cacheable: 写入缓存
+6. 返回结果字符串
+```
+
+**Compact Schema (stripSchema)**:
+递归裁剪 `description` 和 `default`，仅保留核心结构字段:
+```
+保留: type, enum, required, properties, items
+移除: description, default
+```
+
+### 3.4 ToolRAG — 工具语义检索
+
+```
+ToolRAG
+  ├── _provider: IEmbeddingProvider?     // 可插拔 Embedding 提供者
+  ├── _index: Map<name, vector>          // 向量索引 (仅 Embedding 模式)
+  ├── setProvider(p)                     // 设置后触发重建索引
+  ├── index(name, desc)                  // 索引入库
+  ├── remove(name)                       // 移除索引
+  └── search(query, candidates, topK) → string[]
+       ├── 有 provider → _semanticSearch() (余弦相似度)
+       └── 无 provider → _keywordSearch() (中文1-2字滑动窗口 + 英文词匹配)
+```
+
+**选型理由**: 默认关键词匹配零依赖，避免引入 ML 依赖。IEmbeddingProvider 接口允许业务层按需接入任意 Embedding 服务。
+
+### 3.5 SkillModule — 技能管理
+
+```
+SkillModule
+  ├── register(skill)                    // 注册技能定义
+  ├── unregister(name)                   // 移除 + 清理所有对话绑定
+  ├── get / list / listByCategory        // 查询
+  ├── enable(dialogId, skillName)        // 对话级启用
+  ├── disable(dialogId, skillName)       // 对话级禁用
+  ├── getEnabled(dialogId) → string[]    // 获取启用列表
+  ├── resolveTools(dialogId) → ToolDefinition[]  // 解析可用工具 (展开通配符)
+  ├── buildPrompt(dialogId) → string     // 聚合 systemPrompt
+  └── clearDialog(dialogId)             // 清理
+```
+
+**resolveTools 通配符展开逻辑**:
+```
+输入: skill.tools = ["pc/*", "web/search"]
+1. "pc/*" → 遍历 ToolModule 全部工具名, 匹配 "pc/" 前缀
+2. "web/search" → 精确查找
+输出: [ToolDefinition(pc/screenshot), ToolDefinition(pc/clipboard), ToolDefinition(web/search)]
+```
+
+### 3.6 ReasonModule — 推理策略
+
+```
+ReasonModule
+  ├── _reasons: MapPool<AbstractReason>  // 策略池 (6个内置 + 可扩展)
+  ├── register(name, reason)             // 注册自定义策略
+  ├── get(name) → AbstractReason?        // 获取实例
+  ├── execute(input, config, strategy) → ReasonResult  // 一次性执行入口
+  └── list() → [{name, type}]
+```
+
+**策略内部对 useAgent 的处理**:
+```
+单 Agent 策略 (Chain/Reflect/Tree/Plan):
+  agent = config.useAgent ?? createAgent(config.baseConfig)
+  try: agent.run(input, runOptions)
+  finally: if (!config.useAgent) destroyAgent(agent)
+
+多 Agent 策略 (Competitive/Commander):
+  主Agent(裁判/指挥) = config.useAgent ?? createAgent(...)
+  临时Agent(竞争者/工人) = createAgent(...) → 自动销毁
+```
+
+### 3.7 DialogModule — 对话管理
+
+```
+DialogModule
+  ├── _dialogs: MapPool<Dialog>          // 对话池
+  ├── create(title, config, strategy?) → Dialog
+  ├── destroy(dialogId)                  // 委托 Dialog.destroy()
+  ├── get(dialogId) → Dialog?
+  ├── list() → [{dialogId, title, strategy}]
+  ├── export(dialogId) → DialogSnapshot? // 导出快照
+  └── import(snapshot, config) → Dialog? // 恢复 (需重新提供 apiKey)
+```
+
+---
+
+## 四、执行路径
+
+### 路径一: 一次性推理
+
+```
+ReasonModule.execute(input, config, strategy)
+  │
+  ├── 查找策略: _reasons.Get(strategy)
+  ├── reason.execute(input, config)
+  │     ├── 创建 Agent: agentModule.createAgent(config.baseConfig)
+  │     ├── agent.run(input, buildRunOptions(config))
+  │     │     ├── sendUserMessage → OnSendRequest
+  │     │     │     ├── memory.checkPressure() → optimize()
+  │     │     │     ├── ToAPITools(names, compact=true)
+  │     │     │     └── HTTP POST → LLM
+  │     │     └── tool_calls loop → executeTool → sendRequest
+  │     ├── 销毁 Agent: agentModule.destroyAgent(agent.id)
+  │     └── return ReasonResult
+  └── return result
+```
+
+### 路径二: 持久化对话
+
+```
+Dialog.send(input)
+  │
+  ├── 获取策略: reasonModule.get(this.strategy)
+  ├── 过滤工具: skillModule.resolveTools(this.id) → ToolDefinition[]
+  ├── 排序工具: toolModule.selectTools(input, toolNames, topK) → string[]
+  ├── 聚合提示: skillModule.buildPrompt(this.id) → string
+  ├── 构建上下文: { agentId, dialogId, turnCount }
+  ├── reason.execute(input, {
+  │     baseConfig: this.config,
+  │     useAgent: this.agent,       // 复用持久化 Agent
+  │     toolNames, toolContext, skillPrompt
+  │   })
+  │     ├── ChainReason: agent.run(input, runOptions)
+  │     │     ├── memory.checkPressure() → optimize()
+  │     │     ├── ToAPITools(runOptions.toolNames, compact=true)  // 仅 Skill 过滤后的工具
+  │     │     └── ReAct 循环
+  │     └── return ReasonResult
+  └── return DialogResult { ...result, dialogId }
+```
+
+**关键差异**: Dialog 路径在 Agent 执行前多了三个步骤:
+1. `resolveTools()` — Skill 过滤
+2. `selectTools()` — RAG 语义排序
+3. `buildPrompt()` — 注入 Skill 系统提示
+
+---
+
+## 五、Token 优化管线
+
+```
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│  Skill 过滤   │ →  │  RAG 排序    │ →  │  Compact     │ →  │  Memory 压缩  │
+│  (P-前置)     │    │  (P3)        │    │  (P0)        │    │  (P1+P2)     │
+└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
+     ↓                    ↓                    ↓                    ↓
+ resolveTools()     selectTools()       ToAPITools(           checkPressure()
+ 通配符展开          语义排序             compact=true)         → optimize()
+ 精确匹配            Top-K 裁剪          递归去 description    tiktoken 计数
+```
+
+**效果估算** (100 个工具注册):
+
+| 阶段 | 工具数 | Token 估算 | 缩减率 |
+|------|--------|-----------|--------|
+| 原始注册 | 100 | ~50,000 | — |
+| Skill 过滤后 | ~20 | ~10,000 | 80% |
+| RAG Top-10 | 10 | ~5,000 | 50% |
+| Compact Schema | 10 | ~1,500 | 70% |
+| **最终** | **10** | **~1,500** | **97%** |
+
+Memory 压缩在独立维度上工作，减少的是消息历史的 Token 开销，与工具优化互补。
+
+---
+
+## 六、设计决策记录
+
+### 6.1 Agent 缓存为何留在 Agent 内部而非 Dialog？
+
+**考虑**: 将 `_cache` 从 ToolModule/ToolRAG 移到 Dialog？
+
+**结论: 不迁移。**
+
+原因:
+- 一次性推理路径 (ReasonModule → Agent) 也需要缓存，不应与 Dialog 绑定
+- 多 Agent 策略 (Competitive/Commander) 中多个 Agent 共享同一个 ToolModule，缓存归 ToolModule 更合理
+- Memory 优化与 Agent 的消息历史紧密耦合，移到 Dialog 会导致循环依赖
+
+### 6.2 工具为何是 MCP-agnostic？
+
+框架不区分工具来源 (本地/MCP/API)。业务层在 `handler` 中封装所有调用逻辑，框架只负责:
+- 注册表管理 (registry)
+- 执行调度 (并行/串行分组)
+- 结果缓存 + 失败重试
+- 向 LLM 提供工具定义
+
+这避免了框架对 MCP 协议的强依赖，同时允许业务层自由选择工具实现方式。
+
+### 6.3 Skill 为何是 interface 而非 abstract class？
+
+Skill 是纯数据定义 (工具包 + 提示词)，不包含运行时逻辑。遵循"接口描述数据，抽象类描述行为"的原则:
+- `interface Skill` — 数据契约，业务层直接构造对象
+- `abstract class SkillModule` — 运行时行为，管理注册/过滤/聚合
+
+这降低了业务层的使用门槛 (无需 `new` 或继承)。
+
+### 6.4 三级 MemoryPressure 替代单一阈值
+
+**旧设计**: `hasOverflow(): boolean` — 单一阈值 (70%)，溢出后一刀切压缩。
+
+**新设计**: `checkPressure(): MemoryPressure` — 4 级渐进式:
+- `None` (< 70%): 零开销
+- `Mild` (70-85%): 1 次 LLM 调用，温和压缩远期
+- `Moderate` (85-95%): 1-2 次 LLM 调用，压缩远期 + 摘要中间
+- `Critical` (> 95%): 0 次 LLM 调用，激进裁剪
+
+**收益**: 避免轻度过量时执行昂贵的 LLM 压缩调用，同时保证极端情况下的可用性。
+
+### 6.5 tiktoken 替代启发式估算
+
+**旧方案**: `estimateTokens()` 使用 CJK 字符 ×1.5 + 英文词 ×1.3 的启发式公式。
+
+**问题**: 误差 15-30%，可能导致过早压缩 (浪费 LLM 调用) 或过晚压缩 (超出上下文窗口)。
+
+**新方案**: `tiktoken` 的 `cl100k_base` 编码器，与 DeepSeek/OpenAI 的 tokenizer 完全一致，误差 < 1%。
+
+### 6.6 ToolRAG 默认关键词匹配
+
+**选择**: 默认使用 `_keywordSearch()` (中英文分词 + 加权匹配)，而非强依赖 Embedding API。
+
+**理由**:
+- 零依赖，即时可用
+- 工具描述通常较短 (10-50 词)，关键词匹配精度足够
+- `IEmbeddingProvider` 接口允许业务层按需升级为语义检索
+- 避免引入 ML 运行时依赖 (如 transformers.js)
+
+---
+
+## 七、持久化模型
+
+### 快照结构
+
+```
+DialogSnapshot
+  ├── version: number              // 格式版本 (当前 1)
+  ├── createdAt: number            // 创建时间戳
+  ├── dialogId: string             // 对话 ID
+  ├── title: string                // 对话标题
+  ├── strategy: string             // 当前推理策略
+  └── agentSnapshot:
+       ├── version: number
+       ├── agentId: string
+       ├── turnCount: number       // 对话轮次
+       ├── messages: LLMMessage[]  // 完整消息历史
+       ├── scratchpad: string      // 推理草稿
+       ├── toolResults: [id, result][]  // 工具结果缓存
+       └── config:                 // Agent 配置 (已剥离 apiKey/address)
+            ├── model
+            ├── systemPrompt
+            ├── temperature
+            ├── maxTokens
+            ├── enableThinking
+            ├── reasoningEffort
+            └── maxTurns
+```
+
+### 导入导出流程
+
+```
+导出: Dialog.snapshot() → Agent.snapshot() → DialogSnapshot
+       ↑ 不包含 apiKey / address (安全剥离)
+
+导入: DialogModule.import(snapshot, config)
+       ├── 合并 config (address/apiKey 从参数取, 其余从快照恢复)
+       ├── new Dialog(title, mergedConfig, strategy)
+       └── agent.restore(agentSnapshot)
+            ├── turnCount = snapshot.turnCount
+            ├── scratchpad = snapshot.scratchpad
+            ├── toolResults = Map(snapshot.toolResults)
+            └── messages = snapshot.messages
+```
+
+### 安全设计
+
+- `apiKey` 和 `address` 不会出现在任何快照中
+- 恢复时必须重新传入完整的 `AgentConfig`（含 `apiKey`/`address`）
+- 快照的 `config` 字段只包含非敏感的模型参数
+
+---
+
+## 八、扩展点
+
+### 自定义推理策略
+
+```typescript
+import { AbstractReason, ReasonConfig, ReasonResult } from "knight-agent";
+
+export class MyCustomReason extends AbstractReason {
+  public readonly type = "MyCustomReason";
+
+  async execute(input: string, config: ReasonConfig): Promise<ReasonResult> {
+    const agent = (config.useAgent as Agent)
+      ?? this.host.agentModule.createAgent(config.baseConfig);
+    const runOptions = this.buildRunOptions(config);
+    try {
+      const result = await agent.run(input, runOptions);
+      return { ...result, strategy: this.type };
+    } finally {
+      if (!config.useAgent) this.host.agentModule.destroyAgent(agent.id);
+    }
+  }
+}
+
+Host.reasonModule.register("MyCustomReason", new MyCustomReason());
+```
+
+### 自定义 Embedding 提供者
+
+```typescript
+Host.toolModule.setEmbeddingProvider({
+  dims: 1536,
+  embed: async (text) => {
+    // 调用任意 Embedding 服务
+    const res = await fetch("https://your-embedding-api.com/embed", {
+      method: "POST",
+      body: JSON.stringify({ text }),
+    });
+    return (await res.json()).vector;
+  },
+});
+```
+
+### 扩展模块
+
+所有模块继承 `AbstractModule`，自动获得:
+- 全局唯一 `id`
+- `this.host` 访问其他模块
+- 注册到全局对象池 `AbstractObject.objects`
+
+```typescript
+import { AbstractModule } from "knight-agent";
+
+export class MyModule extends AbstractModule {
+  // 通过 this.host.toolModule / this.host.agentModule 等访问其他模块
+}
+```
+
+将其挂载到 `Host` 即可集成到框架体系中。