enhance-plugins

enhance-plugins

依据最佳实践分析插件结构、MCP 工具和安全模式。

解析参数

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

插件位置

平台	位置
Claude Code	plugins/*/、.claude-plugin/plugin.json
OpenCode	.opencode/plugins/、opencode.json 中的 MCP
Codex	~/.codex/config.toml 中的 MCP

工作流

1. 发现 - 在 plugins/ 目录中查找插件
2. 加载 - 读取 plugin.json、Agent、命令和技能
3. 分析 - 按确定性等级运行模式检查
4. 报告 - 生成 Markdown 输出
5. 修复 - 如果指定 --fix，则应用自动修复（仅限高确定性问题）

检测模式

1. 工具 Schema 设计（高确定性）

基于函数调用最佳实践：

必需元素：

{
  "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	高	是
缺少 required 数组	高	是
缺少工具描述	高	否
缺少参数描述	中	否
名称含糊（search、process）	中	否

2. 描述质量（高确定性）

工具描述必须包含：

• 函数的作用
• 何时使用（触发上下文）
• 返回内容

// 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."

参数描述必须包含：

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

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

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

3. Schema 结构（中确定性）

问题	重要性
嵌套过深（超过 2 层）	降低生成质量
受限值缺少枚举	允许无效状态
数字未设置最小值/最大值	输入不受限制
每个插件的工具超过 20 个	增加错误率

优先采用扁平结构：

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

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

4. 插件结构（高确定性）

必需文件：

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 验证：

• name：小写、kebab-case
• version：semver 格式（^\d+\.\d+\.\d+$）
• description：说明插件提供的功能

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

5. MCP 服务模式（中确定性）

对于提供 MCP 工具的插件：

传输类型：

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

配置：

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

安全原则：

• 访问数据须征得用户同意
• 未经批准不得传输数据
• 工具描述是不可信输入

6. 安全模式（高确定性）

高确定性问题：

模式	风险	检测方式
不受限制的 Bash	命令执行	tools:.*Bash[^(]
命令注入	Shell 转义	命令中出现 \${.*}
路径遍历	文件访问	路径中出现 \.\.\/
硬编码密钥	凭据泄露	API 密钥、密码

中确定性问题：

模式	风险
文件访问范围过宽	数据外泄
缺少输入验证	注入攻击
工具没有超时设置	资源耗尽

必须进行输入验证：

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

7. 错误处理（中确定性）

工具应返回结构化错误：

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

重试建议：

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

8. 工具数量（低确定性）

“少即是多”方法：

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

自动修复

问题	修复
缺少 additionalProperties	添加 "additionalProperties": false
缺少 required	将所有属性添加到 required 数组
版本不匹配	将 plugin.json 与 package.json 同步

输出格式

## Plugin Analysis: {name}

**Files scanned**: {count}

| Certainty | Count |
|-----------|-------|
| HIGH | {n} |
| MEDIUM | {n} |

### Tool Schema Issues
| Tool | Issue | Fix | Certainty |

### Structure Issues
| File | Issue | Certainty |

### Security Issues
| File | Line | Issue | Certainty |

模式统计

类别	模式	确定性
工具 Schema	5	高
描述	2	高
Schema 结构	4	中
插件结构	3	高
MCP 模式	2	中
安全性	6	高/中
错误处理	2	中
工具数量	1	低
总计	25	-

### Schema 严格性 ```json { "properties": { "path": { "type": "string" } } } ``` ```json { "properties": { "path": { "type": "string", "description": "File path" } }, "required": ["path"], "additionalProperties": false } ```

工具描述

<bad_example>

"description": "Search for things"

</bad_example> <good_example>

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

</good_example>

安全性

<bad_example>

tools: Read, Bash  # Unrestricted

</bad_example> <good_example>

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

</good_example>

参考资料

• 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 配置

约束

• 仅自动修复确定性为高的问题
• 安全警告仅供参考，不要自动修复
• 保留现有的 plugin.json 字段
• 绝不修改工具行为，只修改 Schema 定义