@zhin.js/core 1.0.25 → 1.0.27

package/src/built/tool.ts

@@ -1,10 +1,11 @@
 /**
- * Tool Service
- * 统一的工具管理服务，支持 Tool ↔ Command 互转
+ * ToolFeature — 统一的工具管理服务
+ * 支持 Tool ↔ Command 互转
  */
+import { Feature, FeatureJSON } from "../feature.js";
 import { MessageCommand } from "../command.js";
 import { Message } from "../message.js";
-import { Context, Plugin, getPlugin } from "../plugin.js";
+import { Plugin, getPlugin } from "../plugin.js";
 import type { Tool, ToolDefinition, RegisteredAdapter, AdapterMessage, ToolContext, ToolJsonSchema, ToolParametersSchema, PropertySchema, MaybePromise, ToolPermissionLevel, ToolScope } from "../types.js";
 import { MatchResult } from "segment-matcher";
 
@@ -144,34 +145,10 @@ export function extractParamInfo(parameters: ToolJsonSchema): Tool.ParamInfo[] {
 
 /**
  * 定义工具的辅助函数（提供类型推断）
- * 
- * 使用泛型参数获得 execute 函数的类型检查，
- * 返回通用的 Tool 类型，可直接传给 addTool
- * 
- * @example
- * ```typescript
- * const myTool = defineTool<{ name: string }>({
- *   name: 'greet',
- *   description: '打招呼',
- *   parameters: {
- *     type: 'object',
- *     properties: {
- *       name: { type: 'string', description: '名字' }
- *     },
- *     required: ['name']
- *   },
- *   execute: async (args) => {
- *     return `你好，${args.name}！`;  // args.name 有类型提示
- *   }
- * });
- * 
- * plugin.addTool(myTool);  // 无需类型断言
- * ```
  */
 export function defineTool<TArgs extends Record<string, any> = Record<string, any>>(
   tool: ToolDefinition<TArgs>
 ): Tool {
-  // ToolDefinition<TArgs> 兼容 Tool，因为 execute 参数是协变的
   return tool as Tool;
 }
 
@@ -191,28 +168,6 @@ interface ParamDef {
 /**
  * ZhinTool 类
  * 提供类似 MessageCommand 的链式调用风格来定义工具
- * 
- * @example
- * ```typescript
- * const weatherTool = new ZhinTool('weather')
- *   .desc('查询天气信息')
- *   .param('city', { type: 'string', description: '城市名称' }, true)
- *   .param('days', { type: 'number', description: '预报天数' })
- *   .platform('qq', 'telegram')
- *   .scope('group', 'private')
- *   .permission('user')
- *   // AI 调用时执行（必须）
- *   .execute(async (args, ctx) => {
- *     return `${args.city} 的天气是晴天`;
- *   })
- *   // 可选：命令回调（与 MessageCommand.action 一致）
- *   // 如果定义了此回调，会生成 Command
- *   .action(async (message, result) => {
- *     return `命令执行: ${result.params.city}`;
- *   });
- * 
- * plugin.addTool(weatherTool);
- * ```
  */
 export class ZhinTool {
   #name: string;
@@ -225,6 +180,7 @@ export class ZhinTool {
   #permissionLevel: ToolPermissionLevel = 'user';
   #permissions: string[] = [];
   #tags: string[] = [];
+  #keywords: string[] = [];
   /** 命令回调（入参是 message, matchResult） */
   #commandCallback?: MessageCommand.Callback<RegisteredAdapter>;
   /** 命令配置 */
@@ -232,46 +188,28 @@ export class ZhinTool {
   #hidden: boolean = false;
   #source?: string;
 
-  /**
-   * 创建工具实例
-   * @param name 工具名称（唯一标识，建议使用 snake_case）
-   */
   constructor(name: string) {
     this.#name = name;
   }
 
-  /** 获取工具名称 */
   get name(): string {
     return this.#name;
   }
 
-  /** 获取工具描述 */
   get description(): string {
     return this.#description;
   }
 
-  /** 获取有序的参数列表 */
   get params(): ParamDef[] {
     return [...this.#params];
   }
 
-  /**
-   * 设置工具描述
-   * @param description 工具描述（供 AI 和帮助系统使用）
-   */
   desc(description: string): this {
     this.#description = description;
     return this;
   }
 
-  /**
-   * 添加参数（按调用顺序保持有序）
-   * @param name 参数名称
-   * @param schema 参数 Schema（类型、描述等）
-   * @param required 是否必填（默认 false）
-   */
   param(name: string, schema: PropertySchema, required: boolean = false): this {
-    // 如果已存在同名参数，更新它
     const existingIndex = this.#params.findIndex(p => p.name === name);
     if (existingIndex >= 0) {
       this.#params[existingIndex] = { name, schema, required };
@@ -281,125 +219,75 @@ export class ZhinTool {
     return this;
   }
 
-  /**
-   * 设置支持的平台
-   * @param platforms 平台名称列表（如 'qq', 'telegram'）
-   */
   platform(...platforms: string[]): this {
     this.#platforms.push(...platforms);
     return this;
   }
 
-  /**
-   * 设置支持的场景
-   * @param scopes 场景类型列表（'private', 'group', 'channel'）
-   */
   scope(...scopes: ToolScope[]): this {
     this.#scopes.push(...scopes);
     return this;
   }
 
-  /**
-   * 设置权限级别
-   * @param level 权限级别（'user', 'group_admin', 'group_owner', 'bot_admin', 'owner'）
-   */
   permission(level: ToolPermissionLevel): this {
     this.#permissionLevel = level;
     return this;
   }
 
-  /**
-   * 添加旧版权限要求（兼容 MessageCommand）
-   * @param permissions 权限字符串列表
-   */
   permit(...permissions: string[]): this {
     this.#permissions.push(...permissions);
     return this;
   }
 
-  /**
-   * 添加标签
-   * @param tags 标签列表
-   */
   tag(...tags: string[]): this {
     this.#tags.push(...tags);
     return this;
   }
 
-  /**
-   * 设置是否隐藏
-   * @param value 是否隐藏（默认 true）
-   */
+  keyword(...keywords: string[]): this {
+    this.#keywords.push(...keywords);
+    return this;
+  }
+
   hidden(value: boolean = true): this {
     this.#hidden = value;
     return this;
   }
 
-  /**
-   * 设置使用说明（命令配置）
-   * @param usage 使用说明列表
-   */
   usage(...usage: string[]): this {
     this.#commandConfig.usage = [...(this.#commandConfig.usage || []), ...usage];
     return this;
   }
 
-  /**
-   * 设置示例（命令配置）
-   * @param examples 示例列表
-   */
   examples(...examples: string[]): this {
     this.#commandConfig.examples = [...(this.#commandConfig.examples || []), ...examples];
     return this;
   }
 
-  /**
-   * 设置别名（命令配置）
-   * @param alias 别名列表
-   */
   alias(...alias: string[]): this {
     this.#commandConfig.alias = [...(this.#commandConfig.alias || []), ...alias];
     return this;
   }
 
-  /**
-   * 设置自定义命令模式
-   * @param pattern 命令模式（如 'weather <city> [days]'）
-   */
   pattern(pattern: string): this {
     this.#commandConfig.pattern = pattern;
     return this;
   }
 
-  /**
-   * 设置 AI 工具执行函数
-   * @param callback 执行回调，入参是 (args, context)
-   */
   execute(callback: (args: Record<string, any>, context?: ToolContext) => MaybePromise<any>): this {
     this.#execute = callback;
     return this;
   }
 
-  /**
-   * 设置命令回调（可选，与 MessageCommand.action 一致）
-   * 如果定义了此回调，会自动生成 Command
-   * 入参是 (message, matchResult)
-   * 
-   * @param callback 命令回调
-   */
   action(callback: MessageCommand.Callback<RegisteredAdapter>): this {
     this.#commandCallback = callback;
     return this;
   }
 
-  /**
-   * 构建有序的 ToolParametersSchema
-   */
   #buildParameters(): ToolParametersSchema {
     const properties: Record<string, PropertySchema> = {};
     const required: string[] = [];
     
-    // 按顺序构建（必填参数排前面）
     const sortedParams = [...this.#params].sort((a, b) => {
       if (a.required && !b.required) return -1;
       if (!a.required && b.required) return 1;
@@ -420,9 +308,6 @@ export class ZhinTool {
     };
   }
 
-  /**
-   * 生成命令模式字符串
-   */
   #generatePattern(): string {
     if (this.#commandConfig.pattern) {
       return this.#commandConfig.pattern;
@@ -430,7 +315,6 @@ export class ZhinTool {
     
     const parts: string[] = [this.#name];
     
-    // 按顺序生成参数（必填在前，可选在后）
     const sortedParams = [...this.#params].sort((a, b) => {
       if (a.required && !b.required) return -1;
       if (!a.required && b.required) return 1;
@@ -449,9 +333,6 @@ export class ZhinTool {
     return parts.join(' ');
   }
 
-  /**
-   * 转换为 Tool 对象
-   */
   toTool(): Tool {
     if (!this.#execute) {
       throw new Error(`Tool "${this.#name}" has no execute() defined`);
@@ -464,7 +345,6 @@ export class ZhinTool {
       execute: this.#execute,
     };
 
-    // 添加可选字段
     if (this.#platforms.length > 0) tool.platforms = this.#platforms;
     if (this.#scopes.length > 0) tool.scopes = this.#scopes;
     if (this.#permissionLevel !== 'user') tool.permissionLevel = this.#permissionLevel;
@@ -472,8 +352,8 @@ export class ZhinTool {
     if (this.#tags.length > 0) tool.tags = this.#tags;
     if (this.#hidden) tool.hidden = this.#hidden;
     if (this.#source) tool.source = this.#source;
+    if (this.#keywords.length > 0) tool.keywords = this.#keywords;
 
-    // 命令配置：如果没有定义 command 回调，则不生成命令
     if (!this.#commandCallback) {
       tool.command = false;
     } else {
@@ -487,17 +367,10 @@ export class ZhinTool {
     return tool;
   }
 
-  /**
-   * 获取 action 回调（命令回调，如果有）
-   */
   getActionCallback(): MessageCommand.Callback<RegisteredAdapter> | undefined {
     return this.#commandCallback;
   }
 
-  /**
-   * 转换为 JSON 格式（供 AI 使用，不包含 execute 函数）
-   * 符合 OpenAI Function Calling 规范
-   */
   toJSON(): {
     name: string;
     description: string;
@@ -513,7 +386,6 @@ export class ZhinTool {
       parameters: this.#buildParameters(),
     };
 
-    // 添加可选字段
     if (this.#platforms.length > 0) json.platforms = this.#platforms;
     if (this.#scopes.length > 0) json.scopes = this.#scopes;
     if (this.#permissionLevel !== 'user') json.permissionLevel = this.#permissionLevel;
@@ -522,14 +394,10 @@ export class ZhinTool {
     return json;
   }
 
-  /**
-   * 输出帮助信息（类似 MessageCommand）
-   */
   get help(): string {
     const lines: string[] = [this.#generatePattern()];
     if (this.#description) lines.push(`  ${this.#description}`);
     
-    // 参数信息（按顺序）
     if (this.#params.length > 0) {
       lines.push('  参数:');
       for (const param of this.#params) {
@@ -539,22 +407,18 @@ export class ZhinTool {
       }
     }
     
-    // 权限信息
     if (this.#permissionLevel !== 'user') {
       lines.push(`  权限: ${this.#permissionLevel}`);
     }
     
-    // 平台限制
     if (this.#platforms.length > 0) {
       lines.push(`  平台: ${this.#platforms.join(', ')}`);
     }
     
-    // 场景限制
     if (this.#scopes.length > 0) {
       lines.push(`  场景: ${this.#scopes.join(', ')}`);
     }
     
-    // 命令说明
     if (this.#commandConfig.usage?.length) {
       lines.push('  用法:');
       for (const u of this.#commandConfig.usage) {
@@ -562,7 +426,6 @@ export class ZhinTool {
       }
     }
     
-    // 命令示例
     if (this.#commandConfig.examples?.length) {
       lines.push('  示例:');
       for (const e of this.#commandConfig.examples) {
@@ -573,22 +436,17 @@ export class ZhinTool {
     return lines.join('\n');
   }
 
-  /**
-   * 输出简短信息
-   */
   toString(): string {
     return `[ZhinTool: ${this.#name}] ${this.#description}`;
   }
 }
 
-// 为了兼容 addTool，让 ZhinTool 可以隐式转换为 Tool
-// 通过在 ToolService 中检查是否是 ZhinTool 实例
 export function isZhinTool(obj: any): obj is ZhinTool {
   return obj instanceof ZhinTool;
 }
 
 // ============================================================================
-// ToolService 类型定义
+// ToolFeature 类型定义
 // ============================================================================
 
 /**
@@ -597,7 +455,7 @@ export function isZhinTool(obj: any): obj is ZhinTool {
 export type ToolInput = Tool | ZhinTool;
 
 /**
- * ToolService 扩展方法类型
+ * ToolContext 扩展方法类型
  */
 export interface ToolContextExtensions {
   /** 添加工具（自动生成命令） */
@@ -611,51 +469,14 @@ declare module "../plugin.js" {
   namespace Plugin {
     interface Extensions extends ToolContextExtensions {}
     interface Contexts {
-      tool: ToolService;
+      tool: ToolFeature;
     }
   }
 }
 
-/**
- * 工具服务
- */
-export interface ToolService {
-  /** 所有注册的工具 */
-  readonly tools: Map<string, Tool>;
-  
-  /** 工具对应的命令（如果生成了） */
-  readonly toolCommands: Map<string, MessageCommand<RegisteredAdapter>>;
-  
-  /** 添加工具（支持 Tool 对象或 ZhinTool 实例） */
-  add(tool: ToolInput, pluginName: string, generateCommand?: boolean): () => void;
-  
-  /** 移除工具 */
-  remove(name: string): boolean;
-  
-  /** 获取工具 */
-  get(name: string): Tool | undefined;
-  
-  /** 获取所有工具 */
-  getAll(): Tool[];
-  
-  /** 根据标签过滤工具 */
-  getByTags(tags: string[]): Tool[];
-  
-  /** 执行工具 */
-  execute(name: string, args: Record<string, any>, context?: ToolContext): Promise<any>;
-  
-  /** 将 Command 转换为 Tool */
-  commandToTool(command: MessageCommand<RegisteredAdapter>, pluginName: string): Tool;
-  
-  /** 收集所有可用工具（包括从 Command 转换的） */
-  collectAll(plugin: Plugin): Tool[];
-  
-  /** 
-   * 根据上下文过滤工具
-   * 检查平台、场景、权限是否匹配
-   */
-  filterByContext(tools: Tool[], context: ToolContext): Tool[];
-}
+// ============================================================================
+// 内部工具函数
+// ============================================================================
 
 /**
  * 将 Tool 转换为 MessageCommand
@@ -664,27 +485,21 @@ function toolToCommand(tool: Tool): MessageCommand<RegisteredAdapter> {
   const pattern = generatePattern(tool);
   const command = new MessageCommand<RegisteredAdapter>(pattern);
   
-  // 设置描述
   command.desc(tool.description);
   
-  // 设置使用说明
   if (tool.command && tool.command.usage) {
     command.usage(...tool.command.usage);
   }
   
-  // 设置示例
   if (tool.command && tool.command.examples) {
     command.examples(...tool.command.examples);
   }
   
-  // 设置权限
   if (tool.permissions?.length) {
     command.permit(...tool.permissions);
   }
   
-  // 设置执行回调
   command.action(async (message: Message<AdapterMessage<RegisteredAdapter>>, result: MatchResult) => {
-    // 构建工具上下文
     const context: ToolContext = {
       platform: message.$adapter,
       botId: message.$bot,
@@ -693,13 +508,11 @@ function toolToCommand(tool: Tool): MessageCommand<RegisteredAdapter> {
       message,
     };
     
-    // 从 MatchResult 提取参数
     const args = extractArgsFromMatchResult(result, tool.parameters);
     
     try {
       const response = await tool.execute(args, context);
       
-      // 处理返回值
       if (response === undefined || response === null) {
         return undefined;
       }
@@ -708,7 +521,6 @@ function toolToCommand(tool: Tool): MessageCommand<RegisteredAdapter> {
         return response;
       }
       
-      // 对象类型，格式化输出
       return formatToolResult(response);
     } catch (error) {
       const errorMsg = error instanceof Error ? error.message : String(error);
@@ -722,13 +534,12 @@ function toolToCommand(tool: Tool): MessageCommand<RegisteredAdapter> {
 /**
  * 将 MessageCommand 转换为 Tool
  */
-function commandToTool(
+function commandToToolFn(
   command: MessageCommand<RegisteredAdapter>,
   pluginName: string
 ): Tool {
   const { pattern, helpInfo } = command;
   
-  // 解析命令模式，提取参数
   const parameters = parseCommandPattern(pattern);
   
   return {
@@ -738,7 +549,6 @@ function commandToTool(
     source: `command:${pluginName}`,
     tags: ['command', pluginName],
     execute: async (args, context) => {
-      // 重建命令字符串
       const cmdParts = [pattern.split(' ')[0]];
       
       if (parameters.properties) {
@@ -751,9 +561,7 @@ function commandToTool(
       
       const cmdString = cmdParts.join(' ');
       
-      // 如果有消息上下文，模拟命令执行
       if (context?.message) {
-        // 创建一个临时消息副本，修改内容为命令字符串
         const tempMessage = Object.create(context.message);
         tempMessage.$content = cmdString;
         
@@ -767,7 +575,7 @@ function commandToTool(
         command: cmdString 
       };
     },
-    command: false, // 不再生成命令（已经是命令了）
+    command: false,
   };
 }
 
@@ -780,12 +588,10 @@ function extractArgsFromMatchResult(
 ): Record<string, any> {
   const args: Record<string, any> = {};
   
-  // params 包含所有提取的参数
   if (result.params) {
     Object.assign(args, result.params);
   }
   
-  // 类型转换
   if (schema.properties) {
     for (const [key, prop] of Object.entries(schema.properties)) {
       if (args[key] !== undefined) {
@@ -805,13 +611,11 @@ function extractArgsFromMatchResult(
 
 /**
  * 解析命令模式，生成参数 Schema
- * @example 'weather <city> [days:number]' => { properties: { city: {...}, days: {...} }, required: ['city'] }
  */
 function parseCommandPattern(pattern: string): ToolParametersSchema {
   const properties: Record<string, PropertySchema> = {};
   const required: string[] = [];
   
-  // 匹配 <name:type> 或 [name:type] 格式
   const paramRegex = /([<\[])(\w+)(?::(\w+))?([>\]])/g;
   let match;
   
@@ -853,7 +657,6 @@ function formatToolResult(result: any): string {
     return `❌ ${result.error}`;
   }
   
-  // 尝试友好格式化
   try {
     return JSON.stringify(result, null, 2);
   } catch {
@@ -861,189 +664,265 @@ function formatToolResult(result: any): string {
   }
 }
 
-/**
- * 创建工具服务 Context
- */
-export function createToolService(): Context<'tool', ToolContextExtensions> {
-  const tools = new Map<string, Tool>();
-  const toolCommands = new Map<string, MessageCommand<RegisteredAdapter>>();
-  const toolPluginMap = new Map<string, string>();
-  
-  const value: ToolService = {
-    tools,
-    toolCommands,
-    
-    add(toolInput, pluginName, generateCommand = true) {
-      // 保存原始 ZhinTool 引用（用于获取命令回调）
-      const zhinTool = isZhinTool(toolInput) ? toolInput : null;
-      
-      // 转换为 Tool 对象
-      const tool: Tool = zhinTool ? zhinTool.toTool() : toolInput as Tool;
-      
-      // 自动添加来源标识
-      const toolWithSource: Tool = {
-        ...tool,
-        source: tool.source || `plugin:${pluginName}`,
-        tags: [...(tool.tags || []), 'plugin', pluginName],
-      };
-      
-      tools.set(tool.name, toolWithSource);
-      toolPluginMap.set(tool.name, pluginName);
+// ============================================================================
+// ToolFeature 实现
+// ============================================================================
+
+export class ToolFeature extends Feature<Tool> {
+  readonly name = 'tool' as const;
+  readonly icon = 'Wrench';
+  readonly desc = '工具';
+
+  /** 按名称索引 */
+  readonly byName = new Map<string, Tool>();
+
+  /** 工具对应的命令 */
+  readonly toolCommands = new Map<string, MessageCommand<RegisteredAdapter>>();
+
+  /** 工具到插件名的映射 */
+  readonly #toolPluginMap = new Map<string, string>();
+
+  /**
+   * 添加工具
+   * @param toolInput 工具或 ZhinTool 实例
+   * @param pluginName 注册插件名
+   * @param generateCommand 是否生成命令（默认 true）
+   */
+  addTool(toolInput: ToolInput, pluginName: string, generateCommand: boolean = true): () => void {
+    const zhinTool = isZhinTool(toolInput) ? toolInput : null;
+    const tool: Tool = zhinTool ? zhinTool.toTool() : toolInput as Tool;
+
+    const toolWithSource: Tool = {
+      ...tool,
+      source: tool.source || `plugin:${pluginName}`,
+      tags: [...(tool.tags || []), 'plugin', pluginName],
+    };
+
+    this.byName.set(tool.name, toolWithSource);
+    this.#toolPluginMap.set(tool.name, pluginName);
+
+    // 生成对应的命令
+    if (generateCommand && tool.command !== false) {
+      let command: MessageCommand<RegisteredAdapter>;
       
-      // 生成对应的命令
-      // 只有当 tool.command !== false 且 generateCommand 为 true 时才生成
-      if (generateCommand && tool.command !== false) {
-        let command: MessageCommand<RegisteredAdapter>;
+      const customCallback = zhinTool?.getActionCallback();
+      if (customCallback) {
+        command = new MessageCommand<RegisteredAdapter>(
+          tool.command && typeof tool.command === 'object' && tool.command.pattern 
+            ? tool.command.pattern 
+            : generatePattern(toolWithSource)
+        );
         
-        // 如果是 ZhinTool 且有自定义 action 回调，使用自定义回调
-        const customCallback = zhinTool?.getActionCallback();
-        if (customCallback) {
-          // 使用自定义回调创建命令
-          command = new MessageCommand<RegisteredAdapter>(
-            tool.command && typeof tool.command === 'object' && tool.command.pattern 
-              ? tool.command.pattern 
-              : generatePattern(toolWithSource)
-          );
-          
-          command.desc(tool.description);
-          
-          if (tool.command && typeof tool.command === 'object') {
-            if (tool.command.usage) command.usage(...tool.command.usage);
-            if (tool.command.examples) command.examples(...tool.command.examples);
-          }
-          
-          if (tool.permissions?.length) {
-            command.permit(...tool.permissions);
-          }
-          
-          // 使用自定义回调
-          command.action(customCallback);
-        } else {
-          // 使用默认的 toolToCommand（基于 tool.execute）
-          command = toolToCommand(toolWithSource);
-        }
+        command.desc(tool.description);
         
-        toolCommands.set(tool.name, command);
+        if (tool.command && typeof tool.command === 'object') {
+          if (tool.command.usage) command.usage(...tool.command.usage);
+          if (tool.command.examples) command.examples(...tool.command.examples);
+        }
         
-        // 注册到命令服务
-        const plugin = getPlugin();
-        const commandService = plugin.root.inject('command');
-        if (commandService) {
-          commandService.add(command, pluginName);
+        if (tool.permissions?.length) {
+          command.permit(...tool.permissions);
         }
+        
+        command.action(customCallback);
+      } else {
+        command = toolToCommand(toolWithSource);
       }
       
-      return () => value.remove(tool.name);
-    },
-    
-    remove(name) {
-      const existed = tools.has(name);
-      tools.delete(name);
-      toolPluginMap.delete(name);
+      this.toolCommands.set(tool.name, command);
       
-      // 移除对应的命令
-      const command = toolCommands.get(name);
-      if (command) {
-        const plugin = getPlugin();
-        const commandService = plugin.root.inject('command');
-        if (commandService) {
-          commandService.remove(command);
-        }
-        toolCommands.delete(name);
+      const plugin = getPlugin();
+      const commandService = plugin.root.inject('command');
+      if (commandService) {
+        commandService.add(command, pluginName);
       }
-      
-      return existed;
-    },
-    
-    get(name) {
-      return tools.get(name);
-    },
-    
-    getAll() {
-      return Array.from(tools.values());
-    },
-    
-    getByTags(tags) {
-      return Array.from(tools.values()).filter(tool => 
-        tags.some(tag => tool.tags?.includes(tag))
-      );
-    },
-    
-    async execute(name, args, context) {
-      const tool = tools.get(name);
-      if (!tool) {
-        throw new Error(`Tool "${name}" not found`);
+    }
+
+    // Use Feature.add for item tracking
+    const baseDispose = super.add(toolWithSource, pluginName);
+
+    return () => {
+      this.removeTool(tool.name);
+      baseDispose();
+    };
+  }
+
+  /**
+   * 移除工具
+   */
+  removeTool(name: string): boolean {
+    const tool = this.byName.get(name);
+    if (!tool) return false;
+
+    this.byName.delete(name);
+    this.#toolPluginMap.delete(name);
+
+    // 移除对应的命令
+    const command = this.toolCommands.get(name);
+    if (command) {
+      const plugin = getPlugin();
+      const commandService = plugin.root.inject('command');
+      if (commandService) {
+        commandService.remove(command);
       }
-      return tool.execute(args, context);
-    },
+      this.toolCommands.delete(name);
+    }
+
+    // 移除 item
+    super.remove(tool);
+    return true;
+  }
+
+  /**
+   * 获取工具
+   */
+  get(name: string): Tool | undefined {
+    return this.byName.get(name);
+  }
+
+  /**
+   * 获取所有工具
+   */
+  getAll(): Tool[] {
+    return [...this.items];
+  }
+
+  /**
+   * 根据标签过滤工具
+   */
+  getByTags(tags: string[]): Tool[] {
+    return this.items.filter(tool => 
+      tags.some(tag => tool.tags?.includes(tag))
+    );
+  }
+
+  /**
+   * 执行工具
+   */
+  async execute(name: string, args: Record<string, any>, context?: ToolContext): Promise<any> {
+    const tool = this.byName.get(name);
+    if (!tool) {
+      throw new Error(`Tool "${name}" not found`);
+    }
+    return tool.execute(args, context);
+  }
+
+  /**
+   * 将 Command 转换为 Tool
+   */
+  commandToTool(command: MessageCommand<RegisteredAdapter>, pluginName: string): Tool {
+    return commandToToolFn(command, pluginName);
+  }
+
+  /**
+   * 收集所有可用工具（包括从 Command 转换的）
+   */
+  collectAll(plugin: Plugin): Tool[] {
+    const allTools: Tool[] = [];
     
-    commandToTool,
+    allTools.push(...this.getAll());
     
-    collectAll(plugin) {
-      const allTools: Tool[] = [];
-      
-      // 1. 收集 ToolService 中的所有工具
-      allTools.push(...value.getAll());
-      
-      // 2. 收集 Command 并转换为 Tool
-      const commandService = plugin.root.inject('command');
-      if (commandService) {
-        for (const command of commandService.items) {
-          // 跳过已经由 Tool 生成的命令
-          const isFromTool = Array.from(toolCommands.values()).includes(command);
-          if (!isFromTool) {
-            const toolFromCmd = commandToTool(command, 'command');
-            allTools.push(toolFromCmd);
-          }
+    const commandService = plugin.root.inject('command');
+    if (commandService) {
+      for (const command of commandService.items) {
+        const isFromTool = Array.from(this.toolCommands.values()).includes(command);
+        if (!isFromTool) {
+          const toolFromCmd = commandToToolFn(command, 'command');
+          allTools.push(toolFromCmd);
         }
       }
-      
-      // 3. 收集适配器提供的工具
-      for (const [name, context] of plugin.root.contexts) {
-        const adapterValue = context.value;
-        if (adapterValue && typeof adapterValue === 'object' && 'getTools' in adapterValue) {
-          const adapter = adapterValue as { getTools(): Tool[] };
-          allTools.push(...adapter.getTools());
-        }
+    }
+    
+    for (const [name, context] of plugin.root.contexts) {
+      const adapterValue = context.value;
+      if (adapterValue && typeof adapterValue === 'object' && 'getTools' in adapterValue) {
+        const adapter = adapterValue as { getTools(): Tool[] };
+        allTools.push(...adapter.getTools());
       }
-      
-      return allTools;
-    },
+    }
     
-    filterByContext(tools, context) {
-      return tools.filter(tool => canAccessTool(tool, context));
-    },
-  };
-  
-  return {
-    name: 'tool',
-    description: '统一工具服务',
-    value,
-    extensions: {
+    return allTools;
+  }
+
+  /**
+   * 根据上下文过滤工具
+   */
+  filterByContext(tools: Tool[], context: ToolContext): Tool[] {
+    return tools.filter(tool => canAccessTool(tool, context));
+  }
+
+  /**
+   * 按插件名获取工具
+   */
+  getToolsByPlugin(pluginName: string): Tool[] {
+    const result: Tool[] = [];
+    for (const [toolName, pName] of this.#toolPluginMap) {
+      if (pName === pluginName) {
+        const tool = this.byName.get(toolName);
+        if (tool) result.push(tool);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 兼容旧接口：tools Map
+   */
+  get tools(): Map<string, Tool> {
+    return this.byName;
+  }
+
+  /**
+   * 序列化为 JSON
+   */
+  toJSON(pluginName?: string): FeatureJSON {
+    const list = pluginName ? this.getByPlugin(pluginName) : this.items;
+    return {
+      name: this.name,
+      icon: this.icon,
+      desc: this.desc,
+      count: list.length,
+      items: list.map(t => ({
+        name: t.name,
+        desc: t.description,
+        platforms: t.platforms,
+        tags: t.tags,
+      })),
+    };
+  }
+
+  /**
+   * 提供给 Plugin.prototype 的扩展方法
+   */
+  get extensions() {
+    const feature = this;
+    return {
       addTool(tool: ToolInput) {
         const plugin = getPlugin();
-        const dispose = value.add(tool, plugin.name, true);
+        const toolObj = isZhinTool(tool) ? tool.toTool() : tool as Tool;
+        const dispose = feature.addTool(tool, plugin.name, true);
+        plugin.recordFeatureContribution(feature.name, toolObj.name);
         plugin.onDispose(dispose);
         return dispose;
       },
       addToolOnly(tool: ToolInput) {
         const plugin = getPlugin();
-        const dispose = value.add(tool, plugin.name, false);
+        const toolObj = isZhinTool(tool) ? tool.toTool() : tool as Tool;
+        const dispose = feature.addTool(tool, plugin.name, false);
+        plugin.recordFeatureContribution(feature.name, toolObj.name);
         plugin.onDispose(dispose);
         return dispose;
       },
-    },
-  };
+    };
+  }
 }
 
 // 导出类型和工具函数
-// 注意：ZhinTool, isZhinTool, ToolInput 已通过 export 关键字直接导出
 export { 
   toolToCommand, 
-  commandToTool,
+  commandToToolFn as commandToTool,
   canAccessTool,
   inferPermissionLevel,
   hasPermissionLevel,
   PERMISSION_LEVEL_PRIORITY,
 };
-