chenmingxuan/EP-Hub-Skill

Fork 0

Files

T

chenmingxuan 0c8fa2653e first commit

2026-09-02 11:44:52 +08:00

15 KiB

Raw Permalink Blame History

workflow — 自动化工作流管理

创建 / 更新 / 启停 / 手动执行 / 查询执行历史 / 查看 / 列出 Base 下的自动化工作流（"当 X 时自动 Y" 流程）。适用场景：用户要求创建自动化、修改流程、停掉或恢复流程、立即执行流程、核对执行结果或查询已有流程。

命令一览

命令	用途
`workflow edit-example`	获取工作流编辑文档与 workflow-dsl/v1 示例
`workflow create`	创建并发布自动化工作流
`workflow update`	更新并发布已有自动化工作流
`workflow list`	列出 Base 下所有工作流（含状态/创建人/最后修改时间），支持分页
`workflow get`	获取单个工作流详情（含 flowSchema 完整节点定义）
`workflow enable`	启用指定工作流（按配置的触发条件自动执行）
`workflow disable`	禁用指定工作流（高危，建议 `--yes` 二次确认）
`workflow run`	立即执行指定工作流（会产生真实副作用，需确认）
`workflow history`	按状态、时间和分页条件查询工作流执行历史

workflow edit-example 无参数；其他子命令的 --base-id 必填（可用隐藏别名 --base）。

DSL 入参格式与最小 Demo

先运行 workflow edit-example 获取服务端提供的最新编辑文档和示例。workflow create/update 的 --dsl 接收钉钉 AI 表格 workflow-dsl/v1 JSON object。

复杂工作流还应注意：

使用 workflow edit-example 获取最新 DSL Guide、结构和示例。
涉及数据表、字段或视图的节点，先用 table get / field get / view list 确认真实 sheetId、fieldId、viewId。
create 和 update 都提交完整的 workflow-dsl/v1 JSON object，并检查所有 next、loopEntry、branch to 和 ref。

以下 Demo 表示“每天 09:00 触发，并向 Base 所有者发送消息”，不依赖数据表、字段或视图 ID：

{
  "version": "workflow-dsl/v1",
  "name": "每日提醒",
  "description": "可选说明",
  "trigger": "start",
  "steps": {
    "start": {
      "type": "Scheduled",
      "next": "send",
      "data": {
        "mode": "daily",
        "time": "09:00",
        "timezone": "GMT+08:00"
      }
    },
    "send": {
      "type": "SendMessage",
      "data": {
        "title": "定时任务已触发",
        "to": {
          "users": [{"ref": "$.system_node.ownerUserId"}]
        }
      }
    }
  }
}

将上述 JSON 保存为 workflow.json 后创建工作流：

dws aitable workflow create \
  --base-id BASE_ID \
  --dsl @workflow.json \
  --locale zh-CN \
  --format json

保存创建结果中的 data.flowId。更新时修改 workflow.json 中的完整目标定义，例如修改 name、description 或消息 title，然后调用：

dws aitable workflow update \
  --base-id BASE_ID \
  --workflow-id FLOW_ID \
  --dsl @workflow.json \
  --locale zh-CN \
  --format json

create 和 update 都必须同时满足 status=success、data.valid=true、data.issues=[] 才表示发布成功；update 返回的 data.flowId 应与传入的 FLOW_ID 一致。以上仅为最小 Demo，复杂节点的 type 和 data 结构以钉钉 AI 表格 MCP 最新 DSL 文档为准。

命令详情

workflow edit-example — 获取编辑文档与示例

dws aitable workflow edit-example --format json

该命令无业务参数，调用 aitable/edit_workflow_example 返回服务端提供的工作流编辑文档和示例。创建或更新复杂工作流前优先调用它，避免依赖可能过期的本地 DSL 结构。

workflow create — 创建并发布工作流

# 大 DSL 推荐从文件读取
dws aitable workflow create \
  --base-id BASE_ID \
  --dsl @workflow.json \
  --locale zh-CN \
  --format json

