diff --git a/.trae/skills/access-plugin-dev/SKILL.md b/.trae/skills/access-plugin-dev/SKILL.md new file mode 100644 index 000000000..35742f1d7 --- /dev/null +++ b/.trae/skills/access-plugin-dev/SKILL.md @@ -0,0 +1,301 @@ +# Access 插件开发技能 + +## 什么是 Access 插件 + +Access 插件是 Certd 系统中用于存储用户第三方应用授权数据的插件,例如用户名密码、accessSecret 或 accessToken 等。同时,它还负责对接实现第三方的 API 接口,供其他插件调用使用。 + +## 开发步骤 + +### 1. 导入必要的依赖 + +```typescript +import { AccessInput, BaseAccess, IsAccess, Pager, PageRes, PageSearch } from '@certd/pipeline'; +import { DomainRecord } from '@certd/plugin-lib'; +``` + +### 2. 使用 @IsAccess 注解注册插件 + +```typescript +@IsAccess({ + name: 'demo', // 插件唯一标识 + title: '授权插件示例', // 插件标题 + icon: 'clarity:plugin-line', // 插件图标 + desc: '这是一个示例授权插件,用于演示如何实现一个授权插件', // 插件描述 +}) +export class DemoAccess extends BaseAccess { + // 插件实现... +} +``` + +### 3. 定义授权属性 + +使用 `@AccessInput` 注解定义授权属性: + +```typescript +@AccessInput({ + title: '授权方式', + value: 'apiKey', // 默认值 + component: { + name: "a-select", // 基于 antdv 的输入组件 + vModel: "value", // v-model 绑定的属性名 + options: [ // 组件参数 + { label: "API密钥(推荐)", value: "apiKey" }, + { label: "账号密码", value: "account" }, + ], + placeholder: 'demoKeyId', + }, + required: true, +}) +apiType = ''; + +@AccessInput({ + title: '密钥Id', + component: { + name:"a-input", + allowClear: true, + placeholder: 'demoKeyId', + }, + required: true, +}) +demoKeyId = ''; + +@AccessInput({ + title: '密钥',//标题 + required: true, //text组件可以省略 + encrypt: true, //该属性是否需要加密 +}) +demoKeySecret = ''; +``` + +### 4. 实现测试方法 + +```typescript +@AccessInput({ + title: "测试", + component: { + name: "api-test", + action: "TestRequest" + }, + helper: "点击测试接口是否正常" +}) +testRequest = true; + +/** + * 会通过上面的testRequest参数在ui界面上生成测试按钮,供用户测试接口调用是否正常 + */ +async onTestRequest() { + await this.GetDomainList({}); + return "ok" +} +``` + +### 5. 实现 API 方法 + +```typescript +/** + * 获api接口示例 取域名列表, + */ +async GetDomainList(req: PageSearch): Promise> { + //输出日志必须使用ctx.logger + this.ctx.logger.info(`获取域名列表,req:${JSON.stringify(req)}`); + const pager = new Pager(req); + const resp = await this.doRequest({ + action: "ListDomains", + data: { + domain: req.searchKey, + offset: pager.getOffset(), + limit: pager.pageSize, + } + }); + const total = resp?.TotalCount || 0; + let list = resp?.DomainList?.map((item) => { + item.domain = item.Domain; + item.id = item.DomainId; + return item; + }) + return { + total, + list + }; +} + +/** + * 通用api调用方法, 具体如何构造请求体,需参考对应应用的API文档 + */ +async doRequest(req: { action: string, data?: any }) { + /** + this.ctx中包含很多有用的工具类 + type AccessContext = { + http: HttpClient; + logger: ILogger; + utils: typeof utils; + accessService: IAccessService; + } + */ + const res = await this.ctx.http.request({ + url: "https://api.demo.cn/api/", + method: "POST", + data: { + Action: req.action, + Body: req.data + } + }); + + if (res.Code !== 0) { + //异常处理 + throw new Error(res.Message || "请求失败"); + } + return res.Resp; +} +``` + +## 注意事项 + +1. **插件命名**:插件名称应简洁明了,反映其功能。 +2. **属性加密**:对于敏感信息(如密钥),应设置 `encrypt: true`。 +3. **日志输出**:必须使用 `this.ctx.logger` 输出日志,而不是 `console`。 +4. **错误处理**:API 调用失败时应抛出明确的错误信息。 +5. **测试方法**:实现 `onTestRequest` 方法,以便用户可以测试授权是否正常。 + +## 完整示例 + +```typescript +import { AccessInput, BaseAccess, IsAccess, Pager, PageRes, PageSearch } from '@certd/pipeline'; +import { DomainRecord } from '@certd/plugin-lib'; + +/** + * 这个注解将注册一个授权配置 + * 在certd的后台管理系统中,用户可以选择添加此类型的授权 + */ +@IsAccess({ + name: 'demo', + title: '授权插件示例', + icon: 'clarity:plugin-line', //插件图标 + desc: '这是一个示例授权插件,用于演示如何实现一个授权插件', +}) +export class DemoAccess extends BaseAccess { + + /** + * 授权属性配置 + */ + @AccessInput({ + title: '授权方式', + value: 'apiKey', //默认值 + component: { + name: "a-select", //基于antdv的输入组件 + vModel: "value", // v-model绑定的属性名 + options: [ //组件参数 + { + label: "API密钥(推荐)", + value: "apiKey" + }, + { + label: "账号密码", + value: "account" + }, + ], + placeholder: 'demoKeyId', + }, + required: true, + }) + apiType = ''; + + /** + * 授权属性配置 + */ + @AccessInput({ + title: '密钥Id', + component: { + name:"a-input", + allowClear: true, + placeholder: 'demoKeyId', + }, + required: true, + }) + demoKeyId = ''; + + @AccessInput({ + title: '密钥',//标题 + required: true, //text组件可以省略 + encrypt: true, //该属性是否需要加密 + }) + demoKeySecret = ''; + + + @AccessInput({ + title: "测试", + component: { + name: "api-test", + action: "TestRequest" + }, + helper: "点击测试接口是否正常" + }) + testRequest = true; + + /** + * 会通过上面的testRequest参数在ui界面上生成测试按钮,供用户测试接口调用是否正常 + */ + async onTestRequest() { + await this.GetDomainList({}); + return "ok" + } + + /** + * 获api接口示例 取域名列表, + */ + async GetDomainList(req: PageSearch): Promise> { + //输出日志必须使用ctx.logger + this.ctx.logger.info(`获取域名列表,req:${JSON.stringify(req)}`); + const pager = new Pager(req); + const resp = await this.doRequest({ + action: "ListDomains", + data: { + domain: req.searchKey, + offset: pager.getOffset(), + limit: pager.pageSize, + } + }); + const total = resp?.TotalCount || 0; + let list = resp?.DomainList?.map((item) => { + item.domain = item.Domain; + item.id = item.DomainId; + return item; + }) + return { + total, + list + }; + } + + // 还可以继续编写API + + /** + * 通用api调用方法, 具体如何构造请求体,需参考对应应用的API文档 + */ + async doRequest(req: { action: string, data?: any }) { + /** + this.ctx中包含很多有用的工具类 + type AccessContext = { + http: HttpClient; + logger: ILogger; + utils: typeof utils; + accessService: IAccessService; + } + */ + const res = await this.ctx.http.request({ + url: "https://api.demo.cn/api/", + method: "POST", + data: { + Action: req.action, + Body: req.data + } + }); + + if (res.Code !== 0) { + //异常处理 + throw new Error(res.Message || "请求失败"); + } + return res.Resp; + } +} +``` \ No newline at end of file diff --git a/.trae/skills/access-plugin-dev/examples/input.md b/.trae/skills/access-plugin-dev/examples/input.md new file mode 100644 index 000000000..c3540a858 --- /dev/null +++ b/.trae/skills/access-plugin-dev/examples/input.md @@ -0,0 +1 @@ +我需要开发一个 Access 插件,用于存储和管理第三方应用的授权信息。请指导我如何实现。 \ No newline at end of file diff --git a/.trae/skills/access-plugin-dev/examples/output.md b/.trae/skills/access-plugin-dev/examples/output.md new file mode 100644 index 000000000..92209b335 --- /dev/null +++ b/.trae/skills/access-plugin-dev/examples/output.md @@ -0,0 +1,145 @@ +# Access 插件开发指南 + +## 开发步骤 + +### 1. 导入必要的依赖 + +```typescript +import { AccessInput, BaseAccess, IsAccess, Pager, PageRes, PageSearch } from '@certd/pipeline'; +import { DomainRecord } from '@certd/plugin-lib'; +``` + +### 2. 使用 @IsAccess 注解注册插件 + +```typescript +@IsAccess({ + name: 'demo', // 插件唯一标识 + title: '授权插件示例', // 插件标题 + icon: 'clarity:plugin-line', // 插件图标 + desc: '这是一个示例授权插件,用于演示如何实现一个授权插件', // 插件描述 +}) +export class DemoAccess extends BaseAccess { + // 插件实现... +} +``` + +### 3. 定义授权属性 + +使用 `@AccessInput` 注解定义授权属性: + +```typescript +@AccessInput({ + title: '授权方式', + value: 'apiKey', // 默认值 + component: { + name: "a-select", // 基于 antdv 的输入组件 + vModel: "value", // v-model 绑定的属性名 + options: [ // 组件参数 + { label: "API密钥(推荐)", value: "apiKey" }, + { label: "账号密码", value: "account" }, + ], + placeholder: 'demoKeyId', + }, + required: true, +}) +apiType = ''; + +@AccessInput({ + title: '密钥Id', + component: { + name:"a-input", + allowClear: true, + placeholder: 'demoKeyId', + }, + required: true, +}) +demoKeyId = ''; + +@AccessInput({ + title: '密钥',//标题 + required: true, //text组件可以省略 + encrypt: true, //该属性是否需要加密 +}) +demoKeySecret = ''; +``` + +### 4. 实现测试方法 + +```typescript +@AccessInput({ + title: "测试", + component: { + name: "api-test", + action: "TestRequest" + }, + helper: "点击测试接口是否正常" +}) +testRequest = true; + +/** + * 会通过上面的testRequest参数在ui界面上生成测试按钮,供用户测试接口调用是否正常 + */ +async onTestRequest() { + await this.GetDomainList({}); + return "ok" +} +``` + +### 5. 实现 API 方法 + +```typescript +/** + * 获api接口示例 取域名列表, + */ +async GetDomainList(req: PageSearch): Promise> { + //输出日志必须使用ctx.logger + this.ctx.logger.info(`获取域名列表,req:${JSON.stringify(req)}`); + const pager = new Pager(req); + const resp = await this.doRequest({ + action: "ListDomains", + data: { + domain: req.searchKey, + offset: pager.getOffset(), + limit: pager.pageSize, + } + }); + const total = resp?.TotalCount || 0; + let list = resp?.DomainList?.map((item) => { + item.domain = item.Domain; + item.id = item.DomainId; + return item; + }) + return { + total, + list + }; +} + +/** + * 通用api调用方法, 具体如何构造请求体,需参考对应应用的API文档 + */ +async doRequest(req: { action: string, data?: any }) { + const res = await this.ctx.http.request({ + url: "https://api.demo.cn/api/", + method: "POST", + data: { + Action: req.action, + Body: req.data + } + }); + + if (res.Code !== 0) { + //异常处理 + throw new Error(res.Message || "请求失败"); + } + return res.Resp; +} +``` + +## 注意事项 + +1. **插件命名**:插件名称应简洁明了,反映其功能。 +2. **属性加密**:对于敏感信息(如密钥),应设置 `encrypt: true`。 +3. **日志输出**:必须使用 `this.ctx.logger` 输出日志,而不是 `console`。 +4. **错误处理**:API 调用失败时应抛出明确的错误信息。 +5. **测试方法**:实现 `onTestRequest` 方法,以便用户可以测试授权是否正常。 \ No newline at end of file diff --git a/.trae/skills/dns-provider-dev/SKILL.md b/.trae/skills/dns-provider-dev/SKILL.md new file mode 100644 index 000000000..180a698ad --- /dev/null +++ b/.trae/skills/dns-provider-dev/SKILL.md @@ -0,0 +1,212 @@ +# DNS Provider 插件开发技能 + +## 什么是 DNS Provider 插件 + +DNS Provider 插件是 Certd 系统中的 DNS 提供商插件,它用于在 ACME 申请证书时给域名添加 TXT 解析记录,以验证域名所有权。 + +## 开发步骤 + +### 1. 导入必要的依赖 + +```typescript +import { AbstractDnsProvider, CreateRecordOptions, IsDnsProvider, RemoveRecordOptions } from '@certd/plugin-cert'; +import { DemoAccess } from './access.js'; +import { isDev } from '../../utils/env.js'; +``` + +### 2. 定义记录数据结构 + +```typescript +type DemoRecord = { + // 这里定义 Record 记录的数据结构,跟对应云平台接口返回值一样即可,一般是拿到 id 就行,用于删除 txt 解析记录,清理申请痕迹 + // id:string +}; +``` + +### 3. 使用 @IsDnsProvider 注解注册插件 + +```typescript +// 这里通过 IsDnsProvider 注册一个 dnsProvider +@IsDnsProvider({ + name: 'demo', // 插件唯一标识 + title: 'Dns提供商Demo', // 插件标题 + desc: 'dns provider示例', // 插件描述 + icon: 'clarity:plugin-line', // 插件图标 + // 这里是对应的云平台的 access 类型名称 + accessType: 'demo', + order: 99, // 排序 +}) +export class DemoDnsProvider extends AbstractDnsProvider { + access!: DemoAccess; + + async onInstance() { + this.access = this.ctx.access as DemoAccess; + // 也可以通过 ctx 成员变量传递 context + this.logger.debug('access', this.access); + // 初始化的操作 + // ... + } + + // 插件实现... +} +``` + +### 4. 实现 createRecord 方法 + +```typescript +/** + * 创建 dns 解析记录,用于验证域名所有权 + */ +async createRecord(options: CreateRecordOptions): Promise { + /** + * options 参数说明 + * fullRecord: '_acme-challenge.example.com', + * value: 一串 uuid + * type: 'TXT', + * domain: 'example.com' + */ + const { fullRecord, value, type, domain } = options; + this.logger.info('添加域名解析:', fullRecord, value, type, domain); + + // 调用创建 dns 解析记录的对应的云端接口,创建 txt 类型的 dns 解析记录 + // 请根据实际接口情况调用,例如: + // const createDnsRecordUrl = "xxx" + // const record = this.http.post(createDnsRecordUrl,{ + // // 授权参数 + // // 创建 dns 解析记录的参数 + // }) + // // 返回本次创建的 dns 解析记录,这个记录会在删除的时候用到 + // return record +} +``` + +### 5. 实现 removeRecord 方法 + +```typescript +/** + * 删除 dns 解析记录,清理申请痕迹 + * @param options + */ +async removeRecord(options: RemoveRecordOptions): Promise { + const { fullRecord, value, domain } = options.recordReq; + const record = options.recordRes; + this.logger.info('删除域名解析:', domain, fullRecord, value, record); + // 这里调用删除 txt dns 解析记录接口 + // 请根据实际接口情况调用,例如: + + // const deleteDnsRecordUrl = "xxx" + // const res = this.http.delete(deleteDnsRecordUrl,{ + // // 授权参数 + // // 删除 dns 解析记录的参数 + // }) + + + this.logger.info('删除域名解析成功:', fullRecord, value); +} +``` + +### 6. 实例化插件 + +```typescript +// 实例化这个 provider,将其自动注册到系统中 +if (isDev()) { + // 你的实现 要去掉这个 if,不然生产环境将不会显示 + new DemoDnsProvider(); +} +``` + +## 注意事项 + +1. **插件命名**:插件名称应简洁明了,反映其功能。 +2. **accessType**:必须指定对应的云平台的 access 类型名称。 +3. **记录结构**:定义适合对应云平台的记录数据结构,至少包含 id 字段用于删除记录。 +4. **日志输出**:使用 `this.logger` 输出日志,而不是 `console`。 +5. **错误处理**:API 调用失败时应抛出明确的错误信息。 +6. **实例化**:生产环境中应移除 `if (isDev())` 条件,确保插件在生产环境中也能被注册。 + +## 完整示例 + +```typescript +import { AbstractDnsProvider, CreateRecordOptions, IsDnsProvider, RemoveRecordOptions } from '@certd/plugin-cert'; +import { DemoAccess } from './access.js'; +import { isDev } from '../../utils/env.js'; + +type DemoRecord = { + // 这里定义 Record 记录的数据结构,跟对应云平台接口返回值一样即可,一般是拿到 id 就行,用于删除 txt 解析记录,清理申请痕迹 + // id:string +}; + +// 这里通过 IsDnsProvider 注册一个 dnsProvider +@IsDnsProvider({ + name: 'demo', + title: 'Dns提供商Demo', + desc: 'dns provider示例', + icon: 'clarity:plugin-line', + // 这里是对应的云平台的 access 类型名称 + accessType: 'demo', + order: 99, +}) +export class DemoDnsProvider extends AbstractDnsProvider { + access!: DemoAccess; + + async onInstance() { + this.access = this.ctx.access as DemoAccess; + // 也可以通过 ctx 成员变量传递 context + this.logger.debug('access', this.access); + // 初始化的操作 + // ... + } + + /** + * 创建 dns 解析记录,用于验证域名所有权 + */ + async createRecord(options: CreateRecordOptions): Promise { + /** + * options 参数说明 + * fullRecord: '_acme-challenge.example.com', + * value: 一串 uuid + * type: 'TXT', + * domain: 'example.com' + */ + const { fullRecord, value, type, domain } = options; + this.logger.info('添加域名解析:', fullRecord, value, type, domain); + + // 调用创建 dns 解析记录的对应的云端接口,创建 txt 类型的 dns 解析记录 + // 请根据实际接口情况调用,例如: + // const createDnsRecordUrl = "xxx" + // const record = this.http.post(createDnsRecordUrl,{ + // // 授权参数 + // // 创建 dns 解析记录的参数 + // }) + // // 返回本次创建的 dns 解析记录,这个记录会在删除的时候用到 + // return record + } + + /** + * 删除 dns 解析记录,清理申请痕迹 + * @param options + */ + async removeRecord(options: RemoveRecordOptions): Promise { + const { fullRecord, value, domain } = options.recordReq; + const record = options.recordRes; + this.logger.info('删除域名解析:', domain, fullRecord, value, record); + // 这里调用删除 txt dns 解析记录接口 + // 请根据实际接口情况调用,例如: + + // const deleteDnsRecordUrl = "xxx" + // const res = this.http.delete(deleteDnsRecordUrl,{ + // // 授权参数 + // // 删除 dns 解析记录的参数 + // }) + + + this.logger.info('删除域名解析成功:', fullRecord, value); + } +} + +// 实例化这个 provider,将其自动注册到系统中 +if (isDev()) { + // 你的实现 要去掉这个 if,不然生产环境将不会显示 + new DemoDnsProvider(); +} +``` \ No newline at end of file diff --git a/.trae/skills/dns-provider-dev/examples/input.md b/.trae/skills/dns-provider-dev/examples/input.md new file mode 100644 index 000000000..2d483459a --- /dev/null +++ b/.trae/skills/dns-provider-dev/examples/input.md @@ -0,0 +1 @@ +我需要开发一个 DNS Provider 插件,用于在 ACME 申请证书时添加 TXT 解析记录。请指导我如何实现。 \ No newline at end of file diff --git a/.trae/skills/dns-provider-dev/examples/output.md b/.trae/skills/dns-provider-dev/examples/output.md new file mode 100644 index 000000000..deb7de392 --- /dev/null +++ b/.trae/skills/dns-provider-dev/examples/output.md @@ -0,0 +1,121 @@ +# DNS Provider 插件开发指南 + +## 开发步骤 + +### 1. 导入必要的依赖 + +```typescript +import { AbstractDnsProvider, CreateRecordOptions, IsDnsProvider, RemoveRecordOptions } from '@certd/plugin-cert'; +import { DemoAccess } from './access.js'; +import { isDev } from '../../utils/env.js'; +``` + +### 2. 定义记录数据结构 + +```typescript +type DemoRecord = { + // 这里定义 Record 记录的数据结构,跟对应云平台接口返回值一样即可,一般是拿到 id 就行,用于删除 txt 解析记录,清理申请痕迹 + // id:string +}; +``` + +### 3. 使用 @IsDnsProvider 注解注册插件 + +```typescript +// 这里通过 IsDnsProvider 注册一个 dnsProvider +@IsDnsProvider({ + name: 'demo', // 插件唯一标识 + title: 'Dns提供商Demo', // 插件标题 + desc: 'dns provider示例', // 插件描述 + icon: 'clarity:plugin-line', // 插件图标 + // 这里是对应的云平台的 access 类型名称 + accessType: 'demo', + order: 99, // 排序 +}) +export class DemoDnsProvider extends AbstractDnsProvider { + access!: DemoAccess; + + async onInstance() { + this.access = this.ctx.access as DemoAccess; + // 也可以通过 ctx 成员变量传递 context + this.logger.debug('access', this.access); + // 初始化的操作 + // ... + } + + // 插件实现... +} +``` + +### 4. 实现 createRecord 方法 + +```typescript +/** + * 创建 dns 解析记录,用于验证域名所有权 + */ +async createRecord(options: CreateRecordOptions): Promise { + /** + * options 参数说明 + * fullRecord: '_acme-challenge.example.com', + * value: 一串 uuid + * type: 'TXT', + * domain: 'example.com' + */ + const { fullRecord, value, type, domain } = options; + this.logger.info('添加域名解析:', fullRecord, value, type, domain); + + // 调用创建 dns 解析记录的对应的云端接口,创建 txt 类型的 dns 解析记录 + // 请根据实际接口情况调用,例如: + // const createDnsRecordUrl = "xxx" + // const record = this.http.post(createDnsRecordUrl,{ + // // 授权参数 + // // 创建 dns 解析记录的参数 + // }) + // // 返回本次创建的 dns 解析记录,这个记录会在删除的时候用到 + // return record +} +``` + +### 5. 实现 removeRecord 方法 + +```typescript +/** + * 删除 dns 解析记录,清理申请痕迹 + * @param options + */ +async removeRecord(options: RemoveRecordOptions): Promise { + const { fullRecord, value, domain } = options.recordReq; + const record = options.recordRes; + this.logger.info('删除域名解析:', domain, fullRecord, value, record); + // 这里调用删除 txt dns 解析记录接口 + // 请根据实际接口情况调用,例如: + + // const deleteDnsRecordUrl = "xxx" + // const res = this.http.delete(deleteDnsRecordUrl,{ + // // 授权参数 + // // 删除 dns 解析记录的参数 + // }) + + + this.logger.info('删除域名解析成功:', fullRecord, value); +} +``` + +### 6. 实例化插件 + +```typescript +// 实例化这个 provider,将其自动注册到系统中 +if (isDev()) { + // 你的实现 要去掉这个 if,不然生产环境将不会显示 + new DemoDnsProvider(); +} +``` + +## 注意事项 + +1. **插件命名**:插件名称应简洁明了,反映其功能。 +2. **accessType**:必须指定对应的云平台的 access 类型名称。 +3. **记录结构**:定义适合对应云平台的记录数据结构,至少包含 id 字段用于删除记录。 +4. **日志输出**:使用 `this.logger` 输出日志,而不是 `console`。 +5. **错误处理**:API 调用失败时应抛出明确的错误信息。 +6. **实例化**:生产环境中应移除 `if (isDev())` 条件,确保插件在生产环境中也能被注册。 \ No newline at end of file diff --git a/.trae/skills/plugin-converter/SKILL.md b/.trae/skills/plugin-converter/SKILL.md new file mode 100644 index 000000000..650e50d75 --- /dev/null +++ b/.trae/skills/plugin-converter/SKILL.md @@ -0,0 +1,201 @@ +# 插件转换工具技能 + +## 什么是插件转换工具 + +插件转换工具是一个用于将 Certd 插件转换为 YAML 配置文件的命令行工具。它可以分析单个插件文件,识别插件类型,并生成对应的 YAML 配置,方便插件的注册和管理。 + +## 工具位置 + +`trae/skills/convert-plugin-to-yaml.js` + +## 功能特性 + +- **单个插件转换**:支持指定单个插件文件进行转换,而不是扫描整个目录 +- **自动类型识别**:自动识别插件类型(Access、Task、DNS Provider、Notification、Addon) +- **详细日志输出**:提供详细的转换过程日志,便于调试 +- **YAML 配置生成**:生成标准的 YAML 配置文件 +- **配置文件保存**:自动将生成的配置保存到 `./metadata` 目录 +- **可复用函数**:导出了可复用的函数,便于其他模块调用 + +## 使用方法 + +### 基本用法 + +```bash +node trae/skills/convert-plugin-to-yaml.js <插件文件路径> +``` + +### 示例 + +```bash +# 转换 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()**:主函数,处理命令行参数并执行转换 + +### 导出函数 + +工具导出了以下函数,便于其他模块调用: + +```javascript +export { + convertSinglePlugin, // 转换单个插件 + loadSingleModule, // 加载单个模块 + isPrototypeOf // 检查原型关系 +}; +``` + +## 应用场景 + +1. **插件开发**:在开发新插件时,快速生成配置文件 +2. **插件调试**:查看插件的内部定义和配置 +3. **插件管理**:批量转换现有插件为标准配置格式 +4. **自动化构建**:集成到构建流程中,自动生成插件配置 + +## 示例输出 + +### 转换 Access 插件示例 + +```bash +$ 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 插件示例 + +```bash +$ 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 配置文件,简化插件的注册和管理过程。通过命令行参数指定单个插件文件,工具会自动完成类型识别、配置生成和保存等操作,大大提高了插件开发和管理的效率。 \ No newline at end of file diff --git a/.trae/skills/plugin-converter/examples/input.md b/.trae/skills/plugin-converter/examples/input.md new file mode 100644 index 000000000..fe075cb3a --- /dev/null +++ b/.trae/skills/plugin-converter/examples/input.md @@ -0,0 +1 @@ +我需要将一个插件转换为 YAML 配置文件。请指导我如何使用插件转换工具。 \ No newline at end of file diff --git a/.trae/skills/plugin-converter/examples/output.md b/.trae/skills/plugin-converter/examples/output.md new file mode 100644 index 000000000..2f252f73b --- /dev/null +++ b/.trae/skills/plugin-converter/examples/output.md @@ -0,0 +1,95 @@ +# 插件转换工具使用指南 + +## 工具说明 + +插件转换工具用于将单个 Certd 插件转换为 YAML 配置文件,方便插件的注册和管理。 + +## 工具位置 + +`.trae/skills/plugin-converter/resources/convert-plugin-to-yaml.js` + +## 使用方法 + +### 基本用法 + +```bash +node .trae/skills/plugin-converter/resources/convert-plugin-to-yaml.js <插件文件路径> +``` + +### 示例 + +#### 转换 Access 插件 + +```bash +node .trae/skills/plugin-converter/resources/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/access.js +``` + +#### 转换 Task 插件 + +```bash +node .trae/skills/plugin-converter/resources/convert-plugin-to-yaml.js packages/ui/certd-server/src/plugins/plugin-demo/plugins/plugin-test.js +``` + +#### 转换 DNS Provider 插件 + +```bash +node .trae/skills/plugin-converter/resources/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 插件) + +## 示例输出 + +### 转换 Access 插件示例 + +```bash +$ node .trae/skills/plugin-converter/resources/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 +插件转换完成! +``` \ No newline at end of file diff --git a/.trae/skills/plugin-converter/resources/convert-plugin-to-yaml.js b/.trae/skills/plugin-converter/resources/convert-plugin-to-yaml.js new file mode 100644 index 000000000..0bb6251cc --- /dev/null +++ b/.trae/skills/plugin-converter/resources/convert-plugin-to-yaml.js @@ -0,0 +1,160 @@ +// 转换单个插件为 YAML 配置的技能脚本 + +import path from "path"; +import fs from "fs"; +import { pathToFileURL } from "node:url"; +import * as yaml from "js-yaml"; +import { AbstractTaskPlugin, BaseAccess, BaseNotification} from "@certd/pipeline"; +import { BaseAddon} from "@certd/lib-server"; + +/** + * 检查对象是否是指定类的原型 + */ +function isPrototypeOf(value, cls) { + return cls.prototype.isPrototypeOf(value.prototype); +} + +/** + * 加载单个插件模块 + */ +async function loadSingleModule(filePath) { + try { + // 转换为 file:// URL(Windows 必需) + const moduleUrl = pathToFileURL(filePath).href; + const module = await import(moduleUrl); + return module.default || module; + } catch (err) { + console.error(`加载模块 ${filePath} 失败:`, err); + return null; + } +} + +/** + * 分析单个插件并生成 YAML 配置 + */ +async function convertSinglePlugin(pluginPath) { + console.log(`开始转换插件: ${pluginPath}`); + + // 加载插件模块 + const module = await loadSingleModule(pluginPath); + if (!module) { + console.error("加载插件失败,退出"); + return; + } + + // 处理模块中的所有导出 + const entry = Object.entries(module); + if (entry.length === 0) { + console.error("插件模块没有导出任何内容"); + return; + } + + console.log(`插件模块导出了 ${entry.length} 个对象: ${entry.map(([name]) => name).join(", ")}`); + + // 处理每个导出的对象 + for (const [name, value] of entry) { + // 检查是否是插件(有 define 属性) + if (!value.define) { + console.log(`跳过非插件对象: ${name}`); + continue; + } + + console.log(`处理插件: ${name}`); + + // 构建插件定义 + const pluginDefine = { + ...value.define + }; + + let subType = ""; + + // 确定插件类型 + if (pluginDefine.accessType) { + pluginDefine.pluginType = "dnsProvider"; + } else if (isPrototypeOf(value, AbstractTaskPlugin)) { + pluginDefine.pluginType = "deploy"; + } else if (isPrototypeOf(value, BaseNotification)) { + pluginDefine.pluginType = "notification"; + } else if (isPrototypeOf(value, BaseAccess)) { + pluginDefine.pluginType = "access"; + } else if (isPrototypeOf(value, BaseAddon)) { + pluginDefine.pluginType = "addon"; + subType = "_" + (pluginDefine.addonType || ""); + } else { + console.log(`[warning] 未知的插件类型:${pluginDefine.name}`); + continue; + } + + pluginDefine.type = "builtIn"; + + // 计算脚本文件路径 + const relativePath = path.relative(process.cwd(), pluginPath); + const scriptFilePath = relativePath.replace(/\\/g, "/").replace(/\.js$/, ".js"); + pluginDefine.scriptFilePath = scriptFilePath; + + console.log(`插件类型: ${pluginDefine.pluginType}`); + console.log(`脚本路径: ${scriptFilePath}`); + + // 生成 YAML 配置 + const yamlContent = yaml.dump(pluginDefine); + console.log("\n生成的 YAML 配置:"); + console.log(yamlContent); + + // 可选:保存到文件 + const outputDir = "./metadata"; + if (!fs.existsSync(outputDir)) { + fs.mkdirSync(outputDir, { recursive: true }); + } + + const outputFileName = `${pluginDefine.pluginType}${subType}_${pluginDefine.name}.yaml`; + const outputPath = path.join(outputDir, outputFileName); + + fs.writeFileSync(outputPath, yamlContent, 'utf8'); + console.log(`\nYAML 配置已保存到: ${outputPath}`); + + return pluginDefine; + } + + console.error("未找到有效的插件定义"); +} + +/** + * 主函数 + */ +async function main() { + const args = process.argv.slice(2); + + if (args.length === 0) { + console.error("请指定插件文件路径"); + console.log("用法: node convert-plugin-to-yaml.js <插件文件路径>"); + process.exit(1); + } + + const pluginPath = args[0]; + + if (!fs.existsSync(pluginPath)) { + console.error(`插件文件不存在: ${pluginPath}`); + process.exit(1); + } + + try { + await convertSinglePlugin(pluginPath); + console.log("\n插件转换完成!"); + } catch (error) { + console.error("转换过程中出错:", error); + process.exit(1); + } +} + +// 如果直接运行此脚本 +if (import.meta.url === pathToFileURL(process.argv[1]).href) { + main(); +} + +// 导出函数,以便其他模块使用 +export { + convertSinglePlugin, + loadSingleModule, + isPrototypeOf +}; + diff --git a/.trae/skills/task-plugin-dev/SKILL.md b/.trae/skills/task-plugin-dev/SKILL.md new file mode 100644 index 000000000..84d16e690 --- /dev/null +++ b/.trae/skills/task-plugin-dev/SKILL.md @@ -0,0 +1,388 @@ +# Task 插件开发技能 + +## 什么是 Task 插件 + +Task 插件是 Certd 系统中的部署任务插件,它继承自 `AbstractTaskPlugin` 类,被流水线调用 `execute` 方法,将证书部署到对应的应用上。 + +## 开发步骤 + +### 1. 导入必要的依赖 + +```typescript +import { AbstractTaskPlugin, IsTaskPlugin, PageSearch, pluginGroups, RunStrategy, TaskInput } from '@certd/pipeline'; +import { CertInfo, CertReader } from '@certd/plugin-cert'; +import { createCertDomainGetterInputDefine, createRemoteSelectInputDefine } from '@certd/plugin-lib'; +import { optionsUtils } from '@certd/basic'; +import { CertApplyPluginNames} from '@certd/plugin-cert'; +``` + +### 2. 使用 @IsTaskPlugin 注解注册插件 + +```typescript +@IsTaskPlugin({ + // 命名规范,插件类型+功能,大写字母开头,驼峰命名 + name: 'DemoTest', + title: 'Demo-测试插件', // 插件标题 + icon: 'clarity:plugin-line', // 插件图标 + // 插件分组 + group: pluginGroups.other.key, + default: { + // 默认值配置照抄即可 + strategy: { + runStrategy: RunStrategy.SkipWhenSucceed, + }, + }, +}) +// 类名规范,跟上面插件名称(name)一致 +export class DemoTest extends AbstractTaskPlugin { + // 插件实现... +} +``` + +### 3. 定义任务输入参数 + +使用 `@TaskInput` 注解定义任务输入参数: + +```typescript +// 测试参数 +@TaskInput({ + title: '属性示例', + value: '默认值', + component: { + // 前端组件配置,具体配置见组件文档 https://www.antdv.com/components/input-cn + name: 'a-input', + vModel: 'value', // 双向绑定组件的 props 名称 + }, + helper: '帮助说明,[链接](https://certd.docmirror.cn)', + required: false, // 是否必填 +}) +text!: string; + +// 证书选择,此项必须要有 +@TaskInput({ + title: '域名证书', + helper: '请选择前置任务输出的域名证书', + component: { + name: 'output-selector', + from: [...CertApplyPluginNames], + }, + // required: true, // 必填 +}) +cert!: CertInfo; + +@TaskInput(createCertDomainGetterInputDefine({ props: { required: false } })) +// 前端可以展示,当前申请的证书域名列表 +certDomains!: string[]; + +// 授权选择框 +@TaskInput({ + title: 'demo授权', + helper: 'demoAccess授权', + component: { + name: 'access-selector', + type: 'demo', // 固定授权类型 + }, + // rules: [{ required: true, message: '此项必填' }], + // required: true, // 必填 +}) +accessId!: string; +``` + +### 4. 实现插件方法 + +#### 4.1 插件实例化时执行的方法 + +```typescript +// 插件实例化时执行的方法 +async onInstance() {} +``` + +#### 4.2 插件执行方法 + +```typescript +// 插件执行方法 +async execute(): Promise { + const { select, text, cert, accessId } = this; + + try { + const access = await this.getAccess(accessId); + this.logger.debug('access', access); + } catch (e) { + this.logger.error('获取授权失败', e); + } + + try { + const certReader = new CertReader(cert); + this.logger.debug('certReader', certReader); + } catch (e) { + this.logger.error('读取crt失败', e); + } + + this.logger.info('DemoTestPlugin execute'); + this.logger.info('text:', text); + this.logger.info('select:', select); + this.logger.info('switch:', this.switch); + this.logger.info('授权id:', accessId); + + // 具体的部署逻辑 + // ... +} +``` + +#### 4.3 后端获取选项方法 + +```typescript +@TaskInput( + createRemoteSelectInputDefine({ + title: '从后端获取选项', + helper: '选择时可以从后端获取选项', + action: DemoTest.prototype.onGetSiteList.name, + // 当以下参数变化时,触发获取选项 + watches: ['certDomains', 'accessId'], + required: true, + }) +) +siteName!: string | string[]; + +// 从后端获取选项的方法 +async onGetSiteList(req: PageSearch) { + if (!this.accessId) { + throw new Error('请选择Access授权'); + } + + // @ts-ignore + const access = await this.getAccess(this.accessId); + + // const siteRes = await access.GetDomainList(req); + // 以下是模拟数据 + const siteRes = [ + { id: 1, siteName: 'site1.com' }, + { id: 2, siteName: 'site2.com' }, + { id: 3, siteName: 'site2.com' }, + ]; + // 转换为前端所需要的格式 + const options = siteRes.map((item: any) => { + return { + value: item.siteName, + label: item.siteName, + domain: item.siteName, + }; + }); + // 将站点域名名称根据证书域名进行匹配分组,分成匹配的和不匹配的两组选项,返回给前端,供用户选择 + return optionsUtils.buildGroupOptions(options, this.certDomains); +} +``` + +## 注意事项 + +1. **插件命名**:插件名称应遵循命名规范,大写字母开头,驼峰命名。 +2. **类名规范**:类名应与插件名称(name)一致。 +3. **证书选择**:必须包含证书选择参数,用于获取前置任务输出的域名证书。 +4. **日志输出**:使用 `this.logger` 输出日志,而不是 `console`。 +5. **错误处理**:执行过程中的错误应被捕获并记录。 +6. **授权获取**:使用 `this.getAccess(accessId)` 获取授权信息。 + +## 完整示例 + +```typescript +import { AbstractTaskPlugin, IsTaskPlugin, PageSearch, pluginGroups, RunStrategy, TaskInput } from '@certd/pipeline'; +import { CertInfo, CertReader } from '@certd/plugin-cert'; +import { createCertDomainGetterInputDefine, createRemoteSelectInputDefine } from '@certd/plugin-lib'; +import { optionsUtils } from '@certd/basic'; +import { CertApplyPluginNames} from '@certd/plugin-cert'; +@IsTaskPlugin({ + //命名规范,插件类型+功能(就是目录plugin-demo中的demo),大写字母开头,驼峰命名 + name: 'DemoTest', + title: 'Demo-测试插件', + icon: 'clarity:plugin-line', + //插件分组 + group: pluginGroups.other.key, + default: { + //默认值配置照抄即可 + strategy: { + runStrategy: RunStrategy.SkipWhenSucceed, + }, + }, +}) +//类名规范,跟上面插件名称(name)一致 +export class DemoTest extends AbstractTaskPlugin { + //测试参数 + @TaskInput({ + title: '属性示例', + value: '默认值', + component: { + //前端组件配置,具体配置见组件文档 https://www.antdv.com/components/input-cn + name: 'a-input', + vModel: 'value', //双向绑定组件的props名称 + }, + helper: '帮助说明,[链接](https://certd.docmirror.cn)', + required: false, //是否必填 + }) + text!: string; + + //测试参数 + @TaskInput({ + title: '选择框', + component: { + //前端组件配置,具体配置见组件文档 https://www.antdv.com/components/select-cn + name: 'a-auto-complete', + vModel: 'value', + options: [ + //选项列表 + { label: '动态显', value: 'show' }, + { label: '动态隐', value: 'hide' }, + ], + }, + }) + select!: string; + + @TaskInput({ + title: '动态显隐', + helper: '我会根据选择框的值进行显隐', + show: true, //动态计算的值会覆盖它 + //动态计算脚本, mergeScript返回的对象会合并当前配置,此处演示 show的值会被动态计算结果覆盖,show的值根据用户选择的select的值决定 + mergeScript: ` + return { + show: ctx.compute(({form})=>{ + return form.select === 'show'; + }) + } + `, + }) + showText!: string; + + //测试参数 + @TaskInput({ + title: '多选框', + component: { + //前端组件配置,具体配置见组件文档 https://www.antdv.com/components/select-cn + name: 'a-select', + vModel: 'value', + mode: 'tags', + multiple: true, + options: [ + { value: '1', label: '选项1' }, + { value: '2', label: '选项2' }, + ], + }, + }) + multiSelect!: string; + + //测试参数 + @TaskInput({ + title: 'switch', + component: { + //前端组件配置,具体配置见组件文档 https://www.antdv.com/components/switch-cn + name: 'a-switch', + vModel: 'checked', + }, + }) + switch!: boolean; + //证书选择,此项必须要有 + @TaskInput({ + title: '域名证书', + helper: '请选择前置任务输出的域名证书', + component: { + name: 'output-selector', + from: [...CertApplyPluginNames], + }, + // required: true, // 必填 + }) + cert!: CertInfo; + + @TaskInput(createCertDomainGetterInputDefine({ props: { required: false } })) + //前端可以展示,当前申请的证书域名列表 + certDomains!: string[]; + + //授权选择框 + @TaskInput({ + title: 'demo授权', + helper: 'demoAccess授权', + component: { + name: 'access-selector', + type: 'demo', //固定授权类型 + }, + // rules: [{ required: true, message: '此项必填' }], + // required: true, //必填 + }) + accessId!: string; + + @TaskInput( + createRemoteSelectInputDefine({ + title: '从后端获取选项', + helper: '选择时可以从后端获取选项', + action: DemoTest.prototype.onGetSiteList.name, + //当以下参数变化时,触发获取选项 + watches: ['certDomains', 'accessId'], + required: true, + }) + ) + siteName!: string | string[]; + + //插件实例化时执行的方法 + async onInstance() {} + + //插件执行方法 + async execute(): Promise { + const { select, text, cert, accessId } = this; + + try { + const access = await this.getAccess(accessId); + this.logger.debug('access', access); + } catch (e) { + this.logger.error('获取授权失败', e); + } + + try { + const certReader = new CertReader(cert); + this.logger.debug('certReader', certReader); + } catch (e) { + this.logger.error('读取crt失败', e); + } + + this.logger.info('DemoTestPlugin execute'); + this.logger.info('text:', text); + this.logger.info('select:', select); + this.logger.info('switch:', this.switch); + this.logger.info('授权id:', accessId); + + // const res = await this.http.request({ + // url: 'https://api.demo.com', + // method: 'GET', + // }); + // if (res.code !== 0) { + // //检查res是否报错,你需要抛异常,来结束插件执行,否则会判定为执行成功,下次执行时会跳过本任务 + // throw new Error(res.message); + // } + // this.logger.info('部署成功:', res); + } + + //此方法演示,如何让前端在添加插件时可以从后端获取选项,这里是后端返回选项的方法 + async onGetSiteList(req: PageSearch) { + if (!this.accessId) { + throw new Error('请选择Access授权'); + } + + // @ts-ignore + const access = await this.getAccess(this.accessId); + + // const siteRes = await access.GetDomainList(req); + //以下是模拟数据 + const siteRes = [ + { id: 1, siteName: 'site1.com' }, + { id: 2, siteName: 'site2.com' }, + { id: 3, siteName: 'site2.com' }, + ]; + //转换为前端所需要的格式 + const options = siteRes.map((item: any) => { + return { + value: item.siteName, + label: item.siteName, + domain: item.siteName, + }; + }); + //将站点域名名称根据证书域名进行匹配分组,分成匹配的和不匹配的两组选项,返回给前端,供用户选择 + return optionsUtils.buildGroupOptions(options, this.certDomains); + } +} +``` \ No newline at end of file diff --git a/.trae/skills/task-plugin-dev/examples/input.md b/.trae/skills/task-plugin-dev/examples/input.md new file mode 100644 index 000000000..622920d6d --- /dev/null +++ b/.trae/skills/task-plugin-dev/examples/input.md @@ -0,0 +1 @@ +我需要开发一个 Task 插件,用于将申请的证书部署到指定的应用系统中。请指导我如何实现。 \ No newline at end of file diff --git a/.trae/skills/task-plugin-dev/examples/output.md b/.trae/skills/task-plugin-dev/examples/output.md new file mode 100644 index 000000000..28ebb03e0 --- /dev/null +++ b/.trae/skills/task-plugin-dev/examples/output.md @@ -0,0 +1,129 @@ +# Task 插件开发指南 + +## 开发步骤 + +### 1. 导入必要的依赖 + +```typescript +import { AbstractTaskPlugin, IsTaskPlugin, PageSearch, pluginGroups, RunStrategy, TaskInput } from '@certd/pipeline'; +import { CertInfo, CertReader } from '@certd/plugin-cert'; +import { createCertDomainGetterInputDefine, createRemoteSelectInputDefine } from '@certd/plugin-lib'; +import { optionsUtils } from '@certd/basic'; +import { CertApplyPluginNames} from '@certd/plugin-cert'; +``` + +### 2. 使用 @IsTaskPlugin 注解注册插件 + +```typescript +@IsTaskPlugin({ + // 命名规范,插件类型+功能,大写字母开头,驼峰命名 + name: 'DemoTest', + title: 'Demo-测试插件', // 插件标题 + icon: 'clarity:plugin-line', // 插件图标 + // 插件分组 + group: pluginGroups.other.key, + default: { + // 默认值配置照抄即可 + strategy: { + runStrategy: RunStrategy.SkipWhenSucceed, + }, + }, +}) +// 类名规范,跟上面插件名称(name)一致 +export class DemoTest extends AbstractTaskPlugin { + // 插件实现... +} +``` + +### 3. 定义任务输入参数 + +使用 `@TaskInput` 注解定义任务输入参数: + +```typescript +// 测试参数 +@TaskInput({ + title: '属性示例', + value: '默认值', + component: { + //前端组件配置,具体配置见组件文档 https://www.antdv.com/components/input-cn + name: 'a-input', + vModel: 'value', //双向绑定组件的props名称 + }, + helper: '帮助说明,[链接](https://certd.docmirror.cn)', + required: false, //是否必填 +}) +text!: string; + +//证书选择,此项必须要有 +@TaskInput({ + title: '域名证书', + helper: '请选择前置任务输出的域名证书', + component: { + name: 'output-selector', + from: [...CertApplyPluginNames], + }, + // required: true, // 必填 +}) +cert!: CertInfo; + +@TaskInput(createCertDomainGetterInputDefine({ props: { required: false } })) +//前端可以展示,当前申请的证书域名列表 +certDomains!: string[]; + +//授权选择框 +@TaskInput({ + title: 'demo授权', + helper: 'demoAccess授权', + component: { + name: 'access-selector', + type: 'demo', //固定授权类型 + }, + // rules: [{ required: true, message: '此项必填' }], + // required: true, //必填 +}) +accessId!: string; +``` + +### 4. 实现插件方法 + +```typescript +//插件实例化时执行的方法 +async onInstance() {} + +//插件执行方法 +async execute(): Promise { + const { select, text, cert, accessId } = this; + + try { + const access = await this.getAccess(accessId); + this.logger.debug('access', access); + } catch (e) { + this.logger.error('获取授权失败', e); + } + + try { + const certReader = new CertReader(cert); + this.logger.debug('certReader', certReader); + } catch (e) { + this.logger.error('读取crt失败', e); + } + + this.logger.info('DemoTestPlugin execute'); + this.logger.info('text:', text); + this.logger.info('select:', select); + this.logger.info('switch:', this.switch); + this.logger.info('授权id:', accessId); + + // 具体的部署逻辑 + // ... +} +``` + +## 注意事项 + +1. **插件命名**:插件名称应遵循命名规范,大写字母开头,驼峰命名。 +2. **类名规范**:类名应与插件名称(name)一致。 +3. **证书选择**:必须包含证书选择参数,用于获取前置任务输出的域名证书。 +4. **日志输出**:使用 `this.logger` 输出日志,而不是 `console`。 +5. **错误处理**:执行过程中的错误应被捕获并记录。 +6. **授权获取**:使用 `this.getAccess(accessId)` 获取授权信息。 \ No newline at end of file