enhance-plugins

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

enhance-plugins

插件增强分析

Analyze plugin structures, MCP tools, and security patterns against best practices.

对照最佳实践分析插件结构、MCP工具及安全模式。

Parse Arguments

解析参数

javascript

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');

javascript

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');

Plugin Locations

插件位置

Platform	Location
Claude Code	`plugins/*/` , `.claude-plugin/plugin.json`
OpenCode	`.opencode/plugins/` , MCP in `opencode.json`
Codex	MCP in `~/.codex/config.toml`

平台	路径位置
Claude Code	`plugins/*/` , `.claude-plugin/plugin.json`
OpenCode	`.opencode/plugins/` , MCP in `opencode.json`
Codex	MCP in `~/.codex/config.toml`

Workflow

工作流程

Discover - Find plugins in
```
plugins/
```
directory
Load - Read
```
plugin.json
```
, agents, commands, skills
Analyze - Run pattern checks by certainty level
Report - Generate markdown output
Fix - Apply auto-fixes if
```
--fix
```
(HIGH certainty only)

发现 - 在
```
plugins/
```
目录中查找插件
加载 - 读取
```
plugin.json
```
、agents、commands、skills
分析 - 按确定性级别运行模式检查
报告 - 生成Markdown格式的输出报告
修复 - 如果使用
```
--fix
```
参数，自动修复仅HIGH确定性的问题

Detection Patterns

检测模式

1. Tool Schema Design (HIGH)

1. 工具Schema设计（HIGH）

Based on function calling best practices:

Required elements:

json

{
  "name": "verb_noun",
  "description": "What it does. When to use. What it returns.",
  "input_schema": {
    "type": "object",
    "properties": {
      "param": {
        "type": "string",
        "description": "Format and example"
      }
    },
    "required": ["param"],
    "additionalProperties": false
  }
}

The "Intern Test" - Can someone use this tool given only the description?

Issue	Certainty	Auto-Fix
Missing `additionalProperties: false`	HIGH	Yes
Missing `required` array	HIGH	Yes
Missing tool description	HIGH	No
Missing param descriptions	MEDIUM	No
Vague names ( `search` , `process` )	MEDIUM	No

基于函数调用最佳实践：

必填元素：

json

{
  "name": "verb_noun",
  "description": "What it does. When to use. What it returns.",
  "input_schema": {
    "type": "object",
    "properties": {
      "param": {
        "type": "string",
        "description": "Format and example"
      }
    },
    "required": ["param"],
    "additionalProperties": false
  }
}

「实习生测试」 - 仅通过描述，新手能否使用该工具？

问题	确定性	自动修复
缺失 `additionalProperties: false`	HIGH	是
缺失 `required` 数组	HIGH	是
缺失工具描述	HIGH	否
缺失参数描述	MEDIUM	否
模糊命名（如 `search` 、 `process` ）	MEDIUM	否

2. Description Quality (HIGH)

2. 描述质量（HIGH）

Tool descriptions must include:

What the function does
When to use it (trigger context)
What it returns

json

// Bad - vague
"description": "Search for things"

// Good - complete
"description": "Search product catalog by keyword. Use for inventory queries or price checks. Returns matching products with prices."

Parameter descriptions must include:

Format expectations
Example values
Relationships to other params

json

// Bad
"query": { "type": "string" }

// Good
"query": {
  "type": "string",
  "description": "Search keywords. Supports AND/OR. Example: 'laptop AND gaming'"
}

工具描述必须包含：

函数功能
使用场景（触发上下文）
返回结果

json

// 不佳 - 模糊
"description": "Search for things"

// 良好 - 完整
"description": "Search product catalog by keyword. Use for inventory queries or price checks. Returns matching products with prices."

参数描述必须包含：

格式要求
示例值
与其他参数的关系

json

// 不佳
"query": { "type": "string" }

// 良好
"query": {
  "type": "string",
  "description": "Search keywords. Supports AND/OR. Example: 'laptop AND gaming'"
}

3. Schema Structure (MEDIUM)

3. Schema结构（MEDIUM）

Issue	Why It Matters
Deep nesting (>2 levels)	Reduces generation quality
Missing enums for constrained values	Allows invalid states
No min/max on numbers	Unbounded inputs
>20 tools per plugin	Increases error rates

Prefer flat structures:

json

// Bad - nested
{ "config": { "settings": { "timeout": 30 } } }

// Good - flat
{ "timeout_seconds": 30 }

问题	影响原因
深层嵌套（超过2级）	降低生成质量
约束值缺失枚举	允许无效状态
数值类型未设置min/max	输入无边界
单个插件包含超过20个工具	增加错误率