# 也支持 stdin
cat workflow.json | dws aitable workflow create --base-id BASE_ID --dsl - --format json

flag	必填	说明
`--base-id`	是	所属 Base ID
`--dsl`	是	workflow-dsl/v1 JSON object；支持内联 JSON、`@filepath`、`-` stdin
`--locale`	否	请求语言，如 `zh-CN` / `zh_CN`

创建成功返回发布结果：

{
  "status": "success",
  "data": {
    "valid": true,
    "flowId": "G-FLOW-XXXXXX",
    "flowSchema": {},
    "stepNodeIds": {},
    "referenceMap": {},
    "issues": []
  }
}

关键语义：

create 非幂等，CLI 不自动重试。若网络中断导致结果不确定，先 workflow list 按名称确认是否已创建，再决定是否重试。
status=success 只说明 workflow-edit 正常返回；如果 data.valid=false，仍表示 DSL 未通过校验或发布，必须读取 issues 修正。
创建并发布后，用 workflow list 确认 status；需要运行但状态为 STOP 时再调用 workflow enable。

workflow update — 更新并发布工作流

# 先留底现有详情，再提交完整目标 DSL
dws aitable workflow get --base-id BASE_ID --workflow-id WORKFLOW_ID --format json > /tmp/workflow-backup.json
dws aitable workflow update \
  --base-id BASE_ID \
  --workflow-id WORKFLOW_ID \
  --dsl @workflow.json \
  --locale zh_CN \
  --format json

flag	必填	说明
`--base-id`	是	所属 Base ID
`--workflow-id`	是	目标工作流 ID，对应 list 的 `flowId`
`--dsl`	是	完整目标 workflow-dsl/v1 JSON object；支持内联、`@filepath`、`-` stdin
`--locale`	否	请求语言，如 `zh-CN` / `zh_CN`

返回结构与 create 相同，成功时 flowId 应为目标工作流。update 使用 AI 表格瞬态错误重试；最终仍必须检查 data.valid 和 issues，并用 workflow get/list 验证发布结果与运行状态。

workflow run — 立即执行工作流

# 记录类触发器
dws aitable workflow run --base-id BASE_ID --workflow-id WORKFLOW_ID \
  --table-id TABLE_ID --record-ids RECORD_ID_1,RECORD_ID_2

# 定时触发器不传 table-id / record-ids
dws aitable workflow run --base-id BASE_ID --workflow-id WORKFLOW_ID

flag	必填	说明
`--base-id`	是	所属 Base ID
`--workflow-id`	是	目标工作流 ID
`--table-id`	条件必填	记录类触发器绑定的数据表；必须与触发器配置一致
`--record-ids`	条件必填	记录类触发器的记录 ID，1–5 个、逗号分隔且不可重复

run 启动真实异步执行，工作流中的发消息、写记录等动作会实际发生；执行前必须取得用户确认。返回项中的 executionId 是本次执行标识，可与 workflow history 项目的 instanceId 匹配。网络结果不确定时不要直接重复执行，先按该标识查询历史。

workflow history — 查询执行历史

dws aitable workflow history --base-id BASE_ID --workflow-id WORKFLOW_ID \
  --status failed --after-time 1786000000000 --before-time 1787000000000 \
  --page 0 --size 50

flag	说明
`--base-id`	必填
`--workflow-id`	必填；CLI 会映射为 MCP 的 `flowId`
`--status`	可选：`success` / `failed` / `running` / `break` / `untrigger`
`--after-time`	可选，Unix 毫秒开始时间
`--before-time`	可选，Unix 毫秒结束时间；与 after-time 同传时必须更大
`--page`	可选，从 0 开始，默认 0
`--size`	可选，默认 20，范围 `[1, 100]`

返回 totalCount 和 list。running 是非终态；success、failed、break、untrigger 是终态。

workflow list — 列出工作流

dws aitable workflow list --base-id BASE_ID --format json
dws aitable workflow list --base-id BASE_ID --limit 50 --offset 100

