Add files via upload

2026-03-31 08:19:54 +02:00 · 2025-11-14 00:30:33 +08:00
parent a64834abb3
commit 5be865eb7d
2 changed files with 331 additions and 12 deletions
--- a/tools/README.md
+++ b/tools/README.md
@@ -6,20 +6,20 @@

 ## 配置文件格式

-每个工具配置文件是一个 YAML 文件，包含以下字段：
+每个工具配置文件是一个 YAML 文件。下表列出了当前支持的顶层字段及其必填情况，建议逐项核对后再提交：

-### 必需字段
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `name` | ✅ | string | 工具唯一标识，建议使用小写字母、数字、短横线组合。 |
+| `command` | ✅ | string | 实际执行的命令或脚本名称，需位于系统 PATH 或写入绝对路径。 |
+| `enabled` | ✅ | bool | 是否注册到 MCP；设为 `false` 时该工具会被忽略。 |
+| `description` | ✅ | string | 详细描述，支持多行 Markdown，供 AI 深度理解及 `resources/read` 查询。 |
+| `short_description` | 可选 | string | 20-50 字摘要，用于工具列表、减少 token 消耗；缺失时会自动截取 `description` 开头。 |
+| `args` | 可选 | string[] | 固定参数，按顺序 prepend 到命令行，常用于定义默认扫描模式。 |
+| `parameters` | 可选 | array | 运行时可配置参数列表，详见「参数定义」章节。 |
+| `arg_mapping` | 可选 | string | 参数映射模式（`auto`/`manual`/`template`），默认 `auto`；除非有特殊需求，无需填写。 |

- `name`: 工具名称（唯一标识符）
- `command`: 要执行的命令
- `enabled`: 是否启用（true/false）
-
-### 可选字段
-
- `args`: 固定参数列表（数组）
- `short_description`: 简短描述（一句话说明工具用途，用于工具列表，减少token消耗）
- `description`: 工具详细描述（支持多行文本，用于工具文档和详细说明）
- `parameters`: 参数定义列表
+> 若某字段填写错误或漏填必填项，系统会在加载时跳过该工具并在日志中输出警告，但不会影响其他工具。

 ## 工具描述