推荐扁平结构：

json

// 不佳 - 嵌套
{ "config": { "settings": { "timeout": 30 } } }

// 良好 - 扁平
{ "timeout_seconds": 30 }

4. Plugin Structure (HIGH)

4. 插件结构（HIGH）

Required files:

plugin-name/
├── .claude-plugin/
│   └── plugin.json      # name, version, description
├── commands/            # User-invokable commands
├── agents/              # Subagent definitions
├── skills/              # Reusable skill implementations
└── package.json         # Optional, for npm plugins

plugin.json validation:

```
name
```
: lowercase, kebab-case
```
version
```
: semver format (
```
^\d+\.\d+\.\d+$
```
)
```
description
```
: explains what plugin provides

Version sync: plugin.json version must match package.json if present.

必填文件：

plugin-name/
├── .claude-plugin/
│   └── plugin.json      # 名称、版本、描述
├── commands/            # 用户可调用的命令
├── agents/              # 子Agent定义
├── skills/              # 可复用Skill实现
└── package.json         # 可选，适用于npm插件

plugin.json验证规则：

```
name
```
：小写，短横线分隔式（kebab-case）
```
version
```
：语义化版本格式（
```
^\d+\.\d+\.\d+$
```
）
```
description
```
：说明插件提供的功能

版本同步： 若存在package.json，plugin.json中的版本必须与其保持一致。

5. MCP Server Patterns (MEDIUM)

5. MCP服务模式（MEDIUM）

For plugins exposing MCP tools:

Transport types:

```
stdio
```
- Standard I/O (most common)
```
http
```
- HTTP/SSE transport

Configuration:

json

{
  "mcp": {
    "server-name": {
      "type": "local",
      "command": ["node", "path/to/server.js"],
      "environment": { "KEY": "value" },
      "enabled": true
    }
  }
}

Security principles:

User consent for data access
No transmission without approval
Tool descriptions are untrusted input

针对暴露MCP工具的插件：

传输类型：

```
stdio
```
- 标准输入输出（最常见）
```
http
```
- HTTP/SSE传输

配置示例：

json

{
  "mcp": {
    "server-name": {
      "type": "local",
      "command": ["node", "path/to/server.js"],
      "environment": { "KEY": "value" },
      "enabled": true
    }
  }
}

安全原则：

数据访问需用户同意
未经批准不得传输数据
工具描述属于不可信输入

6. Security Patterns (HIGH)

6. 安全模式（HIGH）

HIGH Certainty issues:

Pattern	Risk	Detection
Unrestricted `Bash`	Command execution	`tools:.*Bash[^(]`
Command injection	Shell escape	`\${.*}` in commands
Path traversal	File access	`\.\.\/` in paths
Hardcoded secrets	Credential leak	API keys, passwords

MEDIUM Certainty issues:

Pattern	Risk
Broad file access	Data exfiltration
Missing input validation	Injection attacks
No timeout on tools	Resource exhaustion

Input validation required:

javascript

// Validate before execution
function validateToolInput(params, schema) {
  // Type validation
  // Range validation (min/max)
  // Enum validation
  // Format validation (regex patterns)
}

高确定性问题：

模式	风险	检测方式
无限制的 `Bash` 工具	命令执行风险	`tools:.*Bash[^(]`
命令注入	Shell逃逸漏洞	命令中包含 `\${.*}`
路径遍历	文件访问风险	路径中包含 `\.\.\/`
硬编码密钥	凭证泄露	API密钥、密码等

中确定性问题：

模式	风险
宽泛的文件访问权限	数据泄露
缺失输入验证	注入攻击
工具未设置超时	资源耗尽

必须进行输入验证：

javascript

// 执行前验证
function validateToolInput(params, schema) {
  // 类型验证
  // 范围验证（min/max）
  // 枚举验证
  // 格式验证（正则表达式）
}

7. Error Handling (MEDIUM)

7. 错误处理（MEDIUM）

Tools should return structured errors:

json

{
  "type": "tool_result",
  "tool_use_id": "id",
  "content": "Error: [TYPE]. [WHAT]. [SUGGESTION].",
  "is_error": true
}

Retry guidance:

Transient (429, 503): exponential backoff
Validation (400): no retry, return error
Timeout: configurable, default 30s

工具应返回结构化错误：

json

{
  "type": "tool_result",
  "tool_use_id": "id",
  "content": "Error: [TYPE]. [WHAT]. [SUGGESTION].",
  "is_error": true
}

重试指导：

临时错误（429、503）：指数退避重试
验证错误（400）：不重试，直接返回错误
超时：可配置，默认30秒

8. Tool Count (LOW)

8. 工具数量（LOW）

