agentdev 0.1.8 → 0.1.10

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { E as EnrichedMessage, M as MessageTag, a as Message, L as LLMResponse, T as ToolCall, b as Tool, c as LogContextRef, A as AgentConfig, I as InlineRenderTemplate, d as ToolRenderConfig, H as HookInspectorSnapshot, e as AgentOverviewSnapshot, f as AgentInfo, N as Notification, U as UserInputRequest, g as UserInputResponse, h as UsageStatsSnapshot, i as TemplateSource, j as TemplateLoader, k as UsageStats, P as PlaceholderContext, l as UsageInfo, m as UserInputAction, n as LLMClient, o as MessageRole, p as AgentSession } from './types-DUKIIntb.js';
-export { C as CacheStats, q as ContextMiddleware, D as DebugHubIPCMessage, r as TemplateComposer, s as TemplateError, t as TemplateLoaderOptions, u as TemplateResult, v as ToolMetadata, w as getDefaultUDSPath } from './types-DUKIIntb.js';
+import { E as EnrichedMessage, M as MessageTag, a as Message, L as LLMResponse, T as ToolCall, b as Tool, A as AgentConfig, I as InlineRenderTemplate, c as LogContextRef, d as ToolRenderConfig, H as HookInspectorSnapshot, e as AgentOverviewSnapshot, f as AgentInfo, N as Notification, U as UserInputRequest, g as UserInputResponse, h as UsageStatsSnapshot, i as TemplateSource, j as TemplateLoader, k as UsageStats, P as PlaceholderContext, l as UsageInfo, m as UserInputAction, n as LLMClient, o as MessageRole, p as AgentSession } from './types-CF5UsxD9.js';
+export { C as CacheStats, q as ContextMiddleware, D as DebugHubIPCMessage, r as TemplateComposer, s as TemplateError, t as TemplateLoaderOptions, u as TemplateResult, v as ToolMetadata, w as getDefaultUDSPath } from './types-CF5UsxD9.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { IncomingMessage, ServerResponse } from 'http';
 
@@ -236,6 +236,203 @@ declare class Context {
     private generateId;
 }
 
+/**
+ * Feature 上下文值类型
+ */
+type ToolContextValue = Record<string, unknown>;
+/**
+ * Feature 上下文注入器
+ * 返回要注入到 tool.execute() 的额外参数
+ */
+type ContextInjector = (call: ToolCall) => ToolContextValue;
+/**
+ * Feature 运行时上下文
+ */
+interface FeatureContext {
+    agentId: string;
+    config: AgentConfig;
+    getFeature<T extends AgentFeature>(name: string): T | undefined;
+}
+/**
+ * Feature 快照状态
+ *
+ * 第一阶段只支持显式白名单状态：
+ * - Feature 自己决定要保存什么
+ * - 未声明的状态一律不保证恢复
+ */
+type FeatureStateSnapshot = unknown;
+/**
+ * 包信息
+ */
+interface PackageInfo {
+    /** 包名，如 '@agentdev/shell-feature' 或 'agentdev' */
+    name: string;
+    /** 版本号（可选） */
+    version?: string;
+    /** 包根目录绝对路径 */
+    root: string;
+}
+/**
+ * Feature 初始化上下文
+ */
+interface FeatureInitContext {
+    /** Agent ID */
+    agentId: string;
+    /** Agent 配置 */
+    config: AgentConfig;
+    /** Feature 级结构化日志 */
+    logger: Logger;
+    /** Feature 特定配置 */
+    featureConfig?: unknown;
+    /** 获取其他 Feature */
+    getFeature<T extends AgentFeature>(name: string): T | undefined;
+    /** 注册工具 */
+    registerTool(tool: Tool): void;
+}
+/**
+ * Feature 初始化上下文
+ */
+interface FeatureInitContext {
+    /** Agent ID */
+    agentId: string;
+    /** Agent 配置 */
+    config: AgentConfig;
+    /** Feature 级结构化日志 */
+    logger: Logger;
+    /** Feature 特定配置 */
+    featureConfig?: unknown;
+    /** 获取其他 Feature */
+    getFeature<T extends AgentFeature>(name: string): T | undefined;
+    /** 注册工具 */
+    registerTool(tool: Tool): void;
+}
+/**
+ * Agent Feature 接口
+ *
+ * 可外挂的功能模块，提供工具和上下文注入
+ */
+interface AgentFeature {
+    /** Feature 名称 */
+    readonly name: string;
+    /** 依赖的其他 Feature */
+    readonly dependencies?: string[];
+    /** 可选：用于调试器展示的源码位置 */
+    readonly source?: string;
+    /** 可选：用于调试器展示的 Feature 描述 */
+    readonly description?: string;
+    /**
+     * 获取同步工具（已知工具列表）
+     */
+    getTools?(): Tool[];
+    /**
+     * 获取异步工具（需要连接、发现等）
+     */
+    getAsyncTools?(ctx: FeatureInitContext): Promise<Tool[]>;
+    /**
+     * 获取包信息
+     *
+     * 返回 Feature 所在的包信息（包名、版本、根目录）
+     * 用于统一模板路径解析和包管理
+     *
+     * @returns 包信息，如果 Feature 不属于任何包则返回 null
+     *
+     * @example
+     * ```typescript
+     * getPackageInfo(): PackageInfo | null {
+     *   return {
+     *     name: '@agentdev/shell-feature',
+     *     version: '1.0.0',
+     *     root: '/path/to/package/root'
+     *   };
+     * }
+     * ```
+     */
+    getPackageInfo?(): PackageInfo | null;
+    /**
+     * 获取模板名称列表
+     *
+     * 返回 Feature 提供的模板名称列表（不含扩展名）
+     * 模板文件必须位于 {packageRoot}/dist/templates/{templateName}.render.js
+     *
+     * @returns 模板名称数组
+     *
+     * @example
+     * ```typescript
+     * getTemplateNames(): string[] {
+     *   return ['bash', 'trash-delete', 'trash-list'];
+     * }
+     * ```
+     */
+    getTemplateNames?(): string[];
+    /**
+     * 声明渲染模板（推荐方式）
+     * 直接返回模板对象，无需文件路径
+     *
+     * @example
+     * ```typescript
+     * getRenderTemplates(): Record<string, InlineRenderTemplate> {
+     *   return {
+     *     'bash': {
+     *       call: (args) => `<div class="bash-command">> ${escapeHtml(args.command)}</div>`,
+     *       result: (data, success) => success
+     *         ? `<pre class="bash-output">${escapeHtml(data)}</pre>`
+     *         : `<div class="tool-error">${escapeHtml(data)}</div>`
+     *     }
+     *   };
+     * }
+     * ```
+     */
+    getRenderTemplates?(): Record<string, InlineRenderTemplate>;
+    /**
+     * 声明上下文注入器
+     */
+    getContextInjectors?(): Map<string | RegExp, ContextInjector>;
+    /**
+     * 初始化钩子
+     */
+    onInitiate?(ctx: FeatureInitContext): Promise<void>;
+    /**
+     * 清理钩子
+     */
+    onDestroy?(ctx: FeatureContext): Promise<void>;
+    /**
+     * 捕获可回滚的 Feature 状态
+     *
+     * 仅返回显式声明、可序列化的状态。
+     * 未返回的字段不会参与 rollback。
+     */
+    captureState?(): FeatureStateSnapshot;
+    /**
+     * 从快照恢复 Feature 状态
+     */
+    restoreState?(snapshot: FeatureStateSnapshot): void | Promise<void>;
+    /**
+     * rollback 前钩子
+     */
+    beforeRollback?(snapshot: FeatureStateSnapshot): void | Promise<void>;
+    /**
+     * rollback 后钩子
+     */
+    afterRollback?(snapshot: FeatureStateSnapshot): void | Promise<void>;
+    /**
+     * 可选：为调试器提供 hook 的人类可读说明
+     */
+    getHookDescription?(lifecycle: string, methodName: string): string | undefined;
+}
+/**
+ * 从 Feature 的 source 属性获取包信息
+ *
+ * 通过向上查找 package.json 文件来确定包信息
+ * 支持三种场景：
+ * 1. 框架内置 Feature：找到 AgentDev 的 package.json
+ * 2. 外部 npm 包：找到包的 package.json
+ * 3. 用户本地 Feature：找到用户项目的 package.json
+ *
+ * @param source Feature 的源文件路径（import.meta.url）
+ * @returns 包信息，如果找不到 package.json 则返回 null
+ */
+declare function getPackageInfoFromSource(source: string | undefined): PackageInfo | null;
+
 /**
  * 生命周期类型定义
  * 定义 Agent 生命周期钩子相关的类型
@@ -347,6 +544,8 @@ interface ToolContext {
     input: string;
     /** 消息上下文（可读写） */
     context: Context;
+    /** 获取其他 Feature */
+    getFeature<T extends AgentFeature>(name: string): T | undefined;
 }
 /**
  * 工具结果 - onToolFinished 钩子的参数
@@ -372,6 +571,8 @@ interface ToolResult {
     input: string;
     /** 消息上下文 */
     context: Context;
+    /** 获取其他 Feature */
+    getFeature<T extends AgentFeature>(name: string): T | undefined;
 }
 /**
  * 钩子返回值类型（扩展版）
@@ -498,225 +699,29 @@ declare function runWithLogScope<T>(scope: LogContextRef, fn: () => T): T;
 declare function createLogger(namespace: string, bindings?: LoggerBindings): Logger;
 
 /**
- * Feature 上下文值类型
- */
-type ToolContextValue = Record<string, unknown>;
-/**
- * Feature 上下文注入器
- * 返回要注入到 tool.execute() 的额外参数
- */
-type ContextInjector = (call: ToolCall) => ToolContextValue;
-/**
- * Feature 运行时上下文
+ * 工具定义
+ * 简单的工具创建函数
  */
-interface FeatureContext {
-    agentId: string;
-    config: AgentConfig;
-}
+
 /**
- * Feature 快照状态
- *
- * 第一阶段只支持显式白名单状态：
- * - Feature 自己决定要保存什么
- * - 未声明的状态一律不保证恢复
+ * 渲染配置扩展类型
+ * 支持字符串（模板名称）或配置对象
  */
-type FeatureStateSnapshot = unknown;
+type ToolRenderInput = ToolRenderConfig | string;
 /**
- * 包信息
+ * 创建一个工具
+ * @param config 工具配置
+ * @param sourceFile 可选：调用此函数的源文件路径（用于自动查找渲染文件）
  */
