[Feature] Optimize `/tools` Command Output for Enhanced Human Readability / 优化 `/tools` 命令输出以增强人类可读性

[SunYanbox]

概述 / Overview

The current /tools command output is machine-oriented and difficult for humans to read and understand quickly. In fact, this command is typically used only by users, as tool information is already injected into the prompt. This feature aims to improve the readability and usability of the tool list by providing a more structured, informative, and visually appealing output format.

当前的 /tools 命令输出偏向机器阅读，难以让人快速阅读和理解。事实上，此命令一般只由用户使用，工具的信息已被注入到提示词中。此功能旨在通过提供更结构化、信息更丰富且视觉上更吸引人的输出格式，提高工具列表的可读性和可用性。

---

当前状态 / Current State

The existing /tools command (implemented in src/console/commands/systems/tools_cmd.py) currently displays only a simple table with tool names and docstrings. This lacks important contextual information that users need when collaborating with an LLM.

现有的 /tools 命令（在 src/console/commands/systems/tools_cmd.py 中实现）目前仅显示一个简单的表格，包含工具名称和文档字符串。这缺乏用户在与 LLM 协作时所需的重要上下文信息。

---

需求 / Requirements

1. Enhanced Tool Categorization / 增强的工具分类

Group tools by functional category with clear visual separation:

Categories:

• Query Tools (Read-Only) – Read‑only operations for file exploration and search
• Edit Tools (Audit Required) – File‑modifying operations that need audit approval
• Dangerous Tools (Audit Required) – Potentially dangerous operations (e.g., Git commands)

Implementation:

# Example categorization structure
CATEGORIES = {
    "query": {
        "title": "Query Tools (Read-Only Operations)",
        "title_cn": "查询工具 (只读操作)",
        "color": "green",
        "tools": ["ls", "glob", "read", "read_lines", "stat", "exact_search", "regex_search", "symbol_ref"]
    },
    "edit": {
        "title": "Edit Tools (Audit Required)",
        "title_cn": "编辑工具 (需要审计)",
        "color": "yellow",
        "tools": ["write", "edit"]
    },
    "dangerous": {
        "title": "Dangerous Tools (Audit Required)",
        "title_cn": "危险工具 (需要审计)",
        "color": "red",
        "tools": ["git"]
    }
}

按功能类别对工具进行分组，并提供清晰的视觉分隔：

类别：

• 查询工具 (只读) – 用于文件探索和搜索的只读操作
• 编辑工具 (需审计审批) – 修改文件的操作，需要审计批准
• 危险工具 (需审计审批) – 潜在危险的操作（如 Git 命令）

实现示例：同上代码块。

---

2. Rich Information Display /丰富的信息显示

Display comprehensive information for each tool:

Information Fields:

• Tool name (bold, highlighted)
• Required parameters (marked with ⚠️ or similar indicator)
• Optional parameters with default values
• Security level indicator (🔒 safe, ⚠️ audit required, ☢️ dangerous) with prominent Textual/Rich coloring
• Brief usage example
• Execution time statistics (if available in history)

Example Output Format:

┌─────────────────────────────────────────────────────────────────────┐
│ 🔍 Query Tools (Read-Only Operations)                               │
├─────────────────────────────────────────────────────────────────────┤
│ 📄 read                            [File Reader]                    │
│   Parameters:                                                        │
│     • file_path (required)                                          │
│     • max_lines (optional, default: 0 = unlimited)                  │
│     • encoding (optional, default: 'utf-8')                         │
│   Security: 🔒 Safe (read-only)                                     │
│   Example: <func_call><func_name>read</func_name><param             │
│            name="file_path">README.md</param></func_call>           │
│   Usage: 47 times | Avg: 0.023 sec                                   │
├─────────────────────────────────────────────────────────────────────┤
│ 📏 read_lines                      [Line Range Reader]              │
│   Parameters:                                                        │
│     • file_path (required)                                          │
│     • start (required)                                              │
│     • end (required)                                                │
│     • context (optional, default: 2)                                │
│   Security: 🔒 Safe (read-only)                                     │
│   Example: <func_call><func_name>read_lines</func_name><param       │
│            name="file_path">main.py</param><param                   │
│            name="start">1</param><param name="end">50</param>       │
│            </func_call>                                             │
└─────────────────────────────────────────────────────────────────────┘

Note: Create a dedicated widget to render the tool format section, with double-click auto‑copy functionality.
注意：做一个专门的控件渲染工具格式部分，双击自动复制的那种。

为每个工具显示全面的信息：

信息字段：

• 工具名称（粗体，突出显示）
• 必需参数（用⚠️或类似指示器标记）
• 可选参数及默认值
• 安全级别指示器（🔒表示安全，⚠️需要审计，☢️危险）配合 Textual/Rich 颜色使得显示更加明显
• 简要使用示例
• 执行时间统计（如果历史记录中有可用）

示例输出格式：同上输出示例。

---

3. Visual Enhancements / 视觉增强

English
Use Textual/Rich formatting effectively:

Formatting Elements:

• Color‑coded category headers (green for query, yellow for edit, red for dangerous)
• Icons for quick visual identification (🔍, 📄, ✏️, ☢️, etc.)
• Collapsible sections for detailed parameter lists
• Syntax highlighting for XML examples
• Progress bars or charts for usage statistics

CSS/Styles:

.tools-category-header {
    background: $primary;
    color: white;
    padding: 1;
    font-weight: bold;
}

.tool-row {
    border-left: solid $accent;
    padding-left: 1;
    margin-bottom: 1;
}

.parameter-required {
    color: $warning;
    font-style: italic;
}

.parameter-optional {
    color: $text-muted;
}

.safety-safe {
    color: $success;
}

.safety-audit {
    color: $warning;
}

.safety-dangerous {
    color: $error;
}

有效使用 Textual/Rich 格式化：

格式化元素：

• 颜色编码的分类标题（绿色表示查询，黄色表示编辑，红色表示危险）
• 快速视觉识别的图标（🔍、📄、✏️、☢️等）
• 详细参数列表的可折叠部分
• XML 示例的语法高亮
• 使用统计的进度条或图表

CSS/样式示例：同上代码块。

---

4. Interactive Features / 交互式功能

Make the tool list interactive:

Features:

• Clickable tool names to expand/collapse details
• Search/filter functionality within the list
• Sorting by name, usage count, or category
• Double‑click to copy an XML template to the clipboard
• Show recent usage patterns

Implementation:

class ToolsCommand(Command):
    def execute(self, context: CommandContext) -> CommandResult:
        # Generate categorized, formatted output
        output = self._generate_rich_table(context.tool_registry)
        
        # If in TUI mode, add interactive widget
        if hasattr(context.console, 'mount'):
            widget = ToolsListWidget(output)
            context.console.mount(widget)
        else:
            context.console.print(output)
        
        return CommandResult(success=True)
    
    def _generate_rich_table(self, registry: ToolRegistry) -> str:
        """Generate rich formatted tool list"""
        # Implementation using Rich tables, panels, etc.
        pass

使工具列表具有交互性：

功能：

• 可点击的工具名称以展开/折叠详细信息
• 列表内的搜索/过滤功能
• 按名称、使用次数或类别排序
• 双击复制 XML 模板到剪贴板
• 显示最近的使用模式

实现示例：同上代码块。

---

5. Statistics Integration / 统计集成

Include real‑time usage statistics:

Statistics to Display:

• Total invocation count per tool
• Average execution time
• Success/failure rates
• Last used timestamp
• Common parameter combinations

Data Sources:

• Obtained from ToolResultCollection in ResultManager
• Aggregate across current session or all sessions
• Cache statistics to avoid performance impact

包含实时使用统计：

要显示的统计：

• 每个工具的总调用次数
• 平均执行时间
• 成功率/失败率
• 最近使用时间戳
• 常见的参数组合

数据源：

• 从 ResultManager 中的 ToolResultCollection 获取
• 跨当前会话或所有会话聚合
• 缓存统计以避免性能影响

---

6. Export Options / 导出选项

English
Allow users to export the tool list:

Export Formats:

• Markdown (for documentation)
• JSON (for programmatic use)
• Plain text (for quick reference)
• XML schema (for AI training)

Command Aliases:

/tools --markdown <path>  # Export as Markdown
/tools --json <path>      # Export as JSON
/tools --copy             # Copy to clipboard

允许用户导出工具列表：

导出格式：

• Markdown（用于文档）
• JSON（用于程序化使用）
• 纯文本（用于快速参考）
• XML 模式（用于 AI 训练）

命令别名：同上代码块。

---

实施计划 / Implementation Plan

Phase 1: Basic Enhancements / 基本增强

• Implement categorization grouping

• Add basic visual formatting

• Include required/optional parameter indicators

• 实现分类分组

• 添加基本视觉格式化

• 包含必需/可选参数指示器

Phase 2: Rich Formatting / 富格式化

• Add usage statistics

• Implement syntax highlighting for XML examples

• Create collapsible detail sections

• 添加使用统计

• 实现 XML 示例的语法高亮

• 创建可折叠的详细部分

Phase 3: Interactive Features / 交互式功能

• Add search and filter functionality

• Implement copy to clipboard

• Add sorting options

• 添加搜索和过滤功能

• 实现复制到剪贴板

• 添加排序选项

Phase 4: Advanced Features / 高级功能

• Export functionality

• Real‑time statistics updates

• Customizable themes

• 导出功能

• 实时更新统计

• 可自定义的主题

---

测试要求 / Testing Requirements

• Unit tests for categorization logic

• Integration tests for output formatting

• Accessibility tests for screen readers

• Performance tests with large tool sets

• Cross‑platform compatibility tests

• 分类逻辑的单元测试

• 输出格式化的集成测试

• 屏幕阅读器的可访问性测试

• 大型工具集的性能测试

• 跨平台兼容性测试

向后兼容性 / Backward Compatibility

English

• The existing /tools behavior is not maintained. The old, overly verbose output logic is completely deprecated.

中文

• 不保持现有 /tools 行为，完全弃用旧版过于繁琐的输出逻辑。