--- a/tools/README_EN.md
+++ b/tools/README_EN.md
@@ -0,0 +1,319 @@
+# Tool Configuration Guide
+
+## Overview
+
+Each tool ships with its own YAML configuration placed in the `tools/` directory. This keeps definitions modular, easier to review, and simple to extend. The runtime automatically loads every `.yaml` / `.yml` file in that directory.
+
+## File Structure
+
+The table below enumerates every supported top-level field. Double-check each entry before adding a new tool:
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `name` | ✅ | string | Unique identifier. Prefer lowercase letters, digits, and hyphens. |
+| `command` | ✅ | string | Executable or script name. Must exist in `$PATH` or be an absolute path. |
+| `enabled` | ✅ | bool | Controls MCP registration. Disabled tools are ignored by the loader. |
+| `description` | ✅ | string | Full Markdown description for MCP `resources/read` and AI comprehension. |
+| `short_description` | Optional | string | 20–50 character summary shown in tool lists. When omitted, the loader extracts the start of `description`. |
+| `args` | Optional | string[] | Static arguments prepended to every invocation—useful for default scan profiles. |
+| `parameters` | Optional | array | Runtime parameter definitions. See **Parameter Definition** for details. |
+| `arg_mapping` | Optional | string | Mapping strategy (`auto`/`manual`/`template`). Defaults to `auto`; override only for legacy tooling. |
+
+> If a required field is missing or malformed, the loader skips that tool and logs a warning without blocking the service.
+
+## Tool Descriptions
+
+### Short Description (`short_description`)
+
+- **Purpose**: compact summary for tool listings and to minimise language model context usage.  
+- **Guideline**: one concise sentence (20–50 Chinese characters or English equivalents).  
+- **Example**: `"Network scanner for discovering hosts, open ports, and services"`
+
+### Detailed Description (`description`)
+
+Supports multi-line Markdown. Recommended contents:
+
+1. **Capabilities** – what the tool does.  
+2. **Usage scenarios** – when to prefer this tool.  
+3. **Warnings** – permissions, runtime risks, side-effects.  
+4. **Examples** – optional walkthroughs or sample commands.
+
+**Important**:
+- Tool menus and MCP summaries use `short_description` when available.  
+- Without `short_description`, the loader trims the first line or first 100 characters of `description`.  
+- Full descriptions are accessible through the MCP `resources/read` endpoint (`tool://<tool_name>`).
+
+## Parameter Definition
+
+Each parameter object accepts the fields below:
+
+- `name` *(required)* – parameter key used in CLI construction and MCP schema.  
+- `type` *(required)* – `string`, `int`/`integer`, `bool`/`boolean`, `array`, etc.  
+- `description` *(required)* – Markdown-friendly explanation including purpose, format rules, example values, and safety notes.  
+- `required` – boolean; when `true`, missing values cause the executor to return an error.  
+- `default` – fallback value applied if the caller omits the argument.  
+- `flag` – CLI switch such as `-u` or `--url`.  
+- `position` – zero-based index for positional arguments.  
+- `format` – rendering strategy:
+  - `flag` *(default)* → `--flag value` / `-f value`
+  - `combined` → `--flag=value`
+  - `positional` → appended according to `position`
+  - `template` → uses the `template` string
+- `template` – placeholder string (supports `{flag}`, `{value}`, `{name}`) when `format: "template"`.
+- `options` – array of allowed values; surfaced as `enum` entries in the MCP schema.
+
+### Format Reference
+
+- **`flag`**: pass the flag and the value separately.  
+  Example: `flag: "-u"` → `-u https://example.com`
+
+- **`positional`**: insert according to `position`.  
+  Example: `position: 0` → becomes the first positional argument.
+
+- **`combined`**: join flag and value in one token.  
+  Example: `flag: "--level"`, `format: "combined"` → `--level=3`
+
+- **`template`**: custom rendering.  
+  Example: `template: "{flag} {value}"` → fully manual control.
+
+### Reserved Parameters
+
+- `additional_args` – allows users to append arbitrary CLI fragments. The executor tokenises the string (preserving quoted groups) and appends the resulting list to the command.  
+- `scan_type` – for scanners like `nmap`, replacing default scan switches (e.g., `-sV -sC`).  
+- `action` – consumed by server-side branching logic and intentionally not forwarded to the command line.
+
+## Parameter Description Checklist
+
+When documenting a parameter, include:
+
+1. **Purpose** – what the value controls.  
+2. **Format rules** – accepted patterns (URL, CIDR, path, etc.).  
+3. **Example values** – list several realistic samples.  
+4. **Notes** – permissions, performance impact, or other caveats.
+
+Suggested style: Markdown lists, bold emphasis for key cautions, and code blocks for complex examples.
+
+### Example
+
+```yaml
+description: |
+  Target IP address or domain. Accepts single IPs, ranges, CIDR blocks, or hostnames.
+
+  **Example values**
+  - Single IP: "192.168.1.1"
+  - Range: "192.168.1.1-100"
+  - CIDR: "192.168.1.0/24"
+  - Domain: "example.com"
+
+  **Notes**
+  - Required; cannot be empty.
+  - Validate address format before running to avoid false positives.
+```
+
+## Parameter Types
+
+### Boolean
+- `true` → adds only the flag (no value).  
+- `false` → suppresses the flag.  
+- Accepts `true`/`false`, `1`/`0`, and `"true"`/`"false"`.
+
+```yaml
+- name: "verbose"
+  type: "bool"
+  description: "Enable verbose output"
+  required: false
+  default: false
+  flag: "-v"
+  format: "flag"
+```
+
+### String
+Most common parameter type; accepts any string value.
+
+### Integer
+Use for numeric inputs (ports, levels, limits).
+
+```yaml
+- name: "level"
+  type: "int"
+  description: "Level of detail, 1-5"
+  required: false
+  default: 3
+  flag: "--level"
+  format: "combined"  # --level=3
+```
+
+### Array
+Automatically converted to a comma-separated string.
+
+```yaml
+- name: "ports"
+  type: "array"
+  description: "List of ports to scan"
+  required: false
+  # Input: [80, 443, 8080]
+  # Output: "80,443,8080"
+```
+
+## Special Parameters
+
+### `additional_args`
+
+```yaml
+- name: "additional_args"
+  type: "string"
+  description: "Extra CLI arguments; separate multiple options with spaces"
+  required: false
+  format: "positional"
+```
+
+Examples:
+- `additional_args: "--script vuln -O"` → `["--script", "vuln", "-O"]`
+- `additional_args: "-T4 --max-retries 3"` → `["-T4", "--max-retries", "3"]`
+
+Notes:
+- Quoted strings are preserved.  
+- Validate user input to avoid command injection.  
+- Appended at the end of the final command.
+
+### `scan_type`
+
+```yaml
+- name: "scan_type"
+  type: "string"
+  description: "Overrides default scan switches"
+  required: false
+  format: "positional"
+```
+
+Examples:
+- `scan_type: "-sV -sC"`  
+- `scan_type: "-A"`
+
+Notes:
+- Replaces default entries in the tool’s `args` list.  
+- Separate multiple flags with spaces.
+
+## Complete Example (`nmap`)
+
+```yaml
+name: "nmap"
+command: "nmap"
+args: ["-sT", "-sV", "-sC"]
+enabled: true
+
+short_description: "Network scanner for discovering hosts, open ports, and services"
+
+description: |
+  Network mapping and port scanning utility.
+
+  **Highlights**
+  - Host discovery
+  - Port scanning
+  - Service identification
+  - OS fingerprinting
+  - NSE-based vulnerability checks
+
+parameters:
+  - name: "target"
+    type: "string"
+    description: "Target IP or domain"
+    required: true
+    position: 0
+    format: "positional"
+
+  - name: "ports"
+    type: "string"
+    description: "Port range, e.g., 1-1000"
+    required: false
+    flag: "-p"
+    format: "flag"
+
+  - name: "scan_type"
+    type: "string"
+    description: "Override scan switches, e.g., '-sV -sC'"
+    required: false
+    format: "positional"
+
+  - name: "additional_args"
+    type: "string"
+    description: "Extra nmap arguments, e.g., '--script vuln -O'"
+    required: false
+    format: "positional"
+```
+
+## Adding a New Tool
+
+1. Create a YAML file in `tools/` (e.g., `tools/mytool.yaml`).  
+2. Fill out the top-level fields and parameter list.  
+3. Provide defaults and rich descriptions wherever possible.  
+4. Run `go run cmd/test-config/main.go` to validate the configuration.  
+5. Restart the service (or trigger a reload) so the UI and MCP registry pick up the change.
+
+### Template
+
+```yaml
+name: "tool_name"
+command: "command"
+enabled: true
+
+short_description: "One-line summary"
+
+description: |
+  Detailed description with Markdown formatting.
+
+parameters:
+  - name: "target"
+    type: "string"
+    description: "Explain the expected value, format, examples, and caveats"
+    required: true
+    position: 0
+    format: "positional"
+
+  - name: "option"
+    type: "string"
+    description: "Optional flag parameter"
+    required: false
+    flag: "--option"
+    format: "flag"
+
+  - name: "verbose"
+    type: "bool"
+    description: "Enable verbose mode"
+    required: false
+    default: false
+    flag: "-v"
+    format: "flag"
+
+  - name: "additional_args"
+    type: "string"
+    description: "Extra CLI options separated by spaces"
+    required: false
+    format: "positional"
+```
+
+## Validation & Troubleshooting
+
+- ✅ Verify required fields: `name`, `command`, `enabled`, `description`.  
+- ✅ Ensure parameter definitions use supported types and formats.  
+- ✅ Watch server logs for warnings when a tool fails to load.  
+- ✅ Use `go run cmd/test-config/main.go` to inspect parsed tool metadata.
+
+## Best Practices
+
+1. **Parameter design** – expose common flags individually; leverage `additional_args` for advanced scenarios.  
+2. **Documentation** – combine `short_description` with thorough `description` to balance brevity and clarity.  
+3. **Defaults** – provide sensible `default` values, especially for frequently used options.  
+4. **Validation prompts** – describe expected formats and highlight constraints to help the AI and users avoid mistakes.  
+5. **Safety** – warn about privileged commands, destructive actions, or high-impact scans.
+
+## Disabling a Tool
+
+Set `enabled: false` or remove/rename the YAML file. Disabled tools disappear from the UI and MCP inventory.
+
+## Related Documents
+
+- Main project README: `../README.md`  
+- Tool list samples: `tools/*.yaml`  
+- API overview: see the main README
+