"Less-is-More" approach:

Research shows reducing tools improves accuracy by up to 89%
Limit to 3-5 relevant tools per task context
Consider dynamic tool loading for large toolsets

「少即是多」原则：

研究表明，减少工具数量可将准确率提升高达89%
每个任务上下文限制为3-5个相关工具
对于大型工具集，考虑动态加载工具

Auto-Fixes

自动修复项

Issue	Fix
Missing `additionalProperties`	Add `"additionalProperties": false`
Missing `required`	Add all properties to required array
Version mismatch	Sync plugin.json with package.json

问题	修复方式
缺失 `additionalProperties`	添加 `"additionalProperties": false`
缺失 `required` 数组	将所有属性添加至required数组
版本不匹配	同步plugin.json与package.json的版本

Output Format

输出格式

markdown

undefined

markdown

undefined

Plugin Analysis: {name}

插件分析报告：{name}

Files scanned: {count}

Certainty	Count
HIGH	{n}
MEDIUM	{n}

扫描文件数：{count}

确定性	数量
HIGH	{n}
MEDIUM	{n}

Tool Schema Issues

工具Schema问题

| 工具 | 问题 | 修复方案 | 确定性 |

Structure Issues

结构问题

| File | Issue | Certainty |

| 文件 | 问题 | 确定性 |

Security Issues

安全问题

undefined

| 文件 | 行号 | 问题 | 确定性 |

undefined

Pattern Statistics

模式统计

Category	Patterns	Certainty
Tool Schema	5	HIGH
Descriptions	2	HIGH
Schema Structure	4	MEDIUM
Plugin Structure	3	HIGH
MCP Patterns	2	MEDIUM
Security	6	HIGH/MEDIUM
Error Handling	2	MEDIUM
Tool Count	1	LOW
Total	25	-

分类	模式数量	确定性
工具Schema	5	HIGH
描述质量	2	HIGH
Schema结构	4	MEDIUM
插件结构	3	HIGH
MCP模式	2	MEDIUM
安全	6	HIGH/MEDIUM
错误处理	2	MEDIUM
工具数量	1	LOW
总计	25	-

Schema Strictness

Schema严格性

<bad_example>

json

{
  "properties": { "path": { "type": "string" } }
}

</bad_example> <good_example>

json

{
  "properties": { "path": { "type": "string", "description": "File path" } },
  "required": ["path"],
  "additionalProperties": false
}

</good_example>

<bad_example>

json

{
  "properties": { "path": { "type": "string" } }
}

</bad_example> <good_example>

json

{
  "properties": { "path": { "type": "string", "description": "File path" } },
  "required": ["path"],
  "additionalProperties": false
}

</good_example>

Tool Description

工具描述

<bad_example>

json

"description": "Search for things"

</bad_example> <good_example>

json

"description": "Search product catalog by keyword. Use for inventory or price queries. Returns products with prices."

</good_example>

<bad_example>

json

"description": "Search for things"

</bad_example> <good_example>

json

"description": "Search product catalog by keyword. Use for inventory or price queries. Returns products with prices."

</good_example>

Security

安全

<bad_example>

yaml

tools: Read, Bash  # Unrestricted

</bad_example> <good_example>

yaml

tools: Read, Bash(git:*)  # Scoped

</good_example> </examples>

<bad_example>

yaml

tools: Read, Bash  # 无限制

</bad_example> <good_example>

yaml

tools: Read, Bash(git:*)  # 范围限制

</good_example> </examples>

References

参考文档

agent-docs/FUNCTION-CALLING-TOOL-USE-REFERENCE.md

- Tool schema, descriptions, security

```
agent-docs/CLAUDE-CODE-REFERENCE.md
```
- Plugin structure, MCP config
```
agent-docs/OPENCODE-REFERENCE.md
```
- OpenCode MCP integration
```
agent-docs/CODEX-REFERENCE.md
```
- Codex MCP config

agent-docs/FUNCTION-CALLING-TOOL-USE-REFERENCE.md

- 工具Schema、描述、安全相关内容

```
agent-docs/CLAUDE-CODE-REFERENCE.md
```
- 插件结构、MCP配置
```
agent-docs/OPENCODE-REFERENCE.md
```
- OpenCode MCP集成
```
agent-docs/CODEX-REFERENCE.md
```
- Codex MCP配置

Constraints

约束条件

Auto-fix only HIGH certainty issues
Security warnings are advisory - do not auto-fix
Preserve existing plugin.json fields
Never modify tool behavior, only schema definitions

仅自动修复高确定性问题
安全警告仅作提示 - 不自动修复
保留现有plugin.json字段
仅修改Schema定义，绝不改变工具行为