-interface PackageInfo {
-    /** 包名，如 '@agentdev/shell-feature' 或 'agentdev' */
+declare function createTool(config: {
     name: string;
-    /** 版本号（可选） */
-    version?: string;
-    /** 包根目录绝对路径 */
-    root: string;
-}
+    description: string;
+    parameters?: Record<string, any>;
+    execute: (args: any, context?: any) => Promise<any>;
+    render?: ToolRenderInput;
+}, sourceFile?: string): Tool;
 /**
- * Feature 初始化上下文
- */
-interface FeatureInitContext {
-    /** Agent ID */
-    agentId: string;
-    /** Agent 配置 */
-    config: AgentConfig;
-    /** Feature 级结构化日志 */
-    logger: Logger;
-    /** Feature 特定配置 */
-    featureConfig?: unknown;
-    /** 获取其他 Feature */
-    getFeature<T extends AgentFeature>(name: string): T | undefined;
-    /** 注册工具 */
-    registerTool(tool: Tool): void;
-}
-/**
- * Feature 初始化上下文
- */
-interface FeatureInitContext {
-    /** Agent ID */
-    agentId: string;
-    /** Agent 配置 */
-    config: AgentConfig;
-    /** Feature 级结构化日志 */
-    logger: Logger;
-    /** Feature 特定配置 */
-    featureConfig?: unknown;
-    /** 获取其他 Feature */
-    getFeature<T extends AgentFeature>(name: string): T | undefined;
-    /** 注册工具 */
-    registerTool(tool: Tool): void;
-}
-/**
- * Agent Feature 接口
- *
- * 可外挂的功能模块，提供工具和上下文注入
- */
-interface AgentFeature {
-    /** Feature 名称 */
-    readonly name: string;
-    /** 依赖的其他 Feature */
-    readonly dependencies?: string[];
-    /** 可选：用于调试器展示的源码位置 */
-    readonly source?: string;
-    /** 可选：用于调试器展示的 Feature 描述 */
-    readonly description?: string;
-    /**
-     * 获取同步工具（已知工具列表）
-     */
-    getTools?(): Tool[];
-    /**
-     * 获取异步工具（需要连接、发现等）
-     */
-    getAsyncTools?(ctx: FeatureInitContext): Promise<Tool[]>;
-    /**
-     * 获取包信息
-     *
-     * 返回 Feature 所在的包信息（包名、版本、根目录）
-     * 用于统一模板路径解析和包管理
-     *
-     * @returns 包信息，如果 Feature 不属于任何包则返回 null
-     *
-     * @example
-     * ```typescript
-     * getPackageInfo(): PackageInfo | null {
-     *   return {
-     *     name: '@agentdev/shell-feature',
-     *     version: '1.0.0',
-     *     root: '/path/to/package/root'
-     *   };
-     * }
-     * ```
-     */
-    getPackageInfo?(): PackageInfo | null;
-    /**
-     * 获取模板名称列表
-     *
-     * 返回 Feature 提供的模板名称列表（不含扩展名）
-     * 模板文件必须位于 {packageRoot}/dist/templates/{templateName}.render.js
-     *
-     * @returns 模板名称数组
-     *
-     * @example
-     * ```typescript
-     * getTemplateNames(): string[] {
-     *   return ['bash', 'trash-delete', 'trash-list'];
-     * }
-     * ```
-     */
-    getTemplateNames?(): string[];
-    /**
-     * 声明渲染模板（推荐方式）
-     * 直接返回模板对象，无需文件路径
-     *
-     * @example
-     * ```typescript
-     * getRenderTemplates(): Record<string, InlineRenderTemplate> {
-     *   return {
-     *     'bash': {
-     *       call: (args) => `<div class="bash-command">> ${escapeHtml(args.command)}</div>`,
-     *       result: (data, success) => success
-     *         ? `<pre class="bash-output">${escapeHtml(data)}</pre>`
-     *         : `<div class="tool-error">${escapeHtml(data)}</div>`
-     *     }
-     *   };
-     * }
-     * ```
-     */
-    getRenderTemplates?(): Record<string, InlineRenderTemplate>;
-    /**
-     * 声明上下文注入器
-     */
-    getContextInjectors?(): Map<string | RegExp, ContextInjector>;
-    /**
-     * 初始化钩子
-     */
-    onInitiate?(ctx: FeatureInitContext): Promise<void>;
-    /**
-     * 清理钩子
-     */
-    onDestroy?(ctx: FeatureContext): Promise<void>;
-    /**
-     * 捕获可回滚的 Feature 状态
-     *
-     * 仅返回显式声明、可序列化的状态。
-     * 未返回的字段不会参与 rollback。
-     */
-    captureState?(): FeatureStateSnapshot;
-    /**
-     * 从快照恢复 Feature 状态
-     */
-    restoreState?(snapshot: FeatureStateSnapshot): void | Promise<void>;
-    /**
-     * rollback 前钩子
-     */
-    beforeRollback?(snapshot: FeatureStateSnapshot): void | Promise<void>;
-    /**
-     * rollback 后钩子
-     */
-    afterRollback?(snapshot: FeatureStateSnapshot): void | Promise<void>;
-    /**
-     * 可选：为调试器提供 hook 的人类可读说明
-     */
-    getHookDescription?(lifecycle: string, methodName: string): string | undefined;
-}
-/**
- * 从 Feature 的 source 属性获取包信息
- *
- * 通过向上查找 package.json 文件来确定包信息
- * 支持三种场景：
- * 1. 框架内置 Feature：找到 AgentDev 的 package.json
- * 2. 外部 npm 包：找到包的 package.json
- * 3. 用户本地 Feature：找到用户项目的 package.json
- *
- * @param source Feature 的源文件路径（import.meta.url）
- * @returns 包信息，如果找不到 package.json 则返回 null
- */
-declare function getPackageInfoFromSource(source: string | undefined): PackageInfo | null;
-
-/**
- * 工具定义
- * 简单的工具创建函数
- */
-
-/**
- * 渲染配置扩展类型
- * 支持字符串（模板名称）或配置对象
- */
-type ToolRenderInput = ToolRenderConfig | string;
-/**
- * 创建一个工具
- * @param config 工具配置
- * @param sourceFile 可选：调用此函数的源文件路径（用于自动查找渲染文件）
- */
-declare function createTool(config: {
-    name: string;
-    description: string;
-    parameters?: Record<string, any>;
-    execute: (args: any, context?: any) => Promise<any>;
-    render?: ToolRenderInput;
-}, sourceFile?: string): Tool;
-/**
- * 工具注册表 - 管理多个工具
+ * 工具注册表 - 管理多个工具
  */
 declare class ToolRegistry {
     private tools;
@@ -848,7 +853,7 @@ declare class DebugHub {
      * @param featureTemplates Feature 模板路径映射（可选）
      * @returns 分配的 agentId
      */
-    registerAgent(agent: Agent, name?: string, featureTemplates?: Record<string, string>, hookInspector?: HookInspectorSnapshot, overview?: AgentOverviewSnapshot): string;
+    registerAgent(agent: Agent, name?: string, featureTemplates?: Record<string, string>, hookInspector?: HookInspectorSnapshot, overview?: AgentOverviewSnapshot, projectRoot?: string): string;
     /**
      * 注销 Agent
      * @param agentId Agent ID
@@ -1007,6 +1012,7 @@ declare class AgentBase {
     protected debugEnabled: boolean;
     protected _agentId?: string;
     protected _parentPool?: any;
+    private _agentTypeRegistry;
     private features;
     private contextInjectors;
     private featureToolsReady;
@@ -1052,7 +1058,9 @@ declare class AgentBase {
     /**
      * 启用可视化查看器
      */
-    withViewer(name?: string, port?: number, openBrowser?: boolean): Promise<this>;
+    withViewer(name?: string, port?: number, openBrowser?: boolean, options?: {
+        projectRoot?: string;
+    }): Promise<this>;
     /**
      * 设置上下文
      */
@@ -1125,7 +1133,21 @@ declare class AgentBase {
      */
     protected reportToParent(message: string): Promise<void>;
     /**
-     * 创建 Agent 实例（子类可覆盖）
+     * 注册一个可创建的子代理类型
+     *
+     * 通常在 Agent 子类的构造函数中调用：
+     * this.registerAgentType('MyAgent', () => new MyAgent({ llm: this.llm }));
+     */
+    registerAgentType(name: string, factory: () => AgentBase | Promise<AgentBase>): this;
+    /**
+     * 获取当前已注册的所有子代理类型名
+     */
+    getRegisteredAgentTypes(): string[];
+    /**
+     * 创建 Agent 实例
+     *
+     * 优先从实例注册表查找，未命中则 fallback 到内置类型（向后兼容）。
+     * 子类无需覆盖此方法，通过 registerAgentType() 即可扩展。
      */
     createAgentByType(type: string): Promise<AgentBase>;
     /**
@@ -1157,10 +1179,19 @@ declare class AgentBase {
      * if (agent.isEnabled('mcp')) { ... }
      */
     isEnabled(featureName: string): boolean;
+    /**
+     * 按名称获取已挂载的 Feature 实例
+     */
+    getFeature<T extends AgentFeature>(featureName: string): T | undefined;
     /**
      * 确保 Feature 工具已注册
      */
     private ensureFeatureTools;
+    /**
+     * 收集所有 Feature 自带的 skills
+     * 约定：Feature 目录下存在 skills/ 目录则自动发现
+     */
+    private collectFeatureSkills;
     /**
      * 解析相对路径（处理 ./ 和 ../）
      * @param baseDir 基础目录
@@ -1538,91 +1569,279 @@ declare class MCPFeature implements AgentFeature {
 }
 
 /**
- * Agent Skills 类型定义
- */
-/**
- * Skill 元数据
- */
-interface SkillMetadata {
-    /** Skill 名称 */
-    name: string;
-    /** Skill 描述 */
-    description: string;
-    /** SKILL.md 完整路径 */
-    path: string;
-}
-/**
- * Skills 加载器配置
- */
-interface SkillsOptions {
-    /** skills 目录，默认 cwd/.agentdev/skills */
-    dir?: string;
-}
-
-/**
- * Skill Feature - Skills 发现和 invoke_skill 工具
+ * Audit Feature - 安全审计功能模块
  *
- * 将 Skills 集成从 Agent 核心中解耦，实现可外挂功能
+ * 使用本地大模型（OpenAI 兼容 API）审计 bash 命令安全性
+ * 在工具执行前进行安全检查，拦截危险命令
  *
  * @example
  * ```typescript
- * // 使用默认路径 .agentdev/skills
- * agent.use(new SkillFeature());
- *
- * // 使用自定义路径
- * agent.use(new SkillFeature('./custom/skills'));
- * agent.use(new SkillFeature({ dir: './custom/skills' }));
+ * import { AuditFeature } from './features/index.js';
+ * const agent = new Agent({ ... }).use(new AuditFeature());
  * ```
  */
 
 /**
- * Skill Feature 配置类型
+ * AuditFeature 配置
  */
-interface SkillFeatureConfig extends SkillsOptions {
-    /** Skills 目录路径 */
-    dir?: string;
+interface AuditFeatureConfig {
+    /** LLM 服务地址（默认 localhost:7575） */
+    baseUrl?: string;
+    /** 审计模型名称（默认 Qwen3.5-4B-Q5_K_M） */
+    model?: string;
+    /** 是否启用审计（默认 true） */
+    enabled?: boolean;
+    /** 是否启用数据库缓存（默认 true） */
+    enableCache?: boolean;
+    /** 数据库文件路径（默认 .agentdev/audit/audit.db） */
+    dbPath?: string;
+    /** 缓存有效期（天数，0 表示永久，默认 0） */
+    cacheTtlDays?: number;
+    /** 工作目录（默认 process.cwd()） */
+    workspaceDir?: string;
 }
 /**
- * Skill Feature 输入类型
- */
-type SkillFeatureInput = SkillFeatureConfig | string | undefined;
-/**
- * Skill Feature 实现
+ * AuditFeature 实现
+ *
+ * 在工具执行前进行安全审计，拦截危险的 bash 命令
  */
-declare class SkillFeature implements AgentFeature {
-    readonly name = "skill";
+declare class AuditFeature implements AgentFeature {
+    readonly name = "audit";
     readonly dependencies: string[];
     readonly source: string;
-    readonly description = "\u53D1\u73B0\u672C\u5730 skills\uFF0C\u5E76\u63D0\u4F9B invoke_skill \u5DE5\u5177\u4E0E\u6280\u80FD\u6570\u636E\u6E90\u3002";
-    private skillsDir?;
-    private skills;
+    readonly description = "\u5728\u5DE5\u5177\u6267\u884C\u524D\u5BA1\u8BA1\u9AD8\u98CE\u9669 shell \u547D\u4EE4\uFF0C\u5FC5\u8981\u65F6\u963B\u65AD\u6267\u884C\u3002";
+    private config;
+    private client;
+    private db?;
+    private dbPath;
+    private logger;
+    constructor(config?: AuditFeatureConfig);
+    getTools(): Tool[];
+    onInitiate(ctx: FeatureInitContext): Promise<void>;
+    onDestroy(_ctx: FeatureContext): Promise<void>;
+    getHookDescription(lifecycle: string, methodName: string): string | undefined;
     /**
-     * 缓存包信息
+     * 工具使用前审计
+     *
+     * 触发时机：每次工具执行前
+     * 处理逻辑：
+     * 1. 检查是否是 bash 工具调用
+     * 2. 调用 LLM 审计命令安全性
+     * 3. 恶意则拒绝执行，安全则允许
      */
-    private _packageInfo;
+    auditBashCommand(ctx: ToolContext): Promise<DecisionResult>;
     /**
-     * 获取包信息（统一打包方案）
+     * 调用 LLM（OpenAI 兼容 API）审计命令
      */
-    getPackageInfo(): PackageInfo | null;
+    private auditCommand;
     /**
-     * 获取模板名称列表（统一打包方案）
+     * 格式化审计结果消息
      */
-    getTemplateNames(): string[];
-    constructor(input?: SkillFeatureInput);
+    private formatAuditMessage;
     /**
-     * 获取同步工具（invoke_skill）
+     * 初始化数据库
+     *
+     * - 创建数据库目录（如果不存在）
+     * - 打开数据库连接
+     * - 创建表结构（如果不存在）
+     * - 创建索引（如果不存在）
      */
-    getTools(): Tool[];
+    private initDatabase;
     /**
-     * 声明上下文注入器
-     * 为 invoke_skill 工具注入 _context.skills
+     * 查询缓存的审计结果
+     *
+     * @param command - 要审计的命令
+     * @returns 缓存的审计结果，如果不存在则返回 null
      */
-    getContextInjectors(): Map<string | RegExp, ContextInjector>;
+    private getCachedAuditResult;
     /**
-     * 初始化钩子
-     * 执行 Skills 发现并注册数据源
+     * 保存审计结果到数据库
+     *
+     * @param command - 被审计的命令
+     * @param result - 审计结果
+     */
+    private saveAuditResult;
+    /**
+     * 清理过期的缓存记录
+     *
+     * 根据 cacheTtlDays 配置，删除超过有效期的记录
+     */
+    private cleanExpiredCache;
+}
+
+interface AudioFeedbackConfig {
+    /** 音频文件路径（相对于 feature 目录或绝对路径） */
+    audioPath?: string;
+    /** 是否启用音频反馈（默认：true） */
+    enabled?: boolean;
+    /** 音量（0-1，默认：0.5） */
+    volume?: number;
+}
+
+/**
+ * Audio Feedback Feature
+ *
+ * 在每次 call 完成时播放音频反馈，提供愉悦的交互体验
+ */
+declare class AudioFeedbackFeature implements AgentFeature {
+    readonly name = "audio-feedback";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u5728 call \u5B8C\u6210\u65F6\u64AD\u653E\u97F3\u9891\u53CD\u9988\uFF0C\u63D0\u4F9B\u6109\u60A6\u7684\u4EA4\u4E92\u4F53\u9A8C\u3002";
+    private readonly config;
+    private readonly runtime;
+    private logger?;
+    constructor(config?: AudioFeedbackConfig);
+    /**
+     * 公开 API：启用或禁用音频反馈
+     */
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    /**
+     * 公开 API：设置音量
+     */
+    setVolume(volume: number): void;
+    getPlayCount(): number;
+    onInitiate(ctx: FeatureInitContext): Promise<void>;
+    onDestroy(_ctx: FeatureContext): Promise<void>;
+    captureState(): FeatureStateSnapshot;
+    restoreState(snapshot: FeatureStateSnapshot): void;
+    /**
+     * 核心功能：在 call 完成时播放音频
+     */
+    playAudioOnCallFinish(ctx: CallFinishContext): Promise<void>;
+}
+
+interface MemoryFeatureConfig {
+    /** CLAUDE.md 文件名，默认 'CLAUDE.md' */
+    filename?: string;
+    /** 是否强制注入，即使文件不存在也记录日志 */
+    forceInject?: boolean;
+    /** 读取 CLAUDE.md 的工作目录 */
+    workspaceDir?: string;
+    /** 宿主资源目录；如果提供，优先从这里读取 CLAUDE.md */
+    resourceRoot?: string;
+}
+declare class MemoryFeature implements AgentFeature {
+    readonly name = "memory";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u81EA\u52A8\u8BFB\u53D6\u5E76\u6CE8\u5165\u9879\u76EE CLAUDE.md \u6587\u4EF6\u4F5C\u4E3A\u7CFB\u7EDF\u63D0\u793A\u8BCD\u3002";
+    private filename;
+    private sourceRoot;
+    private _packageInfo;
+    constructor(config?: MemoryFeatureConfig);
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     * 此 Feature 没有模板，返回空数组
+     */
+    getTemplateNames(): string[];
+    /**
+     * CallStart 钩子：仅在首次对话开始时注入 CLAUDE.md 内容
+     */
+    injectCLAUDEContent(ctx: CallStartContext): Promise<void>;
+    /**
+     * 获取钩子描述（用于调试器）
+     */
+    getHookDescription(lifecycle: string, methodName: string): string | undefined;
+}
+
+/**
+ * Agent Skills 类型定义
+ */
+/**
+ * Skill 元数据
+ */
+interface SkillMetadata {
+    /** Skill 名称 */
+    name: string;
+    /** Skill 描述 */
+    description: string;
+    /** SKILL.md 完整路径 */
+    path: string;
+}
+/**
+ * Skills 加载器配置
+ */
+interface SkillsOptions {
+    /** skills 目录，默认 cwd/.agentdev/skills */
+    dir?: string;
+}
+
+/**
+ * Skill Feature - Skills 发现和 invoke_skill 工具
+ *
+ * 将 Skills 集成从 Agent 核心中解耦，实现可外挂功能
+ *
+ * @example
+ * ```typescript
+ * // 使用默认路径 .agentdev/skills
+ * agent.use(new SkillFeature());
+ *
+ * // 使用自定义路径
+ * agent.use(new SkillFeature('./custom/skills'));
+ * agent.use(new SkillFeature({ dir: './custom/skills' }));
+ * ```
+ */
+
+/**
+ * Skill Feature 配置类型
+ */
+interface SkillFeatureConfig extends SkillsOptions {
+    /** Skills 目录路径 */
+    dir?: string;
+}
+/**
+ * Skill Feature 输入类型
+ */
+type SkillFeatureInput = SkillFeatureConfig | string | undefined;
+/**
+ * Skill Feature 实现
+ */
+declare class SkillFeature implements AgentFeature {
+    readonly name = "skill";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u53D1\u73B0\u672C\u5730 skills\uFF0C\u5E76\u63D0\u4F9B invoke_skill \u5DE5\u5177\u4E0E\u6280\u80FD\u6570\u636E\u6E90\u3002";
+    private skillsDir?;
+    private skills;
+    private featureSkills;
+    /**
+     * 缓存包信息
+     */
+    private _packageInfo;
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     */
+    getTemplateNames(): string[];
+    constructor(input?: SkillFeatureInput);
+    /**
+     * 获取同步工具（invoke_skill）
+     */
+    getTools(): Tool[];
+    /**
+     * 声明上下文注入器
+     * 为 invoke_skill 工具注入 _context.skills
+     */
+    getContextInjectors(): Map<string | RegExp, ContextInjector>;
+    /**
+     * 初始化钩子
+     * 执行 Skills 发现并注册数据源
      */
     onInitiate(ctx: FeatureInitContext): Promise<void>;
+    /**
+     * 注入来自其他 Feature 的 skills
+     * 由 Agent 在 onInitiate 之前调用
+     */
+    addFeatureSkills(skills: SkillMetadata[]): void;
     /**
      * 获取已加载的 Skills
      */
@@ -1633,6 +1852,188 @@ declare class SkillFeature implements AgentFeature {
     setSkillsDir(dir: string): void;
 }
 
+/**
+ * OpenClaw 兼容层类型定义
+ */
+
+/**
+ * 支持的兼容钩子名称
+ */
+type CompatHookName = 'before_tool_call' | 'after_tool_call';
+/**
+ * before_tool_call 钩子上下文
+ */
+interface BeforeToolCallContext {
+    /** 工具调用 */
+    call: ToolCall;
+    /** 工具名称 */
+    toolName: string;
+    /** 工具参数 */
+    parameters: Record<string, unknown>;
+    /** 消息历史 */
+    messages: Message[];
+}
+/**
+ * before_tool_call 钩子结果
+ */
+interface BeforeToolCallResult {
+    /** 是否阻止执行 */
+    block?: boolean;
+    /** 拒绝原因 */
+    denyReason?: string;
+    /** 修改后的参数 */
+    rewrittenParameters?: Record<string, unknown>;
+}
+/**
+ * after_tool_call 钩子上下文
+ */
+interface AfterToolCallContext {
+    /** 工具调用 */
+    call: ToolCall;
+    /** 工具名称 */
+    toolName: string;
+    /** 执行是否成功 */
+    success: boolean;
+    /** 执行结果 */
+    result: unknown;
+    /** 错误信息 */
+    error?: string;
+    /** 执行耗时(ms) */
+    duration: number;
+    /** 消息历史 */
+    messages: Message[];
+}
+/**
+ * 兼容钩子处理器映射
+ */
+interface CompatHookHandlerMap {
+    before_tool_call: (ctx: BeforeToolCallContext) => BeforeToolCallResult | Promise<BeforeToolCallResult>;
+    after_tool_call: (ctx: AfterToolCallContext) => void | Promise<void>;
+}
+/**
+ * 已注册的兼容钩子
+ */
+interface RegisteredCompatHook {
+    /** 插件 ID */
+    pluginId: string;
+    /** 钩子名称 */
+    hookName: CompatHookName;
+    /** 处理器 */
+    handler: CompatHookHandlerMap[CompatHookName];
+    /** 优先级（OpenClaw 规则：数值越大越先执行） */
+    priority: number;
+}
+/**
+ * 插件诊断信息
+ */
+interface PluginDiagnostics {
+    /** 插件 ID */
+    pluginId: string;
+    /** 插件名称 */
+    name: string;
+    /** 版本 */
+    version: string;
+    /** 源路径 */
+    source: string;
+    /** 注册的工具 */
+    registeredTools: string[];
+    /** 注册的钩子 */
+    registeredHooks: CompatHookName[];
+    /** 不支持的 API 调用记录 */
+    unsupportedApis: string[];
+    /** 错误信息 */
+    errors: string[];
+}
+/**
+ * 兼容层诊断报告
+ */
+interface CompatDiagnosticsReport {
+    /** 加载的插件列表 */
+    plugins: PluginDiagnostics[];
+    /** 总计注册的工具数 */
+    totalTools: number;
+    /** 总计注册的钩子数 */
+    totalHooks: number;
+}
+
+/**
+ * OpenClaw 兼容钩子注册表
+ *
+ * 管理兼容插件的钩子注册和执行
+ * 遵循 OpenClaw 优先级规则：priority 数值越大越先执行
+ */
+
+/**
+ * 兼容钩子注册表
+ */
+declare class CompatHookRegistry {
+    /** 钩子存储：hookName -> 按优先级排序的钩子列表 */
+    private hooks;
+    /**
+     * 注册钩子
+     *
+     * @param hookName 钩子名称
+     * @param handler 钩子处理器
+     * @param priority 优先级（数值越大越先执行）
+     * @param pluginId 插件 ID
+     */
+    register<K extends CompatHookName>(hookName: K, handler: CompatHookHandlerMap[K], priority: number, pluginId: string): void;
+    /**
+     * 获取指定钩子的所有处理器（按优先级排序）
+     *
+     * @param hookName 钩子名称
+     * @returns 钩子列表
+     */
+    get(hookName: CompatHookName): RegisteredCompatHook[];
+    /**
+     * 检查是否有指定钩子
+     *
+     * @param hookName 钩子名称
+     * @returns 是否存在
+     */
+    has(hookName: CompatHookName): boolean;
+    /**
+     * 执行 before_tool_call 钩子
+     *
+     * 按优先级顺序执行：
+     * - 如果任何钩子返回 block=true，则立即阻止执行
+     * - 多个插件的参数修改会累积合并
+     *
+     * @param context 钩子上下文
+     * @returns 钩子执行结果（如果任何钩子返回 block=true，则阻止执行）
+     */
+    executeBeforeToolCall(context: BeforeToolCallContext): Promise<BeforeToolCallResult>;
+    /**
+     * 深度合并对象
+     */
+    private deepMerge;
+    /**
+     * 执行 after_tool_call 钩子
+     *
+     * 按优先级顺序执行所有钩子（void 返回值）
+     *
+     * @param context 钩子上下文
+     */
+    executeAfterToolCall(context: AfterToolCallContext): Promise<void>;
+    /**
+     * 获取所有已注册的钩子信息
+     *
+     * @returns 钩子信息映射
+     */
+    getHooksInfo(): Map<CompatHookName, Array<{
+        pluginId: string;
+        priority: number;
+    }>>;
+    /**
+     * 清空所有钩子
+     */
+    clear(): void;
+    /**
+     * 获取钩子总数
+     */
+    get size(): number;
+}
+
 /**
  * 反向钩子装饰器
  *
@@ -1689,45 +2090,308 @@ declare const ToolUse: (target: any, propertyKey: string, descriptor: PropertyDe
 declare const ToolFinished: (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 
 /**
- * AgentPool - 子代理管理核心
- * 管理父代理创建的所有子代理实例
- */
-
-/**
- * 子代理实例信息
- */
-interface SubAgentInstance {
-    id: string;
-    type: string;
-    agent: AgentBase;
-    status: SubAgentStatus;
-    initialInstruction: string;
-    createdAt: number;
-    completedAt?: number;
-    result?: string;
-    error?: string;
-}
-/**
- * Agent 创建函数类型（异步）
- */
-type AgentFactory = (type: string) => AgentBase | Promise<AgentBase>;
-/**
- * AgentPool - 子代理管理核心
- * 管理父代理创建的所有子代理实例
+ * PluginCompatFeature
+ *
+ * 加载 OpenClaw 风格插件并将它们转换为 AgentDev 能力
  */
-declare class AgentPool {
-    private _instances;
-    private _counters;
-    private _parent;
-    /** 待回传消息队列：agentId -> messages[] */
-    private _pendingMessages;
-    /** 消息就绪解析器：key -> resolver function */
-    private _messageResolvers;
-    constructor(parent: AgentBase);
+declare class PluginCompatFeature implements AgentFeature {
+    name: string;
+    readonly source: string;
+    readonly description = "\u52A0\u8F7D OpenClaw \u98CE\u683C\u63D2\u4EF6\uFF0C\u5E76\u628A\u63D2\u4EF6\u5DE5\u5177\u4E0E\u517C\u5BB9\u94A9\u5B50\u6865\u63A5\u5230 AgentDev\u3002";
+    /** 兼容钩子注册表 */
+    private compatHookRegistry;
+    /** 诊断收集器 */
+    private diagnostics;
+    /** 已加载的插件 */
+    private loadedPlugins;
+    /** Agent 工具注册表（从 FeatureContext 获取） */
+    private agentToolRegistry?;
+    /** Agent ID */
+    private agentId?;
+    /** 插件根目录 */
+    private pluginRoots;
+    /** 是否启用 */
+    private enabled;
+    /** 注册的工具列表（用于 getAsyncTools） */
+    private registeredTools;
     /**
-     * 创建子代理（不自动执行，等待 sendTo 激活）
+     * 初始化 Feature
      */
-    spawn(type: string, createAgentFn: AgentFactory): Promise<string>;
+    onInitiate(ctx: FeatureInitContext): Promise<void>;
+    /**
+     * 加载所有插件
+     */
+    private loadPlugins;
+    /**
+     * 加载单个插件
+     */
+    private loadPlugin;
+    /**
+     * 注册工具
+     */
+    private registerTool;
+    /**
+     * 获取异步工具列表
+     */
+    getAsyncTools(): Promise<Tool[]>;
+    /**
+     * 注册钩子
+     */
+    private registerHook;
+    /**
+     * 调用工具（用于插件运行时）
+     */
+    private invokeTool;
+    /**
+     * 获取兼容钩子注册表（供内部桥接使用）
+     */
+    getCompatHookRegistry(): CompatHookRegistry;
+    /**
+     * 获取诊断报告
+     */
+    getDiagnostics(): CompatDiagnosticsReport;
+    /**
+     * 清理资源
+     */
+    onDestroy(): Promise<void>;
+    getHookDescription(lifecycle: string, methodName: string): string | undefined;
+    /**
+     * 桥接 before_tool_call 钩子
+     *
+     * 在工具执行前调用兼容插件的 before_tool_call 钩子
+     */
+    handleBeforeToolCall(ctx: ToolContext): Promise<typeof Decision.Deny | typeof Decision.Continue>;
+    /**
+     * 桥接 after_tool_call 钩子
+     *
+     * 在工具执行后调用兼容插件的 after_tool_call 钩子
+     */
+    handleAfterToolCall(result: ToolResult): Promise<void>;
+}
+
+/**
+ * QQBotFeature - QQ 机器人对话能力
+ *
+ * 功能：
+ * - 通过 WebSocket 连接 QQ Bot Gateway
+ * - 接收 QQ 消息并转发给 Agent 处理
+ * - 自动将 Agent 的响应发送回 QQ
+ *
+ * 使用 `@sliverp/qqbot/standalone` 独立接入
+ */
+
+/**
+ * QQ 消息发送选项
+ */
+interface QQBotSendOptions {
+    /** 目标 OpenID */
+    to: string;
+    /** 消息内容 */
+    content: string;
+}
+/**
+ * QQ 消息发送结果
+ */
+interface QQBotSendResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 消息ID */
+    messageId?: string;
+    /** 时间戳 */
+    timestamp?: string | number;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 已知用户信息
+ */
+interface KnownUser {
+    /** 类型 */
+    type: 'c2c' | 'group' | 'channel';
+    /** OpenID */
+    openid: string;
+    /** 昵称 */
+    nickname?: string;
+    /** 最后交互时间 */
+    lastInteractionAt: number;
+}
+/**
+ * QQBot Feature 配置
+ */
+interface QQBotFeatureConfig {
+    /** QQ Bot AppID（可选，如果不提供则从配置文件读取） */
+    appId?: string;
+    /** QQ Bot AppSecret（可选，如果不提供则从配置文件读取） */
+    clientSecret?: string;
+    /** 配置文件路径（默认 .agentdev/qqbot.config.json） */
+    configPath?: string;
+    /** 账户 ID（默认 "default"） */
+    accountId?: string;
+    /** 是否启用 Markdown 消息（默认 true） */
+    markdownSupport?: boolean;
+    /** 系统提示词 */
+    systemPrompt?: string;
+    /** 附加配置（传递给 Gateway） */
+    cfg?: Record<string, unknown>;
+    /** 工作目录（默认 process.cwd()） */
+    workspaceDir?: string;
+    /** 宿主资源目录；默认从这里查找 .agentdev/qqbot.config.json */
+    resourceRoot?: string;
+}
+/**
+ * QQBotFeature - QQ 机器人 Feature
+ *
+ * 使用方式：
+ * ```typescript
+ * const qqbotFeature = new QQBotFeature({ appId, clientSecret });
+ * const agent = new BasicAgent({ llm }).use(qqbotFeature);
+ * await agent.withViewer('QQBot', 2026, false);
+ * await qqbotFeature.startGateway(agent);
+ * ```
+ */
+declare class QQBotFeature implements AgentFeature {
+    readonly name = "qqbot";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u628A Agent \u63A5\u5165 QQ Bot \u7F51\u5173\uFF0C\u63A5\u6536\u6D88\u606F\u5E76\u628A\u56DE\u590D\u56DE\u63A8\u5230 QQ \u4F1A\u8BDD\u3002";
+    private config;
+    private agentRef;
+    private processingLock;
+    private gatewayStarted;
+    private abortController;
+    private _packageInfo;
+    constructor(config?: QQBotFeatureConfig);
+    /**
+     * 显式启动 Gateway（在 Agent 初始化后调用）
+     *
+     * @param agent Agent 实例
+     */
+    startGateway(agent: any): Promise<void>;
+    /**
+     * 创建账户配置
+     */
+    private createAccount;
+    /**
+     * 获取凭据（从配置文件或直接配置）
+     */
+    private getCredentials;
+    getTools(): Tool[];
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     * 此 Feature 没有模板，返回空数组
+     */
+    getTemplateNames(): string[];
+    onInitiate(_ctx: FeatureInitContext): Promise<void>;
+    onDestroy(_ctx: FeatureContext): Promise<void>;
+}
+
+/**
+ * Shell Feature 工具定义
+ *
+ * 提供 run_shell_command 工具，通过 Git Bash 执行 Shell 命令
+ */
+
+interface ShellExecutionResult {
+    stdout: string;
+    stderr: string;
+    output: string;
+}
+
+/**
+ * Shell Feature - Git Bash 命令执行工具 + 安全删除/恢复工具
+ *
+ * 通过 Git Bash 执行 Shell 命令，description 从内部配置加载
+ * 提供安全删除、列表和恢复功能
+ *
+ * @example
+ * ```typescript
+ * import { ShellFeature } from './features/index.js';
+ * const agent = new Agent({ ... }).use(new ShellFeature());
+ * ```
+ */
+
+interface ShellFeatureConfig {
+    workspaceDir?: string;
+    workdir?: string;
+    resourceRoot?: string;
+}
+/**
+ * Shell Feature 实现
+ */
+declare class ShellFeature implements AgentFeature {
+    readonly name = "shell";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u63D0\u4F9B bash \u6267\u884C\u80FD\u529B\uFF0C\u4EE5\u53CA\u5B89\u5168\u5220\u9664\u3001\u6062\u590D\u548C\u67E5\u770B\u5783\u573E\u6876\u5DE5\u5177\u3002";
+    private bashDescription?;
+    private _packageInfo;
+    private readonly workspaceDir;
+    private readonly workdir;
+    private readonly resourceRoot;
+    constructor(config?: ShellFeatureConfig);
+    run(command: string): Promise<ShellExecutionResult>;
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     */
+    getTemplateNames(): string[];
+    /**
+     * 获取同步工具（垃圾桶工具）
+     */
+    getTools(): Tool[];
+    /**
+     * 获取异步工具（bash 工具，加载 description）
+     */
+    getAsyncTools(_ctx: FeatureInitContext): Promise<Tool[]>;
+}
+
+/**
+ * AgentPool - 子代理管理核心
+ * 管理父代理创建的所有子代理实例
+ */
+
+/**
+ * 子代理实例信息
+ */
+interface SubAgentInstance {
+    id: string;
+    type: string;
+    agent: AgentBase;
+    status: SubAgentStatus;
+    initialInstruction: string;
+    createdAt: number;
+    completedAt?: number;
+    result?: string;
+    error?: string;
+}
+/**
+ * Agent 创建函数类型（异步）
+ */
+type AgentFactory = (type: string) => AgentBase | Promise<AgentBase>;
+/**
+ * AgentPool - 子代理管理核心
+ * 管理父代理创建的所有子代理实例
+ */
+declare class AgentPool {
+    private _instances;
+    private _counters;
+    private _parent;
+    /** 待回传消息队列：agentId -> messages[] */
+    private _pendingMessages;
+    /** 消息就绪解析器：key -> resolver function */
+    private _messageResolvers;
+    constructor(parent: AgentBase);
+    /**
+     * 创建子代理（不自动执行，等待 sendTo 激活）
+     */
+    spawn(type: string, createAgentFn: AgentFactory): Promise<string>;
     /**
      * 获取实例信息
      */
@@ -2048,58 +2712,796 @@ declare class TodoFeature implements AgentFeature {
 }
 
 /**
- * UserInputFeature - 通过调试界面获取用户输入
+ * TTS Feature 类型定义
+ */
+/**
+ * TTS Feature 配置选项
+ */
+interface TTSFeatureConfig {
+    /** 工作目录（默认 process.cwd()） */
+    workspaceDir?: string;
+    /**
+     * Python 可执行文件路径
+     * 默认：项目 .venv 中的 Python 或系统 PATH 中的 python
+     */
+    pythonPath?: string;
+    /**
+     * Python 额外参数（如 uv run）
+     * 例如：['run', '--with', 'kokoro', '--with', 'soundfile']
+     */
+    pythonArgs?: string[];
+    /**
+     * 是否在初始化时检查 Python 环境
+     * 默认：true
+     */
+    checkPythonEnv?: boolean;
+    /**
+     * TTS 模型配置
+     */
+    model?: {
+        /**
+         * 默认声音 ID
+         * 中文常用：zf_xiaobei, zf_xiaoxiao, zf_xiaomei
+         * 英文常用：af_bella, af_heart
+         * 默认：zf_xiaobei
+         */
+        voice?: string;
+        /**
+         * 语言代码
+         * 'zh'（中文优先） 或 'a'/'en'（英文优先）
+         * 默认：zh
+         */
+        lang?: string;
+        /**
+         * 语速倍率
+         * 0.8~1.5 之间合理
+         * 默认：1.0
+         */
+        speed?: number;
+    };
+    /**
+     * 音频输出配置
+     */
+    output?: {
+        /**
+         * 输出目录
+         * 默认：.agentdev/tts
+         */
+        outputDir?: string;
+        /**
+         * 是否自动播放生成的音频
+         * 默认：true
+         */
+        autoPlay?: boolean;
+    };
+    /**
+     * TTS 触发条件
+     */
+    triggers?: {
+        /**
+         * 是否启用自动朗读（非工具调用轮）
+         * 默认：true
+         */
+        autoEnabled?: boolean;
+        /**
+         * 最小文本长度（字符数）
+         * 短于此长度的文本不会朗读
+         * 默认：10
+         */
+        minLength?: number;
+        /**
+         * 最大文本长度（字符数）
+         * 长于此长度的文本会被截断
+         * 默认：1000
+         */
+        maxLength?: number;
+        /**
+         * 是否只在非结束轮触发
+         * true: 只在没有工具调用时朗读
+         * false: 所有响应都朗读
+         * 默认：true
+         */
+        onlyOnNonToolCalls?: boolean;
+    };
+}
+/**
+ * TTS 生成结果
+ */
+interface TTSResult {
+    success: boolean;
+    outputPath?: string;
+    duration?: number;
+    error?: string;
+}
+/**
+ * TTS 内部状态（用于快照和恢复）
+ */
+interface TTSState {
+    enabled: boolean;
+    lastUtteranceId: string | null;
+    totalUtterances: number;
+}
+
+/**
+ * TTSFeature - 文本朗读功能模块
+ *
+ * 提供：
+ * 1. @StepFinish 钩子：在每个 step 结束时自动朗读模型输出
+ *    - 包括工具调用轮和非工具调用轮
+ *    - 只要有 assistant 文本回复就会朗读
+ *    - 默认自动播放音频（使用 pygame）
+ *
+ * Python 环境要求：
+ * - 需要安装 kokoro、soundfile、pygame 库
+ *
+ * 安装方式：
+ *   uv 方式（推荐）：
+ *   uv pip install kokoro soundfile pygame
+ *
+ *   或使用 pip：
+ *   pip install kokoro soundfile pygame
+ *
+ * Python 调用方式：
+ * - 默认使用 'python' 命令（从 PATH 中查找）
+ * - 如果使用 uv，可以配置为 'uv run'
+ *
+ * @example
+ * ```typescript
+ * import { TTSFeature } from './features/index.js';
+ *
+ * // 使用默认配置
+ * const agent = new Agent({ ... }).use(new TTSFeature());
+ *
+ * // 自定义声音和语速
+ * const agent = new Agent({ ... }).use(new TTSFeature({
+ *   model: {
+ *     voice: 'zf_xiaoxiao',
+ *     speed: 1.3
+ *   }
+ * }));
+ *
+ * // 禁用自动播放
+ * const agent = new Agent({ ... }).use(new TTSFeature({
+ *   output: {
+ *     autoPlay: false
+ *   }
+ * }));
+ *
+ * // 使用 uv
+ * const agent = new Agent({ ... }).use(new TTSFeature({
+ *   pythonPath: 'uv',
+ *   pythonArgs: ['run']
+ * }));
+ * ```
+ */
+
+declare class TTSFeature implements AgentFeature {
+    readonly name = "tts";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u63D0\u4F9B\u6587\u672C\u6717\u8BFB\u80FD\u529B\uFF0C\u652F\u6301\u5728\u975E\u5DE5\u5177\u8C03\u7528\u8F6E\u81EA\u52A8\u6717\u8BFB\u6A21\u578B\u8F93\u51FA\u3002";
+    private config;
+    private state;
+    private _packageInfo;
+    constructor(config?: TTSFeatureConfig);
+    getTools(): never[];
+    getAsyncTools(_ctx: FeatureInitContext): Promise<never[]>;
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     * 此 Feature 没有模板，返回空数组
+     */
+    getTemplateNames(): string[];
+    onInitiate(_ctx: FeatureInitContext): Promise<void>;
+    onDestroy(_ctx: FeatureContext): Promise<void>;
+    captureState(): FeatureStateSnapshot;
+    restoreState(snapshot: FeatureStateSnapshot): void;
+    getHookDescription(lifecycle: string, methodName: string): string | undefined;
+    /**
+     * 检测 Python 环境和依赖库
+     */
+    private checkPythonEnvironment;
+    /**
+     * 调用 Python 脚本生成 TTS 音频
+     */
+    private generateTTS;
+    /**
+     * 提取模型输出的正文部分
+     * 过滤掉系统消息、工具调用等，只保留实际的回复内容
+     */
+    private extractMainResponse;
+    /**
+     * 在每个 step 结束时自动朗读模型输出
+     * 包括工具调用轮和非工具调用轮
+     */
+    speakOnStepFinish(ctx: StepFinishedContext): Promise<void>;
+}
+
+/**
+ * UserInputFeature - 通过调试界面获取用户输入
+ *
+ * 功能：
+ * - 提供 get_user_input 工具，允许 LLM 请求用户输入
+ * - 通过 DebugHub 的 UDS 通道与 ViewerWorker 通信
+ * - 前端显示输入框，用户提交后返回给 Agent
+ */
+
+interface UserInputFeatureConfig {
+    /** 默认超时时间（毫秒），默认无限等待 */
+    timeout?: number;
+}
+declare class UserInputFeature implements AgentFeature {
+    readonly name = "user-input";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u5141\u8BB8 Agent \u901A\u8FC7\u8C03\u8BD5\u754C\u9762\u5411\u7528\u6237\u53D1\u8D77\u8F93\u5165\u8BF7\u6C42\u5E76\u7B49\u5F85\u56DE\u590D\u3002";
+    private defaultTimeout;
+    private nextDraftInput;
+    /**
+     * 缓存包信息
+     */
+    private _packageInfo;
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     * 注意：UserInputFeature 没有渲染模板
+     */
+    getTemplateNames(): string[];
+    constructor(config?: UserInputFeatureConfig);
+    setNextDraftInput(input: string): void;
+    /**
+     * 请求用户输入（核心方法）
+     */
+    requestUserInput(prompt: string, timeout?: number): Promise<string>;
+    requestUserInputEvent(request: UserInputRequest, timeout?: number): Promise<UserInputResponse>;
+    /**
+     * 获取用户输入（公开接口，供主循环直接调用）
+     * @param prompt 提示信息
+     * @param timeout 超时时间（毫秒）
+     * @returns 用户输入内容
+     */
+    getUserInput(prompt?: string, timeout?: number): Promise<string>;
+    getUserInputEvent(prompt?: string, timeout?: number, actions?: UserInputAction[]): Promise<UserInputResponse>;
+    getTools(): Tool[];
+    onInitiate(_ctx: FeatureInitContext): Promise<void>;
+    onDestroy(_ctx: FeatureContext): Promise<void>;
+}
+
+/**
+ * VisualFeature 类型定义
+ */
+/**
+ * 窗口信息（从 Python enum.py 返回）
+ */
+interface WindowInfo {
+    /** 窗口句柄（16进制格式，如 "0x12345"） */
+    hwnd: string;
+    /** 窗口标题 */
+    title: string;
+    /** 窗口类名 */
+    class_name: string;
+    /** 窗口状态 */
+    status: 'Normal' | 'Minimized' | 'Maximized' | 'Unknown';
+    /** 窗口位置和尺寸 */
+    position: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** 进程名称 */
+    process_name: string;
+    /** 进程路径 */
+    process_path: string;
+    /** 进程 ID */
+    pid: number | string;
+    /** 是否置顶 */
+    is_always_on_top: boolean;
+}
+/**
+ * 截图结果（从 Python capture.py 返回）
+ */
+interface CaptureResult {
+    /** 是否成功 */
+    success?: boolean;
+    /** 窗口句柄 */
+    hwnd?: string;
+    /** 图片宽度 */
+    width?: number;
+    /** 图片高度 */
+    height?: number;
+    /** 图片格式 */
+    format?: string;
+    /** base64 编码的图片数据 */
+    data?: string;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 视觉理解结果（从 LLM 返回）
+ */
+interface VisualUnderstandingResult {
+    /** 图片内容的自然语言描述 */
+    description: string;
+    /** 检测到的 UI 元素（可选） */
+    elements?: Array<{
+        type: string;
+        label?: string;
+        position?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    }>;
+    /** 图片类型/应用类型识别（可选） */
+    app_type?: string;
+}
+/**
+ * VisualFeature 配置
+ */
+interface VisualFeatureConfig {
+    /** 工作目录（默认 process.cwd()） */
+    workspaceDir?: string;
+    /** LLM 服务地址（默认 localhost:7575） */
+    baseUrl?: string;
+    /** 视觉理解模型名称（默认 Qwen3.5-4B-Q5_K_M） */
+    model?: string;
+    /**
+     * 主动视觉理解服务配置
+     *
+     * 用于用户主动调用 capture_and_understand_window_advanced 工具时使用
+     * 使用更大的模型（如 Qwen3.5-9B-Q4_K_M）提供更准确的理解
+     */
+    advancedVision?: {
+        /** LLM 服务地址（默认 localhost:7577） */
+        baseUrl?: string;
+        /** 视觉理解模型名称（默认 Qwen3.5-9B-Q4_K_M） */
+        model?: string;
+    };
+    /**
+     * Python 可执行文件路径（默认 'python'）
+     *
+     * 常用选项：
+     * - 'python' - 系统默认 Python
+     * - 'uv python' - uv 管理的 Python
+     * - 'uv' - 使用 uv run（需要配置 pythonArgs）
+     * - 完整路径如 'C:\\\Python312\\\python.exe'
+     */
+    pythonPath?: string;
+    /**
+     * Python 参数（可选）
+     *
+     * 例如使用 uv run：
+     * pythonArgs: ['run', '--with', 'pywin32', '--with', 'psutil', '--with', 'Pillow', 'script.py']
+     */
+    pythonArgs?: string[];
+    /**
+     * 窗口进程忽略规则文件路径（可选）
+     *
+     * 默认使用项目根目录下的 .agentdev/windows.ignore
+     * 文件格式：每行一个需要忽略的 exe 路径，支持通配符 *
+     *
+     * 示例：
+     * ```
+     * # 系统组件
+     * C:\\Windows\\explorer.exe
+     * # 输入法
+     * C:\\Windows\\System32\\ctfmon.exe
+     * # 通配符匹配
+     * C:\\Program Files\\WindowsApps\\Microsoft.InputApp_*
+     * ```
+     */
+    ignoreFilePath?: string;
+    /** 是否启用 onCallStart 窗口状态注入（默认 true） */
+    enableWindowInfo?: boolean;
+    /** 是否在初始化时检测 Python 环境（默认 true） */
+    checkPythonEnv?: boolean;
+    /**
+     * 后台监控配置
+     */
+    monitoring?: {
+        /** 是否启用后台监控 */
+        enabled?: boolean;
+        /** 轮询间隔（毫秒），默认 250 */
+        pollInterval?: number;
+        /** 截图 Worker 数量，默认 3 */
+        captureWorkerCount?: number;
+        /** 分析 Worker 数量，默认 1（单线程，避免连接压力） */
+        analysisWorkerCount?: number;
+        /** 同一窗口两次截图的最小间隔（毫秒），默认 5 秒 */
+        minCaptureInterval?: number;
+        /** 失去焦点多久后重新获得焦点需要重新截图（毫秒），默认 15 秒 */
+        focusChangeCaptureThreshold?: number;
+        /** 焦点持续多久后需要重新截图（毫秒），默认 30 秒 */
+        longFocusCaptureThreshold?: number;
+        /** 焦点状态持续多久后需要截图（毫秒），默认 10 秒 */
+        focusDurationCaptureThreshold?: number;
+        /** 同一窗口两次分析的最小间隔（毫秒），默认 60 秒 */
+        minAnalysisInterval?: number;
+        /** 失去焦点多久后重新获得焦点需要重新分析（毫秒），默认 30 秒 */
+        focusChangeAnalysisThreshold?: number;
+        /** 焦点持续多久后需要重新分析（毫秒），默认 60 秒 */
+        longFocusAnalysisThreshold?: number;
+        /** 缓存过期时间（毫秒），默认 300 秒（5分钟） */
+        analysisTTL?: number;
+    };
+    /**
+     * 缓存管理配置
+     */
+    cache?: {
+        /** 缓存根目录，默认 .agentdev/visual-cache */
+        cacheDir?: string;
+        /** 最大总大小（字节），默认 500MB */
+        maxSize?: number;
+        /** 最大文件数，默认 100 */
+        maxCount?: number;
+        /** 每个窗口保留的最大截图数量，默认 5 */
+        maxCapturesPerWindow?: number;
+        /** 截图TTL（毫秒），默认 7天 */
+        imageTTL?: number;
+        /** 分析结果TTL（毫秒），默认 7天 */
+        analysisTTL?: number;
+        /** 清理间隔（毫秒），默认 10分钟 */
+        cleanupInterval?: number;
+    };
+    /**
+     * 错误处理配置
+     */
+    errorHandling?: {
+        /** 最大重试次数，默认 1 */
+        maxRetries?: number;
+        /** 任务超时时间（毫秒），默认 30秒 */
+        taskTimeout?: number;
+        /** 是否跳过空图，默认 true */
+        skipEmptyImage?: boolean;
+    };
+}
+
+/**
+ * VisualFeature - 视觉理解功能模块
+ *
+ * 提供：
+ * 1. capture_and_understand_window 工具：截图 + 视觉模型理解
+ * 2. onCallStart 钩子：自动注入当前窗口状态信息
+ *
+ * Python 环境要求：
+ * - 需要安装 pywin32、psutil、Pillow 库
+ *
+ * 安装方式：
+ *   uv 方式（推荐）：
+ *   uv pip install pywin32 psutil Pillow
+ *
+ *   或使用 pip：
+ *   pip install pywin32 psutil Pillow
+ *
+ * Python 调用方式：
+ * - 默认使用 'python' 命令（从 PATH 中查找）
+ * - 如果使用 uv，可以配置为 'uv python' 或 'uv run --with pywin32 --with psutil --with Pillow'
+ *
+ * @example
+ * ```typescript
+ * import { VisualFeature } from './features/index.js';
+ *
+ * // 使用默认 python 命令
+ * const agent = new Agent({ ... }).use(new VisualFeature());
+ *
+ * // 使用 uv
+ * const agent = new Agent({ ... }).use(new VisualFeature({
+ *   pythonPath: 'uv python'
+ * }));
+ *
+ * // 使用 uv run（自动安装依赖）
+ * const agent = new Agent({ ... }).use(new VisualFeature({
+ *   pythonPath: 'uv'
+ *   pythonArgs: ['run', '--with', 'pywin32', '--with', 'psutil', '--with', 'Pillow']
+ * }));
+ * ```
+ */
+
+declare class VisualFeature implements AgentFeature {
+    readonly name = "visual";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u63D0\u4F9B\u7A97\u53E3\u622A\u56FE\u3001\u89C6\u89C9\u7406\u89E3\u548C\u5F53\u524D\u5DE5\u4F5C\u533A\u72B6\u6001\u6CE8\u5165\u80FD\u529B\u3002";
+    private config;
+    private client;
+    private advancedClient;
+    private windowMonitorService;
+    private captureWorkerPool;
+    private analysisWorkerPool;
+    private cacheManager;
+    private _visualEnabled;
+    private injectionState;
+    constructor(config?: VisualFeatureConfig);
+    private _packageInfo;
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     */
+    getTemplateNames(): string[];
+    getTools(): Tool[];
+    getAsyncTools(_ctx: FeatureInitContext): Promise<Tool[]>;
+    onInitiate(_ctx: FeatureInitContext): Promise<void>;
+    /**
+     * 检测 Python 环境和依赖库
+     */
+    private checkPythonEnvironment;
+    onDestroy(_ctx: FeatureContext): Promise<void>;
+    captureState(): FeatureStateSnapshot;
+    restoreState(snapshot: FeatureStateSnapshot): void;
+    getHookDescription(lifecycle: string, methodName: string): string | undefined;
+    /**
+     * 初始化后台监控服务
+     */
+    private initializeMonitoring;
+    /**
+     * 停止后台监控服务
+     */
+    private stopMonitoring;
+    /**
+     * 处理 /visual 命令并注入窗口信息（增量版本）
+     *
+     * 逻辑：
+     * 1. 检测 /visual 命令，切换视觉模式开关
+     * 2. 如果是命令，更新输入缓存为纯净内容（去除命令前缀）
+     * 3. 如果视觉模式开启（包括刚开启的），立即注入窗口信息
+     *
+     * 增量注入策略：
+     * - 第一次：全量注入（所有窗口 + 所有缓存）
+     * - 后续：只注入变化部分（窗口状态变化 + 新的分析结果）
+     */
+    injectWindowInfo(ctx: CallStartContext): Promise<void>;
+    /**
+     * 调用 Python 脚本枚举所有窗口
+     */
+    private enumerateWindows;
+    /**
+     * 获取当前焦点窗口句柄
+     */
+    private getForegroundWindow;
+    /**
+     * 格式化窗口信息为系统消息（全量版本，用于首次注入）
+     */
+    private formatWindowMessage;
+    /**
+     * 格式化缓存的窗口分析结果（全量版本，用于首次注入）
+     */
+    private formatCachedAnalyses;
+    /**
+     * 计算简单哈希（用于检测内容变化）
+     */
+    private hashDescription;
+    /**
+     * 计算窗口状态变化
+     */
+    private computeWindowChanges;
+    /**
+     * 计算缓存分析结果变化
+     */
+    private computeAnalysisChanges;
+    /**
+     * 格式化窗口变化
+     */
+    private formatWindowChanges;
+    /**
+     * 格式化分析变化
+     */
+    private formatAnalysisChanges;
+    /**
+     * 格式化增量消息（合并窗口状态变化 + 缓存分析变化 + 首次全量）
+     */
+    private formatIncrementalMessage;
+}
+
+/**
+ * MCP Tool Adapter - 适配器模式实现
+ *
+ * 将 MCP 工具适配为现有 Tool 接口，保持架构一致性
+ */
+
+/**
+ * 注册工具的简化接口
+ * 用于适配器包装
+ */
+interface RegisteredToolLike {
+    name: string;
+    description?: string;
+    inputSchema?: any;
+    outputSchema?: any;
+    annotations?: any;
+    handler?: (args: any, context?: any) => Promise<any> | any;
+    enabled?: boolean;
+}
+/**
+ * MCP 工具适配器配置
+ */
+interface MCPToolAdapterConfig {
+    /** MCP 服务器名称 */
+    serverName: string;
+    /** 是否为只读工具 */
+    readOnly?: boolean;
+    /** 渲染模板覆盖 */
+    render?: {
+        call?: string;
+        result?: string;
+    };
+}
+/**
+ * MCP 工具适配器
+ *
+ * 将 MCP RegisteredTool 适配为 Agent 的 Tool 接口
+ * 负责格式转换和生命周期管理
+ */
+declare class MCPToolAdapter implements Tool {
+    private registeredTool;
+    private config;
+    readonly name: string;
+    readonly description: string;
+    readonly parameters?: Record<string, any>;
+    readonly render?: {
+        call?: string;
+        result?: string;
+    };
+    constructor(registeredTool: RegisteredToolLike, config: MCPToolAdapterConfig);
+    /**
+     * 执行 MCP 工具
+     */
+    execute(args: any, context?: any): Promise<any>;
+    /**
+     * 格式化 MCP 工具结果
+     */
+    private formatResult;
+    /**
+     * 格式化错误
+     */
+    private formatError;
+    /**
+     * 从 RegisteredToolLike 提取参数定义
+     *
+     * MCP 工具的 inputSchema 已经是 JSON Schema 格式
+     * 直接返回，不需要转换
+     */
+    private extractParameters;
+}
+/**
+ * 批量创建 MCP 工具适配器
+ */
+declare function createMCPToolAdapters(registeredTools: RegisteredToolLike[], serverName: string, config?: Omit<MCPToolAdapterConfig, 'serverName'>): Tool[];
+
+interface MCPDiscoveredTool {
+    name: string;
+    description?: string;
+    inputSchema?: any;
+}
+interface MCPToolCreationOptions {
+    name?: string;
+    description?: string;
+    render?: MCPToolAdapterConfig['render'];
+    transformArgs?: (args: Record<string, unknown>, context?: any) => Record<string, unknown>;
+}
+interface MCPToolDiscoveryOptions {
+    filter?: (tool: MCPDiscoveredTool) => boolean;
+    mapName?: (tool: MCPDiscoveredTool) => string;
+    render?: MCPToolAdapterConfig['render'];
+    transformArgs?: MCPToolCreationOptions['transformArgs'];
+}
+interface MCPDiscoveredToolSet {
+    client: MCPClient;
+    tools: Tool[];
+}
+declare function createDefaultMCPToolName(serverId: string, toolName: string): string;
+declare class MCPClient {
+    readonly serverId: string;
+    private readonly config;
+    private readonly manager;
+    private connected;
+    constructor(serverId: string, config: MCPServerConfig, manager?: MCPConnectionManager);
+    connect(): Promise<void>;
+    listTools(): Promise<MCPDiscoveredTool[]>;
+    callTool(name: string, args: Record<string, unknown>): Promise<any>;
+    getConnectionManager(): MCPConnectionManager;
+    dispose(): Promise<void>;
+}
+declare function createMCPTool(client: MCPClient, tool: MCPDiscoveredTool, options?: MCPToolCreationOptions): Tool;
+declare function createMCPToolsFromClient(client: MCPClient, options?: MCPToolDiscoveryOptions): Promise<Tool[]>;
+declare function discoverMCPTools(serverId: string, config: MCPServerConfig, options?: MCPToolDiscoveryOptions, manager?: MCPConnectionManager): Promise<MCPDiscoveredToolSet>;
+
+interface MCPToolPatch {
+    enabled?: boolean;
+    name?: string;
+    description?: string;
+    render?: MCPToolAdapterConfig['render'];
+    transformArgs?: MCPToolCreationOptions['transformArgs'];
+}
+interface MCPToolManagementOptions {
+    include?: string[];
+    exclude?: string[];
+    disable?: string[];
+    rename?: Record<string, string>;
+    describe?: Record<string, string>;
+    render?: MCPToolAdapterConfig['render'];
+    toolRender?: Record<string, MCPToolAdapterConfig['render']>;
+    mapName?: (tool: MCPDiscoveredTool, client: MCPClient) => string;
+    transformArgs?: MCPToolCreationOptions['transformArgs'];
+    transform?: (tool: MCPDiscoveredTool, client: MCPClient) => MCPToolPatch | false | null | undefined;
+}
+interface MCPConfigMountOptions {
+    manager?: MCPConnectionManager;
+    clients?: Map<string, MCPClient>;
+    getServerOptions?: (serverId: string, serverConfig: MCPServerConfig) => MCPToolManagementOptions | undefined;
+    onError?: (serverId: string, error: unknown) => void;
+}
+interface MCPMountedToolSet {
+    client: MCPClient;
+    tools: Tool[];
+}
+interface MCPMountedConfigResult {
+    tools: Tool[];
+    clients: Map<string, MCPClient>;
+}
+declare function createManagedMCPToolsFromClient(client: MCPClient, options?: MCPToolManagementOptions): Promise<Tool[]>;
+declare function discoverManagedMCPTools(serverId: string, config: MCPServerConfig, options?: MCPToolManagementOptions, manager?: MCPConnectionManager): Promise<MCPMountedToolSet>;
+declare function mountMCPToolsFromConfig(config: MCPConfig, options?: MCPConfigMountOptions): Promise<MCPMountedConfigResult>;
+
+/**
+ * WebSearch Feature - 网页内容获取工具
  *
- * 功能：
- * - 提供 get_user_input 工具，允许 LLM 请求用户输入
- * - 通过 DebugHub 的 UDS 通道与 ViewerWorker 通信
- * - 前端显示输入框，用户提交后返回给 Agent
+ * 提供网页抓取和内容提取功能
+ *
+ * @example
+ * ```typescript
+ * import { WebSearchFeature } from './features/index.js';
+ * const agent = new Agent({ ... }).use(new WebSearchFeature());
+ * ```
  */
 
-interface UserInputFeatureConfig {
-    /** 默认超时时间（毫秒），默认无限等待 */
-    timeout?: number;
+interface WebSearchFeatureConfig {
+    crawl4ai?: false | (MCPToolManagementOptions & {
+        server?: MCPSSEConfig;
+    });
 }
-declare class UserInputFeature implements AgentFeature {
-    readonly name = "user-input";
+/**
+ * WebSearch Feature 实现
+ */
+declare class WebSearchFeature implements AgentFeature {
+    private readonly config;
+    readonly name = "websearch";
     readonly dependencies: string[];
     readonly source: string;
-    readonly description = "\u5141\u8BB8 Agent \u901A\u8FC7\u8C03\u8BD5\u754C\u9762\u5411\u7528\u6237\u53D1\u8D77\u8F93\u5165\u8BF7\u6C42\u5E76\u7B49\u5F85\u56DE\u590D\u3002";
-    private defaultTimeout;
-    private nextDraftInput;
+    readonly description = "\u63D0\u4F9B\u7F51\u9875\u6293\u53D6\u5DE5\u5177\uFF0C\u5E76\u53EF\u6258\u7BA1 crawl4ai MCP \u80FD\u529B\u7528\u4E8E\u6DF1\u5EA6\u7F51\u9875\u8BFB\u53D6\u3002";
+    private readonly manager;
+    private readonly crawl4aiClients;
+    private _packageInfo;
+    constructor(config?: WebSearchFeatureConfig);
     /**
-     * 缓存包信息
+     * 获取工具列表
      */
-    private _packageInfo;
+    getTools(): Tool[];
+    getAsyncTools(_ctx: FeatureInitContext): Promise<Tool[]>;
+    onDestroy(): Promise<void>;
     /**
      * 获取包信息（统一打包方案）
      */
     getPackageInfo(): PackageInfo | null;
     /**
      * 获取模板名称列表（统一打包方案）
-     * 注意：UserInputFeature 没有渲染模板
      */
     getTemplateNames(): string[];
-    constructor(config?: UserInputFeatureConfig);
-    setNextDraftInput(input: string): void;
-    /**
-     * 请求用户输入（核心方法）
-     */
-    requestUserInput(prompt: string, timeout?: number): Promise<string>;
-    requestUserInputEvent(request: UserInputRequest, timeout?: number): Promise<UserInputResponse>;
-    /**
-     * 获取用户输入（公开接口，供主循环直接调用）
-     * @param prompt 提示信息
-     * @param timeout 超时时间（毫秒）
-     * @returns 用户输入内容
-     */
-    getUserInput(prompt?: string, timeout?: number): Promise<string>;
-    getUserInputEvent(prompt?: string, timeout?: number, actions?: UserInputAction[]): Promise<UserInputResponse>;
-    getTools(): Tool[];
-    onInitiate(_ctx: FeatureInitContext): Promise<void>;
-    onDestroy(_ctx: FeatureContext): Promise<void>;
 }
 
+interface OpencodeBasicFeatureConfig {
+    workspaceDir?: string;
+}
 /**
  * OpencodeBasic Feature - 基础文件操作工具集
  */
@@ -2129,6 +3531,8 @@ declare class OpencodeBasicFeature implements AgentFeature {
      * Logger 实例，用于记录结构化日志
      */
     private logger;
+    private readonly workspaceDir;
+    constructor(config?: OpencodeBasicFeatureConfig);
     /**
      * Feature 初始化时清空读取历史
      */
@@ -2305,6 +3709,10 @@ interface BasicAgentConfig {
     tools?: Tool[];
     /** Skills 目录（可选，默认使用 .agentdev/skills） */
     skillsDir?: string;
+    /** 调试器和模板解析使用的项目根目录 */
+    projectRoot?: string;
+    /** 工具默认操作的工作目录 */
+    workspaceDir?: string;
 }
 /**
  * 基础 Agent 类
@@ -2595,7 +4003,7 @@ declare class ViewerWorker {
     /**
      * GET /api/templates/feature - 获取 Feature 模板映射
      */
-    handleGetFeatureTemplates(req: IncomingMessage, res: ServerResponse): void;
+    handleGetFeatureTemplates(req: IncomingMessage, res: ServerResponse, searchParams?: URLSearchParams): void;
     /**
      * 将模板文件路径转换为 HTTP URL
      * 支持多种来源：
@@ -2946,119 +4354,6 @@ declare function createListRenderer<T = any>(config: Omit<DataSourceRenderer<T>,
  */
 declare function discover(options?: SkillsOptions): Promise<SkillMetadata[]>;
 
-/**
- * MCP Tool Adapter - 适配器模式实现
- *
- * 将 MCP 工具适配为现有 Tool 接口，保持架构一致性
- */
-
-/**
- * 注册工具的简化接口
- * 用于适配器包装
- */
-interface RegisteredToolLike {
-    name: string;
-    description?: string;
-    inputSchema?: any;
-    outputSchema?: any;
-    annotations?: any;
-    handler?: (args: any, context?: any) => Promise<any> | any;
-    enabled?: boolean;
-}
-/**
- * MCP 工具适配器配置
- */
-interface MCPToolAdapterConfig {
-    /** MCP 服务器名称 */
-    serverName: string;
-    /** 是否为只读工具 */
-    readOnly?: boolean;
-    /** 渲染模板覆盖 */
-    render?: {
-        call?: string;
-        result?: string;
-    };
-}
-/**
- * MCP 工具适配器
- *
- * 将 MCP RegisteredTool 适配为 Agent 的 Tool 接口
- * 负责格式转换和生命周期管理
- */
-declare class MCPToolAdapter implements Tool {
-    private registeredTool;
-    private config;
-    readonly name: string;
-    readonly description: string;
-    readonly parameters?: Record<string, any>;
-    readonly render?: {
-        call?: string;
-        result?: string;
-    };
-    constructor(registeredTool: RegisteredToolLike, config: MCPToolAdapterConfig);
-    /**
-     * 执行 MCP 工具
-     */
-    execute(args: any, context?: any): Promise<any>;
-    /**
-     * 格式化 MCP 工具结果
-     */
-    private formatResult;
-    /**
-     * 格式化错误
-     */
-    private formatError;
-    /**
-     * 从 RegisteredToolLike 提取参数定义
-     *
-     * MCP 工具的 inputSchema 已经是 JSON Schema 格式
-     * 直接返回，不需要转换
-     */
-    private extractParameters;
-}
-/**
- * 批量创建 MCP 工具适配器
- */
-declare function createMCPToolAdapters(registeredTools: RegisteredToolLike[], serverName: string, config?: Omit<MCPToolAdapterConfig, 'serverName'>): Tool[];
-
-interface MCPDiscoveredTool {
-    name: string;
-    description?: string;
-    inputSchema?: any;
-}
-interface MCPToolCreationOptions {
-    name?: string;
-    description?: string;
-    render?: MCPToolAdapterConfig['render'];
-    transformArgs?: (args: Record<string, unknown>, context?: any) => Record<string, unknown>;
-}
-interface MCPToolDiscoveryOptions {
-    filter?: (tool: MCPDiscoveredTool) => boolean;
-    mapName?: (tool: MCPDiscoveredTool) => string;
-    render?: MCPToolAdapterConfig['render'];
-    transformArgs?: MCPToolCreationOptions['transformArgs'];
-}
-interface MCPDiscoveredToolSet {
-    client: MCPClient;
-    tools: Tool[];
-}
-declare function createDefaultMCPToolName(serverId: string, toolName: string): string;
-declare class MCPClient {
-    readonly serverId: string;
-    private readonly config;
-    private readonly manager;
-    private connected;
-    constructor(serverId: string, config: MCPServerConfig, manager?: MCPConnectionManager);
-    connect(): Promise<void>;
-    listTools(): Promise<MCPDiscoveredTool[]>;
-    callTool(name: string, args: Record<string, unknown>): Promise<any>;
-    getConnectionManager(): MCPConnectionManager;
-    dispose(): Promise<void>;
-}
-declare function createMCPTool(client: MCPClient, tool: MCPDiscoveredTool, options?: MCPToolCreationOptions): Tool;
-declare function createMCPToolsFromClient(client: MCPClient, options?: MCPToolDiscoveryOptions): Promise<Tool[]>;
-declare function discoverMCPTools(serverId: string, config: MCPServerConfig, options?: MCPToolDiscoveryOptions, manager?: MCPConnectionManager): Promise<MCPDiscoveredToolSet>;
-
 interface LoadAllMCPConfigsOptions {
     excludeServers?: string[];
 }
@@ -3066,43 +4361,6 @@ declare function getDefaultMCPConfigDir(rootDir?: string): string;
 declare function loadMCPConfigFromInput(input: string, rootDir?: string): MCPConfig | undefined;
 declare function loadAllMCPConfigs(rootDir?: string, options?: LoadAllMCPConfigsOptions): MCPConfig | undefined;
 
-interface MCPToolPatch {
-    enabled?: boolean;
-    name?: string;
-    description?: string;
-    render?: MCPToolAdapterConfig['render'];
-    transformArgs?: MCPToolCreationOptions['transformArgs'];
-}
-interface MCPToolManagementOptions {
-    include?: string[];
-    exclude?: string[];
-    disable?: string[];
-    rename?: Record<string, string>;
-    describe?: Record<string, string>;
-    render?: MCPToolAdapterConfig['render'];
-    toolRender?: Record<string, MCPToolAdapterConfig['render']>;
-    mapName?: (tool: MCPDiscoveredTool, client: MCPClient) => string;
-    transformArgs?: MCPToolCreationOptions['transformArgs'];
-    transform?: (tool: MCPDiscoveredTool, client: MCPClient) => MCPToolPatch | false | null | undefined;
-}
-interface MCPConfigMountOptions {
-    manager?: MCPConnectionManager;
-    clients?: Map<string, MCPClient>;
-    getServerOptions?: (serverId: string, serverConfig: MCPServerConfig) => MCPToolManagementOptions | undefined;
-    onError?: (serverId: string, error: unknown) => void;
-}
-interface MCPMountedToolSet {
-    client: MCPClient;
-    tools: Tool[];
-}
-interface MCPMountedConfigResult {
-    tools: Tool[];
-    clients: Map<string, MCPClient>;
-}
-declare function createManagedMCPToolsFromClient(client: MCPClient, options?: MCPToolManagementOptions): Promise<Tool[]>;
-declare function discoverManagedMCPTools(serverId: string, config: MCPServerConfig, options?: MCPToolManagementOptions, manager?: MCPConnectionManager): Promise<MCPMountedToolSet>;
-declare function mountMCPToolsFromConfig(config: MCPConfig, options?: MCPConfigMountOptions): Promise<MCPMountedConfigResult>;
-
 /**
  * MCP 工具渲染模板
  *
@@ -3140,4 +4398,4 @@ declare function renderMCPToolCall(serverName: string, toolName: string, args: R
  */
 declare function renderMCPToolResult(result: any, success?: boolean): string;
 
-export { AgentBase as Agent, AgentConfig, type AgentConfigFile, type AgentFeature, AgentInfo, type AgentInitiateContext, AgentPool, AgentSession, type AgentSessionSnapshot, AnthropicLLM, BasicAgent, type BasicAgentConfig, CallFinish, type CallFinishContext, CallStart, type CallStartContext, Context, type ContextInjector, DataSourceRegistry, type DataSourceRenderer, type DebugCapabilities, DebugHub, Decision, type DecisionResult, ExampleFeature, type ExampleFeatureConfig, type ExampleFeatureRuntimeState, type ExampleFeatureSnapshot, ExplorerAgent, type ExplorerAgentConfig, type SystemContext as ExplorerSystemContext, type FeatureContext, type FeatureInitContext, type FeatureStateSnapshot, FileSessionStore, type HookResult, InlineRenderTemplate, LLMClient, LLMResponse, type LoadAllMCPConfigsOptions, type Logger, type LoggerBindings, MCPClient, type MCPClientConfig, type MCPConfig, type MCPConfigMountOptions, type MCPConnectionInfo, MCPConnectionManager, MCPConnectionState, type MCPDiscoveredTool, type MCPDiscoveredToolSet, MCPFeature, type MCPFeatureOptions, type MCPHTTPConfig, type MCPMountedConfigResult, type MCPMountedToolSet, type MCPSSEConfig, type MCPServerConfig, type MCPSstdioConfig, type MCPStatistics, MCPToolAdapter, type MCPToolAdapterConfig, type MCPToolCreationOptions, type MCPToolDiscoveryOptions, type MCPToolManagementOptions, type MCPToolPatch, type MCPToolResult, MCP_RENDER_TEMPLATES, Message, MessageRole, type ModelConfig, OpenAILLM, OpencodeBasicFeature, type PackageInfo, PlaceholderContext, PlaceholderResolver, type SessionStore, SkillFeature, type SkillFeatureConfig, type SkillMetadata, type SkillsOptions, StepFinish, type StepFinishedContext, StepStart, type StepStartContext, SubAgentFeature, type SystemContext$1 as SystemContext, type TaskStatus, TemplateLoader, TemplateSource, TodoFeature, type TodoFeatureConfig, type TodoTask, type TodoTaskSummary, Tool, ToolCall, type ToolContext, type ToolContextValue, ToolFinished, ToolRegistry, ToolRenderConfig, type ToolResult, ToolUse, UserInputFeature, type UserInputFeatureConfig, ViewerWorker, assistant, compileContextForAnthropic, createAnthropicLLM, createDefaultMCPToolName, createLLM, createListRenderer, createLogger, createMCPTool, createMCPToolAdapters, createMCPToolsFromClient, createManagedMCPToolsFromClient, createMessage, createOpenAILLM, createTool, discover, discoverMCPTools, discoverManagedMCPTools, getClawRuntimeUrl, getDebugCapabilities, getDefaultMCPConfigDir, getDefaultSessionStore, getMCPRenderTemplate, getPackageInfoFromSource, installConsoleBridge, listConfigs, loadAllMCPConfigs, loadConfig, loadConfigSync, loadMCPConfigFromInput, mountMCPToolsFromConfig, renderMCPToolCall, renderMCPToolResult, resolveDebugTransportMode, runWithLogScope, system, toolResult, user };
+export { AgentBase as Agent, AgentConfig, type AgentConfigFile, type AgentFeature, AgentInfo, type AgentInitiateContext, AgentPool, AgentSession, type AgentSessionSnapshot, AnthropicLLM, AudioFeedbackFeature, AuditFeature, type AuditFeatureConfig, BasicAgent, type BasicAgentConfig, CallFinish, type CallFinishContext, CallStart, type CallStartContext, type CaptureResult, Context, type ContextInjector, type ContextSnapshot, DataSourceRegistry, type DataSourceRenderer, type DebugCapabilities, DebugHub, Decision, type DecisionResult, ExampleFeature, type ExampleFeatureConfig, type ExampleFeatureRuntimeState, type ExampleFeatureSnapshot, ExplorerAgent, type ExplorerAgentConfig, type SystemContext as ExplorerSystemContext, type FeatureContext, type FeatureInitContext, type FeatureStateSnapshot, FileSessionStore, type HookResult, InlineRenderTemplate, type KnownUser, LLMClient, LLMResponse, type LoadAllMCPConfigsOptions, type Logger, type LoggerBindings, MCPClient, type MCPClientConfig, type MCPConfig, type MCPConfigMountOptions, type MCPConnectionInfo, MCPConnectionManager, MCPConnectionState, type MCPDiscoveredTool, type MCPDiscoveredToolSet, MCPFeature, type MCPFeatureOptions, type MCPHTTPConfig, type MCPMountedConfigResult, type MCPMountedToolSet, type MCPSSEConfig, type MCPServerConfig, type MCPSstdioConfig, type MCPStatistics, MCPToolAdapter, type MCPToolAdapterConfig, type MCPToolCreationOptions, type MCPToolDiscoveryOptions, type MCPToolManagementOptions, type MCPToolPatch, type MCPToolResult, MCP_RENDER_TEMPLATES, MemoryFeature, type MemoryFeatureConfig, Message, MessageRole, type ModelConfig, OpenAILLM, OpencodeBasicFeature, type PackageInfo, PlaceholderContext, PlaceholderResolver, PluginCompatFeature, QQBotFeature, type QQBotFeatureConfig, type QQBotSendOptions, type QQBotSendResult, type SessionStore, ShellFeature, SkillFeature, type SkillFeatureConfig, type SkillMetadata, type SkillsOptions, StepFinish, type StepFinishedContext, StepStart, type StepStartContext, SubAgentFeature, type SystemContext$1 as SystemContext, TTSFeature, type TTSFeatureConfig, type TTSResult, type TTSState, type TaskStatus, TemplateLoader, TemplateSource, TodoFeature, type TodoFeatureConfig, type TodoTask, type TodoTaskSummary, Tool, ToolCall, type ToolContext, type ToolContextValue, ToolFinished, ToolRegistry, ToolRenderConfig, type ToolResult, ToolUse, UserInputFeature, type UserInputFeatureConfig, ViewerWorker, VisualFeature, type VisualFeatureConfig, type VisualUnderstandingResult, WebSearchFeature, type WebSearchFeatureConfig, type WindowInfo, assistant, compileContextForAnthropic, createAnthropicLLM, createDefaultMCPToolName, createLLM, createListRenderer, createLogger, createMCPTool, createMCPToolAdapters, createMCPToolsFromClient, createManagedMCPToolsFromClient, createMessage, createOpenAILLM, createTool, discover, discoverMCPTools, discoverManagedMCPTools, getClawRuntimeUrl, getDebugCapabilities, getDefaultMCPConfigDir, getDefaultSessionStore, getMCPRenderTemplate, getPackageInfoFromSource, installConsoleBridge, listConfigs, loadAllMCPConfigs, loadConfig, loadConfigSync, loadMCPConfigFromInput, mountMCPToolsFromConfig, renderMCPToolCall, renderMCPToolResult, resolveDebugTransportMode, runWithLogScope, system, toolResult, user };