flag	说明
`--base-id`	必填
`--limit`	可选，分页大小 `[1, 100]`，不传走服务端默认 20
`--offset`	可选，分页偏移量 `>= 0`，不传走服务端默认 0

返回结构：

{
  "data": {
    "list": [
      {
        "flowId": "G-FLOW-XXXXXX",            // ★ 注意字段名是 flowId
        "name": "流程1",
        "description": "当创建记录时，就更新记录",
        "status": "RUNNING",                  // RUNNING / STOP
        "creatorStaffId": "281493",
        "lastModifier": { "name": "李普阳", "staffId": "281493" },
        "gmtModified": 1780318540000,
        "versionId": "G-FLOW-VER-XXXXXX",
        "icons": ["..."],                     // 触发器+动作的图标
        "isSubFlow": false,
        "opPermissions": { "canEdit": true }
      }
    ],
    "recordCount": 1,                         // Base 下总数
    "runningCount": 1                         // RUNNING 状态的数量
  }
}

注意：

标识字段服务端在 list 里叫 flowId，但在 enable / disable 出参里叫 workflowId。CLI --workflow-id 传任一即可（同值）。
status 是字符串枚举：RUNNING（启用中）/ STOP（已禁用），不是 boolean。
runningCount 是当前 Base 下 status=RUNNING 的工作流数，方便快速判断「有几个流程在跑」。

workflow get — 获取单个工作流详情

dws aitable workflow get --base-id BASE_ID --workflow-id WORKFLOW_ID --format json

flag	说明
`--base-id`	必填
`--workflow-id`	必填，对应 list 出参里的 `flowId`

返回完整工作流配置：

{
  "data": {
    "name": "流程1",
    "namespace": "...",
    "status": "RUNNING",
    "versionId": "G-FLOW-VER-XXXXXX",
    "versionNo": 14,
    "versionStatus": "...",
    "accessor": {...},                  // 访问者信息
    "corpId": "...",
    "flowAttribute": {...},             // 流程顶层属性
    "flowSchema": {...},                // ★ 流程节点定义（触发器/动作/分支等）
    "gmtCreate": 1780317804000,
    "gmtModified": 1780318540000
  }
}

flowSchema 是完整的节点 DAG，结构因流程而异（条件触发器 vs 定时触发器、单分支 vs 多分支等）。agent 应按需读取关心字段，不要试图建静态 schema。

workflow enable — 启用工作流

dws aitable workflow enable --base-id BASE_ID --workflow-id WORKFLOW_ID --format json

返回 {workflowId, enabled: true} —— enabled: true 是动作确认，不是当前状态查询。要确认真启用了，必须再 workflow list 看 status 是否变成 "RUNNING" 或 runningCount 是否加 1。

workflow disable — 禁用工作流（高危）

dws aitable workflow disable --base-id BASE_ID --workflow-id WORKFLOW_ID --yes --format json

返回 {workflowId, disabled: true} —— 同样是动作确认。禁用后该工作流不再自动触发。

风险：直接影响业务自动化（如停掉「记录创建后自动发通知」会让通知断流）。建议：

操作前先 workflow get 留底当前配置
脚本场景显式传 --yes；交互场景让用户在 prompt 中再次确认

能力边界

能力	状态
新建工作流	✅ 创建并发布
修改工作流配置	✅ 更新并发布
列出工作流	✅
看工作流详情（含 flowSchema）	✅
启用/禁用	✅
查看运行历史/执行日志	✅ `workflow history`
手动触发/单次运行	✅ `workflow run`（需确认）
删除工作流	❌ 暂未开放

错误码速查

