certd/.trae/skills/plugin-converter/SKILL.md

插件转换工具技能

什么是插件转换工具

插件转换工具是一个用于将 Certd 插件转换为 YAML 配置文件的命令行工具。它可以分析单个插件文件，识别插件类型，并生成对应的 YAML 配置，可以让插件分发和在线注册。

工具位置

trae/skills/convert-plugin-to-yaml.js

功能特性

• 单个插件转换：支持指定单个插件文件进行转换，而不是扫描整个目录
• 自动类型识别：自动识别插件类型（Access、Task、DNS Provider、Notification、Addon）
• 详细日志输出：提供详细的转换过程日志，便于调试
• YAML 配置生成：生成标准的 YAML 配置文件
• 配置文件保存：自动将生成的配置保存到 ./metadata 目录
• 可复用函数：导出了可复用的函数，便于其他模块调用

使用方法

基本用法

node trae/skills/convert-plugin-to-yaml.js <插件文件路径>

示例

# 转换 Access 插件
node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/access.js

# 转换 Task 插件
node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js

# 转换 DNS Provider 插件
node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/dns-provider.js

转换过程

1. 加载插件模块：使用 import() 动态加载指定的插件文件
2. 分析插件定义：检查模块导出的对象，寻找带有 define 属性的插件
3. 识别插件类型：根据插件的继承关系或属性识别插件类型
4. 生成 YAML 配置：基于插件定义生成标准的 YAML 配置
5. 保存配置文件：将生成的配置保存到 ./metadata 目录

输出说明

命令行输出

执行转换命令后，工具会输出以下信息：

• 插件加载状态
• 插件导出的对象列表
• 插件类型识别结果
• 生成的 YAML 配置内容
• 配置文件保存路径

配置文件命名规则

生成的配置文件命名规则为：

<插件类型>[_<子类型>]_<插件名称>.yaml

例如：

• access_demo.yaml（Access 插件）
• deploy_DemoTest.yaml（Task 插件）
• dnsProvider_demo.yaml（DNS Provider 插件）

插件类型识别逻辑

工具通过以下逻辑识别插件类型：

1. DNS Provider：如果插件定义中包含 accessType 属性
2. Task：如果插件继承自 AbstractTaskPlugin
3. Notification：如果插件继承自 BaseNotification
4. Access：如果插件继承自 BaseAccess
5. Addon：如果插件继承自 BaseAddon

注意事项

1. 文件路径：插件文件路径可以是相对路径或绝对路径
2. 文件格式：仅支持 .js 文件，不支持 .ts 文件（需要先编译）
3. 依赖安装：执行前确保已安装所有必要的依赖
4. 配置目录：如果 ./metadata 目录不存在，工具会自动创建
5. 错误处理：如果插件加载失败或识别失败，工具会输出错误信息但不会终止执行

代码结构

主要函数

1. isPrototypeOf(value, cls)：检查对象是否是指定类的原型
2. loadSingleModule(filePath)：加载单个插件模块
3. convertSinglePlugin(pluginPath)：分析单个插件并生成 YAML 配置
4. main()：主函数，处理命令行参数并执行转换

导出函数

工具导出了以下函数，便于其他模块调用：

export {
  convertSinglePlugin,  // 转换单个插件
  loadSingleModule,     // 加载单个模块
  isPrototypeOf         // 检查原型关系
};

应用场景

1. 插件开发：在开发新插件时，快速生成配置文件
2. 插件调试：查看插件的内部定义和配置
3. 插件管理：批量转换现有插件为标准配置格式
4. 自动化构建：集成到构建流程中，自动生成插件配置

示例输出

转换 Access 插件示例

$ node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/access.js
开始转换插件: packages/ui/certd-server/src/plugins/plugin-demo/access.js
插件模块导出了 1 个对象: DemoAccess
处理插件: DemoAccess
插件类型: access
脚本路径: packages/ui/certd-server/src/plugins/plugin-demo/access.js

生成的 YAML 配置:
name: demo
title: 授权插件示例
desc: 这是一个示例授权插件，用于演示如何实现一个授权插件
icon: clarity:plugin-line
pluginType: access
type: builtIn
scriptFilePath: packages/ui/certd-server/src/plugins/plugin-demo/access.js

YAML 配置已保存到: ./metadata/access_demo.yaml
插件转换完成!

转换 Task 插件示例

$ node trae/skills/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js
开始转换插件: packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js
插件模块导出了 1 个对象: DemoTest
处理插件: DemoTest
插件类型: deploy
脚本路径: packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js

生成的 YAML 配置:
name: DemoTest
title: Demo-测试插件
desc: ""
icon: clarity:plugin-line
group: other
default:
  strategy:
    runStrategy: SkipWhenSucceed
pluginType: deploy
type: builtIn
scriptFilePath: packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js

YAML 配置已保存到: ./metadata/deploy_DemoTest.yaml
插件转换完成!

故障排除

常见问题

1. 模块加载失败

   • 原因：插件文件依赖未安装或路径错误
   • 解决：确保已安装所有依赖，检查文件路径是否正确

2. 插件类型识别失败

   • 原因：插件未正确继承基类或缺少必要的属性
   • 解决：检查插件代码，确保正确继承对应的基类

3. YAML 配置生成失败

   • 原因：插件定义格式不正确
   • 解决：检查插件的 define 属性格式是否正确

4. 配置文件保存失败

   • 原因：权限不足或磁盘空间不足
   • 解决：确保有足够的权限和磁盘空间

调试建议

• 查看详细日志：工具会输出详细的转换过程日志，仔细查看日志信息
• 检查插件代码：确保插件代码符合 Certd 插件开发规范
• 尝试简化插件：如果转换失败，尝试创建一个最小化的插件示例进行测试
• 检查依赖版本：确保使用的依赖版本与 Certd 兼容

总结

插件转换工具是一个方便实用的工具，它可以帮助开发者快速生成插件的 YAML 配置文件，简化插件的注册和管理过程。通过命令行参数指定单个插件文件，工具会自动完成类型识别、配置生成和保存等操作，大大提高了插件开发和管理的效率。