From 9c8986be104bc448803820ceac419d401a67df88 Mon Sep 17 00:00:00 2001
From: xiaojunnuo <xiaojunnuo@qq.com>
Date: Thu, 27 Aug 2026 23:52:43 +0800
Subject: [PATCH] docs(certd-plugin): update example and docs for runStrategy
 and component comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

补充了示例yaml和文档中关于运行策略、组件注释的说明，完善了runStrategy的使用场景介绍，新增了返回skip跳过任务的代码示例注释
---
 .../examples/DemoDeploy.yaml                  | 11 +++++---
 .../references/online-yaml-format.md          | 27 +++++++++++++------
 .../skills/task-plugin-dev/SKILL.md           | 23 ++++++++++++++++
 3 files changed, 49 insertions(+), 12 deletions(-)

diff --git a/.trae/skills/certd-online-plugin-dev/examples/DemoDeploy.yaml b/.trae/skills/certd-online-plugin-dev/examples/DemoDeploy.yaml
index b4434c121..01e4291b3 100644
--- a/.trae/skills/certd-online-plugin-dev/examples/DemoDeploy.yaml
+++ b/.trae/skills/certd-online-plugin-dev/examples/DemoDeploy.yaml
@@ -11,10 +11,10 @@ input:
     title: 前置任务证书
     helper: 请选择前置任务产生的证书
     component:
-      name: output-selector
+      name: output-selector # 前置任务输出选择组件
       vModel: modelValue
       from:
-        - ':cert:'
+        - ':cert:' # 前置任务输出作为输入的筛选条件 , 格式 pluginType:valueType:keyName ， 为空表示任意匹配
     required: true
   certDomains:
     title: 当前证书域名
@@ -50,10 +50,10 @@ input:
         - value: '2'
           label: 选项2
     required: false
-showRunStrategy: false
+showRunStrategy: false # 用户是否可以选择运行策略， 【默认不显示】
 default:
   strategy:
-    runStrategy: 1
+    runStrategy: 0 # 运行策略， 0 = 成功后跳过，1 = 正常运行
 content: >
 
   // 要用await来import模块
@@ -96,5 +96,8 @@ content: >
       }
       this.logger.info("执行成功")
       // this.outputName = xxxx //设置输出参数，可以被其他插件选择使用
+
+      // 此处可以返回 "skip" ， 表示本次任务没有做任何操作和改变 ， 配合runStrategy=1使用
+      // return "skip"
     }
   }
diff --git a/.trae/skills/certd-online-plugin-dev/references/online-yaml-format.md b/.trae/skills/certd-online-plugin-dev/references/online-yaml-format.md
index 985745a4c..048315184 100644
--- a/.trae/skills/certd-online-plugin-dev/references/online-yaml-format.md
+++ b/.trae/skills/certd-online-plugin-dev/references/online-yaml-format.md
@@ -14,15 +14,26 @@ pluginType: task
 group: other
 version: 1.0.0
 input:
-  cert:
+  cert: # 输入字段定义
     title: 域名证书
-    required: true
-    component:
-      name: cert-select
-output: {}
-dependPlugins: []
-dependPackages: []
-default: {}
+    required: true  # 是否必填
+    component: # 输入字段组件
+      name: cert-select # 前端vue组件名称
+output:  # 【可选】输出字段定义
+  cert:
+    title: 证书 #输出字段标题
+    type: "cert" # 输出字段类型
+dependPlugins: # 依赖的插件
+  # - access:certd/DemoAccess: *
+dependPackages:  #  依赖的nodejs包
+   # xxx: ^1.0.0
+vip: "free" # 默认免费，plus 需要专业版
+showRunStrategy: false # 【默认不显示】
+default: {
+  strategy: { 
+    runStrategy: 0, # 运行策略， 0 = 成功后跳过，1 = 正常运行
+  },
+}
 content: |
   const { AbstractTaskPlugin } = await _ctx.import("@certd/pipeline")
   const { DemoAccess } = await _ctx.import("/@/plugins/plugin-lib/demo/access/index.js")
diff --git a/.trae/skills/certd-online-plugin-dev/skills/task-plugin-dev/SKILL.md b/.trae/skills/certd-online-plugin-dev/skills/task-plugin-dev/SKILL.md
index f62519c18..ed89e82ad 100644
--- a/.trae/skills/certd-online-plugin-dev/skills/task-plugin-dev/SKILL.md
+++ b/.trae/skills/certd-online-plugin-dev/skills/task-plugin-dev/SKILL.md
@@ -14,6 +14,24 @@ description: 用于开发 Certd 在线 Task 插件。输出完整 YAML，脚本
 - 输入配置放在 YAML 的 `input` 字段。
 - 执行脚本放在 YAML 顶层 `content` 字段。
 
+
+## runStrategy
+
+整个流水线每次运行，会记录每个任务的运行结果状态，如果上次任务执行成功，且 runStrategy 为成功后跳过，那么下次运行时会跳过该任务。
+
+
+- `showRunStrategy`: false 【默认不显示】
+  - 任务配置时是否显示 runStrategy 字段，用于指定任务的执行策略。
+- `default.strategy.runStrategy`: 0 【默认成功后跳过】
+  - 0 表示成功后跳过，1 表示正常运行。 
+  - 设置任务的默认运行策略runStrategy。
+
+当证书申请任务，申请证书成功后，会清空后续任务状态。此时后续`runStrategy = 0` 的任务，会重新执行。
+这样可以保证相同的证书不会重复部署。
+
+在其他场景的部署任务，可能希望每次运行都检查是否需要部署，如果即将过期就部署，没有过期就跳过。
+此时可以设置 `default.strategy.runStrategy = 1`，然后在`execute`方法中，如果没有过期，就返回 `"skip"`。
+
 ## `content` 模板
 
 ```javascript
@@ -33,9 +51,14 @@ return class DemoTask extends AbstractTaskPlugin {
       url: "https://api.example.com",
     })
     if (res.error) {
+      // 抛异常让任务执行失败
       throw new Error(`任务执行失败: ${res.message}`)
     }
     this.logger.info("执行成功")
+    // 还可以返回 "skip" 表示当前任务没有执行任何操作
+    // 一般与 runStrategy = 1 配合使用。 (1=正常运行，0表示成功后跳过)
+    // 比如检查无需更新，时就 返回 "skip"
+    // return "skip"
   }
 }
 ```