场景	code	type	备注
create/update 返回 `valid=false`	—	success envelope	读取 `data.issues` 修正 DSL，不能当作发布成功
create 下游失败	`CREATE_WORKFLOW_ERROR`	`SYSTEM_ERROR`	create 不自动重试；先 list 排查是否已创建
update 下游失败	`UPDATE_WORKFLOW_ERROR`	`SYSTEM_ERROR`	update 会重试瞬态错误，最终失败时保留 DSL 和 workflowId 排查
`workflow-id` 不存在调 get	`GET_WORKFLOW_ERROR`	`SYSTEM_ERROR`	message 可能为 null，先 `workflow list` 核对 ID
`workflow-id` 不存在调 enable	`ENABLE_WORKFLOW_ERROR`	`SYSTEM_ERROR`	message 含 "场域中不存在该 namespace"
`workflow-id` 不存在调 disable	`DISABLE_WORKFLOW_ERROR`	`SYSTEM_ERROR`	同上
`--limit` < 1 或 > 100	（CLI 层拦截）	—	`--limit 必须在 [1, 100] 范围内，got N`
`--offset` < 0	（CLI 层拦截）	—	`--offset 必须 >= 0，got N`

拿到 *_WORKFLOW_ERROR / SYSTEM_ERROR 时，先 workflow list 自查目标 ID 是否还存在、是否在当前 Base 下。

典型工作流

创建并确认一个工作流

# 1. 按本文 DSL Demo 生成 /tmp/workflow.json
dws aitable workflow create --base-id BASE_ID --dsl @/tmp/workflow.json --locale zh-CN --format json \
  | tee /tmp/workflow-result.json

# 2. valid 必须为 true；保存 flowId
jq '{valid: .data.valid, flowId: .data.flowId, issues: .data.issues}' /tmp/workflow-result.json

# 3. 确认运行状态，需要时显式启用
FLOW_ID=$(jq -r '.data.flowId' /tmp/workflow-result.json)
dws aitable workflow list --base-id BASE_ID --format json \
  | jq --arg id "$FLOW_ID" '.data.list[] | select(.flowId == $id) | {flowId, name, status}'

看看 Base 里有哪些自动化在跑

dws aitable workflow list --base-id BASE_ID --format json | jq '.data | {total: .recordCount, running: .runningCount, items: .list | map({name, status, flowId})}'

临时停掉某个流程做调试

# 1. 留底当前状态
dws aitable workflow get --base-id BASE_ID --workflow-id WORKFLOW_ID --format json > /tmp/wf-backup.json

# 2. 禁用
dws aitable workflow disable --base-id BASE_ID --workflow-id WORKFLOW_ID --yes --format json

# 3. 调试做完后重启
dws aitable workflow enable --base-id BASE_ID --workflow-id WORKFLOW_ID --format json

# 4. 确认 status=RUNNING
dws aitable workflow list --base-id BASE_ID --format json | jq '.data.list[] | select(.flowId == "WORKFLOW_ID") | .status'

批量关掉某个 Base 下所有 workflow（调试 / 迁移前清场）

for WF in $(dws aitable workflow list --base-id BASE_ID --limit 100 --format json | jq -r '.data.list[] | select(.status == "RUNNING") | .flowId'); do
  dws aitable workflow disable --base-id BASE_ID --workflow-id "$WF" --yes --format json | jq .status
done

注意事项

--workflow-id 接受的就是 list 返回里的 flowId（同值，CLI 屏蔽了服务端字段名差异）。
create / update 的 --dsl 必须是 JSON object，不能传数组、字符串化的二次 JSON 或 FlowSchema。
本文 Demo 可直接用于最小定时消息工作流；复杂节点应以钉钉 AI 表格 MCP 最新 DSL 文档为准。
status=success 且 data.valid=false 仍是 DSL 校验失败；issues 才是下一步修复依据。
create 不自动重试；update 仅对网络/5xx/retryable:true 瞬态错误自动重试。
enable / disable 出参里的 enabled / disabled 是 动作确认 flag，不是当前状态字段。要确认真生效请走 workflow list 查 status。
workflow get 的 flowSchema 结构随触发器/动作类型变化，不要假设固定字段。
workflow run 不自动重试；结果不确定时用 workflow history 按 executionId / instanceId 核对。
删除工作流当前仍未开放。

15 KiB Raw Permalink Blame History Unescape Escape