qinglong/docs/operations/ql3-local-plugin-package-workflow.md

QingLong 3.0 本机 Plugin Package Workflow

ql3-workflow 用于检查和启动已经由 Plugin Package 安装、materialize 并发布的 Workflow。它只适用于 edge/standalone；Cluster 后续使用独立的受认证 API/RBAC transport。

前置条件

• 已完成 Local Owner credential 与 Project RoleBinding；
• Package generation 处于 active，未 disabled、withdrawn 或 quarantine；
• ql3-local-application 正在运行并已输出 event=active；
• command 目录为 0700，command file 为当前运行 UID 的 canonical 0600 regular file。

检查可用 Workflow

{
  "schemaVersion": 1,
  "operation": "workflow.inspect",
  "options": {
    "deploymentRoot": "/opt/qinglong3",
    "databasePath": "/opt/qinglong3/qinglong3.sqlite",
    "profile": "edge",
    "ownerPepperKeyringDirectory": "/opt/qinglong3/owner-peppers",
    "credentialFilePath": "/opt/qinglong3/owner-credential.json",
    "busyTimeoutMs": 100
  },
  "request": {
    "projectId": "default",
    "packageName": "example-automation",
    "requestId": "workflow-inspect-example-v1",
    "auditEventId": "REPLACE_WITH_UUID_V4",
    "failureAuditEventId": "REPLACE_WITH_DIFFERENT_UUID_V4"
  }
}

chmod 0600 /opt/qinglong3/commands/workflow-inspect.json
ql3-workflow run --command-file /opt/qinglong3/commands/workflow-inspect.json

结果只返回 Workflow metadata。记录目标 Workflow 的 id 和所有 Step id；不要从 Package bundle 手工 拼 generation、revision 或 digest。

启动 Workflow

为 plan、Run 和每个 StepRun 分别生成 UUID v4。stepRunIds 的 key 必须与 inspect 返回的 Step id 精确一致：

{
  "schemaVersion": 1,
  "operation": "workflow.start",
  "options": {
    "deploymentRoot": "/opt/qinglong3",
    "databasePath": "/opt/qinglong3/qinglong3.sqlite",
    "profile": "edge",
    "ownerPepperKeyringDirectory": "/opt/qinglong3/owner-peppers",
    "credentialFilePath": "/opt/qinglong3/owner-credential.json",
    "busyTimeoutMs": 100
  },
  "request": {
    "projectId": "default",
    "packageName": "example-automation",
    "workflowId": "daily",
    "planId": "REPLACE_WITH_UUID_V4",
    "runId": "REPLACE_WITH_DIFFERENT_UUID_V4",
    "stepRunIds": {
      "collect": "REPLACE_WITH_DIFFERENT_UUID_V4",
      "summarize": "REPLACE_WITH_DIFFERENT_UUID_V4"
    },
    "requestId": "workflow-start-example-v1",
    "auditEventId": "REPLACE_WITH_DIFFERENT_UUID_V4",
    "failureAuditEventId": "REPLACE_WITH_DIFFERENT_UUID_V4"
  }
}

chmod 0600 /opt/qinglong3/commands/workflow-start.json
ql3-workflow run --command-file /opt/qinglong3/commands/workflow-start.json

created 表示 admission 已耐久提交，不表示 Workflow 已完成。application 的唯一 scheduler cadence 会继续 推进 frontier、Task Attempt 和执行。若命令响应丢失，必须保留并原样重放同一文件；existing 表示同一个 durable plan 已存在。不得重新生成 ID 来“重试”，否则会表达一个新的 Workflow Run。

workflow.inspect 需要 run.read；workflow.start 需要 run.start。Viewer 可以检查但不能启动， Operator/Admin/Owner 按当前 RoleBinding 执行。命令不会回显 credential、数据库路径、Package/plan digest、 Task spec 或业务参数。